ast-8.3.0/0000775000175000017500000000000013004147575007322 500000000000000ast-8.3.0/plot.h0000664000175000017500000015317613004147321010373 00000000000000#if !defined( PLOT_INCLUDED ) /* Include this file only once */ #define PLOT_INCLUDED /* *+ * Name: * plot.h * Type: * C include file. * Purpose: * Define the interface to the Plot class. * Invocation: * #include "plot.h" * Description: * This include file defines the interface to the Plot class and * provides the type definitions, function prototypes and macros, etc. * needed to use this class. * * The Plot class provides facilities for producing graphical information * describing positions within coordinate systems. These include the * creation of annotated coordinate axes, the plotting of markers at given * physical positions, etc. * Inheritance: * The Plot class inherits from the FrameSet class. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 18-SEP-1996 (DSB): * Original version. * 28-OCT-1998 (DSB): * Added method astPolyCurve. * 12-OCT-1999 (DSB): * Allow tick marks to be specified separately for both axes. * 9-JAN-2001 (DSB): * Change argument "in" for astMark and astPolyCurve from type * "const double (*)[]" to "const double *". * 13-JUN-2001 (DSB): * Added methods astGenCurve, astGrfSet, astGrfPop, astGrfPush and * attribute Grf. * 8-JAN-2003 (DSB): * Added protected astInitPlotVtab method. * 13-JAN-2004 (DSB): * Added bbox, logticks and logplot to the AstPlot structure. Added * LogPlot and LogTicks accessor methods. * 19-JAN-2004 (DSB): * Added loggap and loglabel to the AstPlot structure. Added * LogGap and LogLabel accessor methods. * 21-MAR-2005 (DSB): * - Added the Clip attribute. * 24-OCT-2006 (DSB): * - Remove duplicated documentation from prologue. * - Add ForceExterior attribute. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "frameset.h" /* Parent FrameSet class */ #include "keymap.h" #include "region.h" #if defined(astCLASS) /* Protected */ #include "grf.h" #endif /* C header files. */ /* --------------- */ #include /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__NPID 20 /* No. of different genuine plot object id's */ #define AST__GATTR 0 /* Identifiers for GRF functions */ #define AST__GFLUSH 1 /* Note, if any items are added or changed here, */ #define AST__GLINE 2 /* make sure that the astGrfFunID function is */ #define AST__GMARK 3 /* updated in plot.c */ #define AST__GTEXT 4 #define AST__GTXEXT 5 #define AST__GSCALES 6 #define AST__GQCH 7 #define AST__GCAP 8 #define AST__GBBUF 9 #define AST__GEBUF 10 #define AST__NGRFFUN 11 /* No. of Grf functions used by Plot */ #if defined(astCLASS) /* Protected */ #define AST__MXBRK 100 /* Max. no. of breaks in a drawn curve */ /* Identifiers for the graphical elements of an annotated coord grid. "Pseudo-elements" (i.e. values used to indicate a group of other genuine elements) should come at the end of the list. The number of genuine elements should be stored in AST__NPID. */ #define AST__BORDER_ID 0 /* Id for astBorder curves */ #define AST__CURVE_ID 1 /* Id for astCurve, astGenCurve or astPolyCurve curves */ #define AST__TITLE_ID 2 /* Id for textual title */ #define AST__MARKS_ID 3 /* Id for marks drawn by astMark */ #define AST__TEXT_ID 4 /* Id for text strings drawn by astText */ #define AST__AXIS1_ID 5 /* Id for axis 1 through interior tick marks */ #define AST__AXIS2_ID 6 /* Id for axis 2 through interior tick marks */ #define AST__AXIS3_ID 7 /* Id for axis 2 through interior tick marks */ #define AST__NUMLAB1_ID 8 /* Id for numerical labels */ #define AST__NUMLAB2_ID 9 /* Id for numerical labels */ #define AST__NUMLAB3_ID 10 /* Id for numerical labels */ #define AST__TEXTLAB1_ID 11 /* Id for textual axis labels */ #define AST__TEXTLAB2_ID 12 /* Id for textual axis labels */ #define AST__TEXTLAB3_ID 13 /* Id for textual axis labels */ #define AST__TICKS1_ID 14 /* Id for major and minor tick marks */ #define AST__TICKS2_ID 15 /* Id for major and minor tick marks */ #define AST__TICKS3_ID 16 /* Id for major and minor tick marks */ #define AST__GRIDLINE1_ID 17 /* Id for axis 1 astGridLine AST__curves */ #define AST__GRIDLINE2_ID 18 /* Id for axis 2 astGridLine AST__curves */ #define AST__GRIDLINE3_ID 19 /* Id for axis 2 astGridLine AST__curves */ #define AST__AXES_ID 20 /* Id for axes through interior tick marks */ #define AST__NUMLABS_ID 21 /* Id for numerical labels */ #define AST__TEXTLABS_ID 22 /* Id for textual axis labels */ #define AST__GRIDLINE_ID 23 /* Id for astGridLine AST__curves */ #define AST__TICKS_ID 24 /* Id for major and minor tick marks */ /* Define constants used to size global arrays in this module. */ #define AST__PLOT_CRV_MXBRK 1000 /* Max. no. of breaks allowed in a plotted curve */ #define AST__PLOT_STRIPESCAPES_BUFF_LEN 50 /* Length of string returned by astStripEscapes */ #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions */ /* ================ */ /* Pre-declare the AstPlot structure so that it can be used within the GRF function typedefs. */ struct AstPlot; /* Interfaces for GRF functions */ /* ---------------------------- */ /* A general interface into which actual Grf functions should be cast before being passed as an argument to astGrfSet. */ typedef void (* AstGrfFun)( void ); /* Interfaces for specific Grf funstions implemented in C (other languages may have different interfaces). */ typedef int (* AstGAttrFun)( AstKeyMap *, int, double, double *, int ); typedef int (* AstGFlushFun)( AstKeyMap * ); typedef int (* AstGBBufFun)( AstKeyMap * ); typedef int (* AstGEBufFun)( AstKeyMap * ); typedef int (* AstGLineFun)( AstKeyMap *, int, const float *, const float * ); typedef int (* AstGMarkFun)( AstKeyMap *, int, const float *, const float *, int ); typedef int (* AstGTextFun)( AstKeyMap *, const char *, float, float, const char *, float, float ); typedef int (* AstGCapFun)( AstKeyMap *, int, int ); typedef int (* AstGTxExtFun)( AstKeyMap *, const char *, float, float, const char *, float, float, float *, float * ); typedef int (* AstGScalesFun)( AstKeyMap *, float *, float * ); typedef int (* AstGQchFun)( AstKeyMap *, float *, float * ); /* A general interface into which Grf Wrapper functions should be cast before being passed as an argument to astGrfWrapper. */ typedef void (* AstGrfWrap)( void ); /* Interfaces for the wrapper functions which wrap specific Grf funstions. */ typedef int (* AstGAttrWrap)( struct AstPlot *, int, double, double *, int, int * ); typedef int (* AstGBBufWrap)( struct AstPlot *, int * ); typedef int (* AstGEBufWrap)( struct AstPlot *, int * ); typedef int (* AstGFlushWrap)( struct AstPlot *, int * ); typedef int (* AstGLineWrap)( struct AstPlot *, int, const float *, const float *, int * ); typedef int (* AstGMarkWrap)( struct AstPlot *, int, const float *, const float *, int, int * ); typedef int (* AstGTextWrap)( struct AstPlot *, const char *, float, float, const char *, float, float, int * ); typedef int (* AstGCapWrap)( struct AstPlot *, int, int, int * ); typedef int (* AstGTxExtWrap)( struct AstPlot *, const char *, float, float, const char *, float, float, float *, float *, int * ); typedef int (* AstGScalesWrap)( struct AstPlot *, float *, float *, int * ); typedef int (* AstGQchWrap)( struct AstPlot *, float *, float *, int * ); /* A structure in which a collection of Grf function pointers can be stored. */ typedef struct AstGrfPtrs { AstGrfFun grffun[AST__NGRFFUN]; AstGAttrWrap GAttr; AstGBBufWrap GBBuf; AstGEBufWrap GEBuf; AstGFlushWrap GFlush; AstGLineWrap GLine; AstGMarkWrap GMark; AstGTextWrap GText; AstGCapWrap GCap; AstGTxExtWrap GTxExt; AstGScalesWrap GScales; AstGQchWrap GQch; } AstGrfPtrs; /* Structure holding current graphical attribute values for text. */ typedef struct AstGat { float rise; double size; double width; double col; double font; double style; } AstGat; /* Plot structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPlot { /* Attributes inherited from the parent class. */ AstFrameSet parent; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *clip_lbnd; double *clip_ubnd; double centre[ 3 ]; double gap[ 3 ]; double loggap[ 3 ]; double labelat[ 3 ]; double majticklen[ 3 ]; double minticklen[ 3 ]; double numlabgap[ 3 ]; double size[ AST__NPID ]; double textlabgap[ 3 ]; double titlegap; double tol; double ucentre[ 3 ]; double ugap[ 3 ]; double uloggap[ 3 ]; double ulblat[ 3 ]; double umjtkln[ 3 ]; double width[ AST__NPID ]; double *majtickgx[ 3 ]; double *majtickgy[ 3 ]; double *mintickgx[ 3 ]; double *mintickgy[ 3 ]; int majtickcount[ 3 ]; int mintickcount[ 3 ]; int nmajtickval[ 3 ]; double *majtickval[ 3 ]; int nmintickval[ 3 ]; double *mintickval[ 3 ]; double xhi; double xlo; double yhi; double ylo; double bbox[ 4 ]; int border; int clip_axes; int clip_frame; int clip; int clipop; int colour[ AST__NPID ]; int drawaxes[ 3 ]; int abbrev[ 3 ]; int escape; int drawtitle; int edge[ 3 ]; int font[ AST__NPID ]; int grf; int grid; int invisible; int labelling; int labelunits[ 3 ]; int labelup[ 3 ]; int mintick[ 3 ]; int numlab[ 3 ]; int style[ AST__NPID ]; int textlab[ 3 ]; int tickall; int forceexterior; int uborder; int uedge[ 3 ]; int ugrid; int ulbling; int ulbunit[ 3 ]; int ulgtk[ 3 ]; int ulglb[ 3 ]; int umintk[ 3 ]; int utxtlb[ 3 ]; int xrev; int yrev; int ink; int logplot[ 3 ]; int logticks[ 3 ]; int loglabel[ 3 ]; AstGrfFun grffun[AST__NGRFFUN]; AstGAttrWrap GAttr; AstGBBufWrap GBBuf; AstGEBufWrap GEBuf; AstGFlushWrap GFlush; AstGLineWrap GLine; AstGMarkWrap GMark; AstGTextWrap GText; AstGCapWrap GCap; AstGTxExtWrap GTxExt; AstGScalesWrap GScales; AstGQchWrap GQch; AstGrfPtrs *grfstack; int grfnstack; AstGat **gat; int ngat; AstKeyMap *grfcontext; AstKeyMap *grfcontextID; float hmarkx; float hmarky; } AstPlot; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPlotVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameSetVtab FrameSet_vtab;/* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstKeyMap *(* GetGrfContext)( AstPlot *, int * ); AstPointSet *(* GetDrawnTicks)( AstPlot *, int, int, int * ); int (* Border)( AstPlot *, int * ); int (* CvBrk)( AstPlot *, int, double *, double *, double *, int * ); void (* BBuf)( AstPlot *, int * ); void (* BoundingBox)( AstPlot *, float[2], float[2], int * ); void (* Clip)( AstPlot *, int, const double [], const double [], int * ); void (* CopyPlotDefaults)( AstPlot *, int, AstPlot *, int, int * ); void (* Curve)( AstPlot *, const double [], const double [], int * ); void (* DrawExtraTicks)( AstPlot *, int, AstPointSet *, int * ); void (* EBuf)( AstPlot *, int * ); void (* GenCurve)( AstPlot *, AstMapping *, int * ); void (* GrfPop)( AstPlot *, int * ); void (* GrfPush)( AstPlot *, int * ); void (* GrfSet)( AstPlot *, const char *, AstGrfFun, int * ); void (* GrfWrapper)( AstPlot *, const char *, AstGrfWrap, int * ); void (* Grid)( AstPlot *, int * ); void (* GridLine)( AstPlot *, int, const double [], double, int * ); void (* Mark)( AstPlot *, int, int, int, const double *, int, int * ); void (* Mirror)( AstPlot *, int, int * ); void (* PolyCurve)( AstPlot *, int, int, int, const double *, int * ); void (* RegionOutline)( AstPlot *, AstRegion *, int * ); void (* SetTickValues)( AstPlot *, int, int, double *, int, double *, int * ); void (* Text)( AstPlot *, const char *, const double [], const float [], const char *, int * ); double (* GetTol)( AstPlot *, int * ); int (* TestTol)( AstPlot *, int * ); void (* SetTol)( AstPlot *, double, int * ); void (* ClearTol)( AstPlot *, int * ); int (* GetGrid)( AstPlot *, int * ); int (* TestGrid)( AstPlot *, int * ); void (* SetGrid)( AstPlot *, int, int * ); void (* ClearGrid)( AstPlot *, int * ); int (* GetTickAll)( AstPlot *, int * ); int (* TestTickAll)( AstPlot *, int * ); void (* SetTickAll)( AstPlot *, int, int * ); void (* ClearTickAll)( AstPlot *, int * ); int (* GetForceExterior)( AstPlot *, int * ); int (* TestForceExterior)( AstPlot *, int * ); void (* SetForceExterior)( AstPlot *, int, int * ); void (* ClearForceExterior)( AstPlot *, int * ); int (* GetInvisible)( AstPlot *, int * ); int (* TestInvisible)( AstPlot *, int * ); void (* SetInvisible)( AstPlot *, int, int * ); void (* ClearInvisible)( AstPlot *, int * ); int (* GetBorder)( AstPlot *, int * ); int (* TestBorder)( AstPlot *, int * ); void (* SetBorder)( AstPlot *, int, int * ); void (* ClearBorder)( AstPlot *, int * ); int (* GetClipOp)( AstPlot *, int * ); int (* TestClipOp)( AstPlot *, int * ); void (* SetClipOp)( AstPlot *, int, int * ); void (* ClearClipOp)( AstPlot *, int * ); int (* GetClip)( AstPlot *, int * ); int (* TestClip)( AstPlot *, int * ); void (* SetClip)( AstPlot *, int, int * ); void (* ClearClip)( AstPlot *, int * ); int (* GetGrf)( AstPlot *, int * ); int (* TestGrf)( AstPlot *, int * ); void (* SetGrf)( AstPlot *, int, int * ); void (* ClearGrf)( AstPlot *, int * ); int (* GetDrawTitle)( AstPlot *, int * ); int (* TestDrawTitle)( AstPlot *, int * ); void (* SetDrawTitle)( AstPlot *, int, int * ); void (* ClearDrawTitle)( AstPlot *, int * ); int (* GetLabelUp)( AstPlot *, int, int * ); int (* TestLabelUp)( AstPlot *, int, int * ); void (* SetLabelUp)( AstPlot *, int, int, int * ); void (* ClearLabelUp)( AstPlot *, int, int * ); int (* GetLogPlot)( AstPlot *, int, int * ); int (* TestLogPlot)( AstPlot *, int, int * ); void (* SetLogPlot)( AstPlot *, int, int, int * ); void (* ClearLogPlot)( AstPlot *, int, int * ); int (* GetLogTicks)( AstPlot *, int, int * ); int (* TestLogTicks)( AstPlot *, int, int * ); void (* SetLogTicks)( AstPlot *, int, int, int * ); void (* ClearLogTicks)( AstPlot *, int, int * ); int (* GetLogLabel)( AstPlot *, int, int * ); int (* TestLogLabel)( AstPlot *, int, int * ); void (* SetLogLabel)( AstPlot *, int, int, int * ); void (* ClearLogLabel)( AstPlot *, int, int * ); int (* GetDrawAxes)( AstPlot *, int, int * ); int (* TestDrawAxes)( AstPlot *, int, int * ); void (* SetDrawAxes)( AstPlot *, int, int, int * ); void (* ClearDrawAxes)( AstPlot *, int, int * ); int (* GetAbbrev)( AstPlot *, int, int * ); int (* TestAbbrev)( AstPlot *, int, int * ); void (* SetAbbrev)( AstPlot *, int, int, int * ); void (* ClearAbbrev)( AstPlot *, int, int * ); int (* GetEscape)( AstPlot *, int * ); int (* TestEscape)( AstPlot *, int * ); void (* SetEscape)( AstPlot *, int, int * ); void (* ClearEscape)( AstPlot *, int * ); int (* GetLabelling)( AstPlot *, int * ); int (* TestLabelling)( AstPlot *, int * ); void (* SetLabelling)( AstPlot *, int, int * ); void (* ClearLabelling)( AstPlot *, int * ); double (* GetMajTickLen)( AstPlot *, int, int * ); int (* TestMajTickLen)( AstPlot *, int, int * ); void (* SetMajTickLen)( AstPlot *, int, double, int * ); void (* ClearMajTickLen)( AstPlot *, int, int * ); double (* GetMinTickLen)( AstPlot *, int, int * ); int (* TestMinTickLen)( AstPlot *, int, int * ); void (* SetMinTickLen)( AstPlot *, int, double, int * ); void (* ClearMinTickLen)( AstPlot *, int, int * ); double (* GetNumLabGap)( AstPlot *, int, int * ); int (* TestNumLabGap)( AstPlot *, int, int * ); void (* SetNumLabGap)( AstPlot *, int, double, int * ); void (* ClearNumLabGap)( AstPlot *, int, int * ); double (* GetTextLabGap)( AstPlot *, int, int * ); int (* TestTextLabGap)( AstPlot *, int, int * ); void (* SetTextLabGap)( AstPlot *, int, double, int * ); void (* ClearTextLabGap)( AstPlot *, int, int * ); double (* GetTitleGap)( AstPlot *, int * ); int (* TestTitleGap)( AstPlot *, int * ); void (* SetTitleGap)( AstPlot *, double, int * ); void (* ClearTitleGap)( AstPlot *, int * ); double (* GetLabelAt)( AstPlot *, int, int * ); int (* TestLabelAt)( AstPlot *, int, int * ); void (* SetLabelAt)( AstPlot *, int, double, int * ); void (* ClearLabelAt)( AstPlot *, int, int * ); double (* GetGap)( AstPlot *, int, int * ); int (* TestGap)( AstPlot *, int, int * ); void (* SetGap)( AstPlot *, int, double, int * ); void (* ClearGap)( AstPlot *, int, int * ); double (* GetLogGap)( AstPlot *, int, int * ); int (* TestLogGap)( AstPlot *, int, int * ); void (* SetLogGap)( AstPlot *, int, double, int * ); void (* ClearLogGap)( AstPlot *, int, int * ); double (* GetCentre)( AstPlot *, int, int * ); int (* TestCentre)( AstPlot *, int, int * ); void (* SetCentre)( AstPlot *, int, double, int * ); void (* ClearCentre)( AstPlot *, int, int * ); int (* GetEdge)( AstPlot *, int, int * ); int (* TestEdge)( AstPlot *, int, int * ); void (* SetEdge)( AstPlot *, int, int, int * ); void (* ClearEdge)( AstPlot *, int, int * ); int (* GetNumLab)( AstPlot *, int, int * ); int (* TestNumLab)( AstPlot *, int, int * ); void (* SetNumLab)( AstPlot *, int, int, int * ); void (* ClearNumLab)( AstPlot *, int, int * ); int (* GetMinTick)( AstPlot *, int, int * ); int (* TestMinTick)( AstPlot *, int, int * ); void (* SetMinTick)( AstPlot *, int, int, int * ); void (* ClearMinTick)( AstPlot *, int, int * ); int (* GetTextLab)( AstPlot *, int, int * ); int (* TestTextLab)( AstPlot *, int, int * ); void (* SetTextLab)( AstPlot *, int, int, int * ); void (* ClearTextLab)( AstPlot *, int, int * ); int (* GetLabelUnits)( AstPlot *, int, int * ); int (* TestLabelUnits)( AstPlot *, int, int * ); void (* SetLabelUnits)( AstPlot *, int, int, int * ); void (* ClearLabelUnits)( AstPlot *, int, int * ); int (* GetStyle)( AstPlot *, int, int * ); int (* TestStyle)( AstPlot *, int, int * ); void (* SetStyle)( AstPlot *, int, int, int * ); void (* ClearStyle)( AstPlot *, int, int * ); int (* GetFont)( AstPlot *, int, int * ); int (* TestFont)( AstPlot *, int, int * ); void (* SetFont)( AstPlot *, int, int, int * ); void (* ClearFont)( AstPlot *, int, int * ); int (* GetColour)( AstPlot *, int, int * ); int (* TestColour)( AstPlot *, int, int * ); void (* SetColour)( AstPlot *, int, int, int * ); void (* ClearColour)( AstPlot *, int, int * ); double (* GetWidth)( AstPlot *, int, int * ); int (* TestWidth)( AstPlot *, int, int * ); void (* SetWidth)( AstPlot *, int, double, int * ); void (* ClearWidth)( AstPlot *, int, int * ); double (* GetSize)( AstPlot *, int, int * ); int (* TestSize)( AstPlot *, int, int * ); void (* SetSize)( AstPlot *, int, double, int * ); void (* ClearSize)( AstPlot *, int, int * ); int (* GetInk)( AstPlot *, int * ); int (* TestInk)( AstPlot *, int * ); void (* SetInk)( AstPlot *, int, int * ); void (* ClearInk)( AstPlot *, int * ); } AstPlotVtab; /* Structure holding information about curves drawn by astGridLine and astCurve. */ typedef struct AstPlotCurveData{ int out; /* Was the curve completely outside the clipping area? */ int nbrk; /* The number of breaks in the curve. */ float xbrk[ AST__PLOT_CRV_MXBRK ]; /* Graphics X coordinate at each break. */ float ybrk[ AST__PLOT_CRV_MXBRK ]; /* Graphics Y coordinate at each break. */ float vxbrk[ AST__PLOT_CRV_MXBRK ]; /* X comp. of unit tangent vector */ float vybrk[ AST__PLOT_CRV_MXBRK ]; /* Y comp. of unit tangent vector */ float length; /* Drawn length of the curve in graphics coordinates */ } AstPlotCurveData; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstPlotGlobals { AstPlotVtab Class_Vtab; int Class_Init; double GrfAttrs_attrs_t[ GRF__NATTR ]; int GrfAttrs_nesting_t; double Crv_limit_t; double Crv_scerr_t; double Crv_tol_t; double Crv_ux0_t; double Crv_uy0_t; double Crv_vxl_t; double Crv_vyl_t; double Crv_xhi_t; double Crv_xl_t; double Crv_xlo_t; double Crv_yhi_t; double Crv_yl_t; double Crv_ylo_t; float *Crv_vxbrk_t; float *Crv_vybrk_t; float *Crv_xbrk_t; float *Crv_ybrk_t; float Crv_len_t; int Crv_ink_t; int Crv_nbrk_t; int Crv_nent_t; int Crv_out_t; int Crv_clip_t; void (*Crv_map_t)( int, double *, double *, double *, const char *, const char *, int *, struct AstGlobals * ); void *Crv_mapstatics_t; float Box_lbnd_t[ 2 ]; float Box_ubnd_t[ 2 ]; float Boxp_lbnd_t[ 2 ]; float Boxp_ubnd_t[ 2 ]; int Boxp_freeze_t; float *Poly_x_t; float *Poly_y_t; int Poly_n_t; float **Poly_xp_t; float **Poly_yp_t; int *Poly_np_t; int Poly_npoly_t; int Map1_ncoord_t; AstPlot *Map1_plot_t; AstMapping *Map1_map_t; AstFrame *Map1_frame_t; const double *Map1_origin_t; double Map1_length_t; int Map1_axis_t; void *Map1_statics_t; int Map1_norm_t; int Map1_log_t; int Map2_ncoord_t; AstPlot *Map2_plot_t; AstMapping *Map2_map_t; double Map2_x0_t; double Map2_y0_t; double Map2_deltax_t; double Map2_deltay_t; void *Map2_statics_t; int Map3_ncoord_t; AstPlot *Map3_plot_t; AstMapping *Map3_map_t; AstFrame *Map3_frame_t; const double *Map3_origin_t; const double *Map3_end_t; double Map3_scale_t; void *Map3_statics_t; int Map4_ncoord_t; AstPlot *Map4_plot_t; AstMapping *Map4_map_t; AstMapping *Map4_umap_t; void *Map4_statics_t; int Map5_ncoord_t; AstPlot *Map5_plot_t; AstMapping *Map5_map_t; AstRegion *Map5_region_t; void *Map5_statics_t; AstPlotCurveData Curve_data_t; char GetAttrib_Buff[ 200 ]; char SplitValue_Buff[ 200 ]; char StripEscapes_Buff[ AST__PLOT_STRIPESCAPES_BUFF_LEN + 1 ]; double Grf_chv_t; double Grf_chh_t; float Grf_alpha_t; float Grf_beta_t; } AstPlotGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Plot) /* Check class membership */ astPROTO_ISA(Plot) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPlot *astPlot_( void *, const float *, const double *, const char *, int *, ...); #else AstPlot *astPlotId_( void *, const float [], const double [], const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPlot *astInitPlot_( void *, size_t, int, AstPlotVtab *, const char *, AstFrame *, const float *, const double *, int * ); /* Vtab initialiser. */ void astInitPlotVtab_( AstPlotVtab *, const char *, int * ); /* Loader. */ AstPlot *astLoadPlot_( void *, size_t, AstPlotVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitPlotGlobals_( AstPlotGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstKeyMap *astGetGrfContext_( AstPlot *, int * ); AstKeyMap *astGrfConID_( AstPlot *, int * ); const char *astStripEscapes_( const char *, int * ); int astBorder_( AstPlot *, int * ); int astFindEscape_( const char *, int *, int *, int *, int * ); void astBBuf_( AstPlot *, int * ); void astBoundingBox_( AstPlot *, float[2], float[2], int * ); void astClip_( AstPlot *, int, const double [], const double [], int * ); void astCurve_( AstPlot *, const double [], const double [], int * ); void astEBuf_( AstPlot *, int * ); void astGenCurve_( AstPlot *, AstMapping *, int * ); void astGrfPop_( AstPlot *, int * ); void astGrfPush_( AstPlot *, int * ); void astGrfSet_( AstPlot *, const char *, AstGrfFun, int * ); void astGridLine_( AstPlot *, int, const double [], double, int * ); void astGrid_( AstPlot *, int * ); void astMark_( AstPlot *, int, int, int, const double *, int, int * ); void astPolyCurve_( AstPlot *, int, int, int, const double *, int * ); void astRegionOutline_( AstPlot *, AstRegion *, int * ); void astText_( AstPlot *, const char *, const double [], const float [], const char *, int * ); void astGrfWrapper_( AstPlot *, const char *, AstGrfWrap, int * ); int astGrfFunID_( const char *, const char *, const char *, int * ); #if defined(astCLASS) /* Protected */ int astCvBrk_( AstPlot *, int, double *, double *, double *, int * ); void astCopyPlotDefaults_( AstPlot *, int, AstPlot *, int, int * ); void astMirror_( AstPlot *, int, int * ); AstPointSet *astGetDrawnTicks_( AstPlot *, int, int, int * ); void astSetTickValues_( AstPlot *, int, int, double *, int, double *, int * ); void astDrawExtraTicks_( AstPlot *, int, AstPointSet *, int * ); void astGrfAttrs_( AstPlot *, int, int, int, const char *, const char *, int * ); double astGetTol_( AstPlot *, int * ); int astTestTol_( AstPlot *, int * ); void astSetTol_( AstPlot *, double, int * ); void astClearTol_( AstPlot *, int * ); int astGetGrid_( AstPlot *, int * ); int astTestGrid_( AstPlot *, int * ); void astSetGrid_( AstPlot *, int, int * ); void astClearGrid_( AstPlot *, int * ); int astGetTickAll_( AstPlot *, int * ); int astTestTickAll_( AstPlot *, int * ); void astSetTickAll_( AstPlot *, int, int * ); void astClearTickAll_( AstPlot *, int * ); int astGetForceExterior_( AstPlot *, int * ); int astTestForceExterior_( AstPlot *, int * ); void astSetForceExterior_( AstPlot *, int, int * ); void astClearForceExterior_( AstPlot *, int * ); int astGetInvisible_( AstPlot *, int * ); int astTestInvisible_( AstPlot *, int * ); void astSetInvisible_( AstPlot *, int, int * ); void astClearInvisible_( AstPlot *, int * ); int astGetBorder_( AstPlot *, int * ); int astTestBorder_( AstPlot *, int * ); void astSetBorder_( AstPlot *, int, int * ); void astClearBorder_( AstPlot *, int * ); int astGetClip_( AstPlot *, int * ); int astTestClip_( AstPlot *, int * ); void astSetClip_( AstPlot *, int, int * ); void astClearClip_( AstPlot *, int * ); int astGetClipOp_( AstPlot *, int * ); int astTestClipOp_( AstPlot *, int * ); void astSetClipOp_( AstPlot *, int, int * ); void astClearClipOp_( AstPlot *, int * ); int astGetGrf_( AstPlot *, int * ); int astTestGrf_( AstPlot *, int * ); void astSetGrf_( AstPlot *, int, int * ); void astClearGrf_( AstPlot *, int * ); int astGetDrawTitle_( AstPlot *, int * ); int astTestDrawTitle_( AstPlot *, int * ); void astSetDrawTitle_( AstPlot *, int, int * ); void astClearDrawTitle_( AstPlot *, int * ); int astGetLabelUp_( AstPlot *, int, int * ); int astTestLabelUp_( AstPlot *, int, int * ); void astSetLabelUp_( AstPlot *, int, int, int * ); void astClearLabelUp_( AstPlot *, int, int * ); int astGetLogPlot_( AstPlot *, int, int * ); int astTestLogPlot_( AstPlot *, int, int * ); void astSetLogPlot_( AstPlot *, int, int, int * ); void astClearLogPlot_( AstPlot *, int, int * ); int astGetLogTicks_( AstPlot *, int, int * ); int astTestLogTicks_( AstPlot *, int, int * ); void astSetLogTicks_( AstPlot *, int, int, int * ); void astClearLogTicks_( AstPlot *, int, int * ); int astGetLogLabel_( AstPlot *, int, int * ); int astTestLogLabel_( AstPlot *, int, int * ); void astSetLogLabel_( AstPlot *, int, int, int * ); void astClearLogLabel_( AstPlot *, int, int * ); int astGetDrawAxes_( AstPlot *, int, int * ); int astTestDrawAxes_( AstPlot *, int, int * ); void astSetDrawAxes_( AstPlot *, int, int, int * ); void astClearDrawAxes_( AstPlot *, int, int * ); int astGetAbbrev_( AstPlot *, int, int * ); int astTestAbbrev_( AstPlot *, int, int * ); void astSetAbbrev_( AstPlot *, int, int, int * ); void astClearAbbrev_( AstPlot *, int, int * ); int astGetEscape_( AstPlot *, int * ); int astTestEscape_( AstPlot *, int * ); void astSetEscape_( AstPlot *, int, int * ); void astClearEscape_( AstPlot *, int * ); double astGetLabelAt_( AstPlot *, int, int * ); int astTestLabelAt_( AstPlot *, int, int * ); void astSetLabelAt_( AstPlot *, int, double, int * ); void astClearLabelAt_( AstPlot *, int, int * ); double astGetGap_( AstPlot *, int, int * ); int astTestGap_( AstPlot *, int, int * ); void astSetGap_( AstPlot *, int, double, int * ); void astClearGap_( AstPlot *, int, int * ); double astGetLogGap_( AstPlot *, int, int * ); int astTestLogGap_( AstPlot *, int, int * ); void astSetLogGap_( AstPlot *, int, double, int * ); void astClearLogGap_( AstPlot *, int, int * ); double astGetCentre_( AstPlot *, int, int * ); int astTestCentre_( AstPlot *, int, int * ); void astSetCentre_( AstPlot *, int, double, int * ); void astClearCentre_( AstPlot *, int, int * ); int astGetLabelling_( AstPlot *, int * ); int astTestLabelling_( AstPlot *, int * ); void astSetLabelling_( AstPlot *, int, int * ); void astClearLabelling_( AstPlot *, int * ); double astGetMajTickLen_( AstPlot *, int, int * ); int astTestMajTickLen_( AstPlot *, int, int * ); void astSetMajTickLen_( AstPlot *, int, double, int * ); void astClearMajTickLen_( AstPlot *, int, int * ); double astGetMinTickLen_( AstPlot *, int, int * ); int astTestMinTickLen_( AstPlot *, int, int * ); void astSetMinTickLen_( AstPlot *, int, double, int * ); void astClearMinTickLen_( AstPlot *, int, int * ); double astGetNumLabGap_( AstPlot *, int, int * ); int astTestNumLabGap_( AstPlot *, int, int * ); void astSetNumLabGap_( AstPlot *, int, double, int * ); void astClearNumLabGap_( AstPlot *, int, int * ); double astGetTextLabGap_( AstPlot *, int, int * ); int astTestTextLabGap_( AstPlot *, int, int * ); void astSetTextLabGap_( AstPlot *, int, double, int * ); void astClearTextLabGap_( AstPlot *, int, int * ); double astGetTitleGap_( AstPlot *, int * ); int astTestTitleGap_( AstPlot *, int * ); void astSetTitleGap_( AstPlot *, double, int * ); void astClearTitleGap_( AstPlot *, int * ); int astGetEdge_( AstPlot *, int, int * ); int astTestEdge_( AstPlot *, int, int * ); void astSetEdge_( AstPlot *, int, int, int * ); void astClearEdge_( AstPlot *, int, int * ); int astGetMinTick_( AstPlot *, int, int * ); int astTestMinTick_( AstPlot *, int, int * ); void astSetMinTick_( AstPlot *, int, int, int * ); void astClearMinTick_( AstPlot *, int, int * ); int astGetNumLab_( AstPlot *, int, int * ); int astTestNumLab_( AstPlot *, int, int * ); void astSetNumLab_( AstPlot *, int, int, int * ); void astClearNumLab_( AstPlot *, int, int * ); int astGetTextLab_( AstPlot *, int, int * ); int astTestTextLab_( AstPlot *, int, int * ); void astSetTextLab_( AstPlot *, int, int, int * ); void astClearTextLab_( AstPlot *, int, int * ); int astGetLabelUnits_( AstPlot *, int, int * ); int astTestLabelUnits_( AstPlot *, int, int * ); void astSetLabelUnits_( AstPlot *, int, int, int * ); void astClearLabelUnits_( AstPlot *, int, int * ); int astGetStyle_( AstPlot *, int, int * ); int astTestStyle_( AstPlot *, int, int * ); void astSetStyle_( AstPlot *, int, int, int * ); void astClearStyle_( AstPlot *, int, int * ); int astGetFont_( AstPlot *, int, int * ); int astTestFont_( AstPlot *, int, int * ); void astSetFont_( AstPlot *, int, int, int * ); void astClearFont_( AstPlot *, int, int * ); int astGetColour_( AstPlot *, int, int * ); int astTestColour_( AstPlot *, int, int * ); void astSetColour_( AstPlot *, int, int, int * ); void astClearColour_( AstPlot *, int, int * ); double astGetWidth_( AstPlot *, int, int * ); int astTestWidth_( AstPlot *, int, int * ); void astSetWidth_( AstPlot *, int, double, int * ); void astClearWidth_( AstPlot *, int, int * ); double astGetSize_( AstPlot *, int, int * ); int astTestSize_( AstPlot *, int, int * ); void astSetSize_( AstPlot *, int, double, int * ); void astClearSize_( AstPlot *, int, int * ); int astGetInk_( AstPlot *, int * ); int astTestInk_( AstPlot *, int * ); void astSetInk_( AstPlot *, int, int * ); void astClearInk_( AstPlot *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPlot(this) astINVOKE_CHECK(Plot,this,0) #define astVerifyPlot(this) astINVOKE_CHECK(Plot,this,1) /* Test class membership. */ #define astIsAPlot(this) astINVOKE_ISA(Plot,this) #if defined(astCLASS) /* Protected */ #define astPlot astINVOKE(F,astPlot_) #else #define astPlot astINVOKE(F,astPlotId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPlot(mem,size,init,vtab,name,frame,graph,base) \ astINVOKE(O,astInitPlot_(mem,size,init,vtab,name,frame,graph,base,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPlotVtab(vtab,name) astINVOKE(V,astInitPlotVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPlot(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPlot_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckPlot (et al.) to validate Plot pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #define astGetGrfContext(this) \ astINVOKE(O,astGetGrfContext_(astCheckPlot(this),STATUS_PTR)) #define astBorder(this) \ astINVOKE(V,astBorder_(astCheckPlot(this),STATUS_PTR)) #define astBoundingBox(this,lbnd,ubnd) \ astINVOKE(V,astBoundingBox_(astCheckPlot(this),lbnd,ubnd,STATUS_PTR)) #define astClip(this,iframe,lbnd,ubnd) \ astINVOKE(V,astClip_(astCheckPlot(this),iframe,lbnd,ubnd,STATUS_PTR)) #define astMark(this,nmark,ncoord,indim,in,type) \ astINVOKE(V,astMark_(astCheckPlot(this),nmark,ncoord,indim,in,type,STATUS_PTR)) #define astText(this,text,pos,up,just) \ astINVOKE(V,astText_(astCheckPlot(this),text,pos,up,just,STATUS_PTR)) #define astGrid(this) \ astINVOKE(V,astGrid_(astCheckPlot(this),STATUS_PTR)) #define astGridLine(this,axis,start,length) \ astINVOKE(V,astGridLine_(astCheckPlot(this),axis,start,length,STATUS_PTR)) #define astCurve(this,start,finish) \ astINVOKE(V,astCurve_(astCheckPlot(this),start,finish,STATUS_PTR)) #define astGenCurve(this,map) \ astINVOKE(V,astGenCurve_(astCheckPlot(this),astCheckMapping(map),STATUS_PTR)) #define astPolyCurve(this,npoint,ncoord,dim,in) \ astINVOKE(V,astPolyCurve_(astCheckPlot(this),npoint,ncoord,dim,in,STATUS_PTR)) #define astRegionOutline(this,region) \ astINVOKE(V,astRegionOutline_(astCheckPlot(this),astCheckRegion(region),STATUS_PTR)) #define astGrfSet(this,name,fun) \ astINVOKE(V,astGrfSet_(astCheckPlot(this),name,fun,STATUS_PTR)) #define astGrfPush(this) \ astINVOKE(V,astGrfPush_(astCheckPlot(this),STATUS_PTR)) #define astGrfPop(this) \ astINVOKE(V,astGrfPop_(astCheckPlot(this),STATUS_PTR)) #define astBBuf(this) \ astINVOKE(V,astBBuf_(astCheckPlot(this),STATUS_PTR)) #define astEBuf(this) \ astINVOKE(V,astEBuf_(astCheckPlot(this),STATUS_PTR)) #define astGrfFunID(name,method,class) astGrfFunID_(name,method,class,STATUS_PTR) #define astFindEscape(text,type,value,nc) astFindEscape_(text,type,value,nc,STATUS_PTR) #define astStripEscapes(text) astStripEscapes_(text,STATUS_PTR) #define astGrfConID(this) astGrfConID_(this,STATUS_PTR) #define astGrfWrapper(this,name,wrapper) \ astINVOKE(V,astGrfWrapper_(astCheckPlot(this),name,wrapper,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astGrfAttrs(this,id,set,prim,method,class) \ astGrfAttrs_(astCheckPlot(this),id,set,prim,method,class,STATUS_PTR) #define astCvBrk(this,ibrk,brk,vbrk,len) \ astINVOKE(V,astCvBrk_(astCheckPlot(this),ibrk,brk,vbrk,len,STATUS_PTR)) #define astCopyPlotDefaults(this,axis,dplot,daxis) \ astINVOKE(V,astCopyPlotDefaults_(astCheckPlot(this),axis,astCheckPlot(dplot),daxis,STATUS_PTR)) #define astMirror(this,axis) \ astINVOKE(V,astMirror_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetDrawnTicks(this,axis,major) \ astINVOKE(O,astGetDrawnTicks_(astCheckPlot(this),axis,major,STATUS_PTR)) #define astSetTickValues(this,axis,nmajor,major,nminor,minor) \ astINVOKE(V,astSetTickValues_(astCheckPlot(this),axis,nmajor,major,nminor,minor,STATUS_PTR)) #define astDrawExtraTicks(this,axis,pset) \ astINVOKE(V,astDrawExtraTicks_(astCheckPlot(this),axis,astCheckPointSet(pset),STATUS_PTR)) #define astClearTol(this) \ astINVOKE(V,astClearTol_(astCheckPlot(this),STATUS_PTR)) #define astGetTol(this) \ astINVOKE(V,astGetTol_(astCheckPlot(this),STATUS_PTR)) #define astSetTol(this,tol) \ astINVOKE(V,astSetTol_(astCheckPlot(this),tol,STATUS_PTR)) #define astTestTol(this) \ astINVOKE(V,astTestTol_(astCheckPlot(this),STATUS_PTR)) #define astClearGrid(this) \ astINVOKE(V,astClearGrid_(astCheckPlot(this),STATUS_PTR)) #define astGetGrid(this) \ astINVOKE(V,astGetGrid_(astCheckPlot(this),STATUS_PTR)) #define astSetGrid(this,grid) \ astINVOKE(V,astSetGrid_(astCheckPlot(this),grid,STATUS_PTR)) #define astTestGrid(this) \ astINVOKE(V,astTestGrid_(astCheckPlot(this),STATUS_PTR)) #define astClearInk(this) \ astINVOKE(V,astClearInk_(astCheckPlot(this),STATUS_PTR)) #define astGetInk(this) \ astINVOKE(V,astGetInk_(astCheckPlot(this),STATUS_PTR)) #define astSetInk(this,ink) \ astINVOKE(V,astSetInk_(astCheckPlot(this),ink,STATUS_PTR)) #define astTestInk(this) \ astINVOKE(V,astTestInk_(astCheckPlot(this),STATUS_PTR)) #define astClearTickAll(this) \ astINVOKE(V,astClearTickAll_(astCheckPlot(this),STATUS_PTR)) #define astGetTickAll(this) \ astINVOKE(V,astGetTickAll_(astCheckPlot(this),STATUS_PTR)) #define astSetTickAll(this,tickall) \ astINVOKE(V,astSetTickAll_(astCheckPlot(this),tickall,STATUS_PTR)) #define astTestTickAll(this) \ astINVOKE(V,astTestTickAll_(astCheckPlot(this),STATUS_PTR)) #define astClearForceExterior(this) \ astINVOKE(V,astClearForceExterior_(astCheckPlot(this),STATUS_PTR)) #define astGetForceExterior(this) \ astINVOKE(V,astGetForceExterior_(astCheckPlot(this),STATUS_PTR)) #define astSetForceExterior(this,frcext) \ astINVOKE(V,astSetForceExterior_(astCheckPlot(this),frcext,STATUS_PTR)) #define astTestForceExterior(this) \ astINVOKE(V,astTestForceExterior_(astCheckPlot(this),STATUS_PTR)) #define astClearBorder(this) \ astINVOKE(V,astClearBorder_(astCheckPlot(this),STATUS_PTR)) #define astGetBorder(this) \ astINVOKE(V,astGetBorder_(astCheckPlot(this),STATUS_PTR)) #define astSetBorder(this,border) \ astINVOKE(V,astSetBorder_(astCheckPlot(this),border,STATUS_PTR)) #define astTestBorder(this) \ astINVOKE(V,astTestBorder_(astCheckPlot(this),STATUS_PTR)) #define astClearClip(this) \ astINVOKE(V,astClearClip_(astCheckPlot(this),STATUS_PTR)) #define astGetClip(this) \ astINVOKE(V,astGetClip_(astCheckPlot(this),STATUS_PTR)) #define astSetClip(this,clip) \ astINVOKE(V,astSetClip_(astCheckPlot(this),clip,STATUS_PTR)) #define astTestClip(this) \ astINVOKE(V,astTestClip_(astCheckPlot(this),STATUS_PTR)) #define astClearClipOp(this) \ astINVOKE(V,astClearClipOp_(astCheckPlot(this),STATUS_PTR)) #define astGetClipOp(this) \ astINVOKE(V,astGetClipOp_(astCheckPlot(this),STATUS_PTR)) #define astSetClipOp(this,clipop) \ astINVOKE(V,astSetClipOp_(astCheckPlot(this),clipop,STATUS_PTR)) #define astTestClipOp(this) \ astINVOKE(V,astTestClipOp_(astCheckPlot(this),STATUS_PTR)) #define astClearInvisible(this) \ astINVOKE(V,astClearInvisible_(astCheckPlot(this),STATUS_PTR)) #define astGetInvisible(this) \ astINVOKE(V,astGetInvisible_(astCheckPlot(this),STATUS_PTR)) #define astSetInvisible(this,invisible) \ astINVOKE(V,astSetInvisible_(astCheckPlot(this),invisible,STATUS_PTR)) #define astTestInvisible(this) \ astINVOKE(V,astTestInvisible_(astCheckPlot(this),STATUS_PTR)) #define astClearGrf(this) \ astINVOKE(V,astClearGrf_(astCheckPlot(this),STATUS_PTR)) #define astGetGrf(this) \ astINVOKE(V,astGetGrf_(astCheckPlot(this),STATUS_PTR)) #define astSetGrf(this,grf) \ astINVOKE(V,astSetGrf_(astCheckPlot(this),grf,STATUS_PTR)) #define astTestGrf(this) \ astINVOKE(V,astTestGrf_(astCheckPlot(this),STATUS_PTR)) #define astClearDrawTitle(this) \ astINVOKE(V,astClearDrawTitle_(astCheckPlot(this),STATUS_PTR)) #define astGetDrawTitle(this) \ astINVOKE(V,astGetDrawTitle_(astCheckPlot(this),STATUS_PTR)) #define astSetDrawTitle(this,drawtitle) \ astINVOKE(V,astSetDrawTitle_(astCheckPlot(this),drawtitle,STATUS_PTR)) #define astTestDrawTitle(this) \ astINVOKE(V,astTestDrawTitle_(astCheckPlot(this),STATUS_PTR)) #define astClearDrawAxes(this,axis) \ astINVOKE(V,astClearDrawAxes_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetDrawAxes(this,axis) \ astINVOKE(V,astGetDrawAxes_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetDrawAxes(this,axis,drawaxes) \ astINVOKE(V,astSetDrawAxes_(astCheckPlot(this),axis,drawaxes,STATUS_PTR)) #define astTestDrawAxes(this,axis) \ astINVOKE(V,astTestDrawAxes_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearAbbrev(this,axis) \ astINVOKE(V,astClearAbbrev_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetAbbrev(this,axis) \ astINVOKE(V,astGetAbbrev_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetAbbrev(this,axis,abbrev) \ astINVOKE(V,astSetAbbrev_(astCheckPlot(this),axis,abbrev,STATUS_PTR)) #define astTestAbbrev(this,axis) \ astINVOKE(V,astTestAbbrev_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearEscape(this) \ astINVOKE(V,astClearEscape_(astCheckPlot(this),STATUS_PTR)) #define astGetEscape(this) \ astINVOKE(V,astGetEscape_(astCheckPlot(this),STATUS_PTR)) #define astSetEscape(this,escape) \ astINVOKE(V,astSetEscape_(astCheckPlot(this),escape,STATUS_PTR)) #define astTestEscape(this) \ astINVOKE(V,astTestEscape_(astCheckPlot(this),STATUS_PTR)) #define astClearLabelAt(this,axis) \ astINVOKE(V,astClearLabelAt_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLabelAt(this,axis) \ astINVOKE(V,astGetLabelAt_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLabelAt(this,axis,labelat) \ astINVOKE(V,astSetLabelAt_(astCheckPlot(this),axis,labelat,STATUS_PTR)) #define astTestLabelAt(this,axis) \ astINVOKE(V,astTestLabelAt_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearGap(this,axis) \ astINVOKE(V,astClearGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetGap(this,axis) \ astINVOKE(V,astGetGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetGap(this,axis,gap) \ astINVOKE(V,astSetGap_(astCheckPlot(this),axis,gap,STATUS_PTR)) #define astTestGap(this,axis) \ astINVOKE(V,astTestGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLogGap(this,axis) \ astINVOKE(V,astClearLogGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLogGap(this,axis) \ astINVOKE(V,astGetLogGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLogGap(this,axis,gap) \ astINVOKE(V,astSetLogGap_(astCheckPlot(this),axis,gap,STATUS_PTR)) #define astTestLogGap(this,axis) \ astINVOKE(V,astTestLogGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearCentre(this,axis) \ astINVOKE(V,astClearCentre_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetCentre(this,axis) \ astINVOKE(V,astGetCentre_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetCentre(this,axis,centre) \ astINVOKE(V,astSetCentre_(astCheckPlot(this),axis,centre,STATUS_PTR)) #define astTestCentre(this,axis) \ astINVOKE(V,astTestCentre_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearMajTickLen(this,axis) \ astINVOKE(V,astClearMajTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetMajTickLen(this,axis) \ astINVOKE(V,astGetMajTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetMajTickLen(this,axis,majticklen) \ astINVOKE(V,astSetMajTickLen_(astCheckPlot(this),axis,majticklen,STATUS_PTR)) #define astTestMajTickLen(this,axis) \ astINVOKE(V,astTestMajTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearMinTickLen(this,axis) \ astINVOKE(V,astClearMinTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetMinTickLen(this,axis) \ astINVOKE(V,astGetMinTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetMinTickLen(this,axis,minticklen) \ astINVOKE(V,astSetMinTickLen_(astCheckPlot(this),axis,minticklen,STATUS_PTR)) #define astTestMinTickLen(this,axis) \ astINVOKE(V,astTestMinTickLen_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearNumLabGap(this,axis) \ astINVOKE(V,astClearNumLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetNumLabGap(this,axis) \ astINVOKE(V,astGetNumLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetNumLabGap(this,axis,numlabgap) \ astINVOKE(V,astSetNumLabGap_(astCheckPlot(this),axis,numlabgap,STATUS_PTR)) #define astTestNumLabGap(this,axis) \ astINVOKE(V,astTestNumLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearTextLabGap(this,axis) \ astINVOKE(V,astClearTextLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetTextLabGap(this,axis) \ astINVOKE(V,astGetTextLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetTextLabGap(this,axis,textlabgap) \ astINVOKE(V,astSetTextLabGap_(astCheckPlot(this),axis,textlabgap,STATUS_PTR)) #define astTestTextLabGap(this,axis) \ astINVOKE(V,astTestTextLabGap_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearTitleGap(this) \ astINVOKE(V,astClearTitleGap_(astCheckPlot(this),STATUS_PTR)) #define astGetTitleGap(this) \ astINVOKE(V,astGetTitleGap_(astCheckPlot(this),STATUS_PTR)) #define astSetTitleGap(this,titlegap) \ astINVOKE(V,astSetTitleGap_(astCheckPlot(this),titlegap,STATUS_PTR)) #define astTestTitleGap(this) \ astINVOKE(V,astTestTitleGap_(astCheckPlot(this),STATUS_PTR)) #define astClearLabelling(this) \ astINVOKE(V,astClearLabelling_(astCheckPlot(this),STATUS_PTR)) #define astGetLabelling(this) \ astINVOKE(V,astGetLabelling_(astCheckPlot(this),STATUS_PTR)) #define astSetLabelling(this,labelling) \ astINVOKE(V,astSetLabelling_(astCheckPlot(this),labelling,STATUS_PTR)) #define astTestLabelling(this) \ astINVOKE(V,astTestLabelling_(astCheckPlot(this),STATUS_PTR)) #define astClearEdge(this,axis) \ astINVOKE(V,astClearEdge_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetEdge(this,axis) \ astINVOKE(V,astGetEdge_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetEdge(this,axis,edge) \ astINVOKE(V,astSetEdge_(astCheckPlot(this),axis,edge,STATUS_PTR)) #define astTestEdge(this,axis) \ astINVOKE(V,astTestEdge_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearMinTick(this,axis) \ astINVOKE(V,astClearMinTick_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetMinTick(this,axis) \ astINVOKE(V,astGetMinTick_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetMinTick(this,axis,mintick) \ astINVOKE(V,astSetMinTick_(astCheckPlot(this),axis,mintick,STATUS_PTR)) #define astTestMinTick(this,axis) \ astINVOKE(V,astTestMinTick_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearNumLab(this,axis) \ astINVOKE(V,astClearNumLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetNumLab(this,axis) \ astINVOKE(V,astGetNumLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetNumLab(this,axis,numlab) \ astINVOKE(V,astSetNumLab_(astCheckPlot(this),axis,numlab,STATUS_PTR)) #define astTestNumLab(this,axis) \ astINVOKE(V,astTestNumLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLabelUp(this,axis) \ astINVOKE(V,astClearLabelUp_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLabelUp(this,axis) \ astINVOKE(V,astGetLabelUp_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLabelUp(this,axis,labelup) \ astINVOKE(V,astSetLabelUp_(astCheckPlot(this),axis,labelup,STATUS_PTR)) #define astTestLabelUp(this,axis) \ astINVOKE(V,astTestLabelUp_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLogPlot(this,axis) \ astINVOKE(V,astClearLogPlot_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLogPlot(this,axis) \ astINVOKE(V,astGetLogPlot_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLogPlot(this,axis,logplot) \ astINVOKE(V,astSetLogPlot_(astCheckPlot(this),axis,logplot,STATUS_PTR)) #define astTestLogPlot(this,axis) \ astINVOKE(V,astTestLogPlot_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLogTicks(this,axis) \ astINVOKE(V,astClearLogTicks_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLogTicks(this,axis) \ astINVOKE(V,astGetLogTicks_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLogTicks(this,axis,logticks) \ astINVOKE(V,astSetLogTicks_(astCheckPlot(this),axis,logticks,STATUS_PTR)) #define astTestLogTicks(this,axis) \ astINVOKE(V,astTestLogTicks_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLogLabel(this,axis) \ astINVOKE(V,astClearLogLabel_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLogLabel(this,axis) \ astINVOKE(V,astGetLogLabel_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLogLabel(this,axis,loglabel) \ astINVOKE(V,astSetLogLabel_(astCheckPlot(this),axis,loglabel,STATUS_PTR)) #define astTestLogLabel(this,axis) \ astINVOKE(V,astTestLogLabel_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearTextLab(this,axis) \ astINVOKE(V,astClearTextLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetTextLab(this,axis) \ astINVOKE(V,astGetTextLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetTextLab(this,axis,textlab) \ astINVOKE(V,astSetTextLab_(astCheckPlot(this),axis,textlab,STATUS_PTR)) #define astTestTextLab(this,axis) \ astINVOKE(V,astTestTextLab_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearLabelUnits(this,axis) \ astINVOKE(V,astClearLabelUnits_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetLabelUnits(this,axis) \ astINVOKE(V,astGetLabelUnits_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetLabelUnits(this,axis,labelunits) \ astINVOKE(V,astSetLabelUnits_(astCheckPlot(this),axis,labelunits,STATUS_PTR)) #define astTestLabelUnits(this,axis) \ astINVOKE(V,astTestLabelUnits_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearStyle(this,axis) \ astINVOKE(V,astClearStyle_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetStyle(this,axis) \ astINVOKE(V,astGetStyle_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetStyle(this,axis,style) \ astINVOKE(V,astSetStyle_(astCheckPlot(this),axis,style,STATUS_PTR)) #define astTestStyle(this,axis) \ astINVOKE(V,astTestStyle_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearFont(this,axis) \ astINVOKE(V,astClearFont_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetFont(this,axis) \ astINVOKE(V,astGetFont_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetFont(this,axis,font) \ astINVOKE(V,astSetFont_(astCheckPlot(this),axis,font,STATUS_PTR)) #define astTestFont(this,axis) \ astINVOKE(V,astTestFont_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearColour(this,axis) \ astINVOKE(V,astClearColour_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetColour(this,axis) \ astINVOKE(V,astGetColour_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetColour(this,axis,colour) \ astINVOKE(V,astSetColour_(astCheckPlot(this),axis,colour,STATUS_PTR)) #define astTestColour(this,axis) \ astINVOKE(V,astTestColour_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearWidth(this,axis) \ astINVOKE(V,astClearWidth_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetWidth(this,axis) \ astINVOKE(V,astGetWidth_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetWidth(this,axis,width) \ astINVOKE(V,astSetWidth_(astCheckPlot(this),axis,width,STATUS_PTR)) #define astTestWidth(this,axis) \ astINVOKE(V,astTestWidth_(astCheckPlot(this),axis,STATUS_PTR)) #define astClearSize(this,axis) \ astINVOKE(V,astClearSize_(astCheckPlot(this),axis,STATUS_PTR)) #define astGetSize(this,axis) \ astINVOKE(V,astGetSize_(astCheckPlot(this),axis,STATUS_PTR)) #define astSetSize(this,axis,size) \ astINVOKE(V,astSetSize_(astCheckPlot(this),axis,size,STATUS_PTR)) #define astTestSize(this,axis) \ astINVOKE(V,astTestSize_(astCheckPlot(this),axis,STATUS_PTR)) #endif #endif ast-8.3.0/grf_2.0.c0000664000175000017500000000543213004147321010534 00000000000000/* * Name: * grf_2.0.c * Purpose: * Implement the grf module required by AST V2.0 if no graphics system * is available. * Description: * This file implements the low level graphics functions required * by the rest of AST V2.0, by reporting errors when called. * Inheritance: * This module is not a class and does not inherit. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-OCT-1996 (DSB): * Original version. * 13-NOV-1996 (DSB): * Modified to issue error messages using astError instead of printf. * 23-NOV-2004 (DSB): * Renamed from grf_null.c */ /* Header files */ /* ============ */ #include "grf.h" /* Declare the functions in this module */ #include "error.h" /* AST error reporting facilities */ #include "ast_err.h" /* AST error codes */ /* Function Prototypes */ /* =================== */ static void Report( const char * ); /* Function definitions */ /* ==================== */ int astGFlush( void ){ Report( "astGFlush"); return 0; } int astGLine( int n, const float *x, const float *y ){ Report( "astGLine" ); return 0; } int astGQch( float *chv, float *chh ){ Report( "astGQch" ); return 0; } int astGMark( int n, const float *x, const float *y, int type ){ Report( "astGMark" ); return 0; } int astGText( const char *text, float x, float y, const char *just, float upx, float upy ){ Report( "astGText" ); return 0; } int astGTxExt( const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb ){ Report( "astGTxExt" ); return 0; } int astGAttr( int attr, double value, double *old_value, int prim ){ Report( "astGAttr" ); return 0; } static void Report( const char *name ){ astError( AST__GRFER, "%s: No graphics facilities are available.", name ); astError( AST__GRFER, "Re-link using an option such as '-pgplot' with " "the ast_link script." ); } ast-8.3.0/frameset.h0000664000175000017500000006751113004147321011220 00000000000000/* *+ * Name: * frameset.h * Type: * C include file. * Purpose: * Define the interface to the FrameSet class. * Invocation: * #include "frameset.h" * Description: * This include file defines the interface to the FrameSet class and * provides the type definitions, function prototypes and macros, etc. * needed to use this class. * * A FrameSet consists of a set of one or more Frames, which are * inter-related by Mappings in such a way that it is possible to * obtain a Mapping between any pair of the Frames. The Frames are * identified by an integer index, with Frames being numbered * consecutively from one as they are added to the FrameSet. * * At any time, there is 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.). The other Frames represent alternative * coordinate systems which may be selected by making them current. * * When Frame methods are invoked on a FrameSet (e.g. to obtain a * Title value or to determine the number of axes), they are * applied to the current Frame. Thus, a FrameSet may be used in * place of its current Frame in most situations. * * When Mapping methods are invoked on a FrameSet, 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. A FrameSet may also be * inverted, which has the effect of interchanging its base and * current Frames (and hence of reversing the Mapping between * them). * * The FrameSet class also defines methods of its own, which are * used to manage the Frames and Mappings that it contains and to * convert between coordinate systems described by different * FrameSets. * Inheritance: * The FrameSet class inherits from the Frame class. * Attributes Over-Ridden: * Digits (integer) * Direction(axis) (integer) * Domain (string) * Format(axis) (string) * Label(axis) (string) * MatchEnd (integer) * MaxAxes (integer) * MinAxes (integer) * Naxes (integer) * Permute (integer) * PreserveAxes (integer) * Symbol(axis) (string) * Title (string) * Unit(axis) (string) * The FrameSet acquires all of these attributes from its * current Frame, so their meanings, values and defaults are * determined by this Frame and may change if a different * current Frame is selected. * Nin (integer) * Nout (integer) * TranForward (integer) * TranInverse (integer) * The FrameSet interprets all of these as applying to the * Mapping that converts coordinates between its base Frame and * its current Frame, so their values may change if a different * base or current Frame is selected. * Invert (integer) * Report (integer) * The FrameSet interprets these as applying to the Mapping that * converts coordinates between its base Frame and its current * Frame, but their values are not affected by selecing a * different base or current Frame. * New Attributes Defined: * Base (integer) * The (one-based) index of the Frame which is to be regarded as * the base Frame in the FrameSet. By default, this is the first * Frame added to the FrameSet (i.e. when it was created), * unless the Frameset has been inverted, in which case it is * the last Frame added. Inverting a FrameSet interchanges the * values of its Base and Current attributes. * Current (integer) * The (one-based) index of the Frame which is to be regarded as * the current Frame in the FrameSet. By default, this is the * last Frame added to the FrameSet, unless the Frameset has * been inverted, in which case it is the first Frame added * (i.e. when the FrameSet was created). Inverting a FrameSet * interchanges the values of its Base and Current attributes. * Nframe (integer) * A read-only value giving the number of Frames in a * FrameSet. This value will change as Frames are added or * removed. * Methods Over-Ridden: * Public: * astClear * Clear attribute values for a FrameSet. * astConvert * Determine how to convert between two coordinate systems. * astDistance * Calculate the distance between two points. * astFindFrame * Find a coordinate system with specified characteristics * astFormat * Format a coordinate value for a FrameSet axis. * astGetAxis * Obtain a pointer to a specified Axis from a FrameSet. * astGetNaxes * Determine how many axes a FrameSet has. * astGetNin * Get the number of input coordinates for a FrameSet. * astGetNout * Get the number of output coordinates for a FrameSet. * astNorm * Normalise a set of FrameSet coordinates. * astOffset * Calculate an offset along a geodesic curve. * astPermAxes * Permute the order of a FrameSet's axes. * astPickAxes * Create a new Frame by picking axes from a FrameSet. * astSetAxis * Set a new Axis for a FrameSet. * astSimplify * Simplify the Mappings in a FrameSet. * astTransform * Transform a set of points. * astUnformat * Read a formatted coordinate value for a FrameSet axis. * * Protected: * astAbbrev * Abbreviate a formatted FrameSet axis value by skipping leading * fields. * astClearDigits * Clear the value of the Digits attribute for a FrameSet. * astClearDirection * Clear the value of the Direction attribute for a FrameSet axis. * astClearDomain * Clear the value of the Domain attribute for a FrameSet. * astClearFormat * Clear the value of the Format attribute for a FrameSet axis. * astClearLabel * Clear the value of the Label attribute for a FrameSet axis. * astClearMatchEnd * Clear the value of the MatchEnd attribute for a FrameSet. * astClearMaxAxes * Clear the value of the MaxAxes attribute for a FrameSet. * astClearMinAxes * Clear the value of the MinAxes attribute for a FrameSet. * astClearPermute * Clear the value of the Permute attribute for a FrameSet. * astClearPreserveAxes * Clear the value of the PreserveAxes attribute for a FrameSet. * astClearSymbol * Clear the value of the Symbol attribute for a FrameSet axis. * astClearTitle * Clear the value of the Title attribute for a FrameSet. * astClearUnit * Clear the value of the Unit attribute for a FrameSet axis. * astConvertX * Determine how to convert between two coordinate systems. * astGap * Find a "nice" gap for tabulating FrameSet axis values. * astGetDigits * Get the value of the Digits attribute for a FrameSet. * astGetDirection * Get the value of the Direction attribute for a FrameSet axis. * astGetDomain * Get the value of the Domain attribute for a FrameSet. * astGetFormat * Get the value of the Format attribute for a FrameSet axis. * astGetLabel * Get the value of the Label attribute for a FrameSet axis. * astGetMatchEnd * Get the value of the MatchEnd attribute for a FrameSet. * astGetMaxAxes * Get the value of the MaxAxes attribute for a FrameSet. * astGetMinAxes * Get the value of the MinAxes attribute for a FrameSet. * astGetPerm * Access the axis permutation array for the current Frame of * a FrameSet. * astGetPermute * Get the value of the Permute attribute for a FrameSet. * astGetPreserveAxes * Get the value of the PreserveAxes attribute for a FrameSet. * astGetSymbol * Get the value of the Symbol attribute for a FrameSet axis. * astGetTitle * Get the value of the Title attribute for a FrameSet. * astGetTranForward * Determine if a Mapping can perform a "forward" coordinate * transformation. * astGetTranInverse * Determine if a Mapping can perform an "inverse" coordinate * transformation. * astGetUnit * Get the value of the Unit attribute for a FrameSet axis. * astMatch * Determine if conversion is possible between two coordinate systems. * astOverlay * Overlay the attributes of a template FrameSet on to another Frame. * astPrimaryFrame * Uniquely identify a primary Frame and one of its axes. * astReportPoints * Report the effect of transforming a set of points using a FrameSet. * astSetAttrib * Set an attribute value for a FrameSet. * astSetDigits * Set the value of the Digits attribute for a FrameSet. * astSetDirection * Set the value of the Direction attribute for a FrameSet axis. * astSetDomain * Set the value of the Domain attribute for a FrameSet. * astSetFormat * Set the value of the Format attribute for a FrameSet axis. * astSetLabel * Set the value of the Label attribute for a FrameSet axis. * astSetMatchEnd * Set the value of the MatchEnd attribute for a FrameSet. * astSetMaxAxes * Set the value of the MaxAxes attribute for a FrameSet. * astSetMinAxes * Set the value of the MinAxes attribute for a FrameSet. * astSetPermute * Set the value of the Permute attribute for a FrameSet. * astSetPreserveAxes * Set the value of the PreserveAxes attribute for a FrameSet. * astSetSymbol * Set the value of the Symbol attribute for a FrameSet axis. * astSetTitle * Set the value of the Title attribute for a FrameSet. * astSetUnit * Set the value of the Unit attribute for a FrameSet axis. * astSubFrame * Select axes from a FrameSet and convert to the new coordinate * system. * astTestDigits * Test if a value has been set for the Digits attribute of a * FrameSet. * astTestDirection * Test if a value has been set for the Direction attribute of a * FrameSet axis. * astTestDomain * Test if a value has been set for the Domain attribute of a * FrameSet. * astTestFormat * Test if a value has been set for the Format attribute of a * FrameSet axis. * astTestLabel * Test if a value has been set for the Label attribute of a * FrameSet axis. * astTestMatchEnd * Test if a value has been set for the MatchEnd attribute of a * FrameSet. * astTestMaxAxes * Test if a value has been set for the MaxAxes attribute of a * FrameSet. * astTestMinAxes * Test if a value has been set for the MinAxes attribute of a * FrameSet. * astTestPermute * Test if a value has been set for the Permute attribute of a * FrameSet. * astTestPreserveAxes * Test if a value has been set for the PreserveAxes attribute of a * FrameSet. * astTestSymbol * Test if a value has been set for the Symbol attribute of a * FrameSet axis. * astTestTitle * Test if a value has been set for the Title attribute of a FrameSet. * astTestUnit * Test if a value has been set for the Unit attribute of a FrameSet * axis. * astValidateAxis * Validate and permute a FrameSet's axis index. * astVSet * Set values for a FrameSet's attributes. * New Methods Defined: * Public: * astAddFrame * Add a Frame to a FrameSet to define a new coordinate system. * astGetFrame * Obtain a pointer to a specified Frame in a FrameSet. * astGetMapping * Obtain a Mapping between two Frames in a FrameSet. * astRemapFrame * Modify a Frame's relationshp to the other Frames in a FrameSet. * astRemoveFrame * Remove a Frame from a FrameSet. * * Protected: * astClearBase * Clear the value of the Base attribute for a FrameSet. * astClearCurrent * Clear the value of the Current attribute for a FrameSet. * astGetBase * Obtain the value of the Base attribute for a FrameSet. * astGetCurrent * Obtain the value of the Current attribute for a FrameSet. * astGetNframe * Determine the number of Frames in a FrameSet. * astSetBase * Set the value of the Base attribute for a FrameSet. * astSetCurrent * Set the value of the Current attribute for a FrameSet. * astTestBase * Test if a value has been set for the Base attribute of a FrameSet. * astTestCurrent * Test if a value has been set for the Current attribute of a * FrameSet. * astValidateFrameIndex * Validate a FrameSet Frame index number. * Other Class Functions: * Public: * astFrameSet * Create a FrameSet. * astIsAFrameSet * Test class membership. * * Protected: * astCheckFrameSet * Validate class membership. * astInitFrameSet * Initialise a FrameSet. * astInitFrameSetVtab * Initialise the virtual function table for the FrameSet class. * astLoadFrameSet * Load a FrameSet. * Macros: * None. * Type Definitions: * Public: * AstFrameSet * FrameSet object type. * Protected: * AstFrameSetVtab * FrameSet virtual function table type. * Macros: * Public: * AST__BASE * Expands to a constant int that may be used as a Frame index to * refer to a FrameSet's base Frame. * AST__CURRENT * Expands to a constant int that may be used as a Frame index to * refer to a FrameSet's current Frame. * AST__NOFRAME * Expands to a constant int that is guaranteed not to be valid when * used as a Frame index for a FrameSet. * * Protected: * None. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 16-FEB-1996 (RFWS): * Original version. * 5-JUN-1996 (RFWS): * Tidied up, etc. * 12-AUG-1996 (RFWS): * Added support for the public interface. * 25-SEP-1996 (RFWS): * Added I/O facilities. * 20-JAN-1998 (RFWS): * Implemented preservation of FrameSet integrity when attribute * values associated with the current Frame are modified. * 25-FEB-1998 (RFWS): * Over-ride the astUnformat method. * 8-JAN-2003 (DSB): * Added protected astInitFrameSetVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "frame.h" /* Parent Frame class */ /* Note that the usual setting of the FRAMESET_INCLUDED flag, which prevents this file being included more than once, must be deferred until after including the "frame.h" file. This is because "frame.h" needs to include the present interface definition (as a form of "forward reference") in order to have access to FrameSets itself. */ #if !defined( FRAMESET_INCLUDED ) #define FRAMESET_INCLUDED /* Macros. */ /* ======= */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__BASE (0) /* Identify base Frame */ #define AST__CURRENT (-1) /* Identify current Frame */ #define AST__NOFRAME (-99) /* An invalid Frame index */ #define AST__ALLFRAMES (-199) /* A value representing all Frames */ #define AST__FRAMESET_GETALLVARIANTS_BUFF_LEN 200 /* Length for AllVariants buffer */ #define AST__FRAMESET_GETATTRIB_BUFF_LEN 200 /* Length for GetAtribb buffer */ /* Type Definitions. */ /* ================= */ /* FrameSet structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstFrameSet { /* Attributes inherited from the parent class. */ AstFrame parent; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstFrame **frame; /* Array of Frame pointers */ AstMapping **map; /* Array of Mapping pointers */ int *varfrm; /* Array of variants Frames indices */ int *invert; /* Array of Mapping Invert values */ int *link; /* Parent node index for each node */ int *node; /* Index of node associated with Frame */ int base; /* Index of base Frame */ int current; /* Index of current Frame */ int nframe; /* Number of Frames */ int nnode; /* Number of nodes */ } AstFrameSet; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstFrameSetVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstFrame *(* GetFrame)( AstFrameSet *, int, int * ); AstMapping *(* GetMapping)( AstFrameSet *, int, int, int * ); int (* GetBase)( AstFrameSet *, int * ); int (* GetCurrent)( AstFrameSet *, int * ); int (* GetNframe)( AstFrameSet *, int * ); int (* TestBase)( AstFrameSet *, int * ); int (* TestCurrent)( AstFrameSet *, int * ); int (* ValidateFrameIndex)( AstFrameSet *, int, const char *, int * ); void (* AddFrame)( AstFrameSet *, int, AstMapping *, AstFrame *, int * ); void (* AddVariant)( AstFrameSet *, AstMapping *, const char *, int * ); void (* MirrorVariants)( AstFrameSet *, int, int * ); void (* ClearBase)( AstFrameSet *, int * ); void (* ClearCurrent)( AstFrameSet *, int * ); void (* RemapFrame)( AstFrameSet *, int, AstMapping *, int * ); void (* RemoveFrame)( AstFrameSet *, int, int * ); void (* SetBase)( AstFrameSet *, int, int * ); void (* SetCurrent)( AstFrameSet *, int, int * ); void (* ClearVariant)( AstFrameSet *, int * ); const char *(* GetVariant)( AstFrameSet *, int * ); void (* SetVariant)( AstFrameSet *, const char *, int * ); int (* TestVariant)( AstFrameSet *, int * ); const char *(* GetAllVariants)( AstFrameSet *, int * ); } AstFrameSetVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstFrameSetGlobals { AstFrameSetVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__FRAMESET_GETATTRIB_BUFF_LEN + 1 ]; char GetAllVariants_Buff[ AST__FRAMESET_GETALLVARIANTS_BUFF_LEN + 1 ]; AstFrame *Integrity_Frame; const char *Integrity_Method; int Integrity_Lost; } AstFrameSetGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(FrameSet) /* Check class membership */ astPROTO_ISA(FrameSet) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstFrameSet *astFrameSet_( void *, const char *, int *, ...); #else AstFrameSet *astFrameSetId_( void *, const char *, ... )__attribute__((format(printf,2,3))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstFrameSet *astInitFrameSet_( void *, size_t, int, AstFrameSetVtab *, const char *, AstFrame *, int * ); /* Vtab initialiser. */ void astInitFrameSetVtab_( AstFrameSetVtab *, const char *, int * ); /* Loader. */ AstFrameSet *astLoadFrameSet_( void *, size_t, AstFrameSetVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitFrameSetGlobals_( AstFrameSetGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstFrame *astGetFrame_( AstFrameSet *, int, int * ); AstMapping *astGetMapping_( AstFrameSet *, int, int, int * ); void astAddFrame_( AstFrameSet *, int , AstMapping *, AstFrame *, int * ); void astAddVariant_( AstFrameSet *, AstMapping *, const char *, int * ); void astMirrorVariants_( AstFrameSet *, int, int * ); void astRemapFrame_( AstFrameSet *, int, AstMapping *, int * ); void astRemoveFrame_( AstFrameSet *, int, int * ); #if defined(astCLASS) /* Protected */ const char *astGetAllVariants_( AstFrameSet *, int * ); int astGetBase_( AstFrameSet *, int * ); int astGetCurrent_( AstFrameSet *, int * ); int astGetNframe_( AstFrameSet *, int * ); int astTestBase_( AstFrameSet *, int * ); int astTestCurrent_( AstFrameSet *, int * ); int astValidateFrameIndex_( AstFrameSet *, int, const char *, int * ); void astClearBase_( AstFrameSet *, int * ); void astClearCurrent_( AstFrameSet *, int * ); void astSetBase_( AstFrameSet *, int, int * ); void astSetCurrent_( AstFrameSet *, int, int * ); void astClearVariant_( AstFrameSet *, int * ); const char *astGetVariant_( AstFrameSet *, int * ); void astSetVariant_( AstFrameSet *, const char *, int * ); int astTestVariant_( AstFrameSet *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckFrameSet(this) astINVOKE_CHECK(FrameSet,this,0) #define astVerifyFrameSet(this) astINVOKE_CHECK(FrameSet,this,1) /* Test class membership. */ #define astIsAFrameSet(this) astINVOKE_ISA(FrameSet,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astFrameSet astINVOKE(F,astFrameSet_) #else #define astFrameSet astINVOKE(F,astFrameSetId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitFrameSet(mem,size,init,vtab,name,frame) \ astINVOKE(O,astInitFrameSet_(mem,size,init,vtab,name,astCheckFrame(frame),STATUS_PTR)) /* Vtab Initialiser. */ #define astInitFrameSetVtab(vtab,name) astINVOKE(V,astInitFrameSetVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadFrameSet(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadFrameSet_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckFrameSet to validate FrameSet pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #define astAddFrame(this,iframe,map,frame) \ astINVOKE(V,astAddFrame_(astCheckFrameSet(this),iframe,(((iframe)!=AST__ALLFRAMES)?astCheckMapping(map):NULL),astCheckFrame(frame),STATUS_PTR)) #define astAddVariant(this,map,name) \ astINVOKE(V,astAddVariant_(astCheckFrameSet(this),map?astCheckMapping(map):NULL,name,STATUS_PTR)) #define astMirrorVariants(this,iframe) \ astINVOKE(V,astMirrorVariants_(astCheckFrameSet(this),iframe,STATUS_PTR)) #define astGetFrame(this,iframe) \ astINVOKE(O,astGetFrame_(astCheckFrameSet(this),iframe,STATUS_PTR)) #define astGetMapping(this,iframe1,iframe2) \ astINVOKE(O,astGetMapping_(astCheckFrameSet(this),iframe1,iframe2,STATUS_PTR)) #define astRemapFrame(this,iframe,map) \ astINVOKE(V,astRemapFrame_(astCheckFrameSet(this),iframe,astCheckMapping(map),STATUS_PTR)) #define astRemoveFrame(this,iframe) \ astINVOKE(V,astRemoveFrame_(astCheckFrameSet(this),iframe,STATUS_PTR)) /* Interfaces to protected member functions. */ /* ----------------------------------------- */ #if defined(astCLASS) /* Protected */ #define astClearBase(this) \ astINVOKE(V,astClearBase_(astCheckFrameSet(this),STATUS_PTR)) #define astClearCurrent(this) \ astINVOKE(V,astClearCurrent_(astCheckFrameSet(this),STATUS_PTR)) #define astGetBase(this) \ astINVOKE(V,astGetBase_(astCheckFrameSet(this),STATUS_PTR)) #define astGetCurrent(this) \ astINVOKE(V,astGetCurrent_(astCheckFrameSet(this),STATUS_PTR)) #define astGetNframe(this) \ astINVOKE(V,astGetNframe_(astCheckFrameSet(this),STATUS_PTR)) #define astSetBase(this,ibase) \ astINVOKE(V,astSetBase_(astCheckFrameSet(this),ibase,STATUS_PTR)) #define astSetCurrent(this,icurrent) \ astINVOKE(V,astSetCurrent_(astCheckFrameSet(this),icurrent,STATUS_PTR)) #define astTestBase(this) \ astINVOKE(V,astTestBase_(astCheckFrameSet(this),STATUS_PTR)) #define astTestCurrent(this) \ astINVOKE(V,astTestCurrent_(astCheckFrameSet(this),STATUS_PTR)) #define astValidateFrameIndex(this,iframe,method) \ astINVOKE(V,astValidateFrameIndex_(astCheckFrameSet(this),iframe,method,STATUS_PTR)) #define astClearVariant(this) \ astINVOKE(V,astClearVariant_(astCheckFrameSet(this),STATUS_PTR)) #define astGetVariant(this) \ astINVOKE(V,astGetVariant_(astCheckFrameSet(this),STATUS_PTR)) #define astSetVariant(this,variant) \ astINVOKE(V,astSetVariant_(astCheckFrameSet(this),variant,STATUS_PTR)) #define astTestVariant(this) \ astINVOKE(V,astTestVariant_(astCheckFrameSet(this),STATUS_PTR)) #define astGetAllVariants(this) \ astINVOKE(V,astGetAllVariants_(astCheckFrameSet(this),STATUS_PTR)) #endif #endif ast-8.3.0/cmpmap.c0000664000175000017500000053210513004147321010656 00000000000000/* *class++ * Name: * CmpMap * Purpose: * Compound Mapping. * Constructor Function: c astCmpMap f AST_CMPMAP * Description: * A CmpMap is a compound Mapping which allows two component * Mappings (of any class) to be connected together to form a more * complex Mapping. This connection may either be "in series" * (where the first Mapping is used to transform the coordinates of * each point and the second mapping is then applied to the * result), or "in parallel" (where one Mapping transforms the * earlier coordinates for each point and the second Mapping * simultaneously transforms the later coordinates). * * Since a CmpMap is itself a Mapping, it can be used as a * component in forming further CmpMaps. Mappings of arbitrary * complexity may be built from simple individual Mappings in this * way. * Inheritance: * The CmpMap class inherits from the Mapping class. * Attributes: * The CmpMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The CmpMap class does not define any new functions beyond those f The CmpMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 1-FEB-1996 (RFWS): * Original version. * 25-SEP-1996 (RFWS): * Implemented external interface and I/O facilities. * 12-DEC-1996 (RFWS): * Over-ride the astMapList method. * 13-DEC-1996 (RFWS): * Over-ride the astSimplify method. * 4-JUN-1997 (RFWS): * Eliminate any simplification when MapList is used. Instead, * over-ride the MapMerge method and implement all * simplification in this. * 24-MAR-1998 (RFWS): * Fixed bug in testing of simplified invert flag in Simplify. * 15-APR-1998 (RFWS): * Improved the MapMerge method to allow parallel combinations * of series CmpMaps to be replaced by series combinations of * parallel CmpMaps, and vice versa. * 26-SEP-2001 (DSB): * Over-ride the astDecompose method. * 8-JAN-2003 (DSB): * - Changed private InitVtab method to protected astInitCmpMapVtab * method. * 8-JAN-2003 (DSB): * - Modified MapMerge so that a parallel CmpMap can swap with a * suitable PermMap lower neighbour. * 23-APR-2004 (DSB): * - Modified Simplify to avoid infinite loops. * 27-APR-2004 (DSB): * - Correction to MapMerge to prevent segvio if CmpMap and PermMap * cannot be swapped. * 4-OCT-2004 (DSB): * Modify astMapList to return flag indicating presence of inverted * CmpMaps in supplied Mapping. * 20-APR-2005 (DSB): * Modify MapMerge so that it will attempt to merge the first * and second CmpMaps in a list of series CmpMaps. * 8-FEB-2006 (DSB): * Corrected logic within MapMerge for cases where a PermMap is * followed by a parallel CmpMap. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 14-MAR-2006 (DSB): * - When checking for patterns in the simplification process, * require at least 30 samples in the waveform for evidence of a * pattern. * - Override astEqual. * - The constructor no longer reports an error if the resulting * CmpMap cannot transform points in either direction. This is * because it may be possible to simplify such a CmpMap and the * simplified Mapping may have defined transformations. E.g. if a * Mapping which has only a forward transformation is combined in * series with its own inverse, the combination will simplify to a * UnitMap (usually). * 9-MAY-2006 (DSB): * - In Simplify, remove checks for patterns in the number of atomic * mappings when calling astSimplify recursively. * 23-AUG-2006 (DSB): * - In Simplify, add checks for re-appearance of a Mapping that is * already being simplified at a higher levelin the call stack. * 18-APR-2007 (DSB): * In Simplify: if the returned Mapping is not a CmpMap, always copy * the returned component Mapping (rather than cloning it) so that * the returned Mapping is not affected if user code subsequently * inverts the component Mapping via some other pointer. * 12-MAR-2008 (DSB): * Modify MapSplit so that attempts to split the inverse * transformation if it cannot split the forward transformation. * 30-JUL-2009 (DSB): * Ensure the PermMap has equal number of inputs and outputs when * swapping a PermMap and a CmpMap in astMapMerge. * 3-JAN-2011 (DSB): * In MapSplit, certain classes of Mapping (e.g. PermMaps) can * produce a returned Mapping with zero outputs. Consider such * Mappings to be unsplitable. * 11-JAN-2011 (DSB): * Improve simplification of serial combinations of parellel CmpMaps. * 25-JAN-2011 (DSB): * Big improvement to the efficiency of the astMapSplit method. * 24-JAN-2012 (DSB): * If efficient MapSplit fails to split (e.g. due to the presence * of PermMaps), then revert to the older slower method. * 5-FEB-2013 (DSB): * Take account of Invert flags when combining parallel CmpMaps in * series. * 29-APR-2013 (DSB): * In MapList, use the astDoNotSimplify method to check that it is * OK to expand the CmpMap. * 23-APR-2015 (DSB): * In Simplify, prevent mappings that are known to cause infinite * loops from being nominated for simplification. *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 CmpMap /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "permmap.h" /* Coordinate permutation Mappings */ #include "unitmap.h" /* Unit transformations */ #include "cmpmap.h" /* Interface definition for this class */ #include "frameset.h" /* Interface definition for FrameSets */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int (* parent_maplist)( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int *(* parent_mapsplit)( AstMapping *, int, const int *, AstMapping **, 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->Simplify_Depth = 0; \ globals->Simplify_Stackmaps = NULL; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(CmpMap) #define class_init astGLOBAL(CmpMap,Class_Init) #define class_vtab astGLOBAL(CmpMap,Class_Vtab) #define simplify_depth astGLOBAL(CmpMap,Simplify_Depth) #define simplify_stackmaps astGLOBAL(CmpMap,Simplify_Stackmaps) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static int simplify_depth = 0; static AstMapping **simplify_stackmaps = NULL; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstCmpMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstCmpMap *astCmpMapId_( void *, void *, int, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *CombineMaps( AstMapping *, int, AstMapping *, int, int, int * ); static AstMapping *RemoveRegions( AstMapping *, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); static int *MapSplit0( AstMapping *, int, const int *, AstMapping **, int, int * ); static int *MapSplit1( AstMapping *, int, const int *, AstMapping **, int * ); static int *MapSplit2( AstMapping *, int, const int *, AstMapping **, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetIsLinear( AstMapping *, int * ); static int MapList( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int PatternCheck( int, int, int **, int *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Decompose( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int GetObjSize( AstObject *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two CmpMaps are equivalent. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * CmpMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two CmpMaps are equivalent. * Parameters: * this * Pointer to the first Object (a CmpMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the CmpMaps are equivalent, zero otherwise. * 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: */ AstCmpMap *that; AstCmpMap *this; AstMapping **that_map_list; AstMapping **this_map_list; int *that_invert_list; int *this_invert_list; int i; int result; int that_inv; int that_nmap; int this_inv; int this_nmap; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two CmpMap structures. */ this = (AstCmpMap *) this_object; that = (AstCmpMap *) that_object; /* Check the second object is a CmpMap. We know the first is a CmpMap since we have arrived at this implementation of the virtual function. */ if( astIsACmpMap( that ) ) { /* Check they are both either parallel or series. */ if( that->series == that->series ) { /* Decompose the first CmpMap into a sequence of Mappings to be applied in series or parallel, as appropriate, and an associated list of Invert flags. */ this_nmap = 0; this_map_list = NULL; this_invert_list = NULL; astMapList( (AstMapping *) this, this->series, astGetInvert( this ), &this_nmap, &this_map_list, &this_invert_list ); /* Similarly decompose the second CmpMap. */ that_nmap = 0; that_map_list = NULL; that_invert_list = NULL; astMapList( (AstMapping *) that, that->series, astGetInvert( that ), &that_nmap, &that_map_list, &that_invert_list ); /* Check the decompositions yielded the same number of component Mappings. */ if( that_nmap == this_nmap ) { /* Check equality of every component. */ for( i = 0; i < this_nmap; i++ ) { /* Temporarily set the Mapping Invert flags to the required values, saving the original values so that they can be re-instated later.*/ this_inv = astGetInvert( this_map_list[ i ] ); astSetInvert( this_map_list[ i ], this_invert_list[ i ] ); that_inv = astGetInvert( that_map_list[ i ] ); astSetInvert( that_map_list[ i ], that_invert_list[ i ] ); /* Compare the two component Mappings for equality. */ result = astEqual( this_map_list[ i ], that_map_list[ i ] ); /* Re-instate the original Invert flags. */ astSetInvert( this_map_list[ i ], this_inv ); astSetInvert( that_map_list[ i ], that_inv ); /* Leave the loop if the Mappings are not equal. */ if( !result ) break; } } /* Free resources */ for( i = 0; i < this_nmap; i++ ) { this_map_list[ i ] = astAnnul( this_map_list[ i ] ); } this_map_list = astFree( this_map_list ); this_invert_list = astFree( this_invert_list ); for( i = 0; i < that_nmap; i++ ) { that_map_list[ i ] = astAnnul( that_map_list[ i ] ); } that_map_list = astFree( that_map_list ); that_invert_list = astFree( that_invert_list ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* 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 CmpMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * CmpMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is one if both component Mappings have a value of 1 * for the IsLinear attribute. * Parameters: * this * Pointer to the CmpqMap. * status * Pointer to the inherited status variable. */ AstCmpMap *this; this = (AstCmpMap *) this_mapping; return astGetIsLinear( this->map1 ) && astGetIsLinear( this->map2 ); } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * CmpMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied CmpMap, * in bytes. * Parameters: * this * Pointer to the CmpMap. * 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: */ AstCmpMap *this; /* Pointer to CmpMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the CmpMap structure. */ this = (AstCmpMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->map1 ); result += astGetObjSize( this->map2 ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } 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 "cmpmap.h" * AstMapping *CombineMaps( AstMapping *mapping1, int invert1, * AstMapping *mapping2, int invert2, * int series, int *status ) * Class Membership: * CmpMap 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). * status * Pointer to the inherited status variable. * 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 void Decompose( AstMapping *this_mapping, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { /* * * Name: * Decompose * Purpose: * Decompose a Mapping into two component Mappings. * Type: * Private function. * Synopsis: * #include "mapping.h" * void Decompose( AstMapping *this, AstMapping **map1, * AstMapping **map2, int *series, * int *invert1, int *invert2, int *status ) * Class Membership: * CmpMap member function (over-rides the protected astDecompose * method inherited from the Mapping class). * Description: * This function returns pointers to two Mappings which, when applied * either in series or parallel, are equivalent to the supplied Mapping. * * Since the Frame class inherits from the Mapping class, Frames can * be considered as special types of Mappings and so this method can * be used to decompose either CmpMaps or CmpFrames. * Parameters: * this * Pointer to the Mapping. * map1 * Address of a location to receive a pointer to first component * Mapping. * map2 * Address of a location to receive a pointer to second component * Mapping. * series * Address of a location to receive a value indicating if the * component Mappings are applied in series or parallel. A non-zero * value means that the supplied Mapping is equivalent to applying map1 * followed by map2 in series. A zero value means that the supplied * Mapping is equivalent to applying map1 to the lower numbered axes * and map2 to the higher numbered axes, in parallel. * invert1 * The value of the Invert attribute to be used with map1. * invert2 * The value of the Invert attribute to be used with map2. * status * Pointer to the inherited status variable. * Notes: * - Any changes made to the component Mappings using the returned * pointers will be reflected in the supplied Mapping. *- */ /* Local Variables: */ AstCmpMap *this; /* Pointer to CmpMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the CmpMap structure. */ this = (AstCmpMap *) this_mapping; /* First deal with series mappings. */ if( this->series ) { if( series ) *series = 1; /* If the CmpMap has been inverted, return the Mappings in reverse order with inverted Invert falgs. */ if( astGetInvert( this ) ) { if( map1 ) *map1 = astClone( this->map2 ); if( map2 ) *map2 = astClone( this->map1 ); if( invert1 ) *invert1 = this->invert2 ? 0 : 1; if( invert2 ) *invert2 = this->invert1 ? 0 : 1; /* If the CmpMap has not been inverted, return the Mappings in their original order with their original Invert flags. */ } else { if( map1 ) *map1 = astClone( this->map1 ); if( map2 ) *map2 = astClone( this->map2 ); if( invert1 ) *invert1 = this->invert1; if( invert2 ) *invert2 = this->invert2; } /* Now deal with parallel mappings. */ } else { if( series ) *series = 0; /* The mappings are returned in their original order whether or not the CmpMap has been inverted. */ if( map1 ) *map1 = astClone( this->map1 ); if( map2 ) *map2 = astClone( this->map2 ); /* If the CmpMap has been inverted, return inverted Invert flags. */ if( astGetInvert( this ) ) { if( invert1 ) *invert1 = this->invert1 ? 0 : 1; if( invert2 ) *invert2 = this->invert2 ? 0 : 1; /* If the CmpMap has not been inverted, return the original Invert flags. */ } else { if( invert1 ) *invert1 = this->invert1; if( invert2 ) *invert2 = this->invert2; } } } void astInitCmpMapVtab_( AstCmpMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitCmpMapVtab * Purpose: * Initialise a virtual function table for a CmpMap. * Type: * Protected function. * Synopsis: * #include "cmpmap.h" * void astInitCmpMapVtab( AstCmpMapVtab *vtab, const char *name ) * Class Membership: * CmpMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the CmpMap 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 */ 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. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsACmpMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_maplist = mapping->MapList; mapping->MapList = MapList; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_mapsplit = mapping->MapSplit; mapping->MapSplit = MapSplit; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->Decompose = Decompose; mapping->MapMerge = MapMerge; mapping->Simplify = Simplify; mapping->RemoveRegions = RemoveRegions; mapping->GetIsLinear = GetIsLinear; /* For some reason the CmpMap implementation of astRate can be immensely slow for complex Mapping, so it's currently disable until such time as I have time to sort it out. mapping->Rate = Rate; */ /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "CmpMap", "Compound Mapping" ); /* 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) ); } } #if defined(THREAD_SAFE) static int ManageLock( AstObject *this_object, int mode, int extra, AstObject **fail, int *status ) { /* * Name: * ManageLock * Purpose: * Manage the thread lock on an Object. * Type: * Private function. * Synopsis: * #include "object.h" * AstObject *ManageLock( AstObject *this, int mode, int extra, * AstObject **fail, int *status ) * Class Membership: * CmpMap member function (over-rides the astManageLock protected * method inherited from the parent class). * Description: * This function manages the thread lock on the supplied Object. The * lock can be locked, unlocked or checked by this function as * deteremined by parameter "mode". See astLock for details of the way * these locks are used. * Parameters: * this * Pointer to the Object. * mode * An integer flag indicating what the function should do: * * AST__LOCK: Lock the Object for exclusive use by the calling * thread. The "extra" value indicates what should be done if the * Object is already locked (wait or report an error - see astLock). * * AST__UNLOCK: Unlock the Object for use by other threads. * * AST__CHECKLOCK: Check that the object is locked for use by the * calling thread (report an error if not). * extra * Extra mode-specific information. * fail * If a non-zero function value is returned, a pointer to the * Object that caused the failure is returned at "*fail". This may * be "this" or it may be an Object contained within "this". Note, * the Object's reference count is not incremented, and so the * returned pointer should not be annulled. A NULL pointer is * returned if this function returns a value of zero. * status * Pointer to the inherited status variable. * Returned Value: * A local status value: * 0 - Success * 1 - Could not lock or unlock the object because it was already * locked by another thread. * 2 - Failed to lock a POSIX mutex * 3 - Failed to unlock a POSIX mutex * 4 - Bad "mode" value supplied. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ AstCmpMap *this; /* Pointer to CmpMap structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the CmpMap structure. */ this = (AstCmpMap *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->map1, mode, extra, fail ); if( !result ) result = astManageLock( this->map2, mode, extra, fail ); return result; } #endif static int MapList( AstMapping *this_mapping, int series, int invert, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapList * Purpose: * Decompose a CmpMap into a sequence of simpler Mappings. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapList( AstMapping *this, int series, int invert, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * CmpMap member function (over-rides the protected astMapList * method inherited from the Maping class). * Description: * This function decomposes a CmpMap into a sequence of simpler * Mappings which may be applied in sequence to achieve the same * effect. The CmpMap is decomposed as far as possible, but it is * not guaranteed that this will necessarily yield any more than * one Mapping, which may actually be the original CmpMap supplied. * * This function is provided to support both the simplification of * CmpMaps, and the analysis of CmpMap structure so that particular * forms can be recognised. * Parameters: * this * Pointer to the CmpMap to be decomposed (the CmpMap is not * actually modified by this function). * series * If this value is non-zero, an attempt will be made to * decompose the CmpMap into a sequence of equivalent Mappings * which can be applied in series (i.e. one after the other). If * it is zero, the decomposition will instead yield Mappings * which can be applied in parallel (i.e. on successive sub-sets * of the input/output coordinates). * invert * The value to which the CmpMap's Invert attribute is to be * (notionally) set before performing the * decomposition. Normally, the value supplied here will be the * actual Invert value obtained from the CmpMap (e.g. using * astGetInvert). Sometimes, however, when a CmpMap is * encapsulated within another structure, that structure may * retain an Invert value (in order to prevent external * interference) which should be used instead. * * Note that the actual Invert value of the CmpMap supplied is * not used (or modified) by this function. * nmap * The address of an int which holds a count of the number of * individual Mappings in the decomposition. On entry, this * should count the number of Mappings already in the * "*map_list" array (below). On exit, it is updated to include * any new Mappings appended by this function. * map_list * Address of a pointer to an array of Mapping pointers. On * entry, this array pointer should either be NULL (if no * Mappings have yet been obtained) or should point at a * dynamically allocated array containing Mapping pointers * ("*nmap" in number) which have been obtained from a previous * invocation of this function. * * On exit, the dynamic array will be enlarged to contain any * new Mapping pointers that result from the decomposition * requested. These pointers will be appended to any previously * present, and the array pointer will be updated as necessary * to refer to the enlarged array (any space released by the * original array will be freed automatically). * * The new Mapping pointers returned will identify a sequence of * Mappings which, when applied in order, will perform a forward * transformation equivalent to that of the original CmpMap * (after its Invert flag has first been set to the value * requested above). The Mappings should be applied in series or * in parallel according to the type of decomposition requested. * * All the Mapping pointers returned by this function should be * annulled by the caller, using astAnnul, when no longer * required. The dynamic array holding these pointers should * also be freed, using astFree. * invert_list * Address of a pointer to an array of int. On entry, this array * pointer should either be NULL (if no Mappings have yet been * obtained) or should point at a dynamically allocated array * containing Invert attribute values ("*nmap" in number) which * have been obtained from a previous invocation of this * function. * * On exit, the dynamic array will be enlarged to contain any * new Invert attribute values that result from the * decomposition requested. These values will be appended to any * previously present, and the array pointer will be updated as * necessary to refer to the enlarged array (any space released * by the original array will be freed automatically). * * The new Invert values returned identify the values which must * be assigned to the Invert attributes of the corresponding * Mappings (whose pointers are in the "*map_list" array) before * they are applied. Note that these values may differ from the * actual Invert attribute values of these Mappings, which are * not relevant. * * The dynamic array holding these values should be freed by the * caller, using astFree, when no longer required. * Returned Value: * A non-zero value is returned if the supplied Mapping contained any * inverted CmpMaps. * Notes: * - It is unspecified to what extent the original CmpMap and the * individual (decomposed) Mappings are * inter-dependent. Consequently, the individual Mappings cannot be * modified without risking modification of the original CmpMap. * - If this function is invoked with the global error status set, * or if it should fail for any reason, then the *nmap value, the * list of Mapping pointers and the list of Invert values will all * be returned unchanged. */ /* Local Variables: */ AstCmpMap *this; /* Pointer to CmpMap structure */ int invert1; /* Invert flag for first component Mapping */ int invert2; /* Invert flag for second component Mapping */ int r1; /* Value returned from first map list */ int r2; /* Value returned from second map list */ int result; /* Returned value */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the CmpMap structure. */ this = (AstCmpMap *) this_mapping; /* Check if the CmpMap combines its component Mappings in the same way (series or parallel) as the decomposition requires. Also, do not expand CmpMaps that are not appropriate for simplification. */ if ( this->series == series && !astDoNotSimplify( this ) ) { /* If so, obtain the Invert attribute values to be applied to each component Mapping. */ invert1 = this->invert1; invert2 = this->invert2; /* If the CmpMap itself is inverted, also invert the Invert values to be applied to its components. */ if ( invert ) { invert1 = !invert1; invert2 = !invert2; } /* If the component Mappings are applied in series, then concatenate the Mapping lists obtained from each of them. Do this in reverse order if the CmpMap is inverted, since the second Mapping would be applied first in this case. */ if ( series ) { if ( !invert ) { r1 = astMapList( this->map1, series, invert1, nmap, map_list, invert_list ); r2 = astMapList( this->map2, series, invert2, nmap, map_list, invert_list ); } else { r1 = astMapList( this->map2, series, invert2, nmap, map_list, invert_list ); r2 = astMapList( this->map1, series, invert1, nmap, map_list, invert_list ); } /* If the component Mappings are applied in parallel, then concatenate the Mapping lists obtained from each of them. In this case, inverting the CmpMap has no effect on the order in which they are applied. */ } else { r1 = astMapList( this->map1, series, invert1, nmap, map_list, invert_list ); r2 = astMapList( this->map2, series, invert2, nmap, map_list, invert_list ); } /* Did we find any inverted CmpMaps? */ result = invert || r1 || r2; /* If the CmpMap does not combine its components in the way required by the decomposition (series or parallel), then we cannot decompose it. In this case it must be appended to the Mapping list as a single entity. We can use the parent class method to do this. */ } else { result = ( *parent_maplist )( this_mapping, series, invert, nmap, map_list, invert_list, status ); } return result; } static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a CmpMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * CmpMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated CmpMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated CmpMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated CmpMap which is to be merged with * its neighbours. This should be a cloned copy of the CmpMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * CmpMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated CmpMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstCmpMap *cmpmap1; /* Pointer to first CmpMap */ AstCmpMap *cmpmap2; /* Pointer to second CmpMap */ AstCmpMap *cmpmap; /* Pointer to nominated CmpMap */ AstCmpMap *new_cm; /* Pointer to new CmpMap */ AstMapping **map_list1; /* Pointer to list of cmpmap1 component Mappings */ AstMapping **map_list2; /* Pointer to list of cmpmap2 component Mappings */ AstMapping **new_map_list; /* Extended Mapping list */ AstMapping *map; /* Pointer to nominated CmpMap */ AstMapping *new1; /* Pointer to new CmpMap */ AstMapping *new2; /* Pointer to new CmpMap */ AstMapping *new; /* Pointer to replacement Mapping */ AstMapping *simp1; /* Pointer to simplified Mapping */ AstMapping *simp2; /* Pointer to simplified Mapping */ AstMapping *submap1; /* A subset of mappings from cmpmap1 */ AstMapping *submap2; /* A subset of mappings from cmpmap2 */ AstMapping *tmap2; /* Temporary Mapping */ AstMapping *tmap; /* Temporary Mapping */ AstPermMap *new_pm; /* Pointer to new PermMap */ AstPermMap *permmap1; /* Pointer to first PermMap */ AstUnitMap *unit; /* UnitMap that feeds const PermMap i/p's */ const char *class; /* Pointer to Mapping class string */ double *conperm; /* Pointer to PermMap constants array */ double *const_new; /* Pointer to new PermMap constants array */ double *p; /* Pointer to PermMap input position */ double *q; /* Pointer to PermMap output position */ double *qa; /* Pointer to 1st component output position */ double *qb; /* Pointer to 2nd component output position */ int *inperm; /* Pointer to copy of PermMap inperm array */ int *inperm_new; /* Pointer to new PermMap inperm array */ int *invert_list1; /* Pointer to list of cmpmap1 invert values */ int *invert_list2; /* Pointer to list of cmpmap2 invert values */ int *new_invert_list; /* Extended Invert flag list */ int *outperm; /* Pointer to copy of PermMap outperm array */ int *outperm_new; /* Pointer to new PermMap outperm array */ int aconstants; /* Are all 1st component outputs constant? */ int bconstants; /* Are all 2nd component outputs constant? */ int canswap; /* Can nominated Mapping swap with lower neighbour? */ int i; /* Coordinate index */ int iconid; /* Constant identifier in supplied PermMap */ int imap1; /* Index of first Mapping */ int imap2; /* Index of second Mapping */ int imap; /* Loop counter for Mappings */ int invert1; /* Invert flag for first CmpMap */ int invert1a; /* Invert flag for sub-Mapping */ int invert1b; /* Invert flag for sub-Mapping */ int invert2; /* Invert flag for second CmpMap */ int invert2a; /* Invert flag for sub-Mapping */ int invert2b; /* Invert flag for sub-Mapping */ int invert; /* Invert attribute value */ int j; /* Coordinate index */ int jmap1; /* Index of next component Mapping in cmpmap1 */ int jmap2; /* Index of next component Mapping in cmpmap2 */ int new_invert; /* New Invert attribute value */ int nin2a; /* No. input coordinates for sub-Mapping */ int nin2b; /* No. input coordinates for sub-Mapping */ int nmap1; /* Number of Mappings in cmpmap1 */ int nmap2; /* Number of Mappings in cmpmap2 */ int nout2a; /* No. of outputs for 1st component Mapping */ int nout2b; /* No. of outputs for 2nd component Mapping */ int npin; /* No. of inputs for original PermMap */ int npin_new; /* No. of inputs for new PermMap */ int npout; /* No. of outputs for original PermMap */ int npout_new; /* No. of outputs for new PermMap */ int nunit; /* No. of PermMap i/p's fed by UnitMap */ int oconid; /* Constant identifier in returned PermMap */ int result; /* Result value to return */ int set; /* Invert attribute set? */ int simpler; /* Simplification possible? */ int subin2; /* Number of inputs of submap2 */ int subinv1; /* Invert attribute to use with submap1 */ int subinv2; /* Invert attribute to use with submap2 */ int subout1; /* Number of outputs of submap1 */ /* Initialise.*/ result = -1; /* Check the inherited status. */ if ( !astOK ) return result; /* Simplify the CmpMap on its own. */ /* =============================== */ /* Obtain a pointer to the nominated Mapping (which is a CmpMap). */ map = ( *map_list )[ where ]; cmpmap = (AstCmpMap *) map; /* Determine if the Mapping's Invert attribute is set and obtain its value. */ set = astTestInvert( map ); invert = astGetInvert( map ); /* If necessary, change the Invert attribute to the value we want. We do this so that simplification (below) has a chance to absorb a non-zero Invert value into the implementation of the simplified Mapping (the preference being to have an Invert value of zero after simplification, if possible). */ if ( invert != ( *invert_list )[ where ] ) { astSetInvert( map, ( *invert_list )[ where ] ); } /* Simplify the Mapping and obtain the new Invert value. */ new = astSimplify( map ); new_invert = astGetInvert( new ); /* If necessary, restore the original Mapping's Invert attribute to its initial state. */ if ( invert != ( *invert_list )[ where ] ) { if ( set ) { astSetInvert( map, invert ); } else { astClearInvert( map ); } } /* We must now determine if simplification has occurred. Since this is internal code, we can compare the two Mapping pointers directly to see whether "astSimplify" just cloned the pointer we gave it. If it did, then simplification was probably not possible, but check to see if the Invert attribute has changed to be sure. */ if ( astOK ) { simpler = ( new != map ) || ( new_invert != ( *invert_list )[ where ] ); /* If simplification was successful, annul the original pointer in the Mapping list and replace it with the new one, together with its invert flag. */ if ( simpler ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = new_invert; /* Return the result. */ result = where; /* Otherwise, annul the new Mapping pointer. */ } else { new = astAnnul( new ); /* If the nominated CmpMap is a series CmpMap and the sequence of Mappings are being combined in series, or if the nominated CmpMap is a parallel CmpMap and the sequence of Mappings are being combined in parallel, replace the single CmpMap with the two component Mappings. */ if( ( series && cmpmap->series ) || ( !series && !cmpmap->series ) ) { /* We are increasing the number of Mappings in the list, so we need to create new, larger, arrays to hold the list of Mapping pointers and invert flags. */ new_map_list = astMalloc( ( *nmap + 1 )*sizeof( AstMapping * ) ); new_invert_list = astMalloc( ( *nmap + 1 )*sizeof( int ) ); if( astOK ) { /* Copy the values prior to the nominated CmpMap. */ for( i = 0; i < where; i++ ) { new_map_list[ i ] = astClone( ( *map_list )[ i ] ); new_invert_list[ i ] = ( *invert_list )[ i ]; } /* Next insert the two components of the nominated CmpMap */ new_map_list[ where ] = astClone( cmpmap->map1 ); new_invert_list[ where ] = cmpmap->invert1; new_map_list[ where + 1 ] = astClone( cmpmap->map2 ); new_invert_list[ where + 1 ] = cmpmap->invert2; /* Now copy any values after the nominated CmpMap. */ for( i = where + 1; i < *nmap; i++ ) { new_map_list[ i + 1 ] = astClone( ( *map_list )[ i ] ); new_invert_list[ i + 1 ] = ( *invert_list )[ i ]; } /* Now annul the Object pointers in the supplied map list. */ for( i = 0; i < *nmap; i++ ) { (* map_list )[ i ] = astAnnul( ( *map_list )[ i ] ); } /* Free the memory holding the supplied Mapping and invert flag lists. */ astFree( *map_list ); astFree( *invert_list ); /* Return pointers to the new extended lists. */ *map_list = new_map_list; *invert_list = new_invert_list; /* Increase the number of Mappings in the list, and the index of the first modified Mapping. */ (*nmap)++; result = where; /* Indicate some simplification has taken place */ simpler = 1; } } } /* If no simplification has been done, merge adjacent CmpMaps. */ /* ========================================================== */ /* If the CmpMap would not simplify on its own, we now look for a neighbouring CmpMap with which it might merge. We use the previous Mapping, if suitable, since this will normally also have been fully simplified on its own. Check if a previous Mapping exists. */ if( !simpler ) { if ( astOK && *nmap > 1 ) { /* Obtain the indices of the two potential Mappings to be merged. imap1 is the first Mapping, imap2 is the second. imapc is the CmpMap, imapn is the neighbouring Mapping. */ if( where == 0 ) { imap1 = 0; imap2 = 1; } else { imap1 = where - 1; imap2 = where; } /* Obtain the Class string of the neighbouring Mapping and determine if it is a CmpMap. */ class = astGetClass( ( *map_list )[ (where>0)?where-1:1 ] ); if ( astOK && !strcmp( class, "CmpMap" ) ) { /* If suitable, obtain pointers to the two CmpMaps. */ cmpmap1 = (AstCmpMap *) ( *map_list )[ imap1 ]; cmpmap2 = (AstCmpMap *) ( *map_list )[ imap2 ]; /* Obtain the associated invert flag values. */ invert1 = ( *invert_list )[ imap1 ]; invert2 = ( *invert_list )[ imap2 ]; /* Extract the invert flags associated with each CmpMap sub-Mapping and combine these with the flag values obtained above so as to give the invert flag to be used with each individual sub-Mapping. */ invert1a = cmpmap1->invert1; invert1b = cmpmap1->invert2; if ( invert1 ) { invert1a = !invert1a; invert1b = !invert1b; } invert2a = cmpmap2->invert1; invert2b = cmpmap2->invert2; if ( invert2 ) { invert2a = !invert2a; invert2b = !invert2b; } /* Series CmpMaps in parallel. */ /* =========================== */ /* Now check if the CmpMaps can be merged. This may be possible if we are examining a list of Mappings combined in parallel and the two adjacent CmpMaps both combine their sub-Mappings in series. */ if ( !series && cmpmap1->series && cmpmap2->series ) { /* Form two new parallel CmpMaps with the sub-Mappings re-arranged so that when combined in series these new CmpMaps are equivalent to the original ones. In doing this, we must take account of the invert flags which apply to each sub-Mapping and also of the fact that the order in which the sub-Mappings are applied depends on the invert flags of the original CmpMaps. */ new1 = CombineMaps( invert1 ? cmpmap1->map2 : cmpmap1->map1, invert1 ? invert1b : invert1a, invert2 ? cmpmap2->map2 : cmpmap2->map1, invert2 ? invert2b : invert2a, 0, status ); new2 = CombineMaps( invert1 ? cmpmap1->map1 : cmpmap1->map2, invert1 ? invert1a : invert1b, invert2 ? cmpmap2->map1 : cmpmap2->map2, invert2 ? invert2a : invert2b, 0, status ); /* Having converted the parallel combination of series CmpMaps into a pair of equivalent parallel CmpMaps that can be combined in series, try and simplify each of these new CmpMaps. */ simp1 = astSimplify( new1 ); simp2 = astSimplify( new2 ); /* Test if either could be simplified by checking if its pointer value has changed. Also check if the Invert attribute has changed (not strictly necessary, but a useful safety feature in case of any rogue code which just changes this attribute instead of issuing a new pointer). */ simpler = ( simp1 != new1 ) || ( simp2 != new2 ) || astGetInvert( simp1 ) || astGetInvert( simp2 ); /* If either CmpMap was simplified, then combine the resulting Mappings in series to give the replacement CmpMap. */ if ( simpler ) new = (AstMapping *) astCmpMap( simp1, simp2, 1, "", status ); /* Annul the temporary Mapping pointers. */ new1 = astAnnul( new1 ); new2 = astAnnul( new2 ); simp1 = astAnnul( simp1 ); simp2 = astAnnul( simp2 ); /* Parallel CmpMaps in series. */ /* =========================== */ /* A pair of adjacent CmpMaps can also potentially be merged if we are examining a list of Mappings combined in series and the two adjacent CmpMaps both combine their sub-Mappings in parallel. */ } else if ( series && !cmpmap1->series && !cmpmap2->series ) { /* Expand each of the two adjacent CmpMaps into a list of Mappings to be combined in parallel. */ map_list1 = map_list2 = NULL; invert_list1 = invert_list2 = NULL; nmap1 = nmap2 = 0; (void) astMapList( (AstMapping *) cmpmap1, 0, invert1, &nmap1, &map_list1, &invert_list1 ); (void) astMapList( (AstMapping *) cmpmap2, 0, invert2, &nmap2, &map_list2, &invert_list2 ); /* We want to divide each of these lists into N sub-lists so that the outputs of the Mappings in the i'th sub-list from cmpmap1 can feed (i.e. equal in number) the inputs of the Mappings in the i'th sub-list from cmpmap2. If such a sub-list contains more than one Mapping we combine them together into a parallel CmpMap. Initialise a flag to indicate that we have not yet found any genuine simplification. */ simpler = 0; /* Initialise the index of the next Mapping to be added into each sublist. */ jmap1 = jmap2 = 0; /* Indicate both sublists are currently empty. */ subout1 = subin2 = 0; new = submap1 = submap2 = NULL; subinv1 = subinv2 = 0; /* Loop round untill all Mappings have been used. */ while( jmap1 <= nmap1 && jmap2 <= nmap2 && astOK ) { /* Note the number of outputs from submap1 and the number of inputs to submap2. If the Invert flag is not set to the required value for either Mapping, then inputs become outputs and vice-versa, so swap Nin and Nout. */ if( !submap1 ) { subout1 = 0; } else if( subinv1 == astGetInvert( submap1 ) ) { subout1 = astGetNout( submap1 ); } else { subout1 = astGetNin( submap1 ); } if( !submap2 ) { subin2 = 0; } else if( subinv2 == astGetInvert( submap2 ) ) { subin2 = astGetNin( submap2 ); } else { subin2 = astGetNout( submap2 ); } /* If sublist for cmpmap1 has too few outputs, add the next Mapping from the cmpmap1 list into the submap1 sublist. */ if( subout1 < subin2 ) { tmap = CombineMaps( submap1, subinv1, map_list1[ jmap1 ], invert_list1[ jmap1 ], 0, status ); (void) astAnnul( submap1 ); submap1 = tmap; subinv1 = 0; jmap1++; /* If sublist for cmpmap2 has too few inputs, add the next Mapping from the cmpmap2 list into the submap2 sublist. */ } else if( subin2 < subout1 ) { tmap = CombineMaps( submap2, subinv2, map_list2[ jmap2 ], invert_list2[ jmap2 ], 0, status ); (void) astAnnul( submap2 ); submap2 = tmap; subinv2 = 0; jmap2++; /* If submap1 can now feed submap2, combine them in series, and attempt to simplify it. */ } else { /* Check this is not the first pass (when we do not have a submap1 or submap2). */ if( submap1 && submap2 ) { /* Combine the Mappings in series and simplify. */ tmap = CombineMaps( submap1, subinv1, submap2, subinv2, 1, status ); submap1 = astAnnul( submap1 ); submap2 = astAnnul( submap2 ); tmap2 = astSimplify( tmap ); tmap = astAnnul( tmap ); /* Note if any simplification took place. */ if( tmap != tmap2 || astGetInvert( tmap ) != astGetInvert( tmap2 ) ) simpler = 1; /* Add the simplifed Mapping into the total merged Mapping (a parallel CmpMap). */ if( !new ) { new = tmap2; } else { tmap = (AstMapping *) astCmpMap( new, tmap2, 0, " ", status ); tmap2 = astAnnul( tmap2 ); (void) astAnnul( new ); new = tmap; } } /* Reset submap1 to be the next Mapping from the cmpmap1 map list. First, save its old Invert flag and set it to the required value. */ if( jmap1 < nmap1 ) { submap1 = astClone( map_list1[ jmap1 ] ); subinv1 = invert_list1[ jmap1 ]; jmap1++; } else { break; } /* Do the same for the second list. */ if( jmap2 < nmap2 ) { submap2 = astClone( map_list2[ jmap2 ] ); subinv2 = invert_list2[ jmap2 ]; jmap2++; } else { break; } } } /* Free the lists of Mapping pointers and invert flags. */ if( map_list1 ) { for( jmap1 = 0; jmap1 < nmap1; jmap1++ ) { map_list1[ jmap1 ] = astAnnul( map_list1[ jmap1 ] ); } map_list1 = astFree( map_list1 ); } invert_list1 = astFree( invert_list1 ); if( map_list2 ) { for( jmap2 = 0; jmap2 < nmap2; jmap2++ ) { map_list2[ jmap2 ] = astAnnul( map_list2[ jmap2 ] ); } map_list2 = astFree( map_list2 ); } invert_list2 = astFree( invert_list2 ); } } /* Update Mapping list. */ /* ==================== */ /* If adjacent CmpMaps can be combined, then annul the original pointers. */ if ( astOK && simpler ) { ( *map_list )[ imap1 ] = astAnnul( ( *map_list )[ imap1 ] ); ( *map_list )[ imap2 ] = astAnnul( ( *map_list )[ imap2 ] ); /* Insert the pointer to the replacement CmpMap and initialise its invert flag. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Loop to close the resulting gap by moving subsequent elements down in the arrays. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - 1 ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - 1 ] = ( *invert_list )[ imap ]; } /* Clear the vacated elements at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = imap1; } } } } /* If we are merging the Mappings in series, and if the nominated CmpMap is a parallel CmpMap, and if the lower neighbour is a PermMap, it may be possible to swap the PermMap and the CmpMap. This may allow one of the two swapped Mappings to merge with its new neighbour. ==================================================================== */ /* Only do this if no simplification occurred above, and if the Mappings are being merged in series, and if the nominated Mapping is not the first in the list. */ if( result == -1 && where > 0 ){ /* Obtain the indices of the two potential Mappings to be swapped. */ imap1 = where - 1; imap2 = where; /* Obtain a pointer to the CmpMap. */ cmpmap2 = (AstCmpMap *) ( *map_list )[ imap2 ]; /* Obtain the Class string of the first (previous) Mapping and determine if it is a PermMap. Also check that the nominated Mapping is a parallel CmpMap. */ class = astGetClass( ( *map_list )[ imap1 ] ); if ( astOK && !strcmp( class, "PermMap" ) && !cmpmap2->series) { /* Indicate we have no new Mapping to store. */ new = NULL; /* If suitable, obtain a pointer to the PermMap. */ permmap1 = (AstPermMap *) ( *map_list )[ imap1 ]; /* Obtain the current values of the Invert attribute in the Mappings. */ invert1 = astGetInvert( permmap1 ); invert2 = astGetInvert( cmpmap2 ); /* Temporarily set the Invert attributes of both Mappings to the values supplied in the "invert_list" parameter. */ astSetInvert( permmap1, ( *invert_list )[ imap1 ] ); astSetInvert( cmpmap2, ( *invert_list )[ imap2 ] ); /* Get the number of inputs and outputs for the PermMap.*/ npout = astGetNout( permmap1 ); npin = astGetNin( permmap1 ); /* Get the number of inputs and outputs for the two components of the nominated parallel CmpMap. */ nin2a = astGetNin( cmpmap2->map1 ); nin2b = astGetNin( cmpmap2->map2 ); nout2a = astGetNout( cmpmap2->map1 ); nout2b = astGetNout( cmpmap2->map2 ); /* Get the input and output axis permutation arrays and the constants array from the PermMap */ inperm =astGetInPerm( permmap1 ); outperm =astGetOutPerm( permmap1 ); conperm = astGetConstants( permmap1 ); /* In order to swap the Mappings, the PermMap outputs which feed the inputs of the first component of the parallel CmpMap must be copied from a contiguous block at the end of the list of PermMap inputs, or must all be assigned constant values. Likewise, the PermMap outputs which feed the inputs of the second component of the parallel CmpMap must be copied from a contiguous block at the beggining of the list of PermMap inputs or must be assigned constant values. Also, there must be a one-to-one correspondance between inputs and outputs in the PermMap. Check that the first block of nin2a PermMap outputs are copied from the last block of nin2a PermMap inputs (and vica-versa) or are constant. */ canswap = ( npin == npout ); aconstants = ( outperm[ 0 ] < 0 ); for( i = 0, j = npin - nin2a; i < nin2a; i++, j++ ) { if( aconstants ) { if( outperm[ i ] >= 0 ) { canswap = 0; break; } } else if( outperm[ i ] != j || inperm[ j ] != i ) { canswap = 0; break; } } /* Check that the first block of nin2b PermMap inputs are copied from the last block of nin2b PermMap outputs, and vica-versa. */ bconstants = ( outperm[ nin2a ] < 0 ); for( i = 0, j = npout - nin2b; i < nin2b; i++, j++ ) { if( bconstants ) { if( outperm[ j ] >= 0 ) { canswap = 0; break; } } else if( inperm[ i ] != j || outperm[ j ] != i ) { canswap = 0; break; } } /* If the Mappings can be swapped.. */ new_pm = NULL; new_cm = NULL; qa = NULL; qb = NULL; if( canswap ) { /* Temporarily set the Invert attributes of the component Mappings to the values they had when the CmpMap was created. */ invert2a = astGetInvert( cmpmap2->map1 ); invert2b = astGetInvert( cmpmap2->map2 ); astSetInvert( cmpmap2->map1, cmpmap2->invert1 ); astSetInvert( cmpmap2->map2, cmpmap2->invert2 ); /* If any PermMap outputs are constant, we will need the results of transforming these constants using the CmpMap which follows. */ if( aconstants || bconstants ) { /* Transform a set of bad inputs using the PermMap. This will assign the PermMap constant to any fixed outputs. */ p = astMalloc( sizeof( double )*(size_t) npin ); q = astMalloc( sizeof( double )*(size_t) npout ); qa = astMalloc( sizeof( double )*(size_t) nout2a ); qb = astMalloc( sizeof( double )*(size_t) nout2b ); if( astOK ) { for( i = 0; i < npin; i++ ) p[ i ] = AST__BAD; astTranN( permmap1, 1, npin, 1, p, 1, npout, 1, q ); /* Transform the PermMap outputs using the two component Mappings in the CmpMap. */ astTranN( cmpmap2->map1, 1, nin2a, 1, q, 1, nout2a, 1, qa ); astTranN( cmpmap2->map2, 1, nin2b, 1, q + nin2a, 1, nout2b, 1, qb ); } p = astFree( p ); q = astFree( q ); } /* If necessary, create a UnitMap to replace a Mapping which has constant outputs. The number of axes for the UnitMap is chosen to give the correct total number of inputs for the final parallel CmpMap. At the same time determine the number of inputs needed by the final PermMap. */ if( aconstants ) { nunit = npin - nin2b; npin_new = nout2b + nunit; } else if( bconstants ) { nunit = npin - nin2a; npin_new = nout2a + nunit; } else { nunit = 0; npin_new = nout2a + nout2b; } unit = nunit ? astUnitMap( nunit, "", status ) : NULL; /* Determine the number of outputs for the final PermMap and allocate memory for its permutation arrays. */ npout_new = nout2a + nout2b; outperm_new = astMalloc( sizeof( int )*(size_t) npout_new ); inperm_new = astMalloc( sizeof( int )*(size_t) npin_new ); const_new = astMalloc( sizeof( double )*(size_t) ( npout_new + npin_new ) ); if( astOK ) { oconid = 0; /* First assign permutations for the second component Mapping, if used. */ if( !bconstants ) { for( i = 0, j = npout_new - nout2b; i < nout2b; i++,j++ ) { inperm_new[ i ] = j; outperm_new[ j ] = i; } /* Otherwise, store constants */ } else { for( i = 0; i < nunit; i++ ){ iconid = inperm[ i ]; if( iconid >= npout ) { inperm_new[ i ] = npout_new; } else if( iconid >= 0 ) { astError( AST__INTER, "astMapMerge(CmpMap): Swapped PermMap " "input is not constant (internal AST programming " "error)." , status); break; } else { inperm_new[ i ] = --oconid; const_new[ -( oconid + 1 ) ] = conperm[ -( iconid + 1 ) ]; } } for( i = 0, j = npout_new - nout2b; i < nout2b; i++,j++ ) { outperm_new[ j ] = --oconid; const_new[ -( oconid + 1 ) ] = qb[ i ]; } } /* Now assign permutations for the first component Mapping, if used. */ if( !aconstants ) { for( i = 0, j = npin_new - nout2a; i < nout2a; i++,j++ ) { inperm_new[ j ] = i; outperm_new[ i ] = j; } /* Otherwise, store constants */ } else { for( i = nout2b; i < npin_new; i++ ){ iconid = inperm[ i - nout2b + nin2b ]; if( iconid >= npout ) { inperm_new[ i ] = npout_new; } else if( iconid >= 0 ) { astError( AST__INTER, "astMapMerge(CmpMap): Swapped PermMap " "input is not constant (internal AST programming " "error)." , status); break; } else { inperm_new[ i ] = --oconid; const_new[ -( oconid + 1 ) ] = conperm[ -( iconid + 1 ) ]; } } for( i = 0; i < nout2a; i++ ) { outperm_new[ i ] = --oconid; const_new[ -( oconid + 1 ) ] = qa[ i ]; } } /* Create the new PermMap */ new_pm = astPermMap( npin_new, inperm_new, npout_new, outperm_new, const_new, "", status ); /* Create the new CmpMap.*/ if( aconstants ) { if( unit ) { new_cm = astCmpMap( cmpmap2->map2, unit, 0, "", status ); } else { new_cm = astCopy( cmpmap2->map2 ); } } else if( bconstants ) { if( unit ) { new_cm = astCmpMap( unit, cmpmap2->map1, 0, "", status ); } else { new_cm = astCopy( cmpmap2->map1 ); } } else{ new_cm = astCmpMap( cmpmap2->map2, cmpmap2->map1, 0, "", status ); } } /* Free Memory. */ if( unit ) unit = astAnnul( unit ); outperm_new = astFree( outperm_new ); inperm_new = astFree( inperm_new ); const_new = astFree( const_new ); if( aconstants || bconstants ) { qa = astFree( qa ); qb = astFree( qb ); } /* Re-instate the original Invert attributes in the component Mappings. */ astSetInvert( cmpmap2->map1, invert2a ); astSetInvert( cmpmap2->map2, invert2b ); } /* Release the arrays holding the input and output permutation arrays and constants copied from the PermMap. */ inperm = astFree( inperm ); outperm = astFree( outperm ); conperm = astFree( conperm ); /* Re-instate the original values of the Invert attributes of both Mappings. */ astSetInvert( permmap1, invert1 ); astSetInvert( cmpmap2, invert2 ); /* If the Mappings can be swapped... */ if( astOK && canswap ) { /* Annul the supplied pointer to the two Mappings. */ ( *map_list )[ imap1 ] = astAnnul( ( *map_list )[ imap1 ] ); ( *map_list )[ imap2 ] = astAnnul( ( *map_list )[ imap2 ] ); /* Store the new PermMap pointer in the slot previously occupied by the nominated CmpMap pointer. Likewise, store the invert flag. */ ( *map_list )[ imap2 ] = (AstMapping *) new_pm; ( *invert_list )[ imap2 ] = astGetInvert( new_pm ); /* Store the new PermMap pointer in the slot previously occupied by the nominated CmpMap pointer. Likewise, store the invert flag. */ ( *map_list )[ imap1 ] = (AstMapping *) new_cm; ( *invert_list )[ imap1 ] = astGetInvert( new_cm ); /* Return the index of the first modified element. */ result = imap1; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static int *MapSplit1( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ){ /* * Name: * MapSplit1 * Purpose: * Create a Mapping representing a subset of the inputs of an existing * Mapping. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int *MapSplit1( AstMapping *this, int nin, const int *in, AstMapping **map ) * Class Membership: * CmpMap method * Description: * This function performs the work for the astMapSplit method. It * first invokes the astMapSplit method to see if the forward * transformation of the supplied Mapping (not necessarily a CmpMap) * can be split as requested. If this is not possible it invokes MapSplit2 * which attempts an inverse approach to the problem. For each possible * sub-sets of the Mapping outputs it call astMapSplit to see if the * sub-set of outputs are generated from the selected inputs. * Parameters: * this * Pointer to the Mapping to be split. It is not assumed to be a CmpMap. * 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 Mapping, 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 Mapping has no subset of outputs which * depend only on the selected inputs. * 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 Mapping. The array should be * freed using astFree when no longer needed. A NULL pointer will * be returned if no output Mapping can be created. * Notes: * - If this function is invoked with the global error status set, * or if it should fail for any reason, then NULL values will be * returned as the function value and for the "map" pointer. */ /* Local Variables: */ int *result; /* Axis order to return */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* First see if the forward transformation can be split as requested. */ result = astMapSplit( this, nin, in, map ); /* If forward transformation could not be split, we attempt to split the inverse transformation by selecting every possible sub-set of Mapping outputs until one is found which is fed by the requested mapping inputs. */ if( !result ) result = MapSplit2( this, nin, in, map, status ); /* 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 *MapSplit2( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ){ /* * Name: * MapSplit2 * Purpose: * Create a Mapping representing a subset of the inputs of an existing * Mapping. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int *MapSplit2( AstMapping *this, int nin, const int *in, AstMapping **map ) * Class Membership: * CmpMap method * Description: * This function attempts to split the supplied Mapping using an * inverse approach to the problem. For each possible sub-sets of the * Mapping outputs it call astMapSplit to see if the sub-set of outputs * are generated from the selected inputs. * Parameters: * this * Pointer to the Mapping to be split. It is not assumed to be a CmpMap. * 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 Mapping, 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 Mapping has no subset of outputs which * depend only on the selected inputs. * 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 Mapping. 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 *map2; /* Subset Mapping */ AstMapping *this2; /* Inverted copy of the supplied Mapping */ int *out; /* Selected output indices */ int *result; /* Axis order to return */ int *result2; /* Axis order for current output subset */ int i; /* Loop count */ int iscmp; /* Is "this" a CmpMap? */ int j; /* Loop count */ int mout; /* Number of selected outputs */ int nin2; /* Number of inputs fed by current outputs */ int nout; /* The number of outputs from the supplied Mapping */ int ok; /* Are all required inputs fed by current outputs? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the number of Mapping outputs. */ nout = astGetNout( this ); /* Get an inverted copy of the Mapping. We do this rather than inverting the supplied Maping in case an error occurs which may leave the supplied Mapping inverted. */ this2 = astCopy( this ); astInvert( this2 ); /* Note if the Mapping is a CmpMap. */ iscmp = astIsACmpMap( this ); /* Allocate memory to hold the selected output indices. */ out = astMalloc( nout*sizeof( int ) ); /* Loop round all useful subset sizes. */ if( out ) { for( mout = 1; mout < nout && !result; mout++ ) { /* Initialise the first subset of outputs to check at the current subset size. */ for( i = 0; i < mout; i++ ) out[ i ] = 0; /* Loop round all ways of picking a subset of "mout" outputs from the total available "nout" outputs. */ while( ! result ) { /* Skip this subset if it refers to any axis index more than once. */ ok = 1; for( i = 1; i < mout && ok; i++ ) { for( j = 0; j < i; j++ ) { if( out[ i ] == out[ j ] ) { ok = 0; break; } } } if( ok ) { /* Attempt to split the inverted Mapping using the current subset of outputs. Take care to avoid an infinite loop if "this" is a CmpMap. */ if( iscmp ) { result2 = MapSplit0( this2, mout, out, &map2, 1, status ); } else { result2 = astMapSplit( this2, mout, out, &map2 ); } /* If succesful... */ if( result2 ) { /* See if the inputs that feed the current subset of outputs are the same as the inputs specified by the caller (and in the same order). */ nin2 = astGetNout( map2 ); ok = ( nin2 == nin ); if( ok ) { for( i = 0; i < nin; i++ ) { if( in[ i ] != result2[ i ] ) { ok = 0; break; } } } /* If so, set up the values returned to the caller. */ if( ok ) { result = astStore( result, out, mout*sizeof(int) ); astInvert( map2 ); *map = astClone( map2 ); } /* Free resources. */ result2 = astFree( result2 ); map2 = astAnnul( map2 ); } } /* Increment the first axis index. */ i = 0; out[ i ]++; /* If the incremented axis index is now too high, reset it to zero and increment the next higher axis index. Do this until an incremented axis index is not too high. */ while( out[ i ] == nout ) { out[ i++ ] = 0; if( i < mout ) { out[ i ]++; } else { break; } } /* If all subsets have been checked break out of the loop. */ if( i == mout ) break; } } } /* Free resources. */ out = astFree( out ); this2 = astAnnul( this2 ); /* 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 *MapSplit0( AstMapping *this_mapping, int nin, const int *in, AstMapping **map, int reentry, int *status ){ /* * Name: * MapSplit0 * Purpose: * Create a Mapping representing a subset of the inputs of an existing * CmpMap. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int *MapSplit0( AstMapping *this, int nin, const int *in, * AstMapping **map, int reentry, int *status ) * Class Membership: * CmpMap method * Description: * This function creates a new Mapping by picking specified inputs from * an existing CmpMap. This is only possible if the specified inputs * correspond to some subset of the CmpMap outputs. That is, there * must exist a subset of the CmpMap outputs for which each output * depends only on the selected CmpMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied CmpMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the CmpMap to be split (the CmpMap 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 CmpMap, 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 CmpMap has no subset of outputs which * depend only on the selected inputs. * reentry * Set to zero if this is a top level entry, and non-zero if it is * a recursive entry. * 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 CmpMap. 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: */ AstCmpMap *this; AstMapping **map_list; AstMapping *amap; AstMapping *bmap; AstPermMap *pmap; int *aout; int *cin; int *cout; int *inp; int *invert_list; int *outp; int *p; int *result; int doperm; int i; int ibot; int ibotout; int iin; int imap; int iout; int itop; int j; int naout; int ncin; int ncout; int nmap; int npin; int npout; int ok; int old_inv; int t; /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the CmpMap structure. */ this = (AstCmpMap *) this_mapping; /* Get the number of inputs and outputs in the supplied CmpMap. */ npin = astGetNin( this ); npout = astGetNout( this ); /* Check all input axis indices are valid. */ ok = 1; for( i = 0; i < nin; i++ ) { if( in[ i ] < 0 || in[ i ] >= npin ) { ok = 0; break; } } /* If OK, proceed. */ if( ok ) { /* Initialise dynamic arrays of Mapping pointers and associated Invert flags. */ nmap = 0; map_list = NULL; invert_list = NULL; /* Decompose the CmpMap into a sequence of Mappings to be applied in series or parallel, as appropriate, and an associated list of Invert flags. */ (void) astMapList( this_mapping, this->series, astGetInvert( this ), &nmap, &map_list, &invert_list ); /* First handle lists of Mapping in series. */ if( this->series ) { /* Initialise the array of inputs to be split from the next component Mapping. */ ncin = nin; cin = astStore( NULL, in, sizeof( int )*nin ); /* Loop round all the component Mappings that are combined in series to form the supplied CmpMap. */ for( imap = 0; imap < nmap && cin; imap++ ) { /* Temporarily reset the Invert attribute within the commponent Mapping back to the value it had when the CmpMap was created. */ old_inv = astGetInvert( map_list[ imap ] ); astSetInvert( map_list[ imap ], invert_list[ imap ] ); /* Attempt to split the component Mapping using the current list of inputs. */ cout = MapSplit1( map_list[ imap ], ncin, cin, &amap, status ); /* If the split could be done... */ if( amap ) { /* The outputs that correspond to the picked inputs become the inputs to be picked from the next component Mapping. */ (void) astFree( cin ); cin = cout; ncin = astGetNout( amap ); /* Combine the split Mapping in series with the earlier split Mappings. */ if( *map ) { bmap = (AstMapping *) astCmpMap( *map, amap, 1, " ", status ); amap = astAnnul( amap ); (void) astAnnul( *map ); *map = bmap; } else { *map = amap; } /* If the split could not be done, free the array of Mapping inputs to indicate that no more component Mappings need be checked. */ } else { cin = astFree( cin ); cout = astFree( cout ); } /* Re-instate the original value of the Invert attribute within the commponent Mapping. */ astSetInvert( map_list[ imap ], old_inv ); } /* Return the final array of output indices. */ result = cin; /* Now handle lists of Mapping in parallel. */ } else { /* Allocate work space. */ outp = astMalloc( sizeof(int)*(size_t)nin ); inp = astMalloc( sizeof(int)*(size_t)nin ); cin = astMalloc( sizeof(int)*(size_t)npin ); cout = astMalloc( sizeof(int)*(size_t)npout ); if( astOK ) { /* The caller may have selected the Mapping inputs in any order, so we need to create a PermMap which will permute the inputs from the requested order to the order used by the CmpMap. First fill the outperm work array with its own indices. */ for( i = 0; i < nin; i++ ) outp[ i ] = i; /* Sort the outperm work array so that it accesses the array of input indices in ascending order */ for( j = nin - 1; j > 0; j-- ) { p = outp; for( i = 0; i < j; i++,p++ ) { if( in[ p[0] ] > in[ p[1] ] ) { t = p[0]; p[0] = p[1]; p[1] = t; } } } /* Create the inperm array which is the inverse of the above outperm array. Note if the permutation is necessary. */ doperm = 0; for( i = 0; i < nin; i++ ) { if( outp[ i ] != i ) doperm = 1; inp[ outp[ i ] ] = i; } /* Create a PermMap which reorders the inputs into ascending order. */ pmap = doperm ? astPermMap( nin, inp, nin, outp, NULL, "", status ) : NULL; /* Store the sorted input indices in the inp work array. */ for( i = 0; i < nin; i++ ) { inp[ i ] = in[ outp[ i ] ]; } /* Initialise the index within the supplied CmpMap of the last (highest) input in the current component Mapping. */ itop = -1; /* Initialise the index within the supplied CmpMap of the first (lowest) output for the current component Mapping. */ ibotout = 0; /* Initialise the index within the supplied CmpMap of the current picked input. */ iin = 0; /* Initialise the index of the next returned output index. */ ncout = 0; /* Loop round all the component Mappings that are combined in series to form the supplied CmpMap. */ for( imap = 0; imap < nmap && cout; imap++ ) { /* Temporarily reset the Invert attribute within the component Mapping back to the value it had when the CmpMap was created. */ old_inv = astGetInvert( map_list[ imap ] ); astSetInvert( map_list[ imap ], invert_list[ imap ] ); /* Get the index within the supplied CmpMap of the first (lowest) input in the current component Mapping. */ ibot = itop + 1; /* Get the index within the supplied CmpMap of the last (highest) input in the current component Mapping. */ itop += astGetNin( map_list[ imap ] ); /* Get the zero-based indices of the required inputs that feed the current component Mapping. */ ncin = 0; while( iin < nin && inp[ iin ] <= itop ) { cin[ ncin++ ] = inp[ iin++ ] - ibot; } /* Skip components from which no inputs are being picked. */ if( ncin > 0 ) { /* Attempt to split the component Mapping using the current list of inputs. */ aout = MapSplit1( map_list[ imap ], ncin, cin, &amap, status ); /* If successful... */ if( amap ) { /* Correct the output indices so that they refer to the numbering scheme of the total CmpMap, and append to the total list of output indices. */ naout = astGetNout( amap ); for( iout = 0; iout < naout; iout++ ) { cout[ ncout++ ] = aout[ iout ] + ibotout; } /* Combine the split Mapping in parallel with the earlier split Mappings. */ if( *map ) { bmap = (AstMapping *) astCmpMap( *map, amap, 0, " ", status ); amap = astAnnul( amap ); (void) astAnnul( *map ); *map = bmap; } else { *map = amap; } /* If the component Mapping could not be split, free the cout array to indicate that no more component Mappings need be considered. */ } else { cout = astFree( cout ); } /* Free remaining resources. */ aout = astFree( aout ); } /* Update the index within the supplied CmpMap of the first (lowest) output in the next component Mapping. */ ibotout += astGetNout( map_list[ imap ] ); /* Re-instate the original value of the Invert attribute within the commponent Mapping. */ astSetInvert( map_list[ imap ], old_inv ); } /* If the requested inputs could be split from the total CmpMap, add in any PermMap needed to re-order the inputs. */ if( cout && ncout ){ if( doperm ) { bmap = (AstMapping *) astCmpMap( pmap, *map, 1, "", status ); (void) astAnnul( *map ); *map = bmap; } /* Also return the list of output indices. */ result = cout; cout = NULL; } /* Free remaining resources. */ if( pmap ) pmap = astAnnul( pmap ); } outp = astFree( outp ); inp = astFree( inp ); cin = astFree( cin ); cout = astFree( cout ); } /* Loop to annul all the Mapping pointers in the list. */ for ( i = 0; i < nmap; i++ ) map_list[ i ] = astAnnul( map_list[ i ] ); /* Free the dynamic arrays. */ map_list = astFree( map_list ); invert_list = astFree( invert_list ); } /* Mappings that have no outputs cannot be used. */ if( !result && *map ) *map = astAnnul( *map ); /* If the above method failed to split the CmpMap, we attempt to split the inverse transformation by selecting every possible sub-set of Mapping outputs until one is found which is fed by the requested mapping inputs. */ if( !result && !reentry ) result = MapSplit2( this_mapping, nin, in, map, status ); /* 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 *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ){ /* * Name: * MapSplit * Purpose: * Create a Mapping representing a subset of the inputs of an existing * CmpMap. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, * AstMapping **map, int *status ) * Class Membership: * CmpMap method (over-rides the protected astMapSplit method * inherited from the Mapping class). * Description: * This function is the main entry point for the astMapSplit method. * It is a simple wrapper for MapSplit0 which calls MapSplit0 * indicating that this is a top-level entry. * Parameters: * this * Pointer to the CmpMap to be split (the CmpMap 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 CmpMap, 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 CmpMap 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 CmpMap. 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. */ return MapSplit0( this, nin, in, map, 0, status ); } static int PatternCheck( int val, int check, int **list, int *list_len, int *status ){ /* * Name: * Looping * Purpose: * Check for repeating patterns in a set of integer values. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * int PatternCheck( int val, int nmap, int **mlist, int **nlist, int *list_len ) * Class Membership: * CmpMap member function. * Description: * This function appends a supplied integer to a dynamic list, creating * or expanding the list if necessary.It then optionally, check the * list for evidence of repeating patterns. If such a pattern is * found, its wavelength is returned. * Parameters: * val * The integer value to add to the list. * check * Should a check for reating patterns be performed? * list * Address of a location at which is stored a pointer to an array * holding the values supplied on previous invocations of this * function. If a NULL pointer is supplied a new array is allocated. * On exit, the supplied value is appended to the end of the array. The * array is extended as necessary. The returned pointer should be * freed using astFree when no longer needed. * list_len * Address of a location at which is stored the number of elements * in the "list" array. * Returned Value: * A non-zero "wavelength" value is returned if there is a repeating * pattern is found in the "list" array. Otherwise, zero is returned. * The "wavelength" is the number of integer values which constitute a * single instance of the pattern. * Notes: * - A value of 1 is returned if this function is invoked with the AST * error status set, or if it should fail for any reason. */ /* Local Variables: */ int *wave[ 30 ]; /* Pointers to start of waves */ int iat; /* Index of elements added by this invocation */ int jat; /* Index of element condiered next */ int jlo; /* Earliest "mlist" entry to consider */ int k; /* Index of element within pattern */ int mxwave; /* Max pattern length to consider */ int iwave; /* Index of current wave */ int nwave; /* Number of waves required to mark a pattern */ int result; /* Returned flag */ int wavelen; /* Current pattern length */ /* Check the global status. */ if ( !astOK ) return 1; /* Initialise */ result = 0; /* If no array has been supplied, create a new array. */ if( !(*list) ) { *list = astMalloc( 100*sizeof( int ) ); *list_len = 0; } /* Store the new value in the array, extending it if necessary. */ iat = (*list_len)++; *list = astGrow( *list, *list_len, sizeof( int ) ); if( astOK ) { (*list)[ iat ] = val; /* If required, determine the maximum "wavelength" for looping patterns to be checked, and store the earliest list entry to consider. We take 3 complete patterns as evidence of looping, but we only do the check when the list length is at least 30. */ if( check && *list_len > 29 ){ mxwave = iat/3; if( mxwave > 50 ) mxwave = 50; jlo = iat - 3*mxwave; /* Search backwards from the end of "list" looking for the most recent occurence of the supplied "val" value. Limit the search to wavelengths of no more than the above limit. */ jat = iat - 1; while( jat >= jlo ) { if( (*list)[ jat ] == val ) { /* When an earlier occurrence of "val" is found, see if the values which precede it are the same as the values which precede the new element if "list" added by this invocation. We use 3 complete patterns as evidence of looping, unless the wavelength is 1 in which case we use 30 patterns (this is because wavelengths of 1 can occur in short sequences legitamately). */ wavelen = iat - jat; if( wavelen == 1 ) { nwave = 30; if( nwave > iat ) nwave = iat; } else { nwave = 3; } if( nwave*wavelen <= *list_len ) { result = wavelen; wave[ 0 ] = *list + *list_len - wavelen; for( iwave = 1; iwave < nwave; iwave++ ) { wave[ iwave ] = wave[ iwave - 1 ] - wavelen; } for( k = 0; k < wavelen; k++ ) { for( iwave = 1; iwave < nwave; iwave++ ) { if( *wave[ iwave ] != *wave[ 0 ] ) { result = 0; break; } wave[ iwave ]++; } wave[ 0 ]++; } } /* Break if we have found a repeating pattern. */ if( result ) break; } jat--; } } } if( !astOK ) result= 1; /* Return the result.*/ return result; } static double Rate( AstMapping *this, 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 "cmpmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * CmpMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ /* Local Variables: */ AstMapping *c1; AstMapping *c2; AstCmpMap *map; double result; int old_inv1; int old_inv2; int nin1; int nin2; double *at2; double r1; double r2; int nout1; int i; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the CmpMap structure. */ map = (AstCmpMap *) this; /* Note the current Invert flags of the two component Mappings. */ old_inv1 = astGetInvert( map->map1 ); old_inv2 = astGetInvert( map->map2 ); /* Temporarily reset them to the values they had when the CmpMap was created. */ astSetInvert( map->map1, map->invert1 ); astSetInvert( map->map2, map->invert2 ); /* If the CmpMap itself has been inverted, invert the component Mappings. Also note the order in which the Mappings should be applied if in series. */ if( !astGetInvert( this ) ) { c1 = map->map1; c2 = map->map2; } else { c1 = map->map2; c2 = map->map1; astInvert( c1 ); astInvert( c2 ); } /* First deal with Mappings in series. */ if( map->series ) { /* Get the number of inputs to the two component Mappings. */ nin1 = astGetNin( c1 ); nin2 = astGetNin( c2 ); /* Allocate workspace to hold the result of transforming the supplied "at" position using the first component. */ at2 = astMalloc( sizeof( double )*(size_t) nin2 ); /* Transform the supplied "at" position using the first component. */ astTranN( c1, 1, nin1, 1, at, 1, nin2, 1, at2 ); /* The required rate of change is the sum of the products of the rate of changes of the two component mappings, summed over all the output axes of the first componment. */ result = 0.0; for( i = 0; i < nin2; i++ ) { /* Find the rate of change of output "i" of the first component with respect to input "ax2" at the supplied "at" position. */ r1 = astRate( c1, at, i, ax2 ); /* Find the rate of change of output "ax1" of the second component with respect to input "i" at the transformed "at2" position. */ r2 = astRate( c2, at2, ax1, i ); /* If both are good, increment the ryunning total by the product of the two rates. Otherwise, break. */ if( r1 != AST__BAD && r2 != AST__BAD ) { result += r1*r2; } else { result = AST__BAD; break; } } /* Free the workspace. */ at2 = astFree( at2 ); /* Now deal with Mappings in parallel. */ } else { /* Get the number of inputs and outputs for the lower component Mappings. */ nin1 = astGetNin( map->map1 ); nout1 = astGetNout( map->map1 ); /* If both input and output relate to the lower component Mappings, use its astRate method. */ if( ax1 < nout1 && ax2 < nin1 ) { result = astRate( map->map1, at, ax1, ax2 ); /* If both input and output relate to the upper component Mappings, use its astRate method. */ } else if( ax1 >= nout1 && ax2 >= nin1 ) { result = astRate( map->map2, at + nin1, ax1 - nout1, ax2 - nin1 ); /* If input and output relate to different component Mappings, return zero. */ } else { result = 0.0; } } /* Reinstate the original Invert flags of the component Mappings .*/ astSetInvert( map->map1, old_inv1 ); astSetInvert( map->map2, old_inv2 ); /* Return the result. */ return result; } static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { /* * Name: * RemoveRegions * Purpose: * Remove any Regions from a Mapping. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * AstMapping *RemoveRegions( AstMapping *this, int *status ) * Class Membership: * CmpMap 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 CmpMap) for any component Mappings * that are instances of the AST Region class. It then creates a new * Mapping from which all Regions have been removed. If a Region * cannot simply be removed (for instance, if it is a component of a * parallel CmpMap), then it is replaced with an equivalent UnitMap * in the returned Mapping. * * The implementation provided by the CmpMap class invokes the * astRemoveRegions method on the two component Mappings, and joins * the results together into a new CmpMap. * 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: */ AstCmpMap *new; /* Pointer to new CmpMap */ AstCmpMap *this; /* Pointer to CmpMap structure */ AstMapping *newmap1; /* New first component Mapping */ AstMapping *newmap2; /* New second component Mapping */ AstMapping *result; /* Result pointer to return */ int nax; /* Number of Frame axes */ int unit1; /* Is new first Mapping a UnitMap? */ int unit2; /* Is new second Mapping a UnitMap? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the CmpMap. */ this = (AstCmpMap *) this_mapping; /* Invoke the astRemoveRegions method on the two component Mappings. */ newmap1 = astRemoveRegions( this->map1 ); newmap2 = astRemoveRegions( this->map2 ); /* If neither component was modified, just return a clone of the supplied pointer. */ if( this->map1 == newmap1 && this->map2 == newmap2 ) { result = astClone( this ); /* Otherwise, we need to create a new Mapping to return. */ } else { /* 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 either of these new Mappings is a Frame, replace it with an equivalent UnitMap. Also, get flags indicating if either Mapping is a UnitMap.*/ if( astIsAFrame( newmap1 ) ) { nax = astGetNin( newmap1 ); (void) astAnnul( newmap1 ); newmap1 = (AstMapping *) astUnitMap( nax, " ", status ); unit1 = 1; } else { unit1 = astIsAUnitMap( newmap1 ); } if( astIsAFrame( newmap2 ) ) { nax = astGetNin( newmap2 ); (void) astAnnul( newmap2 ); newmap2 = (AstMapping *) astUnitMap( nax, " ", status ); unit2 = 1; } else { unit2 = astIsAUnitMap( newmap2 ); } /* First handle series CmpMaps. */ if( this->series ) { /* Otherwise, if the second new Mapping is a UnitMap, return a copy of the first new Mapping (with the original Invert attribute) since the second one will have no effect. */ if( unit1 ) { result = astCopy( newmap2 ); astSetInvert( result, this->invert2 ); if( astGetInvert( this ) ) astInvert( result ); /* Otherwise, if the second new Mapping is a UnitMap, return a copy of the first new Mapping (with the original Invert attribute) since the second one will have no effect. */ } else if( unit2 ) { result = astCopy( newmap1 ); astSetInvert( result, this->invert1 ); if( astGetInvert( this ) ) astInvert( result ); /* If neither of the new Mappings is a UnitMap, return a new CmpMap containing the two new Mappings. We take a deep copy of the supplied CmpMap and then modify the Mappings os that we retain any extra information (such as invert flags) in the supplied CmpMap. */ } else { new = astCopy( this ); (void) astAnnul( new->map1 ); (void) astAnnul( new->map2 ); new->map1 = astClone( newmap1 ); new->map2 = astClone( newmap2 ); result = (AstMapping *) new; } /* Now handle parallel CmpMaps. */ } else { /* If both new Mappings are UnitMaps, return an equivalent UnitMap. */ if( unit1 && unit2 ) { result = (AstMapping *) astUnitMap( astGetNin( newmap1 ) + astGetNin( newmap2 ), " ", status ); /* Otherwise, return a new CmpMap containing the two new Mappings. */ } else { new = astCopy( this ); (void) astAnnul( new->map1 ); (void) astAnnul( new->map2 ); new->map1 = astClone( newmap1 ); new->map2 = astClone( newmap2 ); result = (AstMapping *) new; } } } /* Free resources. */ newmap1 = astAnnul( newmap1 ); newmap2 = astAnnul( newmap2 ); /* Annul the returned Mapping if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * CmpMap method (over-rides the astSimplify method inherited from * the Mapping class). * Description: * This function simplifies a CmpMap 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 Mapping. * status * Pointer to the inherited status variable. * Returned Value: * A new pointer to the (possibly simplified) 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstCmpMap *this; /* Pointer to CmpMap structure */ AstMapping **map_list; /* Mapping array pointer */ AstMapping *map; /* Pointer to cloned Mapping pointer */ AstMapping *result; /* Result pointer to return */ AstMapping *tmp; /* Temporary Mapping pointer */ int *invert_list; /* Invert array pointer */ int *mlist; /* Point to list of modified Mapping indices */ int *nlist; /* Point to list of Mapping counts */ int i; /* Loop counter for Mappings */ int improved; /* Simplification achieved? */ int invert; /* Invert attribute value */ int invert_n; /* Invert value for final Mapping */ int mlist_len; /* No. of entries in mlist */ int nlist_len; /* No. of entries in nlist */ int modified; /* Index of first modified Mapping */ int nmap; /* Mapping count */ int nominated; /* Index of nominated Mapping */ int set; /* Invert attribute set? */ int set_n; /* Invert set for final Mapping? */ int simpler; /* Simplification possible? */ int t; /* Temporary storage */ int wlen1; /* Pattern wavelength for "modified" values */ int wlen2; /* Pattern wavelength for "nmap" values */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_mapping); /* It is possible for the astSimplify method to be called recursively from within astSimplify. It is also possible that the Mapping being simplified by the current invocation is the same as the Mapping being simplified by some recursive invocation higher up the call stack. If this happens we will get into an infinite loop, since we already know that simplifying the supplied Mapping will involve (eventually) a recursive call to astSimplify with the same Mapping. To avoid this looping, we note the Mappings supplied at each depth and first compare the supplied Mapping with the Mappings which are currently being simplified higher up the call stack. If the supplied Mapping is already being simplified at a higher level, then we return immediately without doing any simplification. Otherwise, we record the supplied Mapping pointer in a static list so that it is available to subsequent recursive invocations of this function. First compare the supplied Mapping with the Mappingsbeing simpliied higher up. Return without action if a match is found. */ for( i = 0; i < simplify_depth; i++ ) { if( astEqual( this_mapping, simplify_stackmaps[ i ] ) ) { return astClone( this_mapping ); } } /* We have further work to do, so increment the recursion depth, extend the simplify_stackmaps array, and store the new Mapping in it for future use. */ simplify_depth++; simplify_stackmaps = astGrow( simplify_stackmaps, simplify_depth, sizeof( AstMapping * ) ); if( astOK ) { simplify_stackmaps[ simplify_depth - 1 ] = astClone( this_mapping ); } /* Obtain a pointer to the CmpMap structure. */ this = (AstCmpMap *) this_mapping; /* Initialise dynamic arrays of Mapping pointers and associated Invert flags. */ nmap = 0; map_list = NULL; invert_list = NULL; /* Decompose the CmpMap into a sequence of Mappings to be applied in series or parallel, as appropriate, and an associated list of Invert flags. If any inverted CmpMaps are found in the Mapping, then we can at least simplify the returned Mapping by swapping and inverting the components. Set "simpler" to indicate this. */ simpler = astMapList( this_mapping, this->series, astGetInvert( this ), &nmap, &map_list, &invert_list ); /* Each Mapping has a flag that indicates if the mapping is frozen (i.e. cannot be nominated for simplification). Mappings become frozen if nominating them would create an infinite loop in which neighbouring mappings argue as to their form. Freezing a mapping prevents the frozen mapping contributing any further to the argument, so the other Mapping "wins" the argument. Ensure no Mappings are frozen to begin with. */ for( i = 0; i < nmap; i++ ) { map_list[ i ]->flags &= ~AST__FROZEN_FLAG; } /* Initialise pointers to memory used to hold lists of the modified Mapping index and the number of mappings after each call of astMapMerge. */ mlist = NULL; nlist = NULL; /* Loop to simplify the sequence until a complete pass through it has been made without producing any improvement. */ improved = 1; while ( astOK && improved ) { improved = 0; /* Loop to nominate each Mapping in the sequence in turn. */ nominated = 0; while ( astOK && ( nominated < nmap ) ) { /* If the current nominated mapping has been frozen, then we do not allow it to suggest changes to the mapping sequence. Instead, just increment the index of the next mapping to be checked and continue on to the next pass round the while loop. */ if( map_list[ nominated ]->flags & AST__FROZEN_FLAG ) { nominated++; continue; } /* Clone a pointer to the nominated Mapping and attempt to merge it with its neighbours. Annul the cloned pointer afterwards. */ map = astClone( map_list[ nominated ] ); modified = astMapMerge( map, nominated, this->series, &nmap, &map_list, &invert_list ); map = astAnnul( map ); /* Move on to nominate the next Mapping in the sequence. */ nominated++; /* Note if any simplification occurred above. */ if( modified >= 0 && astOK ) { /* Append the index of the first modified Mapping in the list and and check that there is no repreating pattern in the list. If there is, we are probably in a loop where one mapping class is making a change, and another is undoing the change. The Looping function returns the "wavelength" of any pattern found. If a pattern was discovered, we ignore it unless there is also a pattern in the "nmap" values - the wavelengths of the two patterns must be related by a integer factor. */ wlen1 = PatternCheck( modified, 1, &mlist, &mlist_len, status ); wlen2 = PatternCheck( nmap, wlen1, &nlist, &nlist_len, status ); if( wlen1 && wlen2 ) { /* Ensure wlen2 is larger than or equal to wlen1. */ if( wlen1 > wlen2 ) { t = wlen1; wlen1 = wlen2; wlen2 = t; } /* See if wlen2 is an integer multiple of wlen1. If not, ignore the patterns. */ if( ( wlen2 % wlen1 ) != 0 ) wlen1 = 0; } /* If a repeating pattern is occurring, set the frozen flag in order to prevent the modified mapping from being modified any more. */ if( wlen1 > 0 ) { map_list[ modified ]->flags |= AST__FROZEN_FLAG; /* Otherwise, indicate we have improved the mapping and go round to test the next nominated mapping. */ } else { improved = 1; simpler = 1; /* If the simplification resulted in modification of an earlier Mapping than would normally be considered next, then go back to consider the modified one first. */ if ( modified < nominated ) nominated = modified; } } } } /* Free resources */ mlist = astFree( mlist ); nlist = astFree( nlist ); /* Construct the output Mapping. */ /* ============================= */ /* If no simplification occurred above, then simply clone a pointer to the original Mapping. */ if ( astOK ) { if ( !simpler ) { result = astClone( this ); /* Otherwise, we must construct the result from the contents of the Mapping list. */ } else { /* If the simplified Mapping list has only a single element, then the output Mapping will not be a CmpMap. In this case, we cannot necessarily set the Invert flag of the Mapping to the value we want (because we must not modify the Mapping itself. */ if ( nmap == 1 ) { /* We must make a copy. Cloning is no good (even if the Mapping already has the Invert attribute value we want), since we want the returned Mapping to be independent of the original component Mappings, so that if user code inverts a component Mapping (via some other pre-existing pointer), the returned simplified Mapping is not affected. */ result = astCopy( map_list[ 0 ] ); /* Either clear the copy's Invert attribute, or set it to 1, as required. */ if ( invert_list[ 0 ] ) { astSetInvert( result, 1 ); } else { astClearInvert( result ); } /* If the simplified Mapping sequence has more than one element, the output Mapping will be a CmpMap. In this case, we can set each individual Mapping element to have the Invert attribute value we want, so long as we return these attribute values to their original state again afterwards (once a Mapping is encapsulated inside a CmpMap, further external changes to its Invert attribute do not affect the behaviour of the CmpMap). */ } else { /* Determine if the Invert attribute for the last Mapping is set, and obtain its value. */ set_n = astTestInvert( map_list[ nmap - 1 ] ); invert_n = astGetInvert( map_list[ nmap - 1 ] ); /* Set this attribute to the value we want. */ astSetInvert( map_list[ nmap - 1 ], invert_list[ nmap - 1 ] ); /* Loop through the Mapping sequence in reverse to merge it into an equivalent CmpMap. */ for ( i = nmap - 1; i >= 0; i-- ) { /* Simply clone the pointer to the last Mapping in the sequence (which will be encountered first). */ if ( !result ) { result = astClone( map_list[ i ] ); /* For subsequent Mappings, test if the Invert attribute is set and save its value. */ } else { set = astTestInvert( map_list[ i ] ); invert = astGetInvert( map_list[ i ] ); /* Set this attribute to the value required. */ astSetInvert( map_list[ i ], invert_list[ i ] ); /* Combine the Mapping with the CmpMap formed so far and replace the result pointer with the new pointer this produces, annulling the previous pointer. */ tmp = (AstMapping *) astCmpMap( map_list[ i ], result, this->series, "", status ); (void) astAnnul( result ); result = tmp; /* Restore the Invert attribute of the Mapping to its original state. */ if ( !set ) { astClearInvert( map_list[ i ] ); } else { astSetInvert( map_list[ i ], invert ); } } } /* When all the Mappings have been merged into the CmpMap, restore the state of the Invert attribute for the final Mapping in the sequence. */ if ( !set_n ) { astClearInvert( map_list[ nmap - 1 ] ); } else { astSetInvert( map_list[ nmap - 1 ], invert_n ); } } } } /* Clean up. */ /* ========= */ /* Loop to annul all the Mapping pointers in the simplified list. */ for ( i = 0; i < nmap; i++ ) map_list[ i ] = astAnnul( map_list[ i ] ); /* Free the dynamic arrays. */ map_list = astFree( map_list ); invert_list = astFree( invert_list ); /* Decrement the recursion depth and free the pointer to the supplied Mapping currently stored at the end of the simplify_stackmaps array. */ simplify_depth--; if( astOK ) { simplify_stackmaps[ simplify_depth ] = astAnnul( simplify_stackmaps[ simplify_depth ] ); } /* If we are now at depth zero, free the simplify_stackmaps array. */ if( simplify_depth == 0 ) simplify_stackmaps = astFree( simplify_stackmaps ); /* If an error occurred, annul the returned Mapping. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a CmpMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "cmpmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * CmpMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a CmpMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Mapping. * This implies applying each of the CmpMap's component Mappings in turn, * either in series or in parallel. * Parameters: * this * Pointer to the CmpMap. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the CmpMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstCmpMap *map; /* Pointer to CmpMap to be applied */ AstPointSet *result; /* Pointer to output PointSet */ AstPointSet *temp1; /* Pointer to temporary PointSet */ AstPointSet *temp2; /* Pointer to temporary PointSet */ AstPointSet *temp; /* Pointer to temporary PointSet */ int forward1; /* Use forward direction for Mapping 1? */ int forward2; /* Use forward direction for Mapping 2? */ int ipoint1; /* Index of first point in batch */ int ipoint2; /* Index of last point in batch */ int nin1; /* No. input coordinates for Mapping 1 */ int nin2; /* No. input coordinates for Mapping 2 */ int nin; /* No. input coordinates supplied */ int nout1; /* No. output coordinates for Mapping 1 */ int nout2; /* No. output coordinates for Mapping 2 */ int nout; /* No. output coordinates supplied */ int np; /* Number of points in batch */ int npoint; /* Number of points to be transformed */ /* Local Constants: */ const int nbatch = 2048; /* Maximum points in a batch */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the CmpMap. */ map = (AstCmpMap *) this; /* Apply the parent Mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We now extend the parent astTransform method by applying the component Mappings of the CmpMap to generate the output coordinate values. */ /* Determine whether to apply the forward or inverse Mapping, according to the direction specified and whether the Mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Check if either component Mapping's inversion flag has changed since it was used to construct the CmpMap. Set a "forward" flag for each Mapping to change the direction we will use, to compensate if necessary. (Such changes may have occurred if other pointers to the component Mappings are in circulation). */ forward1 = forward; forward2 = forward; if ( map->invert1 != astGetInvert( map->map1 ) ) forward1 = !forward1; if ( map->invert2 != astGetInvert( map->map2 ) ) forward2 = !forward2; /* Determine the number of points being transformed. */ npoint = astGetNpoint( in ); /* Mappings in series. */ /* ------------------- */ /* If required, use the two component Mappings in series. To do this, we must apply one Mapping followed by the other, which means storing an intermediate result. Since this function may be invoked recursively and have to store an intermediate result on each occasion, the memory required may become excessive when transforming large numbers of points. To overcome this, we split the points up into smaller batches. */ if ( astOK ) { if ( map->series ) { /* Obtain the numbers of input and output coordinates. */ nin = astGetNcoord( in ); nout = astGetNcoord( result ); /* Loop to process all the points in batches, of maximum size nbatch points. */ for ( ipoint1 = 0; ipoint1 < npoint; ipoint1 += nbatch ) { /* Calculate the index of the final point in the batch and deduce the number of points (np) to be processed in this batch. */ ipoint2 = ipoint1 + nbatch - 1; if ( ipoint2 > npoint - 1 ) ipoint2 = npoint - 1; np = ipoint2 - ipoint1 + 1; /* Create temporary PointSets to describe the input and output points for this batch. */ temp1 = astPointSet( np, nin, "", status ); temp2 = astPointSet( np, nout, "", status ); /* Associate the required subsets of the input and output coordinates with the two PointSets. */ astSetSubPoints( in, ipoint1, 0, temp1 ); astSetSubPoints( result, ipoint1, 0, temp2 ); /* Apply the two Mappings in sequence and in the required order and direction. Store the intermediate result in a temporary PointSet (temp) which is created by the first Mapping applied. */ if ( forward ) { temp = astTransform( map->map1, temp1, forward1, NULL ); (void) astTransform( map->map2, temp, forward2, temp2 ); } else { temp = astTransform( map->map2, temp1, forward2, NULL ); (void) astTransform( map->map1, temp, forward1, temp2 ); } /* Delete the temporary PointSets after processing each batch of points. */ temp = astDelete( temp ); temp1 = astDelete( temp1 ); temp2 = astDelete( temp2 ); /* Quit processing batches if an error occurs. */ if ( !astOK ) break; } /* Mappings in parallel. */ /* --------------------- */ /* If required, use the two component Mappings in parallel. Since we do not need to allocate any memory to hold intermediate coordinate values here, there is no need to process the points in batches. */ } else { /* Get the effective number of input and output coordinates per point for each Mapping (taking account of the direction in which each will be used to transform points). */ nin1 = forward1 ? astGetNin( map->map1 ) : astGetNout( map->map1 ); nout1 = forward1 ? astGetNout( map->map1 ) : astGetNin( map->map1 ); nin2 = forward2 ? astGetNin( map->map2 ) : astGetNout( map->map2 ); nout2 = forward2 ? astGetNout( map->map2 ) : astGetNin( map->map2 ); /* Create temporary PointSets to describe the input and output coordinates for the first Mapping. */ temp1 = astPointSet( npoint, nin1, "", status ); temp2 = astPointSet( npoint, nout1, "", status ); /* Associate the required subsets of the input and output coordinates with these PointSets. */ astSetSubPoints( in, 0, 0, temp1 ); astSetSubPoints( result, 0, 0, temp2 ); /* Use the astTransform method to apply the coordinate transformation described by the first Mapping. */ (void) astTransform( map->map1, temp1, forward1, temp2 ); /* Delete the temporary PointSets. */ temp1 = astDelete( temp1 ); temp2 = astDelete( temp2 ); /* Create a new pair of temporary PointSets to describe the input and output coordinates for the second Mapping, and associate the required subsets of the input and output coordinates with these PointSets. */ temp1 = astPointSet( npoint, nin2, "", status ); temp2 = astPointSet( npoint, nout2, "", status ); astSetSubPoints( in, 0, nin1, temp1 ); astSetSubPoints( result, 0, nout1, temp2 ); /* Apply the coordinate transformation described by the second Mapping. */ (void) astTransform( map->map2, temp1, forward2, temp2 ); /* Delete the two temporary PointSets. */ temp1 = astDelete( temp1 ); temp2 = astDelete( temp2 ); } } /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for CmpMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for CmpMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Mappings within the CmpMap. */ /* Local Variables: */ AstCmpMap *in; /* Pointer to input CmpMap */ AstCmpMap *out; /* Pointer to output CmpMap */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output CmpMaps. */ in = (AstCmpMap *) objin; out = (AstCmpMap *) objout; /* For safety, start by clearing any references to the input component Mappings from the output CmpMap. */ out->map1 = NULL; out->map2 = NULL; /* Make copies of these Mappings and store pointers to them in the output CmpMap structure. */ out->map1 = astCopy( in->map1 ); out->map2 = astCopy( in->map2 ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for CmpMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for CmpMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstCmpMap *this; /* Pointer to CmpMap */ /* Obtain a pointer to the CmpMap structure. */ this = (AstCmpMap *) obj; /* Annul the pointers to the component Mappings. */ this->map1 = astAnnul( this->map1 ); this->map2 = astAnnul( this->map2 ); /* Clear the remaining CmpMap variables. */ this->invert1 = 0; this->invert2 = 0; this->series = 0; } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for CmpMap 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 CmpMap class to an output Channel. * Parameters: * this * Pointer to the CmpMap 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 Variables: */ AstCmpMap *this; /* Pointer to the CmpMap structure */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the CmpMap structure. */ this = (AstCmpMap *) this_object; /* Write out values representing the instance variables for the CmpMap 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. */ /* Series. */ /* ------- */ ival = this->series; set = ( ival == 0 ); astWriteInt( channel, "Series", set, 0, ival, ival ? "Component Mappings applied in series" : "Component Mappings applied in parallel" ); /* First Invert flag. */ /* ------------------ */ ival = this->invert1; set = ( ival != 0 ); astWriteInt( channel, "InvA", set, 0, ival, ival ? "First Mapping used in inverse direction" : "First Mapping used in forward direction" ); /* Second Invert flag. */ /* ------------------- */ ival = this->invert2; set = ( ival != 0 ); astWriteInt( channel, "InvB", set, 0, ival, ival ? "Second Mapping used in inverse direction" : "Second Mapping used in forward direction" ); /* First Mapping. */ /* -------------- */ astWriteObject( channel, "MapA", 1, 1, this->map1, "First component Mapping" ); /* Second Mapping. */ /* --------------- */ astWriteObject( channel, "MapB", 1, 1, this->map2, "Second component Mapping" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsACmpMap and astCheckCmpMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(CmpMap,Mapping) astMAKE_CHECK(CmpMap) AstCmpMap *astCmpMap_( void *map1_void, void *map2_void, int series, const char *options, int *status, ...) { /* *+ * Name: * astCmpMap * Purpose: * Create a CmpMap. * Type: * Protected function. * Synopsis: * #include "cmpmap.h" * AstCmpMap *astCmpMap( AstMapping *map1, AstMapping *map2, int series, * const char *options, ... ) * Class Membership: * CmpMap constructor. * Description: * This function creates a new CmpMap and optionally initialises its * attributes. * Parameters: * map1 * Pointer to the first Mapping. * map2 * Pointer to the second Mapping. * series * If a non-zero value is given, the two Mappings will be connected * together in series. A zero value requests that they be connected in * parallel. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new CmpMap. The syntax used is the same as for the * astSet method and may include "printf" format specifiers identified * by "%" symbols in the normal way. * ... * 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 CmpMap. * 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 CmpMap constructor which is * available via the protected interface to the CmpMap class. A * public interface is provided by the astCmpMapId_ 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 * "map1" and "map2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstCmpMap *new; /* Pointer to new CmpMap */ AstMapping *map1; /* Pointer to first Mapping structure */ AstMapping *map2; /* Pointer to second Mapping structure */ 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 pointers to the Mapping structures provided. */ map1 = astCheckMapping( map1_void ); map2 = astCheckMapping( map2_void ); if ( astOK ) { /* Initialise the CmpMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitCmpMap( NULL, sizeof( AstCmpMap ), !class_init, &class_vtab, "CmpMap", map1, map2, series ); /* 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 CmpMap'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 CmpMap. */ return new; } AstCmpMap *astCmpMapId_( void *map1_void, void *map2_void, int series, const char *options, ... ) { /* *++ * Name: c astCmpMap f AST_CMPMAP * Purpose: * Create a CmpMap. * Type: * Public function. * Synopsis: c #include "cmpmap.h" c AstCmpMap *astCmpMap( AstMapping *map1, AstMapping *map2, int series, c const char *options, ... ) f RESULT = AST_CMPMAP( MAP1, MAP2, SERIES, OPTIONS, STATUS ) * Class Membership: * CmpMap constructor. * Description: * This function creates a new CmpMap and optionally initialises * its attributes. * * A CmpMap is a compound Mapping which allows two component * Mappings (of any class) to be connected together to form a more * complex Mapping. This connection may either be "in series" * (where the first Mapping is used to transform the coordinates of * each point and the second mapping is then applied to the * result), or "in parallel" (where one Mapping transforms the * earlier coordinates for each point and the second Mapping * simultaneously transforms the later coordinates). * * Since a CmpMap is itself a Mapping, it can be used as a * component in forming further CmpMaps. Mappings of arbitrary * complexity may be built from simple individual Mappings in this * way. * Parameters: c map1 f MAP1 = INTEGER (Given) * Pointer to the first component Mapping. c map2 f MAP2 = INTEGER (Given) * Pointer to the second component Mapping. c series f SERIES = LOGICAL (Given) c If a non-zero value is given for this parameter, the two c component Mappings will be connected in series. A zero c value requests that they are connected in parallel. f If a .TRUE. value is given for this argument, the two f component Mappings will be connected in series. A f .FALSE. value requests that they are connected in parallel. 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 CmpMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new CmpMap. The syntax used is identical to that for the f AST_SET routine. 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 astCmpMap() f AST_CMPMAP = INTEGER * A pointer to the new CmpMap. * Notes: * - If the component Mappings are connected in series, then using * the resulting CmpMap to transform coordinates will cause the * first Mapping to be applied, followed by the second Mapping. If * the inverse CmpMap transformation is requested, the two * component Mappings will be applied in both the reverse order and * the reverse direction. * - When connecting two component Mappings in series, the number * of output coordinates generated by the first Mapping (its Nout * attribute) must equal the number of input coordinates accepted * by the second Mapping (its Nin attribute). * - If the component Mappings of a CmpMap are connected in * parallel, then the first Mapping will be used to transform the * earlier input coordinates for each point (and to produce the * earlier output coordinates) and the second Mapping will be used * simultaneously to transform the remaining input coordinates (to * produce the remaining output coordinates for each point). If the * inverse transformation is requested, each Mapping will still be * applied to the same coordinates, but in the reverse direction. * - When connecting two component Mappings in parallel, there is * no restriction on the number of input and output coordinates for * each Mapping. c - Note that the component Mappings supplied are not copied by c astCmpMap (the new CmpMap simply retains a reference to c them). They may continue to be used for other purposes, but c should not be deleted. If a CmpMap containing a copy of its c component Mappings is required, then a copy of the CmpMap should c be made using astCopy. f - Note that the component Mappings supplied are not copied by f AST_CMPMAP (the new CmpMap simply retains a reference to f them). They may continue to be used for other purposes, but f should not be deleted. If a CmpMap containing a copy of its f component Mappings is required, then a copy of the CmpMap should f be made using AST_COPY. * - 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 astCmpMap constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astCmpMap_ 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 "map1" and "map2" parameters * are of type (void *) and are converted from an ID value to a * pointer and validated within the function itself. * - The variable argument list also prevents this function from * invoking astCmpMap_ 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 */ AstCmpMap *new; /* Pointer to new CmpMap */ AstMapping *map1; /* Pointer to first Mapping structure */ AstMapping *map2; /* Pointer to second Mapping structure */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ new = NULL; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return new; /* Obtain the Mapping pointers from the ID's supplied and validate the pointers to ensure they identify valid Mappings. */ map1 = astVerifyMapping( astMakePointer( map1_void ) ); map2 = astVerifyMapping( astMakePointer( map2_void ) ); if ( astOK ) { /* Initialise the CmpMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitCmpMap( NULL, sizeof( AstCmpMap ), !class_init, &class_vtab, "CmpMap", map1, map2, series ); /* 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 CmpMap'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 CmpMap. */ return astMakeId( new ); } AstCmpMap *astInitCmpMap_( void *mem, size_t size, int init, AstCmpMapVtab *vtab, const char *name, AstMapping *map1, AstMapping *map2, int series, int *status ) { /* *+ * Name: * astInitCmpMap * Purpose: * Initialise a CmpMap. * Type: * Protected function. * Synopsis: * #include "cmpmap.h" * AstCmpMap *astInitCmpMap( void *mem, size_t size, int init, * AstCmpMapVtab *vtab, const char *name, * AstMapping *map1, AstMapping *map2, * int series ) * Class Membership: * CmpMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new CmpMap object. It allocates memory (if necessary) to * accommodate the CmpMap plus any additional data associated with the * derived class. It then initialises a CmpMap 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 CmpMap at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the CmpMap is to be initialised. * This must be of sufficient size to accommodate the CmpMap data * (sizeof(CmpMap)) 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 CmpMap (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 * CmpMap structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the CmpMap'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 CmpMap. * 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 Object * astClass function). * map1 * Pointer to the first Mapping. * map2 * Pointer to the second Mapping. * series * If a non-zero value is given, the two Mappings will be connected * together in series. A zero value requests that they be connected in * parallel. * Returned Value: * A pointer to the new CmpMap. * 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: */ AstCmpMap *new; /* Pointer to new CmpMap */ int map_f; /* Forward transformation defined? */ int map_i; /* Inverse transformation defined? */ int nin2; /* No. input coordinates for Mapping 2 */ int nin; /* No. input coordinates for CmpMap */ int nout1; /* No. output coordinates for Mapping 1 */ int nout; /* No. output coordinates for CmpMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitCmpMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Determine in which directions each component Mapping is able to transform coordinates. Combine these results to obtain a result for the overall CmpMap. */ map_f = astGetTranForward( map1 ) && astGetTranForward( map2 ); map_i = astGetTranInverse( map1 ) && astGetTranInverse( map2 ); if ( astOK ) { /* If connecting the Mappings in series, check that the number of coordinates are compatible and report an error if they are not. */ if ( series ) { nout1 = astGetNout( map1 ); nin2 = astGetNin( map2 ); if ( astOK && ( nout1 != nin2 ) ) { astError( AST__INNCO, "astInitCmpMap(%s): The number of output " "coordinates per point (%d) for the first Mapping " "supplied does not match the number of input " "coordinates (%d) for the second Mapping.", status, name, nout1, nin2 ); } } } /* If OK, determine the total number of input and output coordinates per point for the CmpMap. */ if ( astOK ) { if ( series ) { nin = astGetNin( map1 ); nout = astGetNout( map2 ); } else { nin = astGetNin( map1 ) + astGetNin( map2 ); nout = astGetNout( map1 ) + astGetNout( map2 ); } } else { nin = 0; nout = 0; } /* Initialise a Mapping structure (the parent class) as the first component within the CmpMap structure, allocating memory if necessary. Specify the number of input and output coordinates and in which directions the Mapping should be defined. */ if ( astOK ) { new = (AstCmpMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, map_f, map_i ); if ( astOK ) { /* Initialise the CmpMap data. */ /* --------------------------- */ /* Store pointers to the component Mappings. Extract Mappings if FrameSets are provided. */ if( astIsAFrameSet( map1 ) ) { new->map1 = astGetMapping( (AstFrameSet *) map1, AST__BASE, AST__CURRENT ); } else { new->map1 = astClone( map1 ); } if( astIsAFrameSet( map2 ) ) { new->map2 = astGetMapping( (AstFrameSet *) map2, AST__BASE, AST__CURRENT ); } else { new->map2 = astClone( map2 ); } /* Save the initial values of the inversion flags for these Mappings. */ new->invert1 = astGetInvert( new->map1 ); new->invert2 = astGetInvert( new->map2 ); /* Note whether the Mappings are joined in series (instead of in parallel), constraining this flag to be 0 or 1. */ new->series = ( series != 0 ); /* If an error occurred, clean up by annulling the Mapping pointers and deleting the new object. */ if ( !astOK ) { new->map1 = astAnnul( new->map1 ); new->map2 = astAnnul( new->map2 ); new = astDelete( new ); } } } /* Return a pointer to the new object. */ return new; } AstCmpMap *astLoadCmpMap_( void *mem, size_t size, AstCmpMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadCmpMap * Purpose: * Load a CmpMap. * Type: * Protected function. * Synopsis: * #include "cmpmap.h" * AstCmpMap *astLoadCmpMap( void *mem, size_t size, * AstCmpMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * CmpMap loader. * Description: * This function is provided to load a new CmpMap 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 * CmpMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a CmpMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the CmpMap is to be * loaded. This must be of sufficient size to accommodate the * CmpMap data (sizeof(CmpMap)) 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 CmpMap (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 CmpMap 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(AstCmpMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new CmpMap. If this is NULL, a pointer to * the (static) virtual function table for the CmpMap 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 "CmpMap" is used instead. * Returned Value: * A pointer to the new CmpMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstCmpMap *new; /* Pointer to the new CmpMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this CmpMap. In this case the CmpMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstCmpMap ); vtab = &class_vtab; name = "CmpMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitCmpMapVtab( 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 CmpMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "CmpMap" ); /* 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. */ /* Series. */ /* ------- */ new->series = astReadInt( channel, "series", 1 ); new->series = ( new->series != 0 ); /* First Invert flag. */ /* ------------------ */ new->invert1 = astReadInt( channel, "inva", 0 ); new->invert1 = ( new->invert1 != 0 ); /* Second Invert flag. */ /* ------------------- */ new->invert2 = astReadInt( channel, "invb", 0 ); new->invert2 = ( new->invert2 != 0 ); /* First Mapping. */ /* -------------- */ new->map1 = astReadObject( channel, "mapa", NULL ); /* Second Mapping. */ /* --------------- */ new->map2 = astReadObject( channel, "mapb", NULL ); /* If an error occurred, clean up by deleting the new CmpMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new CmpMap pointer. */ return new; } /* 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. */ /* None. */ ast-8.3.0/c2f77.h0000664000175000017500000001166313004147321010237 00000000000000#if !defined( C2F77_INCLUDED ) /* Include this file only once */ #define C2F77_INCLUDED /* *+ * Name: * c2f77.h * Purpose: * Define the interface to the c2f77 module. * Description: * This file defines language-specific functions which support the * FORTRAN 77 interface to the AST library. * * Note that this module is not a class implementation, although it * resembles one. * Functions Defined: * Public: * None. * * Protected: * astStringExport * Export a C string to a FORTRAN string. * Macros Defined: * Public: * None. * * Protected: * astWatchSTATUS * Execute C code while watching a FORTRAN STATUS variable. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 15-NOV-1996 (RFWS): * Original version. * 16-JUL-1997 (RFWS): * Added astWatchSTATUS. * 13-JUN-2001 (DSB): * Make astStringExport available to F77 interface modules as well * as AST classes. *- */ /* Macros. */ /* ======= */ /* *+ * Name: * astWatchSTATUS * Type: * Protected macro. * Purpose: * Execute C code while watching a FORTRAN STATUS variable. * Synopsis: * #include "c2f77.h" * astWatchSTATUS(code) * Description: * This macro expands to code which executes the C code supplied * via the "code" argument in a new C scope (delimited by * {...}). The code supplied executes while the AST error status is * equated to a variable called STATUS, which is an error status * argument passed from a FORTRAN routine using the macros defined * in the "f77.h" include file. * * The effect of this is roughly as if the astWatch function had * been used to locally declare the FORTRAN STATUS argument as a * new AST error status variable, except that this macro also works * if STATUS is not an int. * Parameters: * code * The C code to be executed. * Examples: * F77_SUBROUTINE(ast_doit)( INTEGER(STATUS) ) { * astWatchSTATUS( * astDoit(); * ) * } * Causes the astDoit function to be invoked as if the AST error * status were equated to the STATUS argument passed from * FORTRAN. Typically, if STATUS is set to an error value, * astDoit would detect this by means of the astOK macro and * would not then execute. If an error occurs in astDoit, * causing the AST error status to be set, then that value is * transferred to STATUS after the C code has executed (i.e. at * the end of the astWatchSTATUS macro). * Notes: * - The FORTRAN argument must be called STATUS and must appear in * the C function's parameter list as an argument of the INTEGER() * macro defined in the "f77.h" include file. * - The C code supplied executes in a new scope, in which * automatic variables may be declared. However, such variables * will not exist after the macro's expansion has been executed. * - The AST error status variable and its value remain unchanged * after the expansion of this macro has executed. *- */ /* Define the macro. */ #define astWatchSTATUS(code) \ \ /* Begin a new C scope. */ \ { \ \ /* Ensure that a pointer to the STATUS argument exists. */ \ GENPTR_INTEGER(STATUS) \ \ /* Store the STATUS value in a local int. */ \ int ast_local_status = *STATUS; \ int *status = &ast_local_status; \ \ /* Make this int the AST error status variable, saving the address of \ the previous variable. */ \ int *ast_previous_status = astWatch( &ast_local_status ); \ \ /* Execute the code supplied using the new error status variable. */ \ code \ \ /* Restore the original error status variable. */ \ (void) astWatch( ast_previous_status ); \ \ /* Return the final error status to STATUS. */ \ *STATUS = ast_local_status; \ } /* Function prototypes. */ /* ==================== */ void astStringExport_( const char *, char *, int ); /* Function interfaces. */ /* ==================== */ /* These wrap up the functions defined by this module to make them easier to use. */ #define astStringExport astStringExport_ #endif ast-8.3.0/fdssmap.c0000664000175000017500000000456213004147321011037 00000000000000/* *+ * Name: * fdssmap.c * Purpose: * Define a FORTRAN 77 interface to the AST DssMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the DssMap class. * Routines Defined: * AST_ISADSSMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink) * History: * 19-FEB-1997 (DSB): * Original version. * 5-SEP-1997 (RFWS) * Removed the AST_DSSMAP function (now protected, so not * required in the Fortran interface). */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "dssmap.h" /* C interface to the DssMap class */ F77_LOGICAL_FUNCTION(ast_isadssmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISADSSMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsADssMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } ast-8.3.0/matrixmap.c0000664000175000017500000057075613004147321011421 00000000000000/* *class++ * Name: * MatrixMap * Purpose: * Map coordinates by multiplying by a matrix. * Constructor Function: c astMatrixMap f AST_MATRIXMAP * Description: * A MatrixMap is form of Mapping which performs a general linear * transformation. Each set of input coordinates, regarded as a * column-vector, are pre-multiplied by a matrix (whose elements * are specified when the MatrixMap is created) to give a new * column-vector containing the output coordinates. If appropriate, * the inverse transformation may also be performed. * Inheritance: * The MatrixMap class inherits from the Mapping class. * Attributes: * The MatrixMap class does not define any new attributes beyond * those which are applicable to all Mappings. * Functions: c The MatrixMap class does not define any new functions beyond those f The MatrixMap class does not define any new routines beyond those * which are applicable to all Mappings. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink) * History: * 9-FEB-1996 (DSB): * Original version. * 13-NOV-1996 (DSB): * Updated to support attributes, I/O and an external interface. * 3-JUN-1997 (DSB): * astMtrMult and astMtrRot made protected instead of public. * 16-JUN-1997 (RFWS): * Tidied public prologues. * 24-JUN-1997 (DSB): * Zero returned for coordinates which are indeterminate as a * result of using an inverted, non-square, diagonal matrix. * 10-OCT-1997 (DSB): * o The inverse matrix is no longer dumped by the Dump function. * Instead, it is re-calculated by the Load function. * o The description of argument "form" in astMatrixMap corrected * to indicate that a value of 2 produces a unit matrix. * o String values used to represent choices externally, instead * of integers. * 24-NOV-1997 (DSB): * Use of error code AST__OPT replaced by AST__RDERR. * 28-JAN-1998 (DSB): * Bug fix in astMtrMult: the matrix (forward or inverse) used for * the "a" MatrixMap was determined by the Invert flag of the other * ("this") MatrixMap. * 14-APR-1998 (DSB): * Bug fix in Dump. Previously, matrix elements with value AST__BAD * were explicitly written out. Now they are not written out, since * AST__BAD can have different values on different machines. Missing * elements default to AST__BAD when read back in using astLoadMatrixMap. * 20-APR-1998 (DSB): * Bug fix in astLoadMatrixMap: initialise the pointer to the inverse * matrix array to NULL if no inverse matrix is needed. * 25-AUG-1998 (DSB): * - Transform changed so that bad input axis values are not * propagated to output axes which are independant of the input axis. * - CompressMatrix changed to allow a tolerance of DBL_EPSILON when * determining if a matrix is a unit matrix, or a diagonal matrix. * - MapMerge changed to allow MatrixMaps to swap with PermMaps * in order to move the MatrixMap closer to a Mapping with which it * could merge. * 22-FEB-1999 (DSB): * Changed logic of MapMerge to avoid infinite looping. * 5-MAY-1999 (DSB): * More corrections to MapMerge: Cleared up errors in the use of the * supplied invert flags, and corrected logic for deciding which * neighbouring Mapping to swap with. * 16-JUL-1999 (DSB): * Fixed memory leaks in MatWin and MapMerge. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitatrixMapVtab * method. * 11-SEP-2003 (DSB): * Increased tolerance on checks for unit matrices within * CompressMatrix. Now uses sqrt(DBL_EPSILON)*diag (previously was * DBL_EPSILON*DIAG ). * 10-NOV-2003 (DSB): * Modified functions which swap a MatrixMap with another Mapping * (e.g. MatSwapPerm, etc), to simplify the returned Mappings. * 13-JAN-2003 (DSB): * Modified the tolerance used by CompressMatrix when checking for * zero matrix elements. Old system compared each element to thre * size of the diagonal, but different scalings on different axes could * cause this to trat as zero values which should nto be treated as * zero. * 23-APR-2004 (DSB): * Changes to simplification algorithm. * 8-JUL-2004 (DSB): * astMtrMult - Report an error if either MatrixMap does not have a * defined forward transformation. * 1-SEP-2004 (DSB): * Ensure do1 and do2 are initialised before use in MapMerge. * 7-SEP-2005 (DSB): * Take account of the Invert flag when using the zoom factor from * a ZoomMap. * 14-FEB-2006 (DSB): * Correct row/col confusion in CompressMatrix. * 15-MAR-2006 (DSB): * Override astEqual. * 15-MAR-2009 (DSB): * MapSplit: Only create the returned Mapping if it would have some * outputs. Also, do not create the returned Mapping if any output * depends on a mixture of selected and unselected inputs. * 16-JUL-2009 (DSB): * MatPerm: Fix memory leak (mm2 was not being annulled). * 2-OCT-2012 (DSB): * - Check for Infs as well as NaNs. * - In MapSplit do not split the MatrixMap if the resulting * matrix would contain only bad elements. * - Report an error if an attempt is made to create a MatrixMap * containing only bad elements. * 4-NOV-2013 (DSB): * Allow a full form MatrixMap to be simplified to a diagonal form * MatrixMap if all the off-diagonal values are zero. * 23-APR-2015 (DSB): * Improve MapMerge. If a MatrixMap can merge with its next-but-one * neighbour, then swap the MatrixMap with its neighbour, so that * it is then next its next-but-one neighbour, and then merge the * two Mappings into a single Mapping. Previously, only the swap * was performed - not the merger. And the swap was only performed * if the intervening neighbour could not itself merge. This could * result in an infinite simplification loop, which was detected by * CmpMap and and aborted, resulting in no useful simplification. *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 MatrixMap /* Define identifiers for the different forms of matrix storage. */ #define FULL 0 #define DIAGONAL 1 #define UNIT 2 /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "matrixmap.h" /* Interface definition for this class */ #include "pal.h" /* SLALIB function definitions */ #include "permmap.h" #include "zoommap.h" #include "unitmap.h" #include "winmap.h" /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; static const char *Form[3] = { "Full", "Diagonal", "Unit" }; /* Text values used to represent storage form externally */ /* Pointers to parent class methods which are extended by this class. */ static AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int *(* parent_mapsplit)( AstMapping *, int, const int *, AstMapping **, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(MatrixMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(MatrixMap,Class_Init) #define class_vtab astGLOBAL(MatrixMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstMatrixMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstMatrixMap *astMatrixMapId_( int, int, int, const double [], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMatrixMap *MatMat( AstMapping *, AstMapping *, int, int, int * ); static AstMatrixMap *MatPerm( AstMatrixMap *, AstPermMap *, int, int, int, int * ); static AstMatrixMap *MatZoom( AstMatrixMap *, AstZoomMap *, int, int, int * ); static AstMatrixMap *MtrMult( AstMatrixMap *, AstMatrixMap *, int * ); static AstMatrixMap *MtrRot( AstMatrixMap *, double, const double[], int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double *InvertMatrix( int, int, int, double *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int Equal( AstObject *, AstObject *, int * ); static int FindString( int, const char *[], const char *, const char *, const char *, const char *, int * ); static int Ustrcmp( const char *, const char *, int * ); static int GetTranForward( AstMapping *, int * ); static int GetIsLinear( AstMapping *, int * ); static int GetTranInverse( AstMapping *, int * ); static int CanSwap( AstMapping *, AstMapping *, int, int, int *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int PermOK( AstMapping *, int * ); static int ScalingRowCol( AstMatrixMap *, int, int * ); static void CompressMatrix( AstMatrixMap *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *obj, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void ExpandMatrix( AstMatrixMap *, int * ); static void MatWin( AstMapping **, int *, int, int * ); static void MatPermSwap( AstMapping **, int *, int, int * ); static void PermGet( AstPermMap *, int **, int **, double **, int * ); static void SMtrMult( int, int, int, const double *, double *, double*, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); /* Member functions. */ /* ================= */ static int CanSwap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *simpler, int *status ){ /* * Name: * CanSwap * Purpose: * Determine if two Mappings could be swapped. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int CanSwap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, * int *simpler, int *status ) * Class Membership: * MatrixMap member function * Description: * This function returns a flag indicating if the pair of supplied * Mappings could be replaced by an equivalent pair of Mappings from the * same classes as the supplied pair, but in reversed order. Each pair * of Mappings is considered to be compunded in series. The supplied * Mapings are not changed in any way. * Parameters: * map1 * The Mapping to be applied first. * map2 * The Mapping to be applied second. * inv1 * The invert flag to use with map1. A value of zero causes the forward * mapping to be used, and a non-zero value causes the inverse * mapping to be used. * inv2 * The invert flag to use with map2. * simpler * Addresss of a location at which to return a flag indicating if * the swapped Mappings would be intrinsically simpler than the * original Mappings. * status * Pointer to the inherited status variable. * Returned Value: * 1 if the Mappings could be swapped, 0 otherwise. * Notes: * - One of the supplied pair of Mappings must be a MatrixMap. * - A value of 0 is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstMatrixMap *mat; /* Pointer to MatrixMap Mapping */ AstMapping *nomat; /* Pointer to non-MatrixMap Mapping */ const char *class1; /* Pointer to map1 class string */ const char *class2; /* Pointer to map2 class string */ const char *nomat_class; /* Pointer to non-MatrixMap class string */ double *consts; /* Pointer to constants array */ int *inperm; /* Pointer to input axis permutation array */ int *outperm; /* Pointer to output axis permutation array */ int i; /* Loop count */ int invert[ 2 ]; /* Original invert flags */ int nax; /* No. of in/out coordinates for the MatrixMap */ int nin; /* No. of input coordinates for the PermMap */ int nout; /* No. of output coordinates for the PermMap */ int ret; /* Returned flag */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise */ ret = 0; *simpler = 0; /* Temporarily set the Invert attributes of both Mappings to the supplied values. */ invert[ 0 ] = astGetInvert( map1 ); astSetInvert( map1, inv1 ); invert[ 1 ] = astGetInvert( map2 ); astSetInvert( map2, inv2 ); /* Get the classes of the two mappings. */ class1 = astGetClass( map1 ); class2 = astGetClass( map2 ); if( astOK ){ /* Get a pointer to the MatrixMap and non-MatrixMap Mappings. */ if( !strcmp( class1, "MatrixMap" ) ){ mat = (AstMatrixMap *) map1; nomat = map2; nomat_class = class2; } else { nomat = map1; mat = (AstMatrixMap *) map2; nomat_class = class1; } /* Get the number of input axes for the MatrixMap. */ nax = astGetNin( mat ); /* If it is a WinMap, the Mappings can be swapped. */ if( !strcmp( nomat_class, "WinMap" ) ){ ret = 1; /* If it is a PermMap, the Mappings can be swapped so long as: 1) all links between input and output axes in the PermMap are bi-directional. This does not preclude the existence of unconnected axes, which do not have links (bi-directional or otherwise). 2) The MatrixMap is square, and invertable. 3) If the permMap is applied first, then each output of the PermMap which is assigned a constant value must correspond to a "scaling" row and column in the MatrixMap. I.e. if PermMap output axis "i" is assigned a constant value, then row i and column i of the following MatrixMap must contain only zeros, EXCEPT for the diagonal term (row i, column i) which must be non-zero. If the Mappings are in the other order, then the same applies to PermMap input axes assigned a constant value. */ /* Check the other Mapping is a PermMap, and that the MatrixMap is square and has an inverse. */ } else if( !strcmp( nomat_class, "PermMap" ) && nax == astGetNout( mat ) && ( mat->form == UNIT || ( mat->i_matrix != NULL && mat->f_matrix != NULL ) ) ) { /* Get the number of input and output coordinates for the PermMap. */ nin = astGetNin( nomat ); nout = astGetNout( nomat ); /* We need to know the axis permutation arrays and constants array for the PermMap. */ PermGet( (AstPermMap *) nomat, &outperm, &inperm, &consts, status ); if( astOK ) { /* Indicate we can swap with the PermMap. */ ret = 1; /* Check each output axis. If any links between axes are found which are not bi-directional, indicate that we cannot swap with the PermMap. */ for( i = 0; i < nout; i++ ){ if( outperm[ i ] >= 0 && outperm[ i ] < nin ) { if( inperm[ outperm[ i ] ] != i ) { ret = 0; break; } } } /* Check each input axis. If any links between axes are found which are not bi-directional, indicate that we cannot swap with the PermMap. */ for( i = 0; i < nin; i++ ){ if( inperm[ i ] >= 0 && inperm[ i ] < nout ) { if( outperm[ inperm[ i ] ] != i ) { ret = 0; break; } } } /* If the PermMap is suitable, check that any constant values fed from the PermMap into the MatrixMap (in either forward or inverse direction) are not changed by the MatrixMap. This requires the row and column for each constant axis to be zeros, ecept for a value of 1.0 on the diagonal. First deal with the cases where the PermMap is applied first, so the outputs of the PermMap are fed into the MatrixMap in the forward direction. */ if( ret && ( nomat == map1 ) ) { if( nout != nax ){ astError( AST__RDERR, "PermMap produces %d outputs, but the following" "MatrixMap has %d inputs\n", status, nout, nax ); ret = 0; } /* Consider each output axis of the PermMap. */ for( i = 0; i < nout && astOK ; i++ ) { /* If this PermMap output is assigned a constant... */ if( outperm[ i ] < 0 || outperm[ i ] >= nin ) { /* Check the i'th row of the MatrixMap is all zero except for the i'th column which must be non-zero. If not indicate that the MatrixMap cannot swap with the PermMap and leave the loop. */ if( !ScalingRowCol( mat, i, status ) ) { ret = 0; break; } } } } /* Now deal with the cases where the PermMap is applied second, so the inputs of the PermMap are fed into the MatrixMap in the inverse direction. */ if( ret && ( nomat == map2 ) ) { if( nin != nax ){ astError( AST__RDERR, "Inverse PermMap produces %d inputs, but the " "preceding MatrixMap has %d outputs\n", status, nin, nax ); ret = 0; } /* Consider each input axis of the PermMap. */ for( i = 0; i < nin && astOK; i++ ){ /* If this PermMap input is assigned a constant (by the inverse Mapping)... */ if( inperm[ i ] < 0 || inperm[ i ] >= nout ) { /* Check the i'th row of the MatrixMap is all zero except for the i'th column which must be non-zero. If not indicate that the MatrixMap cannot swap with the PermMap and leave the loop. */ if( !ScalingRowCol( mat, i, status ) ) { ret = 0; break; } } } } /* If we can swap with the PermMap, the swapped Mappings may be intrinsically simpler than the original mappings. */ if( ret ) { /* If the PermMap precedes the WinMap, this will be the case if the PermMap has more outputs than inputs. If the WinMap precedes the PermMap, this will be the case if the PermMap has more inputs than outputs. */ *simpler = ( nomat == map1 ) ? nout > nin : nin > nout; } /* Free the axis permutation and constants arrays. */ outperm = (int *) astFree( (void *) outperm ); inperm = (int *) astFree( (void *) inperm ); consts = (double *) astFree( (void *) consts ); } } } /* Re-instate the original settings of the Invert attributes for the supplied MatrixMaps. */ astSetInvert( map1, invert[ 0 ] ); astSetInvert( map2, invert[ 1 ] ); /* Return the answer. */ return astOK ? ret : 0; } static void CompressMatrix( AstMatrixMap *this, int *status ){ /* * Name: * CompressMatrix * Purpose: * If possible, reduce the amount of storage needed to store a MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void CompressMatrix( AstMatrixMap *this, int *status ) * Class Membership: * MatrixMap member function. * Description: * The supplid MatrixMap is converted to its most compressed form * (i.e no element values if it is a unit matrix, diagonal elements only * if it is a diagonal matrix, or all elements otherwise). * Parameters: * this * A pointer to the MatrixMap to be compressed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double *a; /* Pointer to next element */ double *colmax; /* Pointer to array holding column max values */ double *fmat; /* Pointer to compressed forward matrix */ double *rowmax; /* Pointer to array holding row max values */ double mval; /* Matrix element value */ int i; /* Loop count */ int j; /* Loop count */ int k; /* Loop count */ int ncol; /* No. of columns in forward matrix */ int ndiag; /* No. of diagonal elements in matrix */ int new_form; /* Compressed storage form */ int new_inv; /* New inverse requied? */ int next_diag; /* Index of next diagonal element */ int nrow; /* No. of rows in forward matrix */ /* Check the global error status. */ if ( !astOK || !this ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ new_inv = 0; /* Get the dimensions of the forward matrix. */ if( astGetInvert( this ) ){ nrow = astGetNin( this ); ncol = astGetNout( this ); } else { ncol = astGetNin( this ); nrow = astGetNout( this ); } /* Store the number of diagonal elements in the matrix. This is the minimum of the number of rows and columns. */ if( ncol < nrow ){ ndiag = ncol; } else { ndiag = nrow; } /* If the MatrixMap is already stored in UNIT form, it cannot be compressed any further. */ if( this->form == UNIT){ return; /* Otherwise, if the MatrixMap is stored in DIAGONAL form, it could be compressed into a UNIT MatrixMap if all the supplied element values are one. */ } else if( this->form == DIAGONAL ){ new_form = UNIT; for( i = 0; i < ndiag; i++ ){ if( !astEQUAL( (this->f_matrix)[ i ], 1.0 ) ){ new_form = DIAGONAL; break; } } /* If it can be compressed, change the storage form and free the arrays holding the diagonal element values. */ if( new_form == UNIT ) { this->f_matrix = (double *) astFree( (void *)( this->f_matrix ) ); this->i_matrix = (double *) astFree( (void *)( this->i_matrix ) ); this->form = UNIT; } /* Otherwise, a full MatrixMap has been supplied, but this could be stored in a unit or diagonal MatrixMap if the element values are appropriate. */ } else { new_form = FULL; /* Find the maximum absolute value in each column. Scale by sqrt(DBL_EPSILON) to be come a lower limit for non-zero values. */ colmax = astMalloc( ncol*sizeof( double ) ); if( colmax ) { for( j = 0; j < ncol; j++ ) { colmax[ j ] = 0.0; i = j; for( k = 0; k < nrow; k++ ) { mval = (this->f_matrix)[ i ]; if( mval != AST__BAD ) { mval = fabs( mval ); if( mval > colmax[ j ] ) colmax[ j ] = mval; } i += ncol; } colmax[ j ] *= sqrt( DBL_EPSILON ); } } /* Find the maximum absolute value in each row. Scale by sqrt(DBL_EPSILON) to be come a lower limit for non-zero values. */ rowmax = astMalloc( nrow*sizeof( double ) ); if( rowmax ) { for( k = 0; k < nrow; k++ ) { rowmax[ k ] = 0.0; i = k*ncol; for( j = 0; j < ncol; j++ ) { mval = (this->f_matrix)[ i ]; if( mval != AST__BAD ) { mval = fabs( mval ); if( mval > rowmax[ k ] ) rowmax[ k ] = mval; } i++; } rowmax[ k ] *= sqrt( DBL_EPSILON ); } } /* Check memory can be used */ if( astOK ) { /* Initialise a flag indicating that the inverse matrix does not need to be re-calculated. */ new_inv = 0; /* Initially assume that the forward matrix is a unit matrix. */ new_form = UNIT; /* Store a pointer to the next matrix element. */ a = this->f_matrix; /* Loop through all the rows in the forward matrix array. */ for( k = 0; k < nrow; k++ ) { /* Loop through all the elements in this column. */ for( j = 0; j < ncol; j++, a++ ) { /* If this element is bad, use full form. */ if( *a == AST__BAD ) { new_form = FULL; /* Otherwise, if this is a diagonal term, check its value. If it is not one, then the matrix cannot be a unit matrix, but it could still be a diagonal matrix. */ } else { if( j == k ) { if( *a != 1.0 && new_form == UNIT ) new_form = DIAGONAL; /* If this is not a diagonal element, and the element value is not zero, then the matrix is not a diagonal matrix. Allow a tolerance of SQRT(DBL_EPSILON) times the largest value in the same row or column as the current matrix element. That is, an element must be insignificant to both its row and its column to be considered as effectively zero. Replace values less than this limit with zero. */ } else { mval = fabs( *a ); if( mval <= rowmax[ k ] && mval <= colmax[ j ] ) { /* If the element will change value, set a flag indicating that the inverse matrix needs to be re-calculated. */ if( *a != 0.0 ) new_inv = 1; /* Ensure this element value is zero. */ *a = 0.0; } else { new_form = FULL; } } } } } } /* Free memory. */ colmax = astFree( colmax ); rowmax = astFree( rowmax ); /* If it can be compressed into a UNIT MatrixMap, change the storage form and free the arrays holding the element values. */ if( new_form == UNIT ) { this->f_matrix = (double *) astFree( (void *)( this->f_matrix ) ); this->i_matrix = (double *) astFree( (void *)( this->i_matrix ) ); this->form = UNIT; /* Otherwise, if it can be compressed into a DIAGONAL MatrixMap, copy the diagonal elements from the full forward matrix into a newly allocated array, use this array to replace the forward matrix array in the MatrixMap, create a new inverse matrix, and change the storage form. */ } else if( new_form == DIAGONAL ) { fmat = astMalloc( sizeof(double)*(size_t)ndiag ); if( fmat ){ next_diag = 0; for( i = 0; i < ndiag; i++ ){ fmat[ i ] = (this->f_matrix)[ next_diag ]; next_diag += ncol + 1; } (void) astFree( (void *) this->f_matrix ); (void) astFree( (void *) this->i_matrix ); this->f_matrix = fmat; this->i_matrix = InvertMatrix( DIAGONAL, nrow, ncol, fmat, status ); this->form = DIAGONAL; } /* Calculate a new inverse matrix if necessary. */ } else if( new_inv ) { (void) astFree( (void *) this->i_matrix ); this->i_matrix = InvertMatrix( FULL, nrow, ncol, this->f_matrix, status ); } } return; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two MatrixMaps are equivalent. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * MatrixMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two MatrixMaps are equivalent. * Parameters: * this * Pointer to the first Object (a MatrixMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the MatrixMaps are equivalent, zero otherwise. * 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: */ AstMatrixMap *that; AstMatrixMap *this; double *that_matrix; double *this_matrix; int i; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two MatrixMap structures. */ this = (AstMatrixMap *) this_object; that = (AstMatrixMap *) that_object; /* Check the second object is a MatrixMap. We know the first is a MatrixMap since we have arrived at this implementation of the virtual function. */ if( astIsAMatrixMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNout( that ) == nout && astGetNin( that ) == nin ) { /* Assume the MatrixMaps are equivalent. */ result = 1; /* Ensure both MatrixMaps are stored in full form. */ ExpandMatrix( this, status ); ExpandMatrix( that, status ); /* Get pointers to the arrays holding the elements of the forward matrix for both MatrixMaps. */ if( astGetInvert( this ) ) { this_matrix = this->i_matrix; } else { this_matrix = this->f_matrix; } if( astGetInvert( that ) ) { that_matrix = that->i_matrix; } else { that_matrix = that->f_matrix; } /* If either of the above arrays is not available, try to get the inverse matrix arrays. */ if( !this_matrix || !that_matrix ) { if( astGetInvert( this ) ) { this_matrix = this->f_matrix; } else { this_matrix = this->i_matrix; } if( astGetInvert( that ) ) { that_matrix = that->f_matrix; } else { that_matrix = that->i_matrix; } } /* If both arrays are now available compare their elements. */ if( this_matrix && that_matrix ) { result = 1; for( i = 0; i < nin*nout; i++ ) { if( !astEQUAL( this_matrix[ i ], that_matrix[ i ] ) ){ result = 0; break; } } } /* Ensure the supplied MatrixMaps are stored back in compressed form. */ CompressMatrix( this, status ); CompressMatrix( that, status ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void ExpandMatrix( AstMatrixMap *this, int *status ){ /* * Name: * ExpandMatrix * Purpose: * Ensure the MatrixMap is stored in full (non-compressed) form. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void ExpandMatrix( AstMatrixMap *this, int *status ) * Class Membership: * MatrixMap member function. * Description: * If the supplid MatrixMap is stored in a compressed form (i.e no * element values if it is a unit matrix, diagonal elements only * if it is a diagonal matrix), it is expanded into a full MatrixMap * in which all elements are stored. * Parameters: * this * A pointer to the MatrixMap to be expanded. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double *fmat; /* Pointer to full forward matrix */ double *imat; /* Pointer to full inverse matrix */ int i; /* Loop count */ int ncol; /* No. of columns in forward matrix */ int ndiag; /* No. of diagonal elements in matrix */ int nrow; /* No. of rows in forward matrix */ /* Check the global error status. Also return if the MatrixMap pointer is null. */ if ( !astOK || !this ) return; /* Return without action if the MatrixMap is already in full form. */ if( this->form == FULL ) return; /* Get the dimensions of the forward matrix. */ if( astGetInvert( this ) ){ nrow = astGetNin( this ); ncol = astGetNout( this ); } else { ncol = astGetNin( this ); nrow = astGetNout( this ); } /* Store the number of diagonal elements. */ if( nrow > ncol ){ ndiag = ncol; } else { ndiag = nrow; } /* Allocate arrays to hold the full forward and inverse matrices. */ fmat = (double *) astMalloc( sizeof( double )*(size_t)( nrow*ncol ) ); imat = (double *) astMalloc( sizeof( double )*(size_t)( nrow*ncol ) ); if( imat && fmat ){ /* Fill them both with zeros. */ for( i = 0; i < nrow*ncol; i++ ) { fmat[ i ] = 0.0; imat[ i ] = 0.0; } /* If a unit MatrixMap was supplied, put ones on the diagonals. */ if( this->form == UNIT ){ for( i = 0; i < ndiag; i++ ) { fmat[ i*( ncol + 1 ) ] = 1.0; imat[ i*( nrow + 1 ) ] = 1.0; } /* If a diagonal MatrixMap was supplied, copy the diagonal terms from the supplied MatrixMap. */ } else if( this->form == DIAGONAL ){ for( i = 0; i < ndiag; i++ ) { fmat[ i*( ncol + 1 ) ] = (this->f_matrix)[ i ]; imat[ i*( nrow + 1 ) ] = (this->i_matrix)[ i ]; } } /* Free any existing arrays in the MatrixMap and store the new ones. */ (void) astFree( (void *) this->f_matrix ); (void) astFree( (void *) this->i_matrix ); this->f_matrix = fmat; this->i_matrix = imat; /* Update the storage form. */ this->form = FULL; /* If either of the new matrices could not be allocated, ensure that both have been freed. */ } else { fmat = (double *) astFree( (void *) fmat ); imat = (double *) astFree( (void *) imat ); } return; } static int FindString( int n, const char *list[], const char *test, const char *text, const char *method, const char *class, int *status ){ /* * Name: * FindString * Purpose: * Find a given string within an array of character strings. * Type: * Private function. * Synopsis: * #include "matrix.h" * int FindString( int n, const char *list[], const char *test, * const char *text, const char *method, const char *class, int *status ) * Class Membership: * MatrixMap method. * Description: * This function identifies a supplied string within a supplied * array of valid strings, and returns the index of the string within * the array. The test option may not be abbreviated, but case is * insignificant. * Parameters: * n * The number of strings in the array pointed to be "list". * list * A pointer to an array of legal character strings. * test * A candidate string. * text * A string giving a description of the object, parameter, * attribute, etc, to which the test value refers. * This is only for use in constructing error messages. It should * start with a lower case letter. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The index of the identified string within the supplied array, starting * at zero. * Notes: * - A value of -1 is returned if an error has already occurred, or * if this function should fail for any reason (for instance if the * supplied option is not specified in the supplied list). */ /* Local Variables: */ int ret; /* The returned index */ /* Check global status. */ if( !astOK ) return -1; /* Compare the test string with each element of the supplied list. Leave the loop when a match is found. */ for( ret = 0; ret < n; ret++ ) { if( !Ustrcmp( test, list[ ret ], status ) ) break; } /* Report an error if the supplied test string does not match any element in the supplied list. */ if( ret >= n ) { astError( AST__RDERR, "%s(%s): Illegal value '%s' supplied for %s.", status, method, class, test, text ); ret = -1; } /* Return the answer. */ return ret; } static int GetIsLinear( AstMapping *this_mapping, int *status ){ /* * Name: * GetIsLinear * Purpose: * Return the value of the IsLinear attribute for a MatrixMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * MatrixMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one. * Parameters: * this * Pointer to the MatrixMap. * status * Pointer to the inherited status variable. */ return 1; } static int Ustrcmp( const char *a, const char *b, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strcmp. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int Ustrcmp( const char *a, const char *b ) * Class Membership: * MatrixMap member function. * Description: * Returns 0 if there are no differences between the two strings, and 1 * otherwise. Comparisons are case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strcmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Loop round each character. */ while( 1 ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } void astInitMatrixMapVtab_( AstMatrixMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitMatrixMapVtab * Purpose: * Initialise a virtual function table for a MatrixMap. * Type: * Protected function. * Synopsis: * #include "matrixmap.h" * void astInitMatrixMapVtab( AstMatrixMapVtab *vtab, const char *name ) * Class Membership: * MatrixMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the MatrixMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAMatrixMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->MtrRot = MtrRot; vtab->MtrMult = MtrMult; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_mapsplit = mapping->MapSplit; mapping->MapSplit = MapSplit; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->GetIsLinear = GetIsLinear; mapping->GetTranForward = GetTranForward; mapping->GetTranInverse = GetTranInverse; mapping->MapMerge = MapMerge; mapping->Rate = Rate; /* Declare the destructor and copy constructor. */ astSetDelete( (AstObjectVtab *) vtab, Delete ); astSetCopy( (AstObjectVtab *) vtab, Copy ); /* Declare the class dump function. */ astSetDump( vtab, Dump, "MatrixMap", "Matrix transformation" ); /* 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 double *InvertMatrix( int form, int nrow, int ncol, double *matrix, int *status ){ /* * Name: * InvertMatrix * Purpose: * Invert a suplied matrix. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * double *InvertMatrix( int form, int nrow, int ncol, double *matrix, int *status ) * Class Membership: * MatrixMap member function. * Description: * This function returns a pointer to a matrix holding the inverse of * the supplied matrix, or a NULL pointer if the inverse is not defined. * The memory to store the inverse matrix is allocated internally, and * should be freed using astFree when no longer required. * * The correspondence between a full matrix and its inverse is only * unique if the matrix is square, and so a NULL pointer is returned if * the supplied matrix is not square. * Parameters: * form * The form of the MatrixMap; UNIT, DIAGONAL or FULL. * nrow * Number of rows in the supplied matrix. * ncol * Number of columns in the supplied matrix. * matrix * A pointer to the input matrix. Elements should be stored in row * order (i.e. (row 1,column 1 ), (row 1,column 2 )... (row 2,column 1), * etc). * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the output matrix. * Notes: * - A NULL pointer is returned if a unit matrix is supplied. * - 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. * - No error is reported if the inverse is not defined. */ /* Local Variables: */ double det; /* Determinant of supplied matrix */ double mval; /* Matrix element value */ double *out; /* Pointer to returned inverse matrix */ double *vector; /* Pointer to vector used by palDmat */ int i; /* Matrix element number */ int *iw; /* Pointer to workspace used by palDmat */ int nel; /* No. of elements in square matrix */ int ndiag; /* No. of diagonal elements */ int ok; /* Zero if any bad matrix values found */ int sing; /* Zero if matrix is not singular */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Return a NULL pointer if the input matrix is NULL. */ if( !matrix ) return NULL; /* If a unit matrix map has been supplied, return NULL. */ if( form == UNIT ){ return NULL; /* If a diagonal matrix has been supplied, allocate an array to hold the diagonal terms of the inverse matrix. Store the reciprocal of the input matrix diagonal terms in it. If any of the input diagonal terms are zero or BAD, set the associated elements of the inverse matrix BAD. */ } else if( form == DIAGONAL ){ if( nrow > ncol ) { ndiag = ncol; } else { ndiag = nrow; } out = (double *) astMalloc( sizeof( double )*(size_t)ndiag ); if( out ) { for( i = 0; i < ndiag; i++ ) { mval = matrix[ i ]; if( mval != 0.0 && mval != AST__BAD ){ out[ i ] = 1.0/mval; } else { out[ i ] = AST__BAD; } } } /* If a full matrix has been supplied, initialise the returned pointer. */ } else { out = NULL; /* Check that the matrix is square. */ if( nrow == ncol ){ /* Find the number of elements in the matrix. */ nel = nrow*ncol; /* See if there are any bad values in the matrix. */ ok = 1; for ( i=0; iform == UNIT && nin == nout ){ map2 = (AstMapping *) astUnitMap( nin, "", status ); /* If the MatrixMap is a square diagonal matrix with equal diagonal terms, then it can be replaced by a ZoomMap. */ } else if( mm->form == DIAGONAL && nin == nout && mm->f_matrix && mm->i_matrix && (mm->f_matrix)[ 0 ] != AST__BAD ){ zoom = 1; b = mm->f_matrix + 1; for( i = 1; i < nin; i++ ){ if( !astEQUAL( *b, *( b - 1 ) ) ){ zoom = 0; break; } b++; } if( zoom ){ if( ( *invert_list )[ where ] ){ map2 = (AstMapping *) astZoomMap( nin, (mm->i_matrix)[ 0 ], "", status ); } else { map2 = (AstMapping *) astZoomMap( nin, (mm->f_matrix)[ 0 ], "", status ); } } /* If the MatrixMap is a full matrix but all off-diagnal elements are zero, it can be replaced by a diagonal MatrixMap. */ } else if( mm->form == FULL && nin == nout && mm->f_matrix ){ new_mat = astMalloc( sizeof( double )*nin ); b = mm->f_matrix; for( i = 0; i < nin && new_mat; i++ ){ for( j = 0; j < nout; j++,b++ ){ if( i == j ) { new_mat[ i ] = *b; } else if( *b != 0.0 ) { new_mat = astFree( new_mat ); break; } } } if( new_mat ) { map2 = (AstMapping *) astMatrixMap( nin, nout, 1, new_mat, "", status ); new_mat = astFree( new_mat ); } } /* If the MatrixMap can be replaced, annul the MatrixMap pointer in the list and replace it with the new Mapping pointer, and indicate that the forward transformation of the returned Mapping should be used. */ if( map2 ){ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = map2; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the MatrixMap itself could not be simplified, see if it can be merged with the Mappings on either side of it in the list. */ /*==========================================================================*/ } else { /* Store the classes of the neighbouring Mappings in the list. */ class1 = ( where > 0 ) ? astGetClass( ( *map_list )[ where - 1 ] ) : NULL; class2 = ( where < *nmap - 1 ) ? astGetClass( ( *map_list )[ where + 1 ] ) : NULL; /* In series. */ /* ========== */ if ( series ) { /* We first look to see if the MatrixMap can be merged with one of its neighbours, resulting in a reduction of one in the number of Mappings in the list. MatrixMaps can merge directly with another MatrixMap, a ZoomMap, an invertable PermMap, or a UnitMap. */ if( class1 && ( !strcmp( class1, "MatrixMap" ) || !strcmp( class1, "ZoomMap" ) || !strcmp( class1, "PermMap" ) || !strcmp( class1, "UnitMap" ) ) ){ nclass = class1; i1 = where - 1; i2 = where; } else if( class2 && ( !strcmp( class2, "MatrixMap" ) || !strcmp( class2, "ZoomMap" ) || !strcmp( class2, "PermMap" ) || !strcmp( class2, "UnitMap" ) ) ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* Only some PermMaps can be merged with (those which have consistent forward and inverse mappings). If this is not one of them, set nclass NULL to indicate this. */ if( nclass && !strcmp( nclass, "PermMap" ) && !PermOK( ( *map_list )[ (i1==where)?i2:i1 ], status ) ) nclass = NULL; /* If the MatrixMap can merge with one of its neighbours, create the merged Mapping. */ if( nclass ){ if( !strcmp( nclass, "MatrixMap" ) ){ newmm = MatMat( ( *map_list )[ i1 ], ( *map_list )[ i2 ], ( *invert_list )[ i1 ], ( *invert_list )[ i2 ], status ); invert = 0; } else if( !strcmp( nclass, "ZoomMap" ) ){ if( i1 == where ){ newmm = MatZoom( (AstMatrixMap *)( *map_list )[ i1 ], (AstZoomMap *)( *map_list )[ i2 ], ( *invert_list )[ i1 ], ( *invert_list )[ i2 ], status ); } else { newmm = MatZoom( (AstMatrixMap *)( *map_list )[ i2 ], (AstZoomMap *)( *map_list )[ i1 ], ( *invert_list )[ i2 ], ( *invert_list )[ i1 ], status ); } invert = 0; } else if( !strcmp( nclass, "PermMap" ) ){ if( i1 == where ){ newmm = MatPerm( (AstMatrixMap *)( *map_list )[ i1 ], (AstPermMap *)( *map_list )[ i2 ], ( *invert_list )[ i1 ], ( *invert_list )[ i2 ], 1, status ); } else { newmm = MatPerm( (AstMatrixMap *)( *map_list )[ i2 ], (AstPermMap *)( *map_list )[ i1 ], ( *invert_list )[ i2 ], ( *invert_list )[ i1 ], 0, status ); } invert = 0; } else { newmm = astClone( ( *map_list )[ where ] ); invert = ( *invert_list )[ where ]; } /* If succesfull... */ if( astOK ){ /* Annul the first of the two Mappings, and replace it with the merged MatrixMap. Also set the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = (AstMapping *) newmm; ( *invert_list )[ i1 ] = invert; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i2 ] ); for ( i = i2 + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } /* If the MatrixMap could not merge directly with either of its neighbours, we consider whether it would be worthwhile to swap the MatrixMap with either of its neighbours. This can only be done for certain classes of Mapping (WinMaps and some PermMaps), and will usually require both Mappings to be modified (unless they are commutative). The advantage of swapping the order of the Mappings is that it may result in the MatrixMap being adjacent to a Mapping with which it can merge directly on the next invocation of this function, thus reducing the number of Mappings in the list. */ } else { /* Set a flag if we could swap the MatrixMap with its higher neighbour. "do2" is returned if swapping the Mappings would simplify either of the Mappings. */ if( where + 1 < *nmap ){ swaphi = CanSwap( ( *map_list )[ where ], ( *map_list )[ where + 1 ], ( *invert_list )[ where ], ( *invert_list )[ where + 1 ], &do2, status ); } else { swaphi = 0; do2 = 0; } /* If so, step through each of the Mappings which follow the MatrixMap, looking for a Mapping with which the MatrixMap could merge directly. Stop when such a Mapping is found, or if a Mapping is found with which the MatrixMap could definitely not swap. Note the number of Mappings which separate the MatrixMap from the Mapping with which it could merge (if any). */ nstep2 = -1; if( swaphi ){ for( i2 = where + 1; i2 < *nmap; i2++ ){ /* See if we can merge with this Mapping. If so, note the number of steps between the two Mappings and leave the loop. */ nclass = astGetClass( ( *map_list )[ i2 ] ); if( !strcmp( nclass, "MatrixMap" ) || !strcmp( nclass, "ZoomMap" ) || ( !strcmp( nclass, "PermMap" ) && PermOK( ( *map_list )[ i2 ], status ) ) || !strcmp( nclass, "UnitMap" ) ) { nstep2 = i2 - where - 1; break; } /* If there is no chance that we can swap with this Mapping, leave the loop with -1 for the number of steps to indicate that no merging is possible. MatrixMaps can swap with WinMaps and some permmaps. */ if( strcmp( nclass, "WinMap" ) && strcmp( nclass, "PermMap" ) ) { break; } } } /* Do the same working forward from the MatrixMap towards the start of the map list. */ if( where > 0 ){ swaplo = CanSwap( ( *map_list )[ where - 1 ], ( *map_list )[ where ], ( *invert_list )[ where - 1 ], ( *invert_list )[ where ], &do1, status ); } else { swaplo = 0; do1 = 0; } nstep1 = -1; if( swaplo ){ for( i1 = where - 1; i1 >= 0; i1-- ){ nclass = astGetClass( ( *map_list )[ i1 ] ); if( !strcmp( nclass, "MatrixMap" ) || ( !strcmp( nclass, "PermMap" ) && PermOK( ( *map_list )[ i1 ], status ) ) || !strcmp( nclass, "ZoomMap" ) || !strcmp( nclass, "UnitMap" ) ) { nstep1 = where - 1 - i1; break; } if( strcmp( nclass, "WinMap" ) && strcmp( nclass, "PermMap" ) ) { break; } } } /* Choose which neighbour to swap with so that the MatrixMap moves towards the nearest Mapping with which it can merge. */ if( do1 || ( nstep1 != -1 && ( nstep2 == -1 || nstep2 > nstep1 ) ) ){ nclass = class1; i1 = where - 1; i2 = where; } else if( do2 || nstep2 != -1 ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* If there is a target Mapping in the list with which the MatrixMap could merge, consider replacing the supplied Mappings with swapped Mappings to bring the MatrixMap closer to the target Mapping. */ if( nclass ){ /* Swap the Mappings. */ if (!strcmp( nclass, "WinMap" ) ){ MatWin( (*map_list) + i1, (*invert_list) + i1, where - i1, status ); } else if( !strcmp( nclass, "PermMap" ) ){ MatPermSwap( (*map_list) + i1, (*invert_list) + i1, where - i1, status ); } /* And then merge them. */ if( where == i1 && where + 1 < *nmap ) { /* Merging upwards */ map2 = astClone( (*map_list)[ where + 1 ] ); nmapt = *nmap - where - 1; maplt = *map_list + where + 1; invlt = *invert_list + where + 1; (void) astMapMerge( map2, 0, series, &nmapt, &maplt, &invlt ); map2 = astAnnul( map2 ); *nmap = where + 1 + nmapt; } else if( where - 2 >= 0 ) { /* Merging downwards */ map2 = astClone( (*map_list)[ where - 2 ] ); nmapt = *nmap - where + 2; maplt = *map_list + where - 2 ; invlt = *invert_list + where - 2; (void) astMapMerge( map2, 0, series, &nmapt, &maplt, &invlt ); map2 = astAnnul( map2 ); *nmap = where - 2 + nmapt; } result = i1; /* If there is no Mapping available for merging, it may still be advantageous to swap with a neighbour because the swapped Mapping may be simpler than the original Mappings. For instance, a PermMap may strip rows of the MatrixMap leaving only a UnitMap. */ } else if( swaphi || swaplo ) { /* Try swapping with each possible neighbour in turn. */ for( i = 0; i < 2; i++ ) { /* Set up the class and pointers for the mappings to be swapped, first the lower neighbour, then the upper neighbour. */ if( i == 0 && swaplo ){ nclass = class1; i1 = where - 1; i2 = where; } else if( i == 1 && swaphi ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* If we have a Mapping to swap with... */ if( nclass ) { /* Take copies of the Mapping and Invert flag arrays so we do not change the supplied values. */ mc[ 0 ] = (AstMapping *) astCopy( ( (*map_list) + i1 )[0] ); mc[ 1 ] = (AstMapping *) astCopy( ( (*map_list) + i1 )[1] ); ic[ 0 ] = ( (*invert_list) + i1 )[0]; ic[ 1 ] = ( (*invert_list) + i1 )[1]; /* Swap these Mappings. */ if( !strcmp( nclass, "WinMap" ) ){ MatWin( mc, ic, where - i1, status ); } else if( !strcmp( nclass, "PermMap" ) ){ MatPermSwap( mc, ic, where - i1, status ); } /* If neither of the swapped Mappings can be simplified further, then there is no point in swapping the Mappings, so just annul the map copies. */ smc0 = astSimplify( mc[0] ); smc1 = astSimplify( mc[1] ); if( astGetClass( smc0 ) == astGetClass( mc[0] ) && astGetClass( smc1 ) == astGetClass( mc[1] ) ) { mc[ 0 ] = (AstMapping *) astAnnul( mc[ 0 ] ); mc[ 1 ] = (AstMapping *) astAnnul( mc[ 1 ] ); /* If one or both of the swapped Mappings could be simplified, then annul the supplied Mappings and return the swapped mappings, storing the index of the first modified Mapping. */ } else { (void ) astAnnul( ( (*map_list) + i1 )[0] ); (void ) astAnnul( ( (*map_list) + i1 )[1] ); ( (*map_list) + i1 )[0] = mc[ 0 ]; ( (*map_list) + i1 )[1] = mc[ 1 ]; ( (*invert_list) + i1 )[0] = ic[ 0 ]; ( (*invert_list) + i1 )[1] = ic[ 1 ]; result = i1; break; } /* Annul the simplied Mappings */ smc0 = astAnnul( smc0 ); smc1 = astAnnul( smc1 ); } } } } } } /* Return the result. */ return result; } 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 * MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * MatrixMap 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 MatrixMap. This is only possible if the specified inputs * correspond to some subset of the MatrixMap outputs. That is, there * must exist a subset of the MatrixMap outputs for which each output * depends only on the selected MatrixMap inputs, and not on any of the * inputs which have not been selected. In addition, outputs that are * not in this subset must not depend on any selected inputs. If these * conditions are not met by the supplied MatrixMap, then a NULL Mapping * is returned. * Parameters: * this * Pointer to the MatrixMap to be split (the MatrixMap 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 MatrixMap, 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 MatrixMap 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 MatrixMap. 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: */ AstMatrixMap *this; /* Pointer to MatrixMap structure */ double *mat; /* Pointer to matrix for supplied MatrixMap */ double *pmat; /* Pointer to row start in returned matrix */ double *prow; /* Pointer to row start in supplied matrix */ double *rmat; /* Pointer to matrix for returned MatrixMap */ double el; /* Next element value in supplied matrix */ int *result; /* Pointer to returned array */ int good; /* Would new matrix contain any good values/ */ int i; /* Loop count */ int icol; /* Column index within supplied MatrixMap */ int iel; /* Index of next element from the input matrix */ int irow; /* Row index within supplied MatrixMap */ int isel; /* Does output depend on any selected inputs? */ int ncol; /* Number of columns (inputs) in supplied MatrixMap */ int nout; /* Number of outputs in returned MatrixMap */ int nrow; /* Number of rows (outputs) in supplied MatrixMap */ int ok; /* Are input indices OK? */ int sel; /* Does any output depend on selected inputs? */ int unsel; /* Does any output depend on unselected inputs? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the parent astMapSplit method to see if it can do the job. */ result = (*parent_mapsplit)( this_map, nin, in, map, status ); /* If not, we provide a special implementation here. */ if( !result ) { /* Get a pointer to the MatrixMap structure. */ this = (AstMatrixMap *) this_map; /* Get the number of inputs and outputs. */ ncol = astGetNin( this ); nrow = astGetNout( this ); /* Check the supplied input indices are usable. */ ok = 1; for( i = 0; i < nin; i++ ) { if( in[ i ] < 0 || in[ i ] >= ncol ) { ok = 0; break; } } if( ok ) { /* Ensure the MatrixMap is stored in full form. */ ExpandMatrix( this, status ); /* Allocate the largest array that could be necessary to hold the returned array of Mapping outputs. */ result = astMalloc( sizeof(int)*(size_t) nrow ); /* Allocate the largest array that could be necessary to hold the matrix representing the returned MatrixMap. */ rmat = astMalloc( sizeof(double)*(size_t) (nrow*ncol) ); /* Get the matrix which defines the current forward transformation. This takes into account whether the MatrixMap has been inverted or not. */ if( astGetInvert( this ) ) { mat = this->i_matrix; } else { mat = this->f_matrix; } /* We cannot create the require Mapping if the matrix is undefined. */ if( !mat || !astOK ) { ok = 0; nout = 0; good = 0; /* Otherwise, loop round all the rows in the matrix. */ } else { nout = 0; good = 0; pmat = rmat; iel = 0; for( irow = 0; irow < nrow; irow++ ) { /* Indicate that this output (i.e. row of the matrix) depends on neither selected nor unselected inputs as yet. */ sel = 0; unsel = 0; /* Save a pointer to the first element of this row in the MatrixMap matrix. */ prow = mat + iel; /* Loop round all the elements in the current row of the matrix. */ for( icol = 0; icol < ncol; icol++ ) { /* If this element is non-zero and non-bad, then output "irow" depends on input "icol". */ el = mat[ iel++ ]; if( el != 0.0 && el != AST__BAD ) { /* Is input "icol" one of the selected inputs? */ isel = 0; for( i = 0; i < nin; i++ ) { if( in[ i ] == icol ) { isel = 1; break; } } /* If so, note that this output depends on selected inputs. Otherwise note it depends on unselected inputs. */ if( isel ) { sel = 1; } else { unsel = 1; } } } /* If this output depends only on selected inputs, we can include it in the returned Mapping.*/ if( sel && !unsel ) { /* Store the index of the output within the original MatrixMap. */ result[ nout ] = irow; /* Increment the number of outputs in the returned Mapping. */ nout++; /* Copy the elements of the current matrix row which correspond to the selected inputs into the new matrix. */ for( i = 0; i < nin; i++ ) { if( astISGOOD( prow[ in[ i ] ] ) ) { *(pmat++) = prow[ in[ i ] ]; good = 1; } } } /* If this output depends on a selected input, but also depends on an unselected input, we cannot split the MatrixMap. */ if( sel && unsel ) { ok = 0; break; } } } /* If the returned Mapping can be created, create it. */ if( ok && nout > 0 && good ) { *map = (AstMapping *) astMatrixMap( nin, nout, 0, rmat, "", status ); /* Otherwise, free the returned array. */ } else { result = astFree( result ); } /* Free resources. */ rmat = astFree( rmat ); /* Re-compress the supplied MatrixMap. */ CompressMatrix( this, status ); } } /* 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 AstMatrixMap *MatMat( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ){ /* * Name: * MatMat * Purpose: * Create a merged MatrixMap from two supplied MatrixMaps. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *MatMat( AstMapping *map1, AstMapping *map2, int inv1, * int inv2, int *status ) * Class Membership: * MatrixMap member function * Description: * This function creates a new MatrixMap which performs a mapping * equivalent to applying the two supplied MatrixMaps in series, in the * directions specified by the "invert" flags (the Invert attributes of * the supplied MatrixMaps are ignored). * Parameters: * map1 * A pointer to the MatrixMap to apply first. * map2 * A pointer to the MatrixMap to apply second. * inv1 * The invert flag to use with map1. A value of zero causes the forward * mapping to be used, and a non-zero value causes the inverse * mapping to be used. * inv2 * The invert flag to use with map2. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the new MatrixMap. * Notes: * - The forward direction of the returned MatrixMap is equivalent to the * combined effect of the two supplied MatrixMap, operating in the * directions specified by "inv1" and "inv2". * - 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: */ AstMatrixMap *result; /* Pointer to output MatrixMap */ int invert[ 2 ]; /* Original invert flags */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the returned pointer. */ result = NULL; /* Temporarily set their Invert attributes to the supplied values. */ invert[ 0 ] = astGetInvert( map1 ); astSetInvert( map1, inv1 ); invert[ 1 ] = astGetInvert( map2 ); astSetInvert( map2, inv2 ); /* Create a new MatrixMap by multiplying them together. */ result = astMtrMult( (AstMatrixMap *) map1, (AstMatrixMap *) map2 ); /* Re-instate the original settings of the Invert attributes for the supplied MatrixMaps. */ astSetInvert( map1, invert[ 0 ] ); astSetInvert( map2, invert[ 1 ] ); /* If an error has occurred, annull the returned MatrixMap. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output MatrixMap. */ return result; } static AstMatrixMap *MatPerm( AstMatrixMap *mm, AstPermMap *pm, int minv, int pinv, int mat1, int *status ){ /* * Name: * MatPerm * Purpose: * Create a MatrixMap by merging a MatrixMap and a PermMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *MatPerm( AstMatrixMap *mm, AstPermMap *pm, int minv, * int pinv, int mat1, int *status ) * Class Membership: * MatrixMap member function * Description: * This function creates a new MatrixMap which performs a mapping * equivalent to applying the two supplied Mappings in series in the * directions specified by the "invert" flags (the Invert attributes of * the supplied MatrixMaps are ignored). * Parameters: * mm * A pointer to the MatrixMap. * pm * A pointer to the PermMap. * minv * The invert flag to use with mm. A value of zero causes the forward * mapping to be used, and a non-zero value causes the inverse * mapping to be used. * pinv * The invert flag to use with pm. * mat1 * If non-zero, then "mm" is applied first followed by "pm". Otherwise, * "pm" is applied first followed by "mm". * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the new MatrixMap. * Notes: * - The forward direction of the returned MatrixMap is equivalent to the * combined effect of the two supplied Mappings, operating in the * directions specified by "pinv" and "minv". * - 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: */ AstMatrixMap *mm2; /* Pointer to an intermediate MatrixMap */ AstMatrixMap *result; /* Pointer to output MatrixMap */ AstPointSet *pset1; /* Pointer to a PointSet holding unpermuted unit vectors */ AstPointSet *pset2; /* Pointer to a PointSet holding permuted unit vectors */ double *matrix; /* Pointer to a matrix representing the PermMap */ double *p; /* Pointer to next matrix element */ double **ptr1; /* Pointer to the data in pset1 */ double **ptr2; /* Pointer to the data in pset2 */ int i; /* Axis index */ int j; /* Point index */ int nax; /* No. of axes in the PermMap */ int old_minv; /* Original setting of MatrixMap Invert attribute */ int old_pinv; /* Original setting of PermMap Invert attribute */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the returned pointer. */ result = NULL; /* Temporarily set the Invert attributes of both Mappings to the supplied values. */ old_minv = astGetInvert( mm ); astSetInvert( mm, minv ); old_pinv = astGetInvert( pm ); astSetInvert( pm, pinv ); /* Get the number of axes in the PermMap. The PermMap will have the same number of input and output axes because a check has already been made on it to ensure that this is so (in function PermOK). */ nax = astGetNin( pm ); /* We first represent the PermMap as a MatrixMap containing elements with values zero or one. Each row of this matrix is obtained by transforming a unit vector along each axis using the inverse PermMap. Allocate memory to hold the matrix array, and create a PointSet holding the unit vectors. */ matrix = (double *) astMalloc( sizeof( double )*(size_t)( nax*nax ) ); pset1 = astPointSet( nax, nax, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( nax, nax, "", status ); ptr2 = astGetPoints( pset2 ); if( astOK ){ for( i = 0; i < nax; i++ ){ for( j = 0; j < nax; j++ ) ptr1[ i ][ j ] = 0.0; ptr1[ i ][ i ] = 1.0; } /* Transform these unit vectors using the inverse PermMap. */ (void) astTransform( pm, pset1, 0, pset2 ); /* Copy the transformed vectors into the matrix array. */ p = matrix; for( j = 0; j < nax; j++ ){ for( i = 0; i < nax; i++ ) *(p++) = ptr2[ i ][ j ]; } /* Create a MatrixMap holding this array. */ mm2 = astMatrixMap( nax, nax, 0, matrix, "", status ); /* Create a new MatrixMap equal to the product of the supplied MatrixMap and the MatrixMap just created from the PermMap. */ if( mat1 ){ result = astMtrMult( mm, mm2 ); } else { result = astMtrMult( mm2, mm ); } /* Free everything. */ mm2 = astAnnul( mm2 ) ; } pset2 = astAnnul( pset2 ); pset1 = astAnnul( pset1 ); matrix = (double *) astFree( (void *) matrix ); /* Re-instate the original settings of the Invert attribute for the supplied Mappings. */ astSetInvert( mm, old_minv ); astSetInvert( pm, old_pinv ); /* If an error has occurred, annull the returned MatrixMap. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output MatrixMap. */ return result; } static void MatPermSwap( AstMapping **maps, int *inverts, int imm, int *status ){ /* * Name: * MatPermSwap * Purpose: * Swap a PermMap and a MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void MatPermSwap( AstMapping **maps, int *inverts, int imm ) * Class Membership: * MatrixMap member function * Description: * A list of two Mappings is supplied containing a PermMap and a * MatrixMap. These Mappings are annulled, and replaced with * another pair of Mappings consisting of a PermMap and a MatrixMap * in the opposite order. These Mappings are chosen so that their * combined effect is the same as the original pair of Mappings. * Parameters: * maps * A pointer to an array of two Mapping pointers. * inverts * A pointer to an array of two invert flags. * imm * The index within "maps" of the MatrixMap. * Notes: * - There are restictions on the sorts of PermMaps which can be * swapped with a MatrixMap -- see function CanSwap. It is assumed * that the supplied MatrixMap and PermMap satisfy these requirements. */ /* Local Variables: */ AstMatrixMap *mm; /* Pointer to the supplied MatrixMap */ AstMatrixMap *mmnew; /* Pointer to new MatrixMap */ AstMatrixMap *smmnew; /* Pointer to new simplified MatrixMap */ AstPermMap *pm; /* Pointer to the supplied PermMap */ AstPermMap *pmnew; /* Pointer to new PermMap */ AstPermMap *spmnew; /* Pointer to new simplified PermMap */ double *consts; /* Pointer to constants array */ double *matrix; /* Supplied array of matrix elements */ double *out_el; /* Pointer to next element of new MatrixMap */ double *out_mat; /* Matrix elements for new MatrixMap */ double c; /* Constant */ double matel; /* Matrix element */ int *inperm; /* Pointer to input axis permutation array */ int *outperm; /* Pointer to output axis permutation array */ int col; /* Index of matrix column */ int i; /* Axis count */ int k; /* Axis count */ int nin; /* No. of axes in supplied PermMap */ int nout; /* No. of axes in returned PermMap */ int old_pinv; /* Invert value for the supplied PermMap */ int row; /* Index of matrix row */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ mmnew = NULL; pmnew = NULL; /* Store pointers to the supplied PermMap and the MatrixMap. */ pm = (AstPermMap *) maps[ 1 - imm ]; mm = (AstMatrixMap *) maps[ imm ]; /* Temporarily set the Invert attribute of the supplied PermMap to the supplied value. */ old_pinv = astGetInvert( pm ); astSetInvert( pm, inverts[ 1 - imm ] ); /* Ensure the MatrixMap is stored in full form. */ ExpandMatrix( mm, status ); /* Store a pointer to the required array of matrix elements. */ if( inverts[ imm ] ) { matrix = mm->i_matrix; } else { matrix = mm->f_matrix; } /* Get the number of input and output axes of the PermMap. */ nin = astGetNin( pm ); nout = astGetNout( pm ); /* Allocate memory to hold the matrix elements for the swapped MatrixMap. The number of rows and olumns in the new matrix must equal the number of input or output axes for the PermMap, depending on whether the PermMap or MatrixMap is applied first. */ if( imm == 0 ) { out_mat = (double *) astMalloc( sizeof( double )*(size_t)( nout*nout ) ); } else { out_mat = (double *) astMalloc( sizeof( double )*(size_t)( nin*nin ) ); } /* We need to know the axis permutation arrays and constants array for the PermMap. */ PermGet( pm, &outperm, &inperm, &consts, status ); if( astOK ) { /* First deal with cases where the MatrixMap is applied first. */ if( imm == 0 ) { /* Consider each output axis of the PermMap. */ for( i = 0; i < nout; i++ ) { /* If this output is connected to one of the input axes... */ row = outperm[ i ]; if( row >= 0 && row < nin ) { /* Permute the row of the supplied matrix which feeds the corresponding PermMap input axis (i.e. axis outperm[k] ) using the forward PermMap. Store zeros for any output axes which are assigned constants. This forms row i of the new MatrixMap. */ out_el = out_mat + nout*i; for( k = 0; k < nout; k++ ){ col = outperm[ k ]; if( col >= 0 && col < nin ) { *(out_el++) = *( matrix + nin*row + col ); } else { *(out_el++) = 0.0; } } /* If this output is asigned a constant value, use a "diagonal" vector for row i of the new MatrixMap (i.e. all zeros except for a 1.0 in column i ). */ } else { out_el = out_mat + nout*i; for( k = 0; k < nout; k++ ) { if( k != i ) { *(out_el++) = 0.0; } else { *(out_el++) = 1.0; } } } } /* Create the new MatrixMap. */ mmnew = astMatrixMap( nout, nout, 0, out_mat, "", status ); /* Any PermMap inputs which are assigned a constant value need to be changed now, since they will no longer be scaled by the inverse MatrixMap. CanSwap ensures that the inverse MatrixMap produces a simple scaling for constant axes, so we change the PermMap constant to be the constant AFTER scaling by the inverse MatrixMap. Consider each input axis of the PermMap. */ for( i = 0; i < nin; i++ ) { /* If this input is assigned a constant value... */ if( inperm[ i ] < 0 ) { /* Divide the supplied constant value by the corresponding diagonal term in the supplied MatrixMap. */ c = consts[ -inperm[ i ] - 1 ]; if( c != AST__BAD ) { matel = matrix[ i*( nin + 1 ) ]; if( matel != 0.0 && matel != AST__BAD ) { consts[ -inperm[ i ] - 1 ] /= matel; } else { consts[ -inperm[ i ] - 1 ] = AST__BAD; } } } } /* Now deal with cases where the PermMap is applied first. */ } else { /* Consider each input axis of the PermMap. */ for( i = 0; i < nin; i++ ) { /* If this input is connected to one of the output axes... */ row = inperm[ i ]; if( row >= 0 && row < nout ) { /* Permute the row of the supplied matrix which feeds the corresponding PermMap output axis (i.e. axis inperm[k] ) using the inverse PermMap. Store zeros for any input axes which are assigned constants. This forms row i of the new MatrixMap. */ out_el = out_mat + nin*i; for( k = 0; k < nin; k++ ){ col = inperm[ k ]; if( col >= 0 && col < nout ) { *(out_el++) = *( matrix + nout*row + col ); } else { *(out_el++) = 0.0; } } /* If this input is asigned a constant value, use a "diagonal" vector for row i of the new MatrixMap (i.e. all zeros except for a 1.0 in column i ). */ } else { out_el = out_mat + nin*i; for( k = 0; k < nin; k++ ) { if( k != i ) { *(out_el++) = 0.0; } else { *(out_el++) = 1.0; } } } } /* Create the new MatrixMap. */ mmnew = astMatrixMap( nin, nin, 0, out_mat, "", status ); /* Any PermMap outputs which are assigned a constant value need to be changed now, since they will no longer be scaled by the forward MatrixMap. CanSwap ensures that the forward MatrixMap produces a simple scaling for constant axes, so we change the PermMap constant to be the constant AFTER scaling by the forward MatrixMap. Consider each output axis of the PermMap. */ for( i = 0; i < nout; i++ ) { /* If this output is assigned a constant value... */ if( outperm[ i ] < 0 ) { /* Multiple the supplied constant value by the corresponding diagonal term in the supplied MatrixMap. */ c = consts[ -outperm[ i ] - 1 ]; if( c != AST__BAD ) { matel = matrix[ i*( nout + 1 ) ]; if( matel != AST__BAD ) { consts[ -outperm[ i ] - 1 ] *= matel; } else { consts[ -outperm[ i ] - 1 ] = AST__BAD; } } } } } /* Create a new PermMap (since the constants may have changed). */ pmnew = astPermMap( nin, inperm, nout, outperm, consts, "", status ); /* Free the axis permutation and constants arrays. */ outperm = (int *) astFree( (void *) outperm ); inperm = (int *) astFree( (void *) inperm ); consts = (double *) astFree( (void *) consts ); } /* Free the memory used to hold the new matrix elements. */ out_mat = (double *) astFree( (void *) out_mat ); /* Ensure the supplied MatrixMap is stored back in compressed form. */ CompressMatrix( mm, status ); /* Re-instate the original value of the Invert attribute of the supplied PermMap. */ astSetInvert( pm, old_pinv ); if( astOK ) { /* Annul the supplied PermMap. */ (void) astAnnul( pm ); /* Simplify the returned Mappings. */ spmnew = astSimplify( pmnew ); pmnew = astAnnul( pmnew ); smmnew = astSimplify( mmnew ); mmnew = astAnnul( mmnew ); /* Store a pointer to the new PermMap in place of the supplied MatrixMap. This PermMap should be used in its forward direction. */ maps[ imm ] = (AstMapping *) spmnew; inverts[ imm ] = astGetInvert( spmnew ); /* Annul the supplied matrixMap. */ (void) astAnnul( mm ); /* Store a pointer to the new MatrixMap. This MatrixMap should be used in its forward direction. */ maps[ 1 - imm ] = (AstMapping *) smmnew; inverts[ 1 - imm ] = astGetInvert( smmnew ); } /* Return. */ return; } static void MatWin( AstMapping **maps, int *inverts, int imm, int *status ){ /* * Name: * MatWin * Purpose: * Swap a WinMap and a MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void MatWin( AstMapping **maps, int *inverts, int imm, int *status ) * Class Membership: * WinMap member function * Description: * A list of two Mappings is supplied containing a WinMap and a * MatrixMap. These Mappings are annulled, and replaced with * another pair of Mappings consisting of a WinMap and a MatrixMap * in the opposite order. These Mappings are chosen so that their * combined effect is the same as the original pair of Mappings. * The scale factors in the returned WinMap are always unity (i.e. * the differences in scaling get absorbed into the returned * MatrixMap). * Parameters: * maps * A pointer to an array of two Mapping pointers. * inverts * A pointer to an array of two invert flags. * imm * The index within "maps" of the MatrixMap. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMatrixMap *m1; /* Pointer to Diagonal scale factor MatrixMap */ AstMatrixMap *m2; /* Pointer to returned MatrixMap */ AstMatrixMap *sm2; /* Pointer to simplified returned MatrixMap */ AstMatrixMap *mm; /* Pointer to the supplied MatrixMap */ AstPointSet *pset1; /* Shift terms from supplied WinMap */ AstPointSet *pset2; /* Shift terms for returned WinMap */ AstWinMap *w1; /* Pointer to the returned WinMap */ AstWinMap *sw1; /* Pointer to the simplified returned WinMap */ AstWinMap *wm; /* Pointer to the supplied WinMap */ double **ptr1; /* Pointer to pset1 data */ double **ptr2; /* Pointer to pset2 data */ double *a; /* Array of shift terms from supplied WinMap */ double *aa; /* Pointer to next shift term */ double *b; /* Array of scale terms from supplied WinMap */ double *bb; /* Pointer to next scale term */ int i; /* Axis count */ int nin; /* No. of axes in supplied WinMap */ int nout; /* No. of axes in returned WinMap */ int old_minv; /* Invert value for the supplied MatrixMap */ int old_winv; /* Invert value for the supplied WinMap */ /* Check the global error status. */ if ( !astOK ) return; /* Store pointers to the supplied WinMap and the MatrixMap. */ wm = (AstWinMap *) maps[ 1 - imm ]; mm = (AstMatrixMap *) maps[ imm ]; /* Temporarily set the Invert attribute of the supplied Mappings to the supplied values. */ old_winv = astGetInvert( wm ); astSetInvert( wm, inverts[ 1 - imm ] ); old_minv = astGetInvert( mm ); astSetInvert( mm, inverts[ imm ] ); /* Get copies of the shift and scale terms used by the WinMap. This also returns the number of axes in the WinMap. */ nin = astWinTerms( wm, &a, &b ); /* Create a diagonal MatrixMap holding the scale factors from the supplied WinMap. */ m1 = astMatrixMap( nin, nin, 1, b, "", status ); /* Create a PointSet holding a single position given by the shift terms in the supplied WinMap. */ pset1 = astPointSet( 1, nin, "", status ); ptr1 = astGetPoints( pset1 ); if( astOK ){ aa = a; for( i = 0; i < nin; i++ ) ptr1[ i ][ 0 ] = *(aa++); } /* First deal with cases when the WinMap is applied first, followed by the MatrixMap. */ if( imm == 1 ){ /* Multiply the diagonal matrix holding the WinMap scale factors by the supplied matrix. The resulting MatrixMap is the one to return in the map list. */ m2 = astMtrMult( m1, mm ); /* Transform the position given by the shift terms from the supplied WinMap using the supplied MatrixMap to get the shift terms for the returned WinMap. */ pset2 = astTransform( mm, pset1, 1, NULL ); /* Now deal with cases when the MatrixMap is applied first, followed by the WinMap. */ } else { /* Multiply the supplied MatrixMap by the diagonal matrix holding scale factors from the supplied WinMap. The resulting MatrixMap is the one to return in the map list. */ m2 = astMtrMult( mm, m1 ); /* Transform the position given by the shift terms from the supplied WinMap using the inverse of the returned MatrixMap to get the shift terms for the returned WinMap. */ pset2 = astTransform( m2, pset1, 0, NULL ); } /* Re-instate the original value of the Invert attributes of the supplied Mappings. */ astSetInvert( wm, old_winv ); astSetInvert( mm, old_minv ); /* Get pointers to the shift terms for the returned WinMap. */ ptr2 = astGetPoints( pset2 ); /* Create the returned WinMap, initially with undefined corners. The number of axes in the WinMap must equal the number of shift terms. */ nout = astGetNcoord( pset2 ); w1 = astWinMap( nout, NULL, NULL, NULL, NULL, "", status ); /* If succesful, store the scale and shift terms in the WinMap. The scale terms are always unity. */ if( astOK ){ bb = w1->b; aa = w1->a; for( i = 0; i < nout; i++ ) { *(bb++) = 1.0; *(aa++) = ptr2[ i ][ 0 ]; } /* Replace the supplied Mappings and invert flags with the ones found above. Remember that the order of the Mappings is now swapped */ (void) astAnnul( maps[ 0 ] ); (void) astAnnul( maps[ 1 ] ); sw1 = astSimplify( w1 ); w1 = astAnnul( w1 ); maps[ imm ] = (AstMapping *) sw1; inverts[ imm ] = astGetInvert( sw1 ); sm2 = astSimplify( m2 ); m2 = astAnnul( m2 ); maps[ 1 - imm ] = (AstMapping *) sm2; inverts[ 1 - imm ] = astGetInvert( sm2 ); } /* Annul the MatrixMap and PointSet holding the scale and shift terms from the supplied WinMap. */ m1 = astAnnul( m1 ); pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free the copies of the scale and shift terms from the supplied WinMap. */ b = (double *) astFree( (void *) b ); a = (double *) astFree( (void *) a ); /* Return. */ return; } static AstMatrixMap *MatZoom( AstMatrixMap *mm, AstZoomMap *zm, int minv, int zinv, int *status ){ /* * Name: * MatZoom * Purpose: * Create a MatrixMap by merging a MatrixMap and a ZoomMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *MatZoom( AstMatrixMap *mm, AstZoomMap *zm, int minv, * int zinv, int *status ) * Class Membership: * MatrixMap member function * Description: * This function creates a new MatrixMap which performs a mapping * equivalent to applying the two supplied Mappings in series in the * directions specified by the "invert" flags (the Invert attributes of * the supplied MatrixMaps are ignored). * Parameters: * mm * A pointer to the MatrixMap. * zm * A pointer to the ZoomMap. * minv * The invert flag to use with mm. A value of zero causes the forward * mapping to be used, and a non-zero value causes the inverse * mapping to be used. * zinv * The invert flag to use with zm. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the new MatrixMap. * Notes: * - The forward direction of the returned MatrixMap is equivalent to the * combined effect of the two supplied Mappings, operating in the * directions specified by "zinv" and "minv". * - 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: */ AstMatrixMap *mm2; /* Pointer to intermediate MatrixMap */ AstMatrixMap *result; /* Pointer to output MatrixMap */ double *matrix; /* Pointer to diagonal matrix elements array */ double zfac; /* Zoom factor */ int i; /* Axis index */ int nrow; /* No. of rows in the MatrixMap */ int old_minv; /* Original setting of MatrixMap Invert attribute */ int old_zinv; /* Original setting of ZoomMap Invert attribute */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the returned pointer. */ result = NULL; /* Temporarily set the Invert attributes of both Mappings to the supplied values. */ old_minv = astGetInvert( mm ); astSetInvert( mm, minv ); old_zinv = astGetInvert( zm ); astSetInvert( zm, zinv ); /* Get the number of rows in the MatrixMap (i.e. the number of output axes). */ nrow = astGetNout( mm ); /* Get the zoom factor implemented by the ZoomMap. Invert it if necessary since astGetZoom does not take account of the Invert setting. */ zfac = astGetZoom( zm ); if( zinv ) zfac = 1.0 / zfac; /* Create a diagonal matrix map in which each diagonal element is equal to the zoom factor. */ matrix = (double *) astMalloc( sizeof( double )*(size_t) nrow ); if( astOK ) { for( i = 0; i < nrow; i++ ) matrix[ i ] = zfac; } mm2 = astMatrixMap( nrow, nrow, 1, matrix, "", status ); matrix = (double *) astFree( (void *) matrix ); /* Create a new MatrixMap holding the product of the supplied MatrixMap and the diagonal MatrixMap just created. */ result = astMtrMult( mm, mm2 ); mm2 = astAnnul( mm2 ); /* Re-instate the original settings of the Invert attribute for the supplied Mappings. */ astSetInvert( mm, old_minv ); astSetInvert( zm, old_zinv ); /* If an error has occurred, annull the returned MatrixMap. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output MatrixMap. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ static AstMatrixMap *MtrMult( AstMatrixMap *this, AstMatrixMap *a, int *status ){ /* *+ * Name: * astMtrMult * Purpose: * Multiply a MatrixMap by another MatrixMap. * Type: * Protected virtual function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *MtrMult( astMatrixMap *this, astMatrixMap *a ) * Class Membership: * MatrixMap method * Description: * This function multiples the matrices given by "this" and "a", returning * a pointer to a new MatrixMap holding the product "a x this". * * The number of columns in the "a" matrix must match the number of * rows in the "this" matrix. The number of rows in the returned * MatrixMap is equal to the number of rows in "a", and the number of * columns is the same as the number of rows in "this". * Parameters: * this * Pointer to the first MatrixMap. * a * Pointer to a second MatrixMap. * Returned Value: * A pointer to the product MatrixMap. * Notes: * - An error is reported if the two MatrixMaps have incompatible * shapes, or if either MatrixMap does not have a defined forward * transformation. * - A null Object pointer 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. */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMatrixMap *new; /* New MatrixMap holding the product matrix */ double *a_matrix; /* Pointer to the forward "a" matrix */ double *a_row; /* Pointer to start of current row in "a" */ double a_val; /* Current element value from "a" */ double factor; /* Diagonal matrix term */ double *new_matrix; /* Pointer to the new forward "this" matrix */ double *new_val; /* Pointer to current output element value */ double sum; /* Dot product value */ double *this_col; /* Pointer to start of current column in "this" */ double *this_matrix; /* Pointer to the forward "this" matrix */ double this_val; /* Current element value from "this" */ int col; /* Current output column number */ int i; /* Loop count */ int minrow; /* Min. number of rows in "a" or "this" */ int ncol_a; /* No. of columns in the "a" MatrixMap */ int ncol_this; /* No. of columns in the "this" MatrixMap */ int nrow_a; /* No. of rows in the "a" MatrixMap */ int nrow_this; /* No. of rows in the "this" MatrixMap */ int row; /* Current output row number */ /* Return a NULL pointer if an error has already occurred. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise */ new = NULL; /* Report an error if eitherof the MatrixMaps doe snot have a defined forward transformation.*/ if( !astGetTranForward( this ) ){ astError( AST__MTRML, "astMtrMult(%s): Cannot find the product of 2 " "MatrixMaps- the first MatrixMap has no forward transformation.", status, astClass(this) ); return NULL; } if( !astGetTranInverse( this ) ){ astError( AST__MTRML, "astMtrMult(%s): Cannot find the product of 2 " "MatrixMaps- the second MatrixMap has no forward transformation.", status, astClass(this) ); return NULL; } /* Report an error if the shapes of the two matrices are incompatible. */ nrow_a = astGetNout( a ); ncol_a = astGetNin( a ); nrow_this = astGetNout( this ); ncol_this = astGetNin( this ); if( ncol_a != nrow_this && astOK ){ astError( AST__MTRML, "astMtrMult(%s): Number of rows in the first " "MatrixMap (%d) does not equal number of columns in the " "second MatrixMap (%d).", status, astClass(this), nrow_this, ncol_a ); return NULL; } /* Store the minimum number of rows in either matrix for later use. */ if( nrow_a < nrow_this ){ minrow = nrow_a; } else { minrow = nrow_this; } /* Ensure that "this" is stored in FULL form (i.e. with all elements stored explicitly, even if the matrix is a unit or diagonal matrix). */ ExpandMatrix( this, status ); /* Store pointers to the current forward matrices (taking into account the current states of the Mapping inversion flags ). */ this_matrix = astGetInvert( this ) ? this->i_matrix : this->f_matrix; a_matrix = astGetInvert( a ) ? a->i_matrix : a->f_matrix; /* Get memory to hold the product matrix in full form. */ new_matrix = (double *) astMalloc( sizeof( double )* (size_t)( nrow_a*ncol_this ) ); if( astOK ){ /* First deal with cases where the "a" MatrixMap represents a unit matrix. */ if( a->form == UNIT ){ /* Copy the required number of rows from "this" to "new". */ (void) memcpy( (void *) new_matrix, (const void *) this_matrix, sizeof(double)*(size_t)( minrow*ncol_this ) ); /* If there are insufficient rows in "this", append some zero-filled rows. */ if( minrow < nrow_a ){ for( i = minrow*ncol_this; i < nrow_a*ncol_this; i++ ){ new_matrix[ i ] = 0.0; } } /* Now deal with cases where the "a" MatrixMap represents a diagonal matrix. */ } else if( a->form == DIAGONAL ){ /* Scale the required number of rows from "this" storing them in "new", and checking for bad values. */ i = 0; for( row = 0; row < minrow; row++ ){ factor = a_matrix[ row ]; if( factor != AST__BAD ){ for( col = 0; col < ncol_this; col++ ){ this_val = this_matrix[ i ]; if( this_val != AST__BAD ){ new_matrix[ i ] = this_val*factor; } else { new_matrix[ i ] = AST__BAD; } i++; } } else { for( col = 0; col < ncol_this; col++ ){ new_matrix[ i++ ] = AST__BAD; } } } /* If there are insufficient rows in "this", append some zero-filled rows. */ if( minrow < nrow_a ){ for( i = minrow*ncol_this; i < nrow_a*ncol_this; i++ ){ new_matrix[ i ] = 0.0; } } /* Now deal with cases where the "a" MatrixMap represents a full, non-diagonal matrix. */ } else { /* Initialise a pointer to the next element in the product matrix. */ new_val = new_matrix; /* Get a pointer to the start of each row of the "a" matrix. */ for( row = 0; row < nrow_a; row++ ){ a_row = a_matrix + ncol_a*row; /* Get a pointer to the start of each column of the "this" matrix. */ for( col = 0; col < ncol_this; col++ ){ this_col = this_matrix + col; /* Form the dot product of the current row from "a", and the current column from "this", checking for bad values. */ sum = 0.0; for( i = 0; i < ncol_a; i++ ){ a_val = a_row[ i ]; this_val = this_col[ i*ncol_this ]; if( a_val != AST__BAD && this_val != AST__BAD ){ sum += a_val*this_val; } else { sum = AST__BAD; break; } } /* Store the output matrix element value. */ *(new_val++) = sum; } } } /* Create the new MatrixMap. */ new = astInitMatrixMap( NULL, sizeof( AstMatrixMap ), !class_init, &class_vtab, "MatrixMap", ncol_this, nrow_a, FULL, new_matrix ); /* If possible, compress the new MatrixMap by removing off-diagonal zero elements. */ CompressMatrix( new, status ); /* Re-compress the original "this" MatrixMap. */ CompressMatrix( this, status ); } /* Free the memory used to hold the product matrix in full form. */ new_matrix = (double *) astFree( (void *) new_matrix ); return new; } static AstMatrixMap *MtrRot( AstMatrixMap *this, double theta, const double axis[], int *status ){ /* *+ * Name: * astMtrRot * Purpose: * Multiply a MatrixMap by a rotation matrix. * Type: * Protected virtual function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *astMtrRot( astMatrixMap *this, double theta, * const double axis[] ) * Class Membership: * MatrixMap method. * Description: * This function creates a new MatrixMap which is a copy of "this", * rotated by a specified angle. It can only be used on MatrixMaps which * have either 2 or 3 output coordinates. In the 3-D case, the rotation * is about an arbitrary axis passing through the origin. * Parameters: * this * Pointer to the MatrixMap. * theta * The angle by which to rotate the matrix, in radians. If the matrix * is applied to a 2-D vector position, the resulting vector is * rotated clockwise about the origin (i.e. from the positive direction * of the second axis to the positive direction of the first axis). If * the vector positions are three dimensional, the rotation is clockwise * when looking along the vector given by "axis". Note, "theta" measures f when looking along the vector given by AXIS. Note, THETA measures * the movemement of the vectors relative to a fixed reference frame. * Alternatively, the reference frame can be thought of as rotating by * (-theta) relative to the fixed vectors. * axis * A 3-D vector specifying the axis of rotation. This parameter is * ignored if the output from MatrixMap is 2-dimensional. * Returned Value: * A pointer to the rotated MatrixMap. * Notes: * - A null Object pointer 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. */ AstMatrixMap *new; /* New MatrixMap holding the rotated matrix */ double as,a,b,c,d,e,f,g; /* Intermediate quantities */ double axlen; /* Length of axis vector */ double axlen2; /* Squared length of axis vector */ double costh; /* Cos(rotation angle) */ double sinth; /* Sin(rotation angle) */ double rotmat[9]; /* Rotation matrix */ double work[3]; /* Work space for matrix multiplication */ int ncol; /* No. of columns in the MatrixMap */ int nrow; /* No. of rows in the MatrixMap */ /* Return a NULL pointer if an error has already occurred. */ if ( !astOK ) return NULL; /* Initialise the returned MarixMap to be a copy of the supplied MatrixMap. */ new = astCopy( this ); /* Save the cos and sin of the rotation angle for future use. */ costh = cos( theta ); sinth = sin( theta ); /* Return without changing the MatrixMap if the rotation angle is a multiple of 360 degrees. */ if ( costh == 1.0 ) return new; /* Get the dimensions of the MatrixMap. */ nrow = astGetNout( new ); ncol = astGetNin( new ); /* First do rotation of a plane about the origin. */ if( nrow == 2 ){ /* Ensure that the MatrixMap is stored in full form rather than compressed form. */ ExpandMatrix( new, status ); /* Form the 2x2 forward rotation matrix. Theta is the clockwise angle of rotation. */ rotmat[0] = costh; rotmat[1] = sinth; rotmat[2] = -sinth; rotmat[3] = costh; /* Post-multiply the current forward matrix (depending on whether or not the MatrixMap has been inverted) by the forward rotation matrix. */ if( !astGetInvert( new ) ){ SMtrMult( 1, 2, ncol, rotmat, new->f_matrix, work, status ); } else { SMtrMult( 1, 2, ncol, rotmat, new->i_matrix, work, status ); } /* Now form the 2x2 inverse rotation matrix (the diagonal elements don't change). */ rotmat[1] = -sinth; rotmat[2] = sinth; /* Pre-multiply the current inverse matrix (depending on whether or not the MatrixMap has been inverted) by the inverse rotation matrix. */ if( !astGetInvert( new ) ){ SMtrMult( 0, ncol, 2, rotmat, new->i_matrix, work, status ); } else { SMtrMult( 0, ncol, 2, rotmat, new->f_matrix, work, status ); } /* See if the matrix can be stored as a UNIT or DIAGONAL matrix. */ CompressMatrix( new, status ); /* Now do rotation of a volume about an axis passing through the origin. */ } else if( nrow == 3 ){ /* Find the length of the axis vector. Report an error if it has zero length or has not been supplied. */ if( axis ) { axlen2 = axis[0]*axis[0] + axis[1]*axis[1] + axis[2]*axis[2]; } else { axlen2 = 0.0; } if( axlen2 <= 0.0 ) { astError( AST__MTRAX, "astMtrRot(%s): NULL or zero length " "axis vector supplied.", status, astClass(new) ); } axlen = sqrt( axlen2 ); /* Ensure that the MatrixMap is stored in full form rather than compressed form. */ ExpandMatrix( new, status ); /* Form commonly used terms in the rotation matrix. */ as = sinth/axlen; a = (1.0 - costh)/axlen2; b = a*axis[0]*axis[1]; c = as*axis[2]; d = a*axis[0]*axis[2]; e = as*axis[1]; f = a*axis[1]*axis[2]; g = as*axis[0]; /* Form the 3x3 forward rotation matrix. Theta is the clockwise angle of rotation looking in the direction of the axis vector. */ rotmat[0] = a*axis[0]*axis[0] + costh; rotmat[1] = b - c; rotmat[2] = d + e; rotmat[3] = b + c; rotmat[4] = a*axis[1]*axis[1] + costh; rotmat[5] = f - g; rotmat[6] = d - e; rotmat[7] = f + g; rotmat[8] = a*axis[2]*axis[2] + costh; /* Post-multiply the current forward matrix (depending on whether or not the MatrixMap has been inverted) by the forward rotation matrix. */ if( !astGetInvert( new ) ){ SMtrMult( 1, 3, ncol, rotmat, new->f_matrix, work, status ); } else { SMtrMult( 1, 3, ncol, rotmat, new->i_matrix, work, status ); } /* Now form the 3x3 inverse rotation matrix (the diagonal elements don't change). */ rotmat[1] = b + c; rotmat[2] = d - e; rotmat[3] = b - c; rotmat[5] = f + g; rotmat[6] = d + e; rotmat[7] = f - g; /* Pre-multiply the current inverse matrix (depending on whether or not the MatrixMap has been inverted) by the inverse rotation matrix. */ if( !astGetInvert( new ) ){ SMtrMult( 0, ncol, 3, rotmat, new->i_matrix, work, status ); } else { SMtrMult( 0, ncol, 3, rotmat, new->f_matrix, work, status ); } /* See if the matrix can be stored as a UNIT or DIAGONAL matrix. */ CompressMatrix( new, status ); /* Report an error if the matrix is not suitable for rotation. */ } else { astError( AST__MTR23, "astMtrRot(%s): Cannot rotate a %dx%d" " MatrixMap.", status, astClass(new), nrow, ncol ); } /* Delete the new MatrixMap if an error has occurred. */ if( !astOK ) new = astDelete( new ); return new; } static void PermGet( AstPermMap *map, int **outperm, int **inperm, double **consts, int *status ){ /* * Name: * PermGet * Purpose: * Get the axis permutation and constants array for a PermMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void PermGet( AstPermMap *map, int **outperm, int **inperm, * double **const, int *status ) * Class Membership: * MatrixMap member function * Description: * This function returns axis permutation and constants arrays which can * be used to create a PermMap which is equivalent to the supplied PermMap. * Parameters: * map * The PermMap. * outperm * An address at which to return a popinter to an array of ints * holding the output axis permutation array. The array should be * released using astFree when no longer needed. * inperm * An address at which to return a popinter to an array of ints * holding the input axis permutation array. The array should be * released using astFree when no longer needed. * consts * An address at which to return a popinter to an array of doubles * holding the constants array. The array should be released using * astFree when no longer needed. * status * Pointer to the inherited status variable. * Notes: * - NULL pointers are returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding input positions for PermMap */ AstPointSet *pset2; /* PointSet holding output positions for PermMap */ double **ptr1; /* Pointer to pset1 data */ double **ptr2; /* Pointer to pset2 data */ double *cnst; /* Pointer to constants array */ double cn; /* Potential new constant value */ double ip; /* Potential output axis index */ double op; /* Potential input axis index */ int *inprm; /* Pointer to input axis permutation array */ int *outprm; /* Pointer to output axis permutation array */ int i; /* Axis count */ int nc; /* Number of constants stored so far */ int nin; /* No. of input coordinates for the PermMap */ int nout; /* No. of output coordinates for the PermMap */ /* Initialise. */ if( outperm ) *outperm = NULL; if( inperm ) *inperm = NULL; if( consts ) *consts = NULL; /* Check the global error status and the supplied pointers. */ if ( !astOK || !outperm || !inperm || !consts ) return; /* Get the number of input and output axes for the supplied PermMap. */ nin = astGetNin( map ); nout = astGetNout( map ); /* Allocate the memory for the returned arrays. */ outprm = (int *) astMalloc( sizeof( int )* (size_t) nout ); inprm = (int *) astMalloc( sizeof( int )* (size_t) nin ); cnst = (double *) astMalloc( sizeof( double )* (size_t) ( nout + nin ) ); /* Returned the pointers to these arrays.*/ *outperm = outprm; *inperm = inprm; *consts = cnst; /* Create two PointSets, each holding two points, which can be used for input and output positions with the PermMap. */ pset1 = astPointSet( 2, nin, "", status ); pset2 = astPointSet( 2, nout, "", status ); /* Set up the two input positions to be [0,1,2...] and [-1,-1,-1,...]. The first position is used to enumerate the axes, and the second is used to check for constant axis values. */ ptr1 = astGetPoints( pset1 ); if( astOK ){ for( i = 0; i < nin; i++ ){ ptr1[ i ][ 0 ] = ( double ) i; ptr1[ i ][ 1 ] = -1.0; } } /* Use the PermMap to transform these positions in the forward direction. */ (void) astTransform( map, pset1, 1, pset2 ); /* No constant axis valeus found yet. */ nc = 0; /* Look at the mapped positions to determine the output axis permutation array. */ ptr2 = astGetPoints( pset2 ); if( astOK ){ /* Do each output axis. */ for( i = 0; i < nout; i++ ){ /* If the output axis value is copied from an input axis value, the index of the appropriate input axis will be in the mapped first position. */ op = ptr2[ i ][ 0 ]; /* If the output axis value is assigned a constant value, the result of mapping the two different input axis values will be the same. */ cn = ptr2[ i ][ 1 ]; if( op == cn ) { /* We have found another constant. Store it in the constants array, and store the index of the constant in the output axis permutation array. */ cnst[ nc ] = cn; outprm[ i ] = -( nc + 1 ); nc++; /* If the output axis values are different, then the output axis value must be copied from the input axis value. */ } else { outprm[ i ] = (int) ( op + 0.5 ); } } } /* Now do the same thing to determine the input permutation array. */ if( astOK ){ for( i = 0; i < nout; i++ ){ ptr2[ i ][ 0 ] = ( double ) i; ptr2[ i ][ 1 ] = -1.0; } } (void) astTransform( map, pset2, 0, pset1 ); if( astOK ){ for( i = 0; i < nin; i++ ){ ip = ptr1[ i ][ 0 ]; cn = ptr1[ i ][ 1 ]; if( ip == cn ) { cnst[ nc ] = cn; inprm[ i ] = -( nc + 1 ); nc++; } else { inprm[ i ] = (int) ( ip + 0.5 ); } } } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* If an error has occurred, attempt to free the returned arrays. */ if( !astOK ) { *outperm = (int *) astFree( (void *) *outperm ); *inperm = (int *) astFree( (void *) *inperm ); *consts = (double *) astFree( (void *) *consts ); } /* Return. */ return; } static int PermOK( AstMapping *pm, int *status ){ /* * Name: * PermOK * Purpose: * Determine if a PermMap can be merged with a MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int PermOK( AstMapping *pm, int *status ) * Class Membership: * PermMap member function * Description: * This function returns a flag indicating if the supplied PermMap * could be merged with a MatrixMap. For thios to be possible, the * PermMap must have the same number of input and output axes, and the * inverse and forward mappings must be consistent. * Parameters: * pm * The PermMap. * status * Pointer to the inherited status variable. * Returned Value: * 1 if the PermMap can be merged, 0 otherwise. * Notes: * - A value of 0 is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding input positions for PermMap */ AstPointSet *pset2; /* PointSet holding output positions for PermMap */ double **ptr1; /* Pointer to pset1 data */ int i; /* Loop count */ int nin; /* No. of input coordinates for the PermMap */ int nout; /* No. of output coordinates for the PermMap */ int ret; /* Returned flag */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise */ ret = 0; /* The PermMap must have the same number of input and output coordinates. */ nin = astGetNin( pm ); nout = astGetNout( pm ); if( nin == nout ){ /* Create two PointSets, each holding two points, which can be used for the input and output positions with the PermMap. */ pset1 = astPointSet( 2, nin, "", status ); pset2 = astPointSet( 2, nout, "", status ); /* Set up the two input positions to be [1,2,3...] and [0,-1,-2,...] */ ptr1 = astGetPoints( pset1 ); if( astOK ){ for( i = 0; i < nin; i++ ){ ptr1[ i ][ 0 ] = ( double )( i + 1 ); ptr1[ i ][ 1 ] = ( double )( -i ); } } /* Use the PermMap to transform these positions in the forward direction. */ (void) astTransform( pm, pset1, 1, pset2 ); /* Now transform the results back again using the inverse PermMap. */ (void) astTransform( pm, pset2, 0, pset1 ); /* See if the input positions have changed. If they have, then the PermMap does not have a consistent pair of transformations. If they have not, then the transformations must be consistent because we used two different input positions and only one could come out unchanged by chance. */ if( astOK ){ ret = 1; for( i = 0; i < nin; i++ ){ if( ptr1[ i ][ 0 ] != ( double )( i + 1 ) || ptr1[ i ][ 1 ] != ( double )( -i ) ){ ret = 0; break; } } } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); } /* Return the answer. */ return astOK ? ret : 0; } static double Rate( AstMapping *this, 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 "matrixmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * MatrixMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ /* Local Variables: */ AstMatrixMap *map; double *matrix; double result; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the MatrixMap structure. */ map = (AstMatrixMap *) this; /* Get a pointer to the array holding the required matrix elements, according to whether the MatrixMap has been inverted. */ if( !astGetInvert( this ) ) { matrix = map->f_matrix; } else { matrix = map->i_matrix; } /* First deal with full MatrixMaps in which all matrix elements are stored. */ if( map->form == FULL ){ result = matrix[ ax1*astGetNin( this ) + ax2 ]; /* For unit matrices, the rate is unity if the input and output axes are equal, and zero otherwise. */ } else if( map->form == UNIT ){ result = (ax1 == ax2 ) ? 1.0 : 0.0; /* For diagonal matrices, the rate is zero for off diagonal elements and the matrix array stored the on-diagonal rates. */ } else if( ax1 == ax2 ) { result = matrix[ ax1 ]; } else { result = 0.0; } /* Return the result. */ return result; } static void SMtrMult( int post, int m, int n, const double *mat1, double *mat2, double *work, int *status ){ /* * Name: * SMtrMult * Purpose: * Multiply a square matrix and a non-square matrix. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * void SMtrMult( int post, int m, int n, const double *mat1, * double *mat2, double *work, int *status ) * Class Membership: * MatrixMap member function. * Description: * The matrix pointed to by "mat2" is modified by multiplying it by * the square matrix pointed to by "mat1". If "post" is 1, then: * * mat2 -> mat1*mat2 (mat1 is mxm and mat2 is mxn) * * If "post" is zero, then: * * mat2 -> mat2*mat1 (mat1 is nxn and mat2 is mxn) * * The restriction that "mat1" must be square is imposed so that the * returned matrix will have the same shape as the supplied matrix (mat1). * Parameters: * post * Specifies whether to post- or pre- multiply mat2 by mat1. * m * The number of rows in mat2. * n * The number of columns in mat2. * mat1 * The multiplier matrix. It must be square of size m or n, depending * on "post". * mat2 * The multiplicand matrix. * work * Pointer to work space containing room for m doubles (if "post" * is 1), or n doubles (if "post" is 0). * status * Pointer to the inherited status variable. * Notes: * - No error is reported if "mat2" is supplied NULL. In this case * it will also be returned NULL. */ /* Local Variables */ double dot; /* Output matrix element value */ const double *mat1_col; /* Pointer to start of current column of mat1 */ const double *mat1_row; /* Pointer to start of current row of mat1 */ double *mat2_col; /* Pointer to start of current column of mat2 */ double *mat2_row; /* Pointer to start of current row of mat2 */ double cel; /* Column element value */ double rel; /* Row element value */ int i; /* Index of current output row */ int j; /* Index of current output column */ int k; /* Dot product index */ /* Do nothing if mat2 is NULL */ if ( mat2 ){ /* First deal with cases where the supplied matrix is post-multiplied (i.e. the returned matrix is mat1*mat2). */ if( post ){ /* Loop round each column of the output matrix, storing a pointer to the start of the corresponding column of mat2. */ for( j=0; jform == UNIT ) { result = 1; /* Otherwise, check that the appropriate array is defined in the MatrixMap. */ } else { /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* If OK, obtain the result. */ if ( astOK ) { if( invert ){ result = ( map->i_matrix != NULL ); } else { result = ( map->f_matrix != NULL ); } } } /* Return the result. */ return result; } static int GetTranInverse( AstMapping *this, int *status ) { /* * * Name: * GetTranInverse * Purpose: * Determine if a MatrixMap defines an inverse coordinate transformation. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int GetTranInverse( AstMapping *this, int *status ) * Class Membership: * MatrixMap member function (over-rides the astGetTranInverse method * inherited from the Mapping class). * Description: * This function returns a value indicating if the MatrixMap is able * to perform an inverse coordinate transformation. * Parameters: * this * Pointer to the MatrixMap. * status * Pointer to the inherited status variable. * 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: */ AstMatrixMap *map; /* Pointer to MatrixMap to be queried */ int invert; /* Has the mapping been inverted? */ int result; /* The returned value */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the MatrixMap. */ map = (AstMatrixMap *) this; /* All unit MatrixMaps are defined in both directions. */ if( map->form == UNIT ) { result = 1; /* Otherwise, check that the appropriate array is defined in the MatrixMap. */ } else { /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* If OK, obtain the result. */ if ( astOK ) { if( invert ){ result = ( map->f_matrix != NULL ); } else { result = ( map->i_matrix != NULL ); } } } /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a MatrixMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * MatrixMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a MatrixMap and a set of points encapsulated in a * PointSet and transforms the points by multiplying them by the matrix. * Parameters: * this * Pointer to the MatrixMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of columns in the MatrixMap being applied. * - The number of coordinate values per point in the output PointSet will * equal the number of rows in the MatrixMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstMatrixMap *map; /* Pointer to MatrixMap to be applied */ double diag_term; /* Current diagonal element value */ double *indata; /* Pointer to next input data value */ double *matrix; /* Pointer to start of matrix element array */ double *matrix_element; /* Pointer to current matrix element value */ double *outdata; /* Pointer to next output data value */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double sum; /* Partial output value */ double val; /* Data value */ int in_coord; /* Index of output coordinate */ int nax; /* Output axes for which input axes exist */ int ncoord_in; /* Number of coordinates per input point */ int ncoord_out; /* Number of coordinates per output point */ int npoint; /* Number of points */ int out_coord; /* Index of output coordinate */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the MatrixMap. */ map = (AstMatrixMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input and output PointSets and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); ncoord_out = astGetNcoord( result ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Get a pointer to the array holding the required matrix elements, according to the direction of mapping required. */ if ( forward ) { matrix = map->f_matrix; } else { matrix = map->i_matrix; } /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* First deal with full MatrixMaps in which all matrix elements are stored. */ if( map->form == FULL ){ /* Loop to apply the matrix to each point in turn, checking for (and propagating) bad values in the process. The matrix elements are accessed sequentially in row order. The next matrix element to be used is identified by a pointer which is initialised to point to the first element of the matrix prior to processing each point. */ for ( point = 0; point < npoint; point++ ) { matrix_element = matrix; /* Each output co-ordinate value is created by summing the product of the corresponding input co-ordinates and the elements of one row of the matrix. */ for ( out_coord = 0; out_coord < ncoord_out; out_coord++ ) { sum = 0.0; for ( in_coord = 0; in_coord < ncoord_in; in_coord++ ) { /* Check the current input coordinate value and the current matrix element. If the coordinate value is bad, then the output value will also be bad unless the matrix element is zero. That is, a zero matrix element results in the input coordinate value being ignored, even if it is bad. This prevents bad input values being propagated to output axes which are independant of the bad input axis. A bad matrix element always results in the output value being bad. In either of these cases, break out of the loop, remembering to advance the pointer to the next matrix element so that it points to the start of the next row ready for doing the next output coordinate. */ if ( ( ptr_in[ in_coord ][ point ] == AST__BAD && (*matrix_element) != 0.0 ) || (*matrix_element) == AST__BAD ) { sum = AST__BAD; matrix_element += ncoord_in - in_coord; break; /* If the input coordinate and the current matrix element are both valid, increment the sum by their product, and step to the next matrix element pointer If we arrive here with a bad input value, then the matrix element must be zero, in which case the running sum is left unchanged. */ } else { if ( ptr_in[ in_coord ][ point ] != AST__BAD ) { sum += ptr_in[ in_coord ][ point ] * (*matrix_element); } matrix_element++; } } /* Store the output coordinate value. */ ptr_out[ out_coord ][ point ] = sum; } } /* Now deal with unit and diagonal MatrixMaps. */ } else { /* Find the number of output axes for which input data is available. */ if( ncoord_in < ncoord_out ){ nax = ncoord_in; } else { nax = ncoord_out; } /* For unit matrices, copy the input axes to the corresponding output axes. */ if( map->form == UNIT ){ for( out_coord = 0; out_coord < nax; out_coord++ ) { (void) memcpy( ptr_out[ out_coord ], (const void *) ptr_in[ out_coord ], sizeof( double )*(size_t)npoint ); } /* For diagonal matrices, scale each input axis using the appropriate diagonal element from the matrix, and store in the output. */ } else { for( out_coord = 0; out_coord < nax; out_coord++ ){ diag_term = matrix[ out_coord ]; outdata = ptr_out[ out_coord ]; indata = ptr_in[ out_coord ]; if( diag_term != AST__BAD ){ for( point = 0; point < npoint; point++ ){ val = *(indata++); if( val != AST__BAD ){ *(outdata++) = diag_term*val; } else { *(outdata++) = AST__BAD; } } } else { for( point = 0; point < npoint; point++ ){ *(outdata++) = AST__BAD; } } } } /* If there are any remaining output axes, fill the first one with zeros. */ if( nax < ncoord_out ){ outdata = ptr_out[ nax ]; for( point = 0; point < npoint; point++ ) *(outdata++) = 0.0; /* Copy this axis to any remaining output axes. */ outdata = ptr_out[ nax ]; for( out_coord = nax + 1; out_coord < ncoord_out; out_coord++ ) { (void) memcpy( ptr_out[ out_coord ], (const void *) outdata, sizeof( double )*(size_t)npoint ); } } } } /* Return a pointer to the output PointSet. */ return result; } static int ScalingRowCol( AstMatrixMap *map, int axis, int *status ){ /* * Name: * ScalingRowCol * Purpose: * Determine if a given row and column of a MatrixMap are zeros * with a non-zero diagonal term. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int ScalingRowCol( AstMatrixMap *map, int axis, int *status ) * Class Membership: * MatrixMap member function * Description: * This function returns a flag indicating if a MatrixMap presents a * simple scaling for a given axis in both directions. The MatrixMap * must be square. A value of one is returned if every element of the * row and column corresponding to the given axis is zero, except for * the diagonal term which must be non-zero. * Parameters: * map * The MatrixMap. * axis * The zero-based index of the axis to check. * status * Pointer to the inherited status variable. * Returned Value: * 1 if the row/column produces a simple scaling, 0 otherwise. */ /* Local Variables: */ double *el; /* Pointer to matrix element */ int i; /* Element count */ int ncol; /* No. of input coordinates */ int ret; /* Returned flag */ /* Initialise */ ret = 0; /* Check the global error status. */ if ( !astOK ) return ret; /* If a unit or diagonal MatrixMap has been supplied, return 1. */ if( map->form != FULL ){ ret = 1; /* If a full matrix has been supplied... */ } else { /* Assume the row/column gives a unit mapping. */ ret = 1; /* Get the number of input axes for the MatrixMap. */ ncol = astGetNin( map ); /* Check that all elements of the "axis"th row are effectively zero, except for the "axis"th element which must be non-zero. */ el = map->f_matrix + axis*ncol; for( i = 0; i < ncol; i++ ) { if( i == axis ) { if( fabs( *el ) <= DBL_EPSILON ) { ret = 0; break; } } else if( fabs( *el ) > DBL_EPSILON ) { ret = 0; break; } el++; } /* Check that all elements of the "axis"th column are effectively zero, except for the "axis"th element which must be non-zero. */ if( ret ) { el = map->f_matrix + axis; for( i = 0; i < ncol; i++ ) { if( i == axis ) { if( fabs( *el ) <= DBL_EPSILON ) { ret = 0; break; } } else if( fabs( *el ) > DBL_EPSILON ) { ret = 0; break; } el += ncol; } } } /* Return the answer. */ return astOK ? ret : 0; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for MatrixMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for MatrixMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the matrix * element values associated with the input MatrixMap. */ /* Local Variables: */ AstMatrixMap *in; /* Pointer to input MatrixMap */ AstMatrixMap *out; /* Pointer to output MatrixMap */ int nel; /* No. of elements in the matrix */ int nin; /* No. of input coordinates */ int nout; /* No. of output coordinates */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output MatrixMaps. */ in = (AstMatrixMap *) objin; out = (AstMatrixMap *) objout; /* Nullify the pointers stored in the output object since these will currently be pointing at the input data (since the output is a simple byte-for-byte copy of the input). Otherwise, the input data could be freed by accidient if the output object is deleted due to an error occuring in this function. */ out->f_matrix = NULL; out->i_matrix = NULL; /* If the input MatrixMap is a unit mapping, then no matrix elements are stored with it, so do nothing in this case. */ if( out->form != UNIT ){ /* Obtain the number of stored values in the MatrixMap. This is independant of whether the Mapping has been inverted or not. If the MatrixMap is diagonal, only the diagonal terms are stored. */ nin = astGetNin( in ); nout = astGetNout( in ); if( out->form == DIAGONAL ){ if( nin < nout ){ nel = nin; } else { nel = nout; } } else { nel = nin*nout; } /* Store the forward matrix elements in the output MatrixMap. */ out->f_matrix = (double *) astStore( NULL, (void *) in->f_matrix, sizeof( double )*(size_t) nel ); /* Store the inverse matrix elements (if defined) in the output MatrixMap. */ if( in->i_matrix ){ out->i_matrix = (double *) astStore( NULL, (void *) in->i_matrix, sizeof( double )*(size_t) nel ); } /* If an error has occurred, free the output MatrixMap arrays. */ if( !astOK ) { out->f_matrix = (double *) astFree( (void *) out->f_matrix ); out->i_matrix = (double *) astFree( (void *) out->i_matrix ); } } return; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for MatrixMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for MatrixMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstMatrixMap *this; /* Pointer to MatrixMap */ /* Obtain a pointer to the MatrixMap structure. */ this = (AstMatrixMap *) obj; /* Free the arrays used to store element values for forward and inverse matrices. */ this->f_matrix = (double *) astFree( (void *) this->f_matrix ); this->i_matrix = (double *) astFree( (void *) this->i_matrix ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for MatrixMap 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 MatrixMap class to an output Channel. * Parameters: * this * Pointer to the MatrixMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstMatrixMap *this; /* Pointer to the MatrixMap structure */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int el; /* Element index */ int nel; /* No. of elements in the matrix */ int nin; /* No. of input coords */ int nout; /* No. of output coords */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the MatrixMap structure. */ this = (AstMatrixMap *) this_object; /* Find the number of elements stored for each matrix. */ nin = astGetNin( this ); nout = astGetNout( this ); if( this->form == FULL ){ nel = nin*nout; } else if( this->form == DIAGONAL ){ nel = astMIN( nin, nout ); } else { nel = 0; } /* Write out values representing the instance variables for the MatrixMap class. */ /* The forward matrix. The inverse matrix not written out since it can be re-calculated when the MatrixMap is read back in. Note BAD values are not written out as the AST__BAD value may differ on different machines. If a matrix element is not found when reading the matrix back in again (in astLoadMatrixMap), then it is assigned a default value of AST__BAD. */ if( this->f_matrix ){ for( el = 0; el < nel; el++ ){ if( (this->f_matrix)[ el ] != AST__BAD ) { (void) sprintf( buff, "M%d", el ); astWriteDouble( channel, buff, 1, 1, (this->f_matrix)[ el ], "Forward matrix value" ); } } } /* The matrix storage form. */ astWriteString( channel, "Form", 1, 1, Form[ this->form ], "Matrix storage form" ); /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAMatrixMap and astCheckMatrixMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(MatrixMap,Mapping) astMAKE_CHECK(MatrixMap) AstMatrixMap *astMatrixMap_( int nin, int nout, int form, const double matrix[], const char *options, int *status, ...){ /* *++ * Name: c astMatrixMap f AST_MATRIXMAP * Purpose: * Create a MatrixMap. * Type: * Public function. * Synopsis: c #include "matrixmap.h" c AstMatrixMap *astMatrixMap( int nin, int nout, int form, c const double matrix[], c const char *options, ... ) f RESULT = AST_MATRIXMAP( NIN, NOUT, FORM, MATRIX, OPTIONS, STATUS ) * Class Membership: * MatrixMap constructor. * Description: * This function creates a new MatrixMap and optionally initialises * its attributes. * * A MatrixMap is a form of Mapping which performs a general linear * transformation. Each set of input coordinates, regarded as a * column-vector, are pre-multiplied by a matrix (whose elements * are specified when the MatrixMap is created) to give a new * column-vector containing the output coordinates. If appropriate, * the inverse transformation may also be performed. * Parameters: c nin f NIN = INTEGER (Given) * The number of input coordinates, which determines the number * of columns in the matrix. c nout f NOUT = INTEGER (Given) * The number of output coordinates, which determines the number * of rows in the matrix. c form f FORM = INTEGER (Given) * An integer which indicates the form in which the matrix * elements will be supplied. * c A value of zero indicates that a full "nout" x "nin" matrix f A value of zero indicates that a full NOUT x NIN matrix c of values will be supplied via the "matrix" parameter f of values will be supplied via the MATRIX argument * (below). In this case, the elements should be given in row * order (the elements of the first row, followed by the * elements of the second row, etc.). * * A value of 1 indicates that only the diagonal elements of the * matrix will be supplied, and that all others should be c zero. In this case, the elements of "matrix" should contain f zero. In this case, the elements of MATRIX should contain * only the diagonal elements, stored consecutively. * * A value of 2 indicates that a "unit" matrix is required, * whose diagonal elements are set to unity (with all other c elements zero). In this case, the "matrix" parameter is c ignored and a NULL pointer may be supplied. f elements zero). In this case, the MATRIX argument is not used. c matrix f MATRIX( * ) = DOUBLE PRECISION (Given) * The array of matrix elements to be used, stored according to c the value of "form". f the value of FORM. 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 MatrixMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new MatrixMap. The syntax used is identical to that for the f AST_SET routine. 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 astMatrixMap() f AST_MATRIXMAP = INTEGER * A pointer to the new MatrixMap. * Notes: * - In general, a MatrixMap's forward transformation will always * be available (as indicated by its TranForward attribute), but * its inverse transformation (TranInverse attribute) will only be * available if the associated matrix is square and non-singular. * - As an exception to this, the inverse transformation is always * available if a unit or diagonal matrix is specified. In this * case, if the matrix is not square, one or more of the input * coordinate values may not be recoverable from a set of output * coordinates. Any coordinates affected in this way will simply be * set to the value zero. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMatrixMap *new; /* Pointer to new MatrixMap */ va_list args; /* Variable argument list */ /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise the MatrixMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitMatrixMap( NULL, sizeof( AstMatrixMap ), !class_init, &class_vtab, "MatrixMap", nin, nout, form, matrix); /* 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 MatrixMap'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 MatrixMap. */ return new; } AstMatrixMap *astMatrixMapId_( int nin, int nout, int form, const double matrix[], const char *options, ... ) { /* * Name: * astMatrixMapId_ * Purpose: * Create a MatrixMap. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *astMatrixMapId_( int nin, int nout, int form, * const double matrix[], const char *options, * ... ) * Class Membership: * MatrixMap constructor. * Description: * This function implements the external (public) interface to the * astMatrixMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astMatrixMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astMatrixMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astMatrixMap_. * Returned Value: * The ID value associated with the new MatrixMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMatrixMap *new; /* Pointer to new MatrixMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the MatrixMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitMatrixMap( NULL, sizeof( AstMatrixMap ), !class_init, &class_vtab, "MatrixMap", nin, nout, form, matrix ); /* 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 MatrixMap'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 MatrixMap. */ return astMakeId( new ); } AstMatrixMap *astInitMatrixMap_( void *mem, size_t size, int init, AstMatrixMapVtab *vtab, const char *name, int nin, int nout, int form, const double *matrix, int *status ) { /* *+ * Name: * astInitMatrixMap * Purpose: * Initialise a MatrixMap. * Type: * Protected function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *astInitMatrixMap( void *mem, size_t size, int init, * AstMatrixMapVtab *vtab, const char *name, * int nin, int nout, int form, * const double *matrix ) * Class Membership: * MatrixMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new MatrixMap object. It allocates memory (if necessary) to accommodate * the MatrixMap plus any additional data associated with the derived class. * It then initialises a MatrixMap 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 MatrixMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the MatrixMap is to be initialised. * This must be of sufficient size to accommodate the MatrixMap data * (sizeof(MatrixMap)) 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 MatrixMap (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 MatrixMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the MatrixMap'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 MatrixMap. * 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). * nin * The number of input coordinate values per point. This is the * same as the number of columns in the matrix. * nout * The number of output coordinate values per point. This is the * same as the number of rows in the matrix. * form * If "form" is 2 or larger, then a unit MatrixMap is created. In this * case "matrix" is ignored and can be supplied as NULL. If "form" is * 1, then a diagonal MatrixMap is created. In this case, the number of * values in "matrix" should be equal to the minimum of nin and nout, * and "matrix" should contain the corresponding diagonal terms, in row * order. If "form" is 0 or less, then a full MatrixMap is created, and * "matrix" should contain all nin*nout element values. * matrix * A pointer to an array of matrix element values. The values should be * supplied in row order. The content of this array is determined by * "form". If a full MatrixMap is to be created then the array starts * with (row 1, column 1), then comes (row 1, column 2), up to (row 1, * column nin), then (row 2, column 1), (row 2, column 2), and so on, * finishing with (row nout, column nin) ). An error is reported if a * NULL value is supplied unless "form" is 2 or more. * Returned Value: * A pointer to the new MatrixMap. * 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: */ AstMatrixMap *new; /* Pointer to new MatrixMap */ double *fmat; /* Pointer to the forward matrix */ double *imat; /* Pointer to the inverse matrix */ int i; /* Loop count */ int nel; /* No. of elements in matrix array */ int nuse; /* Number of usable matrix elements */ int used_form; /* Form limited to 0, 1 or 2 */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitMatrixMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Report an error if a NULL matrix was supplied, unless a unit MatrixMap has been requested. */ if( form < 2 && !matrix ){ astError( AST__MTRMT, "astInitMatrixMap(%s): NULL matrix supplied.", status, name ); } else { /* Initialise a Mapping structure (the parent class) as the first component within the MatrixMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstMatrixMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, 1, 1 ); if ( astOK ) { /* Initialise the MatrixMap data. */ /* ---------------------------- */ /* If a unit MatrixMap is being created, then no additional storage is required. */ if( form > 1 ){ nel = 0; used_form = UNIT; /* If a diagonal MatrixMap is being created, then memory is needed to hold the diagonal terms. */ } else if( form == 1 ){ if( nin < nout ){ nel = nin; } else { nel = nout; } used_form = DIAGONAL; /* If a full MatrixMap is being created, then memory is needed to hold all the terms. */ } else { nel = nin*nout ; used_form = FULL; } /* Allocate memory for the forward matrix, storing the supplied matrix values in it. */ fmat = (double *) astStore( NULL, (void *) matrix, sizeof(double)*(size_t)nel ); /* Replace any NaNs by AST__BAD and count the number of usable values. */ if( nel > 0 ) { nuse = 0; for( i = 0; i < nel; i++ ) { if( !astISFINITE(fmat[ i ]) ) { fmat[ i ] = AST__BAD; } else if( fmat[ i ] != AST__BAD ) { nuse++; } } /* Report an error if there are no usable values. */ if( nuse == 0 && astOK ) { astError( AST__MTRMT, "astInitMatrixMap(%s): Supplied matrix " "contains only bad values.", status, name ); } } /* Create an inverse matrix if possible. */ imat = InvertMatrix( used_form, nout, nin, fmat, status ); /* Store the matrix arrays. */ new->form = used_form; new->f_matrix = fmat; new->i_matrix = imat; /* Attempt to compress the MatrixMap into DIAGONAL or UNIT form. */ CompressMatrix( new, status ); /* If an error occurred, clean up by deleting the new MatrixMap. */ if ( !astOK ) new = astDelete( new ); } } /* Return a pointer to the new MatrixMap. */ return new; } AstMatrixMap *astLoadMatrixMap_( void *mem, size_t size, AstMatrixMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadMatrixMap * Purpose: * Load a MatrixMap. * Type: * Protected function. * Synopsis: * #include "matrixmap.h" * AstMatrixMap *astLoadMatrixMap( void *mem, size_t size, * AstMatrixMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * MatrixMap loader. * Description: * This function is provided to load a new MatrixMap 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 * MatrixMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a MatrixMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the MatrixMap is to be * loaded. This must be of sufficient size to accommodate the * MatrixMap data (sizeof(MatrixMap)) 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 MatrixMap (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 MatrixMap 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(AstMatrixMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new MatrixMap. If this is NULL, a pointer * to the (static) virtual function table for the MatrixMap 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 "MatrixMap" is used instead. * Returned Value: * A pointer to the new MatrixMap. * 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. *- */ #define KEY_LEN 50 /* Maximum length of a keyword */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Local Variables: */ AstMatrixMap *new; /* Pointer to the new MatrixMap */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *form; /* String form */ int def; /* Is the matrix defined? */ int el; /* Element index */ int nel; /* No. of elements in the matrix */ int nin; /* No. of input coords */ int nout; /* No. of output coords */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this MatrixMap. In this case the MatrixMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstMatrixMap ); vtab = &class_vtab; name = "MatrixMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitMatrixMapVtab( 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 MatrixMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "MatrixMap" ); /* Now obtain the Matrix storage form from this list. */ form = astReadString( channel, "form", Form[FULL] ); new->form = FindString( 3, Form, form, "the MatrixMap component 'Form'", "astRead", astGetClass( channel ), status ); form = astFree( (void *) form ); /* Find the number of elements stored for each matrix. */ nin = astGetNin( (AstMapping *) new ); nout = astGetNout( (AstMapping *) new ); if( new->form == FULL ){ nel = nin*nout; } else if( new->form == DIAGONAL ){ nel = astMIN( nin, nout ); } else { nel = 0; } /* Allocate memory to hold the forward matrix. */ new->f_matrix = (double *) astMalloc( sizeof(double)*(size_t)nel ); /* Now read the other data items from the list and use them to initialise the appropriate instance variable(s) for this class. */ /* The forward matrix. */ if( new->f_matrix ){ def = 0; for( el = 0; el < nel; el++ ){ (void) sprintf( buff, "m%d", el ); (new->f_matrix)[ el ] = astReadDouble( channel, buff, AST__BAD ); if( (new->f_matrix)[ el ] != AST__BAD ) def = 1; } /* Store a NULL pointer if no elements of the matrix were found. */ if( !def ) new->f_matrix = (double *) astFree( (void *) new->f_matrix ); } /* Create an inverse matrix if possible, otherwise store a NULL pointer. */ if( new->f_matrix ){ new->i_matrix = InvertMatrix( new->form, nout, nin, new->f_matrix, status ); } else { new->i_matrix = NULL; } /* If an error occurred, clean up by deleting the new MatrixMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new MatrixMap 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. */ AstMatrixMap *astMtrRot_( AstMatrixMap *this, double theta, const double axis[], int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,MatrixMap,MtrRot))( this, theta, axis, status ); } AstMatrixMap *astMtrMult_( AstMatrixMap *this, AstMatrixMap *a, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,MatrixMap,MtrMult))( this, a, status ); } ast-8.3.0/wcsmath.h0000664000175000017500000000413613004147321011052 00000000000000/*============================================================================= * * WCSLIB - an implementation of the FITS WCS proposal. * Copyright (C) 1995-2002, Mark Calabretta * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published * by the Free Software Foundation; either version 2 of the License, or (at * your option) any later version. * * This library 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 Library * General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA * * Correspondence concerning WCSLIB may be directed to: * Internet email: mcalabre@atnf.csiro.au * Postal address: Dr. Mark Calabretta, * Australia Telescope National Facility, * P.O. Box 76, * Epping, NSW, 2121, * AUSTRALIA * * Author: Mark Calabretta, Australia Telescope National Facility * $Id$ *============================================================================= * * This version of wcstrig.h is based on the version in wcslib-2.9, but has * been modified in the following ways by the Starlink project (e-mail: * ussc@star.rl.ac.uk): * - Changed the name of the WCSLIB_MATH macro to WCSLIB_MATH_INCLUDED *===========================================================================*/ #ifndef WCSLIB_MATH_INCLUDED #define WCSLIB_MATH_INCLUDED #ifdef PI #undef PI #endif #ifdef D2R #undef D2R #endif #ifdef R2D #undef R2D #endif #ifdef SQRT2 #undef SQRT2 #endif #ifdef SQRT2INV #undef SQRT2INV #endif #define PI 3.141592653589793238462643 #define D2R PI/180.0 #define R2D 180.0/PI #define SQRT2 1.4142135623730950488 #define SQRT2INV 1.0/SQRT2 #endif /* WCSLIB_MATH_INCLUDED */ ast-8.3.0/specfluxframe.c0000664000175000017500000022613713004147321012252 00000000000000/* *class++ * Name: * SpecFluxFrame * Purpose: * Compound spectrum/flux Frame. * Constructor Function: c astSpecFluxFrame f AST_SPECFLUXFRAME * Description: * A SpecFluxFrame combines a SpecFrame and a FluxFrame into a single * 2-dimensional compound Frame. Such a Frame can for instance be used * to describe a Plot of a spectrum in which the first axis represents * spectral position and the second axis represents flux. * Inheritance: * The SpecFluxFrame class inherits from the CmpFrame class. * Attributes: * The SpecFluxFrame class does not define any new attributes beyond * those which are applicable to all CmpFrames. However, the attributes * of the component Frames can be accessed as if they were attributes * of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise * the "StdOfRest" attribute and forward access requests to the component * SpecFrame. An axis index can optionally be appended to the end of any * attribute name, in which case the request to access the attribute will * be forwarded to the primary Frame defining the specified axis. * Functions: c The SpecFluxFrame class does not define any new functions beyond those f The SpecFluxFrame class does not define any new routines beyond those * which are applicable to all CmpFrames. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 8-DEC-2004 (DSB): * Original version. * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. *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 SpecFluxFrame /* Define the first and last acceptable System values. */ #define FIRST_SYSTEM AST__COMP #define LAST_SYSTEM AST__COMP /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "globals.h" /* Thread-safe global data access */ #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 "axis.h" /* Coordinate axes */ #include "cmpframe.h" /* Parent CmpFrame class */ #include "tranmap.h" /* Separated transformation Mappings */ #include "mathmap.h" /* Algebraic Mappings */ #include "ratemap.h" /* Differential Mappings */ #include "specframe.h" /* SpecFrame class */ #include "fluxframe.h" /* FluxFrame class */ #include "specfluxframe.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* 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_match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int (* parent_subframe)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static const char *(* parent_gettitle)( AstFrame *, int * ); /* 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->GetTitle_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SpecFluxFrame) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SpecFluxFrame,Class_Init) #define class_vtab astGLOBAL(SpecFluxFrame,Class_Vtab) #define gettitle_buff astGLOBAL(SpecFluxFrame,GetTitle_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char gettitle_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSpecFluxFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstSpecFluxFrame *astSpecFluxFrameId_( void *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstFluxFrame *GetFluxFrame( AstSpecFluxFrame *, int, int * ); static AstMapping *MakeMap2( AstSpecFluxFrame *, int * ); static AstMapping *MakeMap3( AstSpecFluxFrame *, AstSpecFluxFrame *, int * ); static AstMapping *MakeMapF( AstFluxFrame *, AstSpecFrame *, AstFluxFrame *, AstSpecFrame *, int * ); static AstMapping *MakeMapI( AstFluxFrame *, AstSpecFrame *, AstFluxFrame *, AstSpecFrame *, int * ); static AstSpecFrame *GetSpecFrame( AstSpecFluxFrame *, int, int * ); static const char *GetTitle( AstFrame *, int * ); static int MakeSFMapping( AstSpecFluxFrame *, AstSpecFluxFrame *, AstMapping **, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static void Dump( AstObject *, AstChannel *, int * ); /* Member functions. */ /* ================= */ static AstFluxFrame *GetFluxFrame( AstSpecFluxFrame *this, int std, int *status ){ /* * Name: * GetFluxFrame * Purpose: * Return a pointer to the FluxFrame in a FluxSpecFrame. * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstFluxFrame *GetFluxFrame( AstSpecFluxFrame *this, int std, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * Returns a pointer to the FluxFrame in a SpecFluxFrame. * Parameters: * this * Pointer to the SpecFluxFrame. * std * If non zero, then the returned FluxFrame is a standardised copy of * the FluxFrame in the supplied SpecFluxFrame, in which the System has * been set explicitly (rather than potentially being defaulted), and * the Units have been cleared to use default units appropriate to * the flux System. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the FluxFrame. Should be freed using astAnnul when no * longer needed. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables; */ AstFluxFrame *ff; AstFluxFrame *ret; /* Check the global error status. */ if ( !astOK ) return NULL; /* The FluxFrame is always the second Frame in the parent CmpFrame. */ ff = (AstFluxFrame *) ((AstCmpFrame *)this)->frame2; /* Produce a standardised copy of the FluxFrame if required, or clone the above pointer otherwise. */ if( std ) { ret = astCopy( ff ); astSetSystem( ret, astGetSystem( ff ) ); astClearUnit( ret, 0 ); } else { ret = astClone( ff ); } /* Annul the returned pointer if anything went wrong. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result. */ return ret; } static AstSpecFrame *GetSpecFrame( AstSpecFluxFrame *this, int std, int *status ){ /* * Name: * GetSpecFrame * Purpose: * Return a pointer to the SpecFrame in a FluxSpecFrame. * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstSpecFrame *GetSpecFrame( AstSpecFluxFrame *this, int std, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * Returns a pointer to the SpecFrame in a SpecFluxFrame. * Parameters: * this * Pointer to the SpecFluxFrame. * std * If non zero, then the returned SpecFrame is a standardised copy of * the SpecFrame in the supplied SpecFluxFrame, in which the System * and Units have been set explicitly to the values appropriate to the * flux system in use in the FluxFrame in the supplied SpecFluxFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the FluxFrame. Should be freed using astAnnul when no * longer needed. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables; */ AstFluxFrame *ff; AstSpecFrame *ret; AstSpecFrame *sf; /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the SpecFrame (the first Frame in the parent CmpFrame). */ sf = (AstSpecFrame *) ((AstCmpFrame *)this)->frame1; /* If we want a standardised version of the SpecFrame... */ if( std ) { /* The FluxFrame is always the second Frame in the parent CmpFrame. */ ff = (AstFluxFrame *) ((AstCmpFrame *)this)->frame2; /* Produce a copy of the SpecFrame and set its System and Units appropriate to the flux system (expressed in default units). */ ret = astCopy( sf ); astSetSystem( ret, astGetDensitySystem( ff ) ); astSetUnit( ret, 0, astGetDensityUnit( ff ) ); /* If we are not standardising the SpecFrame, just return a clone of the pointer in the parent CmpFrame. */ } else { ret = astClone( sf ); } /* Annul the returned pointer if anything went wrong. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result. */ return ret; } static const char *GetTitle( AstFrame *this_frame, int *status ) { /* * Name: * GetTitle * Purpose: * Obtain a pointer to the Title string for a SpecFluxFrame. * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * const char *GetTitle( AstFrame *this_frame, int *status ) * Class Membership: * SpecFluxFrame member function (over-rides the astGetTitle method * inherited from the CmpFrame class). * Description: * This function returns a pointer to the Title string for a SpecFluxFrame. * A pointer to a suitable default string is returned if no Title value has * previously been set. * Parameters: * this * Pointer to the SpecFluxFrame. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null-terminated character string containing the requested * information. * 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: */ astDECLARE_GLOBALS AstSpecFluxFrame *this; AstSpecFrame *sf; AstFluxFrame *ff; const char *result; /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_frame); /* Initialise. */ result = NULL; /* Obtain a pointer to the SpecFluxFrame structure. */ this = (AstSpecFluxFrame *) this_frame; /* See if a Title string has been set. If so, use the parent astGetTitle method to obtain a pointer to it. */ if ( astTestTitle( this ) ) { result = (*parent_gettitle)( this_frame, status ); /* Otherwise, we will generate a default Title string. Obtain the values of the SpecFrame's attributes that determine what this string will be. */ } else { ff = GetFluxFrame( this, 0, status ); sf = GetSpecFrame( this, 0, status ); if( astOK ) { sprintf( gettitle_buff, "%s versus %s", astGetLabel( ff, 0 ), astGetLabel( sf, 0 ) ); gettitle_buff[ 0 ] = toupper( gettitle_buff[ 0 ] ); result = gettitle_buff; } ff = astAnnul( ff ); sf = astAnnul( sf ); } /* If an error occurred, clear the returned pointer value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } void astInitSpecFluxFrameVtab_( AstSpecFluxFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSpecFluxFrameVtab * Purpose: * Initialise a virtual function table for a SpecFluxFrame. * Type: * Protected function. * Synopsis: * #include "specfluxframe.h" * void astInitSpecFluxFrameVtab( AstSpecFluxFrameVtab *vtab, const char *name ) * Class Membership: * SpecFluxFrame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SpecFluxFrame class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstFrameVtab *frame; /* Pointer to Frame component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitCmpFrameVtab( (AstCmpFrameVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsASpecFluxFrame) 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 = &(((AstCmpFrameVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; frame = (AstFrameVtab *) vtab; mapping = (AstMappingVtab *) vtab; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ parent_match = frame->Match; frame->Match = Match; parent_subframe = frame->SubFrame; frame->SubFrame = SubFrame; parent_gettitle = frame->GetTitle; frame->GetTitle = GetTitle; /* Declare the copy constructor, destructor and class dump function. */ astSetDump( vtab, Dump, "SpecFluxFrame", "Compound spectral/flux coordinate system description" ); /* If we have just initialised the vtab for the current class, indicate that the vtab is now initialised, and store a pointer to the class identifier in the base "object" level of the vtab. */ if( vtab == &class_vtab ) { class_init = 1; astSetVtabClassIdentifier( vtab, &(vtab->id) ); } } static AstMapping *MakeMap2( AstSpecFluxFrame *this, int *status ){ /* * Name: * MakeMap2 * Purpose: * Generate the second Mapping required by MakeSFMapping * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstMapping *MakeMap2( AstSpecFluxFrame *this, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * The second Mapping used by MakeSFMapping contains three Mappings in * parallel which converts v1 (flux value) and x1 (spectral position) into * default units, and passes the third axis (a copy of flux value) * unchanged. * Parameters: * this * Pointer to the SpecFluxFrame to use. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the required Mapping, or NULL if the Mapping cannot be * created. The Mapping will have 3 inputs and 3 outputs. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables: */ AstFrame *f1; AstFrame *f2; AstFrameSet *fs; AstMapping *ax1_map; AstMapping *ax2_map; AstMapping *ax3_map; AstMapping *ret; AstMapping *tmap; /* Initialise. */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* Input 0 is the supplied FluxFrame value and output 0 is the corresponding value in the default units for the FluxFrame system. Take a copy of the supplied FluxFrame, and fix its System value (which may be a default value based on the Units string), and then clear the Units so that it represents default units for the System. */ f1 = (AstFrame *) GetFluxFrame( this, 0, status ); f2 = (AstFrame *) GetFluxFrame( this, 1, status ); /* Now, if conversion was possible, get the Mapping from the supplied FluxFrame to the default units FluxFrame. */ fs = astConvert( f1, f2, "" ); f1 = astAnnul( f1 ); f2 = astAnnul( f2 ); if( fs ) { ax1_map = astGetMapping( fs, AST__BASE, AST__CURRENT ); fs = astAnnul( fs ); /* Input 1 is the supplied SpecFrame value and output 1 is the corresponding value in the spectral system used by the flux system (wavelength or frequency). Take a copy of the supplied SpecFrame, and fix its System value to wavelength or frequency (depending on the System value of the FluxFrame), and set up units of Hz or Angstrom (these are the spectral position units used within the default flux units for a FluxFrame). */ f1 = (AstFrame *) GetSpecFrame( this, 0, status ); f2 = (AstFrame *) GetSpecFrame( this, 1, status ); /* Now, if conversion was possible, get the Mapping from the supplied SpecFrame to the required SpecFrame. */ fs = astConvert( f1, f2, "" ); f1 = astAnnul( f1 ); f2 = astAnnul( f2 ); if( fs ) { ax2_map = astGetMapping( fs, AST__BASE, AST__CURRENT ); fs = astAnnul( fs ); /* Create a UnitMap for the 3rd axis. */ ax3_map = (AstMapping *) astUnitMap( 1, "", status ); /* Create a parallel CmpMap containing the three Mappings. */ tmap = (AstMapping *) astCmpMap( ax1_map, ax2_map, 0, "", status ); ret = (AstMapping *) astCmpMap( tmap, ax3_map, 0, "", status ); /* Free remaining resources. */ tmap = astAnnul( tmap ); ax2_map = astAnnul( ax2_map ); ax3_map = astAnnul( ax3_map ); } ax1_map = astAnnul( ax1_map ); } /* If an error has occurred, return NULL. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result */ return ret; } static AstMapping *MakeMap3( AstSpecFluxFrame *target, AstSpecFluxFrame *result, int *status ){ /* * Name: * MakeMap3 * Purpose: * Generate the third Mapping required by MakeSFMapping * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstMapping *MakeMap3( AstSpecFluxFrame *target, AstSpecFluxFrame *result, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * The third Mapping used by MakeSFMapping converts input (v1,x1) in * default units to output (v2,x2) in default units. The third axis (x1) * in original units is converted to x2 in original units. * Parameters: * target * Pointer to the first SpecFluxFrame. * result * Pointer to the second SpecFluxFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the required Mapping, or NULL if the Mapping cannot be * created. The Mapping will have 3 inputs and 3 outputs. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables: */ AstFluxFrame *ff2; AstFluxFrame *ff1; AstFrameSet *fs; AstMapping *fmap; AstMapping *imap; AstMapping *mapa; AstMapping *mapb; AstMapping *ret; AstSpecFrame *sf2; AstSpecFrame *sf1; /* Initialise */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* The first two inputs and outputs are related by a TranMap which converts between standardised (v1,x1) and standardised (v2,x2). Get pointers to the standardised SpecFrames and FluxFrames in the two supplied SpecFluxFrames. */ ff1 = GetFluxFrame( target, 1, status ); sf1 = GetSpecFrame( target, 1, status ); ff2 = GetFluxFrame( result, 1, status ); sf2 = GetSpecFrame( result, 1, status ); /* Create the Mapping which defines the forward transformation of the required TranMap. The forward transformation of this Mapping goes from (v1,x1) to (v2,x2). */ fmap = MakeMapF( ff1, sf1, ff2, sf2, status ); /* Create the Mapping which defines the inverse transformation of the required TranMap. The inverse transformation of this Mapping goes from (v2,x2) to (v1,x1). */ imap = MakeMapI( ff1, sf1, ff2, sf2, status ); /* Combine these into a TranMap */ if( fmap && imap ) { mapa = (AstMapping *) astTranMap( fmap, imap, "", status ); } else { mapa = NULL; } /* Free resources. */ ff1 = astAnnul( ff1 ); sf1 = astAnnul( sf1 ); ff2 = astAnnul( ff2 ); sf2 = astAnnul( sf2 ); if( fmap ) fmap = astAnnul( fmap ); if( imap ) imap = astAnnul( imap ); /* The third input and output are related by a Mapping which converts between supplied (x1) and supplied (x2). Get pointers to the original unmodified SpecFrames in the two supplied SpecFluxFrames. */ sf1 = GetSpecFrame( target, 0, status ); sf2 = GetSpecFrame( result, 0, status ); /* Find the Mapping from the first to the second. */ fs = astConvert( sf1, sf2, "" ); if( fs ) { mapb = astGetMapping( fs, AST__BASE, AST__CURRENT ); fs = astAnnul( fs ); } else { mapb = NULL; } /* Free resources. */ sf1 = astAnnul( sf1 ); sf2 = astAnnul( sf2 ); /* Combine the two Mappings in parallel. */ if( mapa && mapb ) ret = (AstMapping *) astCmpMap( mapa, mapb, 0, "", status ); if( mapa ) mapa = astAnnul( mapa ); if( mapb ) mapb = astAnnul( mapb ); /* If an error has occurred, return NULL. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result */ return ret; } static AstMapping *MakeMapF( AstFluxFrame *v1, AstSpecFrame *x1, AstFluxFrame *v2, AstSpecFrame *x2, int *status ){ /* * Name: * MakeMapF * Purpose: * Generate the forward part of the third Mapping required by MakeSFMapping * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstMapping *MakeMapF( AstFluxFrame *v1, AstSpecFrame *x1, * AstFluxFrame *v2, AstSpecFrame *x2, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * Theis creates a 2-input 2-output Mapping which transforms * input (v1,x1) in default units to output (v2,x2) in default units. * Parameters: * v1 * Pointer to the standardised input FluxFrame. * x1 * Pointer to the standardised input SpecFrame. * v2 * Pointer to the standardised output FluxFrame. * x2 * Pointer to the standardised output SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the required Mapping, or NULL if the Mapping cannot be * created. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables: */ AstCmpMap *cmap1; AstCmpMap *cmap2; AstCmpMap *cmap3; AstFrameSet *fs; AstMapping *m; AstMapping *ret; AstMathMap *div; AstPermMap *perm; AstRateMap *rate; AstUnitMap *unit; const char *fwd[1]; const char *inv[2]; int inperm[ 2 ]; int outperm[ 3 ]; /* Initialise */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* First create the required component Mappings. --------------------------------------------- */ /* A Mapping which maps input spectral position (x1) into output spectral position (x2). */ fs = astConvert( x1, x2, "" ); if( fs ) { m = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* A 1-input 1-output Mapping in which the input is spectral position (x1) and the output is the rate of change of output spectral position (x2) with respect to input spectral position (x1). */ rate = astRateMap( m, 0, 0, "", status ); /* A MathMap which is used to divide the flux value (v1) by the absolute rate of change of x2 wrt x1 */ fwd[ 0 ] = "out=in0/abs(in1)"; inv[ 0 ] = "in0"; inv[ 1 ] = "in1"; div = astMathMap( 2, 1, 1, fwd, 2, inv, "", status ); /* A 1D UnitMap used to copy v1. */ unit = astUnitMap( 1, "", status ); /* A PermMap which is used to produce an extra output copy of x1. */ inperm[ 0 ] = 0; inperm[ 1 ] = 2; outperm[ 0 ] = 0; outperm[ 1 ] = 1; outperm[ 2 ] = 1; perm = astPermMap( 2, inperm, 3, outperm, NULL, "", status ); /* Now combine these component Mappings together. --------------------------------------------- */ /* First put the UnitMap and the RateMap in parallel. This produces a 2-in 2-out Mapping in which the inputs are (v1,x1) and the outputs are (v1,dx2/dx1). */ cmap1 = astCmpMap( unit, rate, 0, "", status ); /* Now put this in series with the dividing MathMap. This results in a 2-in, 1-out Mapping in which the inputs are v1 and x1 and the single output is v2. */ cmap2 = astCmpMap( cmap1, div, 1, "", status ); /* Now put this in parallel with the x1->x2 Mapping. This results in a 3-in, 2-out Mapping in which the inputs are (v1,x1,x1) and the outputs are (v2,x2). */ cmap3 = astCmpMap( cmap2, m, 0, "", status ); /* Finally put this in series with the PermMap. This results in a 2-in, 2-out Mapping in which the inputs are (v1,x1) and the outputs are (v2,x2). */ ret = (AstMapping *) astCmpMap( perm, cmap3, 1, "", status ); /* Free resources. */ fs = astAnnul( fs ); m = astAnnul( m ); rate = astAnnul( rate ); div= astAnnul( div ); unit = astAnnul( unit ); perm = astAnnul( perm ); cmap1 = astAnnul( cmap1 ); cmap2 = astAnnul( cmap2 ); cmap3 = astAnnul( cmap3 ); } /* If an error has occurred, return NULL. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result */ return ret; } static AstMapping *MakeMapI( AstFluxFrame *v1, AstSpecFrame *x1, AstFluxFrame *v2, AstSpecFrame *x2, int *status ){ /* * Name: * MakeMapI * Purpose: * Generate the inverse part of the third Mapping required by MakeSFMapping * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstMapping *MakeMapI( AstFluxFrame *v1, AstSpecFrame *x1, * AstFluxFrame *v2, AstSpecFrame *x2 ) * Class Membership: * SpecFluxFrame member function. * Description: * This creates a 2-input 2-output Mapping in which the inverse * transformation transforms "outputs" representing (v2,x2) into * "inputs" representing (v1,x1). * Parameters: * v1 * Pointer to the standardised input FluxFrame. * x1 * Pointer to the standardised input SpecFrame. * v2 * Pointer to the standardised output FluxFrame. * x2 * Pointer to the standardised output SpecFrame. * Returned Value: * A pointer to the required Mapping, or NULL if the Mapping cannot be * created. * Notes: * NULL is returned if this function is invoked with the global error * status set or if it should fail for any reason. */ /* Local Variables: */ AstCmpMap *cmap1; AstCmpMap *cmap2; AstCmpMap *cmap3; AstCmpMap *cmap4; AstCmpMap *cmap5; AstFrameSet *fs; AstMapping *m; AstMapping *ret; AstMathMap *mult; AstPermMap *perm; AstRateMap *rate; AstUnitMap *unit; const char *fwd[1]; const char *inv[2]; int inperm[ 2 ]; int outperm[ 3 ]; /* Initialise */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* We create a CmpMap in which the forward transformation foes from (v2,x2) to (v1,x1) and we finally invert this Mapping to get the required Mapping in which the *inverse* transformation goes from (v2,x2) to (v1,x1). First create the required component Mappings. --------------------------------------------- */ /* A Mapping which maps spectral position x1 into spectral position x2. */ fs = astConvert( x1, x2, "" ); if( fs ) { m = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* A 1-input 1-output Mapping in which the input is spectral position x1 and the output is the rate of change of spectral position x2 with respect to spectral position x1. */ rate = astRateMap( m, 0, 0, "", status ); /* Now invert "m" so that its forward transformation goes from x2 to x1. The RateMap created above retains a copy of the original Invert flag for "m" and uses it in preference to the current value when transforming points. */ astInvert( m ); /* A MathMap which is used to multiple the flux value v2 by the absolute rate of change of x2 wrt x1 */ fwd[ 0 ] = "out=in0*abs(in1)"; inv[ 0 ] = "in0"; inv[ 1 ] = "in1"; mult = astMathMap( 2, 1, 1, fwd, 2, inv, "", status ); /* A 1D UnitMap used to copy various values. */ unit = astUnitMap( 1, "", status ); /* A PermMap which is used to produce an extra copy of x1. */ inperm[ 0 ] = 0; inperm[ 1 ] = 2; outperm[ 0 ] = 0; outperm[ 1 ] = 1; outperm[ 2 ] = 1; perm = astPermMap( 2, inperm, 3, outperm, NULL, "", status ); /* Now combine these component Mappings together. --------------------------------------------- */ /* First put the UnitMap and the RateMap in parallel. This produces a 2-in 2-out Mapping in which the inputs are (v2,x1) and the outputs are (v2,dx2/dx1). */ cmap1 = astCmpMap( unit, rate, 0, "", status ); /* Now put this in series with the multiplying MathMap. This results in a 2-in, 1-out Mapping in which the inputs are (v2,x1) and the single output is v1. */ cmap2 = astCmpMap( cmap1, mult, 1, "", status ); /* Now put this in parallel with the UnitMap to get a 3-in, 2-out Mapping in which the inputs are (v2,x1,x1) and the outputs are (v1,x1). */ cmap3 = astCmpMap( cmap2, unit, 0, "", status ); /* Now put this in series with the PermMap to get a 2-in, 2-out Mapping in which the inputs are (v2,x1) and the outputs are (v1,x1). */ cmap4 = astCmpMap( perm, cmap3, 1, "", status ); /* Now put the UnitMap in parallel with the (x2->x1 Mapping to get a 2-in, 2-out Mapping in which the inputs are (v2,x2) and the outputs are (v2,x1). */ cmap5 = astCmpMap( unit, m, 0, "", status ); /* Finally put this in series with "cmap4" to get a 2-in 2-out Mapping from (v2,x2) to (v1,x1). */ ret = (AstMapping *) astCmpMap( cmap5, cmap4, 1, "", status ); /* Invert this so that the inverse transformation goes from (v2,x2) to (v1,x1). */ astInvert( ret ); /* Free resources. */ fs = astAnnul( fs ); m = astAnnul( m ); rate = astAnnul( rate ); mult = astAnnul( mult ); unit = astAnnul( unit ); perm = astAnnul( perm ); cmap1 = astAnnul( cmap1 ); cmap2 = astAnnul( cmap2 ); cmap3 = astAnnul( cmap3 ); cmap4 = astAnnul( cmap4 ); cmap5 = astAnnul( cmap5 ); } /* If an error has occurred, return NULL. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result */ return ret; } static int MakeSFMapping( AstSpecFluxFrame *target, AstSpecFluxFrame *result, AstMapping **map, int *status ){ /* * Name: * MakeSFMapping * Purpose: * Generate a Mapping between two SpecFluxFrames. * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * int MakeSFMapping( AstSpecFluxFrame *target, AstSpecFluxFrame *result, * AstMapping **map, int *status ) * Class Membership: * SpecFluxFrame member function. * Description: * This function takes two SpecFluxFrames and generates a Mapping that * converts between them, taking account of differences in their * coordinate systems, systems, units, etc. (but not allowing for any * axis permutations). * Parameters: * target * Pointer to the first SpecFluxFrame. * result * Pointer to the second SpecFluxFrame. * map * Pointer to a location which is to receive a pointer to the * returned Mapping. The forward transformation of this Mapping * will convert from "target" coordinates to "result" * coordinates, and the inverse transformation will convert in * the opposite direction (all coordinate values in radians). * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Mapping could be generated, or zero if the two * SpecFluxFrames are sufficiently un-related that no meaningful Mapping * can be produced. * Notes: * A value of zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ AstMapping *map1; AstMapping *map2; AstMapping *map3; AstMapping *map4; AstMapping *map5; AstMapping *tmap1; AstMapping *tmap2; AstMapping *tmap3; AstMapping *tmap4; int inperm[2]; int match; int outperm[3]; /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise the returned values. */ match = 0; *map = NULL; /* Initialise other things. */ map1 = NULL; map2 = NULL; map3 = NULL; map4 = NULL; map5 = NULL; tmap1 = NULL; tmap2 = NULL; tmap3 = NULL; tmap4 = NULL; /* At the top level, the required Mapping consists of five Mappings in series. Inputs 0 and 1 of the total Mapping correspond to the SpecFrame and FluxFrame in the target SpecFluxFrame. These are referred to as X1 and V1. Outputs 0 and 1 of the total Mapping correspond to the SpecFrame and FluxFrame in the result SpecFluxFrame. These are referred to as X2 and V2. */ /* Map1 is a PermMap which copies v1 to its first output and x1 to its second and third outputs. The inverse transformation copies v1 from its first output and x1 from its third output. */ inperm[ 0 ] = 2; inperm[ 1 ] = 0; outperm[ 0 ] = 1; outperm[ 1 ] = 0; outperm[ 2 ] = 0; map1 = (AstMapping *) astPermMap( 2, inperm, 3, outperm, NULL, "", status ); /* Map2 contains three Mappings in parallel which converts v1 and x1 into default units, and passes the third axis unchanged. */ map2 = MakeMap2( target, status ); /* Map3 converts ( v1,x1) in default units to (v2,x2) in default units. The third axis (x1) in original units is convert to x2 in original units. */ map3 = map2 ? MakeMap3( target, result, status ) : NULL; /* Map4 converts (v2,x2) in default units to (v2,x2) in original units and passes the third axis unchanged. This is similar to Map2 but based on the result ratherthan the target, and in the opposite direction. */ if( map3 ) { map4 = MakeMap2( result, status ); if( map4 ) astInvert( map4 ); } else { map4 = NULL; } /* Map5 is a PermMap which is the inverse of Map1. */ map5 = map4 ? astCopy( map1 ) : NULL; if( map5 ) astInvert( map5 ); /* Combine all 6 Mappings in series. */ if( map5 ) { tmap1 = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); tmap2 = (AstMapping *) astCmpMap( tmap1, map3, 1, "", status ); tmap3 = (AstMapping *) astCmpMap( tmap2, map4, 1, "", status ); tmap4 = (AstMapping *) astCmpMap( tmap3, map5, 1, "", status ); /* Return the simplified total Mapping. */ *map = astSimplify( tmap4 ); match = 1; } /* Free resources. */ if( map1 ) map1 = astAnnul( map1 ); if( map2 ) map2 = astAnnul( map2 ); if( map3 ) map3 = astAnnul( map3 ); if( map4 ) map4 = astAnnul( map4 ); if( map5 ) map5 = astAnnul( map5 ); if( tmap1 ) tmap1 = astAnnul( tmap1 ); if( tmap2 ) tmap2 = astAnnul( tmap2 ); if( tmap3 ) tmap3 = astAnnul( tmap3 ); if( tmap4 ) tmap4 = astAnnul( tmap4 ); /* If an error occurred, annul the returned Mapping and clear the returned values. */ if ( !astOK ) { *map = astAnnul( *map ); match = 0; } /* Return the result. */ return match; } static int Match( AstFrame *template_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 "specfluxframe.h" * int Match( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result, int *status ) * Class Membership: * SpecFluxFrame member function (over-rides the protected astMatch * method inherited from the Frame class). * Description: * This function matches a "template" SpecFluxFrame to a "target" Frame * and determines whether it is possible to convert coordinates * between them. If it is, a Mapping that performs the * transformation is returned along with a new Frame that describes * the coordinate system that results when this Mapping is applied * to the "target" coordinate system. In addition, information is * returned to allow the axes in this "result" Frame to be * associated with the corresponding axes in the "target" Frame and * "template" SpecFluxFrame from which they are derived. * Parameters: * template * Pointer to the template SpecFluxFrame. This describes the * coordinate system (or set of possible coordinate systems) * into which we wish to convert our coordinates. * target * Pointer to the target Frame. This describes the coordinate * system in which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case. * template_axes * Address of a location where a pointer to int will be returned * if the requested coordinate conversion is possible. This * pointer will point at a dynamically allocated array of * integers with one element for each axis of the "result" Frame * (see below). It must be freed by the caller (using astFree) * when no longer required. * * For each axis in the result Frame, the corresponding element * of this array will return the (zero-based) index of the * template SpecFluxFrame axis from which it is derived. If it is not * derived from any template axis, a value of -1 will be * returned instead. * target_axes * Address of a location where a pointer to int will be returned * if the requested coordinate conversion is possible. This * pointer will point at a dynamically allocated array of * integers with one element for each axis of the "result" Frame * (see below). It must be freed by the caller (using astFree) * when no longer required. * * For each axis in the result Frame, the corresponding element * of this array will return the (zero-based) index of the * target Frame axis from which it is derived. If it is not * derived from any target 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 template * SpecFluxFrame. 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: * - By default, the "result" Frame will have its number of axes * and axis order determined by the "template" SpecFluxFrame. However, * if the PreserveAxes attribute of the template SpecFluxFrame is * non-zero, then the axis count and axis order of the "target" * Frame will be used instead. * - 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: */ AstSpecFluxFrame *template; /* Pointer to template SpecFluxFrame structure */ int match; /* Coordinate conversion possible? */ int swap1; /* Template axes swapped? */ int swap2; /* Target axes swapped? */ int swap; /* Additional axis swap needed? */ /* 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 template SpecFluxFrame structure. */ template = (AstSpecFluxFrame *) template_frame; /* If the target is not a SpecFluxFrame, use the results returned by the parent Match method inherited from the CmpFrame class. */ if( !astIsASpecFluxFrame( target ) ) { match = (*parent_match)( template_frame, target, matchsub, template_axes, target_axes, map, result, status ); /* If the target is a SpecFluxFrame, see if we can convert between target and template */ } else { /* We must now decide how the order of the axes in the result Frame relates to the order of axes in the target Frame. There are two factors involved. The first depends on whether the axis permutation array for the template SpecFluxFrame (whose method we are executing) causes an axis reversal. Determine this by permuting axis index zero. */ swap1 = ( astValidateAxis( template, 0, 1, "astMatch" ) != 0 ); /* The second factor depends on whether the axes of the target SpecFluxFrame causes an axis reversal. Determine this by permuting axis index zero. */ swap2 = ( astValidateAxis( target, 0, 1, "astMatch" ) != 0 ); /* Combine these to determine if an additional axis swap will be needed. */ swap = ( swap1 != swap2 ); /* Now check to see if this additional swap is permitted by the template's Permute attribute. */ match = ( !swap || astGetPermute( template ) ); /* Allocate the target and template axes arrays. */ *template_axes = astMalloc( sizeof(int)*2 ); *target_axes = astMalloc( sizeof(int)*2 ); /* If the Frames still match, we next set up the axis association arrays. */ if ( astOK && match ) { /* If the target axis order is to be preserved, then the target axis association involves no permutation but the template axis association may involve an axis swap. */ if ( astGetPreserveAxes( template ) ) { (*template_axes)[ 0 ] = swap; (*template_axes)[ 1 ] = !swap; (*target_axes)[ 0 ] = 0; (*target_axes)[ 1 ] = 1; /* Otherwise, any swap applies to the target axis association instead. */ } else { (*template_axes)[ 0 ] = 0; (*template_axes)[ 1 ] = 1; (*target_axes)[ 0 ] = swap; (*target_axes)[ 1 ] = !swap; } /* Use the target's "astSubFrame" method to create a new Frame (the result Frame) with copies of the target axes in the required order. This process also overlays the template attributes on to the target Frame and returns a Mapping between the target and result Frames which effects the required coordinate conversion. */ match = astSubFrame( target, template, 2, *target_axes, *template_axes, map, result ); /* If an error occurred, or conversion to the result Frame's coordinate system was not possible, then free all memory, annul the returned objects, and reset the returned value. */ if ( !astOK || !match ) { *template_axes = astFree( *template_axes ); *target_axes = astFree( *target_axes ); if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } } } /* Return the result. */ return match; } static int SubFrame( AstFrame *target_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 SpecFluxFrame and convert to the new coordinate system. * Type: * Private function. * Synopsis: * #include "specfluxframe.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: * SpecFluxFrame 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 a "target" SpecFluxFrame and creates a new Frame with * copies of the selected axes assembled in the requested order. It * then optionally overlays the attributes of a "template" Frame on * to the result. It returns both the resulting Frame and a Mapping * that describes how to convert between the coordinate systems * described by the target and result Frames. If necessary, this * Mapping takes account of any differences in the Frames' * attributes due to the influence of the template. * Parameters: * target * Pointer to the target SpecFluxFrame, from which axes are to be selected. * template * Pointer to the template Frame, from which new attributes for * the result Frame are to be obtained. Optionally, this may be * NULL, in which case no overlaying of template attributes will * be performed. * result_naxes * Number of axes to be selected from the target Frame. This * number may be greater than or less than the number of axes in * this Frame (or equal). * target_axes * Pointer to an array of int with result_naxes elements, giving * a list of the (zero-based) axis indices of the axes to be * selected from the target SpecFluxFrame. The order in which these * are given determines the order in which the axes appear in * the result Frame. If any of the values in this array is set * to -1, the corresponding result axis will not be derived from * the target Frame, but will be assigned default attributes * instead. * template_axes * Pointer to an array of int with result_naxes elements. This * should contain a list of the template axes (given as * zero-based axis indices) with which the axes of the result * Frame are to be associated. This array determines which axes * are used when overlaying axis-dependent attributes of the * template on to the result. If any element of this array is * set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not * used and a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned * Mapping. The forward transformation of this Mapping will * describe how to convert coordinates from the coordinate * system described by the target SpecFluxFrame 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 target and the result Frame. Otherwise zero * is returned and *map and *result are returned as NULL (but this * will not in itself result in an error condition). In general, * coordinate conversion should always be possible if no template * Frame is supplied but may not always be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * Implementation Deficiencies: * - It is not clear that the method of handling "extra" axes is * the best one, nor is the method of setting the "following" flag * necessarily correct. However, it is also not obvious that this * feature will ever be needed, so improvements have been left * until the requirement is clearer. */ /* Local Variables: */ AstMapping *tmpmap; /* Temporary Mapping pointer */ AstPermMap *permmap; /* Pointer to PermMap */ AstSpecFluxFrame *target; /* Pointer to target SpecFluxFrame structure */ int match; /* Coordinate conversion is possible? */ int perm[ 2 ]; /* Permutation array for axis swap */ int result_swap; /* Swap result SpecFluxFrame coordinates? */ int target_swap; /* Swap target SpecFluxFrame coordinates? */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* If the template is not a SpecFluxFrame we use the parent SubFrame method inherited form the CmpFrame class. */ if( !template || !astIsASpecFluxFrame( template ) || result_naxes != 2 ) { match = (*parent_subframe)( target_frame, template, result_naxes, target_axes, template_axes, map, result, status ); /* Otherwise... */ } else { /* Obtain a pointer to the target SpecFluxFrame structure. */ target = (AstSpecFluxFrame *) target_frame; /* Form the result from a copy of the target and then permute its axes into the order required. */ *result = astCopy( target ); astPermAxes( *result, target_axes ); /* Overlay the template attributes on to the result SpecFrame. */ astOverlay( template, template_axes, *result ); /* Generate a Mapping that takes account of changes in the coordinate system (system, units, etc.) between the target SpecFluxFrame and the result SpecFluxFrame. If this Mapping can be generated, set "match" to indicate that coordinate conversion is possible. */ match = MakeSFMapping( target, (AstSpecFluxFrame *) *result, map, status ); /* If a Mapping has been obtained, it will expect coordinate values to be supplied in (flux,spec) pairs. Test whether we need to swap the order of the target SpecFluxFrame coordinates to conform with this. */ if ( astOK && match ) { target_swap = ( astValidateAxis( target, 0, 1, "astSubFrame" ) != 0 ); /* Coordinates will also be delivered in (flux,spec) pairs, so check to see whether the result SpecFluxFrame coordinate order should be swapped. */ result_swap = ( target_swap != ( target_axes[ 0 ] != 0 ) ); /* If either set of coordinates needs swapping, create a PermMap that will swap a pair of coordinates. */ permmap = NULL; if ( target_swap || result_swap ) { perm[ 0 ] = 1; perm[ 1 ] = 0; permmap = astPermMap( 2, perm, 2, perm, NULL, "", status ); } /* If necessary, prefix this PermMap to the main Mapping. */ if ( target_swap ) { tmpmap = (AstMapping *) astCmpMap( permmap, *map, 1, "", status ); *map = astAnnul( *map ); *map = tmpmap; } /* Also, if necessary, append it to the main Mapping. */ if ( result_swap ) { tmpmap = (AstMapping *) astCmpMap( *map, permmap, 1, "", status ); *map = astAnnul( *map ); *map = tmpmap; } /* Annul the pointer to the PermMap (if created). */ if ( permmap ) permmap = astAnnul( permmap ); } } /* If an error occurred, clean up by annulling the result pointers and returning appropriate null values. */ if ( !astOK ) { *map = astAnnul( *map ); *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with the axes of a SpecFluxFrame using the private macros defined for this purpose at the start of this file. */ /* Copy constructor. */ /* ----------------- */ /* Destructor. */ /* ----------- */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SpecFluxFrame 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 SpecFluxFrame class to an output Channel. * Parameters: * this * Pointer to the SpecFluxFrame 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 Variables: */ AstSpecFluxFrame *this; /* Pointer to the SpecFluxFrame structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFluxFrame structure. */ this = (AstSpecFluxFrame *) this_object; /* Write out values representing the instance variables for the SpecFluxFrame 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. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASpecFluxFrame and astCheckSpecFluxFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SpecFluxFrame,CmpFrame) astMAKE_CHECK(SpecFluxFrame) AstSpecFluxFrame *astSpecFluxFrame_( void *frame1_void, void *frame2_void, const char *options, int *status, ...) { /* *++ * Name: c astSpecFluxFrame f AST_SPECFLUXFRAME * Purpose: * Create a SpecFluxFrame. * Type: * Public function. * Synopsis: c #include "specfluxframe.h" c AstSpecFluxFrame *astSpecFluxFrame( AstSpecFrame *frame1, AstFluxFrame *frame2, c const char *options, ... ) f RESULT = AST_SPECFLUXFRAME( FRAME1, FRAME2, OPTIONS, STATUS ) * Class Membership: * SpecFluxFrame constructor. * Description: * This function creates a new SpecFluxFrame and optionally initialises * its attributes. * * A SpecFluxFrame combines a SpecFrame and a FluxFrame into a single * 2-dimensional compound Frame. Such a Frame can for instance be used * to describe a Plot of a spectrum in which the first axis represents * spectral position and the second axis represents flux. * Parameters: c frame1 f FRAME1 = INTEGER (Given) * Pointer to the SpecFrame. This will form the first axis in the * new SpecFluxFrame. c frame2 f FRAME2 = INTEGER (Given) * Pointer to the FluxFrame. This will form the second axis in the * new SpecFluxFrame. The "SpecVal" attribute of this FluxFrame is * not used by the SpecFluxFrame class and so may be set to AST__BAD * when the FluxFrame is created. 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 SpecFluxFrame. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new SpecFluxFrame. The syntax used is identical to that for the f AST_SET routine. 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 astSpecFluxFrame() f AST_SPECFLUXFRAME = INTEGER * A pointer to the new SpecFluxFrame. * Notes: * - The supplied Frame pointers are stored directly, rather than * being used to create deep copies of the supplied Frames. This means * that any subsequent changes made to the Frames via the supplied * pointers will result in equivalent changes being visible in the * SpecFluxFrame. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- * Implementation Notes: * - This function implements the basic SpecFluxFrame constructor which * is available via the protected interface to the SpecFluxFrame class. * A public interface is provided by the astSpecFluxFrameId_ 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 * "frame1" and "frame2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSpecFluxFrame *new; /* Pointer to new SpecFluxFrame */ AstFluxFrame *frame2; /* Pointer to FluxFrame structure */ AstSpecFrame *frame1; /* Pointer to SpecFrame structure */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ new = NULL; if ( !astOK ) return new; /* Obtain and validate pointers to the Frame structures provided. */ frame1 = astCheckSpecFrame( frame1_void ); frame2 = astCheckFluxFrame( frame2_void ); if ( astOK ) { /* Initialise the SpecFluxFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecFluxFrame( NULL, sizeof( AstSpecFluxFrame ), !class_init, &class_vtab, "SpecFluxFrame", frame1, frame2 ); /* 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 SpecFluxFrame'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 SpecFluxFrame. */ return new; } AstSpecFluxFrame *astSpecFluxFrameId_( void *frame1_void, void *frame2_void, const char *options, ... ) { /* * Name: * astSpecFluxFrameId_ * Purpose: * Create a SpecFluxFrame. * Type: * Private function. * Synopsis: * #include "specfluxframe.h" * AstSpecFluxFrame *astSpecFluxFrameId_( void *frame1_void, void *frame2_void, * const char *options, ... ) * Class Membership: * SpecFluxFrame constructor. * Description: * This function implements the external (public) interface to the * astSpecFluxFrame constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astSpecFluxFrame_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). For the same reason, the "frame1" and "frame2" * parameters are of type (void *) and are converted and validated * within the function itself. * * The variable argument list also prevents this function from * invoking astSpecFluxFrame_ directly, so it must be a * re-implementation of it in all respects, except for the final * conversion of the result to an ID value. * Parameters: * As for astSpecFluxFrame_. * Returned Value: * The ID value associated with the new SpecFluxFrame. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSpecFluxFrame *new; /* Pointer to new SpecFluxFrame */ AstSpecFrame *frame1; /* Pointer to first Frame structure */ AstFluxFrame *frame2; /* Pointer to second Frame structure */ va_list args; /* Variable argument list */ int *status; /* 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. */ new = NULL; if ( !astOK ) return new; /* Obtain the Frame pointers from the ID's supplied and validate the pointers to ensure they identify valid Frames. */ frame1 = astVerifySpecFrame( astMakePointer( frame1_void ) ); frame2 = astVerifyFluxFrame( astMakePointer( frame2_void ) ); if ( astOK ) { /* Initialise the SpecFluxFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecFluxFrame( NULL, sizeof( AstSpecFluxFrame ), !class_init, &class_vtab, "SpecFluxFrame", frame1, frame2 ); /* 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 SpecFluxFrame'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 SpecFluxFrame. */ return astMakeId( new ); } AstSpecFluxFrame *astInitSpecFluxFrame_( void *mem, size_t size, int init, AstSpecFluxFrameVtab *vtab, const char *name, AstSpecFrame *frame1, AstFluxFrame *frame2, int *status ) { /* *+ * Name: * astInitSpecFluxFrame * Purpose: * Initialise a SpecFluxFrame. * Type: * Protected function. * Synopsis: * #include "specfluxframe.h" * AstSpecFluxFrame *astInitSpecFluxFrame( void *mem, size_t size, int init, * AstSpecFluxFrameVtab *vtab, const char *name, * AstSpecFrame *frame1, AstFluxFrame *frame2 ) * Class Membership: * SpecFluxFrame initialiser. * Description: * This function is provided for use by class implementations to * initialise a new SpecFluxFrame object. It allocates memory (if * necessary) to accommodate the SpecFluxFrame plus any additional data * associated with the derived class. It then initialises a * SpecFluxFrame 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 SpecFluxFrame at the start of the memory passed * via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SpecFluxFrame is to be * created. This must be of sufficient size to accommodate the * SpecFluxFrame data (sizeof(SpecFluxFrame)) 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 SpecFluxFrame (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 SpecFluxFrame structure, so a valid value must be * supplied even if not required for allocating memory. * init * A logical flag indicating if the SpecFluxFrame'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 SpecFluxFrame. * 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 Object astClass function). * frame1 * Pointer to the SpecFrame * frame2 * Pointer to the FluxFrame * Returned Value: * A pointer to the new SpecFluxFrame. * 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: */ AstSpecFluxFrame *new; /* Pointer to new SpecFluxFrame */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSpecFluxFrameVtab( vtab, name ); /* Initialise a Frame structure (the parent class) as the first component within the SpecFluxFrame structure, allocating memory if necessary. Set the number of Frame axes to zero, since all axis information is stored within the component Frames. */ new = astInitCmpFrame( mem, size, 0, (AstCmpFrameVtab *) vtab, name, frame1, frame2 ); if ( astOK ) { /* 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; } AstSpecFluxFrame *astLoadSpecFluxFrame_( void *mem, size_t size, AstSpecFluxFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSpecFluxFrame * Purpose: * Load a SpecFluxFrame. * Type: * Protected function. * Synopsis: * #include "specfluxframe.h" * AstSpecFluxFrame *astLoadSpecFluxFrame( void *mem, size_t size, * AstSpecFluxFrameVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SpecFluxFrame loader. * Description: * This function is provided to load a new SpecFluxFrame 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 * SpecFluxFrame structure in this memory, using data read from the * input Channel. * Parameters: * mem * A pointer to the memory into which the SpecFluxFrame is to be * loaded. This must be of sufficient size to accommodate the * SpecFluxFrame data (sizeof(SpecFluxFrame)) 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 SpecFluxFrame (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 SpecFluxFrame 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(AstSpecFluxFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SpecFluxFrame. If this is NULL, a pointer * to the (static) virtual function table for the SpecFluxFrame 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 "SpecFluxFrame" is used instead. * Returned Value: * A pointer to the new SpecFluxFrame. * 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: */ AstSpecFluxFrame *new; /* Pointer to the new SpecFluxFrame */ /* Initialise. */ new = NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* 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 SpecFluxFrame. In this case the SpecFluxFrame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSpecFluxFrame ); vtab = &class_vtab; name = "SpecFluxFrame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSpecFluxFrameVtab( 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 SpecFluxFrame. */ new = astLoadCmpFrame( mem, size, (AstCmpFrameVtab *) 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, "SpecFluxFrame" ); /* 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. */ /* (none) */ /* If an error occurred, clean up by deleting the new SpecFluxFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SpecFluxFrame 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. */ ast-8.3.0/fprism.c0000664000175000017500000000614513004147321010701 00000000000000/* *+ * Name: * fprism.c * Purpose: * Define a FORTRAN 77 interface to the AST Prism class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Prism class. * Routines Defined: * AST_ISAPRISM * AST_PRISM * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 10-JAN-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "prism.h" /* C interface to the Prism class */ F77_LOGICAL_FUNCTION(ast_isaprism)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPRISM", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPrism( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_prism)( INTEGER(REG1), INTEGER(REG2), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(REG1) GENPTR_INTEGER(REG2) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_PRISM", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPrism( astI2P( *REG1 ), astI2P( *REG2 ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/tpn.c0000664000175000017500000002703313004147321010201 00000000000000#include #include #include "wcsmath.h" #include "wcstrig.h" #include "proj.h" #define icopysign(X, Y) ((Y) < 0.0 ? -abs(X) : abs(X)) #define TPN 999 /*============================================================================ * TAN: gnomonic projection, with correction terms. * * This projection is no longer part of the FITSWCS standard, but is * retained here for use b the AST library as a means of implementing * the IRAF TNX projection, and the DSS encoding. * * Given and/or returned: * prj->p Array of latitude coefficients * prj->p2 Array of longitude coefficients * prj->flag TPN, or -TPN if prj->flag is given < 0. * prj->r0 r0; reset to 180/pi if 0. * prj->n If zero, only do poly part of transformation (i.e. omit * the TAN projection). * * Returned: * prj->code "TPN" * prj->phi0 0.0 * prj->theta0 90.0 * prj->astPRJfwd Pointer to astTPNfwd(). * prj->astPRJrev Pointer to astTPNrev(). * prj->w[ 0 ] Set to 0.0 if a simple tan projection is required * (with no polynomial correction). Otherwise, set to 1.0. *===========================================================================*/ int astTPNset(prj) struct AstPrjPrm *prj; { int m; prj->flag = icopysign(TPN, prj->flag); prj->phi0 = 0.0; prj->theta0 = 90.0; if (prj->r0 == 0.0) prj->r0 = R2D; prj->astPRJfwd = astTPNfwd; prj->astPRJrev = astTPNrev; /* If all co-efficients have their "unit" values, we do not need to use the polynomial correction. */ prj->w[ 0 ] = 0.0; if( prj->p[ 0 ] != 0.0 || prj->p2[ 0 ] != 0.0 ) { prj->w[ 0 ] = 1.0; } else if( prj->p[ 1 ] != 1.0 || prj->p2[ 1 ] != 1.0 ) { prj->w[ 0 ] = 1.0; } else { for( m = 2; m < WCSLIB_MXPAR; m++ ){ if( prj->p[ m ] != 0.0 || prj->p2[ m ] != 0.0 ){ prj->w[ 0 ] = 1.0; break; } } } return 0; } /*--------------------------------------------------------------------------*/ int astTPNfwd(phi, theta, prj, xx, yy) const double phi, theta; double *xx, *yy; struct AstPrjPrm *prj; { double r, xi, eta, x2, xy, y2, r2, x3, x2y, xy2, y3, r3, x4, x3y, x2y2, xy3, y4, x5, x4y, x3y2, x2y3, xy4, y5, r5, x6, x5y, x4y2, x3y3, x2y4, xy5, y6, x7, x6y, x5y2, x4y3, x3y4, x2y5, xy6, y7, r7, tol, f, g, fx, fy, gx, gy, dx, dy, x, y, denom; double *a, *b; int i, ok; if (abs(prj->flag) != TPN ) { if (astTPNset(prj)) return 1; } if( prj->n ) { double s = astSind(theta); if (prj->flag > 0 && s < 0.0) { return 2; } r = prj->r0*astCosd(theta)/s; xi = r*astSind(phi); eta = -r*astCosd(phi); } else { xi = phi; eta = theta; } /* Simple tan */ if( prj->w[ 0 ] == 0.0 ){ *xx = xi; *yy = eta; /* Tan with polynomial corrections: Iterate using Newton's method to get the (x,y) corresponding to the above (xi,eta). */ } else { a = prj->p2; b = prj->p; /* Initial guess: linear solution assuming a3,... and b3,... are zero. */ denom = a[1]*b[1] - a[2]*b[2]; if( denom != 0.0 ) { x = ( xi*b[1] - eta*a[2] - a[0]*b[1] + b[0]*a[2] )/denom; y = -( xi*b[2] - eta*a[1] - a[0]*b[2] + b[0]*a[1] )/denom; } else { if( a[1] != 0.0 ){ x = ( xi - a[0] )/a[1]; } else { x = a[0]; } if( b[1] != 0.0 ){ y = ( eta - b[0] )/b[1]; } else { y = b[0]; } } /* Iterate up to 50 times, until the required relative accuracy is achieved. */ tol = 1.0E-5; ok = 0; for (i = 0; i < 50; i++) { /* Get required products of the current x and y values */ x2 = x*x; xy = x*y; y2 = y*y; r2 = x2 + y2; r = sqrt( r2 ); x3 = x2*x; x2y = x2*y; xy2 = x*y2; y3 = y*y2; r3 = r*r2; x4 = x3*x; x3y = x3*y; x2y2 = x2*y2; xy3 = x*y3; y4 = y*y3; x5 = x4*x; x4y = x4*y; x3y2 = x3*y2; x2y3 = x2*y3; xy4 = x*y4; y5 = y*y4; r5 = r3*r2; x6 = x5*x; x5y = x5*y; x4y2 = x4*y2; x3y3 = x3*y3; x2y4 = x2*y4; xy5 = x*y5; y6 = y*y5; x7 = x6*x; x6y = x6*y; x5y2 = x5*y2; x4y3 = x4*y3; x3y4 = x3*y4; x2y5 = x2*y5; xy6 = x*y6; y7 = y*y6; r7 = r5*r2; /* Get the xi and eta models corresponding to the current x and y values */ f = a[0] + a[1]*x + a[2]*y + a[3]*r + a[4]*x2 + a[5]*xy + a[6]*y2 + a[7]*x3 + a[8]*x2y + a[9]*xy2 + a[10]*y3 + a[11]*r3 + a[12]*x4 + a[13]*x3y + a[14]*x2y2 + a[15]*xy3 + a[16]*y4 + a[17]*x5 + a[18]*x4y + a[19]*x3y2 + a[20]*x2y3 + a[21]*xy4 + a[22]*y5 + a[23]*r5 + a[24]*x6 + a[25]*x5y + a[26]*x4y2 + a[27]*x3y3 + a[28]*x2y4 + a[29]*xy5 + a[30]*y6 + a[31]*x7 + a[32]*x6y + a[33]*x5y2 + a[34]*x4y3 + a[35]*x3y4 + a[36]*x2y5 + a[37]*xy6 + a[38]*y7 + a[39]*r7; g = b[0] + b[1]*y + b[2]*x + b[3]*r + b[4]*y2 + b[5]*xy + b[6]*x2 + b[7]*y3 + b[8]*xy2 + b[9]*x2y + b[10]*x3 + b[11]*r3 + b[12]*y4 + b[13]*xy3 + b[14]*x2y2 + b[15]*x3y + b[16]*x4 + b[17]*y5 + b[18]*xy4 + b[19]*x2y3 + b[20]*x3y2 + b[21]*x4y + b[22]*x5 + b[23]*r5 + b[24]*y6 + b[25]*xy5 + b[26]*x2y4 + b[27]*x3y3 + b[28]*x4y2 + b[29]*x5y + b[30]*x6 + b[31]*y7 + b[32]*xy6 + b[33]*x2y5 + b[34]*x3y4 + b[35]*x4y3 + b[36]*x5y2 + b[37]*x6y + b[38]*x7 + b[39]*r7; /* Partial derivative of xi wrt x... */ fx = a[1] + a[3]*( (r!=0.0)?(x/r):0.0 ) + 2*a[4]*x + a[5]*y + 3*a[7]*x2 + 2*a[8]*xy + a[9]*y2 + 3*a[11]*r*x + 4*a[12]*x3 + 3*a[13]*x2y + 2*a[14]*xy2 + a[15]*y3 + 5*a[17]*x4 + 4*a[18]*x3y + 3*a[19]*x2y2 + 2*a[20]*xy3 + a[21]*y4 + 5*a[23]*r3*x + 6*a[24]*x5 + 5*a[25]*x4y + 4*a[26]*x3y2 + 3*a[27]*x2y3 + 2*a[28]*xy4 + a[29]*y5 + 7*a[31]*x6 + 6*a[32]*x5y + 5*a[33]*x4y2 + 4*a[34]*x3y3 + 3*a[35]*x2y4 + 2*a[36]*xy5 + a[37]*y6 + 7*a[39]*r5*x; /* Partial derivative of xi wrt y... */ fy = a[2] + a[3]*( (r!=0.0)?(y/r):0.0 ) + a[5]*x + 2*a[6]*y + a[8]*x2 + 2*a[9]*xy + 3*a[10]*y2 + 3*a[11]*r*y + a[13]*x3 + 2*a[14]*x2y + 3*a[15]*xy2 + 4*a[16]*y3 + a[18]*x4 + 2*a[19]*x3y + 3*a[20]*x2y2 + 4*a[21]*xy3 + 5*a[22]*y4 + 5*a[23]*r3*y + a[25]*x5 + 2*a[26]*x4y + 3*a[27]*x3y2 + 4*a[28]*x2y3 + 5*a[29]*xy4 + 6*a[30]*y5 + a[32]*x6 + 2*a[33]*x5y + 3*a[34]*x4y2 + 4*a[35]*x3y3 + 5*a[36]*x2y4 + 6*a[37]*xy5 + 7*a[38]*y6 + 7*a[39]*r5*y; /* Partial derivative of eta wrt x... */ gx = b[2] + b[3]*( (r!=0.0)?(x/r):0.0 ) + b[5]*y + 2*b[6]*x + b[8]*y2 + 2*b[9]*xy + 3*b[10]*x2 + 3*b[11]*r*x + b[13]*y3 + 2*b[14]*xy2 + 3*b[15]*x2y + 4*b[16]*x3 + b[18]*y4 + 2*b[19]*xy3 + 3*b[20]*x2y2 + 4*b[21]*x3y + 5*b[22]*x4 + 5*b[23]*r3*x + b[25]*y5 + 2*b[26]*xy4 + 3*b[27]*x2y3 + 4*b[28]*x3y2 + 5*b[29]*x4y + 6*b[30]*x5 + b[32]*y6 + 2*b[33]*xy5 + 3*b[34]*x2y4 + 4*b[35]*x3y3 + 5*b[36]*x4y2 + 6*b[37]*x5y + 7*b[38]*x6 + 7*b[39]*r5*x; /* Partial derivative of eta wrt y... */ gy = b[1] + b[3]*( (r!=0.0)?(y/r):0.0 ) + 2*b[4]*y + b[5]*x + 3*b[7]*y2 + 2*b[8]*xy + b[9]*x2 + 3*b[11]*r*y + 4*b[12]*y3 + 3*b[13]*xy2 + 2*b[14]*x2y + b[15]*x3 + 5*b[17]*y4 + 4*b[18]*xy3 + 3*b[19]*x2y2 + 2*b[20]*x3y + b[21]*x4 + 5*b[23]*r3*y + 6*b[24]*y5 + 5*b[25]*xy4 + 4*b[26]*x2y3 + 3*b[27]*x3y2 + 2*b[28]*x4y + b[29]*x5 + 7*b[31]*y6 + 6*b[32]*xy5 + 5*b[33]*x2y4 + 4*b[34]*x3y3 + 3*b[35]*x4y2 + 2*b[36]*x5y + b[37]*x6 + 7*b[39]*r5*y; /* Calculate new x and y values. */ f = f - xi; g = g - eta; dx = ( (-f*gy) + (g*fy) ) / ( (fx*gy) - (fy*gx) ); dy = ( (-g*fx) + (f*gx) ) / ( (fx*gy) - (fy*gx) ); x += dx; y += dy; /* Check if convergence has been achieved. */ if( fabs(dx) <= tol*fabs(x) && fabs(dy) <= tol*fabs(y) ) { ok = 1; break; } } *xx = x; *yy = y; if( !ok ) return 2; } return 0; } /*--------------------------------------------------------------------------*/ int astTPNrev(x, y, prj, phi, theta) const double x, y; double *phi, *theta; struct AstPrjPrm *prj; { double r, xi, eta, x2, xy, y2, r2, x3, x2y, xy2, y3, r3, x4, x3y, x2y2, xy3, y4, x5, x4y, x3y2, x2y3, xy4, y5, r5, x6, x5y, x4y2, x3y3, x2y4, xy5, y6, x7, x6y, x5y2, x4y3, x3y4, x2y5, xy6, y7, r7; double *a, *b; if (abs(prj->flag) != TPN ) { if (astTPNset(prj)) return 1; } /* Simple tan */ if( prj->w[ 0 ] == 0.0 ){ xi = x; eta = y; /* Tan with polynomial corrections. */ } else { x2 = x*x; xy = x*y; y2 = y*y; r2 = x2 + y2; r = sqrt( r2 ); x3 = x2*x; x2y = x2*y; xy2 = x*y2; y3 = y*y2; r3 = r*r2; x4 = x3*x; x3y = x3*y; x2y2 = x2*y2; xy3 = x*y3; y4 = y*y3; x5 = x4*x; x4y = x4*y; x3y2 = x3*y2; x2y3 = x2*y3; xy4 = x*y4; y5 = y*y4; r5 = r3*r2; x6 = x5*x; x5y = x5*y; x4y2 = x4*y2; x3y3 = x3*y3; x2y4 = x2*y4; xy5 = x*y5; y6 = y*y5; x7 = x6*x; x6y = x6*y; x5y2 = x5*y2; x4y3 = x4*y3; x3y4 = x3*y4; x2y5 = x2*y5; xy6 = x*y6; y7 = y*y6; r7 = r5*r2; a = prj->p2; xi = a[0] + a[1]*x + a[2]*y + a[3]*r + a[4]*x2 + a[5]*xy + a[6]*y2 + a[7]*x3 + a[8]*x2y + a[9]*xy2 + a[10]*y3 + a[11]*r3 + a[12]*x4 + a[13]*x3y + a[14]*x2y2 + a[15]*xy3 + a[16]*y4 + a[17]*x5 + a[18]*x4y + a[19]*x3y2 + a[20]*x2y3 + a[21]*xy4 + a[22]*y5 + a[23]*r5 + a[24]*x6 + a[25]*x5y + a[26]*x4y2 + a[27]*x3y3 + a[28]*x2y4 + a[29]*xy5 + a[30]*y6 + a[31]*x7 + a[32]*x6y + a[33]*x5y2 + a[34]*x4y3 + a[35]*x3y4 + a[36]*x2y5 + a[37]*xy6 + a[38]*y7 + a[39]*r7; b = prj->p; eta = b[0] + b[1]*y + b[2]*x + b[3]*r + b[4]*y2 + b[5]*xy + b[6]*x2 + b[7]*y3 + b[8]*xy2 + b[9]*x2y + b[10]*x3 + b[11]*r3 + b[12]*y4 + b[13]*xy3 + b[14]*x2y2 + b[15]*x3y + b[16]*x4 + b[17]*y5 + b[18]*xy4 + b[19]*x2y3 + b[20]*x3y2 + b[21]*x4y + b[22]*x5 + b[23]*r5 + b[24]*y6 + b[25]*xy5 + b[26]*x2y4 + b[27]*x3y3 + b[28]*x4y2 + b[29]*x5y + b[30]*x6 + b[31]*y7 + b[32]*xy6 + b[33]*x2y5 + b[34]*x3y4 + b[35]*x4y3 + b[36]*x5y2 + b[37]*x6y + b[38]*x7 + b[39]*r7; } /* Now do the tan projection */ if( prj->n ) { r = sqrt(xi*xi + eta*eta); if (r == 0.0) { *phi = 0.0; } else { *phi = astATan2d(xi, -eta); } *theta = astATan2d(prj->r0, r); } else { *phi = xi; *theta = eta; } return 0; } ast-8.3.0/loader.c0000664000175000017500000001066213004147321010646 00000000000000#define astCLASS #include "axis.h" #include "box.h" #include "channel.h" #include "circle.h" #include "cmpframe.h" #include "cmpmap.h" #include "cmpregion.h" #include "dsbspecframe.h" #include "dssmap.h" #include "ellipse.h" #include "fitschan.h" #include "fluxframe.h" #include "timeframe.h" #include "timemap.h" #include "frame.h" #include "frameset.h" #include "grismmap.h" #include "interval.h" #include "intramap.h" #include "keymap.h" #include "loader.h" #include "lutmap.h" #include "mapping.h" #include "mathmap.h" #include "matrixmap.h" #include "nullregion.h" #include "object.h" #include "pcdmap.h" #include "permmap.h" #include "plot.h" #include "plot3d.h" #include "pointlist.h" #include "pointset.h" #include "polygon.h" #include "polymap.h" #include "prism.h" #include "normmap.h" #include "ratemap.h" #include "region.h" #include "shiftmap.h" #include "skyaxis.h" #include "skyframe.h" #include "slamap.h" #include "specfluxframe.h" #include "specframe.h" #include "specmap.h" #include "sphmap.h" #include "tranmap.h" #include "selectormap.h" #include "switchmap.h" #include "unitmap.h" #include "unitnormmap.h" #include "wcsmap.h" #include "winmap.h" #include "xmlchan.h" #include "zoommap.h" #include "stc.h" #include "stcresourceprofile.h" #include "stcsearchlocation.h" #include "stccatalogentrylocation.h" #include "stcobsdatalocation.h" #include "stcschan.h" #include "table.h" #include "fitstable.h" #include "error.h" #include "ast_err.h" #include #include /* *+ * Copyright: * Copyright (C) 1997-2016 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * RO: Russell Owen (LSST) * History: * 18-NOV-1997 (RFWS): * Original version. * 18-MAR-1998 (RFWS): * Added the IntraMap class. * 3-JUN-1999 (RFWS): * Added the PcdMap class. * 17-AUG-1999 (RFWS): * Added the MathMap class. * 8-JAN-2003 (DSB): * Added the SpecMap and SpecFrame classes. * 15-JUL-2003 (DSB): * Added the GrsimMap class. * 6-FEB-2009 (DSB): * Added the StcsChan class. * 20-APR-2016 (RO): * Added the UnitNormMap class. *- */ AstLoaderType *astGetLoader( const char *class, int *status ) { if ( !astOK ) return NULL; #define LOAD(name) \ if ( !strcmp( class, #name ) ) return (AstLoaderType *) astLoad##name##_ LOAD(Axis); LOAD(Box); LOAD(Channel); LOAD(Circle); LOAD(CmpFrame); LOAD(CmpMap); LOAD(CmpRegion); LOAD(DSBSpecFrame); LOAD(DssMap); LOAD(Ellipse); LOAD(FitsChan); LOAD(FitsTable); LOAD(FluxFrame); LOAD(Frame); LOAD(FrameSet); LOAD(GrismMap); LOAD(Interval); LOAD(IntraMap); LOAD(KeyMap); LOAD(LutMap); LOAD(Mapping); LOAD(MathMap); LOAD(MatrixMap); LOAD(NullRegion); LOAD(Object); LOAD(PcdMap); LOAD(PermMap); LOAD(Plot); LOAD(Plot3D); LOAD(PointList); LOAD(PointSet); LOAD(PolyMap); LOAD(Polygon); LOAD(Prism); LOAD(NormMap); LOAD(RateMap); LOAD(Region); LOAD(ShiftMap); LOAD(SkyAxis); LOAD(SkyFrame); LOAD(SlaMap); LOAD(SpecFluxFrame); LOAD(SpecFrame); LOAD(SpecMap); LOAD(SphMap); LOAD(SelectorMap); LOAD(SwitchMap); LOAD(Table); LOAD(TimeFrame); LOAD(TimeMap); LOAD(TranMap); LOAD(UnitMap); LOAD(UnitNormMap); LOAD(WcsMap); LOAD(WinMap); LOAD(XmlChan); LOAD(ZoomMap); LOAD(StcsChan); LOAD(Stc); LOAD(StcResourceProfile); LOAD(StcSearchLocation); LOAD(StcCatalogEntryLocation); LOAD(StcObsDataLocation); astError( AST__OCLUK, "astGetLoader: Object of unknown class \"%s\" cannot " "be loaded.", status, class ); return NULL; #undef LOAD } ast-8.3.0/stcsearchlocation.c0000664000175000017500000007300713004147321013112 00000000000000/* *class++ * Name: * StcSearchLocation * Purpose: * Correspond to the IVOA SearchLocation class. * Constructor Function: c astStcSearchLocation f AST_STCSEARCHLOCATION * Description: * The StcSearchLocation class is a sub-class of Stc used to describe * the coverage of a query. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcSearchLocation class inherits from the Stc class. * Attributes: * The StcSearchLocation class does not define any new attributes beyond * those which are applicable to all Stcs. * Functions: c The StcSearchLocation class does not define any new functions beyond those f The StcSearchLocation class does not define any new routines beyond those * which are applicable to all Stcs. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-NOV-2004 (DSB): * Original version. *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 StcSearchLocation /* Include 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 "stc.h" /* Coordinate stcs (parent class) */ #include "channel.h" /* I/O channels */ #include "region.h" /* Regions within coordinate systems */ #include "stcsearchlocation.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(StcSearchLocation) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(StcSearchLocation,Class_Init) #define class_vtab astGLOBAL(StcSearchLocation,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstStcSearchLocationVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstStcSearchLocation *astStcSearchLocationId_( void *, int, AstKeyMap **, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static void Dump( AstObject *, AstChannel *, int * ); /* Member functions. */ /* ================= */ void astInitStcSearchLocationVtab_( AstStcSearchLocationVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitStcSearchLocationVtab * Purpose: * Initialise a virtual function table for a StcSearchLocation. * Type: * Protected function. * Synopsis: * #include "stcsearchlocation.h" * void astInitStcSearchLocationVtab( AstStcSearchLocationVtab *vtab, const char *name ) * Class Membership: * StcSearchLocation vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the StcSearchLocation 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstStcVtab *stc; /* Pointer to Stc 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. */ astInitStcVtab( (AstStcVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAStcSearchLocation) 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 = &(((AstStcVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; stc = (AstStcVtab *) vtab; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump functions. */ astSetDump( vtab, Dump, "StcSearchLocation", "Query coverage" ); /* 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) ); } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ /* None */ /* Destructor. */ /* ----------- */ /* None */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for StcSearchLocation 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 StcSearchLocation class to an output Channel. * Parameters: * this * Pointer to the StcSearchLocation 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 Variables: */ AstStcSearchLocation *this; /* Pointer to the StcSearchLocation structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the StcSearchLocation structure. */ this = (AstStcSearchLocation *) this_object; /* Write out values representing the instance variables for the StcSearchLocation 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAStcSearchLocation and astCheckStcSearchLocation functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(StcSearchLocation,Stc) astMAKE_CHECK(StcSearchLocation) AstStcSearchLocation *astStcSearchLocation_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, int *status, ...) { /* *++ * Name: c astStcSearchLocation f AST_STCSEARCHLOCATION * Purpose: * Create a StcSearchLocation. * Type: * Public function. * Synopsis: c #include "stcsearchlocation.h" c AstStcResourceProfile *astStcSearchLocation( AstRegion *region, c int ncoords, AstKeyMap *coords[], const char *options, ... ) f RESULT = AST_STCSEARCHLOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) * Class Membership: * StcSearchLocation constructor. * Description: * This function creates a new StcSearchLocation and optionally initialises its * attributes. * * The StcSearchLocation class is a sub-class of Stc used to describe * the coverage of a VO query. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Parameters: c region f REGION = INTEGER (Given) * Pointer to the encapsulated Region. c ncoords f NCOORDS = INTEGER (Given) c The length of the "coords" array. Supply zero if "coords" is NULL. f The length of the COORDS array. Supply zero if COORDS should be f ignored. c coords f COORDS( NCOORDS ) = INTEGER (Given) c Pointer to an array holding "ncoords" AstKeyMap pointers (if "ncoords" f An array holding NCOORDS AstKeyMap pointers (if NCOORDS * is zero, the supplied value is ignored). Each supplied KeyMap * describes the contents of a single STC element, and * should have elements with keys given by constants AST__STCNAME, * AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. Any of these elements may be omitted, but no other * elements should be included. If supplied, the AST__STCNAME element * should be a vector of character string pointers holding the "Name" * item for each axis in the coordinate system represented by c "region". f REGION. * Any other supplied elements should be scalar elements, each holding * a pointer to a Region describing the associated item of ancillary * information (error, resolution, size, pixel size or value). These * Regions should describe a volume within the coordinate system c represented by "region". f represented by REGION. 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 StcSearchLocation. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new StcSearchLocation. The syntax used is identical to that for the f AST_SET routine. 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 astStcSearchLocation() f AST_STCSEARCHLOCATION = INTEGER * A pointer to the new StcSearchLocation. * Notes: * - A deep copy is taken of the supplied Region. This means that * any subsequent changes made to the encapsulated Region using the * supplied pointer will have no effect on the Stc. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstRegion *region; /* Pointer to Region structure */ AstStcSearchLocation *new; /* Pointer to new StcSearchLocation */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the Region structure provided. */ region = astCheckRegion( region_void ); /* Initialise the StcSearchLocation, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcSearchLocation( NULL, sizeof( AstStcSearchLocation ), !class_init, &class_vtab, "StcSearchLocation", region, ncoords, coords ); /* 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 StcSearchLocation'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 StcSearchLocation. */ return new; } AstStcSearchLocation *astStcSearchLocationId_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, ... ) { /* * Name: * astStcSearchLocationId_ * Purpose: * Create a StcSearchLocation. * Type: * Private function. * Synopsis: * #include "stcsearchlocation.h" * AstStcSearchLocation *astStcSearchLocationId_( AstRegion *region, * int ncoords, AstKeyMap *coords[], const char *options, ... ) * Class Membership: * StcSearchLocation constructor. * Description: * This function implements the external (public) interface to the * astStcSearchLocation constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astStcSearchLocation_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astStcSearchLocation_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astStcSearchLocation_. * Returned Value: * The ID value associated with the new StcSearchLocation. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstKeyMap **keymaps; /* Pointer to array of KeyMap pointers */ AstRegion *region; /* Pointer to Region structure */ AstStcSearchLocation *new; /* Pointer to new StcSearchLocation */ int icoord; /* Keymap index */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain a Region pointer from the supplied ID and validate the pointer to ensure it identifies a valid Region. */ region = astVerifyRegion( astMakePointer( region_void ) ); /* Obtain pointer from the supplied KeyMap ID's and validate the pointers to ensure it identifies a valid KeyMap. */ keymaps = astMalloc( sizeof( AstKeyMap * )*(size_t) ncoords ); if( keymaps ) { for( icoord = 0; icoord < ncoords; icoord++ ) { keymaps[ icoord ] = astVerifyKeyMap( astMakePointer( coords[ icoord ] ) ); } } /* Initialise the StcSearchLocation, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcSearchLocation( NULL, sizeof( AstStcSearchLocation ), !class_init, &class_vtab, "StcSearchLocation", region, ncoords, keymaps ); /* Free resources. */ keymaps = astFree( keymaps ); /* 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 StcSearchLocation'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 StcSearchLocation. */ return astMakeId( new ); } AstStcSearchLocation *astInitStcSearchLocation_( void *mem, size_t size, int init, AstStcSearchLocationVtab *vtab, const char *name, AstRegion *region, int ncoords, AstKeyMap **coords, int *status ) { /* *+ * Name: * astInitStcSearchLocation * Purpose: * Initialise a StcSearchLocation. * Type: * Protected function. * Synopsis: * #include "stcsearchlocation.h" * AstStcSearchLocation *astInitStcSearchLocation_( void *mem, size_t size, * int init, AstStcSearchLocationVtab *vtab, * const char *name, AstRegion *region, * int ncoords, AstKeyMap **coords ) * Class Membership: * StcSearchLocation initialiser. * Description: * This function is provided for use by class implementations to initialise * a new StcSearchLocation object. It allocates memory (if necessary) to accommodate * the StcSearchLocation plus any additional data associated with the derived class. * It then initialises a StcSearchLocation 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 StcSearchLocation at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the StcSearchLocation is to be initialised. * This must be of sufficient size to accommodate the StcSearchLocation data * (sizeof(StcSearchLocation)) 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 StcSearchLocation (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 StcSearchLocation * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the StcSearchLocation'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 StcSearchLocation. * 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). * region * A pointer to the Region encapsulated by the StcSearchLocation. * ncoords * Number of KeyMap pointers supplied in "coords". Can be zero. * Ignored if "coords" is NULL. * coords * Pointer to an array of "ncoords" KeyMap pointers, or NULL if * "ncoords" is zero. Each KeyMap defines defines a single * element, and should have elements with keys given by constants * AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. These elements hold values for the corresponding * components of the STC AstroCoords element. Any of these elements may * be omitted, but no other elements should be included. All supplied * elements should be vector elements, with vector length less than or * equal to the number of axes in the supplied Region. The data type of * all elements should be "double", except for AST__STCNAME which should * be "character string". If no value is available for a given axis, then * AST__BAD (or NULL for the AST__STCNAME element) should be stored in * the vector at the index corresponding to the axis (trailing axes * can be omitted completely from the KeyMap). * Returned Value: * A pointer to the new StcSearchLocation. * 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: */ AstStcSearchLocation *new; /* Pointer to new StcSearchLocation */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitStcSearchLocationVtab( vtab, name ); /* Initialise a Stc structure (the parent class) as the first component within the StcSearchLocation structure, allocating memory if necessary. */ new = (AstStcSearchLocation *) astInitStc( mem, size, 0, (AstStcVtab *) vtab, name, region, ncoords, coords ); /* If an error occurred, clean up by deleting the new StcSearchLocation. */ if ( !astOK ) new = astDelete( new ); /* Return a pointer to the new StcSearchLocation. */ return new; } AstStcSearchLocation *astLoadStcSearchLocation_( void *mem, size_t size, AstStcSearchLocationVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadStcSearchLocation * Purpose: * Load a StcSearchLocation. * Type: * Protected function. * Synopsis: * #include "stcsearchlocation.h" * AstStcSearchLocation *astLoadStcSearchLocation( void *mem, size_t size, AstStcSearchLocationVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * StcSearchLocation loader. * Description: * This function is provided to load a new StcSearchLocation 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 * StcSearchLocation structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a StcSearchLocation at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the StcSearchLocation is to be * loaded. This must be of sufficient size to accommodate the * StcSearchLocation data (sizeof(StcSearchLocation)) 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 StcSearchLocation (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 StcSearchLocation 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(AstStcSearchLocation) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new StcSearchLocation. If this is NULL, a pointer * to the (static) virtual function table for the StcSearchLocation 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 "StcSearchLocation" is used instead. * Returned Value: * A pointer to the new StcSearchLocation. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstStcSearchLocation *new; /* Pointer to the new StcSearchLocation */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this StcSearchLocation. In this case the StcSearchLocation belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstStcSearchLocation ); vtab = &class_vtab; name = "StcSearchLocation"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitStcSearchLocationVtab( 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 StcSearchLocation. */ new = astLoadStc( mem, size, (AstStcVtab *) 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, "StcSearchLocation" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* If an error occurred, clean up by deleting the new StcSearchLocation. */ if ( !astOK ) new = astDelete( new ); } /* Return the new StcSearchLocation pointer. */ return new; } /* 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. */ ast-8.3.0/fitschan.c0000664000175000017500000607167513004147321011220 00000000000000/* *class++ * Name: * FitsChan * Purpose: * I/O Channel using FITS header cards to represent Objects. * Constructor Function: c astFitsChan f AST_FITSCHAN * Description: * A FitsChan is a specialised form of Channel which supports I/O * operations involving the use of FITS (Flexible Image Transport * System) header cards. Writing an Object to a FitsChan (using c astWrite) will, if the Object is suitable, generate a f AST_WRITE) will, if the Object is suitable, generate a * description of that Object composed of FITS header cards, and * reading from a FitsChan will create a new Object from its FITS * header card description. * * While a FitsChan is active, it represents a buffer which may * contain zero or more 80-character "header cards" conforming to * FITS conventions. Any sequence of FITS-conforming header cards * may be stored, apart from the "END" card whose existence is * merely implied. The cards may be accessed in any order by using * the FitsChan's integer Card attribute, which identifies a "current" * card, to which subsequent operations apply. Searches c based on keyword may be performed (using astFindFits), new c cards may be inserted (astPutFits, astPutCards, astSetFits) and c existing ones may be deleted (astDelFits), extracted (astGetFits), c or changed (astSetFits). f based on keyword may be performed (using AST_FINDFITS), new f cards may be inserted (AST_PUTFITS, AST_PUTCARDS, AST_SETFITS) and f existing ones may be deleted (AST_DELFITS), extracted f (AST_GETFITS) or changed (AST_SETFITS). * * When you create a FitsChan, you have the option of specifying * "source" and "sink" functions which connect it to external data * stores by reading and writing FITS header cards. If you provide * a source function, it is used to fill the FitsChan with header cards * when it is accessed for the first time. If you do not provide a * source function, the FitsChan remains empty until you explicitly enter c data into it (e.g. using astPutFits, astPutCards, astWrite f data into it (e.g. using AST_PUTFITS, AST_PUTCARDS, AST_WRITE * or by using the SourceFile attribute to specifying a text file from * which headers should be read). When the FitsChan is deleted, any * remaining header cards in the FitsChan can be saved in either of * two ways: 1) by specifying a value for the SinkFile attribute (the * name of a text file to which header cards should be written), or 2) * by providing a sink function (used to to deliver header cards to an * external data store). If you do not provide a sink function or a * value for SinkFile, any header cards remaining when the FitsChan * is deleted will be lost, so you should arrange to extract them * first if necessary c (e.g. using astFindFits or astRead). f (e.g. using AST_FINDFITS or AST_READ). * * Coordinate system information may be described using FITS header * cards using several different conventions, termed * "encodings". When an AST Object is written to (or read from) a * FitsChan, the value of the FitsChan's Encoding attribute * determines how the Object is converted to (or from) a * description involving FITS header cards. In general, different * encodings will result in different sets of header cards to * describe the same Object. Examples of encodings include the DSS * encoding (based on conventions used by the STScI Digitised Sky * Survey data), the FITS-WCS encoding (based on a proposed FITS * standard) and the NATIVE encoding (a near loss-less way of * storing AST Objects in FITS headers). * * The available encodings differ in the range of Objects they can * represent, in the number of Object descriptions that can coexist * in the same FitsChan, and in their accessibility to other * (external) astronomy applications (see the Encoding attribute * for details). Encodings are not necessarily mutually exclusive * and it may sometimes be possible to describe the same Object in * several ways within a particular set of FITS header cards by * using several different encodings. * c The detailed behaviour of astRead and astWrite, when used with f The detailed behaviour of AST_READ and AST_WRITE, when used with * a FitsChan, depends on the encoding in use. In general, however, c all successful use of astRead is destructive, so that FITS header cards f all successful use of AST_READ is destructive, so that FITS header cards * are consumed in the process of reading an Object, and are * removed from the FitsChan (this deletion can be prevented for * specific cards by calling the c astRetainFits function). f AST_RETAINFITS routine). * An unsuccessful call of c astRead f AST_READ * (for instance, caused by the FitsChan not containing the necessary * FITS headers cards needed to create an Object) results in the * contents of the FitsChan being left unchanged. * * If the encoding in use allows only a single Object description * to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF c encodings), then write operations using astWrite will f encodings), then write operations using AST_WRITE will * over-write any existing Object description using that * encoding. Otherwise (e.g. the NATIVE encoding), multiple Object * descriptions are written sequentially and may later be read * back in the same sequence. * Inheritance: * The FitsChan class inherits from the Channel class. * Attributes: * In addition to those attributes common to all Channels, every * FitsChan also has the following attributes: * * - AllWarnings: A list of the available conditions * - Card: Index of current FITS card in a FitsChan * - CardComm: The comment of the current FITS card in a FitsChan * - CardName: The keyword name of the current FITS card in a FitsChan * - CardType: The data type of the current FITS card in a FitsChan * - CarLin: Ignore spherical rotations on CAR projections? * - CDMatrix: Use a CD matrix instead of a PC matrix? * - Clean: Remove cards used whilst reading even if an error occurs? * - DefB1950: Use FK4 B1950 as default equatorial coordinates? * - Encoding: System for encoding Objects as FITS headers * - FitsAxisOrder: Sets the order of WCS axes within new FITS-WCS headers * - FitsDigits: Digits of precision for floating-point FITS values * - Iwc: Add a Frame describing Intermediate World Coords? * - Ncard: Number of FITS header cards in a FitsChan * - Nkey: Number of unique keywords in a FitsChan * - TabOK: Should the FITS "-TAB" algorithm be recognised? * - PolyTan: Use PVi_m keywords to define distorted TAN projection? * - Warnings: Produces warnings about selected conditions * Functions: c In addition to those functions applicable to all Channels, the c following functions may also be applied to all FitsChans: f In addition to those routines applicable to all Channels, the f following routines may also be applied to all FitsChans: * c - astDelFits: Delete the current FITS card in a FitsChan c - astEmptyFits: Delete all cards in a FitsChan c - astFindFits: Find a FITS card in a FitsChan by keyword c - astGetFits: Get a keyword value from a FitsChan c - astGetTables: Retrieve any FitsTables from a FitsChan c - astPurgeWCS: Delete all WCS-related cards in a FitsChan c - astPutCards: Stores a set of FITS header card in a FitsChan c - astPutFits: Store a FITS header card in a FitsChan c - astPutTable: Store a single FitsTable in a FitsChan c - astPutTables: Store multiple FitsTables in a FitsChan c - astReadFits: Read cards in through the source function c - astRemoveTables: Remove one or more FitsTables from a FitsChan c - astRetainFits: Ensure current card is retained in a FitsChan c - astSetFits: Store a new keyword value in a FitsChan c - astShowFits: Display the contents of a FitsChan on standard output c - astTableSource: Register a source function for FITS table access c - astTestFits: Test if a keyword has a defined value in a FitsChan c - astWriteFits: Write all cards out to the sink function f - AST_DELFITS: Delete the current FITS card in a FitsChan f - AST_EMPTYFITS: Delete all cards in a FitsChan f - AST_FINDFITS: Find a FITS card in a FitsChan by keyword f - AST_GETFITS: Get a keyword value from a FitsChan f - AST_GETTABLES: Retrieve any FitsTables from a FitsChan f - AST_PURGEWCS: Delete all WCS-related cards in a FitsChan f - AST_PUTCARDS: Stores a set of FITS header card in a FitsChan f - AST_PUTFITS: Store a FITS header card in a FitsChan f - AST_PUTTABLE: Store a single FitsTables in a FitsChan f - AST_PUTTABLES: Store multiple FitsTables in a FitsChan f - AST_READFITS: Read cards in through the source function f - AST_REMOVETABLES: Remove one or more FitsTables from a FitsChan f - AST_RETAINFITS: Ensure current card is retained in a FitsChan f - AST_SETFITS: Store a new keyword value in a FitsChan c - AST_SHOWFITS: Display the contents of a FitsChan on standard output f - AST_TABLESOURCE: Register a source function for FITS table access f - AST_TESTFITS: Test if a keyword has a defined value in a FitsChan f - AST_WRITEFITS: Write all cards out to the sink function * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008-2011 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink, RAL) * TIMJ: Tim Jenness (JAC, Hawaii) * History: * 11-DEC-1996 (DSB): * Original version. * 20-MAR-1997 (DSB): * Made keyword setting and getting functions protected instead of * public. Renamed public methods. Added Ncard attribute. * 20-MAY-1997 (RFWS): * Tidied public prologues. * 30-JUN-1997 (DSB): * Added support for reading post-2000 DATE-OBS strings. Reading DSS * or FITS-WCS objects now returns NULL unless the FitsChan is * positioned at the start-of-file prior to the read. Bug fixed * which caused Ncard to be returned too large by one. Removed * dependancy on hard-wired header and footer text in Native * FitsChans. * 18-AUG-1997 (DSB): * Bug fixed in WcsNative which caused incorrect CRVAL values * to be used if the axes needed permuting. Values assigned to the * Projection attribute fo the SkyFrames created by astRead. * 2-SEP-1997 (DSB): * Added the IRAF convention that EPOCH=0.0 really means EPOCH=1950.0 * (the EPOCH keyword is deprecated in the new FITS-WCS conventions * and is taken always as a Besselian epoch). * 19-SEP-1997 (DSB): * Corrected interpretation of the FITS CD matrix. * 25-SEP-1997 (DSB): * o Fix bug in LinearMap which caused it always to detect a linear * mapping. For instance, this allowed DssMaps to be erroneously * written out using FITS-WCS encoding with a CAR projection. * o Assign a full textual description to SkyFrame's Projection * attribute instead of a 3 letter acronym. * o If DATE-OBS >= 1999.0 then DATE-OBS is now written in new * Y2000 format. For DATE-OBS < 1999.0, the old format is written. * o Add new attribute CDMatrix to determine whether PC or CD * matrices should be used when writing objects using FITS-WCS * encoding. * o Modified the way floating point values are formatted to omit * unnecessary leading zeros from the exponent (i.e. E-5 instead of * E-05). * o New-line characters at the end of supplied header cards are now * ignored. * o Cater for EQUINOX specified as a string prefixed by B or J * rather than as a floating point value (some HST data does this). * o Corrected SetValue so that it always inserts comment cards * rather than over-write existing comment cards. Previously, * writing a FrameSet to a DSS encoded FitsChan resulted in all * comments cards being stripped except for the last one. * o Reading a FrameSet from a DSS-encoded FrameSet now only * removes the keywords actually required to construct the FrameSet. * Previously, all keywords were removed. * o The EPOCH and EQUINOX keywords created when a FrameSet is * written to a DSS-encoded FitsChan are now determined from the * epoch and equinox of the current Frame, instead of from a copy * of the original FitsChan stored within the DssMap. * o The Encoding and CDMatrix attributes, and keyword types are * now stored as strings externally instead of integers. * 11-NOV-1997 (DSB): * o Assume default of j2000 for DSS EQUINOX value. * o Check for null object pointers in the interfaces for * virtual functions which execute even if an error has previously * occurred. Otherwise, a segmentation violation can occur when * trying to find the member function pointer. * o Trailing spaces ignored in Encoding attribute. * o Bugs fixed in FindWcs and SetValue which resulted in WCS cards * being written at the wrong place if the supplied FitsChan does not * contain any WCS keywords. * o Default for CDMatrix (if no axis rotation keywords can be found) * changed to 2 (i.e. use "CDi_j" form keywords). * o Write now leaves the current card unchanged if nothing is * written to the FitsChan. * 17-NOV-1997 (RFWS): * Disabled use of CDmatrix. Fixed initialisation problems in * astLoadFitsChan. * 24-NOV-1997 (DSB): * Replace references to error code AST__OPT with AST__RDERR. * 28-NOV-1997 (DSB): * o Function WcsValues modified to prevent it from changing the * current card. Previously, this could cause new cards to be * written to the wrong place in a FITS-WCS encoded FitsChan. * o Description of argument "value" corrected in prologue of * function SetFits. * o Argument "lastkey" removed from function SetValue since it * was never used (it was a relic from a previous method of * determining where to store new cards). Corresponding changes * have been made to all the functions which create "lastkey" values * or pass them on to SetValue (i.e DescWcs, WcsPrimary, WcsSecondary, * WriteWcs and WriteDss). * 10-DEC-1997 (DSB): * Bug fixed which caused the initial character designating the system * within CTYPE value (eg E in ELON, G in GLON, etc) to be omitted. * 1-JUN-1998 (DSB): * CDELT values of zero are now replaced by a small non-zero value * when creating the "pixel-to-relative physical" transformation * matrix. Previously, zero CDELT values could cause the matrix to * be non-invertable. * 4-SEP-1998 (DSB): * - Indicate that SphMaps created by this class when using FITS-WCS * encoding all operate on the unit sphere. This aids simplification. * - Fix a bug in StoreFits which caused CD matrices to be indexed * incorrectly (sometimes causing floating exceptions) if they do not * describe a celestial longitude/latitude system. * - Changed astFindFits to ignore trailing spaces in the keyword * template. * - astSplit changed so that an error is not reported if a textual * keyword value ends before column 20. * 7-OCT-1998 (DSB): * - Corrected test for linearity in LinearMap to include a factor * of the test vector length. Also LinearMap now uses a simplified * Mapping. * 5-NOV-1998 (DSB): * Added FITS-IRAF encoding. * 9-NOV-1998 (DSB): * - Corrected values of macros DSS_ENCODING and MAX_ENCODING. * - Corrected erroneous success indication in IrafStore. * - Included checks for bad values in function LinearMap. * 17-NOV-1998 (DSB): * The Domain name GRID is now given to the Base Frame in any FrameSets * created by astRead when using FitsChans with DSS, FITS-WCS or * FITS-IRAF encodings. * 18-DEC-1998 (DSB): * Check for "D" exponents in floating point keyword strings. * 12-FEB-1998 (DSB): * Modified EncodeFloat to avoid exceeding the 20 character FITS * limit wherever possible if FitsDigits is positive. * 10-MAY-1998 (DSB): * Bug fixed in astSplit which caused comments associated with string * keywords to be lost when storing the card in a FitsChan. * 15-JUN-1999 (DSB): * Report an error if an unrecognised projection name is supplied. * 9-DEC-1999 (DSB): * - Fixed bug in WcsNatPole which could result in longitude values * being out by 180 degrees for cylindrical projections such as CAR. * - Only report an "unrecognised projection" error for CTYPE values * which look like celestial longitude or latitude axes (i.e. if the * first 4 characters are "RA--", "DEC-", "xLON" or "xLAT", and the * fifth character is "-"). * - Added function SpecTrans to translated keywords related to the * IRAF ZPX projection into keyword for the standard ZPN projection. * - Add ICRS as a valid value for the RADECSYS keyword. Since the * SkyFrame class does not yet support ICRS, an FK5 SkyFrame is * created if RADECSYS=ICRS. * 16-DEC-1999 (DSB): * - Modified SpecTrans so that all keywords used to created a * standard WCS representation from a non-standard one are consumed * by the astRead operation. * - Changed the text of ASTWARN cards added to the FitsChan if an * IRAF ZPX projection is found to require unsupported corrections. * - Simplified the documentation describing the handling of the IRAF * ZPX projection. * - Fixed code which assumed that the 10 FITS-WCS projection * parameters were PROJP1 -> PROJP10. In fact they are PROJP0 - * PROJP9. This could cause projection parameter values to be * incorrectly numbered when they are written out upon deletion of * the FitsChan. * 1-FEB-2000 (DSB): * Check that FITS_IRAF encoding is not being used before using a * PC matrix when reading WCS information from a header. This is * important if the header contains both PC and CD matrices. * 8-FEB-2000 (DSB): * - Header cards are now only consumed by an astRead operation if the * operation succeeds (i.e. returns a non-null Object). * - The original FITS-WCS encoding has been renamed as FITS-PC (to * indicate the use of a PCiiijjj matrix), and a new FITS-WCS * encoding has been added. * - The disabled CDMatrix attribute has been removed. * - Bug in LinearMap corrected which prevented genuinely linear * Mappings from being judged to be linear. This bug was previously * fudged (so it now appears) by the introduction of the test vector * length factor (see History entry for 7-OCT-1998). This test * vector length scale factor has consequently now been removed. * - Added FITS-AIPS encoding. * - The critical keywords used to select default encoding have been * changed. * - Support for common flavours of IRAF TNX projections added. * - The algorithm used to find a WcsMap in the supplied FrameSet * has been improved so that compound Mappings which contain complex * mixtures of parallel and serial Mappings can be translated into * FITS-WCS encoding. * - Trailing white space in string keyword values is now retained * when using foreign encodings to enable correct concatenation where * a string has been split over several keywords. E.g. if 2 string * keywords contain a list of formatted numerical values (e.g. IRAF * WAT... keywords), and the 1st one ends "0.123 " and the next one * begins "1234.5 ", the trailing space at the end of the first keyword * is needed to prevent the two numbers being merged into "0.1231234.5". * Trailing spaces in native encodings is still protected by enclosing * the whole string in double quotes. * - The Channel methods WriteString and GetNextData can now save * and restore strings of arbitary length. This is done by storing * as much of the string as possible in the usual way, and then * storing any remaining characters in subsequent CONTINUE cards, * using the FITSIO conventions. This storage and retrieval of long * strings is only available for native encodings. * 19-MAY-2000 (DSB): * Added attribute Warnings. Lowered DSS in the priority list * of encodings implemented by GetEncoding. * 6-OCT-2000 (DSB): * Increased size of buffers used to store CTYPE values to take * account of the possiblity of lots of trailing spaces. * 5-DEC-2000 (DSB): * Add support for the WCSNAME FITS keyword. * 12-DEC-2000 (DSB): * Add a title to each physical, non-celestial coord Frame based on * its Domain name (if any). * 3-APR-2001 (DSB): * - Use an "unknown" celestial coordinate system, instead of a * Cartesian coordinate system, if the CTYPE keywords specify an * unknown celestial coordinate system. * - Do not report an error if there are no CTYPE keywords in the * header (assume a unit mapping, like in La Palma FITS files). * - Add a NoCTYPE warning condition. * - Added AllWarnings attribute. * - Ensure multiple copies of identical warnings are not produced. * - Use the Object Ident attribute to store the identifier letter * associated with each Frame read from a secondary axis description, * so that they can be given the same letter when they are written * out to a new FITS file. * 10-AUG-2001 (DSB): * - Corrected function value returned by SkySys to be 1 unless an * error occurs. This error resulted in CAR headers being produced * by astWrite with CRVAL and CD values till in radians rather than * degrees. * - Introduced SplitMap2 in order to guard against producing * celestial FITS headers for a Mapping which includes more than * one WcsMap. * 13-AUG-2001 (DSB): * - Modified FixNew so that it retains the current card index if possible. * This fixed a bug which could cause headers written out using Native * encodings to be non-contiguous. * - Corrected ComBlock to correctly remove AST comment blocks in * native encoded fitschans. * 14-AUG-2001 (DSB): * - Modified FixUsed so that it it does not set the current card * back to the start of file if the last card in the FitsChan is * deleted. * 16-AUG-2001 (DSB): * Modified WcsNative to limit reference point latitude to range * +/-90 degs (previously values outside this range were wrapped * round onto the opposite meridian). Also added new warning * condition "badlat". * 23-AUG-2001 (DSB): * - Re-write LinearMap to use a least squares fit. * - Check that CDj_i is not AST__BAD within WcsWithWcs when * forming the increments along each physical axis. * 28-SEP-2001 (DSB): * GoodWarns changed so that no error is reported if a blank list * of conditions is supplied. * 12-OCT-2001 (DSB): * - Added DefB1950 attribute. * - Corrected equations which calculate CROTA when writing * FITS-AIPS encodings. * - Corrected equations which turn a CROTA value into a CD matrix. * 29-NOV-2001 (DSB): * Corrected use of "_" and "-" characters when referring to FK4-NO-E * system in function SkySys. * 20-FEB-2002 (DSB) * Added CarLin attribute. * 8-MAY-2002 (DSB): * Correct DSSToStore to ignore trailing blanks in the PLTDECSN * keyword value. * 9-MAY-2002 (DSB): * Correct GetCard to avoid infinite loop if the current card has * been marked as deleted. * 25-SEP-2002 (DSB): * AIPSFromStore: use larger of coscro and sincro when determining * CDELT values. Previously a non-zero coscro was always used, even * if it was a s small as 1.0E-17. * 3-OCT-2002 (DSB): * - SkySys: Corrected calculation of longitude axis index for unknown * celestial systems. * - SpecTrans: Corrected check for latcor terms for ZPX projections. * - WcsFrame: Only store an explicit equinox value in a skyframe if * it needs one (i.e. if the system is ecliptic or equatorial). * - WcsWithWcs: For Zenithal projections, always use the default * LONPOLE value, and absorb any excess rotation caused by this * into the CD matrix. * - WcsWithWcs: Improve the check that the native->celestial mapping * is a pure rotation, allowing for rotations which change the * handed-ness of the system (if possible). * - WcsWithWcs: Avoid using LONPOLE keywords when creating headers * for a zenithal projection. Instead, add the corresponding rotation * into the CD matrix. * 22-OCT-2002 (DSB): * - Retain leading and trailing white space within COMMENT cards. * - Only use CTYPE comments as axis labels if all non-celestial * axes have a unique non-blank comment (otherwise use CTYPE * values as labels). * - Updated to use latest FITS-WCS projections. This means that the * "TAN with projection terms" is no longer a standard FITS * projection. It is now represented using the AST-specific TPN * projection (until such time as FITS-WCS paper IV is finished). * - Remove trailing "Z" from DATE-OBS values created by astWrite. * 14-NOV-2002 (DSB): * - WcsWithWcs: Corrected to ignore longitude axis returned by * astPrimaryFrame since it does not take into account any axis * permutation. * 26-NOV-2002 (DSB): * - SpecTrans: Corrected no. of characters copied from CTYPE to PRJ, * (from 5 to 4), and terminate PRJ correctly. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitFitsChanVtab * method. * 22-JAN-2003 (DSB): * Restructured the functions used for reading FITS_WCS headers to * make the distinction between the generic parts (pixel->intermediate * world coordinates) and the specialised parts (e.g. celestial, * spectral, etc) clearer. * 31-JAN-2003 (DSB) * - Added Clean attribute. * - Corrected initialisation and defaulting of CarLin and DefB1950 * attributes. * - Extensive changes to allow foreign encodings to be produced in * cases where the Base Frame has fewer axes than the Current Frame. * 12-FEB-2003 (DSB) * - Modified SetFits so that the existing card comment is retained * if the new data value equals the existing data value. * 30-APR-2003 (DSB): * - Revert to standard "TAN" code for distorted tan projections, * rather than using the "TPN" code. Also recognise QVi_m (produced * by AUTOASTROM) as an alternative to PVi_m when reading distorted * TAN headers. * 22-MAY-2003 (DSB): * Modified GetEncoding so that the presence of RADECSYS and/or * PROJPm is only considered significant if the modern equivalent * keyword (REDESYS or PVi_m) is *NOT* present. * 2-JUN-2003 (DSB): * - Added support for PCi_j kewwords within FITS-WCS encoding * - Added CDMatrix attribute * - Changed internal FitsStore usage to use PC/CDELT instead of CD * (as preparation for FITS-WCS paper IV). * - Added warning "BadMat". * 11-JUN-2003 (DSB): * - Modified WcsNative to use the new SphMap PolarLong attribute * in order to ensure correct propagation of the longitude CRVAL * value in cases where the fiducial point is coincident with a pole. * - Use PVi_3 and PVi_4 for longitude axis "i" (if present) in * preference to LONPOLE and LATPOLE when reading a FITS-WCS header. * Note, these projection values are never written out (LONPOLE and * LATPOLE are written instead). * - Associate "RADESYS=ICRS" with SkyFrame( "System=ICRS" ), rather * than SkyFrame( "System=FK5" ). * - If DefB1950 is zero, use ICRS instead of FK5 as the default RADESYS * if no EQUINOX is present. * 1-SEP-2003 (DSB): * - Modify Dump so that it dumps all cards including those flagged as * having been read. * - Added "reset" parameter to FixUsed. * - WcsMapFrm: store an Ident of ' ' for the primary coordinate * description (previously Ident was left unset) * - Default value for DefB1950 attribute now depends on the value * of the Encoding attribute. * 15-SEP-2003 (DSB): * - Added Warnings "BadVal", "Distortion". * - Ignore FITS-WCS paper IV CTYPE distortion codes (except for * "-SIP" which is interpreted correctly on reading). * 22-OCT-2003 (DSB): * - GetEncoding: If the header contains CDi_j but does not contain * any of the old IRAF keywords (RADECSYS, etc) then assume FITS-WCS * encoding. This allows a FITS-WCS header to have both CDi_j *and* * CROTA keywords. * 5-JAN-2004 (DSB): * - SpecTrans: Use 1.0 (instead of the CDELT value) as the * diagonal PCi_j term for non-celestial axes with associated CROTA * values. * 12-JAN-2004 (DSB): * - CelestialAxes: Initialise "tmap1" pointer to NULL in case of error * (avoids a segvio happening in the case of an error). * - AddVersion: Do not attempt to add a Frame into the FITS header * if the mapping from grid to frame is not invertable. * - WorldAxes: Initialise the returned "perm" values to safe values, * and return these values if no basis vectors cen be created. * 19-JAN-2004 (DSB): * - When reading a FITS-WCS header, allow all keywords to be defaulted * as decribed in paper I. * 27-JAN-2004 (DSB): * - Modify FitLine to use correlation between actual and estimated * axis value as the test for linearity. * - Modify RoundFString to avoid writing beyond the end of the * supplied buffer if the supplied string contains a long list of 9's. * 11-MAR-2004 (DSB): * - Modified SpecTrans to check all axis descriptions for keywords * to be translated. * 19-MAR-2004 (DSB): * - Added astPutCards to support new fits_hdr2str function in * CFITSIO. * 25-MAR-2004 (DSB): * - Corrected bug in astSplit which causes legal cards to be * rejected because characters beyond the 80 char limit are being * considered significant. * - Corrected bug in SpecTrans which caused QV keywords to be * ignored. * 15-APR-2004 (DSB): * - SpecTrans modified to include translation of old "-WAV", "-FRQ" * and "-VEL" spectral algorithm codes to modern "-X2P" form. * - WcsFromStore modified to supress creation of WCSAXES keywords * for un-used axis versions. * - IsMapLinear modified to improve fit by doing a second least * squares fit to the residualleft by the first least squares fit. * 16-APR-2004 (DSB): * - NonLinSpecWcs: Issue a warning if an illegal non-linear * spectral code is encountered. * - Add a BadCTYPE warning condition. * - Corrected default value for Clean so that it is zero (as * documented). * 21-APR-2004 (DSB): * - FindWcs: Corrected to use correct OBSGEO template. This bug * caused OBSGEO keywords to be misplaced in written headers. * 23-APR-2004 (DSB): * - SplitMap: Modified so that a Mapping which has celestial axes * with constant values (such as produced by a PermMap) are treated * as a valid sky coordinate Mapping. * - AddFrame modified so that WCS Frames with a different number * of axes ot the pixel Frame can be added into the FrameSet. * - IRAFFromStore and AIPSFromStore modified so that they do not * create any output keywords if the number of WCS axes is different * to the number of pixel axes. * - Handling of OBSGEO-X/Y/Z corrected again. * - WCSFromStore modified to avouid writing partial axis descriptions. * 26-APR-2004 (DSB): * - Corrected text of output SPECSYS keyword values. * 17-MAY-2004 (DSB): * - Added IWC attribute. * 15-JUN-2004 (DSB): * - Ensure out-of-bounds longitude CRPIX values for CAR * projections are wrapped back into bounds. * 21-JUN-2004 (DSB): * - Ensure primary MJD-OBS value is used when reading foreign FITS * headers. * 7-JUL-2004 (DSB): * - Issue errors if an un-invertable PC/CD matrix is supplied in a * FITS-WCS Header. * 11-JUL-2004 (DSB): * - Re-factor code for checking spectral axis CTYPE values into * new function IsSpectral. * - Modify AIPSFromSTore to create spectral axis keywords if * possible. * - Modify SpecTrans to recognize AIPS spectral axis keywords, and * to convert "HZ" to "Hz". * - Added FITS-AIPS++ encoding. * 12-AUG-2004 (DSB): * - Convert GLS projection codes to equivalent SFL in SpecTrans. * - Added FITS-CLASS encoding. * 16-AUG-2004 (DSB): * - Removed support for paper III keyword VSOURCE, and added * support for SSYSSRC keyword. * - Added initial support for CLASS encoding. * - In FitOK: Changed tolerance for detecting constant values * from 1.0E-10 to 1.0E-8. * 17-AUG-2004 (DSB): * Correct GetFiducialNSC so that the stored values for longitude * parameters 1 and 2 are ignored unless the value of parameter 0 is * not zero. * 19-AUG-2004 (DSB): * Modify SpecTrans to ignore any CDELT values if the header * includes some CDi_j values. * 26-AUG-2004 (DSB): * Modify astSplit_ to allow floating point keyword values which * include an exponent to be specified with no decimal point * (e.g. "2E-4"). * 27-AUG-2004 (DSB): * Completed initial attempt at a FITS-CLASS encoding. * 9-SEP-2004 (DSB): * Fixed usage of uninitialised values within ReadCrval. * 13-SEP-2004 (DSB): * Check the "text" pointer can be used safely before using it in * DSSToStore. * 27-SEP-2004 (DSB): * In SpecTrans, before creating new PCi_j values, check that no * PCi_j values have been created via an earlier translation. * 28-SEP-2004 (DSB): * In AIPSPPFromStore only get projection parameters values if there * are some celestialaxes. Also allow CROTA to describe rotation of * non-celestial axes (same for AIPSFromSTore). * 4-OCT-2004 (DSB): * Correct rounding of CRPIX in AddVersion to avoid integer overflow. * 11-NOV-2004 (DSB): * - WcsFcRead: Avoid issuing warnings about bad keywords which * have already been translated into equivalent good forms. * - SpecTrans: If both PROJP and PV keywords are present, use PV * in favour of PROJP only if the PV values look correct. * 17-NOV-2004 (DSB): * - Make astSetFits public. * 16-MAR-2005 (DSB): * - Primary OBSGEO-X/Y/Z, MJD-AVG and MJDOBS keywords are associated * with all axis descriptions and should not have a trailing single * character indicating an alternate axis set. * 9-AUG-2005 (DSB): * In WcsMapFrm, check reffrm is used before annulling it. * 8-SEP-2005 (DSB): * - Change "if( a < b < c )" constructs to "if( a < b && b < c )" * - DSBSetup: correct test on FrameSet pointer state * - Ensure CLASS keywords written to a FitsChan do not come before * the final fixed position keyword. * 9-SEP-2005 (DSB): * - Added "AZ--" and "EL--" as allowed axis types in FITS-WCS * ctype values. * 12-SEP-2005 (DSB): * - Cast difference between two pointers to (int) * - CLASSFromStore:Check source velocity is defined before * storing it in the output header. * 13-SEP-2005 (DSB): * - Corrected B1940 to B1950 in AddEncodingFrame. This bug * prevented some FrameSets being written out using FITS-CLASS. * - Rationalise the use of the "mapping" pointer in AddVersion. * - WcsCelestial: Modified so that the FITS reference point is * stored as the SkyFrame SkyRef attribute value. * 7-OCT-2005 (DSB): * Make astGetFits public. * 30-NOV-2005 (DSB): * Add support for undefined FITS keyword values. * 5-DEC-2005 (DSB): * - Include an IMAGFREQ keyword in the output when writing a * DSBSpecFrame out using FITS-WCS encoding. * - Correct test for constant values in FitOK. * 7-DEC-2005 (DSB): * Free memory allocated by calls to astReadString. * 30-JAN-2006 (DSB): * Modify astSplit so that it does no read the supplied card beyond * column 80. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 28-FEB-2006 (DSB): * Correct documentation typo ("NCards" -> "Ncard"). * 5-APR-2006 (DSB): * Modify SpecTrans to convert CTYPE="LAMBDA" to CTYPE="WAVE". * 26-MAY-2006 (DSB): * Guard against NULL comment pointer when converting RESTFREQ to * RESTFRQ in SpecTrans. * 29-JUN-2006 (DSB): * - Added astRetainFits. * - Consume VELOSYS FITS-WCS keywords when reading an object. * - Write out VELOSYS FITS-WCS keywords when writing an object. * 7-AUG-2006 (DSB): * Remove trailing spaces from the string returned by astGetFitsS * if the original string contains 8 or fewer characters. * 16-AUG-2006 (DSB): * Document non-destructive nature of unsuccessful astRead calls. * 17-AUG-2006 (DSB): * Fix bugs so that the value of the Clean attribute is honoured * even if an error has occurred. * 4-SEP-2006 (DSB): * Modify GetClean so that it ignores the inherited status. * 20-SEP-2006 (DSB): * Fix memory leak in WcsSpectral. * 6-OCT-2006 (DSB): * Modify IsSpectral and IsAIPSSpectral to allow for CTYPE values that * are shorter than eight characters. * 13-OCT-2006 (DSB): * - Ensure SpecFrames and SkyFrames created from a foreign FITS header * are consistent in their choice of Epoch. * - Convert MJD-OBS and MJD-AVG values from TIMESYS timescale to * TDB before using as the Epoch value in an AstFrame. Use UTC if * TIMESYS is absent. * - Convert Epoch values from TDB to UTC before storing as the * value of an MJD-OBS or MJD-AVG keyword (no TIMESYS keyword is * written). * 23-OCT-2006 (DSB): * Prefer MJD-AVG over MJD-OBS. * 30-OCT-2006 (DSB): * In FitOK: Changed lower limit on acceptbale correlation from * 0.999999 to 0.99999. * 1-NOV-2006 (DSB): * - When reading a foreign header that contains a DUT1 keyword, * use it to set the Dut1 attribute in the SkyFrame. Note, JACH * store DUT1 in units of days. This may clash with the FITS-WCS * standard (when its produced). Also note that DUT1 is not written * out as yet when writing a FrameSet to a foreign FITS header. * - Correct bug that prevented ZSOURCE keyword being added to the * output header if the source velocity was negative. * 9-NOV-2006 (DSB): * Add STATUS argument to docs for F77 AST_SETx. * 20-DEC-2006 (DSB): * Correct FK5 to ICRS in error message issued if no RADESYS or * EQUINOX is found. * 16-JAN-2007 (DSB): * Cast ignored function return values to (void) to avoid compiler * warnings. * 31-JAN-2007 (DSB): * Change SpecTrans to ignore blank unit strings (previously * converted them to "Hz"). * 16-APR-2007 (DSB): * In SplitMat, increase the allowed level of rounding erros from * 1.0E-10 to 1.0E-7 (to avoid spurious low CDi_j values being * created that should be zero). * 30-APR-2007 (DSB): * - Change DSBSetup so that the central DSBSpecFrame frequency is * CRVAL and the IF is the difference between CRVAL and LO. * - Change tolerance in FitOK from 0.99999 to 0.995 to handle data from Nicolas * Peretto. * 1-MAY-2007 (DSB): * - In astSplit, if a keyword value looks like an int but is too long to * fit in an int, then treat it as a float instead. * 18-MAY-2007 (DSB): * In CnvType, use input type rather than output type when checking * for a COMMENT card. Also, return a null data value buffer for a * COMMENT card. * 4-JUN-2007 (DSB): * In CLASSFromStore, create a DELTAV header even if it is equal to * the spectral CDELT value. Also, convert spatial reference point * to (az,el) and write out as headers AZIMUTH and ELEVATIO. * 9-JUL-2007 (DSB): * Fixed bug in DSBSetUp - previously, this function assumed that * the supplied DSBSpecFrame represented frequency, and so gave * incorrect values for IF and DSBCentre if the header described * velocity. * 9-AUG-2007 (DSB): * Changed GetEncoding so that critcal keywords are ignored if * there are no CTYPE, CRPIX or CRVAL keywords in the header. * 10-AUG-2007 (DSB): * - Changed GetEncoding so that FITS_PC is not returned if there are * any CDi_j or PCi_j keywords in the header. * - Added astPurgeWCS method. * 13-AUG-2007 (DSB): * - Include the DSS keywords AMDX%d and AMDY%d in FindWCS. * 16-AUG-2007 (DSB): * - Force all FITS-CLASS headers to contain frequency axes * (velocity axes seem not to be recognised properly by CLASS). * - Change the CLASS "VELO-LSR" header to be the velocity at the * reference channel, not the source velocity. * 22-AUG-2007 (DSB): * - Remove debugging printf statements. * 20-SEP-2007 (DSB): * Changed FitOK to check that the RMS residual is not more than * a fixed small fraction of the pixel size. * 4-DEC-2007 (DSB): * Changed CreateKeyword so that it uses a KeyMap to search for * existing keywords. This is much faster than checking every * FitsCard in the FitsChan explicitly. * 18-DEC-2007 (DSB): * Add keyword VLSR to the CLASS encoding. It holds the same value * as VELO-LSR, but different versions of class use different names. * Also write out the DELTAV keyword in the LSR rest frame rather * than the source rest frame. * 31-JAN-2008 (DSB): * Correct calculation of redshift from radio velocity in ClassTrans. * 25-FEB-2008 (DSB): * Ensure a SkyFrame represents absolute (rather than offset) * coords before writing it out in any non-native encoding. * 28-FEB-2008 (DSB): * Test for existing of SkyRefIs attribute before accessing it. * 2-APR-2008 (DSB): * In CLASSFromStore, adjust the spatial CRVAL and CRPIX values to be * the centre of the first pixel if the spatial axes are degenerate. * 17-APR-2008 (DSB): * Ignore latitude axis PV terms supplied in a TAN header * (previously, such PV terms were used as polynomial correction * terms in a TPN projection). * 30-APR-2008 (DSB): * SetValue changed so that new keywords are inserted before the * current card. * 1-MAY-2008 (DSB): * Added UndefRead warning. * 7-MAY-2008 (DSB): * Correct conversion of CDi_j to PCi_j/CDELT in SpecTrans. * 8-MAY-2008 (DSB): * When writing out a FITS-WCS header, allow linear grid->WCS * mapping to be represented by a CAR projection. * 9-MAY-2008 (DSB): * Make class variables IgnoreUsed and MarkNew static. * 30-JUN-2008 (DSB): * Improve efficiency of FindWcs. * 2-JUL-2008 (DSB): * FitsSof now returns non-zero if the FitsChan is empty. * 16-JUL-2008 (DSB): * Plug memory leak caused by failure to free the Warnings * attribute string when a FitsChan is deleted. * 24-JUL-2008 (TIMJ): * Fix buffer overrun in astGetFits when writing the keyword * to the buffer (occurred if the input string was 80 characters). * 1-OCT-2008 (DSB): * When reading a FITS-WCS header, spurious PVi_j keywords no * longer generate an error. Instead they generate warnings via the * new "BadPV" warning type. * 21-NOV-2008 (DSB): * Do not remove keywords from read headers if they may be of * relevance to things other than WCS (e.g. MJD-OBS, OBSGEO, etc). * 2-DEC-2008 (DSB): * - astGetFits now reports an error if the keyword value is undefined. * - Add new functions astTestFits and astSetFitsU. * - Remove use of AST__UNDEF constants. * - Remove "undefread" warning. * 16-JAN-2009 (DSB): * Use astAddWarning to store each warning in the parent Channel * structure. * 4-MAR-2009 (DSB): * DATE-OBS and MJD-OBS cannot have an axis description character. * 13-MAR-2009 (DSB): * The VELOSYS value read from the header is never used, so do not * report an error if VELOSYS has an undefined value. * 11-JUN-2009 (DSB): * Delay reading cards from the source until they are actually * needed. Previously, the source function was called in the * FitsChan initialiser, but this means it is not possible for * application code to call astPutChannelData before the source * function is called. The ReadFromSource function is now called * at the start of each (nearly) public or protected function to * ensure the source function has been called (the source function * pointer in the FitsChan is then nullified to ensure it is not * called again). * 18-JUN-2009 (DSB): * Include the effect of observer height (in the ObsAlt attribute) * when creating OBSGEO-X/Y/Z headers, and store a value for * ObsAlt when reading a set of OBSGEO-X/Y/Z headers. * 2-JUL-2009 (DSB): * Check FitsChan is not empty at start of FindWcs. * 7-JUL-2009 (DSB): * Add new function astSetFitsCM. * 30-JUL-2009 (DSB): * Fix axis numbering in SkyPole. * 12-FEB-2010 (DSB): * Use "" to represent AST__BAD externally. * 25-JUN-2010 (DSB): * Fix problem rounding lots of 9's in RoundFString. The problem * only affected negative values, and could lead to an extra zero * being included in the integer part. * 28-JUN-2010 (DSB): * Another problem in RoundFString! If the value has a series of * 9's followed by a series of zeros, with no decimal point (e.g. * "260579999000"), then the trailing zeros were being lost. * 16-JUL-2010 (DSB): * In SpecTrans, avoid over-writing the spatial projection code * with the spectral projection code. * 20-JUL-2010 (DSB): * Correct interpretation of NCP projection code. * 14-OCT-2010 (DSB): * - Correct loading of FitsChans that contain UNDEF keywords. * - Correct translation of spectral units with non-standard * capitalisation in SpecTrans. * 10-JAN-2011 (DSB): * Fix memory leak in MakeIntWorld. * 13-JAN-2011 (DSB): * Rename astEmpty ast astEmptyFits and make public. * 20-JAN-2011 (DSB): * - Extensive changes to support -TAB algorithm * - Recovery from a major unrequested reformatting of whitespace by * my editor! * 7-FEB-2011 (DSB): * Put a space between keyword value and slash that starts a comment * when formatting a FITS header card. * 11-FEB-2011 (DSB): * Change meaning of TabOK attribute. It is no longer a simple * boolean indicating if the -TAB algorithm is supported. Instead * it gives the value to be used for the EXTVER header - i.e. the * version number to store with any binary table created as a * result of calling astWrite. If TabOK is zero or begative, then * the -TAB algorithm is not supported. This is so that there is * some way of having multiple binary table extensions with the same * name (but different EXTVER values). * 14-FEB-2011 (DSB): * - Spectral reference point CRVAL records the obs. centre. So for -TAB * (when CRVAL is set to zero) we need to record the obs centre some * other way (use the AST-specific AXREF keywords, as for spatial axes). * - Whether to scale spatial axes from degs to rads depends on * whether the spatial axes are descirbed by -TAB or not. * - Relax the linearity requirement in IsMapLinear by a factor of * 10 to prevent a change in rest frame resulting in a non-linear * mapping. * 17-FEB-2011 (DSB): * Fix bug in axis linearity check (IsMapLinear). * 22-FEB-2011 (DSB): * The translations of AIPS non-standard CTYPE values were always * stored as primary axis description keywords, even if the original * non-standard CTYPE values were read from an alternative axis * descriptions. * 5-APR-2011 (DSB): * In SpecTrans, correct the MSX CAR projection translation. The * first pixel starts at GRID=0.5, not GRID=0.0. So the CRPIX value * needs to be reduced by 0.5 prior to normalisation, and then * increased by 0.5 after normalisation. * 23-MAY-2011 (DSB): * Add support for TNX projections that use Chebyshev polynomials. * 24-MAY-2011 (DSB): * - Add support for ZPX projections that include IRAF polynomial * corrections. * - Add PolyTan attribute. * - Fix interpretation of -SIP headers that have no inverse. * 1-JUN-2011 (DSB): * In astInitFitsChanVtab, only create the two TimeFrames if they * have not already been created (fixes scuba2 trac ticket #666). * 9-JUN-2011 (DSB): * In WCSFcRead, ignore trailing spaces when reading string values * for WCS keywords. * 23-JUN-2011 (DSB): * - Override the parent astSetSourceFile method so that it reads * headers from the SourceFile and appends them to the end of the * FitsChan. * - On deletion, write out the FitsChan contents to the file * specified by the SinkFile attribute. If no file is specified, * use the sink function specified when the FitsChan was created. * 30-AUG-2011 (DSB): * - Added astWriteFits and astReadFits. * - Move the deletion of tables and warnings from Delete to * EmptyFits. * 21-SEP-2011 (DSB): * - In RoundFString, remember to update the pointer to the exponent. * This bug caused parts of the exponent to dissappear when * formatting a value that included some trailing zeros and a * series of adjacent 9's. * - Added Nkey attribute. * 22-SEP-2011 (DSB): * - Added CardType attribute * - Allow GetFits to be used to get/set the value of the current * card. * 4-OCT-2011 (DSB): * When reading a FITS-WCFS header, if the projection is TPV (as produced * by SCAMP), change to TPN (the internal AST code for a distorted * TAN projection). * 22-NOV-2011 (DSB): * Allow the "-SIP" code to be used with non-celestial axes. * 1-FEB-2012 (DSB): * Write out MJD-OBS in the timescale specified by any TIMESYS * keyword in the FitsChan, and ensure the TIMESYS value is included * in the output header. * 23-FEB-2012 (DSB): * Use iauGd2gc in place of palGeoc where is saves some calculations. * 24-FEB-2012 (DSB): * Move invocation of AddEncodingFrame from Write to end of * MakeFitsFrameSet. This is so that AddEncodingFrame can take * advantage of any standardisations (such as adding celestial axes) * performed by MakeFItsFrameSet. Without this, a FRameSet contain * a 1D SpecFrame (no celestial axes) would fail to be exported using * FITS-CLASS encoding. * 29-FEB-2012 (DSB): * Fix bug in CLASSFromStore that caused spatial axes added by * MakeFitsFrameSet to be ignored. * 2-MAR-2012 (DSB): * - In CLASSFromSTore, ensure NAXIS2/3 values are stored in teh FitsChan, * and cater for FrameSets that have only a apectral axis and no celestial * axes (this prevented the VELO_LSR keyword being created).. * 7-MAR-2012 (DSB): * Use iauGc2gd in place of Geod. * 22-JUN-2012 (DSB): * - Check for distorted TAN projections that have zero for all PVi_m * coefficients. Issue a warning and ignore the distortion in such * cases. * - Remove all set but unused variables. * - Convert SAO distorted TAN projections (which use COi_j keywords * for polynomial coeffs) to TPN. * 26-JUN-2012 (DSB): * Correct call to astKeyFields in SAOTrans (thanks to Bill Joye * for pointing out this error). * 8-AUG-2012 (DSB): * Correct assignment to lonpole within CLASSFromStore. * 10-AUG-2012 (DSB): * Default DSS keywords CNPIX1 and CNPIX2 to zero if they are * absent, rather than reporting an error. * 7-DEC-2012 (DSB): * - When writing out a FrameSet that uses an SkyFrame to describe a * generalised spherical coordinate system ("system=unknown"), ensure * that the generated FITS CTYPE values use FITS-compliant codes * for the axis type ( "xxLN/xxLT" or "xLON/xLAT" ). * - Add support for reading and writing offset SkyFrames to * FITS-WCS. * 30-JAN-2013 (DSB): * When reading a FITS-CLASS header, use "VLSR" keyword if * "VELO-..." is not available. * 15-APR-2013 (DSB): * Correct initialisation of missing coefficients When reading a * SAO plate solution header. * 16-APR-2013 (DSB): * When determining default Encoding value, use "VLSR" keyword if * "VELO-..." is not available. * 30-MAY-2013 (DSB): * Prevent seg fault caused by overrunning the coeffs array in * WATCoeffs in cases where the TNX/ZPX projection is found to be * of a form that cannot be implemented as a TPN projection. * 11-JUN-2013 (DSB): * Fix support for reading GLS projections, and add support for * rotated GLS projections. * 28-AUG-2013 (DSB): * In WcsCelestial, if celestial axes are found with no projection * code in CTYPE, assume an old-fashioned CAR projection (i.e. no * rotation from native to WCS coords). Before this change, * CTYPE = "RA" | "DEC" axes got treated as radians, not degrees. * 16-SEP-2013 (DSB): * When exporting alternate offset SkyFrames to FITS-WCS headers, * correctly test the alternate Frame in the supplied FrameSet, rather * than the current Frame. * 24-SEP-2013 (DSB): * Fix bug in choosing default value for PolyTan attribute. * 19-OCT-2013 (DSB): * - In SIPMapping, always ignore any inverse polynomial supplied in * a SIP header as they seem often to be inaccurate. A new inverse is * created to replace it. * - In SIPMapping, only use a fit to the inverted SIP transformation * if an accuracy of 0.01 pixel can be achieved over an area three * times the dimensions of the image. Otherwise use an iterative * inverse for each point. People were seeing bad round-trip errors * when transforming points outside the image because the fit was * being used when it was not very accurate. * 12-NOV-2013 (DSB): * Added CardName and CardComm attributes. * 13-NOV-2013 (DSB): * Use a zero-length string for the CardComm attribute if the card * has no comment. * 15-NOV-2013 (DSB): * - Added method astShowFits. * - Ensure PurgeWcs removes WCS cards even if an error occurs when * reading FrameSets from the FitsChan. * - Change IsMapTab1D to improve chances of a -TAB mapping being found. * 6-JAN-2014 (DSB): * - Allow default options for newly created FitsChans to be * specified by the FITSCHAN_OPTIONS environment variable. * - Ensure the used CarLin value is not changed by a trailing frequency axis. * 9-JUL-2014 (DSB): * Added attribute FitsAxisOrder, which allows an order to be * specified for WCS axis within FITS headers generated using astWrite. * 9-SEP-2014 (DSB): * Modify Split so that any non-printing characters such as * newlines at the end of the string are ignored. * 30-SEP-2014 (DSB): * Modify CnvType to indicate that comment cards cannot be * converted to any other data type. For instance, this causes * a warning to be issued if an equals sign is misplaced in a * WCS-related card (causing it to be treated as a comment card). * 24-MAR-2015 (DSB): * Modify SpecTrans to avoid modifying the CRPIC value for CAR * projections when they do not need to be modified. The princiuple * is that the bulk of the array should be witin the native longitude * range [-180,+180]. Prompted by bug report from Bill Joye "yet * another CAR issue" on 24-MAR-2015 (file CHIPASS_Equ.head in * ast_tester). * 27-APR-2015 (DSB): * Modify MakeFitsFrameSet so that isolated SkyAxes (e.g. * individual axes that have been oicked from a SkyFrame) are * re-mapped into degrees before being used. * 20-APR-2015 (DSB): * In MakeIntWorld, relax tolerance for checking that each FITS-WCS IWC * axis is linear, from 0.01 of a pixel to 0.1 of a pixel. * 6-JUL-2015 (DSB): * When checking a sub-string, ensure the whole string is at least as * long as the offset to the start of the sub-string. Without this, you * can get erroneous sub-string matches by chance, depending on what * characters happen to be present in memory after the end of the string. * 11-AUG-2015 (DSB): * - Fix bug in CheckFitsName that prevented an error from being reported * if the FITS keyword name contained any illegal printable characters. * - Add new Warning "badkeyname", and issue such a warning instead * of an error if illegal characters are found in a keyword name. * 31-AUG-2015 (DSB): * In FitLine, use the whole axis rather than 0.1 of the axis (if "dim" * is supplied). This is because non-linearity can become greater at * further distances along the axis. In practice, it meant that SIP * distortion were being treated as linear because the test did not * explore a large enough region of pixel space. * 12-OCT-2015 (DSB): * Only add sky axes to a SpecFrame if the WCS Frame contains no * other axes other than the SpecFrame (MakeFitsFrameSet). * 17-OCT-2015 (DSB): * - Add new Warning "badkeyvalue", and issue such a warning instead * of an error if the Split function cannot determine the keyword value. * - Move the check for PLTRAH (i.e. DSS encoding) higher up in GetEncoding. * This is because some DSS file slaos have CD and/or PC keywords. * 5-NOV-2015 (DSB): * Fix bug in MakeFitsFrameSet that could cause an inappropriate * RefRA and RefDec values to be used when writing out a SpecFrame * using FITS-WCS. This bug was caused by the assumption that * changing the current Frame of a FRameSet also changes the Frame * that was added into the FRameSet. This used to be the case as * astAddFrame took a clone of the supplied Frame pointer, but it * now takes a deep copy, so the original Frame and the FrameSet's * current Frame are now independent of each other. * 28-JUN-2016 ((DSB): * IsAipsSpectral: Trailing spaces in CTYPE values are insignificant. *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 FitsChan /* A macro which tests a character to see if it can be used within a FITS keyword. We include lower case letters here, but they are considered as equivalent to upper case letter. */ #define isFits(a) ( islower(a) || isupper(a) || isdigit(a) || (a)=='-' || (a)=='_' ) /* A amacro to test if a Frame is a SkyFrame, and is used to describe the sky (skyframes could be used for other purposes - eg a POLANAL Frame). */ #define IsASkyFrame(frame) (astIsASkyFrame(frame)&&!strcmp("SKY",astGetDomain(frame))) /* Macro which takes a pointer to a FitsCard and returns non-zero if the card has been used and so should be ignored. */ #define CARDUSED(card) ( \ ( ignore_used == 2 && \ ( (FitsCard *) (card) )->flags & PROVISIONALLY_USED ) || \ ( ignore_used >= 1 && \ ( (FitsCard *) (card) )->flags & USED ) ) /* Set of characters used to encode a "sequence number" at the end of FITS keywords in an attempt to make them unique.. */ #define SEQ_CHARS "_ABCDEFGHIJKLMNOPQRSTUVWXYZ" /* A general tolerance for equality between floating point values. */ #define TOL1 10.0*DBL_EPSILON /* A tolerance for equality between angular values in radians. */ #define TOL2 1.0E-10 /* Macro to check for equality of floating point angular values. We cannot compare bad values directory because of the danger of floating point exceptions, so bad values are dealt with explicitly. The smallest significant angle is assumed to be 1E-9 radians (0.0002 arc-seconds).*/ #define EQUALANG(aa,bb) (((aa)==AST__BAD)?(((bb)==AST__BAD)?1:0):(((bb)==AST__BAD)?0:(fabs((aa)-(bb))<=astMAX(1.0E5*(fabs(aa)+fabs(bb))*DBL_EPSILON,1.0E-9)))) /* Macro to compare an angle in radians with zero, allowing some tolerance. */ #define ZEROANG(aa) (fabs(aa)<1.0E-9) /* Constants: */ #define UNKNOWN_ENCODING -1 #define NATIVE_ENCODING 0 #define FITSPC_ENCODING 1 #define DSS_ENCODING 2 #define FITSWCS_ENCODING 3 #define FITSIRAF_ENCODING 4 #define FITSAIPS_ENCODING 5 #define FITSAIPSPP_ENCODING 6 #define FITSCLASS_ENCODING 7 #define MAX_ENCODING 7 #define UNKNOWN_STRING "UNKNOWN" #define NATIVE_STRING "NATIVE" #define FITSPC_STRING "FITS-PC" #define FITSPC_STRING2 "FITS_PC" #define DSS_STRING "DSS" #define FITSWCS_STRING "FITS-WCS" #define FITSWCS_STRING2 "FITS_WCS" #define FITSIRAF_STRING "FITS-IRAF" #define FITSIRAF_STRING2 "FITS_IRAF" #define FITSAIPS_STRING "FITS-AIPS" #define FITSAIPS_STRING2 "FITS_AIPS" #define FITSAIPSPP_STRING "FITS-AIPS++" #define FITSAIPSPP_STRING2 "FITS_AIPS++" #define FITSCLASS_STRING "FITS-CLASS" #define FITSCLASS_STRING2 "FITS_CLASS" #define INDENT_INC 3 #define PREVIOUS 0 #define NEXT 1 #define HEADER_TEXT "Beginning of AST data for " #define FOOTER_TEXT "End of AST data for " #define FITSNAMLEN 8 #define FITSSTCOL 20 #define FITSRLCOL 30 #define FITSIMCOL 50 #define FITSCOMCOL 32 #define NORADEC 0 #define FK4 1 #define FK4NOE 2 #define FK5 3 #define GAPPT 4 #define ICRS 5 #define NOCEL 0 #define RADEC 1 #define ECLIP 2 #define GALAC 3 #define SUPER 4 #define HECLIP 5 #define AZEL 6 #define LONAX -1 #define NONAX 0 #define LATAX 1 #define NDESC 9 #define MXCTYPELEN 81 #define ALLWARNINGS " distortion noequinox noradesys nomjd-obs nolonpole nolatpole tnx zpx badcel noctype badlat badmat badval badctype badpv badkeyname badkeyvalue " #define NPFIT 10 #define SPD 86400.0 #define FL 1.0/298.257 /* Reference spheroid flattening factor */ #define A0 6378140.0 /* Earth equatorial radius (metres) */ /* String used to represent AST__BAD externally. */ #define BAD_STRING "" /* Each card in the fitschan has a set of flags associated with it, stored in different bits of the "flags" item within each FitsCard structure (note, in AST V1.4 these flags were stored in the "del" item... Dump and LoadFitsChan will need to be changed to use a correspondingly changed name for the external representation of this item). The following flags are currently defined: */ /* "USED" - This flag indicates that the the card has been used in the construction of an AST Object returned by astRead. Such cards should usually be treated as if they do not exist, i.e. they should not be used again by subsequent calls to astRead, they should not be recognised by public FitsChan methods which search the FitsChan for specified cards, and they should not be written out when the FitsChan is deleted. This flag was the only flag available in AST V1.4, and was called "Del" (for "deleted"). Used cards are retained in order to give an indication of where abouts within the header new cards should be placed when astWrite is called (i.e. new cards should usually be placed at the same point within the header as the cards which they replace). */ #define USED 1 /* "PROVISIONALLY_USED" - This flag indicates that the the card is being considered as a candidate for inclusion in the construction of an AST Object. If the Object is constructed succesfully, cards flagged as "provisionally used" will be changed to be flagged as "definitely used" (using the USED flag). If the Object fails to be constructed succesfully (if some required cards are missing from the FitsChan for instance), then "provisionally used" cards will be returned to the former state which they had prior to the attempt to construct the object. */ #define PROVISIONALLY_USED 2 /* "NEW" - This flag indicates that the the card has just been added to the FitsChan and may yet proove to be unrequired. For instance if the supplied Object is not of an appropriate flavour to be stored using the requested encoding, all "new" cards which were added before the inappropriateness was discovered will be removed from the FitsChan. Two different levels of "newness" are available. */ #define NEW1 4 #define NEW2 8 /* "PROTECTED" - This flag indicates that the the card should not be removed form the FitsChan when an Object is read using astRead. If this flag is not set, then the card will dehave as if it has been deleted if it was used in the construction of the returned AST Object. */ #define PROTECTED 16 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" #include "cmpframe.h" #include "cmpmap.h" #include "dssmap.h" #include "error.h" #include "fitschan.h" #include "frame.h" #include "frameset.h" #include "grismmap.h" #include "lutmap.h" #include "mathmap.h" #include "matrixmap.h" #include "memory.h" #include "object.h" #include "permmap.h" #include "pointset.h" #include "shiftmap.h" #include "skyframe.h" #include "timeframe.h" #include "keymap.h" #include "pal.h" #include "erfa.h" #include "slamap.h" #include "specframe.h" #include "dsbspecframe.h" #include "specmap.h" #include "sphmap.h" #include "unit.h" #include "unitmap.h" #include "polymap.h" #include "wcsmap.h" #include "winmap.h" #include "zoommap.h" #include "globals.h" #include "fitstable.h" /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* Type Definitions */ /* ================ */ /* This structure contains information describing a single FITS header card in a circular list of such structures. */ typedef struct FitsCard { char name[ FITSNAMLEN + 1 ];/* Keyword name (plus terminating null). */ int type; /* Data type. */ void *data; /* Pointer to the keyword's data value. */ char *comment; /* Pointer to a comment for the keyword. */ int flags; /* Flags for each card */ size_t size; /* Size of data value */ struct FitsCard *next; /* Pointer to next structure in list. */ struct FitsCard *prev; /* Pointer to previous structure in list. */ } FitsCard; /* Structure used to store information derived from the FITS WCS keyword values in a form more convenient to further processing. Conventions for units, etc, for values in a FitsStore follow FITS-WCS (e.g. angular values are stored in degrees, equinox is B or J depending on RADECSYS, etc). */ typedef struct FitsStore { char ****cname; char ****ctype; char ****ctype_com; char ****cunit; char ****radesys; char ****wcsname; char ****specsys; char ****ssyssrc; char ****ps; char ****timesys; double ***pc; double ***cdelt; double ***crpix; double ***crval; double ***equinox; double ***latpole; double ***lonpole; double ***mjdobs; double ***dut1; double ***mjdavg; double ***pv; double ***wcsaxes; double ***obsgeox; double ***obsgeoy; double ***obsgeoz; double ***restfrq; double ***restwav; double ***zsource; double ***velosys; double ***asip; double ***bsip; double ***apsip; double ***bpsip; double ***imagfreq; double ***axref; int naxis; AstKeyMap *tables; double ***skyref; double ***skyrefp; char ****skyrefis; } FitsStore; /* 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 void (* parent_setsourcefile)( AstChannel *, const char *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_getfull)( AstChannel *, int * ); static int (* parent_getskip)( AstChannel *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static int (* parent_write)( AstChannel *, AstObject *, int * ); static AstObject *(* parent_read)( AstChannel *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* Strings to describe each data type. These should be in the order implied by the corresponding macros (eg AST__FLOAT, etc). */ static const char *type_names[9] = {"comment", "integer", "floating point", "string", "complex floating point", "complex integer", "logical", "continuation string", "undef" }; /* Text values used to represent Encoding values externally. */ static const char *xencod[8] = { NATIVE_STRING, FITSPC_STRING, DSS_STRING, FITSWCS_STRING, FITSIRAF_STRING, FITSAIPS_STRING, FITSAIPSPP_STRING, FITSCLASS_STRING }; /* Define two variables to hold TimeFrames which will be used for converting MJD values between time scales. */ static AstTimeFrame *tdbframe = NULL; static AstTimeFrame *timeframe = NULL; /* Max number of characters in a formatted int */ static int int_dig; /* 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->Items_Written = 0; \ globals->Write_Nest = -1; \ globals->Current_Indent = 0; \ globals->Ignore_Used = 1; \ globals->Mark_New = 0; \ globals->CnvType_Text[ 0 ] = 0; \ globals->CnvType_Text0[ 0 ] = 0; \ globals->CnvType_Text1[ 0 ] = 0; \ globals->CreateKeyword_Seq_Nchars = -1; \ globals->FormatKey_Buff[ 0 ] = 0; \ globals->FitsGetCom_Sval[ 0 ] = 0; \ globals->IsSpectral_Ret = NULL; \ globals->Match_Fmt[ 0 ] = 0; \ globals->Match_Template = NULL; \ globals->Match_PA = 0; \ globals->Match_PB = 0; \ globals->Match_NA = 0; \ globals->Match_NB = 0; \ globals->Match_Nentry = 0; \ globals->WcsCelestial_Type[ 0 ] = 0; \ globals->Ignore_Used = 1; \ globals->Mark_New = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(FitsChan) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(FitsChan,Class_Init) #define class_vtab astGLOBAL(FitsChan,Class_Vtab) #define getattrib_buff astGLOBAL(FitsChan,GetAttrib_Buff) #define items_written astGLOBAL(FitsChan,Items_Written) #define write_nest astGLOBAL(FitsChan,Write_Nest) #define current_indent astGLOBAL(FitsChan,Current_Indent) #define ignore_used astGLOBAL(FitsChan,Ignore_Used) #define mark_new astGLOBAL(FitsChan,Mark_New) #define cnvtype_text astGLOBAL(FitsChan,CnvType_Text) #define cnvtype_text0 astGLOBAL(FitsChan,CnvType_Text0) #define cnvtype_text1 astGLOBAL(FitsChan,CnvType_Text1) #define createkeyword_seq_nchars astGLOBAL(FitsChan,CreateKeyword_Seq_Nchars) #define formatkey_buff astGLOBAL(FitsChan,FormatKey_Buff) #define fitsgetcom_sval astGLOBAL(FitsChan,FitsGetCom_Sval) #define isspectral_ret astGLOBAL(FitsChan,IsSpectral_Ret) #define match_fmt astGLOBAL(FitsChan,Match_Fmt) #define match_template astGLOBAL(FitsChan,Match_Template) #define match_pa astGLOBAL(FitsChan,Match_PA) #define match_pb astGLOBAL(FitsChan,Match_PB) #define match_na astGLOBAL(FitsChan,Match_NA) #define match_nb astGLOBAL(FitsChan,Match_NB) #define match_nentry astGLOBAL(FitsChan,Match_Nentry) #define wcscelestial_type astGLOBAL(FitsChan,WcsCelestial_Type) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); static pthread_mutex_t mutex3 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX3 pthread_mutex_lock( &mutex3 ); #define UNLOCK_MUTEX3 pthread_mutex_unlock( &mutex3 ); static pthread_mutex_t mutex4 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX4 pthread_mutex_lock( &mutex4 ); #define UNLOCK_MUTEX4 pthread_mutex_unlock( &mutex4 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffer returned by GetAttrib. */ static char getattrib_buff[ AST__FITSCHAN_GETATTRIB_BUFF_LEN + 1 ]; /* Buffer for returned text string in CnvType */ static char cnvtype_text[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Buffer for real value in CnvType */ static char cnvtype_text0[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Buffer for imaginary value in CnvType */ static char cnvtype_text1[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Number of output items written since the last "Begin" or "IsA" output item, and level of Object nesting during recursive invocation of the astWrite method. */ static int items_written = 0; static int write_nest = -1; /* Indentation level for indented comments when writing Objects to a FitsChan. */ static int current_indent = 0; /* Ignore_Used: If 2, then cards which have been marked as either "definitely used" or "provisionally used" (see the USED flag above) will be ignored when searching the FitsChan, etc (i.e. they will be treated as if they have been removed from the FitsChan). If 1, then cards which have been "definitely used" will be skipped over. If zero then no cards will be skipped over. */ static int ignore_used = 1; /* Mark_New: If non-zero, then all cards added to the FitsChan will be marked with both the NEW1 and NEW2 flags (see above). If zero then new cards will not be marked with either NEW1 or NEW2. */ static int mark_new = 0; /* Number of characters used for encoding */ static int createkeyword_seq_nchars = -1; /* Buffer for value returned by FormatKey */ static char formatkey_buff[ 10 ]; /* Buffer for value returned by FitsGetCom */ static char fitsgetcom_sval[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Pointer returned by IsSpectral */ static const char *isspectral_ret = NULL; /* Format specifier for reading an integer field in Match */ static char match_fmt[ 10 ]; /* Pointer to start of template in Match */ static const char *match_template = NULL; /* Pointer to first returned field value in Match */ static int *match_pa = 0; /* Pointer to last returned field value in Match */ static int *match_pb = 0; /* No. of characters read from the test string in Match */ static int match_na = 0; /* No. of characters read from the template string in Match */ static int match_nb = 0; /* Number of recursive entries into Match */ static int match_nentry = 0; /* Buffer for celestial system in WcsCelestial */ static char wcscelestial_type[ 4 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstFitsChanVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #define LOCK_MUTEX3 #define UNLOCK_MUTEX3 #define LOCK_MUTEX4 #define UNLOCK_MUTEX4 #endif /* External 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. */ AstFitsChan *astFitsChanForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); AstFitsChan *astFitsChanId_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static int GetObjSize( AstObject *, int * ); static void ClearCard( AstFitsChan *, int * ); static int GetCard( AstFitsChan *, int * ); static int TestCard( AstFitsChan *, int * ); static void SetCard( AstFitsChan *, int, int * ); static void ClearEncoding( AstFitsChan *, int * ); static int GetEncoding( AstFitsChan *, int * ); static int TestEncoding( AstFitsChan *, int * ); static void SetEncoding( AstFitsChan *, int, int * ); static void ClearCDMatrix( AstFitsChan *, int * ); static int GetCDMatrix( AstFitsChan *, int * ); static int TestCDMatrix( AstFitsChan *, int * ); static void SetCDMatrix( AstFitsChan *, int, int * ); static void ClearFitsDigits( AstFitsChan *, int * ); static int GetFitsDigits( AstFitsChan *, int * ); static int TestFitsDigits( AstFitsChan *, int * ); static void SetFitsDigits( AstFitsChan *, int, int * ); static void ClearFitsAxisOrder( AstFitsChan *, int * ); static const char *GetFitsAxisOrder( AstFitsChan *, int * ); static int TestFitsAxisOrder( AstFitsChan *, int * ); static void SetFitsAxisOrder( AstFitsChan *, const char *, int * ); static void ClearDefB1950( AstFitsChan *, int * ); static int GetDefB1950( AstFitsChan *, int * ); static int TestDefB1950( AstFitsChan *, int * ); static void SetDefB1950( AstFitsChan *, int, int * ); static void ClearTabOK( AstFitsChan *, int * ); static int GetTabOK( AstFitsChan *, int * ); static int TestTabOK( AstFitsChan *, int * ); static void SetTabOK( AstFitsChan *, int, int * ); static void ClearCarLin( AstFitsChan *, int * ); static int GetCarLin( AstFitsChan *, int * ); static int TestCarLin( AstFitsChan *, int * ); static void SetCarLin( AstFitsChan *, int, int * ); static void ClearPolyTan( AstFitsChan *, int * ); static int GetPolyTan( AstFitsChan *, int * ); static int TestPolyTan( AstFitsChan *, int * ); static void SetPolyTan( AstFitsChan *, int, int * ); static void ClearIwc( AstFitsChan *, int * ); static int GetIwc( AstFitsChan *, int * ); static int TestIwc( AstFitsChan *, int * ); static void SetIwc( AstFitsChan *, int, int * ); static void ClearClean( AstFitsChan *, int * ); static int GetClean( AstFitsChan *, int * ); static int TestClean( AstFitsChan *, int * ); static void SetClean( AstFitsChan *, int, int * ); static void ClearWarnings( AstFitsChan *, int * ); static const char *GetWarnings( AstFitsChan *, int * ); static int TestWarnings( AstFitsChan *, int * ); static void SetWarnings( AstFitsChan *, const char *, int * ); static AstFitsChan *SpecTrans( AstFitsChan *, int, const char *, const char *, int * ); static AstFitsTable *GetNamedTable( AstFitsChan *, const char *, int, int, int, const char *, int * ); static AstFrameSet *MakeFitsFrameSet( AstFitsChan *, AstFrameSet *, int, int, int, const char *, const char *, int * ); static AstGrismMap *ExtractGrismMap( AstMapping *, int, AstMapping **, int * ); static AstKeyMap *GetTables( AstFitsChan *, int * ); static AstMapping *AddUnitMaps( AstMapping *, int, int, int * ); static AstMapping *CelestialAxes( AstFitsChan *this, AstFrameSet *, double *, int *, char, FitsStore *, int *, int, const char *, const char *, int * ); static AstMapping *GrismSpecWcs( char *, FitsStore *, int, char, AstSpecFrame *, const char *, const char *, int * ); static AstMapping *IsMapTab1D( AstMapping *, double, const char *, AstFrame *, double *, int, int, AstFitsTable **, int *, int *, int *, int * ); static AstMapping *IsMapTab2D( AstMapping *, double, const char *, AstFrame *, double *, int, int, int, int, AstFitsTable **, int *, int *, int *, int *, int *, int *, int *, int *, int * ); static AstMapping *LinearWcs( FitsStore *, int, char, const char *, const char *, int * ); static AstMapping *LogAxis( AstMapping *, int, int, double *, double *, double, int * ); static AstMapping *LogWcs( FitsStore *, int, char, const char *, const char *, int * ); static AstMapping *MakeColumnMap( AstFitsTable *, const char *, int, int, const char *, const char *, int * ); static AstMapping *NonLinSpecWcs( AstFitsChan *, char *, FitsStore *, int, char, AstSpecFrame *, const char *, const char *, int * ); static AstMapping *OtherAxes( AstFitsChan *, AstFrameSet *, double *, int *, char, FitsStore *, double *, int *, const char *, const char *, int * ); static AstMapping *SIPMapping( double *, FitsStore *, char, int, const char *, const char *, int * ); static AstMapping *SpectralAxes( AstFitsChan *, AstFrameSet *, double *, int *, char, FitsStore *, double *, int *, const char *, const char *, int * ); static AstMapping *TabMapping( AstFitsChan *, FitsStore *, char, int **, const char *, const char *, int *); static AstMapping *WcsCelestial( AstFitsChan *, FitsStore *, char, AstFrame **, AstFrame *, double *, double *, AstSkyFrame **, AstMapping **, int *, const char *, const char *, int * ); static AstMapping *WcsIntWorld( AstFitsChan *, FitsStore *, char, int, const char *, const char *, int * ); static AstMapping *WcsMapFrm( AstFitsChan *, FitsStore *, char, AstFrame **, const char *, const char *, int * ); static AstMapping *WcsNative( AstFitsChan *, FitsStore *, char, AstWcsMap *, int, int, const char *, const char *, int * ); static AstMapping *WcsOthers( AstFitsChan *, FitsStore *, char, AstFrame **, AstFrame *, const char *, const char *, int * ); static AstMapping *WcsSpectral( AstFitsChan *, FitsStore *, char, AstFrame **, AstFrame *, double, double, AstSkyFrame *, const char *, const char *, int * ); static AstMapping *ZPXMapping( AstFitsChan *, FitsStore *, char, int, int[2], const char *, const char *, int * ); static AstMatrixMap *WcsCDeltMatrix( FitsStore *, char, int, const char *, const char *, int * ); static AstMatrixMap *WcsPCMatrix( FitsStore *, char, int, const char *, const char *, int * ); static AstObject *FsetFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static AstObject *Read( AstChannel *, int * ); static AstSkyFrame *WcsSkyFrame( AstFitsChan *, FitsStore *, char, int, char *, int, int, const char *, const char *, int * ); static AstTimeScaleType TimeSysToAst( AstFitsChan *, const char *, const char *, const char *, int * ); static AstWinMap *WcsShift( FitsStore *, char, int, const char *, const char *, int * ); static FitsCard *GetLink( FitsCard *, int, const char *, const char *, int * ); static FitsStore *FitsToStore( AstFitsChan *, int, const char *, const char *, int * ); static FitsStore *FreeStore( FitsStore *, int * ); static FitsStore *FsetToStore( AstFitsChan *, AstFrameSet *, int, double *, int, const char *, const char *, int * ); static char *CardComm( AstFitsChan *, int * ); static char *CardName( AstFitsChan *, int * ); static char *ConcatWAT( AstFitsChan *, int, const char *, const char *, int * ); static char *FormatKey( const char *, int, int, char, int * ); static char *GetItemC( char *****, int, int, char, char *, const char *method, const char *class, int * ); static char *SourceWrap( const char *(*)( void ), int * ); static char *UnPreQuote( const char *, int * ); static char GetMaxS( double ****item, int * ); static const char *GetAllWarnings( AstFitsChan *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetCardComm( AstFitsChan *, int * ); static const char *GetCardName( AstFitsChan *, int * ); static const char *GetFitsSor( const char *, int * ); static const char *IsSpectral( const char *, char[5], char[5], int * ); static double **OrthVectorSet( int, int, double **, int * ); static double *Cheb2Poly( double *, int, int, double, double, double, double, int * ); static double *FitLine( AstMapping *, double *, double *, double *, double, double *, int * ); static double *OrthVector( int, int, double **, int * ); static double *ReadCrval( AstFitsChan *, AstFrame *, char, const char *, const char *, int * ); static double ChooseEpoch( AstFitsChan *, FitsStore *, char, const char *, const char *, int * ); static double DateObs( const char *, int * ); static double GetItem( double ****, int, int, char, char *, const char *method, const char *class, int * ); static double NearestPix( AstMapping *, double, int, int * ); static double TDBConv( double, int, int, const char *, const char *, int * ); static int *CardFlags( AstFitsChan *, int * ); static int AIPSFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int AIPSPPFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int AddEncodingFrame( AstFitsChan *, AstFrameSet *, int, const char *, const char *, int * ); static int AddVersion( AstFitsChan *, AstFrameSet *, int, int, FitsStore *, double *, char, int, int, const char *, const char *, int * ); static int CLASSFromStore( AstFitsChan *, FitsStore *, AstFrameSet *, double *, const char *, const char *, int * ); static int CardType( AstFitsChan *, int * ); static int CheckFitsName( AstFitsChan *, const char *, const char *, const char *, int * ); static int ChrLen( const char *, int * ); static int CnvType( int, void *, size_t, int, int, void *, const char *, const char *, const char *, int * ); static int CnvValue( AstFitsChan *, int , int, void *, const char *, int * ); static int ComBlock( AstFitsChan *, int, const char *, const char *, int * ); static int CountFields( const char *, char, const char *, const char *, int * ); static int DSSFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int EncodeFloat( char *, int, int, int, double, int * ); static int EncodeValue( AstFitsChan *, char *, int, int, const char *, int * ); static int FindBasisVectors( AstMapping *, int, int, double *, AstPointSet *, AstPointSet *, int * ); static int FindFits( AstFitsChan *, const char *, char[ AST__FITSCHAN_FITSCARDLEN + 1 ], int, int * ); static int FindKeyCard( AstFitsChan *, const char *, const char *, const char *, int * ); static int FindLonLatSpecAxes( FitsStore *, char, int *, int *, int *, const char *, const char *, int * ); static int FindString( int, const char *[], const char *, const char *, const char *, const char *, int * ); static int FitOK( int, double *, double *, double, int * ); static int FitsAxisOrder( AstFitsChan *this, int nwcs, AstFrame *wcsfrm, int *perm, int *status ); static int FitsEof( AstFitsChan *, int * ); static int FitsFromStore( AstFitsChan *, FitsStore *, int, double *, AstFrameSet *, const char *, const char *, int * ); static int FitsGetCom( AstFitsChan *, const char *, char **, int * ); static int FitsSof( AstFitsChan *, int * ); static int FullForm( const char *, const char *, int, int * ); static int GetCardType( AstFitsChan *, int * ); static int GetFiducialWCS( AstWcsMap *, AstMapping *, int, int, double *, double *, int * ); static int GetFitsCF( AstFitsChan *, const char *, double *, int * ); static int GetFitsCI( AstFitsChan *, const char *, int *, int * ); static int GetFitsCN( AstFitsChan *, const char *, char **, int * ); static int GetFitsF( AstFitsChan *, const char *, double *, int * ); static int GetFitsI( AstFitsChan *, const char *, int *, int * ); static int GetFitsL( AstFitsChan *, const char *, int *, int * ); static int GetFitsS( AstFitsChan *, const char *, char **, int * ); static int GetFull( AstChannel *, int * ); static int GetMaxI( double ****item, char, int * ); static int GetMaxJM( double ****item, char, int * ); static int GetMaxJMC( char *****item, char, int * ); static int GetNcard( AstFitsChan *, int * ); static int GetNkey( AstFitsChan *, int * ); static int GetSkip( AstChannel *, int * ); static int GetUsedPolyTan( AstFitsChan *, AstFitsChan *, int, int, char, const char *, const char *, int * ); static int GetValue( AstFitsChan *, const char *, int, void *, int, int, const char *, const char *, int * ); static int GetValue2( AstFitsChan *, AstFitsChan *, const char *, int, void *, int, const char *, const char *, int * ); static int GoodWarns( const char *, int * ); static int HasAIPSSpecAxis( AstFitsChan *, const char *, const char *, int * ); static int HasCard( AstFitsChan *, const char *, const char *, const char *, int * ); static int IRAFFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int IsAIPSSpectral( const char *, char **, char **, int * ); static int IsMapLinear( AstMapping *, const double [], const double [], int, int * ); static int IsSkyOff( AstFrameSet *, int, int * ); static int KeyFields( AstFitsChan *, const char *, int, int *, int *, int * ); static int LooksLikeClass( AstFitsChan *, const char *, const char *, int * ); static int MakeBasisVectors( AstMapping *, int, int, double *, AstPointSet *, AstPointSet *, int * ); static int MakeIntWorld( AstMapping *, AstFrame *, int *, char, FitsStore *, double *, const char *, const char *, int * ); static int Match( const char *, const char *, int, int *, int *, const char *, const char *, int * ); static int MatchChar( char, char, const char *, const char *, const char *, int * ); static int MatchFront( const char *, const char *, char *, int *, int *, int *, const char *, const char *, const char *, int * ); static int MoveCard( AstFitsChan *, int, const char *, const char *, int * ); static int PCFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int SAOTrans( AstFitsChan *, AstFitsChan *, const char *, const char *, int * ); static int SearchCard( AstFitsChan *, const char *, const char *, const char *, int * ); static int SetFits( AstFitsChan *, const char *, void *, int, const char *, int, int * ); static int Similar( const char *, const char *, int * ); static int SkySys( AstFitsChan *, AstSkyFrame *, int, int, FitsStore *, int, int, char c, int, const char *, const char *, int * ); static int Split( AstFitsChan *, const char *, char **, char **, char **, const char *, const char *, int * ); static int SplitMap( AstMapping *, int, int, int, AstMapping **, AstWcsMap **, AstMapping **, int * ); static int SplitMap2( AstMapping *, int, AstMapping **, AstWcsMap **, AstMapping **, int * ); static int SplitMat( int , double *, double *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestFits( AstFitsChan *, const char *, int *, int * ); static int Use( AstFitsChan *, int, int, int * ); static int Ustrcmp( const char *, const char *, int * ); static int Ustrncmp( const char *, const char *, size_t, int * ); static int WATCoeffs( const char *, int, double **, int **, int *, int * ); static int WcsFromStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static int WcsNatPole( AstFitsChan *, AstWcsMap *, double, double, double, double *, double *, double *, int * ); static int WorldAxes( AstFitsChan *this, AstMapping *, double *, int *, int * ); static int Write( AstChannel *, AstObject *, int * ); static void *CardData( AstFitsChan *, size_t *, int * ); static void AdaptLut( AstMapping *, int, double, double, double, double, double, double **, double **, int *, int * ); static void AddFrame( AstFitsChan *, AstFrameSet *, int, int, FitsStore *, char, const char *, const char *, int * ); static void ChangePermSplit( AstMapping *, int * ); static void CheckZero( char *, double, int, int * ); static void Chpc1( double *, double *, int, int *, int *, int * ); static void ClassTrans( AstFitsChan *, AstFitsChan *, int, int, const char *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void CreateKeyword( AstFitsChan *, const char *, char [ FITSNAMLEN + 1 ], int * ); static void DSBSetUp( AstFitsChan *, FitsStore *, AstDSBSpecFrame *, char, double, const char *, const char *, int * ); static void DSSToStore( AstFitsChan *, FitsStore *, const char *, const char *, int * ); static void DelFits( AstFitsChan *, int * ); static void Delete( AstObject *, int * ); static void DeleteCard( AstFitsChan *, const char *, const char *, int * ); static void DistortMaps( AstFitsChan *, FitsStore *, char, int , AstMapping **, AstMapping **, AstMapping **, AstMapping **, const char *, const char *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void EmptyFits( AstFitsChan *, int * ); static void FindWcs( AstFitsChan *, int, int, int, const char *, const char *, int * ); static void FixNew( AstFitsChan *, int, int, const char *, const char *, int * ); static void FixUsed( AstFitsChan *, int, int, int, const char *, const char *, int * ); static void FormatCard( AstFitsChan *, char *, const char *, int * ); static void FreeItem( double ****, int * ); static void FreeItemC( char *****, int * ); static void GetFiducialNSC( AstWcsMap *, double *, double *, int * ); static void GetFiducialPPC( AstWcsMap *, double *, double *, int * ); static void GetNextData( AstChannel *, int, char **, char **, int * ); static void InsCard( AstFitsChan *, int, const char *, int, void *, const char *, const char *, const char *, int * ); static void MakeBanner( const char *, const char *, const char *, char [ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ], int * ); static void MakeIndentedComment( int, char, const char *, const char *, char [ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1], int * ); static void MakeIntoComment( AstFitsChan *, const char *, const char *, int * ); static void MakeInvertable( double **, int, double *, int * ); static void MarkCard( AstFitsChan *, int * ); static void NewCard( AstFitsChan *, const char *, int, const void *, const char *, int, int * ); static void PreQuote( const char *, char [ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 3 ], int * ); static void PurgeWCS( AstFitsChan *, int * ); static void PutCards( AstFitsChan *, const char *, int * ); static void PutFits( AstFitsChan *, const char [ AST__FITSCHAN_FITSCARDLEN + 1 ], int, int * ); static void PutTable( AstFitsChan *, AstFitsTable *, const char *, int * ); static void PutTables( AstFitsChan *, AstKeyMap *, int * ); static void ReadFits( AstFitsChan *, int * ); static void ReadFromSource( AstFitsChan *, int * ); static void RemoveTables( AstFitsChan *, const char *, int * ); static void RetainFits( AstFitsChan *, int * ); static void RoundFString( char *, int, int * ); static void SetAlgCode( char *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetFitsCF( AstFitsChan *, const char *, double *, const char *, int, int * ); static void SetFitsCI( AstFitsChan *, const char *, int *, const char *, int, int * ); static void SetFitsCM( AstFitsChan *, const char *, int, int * ); static void SetFitsCN( AstFitsChan *, const char *, const char *, const char *, int, int * ); static void SetFitsCom( AstFitsChan *, const char *, const char *, int, int * ); static void SetFitsF( AstFitsChan *, const char *, double, const char *, int, int * ); static void SetFitsI( AstFitsChan *, const char *, int, const char *, int, int * ); static void SetFitsL( AstFitsChan *, const char *, int, const char *, int, int * ); static void SetFitsS( AstFitsChan *, const char *, const char *, const char *, int, int * ); static void SetFitsU( AstFitsChan *, const char *, const char *, int, int * ); static void SetItem( double ****, int, int, char, double, int * ); static void SetItemC( char *****, int, int, char, const char *, int * ); static void SetSourceFile( AstChannel *, const char *, int * ); static void SetValue( AstFitsChan *, const char *, void *, int, const char *, int * ); static void ShowFits( AstFitsChan *, int * ); static void Shpc1( double, double, int, double *, double *, int * ); static void SinkWrap( void (*)( const char * ), const char *, int * ); static void SkyPole( AstWcsMap *, AstMapping *, int, int, int *, char, FitsStore *, const char *, const char *, int * ); static void TableSource( AstFitsChan *, void (*)( AstFitsChan *, const char *, int, int, int * ), int * ); static void TidyOffsets( AstFrameSet *, int * ); static void Warn( AstFitsChan *, const char *, const char *, const char *, const char *, int * ); static void WcsFcRead( AstFitsChan *, AstFitsChan *, FitsStore *, const char *, const char *, int * ); static void WcsToStore( AstFitsChan *, AstFitsChan *, FitsStore *, const char *, const char *, int * ); static void WriteBegin( AstChannel *, const char *, const char *, int * ); static void WriteDouble( AstChannel *, const char *, int, int, double, const char *, int * ); static void WriteEnd( AstChannel *, const char *, int * ); static void WriteFits( AstFitsChan *, int * ); static void WriteInt( AstChannel *, const char *, int, int, int, const char *, int * ); static void WriteIsA( AstChannel *, const char *, const char *, int * ); static void WriteObject( AstChannel *, const char *, int, int, AstObject *, const char *, int * ); static void WriteString( AstChannel *, const char *, int, int, const char *, const char *, int * ); static void WriteToSink( AstFitsChan *, int * ); static void SetTableSource( AstFitsChan *, void (*)( void ), void (*)( void (*)( void ), AstFitsChan *, const char *, int, int, int * ), int * ); static void TabSourceWrap( void (*)( void ), AstFitsChan *, const char *, int, int, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static void AdaptLut( AstMapping *map, int npos, double eps, double x0, double x1, double v0, double v1, double **xtab, double **vtab, int *nsamp, int *status ){ /* * Name: * AdaptLut * Purpose: * Create a table of optimally sampled values for a Mapping. * Type: * Private function. * Synopsis: * void AdaptLut( AstMapping *map, int npos, double eps, double x0, * double x1, double v0, double v1, double **xtab, * double **vtab, int *nsamp, int *status ) * Class Membership: * FitsChan * Description: * This function returns a look-up table holding samples of the supplied * 1D mapping. The input values at which the samples are taken are * returned in the "xtab" array, and the Mapping output values at * these input values are returned in the "vtab" array. The sample * spacing is smaller at positions where the output gradient is * changing more rapidly (i.e. where the output is more non-linear). * Parameters: * map * Pointer to the Mapping. Should have 1 input and 1 output. * npos * The minimum number of samples to place within the interval to be * sampled, excluding the two end points (which are always sampeld * anyway). These samples are placed evenly through the [x0,x1] interval. The interval between adjacent samples will be further * subdivided if necessary by calling this function recursively. * eps * The maximum error in X (i.e. the Mapping input) allowed before * the supplied interval is subdivided further by a recursive call * to this function. * x0 * The Mapping input value at the start of the interval to be sampled. * It is assumed that this value is already stored in (*xtab)[0] on * entry. * x1 * The Mapping input value at the end of the interval to be sampled. * v0 * The Mapping output value at the start of the interval to be sampled. * It is assumed that this value is already stored in (*vtab)[0] on * entry. * v1 * The Mapping output value at the end of the interval to be sampled. * xtab * Address of a pointer to the array in which to store the Mapping * input values at which samples were taken. The supplied pointer * may be changed on exit to point to a larger array. New values * are added to the end of this array. The initial size of the array * is given by the supplied value for "*nsamp" * vtab * Address of a pointer to the array in which to store the Mapping * output value at each sample. The supplied pointer may be changed * on exit to point to a larger array. New values are added to the * end of this array. The initial size of the array is given by the * supplied value for "*nsamp". * nsamp * Address of an int holding the number of values in the "*xtab" * and "*ytab" arrays. Updated on exit to include the new values * added to the arrays by this function. * status * Pointer to the inherited status variable. * Returned Value: * The size of the returned xtab and vtab arrays. */ /* Local Variables: */ double *vv; /* Pointer to Mapping output values */ double *xx; /* Pointer to Mapping input values */ double dx; /* Step between sample positions */ double rg; /* Reciprocal of gradient of (x0,v0)->(x1,v1) line */ double xx0; /* X at first new sample position */ int ipos; /* Interior sample index */ int isamp; /* Index into extended xtab and vtab arrays. */ int subdivide; /* Subdivide each subinterval? */ /* Check the inherited status. */ if( !astOK ) return; /* Allocate work space. */ xx = astMalloc( sizeof( double )*npos ); vv = astMalloc( sizeof( double )*npos ); if( astOK ) { /* Set up the evenly spaced interior sample positions. */ dx = ( x1 - x0 )/( npos + 1 ); xx0 = x0 + dx; for( ipos = 0; ipos < npos; ipos++ ) { xx[ ipos ] = xx0 + ipos*dx; } /* Find the Mapping output values at these input values. */ astTran1( map, npos, xx, 1, vv ); /* See if any of these samples deviate significantly from the straight line defined by (x0,v0) and (x1,v1). If any such sample is found, we call this function recursively to sample the subdivided intervals. First handle cases where the straight line has zero gradient. */ subdivide = 0; if( v0 == v1 ) { /* Subdivide if any of the interior sample values are different to the end values. */ for( ipos = 0; ipos < npos; ipos++ ) { if( vv[ ipos ] != v0 ) { subdivide = 1; break; } } /* Now handle cases where the line has non-zero gradient. Subdivide if any of the interior sample input positions are further than "eps" from the input position that would give the same output value if the mapping was linear. */ } else { rg = ( x1 - x0 )/( v1 - v0 ); for( ipos = 0; ipos < npos; ipos++ ) { if( vv[ ipos ] == AST__BAD || fabs( rg*( vv[ ipos ] - v0 ) - ( xx[ ipos ] - x0 ) ) > eps ) { subdivide = 1; break; } } } /* If required, call this function recursively to subdivide each section of the supplied input interval, and append samples to the returned arrays. */ if( subdivide ) { /* Do each sub-interval, except the last one. The number of subintervals is one more than the number of interior samples. */ for( ipos = 0; ipos < npos; ipos++ ) { /* Append samples covering the current subinterval to the ends of the arrays. */ AdaptLut( map, npos, eps, x0, xx[ ipos ], v0, vv[ ipos ], xtab, vtab, nsamp, status ); /* Store the starting position for the next sub-interval. */ x0 = xx[ ipos ]; v0 = vv[ ipos ]; } /* Now do the final sub-interval. */ AdaptLut( map, npos, eps, x0, x1, v0, v1, xtab, vtab, nsamp, status ); /* If we do not need to subdivide, store the samples in the returned array, together with the supplied final point. */ } else { /* Extend the arrays. */ isamp = *nsamp; *nsamp += npos + 1; *xtab = astGrow( *xtab, *nsamp, sizeof( double ) ); *vtab = astGrow( *vtab, *nsamp, sizeof( double ) ); if( astOK ) { /* Store the sample positions and values at the end of the extended arrays. */ for( ipos = 0; ipos < npos; ipos++, isamp++ ) { (*xtab)[ isamp ] = xx[ ipos ]; (*vtab)[ isamp ] = vv[ ipos ]; } (*xtab)[ isamp ] = x1; (*vtab)[ isamp ] = v1; } } } /* Free resources. */ xx = astFree( xx ); vv= astFree( vv ); } static int AddEncodingFrame( AstFitsChan *this, AstFrameSet *fs, int encoding, const char *method, const char *class, int *status ){ /* * Name: * AddEncodingFrame * Purpose: * Add a Frame which conforms to the requirements of the specified encoding. * Type: * Private function. * Synopsis: * int AddEncodingFrame( AstFitsChan *this, AstFrameSet *fs, int encoding, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function attempts to create a Frame based on the current Frame * of the supplied FrameSet, which conforms to the requirements of the * specified Encoding. If created, this Frame is added into the * FrameSet as the new current Frame, and the index of the original current * Frame is returned. * Parameters: * this * Pointer to the FitsChan. * fs * Pointer to the FrameSet. * encoding * The encoding in use. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The index of the original current Frame in the FrameSet. A value of * AST__NOFRAME is returned if no new Frame is added to the FrameSet, * or if an error occurs. */ /* Local Variables: */ AstCmpFrame *cmpfrm; /* Pointer to spectral cube frame */ AstFrame *cfrm; /* Pointer to original current Frame */ AstFrame *newfrm; /* Frame describing coord system to be used */ AstFrame *pfrm; /* Pointer to primary Frame containing axis */ AstFrameSet *fsconv; /* FrameSet converting what we have to what we want */ AstMapping *map; /* Mapping from what we have to what we want */ AstSkyFrame *skyfrm; /* Pointer to SkyFrame */ AstSpecFrame *specfrm; /* Pointer to SpecFrame */ AstSystemType sys; /* Frame coordinate system */ int i; /* Axis index */ int naxc; /* No. of axes in original current Frame */ int paxis; /* Axis index in primary frame */ int result; /* Returned value */ /* Initialise */ result = AST__NOFRAME; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the current Frame and note how many axes it has. */ cfrm = astGetFrame( fs, AST__CURRENT ); naxc = astGetNaxes( cfrm ); /* FITS-CLASS */ /* ========== */ if( encoding == FITSCLASS_ENCODING ) { /* Try to locate a SpecFrame and a SkyFrame in the current Frame. */ specfrm = NULL; skyfrm = NULL; for( i = 0; i < naxc; i++ ) { astPrimaryFrame( cfrm, i, &pfrm, &paxis ); if( astIsASpecFrame( pfrm ) ) { if( !specfrm ) specfrm = astCopy( pfrm ); } else if( IsASkyFrame( pfrm ) ) { if( !skyfrm ) skyfrm = astCopy( pfrm ); } pfrm = astAnnul( pfrm ); } /* Cannot do anything if either is missing. */ if( specfrm && skyfrm ) { /* If the spectral axis is not frequency, set it to frequency. Also set spectral units of "Hz". */ sys = astGetSystem( specfrm ); if( sys != AST__FREQ ) { astSetSystem( specfrm, AST__FREQ ); sys = AST__FREQ; } /* Ensure the standard of rest is Source and units are "Hz". */ astSetUnit( specfrm, 0, "Hz" ); astSetStdOfRest( specfrm, AST__SCSOR ); /* The celestial axes must be either FK4, FK5 or galactic. */ sys = astGetSystem( skyfrm ); if( sys != AST__FK4 && sys != AST__FK5 && sys != AST__GALACTIC ) { astSetSystem( skyfrm, AST__FK5 ); sys = AST__FK5; } /* FK5 systems must be J2000, and FK4 must be B1950. */ if( sys == AST__FK5 ) { astSetC( skyfrm, "Equinox", "J2000.0" ); } else if( sys == AST__FK4 ) { astSetC( skyfrm, "Equinox", "B1950.0" ); } /* Combine the spectral and celestial Frames into a single CmpFrame with the spectral axis being the first axis. */ cmpfrm = astCmpFrame( specfrm, skyfrm, "", status ); /* Attempt to obtain the current Frame of the supplied FrameSet to this new Frame. */ fsconv = astConvert( cfrm, cmpfrm, "" ); if( fsconv ) { /* Get the Mapping and current Frame from the rconversion FrameSet. */ newfrm = astGetFrame( fsconv, AST__CURRENT ); map = astGetMapping( fsconv, AST__BASE, AST__CURRENT ); /* Save the original current Frame index. */ result = astGetCurrent( fs ); /* Add the new Frame into the supplied FrameSet using the above Mapping to connect it to the original current Frame. The new Frame becomes the current Frame. */ astAddFrame( fs, AST__CURRENT, map, newfrm ); /* Free resources */ map = astAnnul( map ); newfrm = astAnnul( newfrm ); fsconv = astAnnul( fsconv ); } /* Free resources */ cmpfrm = astAnnul( cmpfrm ); } /* Release resources. */ if( specfrm ) specfrm = astAnnul( specfrm ); if( skyfrm ) skyfrm = astAnnul( skyfrm ); } /* Free reources. */ cfrm = astAnnul( cfrm ); /* Return the result */ return result; } static void AddFrame( AstFitsChan *this, AstFrameSet *fset, int pixel, int npix, FitsStore *store, char s, const char *method, const char *class, int *status ){ /* * Name: * AddFrame * Purpose: * Create a Frame describing a set of axes with a given co-ordinate * version, and add it to the supplied FrameSet. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void AddFrame( AstFitsChan *this, AstFrameSet *fset, int pixel, * int npix, FitsStore *store, char s, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A Frame is created describing axis with a specific co-ordinate * version character, reading information from the supplied FitsStore. * A suitable Mapping is created to connect the new Frame to the pixel * (GRID) Frame in the supplied FrameSet, and the Frame is added into * the FrameSet using this Mapping. * Parameters: * this * The FitsChan from which the keywords were read. Warning messages * are added to this FitsChan if the celestial co-ordinate system is * not recognized. * fset * Pointer to the FrameSet to be extended. * pixel * The index of the pixel (GRID) Frame within fset. * npix * The number of pixel axes. * store * The FitsStore containing the required information extracted from * the FitsChan. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frame; /* Requested Frame */ AstMapping *mapping; /* Mapping from pixel to requested Frame */ AstMapping *tmap; /* Temporary Mapping pointer */ AstPermMap *pmap; /* PermMap pointer to add or remove axes */ double con; /* Value to be assigned to missing axes */ int *inperm; /* Pointer to input axis permutation array */ int *outperm; /* Pointer to output axis permutation array */ int i; /* Axis index */ int nwcs; /* Number of wcs axes */ /* Check the inherited status. */ if( !astOK ) return; /* Get a Mapping between pixel coordinates and physical coordinates, using the requested axis descriptions. Also returns a Frame describing the physical coordinate system. */ mapping = WcsMapFrm( this, store, s, &frame, method, class, status ); /* Add the Frame into the FrameSet, and annul the mapping and frame. If the new Frame has more axes than the pixel Frame, use a PermMap which assigns constant value 1.0 to the extra axes. If the new Frame has less axes than the pixel Frame, use a PermMap which throws away the extra axes. */ if( mapping != NULL ) { nwcs = astGetNin( mapping ); if( nwcs != npix ) { inperm = astMalloc( sizeof(int)*(size_t)npix ); outperm = astMalloc( sizeof(int)*(size_t)nwcs ); if( astOK ) { for( i = 0; i < npix; i++ ) { inperm[ i ] = ( i < nwcs ) ? i : -1; } for( i = 0; i < nwcs; i++ ) { outperm[ i ] = ( i < npix ) ? i : -1; } con = 1.0; pmap = astPermMap( npix, inperm, nwcs, outperm, &con, "", status ); tmap = (AstMapping *) astCmpMap( pmap, mapping, 1, "", status ); pmap = astAnnul( pmap ); (void) astAnnul( mapping ); mapping = tmap; } inperm = astFree( inperm ); outperm = astFree( outperm ); } astAddFrame( fset, pixel, mapping, frame ); /* Annul temporary resources. */ mapping = astAnnul( mapping ); } frame = astAnnul( frame ); } static int AddVersion( AstFitsChan *this, AstFrameSet *fs, int ipix, int iwcs, FitsStore *store, double *dim, char s, int encoding, int isoff, const char *method, const char *class, int *status ){ /* * Name: * AddVersion * Purpose: * Add values to a FitsStore describing a specified Frame in a FrameSet. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int AddVersion( AstFitsChan *this, AstFrameSet *fs, int ipix, int iwcs, * FitsStore *store, double *dim, char s, int encoding, * int isoff, const char *method, const char *class, * int *status ) * Class Membership: * FitsChan member function. * Description: * Values are added to the supplied FitsStore describing the specified * WCS Frame, and its relationship to the specified pixel Frame. These * values are based on the standard FITS-WCS conventions. * Parameters: * this * Pointer to the FitsChan. * fs * Pointer to the FrameSet. * ipix * The index of the pixel (GRID) Frame within fset. * iwcs * The index of the Frame within fset to use as the WCS co-ordinate * Frame. * store * The FitsStore in which to store the information extracted from * the FrameSet. * dim * Pointer to an array of pixel axis dimensions. Individual elements * will be AST__BAD if dimensions are not known. The number of * elements should equal the number of axes in the base Frame of the * supplied FrameSet. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * encoding * The encoding being used. * isoff * If greater than zero, the Frame is an offset SkyFrame and the * description added to the FitsStore should describe offset coordinates. * If less than than zero, the Frame is an offset SkyFrame and the * description added to the FitsStore should describe absolute coordinates. * If zero, the Frame is an absolute SkyFrame and the description added * to the FitsSTore should (by necessity) describe absolute coordinates. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Retuned Value: * A value of 1 is returned if the WCS Frame was succesfully added to * the FitsStore. A value of zero is returned otherwise. */ /* Local Variables: */ AstFrame *wcsfrm; /* WCS Frame */ AstFrameSet *fset; /* Temporary FrameSet */ AstMapping *iwcmap; /* Mapping from WCS to IWC Frame */ AstMapping *mapping; /* Mapping from pixel to WCS Frame */ AstMapping *pixiwcmap; /* Mapping from pixel to IWC Frame */ AstMapping *tmap2; /* Temporary Mapping */ AstMapping *tmap; /* Temporary Mapping */ const char *old_skyrefis;/* Old value of SkyRefIs attribute */ double *crvals; /* Pointer to array holding default CRVAL values */ double cdelt2; /* Sum of squared PC values */ double cdelt; /* CDELT value for axis */ double crpix; /* CRPIX value for axis */ double crval; /* CRVAL value for axis */ double pc; /* Element of the PC array */ int *axis_done; /* Flags indicating which axes have been done */ int *wperm; /* FITS axis for each Mapping output (Frame axis) */ int fits_i; /* FITS WCS axis index */ int fits_j; /* FITS pixel axis index */ int iax; /* Frame axis index */ int icurr; /* Index of current Frame */ int nwcs; /* No. of axes in WCS frame */ int ret; /* Returned value */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* If the frame is a SkyFrame describing offset coordinates, but the description added to the FitsStore should be for absolute coordinates, temporarily clear the SkyFrame SkyRefIs attribute. We need to make it the current Frame first so that we can use the FrameSet to clear the attribte, so that the SkyFrame will be re-mapped within the FrameSet to take account of the clearing. For negative isoff values, set the specific negative value to indicate the original SkyRefIs value. */ if( isoff < 0 ) { icurr = astGetCurrent( fs ); astSetCurrent( fs, iwcs ); old_skyrefis = astGetC( fs, "SkyRefIs" ); if( astOK ) { if( !Ustrcmp( old_skyrefis, "POLE", status ) ) { isoff = -1; } else if( !Ustrcmp( old_skyrefis, "ORIGIN", status ) ) { isoff = -2; } else { isoff = -3; } } astClear( fs, "SkyRefIs" ); astSetCurrent( fs, icurr ); } else { old_skyrefis = AST__BAD_REF; } /* Construct a new FrameSet holding the pixel and WCS Frames from the supplied FrameSet, but in which the current Frame is a copy of the supplied WCS Frame, but optionally extended to include any extra axes needed to conform to the FITS model. For instance, if the WCS Frame consists of a single 1D SpecFrame with a defined celestial reference position (SpecFrame attributes RefRA and RefDec), then FITS-WCS paper III requires there to be a pair of celestial axes in the WCS Frame in which the celestial reference point for the spectral axis is defined. */ fset = MakeFitsFrameSet( this, fs, ipix, iwcs, encoding, method, class, status ); /* If required, re-instate the original value of the SkyRefIs attribute in the supplied FrameSet. */ if( old_skyrefis != AST__BAD_REF ) { astSetCurrent( fs, iwcs ); astSetC( fs, "SkyRefIs", old_skyrefis ); astSetCurrent( fs, icurr ); } /* Abort if the FrameSet could not be produced. */ if( !fset ) return ret; /* Get the Mapping from base to current Frame and check its inverse is defined. Return if not. Note, we can handle non-invertable Mappings if we are allowed to use the -TAB algorithm. */ mapping = astGetMapping( fset, AST__BASE, AST__CURRENT ); wcsfrm = astGetFrame( fset, AST__CURRENT ); if( !astGetTranInverse( mapping ) && astGetTabOK( this ) <= 0 ) { mapping = astAnnul( mapping ); wcsfrm = astAnnul( wcsfrm ); fset = astAnnul( fset ); return ret; } /* We now need to choose the "FITS WCS axis" (i.e. the number that is included in FITS keywords such as CRVAL2) for each axis of the output Frame. Allocate memory to store these indices. */ nwcs= astGetNout( mapping ); wperm = astMalloc( sizeof(int)*(size_t) nwcs ); /* Attempt to use the FitsAxisOrder attribute to determine the order. If this is set to "", then for each WCS axis, we use the index of the pixel axis which is most closely aligned with it. */ if( !FitsAxisOrder( this, nwcs, wcsfrm, wperm, status ) && !WorldAxes( this, mapping, dim, wperm, status ) ) { wperm = astFree( wperm ); mapping = astAnnul( mapping ); wcsfrm = astAnnul( wcsfrm ); fset = astAnnul( fset ); return ret; } /* Allocate an array of flags, one for each axis, which indicate if a description of the corresponding axis has yet been stored in the FitsStore. Initialise them to indicate that no axes have yet been described. */ axis_done = astMalloc( sizeof(int)*(size_t) nwcs ); if( astOK ) for( iax = 0; iax < nwcs; iax++ ) axis_done[ iax ] = 0; /* Get the original reference point from the FitsChan and convert it into the require WCS Frame. This is used as the default reference point (some algorithms may choose to ignore this default reference point ). */ crvals = ReadCrval( this, wcsfrm, s, method, class, status ); /* For each class of FITS conventions (celestial, spectral, others), identify any corresponding axes within the WCS Frame and add descriptions of them to the FitsStore. These descriptions are in terms of the FITS keywords defined in the corresponding FITS-WCS paper. Note, the keywords which descirbed the pixel->IWC mapping (CRPIX, CD, PC, CDELT) are not stored by these functions, instead each function returns a Mapping from WCS to IWC coords (these Mappings pass on axes of the wrong class without change). These Mappings are combined in series to get the final WCS->IWC Mapping. First do celestial axes. */ iwcmap = CelestialAxes( this, fset, dim, wperm, s, store, axis_done, isoff, method, class, status ); /* Now look for spectral axes, and update the iwcmap. */ tmap = SpectralAxes( this, fset, dim, wperm, s, store, crvals, axis_done, method, class, status ); tmap2 = (AstMapping *) astCmpMap( iwcmap, tmap, 1, "", status ); tmap = astAnnul( tmap ); (void) astAnnul( iwcmap ); iwcmap = tmap2; /* Finally add descriptions of any axes not yet described (they are assumed to be linear), and update the iwcmap. */ tmap = OtherAxes( this, fset, dim, wperm, s, store, crvals, axis_done, method, class, status ); tmap2 = (AstMapping *) astCmpMap( iwcmap, tmap, 1, "", status ); tmap = astAnnul( tmap ); (void) astAnnul( iwcmap ); iwcmap = tmap2; /* The "iwcmap" Mapping found above converts from the WCS Frame to the IWC Frame. Combine the pixel->WCS Mapping with this WCS->IWC Mapping to get the pixel->IWC Mapping. */ pixiwcmap = (AstMapping *) astCmpMap( mapping, iwcmap, 1, "", status ); mapping = astAnnul( mapping ); iwcmap = astAnnul( iwcmap ); /* Now attempt to store values for the keywords describing the pixel->IWC Mapping (CRPIX, CD, PC, CDELT). This tests that the iwcmap is linear. Zero is returned if the test fails. */ ret = MakeIntWorld( pixiwcmap, wcsfrm, wperm, s, store, dim, method, class, status ); /* If succesfull... */ if( ret ) { /* Store the Domain name as the WCSNAME keyword (if set). */ if( astTestDomain( wcsfrm ) ) { SetItemC( &(store->wcsname), 0, 0, s, (char *) astGetDomain( wcsfrm ), status ); } /* Store the UT1-UTC correction, if set, converting from seconds to days (as used by JACH). */ if( astTestDut1( wcsfrm ) && s == ' ' ) { SetItem( &(store->dut1), 0, 0, ' ', astGetDut1( wcsfrm )/SPD, status ); } /* Set CRVAL values which are very small compared to the pixel size to zero. */ for( iax = 0; iax < nwcs; iax++ ) { fits_i = wperm[ iax ]; crval = GetItem( &(store->crval), fits_i, 0, s, NULL, method, class, status ); if( crval != AST__BAD ) { cdelt2 = 0.0; for( fits_j = 0; fits_j < nwcs; fits_j++ ){ pc = GetItem( &(store->pc), fits_i, fits_j, s, NULL, method, class, status ); if( pc == AST__BAD ) pc = ( fits_i == fits_j ) ? 1.0 : 0.0; cdelt2 += pc*pc; } cdelt = GetItem( &(store->cdelt), fits_i, 0, s, NULL, method, class, status ); if( cdelt == AST__BAD ) cdelt = 1.0; cdelt2 *= ( cdelt*cdelt ); if( fabs( crval ) < sqrt( DBL_EPSILON*cdelt2 ) ) { SetItem( &(store->crval), fits_i, 0, s, 0.0, status ); } } } /* Round CRPIX values to the nearest millionth of a pixel. */ for( iax = 0; iax < nwcs; iax++ ) { crpix = GetItem( &(store->crpix), 0, iax, s, NULL, method, class, status ); if( crpix != AST__BAD ) { SetItem( &(store->crpix), 0, iax, s, floor( crpix*1.0E6 + 0.5 )*1.0E-6, status ); } } } /* Free remaining resources. */ if( crvals ) crvals = astFree( crvals ); wcsfrm = astAnnul( wcsfrm ); pixiwcmap = astAnnul( pixiwcmap ); axis_done = astFree( axis_done ); wperm = astFree( wperm ); fset = astAnnul( fset ); /* If an error has occurred, return zero */ return astOK ? ret : 0; } static AstMapping *AddUnitMaps( AstMapping *map, int iax, int nax, int *status ) { /* * Name: * AddUnitMaps * Purpose: * Embed a Mapping within a pair of parallel UnitMaps. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *AddUnitMaps( AstMapping *map, int iax, int nax, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a Mapping which consists of the supplied Mapping * in parallel with a pair of UnitMaps so that the first axis of the * supplied Mapping is at a specified axis number in the returned Mapping. * Parameters: * map * Pointer to the Mapping. The Mapping must have equal numbers of * input and output coordinates. * iax * The index for the first input of "map" within the returned * Mapping. * nax * The number of axes for the returned Mapping. * status * Pointer to the inherited status variable. * Returned Value: * A Mapping which has "nax" axes, and in which the "iax" axis * corresponds to the first axis of "map". Axes lower than "iax" are * transformed using a UnitMap, and axes higher than the last axis of * "map" are transformed using a UnitMap. */ /* Local Variables: */ AstMapping *ret; /* Returned Mapping */ AstMapping *tmap0; /* Temporary Mapping */ AstMapping *tmap1; /* Temporary Mapping */ AstMapping *tmap2; /* Temporary Mapping */ int nmap; /* Number of supplied Mapping inputs */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Initialise the returned Mapping to be a clone of the supplied Mapping. */ ret = astClone( map ); /* Note the number of inputs of the supplied Mapping (assumed to be equal to the number of outputs). */ nmap = astGetNin( map ); /* If necessary produce a parallel CmpMap which combines the Mapping with a UnitMap representing the axes lower than "iax". */ if( iax > 0 ) { tmap0 = (AstMapping *) astUnitMap( iax, "", status ); tmap1 = (AstMapping *) astCmpMap( tmap0, ret, 0, "", status ); ret = astAnnul( ret ); tmap0 = astAnnul( tmap0 ); ret = tmap1; } /* If necessary produce a parallel CmpMap which combines the Mapping with a UnitMap representing the axes higher than "iax+nmap". */ if( iax + nmap < nax ) { tmap1 = (AstMapping *) astUnitMap( nax - iax - nmap, "", status ); tmap2 = (AstMapping *) astCmpMap( ret, tmap1, 0, "", status ); ret = astAnnul( ret ); tmap1 = astAnnul( tmap1 ); ret = tmap2; } /* Return the result. */ return ret; } static int AIPSFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * AIPSFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-AIPS encoding. * Type: * Private function. * Synopsis: * int AIPSFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-AIPS encoding. * * AIPS encoding is like FITS-WCS encoding but with the following * restrictions: * * 1) The celestial projection must not have any projection parameters * which are not set to their default values. The one exception to this * is that SIN projections are acceptable if the associated projection * parameter PV_1 is zero and PV_2 = cot( reference point * latitude). This is encoded using the string "-NCP". The SFL projection * is encoded using the string "-GLS". Note, the original AIPS WCS * system only recognised a small subset of the currently available * projections, but some more recent AIPS-like software recognizes some * of the new projections included in the FITS-WCS encoding. The AIT, * GLS and MER can only be written if the CRVAL keywords are zero for * both longitude and latitude axes. * * 2) The celestial axes must be RA/DEC, galactic or ecliptic. * * 3) LONPOLE and LATPOLE must take their default values. * * 4) Only primary axis descriptions are written out. * * 5) EPOCH is written instead of EQUINOX & RADECSYS, and uses the * IAU 1984 rule ( EPOCH < 1984.0 is treated as a Besselian epoch * and implies RADECSYS=FK4, EPOCH >= 1984.0 is treated as a * Julian epoch and implies RADECSYS=FK5). The RADECSYS & EQUINOX * values in the FitsStore must be consistent with this rule. * * 6) Any rotation produced by the PC matrix must be restricted to * the celestial plane, and must involve no shear. A CROTA keyword * with associated CDELT values are produced instead of the PC * matrix. * * 7) ICRS is not supported. * * 8) Spectral axes can be created only for FITS-WCS CTYPE values of "FREQ" * "VRAD" and "VOPT-F2W" and with standards of rest of LSRK, LSRD, * BARYCENT and GEOCENTR. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ char *comm; /* Pointer to comment string */ const char *cval; /* Pointer to string keyword value */ const char *specunit;/* Pointer to corrected spectral units string */ char combuf[80]; /* Buffer for FITS card comment */ char lattype[MXCTYPELEN];/* Latitude axis CTYPE */ char lontype[MXCTYPELEN];/* Longitude axis CTYPE */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ char spectype[MXCTYPELEN];/* Spectral axis CTYPE */ double *cdelt; /* Pointer to CDELT array */ double cdl; /* CDELT term */ double cdlat_lon; /* Off-diagonal CD element */ double cdlon_lat; /* Off-diagonal CD element */ double coscro; /* Cos( CROTA ) */ double crota; /* CROTA value to use */ double epoch; /* Epoch of reference equinox */ double fd; /* Fraction of a day */ double latval; /* CRVAL for latitude axis */ double lonval; /* CRVAL for longitude axis */ double mjd99; /* MJD at start of 1999 */ double p1, p2; /* Projection parameters */ double rho_a; /* First estimate of CROTA */ double rho_b; /* Second estimate of CROTA */ double sincro; /* Sin( CROTA ) */ double specfactor; /* Factor for converting internal spectral units */ double val; /* General purpose value */ int axlat; /* Index of latitude FITS WCS axis */ int axlon; /* Index of longitude FITS WCS axis */ int axrot1; /* Index of first CROTA rotation axis */ int axrot2; /* Index of second CROTA rotation axis */ int axspec; /* Index of spectral FITS WCS axis */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int naxis; /* No. of axes */ int ok; /* Is FitsSTore OK for IRAF encoding? */ int prj; /* Projection type */ /* Check the inherited status. */ if( !astOK ) return 0; /* Initialise */ specunit = ""; specfactor = 1.0; /* First check that the values in the FitsStore conform to the requirements of the AIPS encoding. Assume they do to begin with. */ ok = 1; /* Just do primary axes. */ s = ' '; /* Look for the primary celestial axes. */ FindLonLatSpecAxes( store, s, &axlon, &axlat, &axspec, method, class, status ); /* If both longitude and latitude axes are present ...*/ if( axlon >= 0 && axlat >= 0 ) { /* Get the CRVAL values for both axes. */ latval = GetItem( &( store->crval ), axlat, 0, s, NULL, method, class, status ); if( latval == AST__BAD ) ok = 0; lonval = GetItem( &( store->crval ), axlon, 0, s, NULL, method, class, status ); if( lonval == AST__BAD ) ok = 0; /* Get the CTYPE values for both axes. Extract the projection type as specified by the last 4 characters in the latitude CTYPE keyword value. */ cval = GetItemC( &(store->ctype), axlon, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { strcpy( lontype, cval ); } cval = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; prj = AST__WCSBAD; } else { strcpy( lattype, cval ); prj = astWcsPrjType( cval + 4 ); } /* Check the projection type is OK. */ if( prj == AST__WCSBAD ){ ok = 0; } else if( prj != AST__SIN ){ /* There must be no projection parameters. */ if( GetMaxJM( &(store->pv), ' ', status ) >= 0 ) { ok = 0; /* FITS-AIPS cannot handle the AST-specific TPN projection. */ } else if( prj == AST__TPN ) { ok = 0; /* For AIT, MER and GLS, check that the reference point is the origin of the celestial co-ordinate system. */ } else if( prj == AST__MER || prj == AST__AIT || prj == AST__SFL ) { if( latval != 0.0 || lonval != 0.0 ){ ok = 0; /* Change the new SFL projection code to to the older equivalent GLS */ } else if( prj == AST__SFL ){ (void) strcpy( lontype + 4, "-GLS" ); (void) strcpy( lattype + 4, "-GLS" ); } } /* SIN projections are only acceptable if the associated projection parameters are both zero, or if the first is zero and the second = cot( reference point latitude ) (the latter case is equivalent to the old NCP projection). */ } else { p1 = GetItem( &( store->pv ), axlat, 1, s, NULL, method, class, status ); p2 = GetItem( &( store->pv ), axlat, 2, s, NULL, method, class, status ); if( p1 == AST__BAD ) p1 = 0.0; if( p2 == AST__BAD ) p2 = 0.0; ok = 0; if( p1 == 0.0 ) { if( p2 == 0.0 ) { ok = 1; } else if( fabs( p2 ) >= 1.0E14 && latval == 0.0 ){ ok = 1; (void) strcpy( lontype + 4, "-NCP" ); (void) strcpy( lattype + 4, "-NCP" ); } else if( fabs( p2*tan( AST__DD2R*latval ) - 1.0 ) < 0.01 ){ ok = 1; (void) strcpy( lontype + 4, "-NCP" ); (void) strcpy( lattype + 4, "-NCP" ); } } } /* Identify the celestial coordinate system from the first 4 characters of the longitude CTYPE value. Only RA, galactic longitude, and ecliptic longitude can be stored using FITS-AIPS. */ if( ok && strncmp( lontype, "RA--", 4 ) && strncmp( lontype, "GLON", 4 ) && strncmp( lontype, "ELON", 4 ) ) ok = 0; /* If the physical Frame requires a LONPOLE or LATPOLE keyword, it cannot be encoded using FITS-IRAF. */ if( GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ) != AST__BAD || GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ) != AST__BAD ) ok = 0; } /* If a spectral axis is present ...*/ if( ok && axspec >= 0 ) { /* Get the CTYPE values for the axis, and find the AIPS equivalent, if possible. */ cval = GetItemC( &(store->ctype), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { if( !strncmp( cval, "FREQ", astChrLen( cval ) ) ) { strcpy( spectype, "FREQ" ); } else if( !strncmp( cval, "VRAD", astChrLen( cval ) ) ) { strcpy( spectype, "VELO" ); } else if( !strncmp( cval, "VOPT-F2W", astChrLen( cval ) ) ) { strcpy( spectype, "FELO" ); } else { ok = 0; } } /* If OK, check the SPECSYS value and add the AIPS equivalent onto the end of the CTYPE value.*/ cval = GetItemC( &(store->specsys), 0, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else if( ok ) { if( !strncmp( cval, "LSRK", astChrLen( cval ) ) ) { strcpy( spectype+4, "-LSR" ); } else if( !strncmp( cval, "LSRD", astChrLen( cval ) ) ) { strcpy( spectype+4, "-LSD" ); } else if( !strncmp( cval, "BARYCENT", astChrLen( cval ) ) ) { strcpy( spectype+4, "-HEL" ); } else if( !strncmp( cval, "GEOCENTR", astChrLen( cval ) ) ) { strcpy( spectype+4, "-GEO" ); } else { ok = 0; } } /* If still OK, ensure the spectral axis units are Hz or m/s. */ cval = GetItemC( &(store->cunit), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else if( ok ) { if( !strcmp( cval, "Hz" ) ) { specunit = "HZ"; specfactor = 1.0; } else if( !strcmp( cval, "kHz" ) ) { specunit = "HZ"; specfactor = 1.0E3; } else if( !strcmp( cval, "MHz" ) ) { specunit = "HZ"; specfactor = 1.0E6; } else if( !strcmp( cval, "GHz" ) ) { specunit = "HZ"; specfactor = 1.0E9; } else if( !strcmp( cval, "m/s" ) ) { specunit = "m/s"; specfactor = 1.0; } else if( !strcmp( cval, "km/s" ) ) { specunit = "m/s"; specfactor = 1.0E3; } else { ok = 0; } } } /* Save the number of axes */ naxis = GetMaxJM( &(store->crpix), ' ', status ) + 1; /* If this is different to the value of NAXIS abort since this encoding does not support WCSAXES keyword. */ if( naxis != store->naxis ) ok = 0; /* Allocate memory to store the CDELT values */ if( ok ) { cdelt = (double *) astMalloc( sizeof(double)*naxis ); if( !cdelt ) ok = 0; } else { cdelt = NULL; } /* Check that rotation is restricted to the celestial plane, and extract the CDELT (diagonal) terms, etc. If there are no celestial axes, restrict rotation to the first two non-spectral axes. */ if( axlat < 0 && axlon < 0 ) { if( axspec >= 0 && naxis > 2 ) { axrot2 = ( axspec == 0 ) ? 1 : 0; axrot1 = axrot2 + 1; if( axrot1 == axspec ) axrot1++; } else if( naxis > 1 ){ axrot2 = 0; axrot1 = 1; } else { axrot2 = -1; axrot1 = -1; } } else { axrot1 = axlon; axrot2 = axlat; } cdlat_lon = 0.0; cdlon_lat = 0.0; for( i = 0; i < naxis && ok; i++ ){ cdl = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdl == AST__BAD ) cdl = 1.0; for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdl; if( i == j ){ cdelt[ i ] = val; } else if( i == axrot2 && j == axrot1 ){ cdlat_lon = val; } else if( i == axrot1 && j == axrot2 ){ cdlon_lat = val; } else if( val != 0.0 ){ ok = 0; } } } /* Find the CROTA and CDELT values for the celestial axes. */ if( ok && axrot1 >= 0 && axrot2 >= 0 ) { if( cdlat_lon > 0.0 ) { rho_a = atan2( cdlat_lon, cdelt[ axrot1 ] ); } else if( cdlat_lon == 0.0 ) { rho_a = 0.0; } else { rho_a = atan2( -cdlat_lon, -cdelt[ axrot1 ] ); } if( cdlon_lat > 0.0 ) { rho_b = atan2( cdlon_lat, -cdelt[ axrot2 ] ); } else if( cdlon_lat == 0.0 ) { rho_b = 0.0; } else { rho_b = atan2( -cdlon_lat, cdelt[ axrot2 ] ); } if( fabs( palDrange( rho_a - rho_b ) ) < 1.0E-2 ){ crota = 0.5*( palDranrm( rho_a ) + palDranrm( rho_b ) ); coscro = cos( crota ); sincro = sin( crota ); if( fabs( coscro ) > fabs( sincro ) ){ cdelt[ axrot2 ] /= coscro; cdelt[ axrot1 ] /= coscro; } else { cdelt[ axrot2 ] = -cdlon_lat/sincro; cdelt[ axrot1 ] = cdlat_lon/sincro; } crota *= AST__DR2D; } else { ok = 0; } } else { crota = 0.0; } /* Get RADECSYS and the reference equinox (called EPOCH in FITS-AIPS). */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); epoch = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); /* If RADECSYS was available... */ if( cval ){ /* ICRS is not supported in this encoding. */ if( !strcmp( "ICRS", cval ) ) ok = 0; /* If epoch was not available, set a default epoch. */ if( epoch == AST__BAD ){ if( !strcmp( "FK4", cval ) ){ epoch = 1950.0; } else if( !strcmp( "FK5", cval ) ){ epoch = 2000.0; } else { ok = 0; } /* If an epoch was supplied, check it is consistent with the IAU 1984 rule. */ } else { if( !strcmp( "FK4", cval ) ){ if( epoch >= 1984.0 ) ok = 0; } else if( !strcmp( "FK5", cval ) ){ if( epoch < 1984.0 ) ok = 0; } else { ok = 0; } } } /* Only create the keywords if the FitsStore conforms to the requirements of the FITS-AIPS encoding. */ if( ok ) { /* Get and save CRPIX for all pixel axes. These are required, so break if they are not available. */ for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->crpix), 0, j, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { sprintf( combuf, "Reference pixel on axis %d", j + 1 ); SetValue( this, FormatKey( "CRPIX", j + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CRVAL for all intermediate axes. These are required, so break if they are not available. */ for( i = 0; i < naxis && ok; i++ ){ val = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { if( i == axspec ) val *= specfactor; sprintf( combuf, "Value at ref. pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRVAL", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CTYPE for all intermediate axes. These are required, so break if they are not available. Use the potentially modified versions saved above for the celestial axes. */ for( i = 0; i < naxis && ok; i++ ){ if( i == axlat ) { cval = lattype; } else if( i == axlon ) { cval = lontype; } else if( i == axspec ) { cval = spectype; } else { cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); } if( cval && ( strlen(cval) < 5 || strcmp( cval + 4, "-TAB" ) ) ) { comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } SetValue( this, FormatKey( "CTYPE", i + 1, -1, s, status ), &cval, AST__STRING, comm, status ); } else { ok = 0; } } /* CDELT values */ if( axspec != -1 ) cdelt[ axspec ] *= specfactor; for( i = 0; i < naxis; i++ ){ SetValue( this, FormatKey( "CDELT", i + 1, -1, s, status ), cdelt + i, AST__FLOAT, "Pixel size", status ); } /* CUNIT values. */ for( i = 0; i < naxis; i++ ) { cval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( cval ) { if( i == axspec ) cval = specunit; sprintf( combuf, "Units for axis %d", i + 1 ); SetValue( this, FormatKey( "CUNIT", i + 1, -1, s, status ), &cval, AST__STRING, combuf, status ); } } /* CROTA */ if( axrot2 != -1 ){ SetValue( this, FormatKey( "CROTA", axrot2 + 1, -1, s, status ), &crota, AST__FLOAT, "Axis rotation", status ); } else if( ( axspec == -1 && naxis > 1 ) || ( axspec != -1 && naxis > 2 ) ) { SetValue( this, "CROTA1", &crota, AST__FLOAT, "Axis rotation", status ); } /* Reference equinox */ if( epoch != AST__BAD ) SetValue( this, "EPOCH", &epoch, AST__FLOAT, "Epoch of reference equinox", status ); /* Date of observation. */ val = GetItem( &(store->mjdobs), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD ) { /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", (void *) &cval, AST__STRING, "Date of observation", status ); } /* Spectral stuff.. */ if( axspec >= 0 ) { /* Rest frequency */ val = GetItem( &(store->restfrq), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "RESTFREQ", -1, -1, s, status ), &val, AST__FLOAT, "[Hz] Rest frequency", status ); } } /* Release CDELT workspace */ if( cdelt ) cdelt = (double *) astFree( (void *) cdelt ); /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ok : 0; } static int AIPSPPFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * AIPSPPFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-AIPS++ encoding. * Type: * Private function. * Synopsis: * int AIPSPPFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-AIPS++ encoding. * * AIPS++ encoding is like FITS-WCS encoding but with the following * restrictions: * * 1) The celestial axes must be RA/DEC, galactic or ecliptic. * * 2) Only primary axis descriptions are written out. * * 3) RADESYS is not written and so the RADECSYS & EQUINOX values in the * FitsStore must be consistent with the "1984" rule. * * 4) Any rotation produced by the PC matrix must be restricted to * the celestial plane, and must involve no shear. A CROTA keyword * with associated CDELT values are produced instead of the PC * matrix. * * 5) ICRS is not supported. * * 6) Spectral axes can be created only for FITS-WCS CTYPE values of "FREQ" * "VRAD" and "VOPT-F2W" and with standards of rest of LSRK, LSRD, * BARYCENT and GEOCENTR. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ char *comm; /* Pointer to comment string */ const char *cval; /* Pointer to string keyword value */ const char *specunit;/* Pointer to corrected spectral units string */ char combuf[80]; /* Buffer for FITS card comment */ char lattype[MXCTYPELEN];/* Latitude axis CTYPE */ char lontype[MXCTYPELEN];/* Longitude axis CTYPE */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ char spectype[MXCTYPELEN];/* Spectral axis CTYPE */ double *cdelt; /* Pointer to CDELT array */ double cdl; /* CDELT term */ double cdlat_lon; /* Off-diagonal CD element */ double cdlon_lat; /* Off-diagonal CD element */ double coscro; /* Cos( CROTA ) */ double crota; /* CROTA value to use */ double epoch; /* Epoch of reference equinox */ double fd; /* Fraction of a day */ double mjd99; /* MJD at start of 1999 */ double rho_a; /* First estimate of CROTA */ double rho_b; /* Second estimate of CROTA */ double sincro; /* Sin( CROTA ) */ double specfactor; /* Factor for converting internal spectral units */ double val; /* General purpose value */ int axlat; /* Index of latitude FITS WCS axis */ int axlon; /* Index of longitude FITS WCS axis */ int axrot1; /* Index of first CROTA rotation axis */ int axrot2; /* Index of second CROTA rotation axis */ int axspec; /* Index of spectral FITS WCS axis */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int m; /* Projection parameter index */ int maxm; /* Max projection parameter index */ int naxis; /* No. of axes */ int ok; /* Is FitsSTore OK for IRAF encoding? */ int prj; /* Projection type */ /* Check the inherited status. */ if( !astOK ) return 0; /* Initialise */ specunit = ""; specfactor = 1.0; maxm = 0; /* First check that the values in the FitsStore conform to the requirements of the AIPS++ encoding. Assume they do to begin with. */ ok = 1; /* Just do primary axes. */ s = ' '; /* Save the number of axes */ naxis = GetMaxJM( &(store->crpix), ' ', status ) + 1; /* Look for the primary celestial and spectral axes. */ FindLonLatSpecAxes( store, s, &axlon, &axlat, &axspec, method, class, status ); /* If both longitude and latitude axes are present ...*/ if( axlon >= 0 && axlat >= 0 ) { /* Get the CTYPE values for both axes. Extract the projection type as specified by the last 4 characters in the latitude CTYPE keyword value. */ cval = GetItemC( &(store->ctype), axlon, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { strcpy( lontype, cval ); } cval = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; prj = AST__WCSBAD; } else { strcpy( lattype, cval ); prj = astWcsPrjType( cval + 4 ); } /* FITS-AIPS++ cannot handle the AST-specific TPN projection. */ if( prj == AST__TPN || prj == AST__WCSBAD ) ok = 0; /* Projection parameters. FITS-AIPS++ encoding ignores projection parameters associated with the longitude axis. The number of parameters is limited to 10. */ maxm = GetMaxJM( &(store->pv), ' ', status ); for( i = 0; i < naxis && ok; i++ ){ if( i != axlon ) { for( m = 0; m <= maxm; m++ ){ val = GetItem( &(store->pv), i, m, s, NULL, method, class, status ); if( val != AST__BAD ) { if( i != axlat || m >= 10 ){ ok = 0; break; } } } } } /* Identify the celestial coordinate system from the first 4 characters of the longitude CTYPE value. Only RA, galactic longitude, and ecliptic longitude can be stored using FITS-AIPS++. */ if( ok && strncmp( lontype, "RA--", 4 ) && strncmp( lontype, "GLON", 4 ) && strncmp( lontype, "ELON", 4 ) ) ok = 0; } /* If a spectral axis is present ...*/ if( axspec >= 0 ) { /* Get the CTYPE values for the axis, and find the AIPS equivalent, if possible. */ cval = GetItemC( &(store->ctype), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { if( !strncmp( cval, "FREQ", astChrLen( cval ) ) ) { strcpy( spectype, "FREQ" ); } else if( !strncmp( cval, "VRAD", astChrLen( cval ) ) ) { strcpy( spectype, "VELO" ); } else if( !strncmp( cval, "VOPT-F2W", astChrLen( cval ) ) ) { strcpy( spectype, "FELO" ); } else { ok = 0; } } /* If OK, check the SPECSYS value and add the AIPS equivalent onto the end of the CTYPE value.*/ cval = GetItemC( &(store->specsys), 0, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { if( !strncmp( cval, "LSRK", astChrLen( cval ) ) ) { strcpy( spectype+4, "-LSR" ); } else if( !strncmp( cval, "LSRD", astChrLen( cval ) ) ) { strcpy( spectype+4, "-LSD" ); } else if( !strncmp( cval, "BARYCENT", astChrLen( cval ) ) ) { strcpy( spectype+4, "-HEL" ); } else if( !strncmp( cval, "GEOCENTR", astChrLen( cval ) ) ) { strcpy( spectype+4, "-GEO" ); } else { ok = 0; } } /* If still OK, ensure the spectral axis units are Hz or m/s. */ cval = GetItemC( &(store->cunit), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else if( ok ) { if( !strcmp( cval, "Hz" ) ) { specunit = "HZ"; specfactor = 1.0; } else if( !strcmp( cval, "kHz" ) ) { specunit = "HZ"; specfactor = 1.0E3; } else if( !strcmp( cval, "MHz" ) ) { specunit = "HZ"; specfactor = 1.0E6; } else if( !strcmp( cval, "GHz" ) ) { specunit = "HZ"; specfactor = 1.0E9; } else if( !strcmp( cval, "m/s" ) ) { specunit = "m/s"; specfactor = 1.0; } else if( !strcmp( cval, "km/s" ) ) { specunit = "m/s"; specfactor = 1.0E3; } else { ok = 0; } } } /* If this is different to the value of NAXIS abort since this encoding does not support WCSAXES keyword. */ if( naxis != store->naxis ) ok = 0; /* Allocate memory to store the CDELT values */ if( ok ) { cdelt = (double *) astMalloc( sizeof(double)*naxis ); if( !cdelt ) ok = 0; } else { cdelt = NULL; } /* Check that rotation is restricted to the celestial plane, and extract the CDELT (diagonal) terms, etc. If there are no celestial axes, restrict rotation to the first two non-spectral axes. */ if( axlat < 0 && axlon < 0 ) { if( axspec >= 0 && naxis > 2 ) { axrot2 = ( axspec == 0 ) ? 1 : 0; axrot1 = axrot2 + 1; if( axrot1 == axspec ) axrot1++; } else if( naxis > 1 ){ axrot2 = 0; axrot1 = 1; } else { axrot2 = -1; axrot1 = -1; } } else { axrot1 = axlon; axrot2 = axlat; } cdlat_lon = 0.0; cdlon_lat = 0.0; for( i = 0; i < naxis && ok; i++ ){ cdl = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdl == AST__BAD ) cdl = 1.0; for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdl; if( i == j ){ cdelt[ i ] = val; } else if( i == axrot2 && j == axrot1 ){ cdlat_lon = val; } else if( i == axrot1 && j == axrot2 ){ cdlon_lat = val; } else if( val != 0.0 ){ ok = 0; } } } /* Find the CROTA and CDELT values for the celestial axes. */ if( ok && axrot1 >= 0 && axrot2 >= 0 ) { if( cdlat_lon > 0.0 ) { rho_a = atan2( cdlat_lon, cdelt[ axrot1 ] ); } else if( cdlat_lon == 0.0 ) { rho_a = 0.0; } else { rho_a = atan2( -cdlat_lon, -cdelt[ axrot1 ] ); } if( cdlon_lat > 0.0 ) { rho_b = atan2( cdlon_lat, -cdelt[ axrot2 ] ); } else if( cdlon_lat == 0.0 ) { rho_b = 0.0; } else { rho_b = atan2( -cdlon_lat, cdelt[ axrot2 ] ); } if( fabs( palDrange( rho_a - rho_b ) ) < 1.0E-2 ){ crota = 0.5*( palDranrm( rho_a ) + palDranrm( rho_b ) ); coscro = cos( crota ); sincro = sin( crota ); if( fabs( coscro ) > fabs( sincro ) ){ cdelt[ axrot2 ] /= coscro; cdelt[ axrot1 ] /= coscro; } else { cdelt[ axrot2 ] = -cdlon_lat/sincro; cdelt[ axrot1 ] = cdlat_lon/sincro; } crota *= AST__DR2D; /* Use AST__BAD to indicate that CDi_j values should be produced instead of CROTA/CDELT. (I am told AIPS++ can understand CD matrices) */ } else { crota = AST__BAD; } } else { crota = 0.0; } /* Get RADECSYS and the reference equinox. */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); epoch = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); /* If RADECSYS was available... */ if( cval ){ /* ICRS is not supported in this encoding. */ if( !strcmp( "ICRS", cval ) ) ok = 0; /* If epoch was not available, set a default epoch. */ if( epoch == AST__BAD ){ if( !strcmp( "FK4", cval ) ){ epoch = 1950.0; } else if( !strcmp( "FK5", cval ) ){ epoch = 2000.0; } else { ok = 0; } /* If an equinox was supplied, check it is consistent with the IAU 1984 rule. */ } else { if( !strcmp( "FK4", cval ) ){ if( epoch >= 1984.0 ) ok = 0; } else if( !strcmp( "FK5", cval ) ){ if( epoch < 1984.0 ) ok = 0; } else { ok = 0; } } } /* Only create the keywords if the FitsStore conforms to the requirements of the FITS-AIPS++ encoding. */ if( ok ) { /* Get and save CRPIX for all pixel axes. These are required, so break if they are not available. */ for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->crpix), 0, j, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { sprintf( combuf, "Reference pixel on axis %d", j + 1 ); SetValue( this, FormatKey( "CRPIX", j + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CRVAL for all intermediate axes. These are required, so break if they are not available. */ for( i = 0; i < naxis && ok; i++ ){ val = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { if( i == axspec ) val *= specfactor; sprintf( combuf, "Value at ref. pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRVAL", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CTYPE for all intermediate axes. These are required, so break if they are not available. Use the potentially modified versions saved above for the celestial axes. */ for( i = 0; i < naxis && ok; i++ ){ if( i == axlat ) { cval = lattype; } else if( i == axlon ) { cval = lontype; } else if( i == axspec ) { cval = spectype; } else { cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); } if( cval && ( strlen(cval) < 5 || strcmp( cval + 4, "-TAB" ) ) ) { comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } SetValue( this, FormatKey( "CTYPE", i + 1, -1, s, status ), &cval, AST__STRING, comm, status ); } else { ok = 0; } } /* CDELT values */ if( axspec != -1 ) cdelt[ axspec ] *= specfactor; for( i = 0; i < naxis; i++ ){ SetValue( this, FormatKey( "CDELT", i + 1, -1, s, status ), cdelt + i, AST__FLOAT, "Pixel size", status ); } /* CUNIT values. [Spectral axis units should be upper-case] */ for( i = 0; i < naxis; i++ ) { cval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( cval ) { if( i == axspec ) cval = specunit; sprintf( combuf, "Units for axis %d", i + 1 ); SetValue( this, FormatKey( "CUNIT", i + 1, -1, s, status ), &cval, AST__STRING, combuf, status ); } } /* CD matrix. Multiply the row of the PC matrix by the CDELT value. */ if( crota == AST__BAD ) { for( i = 0; i < naxis; i++ ) { cdl = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdl == AST__BAD ) cdl = 1.0; for( j = 0; j < naxis; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdl; if( val != 0.0 ) { SetValue( this, FormatKey( "CD", i + 1, j + 1, s, status ), &val, AST__FLOAT, "Transformation matrix element", status ); } } } /* CROTA */ } else if( crota != 0.0 ) { if( axrot2 != -1 ){ SetValue( this, FormatKey( "CROTA", axrot2 + 1, -1, s, status ), &crota, AST__FLOAT, "Axis rotation", status ); } else if( ( axspec == -1 && naxis > 1 ) || ( axspec != -1 && naxis > 2 ) ) { SetValue( this, "CROTA1", &crota, AST__FLOAT, "Axis rotation", status ); } } /* Reference equinox */ if( epoch != AST__BAD ) SetValue( this, "EPOCH", &epoch, AST__FLOAT, "Epoch of reference equinox", status ); /* Latitude of native north pole. */ val = GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "LATPOLE", &val, AST__FLOAT, "Latitude of native north pole", status ); /* Longitude of native north pole. */ val = GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "LONPOLE", &val, AST__FLOAT, "Longitude of native north pole", status ); /* Date of observation. */ val = GetItem( &(store->mjdobs), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD ) { /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", (void *) &cval, AST__STRING, "Date of observation", status ); } /* Projection parameters. */ if( axlat >= 0 && axlon >= 0 ) { for( m = 0; m <= maxm; m++ ){ val = GetItem( &(store->pv), axlat, m, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "PROJP", m, -1, ' ', status ), &val, AST__FLOAT, "Projection parameter", status ); } } /* Spectral stuff.. */ if( axspec >= 0 ) { /* Rest frequency */ val = GetItem( &(store->restfrq), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "RESTFREQ", -1, -1, s, status ), &val, AST__FLOAT, "[Hz] Rest frequency", status ); } } /* Release CDELT workspace */ if( cdelt ) cdelt = (double *) astFree( (void *) cdelt ); /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ok : 0; } static char *CardComm( AstFitsChan *this, int *status ){ /* * Name: * CardComm * Purpose: * Return the keyword comment from the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *CardComm( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a pointer to a string holding the keyword comment from the * current card. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the keyword comment, or NULL if the FitsChan is at * end-of-file, or does not have a comment. * Notes: * - The current card is not changed by this function. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ char *ret; /* Check the supplied object. */ if( !this ) return NULL; /* If the current card is defined, store a pointer to its keyword comment. */ if( this->card ){ ret = ( (FitsCard *) this->card )->comment; /* Otherwise store a NULL pointer. */ } else { ret = NULL; } /* Return the answer. */ return ret; } static void *CardData( AstFitsChan *this, size_t *size, int *status ){ /* * Name: * CardData * Purpose: * Return a pointer to the keyword data value for the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void *CardData( AstFitsChan *this, size_t *size, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a pointer to keyword data value from the current card. * Parameters: * this * Pointer to the FitsChan. * size * A pointer to a location at which to return the number of bytes * occupied by the data value. NULL can be supplied if this * information is not required. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the keyword data, or NULL if the FitsChan is at * end-of-file, or if the keyword does not have any data. * Notes: * - For text data, the returned value for "size" includes the * terminating null character. * - The current card is not changed by this function. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ void *ret; /* Check the supplied object. */ if( !this ) return NULL; /* If the current card is defined, store a pointer to its keyword data. */ if( this->card ){ ret = ( (FitsCard *) this->card )->data; if( size ) *size = ( (FitsCard *) this->card )->size; /* Otherwise store a NULL pointer. */ } else { ret = NULL; if( size ) *size = 0; } /* Return the answer. */ return ret; } static int *CardFlags( AstFitsChan *this, int *status ){ /* * Name: * CardFlags * Purpose: * Return a pointer to the flags mask for the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int *CardFlags( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a pointer to the flags mask for the current card. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The pointer to the flags mask. * Notes: * - The current card is not changed by this function. * - NULL is returned if the current card is not defined. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ int *ret; /* Check the supplied object. */ if( !this ) return NULL; /* If the current card is defined, store its deletion flag. */ if( this->card ){ ret = &( ( (FitsCard *) this->card )->flags ); /* Otherwise store zero. */ } else { ret = NULL; } /* Return the answer. */ return ret; } static char *CardName( AstFitsChan *this, int *status ){ /* * Name: * CardName * Purpose: * Return the keyword name from the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *CardName( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a pointer to a string holding the keyword name from the * current card. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the keyword name, or NULL if the FitsChan is at * end-of-file. * Notes: * - The current card is not changed by this function. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ char *ret; /* Check the supplied object. */ if( !this ) return NULL; /* If the current card is defined, store a pointer to its keyword name. */ if( this->card ){ ret = ( (FitsCard *) this->card )->name; /* Otherwise store a NULL pointer. */ } else { ret = NULL; } /* Return the answer. */ return ret; } static int CardType( AstFitsChan *this, int *status ){ /* * Name: * CardType * Purpose: * Return the keyword type from the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int CardType( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns the keyword type from the current card. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The keyword type. * Notes: * - The current card is not changed by this function. * - AST__NOTYPE is returned if the current card is not defined. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ int ret; /* Check the supplied object. */ if( !this ) return AST__NOTYPE; /* If the current card is defined, store the keyword type. */ if( this->card ){ ret = ( (FitsCard *) this->card )->type; /* Otherwise store AST__NOTYPE. */ } else { ret = AST__NOTYPE; } /* Return the answer. */ return ret; } static AstMapping *CelestialAxes( AstFitsChan *this, AstFrameSet *fs, double *dim, int *wperm, char s, FitsStore *store, int *axis_done, int isoff, const char *method, const char *class, int *status ){ /* * Name: * CelestialAxes * Purpose: * Add values to a FitsStore describing celestial axes in a Frame. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *CelestialAxes( AstFitsChan *this, AstFrameSet *fs, double *dim, * int *wperm, char s, FitsStore *store, int *axis_done, * int isoff, const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The current Frame of the supplied FrameSet is searched for celestial * axes. If any are found, FITS WCS keyword values describing the axis * are added to the supplied FitsStore, if possible (the conventions * of FITS-WCS paper II are used). Note, this function does not store * values for keywords which define the transformation from pixel * coords to Intermediate World Coords (CRPIX, PC and CDELT), but a * Mapping is returned which embodies these values. This Mapping is * from the current Frame in the FrameSet (WCS coords) to a Frame * representing IWC. The IWC Frame has the same number of axes as the * WCS Frame which may be greater than the number of base Frame (i.e. * pixel) axes. * Parameters: * this * Pointer to the FitsChan. * fs * Pointer to the FrameSet. The base Frame should represent FITS pixel * coordinates, and the current Frame should represent FITS WCS * coordinates. The number of base Frame axes should not exceed the * number of current Frame axes. * dim * An array holding the image dimensions in pixels. AST__BAD can be * supplied for any unknown dimensions. * wperm * Pointer to an array of integers with one element for each axis of * the current Frame. Each element holds the zero-based * index of the FITS-WCS axis (i.e. the value of "i" in the keyword * names "CTYPEi", "CRVALi", etc) which describes the Frame axis. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * store * The FitsStore in which to store the FITS WCS keyword values. * axis_done * An array of flags, one for each Frame axis, which indicate if a * description of the corresponding axis has yet been stored in the * FitsStore. * isoff * If greater than zero, the description to add to the FitsStore * should describe offset coordinates. If less than zero, the * description to add to the FitsStore should describe absolute * coordinates but should include the SkyRefIs, SkyRef and SkyRefP * attributes. If zero, ignore all offset coordinate info. The * absolute value indicates the nature of the reference point: * 1 == "pole", 2 == "origin", otherwise "ignored". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * If celestial axes were found which can be described using the * conventions of FITS-WCS paper II, then a Mapping from the current Frame * of the supplied FrameSet, to the IWC Frame is returned. Otherwise, * a UnitMap is returned. Note, the Mapping only defines the IWC * transformation for celestial axes. Any non-celestial axes are passed * unchanged by the returned Mapping. */ /* Local Variables: */ AstFitsTable *table; /* Pointer to structure holding -TAB table info */ AstFrame *pframe; /* Primary Frame containing current WCS axis*/ AstFrame *wcsfrm; /* WCS Frame within FrameSet */ AstMapping *map1; /* Pointer to pre-WcsMap Mapping */ AstMapping *map3; /* Pointer to post-WcsMap Mapping */ AstMapping *map; /* Pixel -> WCS mapping */ AstMapping *ret; /* Returned Mapping */ AstMapping *tmap0; /* A temporary Mapping */ AstMapping *tmap1; /* A temporary Mapping */ AstMapping *tmap2; /* A temporary Mapping */ AstMapping *tmap3; /* A temporary Mapping */ AstMapping *tmap4; /* A temporary Mapping */ AstSkyFrame *skyfrm; /* The SkyFrame defining current WCS axis */ AstWcsMap *map2; /* Pointer to WcsMap */ AstWcsMap *map2b; /* Pointer to WcsMap with cleared lat/lonpole */ char *cval; /* Pointer to keyword value */ char *temp; /* Pointer to temporary string */ double *mat; /* Pointer to matrix diagonal elements */ double *ppcfid; /* Pointer to array holding PPC at fiducial point */ double con; /* Constant value for unassigned axes */ double crval[ 2 ]; /* Psi coords of reference point */ double pv; /* Projection parameter value */ double skyfid[ 2 ]; /* Sky coords of fiducial point */ double val; /* Keyword value */ int *inperm; /* Input axis permutation array */ int *outperm; /* Output axis permutation array */ int *tperm; /* Pointer to new FITS axis numbering array */ int axlat; /* Index of latitude output from WcsMap */ int axlon; /* Index of longitude output from WcsMap */ int extver; /* Table version number for -TAB headers */ int fits_ilat; /* FITS WCS axis index for latitude axis */ int fits_ilon; /* FITS WCS axis index for longitude axis */ int i; /* Loop index */ int iax; /* Axis index */ int icolindexlat; /* Index of table column holding lat index vector */ int icolindexlon; /* Index of table column holding lon index vector */ int icolmainlat; /* Index of table column holding main lat coord array */ int icolmainlon; /* Index of table column holding main lon coord array */ int interplat; /* INterpolation method for latitude look-up tables */ int interplon; /* INterpolation method for longitude look-up tables */ int ilat; /* Index of latitude axis within total WCS Frame */ int ilon; /* Index of longitude axis within total WCS Frame */ int j; /* Loop index */ int m; /* Projection parameter index */ int maxm; /* Largest used "m" value */ int mlat; /* Index of latitude axis in main lat coord array */ int mlon; /* Index of longitude axis in main lon coord array */ int nwcs; /* Number of WCS axes */ int nwcsmap; /* Number of inputs/outputs for the WcsMap */ int paxis; /* Axis index within primary Frame */ int skylataxis; /* Index of latitude axis within SkyFrame */ int skylonaxis; /* Index of longitude axis within SkyFrame */ int tpn; /* Is the WCS projectiona TPN projection? */ /* Initialise */ ret = NULL; /* Other initialisation to avoid compiler warnings. */ mlon = 0; mlat = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Get a pointer to the WCS Frame. */ wcsfrm = astGetFrame( fs, AST__CURRENT ); /* Store the number of WCS axes. */ nwcs = astGetNout( fs ); /* Check each axis in the WCS Frame to see if it is a celestial axis. */ skyfrm = NULL; map = NULL; ilon = -1; ilat = -1; for( iax = 0; iax < nwcs; iax++ ) { /* Obtain a pointer to the primary Frame containing the current WCS axis. */ astPrimaryFrame( wcsfrm, iax, &pframe, &paxis ); /* If the current axis belongs to a SkyFrame, we have found a celestial axis. Keep a pointer to it, and note the indices of the celestial axes within the complete WCS Frame. The MakeFitsFrameSet function will have ensured that the WCS Frame only contains at most a single SkyFrame. */ if( IsASkyFrame( pframe ) ) { if( !skyfrm ) skyfrm = astClone( pframe ); if( paxis == 0 ) { ilon = iax; } else { ilat = iax; } /* Indicate that this axis has been classified. */ axis_done[ iax ] = 1; } /* Release resources. */ pframe = astAnnul( pframe ); } /* Only proceed if we found celestial axes. */ if( ilon != -1 && ilat != -1 ) { /* Note the FITS WCS axis indices for the longitude and latitude axes */ fits_ilon = wperm[ ilon ]; fits_ilat = wperm[ ilat ]; /* Create an array to hold the Projection Plane Coords corresponding to the CRVALi keywords. */ ppcfid = (double *) astMalloc( sizeof( double )*nwcs ); /* Get the pixel->wcs Mapping. */ map = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Get the table version number to use if we end up using the -TAB algorithm. This is the set value of the TabOK attribute (if positive). */ extver = astGetTabOK( this ); /* Some of the required FITS Keyword values are defined by the WcsMap contained within the Mapping. Split the mapping up into a list of serial component mappings, and locate the first WcsMap in this list. The first Mapping returned by this call is the result of compounding all the Mappings up to (but not including) the WcsMap, the second returned Mapping is the (inverted) WcsMap, and the third returned Mapping is anything following the WcsMap. Only proceed if one and only one WcsMap is found. */ if( SplitMap( map, astGetInvert( map ), ilon, ilat, &map1, &map2, &map3, status ) ){ /* Get the indices of the latitude and longitude axes within the SkyFrame (not necessarily (1,0) because they may have been permuted). */ skylataxis = astGetLatAxis( skyfrm ); skylonaxis = astGetLonAxis( skyfrm ); /* The reference point in the celestial coordinate system is found by transforming the fiducial point in native spherical co-ordinates into WCS coordinates using map3. */ if( GetFiducialWCS( map2, map3, ilon, ilat, skyfid + skylonaxis, skyfid + skylataxis, status ) ){ /* We also need to find the indices of the longitude and latitude outputs from the WcsMap. These may not be the same as ilat and ilon because of axis permutations in "map3". */ axlon = astGetWcsAxis( map2, 0 ); axlat = astGetWcsAxis( map2, 1 ); /* Normalise the latitude and longitude values at the fiducial point. The longitude and latitude values found above will be in radians, but after normalization we convert them to degrees, as expected by other functions which handle FitsStores. */ if( skyfid[ skylonaxis ] == AST__BAD ) skyfid[ skylonaxis ] = 0.0; if( skyfid[ skylataxis ] == AST__BAD ) skyfid[ skylataxis ] = 0.0; if( ZEROANG( skyfid[ 0 ] ) ) skyfid[ 0 ] = 0.0; if( ZEROANG( skyfid[ 1 ] ) ) skyfid[ 1 ] = 0.0; astNorm( skyfrm, skyfid ); SetItem( &(store->crval), fits_ilon, 0, s, AST__DR2D*skyfid[ skylonaxis ], status ); SetItem( &(store->crval), fits_ilat, 0, s, AST__DR2D*skyfid[ skylataxis ], status ); /* Set a flag if we have a TPN projection. This is an AST-specific projection which mimicks the old "TAN with correction terms" projection which was removed from the final version of the FITS-WCS paper II. */ tpn = ( astGetWcsType( map2 ) == AST__TPN ); /* Store the WCS projection parameters. Except for TPN projections, always exclude parameters 3 and 4 on the longitude axis since these are reserved to hold copies of LONPOLE and LATPOLE. */ for( m = 0; m < WCSLIB_MXPAR; m++ ){ if( astTestPV( map2, axlon, m ) ) { if( m < 3 || m > 4 || tpn ) { pv = astGetPV( map2, axlon, m ); if( pv != AST__BAD ) SetItem( &(store->pv), fits_ilon, m, s, pv, status ); } } if( astTestPV( map2, axlat, m ) ) { pv = astGetPV( map2, axlat, m ); if( pv != AST__BAD ) SetItem( &(store->pv), fits_ilat, m, s, pv, status ); } } /* If PVi_0 (for the longitude axis) is non-zero, the Cartesian coordinates used by the WcsMap (Projection Plane Coordinates, PPC) need to be shifted to produce Intermediate World Coordinates (IWC). This shift results in the pixel reference position specified by the CRPIXi values (and which corresponds to the origin of IWC) mapping on to the fiducial position specified by the CRVALi values. The required shifts are just the PPC coordinates of the fiducial point. The AST-specific "TPN" projection uses longitude projection parameters to define correction terms, and so cannot use the above convention (which is part of FITS-WCS paper II). Therefore TPN projections always use zero shift between PPC and IWC. */ for( iax = 0; iax < nwcs; iax++ ) ppcfid[ iax ] = 0.0; if( !tpn && astGetPV( map2, axlon, 0 ) != 0.0 ) { GetFiducialPPC( (AstWcsMap *) map2, ppcfid + ilon, ppcfid + ilat, status ); if( ppcfid[ ilon ] == AST__BAD ) ppcfid[ ilon ] = 0.0; if( ppcfid[ ilat ] == AST__BAD ) ppcfid[ ilat ] = 0.0; ppcfid[ ilon ] *= AST__DR2D; ppcfid[ ilat ] *= AST__DR2D; } /* Store the CTYPE, CNAME, EQUINOX, MJDOBS, and RADESYS values. */ SkySys( this, skyfrm, 1, astGetWcsType( map2 ), store, fits_ilon, fits_ilat, s, isoff, method, class, status ); /* Store the LONPOLE and LATPOLE values in the FitsStore. */ SkyPole( map2, map3, ilon, ilat, wperm, s, store, method, class, status ); /* The values of LONPOLE and LATPOLE stored above (in the FitsStore) will be ignored by WcsNative if the WcsMap contains set values for projection parameters PVi_3a and/or PVi_4a (these will be used in preference to the values in the FitsStore). To avoid this happening we take a copy of the WcsMap and clear the relevant parameters (but not if the WcsMap is for a TPN projection because TPN uses PVi_3a and PVi_4a for other purposes). */ if( astGetWcsType( map2 ) != AST__TPN ) { map2b = astCopy( map2 ); astClearPV( map2b, axlon, 3 ); astClearPV( map2b, axlon, 4 ); } else { map2b = astClone( map2 ); } /* We will now create the Mapping from WCS coords to IWC coords. In fact, we produce the Mapping from IWC to WCS and then invert it. Create the first component of this Mapping which implements any shift of origin from IWC to PPC. */ tmap0 = (AstMapping *) astShiftMap( nwcs, ppcfid, "", status ); /* The next component of this Mapping scales the PPC coords from degrees to radians on the celestial axes. */ mat = astMalloc( sizeof( double )*(size_t) nwcs ); if( astOK ) { for( iax = 0; iax < nwcs; iax++ ) mat[ iax ] = 1.0; mat[ ilon ] = AST__DD2R; mat[ ilat ] = AST__DD2R; tmap1 = (AstMapping *) astMatrixMap( nwcs, nwcs, 1, mat, "", status ); mat = astFree( mat ); } else { tmap1 = NULL; } /* Now create the Mapping from Native Spherical Coords to WCS. */ tmap2 = WcsNative( NULL, store, s, map2b, fits_ilon, fits_ilat, method, class, status ); /* Combine the WcsMap with the above Mapping, to get the Mapping from PPC to WCS. */ tmap3 = (AstMapping *) astCmpMap( map2b, tmap2, 1, "", status ); tmap2 = astAnnul( tmap2 ); /* If there are more WCS axes than IWC axes, create a UnitMap for the extra WCS axes and add it in parallel with tmap3. */ nwcsmap = astGetNin( map3 ); if( nwcsmap < nwcs ) { tmap2 = (AstMapping *) astUnitMap( nwcs - nwcsmap, "", status ); tmap4 = (AstMapping *) astCmpMap( tmap3, tmap2, 0, "", status ); tmap3 = astAnnul( tmap3 ); tmap2 = astAnnul( tmap2 ); tmap3 = tmap4; nwcsmap = nwcs; } /* The pixel->wcs mapping may include a PermMap which selects some sub-set or super-set of the orignal WCS axes. In this case the number of inputs and outputs for "tmap3" created above may not equal "nwcs". To avoid this, we embed "tmap3" between 2 PermMaps which select the required axes. */ if( nwcsmap != nwcs || ilon != axlon || ilat != axlat ) { inperm = astMalloc( sizeof( int )*(size_t) nwcs ); outperm = astMalloc( sizeof( int )*(size_t) nwcsmap ); if( astOK ) { /* Indicate that no inputs of the PermMap have yet been assigned to any outputs */ for( i = 0; i < nwcs; i++ ) inperm[ i ] = -1; /* Assign the WcsMap long/lat axes to the WCS Frame long/lat axes */ inperm[ ilon ] = axlon; inperm[ ilat ] = axlat; /* Assign the remaining inputs arbitrarily (doesn't matter how we do this since the WcsMap is effectively a UnitMap on all non-celestial axes). */ iax = 0; for( i = 0; i < nwcs; i++ ) { while( iax == axlon || iax == axlat ) iax++; if( inperm[ i ] == -1 ) inperm[ i ] = iax++; } /* Do the same for the outputs. */ for( i = 0; i < nwcsmap; i++ ) outperm[ i ] = -1; outperm[ axlon ] = ilon; outperm[ axlat ] = ilat; iax = 0; for( i = 0; i < nwcsmap; i++ ) { while( iax == ilon || iax == ilat ) iax++; if( outperm[ i ] == -1 ) outperm[ i ] = iax++; } /* Create the PermMap. */ con = AST__BAD; tmap2 = (AstMapping *) astPermMap( nwcs, inperm, nwcsmap, outperm, &con, "", status ); /* Sandwich the WcsMap between the PermMap and its inverse. */ tmap4 = (AstMapping *) astCmpMap( tmap2, tmap3, 1, "", status ); tmap3 = astAnnul( tmap3 ); astInvert( tmap2 ); tmap3 = (AstMapping *) astCmpMap( tmap4, tmap2, 1, "", status ); tmap2 = astAnnul( tmap2 ); tmap4 = astAnnul( tmap4 ); } inperm = astFree( inperm ); outperm = astFree( outperm ); } /* Combine these Mappings together. */ tmap4 = (AstMapping *) astCmpMap( tmap0, tmap1, 1, "", status ); tmap0 = astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); ret = (AstMapping *) astCmpMap( tmap4, tmap3, 1, "", status ); tmap3 = astAnnul( tmap3 ); tmap4 = astAnnul( tmap4 ); /* Invert this Mapping to get the Mapping from WCS to IWC. */ astInvert( ret ); /* The spherical rotation involved in converting WCS to IWC can result in inappropriate numbering of the FITS axes. For instance, a LONPOLE value of 90 degrees causes the IWC axes to be transposed. For this reason we re-asses the FITS axis numbers assigned to the celestial axes in order to make the IWC axes as close as possible to the pixel axes with the same number (but only if the axis order is being determined automatically). To do this, we need the Mapping from pixel to IWC, which is formed by concatenating the pixel->WCS Mapping with the WCS->IWC Mapping. */ if( astChrMatch( astGetFitsAxisOrder( this ), "" ) ) { tmap0 = (AstMapping *) astCmpMap( map, ret, 1, "", status ); /* Find the outputs of this Mapping which should be associated with each input. */ tperm = astMalloc( sizeof(int)*(size_t) nwcs ); if( ! WorldAxes( this, tmap0, dim, tperm, status ) ) { ret = astAnnul( ret ); } /* If the index associated with the celestial axes appear to have been swapped... */ if( ret && astOK && fits_ilon == tperm[ ilat ] && fits_ilat == tperm[ ilon ] ) { /* Swap the fits axis indices associated with each WCS axis to match. */ wperm[ ilon ] = fits_ilat; wperm[ ilat ] = fits_ilon; /* Swap the stored CRVAL value for the longitude and latitude axis. */ val = GetItem( &(store->crval), fits_ilat, 0, s, NULL, method, class, status ); SetItem( &(store->crval), fits_ilat, 0, s, GetItem( &(store->crval), fits_ilon, 0, s, NULL, method, class, status ), status ); SetItem( &(store->crval), fits_ilon, 0, s, val, status ); /* Swap the stored CTYPE value for the longitude and latitude axis. */ cval = GetItemC( &(store->ctype), fits_ilat, 0, s, NULL, method, class, status ); if( cval ) { temp = astStore( NULL, (void *) cval, strlen( cval ) + 1 ); cval = GetItemC( &(store->ctype), fits_ilon, 0, s, NULL, method, class, status ); if( cval ) { SetItemC( &(store->ctype), fits_ilat, 0, s, cval, status ); SetItemC( &(store->ctype), fits_ilon, 0, s, temp, status ); } temp = astFree( temp ); } /* Swap the stored CNAME value for the longitude and latitude axis. */ cval = GetItemC( &(store->cname), fits_ilat, 0, s, NULL, method, class, status ); if( cval ) { temp = astStore( NULL, (void *) cval, strlen( cval ) + 1 ); cval = GetItemC( &(store->cname), fits_ilon, 0, s, NULL, method, class, status ); if( cval ) { SetItemC( &(store->cname), fits_ilat, 0, s, cval, status ); SetItemC( &(store->cname), fits_ilon, 0, s, temp, status ); } temp = astFree( temp ); } /* Swap the projection parameters asociated with the longitude and latitude axes. */ maxm = GetMaxJM( &(store->pv), s, status ); for( m = 0; m <= maxm; m++ ){ val = GetItem( &(store->pv), fits_ilat, m, s, NULL, method, class, status ); SetItem( &(store->pv), fits_ilat, m, s, GetItem( &(store->pv), fits_ilon, m, s, NULL, method, class, status ), status ); SetItem( &(store->pv), fits_ilon, m, s, val, status ); } } /* Release resources. */ tperm = astFree( tperm ); tmap0 = astAnnul( tmap0 ); } map2b = astAnnul( map2b ); } /* Release resources. */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); /* If no WcsMap was found in the pixel->WCS Mapping, it may be possible to describe the celestial axes using a tabular look-up table (i.e. the FITS-WCS "_TAB" algorithm). Only do this if the -TAB algorithm is to be supported. */ } else if( extver > 0 ) { /* Get any pre-existing FitsTable from the FitsStore. This is the table in which the tabular data will be stored (if the Mapping can be expressed in -TAB form). */ if( !astMapGet0A( store->tables, AST_TABEXTNAME, &table ) ) table = NULL; /* See if the transformations for the celestial axes can be expressed in -TAB form. The returned Mapping (if any) is the Mapping from (lon,lat) (rads) to (psi_lon,psi_lat) (pixels). See FITS-WCS paper III section 6.1.2 for definition of psi. Scale the values stored in the table from radians to degrees. */ tmap0 = IsMapTab2D( map, AST__DR2D, "deg", wcsfrm, dim, ilon, ilat, fits_ilon, fits_ilat, &table, &icolmainlon, &icolmainlat, &icolindexlon, &icolindexlat, &mlon, &mlat, &interplon, &interplat, status ); if( tmap0 ) { /* Store the CTYPE, CNAME, EQUINOX, MJDOBS, and RADESYS values. */ SkySys( this, skyfrm, 0, 0, store, fits_ilon, fits_ilat, s, isoff, method, class, status ); /* If possible, choose the two CRVAL values (which are values on the psi axes) so that transforming them using the Mapping returned by IsMapTab2D gives the sky reference position stored in the SkyFrame. Check the SkyFrame has a defined reference position. */ if( astTestSkyRef( skyfrm, 0 ) && astTestSkyRef( skyfrm, 1 ) ){ /* Get the longitude and latitude at the reference point in radians. */ skyfid[ 0 ] = astGetSkyRef( skyfrm, astGetLonAxis( skyfrm )); skyfid[ 1 ] = astGetSkyRef( skyfrm, astGetLatAxis( skyfrm )); /* We use the WCS->psi Mapping to convert the reference point WCS coords (rads) into psi coords (pixels). We can only do this if the WCS->psi Mapping has a defined forward transformation. */ if( astGetTranForward( tmap0 ) ) { astTran2( tmap0, 1, skyfid, skyfid + 1, 1, crval, crval + 1 ); /* If the WCS->psi mapping has an undefined forward transformation, then just store the sky reference point coords (in degs) in keywords AXREFn, and use 1.0 for the CRVAL values, so that IWC becomes equal to (psi-1) i.e. (grid coords - 1). This means the reference point is at grid coords (1.0,1.0). Note this choice of 1.0 for CRVAL is not arbitrary since it is required by the trick used to create invertable CD matrix in function MakeInvertable. */ } else { SetItem( &(store->axref), fits_ilon, 0, s, AST__DR2D*skyfid[ 0 ], status ); SetItem( &(store->axref), fits_ilat, 0, s, AST__DR2D*skyfid[ 1 ], status ); crval[ 0 ] = 1.0; crval[ 1 ] = 1.0; } /* If the SkyFrame has no reference position, use 1.0 for the CRVAL values. */ } else { crval[ 0 ] = 1.0; crval[ 1 ] = 1.0; } /* Create a Mapping that describes the transformation from the lon and lat psi axes to the lon and lat IWC axes (i.e. a ShiftMap that just subtracts the CRVAL values from each axis). */ crval[ 0 ] = -crval[ 0 ]; crval[ 1 ] = -crval[ 1 ]; tmap1 = (AstMapping *) astShiftMap( 2, crval, " ", status ); crval[ 0 ] = -crval[ 0 ]; crval[ 1 ] = -crval[ 1 ]; /* Create a series compound Mapping that applies the Mapping returned by IsMapTab2D first (the Mapping from WCS to psi), followed by the Mapping from psi to IWC created above. There-after, use this compound Mapping in place of the Mapping returned by IsMapTab2D. It maps WCS to IWC. */ tmap2 = (AstMapping *) astCmpMap( tmap0, tmap1, 1, " ", status ); (void) astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); tmap0 = tmap2; /* Store the CRVAL values */ SetItem( &(store->crval), fits_ilon, 0, s, crval[ 0 ], status ); SetItem( &(store->crval), fits_ilat, 0, s, crval[ 1 ], status ); /* Store TAB-specific values in the FitsStore. First the name of the FITS binary table extension holding the coordinate info. */ SetItemC( &(store->ps), fits_ilon, 0, s, AST_TABEXTNAME, status ); SetItemC( &(store->ps), fits_ilat, 0, s, AST_TABEXTNAME, status ); /* Next the table version number. This is the set (positive) value for the TabOK attribute. */ SetItem( &(store->pv), fits_ilon, 1, s, extver, status ); SetItem( &(store->pv), fits_ilat, 1, s, extver, status ); /* Also store the table version in the binary table header. */ astSetFitsI( table->header, "EXTVER", extver, "Table version number", 0 ); /* Next the name of the table column containing the main coords array. */ SetItemC( &(store->ps), fits_ilon, 1, s, astColumnName( table, icolmainlon ), status ); SetItemC( &(store->ps), fits_ilat, 1, s, astColumnName( table, icolmainlat ), status ); /* Next the name of the column containing the index array. */ if( icolindexlon >= 0 ) SetItemC( &(store->ps), fits_ilon, 2, s, astColumnName( table, icolindexlon ), status ); if( icolindexlat >= 0 ) SetItemC( &(store->ps), fits_ilat, 2, s, astColumnName( table, icolindexlat ), status ); /* The one-based index of the axes within the coordinate array that describes FITS WCS axes "fits_ilon" and "fits_ilat". */ SetItem( &(store->pv), fits_ilon, 3, s, mlon, status ); SetItem( &(store->pv), fits_ilat, 3, s, mlat, status ); /* The interpolation method (an AST extension to the published -TAB algorithm, communicated through the QVi_4a keyword). */ SetItem( &(store->pv), fits_ilon, 4, s, interplon, status ); SetItem( &(store->pv), fits_ilat, 4, s, interplat, status ); /* Also store the FitsTable itself in the FitsStore. */ astMapPut0A( store->tables, AST_TABEXTNAME, table, NULL ); /* Allocate space for the arrays that define the permutations required for the inputs and outputs of a PermMap. */ inperm = astMalloc( sizeof( double )*nwcs ); outperm = astMalloc( sizeof( double )*nwcs ); if( astOK ) { /* Create the WCS -> IWC Mapping. First create a parallel CmpMap that combines the Mapping returned by IsMapTab2D (which transforms the celestial axes), with a UnitMap which transforms the non-celestial axes. */ if( nwcs > 2 ) { tmap1 = (AstMapping *) astUnitMap( nwcs - 2, " ", status ); tmap2 = (AstMapping *) astCmpMap( tmap0, tmap1, 0, " ", status ); tmap1 = astAnnul( tmap1 ); } else { tmap2 = astClone( tmap0 ); } /* Now create a PermMap that permutes the inputs of this CmpMap into the order of the axes in the WCS Frame. */ outperm[ 0 ] = ilon; outperm[ 1 ] = ilat; j = 0; for( i = 2; i < nwcs; i++ ) { while( j == ilon || j == ilat ) j++; outperm[ i ] = j++; } for( i = 0; i < nwcs; i++ ) inperm[ outperm[ i ] ] = i; tmap1 = (AstMapping *) astPermMap( nwcs, inperm, nwcs, outperm, NULL, " ", status ); /* Use this PermMap (and its inverse) to permute the inputs (and outputs) of the parallel CmpMap created above. */ tmap3 = (AstMapping *) astCmpMap( tmap1, tmap2, 1, " ", status ); tmap2 = astAnnul( tmap2 ); astInvert( tmap1 ); tmap2 = (AstMapping *) astCmpMap( tmap3, tmap1, 1, " ", status ); tmap1 = astAnnul( tmap1 ); tmap3 = astAnnul( tmap3 ); /* Now create a PermMap that permutes the WCS axes into the FITS axis order. */ for( i = 0; i < nwcs; i++ ) { inperm[ i ] = wperm[ i ]; outperm[ wperm[ i ] ] = i; } tmap1 = (AstMapping *) astPermMap( nwcs, inperm, nwcs, outperm, NULL, "", status ); /* Use this PermMap to permute the outputs of the "tmap2" Mapping. The resulting Mapping is the Mapping from the current Frame to IWC and is the Mapping to be returned as the function value. */ ret = (AstMapping *) astCmpMap( tmap2, tmap1, 1, " ", status ); tmap1 = astAnnul( tmap1 ); tmap2 = astAnnul( tmap2 ); } /* Free remaining resources. */ inperm = astFree( inperm ); outperm = astFree( outperm ); tmap0 = astAnnul( tmap0 ); } if( table ) table = astAnnul( table ); } /* Release resources. */ ppcfid = astFree( ppcfid ); } /* Release resources. */ wcsfrm = astAnnul( wcsfrm ); if( skyfrm ) skyfrm = astAnnul( skyfrm ); if( map ) map = astAnnul( map ); /* If we have a Mapping to return, simplify it. Otherwise, create a UnitMap to return. */ if( ret ) { tmap0 = ret; ret = astSimplify( tmap0 ); tmap0 = astAnnul( tmap0 ); } else { ret = (AstMapping *) astUnitMap( nwcs, "", status ); } /* Return the result. */ return ret; } static void ChangePermSplit( AstMapping *map, int *status ){ /* * Name: * ChangePermSplit * Purpose: * Change all PermMaps in a Mapping to use the alternate * implementation of the astMapSplit method. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void ChangePermSplit( AstMapping *map, int *status ) * Class Membership: * FitsChan member function. * Description: * The PemMap class provides two implementations of the astMapSplit * method. The implementation used by each PermMap is determined by * the value of the PermMap's "PermSplit" attribute. This function * searches the supplied Mapping for any PermMaps, and set their * PermSplit attribute to 1, indicating that the alternate * implementation of astMapSplit should be used. * Parameters: * map * Pointer to the Mapping. Modified on exit by setting all * PermSplit attributes to 1. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMapping *map1; AstMapping *map2; int series; int invert1; int invert2; /* Check inherited status */ if( !astOK ) return; /* If the supplied Mapping is a PermMap, set its PermSplit attribute non-zero. */ if( astIsAPermMap( map ) ) { astSetPermSplit( map, 1 ); /* If the supplied Mapping is not a PermMap, attempt to decompose the Mapping into two component Mappings. */ } else { astDecompose( map, &map1, &map2, &series, &invert1, &invert2 ); /* If the Mapping could be decomposed, use this function recursively to set the PermSplit attributes in each component Mapping. */ if( map1 && map2 ) { ChangePermSplit( map1, status ); ChangePermSplit( map2, status ); /* Annul the component Mappings. */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } else if( map1 ) { map1 = astAnnul( map1 ); } else if( map2 ) { map2 = astAnnul( map2 ); } } } static double *Cheb2Poly( double *c, int nx, int ny, double xmin, double xmax, double ymin, double ymax, int *status ){ /* * Name: * Cheb2Poly * Purpose: * Converts a two-dimensional Chebyshev polynomial to standard form and * scale the arguments. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double *Cheb2Poly( double *c, int nx, int ny, double xmin, double xmax, * double ymin, double ymax, int *status ) * Class Membership: * FitsChan * Description: * Given the coefficients of a two-dimensional Chebychev polynomial P(u,v), * find the coefficients of the equivalent standard two-dimensional * polynomial Q(x,y). The allowed range of u and v is assumed to be the * unit square, and this maps on to the rectangle in (x,y) given by * (xmin:xmax,ymin:ymax). * Parameters: * c * An array of (nx,ny) elements supplied holding the coefficients of * P, such that the coefficient of (Ti(u)*Tj(v)) is held in element * (i + j*nx), where "Ti(u)" is the Chebychev polynomial (of the * first kind) of order "i" evaluated at "u", and "Tj(v)" is the * Chebychev polynomial of order "j" evaluated at "v". * nx * One more than the maximum power of u within P. * ny * One more than the maximum power of v within P. * xmin * X value corresponding to u = -1 * xmax * X value corresponding to u = +1 * ymin * Y value corresponding to v = -1 * ymax * Y value corresponding to v = +1 * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a dynamically allocated array of (nx,ny) elements holding * the coefficients of Q, such that the coefficient of (x^i*y^j) is held * in element (i + j*nx). Free it using astFree when no longer needed. */ /* Local Variables: */ double *d; double *pa; double *pw; double *work1; double *work2; double *work3; int *iw1; int *iw2; int i; int j; /* Check the status and supplied value pointer. */ if( !astOK ) return NULL; /* Allocate returned array. */ d = astMalloc( sizeof( *d )*nx*ny ); /* Allocate workspace. */ work1 = astMalloc( sizeof( *work1 )*ny ); work2 = astMalloc( sizeof( *work2 )*ny ); work3 = astMalloc( sizeof( *work2 )*nx ); iw1 = astMalloc( sizeof(int)*( nx > ny ? nx : ny ) ); iw2 = astMalloc( sizeof(int)*( nx > ny ? nx : ny ) ); if( astOK ) { /* Thinking of P as a 1D polynomial in v, each coefficient would itself then be a 1D polynomial in u: P = ( c[0] + c[1]*T1(u) + c[2]*T2(u) + ... ) + ( c[nx] + c[nx+1]*T1(u) + c[nx+2]*T2(u) + ... )*T1(v) + (c[2*nx] + c[2*nx+1]*T1(u) + c[2*nx+2]*T2(u) + ... )*T2(v) + ... (c[(ny-1)*nx] + c[(ny-1)*nx+1]*T1(u) + c[(ny-1)*nx+2]*T2(u) + ... )T{ny-1}(v) Use Chpc1 to convert these "polynomial coefficients" to standard form, storing the result in the corresponding row of "d" . Also, convert them from u to x. */ for( j = 0; j < ny; j++ ) { Chpc1( c + j*nx, work3, nx, iw1, iw2, status ); Shpc1( xmin, xmax, nx, work3, d + j*nx, status ); } /* The polynomial value is now: ( d[0] + d[1]*x + d[2]*x*x + ... ) + ( d[nx] + d[nx+1]*x + d[nx+2]*x*x + ... )*T1(v) + (d[2*nx] + d[2*nx+1]*x + d[2*nx+2]*x*x + ... )*T2(v) + ... (d[(ny-1)*nx] + d[(ny-1)*nx+1]*x + d[(ny-1)*nx+2]*x*x + ... )*T{ny-1}(v) If we rearrange this expression to view it as a 1D polynomial in x, rather than v, each coefficient of the new 1D polynomial is then itself a polynomial in v: ( d[0] + d[nx]*T1(v) + d[2*nx]*T2(v) + ... d[(ny-1)*nx]*T{ny-1}(v) ) + ( d[1] + d[nx+1]*T1(v) + d[2*nx+1]*T2(v) + ... d[(ny-1)*nx+1]T{ny-1}(v)... )*x + ( d[2] + d[nx+2]*T1(v) + d[2*nx+2]*T2(v) + ... d[(ny-1)*nx+2]T{ny-1}(v)... )*x*x + ... ( d[nx-1] + d[2*nx-1]*T1(v) + d[3*nx-1]*T2(v) + ... d[ny*nx-1]*T{ny-1}(v) )*x*x*... Now use Chpc1 to convert each of these "polynomial coefficients" to standard form. We copy each column of the d array into a 1D work array, use Shpc1 to modify the values in the work array, and then write the modified values back into the current column of d. Also convert from v to y. */ for( i = 0; i < nx; i++ ) { pa = d + i; pw = work1; for( j = 0; j < ny; j++ ) { *(pw++) = *pa; pa += nx; } Chpc1( work1, work2, ny, iw1, iw2, status ); Shpc1( ymin, ymax, ny, work2, work1, status ); pa = d + i; pw = work1; for( j = 0; j < ny; j++ ) { *pa = *(pw++); pa += nx; } } /* So the polynomial is now: ( d[0] + d[nx]*y + d[2*nx]*y*y + ... d[(ny-1)*nx]*y*y*... ) + ( d[1] + d[nx+1]*y + d[2*nx+1]*y*y + ... d[(ny-1)*nx+1]*y*y*... )*x + ( d[2] + d[nx+2]*y + d[2*nx+2]*y*y + ... d[(ny-1)*nx+2]*y*y*... )*x*x + ... ( d[nx-1] + d[2*nx-1]*y + d[3*nx-1]*y*y + ... d[ny*nx-1]*y*y*... )*x*x*... Re-arranging, this is: ( d[0] + d[1]*x + d[2]*x*x + ... ) + ( d[nx] + d[nx+1]*x + d[nx+2]*x*x + ... )*y + (d[2*nx] + d[2*nx+1]*x + d[2*nx+2]*x*x + ... )*y*y + ... (d[(ny-1)*nx] + d[(ny-1)*nx+1]*x + d[(ny-1)*nx+2]*x*x + ... )*y*y*... as required. */ } /* Free the workspace. */ work1 = astFree( work1 ); work2 = astFree( work2 ); work3 = astFree( work3 ); iw1 = astFree( iw1 ); iw2 = astFree( iw2 ); /* Return the result. */ return d; } static int CheckFitsName( AstFitsChan *this, const char *name, const char *method, const char *class, int *status ){ /* * Name: * CheckFitsName * Purpose: * Check a keyword name conforms to FITS standards. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int CheckFitsName( AstFitsChan *this, const char *name, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * FITS keywords must contain between 1 and 8 characters, and each * character must be an upper-case Latin alphabetic character, a digit, * an underscore, or a hyphen. Leading, trailing or embedded white space * is not allowed, with the exception of totally blank or null keyword * names. * * If the supplied keyword name is invalid, either a warning is issued * (for violations that can be handled - such as illegal characters in * keywords), or an error is reported (for more major violations such * as the keyname containing an equals sign). * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a string holding the name to check. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 0 is returned if the supplied name was blank. A value of 1 * is returned otherwise. * Notes: * - An error is reported if the supplied keyword name does not * conform to FITS requirements, and zero is returned. */ /* Local Variables: */ char buf[100]; /* Buffer for warning text */ const char *c; /* Pointer to next character in name */ size_t n; /* No. of characters in supplied name */ int ret; /* Returned value */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise the returned value to indicate that the supplied name was blank. */ ret = 0; /* Check that the supplied pointer is not NULL. */ if( name ){ /* Get the number of characters in the name. */ n = strlen( name ); /* Report an error if the name has too many characters in it. */ if( n > FITSNAMLEN ){ astError( AST__BDFTS, "%s(%s): The supplied FITS keyword name ('%s') " "has %d characters. FITS only allows up to %d.", status, method, class, name, (int) n, FITSNAMLEN ); /* If the name has no characters in it, then assume it is a legal blank keyword name. Otherwise, check that no illegal characters occur in the name. */ } else if( n != 0 ) { /* Whitespace is only allowed in the special case of a name consisting entirely of whitespace. Such keywords are used to indicate that the rest of the card is a comment. Find the first non-whitespace character in the name. */ c = name; while( isspace( ( int ) *(c++) ) ); /* If the name is filled entirely with whitespace, then the name is acceptable as the special case. Otherwise, we need to do more checks. */ if( c - name - 1 < n ){ /* Indicate that the supplied name is not blank. */ ret = 1; /* Loop round every character checking that it is one of the legal characters. Report an error if any illegal characters are found. */ c = name; while( *c ){ if( !isFits( (int) *c ) ){ if( *c == '=' ){ astError( AST__BDFTS, "%s(%s): An equals sign ('=') was found " "before column %d within a FITS keyword name or header " "card.", status, method, class, FITSNAMLEN + 1 ); } else if( *c < ' ' ) { sprintf( buf, "The FITS keyword name ('%s') contains an " "illegal non-printing character (ascii value " "%d).", name, *c ); Warn( this, "badkeyname", buf, method, class, status ); } else if( *c > ' ' ) { sprintf( buf, "The FITS keyword name ('%s') contains an " "illegal character ('%c').", name, *c ); Warn( this, "badkeyname", buf, method, class, status ); } break; } c++; } } } /* Report an error if no pointer was supplied. */ } else if( astOK ){ astError( AST__INTER, "CheckFitsName(%s): AST internal error; a NULL " "pointer was supplied for the keyword name. ", status, astGetClass( this ) ); } /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static void CheckZero( char *text, double value, int width, int *status ){ /* * Name: * CheckZero * Purpose: * Ensure that the formatted value zero has no minus sign. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void CheckZero( char *text, double value, int width, int *status ) * Class Membership: * FitsChan member function. * Description: * There is sometimes a problem (perhaps only on DEC UNIX) when formatting * the floating-point value 0.0 using C. Sometimes it gives the string * "-0". This function fixed this by checking the first character of * the supplied string (if the supplied value is zero), and shunting the * remaining text one character to the right if it is a minus sign. It * returns without action if the supplied value is not zero. * * In addition, this function also rounds out long sequences of * adjacent zeros or nines in the number. * Parameters: * text * The formatted value. * value * The floating value which was formatted. * width * The minimum field width to use. The value is right justified in * this field width. Ignored if zero. * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ char *c; /* Return if no text was supplied. */ if( !text ) return; /* If the numerical value is zero, check for the leading minus sign. */ if( value == 0.0 ) { /* Find the first non-space character. */ c = text; while( *c && isspace( (int) *c ) ) c++; /* If the first non-space character is a minus sign, replace it with a space. */ if( *c == '-' ) *c = ' '; /* Otherwise, round out sequences of zeros or nines. */ } else { RoundFString( text, width, status ); } } static double ChooseEpoch( AstFitsChan *this, FitsStore *store, char s, const char *method, const char *class, int *status ){ /* * Name: * ChooseEpoch * Purpose: * Choose a FITS keyword value to use for the AST Epoch attribute. * Type: * Private function. * Synopsis: * double ChooseEpoch( AstFitsChan *this, FitsStore *store, char s, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function returns an MJD value in the TDB timescale, which can * be used as the Epoch value in an AST Frame. It uses the following * preference order: secondary MJD-AVG, primary MJD-AVG, secondary MJD-OBS, * primary MJD-OBS. Note, DATE-OBS keywords are converted into MJD-OBS * keywords by the SpecTrans function before this function is called. * Parameters: * this * Pointer to the FitsChan. * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * method * The calling method. Used only in error messages. * class * The object class. Used only in error messages. * status * Pointer to the inherited status variable. * Returned Value: * The MJD value. * Notes: * - A value of AST__BAD is returned if an error occurs, or if none * of the required keywords can be found in the FitsChan. */ /* Local Variables: */ const char *timesys; /* The TIMESYS value in the FitsStore */ double mjd; /* The returned MJD */ /* Initialise the returned value. */ mjd = AST__BAD; /* Check the global status. */ if( !astOK ) return mjd; /* Otherwise, try to get the secondary MJD-AVG value. */ mjd = GetItem( &(store->mjdavg), 0, 0, s, NULL, method, class, status ); /* Otherwise, try to get the primary MJD-AVG value. */ if( mjd == AST__BAD ) mjd = GetItem( &(store->mjdavg), 0, 0, ' ', NULL, method, class, status ); /* If the secondary MJD-OBS keyword is present in the FitsChan, gets its value. */ if( mjd == AST__BAD ) mjd = GetItem( &(store->mjdobs), 0, 0, s, NULL, method, class, status ); /* Otherwise, try to get the primary MJD-OBS value. */ if( mjd == AST__BAD ) mjd = GetItem( &(store->mjdobs), 0, 0, ' ', NULL, method, class, status ); /* Now convert the MJD value to the TDB timescale. */ timesys = GetItemC( &(store->timesys), 0, 0, ' ', NULL, method, class, status ); mjd = TDBConv( mjd, TimeSysToAst( this, timesys, method, class, status ), 0, method, class, status ); /* Return the answer. */ return mjd; } static void Chpc1( double *c, double *d, int n, int *w0, int *w1, int *status ){ /* * Name: * Chpc1 * Purpose: * Converts a one-dimensional Chebyshev polynomial to standard form. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void Chpc1( double *c, double *d, int n, int *w0, int *w1, int *status ) * Class Membership: * FitsChan * Description: * Given the coefficients of a one-dimensional Chebychev polynomial P(u), * find the coefficients of the equivalent standard 1D polynomial Q(u). * The allowed range of u is assumed to be the unit interval. * Parameters: * c * An array of n elements supplied holding the coefficients of * P, such that the coefficient of (Ti(u)) is held in element * (i), where "Ti(u)" is the Chebychev polynomial (of the * first kind) of order "i" evaluated at "u". * d * An array of n elements returned holding the coefficients of * Q, such that the coefficient of (u^i) is held in element (i). * n * One more than the highest power of u in P. * w0 * Pointer to a work array of n elements. * w1 * Pointer to a work array of n elements. * status * Inherited status value * Notes: * - Vaguely inspired by the Numerical Recipes routine "chebpc". But the * original had bugs, so I wrote this new version from first principles. */ /* Local Variables: */ int sv; int j; int k; /* Check inherited status */ if( !astOK ) return; /* Initialise the returned coefficients array. */ for( j = 0; j < n; j++ ) d[ j ] = 0.0; /* Use the recurrence relation T{k+1}(x) = 2.x.T{k}(x) - T{k-1}(x). w0[i] holds the coefficient of x^i in T{k-1}. w1[i] holds the coefficient of x^i in T{k}. Initialise them for T0 (="1") and T1 (="x"). */ for( j = 0; j < n; j++ ) w0[ j ] = w1[ j ] = 0; w0[ 0 ] = 1; w1[ 1 ] = 1; /* Update the returned coefficients array to include the T0 and T1 terms. */ d[ 0 ] = c[ 0 ]; d[ 1 ] = c[ 1 ]; /* Loop round using the above recurrence relation until we have found T{n-1}. */ for( k = 1; k < n - 1; k++ ){ /* To get the coefficients of T{k+1} shift the contents of w1 up one element, introducing a zero at the low end, and then double all the values in w1. Finally subtract off the values in w0. This implements the above recurrence relationship. Starting at the top end and working down to the bottom, store a new value for each element of w1. */ for( j = n - 1; j > 0; j-- ) { /* First save the original element of w1 in w0 for use next time. But we also need the original w0 element later on so save it first. */ sv = w0[ j ]; w0[ j ] = w1[ j ]; /* Double the lower neighbouring w1 element and subtract off the w0 element saved above. This forms the new value for w1. */ w1[ j ] = 2*w1[ j - 1 ] - sv; } /* Introduce a zero into the lowest element of w1, saving the original value first in w0. Then subtract off the original value of w0. */ sv = w0[ 0 ]; w0[ 0 ] = w1[ 0 ]; w1[ 0 ] = -sv; /* W1 now contains the coefficients of T{k+1} in w1, and the coefficients of T{k} in w0. Multiply these by the supplied coefficient for T{k+1}, and add them into the returned array. */ for( j = 0; j <= k + 1; j++ ){ d[ j ] += c[ k + 1 ]*w1[ j ]; } } } static int ChrLen( const char *string, int *status ){ /* * Name: * ChrLen * Purpose: * Return the length of a string excluding any trailing white space. * Type: * Private function. * Synopsis: * int ChrLen( const char *string, int *status ) * Class Membership: * FitsChan * Description: * This function returns the length of a string excluding any trailing * white space, or non-printable characters. * Parameters: * string * Pointer to the string. * status * Pointer to the inherited status variable. * Returned Value: * The length of a string excluding any trailing white space and * non-printable characters. * Notes: * - A value of zero is returned if a NULL pointer is supplied, or if an * error has already occurred. */ /* Local Variables: */ const char *c; /* Pointer to the next character to check */ int ret; /* The returned string length */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise the returned string length. */ ret = 0; /* Check a string has been supplied. */ if( string ){ /* Check each character in turn, starting with the last one. */ ret = strlen( string ); c = string + ret - 1; while( ret ){ if( isprint( (int) *c ) && !isspace( (int) *c ) ) break; c--; ret--; } } /* Return the answer. */ return ret; } static int CLASSFromStore( AstFitsChan *this, FitsStore *store, AstFrameSet *fs, double *dim, const char *method, const char *class, int *status ){ /* * Name: * CLASSFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-CLASS encoding. * Type: * Private function. * Synopsis: * int CLASSFromStore( AstFitsChan *this, FitsStore *store, * AstFrameSet *fs, double *dim, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-CLASS encoding. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * fs * Pointer to the FrameSet from which the values in the FitsStore * were derived. * dim * Pointer to an array holding the main array dimensions (AST__BAD * if a dimension is not known). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ AstFrame *azelfrm; /* (az,el) frame */ AstFrame *curfrm; /* Current Frame in supplied FrameSet */ AstFrame *freqfrm; /* Frame for reference frequency value */ AstFrame *radecfrm; /* Spatial frame for CRVAL values */ AstFrame *velofrm; /* Frame for reference velocity value */ AstFrameSet *fsconv1;/* FrameSet connecting "curfrm" & "radecfrm" */ AstFrameSet *fsconv2;/* FrameSet connecting "curfrm" & "azelfrm" */ AstMapping *map1; /* Axis permutation to get (lonaxis,lataxis) = (0,1) */ AstMapping *map2; /* Mapping from FITS CTYPE to (az,el) */ AstMapping *map3; /* Mapping from (lon,lat) to (az,el) */ char *comm; /* Pointer to comment string */ char *cval; /* Pointer to string keyword value */ char attbuf[20]; /* Buffer for AST attribute name */ char combuf[80]; /* Buffer for FITS card comment */ char lattype[MXCTYPELEN];/* Latitude axis CTYPE */ char lontype[MXCTYPELEN];/* Longitude axis CTYPE */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ char spectype[MXCTYPELEN];/* Spectral axis CTYPE */ double *cdelt; /* Pointer to CDELT array */ double aval[ 2 ]; /* General purpose array */ double azel[ 2 ]; /* Reference (az,el) values */ double cdl; /* CDELT term */ double crval[ 3 ]; /* CRVAL values converted to rads, etc */ double delta; /* Spectral axis increment */ double equ; /* Epoch of reference equinox */ double fd; /* Fraction of a day */ double latval; /* CRVAL for latitude axis */ double lonpole; /* LONPOLE value */ double lonval; /* CRVAL for longitude axis */ double mjd99; /* MJD at start of 1999 */ double p1, p2; /* Projection parameters */ double radec[ 2 ]; /* Reference (lon,lat) values */ double rf; /* Rest freq (Hz) */ double specfactor; /* Factor for converting internal spectral units */ double val; /* General purpose value */ double xin[ 3 ]; /* Grid coords at centre of first pixel */ double xout[ 3 ]; /* WCS coords at centre of first pixel */ int axlat; /* Index of latitude FITS WCS axis */ int axlon; /* Index of longitude FITS WCS axis */ int axspec; /* Index of spectral FITS WCS axis */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int naxis2; /* Length of pixel axis 2 */ int naxis3; /* Length of pixel axis 3 */ int naxis; /* No. of axes */ int ok; /* Is FitsSTore OK for IRAF encoding? */ int prj; /* Projection type */ /* Other initialisation to avoid compiler warnings. */ lonval = 0.0; latval = 0.0; /* Check the inherited status. */ if( !astOK ) return 0; /* Initialise */ specfactor = 1.0; /* First check that the values in the FitsStore conform to the requirements of the CLASS encoding. Assume they do not to begin with. */ ok = 0; /* Just do primary axes. */ s = ' '; /* Look for the primary celestial axes. */ FindLonLatSpecAxes( store, s, &axlon, &axlat, &axspec, method, class, status ); /* Get the current Frame from the supplied FrameSet. */ curfrm = astGetFrame( fs, AST__CURRENT ); /* Spectral and celestial axes must be present in axes 1,2 and 3. */ if( axspec >= 0 && axspec < 3 && axlon >= 0 && axlon < 3 && axlat >= 0 && axlat < 3 ) { ok = 1; /* If the spatial pixel axes are degenerate (i.e. span only a single pixel), modify the CRPIX and CRVAL values in the FitsStore to put the reference point at the centre of the one and only spatial pixel. */ if( store->naxis >= 3 && dim[ axlon ] == 1.0 && dim[ axlat ] == 1.0 ){ xin[ 0 ] = 1.0; xin[ 1 ] = 1.0; xin[ 2 ] = 1.0; astTranN( fs, 1, 3, 1, xin, 1, 3, 1, xout ); if( xout[ axlon ] != AST__BAD && xout[ axlat ] != AST__BAD ) { /* The indices of the spatial axes in the FITS header may not be the same as the indices of the spatial axes in the WCS Frame of the supplied FrameSet. So search the current Frame for longitude and latitude axes, and store the corresponding elements of the "xout" array for later use. */ for( i = 0; i < 3; i++ ) { sprintf( attbuf, "IsLonAxis(%d)", i + 1 ); if( astHasAttribute( curfrm, attbuf ) ) { if( astGetI( curfrm, attbuf ) ) { lonval = xout[ i ]; } else { latval = xout[ i ]; } } } /* Store them in the FitsStore. */ SetItem( &(store->crval), axlon, 0, ' ', lonval*AST__DR2D, status ); SetItem( &(store->crval), axlat, 0, ' ', latval*AST__DR2D, status ); SetItem( &(store->crpix), 0, axlon, ' ', 1.0, status ); SetItem( &(store->crpix), 0, axlat, ' ', 1.0, status ); } } /* Get the CRVAL values for both spatial axes. */ latval = GetItem( &( store->crval ), axlat, 0, s, NULL, method, class, status ); if( latval == AST__BAD ) ok = 0; lonval = GetItem( &( store->crval ), axlon, 0, s, NULL, method, class, status ); if( lonval == AST__BAD ) ok = 0; /* Get the CTYPE values for both axes. Extract the projection type as specified by the last 4 characters in the latitude CTYPE keyword value. */ cval = GetItemC( &(store->ctype), axlon, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { strcpy( lontype, cval ); } cval = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; prj = AST__WCSBAD; } else { strcpy( lattype, cval ); prj = astWcsPrjType( cval + 4 ); } /* Check the projection type is OK. */ if( prj == AST__WCSBAD ){ ok = 0; } else if( prj != AST__SIN ){ /* Check the projection code is OK. */ ok = 0; if( prj == AST__TAN || prj == AST__ARC || prj == AST__STG || prj == AST__AIT || prj == AST__SFL ) { ok = 1; /* For AIT, and SFL, check that the reference point is the origin of the celestial co-ordinate system. */ if( prj == AST__AIT || prj == AST__SFL ) { if( latval != 0.0 || lonval != 0.0 ){ ok = 0; /* Change the new SFL projection code to to the older equivalent GLS */ } else if( prj == AST__SFL ){ (void) strcpy( lontype + 4, "-GLS" ); (void) strcpy( lattype + 4, "-GLS" ); /* Change the new AIT projection code to to the older equivalent ATF */ } else if( prj == AST__AIT ){ (void) strcpy( lontype + 4, "-ATF" ); (void) strcpy( lattype + 4, "-ATF" ); } } } /* SIN projections are only acceptable if the associated projection parameters are both zero. */ } else { p1 = GetItem( &( store->pv ), axlat, 1, s, NULL, method, class, status ); p2 = GetItem( &( store->pv ), axlat, 2, s, NULL, method, class, status ); if( p1 == AST__BAD ) p1 = 0.0; if( p2 == AST__BAD ) p2 = 0.0; ok = ( p1 == 0.0 && p2 == 0.0 ); } /* Identify the celestial coordinate system from the first 4 characters of the longitude CTYPE value. Only RA and galactic longitude can be stored using FITS-CLASS. */ if( ok && strncmp( lontype, "RA--", 4 ) && strncmp( lontype, "GLON", 4 ) ) ok = 0; /* Get the CTYPE values for the spectral axis, and find the CLASS equivalent, if possible. */ cval = GetItemC( &(store->ctype), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else { if( !strncmp( cval, "FREQ", astChrLen( cval ) ) ) { strcpy( spectype, "FREQ" ); } else { ok = 0; } } /* If OK, check the SPECSYS value is SOURCE. */ cval = GetItemC( &(store->specsys), 0, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else if( ok ) { if( strncmp( cval, "SOURCE", astChrLen( cval ) ) ) ok = 0; } /* If still OK, ensure the spectral axis units are Hz. */ cval = GetItemC( &(store->cunit), axspec, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; } else if( ok ) { if( !strcmp( cval, "Hz" ) ) { specfactor = 1.0; } else if( !strcmp( cval, "kHz" ) ) { specfactor = 1.0E3; } else if( !strcmp( cval, "MHz" ) ) { specfactor = 1.0E6; } else if( !strcmp( cval, "GHz" ) ) { specfactor = 1.0E9; } else { ok = 0; } } } /* Save the number of WCS axes */ naxis = GetMaxJM( &(store->crpix), ' ', status ) + 1; /* If this is larger than 3, ignore the surplus WCS axes. Note, the above code has checked that the spatial and spectral axes are WCS axes 0, 1 and 2. */ if( naxis > 3 ) naxis = 3; /* Allocate memory to store the CDELT values */ if( ok ) { cdelt = (double *) astMalloc( sizeof(double)*naxis ); if( !cdelt ) ok = 0; } else { cdelt = NULL; } /* Check that there is no rotation, and extract the CDELT (diagonal) terms, etc. If the spatial axes are degenerate (i.e. cover only a single pixel) then ignore any rotation. */ if( !GetValue( this, FormatKey( "NAXIS", axlon + 1, -1, s, status ), AST__INT, &naxis2, 0, 0, method, class, status ) ) { naxis2 = 0; } if( !GetValue( this, FormatKey( "NAXIS", axlat + 1, -1, s, status ), AST__INT, &naxis3, 0, 0, method, class, status ) ) { naxis3 = 0; } for( i = 0; i < naxis && ok; i++ ){ cdl = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdl == AST__BAD ) cdl = 1.0; for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdl; if( i == j ){ cdelt[ i ] = val; } else if( val != 0.0 ){ if( naxis2 != 1 || naxis3 != 1 ) ok = 0; } } } /* Get RADECSYS and the reference equinox. */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); equ = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); /* If RADECSYS was available... */ if( cval ){ /* Only FK4 and FK5 are supported in this encoding. */ if( strcmp( "FK4", cval ) && strcmp( "FK5", cval ) ) ok = 0; /* If epoch was not available, set a default epoch. */ if( equ == AST__BAD ){ if( !strcmp( "FK4", cval ) ){ equ = 1950.0; } else if( !strcmp( "FK5", cval ) ){ equ = 2000.0; } else { ok = 0; } /* If an epoch was supplied, check it is consistent with the IAU 1984 rule. */ } else { if( !strcmp( "FK4", cval ) ){ if( equ >= 1984.0 ) ok = 0; } else if( !strcmp( "FK5", cval ) ){ if( equ < 1984.0 ) ok = 0; } else { ok = 0; } } /* Check we have a rest frequency */ rf = GetItem( &(store->restfrq), 0, 0, s, NULL, method, class, status ); if( rf == AST__BAD ) ok = 0; } /* If the spatial Frame covers more than a single Frame and requires a LONPOLE or LATPOLE keyword, it cannot be encoded using FITS-CLASS. However since FITS-CLASS imposes a no rotation restriction, it can tolerate lonpole values of +/- 180 degrees. */ if( ok && ( naxis2 != 1 || naxis3 != 1 ) ) { lonpole = GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ); if( lonpole != AST__BAD && lonpole != -180.0 && lonpole == 180 ) ok = 0; if( GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ) != AST__BAD ) ok = 0; } /* Only create the keywords if the FitsStore conforms to the requirements of the FITS-CLASS encoding. */ if( ok ) { /* If celestial axes were added by MakeFitsFrameSet, we need to ensure the header contains 3 main array axes. This is because the CLASS encoding does not support the WCSAXES keyword. */ if( store->naxis == 1 ) { /* Update the "NAXIS" value to 3 or put a new card in at the start. */ astClearCard( this ); i = 3; SetValue( this, "NAXIS", &i, AST__INT, NULL, status ); /* Put NAXIS2/3 after NAXIS1, or after NAXIS if the FitsChan does not contain NAXIS1. These are set to 1 since the spatial axes are degenerate. */ if( FindKeyCard( this, "NAXIS1", method, class, status ) ) { MoveCard( this, 1, method, class, status ); } i = 1; SetValue( this, "NAXIS2", &i, AST__INT, NULL, status ); SetValue( this, "NAXIS3", &i, AST__INT, NULL, status ); } /* Find the last WCS related card. */ FindWcs( this, 1, 1, 0, method, class, status ); /* Get and save CRPIX for all pixel axes. These are required, so break if they are not available. */ for( j = 0; j < naxis && ok; j++ ){ val = GetItem( &(store->crpix), 0, j, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { sprintf( combuf, "Reference pixel on axis %d", j + 1 ); SetValue( this, FormatKey( "CRPIX", j + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CRVAL for all intermediate axes. These are required, so break if they are not available. Note, the frequency axis CRVAL is redefined by FITS-CLASS by reducing it by the RESTFREQ value. */ for( i = 0; i < naxis && ok; i++ ){ val = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; } else { crval[ i ] = val; if( i == axspec ) { val *= specfactor; val -= rf; } sprintf( combuf, "Value at ref. pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRVAL", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save CTYPE for all intermediate axes. These are required, so break if they are not available. Use the potentially modified versions saved above for the celestial axes. */ for( i = 0; i < naxis && ok; i++ ){ if( i == axlat ) { cval = lattype; } else if( i == axlon ) { cval = lontype; } else if( i == axspec ) { cval = spectype; } else { cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); } if( cval && ( strlen(cval) < 5 || strcmp( cval + 4, "-TAB" ) ) ) { comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } SetValue( this, FormatKey( "CTYPE", i + 1, -1, s, status ), &cval, AST__STRING, comm, status ); } else { ok = 0; } } /* CDELT values */ if( axspec != -1 ) cdelt[ axspec ] *= specfactor; for( i = 0; i < naxis; i++ ){ SetValue( this, FormatKey( "CDELT", i + 1, -1, s, status ), cdelt + i, AST__FLOAT, "Pixel size", status ); } /* Reference equinox */ if( equ != AST__BAD ) SetValue( this, "EQUINOX", &equ, AST__FLOAT, "Epoch of reference equinox", status ); /* Date of observation. */ val = GetItem( &(store->mjdobs), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD ) { /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", (void *) &cval, AST__STRING, "Date of observation", status ); } /* Rest frequency */ SetValue( this, "RESTFREQ", &rf, AST__FLOAT, "[Hz] Rest frequency", status ); /* The image frequency corresponding to the rest frequency (only used for double sideband data). */ val = GetItem( &(store->imagfreq), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { SetValue( this, "IMAGFREQ", &val, AST__FLOAT, "[Hz] Image frequency", status ); } /* Ensure the FitsChan contains OBJECT and LINE headers */ if( !HasCard( this, "OBJECT", method, class, status ) ) { cval = " "; SetValue( this, "OBJECT", &cval, AST__STRING, NULL, status ); } if( !HasCard( this, "LINE", method, class, status ) ) { cval = " "; SetValue( this, "LINE", &cval, AST__STRING, NULL, status ); } /* CLASS expects the VELO-LSR keyword to hold the radio velocity of the reference channel (NOT of the source as I was told!!) with respect to the LSRK rest frame. The "crval" array holds the frequency of the reference channel in the source rest frame, so we need to convert this to get the value for VELO-LSR. Create a SpecFrame describing the required frame (other attributes such as Epoch etc are left unset and so will be picked up from the supplied FrameSet). We set MinAxes and MaxAxes so that the Frame can be used as a template to match the 1D or 3D current Frame in the supplied FrameSet. */ velofrm = (AstFrame *) astSpecFrame( "System=vrad,StdOfRest=lsrk," "Unit=m/s,MinAxes=1,MaxAxes=3", status ); /* Find the spectral axis within the current Frame of the supplied FrameSet, using the above "velofrm" as a template. */ fsconv1 = astFindFrame( curfrm, velofrm, "" ); /* If OK, extract the SpecFrame from the returned FraneSet (this will have the attribute values that were assigned explicitly to "velofrm" and will have inherited all unset attributes from the supplied FrameSet). */ if( fsconv1 ) { velofrm = astAnnul( velofrm ); velofrm = astGetFrame( fsconv1, AST__CURRENT ); fsconv1 = astAnnul( fsconv1 ); /* Take a copy of the velofrm and modify its attributes so that it describes frequency in the sources rest frame in units of Hz. This is the system that CLASS expects for the CRVAL3 keyword. */ freqfrm = astCopy( velofrm ); astSet( freqfrm, "System=freq,StdOfRest=Source,Unit=Hz", status ); /* Get a Mapping from frequency to velocity. */ fsconv1 = astConvert( freqfrm, velofrm, "" ); if( fsconv1 ) { /* Use this Mapping to convert the spectral crval value from frequency to velocity. Also convert the value for the neighbouring channel. */ aval[ 0 ] = crval[ axspec ]*specfactor; aval[ 1 ] = aval[ 0 ] + cdelt[ axspec ]*specfactor; astTran1( fsconv1, 2, aval, 1, aval ); /* Store the value. Also store it as VLSR since this keyword seems to be used for the same thing. */ SetValue( this, "VELO-LSR", aval, AST__FLOAT, "[m/s] Reference velocity", status ); SetValue( this, "VLSR", aval, AST__FLOAT, "[m/s] Reference velocity", status ); /* The DELTAV keyword holds the radio velocity channel spacing in the LSR. */ delta = aval[ 1 ] - aval[ 0 ]; SetValue( this, "DELTAV", &delta, AST__FLOAT, "[m/s] Velocity resolution", status ); /* Free remaining resources. */ fsconv1 = astAnnul( fsconv1 ); } } velofrm = astAnnul( velofrm ); /* AZIMUTH and ELEVATIO - the (az,el) equivalent of CRVAL. We need a Mapping from the CTYPE spatial system to (az,el). This depends on all the extra info like telescope position, epoch, etc. This info is in the current Frame in the supplied FrameSet. First get a conversion from a sky frame with default axis ordering to the supplied Frame. All the extra info is picked up from the supplied Frame since it is not set in the template. */ radecfrm = (AstFrame *) astSkyFrame( "Permute=0,MinAxes=3,MaxAxes=3", status ); fsconv1 = astFindFrame( curfrm, radecfrm, "" ); /* Now get conversion from the an (az,el) Frame to the supplied Frame. */ azelfrm = (AstFrame *) astSkyFrame( "System=AZEL,Permute=0,MinAxes=3,MaxAxes=3", status ); fsconv2 = astFindFrame( curfrm, azelfrm, "" ); /* If both conversions werew possible, concatenate their Mappings to get a Mapping from (lon,lat) in the CTYPE system, to (az,el). */ if( fsconv1 && fsconv2 ) { map1 = astGetMapping( fsconv1, AST__CURRENT, AST__BASE ); map2 = astGetMapping( fsconv2, AST__BASE, AST__CURRENT ); map3 = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); /* Store the CRVAL (ra,dec) values in the default order. */ radec[ 0 ] = crval[ axlon ]*AST__DD2R; radec[ 1 ] = crval[ axlat ]*AST__DD2R; /* Transform to (az,el), normalise, convert to degrees and store. */ astTranN( map3, 1, 2, 1, radec, 1, 2, 1, azel ); if( azel[ 0 ] != AST__BAD && azel[ 1 ] != AST__BAD ) { astNorm( azelfrm, azel ); azel[ 0 ] *= AST__DR2D; azel[ 1 ] *= AST__DR2D; SetValue( this, "AZIMUTH", azel, AST__FLOAT, "[Deg] Telescope azimuth", status ); SetValue( this, "ELEVATIO", azel + 1, AST__FLOAT, "[Deg] Telescope elevation", status ); } /* Free resources */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); fsconv1 = astAnnul( fsconv1 ); fsconv2 = astAnnul( fsconv2 ); } radecfrm = astAnnul( radecfrm ); azelfrm = astAnnul( azelfrm ); } curfrm = astAnnul( curfrm ); /* Release CDELT workspace */ if( cdelt ) cdelt = (double *) astFree( (void *) cdelt ); /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ok : 0; } static void ClassTrans( AstFitsChan *this, AstFitsChan *ret, int axlat, int axlon, const char *method, const char *class, int *status ){ /* * Name: * ClassTrans * Purpose: * Translated non-standard FITS-CLASS headers into equivalent standard * ones. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void ClassTrans( AstFitsChan *this, AstFitsChan *ret, int axlat, * int axlon, const char *method, const char *class ) * Class Membership: * FitsChan member function. * Description: * This function extends the functionality of the SpecTrans function, * by converting non-standard WCS keywords into standard FITS-WCS * keywords, using the conventions of the FITS-CLASS encoding. * Parameters: * this * Pointer to the FitsChan containing the original header cards. * ret * Pointer to a FitsChan in which to return the standardised header * cards. * axlat * Zero-based index of the celestial latitude axis. * axlon * Zero-based index of the celestial longitude axis. * method * Pointer to string holding name of calling method. * class * Pointer to a string holding the name of the supplied object class. */ /* Local Variables: */ char *cval; /* Pointer to character string */ char newtype[ 10 ]; /* New CTYPE value */ const char *keyname; /* Pointer to keyword name */ const char *ssyssrc; /* Pointer to SSYSSRC keyword value string */ double crval; /* CRVAL value */ double restfreq; /* Rest frequency (Hz) */ double v0; /* Ref channel velocity in source frame */ double vref; /* Ref channel velocity in LSR or whatever */ double vsource; /* Source velocity */ double zsource; /* Source redshift */ int axspec; /* Index of spectral axis */ /* Check the global error status. */ if ( !astOK ) return; /* Get the rest frequency. */ restfreq = AST__BAD; if( !GetValue2( ret, this, "RESTFRQ", AST__FLOAT, (void *) &restfreq, 0, method, class, status ) ){ GetValue2( ret, this, "RESTFREQ", AST__FLOAT, (void *) &restfreq, 0, method, class, status ); } if( restfreq == AST__BAD ) { astError( AST__BDFTS, "%s(%s): Keyword RESTFREQ not found in CLASS " "FITS header.", status, method, class ); } /* Get the index of the spectral axis. */ if( axlat + axlon == 1 ) { axspec = 2; } else if( axlat + axlon == 3 ) { axspec = 0; } else { axspec = 1; } /* Get the spectral CTYPE value */ if( GetValue2( ret, this, FormatKey( "CTYPE", axspec + 1, -1, ' ', status ), AST__STRING, (void *) &cval, 0, method, class, status ) ){ /* We can only handle frequency axes at the moment. */ if( !astChrMatch( "FREQ", cval ) ) { astError( AST__BDFTS, "%s(%s): FITS-CLASS keyword %s has value " "\"%s\" - CLASS support in AST only includes \"FREQ\" axes.", status, method, class, FormatKey( "CTYPE", axspec + 1, -1, ' ', status ), cval ); /* CRVAL for the spectral axis needs to be incremented by RESTFREQ if the axis represents frequency. */ } else { keyname = FormatKey( "CRVAL", axspec + 1, -1, ' ', status ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &crval, 1, method, class, status ) ) { crval += restfreq; SetValue( ret, keyname, (void *) &crval, AST__FLOAT, NULL, status ); } } /* CLASS frequency axes describe source frame frequencies. */ cval = "SOURCE"; SetValue( ret, "SPECSYS", (void *) &cval, AST__STRING, NULL, status ); } /* If no projection code is supplied for the longitude and latitude axes, use "-GLS". This will be translated to "-SFL" by SpecTrans. */ keyname = FormatKey( "CTYPE", axlon + 1, -1, ' ', status ); if( GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) ){ if( strlen(cval) > 4 && !strncmp( " ", cval + 4, 4 ) ) { strncpy( newtype, cval, 4 ); strcpy( newtype + 4, "-GLS" ); cval = newtype; SetValue( ret, keyname, (void *) &cval, AST__STRING, NULL, status ); } } keyname = FormatKey( "CTYPE", axlat + 1, -1, ' ', status ); if( GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) ){ if( strlen(cval) > 4 && !strncmp( " ", cval + 4, 4 ) ) { strncpy( newtype, cval, 4 ); strcpy( newtype + 4, "-GLS" ); cval = newtype; SetValue( ret, keyname, (void *) &cval, AST__STRING, NULL, status ); } } /* Look for a keyword with name "VELO-...". This specifies the radio velocity at the reference channel, in a standard of rest specified by the "..." in the keyword name. If "VELO-..." is not found, look for "VLSR", which is the same as "VELO-LSR". */ if( GetValue2( ret, this, "VELO-%3c", AST__FLOAT, (void *) &vref, 0, method, class, status ) || GetValue2( ret, this, "VLSR", AST__FLOAT, (void *) &vref, 0, method, class, status ) ){ /* Calculate the radio velocity (in the rest frame of the source) corresponding to the frequency at the reference channel. */ v0 = AST__C*( restfreq - crval )/restfreq; /* Assume that the source velocity is the difference between this velocity and the reference channel velocity given by "VELO-..." */ vsource = vref - v0; /* Get the keyword name and find the corresponding SSYSSRC keyword value. */ keyname = CardName( this, status ); if( !strcmp( keyname, "VELO-HEL" ) ) { ssyssrc = "BARYCENT"; } else if( !strcmp( keyname, "VELO-OBS" ) || !strcmp( keyname, "VELO-TOP" ) ) { ssyssrc = "TOPOCENT"; } else if( !strcmp( keyname, "VELO-EAR" ) || !strcmp( keyname, "VELO-GEO" ) ) { ssyssrc = "GEOCENTR"; } else { ssyssrc = "LSRK"; } SetValue( ret, "SSYSSRC", (void *) &ssyssrc, AST__STRING, NULL, status ); /* Convert from radio velocity to redshift and store as ZSOURCE */ zsource = ( AST__C / (AST__C - vsource) ) - 1.0; SetValue( ret, "ZSOURCE", (void *) &zsource, AST__FLOAT, NULL, status ); } } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * FitsChan member function (over-rides the astClearAttrib protected * method inherited from the Channel class). * Description: * This function clears the value of a specified attribute for a * FitsChan, so that the default value will subsequently be used. * Parameters: * this * Pointer to the FitsChan. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Card. */ /* ----- */ if ( !strcmp( attrib, "card" ) ) { astClearCard( this ); /* Encoding. */ /* --------- */ } else if ( !strcmp( attrib, "encoding" ) ) { astClearEncoding( this ); /* CDMatrix */ /* -------- */ } else if ( !strcmp( attrib, "cdmatrix" ) ) { astClearCDMatrix( this ); /* FitsAxisOrder. */ /* ----------- */ } else if ( !strcmp( attrib, "fitsaxisorder" ) ) { astClearFitsAxisOrder( this ); /* FitsDigits. */ /* ----------- */ } else if ( !strcmp( attrib, "fitsdigits" ) ) { astClearFitsDigits( this ); /* DefB1950 */ /* -------- */ } else if ( !strcmp( attrib, "defb1950" ) ) { astClearDefB1950( this ); /* TabOK */ /* ----- */ } else if ( !strcmp( attrib, "tabok" ) ) { astClearTabOK( this ); /* CarLin */ /* ------ */ } else if ( !strcmp( attrib, "carlin" ) ) { astClearCarLin( this ); /* PolyTan */ /* ------- */ } else if ( !strcmp( attrib, "polytan" ) ) { astClearPolyTan( this ); /* Iwc */ /* --- */ } else if ( !strcmp( attrib, "iwc" ) ) { astClearIwc( this ); /* Clean */ /* ----- */ } else if ( !strcmp( attrib, "clean" ) ) { astClearClean( this ); /* Warnings. */ /* -------- */ } else if ( !strcmp( attrib, "warnings" ) ) { astClearWarnings( 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 ( astOK && ( !strcmp( attrib, "ncard" ) || !strcmp( attrib, "allwarnings" ) ) ){ 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearCard( AstFitsChan *this, int *status ){ /* *+ * Name: * astClearCard * Purpose: * Clear the Card attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * void astClearCard( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function clears the Card attribute for the supplied FitsChan by * setting it to the index of the first un-used card in the FitsChan. * This causes the next read operation performed on the FitsChan to * read the first card. Thus, it is equivalent to "rewinding" the FitsChan. * Parameters: * this * Pointer to the FitsChan. * Notes: * - This function attempts to execute even if an error has occurred. *- */ /* Local Variables; */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Check the supplied FitsChan. If its is empty, return. */ if ( !this || !(this->head) ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Set the pointer to the current card so that it points to the card at the head of the list. */ this->card = this->head; /* If the current card has been read into an AST object, move on to the first card which has not, unless we are not skipping such cards. */ if( CARDUSED(this->card) ){ MoveCard( this, 1, "astClearCard", astGetClass( this ), status ); } } static int CnvValue( AstFitsChan *this, int type, int undef, void *buff, const char *method, int *status ){ /* * * Name: * CnvValue * Purpose: * Convert a data value into a given FITS data type. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int CnvValue( AstFitsChan *this, int type, int undef, void *buff, * const char *method, int *status ) * Class Membership: * FitsChan method. * Description: * This function produces a copy of the data value for the current card * converted from its stored data type to the supplied data type. * Parameters: * this * Pointer to the FitsChan. * type * The FITS data type in which to return the data value of the * current card. * undef * Determines what happens if the current card has an undefined * value. If "undef" is zero, an error will be reported identifying * the undefined keyword value. If "undef" is non-zero, no error is * reported and the contents of the output buffer are left unchanged. * buf * A pointer to a buffer to recieve the converted value. It is the * responsibility of the caller to ensure that a suitable buffer is * supplied. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the conversion was not possible (in which case NO error is * reported), one otherwise. * Notes: * - When converting from floating point to integer, the floating * point value is truncated using a C cast. * - Non-zero numerical values are considered TRUE, and zero * numerical values are considered FALSE. Any string starting with a * 'T' or a 'Y' (upper or lower case) is considered TRUE, and anything * starting with an 'F' or an 'N' (upper or lower case) is considered * FALSE. In addition, a dot ('.') may be placed in front of a 'T' or an * 'F'. * - A logical TRUE value is represented as a real numerical value of * one and the character string "Y". A logical FALSE value is represented * by a real numerical value of zero and the character string "N". * - When converting from a string to any numerical value, zero is * returned if the string is not a formatted value which can be converted * into the corresponding type using astSscanf. * - Real and imaginary parts of a complex value should be separated by * spaces within strings. If a string does contains only a single numerical * value, it is assumed to be the real part, and the imaginary part is * assumed to be zero. * - When converting a complex numerical type to a non-complex numerical * type, the returned value is derived from the real part only, the * imaginary part is ignored. * - Zero is returned if an error has occurred, or if this function * should fail for any reason. * - If the supplied value is undefined an error will be reported. */ /* Local Variables: */ int otype; /* Stored data type */ size_t osize; /* Size of stored data */ void *odata; /* Pointer to stored data */ /* Check the global error status, and the supplied buffer. */ if ( !astOK || !buff ) return 0; /* Get the type in which the data value is stored. */ otype = CardType( this, status ); /* Get a pointer to the stored data value, and its size. */ osize = 0; odata = CardData( this, &osize, status ); /* Do the conversion. */ return CnvType( otype, odata, osize, type, undef, buff, CardName( this, status ), method, astGetClass( this ), status ); } static int CnvType( int otype, void *odata, size_t osize, int type, int undef, void *buff, const char *name, const char *method, const char *class, int *status ){ /* * * Name: * CnvType * Purpose: * Convert a data value into a given FITS data type. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int CnvType( int otype, void *odata, size_t osize, int type, int undef, * void *buff, const char *name, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan method. * Description: * This function produces a copy of the data value for the current card * converted from its stored data type to the supplied data type. * Parameters: * otype * The type of the supplied data value. * odata * Pointer to a buffer holding the supplied data value. * osize * The size of the data value (in bytes - strings include the * terminating null). * type * The FITS data type in which to return the data value of the * current card. * undef * Determines what happens if the supplied data value type is * undefined If "undef" is zero, an error will be reported identifying * the undefined keyword value. If "undef" is non-zero, no error is * reported and the contents of the output buffer are left unchanged. * buff * A pointer to a buffer to recieve the converted value. It is the * responsibility of the caller to ensure that a suitable buffer is * supplied. * name * A pointer to a string holding a keyword name to include in error * messages. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the conversion was not possible (in which case NO error is * reported), one otherwise. * Notes: * - When converting from floating point to integer, the floating * point value is truncated using a C cast. * - Non-zero numerical values are considered TRUE, and zero * numerical values are considered FALSE. Any string starting with a * 'T' or a 'Y' (upper or lower case) is considered TRUE, and anything * starting with an 'F' or an 'N' (upper or lower case) is considered * FALSE. In addition, a dot ('.') may be placed in front of a 'T' or an * 'F'. * - A logical TRUE value is represented as a real numerical value of * one and the character string "Y". A logical FALSE value is represented * by a real numerical value of zero and the character string "N". * - When converting from a string to any numerical value, zero is * returned if the string isn not a formatted value which can be converted * into the corresponding type using astSscanf. * - Real and imaginary parts of a complex value should be separated by * spaces within strings. If a string does contains only a single numerical * value, it is assumed to be the real part, and the imaginary part is * assumed to be zero. * - When converting a complex numerical type to a non-complex numerical * type, the returned value is derived from the real part only, the * imaginary part is ignored. * - Zero is returned if an error has occurred, or if this function * should fail for any reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *c; /* Pointer to next character */ const char *ostring; /* String data value */ double odouble; /* Double data value */ int oint; /* Integer data value */ int ival; /* Integer value read from string */ int len; /* Length of character string */ int nc; /* No. of characetsr used */ int ret; /* Returned success flag */ /* Check the global error status, and the supplied buffer. */ if ( !astOK || !buff ) return 0; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* Assume success. */ ret = 1; /* If the supplied data type is undefined, report an error unless the returned data type is also undefined or an undefined value is acceptable for the keyword. */ if( otype == AST__UNDEF ) { if( type != AST__UNDEF && !undef ) { ret = 0; astError( AST__FUNDEF, "The FITS keyword '%s' has an undefined " "value.", status, name ); } /* If the returned data type is undefined, the returned value is immaterial, so leave the buffer contents unchanged. */ } else if( type == AST__UNDEF ) { /* If there is no data value and this is not a COMMENT keyword, or if there is a data value and this is a COMMENT card, conversion is not possible. */ } else if( ( odata && otype == AST__COMMENT ) || ( !odata && otype != AST__COMMENT ) ) { ret = 0; /* If there is no data value (and therefore this is a comment card), conversion is only possible if the output type is also a comment. */ } else if( !odata ) { if( type != AST__COMMENT ) ret = 0; /* Otherwise we have a data value, so do each possible combination of supplied and stored data types... */ } else { /* Convert a AST__FLOAT data value to ... */ if( otype == AST__FLOAT ){ odouble = *( (double *) odata ); if( type == AST__FLOAT ){ (void) memcpy( buff, odata, osize ); } else if( type == AST__STRING || type == AST__CONTINUE ){ if( odouble != AST__BAD ) { (void) sprintf( cnvtype_text, "%.*g", DBL_DIG, odouble ); CheckZero( cnvtype_text, odouble, 0, status ); } else { strcpy( cnvtype_text, BAD_STRING ); } *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ *( (int *) buff ) = (int) odouble; } else if( type == AST__LOGICAL ){ *( (int *) buff ) = ( odouble == 0.0 ) ? 0 : 1; } else if( type == AST__COMPLEXF ){ ( (double *) buff )[ 0 ] = odouble; ( (double *) buff )[ 1 ] = 0.0; } else if( type == AST__COMPLEXI ){ ( (int *) buff )[ 0 ] = (int) odouble; ( (int *) buff )[ 1 ] = 0; } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } /* Convert a AST__STRING data value to ... */ } else if( otype == AST__STRING || type == AST__CONTINUE ){ ostring = (char *) odata; len = (int) strlen( ostring ); if( type == AST__FLOAT ){ if( nc = 0, ( 0 == astSscanf( ostring, BAD_STRING " %n", &nc ) ) && (nc >= len ) ){ *( (double *) buff ) = AST__BAD; } else if( nc = 0, ( 1 != astSscanf( ostring, "%lf %n", (double *) buff, &nc ) ) || (nc < len ) ){ ret = 0; } } else if( type == AST__STRING || type == AST__CONTINUE ){ strncpy( cnvtype_text, (char *) odata, AST__FITSCHAN_FITSCARDLEN ); *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ if( nc = 0, ( 1 != astSscanf( ostring, "%d %n", (int *) buff, &nc ) ) || (nc < len ) ){ ret = 0; } } else if( type == AST__LOGICAL ){ if( nc = 0, ( 1 == astSscanf( ostring, "%d %n", &ival, &nc ) ) && (nc >= len ) ){ *( (int *) buff ) = ival ? 1 : 0; } else { c = ostring; while( *c && isspace( (int) *c ) ) c++; if( *c == 'y' || *c == 'Y' || *c == 't' || *c == 'T' || ( *c == '.' && ( c[1] == 't' || c[1] == 'T' ) ) ){ *( (int *) buff ) = 1; } else if( *c == 'n' || *c == 'N' || *c == 'f' || *c == 'F' || ( *c == '.' && ( c[1] == 'f' || c[1] == 'F' ) ) ){ *( (int *) buff ) = 0; } else { ret = 0; } } } else if( type == AST__COMPLEXF ){ if( nc = 0, ( 1 != astSscanf( ostring, "%lf %lf %n", (double *) buff, (double *) buff + 1, &nc ) ) || (nc < len ) ){ if( nc = 0, ( 1 != astSscanf( ostring, "%lf %n", (double *) buff, &nc ) ) || (nc < len ) ){ ret = 0; } else { ( (double *) buff )[ 1 ] = 0.0; } } } else if( type == AST__COMPLEXI ){ if( nc = 0, ( 1 != astSscanf( ostring, "%d %d %n", (int *) buff, (int *) buff + 1, &nc ) ) || (nc < len ) ){ if( nc = 0, ( 1 != astSscanf( ostring, "%d %n", (int *) buff, &nc ) ) || (nc < len ) ){ ret = 0; } else { ( (int *) buff )[ 1 ] = 0; } } } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } /* Convert an AST__INT data value to ... */ } else if( otype == AST__INT ){ oint = *( (int *) odata ); if( type == AST__FLOAT ){ *( (double *) buff ) = (double) oint; } else if( type == AST__STRING || type == AST__CONTINUE ){ (void) sprintf( cnvtype_text, "%d", oint ); *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ (void) memcpy( buff, odata, osize ); } else if( type == AST__LOGICAL ){ *( (int *) buff ) = oint ? 1 : 0; } else if( type == AST__COMPLEXF ){ ( (double *) buff )[ 0 ] = (double) oint; ( (double *) buff )[ 1 ] = 0.0; } else if( type == AST__COMPLEXI ){ ( (int *) buff )[ 0 ] = oint; ( (int *) buff )[ 1 ] = 0; } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } /* Convert a LOGICAL data value to ... */ } else if( otype == AST__LOGICAL ){ oint = *( (int *) odata ); if( type == AST__FLOAT ){ *( (double *) buff ) = oint ? 1.0 : 0.0; } else if( type == AST__STRING || type == AST__CONTINUE ){ if( oint ){ strcpy( cnvtype_text, "Y" ); } else { strcpy( cnvtype_text, "N" ); } *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ *( (int *) buff ) = oint; } else if( type == AST__LOGICAL ){ (void) memcpy( buff, odata, osize ); } else if( type == AST__COMPLEXF ){ ( (double *) buff )[ 0 ] = oint ? 1.0 : 0.0; ( (double *) buff )[ 1 ] = 0.0; } else if( type == AST__COMPLEXI ){ ( (int *) buff )[ 0 ] = oint ? 1 : 0; ( (int *) buff )[ 1 ] = 0; } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } /* Convert a AST__COMPLEXF data value to ... */ } else if( otype == AST__COMPLEXF ){ odouble = ( (double *) odata )[ 0 ]; if( type == AST__FLOAT ){ *( (double *) buff ) = odouble; } else if( type == AST__STRING || type == AST__CONTINUE ){ (void) sprintf( cnvtype_text0, "%.*g", DBL_DIG, ( (double *) odata )[ 0 ] ); CheckZero( cnvtype_text0, ( (double *) odata )[ 0 ], 0, status ); (void) sprintf( cnvtype_text1, "%.*g", DBL_DIG, ( (double *) odata )[ 1 ] ); CheckZero( cnvtype_text1, ( (double *) odata )[ 1 ], 0, status ); (void) sprintf( cnvtype_text, "%s %s", cnvtype_text0, cnvtype_text1 ); *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ *( (int *) buff ) = (int) odouble; } else if( type == AST__LOGICAL ){ *( (int *) buff ) = ( odouble == 0.0 ) ? 0 : 1; } else if( type == AST__COMPLEXF ){ (void) memcpy( buff, odata, osize ); } else if( type == AST__COMPLEXI ){ ( (int *) buff )[ 0 ] = (int) odouble; ( (int *) buff )[ 1 ] = (int) ( (double *) odata )[ 1 ]; } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } /* Convert a AST__COMPLEXI data value to ... */ } else if( otype == AST__COMPLEXI ){ oint = ( (int *) odata )[ 0 ]; if( type == AST__FLOAT ){ *( (double *) buff ) = (double) oint; } else if( type == AST__STRING || type == AST__CONTINUE ){ (void) sprintf( cnvtype_text, "%d %d", ( (int *) odata )[ 0 ], ( (int *) odata )[ 1 ] ); *( (char **) buff ) = cnvtype_text; } else if( type == AST__INT ){ *( (int *) buff ) = oint; } else if( type == AST__LOGICAL ){ *( (int *) buff ) = oint ? 1 : 0; } else if( type == AST__COMPLEXF ){ ( (double *) buff )[ 0 ] = (double) oint; ( (double *) buff )[ 1 ] = (double) ( (int *) odata )[ 1 ]; } else if( type == AST__COMPLEXI ){ (void) memcpy( buff, odata, osize ); } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } } else if( astOK ){ ret = 0; astError( AST__INTER, "CnvType: AST internal programming error - " "FITS data-type no. %d not yet supported.", status, type ); } } return ret; } static int ComBlock( AstFitsChan *this, int incr, const char *method, const char *class, int *status ){ /* * Name: * ComBlock * Purpose: * Delete a AST comment block in a Native-encoded FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int ComBlock( AstFitsChan *this, int incr, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function looks for a block of comment cards as defined below, * and deletes all the cards in the block, if a suitable block is found. * * Comment blocks consist of a contiguous sequence of COMMENT cards. The * text of each card should start and end with the 3 characters "AST". * The block is delimited above by a card containing all +'s (except * for the two "AST" strings), and below by a card containing all -'s. * * The block is assumed to start on the card which is adjacent to the * current card on entry. * Parameters: * this * Pointer to the FitsChan. * incr * This should be either +1 or -1, and is the increment between * adjacent cards in the comment block. A value of +1 means * that the card following the current card is taken as the first in * the block, and subsequent cards are checked. The block must then * end with a line of -'s. If -1 is supplied, then the card * preceding the current card is taken as the first in the block, * and preceding cards are checked. The block must then end with * a row of +'s. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * 1 if a block was found and deleted, 0 otherwise. * Notes: * - The pointer to the current card is returned unchanged. */ /* Local Variables: */ FitsCard *card0; /* Pointer to current FitsCard on entry */ char del; /* Delimiter character */ char *text; /* Pointer to the comment text */ int i; /* Card index within the block */ int ncard; /* No. of cards in the block */ int ret; /* The returned flag */ size_t len; /* Length of the comment text */ /* Check the global status. */ if( !astOK ) return 0; /* Save the pointer to the current card. */ card0 = this->card; /* Initialise the returned flag to indicate that we have not found a comment block. */ ret = 0; /* Move on to the first card in the block. If this is not possible (due to us already being at the start or end of the FitsChan), then return. */ if( MoveCard( this, incr, method, class, status ) == 1 ) { /* Store the character which is used in the delimiter line for the comment block. */ del = ( incr == 1 ) ? '-' : '+'; /* Initialise the number of cards in the comment block to zero. */ ncard = 0; /* Loop round until the end (or start) of the comment block is found. Leave the loop if an error occurs. */ while( astOK ) { /* Is this card a comment card? If not, then we have failed to find a complete comment block. Break out of the loop. */ if( CardType( this, status ) != AST__COMMENT ) break; /* Increment the number of cards in the comment block. */ ncard++; /* Get the text of the comment, and its length. */ text = CardComm( this, status ); if( text ){ len = strlen( text ); /* Check the first 3 characters. Break out of the loop if they are not "AST". */ if( strncmp( "AST", text, 3 ) ) break; /* Check the last 3 characters. Break out of the loop if they are not "AST". */ if( strcmp( "AST", text + len - 3 ) ) break; /* If the comment is the appropriate block delimiter (a line of +'s or -'s depending on the direction), then set the flag to indicate that we have a complete comment block and leave the loop. Allow spaces to be included. Exclude the "AST" strings at begining and end from the check. */ ret = 1; for( i = 3; i < len - 3; i++ ) { if( text[ i ] != del && text[ i ] != ' ' ) { ret = 0; break; } } } if( ret ) break; /* Move on to the next card. If this is not possible (due to us already being at the start or end of the FitsChan), then break out of the loop. */ if( MoveCard( this, incr, method, class, status ) == 0 ) break; } /* Re-instate the original current card. */ this->card = card0; /* If we found a complete comment block, mark it (which is equivalent to deleting it except that memory of the cards location within the FitsChan is preserved for future use), and then re-instate the original current card. */ if( ret && astOK ) { for( i = 0; i < ncard; i++ ) { MoveCard( this, incr, method, class, status ); MarkCard( this, status ); } this->card = card0; } } /* If an error occurred, indicate that coment block has been deleted. */ if( !astOK ) ret = 0; return ret; } static char *ConcatWAT( AstFitsChan *this, int iaxis, const char *method, const char *class, int *status ){ /* * Name: * ConcatWAT * Purpose: * Concatenate all the IRAF "WAT" keywords for an axis. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *ConcatWAT( AstFitsChan *this, int iaxis, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function searches the supplied FitsChan for any keywords of * the form "WATi_j", where i and j are integers and i is equal to the * supplied "iaxis" value plus one, and concatenates their string * values into a single string. Such keywords are created by IRAF to * describe their non-standard ZPX and TNX projections. * Parameters: * this * The FistChan. * iaxis * The zero-based index of the axis to be retrieved. * method * The name of the calling method to include in error messages. * class * The object type to include in error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated, null terminated string * containing a copy of the concatentated WAT values. This string must * be freed by the caller (using astFree) when no longer required. * * A NULL pointer will be returned if there are no WAT kewyords for * the requested axis in the FitsChan. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ char keyname[ FITSNAMLEN + 5 ];/* Keyword name */ char *wat; /* Pointer to a single WAT string */ char *result; /* Returned string */ int watlen; /* Length of total WAT string (inc. term null)*/ int j; /* WAT index */ size_t size; /* Length of string value */ /* Initialise returned value. */ result = NULL; /* Check inherited status */ if( !astOK ) return result; /* Rewind the FitsChan. */ astClearCard( this ); /* Concatenate all the IRAF "WAT" keywords together for this axis. These keywords are marked as having been used, so that they are not written out when the FitsChan is deleted. */ watlen = 1; j = 1; size = 0; sprintf( keyname, "WAT%d_%.3d", iaxis + 1, j ); while( astOK ) { /* Search forward from the current card for the next WAT card. If no found, try searching again from the start of the FitsChan. If not found evenm then, break. */ if( ! FindKeyCard( this, keyname, method, class, status ) ) { astClearCard( this ); if( ! FindKeyCard( this, keyname, method, class, status ) ) break; } wat = (char *) CardData( this, &size, status ); result = (char *) astRealloc( (void *) result, watlen - 1 + size ); if( result ) { strcpy( result + watlen - 1, wat ); watlen += size - 1; MarkCard( this, status ); MoveCard( this, 1, method, class, status ); j++; sprintf( keyname, "WAT%d_%.3d", iaxis + 1, j ); } else { break; } } /* Return the result. */ return result; } static int CountFields( const char *temp, char type, const char *method, const char *class, int *status ){ /* * Name: * CountFields * Purpose: * Count the number of field specifiers in a template string. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int CountFields( const char *temp, char type, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns the number of fields which include the * specified character type in the supplied string. * Parameters: * temp * Pointer to a null terminated string holding the template. * type * A single character giving the field type to be counted (e.g. * 'd', 'c' or 'f'). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The number of fields. * Notes: * - No error is reported if the parameter "type" is not a valid * field type specifier, but zero will be returned. * - An error is reported if the template has any invalid field * specifiers in it. * - A value of zero is returned if an error has already occurred, * or if this function should fail for any reason. */ /* Local Variables: */ const char *b; /* Pointer to next template character */ int nf; /* No. of fields found so far */ /* Check global status. */ if( !astOK ) return 0; /* Initialise a pointer to the start of the template string. */ b = temp; /* Initialise the number of fields found so far. */ nf = 0; /* Go through the string. */ while( *b && astOK ){ /* If the current character is a '%', a field is starting. */ if( *b == '%' ){ /* Skip over the field width (if supplied). */ if( isdigit( (int) *(++b) ) ) b++; /* Report an error if the end of the string occurs within the field. */ if( !*b ) { astError( AST__BDFMT, "%s(%s): Incomplete field specifier found " "at end of filter template '%s'.", status, method, class, temp ); break; /* Report an error if the field type is illegal. */ } else if( *b != 'd' && *b != 'c' && *b != 'f' ) { astError( AST__BDFMT, "%s(%s): Illegal field type or width " "specifier '%c' found in filter template '%s'.", status, method, class, *b, temp ); break; } /* Compare the field type with the supplied type, and increment the number of fields found if it is the correct type. */ if( *b == type ) nf++; } /* Move on to the next character. */ b++; } /* If an error has occurred, return 0. */ if( !astOK ) nf = 0; /* Return the answer. */ return nf; } static void CreateKeyword( AstFitsChan *this, const char *name, char keyword[ FITSNAMLEN + 1 ], int *status ){ /* * Name: * CreateKeyword * Purpose: * Create a unique un-used keyword for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void CreateKeyword( AstFitsChan *this, const char *name, * char keyword[ FITSNAMLEN + 1 ], int *status ) * Class Membership: * FitsChan member function. * Description: * This function takes a name which forms the basis of a FITS * keyword and appends a sequence number (encoded as a pair of * legal FITS keyword characters) so as to generate a unique FITS * keyword which has not previously been used in the FitsChan * supplied. * * It is intended for use when several keywords with the same name * must be stored in a FitsChan, since to comply strictly with the * FITS standard keywords should normally be unique (otherwise * external software which processes the keywords might omit one or * other of the values). * * An attempt is also made to generate keywords in a form that is * unlikely to clash with those from other sources (in as far as * this is possible with FITS). In any event, a keyword that * already appears in the FitsChan will not be re-used. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a constant null-terminated string containing the * name on which the new keyword should be based. This should be * a legal FITS keyword in itself, except that it should be at * least two characters shorter than the maximum length, in * order to accommodate the sequence number characters. * * If this string is too long, it will be silently * truncated. Mixed case is permitted, as all characters * supplied are converted to upper case before use. * keyword * A character array in which the generated unique keyword will * be returned, null terminated. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *seq_chars = SEQ_CHARS;/* Pointer to characters used for encoding */ char seq_char; /* The first sequence character */ const char *class; /* Object clas */ int found; /* Keyword entry found in list? */ int limit; /* Sequence number has reached limit? */ int nc; /* Number of basic keyword characters */ int seq; /* The sequence number */ /* Check the global error status. */ if( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Store the object class. */ class = astGetClass( this ); /* On the first invocation only, determine the number of characters being used to encode sequence number information and save this value. */ if( createkeyword_seq_nchars < 0 ) createkeyword_seq_nchars = (int) strlen( seq_chars ); /* Copy the name supplied into the output array, converting to upper case. Leave space for two characters to encode a sequence number. Terminate the resulting string. */ for( nc = 0; ( nc < ( FITSNAMLEN - 2 ) ) && name[ nc ]; nc++ ) { keyword[ nc ] = toupper( name[ nc ] ); } keyword[ nc ] = '\0'; /* We now search the list of sequence numbers already allocated to find the next one to use for this keyword. */ if( this->keyseq ) { found = astMapGet0I( this->keyseq, keyword, &seq ); } else { found = 0; this->keyseq = astKeyMap( " ", status ); } /* If the keyword was not found in the list, create a new list entry to describe it. */ if( !found ) seq = 0; /* If OK, loop to find a new sequence number which results in a FITS keyword that hasn't already been used to store data in the FitsChan. */ if( astOK ) { while( 1 ) { /* Determine if the sequence number just obtained has reached the upper limit. This is unlikely to happen in practice, but if it does, we simply re-use this maximum value. Otherwise, we increment the sequence number last used for this keyword to obtain a new one. */ limit = ( seq >= ( createkeyword_seq_nchars * createkeyword_seq_nchars - 1 ) ); if( !limit ) seq++; /* Encode the sequence number into two characters and append them to the original keyword (with a terminating null). */ seq_char = seq_chars[ seq / createkeyword_seq_nchars ]; keyword[ nc ] = seq_char; keyword[ nc + 1 ] = seq_chars[ seq % createkeyword_seq_nchars ]; keyword[ nc + 2 ] = '\0'; /* If the upper sequence number limit has not been reached, try to look up the resulting keyword in the FitsChan to see if it has already been used. Quit searching when a suitable keyword is found. */ if ( limit || !HasCard( this, keyword, "astWrite", class, status ) ) break; } /* Store the update sequence number in the keymap. The keys into this keymap are the base keyword name without the appended sequence string, so temporaily terminate the returned keyword name to exclude the sequence string. */ keyword[ nc ] = '\0'; astMapPut0I( this->keyseq, keyword, seq, NULL ); keyword[ nc ] = seq_char; } } static double DateObs( const char *dateobs, int *status ) { /* * Name: * DateObs * Purpose: * Convert a FITS DATE-OBS keyword value to a MJD. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double DateObs( const char *dateobs, int *status ) * Class Membership: * FitsChan member function. * Description: * Extracts the date and time fields from the supplied string and converts * them into a modified Julian Date. Supports both old "dd/mm/yy" * format, and the new "ccyy-mm-ddThh:mm:ss[.sss...]" format. * Parameters: * dateobs * Pointer to the DATE-OBS string. * status * Pointer to the inherited status variable. * Returned Value: * The Modified Julian Date corresponding to the supplied DATE-OBS * string. * Notes: * - The value AST__BAD is returned (without error) if the supplied * string does not conform to the requirements of a FITS DATE-OBS value, * or if an error has already occurred. */ /* Local Variables: */ double days; /* The hours, mins and secs as a fraction of a day */ double ret; /* The returned MJD value */ double secs; /* The total value of the two seconds fields */ int dd; /* The day field from the supplied string */ int fsc; /* The fractional seconds field from the supplied string */ int hr; /* The hour field from the supplied string */ int j; /* SLALIB status */ int len; /* The length of the supplied string */ int mm; /* The month field from the supplied string */ int mn; /* The minute field from the supplied string */ int nc; /* Number of characters used */ int ok; /* Was the string of a legal format? */ int rem; /* The least significant digit in fsc */ int sc; /* The whole seconds field from the supplied string */ int yy; /* The year field from the supplied string */ /* Check the global status. */ if( !astOK ) return AST__BAD; /* Initialise the returned value. */ ret = AST__BAD; /* Save the length of the supplied string. */ len = (int) strlen( dateobs ); /* Extract the year, month, day, hour, minute, second and fractional seconds fields from the supplied string. Assume initially that the string does not match any format. */ ok = 0; /* First check for the old "dd/mm/yy" format. */ if( nc = 0, ( astSscanf( dateobs, " %2d/%2d/%d %n", &dd, &mm, &yy, &nc ) == 3 ) && ( nc >= len ) ){ ok = 1; hr = 0; mn = 0; sc = 0; fsc = 0; /* Otherwise, check for the new short format "ccyy-mm-dd". */ } else if( nc = 0, ( astSscanf( dateobs, " %4d-%2d-%2d %n", &yy, &mm, &dd, &nc ) == 3 ) && ( nc >= len ) ){ ok = 1; hr = 0; mn = 0; sc = 0; fsc = 0; /* Otherwise, check for the new format "ccyy-mm-ddThh:mm:ss" without a fractional seconds field or the trailing Z. */ } else if( nc = 0, ( astSscanf( dateobs, " %4d-%2d-%2dT%2d:%2d:%2d %n", &yy, &mm, &dd, &hr, &mn, &sc, &nc ) == 6 ) && ( nc >= len ) ){ ok = 1; fsc = 0; /* Otherwise, check for the new format "ccyy-mm-ddThh:mm:ss.sss" with a fractional seconds field but without the trailing Z. */ } else if( nc = 0, ( astSscanf( dateobs, " %4d-%2d-%2dT%2d:%2d:%2d.%d %n", &yy, &mm, &dd, &hr, &mn, &sc, &fsc, &nc ) == 7 ) && ( nc >= len ) ){ ok = 1; /* Otherwise, check for the new format "ccyy-mm-ddThh:mm:ssZ" without a fractional seconds field but with the trailing Z. */ } else if( nc = 0, ( astSscanf( dateobs, " %4d-%2d-%2dT%2d:%2d:%2dZ %n", &yy, &mm, &dd, &hr, &mn, &sc, &nc ) == 6 ) && ( nc >= len ) ){ ok = 1; fsc = 0; /* Otherwise, check for the new format "ccyy-mm-ddThh:mm:ss.sssZ" with a fractional seconds field and the trailing Z. */ } else if( nc = 0, ( astSscanf( dateobs, " %4d-%2d-%2dT%2d:%2d:%2d.%dZ %n", &yy, &mm, &dd, &hr, &mn, &sc, &fsc, &nc ) == 7 ) && ( nc >= len ) ){ ok = 1; } /* If the supplied string was legal, create a MJD from the separate fields. */ if( ok ) { /* Get the MJD at the start of the day. */ palCaldj( yy, mm, dd, &ret, &j ); /* If succesful, convert the hours, minutes and seconds to a fraction of a day, and add it onto the MJD found above. */ if( j == 0 ) { /* Obtain a floating point representation of the fractional seconds field. */ secs = 0.0; while ( fsc > 0 ) { rem = ( fsc % 10 ); fsc /= 10; secs = 0.1 * ( secs + (double) rem ); } /* Add on the whole seconds field. */ secs += (double) sc; /*Convert the hours, minutes and seconds to a fractional day. */ palDtf2d( hr, mn, secs, &days, &j ); /* If succesful, add this onto the returned MJD. */ if( j == 0 ) { ret = ret + days; /* If the conversion to MJD failed, return AST__BAD. */ } else { ret = AST__BAD; } } else { ret = AST__BAD; } } /* Return the result. */ return ret; } static void DeleteCard( AstFitsChan *this, const char *method, const char *class, int *status ){ /* * Name: * DeleteCard * Purpose: * Delete the current card from a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void DeleteCard( AstFitsChan *this, const char *method, * const char *class ) * Class Membership: * FitsChan member function. * Description: * The current card is removed from the circular linked list of structures * stored in the supplied FitsChan, and the memory used to store the * structure is then freed. * Parameters: * this * Pointer to the FitsChan containing the list. * method * Name of calling method. * class * Object class. * Notes: * - This function returns without action if the FitsChan is * currently at "end-of-file". * - The next card becomes the current card. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ FitsCard *card; /* Pointer to the current card */ FitsCard *next; /* Pointer to next card in list */ FitsCard *prev; /* Pointer to previous card in list */ /* Return if the supplied object or current card is NULL. */ if( !this || !this->card ) return; /* Get a pointer to the card to be deleted (the current card). */ card = (FitsCard *) this->card; /* Remove it from the KeyMap holding all keywords. */ astMapRemove( this->keywords, card->name ); /* Move the current card on to the next card. */ MoveCard( this, 1, method, class, status ); /* Save pointers to the previous and next cards in the list. */ prev = GetLink( card, PREVIOUS, method, class, status ); next = GetLink( card, NEXT, method, class, status ); /* If the backwards link points back to the supplied card, then it must be the only one left on the list. */ if( prev == card ) prev = NULL; if( next == card ) next = NULL; /* If the list head is to be deleted, store a value for the new list head. */ if( this->head == (void *) card ) this->head = (void *) next; /* Free the memory used to hold the data value. */ (void) astFree( card->data ); /* Free the memory used to hold any comment. */ if( card->comment ) (void) astFree( (void *) card->comment ); /* Free the memory used to hold the whole structure. */ (void) astFree( (void *) card ); /* Fix up the links between the two adjacent cards in the list, unless the supplied card was the last one in the list. */ if( prev && next ){ next->prev = prev; prev->next = next; } else { this->head = NULL; this->card = NULL; } /* Return. */ return; } static void DelFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astDelFits f AST_DELFITS * Purpose: * Delete the current FITS card in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astDelFits( AstFitsChan *this ) f CALL AST_DELFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function deletes the current FITS card from a FitsChan. The f This routine deletes the current FITS card from a FitsChan. The * current card may be selected using the Card attribute (if its index c is known) or by using astFindFits (if only the FITS keyword is f is known) or by using AST_FINDFITS (if only the FITS keyword is * known). * * After deletion, the following card becomes the current card. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - This function returns without action if the FitsChan is * initially positioned at the "end-of-file" (i.e. if the Card * attribute exceeds the number of cards in the FitsChan). * - If there are no subsequent cards in the FitsChan, then the * Card attribute is left pointing at the "end-of-file" after * deletion (i.e. is set to one more than the number of cards in * the FitsChan). *-- */ /* Check the global error status. */ if ( !astOK ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Delete the current card. The next card will be made the current card. */ DeleteCard( this, "astDelFits", astGetClass( this ), status ); } static void DistortMaps( AstFitsChan *this, FitsStore *store, char s, int naxes, AstMapping **map1, AstMapping **map2, AstMapping **map3, AstMapping **map4, const char *method, const char *class, int *status ){ /* * Name: * DistortMap * Purpose: * Create a Mapping representing a FITS-WCS Paper IV distortion code. * Type: * Private function. * Synopsis: * void DistortMaps( AstFitsChan *this, FitsStore *store, char s, * int naxes, AstMapping **map1, AstMapping **map2, * AstMapping **map3, AstMapping **map4, * const char *method, const char *class ) * Class Membership: * FitsChan * Description: * This function checks the CTYPE keywords in the supplied FitsStore to see * if they contain a known distortion code (following the syntax described * in FITS-WCS paper IV). If so, Mappings are returned which represent the * distortions to be applied at each stage in the pixel->IWC chain. If * any distortion codes are found in the FitsStore CTYPE values, whether * recognised or not, the CTYPE values in the FitsStore are modified to * remove the distortion code. Warnings about any unknown or inappropriate * distortion codes are added to the FitsChan. * Parameters: * this * The FitsChan. ASTWARN cards may be added to this FitsChan if any * anomalies are found in the keyword values in the FitsStore. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * map1 * Address of a location at which to store a pointer to a Mapping * which describes any distortion to be applied to pixel * coordinates, prior to performing the translation specified by the * CRPIXj keywords. NULL is returned if no distortion is necessary. * map2 * Address of a location at which to store a pointer to a Mapping * which describes any distortion to be applied to translated pixel * coordinates, prior to performing the PC matrix multiplication. * NULL is returned if no distortion is necessary. * map3 * Address of a location at which to store a pointer to a Mapping * which describes any distortion to be applied to unscaled IWC * coordinates, prior to performing the CDELT matrix multiplication. * NULL is returned if no distortion is necessary. * map4 * Address of a location at which to store a pointer to a Mapping * which describes any distortion to be applied to scaled IWC * coordinates, after performing the CDELT matrix multiplication. * NULL is returned if no distortion is necessary. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. */ /* Local Variables: */ AstMapping *tmap1; /* Mapping pointer */ AstMapping *tmap2; /* Mapping pointer */ char *ctype; /* Pointer to CTYPE value */ char code[ 4 ]; /* Projection code extracted from CTYPE */ char dist[ 4 ]; /* Distortion code extracted from CTYPE */ char msgbuf[ 250 ]; /* Buffer for warning message */ char type[ 5 ]; /* Axis type extracted from CTYPE */ double *dim; /* Array holding array dimensions */ int found_axes[ 2 ]; /* Index of axes with the distortion code */ int i; /* FITS axis index */ int nc; /* No. of characters in CTYPE without "-SIP" */ int nfound; /* No. of axes with the distortion code */ int warned; /* Have any ASTWARN cards been issued? */ /* Initialise pointers to the returned Mappings. */ *map1 = NULL; *map2 = NULL; *map3 = NULL; *map4 = NULL; /* Check the global status. */ if ( !astOK ) return; /* Allocate memory to hold the image dimensions. */ dim = (double *) astMalloc( sizeof(double)*naxes ); if( dim ){ /* Note the image dimensions, if known. If not, store AST__BAD values. */ for( i = 0; i < naxes; i++ ){ if( !astGetFitsF( this, FormatKey( "NAXIS", i + 1, -1, ' ', status ), dim + i ) ) dim[ i ] = AST__BAD; } /* First check each known distortion type... */ /* "-SIP": Spitzer (http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf) ============= */ /* Spitzer distortion is limited to 2D. Check the first two axes to see if they have "-SIP" codes at the end of their CTYPE values. If they do, terminate the ctype string in order to exclude the distortion code (this is so that later functions do not need to allow for the possibility of a distortion code being present in the CTYPE value). */ ctype = GetItemC( &(store->ctype), 0, 0, s, NULL, method, class, status ); if( ctype ){ nc = astChrLen( ctype ) - 4; if( nc >= 0 && !strcmp( ctype + nc, "-SIP" ) ) { ctype[ nc ] = 0; ctype = GetItemC( &(store->ctype), 1, 0, s, NULL, method, class, status ); if( ctype ) { nc = astChrLen( ctype ) - 4; if( nc >= 0 && !strcmp( ctype + nc, "-SIP" ) ) { ctype[ nc ] = 0; /* Create a Mapping describing the distortion (other axes are passed unchanged by this Mapping), and add it in series with the returned map2 (Spitzer distortion is applied to the translated pixel coordinates). */ tmap1 = SIPMapping( dim, store, s, naxes, method, class, status ); if( ! *map2 ) { *map2 = tmap1; } else { tmap2 = (AstMapping *) astCmpMap( *map2, tmap1, 1, "", status ); *map2 = astAnnul( *map2 ); tmap1 = astAnnul( tmap1 ); *map2 = tmap2; } } } } } /* Check that the "-SIP" code is not included in any axes other than axes 0 and 1. Issue a warning if it is, and remove it. */ warned = 0; for( i = 2; i < naxes; i++ ){ ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( ctype ){ nc = astChrLen( ctype ) - 4; if( nc >= 0 && !strcmp( ctype + nc, "-SIP" ) ) { if( !warned ){ warned = 1; sprintf( msgbuf, "The \"-SIP\" distortion code can only be " "used on axes 1 and 2, but was found in keyword " "%s (='%s'). The distortion will be ignored.", FormatKey( "CTYPE", i + 1, -1, ' ', status ), ctype ); Warn( this, "distortion", msgbuf, method, class, status ); } ctype[ nc ] = 0; } } } /* "-ZPX": IRAF (http://iraf.noao.edu/projects/ccdmosaic/zpx.html) ============= */ /* An IRAF ZPX header uses a ZPX projection within each CTYPE value in place of the basic ZPN projection. The SpecTrans function converts -ZPX" to "-ZPN-ZPX" (i.e. a basic projection of ZPN with a distortion code of "-ZPX"). This function then traps and processes the "-ZPX" distortion code. */ /* Look for axes that have the "-ZPX" code in their CTYPE values. If any are found, check that there are exactly two such axes, and terminate the ctype strings in order to exclude the distortion code (this is so that later functions do not need to allow for the possibility of a distortion code being present in the CTYPE value)*/ nfound = 0; for( i = 0; i < naxes; i++ ){ ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( ctype && 3 == astSscanf( ctype, "%4s-%3s-%3s", type, code, dist ) ){ if( !strcmp( "ZPX", dist ) ){ if( nfound < 2 ) found_axes[ nfound ] = i; nfound++; ctype[ 8 ] = 0; } } } /* Issue a warning if more than two ZPX axes were found. */ if( nfound > 2 ) { Warn( this, "distortion", "More than two axes were found " "with the \"-ZPX\" projection code. A ZPN projection " "will be used instead.", method, class, status ); /* Otherwise, create a Mapping describing the distortion (other axes are passed unchanged by this Mapping), and add it in series with the returned map4 (ZPX distortion is applied to the translated, rotated, scaled IWC coordinates). */ } else if( nfound == 2 ){ tmap1 = ZPXMapping( this, store, s, naxes, found_axes, method, class, status ); if( ! *map4 ) { *map4 = tmap1; } else { tmap2 = (AstMapping *) astCmpMap( *map4, tmap1, 1, "", status ); *map4 = astAnnul( *map4 ); tmap1 = astAnnul( tmap1 ); *map4 = tmap2; } } /* (There are currently no other supported distortion codes.) */ /* Finally, check all axes looking for any remaining (and therefore unsupported) distortion codes. Issue a warning about them and remove them. =================================================================== */ /* Indicate that we have not yet issued a warning. */ warned = 0; /* Do each IWC axis. */ for( i = 0; i < naxes; i++ ){ /* Get the CTYPE value for this axis. */ ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( ctype ) { /* See if has the "4-3-3" form described in FITS-WCS paper IV. */ if( 3 == astSscanf( ctype, "%4s-%3s-%3s", type, code, dist ) ){ /* Add an ASTWARN card to the FitsChan. Only issue one warning (this avoids multiple warnings about the same distortion code in multiple CTYPE values). */ if( !warned ){ warned = 1; sprintf( msgbuf, "The header contains CTYPE values (e.g. " "%s = '%s') which " "include a distortion code \"-%s\". AST " "currently ignores this distortion. The code " "has been removed from the CTYPE values.", FormatKey( "CTYPE", i + 1, -1, ' ', status ), ctype, dist ); Warn( this, "distortion", msgbuf, method, class, status ); } /* Terminate the CTYPE value in the FitsStore in order to exclude the distortion code. This means that later functions will not need to take account of distortion codes. */ ctype[ 8 ] = 0; } } } } /* Free resources. */ dim = astFree( dim ); } static void DSBSetUp( AstFitsChan *this, FitsStore *store, AstDSBSpecFrame *dsb, char s, double crval, const char *method, const char *class, int *status ){ /* * Name: * DSBSetUp * Purpose: * Modify an AstDSBSpecFrame object to reflect the contents of a FitsStore. * Type: * Private function. * Synopsis: * void DSBSetUp( AstFitsChan *this, FitsStore *store, * AstDSBSpecFrame *dsb, char s, double crval, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function sets the attributes of the supplied DSBSpecFrame to * reflect the values in the supplied FitsStore. * Parameters: * this * The FitsChan. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * dsb * Pointer to the DSBSpecFrame. * s * Alternate axis code. * crval * The spectral CRVAL value, in the spectral system represented by * the supplied DSBSPecFrame. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This implementation follows the conventions of the FITS-CLASS encoding. */ /* Local Variables: */ AstDSBSpecFrame *dsb_src; /* New DSBSpecFrame in which StdOfRest is source */ AstDSBSpecFrame *dsb_topo;/* New DSBSpecFrame in which StdOfRest is topo */ AstFrameSet *fs; /* FrameSet connecting two standards of rest */ double dsbcentre; /* Topocentric reference (CRVAL) frequency */ double in[2]; /* Source rest and image frequencies */ double lo; /* Topocentric Local Oscillator frequency */ double out[2]; /* Topocentric rest and image frequencies */ /* Check the global status. */ if ( !astOK ) return; /* In order to determine the topocentric IF, we need the topocentric frequencies corresponding to the RESTFREQ and IMAGFREQ values in the FITS header. The values stored in the FITS header are measured in Hz, in the source's rest frame, so we need a mapping from frequency in the source rest frame to topocentric frequency. Take a copy of the supplied DSBSpecFrame and then set its attributes to represent frequency in the sources rest frame. */ dsb_src = astCopy( dsb ); astSetStdOfRest( dsb_src, AST__SCSOR ); astSetSystem( dsb_src, AST__FREQ ); astSetUnit( dsb_src, 0, "Hz" ); /* Take a copy of this DSBSpecFrame and set its standard of rest to topocentric. */ dsb_topo = astCopy( dsb_src ); astSetStdOfRest( dsb_topo, AST__TPSOR ); /* Now get the Mapping between these. */ fs = astConvert( dsb_src, dsb_topo, "" ); dsb_src = astAnnul( dsb_src ); dsb_topo = astAnnul( dsb_topo ); /* Check a conversion was found. */ if( fs != NULL ) { /* Use this Mapping to transform the rest frequency and the image frequency from the standard of rest of the source to that of the observer. */ in[ 0 ] = astGetRestFreq( dsb ); in[ 1 ] = GetItem( &(store->imagfreq), 0, 0, s, NULL, method, class, status ); astTran1( fs, 2, in, 1, out ); /* The intermediate frequency is half the distance between these two frequencies. Note, the IF value is signed so as to put the rest frequency in the observed sideband. */ if( out[ 0 ] != AST__BAD && out[ 1 ] != AST__BAD ) { /* Store the spectral CRVAL value as the centre frequency of the DSBSpecFrame. The public astSetD method interprets the supplied value as a value in the spectral system described by the other SpecFrame attributes. */ astSetD( dsb, "DSBCentre", crval ); /* To calculate the topocentric IF we need the topocentric frequency equivalent of CRVAL. So take a copy of the DSBSpecFrame, then set it to represent topocentric frequency, and read back the DSBCentre value. */ dsb_topo = astCopy( dsb ); astSetStdOfRest( dsb_topo, AST__TPSOR ); astSetSystem( dsb_topo, AST__FREQ ); astSetUnit( dsb_topo, 0, "Hz" ); dsbcentre = astGetD( dsb_topo, "DSBCentre" ); dsb_topo = astAnnul( dsb_topo ); /* We also need the topocentric Local Oscillator frequency. This is assumed to be half way between the topocentric IMAGFREQ and RESTFREQ values. */ lo = 0.5*( out[ 1 ] + out[ 0 ] ); /* Set the IF to be the difference between the Local Oscillator frequency and the CRVAL frequency. */ astSetIF( dsb, lo - dsbcentre ); /* Set the DSBSpecFrame to represent the observed sideband */ astSetC( dsb, "SideBand", "observed" ); } /* Free resources. */ fs = astAnnul( fs ); } } static int DSSFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * DSSFromStore * Purpose: * Store WCS keywords in a FitsChan using DSS encoding. * Type: * Private function. * Synopsis: * int DSSFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using DSS encoding. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ const char *comm; /* Pointer to comment string */ char *cval; /* Pointer to string keyword value */ const char *pltdecsn;/* PLTDECSN keyword value */ double amdx[20]; /* AMDXi keyword value */ double amdy[20]; /* AMDYi keyword value */ double cdelt; /* CDELT element */ double cnpix1; /* CNPIX1 keyword value */ double cnpix2; /* CNPIX2 keyword value */ double pc; /* PC element */ double pltdecd; /* PLTDECD keyword value */ double pltdecm; /* PLTDECM keyword value */ double pltdecs; /* PLTDECS keyword value */ double pltrah; /* PLTRAH keyword value */ double pltram; /* PLTRAM keyword value */ double pltras; /* PLTRAS keyword value */ double pltscl; /* PLTSCL keyword value */ double ppo1; /* PPO1 keyword value */ double ppo2; /* PPO2 keyword value */ double ppo3; /* PPO3 keyword value */ double ppo4; /* PPO4 keyword value */ double ppo5; /* PPO5 keyword value */ double ppo6; /* PPO6 keyword value */ double pvx[22]; /* X projection parameter values */ double pvy[22]; /* Y projection parameter values */ double val; /* General purpose value */ double xpixelsz; /* XPIXELSZ keyword value */ double ypixelsz; /* YPIXELSZ keyword value */ int i; /* Loop count */ int gottpn; /* Is the projection a "TPN" projection? */ int m; /* Parameter index */ int ret; /* Returned value. */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Check the image is 2 dimensional. */ if( GetMaxJM( &(store->crpix), ' ', status ) != 1 ) return ret; /* Check the first axis is RA with a TAN or TPN projection. */ cval = GetItemC( &(store->ctype), 0, 0, ' ', NULL, method, class, status ); if( !cval ) return ret; gottpn = !strcmp( "RA---TPN", cval ); if( strcmp( "RA---TAN", cval ) && !gottpn ) return ret; /* Check the second axis is DEC with a TAN or TPN projection. */ cval = GetItemC( &(store->ctype), 1, 0, ' ', NULL, method, class, status ); if( !cval ) return ret; if( gottpn ) { if( strcmp( "DEC--TPN", cval ) ) return ret; } else { if( strcmp( "DEC--TAN", cval ) ) return ret; } /* Check that LONPOLE is undefined or is 180 degrees. */ val = GetItem( &(store->lonpole), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD && val != 180.0 ) return ret; /* Check that the RA/DEC system is FK5. */ cval = GetItemC( &(store->radesys), 0, 0, ' ', NULL, method, class, status ); if( !cval || strcmp( "FK5", cval ) ) return ret; /* Check that equinox is not defined or is 2000.0 */ val = GetItem( &(store->equinox), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD && val != 2000.0 ) return ret; /* Get the pixel sizes from the PC/CDELT keywords. They must be defined and not be zero. */ cdelt = GetItem( &(store->cdelt), 0, 0, ' ', NULL, method, class, status ); if( cdelt == AST__BAD ) return ret; pc = GetItem( &(store->pc), 0, 0, ' ', NULL, method, class, status ); if( pc == AST__BAD ) pc = 1.0; xpixelsz = cdelt*pc; cdelt = GetItem( &(store->cdelt), 1, 0, ' ', NULL, method, class, status ); if( cdelt == AST__BAD ) return ret; pc = GetItem( &(store->pc), 1, 1, ' ', NULL, method, class, status ); if( pc == AST__BAD ) pc = 1.0; ypixelsz = cdelt*pc; if( xpixelsz == 0.0 || ypixelsz == 0.0 ) return ret; xpixelsz *= -1000.0; ypixelsz *= 1000.0; /* Check the off-diagonal PC terms are zero. DSS does not allow any rotation. */ val = GetItem( &(store->pc), 0, 1, ' ', NULL, method, class, status ); if( val != AST__BAD && val != 0.0 ) return ret; val = GetItem( &(store->pc), 1, 0, ' ', NULL, method, class, status ); if( val != AST__BAD && val != 0.0 ) return ret; /* Get the required projection parameter values from the store, supplying appropriate values if a simple TAN projection is being used. */ for( m = 0; m < 22; m++ ){ pvx[ m ] = GetItem( &(store->pv), 0, m, ' ', NULL, method, class, status ); if( pvx[ m ] == AST__BAD || !gottpn ) pvx[ m ] = ( m == 1 ) ? 1.0 : 0.0; pvy[ m ] = GetItem( &(store->pv), 1, m, ' ', NULL, method, class, status ); if( pvy[ m ] == AST__BAD || !gottpn ) pvy[ m ] = ( m == 1 ) ? 1.0 : 0.0; } /* Check that no other projection parameters have been set. */ if( GetMaxJM( &(store->pv), ' ', status ) > 21 ) return ret; /* Check that specific parameters take their required zero value. */ if( pvx[ 3 ] != 0.0 || pvy[ 3 ] != 0.0 ) return ret; for( m = 11; m < 17; m++ ){ if( pvx[ m ] != 0.0 || pvy[ m ] != 0.0 ) return ret; } if( pvx[ 18 ] != 0.0 || pvy[ 18 ] != 0.0 ) return ret; if( pvx[ 20 ] != 0.0 || pvy[ 20 ] != 0.0 ) return ret; /* Check that other projection parameters are related correctly. */ if( !astEQUAL( 2*pvx[ 17 ], pvx[ 19 ] ) ) return ret; if( !astEQUAL( pvx[ 17 ], pvx[ 21 ] ) ) return ret; if( !astEQUAL( 2*pvy[ 17 ], pvy[ 19 ] ) ) return ret; if( !astEQUAL( pvy[ 17 ], pvy[ 21 ] ) ) return ret; /* Initialise all polynomial co-efficients to zero. */ for( m = 0; m < 20; m++ ){ amdx[ m ] = 0.0; amdy[ m ] = 0.0; } /* Polynomial co-efficients. There is redundancy here too, so we arbitrarily choose to leave AMDX/Y7 and AMDX/Y12 set to zero. */ amdx[ 0 ] = 3600.0*pvx[ 1 ]; amdx[ 1 ] = 3600.0*pvx[ 2 ]; amdx[ 2 ] = 3600.0*pvx[ 0 ]; amdx[ 3 ] = 3600.0*pvx[ 4 ]; amdx[ 4 ] = 3600.0*pvx[ 5 ]; amdx[ 5 ] = 3600.0*pvx[ 6 ]; amdx[ 7 ] = 3600.0*pvx[ 7 ]; amdx[ 8 ] = 3600.0*pvx[ 8 ]; amdx[ 9 ] = 3600.0*pvx[ 9 ]; amdx[ 10 ] = 3600.0*pvx[ 10 ]; amdx[ 12 ] = 3600.0*pvx[ 17 ]; amdy[ 0 ] = 3600.0*pvy[ 1 ]; amdy[ 1 ] = 3600.0*pvy[ 2 ]; amdy[ 2 ] = 3600.0*pvy[ 0 ]; amdy[ 3 ] = 3600.0*pvy[ 4 ]; amdy[ 4 ] = 3600.0*pvy[ 5 ]; amdy[ 5 ] = 3600.0*pvy[ 6 ]; amdy[ 7 ] = 3600.0*pvy[ 7 ]; amdy[ 8 ] = 3600.0*pvy[ 8 ]; amdy[ 9 ] = 3600.0*pvy[ 9 ]; amdy[ 10 ] = 3600.0*pvy[ 10 ]; amdy[ 12 ] = 3600.0*pvy[ 17 ]; /* The plate scale is the mean of the first X and Y co-efficients. */ pltscl = 0.5*( amdx[ 0 ] + amdy[ 0 ] ); /* There is redundancy in the DSS encoding. We can choose an arbitrary pixel corner (CNPIX1, CNPIX2) so long as we use the corresponding origin for the cartesian co-ordinate system in which the plate centre is specified (PPO3, PPO6). Arbitrarily set CNPIX1 and CNPIX2 to one. */ cnpix1 = 1.0; cnpix2 = 1.0; /* Find the corresponding plate centre PPO3 and PPO6 (other co-efficients are set to zero). */ ppo1 = 0.0; ppo2 = 0.0; val = GetItem( &(store->crpix), 0, 0, ' ', NULL, method, class, status ); if( val == AST__BAD ) return ret; ppo3 = xpixelsz*( val + cnpix1 - 0.5 ); ppo4 = 0.0; ppo5 = 0.0; val = GetItem( &(store->crpix), 0, 1, ' ', NULL, method, class, status ); if( val == AST__BAD ) return ret; ppo6 = ypixelsz*( val + cnpix2 - 0.5 ); /* The reference RA. Get it in degrees. */ val = GetItem( &(store->crval), 0, 0, ' ', NULL, method, class, status ); if( val == AST__BAD ) return ret; /* Convert to hours and ensure it is in the range 0 to 24 */ val /= 15.0; while( val < 0 ) val += 24.0; while( val >= 24.0 ) val -= 24.0; /* Split into hours, mins and seconds. */ pltrah = (int) val; val = 60.0*( val - pltrah ); pltram = (int) val; pltras = 60.0*( val - pltram ); /* The reference DEC. Get it in degrees. */ val = GetItem( &(store->crval), 1, 0, ' ', NULL, method, class, status ); if( val == AST__BAD ) return ret; /* Ensure it is in the range -180 to +180 */ while( val < -180.0 ) val += 360.0; while( val >= 180.0 ) val -= 360.0; /* Save the sign. */ if( val > 0.0 ){ pltdecsn = "+"; } else { pltdecsn = "-"; val = -val; } /* Split into degrees, mins and seconds. */ pltdecd = (int) val; val = 60.0*( val - pltdecd ); pltdecm = (int) val; pltdecs = 60.0*( val - pltdecm ); /* Store the DSS keywords in the FitsChan. */ SetValue( this, "CNPIX1", &cnpix1, AST__FLOAT, "X corner (pixels)", status ); SetValue( this, "CNPIX2", &cnpix2, AST__FLOAT, "Y corner (pixels)", status ); SetValue( this, "PPO1", &ppo1, AST__FLOAT, "Orientation co-efficients", status ); SetValue( this, "PPO2", &ppo2, AST__FLOAT, "", status ); SetValue( this, "PPO3", &ppo3, AST__FLOAT, "", status ); SetValue( this, "PPO4", &ppo4, AST__FLOAT, "", status ); SetValue( this, "PPO5", &ppo5, AST__FLOAT, "", status ); SetValue( this, "PPO6", &ppo6, AST__FLOAT, "", status ); SetValue( this, "XPIXELSZ", &xpixelsz, AST__FLOAT, "X pixel size (microns)", status ); SetValue( this, "YPIXELSZ", &ypixelsz, AST__FLOAT, "Y pixel size (microns)", status ); SetValue( this, "PLTRAH", &pltrah, AST__FLOAT, "RA at plate centre", status ); SetValue( this, "PLTRAM", &pltram, AST__FLOAT, "", status ); SetValue( this, "PLTRAS", &pltras, AST__FLOAT, "", status ); SetValue( this, "PLTDECD", &pltdecd, AST__FLOAT, "DEC at plate centre", status ); SetValue( this, "PLTDECM", &pltdecm, AST__FLOAT, "", status ); SetValue( this, "PLTDECS", &pltdecs, AST__FLOAT, "", status ); SetValue( this, "PLTDECSN", &pltdecsn, AST__STRING, "", status ); SetValue( this, "PLTSCALE", &pltscl, AST__FLOAT, "Plate scale (arcsec/mm)", status ); comm = "Plate solution x co-efficients"; for( i = 0; i < 20; i++ ){ SetValue( this, FormatKey( "AMDX", i + 1, -1, ' ', status ), amdx + i, AST__FLOAT, comm, status ); comm = NULL; } comm = "Plate solution y co-efficients"; for( i = 0; i < 20; i++ ){ SetValue( this, FormatKey( "AMDY", i + 1, -1, ' ', status ), amdy + i, AST__FLOAT, comm, status ); comm = NULL; } /* If no error has occurred, return one. */ if( astOK ) ret = 1; /* Return the answer. */ return ret; } static void DSSToStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * DSSToStore * Purpose: * Extract WCS information from the supplied FitsChan using a DSS * encoding, and store it in the supplied FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void DSSToStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function extracts DSS keywords from the supplied FitsChan, and * stores the corresponding WCS information in the supplied FitsStore. * The conversion from DSS encoding to standard WCS encoding is * described in an ear;y draft of the Calabretta & Greisen paper * "Representations of celestial coordinates in FITS" (A&A, in prep.), * and uses the now deprecated "TAN with polynomial corrections", * which is still supported by the WcsMap class as type AST__TPN. * Here we use "lambda=1" (i.e. plate co-ordinate are measured in mm, * not degrees). * * It is assumed that DSS images are 2 dimensional. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore structure. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char *text; /* Pointer to textual keyword value */ char pltdecsn[11]; /* First 10 non-blank characters from PLTDECSN keyword */ char keyname[10]; /* Buffer for keyword name */ double amdx[20]; /* AMDXi keyword value */ double amdy[20]; /* AMDYi keyword value */ double cnpix1; /* CNPIX1 keyword value */ double cnpix2; /* CNPIX2 keyword value */ double crval2; /* Equivalent CRVAL2 keyword value */ double dummy; /* Unused keyword value */ double pltdecd; /* PLTDECD keyword value */ double pltdecm; /* PLTDECM keyword value */ double pltdecs; /* PLTDECS keyword value */ double pltrah; /* PLTRAH keyword value */ double pltram; /* PLTRAM keyword value */ double pltras; /* PLTRAS keyword value */ double ppo3; /* PPO3 keyword value */ double ppo6; /* PPO6 keyword value */ double pv; /* Projection parameter value */ double xpixelsz; /* XPIXELSZ keyword value */ double ypixelsz; /* YPIXELSZ keyword value */ int i; /* Loop count */ /* Check the inherited status. */ if( !astOK ) return; /* Get the optional DSS keywords, supplying defaults for any missing keywords. */ cnpix1 = 0.0; cnpix2 = 0.0; GetValue( this, "CNPIX1", AST__FLOAT, &cnpix1, 0, 1, method, class, status ); GetValue( this, "CNPIX2", AST__FLOAT, &cnpix2, 0, 1, method, class, status ); /* Get the required DSS keywords. Report an error if any are missing. */ GetValue( this, "PPO3", AST__FLOAT, &ppo3, 1, 1, method, class, status ); GetValue( this, "PPO6", AST__FLOAT, &ppo6, 1, 1, method, class, status ); GetValue( this, "XPIXELSZ", AST__FLOAT, &xpixelsz, 1, 1, method, class, status ); GetValue( this, "YPIXELSZ", AST__FLOAT, &ypixelsz, 1, 1, method, class, status ); GetValue( this, "PLTRAH", AST__FLOAT, &pltrah, 1, 1, method, class, status ); GetValue( this, "PLTRAM", AST__FLOAT, &pltram, 1, 1, method, class, status ); GetValue( this, "PLTRAS", AST__FLOAT, &pltras, 1, 1, method, class, status ); GetValue( this, "PLTDECD", AST__FLOAT, &pltdecd, 1, 1, method, class, status ); GetValue( this, "PLTDECM", AST__FLOAT, &pltdecm, 1, 1, method, class, status ); GetValue( this, "PLTDECS", AST__FLOAT, &pltdecs, 1, 1, method, class, status ); /* Copy the first 10 non-blank characters from the PLTDECSN keyword. */ GetValue( this, "PLTDECSN", AST__STRING, &text, 1, 1, method, class, status ); if( astOK ) { text += strspn( text, " " ); text[ strcspn( text, " " ) ] = 0; strncpy( pltdecsn, text, 10 ); } /* Read other related keywords. We do not need these, but we read them so that they are not propagated to any output FITS file. */ GetValue( this, "PLTSCALE", AST__FLOAT, &dummy, 0, 1, method, class, status ); GetValue( this, "PPO1", AST__FLOAT, &dummy, 0, 1, method, class, status ); GetValue( this, "PPO2", AST__FLOAT, &dummy, 0, 1, method, class, status ); GetValue( this, "PPO4", AST__FLOAT, &dummy, 0, 1, method, class, status ); GetValue( this, "PPO5", AST__FLOAT, &dummy, 0, 1, method, class, status ); /* Get the polynomial co-efficients. These can be defaulted if they are missing, so do not report an error. */ for( i = 0; i < 20; i++ ){ (void) sprintf( keyname, "AMDX%d", i + 1 ); amdx[i] = AST__BAD; GetValue( this, keyname, AST__FLOAT, amdx + i, 0, 1, method, class, status ); (void) sprintf( keyname, "AMDY%d", i + 1 ); amdy[i] = AST__BAD; GetValue( this, keyname, AST__FLOAT, amdy + i, 0, 1, method, class, status ); } /* Check the above went OK. */ if( astOK ) { /* Calculate and store the equivalent PV projection parameters. */ if( amdx[2] != AST__BAD ) { pv = amdx[2]/3600.0; SetItem( &(store->pv), 0, 0, ' ', pv, status ); } if( amdx[0] != AST__BAD ) { pv = amdx[0]/3600.0; SetItem( &(store->pv), 0, 1, ' ', pv, status ); } if( amdx[1] != AST__BAD ) { pv = amdx[1]/3600.0; SetItem( &(store->pv), 0, 2, ' ', pv, status ); } if( amdx[3] != AST__BAD && amdx[6] != AST__BAD ) { pv = ( amdx[3] + amdx[6] )/3600.0; SetItem( &(store->pv), 0, 4, ' ', pv, status ); } if( amdx[4] != AST__BAD ) { pv = amdx[4]/3600.0; SetItem( &(store->pv), 0, 5, ' ', pv, status ); } if( amdx[5] != AST__BAD && amdx[6] != AST__BAD ) { pv = ( amdx[5] + amdx[6] )/3600.0; SetItem( &(store->pv), 0, 6, ' ', pv, status ); } if( amdx[7] != AST__BAD && amdx[11] != AST__BAD ) { pv = ( amdx[7] + amdx[11] )/3600.0; SetItem( &(store->pv), 0, 7, ' ', pv, status ); } if( amdx[8] != AST__BAD ) { pv = amdx[8]/3600.0; SetItem( &(store->pv), 0, 8, ' ', pv, status ); } if( amdx[9] != AST__BAD && amdx[11] != AST__BAD ) { pv = ( amdx[9] + amdx[11] )/3600.0; SetItem( &(store->pv), 0, 9, ' ', pv, status ); } if( amdx[10] != AST__BAD ) { pv = amdx[10]/3600.0; SetItem( &(store->pv), 0, 10, ' ', pv, status ); } if( amdx[12] != AST__BAD ) { pv = amdx[12]/3600.0; SetItem( &(store->pv), 0, 17, ' ', pv, status ); SetItem( &(store->pv), 0, 19, ' ', 2*pv, status ); SetItem( &(store->pv), 0, 21, ' ', pv, status ); } if( amdy[2] != AST__BAD ) { pv = amdy[2]/3600.0; SetItem( &(store->pv), 1, 0, ' ', pv, status ); } if( amdy[0] != AST__BAD ) { pv = amdy[0]/3600.0; SetItem( &(store->pv), 1, 1, ' ', pv, status ); } if( amdy[1] != AST__BAD ) { pv = amdy[1]/3600.0; SetItem( &(store->pv), 1, 2, ' ', pv, status ); } if( amdy[3] != AST__BAD && amdy[6] != AST__BAD ) { pv = ( amdy[3] + amdy[6] )/3600.0; SetItem( &(store->pv), 1, 4, ' ', pv, status ); } if( amdy[4] != AST__BAD ) { pv = amdy[4]/3600.0; SetItem( &(store->pv), 1, 5, ' ', pv, status ); } if( amdy[5] != AST__BAD && amdy[6] != AST__BAD ) { pv = ( amdy[5] + amdy[6] )/3600.0; SetItem( &(store->pv), 1, 6, ' ', pv, status ); } if( amdy[7] != AST__BAD && amdy[11] != AST__BAD ) { pv = ( amdy[7] + amdy[11] )/3600.0; SetItem( &(store->pv), 1, 7, ' ', pv, status ); } if( amdy[8] != AST__BAD ) { pv = amdy[8]/3600.0; SetItem( &(store->pv), 1, 8, ' ', pv, status ); } if( amdy[9] != AST__BAD && amdy[11] != AST__BAD ) { pv = ( amdy[9] + amdy[11] )/3600.0; SetItem( &(store->pv), 1, 9, ' ', pv, status ); } if( amdy[10] != AST__BAD ) { pv = amdy[10]/3600.0; SetItem( &(store->pv), 1, 10, ' ', pv, status ); } if( amdy[12] != AST__BAD ) { pv = amdy[12]/3600.0; SetItem( &(store->pv), 1, 17, ' ', pv, status ); SetItem( &(store->pv), 1, 19, ' ', 2*pv, status ); SetItem( &(store->pv), 1, 21, ' ', pv, status ); } /* Calculate and store the equivalent CRPIX values. */ if( xpixelsz != 0.0 ) { SetItem( &(store->crpix), 0, 0, ' ', ( ppo3/xpixelsz ) - cnpix1 + 0.5, status ); } else if( astOK ){ astError( AST__BDFTS, "%s(%s): FITS keyword XPIXELSZ has illegal " "value 0.0", status, method, class ); } if( ypixelsz != 0.0 ) { SetItem( &(store->crpix), 0, 1, ' ', ( ppo6/ypixelsz ) - cnpix2 + 0.5, status ); } else if( astOK ){ astError( AST__BDFTS, "%s(%s): FITS keyword YPIXELSZ has illegal " "value 0.0", status, method, class ); } /* Calculate and store the equivalent CRVAL values. */ SetItem( &(store->crval), 0, 0, ' ', 15.0*( pltrah + pltram/60.0 + pltras/3600.0 ), status ); crval2 = pltdecd + pltdecm/60.0 + pltdecs/3600.0; if( !strcmp( pltdecsn, "-") ) crval2 = -crval2; SetItem( &(store->crval), 1, 0, ' ', crval2, status ); /* Calculate and store the equivalent PC matrix. */ SetItem( &(store->pc), 0, 0, ' ', -0.001*xpixelsz, status ); SetItem( &(store->pc), 1, 1, ' ', 0.001*ypixelsz, status ); /* Set values of 1.0 for the CDELT values. */ SetItem( &(store->cdelt), 0, 0, ' ', 1.0, status ); SetItem( &(store->cdelt), 1, 0, ' ', 1.0, status ); /* Store remaining constant items */ SetItem( &(store->lonpole), 0, 0, ' ', 180.0, status ); SetItem( &(store->equinox), 0, 0, ' ', 2000.0, status ); SetItemC( &(store->radesys), 0, 0, ' ', "FK5", status ); SetItem( &(store->wcsaxes), 0, 0, ' ', 2.0, status ); store->naxis = 2; SetItemC( &(store->ctype), 0, 0, ' ', "RA---TPN", status ); SetItemC( &(store->ctype), 1, 0, ' ', "DEC--TPN", status ); } } static void EmptyFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astEmptyFits f AST_EMPTYFITS * Purpose: * Delete all cards in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astEmptyFits( AstFitsChan *this ) f CALL AST_EMPTYFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * deletes all cards and associated information from a FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - This method simply deletes the cards currently in the FitsChan. c Unlike astWriteFits, f Unlike AST_WRITEFITS, * they are not first written out to the sink function or sink file. * - Any Tables or warnings stored in the FitsChan are also deleted. * - This method attempt to execute even if an error has occurred * previously. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *class; /* Pointer to string holding object class */ const char *method; /* Pointer to string holding calling method */ int old_ignore_used; /* Original setting of ignore_used variable */ /* Check a FitsChan was supplied. */ if( !this ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Store the method and class strings. */ method = "astEmpty"; class = astGetClass( this ); /* Delete all cards from the circular linked list stored in the FitsChan, starting with the card at the head of the list. */ old_ignore_used = ignore_used; ignore_used = 0; astClearCard( this ); while( !astFitsEof( this ) ) DeleteCard( this, method, class, status ); ignore_used = old_ignore_used; /* Delete the KeyMap which holds keywords and the latest sequence number used by each of them. */ if( this->keyseq ) this->keyseq = astAnnul( this->keyseq ); /* Delete the KeyMap holding the keyword names. */ if( this->keywords ) this->keywords = astAnnul( this->keywords ); /* Free any memory used to hold the Warnings attribute value. */ this->warnings = astFree( this->warnings ); /* Other objects in the FitsChan structure. */ if( this->tables ) this->tables = astAnnul( this->tables ); } static int EncodeFloat( char *buf, int digits, int width, int maxwidth, double value, int *status ){ /* * * Name: * EncodeFloat * Purpose: * Formats a floating point value. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int EncodeFloat( char *buf, int digits, int width, int maxwidth, * double value, int *status ) * Class Membership: * FitsChan method. * Description: * This function formats the value using a G format specified in order * to use the minimum field width (trailing zeros are not printed). * However, the G specifier does not include a decimal point unless it * is necessary. FITS requires that floating point values always include * a decimal point, so this function inserts one, if necessary. * Parameters: * buf * A character string into which the value is written. * digits * The number of digits after the decimal point. If the supplied value * is negative, the number of digits actually used may be reduced if * the string would otherwise extend beyond the number of columns * allowed by the FITS standard. If the value is positive, the * specified number of digits are always produced, even if it means * breaking the FITS standard. * width * The minimum field width to use. The value is right justified in * this field width. * maxwidth * The maximum field width to use. A value of zero is returned if * the maximum field width is exceeded. * value * The value to format. * status * Pointer to the inherited status variable. * Returned Value: * The field width actually used, or zero if the value could not be * formatted. This does not include the trailing null character. * Notes: * - If there is room, a trailing zero is also added following the * inserted decimal point. */ /* Local Variables: */ char *c; char *w, *r; int i; int ldigits; int n; int ret; /* Check the global error status. */ if ( !astOK ) return 0; /* The supplied value of "digits" may be negative. Obtain the positive value giving the initial number of decimal digits to use. */ ldigits = ( digits > 0 ) ? digits : -digits; /* Loop until a suitably encoded value has been obtained. */ while( 1 ){ /* Write the value into the buffer. Most are formatted with a G specifier. This will result in values between -0.001 and -0.0001 being formatted without an exponent, and thus occupying (ldigits+6) characters. With an exponent, these values would be formatted in (ldigits+5) characters thus saving one character. This is important because the default value of ldigits is 15, resulting in 21 characters being used by the G specifier. This is one more than the maximum allowed by the FITS standard. Using an exponent instead would result in 20 characters being used without any loss of precision, thus staying within the FITS limit. Note, the precision used with the E specifier is one less than with the G specifier because the digit to the left of the decimal place is significant with the E specifier, and so we only need (ldigits-1) significant digits to the right of the decimal point. */ if( value > -0.001 && value < -0.0001 ) { (void) sprintf( buf, "%*.*E", width, ldigits - 1, value ); } else { (void) sprintf( buf, "%*.*G", width, ldigits, value ); } /* Check that the value zero is not encoded with a minus sign (e.g. "-0."). This also rounds out long sequences of zeros or nines. */ CheckZero( buf, value, width, status ); /* If the formatted value includes an exponent, it will have 2 digits. If the exponent includes a leading zero, remove it. */ if( ( w = strstr( buf, "E-0" ) ) ) { w += 2; } else if( ( w = strstr( buf, "E+0" ) ) ){ w += 2; } else if( ( w = strstr( buf, "E0" ) ) ){ w += 1; } /* If a leading zero was found, shuffle everything down from the start of the string by one character, over-writing the redundant zero, and insert a space at the start of the string. */ if( w ) { r = w - 1 ; while( w != buf ) *(w--) = *(r--); *w = ' '; } /* If the used field width was too large, reduce it and try again, so long as we are allowed to change the number of digits being used. */ ret = strlen( buf ); if( ret > width && digits < 0 ){ ldigits -= ( ret - width ); /* Otherwise leave the loop. Return zero field width if the maximum field width was exceeded. */ } else { if( ret > maxwidth ) ret = 0; break; } } /* If a formatted value was obtained, we need to ensure that the it includes a decimal point. */ if( ret ){ /* Get a pointer to the first digit in the buffer. */ c = strpbrk( buf, "0123456789" ); /* Something funny is going on if there are no digits in the buffer, so return a zero field width. */ if( !c ){ ret = 0; /* Otherwise... */ } else { /* Find the number of digits following and including the first digit. */ n = strspn( c, "0123456789" ); /* If the first non-digit character is a decimal point, do nothing. */ if( c[ n ] != '.' ){ /* If there are two or more leading spaces, move the start of the string two character to the left, and insert ".0" in the gap created. This keeps the field right justified within the desired field width. */ if( buf[ 0 ] == ' ' && buf[ 1 ] == ' ' ){ for( i = 2; i < c - buf + n; i++ ) buf[ i - 2 ] = buf[ i ]; c[ n - 2 ] = '.'; c[ n - 1 ] = '0'; /* If there is just one leading space, move the start of the string one character to the left, and insert "." in the gap created. This keeps the field right justified within the desired field width. */ } else if( buf[ 0 ] == ' ' ){ for( i = 0; i < n; i++ ) c[ i - 1 ] = c[ i ]; c[ n - 1 ] = '.'; /* If there are no leading spaces we need to move the end of the string to the right. This will result in the string no longer being right justified in the required field width. Return zero if there is insufficient room for an extra character. */ } else { ret++; if( ret > maxwidth ){ ret = 0; /* Otherwise, more the end of the string one place to the right and insert the decimal point. */ } else { for( i = strlen( c ); i >= n; i-- ) c[ i + 1 ] = c[ i ]; c[ n ] = '.'; } } } } } /* Return the field width. */ return ret; } static int EncodeValue( AstFitsChan *this, char *buf, int col, int digits, const char *method, int *status ){ /* * Name: * EncodeValue * Purpose: * Encode the current card's keyword value into a string. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int EncodeValue( AstFitsChan *this, char *buf, int col, int digits, * const char *method, int *status ) * Class Membership: * FitsChan member function. * Description: * This function encodes the keyword value defined in the current card * of the supplied FitsChan and stores it at the start of the supplied * buffer. The number of characters placed in the buffer is returned * (not including a terminating null). * Parameters: * this * Pointer to the FitsChan. * buf * The buffer to receive the formatted value. This should be at least * 70 characters long. * col * The column number within the FITS header card corresponding to the * start of "buf". * digits * The number of digits to use when formatting floating point * values. If the supplied value is negative, the number of digits * actually used may be reduced if the string would otherwise extend * beyond the number of columns allowed by the FITS standard. If the * value is positive, the specified number of digits are always * produced, even if it means breaking the FITS standard. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The number of columns used by the encoded value. * Notes: * - The function returns 0 if an error has already occurred * or if an error occurs for any reason within this function. */ /* Local Variables: */ char *c; /* Pointer to next character */ char *name; /* Pointer to the keyword name */ double dval; /* Keyword value */ void *data; /* Pointer to keyword value */ int i; /* Loop count */ int ilen; /* Length of imaginary part */ int len; /* Returned length */ int quote; /* Quote character found? */ int rlen; /* Length of real part */ int type; /* Data type for keyword in current card */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise returned length. */ len = 0; /* Get the data type of the keyword. */ type = CardType( this, status ); /* Get a pointer to the data value in the current card. */ data = CardData( this, NULL, status ); /* Return if there is no defined value associated with the keyword in the current card. */ if( type != AST__UNDEF ) { /* Get the name of the keyword. */ name = CardName( this, status ); /* Go through each supported data type (roughly in the order of decreasing usage)... */ /* AST__FLOAT - stored internally in a variable of type "double". Right justified to column 30 in the header card. */ if( type == AST__FLOAT ){ dval = *( (double *) data ); len = EncodeFloat( buf, digits, FITSRLCOL - FITSNAMLEN - 2, AST__FITSCHAN_FITSCARDLEN - col + 1, dval, status ); if( len <= 0 && astOK ) { astError( AST__BDFTS, "%s(%s): Cannot encode floating point value " "%g into a FITS header card for keyword '%s'.", status, method, astGetClass( this ), dval, name ); } /* AST__STRING & AST__CONTINUE - stored internally in a null terminated array of type "char". The encoded string is enclosed in single quotes, starting at FITS column 11 and ending in at least column 20. Single quotes in the string are replaced by two adjacent single quotes. */ } else if( type == AST__STRING || type == AST__CONTINUE ){ c = (char *) data; /* Enter the opening quote. */ len = 0; buf[ len++ ] = '\''; /* Inspect each character, looking for quotes. */ for ( i = 0; c[ i ]; ) { quote = ( c[ i ] == '\'' ); /* If it will not fit into the header card (allowing for doubled quotes), give up here. */ if ( len + ( quote ? 2 : 1 ) > AST__FITSCHAN_FITSCARDLEN - col ) break; /* Otherwise, copy it into the output buffer and double any quotes. */ buf[ len++ ] = c[ i ]; if ( quote ) buf[ len++ ] = '\''; /* Look at the next character. */ i++; } /* Pad the string out to the required minimum length with blanks and add the final quote. */ while( len < FITSSTCOL - col ) buf[ len++ ] = ' '; buf[ len++ ] = '\''; /* Inspect any characters that weren't used. If any are non-blank, report an error. */ for ( ; c[ i ]; i++ ) { if ( !isspace( c[ i ] ) ) { astError( AST__BDFTS, "%s(%s): Cannot encode string '%s' into a FITS " "header card for keyword '%s'.", status, method, astGetClass( this ), (char *) data, name ); break; } } /* INTEGER - stored internally in a variable of type "int". Right justified to column 30 in the header card. */ } else if( type == AST__INT ){ len = sprintf( buf, "%*d", FITSRLCOL - col + 1, *( (int *) data ) ); if( len < 0 || len > AST__FITSCHAN_FITSCARDLEN - col ) { astError( AST__BDFTS, "%s(%s): Cannot encode integer value %d into a " "FITS header card for keyword '%s'.", status, method, astGetClass( this ), *( (int *) data ), name ); } /* LOGICAL - stored internally in a variable of type "int". Represented by a "T" or "F" in column 30 of the FITS header card. */ } else if( type == AST__LOGICAL ){ for( i = 0; i < FITSRLCOL - col; i++ ) buf[ i ] = ' '; if( *( (int *) data ) ){ buf[ FITSRLCOL - col ] = 'T'; } else { buf[ FITSRLCOL - col ] = 'F'; } len = FITSRLCOL - col + 1; /* AST__COMPLEXF - stored internally in an array of two "doubles". The real part is right justified to FITS column 30. The imaginary part is right justified to FITS column 50. */ } else if( type == AST__COMPLEXF ){ dval = ( (double *) data )[ 0 ]; rlen = EncodeFloat( buf, digits, FITSRLCOL - FITSNAMLEN - 2, AST__FITSCHAN_FITSCARDLEN - col + 1, dval, status ); if( rlen <= 0 || rlen > AST__FITSCHAN_FITSCARDLEN - col ) { astError( AST__BDFTS, "%s(%s): Cannot encode real part of a complex " "floating point value [%g,%g] into a FITS header card " "for keyword '%s'.", status, method, astGetClass( this ), dval, ( (double *) data )[ 1 ], name ); } else { dval = ( (double *) data )[ 1 ]; ilen = EncodeFloat( buf + rlen, digits, FITSIMCOL - FITSRLCOL, AST__FITSCHAN_FITSCARDLEN - col - rlen, dval, status ); if( ilen <= 0 ) { astError( AST__BDFTS, "%s(%s): Cannot encode imaginary part of a " "complex floating point value [%g,%g] into a FITS header " "card for keyword '%s'.", status, method, astGetClass( this ), ( (double *) data )[ 0 ], dval, name ); } else { len = ilen + rlen; } } /* AST__COMPLEXI - stored internally in a an array of two "ints". */ } else if( type == AST__COMPLEXI ){ rlen = sprintf( buf, "%*d", FITSRLCOL - col + 1, ( (int *) data )[ 0 ] ); if( rlen < 0 || rlen > AST__FITSCHAN_FITSCARDLEN - col ) { astError( AST__BDFTS, "%s(%s): Cannot encode real part of a complex " "integer value [%d,%d] into a FITS header card " "for keyword '%s'.", status, method, astGetClass( this ), ( (int *) data )[ 0 ], ( (int *) data )[ 1 ], name ); } else { ilen = sprintf( buf + rlen, "%*d", FITSIMCOL - FITSRLCOL + 1, ( (int *) data )[ 1 ] ); if( ilen < 0 || ilen > AST__FITSCHAN_FITSCARDLEN - col - rlen ) { astError( AST__BDFTS, "%s(%s): Cannot encode imaginary part of a " "complex integer value [%d,%d] into a FITS header card " "for keyword '%s'.", status, method, astGetClass( this ), ( (int *) data )[ 0 ], ( (int *) data )[ 1 ], name ); } else { len = ilen + rlen; } } /* Report an internal (ast) programming error if the keyword is of none of the above types. */ } else if( astOK ){ astError( AST__INTER, "EncodeValue: AST internal programming error - " "FITS %s data-type not yet supported.", status, type_names[ type ] ); } } /* If an error has occurred, return zero length. */ if( !astOK ) len = 0; /* Return the answer. */ return len; } static AstGrismMap *ExtractGrismMap( AstMapping *map, int iax, AstMapping **new_map, int *status ){ /* * Name: * ExtractGrismMap * Purpose: * Extract a GrismMap from the end of the supplied Mapping. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstGrismMap *ExtractGrismMap( AstMapping *map, int iax, * AstMapping **new_map, int *status ) * Class Membership: * FitsChan member function. * Description: * This function examines the supplied Mapping; if the specified output * coordinate of the Mapping is created directly by an un-inverted GrismMap, * then a pointer to the GrismMap is returned as the function value. A new * Mapping is also returned via parameter "new_map" which is a copy of * the supplied Mapping, except that the GrismMap is replaced with a * UnitMap. If no GrismMap is found, NULL is returned for both Mappings. * The condition that "the specified output coordinate of the Mapping is * created directly by an un-inverted GrismMap" means that the output * of the GrismMap is no subsequently modified by any further Mappings * before being returned as the "iax"th output of the supplied Mapping. * This means the GrismMap must be "at the end of" a CmpMap, not in * the middle of the CmpMap. * Parameters: * map * Pointer to the Mapping to check. * iax * The index for the output coordinate to be checked. * new_map * Pointer to a location at which to return a pointer to a new * Mapping which is a copy of "map" except that the GrismMap is * replaced by a UnitMap. NULL is returned if the specified output * was not created by a GrismMap. * status * Pointer to the inherited status variable. * Returned Value: * The extracted GrismMap, or NULL if the specified output was not * created by a GrismMap. */ /* Local Variables: */ AstMapping *mapa; /* First component Mapping */ AstMapping *mapb; /* Second component Mapping */ AstMapping *new_mapa; /* Replacement for first component Mapping */ AstMapping *new_mapb; /* Replacement for second component Mapping */ AstGrismMap *ret; /* Returned GrismMap */ int inva; /* Invert attribute for mapa within the CmpMap */ int invb; /* Invert attribute for mapb within the CmpMap */ int na; /* Number of outputs for mapa */ int old_inva; /* Current Invert attribute for mapa */ int old_invb; /* Current Invert attribute for mapb */ int series; /* Are component Mappings applied in series? */ /* Initialise */ ret = NULL; *new_map = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* If the supplied Mapping is a GrismMap which has not been inverted, return it as the function value and return a UnitMap as the new Mapping. */ if( astIsAGrismMap( map ) ) { if( !astGetInvert( map ) ) { ret = astClone( map ); *new_map = (AstMapping *) astUnitMap( 1, "", status ); } /* If the supplied Mapping is a CmpMap, get its two component Mappings, see if they are applied in parallel or series, and get the Invert attribute values which the component Mappings had at the time the CmpMap was created. */ } else if( astIsACmpMap( map ) ) { astDecompose( map, &mapa, &mapb, &series, &inva, &invb ); /* Temporaily reset the Invert attributes of the component Mappings back to the values they had when the CmpMap was created. */ old_inva = astGetInvert( mapa ); old_invb = astGetInvert( mapb ); astSetInvert( mapa, inva ); astSetInvert( mapb, invb ); /* If the supplied Mapping is a series CmpMap, attempt to extract a GrismMap from the second component Mapping ("mapb"). The first component Mapping ("mapa") is unchanged. We do not need to consdier the first component since we are only interested in GrismMaps which are at the end of the CmpMap. */ if( series ) { ret = ExtractGrismMap( mapb, iax, &new_mapb, status ); if( ret ) new_mapa = astClone( mapa ); /* If the supplied Mapping is a parallel CmpMap, attempt to extract a GrismMap from the component Mapping which produces output "iax". The other component Mapping is unchanged. */ } else { na = astGetNout( mapa ); if( iax < na ) { ret = ExtractGrismMap( mapa, iax, &new_mapa, status ); if( ret ) new_mapb = astClone( mapb ); } else { ret = ExtractGrismMap( mapb, iax - na, &new_mapb, status ); if( ret ) new_mapa = astClone( mapa ); } } /* If succesful, create a new CmpMap to return. */ if( ret ) { *new_map = (AstMapping *) astCmpMap( new_mapa, new_mapb, series, "", status ); new_mapa = astAnnul( new_mapa ); new_mapb = astAnnul( new_mapb ); } /* Re-instate the original Invert attributes of the component Mappings. */ astSetInvert( mapa, old_inva ); astSetInvert( mapb, old_invb ); /* Annul the component Mapping pointers. */ mapa = astAnnul( mapa ); mapb = astAnnul( mapb ); } /* Return the result. */ return ret; } static int MakeBasisVectors( AstMapping *map, int nin, int nout, double *g0, AstPointSet *psetg, AstPointSet *psetw, int *status ){ /* * Name: * MakeBasisVectors * Purpose: * Create a set of basis vectors in grid coordinates * Type: * Private function. * Synopsis: * #include "fitschan.h" * int MakeBasisVectors( AstMapping *map, int nin, int nout, * double *g0, AstPointSet *psetg, * AstPointSet *psetw, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a set of unit vectors in grid coordinates, * one for each grid axis. Each unit vector is parallel to the * corresponding grid axis, and rooted at a specified grid position * ("g0"). The IWC coordinates corresponding to "g0" and to the end of * each of the unit vectors are also returned, together with a flag * indicating if all the IWC coordinate values are good. * Parameters: * map * A pointer to a Mapping which transforms grid coordinates into * intermediate world coordinates (IWC). The number of outputs must * be greater than or equal to the number of inputs. * nin * The number of inputs for "map" (i.e. the number of grid axes). * nout * The number of outputs for "map" (i.e. the number of IWC axes). * g0 * Pointer to an array of holding the grid coordinates at the * "root" position. * psetg * A pointer to a PointSet which can be used to hold the required * grid positions. This should have room for nin+1 positions. On * return, the first position holds "g0", and the subsequent "nin" * positions hold are offset from "g0" by unit vectors along the * corresponding grid axis. * psetw * A pointer to a PointSet which can be used to hold the required * IWC position. This should also have room for nin+1 positions. On * return, the values are the IWC coordinates corresponding to the * grid positions returned in "psetg". * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if all the axis values in "psetw" are good. * Zero is returned otherwise. * Notes: * - Zero is returned if an error occurs. */ /* Local Variables: */ double **ptrg; double **ptrw; double *c; int i; int ii; int j; int ret; /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Get pointers to the data in the two supplied PointSets. */ ptrg = astGetPoints( psetg ); ptrw = astGetPoints( psetw ); /* Check the pointers can be used safely. */ if( astOK ) { /* Assume success. */ ret = 1; /* Store the required grid positions in PointSet "pset1". The first position is the supplied root grid position, g0. The next "nin" positions are offset from the root position by a unit vector along each grid axis in turn. Store values for each grid axis in turn. */ for( i = 0; i < nin; i++ ) { /* Get a pointer to the first axis value for this grid axis. */ c = ptrg[ i ]; /* Initially set all values for this axis to the supplied root grid value. */ for( ii = 0; ii < nin + 1; ii++ ) c[ ii ] = g0[ i ]; /* Modify the value corresponding to the vector along this grid axis. */ c[ i + 1 ] += 1.0; } /* Transform these grid positions in IWC positions using the supplied Mapping. */ (void) astTransform( map, psetg, 1, psetw ); /* Check that all the transformed positions are good. */ for( j = 0; j < nout; j++ ) { c = ptrw[ j ]; for( ii = 0; ii < nin + 1; ii++, c++ ) { if( *c == AST__BAD ) { ret = 0; break; } } } } /* Return the result. */ return ret; } static int FindBasisVectors( AstMapping *map, int nin, int nout, double *dim, AstPointSet *psetg, AstPointSet *psetw, int *status ){ /* * Name: * FindBasisVectors * Purpose: * Find the a set of basis vectors in grid coordinates * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FindBasisVectors( AstMapping *map, int nin, int nout, * double *dim, AstPointSet *psetg, * AstPointSet *psetw, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a set of unit vectors in grid coordinates, * one for each grid axis. Each unit vector is parallel to the * corresponding grid axis, and rooted at a specified grid position * ("g0"). The IWC coordinates corresponding to "g0" and to the end of * each of the unit vectors are also returned, together with a flag * indicating if all the IWC coordinate values are good. * Parameters: * map * A pointer to a Mapping which transforms grid coordinates into * intermediate world coordinates (IWC). The number of outputs must * be greater than or equal to the number of inputs. * nin * The number of inputs for "map" (i.e. the number of grid axes). * nout * The number of outputs for "map" (i.e. the number of IWC axes). * dim * Array dimensions, in pixels, if known (otherwise supplied a NULL * pointer to values of AST__BAD). * psetg * A pointer to a PointSet which can be used to hold the required * grid position. This should have room for nin+1 positions. On * return, the first position holds the "root" position and the * subsequent "nin" positions hold are offset from root position * by unit vectors along the corresponding grid axis. * psetw * A pointer to a PointSet which can be used to hold the required * IWC position. This should also have room for nin+1 positions. On * return, the values are the IWC coordinates corresponding to the * grid positions returned in "psetg". * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if a set of basis vectors was found * succesfully. Zero is returned otherwise. * Notes: * - Zero is returned if an error occurs. */ /* Local Variables: */ double *g0; double dd; double ddlim; int i; int ii; int ret; /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Allocate an array to store the candidate root position. */ g0 = astMalloc( sizeof( double )*(size_t) nin ); if( astOK ) { /* First try the grid centre, if known. */ ddlim = 0; ret = 0; if( dim ) { ret = 1; for( i = 0; i < nin; i++ ) { if( dim[ i ] != AST__BAD ) { g0[ i ] = 0.5*( 1 + dim[ i ] ); if( dim[ i ] > ddlim ) ddlim = dim[ i ]; } else { ret = 0; break; } } } if( ret ) ret = MakeBasisVectors( map, nin, nout, g0, psetg, psetw, status ); /* If this did not produce a set of good IWC positions, try grid position (1,1,1...). */ if( !ret ) { for( i = 0; i < nin; i++ ) g0[ i ] = 1.0; ret = MakeBasisVectors( map, nin, nout, g0, psetg, psetw, status ); } /* If this did not produce a set of good IWC positions, try a sequence of grid positions which move an increasing distance along each grid axis from (1,1,1,...). Stop when we get further than "ddlim" from the origin. */ dd = 10.0; if( ddlim == 0.0 ) ddlim = 10240.0; while( !ret && dd <= ddlim ) { /* First try positions which extend across the middle of the data set. If the image dimensions are known, make the line go from the "bottom left corner" towards the "top right corner", taking the aspect ratio of the image into account. Otherise, just use a vector of (1,1,1,..) */ for( i = 0; i < nin; i++ ) { if( dim && dim[ i ] != AST__BAD ) { g0[ i ] = dd*dim[ i ]/ddlim; } else { g0[ i ] = dd; } } ret = MakeBasisVectors( map, nin, nout, g0, psetg, psetw, status ); /* If the above didn't produce good positions, try moving out along each grid axis in turn. */ for( ii = 0; !ret && ii < nin; ii++ ) { for( i = 0; i < nin; i++ ) g0[ i ] = 1.0; g0[ ii ] = dd; ret = MakeBasisVectors( map, nin, nout, g0, psetg, psetw, status ); } /* Go further out from the origin for the next set of tests (if any). */ dd *= 2.0; } } /* Free resources. */ g0 = astFree( g0 ); /* Return the result. */ return ret; } static int FindLonLatSpecAxes( FitsStore *store, char s, int *axlon, int *axlat, int *axspec, const char *method, const char *class, int *status ) { /* * Name: * FindLonLatSpecAxes * Purpose: * Search the CTYPE values in a FitsStore for celestial and spectral axes. * Type: * Private function. * Synopsis: * int FindLonLatSpecAxes( FitsStore *store, char s, int *axlon, int *axlat, * int *axspec, const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * The supplied FitsStore is searched for axes with a specified axis * description character which describe celestial longitude or latitude * or spectral position. * Parameters: * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * axlon * Address of a location at which to return the index of the * longitude axis (if found). This is the value of "i" within the * keyword name "CTYPEi". A value of -1 is returned if no longitude * axis is found. * axlat * Address of a location at which to return the index of the * latitude axis (if found). This is the value of "i" within the * keyword name "CTYPEi". A value of -1 is returned if no latitude * axis is found. * axspec * Address of a location at which to return the index of the * spectral axis (if found). This is the value of "i" within the * keyword name "CTYPEi". A value of -1 is returned if no spectral * axis is found. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * One is returned if both celestial axes were found. Zero is returned if * either axis was not found. The presence of a spectral axis does not * affect the returned value. * Notes: * - If an error occurs, zero is returned. */ /* Local Variables: */ char *assys; char *astype; char algcode[5]; char stype[5]; const char *ctype; double dval; int i; int wcsaxes; /* Initialise */ *axlon = -1; *axlat = -1; *axspec = -1; /* Check the global status. */ if ( !astOK ) return 0; /* Obtain the number of FITS WCS axes in the header. If the WCSAXES header was specified, use it. Otherwise assume it is the same as the number of pixel axes. */ dval = GetItem( &(store->wcsaxes), 0, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) { wcsaxes = (int) dval + 0.5; } else { wcsaxes = store->naxis; } /* Loop round the FITS WCS axes, getting each CTYPE value. */ for( i = 0; i < wcsaxes && astOK; i++ ){ ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); /* Check a value was found. */ if( ctype ) { /* First check for spectral axes, either FITS-WCS or AIPS-like. */ if( IsSpectral( ctype, stype, algcode, status ) || IsAIPSSpectral( ctype, &astype, &assys, status ) ) { *axspec = i; /* Otherwise look for celestial axes. Celestial axes must have a "-" as the fifth character in CTYPE. */ } else if( ctype[4] == '-' ) { /* See if this is a longitude axis (e.g. if the first 4 characters of CTYPE are "RA--" or "xLON" or "yzLN" ). */ if( !strncmp( ctype, "RA--", 4 ) || !strncmp( ctype, "AZ--", 4 ) || !strncmp( ctype + 1, "LON", 3 ) || !strncmp( ctype + 2, "LN", 2 ) ){ *axlon = i; /* Otherwise see if it is a latitude axis. */ } else if( !strncmp( ctype, "DEC-", 4 ) || !strncmp( ctype, "EL--", 4 ) || !strncmp( ctype + 1, "LAT", 3 ) || !strncmp( ctype + 2, "LT", 2 ) ){ *axlat = i; } } } } /* Indicate failure if an error occurred. */ if( !astOK ) { *axlon = -1; *axlat = -1; *axspec = -1; } /* Return the result. */ return ( *axlat != -1 && *axlon != -1 ); } static void FindWcs( AstFitsChan *this, int last, int all, int rewind, const char *method, const char *class, int *status ){ /* * Name: * FindWcs * Purpose: * Find the first or last FITS WCS related keyword in a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FindWcs( AstFitsChan *this, int last, int all, int rewind, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A search is made through the FitsChan for the first or last card * which relates to a FITS WCS keyword (any encoding). If "last" is * non-zero, the next card becomes the current card. If "last" is * zero, the WCS card is left as the current card. Cards marked as * having been read are included or not, as specified by "all". * Parameters: * this * Pointer to the FitsChan. * last * If non-zero, the last WCS card is searched for. Otherwise, the * first WCS card is searched for. * all * If non-zero, then cards marked as having been read are included * in the search. Otherwise such cards are ignored. * rewind * Only used if "last" is zero (i.e. the first card is being * searched for). If "rewind" is non-zero, then the search starts * from the first card in the FitsChan. If zero, the search starts * from the current card. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - The FitsChan is left at end-of-file if no FITS-WCS keyword cards * are found in the FitsChan. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *keyname; /* Keyword name from current card */ int nfld; /* Number of fields in keyword template */ int old_ignore_used; /* Original value of variable ignore_used */ /* Check the global status. Also check the FitsChan is not empty. */ if( !astOK || !this->head ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Indicate that we should, or should not, skip over cards marked as having been read. */ old_ignore_used = ignore_used; ignore_used = all ? 0 : 1; /* If required, set the FitsChan to start or end of file. */ if( last ) { astSetCard( this, INT_MAX ); } else if( rewind ) { astClearCard( this ); } /* If the current card is marked as used, and we are skipping used cards, move on to the next unused card */ if( CARDUSED( this->card ) ) MoveCard( this, last?-1:1, method, class, status ); /* Check each card moving backwards from the end to the start, or forwards from the start to the end, until a WCS keyword is found, or the other end of the FitsChan is reached. */ while( astOK ){ /* Get the keyword name from the current card. */ keyname = CardName( this, status ); /* Save a pointer to the keyword if it is the first non-null, non-comment card. */ if( keyname ) { /* If it matches any of the WCS keywords, move on one card and break out of the loop. */ if( Match( keyname, "CRVAL%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CRPIX%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CDELT%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CROTA%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CTYPE%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CUNIT%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PC%3d%3d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CD%3d%3d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CD%1d_%1d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PC%1d_%1d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "LONGPOLE", 0, NULL, &nfld, method, class, status ) || Match( keyname, "LONPOLE%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "LATPOLE%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PROJP%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PV%d_%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PS%d_%d%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "EPOCH", 0, NULL, &nfld, method, class, status ) || Match( keyname, "EQUINOX%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "MJD-OBS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "DATE-OBS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "TIMESYS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "RADECSYS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "RADESYS%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "C%1dVAL%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "C%1dPIX%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "C%1dELT%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "C%1dYPE%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "C%1dNIT%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CNPIX1", 0, NULL, &nfld, method, class, status ) || Match( keyname, "CNPIX2", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PPO%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "AMDX%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "AMDY%d", 0, NULL, &nfld, method, class, status ) || Match( keyname, "XPIXELSZ", 0, NULL, &nfld, method, class, status ) || Match( keyname, "YPIXELSZ", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTRAH", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTRAM", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTRAS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTDECD", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTDECM", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTDECS", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTDECSN", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PLTSCALE", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PPO1", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PPO2", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PPO4", 0, NULL, &nfld, method, class, status ) || Match( keyname, "PPO5", 0, NULL, &nfld, method, class, status ) || Match( keyname, "WCSNAME%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "SPECSYS%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "SSYSSRC%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "ZSOURCE%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "VELOSYS%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "RESTFRQ%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "MJD_AVG%0c", 0, NULL, &nfld, method, class, status ) || Match( keyname, "OBSGEO-X", 0, NULL, &nfld, method, class, status ) || Match( keyname, "OBSGEO-Y", 0, NULL, &nfld, method, class, status ) || Match( keyname, "OBSGEO-Z", 0, NULL, &nfld, method, class, status ) ) { if( last ) MoveCard( this, 1, method, class, status ); break; } } /* Leave the FitsChan at end-of-file if no WCS cards were found. */ if( (last && FitsSof( this, status ) ) || (!last && astFitsEof( this ) ) ) { astSetCard( this, INT_MAX ); break; } else { MoveCard( this, last?-1:1, method, class, status ); } } /* Re-instate the original flag indicating if cards marked as having been read should be skipped over. */ ignore_used = old_ignore_used; /* Return. */ return; } static int FindString( int n, const char *list[], const char *test, const char *text, const char *method, const char *class, int *status ){ /* * Name: * FindString * Purpose: * Find a given string within an array of character strings. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FindString( int n, const char *list[], const char *test, * const char *text, const char *method, const char *class, int *status ) * Class Membership: * FitsChan method. * Description: * This function identifies a supplied string within a supplied * array of valid strings, and returns the index of the string within * the array. The test option may not be abbreviated, but case is * insignificant. * Parameters: * n * The number of strings in the array pointed to be "list". * list * A pointer to an array of legal character strings. * test * A candidate string. * text * A string giving a description of the object, parameter, * attribute, etc, to which the test value refers. * This is only for use in constructing error messages. It should * start with a lower case letter. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The index of the identified string within the supplied array, starting * at zero. * Notes: * - A value of -1 is returned if an error has already occurred, or * if this function should fail for any reason (for instance if the * supplied option is not specified in the supplied list). */ /* Local Variables: */ int ret; /* The returned index */ /* Check global status. */ if( !astOK ) return -1; /* Compare the test string with each element of the supplied list. Leave the loop when a match is found. */ for( ret = 0; ret < n; ret++ ) { if( !Ustrcmp( test, list[ ret ], status ) ) break; } /* Report an error if the supplied test string does not match any element in the supplied list. */ if( ret >= n && astOK ) { astError( AST__RDERR, "%s(%s): Illegal value '%s' supplied for %s.", status, method, class, test, text ); ret = -1; } /* Return the answer. */ return ret; } static int FitOK( int n, double *act, double *est, double tol, int *status ) { /* * Name: * FitOK * Purpose: * See if a fit is usable. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FitOK( int n, double *act, double *est, double tol, int *status ) * Class Membership: * FitsChan member function. * Description: * This function is supplied with a set of actual data values, and the * corresponding values estimated by some fitting process. It tests * that the RMS residual between them is no more than "tol". * Parameters: * n * Number of data points. * act * Pointer to the start of the actual data values. * est * Pointer to the start of the estimated data values. * tol * The largest acceptable RMS error between "act" and "est". * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if the two sets of values agree. Zero is * returned otherwise. * Notes: * - Zero is returned if an error occurs. */ /* Local Variables: */ int ret, i; double s1, s2; double *px, *py, diff, mserr; /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Initialise the sum of the squared residuals, and the number summed. */ s1 = 0.0; s2 = 0.0; /* Initialise pointers to the next actual and estimated values to use. */ px = act; py = est; /* Loop round all pairs of good actual and estimate value. */ for( i = 0; i < n; i++, px++, py++ ){ if( *px != AST__BAD && *py != AST__BAD ) { /* Increment the sums need to find the RMS residual between the actual and estimated values. */ diff = *px - *py; s1 += diff*diff; s2 += 1.0; } } /* If the sums are usable... */ if( s2 > 0.0 ) { /* Form the mean squared residual, and check if it is less than the squared error limit. */ mserr = s1/s2; if( mserr < tol*tol ) ret = 1; } /* Return the result. */ return ret; } static int FitsAxisOrder( AstFitsChan *this, int nwcs, AstFrame *wcsfrm, int *perm, int *status ){ /* * Name: * FitsAxisOrder * Purpose: * Return the order of WCS axes specified by attribute FitsAxisOrder. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FitsAxisOrder( AstFitsChan *this, int nwcs, AstFrame *wcsfrm, * int *perm, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns an array indicating the order of the WCS axes * within the output FITS header, as specified by the FitsAxisOrder * attribute. * Parameters: * this * Pointer to the FitsChan. * nwcs * The number of axes in "wcsfrm". * wcsfrm * The Frame containing the output WCS axes. * perm * Pointer to an array of "nwcs" integers. On exit, element "k" * of this array holds the zero-based index of the FITS-WCS axis * (i.e. one less than the value of "i" in the keyword names * "CTYPEi", "CRVALi", etc) that describes the k'th axis in "wcsfrm". * In other words, "perm[ast_index] = fits_index". The order is * determined by the FitsAxisOrder attribute. If this attribute is * "" or "", then "perm[k]=k" for all k on exit (i.e. * a unit mapping between axes in "wcsfrm" and the FITS header). * status * Pointer to the inherited status variable. * Returned Value: * Returns zero if the FitsAxisOrder attribute is ", and * non-zero otherwise. This is a flag indicating if the returned * values in "perm" can be used s they are. */ /* Local Variables: */ AstKeyMap *km; /* KeyMap holding axis indices keyed by axis symbols */ char **words; /* Pointer to array of words from FitsAxisOrder */ char attr_name[15];/* Attribute name */ const char *attr; /* Pointer to a string holding the FitsAxisOrder value */ int i; /* Loop count */ int j; /* Zero-based axis index */ int k; /* Zero-based axis index */ int nword; /* Number of words in FitsAxisOrder */ int result; /* Retrned value */ /* Check the inherited status. */ if( !astOK ) return 0; /* Initialise the returned array to a unit mapping from Frame axis to FITS axis. */ for( i = 0; i < nwcs; i++ ) perm[ i ] = i; /* Get the FitsAxisOrder attribute value, and set the returned value to indicate if it is "". */ attr = astGetFitsAxisOrder( this ); result = !astChrMatch( attr, "" ); /* Return immediately if it is "" or "". */ if( result && !astChrMatch( attr, "" ) ) { /* Create a KeyMap in which each key is the Symbol for an axis and the associated value is the zero based index of the axis within "wcsfrm". */ km = astKeyMap( "KeyCase=0", status ); for( i = 0; i < nwcs; i++ ){ sprintf( attr_name, "Symbol(%d)", i + 1 ); astMapPut0I( km, astGetC( wcsfrm, attr_name ), i, NULL ); } /* Split the FitsAxisOrder value into a collection of space-separated words. */ words = astChrSplit( attr, &nword ); /* Loop round them all. */ k = 0; for( i = 0; i < nword; i++ ) { /* Get the zero based index within "wcsfrm" of the axis that has a Symbol equal to the current word from FitsAxisOrder. */ if( astMapGet0I( km, words[ i ], &j ) ) { /* If this "wcsfrm" axis has already been used, report an error. */ if( j < 0 ) { if( astOK ) astError( AST__ATTIN, "astWrite(fitschan): " "attribute FitsAxisOrder (%s) refers to axis " "%s more than once.", status, attr, words[ i ] ); /* Otherwise, set the corresponding element of the returned array, and ensure this axis cannot be used again by assigning it an index of -1 in the KeyMap. */ } else { perm[ j ] = k++; astMapPut0I( km, words[ i ], -1, NULL ); } } /* Free the memory holding the copy of the word. */ words[ i ] = astFree( words[ i ] ); } /* Report an error if any wcsfrm axes were not included in FitsAxisOrder. */ if( astOK ) { for( i = 0; i < nwcs; i++ ){ sprintf( attr_name, "Symbol(%d)", i + 1 ); if( astMapGet0I( km, astGetC( wcsfrm, attr_name ), &j ) ) { if( j >= 0 ) { astError( AST__ATTIN, "astWrite(fitschan): attribute FitsAxisOrder " "(%s) does not specify a position for WCS axis '%s'.", status, attr, astGetC( wcsfrm, attr_name ) ); break; } } } } /* Free resources. */ words = astFree( words ); km = astAnnul( km ); } return result; } static int FitsFromStore( AstFitsChan *this, FitsStore *store, int encoding, double *dim, AstFrameSet *fs, const char *method, const char *class, int *status ){ /* * Name: * FitsFromStore * Purpose: * Store WCS keywords in a FitsChan. * Type: * Private function. * Synopsis: * int FitsFromStore( AstFitsChan *this, FitsStore *store, int encoding, * double *dim, AstFrameSet *fs, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using a specified encoding. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * encoding * The encoding to use. * dim * Pointer to an array holding the array dimensions (AST__BAD * indicates that the dimenson is not known). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ int ret; /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Set the current card so that it points to the last WCS-related keyword in the FitsChan (whether previously read or not). Any new WCS related keywords either over-write pre-existing cards for the same keyword, or (if no pre-existing card exists) are inserted after the last WCS related keyword. */ FindWcs( this, 1, 1, 0, method, class, status ); /* Do each non-standard FITS encoding... */ if( encoding == DSS_ENCODING ){ ret = DSSFromStore( this, store, method, class, status ); } else if( encoding == FITSPC_ENCODING ){ ret = PCFromStore( this, store, method, class, status ); } else if( encoding == FITSIRAF_ENCODING ){ ret = IRAFFromStore( this, store, method, class, status ); } else if( encoding == FITSAIPS_ENCODING ){ ret = AIPSFromStore( this, store, method, class, status ); } else if( encoding == FITSAIPSPP_ENCODING ){ ret = AIPSPPFromStore( this, store, method, class, status ); } else if( encoding == FITSCLASS_ENCODING ){ ret = CLASSFromStore( this, store, fs, dim, method, class, status ); /* Standard FITS-WCS encoding */ } else { ret = WcsFromStore( this, store, method, class, status ); } /* If there are any Tables in the FitsStore move the KeyMap that contains them from the FitsStore to the FitsChan, from where they can be retrieved using the public astGetTables method. */ if( astMapSize( store->tables ) > 0 ) { if( !this->tables ) this->tables = astKeyMap( " ", status ); astMapCopy( this->tables, store->tables ); (void) astAnnul( store->tables ); store->tables = astKeyMap( " ", status ); } /* If an error has occurred, return zero. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static FitsStore *FitsToStore( AstFitsChan *this, int encoding, const char *method, const char *class, int *status ){ /* * Name: * FitsToStore * Purpose: * Return a pointer to a FitsStore structure containing WCS information * read from the supplied FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * FitsStore *FitsToStore( AstFitsChan *this, int encoding, * const char *method, const char *class ) * Class Membership: * FitsChan member function. * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function creates a new FitsStore containing WCS information * read from the supplied FitsChan using the specified encoding. An * error is reported and a null pointer returned if the FitsChan does * not contain usable WCS information with the specified encoding. * Parameters: * this * Pointer to the FitsChan. * encoding * The encoding to use. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * Returned Value: * A pointer to a new FitsStore, or NULL if an error has occurred. The * FitsStore should be released using FreeStore function when it is no * longer needed. */ /* Local Variables: */ AstFitsChan *trans; FitsStore *ret; /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Allocate memory for the new FitsStore, and store NULL pointers in it. */ ret = (FitsStore *) astMalloc( sizeof(FitsStore) ); if( ret ) { ret->cname = NULL; ret->ctype = NULL; ret->ctype_com = NULL; ret->cunit = NULL; ret->ps = NULL; ret->radesys = NULL; ret->wcsname = NULL; ret->wcsaxes = NULL; ret->pc = NULL; ret->cdelt = NULL; ret->crpix = NULL; ret->crval = NULL; ret->equinox = NULL; ret->latpole = NULL; ret->lonpole = NULL; ret->mjdobs = NULL; ret->mjdavg = NULL; ret->dut1 = NULL; ret->pv = NULL; ret->specsys = NULL; ret->ssyssrc = NULL; ret->obsgeox = NULL; ret->obsgeoy = NULL; ret->obsgeoz = NULL; ret->restfrq = NULL; ret->restwav = NULL; ret->zsource = NULL; ret->velosys = NULL; ret->asip = NULL; ret->bsip = NULL; ret->apsip = NULL; ret->bpsip = NULL; ret->imagfreq = NULL; ret->axref = NULL; ret->naxis = 0; ret->timesys = NULL; ret->tables = astKeyMap( " ", status ); ret->skyref = NULL; ret->skyrefp = NULL; ret->skyrefis = NULL; } /* Call the routine apropriate to the encoding. */ if( encoding == DSS_ENCODING ){ DSSToStore( this, ret, method, class, status ); /* All other foreign encodings are treated as variants of FITS-WCS. */ } else { /* Create a new FitsChan containing standard translations for any non-standard keywords in the supplied FitsChan. The non-standard keywords are marked as provisionally read in the supplied FitsChan. */ trans = SpecTrans( this, encoding, method, class, status ); /* Copy the required values to the FitsStore, using keywords in "trans" in preference to those in "this". */ WcsToStore( this, trans, ret, method, class, status ); /* Delete the temporary FitsChan holding translations of non-standard keywords. */ if( trans ) trans = (AstFitsChan *) astDelete( trans ); /* Store the number of pixel axes. This is taken as the highest index used in any primary CRPIX keyword. */ ret->naxis = GetMaxJM( &(ret->crpix), ' ', status ) + 1; } /* If an error has occurred, free the returned FitsStore, and return a null pointer. */ if( !astOK ) ret = FreeStore( ret, status ); /* Return the answer. */ return ret; } static void FreeItem( double ****item, int *status ){ /* * Name: * FreeItem * Purpose: * Frees all dynamically allocated memory associated with a specified * item in a FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FreeItem( double ****item, int *status ); * Class Membership: * FitsChan member function. * Description: * Frees all dynamically allocated memory associated with the specified * item in a FitsStore. A NULL pointer is stored in the FitsStore. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crval) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (j), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (i) or projection parameter (m). * status * Pointer to the inherited status variable. * Notes: * - This function attempt to execute even if an error has occurred. */ /* Local Variables: */ int si; /* Integer co-ordinate version index */ int j; /* Intermediate co-ordinate axis index */ int oldstatus; /* Old error status value */ int oldreport; /* Old error reporting value */ /* Other initialisation to avoid compiler warnings. */ oldreport = 0; /* Check the supplied pointer */ if( item && *item ){ /* Start a new error reporting context. */ oldstatus = astStatus; if( !astOK ) { oldreport = astReporting( 0 ); astClearStatus; } /* Loop round each coordinate version. */ for( si = 0; si < astSizeOf( (void *) *item )/sizeof(double **); si++ ){ /* Check the pointer stored for this co-ordinate version is not null. */ if( (*item)[si] ) { /* Loop round the intermediate axes. */ for( j = 0; j < astSizeOf( (void *) (*item)[si] )/sizeof(double *); j++ ){ /* Free the pixel axis/parameter index pointer. */ (*item)[si][j] = (double *) astFree( (void *) (*item)[si][j] ); } /* Free the intermediate axes pointer */ (*item)[si] = (double **) astFree( (void *) (*item)[si] ); } } /* Free the co-ordinate versions pointer */ *item = (double ***) astFree( (void *) *item ); /* If there was an error status on entry to this function, re-instate it. Otherwise, allow any new error status to remain. */ if( oldstatus ){ if( !astOK ) astClearStatus; astSetStatus( oldstatus ); astReporting( oldreport ); } } } static void FreeItemC( char *****item, int *status ){ /* * Name: * FreeItemC * Purpose: * Frees all dynamically allocated memory associated with a specified * string item in a FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FreeItemC( char *****item, int *status ) * Class Membership: * FitsChan member function. * Description: * Frees all dynamically allocated memory associated with the specified * string item in a FitsStore. A NULL pointer is stored in the FitsStore. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->ctype) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (j), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element (a char pointyer) for every pixel axis (i) or * projection parameter (m). * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ int si; /* Integer co-ordinate version index */ int i; /* Intermediate co-ordinate axis index */ int jm; /* Pixel co-ordinate axis or parameter index */ int oldstatus; /* Old error status value */ int oldreport; /* Old error reporting value */ /* Other initialisation to avoid compiler warnings. */ oldreport = 0; /* Check the supplied pointer */ if( item && *item ){ /* Start a new error reporting context. */ oldstatus = astStatus; if( !astOK ) { oldreport = astReporting( 0 ); astClearStatus; } /* Loop round each coordinate version. */ for( si = 0; si < astSizeOf( (void *) *item )/sizeof(char ***); si++ ){ /* Check the pointer stored for this co-ordinate version is not null. */ if( (*item)[si] ) { /* Loop round the intermediate axes. */ for( i = 0; i < astSizeOf( (void *) (*item)[si] )/sizeof(char **); i++ ){ /* Check the pointer stored for this intermediate axis is not null. */ if( (*item)[si][i] ) { /* Loop round the pixel axes or parameter values. */ for( jm = 0; jm < astSizeOf( (void *) (*item)[si][i] )/sizeof(char *); jm++ ){ /* Free the string. */ (*item)[si][i][jm] = (char *) astFree( (void *) (*item)[si][i][jm] ); } /* Free the pixel axes/parameter pointer */ (*item)[si][i] = (char **) astFree( (void *) (*item)[si][i] ); } } /* Free the intermediate axes pointer */ (*item)[si] = (char ***) astFree( (void *) (*item)[si] ); } } /* Free the co-ordinate versions pointer */ *item = (char ****) astFree( (void *) *item ); /* If there was an error status on entry to this function, re-instate it. Otherwise, allow any new error status to remain. */ if( oldstatus ){ if( !astOK ) astClearStatus; astSetStatus( oldstatus ); astReporting( oldreport ); } } } static FitsStore *FreeStore( FitsStore *store, int *status ){ /* * Name: * FreeStore * Purpose: * Free dynamic arrays stored in a FitsStore structure. * Type: * Private function. * Synopsis: * FitsStore *FreeStore( FitsStore *store, int *status ) * Class Membership: * FitsChan * Description: * This function frees all dynamically allocated arrays stored in the * supplied FitsStore structure, and returns a NULL pointer. * Parameters: * store * Pointer to the structure to clean. * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if an error exists on entry. */ /* Return if no FitsStore was supplied. */ if( !store ) return NULL; /* Free each of the dynamic arrays stored in the FitsStore. */ FreeItemC( &(store->cname), status ); FreeItemC( &(store->ctype), status ); FreeItemC( &(store->ctype_com), status ); FreeItemC( &(store->cunit), status ); FreeItemC( &(store->radesys), status ); FreeItemC( &(store->wcsname), status ); FreeItemC( &(store->specsys), status ); FreeItemC( &(store->ssyssrc), status ); FreeItemC( &(store->ps), status ); FreeItemC( &(store->timesys), status ); FreeItem( &(store->pc), status ); FreeItem( &(store->cdelt), status ); FreeItem( &(store->crpix), status ); FreeItem( &(store->crval), status ); FreeItem( &(store->equinox), status ); FreeItem( &(store->latpole), status ); FreeItem( &(store->lonpole), status ); FreeItem( &(store->mjdobs), status ); FreeItem( &(store->dut1), status ); FreeItem( &(store->mjdavg), status ); FreeItem( &(store->pv), status ); FreeItem( &(store->wcsaxes), status ); FreeItem( &(store->obsgeox), status ); FreeItem( &(store->obsgeoy), status ); FreeItem( &(store->obsgeoz), status ); FreeItem( &(store->restfrq), status ); FreeItem( &(store->restwav), status ); FreeItem( &(store->zsource), status ); FreeItem( &(store->velosys), status ); FreeItem( &(store->asip), status ); FreeItem( &(store->bsip), status ); FreeItem( &(store->apsip), status ); FreeItem( &(store->bpsip), status ); FreeItem( &(store->imagfreq), status ); FreeItem( &(store->axref), status ); store->tables = astAnnul( store->tables ); FreeItem( &(store->skyref), status ); FreeItem( &(store->skyrefp), status ); FreeItemC( &(store->skyrefis), status ); return (FitsStore *) astFree( (void *) store ); } static char *FormatKey( const char *key, int c1, int c2, char s, int *status ){ /* * Name: * FormatKey * Purpose: * Format a keyword name with indices and co-ordinate version character. * Type: * Private function. * Synopsis: * char *FormatKey( const char *key, int c1, int c2, char s, int *status ) * Class Membership: * FitsChan * Description: * This function formats a keyword name by including the supplied * axis/parameter indices and co-ordinate version character. * Parameters: * key * The base name of the keyword (e.g. "CD", "CRVAL", etc). * c1 * An integer value to append to the end of the keyword. Ignored if * less than zero. * c2 * A second integer value to append to the end of the keyword. Ignored if * less than zero. This second integer is preceded by an underscore. * s * The co-ordinate version character to append to the end of the * final string. Ignored if blank. * status * Pointer to the inherited status variable. * Returned Value; * A pointer to a static character buffer containing the final string. * NULL if an error occurs. */ /* Local Variables: */ astDECLARE_GLOBALS char *ret; int len; int nc; /* Initialise */ ret = NULL; /* Check inherited status */ if( !astOK ) return ret; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* No characters stored yet. A value of -1 is used to indicate that an error has occurred. */ len = 0; /* Store the supplied keyword base name. */ if( len >= 0 && ( nc = sprintf( formatkey_buff + len, "%s", key ) ) >= 0 ){ len += nc; } else { len = -1; } /* If index c1 has been supplied, append it to the end of the string. */ if( c1 >= 0 ) { if( len >= 0 && ( nc = sprintf( formatkey_buff + len, "%d", c1 ) ) >= 0 ){ len += nc; } else { len = -1; } /* If index c2 has been supplied, append it to the end of the string, preceded by an underscore. */ if( c2 >= 0 ) { if( len >= 0 && ( nc = sprintf( formatkey_buff + len, "_%d", c2 ) ) >= 0 ){ len += nc; } else { len = -1; } } } /* If a co-ordinate version character has been supplied, append it to the end of the string. */ if( s != ' ' ) { if( len >= 0 && ( nc = sprintf( formatkey_buff + len, "%c", s ) ) >= 0 ){ len += nc; } else { len = -1; } } /* Report an error if necessary */ if( len < 0 && astOK ) { astError( AST__INTER, "FormatKey(fitschan): AST internal error; failed " "to format the keyword %s with indices %d and %d, and " "co-ordinate version %c.", status, key, c1, c2, s ); ret = NULL; } else { ret = formatkey_buff; } return formatkey_buff; } static AstObject *FsetFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * FsetFromStore * Purpose: * Create a FrameSet using the the information previously stored in * the suppllied FitsStore structure. * Type: * Private function. * Synopsis: * AstObject *FsetFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function creates a new FrameSet containing WCS information * stored in the supplied FitsStore. A null pointer is returned and no * error is reported if this is not possible. * Parameters: * this * The FitsChan from which the keywords were read. Warning messages * are added to this FitsChan if the celestial co-ordinate system is * not recognized. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new FrameSet, or a null pointer if no FrameSet * could be constructed. * Notes: * - The pixel Frame is given a title of "Pixel Coordinates", and * each axis in the pixel Frame is given a label of the form "Pixel * axis ", where is the axis index (starting at one). * - The FITS CTYPE keyword values are used to set the labels for any * non-celestial axes in the physical coordinate Frames, and the FITS * CUNIT keywords are used to set the corresponding units strings. * - On exit, the pixel Frame is the base Frame, and the physical * Frame derived from the primary axis descriptions is the current Frame. * - Extra Frames are added to hold any secondary axis descriptions. All * axes within such a Frame refer to the same coordinate version ('A', * 'B', etc). */ /* Local Variables: */ AstFrame *frame; /* Pointer to pixel Frame */ AstFrameSet *ret; /* Pointer to returned FrameSet */ char buff[ 20 ]; /* Buffer for axis label */ char s; /* Co-ordinate version character */ int i; /* Pixel axis index */ int physical; /* Index of primary physical co-ordinate Frame */ int pixel; /* Index of pixel Frame in returned FrameSet */ int use; /* Has this co-ordinate version been used? */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return (AstObject *) ret; /* Only proceed if there are some axes. */ if( store->naxis ) { /* Create a Frame describing the pixel coordinate system. Give it the Domain GRID. */ frame = astFrame( store->naxis, "Title=Pixel Coordinates,Domain=GRID", status ); /* Store labels for each pixel axis. */ if( astOK ){ for( i = 0; i < store->naxis; i++ ){ sprintf( buff, "Pixel axis %d", i + 1 ); astSetLabel( frame, i, buff ); } } /* Create the FrameSet initially holding just the pixel coordinate frame (this becomes the base Frame). */ ret = astFrameSet( frame, "", status ); /* Annul the pointer to the pixel coordinate Frame. */ frame = astAnnul( frame ); /* Get the index of the pixel Frame in the FrameSet. */ pixel = astGetCurrent( ret ); /* Produce the Frame describing the primary axis descriptions, and add it into the FrameSet. */ AddFrame( this, ret, pixel, store->naxis, store, ' ', method, class, status ); /* Get the index of the primary physical co-ordinate Frame in the FrameSet. */ physical = astGetCurrent( ret ); /* Loop, producing secondary axis Frames for each of the co-ordinate versions stored in the FitsStore. */ for( s = 'A'; s <= GetMaxS( &(store->crval), status ) && astOK; s++ ){ /* Only use this co-ordinate version character if any of the required keywords (for any axis) are stored in the FitsStore. */ use = 0; for( i = 0; i < store->naxis; i++ ){ if( GetItem( &(store->crval), i, 0, s, NULL, method, class, status ) != AST__BAD || GetItem( &(store->crpix), 0, i, s, NULL, method, class, status ) != AST__BAD || GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ) != NULL ){ use = 1; break; } } /* If this co-ordinate version has been used, add a Frame to the returned FrameSet holding this co-ordinate version. */ if( use ) AddFrame( this, ret, pixel, store->naxis, store, s, method, class, status ); } /* Ensure the pixel Frame is the Base Frame and the primary physical Frame is the Current Frame. */ astSetBase( ret, pixel ); astSetCurrent( ret, physical ); /* Remove any unneeded Frames that hold a FITS representation of offset coordinates. */ TidyOffsets( ret, status ); /* If an error has occurred, free the returned FrameSet and return a null pointer. */ if( !astOK ) ret = astAnnul( ret ); } /* Return the answer. */ return (AstObject *) ret; } static FitsStore *FsetToStore( AstFitsChan *this, AstFrameSet *fset, int naxis, double *dim, int encoding, const char *class, const char *method, int *status ){ /* * Name: * FsetToStore * Purpose: * Fill a FitsStore structure with a description of the supplied * FrameSet. * Type: * Private function. * Synopsis: * FitsStore *FsetToStore( AstFitsChan *this, AstFrameSet *fset, int naxis, * double *dim, int encoding, const char *class, * const char *method, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function creates a new FitsStore containing WCS information * read from the supplied FitsChan using the specified encoding. An * error is reported and a null pointer returned if the FitsChan does * not contain usable WCS information with the specified encoding. * Parameters: * this * Pointer to the FitsChan. * fset * Pointer to the FrameSet. * naxis * The number of axes in the Base Frame of the supplied FrameSet. * dim * Pointer to an array of pixel axis dimensions. Individual elements * will be AST__BAD if dimensions are not known. * encoding * The encoding being used. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a new FitsStore, or NULL if an error has occurred. The * FitsStore should be released using FreeStore function when it is no * longer needed. * Notes: * - A NULL pointer will be returned if this function is invoked * with the AST error status set, or if it should fail for any * reason. * - The Base Frame in the FrameSet is used as the pixel Frame, and * the Current Frame is used to create the primary axis descriptions. * Attempts are made to create secondary axis descriptions for any * other Frames in the FrameSet (up to a total of 26). */ /* Local Variables: */ AstFrame *frame; /* A Frame */ const char *id; /* Frame Ident string */ int nfrm; /* Number of Frames in FrameSet */ char *sid; /* Pointer to array of version letters */ int frms[ 'Z' + 1 ]; /* Array of Frame indices */ FitsStore *ret; /* Returned FitsStore */ char s; /* Next available co-ordinate version character */ char s0; /* Co-ordinate version character */ int ibase; /* Base Frame index */ int icurr; /* Current Frame index */ int ifrm; /* Next Frame index */ int isoff; /* Is the Frame an offset SkyFrame? */ int primok; /* Primary Frame stored succesfully? */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Allocate memory for the new FitsStore, and store NULL pointers in it. */ ret = (FitsStore *) astMalloc( sizeof(FitsStore) ); if( astOK ) { ret->cname = NULL; ret->ctype = NULL; ret->ctype_com = NULL; ret->cunit = NULL; ret->ps = NULL; ret->radesys = NULL; ret->wcsname = NULL; ret->wcsaxes = NULL; ret->pc = NULL; ret->cdelt = NULL; ret->crpix = NULL; ret->crval = NULL; ret->equinox = NULL; ret->latpole = NULL; ret->lonpole = NULL; ret->dut1 = NULL; ret->mjdobs = NULL; ret->mjdavg = NULL; ret->pv = NULL; ret->specsys = NULL; ret->ssyssrc = NULL; ret->obsgeox = NULL; ret->obsgeoy = NULL; ret->obsgeoz = NULL; ret->restfrq = NULL; ret->restwav = NULL; ret->zsource = NULL; ret->velosys = NULL; ret->asip = NULL; ret->bsip = NULL; ret->apsip = NULL; ret->bpsip = NULL; ret->imagfreq = NULL; ret->axref = NULL; ret->naxis = naxis; ret->timesys = NULL; ret->tables = astKeyMap( " ", status ); ret->skyref = NULL; ret->skyrefp = NULL; ret->skyrefis = NULL; /* Obtain the index of the Base Frame (i.e. the pixel frame ). */ ibase = astGetBase( fset ); /* Obtain the index of the Current Frame (i.e. the Frame to use as the primary physical coordinate frame). */ icurr = astGetCurrent( fset ); /* Does the current Frame contain a SkyFrame that describes offset coordinates? */ isoff = IsSkyOff( fset, icurr, status ); /* Add a description of the primary axes to the FitsStore, based on the Current Frame in the FrameSet. */ primok = AddVersion( this, fset, ibase, icurr, ret, dim, ' ', encoding, isoff, method, class, status ); /* Do not add any alternate axis descriptions if the primary axis descriptions could not be produced. */ if( primok && astOK ) { /* Get the number of Frames in the FrameSet. */ nfrm = astGetNframe( fset ); /* We now need to allocate a version letter to each Frame. Allocate memory to hold the version letter assigned to each Frame. */ sid = (char *) astMalloc( ( nfrm + 1 )*sizeof( char ) ); /* The frms array has an entry for each of the 26 possible version letters (starting at A and ending at Z). Each entry holds the index of the Frame which has been assigned that version character. Initialise this array to indicate that no version letters have yet been assigned. */ for( s = 'A'; s <= 'Z'; s++ ) { frms[ (int) s ] = 0; } /* Loop round all frames (excluding the current and base and IWC Frames which do not need version letters). If the Frame has an Ident attribute consisting of a single upper case letter, use it as its version letter unless that letter has already been given to an earlier frame. IWC Frames are not written out - identify them by giving them a "sid" value of 1 (an illegal FITS axis description character). */ for( ifrm = 1; ifrm <= nfrm; ifrm++ ){ sid[ ifrm ] = 0; if( ifrm != icurr && ifrm != ibase ) { frame = astGetFrame( fset, ifrm ); if( astChrMatchN( astGetDomain( frame ), "IWC", 3 ) ) { sid[ ifrm ] = 1; } else { id = astGetIdent( frame ); if( strlen( id ) == 1 && isupper( id[ 0 ] ) ) { if( frms[ (int) id[ 0 ] ] == 0 ) { frms[ (int) id[ 0 ] ] = ifrm; sid[ ifrm ] = id[ 0 ]; } } } (void) astAnnul( frame ); } } /* Now go round all the Frames again, looking for Frames which did not get a version letter assigned to it on the previous loop. Assign them letters now, selected them from the letters not already assigned (lowest to highest). */ s = 'A' - 1; for( ifrm = 1; ifrm <= nfrm; ifrm++ ){ if( ifrm != icurr && ifrm != ibase && sid[ ifrm ] != 1 ) { if( sid[ ifrm ] == 0 ){ while( frms[ (int) ++s ] != 0 ); if( s <= 'Z' ) { sid[ ifrm ] = s; frms[ (int) s ] = ifrm; } } } } /* If the primary headers describe offset coordinates, create an alternate axis description for the correspondsing absolute coordinate system. */ if( isoff && ++s <= 'Z' ) { (void) AddVersion( this, fset, ibase, icurr, ret, dim, s, encoding, -1, method, class, status ); } /* Now go through all the other Frames in the FrameSet, attempting to create alternate axis descriptions for each one. */ for( ifrm = 1; ifrm <= nfrm; ifrm++ ){ s0 = sid[ ifrm ]; if( s0 != 0 && s0 != 1 ) { /* Does it contain an offset sky frame? */ isoff = IsSkyOff( fset, ifrm, status ); /* Write out the Frame - offset if it is offset, absolute otherwise. */ (void) AddVersion( this, fset, ibase, ifrm, ret, dim, s0, encoding, isoff, method, class, status ); /* If the Frame is offset, create an extra alternate axis description for the correspondsing absolute coordinate system. */ if( isoff && ++s <= 'Z' ) { (void) AddVersion( this, fset, ibase, ifrm, ret, dim, s, encoding, -1, method, class, status ); } } } /* Free memory holding version letters */ sid = (char *) astFree( (void *) sid ); } /* If an error has occurred, or if the primary Frame could not be cerated, free the returned FitsStore, and return a null pointer. */ if( !astOK || !primok ) ret = FreeStore( ret, status ); } /* Return the answer. */ return ret; } static int GetClean( AstFitsChan *this, int *status ) { /* * Name: * GetClean * Purpose: * Return the value of the Clean attribute. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetClean( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns the value of the Clean attribute. Since this * attribute controls the behaviour of the FitsChan in the event of an * error condition, it is is necessary to ignore any inherited error * condition when getting the attribute value. This is why the * astMAKE_GET macro is not used. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The Clean value to use. */ /* Return if no FitsChan pointer was supplied. */ if ( !this ) return 0; /* Return the attribute value, supplying a default value of 0 (false). */ return ( this->clean == -1 ) ? 0 : (this->clean ? 1 : 0 ); } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * FitsChan member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied FitsChan, * in bytes. * Parameters: * this * Pointer to the FitsChan. * 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: */ AstFitsChan *this; /* Pointer to FitsChan structure */ FitsCard *card; /* Pointer to next FitsCard */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the FitsChan structure. */ this = (AstFitsChan *) this_object; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->warnings ); result += astGetObjSize( this->keyseq ); result += astGetObjSize( this->keywords ); result += astGetObjSize( this->tables ); card = (FitsCard *) ( this->head ); while( card ) { result += astTSizeOf( card ); result += card->size; result += astTSizeOf( card->comment ); card = GetLink( card, NEXT, "astGetObjSize", "FitsChan", status ); if( (void *) card == this->head ) break; } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetCDMatrix( AstFitsChan *this, int *status ){ /* * Name: * GetCDMatrix * Purpose: * Get the value of the CDMatrix attribute. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetCDMatrix( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * If the CDMatrix attribute has been set, then its value is returned. * Otherwise, the supplied FitsChan is searched for keywords of the * form CDi_j. If any are found a non-zero value is returned. Otherwise * a zero value is returned. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The attribute value to use. * Notes: * - A value of zero is returned if an error has already occurred * or if an error occurs for any reason within this function. */ /* Local Variables... */ int ret; /* Returned value */ int icard; /* Index of current card on entry */ /* Check the global status. */ if( !astOK ) return 0; /* If a value has been supplied for the CDMatrix attribute, use it. */ if( astTestCDMatrix( this ) ) { ret = this->cdmatrix; /* Otherwise, check for the existence of CDi_j keywords... */ } else { /* Save the current card index, and rewind the FitsChan. */ icard = astGetCard( this ); astClearCard( this ); /* If the FitsChan contains any keywords with the format "CDi_j" then return 1. Otherwise return zero. */ ret = astKeyFields( this, "CD%1d_%1d", 0, NULL, NULL ) ? 1 : 0; /* Reinstate the original current card index. */ astSetCard( this, icard ); } /* Return the result. */ return astOK ? ret : 0; } static int GetEncoding( AstFitsChan *this, int *status ){ /* * Name: * GetEncoding * Purpose: * Get the value of the Encoding attribute. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetEncoding( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * If the Encoding attribute has been set, then its value is returned. * Otherwise, an attempt is made to determine the encoding scheme by * looking for selected keywords within the FitsChan. Checks are made * for the following keywords in the order specified, and the * corresponding encoding is adopted when the first one is found ( where * i, j and m are integers and s is a single upper case character): * * 1) Any keywords starting with "BEGAST" = Native encoding * 2) DELTAV and VELO-xxx (or VLSR) keywords = FITS-CLASS. * 3) Any AIPS spectral CTYPE values: * Any of CDi_j, PROJP, LONPOLE, LATPOLE = FITS-AIPS++ encoding: * None of the above = FITS-AIPS encoding. * 4) Any keywords matching PCiiijjj = FITS-PC encoding * 5) Any keywords matching CDiiijjj = FITS-IRAF encoding * 6) Any keywords matching CDi_j, AND at least one of RADECSYS, PROJPi * or CmVALi = FITS-IRAF encoding * 7) Any keywords RADECSYS, PROJPi or CmVALi, and no CDi_j or PCi_j * keywords, = FITS-PC encoding * 8) Any keywords matching CROTAi = FITS-AIPS encoding * 9) Keywords matching CRVALi = FITS-WCS encoding * 10) The PLTRAH keyword = DSS encoding * 11) If none of the above keywords are found, Native encoding is assumed. * * For cases 2) to 9), a check is also made that the header contains * at least one of each keyword CTYPE, CRPIX and CRVAL. If not, then * the checking process continues to the next case. This goes some way * towards ensuring that the critical keywords used to determine the * encoding are part of a genuine WCS description and have not just been * left in the header by accident. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The encoding scheme identifier. * Notes: * - The function returns UNKNOWN_ENCODING if an error has already occurred * or if an error occurs for any reason within this function. */ /* Local Variables... */ int hascd; /* Any CDi_j keywords found? */ int haspc; /* Any PCi_j keywords found? */ int haswcs; /* Any CRVAL, CTYPE and CRPIX found? */ int icard; /* Index of current card on entry */ int ret; /* Returned value */ /* Check the global status. */ if( !astOK ) return UNKNOWN_ENCODING; /* If a value has been supplied for the Encoding attribute, use it. */ if( astTestEncoding( this ) ) { ret = this->encoding; /* Otherwise, check for the existence of certain critcal keywords... */ } else { /* See if the header contains some CTYPE, CRPIX and CRVAL keywords. */ haswcs = astKeyFields( this, "CTYPE%d", 0, NULL, NULL ) && astKeyFields( this, "CRPIX%d", 0, NULL, NULL ) && astKeyFields( this, "CRVAL%d", 0, NULL, NULL ); /* See if there are any CDi_j keywords. */ hascd = astKeyFields( this, "CD%1d_%1d", 0, NULL, NULL ); /* See if there are any PCi_j keywords. */ haspc = astKeyFields( this, "PC%1d_%1d", 0, NULL, NULL ); /* Save the current card index, and rewind the FitsChan. */ icard = astGetCard( this ); astClearCard( this ); /* If the FitsChan contains any keywords starting with "BEGAST", then return "Native" encoding. */ if( astKeyFields( this, "BEGAST%2f", 0, NULL, NULL ) ){ ret = NATIVE_ENCODING; /* Otherwise, look for a FITS-CLASS signature... */ } else if( haswcs && LooksLikeClass( this, "astGetEncoding", "AstFitsChan", status ) ){ ret = FITSCLASS_ENCODING; /* Otherwise, if the FitsChan contains any CTYPE keywords which have the peculiar form used by AIPS, then use "FITS-AIPS" or "FITS-AIPS++" encoding. */ } else if( haswcs && HasAIPSSpecAxis( this, "astGetEncoding", "AstFitsChan", status ) ){ if( hascd || astKeyFields( this, "PROJP%d", 0, NULL, NULL ) || astKeyFields( this, "LONPOLE", 0, NULL, NULL ) || astKeyFields( this, "LATPOLE", 0, NULL, NULL ) ) { ret = FITSAIPSPP_ENCODING; } else { ret = FITSAIPS_ENCODING; } /* Otherwise, if the FitsChan contains the "PLTRAH" keywords, use "DSS" encoding. */ } else if( astKeyFields( this, "PLTRAH", 0, NULL, NULL ) ){ ret = DSS_ENCODING; /* Otherwise, if the FitsChan contains any keywords with the format "PCiiijjj" then return "FITS-PC" encoding. */ } else if( haswcs && astKeyFields( this, "PC%3d%3d", 0, NULL, NULL ) ){ ret = FITSPC_ENCODING; /* Otherwise, if the FitsChan contains any keywords with the format "CDiiijjj" then return "FITS-IRAF" encoding. */ } else if( haswcs && astKeyFields( this, "CD%3d%3d", 0, NULL, NULL ) ){ ret = FITSIRAF_ENCODING; /* Otherwise, if the FitsChan contains any keywords with the format "CDi_j" AND there is a RADECSYS. PROJPi or CmVALi keyword, then return "FITS-IRAF" encoding. If "CDi_j" is present but none of the others are, return "FITS-WCS" encoding. */ } else if( haswcs && hascd ) { if( ( astKeyFields( this, "RADECSYS", 0, NULL, NULL ) && !astKeyFields( this, "RADESYS", 0, NULL, NULL ) ) || ( astKeyFields( this, "PROJP%d", 0, NULL, NULL ) && !astKeyFields( this, "PV%d_%d", 0, NULL, NULL ) ) || ( astKeyFields( this, "C%1dVAL%d", 0, NULL, NULL )) ){ ret = FITSIRAF_ENCODING; } else { ret = FITSWCS_ENCODING; } /* Otherwise, if the FitsChan contains any keywords with the format RADECSYS. PROJPi or CmVALi keyword, then return "FITS-PC" encoding, so long as there are no FITS-WCS equivalent keywords. */ } else if( haswcs && !haspc && !hascd && ( ( astKeyFields( this, "RADECSYS", 0, NULL, NULL ) && !astKeyFields( this, "RADESYS", 0, NULL, NULL ) ) || ( astKeyFields( this, "PROJP%d", 0, NULL, NULL ) && !astKeyFields( this, "PV%d_%d", 0, NULL, NULL ) ) || astKeyFields( this, "C%1dVAL%d", 0, NULL, NULL ) ) ) { ret = FITSPC_ENCODING; /* Otherwise, if the FitsChan contains any keywords with the format "CROTAi" then return "FITS-AIPS" encoding. */ } else if( haswcs && astKeyFields( this, "CROTA%d", 0, NULL, NULL ) ){ ret = FITSAIPS_ENCODING; /* Otherwise, if the FitsChan contains any keywords with the format "CRVALi" then return "FITS-WCS" encoding. */ } else if( haswcs && astKeyFields( this, "CRVAL%d", 0, NULL, NULL ) ){ ret = FITSWCS_ENCODING; /* If none of these conditions is met, assume Native encoding. */ } else { ret = NATIVE_ENCODING; } /* Reinstate the original current card index. */ astSetCard( this, icard ); } /* Return the encoding scheme. */ return astOK ? ret : UNKNOWN_ENCODING; } static void GetFiducialNSC( AstWcsMap *map, double *phi, double *theta, int *status ){ /* * Name: * GetFiducialNSC * Purpose: * Return the Native Spherical Coordinates at the fiducial point of a * WcsMap projection. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void GetFiducialNSC( AstWcsMap *map, double *phi, double *theta, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns the native spherical coords corresponding at * the fiducial point of a WcsMap. * * The values of parameters 1 and 2 on the longitude axis of the WcsMap * are usually used as the native spherical coordinates of the * fiducial point. The default values for these parameters are equal * to the native spherical coordinates of the projection reference point. * The exception is that a TPN projection always uses the default * values, since the projection parameters are used to store polynomial * coefficients. * Parameters: * map * Pointer to the WcsMap. * phi * Address of a location at which to return the native spherical * longitude at the fiducial point (radians). * theta * Address of a location at which to return the native spherical * latitude at the fiducial point (radians). * status * Pointer to the inherited status variable. */ /* Local Variables: */ int axlon; /* Index of longitude axis */ /* Initialise */ *phi = AST__BAD; *theta = AST__BAD; /* Check the inherited status. */ if( !astOK ) return; /* If this is not a TPN projection get he value of the required projection parameters (the default values for these are equal to the fixed native shperical coordinates at the projection reference point). */ if( astGetWcsType( map ) != AST__TPN ) { axlon = astGetWcsAxis( map, 0 ); if( astGetPV( map, axlon, 0 ) != 0.0 ) { *phi = AST__DD2R*astGetPV( map, axlon, 1 ); *theta = AST__DD2R*astGetPV( map, axlon, 2 ); } else { *phi = astGetNatLon( map ); *theta = astGetNatLat( map ); } /* If this is a TPN projection, the returned values are always the fixed native shperical coordinates at the projection reference point). */ } else { *phi = astGetNatLon( map ); *theta = astGetNatLat( map ); } } static void GetFiducialPPC( AstWcsMap *map, double *x0, double *y0, int *status ){ /* * Name: * GetFiducialPPC * Purpose: * Return the IWC at the fiducial point of a WcsMap projection. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void GetFiducialPPC( AstWcsMap *map, double *x0, double *y0, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns the projection plane coords corresponding to * the native spherical coords of the fiducial point of a FITS-WCS * header. Note, projection plane coordinates (PPC) are equal to * Intermediate World Coordinates (IWC) except for cases where the * fiducial point does not correspond to the projection reference point. * In these cases, IWC and PPC will be connected by a translation * which ensures that the fiducial point corresponds to the origin of * IWC. * * The values of parameters 1 and 2 on the longitude axis of * the WcsMap are used as the native spherical coordinates of the * fiducial point. The default values for these parameters are equal * to the native spherical coordinates of the projection reference point. * Parameters: * map * Pointer to the WcsMap. * x0 * Address of a location at which to return the PPC X axis value at * the fiducial point (radians). * y0 * Address of a location at which to return the PPC Y axis value at * the fiducial point (radians). * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *pset1; /* Pointer to the native spherical PointSet */ AstPointSet *pset2; /* Pointer to the intermediate world PointSet */ double **ptr1; /* Pointer to pset1 data */ double **ptr2; /* Pointer to pset2 data */ int axlat; /* Index of latitude axis */ int axlon; /* Index of longitude axis */ int i; /* Loop count */ int naxes; /* Number of axes */ /* Initialise */ *x0 = AST__BAD; *y0 = AST__BAD; /* Check the inherited status. */ if( !astOK ) return; /* Save number of axes in the WcsMap. */ naxes = astGetNin( map ); /* Allocate resources. */ pset1 = astPointSet( 1, naxes, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( 1, naxes, "", status ); ptr2 = astGetPoints( pset2 ); /* Check pointers can be used safely. */ if( astOK ) { /* Get the indices of the longitude and latitude axes in WcsMap. */ axlon = astGetWcsAxis( map, 0 ); axlat = astGetWcsAxis( map, 1 ); /* Use zero on all non-celestial axes. */ for( i = 0; i < naxes; i++ ) ptr1[ i ][ 0 ] = 0.0; /* Get the native spherical coords at the fiducial point. */ GetFiducialNSC( map, ptr1[ axlon ], ptr1[ axlat ], status ); /* Use the inverse WcsMap to convert the native longitude and latitude of the fiducial point into PPC (x,y). */ (void) astTransform( map, pset1, 0, pset2 ); /* Return the calculated PPC coords. */ *x0 = ptr2[ axlon ][ 0 ]; *y0 = ptr2[ axlat ][ 0 ]; } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); } static int GetFiducialWCS( AstWcsMap *wcsmap, AstMapping *map2, int colon, int colat, double *fidlon, double *fidlat, int *status ){ /* * Name: * GetFiducialWCS * Purpose: * Decide on the celestial coordinates of the fiducial point. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetFiducialWCS( AstWcsMap wcsmap, AstMapping map2, int colon, * int colat, double *fidlon, double *fidlat, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns the celestial longitude and latitude values * to use for the fiducial point. These are the values stored in FITS * keywords CRVALi. * Parameters: * wcsmap * The WcsMap which converts Projection Plane Coordinates into * native spherical coordinates. The number of outputs from this * Mapping should match the number of inputs to "map2". * map2 * The Mapping which converts native spherical coordinates into WCS * coordinates. * colon * The index of the celestial longitude output from "map2". * colat * The index of the celestial latitude output from "map2". * fidlon * Pointer to a location at which to return the celestial longitude * value at the fiducial point. The value is returned in radians. * fidlat * Pointer to a location at which to return the celestial latitude * value at the fiducial point. The value is returned in radians. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the fiducial point longitude or latitude could not be * determined. One otherwise. */ /* Local Variables: */ AstPointSet *pset1; /* Pointer to the native spherical PointSet */ AstPointSet *pset2; /* Pointer to the WCS PointSet */ double **ptr1; /* Pointer to pset1 data */ double **ptr2; /* Pointer to pset2 data */ int axlat; /* Index of latitude axis */ int axlon; /* Index of longitude axis */ int iax; /* Axis index */ int naxin; /* Number of IWC axes */ int naxout; /* Number of WCS axes */ int ret; /* The returned FrameSet */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Allocate resources. */ naxin = astGetNin( map2 ); naxout = astGetNout( map2 ); pset1 = astPointSet( 1, naxin, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( 1, naxout, "", status ); ptr2 = astGetPoints( pset2 ); if( astOK ) { /* Get the indices of the latitude and longitude outputs in the WcsMap. These are not necessarily the same as "colat" and "colon" because "map2" may contain a PermMap. */ axlon = astGetWcsAxis( wcsmap, 0 ); axlat = astGetWcsAxis( wcsmap, 1 ); /* Use zero on all non-celestial axes. */ for( iax = 0; iax < naxin; iax++ ) ptr1[ iax ][ 0 ] = 0.0; /* Get the native spherical coords at the fiducial point. */ GetFiducialNSC( wcsmap, ptr1[ axlon ], ptr1[ axlat ], status ); /* The fiducial point in the celestial coordinate system is found by transforming the fiducial point in native spherical co-ordinates into absolute physical coordinates using map2. */ (void) astTransform( map2, pset1, 1, pset2 ); /* Store the returned WCS values. */ *fidlon = ptr2[ colon ][ 0 ]; *fidlat = ptr2[ colat ][ 0 ]; /* Indicate if we have been succesfull. */ if( astOK && *fidlon != AST__BAD && *fidlat != AST__BAD ) ret = 1; } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Return the result. */ return ret; } static const char *GetFitsSor( const char *string, int *status ) { /* * Name: * GetFitsSor * Purpose: * Get the string used to represent an AST spectral standard of rest. * Type: * Private function. * Synopsis: * #include "fitschan.h" * const char *GetFitsSor( const char *string, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a pointer to a static string which is the * FITS equivalent to a given SpecFrame StdOfRest value. * Parameters: * string * Pointer to a constant null-terminated string containing the * SpecFrame StdOfRest value. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a static null-terminated string containing the FITS * equivalent to the supplied string. NULL is returned if the supplied * string has no FITS equivalent. * Notes: * - A NULL pointer value will be returned if this function is * invoked wth the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Compare the supplied string with SpecFrame value for which there is a known FITS equivalent. */ if( !strcmp( string, "Topocentric" ) ){ result = "TOPOCENT"; } else if( !strcmp( string, "Geocentric" )){ result = "GEOCENTR"; } else if( !strcmp( string, "Barycentric" )){ result = "BARYCENT"; } else if( !strcmp( string, "Heliocentric" )){ result = "HELIOCEN"; } else if( !strcmp( string, "LSRK" )){ result = "LSRK"; } else if( !strcmp( string, "LSRD" )){ result = "LSRD"; } else if( !strcmp( string, "Galactic" )){ result = "GALACTOC"; } else if( !strcmp( string, "Local_group" )){ result = "LOCALGRP"; } else if( !strcmp( string, "Source" )){ result = "SOURCE"; } else { result = NULL; } /* Return the answer. */ return result; } static double GetItem( double ****item, int i, int jm, char s, char *name, const char *method, const char *class, int *status ){ /* * Name: * GetItem * Purpose: * Retrieve a value for a axis keyword value from a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double GetItem( double ****item, int i, int jm, char s, char *name, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The requested keyword value is retrieved from the specified array, * at a position indicated by the axis and co-ordinate version. * AST__BAD is returned if the array does not contain the requested * value. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crval) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (j) or projection parameter (m). * i * The zero based intermediate axis index in the range 0 to 98. Set * this to zero for keywords (e.g. CRPIX) which are not indexed by * intermediate axis number. * jm * The zero based pixel axis index (in the range 0 to 98) or parameter * index (in the range 0 to WCSLIB_MXPAR-1). Set this to zero for * keywords (e.g. CRVAL) which are not indexed by either pixel axis or * parameter number. * s * The co-ordinate version character (A to Z, or space), case * insensitive * name * A string holding a name for the item of information. A NULL * pointer may be supplied, in which case it is ignored. If a * non-NULL pointer is supplied, an error is reported if the item * of information has not been stored, and the supplied name is * used to identify the information within the error message. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The required keyword value, or AST__BAD if no value has previously * been stored for the keyword (or if an error has occurred). */ /* Local Variables: */ double ret; /* Returned keyword value */ int si; /* Integer co-ordinate version index */ /* Initialise */ ret = AST__BAD; /* Check the inherited status. */ if( !astOK ) return ret; /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "GetItem(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); /* Check the intermediate axis index is within range. */ } else if( i < 0 || i > 98 ) { astError( AST__INTER, "GetItem(fitschan): AST internal error; " "intermediate axis index %d is invalid.", status, i ); /* Check the pixel axis or parameter index is within range. */ } else if( jm < 0 || jm > 99 ) { astError( AST__INTER, "GetItem(fitschan): AST internal error; " "pixel axis or parameter index %d is invalid.", status, jm ); /* Otherwise, if the array holding the required keyword is not null, proceed... */ } else if( *item ){ /* Find the number of coordinate versions in the supplied array. Only proceed if it encompasses the requested co-ordinate version. */ if( astSizeOf( (void *) *item )/sizeof(double **) > si ){ /* Find the number of intermediate axes in the supplied array. Only proceed if it encompasses the requested intermediate axis. */ if( astSizeOf( (void *) (*item)[si] )/sizeof(double *) > i ){ /* Find the number of pixel axes or parameters in the supplied array. Only proceed if it encompasses the requested index. */ if( astSizeOf( (void *) (*item)[si][i] )/sizeof(double) > jm ){ /* Return the required keyword value. */ ret = (*item)[si][i][jm]; } } } } /* If required, report an error if the requested item of information has not been stored. */ if( ret == AST__BAD && name && astOK ){ astError( AST__NOFTS, "%s(%s): No value can be found for %s.", status, method, class, name ); } return ret; } static int GetMaxJM( double ****item, char s, int *status ){ /* * Name: * GetMaxJM * Purpose: * Return the largest pixel axis or parameter index stored for an * numerical axis keyword value in a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetMaxJM( double ****item, char s, int *status) * Class Membership: * FitsChan member function. * Description: * The number of pixel axis numbers or projection parameters stored for * a specified axis keyword is found and returned. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crpix) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (j) or projection parameter (m). * s * The co-ordinate version character (A to Z, or space), case * insensitive * status * Pointer to the inherited status variable. * Returned Value: * The maximum pixel axis number or projection parameter index (zero * based). */ /* Local Variables: */ int jm; /* Number of parameters/pixel axes */ int i; /* Intermediate axis index */ int ret; /* Returned axis index */ int si; /* Integer co-ordinate version index */ /* Initialise */ ret = -1; /* Check the inherited status. */ if( !astOK ) return ret; /* If the array holding the required keyword is not null, proceed... */ if( *item ){ /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "GetMaxJM(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); return ret; } /* Find the number of coordinate versions in the supplied array. Only proceed if it encompasses the requested co-ordinate version. */ if( astSizeOf( (void *) *item )/sizeof(double **) > si ){ /* Check that the pointer to the array of intermediate axis values is not null. */ if( (*item)[si] ){ /* Loop round each used element in this array. */ for( i = 0; i < astSizeOf( (void *) (*item)[si] )/sizeof(double *); i++ ){ if( (*item)[si][i] ){ /* Get the size of the pixel axis/projection parameter array for the current intermediate axis, and subtract 1 to get the largest index. */ jm = astSizeOf( (void *) (*item)[si][i] )/sizeof(double) - 1; /* Ignore any trailing unused (AST__BAD) values. */ while( jm >= 0 && (*item)[si][i][jm] == AST__BAD ) jm--; /* Update the returned value if the current value is larger. */ if( jm > ret ) ret = jm; } } } } } return ret; } static int GetMaxJMC( char *****item, char s, int *status ){ /* * Name: * GetMaxJMC * Purpose: * Return the largest pixel axis or parameter index stored for an * character-valued axis keyword value in a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetMaxJMC( char *****item, char s, int *status) * Class Membership: * FitsChan member function. * Description: * The number of pixel axis numbers or projection parameters stored for * a specified axis keyword is found and returned. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->ctype) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword string pointers. These arrays of keyword * string pointers have one element for every pixel axis (j) or * projection parameter (m). * s * The co-ordinate version character (A to Z, or space), case * insensitive * status * Pointer to the inherited status variable. * Returned Value: * The maximum pixel axis number or projection parameter index (zero * based). */ /* Local Variables: */ int jm; /* Number of parameters/pixel axes */ int i; /* Intermediate axis index */ int ret; /* Returned axis index */ int si; /* Integer co-ordinate version index */ /* Initialise */ ret = -1; /* Check the inherited status. */ if( !astOK ) return ret; /* If the array holding the required keyword is not null, proceed... */ if( *item ){ /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "GetMaxJMC(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); return ret; } /* Find the number of coordinate versions in the supplied array. Only proceed if it encompasses the requested co-ordinate version. */ if( astSizeOf( (void *) *item )/sizeof(char ***) > si ){ /* Check that the pointer to the array of intermediate axis values is not null. */ if( (*item)[si] ){ /* Loop round each used element in this array. */ for( i = 0; i < astSizeOf( (void *) (*item)[si] )/sizeof(char **); i++ ){ if( (*item)[si][i] ){ /* Get the size of the pixel axis/projection parameter array for the current intermediate axis, and subtract 1 to get the largest index. */ jm = astSizeOf( (void *) (*item)[si][i] )/sizeof(char *) - 1; /* Ignore any trailing unused (NULL) values. */ while( jm >= 0 && (*item)[si][i][jm] == NULL ) jm--; /* Update the returned value if the current value is larger. */ if( jm > ret ) ret = jm; } } } } } return ret; } static int GetMaxI( double ****item, char s, int *status ){ /* * Name: * GetMaxI * Purpose: * Return the largest WCS axis index stored for an axis keyword value in * a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetMaxJM( double ****item, char s) * Class Membership: * FitsChan member function. * Description: * The number of Wcs axis numbers stored for a specified axis keyword is * found and returned. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crval) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (j) or projection parameter (m). * s * The co-ordinate version character (A to Z, or space), case * insensitive * Returned Value: * The maximum WCS axis index (zero based). */ /* Local Variables: */ int ret; /* Returned axis index */ int si; /* Integer co-ordinate version index */ /* Initialise */ ret = -1; /* Check the inherited status. */ if( !astOK ) return ret; /* If the array holding the required keyword is not null, proceed... */ if( *item ){ /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "GetMaxI(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); return ret; } /* Find the number of coordinate versions in the supplied array. Only proceed if it encompasses the requested co-ordinate version. */ if( astSizeOf( (void *) *item )/sizeof(double **) > si ){ /* Check that the pointer to the array of intermediate axis values is not null. */ if( (*item)[si] ){ /* Get the size of the intermediate axis array and subtract 1 to get the largest index. */ ret = astSizeOf( (void *) (*item)[si] )/sizeof(double *) - 1; /* Ignore any trailing unused (NULL) values. */ while( ret >= 0 && (*item)[si][ret] == NULL ) ret--; } } } return ret; } static char GetMaxS( double ****item, int *status ){ /* * Name: * GetMaxS * Purpose: * Return the largest (i.e. closest to Z) coordinate version character * stored for a axis keyword value in a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char GetMaxS( double ****item, int *status) * Class Membership: * FitsChan member function. * Description: * The largest (i.e. closest to Z) coordinate version character * stored for a axis keyword value in a FitStore structure is found * and returned. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crval) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (j) or projection parameter (m). * status * Pointer to the inherited status variable. * Returned Value: * The highest coordinate version character. */ /* Local Variables: */ char ret; /* Returned axis index */ int si; /* Integer index into alphabet */ /* Initialise */ ret = ' '; /* Check the inherited status. */ if( !astOK ) return ret; /* If the array holding the required keyword is not null, proceed... */ if( *item ){ /* Find the length of this array, and subtract 1 to get the largest index in the array. */ si = astSizeOf( (void *) *item )/sizeof(double **) - 1; /* Ignore any trailing null (i.e. unused) values. */ while( si >= 0 && !(*item)[si] ) si--; /* Store the corresponding character */ if( si == 0 ) { ret = ' '; } else { ret = 'A' + si - 1; } } return ret; } static char *GetItemC( char *****item, int i, int jm, char s, char *name, const char *method, const char *class, int *status ){ /* * Name: * GetItemC * Purpose: * Retrieve a string value for a axis keyword value from a FitStore * structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *GetItemC( char *****item, int i, int jm, char s, char *name, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The requested keyword string value is retrieved from the specified * array, at a position indicated by the axis and co-ordinate version. * NULL is returned if the array does not contain the requested * value. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->ctype) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword string pointers. These arrays of keyword * string pointers have one element for every pixel axis (j) or * projection parameter (m). * i * The zero based intermediate axis index in the range 0 to 98. Set * this to zero for keywords (e.g. CRPIX) which are not indexed by * intermediate axis number. * jm * The zero based pixel axis index (in the range 0 to 98) or parameter * index (in the range 0 to WCSLIB__MXPAR-1). Set this to zero for * keywords (e.g. CTYPE) which are not indexed by either pixel axis or * parameter number. * s * The co-ordinate version character (A to Z, or space), case * insensitive * name * A string holding a name for the item of information. A NULL * pointer may be supplied, in which case it is ignored. If a * non-NULL pointer is supplied, an error is reported if the item * of information has not been stored, and the supplied name is * used to identify the information within the error message. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the required keyword string value, or NULL if no value * has previously been stored for the keyword (or if an error has * occurred). */ /* Local Variables: */ char *ret; /* Returned keyword value */ int si; /* Integer co-ordinate version index */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "GetItemC(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); /* Check the intermediate axis index is within range. */ } else if( i < 0 || i > 98 ) { astError( AST__INTER, "GetItemC(fitschan): AST internal error; " "intermediate axis index %d is invalid.", status, i ); /* Check the pixel axis or parameter index is within range. */ } else if( jm < 0 || jm > 99 ) { astError( AST__INTER, "GetItem(fitschan): AST internal error; " "pixel axis or parameter index %d is invalid.", status, jm ); /* Otherwise, if the array holding the required keyword is not null, proceed... */ } else if( *item ){ /* Find the number of coordinate versions in the supplied array. Only proceed if it encompasses the requested co-ordinate version. */ if( astSizeOf( (void *) *item )/sizeof(char ***) > si ){ /* Find the number of intermediate axes in the supplied array. Only proceed if it encompasses the requested intermediate axis. */ if( astSizeOf( (void *) (*item)[si] )/sizeof(char **) > i ){ /* Find the number of pixel axes or parameters in the supplied array. Only proceed if it encompasses the requested index. */ if( astSizeOf( (void *) (*item)[si][i] )/sizeof(char *) > jm ){ /* Return the required keyword value. */ ret = (*item)[si][i][jm]; } } } } /* If required, report an error if the requested item of information has not been stored. */ if( !ret && name && astOK ){ astError( AST__NOFTS, "%s(%s): No value can be found for %s.", status, method, class, name ); } return ret; } static AstFitsTable *GetNamedTable( AstFitsChan *this, const char *extname, int extver, int extlevel, int report, const char *method, int *status ){ /* * Name: * GetNamedTable * Purpose: * Return a FitsTable holding the contents of a named FITS binary table. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstFitsTable *GetNamedTable( AstFitsChan *this, const char *extname, * int extver, int extlevel, int report, * const char *method, int *status ) * Class Membership: * FitsChan member function. * Description: * If a table source function has been registered with FitsChan (using * astTableSource), invoke it to read the required table from the external * FITS file. If the extension is available in the FITS file, this will * put a FitsTable into the "tables" KeyMap in the FitsChan structure, * using the FITS extension name as the key - this will replace any * FitsTable already present in the KeyMap with the same key. Finally, * return a pointer to the FitsTable stored in the KeyMap - if any. * * This strategy allows the astPutTables or astPutTable method to be used * as an alternative to registering a table source function with the * FitsChan. Note, any table read using the source function is used * in preference to any table stored in the FitsChan by an earlier call * to astPutTables/astPutTable. * Parameters: * this * Pointer to the FitsChan. * extname * The key associated with the required table - should be the name * of the FITS extension containing the binary table. * extver * The FITS "EXTVER" value for the required table. * extlevel * The FITS "EXTLEVEL" value for the required table. * report * If non-zero, report an error if the named table is not available. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the FitsTable, or NULL if the table is not avalable. */ /* Local Variables: */ AstFitsTable *ret; /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Fitrst attempt to read the required table from the external FITS file. Only proceed if table source function and wrapper have been supplied using astTableSource. */ if( this->tabsource && this->tabsource_wrap ){ /* Invoke the table source function asking it to place the required FITS table in the FitsChan. This is an externally supplied function which may not be thread-safe, so lock a mutex first. Note, a cloned FitsChan pointer is sent to the table source function since the table source function will annul the supplied FitsChan pointer. Also store the channel data pointer in a global variable so that it can be accessed in the source function using macro astChannelData. */ astStoreChannelData( this ); LOCK_MUTEX2; ( *this->tabsource_wrap )( this->tabsource, astClone( this ), extname, extver, extlevel, status ); UNLOCK_MUTEX2; } /* Now get a pointer to the required FitsTable, stored as an entry in the "tables" KeyMap. Report an error if required. */ if( ! (this->tables) || !astMapGet0A( this->tables, extname, &ret ) ){ if( report && astOK ) { astError( AST__NOTAB, "%s(%s): Failed to read FITS binary table " "from extension '%s' (extver=%d, extlevel=%d).", status, method, astGetClass( this ), extname, extver, extlevel ); } } /* Return the result. */ return ret; } static AstKeyMap *GetTables( AstFitsChan *this, int *status ) { /* *++ * Name: c astGetTables f AST_GETTABLES * Purpose: * Retrieve any FitsTables currently in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c AstKeyMap *astGetTables( AstFitsChan *this ) f RESULT = AST_GETTABLES( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: * If the supplied FitsChan currently contains any tables, then this * function returns a pointer to a KeyMap. Each entry in the KeyMap * is a pointer to a FitsTable holding the data for a FITS binary * table. The key used to access each entry is the FITS extension * name in which the table should be stored. * * Tables can be present in a FitsChan as a result either of using the c astPutTable (or astPutTables) f AST_PUTTABLE (or AST_PUTTABLES) * method to store existing tables in the FitsChan, or of using the c astWrite f AST_WRITE * method to write a FrameSet to the FitsChan. For the later case, if * the FitsChan "TabOK" attribute is positive and the FrameSet requires * a look-up table to describe one or more axes, then the "-TAB" * algorithm code described in FITS-WCS paper III is used and the table * values are stored in the FitsChan in the form of a FitsTable object * (see the documentation for the "TabOK" attribute). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetTables() f AST_GETTABLES = INTEGER * A pointer to a deep copy of the KeyMap holding the tables currently * in the FitsChan, or c NULL f AST__NULL * if the FitsChan does not contain any tables. The returned * pointer should be annulled using c astAnnul f AST_ANNUL * when no longer needed. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ AstKeyMap *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the FitsChan contains any tables, return a pointer to a copy of the KeyMap containing them. Otherwise, return a NULL pointer. */ if( this->tables && astMapSize( this->tables ) > 0 ) { result = astCopy( this->tables ); } /* Return the result. */ return result; } static int GetUsedPolyTan( AstFitsChan *this, AstFitsChan *out, int latax, int lonax, char s, const char *method, const char *class, int *status ){ /* * Name: * GetUsedPolyTan * Purpose: * Get the value to use for the PolyTan attribute. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetUsedPolyTan( AstFitsChan *this, AstFitsChan *out, int latax, * int lonax, char s, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * If the PolyTan attribute is zero or positive, then its value is * returned. If it is negative, the supplied FitsChan is searched for * keywords of the form PVi_m. If any are found on the latitude axis, * or if any are found on the longitude axis with "m" > 4, +1 is * returned (meaning "use the distorted TAN conventio"). Otherwise 0 * is returned (meaning "use the standard TAN convention"). * * If all the PVi_m values for m > 0 on either axis are zero, a warning is * issued and zero is returned. * Parameters: * this * Pointer to the FitsChan. * out * Pointer to a secondary FitsChan. If the PV values in "this" are * found to be unusable, they will be marked as used in both "this" * and "out". * latax * The one-based index of the latitude axis within the FITS header. * lonax * The one-based index of the longitude axis within the FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * The attribute value to use. * Notes: * - A value of zero is returned if an error has already occurred * or if an error occurs for any reason within this function. */ /* Local Variables... */ char template[ 20 ]; double pval; int lbnd_lat; int lbnd_lon; int m; int nfound1; int nfound2; int ok; int ret; int ubnd_lat; int ubnd_lon; /* Check the global status. */ if( !astOK ) return 0; /* Get the value of the PolyTan attribute. */ ret = astGetPolyTan( this ); /* If it is negative, we examine the FitsChan to see which convention to use. */ if( ret < 0 ) { ret = 0; /* Search the FitsChan for latitude PV cards. */ if( s != ' ' ) { sprintf( template, "PV%d_%%d%c", latax, s ); } else { sprintf( template, "PV%d_%%d", latax ); } nfound1 = astKeyFields( this, template, 1, &ubnd_lat, &lbnd_lat ); /* Search the FitsChan for longitude PV cards. */ if( s != ' ' ) { sprintf( template, "PV%d_%%d%c", lonax, s ); } else { sprintf( template, "PV%d_%%d", lonax ); } nfound2 = astKeyFields( this, template, 1, &ubnd_lon, &lbnd_lon ); /* If any were found with "m" value greater than 4, assume the distorted TAN convention is in use. Otherwise assume the stdanrd TAN convention is in use. */ if( nfound1 || ( nfound2 && ubnd_lon > 4 ) ) ret = 1; /* If the distorted TAN convention is to be used, check that at least one of the PVi_m values is non-zero on each axis. We ignore the PVi_0 (constant) terms in this check. */ if( ret > 0 ) { /* Do the latitude axis first, skipping the first (constant) term. Assume that all latitude pV values are zero until we find one that is not. */ ok = 0; for( m = 1; m <= ubnd_lat && !ok; m++ ) { /* Form the PVi_m keyword name. */ if( s != ' ' ) { sprintf( template, "PV%d_%d%c", latax, m, s ); } else { sprintf( template, "PV%d_%d", latax, m ); } /* Get it's value. */ if( ! GetValue( this, template, AST__FLOAT, &pval, 0, 0, method, class, status ) ) { /* If the PVi_m header is not present in the FitsChan, use a default value. */ pval = ( m == 1 ) ? 1.0 : 0.0; } /* If the PVi_m header has a non-zero value, we can leave the loop. */ if( pval != 0.0 ) ok = 1; } /* If all the latitude PVi_m values are zero, issue a warning and return zero, indicating that a simple undistorted TAN projection should be used. */ if( !ok ) { Warn( this, "badpv", "This FITS header describes a distorted TAN " "projection, but all the distortion coefficients (the " "PVi_m headers) on the latitude axis are zero.", method, class, status ); ret = 0; /* Also, delete the PV keywords so that no attempt is made to use them. */ for( m = 1; m <= ubnd_lat; m++ ) { if( s != ' ' ) { sprintf( template, "PV%d_%d%c", latax, m, s ); } else { sprintf( template, "PV%d_%d", latax, m ); } astClearCard( this ); if( FindKeyCard( this, template, method, class, status ) ) { DeleteCard( this, method, class, status ); } } /* Otherwise, do the same check for the longitude axis. */ } else { ok = 0; for( m = 1; m <= ubnd_lon && !ok; m++ ) { if( s != ' ' ) { sprintf( template, "PV%d_%d%c", lonax, m, s ); } else { sprintf( template, "PV%d_%d", lonax, m ); } if( ! GetValue( this, template, AST__FLOAT, &pval, 0, 0, method, class, status ) ) { pval = ( m == 1 ) ? 1.0 : 0.0; } if( pval != 0.0 ) ok = 1; } if( !ok ) { Warn( this, "badpv", "This FITS header describes a distorted TAN " "projection, but all the distortion coefficients (the " "PVi_m headers) on the longitude axis are zero.", method, class, status ); ret = 0; for( m = 1; m <= ubnd_lon; m++ ) { if( s != ' ' ) { sprintf( template, "PV%d_%d%c", lonax, m, s ); } else { sprintf( template, "PV%d_%d", lonax, m ); } astClearCard( this ); if( FindKeyCard( this, template, method, class, status ) ) { DeleteCard( this, method, class, status ); } } } } } } /* Return the result. */ return astOK ? ret : 0; } static int GoodWarns( const char *value, int *status ){ /* * Name: * GoodWarns * Purpose: * Checks a string to ensure it is a legal list of warning conditions. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GoodWarns( const char *value, int *status ) * Class Membership: * FitsChan member function. * Description: * This function checks the supplied string to ensure it contains a space * separated list of zero or more recognised warning conditions. An * error is reported if it does not. * Parameters: * value * The string to check. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the supplied string is not a legal list of * conditions, or if an error has already occurred. One is returned * otherwise. */ /* Local Variables: */ char *b; /* Pointer to next buffer element */ const char *c ; /* Pointer to next character */ char buf[100]; /* Buffer for condition name */ int inword; /* Are we in a word? */ int n; /* Number of conditions supplied */ int ret; /* Returned value */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Report an error and return if the pointer is null. */ if( !value ){ astError( AST__ATTIN, "astSetWarnings(fitschan): Null pointer " "supplied for the Warnings attribute." , status); return ret; } /* Initialise things */ inword = 0; buf[ 0 ] = ' '; b = buf + 1; n = 0; ret = 1; /* Loop round each character in the supplied string. */ for( c = value ; c < value + strlen( value ) + 1; c++ ){ /* Have we found the first space or null following a word? */ if( ( !(*c) || isspace( *c ) ) && inword ){ /* Add a space to the end of the buffer and terminate it. */ *(b++) = ' '; *b = 0; /* Check the word is legal by searching for it in the string of all conditions, which should be lower case and have spaces at start and end. The word in the buffer is delimited by spaces and so it will not match a substring within a condition. If it is legal increment the number of conditions found. */ if( strstr( ALLWARNINGS, buf ) ){ n++; /* Otherwise, report an error and break. */ } else { ret = 0; *(--b) = 0; astError( AST__ATTIN, "astSetWarnings(fitschan): Unknown " "condition '%s' specified when setting the Warnings " "attribute.", status, buf + 1 ); break; } /* Reset the pointer to the next character in the buffer, retaining the initial space in the buffer. */ b = buf + 1; /* Indicate we are no longer in a word. */ inword = 0; /* Have we found the first non-space, non-null character following a space? */ } else if( *c && !isspace( *c ) && !inword ){ /* Note we are now in a word. */ inword = 1; } /* If we are in a word, copy the lowercase character to the buffer. */ if( inword ) *(b++) = tolower( *c ); } return ret; } static AstMapping *GrismSpecWcs( char *algcode, FitsStore *store, int i, char s, AstSpecFrame *specfrm, const char *method, const char *class, int *status ) { /* * Name: * GrismSpecWcs * Purpose: * Create a Mapping describing a FITS-WCS grism-dispersion algorithm * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *GrismSpecWcs( char *algcode, FitsStore *store, int i, char s, * AstSpecFrame *specfrm, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function uses the contents of the supplied FitsStore to create * a Mapping which goes from Intermediate World Coordinate (known as "w" * in the context of FITS-WCS paper III) to the spectral system * described by the supplied SpecFrame. * * The returned Mapping implements the grism "GRA" and "GRI" algorithms * described in FITS-WCS paper III. * Parameters: * algcode * Pointer to a string holding the code for the required algorithm * ("-GRA" or "-GRI"). * store * Pointer to the FitsStore structure holding the values to use for * the WCS keywords. * i * The zero-based index of the spectral axis within the FITS header * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * specfrm * Pointer to the SpecFrame. This specifies the "S" system - the * system in which the CRVAL kewyords (etc) are specified. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a Mapping, or NULL if an error occurs. */ /* Local Variables: */ AstFrameSet *fs; AstMapping *gmap; AstMapping *map1; AstMapping *map2; AstMapping *map2a; AstMapping *map2b; AstMapping *ret; AstMapping *smap; AstSpecFrame *wfrm; double crv; double dg; double gcrv; double pv; double wcrv; /* Check the global status. */ ret = NULL; if( !astOK ) return ret; /* The returned Mapping will be a CmpMap including a GrismMap. This GrismMap will produced wavelength as output. We also need the Mapping from wavelength to the system represented by the supplied SpecFrame. To get this, we first create a copy of the supplied SpecFrame (in order to inherit the standard of rest, epoch, etc), and set its System to wavlength in vacuum (for "-GRI") or air (for "-GRA"), and then use astConvert to get the Mapping from the SpecFrame system to relevant form of wavelength. */ wfrm = astCopy( specfrm ); astSetSystem( wfrm, strcmp( algcode, "-GRI" )?AST__AIRWAVE:AST__WAVELEN ); astSetUnit( wfrm, 0, "m" ); fs = astConvert( specfrm, wfrm, "" ); if( fs ) { smap = astGetMapping( fs, AST__BASE, AST__CURRENT ); fs = astAnnul( fs ); /* Get the CRVAL value for the spectral axis (this will be in the S system). */ crv = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( crv == AST__BAD ) crv = 0.0; /* Convert it to the wavelength system (vacuum or air) in metres. */ astTran1( smap, 1, &crv, 1, &wcrv ); /* Create a GrismMap, and then use the projection parameters stored in the FitsStore to set its attributes (convert degrees values to radians and supply the defaults specified in FITS-WCS paper III). The FITS paper specifies units in which these parameters should be stored in a FITS header - distances are in metres and angles in degrees. */ gmap = (AstMapping *) astGrismMap( "", status ); pv = GetItem( &(store->pv), i, 0, s, NULL, method, class, status ); astSetGrismG( gmap, ( pv != AST__BAD )?pv:0.0 ); pv = GetItem( &(store->pv), i, 1, s, NULL, method, class, status ); astSetGrismM( gmap, ( pv != AST__BAD )?(int) ( pv + 0.5 ):0); pv = GetItem( &(store->pv), i, 2, s, NULL, method, class, status ); astSetGrismAlpha( gmap, ( pv != AST__BAD )?pv*AST__DD2R:0.0 ); pv = GetItem( &(store->pv), i, 3, s, NULL, method, class, status ); astSetGrismNR( gmap, ( pv != AST__BAD )?pv:1.0 ); pv = GetItem( &(store->pv), i, 4, s, NULL, method, class, status ); astSetGrismNRP( gmap, ( pv != AST__BAD )?pv:0.0 ); pv = GetItem( &(store->pv), i, 5, s, NULL, method, class, status ); astSetGrismEps( gmap, ( pv != AST__BAD )?pv*AST__DD2R:0.0 ); pv = GetItem( &(store->pv), i, 6, s, NULL, method, class, status ); astSetGrismTheta( gmap, ( pv != AST__BAD )?pv*AST__DD2R:0.0 ); /* Store the reference wavelength found above as an attribute of the GrismMap. */ astSetGrismWaveR( gmap, wcrv ); /* Invert the GrismMap to get the (Wavelength -> grism parameter) Mapping, and then combine it with the (S -> Wavelength) Mapping to get the (S -> grism parameter) Mapping. */ astInvert( gmap ); map1 = (AstMapping *) astCmpMap( smap, gmap, 1, "", status ); /* Convert the reference point value from wavelength to grism parameter. */ astTran1( gmap, 1, &wcrv, 1, &gcrv ); /* Find the rate of change of grism parameter with respect to the S system at the reference point, dg/dS. */ dg = astRate( map1, &crv, 0, 0 ); if( dg != AST__BAD && dg != 0.0 ) { /* FITS-WCS paper II requires headers to be constructed so that dS/dw = 1.0 at the reference point. Therefore dg/dw = dg/dS. Create a WinMap which scales and shifts the "w" value to get the grism parameter value. */ map2a = (AstMapping *) astZoomMap( 1, dg, "", status ); map2b = (AstMapping *) astShiftMap( 1, &gcrv, "", status ); map2 = (AstMapping *) astCmpMap( map2a, map2b, 1, "", status ); map2a = astAnnul( map2a ); map2b = astAnnul( map2b ); /* The Mapping to be returned is the concatenation of the above Mapping (from w to g) with the Mapping from g to S. */ astInvert( map1 ); ret = (AstMapping *) astCmpMap( map2, map1, 1, "", status ); map2 = astAnnul( map2 ); } map1 = astAnnul( map1 ); smap = astAnnul( smap ); gmap = astAnnul( gmap ); } wfrm = astAnnul( wfrm ); /* Return the result */ return ret; } static int KeyFields( AstFitsChan *this, const char *filter, int maxfld, int *ubnd, int *lbnd, int *status ){ /* *+ * Name: * astKeyFields * Purpose: * Find the ranges taken by integer fields within the keyword names * in a FitsChan. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astKeyFields( AstFitsChan *this, const char *filter, int maxfld, * int *ubnd, int *lbnd ) * Class Membership: * FitsChan method. * Description: * This function returns the number of cards within a FitsChan which * refer to keywords which match the supplied filter template. If the * filter contains any integer field specifiers (e.g. "%d", "%3d", etc), * it also returns the upper and lower bounds found for the integer * fields. * Parameters: * this * Pointer to the FitsChan. * filter * The filter string. * maxfld * The size of the "ubnd" and "lbnd" arrays. * ubnd * A pointer to an integer array in which to return the * upper bound found for each integer field in the filter. * They are stored in the order in which they occur in the filter. * If the filter contains too many fields to fit in the supplied * array, the excess trailing fields are ignored. * lbnd * A pointer to an integer array in which to return the * lower bound found for each integer field in the filter. * Returned Value: * astKeyFields() * The total number of cards matching the supplied filter in the * FitsChan. * Filter Syntax: * - The criteria for a keyword name to match a filter template are * as follows: * - All characters in the template other than "%" (and the field width * and type specifiers which follow a "%") must be matched by an * identical character in the test string. - If a "%" occurs in the template, then the next character in the * template should be a single digit specifying a field width. If it is * zero, then the test string may contain zero or more matching characters. * Otherwise, the test string must contain exactly the specified number * of matching characters (i.e. 1 to 9). The field width digit may be * omitted, in which case the test string must contain one or more matching * characters. The next character in the template specifies the type of * matching characters and must be one of "d", "c" or "f". Decimal digits * are matched by "d", all upper (but not lower) case alphabetical * characters are matched by "c", and all characters which may legally be * found within a FITS keyword name are matched by "f". * Examples: * - The filter "CRVAL1" accepts the single keyword CRVAL1. * - The filter "CRVAL%1d" accepts the single keyword CRVAL0, CRVAL1, * CRVAL2, up to CRVAL9. * - The filter "CRVAL%d" accepts any keyword consisting of the string * "CRVAL" followed by any integer value. * - The filter "CR%0s1" accepts any keyword starting with the string "CR" * and ending with the character "1" (including CR1). * Notes: * - The entire FitsChan is searched, irrespective of the setting of * the Card attribute. * - If "maxfld" is supplied as zero, "ubnd" and "lbnd" are ignored, * but the number of matching cards is still returned as the function value. * - If no matching cards are found in the FitsChan, or if there are no * integer fields in the filter, then the lower and upper bounds are * returned as zero and -1 (i.e. reversed). * - If an error has already occured, or if this function should fail * for any reason, a value of zero is returned for the function value, * and the lower and upper bounds are set to zero and -1. *- */ /* Local Variables: */ const char *class; /* Object class */ const char *method; /* Method name */ int *fields; /* Pointer to array of field values */ int i; /* Field index */ int icard; /* Index of current card on entry */ int nmatch; /* No. of matching cards */ int nf; /* No. of integer fields in the filter */ int nfld; /* No. of integer fields in current keyword name */ /* Initialise the returned values. */ nmatch = 0; for( i = 0; i < maxfld; i++ ){ lbnd[ i ] = 0; ubnd[ i ] = -1; } nf = 0; /* Check the global error status. */ if ( !astOK || !filter ) return nf; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the method name and object class for use in error messages. */ method = "astKeyFields"; class = astGetClass( this ); /* Count the number of integer fields in the filter string. */ nf = CountFields( filter, 'd', method, class, status ); /* If this is larger than the supplied arrays, use the size of the arrays instead. */ if( nf > maxfld ) nf = maxfld; /* Allocate memory to hold the integer field values extracted from each matching keyword. */ fields = (int *) astMalloc( sizeof( int )*(size_t) nf ); /* Save the current card index, and rewind the FitsChan. */ icard = astGetCard( this ); astClearCard( this ); /* Check that the FitsChan is not empty and the pointer can be used. */ if( !astFitsEof( this ) && astOK ){ /* Initialise the returned bounds. Any excess elements in the array are left at the previously initialised values. */ for( i = 0; i < nf; i++ ){ lbnd[ i ] = INT_MAX; ubnd[ i ] = -INT_MAX; } /* Initialise the number of matching keywords. */ nmatch = 0; /* Loop round all the cards in the FitsChan. */ while( !astFitsEof( this ) && astOK ){ /* If the current keyword name matches the filter, update the returned bounds and increment the number of matches. */ if( Match( CardName( this, status ), filter, nf, fields, &nfld, method, class, status ) ){ for( i = 0; i < nf; i++ ){ if( fields[ i ] > ubnd[ i ] ) ubnd[ i ] = fields[ i ]; if( fields[ i ] < lbnd[ i ] ) lbnd[ i ] = fields[ i ]; } nmatch++; } /* Move on to the next card. */ MoveCard( this, 1, method, class, status ); } /* If bounds were not found, returned 0 and -1. */ for( i = 0; i < nf; i++ ){ if( lbnd[ i ] == INT_MAX ){ lbnd[ i ] = 0; ubnd[ i ] = -1; } } } /* Reinstate the original current card index. */ astSetCard( this, icard ); /* Free the memory used to hold the integer field values extracted from each matching keyword. */ fields = (int *) astFree( (void *) fields ); /* If an error has occurred, returned no matches and reversed bounds. */ if( !astOK ){ nmatch = 0; for( i = 0; i < maxfld; i++ ){ lbnd[ i ] = 0; ubnd[ i ] = -1; } } /* Returned the answer. */ return nmatch; } static int FindFits( AstFitsChan *this, const char *name, char card[ AST__FITSCHAN_FITSCARDLEN + 1 ], int inc, int *status ){ /* *++ * Name: c astFindFits f AST_FINDFITS * Purpose: * Find a FITS card in a FitsChan by keyword. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c int astFindFits( AstFitsChan *this, const char *name, char card[ 81 ], c int inc ) f RESULT = AST_FINDFITS( THIS, NAME, CARD, INC, STATUS ) * Class Membership: * FitsChan member function. * Description: * This function searches for a card in a FitsChan by keyword. The * search commences at the current card (identified by the Card * attribute) and ends when a card is found whose FITS keyword * matches the template supplied, or when the last card in the * FitsChan has been searched. * * If the search is successful (i.e. a card is found which matches c the template), the contents of the card are (optionally) f the template), the contents of the card are * returned and the Card attribute is adjusted to identify the card * found or, if required, the one following it. If the search is c not successful, the function returns zero and the Card attribute f not successful, the function returns .FALSE. and the Card attribute * is set to the "end-of-file". * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c name f NAME = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string containing a f A character string containing a * template for the keyword to be found. In the simplest case, * this should simply be the keyword name (the search is case * insensitive and trailing spaces are ignored). However, this * template may also contain "field specifiers" which are * capable of matching a range of characters (see the "Keyword * Templates" section for details). In this case, the first card * with a keyword which matches the template will be found. To * find the next FITS card regardless of its keyword, you should * use the template "%f". c card f CARD = CHARACTER * ( 80 ) (Returned) c An array of at least 81 characters (to allow room for a c terminating null) f A character variable with at least 80 characters * in which the FITS card which is found will be returned. If c the search is not successful (or a NULL pointer is given), a f the search is not successful, a * card will not be returned. c inc f INC = LOGICAL (Given) c If this value is zero (and the search is successful), the f If this value is .FALSE. (and the search is successful), the * FitsChan's Card attribute will be set to the index of the card c that was found. If it is non-zero, however, the Card f that was found. If it is .TRUE., however, the Card * attribute will be incremented to identify the card which * follows the one found. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astFindFits() f AST_FINDFITS = LOGICAL c One if the search was successful, otherwise zero. f .TRUE. if the search was successful, otherwise .FALSE.. * Notes: * - The search always starts with the current card, as identified * by the Card attribute. To ensure you search the entire contents * of a FitsChan, you should first clear the Card attribute (using c astClear). This effectively "rewinds" the FitsChan. f AST_CLEAR). This effectively "rewinds" the FitsChan. * - If a search is unsuccessful, the Card attribute is set to the * "end-of-file" (i.e. to one more than the number of cards in the * FitsChan). No error occurs. c - A value of zero will be returned if this function is invoked f - A value of .FALSE. will be returned if this function is invoked * with the AST error status set, or if it should fail for any * reason. * Examples: c result = astFindFits( fitschan, "%f", card, 1 ); f RESULT = AST_FINDFITS( FITSCHAN, '%f', CARD, .TRUE., STATUS ) * Returns the current card in a FitsChan and advances the Card * attribute to identify the card that follows (the "%f" * template matches any keyword). c result = astFindFits( fitschan, "BITPIX", card, 1 ); f RESULT = AST_FINDFITS( FITSCHAN, 'BITPIX', CARD, .TRUE., STATUS ) * Searches a FitsChan for a FITS card with the "BITPIX" keyword * and returns that card. The Card attribute is then incremented * to identify the card that follows it. c result = astFindFits( fitschan, "COMMENT", NULL, 0 ); f RESULT = AST_FINDFITS( FITSCHAN, 'COMMENT', CARD, .FALSE., STATUS ) * Sets the Card attribute of a FitsChan to identify the next c COMMENT card (if any). The card itself is not returned. f COMMENT card (if any) and returns that card. c result = astFindFits( fitschan, "CRVAL%1d", card, 1 ); f RESULT = AST_FINDFITS( FITSCHAN, 'CRVAL%1d', CARD, .TRUE., STATUS ) * Searches a FitsChan for the next card with a keyword of the * form "CRVALi" (for example, any of the keywords "CRVAL1", * "CRVAL2" or "CRVAL3" would be matched). The card found (if * any) is returned, and the Card attribute is then incremented * to identify the following card (ready to search for another * keyword with the same form, perhaps). * Keyword Templates: * The templates used to match FITS keywords are normally composed * of literal characters, which must match the keyword exactly * (apart from case). However, a template may also contain "field * specifiers" which can match a range of possible characters. This * allows you to search for keywords that contain (for example) * numbers, where the digits comprising the number are not known in * advance. * * A field specifier starts with a "%" character. This is followed * by an optional single digit (0 to 9) specifying a field * width. Finally, there is a single character which specifies the * type of character to be matched, as follows: * * - "c": matches all upper case letters, * - "d": matches all decimal digits, * - "f": matches all characters which are permitted within a FITS * keyword (upper case letters, digits, underscores and hyphens). * * If the field width is omitted, the field specifier matches one * or more characters. If the field width is zero, it matches zero * or more characters. Otherwise, it matches exactly the number of * characters specified. In addition to this: * * - The template "%f" will match a blank FITS keyword consisting * of 8 spaces (as well as matching all other keywords). * - A template consisting of 8 spaces will match a blank keyword * (only). * * For example: * * - The template "BitPix" will match the keyword "BITPIX" only. * - The template "crpix%1d" will match keywords consisting of * "CRPIX" followed by one decimal digit. * - The template "P%c" will match any keyword starting with "P" * and followed by one or more letters. * - The template "E%0f" will match any keyword beginning with "E". * - The template "%f" will match any keyword at all (including a * blank one). *-- */ /* Local Variables: */ char *c; /* Pointer to next character to check */ char *lname; /* Pointer to copy of name without trailing spaces */ const char *class; /* Object class */ const char *method; /* Calling method */ int ret; /* Was a card found? */ /* Check the global status, and supplied keyword name. */ if( !astOK ) return 0; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the calling method and object class. */ method = "astFindFits"; class = astGetClass( this ); /* Get a local copy of the keyword template. */ lname = (char *) astStore( NULL, (void *) name, strlen(name) + 1 ); /* Terminate it to exclude trailing spaces. */ c = lname + strlen(lname) - 1; while( *c == ' ' && c >= lname ) *(c--) = 0; /* Use the private FindKeyCard function to find the card and make it the current card. Always use the supplied current card (if any) if the template is "%f" or "%0f". */ if ( !strcmp( lname, "%f" ) || !strcmp( lname, "%0f" ) ){ ret = astFitsEof( this ) ? 0 : 1; } else { ret = FindKeyCard( this, lname, method, class, status ); } /* Only proceed if the card was found. */ if( ret && astOK ){ /* Format the current card if a destination string was supplied. */ if( card ) FormatCard( this, card, method, status ); /* Increment the current card pointer if required. */ if( inc ) MoveCard( this, 1, method, class, status ); /* Indicate that a card has been formatted. */ ret = 1; } /* Free the memory holding the local copy of the keyword template. */ lname = (char *) astFree( (void *) lname ); /* If an errror has occurred, return zero. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static int FindKeyCard( AstFitsChan *this, const char *name, const char *method, const char *class, int *status ){ /* * Name: * FindKeyCard * Purpose: * Find the next card refering to given keyword. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FindKeyCard( AstFitsChan *this, const char *name, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Finds the next card which refers to the supplied keyword and makes * it the current card. The search starts with the current card and ends * when it reaches the last card. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a string holding the keyword template (using the * syntax expected by the Match function). * method * Pointer to string holding name of calling method. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if a card was found refering to the given * keyword. Otherwise zero is returned. * Notes: * - If a NULL pointer is supplied for "name" then the current card * is left unchanged. * - The current card is set to NULL (end-of-file) if no card can be * found for the supplied keyword. */ /* Local Variables: */ int nfld; /* Number of fields in keyword template */ int ret; /* Was a card found? */ /* Check the global status, and supplied keyword name. */ if( !astOK || !name ) return 0; /* Indicate that no card has been found yet. */ ret = 0; /* Search forward through the list until all cards have been checked. */ while( !astFitsEof( this ) && astOK ){ /* Break out of the loop if the keyword name from the current card matches the supplied keyword name. */ if( Match( CardName( this, status ), name, 0, NULL, &nfld, method, class, status ) ){ ret = 1; break; /* Otherwise, move the current card on to the next card. */ } else { MoveCard( this, 1, method, class, status ); } } /* Return. */ return ret; } static double *FitLine( AstMapping *map, double *g, double *g0, double *w0, double dim, double *tol, int *status ){ /* * Name: * FitLine * Purpose: * Check a Mapping for linearity. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double *FitLine( AstMapping *map, double *g, double *g0, double *w0, * double dim, double *tol, int *status ) * Class Membership: * FitsChan member function. * Description: * This function applies the supplied Mapping to a set of points along * a straight line in the input space. It checks to see if the transformed * positions also lie on a straight line (in the output space). If so, * it returns the vector along this line in the output space which * corresponds to a unit vector along the line in the input space. If * not, a NULL pointer is returned. * * The returned vector is found by doing a least squares fit. * Parameters: * map * A pointer to the Mapping to test. The number of outputs must be * greater than or equal to the number of inputs. * g * A pointer to an array holding a unit vector within the input space * defining the straight line to be checked. The number of elements * within this array should equal the number of inputs for "map". * g0 * A pointer to an array holding a position within the input space * giving the central position of the vector "g". The number of elements * within this array should equal the number of inputs for "map". * w0 * A pointer to an array holding a vector within the output space * which corresponds to "g0". The number of elements within this array * should equal the number of outputs for "map". * dim * The length of the pixel axis, or AST__BAD if unknown. * tol * Pointer to an array holding the tolerance for equality on each * output axis. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to dynamically allocated memory holding the required vector * in the output space. The number of elements in this vector will equal * the number of outputs for "map". The memory should be freed using * astFree when no longer needed. If the Mapping is not linear, NULL * is returned. * Notes: * - NULL is returned if an error occurs. */ /* Local Constants: */ #define NPO2 50 #define NP (2*NPO2+1) /* Local Variables: */ AstPointSet *pset1; AstPointSet *pset2; double **ptr1; double **ptr2; double *offset; double *pax; double *ret; double *voffset; double dax; double denom; double gap; double sd2; double sd; double sdw; double sw; double wmax; double wmin; int i; int j; int n; int nin; int nout; int ok; /* Initialise */ ret = NULL; /* Check the inherited status and supplied axis size. */ if( !astOK || dim == 0.0 ) return ret; /* Get the number of inputs and outputs for the Mapping. Return if the number of outputs is smaller than the number of inputs. */ nin = astGetNin( map ); nout = astGetNout( map ); if( nout < nin ) return ret; /* Check the supplied position is good on all axes. */ for( j = 0; j < nout; j++ ) { if( w0[ j ] == AST__BAD ) return ret; } /* We use NP points in the fit. If a value for "dim" has been supplied, we use points evenly distributed over the whole axis. If not, we use a gap of 1.0 (corresponds to an axis length of 100 pixels). Choose the gap. */ gap = ( dim != AST__BAD ) ? dim/NP : 1.0; /* Create PointSets to hold the input and output positions. */ pset1 = astPointSet( NP, nin, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( NP, nout, "", status ); ptr2 = astGetPoints( pset2 ); /* Allocate the returned array. */ ret = astMalloc( sizeof( double )*(size_t) nout ); /* Allocate workspace to hold the constant offsets of the fit. */ offset = astMalloc( sizeof( double )*(size_t) nout ); voffset = astMalloc( sizeof( double )*(size_t) nout ); /* Indicate we have not yet got a usable returned vector. */ ok = 0; /* Check we can use the pointers safely. */ if( astOK ) { /* Set up the input positions: NP evenly spaced points along a line with unit direction vector given by "g", centred at position given by "g0". */ for( j = 0; j < nin; j++ ) { pax = ptr1[ j ]; dax = g[ j ]*gap; for( i = -NPO2; i <= NPO2; i++ ) *(pax++) = g0[ j ] + dax*i; } /* Transform these positions into the output space. */ (void) astTransform( map, pset1, 1, pset2 ); /* Loop over all output axes, finding the component of the returned vector. */ ok = 1; for( j = 0; j < nout; j++ ) { pax = ptr2[ j ]; /* Now loop over all the transformed points to form the other required sums. We also form the sums needed to estimate the variance in the calculated offset. */ sdw = 0.0; sw = 0.0; sd = 0.0; sd2 = 0.0; n = 0; wmax = -DBL_MAX; wmin = DBL_MAX; for( i = -NPO2; i <= NPO2; i++, pax++ ) { if( *pax != AST__BAD ) { /* Increment the required sums. */ sdw += i*(*pax); sw += (*pax); sd += i; sd2 += i*i; n++; if( *pax > wmax ) wmax = *pax; if( *pax < wmin ) wmin = *pax; } } /* If a reasonable number of good points were found, find the component of the returned vector (excluding a scale factor of 1/gap). */ denom = sd2*n - sd*sd; if( n > NP/4 && denom != 0.0 ) { /* Find the constant scale factor to return for this axis. If the axis value is constant, return zero. */ if( wmax > wmin ) { ret[ j ] = (sdw*n - sw*sd)/denom; } else { ret[ j ] = 0.0; } /* Now find the constant offset for this axis. */ offset[ j ] = (sw*sd2 - sdw*sd)/denom; } else { ok = 0; break; } } /* Now check that the fit is good enough. Each axis is checked separately. All axes must be good. */ if( ok ) { for( j = 0; j < nout; j++ ) { /* Store the axis values implied by the linear fit in the now un-needed ptr1[0] array. */ pax = ptr1[ 0 ]; for( i = -NPO2; i <= NPO2; i++, pax++ ) { *pax = i*ret[ j ] + offset[ j ]; } /* Test the fit to see if we beleive that the mapping is linear. If it is, scale the returned value from units of "per gap" to units of "per pixel". Otherwise,indicate that he returned vector is unusable. */ if( FitOK( NP, ptr2[ j ], ptr1[ 0 ], tol[ j ], status ) ) { ret[ j ] /= gap; } else { ok = 0; break; } } } } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free memory. */ offset = astFree( offset ); voffset = astFree( voffset ); /* If an error has occurred, or if the returned vector is unusable, free any returned memory */ if( !astOK || !ok ) ret = astFree( ret ); /* Return the answer. */ return ret; /* Undefine local constants: */ #undef NP #undef NPO2 } static int FitsEof( AstFitsChan *this, int *status ){ /* *+ * Name: * astFitsEof * Purpose: * See if the FitsChan is at "end-of-file". * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astFitsEof( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * A value of zero is returned if any more cards remain to be read from the * FitsChan. Otherwise a value of 1 is returned. Thus, it is * equivalent to testing the FitsChan for an "end-of-file" condition. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * One if no more cards remain to be read, otherwise zero. * Notes: * - This function attempts to execute even if an error has already * occurred. *- */ /* Check the supplied object. */ if( !this ) return 1; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* If no more cards remain to be read, the current card pointer in the FitsChan will be NULL. Return an appropriate integer value. */ return this->card ? 0 : 1; } static int FitsSof( AstFitsChan *this, int *status ){ /* *+ * Name: * FitsSof * Purpose: * See if the FitsChan is at "start-of-file". * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FitsSof( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * A value of 1 is returned if the current card is the first card in * the FitsChan. Otherwise a value of zero is returned. This function * is much more efficient than "astGetCard(this) <= 1" . * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the current card is the first card. * Notes: * - This function attempts to execute even if an error has already * occurred. * - A non-zero value is returned if the FitsChan is empty. *- */ /* Return if no FitsChan was supplied, or if the FitsChan is empty. */ if ( !this || !this->head ) return 1; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* If the current card is at the head of the linked list, it is the first card. */ return this->card == this->head; } /* *++ * Name: c astGetFits f AST_GETFITS * Purpose: * Get a named keyword value from a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c int astGetFits( AstFitsChan *this, const char *name, type *value ) f RESULT = AST_GETFITS( THIS, NAME, VALUE, STATUS ) * Class Membership: * FitsChan method. * Description: * This is a family of functions which gets a value for a named keyword, * or the value of the current card, from a FitsChan using one of several * different data types. The data type of the returned value is selected * by replacing in the function name by one of the following strings * representing the recognised FITS data types: * * - CF - Complex floating point values. * - CI - Complex integer values. * - F - Floating point values. * - I - Integer values. * - L - Logical (i.e. boolean) values. * - S - String values. * - CN - A "CONTINUE" value, these are treated like string values, but * are encoded without an equals sign. * * The data type of the "value" c parameter f argument * depends on as follows: * c - CF - "double *" (a pointer to a 2 element array to hold the real and c imaginary parts of the complex value). c - CI - "int *" (a pointer to a 2 element array to hold the real and c imaginary parts of the complex value). c - F - "double *". c - I - "int *". c - L - "int *". c - S - "char **" (a pointer to a static "char" array is returned at the c location given by the "value" parameter, Note, the stored string c may change on subsequent invocations of astGetFitsS so a c permanent copy should be taken of the string if necessary). c - CN - Like"S". f - CF - DOUBLE PRECISION(2) (a 2 element array to hold the real and f imaginary parts of the complex value). f - CI - INTEGER(2) (a 2 element array to hold the real and imaginary f parts of the complex value). f - F - DOUBLE PRECISION. f - I - INTEGER f - L - LOGICAL f - S - CHARACTER f - CN - CHARACTER * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c name f NAME = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string f A character string * containing the FITS keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. If c NULL f a single dot '.' * is supplied, the value of the current card is returned. c value f VALUE = type (Returned) c A pointer to a f A * buffer to receive the keyword value. The data type depends on * as described above. The conents of the buffer on entry are left * unchanged if the keyword is not found. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetFits() f AST_GETFITS = LOGICAL c A value of zero f .FALSE. * is returned if the keyword was not found in the FitsChan (no error * is reported). Otherwise, a value of c one f .TRUE. * is returned. * Notes: * - If a name is supplied, the card following the current card is * checked first. If this is not the required card, then the rest of the * FitsChan is searched, starting with the first card added to the * FitsChan. Therefore cards should be accessed in the order they are * stored in the FitsChan (if possible) as this will minimise the time * spent searching for cards. * - If the requested card is found, it becomes the current card, * otherwise the current card is left pointing at the "end-of-file". * - If the stored keyword value is not of the requested type, it is * converted into the requested type. * - If the keyword is found in the FitsChan, but has no associated * value, an error is reported. If necessary, the c astTestFits f AST_TESTFITS * function can be used to determine if the keyword has a defined * value in the FitsChan prior to calling this function. * - An error will be reported if the keyword name does not conform * to FITS requirements. c - Zero * - .FALSE. * is returned as the function value if an error has already occurred, * or if this function should fail for any reason. * - The FITS standard says that string keyword values should be * padded with trailing spaces if they are shorter than 8 characters. * For this reason, trailing spaces are removed from the string * returned by c astGetFitsS f AST_GETFITSS * if the original string (including any trailing spaces) contains 8 * or fewer characters. Trailing spaces are not removed from longer * strings. *-- */ /* Define a macro which expands to the implementation of the astGetFits routine for a given data type. */ #define MAKE_FGET(code,ctype,ftype) \ static int GetFits##code( AstFitsChan *this, const char *name, ctype value, int *status ){ \ \ /* Local Variables: */ \ const char *class; /* Object class */ \ const char *method; /* Calling method */ \ char *lcom; /* Supplied keyword comment */ \ char *lname; /* Supplied keyword name */ \ char *lvalue; /* Supplied keyword value */ \ char *string; /* Pointer to returned string value */ \ char *c; /* Pointer to next character */ \ int cl; /* Length of string value */ \ int ret; /* The returned value */ \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Ensure the source function has been called */ \ ReadFromSource( this, status ); \ \ /* Store the calling method and object class. */ \ method = "astGetFits"#code; \ class = astGetClass( this ); \ \ /* Initialise the returned value. */ \ ret = 0; \ \ /* Extract the keyword name from the supplied string. */ \ if( name ) { \ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); \ } else { \ lname = NULL; \ lvalue = NULL; \ lcom = NULL; \ } \ \ /* Attempt to find a card in the FitsChan refering to this keyword, \ and make it the current card. Only proceed if a card was found. No \ need to do the search if the value of the current card is required. */ \ if( !lname || SearchCard( this, lname, method, class, status ) ){ \ \ /* Convert the stored data value to the requested type, and store it in \ the supplied buffer. */ \ if( !CnvValue( this, ftype, 0, value, method, status ) && astOK ) { \ astError( AST__FTCNV, "%s(%s): Cannot convert FITS keyword " \ "'%s' to %s.", status, method, class, \ CardName( this, status ), type_names[ ftype ] ); \ } \ \ /* If the returned value is a string containing 8 or fewer characters, \ replace trailing spaces with null characters. */ \ if( astOK ) { \ if( ftype == AST__STRING ) { \ string = *( (char **) value ); \ if( string ) { \ cl =strlen( string ); \ if( cl <= 8 ) { \ c = string + cl - 1; \ while( *c == ' ' && c > string ) { \ *c = 0; \ c--; \ } \ } \ } \ } \ \ /* Indicate that a value is available. */ \ ret = 1; \ } \ \ } \ \ /* Context error message. */ \ if( !astOK && lname && *lname ) { \ astError( astStatus, "%s(%s): Cannot get value for FITS keyword " \ "'%s'.", status, method, class, lname ); \ } \ \ /* Release the memory used to hold keyword name, value and comment strings. */ \ lname = (char *) astFree( (void *) lname ); \ lvalue = (char *) astFree( (void *) lvalue ); \ lcom = (char *) astFree( (void *) lcom ); \ \ /* Return the answer. */ \ return ret; \ \ } /* Use the above macro to give defintions for the astGetFits method for each FITS data type. */ MAKE_FGET(CF,double *,AST__COMPLEXF) MAKE_FGET(CI,int *,AST__COMPLEXI) MAKE_FGET(F,double *,AST__FLOAT) MAKE_FGET(I,int *,AST__INT) MAKE_FGET(L,int *,AST__LOGICAL) MAKE_FGET(S,char **,AST__STRING) MAKE_FGET(CN,char **,AST__CONTINUE) #undef MAKE_FGET static int FitsGetCom( AstFitsChan *this, const char *name, char **comment, int *status ){ /* *+ * Name: * astFitsGetCom * Purpose: * Get a keyword comment from a FitsChan. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astFitsGetCom( AstFitsChan *this, const char *name, * char **comment ) * Class Membership: * FitsChan method. * Description: * This function gets the comment associated with the next occurrence of * a named keyword in a FitsChan. * Parameters: * this * Pointer to the FitsChan. * name * A pointer to a * string holding the keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. * comment * A pointer to a location at which to return a pointer to a string * holding the keyword comment. Note, the stored string will change on * subsequent invocations of astFitsGetCom so a permanent copy * should be taken of the string if necessary. * Returned Value: * astFitsGetCom() * A value of zero is returned if the keyword was not found before * the end of the FitsChan was reached (no error is reported). * Otherwise, a value of one is returned. * Notes: * - If a NULL pointer is supplied for "name" then the comment from * the current card is returned. * - The returned value is obtained from the next card refering to * the required keyword, starting the search with the current card. * Any cards occuring before the current card are not seached. If * the entire contents of the FitsChan must be searched, then ensure * the current card is the first card in the FitsChan by clearing the Card * attribute. This effectively "rewinds" the FitsChan. * - The current card is updated to become the card following the one * read by this function. If the card read by this function is the * last one in the FitsChan, then the current card is left pointing at the * "end-of-file". * - An error will be reported if the keyword name does not conform * to FITS requirements. * - A NULL pointer is returned for the comment string if the keyword * has no comment. * - Zero is returned as the function value if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *method; /* Calling method */ const char *class; /* Object class */ char *lcom; /* Supplied keyword comment */ char *lname; /* Supplied keyword name */ char *lvalue; /* Supplied keyword value */ int ret; /* The returned value */ /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Initialise the returned value. */ ret = 0; /* Store the method name and object class. */ method = "astFitsGetCom"; class = astGetClass( this ); /* Extract the keyword name from the supplied string (if supplied). */ if( name ){ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); } else { lname = NULL; lcom = NULL; lvalue = NULL; } /* Find the next card in the FitsChan refering to this keyword. This will be the current card if no keyword name was supplied. The matching card is made the current card. Only proceed if a card was found. */ if( FindKeyCard( this, lname, method, class, status ) ){ /* Copy the comment into a static buffer, and return a pointer to it. */ if( CardComm( this, status ) ){ (void) strncpy( fitsgetcom_sval, CardComm( this, status ), AST__FITSCHAN_FITSCARDLEN ); fitsgetcom_sval[ AST__FITSCHAN_FITSCARDLEN ] = 0; if( comment ) *comment = fitsgetcom_sval; } else { if( comment ) *comment = NULL; } /* Move on to the next card. */ MoveCard( this, 1, method, class, status ); /* Indicate that a value is available. */ if( astOK ) ret = 1; } /* Release the memory used to hold keyword name, value and comment strings. */ lname = (char *) astFree( (void *) lname ); lvalue = (char *) astFree( (void *) lvalue ); lcom = (char *) astFree( (void *) lcom ); /* Return the answer. */ return ret; } static int SetFits( AstFitsChan *this, const char *keyname, void *value, int type, const char *comment, int overwrite, int *status ){ /* * Name: * SetFits * Purpose: * Store a keyword value of any type in a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int SetFits( AstFitsChan *this, const char *keyname, void *value, * int type, const char *comment, int overwrite, int *status ) * Class Membership: * FitsChan member function. * Description: * This function stores the supplied value for the supplied keyword * in the supplied FitsChan, assuming it is of the supplied data type. * Parameters: * this * Pointer to the FitsChan. * name * A pointer to a string holding the keyword name. * value * A pointer to a buffer holding the keyword value. For strings, * the buffer should hold the address of a pointer to the character * string. * type * The keyword type. * comment * A pointer to a string holding a comment to associated with the * keyword. If a NULL pointer or a blank string is supplied, then * any comment included in the string supplied for the "name" parameter * is used instead. If "name" contains no comment, then any existing * comment in the card being over-written is retained, or a NULL * pointer is stored if a new card is being inserted. If the data * value being stored for the card is the same as the card being * over-written, then any existing comment is retained. * overwrite * If non-zero, the new card formed from the supplied keyword name, * value and comment string over-writes the current card, and the * current card is incremented to refer to the next card. If zero, the * new card is inserted in front of the current card and the current * card is left unchanged. In either case, if the current card on * entry points to the "end-of-file", the new card is appended to the * end of the list. * status * Pointer to the inherited status variable. * Returned Value: * A value of 0 is returned if the value could not be stored for any * reason. A value of 1 is returned otherwise. * Notes: * - Nothing is stored in the FitsChan and a value of zero is returned * (but no error is reported) if an AST__FLOAT value is supplied equal * to AST__BAD. */ /* Local Variables: */ const char *cval; const char *ecval; double dval; double ecdval[ 2 ]; double edval; int ecival[ 2 ]; int eival; int ival; int ret; /* Check the global status, and the supplied pointer. */ if( !astOK || !value ) return 0; /* Initialise the returned value to indicate that the supplied name was stored. */ ret = 1; /* Check each data type in turn. */ if( type == AST__FLOAT ){ dval = *( (double *) value ); if( dval != AST__BAD ) { /* If the data value has not changed, and the card has a coment, set the comment pointer NULL so that the existing comment will be retained. */ if( overwrite && CnvValue( this, type, 0, &edval, "SetFits", status ) && CardComm( this, status ) ) { if( astEQUAL( edval, dval ) ) comment = NULL; } astSetFitsF( this, keyname, dval, comment, overwrite ); } else { ret = 0; } } else if( type == AST__STRING ){ cval = *( (char **) value); if( cval ){ /* If the data value has not changed, retain the original comment. */ if( overwrite && CnvValue( this, type, 0, &ecval, "SetFits", status ) && CardComm( this, status ) ) { if( Similar( ecval, cval, status ) ) comment = NULL; } /* Ignore comments if they are identical to the keyword value. */ if( comment && !strcmp( cval, comment ) ) comment = NULL; astSetFitsS( this, keyname, cval, comment, overwrite ); } else { ret = 0; } } else if( type == AST__CONTINUE ){ cval = *( (char **) value); if( cval ){ astSetFitsCN( this, keyname, cval, comment, overwrite ); } else { ret = 0; } } else if( type == AST__COMMENT ){ astSetFitsCom( this, keyname, comment, overwrite ); } else if( type == AST__INT ){ ival = *( (int *) value ); /* If the data value has not changed, retain the original comment. */ if( overwrite && CnvValue( this, type, 0, &eival, "SetFits", status ) && CardComm( this, status ) ) { if( eival == ival ) comment = NULL; } astSetFitsI( this, keyname, ival, comment, overwrite ); } else if( type == AST__COMPLEXF ){ if( ( (double *) value )[0] != AST__BAD && ( (double *) value )[1] != AST__BAD ) { /* If the data value has not changed, retain the original comment. */ if( overwrite && CnvValue( this, type, 0, ecdval, "SetFits", status ) && CardComm( this, status ) ) { if( astEQUAL( ecdval[ 0 ], ( (double *) value )[ 0 ] ) && astEQUAL( ecdval[ 1 ], ( (double *) value )[ 1 ] ) ) comment = NULL; } astSetFitsCF( this, keyname, (double *) value, comment, overwrite ); } else { ret = 0; } } else if( type == AST__COMPLEXI ){ /* If the data value has not changed, retain the original comment. */ if( overwrite && CnvValue( this, type, 0, ecival, "SetFits", status ) && CardComm( this, status ) ) { if( ecival[ 0 ] == ( (int *) value )[ 0 ] && ecival[ 1 ] == ( (int *) value )[ 1 ] ) comment = NULL; } astSetFitsCI( this, keyname, (int *) value, comment, overwrite ); } else if( type == AST__LOGICAL ){ ival = ( *( (int *) value ) != 0 ); /* If the data value has not changed, retain the original comment. */ if( overwrite && CnvValue( this, type, 0, &eival, "SetFits", status ) && CardComm( this, status ) ) { if( eival == ival ) comment = NULL; } astSetFitsL( this, keyname, ival, comment, overwrite ); } else if( type == AST__UNDEF ){ if( overwrite && CardType( this, status ) == AST__UNDEF && CardComm( this, status ) ) { comment = NULL; } astSetFitsU( this, keyname, comment, overwrite ); } return ret; } /* *++ * Name: c astSetFits f AST_SETFITS * Purpose: * Store a keyword value in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astSetFits( AstFitsChan *this, const char *name, type value, c const char *comment, int overwrite ) f CALL AST_SETFITS( THIS, NAME, VALUE, COMMENT, OVERWRITE, STATUS ) * Class Membership: * FitsChan method. * Description: c This is a family of functions which store values for named keywords f This is a family of routines which store values for named keywords * within a FitsChan at the current card position. The supplied keyword * value can either over-write an existing keyword value, or can be * inserted as a new header card into the FitsChan. * c The keyword data type is selected by replacing in the function name f The keyword data type is selected by replacing in the routine name * by one of the following strings representing the recognised FITS data * types: * * - CF - Complex floating point values. * - CI - Complex integer values. * - F - Floating point values. * - I - Integer values. * - L - Logical (i.e. boolean) values. * - S - String values. * - CN - A "CONTINUE" value, these are treated like string values, but * are encoded without an equals sign. * * The data type of the "value" parameter depends on as follows: * c - CF - "double *" (a pointer to a 2 element array holding the real and c imaginary parts of the complex value). c - CI - "int *" (a pointer to a 2 element array holding the real and c imaginary parts of the complex value). c - F - "double". c - I - "int". c - L - "int". c - S - "const char *". c - CN - "const char *". * f - CF - DOUBLE PRECISION(2) (a 2 element array holding the real and f imaginary parts of the complex value). f - CI - INTEGER(2) (a 2 element array holding the real and imaginary f parts of the complex value). f - F - DOUBLE PRECISION. f - I - INTEGER f - L - LOGICAL f - S - CHARACTER f - CN - CHARACTER * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c name f NAME = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string f A character string * containing the FITS keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. c value f VALUE = type (Given) * The keyword value to store with the named keyword. The data type * of this parameter depends on as described above. c comment f COMMENT = CHARACTER * ( * ) (Given) c A pointer to a null terminated string f A string * holding a comment to associated with the keyword. c If a NULL pointer or f If * a blank string is supplied, then any comment included in the string * supplied for the c "name" parameter is used instead. If "name" f NAME parameter is used instead. If NAME * contains no comment, then any existing comment in the card being * over-written is retained. Otherwise, no comment is stored with * the card. c overwrite f OVERWRITE = LOGICAL (Given) c If non-zero, f If .TRUE., * the new card formed from the supplied keyword name, value and comment * string over-writes the current card, and the current card is * incremented to refer to the next card (see the "Card" attribute). If c zero, f .FALSE., * the new card is inserted in front of the current card and the current * card is left unchanged. In either case, if the current card on entry * points to the "end-of-file", the new card is appended to the end of * the list. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The c function astSetFitsU f routine AST_SETFITSU * can be used to indicate that no value is associated with a keyword. * - The c function astSetFitsCM f routine AST_SETFITSCM * can be used to store a pure comment card (i.e. a card with a blank * keyword). * - To assign a new value for an existing keyword within a FitsChan, c first find the card describing the keyword using astFindFits, and c then use one of the astSetFits family to over-write the old value. f first find the card describing the keyword using AST_FINDFITS, and f then use one of the AST_SETFITS family to over-write the old value. * - If, on exit, there are no cards following the card written by c this function, then the current card is left pointing at the f this routine, then the current card is left pointing at the * "end-of-file". * - An error will be reported if the keyword name does not conform * to FITS requirements. *-- */ /* Define a macro which expands to the implementation of the astSetFits routine for a given data type. */ #define MAKE_FSET(code,ctype,ftype,valexp) \ static void SetFits##code( AstFitsChan *this, const char *name, ctype value, const char *comment, int overwrite, int *status ) { \ \ /* Local variables: */ \ const char *class; /* Object class */ \ const char *method; /* Calling method */ \ const char *com; /* Comment to use */ \ char *lcom; /* Supplied keyword comment */ \ char *lname; /* Supplied keyword name */ \ char *lvalue; /* Supplied keyword value */ \ int free_com; /* Should com be freed before returned? */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Ensure the source function has been called */ \ ReadFromSource( this, status ); \ \ /* Store the object clas and calling method. */ \ class = astGetClass( this ); \ method = "astSetFits"#code; \ \ /* Extract the keyword name from the supplied string. */ \ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); \ \ /* Initialise a pointer to the comment to be stored. If the supplied \ comment is blank, use the comment given with "name". */ \ com = ChrLen( comment, status ) ? comment : lcom; \ \ /* If the comment is still blank, use the existing comment if we are \ over-writing, or a NULL pointer otherwise. */ \ free_com = 0; \ if( !ChrLen( com, status ) ) { \ com = NULL; \ if( overwrite ) { \ if( CardComm( this, status ) ){ \ com = (const char *) astStore( NULL, (void *) CardComm( this, status ), \ strlen( CardComm( this, status ) ) + 1 ); \ free_com = 1; \ } \ } \ } \ \ /* Insert the new card. */ \ InsCard( this, overwrite, lname, ftype, valexp, com, method, class, status ); \ \ /* Release the memory used to hold keyword name, value and comment strings. */ \ lname = (char *) astFree( (void *) lname ); \ lvalue = (char *) astFree( (void *) lvalue ); \ lcom = (char *) astFree( (void *) lcom ); \ \ /* Release the memory holding the stored comment string, so long as it was \ allocated within this function. */ \ if( free_com ) com = (const char *) astFree( (void *) com ); \ \ } /* Use the above macro to give defintions for the astSetFits method for each FITS data type. */ MAKE_FSET(I,int,AST__INT,(void *)&value) MAKE_FSET(F,double,AST__FLOAT,(void *)&value) MAKE_FSET(S,const char *,AST__STRING,(void *)value) MAKE_FSET(CN,const char *,AST__CONTINUE,(void *)value) MAKE_FSET(CF,double *,AST__COMPLEXF,(void *)value) MAKE_FSET(CI,int *,AST__COMPLEXI,(void *)value) MAKE_FSET(L,int,AST__LOGICAL,(void *)&value) #undef MAKE_FSET static void SetFitsU( AstFitsChan *this, const char *name, const char *comment, int overwrite, int *status ) { /* *++ * Name: c astSetFitsU f AST_SETFITSU * Purpose: * Store an undefined keyword value in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astSetFitsU( AstFitsChan *this, const char *name, c const char *comment, int overwrite ) f CALL AST_SETFITSU( THIS, NAME, COMMENT, OVERWRITE, STATUS ) * Description: * This c function f routine * stores an undefined value for a named keyword within * a FitsChan at the current card position. The new undefined value * can either over-write an existing keyword value, or can be inserted * as a new header card into the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c name f NAME = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string f A character string * containing the FITS keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. c comment f COMMENT = CHARACTER * ( * ) (Given) c A pointer to a null terminated string f A string * holding a comment to associated with the keyword. c If a NULL pointer or f If * a blank string is supplied, then any comment included in the string * supplied for the c "name" parameter is used instead. If "name" f NAME parameter is used instead. If NAME * contains no comment, then any existing comment in the card being * over-written is retained. Otherwise, no comment is stored with * the card. c overwrite f OVERWRITE = LOGICAL (Given) c If non-zero, f If .TRUE., * the new card formed from the supplied keyword name and comment * string over-writes the current card, and the current card is * incremented to refer to the next card (see the "Card" attribute). If c zero, f .FALSE., * the new card is inserted in front of the current card and the current * card is left unchanged. In either case, if the current card on entry * points to the "end-of-file", the new card is appended to the end of * the list. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If, on exit, there are no cards following the card written by * this function, then the current card is left pointing at the * "end-of-file". * - An error will be reported if the keyword name does not conform * to FITS requirements. *-- */ /* Local variables: */ const char *class; /* Object class */ const char *method; /* Calling method */ const char *com; /* Comment to use */ char *lcom; /* Supplied keyword comment */ char *lname; /* Supplied keyword name */ char *lvalue; /* Supplied keyword value */ int free_com; /* Should com be freed before returned? */ /* Check the global error status. */ if ( !astOK ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the object clas and calling method. */ class = astGetClass( this ); method = "astSetFitsU"; /* Extract the keyword name from the supplied string. */ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); /* Initialise a pointer to the comment to be stored. If the supplied comment is blank, use the comment given with "name". */ com = ChrLen( comment, status ) ? comment : lcom; /* If the comment is still blank, use the existing comment if we are over-writing, or a NULL pointer otherwise. */ free_com = 0; if( !ChrLen( com, status ) ) { com = NULL; if( overwrite ) { if( CardComm( this, status ) ){ com = (const char *) astStore( NULL, (void *) CardComm( this, status ), strlen( CardComm( this, status ) ) + 1 ); free_com = 1; } } } /* Insert the new card. */ InsCard( this, overwrite, lname, AST__UNDEF, NULL, com, method, class, status ); /* Release the memory used to hold keyword name, value and comment strings. */ lname = (char *) astFree( (void *) lname ); lvalue = (char *) astFree( (void *) lvalue ); lcom = (char *) astFree( (void *) lcom ); /* Release the memory holding the stored comment string, so long as it was allocated within this function. */ if( free_com ) com = (const char *) astFree( (void *) com ); } static void SetFitsCM( AstFitsChan *this, const char *comment, int overwrite, int *status ) { /* *++ * Name: c astSetFitsCM f AST_SETFITSCM * Purpose: * Store a comment card in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astSetFitsCM( AstFitsChan *this, const char *comment, c int overwrite ) f CALL AST_SETFITSCM( THIS, COMMENT, OVERWRITE, STATUS ) * Description: * This c function f routine * stores a comment card ( i.e. a card with no keyword name or equals * sign) within a FitsChan at the current card position. The new card * can either over-write an existing card, or can be inserted as a new * card into the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c comment f COMMENT = CHARACTER * ( * ) (Given) c A pointer to a null terminated string f A string * holding the text of the comment card. c If a NULL pointer or f If * a blank string is supplied, then a totally blank card is produced. c overwrite f OVERWRITE = LOGICAL (Given) c If non-zero, f If .TRUE., * the new card over-writes the current card, and the current card is * incremented to refer to the next card (see the "Card" attribute). If c zero, f .FALSE., * the new card is inserted in front of the current card and the current * card is left unchanged. In either case, if the current card on entry * points to the "end-of-file", the new card is appended to the end of * the list. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If, on exit, there are no cards following the card written by * this function, then the current card is left pointing at the * "end-of-file". *-- */ /* Just call astSetFitsCom with a blank keyword name. */ astSetFitsCom( this, "", comment, overwrite ); } static void SetFitsCom( AstFitsChan *this, const char *name, const char *comment, int overwrite, int *status ){ /* *+ * Name: * astSetFitsCom * Purpose: * Store a comment for a keyword in a FitsChan. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * void astSetFitsCom( AstFitsChan *this, const char *name, * const char *comment, int overwrite ) * Class Membership: * FitsChan method. * Description: * This function replaces the comment within an existing card, or * stores a new comment card within a FitsChan. * Parameters: * this * Pointer to the FitsChan. * name * A pointer to a * string holding the keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. * comment * A pointer to a * string holding a comment to associated with the keyword. * If a NULL or * blank string is supplied, any existing comment associated with * the keyword is removed. * overwrite * If non-zero, the new comment replaces the comment in the current * card, and the current card is then incremented to refer to the next * card. If zero, a new comment card is inserted in front of the current * card and the current card is left unchanged. In either case, if the * current card on entry points to the "end-of-file", the new card is * appended to the end of the list. * Notes: * - When replacing an existing comment, any existing keyword value is * retained only if the supplied keyword name is the same as the keyword * name in the current card. If the keyword names are different, then * the new name replaces the old name, and any existing keyword data value * is deleted. The card thus becomes a comment card with the supplied * keyword name and comment, but no data value. * - If, on exit, there are no cards following the card written by * this function, then the current card is left pointing at the * "end-of-file". * - The current card can be set explicitly before calling this function * either by assigning a value to the Card attribute (if the index of the * required card is already known), or using astFindFits (if only the * keyword name is known). * - An error will be reported if the keyword name does not conform * to FITS requirements. *- */ /* Local variables: */ const char *class; /* Pointer to object class string */ const char *method; /* Pointer to calling method string */ const char *cname; /* The existing keyword name */ const char *com; /* The comment to use */ char *lcom; /* Supplied keyword comment */ char *lname; /* Supplied keyword name */ char *lvalue; /* Supplied keyword value */ void *old_data; /* Pointer to the old data value */ void *data; /* Pointer to data value to be stored */ size_t size; /* The size of the data value */ /* Check the global error status. */ if ( !astOK ) return; /* Initialisation */ size = 0; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the calling method and object class. */ method = "astSetFitsCom"; class = astGetClass( this ); /* Extract the keyword name, etc, from the supplied string. */ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); /* If a blank comment has been supplied, use NULL instead. */ com = ChrLen( comment, status )? comment : NULL; /* If we are inserting a new card, or over-writing an old card with a different name, create and store a comment card with the given keyword name and comment, but no data value. */ cname = CardName( this, status ); if( !overwrite || !cname || strcmp( lname, cname ) ){ InsCard( this, overwrite, lname, AST__COMMENT, NULL, com, method, class, status ); /* If we are overwriting an existing keyword comment, use the data type and value from the existing current card. Note, we have to take a copy of the old data value because InsCard over-writes by deleting the old card and then inserting a new one. */ } else { old_data = CardData( this, &size, status ); data = astStore( NULL, old_data, size ); InsCard( this, 1, lname, CardType( this, status ), data, com, method, class, status ); data = astFree( data ); } /* Release the memory used to hold keyword name, value and comment strings. */ lname = (char *) astFree( (void *) lname ); lvalue = (char *) astFree( (void *) lvalue ); lcom = (char *) astFree( (void *) lcom ); } static void FixNew( AstFitsChan *this, int flag, int remove, const char *method, const char *class, int *status ){ /* * * Name: * FixNew * Purpose: * Remove "new" flags from the whole FitsChan, and optionally remove * "new" cards. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FixNew( AstFitsChan *this, int flag, int remove, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan method. * Description: * This function searches the entire FitsChan for cards which are * marked as new using the supplied flag (NEW1 or NEW2). If "remove" * is non-zero, these cards are completely removed from the FitsChan * (not just marked as used). If "remove" is zero, they are retained * and the specified flag is cleared. * Parameters: * this * Pointer to the FitsChan. * flag * The flag to use; NEW1 or NEW2. * remove * Remove flagged cards from the FitsChan? * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if an error has occurred. * - If any cards are removed, the current Card is left at "end-of-file" * on exit. If no cards are removed, the original current card is * retained. *- */ /* Local Variables: */ int *flags; /* Pointer to flags mask for the current card */ int icard; /* Index of current card on entry */ int ndeleted; /* Number of cards deleted by this call */ /* Return if no FitsChan was supplied, or if the FitsChan is empty. */ if ( !this || !this->head ) return; /* Save the current card index, and rewind the FitsChan. */ icard = astGetCard( this ); astClearCard( this ); /* Indicate no cards have yet been deleted. */ ndeleted = 0; /* Loop through the list of FitsCards in the FitsChan until the final card is reached. */ while( astOK && this->card ){ /* Get a pointer to the flags mask for this card. */ flags = CardFlags( this, status ); /* See if the Card has been marked with the requeste new flag. */ if( flags && ( (*flags) & flag ) ) { /* If requested, remove the card. This will automatically move the current card on to the next card. */ if( remove ){ DeleteCard( this, method, class, status ); ndeleted++; /* Otherwise, clear the flag. */ } else { *flags = (*flags) & ~flag; /* Increment the card count and move on to the next card. */ MoveCard( this, 1, method, class, status ); } /* Move on to the next card if this card is not marked with the requested new flag. */ } else { MoveCard( this, 1, method, class, status ); } } /* If no cards were removed, we can safely re-instate the original current card. Otherwise, the current card is left at "end-of-file". */ if( ndeleted == 0 ) astSetCard( this, icard ); /* Return */ return; } static void FixUsed( AstFitsChan *this, int reset, int used, int remove, const char *method, const char *class, int *status ){ /* * * Name: * FixUsed * Purpose: * Remove "provisionally used" flags from the whole FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FixUsed( AstFitsChan *this, int reset, int used, int remove, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan method. * Description: * This function searches the entire FitsChan for cards which are * marked as "provisionally used". The "provisionally used" flag is * cleared for each such card. In addition, if "used" is non-zero then * each such card is flagged as having been "definitely used". If * "remove" is non-zero, then all "provisionally used" cards are deleted * from the FitsChan. * Parameters: * this * Pointer to the FitsChan. * reset * Set all cards so that they are neither provisionally used or * definitely used. In this case neither the "used" nor the * "remove" parameter are accssed. * used * Have the provisionally used cards definitely been used? * remove * Should provisionally used cards be deleted? * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if an error has occurred. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ FitsCard *card0; /* Pointer to current FitsCard */ int *flags; /* Pointer to flags mask for the current card */ int old_ignore_used; /* Original value of variable ignore_used */ int old_status; /* Original inherited status value */ int rep; /* Original error reporting flag */ /* Return if no FitsChan was supplied, or if the FitsChan is empty. */ if ( !this || !this->head ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Temporarily clear any bad status value and supress error reporting in this function. */ old_status = astStatus; astClearStatus; rep = astReporting( 0 ); /* Indicate that we should not skip over cards marked as having been read. */ old_ignore_used = ignore_used; ignore_used = 0; /* Save a pointer to the current card, and the reset the current card to be the first card. */ card0 = this->card; astClearCard( this ); /* Loop through the list of FitsCards in the FitsChan until the final card is reached. */ while( this->card ){ /* Get a pointer to the flags mask for this card. */ flags = CardFlags( this, status ); /* Reset both used flags if required. */ if( reset ) { *flags = (*flags) & ~PROVISIONALLY_USED; *flags = (*flags) & ~USED; MoveCard( this, 1, method, class, status ); /* Otherwise perform the actions indicated by parameters "used" and "remove". */ } else { /* See if the Card has been provisionally used. */ if( flags && ( (*flags) & PROVISIONALLY_USED ) ) { /* Clear the provisionally used flag. */ *flags = (*flags) & ~PROVISIONALLY_USED; /* If required, set the definitely used flag. */ if( used ) *flags = (*flags) | USED; /* If required, delete the card. The next card is made current. If we are about to delete the original current card, we need to update the pointer to the card to be made current at the end of this function. If we end up back at the head of the chain, indicate that we have reached the end of file by setting card0 NULL. */ if( remove ) { if( card0 == this->card && card0 ) { card0 = ( (FitsCard *) this->card )->next; if( (void *) card0 == this->head ) card0 = NULL; } DeleteCard( this, method, class, status ); /* Otherwise, just move on to the next card. */ } else { MoveCard( this, 1, method, class, status ); } /* If this card has not bee provisionally used, move on to the next card. */ } else { MoveCard( this, 1, method, class, status ); } } } /* Re-instate the original current card. */ this->card = card0; /* If this card is now flagged as definitely used, move forward to the next un-used card. */ flags = CardFlags( this, status ); if( flags && (*flags & USED ) ) { ignore_used = 1; MoveCard( this, 1, method, class, status ); } /* Re-instate the original flag indicating if cards marked as having been read should be skipped over. */ ignore_used = old_ignore_used; /* Re-instate the original status value and error reporting condition. */ astReporting( rep ); astSetStatus( old_status ); } static void FormatCard( AstFitsChan *this, char *buf, const char *method, int *status ){ /* * * Name: * FormatCard * Purpose: * Formats the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void FormatCard( AstFitsChan *this, char *buf, const char *method, int *status ) * Class Membership: * FitsChan method. * Description: * This function write the current card into the supplied character * buffer as a complete FITS header card. * Parameters: * this * Pointer to the FitsChan. * buf * A character string into which the header card is written. This * should be at least 81 characters long. The returned string is * padded with spaces upto column 80. A terminating null character * is added. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - An error is reported if the requested header card does not conform to * FITS standards. * */ /* Local Variables: */ const char *com; /* Pointer to comment string to use */ int comlen; /* Length of comment string */ int comstart; /* Column in which to start comment */ int i; /* Loop counter for characters */ int len; /* Output string length */ int digits; /* No. of digits to use when formatting floating point values */ int type; /* Card data type */ /* Check the global error status, and check the current card is defined. */ if ( !astOK || astFitsEof( this ) ) return; /* Get a pointer to the comment to use and determine its length. */ com = CardComm( this, status ); comlen = ChrLen( com, status ); /* Copy the keyword name to the start of the output buffer, and store its length. */ len = (int) strlen( strcpy( buf, CardName( this, status ) ) ); /* Pad the name with spaces up to column 8. */ while ( len < FITSNAMLEN ) buf[ len++ ] = ' '; /* If the card contains a keyword value... */ type = CardType( this, status ); if( type != AST__COMMENT ){ /* Get the number of digits to use when formatting floating point values. */ digits = astGetFitsDigits( this ); /* Put an equals sign in column 9 (or a space if the keyword is a CONTINUE card), followed by a space in column 10. */ buf[ len++ ] = ( type == AST__CONTINUE ) ? ' ' : '='; buf[ len++ ] = ' '; /* Format and store the keyword value, starting at column 11 and update the output string length. */ len += EncodeValue( this, buf + len, FITSNAMLEN + 3, digits, method, status ); /* If there is a comment, determine which column it should start in so that it ends in column 80. */ if( com ){ comstart = AST__FITSCHAN_FITSCARDLEN - ( comlen - 2 ) + 1; /* Adjust the starting column to 32 if possible, avoiding over-writing the value, or running off the end of the card unless this is unavoidable. */ if ( comstart > FITSCOMCOL ) comstart = FITSCOMCOL; if ( comstart < len + 2 ) comstart = len + 2; /* Pad the output buffer with spaces up to the start of the comment. */ while ( len < comstart - 1 ) buf[ len++ ] = ' '; /* Then append "/ " to introduce the comment, truncating if the card length forces this. */ for ( i = 0; ( i < 2 ) && ( len < AST__FITSCHAN_FITSCARDLEN ); i++ ) { buf[ len++ ] = "/ "[ i ]; } } } /* Append any comment, truncating it if the card length forces this. */ if ( com ) { for ( i = 0; com[ i ] && ( len < AST__FITSCHAN_FITSCARDLEN ); i++ ) { buf[ len++ ] = com[ i ]; } } /* Pad with spaces up to the end of the card. */ while ( len < AST__FITSCHAN_FITSCARDLEN ) buf[ len++ ] = ' '; /* Terminate it. */ buf[ AST__FITSCHAN_FITSCARDLEN ] = 0; } static int FullForm( const char *list, const char *test, int abbrev, int *status ){ /* * Name: * FullForm * Purpose: * Identify the full form of an option string. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int FullForm( const char *list, const char *test, int abbrev, int *status ) * Class Membership: * FitsChan method. * Description: * This function identifies a supplied test option within a supplied * list of valid options, and returns the index of the option within * the list. The test option may be abbreviated, and case is * insignificant. * Parameters: * list * A list of space separated option strings. * test * A candidate option string. * abbrev * 1 if abbreviations are to be accepted. Zero otherwise. * status * Pointer to the inherited status variable. * Returned Value: * The index of the identified option within the supplied list, starting * at zero. -1 is returned if the option is not recognised, and (if * abbrev is 1 ) -2 if the option is ambiguous (no errors are reported * in these cases). If abbrev is zero, the returned index will be the * index of the first matching string. * * Notes: * - A value of -1 is returned if an error has already occurred, or * if this function should fail for any reason. */ /* Local Variables: */ char *context; /* Context used by strtok_r */ char *llist; /* Pointer to a local copy of the options list */ char *option; /* Pointer to the start of the next option */ int i; /* Current option index */ int len; /* Length of supplied option */ int nmatch; /* Number of matching options */ int ret; /* The returned index */ /* Initialise the answer to indicate that the option has not been identified. */ ret = -1; /* Avoid compiler warnings. */ context = NULL; /* Check global status. */ if( !astOK ) return ret; /* Take a local copy of the supplied options list. This is necessary since "strtok" modified the string by inserting null characters. */ llist = (char *) astStore( NULL, (void *) list, strlen(list) + 1 ); if( astOK ){ /* Save the number of characters in the supplied test option (excluding trailing spaces). */ len = ChrLen( test, status ); /* Compare the supplied test option against each of the known options in turn. Count the number of matches. */ nmatch = 0; #if HAVE_STRTOK_R option = strtok_r( llist, " ", &context ); #else option = strtok( llist, " " ); #endif i = 0; while( option ){ /* If every character in the supplied label matches the corresponding character in the current test label we have a match. Increment the number of matches and save the current item index. If abbreviation is not allowed ensure that the lengths of the strings are equal. */ if( !Ustrncmp( test, option, len, status ) && ( abbrev || len == ChrLen( option, status ) ) ) { nmatch++; ret = i; if( !abbrev ) break; } /* Get a pointer to the next option. */ #if HAVE_STRTOK_R option = strtok_r( NULL, " ", &context ); #else option = strtok( NULL, " " ); #endif i++; } /* Return -1 if no match was found. */ if( !nmatch ){ ret = -1; /* Return -2 if the option was ambiguous. */ } else if( abbrev && nmatch > 1 ){ ret = -2; } /* Free the local copy of the options list. */ llist = (char *) astFree( (void *) llist ); } /* Return the answer. */ return ret; } static const char *GetAllWarnings( AstFitsChan *this, int *status ){ /* *+ * Name: * astGetAllWarnings * Purpose: * Return a list of all condition names. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * const char *GetAllWarnings( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function returns a space separated lits of the condition names * currently recognized by the Warnings attribute. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * A pointer to a static string holding the condition names. * Notes: * - This routine does not check the inherited status. *- */ /* Return the result. */ return ALLWARNINGS; } const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * FitsChan member function (over-rides the protected astGetAttrib * method inherited from the Channel class). * Description: * This function returns a pointer to the value of a specified * attribute for a FitsChan, formatted as a character string. * Parameters: * this * Pointer to the FitsChan. * 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 FitsChan, 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 FitsChan. 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 */ AstFitsChan *this; /* Pointer to the FitsChan structure */ const char *result; /* Pointer value to return */ int ival; /* Integer 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 FitsChan structure. */ this = (AstFitsChan *) this_object; /* Card. */ /* ----- */ if ( !strcmp( attrib, "card" ) ) { ival = astGetCard( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* CardComm. */ /* --------- */ } else if ( !strcmp( attrib, "cardcomm" ) ) { result = astGetCardComm( this ); /* CardName. */ /* --------- */ } else if ( !strcmp( attrib, "cardname" ) ) { result = astGetCardName( this ); /* CardType. */ /* --------- */ } else if ( !strcmp( attrib, "cardtype" ) ) { ival = astGetCardType( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Encoding. */ /* --------- */ } else if ( !strcmp( attrib, "encoding" ) ) { ival = astGetEncoding( this ); if ( astOK ) { if( ival == NATIVE_ENCODING ){ result = NATIVE_STRING; } else if( ival == FITSPC_ENCODING ){ result = FITSPC_STRING; } else if( ival == FITSIRAF_ENCODING ){ result = FITSIRAF_STRING; } else if( ival == FITSAIPS_ENCODING ){ result = FITSAIPS_STRING; } else if( ival == FITSAIPSPP_ENCODING ){ result = FITSAIPSPP_STRING; } else if( ival == FITSCLASS_ENCODING ){ result = FITSCLASS_STRING; } else if( ival == FITSWCS_ENCODING ){ result = FITSWCS_STRING; } else if( ival == DSS_ENCODING ){ result = DSS_STRING; } else { result = UNKNOWN_STRING; } } /* CDMatrix */ /* -------- */ } else if ( !strcmp( attrib, "cdmatrix" ) ) { ival = astGetCDMatrix( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* DefB1950 */ /* -------- */ } else if ( !strcmp( attrib, "defb1950" ) ) { ival = astGetDefB1950( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* TabOK */ /* ----- */ } else if ( !strcmp( attrib, "tabok" ) ) { ival = astGetTabOK( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* CarLin */ /* ------ */ } else if ( !strcmp( attrib, "carlin" ) ) { ival = astGetCarLin( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* PolyTan */ /* ------- */ } else if ( !strcmp( attrib, "polytan" ) ) { ival = astGetPolyTan( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Iwc */ /* --- */ } else if ( !strcmp( attrib, "iwc" ) ) { ival = astGetIwc( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Clean */ /* ----- */ } else if ( !strcmp( attrib, "clean" ) ) { ival = astGetClean( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* FitsAxisOrder. */ /* -------------- */ } else if ( !strcmp( attrib, "fitsaxisorder" ) ) { result = astGetFitsAxisOrder( this ); /* FitsDigits. */ /* ----------- */ } else if ( !strcmp( attrib, "fitsdigits" ) ) { ival = astGetFitsDigits( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Ncard. */ /* ------ */ } else if ( !strcmp( attrib, "ncard" ) ) { ival = astGetNcard( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Nkey. */ /* ----- */ } else if ( !strcmp( attrib, "nkey" ) ) { ival = astGetNkey( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* AllWarnings */ /* ----------- */ } else if ( !strcmp( attrib, "allwarnings" ) ) { result = astGetAllWarnings( this ); /* Warnings. */ /* -------- */ } else if ( !strcmp( attrib, "warnings" ) ) { result = astGetWarnings( this ); /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetCard( AstFitsChan *this, int *status ){ /* *+ * Name: * astGetCard * Purpose: * Get the value of the Card attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astGetCard( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function returns the value of the Card attribute for the supplied * FitsChan. This is the index of the next card to be read from the * FitsChan. The index of the first card is 1. If there are no more * cards to be read, a value one greater than the number of cards in the * FitsChan is returned. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * The index of the next card to be read. * Notes: * - A value of zero will be returned if the current card is not defined. * - This function attempts to execute even if an error has occurred. *- */ /* Local Variables: */ const char *class; /* Pointer to class string */ const char *method; /* Pointer to method string */ FitsCard *card0; /* Pointer to current FitsCard */ int index; /* Index of next FitsCard */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return if no FitsChan was supplied, or if the FitsChan is empty. */ if ( !this || !this->head ) return 0; /* Store the method and object class. */ method = "astGetCard"; class = astGetClass( this ); /* Save a pointer to the current card, and the reset the current card to be the first card. */ card0 = this->card; astClearCard( this ); /* Count through the list of FitsCards in the FitsChan until the original current card is reached. If the current card is not found (for instance if it has been marked as deleted and we are currently skipping such cards), this->card will be left null (end-of-file). */ index = 1; while( this->card != card0 && astOK && this->card ){ /* Increment the card count and move on to the next card. */ index++; MoveCard( this, 1, method, class, status ); } /* Return the card index. */ return index; } static const char *GetCardComm( AstFitsChan *this, int *status ){ /* *+ * Name: * GetCardComm * Purpose: * Get the value of the CardComm attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * const char *astGetCardComm( AstFitsChan *this) * Class Membership: * FitsChan method. * Description: * This function returns the value of the CardComm attribute for the * supplied FitsChan. This is the comment for the current card. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * A pointer to a static string holding the comment. A zero-length * string is returned if the card has no comment. * Notes: * - A value of NULL will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables */ const char *result = NULL; /* Check inherited status */ if( !astOK ) return result; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Get the comment for the current card. */ result = CardComm( this, status ); /* Return a zero-length string if the card has no comment. */ if( astOK && !result ) result = ""; /* Return the comment. */ return result; } static const char *GetCardName( AstFitsChan *this, int *status ){ /* *+ * Name: * GetCardName * Purpose: * Get the value of the CardName attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * const char *astGetCardName( AstFitsChan *this) * Class Membership: * FitsChan method. * Description: * This function returns the value of the CardName attribute for the * supplied FitsChan. This is the keyword name for the current card. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * A pointer to a static string holding the keyword name. * Notes: * - A value of NULL will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return the keyword name of the current card. */ return CardName( this, status ); } static int GetCardType( AstFitsChan *this, int *status ){ /* *+ * Name: * GetCardType * Purpose: * Get the value of the CardType attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astGetCardType( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function returns the value of teh CardType attribute for the supplied * FitsChan. This is the data type of the keyword value for the current card. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * An integer representing the data type of the current card. * Notes: * - A value of AST__NOTYPE will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return the data type of the current card. */ return CardType( this, status ); } static int GetFull( AstChannel *this_channel, int *status ) { /* * Name: * GetFull * Purpose: * Obtain the value of the Full attribute for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetFull( AstChannel *this, int *status ) * Class Membership: * FitsChan member function (over-rides the protected astGetFull * method inherited from the Channel class). * Description: * This function return the integer value of the Full attribute for * a FitsChan. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The Full attribute value. * Notes: * - This function modifies the default Full value from 0 to -1 for * the benefit of the FitsChan class. This prevents non-essential * information being written by the astWrite method unless it is * requested by explicitlt setting a Full value. * - 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: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ int result; /* Result value to return */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* If the Full attribute us set, obtain its value using the parent class method. */ if ( astTestFull( this ) ) { result = (* parent_getfull)( this_channel, status ); /* Otherwise, supply a default value of -1. */ } else { result = -1; } /* Return the result. */ return result; } static FitsCard *GetLink( FitsCard *card, int next, const char *method, const char *class, int *status ){ /* * Name: * GetLink * Purpose: * Get a pointer to the next or previous card in the list. * Type: * Private function. * Synopsis: * #include "fitschan.h" * FitsCard *GetLink( FitsCard *card, int next, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns the a pointer to either the next or previous FitsCard * structure in the circular linked list of such structures stored in a * FitsChan. A check is performed to ensure that the forward and * backward links from the supplied card are consistent and an error * is reported if they are not (so long as no previous error has been * reported). Memory corruption can result in inconsistent links * which can result in infinite loops if an attempt is made to scan the * list. * Parameters: * card * The current card. * next * If non-zero, a pointer to the "next" card is returned. Otherwise * a pointer to the "previous" card is returned. * method * Pointer to string holding the name of the calling method. * class * Pointer to string holding the object class. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the required card, or NULL if an error occurs. * Notes: * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ FitsCard *ret; /* Pointer to the returned card */ /* Check that the "next" link from the previous card points back to the current card, and that the "prev" link from the next card points back to the current card. */ if( card && ( card->prev->next != card || card->next->prev != card ) ){ /* Report an error so long as no previous error has been reported, and return a NULL pointer. */ if( astOK ){ astError( AST__FCRPT, "%s(%s): A corrupted %s object has been " "supplied.", status, method, class, class ); } ret = NULL; /* If the links are good, return a pointer to the required card. */ } else { ret = next ? card->next : card->prev; } /* Return the result. */ return ret; } static int GetNcard( AstFitsChan *this, int *status ){ /* *+ * Name: * astGetNcard * Purpose: * Get the value of the Ncard attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astGetNcard( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function returns the value of the Ncard attribute for the supplied * FitsChan. This is the number of cards currently in the FitsChan. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * The number of cards currently in the FitsChan. * Notes: * - A value of zero will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ const char *class; /* Pointer to class string */ const char *method; /* Pointer to method string */ FitsCard *card0; /* Pointer to current card on entry */ int ncard; /* Number of cards so far */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return zero if an error has already occurred, or no FitsChan was supplied, or the FitsChan is empty. */ if ( !astOK || !this || !this->head ) return 0; /* Store the method and object class. */ method = "astGetNcard"; class = astGetClass( this ); /* Save a pointer to the current card, and then reset the current card to be the first card. */ card0 = this->card; astClearCard( this ); /* Count through the cards in the FitsChan until the end of file is reached. */ ncard = 0; while( astOK && this->card ){ /* Increment the card count and move on to the next card. */ ncard++; MoveCard( this, 1, method, class, status ); } /* Reset the current card to be the original current card. */ this->card = card0; /* Return the result. */ return astOK ? ncard : 0; } static int GetNkey( AstFitsChan *this, int *status ){ /* *+ * Name: * astGetNkey * Purpose: * Get the value of the Nkey attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astGetNkey( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function returns the value of the Nkey attribute for the supplied * FitsChan. This is the number of unique keywords currently in the * FitsChan. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * The number of unique keywords currently in the FitsChan. * Notes: * - A value of zero will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ AstKeyMap *km; /* KeyMap holding unique keyword names */ FitsCard *card0; /* Pointer to current card on entry */ const char *class; /* Pointer to class string */ const char *method; /* Pointer to method string */ int nkey; /* Returned Nkey value */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return zero if an error has already occurred, or no FitsChan was supplied, or the FitsChan is empty. */ if ( !astOK || !this || !this->head ) return 0; /* Store the method and object class. */ method = "astGetNkey"; class = astGetClass( this ); /* Create an empty KeyMap to hold the unused keyword names */ km = astKeyMap( " ", status ); /* Save a pointer to the current card, and then reset the current card to be the first card. */ card0 = this->card; astClearCard( this ); /* Loop through the cards in the FitsChan until the end of file is reached. */ while( astOK && this->card ){ /* Get the keyword name for the current card and add it to the keymap. */ astMapPut0I( km, CardName( this, status ), 0, NULL ); /* Move on to the next unused card. */ MoveCard( this, 1, method, class, status ); } /* Reset the current card to be the original current card. */ this->card = card0; /* Get the number of keywords. */ nkey = astMapSize( km ); /* Annull the KeyMap . */ km = astAnnul( km ); /* Return the result. */ return astOK ? nkey : 0; } static void GetNextData( AstChannel *this_channel, int skip, char **name, char **val, int *status ) { /* * Name: * GetNextData * Purpose: * Read the next item of data from a data source. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void GetNextData( AstChannel *this, int skip, char **name, char **val ) * Class Membership: * FitsChan member function (over-rides the protected * astGetNextData method inherited from the Channel class). * Description: * This function reads the next item of input data from a data * source associated with a FitsChan and returns the result. It * decodes the data item and returns name/value pairs ready for * use. * Parameters: * this * Pointer to the FitsChan. * skip * A non-zero value indicates that a new Object is to be read, * and that all input data up to the next "Begin" item are to be * skipped in order to locate it. This is useful if the data * source contains AST objects interspersed with other data (but * note that these other data cannot appear inside AST Objects, * only between them). * * A zero value indicates that all input data are significant * and the next item will therefore be read and an attempt made * to interpret it whatever it contains. Any other data * inter-mixed with AST Objects will then result in an error. * name * An address at which to store a pointer to a null-terminated * dynamically allocated string containing the name of the next * item in the input data stream. This name will be in lower * case with no surrounding white space. It is the callers * responsibilty to free the memory holding this string (using * astFree) when it is no longer required. * * A NULL pointer value will be returned (without error) to * indicate when there are no further input data items to be * read. * val * An address at which to store a pointer to a null-terminated * dynamically allocated string containing the value associated * with the next item in the input data stream. No case * conversion is performed on this string and all white space is * potentially significant. It is the callers responsibilty to * free the memory holding this string (using astFree) when it * is no longer required. * * The returned pointer will be NULL if an Object data item is * read (see the "Data Representation" section). * Data Representation: * The returned data items fall into the following categories: * * - Begin: Identified by the name string "begin", this indicates * the start of an Object definition. The associated value string * gives the class name of the Object being defined. * * - IsA: Identified by the name string "isa", this indicates the * end of the data associated with a particular class structure * within the definiton of a larger Object. The associated value * string gives the name of the class whose data have just been * read. * * - End: Identified by the name string "end", this indicates the * end of the data associated with a complete Object * definition. The associated value string gives the class name of * the Object whose definition is being ended. * * - Non-Object: Identified by any other name string plus a * non-NULL "val" pointer, this gives the value of a non-Object * structure component (instance variable). The name identifies * which instance variable it is (within the context of the class * whose data are being read) and the value is encoded as a string. * * - Object: Identified by any other name string plus a NULL "val" * pointer, this identifies the value of an Object structure * component (instance variable). The name identifies which * instance variable it is (within the context of the class whose * data are being read) and the value is given by subsequent data * items (so the next item should be a "Begin" item). * Notes: * - NULL pointer values will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Constants: */ #define BUFF_LEN 100 /* Length of formatting buffer */ /* Local Variables: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ char *keyword; /* Pointer to current keyword string */ char *newdata; /* Pointer to stripped string value */ char *upq; /* Pointer to unprequoted string */ char buff[ BUFF_LEN + 1 ]; /* Buffer for formatting values */ const char *class; /* Pointer to object class */ const char *method; /* Pointer to method name */ int cont; /* String ends with an ampersand? */ int done; /* Data item found? */ int freedata; /* Should the data pointer be freed? */ int i; /* Loop counter for keyword characters */ int len; /* Length of current keyword */ int nc; /* Number of characters read by "astSscanf" */ int nn; /* No. of characters after UnPreQuoting */ int type; /* Data type code */ void *data; /* Pointer to current data value */ /* Initialise the returned pointer values. */ *name = NULL; *val = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Store the method name and object class. */ method = "astRead"; class = astGetClass( this ); /* Loop to consider successive cards stored in the FitsChan (starting at the "current" card) until a valid data item is read or "end of file" is reached. Also quit the loop if an error occurs. */ done = 0; newdata = NULL; while ( !done && !astFitsEof( this ) && astOK ){ /* Obtain the keyword string, data type code and data value pointer from the current card. */ keyword = CardName( this, status ); type = CardType( this, status ); data = CardData( this, NULL, status ); /* Mark all cards as having been used unless we are skipping over cards which may not be related to AST. */ if( !skip ) MarkCard( this, status ); /* Ignore comment cards. */ if ( type != AST__COMMENT ) { /* Native encoding requires trailing white space to be removed from string values (so that null strings can be distinguished from blank strings). Do this now. */ freedata = 0; if ( ( type == AST__STRING || type == AST__CONTINUE ) && data ){ newdata = (char *) astStore( NULL, data, strlen( (char *) data ) + 1 ); if( newdata ){ newdata[ ChrLen( data, status ) ] = 0; data = (void *) newdata; freedata = 1; } } /* Obtain the keyword length and test the card to identify the type of AST data item (if any) that it represents. */ len = (int) strlen( keyword ); /* "Begin" item. */ /* ------------- */ /* This is identified by a string value and a keyword of the form "BEGASTxx", where "xx" are characters encoding a sequence number. */ if ( ( type == AST__STRING ) && ( nc = 0, ( 0 == astSscanf( keyword, "BEGAST" "%*1[" SEQ_CHARS "]" "%*1[" SEQ_CHARS "]%n", &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name to "begin" and extract the associated class name from the string value. Store both of these in dynamically allocated strings. */ *name = astString( "begin", 5 ); *val = UnPreQuote( (const char *) data, status ); /* Indicate that the current card has been used. */ MarkCard( this, status ); /* The "begin" item will be preceded by a header of COMMENT cards. Mark them as having been used. */ ComBlock( this, -1, method, class, status ); /* "IsA" item. */ /* ----------- */ /* This is identified by a string value and a keyword of the form "ISAxx", where "xx" are characters encoding a sequence number. Don't accept the item if we are skipping over cards looking for a "Begin" item. */ } else if ( !skip && ( type == AST__STRING ) && ( nc = 0, ( 0 == astSscanf( keyword, "ISA" "%*1[" SEQ_CHARS "]" "%*1[" SEQ_CHARS "]%n", &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name to "isa" and extract the associated class name from the string value. Store both of these in dynamically allocated strings. */ *name = astString( "isa", 3 ); *val = UnPreQuote( (const char *) data, status ); /* "End" item. */ /* ----------- */ /* This is identified by a string value and a keyword of the form "ENDASTxx", where "xx" are characters encoding a sequence number. Don't accept the item if we are skipping over cards looking for a "Begin" item. */ } else if ( !skip && ( type == AST__STRING ) && ( nc = 0, ( 0 == astSscanf( keyword, "ENDAST" "%*1[" SEQ_CHARS "]" "%*1[" SEQ_CHARS "]%n", &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name to "end" and extract the associated class name from the string value. Store both of these in dynamically allocated strings. */ *name = astString( "end", 3 ); *val = UnPreQuote( (const char *) data, status ); /* The "end" item eill be followed by a footer of COMMENT cards. Mark these cards as having been used. */ ComBlock( this, 1, method, class, status ); /* Object or data item. */ /* -------------------- */ /* These are identified by a string, int, or double value, and a keyword ending in two characters encoding a sequence number. Don't accept the item if we are skipping over cards looking for a "Begin" item. */ } else if ( !skip && ( ( type == AST__STRING ) || ( type == AST__INT ) || ( type == AST__FLOAT ) ) && ( len > 2 ) && strchr( SEQ_CHARS, keyword[ len - 1 ] ) && strchr( SEQ_CHARS, keyword[ len - 2 ] ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name by removing the last two characters from the keyword and converting to lower case. Store this in a dynamically allocated string. */ *name = astString( keyword, len - 2 ); for ( i = 0; ( *name )[ i ]; i++ ) { ( *name )[ i ] = tolower( ( *name )[ i ] ); } /* Classify the data type. */ switch ( type ) { /* If the value is a string, test if it is zero-length. If so, this "null" value indicates an Object data item (whose definition follows), so leave the returned value pointer as NULL. Otherwise, we have a string data item, so extract its value and store it in a dynamically allocated string. */ case AST__STRING: if ( *( (char *) data ) ) { /* A long string value may be continued on subsequent CONTINUE cards. See if the current string may be continued. This is the case if the final non-blank character (before UnPreQuoting) is an ampersand. */ cont = ( ((char *) data)[ ChrLen( data, status ) - 1 ] == '&' ); /* If the string does not end with an ampersand, just UnPreQUote it and return a copy. */ if( !cont ) { *val = UnPreQuote( (const char *) data, status ); /* Otherwise, initialise the returned string to hold a copy of the keyword value. */ } else { nc = strlen( (const char *) data ); *val = astStore( NULL, (const char *) data, nc + 1 ); /* Loop round reading any subsequent CONTINUE cards. Leave the loop when the end-of-file is hit, or an error occurs. */ while( cont && MoveCard( this, 1, method, class, status ) && astOK ){ /* See if this is a CONTINUE card. If so, get its data pointer. */ if( CardType( this, status ) == AST__CONTINUE ){ data = CardData( this, NULL, status ); /* See if the CONTINUE card ends with an ampersand (i.e. if there is a possibility of there being any remaining CONTINUE cards). */ cont = ( ( (char *) data)[ ChrLen( data, status ) - 1 ] == '&' ); /* UnPreQUote it. */ upq = UnPreQuote( (const char *) data, status ); if( !astOK ) break; /* Expand the memory for the returned string to hold the new string. */ nn = strlen( upq ); *val = astRealloc( *val, nc + nn ); if( !astOK ) break; /* Copy the new string into the expanded memory, so that the first character of the new string over-writes the trailing ampersand currently in the buffer. */ strcpy( *val + nc - 1, upq ); /* Release the memory holding the UnPreQUoted string . */ upq = astFree( upq ); /* Update the current length of the returned string. */ nc += nn - 1; /* Mark the current card as having been read. */ MarkCard( this, status ); /* Report an error if this is not a CONTINUE card. */ } else { astError( AST__BADIN, "%s(%s): One or more " "FITS \"CONTINUE\" cards are missing " "after the card for keyword \"%s\".", status, method, class, keyword ); } } } } break; /* If the value is an int, format it and store the result in a dynamically allocated string. */ case AST__INT: (void) sprintf( buff, "%d", *( (int *) data ) ); *val = astString( buff, (int) strlen( buff ) ); break; /* If the value is a double, format it and store the result in a dynamically allocated string. */ case AST__FLOAT: (void) sprintf( buff, "%.*g", DBL_DIG, *( (double *) data ) ); CheckZero( buff, *( (double *) data ), 0, status ); *val = astString( buff, (int) strlen( buff ) ); break; } /* Anything else. */ /* -------------- */ /* If the input line didn't match any of the above and the "skip" flag is not set, then report an error.. */ } else if ( !skip ) { astError( AST__BADIN, "%s(%s): Cannot interpret the input data given by " "FITS keyword \"%s\".", status, method, class, keyword ); } /* Free any memory used to hold stripped string data. */ if( freedata ) newdata = (char *) astFree( (void *) newdata ); } /* Increment the current card. */ MoveCard( this, 1, method, class, status ); } /* If an error occurred, ensure that any allocated memory is freed and that NULL pointer values are returned. */ if ( !astOK ) { *name = astFree( *name ); *val = astFree( *val ); } /* Undefine macros local to this function. */ #undef BUFF_LEN } static int GetSkip( AstChannel *this_channel, int *status ) { /* * Name: * GetSkip * Purpose: * Obtain the value of the Skip attribute for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int GetSkip( AstChannel *this, int *status ) * Class Membership: * FitsChan member function (over-rides the protected astGetSkip * method inherited from the Channel class). * Description: * This function return the (boolean) integer value of the Skip * attribute for a FitsChan. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * The Skip attribute value. * Notes: * - This function modifies the default Skip value from 0 to 1 for * the benefit of the FitsChan class. This default value allows the * astRead method to skip over unrelated FITS keywords when * searching for the next Object to read. * - 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: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ int result; /* Result value to return */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* If the Skip attribute us set, obtain its value using the parent class method. */ if ( astTestSkip( this ) ) { result = (* parent_getskip)( this_channel, status ); /* Otherwise, supply a default value of 1. */ } else { result = 1; } /* Return the result. */ return result; } static int GetValue( AstFitsChan *this, const char *keyname, int type, void *value, int report, int mark, const char *method, const char *class, int *status ){ /* * Name: * GetValue * Purpose: * Obtain a FITS keyword value. * Type: * Private function. * Synopsis: * int GetValue( AstFitsChan *this, const char *keyname, int type, void *value, * int report, int mark, const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function gets a value for the specified keyword from the * supplied FitsChan, and stores it in the supplied buffer. Optionally, * the keyword is marked as having been read into an AST object so that * it is not written out when the FitsChan is deleted. * Parameters: * this * A pointer to the FitsChan containing the keyword values to be * read. * keyname * A pointer to a string holding the keyword name. * type * The FITS data type in which to return the keyword value. If the * stored value is not of the requested type, it is converted if * possible. * value * A pointer to a buffer of suitable size to receive the keyword * value. The supplied value is left unchanged if the keyword is * not found. * report * Should an error be reported if the keyword cannot be found, or * cannot be converted to the requested type? * mark * Should the card be marked as having been used? * method * A string holding the name of the calling method. * class * A string holding the object class. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the keyword does not exist in "this", or cannot be * converted to the requested type. One is returned otherwise. * Notes: * - An error is reported if the keyword value is undefined. * - A value of zero is returned if an error has already occurred, * or if an error occurs within this function. */ /* Local Variables: */ int icard; /* Current card index */ int ret; /* Returned value */ /* Check the status */ if( !astOK ) return 0; /* Save the current card index. */ icard = astGetCard( this ); /* Attempt to find the supplied keyword. */ ret = SearchCard( this, keyname, method, class, status ); /* If the keyword was found, convert the current card's data value and copy it to the supplied buffer. */ if( ret ){ if( CnvValue( this, type, 0, value, method, status ) ) { /* If required, mark it as having been read into an AST object. */ if( mark ) MarkCard( this, status ); /* If the value is undefined, report an error if "report" is non-zero. */ if( type == AST__UNDEF && report && astOK ) { ret = 0; astError( AST__FUNDEF, "%s(%s): FITS keyword \"%s\" has no value.", status, method, class, keyname ); } /* If the value could not be converted to the requested data, type report an error if reporting is enabled. */ } else { ret = 0; if( report && astOK ){ astError( AST__FTCNV, "%s(%s): Cannot convert FITS keyword '%s' to %s.", status, method, class, keyname, type_names[ type ] ); } } /* If the keyword was not found, report an error if "report" is non-zero. */ } else if( report && astOK ){ astError( AST__BDFTS, "%s(%s): Unable to find a value for FITS " "keyword \"%s\".", status, method, class, keyname ); } /* Reinstate the original current card index. */ astSetCard( this, icard ); /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the result. */ return ret; } static int GetValue2( AstFitsChan *this1, AstFitsChan *this2, const char *keyname, int type, void *value, int report, const char *method, const char *class, int *status ){ /* * Name: * GetValue2 * Purpose: * Obtain a FITS keyword value from one of two FitsChans. * Type: * Private function. * Synopsis: * int GetValue2( AstFitsChan *this1, AstFitsChan *this2, const char *keyname, * int type, void *value, int report, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function attempts to get a value for the specified keyword from * the first supplied FitsChan. If this fails (due to the FitsChan not * containing a value for the ketword) then an attempt is made to get * a value for the keyword from the second supplied FitsChan. * Parameters: * this1 * A pointer to the first FitsChan to be used. * this2 * A pointer to the second FitsChan to be used. * keyname * A pointer to a string holding the keyword name. * type * The FITS data type in which to return the keyword value. If the * stored value is not of the requested type, it is converted if * possible. * value * A pointer to a buffer of suitable size to receive the keyword * value. The supplied value is left unchanged if the keyword is * not found. * report * Should an error be reported if the keyword cannot be found, or * cannot be converted to the requested type? * method * A string holding the name of the calling method. * class * A string holding the object class. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the keyword does not exist in either FitsChan, or cannot be * converted to the requested type. One is returned otherwise. * Notes: * - A value of zero is returned if an error has already occurred, * or if an error occurs within this function. * - If the card is found in the first FitsChan, it is not marked as * having been used. If the card is found in the second FitsChan, it is * marked as having been used. */ /* Local Variables: */ int ret; /* Returned value */ /* Check the status */ if( !astOK ) return 0; /* Try the first FitsChan. If this fails try the second. Do not report an error if the keyword is not found in the first FitsChan (this will be done, if required, once the second FitsChan has been searched). */ ret = GetValue( this1, keyname, type, value, 0, 0, method, class, status ); if( ! ret ) { ret = GetValue( this2, keyname, type, value, report, 1, method, class, status ); } /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the result. */ return ret; } static int HasAIPSSpecAxis( AstFitsChan *this, const char *method, const char *class, int *status ){ /* * Name: * HasAIPSSpecAxis * Purpose: * Does the FitsChan contain an AIPS spectral CTYPE keyword? * Type: * Private function. * Synopsis: * int HasAIPSSpecAxis( AstFitsChan *this, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function returns a non-zero value if the FitsCHan contains a * CTYPE value which conforms to the non-standard system used by AIPS. * Parameters: * this * A pointer to the FitsChan to be used. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if an AIPS spectral CTYPE keyword was found. */ /* Local Variables: */ char *assys; /* AIPS standard of rest type */ char *astype; /* AIPS spectral type */ char *cval; /* Pointer to character string */ int j; /* Current axis index */ int jhi; /* Highest axis index with a CTYPE */ int jlo; /* Lowest axis index with a CTYPE */ int ret; /* Returned value */ /* Initialise */ ret = 0; /* Check the status */ if( !astOK ) return ret; /* If the FitsChan contains any CTYPE values, convert the bounds from one-based to zero-based, and loop round them all. */ if( astKeyFields( this, "CTYPE%1d", 1, &jhi, &jlo ) ) { jlo--; jhi--; for( j = jlo; j <= jhi; j++ ) { /* Get the next CTYPE value. If found, see if it is an AIPS spectral CTYPE value. */ if( GetValue( this, FormatKey( "CTYPE", j + 1, -1, ' ', status ), AST__STRING, (void *) &cval, 0, 0, method, class, status ) ){ if( IsAIPSSpectral( cval, &astype, &assys, status ) ) { ret = 1; break; } } } } /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the result. */ return ret; } static int HasCard( AstFitsChan *this, const char *name, const char *method, const char *class, int *status ){ /* * Name: * HasCard * Purpose: * Check if the FitsChan contains a specified keyword. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int HasCard( AstFitsChan *this, const char *name, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a non-zero value if the FitsChan contains the given keyword, * and zero otherwise. The current card is unchanged. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a string holding the keyword name. * method * Pointer to string holding name of calling method. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if a card was found refering to the given * keyword. Otherwise zero is returned. */ /* Check the supplied pointers (we can rely on astMapHasKey to check the inherited status). */ if( !name || !this || !this->keywords ) return 0; /* Search the KeyMap holding the keywords currently in the FitsChan, returning non-zero if the keyword was found. A KeyMap is used because it uses a hashing algorithm to find the entries and is therefore a lot quicker than searching through the list of linked FitsCards. */ return astMapHasKey( this->keywords, name ); } void astInitFitsChanVtab_( AstFitsChanVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitFitsChanVtab * Purpose: * Initialise a virtual function table for a FitsChan. * Type: * Protected function. * Synopsis: * #include "fitschan.h" * void astInitFitsChanVtab( AstFitsChanVtab *vtab, const char *name ) * Class Membership: * FitsChan vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the FitsChan class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstChannelVtab *channel; /* Pointer to Channel component of Vtab */ char buf[ 100 ]; /* Buffer large enough to store formatted INT_MAX */ /* 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. */ astInitChannelVtab( (AstChannelVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAFitsChan) 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 = &(((AstChannelVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->PutCards = PutCards; vtab->PutFits = PutFits; vtab->DelFits = DelFits; vtab->GetTables = GetTables; vtab->PutTables = PutTables; vtab->PutTable = PutTable; vtab->TableSource = TableSource; vtab->SetTableSource = SetTableSource; vtab->RemoveTables = RemoveTables; vtab->PurgeWCS = PurgeWCS; vtab->RetainFits = RetainFits; vtab->FindFits = FindFits; vtab->KeyFields = KeyFields; vtab->ReadFits = ReadFits; vtab->ShowFits = ShowFits; vtab->WriteFits = WriteFits; vtab->EmptyFits = EmptyFits; vtab->FitsEof = FitsEof; vtab->GetFitsCF = GetFitsCF; vtab->GetFitsCI = GetFitsCI; vtab->GetFitsF = GetFitsF; vtab->GetFitsI = GetFitsI; vtab->GetFitsL = GetFitsL; vtab->TestFits = TestFits; vtab->GetFitsS = GetFitsS; vtab->GetFitsCN = GetFitsCN; vtab->FitsGetCom = FitsGetCom; vtab->SetFitsCom = SetFitsCom; vtab->SetFitsCF = SetFitsCF; vtab->SetFitsCI = SetFitsCI; vtab->SetFitsF = SetFitsF; vtab->SetFitsI = SetFitsI; vtab->SetFitsL = SetFitsL; vtab->SetFitsU = SetFitsU; vtab->SetFitsS = SetFitsS; vtab->SetFitsCN = SetFitsCN; vtab->SetFitsCM = SetFitsCM; vtab->ClearCard = ClearCard; vtab->TestCard = TestCard; vtab->SetCard = SetCard; vtab->GetCard = GetCard; vtab->ClearFitsDigits = ClearFitsDigits; vtab->TestFitsDigits = TestFitsDigits; vtab->SetFitsDigits = SetFitsDigits; vtab->GetFitsDigits = GetFitsDigits; vtab->ClearFitsAxisOrder = ClearFitsAxisOrder; vtab->TestFitsAxisOrder = TestFitsAxisOrder; vtab->SetFitsAxisOrder = SetFitsAxisOrder; vtab->GetFitsAxisOrder = GetFitsAxisOrder; vtab->ClearDefB1950 = ClearDefB1950; vtab->TestDefB1950 = TestDefB1950; vtab->SetDefB1950 = SetDefB1950; vtab->GetDefB1950 = GetDefB1950; vtab->ClearTabOK = ClearTabOK; vtab->TestTabOK = TestTabOK; vtab->SetTabOK = SetTabOK; vtab->GetTabOK = GetTabOK; vtab->ClearCarLin = ClearCarLin; vtab->TestCarLin = TestCarLin; vtab->SetCarLin = SetCarLin; vtab->GetCarLin = GetCarLin; vtab->ClearPolyTan = ClearPolyTan; vtab->TestPolyTan = TestPolyTan; vtab->SetPolyTan = SetPolyTan; vtab->GetPolyTan = GetPolyTan; vtab->ClearIwc = ClearIwc; vtab->TestIwc = TestIwc; vtab->SetIwc = SetIwc; vtab->GetIwc = GetIwc; vtab->ClearWarnings = ClearWarnings; vtab->TestWarnings = TestWarnings; vtab->SetWarnings = SetWarnings; vtab->GetWarnings = GetWarnings; vtab->GetCardType = GetCardType; vtab->GetCardName = GetCardName; vtab->GetCardComm = GetCardComm; vtab->GetNcard = GetNcard; vtab->GetNkey = GetNkey; vtab->GetAllWarnings = GetAllWarnings; vtab->ClearEncoding = ClearEncoding; vtab->TestEncoding = TestEncoding; vtab->SetEncoding = SetEncoding; vtab->GetEncoding = GetEncoding; vtab->ClearClean = ClearClean; vtab->TestClean = TestClean; vtab->SetClean = SetClean; vtab->GetClean = GetClean; vtab->ClearCDMatrix = ClearCDMatrix; vtab->TestCDMatrix = TestCDMatrix; vtab->SetCDMatrix = SetCDMatrix; vtab->GetCDMatrix = GetCDMatrix; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; channel = (AstChannelVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_write = channel->Write; channel->Write = Write; parent_read = channel->Read; channel->Read = Read; parent_getskip = channel->GetSkip; channel->GetSkip = GetSkip; parent_getfull = channel->GetFull; channel->GetFull = GetFull; channel->WriteBegin = WriteBegin; channel->WriteIsA = WriteIsA; channel->WriteEnd = WriteEnd; channel->WriteInt = WriteInt; channel->WriteDouble = WriteDouble; channel->WriteString = WriteString; channel->WriteObject = WriteObject; channel->GetNextData = GetNextData; parent_setsourcefile = channel->SetSourceFile; channel->SetSourceFile = SetSourceFile; /* Declare the class dump, copy and delete functions.*/ astSetDump( vtab, Dump, "FitsChan", "I/O channels to FITS files" ); astSetCopy( (AstObjectVtab *) vtab, Copy ); astSetDelete( (AstObjectVtab *) vtab, Delete ); /* Max number of characters needed to format an int. */ LOCK_MUTEX4 sprintf( buf, "%d", INT_MAX ); int_dig = strlen( buf ); /* Create a pair of MJD TimeFrames which will be used for converting to and from TDB. */ astBeginPM; if( !tdbframe ) tdbframe = astTimeFrame( "system=MJD,timescale=TDB", status ); if( !timeframe ) timeframe = astTimeFrame( "system=MJD", status ); astEndPM; UNLOCK_MUTEX4 /* 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 InsCard( AstFitsChan *this, int overwrite, const char *name, int type, void *data, const char *comment, const char *method, const char *class, int *status ){ /* * Name: * InsCard * Purpose: * Inserts a card into a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void InsCard( AstFitsChan *this, int overwrite, const char *name, * int type, void *data, const char *comment, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Either appends a new card to a FitsChan, or over-writes an existing * card, holding the supplied keyword name, value and comment. * Parameters: * this * Pointer to the FitsChan containing the filters to apply to the * keyword name. If a NULL pointer is supplied, no filtering is applied. * overwrite * If non-zero, the new card over-writes the current card given by * the "Card" attribute, and the current card is incremented so * that it refers to the next card. Otherwise, the new card is * inserted in front of the current card and the current card is * left unchanged. * name * Pointer to a string holding the keyword name of the new card. * type * An integer value representing the data type of the keyword. * data * Pointer to the data associated with the keyword. * comment * Pointer to a null-terminated string holding a comment. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - An error is reported if an attempt is made to change the data type * of an existing card. * - If a type of AST__COMMENT is supplied, then any data value (of any * type) associated with an existing card is left unchanged. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ int flags; /* Flags to assign to new card */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* If the current card is to be over-written, delete the current card (the next card in the list, if any, will become the new current card). */ if( overwrite ) DeleteCard( this, method, class, status ); /* If requested, set both NEW flags for the new card. */ flags = ( mark_new ) ? ( NEW1 | NEW2 ): 0; /* Insert the new card into the list, just before the current card. */ NewCard( this, name, type, data, comment, flags, status ); } static int IRAFFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * IRAFFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-IRAF encoding. * Type: * Private function. * Synopsis: * int IRAFFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-IRAF encoding. * * IRAF encoding is like FITS-WCS encoding but with the following * restrictions: * * 1) The celestial projection must not have any projection parameters * which are not set to their default values. The one exception to this * is that SIN projections are acceptable if the associated projection * parameter PV_1 is zero and PV_2 = cot( reference point * latitude). This is encoded using the string "-NCP". The SFL projection * is encoded using the string "-GLS". Note, the original IRAF WCS * system only recognised a small subset of the currently available * projections, but some more recent IRAF-like software recognizes some * of the new projections included in the FITS-WCS encoding. * * 2) The celestial axes must be RA/DEC, galactic or ecliptic. * * 3) LONPOLE and LATPOLE cannot be used. * * 4) Only primary axis descriptions are written out. * * 5) RADECSYS is used in place of RADESYS. * * 6) PC/CDELT keywords are not allowed (CD must be used) * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ char *comm; /* Pointer to comment string */ char *cval; /* Pointer to string keyword value */ char combuf[80]; /* Buffer for FITS card comment */ char lattype[MXCTYPELEN];/* Latitude axis CTYPE */ char lontype[MXCTYPELEN];/* Longitude axis CTYPE */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ double cdelt; /* A CDELT value */ double fd; /* Fraction of a day */ double mjd99; /* MJD at start of 1999 */ double p1, p2; /* Projection parameters */ double val; /* General purpose value */ int axlat; /* Index of latitude FITS WCS axis */ int axlon; /* Index of longitude FITS WCS axis */ int axspec; /* Index of spectral FITS WCS axis */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int naxis; /* No. of axes */ int ok; /* Is FitsSTore OK for IRAF encoding? */ int prj; /* Projection type */ int ret; /* Returned value. */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* First check that the values in the FitsStore conform to the requirements of the IRAF encoding. Assume they do to begin with. */ ok = 1; /* Just do primary axes. */ s = ' '; /* Look for the primary celestial and spectral axes. */ FindLonLatSpecAxes( store, s, &axlon, &axlat, &axspec, method, class, status ); /* If both longitude and latitude axes are present and thereis no spectral axis...*/ if( axlon >= 0 && axlat >= 0 ) { /* Get the CTYPE values for both axes. */ cval = GetItemC( &(store->ctype), axlon, 0, s, NULL, method, class, status ); if( !cval ) return ret; strcpy( lontype, cval ); cval = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); if( !cval ) return ret; strcpy( lattype, cval ); /* Extract the projection type as specified by the last 4 characters in the CTYPE keyword value. */ prj = astWcsPrjType( lattype + 4 ); /* Check the projection type is OK. Assume not initially. */ ok = 0; /* FITS-IRAF cannot handle the AST-specific TPN projection. */ if( prj == AST__TPN || prj == AST__WCSBAD ) { ok = 0; /* SIN projections are handled later. */ } else if( prj != AST__SIN ){ /* There must be no projection parameters. */ if( GetMaxJM( &(store->pv), ' ', status ) == -1 ) ok = 1; /* Change the new SFL projection code to to the older equivalent GLS */ if( prj == AST__SFL ){ (void) strcpy( lontype + 4, "-GLS" ); (void) strcpy( lattype + 4, "-GLS" ); } /* SIN projections are only acceptable if the associated projection parameters are both zero, or if the first is zero and the second = cot( reference point latitude ) (the latter case is equivalent to the old NCP projection). */ } else { p1 = GetItem( &( store->pv ), axlat, 1, s, NULL, method, class, status ); p2 = GetItem( &( store->pv ), axlat, 2, s, NULL, method, class, status ); if( p1 == AST__BAD ) p1 = 0.0; if( p2 == AST__BAD ) p2 = 0.0; val = GetItem( &( store->crval ), axlat, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { if( p1 == 0.0 ) { if( p2 == 0.0 ) { ok = 1; } else if( fabs( p2 ) >= 1.0E14 && val == 0.0 ){ ok = 1; (void) strcpy( lontype + 4, "-NCP" ); (void) strcpy( lattype + 4, "-NCP" ); } else if( fabs( p2*tan( AST__DD2R*val ) - 1.0 ) < 0.01 ){ ok = 1; (void) strcpy( lontype + 4, "-NCP" ); (void) strcpy( lattype + 4, "-NCP" ); } } } } /* Identify the celestial coordinate system from the first 4 characters of the longitude CTYPE value. Only RA, galactic longitude, and ecliptic longitude can be stored using FITS-IRAF. */ if( strncmp( lontype, "RA--", 4 ) && strncmp( lontype, "GLON", 4 ) && strncmp( lontype, "ELON", 4 ) ) ok = 0; /* If the physical Frame requires a LONPOLE or LATPOLE keyword, it cannot be encoded using FITS-IRAF. */ if( GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ) != AST__BAD || GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ) != AST__BAD ) ok = 0; /* If there are no celestial axes, the physical Frame can be written out using FITS-IRAF. */ } else { ok = 1; } /* Save the number of axes */ naxis = GetMaxJM( &(store->crpix), ' ', status ) + 1; /* If this is different to the value of NAXIS abort since this encoding does not support WCSAXES keyword. */ if( naxis != store->naxis ) ok = 0; /* Return if the FitsStore does not conform to IRAF encoding. */ if( !ok ) return ret; /* Get and save CRPIX for all pixel axes. These are required, so return if they are not available. */ for( i = 0; i < naxis; i++ ){ val = GetItem( &(store->crpix), 0, i, s, NULL, method, class, status ); if( val == AST__BAD ) return ret; sprintf( combuf, "Reference pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRPIX", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } /* Get and save CRVAL for all intermediate axes. These are required, so return if they are not available. */ for( j = 0; j < naxis; j++ ){ val = GetItem( &(store->crval), j, 0, s, NULL, method, class, status ); if( val == AST__BAD ) return ret; sprintf( combuf, "Value at ref. pixel on axis %d", j + 1 ); SetValue( this, FormatKey( "CRVAL", j + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } /* Get and save CTYPE for all intermediate axes. These are required, so return if they are not available. Use the potentially modified versions saved above for the celestial axes. */ for( i = 0; i < naxis; i++ ){ if( i == axlat ) { cval = lattype; } else if( i == axlon ) { cval = lontype; } else { cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( !cval ) return ret; } if( strlen(cval) > 4 && !strcmp( cval + 4, "-TAB" ) ) return ret; comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } SetValue( this, FormatKey( "CTYPE", i + 1, -1, s, status ), &cval, AST__STRING, comm, status ); } /* CD matrix (the product of the CDELT and PC matrices). */ for( i = 0; i < naxis; i++ ){ cdelt = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdelt == AST__BAD ) cdelt = 1.0; for( j = 0; j < naxis; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdelt; if( val != 0.0 ) { SetValue( this, FormatKey( "CD", i + 1, j + 1, s, status ), &val, AST__FLOAT, "Transformation matrix element", status ); } } } /* Get and save CUNIT for all intermediate axes. These are NOT required, so do not return if they are not available. */ for( i = 0; i < naxis; i++ ){ cval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( cval ) { sprintf( combuf, "Units for axis %d", i + 1 ); SetValue( this, FormatKey( "CUNIT", i + 1, -1, s, status ), &cval, AST__STRING, combuf, status ); } } /* Get and save RADECSYS. This is NOT required, so do not return if it is not available. */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, "RADECSYS", &cval, AST__STRING, "Reference frame for RA/DEC values", status ); /* Reference equinox */ val = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "EQUINOX", &val, AST__FLOAT, "Epoch of reference equinox", status ); /* Date of observation */ val = GetItem( &(store->mjdobs), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD ) { /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", (void *) &cval, AST__STRING, "Date of observation", status ); } /* If we get here we have succeeded. */ ret = 1; /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ret : 0; } static int IsMapLinear( AstMapping *smap, const double lbnd_in[], const double ubnd_in[], int coord_out, int *status ) { /* * Name: * IsMapLinear * Purpose: * See if a specified Mapping output is linearly related to the * Mapping inputs. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int IsMapLinear( AstMapping *smap, const double lbnd_in[], * const double ubnd_in[], int coord_out, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a flag indicating if the specified output of the supplied * Mapping is a linear function of the Mapping inputs. A set of output * positions are created which are evenly spaced along the specified * output coordinate. The spacing is chosen so that the entire range * of the output coordinate is covered in 20 steps. The other output * coordinates are held fixed at arbitrary values (actually, values * at which the specified output coordinate achieves its minimum value). * This set of output positions is transformed into the corresponding * set of input coordinates using the inverse of the supplied Mapping. * A least squares linear fit is then made which models each input * coordinate as a linear function of the specified output coordinate. * The residual at every point in this fit must be less than some * small fraction of the total range of the corresponding input * coordinate for the Mapping to be considered linear. * Parameters: * smap * Pointer to the Mapping. * lbnd_in * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the lower bound * of the input box in each input dimension. * ubnd_in * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the upper bound * of the input box in each input dimension. * coord_out * The zero-based index of the Mapping output which is to be checked. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the specified Mapping output is linear. Zero otherwise. */ /* Local Constants: */ #define NP 20 /* Local Variables: */ AstMapping *map; AstPointSet *pset1; AstPointSet *pset2; double **ptr1; double **ptr2; double *p; double *s; double *xl; double c; double d; double delta; double in_lbnd; double in_ubnd; double lbnd_out; double m; double p0; double pv; double sn; double sp; double sps; double ss2; double ss; double sv; double tol; double ubnd_out; int *ins; int boxok; int i; int j; int nin; int nout; int oldrep; int ret; /* Initialise */ ret = 0; /* Check inherited status */ if( !astOK ) return ret; /* Attempt to split off the required output (in case any of the other outputs are associated with Mappings that do not have an inverse). */ astInvert( smap ); ins = astMapSplit( smap, 1, &coord_out, &map ); astInvert( smap ); /* If successful, check that the output is fed by only one input. */ if( ins ) { if( astGetNin( map ) == 1 ) { /* If so, invert the map so that it goes from pixel to wcs, and then modify the supplied arguments so that they refer to the single required axis. */ astInvert( map ); lbnd_in += coord_out; ubnd_in += coord_out; coord_out = 0; /* If the output was fed by more than one input, annul the split mapping and use the supplied nmapping. */ } else { (void) astAnnul( map ); map = astClone( smap ); } ins = astFree( ins ); /* If the supplied Mapping could not be split, use the supplied nmapping. */ } else { map = astClone( smap ); } /* Check the Mapping is defined in both directions. */ if( astGetTranForward( map ) && astGetTranInverse( map ) ) { /* Allocate resources. */ nin = astGetNin( map ); nout = astGetNout( map ); xl = astMalloc( sizeof( double )*(size_t) nin ); pset1 = astPointSet( NP, nin, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( NP, nout, "", status ); ptr2 = astGetPoints( pset2 ); /* Call astMapBox in a new error reporting context. */ boxok = 0; if( astOK ) { /* Temporarily switch off error reporting so that no report is made if astMapBox cannot find a bounding box (which can legitimately happen with some non-linear Mappings). */ oldrep = astReporting( 0 ); /* Find the upper and lower bounds on the specified Mapping output. This also returns the input coords of a point at which the required output has its lowest value. */ astMapBox( map, lbnd_in, ubnd_in, 1, coord_out, &lbnd_out, &ubnd_out, xl, NULL ); /* If the box could not be found, clear the error status and pass on. */ if( !astOK ) { astClearStatus; /* If the box was found OK, flag this and check if the bounds are equal. If so we cannot use them. In this case create new bounds. */ } else { boxok = 1; if( astEQUAL( lbnd_out, ubnd_out ) ) { m = 0.5*( lbnd_out + ubnd_out ); if( fabs( m ) > 1.0E-15 ) { lbnd_out = 0.9*m; ubnd_out = 1.1*m; } else { lbnd_out = -1.0; ubnd_out = 1.0; } } } /* Re-instate error reporting. */ astReporting( oldrep ); } /* Check pointers can be used safely and a box was obtained. */ if( astOK && boxok ) { /* Transform the input position returned by astMapBox using the supplied Mapping to get the corresponding output position. Fill all unused elements of the PointSet with AST__BAD. */ for( i = 0; i < nin; i++ ){ p = ptr1[ i ]; *(p++) = xl[ i ]; for( j = 1; j < NP; j++ ) *(p++) = AST__BAD; } (void) astTransform( map, pset1, 1, pset2 ); /* Now create a set of NP points evenly spaced in output coordinates. The first point is at the output position found above. Each subsequent point is incremented by a fixed amount along the specified output coordinate (the values on all other output coordinates is held fixed). */ delta = ( ubnd_out - lbnd_out )/ ( NP - 1 ); for( i = 0; i < nout; i++ ){ p = ptr2[ i ]; if( i == coord_out ) { for( j = 0; j < NP; j++ ) *(p++) = lbnd_out + j*delta; } else { p0 = p[ 0 ]; for( j = 0; j < NP; j++ ) *(p++) = p0; } } /* Transform these output positions into input positions using the inverse Mapping. */ (void) astTransform( map, pset2, 0, pset1 ); /* Do a least squares fit to each input coordinate. Each fit gives the corresponding input coordinate value as a linear function of the specified output coordinate value. Note, linear function should never produce bad values so abort if a bad value is found. */ ret = 1; s = ptr2[ coord_out ]; for( i = 0; i < nin; i++ ) { p = ptr1[ i ]; /* Form the required sums. Also find the largest and smallest input coordinate value achieved. */ sp = 0.0; ss = 0.0; sps = 0.0; sn = 0.0; ss2 = 0.0; in_lbnd = DBL_MAX; in_ubnd = DBL_MIN; for( j = 0; j < NP; j++ ) { sv = s[ j ]; pv = p[ j ]; if( pv != AST__BAD && sv != AST__BAD ) { sp += pv; ss += sv; sps += pv*sv; sn += 1.0; ss2 += sv*sv; if( pv < in_lbnd ) in_lbnd = pv; if( pv > in_ubnd ) in_ubnd = pv; } else { sn = 0.0; break; } } /* Ignore input axes which are independant of the output axis. */ if( !astEQUAL( in_lbnd, in_ubnd ) ) { /* Calculate the constants "input coord = m*output coord + c" */ d = ss*ss - sn*ss2; if( sn > 0.0 && d != 0.0 ) { m = ( sp*ss - sps*sn )/d; c = ( sps*ss - sp*ss2 )/d; /* Subtract off the fit value form the "p" values to get the residuals of the fit. */ for( j = 0; j < NP; j++ ) p[ j ] -= m*s[ j ] + c; /* We now do a least squares fit to the residuals. This second fit is done because the first least squares fit sometimes leaves the residuals with a distinct non-zero gradient. We do not need to worry about bad values here since we have checked above that there are no bad values. Also we do not need to recalculate sums which only depend on the "s" values since they have not changed. */ sp = 0.0; sps = 0.0; for( j = 0; j < NP; j++ ) { pv = p[ j ]; sp += pv; sps += pv*s[ j ]; } /* Find the constants in "input residual = m*output coord + c" equation. */ m = ( sp*ss - sps*sn )/d; c = ( sps*ss - sp*ss2 )/d; /* Subtract off the fit value form the "p residuals" values to get the residual redisuals of the fit. */ for( j = 0; j < NP; j++ ) p[ j ] -= m*s[ j ] + c; /* The requirement for a linear relationship is that the absolute residual between the input coord produced by the above linear fit and the input coord produced by the actual Mapping should be less than some small fraction of the total range of input coord value, at every point. Test this. */ tol = 1.0E-7*( in_ubnd - in_lbnd ); for( j = 0; j < NP; j++ ) { if( fabs( p[ j ] ) > tol ) { ret = 0; break; } } } else { ret = 0; } } if( !ret ) break; } } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); xl = astFree( xl ); } map = astAnnul( map ); /* Return the answer. */ return ret; } static AstMapping *IsMapTab1D( AstMapping *map, double scale, const char *unit, AstFrame *wcsfrm, double *dim, int iax, int iwcs, AstFitsTable **table, int *icolmain, int *icolindex, int *interp, int *status ){ /* * Name: * IsMapTab1D * Purpose: * See if a specified Mapping output is related to a single Mapping input * via a FITS -TAB algorithm. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *IsMapTab1D( AstMapping *map, double scale, const char *unit, * AstFrame *wcsfrm, double *dim, int iax, * int iwcs, AstFitsTable **table, int *icolmain, * int *icolindex, int *interp, int *status ) * Class Membership: * FitsChan member function. * Description: * A specified axis of the supplied Mapping is tested to see if it * can be represented by the -TAB alogirithm described in FITS-WCS * paper III. If the test is passed, a Mapping is returned from the * specified WCS axis to the corresponding psi axis. A FitsTable is * also created holding the information to be stored in the * corresponding FITS binary table. * * Note, when creating a -TAB header, AST uses grid coords for the psi * axis. See FITS-WCS paper III section 6.1.2 for a definition of the * psi axes. * Parameters: * map * Pointer to the Mapping from pixel coords to WCS coords. * scale * A scale factor by which to multiply the axis values stored in the * returned FitsTable. Note, the returned Mapping is unaffected by * this scaling factor. * unit * Pointer to the unit string to store with the coords column. If * NULL, the unit string is extracted form the supplied WCS Frame. * wcsfrm * Pointer to a Frame describing WCS coords. * dim * An array holding the array dimensions in pixels. AST__BAD should * be supplied for any unknown dimensions. * iax * The zero-based index of the Mapping output which is to be checked. * iwcs * The zero-based index of the corresponding FITS WCS axis. * table * Pointer to a location holding a pointer to the FitsTable describing * the -TAB look-up table. If "*table" is NULL on entry, a new * FitsTable will be created and returned, otherwise the supplied * FitsTable is used. * icolmain * The one-based index of the column within "*table" that holds the * main data array. * icolindex * The one-based index of the column within "*table" that holds the * index vector. Returned equal to -1 if no index is added to the * table (i.e. if the index is a unt index). * interp * The interpolation method (0=linear, other=nearest neighbour). * status * Pointer to the inherited status variable. * Returned Value: * If the specified "map" output can be described using the -TAB * algorithm of FITS-WCS paper III, then a 1-input/1-output Mapping * from the specified WCS axis to the corresponding psi axis (which is * assumed to be equal to grid coords) is returned. NULL is returned * otherwise, of if an error occurs. */ /* Local Variables: */ AstCmpMap *cm; /* CmpMap pointer */ AstMapping **map_list; /* Mapping array pointer */ AstMapping *postmap; /* Total Mapping after LutMap */ AstMapping *premap; /* Total Mapping before LutMap */ AstMapping *ret; /* Returned WCS axis Mapping */ AstMapping *tmap; /* Temporary Mapping */ AstPermMap *pm; /* PermMap pointer */ char cellname[ 20 ]; /* Buffer for cell name */ char colname[ 20 ]; /* Buffer for column name */ double *lut; /* Pointer to table of Y values */ double *work1; /* Pointer to work array */ double *work2; /* Pointer to work array */ double inc; /* X increment between table entries */ double start; /* X value at first table entry */ double v[ 2 ]; /* Y values at start and end of interval */ double x[ 2 ]; /* X values at start and end of interval */ int *ins; /* Array of "map" input indices */ int *invert_list; /* Invert array pointer */ int *outs; /* Array of "map" output indices */ int dims[ 2 ]; /* Dimensions of the tab coords array */ int iin; /* Index of Mapping input */ int ilut; /* Index of the LutMap within the mappings list */ int imap; /* Index of current Mapping in list */ int iout; /* Index of Mapping output */ int jout; /* Index of Mapping output */ int nin; /* Number of Mapping inputs */ int nlut; /* Number of elements in "lut" array */ int nmap; /* Number of Mappings in the list */ int nout; /* Number of Mapping outputs */ int ok; /* Were columns added to the table? */ int old_invert; /* Original value for Mapping's Invert flag */ int outperm; /* Index of input that feeds the single output */ /* Initialise */ ret = NULL; *icolmain = -1; *icolindex = -1; *interp = 0; /* Check inherited status */ if( !astOK ) return ret; /* Ensure we have aunit string. */ if( !unit ) unit = astGetUnit( wcsfrm, iax ); /* Check that the requested mapping output is fed by only one mapping input, identify that input, and extract the input->output mapping from the total mapping. Since astMapSplit splits off a specified input, we need to invert the Mapping first so we can split off a specified output. */ astInvert( map ); ins = astMapSplit( map, 1, &iax, &ret ); astInvert( map ); /* If the Mapping could not be split, try a different approach in which each input is checked in turn to see if it feeds the specified output. */ if( !ins ) { /* Loop round each input of "map". */ nin = astGetNin( map ); for( iin = 0; iin < nin && !ins; iin++ ) { /* Attempt to find a group of outputs (of "map") that are fed by just this one input. */ outs = astMapSplit( map, 1, &iin, &ret ); /* If successful, "ret" will be a Mapping with one input corresponding to input "iin" of "map, and one or more outputs. We loop round these outputs to see if any of them correspond to output "iax" of "map". */ if( outs ) { nout = astGetNout( ret ); for( iout = 0; iout < nout; iout++ ) { if( outs[ iout ] == iax ) break; } /* Did input "iin" feed the output "iax" (and possibly other outputs)? */ if( iout < nout ) { /* The "ret" Mapping is now a 1-input (pixel) N-output (WCS) Mapping in which output "iout" corresponds to output "iax" of Mapping. To be compatible with the previous approach, we want "ret" to be a 1-input (WCS) to 1-output (pixel) Mapping in which the input corresponds to output "iax" of Mapping. To get "ret" into this form, we first append a PermMap to "ret" that selects a single output ("iout"), and then invert the whole CmpMap. */ for( jout = 0; jout < nout; jout++ ) { outs[ jout ] = -1; } outs[ iout ] = 0; outperm = iout; pm = astPermMap( nout, outs, 1, &outperm, NULL, "", status ); cm = astCmpMap( ret, pm, 1, " ", status ); (void) astAnnul( ret ); pm = astAnnul( pm ); ret = (AstMapping *) cm; astInvert( ret ); /* The earlier approach leves ins[ 0 ] holding the index of the input to "map" that feeds output iax. Ensure we have this too. */ ins = outs; ins[ 0 ] = iin; /* Free resources if the current input did not feed the required output. */ } else { outs = astFree( outs ); ret = astAnnul( ret ); } } } } /* If the Mapping still could not be split, try again on a copy of the Mapping in which all PermMaps provide an alternative implementation of the astMapSplit method. */ if( !ins ) { astInvert( map ); tmap = astCopy( map ); ChangePermSplit( tmap, status ); ins = astMapSplit( tmap, 1, &iax, &ret ); tmap = astAnnul( tmap ); astInvert( map ); } /* Assume the Mapping cannot be represented by -TAB */ ok = 0; /* Check a Mapping was returned by astMapSplit. If so, it will be the mapping from the requested output of "map" (the WCS axis) to the corresponding input(s) (grid axes). Check only one "map" input feeds the requested output. */ if( ins && ret && astGetNout( ret ) == 1 ) { /* Invert the Mapping so that the input is grid coord and the output is WCS coord. */ astInvert( ret ); /* We now search the "ret" mapping for a non-inverted LutMap, splitting ret up into three serial components: 1) the mappings before the LutMap, 2) the LutMap itself, and 3) the mappings following the LutMap. First, decompose the mapping into a list of series mappings. */ map_list = NULL; invert_list = NULL; nmap = 0; astMapList( ret, 1, astGetInvert( ret ), &nmap, &map_list, &invert_list ); /* Search the list for a non-inverted LutMap. */ ilut = -1; for( imap = 0; imap < nmap; imap++ ) { if( astIsALutMap( map_list[ imap ] ) && !(invert_list[ imap ]) ) { ilut = imap; break; } } /* If a LutMap was found, combine all Mappings before the LutMap into a single Mapping. Remember to set the Mapping Invert flags temporarily to the values used within the CmpMap. */ if( ilut >= 0 ) { premap = (AstMapping *) astUnitMap( 1, " ", status ); for( imap = 0; imap < ilut; imap++ ) { old_invert = astGetInvert( map_list[ imap ] ); astSetInvert( map_list[ imap ], invert_list[ imap ] ); tmap = (AstMapping *) astCmpMap( premap, map_list[ imap ], 1, " ", status ); astSetInvert( map_list[ imap ], old_invert ); (void) astAnnul( premap ); premap = tmap; } /* Also combine all Mappings after the LutMap into a single Mapping, setting the Mapping Invert flags temporarily to the values used within the CmpMap. */ postmap = (AstMapping *) astUnitMap( 1, " ", status ); for( imap = ilut + 1; imap < nmap; imap++ ) { old_invert = astGetInvert( map_list[ imap ] ); astSetInvert( map_list[ imap ], invert_list[ imap ] ); tmap = (AstMapping *) astCmpMap( postmap, map_list[ imap ], 1, " ", status ); astSetInvert( map_list[ imap ], old_invert ); (void) astAnnul( postmap ); postmap = tmap; } /* Get the table of values, and other attributes, from the LutMap. */ lut = astGetLutMapInfo( map_list[ ilut ], &start, &inc, &nlut ); *interp = astGetLutInterp( map_list[ ilut ] ); /* If required, create a FitsTable to hold the returned table info. */ if( ! *table ) *table = astFitsTable( NULL, "", status ); ok = 1; /* Define the properties of the column in the FitsTable that holds the main coordinate array. Points on a WCS axis are described by a single value (wavelength, frequency, or whatever), but the coords array has to be 2-dimensional, with an initial degenerate axis, as required by FITS-WCS paper III. */ dims[ 0 ] = 1; dims[ 1 ] = nlut; sprintf( colname, "COORDS%d", iwcs + 1 ); astAddColumn( *table, colname, AST__DOUBLETYPE, 2, dims, unit ); /* Get the one-based index of the column just added to the table. */ *icolmain = astGetNcolumn( *table ); /* Get workspace. */ work1 = astMalloc( nlut*sizeof( double ) ); if( astOK ) { /* Transform the LutMap table values using the post-lutmap mapping to get the list of WCS values in AST units. */ astTran1( postmap, nlut, lut, 1, work1 ); /* Convert them to FITS units (e.g. celestial axis values should be converted from radians to degrees). */ for( ilut = 0; ilut < nlut; ilut++ ) work1[ ilut ] *= scale; /* Store them in row 1, column COORDS, in the FitsTable. */ sprintf( cellname, "COORDS%d(1)", iwcs + 1 ); astMapPut1D( *table, cellname, nlut, work1, NULL ); /* Create an array holding the LutMap input value at the centre of each table entry. Re-use the "lut" array since we no longer need it. */ for( ilut = 0; ilut < nlut; ilut++ ) { lut[ ilut ] = start + ilut*inc; } /* Transform this array using the inverted pre-lutmap mapping to get the list of grid coord. */ astTran1( premap, nlut, lut, 0, work1 ); /* Test this list to see if they form a unit index (i.e. index(i) == i+1 ). (not the "+1" is due to the fact that "i" is zero based). */ for( ilut = 0; ilut < nlut; ilut++ ) { if( fabs( work1[ ilut ] - ilut - 1.0 ) > 1.0E-6 ) break; } /* if it is not a unit index, we add the index to the table. */ if( ilut < nlut ) { /* Define the properties of the column in the FitsTable that holds the indexing vector. */ sprintf( colname, "INDEX%d", iwcs + 1 ); astAddColumn( *table, colname, AST__DOUBLETYPE, 1, &nlut, " " ); /* Get the one-based index of the column just added to the table. */ *icolindex = astGetNcolumn( *table ); /* Store the values in the column. */ sprintf( cellname, "INDEX%d(1)", iwcs + 1 ); astMapPut1D( *table, cellname, nlut, work1, NULL ); } } /* Free resources. */ work1 = astFree( work1 ); lut = astFree( lut ); premap = astAnnul( premap ); postmap = astAnnul( postmap ); /* If no LutMap was found in the Mapping, then we can create a FitsTable by sampling the full WCS Mapping at selected input (i.e. grid) positions. But we can only do this if we know the number of pixels along the WCS axis. */ } else if( dim[ ins[ 0 ] ] != AST__BAD ) { /* Create two works array each holding a single value. The first holds the grid coords at which the samples are taken. The second holds the WCS coords at the sampled positions. These arrays are expanded as required within function AdaptLut. */ work1 = astMalloc( sizeof( double ) ); work2 = astMalloc( sizeof( double ) ); if( astOK ) { /* Get the WCS values at the centres of the first and last pixel on the WCS axis. */ x[ 0 ] = 1.0; x[ 1 ] = dim[ ins[ 0 ] ]; astTran1( ret, 2, x, 1, v ); /* Put the lower limit into the work arrays. */ work1[ 0 ] = x[ 0 ]; work2[ 0 ] = v[ 0 ]; nlut = 1; /* Expand the arrays by sampling the WCS axis adaptively so that more samples occur where the WCS value is changing most rapidly. We require the maximum error introduced by the table to be 0.25 pixels. */ AdaptLut( ret, 3, 0.25, x[ 0 ], x[ 1 ], v[ 0 ], v[ 1 ], &work1, &work2, &nlut, status ); /* Create a FitsTable to hold the returned table info. */ if( ! *table ) *table = astFitsTable( NULL, "", status ); ok = 1; /* Define the properties of the column in the FitsTable that holds the main coordinate array. */ sprintf( colname, "COORDS%d", iwcs + 1 ); dims[ 0 ] = 1; dims[ 1 ] = nlut; astAddColumn( *table, colname, AST__DOUBLETYPE, 2, dims, unit ); *icolmain = astGetNcolumn( *table ); /* Convert the axis values to FITS units (e.g. celestial axis values should be converted from radians to degrees). */ for( ilut = 0; ilut < nlut; ilut++ ) work2[ ilut ] *= scale; /* Store the scaled axis values in row 1 of the column. */ sprintf( cellname, "COORDS%d(1)", iwcs + 1 ); astMapPut1D( *table, cellname, nlut, work2, NULL ); /* Test the index vector to see if they form a unit index (i.e. index(i) == i+1 ). If not the "+1" is due to the fact that "i" is zero based). If not, store them as the index vector in the FitsTable. */ for( ilut = 0; ilut < nlut; ilut++ ) { if( fabs( work1[ ilut ] - ilut - 1.0 ) > 1.0E-6 ) break; } /* If the index vector is not a unit index, define the properties of the column in the FitsTable that holds the indexing vector. Then store values in row 1 of the column. */ if( ilut < nlut ) { sprintf( colname, "INDEX%d", iwcs + 1 ); astAddColumn( *table, colname, AST__DOUBLETYPE, 1, &nlut, " " ); *icolindex = astGetNcolumn( *table ); sprintf( cellname, "INDEX%d(1)", iwcs + 1 ); astMapPut1D( *table, cellname, nlut, work1, NULL ); } } /* Free resources */ work1 = astFree( work1 ); work2 = astFree( work2 ); } /* If columns were added to the table, invert the returned Mapping again so that the input is wcs coord and the output is grid coord. Otherwise, annul the returned Mapping. */ if( ok ) { astInvert( ret ); } else { ret = astAnnul( ret ); } /* Loop to annul all the Mapping pointers in the list. */ for ( imap = 0; imap < nmap; imap++ ) map_list[ imap ] = astAnnul( map_list[ imap ] ); /* Free the dynamic arrays. */ map_list = astFree( map_list ); invert_list = astFree( invert_list ); } /* Free resources. */ ins = astFree( ins ); /* If an error occurred, free the returned Mapping. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result. */ return ret; } static AstMapping *IsMapTab2D( AstMapping *map, double scale, const char *unit, AstFrame *wcsfrm, double *dim, int iax1, int iax2, int iwcs1, int iwcs2, AstFitsTable **table, int *icolmain1, int *icolmain2, int *icolindex1, int *icolindex2, int *max1, int *max2, int *interp1, int *interp2, int *status ){ /* * Name: * IsMapTab2D * Purpose: * See if a specified pair of Mapping outputs are related to a pair of * Mapping inputs via a FITS -TAB algorithm. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *IsMapTab2D( AstMapping *map, double scale, const char *unit, * AstFrame *wcsfrm, double *dim, int iax1, * int iax2, int iwcs1, int iwcs2, * AstFitsTable **table, int *icolmain1, * int *icolmain2, int *icolindex1, * int *icolindex2, int *max1, int *max2, * int *interp1, int *interp2, int *status ) * Class Membership: * FitsChan member function. * Description: * A specified pair of outputs axes of the supplied Mapping are tested * to see if they can be represented by the -TAB alogirithm described in * FITS-WCS paper III. If the test is passed, a Mapping is returned from * the specified WCS axes to the corresponding psi axes. A FitsTable is * also created holding the information to be stored in the corresponding * FITS binary table. Note, when creating a header, AST assumes a unit * transformaton between psi axes and grid axes (psi axes are defined * in FITS-WCS paper III section 6.1.2). * Parameters: * map * Pointer to the Mapping from pixel coords to WCS coords. * scale * A scale factor by which to multiply the axis values stored in the * returned FitsTable. Note, the returned Mapping is unaffected by * this scaling factor. * unit * A unit string for the axis values. If supplied, the same * string is stored for both axes. If NULL, the unit strings are * extracted from the relavent axes of the supplied WCS Frame. * wcsfrm * Pointer to a Frame describing WCS coords. * dim * An array holding the array dimensions in pixels. AST__BAD should * be supplied for any unknown dimensions. * iax1 * The zero-based index of the first Mapping output which is to be * checked. * iax2 * The zero-based index of the second Mapping output which is to be * checked. * iwcs1 * The zero-based index of the FITS WCS axis corresponding to "iax1". * iwcs2 * The zero-based index of the FITS WCS axis corresponding to "iax2". * table * Pointer to a location holding a pointer to the FitsTable describing * the -TAB look-up table. If "*table" is NULL on entry, a new * FitsTable will be created and returned, otherwise the supplied * FitsTable is used. * icolmain1 * The one-based index of the column within "*table" that holds the * main coord array for the first Mapping output. * icolmain2 * The one-based index of the column within "*table" that holds the * main coord array for the second Mapping output. * icolindex1 * The one-based index of the column within "*table" that holds the * index vector for the first Mapping output. Returned equal to -1 * if no index is added to the table (e.g. because the index is a * unit index). * icolindex2 * The one-based index of the column within "*table" that holds the * index vector for the second Mapping output. Returned equal to -1 * if no index is added to the table (e.g. because the index is a * unit index). * max1 * The one-based index of the dimension describing the first Mapping * output within the main coord array specified by "icolmain1". * max2 * The one-based index of the dimension describing the second Mapping * output within the main coord array specified by "icolmain1". * interp1 * The interpolation method (0=linear, other=nearest neighbour) for * the first mapping output. * interp2 * The interpolation method (0=linear, other=nearest neighbour) for * the second mapping output. * status * Pointer to the inherited status variable. * Returned Value: * If the specified "map" outputs can be described using the -TAB * algorithm of FITS-WCS paper III, then a 2-input/2-output Mapping * from the specified WCS axes to the corresponding psi axes (i.e. * grid axes) is returned. NULL is returned otherwise, of if an error * occurs. */ /* Local Variables: */ AstMapping *ret1; /* WCS->IWC Mapping for first output */ AstMapping *ret2; /* WCS->IWC Mapping for second output */ AstMapping *ret; /* Returned WCS axis Mapping */ AstMapping *tmap; AstPermMap *pm; int *pix_axes; /* Zero-based indices of corresponding pixel axes */ int wcs_axes[ 2 ]; /* Zero-based indices of selected WCS axes */ int inperm[ 1 ]; int outperm[ 2 ]; /* Initialise */ ret = NULL; /* Check inherited status */ if( !astOK ) return ret; /* First see if the two required Mapping outputs are separable, in which case they can be described by two 1D tables. */ ret1 = IsMapTab1D( map, scale, unit, wcsfrm, dim, iax1, iwcs1, table, icolmain1, icolindex1, interp1, status ); ret2 = IsMapTab1D( map, scale, unit, wcsfrm, dim, iax2, iwcs2, table, icolmain2, icolindex2, interp2, status ); /* If both outputs are seperable... */ if( ret1 && ret2 ) { /* Both axes are stored as the first dimension in the corresponding main coords array. */ *max1 = 1; *max2 = 1; /* Get a Mapping from the required pair of WCS axes to the corresponding pair of grid axes. First try to split the supplied grid->wcs mapping. */ wcs_axes[ 0 ] = iax1; wcs_axes[ 1 ] = iax2; astInvert( map ); pix_axes = astMapSplit( map, 2, wcs_axes, &ret ); astInvert( map ); if( pix_axes ) { pix_axes = astFree( pix_axes ); if( astGetNout( ret ) > 2 ) { ret = astAnnul( ret ); /* If the two output WCS axes are fed by the same grid axis, we need to add another pixel axis to form the pair. */ } else if( astGetNout( ret ) == 1 ) { inperm[ 0 ] = 0; outperm[ 0 ] = 0; outperm[ 1 ] = 0; pm = astPermMap( 1, inperm, 2, outperm, NULL, " ", status ); tmap = (AstMapping *) astCmpMap( ret, pm, 1, " ", status ); ret = astAnnul( ret ); pm = astAnnul( pm ); ret = tmap; } } /* If this was unsuccessful, combine the Mappings returned by IsMapTab1D. We only do this if the above astMapSplit call failed, since the IsMapTab1D mappings may well not be independent of each other, and we may end up sticking together in parallel two mappings that are basically the same except for ending with PermMapa that select different axes. Is is hard then to simplify such a parallel CmpMap back into the simpler form that uses only one of the two identical mappings, without a PermMap. */ if( !ret ) { ret = (AstMapping *) astCmpMap( ret1, ret2, 0, " ", status ); } /* Free resources. */ ret1 = astAnnul( ret1 ); ret2 = astAnnul( ret2 ); /* If only one output is separable, remove the corresponding columns from the returned table. */ } else if( ret1 ) { ret1 = astAnnul( ret1 ); astRemoveColumn( *table, astColumnName( *table, *icolmain1 ) ); if( icolindex1 >= 0 ) astRemoveColumn( *table, astColumnName( *table, *icolindex1 ) ); } else if( ret2 ) { ret2 = astAnnul( ret2 ); astRemoveColumn( *table, astColumnName( *table, *icolmain2 ) ); if( icolindex1 >= 0 ) astRemoveColumn( *table, astColumnName( *table, *icolindex2 ) ); } /* If the required Mapping outputs were not separable, create a single 2D coords array describing both outputs. */ if( !ret ) { /* TO BE DONE... Until then non-separable Mappings will result in a failure to create a -TAB header. No point in doing this until AST has an N-dimensional LutMap class (otherwise AST could never read the resulting FITS header). */ } /* If an error occurred, free the returned Mapping. */ if( !astOK ) ret = astAnnul( ret ); /* Return the result. */ return ret; } static int IsAIPSSpectral( const char *ctype, char **wctype, char **wspecsys, int *status ){ /* * Name: * IsAIPSSpectral * Purpose: * See if a given CTYPE value describes a FITS-AIPS spectral axis. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int IsAIPSSpectral( const char *ctype, char **wctype, char **wspecsys, int *status ) * Class Membership: * FitsChan member function. * Description: * The given CTYPE value is checked to see if it conforms to the * requirements of a spectral axis CTYPE value as specified by * FITS-AIPS encoding. If so, the equivalent FITS-WCS CTYPE and * SPECSYS values are returned. * Parameters: * ctype * Pointer to a null terminated string holding the CTYPE value to * check. * wctype * The address of a location at which to return a pointer to a * static string holding the corresponding FITS-WCS CTYPE value. A * NULL pointer is returned if the supplied CTYPE string is not an * AIPS spectral CTYPE value. * wspecsys * The address of a location at which to return a pointer to a * static string holding the corresponding FITS-WCS SPECSYS value. A * NULL pointer is returned if the supplied CTYPE string is not an * AIPS spectral CTYPE value. * status * Pointer to the inherited status variable. * Retuned Value: * Non-zero fi the supplied CTYPE was an AIPS spectral CTYPE value. * Note: * - These translations are also used by the FITS-CLASS encoding. */ /* Local Variables: */ int ret; /* Initialise */ ret = 0; *wctype = NULL; *wspecsys = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* If the used length of the string is not 8, then it is not an AIPS spectral axis. */ if( astChrLen( ctype ) == 8 ) { /* Translate AIPS spectral CTYPE values to FITS-WCS paper III equivalents. These are of the form AAAA-BBB, where "AAAA" can be "FREQ", "VELO" (=VRAD!) or "FELO" (=VOPT-F2W), and BBB can be "LSR", "LSD", "HEL" (=*Bary*centric!) or "GEO". */ if( !strncmp( ctype, "FREQ", 4 ) ){ *wctype = "FREQ "; } else if( !strncmp( ctype, "VELO", 4 ) ){ *wctype = "VRAD "; } else if( !strncmp( ctype, "FELO", 4 ) ){ *wctype = "VOPT-F2W"; } else if( !strncmp( ctype, "WAVELENG", 8 ) ){ *wctype = "WAVE "; } if( !strncmp( ctype + 4, "-LSR", 4 ) ){ *wspecsys = "LSRK"; } else if( !strncmp( ctype + 4, "LSRK", 4 ) ){ *wspecsys = "LSRK"; } else if( !strncmp( ctype + 4, "-LSD", 4 ) ){ *wspecsys = "LSRD"; } else if( !strncmp( ctype + 4, "-HEL", 4 ) ){ *wspecsys = "BARYCENT"; } else if( !strncmp( ctype + 4, "-EAR", 4 ) || !strncmp( ctype + 4, "-GEO", 4 ) ){ *wspecsys = "GEOCENTR"; } else if( !strncmp( ctype + 4, "-OBS", 4 ) || !strncmp( ctype + 4, "-TOP", 4 ) ){ *wspecsys = "TOPOCENT"; } if( *wctype && *wspecsys ) { ret = 1; } else { *wctype = NULL; *wspecsys = NULL; } } /* Return the result. */ return ret; } static int IsSkyOff( AstFrameSet *fset, int iframe, int *status ){ /* * Name: * IsSkyOff * Purpose: * See if a given Frame contains an offset SkyFrame. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int IsSkyOff( AstFrameSet *fset, int iframe, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns a flag indicating if the specified Frame within the * supplied FrameSet is, or contains, a SkyFrame that represents * offset coordinates. This is the case if the Frame is a SkyFrame * and its SkyRefIs attribute is "Pole" or "Origin", or is a CmpFrame * containing such a SkyFrame. * Parameters: * fset * The FrameSet. * iframe * Index of the Frame to check within "fset" * status * Pointer to the inherited status variable. * Retuned Value: * +1 if the Frame is an offset SkyFrame. Zero otherwise. * Notes: * - Zero is returned if an error has already occurred. */ /* Local Variables: */ AstFrame *frm; const char *skyrefis; int oldrep; int result; /* Initialise. */ result = 0; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the required Frame in the FrameSet */ frm = astGetFrame( fset, iframe ); /* Since the current Frame may not contain a SkyFrame, we temporarily switch off error reporting. */ oldrep = astReporting( 0 ); /* Get the SkyRefIs attribute value. */ skyrefis = astGetC( frm, "SkyRefIs" ); /* If it is "Pole" or "Origin", return 1. */ if( skyrefis && ( !Ustrcmp( skyrefis, "POLE", status ) || !Ustrcmp( skyrefis, "ORIGIN", status ) ) ) result = 1; /* Cancel any error and switch error reporting back on again. */ astClearStatus; astReporting( oldrep ); /* Annul the Frame pointer. */ frm = astAnnul( frm ); /* Return the result. */ return result; } static const char *IsSpectral( const char *ctype, char stype[5], char algcode[5], int *status ) { /* * Name: * IsSpectral * Purpose: * See if a given FITS-WCS CTYPE value describes a spectral axis. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *IsSpectral( const char *ctype, char stype[5], char algcode[5], int *status ) * Class Membership: * FitsChan member function. * Description: * The given CTYPE value is checked to see if it conforms to the * requirements of a spectral axis CTYPE value as specified by * FITS-WCS paper 3. If so, the spectral system and algorithm codes * are extracted from it and returned, together with the default units * for the spectral system. * Parameters: * ctype * Pointer to a null terminated string holding the CTYPE value to * check. * stype * An array in which to return the null-terminated spectral system type * (e.g. "FREQ", "VELO", "WAVE", etc). A null string is returned if * the CTYPE value does not describe a spectral axis. * algcode * An array in which to return the null-terminated algorithm code * (e.g. "-LOG", "", "-F2W", etc). A null string is returned if the * spectral axis is linear. A null string is returned if the CTYPE * value does not describe a spectral axis. * status * Pointer to the inherited status variable. * Retuned Value: * A point to a static string holding the default units associated * with the spectral system specified by the supplied CTYPE value. * NULL is returned if the CTYPE value does not describe a spectral * axis. * Notes: * - The axis is considered to be a spectral axis if the first 4 * characters form one of the spectral system codes listed in FITS-WCS * paper 3. The algorithm code is not checked, except to ensure that * it begins with a minus sign, or is blank. * - A NULL pointer is returned if an error has already occurred. */ /* Local Variables: */ astDECLARE_GLOBALS int ctype_len; /* Initialise */ stype[ 0 ] = 0; algcode[ 0 ] = 0; /* Check the inherited status. */ if( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* Initialise more stuff */ isspectral_ret = NULL; /* If the length of the string is less than 4, then it is not a spectral axis. */ ctype_len = strlen( ctype ); if( ctype_len >= 4 ) { /* Copy the first 4 characters (the coordinate system described by the axis) into a null-terminated buffer. */ strncpy( stype, ctype, 4 ); stype[ 4 ] = 0; stype[ astChrLen( stype ) ] = 0; /* Copy any remaining characters (the algorithm code) into a null-terminated buffer. Only copy a maximum of 4 characters. */ if( ctype_len > 4 ) { if( ctype_len <= 8 ) { strcpy( algcode, ctype + 4 ); } else { strncpy( algcode, ctype + 4, 4 ); algcode[ 4 ] = 0; } algcode[ astChrLen( algcode ) ] = 0; } else { algcode[ 0 ] = 0; } /* See if the first 4 characters of the CTYPE value form one of the legal spectral coordinate type codes listed in FITS-WCS Paper III. Also note the default units associated with the system. */ if( !strcmp( stype, "FREQ" ) ) { isspectral_ret = "Hz"; } else if( !strcmp( stype, "ENER" ) ) { isspectral_ret = "J"; } else if( !strcmp( stype, "WAVN" ) ) { isspectral_ret = "/m"; } else if( !strcmp( stype, "VRAD" ) ) { isspectral_ret = "m/s"; } else if( !strcmp( stype, "WAVE" ) ) { isspectral_ret = "m"; } else if( !strcmp( stype, "VOPT" ) ) { isspectral_ret = "m/s"; } else if( !strcmp( stype, "ZOPT" ) ) { isspectral_ret = ""; } else if( !strcmp( stype, "AWAV" ) ) { isspectral_ret = "m"; } else if( !strcmp( stype, "VELO" ) ) { isspectral_ret = "m/s"; } else if( !strcmp( stype, "BETA" ) ) { isspectral_ret = ""; } /* Also check that the remaining part of CTYPE (the algorithm code) begins with a minus sign or is blank. */ if( algcode[ 0 ] != '-' && strlen( algcode ) > 0 ) isspectral_ret = NULL; } /* Return null strings if the axis is not a spectral axis. */ if( ! isspectral_ret ) { stype[ 0 ] = 0; algcode[ 0 ] = 0; } /* Return the result. */ return isspectral_ret; } static AstMapping *LinearWcs( FitsStore *store, int i, char s, const char *method, const char *class, int *status ) { /* * Name: * LinearWcs * Purpose: * Create a Mapping describing a FITS-WCS linear algorithm * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *LinearWcs( FitsStore *store, int i, char s, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function uses the contents of the supplied FitsStore to create * a Mapping which goes from Intermediate World Coordinate (known as "w" * in the context of FITS-WCS paper III) to a linearly related axis. * * The returned Mapping is a ShiftMap which simply adds on the value of * CRVALi. * Parameters: * store * Pointer to the FitsStore structure holding the values to use for * the WCS keywords. * i * The zero-based index of the spectral axis within the FITS header * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a Mapping, or NULL if an error occurs. */ /* Local Variables: */ AstMapping *ret; double crv; /* Check the global status. */ ret = NULL; if( !astOK ) return ret; /* Get the CRVAL value for the specified axis. */ crv = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( crv == AST__BAD ) crv = 0.0; /* Create a 1D ShiftMap which adds this value onto the IWCS value. */ if( crv != 0.0 ) { ret = (AstMapping *) astShiftMap( 1, &crv, "", status ); } else { ret = (AstMapping *) astUnitMap( 1, "", status ); } return ret; } static AstMapping *LogAxis( AstMapping *map, int iax, int nwcs, double *lbnd_p, double *ubnd_p, double crval, int *status ){ /* * Name: * LogAxes * Purpose: * Test a Frame axis to see if it logarithmically spaced in pixel coords. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *LogAxis( AstMapping *map, int iax, int nwcs, double *lbnd_p, * double *ubnd_p, double crval ) * Class Membership: * FitsChan member function. * Description: * A specified axis of the supplied Mappinhg is tested to see if it * corresponds to the form * * S = Sr.exp( w/Sr ) * * where "w" is one of the Mapping inputs, "S" is the specified * Mapping output, and "Sr" is the supplied value of "crval". This * is the form for a FITS log axis as defined in FITS-WCS paper III. * * If the above test is passed, a Mapping is returned from "S" to "w" * (the inverseof the above expression). * Parameters: * map * Pointer to the Mapping. This will usually be a Mapping from * pixel coords to WCS coords. * iax * The index of the output of "map" which correspoinds to "S". * nwcs * The number of outputs from "map". * lbnd_p * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the lower bound * of the input pixel box in each input dimension. * ubnd_p * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the upper bound * of the input pixel box in each input dimension. * crval * The reference value ("Sr") to use. Must not be zero. * Returned Value: * If the specified axis is logarithmically spaced, a Mapping with * "nwcs" inputs and "nwcs" outputs is returned. This Mapping transforms * its "iax"th input using the transformation: * * w = Sr.Log( S/Sr ) * * (where "S" is the Mapping is the "iax"th input and "w" is the * "iax"th output). Other inputs are copied to the corresponding * output without change. NULL is returned if the specified axis is * not logarithmically spaced. */ /* Local Variables: */ AstMapping *result; /* Returned Mapping */ AstMapping *tmap0; /* A temporary Mapping */ AstMapping *tmap1; /* A temporary Mapping */ AstMapping *tmap2; /* A temporary Mapping */ AstMapping *tmap3; /* A temporary Mapping */ AstMapping *tmap4; /* A temporary Mapping */ const char *fexps[ 1 ]; /* Forward MathMap expressions */ const char *iexps[ 1 ]; /* Inverse MathMap expressions */ /* Initialise */ result = NULL; /* Check the inherited status and crval value. */ if( !astOK || crval == 0.0 ) return result; /* If the "log" algorithm is appropriate, the supplied axis (s) is related to pixel coordinate (p) by s = Sr.EXP( a*p - b ). If this is the case, then the log of s will be linearly related to pixel coordinates. To test this, we create a CmpMap which produces log(s). */ fexps[ 0 ] = "logs=log(s)"; iexps[ 0 ] = "s=exp(logs)"; tmap1 = (AstMapping *) astMathMap( 1, 1, 1, fexps, 1, iexps, "simpfi=1,simpif=1", status ); tmap2 = AddUnitMaps( tmap1, iax, nwcs, status ); tmap0 = (AstMapping *) astCmpMap( map, tmap2, 1, "", status ); tmap2 = astAnnul( tmap2 ); /* See if this Mapping is linear. */ if( IsMapLinear( tmap0, lbnd_p, ubnd_p, iax, status ) ) { /* Create the Mapping which defines the IWC axis. This is the Mapping from WCS to IWCS - "W = Sr.log( S/Sr )". Other axes are left unchanged by the Mapping. The IWC axis has the same axis index as the WCS axis. */ tmap2 = (AstMapping *) astZoomMap( 1, 1.0/crval, "", status ); tmap3 = (AstMapping *) astCmpMap( tmap2, tmap1, 1, "", status ); tmap2 = astAnnul( tmap2 ); tmap2 = (AstMapping *) astZoomMap( 1, crval, "", status ); tmap4 = (AstMapping *) astCmpMap( tmap3, tmap2, 1, "", status ); tmap3 = astAnnul( tmap3 ); tmap2 = astAnnul( tmap2 ); result = AddUnitMaps( tmap4, iax, nwcs, status ); tmap4 = astAnnul( tmap4 ); } /* Free resources. */ tmap0 = astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); /* Return the result. */ return result; } static AstMapping *LogWcs( FitsStore *store, int i, char s, const char *method, const char *class, int *status ) { /* * Name: * LogWcs * Purpose: * Create a Mapping describing a FITS-WCS logarithmic algorithm * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *LogWcs( FitsStore *store, int i, char s, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function uses the contents of the supplied FitsStore to create * a Mapping which goes from Intermediate World Coordinate (known as "w" * in the context of FITS-WCS paper III) to a logarthmic version of w * called "S" given by: * * S = Sr.exp( w/Sr ) * * where Sr is the value of S corresponding to w=0. * Parameters: * store * Pointer to the FitsStore structure holding the values to use for * the WCS keywords. * i * The zero-based index of the axis within the FITS header * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a Mapping, or NULL if an error occurs. */ /* Local Variables: */ AstMapping *ret; char forexp[ 12 + DBL_DIG*2 ]; char invexp[ 12 + DBL_DIG*2 ]; const char *fexps[ 1 ]; const char *iexps[ 1 ]; double crv; /* Check the global status. */ ret = NULL; if( !astOK ) return ret; /* Get the CRVAL value for the specified axis. Use a default of zero. */ crv = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( crv == AST__BAD ) crv = 0.0; /* Create the MathMap, if possible. */ if( crv != 0.0 ) { sprintf( forexp, "s=%.*g*exp(w/%.*g)", DBL_DIG, crv, DBL_DIG, crv ); sprintf( invexp, "w=%.*g*log(s/%.*g)", DBL_DIG, crv, DBL_DIG, crv ); fexps[ 0 ] = forexp; iexps[ 0 ] = invexp; ret = (AstMapping *) astMathMap( 1, 1, 1, fexps, 1, iexps, "simpfi=1,simpif=1", status ); } /* Return the result */ return ret; } static int LooksLikeClass( AstFitsChan *this, const char *method, const char *class, int *status ){ /* * Name: * LooksLikeClass * Purpose: * Does the FitsChan seem to use FITS-CLASS encoding? * Type: * Private function. * Synopsis: * #include "fitschan.h" * int LooksLikeClass( AstFitsChan *this, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns non-zero if the supplied FitsChan probably uses FITS-CLASS * encoding. This is the case if it contains a DELTAV keyword and a * keyword of the form VELO-xxx", where xxx is one of the accepted * standards of rest, or "VLSR". * Parameters: * this * Pointer to the FitsChan. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the encoding in use lookslike FITS-CLASS. */ /* Local Variables... */ int ret; /* Returned value */ /* Initialise */ ret = 0; /* Check the global status. */ if( !astOK ) return ret; /* See if there is a "DELTAV" card, and a "VELO-xxx" or "VLSR" card. */ if( astKeyFields( this, "DELTAV", 0, NULL, NULL ) && ( astKeyFields( this, "VLSR", 0, NULL, NULL ) || astKeyFields( this, "VELO-OBS", 0, NULL, NULL ) || astKeyFields( this, "VELO-HEL", 0, NULL, NULL ) || astKeyFields( this, "VELO-EAR", 0, NULL, NULL ) || astKeyFields( this, "VELO-LSR", 0, NULL, NULL ) ) ) { ret = 1; } /* Return the result. */ return ret; } static void MakeBanner( const char *prefix, const char *middle, const char *suffix, char banner[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ], int *status ) { /* * Name: * MakeBanner * Purpose: * Create a string containing a banner comment. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void MakeBanner( const char *prefix, const char *middle, * const char *suffix, * char banner[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ], int *status ) * Class Membership: * FitsChan member function. * Description: * This function creates a string which can be written as a FITS * comment card to produce a banner heading (or tail) for an AST * Object when it is written to a FitsChan. The banner will occupy * the maximum permitted width for text in a FITS comment card. * Parameters: * prefix * A pointer to a constant null-terminated string containing the * first part of the text to appear in the banner. * middle * A pointer to a constant null-terminated string containing the * second part of the text to appear in the banner. * suffix * A pointer to a constant null-terminated string containing the * third part of the text to appear in the banner. * banner * A character array to receive the null-terminated result string. * status * Pointer to the inherited status variable. * Notes: * - The text to appear in the banner is constructed by * concatenating the three input strings supplied. */ /* Local Variables: */ char token[] = "AST"; /* Identifying token */ int i; /* Loop counter for input characters */ int len; /* Number of output characters */ int ltok; /* Length of token string */ int mxlen; /* Maximum permitted output characters */ int start; /* Column number where text starts */ /* Check the global error status. */ if ( !astOK ) return; /* Calculate the maximum number of characters that the output banner can hold and the length of the token string. */ mxlen = AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN; ltok = (int) strlen( token ); /* Calculate the column in which to start the text, so that it is centred in the banner (with 4 non-text characters on each side). */ start = ltok + 2 + ( mxlen - ltok - 1 - (int) ( strlen( prefix ) + strlen( middle ) + strlen( suffix ) ) - 1 - ltok ) / 2; if ( start < ltok + 2 ) start = ltok + 2; /* Start building the banner with the token string. */ len = 0; for ( i = 0; token[ i ] && ( len < mxlen ); i++ ) { banner[ len++ ] = token[ i ]; } /* Then pad with spaces up to the start of the text. */ while ( len < start - 1 ) banner[ len++ ] = ' '; /* Insert the prefix data, truncating it if it is too long. */ for ( i = 0; prefix[ i ] && ( len < mxlen - ltok - 1 ); i++ ) { banner[ len++ ] = prefix[ i ]; } /* Insert the middle data, truncating it if it is too long. */ for ( i = 0; middle[ i ] && ( len < mxlen - ltok - 1 ); i++ ) { banner[ len++ ] = middle[ i ]; } /* Insert the suffix data, truncating it if it is too long. */ for ( i = 0; suffix[ i ] && ( len < mxlen - ltok - 1 ); i++ ) { banner[ len++ ] = suffix[ i ]; } /* Pad the end of the text with spaces. */ while ( len < mxlen - ltok ) banner[ len++ ] = ' '; /* Finish the banner with the token string. */ for ( i = 0; token[ i ] && ( len < mxlen ); i++ ) { banner[ len++ ] = token[ i ]; } /* Terminate the output string. */ banner[ len ] = '\0'; } static AstMapping *MakeColumnMap( AstFitsTable *table, const char *col, int isindex, int interp, const char *method, const char *class, int *status ){ /* * Name: * MakeColumnMap * Purpose: * Create a Mapping describing a look-up table supplied in a cell of a * FITS binary table. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *MakeColumnMap( AstFitsTable *table, const char *col, * int isindex, int interp, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a Mapping representing the array of values * stored in row 1 of a named column of a supplied FitsTable. The * array of values is treated as a look-up table following the prescription * of FITS-WCS paper III (the "-TAB" algorithm). If the array has (N+1) * dimensions (where N is one or more), the returned Mapping has N * inputs and N outputs. The inputs correspond to FITS GRID coords * within the array. FITS-WCS paper III requires that the first dimension * in the array has a length of "N" and contains the N output values * at each input values. * Parameters: * table * Pointer to the Fitstable. * col * A string holding the name of the column to use. * isindex * Non-zero if the column hold an index array, zero if it holds a * coordinate array. * interp * The value to use for the Interp attribute of the LutMap. A value * of zero tells the LutMap class to use linear interpolation. Other * values tell the LutMap class to use nearest neighbour interpolation. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping, or NULL if an error occurs. */ /* Local Variables: */ AstMapping *result; char *key; double *lut; int *dims; int ndim; int nel; /* Initialise */ result = NULL; /* Check the inherited status */ if( !astOK ) return result; /* Get the number of dimensions spanned by the value in the named column. */ ndim = astGetColumnNdim( table, col ); /* First deal with index vectors. */ if( isindex ) { /* FITS-WCS paper II mandates that index arrays must be 1-dimensional. */ if( ndim != 1 && astOK ) { astError( AST__BADTAB, "%s(%s): Column '%s' has %d dimensions but it " "holds an index vector and should therefore be 1-dimensional.", status, method, class, col, ndim ); } /* Get the length of the index vector. */ nel = astGetColumnLength( table, col ); /* Allocate memory to hold the array values, and to hold the cell key. */ lut = astMalloc( nel*sizeof( double ) ); key = astMalloc( strlen( col ) + 5 ); if( astOK ) { /* Create the key for the table cell holding the required array. FITS-WCS paper III mandates that tables always occur in the first row of the table (and that the table only has one row). Ignore trailing spaces in the column name. */ sprintf( key, "%.*s(1)", (int) astChrLen( col ), col ); /* Copy the array values into the above memory. */ if( astMapGet1D( table, key, nel, &nel, lut ) ) { /* Create a 1D LutMap. FITS-WCS paper III (sec 6.1.2) mandates that the input corresponds to FITS grid coord (i.e. 1.0 at the centre of the first entry). Ensure the LutMap uses linear interpolation. */ result = (AstMapping *) astLutMap( nel, lut, 1.0, 1.0, "LutInterp=%d", status, interp ); /* Report an error if the table cell was empty. */ } else if( astOK ) { astError( AST__BADTAB, "%s(%s): Row 1 of the binary table " "contains no value for column '%s'.", status, method, class, col ); } } /* Free memory. */ lut = astFree( lut ); key = astFree( key ); /* Now deal with coordinate arrays. */ } else { /* Get the shape of the array. */ dims = astMalloc( sizeof( int )*ndim ); astColumnShape( table, col, ndim, &ndim, dims ); /* For coordinate arrays, check the length of the first axis is "ndim-1", as required by FITS-WCS paper III. */ if( astOK && dims[ 0 ] != ndim - 1 && !isindex ) { astError( AST__BADTAB, "%s(%s): The first dimension of the coordinate " "array has length %d (should be %d since the array has %d " "dimensions).", status, method, class, dims[ 0 ], ndim - 1, ndim ); } /* We can currently only handle 1D look-up tables. These are stored in notionally two-dimensional arrays in which the first dimension is degenarate (i.e. spans only a single element). */ if( ndim > 2 ) { if( astOK ) astError( AST__INTER, "%s(%s): AST can currently only " "handle 1-dimensional coordinate look-up tables " "(the supplied table has %d dimensions).", status, method, class, ndim - 1 ); /* Handle 1-dimensional look-up tables. */ } else if( astOK ){ /* Allocate memory to hold the array values, and to hold the cell key. */ lut = astMalloc( dims[ 1 ]*sizeof( double ) ); key = astMalloc( strlen( col ) + 5 ); if( astOK ) { /* Create the key for the table cell holding the required array. FITS-WCS paper III mandates that tables always occur in the first row of the table (and that the table only has one row). Ignore trailing spaces in the column name. */ sprintf( key, "%.*s(1)", (int) astChrLen( col ), col ); /* Copy the array values into the above memory. */ if( astMapGet1D( table, key, dims[ 1 ], dims, lut ) ) { /* Create a 1D LutMap. FITS-WCS paper III (sec 6.1.2) mandates that the input corresponds to FITS grid coord (i.e. 1.0 at the centre of the first entry). Ensure the LutMap uses linear interpolation. */ result = (AstMapping *) astLutMap( dims[ 1 ], lut, 1.0, 1.0, "LutInterp=%d", status, interp ); /* Report an error if the table cell was empty. */ } else if( astOK ) { astError( AST__BADTAB, "%s(%s): Row 1 of the binary table " "contains no value for column '%s'.", status, method, class, col ); } } /* Free memory. */ lut = astFree( lut ); key = astFree( key ); } dims = astFree( dims ); } /* Issue a context message and annul the returned Mapping if an error has occurred. */ if( !astOK ) { astError( astStatus, "%s(%s): Cannot read a look-up table for a " "tabular WCS axis from column '%s' of a FITS binary table.", status, method, class, col ); result = astAnnul( result ); } /* Return the result. */ return result; } static AstFrameSet *MakeFitsFrameSet( AstFitsChan *this, AstFrameSet *fset, int ipix, int iwcs, int encoding, const char *method, const char *class, int *status ) { /* * Name: * MakeFitsFrameSet * Purpose: * Create a FrameSet which conforms to the requirements of the FITS-WCS * papers. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstFrameSet *MakeFitsFrameSet( AstFitsChan *this, AstFrameSet *fset, * int ipix, int iwcs, int encoding, * const char *method, const char *class, * int *status ) * Class Membership: * FitsChan member function. * Description: * This function constructs a new FrameSet holding the pixel and WCS * Frames from the supplied FrameSet, but optionally extends the WCS * Frame to include any extra axes needed to conform to the FITS model. * Currently, this function does the following: * * - if the WCS Frame contains a 1D spectral Frame with a defined celestial * reference position (SpecFrame attributes RefRA and RefDec), then * it ensures that the WCS Frame also contains a pair of celestial * axes (such axes are added if they do not already exist within the * supplied WCS Frame). The pixel->WCS Mapping is adjusted accordingly. * * - if the WCS Frame contains a spectral axis and a pair of celestial * axes, then the SpecFrame attributes RefRA and RefDec are set to the * reference position defined by the celestial axes. The pixel->WCS * Mapping is adjusted accordingly. * * - NULL is returned if the WCS Frame contains more than one spectral * axis. * * - NULL is returned if the WCS Frame contains more than one pair of * celestial axes. * * - Any isolated sky axes (i.e. not contained within a SkyFrame) are * re-mapped from radians into degrees. * Parameters: * this * The FitsChan. * fset * The FrameSet to check. * ipix * The index of the FITS pixel Frame within "fset". * iwcs * The index of the WCS Frame within "fset". * encoding * The encoding in use. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A new FrameSet which confoms to the requirements of the FITS-WCS * papers. The base Frame in this FrameSet will be the FITS pixel * Frame, and the current Frame will be the WCS Frame. NULL is * returned if an error has already occurred, or if the FrameSet cannot * be produced for any reason. */ /* Local Variables: */ AstFitsChan *fc; /* Pointer to temporary FitsChan */ AstFrame *pframe; /* Pointer to the primary Frame */ AstFrame *pixfrm; /* Pointer to the FITS pixel Frame */ AstFrame *tfrm0; /* Pointer to a temporary Frame */ AstFrame *tfrm; /* Pointer to a temporary Frame */ AstFrame *wcsfrm; /* Pointer to the FITS WCS Frame */ AstFrameSet *ret; /* The returned FrameSet */ AstFrameSet *tfs; /* Pointer to a temporary FrameSet */ AstMapping *map1; /* Pointer to pre-WcsMap Mapping */ AstMapping *map3; /* Pointer to post-WcsMap Mapping */ AstMapping *map; /* Pointer to the pixel->wcs Mapping */ AstMapping *remap; /* Total Mapping from internal to external units */ AstMapping *smap; /* Simplified Mapping */ AstMapping *tmap0; /* Pointer to a temporary Mapping */ AstMapping *tmap1; /* Pointer to a temporary Mapping */ AstMapping *tmap2; /* Pointer to a temporary Mapping */ AstMapping *tmap; /* Pointer to a temporary Mapping */ AstMapping *umap; /* 1D Mapping from internal to external units */ AstSpecFrame *skyfrm; /* Pointer to the SkyFrame within WCS Frame */ AstSpecFrame *specfrm; /* Pointer to the SpecFrame within WCS Frame */ AstWcsMap *map2; /* Pointer to WcsMap */ char card[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* A FITS header card */ char equinox_attr[ 13 ];/* Name of Equinox attribute for sky axes */ char system_attr[ 12 ]; /* Name of System attribute for sky axes */ const char *eqn; /* Pointer to original sky Equinox value */ const char *extunit; /* External units string */ const char *intunit; /* Internal units string */ const char *skysys; /* Pointer to original sky System value */ double con; /* Constant axis value */ double reflat; /* Celestial latitude at reference point */ double reflon; /* Celestial longitude at reference point */ int *perm; /* Pointer to axis permutation array */ int iax; /* Axis inex */ int icurr; /* Index of original current Frame in returned FrameSet */ int ilat; /* Celestial latitude index within WCS Frame */ int ilon; /* Celestial longitude index within WCS Frame */ int npix; /* Number of pixel axes */ int nwcs; /* Number of WCS axes */ int ok; /* Is the supplied FrameSet usable? */ int paxis; /* Axis index within the primary Frame */ int rep; /* Was error reporting switched on? */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Get copies of the pixel Frame, the WCS Frame and the Mapping. */ tfrm = astGetFrame( fset, ipix ); pixfrm = astCopy( tfrm ); tfrm = astAnnul( tfrm ); tfrm = astGetFrame( fset, iwcs ); wcsfrm = astCopy( tfrm ); tfrm = astAnnul( tfrm ); tmap = astGetMapping( fset, ipix, iwcs ); map = astCopy( tmap ); tmap = astAnnul( tmap ); /* Store the number of pixel and WCS axes. */ npix = astGetNaxes( pixfrm ); nwcs = astGetNaxes( wcsfrm ); /* Search the WCS Frame for SkyFrames and SpecFrames. */ umap = NULL; remap = NULL; specfrm = NULL; skyfrm = NULL; ok = 1; ilat = -1; ilon = -1; for( iax = 0; iax < nwcs; iax++ ) { /* Obtain a pointer to the primary Frame containing the current WCS axis. */ astPrimaryFrame( wcsfrm, iax, &pframe, &paxis ); /* If the current axis is a SpecFrame, save a pointer to it. If we have already found a SpecFrame, abort. */ if( astIsASpecFrame( pframe ) ) { if( specfrm ) { ok = 0; break; } specfrm = astClone( pframe ); /* If the current axis is a SkyFrame, save a pointer to it, and its WCS index. If we have already found a different SkyFrame, abort. */ } else if( IsASkyFrame( pframe ) ) { if( skyfrm ) { if( pframe != (AstFrame *) skyfrm ) { ok = 0; break; } } else { skyfrm = astClone( pframe ); } if( paxis == 0 ) { ilon = iax; } else { ilat = iax; } /* If the internal and external units differ, attempt to remap the axis into its external units. */ } else { /* Get the string describing the external units (the "Unit" attribute). */ extunit = astGetUnit( pframe, paxis ); /* Get the string describing the internal units (the "InternalUnit" attribute). */ intunit = astGetInternalUnit( pframe, paxis ); /* If they are the same, we do not need to modify this axis. */ if( astOK && strcmp( extunit, intunit ) ){ /* Otherwise, get the mapping from the internal units to the external units, if possible. Ignore any error reported by unitmapper. */ rep = astReporting( 0 ); umap = astUnitMapper( intunit, extunit, NULL, NULL ); if( !astOK ) astClearStatus; astReporting( rep ); if( !umap ) { /* If the above failed, ensure that the external units are the same as the internal units (except that internal radians are converted to external degrees). */ if( !strcmp( intunit, "rad" ) ) { umap = (AstMapping *) astZoomMap( 1, AST__DR2D, " ", status ); extunit = "deg"; } else { extunit = intunit; } astSetUnit( wcsfrm, iax, extunit ); } } } /* If no change is needed for the mapping for this axis, use a UnitMap. */ if( !umap ) umap = (AstMapping *) astUnitMap( 1, " ", status ); /* Extend the parallel CmpMap to encompass the current axis. */ if( remap ) { tmap = (AstMapping *) astCmpMap( remap, umap, 0, " ", status ); (void) astAnnul( remap ); remap = tmap; } else { remap = astClone( umap ); } /* Free resources. */ umap = astAnnul( umap ); pframe = astAnnul( pframe ); } /* See if the pixel->wcs mapping needs to be modified to take account of any changes to axis units. */ smap = astSimplify( remap ); if( ! astIsAUnitMap( smap ) ) { tmap = (AstMapping *) astCmpMap( map, remap, 1, " ", status ); map = astAnnul( map ); remap = astAnnul( remap ); map = tmap; } /* If the supplied FrameSet is usable... */ if( ok ) { /* If we did not find a SpecFrame, return a FrameSet made from the base and current Frames in the supplied FrameSet. */ if( !specfrm ) { ret = astFrameSet( pixfrm, "", status ); astAddFrame( ret, AST__BASE, map, wcsfrm ); /* If we have a SpecFrame, proceed. */ } else { /* Check that both the RefRA and RefDec attributes of the SpecFrame are set. If not, return a FrameSet made from the base and current Frames in the supplied FrameSet. Also do this if the original WCS Frame contains 3 or more axes (since it is almost always inappropriate to add extra sky axes in such circumestances). But if the other axes form a skyfram, then we need to make sure they use the right refrence point. */ if( !astTestRefRA( specfrm ) || !astTestRefDec( specfrm ) || ( nwcs > 2 && !skyfrm ) ) { ret = astFrameSet( pixfrm, "", status ); astAddFrame( ret, AST__BASE, map, wcsfrm ); /* If we have a celestial reference position for the spectral axis, ensure it is described correctly by a pair of celestial axes. */ } else { /* If the WCS Frame does not contain any celestial axes, we add some now. */ if( !skyfrm ) { /* The easiest way to create the required mapping from pixel to celestial to create a simple FITS header and read it in via a FitsChan to create a FrameSet. */ fc = astFitsChan( NULL, NULL, "", status ); astPutFits( fc, "CRPIX1 = 0", 0 ); astPutFits( fc, "CRPIX2 = 0", 0 ); astPutFits( fc, "CDELT1 = 0.0003", 0 ); astPutFits( fc, "CDELT2 = 0.0003", 0 ); astPutFits( fc, "CTYPE1 = 'RA---TAN'", 0 ); astPutFits( fc, "CTYPE2 = 'DEC--TAN'", 0 ); astPutFits( fc, "RADESYS = 'FK5'", 0 ); astPutFits( fc, "EQUINOX = 2000.0", 0 ); sprintf( card, "CRVAL1 = %.*g", DBL_DIG, AST__DR2D*astGetRefRA( specfrm ) ); astPutFits( fc, card, 0 ); sprintf( card, "CRVAL2 = %.*g", DBL_DIG, AST__DR2D*astGetRefDec( specfrm ) ); astPutFits( fc, card, 0 ); sprintf( card, "MJD-OBS = %.*g", DBL_DIG, TDBConv( astGetEpoch( specfrm ), AST__UTC, 1, "astWrite", "FitsChan", status ) ); astPutFits( fc, card, 0 ); astClearCard( fc ); tfs = astRead( fc ); if( tfs ) { /* Create the new pixel->wcs Mapping. First get the 2-input,2-output Mapping between pixel and sky coords from the above FrameSet. Then add this Mapping in parallel with the original pixel->wcs Mapping. */ tmap0 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); tmap1 = (AstMapping *) astCmpMap( map, tmap0, 0, "", status ); tmap0 = astAnnul( tmap0 ); /* We now have a (npix+2)-input,(nwcs+2)-output Mapping. We now add a PermMap in series with this which feeds the constant value 0.0 (the CRPIX value in the above set of FITS headers) into the 2 pixel axes corresponding to RA and Dec. This PermMap has npix-inputs and (npix+2) outputs. The total Mapping then has npix inputs and (nwcs+2) outputs. */ perm = astMalloc( sizeof( int )*(size_t) ( npix + 2 ) ); if( astOK ) { for( iax = 0; iax < npix; iax++ ) perm[ iax ] = iax; perm[ npix ] = -1; perm[ npix + 1 ] = -1; con = 0.0; tmap0 = (AstMapping *) astPermMap( npix, perm, npix + 2, perm, &con, "", status ); tmap2 = (AstMapping *) astCmpMap( tmap0, tmap1, 1, "", status ); tmap0 = astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); /* We now create the new WCS Frame with the extra RA and Dec axes. This is just a CmpFrame made up of the original WCS Frame and the new SkyFrame. */ tfrm = astGetFrame( tfs, AST__CURRENT ); tfrm0 = (AstFrame *) astCmpFrame( wcsfrm, tfrm, "", status ); tfrm = astAnnul( tfrm ); /* Construct the returned FrameSet. */ ret = astFrameSet( pixfrm, "", status ); astAddFrame( ret, AST__BASE, tmap2, tfrm0 ); tmap2 = astAnnul( tmap2 ); tfrm0 = astAnnul( tfrm0 ); /* Free remaining resources. */ perm = astFree( perm ); } tfs = astAnnul( tfs ); } fc = astAnnul( fc ); /* If the WCS Frame does contain celestial axes we make sure that the SpecFrame uses the same reference point. */ } else { /* The returned FrameSet has no extra Frames (although some attributes may be changed) so just create a new FrameSet equaivalent to the supplied FrameSet. */ tfs = astFrameSet( pixfrm, "", status ); astAddFrame( tfs, AST__BASE, map, wcsfrm ); /* The RefRA and RefDec attributes of the SpecFrame must be set in FK5 J2000. Therefore we need to know the celestial reference point in FK5 J2000. Modify the SkyFrame within the FrameSet to represent FK5 J2000, noting the original sky system and equinox first so that they can be re-instated (if set) later on. */ sprintf( system_attr, "System(%d)", ilon + 1 ); if( astTest( tfs, system_attr ) ) { skysys = astGetC( tfs, system_attr ); } else { skysys = NULL; } astSetC( tfs, system_attr, "FK5" ); sprintf( equinox_attr, "Equinox(%d)", ilon + 1 ); if( astTest( tfs, equinox_attr ) ) { eqn = astGetC( tfs, equinox_attr ); } else { eqn = NULL; } astSetC( tfs, equinox_attr, "J2000" ); /* The reference point for the celestial axes is defined by the WcsMap contained within the Mapping. Split the mapping up into a list of serial component mappings, and locate the first WcsMap in this list. The first Mapping returned by this call is the result of compounding all the Mappings up to (but not including) the WcsMap, the second returned Mapping is the (inverted) WcsMap, and the third returned Mapping is anything following the WcsMap. Only proceed if one and only one WcsMap is found. */ tmap0 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); if( SplitMap( tmap0, astGetInvert( tmap0 ), ilon, ilat, &map1, &map2, &map3, status ) ){ /* The reference point in the celestial coordinate system is found by transforming the fiducial point in native spherical co-ordinates into absolute physical coordinates using map3. */ if( GetFiducialWCS( map2, map3, ilon, ilat, &reflon, &reflat, status ) ){ /* Use reflon and reflat (which represent FK5 J2000 RA and Dec) to set the values of the SpecFrame RefRA and RefDec attributes. Format the values first so that we can use the FrameSet astSetC method, and so maintain the FrameSet integrity. Use "tfs" rather than "wcsfrm" when calling astFormat, as "wcsfrm" is not affected by the above change to the current frame of "tfs" (i.e. astAddFrame takes a deep copy of the supplied Frame). */ astSetC( tfs, "RefRA", astFormat( tfs, ilon, reflon ) ); astSetC( tfs, "RefDec", astFormat( tfs, ilat, reflat ) ); /* If succesfull, return a pointer to the FrameSet. */ if( astOK ) ret = astClone( tfs ); } /* Release resources. */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); /* If no WcsMap was found, the celestial axes have no reference point and so we can retain the original spectral reference point, so just return the temporary FrameSet. */ } else if( astOK ) { ret = astClone( tfs ); } tmap0 = astAnnul( tmap0 ); /* Re-instate the original sky system and equinox. */ if( skysys ) astSetC( tfs, system_attr, skysys ); if( eqn ) astSetC( tfs, equinox_attr, eqn ); /* Release resources. */ tfs = astAnnul( tfs ); } } } } /* Add a new current Frame into the FrameSet which increases the chances of the requested encoding being usable. The index of the original current Frame is returned, or AST__NOFRAME if no new Frame was added. */ icurr = AddEncodingFrame( this, ret, encoding, method, class, status ); /* If a new Frame was added, remove the original current Frame. */ if( icurr != AST__NOFRAME ) astRemoveFrame( ret, icurr ); /* Free resources. */ if( specfrm ) specfrm = astAnnul( specfrm ); if( skyfrm ) skyfrm = astAnnul( skyfrm ); pixfrm = astAnnul( pixfrm ); wcsfrm = astAnnul( wcsfrm ); map = astAnnul( map ); /* Return NULL if an error has occurred. */ if( !astOK && ret ) ret = astAnnul( ret ); /* Return the result. */ return ret; } static void MakeIndentedComment( int indent, char token, const char *comment, const char *data, char string[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ], int *status ) { /* * Name: * MakeIndentedComment * Purpose: * Create a comment string containing an indentation bar. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void MakeIndentedComment( int indent, char token, * const char *comment, const char *data, * char string[ AST__FITSCHAN_FITSCARDLEN - * FITSNAMLEN + 1 ], int *status ) * Class Membership: * FitsChan member function. * Description: * This function creates a string that may be used as text in a * FITS comment card. The string contains a textual comment * preceded by a bar (a line of characters) whose length can be * used to indicate a level of indentation (in the absence of any * way of indenting FITS keywords). * Parameters: * indent * The level of indentation, in characters. * token * The character used to form the indentation bar. * comment * A pointer to a constant null-terminated string containing the text * of the comment to be included. * data * A pointer to a constant null-terminated string containing any * textual data to be appended to the comment. * string * A character array to receive the output string. * status * Pointer to the inherited status variable. * Notes: * - The comment text that appears in the output string is formed by * concatenating the "comment" and "data" strings. */ /* Local Variables: */ int i; /* Loop counter for input characters */ int len; /* Number of output characters */ int mxlen; /* Maximum length of output string */ /* Check the global error status. */ if ( !astOK ) return; /* Calculate the maximum number of characters that the output string can accommodate. */ mxlen = AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN; /* Start the string with "indent" copies of the token character, but without exceeding the output string length. */ len = 0; while ( ( len < indent ) && ( len < mxlen ) ) string[ len++ ] = token; /* Pad with spaces up to the start of the comment, if necessary. */ while ( len < ( FITSCOMCOL - FITSNAMLEN - 1 ) ) { string[ len++ ] = ' '; } /* Add "/ " to introduce the comment (strictly not necessary as the whole card will be a comment, but it matches the other non-comment cards). Truncate if necessary. */ for ( i = 0; ( i < 2 ) && ( len < mxlen ); i++ ) { string[ len++ ] = "/ "[ i ]; } /* Append the comment string, truncating it if it is too long. */ for ( i = 0; comment[ i ] && ( len < mxlen ); i++ ) { string[ len++ ] = comment[ i ]; } /* Append the data string, again truncating if too long. */ for ( i = 0; data[ i ] && ( len < mxlen ); i++ ) { string[ len++ ] = data[ i ]; } /* Terminate the output string. */ string[ len ] = '\0'; } static void MakeIntoComment( AstFitsChan *this, const char *method, const char *class, int *status ){ /* * Name: * MakeIntoComment * Purpose: * Convert a card into a FITS COMMENT card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void MakeIntoComment( AstFitsChan *this, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function formats the card stored just prior to the current card, * and re-stores it as a COMMENT card. It is used (when writing an Object * to a FitsChan) to output values that are not "set" and which are * therefore provided for information only, and should not be read back. * the COMMENT card has the effect of "commenting out" the value. * Parameters: * this * Pointer to the FitsChan. * method * Calling method. * class * Object class. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char card[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Character buffer for FITS card data */ /* Check the global error status. */ if ( !astOK ) return; /* Move the current card backwards by one card. */ MoveCard( this, -1, method, class, status ); /* Format the new current card. */ FormatCard( this, card, method, status ); /* Write the resulting string to the FitsChan as the contents of a COMMENT card, overwriting the existing card. The current card is incremented by this call so that it refers to the same card as on entry. */ astSetFitsCom( this, "COMMENT", card, 1 ); } static int MakeIntWorld( AstMapping *cmap, AstFrame *fr, int *wperm, char s, FitsStore *store, double *dim, const char *method, const char *class, int *status ){ /* * Name: * MakeIntWorld * Purpose: * Create FITS header values which map grid into intermediate world * coords. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int MakeIntWorld( AstMapping *cmap, AstFrame *fr, int *wperm, char s, * FitsStore *store, double *dim, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function adds values to the supplied FitsStore which describe * the transformation from grid (pixel) coords to intermediate world * coords. The values added to the FitsStore correspond to the CRPIXj, * PCi_j, CDELTi and WCSAXES keywords, and are determined by examining the * suppliedMapping, which must be linear with an optional shift of * origin (otherwise a value of zero is returned). * * Much of the complication in the algorithm arises from the need to * support cases where the supplied Mapping has more outputs than * inputs. In these case we add some "degenerate" axes to the grid * coord system, choosing their unit vectors to be orthogonal to all * the other grid axes. It is assumed that degenerate axes will never * be used to find a position other than at the axis value of 1.0. * * NOTE, appropriate values for CRVAL keywords should have been stored * in the FitsStore before calling this function (since this function may * modify them). * Parameters: * cmap * A pointer to a Mapping which transforms grid coordinates into * intermediate world coordinates. The number of outputs must be * greater than or equal to the number of inputs. * fr * Pointer to the final WCS coordinate Frame. * wperm * Pointer to an array of integers with one element for each axis of * the "fr" Frame. Each element holds the zero-based index of the * FITS-WCS axis (i.e. the value of "i" in the keyword names "CTYPEi", * "CDi_j", etc) which describes the Frame axis. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * store * A pointer to the FitsStore into which the calculated CRPIX and * CDi_j values are to be put. * dim * An array holding the image dimensions in pixels. AST__BAD can be * supplied for any unknwon dimensions. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if the CRPIX and CDi_j values are * succesfully calculated. Zero is returned otherwise. * Notes: * - Zero is returned if an error occurs. */ /* Local Variables: */ AstFrame *pfrm; AstFrame *sfrm; AstMapping *map; AstPointSet *psetw; AstPointSet *psetg; double **fullmat; double **partmat; double **ptrg; double **ptrw; double *c; double *cdelt; double *cdmat; double *colvec; double *d; double *g; double *g0; double *m; double *mat; double *tol; double *w0; double *y; double cd; double crp; double crv; double cv; double det; double err; double k; double mxcv; double skydiag1; double skydiag0; double val; int *iw; int *lin; int *pperm; int *skycol; int i; int ii; int j; int jax; int jj; int nin; int nout; int nwcs; int paxis; int ret; int sing; int skycol0; int skycol1; /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Simplify the supplied Mapping to reduce rounding errors when transforming points. */ map = astSimplify( cmap ); /* Get the number of inputs and outputs for the Mapping. Return if the number of outputs is smaller than the number of inputs. */ nin = astGetNin( map ); nout = astGetNout( map ); if( nout < nin ) return ret; /* Note the number of final World Coordinate axes (not necessarily the same as "nout", since some intermediate axes may be discarded by a later PermMap. */ nwcs = astGetNaxes( fr ); /* Allocate work space. */ g = astMalloc( sizeof(double)*(size_t) nin ); g0 = astMalloc( sizeof(double)*(size_t) nin ); w0 = astMalloc( sizeof(double)*(size_t) nout ); tol = astMalloc( sizeof(double)*(size_t) nout ); partmat = astMalloc( sizeof(double *)*(size_t) nout ); lin = astMalloc( sizeof(int)*(size_t) nout ); pperm = astMalloc( sizeof(int)*(size_t) nout ); skycol = astMalloc( sizeof(int)*(size_t) nout ); cdmat = astMalloc( sizeof(double)*(size_t) (nout*nout) ); cdelt = astMalloc( sizeof(double)*(size_t) nout ); /* For safety, initialise all other pointers. */ if( partmat ) for( j = 0; j < nout; j++ ) partmat[ j ] = NULL; fullmat = NULL; /* Create a PointSet to hold an input (grid) position for each axis, plus an extra one. Create two other PointSets to hold corresponding output (IWC) coordinates. */ psetg = astPointSet( nin + 1, nin, "", status ); ptrg = astGetPoints( psetg ); psetw = astPointSet( nin + 1, nout, "", status ); ptrw = astGetPoints( psetw ); /* Check the pointers can be used safely. */ if( astOK ) { /* Assume success. */ ret = 1; /* The next section finds a 'root' grid position for which the corresponding IWC coordinates are all good. It also finds these IWC coordinates, together with the IWC coordinates of "nin" points which are a unit distance away from the root grid position along each grid axis. It also finds an estimate of the rounding error in each Mapping output. ================================================================= */ ret = FindBasisVectors( map, nin, nout, dim, psetg, psetw, status ); /* Save the grid root position in "g0". */ for( j = 0; j < nin; j++ ) g0[ j ] = ptrg[ j ][ 0 ]; /* Save the transformed root position in "w0". This is the grid root position represented as a vector within the Intermediate World Coordinate system. */ for( j = 0; j < nout; j++ ) { w0[ j ] = ptrw[ j ][ 0 ]; /* Find the tolerance for positions on the j'th IWC axis. This is one tenth of the largest change in the j'th IWC axis value caused by moving out 1 pixel along any grid axis. */ tol[ j ] = 0.0; for( i = 0; i < nin; i++ ) { err = fabs( ptrw[ j ][ i + 1 ] - w0[ j ] ); if( err > tol[ j ] ) tol[ j ] = err; } tol[ j ] *= 0.1; /* If the tolerance is zero (e.g. as is produced for degenerate axes), then use a tolerance equal to a very small fraction of hte degenerate axis value. If the axis value is zero use a fixed small value. */ if( tol[ j ] == 0.0 ) tol[ j ] = w0[ j ]*DBL_EPSILON*1.0E5; if( tol[ j ] == 0.0 ) tol[ j ] = sqrt( DBL_MIN ); } /* The next section finds the CD matrix. ===================================== */ /* Initialise the CD matrix elements to "all missing". */ for( i = 0; i < nout*nout; i++ ) cdmat[ i ] = AST__BAD; /* The elements of column "j" of the CD matrix form a vector (in Intermediate World Coords) which corresponds to a unit vector along grid axis "j". We now find these vectors for all the grid axes represented by the inputs to the supplied Mapping. */ for( i = 0; i < nin && ret; i++ ) { /* Form a unit vector along the current input axis. */ for( ii = 0; ii < nin; ii++ ) g[ ii ] = 0.0; g[ i ] = 1.0; /* Fit a straight line (within IWC) to the current input axis of the Mapping. The IWC vector corresponding to a unit vector along the current input axis is returned if the Mapping is linear. A NULL pointer is returned if the Mapping is not linear. */ partmat[ i ] = FitLine( map, g, g0, w0, dim[ i ], tol, status ); /* If unsuccesful, indicate failure and break out of the loop. */ if( !partmat[ i ] ) { ret = 0; break; } } /* If the number of outputs for "map" is larger than the number of inputs, then we will still be missing some column vectors for the CDi_j matrix (which has to be square). We invent these such that the they are orthogonal to all the other column vectors. Only do this if the Mapping is linear. */ if( ret ) { fullmat = OrthVectorSet( nout, nin, partmat, status ); if( !fullmat ) ret = 0; } /* Check everything is OK. */ if( ret ) { /* Check that the full matrix is invertable, and if not, see if there is any way to make it invertable. */ MakeInvertable( fullmat, nout, dim, status ); /* Set up an array holding index of the Mapping output corresponding to each IWC axis (the inverse of "wperm"). Also look for matching pairs of celestial WCS axes. For the first such pair, note the corresponding column indices and the diagonal element of the matrix which gives the scaling for the axis (taking account of the permutation of WCS axes). Also note if the Mapping from intermediate world coords to final world coords is linear for each axis (this is assumed to be the case if the axis is part of a simple Frame). */ sfrm = NULL; skydiag0 = AST__BAD; skydiag1 = AST__BAD; skycol0 = -1; skycol1 = -1; for( i = 0; i < nout; i++ ) { pperm[ wperm[ i ] ] = i; astPrimaryFrame( fr, i, &pfrm, &paxis ); if( IsASkyFrame( pfrm ) ) { skycol[ wperm[ i ] ] = paxis + 1; lin[ i ] = 0; if( !sfrm ) { sfrm = astClone( pfrm ); skycol0 = wperm[ i ]; skydiag0 = fullmat[ skycol0 ][ i ]; } else if( sfrm == pfrm ) { skycol1 = wperm[ i ]; skydiag1 = fullmat[ skycol1 ][ i ]; } } else { skycol[ wperm[ i ] ] = 0; lin[ i ] = !strcmp( astGetClass( pfrm ), "Frame" ); } pfrm = astAnnul( pfrm ); } if( sfrm ) sfrm = astAnnul( sfrm ); /* We now have the complete CDi_j matrix. Now to find the CRPIX values. These are the grid coords of the reference point (which corresponds to the origin of Intermediate World Coords). The "w0" array currently holds the position of the root position, as a position within IWC, and the "g0" array holds the corresponding position in grid coordinates. We also have IWC vectors which correspond to unit vectors on each grid axis. The CRPIX values are defined by the matrix equation w0 = fullmat*( g0 - crpix ) The "g0" array only contains "nin" values. If nout>nin, then the missing g0 values will be assumed to be zero when we come to find the CRPIX values below. We use palDmat to solve this system of simultaneous equations to get crpix. The "y" array initially holds "w0" but is over-written to hold "g0 - crpix". */ mat = astMalloc( sizeof( double )*(size_t)( nout*nout ) ); y = astMalloc( sizeof( double )*(size_t) nout ); iw = astMalloc( sizeof( int )*(size_t) nout ); if( astOK ) { m = mat; for( i = 0; i < nout; i++ ) { for( j = 0; j < nout; j++ ) *(m++) = fullmat[ j ][ i ]; y[ i ] = w0[ i ]; } palDmat( nout, mat, y, &det, &sing, iw ); } mat = astFree( mat ); iw = astFree( iw ); /* Loop round all axes, storing the column vector pointer. */ for( j = 0; j < nout; j++ ) { colvec = fullmat[ j ]; /* Get the CRPIX values from the "y" vector created above by palDmat. First deal with axes for which there are Mapping inputs. */ if( j < nin ) { crp = g0[ j ] - y[ j ]; /* If this is a grid axis which has been created to represent a "missing" input to the mapping, we need to add on 1.0 to the crpix value found above. This is because the "w0" vector corresponds to a value of zero on any missing axes, but the FITS grid value for any missing axes is 1.0. */ } else { crp = 1.0 - y[ j ]; } /* Store the CD and CRPIX values for axes which correspond to inputs of "map". The CD matrix elements are stored in an array and are converted later to the corresponding PC and CDELT values. */ if( j < nin || crp == 0.0 ) { for( i = 0; i < nout; i++ ) { cdmat[ wperm[ i ]*nout+j ] = colvec[ i ] ; } SetItem( &(store->crpix), 0, j, s, crp, status ); /* The length of the unit vector along any "degenerate" axes was fixed arbitrarily at 1.0 by the call to OrthVectorSet. We can probably choose a more appropriate vector length. The choice shouldn't make any difference to the transformation, but an appropriate value will look more natural to human readers. */ } else { /* First, try to arrange for longitude/latitude axis pairs to have the same scale. Do we have a matching pair of celestial axes? */ k = AST__BAD; if( skydiag0 != AST__BAD && skydiag1 != AST__BAD ) { /* Is the current column the one which corresponds to the first celestial axis, and does the other sky column correspond to a Mapping input? */ if( skycol0 == j && skycol1 < nin ) { /* If so, scale this column so that its diagonal element is the negative of the diagonal element of the other axis. This is on the assumption that the scales on the two axes should be equal, and that longitude increases east whilst latitude increases north, and that the CD matrix does not introduce an axis permutation. */ if( skydiag0 != 0.0 ) k = -skydiag1/skydiag0; /* Now see if the current column the one which corresponds to the second celestial axis. Do the same as above. */ } else if( skycol1 == j && skycol0 < nin ) { if( skydiag1 != 0.0 ) k = -skydiag0/skydiag1; /* If neither of the above conditions was met, assume a diagonal element value of 1.0 degrees for latitude axes, and -1.0 degrees for longitude axes. */ } } /* If this failed, the next choice is to arrange for diagonally opposite elements to be equal and opposite in value. Look for the element of the column which has the largest diagonally opposite element, and choose a scaling factor which makes this column element equal to the negative value of its diagonally opposite element. Be careful to take axis permutations into account when finding the value of the diagonal element. */ if( k == AST__BAD ) { mxcv = 0.0; ii = pperm[ j ]; for( i = 0; i < nout; i++ ) { jj = wperm[ i ]; if( jj < nin ) { cv = fullmat[ jj ][ ii ]; if( !astEQUAL( colvec[ i ], 0.0 ) && fabs( cv ) > mxcv ) { mxcv = fabs( cv ); k = -cv/colvec[ i ]; } } } } /* If still no scaling factor is available, use a scaling factor which produces a diagonal element of 1.0 degree if the corresponding row is a sky latitude axis, -1.0 degree of sky longitude axes, and 1.0 for other axes. */ if( k == AST__BAD && colvec[ pperm[ j ] ] != 0.0 ) { if( skycol[ j ] ) { k = AST__DD2R/colvec[ pperm[ j ] ]; if( skycol[ j ] == 1 ) k = -k; } else { k = 1.0/colvec[ pperm[ j ] ]; } } /* If we still do not have a scaling, use 1.0 (no scaling). */ if( k == AST__BAD ) k = 1.0; /* Now scale and store the column elements. */ for( i = 0; i < nout; i++ ) { cdmat[ wperm[ i ]*nout+j ] = k*colvec[ i ]; } /* Find the corresponding modified CRPIX value and store it. */ crp = 1.0 + ( crp - 1.0 )/k; SetItem( &(store->crpix), 0, j, s, crp, status ); } /* Free resources */ if( pfrm ) pfrm = astAnnul( pfrm ); } /* Any "degenerate" axes added in the above process for which the intermediate->world mapping is linear, and which depend only on one pixel axis, can be adjusted so that the reference point is at grid coord 1.0. */ for( i = 0; i < nout; i++ ) { if( lin[ i ] ) { /* Check only one pixel axis contributes to this intermediate world axis and find which one it is. */ jax = -1; for( j = 0; j < nout; j++ ) { if( !astEQUAL( fullmat[ j ][ i ], 0.0 ) ) { if( jax == -1 ) { jax = j; } else { jax = -1; break; } } } /* We only adjust values for "degenerate" axes. */ if( jax >= nin ) { /* Check that this pixel axis only contributes to the single world axis currently being considered. */ for( ii = 0; ii < nout; ii++ ) { if( ii != i ) { if( !astEQUAL( fullmat[ jax ][ ii ], 0.0 ) ) { jax = -1; break; } } } if( jax != -1 ) { /* Get the original CRVAL, CRPIX and CD values. Check they are defined.*/ crv = GetItem( &(store->crval), wperm[ i ], 0, s, NULL, method, class, status ); cd = cdmat[ wperm[ i ]*nout + jax ]; crp = GetItem( &(store->crpix), 0, jax, s, NULL, method, class, status ); if( crv != AST__BAD && crp != AST__BAD && cd != AST__BAD ) { /* Modify the CRPIX to be 1.0 and modify the CRVAL value accordingly. */ SetItem( &(store->crpix), 0, jax, s, 1.0, status ); SetItem( &(store->crval), wperm[ i ], 0, s, cd*( 1.0 - crp ) + crv, status ); } } } } } /* Finally, if there are fewer input axes than output axes, put a value for the WCSAXES keyword into the store. */ if( nin < nwcs ) SetItem( &(store->wcsaxes), 0, 0, s, nwcs, status ); /* Release resources. */ y = astFree( y ); } /* Produce and store PC and CDELT values from the above CD matrix */ SplitMat( nout, cdmat, cdelt, status ); c = cdmat; d = cdelt; for( i = 0; i < nout; i++ ){ for( j = 0; j < nout; j++ ){ val = *(c++); if( i == j ){ if( astEQUAL( val, 1.0 ) ) val = AST__BAD; } else { if( astEQUAL( val, 0.0 ) ) val = AST__BAD; } if( val != AST__BAD ) SetItem( &(store->pc), i, j, s, val, status ); } SetItem( &(store->cdelt), i, 0, s, *(d++), status ); } } /* Annul pointsets. */ psetg = astAnnul( psetg ); psetw = astAnnul( psetw ); /* Free other resources*/ map = astAnnul( map ); if( fullmat ) for( j = 0; j < nout; j++ ) fullmat[ j ] = astFree( fullmat[ j ] ); if( partmat ) for( j = 0; j < nout; j++ ) partmat[ j ] = astFree( partmat[ j ] ); fullmat = astFree( fullmat ); partmat = astFree( partmat ); cdmat = astFree( cdmat ); cdelt = astFree( cdelt ); g = astFree( g ); g0 = astFree( g0 ); w0 = astFree( w0 ); tol = astFree( tol ); lin = astFree( lin ); skycol = astFree( skycol ); pperm = astFree( pperm ); /* If an error has occurred, return zero. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static void MakeInvertable( double **fullmat, int n, double *dim, int *status ){ /* * Name: * MakeInvertable * Purpose: * Modify a supplied square CD matrix if possible to make it invertable. * Type: * Private function. * Synopsis: * void MakeInvertable( double **fullmat, int n, double *dim, int *status ) * Class Membership: * FitsChan * Description: * A search is made for matrix inputs that have no effect on any * matrix outputs. if any such matrix inputs are associated with * degenerate pixel axes (i.e. pixel axes that span only a single * pixel), then the matrix input should always have the value zero and * so the corresponding diagonal element of the matrix can be set to * 1.0 without changing and of the outputs. * Parameters: * fullmat * A pointer to an array with "n" elements corresponding to the n * inputs of the matrix, each element being a pointer to an array * with "n" elements corresponding to the n outputs of the matrix. * n * The number of inputs and outputs for the square matrix. * dim * Pointer to an array of "n" input (i.e. pixel) axis dimensions. * Individual elements will be AST__BAD if dimensions are not known. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; /* Input index */ int j; /* Output index */ int unused; /* Does the current input have no effect on any output? */ /* Check inherited status */ if( !astOK ) return; /* Look for any inputs that have no effect on any of the outputs. If such an input is associated with a degenerate grid axis (i.e. a grid axis with a dimension of 1.0), then the input value will always be zero and so the corresponding diagonal element of the matrix can eb set to 1.0 without affecting the output value (which will always be zero since zero times anything is zero). Loop over all inputs. */ for( i = 0; i < n; i++ ) { /* Assume this input has no effect on any output. */ unused = 1; /* Loop over all outputs. */ for( j = 0; j < n; j++ ) { /* If the corresponding matrix term is non-zero, the the input will have an effect on the output, so set the unused flag false and break out of the output loop. */ if( fullmat[ i ][ j ] != 0.0 ) { unused = 0; break; } } /* If the input is unused, and it is associated with a degenerate pixel axis, we can set the corresponding diagonal element of the matrix to 1.0. */ if( unused && dim[ i ] == 1.0 ) fullmat[ i ][ i ] = 1.0; } } #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: * FitsChan 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: */ AstFitsChan *this; /* Pointer to FitsChan structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NUL. */ if( ! this_object ) return result; /* Obtain a pointers to the FitsChan structure. */ this = (AstFitsChan *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->keyseq, mode, extra, fail ); if( !result ) result = astManageLock( this->keywords, mode, extra, fail ); return result; } #endif static int Match( const char *test, const char *temp, int maxfld, int *fields, int *nfld, const char *method, const char *class, int *status ){ /* * Name: * Match * Purpose: * Sees if a test keyword name matches a template. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Match( const char *test, const char *temp, int maxfld, int *fields, * int *nfld, const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * All characters in the template other than "%" (and the field width * and type specifiers which follow a "%") must be matched by an * identical character (ignoring case) in the test string. If a "%" occurs * in the template, then the next character in the template should be a * single digit specifying a field width. If it is zero, then the test * string may contain zero or more matching characters. Otherwise, * the test string must contain exactly the specified number of matching * characters (i.e. 1 to 9). The field width digit may be omitted, in * which case the test string must contain one or more matching * characters. The next character in the template specifies the type of * matching characters and must be one of "d", "c" or "f". Decimal digits * are matched by "d", all upper (but not lower) case alphabetical * characters are matched by "c", and all characters which are legal within * a FITS keyword (i.e. upper case letters, digits, underscores and * hyphens) are matched by "f". * Parameters: * test * Pointer to a null terminated string holding the keyword name to * be tested. * temp * Pointer to a null terminated string holding the template. * maxfld * The maximum number of integer field values which should be * returned in "fields". * fields * A pointer to an array of at least "maxfld" integers. This is * returned holding the values of any integer fields specified * in the template. The values are extracted from the test string, * and stored in the order they appear in the template string. * nfld * Pointer to a location at which is returned the total number of * integer fields in the test string. This may be more than the * number returned in "fields" if "maxfld" is smaller than "*nfld". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the test string does not match the template * string, and one is returned if it does. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char type; /* Field type specifier */ const char *a; /* Pointer to next test character */ const char *b; /* Pointer to next template character */ int extend; /* Can the width of the first field be extended? */ int i; /* Field index */ int match; /* Does "test" match "temp"? */ int nfret; /* No. of fields returned */ int tmp; /* Field value */ /* Check global status. */ if( !astOK ) return 0; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* On the first entry to this function, indicate that no integer fields have yet been returned, and save a pointer to the start of the template string. */ if( !match_nentry ) { *nfld = 0; match_template = temp; } /* Increment the number of entries into this function. */ match_nentry++; /* Initialise pointers to the start of each string. */ a = test; b = temp; /* Initialise the returned flag to indicate that the two strings do not match. */ match = 0; /* Check that the initial part of the test string can match the first field in the template. */ if( MatchFront( a, b, &type, &extend, &match_na, &match_nb, method, class, match_template, status ) ){ /* If it does, increment the pointers to skip over the characters used up in the comparison. */ a += match_na; b += match_nb; /* If the ends of both strings have been reached, they match. */ if( *a == 0 && *b == 0 ){ match = 1; /* Otherwise, if the end of the template has been reached but there are still characters to be read from the test string, we could still have a match if all the remaining test characters match an extandable field. */ } else if( *b == 0 && *a != 0 && extend ){ /* Loop until all the matching characters have been read from the end of the test string. */ while( *a != 0 && MatchChar( *a, type, method, class, match_template, status ) ) a++; /* If we reached the end of the test string, we have a match. */ if( *a == 0 ) match = 1; /* Otherwise, we need to carry on checking the remaining fields. */ } else { /* Call this function recursively to see if the remainder of the strings match. */ if( Match( a, b, maxfld, fields, nfld, method, class, status ) ){ match = 1; /* If the remainder of the strings do not match, we may be able to make them match by using up some extra test characters on the first field. This can only be done if the first field has an unspecified field width, and if the next test character if of a type which matches the first field in the template. */ } else if( extend ){ /* Loop until all the suitable characters have been read from the test string. Break out of the loop early if we find a field width which results in the whole string matching. */ while( MatchChar( *a, type, method, class, match_template, status ) ){ a++; if( Match( a, b, maxfld, fields, nfld, method, class, status ) ){ match = 1; break; } } } } } /* If the strings match and the leading field is an integer, decode the field and store it in the supplied array (if there is room). */ if( match && type == 'd' && a > test ){ if( *nfld < maxfld ){ sprintf( match_fmt, "%%%dd", (int) ( a - test ) ); astSscanf( test, match_fmt, fields + *nfld ); } (*nfld)++; } /* Decrement the number of entries into this function. */ match_nentry--; /* If we are leaving this function for the last time, reverse the order of the returned integer fields so that they are returned in the same order that they occur in the template. */ if( !match_nentry ){ nfret = ( *nfld < maxfld ) ? (*nfld) : maxfld; match_pa = fields; match_pb = fields + nfret - 1; for( i = 0; i < nfret/2; i++ ){ tmp = *match_pa; *(match_pa++) = *match_pb; *(match_pb--) = tmp; } } /* Return the result. */ return match; } static int MatchChar( char test, char type, const char *method, const char *class, const char *template, int *status ){ /* * Name: * MatchChar * Purpose: * See if a given character is of a specified type. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int MatchChar( char test, char type, const char *method, * const char *class, const char *template, int *status ) * Class Membership: * FitsChan member function. * Description: * This function checks that the supplied test character belongs * to the set of characters specified by the parameter "type". * Parameters: * test * The character to test. * type * The character specifying the set of acceptable characters. This * should be one of the field type characters accepted by function * Match (e.g. "d", "c" or "f"). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * template * Pointer to the start of the whole template string, for use in error * messages. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the test character does not belongs to the * specified character set, and one is returned if it does. * Notes: * - An error is reported if the type specifier is not legal. * - Zero is returned if an error has already occurred, or if ths * function fails for any reason. */ /* Local Variables: */ int ret; /* Returned flag */ /* Check global status. */ ret = 0; if( !astOK ) return ret; /* Check for "d" specifiers (digits). */ if( type == 'd' ){ ret = isdigit( (int) test ); /* Check for "c" specifiers (upper case letters). */ } else if( type == 'c' ){ ret = isupper( (int) test ); /* Check for "s" specifiers (any legal FITS keyword character). */ } else if( type == 'f' ){ ret = isFits( (int) test ); /* Report an error for any other specifier. */ } else if( astOK ){ ret = 0; astError( AST__BDFMT, "%s(%s): Illegal field type or width " "specifier '%c' found in filter template '%s'.", status, method, class, type, template ); } /* Return the answer. */ return ret; } static int MatchFront( const char *test, const char *temp, char *type, int *extend, int *ntest, int *ntemp, const char *method, const char *class, const char *template, int *status ){ /* * Name: * MatchFront * Purpose: * Sees if the start of a test string matches the start of a template. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int MatchFront( const char *test, const char *temp, char *type, * int *extend, int *ntest, int *ntemp, * const char *method, const char *class, * const char *template ) * Class Membership: * FitsChan member function. * Description: * This function looks for a match between the first field in the * template string and the string at the start of the test string, * using the syntax described in function Match. * Parameters: * test * Pointer to a null terminated string holding the keyword name to * be tested. * temp * Pointer to a null terminated string holding the template. * type * Pointer to a location at which to return a character specifying the * sort of field that was matched. This will be one of the legal field * types accepted by Match (e.g. "d", "c" or "f"), or null (zero) if * the first field in the template string was a literal character (i.e. * did not start with a "%"). * extend * Pointer to a location at which to return a flag which will be non-zero * if the further test characters could be matched by the first field in * the template. This will be the case if the template field only * specifies a minimum number of matching characters (i.e. if the field * width can be extended). For instance, "%d" can be extended, but "%1d" * cannot. * ntest * Pointer to a location at which to return the number of characters * matched in the test string. This will be the minimum number allowed * by the template field. * ntemp * Pointer to a location at which to return the number of characters * read from the template string (i.e. the number of characters in the * field specification). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * template * Pointer to the start of the whole template string, for use in error * messages. * Returned Value: * Zero is returned if the test string starts with fewer than the * minimum number of characters matching the template string, and one * is returned if it does. * Notes: * - Zero is returned if an error has already occurred, or if this * function fails for any reason. */ /* Local Variables: */ const char *a; /* Pointer to next test character */ const char *b; /* Pointer to next template character */ int i; /* Character index */ int match; /* Does "test" match "temp"? */ /* Check global status. */ if( !astOK ) return 0; /* Initialise pointers to the start of each string. */ a = test; b = temp; /* Initialise the returned value to indicate that the strings match. */ match = 1; /* If the current character in the template is not a % sign, it must match the current character in the test string (except for case). */ if( *b != '%' ){ if( toupper( (int) *b ) != toupper( (int) *a ) ) { match = 0; /* If the characters match, return all the required information. */ } else { *type = 0; *extend = 0; *ntest = 1; *ntemp = 1; } /* If the current character of the template is a %, we need to match a field. */ } else { *ntemp = 3; /* The next character in the template string determines the field width. Get the lowest number of characters which must match in the test string, and set a flag indicating if this lowest limit can be extended. */ b++; if( *b == '0' ){ *ntest = 0; *extend = 1; } else if( *b == '1' ){ *ntest = 1; *extend = 0; } else if( *b == '2' ){ *ntest = 2; *extend = 0; } else if( *b == '3' ){ *ntest = 3; *extend = 0; } else if( *b == '4' ){ *ntest = 4; *extend = 0; } else if( *b == '5' ){ *ntest = 5; *extend = 0; } else if( *b == '6' ){ *ntest = 6; *extend = 0; } else if( *b == '7' ){ *ntest = 7; *extend = 0; } else if( *b == '8' ){ *ntest = 8; *extend = 0; } else if( *b == '9' ){ *ntest = 9; *extend = 0; /* If no field width was given, one or more test characters are matched. Step back a character so that the current character will be re-used as the type specifier. */ } else { *ntest = 1; *extend = 1; b--; (*ntemp)--; } /* The next template character gives the type of character which should be matched. */ b++; *type = *b; /* Report an error if the template string ended within the field specifier. */ if( !*b ){ match = 0; astError( AST__BDFMT, "%s(%s): Incomplete field specifier found " "at end of filter template '%s'.", status, method, class, template ); /* Otherwise, check that the test string starts with the minimum allowed number of characters matching the specified type. */ } else { for( i = 0; i < *ntest; i++ ){ if( !MatchChar( *a, *type, method, class, template, status ) ){ match = 0; break; } a++; } } } /* Return the answer. */ return match; } static void MarkCard( AstFitsChan *this, int *status ){ /* * Name: * MarkCard * Purpose: * Mark the current card as having been read into an AST object. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void MarkCard( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * The current card is marked as having been "provisionally used" in * the construction of an AST object. If the Object is constructed * succesfully, such cards are marked as having been definitely used, * and they are then considered to have been removed from the FitsChan. * Parameters: * this * Pointer to the FitsChan containing the list of cards. * status * Pointer to the inherited status variable. * Notes: * - The card remains the current card even though it is now marked * as having been read. */ int flags; /* Return if the global error status has been set, or the current card is not defined. */ if( !astOK || !this->card ) return; /* Set the PROVISIONALLY_USED flag in the current card, but only if the PROTECTED flag is not set. */ flags = ( (FitsCard *) this->card )->flags; if( !( flags & PROTECTED ) ) { ( (FitsCard *) this->card )->flags = flags | PROVISIONALLY_USED; } } static int MoveCard( AstFitsChan *this, int move, const char *method, const char *class, int *status ){ /* * Name: * MoveCard * Purpose: * Move the current card a given number of cards forward or backwards. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int MoveCard( AstFitsChan *this, int move, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The current card is increment by the given number of cards, ignoring * cards which have been read into an AST object if the ignore_used flag * is set non-zero. * Parameters: * this * Pointer to the FitsChan containing the list of cards. * move * The number of cards by which to move the current card. Positive * values move towards the end-of-file. Negative values move * towards the start of the file (i.e. the list head). * method * Pointer to string holding name of calling method. * class * Pointer to string holding object class. * status * Pointer to the inherited status variable. * Returned Value: * The number of cards actually moved. This may not always be equal to * the requested number (for instance, if the end or start of the * FitsChan is encountered first). * Notes: * - If the end-of-file is reached before the required number of * cards have been skipped, the current card is set NULL, to indicate * an end-of-file condition. * - If the start of the file is reached before the required number of * cards have been skipped, the current card is left pointing to the * first usable card. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ FitsCard *card; /* The current card */ FitsCard *card0; /* The previous non-deleted card */ int moved; /* The number of cards moved by so far */ /* Return if the supplied object is NULL or the FitsChan is empty, or zero movement is requested. */ if( !this || !this->head || !move ) return 0; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Get a pointer to the current card. */ card = (FitsCard *) this->card; /* Initialise the number of cards moved so far. */ moved = 0; /* First deal with positive movements (towards the end-of-file). */ if( move > 0 ){ /* Loop round moving on to the next card until the correct number of moves have been made, or the end-of-file is reached. */ while( moved < move && card ){ /* Get a pointer to the next card in the list, reporting an error if the links are inconsistent. */ card = GetLink( card, NEXT, method, class, status ); /* If we have moved past the last card and are now pointing back at the list head, then indicate that we are at end-of-file by setting the card pointer NULL. */ if( (void *) card == this->head ){ card = NULL; /* Otherwise, increment the number of cards moved. We ignore cards which have been read into an AST object if the external "ignore_used" flag is set. */ } else if( card ){ if( !CARDUSED(card) ) moved++; } } /* Now deal with negative movements (towards the list head), so long as we are not currently at the list head. */ } else if( (void *) card != this->head ){ /* If we are currently at end-of-file, replace the NULL pointer for the current card with a pointer to the list head. The first step backwards will make the last card the current card. */ if( !card ) card = (FitsCard *) this->head; /* Loop round until the correct number of cards have been moved. */ while( moved < -move && card ){ /* If cards which have been read into an AST object are to be included in the count of moved cards, get a pointer to the previous card in the list, reporting an error if the links are inconsistent. */ if( !ignore_used ){ card = GetLink( card, PREVIOUS, method, class, status ); /* If cards which have been read into an AST object are to be ignored... */ } else { /* We need to find the previous card which has not been read into an AST object. We do not search beyond the start of the list. */ card0 = GetLink( card, PREVIOUS, method, class, status ); while( card0 && CARDUSED(card0) && (void *) card0 != this->head ){ card0 = GetLink( card0, PREVIOUS, method, class, status ); } /* If no such card was found we leave the card where it is. */ if( card0 && ( card0->flags & USED ) ) { break; /* Otherwise, move back to card found above. */ } else { card = card0; } } /* Increment the number of cards moved. */ moved++; /* If the current card is the list head, break out of the loop. */ if( (void *) card == this->head ) break; } } /* Store the new current card. */ this->card = (void *) card; /* Return the answer. */ return moved; } static double NearestPix( AstMapping *map, double val, int axis, int *status ){ /* * Name: * NearestPix * Purpose: * Find an axis value which corresponds to an integer pixel value. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double NearestPix( AstMapping *map, double val, int axis, int *status ) * Class Membership: * FitsChan member function. * Description: * The supplied axis value is transformed using the inverse of the * supplied Mapping (other axes are given the value AST__BAD). The * resulting axis values are rounded to the nearest whole number, and * then transformed back using the supplied Mapping in the forward * direction. If the nominated axis value is good, it is returned as * the function value, otherwise the supplied value is returned unchanged. * Parameters: * map * A Mapping (usually the input coordinates will correspond to * pixel coordinates). * val * A value for one of the outputs of the "map" Mapping. * axis * The index of the Mapping output to which "val" refers. * status * Pointer to the inherited status variable. * Retuned Value: * The modified output axis value. */ /* Local Variables: */ AstMapping *tmap; /* Mapping to be used */ AstPointSet *pset1; /* Pixel coords PointSet */ AstPointSet *pset2; /* WCS coords PointSet */ double **ptr1; /* Pointer to data in pset1 */ double **ptr2; /* Pointer to data in pset2 */ double result; /* Returned value */ int *ins; /* Array holding input axis indices */ int i; /* Loop count */ int nin; /* Number of Mapping inputs */ int nout; /* Number of Mapping outputs */ /* Initialise. */ result = val; /* Check inherited status, and that the supplied value is good. */ if( !astOK || result == AST__BAD ) return result; /* If the supplied Mapping has no inverse, trying splitting off the transformation for the required axis, which may have an inverse. If succesful, use the 1-in,1-out Mapping returned by astMapSPlit instead of the supplied Mapping, and adjust the axis index accordingly. */ if( !astGetTranInverse( map ) ) { astInvert( map ); ins = astMapSplit( map, 1, &axis, &tmap ); if( tmap ) { astInvert( tmap ); axis = 0; } else { tmap = astClone( map ); } ins = astFree( ins ); astInvert( map ); } else { tmap = astClone( map ); } /* If the Mapping still has no inverse, return the supplied value unchanged. */ if( astGetTranInverse( tmap ) ) { /* Get the number of input and output coordinates. */ nin = astGetNin( tmap ); nout = astGetNout( tmap ); /* Create PointSets to hold a single input position and the corresponding output position. */ pset1 = astPointSet( 1, nin, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( 1, nout, "", status ); ptr2 = astGetPoints( pset2 ); if( astOK ) { /* Assign AST__BAD values to all output axes, except for the specified axis, which is given the supplied axis value. */ for( i = 0; i < nout; i++ ) ptr2[ i ][ 0 ] = AST__BAD; ptr2[ axis ][ 0 ] = val; /* Transform this output position into an input position. */ (void) astTransform( tmap, pset2, 0, pset1 ); /* Round all good axis values in the resulting input position to the nearest integer. */ for( i = 0; i < nin; i++ ) { if( ptr1[ i ][ 0 ] != AST__BAD ) { ptr1[ i ][ 0 ] = (int) ( ptr1[ i ][ 0 ] + 0.5 ); } } /* Transform this input position back into output coords. */ (void) astTransform( tmap, pset1, 1, pset2 ); /* If the resulting axis value is good, return it. */ if( ptr2[ axis ] [ 0 ] != AST__BAD ) result = ptr2[ axis ] [ 0 ]; } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); } tmap = astAnnul( tmap ); /* Return the result. */ return result; } static void NewCard( AstFitsChan *this, const char *name, int type, const void *data, const char *comment, int flags, int *status ){ /* * Name: * NewCard * Purpose: * Insert a new card in front of the current card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void NewCard( AstFitsChan *this, const char *name, int type, * const void *data, const char *comment, int flags, * int *status ) * Class Membership: * FitsChan member function. * Description: * The supplied keyword name, data type and value, and comment are * stored in a new FitsCard structure, and this structure is * inserted into the circular linked list stored in the supplied * FitsChan. It is inserted in front of the current card. * Parameters: * this * Pointer to the FitsChan containing the list of cards. * name * Pointer to a string holding the keyword name of the new card. * type * An integer value representing the data type of the keyword. * data * Pointer to the data associated with the keyword. * comment * Pointer to a null-terminated string holding a comment. * flags * The flags to assign to the card. * status * Pointer to the inherited status variable. * Notes: * - The new card is inserted into the list in front of the current card, * so that the "next" link from the new card points to the current card. * If the FitsChan is currently at end-of-file (indicated by a NULL * pointer being stored for the current card), then the card is appended * to the end of the list. The pointer to the current card is left * unchanged. * - Keyword names are converted to upper case before being stored. * - Any trailing white space in a string value is saved as supplied. * - Logical values are converted to zero or one before being stored. * - The "comment" and/or "data" pointers may be supplied as NULL. */ /* Local Variables: */ FitsCard *new; /* Pointer to the new card */ FitsCard *prev; /* Pointer to the previous card in the list */ char *b; /* Pointer to next stored character */ const char *a; /* Pointer to next supplied character */ int lval; /* Logical data value restricted to 0 or 1 */ int nc; /* No. of characters to store */ /* Check the global status. */ if( !astOK ) return; /* Get memory to hold the new FitsCard structure. */ new = (FitsCard *) astMalloc( sizeof( FitsCard ) ); /* Check the pointer can be used. */ if( astOK ){ /* Copy the keyword name, converting to upper case. */ a = name; b = new->name; while( *a ) *(b++) = (char) toupper( (int) *(a++) ); *b = 0; /* Ensure that a KeyMap exists to hold the keywords currently in the FitsChan. */ if( !this->keywords ) this->keywords = astKeyMap( " ", status ); /* Add the keyword name to the KeyMap. The value associated with the KeyMap entry is not used and is set arbitrarily to zero. */ astMapPut0I( this->keywords, new->name, 0, NULL ); /* Copy the data type. */ new->type = type; /* Copy any data (ignore any data supplied for an UNDEF value). */ if( data && type != AST__UNDEF ){ /* Logical values are converted to zero or one before being stored. */ if( type == AST__LOGICAL ){ lval = *( (int *) data ) ? 1 : 0; new->size = sizeof( int ); new->data = astStore( NULL, (void *) &lval, sizeof( int ) ); /* String values... */ } else if( type == AST__STRING || type == AST__CONTINUE ){ /* Find the number of characters excluding the trailing null character. */ nc = strlen( data ); /* Store the string, reserving room for a terminating null. */ new->size = (size_t)( nc + 1 ); new->data = astStore( NULL, (void *) data, (size_t)( nc + 1 ) ); /* Terminate it. */ ( (char *) new->data)[ nc ] = 0; /* Other types are stored as supplied. */ } else if( type == AST__INT ){ new->size = sizeof( int ); new->data = astStore( NULL, (void *) data, sizeof( int ) ); } else if( type == AST__FLOAT ){ new->size = sizeof( double ); new->data = astStore( NULL, (void *) data, sizeof( double ) ); } else if( type == AST__COMPLEXF ){ if( *( (double *) data ) != AST__BAD ) { new->size = 2*sizeof( double ); new->data = astStore( NULL, (void *) data, 2*sizeof( double ) ); } else { nc = strlen( BAD_STRING ); new->size = (size_t)( nc + 1 ); new->data = astStore( NULL, BAD_STRING, (size_t)( nc + 1 ) ); ( (char *) new->data)[ nc ] = 0; } } else if( type == AST__COMPLEXI ){ new->size = 2*sizeof( int ); new->data = astStore( NULL, (void *) data, 2*sizeof( int ) ); } else { new->size = 0; new->data = NULL; } } else { new->size = 0; new->data = NULL; } /* Find the first non-blank character in the comment, and find the used length of the remaining string. We retain leading and trailing white space if the card is a COMMENT card. */ if( comment ){ a = comment; if( type != AST__COMMENT ) { while( isspace( *a ) ) a++; nc = ChrLen( a, status ); } else { nc = strlen( a ); } } else { nc = 0; } /* Copy any comment, excluding leading and trailing white space unless this is a COMMENT card */ if( nc > 0 ){ new->comment = astStore( NULL, (void *) a, (size_t)( nc + 1 ) ); ( (char *) new->comment)[ nc ] = 0; } else { new->comment = NULL; } /* Set the supplied flag values. */ new->flags = flags; /* Insert the copied card into the list, in front of the current card. If the current card is the list head, make the new card the list head. */ if( this->card ){ prev = ( ( FitsCard *) this->card )->prev; ( ( FitsCard *) this->card )->prev = new; new->prev = prev; prev->next = new; new->next = (FitsCard *) this->card; if( this->card == this->head ) this->head = (void *) new; /* If the FitsChan is at end-of-file, append the new card to the end of the list (i.e. insert it just before the list head). */ } else { if( this->head ){ prev = ( (FitsCard *) this->head )->prev; ( (FitsCard *) this->head )->prev = new; new->prev = prev; prev->next = new; new->next = (FitsCard *) this->head; /* If there are no cards in the list, start a new list. */ } else { new->prev = new; new->next = new; this->head = (void *) new; this->card = NULL; } } } /* Return. */ return; } static AstMapping *NonLinSpecWcs( AstFitsChan *this, char *algcode, FitsStore *store, int i, char s, AstSpecFrame *specfrm, const char *method, const char *class, int *status ) { /* * Name: * NonLinSpecWcs * Purpose: * Create a Mapping describing a FITS-WCS non-linear spectral algorithm * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *NonLinSpecWcs( AstFitsChan *this, char *algcode, * FitsStore *store, int i, char s, * AstSpecFrame *specfrm, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function uses the contents of the supplied FitsStore to create * a Mapping which goes from Intermediate World Coordinate (known as "w" * in the context of FITS-WCS paper III) to the spectral system * described by the supplied SpecFrame. * * The returned Mapping implements the non-linear "X2P" algorithms * described in FITS-WCS paper III. The axis is linearly sampled in * system "X" but expressed in some other system (specified by the * supplied SpecFrame). * Parameters: * this * Pointer to the FitsChan. * algcode * Pointer to a string holding the non-linear "-X2P" code for the * required algorithm. This includes aleading "-" character. * store * Pointer to the FitsStore structure holding the values to use for * the WCS keywords. * i * The zero-based index of the spectral axis within the FITS header * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * specfrm * Pointer to the SpecFrame. This specified the "S" system - the * system in which the CRVAL kewyords (etc) are specified. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a Mapping, or NULL if an error occurs. */ /* Local Variables: */ AstFrameSet *fs; AstMapping *map1; AstMapping *ret; AstSpecFrame *xfrm; AstMapping *map2; char buf[ 100 ]; char pc; double crv; double ds; double in_a; double in_b; double out_a; double out_b; int ok; int s_sys; /* Check the global status. */ ret = NULL; if( !astOK ) return ret; /* Identify the spectral "X" system within the "X2P" algorithm code, and create a SpecFrame describing the X system ("X" is the system in which the axis is linearly sampled). This is done by copying the supplied SpecFrame and then setting its System attribute. Copying the supplied SpecFrame ensures that all the other attributes (RestFreq, etc.) are set correctly. */ ok = 1; xfrm = astCopy( specfrm ); if( algcode[ 1 ] == 'F' ) { astSetSystem( xfrm, AST__FREQ ); astSetUnit( xfrm, 0, "Hz" ); } else if( algcode[ 1 ] == 'W' ) { astSetSystem( xfrm, AST__WAVELEN ); astSetUnit( xfrm, 0, "m" ); } else if( algcode[ 1 ] == 'V' ) { astSetSystem( xfrm, AST__VREL ); astSetUnit( xfrm, 0, "m/s" ); } else if( algcode[ 1 ] == 'A' ) { astSetSystem( xfrm, AST__AIRWAVE ); astSetUnit( xfrm, 0, "m" ); } else { ok = 0; } /* If the X system was identified, find a Mapping from the "S" (specfrm) system to the X system. */ map1 = NULL; if( ok ) { ok = 0; fs = astConvert( specfrm, xfrm, "" ); if( fs ) { map1 = astGetMapping( fs, AST__BASE, AST__CURRENT ); fs = astAnnul( fs ); ok = 1; } /* Issue a warning if the "P" system is not the correct one for the given "S" system. We can however continue, sine AST interprets illegal "P" systems correctly. */ pc = 0; s_sys = astGetSystem( specfrm ); if( s_sys == AST__FREQ || s_sys == AST__ENERGY || s_sys == AST__WAVENUM || s_sys == AST__VRADIO ) { pc = 'F'; } else if( s_sys == AST__WAVELEN || s_sys == AST__VOPTICAL || s_sys == AST__REDSHIFT ){ pc = 'W'; } else if( s_sys == AST__AIRWAVE ) { pc = 'A'; } else if( s_sys == AST__BETA || s_sys == AST__VREL ) { pc = 'V'; } else if( astOK ) { pc = algcode[ 3 ]; astError( AST__INTER, "%s: Function NonLinSpecWcs does not yet " "support spectral axes of type %s (internal AST " "programming error).", status, method, astGetC( specfrm, "System" ) ); } if( algcode[ 3 ] != pc ) { sprintf( buf, "The spectral CTYPE value %s%s is not legal - " "using %s%.3s%c instead.", astGetC( specfrm, "System" ), algcode, astGetC( specfrm, "System" ), algcode, pc ); Warn( this, "badctype", buf, method, class, status ); } } /* If succesfull, use this Mapping to find the reference value (CRVAL) in the "X" system. */ if( ok ) { /* Get the CRVAL value for the spectral axis (this will be in the S system). */ crv = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( crv == AST__BAD ) crv = 0.0; /* Convert it to the X system. */ astTran1( map1, 1, &crv, 1, &crv ); /* Invert this Mapping so that it forward transformation goes from X to S. */ astInvert( map1 ); /* Find the rate of change of S with respect to X (dS/dX) at the reference point (x = crv). */ ds = astRate( map1, &crv, 0, 0 ); if( ds != AST__BAD && ds != 0.0 ) { /* FITS-WCS paper III says that dS/dw must be 1.0 at the reference point. Therefore dX/dw = dX/dS at the reference point. Also, since the spectral axis is linear in X, dX/dw must be constant. Therefore the Mapping from IWC to X is a WinMap which scales the IWC axis ("w") by dX/dw and adds on the X value at the reference point. */ if( crv != 0.0 ) { in_a = 0.0; out_a = crv; in_b = crv*ds; out_b = 2.0*crv; map2 = (AstMapping *) astWinMap( 1, &in_a, &in_b, &out_a, &out_b, "", status ); } else { map2 = (AstMapping *) astZoomMap( 1, 1.0/ds, "", status ); } /* The Mapping to be returned is the concatenation of the above Mapping (from w to X) with the Mapping from X to S. */ ret = (AstMapping *) astCmpMap( map2, map1, 1, "", status ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } } xfrm = astAnnul( xfrm ); /* Return the result */ return ret; } static double *OrthVector( int n, int m, double **in, int *status ){ /* * Name: * OrthVector * Purpose: * Find a unit vector which is orthogonal to a set of supplied vectors. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double *OrthVector( int n, int m, double **in, int *status ) * Class Membership: * FitsChan member function. * Description: * A set of M vectors is supplied, each vector being N-dimensional. * It is assumed that M < N and that the supplied vectors span M * axes within the N dimensional space. An N-dimensional unit vector is * returned which is orthogonal to all the supplied vectors. * * The required vector is orthogonal to all the supplied vectors. * Therefore the dot product of the required vector with each of the * supplied vectors must be zero. This gives us M equations of the * form: * * a1*r1 + a2*r2 + a3*r3 + .... + aN*rN = 0.0 * b1*r1 + b2*r2 + b3*r3 + .... + bN*rN = 0.0 * ... * * where (a1,a2,..,aN), (b1,b2,..,bN), ... are the supplied vectors * and (r1,r2,...,rN) is the required vector. Since M is less * than N the system of linear simultaneous equations is under * specified and we need to assign arbitrary values to some of the * components of the required vector in order to allow the equations * to be solved. We arbitrarily assume that 1 element of the required * vector has value 1.0 and (N-M-1) have value zero. The selection of * *which* elements to set constant is based on the magnitudes of the * columns of coefficients (a1,b1...), (a2,b2,...), etc. The M components * of the required vector which are *not* set constant are the ones which * have coefficient columns with the *largest* magnitude. This choice is * made in order to minimise the risk of the remaining matrix of * coefficients being singular (for instance, if a component of the * required vector has a coefficient of zero in every supplied vector * then the column magnitude will be zero and that component will be * set to 1.0). After choosing the M largest columns, the largest * remaining column is assigned a value of 1.0 in the required vector, * and all other columns are assigned the value zero in the required * vector. This means that the above equations becomes: * * a1*r1 + a2*r2 + a3*r3 + .... + aM*rM = -aM+1 * b1*r1 + b2*r2 + b3*r3 + .... + bM*rM = -bM+1 * ... * * Where the indices are now not direct indices into the supplied and * returned vectors, but indices into an array of indices which have * been sorted into column magnitude order. This is now a set of MxM * simultaneous linear equations which we can solve using palDmat: * * MAT.R = V * * where MAT is the the matrix of columns (coefficients) on the left * hand side of the above set of simultaneous equations, R is the * required vector (just the components which have *not* been set * constant), and V is a constant vector equal to the column of values * on the right hand side in the above set of simultaneous equations. * The palDmat function solves this equation to obtain R. * Parameters: * n * The number of dimensions * m * The number of supplied vectors. * in * A pointer to an array with "m" elements, each element being a * pointer to an array with "n" elements. Each of these "n" element * array holds one of the supplied vectors. * status * Pointer to the inherited status variable. * Returned Value: * The pointer to some newly allocated memory holding the returned N * dimensional unit vector. The memory should be freed using astFree when * no longer needed. * Notes: * - NULL is returned if an error occurs. * - NULL is returned (without error) if the required vector cannot * be found (.e.g becuase the supplied M vectors span less than M axes). */ /* Local Variables: */ double *colmag; double *d; double *e; double *mat; double *mel; double *ret; double *rhs; double det; double sl; int *colperm; int *iw; int done; int i; int ih; int ii; int il; int j; int sing; /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Return if any of the M supplied vectors are NULL. */ for( i = 0; i < m; i++ ) { if( !in[ i ] ) return ret; } /* Allocate rquired memory. */ ret = astMalloc( sizeof( double )*(size_t) n ); rhs = astMalloc( sizeof( double )*(size_t) m ); mat = astMalloc( sizeof( double )*(size_t) m*m ); iw = astMalloc( sizeof( int )*(size_t) m ); colmag = astMalloc( sizeof( double )*(size_t) n ); colperm = astMalloc( sizeof( int )*(size_t) n ); /* Check memory can be used safely. */ if( astOK ) { /* Find the magnitude of each column of coefficients in the full set of simultaneous linear equations (before setting any components of the required vector constant). Also initialise the column permutation array to indicate that the columns are in their original order. The outer loop loops through the columns and the inner loop loops through rows (i.e. equations). */ for( i = 0; i < n; i++ ) { colperm[ i ] = i; colmag[ i ] = 0.0; for( j = 0; j < m; j++ ) { colmag[ i ] += in[ j ][ i ]*in[ j ][ i ]; } } /* Now re-arrange the column indices within the permutation array so that they are in order of decreasing ciolumn magnitude (i.e. colperm[0] will be left holding the index of the column with the largest magnitude). A simple bubble sort is used. */ ii = 1; done = 0; while( !done ) { done = 1; for( i = ii; i < n; i++ ) { ih = colperm[ i ]; il = colperm[ i - 1 ]; if( colmag[ ih ] > colmag[ il ] ) { colperm[ i ] = il; colperm[ i - 1 ] = ih; done = 0; } } ii++; } /* The first M elements in "colperm" now hold the indices of the columns which are to be used within the MAT matrix, the next element of "colperm" hold the index of the column which is to be included in the V vector (other elements hold the indices of the columns which are being ignored because they will be mutiplied by a value of zero - the assumed value of the corresponding components of the returned vector). We now copy the these values into arrays which can be passed to palDmat. First, initialise a pointer used to step through the mat array. */ mel = mat; /* Loop through all the supplied vectors. Get a pointer to the first element of the vector. */ for( i = 0; i < m; i++ ) { d = in[ i ]; /* Copy the required M elements of this supplied vector into the work array which will be passed to palDmat. */ for( j = 0; j < m; j++ ) *(mel++) = d[ colperm[ j ] ]; /* Put the next right-hand side value into the "rhs" array. */ rhs[ i ] = -d[ colperm[ m ] ]; } /* Use palDmat to find the first M elements of the returned array. These are stored in "rhs", over-writing the original right-hand side values. */ palDmat( m, mat, rhs, &det, &sing, iw ); /* If the supplied vectors span fewer than M axes, the above call will fail. In this case, annul the returned vector. */ if( sing != 0 ) { ret = astFree( ret ); /* If succesful, copy the M elements of the solution vector into the required M elements of the returned vector. Also find the squared length of the vector. */ } else { sl = 0.0; e = rhs; for( j = 0; j < m; j++ ) { sl += (*e)*(*e); ret[ colperm[ j ] ] = *(e++); } /* Put 1.0 into the next element of the returned vector. */ sl += 1.0; ret[ colperm[ m ] ] = 1.0; /* Fill up the rest of the returned vector with zeros. */ for( j = m + 1; j < n; j++ ) ret[ colperm[ j ] ] = 0.0; /* Normalise the returned vector so that it is a unit vector.Also ensure that any zeros are "+0.0" insteasd of "-0.0". */ e = ret; sl = sqrt( sl ); for( j = 0; j < n; e++,j++ ) { *e /= sl; if( *e == 0.0 ) *e = 0.0; } } } /* Free workspace. */ rhs = astFree( rhs ); mat = astFree( mat ); iw = astFree( iw ); colmag = astFree( colmag ); colperm = astFree( colperm ); /* Free the returned vector if an error has occurred. */ if( !astOK ) ret = astFree( ret ); /* Return the answer. */ return ret; } static double **OrthVectorSet( int n, int m, double **in, int *status ){ /* * Name: * OrthVectorSet * Purpose: * Find a set of mutually orthogonal vectors. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double **OrthVectorSet( int n, int m, double **in, int *status ) * Class Membership: * FitsChan member function. * Description: * A set of M vectors is supplied, each vector being N-dimensional. * It is assumed that the supplied vectors span M axes within the * N dimensional space. A pointer to a set of N vectors is returned. * The first M returned vectors are copies of the M supplied vectors. * The remaining returned vectors are unit vectors chosen to be * orthogonal to all other vectors in the returned set. * Parameters: * n * The number of dimensions * m * The number of supplied vectors. * in * A pointer to an array with "m" elements, each element being a * pointer to an array with "n" elements. Each of these "n" element * array holds one of the supplied vectors. * status * Pointer to the inherited status variable. * Returned Value: * The pointer to some newly allocated memory holding the returned N * vectors. The pointer locates an array of N elements, each of which * is a pointer to an array holding the N elements of a single vector. * The memory (including the inner pointers) should be freed using * astFree when no longer needed. * Notes: * - NULL is returned if an error occurs. * - NULL is returned (without error) if the required vectors cannot * be found (e.g. becuase the supplied M vectors span less than M axes). */ /* Local Variables: */ double **ret; int i; int bad; /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Allocate required memory. */ ret = astMalloc( sizeof( double * )*(size_t) n ); /* Check memory can be used safely. */ bad = 0; if( astOK ) { /* Copy the supplied vectors into the returned array. */ for( i = 0; i < m; i++ ) { ret[ i ] = astStore( NULL, in[ i ], sizeof( double )*n ); } /* For the remaining vectors, find a vector which is orthogonal to all the vectors currently in the returned set. */ for( ; i < n; i++ ) { ret[ i ] = OrthVector( n, i, ret, status ); if( !ret[ i ] ) bad = 1; } } /* Free the returned vectors if an error has occurred. */ if( bad || !astOK ) { for( i = 0; ret && i < n; i++ ) ret[ i ] = astFree( ret[ i ] ); ret = astFree( ret ); } /* Return the answer. */ return ret; } static AstMapping *OtherAxes( AstFitsChan *this, AstFrameSet *fs, double *dim, int *wperm, char s, FitsStore *store, double *crvals, int *axis_done, const char *method, const char *class, int *status ){ /* * Name: * OtherAxes * Purpose: * Add values to a FitsStore describing unknown axes in a Frame. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *OtherAxes( AstFitsChan *this, AstFrameSet *fs, double *dim, * int *wperm, char s, FitsStore *store, * double *crvals, int *axis_done, * const char *method, const char *class, * int *status ) * Class Membership: * FitsChan member function. * Description: * FITS WCS keyword values are added to the supplied FitsStore which * describe any as yet undescribed axes in the supplied FrameSet. These * axes are assumed to be linear and to follow the conventions * of FITS-WCS paper I (if in fact they are not linear, then the * grid->iwc mapping determined by MakeIntWorld will not be linear and * so the axes will be rejected). * * Note, this function does not store values for keywords which define * the transformation from pixel coords to Intermediate World Coords * (CRPIX, PC and CDELT), but a Mapping is returned which embodies these * values. This Mapping is from the current Frame in the FrameSet (WCS * coords) to a Frame representing IWC. The IWC Frame has the same number * of axes as the WCS Frame which may be greater than the number of base * Frame (i.e. pixel) axes. * Parameters: * this * Pointer to the FitsChan. * fs * Pointer to the FrameSet. The base Frame should represent FITS pixel * coordinates, and the current Frame should represent FITS WCS * coordinates. The number of base Frame axes should not exceed the * number of current Frame axes. * dim * An array holding the image dimensions in pixels. AST__BAD can be * supplied for any unknwon dimensions. * wperm * Pointer to an array of integers with one element for each axis of * the current Frame. Each element holds the zero-based * index of the FITS-WCS axis (i.e. the value of "i" in the keyword * names "CTYPEi", "CRVALi", etc) which describes the Frame axis. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * store * The FitsStore in which to store the FITS WCS keyword values. * crvals * Pointer to an array holding the default CRVAL value for each * axis in the WCS Frame. * axis_done * An array of flags, one for each Frame axis, which indicate if a * description of the corresponding axis has yet been stored in the * FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * If any axis descriptions were added to the FitsStore, a Mapping from * the current Frame of the supplied FrameSet, to the IWC Frame is returned. * Otherwise, a UnitMap is returned. Note, the Mapping only defines the IWC * transformation for the described axes. Any other (previously * described) axes are passed unchanged by the returned Mapping. */ /* Local Variables: */ AstFitsTable *table; /* Pointer to structure holding -TAB table info */ AstFrame *wcsfrm; /* WCS Frame within FrameSet */ AstMapping *axmap; /* Mapping from WCS to IWC */ AstMapping *map; /* FITS pixel->WCS Mapping */ AstMapping *ret; /* Returned Mapping */ AstMapping *tmap0; /* Pointer to a temporary Mapping */ AstMapping *tmap1; /* Pointer to a temporary Mapping */ AstPermMap *pm; /* PermMap pointer */ AstPointSet *pset1; /* PointSet holding central pixel position */ AstPointSet *pset2; /* PointSet holding reference WCS position */ char buf[80]; /* Text buffer */ const char *lab; /* Pointer to axis Label */ const char *sym; /* Pointer to axis Symbol */ double **ptr1; /* Pointer to data for pset1 */ double **ptr2; /* Pointer to data for pset2 */ double *lbnd_p; /* Pointer to array of lower pixel bounds */ double *ubnd_p; /* Pointer to array of upper pixel bounds */ double crval; /* The value for the FITS CRVAL keyword */ int *inperm; /* Pointer to permutation array for input axes */ int *outperm; /* Pointer to permutation array for output axes */ int extver; /* Table version number for -TAB headers */ int fits_i; /* FITS WCS axis index */ int i; /* Loop count */ int iax; /* WCS Frame axis index */ int icolindex; /* Index of table column holding index vector */ int icolmain; /* Index of table column holding main coord array */ int interp; /* Interpolation method for look-up tables */ int log_axis; /* Is the axis logarithmically spaced? */ int nother; /* Number of axes still to be described */ int npix; /* Number of pixel axes */ int nwcs; /* Number of WCS axes */ int tab_axis; /* Can the axis be described by the -TAB algorithm? */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Get the number of WCS axes. */ nwcs = astGetNaxes( fs ); /* Count the number of WCS axes which have not yet been described. */ nother = 0; for( iax = 0; iax < nwcs; iax++ ) { if( ! axis_done[ iax ] ) nother++; } /* Only proceed if there are some axes to described. */ if( nother ) { /* Get a pointer to the WCS Frame. */ wcsfrm = astGetFrame( fs, AST__CURRENT ); /* Get a pointer to the pixel->wcs Mapping. */ map = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Store the number of pixel and WCS axes. */ npix = astGetNin( fs ); nwcs = astGetNout( fs ); /* Store the upper and lower pixel bounds. */ lbnd_p = astMalloc( sizeof( double )*(size_t) npix ); ubnd_p = astMalloc( sizeof( double )*(size_t) npix ); if( astOK ) { for( iax = 0; iax < npix; iax++ ) { lbnd_p[ iax ] = 1.0; ubnd_p[ iax ] = ( dim[ iax ] != AST__BAD ) ? dim[ iax ] : 500; } } /* Transform the central pixel coords into WCS coords */ pset1 = astPointSet( 1, npix, "", status ); ptr1 = astGetPoints( pset1 ); pset2 = astPointSet( 1, nwcs, "", status ); ptr2 = astGetPoints( pset2 ); if( astOK ) { for( iax = 0; iax < npix; iax++ ) { ptr1[ iax ][ 0 ] = ( dim[ iax ] != AST__BAD ) ? floor( 0.5*dim[ iax ] ) : 1.0; } (void) astTransform( map, pset1, 1, pset2 ); } /* Loop round all WCS axes, producing descriptions of any axes which have not yet been described. */ for( iax = 0; iax < nwcs && astOK; iax++ ) { if( ! axis_done[ iax ] ) { /* Get the (one-based) FITS WCS axis index to use for this Frame axis. */ fits_i = wperm[ iax ]; /* Use the supplied default CRVAL value. If bad, use the WCS value corresponding to the central pixel found above (if this value is bad, abort). */ crval = crvals ? crvals[ iax ] : AST__BAD; if( crval == AST__BAD ) crval = ptr2[ iax ][ 0 ]; if( crval == AST__BAD ) { break; } else { SetItem( &(store->crval), fits_i, 0, s, crval, status ); } /* Initialise flags indicating the type of the axis. */ log_axis = 0; tab_axis = 0; /* Get the table version number to use if we end up using the -TAB algorithm. This is the set value of the TabOK attribute (if positive). */ extver = astGetTabOK( this ); /* See if the axis is linear. If so, create a ShiftMap which subtracts off the CRVAL value. */ if( IsMapLinear( map, lbnd_p, ubnd_p, iax, status ) ) { crval = -crval; tmap0 = (AstMapping *) astShiftMap( 1, &crval, "", status ); axmap = AddUnitMaps( tmap0, iax, nwcs, status ); tmap0 = astAnnul( tmap0 ); crval = -crval; /* If it is not linear, see if it is logarithmic. If the "log" algorithm is appropriate (as defined in FITS-WCS paper III), the supplied Frame (s) is related to pixel coordinate (p) by s = Sr.EXP( a*p - b ). If this is the case, the log of s will be linearly related to pixel coordinates. Test this. If the test is passed a Mapping is returned from WCS to IWC. */ } else if( (axmap = LogAxis( map, iax, nwcs, lbnd_p, ubnd_p, crval, status ) ) ) { log_axis = 1; /* If it is not linear or logarithmic, and the TabOK attribute is non-zero, describe it using the -TAB algorithm. */ } else if( extver > 0 ){ /* Get any pre-existing FitsTable from the FitsStore. This is the table in which the tabular data will be stored (if the Mapping can be expressed in -TAB form). */ if( !astMapGet0A( store->tables, AST_TABEXTNAME, &table ) ) table = NULL; /* See if the Mapping can be expressed in -TAB form. */ tmap0 = IsMapTab1D( map, 1.0, NULL, wcsfrm, dim, iax, fits_i, &table, &icolmain, &icolindex, &interp, status ); if( tmap0 ) { tab_axis = 1; /* The values stored in the table index vector are GRID coords. So we need to ensure that IWC are equivalent to GRID coords. So set CRVAL to zero. */ crval = 0.0; /* Store TAB-specific values in the FitsStore. First the name of the FITS binary table extension holding the coordinate info. */ SetItemC( &(store->ps), fits_i, 0, s, AST_TABEXTNAME, status ); /* Next the table version number. This is the set (positive) value for the TabOK attribute. */ SetItem( &(store->pv), fits_i, 1, s, extver, status ); /* Also store the table version in the binary table header. */ astSetFitsI( table->header, "EXTVER", extver, "Table version number", 0 ); /* Next the name of the table column containing the main coords array. */ SetItemC( &(store->ps), fits_i, 1, s, astColumnName( table, icolmain ), status ); /* Next the name of the column containing the index array */ if( icolindex >= 0 ) SetItemC( &(store->ps), fits_i, 2, s, astColumnName( table, icolindex ), status ); /* The interpolation method (an AST extension to the published -TAB algorithm, communicated through the QVi_4a keyword). */ SetItem( &(store->pv), fits_i, 4, s, interp, status ); /* Also store the FitsTable itself in the FitsStore. */ astMapPut0A( store->tables, AST_TABEXTNAME, table, NULL ); /* Create the WCS -> IWC Mapping (AST uses grid coords as IWC coords for the -TAB algorithm). First, get a Mapping that combines the TAB axis Mapping( tmap0) in parallel with one or two UnitMaps in order to put the TAB axis at the required index. */ tmap1 = AddUnitMaps( tmap0, iax, nwcs, status ); /* Now get a PermMap that permutes the WCS axes into the FITS axis order. */ inperm = astMalloc( sizeof( double )*nwcs ); outperm = astMalloc( sizeof( double )*nwcs ); if( astOK ) { for( i = 0; i < nwcs; i++ ) { inperm[ i ] = wperm[ i ]; outperm[ wperm[ i ] ] = i; } } pm = astPermMap( nwcs, inperm, nwcs, outperm, NULL, "", status ); /* Combine these two Mappings in series, to get the Mapping from WCS to IWC. */ axmap = (AstMapping *) astCmpMap( pm, tmap1, 1, " ", status ); /* Free resources. */ inperm = astFree( inperm ); outperm = astFree( outperm ); pm = astAnnul( pm ); tmap0 = astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); } if( table ) table = astAnnul( table ); } /* If the axis cannot be described by any of the above methods, we pretend it is linear. This will generate a non-linear PIXEL->IWC mapping later (in MakeIntWorld) which will cause the write operation to fail. */ if( !axmap ) { crval = -crval; tmap0 = (AstMapping *) astShiftMap( 1, &crval, "", status ); axmap = AddUnitMaps( tmap0, iax, nwcs, status ); tmap0 = astAnnul( tmap0 ); crval = -crval; } /* Combine the Mapping for this axis in series with those of earlier axes. */ if( ret ) { tmap0 = (AstMapping *) astCmpMap( ret, axmap, 1, "", status ); (void) astAnnul( ret ); ret = tmap0; } else { ret = astClone( axmap ); } /* Get axis label and symbol. */ sym = astGetSymbol( wcsfrm, iax ); lab = astGetLabel( wcsfrm, iax ); /* The axis symbols are taken as the CTYPE values. Append "-LOG" or "-TAB" if the axis is logarithmic or tabular. */ if( sym && strlen( sym ) ) { (void) sprintf( buf, "%s", sym ); } else { (void) sprintf( buf, "AXIS%d", iax + 1 ); } if( log_axis ) { SetAlgCode( buf, "-LOG", status ); } else if( tab_axis ) { SetAlgCode( buf, "-TAB", status ); } SetItemC( &(store->ctype), fits_i, 0, s, buf, status ); /* The axis labels are taken as the comment for the CTYPE keywords and as the CNAME keyword (but only if a label has been set and is different to the symbol). */ if( lab && lab[ 0 ] && astTestLabel( wcsfrm, iax ) && strcmp( sym, lab ) ) { SetItemC( &(store->ctype_com), fits_i, 0, s, (char *) lab, status ); SetItemC( &(store->cname), fits_i, 0, s, (char *) lab, status ); } else { sprintf( buf, "Type of co-ordinate on axis %d", iax + 1 ); SetItemC( &(store->ctype_com), fits_i, 0, s, buf, status ); } /* If a value has been set for the axis units, use it as CUNIT. */ if( astTestUnit( wcsfrm, iax ) ){ SetItemC( &(store->cunit), fits_i, 0, s, (char *) astGetUnit( wcsfrm, iax ), status ); } /* Indicate this axis has now been described. */ axis_done[ iax ] = 1; /* Release Resources. */ axmap = astAnnul( axmap ); } } /* Release Resources. */ wcsfrm = astAnnul( wcsfrm ); map = astAnnul( map ); pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); lbnd_p = astFree( lbnd_p ); ubnd_p = astFree( ubnd_p ); } /* If we have a Mapping to return, simplify it. Otherwise, create a UnitMap to return. */ if( ret ) { tmap0 = ret; ret = astSimplify( tmap0 ); tmap0 = astAnnul( tmap0 ); } else { ret = (AstMapping *) astUnitMap( nwcs, "", status ); } /* Return the result. */ return ret; } static int PCFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * PCFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-PC encoding. * Type: * Private function. * Synopsis: * int PCFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-PC encoding. * * Zero is returned if the primary axis descriptions cannot be produced. * Whether or not secondary axis descriptions can be produced does not * effect the returned value (i.e. failure to produce a specific set of * secondary axes does not prevent other axis descriptions from being * produced). * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ char *comm; /* Pointer to comment string */ char *cval; /* Pointer to string keyword value */ char combuf[80]; /* Buffer for FITS card comment */ char keyname[10]; /* Buffer for keyword name string */ char primsys[20]; /* Buffer for primnary RADECSYS value */ char type[MXCTYPELEN];/* Buffer for CTYPE value */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ char sup; /* Upper limit on s */ double *c; /* Pointer to next array element */ double *d; /* Pointer to next array element */ double *matrix; /* Pointer to Frame PC/CD matrix */ double *primpc; /* Pointer to primary PC/CD matrix */ double fd; /* Fraction of a day */ double mjd99; /* MJD at start of 1999 */ double primdt; /* Primary mjd-obs value */ double primeq; /* Primary equinox value */ double primln; /* Primary lonpole value */ double primlt; /* Primary latpole value */ double primpv[10]; /* Primary projection parameter values */ double val; /* General purpose value */ int axlat; /* Index of latitude FITS WCS axis */ int axlon; /* Index of longitude FITS WCS axis */ int axspec; /* Index of spectral FITS WCS axis */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int is; /* Co-ordinate version index */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int m; /* Parameter index */ int maxm; /* Upper limit on m */ int naxis; /* No. of axes */ int nc; /* Length of string */ int ok; /* Frame written out succesfully? */ int prj; /* Projection type */ int ret; /* Returned value. */ /* Initialise */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Find the number of co-ordinate versions in the FitsStore. FITS-PC can only encode 10 axis descriptions (including primary). */ sup = GetMaxS( &(store->crval), status ); if( sup > 'I' ) return ret; /* Initialise */ primdt = AST__BAD; primeq = AST__BAD; primln = AST__BAD; primlt = AST__BAD; /* Loop round all co-ordinate versions (0-9) */ primpc = NULL; for( s = ' '; s <= sup && astOK; s++ ){ is = s - 'A' + 1; /* Assume the Frame can be created succesfully. */ ok = 1; /* Save the number of wcs axes */ val = GetItem( &(store->wcsaxes), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { naxis = (int) ( val + 0.5 ); SetValue( this, FormatKey( "WCSAXES", -1, -1, s, status ), &naxis, AST__INT, "Number of WCS axes", status ); } else { naxis = GetMaxJM( &(store->crpix), s, status ) + 1; } /* PC matrix: --------- */ /* This encoding does not allow the PC matrix to be specified for each version - instead they all share the primary PC matrix. Therefore we need to check that all versions can use the primary PC matrix. Allocate memory to hold the PC matrix for this version. */ matrix = (double *) astMalloc( sizeof(double)*naxis*naxis ); if( matrix ){ /* Fill these array with the values supplied in the FitsStore. */ c = matrix; for( i = 0; i < naxis; i++ ){ for( j = 0; j < naxis; j++ ){ *c = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( *c == AST__BAD ) *c = ( i == j ) ? 1.0 : 0.0; c++; } } /* If we are currently processing the primary axis description, take a copy of the PC matrix. */ if( s == ' ' ) { primpc = (double *) astStore( NULL, (void *) matrix, sizeof(double)*naxis*naxis ); /* Store each matrix element in turn. */ c = matrix; for( i = 0; i < naxis; i++ ){ for( j = 0; j < naxis; j++ ){ /* Set the element bad if it takes its default value. */ val = *(c++); if( i == j ){ if( astEQUAL( val, 1.0 ) ) val = AST__BAD; } else { if( astEQUAL( val, 0.0 ) ) val = AST__BAD; } /* Only store elements which do not take their default values. */ if( val != AST__BAD ){ sprintf( keyname, "PC%.3d%.3d", i + 1, j + 1 ); SetValue( this, keyname, &val, AST__FLOAT, NULL, status ); } } } /* For secondary axis descriptions, a check is made that the PC values are the same as the primary PC values stored earlier. If not, the current Frame cannot be stored as a secondary axis description so continue on to the next Frame. */ } else { if( primpc ){ c = matrix; d = primpc; for( i = 0; i < naxis; i++ ){ for( j = 0; j < naxis; j++ ){ if( !astEQUAL( *c, *d ) ){ ok = 0; } else { c++; d++; } } } /* Continue with the next Frame if the PC matrix for this Frame is different to the primary PC matrix. */ if( !ok ) goto next; } } matrix = (double *) astFree( (void *) matrix ); } /* CDELT: ------ */ for( i = 0; i < naxis; i++ ){ val = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Pixel scale on axis %d", i + 1 ); if( s == ' ' ) { sprintf( keyname, "CDELT%d", i + 1 ); } else { sprintf( keyname, "C%dELT%d", is, i + 1 ); } SetValue( this, keyname, &val, AST__FLOAT, combuf, status ); } /* CRPIX: ------ */ for( j = 0; j < naxis; j++ ){ val = GetItem( &(store->crpix), 0, j, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Reference pixel on axis %d", j + 1 ); if( s == ' ' ) { sprintf( keyname, "CRPIX%d", j + 1 ); } else { sprintf( keyname, "C%dPIX%d", is, j + 1 ); } SetValue( this, keyname, &val, AST__FLOAT, combuf, status ); } /* CRVAL: ------ */ for( i = 0; i < naxis; i++ ){ val = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Value at ref. pixel on axis %d", i + 1 ); if( s == ' ' ) { sprintf( keyname, "CRVAL%d", i + 1 ); } else { sprintf( keyname, "C%dVAL%d", is, i + 1 ); } SetValue( this, keyname, &val, AST__FLOAT, combuf, status ); } /* CTYPE: ------ */ for( i = 0; i < naxis; i++ ){ cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); nc = strlen( cval ); if( !cval || ( nc > 4 && !strcmp( cval + 4, "-TAB" ) ) ) { ok = 0; goto next; } comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } if( s == ' ' ) { sprintf( keyname, "CTYPE%d", i + 1 ); } else { sprintf( keyname, "C%dYPE%d", is, i + 1 ); } /* FITS-PC cannot handle celestial axes of type "xxLT" or "xxLN". Neither can it handle the "-TAB". */ if( ( nc > 2 && !strncmp( cval + 2, "LT-", 3 ) ) || ( nc > 2 && !strncmp( cval + 2, "LN-", 3 ) ) || ( nc > 4 && !strncmp( cval + 4, "-TAB", 4 ) ) ){ ok = 0; goto next; } /* Extract the projection type as specified by the last 4 characters in the CTYPE keyword value. This will be AST__WCSBAD for non-celestial axes. */ prj = astWcsPrjType( cval + 4 ); /* Change the new SFL projection code to to the older equivalent GLS */ if( prj == AST__SFL ) { strcpy( type, cval ); (void) strcpy( type + 4, "-GLS" ); cval = type; } /* FITS-PC cannot handle the AST-specific TPN projection. */ if( prj == AST__TPN ) { ok = 0; goto next; } /* Store the CTYPE value */ SetValue( this, keyname, &cval, AST__STRING, comm, status ); } /* Get and save CUNIT for all intermediate axes. These are NOT required, so do not pass on if they are not available. */ for( i = 0; i < naxis; i++ ){ cval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( cval ) { sprintf( combuf, "Units for axis %d", i + 1 ); if( s == ' ' ) { sprintf( keyname, "CUNIT%d", i + 1 ); } else { sprintf( keyname, "C%dNIT%d", is, i + 1 ); } SetValue( this, keyname, &cval, AST__STRING, combuf, status ); } } /* Get and save RADESYS. This is NOT required, so do not pass on if it is not available. If RADECSYS is provided for a secondary axis, it must be the same as the primary axis RADECSYS value. If it is not, pass on to the next Frame. */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); if( cval ) { if( s == ' ' ) { strcpy( primsys, cval ); SetValue( this, "RADECSYS", &cval, AST__STRING, "Reference frame for RA/DEC values", status ); } else if( strcmp( cval, primsys ) ) { ok = 0; goto next; } } /* Reference equinox. This is NOT required, so do not pass on if it is not available. If equinox is provided for a secondary axis, it must be the same as the primary axis equinox value. If it is not, pass on to the next Frame. */ val = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); if( s == ' ' ) { primeq = val; if( val != AST__BAD ) SetValue( this, "EQUINOX", &val, AST__FLOAT, "Epoch of reference equinox", status ); } else if( !astEQUAL( val, primeq ) ){ ok = 0; goto next; } /* Latitude of native north pole. This is NOT required, so do not pass on if it is not available. If latpole is provided for a secondary axis, it must be the same as the primary axis value. If it is not, pass on to the next Frame. */ val = GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ); if( s == ' ' ) { primlt = val; if( val != AST__BAD ) SetValue( this, "LATPOLE", &val, AST__FLOAT, "Latitude of native north pole", status ); } else if( !EQUALANG( val, primlt ) ){ ok = 0; goto next; } /* Longitude of native north pole. This is NOT required, so do not pass on if it is not available. If lonpole is provided for a secondary axis, it must be the same as the primary axis value. If it is not, pass on to the next Frame. */ val = GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ); if( s == ' ' ) { primln = val; if( val != AST__BAD ) SetValue( this, "LONGPOLE", &val, AST__FLOAT, "Longitude of native north pole", status ); } else if( !EQUALANG( val, primln ) ){ ok = 0; goto next; } /* Date of observation. This is NOT required, so do not pass on if it is not available. If mjd-obs is provided for a secondary axis, it must be the same as the primary axis value. If it is not, pass on to the next Frame. */ val = GetItem( &(store->mjdobs), 0, 0, s, NULL, method, class, status ); if( s == ' ' ) { primdt = val; if( val != AST__BAD ) { SetValue( this, "MJD-OBS", &val, AST__FLOAT, "Modified Julian Date of observation", status ); /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", &cval, AST__STRING, "Date of observation", status ); } } else if( !astEQUAL( val, primdt ) ){ ok = 0; goto next; } /* Look for the celestial and spectral axes. */ FindLonLatSpecAxes( store, s, &axlon, &axlat, &axspec, method, class, status ); /* If both longitude and latitude axes are present ...*/ if( axlon >= 0 && axlat >= 0 ) { /* Get the CTYPE values for the latitude axis. */ cval = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); /* Extract the projection type as specified by the last 4 characters in the CTYPE keyword value. */ prj = ( cval ) ? astWcsPrjType( cval + 4 ) : AST__WCSBAD; /* Projection parameters. If provided for a secondary axis, they must be the same as the primary axis value. If it is not, pass on to the next Frame. PC encoding ignores parameters associated with the longitude axis. The old PC TAN projection did not have any parameters. Pass on if a TAN projection with parameters is found. The number of parameters was limited to 10. Pass on if more than 10 are supplied. */ maxm = GetMaxJM( &(store->pv), ' ', status ); for( i = 0; i < naxis; i++ ){ if( i != axlon ) { for( m = 0; m <= maxm; m++ ){ val = GetItem( &(store->pv), i, m, s, NULL, method, class, status ); if( s == ' ' ){ if( val != AST__BAD ) { if( i != axlat || prj == AST__TAN || m >= 10 ){ ok = 0; goto next; } else { SetValue( this, FormatKey( "PROJP", m, -1, ' ', status ), &val, AST__FLOAT, "Projection parameter", status ); } } if( i == axlat && m < 10 ) primpv[m] = val; } else { if( ( ( i != axlat || m >= 10 ) && val != AST__BAD ) || ( i == axlat && m < 10 && !astEQUAL( val, primpv[m] ) ) ){ ok = 0; goto next; } } } } } } /* See if a Frame was sucessfully written to the FitsChan. */ next: ok = ok && astOK; /* If so, indicate we have something to return. */ if( ok ) ret = 1; /* Clear any error status so we can continue to produce the next Frame. Retain the error if the primary axes could not be produced. After the primary axes, do the A axes. */ if( s != ' ' ) { astClearStatus; } else { s = 'A' - 1; } /* Remove the secondary "new" flags from the FitsChan. This flag is associated with cards which have been added to the FitsChan during this pass through the main loop in this function. If the Frame was written out succesfully, just clear the flags. If anything went wrong with this Frame, remove the flagged cards from the FitsChan. */ FixNew( this, NEW2, !ok, method, class, status ); /* Set the current card so that it points to the last WCS-related keyword in the FitsChan (whether previously read or not). */ FindWcs( this, 1, 1, 0, method, class, status ); } /* Annul the array holding the primary PC matrix. */ primpc = (double *) astFree( (void *) primpc ); /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ret : 0; } static void PreQuote( const char *value, char string[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 3 ], int *status ) { /* * Name: * PreQuote * Purpose: * Pre-quote FITS character data. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void PreQuote( const char *value, * char string[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 3 ] ) * Class Membership: * FitsChan member function. * Description: * This function processes a string value in such a way that it can * be stored as a FITS character value (associated with a keyword) * and later retrieved unchanged, except for possible truncation. * * This pre-processing is necessary because FITS does not regard * trailing white space as significant, so it is lost. This * function adds double quote (") characters around the string if * it is necessary in order to prevent this loss. These quotes are * also added to zero-length strings and to strings that are * already quoted (so that the original quotes are not lost when * they are later un-quoted). * * This function will silently truncate any string that is too long * to be stored as a FITS character value, but will ensure that the * maximum number of characters are retained, taking account of any * quoting required. * Parameters: * value * Pointer to a constant null-terminated string containing the * input character data to be quoted. All white space is * significant. * string * A character array into which the result string will be * written, with a terminating null. The maximum number of * characters from the input string that can be accommodated in * this is (AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 4), but this * will be reduced if quoting is necessary. * Notes: * - The UnPreQuote function should be used to reverse the effect * of this function on a string (apart from any truncation). */ /* Local Variables: */ int dq; /* Number of double quotes needed */ int dquotes; /* Final number of double quotes */ int i; /* Loop counter for input characters */ int j; /* Counter for output characters */ int nc; /* Number of characters to be accommodated */ int sq; /* Number of single quotes needed */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise, setting the default number of double quotes (which applies to a zero-length string) to 2. */ dquotes = 2; nc = 0; sq = 0; /* Loop to consider each input character to see if it will fit into the result string. */ for ( i = 0; value[ i ]; i++ ) { /* If a single quote character is to be included, count it. When the string is encoded as FITS character data, these quotes will be doubled, so will increase the overall string length by one. */ if ( value[ i ] == '\'' ) sq++; /* See how many double quotes are needed around the string (0 or 2). These are needed if there is trailing white space that needs protecting (this is not significant in FITS and will be removed), or if the string already has quotes at either end (in which case an extra set is needed to prevent the original ones being removed when it is later un-quoted). Note we do not need to double existing double quote characters within the string, because the position of the ends of the string are known (from the quoting supplied by FITS) so only the first and last characters need be inspected when un-quoting the string. In assessing the number of double quotes, assume the string will be truncated after the current character. */ dq = ( isspace( value[ i ] ) || ( ( value[ 0 ] == '"' ) && ( value[ i ] == '"' ) ) ) ? 2 : 0; /* See if the length of the resulting string, including the current character and all necessary quotes, is too long. If so, give up here. */ if ( ( nc + 1 + dq + sq ) > ( AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 4 ) ) break; /* If the string is not too long, accept the character and note the number of double quotes needed. */ nc = i + 1; dquotes = dq; } /* If double quotes are needed, insert the opening quote into the output string. */ j = 0; if ( dquotes ) string[ j++ ] = '"'; /* Follow this with the maximum number of input string characters that can be accommodated. */ for ( i = 0; i < nc; i++ ) string[ j++ ] = value[ i ]; /* Append the closing quote if necessary and terminate the output string. */ if ( dquotes ) string[ j++ ] = '"'; string[ j ] = '\0'; } static void PurgeWCS( AstFitsChan *this, int *status ){ /* *++ * Name: c astPurgeWCS f AST_PURGEWCS * Purpose: * Delete all cards in the FitsChan describing WCS information. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astPurgeWCS( AstFitsChan *this ) f CALL AST_PURGEWCS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * deletes all cards in a FitsChan that relate to any of the recognised * WCS encodings. On exit, the current card is the first remaining card * in the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstObject *obj; int oldclean; /* Check the global status. */ if( !astOK ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Ensure the Clean attribute is set so that WCS keywords are removed even if an error occurs. */ if( astTestClean( this ) ) { oldclean = astGetClean( this ); astSetClean( this, 1 ); } else { astSetClean( this, 1 ); oldclean = -1; } /* Loop round attempting to read AST objects form the FitsChan. This will flag cards as used that are involved in the creation of these object (including NATIVE encodings). Ignore any error that ocurs whilst doing this. */ astClearCard( this ); if( astOK ) { int oldreporting = astReporting( 0 ); obj = astRead( this ); while( obj ) { obj = astAnnul( obj ); astClearCard( this ); obj = astRead( this ); } if( !astOK ) astClearStatus; astReporting( oldreporting ); } /* We now loop round to remove any spurious WCS-related cards left in the FitsChan that did not form part of a complete WCS encoding. Find the first WCS-related card left in the FitsChan. */ FindWcs( this, 0, 0, 1, "DeleteWcs", "FitsChan", status ); /* Loop round marking each WCS-related card as used until none are left */ while( this->card && astOK ) { /* Mark the current card as having been read. */ ( (FitsCard*) this->card )->flags = USED; /* Find the next WCS-related card. */ FindWcs( this, 0, 0, 0, "DeleteWcs", "FitsChan", status ); } /* Rewind the FitsChan. */ astClearCard( this ); /* Reset the Clean attribute. */ if( oldclean == -1 ) { astClearClean( this ); } else { astSetClean( this, oldclean ); } } static void PutCards( AstFitsChan *this, const char *cards, int *status ) { /* *++ * Name: c astPutCards f AST_PUTCARDS * Purpose: * Store a set of FITS header cards in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astPutCards( AstFitsChan *this, const char *cards ) f CALL AST_PUTCARDS( THIS, CARDS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * stores a set of FITS header cards in a FitsChan. The cards are * supplied concatenated together into a single character string. * Any existing cards in the FitsChan are removed before the new cards * are added. The FitsChan is "re-wound" on exit by clearing its Card * attribute. This means that a subsequent invocation of c astRead f AST_READ * can be made immediately without the need to re-wind the FitsChan * first. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c cards f CARDS = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string f A character string * containing the FITS cards to be stored. Each individual card * should occupy 80 characters in this string, and there should be * no delimiters, new lines, etc, between adjacent cards. The final * card may be less than 80 characters long. c This is the format produced by the fits_hdr2str function in the c CFITSIO library. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - An error will result if the supplied string contains any cards * which cannot be interpreted. *-- */ /* Local Variables: */ const char *a; /* Pointer to start of next card */ int clen; /* Length of supplied string */ int i; /* Card index */ int ncard; /* No. of cards supplied */ /* Check the global error status. */ if ( !astOK ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Empty the FitsChan. */ astEmptyFits( this ); /* Loop round the supplied string in 80 character segments, inserting each segment into the FitsChan as a header card. Allow the last card to be less than 80 characters long. */ clen = strlen( cards ); ncard = clen/80; if( ncard*80 < clen ) ncard++; a = cards; for( i = 0; i < ncard; i++, a += 80 ) astPutFits( this, a, 1 ); /* Rewind the FitsChan. */ astClearCard( this ); } static void PutFits( AstFitsChan *this, const char card[ AST__FITSCHAN_FITSCARDLEN + 1 ], int overwrite, int *status ){ /* *++ * Name: c astPutFits f AST_PUTFITS * Purpose: * Store a FITS header card in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astPutFits( AstFitsChan *this, const char card[ 80 ], c int overwrite ) f CALL AST_PUTFITS( THIS, CARD, OVERWRITE, STATUS ) * Class Membership: * FitsChan method. * Description: c This function stores a FITS header card in a FitsChan. The card f This routine stores a FITS header card in a FitsChan. The card * is either inserted before the current card (identified by the * Card attribute), or over-writes the current card, as required. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c card f CARD = CHARACTER * ( 80 ) (Given) c Pointer to a possibly null-terminated character string c containing the FITS card to be stored. No more than 80 c characters will be used from this string (or fewer if a null c occurs earlier). f A character string string containing the FITS card to be f stored. No more than 80 characters will be used from this f string. c overwrite f OVERWRITE = LOGICAL (Given) c If this value is zero, the new card is inserted in front of f If this value is .FALSE., the new card is inserted in front of * the current card in the FitsChan (as identified by the c initial value of the Card attribute). If it is non-zero, the f initial value of the Card attribute). If it is .TRUE., the * new card replaces the current card. In either case, the Card * attribute is then incremented by one so that it subsequently * identifies the card following the one stored. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If the Card attribute initially points at the "end-of-file" * (i.e. exceeds the number of cards in the FitsChan), then the new * card is appended as the last card in the FitsChan. * - An error will result if the supplied string cannot be interpreted * as a FITS header card. *-- */ /* Local Variables: */ char *comment; /* The keyword comment */ char *name; /* The keyword name */ char *value; /* The keyword value */ const char *class; /* Object class */ const char *method; /* Current method */ double cfval[2]; /* Complex floating point keyword value */ double fval; /* floating point keyword value */ int cival[2]; /* Complex integer keyword value */ int ival; /* Integer keyword value */ int len; /* No. of characters to read from the value string */ int nc; /* No. of characters read from value string */ int type; /* Keyword data type */ /* Check the global error status. */ if ( !astOK ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astPutFits"; class = astGetClass( this ); /* Split the supplied card up into name, value and commment strings, and get pointers to local copies of them. The data type associated with the keyword is returned. */ type = Split( this, card, &name, &value, &comment, method, class, status ); /* Check that the pointers can be used. */ if( astOK ){ /* Initialise the number of characters read from the value string. */ nc = 0; /* Store the number of characters in the value string. */ len = strlen( value ); /* Read and store floating point values from the value string. NB, this list is roughly in the order of descreasing frequency of use (i.e. most FITS keywords are simple floating point values, the next most common are strings, etc). */ if( type == AST__FLOAT ){ if( 1 == astSscanf( value, " %lf %n", &fval, &nc ) && nc >= len ){ astSetFitsF( this, name, fval, comment, overwrite ); } else { astError( AST__BDFTS, "%s(%s): Unable to read a floating point " "FITS keyword value.", status, method, class ); } /* Read and store string values from the value string. */ } else if( type == AST__STRING ){ astSetFitsS( this, name, value, comment, overwrite ); /* Read and store string values from the value string. */ } else if( type == AST__CONTINUE ){ astSetFitsCN( this, name, value, comment, overwrite ); /* Store comment card. */ } else if( type == AST__COMMENT ){ astSetFitsCom( this, name, comment, overwrite ); /* Read and store integer values from the value string. */ } else if( type == AST__INT ){ if( 1 == astSscanf( value, " %d %n", &ival, &nc ) && nc >= len ){ astSetFitsI( this, name, ival, comment, overwrite ); } else { astError( AST__BDFTS, "%s(%s): Unable to read an integer FITS " "keyword value.", status, method, class ); } /* Read and store logical values from the value string. */ } else if( type == AST__LOGICAL ){ astSetFitsL( this, name, (*value == 'T'), comment, overwrite ); /* Read and store undefined values from the value string. */ } else if( type == AST__UNDEF ){ astSetFitsU( this, name, comment, overwrite ); /* Read and store complex floating point values from the value string. */ } else if( type == AST__COMPLEXF ){ if( 2 == astSscanf( value, " %lf %lf %n", cfval, cfval + 1, &nc ) && nc >= len ){ astSetFitsCF( this, name, cfval, comment, overwrite ); } else { astError( AST__BDFTS, "%s(%s): Unable to read a complex pair " "of floating point FITS keyword values.", status, method, class ); } /* Read and store complex integer values from the value string. */ } else if( type == AST__COMPLEXI ){ if( 2 == astSscanf( value, " %d %d %n", cival, cival + 1, &nc ) && nc >= len ){ astSetFitsCI( this, name, cival, comment, overwrite ); } else { astError( AST__BDFTS, "%s(%s): Unable to read a complex pair " "of integer FITS keyword values.", status, method, class ); } /* Report an error for any other type. */ } else { astError( AST__INTER, "%s: AST internal programming error - " "FITS data-type '%d' not yet supported.", status, method, type ); } /* Give a context message if an error occurred. */ if( !astOK ){ astError( astStatus, "%s(%s): Unable to store the following FITS " "header card:\n%s\n", status, method, class, card ); } } /* Free the memory used to hold the keyword name, comment and value strings. */ (void) astFree( (void *) name ); (void) astFree( (void *) comment ); (void) astFree( (void *) value ); } static void PutTable( AstFitsChan *this, AstFitsTable *table, const char *extnam, int *status ) { /* *++ * Name: c astPutTable f AST_PUTTABLE * Purpose: * Store a single FitsTable in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astPutTable( AstFitsChan *this, AstFitsTable *table, c const char *extnam ) f CALL AST_PUTTABLE( THIS, TABLE, EXTNAM, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * allows a representation of a single FITS binary table to be * stored in a FitsChan. For instance, this may provide the coordinate * look-up tables needed subequently when reading FITS-WCS headers * for axes described using the "-TAB" algorithm. Since, in general, * the calling application may not know which tables will be needed - * if any - prior to calling c astRead, the astTablesSource function f AST_READ, the AST_TABLESOURCE routine * provides an alternative mechanism in which a caller-supplied * function is invoked to store a named table in the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c table f TABLE = INTEGER (Given) * Pointer to a FitsTable to be added to the FitsChan. If a FitsTable * with the associated extension name already exists in the FitsChan, * it is replaced with the new one. A deep copy of the FitsTable is * stored in the FitsChan, so any subsequent changes made to the * FitsTable will have no effect on the behaviour of the FitsChan. c extnam f EXTNAM = CHARACTER * ( * ) (Given) * The name of the FITS extension associated with the table. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Tables stored in the FitsChan may be retrieved using c astGetTables. f AST_GETTABLES. c - The astPutTables method can add multiple FitsTables in a single call. f - The AST_PUTTABLES method can add multiple FitsTables in a single call. *-- */ /* Local Variables: */ AstObject *ft; /* Check the global error status. */ if ( !astOK ) return; /* Create a KeyMap to hold the tables within the FitsChan, if this has not already been done. */ if( !this->tables ) this->tables = astKeyMap( " ", status ); /* Store a copy of the FitsTable in the FitsChan. */ ft = astCopy( table ); astMapPut0A( this->tables, extnam, ft, NULL ); ft = astAnnul( ft ); } static void PutTables( AstFitsChan *this, AstKeyMap *tables, int *status ) { /* *++ * Name: c astPutTables f AST_PUTTABLES * Purpose: * Store one or more FitsTables in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astPutTables( AstFitsChan *this, AstKeyMap *tables ) f CALL AST_PUTTABLES( THIS, TABLES, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * allows representations of one or more FITS binary tables to be * stored in a FitsChan. For instance, these may provide the coordinate * look-up tables needed subequently when reading FITS-WCS headers * for axes described using the "-TAB" algorithm. Since, in general, * the calling application may not know which tables will be needed - * if any - prior to calling c astRead, the astTablesSource function f AST_READ, the AST_TABLESOURCE routine * provides an alternative mechanism in which a caller-supplied * function is invoked to store a named table in the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c tables f TABLES = INTEGER (Given) * Pointer to a KeyMap holding the tables that are to be added * to the FitsChan. Each entry should hold a scalar value which is a * pointer to a FitsTable to be added to the FitsChan. Any unusable * entries are ignored. The key associated with each entry should be * the name of the FITS binary extension from which the table was * read. If a FitsTable with the associated key already exists in the * FitsChan, it is replaced with the new one. A deep copy of each * usable FitsTable is stored in the FitsChan, so any subsequent * changes made to the FitsTables will have no effect on the * behaviour of the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Tables stored in the FitsChan may be retrieved using c astGetTables. f AST_GETTABLES. * - The tables in the supplied KeyMap are added to any tables already * in the FitsChan. c - The astPutTable f - The AST_PUTTABLE * method provides a simpler means of adding a single table to a FitsChan. *-- */ /* Local Variables: */ AstObject *obj; const char *key; int ientry; int nentry; /* Check the global error status. */ if ( !astOK ) return; /* Loop through all entries in the supplied KeyMap. */ nentry = astMapSize( tables ); for( ientry = 0; ientry < nentry; ientry++ ) { key = astMapKey( tables, ientry ); /* Ignore entries that do not contain AST Object pointers, or are not scalar. */ if( astMapType( tables, key ) == AST__OBJECTTYPE && astMapLength( tables, key ) == 1 ) { /* Get the pointer, amd ignore it if it is not a FitsTable. */ astMapGet0A( tables, key, &obj ); if( astIsAFitsTable( obj ) ) { /* Store it in the FitsChan. */ astPutTable( this, (AstFitsTable *) obj, key ); } /* Annul the Object pointer. */ obj = astAnnul( obj ); } } } static AstObject *Read( AstChannel *this_channel, int *status ) { /* * Name: * Read * Purpose: * Read an Object from a Channel. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstObject *Read( AstChannel *this_channel, int *status ) * Class Membership: * FitsChan member function (over-rides the astRead method * inherited from the Channel class). * Description: * This function reads an Object from a FitsChan. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new Object. This will always be a FrameSet. * Notes: * - The pixel Frame is given a title of "Pixel Coordinates", and * each axis in the pixel Frame is given a label of the form "Pixel * axis ", where is the axis index (starting at one). * - The FITS CTYPE keyword values are used to set the labels for any * non-celestial axes in the physical coordinate Frames, and the FITS * CUNIT keywords are used to set the corresponding units strings. * - On exit, the pixel Frame is the base Frame, and the physical * Frame derived from the primary axis descriptions is the current Frame. * - Extra Frames are added to hold any secondary axis descriptions. All * axes within such a Frame refer to the same coordinate version ('A', * 'B', etc). * - For foreign encodings, the first card in the FitsChan must be * the current card on entry (otherwise a NULL pointer is returned), * and the FitsChan is left at end-of-file on exit. * - For the Native encoding, reading commences from the current card * on entry (which need not be the first in the FitsChan), and the * current Card on exit is the first card following the last one read * (or end-of-file). */ /* Local Variables: */ AstObject *new; /* Pointer to returned Object */ AstFitsChan *this; /* Pointer to the FitsChan structure */ FitsStore *store; /* Intermediate storage for WCS information */ const char *method; /* Pointer to string holding calling method */ const char *class; /* Pointer to string holding object class */ int encoding; /* The encoding scheme */ int remove; /* Remove used cards? */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the calling method, and object class. */ method = "astRead"; class = astGetClass( this ); /* Get the encoding scheme used by the FitsChan. */ encoding = astGetEncoding( this ); /* If we are reading from a FitsChan in which AST objects are encoded using native AST-specific keywords, use the Read method inherited from the Channel class. */ if( encoding == NATIVE_ENCODING ){ new = (*parent_read)( this_channel, status ); /* Indicate that used cards should be removed from the FitsChan. */ remove = 1; /* If we are reading from a FitsChan in which AST objects are encoded using any of the other supported encodings, the header may only contain a single FrameSet. */ } else { remove = 0; /* Only proceed if the FitsChan is at start-of-file. */ if( !astTestCard( this ) && astOK ){ /* Extract the required information from the FITS header into a standard intermediary structure called a FitsStore. */ store = FitsToStore( this, encoding, method, class, status ); /* Now create a FrameSet from this FitsStore. */ new = FsetFromStore( this, store, method, class, status ); /* Release the resources used by the FitsStore. */ store = FreeStore( store, status ); /* Indicate that used cards should be retained in the FitsChan. */ remove = 0; /* If no object is being returned, rewind the fitschan in order to re-instate the original current Card. */ if( !new ) { astClearCard( this ); /* Otherwise, ensure the current card is at "end-of-file". */ } else { astSetCard( this, INT_MAX ); } } } /* If an error occurred, clean up by deleting the new Object and return a NULL pointer. */ if ( !astOK ) new = astDelete( new ); /* If no object is being returned, clear the "provisionally used" flags associated with cards which were read. We do not do this if the user wants to clean WCS cards from the FitsChan even if an error occurs. */ if( !new && !astGetClean( this ) ) { FixUsed( this, 0, 0, 0, method, class, status ); /* Otherwise, indicate that all the "provisionally used" cards have been "definitely used". If native encoding was used, these cards are totally removed from the FitsChan. */ } else { FixUsed( this, 0, 1, remove, method, class, status ); } /* Return the pointer to the new Object. */ return new; } static double *ReadCrval( AstFitsChan *this, AstFrame *wcsfrm, char s, const char *method, const char *class, int *status ){ /* * Name: * ReadCrval * Purpose: * Obtain the reference point from the supplied FitsChan in the * supplied WCS Frame. * Type: * Private function. * Synopsis: * #include "fitschan.h" * double *ReadCrval( AstFitsChan *this, AstFrame *wcsfrm, char s, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The original reference point in the "s" coordinate description is read * from the CRVAL keywords in the supplied FitsChan, and the original * FrameSet is re-read from the FitsChan. If possible, the reference * position is then converted from the "s" coordinate description to the * supplied WCS Frame, and a pointer to an array holding the axis * values for the transformed reference point is returned. * Parameters: * this * The FitsChan. * wcsfrm * The WCS Frame in the FitsChan being written to. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated array holding the reference * point in the supplied WCS Frame. NULL is returned if is is not * possible to determine the reference point for any reason (for * instance, if the FitsChan does not contain values for the CRVAL * keywords). */ /* Local Variables: */ AstFitsChan *fc; /* A copy of the supplied FitsChan */ AstFrame *tfrm; /* Temporary Frame pointer */ AstFrameSet *fs; /* The FITS FrameSet */ AstFrameSet *tfs; /* FrameSet connecting FITS and supplied WCS Frame */ const char *id; /* Pointer to Object "Id" string */ char buf[ 11 ]; /* FITS keyword template buffer */ double *crval; /* CRVAL keyword values in supplied FitsChan */ double *ret; /* Returned array */ int hii; /* Highest found FITS axis index */ int iax; /* Axis index (zero based) */ int ifr; /* Frames index */ int loi; /* Lowest found FITS axis index */ int nax; /* Axis count */ int nfr; /* No. of Frames in FITS FrameSet */ int ok; /* Were CRVAL values found? */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* We want to re-create the original FrameSet represented by the original contents of the supplied FitsChan. Some of the contents of the FitsChan will already have been marked as "having been read" and so will be ignored if we attempt to read a FrameSet directly from the supplied FitsChan. Therefore we take a deep copy of the supplied FitsChan and clear all the "previusly read" flags in the copy. */ fc = astCopy( this ); astClearEncoding( fc ); FixUsed( fc, 1, 0, 0, method, class, status ); /* Copy the CRVAL values for the "s" axis descriptions into a dynamically allocated array ("crval"). */ if( s == ' ' ) { strcpy( buf, "CRVAL%d" ); } else { sprintf( buf, "CRVAL%%d%c", s ); } if( astKeyFields( fc, buf, 1, &hii, &loi ) > 0 ) { crval = astMalloc( sizeof( double )*(size_t) hii ); ok = 1; for( iax = 0; iax < hii; iax++ ){ ok = ok && GetValue( fc, FormatKey( "CRVAL", iax + 1, -1, s, status ), AST__FLOAT, (void *) (crval + iax), 0, 0, method, class, status ); } } else { crval = NULL; ok = 0; } /* If the CRVAL values were obtained succesfully, attempt to read a FrameSet from the FitsChan copy. Do it in a new error report context so that we can annull any error when the FrameSet is read. */ if( ok ) { int oldreporting = astReporting( 0 ); astClearCard( fc ); fs = astRead( fc ); if( fs ) { /* We want to find a conversion from the Frame in this FrameSet which represents the FITS-WCS "s" coordinate descriptions and the supplied WCS Frame. So first find the Frame which has its Ident attribute set to "s" and make it the current Frame. */ nfr = astGetNframe( fs ); for( ifr = 1; ifr <= nfr; ifr++ ) { astSetCurrent( fs, ifr ); tfrm = astGetFrame( fs, ifr ); id = astTestIdent( tfrm ) ? astGetIdent( tfrm ) : NULL; tfrm = astAnnul( tfrm ); if( id && strlen( id ) == 1 && id[ 0 ] == s ) break; } /* Check a Frame was found, and that we have CRVAL values for all axes in the Frame. */ if( ifr <= nfr && astGetNaxes( fs ) == hii ) { /* Attempt to find a conversion route from the Frame found above to the supplied WCS Frame. */ tfs = astConvert( fs, wcsfrm, astGetDomain( wcsfrm ) ); if( tfs ) { /* Allocate memory to hold the returned reference point. */ nax = astGetNaxes( wcsfrm ); ret = astMalloc( sizeof( double )*(size_t) nax ); /* Transform the original reference position from the "s" Frame to the supplied WCS Frame using the Mapping returned by astConvert. */ astTranN( tfs, 1, hii, 1, crval, 1, nax, 1, ret ); /* Free resources. */ tfs = astAnnul( tfs ); } } /* Free resources. */ fs = astAnnul( fs ); /* Annul any error that occurred reading the FitsChan. */ } else if( !astOK ) { astClearStatus; } /* Re-instate error reporting. */ astReporting( oldreporting ); } /* Free resources. */ if( crval ) crval = astFree( crval ); fc = astAnnul( fc ); /* If an error occurred, free the returned array. */ if( !astOK ) ret = astFree( ret ); /* Return the result. */ return ret; } static void ReadFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astReadFits f AST_READFITS * Purpose: * Read cards into a FitsChan from the source function. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astReadFits( AstFitsChan *this ) f CALL AST_READFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * reads cards from the source function that was specified when the * FitsChan was created, and stores them in the FitsChan. This * normally happens once-only, when the FitsChan is accessed for the * first time. c This function f This routine * provides a means of forcing a re-read of the external source, and * may be useful if (say) new cards have been deposited into the * external source. Any newcards read from the source are appended to * the end of the current contents of the FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - This function returns without action if no source function was * specified when the FitsChan was created. * - The SourceFile attribute is ignored by this c function. f routine. * New cards are read from the source file whenever a new value is * assigned to the SourceFile attribute. *-- */ /* Check the inherited status */ if( !astOK ) return; /* If no source function is available, re-instate any saved source function pointer. */ if( !this->source ) { this->source = this->saved_source; this->saved_source = NULL; } /* Call the source function. */ ReadFromSource( this, status ); } static void ReadFromSource( AstFitsChan *this, int *status ){ /* * Name: * ReadFromSource * Purpose: * Fill the FitsChan by reading cards from the source function. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void ReadFromSource( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * The source function specified when the FitsChan was created is * called repeatedly until it returns a NULL pointer. The string * returned by each such call is assumed to be a FITS header card, * and is stored in the FitsChan using astPutFits. * * If no source function was provided, the FitsChan is left as supplied. * This is different to a standard Channel, which tries to read data * from standard input if no source function is provided. * * This function should be called at the start of most public or protected * FitsChan functions, and most private functions that are used to override * methods inherited form the Channel class. Previously, this function * was called only once, from the FitsChan initialiser (astInitFitschan). * However, calling it from astInitFitsChan means that application code * cannot use the astPutChannelData function with a FitsChan, since the * source function would already have been called by the time the * FitsChan constructor returned (and thus before astPutChannelData * could have been called). In order to ensure that the source * function is called only once, this function now nullifies the source * function pointer after its first use. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Notes: * - The new cards are appended to the end of the FitsChan. * - The first of the new cards is made the current card on exit. If no * source function is supplied, the current card is left unchanged. */ /* Local Variables: */ const char *(* source)( void ); /* Pointer to source function */ const char *card; /* Pointer to externally-read header card */ int icard; /* Current card index on entry */ /* Check the global status. */ if( !astOK || !this ) return; /* Only proceed if source function and wrapper were supplied when the FitsChan was created and are still available. */ if( this->source && this->source_wrap ){ /* Save the source function pointer and then nullify the pointer in the FitsChan structure. This avoids infinte loops. */ source = this->source; this->source = NULL; /* Save the source fubnction pointer in the FitsChan so that it can be re-instated if required (e.g. by astReadFits). */ this->saved_source = source; /* Ensure the FitsChan is at end-of-file. This will result in the new cards being appended to the end of the FitsChan. */ astSetCard( this, INT_MAX ); /* Store the current card index. */ icard = astGetCard( this ); /* Obtain the first header card from the source function. This is an externally supplied function which may not be thread-safe, so lock a mutex first. Also store the channel data pointer in a global variable so that it can be accessed in the source function using macro astChannelData. */ astStoreChannelData( this ); LOCK_MUTEX2; card = ( *this->source_wrap )( source, status ); UNLOCK_MUTEX2; /* Loop until a NULL pointer is returned by the source function, or an error occurs. */ while( card && astOK ){ /* Store the card in the FitsChan. */ astPutFits( this, card, 0 ); /* Free the memory holding the header card. */ card = (char *) astFree( (void *) card ); /* Obtain the next header card. Also store the channel data pointer in a global variable so that it can be accessed in the source function using macro astChannelData. */ astStoreChannelData( this ); LOCK_MUTEX2; card = ( *this->source_wrap )( source, status ); UNLOCK_MUTEX2; } /* Set the current card index so that the first of the new cards will be the next card to be read from the FitsChan. */ astSetCard( this, icard ); } } static void RemoveTables( AstFitsChan *this, const char *key, int *status ){ /* *++ * Name: c astRemoveTables f AST_REMOVETABLES * Purpose: * Remove one or more tables from a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astRemoveTables( AstFitsChan *this, const char *key ) f CALL AST_REMOVETABLES( THIS, KEY, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * removes the named tables from the FitsChan, it they exist (no error * is reported if any the tables do not exist). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c key f KEY = CHARACTER * ( * ) (Given) * The key indicating which tables to exist. A single key or a * comma-separated list of keys can be supplied. If a blank string * is supplied, all tables are removed. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local variables: */ char **words; int itable; int ntable; /* Return if the global error status has been set, or the FitsChan contains no tables KeyMap. */ if( !astOK || !this->tables ) return; /* If the string is blank, remove all tables. */ if( astChrLen( key ) == 0 ) { ntable = astMapSize( this->tables ); for( itable = 0; itable < ntable; itable++ ) { astMapRemove( this->tables, astMapKey( this->tables, itable ) ); } /* Otherwise, split the supplied comma-separated string up into individual items. */ } else { words = astChrSplitC( key, ',', &ntable ); /* Attempt to remove each one, and then free the string. */ if( astOK ) { for( itable = 0; itable < ntable; itable++ ) { astMapRemove( this->tables, words[ itable ] ); words[ itable ] = astFree( words[ itable ] ); } } /* Free the list. */ words = astFree( words ); } } static void RetainFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astRetainFits f AST_RETAINFITS * Purpose: * Indicate that the current card in a FitsChan should be retained. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astRetainFits( AstFitsChan *this ) f CALL AST_RETAINFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * stores a flag with the current card in the FitsChan indicating that * the card should not be removed from the FitsChan when an Object is * read from the FitsChan using c astRead. f AST_READ. * * Cards that have not been flagged in this way are removed when a * read operation completes succesfully, but only if the card was used * in the process of creating the returned AST Object. Any cards that * are irrelevant to the creation of the AST Object are retained whether * or not they are flagged. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - This function returns without action if the FitsChan is * initially positioned at the "end-of-file" (i.e. if the Card * attribute exceeds the number of cards in the FitsChan). * - The current card is not changed by this function. *-- */ /* Local variables: */ int flags; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Return if the global error status has been set, or the current card is not defined. */ if( !astOK || !this->card ) return; /* Set the PROTECTED flag in the current card. */ flags = ( (FitsCard *) this->card )->flags; ( (FitsCard *) this->card )->flags = flags | PROTECTED; } static void RoundFString( char *text, int width, int *status ){ /* * Name: * RoundString * Purpose: * Modify a formatted floating point number to round out long * sequences of zeros or nines. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void RoundFString( char *text, int width ) * Class Membership: * FitsChan member function. * Description: * The supplied string is assumed to be a valid decimal representation of * a floating point number. It is searched for sub-strings consisting * of NSEQ or more adjacent zeros, or NSEQ or more adjacent nines. If found * the string is modified to represent the result of rounding the * number to remove the sequence of zeros or nines. * Parameters: * text * The formatted number. Modified on exit to round out long * sequences of zeros or nines. The returned string is right justified. * width * The minimum field width to use. The value is right justified in * this field width. Ignored if zero. */ /* Local Constants: */ #define NSEQ 4 /* No. of adjacent 0's or 9's to produce rounding */ /* Local Variables: */ char *a; char *c; char *dot; char *exp; char *last; char *start; char *end; int i; int neg; int nnine; int nonzero; int nzero; int replace; int started; int len; int bu; int nls; /* Check the inherited status. */ if( !astOK ) return; /* Save the original length of the text. */ len = strlen( text ); /* Locate the start of any exponent string. */ exp = strpbrk( text, "dDeE" ); /* First check for long strings of adjacent zeros. =============================================== */ /* Indicate that we have not yet found a decimal point in the string. */ dot = NULL; /* The "started" flag controls whether *leading* zeros should be removed if there are more than NSEQ of them. They are only removed if there is an exponent. */ started = ( exp != NULL ); /* We are not currently replacing digits with zeros. */ replace = 0; /* We have not yet found any adjacent zeros. */ nzero = 0; /* We have no evidence yet that the number is non-zero. */ nonzero = 0; /* Loop round the supplied text string. */ c = text; while( *c && c != exp ){ /* If this is a zero, increment the number of adjacent zeros found, so long as we have previously found a non-zero digit (or there is an exponent). If this is the NSEQ'th adjacent zero, indicate that subsequent digits should be replaced by zeros. */ if( *c == '0' ){ if( started && ++nzero >= NSEQ ) replace = 1; /* Note if the number contains a decimal point. */ } else if( *c == '.' ){ dot = c; /* If this character is a non-zero digit, indicate that we have found a non-zero digit. If we have previously found a long string of adjacent zeros, replace the digit by '0'. Otherwise, reset the count of adjacent zeros, and indicate the final number is non-zero. */ } else if( *c != ' ' && *c != '+' && *c != '-' ){ started = 1; if( replace ) { *c = '0'; } else { nzero = 0; nonzero = 1; } } /* Move on to the next character. */ c++; } /* If the final number is zero, just return the most simple decimal zero value. */ if( !nonzero ) { strcpy( text, "0.0" ); /* Otherwise, we remove any trailing zeros which occur to the right of a decimal point. */ } else if( dot ) { /* Find the last non-zero digit. */ while( c-- > text && *c == '0' ); /* If any trailing zeros were found... */ if( c > text ) { /* Retain one trailing zero after a decimal point. */ if( *c == '.' ) c++; /* We put a terminator following the last non-zero character. The terminator is the exponent, if there was one, or a null character. Remember to update the pointer to the start of the exponent. */ c++; if( exp ) { a = exp; exp = c; while( ( *(c++) = *(a++) ) ); } else { *c = 0; } } } /* Next check for long strings of adjacent nines. ============================================= */ /* We have not yet found any adjacent nines. */ nnine = 0; /* We have not yet found a non-nine digit. */ a = NULL; /* We have not yet found a non-blank character */ start = NULL; last = NULL; /* Number is assumed positive. */ neg = 0; /* Indicate that we have not yet found a decimal point in the string. */ dot = NULL; /* Loop round the supplied text string. */ c = text; while( *c && c != exp ){ /* Note the address of the first non-blank character. */ if( !start && *c != ' ' ) start = c; /* If this is a nine, increment the number of adjacent nines found. */ if( *c == '9' ){ ++nnine; /* Note if the number contains a decimal point. */ } else if( *c == '.' ){ dot = c; /* Note if the number is negative. */ } else if( *c == '-' ){ neg = 1; /* If this character is a non-nine digit, and we have not had a long sequence of 9's, reset the count of adjacent nines, and update a pointer to "the last non-nine digit prior to a long string of nines". */ } else if( *c != ' ' && *c != '+' ){ if( nnine < NSEQ ) { nnine = 0; a = c; } } /* Note the address of the last non-blank character. */ if( *c != ' ' ) last = c; /* Move on to the next character. */ c++; } /* If a long string of adjacent nines was found... */ if( nnine >= NSEQ ) { c = NULL; /* If we found at least one non-nine digit. */ if( a ) { /* "a" points to the last non-nine digit before the first of the group of 9's. Increment this digit by 1. Since we know the digit is not a nine, there is no danger of a carry. */ *a = *a + 1; /* Fill with zeros up to the decimal point, or to the end if there is no decimal point. */ c = a + 1; if( dot ) { while( c < dot ) *(c++) = '0'; } else { while( *c ) *(c++) = '0'; } /* Now make "c" point to the first character for the terminator. This is usually the character following the last non-nine digit. However, if the last non-nine digit appears immediately before a decimal point, then we append ".0" to the string before appending the terminator. */ if( *c == '.' ) { *(++c) = '0'; c++; } /* If all digits were nines, the rounded number will occupy one more character than the supplied number. We can only do the rounding if there is a spare character (i.e.a space) in the supplied string. */ } else if( last - start + 1 < len ) { /* Put the modified text at the left of the available space. */ c = text; /* Start with a minus sing if needed, followed by the leading "1" (caused by the overflow from the long string of 9's). */ if( neg ) *(c++) = '-'; *(c++) = '1'; /* Now find the number of zeros to place after the leading "1". This is the number of characters in front of the terminator marking the end of the integer part of the number. */ if( dot ) { nzero = dot - start; } else if( exp ) { nzero = exp - start; } else { nzero = last - start; } /* If the number is negative, the above count will include the leading minus sign, which is not a digit. So reduce the count by one. */ if( neg ) nzero--; /* Now put in the correct number of zeros. */ for( i = 0; i < nzero; i++ ) *(c++) = '0'; /* If the original string containsed a decimal point, make sure the returned string also contains one. */ if( dot ) { *(c++) = '.'; if( *c ) *(c++) = '0'; } } /* We put a terminator following the last non-zero character. The terminator is the exponent, if there was one, or a null character. */ if( c ) { if( exp ) { while( ( *(c++) = *(exp++) ) ); } else { *c = 0; } } } /* Right justify the returned string in the original field width. */ end = text + len; c = text + strlen( text ); if( c != end ) { while( c >= text ) *(end--) = *(c--); while( end >= text ) *(end--) = ' '; } /* If a minimum field width was given, shunt the text to the left in order to reduce the used field width to the specified value. This requires there to be some leading spaces (because we do not want to loose any non-blank characters from the left hand end of the string). If there are insufficient leading spaces to allow the field width to be reduced to the specified value, then reduce the field width as far as possible. First find the number of spaces we would like to remove from the front of the string (in order to reduce the used width to the specified value). */ bu = len - width; /* If we need to remove any leading spaces... */ if( width > 0 && bu > 0 ) { /* Find the number of leading spaces which are available to be removed. */ c = text - 1; while( *(++c) == ' ' ); nls = c - text; /* If there are insufficient leading spaces, just use however many there are. */ if( bu > nls ) bu = nls; /* Shift the string. */ c = text; a = c + bu; while( ( *(c++) = *(a++) ) ); } /* Undefine local constants. */ #undef NSEQ } static int SAOTrans( AstFitsChan *this, AstFitsChan *out, const char *method, const char *class, int *status ){ /* * Name: * SAOTrans * Purpose: * Translate an SAO encoded header into a TPN encoded header. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int SAOTrans( AstFitsChan *this, AstFitsChan *out, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Search "this" for keywords that give a description of a distorted * TAN projection using the SAO representation and, if found, write * keywords to "out" that describe an equivalent projection using TPN * representation. The definition of the SAO polynomial is taken from * the platepos.c file included in Doug Mink's WCSTools. * Parameters: * this * Pointer to the FitsChan to read. * out * Pointer to a FitsCHan in which to store translated keywords. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if "this" contained an SAO encoded header. Zero otherwise. */ #define NC 13 /* Local Variables: */ char keyname[10]; double co[ 2 ][ NC ]; double pv; int i; int is_sao; int m; int ok; int result; /* Initialise */ result = 0; /* Check the inherited status. */ if( !astOK ) return result; /* Check there are exactly two CTYPE keywords in the header. */ if( 2 == astKeyFields( this, "CTYPE%d", 0, NULL, NULL ) ){ /* Initialise all cooefficients. */ memset( co, 0, sizeof( co ) ); /* Get the required SAO keywords. */ is_sao = 1; ok = 1; for( i = 0; i < 2 && ok && is_sao; i++ ) { ok = 0; for( m = 0; m < NC; m++ ) { /* Get the value of the next "COi_j" keyword. If any of the first 3 values are missing on either axis, we assume this is not an SAO header. */ sprintf( keyname, "CO%d_%d", i + 1, m + 1 ); if( !GetValue( this, keyname, AST__FLOAT, &co[ i ][ m ], 0, 1, method, class, status ) ) { if( m < 3 ) is_sao = 0; break; } /* Check that we have at least one non-zero coefficient (excluding the first constant term ). */ if( co[ i ][ m ] != 0.0 && m > 0 ) ok = 1; } } /* If this is an SAO header.. */ if( is_sao ) { /* Issue a warning if all coefficients for this axis are zero. */ if( !ok ) { Warn( this, "badpv", "This FITS header describes an SAO encoded " "distorted TAN projection, but all the distortion " "coefficients for at least one axis are zero.", method, class, status ); /* Otherwise, calculate and store the equivalent PV projection parameters. */ } else { pv = co[ 0 ][ 0 ]; if( pv != AST__BAD ) SetValue( out, "PV1_0", &pv, AST__FLOAT, NULL, status ); pv = co[ 0 ][ 1 ]; if( pv != AST__BAD ) SetValue( out, "PV1_1", &pv, AST__FLOAT, NULL, status ); pv = co[ 0 ][ 2 ]; if( pv != AST__BAD ) SetValue( out, "PV1_2", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 3 ] != AST__BAD ) pv += co[ 0 ][ 3 ]; if( co[ 0 ][ 10 ] != AST__BAD ) pv += co[ 0 ][ 10 ]; if( pv != AST__BAD ) SetValue( out, "PV1_4", &pv, AST__FLOAT, NULL, status ); pv = co[ 0 ][ 5 ]; if( pv != AST__BAD ) SetValue( out, "PV1_5", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 4 ] != AST__BAD ) pv += co[ 0 ][ 4 ]; if( co[ 0 ][ 10 ] != AST__BAD ) pv += co[ 0 ][ 10 ]; if( pv != AST__BAD ) SetValue( out, "PV1_6", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 6 ] != AST__BAD ) pv += co[ 0 ][ 6 ]; if( co[ 0 ][ 11 ] != AST__BAD ) pv += co[ 0 ][ 11 ]; if( pv != AST__BAD ) SetValue( out, "PV1_7", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 8 ] != AST__BAD ) pv += co[ 0 ][ 8 ]; if( co[ 0 ][ 12 ] != AST__BAD ) pv += co[ 0 ][ 12 ]; if( pv != AST__BAD ) SetValue( out, "PV1_8", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 9 ] != AST__BAD ) pv += co[ 0 ][ 9 ]; if( co[ 0 ][ 11 ] != AST__BAD ) pv += co[ 0 ][ 11 ]; if( pv != AST__BAD ) SetValue( out, "PV1_9", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 0 ][ 7 ] != AST__BAD ) pv += co[ 0 ][ 7 ]; if( co[ 0 ][ 12 ] != AST__BAD ) pv += co[ 0 ][ 12 ]; if( pv != AST__BAD ) SetValue( out, "PV1_10", &pv, AST__FLOAT, NULL, status ); pv = co[ 1 ][ 0 ]; if( pv != AST__BAD ) SetValue( out, "PV2_0", &pv, AST__FLOAT, NULL, status ); pv = co[ 1 ][ 2 ]; if( pv != AST__BAD ) SetValue( out, "PV2_1", &pv, AST__FLOAT, NULL, status ); pv = co[ 1 ][ 1 ]; if( pv != AST__BAD ) SetValue( out, "PV2_2", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 4 ] != AST__BAD ) pv += co[ 1 ][ 4 ]; if( co[ 1 ][ 10 ] != AST__BAD ) pv += co[ 1 ][ 10 ]; if( pv != AST__BAD ) SetValue( out, "PV2_4", &pv, AST__FLOAT, NULL, status ); pv = co[ 1 ][ 5 ]; if( pv != AST__BAD ) SetValue( out, "PV2_5", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 3 ] != AST__BAD ) pv += co[ 1 ][ 3 ]; if( co[ 1 ][ 10 ] != AST__BAD ) pv += co[ 1 ][ 10 ]; if( pv != AST__BAD ) SetValue( out, "PV2_6", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 7 ] != AST__BAD ) pv += co[ 1 ][ 7 ]; if( co[ 1 ][ 12 ] != AST__BAD ) pv += co[ 1 ][ 12 ]; if( pv != AST__BAD ) SetValue( out, "PV2_7", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 9 ] != AST__BAD ) pv += co[ 1 ][ 9 ]; if( co[ 1 ][ 11 ] != AST__BAD ) pv += co[ 1 ][ 11 ]; if( pv != AST__BAD ) SetValue( out, "PV2_8", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 8 ] != AST__BAD ) pv += co[ 1 ][ 8 ]; if( co[ 1 ][ 12 ] != AST__BAD ) pv += co[ 1 ][ 12 ]; if( pv != AST__BAD ) SetValue( out, "PV2_9", &pv, AST__FLOAT, NULL, status ); pv = 0.0; if( co[ 1 ][ 6 ] != AST__BAD ) pv += co[ 1 ][ 6 ]; if( co[ 1 ][ 11 ] != AST__BAD ) pv += co[ 1 ][ 11 ]; if( pv != AST__BAD ) SetValue( out, "PV2_10", &pv, AST__FLOAT, NULL, status ); /* From an example header provided by Bill Joye, it seems that the SAO polynomial includes the rotation and scaling effects of the CD matrix. Therefore we mark as read all CDi_j, CDELT and CROTA values. Without this, the rotation and scaling would be applied twice. First, mark the original values as having been used, no matter which FitsChan they are in. */ GetValue( this, "CD1_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CD1_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CD2_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CD2_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "PC1_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "PC1_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "PC2_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "PC2_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CDELT1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CDELT2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CROTA1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( this, "CROTA2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CD1_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CD1_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CD2_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CD2_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "PC1_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "PC1_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "PC2_1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "PC2_2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CDELT1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CDELT2", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CROTA1", AST__FLOAT, &pv, 0, 1, method, class, status ); GetValue( out, "CROTA2", AST__FLOAT, &pv, 0, 1, method, class, status ); /* Now store new default values in the returned FitsChan. */ pv = 1.0; SetValue( out, "PC1_1", &pv, AST__FLOAT, NULL, status ); SetValue( out, "PC2_2", &pv, AST__FLOAT, NULL, status ); SetValue( out, "CDELT1", &pv, AST__FLOAT, NULL, status ); SetValue( out, "CDELT2", &pv, AST__FLOAT, NULL, status ); pv = 0.0; SetValue( out, "PC1_2", &pv, AST__FLOAT, NULL, status ); SetValue( out, "PC2_1", &pv, AST__FLOAT, NULL, status ); /* Indicate we have converted an SAO header. */ result = 1; } } } /* Return a flag indicating if an SAO header was found. */ return result; } #undef NC static int SearchCard( AstFitsChan *this, const char *name, const char *method, const char *class, int *status ){ /* * Name: * SearchCard * Purpose: * Search the whole FitsChan for a card refering to given keyword. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int SearchCard( AstFitsChan *this, const char *name, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * Searches the whole FitsChan for a card refering to the supplied keyword, * and makes it the current card. The card following the current card is * checked first. If this is not the required card, then a search is * performed starting with the first keyword in the FitsChan. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a string holding the keyword name. * method * Pointer to string holding name of calling method. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if a card was found refering to the given * keyword. Otherwise zero is returned. * Notes: * - If a NULL pointer is supplied for "name" then the current card * is left unchanged. * - The current card is set to NULL (end-of-file) if no card can be * found for the supplied keyword. */ /* Local Variables: */ int ret; /* Was a card found? */ /* Check the global status, and supplied keyword name. */ if( !astOK || !name ) return 0; /* Indicate that no card has been found yet. */ ret = 0; /* The required card is very often the next card in the FitsChan, so check the next card, and only search the entire FitsChan if the check fails. */ MoveCard( this, 1, method, class, status ); if( !astFitsEof( this ) && !Ustrncmp( CardName( this, status ), name, FITSNAMLEN, status ) ){ ret = 1; /* If the next card is not the required card, rewind the FitsChan back to the first card. */ } else { astClearCard( this ); /* Attempt to find the supplied keyword, searching from the first card. */ ret = FindKeyCard( this, name, method, class, status ); } /* Return. */ return ret; } static void SetAlgCode( char *buf, const char *algcode, int *status ){ /* * Name: * SetAlgCode * Purpose: * Create a non-linear CTYPE string from a system code and an algorithm * code. * Type: * Private function. * Synopsis: * void SetAlgCode( char *buf, const char *algcode, int *status ) * Class Membership: * FitsChan * Description: * FITS-WCS paper 1 says that non-linear axes must have a CTYPE of the * form "4-3" (e.g. "VRAD-TAB"). This function handles the truncation * of long system codes, or the padding of short system codes. * Parameters: * buf * A buffer in which is stored the system code. Modified on exit to * hold the combined CTYPE value. It should have a length long * enough to hold the system code and the algorithm code. * algcode * Pointer to a string holding the algorithm code (with a leading * "-", e.g. "-TAB"). * status * Pointer to the inherited status variable. */ /* Local Variables: */ int nc; /* Check inherited status */ if( !astOK ) return; /* Pad the supplied string to at least 4 characters using "-" characters. */ nc = strlen( buf ); while( nc < 4 ) buf[ nc++ ] = '-'; /* Insert the null-terminated code at position 4. */ strcpy( buf + 4, algcode ); } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * FitsChan member function (over-rides the astSetAttrib protected * method inherited from the Channel class). * Description: * This function assigns an attribute value for a FitsChan, 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 FitsChan. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ const char *class; /* Object class */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ int offset; /* Offset of attribute string */ int warn; /* Offset of Warnings string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_object; /* Obtain the length of the setting string. */ len = (int) strlen( setting ); /* Obtain the object class. */ class = astGetClass( this ); /* Card. */ /* ----- */ if ( nc = 0, ( 1 == astSscanf( setting, "card= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetCard( this, ival ); /* Encoding. */ /* --------- */ } else if( nc = 0, ( 0 == astSscanf( setting, "encoding=%n%*[^\n]%n", &ival, &nc ) ) && ( nc >= len ) ) { nc = ChrLen( setting + ival, status ); if( !Ustrncmp( setting + ival, NATIVE_STRING, nc, status ) ){ astSetEncoding( this, NATIVE_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSPC_STRING, nc, status ) ){ astSetEncoding( this, FITSPC_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSPC_STRING2, nc, status ) ){ astSetEncoding( this, FITSPC_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSWCS_STRING, nc, status ) ){ astSetEncoding( this, FITSWCS_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSWCS_STRING2, nc, status ) ){ astSetEncoding( this, FITSWCS_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSIRAF_STRING, nc, status ) ){ astSetEncoding( this, FITSIRAF_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSIRAF_STRING2, nc, status ) ){ astSetEncoding( this, FITSIRAF_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSAIPS_STRING, nc, status ) ){ astSetEncoding( this, FITSAIPS_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSAIPS_STRING2, nc, status ) ){ astSetEncoding( this, FITSAIPS_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSAIPSPP_STRING, nc, status ) ){ astSetEncoding( this, FITSAIPSPP_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSAIPSPP_STRING2, nc, status ) ){ astSetEncoding( this, FITSAIPSPP_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSCLASS_STRING, nc, status ) ){ astSetEncoding( this, FITSCLASS_ENCODING ); } else if( !Ustrncmp( setting + ival, FITSCLASS_STRING2, nc, status ) ){ astSetEncoding( this, FITSCLASS_ENCODING ); } else if( !Ustrncmp( setting + ival, DSS_STRING, nc, status ) ){ astSetEncoding( this, DSS_ENCODING ); } else { astError( AST__BADAT, "astSet(%s): Unknown encoding system '%s' " "requested for a %s.", status, class, setting + ival, class ); } /* FitsDigits. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "fitsdigits= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetFitsDigits( this, ival ); /* FitsAxisOrder. */ /* -------------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "fitsaxisorder=%n%*[^\n]%n", &offset, &nc ) ) && ( nc >= len ) ) { astSetFitsAxisOrder( this, setting + offset ); /* CDMatrix */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "cdmatrix= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetCDMatrix( this, ival ); /* DefB1950 */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "defb1950= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetDefB1950( this, ival ); /* TabOK */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "tabok= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetTabOK( this, ival ); /* CarLin */ /* ------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "carlin= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetCarLin( this, ival ); /* PolyTan */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "polytan= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetPolyTan( this, ival ); /* Iwc */ /* --- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "iwc= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetIwc( this, ival ); /* Clean */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "clean= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetClean( this, ival ); /* Warnings. */ /* -------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "warnings=%n%*[^\n]%n", &warn, &nc ) ) && ( nc >= len ) ) { astSetWarnings( this, setting + warn ); /* 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( "ncard" ) || MATCH( "cardtype" ) || MATCH( "cardcomm" ) || MATCH( "cardname" ) || MATCH( "nkey" ) || MATCH( "allwarnings" ) ){ 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetCard( AstFitsChan *this, int icard, int *status ){ /* *+ * Name: * astSetCard * Purpose: * Set the value of the Card attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * void astSetCard( AstFitsChan *this, int icard ) * Class Membership: * FitsChan method. * Description: * This function sets the value of the Card attribute for the supplied * FitsChan. This is the index of the next card to be read from the * FitsChan. If a value of 1 or less is supplied, the first card in * the FitsChan will be read next. If a value greater than the number * of cards in the FitsChan is supplied, the FitsChan will be left in an * "end-of-file" condition, in which no further read operations can be * performed. * Parameters: * this * Pointer to the FitsChan. * icard * The index of the next card to read. * Notes: * - This function attempts to execute even if an error has occurred. *- */ /* Check the supplied object. */ if ( !this ) return; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Rewind the FitsChan. */ astClearCard( this ); /* Move forward the requested number of cards. */ MoveCard( this, icard - 1, "astSetCard", astGetClass( this ), status ); /* Return. */ return; } static void SetItem( double ****item, int i, int jm, char s, double val, int *status ){ /* * Name: * SetItem * Purpose: * Store a value for a axis keyword value in a FitStore structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SetItem( double ****item, int i, int jm, char s, double val, int *status ) * Class Membership: * FitsChan member function. * Description: * The supplied keyword value is stored in the specified array, * at a position indicated by the axis and co-ordinate version. * The array is created or extended as necessary to make room for * the new value. Any old value is over-written. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->crval) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword values. These arrays of keyword values have * one element for every pixel axis (j) or projection parameter (m). * i * The zero based intermediate axis index in the range 0 to 98. Set * this to zero for keywords (e.g. CRPIX) which are not indexed by * intermediate axis number. * jm * The zero based pixel axis index (in the range 0 to 98) or parameter * index (in the range 0 to WCSLIB__MXPAR-1). Set this to zero for * keywords (e.g. CRVAL) which are not indexed by either pixel axis or * parameter number. * val * The keyword value to store. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int el; /* Array index */ int nel; /* Number of elements in array */ int si; /* Integer co-ordinate version index */ /* Check the inherited status. */ if( !astOK ) return; /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "SetItem(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); /* Check the intermediate axis index is within range. */ } else if( i < 0 || i > 98 ) { astError( AST__INTER, "SetItem(fitschan): AST internal error; " "intermediate axis index %d is invalid.", status, i ); /* Check the pixel axis or parameter index is within range. */ } else if( jm < 0 || jm > 99 ) { astError( AST__INTER, "SetItem(fitschan): AST internal error; " "pixel axis or parameter index %d is invalid.", status, jm ); /* Otherwise proceed... */ } else { /* Store the current number of coordinate versions in the supplied array */ nel = astSizeOf( (void *) *item )/sizeof(double **); /* If required, extend the array located by the supplied pointer so that it is long enough to hold the specified co-ordinate version. */ if( nel < si + 1 ){ *item = (double ***) astGrow( (void *) *item, si + 1, sizeof(double **) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold NULL. Note, astGrow may add more elements to the array than is actually needed, so use the actual current size of the array as implied by astSize rather than the index si. */ for( el = nel; el < astSizeOf( (void *) *item )/sizeof(double **); el++ ) (*item)[el] = NULL; } } /* If the above went OK... */ if( astOK ){ /* Store the currrent number of intermediate axes in the supplied array */ nel = astSizeOf( (void *) (*item)[si] )/sizeof(double *); /* If required, extend the array so that it is long enough to hold the specified intermediate axis. */ if( nel < i + 1 ){ (*item)[si] = (double **) astGrow( (void *) (*item)[si], i + 1, sizeof(double *) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold NULL. */ for( el = nel; el < astSizeOf( (void *) (*item)[si] )/sizeof(double *); el++ ) (*item)[si][el] = NULL; } } /* If the above went OK... */ if( astOK ){ /* Store the current number of pixel axis or parameter values in the array. */ nel = astSizeOf( (void *) (*item)[si][i] )/sizeof(double); /* If required, extend the array so that it is long enough to hold the specified axis. */ if( nel < jm + 1 ){ (*item)[si][i] = (double *) astGrow( (void *) (*item)[si][i], jm + 1, sizeof(double) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold AST__BAD. */ for( el = nel; el < astSizeOf( (void *) (*item)[si][i] )/sizeof(double); el++ ) (*item)[si][i][el] = AST__BAD; } } /* If the above went OK, store the supplied keyword value. */ if( astOK ) (*item)[si][i][jm] = val; } } } } static void SetItemC( char *****item, int i, int jm, char s, const char *val, int *status ){ /* * Name: * SetItemC * Purpose: * Store a character string for an axis keyword value in a FitStore * structure. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SetItemC( char *****item, int i, int jm, char s, const char *val, * int *status ) * Class Membership: * FitsChan member function. * Description: * The supplied keyword string value is stored in the specified array, * at a position indicated by the axis and co-ordinate version. * The array is created or extended as necessary to make room for * the new value. Any old value is over-written. * Parameters: * item * The address of the pointer within the FitsStore which locates the * arrays of values for the required keyword (eg &(store->ctype) ). * The array located by the supplied pointer contains a vector of * pointers. Each of these pointers is associated with a particular * co-ordinate version (s), and locates an array of pointers for that * co-ordinate version. Each such array of pointers has an element * for each intermediate axis number (i), and the pointer locates an * array of axis keyword string pointers. These arrays of keyword * string pointers have one element for every pixel axis (j) or * projection parameter (m). * i * The zero based intermediate axis index in the range 0 to 98. Set * this to zero for keywords (e.g. RADESYS) which are not indexed by * intermediate axis number. * jm * The zero based pixel axis index (in the range 0 to 98) or parameter * index (in the range 0 to WCSLIB__MXPAR-1). Set this to zero for * keywords (e.g. CTYPE) which are not indexed by either pixel axis or * parameter number. * val * The keyword string value to store. A copy of the supplied string * is taken. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int el; /* Array index */ int nel; /* Number of elements in array */ int si; /* Integer co-ordinate version index */ /* Check the inherited status and the supplied pointer. */ if( !astOK || !val ) return; /* Convert the character co-ordinate version into an integer index, and check it is within range. The primary axis description (s=' ') is given index zero. 'A' is 1, 'B' is 2, etc. */ if( s == ' ' ) { si = 0; } else if( islower(s) ){ si = (int) ( s - 'a' ) + 1; } else { si = (int) ( s - 'A' ) + 1; } if( si < 0 || si > 26 ) { astError( AST__INTER, "SetItemC(fitschan): AST internal error; " "co-ordinate version '%c' ( char(%d) ) is invalid.", status, s, s ); /* Check the intermediate axis index is within range. */ } else if( i < 0 || i > 98 ) { astError( AST__INTER, "SetItemC(fitschan): AST internal error; " "intermediate axis index %d is invalid.", status, i ); /* Check the pixel axis or parameter index is within range. */ } else if( jm < 0 || jm > 99 ) { astError( AST__INTER, "SetItemC(fitschan): AST internal error; " "pixel axis or parameter index %d is invalid.", status, jm ); /* Otherwise proceed... */ } else { /* Store the current number of coordinate versions in the supplied array */ nel = astSizeOf( (void *) *item )/sizeof(char ***); /* If required, extend the array located by the supplied pointer so that it is long enough to hold the specified co-ordinate version. */ if( nel < si + 1 ){ *item = (char ****) astGrow( (void *) *item, si + 1, sizeof(char ***) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold NULL. Note, astGrow may add more elements to the array than is actually needed, so use the actual current size of the array as implied by astSize rather than the index si. */ for( el = nel; el < astSizeOf( (void *) *item )/sizeof(char ***); el++ ) (*item)[el] = NULL; } } /* If the above went OK... */ if( astOK ){ /* Store the currrent number of intermediate axes in the supplied array */ nel = astSizeOf( (void *) (*item)[si] )/sizeof(char **); /* If required, extend the array so that it is long enough to hold the specified intermediate axis. */ if( nel < i + 1 ){ (*item)[si] = (char ***) astGrow( (void *) (*item)[si], i + 1, sizeof(char **) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold NULL. */ for( el = nel; el < astSizeOf( (void *) (*item)[si] )/sizeof(char **); el++ ) (*item)[si][el] = NULL; } } /* If the above went OK... */ if( astOK ){ /* Store the current number of pixel axis or parameter values in the array. */ nel = astSizeOf( (void *) (*item)[si][i] )/sizeof(char *); /* If required, extend the array so that it is long enough to hold the specified axis. */ if( nel < jm + 1 ){ (*item)[si][i] = (char **) astGrow( (void *) (*item)[si][i], jm + 1, sizeof(char *) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the new elements to hold NULL. */ for( el = nel; el < astSizeOf( (void *) (*item)[si][i] )/sizeof(char *); el++ ) (*item)[si][i][el] = NULL; } } /* If the above went OK... */ if( astOK ){ /* Store a copy of the supplied string, using any pre-allocated memory. */ (*item)[si][i][jm] = (char *) astStore( (void *) (*item)[si][i][jm], (void *) val, strlen( val ) + 1 ); } } } } } static void SetSourceFile( AstChannel *this_channel, const char *source_file, int *status ) { /* * Name: * SetSourceFile * Purpose: * Set a new value for the SourceFile attribute. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SetSourceFile( AstChannel *this, const char *source_file, * int *status ) * Class Membership: * FitsChan member function (over-rides the astSetSourceFile * method inherited from the Channel class). * Description: * This function stores the supplied string as the new value for the * SourceFile attribute. In addition, it also attempts to open the * file, read FITS headers from it and append them to the end of the * FitsChan. It then closes the SourceFile. * Parameters: * this * Pointer to the FitsChan. * source_file * The new attribute value. Should be the path to an existing text * file, holding FITS headers (one per line) * status * Inherited status pointer. */ /* Local Constants: */ #define ERRBUF_LEN 80 /* Local Variables: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ FILE *fd; /* Descriptor for source file */ char *errstat; /* Pointer for system error message */ char card[ AST__FITSCHAN_FITSCARDLEN + 2 ]; /* Buffer for source line */ char errbuf[ ERRBUF_LEN ]; /* Buffer for system error message */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Invoke the parent astSetSourceFile method to store the supplied string in the Channel structure. */ (*parent_setsourcefile)( this_channel, source_file, status ); /* Attempt to open the file. */ fd = NULL; if( astOK ) { fd = fopen( source_file, "r" ); if( !fd ) { if ( errno ) { #if HAVE_STRERROR_R strerror_r( errno, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( errno ); #endif astError( AST__RDERR, "astSetSourceFile(%s): Failed to open input " "SourceFile '%s' - %s.", status, astGetClass( this ), source_file, errstat ); } else { astError( AST__RDERR, "astSetSourceFile(%s): Failed to open input " "SourceFile '%s'.", status, astGetClass( this ), source_file ); } } } /* Move the FitsChan to EOF */ astSetCard( this, INT_MAX ); /* Read each line from the file, remove trailing space, and append to the FitsChan. */ while( astOK && fgets( card, AST__FITSCHAN_FITSCARDLEN + 2, fd ) ) { card[ astChrLen( card ) ] = 0; astPutFits( this, card, 0 ); } /* Close the source file. */ if( fd ) fclose( fd ); } static void SetTableSource( AstFitsChan *this, void (*tabsource)( void ), void (*tabsource_wrap)( void (*)( void ), AstFitsChan *, const char *, int, int, int * ), int *status ){ /* *+ * Name: * astSetTableSource * Purpose: * Register source and wrapper function for accessing tables in FITS files. * Type: * Protected function. * Synopsis: * #include "fitschan.h" * void astSetTableSource( AstFitsChan *this, * void (*tabsource)( void ), * void (*tabsource_wrap)( void (*)( void ), * AstFitsChan *, const char *, * int, int, int * ), * int *status ) * Class Membership: * FitsChan member function. * Description: * This function registers a table source function and its wrapper. A * wrapper function exists to adapt the API of the table source * function to the needs of different languages. The wrapper is called * from the FitsChan code. The wrapper then adjusts the arguments as * required and then calls the actualy table source function. * Parameters: * this * Pointer to the FitsChan. * tabsource * Pointer to the table source function. The API for this function * will depend on the language, and so is cast to void here. It * should be cast to the required form within the wrapper function. * tabsource_wrap * The wrapper function. *- */ /* Local Variables: */ /* Check the global error status. */ if ( !astOK ) return; this->tabsource = tabsource; this->tabsource_wrap = tabsource_wrap; } static void SetValue( AstFitsChan *this, const char *keyname, void *value, int type, const char *comment, int *status ){ /* * Name: * SetValue * Purpose: * Save a FITS keyword value, over-writing any existing keyword value. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SetValue( AstFitsChan *this, char *keyname, void *value, * int type, const char *comment, int *status ) * Class Membership: * FitsChan * Description: * This function saves a keyword value as a card in the supplied * FitsChan. Comment cards are always inserted in-front of the current * card. If the keyword is not a comment card, any existing value * for the keyword is over-written with the new value (even if it is * marked as having been read). Otherwise, (i.e. if it is not a comment * card, and no previous value exists) it is inserted in front * of the current card. * Parameters: * this * A pointer to the FitsChan. * keyname * A pointer to a string holding the keyword name. * value * A pointer to a buffer holding the keyword value. For strings, * the buffer should hold a pointer to the character string. * type * The FITS data type of the supplied keyword value. * comment * A comment to store with the keyword. * status * Pointer to the inherited status variable. * Notes: * - Nothing is stored if a NULL pointer is supplied for "value". * - If the keyword has a value of AST__BAD then nothing is stored, * and an error is reported. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ FitsCard *card; /* Pointer to original current card */ const char *class; /* Class name to include in error messages */ const char *method; /* Method name to include in error messages */ int newcard; /* Has the original current card been deleted? */ int old_ignore_used; /* Original setting of external ignore_used variable */ int stored; /* Has the keyword been stored? */ /* Check the status and supplied value pointer. */ if( !astOK || !value ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Set up the method and class names for inclusion in error mesages. */ method = "astWrite"; class = astGetClass( this ); /* Comment card are always inserted in-front of the current card. */ if ( type == AST__COMMENT ) { SetFits( this, keyname, value, type, comment, 0, status ); /* Otherwise... */ } else { /* Report an error if a bad value is stored for a keyword. */ if( type == AST__FLOAT ){ if( *( (double *) value ) == AST__BAD && astOK ) { astError( AST__BDFTS, "%s(%s): The required FITS keyword " "\"%s\" is indeterminate.", status, method, class, keyname ); } } /* Save a pointer to the current card. */ card = (FitsCard *) this->card; /* Indicate that we should not skip over cards marked as having been read. */ old_ignore_used = ignore_used; ignore_used = 0; /* Indicate that we have not yet stored the keyword value. */ stored = 0; /* Attempt to find a card refering to the supplied keyword. If one is found, it becomes the current card. */ if( SearchCard( this, keyname, "astWrite", astGetClass( this ), status ) ){ /* If the card which was current on entry to this function will be over-written, we will need to take account of this when re-instating the original current card. Make a note of this. */ newcard = ( card == (FitsCard *) this->card ); /* Replace the current card with a card holding the supplied information. */ SetFits( this, keyname, value, type, comment, 1, status ); stored = 1; /* If we have just replaced the original current card, back up a card so that the replacement card becomes the current card. */ if( newcard ) { MoveCard( this, -1, "astWrite", astGetClass( this ), status ); /* Otherwise, re-instate the original current card. */ } else { this->card = (void *) card; } } /* If the keyword has not yet been stored (i.e. if it did not exist in the FitsChan), re-instate the original current card and insert the new card before the original current card, leaving the current card unchanged. */ if( !stored ) { this->card = (void *) card; SetFits( this, keyname, value, type, comment, 0, status ); } /* Re-instate the original flag indicating if cards marked as having been read should be skipped over. */ ignore_used = old_ignore_used; } } static void Shpc1( double xmin, double xmax, int n, double *d, double *w, int *status ){ /* * Name: * Shpc1 * Purpose: * Modifies a one-dimensional polynomial to scale the polynomial argument. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void Shpc1( double xmin, double xmax, int n, double *d, double *w, * int *status ) * Description: * Given the coefficients of a one-dimensional polynomial P(u) defined on a * unit interval (i.e. -1 <= u <= +1 ), find the coefficients of another * one-dimensional polynomial Q(x) where: * * Q(x) = P(u) * u = ( 2*x - ( xmax + xmin ) ) / ( xmax - xmin ) * * That is, u is a scaled version of x, such that the unit interval in u * maps onto (xmin:xmax) in x. * Parameters: * xmin * X value corresponding to u = -1 * xmax * X value corresponding to u = +1 * n * One more than the maximum power of u within P. * d * An array of n elements supplied holding the coefficients of P such * that the coefficient of (u^i) is held in element (i). * w * An array of n elements returned holding the coefficients of Q such * that the coefficient of (x^i) is held in element (i). * status * Pointer to the inherited status variable. * Notes: * - Vaguely inspired by the Numerical Recipes routine "pcshft". But the * original had bugs, so I wrote this new version from first principles. */ /* Local Variables: */ double b; double a; int j; int i; /* Check inherited status */ if( !astOK ) return; /* Get the scale and shift terms so that u = a*x + b */ a = 2.0/( xmax - xmin ); b = ( xmin + xmax )/( xmin - xmax ); /* Initialise the returned coeffs */ for( i = 0; i < n; i++ ) w[ i ] = 0.0; /* The supplied Polynomial is P(u) = d0 + d1*u + d2*u^2 + ... = d0 + u*( d1 + u*( d2 + ... u*( d{n-1} ) ) ) . . . . . (1) = d0 + (a*x+b)*( d1 + (a*x+b)*( d2 + ... (a*x+b)*( d[n-1] ) ) ) The inner-most parenthesised expression is a polynomial of order zero (a constant - d[n-1]). Store the coefficients of this zeroth order polynomial in the returned array. The "w" array is used to hold the coefficients of Q, i.e. coefficients of powers of "x", not "u", but since the inner-most polynomial is a constant, it makes no difference (x^0 == u^0 == 1). */ w[ 0 ] = d[ n - 1 ]; /* Now loop through each remaining level of parenthetic nesting in (1). At each level, the parenthesised expression represents a polynomial of order "i". At the end of each pass though this loop, the returned array "w" holds the coefficients of this "i"th order polynomial. So on the last loop, i = n-1, "w" holds the required coefficients of Q. */ for( i = 1; i < n; i++ ) { /* If "R" is the polynomial at the "i-1"th level of nesting (the coefficiemts of which are currently held in "w"), and "S" is the polynomial at the "i"th level of nesting, we can see from (1) that: S = d[ n - 1 - i ] + u*R Substituting for "u", this becomes S = d[ n - 1 - i ] + ( a*x + b )*R = d[ n - 1 - i ] + a*R*x + b*R Looking at each of these three terms in reverse order: 1) The "b*R" term is implemented by simply scaling the current contents of the "w" array by "b"; in the "a*R*x" term. 2) In "a*R*x", the effect of multiplying by "x" is to move the existing coefficients in "w" up one element. We then multiply the shifted coefficients by "a" and add them onto the coefficients produced at step 1) above. We know that "w" still contains the initial zeros at indices higher than "i" so we only need to scale the bottom "i" elements. We do not do the zeroth term in this loop since there is no lower term to shift up into it. */ for( j = i; j > 0; j-- ){ w[ j ] = b*w[ j ] + a*w[ j - 1 ]; } /* Now do the zeroth term. Scale the existing zeroth term by "b" as required by step 1) and add on the first term, the constant "d[ n - 1 - i ]". Step 2) is a no-op, since in effect the value of "w[-1]" is zero. */ w[ 0 ] = d[ n - i - 1 ] + b*w[ 0 ]; } } static void ShowFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astShowFits f AST_SHOWFITS * Purpose: * Display the contents of a FitsChan on standard output. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astShowFits( AstFitsChan *this ) f CALL AST_SHOWFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * formats and displays all the cards in a FitsChan on standard output. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char card[ AST__FITSCHAN_FITSCARDLEN + 1]; /* Buffer for header card */ int icard; /* Current card index on entry */ int old_ignore_used; /* Original value of external variable ignore_used */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Store the current card index. */ icard = astGetCard( this ); /* Indicate that cards which have been read into an AST object should skipped over by the functions which navigate the linked list of cards. */ old_ignore_used = ignore_used; ignore_used = 1; /* Ensure that the first card in the FitsChan will be the next one to be read. */ astSetCard( this, 1 ); /* Loop round obtaining and writing out each card, until all cards have been processed. */ while( !astFitsEof( this ) && astOK ){ /* Get the current card, and display it. The call to astFindFits increments the current card. */ if( astFindFits( this, "%f", card, 1 ) ) printf( "%s\n", card ); } /* Re-instate the original flag indicating if cards marked as having been read should be skipped over. */ ignore_used = old_ignore_used; /* Set the current card index back to what it was on entry. */ astSetCard( this, icard ); } static int Similar( const char *str1, const char *str2, int *status ){ /* * Name: * Similar * Purpose: * Are two string effectively the same to human readers? * Type: * Private function. * Synopsis: * #include "fitschan.h" * void Similar( const char *str1, const char *str2, int *status ) * Class Membership: * FitsChan * Description: * This function returns a non-zero value if the two supplied strings * are equivalent to a human reader. This is assumed to be the case if * the strings are equal apart from leading and trailing white space, * multiple embedded space, and case. * Parameters: * str1 * The first string * str2 * The second string * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the two supplied strings are equivalent, and zero * otherwise. */ /* Local Variables: */ const char *ea; /* Pointer to end of string a */ const char *eb; /* Pointer to end of string b */ const char *a; /* Pointer to next character in string a */ const char *b; /* Pointer to next character in string b */ int result; /* Are the two strings equivalent? */ int ss; /* Skip subsequent spaces? */ /* Initialise */ result = 0; /* Check the status and supplied value pointer. */ if( !astOK ) return result; /* Initialise pointers into the two strings. */ a = str1; b = str2; /* Get a pointer to the character following the last non-blank character in each string. */ ea = a + ChrLen( a, status ) - 1; eb = b + ChrLen( b, status ) - 1; /* Set a flag indicating that spaces before the next non-blank character should be ignored. */ ss = 1; /* Compare the strings. */ while( 1 ){ /* Move on to the next significant character in both strings. */ while( a < ea && *a == ' ' && ss ) a++; while( b < eb && *b == ' ' && ss ) b++; /* If one string has been exhausted but the other has not, the strings are not equivalent. */ if( ( a < ea && b == eb ) || ( a == ea && b < eb ) ) { break; /* If both strings have been exhausted simultaneously, the strings are equivalent. */ } else if( b == eb && a == ea ) { result = 1; break; /* If neither string has been exhausted, compare the current character for equality, ignoring case. Break if they are different. */ } else if( tolower( *a ) != tolower( *b ) ){ break; /* If the two characters are both spaces, indicate that subsequent spaces should be skipped. */ } else if( *a == ' ' ) { ss = 1; /* If the two characters are not spaces, indicate that subsequent spaces should not be skipped. */ } else { ss = 0; } /* Move on to the next characters. */ a++; b++; } /* Return the result. */ return result; } static void SinkWrap( void (* sink)( const char * ), const char *line, int *status ) { /* * Name: * SinkWrap * Purpose: * Wrapper function to invoke a C FitsChan sink function. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SinkWrap( void (* sink)( const char * ), const char *line, int *status ) * Class Membership: * FitsChan member function. * Description: * This function invokes the sink function whose pointer is * supplied in order to write an output line to an external data * store. * Parameters: * sink * Pointer to a sink function, whose single parameter is a * pointer to a const, null-terminated string containing the * text to be written, and which returns void. This is the form * of FitsChan sink function employed by the C language interface * to the AST library. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the sink function. */ ( *sink )( line ); } static AstMapping *SIPMapping( double *dim, FitsStore *store, char s, int naxes, const char *method, const char *class, int *status ){ /* * Name: * SIPMapping * Purpose: * Create a Mapping descriping "-SIP" (Spitzer) distortion. * Type: * Private function. * Synopsis: * AstMapping *SIPMapping( double *dim, FitsStore *store, char s, int naxes, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function uses the values in the supplied FitsStore to create a * Mapping which implements the "-SIP" distortion code. This is the * code used by the Spitzer project and is described in: * * http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf * * SIP distortion can only be applied to axes 0 and 1. Other axes are * passed unchanged by the returned Mapping. * Parameters: * dim * The dimensions of the array in pixels. AST__BAD is stored for * each value if dimensions are not known. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstMapping *ret; /* Pointer to the returned Mapping */ AstPolyMap *pmap; /* PolyMap describing the distortion */ AstPolyMap *pmap2; /* New PolyMap describing the distortion */ double ****item; /* Address of FitsStore item to use */ double *c; /* Pointer to start of coefficient description */ double *coeff_f; /* Array of coeffs. for forward transformation */ double *coeff_i; /* Array of coeffs. for inverse transformation */ double cof; /* Coefficient value */ double lbnd[ 2 ]; /* Lower bounds of fitted region */ double ubnd[ 2 ]; /* Upper bounds of fitted region */ int def; /* Is transformation defined? */ int iin; /* Input (u or v) index */ int iout; /* Output (U or V) index */ int ncoeff_f; /* No. of coeffs. for forward transformation */ int ncoeff_i; /* No. of coeffs. for inverse transformation */ int p; /* Power of u or U */ int pmax; /* Max power of u or U */ int q; /* Power of v or V */ int qmax; /* Max power of v or V */ /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Store coefficients of the forward transformation: ================================================ */ /* Indicate that we have as yet no coefficients for the forward polynomials. */ ncoeff_f = 0; /* Indicate that we do not yet have any evidence that the forward transformation is defined. */ def = 0; /* Allocate workspace to hold descriptions of (initially) 20 coefficients used within the forward polynomials. */ coeff_f = astMalloc( sizeof( double )*20 ); /* Store the coefficients of the polynomial which produces each output axis (U or V) in turn. */ for( iout = 0; iout < 2; iout++ ){ /* Get a pointer to the FitsStore item holding the values defining this output. */ item = ( iout == 0 ) ? &(store->asip) : &(store->bsip); /* Get the largest powers used of u and v. */ pmax = GetMaxI( item, s, status ); qmax = GetMaxJM( item, s, status ); /* Loop round all combination of powers. */ for( p = 0; p <= pmax; p++ ){ for( q = 0; q <= qmax; q++ ){ /* Get the polynomial coefficient for this combination of powers. */ cof = GetItem( item, p, q, s, NULL, method, class, status ); /* If there is no coefficient for this combination of powers, use a value of zero. Otherwise indicate we have found at least one coefficient. */ if( cof == AST__BAD ) { cof = 0.0; } else { def = 1; } /* The distortion polynomial gives a correction to be added on to the input value. On the other hand, the returned Mapping is a direct transformation from input to output. Therefore increment the coefficient value by 1 for the term which corresponds to the current output axis. */ if( p == ( 1 - iout ) && q == iout ) cof += 1.0; /* If the coefficient is not zero, store it in the array of coefficient descriptions. */ if( cof != 0.0 ) { /* Increment the number of coefficients for the forward polynomials. */ ncoeff_f++; /* Ensure the "coeff_f" array is large enough to hold the new coefficient. */ coeff_f = astGrow( coeff_f, sizeof( double )*4, ncoeff_f ); if( astOK ) { /* Store it. Each coefficient is described by 4 values (since we have 2 inputs to the Mapping). The first is the coefficient value, the second is the (1-based) index of the output to which the coefficient relates. The next is the power of input 0, and the last one is the power of input 1. */ c = coeff_f + 4*( ncoeff_f - 1 ); c[ 0 ] = cof; c[ 1 ] = iout + 1; c[ 2 ] = p; c[ 3 ] = q; } } } } } /* If no coefficients were supplied in the FitsStore, the forward transformation is undefined. */ if( !def ) ncoeff_f = 0; /* Store coefficients of the inverse transformation: ================================================ */ /* Indicate that we have as yet no coefficients for the inverse polynomials. */ ncoeff_i = 0; /* Indicate that we do not yet have any evidence that the forward transformation is defined. */ def = 0; /* Allocate workspace to hold descriptions of (initially) 20 coefficients used within the inverse polynomials. */ coeff_i = astMalloc( sizeof( double )*20 ); /* Store the coefficients of the polynomial which produces each input axis (u or v) in turn. */ for( iin = 0; iin < 2; iin++ ){ /* Get a pointer to the FitsStore item holding the values defining this output. */ item = ( iin == 0 ) ? &(store->apsip) : &(store->bpsip); /* Get the largest powers used of U and V. */ pmax = GetMaxI( item, s, status ); qmax = GetMaxJM( item, s, status ); /* Loop round all combination of powers. */ for( p = 0; p <= pmax; p++ ){ for( q = 0; q <= qmax; q++ ){ /* Get the polynomial coefficient for this combination of powers. */ cof = GetItem( item, p, q, s, NULL, method, class, status ); /* If there is no coefficient for this combination of powers, use a value of zero. Otherwise indicate we have found at least one coefficient. */ if( cof == AST__BAD ) { cof = 0.0; } else { def = 1; } /* The distortion polynomial gives a correction to be added on to the output value. On the other hand, the returned Mapping is a direct transformation from output to input. Therefore increment the coefficient value by 1 for the term which corresponds to the current input axis. */ if( p == ( 1 - iin ) && q == iin ) cof += 1.0; /* If the coefficient is not zero, store it in the array of coefficient descriptions. */ if( cof != 0.0 ) { /* Increment the number of coefficients for the inverse polynomials. */ ncoeff_i++; /* Ensure the "coeff_i" array is large enough to hold the new coefficient. */ coeff_i = astGrow( coeff_i, sizeof( double )*4, ncoeff_i ); if( astOK ) { /* Store it. Each coefficient is described by 4 values (since we have 2 outputs to the Mapping). The first is the coefficient value, the second is the (1-based) index of the input to which the coefficient relates. The next is the power of output 0, and the last one is the power of output 1. */ c = coeff_i + 4*( ncoeff_i - 1 ); c[ 0 ] = cof; c[ 1 ] = iin + 1; c[ 2 ] = p; c[ 3 ] = q; } } } } } /* If no coefficients were supplied in the FitsStore, the forward transformation is undefined. */ if( !def ) ncoeff_i = 0; /* Create the returned Mapping: ============================ */ /* If neither transformation is defined, create a UnitMap. */ if( ncoeff_f == 0 && ncoeff_i == 0 ){ ret = (AstMapping *) astUnitMap( naxes, "", status ); /* Otherwise, create a PolyMap to describe axes 0 and 1. */ } else { pmap = astPolyMap( 2, 2, ncoeff_f, coeff_f, ncoeff_i, coeff_i, "", status ); /* The inverse transformations supplied within SIP headers are often inaccurate. So replace any existing inverse by sampling the supplied transformation, and fitting a polynomial to the sampled positions. If the fit fails to reach 0.01 pixel accuracy, forget it and rely on the (slower) iterative inverse provided by the PolyMap class. Do the fit over an area three times the size of the image to provide accurate values outside the image.*/ lbnd[ 0 ] = ( dim[ 0 ] != AST__BAD ) ? -dim[ 0 ] : -1000.0; lbnd[ 1 ] = ( dim[ 1 ] != AST__BAD ) ? -dim[ 1 ] : -1000.0; ubnd[ 0 ] = ( dim[ 0 ] != AST__BAD ) ? 2*dim[ 0 ] : 2000.0; ubnd[ 1 ] = ( dim[ 1 ] != AST__BAD ) ? 2*dim[ 1 ] : 2000.0; pmap2 = astPolyTran( pmap, (ncoeff_f == 0), 0.0001, 0.01, 7, lbnd, ubnd ); if( pmap2 ) { (void) astAnnul( pmap ); pmap = pmap2; } else { astSet( pmap, "IterInverse=1,NiterInverse=6,TolInverse=1.0E-8", status ); } /* Add the above Mapping in parallel with a UnitMap which passes any other axes unchanged. */ ret = AddUnitMaps( (AstMapping *) pmap, 0, naxes, status ); pmap = astAnnul( pmap ); } /* Free resources. */ coeff_f = astFree( coeff_f ); coeff_i = astFree( coeff_i ); /* Return the result. */ return ret; } static void SkyPole( AstWcsMap *map2, AstMapping *map3, int ilon, int ilat, int *wperm, char s, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * SkyPole * Purpose: * Put values for FITS keywords LONPOLE and LATPOLE into a FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void SkyPole( AstWcsMap *map2, AstMapping *map3, int ilon, int ilat, * int *wperm, char s, FitsStore *store, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function calculates values for the LONPOLE and LATPOLE FITS * keywords and stores them in the supplied FitsStore. LONPOLE and * LATPOLE are the longitude and latitude of the celestial north pole * in native spherical coordinates. * Parameters: * map2 * Pointer to the Mapping from Intermediate World Coordinates to Native * Spherical Coordinates. * map3 * Pointer to the Mapping from Native Spherical Coordinates to celestial * coordinates. * ilon * Zero-based index of longitude output from "map3". * ilat * Zero-based index of latitude output from "map3". * wperm * Pointer to an array of integers with one element for each axis of * the current Frame. Each element holds the zero-based * index of the FITS-WCS axis (i.e. the value of "i" in the keyword * names "CTYPEi", "CRVALi", etc) which describes the Frame axis. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * store * The FitsStore in which to store the FITS WCS keyword values. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding intermediate wcs coords */ AstPointSet *pset2; /* PointSet holding final WCS coords */ double **ptr1; /* Pointer to coordinate data */ double **ptr2; /* Pointer to coordinate data */ double alpha0; /* Long. of fiducial point in standard system */ double alphap; /* Celestial longitude of native north pole */ double deflonpole; /* Default value for lonpole */ double delta0; /* Lat. of fiducial point in standard system */ double latpole; /* Native latitude of celestial north pole */ double lonpole; /* Native longitude of celestial north pole */ double phi0; /* Native longitude at fiducial point */ double theta0; /* Native latitude at fiducial point */ int axlat; /* Index of latitude output from "map2" */ int axlon; /* Index of longitude output from "map2" */ int fits_ilat; /* FITS WCS axis index for latitude axis */ int fits_ilon; /* FITS WCS axis index for longitude axis */ int iax; /* Axis index */ int nax; /* Number of IWC axes */ int nax2; /* Number of WCS axes */ /* Check the inherited status. */ if( !astOK ) return; /* Store the indices of the native longitude and latitude outputs of the WcsMap. */ axlon = astGetWcsAxis( map2, 0 ); axlat = astGetWcsAxis( map2, 1 ); /* Store the indices of the FITS WCS axes for longitude and latitude */ fits_ilon = wperm[ ilon ]; fits_ilat = wperm[ ilat ]; /* To find the longitude and latitude of the celestial north pole in native spherical coordinates, we will transform the coords of the celestial north pole into spherical cords using the inverse of "map2", and if the resulting native spherical coords differ from the default values of LONPOLE and LATPOLE, we store them in the FitsStore. However, for zenithal projections, any value can be used simply by introducing an extra rotation into the (X,Y) projection plane. If values have been set in the WcsMap (as projection parameters PVi_3 and PVi_4 for longitude axis "i") uses them. Otherwise, set the values bad to indicate that the default values should be used. Note, these projection parameters are used for other purposes in a TPN projection. */ lonpole = AST__BAD; latpole = AST__BAD; if( astIsZenithal( map2 ) ) { if( astGetWcsType( map2 ) != AST__TPN ) { lonpole = astTestPV( map2, axlon, 3 ) ? astGetPV( map2, axlon, 3 ) : AST__BAD; latpole = astTestPV( map2, axlon, 4 ) ? astGetPV( map2, axlon, 4 ) : AST__BAD; } /* For non-zenithal projections, do the full calculation. */ } else { /* Allocate resources. */ nax = astGetNin( map2 ); pset1 = astPointSet( 1, nax, "", status ); ptr1 = astGetPoints( pset1 ); nax2 = astGetNout( map3 ); pset2 = astPointSet( 1, nax2, "", status ); ptr2 = astGetPoints( pset2 ); if( astOK ) { /* Calculate the longitude and latitude of the celestial north pole in native spherical coordinates (using the inverse of map3). These values correspond to the LONPOLE and LATPOLE keywords. */ for( iax = 0; iax < nax2; iax++ ) ptr2[ iax ][ 0 ] = 0.0; ptr2[ ilat ][ 0 ] = AST__DPIBY2; (void) astTransform( map3, pset2, 0, pset1 ); /* Retrieve the latitude and longitude (in the standard system) of the fiducial point (i.e. CRVAL), in radians. */ delta0 = GetItem( &(store->crval), fits_ilat, 0, s, NULL, method, class, status ); if( delta0 == AST__BAD ) delta0 = 0.0; delta0 *= AST__DD2R; alpha0 = GetItem( &(store->crval), fits_ilon, 0, s, NULL, method, class, status ); if( alpha0 == AST__BAD ) alpha0 = 0.0; alpha0 *= AST__DD2R; /* The default value of the LATPOLE is defined by equation 8 of FITS-WCS paper II (taking the +ve signs). Find this value. */ if( WcsNatPole( NULL, map2, alpha0, delta0, 999.0, ptr1[ axlon ], &alphap, &latpole, status ) ){ /* If the default value is defined, compare it to the latitude of the north pole found above. If they are equal use a bad value instead to prevent an explicit keyword from being added to the FitsChan. */ if( EQUALANG( ptr1[ axlat ][ 0 ], latpole ) ) { latpole = AST__BAD; } else { latpole = ptr1[ axlat ][ 0 ]; } /* If the default value is not defined, always store an explicit LATPOLE value. */ } else { latpole = ptr1[ axlat ][ 0 ]; } /* The default LONPOLE value is zero if the celestial latitude at the fiducial point is greater than or equal to the native latitude at the fiducial point. Otherwise, the default is (+ or -) 180 degrees. If LONPOLE takes the default value, replace it with AST__BAD to prevent an explicit keyword being stored in the FitsChan. */ GetFiducialNSC( map2, &phi0, &theta0, status ); lonpole = palDranrm( ptr1[ axlon ][ 0 ] ); if( delta0 >= theta0 ){ deflonpole = 0.0; } else { deflonpole = AST__DPI; } if( EQUALANG( lonpole, deflonpole ) ) lonpole = AST__BAD; } /* Convert from radians to degrees. */ if( lonpole != AST__BAD ) lonpole *= AST__DR2D; if( latpole != AST__BAD ) latpole *= AST__DR2D; /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); } /* Store these values. */ SetItem( &(store->lonpole), 0, 0, s, lonpole, status ); SetItem( &(store->latpole), 0, 0, s, latpole, status ); /* FITS-WCS paper 2 recommends putting a copy of LONPOLE and LATPOLE in projection parameters 3 and 4 associated with the longitude axis. Only do this if the projection is not TPN (since this projection uses these parameters for other purposes). */ if( astGetWcsType( map2 ) != AST__TPN ) { SetItem( &(store->pv), fits_ilon, 3, s, lonpole, status ); SetItem( &(store->pv), fits_ilon, 4, s, latpole, status ); } } static int SkySys( AstFitsChan *this, AstSkyFrame *skyfrm, int wcstype, int wcsproj, FitsStore *store, int axlon, int axlat, char s, int isoff, const char *method, const char *class, int *status ){ /* * Name: * SkySys * Purpose: * Return FITS-WCS values describing a sky coordinate system. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int SkySys( AstFitsChan *this, AstSkyFrame *skyfrm, int wcstype, * int wcsproj, FitsStore *store, int axlon, int axlat, char s, * int isoff, const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function sets values for the following FITS-WCS keywords * within the supplied FitsStore structure: CTYPE, CNAME, RADESYS, EQUINOX, * MJDOBS, CUNIT, OBSGEO-X/Y/Z. The values are derived from the supplied * SkyFrame and WcsMap. * Parameters: * this * Pointer to the FitsChan. * skyfrm * A pointer to the SkyFrame to be described. * wcstype * The type of WCS: 0 = TAB, 1 = WcsMap projection. * wcsproj * An identifier for the type of WCS projection to use. Should be * one of the values defined by the WcsMap class. Only used if "wcstype" * is 1. * store * A pointer to the FitsStore structure in which to store the * results. * axlon * The index of the FITS WCS longitude axis (i.e. the value of "i" * in "CTYPEi"). * axlat * The index of the FITS WCS latitude axis (i.e. the value of "i" * in "CTYPEi"). * s * Co-ordinate version character. * isoff * If greater than zero, the description to add to the FitsStore * should describe offset coordinates. If less than zero, the * description to add to the FitsStore should describe absolute * coordinates but should include the SkyRefIs, SkyRef and SkyRefP * attributes. If zero, ignore all offset coordinate info. The * absolute value indicates the nature of the reference point: * 1 == "pole", 2 == "origin", otherwise "ignored". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Are the keywords values in the FitsStore usable? */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *label; /* Pointer to axis label string */ char attr[20]; /* Buffer for AST attribute name */ char com[80]; /* Buffer for keyword comment */ char lattype[MXCTYPELEN];/* Latitude axis CTYPE value */ char lontype[MXCTYPELEN];/* Longitude axis CTYPE value */ const char *latsym; /* SkyFrame latitude axis symbol */ const char *lonsym; /* SkyFrame longitude axis symbol */ const char *prj_name; /* Pointer to projection name string */ const char *skyref; /* Formatted SkyRef position */ const char *skyrefis; /* SkyRefIs value */ const char *sys; /* Celestal coordinate system */ const char *timesys; /* Timescale specified in FitsChan */ double ep; /* Epoch of observation in required timescale (MJD) */ double ep_tdb; /* Epoch of observation in TDB timescale (MJD) */ double ep_utc; /* Epoch of observation in UTC timescale (MJD) */ double eq; /* Epoch of reference equinox (MJD) */ double geolat; /* Geodetic latitude of observer (radians) */ double geolon; /* Geodetic longitude of observer (radians) */ double h; /* Geodetic altitude of observer (metres) */ double skyref_lat; /* SkyRef latitude value (rads) */ double skyrefp_lat; /* SkyRefP latitude value (rads) */ double skyref_lon; /* SkyRef longitude value (rads) */ double skyrefp_lon; /* SkyRefP longitude value (rads) */ double xyz[3]; /* Geocentric position vector (in m) */ int defdate; /* Can the date keywords be defaulted? */ int i; /* Character count */ int isys; /* Celestial coordinate system */ int latax; /* Index of latitude axis in SkyFrame */ int lonax; /* Index of longitude axis in SkyFrame */ int ok; /* Do axis symbols conform to FITS-WCS CTYPE form? */ int old_ignore_used; /* Original setting of external ignore_used variable */ int ret; /* Returned flag */ /* Check the status. */ if( !astOK ) return 0; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Check we have a SkyFrame. */ if( !IsASkyFrame( skyfrm ) ) return 0; /* Initialise */ ret = 1; /* Get the equinox, epoch of observation, and system of the SkyFrame. The epoch is in TDB. It is assumed the Equinox is in UTC. */ eq = astGetEquinox( skyfrm ); sys = astGetC( skyfrm, "system" ); ep_tdb = astTestEpoch( skyfrm ) ? astGetEpoch( skyfrm ) : AST__BAD; /* Convert the epoch to UTC. */ ep_utc = TDBConv( ep_tdb, AST__UTC, 1, method, class, status ); /* See if the FitsChan contains a value for the TIMESYS keyword (include previously used cards in the search). If so, and if it is not UTC, convert the epoch to the specified time scale, and store a TIMESYS value in the FitsStore. */ old_ignore_used = ignore_used; ignore_used = 0; if( GetValue( this, "TIMESYS", AST__STRING, (void *) ×ys, 0, 0, method, class, status ) && strcmp( timesys, "UTC" ) ) { ep = TDBConv( ep_tdb, TimeSysToAst( this, timesys, method, class, status ), 1, method, class, status ); SetItemC( &(store->timesys), 0, 0, s, timesys, status ); /* If no TIMESYS keyword was found in the FitsChan, or the timesys was UTC, we use the UTC epoch value found above. In this case no TIMESYS value need be stored in the FitsSTore since UTC is the default for TIMESYS. */ } else { ep = ep_utc; } /* Reinstate the original value for the flag that indicates whether keywords in the FitsChan that have been used previously should be ignored. */ ignore_used = old_ignore_used; /* The MJD-OBS and DATE-OBS keywords default to the epoch of the reference equinox if not supplied. Therefore MJD-OBS and DATE-OBS do not need to be stored in the FitsChan if the epoch of observation is the same as the epoch of the reference equinox. This can avoid producing FITS headers which say unlikely things like DATE-OBS = "01/01/50". Set a flag indicating if MJD-OBS and DATE-OBS can be defaulted. */ defdate = astEQUAL( ep_utc, eq ); /* Convert the equinox to a Julian or Besselian epoch. Also get the reference frame and standard system. */ if( !Ustrcmp( sys, "FK4", status ) ){ eq = palEpb( eq ); isys = RADEC; SetItemC( &(store->radesys), 0, 0, s, "FK4", status ); } else if( !Ustrcmp( sys, "FK4_NO_E", status ) || !Ustrcmp( sys, "FK4-NO-E", status ) ){ eq = palEpb( eq ); isys = RADEC; SetItemC( &(store->radesys), 0, 0, s, "FK4-NO-E", status ); } else if( !Ustrcmp( sys, "FK5", status ) ){ eq = palEpj( eq ); isys = RADEC; SetItemC( &(store->radesys), 0, 0, s, "FK5", status ); } else if( !Ustrcmp( sys, "ICRS", status ) ){ eq = AST__BAD; isys = RADEC; SetItemC( &(store->radesys), 0, 0, s, "ICRS", status ); } else if( !Ustrcmp( sys, "GAPPT", status ) || !Ustrcmp( sys, "Apparent", status ) || !Ustrcmp( sys, "Geocentric", status ) ){ eq = AST__BAD; isys = RADEC; SetItemC( &(store->radesys), 0, 0, s, "GAPPT", status ); } else if( !Ustrcmp( sys, "Helioecliptic", status ) ){ eq = AST__BAD; isys = HECLIP; } else if( !Ustrcmp( sys, "Galactic", status ) ){ eq = AST__BAD; isys = GALAC; } else if( !Ustrcmp( sys, "Supergalactic", status ) ){ eq = AST__BAD; isys = SUPER; } else if( !Ustrcmp( sys, "AzEl", status ) ){ eq = AST__BAD; isys = AZEL; } else { eq = AST__BAD; isys = NOCEL; } /* Store these values. Only store the date if it does not take its default value. */ SetItem( &(store->equinox), 0, 0, s, eq, status ); if( !defdate ) SetItem( &(store->mjdobs), 0, 0, ' ', ep, status ); /* Only proceed if we have usable values */ if( astOK ) { /* Get the indices of the latitude and longitude axes within the SkyFrame. */ latax = astGetLatAxis( skyfrm ); lonax = 1 - latax; /* The first 4 characters in CTYPE are determined by the celestial coordinate system and the second 4 by the projection type. If we are describing offset coordinates, then use "OFLN" and "OFLT. Otherwise use the standard FITS-WCS name of the system. */ if( isoff > 0 ){ strcpy( lontype, "OFLN" ); strcpy( lattype, "OFLT" ); } else if( isys == RADEC ){ strcpy( lontype, "RA--" ); strcpy( lattype, "DEC-" ); } else if( isys == ECLIP ){ strcpy( lontype, "ELON" ); strcpy( lattype, "ELAT" ); } else if( isys == HECLIP ){ strcpy( lontype, "HLON" ); strcpy( lattype, "HLAT" ); } else if( isys == GALAC ){ strcpy( lontype, "GLON" ); strcpy( lattype, "GLAT" ); } else if( isys == SUPER ){ strcpy( lontype, "SLON" ); strcpy( lattype, "SLAT" ); } else if( isys == AZEL ){ strcpy( lontype, "AZ--" ); strcpy( lattype, "EL--" ); /* For unknown systems, use the axis symbols within CTYPE if they conform to the requirement of FITS-WCS (i.e. "xxLN/xxLT" or "xLON/xLAT") or use "UNLN/UNLT" otherwise. */ } else { latsym = astGetSymbol( skyfrm, latax ); lonsym = astGetSymbol( skyfrm, lonax ); if( astOK ) { ok = 0; if( strlen( latsym ) == 4 && strlen( lonsym ) == 4 ) { if( !strcmp( latsym + 2, "LT" ) && !strcmp( lonsym + 2, "LN" ) && !strncmp( latsym, lonsym, 2 ) ) { ok = 1; } else if( !strcmp( latsym + 1, "LAT" ) && !strcmp( lonsym + 1, "LON" ) && !strncmp( latsym, lonsym, 1 ) ) { ok = 1; } } if( !ok ) { latsym = "UNLT"; lonsym = "UNLN"; } strncpy( lontype, lonsym, 4 ); for( i = strlen( lonsym ); i < 4; i++ ) { lontype[ i ] = '-'; } strncpy( lattype, latsym, 4 ); for( i = strlen( latsym ); i < 4; i++ ) { lattype[ i ] = '-'; } } } /* Store the projection strings. */ prj_name = ( wcstype == 0 ) ? "-TAB" : astWcsPrjName( wcsproj ); if( astOK ) { strcpy( lontype + 4, prj_name ); strcpy( lattype + 4, prj_name ); } /* Store the total CTYPE strings */ SetItemC( &(store->ctype), axlon, 0, s, lontype, status ); SetItemC( &(store->ctype), axlat, 0, s, lattype, status ); /* Store offset coord information. */ if( isoff ) { /* If the description is for offset coords store suitable comments for the CTYPE keywords. */ if( isoff > 0 ) { skyref = astGetC( skyfrm, "SkyRef" ); sprintf( attr, "Symbol(%d)", axlon + 1 ); sprintf( com, "%s offset from %s",astGetC( skyfrm, attr )+1, skyref ); SetItemC( &(store->ctype_com), axlon, 0, s, com, status ); sprintf( attr, "Symbol(%d)", axlat + 1 ); sprintf( com, "%s offset from %s",astGetC( skyfrm, attr )+1, skyref ); SetItemC( &(store->ctype_com), axlat, 0, s, com, status ); /* If the description is for absolute coords store the SkyFrame attribute values in AST-specific keywords. */ } else { sprintf( attr, "SkyRef(%d)", axlon + 1 ); skyref_lon = astGetD( skyfrm, attr ); sprintf( attr, "SkyRef(%d)", axlat + 1 ); skyref_lat = astGetD( skyfrm, attr ); sprintf( attr, "SkyRefP(%d)", axlon + 1 ); skyrefp_lon = astGetD( skyfrm, attr ); sprintf( attr, "SkyRefP(%d)", axlat + 1 ); skyrefp_lat = astGetD( skyfrm, attr ); skyrefis = (isoff < -2) ? "IGNORED" : ( (isoff < -1) ? "ORIGIN" : "POLE" ); SetItemC( &(store->skyrefis), 0, 0, s, skyrefis, status ); if( astTest( skyfrm, "SkyRef(1)" ) ) { SetItem( &(store->skyref), axlon, 0, s, skyref_lon, status ); SetItem( &(store->skyref), axlat, 0, s, skyref_lat, status ); } if( astTest( skyfrm, "SkyRefP(1)" ) ) { SetItem( &(store->skyrefp), axlon, 0, s, skyrefp_lon, status ); SetItem( &(store->skyrefp), axlat, 0, s, skyrefp_lat, status ); } } } /* If the Label attribute has been set for an axis, use it as the CTYPE comment and CNAME value. */ if( astTestLabel( skyfrm, latax ) ) { label = (char *) astGetLabel( skyfrm, latax ); SetItemC( &(store->ctype_com), axlat, 0, s, label, status ); SetItemC( &(store->cname), axlat, 0, s, label, status ); } if( astTestLabel( skyfrm, lonax ) ) { label = (char *) astGetLabel( skyfrm, lonax ); SetItemC( &(store->ctype_com), axlon, 0, s, label, status ); SetItemC( &(store->cname), axlon, 0, s, label, status ); } /* Nullify any CUNITS strings for the longitude and latitude axes (they always take the default value of degrees). */ SetItemC( &(store->cunit), axlat, 0, s, NULL, status ); SetItemC( &(store->cunit), axlon, 0, s, NULL, status ); } /* Store the Domain name as the WCSNAME keyword (if set). */ if( astTestDomain( skyfrm ) ) { SetItemC( &(store->wcsname), 0, 0, s, (char *) astGetDomain( skyfrm ), status ); } /* Store the observer's position if set (needed for definition of AzEl systems). */ if( astTestObsLon( skyfrm ) && astTestObsLat( skyfrm ) && s == ' ' ) { geolon = astGetObsLon( skyfrm ); geolat = astGetObsLat( skyfrm ); h = astGetObsAlt( skyfrm ); if( geolat != AST__BAD && geolon != AST__BAD && h != AST__BAD ) { eraGd2gc( 1, geolon, geolat, h, xyz ); SetItem( &(store->obsgeox), 0, 0, ' ', xyz[0], status ); SetItem( &(store->obsgeoy), 0, 0, ' ', xyz[1], status ); SetItem( &(store->obsgeoz), 0, 0, ' ', xyz[2], status ); } } if( !astOK ) ret = 0; return ret; } static char *SourceWrap( const char *(* source)( void ), int *status ) { /* * Name: * SourceWrap * Purpose: * Wrapper function to invoke a C FitsChan source function. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *SourceWrap( const char *, int *status(* source)( void ) ) * Class Membership: * FitsChan member function. * Description: * This function invokes the source function whose pointer is * supplied in order to read the next input line from an external * data store. It then returns a pointer to a dynamic string * containing a copy of the text that was read. * Parameters: * source * Pointer to a source function, with no parameters, that * returns a pointer to a const, null-terminated string * containing the text that it read. This is the form of FitsChan * source function employed by the C language interface to the * AST library. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated, null terminated string * containing a copy of the text that was read. This string must be * freed by the caller (using astFree) when no longer required. * * A NULL pointer will be returned if there is no more input text * to read. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ char *result; /* Pointer value to return */ const char *line; /* Pointer to input line */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the source function to read the next input line and return a pointer to the resulting string. */ line = ( *source )(); /* If a string was obtained, make a dynamic copy of it and save the resulting pointer. */ if ( line ) result = astString( line, (int) strlen( line ) ); /* Return the result. */ return result; } static AstMapping *SpectralAxes( AstFitsChan *this, AstFrameSet *fs, double *dim, int *wperm, char s, FitsStore *store, double *crvals, int *axis_done, const char *method, const char *class, int *status ){ /* * Name: * SpectralAxes * Purpose: * Add values to a FitsStore describing spectral axes in a Frame. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *SpectralAxes( AstFitsChan *this, AstFrameSet *fs, * double *dim, int *wperm, * char s, FitsStore *store, double *crvals, * int *axis_done, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The current Frame of the supplied FrameSet is searched for spectral * axes. If any are found, FITS WCS keyword values describing the axis * are added to the supplied FitsStore, if possible (the conventions * of FITS-WCS paper III are used). Note, this function does not store * values for keywords which define the transformation from pixel * coords to Intermediate World Coords (CRPIX, PC and CDELT), but a * Mapping is returned which embodies these values. This Mapping is * from the current Frame in the FrameSet (WCS coords) to a Frame * representing IWC. The IWC Frame has the same number of axes as the * WCS Frame which may be greater than the number of base Frame (i.e. * pixel) axes. * * If a spectral axis is found, the RafRA and RefDec attributes of the * SpecFrame describing the axis are ignored: it is assumed that the * WCS Frame also contains a pair of celestial axes which will result * in appropriate celestial reference values being stored in the * FitsStore (this asumption should be enforced by calling function * MakeFitsFrameSet prior to calling this function). * Parameters: * this * Pointer to the FitsChan. * fs * Pointer to the FrameSet. The base Frame should represent FITS pixel * coordinates, and the current Frame should represent FITS WCS * coordinates. The number of base Frame axes should not exceed the * number of current Frame axes. The spectral Unit in the returned * FrameSet will always be linearly related to the default Units for * the spectral System in use by the axis. If this requires a * change to the existing spectral Unit, the integrity of the * FrameSet will be maintained by suitable adjustments to the Mappings * within the FrameSet. * dim * An array holding the image dimensions in pixels. AST__BAD can be * supplied for any unknwon dimensions. * wperm * Pointer to an array of integers with one element for each axis of * the current Frame. Each element holds the zero-based * index of the FITS-WCS axis (i.e. one les than the value of "i" in * the keyword names "CTYPEi", "CRVALi", etc) which describes the * Frame axis. * s * The co-ordinate version character. A space means the primary * axis descriptions. Otherwise the supplied character should be * an upper case alphabetical character ('A' to 'Z'). * store * The FitsStore in which to store the FITS WCS keyword values. * crvals * Pointer to an array holding the default CRVAL value for each * axis in the WCS Frame. * axis_done * An array of flags, one for each Frame axis, which indicate if a * description of the corresponding axis has yet been stored in the * FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * If a spectral axis was found which can be described using the * conventions of FITS-WCS paper III, then a Mapping from the current Frame * of the supplied FrameSet, to the IWC Frame is returned. Otherwise, * a UnitMap is returned. Note, the Mapping only defines the IWC * transformation for spectral axes. Any non-spectral axes are passed * unchanged by the returned Mapping. */ /* Local Variables: */ AstFitsTable *table; /* Pointer to structure holding -TAB table info */ AstFrame *pframe; /* Primary Frame containing current WCS axis*/ AstFrame *tfrm1; /* A temporary Frame */ AstFrame *tfrm; /* A temporary Frame */ AstFrame *wcsfrm; /* WCS Frame within FrameSet */ AstFrameSet *tfs; /* A temporary FrameSet */ AstGrismMap *gmap; /* GrismMap defining the spectral axis */ AstMapping *axmap; /* Mapping from WCS to IWC */ AstMapping *map; /* Pixel -> WCS mapping */ AstMapping *ret; /* Returned Mapping */ AstMapping *tmap0; /* A temporary Mapping */ AstMapping *tmap1; /* A temporary Mapping */ AstMapping *tmap2; /* A temporary Mapping */ AstMapping *tmap3; /* A temporary Mapping */ AstMapping *tmap4; /* A temporary Mapping */ AstMapping *tmap5; /* A temporary Mapping */ AstMapping *tmap6; /* A temporary Mapping */ AstPermMap *pm; /* PermMap pointer */ AstSpecFrame *specfrm; /* The SpecFrame defining current WCS axis */ char *cname; /* Pointer to CNAME value */ char ctype[ MXCTYPELEN ]; /* The value for the FITS CTYPE keyword */ char lin_unit[ 20 ]; /* Linear spectral Units being used */ char orig_system[ 40 ]; /* Value of System attribute for current WCS axis */ char system_attr[ 10 ]; /* Name of System attribute for current WCS axis */ char unit_attr[ 10 ]; /* Name of Unit attribute for current WCS axis */ const char *cval; /* Pointer to temporary character string */ const char *x_sys[ 4 ]; /* Basic spectral systems */ double *lbnd_p; /* Pointer to array of lower pixel bounds */ double *ubnd_p; /* Pointer to array of upper pixel bounds */ double crval; /* The value for the FITS CRVAL keyword */ double dgbyds; /* Rate of change of grism parameter wrt "S" at ref. point */ double dsbydx; /* Rate of change of "S" wrt "X" at ref. point */ double geolat; /* Geodetic latitude of observer (radians) */ double geolon; /* Geodetic longitude of observer (radians) */ double gval; /* Value of grism parameter at reference point */ double h; /* Geodetic altitude of observer (metres) */ double imagfreq; /* Image sideband equivalent to the rest frequency (Hz) */ double lbnd_s; /* Lower bound on spectral axis */ double pv; /* Value of projection parameter */ double restfreq; /* Rest frequency (Hz) */ double ubnd_s; /* Upper bound on spectral axis */ double vsource; /* Rel.vel. of source (m/s) */ double xval; /* Value of "X" system at reference point */ double xyz[3]; /* Geocentric position vector (in m) */ double zsource; /* Redshift of source */ int *inperm; /* Pointer to permutation array for input axes */ int *outperm; /* Pointer to permutation array for output axes */ int extver; /* Table version number for -TAB headers */ int fits_i; /* FITS WCS axis index for current WCS axis */ int iax; /* Axis index */ int icolindex; /* Index of table column holding index vector */ int icolmain; /* Index of table column holding main coord array */ int interp; /* INterpolation method for look-up tables */ int ix; /* System index */ int j; /* Loop count */ int npix; /* Number of pixel axes */ int nwcs; /* Number of WCS axes */ int paxis; /* Axis index within primary Frame */ int sourcevrf; /* Rest Frame in which SourceVel is accesed */ /* Initialise */ ret = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* Every supported spectral system is linearly related to one of the following four systems. */ x_sys[ 0 ] = "FREQ"; x_sys[ 1 ] = "WAVE"; x_sys[ 2 ] = "AWAV"; x_sys[ 3 ] = "VELO"; /* Get a pointer to the WCS Frame. */ wcsfrm = astGetFrame( fs, AST__CURRENT ); /* Store the number of pixel and WCS axes. */ npix = astGetNin( fs ); nwcs = astGetNout( fs ); /* Store the upper and lower pixel bounds. */ lbnd_p = astMalloc( sizeof( double )*(size_t) npix ); ubnd_p = astMalloc( sizeof( double )*(size_t) npix ); if( astOK ) { for( iax = 0; iax < npix; iax++ ) { lbnd_p[ iax ] = 1.0; ubnd_p[ iax ] = ( dim[ iax ] != AST__BAD ) ? dim[ iax ] : 500; } } /* Check each axis in the WCS Frame to see if it is a spectral axis. */ axmap = NULL; for( iax = 0; iax < nwcs; iax++ ) { /* Obtain a pointer to the primary Frame containing the current WCS axis. */ astPrimaryFrame( wcsfrm, iax, &pframe, &paxis ); /* If the current axis belongs to a SpecFrame, we have found a spectral axis. */ if( astIsASpecFrame( pframe ) ) { specfrm = (AstSpecFrame *) pframe; /* Note the (zero-based) FITS WCS axis index to be used for the current Frame axis. */ fits_i = wperm[ iax ]; /* Note the name and original value of the System attribute for the spectral axis within the FrameSet current Frame. */ sprintf( system_attr, "System(%d)", iax + 1 ); cval = astGetC( wcsfrm, system_attr ); if( cval ) strcpy( orig_system, cval ); /* Note the name of the Unit attribute for the spectral axis within the FrameSet current Frame. */ sprintf( unit_attr, "Unit(%d)", iax + 1 ); /* Get a pointer to the Mapping from FITS pixel coordinates to SpecFrame. */ map = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Find the bounds of the Spectral axis over the volume of the pixel grid. */ astMapBox( map, lbnd_p, ubnd_p, 1, iax, &lbnd_s, &ubnd_s, NULL, NULL ); /* The Unit attribute of a SpecFrame can be set to arbitrary non-linear functions of standard linear spectral units. FITS-WCS paper III requires CRVAL etc to be given in linear units. So first we ensure that we have a SpecFrame with linear Units. Create a copy of the SpecFrame and clear its Unit attribute (this ensures the copy has the default linear units). Then find a Mapping from the original spectral units to the default linear units. If the conversion is possible, see if the Mapping between the units is linear. If it is, then the original Unit attribute of the SpecFrame is OK (i.e. the units are linear). If not, clear the Unit attribute of the spectral axis in the FrameSet so that it uses the default linear units (retaining the original value so that it can be re-instated later). Using the clear method on the FrameSet pointer rather than the SpecFrame pointer causes the SpecFrame to be re-mapped within the FrameSet to maintain its correct relationship with the other Frames in the FrameSet. Also update the pixel->spectrum Mapping to take account of the change in units and re-calculate the new bounds on the spectral axis. Also update any supplied CRVAL value for the spectral axis. */ tfrm = astCopy( specfrm ); astClearUnit( tfrm, 0 ); tfs = astConvert( specfrm, tfrm, "" ); tfrm = astAnnul( tfrm ); if( tfs ) { crval = crvals ? crvals[ iax ] : AST__BAD; tmap1 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); tfs = astAnnul( tfs ); if( !IsMapLinear( tmap1, &lbnd_s, &ubnd_s, 0, status ) ) { astClear( fs, unit_attr ); (void) astAnnul( map ); map = astGetMapping( fs, AST__BASE, AST__CURRENT ); astMapBox( map, lbnd_p, ubnd_p, 1, iax, &lbnd_s, &ubnd_s, NULL, NULL ); astTran1( tmap1, 1, &crval, 1, &crval ); } tmap1 = astAnnul( tmap1 ); /* Note the linear spectral Unit currently in use. */ cval = astGetUnit( specfrm, 0 ); if( cval ) strcpy( lin_unit, cval ); /* For some of the algorithms, the reference value CRVAL is arbitrary. For these algorithms we choose to use the supplied default CRVAL value. If no default CRVAL value was suppllied, we use the mid spectral value if the size of the spectral axis was given, or the lower bound (i.e. pixel 1) if the size of the spectral axis was not given. */ if( crval == AST__BAD ) { if( dim[ iax ] != AST__BAD ) { crval = 0.5*( lbnd_s + ubnd_s ); } else { crval = lbnd_s; } } /* Modify this crval value so that it correpsonds to an integer pixel coordinate. */ crval = NearestPix( map, crval, iax, status ); /* We now check to see if the Mapping from pixel coords -> linear spectral coords corresponds to one of the algorithms supported in FITS-WCS paper III. First check for the "linear" algorithm in which the linear spectral coordinate given by the SpecFrame is related linearly to the pixel coords. */ ctype[ 0 ] = 0; if( IsMapLinear( map, lbnd_p, ubnd_p, iax, status ) ) { /* The CTYPE value is just the spectral system. */ strcpy( ctype, orig_system ); /* Create the Mapping which defines the spectral IWC axis. This is initially the Mapping from WCS to IWCS - it subtracts the CRVAL value from the spectral WCS value to get the spectral IWC value (other non-spectral axes are left unchanged by this Mapping). This results in the spectral IWC axis having the same axis index as the spectral WCS axis. */ crval = -crval; tmap0 = (AstMapping *) astShiftMap( 1, &crval, "", status ); crval = -crval; axmap = AddUnitMaps( tmap0, iax, nwcs, status ); tmap0 = astAnnul( tmap0 ); } /* If the "linear" algorithm above is inappropriate, see if the "non-linear" algorithm defined in FITS-WCS paper III can be used, in which pixel coords are linearly related to some spectral system (called "X") other than the one represented by the supplied SpecFrame (called "S"). */ if( !ctype[ 0 ] ) { /* Loop round each of the 4 allowed X systems. All other spectral systems are linearly related to one of these 4 systems and so do not need to be tested. */ for( ix = 0; ix < 4 && !ctype[ 0 ]; ix++ ) { /* Set the system of the spectral WCS axis to the new trial X system. Clear the Unit attribute to ensure we are using the default linear units. Using the FrameSet pointer "fs" ensures that the Mappings within the FrameSet are modified to maintain the correct inter-Frame relationships. */ astSetC( fs, system_attr, x_sys[ ix ] ); astClear( fs, unit_attr ); /* Now we check to see if the current X system is linearly related to pixel coordinates. */ tmap3 = astGetMapping( fs, AST__BASE, AST__CURRENT ); if( IsMapLinear( tmap3, lbnd_p, ubnd_p, iax, status ) ) { /* CTYPE: First 4 characters specify the "S" system. */ strcpy( ctype, orig_system ); /* The non-linear algorithm code to be appended to the "S" system is of the form "-X2P" ("P" is the system which is linearly related to "S"). */ if( !strcmp( x_sys[ ix ], "FREQ" ) ) { strcpy( ctype + 4, "-F2" ); } else if( !strcmp( x_sys[ ix ], "WAVE" ) ) { strcpy( ctype + 4, "-W2" ); } else if( !strcmp( x_sys[ ix ], "AWAV" ) ) { strcpy( ctype + 4, "-A2" ); } else { strcpy( ctype + 4, "-V2" ); } if( !strcmp( orig_system, "FREQ" ) || !strcmp( orig_system, "ENER" ) || !strcmp( orig_system, "WAVN" ) || !strcmp( orig_system, "VRAD" ) ) { strcpy( ctype + 7, "F" ); } else if( !strcmp( orig_system, "WAVE" ) || !strcmp( orig_system, "VOPT" ) || !strcmp( orig_system, "ZOPT" ) ) { strcpy( ctype + 7, "W" ); } else if( !strcmp( orig_system, "AWAV" ) ) { strcpy( ctype + 7, "A" ); } else { strcpy( ctype + 7, "V" ); } /* Create a Mapping which gives S as a function of X. */ tfrm = astCopy( specfrm ); astSetC( tfrm, "System(1)", orig_system ); astSetC( tfrm, "Unit(1)", lin_unit ); tfs = astConvert( specfrm, tfrm, "" ); tmap5 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); tfs = astAnnul( tfs ); tfrm = astAnnul( tfrm ); /* Use the inverse of this Mapping to get the X value at the reference S value. */ astTran1( tmap5, 1, &crval, 0, &xval ); /* Also use it to get the rate of change of S with respect to X at the reference point. */ dsbydx = astRate( tmap5, &xval, 0, 0 ); /* Create the Mapping which defines the spectral IWC axis. This is the Mapping from WCS to IWC - it first converts from S to X, then subtracts the X reference value value, and then scales the axis to ensure that the rate of change of S with respect to IWC is unity (as required by FITS-WCS paper III). Other non-spectral axes are left unchanged by the Mapping. The spectral IWC axis has the same axis index as the spectral WCS axis. */ xval = -xval; tmap2 = (AstMapping *) astShiftMap( 1, &xval, "", status ); astInvert( tmap5 ); tmap0 = (AstMapping *) astCmpMap( tmap5, tmap2, 1, "", status ); tmap5 = astAnnul( tmap5 ); tmap2 = astAnnul( tmap2 ); tmap2 = (AstMapping *) astZoomMap( 1, dsbydx, "", status ); tmap1 = (AstMapping *) astCmpMap( tmap0, tmap2, 1, "", status ); tmap0 = astAnnul( tmap0 ); tmap2 = astAnnul( tmap2 ); axmap = AddUnitMaps( tmap1, iax, nwcs, status ); tmap1 = astAnnul( tmap1 ); } tmap3 = astAnnul( tmap3 ); /* Re-instate the original system and unit attributes for the spectral axis. */ astSetC( fs, system_attr, orig_system ); astSetC( fs, unit_attr, lin_unit ); } } /* If the "non-linear" algorithm above is inappropriate, see if the "log-linear" algorithm defined in FITS-WCS paper III can be used, in which the spectral axis is logarithmically spaced in the spectral system given by the SpecFrame. */ if( !ctype[ 0 ] ) { /* If the "log-linear" algorithm is appropriate, the supplied SpecFrame (s) is related to pixel coordinate (p) by s = Sr.EXP( a*p - b ). If this is the case, then the log of s will be linearly related to pixel coordinates. Test this. If the test is passed a Mapping is returned from WCS to IWC. */ axmap = LogAxis( map, iax, nwcs, lbnd_p, ubnd_p, crval, status ); /* If the axis is logarithmic... */ if( axmap ) { /* CTYPE: First 4 characters specify the "S" system. */ strcpy( ctype, orig_system ); /* The rest is "-LOG". */ strcpy( ctype + 4, "-LOG" ); } } /* If the "log-linear" algorithm above is inappropriate, see if the "grism" algorithm defined in FITS-WCS paper III can be used, in which pixel coords are related to wavelength using a grism dispersion function, implemented in AST by a GrismMap. GrismMaps produce either vacuum wavelength or air wavelength as output. Temporarily set the SpecFrame to these two systems in turn before we do the check for a GrismMap. */ for( ix = 0; ix < 2 && !ctype[ 0 ]; ix++ ) { astSetC( fs, system_attr, ( ix == 0 ) ? "WAVE" : "AWAV" ); astSetC( fs, unit_attr, "m" ); /* Get the simplified Mapping from pixel to wavelength. If the Mapping is a CmpMap containing a GrismMap, and if the output of the GrismMap is scaled by a neighbouring ZoomMap (e.g. into different wavelength units), then the GrismMap will be modified to incorporate the effect of the ZoomMap, and the ZoomMap will be removed. */ tmap2 = astGetMapping( fs, AST__BASE, AST__CURRENT ); tmap1 = astSimplify( tmap2 ); tmap2 = astAnnul( tmap2 ); /* Analyse this Mapping to see if the iax'th output is created diretcly by a GrismMap (i.e. the output of theGrismMap must not subsequently be modified by some other Mapping). If so, ExtractGrismMap returns a pointer to the GrismMap as its function value, and also returns "tmap2" as a copy of tmap1 in which the GrismMap has been replaced by a UnitMap. */ gmap = ExtractGrismMap( tmap1, iax, &tmap2, status ); if( gmap ) { /* The Mapping without the GrismMap must be linear on the spectral axis. */ if( IsMapLinear( tmap2, lbnd_p, ubnd_p, iax, status ) ) { /* Get the reference wavelength (in "m") stored in the GrismMap. */ crval = astGetGrismWaveR( gmap ); /* Save a copy of the current Wavelength (in "m") SpecFrame. */ tfrm1 = astCopy( specfrm ); /* Re-instate the original System and Unit attributes for the SpecFrame. */ astSetC( fs, system_attr, orig_system ); astSetC( fs, unit_attr, lin_unit ); /* Find the Mapping from the original "S" system to wavelength (in "m"). */ tfs = astConvert( specfrm, tfrm1, "" ); tfrm1 = astAnnul( tfrm1 ); if( tfs ) { tmap3 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); tfs = astAnnul( tfs ); /* Use the inverse of this Mapping to convert the reference value from wavelength to the "S" system. */ astTran1( tmap3, 1, &crval, 0, &crval ); /* Concatenate the "S"->wavelength Mapping with the inverse GrismMap (from wavelength to grism parameter), to get the "S" -> "grism parameter" Mapping. */ astInvert( gmap ); tmap4 = (AstMapping *) astCmpMap( tmap3, gmap, 1, "", status ); tmap3 = astAnnul( tmap3 ); /* Use this Mapping to find the grism parameter at the reference point. */ astTran1( tmap4, 1, &crval, 1, &gval ); /* Also use it to find the rate of change of grism parameter with respect to "S" at the reference point. */ dgbyds = astRate( tmap4, &crval, 0, 0 ); /* FITS-WCS paper III required ds/dw to be unity at the reference point. Therefore the rate of change of grism parameter with respect to IWC ("w") is equal to the rate of change of grism parameter with respect to "S" (at the reference point). The mapping from "w" to grism parameter is a ZoomMap which scales "w" by "dgbyds" followed by a ShiftMap which adds on "gval". */ tmap5 = (AstMapping *) astZoomMap( 1, dgbyds, "", status ); tmap6 = (AstMapping *) astShiftMap( 1, &gval, "", status ); tmap3 = (AstMapping *) astCmpMap( tmap5, tmap6, 1, "", status ); tmap5 = astAnnul( tmap5 ); tmap6 = astAnnul( tmap6 ); /* Create the Mapping which defines the spectral IWC axis. This is the Mapping from WCS "S" to IWCS "w", formed by combining the Mapping from "S" to grism parameter (tmap4), with the Mapping from grism parameter to "w" (inverse of tmap3). Other non-spectral axes are left unchanged by the Mapping. The spectral IWC axis has the same axis index as the spectral WCS axis. */ astInvert( tmap3 ); tmap5 = (AstMapping *) astCmpMap( tmap4, tmap3, 1, "", status ); tmap3 = astAnnul( tmap3 ); tmap4 = astAnnul( tmap4 ); axmap = AddUnitMaps( tmap5, iax, nwcs, status ); tmap5 = astAnnul( tmap5 ); /* CTYPE: First 4 characters specify the "S" system. */ strcpy( ctype, orig_system ); /* Last 4 characters are "-GRA" or "-GRI". */ strcpy( ctype + 4, ( ix == 0 ) ? "-GRI" : "-GRA" ); /* Store values for the projection parameters in the FitsStore. Ignore parameters which are set to the default values defined in FITS-WCS paper III. */ pv = astGetGrismG( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 0, s, pv, status ); pv = (double) astGetGrismM( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 1, s, pv, status ); pv = astGetGrismAlpha( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 2, s, pv*AST__DR2D, status ); pv = astGetGrismNR( gmap ); if( pv != 1.0 ) SetItem( &(store->pv), fits_i, 3, s, pv, status ); pv = astGetGrismNRP( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 4, s, pv, status ); pv = astGetGrismEps( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 5, s, pv*AST__DR2D, status ); pv = astGetGrismTheta( gmap ); if( pv != 0 ) SetItem( &(store->pv), fits_i, 6, s, pv*AST__DR2D, status ); } } /* Release resources. */ tmap2 = astAnnul( tmap2 ); gmap = astAnnul( gmap ); } /* Release resources. */ tmap1 = astAnnul( tmap1 ); /* Re-instate the original System and Unit attributes for the SpecFrame. */ astSetC( fs, system_attr, orig_system ); astSetC( fs, unit_attr, lin_unit ); } /* If none of the above algorithms are appropriate, we must resort to using the -TAB algorithm, in which the Mapping is defined by a look-up table. Check the TabOK attribute to see -TAB is to be supported. */ extver = astGetTabOK( this ); if( !ctype[ 0 ] && extver > 0 ) { /* Get any pre-existing FitsTable from the FitsStore. This is the table in which the tabular data will be stored (if the Mapping can be expressed in -TAB form). */ if( !astMapGet0A( store->tables, AST_TABEXTNAME, &table ) ) table = NULL; /* See if the Mapping can be expressed in -TAB form. */ tmap0 = IsMapTab1D( map, 1.0, NULL, wcsfrm, dim, iax, fits_i, &table, &icolmain, &icolindex, &interp, status ); if( tmap0 ) { /* CTYPE: First 4 characters specify the "S" system. Last 4 characters are "-TAB". */ strcpy( ctype, orig_system ); strcpy( ctype + 4, "-TAB" ); /* The values stored in the table index vector are GRID coords. So we need to ensure that IWC are equivalent to GRID coords. So set CRVAL to zero. First store the original CRVAL value (which gives the observation centre) in AXREF. */ SetItem( &(store->axref), fits_i, 0, s, crval, status ); crval = 0.0; /* Store TAB-specific values in the FitsStore. First the name of the FITS binary table extension holding the coordinate info. */ SetItemC( &(store->ps), fits_i, 0, s, AST_TABEXTNAME, status ); /* Next the table version number. This is the set (positive) value for the TabOK attribute. */ SetItem( &(store->pv), fits_i, 1, s, extver, status ); /* Also store the table version in the binary table header. */ astSetFitsI( table->header, "EXTVER", extver, "Table version number", 0 ); /* Next the name of the table column containing the main coords array. */ SetItemC( &(store->ps), fits_i, 1, s, astColumnName( table, icolmain ), status ); /* Next the name of the column containing the index array */ if( icolindex >= 0 ) SetItemC( &(store->ps), fits_i, 2, s, astColumnName( table, icolindex ), status ); /* The interpolation method (an AST extension to the published -TAB algorithm, communicated through the QVi_4a keyword). */ SetItem( &(store->pv), fits_i, 4, s, interp, status ); /* Also store the FitsTable itself in the FitsStore. */ astMapPut0A( store->tables, AST_TABEXTNAME, table, NULL ); /* Create the WCS -> IWC Mapping (AST uses grid coords as IWC coords for the -TAB algorithm). First, get a Mapping that combines the TAB axis Mapping( tmap0) in parallel with one or two UnitMaps in order to put the TAB axis at the required index. */ tmap1 = AddUnitMaps( tmap0, iax, nwcs, status ); /* Now get a PermMap that permutes the WCS axes into the FITS axis order. */ inperm = astMalloc( sizeof( double )*nwcs ); outperm = astMalloc( sizeof( double )*nwcs ); if( astOK ) { for( j = 0; j < nwcs; j++ ) { inperm[ j ] = wperm[ j ]; outperm[ wperm[ j ] ] = j; } } pm = astPermMap( nwcs, inperm, nwcs, outperm, NULL, "", status ); /* Combine these two Mappings in series, to get the Mapping from WCS to IWC. */ axmap = (AstMapping *) astCmpMap( pm, tmap1, 1, " ", status ); /* Free resources. */ inperm = astFree( inperm ); outperm = astFree( outperm ); pm = astAnnul( pm ); tmap0 = astAnnul( tmap0 ); tmap1 = astAnnul( tmap1 ); } if( table ) table = astAnnul( table ); } /* If this axis is a usable spectral axis... */ if( ctype[ 0 ] ) { /* Add the Mapping for this axis in series with any existing result Mapping. */ if( ret ) { tmap0 = (AstMapping *) astCmpMap( ret, axmap, 1, "", status ); (void) astAnnul( ret ); ret = tmap0; } else { ret = astClone( axmap ); } axmap = astAnnul( axmap ); /* Store values for CTYPE, CRVAL and CUNIT in the FitsStore. */ SetItemC( &(store->ctype), fits_i, 0, s, ctype, status ); SetItem( &(store->crval), fits_i, 0, s, crval, status ); SetItemC( &(store->cunit), fits_i, 0, s, lin_unit, status ); /* If the axis label has been set, use it as the CTYPE comment and CNAME value. */ if( astTestLabel( specfrm, 0 ) ) { cname = (char *) astGetLabel( specfrm, 0 ); SetItemC( &(store->ctype_com), fits_i, 0, s, cname, status ); SetItemC( &(store->cname), fits_i, 0, s, cname, status ); } /* Store values for the other FITS-WCS keywords which describe the spectral system. Only store values which have been explicitly set in the SpecFrame, which are different to the default values defined by FITS-WCS paper III (if any), and which are not bad. */ if( astTestObsLon( specfrm ) && astTestObsLat( specfrm ) && s == ' ' ) { geolon = astGetObsLon( specfrm ); geolat = astGetObsLat( specfrm ); h = astGetObsAlt( specfrm ); if( geolat != AST__BAD && geolon != AST__BAD && h != AST__BAD ) { eraGd2gc( 1, geolon, geolat, h, xyz ); SetItem( &(store->obsgeox), 0, 0, ' ', xyz[0], status ); SetItem( &(store->obsgeoy), 0, 0, ' ', xyz[1], status ); SetItem( &(store->obsgeoz), 0, 0, ' ', xyz[2], status ); } } if( astTestRestFreq( specfrm ) ) { restfreq = astGetRestFreq( specfrm ); if( restfreq != AST__BAD ) { if( !strcmp( orig_system, "WAVE" ) || !strcmp( orig_system, "VOPT" ) || !strcmp( orig_system, "ZOPT" ) || !strcmp( orig_system, "AWAV" ) ) { SetItem( &(store->restwav), 0, 0, s, AST__C/restfreq, status ); } else { SetItem( &(store->restfrq), 0, 0, s, restfreq, status ); } } if( astIsADSBSpecFrame( specfrm ) ) { imagfreq = astGetImagFreq( (AstDSBSpecFrame *) specfrm ); if( imagfreq != AST__BAD ) { SetItem( &(store->imagfreq), 0, 0, s, imagfreq, status ); } } } cval = GetFitsSor( astGetC( specfrm, "StdOfRest" ), status ); if( cval ) SetItemC( &(store->specsys), 0, 0, s, cval, status ); if( astTestSourceVel( specfrm ) ) { vsource = astGetSourceVel( specfrm ); if( vsource != AST__BAD && fabs( vsource ) < AST__C ) { zsource = sqrt( (AST__C + vsource)/ (AST__C - vsource) ) - 1.0; SetItem( &(store->zsource), 0, 0, s, zsource, status ); cval = GetFitsSor( astGetC( specfrm, "SourceVRF" ), status ); if( cval ) SetItemC( &(store->ssyssrc), 0, 0, s, cval, status ); } } else { vsource = AST__BAD; } /* Store the VELOSYS value (not strictly needed since it can be determined from the other values, but FITS-WCS paper III says it can be useful). We temporarily change the source velocity to be zero m/s in the main rest frame (StdOfRest) (unless the main rest frame is already the source rest frame). We then change the source rest frame to topocentric and get the source velocity (i.e. the velocity of the main rest Frame) in the topocentric system. We then re-instate the original attribute values if they were set. */ if( astGetStdOfRest( specfrm ) != AST__SCSOR ) { sourcevrf = astGetSourceVRF( specfrm ); astSetSourceVRF( specfrm, astGetStdOfRest( specfrm ) ); astSetSourceVel( specfrm, 0.0 ); } else { vsource = AST__BAD; sourcevrf = AST__NOSOR; } astSetSourceVRF( specfrm, AST__TPSOR ); SetItem( &(store->velosys), 0, 0, s, astGetSourceVel( specfrm ), status ); if( vsource != AST__BAD ){ astSetSourceVRF( specfrm, sourcevrf ); astSetSourceVel( specfrm, vsource ); } /* Indicate that this axis has been described. */ axis_done[ iax ] = 1; } /* Release resources. */ map = astAnnul( map ); } } pframe = astAnnul( pframe ); } /* Release resources. */ lbnd_p = astFree( lbnd_p ); ubnd_p = astFree( ubnd_p ); wcsfrm = astAnnul( wcsfrm ); /* If we have a Mapping to return, simplify it. Otherwise, create a UnitMap to return. */ if( ret ) { tmap0 = ret; ret = astSimplify( tmap0 ); tmap0 = astAnnul( tmap0 ); } else { ret = (AstMapping *) astUnitMap( nwcs, "", status ); } /* Return the result. */ return ret; } static AstFitsChan *SpecTrans( AstFitsChan *this, int encoding, const char *method, const char *class, int *status ){ /* * Name: * SpecTrans * Purpose: * Translated non-standard WCS FITS headers into equivalent standard * ones. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstFitsChan *SpecTrans( AstFitsChan *this, int encoding, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function checks the supplied FitsChan for selected * non-standard WCS keywords and, if found, stores equivalent * standard keywords in a newly created FitsChan which is returned as * the function value. All the original keywords are marked * as having been used, so that they are not written out when the * FitsChan is deleted. * * At the moment, the non-standard keywords checked for are: * * 1) RADECSYS is renamed as RADESYS * * 2) LONGPOLE is renamed as LONPOLE * * 3) CDjjjiii and CDj_i are converted to PCi_j (with unit CDELT) * * 4) CROTAj are converted to PCi_j * * 5) PROJPi are converted to PV_i * * 6) CmVALi are converted to CRVALis (s=A,B,,, for m=1,2...). This * is also done for CmPIXi, CmYPEi, and CmNITi. CmELTi is converted * to a CDj_is array. * * 7) EQUINOX keywords with string values equal to a date preceded * by the letter B or J (eg "B1995.0"). These are converted to the * corresponding Julian floating point value without any epoch * specifier. * * 8) EPOCH values are converted into Julian EQUINOX values (but only * if the FitsChan does not already contain an EQUINOX value). * * 9) DATE-OBS values are converted into MJD-OBS values (but only * if the FitsChan does not already contain an MJD-OBS value). * * 10) EQUINOX or EPOCH keywords with value zero are converted to * B1950. * * 11) The AIPS NCP and GLS projections are converted into equivalent SIN * or SFL projections. * * 12) The IRAF "ZPX" projection. If the last 4 chacaters of CTYPEi * (i = 1, naxis) are "-ZPX", then: * - "ZPX" is replaced by "ZPN" within the CTYPEi value * - A distortion code of "-ZPX" is appended to the end of the CTYPEi * value (this is used later by the DistortMaps function). * - If the FitsChan contains no PROJP keywords, then projection * parameter valus are read from any WATi_nnn keywords, and * corresponding PV keywords are added to the FitsChan. * * 13) The IRAF "TNX" projection. If the last 4 chacaters of CTYPEi * (i = 1, naxis) are "-TNX", then: * - "TNX" is replaced by "TAN" within the CTYPEi value (the distorted * TAN projection included in a pre-final version of FITS-WCS is still * supported by AST using the WcsMap AST__TPN projection). * - If the FitsChan contains no PROJP keywords, then projection * parameter valus are read from any WATi_nnn keywords, and * corresponding PV keywords are added to the FitsChan. * - If the TNX projection cannot be converted exactly into a TAN * projection, ASTWARN keywords are added to the FitsChan * containing a warning message. The calling application can (if it * wants to) check for this keyword, and report its contents to the * user. * * 14) Keywords relating to the IRAF "mini-WCS" system are removed. * This is the IRAF equivalent of the AST native encoding. Mini-WCS * keywords are removed in order to avoid confusion arising between * potentially inconsistent encodings. * * 15) "QV" parameters for TAN projections (as produced by AUTOASTROM) * or "-TAB" (as produced by FitsChan) are renamed to "PV". * * 16) RESTFREQ is converted to RESTFRQ. * * 17) the "-WAV", "-FRQ" and "-VEL" CTYPE algorithms included in an * early draft of FITS-WCS paper III are translated to the * corresponding modern "-X2P" form. * * 18) AIPS spectral CTYPE values are translated to FITS-WCS paper III * equivalents. * * 19) AIPS spectral keywords OBSRA and OBSDEC are used to create a * pair of celestial axes with reference point at the specified * (OBSRA,OBSDEC) position. This is only done if the header does not * already contain a pair of celestial axes. * * 20) Common case insensitive CUNIT values: "Hz", "Angstrom", "km/s", * "M/S" * * 21) Various translations specific to the FITS-CLASS encoding. * * 22) SAO distorted TAN projections (uses COi_j keywords to store * polynomial coefficients) are converted to TPN projections. * 23) CTYPE == "LAMBDA" changed to CTYPE = "WAVE" * * 24) if the projection is TAN and the PolyTan attribute is non-zero, * or if the projection is TPV (produced by SCAMP), the projection is * changed to TPN (the AST code for the draft FITS-WCS paper II * conventions for a distorted TAN projection). * Parameters: * this * Pointer to the FitsChan. * encoding * The FitsChan encoding in use. * method * Pointer to string holding name of calling method. * class * Pointer to a string holding the name of the supplied object class. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new FitsChan containing the keywords which * constitute the standard equivalents to any non-standard keywords in * the supplied FitsChan. A NULL pointer is returned if there are no * non-standard keywords in the supplied FitsChan. */ /* Local Variables: */ AstFitsChan *ret; /* The returned FitsChan */ char *assys; /* AIPS standad of rest type */ char *astype; /* AIPS spectral type */ char *comm; /* Pointer to comment string */ char *cval; /* Pointer to character string */ char *start; /* Pointer to start of projp term */ char *watmem; /* Pointer to total WAT string */ char bj; /* Besselian/Julian indicator */ char format[ 50 ]; /* scanf format string */ char keyname[ FITSNAMLEN + 5 ];/* General keyword name + formats */ char lattype[MXCTYPELEN]; /* CTYPE value for latitude axis */ char lontype[MXCTYPELEN]; /* CTYPE value for longitude axis */ char prj[6]; /* Spatial projection string */ char s; /* Co-ordinate version character */ char spectype[MXCTYPELEN]; /* CTYPE value for spectral axis */ char sprj[6]; /* Spectral projection string */ char ss; /* Co-ordinate version character */ char template[ FITSNAMLEN + 1 ];/* General keyword name template */ double *cvals; /* PVi_m values for TPN projection */ double cdelti; /* CDELT for longitude axis */ double cdeltj; /* CDELT for latitude axis */ double cosrota; /* Cos( CROTA ) */ double crota; /* CROTA Value */ double dval; /* General floating value */ double lambda; /* Ratio of CDELTs */ double projp; /* Projection parameter value */ double rowsum2; /* Sum of squared CDi_j row elements */ double sinrota; /* Sin( CROTA ) */ double sinval; /* Sin( dec ref ) */ int *mvals; /* "m" index of each PVi_m value */ int axlat; /* Index of latitude axis */ int axlon; /* Index of longitude axis */ int diag; /* Sign of diagonal CDi_j element */ int dim; /* Length of pixel axis */ int gotpcij; /* Does FitsChan contain any PCi_j keywords? */ int i,j; /* Indices */ int iaxis; /* Axis index */ int icoeff; /* Index of next PVi_m value */ int iproj; /* Projection parameter index */ int jhi; /* Highest axis index */ int jlo; /* Lowest axis index */ int lbnd[ 2 ]; /* Lower index bounds */ int m; /* Co-ordinate version index */ int naxis; /* Number of axes */ int nc; /* Length of string */ int ncoeff; /* Number of PVi_m values */ int ok; /* Can projection be represented in FITS-WCS?*/ int shifted; /* Non-zero if there is an origin shift */ int tlbnd[ 2 ]; /* Lower index bounds */ int tubnd[ 2 ]; /* Upper index bounds */ int ubnd[ 2 ]; /* Upper index bounds */ int use_projp; /* Use PROJP keywors in favour of PV keywords? */ size_t size; /* Length of string value */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise to avoid compiler warnings. */ size = 0; prj[ 0 ] = 0; /* Create the returned FitsChan. */ ret = astFitsChan( NULL, NULL, "", status ); /* Loop round all axis descriptions, starting with primary (' '). */ for( s = 'A' - 1; s <= 'Z' && astOK; s++ ){ if( s == 'A' - 1 ) s = ' '; /* Find the number of axes by finding the highest axis number in any CRPIXi keyword name. Pass on if there are no axes for this axis description. */ if( s != ' ' ) { sprintf( template, "CRPIX%%d%c", s ); } else { strcpy( template, "CRPIX%d" ); } if( !astKeyFields( this, template, 1, &naxis, lbnd ) ) { if( s == ' ' ) s = 'A' - 1; continue; } /* Find the longitude and latitude axes by examining the CTYPE values. They are marked as read. Such markings are only provisional, and they can be read again any number of times until the current astRead operation is completed. Also note the projection type. */ j = 0; axlon = -1; axlat = -1; while( j < naxis && astOK ){ if( GetValue2( ret, this, FormatKey( "CTYPE", j + 1, -1, s, status ), AST__STRING, (void *) &cval, 0, method, class, status ) ){ nc = strlen( cval ); if( !strncmp( cval, "RA--", 4 ) || !strncmp( cval, "AZ--", 4 ) || ( nc > 1 && !strncmp( cval + 1, "LON", 3 ) ) || ( nc > 2 && !strncmp( cval + 2, "LN", 2 ) ) ) { axlon = j; strncpy( prj, cval + 4, 4 ); strncpy( lontype, cval, 10 ); prj[ 4 ] = 0; } else if( !strncmp( cval, "DEC-", 4 ) || !strncmp( cval, "EL--", 4 ) || ( nc > 1 && !strncmp( cval + 1, "LAT", 3 ) ) || ( nc > 2 && !strncmp( cval + 2, "LT", 2 ) ) ) { axlat = j; strncpy( prj, cval + 4, 4 ); strncpy( lattype, cval, 10 ); prj[ 4 ] = 0; /* Check for spectral algorithms from early drafts of paper III */ } else { sprj[ 0 ] = '-'; if( ( nc > 4 && !strncmp( cval + 4, "-WAV", 4 ) ) ) { sprj[ 1 ] = 'W'; } else if( ( nc > 4 && !strncmp( cval + 4, "-FRQ", 4 ) ) ) { sprj[ 1 ] = 'F'; } else if( ( nc > 4 && !strncmp( cval + 4, "-VEL", 4 ) ) ) { sprj[ 1 ] = 'V'; } else { sprj[ 0 ] = 0; } if( *sprj ) { sprj[ 2 ] = '2'; if( !strncmp( cval, "WAVE", 4 ) ) { sprj[ 3 ] = 'W'; } else if( !strncmp( cval, "FREQ", 4 ) ) { sprj[ 3 ] = 'F'; } else if( !strncmp( cval, "VELO", 4 ) ) { sprj[ 3 ] = 'V'; } else if( !strncmp( cval, "VRAD", 4 ) ) { sprj[ 3 ] = 'F'; } else if( !strncmp( cval, "VOPT", 4 ) ) { sprj[ 3 ] = 'W'; } else if( !strncmp( cval, "ZOPT", 4 ) ) { sprj[ 3 ] = 'W'; } else if( !strncmp( cval, "ENER", 4 ) ) { sprj[ 3 ] = 'F'; } else if( !strncmp( cval, "WAVN", 4 ) ) { sprj[ 3 ] = 'F'; } else if( !strncmp( cval, "BETA", 4 ) ) { sprj[ 3 ] = 'V'; } else { sprj[ 0 ] = 0; } } if( *sprj ) { strcpy( spectype, cval ); if( sprj[ 1 ] == sprj[ 3 ] ) { strcpy( sprj, strlen( cval ) > 8 ? "----" : " " ); } else { sprj[ 4 ] = 0; } strncpy( spectype + 4, sprj, 4 ); cval = spectype; SetValue( ret, FormatKey( "CTYPE", j + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); } } j++; } else { break; } } /* RADECSYS keywords ----------------- */ if( s == ' ' ) { if( GetValue2( ret, this, "RADECSYS", AST__STRING, (void *) &cval, 0, method, class, status ) ){ if( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ){ SetValue( ret, "RADESYS", (void *) &cval, AST__STRING, CardComm( this, status ), status ); } } /* LONGPOLE keywords ----------------- */ if( GetValue2( ret, this, "LONGPOLE", AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ if( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ){ SetValue( ret, "LONPOLE", (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } } /* Zero CDELT values. ----------------- */ /* Check there are some CDELT keywords... */ if( s != ' ' ) { sprintf( template, "CDELT%%d%c", s ); } else { strcpy( template, "CDELT%d" ); } if( astKeyFields( this, template, 0, NULL, NULL ) ){ /* Do each row in the matrix. */ for( j = 0; j < naxis; j++ ){ /* Get the CDELT value for this row. */ GetValue2( ret, this, FormatKey( "CDELT", j + 1, -1, s, status ), AST__FLOAT, (void *) &cdeltj, 0, method, class, status ); /* If CDELT is zero, use 1.0E-6 of the corresponding CRVAL value instead, or 1.0 if CRVAL is zero. Otherwise, the zeros could cause the matrix to be non-invertable. The Mapping could then not be simplified or used by a Plot. CDELT values of zero are usually used to indicate "redundant" axes. For instance, a 2D image may be stored as a 3D cube with a single plane with the "redundant" 3rd axis used to specify the wavelength of the filter. The actual value used for CDELT shouldn't matter since the axis only spans a single pixel anyway. */ if( cdeltj == 0.0 ){ GetValue2( ret, this, FormatKey( "CDELT", j + 1, -1, s, status ), AST__FLOAT, (void *) &dval, 1, method, class, status ); cdeltj = 1.0E-6*dval; if( cdeltj == 0.0 ) cdeltj = 1.0; SetValue( ret, FormatKey( "CDELT", j + 1, -1, s, status ), (void *) &cdeltj, AST__FLOAT, NULL, status ); } } } /* Following conversions produce PCi_j keywords. Only do them if there are currently no PCi_j keywords in the header. */ if( s != ' ' ) { sprintf( template, "PC%%d_%%d%c", s ); } else { strcpy( template, "PC%d_%d" ); } gotpcij = astKeyFields( this, template, 0, NULL, NULL ); if( !gotpcij ){ /* CDjjjiii -------- */ if( s == ' ' && astKeyFields( this, "CD%3d%3d", 0, NULL, NULL ) ){ /* Do each row in the matrix. */ for( j = 0; j < naxis; j++ ){ /* Do each column in the matrix. */ for( i = 0; i < naxis; i++ ){ /* Get the CDjjjiii matrix element */ sprintf( keyname, "CD%.3d%.3d", j + 1, i + 1 ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ /* If found, save it with name PCj_i, and ensure the default value of 1.0 is used for CDELT. */ if( encoding == FITSIRAF_ENCODING ){ SetValue( ret, FormatKey( "PC", j + 1, i + 1, ' ', status ), (void *) &dval, AST__FLOAT, NULL, status ); dval = 1.0; SetValue( ret, FormatKey( "CDELT", j + 1, -1, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); gotpcij = 1; } } } } } /* CDj_i ---- */ if( s != ' ' ) { sprintf( template, "CD%%d_%%d%c", s ); } else { strcpy( template, "CD%d_%d" ); } if( !gotpcij && astKeyFields( this, template, 0, NULL, NULL ) ){ /* Do each row in the matrix. */ for( j = 0; j < naxis; j++ ){ /* First find the sum of the squared elements in the row. and note the sign of the diagonal element. */ rowsum2 = 0.0; diag = +1; for( i = 0; i < naxis; i++ ){ if( GetValue2( ret, this, FormatKey( "CD", j + 1, i + 1, s, status ), AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ rowsum2 += dval*dval; if( i == j ) diag = ( dval >= 0.0 ) ? +1 : -1; } } /* The CDELT value for this row will be the length of the row vector. This means that each row will be a unit vector when converted to PCi_j form, and the CDELT will give a real indication of the pixel size. Ensure that the diagonal PCi+j element has a positive sign. */ cdelti = sqrt( rowsum2 )*diag; SetValue( ret, FormatKey( "CDELT", j + 1, -1, s, status ), (void *) &cdelti, AST__FLOAT, NULL, status ); /* Do each column in the matrix. */ for( i = 0; i < naxis; i++ ){ /* Get the CDj_i matrix element (note default value for all CD elements is zero (even diagonal elements!). */ if( !GetValue2( ret, this, FormatKey( "CD", j + 1, i + 1, s, status ), AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ dval = 0.0; } /* Divide by the rows cdelt value and save it with name PCj_i. */ if( cdelti != 0.0 ) dval /= cdelti; SetValue( ret, FormatKey( "PC", j + 1, i + 1, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); gotpcij = 1; } } } /* PCjjjiii and CROTAi keywords ---------------------------- */ /* Check there are some CDELT keywords... */ if( s != ' ' ) { sprintf( template, "CDELT%%d%c", s ); } else { strcpy( template, "CDELT%d" ); } if( !gotpcij && astKeyFields( this, template, 0, NULL, NULL ) ){ /* See if there is a CROTA keyword. Try to read values for both axes since they are sometimes both included. This ensures they will not be included in the output when the FitsChan is deleted. Read the latitude axis second in order to give it priority in cases where both are present. */ crota = AST__BAD; GetValue2( ret, this, FormatKey( "CROTA", axlon + 1, -1, s, status ), AST__FLOAT, (void *) &crota, 0, method, class, status ); GetValue2( ret, this, FormatKey( "CROTA", axlat + 1, -1, s, status ), AST__FLOAT, (void *) &crota, 0, method, class, status ); /* If there are any PCjjjiii keywords, rename them as PCj_i. */ if( s == ' ' && astKeyFields( this, "PC%3d%3d", 0, NULL, NULL ) ){ /* Do each row in the matrix. */ for( j = 0; j < naxis; j++ ){ /* Do each column in the matrix. */ for( i = 0; i < naxis; i++ ){ /* Get the PCiiijjj matrix element */ sprintf( keyname, "PC%.3d%.3d", j + 1, i + 1 ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ } else if( i == j ) { dval = 1.0; } else { dval = 0.0; } /* Store it as PCi_j */ SetValue( ret, FormatKey( "PC", j + 1, i + 1, ' ', status ), (void *) &dval, AST__FLOAT, NULL, status ); gotpcij = 1; } } /* If there is a CROTA value and no PCjjjii keywords, create a PCj_i matrix from the CROTA values. We need to have latitude and longitude axes for this. */ } else if( s == ' ' && axlat != -1 && axlon != -1 && crota != AST__BAD ){ /* Get the sin and cos of CROTA */ cosrota = cos( crota*AST__DD2R ); sinrota = sin( crota*AST__DD2R ); /* Get the CDELT values for the longitude and latitude axes. */ if( GetValue2( ret, this, FormatKey( "CDELT", axlat + 1, -1, ' ', status ), AST__FLOAT, (void *) &cdeltj, 1, method, class, status ) && GetValue2( ret, this, FormatKey( "CDELT", axlon + 1, -1, ' ', status ), AST__FLOAT, (void *) &cdelti, 1, method, class, status ) ){ /* Save the ratio, needed below. */ lambda = cdeltj/cdelti; /* Save a corresponding set of PCi_j keywords in the FitsChan. First do the diagonal terms. */ for( i = 0; i < naxis; i++ ){ if( i == axlat ) { dval = cosrota; } else if( i == axlon ) { dval = cosrota; } else { dval = 1.0; } SetValue( ret, FormatKey( "PC", i + 1, i + 1, ' ', status ), (void *) &dval, AST__FLOAT, NULL, status ); gotpcij = 1; } /* Now do the non-zero off-diagonal terms. */ dval = sinrota/lambda; SetValue( ret, FormatKey( "PC", axlat + 1, axlon + 1, ' ', status ), (void *) &dval, AST__FLOAT, NULL, status ); dval = -sinrota*lambda; SetValue( ret, FormatKey( "PC", axlon + 1, axlat + 1, ' ', status ), (void *) &dval, AST__FLOAT, NULL, status ); } } } } /* Conversion of old PROJP, etc, is done once on the "primary" pass. */ if( s == ' ' ) { /* PROJP keywords -------------- */ if( astKeyFields( this, "PROJP%d", 1, ubnd, lbnd ) && axlat != -1 ) { /* Some people produce headers with both PROJP and PV. Even worse, the PROJP and PV values are sometimes inconsistent. In this case we trust the PV values rather than the PROJP values, but only if the PV values are not obviously incorrect for some reason. In particularly, we check that, *if* either PVi_1 or PVi_2 (where i=longitude axis) is present, then PVi_0 is also present. Conversely we check that if PVi_0 is present then at least one of PVi_1 or PVi_2 is present. */ use_projp = 1; if( axlat != -1 && astKeyFields( this, "PV%d_%d", 2, tubnd, tlbnd ) ){ use_projp = 0; /* Are there any PV values for the longitude axis? */ if( tlbnd[ 0 ] <= axlon + 1 && axlon + 1 <= tubnd[ 0 ] ) { /* Are either PVi_1 or PVi_2 available? */ if( HasCard( this, FormatKey( "PV", axlon + 1, 1, ' ', status ), method, class, status ) || HasCard( this, FormatKey( "PV", axlon + 1, 2, ' ', status ), method, class, status ) ) { /* If so use PROJP if PVi_0 is not also available. */ if( !HasCard( this, FormatKey( "PV", axlon + 1, 0, ' ', status ), method, class, status ) ) use_projp = 1; /* If neither PVi_1 or PVi_2 are available, use PROJP if PVi_0 is available. */ } else if( HasCard( this, FormatKey( "PV", axlon + 1, 0, ' ', status ), method, class, status ) ) { use_projp = 1; } } } /* Translate PROJP to PV if required. */ if( use_projp ) { for( i = lbnd[ 0 ]; i <= ubnd[ 0 ]; i++ ){ if( GetValue2( ret, this, FormatKey( "PROJP", i, -1, ' ', status ), AST__FLOAT, (void *) &dval, 0, method, class, status ) && ( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ) ){ SetValue( ret, FormatKey( "PV", axlat + 1, i, ' ', status ), (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } } } /* CmVALi keywords --------------- */ if( astKeyFields( this, "C%1dVAL%d", 2, ubnd, lbnd ) ){ ss = 'A'; for( m = lbnd[ 0 ]; m <= ubnd[ 0 ]; m++ ){ for( i = lbnd[ 1 ]; i <= ubnd[ 1 ]; i++ ){ sprintf( keyname, "C%dVAL%d", m, i ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) && ( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ) ){ sprintf( keyname, "CRVAL%d%c", i, ss ); SetValue( ret, keyname, (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } ss++; } } /* CmPIXi keywords --------------- */ if( astKeyFields( this, "C%1dPIX%d", 2, ubnd, lbnd ) ){ ss = 'A'; for( m = lbnd[ 0 ]; m <= ubnd[ 0 ]; m++ ){ for( i = lbnd[ 1 ]; i <= ubnd[ 1 ]; i++ ){ sprintf( keyname, "C%dPIX%d", m, i ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) && ( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ) ){ sprintf( keyname, "CRPIX%d%c", i, ss ); SetValue( ret, keyname, (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } ss++; } } /* CmYPEi keywords --------------- */ if( astKeyFields( this, "C%1dYPE%d", 2, ubnd, lbnd ) ){ ss = 'A'; for( m = lbnd[ 0 ]; m <= ubnd[ 0 ]; m++ ){ for( i = lbnd[ 1 ]; i <= ubnd[ 1 ]; i++ ){ sprintf( keyname, "C%dYPE%d", m, i ); if( GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) && ( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ) ){ sprintf( keyname, "CTYPE%d%c", i, ss ); SetValue( ret, keyname, (void *) &cval, AST__STRING, CardComm( this, status ), status ); } } ss++; } } /* CmNITi keywords --------------- */ if( astKeyFields( this, "C%1dNIT%d", 2, ubnd, lbnd ) ){ ss = 'A'; for( m = lbnd[ 0 ]; m <= ubnd[ 0 ]; m++ ){ for( i = lbnd[ 1 ]; i <= ubnd[ 1 ]; i++ ){ sprintf( keyname, "C%dNIT%d", m, i ); if( GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) && ( encoding == FITSPC_ENCODING || encoding == FITSIRAF_ENCODING ) ){ sprintf( keyname, "CUNIT%d%c", i, ss ); SetValue( ret, keyname, (void *) &cval, AST__STRING, CardComm( this, status ), status ); } } ss++; } } /* CmELTi keywords --------------- */ if( astKeyFields( this, "C%1dELT%d", 2, ubnd, lbnd ) ){ ss = 'A'; for( m = lbnd[ 0 ]; m <= ubnd[ 0 ]; m++ ){ /* Create a PCj_is matrix by copying the PCjjjiii values and rename CmELTi as CDELTis. */ /* Do each row in the matrix. */ for( j = 0; j < naxis; j++ ){ /* Get the CDELT value for this row. Report an error if not present. */ sprintf( keyname, "C%dELT%d", m, j + 1 ); GetValue2( ret, this, keyname, AST__FLOAT, (void *) &cdeltj, 1, method, class, status ); /* If CDELT is zero, use one hundredth of the corresponding CRVAL value instead, or 1.0 if CRVAL is zero. Otherwise, the zeros could cause the matrix to be non-invertable. The Mapping could then not be simplified or used by a Plot. CDELT values of zero are usually used to indicate "redundant" axes. For instance, a 2D image may be stored as a 3D cube with a single plane with the "redundant" 3rd axis used to specify the wavelength of the filter. The actual value used for CDELT shouldn't matter since the axis only spans a single pixel anyway. */ if( cdeltj == 0.0 ){ GetValue2( ret, this, FormatKey( "CRVAL", j + 1, -1, ss, status ), AST__FLOAT, (void *) &dval, 1, method, class, status ); cdeltj = 0.01*dval; if( cdeltj == 0.0 ) cdeltj = 1.0; } /* Save it as CDELTis */ sprintf( keyname, "CDELT%d%c", j + 1, ss ); SetValue( ret, keyname, (void *) &cdeltj, AST__FLOAT, CardComm( this, status ), status ); /* Do each column in the matrix. */ for( i = 0; i < naxis; i++ ){ /* Get the PCiiijjj matrix element */ sprintf( keyname, "PC%.3d%.3d", j + 1, i + 1 ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ } else if( i == j ) { dval = 1.0; } else { dval = 0.0; } /* Store it as PCi_js. */ SetValue( ret, FormatKey( "PC", j + 1, i + 1, ss, status ), (void *) &dval, AST__FLOAT, NULL, status ); } } ss++; } } /* EPOCH keywords ------------ */ /* Get any EPOCH card, marking it as read. */ if( GetValue2( ret, this, "EPOCH", AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ /* Convert values of zero to B1950. */ if( dval == 0.0 ) dval = 1950.0; /* Save a new EQUINOX card in the FitsChan, so long as there is not already one there. */ if( !GetValue2( ret, this, "EQUINOX", AST__STRING, (void *) &cval, 0, method, class, status ) ){ SetValue( ret, "EQUINOX", (void *) &dval, AST__FLOAT, "Reference equinox", status ); } } /* String EQUINOX values --------------------- If found, EQUINOX will be used in favour of any EPOCH value found above. */ if( GetValue2( ret, this, "EQUINOX", AST__STRING, (void *) &cval, 0, method, class, status ) ){ /* Note the first character. */ bj = cval[ 0 ]; /* If it is "B" or "J", read a floating value from the rest */ if( bj == 'B' || bj == 'J' ) { if( 1 == astSscanf( cval + 1, " %lf ", &dval ) ){ /* If it is a Besselian epoch, convert to Julian. */ if( bj == 'B' ) dval = palEpj( palEpb2d( dval ) ); /* Replace the original EQUINOX card. */ SetValue( ret, "EQUINOX", (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } } /* EQUINOX = 0.0 keywords ---------------------- */ if( GetValue2( ret, this, "EQUINOX", AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ if( dval == 0.0 ){ dval = 1950.0; SetValue( ret, "EQUINOX", (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } } /* DATE-OBS keywords ---------------- */ /* Read any DATE-OBS card. This prevents it being written out when the FitsChan is deleted. */ if( s == ' ' ) { strcpy( keyname, "DATE-OBS" ); if( GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) ){ /* Ignore DATE-OBS values if the header contains an MJD-OBS value */ strcpy( keyname, "MJD-OBS" ); if( !GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ /* Get the corresponding mjd-obs value, checking that DATE-OBS is valid. */ dval = DateObs( cval, status ); if( dval != AST__BAD ){ SetValue( ret, keyname, (void *) &dval, AST__FLOAT, "Date of observation", status ); } } } } /* Things specific to the CLASS encoding ------------------------------------- */ if( encoding == FITSCLASS_ENCODING ) ClassTrans( this, ret, axlat, axlon, method, class, status ); /* Convert SAO distorted TAN headers to TPN distorted TAN headers. -------------------------------------------------------------- */ if( s == ' ' && !Ustrcmp( prj, "-TAN", status ) ){ /* Translate the COi_m keywords into PV i+m keywords. */ if( SAOTrans( this, ret, method, class, status ) ) { /* Change the CTYPE projection form TAN to TPV. */ strcpy( prj, "-TPN" ); strcpy( lontype + 4, "-TPN" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-TPN" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); } } /* AIPS "NCP" projections --------------------- */ /* Compare the projection type with "-NCP" */ if( !Ustrcmp( prj, "-NCP", status ) ) { /* Get the latitude reference value, and take is cot. */ GetValue2( ret, this, FormatKey( "CRVAL", axlat + 1, -1, s, status ), AST__FLOAT, (void *) &dval, 1, method, class, status ); sinval = sin( dval*AST__DD2R ); if( sinval != 0.0 ) { dval = cos( dval*AST__DD2R )/sinval; /* Replace NCP with SIN in the CTYPE values. */ strcpy( lontype + 4, "-SIN" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-SIN" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); /* Store the new projection parameters using names suitable to FITS_WCS encoding. */ SetValue( ret, FormatKey( "PV", axlat + 1, 2, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); dval = 0.0; SetValue( ret, FormatKey( "PV", axlat + 1, 1, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); } } /* CLASS "ATF" projections ---------------------- */ /* Replace ATF with AIT in the CTYPE values. */ if( !Ustrcmp( prj, "-ATF", status ) ) { strcpy( lontype + 4, "-AIT" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-AIT" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); } /* AIPS "GLS" projections --------------------- */ /* Compare the projection type with "-GLS" */ if( !Ustrcmp( prj, "-GLS", status ) ) { /* Convert to "-SFL" */ strcpy( lontype + 4, "-SFL" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-SFL" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); /* FITS-WCS paper 2 (sec. 6.1.4) describes how to handle AIPS GLS projections, but requires that the axes are not rotated. Instead, we modify the native latitude at the fiducial point, theta_0, as is done in wcslib function celfix in file wcsfix.c (see also FITS-WCS paper II sec. 2.5). We only need to change theta_0 if the CRVAL position is not the celestial origin. */ shifted = 0; sprintf( keyname, "CRVAL%d", axlon + 1 ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ if( dval != 0.0 ) shifted = 1; } sprintf( keyname, "CRVAL%d", axlat + 1 ); if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ if( dval != 0.0 ) shifted = 1; } if( 0 && shifted ) { SetValue( ret, FormatKey( "PV", axlon + 1, 2, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); dval = 0.0; SetValue( ret, FormatKey( "PV", axlon + 1, 1, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); dval = 1.0; SetValue( ret, FormatKey( "PV", axlon + 1, 0, s, status ), (void *) &dval, AST__FLOAT, NULL, status ); } } /* Rename any "QV" projection parameters to "PV" (such as used by -TAB to indicate the interpolation method, or by the internal -TPN projection to indicate distortion coefficients). ------------------------------------------------------------ */ /* Rewind the FitsChan. */ astClearCard( this ); /* Search the FitsChan for QV cards. */ if( s != ' ' ) { sprintf( template, "QV%%d_%%d%c", s ); } else { strcpy( template, "QV%d_%d" ); } while( FindKeyCard( this, template, method, class, status ) && astOK ) { /* If the projection name is "TAN", replace TAN with TPN in the CTYPE values. */ if( !Ustrcmp( prj, "-TAN", status ) ){ strcpy( prj, "-TPN" ); strcpy( lontype + 4, "-TPN" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-TPN" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); } /* Indicate that the QV card has been consumed. */ MarkCard( this, status ); /* Get the keyword name and change it from QV to PV. */ strcpy( keyname, CardName( this, status ) ); keyname[ 0 ] ='P'; /* Store the new PV card so long as there it is not already present in the FitsChan. */ if( !GetValue2( ret, this, keyname, AST__FLOAT, (void *) &cval, 0, method, class, status ) ){ SetValue( ret, keyname, CardData( this, &size, status ), AST__FLOAT, CardComm( this, status ), status ); } /* Move on to the next card. */ MoveCard( this, 1, method, class, status ); } /* Change any TAN projection to TPN projection if the PolyTan attribute is non-zero. Also change any TPV projection to TPN projection. --------------------------------------------------- */ if( ( !Ustrcmp( prj, "-TAN", status ) && GetUsedPolyTan( this, ret, axlat + 1, axlon + 1, s, method, class, status ) ) || !Ustrcmp( prj, "-TPV", status ) ){ strcpy( prj, "-TPN" ); strcpy( lontype + 4, "-TPN" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-TPN" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); } /* IRAF "ZPX" projections --------------------- */ if( s == ' ' && !Ustrcmp( prj, "-ZPX", status ) ) { /* Replace "ZPX" with "ZPN-ZPX" (i.e. ZPN projection with ZPX distortion code) in the CTYPE values. */ strcpy( lontype + 4, "-ZPN-ZPX" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, ' ', status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-ZPN-ZPX" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, ' ', status ), (void *) &cval, AST__STRING, NULL, status ); /* Check latitude then longitude axes */ for( i = 0; i < 2; i++ ){ iaxis = i ? axlat : axlon; /* Concatenate all the IRAF "WAT" keywords together for this axis. These keywords are marked as having been used, so that they are not written out when the FitsChan is deleted. */ watmem = ConcatWAT( this, iaxis, method, class, status ); /* Search the total WAT string for any projp terms. */ if( watmem ){ for( iproj = 0; iproj < 10 && astOK; iproj++ ) { sprintf( format, "projp%d=", iproj ); start = strstr( watmem, format ); if( start ) { sprintf( format, "projp%d=%%lf", iproj ); if( astSscanf( start, format, &projp ) ){ SetValue( ret, FormatKey( "PV", axlat + 1, iproj, ' ', status ), (void *) &projp, AST__FLOAT, "ZPN projection parameter", status ); } } } /* Release the memory used to hold the concatenated WAT keywords. */ watmem = (char *) astFree( (void *) watmem ); } } /* IRAF "TNX" projections --------------------- */ } else if( s == ' ' && !Ustrcmp( prj, "-TNX", status ) ) { /* Replace TNX with TPN in the CTYPE values. */ strcpy( lontype + 4, "-TPN" ); cval = lontype; SetValue( ret, FormatKey( "CTYPE", axlon + 1, -1, ' ', status ), (void *) &cval, AST__STRING, NULL, status ); strcpy( lattype + 4, "-TPN" ); cval = lattype; SetValue( ret, FormatKey( "CTYPE", axlat + 1, -1, ' ', status ), (void *) &cval, AST__STRING, NULL, status ); /* Check latitude then longitude axes */ for( i = 0; i < 2; i++ ){ iaxis = i ? axlat : axlon; /* Concatenate all the IRAF "WAT" keywords together for this axis. These keywords are marked as having been used, so that they are not written out when the FitsChan is deleted. */ watmem = ConcatWAT( this, iaxis, method, class, status ); /* Extract the polynomial coefficients from the concatenated WAT string. These are returned in the form of a list of PVi_m values for a TPN projection. */ ncoeff = WATCoeffs( watmem, i, &cvals, &mvals, &ok, status ); /* If we can handle the TNX projection, store the PV values in the FitsChan. */ if( ok ) { for( icoeff = 0; icoeff < ncoeff; icoeff++ ) { SetValue( ret, FormatKey( "PV", iaxis + 1, mvals[ icoeff ], ' ', status ), (void *) (cvals + icoeff), AST__FLOAT, "TAN projection parameter", status ); } /* If the TNX cannot be represented in FITS-WCS (within our restrictions), add warning keywords to the FitsChan. */ } else { Warn( this, "tnx", "This FITS header includes, or was " "derived from, a TNX projection which requires " "unsupported IRAF-specific corrections. The WCS " "information may therefore be incorrect.", method, class, status ); } /* Release the memory used to hold the concatenated WAT keywords. */ watmem = (char *) astFree( (void *) watmem ); } } /* MSX CAR projections. ------------------- */ if( !Ustrcmp( prj, "-CAR", status ) && !astGetCarLin( this ) ) { /* The CAR projection has valid projection plane points only for native longitudes in the range [-180,+180]. The reference pixel (CRPIX) is at native longitude zero. We need to check that the reference point is not so far outside the image that the entire image lies outside the range [-180,+180]. If it is, we modify the CRPIX value by the number of pixels corresponding to 360 degres of longitude in order to bring the array into the valid domain ([-180,+180]) of the projection. */ if( GetValue2( ret, this, FormatKey( "CDELT", axlon + 1, -1, s, status ), AST__FLOAT, (void *) &cdelti, 1, method, class, status ) && GetValue2( ret, this, FormatKey( "CRPIX", axlon + 1, -1, s, status ), AST__FLOAT, (void *) &dval, 0, method, class, status ) ) { /* We check if the mid point of the array is in the valiud longitude range. Use the bottom left corner as a fallback if the image size is unknown. */ if( !GetValue( this, FormatKey( "NAXIS", axlon + 1, -1, ' ', status ), AST__INT, &dim, 0, 0, method, class, status ) ) { dim = 0; } if( cdelti != 0.0 ) { double offset = 0.5*( dim + 1 ); dval = offset + AST__DR2D*palDrange( AST__DD2R*( dval - offset )*cdelti )/cdelti; SetValue( ret, FormatKey( "CRPIX", axlon + 1, -1, s, status ), (void *) &dval, AST__FLOAT, CardComm( this, status ), status ); } } } /* Replace RESTFREQ by RESTFRQ. ---------------------------- */ /* Get any RESTFREQ card, marking it as read. */ if( s != ' ' ) { sprintf( keyname, "RESTFREQ%c", s ); } else { strcpy( keyname, "RESTFREQ" ); } if( GetValue2( ret, this, keyname, AST__FLOAT, (void *) &dval, 0, method, class, status ) ){ /* Look for "MHz" and "GHz" within the comment. If found scale the value into Hz. */ comm = CardComm( this, status ); if( comm ) { if( strstr( comm, "GHz" ) ) { dval *= 1.0E9; comm = "[Hz] Rest Frequency"; } else if( strstr( comm, "MHz" ) ) { dval *= 1.0E6; comm = "[Hz] Rest Frequency"; } } /* Save a new RESTFRQ card in the FitsChan, so long as there is not already one there. */ if( s != ' ' ) { sprintf( keyname, "RESTFRQ%c", s ); } else { strcpy( keyname, "RESTFRQ" ); } if( !GetValue2( ret, this, keyname, AST__STRING, (void *) &cval, 0, method, class, status ) ){ SetValue( ret, keyname, (void *) &dval, AST__FLOAT, comm, status ); } } /* Translate AIPS spectral CTYPE values to FITS-WCS paper III equivalents. These are of the form AAAA-BBB, where "AAAA" can be "FREQ", "VELO" (=VRAD!) or "FELO" (=VOPT-F2W), and BBB can be "LSR", "LSD", "HEL" (=*Bary*centric!) or "GEO". Also convert "LAMBDA" to "WAVE". */ for( j = 0; j < naxis; j++ ) { if( GetValue2( ret, this, FormatKey( "CTYPE", j + 1, -1, s, status ), AST__STRING, (void *) &cval, 0, method, class, status ) ){ if( IsAIPSSpectral( cval, &astype, &assys, status ) ) { SetValue( ret, FormatKey( "CTYPE", j + 1, -1, s, status ), (void *) &astype, AST__STRING, NULL, status ); SetValue( ret, "SPECSYS", (void *) &assys, AST__STRING, NULL, status ); break; } else if( !strcmp( cval, "LAMBDA " ) ) { cval = "WAVE"; SetValue( ret, FormatKey( "CTYPE", j + 1, -1, s, status ), (void *) &cval, AST__STRING, NULL, status ); break; } } } /* Common case insensitive CUNIT values: "Hz", "Angstrom", "km/s", "M/S" */ if( s != ' ' ) { sprintf( template, "CUNIT%%d%c", s ); } else { strcpy( template, "CUNIT%d" ); } if( astKeyFields( this, template, 1, &jhi, &jlo ) ){ /* Convert keyword indices from 1-based to 0-base, and loop round them all. */ jhi--; jlo--; for( j = jlo; j <= jhi; j++ ){ char *keynam; keynam = FormatKey( "CUNIT", j + 1, -1, s, status ); if( GetValue2( ret, this, keynam, AST__STRING, (void *) &cval, 0, method, class, status ) ){ size_t nc = astChrLen( cval ); if( nc == 0 ) { cval = NULL; } else if( !Ustrcmp( cval, "Hz", status ) ) { cval = "Hz"; } else if( !Ustrcmp( cval, "Angstrom", status ) ) { cval = "Angstrom"; } else if( !Ustrcmp( cval, "km/s", status ) ) { cval = "km/s"; } else if( !Ustrcmp( cval, "m/s", status ) ) { cval = "m/s"; } else { cval = NULL; } if( cval ) SetValue( ret, keynam, (void *) &cval, AST__STRING, NULL, status ); } } } /* After doing the primary axis descriptions, prepare to do the "A" description. */ if( s == ' ' ) s = 'A' - 1; } /* IRAF mini-WCS keywords ---------------------- */ /* Rewind the FitsChan to search from the first card. */ astClearCard( this ); /* Search forward through until all cards have been checked. */ while( !astFitsEof( this ) && astOK ){ /* Check to see if the keyword name from the current card matches any of the known mini-WCS keywords. If so, mark the card as read. */ if( Match( CardName( this, status ), "WAT%d_%d", 0, NULL, &m, method, class, status ) || Match( CardName( this, status ), "LTM%d_%d", 0, NULL, &m, method, class, status ) || Match( CardName( this, status ), "LTV%d", 0, NULL, &m, method, class, status ) || Match( CardName( this, status ), "WSV%d_LEN", 0, NULL, &m, method, class, status ) || Match( CardName( this, status ), "WSV%d_%d", 0, NULL, &m, method, class, status ) ){ MarkCard( this, status ); } /* Now move the current card on to the next card. */ MoveCard( this, 1, method, class, status ); } /* Delete the returned FitsChan if it is empty. */ if( ret && !astGetNcard( ret ) ) ret = (AstFitsChan *) astDelete( ret ); /* Return. */ return ret; } int Split( AstFitsChan *this, const char *card, char **name, char **value, char **comment, const char *method, const char *class, int *status ){ /* * Name: * Split * Purpose: * Extract the keyword name, value and comment from a FITS header card. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Split( AstFitsChan *this, const char *card, char **name, char **value, * char **comment, const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * The name, value and comment (if present) are extracted from the * supplied card text and returned. * Parameters: * this * Pointer to the FitsCHan. * card * Pointer to a string holding the FITS header card. * name * Pointer to a location at which to return the pointer to a string * holding the keyword name. * value * Pointer to a location at which to return the pointer to a string * holding the keyword value. * comment * Pointer to a location at which to return the pointer to a string * holding the keyword comment. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned value: * - An integer identifying the data type of the keyword value. This * will be one of the values AST__UNDEF, AST__COMMENT, AST__INT, * AST__STRING, AST__CONTINUE, AST__FLOAT, AST__COMPLEXI or AST__COMPLEXF * defined in fitschan.h. * Notes: * - If the keyword value is a string, then the returned value does not * include the delimiting quotes, and pairs of adjacent quotes within the * string are replaced by single quotes. * - A maximum of 80 characters are read from the supplied card, so the * string does not need to be null terminated unless less than 80 * characters are to be read. * - The memory holding the three strings "name", "value" and "comment" * should be released when no longer needed using astFree. * - NULL pointers and a data type of AST__COMMENT are returned if an * error has already occurred, or if this function fails for any reason. */ /* Local Variables: */ char *c; /* Pointer to returned comment string */ char *dd; /* Pointer to intermediate character */ char *slash; /* Pointer to comment character */ char *v; /* Pointer to returned value string */ char buf[255]; /* Buffer for warning text */ const char *d; /* Pointer to first comment character */ const char *v0; /* Pointer to first non-blank value character */ double fi, fr; /* Values read from value string */ int badval; /* Is the keyword value illegal? */ int blank_name; /* Is keyword name blank? */ int cont; /* Is this a continuation card? */ int i; /* Character index */ int ii, ir; /* Values read from value string */ int iopt; /* Index of option within list */ int len; /* Used length of value string */ int lq; /* Was previous character an escaping quote? */ int nch; /* No. of characters used */ int ndig; /* No. of digits in the formatted integer */ int type; /* Keyword data type */ size_t nc; /* Number of character in the supplied card */ size_t ncc; /* No. of characters in the comment string */ size_t ncv; /* No. of characters in the value string */ /* Initialise the returned pointers. */ *name = NULL; *value = NULL; *comment = NULL; type = AST__COMMENT; /* Check the global status. */ if( !astOK ) return type; /* Assume initially that the keyword value is legal. */ badval = 0; /* Store the number of characters to be read from the supplied card. This is not allowed to be more than the length of a FITS header card. */ nc = 0; while( nc < AST__FITSCHAN_FITSCARDLEN && card[ nc ] ) nc++; /* Reduce the number of characters to read so that any non-printing characters such as new-lines at the end of the string are ignored. */ while( nc > 0 && !isprint( card[ nc - 1 ] ) ) nc--; /* Allocate memory for a copy of the keyword name plus a terminating null character. */ *name = (char *) astMalloc( ( 1 + FITSNAMLEN )*sizeof(char) ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise the name string by filling it with spaces, and terminating it. */ for( i = 0; i < FITSNAMLEN; i++ ) (*name)[ i ] = ' '; (*name)[ FITSNAMLEN ] = 0; /* Copy the the keyword name, ensuring that no more than FITSNAMLEN (8) characters are copied. */ strncpy( *name, card, ( nc > FITSNAMLEN ) ? FITSNAMLEN : nc ); /* If there is no keyword name, flag that we have a blank name which will be treated as a comment card. */ if( strspn( *name, " " ) == strlen( *name ) ){ blank_name = 1; /* If the card contains a keyword name, replace any white space with nulls. */ } else { blank_name = 0; dd = *name + strlen( *name ) - 1; while( isspace( *dd ) ) *(dd--) = 0; } /* Check the keyword name is legal. */ CheckFitsName( this, *name, method, class, status ); /* Allocate memory to hold the keyword value and comment strings. */ *value = (char *) astMalloc( sizeof(char)*( 2 + nc ) ); *comment = (char *) astMalloc( sizeof(char)*( 1 + nc ) ); /* Check the pointers can be used. */ if( astOK ){ /* Check for CONTINUE cards. These have keyword CONTINUE but have a space instead of an equals sign in column 9. They must also have a single quote in column 11. */ cont = ( !Ustrcmp( *name, "CONTINUE", status ) && nc > FITSNAMLEN + 3 && card[ FITSNAMLEN ] == ' ' && card[ FITSNAMLEN + 2 ] == '\'' ); /* If column 9 does not contain an equals sign (but is not a CONTINUE card), or if the keyword is "HISTORY", "COMMENT" or blank, then columns 9 to the end are comment characters, and the value string is null. */ if( ( nc <= FITSNAMLEN || card[ FITSNAMLEN ] != '=' || !Ustrcmp( *name, "HISTORY", status ) || !Ustrcmp( *name, "COMMENT", status ) || blank_name ) && !cont ){ (*value)[ 0 ] = 0; if( nc > FITSNAMLEN ){ (void) strncpy( *comment, card + FITSNAMLEN, nc - FITSNAMLEN ); (*comment)[ nc - FITSNAMLEN ] = 0; } else { (*comment)[ 0 ] = 0; } /* Otherwise there is a value field. */ } else { /* Find the first non-blank character in the value string. */ v0 = card + FITSNAMLEN + 1; while( (size_t)(v0 - card) < nc && isspace( (int) *v0 ) ) v0++; /* Store pointers to the start of the returned value and comment strings. */ v = *value; c = *comment; /* If the first character in the value string is a single quote, the value is a string. In this case the value ends at the first non-escaped single quote. */ if( *v0 == '\''){ type = cont ? AST__CONTINUE : AST__STRING; /* We want to copy the string value, without the delimiting quotes, to the returned value string. Single quotes within the string are represented by two adjacent quotes, so we also need to check for these and replace them by one quote in the returned string. First initialise a pointer to the first character after the opening quote, and set a flag indicating that (for the purposes of identifying pairs of adjacent quotes within the string) the previous character was not a quote. */ d = v0 + 1; lq = 0; /* Loop round each remaining character in the supplied card. */ while( (size_t)(d - card) < nc ){ /* If the current character is a single quote... */ if( *d == '\'' ){ /* If the previous character was also a single quote then the quote does not mark the end of the string, but is a quote to be included literally in the value. Copy the quote to the returned string and clear the flag to indicate that the pair of adjacent quotes is now complete. */ if( lq ){ *(v++) = '\''; lq = 0; /* If the last character was not a quote, then set the flag for the next pass through the loop, but do not copy the quote to the returned string since it will either be a quote escaping a following adjacent quote, or a quote to mark the end of the string. */ } else { lq = 1; } /* If the current character is not a quote... */ } else { /* If the previous character was a quote, then we have found a single isolated quote which therefore marks the end of the string value. The pointer "d" is left pointing to the first character after the terminating quote. */ if( lq ){ break; /* If the last character was not a quote, copy it to the returned string. */ } else { *(v++) = *d; } } d++; } /* Terminate the returned value string. */ *v = 0; /* Now deal with logical and numerical values. */ } else { /* The end of the value field is marked by the first "/". Find the number of characters in the value field. Pointer "d" is left pointing to the first character in the comment (if any). Only use "/" characters which occur within the first nc characters, and do not occur wiuthin the keyword name (not strictly legal, but a warning will have been issued by CheckFitsName in such cases). */ d = strchr( card + FITSNAMLEN, '/' ); if( !d || ( d - card ) >= nc ){ ncv = nc - FITSNAMLEN - 1; d = NULL; } else { ncv = (size_t)( d - card ) - FITSNAMLEN - 1; } /* Copy the value string to the returned string. */ if( ncv == 0 ){ *v = 0; } else { strncpy( v, card + FITSNAMLEN + 1, ncv ); v[ ncv ] = ' '; v[ ncv + 1 ] = 0; } /* Find the first non-blank character in the value string. */ v0 = v; while( *v0 && isspace( (int) *v0 ) ) v0++; /* See if the value string is one of the following strings (optionally abbreviated and case insensitive): YES, NO, TRUE, FALSE. */ iopt = FullForm( "YES NO TRUE FALSE", v0, 1, status ); /* Return the single character "T" or "F" at the start of the value string if the value matches one of the above strings. */ if( iopt == 0 || iopt == 2 ) { type = AST__LOGICAL; strcpy ( v, "T" ); } else if( iopt == 1 || iopt == 3 ) { type = AST__LOGICAL; strcpy ( v, "F" ); /* If it does not match, see if the value is numerical. */ } else { /* Save the length of the value string excluding trailing blanks. */ len = ChrLen( v, status ); /* If the entire string is blank, the value type is UNDEF. */ if( len == 0 ) { type = AST__UNDEF; /* If there are no dots (decimal points) or exponents (D or E) in the value... */ } else if( !strpbrk( v, ".EeDd" ) ){ /* First attempt to read two integers from the string (separated by white space). */ if( nch = 0, ( 2 == astSscanf( v, " %d %d%n", &ir, &ii, &nch ) ) && ( nch >= len ) ) { type = AST__COMPLEXI; /* If that failed, attempt to read a single integer from the string. */ } else if( nch = 0, ( 1 == astSscanf( v, " %d%n", &ir, &nch ) ) && ( nch >= len ) ) { type = AST__INT; } /* If there are dots (decimal points) in the value... */ } else { /* First attempt to read two doubles from the string (separated by white space). */ if( nch = 0, ( 2 == astSscanf( v, " %lf %lf%n", &fr, &fi, &nch ) ) && ( nch >= len ) ) { type = AST__COMPLEXF; /* If that failed, attempt to read a single double from the string. */ } else if( nch = 0, ( 1 == astSscanf( v, " %lf%n", &fr, &nch ) ) && ( nch >= len ) ) { type = AST__FLOAT; } /* If both the above failed, it could be because the string contains a "D" exponent (which is probably valid FITS) instead of an "E" exponent. Replace any "D" in the string with "e" and try again. */ if( type == AST__COMMENT && astOK ) { /* Replace "d" and "D" by "e" (if this doesn't produce a readable floating point value then the value string will not be used, so it is safe to do the replacement in situ). */ for( i = 0; i < len; i++ ) { if( v[ i ] == 'd' || v[ i ] == 'D' ) v[ i ] = 'e'; } /* Attempt to read two doubles from the edited string (separated by white space). */ if( nch = 0, ( 2 == astSscanf( v, " %lf %lf%n", &fr, &fi, &nch ) ) && ( nch >= len ) ) { type = AST__COMPLEXF; /* If that failed, attempt to read a single double from the edited string. */ } else if( nch = 0, ( 1 == astSscanf( v, " %lf%n", &fr, &nch ) ) && ( nch >= len ) ) { type = AST__FLOAT; } } } } /* If the value type could not be determined, indicate that a warning should be issued. */ if( type == AST__COMMENT && astOK ) { badval = 1; (*value)[ 0 ] = 0; (*comment)[ 0 ] = 0; d = NULL; } } /* Find the number of characters in the comment. Pointer "d" should point to the first character following the value string. */ if( d ){ ncc = nc - (size_t)( d - card ); } else { ncc = 0; } /* Copy the remainder of the card to the returned comment string. */ if( astOK && ncc > 0 ){ strncpy( c, d, ncc ); c[ ncc ] = 0; /* Find the start of the comment (indicated by the first "/" after the value string). */ slash = strchr( c, '/' ); /* Temporarily terminate the string at the slash. */ if( slash ) *slash = 0; /* Shuffle the characters following the slash down to the start of the returned string. */ if( slash ){ ncc -= (size_t)( slash - c ) + 1; d = slash + 1; for( i = 0; i < 1 + (int) ncc; i++ ) *(c++) = *(d++); } /* If there is no comment string, return a null string. */ } else { *c = 0; } } } } /* Truncate the returned string to avoid wasting space. */ if( *name ) *name = (char *) astRealloc( (void *) *name, strlen( *name ) + 1 ); if( *comment ) *comment = (char *) astRealloc( (void *) *comment, strlen( *comment ) + 1 ); if( *value ) *value = (char *) astRealloc( (void *) *value, strlen( *value ) + 1 ); /* If the value is deemed to be integer, check that the number of digits in the formatted value does not exceed the capacity of an int. This may be the case if there are too many digits in the integer for an "int" to hold. In this case, change the data type to float. */ if( *value && type == AST__INT ) { ndig = 0; c = *value; while( *c ) { if( isdigit( *(c++) ) ) ndig++; } if( ndig >= int_dig ) type = AST__FLOAT; } /* If an error occurred, free the returned strings and issue a context message. */ if( !astOK ){ *name = (char *) astFree( (void *) *name ); *value = (char *) astFree( (void *) *value ); *comment = (char *) astFree( (void *) *comment ); type = AST__COMMENT; astError( astStatus, "%s(%s): Unable to store the following FITS " "header card:\n%.*s\n", status, method, class, AST__FITSCHAN_FITSCARDLEN, card ); /* If a bad keyword value was encountered, issue a warning. Remember that "card" may not be null terminated, so ensure that only one header is included from "card". */ } else if( badval ){ snprintf( buf, sizeof(buf), "The keyword value is illegal in " "'%.*s'", AST__FITSCHAN_FITSCARDLEN, card ); Warn( this, "badkeyvalue", buf, method, class, status ); } /* Return the data type. */ return type; } static int SplitMap( AstMapping *map, int invert, int ilon, int ilat, AstMapping **map1, AstWcsMap **map2, AstMapping **map3, int *status ){ /* * Name: * SplitMap * Purpose: * Locate a WCS projection within a Mapping. * Type: * Private function. * Synopsis: * int SplitMap( AstMapping *map, int invert, int ilon, int ilat, * AstMapping **map1, AstWcsMap **map2, AstMapping **map3, int *status ) * Class Membership: * FitsChan * Description: * If possible, the supplied Mapping is decomposed into three component * mappings to be compounded in series. To be acceptable, the second of * these three Mappings must be an inverted WcsMap with a non-zero * FITSProj attribute value, and there must not be such a WcsMap in * either of the other two Mappings. If it is not possible to produce * such a group of three Mappings, then a zero function value is returned, * together with three NULL Mapping pointers. All the mappings before the * WcsMap are compounded together and returned as "map1". The inverse of * the WcsMap itself is returned as "map2", and any remaining Mappings * are compounded together and returned as "map3". * * The search algorithm allows for an arbitrary combination of series and * parallel CmpMaps. * Parameters: * map * A pointer to the Mapping from pixel to physical coordinates. * invert * The value of the Invert attribute to use with "map" (the value * returned by astGetInvert is not used). * ilon * Index of mapping output which is connected to the longitude axis. * ilat * Index of mapping output which is connected to the latitude axis. * map1 * A location at which to return a pointer to the Mapping from pixel * to intermediate world coordinates. * map2 * A location at which to return a pointer to the Mapping from * intermediate world coordinates to native spherical coordinates. This * will be an inverted WcsMap with non-zero FITSProj attribute value. * map3 * A location at which to return a pointer to the Mapping from * native spherical coordinates to physical coordinates. * dep * The address of an integer holding the current depth of recursion * into this function. * status * Pointer to the inherited status variable. * Returned Value: * One if a suitable WcsMap was found, zero otherwise. * Notes: * - The returned Mappings contain independant copies of the relevant * components of the supplied Mapping and can be modified without * changing the supplied Mapping. * - NULL pointers will be returned for all Mappings if no WcsMap * can be found in the supplied Mapping. * - A pointer to a UnitMap will be returned for map1 if no mappings * exist before the WcsMap. * - A pointer to a UnitMap will be returned for map3 if no mappings * exist after the WcsMap. * - NULL pointers will be returned for all Mappings and a function * value of zero will be returned if an error has occurred, or if this * function should fail for any reason. */ /* Local Variables */ AstFitsChan *fc; /* Pointer to temporary FitsChan */ AstFrameSet *tfs; /* Temporary FrameSet */ AstMapping *mapa; /* Pre-wcs Mapping */ AstMapping *mapc; /* Post-wcs Mapping */ AstMapping *tmap1; /* Temporary Mapping */ AstMapping *tmap2; /* Temporary Mapping */ AstPointSet *pset1; /* Pixel positions */ AstPointSet *pset2; /* WCS positions */ AstWcsMap *mapb; /* WcsMap */ char card[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Buffer for header card */ double **ptr1; /* Pointer to pixel axis values */ double **ptr2; /* Pointer to WCS axis values */ double *iwc_origin; /* Array holding IWC at pixel origin */ double *pix_origin; /* Array holding pixel coords at pixel origin */ double *w1; /* Pointer to work space */ int i; /* Loop index */ int npix; /* Number of pixel axes */ int nwcs; /* Number of WCS axes */ int ret; /* Was a non-linear Mapping found? */ /* Initialise */ *map1 = NULL; *map2 = NULL; *map3 = NULL; ret = 0; /* Check the global status. */ if( !astOK ) return ret; /* Call SplitMap2 to do the work. SplitMap2 does not check that the WcsMap is an *inverted* WcsMap, neither does it check that there are no WcsMaps in either map1 or map3. */ if( SplitMap2( map, invert, map1, map2, map3, status ) ) { /* Check that the WcsMap is inverted. */ if( astGetInvert( *map2 ) ) { /* Check that map 1 does not contain a WcsMap with non-zero FITSProj attribute. */ if( !SplitMap2( *map1, astGetInvert( *map1 ), &mapa, &mapb, &mapc, status ) ) { /* Check that map 3 does not contain a WcsMap with non-zero FITSProj attribute. */ if( !SplitMap2( *map3, astGetInvert( *map3 ), &mapa, &mapb, &mapc, status ) ) { /* If so, the three Mappings are OK. */ ret = 1; } else { mapa = astAnnul( mapa ); mapb = astAnnul( mapb ); mapc = astAnnul( mapc ); } } else { mapa = astAnnul( mapa ); mapb = astAnnul( mapb ); mapc = astAnnul( mapc ); } } } /* If the above failed to find a suitable WcsMap, we now consider cases where the pixel->WCS mapping is linear. We can invent a CAR projection WcsMap for such cases. We use a ShiftMap to move the origin of the longitude IWC axis to a sensible value (it is left at zero otherwise). We cannot do this with the latitude axis since pre-FITS-WCS fits readers could not handle the resulting rotation from native to celestial coords. */ if( !ret && astGetIsLinear( map ) ) { nwcs = astGetNout( map ); npix = astGetNin( map ); iwc_origin = astMalloc( sizeof( double )*nwcs ); pix_origin = astMalloc( sizeof( double )*npix ); if( astOK ) { for( i = 0; i < npix; i++ ) pix_origin[ i ] = 0.0; astTranN( map, 1, npix, 1, pix_origin, 1, nwcs, 1, iwc_origin ); for( i = 0; i < nwcs; i++ ) { if( i != ilon ) { iwc_origin[ i ] = 0.0; } else { iwc_origin[ i ] *= -1; } } mapa = (AstMapping *) astShiftMap( nwcs, iwc_origin, "", status ); *map1 = (AstMapping *) astCmpMap( map, mapa, 1, "", status ); *map2 = astWcsMap( nwcs, AST__CAR, ilon + 1, ilat + 1, "Invert=1", status ); astInvert( mapa ); *map3 = astClone( mapa ); mapa = astAnnul( mapa ); ret = 1; } iwc_origin = astFree( iwc_origin ); pix_origin = astFree( pix_origin ); } /* If the above failed to find a suitable WcsMap, we now consider cases where the output (long,lat) values are constants supplied by a final PermMap. We can invent a WcsMap for such cases. */ if( !ret ) { /* Transform two arbitrary pixel positions into the WCS Frame. */ npix = astGetNin( map ); nwcs = astGetNout( map ); pset1 = astPointSet( 2, npix, "", status ); pset2 = astPointSet( 2, nwcs, "", status ); ptr1 = astGetPoints( pset1 ); ptr2 = astGetPoints( pset2 ); w1 = astMalloc( sizeof( double )*(size_t) nwcs ); if( astOK ) { for( i = 0; i < npix; i++ ) { ptr1[ i ][ 0 ] = 1.0; ptr1[ i ][ 1 ] = 1000.0; } (void) astTransform( map, pset1, 1, pset2 ); /* If the two wcs positions have equal longitude and latitude values, assume that the output longitude and latitude axes are assigned constant values by the Mapping. */ if( ptr2[ ilon ][ 0 ] == ptr2[ ilon ][ 1 ] && ptr2[ ilon ][ 0 ] != AST__BAD && ptr2[ ilat ][ 0 ] == ptr2[ ilat ][ 1 ] && ptr2[ ilat ][ 0 ] != AST__BAD ) { /* Create a set of Mappings to return, including a WcsMap, which result in these constant latitude and longitude values. We do this by creating a FITS-WCS header and reading the FrameSet from it. Keywords which are not important to the final mappings are given arbitrary values. */ fc = astFitsChan( NULL, NULL, "", status ); for( i = 0; i < nwcs; i++ ) { sprintf( card, "CRPIX%d = 0", i + 1 ); astPutFits( fc, card, 0 ); sprintf( card, "CDELT%d = 0.0003", i + 1 ); astPutFits( fc, card, 0 ); if( i == ilon ) { sprintf( card, "CTYPE%d = 'RA---TAN'", i + 1 ); } else if( i == ilat ) { sprintf( card, "CTYPE%d = 'DEC--TAN'", i + 1 ); } else { sprintf( card, "CTYPE%d = 'DUMMY'", i + 1 ); } astPutFits( fc, card, 0 ); if( i == ilon ) { sprintf( card, "CRVAL%d = %.*g", i + 1, DBL_DIG, AST__DR2D*ptr2[ ilon ][ 0 ] ); } else if( i == ilat ) { sprintf( card, "CRVAL%d = %.*g", i + 1, DBL_DIG, AST__DR2D*ptr2[ ilat ][ 0 ] ); } else { sprintf( card, "CRVAL%d = 0.0", i + 1 ); } astPutFits( fc, card, 0 ); } astClearCard( fc ); tfs = astRead( fc ); if( tfs ) { /* Use SplitMap to get the required Mapings from the FrameSet. */ tmap2 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); SplitMap( tmap2, astGetInvert( tmap2 ), 0, 1, &tmap1, map2, map3, status ); tmap1 = astAnnul( tmap1 ); tmap2 = astAnnul( tmap2 ); /* Create a ShiftMap which subtract the constant longitude and latitude values off the inputs. */ for( i = 0; i < nwcs; i++ ) w1[ i ] = 0.0; w1[ ilon ] = -ptr2[ ilon ][ 0 ]; w1[ ilat ] = -ptr2[ ilat ][ 0 ]; tmap1 = (AstMapping *) astShiftMap( nwcs, w1, "", status ); /* Compose this with the supplied Mapping. This results in the celestial outputs being zero. This gives the required "map1". */ *map1 = (AstMapping *) astCmpMap( map, tmap1, 1, "", status ); /* Indicate success.*/ ret = 1; /* Free resources. */ tmap1 = astAnnul( tmap1 ); tfs = astAnnul( tfs ); } fc = astAnnul( fc ); } } /* Free resources */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); w1 = astFree( w1 ); } if( !ret ) { if( *map1 ) *map1 = astAnnul( *map1 ); if( *map2 ) *map2 = astAnnul( *map2 ); if( *map3 ) *map3 = astAnnul( *map3 ); } return ret; } static int SplitMap2( AstMapping *map, int invert, AstMapping **map1, AstWcsMap **map2, AstMapping **map3, int *status ){ /* * Name: * SplitMap2 * Purpose: * Locate a WCS projection within a Mapping. * Type: * Private function. * Synopsis: * int SplitMap2( AstMapping *map, int invert, AstMapping **map1, * AstWcsMap **map2, AstMapping **map3, int *status ) * Class Membership: * FitsChan * Description: * If possible, the supplied Mapping is decomposed into three component * mappings to be compounded in series. To be acceptable, the second of * these three Mappings must be a WcsMap with a non-zero FITSProj value. * If it is not possible to produce such a group of three Mappings, then a * zero function value is returned, together with three NULL Mapping * pointers. All the mappings before the WcsMap are compounded together * and returned as "map1". The WcsMap itself is returned as "map2", and * any remaining Mappings are compounded together and returned as "map3". * * The search algorithm allows for an arbitrary combination of series and * parallel CmpMaps. * Parameters: * map * A pointer to the Mapping from pixel to physical coordinates. * invert * The value of the Invert attribute to use with "map" (the value * returned by astGetInvert is not used). * map1 * A location at which to return a pointer to the Mapping from pixel * to intermediate world coordinates. * map2 * A location at which to return a pointer to the Mapping from relative * physical coordinates to native spherical coordinates. This will * be a WcsMap, and it will have a non-zero FITSProj value. * map3 * A location at which to return a pointer to the Mapping from * native spherical coordinates to physical coordinates. * dep * The address of an integer holding the current depth of recursion * into this function. * status * Pointer to the inherited status variable. * Returned Value: * One if a suitable WcsMap was found, zero otherwise. * Notes: * - The returned Mappings contain independant copies of the relevant * components of the supplied Mapping and can be modified without * changing the supplied Mapping. * - NULL pointers will be returned for all Mappings if no WcsMap * with anon-zero FITSProj value can be found in the supplied Mapping. * - A pointer to a UnitMap will be returned for map1 if no mappings * exist before the WcsMap. * - A pointer to a UnitMap will be returned for map3 if no mappings * exist after the WcsMap. * - NULL pointers will be returned for all Mappings and a function * value of zero will be returned if an error has occurred, or if this * function should fail for any reason. * - "*map1" and "*map3" may contain WcsMaps, but they will have zero * values for their FITSProj values. */ /* Local Variables */ AstMapping **map_list; /* Mapping array pointer */ AstMapping *mapa; /* Pre-wcs Mapping */ AstWcsMap *mapb; /* WcsMap */ AstMapping *mapc; /* Post-wcs Mapping */ AstMapping *temp; /* Intermediate Mapping */ const char *class; /* Pointer to class of supplied Mapping */ double pv; /* Projection parameter value */ int *invert_list; /* Invert array pointer */ int axis; /* No. of axes in whole Mapping */ int axlat; /* Index of latitude axis */ int axlon; /* Index of longitude axis */ int haswcs; /* Was a usable inverted WcsMap found? */ int imap; /* Index of current Mapping in list */ int i; /* axis index */ int m; /* Parameter index */ int nax; /* No. of axes in Mapping */ int nmap; /* Number of Mappings in the list */ int ret; /* Was a non-linear Mapping found? */ int wcsaxis; /* Index of first WcsMap axis */ /* Initialise */ *map1 = NULL; *map2 = NULL; *map3 = NULL; ret = 0; /* Check the global status. */ if( !astOK ) return ret; /* Get the class of the Mapping. */ class = astGetClass( map ); /* If the supplied Mapping is a CmpMap... */ wcsaxis = -1; if( !strcmp( class, "CmpMap" ) ){ /* Decompose the Mapping into a sequence of Mappings to be applied in series and an associated list of Invert flags. */ map_list = NULL; invert_list = NULL; nmap = 0; astMapList( map, 1, invert, &nmap, &map_list, &invert_list ); /* If there is more than one Mapping, this must be a series CmpMap. */ if( nmap > 1 && astOK ){ /* Initialise the returned pre-wcs Mapping to be a UnitMap. */ if( invert == astGetInvert( map ) ){ *map1 = (AstMapping *) astUnitMap( astGetNin( map ), "", status ); } else { *map1 = (AstMapping *) astUnitMap( astGetNout( map ), "", status ); } /* Indicate we have not yet found a WcsMap. */ ret = 0; /* Process each series Mapping. */ for( imap = 0; imap < nmap; imap++ ){ /* If we have not yet found a WcsMap... */ if( !ret ){ /* Search this Mapping for a WcsMap. */ ret = SplitMap2( map_list[ imap ], invert_list[ imap ], &mapa, map2, map3, status ); /* If no WcsMap was found, use the whole mapping as part of the pre-wcs Mapping. */ if( !ret ){ mapa = astCopy( map_list[ imap ] ); astSetInvert( mapa, invert_list[ imap ] ); } /* Add the pre-wcs mapping to the cumulative pre-wcs CmpMap. */ temp = (AstMapping *) astCmpMap( *map1, mapa, 1, "", status ); *map1 = astAnnul( *map1 ); mapa = astAnnul( mapa ); *map1 = temp; /* If we have previously found a WcsMap, use the whole mapping as part of the post-wcs mapping. */ } else { mapc = astCopy( map_list[ imap ] ); astSetInvert( mapc, invert_list[ imap ] ); temp = (AstMapping *) astCmpMap( *map3, mapc, 1, "", status ); *map3 = astAnnul( *map3 ); mapc = astAnnul( mapc ); *map3 = temp; } } /* If there is only one Mapping, this must be a parallel CmpMap. */ } else { /* Annul the Mapping pointer in the series list created above, and free the dynamic arrays. */ map_list[ 0 ] = astAnnul( map_list[ 0 ] ); map_list = astFree( map_list ); invert_list = astFree( invert_list ); nmap = 0; /* Decompose the Mapping into a sequence of Mappings to be applied in parallel and an associated list of Invert flags. */ astMapList( map, 0, invert, &nmap, &map_list, &invert_list ); /* Process each parallel Mapping. */ axis = 0; for( imap = 0; imap < nmap && astOK; imap++ ){ /* See if this Mapping contains a usable WcsMap. Only do the search if no such WcsMap has already been found, since only the first is usable. */ if( !ret ) { /* Search this Mapping for a WcsMap. */ haswcs = SplitMap2( map_list[ imap ], invert_list[ imap ], &mapa, &mapb, &mapc, status ); /* Note if we have found a usable WcsMap, and its first axis index. */ if( haswcs ){ ret = 1; wcsaxis = axis; } /* If a WcsMap has already been found, the mapping cannot contain a usable WcsMap. */ } else { haswcs = 0; } /* If the Mapping did not contain a usable WcsMap, use the whole mapping as part of the pre-wcs Mapping, and create a UnitMap as part of the post-wcs mapping. */ if( !haswcs ){ mapa = astCopy( map_list[ imap ] ); astSetInvert( mapa, invert_list[ imap ] ); nax = astGetNout( mapa ); mapc = (AstMapping *) astUnitMap( nax, "", status ); } /* Increment the index of the first axis in the next Mapping. */ axis += astGetNout( mapa ); /* Add the pre-wcs mapping in parallel with the cumulative pre-wcs CmpMap. */ if( *map1 ){ temp = (AstMapping *) astCmpMap( *map1, mapa, 0, "", status ); *map1 = astAnnul( *map1 ); mapa = astAnnul( mapa ); *map1 = temp; } else { *map1 = mapa; } /* Add the post-wcs mapping in parallel with the cumulative post-wcs CmpMap. */ if( *map3 ){ temp = (AstMapping *) astCmpMap( *map3, mapc, 0, "", status ); *map3 = astAnnul( *map3 ); mapc = astAnnul( mapc ); *map3 = temp; } else { *map3 = mapc; } } /* If a usable WcsMap was found, create a new one which has all the same properties, but with enough axes to join the pre and post wcs Mappings together. Ensure the correct axes are used for longitude and latitude, and copy the projection parameters. */ if( ret ){ axlat = astGetWcsAxis( mapb, 1 ); axlon = astGetWcsAxis( mapb, 0 ); *map2 = astWcsMap( axis, astGetWcsType( mapb ), axlon + wcsaxis + 1, axlat + wcsaxis + 1, "", status ); for( i = 0; i < astGetNin( mapb ); i++ ){ for( m = 0; m < WCSLIB_MXPAR; m++ ){ if( astTestPV( mapb, i, m ) ) { pv = astGetPV( mapb, i, m ); if( pv != AST__BAD ) astSetPV( *map2, i + wcsaxis, m, pv ); } } } astInvert( *map2 ); mapb = astAnnul( mapb ); } } /* Loop to annul all the Mapping pointers in the list. */ for ( imap = 0; imap < nmap; imap++ ) map_list[ imap ] = astAnnul( map_list[ imap ] ); /* Free the dynamic arrays. */ map_list = astFree( map_list ); invert_list = astFree( invert_list ); /* If the supplied Mapping is not a CmpMap, see if it is a WcsMap with a non-zero FITSProj value. If so, take a copy and set its invert attribute correctly. Also create UnitMaps for the pre and post wcs mappings. */ } else if( astOK && !strcmp( class, "WcsMap" ) && astGetFITSProj( map ) ){ ret = 1; nax = astGetNin( map ); *map1 = (AstMapping *) astUnitMap( nax, "", status ); *map2 = astCopy( map ); astSetInvert( *map2, invert ); *map3 = (AstMapping *) astUnitMap( nax, "", status ); } /* If an error has occurred, or if no suitable WcsMap was found, annul any Mappings. */ if( !astOK || !ret ){ ret = 0; if( *map1 ) *map1 = astAnnul( *map1 ); if( *map2 ) *map2 = astAnnul( *map2 ); if( *map3 ) *map3 = astAnnul( *map3 ); } /* Return the answer. */ return ret; } static int SplitMat( int naxis, double *matrix, double *cdelt, int *status ){ /* * Name: * SplitMat * Purpose: * Factorises a single "CD"-style matrix into a diagonal CDELT matrix * and a "PC"-style matrix. * Type: * Private function. * Synopsis: * int SplitMat( int naxis, double *matrix, double *cdelt, int *status ) * Class Membership: * FitsChan * Description: * This function splits up the supplied CD matrix into separate PC and * CDELT matrices. The product of the returned matrices (CDELT.PC) * equals the supplied CD matrix. The CDELT values are chosen so that * the corresponding row of the PC matrix represents a unit vector. * The signs of the CDELT values are chosen so that the diagonal terms * of the PC matrix are all positive. * * Parameters: * naxis * The number of axes. * matrix * A pointer to an array of naxis*naxis elements. On entry this holds * the "CD" matrix. On exit, it is modified to represent the "PC" * matrix. * cdelt * A pointer to an array of naxis elements. On exit this holds the CDELT * values for each axis (i.e. the diagonal terms of the CDELT matrix). * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if any bad values are found in the supplied * matrix, or if an error has already occurred. One is returned otherwise. */ /* Local Variables: */ int i; int j; int ok; double *a; int dineg; double s2; double cdlt; /* Check the inherited status. */ if( !astOK ) return 0; /* Assume success. */ ok = 1; /* Loop round every row in the matrix. Get a pointer to the first element in the row. */ for( i = 0; i < naxis; i++ ){ a = matrix + i*naxis; /* Note the sign of the diagonal term (i.e. the i'th element) of this row. */ dineg = ( a[ i ] < 0.0 ); /* Get the magnitude of the vector represented by this row. This is the CDELT value for the row. BAD values cause the whole function to return. */ s2 = 0.0; for( j = 0; j < naxis; j++ ){ if( *a == AST__BAD ) { ok = 0; break; } s2 += (*a)*(*a); a++; } if( !ok ) break; cdlt = sqrt( astMAX( 0.0, s2 ) ); /* If the diagonal term for this row of the matrix is negative, make the CDELT value negative instead. This means that the diagonal term in the final PC matrix will be positive. */ if( dineg ) cdlt = -cdlt; /* Store the CDELT value. */ cdelt[ i ] = cdlt; /* The row of the PC matrix is obtained by dividing the original row by the CDELT value. Set to zero any PC values which are less than 1.0E-7 (such values may be produced by rounding errors). */ a = matrix + i*naxis; for( j = 0; j < naxis; j++ ) { if( cdlt != 0.0 ){ *a /= cdlt; if( fabs( *a ) < 1.E-7 ) *a = 0.0; } else { *a = 0.0; } a++; } } return ok; } static void TableSource( AstFitsChan *this, void (* tabsource)( AstFitsChan *, const char *, int, int, int * ), int *status ){ /* *++ * Name: c astTableSource f AST_TABLESOURCE * Purpose: c Register a source function for accessing tables in FITS files. f Register a source routine for accessing tables in FITS files. * Type: * Public function. * Synopsis: c #include "fitschan.h" c void astTableSource( AstFitsChan *this, c void (* tabsource)( AstFitsChan *, const char *, c int, int, int * ) ) f CALL AST_TABLESOURCE( THIS, TABSOURCE, STATUS ) * Class Membership: * FitsChan member function. * Description: c This function can be used to register a call-back function f This routine can be used to register a call-back routine * with a FitsChan. The registered c function f routine * is called when-ever the FitsChan needs to read information from a * binary table contained within a FITS file. This occurs if the c astRead f AST_READ * function is invoked to read a FrameSet from a set of FITS headers * that use the "-TAB" algorithm to describe one or more axes. Such * axes use a FITS binary table to store a look-up table of axis values. * The FitsChan will fail to read such axes unless the "TabOK" attribute * is set to a non-zero positive integer value. The table containing the * axis values must be made available to the FitsChan either by storing * the table contents in the FitsChan (using c astPutTables or astPutTable) prior to invoking astRead f AST_PUTTABLES or AST_PUTTABLE) prior to invoking AST_READ * or by registering a call-back c function using astTableSource. f routine using AST_TABLESOURCE. * The first method is possibly simpler, but requires that the name of * the extension containing the table be known in advance. Since the * table name is embedded in the FITS headers, the name is often not * known in advance. If a call-back is registered, the FitsChan will * determine the name of the required table and invoke the call-back c function f routine * to supply the table at the point where it is needed (i.e. within c the astRead method). f the AST_READ method). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c tabsource f TABSOURCE = SUBROUTINE (Given) c Pointer to the table source function to use. f The table source routine to use. * It takes five arguments - the first is a pointer to the * FitsChan, the second is a string holding the name of the * FITS extension containing the required binary table ("EXTNAME"), * the third is the integer FITS "EXTVER" header value for the * required extension, the fourth is the integer FITS "EXTLEVEL" * header value for the required extension, and the fifth is c a pointer to * the inherited integer status value. * * The call-back should read the entire contents (header and data) * of the binary table in the named extension of the external FITS * file, storing the contents in a newly created FitsTable object. It * should then store this FitsTable in the FitsChan using the c astPutTables or astPutTable f AST_PUTTABLES or AST_PUTTABLE * method, and finally annull its local copy of the FitsTable pointer. * If the table cannot be read for any reason, or if any other * error occurs, it should return a non-zero integer for the final * (third) argument. * c If "tabsource" is NULL, f If TABSOURCE is AST_NULL, * any registered call-back function will be removed. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - Application code can pass arbitrary data (such as file c descriptors, etc) to the table source function using the c astPutChannelData function. The source function should use c the astChannelData macro to retrieve this data. f - The name of the routine supplied for the TABSOURCE f argument should appear in an EXTERNAL statement in the Fortran f routine which invokes AST_TABLESOURCE. However, this is not generally f necessary for the null routine AST_NULL (so long as the AST_PAR f include file has been used). f - Note that the null routine AST_NULL (one underscore) is f different to AST__NULL (two underscores), which is the null Object f pointer. *-- */ /* Check the global error status. */ if ( !astOK ) return; /* Register the supplied source function, using the wrapper function appropriate for calling C table source functions. */ astSetTableSource( this, (void (*)( void )) tabsource, TabSourceWrap ); } static AstMapping *TabMapping( AstFitsChan *this, FitsStore *store, char s, int **tabaxis, const char *method, const char *class, int *status ) { /* * Name: * TabMapping * Purpose: * Create a Mapping that performs any -TAB look-ups for all WCS axes. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstMapping *TabMapping( AstFitsChan *this, FitsStore *store, char s, * int **tabaxis, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * This function returns a Mapping that has "nwcs" inputs and outputs, * where "nwcs" is the number of FITS WCS axes defined in the supplied * FitsStore. The inputs and outputs are in the same order as the * CTYPEi keywords in the FitsStore. The forward transformation of the * Mapping converts positions from the axes defined by the CRVALi keywords * to the WCS axes. This transformation will be a UnitMap except for * any axes that are described using the "-TAB" algorithm. For "-TAB" * axes, the transformation will implement the relevant coordinate * look-up function. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore structure holding the values to use for * the WCS keywords. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * tabaxis * Address of a location at which to store a pointer to an array of * flags, one for each output of the returned Mapping. A flag will * be non-zero if the corresponding output of the returned Mapping * corresponds to a -TAB axis. A NULL pointer is returned if the * returned Mapping is NULL. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a Mapping. A NULL pointer is returned if the FitsChan does * not support the -TAB algorithm (i.e. if the value of the TabOK * attribute is zero or negative), or if no axes use the "-TAB" algorithm. */ /* Local Variables: */ AstFitsTable *table; AstKeyMap *used_tables; AstMapping *tmap1; AstMapping *tmap2; AstMapping *indexmap; AstMapping *tmap0; AstMapping *ret; AstPermMap *pm; char name[21]; const char *indexcol; const char *extname; const char *cval; const char *ctype; const char *coordscol; double dval; int *marray; int *permin; int *permout; int extlevel; int extver; int iaxis; int iiaxis; int ikey; int interp; int ival; int maxis; int mdim; int nkey; int nperm; int unit; int wcsaxes; /* Initialise */ ret = NULL; *tabaxis = NULL; extname = NULL; tmap0 = NULL; tmap2 = NULL; /* Check the global status. */ if( !astOK ) return ret; /* Obtain the number of physical axes in the header. If the WCSAXES header was specified, use it. Otherwise assume it is the same as the number of pixel axes. */ dval = GetItem( &(store->wcsaxes), 0, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) { wcsaxes = (int) dval + 0.5; } else { wcsaxes = store->naxis; } /* If the FitsChan does not support the -TAB algorithm, return a NULL pointer. */ if( astGetTabOK( this ) > 0 ) { /* Create a KeyMap to hold a list of the used extension names. */ used_tables = astKeyMap( " ", status ); /* Allocate memory to indicate if each WCS axis is described by a -TAB algorithm or not. Initialiss it to zero. */ *tabaxis = astCalloc( wcsaxes, sizeof( int ) ); /* Allocate memory to hold the FITS-WCS axis index corresponding to each input of the "tmap0" Mapping. Indicate that as yet, not values are stored in this array. Also allocate memory for the inverse of this permutation array. */ permout = astMalloc( wcsaxes*sizeof( int ) ); permin = astMalloc( wcsaxes*sizeof( int ) ); nperm = 0; if( astOK ) { /* Initialise the permutation arrays. */ for( iaxis = 0; iaxis < wcsaxes; iaxis++ ) { permout[ iaxis ] = permin[ iaxis ] = -1; } /* Otherwise, loop round all FITS WCS axis indices present in the FitsStore. */ for( iaxis = 0; iaxis < wcsaxes; iaxis++ ) { /* If the current FITS WCS axis is already included in the returned Mapping, skip it. This will be the case if the axis uses the same coordinate array as an earlier axis since all FITS WCS axes associated with a coordinate array are processed together. */ if( permin[ iaxis ] == -1 ) { /* See if this WCS axis uses the -TAB algorithm. */ ctype = GetItemC( &(store->ctype), iaxis, 0, s, NULL, method, class, status ); if( ctype && strlen(ctype) > 4 && !strncmp( ctype + 4, "-TAB", 4 ) ) { /* Get the name of the FITS binary table extension holding the coordinate info. No default, so report an error if not present. */ sprintf( name, "PS%d_0%c", iaxis + 1, s ); extname = GetItemC( &(store->ps), iaxis, 0, s, name, method, class, status ); /* Get the extension version and level. */ dval = GetItem( &(store->pv), iaxis, 1, s, NULL, method, class, status ); extver = ( dval != AST__BAD ) ? (int) dval : 1; dval = GetItem( &(store->pv), iaxis, 2, s, NULL, method, class, status ); extlevel = ( dval != AST__BAD ) ? (int) dval : 1; /* Get the FITS binary table. This will invoke any supplied table source function, and put a copy of the table into the FitsChan structure. Report an error if the table can not be obtained. */ table = GetNamedTable( this, extname, extver, extlevel, 1, method, status ); /* Add this extension name to a list of used extensions. */ astMapPut0I( used_tables, extname, 1, NULL ); /* Get the name of the table column containing the main coords array. No default so report error if not present. Report an error if the column is not present in the table. */ sprintf( name, "PS%d_1%c", iaxis + 1, s ); coordscol = GetItemC( &(store->ps), iaxis, 1, s, name, method, class, status ); if( !astHasColumn( table, coordscol ) && astOK ) { astError( AST__BADTAB, "%s(%s): Unable to find the " "coordinate array for FITS-WCS axis %d (type %s): " "column '%s' cannot be found in table '%s'.", status, method, class, iaxis + 1, ctype, coordscol, extname ); } /* Get the number of dimensions spanned by the coordinate array. Report an error if the coordinate array has only one axis (FITS-WCS paper III requires it to have at leats two axes). */ mdim = astGetColumnNdim( table, coordscol ); if( mdim == 1 && astOK ) { astError( AST__BADTAB, "%s(%s): Unable to use the " "coordinate array for FITS-WCS axis %d (type %s): " "column '%s' in table '%s' has one axis but at " "least two are required.", status, method, class, iaxis + 1, ctype, coordscol, extname ); } /* Allocate memory to hold the FITS-WCS axis corresponding to each dimension of the coordinate array. Initialise it to hold -1 (i.e. "no matching FITS-WCS axis yet found") at every element. */ marray = astMalloc( mdim*sizeof( int ) ); if( astOK ) { for( maxis = 0; maxis < mdim; maxis++ ) { marray[ maxis ] = -1; } /* Loop round each dimension of the coordinate array, storing the index of the corresponding FITS-WCS axis in "marray". We omit the first axis (axis 0) since FITS-WCS Paper III defines it is a "conventional" axis used to enumerate the planes of coordinate values. */ for( maxis = 1; maxis < mdim && astOK ; maxis++ ) { /* Each axis of the coordinate array (except axis 0) must have one, and only one, corresponding FITS-WCS axis. Check each FITS-WCS axis to find one that uses the same table and column as the "iaxis" axis, and which corresponds to axis "maxis" of the coordinate array. */ for( iiaxis = 0; iiaxis < wcsaxes; iiaxis++ ) { cval = GetItemC( &(store->ps), iiaxis, 0, s, NULL, method, class, status ); if( cval && !strcmp( cval, extname ) ) { cval= GetItemC( &(store->ps), iiaxis, 1, s, NULL, method, class, status ); if( cval && !strcmp( cval, coordscol ) ) { dval = GetItem( &(store->pv), iiaxis, 3, s, NULL, method, class, status ); if( dval != AST__BAD ) { ival = (int)( dval + 0.5 ); } else { ival = 1; } if( ival == maxis ) { /* Arrive here if the "iiaxis" FITS-WCS axis uses the same table and column as "iaxis", and corresponds to the "maxis" axis in the coordinate array. If this is the first matching FITS-WCS axis, store its index. */ if( marray[ maxis ] == -1 ) { marray[ maxis ] = iiaxis; /* If a matching FITS-WCS axis has already been found, report an error. */ } else if( astOK ) { astError( AST__BADTAB, "%s(%s): Unable to use " "the coordinate array for FITS-WCS " "axis %d (type %s): more than one " "intermediate WCS axis is mapped onto " " dimension %d of the coordinate " "array in column '%s' of table '%s'.", status, method, class, iaxis + 1, ctype, maxis, coordscol, extname ); } } } } } } /* Check that every dimension of the coordinate array (except the first) has a corresponding FITS-WCS axis. */ for( maxis = 1; maxis < mdim && astOK ; maxis++ ) { if( marray[ maxis ] == -1 ) { astError( AST__BADTAB, "%s(%s): Unable to use the " "coordinate array for FITS-WCS axis %d (type " "%s): no intermediate WCS axis is mapped onto " " dimension %d of the coordinate array in column " " '%s' of table '%s'.", status, method, class, iaxis + 1, ctype, maxis, coordscol, extname ); } } /* Now we know which FITS-WCS axis corresponds to each dimension of the coordinate array. We now need to form a parallel CmpMap (compound Mapping) by gathering together the indexing vectors for each dimension of the coordinates array. Each indexing vector is represented by an inverted 1D LutMap - dimensions that do not have an indexing vector are represented using a UnitMap. */ indexmap = NULL; unit = 1; for( maxis = 1; maxis < mdim && astOK ; maxis++ ) { /* Get the name of the column containing the index array. Defaults is to use a unit index, so do not report an error if not present. */ indexcol = GetItemC( &(store->ps), marray[ maxis ], 2, s, NULL, method, class, status ); /* If the table contains an index vector, create a LutMap from it, then invert it. */ if( indexcol ) { tmap1 = MakeColumnMap( table, indexcol, 1, 0, method, class, status ); astInvert( tmap1 ); unit = 0; /* If the table does not contain an index vector, use a UnitMap. */ } else { tmap1 = (AstMapping *) astUnitMap( 1, " ", status ); } /* Combine the index Mapping for this dimension in parallel with the Mapping for all earlier dimensions. */ if( indexmap ) { tmap2 = (AstMapping *) astCmpMap( indexmap, tmap1, 0, " ", status ); indexmap = astAnnul( indexmap ); tmap1 = astAnnul( tmap1 ); indexmap = tmap2; } else { indexmap = tmap1; } } /* Get the interpolation method to use for the main coordinate array. This is an extension to the published -TAB algorithm in which the QVi_4a keyword is assumed to hold zero for linear interpolation (the default) and non-zero for nearest neighbour interpolation. The QVi_4a keyword will be translated to PVi_4a by the SpecTrans function. */ dval = GetItem( &(store->pv), iaxis, 4, s, NULL, method, class, status ); if( dval != AST__BAD ) { interp = (int)( dval + 0.5 ); } else { interp = 0; } /* Make a Mapping from the main coordinate array, and then if required append it in series to the end of the index Mapping created above. */ tmap1 = MakeColumnMap( table, coordscol, 0, interp, method, class, status ); if( ! unit ) { tmap2 = (AstMapping *) astCmpMap( indexmap, tmap1, 1, " ", status ); } else { tmap2 = astClone( tmap1 ); } indexmap = astAnnul( indexmap ); tmap1 = astAnnul( tmap1 ); /* Extend the array that holds the zero-based FITS-WCS axis index corresponding to each input of the extended "tmap0" mapping. Also create the inverse permutation (i.e. zero-based "tmap0" input indexed by zero-based FITS-WCS axis index). */ for( maxis = 1; maxis < mdim; maxis++ ) { permout[ nperm ] = marray[ maxis ]; permin[ marray[ maxis ] ] = nperm++; } /* Free resources. */ marray = astFree( marray ); } /* Annul the table pointer. */ table = astAnnul( table ); /* Clear the CTYPE algorithm code to indicate that the axis should be considered to be linear from now on. This means that the following functions will create a Mapping from pixel to psi (the system in which the CRVAL values are defined when using -TAB). The psi axes will then be mapping into the CS axes using the Mappign returned by this function. */ strncpy( name, ctype, 4 ); strcpy( name + 4, ctype + 8 ); SetItemC( &(store->ctype), iaxis, 0, s, name, status ); /* Set the returned flag for this axis. */ (*tabaxis)[ iaxis ] = 1; /* If the FITS WCS axis "iaxis" does not use a -TAB algorithm, describe it in the returned Mapping using a 1D UnitMap. */ } else { tmap2 = (AstMapping *) astUnitMap( 1, " ", status ); /* Extend the array that holds the zero-based FITS-WCS axis index corresponding to each input of the extended "tmap0" mapping. Also create the inverse permutation (i.e. zero-based "tmap0" input indexed by zero-based FITS-WCS axis index). */ permout[ nperm ] = iaxis; permin[ iaxis ] = nperm++; } /* Append the Mapping describing the FITS WCS axis "iaxis" in parallel to any Mappings created for earlier "iaxis" axes. */ if( tmap0 ) { tmap1 = (AstMapping *) astCmpMap( tmap0, tmap2, 0, " ", status ); tmap0 = astAnnul( tmap0 ); tmap2 = astAnnul( tmap2 ); tmap0 = tmap1; } else { tmap0 = tmap2; } } } /* If no -TAB axes were found, just return a NULL pointer. */ if( extname && astOK ) { /* Do a sanity check on the permutation arrays. */ for( iaxis = 0; iaxis < wcsaxes; iaxis++ ) { if( permin[ iaxis ] < 0 || permin[ iaxis ] >= wcsaxes || permout[ permin[ iaxis ] ] != iaxis ) { astError( AST__INTER, "%s(%s): Invalid permutation " "arrays in function TabMapping (internal AST " "progranmming error).", status, method, class ); break; } } /* Sandwich the "tmap0" Mapping in series between two PermMaps to create a Mapping in which the inputs and outputs correspond to FITS WCS axis numbering. */ pm = astPermMap( wcsaxes, permin, wcsaxes, permout, NULL, " ", status ); tmap1 = (AstMapping *) astCmpMap( pm, tmap0, 1, " ", status ); astInvert( pm ); tmap2 = (AstMapping *) astCmpMap( tmap1, pm, 1, " ", status ); pm = astAnnul( pm ); tmap1 = astAnnul( tmap1 ); /* Simplify the returned Mapping. */ ret = astSimplify( tmap2 ); tmap2 = astAnnul( tmap2 ); } /* Free remaining resources */ tmap0 = astAnnul( tmap0 ); } permout = astFree( permout ); permin = astFree( permin ); /* Remove all used tables from the FitsChan now that they have been used. */ nkey = astMapSize( used_tables ); for( ikey = 0; ikey < nkey; ikey++ ) { astRemoveTables( this, astMapKey( used_tables, ikey ) ); } /* Delete the KeyMap holding the used table names. */ used_tables = astAnnul( used_tables ); /* If we are not returning a Mapping, ensure we do not return any axis flags either. */ if( !ret ) *tabaxis = astFree( *tabaxis ); } /* Return the result */ return ret; } static void TabSourceWrap( void (*tabsource)( void ), AstFitsChan *this, const char *extname, int extver, int extlevel, int *status ){ /* * Name: * TabSourceWrap * Purpose: * Wrapper function to invoke the C table source function. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void TabSourceWrap( void (*tabsource)( void ), * AstFitsChan *this, const char *extname, * int extver, int extlevel, int *status ) * Class Membership: * Channel member function. * Description: * This function invokes the table source function whose pointer is * supplied in order to read a named FITS binary table from an external * FITS file. * Parameters: * tabsource * Pointer to the C tab source function. * this * Pointer to the FitsChan. The reference count for the FitsChan is * decremented by this function (this behaviour is imposed by * restrictions in the equivalent Fortran wrapper function). * extname * Pointer to the string holding the name of the FITS extension * from which a table is to be read. * extver * The integer "EXTVER" value for the required extension. * extlevel * The integer "EXTLEVEL" value for the required extension. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFitsChan *this_id; int lstat; /* Check the global error status. */ if ( !astOK ) return; /* Get an external identifier for the FitsChan. Could use astClone here to avoid this function anulling the supplied pointer, but the F77 wrapper cannot use the protected version of astClone, so for consistency we do not use it here either. */ this_id = astMakeId( this ); /* Invoke the table source function (casting it to the C API first) to read the table, and store it in the FitsChan. */ ( *( void (*)( struct AstFitsChan *, const char *, int, int, int * ) )tabsource )( this_id, extname, extver, extlevel, &lstat ); /* Free the FitsChan identifier (this annuls the supplied "this" pointer). */ this_id = astAnnulId( this_id ); /* Report an error if the source function failed. */ if( !lstat ) { astError( AST__NOTAB, "astRead(%s): The table source function failed to read " "a binary table from extension %s in an external FITS file.", status, astGetClass( this ), extname ); } } static double TDBConv( double mjd, int timescale, int fromTDB, const char *method, const char *class, int *status ){ /* * Name: * TDBConv * Purpose: * Convert an MJD between the TDB time scale and another timescale. * Type: * Private function. * Synopsis: * double TDBConv( double mjd, int timescale, int fromTDB, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function converts the supplied mjd value to or from the TDB * timescale. * Parameters: * mjd * The input MJD value. * timescale * The other timescale. * fromTDB * Indicates the direction of the required conversion. If non-zero, * the supplied "mjd" value should be in the TDB timescale, and the * returned value will be in the timescale specified by "timescale". * If zero, the supplied "mjd" value should be in the timescale * specified by "timescale", and the returned value will be in the * TDB timescale. * method * The calling method. Used only in error messages. * class * The object class. Used only in error messages. * status * Pointer to the inherited status variable. * Returned Value: * The converted MJD value, or AST__BAD if an error occurs. */ /* Local Variables: */ AstFrameSet *fs; /* Mapping from supplied timescale to TDB */ double ret; /* The returned value */ /* Initialise */ ret = AST__BAD; /* Check inherited status and supplied TDB value. */ if( !astOK || mjd == AST__BAD ) return ret; /* Return the supplied value if no conversion is needed. */ if( timescale == AST__TDB ) { ret = mjd; /* Otherwise, do the conversion. */ } else { /* Lock the timeframes for use by the current thread, waiting if they are currently locked by another thread. */ astManageLock( timeframe, AST__LOCK, 1, NULL ); astManageLock( tdbframe, AST__LOCK, 1, NULL ); /* Set the required timescale. */ astSetTimeScale( timeframe, timescale ); /* Get the Mapping between the two timescales, and use it to convert the suipplied value. */ fs = astConvert( tdbframe, timeframe, "" ); astTran1( fs, 1, &mjd, fromTDB, &ret ); fs = astAnnul( fs ); /* Unlock the timeframes. */ astManageLock( timeframe, AST__UNLOCK, 1, NULL ); astManageLock( tdbframe, AST__UNLOCK, 1, NULL ); } /* Return the result */ return ret; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * FitsChan member function (over-rides the astTestAttrib protected * method inherited from the Channel class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a FitsChan's attributes. * Parameters: * this * Pointer to the FitsChan. * 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: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_object; /* Card. */ /* ----- */ if ( !strcmp( attrib, "card" ) ) { result = astTestCard( this ); /* Encoding. */ /* --------- */ } else if ( !strcmp( attrib, "encoding" ) ) { result = astTestEncoding( this ); /* FitsAxisOrder. */ /* -------------- */ } else if ( !strcmp( attrib, "fitsaxisorder" ) ) { result = astTestFitsAxisOrder( this ); /* FitsDigits. */ /* ----------- */ } else if ( !strcmp( attrib, "fitsdigits" ) ) { result = astTestFitsDigits( this ); /* DefB1950. */ /* --------- */ } else if ( !strcmp( attrib, "defb1950" ) ) { result = astTestDefB1950( this ); /* TabOK. */ /* ------ */ } else if ( !strcmp( attrib, "tabok" ) ) { result = astTestTabOK( this ); /* CDMatrix. */ /* --------- */ } else if ( !strcmp( attrib, "cdmatrix" ) ) { result = astTestCDMatrix( this ); /* CarLin. */ /* --------- */ } else if ( !strcmp( attrib, "carlin" ) ) { result = astTestCarLin( this ); /* PolyTan */ /* ------- */ } else if ( !strcmp( attrib, "polytan" ) ) { result = astTestPolyTan( this ); /* Iwc. */ /* ---- */ } else if ( !strcmp( attrib, "iwc" ) ) { result = astTestIwc( this ); /* Clean. */ /* ------ */ } else if ( !strcmp( attrib, "clean" ) ) { result = astTestClean( this ); /* Warnings. */ /* -------- */ } else if ( !strcmp( attrib, "warnings" ) ) { result = astTestWarnings( 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, "ncard" ) || !strcmp( attrib, "nkey" ) || !strcmp( attrib, "cardtype" ) || !strcmp( attrib, "cardcomm" ) || !strcmp( attrib, "cardname" ) || !strcmp( attrib, "allwarnings" ) ){ result = 0; /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static int TestCard( AstFitsChan *this, int *status ){ /* *+ * Name: * astTestCard * Purpose: * Test the Card attribute. * Type: * Protected virtual function. * Synopsis: * #include "fitschan.h" * int astTestCard( AstFitsChan *this ) * Class Membership: * FitsChan method. * Description: * This function tests the Card attribute for the supplied FitsChan. * Parameters: * this * Pointer to the FitsChan. * Returned Value: * If the Card attribute has its "cleared" value (i.e. if the first card * in the FitsChan will be the next one to be read), then zero is returned, * otherwise 1 is returned. *- */ /* Local Variables: */ int card; /* The original value of Card */ int ret; /* The returned flag */ /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Get the current value of Card. */ card = astGetCard( this ); /* Temporarily clear Card. */ astClearCard( this ); /* See if the original Card is equal to the cleared card, and set the returned flag appropriately. Re-instate the original value of card is required.*/ if( astGetCard( this ) == card ) { ret = 0; } else { astSetCard( this, card ); ret = 1; } /* Return the flag. */ return ret; } static int TestFits( AstFitsChan *this, const char *name, int *there, int *status ){ /* *++ * Name: c astTestFits f AST_TESTFITS * Purpose: * See if a named keyword has a defined value in a FitsChan. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c int astTestFits( AstFitsChan *this, const char *name, int *there ) f RESULT = AST_TESTFITS( THIS, NAME, THERE, STATUS ) * Class Membership: * FitsChan method. * Description: * This function serches for a named keyword in a FitsChan. If found, * and if the keyword has a value associated with it, a c non-zero f .TRUE. * value is returned. If the keyword is not found, or if it does not * have an associated value, a c zero f .FALSE. * value is returned. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. c name f NAME = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string f A character string * containing the FITS keyword name. This may be a complete FITS * header card, in which case the keyword to use is extracted from * it. No more than 80 characters are read from this string. c there f THERE = LOGICAL (Returned) c Pointer to an integer which will be returned holding a non-zero c value if the keyword was found in the header, and zero otherwise. f A value of .TRUE. will be returned if the keyword was found in the f header, and .FALSE. otherwise. * This parameter allows a distinction to be made between the case * where a keyword is not present, and the case where a keyword is * present but has no associated value. c A NULL pointer may be supplied if this information is not c required. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astTestFits() f AST_TESTFITS = LOGICAL * A value of zero f .FALSE. * is returned if the keyword was not found in the FitsChan or has * no associated value. Otherwise, a value of c one f .TRUE. * is returned. * Notes: * - The current card is left unchanged by this function. * - The card following the current card is checked first. If this is * not the required card, then the rest of the FitsChan is searched, * starting with the first card added to the FitsChan. Therefore cards * should be accessed in the order they are stored in the FitsChan (if * possible) as this will minimise the time spent searching for cards. * - An error will be reported if the keyword name does not conform * to FITS requirements. c - Zero f - .FALSE. * is returned as the function value if an error has already occurred, * or if this function should fail for any reason. *-- */ /* Local Variables: */ const char *class; /* Object class */ const char *method; /* Calling method */ char *lcom; /* Supplied keyword comment */ char *lname; /* Supplied keyword name */ char *lvalue; /* Supplied keyword value */ int icard; /* Current card index on entry */ int ret; /* The returned value */ /* Initialise */ if( there ) *there = 0; /* Check the global error status. */ if ( !astOK ) return 0; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the calling method and object class. */ method = "astTestFits"; class = astGetClass( this ); /* Initialise the returned value. */ ret = 0; /* Extract the keyword name from the supplied string. */ (void) Split( this, name, &lname, &lvalue, &lcom, method, class, status ); /* Store the current card index. */ icard = astGetCard( this ); /* Attempt to find a card in the FitsChan refering to this keyword, and make it the current card. Only proceed if a card was found. */ if( SearchCard( this, lname, method, class, status ) ){ /* Indicate the card has been found. */ if( there ) *there = 1; /* If the cards data type is no undefined, return 1. */ if( CardType( this, status ) != AST__UNDEF ) ret = 1; } /* Re-instate the original current card index. */ astSetCard( this, icard ); /* Release the memory used to hold keyword name, value and comment strings. */ lname = (char *) astFree( (void *) lname ); lvalue = (char *) astFree( (void *) lvalue ); lcom = (char *) astFree( (void *) lcom ); /* Return the answer. */ return ret; } static void TidyOffsets( AstFrameSet *fset, int *status ) { /* * Name: * TidyOffsets * Purpose: * Remove un-needed offset coordinate Frames. * Type: * Private function. * Synopsis: * void TidyOffsets( AstFrameSet *fset, int *status ) * Class Membership: * FitsChan * Description: * A FITS header stores offset sky coordinates as two alternaive axis * descriptions - one giving the offset axes and one giving the absolute * axes. But AST can hold both forms in a single SkyFrame. This function * removes the FITS Frames describing offset axes from the FrameSet. * The remaining absolute Frame is then used to describe both absolute * and offset. * Parameters: * fset * A FrameSet holding the Frames read from a FITS-WCS Header. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; AstFrame *pfrm; const char *dom; const char *skyrefis; int hasabs; int hasoff; int iax; int icurr; int icurr_is_offset; int ifrm; int nax; int nfrm; int pax; int remove; /* Check the inherited status. */ if( !astOK ) return; /* Note the original current Frame index. */ icurr = astGetCurrent( fset ); /* Assume the current Frame is not an offset frame until proven otherwise. */ icurr_is_offset = 0; /* Does the FrameSet contain any Frames holding sky offsets? Such Frames should have been given a Domain of SKY_OFFSETS within function WcsSkyFrame. Loop round all Frames, checking each one. Also note if the FrameSet contains any (absolute) SKY frames. Also set the SkyRefIs attribute for any absolute SkyFrames that were marked with domains SKY_POLE or SKY_OFFSET in WcsSkyFrame. */ hasabs = 0; hasoff = 0; nfrm = astGetNframe( fset ); for( ifrm = 1; ifrm <= nfrm; ifrm++ ){ skyrefis = NULL; frm = astGetFrame( fset, ifrm ); nax = astGetNaxes( frm ); for( iax = 0; iax < nax; iax++ ) { astPrimaryFrame( frm, iax, &pfrm, &pax ); if( IsASkyFrame( pfrm ) ) { dom = astGetDomain( pfrm ); if( dom ) { if( !strcmp( dom, "SKY_OFFSETS" ) ){ hasoff = 1; if( ifrm == icurr ) icurr_is_offset = 1; iax = nax; } else if( !strcmp( dom, "SKY" ) ){ hasabs = 1; iax = nax; } else if( !strcmp( dom, "SKY_POLE" ) ){ hasabs = 1; skyrefis = "POLE"; iax = nax; } else if( !strcmp( dom, "SKY_ORIGIN" ) ){ hasabs = 1; skyrefis = "ORIGIN"; iax = nax; } } } pfrm = astAnnul( pfrm ); } frm = astAnnul( frm ); if( skyrefis ) { astSetI( fset, "Current", ifrm); astSetC( fset, "SkyRefIs", skyrefis ); astSetI( fset, "Current", icurr ); } } /* If one or more absolute sky frames were found, then remove any offset sky frames. Clear the Ident attribute (that holds the FITS-WCS alternate axis description character) for any absoute Frames. */ if( hasabs && hasoff ) { for( ifrm = nfrm; ifrm > 0; ifrm-- ) { remove = 0; frm = astGetFrame( fset, ifrm ); nax = astGetNaxes( frm ); for( iax = 0; iax < nax; iax++ ) { astPrimaryFrame( frm, iax, &pfrm, &pax ); if( IsASkyFrame( pfrm ) ) { dom = astGetDomain( pfrm ); if( dom ) { if( !strcmp( dom, "SKY_OFFSETS" ) ){ remove = 1; iax = nax; } else if( !strcmp( dom, "SKY_POLE" ) || !strcmp( dom, "SKY_ORIGIN" ) ){ astClearIdent( frm ); astClearDomain( pfrm ); /* If we will be deleting the original current Frame (because it is an offset Frame), then mark the first absolute Frame as the new current Frame. */ if( icurr_is_offset ) { astSetCurrent( fset, ifrm ); icurr_is_offset = 0; } iax = nax; } } } pfrm = astAnnul( pfrm ); } frm = astAnnul( frm ); if( remove ) astRemoveFrame( fset, ifrm ); } } } static AstTimeScaleType TimeSysToAst( AstFitsChan *this, const char *timesys, const char *method, const char *class, int *status ){ /* * Name: * TimeSysToAst * Purpose: * Convert a FITS TIMESYS value to an AST TimeFrame timescale value. * Type: * Private function. * Synopsis: * AstTimeScaleType TimeSysToAst( AstFitsChan *this, const char *timesys, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function returns the value used by the AST TimeFrame class to * represent the timescale specified by the "timesys" parameter, which * should hold the value of a FITS TIMESYS keyword. The TIMESYS * convention was introduced as part of the Y2K DATE-OBS changes, and * is not currently part of the published FITS-WCS conventions. * * If the requested timescale is not supported by AST, then a warning is * added to the FitsChan and a value of AST__UTC is returned (but no * error is reported). * Parameters: * this * Pointer to the FitsChan. * timesys * Pointer to the string holding the TIMESYS value. A NULL pointer * returns the default timescale of UTC. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The equivalent AstTimeScaleType value. */ /* Local Variables: */ AstTimeScaleType result; /* The returned timescale */ char buf[ 200 ]; /* Buffer for warning message */ /* Initialise */ result = AST__UTC; /* Check the inherited status. */ if( !astOK ) return result; if( !timesys ) { result = AST__UTC; } else if( !strcmp( timesys, "UTC" ) ) { result = AST__UTC; } else if( !strcmp( timesys, "UT" ) ) { result = AST__UTC; Warn( this, "badval", "The original FITS header contained a value of UT " "for keyword TIMESYS which is being interpreted as UTC.", method, class, status ); } else if( !strcmp( timesys, "TAI" ) ) { result = AST__TAI; } else if( !strcmp( timesys, "IAT" ) ) { result = AST__TAI; } else if( !strcmp( timesys, "ET" ) ) { result = AST__TT; Warn( this, "badval", "The original FITS header contained a value of ET " "for keyword TIMESYS. TT will be used instead.", method, class, status ); } else if( !strcmp( timesys, "TT" ) ) { result = AST__TT; } else if( !strcmp( timesys, "TDT" ) ) { result = AST__TT; } else if( !strcmp( timesys, "TDB" ) ) { result = AST__TDB; } else if( !strcmp( timesys, "TCG" ) ) { result = AST__TCG; } else if( !strcmp( timesys, "TCB" ) ) { result = AST__TCB; } else { result = AST__UTC; sprintf( buf, "The original FITS header contained a value of %s for " "keyword TIMESYS. AST does not support this timescale so " "UTC will be used instead.", timesys ); Warn( this, "badval", buf, method, class, status ); } /* Return the result */ return result; } static char *UnPreQuote( const char *string, int *status ) { /* * Name: * UnPreQuote * Purpose: * Reverse the pre-quoting of FITS character data. * Type: * Private function. * Synopsis: * #include "fitschan.h" * char *UnPreQuote( const char *string, int *status ) * Class Membership: * FitsChan member function. * Description: * This function reverses the effect of the PreQuote function on a * string (apart from any loss of data due to truncation). It * should be used to recover the original character data from the * pre-quoted version of a string retrieved from a FITS character * value associated with a keyword. * Parameters: * string * Pointer to a constant null-terminated string containing the * pre-quoted character data. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a dynamically allocated null-terminated string * containing the un-quoted character data. The memory holding this * string should be freed by the caller (using astFree) when no * longer required. * Notes: * - A NULL pointer value will be returned if this function is * invoked wth the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ char *result; /* Pointer value to return */ int i1; /* Offset of first useful character */ int i2; /* Offest of last useful character */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise to use the first and last characters in the input string. */ i1 = 0; i2 = strlen( string ) - 1; /* If the string contains at least 2 characters, check if the first and last characters are double quotes ("). If so, adjust the offsets to exclude them. */ if ( ( i2 > i1 ) && ( string[ i1 ] == '"' ) && ( string[ i2 ] == '"' ) ) { i1++; i2--; } /* Make a dynamically allocated copy of the useful part of the string. */ result = astString( string + i1, i2 - i1 + 1 ); /* Return the answer. */ return result; } static int Use( AstFitsChan *this, int set, int helpful, int *status ) { /* * Name: * Use * Purpose: * Decide whether to write a value to a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Use( AstFitsChan *this, int set, int helpful, int *status ) * Class Membership: * FitsChan member function. * Description: * This function decides whether a value supplied by a class "Dump" * function, via a call to one of the astWrite... protected * methods, should actually be written to a FitsChan. * * This decision is based on the settings of the "set" and * "helpful" flags supplied to the astWrite... method, plus the * attribute settings of the FitsChan. * Parameters: * this * A pointer to the FitsChan. * set * The "set" flag supplied. * helpful * The "helpful" value supplied. * status * Pointer to the inherited status variable. * Returned Value: * One if the value should be written out, otherwise zero. * 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: */ int full; /* Full attribute value */ int result; /* Result value to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* If "set" is non-zero, then so is the result ("set" values must always be written out). */ result = ( set != 0 ); /* Otherwise, obtain the value of the FitsChan's Full attribute. */ if ( !set ) { full = astGetFull( this ); /* If Full is positive, display all values, if zero, display only "helpful" values, if negative, display no (un-"set") values. */ if ( astOK ) result = ( ( helpful && ( full > -1 ) ) || ( full > 0 ) ); } /* Return the result. */ return result; } static int Ustrcmp( const char *a, const char *b, int *status ){ /* * Name: * Ustrcmp * Purpose: * A case blind version of strcmp. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Ustrcmp( const char *a, const char *b, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns 0 if there are no differences between the two strings, and 1 * otherwise. Comparisons are case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strcmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Loop round each character. */ while( 1 ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } static int Ustrncmp( const char *a, const char *b, size_t n, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strncmp. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Ustrncmp( const char *a, const char *b, size_t n, int *status ) * Class Membership: * FitsChan member function. * Description: * Returns 0 if there are no differences between the first "n" * characters of the two strings, and 1 otherwise. Comparisons are * case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * n * The maximum number of characters to compare. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strncmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int i; /* Character index */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Compare up to "n" characters. */ for( i = 0; i < (int) n; i++ ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } static void Warn( AstFitsChan *this, const char *condition, const char *text, const char*method, const char *class, int *status ){ /* * Name: * Warn * Purpose: * Store warning cards in a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Warn( AstFitsChan *this, const char *condition, const char *text, * const char*method, const char *class, int *status ); * Class Membership: * FitsChan member function. * Description: * If the Warnings attribute indicates that occurences of the specified * condition should be reported, the supplied text is split into lines * and stored in the FitsChan as a series of ASTWARN cards, in front * of the current card. If the specified condition is not being reported, * this function returns without action. * Parameters: * this * The FitsChan. If NULL, this function returns without action. * condition * Pointer to a string holding a lower case condition name. * text * Pointer to a string holding the text of the warning. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char buff[ AST__FITSCHAN_FITSCARDLEN + 1 ]; /* Buffer for new card text */ const char *a; /* Pointer to 1st character in next card */ const char *b; /* Pointer to terminating null character */ const char *c; /* Pointer to last character in next card */ int exists; /* Has the supplied warning already been issued? */ int icard; /* Index of original card */ int nc; /* No. of characters in next card */ /* Check the inherited status, warning text, FitsChan and Clean attribute. */ if( !astOK || !text || !text[0] || !this || astGetClean( this ) ) return; /* Ignore the warning if the supplied condition is not contained within the list of conditions to be reported in this way (given by the Warnings attribute). */ if( FullForm( astGetWarnings( this ), condition, 0, status ) >= 0 ){ /* If found, store the warning in the parent Channel structure. */ astAddWarning( this, 1, "%s", method, status, text ); /* For historical reasons, warnings are also stored in the FitsChan as a set of FITS cards... First save the current card index, and rewind the FitsChan. */ icard = astGetCard( this ); astClearCard( this ); /* Break the supplied text into lines and check the FitsChan to see if a block of adjacent ASTWARN cards with these lines already exist within the FitsChan. Assume they do until proven otherwise. */ exists = 1; a = text; b = a + strlen( text ); while( a < b ){ /* Each card contains about 60 characters of the text. Get a pointer to the nominal last character in the next card. */ c = a + 60; /* If this puts the last character beyond the end of the text, use the last character before the null as the last character in the card. */ if( c >= b ) { c = b - 1; /* Otherwise, if the last character is not a space, move the last character backwards to the first space. This avoids breaking words across cards. */ } else { while( !isspace( *c ) && c > a ) c--; } /* Copy the text into a null terminated buffer. */ nc = c - a + 1; strncpy( buff, a, nc ); buff[ nc ] = 0; /* If this is the first line, search the entire FitsChan for an ASTWARN card with this text. If not, indiate that the supplied text needs to be stored in the FitsChan, and break out of the loop. */ if( a == text ) { exists = 0; while( !exists && FindKeyCard( this, "ASTWARN", method, class, status ) ) { if( !strcmp( (const char *) CardData( this, NULL, status ), buff ) ) { exists = 1; } MoveCard( this, 1, method, class, status ); } if( !exists ) break; /* If this is not the first line, see if the next card in the FitsChan is an ASTWARN card with this text. If not, indiate that the supplied text needs to be stored in the FitsChan, and break out of the loop. */ } else { if( !strcmp( CardName( this, status ), "ASTWARN" ) && !strcmp( (const char *) CardData( this, NULL, status ), buff ) ) { MoveCard( this, 1, method, class, status ); } else { exists = 0; break; } } /* Set the start of the next bit of the text. */ a = c + 1; } /* Reinstate the original current card index. */ astSetCard( this, icard ); /* We only add new cards to the FitsChan if they do not already exist. */ if( !exists ) { /* Break the text into lines using the same algorithm as above, and store each line as a new ASTWARN card. Start with a blank ASTWARN card. */ astSetFitsS( this, "ASTWARN", " ", NULL, 0 ); /* Loop until the entire text has been written out. */ a = text; b = a + strlen( text ); while( a < b ){ /* Each card contains about 60 characters of the text. Get a pointer to the nominal last character in the next card. */ c = a + 60; /* If this puts the last character beyond the end of the text, use the last character before the null as the last character in the card. */ if( c >= b ) { c = b - 1; /* Otherwise, if the last character is not a space, move the last character backwards to the first space. This avoids breaking words across cards. */ } else { while( !isspace( *c ) && c > a ) c--; } /* Copy the text into a null terminated buffer. */ nc = c - a + 1; strncpy( buff, a, nc ); buff[ nc ] = 0; /* Store the buffer as the next card. */ astSetFitsS( this, "ASTWARN", buff, NULL, 0 ); /* Set the start of the next bit of the text. */ a = c + 1; } /* Include a final blank card. */ astSetFitsS( this, "ASTWARN", " ", NULL, 0 ); } } } static int WATCoeffs( const char *watstr, int iaxis, double **cvals, int **mvals, int *ok, int *status ){ /* * Name: * WATCoeffs * Purpose: * Get the polynomial coefficients from the lngcor or latcor component * of an IRAF WAT string. * Type: * Private function. * Synopsis: * int WATCoeffs( const char *watstr, int iaxis, double **cvals, * int **mvals, int *ok, int *status ) * Class Membership: * FitsChan * Description: * This function extracts the polynomial coefficients from a supplied * string containing the concatenated values of a set of IRAF "WAT" * keywords, such as used for the IRAF-specific TNX and ZPX projections. * The coefficients are returned in the form of a set of PVi_m values * for a TPN projection. * Parameters: * watstr * The concatentated WAT keyword values. * iaxis * Zero based index of the axis to which the WAT keywords refer (0 * or 1). * cvals * Location at which to return a pointer to a dynamically allocated * list of coefficient values, or NULL if no lngcor/latcor values * were found in the WAT string. Free using astFree. * mvals * Location at which to return a pointer to a dynamically allocated * list of coefficient indices, or NULL if no lngcor/latcor values * were found in the WAT string. Free using astFree. * ok * Pointer to an in which is returned set to zero if the polynomial * in the supplied WAT string cannot be represented using TPN form. * Non-zero otherwise. * status * Pointer to the inherited status variable. * Returned Value: * The size of the returned cvals and mvals arrays. */ /* Local Variables: */ char **w1; char **w2; double *coeff; double *pc; int result; double dval; double etamax; double etamin; double ximax; double ximin; int cheb; int etaorder; int iword; int m; int mn; int nword; int order; int porder; int xiorder; int ires; /* The number of lngcor/latcor values needed for each order. */ static const int nab[] = {1,3,6,10,15,21,28,36}; /* Initialise the pointer to the returned Mapping. */ result = 0; *mvals = NULL; *cvals = NULL; *ok = 1; /* Other initialisation to avoid compiler warnings. */ etamin = 0.0; etamax = 0.0; ximax = 0.0; ximin = 0.0; order = 0; /* Check the global status. */ if ( !astOK || !watstr ) return result; /* Look for cor = "..." and extract the "..." string. */ w1 = astChrSplitRE( watstr, "cor *= *\"(.*)\"", &nword, NULL ); if( w1 ) { /* Split the "..." string into words. */ w2 = astChrSplit( w1[ 0 ], &nword ); if( w2 ) { /* Initialise flags. */ cheb = 0; xiorder = 0; etaorder = 0; coeff = NULL; porder = -1; /* Loop round each word. Break early if we find that the projection cannot be represented as a TPN projection. */ for( iword = 0; iword < nword && *ok; iword++ ) { /* Convert the word to double. */ dval = astChr2Double( w2[ iword ] ); if( dval == AST__BAD ) { astError( AST__BDFTS, "astRead(FitsChan): Failed to read a " "numerical value from sub-string \"%s\" found in " "an IRAF \"WAT...\" keyword.", status, w2[ iword ] ); break; } /* The first value gives the correction surface type. We can only handle type 1 (chebyshev) or 3 (simple polynomial). */ if( iword == 0 ){ if( dval == 1.0 ) { cheb = 1; } else if( dval == 2.0 ) { *ok = 0; } /* The second and third numbers gives the orders of the polynomial in X and Y. We can only handle cases in which the orders are the same on both axes, and greater than 0 and less than 8. Store a pointer to the first TAN projection parameter index to use. */ } else if( iword == 1 ){ order = dval; porder = order - 1; } else if( iword == 2 ){ if( dval - 1 != porder || dval < 0 || dval > 7 ) *ok = 0; /* The fourth number defines the type of cross-terms. We can only handle type 2 (half-cross terms). */ } else if( iword == 3 ){ if( dval != 2.0 ) *ok = 0; /* We now know the maximum number of co-efficients that may be needed. Allocate memory to hold them, and fill it with zeros. They are stored in this array as if full cross-terms have been supplied (the unspecified coefficients retain their initialised value of zero). */ coeff = astCalloc( order*order, sizeof( double ) ); if( !astOK ) break; /* The next 4 numbers describe the region of validity of the fits in IRAF's xi and eta space, e.g. ximin, ximax, etamin, etamax. We only uses these if we have a chebyshev polynomial. */ } else if( iword == 4 ) { ximin = dval; } else if( iword == 5 ) { ximax = dval; } else if( iword == 6 ) { etamin = dval; } else if( iword == 7 ) { etamax = dval; /* The remaining terms are the coefficients of the polynomial terms. */ } else if( iword > 7 ){ /* Store the coefficient in the array. They are stored so that power of xi increases fastest. */ coeff[ xiorder + order*etaorder ] = dval; /* Increment the powers of the next coefficient. We know we only have half cross-terms, so the maximum power of xi decreases from order to zero as we move through the list of coefficients. */ if( ++xiorder == order - etaorder ) { xiorder = 0; etaorder++; } } } /* Check that all the required co-efficients were found */ if( porder == -1 || nword != 8 + nab[ porder ] ) *ok = 0; /* If we can handle the projection, proceed. */ if( *ok && astOK ) { /* If the coefficients were supplied in chebyshev form, convert to simple form. */ if( cheb ) { double *tcoeff = coeff; coeff = Cheb2Poly( tcoeff, order, order, ximin, ximax, etamin, etamax, status ); tcoeff = astFree( tcoeff ); } /* The polynomials provide a "correction* to be added to the supplied X and Y values. Therefore increase the linear co-efficients by 1 on the axis that is being calculated. */ coeff[ iaxis ? order : 1 ] += 1.0; /* Loop round all coefficients, keeping track of the power of xi and eta for the current coefficient. */ pc = coeff; for( etaorder = 0; etaorder < order; etaorder++ ) { for( xiorder = 0; xiorder < order; xiorder++,pc++ ) { /* Skip coefficients that have their default values (zero, except for the linear coefficients which default to 1.0). */ mn = xiorder + etaorder; if( *pc != ( mn == 1 ? 1.0 : 0.0 ) ) { /* Find the "m" index of the PVi_m FITS keyword for the current coefficient. */ m = mn*( 1 + mn )/2 + mn/2; m += iaxis ? xiorder : etaorder; /* Append the PV and m values to the ends of the returned arrays. */ ires = result++; *cvals = astGrow( *cvals, sizeof( double ), result ); *mvals = astGrow( *mvals, sizeof( int ), result ); if( astOK ) { (*cvals)[ ires ] = *pc; (*mvals)[ ires ] = m; } } } } /* Free coefficients arrays */ coeff = astFree( coeff ); } /* Free resources */ w2 = astFree( w2 ); } w1 = astFree( w1 ); } /* Return the result. */ return result; } static AstMatrixMap *WcsCDeltMatrix( FitsStore *store, char s, int naxes, const char *method, const char *class, int *status ){ /* * Name: * WcsCDeltMatrix * Purpose: * Create a MatrixMap representing the CDELT scaling. * Type: * Private function. * Synopsis: * AstMatrixMap *WcsCDeltMatrix( FitsStore *store, char s, int naxes, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A diagonal MatrixMap representing the FITS "CDELT" keywords is * returned. * Parameters: * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character s identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the created MatrixMap or a NULL pointer if an * error occurred. */ /* Local Variables: */ AstMatrixMap *new; /* The created MatrixMap */ double *el; /* Pointer to next matrix element */ double *mat; /* Pointer to matrix array */ int i; /* Pixel axis index */ /* Initialise/ */ new = NULL; /* Check the global status. */ if ( !astOK ) return new; /* Allocate memory for the diagonal matrix elements. */ mat = (double *) astMalloc( sizeof(double)*naxes ); if( astOK ){ /* Fill the matrix diagonal with values from the FitsStore. */ el = mat; for( i = 0; i < naxes; i++ ){ /* Get the CDELTi value for this axis. Missing terms can be defaulted so do not report an error if the required value is not present in the FitsStore. */ *el = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); /* Missing terms default to to 1.0. */ if( *el == AST__BAD ) *el = 1.0; /* Move on to the next matrix element. */ el++; } /* Create the diagional matrix. */ new = astMatrixMap( naxes, naxes, 1, mat, "", status ); /* Report an error if the inverse transformation is undefined. */ if( !astGetTranInverse( new ) && astOK ) { astError( AST__BDFTS, "%s(%s): Unusable CDELT values found " "in the FITS-WCS header - one or more values are zero.", status, method, class ); } /* Release the memory used to hold the matrix. */ mat = (double *) astFree( (void *) mat ); } /* If an error has occurred, attempt to annul the returned MatrixMap. */ if( !astOK ) new = astAnnul( new ); /* Return the MatrixMap. */ return new; } static AstMapping *WcsCelestial( AstFitsChan *this, FitsStore *store, char s, AstFrame **frm, AstFrame *iwcfrm, double *reflon, double *reflat, AstSkyFrame **reffrm, AstMapping **tabmap, int *tabaxis, const char *method, const char *class, int *status ){ /* * Name: * WcsCelestial * Purpose: * Create a Mapping from intermediate world coords to celestial coords * as described in a FITS header. * Type: * Private function. * Synopsis: * AstMapping *WcsCelestial( AstFitsChan *this, FitsStore *store, char s, * AstFrame **frm, AstFrame *iwcfrm, double *reflon, double *reflat, * AstSkyFrame **reffrm, , AstMapping **tabmap, * int *tabaxis, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function interprets the contents of the supplied FitsStore * structure, looking for world coordinate axes which describe positions * on the sky. If a pair of such longitude/latitude axes is found, a * Mapping is returned which transforms the corresponding intermediate * world coordinates to celestial world coordinates (this mapping leaves * any other axes unchanged). It also, modifies the supplied Frame to * describe the axes (again, other axes are left unchanged). If no * pair of celestial axes is found, a UnitMap is returned, and the * supplied Frame is left unchanged. * Parameters: * this * The FitsChan. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * frm * The address of a location at which to store a pointer to the * Frame describing the world coordinate axes. * iwcfrm * A pointer to the Frame describing the intermediate world coordinate * axes. The properties of this Frame may be changed on exit. * reflon * Address of a location at which to return the celestial longitude * at the reference point. It is returned as AST__BAD if no * celestial coordinate frame is found. * reflat * Address of a location at which to return the celestial latitude * at the reference point. It is returned as AST__BAD if no * celestial coordinate frame is found. * reffrm * Address of a location at which to return a pointer to a SkyFrame * which define the reference values returned in reflon and reflat. * It is returned as NULL if no celestial coordinate frame is found. * tabmap * Address of a pointer to a Mapping describing any -TAB * transformations to be applied to the results of the Mapping returned * by this function. If any celestial axes are found, the supplied * Mapping is modified so that the celestial axes produce values in * radians rather than degrees. NULL if no axes are described by -TAB. * tabaxis * Pointer to an array of flags, one for each WCS axis, indicating * if the corresponding WCS axis is described by the -TAB algorithm. * NULL if no axes are described by -TAB. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFrame *ofrm; /* Pointer to a Frame */ AstMapping *map1; /* Pointer to a Mapping */ AstMapping *map2; /* Pointer to a Mapping */ AstMapping *map3; /* Pointer to a Mapping */ AstMapping *map4; /* Pointer to a Mapping */ AstMapping *ret; /* Pointer to the returned Mapping */ AstMapping *newmap; /* Modified PIXEL->IWC Mapping */ AstMapping *shiftmap; /* ShiftMap from IWC to PPC */ AstSkyFrame *sfrm; /* Pointer to a SkyFrame */ char *ctype; /* Pointer to CTYPE string */ char *keyname; /* Pointer to keyword name string */ char buf[300]; /* Text buffer */ char latctype[MXCTYPELEN];/* Latitude CTYPE keyword value */ char latkey[10]; /* Latitude CTYPE keyword name */ char lattype[4]; /* Buffer for celestial system */ char lonctype[MXCTYPELEN];/* Longitude CTYPE keyword value */ char lonkey[10]; /* Longitude CTYPE keyword name */ char lontype[4]; /* Buffer for celestial system */ double *shifts; /* Array holding axis shifts */ double *ina; /* Pointer to memory holding input position A */ double *inb; /* Pointer to memory holding input position B */ double *mat; /* Pointer to data for deg->rad scaling matrix */ double *outa; /* Pointer to memory holding output position A */ double *outb; /* Pointer to memory holding output position B */ double latval; /* CRVAL for latitude axis */ double lonval; /* CRVAL for longitude axis */ double pv; /* Projection parameter value */ double x0; /* IWC X at the projection fiducial point */ double y0; /* IWC Y at the projection fiducial point */ int *axes; /* Point to a list of axis indices */ int axlat; /* Index of latitude physical axis */ int axlon; /* Index of longitude physical axis */ int carlin; /* Assume native and WCS axes are the same? */ int ctlen; /* Length of CTYPE string */ int gotax; /* Celestial axis found? */ int i; /* Loop count */ int j; /* Axis index */ int latprj; /* Latitude projection type identifier */ int lonprj; /* Longitude projection type identifier */ int m; /* Parameter index */ int mxpar_lat; /* Max. projection parameter index on lat axis */ int mxpar_lon; /* Max. projection parameter index on lon axis */ int naxes; /* Number of axes */ int nc; /* String length */ int np; /* Max parameter index */ int prj; /* Projection type identifier */ /* Initialise the returned values. */ ret = NULL; *reflon = AST__BAD; *reflat = AST__BAD; *reffrm = NULL; /* Other initialisation to avoid compiler warnings. */ map1 = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Get the number of physical axes. */ naxes = astGetNaxes( *frm ); /* See if CAR projections should be interpreted in the old fashioned way (i.e native coords are always the same as WCS coords, so no need for any rotation). */ carlin = astGetCarLin( this ); /* The first major section sees if the physical axes include a pair of longitude/latitude celestial axes. ================================================================= */ /* We have not yet found any celestial axes. */ axlon = -1; axlat = -1; latprj = AST__WCSBAD; lonprj = AST__WCSBAD; prj = AST__WCSBAD; /* First, we examine the CTYPE values in the FitsStore to determine which axes are the longitude and latitude axes, and what the celestial co-ordinate system and projection are. Loop round the physical axes, getting each CTYPE value. */ for( i = 0; i < naxes && astOK; i++ ){ keyname = FormatKey( "CTYPE", i + 1, -1, s, status ); ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); /* Issue a warning if no CTYPE value was found. */ if( !ctype ) { sprintf( buf, "Axis type keywords (CTYPE, etc) were not found " "for one or more axes in the original FITS header. These " "axes will be assumed to be linear." ); Warn( this, "noctype", buf, method, class, status ); } else { /* See if this is a longitude axis (e.g. if the first 4 characters of CTYPE are "RA--" or "xLON" or "yzLN" ). If so, store the value of "x" or "yz" (or "EQU" for equatorial coordinates) in variable "type" to indicate which coordinate system is being used. */ nc = strlen( ctype ); gotax = 0; if( !strcmp( ctype, "RA" ) || !strncmp( ctype, "RA--", 4 ) ){ strcpy( wcscelestial_type, "EQU" ); gotax = 1; } else if( !strcmp( ctype, "AZ" ) || !strncmp( ctype, "AZ--", 4 ) ){ strcpy( wcscelestial_type, "AZL" ); gotax = 1; } else if( nc > 1 && ( !strcmp( ctype + 1, "LON" ) || !strncmp( ctype + 1, "LON-", 4 ) ) ){ wcscelestial_type[ 0 ] = ctype[ 0 ]; wcscelestial_type[ 1 ] = 0; gotax = 1; } else if( nc > 2 && ( !strcmp( ctype + 2, "LN" ) || !strncmp( ctype + 2, "LN-", 3 ) ) ){ wcscelestial_type[ 0 ] = ctype[ 0 ]; wcscelestial_type[ 1 ] = ctype[ 1 ]; wcscelestial_type[ 2 ] = 0; gotax = 1; } /* If this is a longitude axis... */ if( gotax ){ /* Check that this is the first longitude axis to be found. */ if( axlon == -1 ){ /* Find the projection type as specified by the last 4 characters in the CTYPE keyword value. AST__WCSBAD is stored in "prj" if the last 4 characters do not specify a known WCS projection, but no error is reported. Assume simple linear axes if no projection code is supplied. Note, AST__WCSBAD is used to indicate a TAB header. */ ctlen = strlen( ctype ); if( ctlen > 4 ) { prj = astWcsPrjType( ctype + ctlen - 4 ); } else if( tabmap && *tabmap ) { prj = AST__WCSBAD; } else { prj = AST__CAR; carlin = 1; } /* Report an error if the projection is unknown. */ if( prj == AST__WCSBAD && ctlen > 4 ){ astError( AST__BDFTS, "%s(%s): FITS keyword '%s' refers to " "an unknown projection type '%s'.", status, method, class, keyname, ctype + ctlen - 4 ); break; } /* Store the index of the longitude axis, type of longitude, etc. */ axlon = i; strcpy( lontype, wcscelestial_type ); strcpy( lonkey, keyname ); strcpy( lonctype, ctype ); lonprj = prj; /* If another longitude axis has already been found, report an error. */ } else { astError( AST__BDFTS, "%s(%s): FITS keywords '%s' (='%s') " "and '%s' (='%s') both describe celestial longitude axes.", status, method, class, keyname, ctype, lonkey, lonctype ); break; } } /* Do the same for the latitude axis, checking for "DEC-" and "xLAT" and "yzLT". */ gotax = 0; if( !strcmp( ctype, "DEC" ) || !strncmp( ctype, "DEC-", 4 ) ){ strcpy( wcscelestial_type, "EQU" ); gotax = 1; } else if( !strcmp( ctype, "EL" ) || !strncmp( ctype, "EL--", 4 ) ){ strcpy( wcscelestial_type, "AZL" ); gotax = 1; } else if( !strcmp( ctype + 1, "LAT" ) || !strncmp( ctype + 1, "LAT-", 4 ) ){ wcscelestial_type[ 0 ] = ctype[ 0 ]; wcscelestial_type[ 1 ] = 0; gotax = 1; } else if( !strcmp( ctype + 2, "LT" ) || !strncmp( ctype + 2, "LT-", 3 ) ){ wcscelestial_type[ 0 ] = ctype[ 0 ]; wcscelestial_type[ 1 ] = ctype[ 1 ]; wcscelestial_type[ 2 ] = 0; gotax = 1; } if( gotax ){ if( axlat == -1 ){ ctlen = strlen( ctype ); if( ctlen > 4 ) { prj = astWcsPrjType( ctype + ctlen - 4 ); } else if( tabmap && *tabmap ) { prj = AST__WCSBAD; } else { prj = AST__CAR; carlin = 1; } if( prj == AST__WCSBAD && ctlen > 4 ){ astError( AST__BDFTS, "%s(%s): FITS keyword '%s' refers to " "an unknown projection type '%s'.", status, method, class, keyname, ctype + ctlen - 4 ); break; } axlat = i; strcpy( lattype, wcscelestial_type ); strcpy( latkey, keyname ); strcpy( latctype, ctype ); latprj = prj; } else { astError( AST__BDFTS, "%s(%s): FITS keywords '%s' (='%s') " "and '%s' (='%s') both describe celestial latitude axes.", status, method, class, keyname, ctype, latkey, latctype ); break; } } } } /* Check the above went OK */ if( astOK ){ /* If both longitude and latitude axes were found... */ if( axlat != -1 && axlon != -1 ){ /* Report an error if they refer to different celestial coordinate systems. */ if( strcmp( lattype, lontype ) ){ astError( AST__BDFTS, "%s(%s): FITS keywords '%s' and '%s' " "indicate different celestial coordinate systems " "('%s' and '%s').", status, method, class, latkey, lonkey, latctype, lonctype ); /* Otherwise report an error if longitude and latitude axes use different projections. */ } else if( lonprj != latprj ){ astError( AST__BDFTS, "%s(%s): FITS keywords '%s' and '%s' " "indicate different projections ('%s' and '%s').", status, method, class, latkey, lonkey, latctype, lonctype ); } /* If only one axis has been provided without the other (e.g. longitude but no latitude), report an error. */ } else if( axlat != -1 && prj != AST__WCSBAD ){ astError( AST__BDFTS, "%s(%s): A latitude axis ('%s') was found " "without a corresponding longitude axis.", status, method, class, latctype ); } else if( axlon != -1 && prj != AST__WCSBAD ){ astError( AST__BDFTS, "%s(%s): A longitude axis ('%s') was found " "without a corresponding latitude axis.", status, method, class, lonctype ); } } /* If a pair of matching celestial axes was not found, return a UnitMap and leave the Frame unchanged. ===================================================================== */ if( axlat == -1 || axlon == -1 ) { ret = (AstMapping *) astUnitMap( naxes, "", status ); /* The rest of this function deals with creating a Mapping from intermediate world coords to celestial coords, and modifying the Frame appropriately. ===================================================================== */ } else if( astOK ) { /* Create a MatrixMap which scales the intermediate world coordinate axes corresponding to the longitude and latitude axes from degrees to radians. Only do this if a projection was supplied. */ if( latprj != AST__WCSBAD ) { mat = (double *) astMalloc( sizeof(double)*naxes ); if( mat ){ for( i = 0; i < naxes; i++ ){ if( i == axlat || i == axlon ){ mat[ i ] = AST__DD2R; } else { mat[ i ] = 1.0; } } map1 = (AstMapping *) astMatrixMap( naxes, naxes, 1, mat, "", status ); mat = (double *) astFree( (void *) mat ); } } else { map1 = (AstMapping *) astUnitMap( naxes, " ", status ); } /* If the projection is a CAR projection, but the CarLin attribute is set, then we consider the CAR projection to be a simple linear mapping of pixel coords to celestial coords. Do this by using a WcsMap with no projection. All axes will then be treated as linear and non-celestial. If no projection was specified (i.e. if prj == AST__WCSBAD, as is the case when using -TAB for instance) then do the same but use a UnitMap instead of a WcsMap. */ map3 = NULL; if( ( latprj == AST__CAR && carlin ) || latprj == AST__WCSBAD ) { if( latprj == AST__CAR ) { map2 = (AstMapping *) astWcsMap( naxes, AST__WCSBAD, axlon + 1, axlat + 1, "", status ); } else { map2 = (AstMapping *) astUnitMap( naxes, "", status ); } /* Now create a WinMap which adds on the CRVAL values to each axis. */ ina = astMalloc( sizeof(double)*naxes ); inb = astMalloc( sizeof(double)*naxes ); outa = astMalloc( sizeof(double)*naxes ); outb = astMalloc( sizeof(double)*naxes ); if( astOK ) { for( i = 0; i < naxes; i++ ) { ina[ i ] = 0.0; inb[ i ] = 1.0; outa[ i ] = 0.0; outb[ i ] = 1.0; } lonval = GetItem( &(store->crval), axlon, 0, s, NULL, method, class, status ); if( lonval != AST__BAD ) { /* For recognised projections the CRVAL value is required to be degrees, so convert to radians. For other algorithms (e.g. -TAB) the CRVAL values are in unknown units so retain their original scaling. */ *reflon = ( latprj == AST__CAR ) ? lonval*AST__DD2R : lonval; outa[ axlon ] += *reflon; outb[ axlon ] += *reflon; } else { outa[ axlon ] = AST__BAD; outb[ axlon ] = AST__BAD; } latval = GetItem( &(store->crval), axlat, 0, s, NULL, method, class, status ); if( latval != AST__BAD ) { *reflat = ( latprj == AST__CAR ) ? latval*AST__DD2R : latval; outa[ axlat ] += *reflat; outb[ axlat ] += *reflat; } else { outa[ axlat ] = AST__BAD; outb[ axlat ] = AST__BAD; } map3 = (AstMapping *) astWinMap( naxes, ina, inb, outa, outb, "", status ); } ina = astFree( ina ); inb = astFree( inb ); outa = astFree( outa ); outb = astFree( outb ); /* Otherwise, create a WcsMap with the specified projection. The WcsMap is equivalent to a unit mapping for all axes other than "axlat" and "axlon". */ } else { /* Get the highest index ("m" value) of any supplied PVi_m projection parameters (on any axes). */ np = GetMaxJM( &(store->pv), s, status ); /* Create the WcsMap */ map2 = (AstMapping *) astWcsMap( naxes, latprj, axlon + 1, axlat + 1, "", status ); /* If the FITS header contains any projection parameters, store them in the WcsMap. */ mxpar_lat = astGetPVMax( map2, axlat ); mxpar_lon = astGetPVMax( map2, axlon ); for( m = 0; m <= np; m++ ){ pv = GetItem( &(store->pv), axlat, m, s, NULL, method, class, status ); if( pv != AST__BAD ) { if( m <= mxpar_lat ) { astSetPV( map2, axlat, m, pv ); } else { sprintf( buf, "Projection parameter PV%d_%d found, " "but is not used by %s projections.", axlat + 1, m, astWcsPrjName( astGetWcsType( map2 ) ) ); Warn( this, "badpv", buf, method, class, status ); } } pv = GetItem( &(store->pv), axlon, m, s, NULL, method, class, status ); if( pv != AST__BAD ) { if( m <= mxpar_lon ) { astSetPV( map2, axlon, m, pv ); } else { sprintf( buf, "Projection parameter PV%d_%d found, " "but is not used by %s projections.", axlon + 1, m, astWcsPrjName( astGetWcsType( map2 ) ) ); Warn( this, "badpv", buf, method, class, status ); } } } /* Invert the WcsMap to get a DEprojection. */ astInvert( map2 ); /* Now produce a Mapping which converts the axes holding "Native Spherical Coords" into "Celestial Coords", leaving all other axes unchanged. */ map3 = WcsNative( this, store, s, (AstWcsMap *) map2, -1, -1, method, class, status ); /* Retrieve and store the reference longitude and latitude. */ *reflon = GetItem( &(store->crval), axlon, 0, s, NULL, method, class, status ); if( *reflon != AST__BAD ) *reflon *= AST__DD2R; *reflat = GetItem( &(store->crval), axlat, 0, s, NULL, method, class, status ); if( *reflat != AST__BAD ) *reflat *= AST__DD2R; } /* If projection parameter PVi_0a for the longitude axis "i" is non-zero, then there is a shift of origin between Intermediate World Coords, IWC, (the CRPIXi values correspond to the origin of IWC), and Projection Plane Coords, PPC (these are the cartesian coordinates used by the WcsMap). This shift of origin results in the fiducial point specified by the CRVALi values mapping onto the pixel reference point specified by the CRPIXj values. In this case we need to add a Mapping which implements the shift of origin. Note, the AST-specific "TPN" projection cannot use this convention since it uses PVi_0 to hold a polynomial correction term. */ if( latprj != AST__WCSBAD && astGetWcsType( map2 ) != AST__TPN && astGetPV( map2, axlon, 0 ) != 0.0 ) { /* Find the projection plane coords corresponding to the fiducial point of the projection. This is done by using the inverse WcsMap to convert the native spherical coords at the fiducial point into PPC (x,y), which are returned in units of radians (not degrees). */ GetFiducialPPC( (AstWcsMap *) map2, &x0, &y0, status ); if( x0 != AST__BAD && y0 != AST__BAD ) { /* Allocate resources. */ shifts = astMalloc( sizeof( double )*(size_t) naxes ); /* Check pointers can be used safely. */ if( astOK ) { /* Create a Mapping (a ShiftMap) from IWC to PPC. */ for( i = 0; i < naxes; i++ ) shifts[ i ] = 0.0; shifts[ axlon ] = x0; shifts[ axlat ] = y0; shiftmap = (AstMapping *) astShiftMap( naxes, shifts, "", status ); /* Produce a CmpMap which combines "map1" (which converts degrees to radians on the celestial axes) with the above ShiftMap. */ newmap = (AstMapping *) astCmpMap( map1, shiftmap, 1, "", status ); /* Annul the component Mappings and use the new one in place of map1. */ shiftmap = astAnnul( shiftmap ); map1 = astAnnul( map1 ); map1 = newmap; } /* Free resources. */ shifts = astFree( shifts ); } } /* Now concatenate the Mappings to produce the returned Mapping. */ map4 = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); ret = (AstMapping *) astCmpMap( map4, map3, 1, "", status ); /* Annul the component Mappings. */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); map4 = astAnnul( map4 ); /* We now make changes to the supplied Frame so that the longitude and latitude axes are described by a SkyFrame. First create an appropriate SkyFrame. */ sfrm = WcsSkyFrame( this, store, s, prj, wcscelestial_type, axlon, axlat, method, class, status ); /* The values currently stored in *reflat and *reflon are the CRVAL values. In some circumstances, these may not be the original values in the supplied header but may have been translated within the SpecTrans function as part of the process of translating an old unsupported projection into a new supported projection. Since the returned RefLat and RefLon values may be used to set the reference position for a SpecFrame, we should return the original values rather than the translated values. The original values will have been stored (within SpecTrans) in the FitsChan as keywords RFVALi. If such keywords can be found, use their values in preference to the currently stored CRVAL values.*/ if( GetValue( this, FormatKey( "RFVAL", axlon + 1, -1, s, status ), AST__FLOAT, (void *) &lonval, 0, 0, method, class, status ) && GetValue( this, FormatKey( "RFVAL", axlat + 1, -1, s, status ), AST__FLOAT, (void *) &latval, 0, 0, method, class, status ) ) { *reflon = lonval*AST__DD2R; *reflat = latval*AST__DD2R; } /* Store the reflon and reflat values as the SkyRef position in the SkyFrame, and set SkyRefIs to "ignore" so that the SkyFrame continues to represent absolute celestial coords. Do not change the SkyFrame if it already had a set reference posiiton. */ if( ! astTestSkyRef( sfrm, 0 ) ) { if( *reflon != AST__BAD && *reflat != AST__BAD ) { astSetSkyRef( sfrm, 0, *reflon ); astSetSkyRef( sfrm, 1, *reflat ); astSet( sfrm, "SkyRefIs=Ignored", status ); } } /* Return a clone of this SkyFrame as the reference Frame. */ *reffrm = astClone( sfrm ); /* Create a Frame by picking all the other (non-celestial) axes from the supplied Frame. */ axes = astMalloc( naxes*sizeof( int ) ); if( axes ) { j = 0; for( i = 0; i < naxes; i++ ) { if( i != axlat && i != axlon ) axes[ j++ ] = i; } /* If there were no other axes, replace the supplied Frame with the skyframe. */ if( j == 0 ) { (void) astAnnul( *frm ); *frm = (AstFrame *) astClone( sfrm ); /* Otherwise pick the other axes from the supplied Frame */ } else { ofrm = astPickAxes( *frm, j, axes, NULL ); /* Replace the supplied Frame with a CmpFrame made up of this Frame and the SkyFrame. */ (void) astAnnul( *frm ); *frm = (AstFrame *) astCmpFrame( ofrm, sfrm, "", status ); ofrm = astAnnul( ofrm ); } /* Permute the axis order to put the longitude and latitude axes back in their original position. The SkyFrame will have the default axis ordering (lon=axis 0, lat = axis 1). */ j = 0; for( i = 0; i < naxes; i++ ) { if( i == axlat ) { axes[ i ] = naxes - 1; } else if( i == axlon ) { axes[ i ] = naxes - 2; } else { axes[ i ] = j++; } } astPermAxes( *frm, axes ); /* Free the axes array. */ axes= astFree( axes ); } /* Set the units in the supplied IWC Frame for the longitude and latitude axes. Unless using -TAB, these are degrees (the conversion from degs to rads is part of the Mapping from IWC to WCS). If using -TAB the units are unknown. */ if( !tabaxis || !tabaxis[ axlon ] ) astSetUnit( iwcfrm, axlon, "deg" ); if( !tabaxis || !tabaxis[ axlat ] ) astSetUnit( iwcfrm, axlat, "deg" ); /* Modify any supplied tabmap so that the celestial outputs create radians rather than degrees (but only if the celestial axes are generated by the -TAB algorithm). */ if( tabaxis && tabaxis[ axlon ] && tabaxis[ axlat ] ) { mat = (double *) astMalloc( sizeof(double)*naxes ); if( mat ){ for( i = 0; i < naxes; i++ ){ if( i == axlat || i == axlon ){ mat[ i ] = AST__DD2R; } else { mat[ i ] = 1.0; } } map1 = (AstMapping *) astMatrixMap( naxes, naxes, 1, mat, "", status ); mat = (double *) astFree( (void *) mat ); map2 = (AstMapping *) astCmpMap( *tabmap, map1, 1, " ", status ); map1 = astAnnul( map1 ); (void) astAnnul( *tabmap ); *tabmap = map2; } /* Also modify the returned reflon and reflat values to transform them using the tabmap. Also transform the reference position in the SkyFrame. */ if( *reflon != AST__BAD && *reflat != AST__BAD ) { ina = astMalloc( sizeof(double)*naxes ); outa = astMalloc( sizeof(double)*naxes ); if( astOK ) { for( i = 0; i < naxes; i++ ) ina[ i ] = 0.0; ina[ axlat ] = *reflat; ina[ axlon ] = *reflon; astTranN( *tabmap, 1, naxes, 1, ina, 1, naxes, 1, outa ); *reflon = outa[ axlon ]; *reflat = outa[ axlat ]; } ina = astFree( ina ); outa = astFree( outa ); /* Store this transformed reference position in the SkyFrame. */ astSetSkyRef( sfrm, 0, *reflon ); astSetSkyRef( sfrm, 1, *reflat ); astSet( sfrm, "SkyRefIs=Ignored", status ); } } /* If the header contains AXREF values for both lon and lat axes, use them as the sky reference position in preferences to the values derived form the CRVAL values. AXREF keywords are created by the astWrite method for axes described by -TAB algorithm that have no inverse transformation. */ if( GetValue( this, FormatKey( "AXREF", axlon + 1, -1, s, status ), AST__FLOAT, (void *) &lonval, 0, 0, method, class, status ) && GetValue( this, FormatKey( "AXREF", axlat + 1, -1, s, status ), AST__FLOAT, (void *) &latval, 0, 0, method, class, status ) ) { *reflon = lonval*AST__DD2R; *reflat = latval*AST__DD2R; astSetSkyRef( sfrm, 0, *reflon ); astSetSkyRef( sfrm, 1, *reflat ); astSet( sfrm, "SkyRefIs=Ignored", status ); } /* Free resources. */ sfrm = astAnnul( sfrm ); } /* Return the result. */ return ret; } static void WcsFcRead( AstFitsChan *fc, AstFitsChan *fc2, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * WcsFcRead * Purpose: * Extract WCS information from a supplied FitsChan using a FITSWCS * encoding, and store it in the supplied FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WcsFcRead( AstFitsChan *fc, AstFitsChan *fc2, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function extracts FITSWCS keywords from the supplied FitsChan, * and stores the corresponding WCS information in the supplied FitsStore. * Parameters: * fc * Pointer to the FitsChan containing the cards read from the * original FITS header. This should not include any un-used * non-standard keywords. * fc2 * Pointer to a second FitsChan. If a card read from "fc" fails to * be converted to its correct data type, a warning is only issued * if there is no card for this keyword in "fc2". "fc2" may be NULL * in which case a warning is always issued. * store * Pointer to the FitsStore structure. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char buf[200]; /* Buffer for warning message */ char *cval; /* String keyword value */ char *keynam; /* Pointer to current keyword name */ char s; /* Co-ordinate version character */ double dval; /* Floating point keyword value */ int fld[2]; /* Integer field values from keyword name */ int jm; /* Pixel axis or projection parameter index */ int i; /* Intermediate axis index */ int mark; /* Non-zero if card should be removed once used */ int nfld; /* Number of integer fields in test string */ int ok; /* Was value converted succesfully? */ int type; /* Keyword data type */ int undef; /* Is an undefined keyword value acceptable? */ void *item; /* Pointer to item to get/put */ /* Check the global error status. */ if ( !astOK ) return; /* Ensure the FitsChan is re-wound. */ astClearCard( fc ); /* Loop round all the cards in the FitsChan obtaining the keyword name for each card. Note, the single "=" is correct in the following "while" statement. */ s = 0; jm = -1; i = -1; type = AST__NOTYPE; while( (keynam = CardName( fc, status )) ){ item = NULL; /* Assume the card is to be consumed by the reading process. This means the card will be marked as used and effectively excluded from the header. Keywords which supply observation details that do not depend on the mapping from pixel to WCS axes, or on the nature of the WCS axes, are not removed as they may be needed for other, non-WCS related, purposes. */ mark = 1; /* For most keywords, if the keyword is present in the header it must have a definded value. However, some keywords are read from the header but not actually used for anything. This is done to ensure that the keyword is stripped from the header. It is acceptable for such keywords to have an undefined value. Initialise a flag indicating that the next keyword read is not allowed to have an undefined value. */ undef = 0; /* Is this a primary CRVAL keyword? */ if( Match( keynam, "CRVAL%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->crval); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary CRVAL keyword? */ } else if( Match( keynam, "CRVAL%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->crval); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary CRPIX keyword? */ } else if( Match( keynam, "CRPIX%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->crpix); type = AST__FLOAT; i = 0; jm = fld[ 0 ] - 1; s = ' '; /* Is this a secondary CRPIX keyword? */ } else if( Match( keynam, "CRPIX%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->crpix); type = AST__FLOAT; i = 0; jm = fld[ 0 ] - 1; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary CDELT keyword? */ } else if( Match( keynam, "CDELT%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->cdelt); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary CDELT keyword? */ } else if( Match( keynam, "CDELT%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->cdelt); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary CTYPE keyword? If so, store the associated comment. */ } else if( Match( keynam, "CTYPE%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->ctype); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = ' '; SetItemC( &(store->ctype_com), i, 0, ' ', CardComm( fc, status ), status ); /* Is this a secondary CTYPE keyword? If so, store the associated comment. */ } else if( Match( keynam, "CTYPE%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->ctype); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; SetItemC( &(store->ctype_com), i, 0, s, CardComm( fc, status ), status ); /* Is this a primary CNAME keyword? */ } else if( Match( keynam, "CNAME%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->cname); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary CNAME keyword? */ } else if( Match( keynam, "CNAME%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->cname); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary CUNIT keyword? */ } else if( Match( keynam, "CUNIT%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->cunit); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary CUNIT keyword? */ } else if( Match( keynam, "CUNIT%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->cunit); type = AST__STRING; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary PC keyword? */ } else if( Match( keynam, "PC%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->pc); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = fld[ 1 ] - 1; s = ' '; /* Is this a secondary PC keyword? */ } else if( Match( keynam, "PC%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->pc); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = fld[ 1 ] - 1; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary PV keyword? */ } else if( Match( keynam, "PV%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->pv); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = fld[ 1 ]; s = ' '; /* Is this a secondary PV keyword? */ } else if( Match( keynam, "PV%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->pv); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary PS keyword? */ } else if( Match( keynam, "PS%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->ps); type = AST__STRING; i = fld[ 0 ] - 1; jm = fld[ 1 ]; s = ' '; /* Is this a secondary PS keyword? */ } else if( Match( keynam, "PS%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->ps); type = AST__STRING; i = fld[ 0 ] - 1; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary RADESYS keyword? */ } else if( Match( keynam, "RADESYS", 0, fld, &nfld, method, class, status ) ){ item = &(store->radesys); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Is this a secondary RADESYS keyword? */ } else if( Match( keynam, "RADESYS%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->radesys); type = AST__STRING; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary EQUINOX keyword? */ } else if( Match( keynam, "EQUINOX", 0, fld, &nfld, method, class, status ) ){ item = &(store->equinox); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary EQUINOX keyword? */ } else if( Match( keynam, "EQUINOX%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->equinox); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary LATPOLE keyword? */ } else if( Match( keynam, "LATPOLE", 0, fld, &nfld, method, class, status ) ){ item = &(store->latpole); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary LATPOLE keyword? */ } else if( Match( keynam, "LATPOLE%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->latpole); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary LONPOLE keyword? */ } else if( Match( keynam, "LONPOLE", 0, fld, &nfld, method, class, status ) ){ item = &(store->lonpole); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary LONPOLE keyword? */ } else if( Match( keynam, "LONPOLE%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->lonpole); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary WXSAXES keyword? */ } else if( Match( keynam, "WCSAXES", 0, fld, &nfld, method, class, status ) ){ item = &(store->wcsaxes); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary WCSAXES keyword? */ } else if( Match( keynam, "WCSAXES%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->wcsaxes); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary DUT1 keyword? */ } else if( Match( keynam, "DUT1", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->dut1); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a primary MJD-OBS keyword? */ } else if( Match( keynam, "MJD-OBS", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->mjdobs); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a primary WCSNAME keyword? */ } else if( Match( keynam, "WCSNAME", 0, fld, &nfld, method, class, status ) ){ item = &(store->wcsname); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Is this a secondary WCSNAME keyword? */ } else if( Match( keynam, "WCSNAME%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->wcsname); type = AST__STRING; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary SPECSYS keyword? */ } else if( Match( keynam, "SPECSYS", 0, fld, &nfld, method, class, status ) ){ item = &(store->specsys); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Is this a secondary SPECSYS keyword? */ } else if( Match( keynam, "SPECSYS%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->specsys); type = AST__STRING; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary SSYSSRC keyword? */ } else if( Match( keynam, "SSYSSRC", 0, fld, &nfld, method, class, status ) ){ item = &(store->ssyssrc); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Is this a secondary SSYSSRC keyword? */ } else if( Match( keynam, "SSYSSRC%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->ssyssrc); type = AST__STRING; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary ZSOURCE keyword? */ } else if( Match( keynam, "ZSOURCE", 0, fld, &nfld, method, class, status ) ){ item = &(store->zsource); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary ZSOURCE keyword? */ } else if( Match( keynam, "ZSOURCE%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->zsource); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary VELOSYS keyword? */ } else if( Match( keynam, "VELOSYS", 0, fld, &nfld, method, class, status ) ){ item = &(store->velosys); type = AST__FLOAT; undef = 1; i = 0; jm = 0; s = ' '; /* Is this a secondary VELOSYS keyword? */ } else if( Match( keynam, "VELOSYS%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->velosys); type = AST__FLOAT; undef = 1; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary RESTFRQ keyword? */ } else if( Match( keynam, "RESTFRQ", 0, fld, &nfld, method, class, status ) ){ item = &(store->restfrq); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary RESTFRQ keyword? */ } else if( Match( keynam, "RESTFRQ%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->restfrq); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary RESTWAV keyword? */ } else if( Match( keynam, "RESTWAV", 0, fld, &nfld, method, class, status ) ){ item = &(store->restwav); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a secondary RESTWAV keyword? */ } else if( Match( keynam, "RESTWAV%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->restwav); type = AST__FLOAT; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary IMAGFREQ keyword? */ } else if( Match( keynam, "IMAGFREQ", 0, fld, &nfld, method, class, status ) ){ item = &(store->imagfreq); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a primary SKYREF keyword? */ } else if( Match( keynam, "SREF%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->skyref); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary SKYREF keyword? */ } else if( Match( keynam, "SREF%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->skyref); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary SKYREFP keyword? */ } else if( Match( keynam, "SREFP%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->skyrefp); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary SKYREFP keyword? */ } else if( Match( keynam, "SREFP%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->skyrefp); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary SKYREFIS keyword? */ } else if( Match( keynam, "SREFIS", 0, fld, &nfld, method, class, status ) ){ item = &(store->skyrefis); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Is this a secondary SKYREFIS keyword? */ } else if( Match( keynam, "SREFIS%1c", 0, fld, &nfld, method, class, status ) ){ item = &(store->skyrefis); type = AST__STRING; i = 0; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary AXREF keyword? */ } else if( Match( keynam, "AXREF%d", 1, fld, &nfld, method, class, status ) ){ item = &(store->axref); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = ' '; /* Is this a secondary AXREF keyword? */ } else if( Match( keynam, "AXREF%d%1c", 1, fld, &nfld, method, class, status ) ){ item = &(store->axref); type = AST__FLOAT; i = fld[ 0 ] - 1; jm = 0; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a MJD-AVG keyword? */ } else if( Match( keynam, "MJD-AVG", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->mjdavg); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a OBSGEO-X keyword? */ } else if( Match( keynam, "OBSGEO-X", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->obsgeox); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a OBSGEO-Y keyword? */ } else if( Match( keynam, "OBSGEO-Y", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->obsgeoy); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a OBSGEO-Z keyword? */ } else if( Match( keynam, "OBSGEO-Z", 0, fld, &nfld, method, class, status ) ){ mark = 0; item = &(store->obsgeoz); type = AST__FLOAT; i = 0; jm = 0; s = ' '; /* Is this a TIMESYS keyword? */ } else if( Match( keynam, "TIMESYS", 0, fld, &nfld, method, class, status ) ){ item = &(store->timesys); type = AST__STRING; i = 0; jm = 0; s = ' '; /* Following keywords are used to describe "-SIP" distortion as used by the Spitzer project... */ /* Is this a primary A keyword? */ } else if( Match( keynam, "A_%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->asip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = ' '; /* Is this a secondary A keyword? */ } else if( Match( keynam, "A_%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->asip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary B keyword? */ } else if( Match( keynam, "B_%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->bsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = ' '; /* Is this a secondary B keyword? */ } else if( Match( keynam, "B_%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->bsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary AP keyword? */ } else if( Match( keynam, "AP_%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->apsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = ' '; /* Is this a secondary AP keyword? */ } else if( Match( keynam, "AP_%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->apsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; /* Is this a primary BP keyword? */ } else if( Match( keynam, "BP_%d_%d", 2, fld, &nfld, method, class, status ) ){ item = &(store->bpsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = ' '; /* Is this a secondary BP keyword? */ } else if( Match( keynam, "BP_%d_%d%1c", 2, fld, &nfld, method, class, status ) ){ item = &(store->bpsip); type = AST__FLOAT; i = fld[ 0 ]; jm = fld[ 1 ]; s = keynam[ strlen( keynam ) - 1 ]; } /* If this keyword was recognized, store it in the FitsStore, and mark it as having been read. */ if( item ){ ok = 1; if( type == AST__FLOAT ){ if( CnvValue( fc, AST__FLOAT, undef, &dval, method, status ) ) { SetItem( (double ****) item, i, jm, s, dval, status ); if( mark ) MarkCard( fc, status ); } else { ok = 0; } } else { if( CnvValue( fc, AST__STRING, undef, &cval, method, status ) ) { cval[ astChrLen( cval ) ] = 0; /* Exclude trailing spaces */ SetItemC( (char *****) item, i, jm, s, cval, status ); if( mark ) MarkCard( fc, status ); } else { ok = 0; } } /* Issue a warning if the value could not be converted to the expected type. */ if( !ok ) { /* First check that the keyword is not included in "fc2". */ if( !HasCard( fc2, keynam, method, class, status ) ) { sprintf( buf, "The original FITS header contained a value for " "keyword %s which could not be converted to a %s.", keynam, ( type==AST__FLOAT ? "floating point number": "character string" ) ); Warn( fc, "badval", buf, "astRead", "FitsChan", status ); } } } /* Move on to the next card. */ MoveCard( fc, 1, method, class, status ); } } static int WcsFromStore( AstFitsChan *this, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * WcsFromStore * Purpose: * Store WCS keywords in a FitsChan using FITS-WCS encoding. * Type: * Private function. * Synopsis: * int WcsFromStore( AstFitsChan *this, FitsStore *store, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function copies the WCS information stored in the supplied * FitsStore into the supplied FitsChan, using FITS-WCS encoding. * Parameters: * this * Pointer to the FitsChan. * store * Pointer to the FitsStore. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A value of 1 is returned if succesfull, and zero is returned * otherwise. */ /* Local Variables: */ char *comm; /* Pointer to comment string */ char *cval; /* Pointer to string keyword value */ char parprefix[3]; /* Prefix for projection parameter keywords */ char combuf[80]; /* Buffer for FITS card comment */ char s; /* Co-ordinate version character */ char sign[2]; /* Fraction's sign character */ char sup; /* Upper limit on s */ char type[MXCTYPELEN];/* Buffer for CTYPE value */ double cdl; /* CDELT value */ double fd; /* Fraction of a day */ double mjd99; /* MJD at start of 1999 */ double val; /* General purpose value */ int *tabaxis; /* Flags WCS axes that use -TAB algorithm */ int i; /* Axis index */ int ihmsf[ 4 ]; /* Hour, minute, second, fractional second */ int iymdf[ 4 ]; /* Year, month, date, fractional day */ int j; /* Axis index */ int jj; /* SlaLib status */ int m; /* Parameter index */ int maxm; /* Upper limit on m */ int naxis; /* Value of NAXIS keyword */ int nc; /* Length of STYPE string */ int nwcs; /* No. of WCS axes */ int ok; /* Frame created succesfully? */ int prj; /* Projection type */ int ret; /* Returned value */ /* Initialise */ ret = 0; /* Other initialisation to avoid compiler warnings. */ tabaxis = NULL; /* Check the inherited status. */ if( !astOK ) return ret; /* If the FitsChan contains a value for the NAXIS keyword, note it. Otherwise store -1. */ if( !astGetFitsI( this, "NAXIS", &naxis ) ) naxis = -1; /* Find the last WCS related card. */ FindWcs( this, 1, 1, 0, method, class, status ); /* Loop round all co-ordinate versions */ sup = GetMaxS( &(store->crval), status ); for( s = ' '; s <= sup && astOK; s++ ){ /* For alternate axes, skip this axis description if there is no CRPIX1 or CRVAL1 value. This avoids partial axis descriptions being written out. */ if( s != ' ' ) { if( GetItem( &(store->crpix), 0, 0, s, NULL, method, class, status ) == AST__BAD || GetItem( &(store->crval), 0, 0, s, NULL, method, class, status ) == AST__BAD ) { ok = 0; goto next; } } /* Assume the Frame can be created succesfully. */ ok = 1; /* Save the number of wcs axes. If a value for WCSAXES has been set, or if the number of axes is not the same as specified in the NAXIS keyword, store a WCSAXES keyword. */ val = GetItem( &(store->wcsaxes), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { nwcs = (int) ( val + 0.5 ); } else { nwcs = GetMaxJM( &(store->crpix), s, status ) + 1; if( nwcs != 0 && nwcs != naxis ) val = (double) nwcs; } if( val != AST__BAD ) { SetValue( this, FormatKey( "WCSAXES", -1, -1, s, status ), &nwcs, AST__INT, "Number of WCS axes", status ); } /* Get and save WCSNAME. This is NOT required, so do not return if it is not available. If the WCS is 1-d, only store WCSNAME if its value is different to the CTYPE1 value. */ cval = GetItemC( &(store->wcsname), 0, 0, s, NULL, method, class, status ); if( cval && nwcs == 1 ) { comm = GetItemC( &(store->ctype), 0, 0, s, NULL, method, class, status ); if( comm && Similar( comm, cval, status ) ) cval = NULL; } if( cval ) SetValue( this, FormatKey( "WCSNAME", -1, -1, s, status ), &cval, AST__STRING, "Reference name for the coord. frame", status ); /* The prefix for numerical projection parameters is usually "PV". */ strcpy( parprefix, "PV" ); /* Keywords common to all axis types... */ /* Get and save CRPIX for all pixel axes. These are required, so pass on if they are not available. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->crpix), 0, i, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Reference pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRPIX", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } /* Get and save CRVAL for all WCS axes. These are required, so pass on if they are not available. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Value at ref. pixel on axis %d", i + 1 ); SetValue( this, FormatKey( "CRVAL", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } /* Allocate memory to indicate if each WCS axis is described by a -TAB algorithm or not. Initialiss it to zero. */ tabaxis = astCalloc( nwcs, sizeof( int ) ); /* Get and save CTYPE for all WCS axes. These are required, so pass on if they are not available. */ for( i = 0; i < nwcs; i++ ) { cval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( !cval ) { ok = 0; goto next; } comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm ) { sprintf( combuf, "Type of co-ordinate on axis %d", i + 1 ); comm = combuf; } /* Extract the projection type as specified by the last 4 characters in the CTYPE keyword value. This will be AST__WCSBAD for non-celestial axes. Note, CTYPE can be more than 8 characters long. */ nc = strlen( cval ); prj = ( nc > 4 ) ? astWcsPrjType( cval + nc - 4 ) : AST__WCSBAD; /* If the projection type is "TPN" (an AST-specific code) convert it to standard FITS-WCS code "TAN" and change the prefix for projection parameters from "PV" to "QV". AST will do the inverse conversions when reading such a header. Non-AST software will simply ignore the QV terms and interpret the header as a simple TAN projection. */ if( prj == AST__TPN ) { strcpy( parprefix, "QV" ); strcpy( type, cval ); (void) strcpy( type + nc - 4, "-TAN" ); cval = type; } /* Note if the axis is described by the -TAB algorithm. */ tabaxis[ i ] = ( prj == AST__WCSBAD && strlen( cval ) >= 8 && !strncmp( cval + 4, "-TAB", 4 ) ); /* Store the (potentially modified) CTYPE value. */ SetValue( this, FormatKey( "CTYPE", i + 1, -1, s, status ), &cval, AST__STRING, comm, status ); } /* Get and save CNAME for all WCS axes. These are NOT required, so do not pass on if they are not available. Do not include a CNAME keyword if its value equals the commen or value of the corresponding CTYPE keyword. */ for( i = 0; i < nwcs; i++ ) { cval = GetItemC( &(store->cname), i, 0, s, NULL, method, class, status ); if( cval ) { comm = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( !comm || strcmp( comm, cval ) ) { comm = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !comm || strcmp( comm, cval ) ) { sprintf( combuf, "Description of axis %d", i + 1 ); SetValue( this, FormatKey( "CNAME", i + 1, -1, s, status ), &cval, AST__STRING, combuf, status ); } } } } /* Now choose whether to produce CDi_j or CDELT/PCi_j keywords. */ if( astGetCDMatrix( this ) ) { /* CD matrix. Multiply the row of the PC matrix by the CDELT value. */ for( i = 0; i < nwcs; i++ ) { cdl = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( cdl == AST__BAD ) cdl = 1.0; for( j = 0; j < nwcs; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val == AST__BAD ) val = ( i == j ) ? 1.0 : 0.0; val *= cdl; if( val != 0.0 ) { SetValue( this, FormatKey( "CD", i + 1, j + 1, s, status ), &val, AST__FLOAT, "Transformation matrix element", status ); } } } /* If producing PC/CDELT keywords... */ } else { /* CDELT keywords. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->cdelt), i, 0, s, NULL, method, class, status ); if( val == AST__BAD ) { ok = 0; goto next; } sprintf( combuf, "Pixel size on axis %d", i + 1 ); SetValue( this, FormatKey( "CDELT", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } /* PC matrix. */ for( i = 0; i < nwcs; i++ ) { for( j = 0; j < nwcs; j++ ){ val = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); if( val != AST__BAD ) { if( i == j ) { if( astEQUAL( val, 1.0 ) ) val = AST__BAD; } else { if( astEQUAL( val, 0.0 ) ) val = AST__BAD; } } if( val != AST__BAD ) { SetValue( this, FormatKey( "PC", i + 1, j + 1, s, status ), &val, AST__FLOAT, "Transformation matrix element", status ); } } } } /* Get and save CUNIT for all WCS axes. These are NOT required, so do not pass on if they are not available. */ for( i = 0; i < nwcs; i++ ) { cval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( cval ) { sprintf( combuf, "Units for axis %d", i + 1 ); SetValue( this, FormatKey( "CUNIT", i + 1, -1, s, status ), &cval, AST__STRING, combuf, status ); } } /* Get and save AXREF for all WCS axes. These are NOT required, so do not pass on if they are not available. Note, AXREF is a non-standard keyword used by AST to communicate the reference position on any axes described by the -TAB algorithm and which has no inverse transformation. For all other cases, the reference position corresponds to the values of CRVAL. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->axref), i, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { sprintf( combuf, "Reference WCS value on axis %d", i + 1 ); SetValue( this, FormatKey( "AXREF", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save SREFIS. This is NOT required, so do not return if it is not available. Note, SREFIS is a non-standard keyword used by AST to communicate the SkyRefIs attribute in the original SkyFrame. */ cval = GetItemC( &(store->skyrefis), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, FormatKey( "SREFIS", -1, -1, s, status ), &cval, AST__STRING, "Is SkyRef used as pole or origin?", status ); /* Get and save SREF for all WCS axes. These are NOT required, so do not pass on if they are not available. Note, SREF is a non-standard keyword used by AST to communicate the SkyRef position on any axes described by a offset SkyFrame. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->skyref), i, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { sprintf( combuf, "Sky reference position on axis %d", i + 1 ); SetValue( this, FormatKey( "SREF", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Get and save SREFP for all WCS axes. These are NOT required, so do not pass on if they are not available. Note, SREFP is a non-standard keyword used by AST to communicate the SkyRefP position on any axes described by a offset SkyFrame. */ for( i = 0; i < nwcs; i++ ) { val = GetItem( &(store->skyrefp), i, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { sprintf( combuf, "Sky primary meridian position on axis %d", i + 1 ); SetValue( this, FormatKey( "SREFP", i + 1, -1, s, status ), &val, AST__FLOAT, combuf, status ); } } /* Date of observation (only allowed for primary axis descriptions). */ if( s == ' ' ) { val = GetItem( &(store->mjdobs), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { SetValue( this, FormatKey( "MJD-OBS", -1, -1, s, status ), &val, AST__FLOAT, "Modified Julian Date of observation", status ); /* The format used for the DATE-OBS keyword depends on the value of the keyword. For DATE-OBS < 1999.0, use the old "dd/mm/yy" format. Otherwise, use the new "ccyy-mm-ddThh:mm:ss[.ssss]" format. */ palCaldj( 99, 1, 1, &mjd99, &jj ); if( val < mjd99 ) { palDjcal( 0, val, iymdf, &jj ); sprintf( combuf, "%2.2d/%2.2d/%2.2d", iymdf[ 2 ], iymdf[ 1 ], iymdf[ 0 ] - ( ( iymdf[ 0 ] > 1999 ) ? 2000 : 1900 ) ); } else { palDjcl( val, iymdf, iymdf+1, iymdf+2, &fd, &jj ); palDd2tf( 3, fd, sign, ihmsf ); sprintf( combuf, "%4.4d-%2.2d-%2.2dT%2.2d:%2.2d:%2.2d.%3.3d", iymdf[0], iymdf[1], iymdf[2], ihmsf[0], ihmsf[1], ihmsf[2], ihmsf[3] ); } /* Now store the formatted string in the FitsChan. */ cval = combuf; SetValue( this, "DATE-OBS", (void *) &cval, AST__STRING, "Date of observation", status ); } val = GetItem( &(store->mjdavg), 0, 0, ' ', NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "MJD-AVG", &val, AST__FLOAT, "Average Modified Julian Date of observation", status ); /* Store the timescale in TIMESYS. */ cval = GetItemC( &(store->timesys), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, "TIMESYS", &cval, AST__STRING, "Timescale for MJD-OBS/MJD-AVG values", status ); } /* Numerical projection parameters */ maxm = GetMaxJM( &(store->pv), s, status ); for( i = 0; i < nwcs; i++ ){ for( m = 0; m <= maxm; m++ ){ val = GetItem( &(store->pv), i, m, s, NULL, method, class, status ); if( val != AST__BAD ) { /* If the axis uses the "TAB" algorithm, there may be a PVi_4a parameter in the FitsStore. This is an AST extension to the published -TAB algorithm, and is used to hold the interpolation method. To avoid clashing with any standard use of PV1_4a, rename it to QVi_4a. The default is zero (linear interpolation) so do not write the QV value if it zero. */ if( m == 4 && tabaxis[ i ] ) { if( val != 0.0 ) { SetValue( this, FormatKey( "QV", i + 1, m, s, status ), &val, AST__FLOAT, "Use nearest neighbour " "interpolation", status ); } /* Just store the parameters for other type of axes. */ } else { SetValue( this, FormatKey( parprefix, i + 1, m, s, status ), &val, AST__FLOAT, "Projection parameter", status ); } } } } /* String projection parameters */ maxm = GetMaxJMC( &(store->ps), s, status ); for( i = 0; i < nwcs; i++ ){ for( m = 0; m <= maxm; m++ ){ cval = GetItemC( &(store->ps), i, m, s, NULL, method, class, status ); if( cval ) { SetValue( this, FormatKey( "PS", i + 1, m, s, status ), &cval, AST__STRING, "Projection parameter", status ); } } } /* Keywords specific to celestial axes... */ /* Get and save RADESYS. This is NOT required, so do not return if it is not available. */ cval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, FormatKey( "RADESYS", -1, -1, s, status ), &cval, AST__STRING, "Reference frame for RA/DEC values", status ); /* Reference equinox */ val = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "EQUINOX", -1, -1, s, status ), &val, AST__FLOAT, "[yr] Epoch of reference equinox", status ); /* Latitude of native north pole */ val = GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "LATPOLE", -1, -1, s, status ), &val, AST__FLOAT, "[deg] Latitude of native north pole", status ); /* Longitude of native north pole */ val = GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "LONPOLE", -1, -1, s, status ), &val, AST__FLOAT, "[deg] Longitude of native north pole", status ); /* Keywords specific to spectral axes... */ /* SPECSYS - the standard of rest for the spectral axis */ cval = GetItemC( &(store->specsys), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, FormatKey( "SPECSYS", -1, -1, s, status ), &cval, AST__STRING, "Standard of rest for spectral axis", status ); /* SSYSSRC - the standard of rest in which ZSOURCE is stored. */ cval = GetItemC( &(store->ssyssrc), 0, 0, s, NULL, method, class, status ); if( cval ) SetValue( this, FormatKey( "SSYSSRC", -1, -1, s, status ), &cval, AST__STRING, "Standard of rest for source redshift", status ); /* ZSOURCE - topocentric optical velocity of source */ val = GetItem( &(store->zsource), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "ZSOURCE", -1, -1, s, status ), &val, AST__FLOAT, "[] Redshift of source", status ); /* VELOSYS - topocentric apparent radial velocity of the standard of rest. */ val = GetItem( &(store->velosys), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "VELOSYS", -1, -1, s, status ), &val, AST__FLOAT, "[m/s] Topo. apparent velocity of rest frame", status ); /* RESTFRQ - rest frequency */ val = GetItem( &(store->restfrq), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "RESTFRQ", -1, -1, s, status ), &val, AST__FLOAT, "[Hz] Rest frequency", status ); /* RESTWAV - rest wavelength */ val = GetItem( &(store->restwav), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, FormatKey( "RESTWAV", -1, -1, s, status ), &val, AST__FLOAT, "[m] Rest wavelength", status ); /* The image frequency corresponding to the rest frequency (only used for double sideband data). This is not part of the FITS-WCS standard but is added for the benefit of JACH. */ val = GetItem( &(store->imagfreq), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) { SetValue( this, "IMAGFREQ", &val, AST__FLOAT, "[Hz] Image frequency", status ); } /* OBSGEO-X/Y/Z - observer's geocentric coords. Note, these always refer to the primary axes. */ if( s == ' ' ) { val = GetItem( &(store->obsgeox), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "OBSGEO-X", &val, AST__FLOAT, "[m] Observatory geocentric X", status ); val = GetItem( &(store->obsgeoy), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "OBSGEO-Y", &val, AST__FLOAT, "[m] Observatory geocentric Y", status ); val = GetItem( &(store->obsgeoz), 0, 0, s, NULL, method, class, status ); if( val != AST__BAD ) SetValue( this, "OBSGEO-Z", &val, AST__FLOAT, "[m] Observatory geocentric Z", status ); } /* See if a Frame was sucessfully written to the FitsChan. */ next: ok = ok && astOK; /* If so, indicate we have something to return. */ if( ok ) ret = 1; /* If we are producing secondary axes, clear any error status so we can continue to produce the next Frame. Retain the error if the primary axes could not be produced. After the primary axes, do the A axes. */ if( s != ' ' ) { astClearStatus; } else { s = 'A' - 1; } /* Remove the secondary "new" flags from the FitsChan. This flag is associated with cards which have been added to the FitsChan during this pass through the main loop in this function. If the Frame was written out succesfully, just clear the flags. If anything went wrong with this Frame, remove the flagged cards from the FitsChan. */ FixNew( this, NEW2, !ok, method, class, status ); /* Set the current card so that it points to the last WCS-related keyword in the FitsChan (whether previously read or not). */ FindWcs( this, 1, 1, 0, method, class, status ); /* Free resources. */ tabaxis = astFree( tabaxis ); } /* Return zero or ret depending on whether an error has occurred. */ return astOK ? ret : 0; } static AstMapping *WcsIntWorld( AstFitsChan *this, FitsStore *store, char s, int naxes, const char *method, const char *class, int *status ){ /* * Name: * WcsIntWorld * Purpose: * Create a Mapping from pixel coords to intermediate world coords. * Type: * Private function. * Synopsis: * AstMapping *WcsIntWorld( AstFitsChan *this, FitsStore *store, char s, * int naxes, const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function interprets the contents of the supplied FitsStore * structure, and creates a Mapping which describes the transformation * from pixel coordinates to intermediate world coordinates, using the * FITS World Coordinate System conventions. This is a general linear * transformation described by the CRPIXj, PCi_j and CDELTi keywords. * Parameters: * this * The FitsChan. ASTWARN cards may be added to this FitsChan if any * anomalies are found in the keyword values in the FitsStore. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstMapping *mapd1; /* Pointer to first distortion Mapping */ AstMapping *mapd2; /* Pointer to second distortion Mapping */ AstMapping *mapd3; /* Pointer to third distortion Mapping */ AstMapping *mapd4; /* Pointer to fourth distortion Mapping */ AstMapping *map0; /* Pointer to a Mapping */ AstMapping *map1; /* Pointer to a Mapping */ AstMapping *ret; /* Pointer to the returned Mapping */ /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* First of all, check the CTYPE keywords to see if they contain any known distortion codes (following the syntax described in FITS-WCS paper IV). If so, Mappings are returned which represents the distortions to be applied at each point in the chain of Mappings produced by this function. Any distortion codes are removed from the CTYPE values in the FitsStore. */ DistortMaps( this, store, s, naxes, &mapd1, &mapd2, &mapd3, &mapd4, method, class, status ); /* If distortion is to be applied now, initialise the returned Mapping to be the distortion. */ if( mapd1 ) ret = mapd1; /* Try to create a WinMap which translates the pixel coordinates so that they are refered to an origin at the reference pixel. This subtracts the value of CRPIXi from axis i. */ map1 = (AstMapping *) WcsShift( store, s, naxes, method, class, status ); /* Combine this with any previous Mapping. */ if( ret ) { map0 = (AstMapping *) astCmpMap( ret, map1, 1, "", status ); ret = astAnnul( ret ); map1 = astAnnul( map1 ); ret = map0; } else { ret = map1; } /* If distortion is to be applied now, combine the two Mappings. */ if( mapd2 ) { map0 = (AstMapping *) astCmpMap( ret, mapd2, 1, "", status ); ret = astAnnul( ret ); mapd2 = astAnnul( mapd2 ); ret = map0; } /* Now try to create a MatrixMap to implement the PC matrix. Combine it with the above Mapping. Add a Warning if this mapping cannot be inverted. */ map1 = (AstMapping *) WcsPCMatrix( store, s, naxes, method, class, status ); if( !astGetTranInverse( map1 ) ) { Warn( this, "badmat", "The pixel rotation matrix in the original FITS " "header (specified by CD or PC keywords) could not be inverted. " "This may be because the matrix contains rows or columns which " "are entirely zero.", method, class, status ); } map0 = (AstMapping *) astCmpMap( ret, map1, 1, "", status ); ret = astAnnul( ret ); map1 = astAnnul( map1 ); ret = map0; /* If distortion is to be applied now, combine the two Mappings. */ if( mapd3 ) { map0 = (AstMapping *) astCmpMap( ret, mapd3, 1, "", status ); ret = astAnnul( ret ); mapd3 = astAnnul( mapd3 ); ret = map0; } /* Now try to create a diagonal MatrixMap to implement the CDELT scaling. Combine it with the above Mapping. */ map1 = (AstMapping *) WcsCDeltMatrix( store, s, naxes, method, class, status ); map0 = (AstMapping *) astCmpMap( ret, map1, 1, "", status ); ret = astAnnul( ret ); map1 = astAnnul( map1 ); ret = map0; /* If distortion is to be applied now, combine the two Mappings. */ if( mapd4 ) { map0 = (AstMapping *) astCmpMap( ret, mapd4, 1, "", status ); ret = astAnnul( ret ); mapd4 = astAnnul( mapd4 ); ret = map0; } /* Return the result. */ return ret; } static AstMapping *WcsMapFrm( AstFitsChan *this, FitsStore *store, char s, AstFrame **frm, const char *method, const char *class, int *status ){ /* * Name: * WcsMapFrm * Purpose: * Create a Mapping and Frame for the WCS transformations described in a * FITS header. * Type: * Private function. * Synopsis: * AstMapping *WcsMapFrm( AstFitsChan *this, FitsStore *store, char s, * AstFrame **frm, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function interprets the contents of the supplied FitsStore * structure, and creates a Mapping which describes the transformation * from pixel coordinates to world coordinates, using the FITS World * Coordinate System conventions. It also creates a Frame describing * the world coordinate axes. * Parameters: * this * The FitsChan. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * frm * The address of a location at which to store a pointer to the * Frame describing the world coordinate axes. If the Iwc attribute * is non-zero, then this is actually a FrameSet in which the current * Frame is the required WCS system. The FrameSet also contains one * other Frame which defines the FITS IWC system. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstFrame *iwcfrm; /* Frame defining IWC system */ AstFrameSet *fs; /* Pointer to returned FrameSet */ AstMapping *map10; /* Pointer to a Mapping */ AstMapping *map1; /* Pointer to a Mapping */ AstMapping *map2; /* Pointer to a Mapping */ AstMapping *map3; /* Pointer to a Mapping */ AstMapping *map4; /* Pointer to a Mapping */ AstMapping *map5; /* Pointer to a Mapping */ AstMapping *map6; /* Pointer to a Mapping */ AstMapping *map7; /* Pointer to a Mapping */ AstMapping *map8; /* Pointer to a Mapping */ AstMapping *map9; /* Pointer to a Mapping */ AstMapping *ret; /* Pointer to the returned Mapping */ AstMapping *tabmap; /* Mapping from psi to WCS (paper III - 6.1.2) */ AstSkyFrame *reffrm; /* SkyFrame defining reflon and reflat */ char id[2]; /* ID string for returned Frame */ char iwc[5]; /* Domain name for IWC Frame */ const char *cc; /* Pointer to Domain */ double dut1; /* UT1-UTC correction in days */ double dval; /* Temporary double value */ double reflat; /* Reference celestial latitude */ double reflon; /* Reference celestial longitude */ int *tabaxis; /* Flags indicating -TAB axes */ int wcsaxes; /* Number of physical axes */ /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Identify any axes that use the -TAB algoritm code described in FITS-WCS paper III, and convert their CTYPE values to describe linear axes (i.e. just remove "-TAB" from the CTYPE value). This also returns a Mapping (which includes one or more LutMaps) that should be applied to the resulting linear axis values in order to generate the final WCS axis values. A NULL pointer is returned if no axes use -TAB. */ tabmap = TabMapping( this, store, s, &tabaxis, method, class, status ); /* Obtain the number of physical axes in the header. If the WCSAXES header was specified, use it. Otherwise assume it is the same as the number of pixel axes. */ dval = GetItem( &(store->wcsaxes), 0, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) { wcsaxes = (int) dval + 0.5; } else { wcsaxes = store->naxis; } /* Create a simple Frame to represent IWC coords. */ iwcfrm = astFrame( wcsaxes, "Title=FITS Intermediate World Coordinates", status ); strcpy( iwc, "IWC" ); iwc[ 3 ]= s; iwc[ 4 ]= 0; astSetDomain( iwcfrm, iwc ); /* Create a simple Frame which will be used as the initial representation for the physical axes. This Frame will be changed later (or possibly replaced by a Frame of another class) when we know what type of physical axes we are dealing with. Set its Domain to "AST_FITSCHAN" This value is used to identify axes which have not been changed, and will be replaced before returning the final FrameSet. */ *frm = astFrame( wcsaxes, "Domain=AST_FITSCHAN", status ); /* Store the coordinate version character as the Ident attribute for the returned Frame. */ id[ 0 ] = s; id[ 1 ] = 0; astSetIdent( *frm, id ); /* Create a Mapping which goes from pixel coordinates to what FITS-WCS paper I calls "intermediate world coordinates". This stage is the same for all axes. It uses the CRPIXj, PCi_j and CDELTi headers (and distortion codes from the CTYPE keywords). */ map1 = WcsIntWorld( this, store, s, wcsaxes, method, class, status ); /* The conversion from intermediate world coordinates to the final world coordinates depends on the type of axis being converted (as specified by its CTYPE keyword). Check for each type of axis for which known conventions exist... */ /* Celestial coordinate axes. The following call returns a Mapping which transforms any celestial coordinate axes from intermediate world coordinates to the final celestial coordinates. Other axes are left unchanged by the Mapping. It also modifies the Frame so that a SkyFrame is used to describe the celestial axes. */ map2 = WcsCelestial( this, store, s, frm, iwcfrm, &reflon, &reflat, &reffrm, &tabmap, tabaxis, method, class, status ); /* Spectral coordinate axes. The following call returns a Mapping which transforms any spectral coordinate axes from intermediate world coordinates to the final spectral coordinates. Other axes are left unchanged by the Mapping. It also modifies the Frame so that a SpecFrame is used to describe the spectral axes. */ map3 = WcsSpectral( this, store, s, frm, iwcfrm, reflon, reflat, reffrm, method, class, status ); /* Any axes which were not recognized by the above calls are assumed to be linear. Create a Mapping which adds on the reference value for such axes, and modify the Frame to desribe the axes. */ map4 = WcsOthers( this, store, s, frm, iwcfrm, method, class, status ); /* If the Frame still has the Domain "AST_FITSCHAN", clear it. */ cc = astGetDomain( *frm ); if( cc && !strcmp( cc, "AST_FITSCHAN" ) ) astClearDomain( *frm ); /* Concatenate the Mappings and simplify the result. */ map5 = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); map6 = (AstMapping *) astCmpMap( map5, map3, 1, "", status ); map7 = (AstMapping *) astCmpMap( map6, map4, 1, "", status ); if( tabmap ) { map8 = (AstMapping *) astCmpMap( map7, tabmap, 1, "", status ); } else { map8 = astClone( map7 ); } ret = astSimplify( map8 ); /* Ensure that the coordinate version character is stored as the Ident attribute for the returned Frame (the above calls may have changed it). */ astSetIdent( *frm, id ); /* Set the DUT1 value. Note, the JACH store DUT1 in units of days in their FITS headers, so convert from days to seconds. May need to do somthing about this if the forthcoming FITS-WCS paper 5 (time axes) defines DUT1 to be in seconds. */ dut1 = GetItem( &(store->dut1), 0, 0, s, NULL, method, class, status ); if( dut1 != AST__BAD ) astSetDut1( *frm, dut1*SPD ); /* The returned Frame is actually a FrameSet in which the current Frame is the required WCS Frame. The FrameSet contains one other Frame, which is the Frame representing IWC. Create a FrameSet containing these two Frames. */ if( astGetIwc( this ) ) { fs = astFrameSet( iwcfrm, "", status ); astInvert( map1 ); map9 = (AstMapping *) astCmpMap( map1, ret, 1, "", status ); astInvert( map1 ); map10 = astSimplify( map9 ); astAddFrame( fs, AST__BASE, map10, *frm ); /* Return this FrameSet instead of the Frame. */ *frm = astAnnul( *frm ); *frm = (AstFrame *) fs; /* Free resources */ map9 = astAnnul( map9 ); map10 = astAnnul( map10 ); } /* Annull temporary resources. */ if( reffrm ) reffrm = astAnnul( reffrm ); if( tabmap ) tabmap = astAnnul( tabmap ); tabaxis = astFree( tabaxis ); iwcfrm = astAnnul( iwcfrm ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); map4 = astAnnul( map4 ); map5 = astAnnul( map5 ); map6 = astAnnul( map6 ); map7 = astAnnul( map7 ); map8 = astAnnul( map8 ); /* Annul thre returned objects if an error has occurred. */ if( !astOK ) { ret = astAnnul( ret ); *frm = astAnnul( *frm ); } /* Return the result. */ return ret; } static AstMatrixMap *WcsPCMatrix( FitsStore *store, char s, int naxes, const char *method, const char *class, int *status ){ /* * Name: * WcsPCMatrix * Purpose: * Create a MatrixMap representing the PC matrix. * Type: * Private function. * Synopsis: * AstMatrixMap *WcsPCMatrix( FitsStore *store, char s, int naxes, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A MatrixMap representing the FITS "PC" matrix is returned. * Parameters: * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character s identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the created MatrixMap or a NULL pointer if an * error occurred. */ /* Local Variables: */ AstMatrixMap *new; /* The created MatrixMap */ double *el; /* Pointer to next matrix element */ double *mat; /* Pointer to matrix array */ int i; /* Pixel axis index */ int j; /* Intermediate axis index. */ /* Initialise/ */ new = NULL; /* Check the global status. */ if ( !astOK ) return new; /* Allocate memory for the matrix. */ mat = (double *) astMalloc( sizeof(double)*naxes*naxes ); if( astOK ){ /* Fill the matrix with values from the FitsStore. */ el = mat; for( i = 0; i < naxes; i++ ){ for( j = 0; j < naxes; j++ ){ /* Get the PCj_i value for this axis. Missing terms can be defaulted so do not report an error if the required value is not present in the FitsStore. */ *el = GetItem( &(store->pc), i, j, s, NULL, method, class, status ); /* Diagonal terms default to to 1.0, off-diagonal to zero. */ if( *el == AST__BAD ) *el = ( i == j ) ? 1.0: 0.0; /* Move on to the next matrix element. */ el++; } } /* Create the matrix. */ new = astMatrixMap( naxes, naxes, 0, mat, "", status ); /* Report an error if the inverse transformation is undefined. */ if( !astGetTranInverse( new ) && astOK ) { astError( AST__BDFTS, "%s(%s): Unusable rotation matrix (PC or CD) found " "in the FITS-WCS header - the matrix cannot be inverted.", status, method, class ); } /* Release the memory used to hold the matrix. */ mat = (double *) astFree( (void *) mat ); } /* If an error has occurred, attempt to annul the returned MatrixMap. */ if( !astOK ) new = astAnnul( new ); /* Return the MatrixMap. */ return new; } static AstMapping *WcsNative( AstFitsChan *this, FitsStore *store, char s, AstWcsMap *wcsmap, int fits_ilon, int fits_ilat, const char *method, const char *class, int *status ){ /* * Name: * WcsNative * Purpose: * Create a CmpMap which transforms Native Spherical Coords to * Celestial Coords. * Type: * Private function. * Synopsis: * AstMapping *WcsNative( AstFitsChan *this, FitsStore *store, char s, * AstWcsMap *wcsmap, int fits_ilon, int fits_ilat, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A CmpMap is created which rotates the supplied Native Spherical Coords * into Celestial Coords in the standard system specified by the CTYPE * keywords. Any non-celestial axes are left unchanged. * * At the highest level, the returned CmpMap is made up of the following * Mappings in series (if celestial long/lat axes are present): * 1 - A PermMap which rearranges the axes so that the longitude axis is * axis 0, the latitude axis is axis 1, and all other axes are * stored at higher indices, starting at axis 2. * 2 - A CmpMap which converts the values on axes 0 and 1 from Native * Spherical to Celestial coordinates, leaving all other axes * unchanged. * 3 - A PermMap which rearranges the axes to put the longitude and * latitude axes back in their original places. This is just the * inverse of the PermMap used at stage 1 above. * * The CmpMap used at stage 2 above, is made up of two Mappings in * parallel: * 4 - A CmpMap which maps axes 0 and 1 from Native Spherical to * Celestial coordinates. * 5 - A UnitMap which passes on the values to axes 2, 3, etc, * without change. * * The CmpMap used at stage 4 above, is made up of the following Mappings * in series: * 6 - A SphMap which converts the supplied spherical coordinates into * Cartesian Coordinates. * 7 - A MatrixMap which rotates the Cartesian coordinates from the * Native to the Celestial system. * 8 - A SphMap which converts the resulting Cartesian coordinates back * to spherical coordinates. * Parameters: * this * The FitsChan in which to store any warning cards. If NULL, no * warnings are stored. * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * Co-ordinate version character to use (space means primary axes). * wcsmap * A mapping describing the deprojection which is being used. This is * needed in order to be able to locate the fiducial point within the * Native Speherical Coordinate system, since it varies from projection * to projection. * fits_ilon * The zero-based FITS WCS axis index corresponding to celestial * longitude (i.e. one less than the value of "i" in the keyword * names "CTYPEi", "CRVALi", etc). If -1 is supplied, the index of * the longitude axis in the supplied WcsMap is used. * fits_ilat * The zero-based FITS WCS axis index corresponding to celestial * latitude (i.e. one less than the value of "i" in the keyword * names "CTYPEi", "CRVALi", etc). If -1 is supplied, the index of * the latitude axis in the supplied WcsMap is used. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the created CmpMap or a NULL pointer if an error occurred. * Notes: * - The local variable names correspond to the notation in the papers * by Greisen & Calabretta describing the FITS WCS system. */ /* Local Variables: */ AstCmpMap *cmpmap; /* A CmpMap */ AstMapping *new; /* The returned CmpMap */ AstMatrixMap *matmap2; /* Another MatrixMap */ AstMatrixMap *matmap; /* A MatrixMap */ AstPermMap *permmap; /* A PermMap */ AstSphMap *sphmap; /* A SphMap */ AstUnitMap *unitmap; /* A UnitMap */ char buf[150]; /* Message buffer */ double alpha0; /* Long. of fiduaicl point in standard system */ double alphap; /* Long. of native nth pole in standard system */ double axis[3]; /* Vector giving the axis of rotation */ double delta0; /* Lat. of fiducial point in standard system */ double deltap; /* Lat. of native nth pole in standard system */ double latpole; /* Lat. of native nth pole in standard system if deltap undefined */ double phip; /* Long. of standard nth pole in native system */ double phi0; /* Native longitude at fiducial point */ double theta0; /* Native latitude at fiducial point */ int *inperm; /* Pointer to array of output axis indices */ int *outperm; /* Pointer to array of input axis indices */ int axlat; /* Index of latitude physical axis */ int axlon; /* Index of longitude physical axis */ int i; /* Loop count */ int nax_rem; /* No. of non-astrometric axes */ int naxis; /* No. of axes. */ int new_axlat; /* Index of lat. physical axis after perming */ int tpn; /* Is this a TPN projection? */ /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the returned CmpMap pointer. */ new = NULL; /* Store the number of axes in a local variable. */ naxis = astGetNin( wcsmap ); /* Get the indices of the celestial axes. */ axlon = astGetWcsAxis( wcsmap, 0 ); axlat = astGetWcsAxis( wcsmap, 1 ); /* If the corresponding FITS axis indices were not supplied, use the WcsMap axes found above. */ if( fits_ilon == -1 ) fits_ilon = axlon; if( fits_ilat == -1 ) fits_ilat = axlat; /* If there is no longitude or latitude axis, or if we have a non-celestial projection, just return a UnitMap. */ if( axlon == axlat || astGetWcsType( wcsmap ) == AST__WCSBAD ){ new = (AstMapping *) astUnitMap( naxis, "", status ); /* If there is a lon/lat axis pair, create the inperm and outperm arrays which will be needed later to create the PermMap which reorganises the axes so that axis zero is the longitude axis and axis 1 is the latitude axis. */ } else { /* Get storage for the two arrays. */ inperm = (int *) astMalloc( sizeof( int )*(size_t)naxis ); outperm = (int *) astMalloc( sizeof( int )*(size_t)naxis ); if( astOK ){ /* Initialise an array holding the indices of the input axes which are copied to each output axis. Initially assume that there is no re-arranging of the axes. */ for( i = 0; i < naxis; i++ ) outperm[ i ] = i; /* Swap the longitude axis and axis 0. */ i = outperm[ axlon ]; outperm[ axlon ] = outperm[ 0 ]; outperm[ 0 ] = i; /* If axis 0 was originally the latitude axis, the latitude axis will now be where the longitude axis was originally (because of the above axis swap). */ if( axlat == 0 ) { new_axlat = axlon; } else { new_axlat = axlat; } /* Swap the latitude axis and axis 1. */ i = outperm[ new_axlat ]; outperm[ new_axlat ] = outperm[ 1 ]; outperm[ 1 ] = i; /* Create the array holding the output axis index corresponding to each input axis. */ for( i = 0; i < naxis; i++ ) inperm[ outperm[ i ] ] = i; } /* Store the latitude and longitude (in the standard system) of the fiducial point, in radians. */ delta0 = GetItem( &(store->crval), fits_ilat, 0, s, NULL, method, class, status ); if( delta0 == AST__BAD ) delta0 = 0.0; delta0 *= AST__DD2R; alpha0 = GetItem( &(store->crval), fits_ilon, 0, s, NULL, method, class, status ); if( alpha0 == AST__BAD ) alpha0 = 0.0; alpha0 *= AST__DD2R; /* Limit the latitude to the range +/- PI/2, issuing a warning if the supplied CRVAL value is outside this range. The "alphap" variable is used as workspace here. */ alphap = palDrange( delta0 ); delta0 = alphap; if ( delta0 > AST__DPIBY2 ){ delta0 = AST__DPIBY2; } else if ( delta0 < -AST__DPIBY2 ){ delta0 = -AST__DPIBY2; } if( alphap != delta0 ) { sprintf( buf, "The original FITS header specified a fiducial " "point with latitude %.*g. A value of %.*g is being used " "instead. ", DBL_DIG, alphap*AST__DR2D, DBL_DIG, delta0*AST__DR2D ); Warn( this, "badlat", buf, method, class, status ); } /* Set a flag indicating if we have a TPN projection. The handling or projection parameters is different for TPN projections. */ tpn = ( astGetWcsType( wcsmap ) == AST__TPN ); /* Store the radian values of the FITS keywords LONPOLE and LATPOLE. Defaults will be used if either of these items was not supplied. These keyword values may be stored in projection parameters PVi_3a and PVi_4a for longitude axis "i" - in which case the "PV" values take precedence over the "LONPOLE" and "LATPOLE" values. Do not do this for TPN projections since they use these projection parameters to specify correcton terms. */ if( astTestPV( wcsmap, axlon, 3 ) && !tpn ) { phip = astGetPV( wcsmap, axlon, 3 ); } else { phip = GetItem( &(store->lonpole), 0, 0, s, NULL, method, class, status ); if( phip != AST__BAD && !tpn ) astSetPV( wcsmap, axlon, 3, phip ); } if( phip != AST__BAD ) phip *= AST__DD2R; if( astTestPV( wcsmap, axlon, 4 ) && !tpn ) { latpole = astGetPV( wcsmap, axlon, 4 ); } else { latpole = GetItem( &(store->latpole), 0, 0, s, NULL, method, class, status ); if( latpole != AST__BAD && !tpn ) astSetPV( wcsmap, axlon, 4, latpole ); } if( latpole != AST__BAD ) latpole *= AST__DD2R; /* Find the standard Celestial Coordinates of the north pole of the Native Spherical Coordinate system. Report an error if the position was not defined. */ if( !WcsNatPole( this, wcsmap, alpha0, delta0, latpole, &phip, &alphap, &deltap, status ) && astOK ){ astError( AST__BDFTS, "%s(%s): Conversion from FITS WCS native " "coordinates to celestial coordinates is ill-conditioned.", status, method, class ); } /* Create the SphMap which converts spherical coordinates to Cartesian coordinates (stage 6 in the prologue). This asumes that axis 0 is the longitude axis, and axis 1 is the latitude axis. This will be ensured by a PermMap created later. Indicate that the SphMap will only be used to transform points on a unit sphere. This enables a forward SphMap to be combined with an inverse SphMap into a UnitMap, and thus aids simplification. */ sphmap = astSphMap( "UnitRadius=1", status ); astInvert( sphmap ); /* Set the PolarLong attribute of the SphMap so that a longitude of phi0 (the native longitude of the fiducial point) is returned by the inverse transformation (cartesian->spherical) at either pole. */ GetFiducialNSC( wcsmap, &phi0, &theta0, status ); astSetPolarLong( sphmap, phi0 ); /* Create a unit MatrixMap to be the basis of the MatrixMap which rotates Native Spherical Coords to Celestial Coords (stage 7 in the prologue). */ matmap = astMatrixMap( 3, 3, 2, NULL, "", status ); /* Modify the above MatrixMap so that it rotates the Cartesian position vectors by -phip (i.e. LONPOLE) about the Z axis. This puts the north pole of the standard system at zero longitude in the rotated system. Then annul the original MatrixMap and use the new one instead. */ axis[ 0 ] = 0; axis[ 1 ] = 0; axis[ 2 ] = 1; matmap2 = astMtrRot( matmap, -phip, axis ); matmap = astAnnul( matmap ); matmap = matmap2; /* Now modify the above MatrixMap so that it rotates the Cartesian position vectors by -(PI/2-deltap) about the Y axis. This puts the north pole of the standard system as 90 degrees latitude in the rotated system. Then annul the original MatrixMap and use the new one instead. */ axis[ 0 ] = 0; axis[ 1 ] = 1; axis[ 2 ] = 0; matmap2 = astMtrRot( matmap, deltap - AST__DPIBY2, axis ); matmap = astAnnul( matmap ); matmap = matmap2; /* Finally modify the above MatrixMap so that it rotates the Cartesian position vectors (PI+alphap) about the Z axis. This puts the primary meridian of the standard system at zero longitude in the rotated system. This results in the rotated system being coincident with the standard system. */ axis[ 0 ] = 0; axis[ 1 ] = 0; axis[ 2 ] = 1; matmap2 = astMtrRot( matmap, AST__DPI + alphap, axis ); matmap = astAnnul( matmap ); matmap = matmap2; /* Combine the SphMap (stage 6) and MatrixMap (stage 7) in series. */ cmpmap = astCmpMap( sphmap, matmap, 1, "", status ); sphmap = astAnnul( sphmap ); matmap = astAnnul( matmap ); /* Create a new SphMap which converts Cartesian coordinates to spherical coordinates (stage 8 in the prologue). Indicate that the SphMap will only be used to transform points on a unit sphere. */ sphmap = astSphMap( "UnitRadius=1", status ); /* Set the PolarLong attribute of the SphMap so that a longitude of alpha0 (the celestial longitude of the fiducial point) is returned by the forward transformation (cartesian->spherical) at either pole. */ astSetPolarLong( sphmap, alpha0 ); /* Add it to the compound mapping. The CmpMap then corresponds to stage 4 in the prologue. Annul the constituent mappings. */ new = (AstMapping *) astCmpMap( cmpmap, sphmap, 1, "", status ); cmpmap = astAnnul( cmpmap ); sphmap = astAnnul( sphmap ); /* If there are any remaining axes (i.e. axes which do not describe a Celestial coordinate system), create a UnitMap which passes on their values unchanged (stage 5 in the prologue), and add it the CmpMap, putting it in parallel with the earlier mappings. The resulting CmpMap then corresponds to stage 2 in the prologue. Note, the axis numbering used by this UnitMap needs to take account of the fact that it is only applied to the non-celestial axes. The axes are re-ordered by the PermMap described at stage 1 in the prologue. */ nax_rem = naxis - 2; if( nax_rem > 0 ){ unitmap = astUnitMap( nax_rem, "", status ); cmpmap = astCmpMap( new, unitmap, 0, "", status ); new = astAnnul( new ); unitmap = astAnnul( unitmap ); new = (AstMapping *) cmpmap; } /* Now we need to ensure that axes 0 and 1 correspond to longitude and latitude. If this is already the case, then the CmpMap can be returned as it is. Otherwise, a PermMap needs to be created to rearrange the axes. */ if( axlon != 0 || axlat != 1 ){ /* Create the PermMap using the inperm and outperm arrays created earlier. This is the mapping described as stage 1 in the prologue. */ permmap = astPermMap( naxis, inperm, naxis, outperm, NULL, "", status ); /* Compound this PermMap and the CmpMap corresponding to stage 2 (created earlier) in series. */ cmpmap = astCmpMap( permmap, new, 1, "", status ); new = astAnnul( new ); new = (AstMapping *) cmpmap; /* Now invert the PermMap, so that it re-arranges the axes back into their original order. This is the mapping described as stage 3 in the prologue. */ astInvert( permmap ); /* And finally.... add this inverted PermMap onto the end of the CmpMap. */ cmpmap = astCmpMap( new, permmap, 1, "", status ); permmap = astAnnul( permmap ); new = astAnnul( new ); new = (AstMapping *) cmpmap; } /* Free the temporary arrays. */ inperm = (int *) astFree( (void *) inperm ); outperm = (int *) astFree( (void *) outperm ); } /* If an error has occurred, attempt to annul the new CmpMap. */ if( !astOK ) new = astAnnul( new ); /* Return the CmpMap. */ return new; } static int WcsNatPole( AstFitsChan *this, AstWcsMap *wcsmap, double alpha0, double delta0, double latpole, double *phip, double *alphap, double *deltap, int *status ){ /* * Name: * WcsNatPole * Purpose: * Find the celestial coordinates of the north pole of the Native Spherical * Coordinate system. * Type: * Private function. * Synopsis: * int WcsNatPole( AstFitsChan *this, AstWcsMap *wcsmap, double alpha0, * double delta0, double latpole, double *phip, * double *alphap, double *deltap, int *status ) * Class Membership: * FitsChan * Description: * The supplied WcsMap converts projected positions given in * "Projection Plane Coords" to positions in the "Native Spherical * Coordinate" system. This function finds the pole of this spherical * coordinate system in terms of the standard celestial coordinate * system to which the CRVALi, LONPOLE and LATPOLE keywords refer (this * system should be identified by characters 5-8 of the CTYPEi * keywords). It also supplies a default value for LONPOLE if no value * has been supplied explicitly in the FITS header. * * This function implements equations 8, 9 and 10 from the FITS-WCS paper * II by Calabretta & Greisen (plus the associated treatment of special * cases). The paper provides more detailed documentation for the * mathematics implemented by this function. * Parameters: * this * The FitsChan in which to store any warning cards. If NULL, no * warnings are stored. * wcsmap * A mapping describing the deprojection being used (i.e. the * mapping from Projection Plane Coords to Native Spherical Coords). * alpha0 * The longitude of the fiducial point in the standard celestial * coordinate frame (in radians). Note, this fiducial point does * not necessarily correspond to the point given by keywords CRPIXj. * delta0 * The celestial latitude (radians) of the fiducial point. * latpole * The value of FITS keyword LATPOLE, converted to radians, or the * symbolic constant AST__BAD if the keyword was not supplied. * phip * Pointer to a location at which is stored the longitude of the north * pole of the standard Celestial coordinate system, as measured in * the Native Spherical Coordinate system, in radians. This should be * supplied holding the radian equivalent of the value of the FITS * keyword LONPOLE, or the symbolic constant AST__BAD if the keyword was * not supplied (in which case a default value will be returned at the * given location). * alphap * Pointer to a location at which to store the calculated longitude * of the Native North Pole, in radians. * deltap * Pointer to a location at which to store the calculated latitude * of the Native North Pole, in radians. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A status: non-zero for success, zero if the position of the native * north pole is undefined. * Notes: * - Certain combinations of keyword values result in the latitude of * the Native North Pole being undefined. In these cases, a value of * 0 is returned for the function value, but no error is reported. * - All angular values used by this function are in radians. * - A value of 0 is returned if an error has already occurred. */ /* Local Variables: */ char buf[150]; /* Buffer for warning message */ double cos_theta0; /* Cosine of theta0 */ double cos_phip; /* Cosine of (phip - phi0) */ double cos_delta0; /* Cosine of delta0 */ double cos_deltap; /* Cosine of deltap */ double deltap_1; /* First possible value for deltap */ double deltap_2; /* Second possible value for deltap */ double sin_theta0; /* Sine of theta0 */ double sin_phip; /* Sine of (phip - phi0) */ double sin_delta0; /* Sine of delta0 */ double sin_deltap; /* Sine of deltap */ double t0, t1, t2, t3, t4; /* Intermediate values */ double phi0, theta0; /* Native coords of fiducial point */ /* Check the global status. */ if ( !astOK ) return 0; /* Get the longitude and latitude of the fiducial point in the native spherical coordinate frame (in radians). */ GetFiducialNSC( wcsmap, &phi0, &theta0, status ); /* If no value was supplied for the FITS keyword LONPOLE, set up a default value such that the celestial latitude increases in the same direction as the native latitude at the fiducial; point. */ if( *phip == AST__BAD ){ if( delta0 >= theta0 ){ *phip = 0.0; } else { *phip = AST__DPI; } /* Issue a warning that a default lonpole value has been adopted. */ sprintf( buf, "The original FITS header did not specify the " "longitude of the native north pole. A default value " "of %.8g degrees was assumed.", (*phip)*AST__DR2D ); Warn( this, "nolonpole", buf, "astRead", "FitsChan", status ); } /* If the fiducial point is coincident with the Native North Pole, then the Native North Pole must have the same coordinates as the fiducial point. Tests for equality include some tolerance to allow for rounding errors. */ sin_theta0 = sin( theta0 ); if( astEQUAL( sin_theta0, 1.0 ) ){ *alphap = alpha0; *deltap = delta0; /* If the fiducial point is concident with the Native South Pole, then the Native North Pole must have the coordinates of the point diametrically opposite the fiducial point. */ } else if( astEQUAL( sin_theta0, -1.0 ) ){ *alphap = alpha0 + AST__DPI; *deltap = -delta0; /* For all other cases, go through the procedure described in the WCS paper by Greisen & Calabretta, to find the position of the Native North Pole. First store some useful values. */ } else { cos_theta0 = cos( theta0 ); cos_delta0 = cos( delta0 ); cos_phip = cos( *phip - phi0 ); sin_delta0 = sin( delta0 ); sin_phip = sin( *phip - phi0 ); /* Next, find the two possible values for the latitude of the Native North Pole (deltap). If any stage of this transformation is indeterminate, return zero (except for the single special case noted in item 6 para. 2 of the WCS paper, for which LATPOLE specifies the values to be used). */ t0 = cos_theta0*cos_phip; if( fabs( t0 ) < TOL2 && fabs( sin_theta0 ) < TOL2 ){ if( latpole != AST__BAD ) { *deltap = latpole; } else { return 0; } } else { t1 = atan2( sin_theta0, t0 ); t2 = cos_theta0*cos_phip; t2 *= t2; t2 += sin_theta0*sin_theta0; if( t2 <= DBL_MIN ){ return 0; } else { t3 = sin_delta0/sqrt( t2 ); if( fabs( t3 ) > 1.0 + TOL1 ){ return 0; } else { if( t3 < -1.0 ){ t4 = AST__DPI; } else if( t3 > 1.0 ){ t4 = 0.0; } else { t4 = acos( t3 ); } deltap_1 = palDrange( t1 + t4 ); deltap_2 = palDrange( t1 - t4 ); /* Select which of these two values of deltap to use. Values outside the range +/- PI/2 cannot be used. If both values are within this range use the value which is closest to the supplied value of latpole (or use the northern most value if the LATPOLE keyword was not supplied. */ if( fabs( deltap_1 ) > AST__DPIBY2 + TOL2 ){ *deltap = deltap_2; } else if( fabs( deltap_2 ) > AST__DPIBY2 + TOL2 ){ *deltap = deltap_1; } else { if( latpole != AST__BAD ){ if( fabs( deltap_1 - latpole ) < fabs( deltap_2 - latpole ) ){ *deltap = deltap_1; } else { *deltap = deltap_2; } } else { if( deltap_1 > deltap_2 ){ *deltap = deltap_1; } else { *deltap = deltap_2; } /* Issue a warning that a default latpole value has been adopted. */ sprintf( buf, "The original FITS header did not specify " "the latitude of the native north pole. A " "default value of %.8g degrees was assumed.", (*deltap)*AST__DR2D ); Warn( this, "nolatpole", buf, "astRead", "FitsChan", status ); } } if( fabs( *deltap ) > AST__DPIBY2 + TOL2 ) { return 0; } else if( *deltap < -AST__DPIBY2 ){ *deltap = -AST__DPIBY2; } else if( *deltap > AST__DPIBY2 ){ *deltap = AST__DPIBY2; } } } } /* If a valid value for the latitude (deltap) has been found, find the longitude of the Native North Pole. */ if( *deltap != AST__BAD ) { if( fabs( cos_delta0) > TOL2 ){ cos_deltap = cos( *deltap ); sin_deltap = sin( *deltap ); if( fabs( cos_deltap ) > TOL2 ){ t1 = sin_phip*cos_theta0/cos_delta0; t2 = ( sin_theta0 - sin_deltap*sin_delta0 ) /( cos_delta0*cos_deltap ); if( ( fabs( t1 ) > TOL2 ) || ( fabs( t2 ) > TOL2 ) ){ *alphap = alpha0 - atan2( t1, t2 ); } else { *alphap = alpha0; } } else if( sin_deltap > 0.0 ){ *alphap = alpha0 + (*phip - phi0) - AST__DPI; } else { *alphap = alpha0 - (*phip - phi0); } } else { *alphap = alpha0; } } else { *alphap = AST__BAD; } } /* Return a success status if valid latitude and longitude values were found. */ return (*deltap) != AST__BAD && (*alphap) != AST__BAD ; } static AstMapping *WcsOthers( AstFitsChan *this, FitsStore *store, char s, AstFrame **frm, AstFrame *iwcfrm, const char *method, const char *class, int *status ){ /* * Name: * WcsOthers * Purpose: * Create a Mapping from intermediate world coords to any axes * which are not covered by specialised conventions. * Type: * Private function. * Synopsis: * AstMapping *WcsOthers( AstFitsChan *this, FitsStore *store, char s, * AstFrame **frm, AstFrame *iwcfrm, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function interprets the contents of the supplied FitsStore * structure, looking for world coordinate axes for which no * description has yet been added to the supplied Frame . It is * assumed that any such axes are simple linear axes. It returns a * Mapping which simply adds on the CRVAL values to such axes. * It also modifies the supplied Frame to describe the axes. * Parameters: * this * The FitsChan. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * frm * The address of a location at which to store a pointer to the * Frame describing the world coordinate axes. * iwcfrm * A pointer to the Frame describing the intermediate world coordinate * axes. The properties of this Frame may be changed on exit. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstFrame *pfrm; /* Pointer to primary Frame */ AstFrame *pfrm2; /* Pointer to primary Frame */ AstMapping *map1; /* Pointer to a Mapping */ AstMapping *map2; /* Pointer to a Mapping */ AstMapping *ret; /* The returned Mapping */ char **comms; /* Pointer to array of CTYPE commments */ char buf[ 100 ]; /* Buffer for textual attribute value */ char buf2[ 100 ]; /* Buffer for textual attribute value */ char buf3[ 20 ]; /* Buffer for default CTYPE value */ char *newdom; /* Pointer to new Domain value */ const char *ckeyval; /* Pointer to character keyword value */ int i; /* Axis index */ int j; /* Axis index */ int len; /* Used length of string */ int naxes; /* no. of axes in Frame */ int nother; /* The number of "other" axes */ int paxis; /* Primary axis index */ int usecom; /* Use CTYPE comments as axis Labels? */ /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Get the number of physical axes. */ naxes = astGetNaxes( *frm ); /* Assume we will use CTYPE comments as the axis labels. */ usecom = 1; /* Initialise the count of "other" axes. */ nother = 0; /* Get the comments associated with the CTYPE keywords for all "other" axes. */ comms = astMalloc( naxes*sizeof( char * ) ); if( comms ) { /* Loop round all axes in the Frame, and initialise the pointer to its comment. */ for( i = 0; i < naxes; i++ ){ comms[ i ] = NULL; /* Get the Domain for the primary frame containing the axis. This will be "AST_FITSCHAN" if the axis has not yet been recognised (this Domain is set up by WcsMapFrm). Only consider the axis further if the Domain has not been changed. */ astPrimaryFrame( *frm, i, &pfrm, &paxis ); if( !strcmp( astGetDomain( pfrm ), "AST_FITSCHAN" ) ) { /* Increment the count of "other" axes. */ nother++; /* Get the comment associated with the CTYPE header. */ ckeyval = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); /* If this axis has no CTYPE comment, we will use CTYPE values as axis labels (if given, the CNAME keyword take precedence). */ if( !ckeyval || astChrLen( ckeyval ) == 0 ) { usecom = 0; /* If the CTYPE comment for this axis is the same as any other comment, we will use CTYPE values as axis labels. */ } else { for( j = 0; j < nother - 1; j++ ) { if( comms[ j ] && !strcmp( ckeyval, comms[ j ] ) ) { usecom = 0; break; } } } /* If we are still using comments as axis labels, store a copy of it in the workspace. */ if( usecom ) comms[ i ] = astStore( NULL, ckeyval, strlen( ckeyval ) + 1 ); } pfrm = astAnnul( pfrm ); } /* Free the workspace holding comments. */ for( i = 0; i < naxes; i++ ) comms[ i ] = astFree( comms[ i ] ); comms = astFree( comms ); } /* If there are no "other" axes, just return a UnitMap. */ if( nother == 0 ) { ret = (AstMapping *) astUnitMap( naxes, "", status ); /* Otherwise... */ } else { /* If we have only a single other axis, use CTYPE value instead of comment. */ if( nother == 1 ) usecom = 0; /* Not yet started a new Domain value to replace "AST_FITSCHAN". */ newdom = NULL; pfrm2 = NULL; /* Check each axis of the Frame looking for axes which have not yet been recognised. */ for( i = 0; i < naxes; i++ ) { /* Get the Domain for the primary frame containing the axis. This will be "AST_FITSCHAN" if the axis has not yet been recognised (this Domain is set up by WcsMapFrm). Only consider the axis further if the Domain has not been changed. */ astPrimaryFrame( *frm, i, &pfrm, &paxis ); if( !strcmp( astGetDomain( pfrm ), "AST_FITSCHAN" ) ) { /* Save a pointer to the primary Frame which we will use to set the Domain of the primary Frame. */ if( !pfrm2 ) pfrm2 = astClone( pfrm ); /* Get the CTYPE value. Use a default of "AXISn". */ ckeyval = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( !ckeyval ) { sprintf( buf3, "AXIS%d", i + 1 ); ckeyval = buf3; } /* If the CTYPE value ends with "-LOG", assume it is a logarithmically spaced axis. Get the Mapping from IWC to WCS. Reduce the used length of the CTYPE string to exlude any trailing "-LOG" string. */ len = strlen( ckeyval ); if( len > 3 && !strcmp( ckeyval + len - 4, "-LOG" ) ){ map1 = LogWcs( store, i, s, method, class, status ); sprintf( buf2, "%.*s", len - 4, ckeyval ); /* Otherwise, assume the axis is linearly spaced. */ } else { map1 = LinearWcs( store, i, s, method, class, status ); sprintf( buf2, "%.*s", len, ckeyval ); } /* Append the CTYPE value to the final Domain value for the primary Frame. */ if( ckeyval && astChrLen( ckeyval ) > 0 ) { if( newdom ) { sprintf( buf, "%s-%s", newdom, buf2 ); } else { sprintf( buf, "%s", buf2 ); newdom = buf; } } /* Now modify the axis in the Frame to have appropriate values for the Unit, Label and Symbol attributes. Also set the Unit attribute for the corresponding axis in the IWC Frame. */ if( ckeyval ) astSetSymbol( *frm, i, buf2 ); ckeyval = GetItemC( &(store->cname), i, 0, s, NULL, method, class, status ); if( !ckeyval && usecom ) ckeyval = GetItemC( &(store->ctype_com), i, 0, s, NULL, method, class, status ); if( !ckeyval ) ckeyval = buf2; if( ckeyval ) astSetLabel( *frm, i, ckeyval ); ckeyval = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( ckeyval ) { astSetUnit( *frm, i, ckeyval ); astSetUnit( iwcfrm, i, ckeyval ); } /* If this axis has been described by an earlier function (because it uses specialised conventions such as those described in FITS-WCS papers II or III), then create a UnitMap for this axis. */ } else { map1 = (AstMapping *) astUnitMap( 1, "", status ); } /* Annul the pointer to the primary Frame containing the current axis. */ pfrm = astAnnul( pfrm ); /* Add the Mapping for this axis in parallel with the current "running sum" Mapping (if any). */ if( ret ) { map2 = (AstMapping *) astCmpMap( ret, map1, 0, "", status ); ret = astAnnul( ret ); map1 = astAnnul( map1 ); ret = map2; } else { ret = map1; } } /* Set the Domain name for the primary Frame. It is currently set to AST_FITSCHAN. We replace it with a value formed by concatenating the CTYPE values of its axes. */ if( pfrm2 ) { if( newdom && astChrLen( newdom ) > 0 ) { astSetDomain( pfrm2, newdom ); } else { astClearDomain( pfrm2 ); } pfrm2 = astAnnul( pfrm2 ); } /* If the header contained a WCSNAME keyword, use it as the Domain name for the Frame. Also use it to create a title. */ ckeyval = GetItemC( &(store->wcsname), 0, 0, s, NULL, method, class, status ); if( ckeyval ){ astSetDomain( *frm, ckeyval ); sprintf( buf, "%s coordinates", ckeyval ); astSetTitle( *frm, buf ); } } /* Return the result. */ return ret; } static AstWinMap *WcsShift( FitsStore *store, char s, int naxes, const char *method, const char *class, int *status ){ /* * Name: * WcsShift * Purpose: * Create a WinMap which shifts pixels coordinates so that their origin * is at the reference pixel. * Type: * Private function. * Synopsis: * AstWinMap *WcsShift( FitsStore *store, char s, int naxes, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * A WinMap is created which implements a shift of origin by subtracting * the reference pixel coordinates (CRPIXi) from the input pixel * coordinates. * Parameters: * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the created WinMap or a NULL pointer if an * error occurred. * Notes: * - If an error occurs, a NULL pointer is returned. */ /* Local Variables: */ AstWinMap *new; /* The created WinMap */ int j; /* Pixel axis index */ double crpix; /* CRPIX keyword value */ double *c1_in; /* Input corner 1 */ double *c2_in; /* Input corner 2 */ double *c1_out; /* Output corner 1 */ double *c2_out; /* Output corner 2 */ /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the returned WinMap pointer. */ new = NULL; /* Allocate memory to hold the two corners, in both input and output coordinates. */ c1_in = (double *) astMalloc( sizeof( double )*(size_t) naxes ); c1_out = (double *) astMalloc( sizeof( double )*(size_t) naxes ); c2_in = (double *) astMalloc( sizeof( double )*(size_t) naxes ); c2_out = (double *) astMalloc( sizeof( double )*(size_t) naxes ); /* Check these pointers can be used. */ if( astOK ){ /* Set up two arbitrary corners in the input coordinate system, and the corresponding values with the CRPIX values subtracted off. */ for( j = 0; j < naxes; j++ ){ /* Get the CRPIX value for this axis. */ crpix = GetItem( &(store->crpix), 0, j, s, NULL, method, class, status ); if( crpix == AST__BAD ) crpix = 0.0; /* Store the corner co-ordinates. */ c1_in[ j ] = 0.0; c2_in[ j ] = 1.0; c1_out[ j ] = -crpix; c2_out[ j ] = 1.0 - crpix; } /* Create the WinMap. */ new = astWinMap( naxes, c1_in, c2_in, c1_out, c2_out, "", status ); /* If an error has occurred, attempt to annul the new WinMap. */ if( !astOK ) new = astAnnul( new ); } /* Free the memory holding the corners. */ c1_in = (double *) astFree( (void *) c1_in ); c1_out = (double *) astFree( (void *) c1_out ); c2_in = (double *) astFree( (void *) c2_in ); c2_out = (double *) astFree( (void *) c2_out ); /* Return the WinMap. */ return new; } static AstSkyFrame *WcsSkyFrame( AstFitsChan *this, FitsStore *store, char s, int prj, char *sys, int axlon, int axlat, const char *method, const char *class, int *status ){ /* * Name: * WcsSkyFrame * Purpose: * Create a SkyFrame to describe a WCS celestial coordinate system. * Type: * Private function. * Synopsis: * AstSkyFrame *WcsSkyFrame( AstFitsChan this, FitsStore *store, char s, int prj, * char *sys, int axlon, int axlat, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A SkyFrame is returned describing the celestial coordinate system * described by a FITS header. The axes are *not* permuted in the * returned Frame (that is, axis 0 is longitude and axis 1 is latitude * in the returned SkyFrame, no matter what values are supplied for * "axlat" and "axlon"). * Parameters: * this * The FitsChan from which the keywords were read. Warning messages * may be added to this FitsChan. * store * A structure containing values for FITS keywords relating to * the World Coordinate System. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * prj * An integer code for the WCS projection being used. * sys * A pointer to a string identifying the celestial co-ordinate system * implied by the CTYPE values in the FitsStore. This will be "EQU" (for * equatorial), or a one or two character code extracted from the * CTYPE values. * axlon * Zero based index of the longitude axis in the FITS header. * axlat * Zero based index of the latitude axis in the FITS header. * method * The calling method. Used only in error messages. * class * The object class. Used only in error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the SkyFrame. * Notes: * - A NULL pointer is returned if an error has already occurred, or * if this function should fail for any reason. */ /* Local Variables: */ AstSkyFrame *ret; /* Returned Frame */ char *ckeyval; /* Pointer to string item value */ char *lattype; /* Pointer to latitude CTYPE value */ char *lontype; /* Pointer to longitude CTYPE value */ char bj; /* Besselian/Julian selector */ char buf[300]; /* Text buffer */ char sym[10]; /* Axis symbol */ double dval; /* Floating point attribute value */ double eqmjd; /* MJD equivalent of equinox */ double equinox; /* EQUINOX value */ double geolat; /* Observer's geodetic latitude */ double geolon; /* Observer's geodetic longitude */ double h; /* Observer's geodetic height */ double mjdobs; /* MJD-OBS value */ double obsgeo[ 3 ]; /* Observer's Cartesian position */ int radesys; /* RADESYS value */ int report; /* Report unknown lon/lat system? */ /* Initialise. */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* Get the RADESYS keyword from the header, and identify the value. Store a integer value identifying the system. Report an error if an unrecognised system is supplied. Store NORADEC if the keyword was not supplied. */ ckeyval = GetItemC( &(store->radesys), 0, 0, s, NULL, method, class, status ); radesys = NORADEC; if( ckeyval ){ if( !strncmp( ckeyval, "FK4 ", 4 ) || !strcmp( ckeyval, "FK4" ) ){ radesys = FK4; } else if( !strncmp( ckeyval, "FK4-NO-E", 8 ) ){ radesys = FK4NOE; } else if( !strncmp( ckeyval, "FK5 ", 4 ) || !strcmp( ckeyval, "FK5" ) ){ radesys = FK5; } else if( !strncmp( ckeyval, "ICRS ", 5 ) || !strcmp( ckeyval, "ICRS" ) ){ radesys = ICRS; } else if( !strncmp( ckeyval, "GAPPT ", 6 ) || !strcmp( ckeyval, "GAPPT" ) ){ radesys = GAPPT; } else if( astOK ){ astError( AST__BDFTS, "%s(%s): FITS keyword '%s' has the " "unrecognised value '%s'.", status, method, class, FormatKey( "RADESYS", -1, -1, s, status ), ckeyval ); } } else { radesys = NORADEC; } /* Get the value of the EQUINOX keyword. */ equinox = GetItem( &(store->equinox), 0, 0, s, NULL, method, class, status ); /* For FK4 and FK4-NO-E any supplied equinox value is Besselian. For all other systems, the equinox value is Julian. */ bj = 0; if( equinox != AST__BAD ){ if( radesys == FK4 || radesys == FK4NOE ){ bj = 'B'; } else if( radesys != NORADEC ) { bj = 'J'; /* If no RADESYS was suppied, but an equinox was, use the IAU 1984 rule to determine the default RADESYS and equinox type. */ } else { if( equinox < 1984.0 ){ radesys = FK4; bj = 'B'; } else { radesys = FK5; bj = 'J'; } /* If an equatorial system is being used, give a warning that a default RADESYS value is being used. */ if( !strcmp( sys, "EQU" ) ){ sprintf( buf, "The original FITS header did not specify the " "RA/DEC reference frame. A default value of %s was " "assumed.", ( radesys == FK4 ) ? "FK4" : "FK5" ); Warn( this, "noradesys", buf, method, class, status ); } } /* If no equinox was supplied, use a default equinox value depending on the frame of reference. For FK4-based systems, use B1950. */ } else { if( radesys == FK4 || radesys == FK4NOE ){ equinox = 1950.0; bj = 'B'; /* For FK5-based systems, use J2000. */ } else if( radesys == FK5 ){ equinox = 2000.0; bj = 'J'; /* If no RADESYS or EQUINOX was supplied, assume either FK4 B1950 or ICRS - as decided by attribute DefB1950 (GAPPT and ICRS do not use EQUINOX). */ } else if( radesys == NORADEC ) { if( astGetDefB1950( this ) ) { equinox = 1950.0; bj = 'B'; radesys = FK4; } else { radesys = ICRS; } if( !strcmp( sys, "EQU" ) ){ sprintf( buf, "The original FITS header did not specify the " "RA/DEC reference frame. A default value of %s was " "assumed.", ( radesys == FK4 ) ? "FK4" : "ICRS" ); Warn( this, "noradesys", buf, method, class, status ); } } /* If we have an equatorial or ecliptic system, issue a warning that a default equinox has been adopted. */ if( ( !strcmp( sys, "EQU" ) && radesys != ICRS && radesys != GAPPT ) || !strcmp( sys, "ECL" ) ){ sprintf( buf, "The original FITS header did not specify the " "reference equinox. A default value of %c%.8g was " "assumed.", bj, equinox ); Warn( this, "noequinox", buf, method, class, status ); } } /* Convert the equinox to a Modified Julian Date. */ if( equinox != AST__BAD ) { if( bj == 'B' ) { eqmjd = palEpb2d( equinox ); } else { eqmjd = palEpj2d( equinox ); } } else { eqmjd = AST__BAD; } /* Get a value for the Epoch attribute. If no value is available, use EQUINOX and issue a warning. */ mjdobs = ChooseEpoch( this, store, s, method, class, status ); if( mjdobs == AST__BAD ) { mjdobs = eqmjd; if( mjdobs != AST__BAD ) { sprintf( buf, "The original FITS header did not specify the " "date of observation. A default value of %c%.8g was " "assumed.", bj, equinox ); Warn( this, "nomjd-obs", buf, method, class, status ); } } /* Create a SkyFrame for the specified system. */ if( !strcmp( sys, "E" ) ){ ret = astSkyFrame( "System=Ecliptic", status ); } else if( !strcmp( sys, "H" ) ){ ret = astSkyFrame( "System=Helioecliptic", status ); } else if( !(strcmp( sys, "G" ) ) ){ ret = astSkyFrame( "System=Galactic", status ); } else if( !(strcmp( sys, "S" ) ) ){ ret = astSkyFrame( "System=Supergalactic", status ); } else if( !(strcmp( sys, "AZL" ) ) ){ ret = astSkyFrame( "System=AzEl", status ); } else if( !(strcmp( sys, "EQU" ) ) ){ /* For equatorial systems, the specific system is given by the RADESYS value. */ if( radesys == FK4 ){ ret = astSkyFrame( "System=FK4", status ); } else if( radesys == FK4NOE ){ ret = astSkyFrame( "System=FK4-NO-E", status ); } else if( radesys == FK5 ){ ret = astSkyFrame( "System=FK5", status ); } else if( radesys == ICRS ){ ret = astSkyFrame( "System=ICRS", status ); } else if( radesys == GAPPT ){ ret = astSkyFrame( "System=GAPPT", status ); } else if( astOK ){ astError( AST__INTER, "%s(%s): Internal AST programming " "error - FITS equatorial coordinate system type %d " "not yet supported in WcsSkyFrame.", status, method, class, radesys ); } /* If an unknown celestial co-ordinate system was specified by the CTYPE keywords, add warning messages to the FitsChan and treat the axes as a general spherical coordinate system. */ } else if( astOK ){ report = 1; ret = astSkyFrame( "System=UNKNOWN", status ); strcpy( sym, sys ); if( strlen( sys ) == 1 ) { strcpy( sym + 1, "LON" ); astSetSymbol( ret, 0, sym ); strcpy( sym + 1, "LAT" ); astSetSymbol( ret, 1, sym ); } else { strcpy( sym + 2, "LN" ); astSetSymbol( ret, 0, sym ); strcpy( sym + 2, "LT" ); astSetSymbol( ret, 1, sym ); /* The code "OF" is used by AST to describe offset sky coordinates. Set the Domain to SKY_OFFSETS in these cases, so that we can identify these Frames later. */ if( !strcmp( sys, "OF" ) ) { astSetDomain( ret, "SKY_OFFSETS" ); report = 0; } } if( report ) { lontype = GetItemC( &(store->ctype), axlon, 0, s, NULL, method, class, status ); lattype = GetItemC( &(store->ctype), axlat, 0, s, NULL, method, class, status ); if( lontype && lattype ){ sprintf( buf, "This FITS header contains references to an unknown " "spherical co-ordinate system specified in the values " "%s and %s. It may not be possible to convert to " "other standard co-ordinate systems.", lontype, lattype ); Warn( this, "badcel", buf, method, class, status ); } } } /* If a skyFrame was created... */ if( ret ){ /* Store the projection description. */ if( prj != AST__WCSBAD ) astSetProjection( ret, astWcsPrjDesc( prj ) ); /* Store the epoch of the observation in the SkyFrame. */ if( mjdobs != AST__BAD ) astSetEpoch( ret, mjdobs ); /* For equatorial and ecliptic systems, store the epoch of the reference equinox in the SkyFrame. */ if( ( !strcmp( sys, "EQU" ) || !strcmp( sys, "ECL" ) ) && equinox != AST__BAD ) astSetEquinox( ret, eqmjd ); /* If either of the CNAME keywords is set, use it as the axis label. */ ckeyval = GetItemC( &(store->cname), axlon, 0, s, NULL, method, class, status ); if( ckeyval ) astSetLabel( ret, 0, ckeyval ); ckeyval = GetItemC( &(store->cname), axlat, 0, s, NULL, method, class, status ); if( ckeyval ) astSetLabel( ret, 1, ckeyval ); /* Observer's position (from primary axis descriptions). Get the OBSGEO-X/Y/Z keywords, convert to geodetic longitude and latitude and store as the SpecFrame's ObsLat, ObsLon and ObsAlt attributes. */ obsgeo[ 0 ] = GetItem( &(store->obsgeox), 0, 0, ' ', NULL, method, class, status ); obsgeo[ 1 ] = GetItem( &(store->obsgeoy), 0, 0, ' ', NULL, method, class, status ); obsgeo[ 2 ] = GetItem( &(store->obsgeoz), 0, 0, ' ', NULL, method, class, status ); if( obsgeo[ 0 ] != AST__BAD && obsgeo[ 1 ] != AST__BAD && obsgeo[ 2 ] != AST__BAD ) { eraGc2gd( 1, obsgeo, &geolon, &geolat, &h ); astSetObsLat( ret, geolat ); astSetObsLon( ret, geolon ); astSetObsAlt( ret, h ); } /* Store values for the reference point in the SkyFrame. */ dval = GetItem( &(store->skyref), axlon, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) astSetSkyRef( ret, 0, dval ); dval = GetItem( &(store->skyref), axlat, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) astSetSkyRef( ret, 1, dval ); dval = GetItem( &(store->skyrefp), axlon, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) astSetSkyRefP( ret, 0, dval ); dval = GetItem( &(store->skyrefp), axlat, 0, s, NULL, method, class, status ); if( dval != AST__BAD ) astSetSkyRefP( ret, 1, dval ); /* We cannot store the SkyRefIs value yet since this needs to be done after the SkyFrame has been added into the FrameSet, so that the Frame will be remapped to represent the intended offsets. SO instance, mark the Frame by setting the domain to "SKY_POLE" or "SKY_ORIGIN". This odd Domain value will be cleared later in TidyOffsets. */ ckeyval = GetItemC( &(store->skyrefis), 0, 0, s, NULL, method, class, status ); if( ckeyval ) { if( !Ustrcmp( "POLE", ckeyval, status ) ) { astSetDomain( ret, "SKY_POLE" ); } else if( !Ustrcmp( "ORIGIN", ckeyval, status ) ) { astSetDomain( ret, "SKY_ORIGIN" ); } } } /* If an error has occurred, annul the Frame. */ if( !astOK ) ret = astAnnul( ret ); /* Return the Frame. */ return ret; } static AstMapping *WcsSpectral( AstFitsChan *this, FitsStore *store, char s, AstFrame **frm, AstFrame *iwcfrm, double reflon, double reflat, AstSkyFrame *reffrm, const char *method, const char *class, int *status ){ /* * Name: * WcsSpectral * Purpose: * Create a Mapping from intermediate world coords to spectral coords * as described in a FITS header. * Type: * Private function. * Synopsis: * AstMapping *WcsSpectral( AstFitsChan *this, FitsStore *store, char s, * AstFrame **frm, AstFrame *iwcfrm, double reflon, * double reflat, AstSkyFrame *reffrm, * const char *method, const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function interprets the contents of the supplied FitsStore * structure, looking for world coordinate axes which describe positions * in a spectrum. If such an axis is found, a Mapping is returned which * transforms the corresponding intermediate world coordinates to * spectral world coordinates (this mapping leaves any other axes * unchanged). It also, modifies the supplied Frame to describe the * axis (again, other axes are left unchanged). If no spectral axis * is found, a UnitMap is returned, and the supplied Frame is left * unchanged. * Parameters: * this * The FitsChan. * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * frm * The address of a location at which to store a pointer to the * Frame describing the world coordinate axes. * iwcfrm * A pointer to the Frame describing the intermediate world coordinate * axes. The properties of this Frame may be changed on exit. * reflon * The reference celestial longitude, in the frame given by reffrm. * reflat * The reference celestial latitude, in the frame given by reffrm. * reffrm * The SkyFrame defining reflon and reflat. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstFrame *ofrm; /* Pointer to a Frame */ AstMapping *map1; /* Pointer to Mapping */ AstMapping *map2; /* Pointer to Mapping */ AstMapping *ret; /* Pointer to the returned Mapping */ AstSpecFrame *specfrm; /* Pointer to a SpecFrame */ char algcode[ 5 ]; /* Displayed spectral type string */ char stype[ 5 ]; /* Displayed spectral type string */ const char *cname; /* Pointer to CNAME value */ const char *ctype; /* Pointer to CTYPE value */ const char *cunit; /* Pointer to CUNIT value */ const char *defunit; /* Default unit string */ const char *specsys; /* Pointer to SPECSYS value */ const char *ssyssrc; /* Pointer to SSYSSRC value */ double geolat; /* Observer's geodetic latitude */ double geolon; /* Observer's geodetic longitude */ double h; /* Observer's geodetic height */ double mjd; /* Modified Julian Date */ double obscentre; /* Spectral value at observation centre */ double obsgeo[ 3 ]; /* Observer's Cartesian position */ double restfrq; /* RESTFRQ keyword value */ double vsource; /* Source velocity */ int *axes; /* Pointer to axis permutation array */ int i; /* Axis index */ int j; /* Loop count */ int k; /* Loop count */ int kk; /* Loop count */ int naxes; /* No. of axes in Frame */ /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Get the number of physical axes. */ naxes = astGetNaxes( *frm ); /* An array to hold a list of axis selections. */ axes = astMalloc( naxes*sizeof( int ) ); /* Loop round checking each axis. */ defunit = NULL; map1 = NULL; for( i = 0; i < naxes && astOK; i++ ) { /* Get the CTYPE value. Pass on to the next axis if no CTYPE is available. */ ctype = GetItemC( &(store->ctype), i, 0, s, NULL, method, class, status ); if( ctype ) { /* See if this CTYPE describes a spectral axis, and if so, extract the system code, the algorithm code and get the default units. */ defunit = IsSpectral( ctype, stype, algcode, status ); /* Skip to the next axis if the system type was not a spectral system type. */ if( defunit ) { /* Create a SpecFrame or DSBSpecFrame with this system (the FITS type codes are also legal SpecFrame System values). We use astSetC rather than astSetSystem because astSetC translates string values into the corresponding integer system identifiers. */ if( GetItem( &(store->imagfreq), 0, 0, s, NULL, method, class, status ) == AST__BAD ) { specfrm = astSpecFrame( "", status ); } else { specfrm = (AstSpecFrame *) astDSBSpecFrame( "", status ); } astSetC( specfrm, "System", stype ); /* Set the reference position (attributes RefRA and RefDec), if known. */ if( reffrm ) astSetRefPos( specfrm, reffrm, reflon, reflat ); /* Set the SpecFrame units. Use the value of the CUNIT FITS keyword for this axis if available, otherwise use the default units for the system, noted above. */ cunit = GetItemC( &(store->cunit), i, 0, s, NULL, method, class, status ); if( !cunit ) cunit = defunit; astSetUnit( specfrm, 0, cunit ); /* Set the axis unit in the IWC Frame. */ astSetUnit( iwcfrm, i, cunit ); /* Get a value for the Epoch attribute (the date of observation). */ mjd = ChooseEpoch( this, store, s, method, class, status ); if( mjd != AST__BAD ) astSetEpoch( specfrm, mjd ); /* Set the rest frequency. Use the RESTFRQ keyword (assumed to be in Hz), or (if RESTFRQ is not available), RESTWAV (assumes to be in m). */ restfrq = GetItem( &(store->restfrq), 0, 0, s, NULL, method, class, status ); if( restfrq == AST__BAD ) { restfrq = GetItem( &(store->restwav), 0, 0, s, NULL, method, class, status ); if( restfrq != AST__BAD ) restfrq = AST__C/restfrq; } astSetRestFreq( specfrm, restfrq ); /* Observer's position (from primary axis descriptions). Get the OBSGEO-X/Y/Z keywords, convert to geodetic longitude and latitude and store as the SpecFrame's ObsLat, ObsLon and ObsAlt attributes. */ obsgeo[ 0 ] = GetItem( &(store->obsgeox), 0, 0, ' ', NULL, method, class, status ); obsgeo[ 1 ] = GetItem( &(store->obsgeoy), 0, 0, ' ', NULL, method, class, status ); obsgeo[ 2 ] = GetItem( &(store->obsgeoz), 0, 0, ' ', NULL, method, class, status ); if( obsgeo[ 0 ] != AST__BAD && obsgeo[ 1 ] != AST__BAD && obsgeo[ 2 ] != AST__BAD ) { eraGc2gd( 1, obsgeo, &geolon, &geolat, &h ); astSetObsLat( specfrm, geolat ); astSetObsLon( specfrm, geolon ); astSetObsAlt( specfrm, h ); } /* Source velocity rest frame */ ssyssrc = GetItemC( &(store->ssyssrc), 0, 0, s, NULL, method, class, status ); if( ssyssrc ) astSetC( specfrm, "SourceVRF", ssyssrc ); /* Source velocity. Use the ZSOURCE keyword and convert from redshift to velocity. */ vsource = GetItem( &(store->zsource), 0, 0, s, NULL, method, class, status ); if( vsource != AST__BAD ) { vsource += 1.0; vsource *= vsource; vsource = AST__C*( vsource - 1.0 )/( vsource + 1.0 ); astSetSourceVel( specfrm, vsource ); } /* Reference frame. If the SPECSYS keyword is set, use it (the FITS codes are also legal SpecFrame StdOfRest values). We use astSetC rather than astSetSystem because astSetC translates string values into the corresponding integer system identifiers. */ specsys = GetItemC( &(store->specsys), 0, 0, s, NULL, method, class, status ); if( specsys ) astSetC( specfrm, "StdOfRest", specsys ); /* Axis label. If the CNAME keyword is set, use it as the axis label. */ cname = GetItemC( &(store->cname), i, 0, s, NULL, method, class, status ); if( cname ) astSetLabel( specfrm, 0, cname ); /* If the header contains an AXREF value for the spectral axis, use it as the observation centre in preferences to the CRVAL value. AXREF keywords are created by the astWrite method for axes described by -TAB algorithm that have no inverse transformation. */ obscentre = GetItem( &(store->axref), i, 0, s, NULL, method, class, status ); if( obscentre == AST__BAD ) { obscentre = GetItem( &(store->crval), i, 0, s, NULL, method, class, status ); } /* Now do the extra stuff needed if we are creating a dual sideband SpecFrame. */ if( astIsADSBSpecFrame( specfrm ) ) { DSBSetUp( this, store, (AstDSBSpecFrame *) specfrm, s, obscentre, method, class, status ); } /* Now branch for each type of algorithm code. Each case returns a 1D Mapping which converts IWC value into the specified Spectral system. */ /* Linear */ if( strlen( algcode ) == 0 ) { map1 = LinearWcs( store, i, s, method, class, status ); /* Log-Linear */ } else if( !strcmp( "-LOG", algcode ) ) { map1 = LogWcs( store, i, s, method, class, status ); /* Non-Linear */ } else if( algcode[ 0 ] == '-' && algcode[ 2 ] == '2' ) { map1 = NonLinSpecWcs( this, algcode, store, i, s, specfrm, method, class, status ); /* Grism */ } else if( !strcmp( "-GRI", algcode ) || !strcmp( "-GRA", algcode ) ) { map1 = GrismSpecWcs( algcode, store, i, s, specfrm, method, class, status ); } else { map1 = NULL; } if( map1 == NULL && astOK ) { specfrm = astAnnul( specfrm ); astError( AST__BDFTS, "%s(%s): Cannot implement spectral " "algorithm code '%s' specified in FITS keyword '%s'.", status, method, class, ctype + 4, FormatKey( "CTYPE", i + 1, -1, s, status ) ); astError( AST__BDFTS, "%s(%s): Unknown algorithm code or " "unusable parameter values.", status, method, class ); break; } /* Create a Frame by picking all the other (non-spectral) axes from the supplied Frame. */ j = 0; for( k = 0; k < naxes; k++ ) { if( k != i ) axes[ j++ ] = k; } /* If there were no other axes, replace the supplied Frame with the specframe. */ if( j == 0 ) { (void) astAnnul( *frm ); *frm = (AstFrame *) specfrm; /* Otherwise pick the other axes from the supplied Frame */ } else { ofrm = astPickAxes( *frm, j, axes, NULL ); /* Replace the supplied Frame with a CmpFrame made up of this Frame and the SpecFrame. */ (void) astAnnul( *frm ); *frm = (AstFrame *) astCmpFrame( ofrm, specfrm, "", status ); ofrm = astAnnul( ofrm ); specfrm = astAnnul( specfrm ); } /* Permute the axis order to put the spectral axis back in its original position. */ j = 0; for( kk = 0; kk < naxes; kk++ ) { if( kk == i ) { axes[ kk ] = naxes - 1; } else { axes[ kk ] = j++; } } astPermAxes( *frm, axes ); } } /* If this axis is not a spectral axis, create a UnitMap (the Frame is left unchanged). */ if( !map1 && astOK ) map1 = (AstMapping *) astUnitMap( 1, "", status ); /* Add the Mapping for this axis in parallel with the Mappings for previous axes. */ if( ret ) { map2 = (AstMapping *) astCmpMap( ret, map1, 0, "", status ); ret = astAnnul( ret ); map1 = astAnnul( map1 ); ret = map2; } else { ret = map1; map1 = NULL; } } /* Free the axes array. */ axes= astFree( axes ); /* Return the result. */ return ret; } static void WcsToStore( AstFitsChan *this, AstFitsChan *trans, FitsStore *store, const char *method, const char *class, int *status ){ /* * Name: * WcsToStore * Purpose: * Extract WCS information from the supplied FitsChan using a FITSWCS * encoding, and store it in the supplied FitsStore. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WcsToStore( AstFitsChan *this, AstFitsChan *trans, * FitsStore *store, const char *method, * const char *class, int *status ) * Class Membership: * FitsChan member function. * Description: * A FitsStore is a structure containing a generalised represention of * a FITS WCS FrameSet. Functions exist to convert a FitsStore to and * from a set of FITS header cards (using a specified encoding), or * an AST FrameSet. In other words, a FitsStore is an encoding- * independant intermediary staging post between a FITS header and * an AST FrameSet. * * This function extracts FITSWCS keywords from the supplied FitsChan(s), * and stores the corresponding WCS information in the supplied FitsStore. * Keywords will be searched for first in "trans", and then, if they * are not found in "trans", they will be searched for in "this". * Parameters: * this * Pointer to the FitsChan containing the cards read from the * original FITS header. This may include non-standard keywords. * trans * Pointer to a FitsChan containing cards representing standard * translations of any non-standard keywords in "this". A NULL * pointer indicates that "this" contains no non-standard keywords. * store * Pointer to the FitsStore structure. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Read all usable cards out of the main FitsChan, into the FitsStore. */ WcsFcRead( this, trans, store, method, class, status ); /* If a FitsChan containing standard translations was supplied, read all cards out of it, into the FitsStore, potentially over-writing the non-standard values stored in the previous call to WcsFcRead. */ if( trans ) WcsFcRead( trans, NULL, store, method, class, status ); } static int WorldAxes( AstFitsChan *this, AstMapping *cmap, double *dim, int *perm, int *status ){ /* * Name: * WorldAxes * Purpose: * Associate final world axes with pixel axes. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int WorldAxes( AstFitsChan *this, AstMapping *cmap, double *dim, int *perm, * int *status ) * Class Membership: * FitsChan * Description: * This function finds the association between the axes of the final * world coordinate system, and those of the pixel coordinate * system. This may not simply be a 1-to-1 association because the * Mapping may include a PermMap. Each output axis is associated with * the input axis which is most nearly aligned with it. * Parameters: * this * Pointer to the FitsChan. * cmap * Pointer to the Mapping from pixel coordinates to final world * coordinates. * dim * Pointer to an array with one element for each input of "map", * supplied holding the no. of pixels in the data cube along the axis, or * AST__BAD If unknown. * perm * Pointer to an array with one element for each output of "map". * On exit, each element of this array holds the zero-based index of the * "corresponding" (i.e. most nearly parallel) pixel axis. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero for success - zero for failure. */ /* Local Variables: */ AstMapping *smap; AstMapping *map; AstPointSet *pset1; AstPointSet *pset2; double **ptr2; double **ptr1; double *dw; double *g0; double *nwt; double *ntn; double *tn; double *wt; double *w0; double dg; double s; double sj; double tnmin; double wtmax; int *outs; int i2; int i; int imin; int j2; int j; int jmin; int nin; int nout; int nouts; int nused; int ret; int retain; int used; /* Initialise returned value */ ret = 0; /* Other initialisation to avoid compiler warnings. */ retain = 0; /* Check the status */ if( !astOK ) return ret; /* Simplfy the Mapping. */ map = astSimplify( cmap ); /* Get the number of inputs and outputs for the Mapping. */ nin = astGetNin( map ); nout = astGetNout( map ); /* Initialise "perm". */ for( i = 0; i < nout; i++ ) perm[ i ] = i; /* First deal with Mappings that are defined in both directions. */ if( astGetTranForward( map ) && astGetTranInverse( map ) ) { /* Use FindBasisVectors to find an input position which coresponds to a good output position. Store it in a dynamic array pointed to by "g0". */ pset1 = astPointSet( nin+1, nin, "", status ); pset2 = astPointSet( nin+1, nout, "", status ); if( FindBasisVectors( map, nin, nout, dim, pset1, pset2, status ) ) { g0 = astMalloc( sizeof(double)*nin ); ptr1 = astGetPoints( pset1 ); if( astOK ) { for( j = 0; j < nin; j++ ) g0[ j ] = ptr1[ j ][ 0 ]; } pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* If no basis vectors found, return. */ } else { pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); return ret; } /* Create Pointset to hold two input (pixel) points. */ pset1 = astPointSet( 2, nin, "", status ); ptr1 = astGetPoints( pset1 ); /* Create a Pointset to hold the same number of output (world) points. */ pset2 = astPointSet( 2, nout, "", status ); ptr2 = astGetPoints( pset2 ); /* Allocate memory to use as work space */ w0 = astMalloc( sizeof(double)*nout ); dw = astMalloc( sizeof(double)*nout ); tn = astMalloc( sizeof(double)*nout*nin ); wt = astMalloc( sizeof(double)*nout*nin ); /* Check that the pointers can be used. */ if( astOK ) { /* Transform the grid position found above, plus a position 1 pixel away along all pixel axes, into world coords. Also set up "dw" to hold "a small increment" along each world axis. */ for( j = 0; j < nin; j++ ) { ptr1[ j ] [ 0 ] = g0[ j ]; ptr1[ j ] [ 1 ] = g0[ j ] + 1.0; } (void) astTransform( map, pset1, 1, pset2 ); for( i = 0; i < nout; i++ ) { w0[ i ] = ptr2[ i ] [ 0 ]; if( w0[ i ] != AST__BAD && ptr2[ i ] [ 1 ] != AST__BAD ) { dw[ i ] = fabs( 0.1*( ptr2[ i ] [ 1 ] - w0[ i ] ) ); if( dw[ i ] <= fabs( 0.001*w0[ i ] ) ) { if( w0[ i ] != 0.0 ) { dw[ i ] = fabs( 0.001*w0[ i ] ); } else { dw[ i ] = 1.0; } } } else { dw[ i ] = AST__BAD; } } /* Any PermMap in the mapping may result in the the "inverse transformation" not being a true inverse of the forward transformation (for instance, constant values fed in for degenerate axis would have this effect). To ensure that "g0" and "w0" are corresponding positions, transform the "w0" position back into grid coords and use the resulting grid position as "g0". */ (void) astTransform( map, pset2, 0, pset1 ); for( j = 0; j < nin; j++ ) { g0[ j ] = ptr1[ j ] [ 0 ]; } /* In the next loop we find the tan of the angle between each WCS axis and each of the pixel axes. Loop round each WCS axis. */ for( i = 0; i < nout; i++ ) { /* Initialise the tan values for this WCS axis to AST__BAD. */ ntn = tn + i*nin; nwt = wt + i*nin; for( j = 0; j < nin; j++ ) ntn[ j ] = AST__BAD; /* As a side issue, initialise the pixel axis assigned to each WCS axis to -1, to indicate that no grid axis has yet been associated with this WCS axis. */ perm[ i ] = -1; /* Skip over this axis if the increment is bad. */ if( dw[ i ] != AST__BAD ) { /* Store a WCS position which is offset from the "w0" position by a small amount along the current WCS axis. The first position in "ptr2" is currently "w0". */ ptr2[ i ][ 0 ] += dw[ i ]; /* Transform this position into grid coords. */ (void) astTransform( map, pset2, 0, pset1 ); /* Re-instate the original "w0" values within "ptr2", ready for the next WCS axis. */ ptr2[ i ][ 0 ] = w0[ i ]; /* Consider each pixel axis in turn as a candidate for being assigned to the current WCS axis. */ for( j = 0; j < nin; j++ ) { /* Find the tan of the angle between the current ("i"th) WCS axis and the current ("j"th) pixel axis. This gets stored in tn[j+nin*i]. A corresponding weight for each angle is stored in nwt[j+nin*i]. This is the length of the projection of the vector onto the "j"th pixel axis. */ s = 0.0; sj = 0.0; for( j2 = 0; j2 < nin; j2++ ) { if( ptr1[ j2 ][ 0 ] != AST__BAD ) { dg = ptr1[ j2 ][ 0 ] - g0[ j2 ]; if( j2 != j ) { s += dg*dg; } else { sj = fabs( dg ); } } else { s = AST__BAD; break; } } if( s != AST__BAD && sj != 0.0 ) { ntn[ j ] = sqrt( s )/sj; nwt[ j ] = sj; } } } } /* Loop until every grid axes has been assigned to a WCS axis. */ while( 1 ) { /* Pass through the array of tan values, finding the smallest. Note the pixel and WCS axis for which the smallest tan value occurs. If the tan values are equal, favour the one with highest weight. */ ntn = tn; nwt = wt; tnmin = AST__BAD; wtmax = AST__BAD; imin = 0; jmin = 0; for( i = 0; i < nout; i++ ) { for( j = 0; j < nin; j++ ) { if( *ntn != AST__BAD ) { if( tnmin == AST__BAD || *ntn < tnmin ) { tnmin = *ntn; wtmax = *nwt; imin = i; jmin = j; } else if( astEQUAL( *ntn, tnmin ) && *nwt > wtmax ) { wtmax = *nwt; imin = i; jmin = j; } } ntn++; nwt++; } } /* Check we found a usable minimum tan value */ if( tnmin != AST__BAD ) { /* Assign the pixel axis to the WCS axis. */ perm[ imin ] = jmin; /* Set bad all the tan values for this pixel and WCS axis pair. This ensures that the pixel axis will not be assigned to another WCS axis, and that the WCS will not have another pixel axis assigned to it. */ ntn = tn; for( i = 0; i < nout; i++ ) { for( j = 0; j < nin; j++ ) { if( i == imin || j == jmin ) *ntn = AST__BAD; ntn++; } } /* Leave the loop if no more good tan values were found. */ } else { break; } } /* The above process may have left some WCS axes with out any assigned pixel axis. We assign the remaining pixel arbitrarily to such axes, starting with the first remaining pixel axis. Find the lowest unused pixel axis. */ for( j = 0; j < nin; j++ ) { used = 0; for( i = 0; i < nout; i++ ) { if( perm[ i ] == j ) { used = 1; break; } } if( !used ) break; } /* Now check each WCS axis looking for outputs which were not assigned a pixel axis in the above process. */ for( i = 0; i < nout; i++ ) { if( perm[ i ] == -1 ) { /* Use the next unused axis value. */ perm[ i ] = j++; /* Find the next unused axis value. */ for( ; j < nin; j++ ) { used = 0; for( i2 = 0; i2 < nout; i2++ ) { if( perm[ i2 ] == j ) { used = 1; break; } } if( !used ) break; } } } /* Indicate success. */ if( astOK ) ret = 1; } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); g0 = astFree( g0 ); w0 = astFree( w0 ); tn = astFree( tn ); wt = astFree( wt ); dw = astFree( dw ); /* Now, if we can use the TAB algorithm, deal with Mappings that are defined only in the forward direction. */ } else if( astGetTranForward( map ) && astGetTabOK( this ) > 0 ) { /* Assume success. */ ret = 1; /* Initialise to indicate no outputs have yet been assigned. */ for( i = 0; i < nout; i++ ) perm[ i ] = -1; /* Find the output associated with each input. */ for( j = 0; j < nin; j++ ) { /* Attempt to split off the current input. */ outs = astMapSplit( map, 1, &j, &smap ); /* If successfull, store the index of the corresponding input for each output. */ if( outs && smap ) { nouts = astGetNout( smap ); for( i = 0; i < nouts; i++ ) { if( perm[ outs[ i ] ] == -1 ) { perm[ outs[ i ] ] = j; } else { ret = 0; } } } /* Free resources. */ outs = astFree( outs ); if( smap ) smap = astAnnul( smap ); } /* Check all outputs were assigned . */ for( i = 0; i < nout && ret; i++ ) { if( perm[ i ] == -1 ) ret = 0; } /* If succesful, attempt to remove any duplicates from the "perm" array (i.e. inputs that supply more than one output). First get a list of the inputs that are currently unused (i.e. do not appear in "perm"). */ if( ret ) { /* Check each input. */ for( j = 0; j < nin; j++ ) { /* See how many outputs are fed by this input. */ nused = 0; for( i = 0; i < nout; i++ ) { if( perm[ i ] == j ) nused++; } /* If it used more than once, we need to remove all but one of the occurrences. */ if( nused > 1 ) { /* Choose the occurrence to retain. If the output with the same index as the input is one of them, use it. Otherwise, use the first occurrence. */ if( perm[ j ] == j ) { retain = j; } else { for( i = 0; i < nout; i++ ) { if( perm[ i ] == j ) { retain = i; break; } } } /* Loop round all occurrences of this input again. */ for( i = 0; i < nout && ret; i++ ) { if( perm[ i ] == j ) { /* Replace all occurrences, except for the one being retained. */ if( i != retain ) { /* Replace it with the next unused input. */ for( j2 = 0; j2 < nin; j2++ ) { used = 0; for( i2 = 0; i2 < nout; i2++ ) { if( perm[ i2 ] == j2 ) { used = 1; break; } } if( ! used ) { perm[ i ] = j2; break; } } /* If there were no unused inputs, we cannot do it. */ if( used ) ret = 0; } } } } } } } /* Free resources. */ map = astAnnul( map ); /* Return the result. */ return ret; } static int Write( AstChannel *this_channel, AstObject *object, int *status ) { /* * Name: * Write * Purpose: * Write an Object to a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * int Write( AstChannel *this, AstObject *object, int *status ) * Class Membership: * FitsChan member function (over-rides the astWrite method * inherited from the Channel class). * Description: * This function writes an Object to a FitsChan. * Parameters: * this * Pointer to the FitsChan. * object * Pointer to the Object which is to be written. * status * Pointer to the inherited status variable. * Returned Value: * The number of Objects written to the FitsChan by this invocation of * astWrite. * Notes: * - A value of zero will be returned if this function is invoked * with the AST error status set, or if it should fail for any * reason. * - The Base Frame in the FrameSet is used as the pixel Frame, and * the Current Frame is used to create the primary axis descriptions. * Attempts are made to create secondary axis descriptions for any * other Frames in the FrameSet (up to a total of 26). */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure */ FitsStore *store; /* Intermediate storage for WCS information */ char banner[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ]; /* Buffer for begin/end banner */ const char *class; /* Pointer to string holding object class */ const char *method; /* Pointer to string holding calling method */ double *dim; /* Pointer to array of axis dimensions */ int card0; /* Index of original current card */ int comm; /* Value of Comm attribute */ int encoding; /* FITS encoding scheme to use */ int i; /* Axis index */ int naxis; /* No. of pixel axes */ int ret; /* Number of objects read */ /* Initialise. */ ret = 0; /* Check the global error status. */ if ( !astOK ) return ret; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Ensure the source function has been called */ ReadFromSource( this, status ); /* Store the calling method, and object class. */ method = "astWrite"; class = astGetClass( this ); /* The original current card is re-instated at the end if no object is written. Save its index. */ card0 = astGetCard( this ); /* Indicate that all cards added to the FitsCHan by this call should be marked as "new". */ mark_new = 1; /* Get the encoding scheme used by the FitsChan. */ encoding = astGetEncoding( this ); /* First deal with cases where we are writing to a FitsChan in which AST objects are encoded using native AST-specific keywords... */ if( encoding == NATIVE_ENCODING ){ /* Increment the nesting level which keeps track of recursive invocations of this function. */ write_nest++; /* Initialise the current indentation level for top-level objects. */ if ( !write_nest ) current_indent = 0; /* Obtain the value of the Comm attribute. */ comm = astGetComment( this ); /* If this is the top-level invocation (i.e. we are about to write out a new top-level Object), then prefix it with a blank FITS line and an appropriate banner of FITS comments, unless comments have been suppressed. */ if ( !write_nest && comm ) { astSetFitsCom( this, " ", "", 0 ); MakeBanner( "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); if( astIsAFrameSet( object ) ) { MakeBanner( "WCS information in AST format", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); MakeBanner( "See http://www.starlink.ac.uk/ast/", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); } MakeBanner( HEADER_TEXT, astGetClass( object ), " object", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); MakeBanner( "................................................................", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); } /* Invoke the parent astWrite method to write out the Object data. */ (*parent_write)( this_channel, object, status ); /* Append a banner of FITS comments to the object data, as above, if necessary. */ if ( !write_nest && comm ) { MakeBanner( "................................................................", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); MakeBanner( FOOTER_TEXT, astGetClass( object ), " object", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); MakeBanner( "----------------------------------------------------------------", "", "", banner, status ); astSetFitsCom( this, "COMMENT", banner, 0 ); } /* Return the nesting level to its previous value. */ write_nest--; /* Indicate that an object has been written. */ ret = 1; /* Now deal with cases where we are writing to a FitsChan in which AST objects are encoded using any of the supported foreign encodings... */ } else { /* Only proceed if the supplied object is a FrameSet. */ if( astIsAFrameSet( object ) ){ /* Note the number of pixel (i.e. Base Frame) axes, and allocate memory to hold the image dimensions. */ naxis = astGetNin( (AstFrameSet *) object ); dim = (double *) astMalloc( sizeof(double)*naxis ); if( dim ){ /* Note the image dimensions, if known. If not, store AST__BAD values. */ for( i = 0; i < naxis; i++ ){ if( !astGetFitsF( this, FormatKey( "NAXIS", i + 1, -1, ' ', status ), dim + i ) ) dim[ i ] = AST__BAD; } /* Extract the required information from the FrameSet into a standard intermediary structure called a FitsStore. The indices of any celestial axes are returned. */ store = FsetToStore( this, (AstFrameSet *) object, naxis, dim, encoding, method, class, status ); /* If the FrameSet cannot be described in terms of any of the supported FITS encodings, a null pointer will have been returned. */ if( store ){ /* Now put header cards describing the contents of the FitsStore into the supplied FitsChan, using the requested encoding. Zero or one is returned depending on whether the information could be encoded. */ ret = FitsFromStore( this, store, encoding, dim, (AstFrameSet *) object, method, class, status ); /* Release the resources used by the FitsStore. */ store = FreeStore( store, status ); /* If the Object was written to the FitsChan, set the current card to end-of-file. */ if( ret ) astSetCard( this, INT_MAX ); } /* Free workspace holding image dimensions */ dim = (double *) astFree( (void *) dim ); } } } /* If an error has occurred, return zero and remove any new cards added to the FitsCHan by this call. */ if( !astOK ) ret = 0; /* Clear the new flag associated with cards which have been added to the FitsChan as a result of this function. If the object was not added succesfully to the FitsChan, remove any cards which were added before the error was discovered. */ FixNew( this, NEW1, !ret, method, class, status ); FixNew( this, NEW2, !ret, method, class, status ); /* Indicate that all cards added to the FitsChan from now on should not be marked as "new". */ mark_new = 0; /* If no object was written, re-instate the original current card. */ if( !ret ) astSetCard( this, card0 ); /* Return the answer. */ return ret; } static void WriteBegin( AstChannel *this_channel, const char *class, const char *comment, int *status ) { /* * Name: * WriteBegin * Purpose: * Write a "Begin" data item to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteBegin( AstChannel *this, const char *class, * const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected astWriteBegin * method inherited from the Channel class). * Description: * This function writes a "Begin" data item to the data sink * associated with a FitsChan, so as to begin the output of a new * Object definition. * Parameters: * this * Pointer to the FitsChan. * class * Pointer to a constant null-terminated string containing the * name of the class to which the Object belongs. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the "Begin" * item. Normally, this will describe the purpose of the Object. * Notes: * - The comment supplied may not actually be used, depending on * the nature of the FitsChan supplied. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char buff[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ]; /* Character buffer */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Increment the indentation level for comments. */ current_indent += INDENT_INC; /* If we are not beginning a top-level Object definition, and helpful information has not been suppressed, generate an indented comment to mark the "Begin" item and write it to the FitsChan as a comment card with a blank keyword. */ if ( write_nest && ( astGetFull( this ) >= 0 ) ) { MakeIndentedComment( current_indent, '+', "Beginning of ", class, buff, status ); astSetFitsCom( this, " ", buff, 0 ); } /* Create a unique FITS keyword for this "Begin" item, basing it on "BEGAST". */ CreateKeyword( this, "BEGAST", keyword, status ); /* Generate a pre-quoted version of the class name. */ PreQuote( class, buff, status ); /* Write the "Begin" item to the FitsChan as a keyword and string value. */ astSetFitsS( this, keyword, buff, astGetComment( this ) ? comment : NULL, 0 ); /* Clear the count of items written. */ items_written = 0; } static void WriteDouble( AstChannel *this_channel, const char *name, int set, int helpful, double value, const char *comment, int *status ) { /* * Name: * WriteDouble * Purpose: * Write a double value to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteDouble( AstChannel *this, const char *name, * int set, int helpful, * double value, const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected * astWriteDouble method inherited from the Channel class). * Description: * This function writes a named double value, representing the * value of a class instance variable, to the data sink associated * with a FitsChan. It is intended for use by class "Dump" * functions when writing out class information which will * subsequently be re-read. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * FitsChan's Full attribute is set - either to permit all * values to be shown, or to suppress non-essential information * entirely. * value * The value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the FitsChan supplied and the setting of its * Comm attribute. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Use the "set" and "helpful" flags, along with the FitsChan's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Create a unique FITS keyword from the name supplied. */ CreateKeyword( this, name, keyword, status ); /* Write the value to the FitsChan as a keyword and value */ astSetFitsF( this, keyword, value, astGetComment( this ) ? comment : NULL, 0 ); /* If the value is not "set", replace the card just written by a COMMENT card containing the text of the card as the comment. */ if( !set ) MakeIntoComment( this, "astWrite", astGetClass( this ), status ); /* Increment the count of items written. */ items_written++; } } static void WriteEnd( AstChannel *this_channel, const char *class, int *status ) { /* * Name: * WriteEnd * Purpose: * Write an "End" data item to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteEnd( AstChannel *this, const char *class ) * Class Membership: * FitsChan member function (over-rides the protected astWriteEnd * method inherited from the Channel class). * Description: * This function writes an "End" data item to the data sink * associated with a FitsChan. This item delimits the end of an * Object definition. * Parameters: * this * Pointer to the FitsChan. * class * Pointer to a constant null-terminated string containing the * class name of the Object whose definition is being terminated * by the "End" item. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char buff[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ]; /* Character buffer */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Create a unique FITS keyword for this "End" item, basing it on "ENDAST". */ CreateKeyword( this, "ENDAST", keyword, status ); /* Generate a pre-quoted version of the class name. */ PreQuote( class, buff, status ); /* Write the "End" item to the FitsChan as a keyword and string value. */ astSetFitsS( this, keyword, buff, astGetComment( this ) ? "End of object definition" : NULL, 0 ); /* If we are not ending a top-level Object definition, and helpful information has not been suppressed, generate an indented comment to mark the "End" item and write it to the FitsChan as a comment card with a blank keyword. */ if ( write_nest && ( astGetFull( this ) >= 0 ) ) { MakeIndentedComment( current_indent, '-', "End of ", class, buff, status ); astSetFitsCom( this, " ", buff, 0 ); } /* Decrement the indentation level for comments. */ current_indent -= INDENT_INC; } static void WriteFits( AstFitsChan *this, int *status ){ /* *++ * Name: c astWriteFits f AST_WRITEFITS * Purpose: * Write out all cards in a FitsChan to the sink function. * Type: * Public virtual function. * Synopsis: c #include "fitschan.h" c void astWriteFits( AstFitsChan *this ) f CALL AST_WRITEFITS( THIS, STATUS ) * Class Membership: * FitsChan method. * Description: c This function f This routine * writes out all cards currently in the FitsChan. If the SinkFile * attribute is set, they will be written out to the specified sink file. * Otherwise, they will be written out using the sink function specified * when the FitsChan was created. All cards are then deleted from the * FitsChan. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the FitsChan. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If the SinkFile is unset, and no sink function is available, this * method simply empties the FitsChan, and is then equivalent to c astEmptyFits. f AST_EMPTYFITS. * - This method attempt to execute even if an error has occurred * previously. *-- */ /* Ensure a FitsChan was supplied. */ if( this ) { /* Ensure the source function has been called */ ReadFromSource( this, status ); /* We can usefully use the local destructor function to do the work, since it only frees resources used within teh FitsChan, rather than freeing the FitsChan itself. */ Delete( (AstObject *) this, status ); } } static void WriteInt( AstChannel *this_channel, const char *name, int set, int helpful, int value, const char *comment, int *status ) { /* * Name: * WriteInt * Purpose: * Write an int value to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteInt( AstChannel *this, const char *name, * int set, int helpful, * int value, const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected * astWriteInt method inherited from the Channel class). * Description: * This function writes a named int value, representing the * value of a class instance variable, to the data sink associated * with a FitsChan. It is intended for use by class "Dump" * functions when writing out class information which will * subsequently be re-read. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * FitsChan's Full attribute is set - either to permit all * values to be shown, or to suppress non-essential information * entirely. * value * The value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the FitsChan supplied and the setting of its * Comm attribute. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Use the "set" and "helpful" flags, along with the FitsChan's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Create a unique FITS keyword from the name supplied. */ CreateKeyword( this, name, keyword, status ); /* Write the value to the FitsChan as a keyword and value */ astSetFitsI( this, keyword, value, astGetComment( this ) ? comment : NULL, 0 ); /* If the value is not "set", replace the card just written by a COMMENT card containing the text of the card as the comment. */ if( !set ) MakeIntoComment( this, "astWrite", astGetClass( this ), status ); /* Increment the count of items written. */ items_written++; } } static void WriteIsA( AstChannel *this_channel, const char *class, const char *comment, int *status ) { /* * Name: * WriteIsA * Purpose: * Write an "IsA" data item to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteIsA( AstChannel *this, const char *class, * const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected astWriteIsA * method inherited from the Channel class). * Description: * This function writes an "IsA" data item to the data sink * associated with a FitsChan. This item delimits the end of the * data associated with the instance variables of a class, as part * of an overall Object definition. * Parameters: * this * Pointer to the FitsChan. * class * Pointer to a constant null-terminated string containing the * name of the class whose data are terminated by the "IsA" * item. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the "IsA" * item. Normally, this will describe the purpose of the class * whose data are being terminated. * Notes: * - The comment supplied may not actually be used, depending on * the nature of the FitsChan supplied. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char buff[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN + 1 ]; /* Character buffer */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Output an "IsA" item only if there has been at least one item written since the last "Begin" or "IsA" item, or if the Full attribute for the Channel is greater than zero (requesting maximum information). */ if ( items_written || astGetFull( this ) > 0 ) { /* Create a unique FITS keyword for this "IsA" item, basing it on "ISA". */ CreateKeyword( this, "ISA", keyword, status ); /* Generate a pre-quoted version of the class name. */ PreQuote( class, buff, status ); /* Write the "IsA" item to the FitsChan as a keyword and string value. */ astSetFitsS( this, keyword, buff, astGetComment( this ) ? comment : NULL, 0 ); /* If helpful information has not been suppressed, generate an indented comment to mark the "IsA" item and write it to the FitsChan as a comment card with a blank keyword. */ if ( astGetFull( this ) >= 0 ) { MakeIndentedComment( current_indent, '.', "Class boundary", "", buff, status ); astSetFitsCom( this, " ", buff, 0 ); } } /* Clear the count of items written. */ items_written = 0; } static void WriteObject( AstChannel *this_channel, const char *name, int set, int helpful, AstObject *value, const char *comment, int *status ) { /* * Name: * WriteObject * Purpose: * Write an Object value to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteObject( AstChannel *this, const char *name, * int set, int helpful, * AstObject *value, const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected * astWriteObject method inherited from the Channel class). * Description: * This function writes a named Object value, representing the * value of a class instance variable, to the data sink associated * with a FitsChan. It is intended for use by class "Dump" * functions when writing out class information which will * subsequently be re-read. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * FitsChan's Full attribute is set - either to permit all * values to be shown, or to suppress non-essential information * entirely. * value * A pointer to the Object to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the FitsChan supplied and the setting of its * Comm attribute. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Use the "set" and "helpful" flags, along with the FitsChan's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Create a unique FITS keyword from the name supplied. */ CreateKeyword( this, name, keyword, status ); /* Write the value to the FitsChan as a keyword and a blank string value, not pre-quoted (this "null" value indicates that an Object description follows). */ astSetFitsS( this, keyword, "", astGetComment( this ) ? comment : NULL, 0 ); /* If the value is "set", write out the Object description. */ if ( set ) { astWrite( this, value ); /* If the value is not set, replace the card just written to the FitsChan by COMENT card containing the keyword and blank string value (do not write out the Object description). */ } else { MakeIntoComment( this, "astWrite", astGetClass( this ), status ); } /* Increment the count of items written. */ items_written++; } } static void WriteToSink( AstFitsChan *this, int *status ){ /* * Name: * WriteToSink * Purpose: * Write the contents of the FitsChan out to the sink file or function. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteToSink( AstFitsChan *this, int *status ) * Class Membership: * FitsChan member function. * Description: * If the SinkFile attribute is set, each card in the FitsChan is * written out to the sink file. Otherwise, the cards are passed in * turn to the sink function specified when the FitsChan was created. * If no sink function was provided, the cards are not written out. * Cards marked as having been read into an AST object are not written * out. * Parameters: * this * Pointer to the FitsChan. * status * Pointer to the inherited status variable. * Notes: * - The current card is left unchanged. */ /* Local Constants: */ #define ERRBUF_LEN 80 /* Local Variables: */ FILE *fd; /* File descriptor for sink file */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *errstat; /* Pointer for system error message */ char card[ AST__FITSCHAN_FITSCARDLEN + 1]; /* Buffer for header card */ char errbuf[ ERRBUF_LEN ]; /* Buffer for system error message */ const char *sink_file; /* Path to output sink file */ int icard; /* Current card index on entry */ int old_ignore_used; /* Original value of external variable ignore_used */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* If the SinkFile attribute is set, open the file. */ fd = NULL; if( astTestSinkFile( this ) ) { sink_file = astGetSinkFile( this ); fd = fopen( sink_file, "w" ); if( !fd ) { if ( errno ) { #if HAVE_STRERROR_R strerror_r( errno, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( errno ); #endif astError( AST__WRERR, "astDelete(%s): Failed to open output " "SinkFile '%s' - %s.", status, astGetClass( this ), sink_file, errstat ); } else { astError( AST__WRERR, "astDelete(%s): Failed to open output " "SinkFile '%s'.", status, astGetClass( this ), sink_file ); } } } /* Only proceed if a file was opened, or sink function and wrapper were supplied. */ if( fd || ( this->sink && this->sink_wrap ) ){ /* Store the current card index. */ icard = astGetCard( this ); /* Indicate that cards which have been read into an AST object should skipped over by the functions which navigate the linked list of cards. */ old_ignore_used = ignore_used; ignore_used = 1; /* Ensure that the first card in the FitsChan will be the next one to be read. */ astSetCard( this, 1 ); /* Loop round obtaining and writing out each card, until all cards have been processed. */ while( !astFitsEof( this ) && astOK ){ /* Get the current card, and write it out through the sink function. The call to astFindFits increments the current card. */ if( astFindFits( this, "%f", card, 1 ) ) { /* If s sink file was opened, write the card out to it. */ if( fd ) { fprintf( fd, "%s\n", card ); /* Otherwise, use the isnk function. The sink function is an externally supplied function which may not be thread-safe, so lock a mutex first. Also store the channel data pointer in a global variable so that it can be accessed in the sink function using macro astChannelData. */ } else { astStoreChannelData( this ); LOCK_MUTEX3; ( *this->sink_wrap )( *this->sink, card, status ); UNLOCK_MUTEX3; } } } /* Re-instate the original flag indicating if cards marked as having been read should be skipped over. */ ignore_used = old_ignore_used; /* Set the current card index back to what it was on entry. */ astSetCard( this, icard ); } /* Close the sink file. */ if( fd ) fclose( fd ); } static void WriteString( AstChannel *this_channel, const char *name, int set, int helpful, const char *value, const char *comment, int *status ) { /* * Name: * WriteString * Purpose: * Write a string value to a data sink. * Type: * Private function. * Synopsis: * #include "fitschan.h" * void WriteString( AstChannel *this, const char *name, * int set, int helpful, * const char *value, const char *comment ) * Class Membership: * FitsChan member function (over-rides the protected * astWriteString method inherited from the Channel class). * Description: * This function writes a named string value, representing the * value of a class instance variable, to the data sink associated * with a FitsChan. It is intended for use by class "Dump" * functions when writing out class information which will * subsequently be re-read. * Parameters: * this * Pointer to the FitsChan. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * FitsChan's Full attribute is set - either to permit all * values to be shown, or to suppress non-essential information * entirely. * value * Pointer to a constant null-terminated string containing the * value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the FitsChan supplied and the setting of its * Comm attribute. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFitsChan *this; /* Pointer to the FitsChan structure. */ char *c; /* Pointer to next buffer character */ char buff1[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 3 ]; /* Buffer for a single substring */ char buff2[ AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 3 ]; /* Buffer for pre-quoted string */ char cc; /* Next character */ char keyword[ FITSNAMLEN + 1 ]; /* Buffer for FITS keyword */ const char *start; /* Pointer to start of substring */ int first; /* Is this the first sub-string? */ int nc; /* No. of available columns remaining */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_channel); /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) this_channel; /* Use the "set" and "helpful" flags, along with the FitsChan's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Create a unique FITS keyword from the name supplied. */ CreateKeyword( this, name, keyword, status ); /* Store a pointer to the start of the next sub-string (i.e. the beggining of the string), and then loop round until the end of the string is reached. */ start = value; first = 1; while( *start && astOK ){ /* Store the number of characters available in the 80 column header card for the next substring, leaving room for the "= " string at the start, and the delimiting quotes. Also reserve 2 characters to allow for the possibility of double quotes being needed to protect trailing white space (see function PreQuote). */ nc = AST__FITSCHAN_FITSCARDLEN - FITSNAMLEN - 6; /* If this is the first sub-string reserve room for any comment. */ if( first ){ if( comment && comment[0] ) nc -= ChrLen( comment, status ) + 3; /* If the first card will be turned into a comment card, we need to leave room for the keyword name and equals sign, etc, within the 80 columns. */ if( !set ) nc -= FITSNAMLEN + 5; } /* We need to check the sub-string for single quotes since these will take up 2 characters each instead of 1 when encoded since single quotes within a string are doubled. Search through from the starting character, copying the sub-string into a buffer, and reducing the number of available characters remaining in the card for each character. */ c = buff1; while( *start && nc > 0 ){ cc = *(start++); *(c++) = cc; if( cc == '\'' ) { nc -= 2; } else { nc -= 1; } } /* If the last character in the substring was a single quote, there may not have been room for the extra quote which is added when the sub-string is encoded. In this case we need to back up a character in order to remove the single quote frin this substring and move it into the next sub-string. */ if( nc < 0 ){ start--; c--; } /* If the supplied value has not been exhausted, append an ampersand to the string. In this case we need to move the last character in the substring into the next substring to make room for the ampersand. */ if( *start ) { start--; c--; *(c++) = '&'; } /* Terminate the buffer. */ *c = 0; /* The FITS standard considers trailing white space is be insignificant, and so we need to guard against external applications throwing away significant trailing white space. This is done by encosing the string, including trailing white space, in double quotes. */ PreQuote( buff1, buff2, status ); /* On the first pass through this loop, write the value to the FitsChan as a keyword and value */ if( first ){ astSetFitsS( this, keyword, buff2, astGetComment( this ) ? comment : NULL, 0 ); /* If the value is not "set", replace the card just written by a COMMENT card containing the text of the card as the comment. */ if( !set ) MakeIntoComment( this, "astWrite", astGetClass( this ), status ); /* On subsequent passes through the loop, store the string using a CONTINUE keyword, with type AST__CONTINUE (this type is like AST__STRING but is formatted without an equals sign). */ } else { astSetFitsCN( this, "CONTINUE", buff2, NULL, 0 ); } first = 0; } /* Increment the count of items written. */ items_written++; } } static AstMapping *ZPXMapping( AstFitsChan *this, FitsStore *store, char s, int naxes, int zpxaxes[2], const char *method, const char *class, int *status ){ /* * Name: * ZPXMapping * Purpose: * Create a Mapping descriping "-ZPX" (IRAF) distortion. * Type: * Private function. * Synopsis: * AstMapping *ZPXMapping( AstFitsChan *this, FitsStore *store, char s, * int naxes, int zpxaxes[2], const char *method, * const char *class, int *status ) * Class Membership: * FitsChan * Description: * This function uses the values in the supplied FitsStore to create a * Mapping which implements the "-ZPX" distortion code, produced by * the IRAF project. See: * * http://iraf.noao.edu/projects/ccdmosaic/zpx.html * * Note, the Mapping created by this function implements the "lngcor" * and "latcor" corrections described in the WAT... keywords. The * basic ZPN projection code is handled in the normal way, as any * other projection is handled. * Parameters: * store * A structure containing information about the requested axis * descriptions derived from a FITS header. * s * A character identifying the co-ordinate version to use. A space * means use primary axis descriptions. Otherwise, it must be an * upper-case alphabetical characters ('A' to 'Z'). * naxes * The number of intermediate world coordinate axes (WCSAXES). * zpxaxes * The zero-based indices of the two IWC axes that use the ZPX projection. * method * A pointer to a string holding the name of the calling method. * This is used only in the construction of error messages. * class * A pointer to a string holding the class of the object being * read. This is used only in the construction of error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Mapping. */ /* Local Variables: */ AstMapping *ret; char *watstr; double *cvals[ 2 ]; int *mvals[ 2 ]; int ncoeff[ 2 ]; int i; int icoeff; int ok; /* Initialise the pointer to the returned Mapping. */ ret = NULL; /* Check the global status. */ if ( !astOK ) return ret; /* Check both axes */ for( i = 0; i < 2; i++ ){ mvals[ i ] = NULL; cvals[ i ] = NULL; ncoeff[ i ] = 0; /* Concatenate all the IRAF "WAT" keywords together for this axis. These keywords are marked as having been used, so that they are not written out when the FitsChan is deleted. */ watstr = ConcatWAT( this, zpxaxes[ i ], method, class, status ); /* Extract the polynomial coefficients from the concatenated WAT string. These are returned in the form of a list of PVi_m values for a TPN projection. */ ncoeff[ i ] = WATCoeffs( watstr, i, cvals + i, mvals + i, &ok, status ); /* If the current axis of the ZPX projection uses features not supported by AST, do not do any more axes. */ if( !ok ) break; /* Free the WAT string. */ watstr = astFree( watstr ); } /* If we can handle the ZPX projection, store the polynomial coefficients in a new inverted TPN WcsMap. This WcsMap is used as a correction to the ZPN WcsMap to be created later, therefore set its FITSProj value to zero so that it is not used as the FITS projection when written out via astWrite. Also set TPNTan to zero to indicate that the TAN part of the TPN projection should not be used (i.e. just use the polynomial part). */ if( ok && astOK ) { if( ncoeff[ 0 ] || ncoeff[ 1 ] ) { ret = (AstMapping *) astWcsMap( naxes, AST__TPN, zpxaxes[ 0 ] + 1, zpxaxes[ 1 ] + 1, "Invert=1", status ); astSetFITSProj( ret, 0 ); astSetTPNTan( ret, 0 ); for( i = 0; i < 2; i++ ){ for( icoeff = 0; icoeff < ncoeff[ i ]; icoeff++ ) { astSetPV( ret, zpxaxes[ i ], (mvals[ i ])[ icoeff ], (cvals[ i ])[ icoeff ] ); } } } else { ret = (AstMapping *) astUnitMap( naxes, " ", status ); } /* If the TNX cannot be represented in FITS-WCS (within our restrictions), add warning keywords to the FitsChan. */ } else { Warn( this, "zpx", "This FITS header includes, or was " "derived from, a ZPX projection which requires " "unsupported IRAF-specific corrections. The WCS " "information may therefore be incorrect.", method, class, status ); } /* Return the result. */ return ret; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Card. */ /* ===== */ /* *att++ * Name: * Card * Purpose: * Index of current FITS card in a FitsChan. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute gives the index of the "current" FITS header card * within a FitsChan, the first card having an index of 1. The c choice of current card affects the behaviour of functions that f choice of current card affects the behaviour of routines that c access the contents of the FitsChan, such as astDelFits, c astFindFits and astPutFits. f access the contents of the FitsChan, such as AST_DELFITS, f AST_FINDFITS and AST_PUTFITS. * * A value assigned to Card will position the FitsChan at any * desired point, so that a particular card within it can be * accessed. Alternatively, the value of Card may be enquired in * order to determine the current position of a FitsChan. * * The default value of Card is 1. This means that clearing c this attribute (using astClear) effectively "rewinds" the f this attribute (using AST_CLEAR) effectively "rewinds" the * FitsChan, so that the first card is accessed next. If Card is * set to a value which exceeds the total number of cards in the * FitsChan (as given by its Ncard attribute), it is regarded as * pointing at the "end-of-file". In this case, the value returned * in response to an enquiry is always one more than the number of * cards in the FitsChan. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Encoding. */ /* ========= */ /* *att++ * Name: * Encoding * Purpose: * System for encoding Objects as FITS headers. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the encoding system to use when AST * Objects are stored as FITS header cards in a FitsChan. It c affects the behaviour of the astWrite and astRead functions when f affects the behaviour of the AST_WRITE and AST_READ routines when * they are used to transfer any AST Object to or from an external * representation consisting of FITS header cards (i.e. whenever a * write or read operation is performed using a FitsChan as the I/O * Channel). * * There are several ways (conventions) by which coordinate system * information may be represented in the form of FITS headers and * the Encoding attribute is used to specify which of these should * be used. The encoding options available are outlined in the * "Encodings Available" section below, and in more detail in the * sections which follow. * * Encoding systems differ in the range of possible Objects * (e.g. classes) they can represent, in the restrictions they * place on these Objects (e.g. compatibility with some * externally-defined coordinate system model) and in the number of * Objects that can be stored together in any particular set of * FITS header cards (e.g. multiple Objects, or only a single * Object). The choice of encoding also affects the range of * external applications which can potentially read and interpret * the FITS header cards produced. * * The encoding options available are not necessarily mutually * exclusive, and it may sometimes be possible to store multiple * Objects (or the same Object several times) using different * encodings within the same set of FITS header cards. This * possibility increases the likelihood of other applications being * able to read and interpret the information. * * By default, a FitsChan will attempt to determine which encoding * system is already in use, and will set the default Encoding * value accordingly (so that subsequent I/O operations adopt the * same conventions). It does this by looking for certain critical * FITS keywords which only occur in particular encodings. For * details of how this works, see the "Choice of Default Encoding" * section below. If you wish to ensure that a particular encoding * system is used, independently of any FITS cards already present, * you should set an explicit Encoding value yourself. * Encodings Available: * The Encoding attribute can take any of the following (case * insensitive) string values to select the corresponding encoding * system: * * - "DSS": Encodes coordinate system information in FITS header * cards using the convention developed at the Space Telescope * Science Institute (STScI) for the Digitised Sky Survey (DSS) * astrometric plate calibrations. The main advantages of this * encoding are that FITS images which use it are widely available * and it is understood by a number of important and * well-established astronomy applications. For further details, * see the section "The DSS Encoding" below. * * - "FITS-WCS": Encodes coordinate system information in FITS * header cards using the conventions described in the FITS * world coordinate system (FITS-WCS) papers by E.W. Greisen, * M. Calabretta, et al. The main advantages of this encoding are that * it should be understood by any FITS-WCS compliant application and * is likely to be adopted widely for FITS data in future. For further * details, see the section "The FITS-WCS Encoding" below. * * - "FITS-PC": Encodes coordinate system information in FITS * header cards using the conventions described in an earlier draft * of the FITS world coordinate system papers by E.W. Greisen and * M. Calabretta. This encoding uses a combination of CDELTi and * PCiiijjj keywords to describe the scale and rotation of the pixel * axes. This encoding is included to support existing data and * software which uses these now superceded conventions. In general, * the "FITS-WCS" encoding (which uses CDi_j or PCi_j keywords to * describe the scale and rotation) should be used in preference to * "FITS-PC". * * - "FITS-IRAF": Encodes coordinate system information in FITS * header cards using the conventions described in the document * "World Coordinate Systems Representations Within the FITS * Format" by R.J. Hanisch and D.G. Wells, 1988. This encoding is * currently employed by the IRAF data analysis facility, so its * use will facilitate data exchange with IRAF. Its main advantages * are that it is a stable convention which approximates to a * subset of the propsed FITS-WCS encoding (above). This makes it * suitable as an interim method for storing coordinate system * information in FITS headers until the FITS-WCS encoding becomes * stable. Since many datasets currently use the FITS-IRAF * encoding, conversion of data from FITS-IRAF to the final form of * FITS-WCS is likely to be well supported. * * - "FITS-AIPS": Encodes coordinate system information in FITS * header cards using the conventions originally introduced by the * AIPS data analysis facility. This is base on the use of CDELTi and * CROTAi keuwords to desribe the scale and rotation of each axis. * These conventions have been superceded but are still widely used. * * - "FITS-AIPS++": Encodes coordinate system information in FITS * header cards using the conventions used by the AIPS++ project. * This is an extension of FITS-AIPS which includes some of the * features of FITS-IRAF and FITS-PC. * * - "FITS-CLASS": Encodes coordinate system information in FITS * header cards using the conventions used by the CLASS project. * CLASS is a software package for reducing single-dish radio and * sub-mm spectroscopic data. See the section "CLASS FITS format" at * http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/. * * - "NATIVE": Encodes AST Objects in FITS header cards using a * convention which is private to the AST library (but adheres to * the general FITS standard) and which uses FITS keywords that * will not clash with other encoding systems. The main advantages * of this are that any class of AST Object may be encoded, and any * (reasonable) number of Objects may be stored sequentially in the * same FITS header. This makes FITS headers an almost loss-less * communication path for passing AST Objects between applications * (although all such applications must, of course, make use of the * AST library to interpret the information). For further details, * see the section "The NATIVE Encoding" below. * Choice of Default Encoding: * If the Encoding attribute of a FitsChan is not set, the default * value it takes is determined by the presence of certain critical * FITS keywords within the FitsChan. The sequence of decisions * used to arrive at the default value is as follows: * * - If the FitsChan contains any keywords beginning with the * string "BEGAST", then NATIVE encoding is used, * - Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV * keyword and a keyword of the form VELO-xxx, where xxx indicates one * of the rest frames used by class (e.g. "VELO-LSR"), or "VLSR". * - Otherwise, if the FitsChan contains a CTYPE keyword which * represents a spectral axis using the conventions of the AIPS and * AIPS++ projects (e.g. "FELO-LSR", etc), then one of FITS-AIPS or * FITS-AIPS++ encoding is used. FITS-AIPS++ is used if any of the * keywords CDi_j, PROJP, LONPOLE or LATPOLE are * found in the FitsChan. Otherwise FITS-AIPS is used. * - Otherwise, if the FitsChan contains a keyword of the form * "PCiiijjj", where "i" and "j" are single digits, then * FITS-PC encoding is used, * - Otherwise, if the FitsChan contains a keyword of the form * "CDiiijjj", where "i" and "j" are single digits, then * FITS-IRAF encoding is used, * - Otherwise, if the FitsChan contains a keyword of the form * "CDi_j", and at least one of RADECSYS, PROJPi, or CjVALi * where "i" and "j" are single digits, then FITS-IRAF encoding is * used. * - Otherwise, if the FitsChan contains any keywords of the form * PROJPi, CjVALi or RADECSYS, where "i" and "j" are single digits, * then FITS-PC encoding is used. * - Otherwise, if the FitsChan contains a keyword of the form * CROTAi, where "i" is a single digit, then FITS-AIPS encoding is * used. * - Otherwise, if the FitsChan contains a keyword of the form * CRVALi, where "i" is a single digit, then FITS-WCS encoding is * used. * - Otherwise, if the FitsChan contains the "PLTRAH" keyword, then * DSS encoding is used, * - Otherwise, if none of these conditions is met (as would be the * case when using an empty FitsChan), then NATIVE encoding is * used. * * Except for the NATIVE and DSS encodings, all the above checks * also require that the header contains at least one CTYPE, CRPIX and * CRVAL keyword (otherwise the checking process continues to the next * case). * * Setting an explicit value for the Encoding attribute always * over-rides this default behaviour. * * Note that when writing information to a FitsChan, the choice of * encoding will depend greatly on the type of application you * expect to be reading the information in future. If you do not * know this, there may sometimes be an advantage in writing the * information several times, using a different encoding on each * occasion. * The DSS Encoding: * The DSS encoding uses FITS header cards to store a multi-term * polynomial which relates pixel positions on a digitised * photographic plate to celestial coordinates (right ascension and * declination). This encoding may only be used to store a single * AST Object in any set of FITS header cards, and that Object must * be a FrameSet which conforms to the STScI/DSS coordinate system * model (this means the Mapping which relates its base and current * Frames must include either a DssMap or a WcsMap with type * AST__TAN or AST__TPN). * c When reading a DSS encoded Object (using astRead), the FitsChan f When reading a DSS encoded Object (using AST_READ), the FitsChan * concerned must initially be positioned at the first card (its * Card attribute must equal 1) and the result of the read, if * successful, will always be a pointer to a FrameSet. The base * Frame of this FrameSet represents DSS pixel coordinates, and the * current Frame represents DSS celestial coordinates. Such a read * is always destructive and causes the FITS header cards required * for the construction of the FrameSet to be removed from the * FitsChan, which is then left positioned at the "end-of-file". A * subsequent read using the same encoding will therefore not * return another FrameSet, even if the FitsChan is rewound. * c When astWrite is used to store a FrameSet using DSS encoding, f When AST_WRITE is used to store a FrameSet using DSS encoding, * an attempt is first made to simplify the FrameSet to see if it * conforms to the DSS model. Specifically, the current Frame must * be a FK5 SkyFrame; the projection must be a tangent plane * (gnomonic) projection with polynomial corrections conforming to * DSS requirements, and north must be parallel to the second base * Frame axis. * * If the simplification process succeeds, a description of the * FrameSet is written to the FitsChan using appropriate DSS FITS * header cards. The base Frame of the FrameSet is used to form the * DSS pixel coordinate system and the current Frame gives the DSS * celestial coordinate system. A successful write operation will * over-write any existing DSS encoded data in the FitsChan, but * will not affect other (non-DSS) header cards. If a destructive * read of a DSS encoded Object has previously occurred, then an * attempt will be made to store the FITS header cards back in * their original locations. * * If an attempt to simplify a FrameSet to conform to the DSS model * fails (or if the Object supplied is not a FrameSet), then no c data will be written to the FitsChan and astWrite will return f data will be written to the FitsChan and AST_WRITE will return * zero. No error will result. * The FITS-WCS Encoding: * The FITS-WCS convention uses FITS header cards to describe the * relationship between pixels in an image (not necessarily * 2-dimensional) and one or more related "world coordinate systems". * The FITS-WCS encoding may only be used to store a single AST Object * in any set of FITS header cards, and that Object must be a FrameSet * which conforms to the FITS-WCS model (the FrameSet may, however, * contain multiple Frames which will be result in multiple FITS * "alternate axis descriptions"). Details of the use made by this * Encoding of the conventions described in the FITS-WCS papers are * given in the appendix "FITS-WCS Coverage" of this document. A few * main points are described below. * * The rotation and scaling of the intermediate world coordinate system * can be specified using either "CDi_j" keywords, or "PCi_j" together * with "CDELTi" keywords. When writing a FrameSet to a FitsChan, the * the value of the CDMatrix attribute of the FitsChan determines * which system is used. * * In addition, this encoding supports the "TAN with polynomial correction * terms" projection which was included in a draft of the FITS-WCS paper, * but was not present in the final version. A "TAN with polynomial * correction terms" projection is represented using a WcsMap with type * AST__TPN (rather than AST__TAN which is used to represent simple * TAN projections). When reading a FITS header, a CTYPE keyword value * including a "-TAN" code results in an AST__TPN projection if there are * any projection parameters (given by the PVi_m keywords) associated with * the latitude axis, or if there are projection parameters associated * with the longitude axis for m greater than 4. When writing a * FrameSet to a FITS header, an AST__TPN projection gives rise to a * CTYPE value including the normal "-TAN" code, but the projection * parameters are stored in keywords with names "QVi_m", instead of the * usual "PVi_m". Since these QV parameters are not part of the * FITS-WCS standard they will be ignored by other non-AST software, * resulting in the WCS being interpreted as a simple TAN projection * without any corrections. This should be seen as an interim solution * until such time as an agreed method for describing projection * distortions within FITS-WCS has been published. * * AST extends the range of celestial coordinate systems which may be * described using this encoding by allowing the inclusion of * "AZ--" and "EL--" as the coordinate specification within CTYPE * values. These form a longitude/latitude pair of axes which describe * azimuth and elevation. The geographic position of the observer * should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS * paper III. Currently, a simple model is used which includes diurnal * aberration, but ignores atmospheric refraction, polar motion, etc. * These may be added in a later release. * * If an AST SkyFrame that represents offset rather than absolute * coordinates (see attribute SkyRefIs) is written to a FitsChan using * FITS-WCS encoding, two alternate axis descriptions will be created. * One will describe the offset coordinates, and will use "OFLN" and * "OFLT" as the axis codes in the CTYPE keywords. The other will * describe absolute coordinates as specified by the System attribute * of the SkyFrame, using the usual CTYPE codes ("RA--"/"DEC-", etc). * In addition, the absolute coordinates description will contain * AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the * header to be read back into AST in order to reconstruct the original * SkyFrame. * c When reading a FITS-WCS encoded Object (using astRead), the FitsChan f When reading a FITS-WCS encoded Object (using AST_READ), the FitsChan * concerned must initially be positioned at the first card (its * Card attribute must equal 1) and the result of the read, if * successful, will always be a pointer to a FrameSet. The base * Frame of this FrameSet represents FITS-WCS pixel coordinates, * and the current Frame represents the physical coordinate system * described by the FITS-WCS primary axis descriptions. If * secondary axis descriptions are also present, then the FrameSet * may contain additional (non-current) Frames which represent * these. Such a read is always destructive and causes the FITS * header cards required for the construction of the FrameSet to be * removed from the FitsChan, which is then left positioned at the * "end-of-file". A subsequent read using the same encoding will * therefore not return another FrameSet, even if the FitsChan is * rewound. * c When astWrite is used to store a FrameSet using FITS-WCS f When AST_WRITE is used to store a FrameSet using FITS-WCS * encoding, an attempt is first made to simplify the FrameSet to * see if it conforms to the FITS-WCS model. If this simplification * process succeeds (as it often should, as the model is reasonably * flexible), a description of the FrameSet is written to the * FitsChan using appropriate FITS header cards. The base Frame of * the FrameSet is used to form the FITS-WCS pixel coordinate * system and the current Frame gives the physical coordinate * system to be described by the FITS-WCS primary axis * descriptions. Any additional Frames in the FrameSet may be used * to construct secondary axis descriptions, where appropriate. * * A successful write operation will over-write any existing * FITS-WCS encoded data in the FitsChan, but will not affect other * (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS * encoded Object has previously occurred, then an attempt will be * made to store the FITS header cards back in their original * locations. Otherwise, the new cards will be inserted following * any other FITS-WCS related header cards present or, failing * that, in front of the current card (as given by the Card * attribute). * * If an attempt to simplify a FrameSet to conform to the FITS-WCS * model fails (or if the Object supplied is not a FrameSet), then c no data will be written to the FitsChan and astWrite will f no data will be written to the FitsChan and AST_WRITE will * return zero. No error will result. * The FITS-IRAF Encoding: * The FITS-IRAF encoding can, for most purposes, be considered as * a subset of the FITS-WCS encoding (above), although it differs * in the details of the FITS keywords used. It is used in exactly * the same way and has the same restrictions, but with the * addition of the following: * * - The only celestial coordinate systems that may be represented * are equatorial, galactic and ecliptic, * - Sky projections can be represented only if any associated * projection parameters are set to their default values. * - Secondary axis descriptions are not supported, so when writing * a FrameSet to a FitsChan, only information from the base and * current Frames will be stored. * * Note that this encoding is provided mainly as an interim measure to * provide a more stable alternative to the FITS-WCS encoding until the * FITS standard for encoding WCS information is finalised. The name * "FITS-IRAF" indicates the general keyword conventions used and does * not imply that this encoding will necessarily support all features of * the WCS scheme used by IRAF software. Nevertheless, an attempt has * been made to support a few such features where they are known to be * used by important sources of data. * * When writing a FrameSet using the FITS-IRAF encoding, axis rotations * are specified by a matrix of FITS keywords of the form "CDi_j", where * "i" and "j" are single digits. The alternative form "CDiiijjj", which * is also in use, is recognised when reading an Object, but is never * written. * * In addition, the experimental IRAF "ZPX" and "TNX" sky projections will * be accepted when reading, but will never be written (the corresponding * FITS "ZPN" or "distorted TAN" projection being used instead). However, * there are restrictions on the use of these experimental projections. * For "ZPX", longitude and latitude correction surfaces (appearing as * "lngcor" or "latcor" terms in the IRAF-specific "WAT" keywords) are * not supported. For "TNX" projections, only cubic surfaces encoded as * simple polynomials with "half cross-terms" are supported. If an * un-usable "TNX" or "ZPX" projection is encountered while reading * from a FitsChan, a simpler form of TAN or ZPN projection is used * which ignores the unsupported features and may therefore be * inaccurate. If this happens, a warning message is added to the * contents of the FitsChan as a set of cards using the keyword "ASTWARN". * * You should not normally attempt to mix the foreign FITS encodings within * the same FitsChan, since there is a risk that keyword clashes may occur. * The FITS-PC Encoding: * The FITS-PC encoding can, for most purposes, be considered as * equivalent to the FITS-WCS encoding (above), although it differs * in the details of the FITS keywords used. It is used in exactly * the same way and has the same restrictions. * The FITS-AIPS Encoding: * The FITS-AIPS encoding can, for most purposes, be considered as * equivalent to the FITS-WCS encoding (above), although it differs * in the details of the FITS keywords used. It is used in exactly * the same way and has the same restrictions, but with the * addition of the following: * * - The only celestial coordinate systems that may be represented * are equatorial, galactic and ecliptic, * - Spectral axes can only be represented if they represent * frequency, radio velocity or optical velocity, and are linearly * sampled in frequency. In addition, the standard of rest * must be LSRK, LSRD, barycentric or geocentric. * - Sky projections can be represented only if any associated * projection parameters are set to their default values. * - The AIT, SFL and MER projections can only be written if the CRVAL * keywords are zero for both longitude and latitude axes. * - Secondary axis descriptions are not supported, so when writing * a FrameSet to a FitsChan, only information from the base and * current Frames will be stored. * - If there are more than 2 axes in the base and current Frames, any * rotation must be restricted to the celestial plane, and must involve * no shear. * The FITS-AIPS++ Encoding: * The FITS-AIPS++ encoding is based on the FITS-AIPS encoding, but * includes some features of the FITS-IRAF and FITS-PC encodings. * Specifically, any celestial projections supported by FITS-PC may be * used, including those which require parameterisation, and the axis * rotation and scaling may be specified using CDi_j keywords. When * writing a FITS header, rotation will be specified using CROTA/CDELT * keywords if possible, otherwise CDi_j keywords will be used instead. * The FITS-CLASS Encoding: * The FITS-CLASS encoding uses the conventions of the CLASS project. * These are described in the section "Developer Manual"/"CLASS FITS * Format" contained in the CLASS documentation at: * * http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html. * * This encoding is similar to FITS-AIPS with the following restrictions: * * - When a SpecFrame is created by reading a FITS-CLASS header, the * attributes describing the observer's position (ObsLat, ObsLon and * ObsAlt) are left unset because the CLASS encoding does not specify * these values. Conversions to or from the topocentric standard of rest * will therefore be inaccurate (typically by up to about 0.5 km/s) * unless suitable values are assigned to these attributes after the * FrameSet has been created. * - When writing a FrameSet to a FITS-CLASS header, the current Frame * in the FrameSet must have at least 3 WCS axes, of which one must be * a linear spectral axis. The spectral axis in the created header will * always describe frequency. If the spectral axis in the supplied * FrameSet refers to some other system (e.g. radio velocity, etc), * then it will be converted to frequency. * - There must be a pair of celestial axes - either (RA,Dec) or * (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000. * - A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) * can be used. For AIT and SFL, the reference point must be at the * origin of longitude and latitude. For SIN, the associated projection * parameters must both be zero. * - No rotation of the celestial axes is allowed, unless the spatial * axes are degenerate (i.e. cover only a single pixel). * - The frequency axis in the created header will always describe * frequency in the source rest frame. If the supplied FrameSet uses * some other standard of rest then suitable conversion will be applied. * - The source velocity must be defined. In other words, the SpecFrame * attributes SourceVel and SourceVRF must have been assigned values. * - The frequency axis in a FITS-CLASS header does not represent * absolute frequency, but instead represents offsets from the rest * frequency in the standard of rest of the source. * * When writing a FrameSet out using FITS-CLASS encoding, the current * Frame may be temporarily modified if this will allow the header * to be produced. If this is done, the associated pixel->WCS Mapping * will also be modified to take account of the changes to the Frame. * The modifications performed include re-ordering axes (WCS axes, not * pixel axes), changing spectral coordinate system and standard of * rest, changing the celestial coordinate system and reference equinox, * and changing axis units. * The NATIVE Encoding: * The NATIVE encoding may be used to store a description of any * class of AST Object in the form of FITS header cards, and (for * most practical purposes) any number of these Object descriptions * may be stored within a single set of FITS cards. If multiple * Object descriptions are stored, they are written and read * sequentially. The NATIVE encoding makes use of unique FITS * keywords which are designed not to clash with keywords that have * already been used for other purposes (if a potential clash is * detected, an alternative keyword is constructed to avoid the * clash). * * When reading a NATIVE encoded object from a FitsChan (using c astRead), FITS header cards are read, starting at the current f AST_READ), FITS header cards are read, starting at the current * card (as determined by the Card attribute), until the start of * the next Object description is found. This description is then * read and converted into an AST Object, for which a pointer is * returned. Such a read is always destructive and causes all the * FITS header cards involved in the Object description to be * removed from the FitsChan, which is left positioned at the * following card. * * The Object returned may be of any class, depending on the * description that was read, and other AST routines may be used to * validate it (for example, by examining its Class or ID attribute c using astGetC). If further NATIVE encoded Object descriptions f using AST_GETC). If further NATIVE encoded Object descriptions c exist in the FitsChan, subsequent calls to astRead will return f exist in the FitsChan, subsequent calls to AST_READ will return * the Objects they describe in sequence (and destroy their * descriptions) until no more remain between the current card and * the "end-of-file". * c When astWrite is used to write an Object using NATIVE encoding, f When AST_WRITE is used to write an Object using NATIVE encoding, * a description of the Object is inserted immediately before the * current card (as determined by the Card attribute). Multiple * Object descriptions may be written in this way and are stored * separately (and sequentially if the Card attribute is not * modified between the writes). A write operation using the NATIVE * encoding does not over-write previously written Object * descriptions. Note, however, that subsequent behaviour is * undefined if an Object description is written inside a * previously-written description, so this should be avoided. * * When an Object is written to a FitsChan using NATIVE encoding, c astWrite should (barring errors) always transfer data and f AST_WRITE should (barring errors) always transfer data and * return a value of 1. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,Encoding,encoding,UNKNOWN_ENCODING) astMAKE_SET(FitsChan,Encoding,int,encoding,( value == NATIVE_ENCODING || value == FITSPC_ENCODING || value == FITSWCS_ENCODING || value == FITSIRAF_ENCODING || value == FITSAIPS_ENCODING || value == FITSAIPSPP_ENCODING || value == FITSCLASS_ENCODING || value == DSS_ENCODING ? value : (astError( AST__BADAT, "astSetEncoding: Unknown encoding system %d " "supplied.", status, value ), UNKNOWN_ENCODING ))) astMAKE_TEST(FitsChan,Encoding,( this->encoding != UNKNOWN_ENCODING )) /* DefB1950 */ /* ======== */ /* *att++ * Name: * DefB1950 * Purpose: * Use FK4 B1950 as defaults? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which specifies a default equinox * and reference frame to use when reading a FrameSet from a FitsChan * with a foreign (i.e. non-native) encoding. It is only used if the FITS * header contains RA and DEC axes but contains no information about the * reference frame or equinox. If this is the case, then values of FK4 and * B1950 are assumed if the DefB1950 attribute has a non-zero value and * ICRS is assumed if DefB1950 is zero. The default value for DefB1950 * depends on the value of the Encoding attribute: for FITS-WCS encoding * the default is zero, and for all other encodings it is one. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,DefB1950,defb1950,-1) astMAKE_GET(FitsChan,DefB1950,int,1,(this->defb1950 == -1 ? (astGetEncoding(this)== FITSWCS_ENCODING?0:1): this->defb1950)) astMAKE_SET(FitsChan,DefB1950,int,defb1950,( value ? 1 : 0 )) astMAKE_TEST(FitsChan,DefB1950,( this->defb1950 != -1 )) /* TabOK */ /* ===== */ /* *att++ * Name: * TabOK * Purpose: * Should the FITS-WCS -TAB algorithm be recognised? * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute is an integer value which indicates if the "-TAB" * algorithm, defined in FITS-WCS paper III, should be supported by * the FitsChan. The default value is zero. A zero or negative value * results in no support for -TAB axes (i.e. axes that have "-TAB" * in their CTYPE keyword value). In this case, the c astWrite f AST_WRITE * method will return zero if the write operation would required the * use of the -TAB algorithm, and the c astRead f AST_READ * method will return c a NULL pointer f AST__NULL * if any axis in the supplied header uses the -TAB algorithm. * If TabOK is set to a non-zero positive integer, these methods will * recognise and convert axes described by the -TAB algorithm, as * follows: * c The astWrite f The AST_WRITE * method will generate headers that use the -TAB algorithm (if * possible) if no other known FITS-WCS algorithm can be used to * describe the supplied FrameSet. This will result in a table of * coordinate values and index vectors being stored in the FitsChan. * After the write operation, the calling application should check to * see if such a table has been stored in the FitsChan. If so, the * table should be retrived from the FitsChan using the c astGetTables f AST_GETTABLES * method, and the data (and headers) within it copied into a new * FITS binary table extension. See c astGetTables f AST_GETTABLES * for more information. The FitsChan uses a FitsTable object to store * the table data and headers. This FitsTable will contain the required * columns and headers as described by FITS-WCS paper III - the * coordinates array will be in a column named "COORDS", and the index * vector(s) will be in columns named "INDEX" (where is the index * of the corresponding FITS WCS axis). Note, index vectors are only * created if required. The EXTNAME value will be set to the value of the * AST__TABEXTNAME constant (currently "WCS-TAB"). The EXTVER header * will be set to the positive integer value assigned to the TabOK * attribute. No value will be stored for the EXTLEVEL header, and should * therefore be considered to default to 1. * c The astRead f The AST_READ * method will generate a FrameSet from headers that use the -TAB * algorithm so long as the necessary FITS binary tables are made * available. There are two ways to do this: firstly, if the application * knows which FITS binary tables will be needed, then it can create a * Fitstable describing each such table and store it in the FitsChan * (using method c astPutTables or astPutTable) before invoking the astRead method. f AST_PUTTABLES or AST_PUTTABLE) before invoking the AST_READ method. * Secondly, if the application does not know which FITS binary tables * will be needed by c astRead, f AST_READ, * then it can register a call-back function with the FitsChan using * method c astTableSource. f AST_TABLESOURCE. * This call-back function will be called from within c astRead f AST_READ * if and when a -TAB header is encountered. When called, its arguments * will give the name, version and level of the FITS extension containing * a required table. The call-back function should read this table from * an external FITS file, and create a corresponding FitsTable which * it should then return to c astRead. Note, currently astRead f AST_READ. Note, currently AST_READ * can only handle -TAB headers that describe 1-dimensional (i.e. * separable) axes. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,TabOK,tabok,-INT_MAX) astMAKE_GET(FitsChan,TabOK,int,0,(this->tabok == -INT_MAX ? 0 : this->tabok)) astMAKE_SET(FitsChan,TabOK,int,tabok,value) astMAKE_TEST(FitsChan,TabOK,( this->tabok != -INT_MAX )) /* CarLin */ /* ====== */ /* *att++ * Name: * CarLin * Purpose: * Ignore spherical rotations on CAR projections? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which specifies how FITS "CAR" * (plate carree, or "Cartesian") projections should be treated when * reading a FrameSet from a foreign encoded FITS header. If zero (the * default), it is assumed that the CAR projection conforms to the * conventions described in the FITS world coordinate system (FITS-WCS) * paper II "Representation of Celestial Coordinates in FITS" by * M. Calabretta & E.W. Greisen. If CarLin is non-zero, then these * conventions are ignored, and it is assumed that the mapping from pixel * coordinates to celestial coordinates is a simple linear transformation * (hence the attribute name "CarLin"). This is appropriate for some older * FITS data which claims to have a "CAR" projection, but which in fact do * not conform to the conventions of the FITS-WCS paper. * * The FITS-WCS paper specifies that headers which include a CAR projection * represent a linear mapping from pixel coordinates to "native spherical * coordinates", NOT celestial coordinates. An extra mapping is then * required from native spherical to celestial. This mapping is a 3D * rotation and so the overall Mapping from pixel to celestial coordinates * is NOT linear. See the FITS-WCS papers for further details. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,CarLin,carlin,-1) astMAKE_GET(FitsChan,CarLin,int,1,(this->carlin == -1 ? 0 : this->carlin)) astMAKE_SET(FitsChan,CarLin,int,carlin,( value ? 1 : 0 )) astMAKE_TEST(FitsChan,CarLin,( this->carlin != -1 )) /* PolyTan */ /* ======= */ /* *att++ * Name: * PolyTan * Purpose: * Use PVi_m keywords to define distorted TAN projection? * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute is a boolean value which specifies how FITS "TAN" * projections should be treated when reading a FrameSet from a foreign * encoded FITS header. If zero, the projection is assumed to conform * to the published FITS-WCS standard. If positive, the convention * for a distorted TAN projection included in an early draft version * of FITS-WCS paper II are assumed. In this convention the * coefficients of a polynomial distortion to be applied to * intermediate world coordinates are specified by the PVi_m keywords. * This convention was removed from the paper before publication and so * does not form part of the standard. Indeed, it is incompatible with * the published standard because it re-defines the meaning of the * first five PVi_m keywords on the longitude axis, which are reserved * by the published standard for other purposes. However, headers that * use this convention are still to be found, for instance the SCAMP * utility (http://www.astromatic.net/software/scamp) creates them. * * The default value for the PolyTan attribute is -1. A negative * values causes the used convention to depend on the contents * of the FitsChan. If the FitsChan contains any PVi_m keywords for * the latitude axis, or if it contains PVi_m keywords for the * longitude axis with "m" greater than 4, then the distorted TAN * convention is used. Otherwise, the standard convention is used. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,PolyTan,polytan,-INT_MAX) astMAKE_SET(FitsChan,PolyTan,int,polytan,value) astMAKE_TEST(FitsChan,PolyTan,( this->polytan != -INT_MAX )) astMAKE_GET(FitsChan,PolyTan,int,-1,(this->polytan == -INT_MAX ? -1 : this->polytan)) /* Iwc */ /* === */ /* *att++ * Name: * Iwc * Purpose: * Include a Frame representing FITS-WCS intermediate world coordinates? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which is used when a FrameSet is * read from a FitsChan with a foreign FITS encoding (e.g. FITS-WCS) using c astRead. f AST_READ. * If it has a non-zero value then the returned FrameSet will include * Frames representing "intermediate world coordinates" (IWC). These * Frames will have Domain name "IWC" for primary axis descriptions, and * "IWCa" for secondary axis descriptions, where "a" is replaced by * the single alternate axis description character, as used in the * FITS-WCS header. The default value for "Iwc" is zero. * * FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one * axis for each WCS axis, and is the coordinate system produced by the * rotation matrix (represented by FITS keyword PCi_j, CDi_j, etc). * For instance, for a 2-D FITS-WCS header describing projected * celestial longitude and latitude, the intermediate world * coordinates represent offsets in degrees from the reference point * within the plane of projection. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,Iwc,iwc,-1) astMAKE_GET(FitsChan,Iwc,int,1,(this->iwc == -1 ? 0 : this->iwc)) astMAKE_SET(FitsChan,Iwc,int,iwc,( value ? 1 : 0 )) astMAKE_TEST(FitsChan,Iwc,( this->iwc != -1 )) /* *att++ * Name: * CDMatrix * Purpose: * Use CDi_j keywords to represent pixel scaling, rotation, etc? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which specifies how the linear * transformation from pixel coordinates to intermediate world * coordinates should be represented within a FitsChan when using * FITS-WCS encoding. This transformation describes the scaling, * rotation, shear, etc., of the pixel axes. * * If the attribute has a non-zero value then the transformation is * represented by a set of CDi_j keywords representing a square matrix * (where "i" is the index of an intermediate world coordinate axis * and "j" is the index of a pixel axis). If the attribute has a zero * value the transformation is represented by a set of PCi_j keywords * (which also represent a square matrix) together with a corresponding * set of CDELTi keywords representing the axis scalings. See FITS-WCS * paper II "Representation of Celestial Coordinates in FITS" by * M. Calabretta & E.W. Greisen, for a complete description of these two * schemes. * * The default value of the CDMatrix attribute is determined by the * contents of the FitsChan at the time the attribute is accessed. If * the FitsChan contains any CDi_j keywords then the default value is * non-zero. Otherwise it is zero. Note, reading a FrameSet from a * FitsChan will in general consume any CDi_j keywords present in the * FitsChan. Thus the default value for CDMatrix following a read will * usually be zero, even if the FitsChan originally contained some * CDi_j keywords. This behaviour is similar to that of the Encoding * attribute, the default value for which is determined by the contents * of the FitsChan at the time the attribute is accessed. If you wish * to retain the original value of the CDMatrix attribute (that is, * the value before reading the FrameSet) then you should enquire the * default value before doing the read, and then set that value * explicitly. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,CDMatrix,cdmatrix,-1) astMAKE_SET(FitsChan,CDMatrix,int,cdmatrix,( value ? 1 : 0 )) astMAKE_TEST(FitsChan,CDMatrix,( this->cdmatrix != -1 )) /* Clean */ /* ===== */ /* *att++ * Name: * Clean * Purpose: * Remove cards used whilst reading even if an error occurs? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute indicates whether or not cards should be removed from * the FitsChan if an error occurs within c astRead. f AST_READ. * A succesful read on a FitsChan always results in the removal of * the cards which were involved in the description of the returned * Object. However, in the event of an error during the read (for instance * if the cards in the FitsChan have illegal values, or if some required * cards are missing) no cards will be removed from the FitsChan if * the Clean attribute is zero (the default). If Clean is non-zero then * any cards which were used in the aborted attempt to read an object * will be removed. * * This provides a means of "cleaning" a FitsChan of WCS related cards * which works even in the event of the cards not forming a legal WCS * description. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,Clean,clean,-1) astMAKE_SET(FitsChan,Clean,int,clean,( value ? 1 : 0 )) astMAKE_TEST(FitsChan,Clean,( this->clean != -1 )) /* *att++ * Name: * FitsAxisOrder * Purpose: * Frame title. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the order for the WCS axes in any new * FITS-WCS headers created using the c astWrite f AST_WRITE * method. * * The value of the FitsAxisOrder attribute can be either "" * (the default value), "" or a space-separated list of axis * symbols: * * "": causes the WCS axis order to be chosen automatically so that * the i'th WCS axis in the new FITS header is the WCS axis which is * more nearly parallel to the i'th pixel axis. * * "": causes the WCS axis order to be set so that the i'th WCS * axis in the new FITS header is the i'th WCS axis in the current * Frame of the FrameSet being written out to the header. * * "Sym1 Sym2...": the space-separated list is seached in turn for * the Symbol attribute of each axis in the current Frame of the * FrameSet. The order in which these Symbols occur within the * space-separated list defines the order of the WCS axes in the * new FITS header. An error is reported if Symbol for a current * Frame axis is not present in the supplied list. However, no error * is reported if the list contains extra words that do not correspond * to the Symbol of any current Frame axis. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,FitsAxisOrder,fitsaxisorder,astFree( this->fitsaxisorder )) astMAKE_GET(FitsChan,FitsAxisOrder,const char *,NULL,(this->fitsaxisorder ? this->fitsaxisorder : "" )) astMAKE_SET(FitsChan,FitsAxisOrder,const char *,fitsaxisorder,astStore( this->fitsaxisorder, value, strlen( value ) + (size_t) 1 )) astMAKE_TEST(FitsChan,FitsAxisOrder,( this->fitsaxisorder != NULL )) /* FitsDigits. */ /* =========== */ /* *att++ * Name: * FitsDigits * Purpose: * Digits of precision for floating point FITS values. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute gives the number of significant decimal digits to * use when formatting floating point values for inclusion in the * FITS header cards within a FitsChan. * * By default, a positive value is used which results in no loss of c information, assuming that the value's precision is double. f information, assuming that the value is double precision. * Usually, this causes no problems. * * However, to adhere strictly to the recommendations of the FITS * standard, the width of the formatted value (including sign, * decimal point and exponent) ought not to be more than 20 * characters. If you are concerned about this, you should set * FitsDigits to a negative value, such as -15. In this case, the * absolute value (+15) indicates the maximum number of significant * digits to use, but the actual number used may be fewer than this * to ensure that the FITS recommendations are satisfied. When * using this approach, the resulting number of significant digits * may depend on the value being formatted and on the presence of * any sign, decimal point or exponent. * * The value of this attribute is effective when FITS header cards * are output, either using c astFindFits or by the action of the FitsChan's sink function f AST_FINDFITS or by the action of the FitsChan's sink routine * when it is finally deleted. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ astMAKE_CLEAR(FitsChan,FitsDigits,fitsdigits,DBL_DIG) astMAKE_GET(FitsChan,FitsDigits,int,DBL_DIG,this->fitsdigits) astMAKE_SET(FitsChan,FitsDigits,int,fitsdigits,value) astMAKE_TEST(FitsChan,FitsDigits,( this->fitsdigits != DBL_DIG )) /* CardComm */ /* ======== */ /* *att++ * Name: * CardComm * Purpose: * The comment for the current card in a FitsChan. * Type: * Public attribute. * Synopsis: * String, read-only. * Description: * This attribute gives the comment for the current card of the * FitsChan. A zero-length string is returned if the card has no comment. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* CardName */ /* ======== */ /* *att++ * Name: * CardName * Purpose: * The keyword name of the current card in a FitsChan. * Type: * Public attribute. * Synopsis: * String, read-only. * Description: * This attribute gives the name of the keyword for the * current card of the FitsChan. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* CardType */ /* ======== */ /* *att++ * Name: * CardType * Purpose: * The data type of the current card in a FitsChan. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute gives the data type of the keyword value for the * current card of the FitsChan. It will be one of the following * integer constants: AST__NOTYPE, AST__COMMENT, AST__INT, AST__FLOAT, * AST__STRING, AST__COMPLEXF, AST__COMPLEXI, AST__LOGICAL, * AST__CONTINUE, AST__UNDEF. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Ncard */ /* ===== */ /* *att++ * Name: * Ncard * Purpose: * Number of FITS header cards in a FitsChan. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute gives the total number of FITS header cards * stored in a FitsChan. It is updated as cards are added or * deleted. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Nkey */ /* ==== */ /* *att++ * Name: * Nkey * Purpose: * Number of unique FITS keywords in a FitsChan. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute gives the total number of unique FITS keywords * stored in a FitsChan. It is updated as cards are added or * deleted. If no keyword occurrs more than once in the FitsChan, the * Ncard and Nkey attributes will be equal. If any keyword occurrs * more than once, the Nkey attribute value will be smaller than * the Ncard attribute value. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Warnings. */ /* ======== */ /* *att++ * Name: * Warnings * Purpose: * Controls the issuing of warnings about various conditions. * Type: * Public attribute. * Synopsis: * String * Description: * This attribute controls the issuing of warnings about selected * conditions when an Object or keyword is read from or written to a * FitsChan. The value supplied for the Warnings attribute should * consist of a space separated list of condition names (see the * AllWarnings attribute for a list of the currently defined names). * Each name indicates a condition which should be reported. The default * value for Warnings is the string "BadKeyName BadKeyValue Tnx Zpx * BadCel BadMat BadPV BadCTYPE". * * The text of any warning will be stored within the FitsChan in the * form of one or more new header cards with keyword ASTWARN. If * required, applications can check the FitsChan for ASTWARN cards c (using astFindFits) after the call to astRead or astWrite has been f (using AST_FINDFITS) after the call to AST_READ or AST_WRITE has been * performed, and report the text of any such cards to the user. ASTWARN * cards will be propagated to any output header unless they are c deleted from the FitsChan using astDelFits. f deleted from the FitsChan using astDelFits. * Notes: * This attribute only controls the warnings that are to be stored as * a set of header cards in the FitsChan as described above. It has no * effect on the storage of warnings in the parent Channel structure. * All warnings are stored in the parent Channel structure, from where * they can be retrieved using the c astWarnings f AST_WARNINGS * function. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Clear the Warnings value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(FitsChan,Warnings,warnings,astFree( this->warnings )) /* If the Warnings value is not set, supply a default in the form of a pointer to the constant string "BadKeyName BadKeyValue Tnx Zpx BadCel BadMat BadCTYPE". */ astMAKE_GET(FitsChan,Warnings,const char *,NULL,( this->warnings ? this->warnings : "BadKeyName BadKeyValue Tnx Zpx BadPV BadCel BadMat BadCTYPE" )) /* Set a Warnings value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. First check that the list does not contain any unknown conditions. If it does, an error is reported by GoodWarns and the current attribute value is retained. */ astMAKE_SET(FitsChan,Warnings,const char *,warnings,( GoodWarns( value, status ) ? astStore( this->warnings, value, strlen( value ) + (size_t) 1 ) : this->warnings)) /* The Warnings value is set if the pointer to it is not NULL. */ astMAKE_TEST(FitsChan,Warnings,( this->warnings != NULL )) /* AllWarnings. */ /* ============ */ /* *att++ * Name: * AllWarnings * Purpose: * A list of all currently available condition names. * Type: * Public attribute. * Synopsis: * String, read-only * Description: * This read-only attribute is a space separated list of all the conditions * names recognized by the Warnings attribute. The names are listed * below. * Conditions: * The following conditions are currently recognised (all are * case-insensitive): * * - "BadCel": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan if an unknown celestial co-ordinate * system is specified by the CTYPE keywords. * * - "BadCTYPE": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan if an illegal algorithm code is specified * by a CTYPE keyword, and the illegal code can be converted to an * equivalent legal code. * * - "BadKeyName": This condition arises if a FITS keyword name is * encountered that contains an illegal character (i.e. one not allowed * by the FITS standard). * * - "BadKeyValue": This condition arises if the value of a FITS keyword * cannot be determined from the content of the header card. * * - "BadLat": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan if the latitude of the reference point * has an absolute value greater than 90 degrees. The actual absolute * value used is set to exactly 90 degrees in these cases. * * - "BadMat": This condition arises if the matrix describing the * transformation from pixel offsets to intermediate world coordinates * cannot be inverted. This matrix describes the scaling, rotation, shear, * etc., applied to the pixel axes, and is specified by keywords such as * PCi_j, CDi_j, CROTA, etc. For example, the matrix will not be invertable * if any rows or columns consist entirely of zeros. The FITS-WCS Paper I * "Representation of World Coordinates in FITS" by Greisen & Calabretta * requires that this matrix be invertable. Many operations (such as * grid plotting) will not be possible if the matrix cannot be inverted. * * - "BadPV": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan. It is issued if a PVi_m header is found * that refers to a projection parameter that is not used by the * projection type specified by CTYPE, or the PV values are otherwise * inappropriate for the projection type. * * - "BadVal": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan if it is not possible to convert the * value of a FITS keywords to the expected type. For instance, this * can occur if the FITS header contains a string value for a keyword * which should have a floating point value, or if the keyword has no * value at all (i.e. is a comment card). * * - "Distortion": This condition arises when reading a FrameSet from a * non-Native encoded FitsChan if any of the CTYPE keywords specify an * unsupported distortion code using the "4-3-3" format specified in * FITS-WCS paper IV. Such distortion codes are ignored. * * - "NoCTYPE": This condition arises if a default CTYPE value is used c within astRead, due to no value being present in the supplied FitsChan. f within AST_READ, due to no value being present in the supplied FitsChan. * This condition is only tested for when using non-Native encodings. * * - "NoEquinox": This condition arises if a default equinox value is used c within astRead, due to no value being present in the supplied FitsChan. f within AST_READ, due to no value being present in the supplied FitsChan. * This condition is only tested for when using non-Native encodings. * * - "NoRadesys": This condition arises if a default reference frame is c used for an equatorial co-ordinate system within astRead, due to no f used for an equatorial co-ordinate system within AST_READ, due to no * value being present in the supplied FitsChan. This condition is only * tested for when using non-Native encodings. * * - "NoLonpole": This condition arises if a default value is used for c the LONPOLE keyword within astRead, due to no value being present f the LONPOLE keyword within AST_READ, due to no value being present * in the supplied FitsChan. This condition is only tested for when * using non-Native encodings. * * - "NoLatpole": This condition arises if a default value is used for c the LATPOLE keyword within astRead, due to no value being present f the LATPOLE keyword within AST_READ, due to no value being present * in the supplied FitsChan. This condition is only tested for when * using non-Native encodings. * * - "NoMjd-obs": This condition arises if a default value is used for c the date of observation within astRead, due to no value being present f the date of observation within AST_READ, due to no value being present * in the supplied FitsChan. This condition is only tested for when using * non-Native encodings. * * - "Tnx": This condition arises if a FrameSet is read from a FITS * header containing an IRAF "TNX" projection which includes terms * not supproted by AST. Such terms are ignored and so the resulting * FrameSet may be inaccurate. * * - "Zpx": This condition arises if a FrameSet is read from a FITS * header containing an IRAF "ZPX" projection which includes "lngcor" * or "latcor" correction terms. These terms are not supported by AST * and are ignored. The resulting FrameSet may therefore be inaccurate. * Applicability: * FitsChan * All FitsChans have this attribute. *att-- */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for FitsChan objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for FitsChan objects. * Parameters: * objin * Pointer to the FitsChan to be copied. * objout * Pointer to the FitsChan being constructed. * status * Pointer to the inherited status variable. * Notes: * - The source and sink functions are not propagated (i.e. the * pointers are set NULL in the output FitsChan). * - This constructor makes a deep copy, including a copy of the * keyword values. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *class; /* Pointer to object class */ AstFitsChan *in; /* Pointer to input FitsChan */ AstFitsChan *out; /* Pointer to output FitsChan */ int *flags; int icard; int old_ignore_used; /* Original value of external variable ignore_used */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(objin); /* Obtain pointers to the input and output FitsChans. */ in = (AstFitsChan *) objin; out = (AstFitsChan *) objout; /* Nullify all pointers in the output FitsChan so that the input data will not be deleted in the event of an error occurring. */ out->card = NULL; out->head = NULL; out->keyseq = NULL; out->keywords = NULL; out->source = NULL; out->saved_source = NULL; out->source_wrap = NULL; out->sink = NULL; out->sink_wrap = NULL; out->warnings = NULL; out->tabsource = NULL; out->tabsource_wrap = NULL; /* Store the object class. */ class = astGetClass( in ); /* Ensure all cards are copied, including those already read by astRead. */ old_ignore_used = ignore_used; ignore_used = 0; /* Save the current card index in the input FitsChan. */ icard = astGetCard( in ); /* Rewind the input FitsChan. */ astClearCard( in ); /* Copy all the FitsCard structures from input to output. */ while( !astFitsEof( in ) && astOK ){ /* Get a pointer to the flags mask for this card. */ flags = CardFlags( in, status ); /* Store a new card in the output, holding the same information as the input card. */ NewCard( out, CardName( in, status ), CardType( in, status ), CardData( in, NULL, status ), CardComm( in, status ), (flags?(*flags):0), status ); /* Move on to the next input card. */ MoveCard( in, 1, "astCopy", class, status ); } /* Set the current card in both input and output to the current input card on entry. */ astSetCard( in, icard ); astSetCard( out, icard ); /* Copy the list of keyword sequence numbers used. */ if( in->keyseq ) out->keyseq = astCopy( in->keyseq ); /* Copy the Warnings attribute value */ if( in->warnings ) out->warnings = astStore( NULL, in->warnings, strlen( in->warnings ) + 1 ); /* Copy any tables currently in the FitsChan structure. */ if( in->tables ) out->tables = astCopy( in->tables ); /* Reinstate the original setting of the external ignore_used variable. */ ignore_used = old_ignore_used; /* If an error occurred, delete the contents of the output Object. */ if( !astOK ) Delete( objout, status ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for FitsChan objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for FitsChan objects. * Parameters: * obj * Pointer to the FitsChan 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: */ AstFitsChan *this; /* Pointer to FitsChan */ /* Obtain a pointer to the FitsChan structure. */ this = (AstFitsChan *) obj; /* Write out the contents of the FitsChan using the sink function provided when it was created. */ WriteToSink( this, status ); /* Remove all cards from the FitsChan. */ EmptyFits( this, status ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for FitsChan 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 FitsChan class to an output Channel. * Parameters: * this * Pointer to the FitsChan whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstFitsChan *this; /* Pointer to the FitsChan structure */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *class; /* Object class */ const char *sval; /* Pointer to string value */ int cardtype; /* Keyword data type */ int flags; /* Keyword flags */ int icard; /* Index of current card */ int ival; /* Integer value */ int ncard; /* No. of cards dumped so far */ int old_ignore_used; /* Original value of external variable ignore_used */ int set; /* Attribute value set? */ void *data; /* Pointer to keyword data value */ /* 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 FitsChan structure. */ this = (AstFitsChan *) this_object; /* Store the object class. */ class = astGetClass( this ); /* Save the index of ht ecurrent card. */ icard = astGetCard( this ); /* Write out values representing the instance variables for the FitsChan class. Accompany these with appropriate comment strings, possibly depending on the values being written.*/ /* Card. */ /* ----- */ astWriteInt( channel, "Card", 1, 1, icard, "Index of current card" ); /* Encoding. */ /* --------- */ set = TestEncoding( this, status ); ival = set ? GetEncoding( this, status ) : astGetEncoding( this ); if( ival > UNKNOWN_ENCODING && ival <= MAX_ENCODING ) { astWriteString( channel, "Encod", set, 1, xencod[ival], "Encoding system" ); } else { astWriteString( channel, "Encod", set, 1, UNKNOWN_STRING, "Encoding system" ); } /* FitsAxisOrder. */ /* -------------- */ set = TestFitsAxisOrder( this, status ); sval = set ? GetFitsAxisOrder( this, status ) : astGetFitsAxisOrder( this ); astWriteString( channel, "FAxOrd", set, 1, sval, "Order of WCS axes in new FITS headers" ); /* FitsDigits. */ /* ----------- */ set = TestFitsDigits( this, status ); ival = set ? GetFitsDigits( this, status ) : astGetFitsDigits( this ); astWriteInt( channel, "FitsDg", set, 1, ival, "No. of digits for floating point values" ); /* DefB1950 */ /* -------- */ set = TestDefB1950( this, status ); ival = set ? GetDefB1950( this, status ) : astGetDefB1950( this ); astWriteInt( channel, "DfB1950", set, 1, ival, (ival ? "Default to FK4 B1950": "Default to ICRS") ); /* TabOK */ /* ----- */ set = TestTabOK( this, status ); ival = set ? GetTabOK( this, status ) : astGetTabOK( this ); astWriteInt( channel, "TabOK", set, 1, ival, ( ival > 0 ? "EXTVER value for -TAB headers": "Do not support -TAB CTYPE codes") ); /* CDMatrix */ /* -------- */ set = TestCDMatrix( this, status ); ival = set ? GetCDMatrix( this, status ) : astGetCDMatrix( this ); astWriteInt( channel, "CdMat", set, 1, ival, (ival ? "Use CD Matrix":"Use PC matrix") ); /* CarLin */ /* ------ */ set = TestCarLin( this, status ); ival = set ? GetCarLin( this, status ) : astGetCarLin( this ); astWriteInt( channel, "CarLin", set, 1, ival, (ival ? "Use simple linear CAR projections": "Use full FITS-WCS CAR projections") ); /* PolyTan */ /* ------- */ set = TestPolyTan( this, status ); ival = set ? GetPolyTan( this, status ) : astGetPolyTan( this ); astWriteInt( channel, "PolyTan", set, 0, ival, (ival ? "Use distorted TAN convention": "Use standard TAN convention") ); /* Iwc */ /* --- */ set = TestIwc( this, status ); ival = set ? GetIwc( this, status ) : astGetIwc( this ); astWriteInt( channel, "Iwc", set, 1, ival, (ival ? "Include an IWC Frame": "Do not include an IWC Frame") ); /* Clean */ /* ----- */ set = TestClean( this, status ); ival = set ? GetClean( this, status ) : astGetClean( this ); astWriteInt( channel, "Clean", set, 0, ival, "Always remove used cards?" ); /* Warnings. */ /* --------- */ set = TestWarnings( this, status ); sval = set ? GetWarnings( this, status ) : astGetWarnings( this ); astWriteString( channel, "Warn", set, 1, sval, "Warnings to be reported" ); /* Now do instance variables which are not attributes. */ /* =================================================== */ /* Ensure all cards are copied, including those already read by astRead. */ old_ignore_used = ignore_used; ignore_used = 0; /* Rewind the FitsChan. */ astClearCard( this ); /* Dump each card. */ ncard = 1; while( !astFitsEof( this ) && astOK ){ /* Write out the keyword name. */ if( CardName( this, status ) ){ (void) sprintf( buff, "Nm%d", ncard ); astWriteString( channel, buff, 1, 1, CardName( this, status ), "FITS keyword name" ); } /* Write out the keyword type. */ cardtype = CardType( this, status ); (void) sprintf( buff, "Ty%d", ncard ); astWriteString( channel, buff, 1, 1, type_names[ cardtype ], "FITS keyword data type" ); /* Write out the flag values if any are non-zero. */ flags = *CardFlags( this, status ); if( flags ){ (void) sprintf( buff, "Fl%d", ncard ); astWriteInt( channel, buff, 1, 1, flags, "FITS keyword flags" ); } /* Write out the data value, if defined, using the appropriate data type. */ data = CardData( this, NULL, status ); if( data && cardtype != AST__UNDEF ){ if( cardtype == AST__FLOAT ){ (void) sprintf( buff, "Dt%d", ncard ); astWriteDouble( channel, buff, 1, 1, *( (double *) data ), "FITS keyword value" ); } else if( cardtype == AST__STRING || cardtype == AST__CONTINUE ){ (void) sprintf( buff, "Dt%d", ncard ); astWriteString( channel, buff, 1, 1, (char *) data, "FITS keyword value" ); } else if( cardtype == AST__INT ){ (void) sprintf( buff, "Dt%d", ncard ); astWriteInt( channel, buff, 1, 1, *( (int *) data ), "FITS keyword value" ); } else if( cardtype == AST__LOGICAL ){ (void) sprintf( buff, "Dt%d", ncard ); astWriteInt( channel, buff, 1, 1, *( (int *) data ), "FITS keyword value" ); } else if( cardtype == AST__COMPLEXF ){ (void) sprintf( buff, "Dr%d", ncard ); astWriteDouble( channel, buff, 1, 1, *( (double *) data ), "FITS keyword real value" ); (void) sprintf( buff, "Di%d", ncard ); astWriteDouble( channel, buff, 1, 1, *( ( (double *) data ) + 1 ), "FITS keyword imaginary value" ); } else if( cardtype == AST__COMPLEXI ){ (void) sprintf( buff, "Dr%d", ncard ); astWriteInt( channel, buff, 1, 1, *( (int *) data ), "FITS keyword real value" ); (void) sprintf( buff, "Di%d", ncard ); astWriteInt( channel, buff, 1, 1, *( ( (int *) data ) + 1 ), "FITS keyword imaginary value" ); } } /* Write out the keyword comment. */ if( CardComm( this, status ) ){ (void) sprintf( buff, "Cm%d", ncard ); astWriteString( channel, buff, 1, 1, CardComm( this, status ), "FITS keyword comment" ); } /* Move on to the next card. */ ncard++; MoveCard( this, 1, "astDump", class, status ); } /* Dump any FitTables. */ if( this->tables ) { astWriteObject( channel, "Tables", 1, 1, this->tables, "A KeyMap holding associated binary tables" ); } /* Reinstate the original setting of the external ignore_used variable. */ ignore_used = old_ignore_used; /* Reinstate the original current card. */ astSetCard( this, icard ); #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAFitsChan and astCheckFitsChan functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(FitsChan,Channel) astMAKE_CHECK(FitsChan) AstFitsChan *astFitsChan_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, int *status, ...) { /* *++ * Name: c astFitsChan f AST_FITSCHAN * Purpose: * Create a FitsChan. * Type: * Public function. * Synopsis: c #include "fitschan.h" c AstFitsChan *astFitsChan( const char *(* source)( void ), c void (* sink)( const char * ), c const char *options, ... ) f RESULT = AST_FITSCHAN( SOURCE, SINK, OPTIONS, STATUS ) * Class Membership: * FitsChan constructor. * Description: * This function creates a new FitsChan and optionally initialises * its attributes. * * A FitsChan is a specialised form of Channel which supports I/O * operations involving the use of FITS (Flexible Image Transport * System) header cards. Writing an Object to a FitsChan (using c astWrite) will, if the Object is suitable, generate a f AST_WRITE) will, if the Object is suitable, generate a * description of that Object composed of FITS header cards, and * reading from a FitsChan will create a new Object from its FITS * header card description. * * While a FitsChan is active, it represents a buffer which may * contain zero or more 80-character "header cards" conforming to * FITS conventions. Any sequence of FITS-conforming header cards * may be stored, apart from the "END" card whose existence is * merely implied. The cards may be accessed in any order by using * the FitsChan's integer Card attribute, which identifies a "current" * card, to which subsequent operations apply. Searches c based on keyword may be performed (using astFindFits), new c cards may be inserted (astPutFits, astPutCards, astSetFits) and c existing ones may be deleted (astDelFits) or changed (astSetFits). f based on keyword may be performed (using AST_FINDFITS), new f cards may be inserted (AST_PUTFITS, AST_PUTCARDS, AST_SETFITS) and f existing ones may be deleted (AST_DELFITS) or changed (AST_SETFITS). * * When you create a FitsChan, you have the option of specifying * "source" and "sink" functions which connect it to external data * stores by reading and writing FITS header cards. If you provide * a source function, it is used to fill the FitsChan with header cards * when it is accessed for the first time. If you do not provide a * source function, the FitsChan remains empty until you explicitly enter c data into it (e.g. using astPutFits, astPutCards, astWrite f data into it (e.g. using AST_PUTFITS, AST_PUTCARDS, AST_WRITE * or by using the SourceFile attribute to specifying a text file from * which headers should be read). When the FitsChan is deleted, any * remaining header cards in the FitsChan can be saved in either of * two ways: 1) by specifying a value for the SinkFile attribute (the * name of a text file to which header cards should be written), or 2) * by providing a sink function (used to to deliver header cards to an * external data store). If you do not provide a sink function or a * value for SinkFile, any header cards remaining when the FitsChan * is deleted will be lost, so you should arrange to extract them * first if necessary c (e.g. using astFindFits or astRead). f (e.g. using AST_FINDFITS or AST_READ). * * Coordinate system information may be described using FITS header * cards using several different conventions, termed * "encodings". When an AST Object is written to (or read from) a * FitsChan, the value of the FitsChan's Encoding attribute * determines how the Object is converted to (or from) a * description involving FITS header cards. In general, different * encodings will result in different sets of header cards to * describe the same Object. Examples of encodings include the DSS * encoding (based on conventions used by the STScI Digitised Sky * Survey data), the FITS-WCS encoding (based on a proposed FITS * standard) and the NATIVE encoding (a near loss-less way of * storing AST Objects in FITS headers). * * The available encodings differ in the range of Objects they can * represent, in the number of Object descriptions that can coexist * in the same FitsChan, and in their accessibility to other * (external) astronomy applications (see the Encoding attribute * for details). Encodings are not necessarily mutually exclusive * and it may sometimes be possible to describe the same Object in * several ways within a particular set of FITS header cards by * using several different encodings. * c The detailed behaviour of astRead and astWrite, when used with f The detailed behaviour of AST_READ and AST_WRITE, when used with * a FitsChan, depends on the encoding in use. In general, however, c all use of astRead is destructive, so that FITS header cards f all use of AST_READ is destructive, so that FITS header cards * are consumed in the process of reading an Object, and are * removed from the FitsChan (this deletion can be prevented for * specific cards by calling the c astRetainFits function). f AST_RETAINFITS routine). * * If the encoding in use allows only a single Object description * to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF c encodings), then write operations using astWrite will f encodings), then write operations using AST_WRITE will * over-write any existing Object description using that * encoding. Otherwise (e.g. the NATIVE encoding), multiple Object * descriptions are written sequentially and may later be read * back in the same sequence. * Parameters: c source f SOURCE = FUNCTION (Given) c Pointer to a source function which takes no arguments and c returns a pointer to a null-terminated string. This function c will be used by the FitsChan to obtain input FITS header c cards. On each invocation, it should read the next input card c from some external source (such as a FITS file), and return a c pointer to the (null-terminated) contents of the card. It c should return a NULL pointer when there are no more cards to c be read. c c If "source" is NULL, the FitsChan will remain empty until c cards are explicitly stored in it (e.g. using astPutCards, c astPutFits or via the SourceFile attribute). f A source routine, which is a function taking two arguments: a f character argument of length 80 to contain a FITS card, and an f integer error status argument. It should return an integer value. f This function will be used by the FitsChan to obtain input f FITS header cards. On each invocation, it should read the f next input card from some external source (such as a FITS f file), and return the contents of the card via its character f argument. It should return a function result of one unless f there are no more cards to be read, in which case it should f return zero. If an error occurs, it should set its error f status argument to an error value before returning. f f If the null routine AST_NULL is supplied as the SOURCE value, f the FitsChan will remain empty until cards are explicitly f stored in it (e.g. using AST_PUTCARDS, AST_PUTFITS or via the f SourceFile attribute). c sink f SINK = SUBROUTINE (Given) c Pointer to a sink function that takes a pointer to a c null-terminated string as an argument and returns void. If c no value has been set for the SinkFile attribute, this c function will be used by the FitsChan to deliver any FITS c header cards it contains when it is finally deleted. On c each invocation, it should deliver the contents of the character c string passed to it as a FITS header card to some external c data store (such as a FITS file). f A sink routine, which is a subroutine which takes two f arguments: a character argument of length 80 to contain a f FITS card, and an integer error status argument. If no f value has been set for the SinkFile attribute, this routine f will be used by the FitsChan to deliver any FITS header cards f it contains when it is finally deleted. On each invocation, f it should deliver the contents of the character string passed f to it as a FITS header card to some external data store (such f as a FITS file). If an error occurs, it should set its error f status argument to an error value before returning. * c If "sink" is NULL, f If the null routine AST_NULL is supplied as the SINK value, * and no value has been set for the SinkFile attribute, the * contents of the FitsChan will be lost when it is deleted. 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 FitsChan. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new FitsChan. The syntax used is identical to that for the f AST_SET routine. 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). * * Note, the FITSCHAN_OPTIONS environment variable may be used * to specify default options for all newly created FitsChans. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astFitsChan() f AST_FITSCHAN = INTEGER * A pointer to the new FitsChan. * Notes: f - The names of the routines supplied for the SOURCE and SINK f arguments should appear in EXTERNAL statements in the Fortran f routine which invokes AST_FITSCHAN. However, this is not generally f necessary for the null routine AST_NULL (so long as the AST_PAR f include file has been used). c - No FITS "END" card will be written via the sink function. You f - No FITS "END" card will be written via the sink routine. You * should add this card yourself after the FitsChan has been * deleted. * - 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. f - Note that the null routine AST_NULL (one underscore) is f different to AST__NULL (two underscores), which is the null Object f pointer. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFitsChan *new; /* Pointer to new FitsChan */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the FitsChan, allocating memory and initialising the virtual function table as well if necessary. This interface is for use by other C functions within AST, and uses the standard "wrapper" functions included in this class. */ new = astInitFitsChan( NULL, sizeof( AstFitsChan ), !class_init, &class_vtab, "FitsChan", source, SourceWrap, sink, SinkWrap ); /* If successful, note that the virtual function table has been initialised. */ if ( astOK ) { class_init = 1; /* Apply any default options specified by "_OPTIONS" environment variable. */ astEnvSet( new ); /* Obtain the variable argument list and pass it along with the options string to the astVSet method to initialise the new FitsChan'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 FitsChan. */ return new; } AstFitsChan *astFitsChanId_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, ... ) { /* * Name: * astFitsChanId_ * Purpose: * Create a FitsChan. * Type: * Private function. * Synopsis: * #include "fitschan.h" * AstFitsChan *astFitsChanId_( const char *(* source)( void ), * void (* sink)( const char * ), * const char *options, ... ) * Class Membership: * FitsChan constructor. * Description: * This function implements the external (public) C interface to the * astFitsChan constructor function. Another function (astFitsChanForId) * should be called to create a FitsChan for use within other languages. * Both functions return an ID value (instead of a true C pointer) to * external users, and must be provided because astFitsChan_ has a variable * argument list which cannot be encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astFitsChan_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astFitsChan_. * Returned Value: * The ID value associated with the new FitsChan. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFitsChan *new; /* Pointer to new FitsChan */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the FitsChan, allocating memory and initialising the virtual function table as well if necessary. This interface is for use by external C functions and uses the standard "wrapper" functions included in this class. */ new = astInitFitsChan( NULL, sizeof( AstFitsChan ), !class_init, &class_vtab, "FitsChan", source, SourceWrap, sink, SinkWrap ); /* If successful, note that the virtual function table has been initialised. */ if ( astOK ) { class_init = 1; /* Apply any default options specified by "_OPTIONS" environment variable. */ astEnvSet( new ); /* Obtain the variable argument list and pass it along with the options string to the astVSet method to initialise the new FitsChan'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 FitsChan. */ return astMakeId( new ); } AstFitsChan *astFitsChanForId_( const char *(* source)( void ), char *(* source_wrap)( const char *(*)( void ), int * ), void (* sink)( const char * ), void (* sink_wrap)( void (*)( const char * ), const char *, int * ), const char *options, ... ) { /* *+ * Name: * astFitsChanFor * Purpose: * Initialise a FitsChan from a foreign language interface. * Type: * Public function. * Synopsis: * #include "fitschan.h" * AstFitsChan *astFitsChanFor( const char *(* source)( void ), * char *(* source_wrap)( const char *(*) * ( void ), int * ), * void (* sink)( const char * ), * void (* sink_wrap)( void (*)( const char * ), * const char *, int * ), * const char *options, ... ) * Class Membership: * FitsChan constructor. * Description: * This function creates a new FitsChan from a foreign language * interface and optionally initialises its attributes. * * A FitsChan implements FITS input/output for the AST library. * Writing an Object to a FitsChan (using astWrite) will generate a * textual representation of that Object in terms of FITS header cards, * and reading from a FitsChan (using astRead) will create a new Object * from its FITS representation. * * Normally, when you use a FitsChan, you should provide "source" * and "sink" functions which connect it to an external data store * by reading and writing the resulting text. This function also * requires you to provide "wrapper" functions which will invoke * the source and sink functions. * Parameters: * source * Pointer to a "source" function which will be used to obtain * FITS header cards. Generally, this will be obtained by * casting a pointer to a source function which is compatible * with the "source_wrap" wrapper function (below). The pointer * should later be cast back to its original type by the * "source_wrap" function before the function is invoked. * * If "source" is NULL, the FitsChan will remain empty until * cards are added explicitly (e.g. using astPutCards or astPutFits). * source_wrap * Pointer to a function which can be used to invoke the * "source" function supplied (above). This wrapper function is * necessary in order to hide variations in the nature of the * source function, such as may arise when it is supplied by a * foreign (non-C) language interface. * * The single parameter of the "source_wrap" function is a * pointer to the "source" function, and it should cast this * function pointer (as necessary) and invoke the function with * appropriate arguments to obtain the next FITS header card. * The "source_wrap" function should then return a pointer * to a dynamically allocated, null terminated string containing * the text that was read. The string will be freed (using * astFree) when no longer required and the "source_wrap" * function need not concern itself with this. A NULL pointer * should be returned if there is no more input to read. * * If "source" is NULL, the FitsChan will remain empty until * cards are added explicitly (e.g. using astPutCards or astPutFits). * sink * Pointer to a "sink" function which will be used to deliver * FITS header cards. Generally, this will be obtained by * casting a pointer to a sink function which is compatible with * the "sink_wrap" wrapper function (below). The pointer should * later be cast back to its original type by the "sink_wrap" * function before the function is invoked. * * If "sink" is NULL, the contents of the FitsChan will not be * written out before being deleted. * sink_wrap * Pointer to a function which can be used to invoke the "sink" * function supplied (above). This wrapper function is necessary * in order to hide variations in the nature of the sink * function, such as may arise when it is supplied by a foreign * (non-C) language interface. * * The first parameter of the "sink_wrap" function is a pointer * to the "sink" function, and the second parameter is a pointer * to a const, null-terminated character string containing the * text to be written. The "sink_wrap" function should cast the * "sink" function pointer (as necessary) and invoke the * function with appropriate arguments to deliver the line of * output text. The "sink_wrap" function then returns void. * * If "sink_wrap" is NULL, the contents of the FitsChan will not be * written out before being deleted. * options * Pointer to a null-terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new FitsChan. The syntax used is identical to * that for the astSet function and may include "printf" format * specifiers identified by "%" symbols in the normal way. * ... * If the "options" string contains "%" format specifiers, then * an optional list of additional 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 function (and for the C "printf" * function). * Returned Value: * astFitsChanFor() * A pointer to the new FitsChan. * Notes: * - A null Object pointer (AST__NULL) will be returned if this * function is invoked with the global error status set, or if it * should fail for any reason. * - This function is only available through the public interface * to the FitsChan class (not the protected interface) and is * intended solely for use in implementing foreign language * interfaces to this class. *- * Implememtation Notes: * - This function behaves exactly like astFitsChanId_, in that it * returns ID values and not true C pointers, but it has two * additional arguments. These are pointers to the "wrapper * functions" which are needed to accommodate foreign language * interfaces. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFitsChan *new; /* Pointer to new FitsChan */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise the FitsChan, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitFitsChan( NULL, sizeof( AstFitsChan ), !class_init, &class_vtab, "FitsChan", source, source_wrap, sink, sink_wrap ); /* If successful, note that the virtual function table has been initialised. */ if ( astOK ) { class_init = 1; /* Apply any default options specified by "_OPTIONS" environment variable. */ astEnvSet( new ); /* Obtain the variable argument list and pass it along with the options string to the astVSet method to initialise the new FitsChan'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 FitsChan. */ return astMakeId( new ); } AstFitsChan *astInitFitsChan_( void *mem, size_t size, int init, AstFitsChanVtab *vtab, const char *name, const char *(* source)( void ), char *(* source_wrap)( const char *(*)( void ), int * ), void (* sink)( const char * ), void (* sink_wrap)( void (*)( const char * ), const char *, int * ), int *status ) { /* *+ * Name: * astInitFitsChan * Purpose: * Initialise a FitsChan. * Type: * Protected function. * Synopsis: * #include "fitschan.h" * AstFitsChan *astInitFitsChan_( void *mem, size_t size, int init, * AstFitsChanVtab *vtab, const char *name, * const char *(* source)( void ), * char *(* source_wrap)( const char *(*)( void ), int * ), * void (* sink)( const char * ), * void (* sink_wrap)( void (*)( const char * ), * const char *, int * ) ) * Class Membership: * FitsChan initialiser. * Description: * This function is provided for use by class implementations to * initialise a new FitsChan object. It allocates memory (if * necessary) to accommodate the FitsChan plus any additional data * associated with the derived class. It then initialises a * FitsChan 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 FitsChan at the start of the memory passed * via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the FitsChan is to be * initialised. This must be of sufficient size to accommodate * the FitsChan data (sizeof(FitsChan)) 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 FitsChan (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 FitsChan structure, so a valid value must be * supplied even if not required for allocating memory. * init * A boolean flag indicating if the FitsChan'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 FitsChan. * 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). * source * Pointer to a "source" function which will be used to obtain * FITS header cards. Generally, this will be obtained by * casting a pointer to a source function which is compatible * with the "source_wrap" wrapper function (below). The pointer * should later be cast back to its original type by the * "source_wrap" function before the function is invoked. * * If "source" is NULL, the FitsChan will remain empty until * cards are added explicitly (e.g. using astPutCards or astPutFits). * source_wrap * Pointer to a function which can be used to invoke the * "source" function supplied (above). This wrapper function is * necessary in order to hide variations in the nature of the * source function, such as may arise when it is supplied by a * foreign (non-C) language interface. * * The single parameter of the "source_wrap" function is a * pointer to the "source" function, and it should cast this * function pointer (as necessary) and invoke the function with * appropriate arguments to obtain the next FITS header card. * The "source_wrap" function should then return a pointer * to a dynamically allocated, null terminated string containing * the text that was read. The string will be freed (using * astFree) when no longer required and the "source_wrap" * function need not concern itself with this. A NULL pointer * should be returned if there is no more input to read. * * If "source" is NULL, the FitsChan will remain empty until * cards are added explicitly (e.g. using astPutCards or astPutFits). * sink * Pointer to a "sink" function which will be used to deliver * FITS header cards. Generally, this will be obtained by * casting a pointer to a sink function which is compatible with * the "sink_wrap" wrapper function (below). The pointer should * later be cast back to its original type by the "sink_wrap" * function before the function is invoked. * * If "sink" is NULL, the contents of the FitsChan will not be * written out before being deleted. * sink_wrap * Pointer to a function which can be used to invoke the "sink" * function supplied (above). This wrapper function is necessary * in order to hide variations in the nature of the sink * function, such as may arise when it is supplied by a foreign * (non-C) language interface. * * The first parameter of the "sink_wrap" function is a pointer * to the "sink" function, and the second parameter is a pointer * to a const, null-terminated character string containing the * text to be written. The "sink_wrap" function should cast the * "sink" function pointer (as necessary) and invoke the * function with appropriate arguments to deliver the line of * output text. The "sink_wrap" function then returns void. * * If "sink_wrap" is NULL, the contents of the FitsChan will not be * written out before being deleted. * Returned Value: * A pointer to the new FitsChan. * 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: */ AstFitsChan *new; /* Pointer to new FitsChan */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitFitsChanVtab( vtab, name ); /* Initialise a Channel structure (the parent class) as the first component within the FitsChan structure, allocating memory if necessary. I am not sure why FitsChan has its own source_wrap and sink_wrap items, rather than just using those inherited from Channel. It may be possible to do away with the fitschan wrappers and just use the channel wrapper, but I have not yet tried this. Old mail from RFWS suggests that it may be because the F77 FitsChan source and sink interfaces handle fixed length strings (80 characters), whereas Channel sournce and sink handle variable length strings. This needs investigating. */ new = (AstFitsChan *) astInitChannel( mem, size, 0, (AstChannelVtab *) vtab, name, NULL, NULL, NULL, NULL ); if ( astOK ) { /* Initialise the FitsChan data. */ /* ---------------------------- */ new->head = NULL; new->card = NULL; new->keyseq = NULL; new->keywords = NULL; new->defb1950 = -1; new->tabok = -INT_MAX; new->cdmatrix = -1; new->carlin = -1; new->polytan = -INT_MAX; new->iwc = -1; new->clean = -1; new->fitsdigits = DBL_DIG; new->fitsaxisorder = NULL; new->encoding = UNKNOWN_ENCODING; new->warnings = NULL; new->tables = NULL; /* Save the pointers to the source and sink functions and the wrapper functions that invoke them. */ new->source = source; new->saved_source = NULL; new->source_wrap = source_wrap; new->sink = sink; new->sink_wrap = sink_wrap; new->tabsource = NULL; new->tabsource_wrap = NULL; /* Rewind the FitsChan so that the next read operation will return the first card. */ new->card = new->head; /* 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; } AstFitsChan *astLoadFitsChan_( void *mem, size_t size, AstFitsChanVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadFitsChan * Purpose: * Load a FitsChan. * Type: * Protected function. * Synopsis: * #include "fitschan.h" * AstFitsChan *astLoadFitsChan( void *mem, size_t size, * AstFitsChanVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * FitsChan loader. * Description: * This function is provided to load a new FitsChan 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 * FitsChan structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a FitsChan at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the FitsChan is to be * loaded. This must be of sufficient size to accommodate the * FitsChan data (sizeof(FitsChan)) 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 FitsChan (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 FitsChan 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(AstFitsChan) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new FitsChan. If this is NULL, a pointer * to the (static) virtual function table for the FitsChan 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 "FitsChan" is used instead. * Returned Value: * A pointer to the new FitsChan. * 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. *- */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFitsChan *new; /* Pointer to the new FitsChan */ char *comment; /* Pointer to keyword comment */ char *keynm; /* Keyword name */ char *text; /* Textual version of integer value */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ double dval[2]; /* Double precision data values */ int flags; /* Keyword flags */ int free_data; /* Should data memory be freed? */ int ival[2]; /* Integer data values */ int ncard; /* No. of FitsCards read so far */ int type; /* Keyword type */ void *data; /* Pointer to keyword data value */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this FitsChan. In this case the FitsChan belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstFitsChan ); vtab = &class_vtab; name = "FitsChan"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitFitsChanVtab( 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 FitsChan. */ new = astLoadChannel( mem, size, (AstChannelVtab *) 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, "FitsChan" ); /* Initialise the KeyMap holding the keywords in the FitsChan. */ new->keywords = NULL; /* Initialise the list of keyword sequence numbers. */ new->keyseq = NULL; /* Set the pointers to the source and sink functions, and their wrapper functions, to NULL (we cannot restore these since they refer to process-specific addresses). */ new->source = NULL; new->saved_source = NULL; new->source_wrap = NULL; new->sink = NULL; new->sink_wrap = NULL; new->tabsource = NULL; new->tabsource_wrap = NULL; /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* Encoding. */ /* --------- */ text = astReadString( channel, "encod", UNKNOWN_STRING ); if( text && strcmp( text, UNKNOWN_STRING ) ) { new->encoding = FindString( MAX_ENCODING + 1, xencod, text, "the FitsChan component 'Encod'", "astRead", astGetClass( channel ), status ); } else { new->encoding = UNKNOWN_ENCODING; } if ( TestEncoding( new, status ) ) SetEncoding( new, new->encoding, status ); text = astFree( text ); /* FitsAxisOrder. */ /* -------------- */ new->fitsaxisorder = astReadString( channel, "faxord", NULL ); /* FitsDigits. */ /* ----------- */ new->fitsdigits = astReadInt( channel, "fitsdg", DBL_DIG ); if ( TestFitsDigits( new, status ) ) SetFitsDigits( new, new->fitsdigits, status ); /* DefB1950 */ /* -------- */ new->defb1950 = astReadInt( channel, "dfb1950", -1 ); if ( TestDefB1950( new, status ) ) SetDefB1950( new, new->defb1950, status ); /* TabOK */ /* ----- */ new->tabok = astReadInt( channel, "tabok", -INT_MAX ); if ( TestTabOK( new, status ) ) SetTabOK( new, new->tabok, status ); /* CDMatrix */ /* -------- */ new->cdmatrix = astReadInt( channel, "cdmat", -1 ); if ( TestCDMatrix( new, status ) ) SetCDMatrix( new, new->cdmatrix, status ); /* CarLin */ /* ------ */ new->carlin = astReadInt( channel, "carlin", -1 ); if ( TestCarLin( new, status ) ) SetCarLin( new, new->carlin, status ); /* PolyTan */ /* ------- */ new->polytan = astReadInt( channel, "polytan", -1 ); if ( TestPolyTan( new, status ) ) SetPolyTan( new, new->polytan, status ); /* Iwc */ /* --- */ new->iwc = astReadInt( channel, "iwc", -1 ); if ( TestIwc( new, status ) ) SetIwc( new, new->iwc, status ); /* Clean */ /* ----- */ new->clean = astReadInt( channel, "clean", -1 ); if ( TestClean( new, status ) ) SetClean( new, new->clean, status ); /* Warnings. */ /* --------- */ new->warnings = astReadString( channel, "warn", NULL ); /* Card. */ /* ----- */ /* Initialise the index of the card to be read next. */ ncard = 1; new->card = NULL; new->head = NULL; /* Load each card. */ type = AST__NOTYPE + 1; while( type != AST__NOTYPE && astOK ){ /* Get the keyword type. */ (void) sprintf( buff, "ty%d", ncard ); text = astReadString( channel, buff, " " ); if( strcmp( text, " " ) ) { type = FindString( 9, type_names, text, "a FitsChan keyword data type", "astRead", astGetClass( channel ), status ); } else { type = AST__NOTYPE; } text = astFree( text ); /* Only proceed if the keyword type was found. */ if( type != AST__NOTYPE ){ /* Get the keyword name. Use a default blank name. */ (void) sprintf( buff, "nm%d", ncard ); keynm = astReadString( channel, buff, " " ); /* Get the data value, using the appropriate data type, unless the keyword is a comment keyword or is undefined. */ free_data = 0; if( type == AST__FLOAT ){ (void) sprintf( buff, "dt%d", ncard ); dval[ 0 ] = astReadDouble( channel, buff, AST__BAD ); data = (void *) dval; } else if( type == AST__STRING || type == AST__CONTINUE ){ (void) sprintf( buff, "dt%d", ncard ); data = (void *) astReadString( channel, buff, "" ); free_data = 1; } else if( type == AST__INT ){ (void) sprintf( buff, "dt%d", ncard ); ival[ 0 ] = astReadInt( channel, buff, 0 ); data = (void *) ival; } else if( type == AST__LOGICAL ){ (void) sprintf( buff, "dt%d", ncard ); ival[ 0 ] = astReadInt( channel, buff, 0 ); data = (void *) ival; } else if( type == AST__COMPLEXF ){ (void) sprintf( buff, "dr%d", ncard ); dval[ 0 ] = astReadDouble( channel, buff, AST__BAD ); (void) sprintf( buff, "di%d", ncard ); dval[ 1 ] = astReadDouble( channel, buff, AST__BAD ); data = (void *) dval; } else if( type == AST__COMPLEXI ){ (void) sprintf( buff, "dr%d", ncard ); ival[ 0 ] = astReadInt( channel, buff, 0 ); (void) sprintf( buff, "di%d", ncard ); ival[ 1 ] = astReadInt( channel, buff, 0 ); data = (void *) ival; } else { data = NULL; } /* Get the keyword flags (only written by versions of AST later than V1.4). These are packed into an int. */ (void) sprintf( buff, "fl%d", ncard ); flags = astReadInt( channel, buff, 0 ); /* If the flags were not found, use the keyword deletion flag written by AST V1.4 and earlier. */ if( !flags ) { (void) sprintf( buff, "dl%d", ncard ); flags = astReadInt( channel, buff, 0 ); } /* Get the keyword comment. */ (void) sprintf( buff, "cm%d", ncard ); comment = astReadString( channel, buff, NULL ); /* Append a new card to the output FitsChan. */ NewCard( new, keynm, type, data, comment, flags, status ); /* Free the character strings, and data (if required). */ comment = (char *) astFree( (void *) comment ); keynm = (char *) astFree( (void *) keynm ); if( free_data ) data = astFree( data ); } /* Move on to the next card. */ ncard++; } /* Set up the current card index. */ astSetCard( new, astReadInt( channel, "card", 0 ) ); /* Load any FitTables. */ new->tables = astReadObject( channel, "tables", NULL ); } /* If an error occurred, clean up by deleting the new FitsChan. */ if ( !astOK ) new = astDelete( new ); /* Return the new FitsChan pointer. */ return new; } /* 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 astWriteFits_( AstFitsChan *this, int *status ){ if( !this ) return; (**astMEMBER(this,FitsChan,WriteFits))(this, status ); } void astReadFits_( AstFitsChan *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,ReadFits))(this, status ); } void astEmptyFits_( AstFitsChan *this, int *status ){ if( !this ) return; (**astMEMBER(this,FitsChan,EmptyFits))(this, status ); } void astShowFits_( AstFitsChan *this, int *status ){ if( !this ) return; (**astMEMBER(this,FitsChan,ShowFits))(this, status ); } void astPutCards_( AstFitsChan *this, const char *cards, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,PutCards))(this,cards, status ); } void astPutFits_( AstFitsChan *this, const char *card, int overwrite, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,PutFits))(this,card,overwrite, status ); } void astDelFits_( AstFitsChan *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,DelFits))(this, status ); } void astPurgeWCS_( AstFitsChan *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,PurgeWCS))(this, status ); } AstKeyMap *astGetTables_( AstFitsChan *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,FitsChan,GetTables))(this, status ); } void astPutTables_( AstFitsChan *this, AstKeyMap *tables, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,PutTables))(this, tables, status ); } void astPutTable_( AstFitsChan *this, AstFitsTable *table, const char *extnam, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,PutTable))(this, table, extnam, status ); } void astRemoveTables_( AstFitsChan *this, const char *key, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,RemoveTables))(this, key, status ); } void astRetainFits_( AstFitsChan *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,RetainFits))(this, status ); } int astFitsEof_( AstFitsChan *this, int *status ){ if( !this ) return 1; return (**astMEMBER(this,FitsChan,FitsEof))( this, status ); } void astSetFitsCom_( AstFitsChan *this, const char *name, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsCom))( this, name, comment, overwrite, status ); } void astSetFitsI_( AstFitsChan *this, const char *name, int value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsI))( this, name, value, comment, overwrite, status ); } void astSetFitsF_( AstFitsChan *this, const char *name, double value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsF))( this, name, value, comment, overwrite, status ); } void astSetFitsS_( AstFitsChan *this, const char *name, const char *value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsS))( this, name, value, comment, overwrite, status ); } void astSetFitsCN_( AstFitsChan *this, const char *name, const char *value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsCN))( this, name, value, comment, overwrite, status ); } void astSetFitsCF_( AstFitsChan *this, const char *name, double *value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsCF))( this, name, value, comment, overwrite, status ); } void astSetFitsCI_( AstFitsChan *this, const char *name, int *value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsCI))( this, name, value, comment, overwrite, status ); } void astSetFitsL_( AstFitsChan *this, const char *name, int value, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsL))( this, name, value, comment, overwrite, status ); } void astSetFitsU_( AstFitsChan *this, const char *name, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsU))( this, name, comment, overwrite, status ); } void astSetFitsCM_( AstFitsChan *this, const char *comment, int overwrite, int *status ) { if ( !astOK ) return; (**astMEMBER(this,FitsChan,SetFitsCM))( this, comment, overwrite, status ); } void astClearCard_( AstFitsChan *this, int *status ){ if( !this ) return; (**astMEMBER(this,FitsChan,ClearCard))( this, status ); } void astSetCard_( AstFitsChan *this, int card, int *status ){ if( !this ) return; (**astMEMBER(this,FitsChan,SetCard))( this, card, status ); } int astTestCard_( AstFitsChan *this, int *status ){ if( !this ) return 0; return (**astMEMBER(this,FitsChan,TestCard))( this, status ); } int astGetCard_( AstFitsChan *this, int *status ){ if( !this ) return 0; return (**astMEMBER(this,FitsChan,GetCard))( this, status ); } int astGetNcard_( AstFitsChan *this, int *status ){ if( !this ) return 0; return (**astMEMBER(this,FitsChan,GetNcard))( this, status ); } int astGetCardType_( AstFitsChan *this, int *status ){ if( !this ) return AST__NOTYPE; return (**astMEMBER(this,FitsChan,GetCardType))( this, status ); } const char *astGetCardComm_( AstFitsChan *this, int *status ){ if( !this ) return NULL; return (**astMEMBER(this,FitsChan,GetCardComm))( this, status ); } const char *astGetCardName_( AstFitsChan *this, int *status ){ if( !this ) return NULL; return (**astMEMBER(this,FitsChan,GetCardName))( this, status ); } int astGetNkey_( AstFitsChan *this, int *status ){ if( !this ) return 0; return (**astMEMBER(this,FitsChan,GetNkey))( this, status ); } int astGetClean_( AstFitsChan *this, int *status ){ if( !this ) return 0; return (**astMEMBER(this,FitsChan,GetClean))( this, status ); } const char *astGetAllWarnings_( AstFitsChan *this, int *status ){ if( !this ) return NULL; return (**astMEMBER(this,FitsChan,GetAllWarnings))( this, status ); } int astGetFitsCF_( AstFitsChan *this, const char *name, double *value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsCF))( this, name, value, status ); } int astGetFitsCI_( AstFitsChan *this, const char *name, int *value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsCI))( this, name, value, status ); } int astGetFitsF_( AstFitsChan *this, const char *name, double *value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsF))( this, name, value, status ); } int astGetFitsI_( AstFitsChan *this, const char *name, int *value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsI))( this, name, value, status ); } int astGetFitsL_( AstFitsChan *this, const char *name, int *value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsL))( this, name, value, status ); } int astTestFits_( AstFitsChan *this, const char *name, int *there, int *status ){ if( there ) *there = 0; if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,TestFits))( this, name, there, status ); } int astGetFitsS_( AstFitsChan *this, const char *name, char **value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsS))( this, name, value, status ); } int astGetFitsCN_( AstFitsChan *this, const char *name, char **value, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetFitsCN))( this, name, value, status ); } int astFitsGetCom_( AstFitsChan *this, const char *name, char **comment, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,FitsGetCom))( this, name, comment, status ); } int astKeyFields_( AstFitsChan *this, const char *filter, int maxfld, int *ubnd, int *lbnd, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,KeyFields))( this, filter, maxfld, ubnd, lbnd, status ); } int astFindFits_( AstFitsChan *this, const char *name, char *card, int inc, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,FindFits))( this, name, card, inc, status ); } int astGetEncoding_( AstFitsChan *this, int *status ){ if( !astOK ) return UNKNOWN_ENCODING; return (**astMEMBER(this,FitsChan,GetEncoding))( this, status ); } int astGetCDMatrix_( AstFitsChan *this, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,FitsChan,GetCDMatrix))( this, status ); } void astSetTableSource_( AstFitsChan *this, void (*tabsource)( void ), void (*tabsource_wrap)( void (*)( void ), AstFitsChan *, const char *, int, int, int * ), int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,SetTableSource))( this, tabsource, tabsource_wrap, status ); } void astTableSource_( AstFitsChan *this, void (* tabsource)( AstFitsChan *, const char *, int, int, int * ), int *status ){ if( !astOK ) return; (**astMEMBER(this,FitsChan,TableSource))( this, tabsource, status ); } /* * A diagnostic function which lists the contents of a FitsChan to * standard output. */ /* static void ListFC( AstFitsChan *, const char * ); static void ListFC( AstFitsChan *this, const char *ttl ) { FitsCard *cardo; char card[ 81 ]; printf("%s\n----------------------------------------\n", ttl ); cardo = (FitsCard *) this->card; astClearCard( this ); while( !astFitsEof( this ) && astOK ){ FormatCard( this, card, "List" ); if( this->card == cardo ) { printf( "%s <<<<< currrent card <<<<< \n", card ); } else { printf( "%s\n", card ); } MoveCard( this, 1, "List", "FitsChan" ); } this->card = cardo; } */ ast-8.3.0/fskyframe.c0000664000175000017500000000644713004147321011375 00000000000000/* *+ * Name: * fskyframe.c * Purpose: * Define a FORTRAN 77 interface to the AST SkyFrame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the SkyFrame class. * Routines Defined: * AST_ISASKYFRAME * AST_SKYFRAME * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 23-JUL-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "skyframe.h" /* C interface to the SkyFrame class */ F77_LOGICAL_FUNCTION(ast_isaskyframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASKYFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsASkyFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_skyframe)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_SKYFRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astSkyFrame( "%s", options ) ); astFree( options ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_skyoffsetmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_SKYOFFSETMAP", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astSkyOffsetMap( astI2P( *THIS ) ) ); ) return RESULT; } ast-8.3.0/timemap.c0000664000175000017500000060367513004147321011050 00000000000000/* *class++ * Name: * TimeMap * Purpose: * Sequence of time coordinate conversions. * Constructor Function: c astTimeMap (also see astTimeAdd) f AST_TIMEMAP (also see AST_TIMEADD) * Description: * A TimeMap is a specialised form of 1-dimensional Mapping which can be * used to represent a sequence of conversions between standard time * coordinate systems. * * When a TimeMap is first created, it simply performs a unit c (null) Mapping. Using the astTimeAdd f (null) Mapping. Using the AST_TIMEADD c function, a series of coordinate conversion steps may then be f routine, a series of coordinate conversion steps may then be * added. This allows multi-step conversions between a variety of * time coordinate systems to be assembled out of a set of building * blocks. * * For details of the individual coordinate conversions available, c see the description of the astTimeAdd function. f see the description of the AST_TIMEADD routine. * Inheritance: * The TimeMap class inherits from the Mapping class. * Attributes: * The TimeMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c In addition to those functions applicable to all Mappings, the c following function may also be applied to all TimeMaps: f In addition to those routines applicable to all Mappings, the f following routine may also be applied to all TimeMaps: * c - astTimeAdd: Add a time coordinate conversion to an TimeMap f - AST_TIMEADD: Add a time coordinate conversion to an TimeMap * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * NG: Norman Gray (Starlink) * DSB: David Berry (Starlink) * History: * 5-Sep-2003 (NG): * Original version (drawing heavily on specmap.c) * 25-MAY-2005 (DSB): * Extensive modifications to make it more AST-like. * 10-AUG-2005 (DSB): * Add 2006 leap second. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 10-MAY-2006 (DSB): * Override astEqual. * 15-OCT-2006 (DSB): * Add conversions between UT1 and UTC (UTTOUTC and UTCTOUT). * 3-APR-2008 (DSB): * Only call memcpy if the source and destination pointers are * different. * 15-APR-2008 (DSB): * Add missing "break;" statement to "case AST__LMSTTOGMST:" * in Transform. * 20-MAY-2008 (DSB): * Add conversions between Local Time and UTC (LTTOUTC and UTCTOLT). * 18-JUN-2009 (DSB): * Add OBSALT to argument list for TTTOTDB and TDBTOTT. Change * CLOCKLAT/LON to OBSLAT/LON for consistency with other classes. * 1-SEP-2016 (DSB): * Add 2017 January 1 leap second. *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 TimeMap /* Codes to identify time coordinate conversions. */ #define AST__TIME_NULL 0 /* Null value */ #define AST__MJDTOMJD 1 /* MJD to MJD */ #define AST__MJDTOJD 2 /* MJD to JD */ #define AST__JDTOMJD 3 /* JD to MJD */ #define AST__MJDTOBEP 4 /* MJD to Besselian epoch */ #define AST__BEPTOMJD 5 /* Besselian epoch to MJD */ #define AST__MJDTOJEP 6 /* MJD to Julian epoch */ #define AST__JEPTOMJD 7 /* Julian epoch to MJD */ #define AST__TAITOUTC 8 /* TAI to UTC */ #define AST__UTCTOTAI 9 /* UTC to TAI */ #define AST__TTTOTAI 10 /* TT to TAI */ #define AST__TAITOTT 11 /* TAI to TT */ #define AST__TDBTOTT 12 /* TDB to TT */ #define AST__TTTOTDB 13 /* TT to TDB */ #define AST__TCGTOTT 14 /* TCG to TT */ #define AST__TTTOTCG 15 /* TT to TCG */ #define AST__TCBTOTDB 16 /* TCB to TDB */ #define AST__TDBTOTCB 17 /* TDB to TCB */ #define AST__UTTOGMST 18 /* UT to GMST */ #define AST__GMSTTOUT 19 /* GMST to UT1 */ #define AST__GMSTTOLMST 20 /* GMST to LMST */ #define AST__LMSTTOGMST 21 /* LMST to GMST */ #define AST__LASTTOLMST 22 /* LAST to LMST */ #define AST__LMSTTOLAST 23 /* LMST to LAST */ #define AST__UTTOUTC 24 /* UT1 to UTC */ #define AST__UTCTOUT 25 /* UTC to UT1 */ #define AST__LTTOUTC 26 /* Local Time to UTC */ #define AST__UTCTOLT 27 /* UTC to Local Time */ /* Maximum number of arguments required by a conversion. */ #define MAX_ARGS 6 /* The alphabet (used for generating keywords for arguments). */ #define ALPHABET "abcdefghijklmnopqrstuvwxyz" /* Angle conversion */ #define PI 3.1415926535897932384626433832795028841971693993751 #define D2PI (2*PI) #define PIBY2 (PI/2.0) #define D2R (PI/180.0) #define R2D (180.0/PI) /* Other constants */ #define SPD 86400 #define LG 6.969290134E-10 #define LB 1.55051976772E-8 #define P0 6.55E-5 #define TTOFF 32.184 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "pal.h" /* SLALIB interface */ #include "slamap.h" /* Spatial sla mappings */ #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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "unitmap.h" /* Unit (null) Mappings */ #include "timemap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double (* parent_rate)( AstMapping *, double *, int, int, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(TimeMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(TimeMap,Class_Init) #define class_vtab astGLOBAL(TimeMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstTimeMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstTimeMap *astTimeMapId_( int, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *CvtString( int, const char **, int *, int *, const char *[ MAX_ARGS ], int * ); static double Gmsta( double, double, int, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static double Rcc( double, double, double, double, double, int * ); static int Equal( AstObject *, AstObject *, int * ); static int CvtCode( const char *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void AddArgs( int, double *, int * ); static void AddTimeCvt( AstTimeMap *, int, const double *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void TimeAdd( AstTimeMap *, const char *, const double[], int * ); static int GetObjSize( AstObject *, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two TimeMaps are equivalent. * Type: * Private function. * Synopsis: * #include "timemap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * TimeMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two TimeMaps are equivalent. * Parameters: * this * Pointer to the first Object (a TimeMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the TimeMaps are equivalent, zero otherwise. * 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: */ AstTimeMap *that; AstTimeMap *this; const char *argdesc[ MAX_ARGS ]; const char *comment; int i, j; int nargs; int nin; int nout; int result; int szargs; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two TimeMap structures. */ this = (AstTimeMap *) this_object; that = (AstTimeMap *) that_object; /* Check the second object is a TimeMap. We know the first is a TimeMap since we have arrived at this implementation of the virtual function. */ if( astIsATimeMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two TimeMaps differ, it may still be possible for them to be equivalent. First compare the TimeMaps if their Invert flags are the same. In this case all the attributes of the two TimeMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { if( this->ncvt == that->ncvt ) { result = 1; for( i = 0; i < this->ncvt && result; i++ ) { if( this->cvttype[ i ] != that->cvttype[ i ] ) { result = 0; } else { CvtString( this->cvttype[ i ], &comment, &nargs, &szargs, argdesc, status ); for( j = 0; j < nargs; j++ ) { if( !astEQUAL( this->cvtargs[ i ][ j ], that->cvtargs[ i ][ j ] ) ){ result = 0; break; } } } } } /* If the Invert flags for the two TimeMaps differ, the attributes of the two TimeMaps must be inversely related to each other. */ } else { /* In the specific case of a TimeMap, Invert flags must be equal. */ result = 0; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "timemap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * TimeMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied TimeMap, * in bytes. * Parameters: * this * Pointer to the TimeMap. * 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: */ AstTimeMap *this; /* Pointer to TimeMap structure */ int result; /* Result value to return */ int cvt; /* Loop counter for coordinate conversions */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the TimeMap structure. */ this = (AstTimeMap *) 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 ( cvt = 0; cvt < this->ncvt; cvt++ ) { result += astTSizeOf( this->cvtargs[ cvt ] ); } result += astTSizeOf( this->cvtargs ); result += astTSizeOf( this->cvttype ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void AddArgs( int cvttype, double *cvtargs, int *status ) { /* * Name: * AddArgs * Purpose: * Set values for addition conversion arguments. * Type: * Private function. * Synopsis: * #include "timemap.h" * void AddArgs( int cvttype, double *cvtargs, int *status ) * Class Membership: * TimeMap member function. * Description: * This function stores value for additional conversion arguments, * based on the values supplied for the user arguments. * Parameters: * cvttype * The conversion type. * cvtargs * The arguments for the conversion. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double r; /* Distance from Earth axis (AU) */ double z; /* Distance from plane of Earth equator (AU) */ /* Check the global error status. */ if ( !astOK ) return; /* Test for each valid code value in turn and assign the appropriate extra values. */ switch ( cvttype ) { case AST__MJDTOMJD: cvtargs[ 2 ] = cvtargs[ 0 ] - cvtargs[ 1 ]; break; case AST__MJDTOJD: cvtargs[ 2 ] = cvtargs[ 0 ] - cvtargs[ 1 ] + 2400000.5; break; case AST__JDTOMJD: cvtargs[ 2 ] = cvtargs[ 0 ] - cvtargs[ 1 ] - 2400000.5; break; case AST__MJDTOBEP: cvtargs[ 2 ] = palEpb( cvtargs[ 0 ] ) - palEpb( 0.0 ) - cvtargs[ 1 ]; cvtargs[ 3 ] = palEpb2d( cvtargs[ 1 ] ) - palEpb2d( 0.0 ) - cvtargs[ 0 ]; break; case AST__BEPTOMJD: cvtargs[ 2 ] = palEpb2d( cvtargs[ 0 ] ) - palEpb2d( 0.0 ) - cvtargs[ 1 ]; cvtargs[ 3 ] = palEpb( cvtargs[ 1 ] ) - palEpb( 0.0 ) - cvtargs[ 0 ]; break; case AST__MJDTOJEP: cvtargs[ 2 ] = palEpj( cvtargs[ 0 ] ) - palEpj( 0.0 ) - cvtargs[ 1 ]; cvtargs[ 3 ] = palEpj2d( cvtargs[ 1 ] ) - palEpj2d( 0.0 ) - cvtargs[ 0 ]; break; case AST__JEPTOMJD: cvtargs[ 2 ] = palEpj2d( cvtargs[ 0 ] ) - palEpj2d( 0.0 ) - cvtargs[ 1 ]; cvtargs[ 3 ] = palEpj( cvtargs[ 1 ] ) - palEpj( 0.0 ) - cvtargs[ 0 ]; break; case AST__TTTOTDB: palGeoc( cvtargs[ 2 ], cvtargs[ 3 ], &r, &z ); cvtargs[ 4 ] = 0.001*r*AST__AU; cvtargs[ 5 ] = 0.001*z*AST__AU; break; case AST__TDBTOTT: palGeoc( cvtargs[ 2 ], cvtargs[ 3 ], &r, &z ); cvtargs[ 4 ] = 0.001*r*AST__AU; cvtargs[ 5 ] = 0.001*z*AST__AU; break; case AST__TDBTOTCB: cvtargs[ 1 ] = LB*( cvtargs[ 0 ] - (TTOFF/SPD) - 43144.0 ) + P0/SPD; break; case AST__TCBTOTDB: cvtargs[ 1 ] = LB*( cvtargs[ 0 ] - (TTOFF/SPD) - 43144.0 ) + P0/SPD; break; case AST__TTTOTCG: cvtargs[ 1 ] = LG*( cvtargs[ 0 ] - (TTOFF/SPD) - 43144.0 ); break; case AST__TCGTOTT: cvtargs[ 1 ] = LG*( cvtargs[ 0 ] - (TTOFF/SPD) - 43144.0 ); break; } } static void AddTimeCvt( AstTimeMap *this, int cvttype, const double *args, int *status ) { /* * Name: * AddTimeCvt * Purpose: * Add a coordinate conversion step to an TimeMap. * Type: * Private function. * Synopsis: * #include "timemap.h" * void AddTimeCvt( AstTimeMap *this, int cvttype, const double *args ) * Class Membership: * TimeMap member function. * Description: * This function allows one of the supported time coordinate * conversions to be appended to a TimeMap. When a TimeMap is first * created (using astTimeMap), it simply performs a unit mapping. By * using AddTimeCvt repeatedly, a series of coordinate conversions may * then be specified which the TimeMap will subsequently perform in * sequence. This allows a complex coordinate conversion to be * assembled out of the basic building blocks. The TimeMap will also * perform the inverse coordinate conversion (applying the individual * conversion steps in reverse) if required. * Parameters: * this * Pointer to the TimeMap. * cvttype * A code to identify which time coordinate conversion is to be * appended. See the "Coordinate Conversions" section for details * of those available. * args * Pointer to an array of double containing the argument values * required to fully specify the required coordinate * conversion. The number of arguments depends on the conversion * (see the "Coordinate Conversions" section for details). This * value is ignored and may be NULL if no arguments are required. * Returned Value: * void. * Coordinate Conversions: * The following values may be supplied for the "cvttype" parameter * in order to specify the coordinate conversion to be performed. * The argument(s) required to fully specify each conversion are * indicated in parentheses after each value, and described at the end * of the list. Values for these should be given in the array pointed * at by "args". * * AST__MJDTOMJD( MJDOFF1, MJDOFF2 ) * Convert Modified Julian Date from one offset to another. * AST__MJDTOJD( MJDOFF, JDOFF ) * Convert Modified Julian Date to Julian Date. * AST__JDTOMJD( JDOFF, MJDOFF ) * Convert Julian Date to Modified Julian Date. * AST__MJDTOBEP( MJDOFF, BEPOFF ) * Convert Modified Julian Date to Besselian epoch. * AST__BEPTOMJD( BEPOFF, MJDOFF ) * Convert Besselian epoch to Modified Julian Date. * AST__MJDTOJEP( MJDOFF, JEPOFF ) * Convert Modified Julian Date to Julian epoch. * AST__JEPTOMJD( JEPOFF, MJDOFF ) * Convert Julian epoch to Modified Julian Date. * AST__TAITOUTC( MJDOFF ) * Convert a TAI MJD to a UTC MJD. * AST__UTCTOTAI( MJDOFF ) * Convert a UTC MJD to a TAI MJD. * AST__TAITOTT( MJDOFF ) * Convert a TAI MJD to a TT MJD. * AST__TTTOTAI( MJDOFF ) * Convert a TT MJD to a TAI MJD. * AST__TTTOTDB( MJDOFF, OBSLON, OBSLAT, OBSALT ) * Convert a TT MJD to a TDB MJD. * AST__TDBTOTT( MJDOFF, OBSLON, OBSLAT, OBSALT ) * Convert a TDB MJD to a TT MJD. * AST__TTTOTCG( MJDOFF ) * Convert a TT MJD to a TCG MJD. * AST__TCGTOTT( MJDOFF ) * Convert a TCG MJD to a TT MJD. * AST__TDBTOTCB( MJDOFF) * Convert a TAI MJD to a TCB MJD. * AST__TCBTOTDB( MJDOFF) * Convert a TCB MJD to a TDB MJD. * AST__UTTOGMST( MJDOFF ) * Convert a UT MJD to a GMST MJD. * AST__GMSTTOUT( MJDOFF ) * Convert a GMST MJD to a UT MJD. * AST__GMSTTOLMST( MJDOFF, OBSLON, OBSLAT ) * Convert a GMST MJD to a LMST MJD. * AST__LMSTTOGMST( MJDOFF, OBSLON, OBSLAT ) * Convert a LMST MJD to a GMST MJD. * AST__LASTTOLMST( MJDOFF, OBSLON, OBSLAT ) * Convert a LAST MJD to a LMST MJD. * AST__LMSTTOLAST( MJDOFF, OBSLON, OBSLAT ) * Convert a LMST MJD to a LAST MJD. * AST__UTTOUTC( DUT1 ) * Convert a UT1 MJD to a UTC MJD. * AST__UTCTOUT( DUT1 ) * Convert a UTC MJD to a UT1 MJD. * AST__LTTOUTC( LTOFF ) * Convert a local time MJD to a UTC MJD. * AST__UTCTOLT( LTOFF ) * Convert a UTC MJD to a local time MJD. * * The units for the values processed by the above conversions are as * follows: * * - MJD, MJDOFF, JD, JDOFF: days * - Julian epochs, BEPOFF: Tropical years * - Besselian epochs, JEPOFF: Julian years * * The arguments used in the above conversions are as follows: * * - MJDOFF: Offset to be added to each MJD value * - JDOFF: Offset to be added to each JD value * - JEPOFF: Offset to be added to each Julian epoch value * - BEPOFF: Offset to be added to each Besselian epoch value * - OBSLON: Observer's longitude in radians (+ve westwards) * - OBSLAT: Observer's geodetic latitude in radians (+ve northwards) * - OBSALT: Observer's geodetic altitude in metres. * - DUT1: The value of UT1-UTC * - LTOFF: The offset between Local Time and UTC (in hours, positive * for time zones east of Greenwich). * Notes: * - The specified conversion is appended only if the TimeMap's * Invert attribute is zero. If it is non-zero, this function * effectively prefixes the inverse of the conversion specified * instead. */ /* Local Variables: */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ const char *cvt_string; /* Pointer to conversion type string */ int i; /* Argument index */ int nargs; /* Number of user-supplied arguments */ int ncvt; /* Number of coordinate conversions */ int szargs; /* Size of arguments array */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the coordinate conversion type and obtain the number of required user-supplied arguments, and the size of the array in which to put the user-supplied arguments (the array may leave room after the user-supplied arguments for various useful pre-calculated values). */ cvt_string = CvtString( cvttype, &comment, &nargs, &szargs, argdesc, status ); /* If the coordinate conversion type was not valid, then report an error. */ if ( astOK && !cvt_string ) { astError( AST__TIMIN, "AddTimeCvt(%s): Invalid time coordinate " "conversion type (%d).", status, astGetClass( this ), (int) cvttype ); } /* Note the number of coordinate conversions already stored in the TimeMap. */ if ( astOK ) { ncvt = this->ncvt; /* Extend the array of conversion types and the array of pointers to their argument lists to accommodate the new one. */ this->cvttype = (int *) astGrow( this->cvttype, ncvt + 1, sizeof( int ) ); this->cvtargs = (double **) astGrow( this->cvtargs, ncvt + 1, sizeof( double * ) ); /* Allocate memory for the argument list, putting a pointer to it into the TimeMap. */ this->cvtargs[ ncvt ] = astMalloc( sizeof( double ) * (size_t) szargs ); /* Store the conversion type and increment the conversion count. Also copy the supplied arguments into the memory allocated above and put suitable values in any elements of the argument array which are beyond the end of the user-supplied arguments. These are intermediate values calculated on the basis of the user-supplied arguments. */ if ( astOK ) { this->cvttype[ ncvt ] = cvttype; for( i = 0; i < nargs; i++ ) this->cvtargs[ ncvt ][ i ] = args[ i ]; for( i = nargs; i < szargs; i++ ) this->cvtargs[ ncvt ][ i ] = AST__BAD; this->ncvt++; /* Test for each valid code value in turn and assign the appropriate extra values. */ AddArgs( cvttype, this->cvtargs[ ncvt ], status ); } } } static int CvtCode( const char *cvt_string, int *status ) { /* * Name: * CvtCode * Purpose: * Convert a conversion type from a string representation to a code value. * Type: * Private function. * Synopsis: * #include "timemap.h" * int CvtCode( const char *cvt_string, int *status ) * Class Membership: * TimeMap member function. * Description: * This function accepts a string used to repersent one of the * TimeMap coordinate conversions and converts it into a code * value for internal use. * Parameters: * cvt_string * Pointer to a constant null-terminated string representing a * time coordinate conversion. This is case sensitive and should * contain no unnecessary white space. * status * Pointer to the inherited status variable. * Returned Value: * The equivalent conversion code. If the string was not * recognised, the code AST__TIME_NULL is returned, without error. * Notes: * - A value of AST__TIME_NULL will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ int result; /* Result value to return */ /* Initialise. */ result = AST__TIME_NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Test the string against each recognised value in turn and assign the result. */ if ( astChrMatch( cvt_string, "MJDTOJD" ) ) { result = AST__MJDTOJD; } else if ( astChrMatch( cvt_string, "MJDTOMJD" ) ) { result = AST__MJDTOMJD; } else if ( astChrMatch( cvt_string, "JDTOMJD" ) ) { result = AST__JDTOMJD; } else if ( astChrMatch( cvt_string, "JDTOMJD" ) ) { result = AST__JDTOMJD; } else if ( astChrMatch( cvt_string, "MJDTOBEP" ) ) { result = AST__MJDTOBEP; } else if ( astChrMatch( cvt_string, "BEPTOMJD" ) ) { result = AST__BEPTOMJD; } else if ( astChrMatch( cvt_string, "MJDTOJEP" ) ) { result = AST__MJDTOJEP; } else if ( astChrMatch( cvt_string, "JEPTOMJD" ) ) { result = AST__JEPTOMJD; } else if ( astChrMatch( cvt_string, "TAITOUTC" ) ) { result = AST__TAITOUTC; } else if ( astChrMatch( cvt_string, "UTCTOTAI" ) ) { result = AST__UTCTOTAI; } else if ( astChrMatch( cvt_string, "TAITOTT" ) ) { result = AST__TAITOTT; } else if ( astChrMatch( cvt_string, "TTTOTAI" ) ) { result = AST__TTTOTAI; } else if ( astChrMatch( cvt_string, "TTTOTDB" ) ) { result = AST__TTTOTDB; } else if ( astChrMatch( cvt_string, "TDBTOTT" ) ) { result = AST__TDBTOTT; } else if ( astChrMatch( cvt_string, "TTTOTCG" ) ) { result = AST__TTTOTCG; } else if ( astChrMatch( cvt_string, "TCGTOTT" ) ) { result = AST__TCGTOTT; } else if ( astChrMatch( cvt_string, "TDBTOTCB" ) ) { result = AST__TDBTOTCB; } else if ( astChrMatch( cvt_string, "TCBTOTDB" ) ) { result = AST__TCBTOTDB; } else if ( astChrMatch( cvt_string, "UTTOGMST" ) ) { result = AST__UTTOGMST; } else if ( astChrMatch( cvt_string, "GMSTTOUT" ) ) { result = AST__GMSTTOUT; } else if ( astChrMatch( cvt_string, "GMSTTOLMST" ) ) { result = AST__GMSTTOLMST; } else if ( astChrMatch( cvt_string, "LMSTTOGMST" ) ) { result = AST__LMSTTOGMST; } else if ( astChrMatch( cvt_string, "LASTTOLMST" ) ) { result = AST__LASTTOLMST; } else if ( astChrMatch( cvt_string, "LMSTTOLAST" ) ) { result = AST__LMSTTOLAST; } else if ( astChrMatch( cvt_string, "UTTOUTC" ) ) { result = AST__UTTOUTC; } else if ( astChrMatch( cvt_string, "UTCTOUT" ) ) { result = AST__UTCTOUT; } else if ( astChrMatch( cvt_string, "LTTOUTC" ) ) { result = AST__LTTOUTC; } else if ( astChrMatch( cvt_string, "UTCTOLT" ) ) { result = AST__UTCTOLT; } /* Return the result. */ return result; } static const char *CvtString( int cvt_code, const char **comment, int *nargs, int *szargs, const char *arg[ MAX_ARGS ], int *status ) { /* * Name: * CvtString * Purpose: * Convert a conversion type from a code value to a string representation. * Type: * Private function. * Synopsis: * #include "timemap.h" * const char *CvtString( int cvt_code, const char **comment, int *nargs, * int *szargs, const char *arg[ MAX_ARGS ], int *status ) * Class Membership: * TimeMap member function. * Description: * This function accepts a code value used to represent one of the * TimeMap coordinate conversions and converts it into an * equivalent string representation. It also returns a descriptive * comment and information about the arguments required in order to * perform the conversion. * Parameters: * cvt_code * The conversion code. * comment * Address of a location to return a pointer to a constant * null-terminated string containing a description of the * conversion. * nargs * Address of an int in which to return the number of arguments * required from the user in order to perform the conversion (may * be zero). * szargs * Address of an int in which to return the number of arguments * associated with the conversion. This may be bigger than "nargs" * if the conversion can pre-calculate useful values on the basis * of the user-supplied values. Such precalculated values are * stored after the last user-supplied argument. * arg * An array in which to return a pointer to a constant * null-terminated string for each argument (above) containing a * description of what each argument represents. This includes both * user-supplied arguments and pre-calculated values. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated string representation of * the conversion code value supplied. If the code supplied is not * valid, a NULL pointer will be returned, without error. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Result pointer to return */ /* Initialise the returned values. */ *comment = NULL; *nargs = 0; result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Test for each valid code value in turn and assign the appropriate return values. */ switch ( cvt_code ) { case AST__MJDTOMJD: *comment = "Convert MJD between offsets"; result = "MJDTOMJD"; *nargs = 2; *szargs = 3; arg[ 0 ] = "Input MJD offset"; arg[ 1 ] = "Output MJD offset"; arg[ 2 ] = "Combined offset"; break; case AST__MJDTOJD: *comment = "Convert MJD to JD"; result = "MJDTOJD"; *nargs = 2; *szargs = 3; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "JD offset"; arg[ 2 ] = "Combined offset"; break; case AST__JDTOMJD: *comment = "Convert JD to MJD"; result = "JDTOMJD"; *nargs = 2; *szargs = 3; arg[ 0 ] = "JD offset"; arg[ 1 ] = "MJD offset"; arg[ 2 ] = "Combined offset"; break; case AST__MJDTOBEP: *comment = "Convert MJD to Besselian epoch"; result = "MJDTOBEP"; *nargs = 2; *szargs = 4; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Besselian epoch offset"; arg[ 2 ] = "Combined forward offset"; arg[ 3 ] = "Combined inverse offset"; break; case AST__BEPTOMJD: *comment = "Convert Besselian epoch to MJD"; result = "BEPTOMJD"; *nargs = 2; *szargs = 4; arg[ 0 ] = "Besselian epoch offset"; arg[ 1 ] = "MJD offset"; arg[ 2 ] = "Combined forward offset"; arg[ 3 ] = "Combined inverse offset"; break; case AST__MJDTOJEP: *comment = "Convert MJD to Julian epoch"; result = "MJDTOJEP"; *nargs = 2; *szargs = 4; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Julian epoch offset"; arg[ 2 ] = "Combined forward offset"; arg[ 3 ] = "Combined inverse offset"; break; case AST__JEPTOMJD: *comment = "Convert Julian epoch to MJD"; result = "JEPTOMJD"; *nargs = 2; *szargs = 4; arg[ 0 ] = "Julian epoch offset"; arg[ 1 ] = "MJD offset"; arg[ 2 ] = "Combined forward offset"; arg[ 3 ] = "Combined inverse offset"; break; case AST__TAITOUTC: *comment = "Convert TAI to UTC"; result = "TAITOUTC"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__UTCTOTAI: *comment = "Convert UTC to TAI"; result = "UTCTOTAI"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__TAITOTT: *comment = "Convert TAI to TT"; result = "TAITOTT"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__TTTOTAI: *comment = "Convert TT to TAI"; result = "TTTOTAI"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__TTTOTDB: *comment = "Convert TT to TDB"; result = "TTTOTDB"; *nargs = 4; *szargs = 6; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; arg[ 3 ] = "Observer altitude"; arg[ 4 ] = "Distance from earth spin axis"; arg[ 5 ] = "Distance north of equatorial plane"; break; case AST__TDBTOTT: *comment = "Convert TDB to TT"; result = "TDBTOTT"; *nargs = 4; *szargs = 6; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; arg[ 3 ] = "Observer altitude"; arg[ 4 ] = "Distance from earth spin axis"; arg[ 5 ] = "Distance north of equatorial plane"; break; case AST__TTTOTCG: *comment = "Convert TT to TCG"; result = "TTTOTCG"; *nargs = 1; *szargs = 2; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "TCG offset"; break; case AST__TCGTOTT: *comment = "Convert TCG to TT"; result = "TCGTOTT"; *nargs = 1; *szargs = 2; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "TCG offset"; break; case AST__TDBTOTCB: *comment = "Convert TDB to TCB"; result = "TDBTOTCB"; *nargs = 1; *szargs = 2; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "TCB offset"; break; case AST__TCBTOTDB: *comment = "Convert TCB to TDB"; result = "TCBTOTDB"; *nargs = 1; *szargs = 2; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "TCB offset"; break; case AST__UTTOGMST: *comment = "Convert UT to GMST"; result = "UTTOGMST"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__GMSTTOUT: *comment = "Convert GMST to UT"; result = "GMSTTOUT"; *nargs = 1; *szargs = 1; arg[ 0 ] = "MJD offset"; break; case AST__GMSTTOLMST: *comment = "Convert GMST to LMST"; result = "GMSTTOLMST"; *nargs = 3; *szargs = 3; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; break; case AST__LMSTTOGMST: *comment = "Convert LMST to GMST"; result = "LMSTTOGMST"; *nargs = 3; *szargs = 3; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; break; case AST__LASTTOLMST: *comment = "Convert LAST to LMST"; result = "LASTTOLMST"; *nargs = 3; *szargs = 3; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; break; case AST__LMSTTOLAST: *comment = "Convert LMST to LAST"; result = "LMSTTOLAST"; *nargs = 3; *szargs = 3; arg[ 0 ] = "MJD offset"; arg[ 1 ] = "Observer longitude"; arg[ 2 ] = "Observer latitude"; break; case AST__UTTOUTC: *comment = "Convert UT1 to UTC"; result = "UTTOUTC"; *nargs = 1; *szargs = 1; arg[ 0 ] = "DUT1"; break; case AST__UTCTOUT: *comment = "Convert UTC to UT1"; result = "UTCTOUT"; *nargs = 1; *szargs = 1; arg[ 0 ] = "DUT1"; break; case AST__LTTOUTC: *comment = "Convert Local Time to UTC"; result = "LTTOUTC"; *nargs = 1; *szargs = 1; arg[ 0 ] = "LTOFF"; break; case AST__UTCTOLT: *comment = "Convert UTC to Local Time"; result = "UTCTOLT"; *nargs = 1; *szargs = 1; arg[ 0 ] = "LTOFF"; break; } /* Return the result. */ return result; } double astDat_( double in, int forward, int *status ){ /* *+ * Name: * Dat * Purpose: * Convert between UTC and TAI. * Type: * Protected function. * Synopsis: * #include "timemap.h" * double astDat( double in, int forward ) * Class Membership: * TimeMap member function * Description: * This function returns the difference between Coordinated Universal Time * (UTC) and International Atomic Time (TAI), at a given epoch. * Parameters: * in * UTC date or TAI time (as selected by "forward"), as an absolute * MJD. * forward * If non-zero, "in" should be a UTC value, and the returned value * is TAI-UTC. If zero, "in" should be a TAI value, and the returned * value is UTC-TAI. * Returned Value: * Either UTC-TAI or TAI-UTC (as indicated by "forward") in units of * seconds. * Notes: * - The UTC is specified to be a date rather than a time to indicate * that care needs to be taken not to specify an instant which lies * within a leap second. Though in most cases UTC can include the * fractional part, correct behaviour on the day of a leap second * can only be guaranteed up to the end of the second 23:59:59. * - For epochs from 1961 January 1 onwards, the expressions from the * file ftp://maia.usno.navy.mil/ser7/tai-utc.dat are used. * - The 5ms time step at 1961 January 1 is taken from 2.58.1 (p87) of * the 1992 Explanatory Supplement. * - UTC began at 1960 January 1.0 (JD 2436934.5) and it is improper * to call the routine with an earlier epoch. However, if this * is attempted, the TAI-UTC expression for the year 1960 is used. * Implementation Details: * - This function is based on SLA_DAT by P.T.Wallace. * - This routine must be updated on each occasion that a leap second is * announced * - Latest leap second: 2017 January 1 *- */ /* Local Variables: */ double result; /* Initialise the returned value. */ if( in == AST__BAD ) return AST__BAD; /* First do TAI-UTC at a given UTC ------------------------------- */ if( forward ) { /* 2017 January 1 */ if ( in >= 57754.0 ) { result = 37.0; /* 2015 July 1 */ } else if ( in >= 57204.0 ) { result = 36.0; /* 2012 July 1 */ } else if ( in >= 56109.0 ) { result = 35.0; /* 2009 January 1 */ } else if ( in >= 54832.0 ) { result = 34.0; /* 2006 January 1 */ } else if( in >= 53736.0 ) { result = 33.0; /* 1999 January 1 */ } else if( in >= 51179.0 ){ result = 32.0; /* 1997 July 1 */ } else if( in >= 50630.0 ){ result = 31.0; /* 1996 January 1 */ } else if( in >= 50083.0 ){ result = 30.0; /* 1994 July 1 */ } else if( in >= 49534.0 ){ result = 29.0; /* 1993 July 1 */ } else if( in >= 49169.0 ){ result = 28.0; /* 1992 July 1 */ } else if( in >= 48804.0 ){ result = 27.0; /* 1991 January 1 */ } else if( in >= 48257.0 ){ result = 26.0; /* 1990 January 1 */ } else if( in >= 47892.0 ){ result = 25.0; /* 1988 January 1 */ } else if( in >= 47161.0 ){ result = 24.0; /* 1985 July 1 */ } else if( in >= 46247.0 ){ result = 23.0; /* 1983 July 1 */ } else if( in >= 45516.0 ){ result = 22.0; /* 1982 July 1 */ } else if( in >= 45151.0 ){ result = 21.0; /* 1981 July 1 */ } else if( in >= 44786.0 ){ result = 20.0; /* 1980 January 1 */ } else if( in >= 44239.0 ){ result = 19.0; /* 1979 January 1 */ } else if( in >= 43874.0 ){ result = 18.0; /* 1978 January 1 */ } else if( in >= 43509.0 ){ result = 17.0; /* 1977 January 1 */ } else if( in >= 43144.0 ){ result = 16.0; /* 1976 January 1 */ } else if( in >= 42778.0 ){ result = 15.0; /* 1975 January 1 */ } else if( in >= 42413.0 ){ result = 14.0; /* 1974 January 1 */ } else if( in >= 42048.0 ){ result = 13.0; /* 1973 January 1 */ } else if( in >= 41683.0 ){ result = 12.0; /* 1972 July 1 */ } else if( in >= 41499.0 ){ result = 11.0; /* 1972 January 1 */ } else if( in >= 41317.0 ){ result = 10.0; /* 1968 February 1 */ } else if( in >= 39887.0 ){ result = 4.2131700 + ( in - 39126.0 )*0.002592; /* 1966 January 1 */ } else if( in >= 39126.0 ){ result = 4.3131700 + ( in - 39126.0 )*0.002592; /* 1965 September 1 */ } else if( in >= 39004.0 ){ result = 3.8401300 + ( in - 38761.0 )*0.001296; /* 1965 July 1 */ } else if( in >= 38942.0 ){ result = 3.7401300 + ( in - 38761.0 )*0.001296; /* 1965 March 1 */ } else if( in >= 38820.0 ){ result = 3.6401300 + ( in - 38761.0 )*0.001296; /* 1965 January 1 */ } else if( in >= 38761.0 ){ result = 3.5401300 + ( in - 38761.0 )*0.001296; /* 1964 September 1 */ } else if( in >= 38639.0 ){ result = 3.4401300 + ( in - 38761.0 )*0.001296; /* 1964 April 1 */ } else if( in >= 38486.0 ){ result = 3.3401300 + ( in - 38761.0 )*0.001296; /* 1964 January 1 */ } else if( in >= 38395.0 ){ result = 3.2401300 + ( in - 38761.0 )*0.001296; /* 1963 November 1 */ } else if( in >= 38334.0 ){ result = 1.9458580 + ( in - 37665.0 )*0.0011232; /* 1962 January 1 */ } else if( in >= 37665.0 ){ result = 1.8458580 + ( in - 37665.0 )*0.0011232; /* 1961 August 1 */ } else if( in >= 37512.0 ){ result = 1.3728180 + ( in - 37300.0 )*0.001296; /* 1961 January 1 */ } else if( in >= 37300.0 ){ result = 1.4228180 + ( in - 37300.0 )*0.001296; /* Before that */ } else { result = 1.4178180 + ( in - 37300.0 )*0.001296; } /* Now do UTC-TAI at a given TAI. ------------------------------ */ } else { /* 2017 January 1 */ if ( in >= 57754.0 + 37.0/SPD ) { result = -37.0; /* 2015 July 1 */ } else if ( in >= 57204.0 + 36.0/SPD ) { result = -36.0; /* 2012 July 1 */ } else if( in >= 56109.0 + 35.0/SPD ) { result = -35.0; /* 2009 January 1 */ } else if( in >= 54832.0 + 34.0/SPD ) { result = -34.0; /* 2006 January 1 */ } else if( in >= 53736.0 + 33.0/SPD ){ result = -33.0; /* 1999 January 1 */ } else if( in >= 51179.0 + 32.0/SPD ){ result = -32.0; /* 1997 July 1 */ } else if( in >= 50630.0 + 31.0/SPD ){ result = -31.0; /* 1996 January 1 */ } else if( in >= 50083.0 + 30.0/SPD ){ result = -30.0; /* 1994 July 1 */ } else if( in >= 49534.0 + 29.0/SPD ){ result = -29.0; /* 1993 July 1 */ } else if( in >= 49169.0 + 28.0/SPD ){ result = -28.0; /* 1992 July 1 */ } else if( in >= 48804.0 + 27.0/SPD ){ result = -27.0; /* 1991 January 1 */ } else if( in >= 48257.0 + 26.0/SPD ){ result = -26.0; /* 1990 January 1 */ } else if( in >= 47892.0 + 25.0/SPD ){ result = -25.0; /* 1988 January 1 */ } else if( in >= 47161.0 + 24.0/SPD ){ result = -24.0; /* 1985 July 1 */ } else if( in >= 46247.0 + 23.0/SPD ){ result = -23.0; /* 1983 July 1 */ } else if( in >= 45516.0 + 22.0/SPD ){ result = -22.0; /* 1982 July 1 */ } else if( in >= 45151.0 + 21.0/SPD ){ result = -21.0; /* 1981 July 1 */ } else if( in >= 44786.0 + 20.0/SPD ){ result = -20.0; /* 1980 January 1 */ } else if( in >= 44239.0 + 19.0/SPD ){ result = -19.0; /* 1979 January 1 */ } else if( in >= 43874.0 + 18.0/SPD ){ result = -18.0; /* 1978 January 1 */ } else if( in >= 43509.0 + 17.0/SPD ){ result = -17.0; /* 1977 January 1 */ } else if( in >= 43144.0 + 16.0/SPD ){ result = -16.0; /* 1976 January 1 */ } else if( in >= 42778.0 + 15.0/SPD ){ result = -15.0; /* 1975 January 1 */ } else if( in >= 42413.0 + 14.0/SPD ){ result = -14.0; /* 1974 January 1 */ } else if( in >= 42048.0 + 13.0/SPD ){ result = -13.0; /* 1973 January 1 */ } else if( in >= 41683.0 + 12.0/SPD ){ result = -12.0; /* 1972 July 1 */ } else if( in >= 41499.0 + 11.0/SPD ){ result = -11.0; /* 1972 January 1 */ } else if( in >= 41317.0 + 10.0/SPD ){ result = -10.0; /* 1968 February 1 */ } else if( in >= 39887.0 + ( 4.2131700 + ( 39887.0 - 39126.0 )*0.002592 )/SPD ){ result = -( 4.2131700 + ( in - 39126.0 )*0.002592 )/1.02592; /* 1966 January 1 */ } else if( in >= 39126.0 + ( 4.3131700 + ( 39126.0 - 39126.0 )*0.002592 )/SPD ){ result = -( 4.2131700 + ( in - 39126.0 )*0.002592 )/1.02592; /* 1965 September 1 */ } else if( in >= 39004.0 + ( 3.8401300 + ( 39004.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.8401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1965 July 1 */ } else if( in >= 38942.0 + ( 3.7401300 + ( 38942.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.7401300 + ( in - 38761.0 )*0.001296 )/1.01296; /* 1965 March 1 */ } else if( in >= 38820.0 + ( 3.6401300 + ( 38820.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.6401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1965 January 1 */ } else if( in >= 38761.0 + ( 3.5401300 + ( 38761.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.5401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1964 September 1 */ } else if( in >= 38639.0 + ( 3.4401300 + ( 38639.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.4401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1964 April 1 */ } else if( in >= 38486.0 + ( 3.3401300 + ( 38486.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.3401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1964 January 1 */ } else if( in >= 38395.0 + ( 3.2401300 + ( 38395.0 - 38761.0 )*0.001296 )/SPD ){ result = -( 3.2401300 + ( in - 38761.0 )*0.001296 )/1.001296; /* 1963 November 1 */ } else if( in >= 38334.0 + ( 1.9458580 + ( 38334.0 - 37665.0 )*0.0011232 )/SPD ){ result = -( 1.9458580 + ( in - 37665.0 )*0.0011232 )/1.0011232; /* 1962 January 1 */ } else if( in >= 37665.0 + ( 1.8458580 + ( 37665.0 - 37665.0 )*0.0011232 )/SPD ){ result = -( 1.8458580 + ( in - 37665.0 )*0.0011232 )/1.0011232; /* 1961 August 1 */ } else if( in >= 37512.0 + ( 1.3728180 + ( 37512.0 - 37300.0 )*0.001296 )/SPD ){ result = -( 1.3728180 + ( in - 37300.0 )*0.001296 )/1.001296; /* 1961 January 1 */ } else if( in >= 37300.0 + ( 1.4228180 + ( 37300.0 - 37300.0 )*0.001296 )/SPD ){ result = -( 1.4228180 + ( in - 37300.0 )*0.001296 )/1.001296; /* Before that */ } else { result = -( 1.4178180 + ( in - 37300.0 )*0.001296 )/1.001296; } } /* Return the result */ return result; } static double Gmsta( double in, double off, int forward, int *status ){ /* * Name: * Gmsta * Purpose: * Convert between Universal Time (UT) and Greenwich Mean Sidereal Time (GMST). * Type: * Private function. * Synopsis: * #include "timemap.h" * double Gmsta( double in, double off, int forward, int *status ){ * Class Membership: * TimeMap member function * Description: * This functions converts between UT and GMST. Both timescales are * represented by an MJD, rather than as an angle (as is done by SLALIB) * in order to facilitate conversions from GMST to UT1. This means * that whole days are retained. * Parameters: * in * The time to convert, represented as an offset in days from the MJD * zero-point specified by "off". The time is either UT1 or GMST, as * selected by "forward"). * off * The MJD value corresponding to a value of 0.0 for "in". * forward * If non-zero, "in" should be a UT1 value, and the returned value * is GMST. If zero, "in" should be a GMST value, and the returned * value is UT1. * status * Pointer to the inherited status variable. * Returned Value: * An offset in days from the MJD given by "off". When the returned * value is added to "off" the sum is a GMST MJD (if "forward" is * non-zero), or a UT1 MJD (if "forward" is zero), * Notes: * - This function is based on SLA_GMST by P.T.Wallace. */ /* Local Variables: */ double dgdu; double g; double result; double t; double utl; int nit; /* Initialise the returned value. */ if( in == AST__BAD || off == AST__BAD ) return AST__BAD; /* First deal with UT1 -> GMST --------------------------- */ if( forward ) { /* Julian centuries since J2000. */ t = ( off + in - 51544.5 )/36525.0; /* GMST at this UT1. */ result = in + ( 24110.54841 + ( 8640184.812866 + ( 0.093104 - 6.2E-6*t )*t )*t )/86400.0; /* Now deal with GMST -> UT1 ----------------------- */ } else { /* Form an initial guess at the UT1 value using the inverse of a linear approximation to the UT1->GMST equation. */ result = 0.996997348638869*in + 154.49194372222 - 0.00300265136113098*off; /* Loop round improving the guess, until the guess stops changing, or 10 iterations have been performed. */ utl = AST__BAD; nit = 0; while( result != utl && nit++ < 10 ){ /* Calculate the GMST at the current UT1 guess. */ t = ( off + result - 51544.5 )/36525.0; g = result + ( 24110.54841 + ( 8640184.812866 + ( 0.093104 - 6.2E-6*t )*t )*t )/86400.0; /* Calculate the rate of change of GMST with respect to UT1 at the current UT1 guess. */ dgdu = 1.0 + ( 8640184.812866 + ( 0.186208 - 12.4E-6*t )*t)/(36525.0*86400.0); /* Improve the UT1 guess. */ utl = result; result = result - ( g - in )/dgdu; } } /* Return the result */ return result; } void astInitTimeMapVtab_( AstTimeMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTimeMapVtab * Purpose: * Initialise a virtual function table for a TimeMap. * Type: * Protected function. * Synopsis: * #include "timemap.h" * void astInitTimeMapVtab( AstTimeMapVtab *vtab, const char *name ) * Class Membership: * TimeMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the TimeMap 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 */ 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. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsATimeMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->TimeAdd = TimeAdd; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_rate = mapping->Rate; mapping->Rate = Rate; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "TimeMap", "Conversion between time 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a TimeMap. * Type: * Private function. * Synopsis: * #include "mapping.h * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * TimeMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated TimeMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated TimeMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated TimeMap which is to be merged with * its neighbours. This should be a cloned copy of the TimeMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * TimeMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated TimeMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *new; /* Pointer to replacement Mapping */ AstTimeMap *timemap; /* Pointer to TimeMap */ const char *argdesc[ MAX_ARGS ]; /* Argument descriptions (junk) */ const char *class; /* Pointer to Mapping class string */ const char *comment; /* Pointer to comment string (junk) */ double (*cvtargs)[ MAX_ARGS ]; /* Pointer to argument arrays */ double tmp; /* Temporary storage */ int *cvttype; /* Pointer to transformation type codes */ int *szarg; /* Pointer to argument count array */ int done; /* Finished (no further simplification)? */ int iarg; /* Loop counter for arguments */ int icvt1; /* Loop initial value */ int icvt2; /* Loop final value */ int icvt; /* Loop counter for transformation steps */ int ikeep; /* Index to store step being kept */ int imap1; /* Index of first TimeMap to merge */ int imap2; /* Index of last TimeMap to merge */ int imap; /* Loop counter for Mappings */ int inc; /* Increment for transformation step loop */ int invert; /* TimeMap applied in inverse direction? */ int istep; /* Loop counter for transformation steps */ int keep; /* Keep transformation step? */ int narg; /* Number of user-supplied arguments */ int ngone; /* Number of Mappings eliminated */ int nstep0; /* Original number of transformation steps */ int nstep; /* Total number of transformation steps */ int result; /* Result value to return */ int simpler; /* Simplification possible? */ int unit; /* Replacement Mapping is a UnitMap? */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* TimeMaps can only be merged if they are in series (or if there is only one Mapping present, in which case it makes no difference), so do nothing if they are not. */ if ( series || ( *nmap == 1 ) ) { /* Initialise the number of transformation steps to be merged to equal the number in the nominated TimeMap. */ nstep = ( (AstTimeMap *) ( *map_list )[ where ] )->ncvt; /* Search adjacent lower-numbered Mappings until one is found which is not a TimeMap. Accumulate the number of transformation steps involved in any TimeMaps found. */ imap1 = where; while ( ( imap1 - 1 >= 0 ) && astOK ) { class = astGetClass( ( *map_list )[ imap1 - 1 ] ); if ( !astOK || strcmp( class, "TimeMap" ) ) break; nstep += ( (AstTimeMap *) ( *map_list )[ imap1 - 1 ] )->ncvt; imap1--; } /* Similarly search adjacent higher-numbered Mappings. */ imap2 = where; while ( ( imap2 + 1 < *nmap ) && astOK ) { class = astGetClass( ( *map_list )[ imap2 + 1 ] ); if ( !astOK || strcmp( class, "TimeMap" ) ) break; nstep += ( (AstTimeMap *) ( *map_list )[ imap2 + 1 ] )->ncvt; imap2++; } /* Remember the initial number of transformation steps. */ nstep0 = nstep; /* Allocate memory for accumulating a list of all the transformation steps involved in all the TimeMaps found. */ cvttype = astMalloc( sizeof( int ) * (size_t) nstep ); cvtargs = astMalloc( sizeof( double[ MAX_ARGS ] ) * (size_t) nstep ); szarg = astMalloc( sizeof( int ) * (size_t) nstep ); /* Loop to obtain the transformation data for each TimeMap being merged. */ nstep = 0; for ( imap = imap1; astOK && ( imap <= imap2 ); imap++ ) { /* Obtain a pointer to the TimeMap and note if it is being applied in its inverse direction. */ timemap = (AstTimeMap *) ( *map_list )[ imap ]; invert = ( *invert_list )[ imap ]; /* Set up loop limits and an increment to scan the transformation steps in each TimeMap in either the forward or reverse direction, as dictated by the associated "invert" value. */ icvt1 = invert ? timemap->ncvt - 1 : 0; icvt2 = invert ? -1 : timemap->ncvt; inc = invert ? -1 : 1; /* Loop through each transformation step in the TimeMap. */ for ( icvt = icvt1; icvt != icvt2; icvt += inc ) { /* Store the transformation type code and use "CvtString" to determine the associated number of arguments. Then store these arguments. */ cvttype[ nstep ] = timemap->cvttype[ icvt ]; (void) CvtString( cvttype[ nstep ], &comment, &narg, szarg + nstep, argdesc, status ); if ( !astOK ) break; for ( iarg = 0; iarg < szarg[ nstep ]; iarg++ ) { cvtargs[ nstep ][ iarg ] = timemap->cvtargs[ icvt ][ iarg ]; } /* If the TimeMap is inverted, we must not only accumulate its transformation steps in reverse, but also apply them in reverse. For some steps this means changing arguments, for some it means changing the transformation type code to a complementary value, and for others it means both. Define macros to perform each of the required changes. */ /* Macro to exchange a transformation type code for its inverse (and vice versa). */ #define SWAP_CODES( code1, code2 ) \ if ( cvttype[ nstep ] == code1 ) { \ cvttype[ nstep ] = code2; \ AddArgs( code2, cvtargs[ nstep ], status ); \ } else if ( cvttype[ nstep ] == code2 ) { \ cvttype[ nstep ] = code1; \ AddArgs( code1, cvtargs[ nstep ], status ); \ } /* Macro to exchange a transformation type code for its inverse (and vice versa), and swap the order of its 2 arguments. */ #define SWAP_CODES2( code1, code2 ) \ if ( cvttype[ nstep ] == code1 ) { \ cvttype[ nstep ] = code2; \ tmp = cvtargs[ nstep ][ 0 ]; \ cvtargs[ nstep ][ 0 ] = cvtargs[ nstep ][ 1 ]; \ cvtargs[ nstep ][ 1 ] = tmp; \ AddArgs( cvttype[ nstep ], cvtargs[ nstep ], status ); \ } else if ( cvttype[ nstep ] == code2 ) { \ cvttype[ nstep ] = code1; \ tmp = cvtargs[ nstep ][ 0 ]; \ cvtargs[ nstep ][ 0 ] = cvtargs[ nstep ][ 1 ]; \ cvtargs[ nstep ][ 1 ] = tmp; \ AddArgs( cvttype[ nstep ], cvtargs[ nstep ], status ); \ } /* Use these macros to apply the changes where needed. */ if ( invert ) { /* Exchange transformation codes for their inverses. */ SWAP_CODES( AST__TAITOUTC, AST__UTCTOTAI ) SWAP_CODES( AST__TAITOTT, AST__TTTOTAI ) SWAP_CODES( AST__TTTOTDB, AST__TDBTOTT ) SWAP_CODES( AST__TDBTOTCB, AST__TCBTOTDB ) SWAP_CODES( AST__TTTOTCG, AST__TCGTOTT ) SWAP_CODES( AST__UTTOGMST, AST__GMSTTOUT ) SWAP_CODES( AST__GMSTTOLMST, AST__LMSTTOGMST ) SWAP_CODES( AST__LASTTOLMST, AST__LMSTTOLAST ) SWAP_CODES( AST__UTTOUTC, AST__UTCTOUT ) SWAP_CODES( AST__LTTOUTC, AST__UTCTOLT ) /* Exchange transformation codes for their inverses, and swap the offset values. */ SWAP_CODES2( AST__MJDTOMJD, AST__MJDTOMJD ) SWAP_CODES2( AST__MJDTOJD, AST__JDTOMJD ) SWAP_CODES2( AST__MJDTOBEP, AST__BEPTOMJD ) SWAP_CODES2( AST__MJDTOJEP, AST__JEPTOMJD ) } /* Undefine the local macros. */ #undef SWAP_CODES #undef SWAP_CODES2 /* Count the transformation steps. */ nstep++; } } /* Loop to simplify the sequence of transformation steps until no further improvement is possible. */ done = 0; while ( astOK && !done ) { /* Examine each remaining transformation step in turn. */ ikeep = -1; for ( istep = 0; istep < nstep; istep++ ) { /* Initially assume we will retain the current step. */ keep = 1; /* We can eliminate changes of system which have no effect. */ if( ( cvttype[ istep ] == AST__MJDTOMJD || cvttype[ istep ] == AST__MJDTOJD || cvttype[ istep ] == AST__JDTOMJD ) && cvtargs[ istep ][ 2 ] == 0.0 ) { keep = 0; /* The only simplifications for the conversions currently in this class act to combine adjacent transformation steps, so only apply them while there are at least 2 steps left. */ } else if ( istep < ( nstep - 1 ) ) { /* Define a macro to test if two adjacent transformation type codes have specified values. */ #define PAIR_CVT( code1, code2 ) \ ( ( cvttype[ istep ] == code1 ) && \ ( cvttype[ istep + 1 ] == code2 ) ) /* Define a macro to test if two adjacent transformation type codes have specified values, either way round. */ #define PAIR_CVT2( code1, code2 ) \ ( ( PAIR_CVT( code1, code2 ) ) || \ ( PAIR_CVT( code2, code1 ) ) ) /* If a correction is followed by its inverse, and the user-supplied argument values are unchanged (we do not need to test values stored in the argument array which were not supplied by the user), we can eliminate them. First check for conversions which have a single user-supplied argument. */ if( ( PAIR_CVT2( AST__TAITOUTC, AST__UTCTOTAI ) || PAIR_CVT2( AST__TAITOTT, AST__TTTOTAI ) || PAIR_CVT2( AST__UTTOGMST, AST__GMSTTOUT ) || PAIR_CVT2( AST__TTTOTCG, AST__TCGTOTT ) || PAIR_CVT2( AST__TTTOTCG, AST__TCGTOTT ) || PAIR_CVT2( AST__UTTOUTC, AST__UTCTOUT ) || PAIR_CVT2( AST__LTTOUTC, AST__UTCTOLT ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) ) { istep++; keep = 0; /* Now check for conversions which have two user-supplied arguments (test they are swapped). */ } else if( ( PAIR_CVT2( AST__MJDTOJD, AST__JDTOMJD ) || PAIR_CVT2( AST__MJDTOMJD, AST__MJDTOMJD ) || PAIR_CVT2( AST__MJDTOBEP, AST__BEPTOMJD ) || PAIR_CVT2( AST__MJDTOJEP, AST__JEPTOMJD ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 1 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 0 ] ) ) { istep++; keep = 0; /* Now check for conversions which have three user-supplied arguments. */ } else if( ( PAIR_CVT2( AST__TDBTOTCB, AST__TCBTOTDB ) || PAIR_CVT2( AST__GMSTTOLMST, AST__LMSTTOGMST ) || PAIR_CVT2( AST__LASTTOLMST, AST__LMSTTOLAST ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 1 ] ) && astEQUAL( cvtargs[ istep ][ 2 ], cvtargs[ istep + 1 ][ 2 ] ) ) { istep++; keep = 0; /* Now check for conversions which have four user-supplied arguments. */ } else if( ( PAIR_CVT2( AST__TTTOTDB, AST__TDBTOTT ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 1 ] ) && astEQUAL( cvtargs[ istep ][ 2 ], cvtargs[ istep + 1 ][ 2 ] ) && astEQUAL( cvtargs[ istep ][ 3 ], cvtargs[ istep + 1 ][ 3 ] ) ) { istep++; keep = 0; } /* Undefine the local macros. */ #undef PAIR_CVT #undef PAIR_CVT2 } /* If the current transformation (possibly modified above) is being kept, then increment the index that identifies its new location in the list of transformation steps. */ if ( keep ) { ikeep++; /* If the new location is different to its current location, copy the transformation data into the new location. */ if ( ikeep != istep ) { cvttype[ ikeep ] = cvttype[ istep ]; for ( iarg = 0; iarg < szarg[ istep ]; iarg++ ) { cvtargs[ ikeep ][ iarg ] = cvtargs[ istep ][ iarg ]; } szarg[ ikeep ] = szarg[ istep ]; } } } /* Note if no simplification was achieved on this iteration (i.e. the number of transformation steps was not reduced). This is the signal to quit. */ done = ( ( ikeep + 1 ) >= nstep ); /* Note how many transformation steps now remain. */ nstep = ikeep + 1; } /* Determine how many Mappings can be eliminated by condensing all those considered above into a single Mapping. */ if ( astOK ) { ngone = imap2 - imap1; /* Determine if the replacement Mapping can be a UnitMap (a null Mapping). This will only be the case if all the transformation steps were eliminated above. */ unit = ( nstep == 0 ); /* Determine if simplification is possible. This will be the case if (a) Mappings were eliminated ("ngone" is non-zero), or (b) the number of transformation steps was reduced, or (c) the TimeMap(s) can be replaced by a UnitMap, or (d) if there was initially only one TimeMap present, its invert flag was set (this flag will always be cleared in the replacement Mapping). */ simpler = ngone || ( nstep < nstep0 ) || unit || ( *invert_list )[ where ]; /* Do nothing more unless simplification is possible. */ if ( simpler ) { /* If the replacement Mapping is a UnitMap, then create it. */ if ( unit ) { new = (AstMapping *) astUnitMap( astGetNin( ( *map_list )[ where ] ), "", status ); /* Otherwise, create a replacement TimeMap and add each of the remaining transformation steps to it. */ } else { new = (AstMapping *) astTimeMap( 0, "", status ); for ( istep = 0; istep < nstep; istep++ ) { AddTimeCvt( (AstTimeMap *) new, cvttype[ istep ], cvtargs[ istep ], status ); } } /* Annul the pointers to the Mappings being eliminated. */ if ( astOK ) { for ( imap = imap1; imap <= imap2; imap++ ) { ( *map_list )[ imap ] = astAnnul( ( *map_list )[ imap ] ); } /* Insert the pointer and invert value for the new Mapping. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Move any subsequent Mapping information down to close the gap. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - ngone ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - ngone ] = ( *invert_list )[ imap ]; } /* Blank out any information remaining at the end of the arrays. */ for ( imap = ( *nmap - ngone ); imap < *nmap; imap++ ) { ( *map_list )[ imap ] = NULL; ( *invert_list )[ imap ] = 0; } /* Decrement the Mapping count and return the index of the first Mapping which was eliminated. */ ( *nmap ) -= ngone; result = imap1; /* If an error occurred, annul the new Mapping pointer. */ } else { new = astAnnul( new ); } } } /* Free the memory used for the transformation steps. */ cvttype = astFree( cvttype ); cvtargs = astFree( cvtargs ); szarg = astFree( szarg ); } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static double Rate( AstMapping *this, 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 "timemap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * TimeMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. * Implementation Deficiencies: * The initial version of this implementation only deals with * frequency->wavelength conversions. This is because the slowness of * the numerical differentiation implemented by the astRate method in * the parent Mapping class is cripples conversion between SpecFluxFrames. * Such conversions only rely on rate of change of wavelength with * respect to frequency. This implementation should be extended when * needed. */ /* Local Variables: */ AstTimeMap *map; double result; int cvt; int i; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the TimeMap structure. */ map = (AstTimeMap *) this; /* Initialise the returned value. */ result = 1.0; /* Loop round each conversion. */ for( i = 0; i < map->ncvt; i++ ) { /* Store the type of the current conversion.*/ cvt = map->cvttype[ i ]; /* Many of the time conversions are linear. If this is the case, multiply the total rate of change by the rate of change for this step. */ if( cvt == AST__MJDTOBEP ) { result *= 1.0/365.242198781; } else if( cvt == AST__BEPTOMJD ) { result *= 365.242198781; } else if( cvt == AST__MJDTOJEP ) { result *= 1.0/365.25; } else if( cvt == AST__JEPTOMJD ) { result *= 365.25; /* The GMST scales is not linear, so break if we encounter it, and use the (numerical) parent astRate method. The other time scale conversions are assumed to have a slope of unity. In fact the slope will be ever so slightly different to unity. */ } else if( cvt == AST__UTTOGMST || cvt == AST__GMSTTOUT ) { result = AST__BAD; break; } } /* If this is non-linear TimeMap, use the astRate method inherited from the parent Mapping class. */ if( result == AST__BAD ) result = (*parent_rate)( this, at, ax1, ax2, status ); /* Return the result. */ return result; } static double Rcc( double tdb, double ut1, double wl, double u, double v, int *status ){ /* * Name: * Rcc * Purpose: * Find difference between TDB and TT. * Type: * Private function. * Synopsis: * #include "timemap.h" * double Rcc( double tdb, double ut1, double wl, double u, double v, int *status ) * Class Membership: * TimeMap member function * Description: * Relativistic clock correction: the difference between proper time at * a point on the surface of the Earth and coordinate time in the Solar * System barycentric space-time frame of reference. * * The proper time is terrestrial time, TT; the coordinate time is an * implementation of barycentric dynamical time, TDB. * Parameters: * tdb * TDB as an MJD. * ut1 * Universal time (only the fraction of the day is relevant) * wl * Observer longitude (radians west) * u * Observer distance from Earth spin axis (km) * v * Observer distance north of Earth equatorial plane (km) * status * Pointer to the inherited status variable. * Returned Value: * The clock correction, TDB-TT, in seconds. TDB is coordinate time in the * solar system barycentre frame of reference, in units chosen to eliminate * the scale difference with respect to terrestrial time. TT is the proper * time for clocks at mean sea level on the Earth. * Notes: * - This function is a translation of the fortran routine SLA_RCC * written by by P.T.Wallace. * * - The argument TDB is, strictly, the barycentric coordinate time; * however, the terrestrial time TT can in practice be used without * any significant loss of accuracy. * * - The result returned by Rcc comprises a main (annual) * sinusoidal term of amplitude approximately 0.00166 seconds, plus * planetary and lunar terms up to about 20 microseconds, and diurnal * terms up to 2 microseconds. The variation arises from the * transverse Doppler effect and the gravitational red-shift as the * observer varies in speed and moves through different gravitational * potentials. * * - The geocentric model is that of Fairhead & Bretagnon (1990), in * its full form. It was supplied by Fairhead (private * communication) as a FORTRAN subroutine. The original Fairhead * routine used explicit formulae, in such large numbers that * problems were experienced with certain compilers (Microsoft * Fortran on PC aborted with stack overflow, Convex compiled * successfully but extremely slowly). The present implementation is * a complete recoding, with the original Fairhead coefficients held * in a table. To optimise arithmetic precision, the terms are * accumulated in reverse order, smallest first. A number of other * coding changes were made, in order to match the calling sequence * of previous versions of the present routine, and to comply with * Starlink programming standards. The numerical results compared * with those from the Fairhead form are essentially unaffected by * the changes, the differences being at the 10^-20 sec level. * * - The topocentric part of the model is from Moyer (1981) and * Murray (1983). It is an approximation to the expression * ( v / c ) . ( r / c ), where v is the barycentric velocity of * the Earth, r is the geocentric position of the observer and * c is the speed of light. * * - During the interval 1950-2050, the absolute accuracy of is better * than +/- 3 nanoseconds relative to direct numerical integrations * using the JPL DE200/LE200 solar system ephemeris. * * - The IAU definition of TDB was that it must differ from TT only by * periodic terms. Though practical, this is an imprecise definition * which ignores the existence of very long-period and secular * effects in the dynamics of the solar system. As a consequence, * different implementations of TDB will, in general, differ in zero- * point and will drift linearly relative to one other. * * - TDB was, in principle, superseded by new coordinate timescales * which the IAU introduced in 1991: geocentric coordinate time, * TCG, and barycentric coordinate time, TCB. However, Rcc * can be used to implement the periodic part of TCB-TCG. * References: * - Fairhead, L., & Bretagnon, P., Astron.Astrophys., 229, 240-247 * (1990). * * - Moyer, T.D., Cel.Mech., 23, 33 (1981). * * - Murray, C.A., Vectorial Astrometry, Adam Hilger (1983). * * - Seidelmann, P.K. et al, Explanatory Supplement to the * Astronomical Almanac, Chapter 2, University Science Books * (1992). * * - Simon J.L., Bretagnon P., Chapront J., Chapront-Touze M., * Francou G. & Laskar J., Astron.Astrophys., 282, 663-683 (1994). */ /* ----------------------------------------------------------------------- * * Fairhead and Bretagnon canonical coefficients * * 787 sets of three coefficients. * * Each set is amplitude (microseconds) * frequency (radians per Julian millennium since J2000), * phase (radians). * * Sets 0-473 are the T**0 terms, * " 474-678 " " T**1 " * " 679-763 " " T**2 " * " 764-783 " " T**3 " * " 784-786 " " T**4 " . */ static double fairhd[ 787 ][ 3 ] = { { 1656.674564E-6, 6283.075849991, 6.240054195}, { 22.417471E-6, 5753.384884897, 4.296977442}, { 13.839792E-6, 12566.151699983, 6.196904410}, { 4.770086E-6, 529.690965095, 0.444401603}, { 4.676740E-6, 6069.776754553, 4.021195093}, { 2.256707E-6, 213.299095438, 5.543113262}, { 1.694205E-6, -3.523118349, 5.025132748}, { 1.554905E-6, 77713.771467920, 5.198467090}, { 1.276839E-6, 7860.419392439, 5.988822341}, { 1.193379E-6, 5223.693919802, 3.649823730}, { 1.115322E-6, 3930.209696220, 1.422745069}, { 0.794185E-6, 11506.769769794, 2.322313077}, { 0.447061E-6, 26.298319800, 3.615796498}, { 0.435206E-6, -398.149003408, 4.349338347}, { 0.600309E-6, 1577.343542448, 2.678271909}, { 0.496817E-6, 6208.294251424, 5.696701824}, { 0.486306E-6, 5884.926846583, 0.520007179}, { 0.432392E-6, 74.781598567, 2.435898309}, { 0.468597E-6, 6244.942814354, 5.866398759}, { 0.375510E-6, 5507.553238667, 4.103476804}, { 0.243085E-6, -775.522611324, 3.651837925}, { 0.173435E-6, 18849.227549974, 6.153743485}, { 0.230685E-6, 5856.477659115, 4.773852582}, { 0.203747E-6, 12036.460734888, 4.333987818}, { 0.143935E-6, -796.298006816, 5.957517795}, { 0.159080E-6, 10977.078804699, 1.890075226}, { 0.119979E-6, 38.133035638, 4.551585768}, { 0.118971E-6, 5486.777843175, 1.914547226}, { 0.116120E-6, 1059.381930189, 0.873504123}, { 0.137927E-6, 11790.629088659, 1.135934669}, { 0.098358E-6, 2544.314419883, 0.092793886}, { 0.101868E-6, -5573.142801634, 5.984503847}, { 0.080164E-6, 206.185548437, 2.095377709}, { 0.079645E-6, 4694.002954708, 2.949233637}, { 0.062617E-6, 20.775395492, 2.654394814}, { 0.075019E-6, 2942.463423292, 4.980931759}, { 0.064397E-6, 5746.271337896, 1.280308748}, { 0.063814E-6, 5760.498431898, 4.167901731}, { 0.048042E-6, 2146.165416475, 1.495846011}, { 0.048373E-6, 155.420399434, 2.251573730}, { 0.058844E-6, 426.598190876, 4.839650148}, { 0.046551E-6, -0.980321068, 0.921573539}, { 0.054139E-6, 17260.154654690, 3.411091093}, { 0.042411E-6, 6275.962302991, 2.869567043}, { 0.040184E-6, -7.113547001, 3.565975565}, { 0.036564E-6, 5088.628839767, 3.324679049}, { 0.040759E-6, 12352.852604545, 3.981496998}, { 0.036507E-6, 801.820931124, 6.248866009}, { 0.036955E-6, 3154.687084896, 5.071801441}, { 0.042732E-6, 632.783739313, 5.720622217}, { 0.042560E-6, 161000.685737473, 1.270837679}, { 0.040480E-6, 15720.838784878, 2.546610123}, { 0.028244E-6, -6286.598968340, 5.069663519}, { 0.033477E-6, 6062.663207553, 4.144987272}, { 0.034867E-6, 522.577418094, 5.210064075}, { 0.032438E-6, 6076.890301554, 0.749317412}, { 0.030215E-6, 7084.896781115, 3.389610345}, { 0.029247E-6, -71430.695617928, 4.183178762}, { 0.033529E-6, 9437.762934887, 2.404714239}, { 0.032423E-6, 8827.390269875, 5.541473556}, { 0.027567E-6, 6279.552731642, 5.040846034}, { 0.029862E-6, 12139.553509107, 1.770181024}, { 0.022509E-6, 10447.387839604, 1.460726241}, { 0.020937E-6, 8429.241266467, 0.652303414}, { 0.020322E-6, 419.484643875, 3.735430632}, { 0.024816E-6, -1194.447010225, 1.087136918}, { 0.025196E-6, 1748.016413067, 2.901883301}, { 0.021691E-6, 14143.495242431, 5.952658009}, { 0.017673E-6, 6812.766815086, 3.186129845}, { 0.022567E-6, 6133.512652857, 3.307984806}, { 0.016155E-6, 10213.285546211, 1.331103168}, { 0.014751E-6, 1349.867409659, 4.308933301}, { 0.015949E-6, -220.412642439, 4.005298270}, { 0.015974E-6, -2352.866153772, 6.145309371}, { 0.014223E-6, 17789.845619785, 2.104551349}, { 0.017806E-6, 73.297125859, 3.475975097}, { 0.013671E-6, -536.804512095, 5.971672571}, { 0.011942E-6, 8031.092263058, 2.053414715}, { 0.014318E-6, 16730.463689596, 3.016058075}, { 0.012462E-6, 103.092774219, 1.737438797}, { 0.010962E-6, 3.590428652, 2.196567739}, { 0.015078E-6, 19651.048481098, 3.969480770}, { 0.010396E-6, 951.718406251, 5.717799605}, { 0.011707E-6, -4705.732307544, 2.654125618}, { 0.010453E-6, 5863.591206116, 1.913704550}, { 0.012420E-6, 4690.479836359, 4.734090399}, { 0.011847E-6, 5643.178563677, 5.489005403}, { 0.008610E-6, 3340.612426700, 3.661698944}, { 0.011622E-6, 5120.601145584, 4.863931876}, { 0.010825E-6, 553.569402842, 0.842715011}, { 0.008666E-6, -135.065080035, 3.293406547}, { 0.009963E-6, 149.563197135, 4.870690598}, { 0.009858E-6, 6309.374169791, 1.061816410}, { 0.007959E-6, 316.391869657, 2.465042647}, { 0.010099E-6, 283.859318865, 1.942176992}, { 0.007147E-6, -242.728603974, 3.661486981}, { 0.007505E-6, 5230.807466803, 4.920937029}, { 0.008323E-6, 11769.853693166, 1.229392026}, { 0.007490E-6, -6256.777530192, 3.658444681}, { 0.009370E-6, 149854.400134205, 0.673880395}, { 0.007117E-6, 38.027672636, 5.294249518}, { 0.007857E-6, 12168.002696575, 0.525733528}, { 0.007019E-6, 6206.809778716, 0.837688810}, { 0.006056E-6, 955.599741609, 4.194535082}, { 0.008107E-6, 13367.972631107, 3.793235253}, { 0.006731E-6, 5650.292110678, 5.639906583}, { 0.007332E-6, 36.648562930, 0.114858677}, { 0.006366E-6, 4164.311989613, 2.262081818}, { 0.006858E-6, 5216.580372801, 0.642063318}, { 0.006919E-6, 6681.224853400, 6.018501522}, { 0.006826E-6, 7632.943259650, 3.458654112}, { 0.005308E-6, -1592.596013633, 2.500382359}, { 0.005096E-6, 11371.704689758, 2.547107806}, { 0.004841E-6, 5333.900241022, 0.437078094}, { 0.005582E-6, 5966.683980335, 2.246174308}, { 0.006304E-6, 11926.254413669, 2.512929171}, { 0.006603E-6, 23581.258177318, 5.393136889}, { 0.005123E-6, -1.484472708, 2.999641028}, { 0.004648E-6, 1589.072895284, 1.275847090}, { 0.005119E-6, 6438.496249426, 1.486539246}, { 0.004521E-6, 4292.330832950, 6.140635794}, { 0.005680E-6, 23013.539539587, 4.557814849}, { 0.005488E-6, -3.455808046, 0.090675389}, { 0.004193E-6, 7234.794256242, 4.869091389}, { 0.003742E-6, 7238.675591600, 4.691976180}, { 0.004148E-6, -110.206321219, 3.016173439}, { 0.004553E-6, 11499.656222793, 5.554998314}, { 0.004892E-6, 5436.993015240, 1.475415597}, { 0.004044E-6, 4732.030627343, 1.398784824}, { 0.004164E-6, 12491.370101415, 5.650931916}, { 0.004349E-6, 11513.883316794, 2.181745369}, { 0.003919E-6, 12528.018664345, 5.823319737}, { 0.003129E-6, 6836.645252834, 0.003844094}, { 0.004080E-6, -7058.598461315, 3.690360123}, { 0.003270E-6, 76.266071276, 1.517189902}, { 0.002954E-6, 6283.143160294, 4.447203799}, { 0.002872E-6, 28.449187468, 1.158692983}, { 0.002881E-6, 735.876513532, 0.349250250}, { 0.003279E-6, 5849.364112115, 4.893384368}, { 0.003625E-6, 6209.778724132, 1.473760578}, { 0.003074E-6, 949.175608970, 5.185878737}, { 0.002775E-6, 9917.696874510, 1.030026325}, { 0.002646E-6, 10973.555686350, 3.918259169}, { 0.002575E-6, 25132.303399966, 6.109659023}, { 0.003500E-6, 263.083923373, 1.892100742}, { 0.002740E-6, 18319.536584880, 4.320519510}, { 0.002464E-6, 202.253395174, 4.698203059}, { 0.002409E-6, 2.542797281, 5.325009315}, { 0.003354E-6, -90955.551694697, 1.942656623}, { 0.002296E-6, 6496.374945429, 5.061810696}, { 0.003002E-6, 6172.869528772, 2.797822767}, { 0.003202E-6, 27511.467873537, 0.531673101}, { 0.002954E-6, -6283.008539689, 4.533471191}, { 0.002353E-6, 639.897286314, 3.734548088}, { 0.002401E-6, 16200.772724501, 2.605547070}, { 0.003053E-6, 233141.314403759, 3.029030662}, { 0.003024E-6, 83286.914269554, 2.355556099}, { 0.002863E-6, 17298.182327326, 5.240963796}, { 0.002103E-6, -7079.373856808, 5.756641637}, { 0.002303E-6, 83996.847317911, 2.013686814}, { 0.002303E-6, 18073.704938650, 1.089100410}, { 0.002381E-6, 63.735898303, 0.759188178}, { 0.002493E-6, 6386.168624210, 0.645026535}, { 0.002366E-6, 3.932153263, 6.215885448}, { 0.002169E-6, 11015.106477335, 4.845297676}, { 0.002397E-6, 6243.458341645, 3.809290043}, { 0.002183E-6, 1162.474704408, 6.179611691}, { 0.002353E-6, 6246.427287062, 4.781719760}, { 0.002199E-6, -245.831646229, 5.956152284}, { 0.001729E-6, 3894.181829542, 1.264976635}, { 0.001896E-6, -3128.388765096, 4.914231596}, { 0.002085E-6, 35.164090221, 1.405158503}, { 0.002024E-6, 14712.317116458, 2.752035928}, { 0.001737E-6, 6290.189396992, 5.280820144}, { 0.002229E-6, 491.557929457, 1.571007057}, { 0.001602E-6, 14314.168113050, 4.203664806}, { 0.002186E-6, 454.909366527, 1.402101526}, { 0.001897E-6, 22483.848574493, 4.167932508}, { 0.001825E-6, -3738.761430108, 0.545828785}, { 0.001894E-6, 1052.268383188, 5.817167450}, { 0.001421E-6, 20.355319399, 2.419886601}, { 0.001408E-6, 10984.192351700, 2.732084787}, { 0.001847E-6, 10873.986030480, 2.903477885}, { 0.001391E-6, -8635.942003763, 0.593891500}, { 0.001388E-6, -7.046236698, 1.166145902}, { 0.001810E-6, -88860.057071188, 0.487355242}, { 0.001288E-6, -1990.745017041, 3.913022880}, { 0.001297E-6, 23543.230504682, 3.063805171}, { 0.001335E-6, -266.607041722, 3.995764039}, { 0.001376E-6, 10969.965257698, 5.152914309}, { 0.001745E-6, 244287.600007027, 3.626395673}, { 0.001649E-6, 31441.677569757, 1.952049260}, { 0.001416E-6, 9225.539273283, 4.996408389}, { 0.001238E-6, 4804.209275927, 5.503379738}, { 0.001472E-6, 4590.910180489, 4.164913291}, { 0.001169E-6, 6040.347246017, 5.841719038}, { 0.001039E-6, 5540.085789459, 2.769753519}, { 0.001004E-6, -170.672870619, 0.755008103}, { 0.001284E-6, 10575.406682942, 5.306538209}, { 0.001278E-6, 71.812653151, 4.713486491}, { 0.001321E-6, 18209.330263660, 2.624866359}, { 0.001297E-6, 21228.392023546, 0.382603541}, { 0.000954E-6, 6282.095528923, 0.882213514}, { 0.001145E-6, 6058.731054289, 1.169483931}, { 0.000979E-6, 5547.199336460, 5.448375984}, { 0.000987E-6, -6262.300454499, 2.656486959}, { 0.001070E-6, -154717.609887482, 1.827624012}, { 0.000991E-6, 4701.116501708, 4.387001801}, { 0.001155E-6, -14.227094002, 3.042700750}, { 0.001176E-6, 277.034993741, 3.335519004}, { 0.000890E-6, 13916.019109642, 5.601498297}, { 0.000884E-6, -1551.045222648, 1.088831705}, { 0.000876E-6, 5017.508371365, 3.969902609}, { 0.000806E-6, 15110.466119866, 5.142876744}, { 0.000773E-6, -4136.910433516, 0.022067765}, { 0.001077E-6, 175.166059800, 1.844913056}, { 0.000954E-6, -6284.056171060, 0.968480906}, { 0.000737E-6, 5326.786694021, 4.923831588}, { 0.000845E-6, -433.711737877, 4.749245231}, { 0.000819E-6, 8662.240323563, 5.991247817}, { 0.000852E-6, 199.072001436, 2.189604979}, { 0.000723E-6, 17256.631536341, 6.068719637}, { 0.000940E-6, 6037.244203762, 6.197428148}, { 0.000885E-6, 11712.955318231, 3.280414875}, { 0.000706E-6, 12559.038152982, 2.824848947}, { 0.000732E-6, 2379.164473572, 2.501813417}, { 0.000764E-6, -6127.655450557, 2.236346329}, { 0.000908E-6, 131.541961686, 2.521257490}, { 0.000907E-6, 35371.887265976, 3.370195967}, { 0.000673E-6, 1066.495477190, 3.876512374}, { 0.000814E-6, 17654.780539750, 4.627122566}, { 0.000630E-6, 36.027866677, 0.156368499}, { 0.000798E-6, 515.463871093, 5.151962502}, { 0.000798E-6, 148.078724426, 5.909225055}, { 0.000806E-6, 309.278322656, 6.054064447}, { 0.000607E-6, -39.617508346, 2.839021623}, { 0.000601E-6, 412.371096874, 3.984225404}, { 0.000646E-6, 11403.676995575, 3.852959484}, { 0.000704E-6, 13521.751441591, 2.300991267}, { 0.000603E-6, -65147.619767937, 4.140083146}, { 0.000609E-6, 10177.257679534, 0.437122327}, { 0.000631E-6, 5767.611978898, 4.026532329}, { 0.000576E-6, 11087.285125918, 4.760293101}, { 0.000674E-6, 14945.316173554, 6.270510511}, { 0.000726E-6, 5429.879468239, 6.039606892}, { 0.000710E-6, 28766.924424484, 5.672617711}, { 0.000647E-6, 11856.218651625, 3.397132627}, { 0.000678E-6, -5481.254918868, 6.249666675}, { 0.000618E-6, 22003.914634870, 2.466427018}, { 0.000738E-6, 6134.997125565, 2.242668890}, { 0.000660E-6, 625.670192312, 5.864091907}, { 0.000694E-6, 3496.032826134, 2.668309141}, { 0.000531E-6, 6489.261398429, 1.681888780}, { 0.000611E-6, -143571.324284214, 2.424978312}, { 0.000575E-6, 12043.574281889, 4.216492400}, { 0.000553E-6, 12416.588502848, 4.772158039}, { 0.000689E-6, 4686.889407707, 6.224271088}, { 0.000495E-6, 7342.457780181, 3.817285811}, { 0.000567E-6, 3634.621024518, 1.649264690}, { 0.000515E-6, 18635.928454536, 3.945345892}, { 0.000486E-6, -323.505416657, 4.061673868}, { 0.000662E-6, 25158.601719765, 1.794058369}, { 0.000509E-6, 846.082834751, 3.053874588}, { 0.000472E-6, -12569.674818332, 5.112133338}, { 0.000461E-6, 6179.983075773, 0.513669325}, { 0.000641E-6, 83467.156352816, 3.210727723}, { 0.000520E-6, 10344.295065386, 2.445597761}, { 0.000493E-6, 18422.629359098, 1.676939306}, { 0.000478E-6, 1265.567478626, 5.487314569}, { 0.000472E-6, -18.159247265, 1.999707589}, { 0.000559E-6, 11190.377900137, 5.783236356}, { 0.000494E-6, 9623.688276691, 3.022645053}, { 0.000463E-6, 5739.157790895, 1.411223013}, { 0.000432E-6, 16858.482532933, 1.179256434}, { 0.000574E-6, 72140.628666286, 1.758191830}, { 0.000484E-6, 17267.268201691, 3.290589143}, { 0.000550E-6, 4907.302050146, 0.864024298}, { 0.000399E-6, 14.977853527, 2.094441910}, { 0.000491E-6, 224.344795702, 0.878372791}, { 0.000432E-6, 20426.571092422, 6.003829241}, { 0.000481E-6, 5749.452731634, 4.309591964}, { 0.000480E-6, 5757.317038160, 1.142348571}, { 0.000485E-6, 6702.560493867, 0.210580917}, { 0.000426E-6, 6055.549660552, 4.274476529}, { 0.000480E-6, 5959.570433334, 5.031351030}, { 0.000466E-6, 12562.628581634, 4.959581597}, { 0.000520E-6, 39302.096962196, 4.788002889}, { 0.000458E-6, 12132.439962106, 1.880103788}, { 0.000470E-6, 12029.347187887, 1.405611197}, { 0.000416E-6, -7477.522860216, 1.082356330}, { 0.000449E-6, 11609.862544012, 4.179989585}, { 0.000465E-6, 17253.041107690, 0.353496295}, { 0.000362E-6, -4535.059436924, 1.583849576}, { 0.000383E-6, 21954.157609398, 3.747376371}, { 0.000389E-6, 17.252277143, 1.395753179}, { 0.000331E-6, 18052.929543158, 0.566790582}, { 0.000430E-6, 13517.870106233, 0.685827538}, { 0.000368E-6, -5756.908003246, 0.731374317}, { 0.000330E-6, 10557.594160824, 3.710043680}, { 0.000332E-6, 20199.094959633, 1.652901407}, { 0.000384E-6, 11933.367960670, 5.827781531}, { 0.000387E-6, 10454.501386605, 2.541182564}, { 0.000325E-6, 15671.081759407, 2.178850542}, { 0.000318E-6, 138.517496871, 2.253253037}, { 0.000305E-6, 9388.005909415, 0.578340206}, { 0.000352E-6, 5749.861766548, 3.000297967}, { 0.000311E-6, 6915.859589305, 1.693574249}, { 0.000297E-6, 24072.921469776, 1.997249392}, { 0.000363E-6, -640.877607382, 5.071820966}, { 0.000323E-6, 12592.450019783, 1.072262823}, { 0.000341E-6, 12146.667056108, 4.700657997}, { 0.000290E-6, 9779.108676125, 1.812320441}, { 0.000342E-6, 6132.028180148, 4.322238614}, { 0.000329E-6, 6268.848755990, 3.033827743}, { 0.000374E-6, 17996.031168222, 3.388716544}, { 0.000285E-6, -533.214083444, 4.687313233}, { 0.000338E-6, 6065.844601290, 0.877776108}, { 0.000276E-6, 24.298513841, 0.770299429}, { 0.000336E-6, -2388.894020449, 5.353796034}, { 0.000290E-6, 3097.883822726, 4.075291557}, { 0.000318E-6, 709.933048357, 5.941207518}, { 0.000271E-6, 13095.842665077, 3.208912203}, { 0.000331E-6, 6073.708907816, 4.007881169}, { 0.000292E-6, 742.990060533, 2.714333592}, { 0.000362E-6, 29088.811415985, 3.215977013}, { 0.000280E-6, 12359.966151546, 0.710872502}, { 0.000267E-6, 10440.274292604, 4.730108488}, { 0.000262E-6, 838.969287750, 1.327720272}, { 0.000250E-6, 16496.361396202, 0.898769761}, { 0.000325E-6, 20597.243963041, 0.180044365}, { 0.000268E-6, 6148.010769956, 5.152666276}, { 0.000284E-6, 5636.065016677, 5.655385808}, { 0.000301E-6, 6080.822454817, 2.135396205}, { 0.000294E-6, -377.373607916, 3.708784168}, { 0.000236E-6, 2118.763860378, 1.733578756}, { 0.000234E-6, 5867.523359379, 5.575209112}, { 0.000268E-6, -226858.238553767, 0.069432392}, { 0.000265E-6, 167283.761587465, 4.369302826}, { 0.000280E-6, 28237.233459389, 5.304829118}, { 0.000292E-6, 12345.739057544, 4.096094132}, { 0.000223E-6, 19800.945956225, 3.069327406}, { 0.000301E-6, 43232.306658416, 6.205311188}, { 0.000264E-6, 18875.525869774, 1.417263408}, { 0.000304E-6, -1823.175188677, 3.409035232}, { 0.000301E-6, 109.945688789, 0.510922054}, { 0.000260E-6, 813.550283960, 2.389438934}, { 0.000299E-6, 316428.228673312, 5.384595078}, { 0.000211E-6, 5756.566278634, 3.789392838}, { 0.000209E-6, 5750.203491159, 1.661943545}, { 0.000240E-6, 12489.885628707, 5.684549045}, { 0.000216E-6, 6303.851245484, 3.862942261}, { 0.000203E-6, 1581.959348283, 5.549853589}, { 0.000200E-6, 5642.198242609, 1.016115785}, { 0.000197E-6, -70.849445304, 4.690702525}, { 0.000227E-6, 6287.008003254, 2.911891613}, { 0.000197E-6, 533.623118358, 1.048982898}, { 0.000205E-6, -6279.485421340, 1.829362730}, { 0.000209E-6, -10988.808157535, 2.636140084}, { 0.000208E-6, -227.526189440, 4.127883842}, { 0.000191E-6, 415.552490612, 4.401165650}, { 0.000190E-6, 29296.615389579, 4.175658539}, { 0.000264E-6, 66567.485864652, 4.601102551}, { 0.000256E-6, -3646.350377354, 0.506364778}, { 0.000188E-6, 13119.721102825, 2.032195842}, { 0.000185E-6, -209.366942175, 4.694756586}, { 0.000198E-6, 25934.124331089, 3.832703118}, { 0.000195E-6, 4061.219215394, 3.308463427}, { 0.000234E-6, 5113.487598583, 1.716090661}, { 0.000188E-6, 1478.866574064, 5.686865780}, { 0.000222E-6, 11823.161639450, 1.942386641}, { 0.000181E-6, 10770.893256262, 1.999482059}, { 0.000171E-6, 6546.159773364, 1.182807992}, { 0.000206E-6, 70.328180442, 5.934076062}, { 0.000169E-6, 20995.392966449, 2.169080622}, { 0.000191E-6, 10660.686935042, 5.405515999}, { 0.000228E-6, 33019.021112205, 4.656985514}, { 0.000184E-6, -4933.208440333, 3.327476868}, { 0.000220E-6, -135.625325010, 1.765430262}, { 0.000166E-6, 23141.558382925, 3.454132746}, { 0.000191E-6, 6144.558353121, 5.020393445}, { 0.000180E-6, 6084.003848555, 0.602182191}, { 0.000163E-6, 17782.732072784, 4.960593133}, { 0.000225E-6, 16460.333529525, 2.596451817}, { 0.000222E-6, 5905.702242076, 3.731990323}, { 0.000204E-6, 227.476132789, 5.636192701}, { 0.000159E-6, 16737.577236597, 3.600691544}, { 0.000200E-6, 6805.653268085, 0.868220961}, { 0.000187E-6, 11919.140866668, 2.629456641}, { 0.000161E-6, 127.471796607, 2.862574720}, { 0.000205E-6, 6286.666278643, 1.742882331}, { 0.000189E-6, 153.778810485, 4.812372643}, { 0.000168E-6, 16723.350142595, 0.027860588}, { 0.000149E-6, 11720.068865232, 0.659721876}, { 0.000189E-6, 5237.921013804, 5.245313000}, { 0.000143E-6, 6709.674040867, 4.317625647}, { 0.000146E-6, 4487.817406270, 4.815297007}, { 0.000144E-6, -664.756045130, 5.381366880}, { 0.000175E-6, 5127.714692584, 4.728443327}, { 0.000162E-6, 6254.626662524, 1.435132069}, { 0.000187E-6, 47162.516354635, 1.354371923}, { 0.000146E-6, 11080.171578918, 3.369695406}, { 0.000180E-6, -348.924420448, 2.490902145}, { 0.000148E-6, 151.047669843, 3.799109588}, { 0.000157E-6, 6197.248551160, 1.284375887}, { 0.000167E-6, 146.594251718, 0.759969109}, { 0.000133E-6, -5331.357443741, 5.409701889}, { 0.000154E-6, 95.979227218, 3.366890614}, { 0.000148E-6, -6418.140930027, 3.384104996}, { 0.000128E-6, -6525.804453965, 3.803419985}, { 0.000130E-6, 11293.470674356, 0.939039445}, { 0.000152E-6, -5729.506447149, 0.734117523}, { 0.000138E-6, 210.117701700, 2.564216078}, { 0.000123E-6, 6066.595360816, 4.517099537}, { 0.000140E-6, 18451.078546566, 0.642049130}, { 0.000126E-6, 11300.584221356, 3.485280663}, { 0.000119E-6, 10027.903195729, 3.217431161}, { 0.000151E-6, 4274.518310832, 4.404359108}, { 0.000117E-6, 6072.958148291, 0.366324650}, { 0.000165E-6, -7668.637425143, 4.298212528}, { 0.000117E-6, -6245.048177356, 5.379518958}, { 0.000130E-6, -5888.449964932, 4.527681115}, { 0.000121E-6, -543.918059096, 6.109429504}, { 0.000162E-6, 9683.594581116, 5.720092446}, { 0.000141E-6, 6219.339951688, 0.679068671}, { 0.000118E-6, 22743.409379516, 4.881123092}, { 0.000129E-6, 1692.165669502, 0.351407289}, { 0.000126E-6, 5657.405657679, 5.146592349}, { 0.000114E-6, 728.762966531, 0.520791814}, { 0.000120E-6, 52.596639600, 0.948516300}, { 0.000115E-6, 65.220371012, 3.504914846}, { 0.000126E-6, 5881.403728234, 5.577502482}, { 0.000158E-6, 163096.180360983, 2.957128968}, { 0.000134E-6, 12341.806904281, 2.598576764}, { 0.000151E-6, 16627.370915377, 3.985702050}, { 0.000109E-6, 1368.660252845, 0.014730471}, { 0.000131E-6, 6211.263196841, 0.085077024}, { 0.000146E-6, 5792.741760812, 0.708426604}, { 0.000146E-6, -77.750543984, 3.121576600}, { 0.000107E-6, 5341.013788022, 0.288231904}, { 0.000138E-6, 6281.591377283, 2.797450317}, { 0.000113E-6, -6277.552925684, 2.788904128}, { 0.000115E-6, -525.758811831, 5.895222200}, { 0.000138E-6, 6016.468808270, 6.096188999}, { 0.000139E-6, 23539.707386333, 2.028195445}, { 0.000146E-6, -4176.041342449, 4.660008502}, { 0.000107E-6, 16062.184526117, 4.066520001}, { 0.000142E-6, 83783.548222473, 2.936315115}, { 0.000128E-6, 9380.959672717, 3.223844306}, { 0.000135E-6, 6205.325306007, 1.638054048}, { 0.000101E-6, 2699.734819318, 5.481603249}, { 0.000104E-6, -568.821874027, 2.205734493}, { 0.000103E-6, 6321.103522627, 2.440421099}, { 0.000119E-6, 6321.208885629, 2.547496264}, { 0.000138E-6, 1975.492545856, 2.314608466}, { 0.000121E-6, 137.033024162, 4.539108237}, { 0.000123E-6, 19402.796952817, 4.538074405}, { 0.000119E-6, 22805.735565994, 2.869040566}, { 0.000133E-6, 64471.991241142, 6.056405489}, { 0.000129E-6, -85.827298831, 2.540635083}, { 0.000131E-6, 13613.804277336, 4.005732868}, { 0.000104E-6, 9814.604100291, 1.959967212}, { 0.000112E-6, 16097.679950283, 3.589026260}, { 0.000123E-6, 2107.034507542, 1.728627253}, { 0.000121E-6, 36949.230808424, 6.072332087}, { 0.000108E-6, -12539.853380183, 3.716133846}, { 0.000113E-6, -7875.671863624, 2.725771122}, { 0.000109E-6, 4171.425536614, 4.033338079}, { 0.000101E-6, 6247.911759770, 3.441347021}, { 0.000113E-6, 7330.728427345, 0.656372122}, { 0.000113E-6, 51092.726050855, 2.791483066}, { 0.000106E-6, 5621.842923210, 1.815323326}, { 0.000101E-6, 111.430161497, 5.711033677}, { 0.000103E-6, 909.818733055, 2.812745443}, { 0.000101E-6, 1790.642637886, 1.965746028}, { 102.156724E-6, 6283.075849991, 4.249032005}, { 1.706807E-6, 12566.151699983, 4.205904248}, { 0.269668E-6, 213.299095438, 3.400290479}, { 0.265919E-6, 529.690965095, 5.836047367}, { 0.210568E-6, -3.523118349, 6.262738348}, { 0.077996E-6, 5223.693919802, 4.670344204}, { 0.054764E-6, 1577.343542448, 4.534800170}, { 0.059146E-6, 26.298319800, 1.083044735}, { 0.034420E-6, -398.149003408, 5.980077351}, { 0.032088E-6, 18849.227549974, 4.162913471}, { 0.033595E-6, 5507.553238667, 5.980162321}, { 0.029198E-6, 5856.477659115, 0.623811863}, { 0.027764E-6, 155.420399434, 3.745318113}, { 0.025190E-6, 5746.271337896, 2.980330535}, { 0.022997E-6, -796.298006816, 1.174411803}, { 0.024976E-6, 5760.498431898, 2.467913690}, { 0.021774E-6, 206.185548437, 3.854787540}, { 0.017925E-6, -775.522611324, 1.092065955}, { 0.013794E-6, 426.598190876, 2.699831988}, { 0.013276E-6, 6062.663207553, 5.845801920}, { 0.011774E-6, 12036.460734888, 2.292832062}, { 0.012869E-6, 6076.890301554, 5.333425680}, { 0.012152E-6, 1059.381930189, 6.222874454}, { 0.011081E-6, -7.113547001, 5.154724984}, { 0.010143E-6, 4694.002954708, 4.044013795}, { 0.009357E-6, 5486.777843175, 3.416081409}, { 0.010084E-6, 522.577418094, 0.749320262}, { 0.008587E-6, 10977.078804699, 2.777152598}, { 0.008628E-6, 6275.962302991, 4.562060226}, { 0.008158E-6, -220.412642439, 5.806891533}, { 0.007746E-6, 2544.314419883, 1.603197066}, { 0.007670E-6, 2146.165416475, 3.000200440}, { 0.007098E-6, 74.781598567, 0.443725817}, { 0.006180E-6, -536.804512095, 1.302642751}, { 0.005818E-6, 5088.628839767, 4.827723531}, { 0.004945E-6, -6286.598968340, 0.268305170}, { 0.004774E-6, 1349.867409659, 5.808636673}, { 0.004687E-6, -242.728603974, 5.154890570}, { 0.006089E-6, 1748.016413067, 4.403765209}, { 0.005975E-6, -1194.447010225, 2.583472591}, { 0.004229E-6, 951.718406251, 0.931172179}, { 0.005264E-6, 553.569402842, 2.336107252}, { 0.003049E-6, 5643.178563677, 1.362634430}, { 0.002974E-6, 6812.766815086, 1.583012668}, { 0.003403E-6, -2352.866153772, 2.552189886}, { 0.003030E-6, 419.484643875, 5.286473844}, { 0.003210E-6, -7.046236698, 1.863796539}, { 0.003058E-6, 9437.762934887, 4.226420633}, { 0.002589E-6, 12352.852604545, 1.991935820}, { 0.002927E-6, 5216.580372801, 2.319951253}, { 0.002425E-6, 5230.807466803, 3.084752833}, { 0.002656E-6, 3154.687084896, 2.487447866}, { 0.002445E-6, 10447.387839604, 2.347139160}, { 0.002990E-6, 4690.479836359, 6.235872050}, { 0.002890E-6, 5863.591206116, 0.095197563}, { 0.002498E-6, 6438.496249426, 2.994779800}, { 0.001889E-6, 8031.092263058, 3.569003717}, { 0.002567E-6, 801.820931124, 3.425611498}, { 0.001803E-6, -71430.695617928, 2.192295512}, { 0.001782E-6, 3.932153263, 5.180433689}, { 0.001694E-6, -4705.732307544, 4.641779174}, { 0.001704E-6, -1592.596013633, 3.997097652}, { 0.001735E-6, 5849.364112115, 0.417558428}, { 0.001643E-6, 8429.241266467, 2.180619584}, { 0.001680E-6, 38.133035638, 4.164529426}, { 0.002045E-6, 7084.896781115, 0.526323854}, { 0.001458E-6, 4292.330832950, 1.356098141}, { 0.001437E-6, 20.355319399, 3.895439360}, { 0.001738E-6, 6279.552731642, 0.087484036}, { 0.001367E-6, 14143.495242431, 3.987576591}, { 0.001344E-6, 7234.794256242, 0.090454338}, { 0.001438E-6, 11499.656222793, 0.974387904}, { 0.001257E-6, 6836.645252834, 1.509069366}, { 0.001358E-6, 11513.883316794, 0.495572260}, { 0.001628E-6, 7632.943259650, 4.968445721}, { 0.001169E-6, 103.092774219, 2.838496795}, { 0.001162E-6, 4164.311989613, 3.408387778}, { 0.001092E-6, 6069.776754553, 3.617942651}, { 0.001008E-6, 17789.845619785, 0.286350174}, { 0.001008E-6, 639.897286314, 1.610762073}, { 0.000918E-6, 10213.285546211, 5.532798067}, { 0.001011E-6, -6256.777530192, 0.661826484}, { 0.000753E-6, 16730.463689596, 3.905030235}, { 0.000737E-6, 11926.254413669, 4.641956361}, { 0.000694E-6, 3340.612426700, 2.111120332}, { 0.000701E-6, 3894.181829542, 2.760823491}, { 0.000689E-6, -135.065080035, 4.768800780}, { 0.000700E-6, 13367.972631107, 5.760439898}, { 0.000664E-6, 6040.347246017, 1.051215840}, { 0.000654E-6, 5650.292110678, 4.911332503}, { 0.000788E-6, 6681.224853400, 4.699648011}, { 0.000628E-6, 5333.900241022, 5.024608847}, { 0.000755E-6, -110.206321219, 4.370971253}, { 0.000628E-6, 6290.189396992, 3.660478857}, { 0.000635E-6, 25132.303399966, 4.121051532}, { 0.000534E-6, 5966.683980335, 1.173284524}, { 0.000543E-6, -433.711737877, 0.345585464}, { 0.000517E-6, -1990.745017041, 5.414571768}, { 0.000504E-6, 5767.611978898, 2.328281115}, { 0.000485E-6, 5753.384884897, 1.685874771}, { 0.000463E-6, 7860.419392439, 5.297703006}, { 0.000604E-6, 515.463871093, 0.591998446}, { 0.000443E-6, 12168.002696575, 4.830881244}, { 0.000570E-6, 199.072001436, 3.899190272}, { 0.000465E-6, 10969.965257698, 0.476681802}, { 0.000424E-6, -7079.373856808, 1.112242763}, { 0.000427E-6, 735.876513532, 1.994214480}, { 0.000478E-6, -6127.655450557, 3.778025483}, { 0.000414E-6, 10973.555686350, 5.441088327}, { 0.000512E-6, 1589.072895284, 0.107123853}, { 0.000378E-6, 10984.192351700, 0.915087231}, { 0.000402E-6, 11371.704689758, 4.107281715}, { 0.000453E-6, 9917.696874510, 1.917490952}, { 0.000395E-6, 149.563197135, 2.763124165}, { 0.000371E-6, 5739.157790895, 3.112111866}, { 0.000350E-6, 11790.629088659, 0.440639857}, { 0.000356E-6, 6133.512652857, 5.444568842}, { 0.000344E-6, 412.371096874, 5.676832684}, { 0.000383E-6, 955.599741609, 5.559734846}, { 0.000333E-6, 6496.374945429, 0.261537984}, { 0.000340E-6, 6055.549660552, 5.975534987}, { 0.000334E-6, 1066.495477190, 2.335063907}, { 0.000399E-6, 11506.769769794, 5.321230910}, { 0.000314E-6, 18319.536584880, 2.313312404}, { 0.000424E-6, 1052.268383188, 1.211961766}, { 0.000307E-6, 63.735898303, 3.169551388}, { 0.000329E-6, 29.821438149, 6.106912080}, { 0.000357E-6, 6309.374169791, 4.223760346}, { 0.000312E-6, -3738.761430108, 2.180556645}, { 0.000301E-6, 309.278322656, 1.499984572}, { 0.000268E-6, 12043.574281889, 2.447520648}, { 0.000257E-6, 12491.370101415, 3.662331761}, { 0.000290E-6, 625.670192312, 1.272834584}, { 0.000256E-6, 5429.879468239, 1.913426912}, { 0.000339E-6, 3496.032826134, 4.165930011}, { 0.000283E-6, 3930.209696220, 4.325565754}, { 0.000241E-6, 12528.018664345, 3.832324536}, { 0.000304E-6, 4686.889407707, 1.612348468}, { 0.000259E-6, 16200.772724501, 3.470173146}, { 0.000238E-6, 12139.553509107, 1.147977842}, { 0.000236E-6, 6172.869528772, 3.776271728}, { 0.000296E-6, -7058.598461315, 0.460368852}, { 0.000306E-6, 10575.406682942, 0.554749016}, { 0.000251E-6, 17298.182327326, 0.834332510}, { 0.000290E-6, 4732.030627343, 4.759564091}, { 0.000261E-6, 5884.926846583, 0.298259862}, { 0.000249E-6, 5547.199336460, 3.749366406}, { 0.000213E-6, 11712.955318231, 5.415666119}, { 0.000223E-6, 4701.116501708, 2.703203558}, { 0.000268E-6, -640.877607382, 0.283670793}, { 0.000209E-6, 5636.065016677, 1.238477199}, { 0.000193E-6, 10177.257679534, 1.943251340}, { 0.000182E-6, 6283.143160294, 2.456157599}, { 0.000184E-6, -227.526189440, 5.888038582}, { 0.000182E-6, -6283.008539689, 0.241332086}, { 0.000228E-6, -6284.056171060, 2.657323816}, { 0.000166E-6, 7238.675591600, 5.930629110}, { 0.000167E-6, 3097.883822726, 5.570955333}, { 0.000159E-6, -323.505416657, 5.786670700}, { 0.000154E-6, -4136.910433516, 1.517805532}, { 0.000176E-6, 12029.347187887, 3.139266834}, { 0.000167E-6, 12132.439962106, 3.556352289}, { 0.000153E-6, 202.253395174, 1.463313961}, { 0.000157E-6, 17267.268201691, 1.586837396}, { 0.000142E-6, 83996.847317911, 0.022670115}, { 0.000152E-6, 17260.154654690, 0.708528947}, { 0.000144E-6, 6084.003848555, 5.187075177}, { 0.000135E-6, 5756.566278634, 1.993229262}, { 0.000134E-6, 5750.203491159, 3.457197134}, { 0.000144E-6, 5326.786694021, 6.066193291}, { 0.000160E-6, 11015.106477335, 1.710431974}, { 0.000133E-6, 3634.621024518, 2.836451652}, { 0.000134E-6, 18073.704938650, 5.453106665}, { 0.000134E-6, 1162.474704408, 5.326898811}, { 0.000128E-6, 5642.198242609, 2.511652591}, { 0.000160E-6, 632.783739313, 5.628785365}, { 0.000132E-6, 13916.019109642, 0.819294053}, { 0.000122E-6, 14314.168113050, 5.677408071}, { 0.000125E-6, 12359.966151546, 5.251984735}, { 0.000121E-6, 5749.452731634, 2.210924603}, { 0.000136E-6, -245.831646229, 1.646502367}, { 0.000120E-6, 5757.317038160, 3.240883049}, { 0.000134E-6, 12146.667056108, 3.059480037}, { 0.000137E-6, 6206.809778716, 1.867105418}, { 0.000141E-6, 17253.041107690, 2.069217456}, { 0.000129E-6, -7477.522860216, 2.781469314}, { 0.000116E-6, 5540.085789459, 4.281176991}, { 0.000116E-6, 9779.108676125, 3.320925381}, { 0.000129E-6, 5237.921013804, 3.497704076}, { 0.000113E-6, 5959.570433334, 0.983210840}, { 0.000122E-6, 6282.095528923, 2.674938860}, { 0.000140E-6, -11.045700264, 4.957936982}, { 0.000108E-6, 23543.230504682, 1.390113589}, { 0.000106E-6, -12569.674818332, 0.429631317}, { 0.000110E-6, -266.607041722, 5.501340197}, { 0.000115E-6, 12559.038152982, 4.691456618}, { 0.000134E-6, -2388.894020449, 0.577313584}, { 0.000109E-6, 10440.274292604, 6.218148717}, { 0.000102E-6, -543.918059096, 1.477842615}, { 0.000108E-6, 21228.392023546, 2.237753948}, { 0.000101E-6, -4535.059436924, 3.100492232}, { 0.000103E-6, 76.266071276, 5.594294322}, { 0.000104E-6, 949.175608970, 5.674287810}, { 0.000101E-6, 13517.870106233, 2.196632348}, { 0.000100E-6, 11933.367960670, 4.056084160}, { 4.322990E-6, 6283.075849991, 2.642893748}, { 0.406495E-6, 0.000000000, 4.712388980}, { 0.122605E-6, 12566.151699983, 2.438140634}, { 0.019476E-6, 213.299095438, 1.642186981}, { 0.016916E-6, 529.690965095, 4.510959344}, { 0.013374E-6, -3.523118349, 1.502210314}, { 0.008042E-6, 26.298319800, 0.478549024}, { 0.007824E-6, 155.420399434, 5.254710405}, { 0.004894E-6, 5746.271337896, 4.683210850}, { 0.004875E-6, 5760.498431898, 0.759507698}, { 0.004416E-6, 5223.693919802, 6.028853166}, { 0.004088E-6, -7.113547001, 0.060926389}, { 0.004433E-6, 77713.771467920, 3.627734103}, { 0.003277E-6, 18849.227549974, 2.327912542}, { 0.002703E-6, 6062.663207553, 1.271941729}, { 0.003435E-6, -775.522611324, 0.747446224}, { 0.002618E-6, 6076.890301554, 3.633715689}, { 0.003146E-6, 206.185548437, 5.647874613}, { 0.002544E-6, 1577.343542448, 6.232904270}, { 0.002218E-6, -220.412642439, 1.309509946}, { 0.002197E-6, 5856.477659115, 2.407212349}, { 0.002897E-6, 5753.384884897, 5.863842246}, { 0.001766E-6, 426.598190876, 0.754113147}, { 0.001738E-6, -796.298006816, 2.714942671}, { 0.001695E-6, 522.577418094, 2.629369842}, { 0.001584E-6, 5507.553238667, 1.341138229}, { 0.001503E-6, -242.728603974, 0.377699736}, { 0.001552E-6, -536.804512095, 2.904684667}, { 0.001370E-6, -398.149003408, 1.265599125}, { 0.001889E-6, -5573.142801634, 4.413514859}, { 0.001722E-6, 6069.776754553, 2.445966339}, { 0.001124E-6, 1059.381930189, 5.041799657}, { 0.001258E-6, 553.569402842, 3.849557278}, { 0.000831E-6, 951.718406251, 2.471094709}, { 0.000767E-6, 4694.002954708, 5.363125422}, { 0.000756E-6, 1349.867409659, 1.046195744}, { 0.000775E-6, -11.045700264, 0.245548001}, { 0.000597E-6, 2146.165416475, 4.543268798}, { 0.000568E-6, 5216.580372801, 4.178853144}, { 0.000711E-6, 1748.016413067, 5.934271972}, { 0.000499E-6, 12036.460734888, 0.624434410}, { 0.000671E-6, -1194.447010225, 4.136047594}, { 0.000488E-6, 5849.364112115, 2.209679987}, { 0.000621E-6, 6438.496249426, 4.518860804}, { 0.000495E-6, -6286.598968340, 1.868201275}, { 0.000456E-6, 5230.807466803, 1.271231591}, { 0.000451E-6, 5088.628839767, 0.084060889}, { 0.000435E-6, 5643.178563677, 3.324456609}, { 0.000387E-6, 10977.078804699, 4.052488477}, { 0.000547E-6, 161000.685737473, 2.841633844}, { 0.000522E-6, 3154.687084896, 2.171979966}, { 0.000375E-6, 5486.777843175, 4.983027306}, { 0.000421E-6, 5863.591206116, 4.546432249}, { 0.000439E-6, 7084.896781115, 0.522967921}, { 0.000309E-6, 2544.314419883, 3.172606705}, { 0.000347E-6, 4690.479836359, 1.479586566}, { 0.000317E-6, 801.820931124, 3.553088096}, { 0.000262E-6, 419.484643875, 0.606635550}, { 0.000248E-6, 6836.645252834, 3.014082064}, { 0.000245E-6, -1592.596013633, 5.519526220}, { 0.000225E-6, 4292.330832950, 2.877956536}, { 0.000214E-6, 7234.794256242, 1.605227587}, { 0.000205E-6, 5767.611978898, 0.625804796}, { 0.000180E-6, 10447.387839604, 3.499954526}, { 0.000229E-6, 199.072001436, 5.632304604}, { 0.000214E-6, 639.897286314, 5.960227667}, { 0.000175E-6, -433.711737877, 2.162417992}, { 0.000209E-6, 515.463871093, 2.322150893}, { 0.000173E-6, 6040.347246017, 2.556183691}, { 0.000184E-6, 6309.374169791, 4.732296790}, { 0.000227E-6, 149854.400134205, 5.385812217}, { 0.000154E-6, 8031.092263058, 5.120720920}, { 0.000151E-6, 5739.157790895, 4.815000443}, { 0.000197E-6, 7632.943259650, 0.222827271}, { 0.000197E-6, 74.781598567, 3.910456770}, { 0.000138E-6, 6055.549660552, 1.397484253}, { 0.000149E-6, -6127.655450557, 5.333727496}, { 0.000137E-6, 3894.181829542, 4.281749907}, { 0.000135E-6, 9437.762934887, 5.979971885}, { 0.000139E-6, -2352.866153772, 4.715630782}, { 0.000142E-6, 6812.766815086, 0.513330157}, { 0.000120E-6, -4705.732307544, 0.194160689}, { 0.000131E-6, -71430.695617928, 0.000379226}, { 0.000124E-6, 6279.552731642, 2.122264908}, { 0.000108E-6, -6256.777530192, 0.883445696}, { 0.143388E-6, 6283.075849991, 1.131453581}, { 0.006671E-6, 12566.151699983, 0.775148887}, { 0.001480E-6, 155.420399434, 0.480016880}, { 0.000934E-6, 213.299095438, 6.144453084}, { 0.000795E-6, 529.690965095, 2.941595619}, { 0.000673E-6, 5746.271337896, 0.120415406}, { 0.000672E-6, 5760.498431898, 5.317009738}, { 0.000389E-6, -220.412642439, 3.090323467}, { 0.000373E-6, 6062.663207553, 3.003551964}, { 0.000360E-6, 6076.890301554, 1.918913041}, { 0.000316E-6, -21.340641002, 5.545798121}, { 0.000315E-6, -242.728603974, 1.884932563}, { 0.000278E-6, 206.185548437, 1.266254859}, { 0.000238E-6, -536.804512095, 4.532664830}, { 0.000185E-6, 522.577418094, 4.578313856}, { 0.000245E-6, 18849.227549974, 0.587467082}, { 0.000180E-6, 426.598190876, 5.151178553}, { 0.000200E-6, 553.569402842, 5.355983739}, { 0.000141E-6, 5223.693919802, 1.336556009}, { 0.000104E-6, 5856.477659115, 4.239842759}, { 0.003826E-6, 6283.075849991, 5.705257275}, { 0.000303E-6, 12566.151699983, 5.407132842}, { 0.000209E-6, 155.420399434, 1.989815753} }; /* -------------------------------------------------------------------- */ /* Local Variables: */ double t, tsol, w, elsun, emsun, d, elj, els, wt, w0, w1, w2, w3, w4, wf, wj; int i; /* Time since J2000.0 in Julian millennia. */ t = ( tdb - 51544.5 )/365250; /* -------------------- Topocentric terms ----------------------------- */ /* Convert UT1 to local solar time in radians. */ tsol = fmod( ut1, 1.0 )*D2PI - wl; /* FUNDAMENTAL ARGUMENTS: Simon et al 1994 */ /* Combine time argument (millennia ) with deg/arcsec factor. */ w = t / 3600.0; /* Sun Mean Longitude. */ elsun = fmod( 280.46645683 + 1296027711.03429*w, 360.0 )*D2R; /* Sun Mean Anomaly. */ emsun = fmod( 357.52910918 + 1295965810.481*w, 360.0 )*D2R; /* Mean Elongation of Moon from Sun. */ d = fmod( 297.85019547 + 16029616012.090*w, 360.0 )*D2R; /* Mean Longitude of Jupiter. */ elj = fmod( 34.35151874 + 109306899.89453*w, 360.0 )*D2R; /* Mean Longitude of Saturn. */ els = fmod( 50.07744430 + 44046398.47038*w, 360.0 )*D2R; /* TOPOCENTRIC TERMS: Moyer 1981 and Murray 1983. */ wt = + 0.00029E-10*u*sin( tsol + elsun - els ) + 0.00100E-10*u*sin( tsol - 2*emsun ) + 0.00133E-10*u*sin( tsol - d ) + 0.00133E-10*u*sin( tsol + elsun - elj ) - 0.00229E-10*u*sin( tsol + 2*elsun + emsun ) - 0.0220E-10*v*cos( elsun + emsun ) + 0.05312E-10*u*sin( tsol - emsun ) - 0.13677E-10*u*sin( tsol + 2*elsun ) - 1.3184E-10*v*cos( elsun ) + 3.17679E-10*u*sin( tsol ); /* --------------- Fairhead model --------------------------------------- */ /* t**0 */ w0 = 0; for( i = 473; i >= 0; i-- ) { w0 = w0 + fairhd[ i ][ 0 ]*sin( fairhd[ i ][ 1 ]*t + fairhd[ i ][ 2 ] ); } /* t**1 */ w1 = 0; for( i = 678; i >= 474; i-- ) { w1 = w1 + fairhd[ i ][ 0 ]*sin( fairhd[ i ][ 1 ]*t + fairhd[ i ][ 2 ] ); } /* t**2 */ w2 = 0; for( i = 763; i >= 679; i-- ) { w2 = w2 + fairhd[ i ][ 0 ]*sin( fairhd[ i ][ 1 ]*t + fairhd[ i ][ 2 ] ); } /* t**3 */ w3 = 0; for( i = 783; i >= 764; i-- ) { w3 = w3 + fairhd[ i ][ 0 ]*sin( fairhd[ i ][ 1 ]*t + fairhd[ i ][ 2 ] ); } /* t**4 */ w4 = 0; for( i = 786; i >= 784; i-- ) { w4 = w4 + fairhd[ i ][ 0 ]*sin( fairhd[ i ][ 1 ]*t + fairhd[ i ][ 2 ] ); } /* Multiply by powers of T and combine. */ wf = t*( t*( t*( t*w4 + w3 ) + w2 ) + w1 ) + w0; /* Adjustments to use JPL planetary masses instead of IAU. */ wj = 0.00065E-6 * sin( 6069.776754 *t + 4.021194 ) + 0.00033E-6 * sin( 213.299095 *t + 5.543132 ) + ( -0.00196E-6 * sin( 6208.294251 *t + 5.696701 ) ) + ( -0.00173E-6 * sin( 74.781599 *t + 2.435900 ) ) + 0.03638E-6*t*t; /* -------------------------------------------------------------------- */ /* Final result: TDB-TT in seconds. */ return wt + wf + wj; } static void TimeAdd( AstTimeMap *this, const char *cvt, const double args[], int *status ) { /* *++ * Name: c astTimeAdd f AST_TIMEADD * Purpose: * Add a time coordinate conversion to a TimeMap. * Type: * Public virtual function. * Synopsis: c #include "timemap.h" c void astTimeAdd( AstTimeMap *this, const char *cvt, const double args[] ) f CALL AST_TIMEADD( THIS, CVT, ARGS, STATUS ) * Class Membership: * TimeMap method. * Description: c This function adds one of the standard time coordinate f This routine adds one of the standard time coordinate * system conversions listed below to an existing TimeMap. * c When a TimeMap is first created (using astTimeMap), it simply f When a TimeMap is first created (using AST_TIMEMAP), it simply c performs a unit (null) Mapping. By using astTimeAdd (repeatedly f performs a unit (null) Mapping. By using AST_TIMEADD (repeatedly * if necessary), one or more coordinate conversion steps may then * be added, which the TimeMap will perform in sequence. This allows * multi-step conversions between a variety of time coordinate * systems to be assembled out of the building blocks provided by * this class. * * Normally, if a TimeMap's Invert attribute is zero (the default), * then its forward transformation is performed by carrying out * each of the individual coordinate conversions specified by c astTimeAdd in the order given (i.e. with the most recently added f AST_TIMEADD in the order given (i.e. with the most recently added * conversion applied last). * * This order is reversed if the TimeMap's Invert attribute is * non-zero (or if the inverse transformation is requested by any * other means) and each individual coordinate conversion is also * replaced by its own inverse. This process inverts the overall * effect of the TimeMap. In this case, the first conversion to be * applied would be the inverse of the one most recently added. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the TimeMap. c cvt f CVT = CHARACTER * ( * ) (Given) c Pointer to a null-terminated string which identifies the f A character string which identifies the * time coordinate conversion to be added to the * TimeMap. See the "Available Conversions" section for details of * those available. c args f ARGS( * ) = DOUBLE PRECISION (Given) * An array containing argument values for the time * coordinate conversion. The number of arguments required, and * hence the number of array elements used, depends on the * conversion specified (see the "Available Conversions" * section). This array is ignored c and a NULL pointer may be supplied * if no arguments are needed. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - When assembling a multi-stage conversion, it can sometimes be * difficult to determine the most economical conversion path. A solution * to this is to include all the steps which are (logically) necessary, * but then to use c astSimplify to simplify the resulting f AST_SIMPLIFY to simplify the resulting * TimeMap. The simplification process will eliminate any steps * which turn out not to be needed. c - This function does not check to ensure that the sequence of f - This routine does not check to ensure that the sequence of * coordinate conversions added to a TimeMap is physically * meaningful. * Available Conversions: * The following strings (which are case-insensitive) may be supplied c via the "cvt" parameter to indicate which time coordinate f via the CVT argument to indicate which time coordinate * conversion is to be added to the TimeMap. Where arguments are needed by * the conversion, they are listed in parentheses. Values for c these arguments should be given, via the "args" array, in the f these arguments should be given, via the ARGS array, in the * order indicated. Units and argument names are described at the end of * the list of conversions, and "MJD" means Modified Julian Date. * * - "MJDTOMJD" (MJDOFF1,MJDOFF2): Convert MJD from one offset to another. * - "MJDTOJD" (MJDOFF,JDOFF): Convert MJD to Julian Date. * - "JDTOMJD" (JDOFF,MJDOFF): Convert Julian Date to MJD. * - "MJDTOBEP" (MJDOFF,BEPOFF): Convert MJD to Besselian epoch. * - "BEPTOMJD" (BEPOFF,MJDOFF): Convert Besselian epoch to MJD. * - "MJDTOJEP" (MJDOFF,JEPOFF): Convert MJD to Julian epoch. * - "JEPTOMJD" (JEPOFF,MJDOFF): Convert Julian epoch to MJD. * - "TAITOUTC" (MJDOFF): Convert a TAI MJD to a UTC MJD. * - "UTCTOTAI" (MJDOFF): Convert a UTC MJD to a TAI MJD. * - "TAITOTT" (MJDOFF): Convert a TAI MJD to a TT MJD. * - "TTTOTAI" (MJDOFF): Convert a TT MJD to a TAI MJD. * - "TTTOTDB" (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD. * - "TDBTOTT" (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD. * - "TTTOTCG" (MJDOFF): Convert a TT MJD to a TCG MJD. * - "TCGTOTT" (MJDOFF): Convert a TCG MJD to a TT MJD. * - "TDBTOTCB" (MJDOFF): Convert a TDB MJD to a TCB MJD. * - "TCBTOTDB" (MJDOFF): Convert a TCB MJD to a TDB MJD. * - "UTTOGMST" (MJDOFF): Convert a UT MJD to a GMST MJD. * - "GMSTTOUT" (MJDOFF): Convert a GMST MJD to a UT MJD. * - "GMSTTOLMST" (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. * - "LMSTTOGMST" (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. * - "LASTTOLMST" (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. * - "LMSTTOLAST" (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. * - "UTTOUTC" (DUT1): Convert a UT1 MJD to a UTC MJD. * - "UTCTOUT" (DUT1): Convert a UTC MJD to a UT1 MJD. * - "LTTOUTC" (LTOFF): Convert a Local Time MJD to a UTC MJD. * - "UTCTOLT" (LTOFF): Convert a UTC MJD to a Local Time MJD. * * The units for the values processed by the above conversions are as * follows: * * - Julian epochs and offsets: Julian years * - Besselian epochs and offsets: Tropical years * - Modified Julian Dates and offsets: days * - Julian Dates and offsets: days * * The arguments used in the above conversions are the zero-points * used by the c astTransform function. f AST_TRANSFORM routine. * The axis values supplied and returned by c astTransform f AST_TRANSFORM * are offsets away from these zero-points: * * - MJDOFF: The zero-point being used with MJD values. * - JDOFF: The zero-point being used with Julian Date values. * - BEPOFF: The zero-point being used with Besselian epoch values. * - JEPOFF: The zero-point being used with Julian epoch values. * - OBSLON: Observer longitude in radians (+ve westwards). * - OBSLAT: Observer geodetic latitude (IAU 1975) in radians (+ve northwards). * - OBSALT: Observer geodetic altitude (IAU 1975) in metres. * - DUT1: The UT1-UTC value to use. * - LTOFF: The offset between Local Time and UTC (in hours, positive * for time zones east of Greenwich). *-- */ /* Local Variables: */ int cvttype; /* Conversion type code */ /* Check the inherited status. */ if ( !astOK ) return; /* Validate the type string supplied and obtain the equivalent conversion type code. */ cvttype = CvtCode( cvt, status ); /* If the string was not recognised, then report an error. */ if ( astOK && ( cvttype == AST__TIME_NULL ) ) { astError( AST__TIMIN, "%s(%s): Invalid TimeMap time coordinate " "conversion type \"%s\".", status, "astAddTime", astGetClass( this ), cvt ); } /* Add the new conversion to the TimeMap. */ AddTimeCvt( this, cvttype, args, status ); } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a TimeMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "timemap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * TimeMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a TimeMap and a set of points encapsulated * in a PointSet and transforms the points so as to perform the * sequence of time coordinate conversions specified by * previous invocations of astTimeAdd. * Parameters: * this * Pointer to the TimeMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the TimeMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstTimeMap *map; /* Pointer to TimeMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *args; /* Pointer to argument list for conversion */ double *time; /* Pointer to output time axis value array */ double gmstx; /* GMST offset (in days) */ double tai; /* Absolute TAI value (in days) */ double tdb; /* Absolute TDB value (in days) */ double tt; /* Absolute TT value (in days) */ double utc; /* Absolute UTC value (in days) */ int ct; /* Conversion type */ int cvt; /* Loop counter for conversions */ int end; /* Termination index for conversion loop */ int inc; /* Increment for conversion loop */ int ncoord_in; /* Number of coordinates per input point */ int npoint; /* Number of points */ int point; /* Loop counter for points */ int start; /* Starting index for conversion loop */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the TimeMap. */ map = (AstTimeMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the coordinate conversions needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse transformation, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( this ) ) forward = !forward; /* Transform the coordinate values. */ /* -------------------------------- */ /* Use "time" as a synonym for the array of time axis values stored in the output PointSet. */ if ( astOK ) { time = ptr_out[ 0 ]; /* Initialise the output coordinate values by copying the input ones. */ if( time != ptr_in[ 0 ] ) { (void) memcpy( time, ptr_in[ 0 ], sizeof( double ) * (size_t) npoint ); } /* We will loop to apply each time coordinate conversion in turn to the (time) array. However, if the inverse transformation was requested, we must loop through these transformations in reverse order, so set up appropriate limits and an increment to control this loop. */ start = forward ? 0 : map->ncvt - 1; end = forward ? map->ncvt : -1; inc = forward ? 1 : -1; /* Loop through the coordinate conversions in the required order and obtain a pointer to the argument list for the current conversion. */ for ( cvt = start; cvt != end; cvt += inc ) { args = map->cvtargs[ cvt ]; /* Classify the SLALIB sky coordinate conversion to be applied. */ ct = map->cvttype[ cvt ]; switch ( ct ) { /* MJD to MJD. */ /* ---------- */ case AST__MJDTOMJD: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 2 ]; } } } break; /* MJD to JD. */ /* ---------- */ case AST__MJDTOJD: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 2 ]; } } } break; /* JD to MJD. */ /* ---------- */ case AST__JDTOMJD: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 2 ]; } } } break; /* MJD to Besselian epoch. */ /* ----------------------- */ case AST__MJDTOBEP: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpb( time[ point ] ) + args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpb2d( time[ point ] ) + args[ 3 ]; } } } break; /* Besselian epoch to MJD. */ /* ----------------------- */ case AST__BEPTOMJD: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpb2d( time[ point ] ) + args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpb( time[ point ] ) + args[ 3 ]; } } } break; /* MJD to Julian epoch. */ /* -------------------- */ case AST__MJDTOJEP: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpj( time[ point ] ) + args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpj2d( time[ point ] ) + args[ 3 ]; } } } break; /* Julian epoch to MJD. */ /* -------------------- */ case AST__JEPTOMJD: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpj2d( time[ point ] ) + args[ 2 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = palEpj( time[ point ] ) + args[ 3 ]; } } } break; /* TAI to UTC. */ /* ----------- */ case AST__TAITOUTC: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += astDat( time[ point ] + args[ 0 ], 0 )/SPD; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += astDat( time[ point ] + args[ 0 ], 1 )/SPD; } } } break; /* UTC to TAI. */ /* ----------- */ case AST__UTCTOTAI: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += astDat( time[ point ] + args[ 0 ], 1 )/SPD; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += astDat( time[ point ] + args[ 0 ], 0 )/SPD; } } } break; /* TAI to TT. */ /* ---------- */ case AST__TAITOTT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += (TTOFF/SPD); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= (TTOFF/SPD); } } } break; /* TT to TAI. */ /* ---------- */ case AST__TTTOTAI: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= (TTOFF/SPD); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += (TTOFF/SPD); } } } break; /* TT to TDB. */ /* ---------- */ /* For the purpose of estimating TDB-TT, we assume UTC is a good approximation to UT1, and that TT is a good approximation to TDB. */ case AST__TTTOTDB: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { tt = time[ point ] + args[ 0 ]; tai = tt - (TTOFF/SPD); utc = tai + astDat( tai, 0 )/SPD; time[ point ] += Rcc( tt, utc, args[ 1 ], args[ 4 ], args[ 5 ], status )/SPD; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { tdb = time[ point ] + args[ 0 ]; tai = tdb - (TTOFF/SPD); utc = tai + astDat( tai, 0 )/SPD; time[ point ] -= Rcc( tdb, utc, args[ 1 ], args[ 4 ], args[ 5 ], status )/SPD; } } } break; /* TDB to TT. */ /* ---------- */ /* For the purpose of estimating TDB-TT, we assume UTC is a good approximation to UT1, and that TT is a good approximation to TDB. */ case AST__TDBTOTT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { tdb = time[ point ] + args[ 0 ]; tai = tdb - (TTOFF/SPD); utc = tai + astDat( tai, 0 )/SPD; time[ point ] -= Rcc( tdb, utc, args[ 1 ], args[ 4 ], args[ 5 ], status )/SPD; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { tt = time[ point ] + args[ 0 ]; tai = tt - (TTOFF/SPD); utc = tai + astDat( tai, 0 )/SPD; time[ point ] += Rcc( tt, utc, args[ 1 ], args[ 4 ], args[ 5 ], status )/SPD; } } } break; /* TT to TCG. */ /* ---------- */ case AST__TTTOTCG: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += time[ point ]*LG + args[ 1 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = ( time[ point ] - args[ 1 ] ) / ( 1.0 + LG ); } } } break; /* TCG to TT. */ /* ---------- */ case AST__TCGTOTT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = ( time[ point ] - args[ 1 ] ) / ( 1.0 + LG ); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += time[ point ]*LG + args[ 1 ]; } } } break; /* TDB to TCB. */ /* ----------- */ /* For the purpose of estimating TDB-TT, we assume UTC is a good approximation to UT1, and that TT is a good approximation to both TDB and TCB. */ case AST__TDBTOTCB: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += time[ point ]*LB + args[ 1 ]; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = ( time[ point ] - args[ 1 ] ) / ( 1.0 + LB ); } } } break; /* TCB to TDB. */ /* ----------- */ /* For the purpose of estimating TDB-TT, we assume UTC is a good approximation to UT1, and that TT is a good approximation to TDB. */ case AST__TCBTOTDB: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = ( time[ point ] - args[ 1 ] ) / ( 1.0 + LB ); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += time[ point ]*LB + args[ 1 ]; } } } break; /* UT to GMST . */ /* ------------ */ case AST__UTTOGMST: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = Gmsta( time[ point ], args[ 0 ], 1, status ); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = Gmsta( time[ point ], args[ 0 ], 0, status ); } } } break; /* GMST to UT. */ /* ----------- */ case AST__GMSTTOUT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = Gmsta( time[ point ], args[ 0 ], 0, status ); } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] = Gmsta( time[ point ], args[ 0 ], 1, status ); } } } break; /* GMST to LMST. */ /* ------------- */ case AST__GMSTTOLMST: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 1 ]/D2PI; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 1 ]/D2PI; } } } break; /* LMST to GMST. */ /* ------------- */ case AST__LMSTTOGMST: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 1 ]/D2PI; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 1 ]/D2PI; } } } break; /* UT1 to UTC. */ /* ------------- */ case AST__UTTOUTC: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 0 ]/86400.0; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 0 ]/86400.0; } } } break; /* UTC to UT1. */ /* ------------- */ case AST__UTCTOUT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 0 ]/86400.0; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 0 ]/86400.0; } } } break; /* LT to UTC. */ /* ---------- */ case AST__LTTOUTC: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 0 ]/24.0; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 0 ]/24.0; } } } break; /* UTC to LT. */ /* ---------- */ case AST__UTCTOLT: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] += args[ 0 ]/24.0; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { time[ point ] -= args[ 0 ]/24.0; } } } break; /* LMST to LAST. */ /* ------------- */ /* Calculating the equation of the equinoxes required TDB. So we need to convert the given LMST to TDB. We first convert LMST to UT1. UT1 is equal to UTC to within 1 second. We then add on 32 seconds to get TAI (this value is correct since 1999 - for earlier epochs an error of the order of a minute will be introduced in the TAI value). We then add on TTOFF seconds to get TT. This TT is then used as an approximation to TDB. The total error in TDB is of the order of a few minutes, which corresponds to an error of a few tens of microseconds in the equation of the equinoxes. The sla precession-nutation model is accurate to around 3 mas = 200 us, so the error in TDB will be insignificant. */ case AST__LMSTTOLAST: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { gmstx = time[ point ] + args[ 1 ]/D2PI; tdb = Gmsta( gmstx, args[ 0 ], 0, status ) + args[ 0 ] + (32 + TTOFF)/SPD; time[ point ] += palEqeqx( tdb )/D2PI; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { gmstx = time[ point ] + args[ 1 ]/D2PI; tdb = Gmsta( gmstx, args[ 0 ], 0, status ) + args[ 0 ] + (32+TTOFF)/SPD; time[ point ] -= palEqeqx( tdb )/D2PI; } } } break; /* LAST to LMST. */ /* ------------- */ case AST__LASTTOLMST: if ( forward ) { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { gmstx = time[ point ] + args[ 1 ]/D2PI; tdb = Gmsta( gmstx, args[ 0 ], 0, status ) + args[ 0 ] + (32+TTOFF)/SPD; time[ point ] -= palEqeqx( tdb )/D2PI; } } } else { for ( point = 0; point < npoint; point++ ) { if ( time[ point ] != AST__BAD ) { gmstx = time[ point ] + args[ 1 ]/D2PI; tdb = Gmsta( gmstx, args[ 0 ], 0, status ) + args[ 0 ] + (32 + TTOFF)/SPD; time[ point ] += palEqeqx( tdb )/D2PI; } } } } } } /* 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; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for TimeMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for TimeMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstTimeMap *in; /* Pointer to input TimeMap */ AstTimeMap *out; /* Pointer to output TimeMap */ int cvt; /* Loop counter for coordinate conversions */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output TimeMap structures. */ in = (AstTimeMap *) objin; out = (AstTimeMap *) objout; /* For safety, first clear any references to the input memory from the output TimeMap. */ out->cvtargs = NULL; out->cvttype = NULL; /* Allocate memory for the output array of argument list pointers. */ out->cvtargs = astMalloc( sizeof( double * ) * (size_t) in->ncvt ); /* If necessary, allocate memory and make a copy of the input array of coordinate conversion codes. */ if ( in->cvttype ) out->cvttype = astStore( NULL, in->cvttype, sizeof( int ) * (size_t) in->ncvt ); /* If OK, loop through each conversion in the input TimeMap and make a copy of its argument list, storing the new pointer in the output argument list array. */ if ( astOK ) { for ( cvt = 0; cvt < in->ncvt; cvt++ ) { out->cvtargs[ cvt ] = astStore( NULL, in->cvtargs[ cvt ], astSizeOf( in->cvtargs[ cvt ] ) ); } /* If an error occurred while copying the argument lists, loop through the conversions again and clean up by ensuring that the new memory allocated for each argument list is freed. */ if ( !astOK ) { for ( cvt = 0; cvt < in->ncvt; cvt++ ) { out->cvtargs[ cvt ] = astFree( out->cvtargs[ cvt ] ); } } } /* If an error occurred, free all other memory allocated above. */ if ( !astOK ) { out->cvtargs = astFree( out->cvtargs ); out->cvttype = astFree( out->cvttype ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for TimeMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for TimeMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstTimeMap *this; /* Pointer to TimeMap */ int cvt; /* Loop counter for coordinate conversions */ /* Obtain a pointer to the TimeMap structure. */ this = (AstTimeMap *) obj; /* Loop to free the memory containing the argument list for each coordinate conversion. */ for ( cvt = 0; cvt < this->ncvt; cvt++ ) { this->cvtargs[ cvt ] = astFree( this->cvtargs[ cvt ] ); } /* Free the memory holding the array of conversion types and the array of argument list pointers. */ this->cvtargs = astFree( this->cvtargs ); this->cvttype = astFree( this->cvttype ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for TimeMap objects. * Type: * Private function. * Synopsis: * #include "timemap.h" * void Dump( AstObject *this, AstChannel *channel, int *status ) * Description: * This function implements the Dump function which writes out data * for the TimeMap class to an output Channel. * Parameters: * this * Pointer to the TimeMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Local Constants: */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstTimeMap *this; /* Pointer to the TimeMap structure */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ const char *sval; /* Pointer to string value */ int iarg; /* Loop counter for arguments */ int icvt; /* Loop counter for conversion steps */ int ival; /* Integer value */ int nargs; /* Number of user-supplied arguments */ int szargs; /* Number of stored arguments */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeMap structure. */ this = (AstTimeMap *) this_object; /* Write out values representing the instance variables for the TimeMap 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. */ /* Number of conversion steps. */ /* --------------------------- */ /* Regard this as "set" if it is non-zero. */ ival = this->ncvt; set = ( ival != 0 ); astWriteInt( channel, "Ntime", set, 0, ival, "Number of conversion steps" ); /* Write out data for each conversion step... */ for ( icvt = 0; icvt < this->ncvt; icvt++ ) { /* Conversion type. */ /* ---------------- */ /* Change each conversion type code into an equivalent string and obtain associated descriptive information. If the conversion code was not recognised, report an error and give up. */ if ( astOK ) { sval = CvtString( this->cvttype[ icvt ], &comment, &nargs, &szargs, argdesc, status ); if ( astOK && !sval ) { astError( AST__TIMIN, "astWrite(%s): Corrupt %s contains invalid TimeMap " "time coordinate conversion code (%d).", status, astGetClass( channel ), astGetClass( this ), (int) this->cvttype[ icvt ] ); break; } /* Create an appropriate keyword and write out the conversion code information. */ (void) sprintf( key, "Time%d", icvt + 1 ); astWriteString( channel, key, 1, 1, sval, comment ); /* Write out data for each conversion argument... */ for ( iarg = 0; iarg < szargs; iarg++ ) { /* Arguments. */ /* ---------- */ /* Create an appropriate keyword and write out the argument value, accompanied by the descriptive comment obtained above. */ if( this->cvtargs[ icvt ][ iarg ] != AST__BAD ) { (void) sprintf( key, "Time%d%c", icvt + 1, ALPHABET[ iarg ] ); astWriteDouble( channel, key, 1, 1, this->cvtargs[ icvt ][ iarg ], argdesc[ iarg ] ); } } /* Quit looping if an error occurs. */ if ( !astOK ) break; } } /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsATimeMap and astCheckTimeMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(TimeMap,Mapping) astMAKE_CHECK(TimeMap) AstTimeMap *astTimeMap_( int flags, const char *options, int *status, ...) { /* *++ * Name: c astTimeMap f AST_TIMEMAP * Purpose: * Create a TimeMap. * Type: * Public function. * Synopsis: c #include "timemap.h" c AstTimeMap *astTimeMap( int flags, const char *options, ... ) f RESULT = AST_TIMEMAP( FLAGS, OPTIONS, STATUS ) * Class Membership: * TimeMap constructor. * Description: * This function creates a new TimeMap and optionally initialises * its attributes. * * A TimeMap is a specialised form of 1-dimensional Mapping which can be * used to represent a sequence of conversions between standard time * coordinate systems. * * When a TimeMap is first created, it simply performs a unit c (null) Mapping. Using the astTimeAdd f (null) Mapping. Using the AST_TIMEADD c function, a series of coordinate conversion steps may then be f routine, a series of coordinate conversion steps may then be * added. This allows multi-step conversions between a variety of * time coordinate systems to be assembled out of a set of building * blocks. * * For details of the individual coordinate conversions available, c see the description of the astTimeAdd function. f see the description of the AST_TIMEADD routine. * Parameters: c flags f FLAGS = INTEGER (Given) c This parameter is reserved for future use and should currently f This argument is reserved for future use and should currently * always be set to zero. 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 TimeMap. 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 TimeMap. 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 astTimeMap() f AST_TIMEMAP = INTEGER * A pointer to the new TimeMap. * Notes: * - The nature and units of the coordinate values supplied for the * first input (i.e. the time input) of a TimeMap must be appropriate * to the first conversion step applied by the TimeMap. For instance, if * the first conversion step is "MJDTOBEP" (Modified Julian Date to * Besselian epoch) then the coordinate values for the first input should * be date in units of days. Similarly, the nature and units of the * coordinate values returned by a TimeMap will be determined by the * last conversion step applied by the TimeMap. * - 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTimeMap *new; /* Pointer to the new TimeMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the TimeMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTimeMap( NULL, sizeof( AstTimeMap ), !class_init, &class_vtab, "TimeMap", flags ); /* 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 TimeMap'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 TimeMap. */ return new; } AstTimeMap *astTimeMapId_( int flags, const char *options, ... ) { /* * Name: * astTimeMapId_ * Purpose: * Create a TimeMap. * Type: * Private function. * Synopsis: * #include "timemap.h" * AstTimeMap *astTimeMapId_( int flags, const char *options, ... ) * Class Membership: * TimeMap constructor. * Description: * This function implements the external (public) interface to the * astTimeMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astTimeMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astTimeMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astTimeMap_. * Returned Value: * The ID value associated with the new TimeMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTimeMap *new; /* Pointer to the new TimeMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the TimeMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTimeMap( NULL, sizeof( AstTimeMap ), !class_init, &class_vtab, "TimeMap", flags ); /* 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 TimeMap'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 TimeMap. */ return astMakeId( new ); } AstTimeMap *astInitTimeMap_( void *mem, size_t size, int init, AstTimeMapVtab *vtab, const char *name, int flags, int *status ) { /* *+ * Name: * astInitTimeMap * Purpose: * Initialise a TimeMap. * Type: * Protected function. * Synopsis: * #include "timemap.h" * AstTimeMap *astInitTimeMap( void *mem, size_t size, int init, * AstTimeMapVtab *vtab, const char *name, * int flags ) * Class Membership: * TimeMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new TimeMap object. It allocates memory (if necessary) to accommodate * the TimeMap plus any additional data associated with the derived class. * It then initialises a TimeMap 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 TimeMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the TimeMap is to be initialised. * This must be of sufficient size to accommodate the TimeMap data * (sizeof(TimeMap)) 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 TimeMap (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 TimeMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the TimeMap'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 TimeMap. * 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 astClass * method). * flags * This parameter is reserved for future use. It is currently ignored. * Returned Value: * A pointer to the new TimeMap. * 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: */ AstTimeMap *new; /* Pointer to the new TimeMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitTimeMapVtab( vtab, name ); /* Initialise a 1D Mapping structure (the parent class) as the first component within the TimeMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstTimeMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 1, 1, 1, 1 ); if ( astOK ) { /* Initialise the TimeMap data. */ /* --------------------------- */ /* The initial state is with no conversions set, in which condition the TimeMap simply implements a unit mapping. */ new->ncvt = 0; new->cvtargs = NULL; new->cvttype = NULL; /* 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; } AstTimeMap *astLoadTimeMap_( void *mem, size_t size, AstTimeMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadTimeMap * Purpose: * Load a TimeMap. * Type: * Protected function. * Synopsis: * #include "timemap.h" * AstTimeMap *astLoadTimeMap( void *mem, size_t size, * AstTimeMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * TimeMap loader. * Description: * This function is provided to load a new TimeMap 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 * TimeMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a TimeMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the TimeMap is to be * loaded. This must be of sufficient size to accommodate the * TimeMap data (sizeof(TimeMap)) 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 TimeMap (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 TimeMap 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(AstTimeMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new TimeMap. If this is NULL, a pointer to * the (static) virtual function table for the TimeMap 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 "TimeMap" is used instead. * Returned Value: * A pointer to the new TimeMap. * 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: */ AstTimeMap *new; /* Pointer to the new TimeMap */ char *sval; /* Pointer to string value */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ int iarg; /* Loop counter for arguments */ int icvt; /* Loop counter for conversion steps */ int nargs; /* Number of user-supplied arguments */ int szargs; /* Number of stored arguments */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this TimeMap. In this case the TimeMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstTimeMap ); vtab = &class_vtab; name = "TimeMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitTimeMapVtab( 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 TimeMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "TimeMap" ); /* 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. */ /* Number of conversion steps. */ /* --------------------------- */ /* Read the number of conversion steps and allocate memory to hold data for each step. */ new->ncvt = astReadInt( channel, "ntime", 0 ); if ( new->ncvt < 0 ) new->ncvt = 0; new->cvttype = astMalloc( sizeof( int ) * (size_t) new->ncvt ); new->cvtargs = astMalloc( sizeof( double * ) * (size_t) new->ncvt ); /* If an error occurred, ensure that all allocated memory is freed. */ if ( !astOK ) { new->cvttype = astFree( new->cvttype ); new->cvtargs = astFree( new->cvtargs ); /* Otherwise, initialise the argument pointer array. */ } else { for ( icvt = 0; icvt < new->ncvt; icvt++ ) { new->cvtargs[ icvt ] = NULL; } /* Read in data for each conversion step... */ for ( icvt = 0; icvt < new->ncvt; icvt++ ) { /* Conversion type. */ /* ---------------- */ /* Create an appropriate keyword and read the string representation of the conversion type. */ (void) sprintf( key, "time%d", icvt + 1 ); sval = astReadString( channel, key, NULL ); /* If no value was read, report an error. */ if ( astOK ) { if ( !sval ) { astError( AST__BADIN, "astRead(%s): A time coordinate conversion " "type is missing from the input TimeMap data.", status, astGetClass( channel ) ); /* Otherwise, convert the string representation into the required conversion type code. */ } else { new->cvttype[ icvt ] = CvtCode( sval, status ); /* If the string was not recognised, report an error. */ if ( new->cvttype[ icvt ] == AST__TIME_NULL ) { astError( AST__BADIN, "astRead(%s): Invalid time conversion " "type \"%s\" in TimeMap data.", status, astGetClass( channel ), sval ); } } /* Free the memory holding the string value. */ sval = astFree( sval ); } /* Obtain the number of arguments associated with the conversion and allocate memory to hold them. */ (void) CvtString( new->cvttype[ icvt ], &comment, &nargs, &szargs, argdesc, status ); new->cvtargs[ icvt ] = astMalloc( sizeof( double ) * (size_t) szargs ); /* Read in data for each argument... */ if ( astOK ) { for ( iarg = 0; iarg < szargs; iarg++ ) { /* Arguments. */ /* ---------- */ /* Create an appropriate keyword and read each argument value. */ (void) sprintf( key, "time%d%c", icvt + 1, ALPHABET[ iarg ] ); new->cvtargs[ icvt ][ iarg ] = astReadDouble( channel, key, AST__BAD ); } } /* Quit looping if an error occurs. */ if ( !astOK ) break; } } /* If an error occurred, clean up by deleting the new TimeMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new TimeMap 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 astTimeAdd_( AstTimeMap *this, const char *cvt, const double args[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,TimeMap,TimeAdd))( this, cvt, args, status ); } ast-8.3.0/grf3d.c0000664000175000017500000000540213004147321010401 00000000000000/* * Name: * grf3d.c * Purpose: * Implement the grf3D interface if no graphics system is available. * Description: * This file implements the low level 3D graphics functions required * by the rest of AST. These implementations simply report an error * when called. * Inheritance: * This module is not a class and does not inherit. * Copyright: * Copyright (C) 2007 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (JACH - UCLan) * History: * 20-JUN-2007 (DSB): * Original version. */ /* Header files */ /* ============ */ #include "grf3d.h" /* Declare the functions in this module */ #include "error.h" /* AST error reporting facilities */ #include "ast_err.h" /* AST error codes */ /* Function Prototypes */ /* =================== */ static void Report( const char * ); /* Function definitions */ /* ==================== */ int astG3DCap( int cap, int value ){ return 0; } int astG3DFlush( void ){ Report( "astG3DFlush"); return 0; } int astG3DLine( int n, float *x, float *y, float *z ){ Report( "astG3DLine" ); return 0; } int astG3DQch( float *ch ){ Report( "astG3DQch" ); return 0; } int astG3DMark( int n, float *x, float *y, float *z, int type, float norm[3] ){ Report( "astG3DMark" ); return 0; } int astG3DText( const char *text, float ref[3], const char *just, float up[3], float norm[3] ){ Report( "astG3DText" ); return 0; } int astG3DTxExt( const char *text, float ref[3], const char *just, float up[3], float norm[3], float *xb, float *yb, float *zb, float bl[3] ){ Report( "astG3DTxExt" ); return 0; } int astG3DAttr( int attr, double value, double *old_value, int prim ){ Report( "astG3DAttr" ); return 0; } static void Report( const char *name ){ astError( AST__GRFER, "%s: No graphics facilities are available.", name ); astError( AST__GRFER, "Re-link using an option such as '-pgplot' with " "the ast_link script." ); } ast-8.3.0/starlink.cls0000664000175000017500000003401412710127547011576 00000000000000% Latex2E class for writing starlink documents. \NeedsTeXFormat{LaTeX2e} \ProvidesClass{starlink} %-----------------------------------------------------% % .. Class options. % With chapters... \newif\ifwithchapters \withchaptersfalse % If twoside... \newif\iftwoside \twosidefalse % If list of figures (lof) \newif\ifwithlof \withloftrue % If no abstract \newif\ifwithabs \withabstrue % If all one page (affects html output only) \newif\ifmultipage \multipagetrue % Declare the options. \DeclareOption{chapters}{\withchapterstrue} \DeclareOption{twoside}{\twosidetrue} \DeclareOption{nolof}{\withloffalse} \DeclareOption{noabs}{\withabsfalse} \DeclareOption{onepage}{\multipagefalse} % Pass all options not defined above to the classes. % (Must be done before process options) \ifwithchapters \typeout{..... passing options to report .....} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{report}} \else \typeout{........passing options to article......} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \fi % Process custom options. \ProcessOptions\relax \ifwithchapters \LoadClass{report} \typeout{........Report!...........} \else \LoadClass{article} \typeout{..........Article!..........} \fi %-------------------------------------- % Packages required for all reports % chek if in a pdf or not \RequirePackage{ifpdf} % Font types and encoding. \RequirePackage[T1]{fontenc} \RequirePackage[utf8]{inputenc} % microtype For improved pdf typography (must come after loading class) \RequirePackage{microtype} %maths \RequirePackage{amsmath} \RequirePackage{mathpazo} % units \RequirePackage{siunitx} % Titlesec. \RequirePackage{titlesec} % Package to allow graphics to be loaded (\includegraphics) and the % default extensions it will look for (and their order). \RequirePackage{graphicx} \DeclareGraphicsExtensions{.pdf,.png,.jpg,.jpeg} %.. Probably needed for something? \RequirePackage{multirow} % formatting of list enivornments \RequirePackage{enumitem} %.. Using color \RequirePackage[usenames,dvipsnames,svgnames,table]{xcolor} %.. Allow boxes with frames and backgrounds, over multiple pages \RequirePackage[framemethod=TikZ]{mdframed} %.. Allow tables on multiple pages \RequirePackage{longtable} %.. Allow sideways tables \RequirePackage{rotating} %.. Allow landscape pdf pages \RequirePackage{pdflscape} %.. Set up the page \RequirePackage[text={160mm,230mm},centering]{geometry} %.. title page formatting \RequirePackage{titling} %... Set up the headers. \RequirePackage{fancyhdr} %.... table of contents formatting \ifpdf \RequirePackage{tocloft} \fi %.. hyperref \RequirePackage[pdfusetitle=true,backref, breaklinks=True,pdfdisplaydoctitle=true]{hyperref} %... allow environments using verbatim \RequirePackage{fancyvrb} %... allow starlink docs to use indexes \RequirePackage{makeidx} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Starlink document identification commands \newcommand{\stardoccategory}[1]{\def \@stardoccategory {#1}} \newcommand{\stardocinitials}[1]{\def \@stardocinitials {#1}} \newcommand{\stardoccopyright}[1]{\def \@stardoccopyright {#1}} \newcommand{\stardocnumber}[1]{\def \@stardocnumber{#1}} % Define a stardoctitle that takes an optional 'short' argument; this % can then be used in various places. E.g. if you have a multi line % full title, please ensure you also have a single line short title. \def\stardoctitle{\@ifnextchar [{\@stardoctitletwo}{\@stardoctitleone}} \def\@stardoctitletwo[#1]#2{\gdef\@stardoctitle{#2}\gdef\@shorttitle{#1}} \def\@stardoctitleone#1{\gdef\@stardoctitle{#1}\gdef\@shorttitle{#1}} \newcommand{\stardocversion}[1]{\def \@stardocversion{#1}} \newcommand{\stardocmanual}[1]{\def \@stardocmanual{#1}} \newcommand{\stardocabstract}[1]{\def \@stardocabstract{#1}} \newcommand{\stardocauthors}[1]{\def\@stardocauthors{#1}} \newcommand{\stardocdate}[1]{\def\@stardocdate{#1}} \newcommand{\startitlepic}[1]{\def\@startitlepic{#1}} \newcommand{\starfunders}[1]{\def\@starfunders{#1}} \newcommand{\starproject}[1]{\def\@starproject{#1}} \newcommand{\stardocsource}[1]{\def\@stardocsource{#1}} \newcommand{\stardocname}[1]{\def\@stardocname{#1}} % Defaults for current data? \starfunders{} \starproject{Starlink Project} % initalise to nothing \stardoccategory{} \stardocinitials{} \stardoccopyright{} \stardocnumber{} \stardoctitle{} \stardocversion{} \stardocmanual{} \stardocabstract{} \stardocauthors{} \startitlepic{} \stardocname{} \stardocauthors{} \stardocdate{} % Provide \the... versions of these commands so you don't need to use @ % in latex. \newcommand{\thestardoccategory}{\@stardoccategory} \newcommand{\thestardocinitials}{\@stardocinitials} \newcommand{\thestardoccopyright}{\@stardoccopyright} \newcommand{\thestardocnumber}{\@stardocnumber} \newcommand{\thestardoctitle}{\@stardoctitle} \newcommand{\theshorttitle}{\@shorttitle} \newcommand{\thestardocversion}{\@stardocversion} \newcommand{\thestardocmanual}{\@stardocmanual} \newcommand{\thestardocabstract}{\@stardocabstract} \newcommand{\thestardocauthors}{\@stardocauthors} \newcommand{\thestarfunders}{\@starfunders} \newcommand{\thestarproject}{\@starproject} \newcommand{\thestartitlepic}{\@startitlepic} \newcommand{\thestardocsource}{\@stardocsource} \newcommand{\thestardocdate}{\@stardocdate} % Ensure the stardoctitle etc is available as \thetitle. \newcommand{\thetitle}{\@stardoctitle} \title{\@stardoctitle} % Ensure the author list is available as \theauthor. \newcommand{\theauthor}{\@stardocauthors} \author{\@stardocauthors} %%-------------------------------------------------------- %% Various commands to setup the frontmatter of starlink docs. %% This should consist of 1) the title, 2) the abstract, 3) the table %% of contents, 4) the list of figures (unless class option nolof is given). %.. Format the initial header. \newcommand{\titleheader}{% \begin{flushright} \textbf{\thestardocinitials /\thestardocnumber} \end{flushright} \thestarproject\\ \thestardoccategory\ \thestardocnumber\\ } %... Format the main ttile \newcommand{\titlemain}{% \begin{center} {\Huge\textbf{\thestardoctitle}} {\Huge\textbf{\thestardocversion}} {\Huge\textbf{\thestardocmanual}} \end{center} } % Graphics for front page \newcommand{\thestargraphics}{% \centering \thestartitlepic \vspace{7.5mm} \rule{\textwidth}{0.5mm}% } % .. Provide a command \startitle page that will produce a consistent % starlink title page \newcommand{\startitlepage}{% \null \vskip 2em% \vspace*{-1\baselineskip} \thispagestyle{empty} \titleheader %\vspace{-7mm} \begin{flushright} \par\thestardocauthors \par\thestardocdate \par\thestardoccopyright \end{flushright} %\vspace{-2mm} \rule{\textwidth}{0.5mm} \vspace{7.5mm} \titlemain%\par %\vspace{5mm} \thestargraphics\\ } %%.. command to print the abstract (with copyright at bottom of page) \newcommand{\Abstract}{% \ifwithabs \ifwithchapters \chapter*{} \fi \section*{Abstract} \thispagestyle{fancy} \markboth{Abstract}{} \thestardocabstract{} \\ \vspace*{\fill} \\ {\small\thestardoccopyright{}} \clearpage \fi } %% General Front matter command -- title page, abstract, toc, lof This %% command \scfrontmatter is what should be called %% after \begin{document} in any starlink tex file. \newcommand*{\scfrontmatter}{ % Use roman page numbers \renewcommand{\thepage}{\roman{page}} \setcounter{page}{1} % Create the titlepage \begin{titlepage}% \startitlepage \end{titlepage} % Show the abstract (defined to do nothing if noabs is set) \Abstract{} \clearpage % Table of contents (catcode stuff to prevent errors with _) \begingroup \catcode`\_=12 \tableofcontents \endgroup \clearpage % unless the class option 'nolof' has been given, create a list of % figures. \ifwithlof \begingroup \catcode`\_=12 \listoffigures \endgroup \fi \clearpage % Reset the page counting to arabic and start from 1. \renewcommand{\thepage}{\arabic{page}} \setcounter{page}{1} } %%%------------------------------------- %% Back matter commands (references and index) % Ensure index shows up in toc. \let\oldprintindex\printindex \renewcommand{\printindex}{% \phantomsection \addcontentsline{toc}{section}{Index} \oldprintindex} %%------------------------------------ %% Various class specific macros %% Starlink list enivornments %% enumdesc: An enumerated description list \newcounter{enumdescc} \newcounter{enumdescci} \newlist{enumdesc}{description}{2} \setlist[enumdesc,1]{% before={\stepcounter{enumdescc}\setcounter{enumdescci}{0}},% style=nextline,leftmargin=0.5cm,labelindent=0.5cm,rightmargin=0.5cm, topsep=0.5\baselineskip, font={% \phantomsection\normalfont\normalsize\bfseries\refstepcounter{enumdescci}\theenumdescci~} } %% A description list which has the labels in a box on the left with %% the length of the widest label, and the definitions aligned past %% it. In HTML output, starstyle.4ht will format this as a table. %% This uses the package eqparbox to get the box of width of the %% widest label (takes 2 runs of pdflatex). \usepackage{eqparbox} \newcounter{desc} \newcommand{\descriptionmakelabel}[1]{\eqparbox{descnb\romannumeral\value{desc}}{#1\hfill}} \newlist{aligndesc}{description}{2} \setlist[aligndesc]{before={\refstepcounter{desc}\renewcommand{\makelabel}{\descriptionmakelabel}}, leftmargin=\dimexpr\eqboxwidth{descnb\romannumeral\numexpr\value{desc}+1\relax}+3em\relax, labelsep=1em, labelindent=2em, rightmargin=2em} %%%-------------------------------------------------------------- %% Linking and referencing commands. %%.. Starlink xref command %% By default use the starlink.ac.uk; this will be fixed up at the %% end of make world by a different program. \newcommand{\xref}[3]{% \href{http://www.starlink.ac.uk/cgi-bin/htxserver/#2.htx/#2.html?xref_#3}{#1}} \newcommand{\xlabel}[1]{\label{\protect{xref_#1}}} \newcommand{\cref}[3]{#1~\ref{#2}} %problems with _ in labels (e.g. in xrefs) \let\oldunderscore\_ \renewcommand{\_}{\ifmmode \oldunderscore \else \string_\fi} %%--------------------------------------------------------------- %% Deprecated commands (for compatability only) % % Graphics commands \newcommand{\starfig}[6]{ \begin{figure}#2 \centering\includegraphics[#3]{#1} \typeout{#1 inserted on page \arabic{page}} \caption[#5]{\label{#4} #6} \end{figure} } % A starlink Hyperref (defined a bit differently to regular hyperref, % and with a first argument that doesn't do anything. Deprecated; only % provided for consistency with old documents. Include the string, not % just the cross reference number or letter in the hyperlink. \newcommand{\slhyperref}[4]{\hyperref[#4]{#2\ref*{#4}#3}} \newcommand{\latexhtml}[2]{#1} % %.. Empty environment latex only. \newenvironment{latexonly}{}{} %%%% Command that doesn't do anything in latex \newcommand{\html}[1]{} %.. environments that don't do anything \def\makeinnocent#1{\catcode`#1=12 } \def\csarg#1#2{\expandafter#1\csname#2\endcsname} \def\ThrowAwayComment#1{\begingroup \def\CurrentComment{#1}% \let\do\makeinnocent \dospecials \makeinnocent\^^L% and whatever other special cases \endlinechar`\^^M \catcode`\^^M=12 \xComment} {\catcode`\^^M=12 \endlinechar=-1 % \gdef\xComment#1^^M{\def\test{#1} \csarg\ifx{PlainEnd\CurrentComment Test}\test \let\html@next\endgroup \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test \edef\html@next{\endgroup\noexpand\end{\CurrentComment}} \else \let\html@next\xComment \fi \fi \html@next} } \def\excludecomment #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}% {\escapechar=-1\relax \csarg\xdef{PlainEnd#1Test}{\string\\end#1}% \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}% }} \excludecomment{htmlonly} \newcommand{\latex}[1]{#1} %------------------------------------------------------------------------ %.. Define additional colours. \definecolor{mygray}{gray}{0.7} \definecolor{MidnightBlue}{RGB}{25, 25, 112} \definecolor{bblue}{RGB}{172,207,230} %-------------------------------------------------- %.. Miscellanous commands %.. Create a command to remove all space from input \def\RemoveSpaces#1{\zap@space#1 \@empty} % % Command for text that should be pushed to the right of the line (eg % % following an hfill, on a single line of text \newcommand*{\scpushright}[1]{\hfill #1} % %.. verbatim environment for quoting terminal. \DefineVerbatimEnvironment{terminalv}{Verbatim}{% xleftmargin=.5in,formatcom=\color{MidnightBlue},fontsize=\small} % command for a text box that floats around and pops out from the text (framed) \mdfsetup{% backgroundcolor=white,% middlelinewidth=4pt,% middlelinecolor=bblue,% userdefinedwidth=0.8\textwidth,% roundcorner=10pt, % innertopmargin=\topskip}% \newenvironment{sltextbox}[1]{% \begin{figure*}[h]\begin{mdframed}[userdefinedwidth=0.8\textwidth, align=center,% frametitle=#1,% frametitlebackgroundcolor=bblue]% \setlength{\parskip}{\medskipamount}% }% {\end{mdframed}\end{figure*}} %Framed boxes (obsolete). \newsavebox{\fmbox} \newenvironment{fmpage}[1]{\begin{lrbox}{\fmbox}\begin{minipage}{#1}}{\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}} %.. Tip box \newenvironment{tip}% {\begin{figure*}[h]\begin{mdframed}[userdefinedwidth=0.8\textwidth,align=center,frametitle=Tip,frametitlebackgroundcolor=bblue]% \setlength{\parskip}{\medskipamount}% }% {\end{mdframed}\end{figure*}} %.. starlink long table (used so that its easier to fix it up for html output) \setlength{\LTcapwidth}{\textwidth} \newenvironment{sllongtable}[2]{% \begin{longtable}{#1}\caption{#2}\\} {\end{longtable}} %......................................... \newcommand{\Acronyms}{% \ifwithchapters \chapter*{} \fi \section*{Acronyms} \markboth{Acronyms}{} \addcontentsline{toc}{section}{\protect\numberline{}Acronyms} } %-------------------------------------------------------------------- %% Load the reamining starlink specific classes. %.. The remaining starlink specific definitions. \RequirePackage{starabbrev} \RequirePackage{starstyle} \RequirePackage{sst} %-------------------------------------------------------------------- ast-8.3.0/starstyle.sty0000664000175000017500000000765412710127547012051 00000000000000\ProvidesPackage{starstyle} %%%% %% Package for styling the output (primarily in pdf) %%%% % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Number sections down to subsubsection level \setcounter{secnumdepth}{4} % %%% Formatting of the section headging \newcommand{\colorsection}[1]{% \colorbox{bblue}{\strut\parbox{\dimexpr\textwidth-2\fboxsep}{\thesection\ \quad #1}{\huge\strut}}} \newcommand{\colorsectionnumberless}[1]{% \colorbox{bblue}{\strut\parbox{\dimexpr\textwidth-2\fboxsep}{#1}\strut}} % % Section headings (including numberless) \ifpdf \titleformat{name=\section}% {\normalfont\Large\bfseries}{}{0pt}{\colorsection} \titleformat{name=\section,numberless}% {\normalfont\Large\bfseries}{}{0pt}{\colorsectionnumberless} \fi %... Chapter headings \ifwithchapters \titleformat{name=\chapter}[display]% {\normalfont\huge\bfseries\thispagestyle{plain}}{% \chaptertitlename\ \thechapter}{0pt}{} \titleformat{name=\chapter,numberless}[display]% {\normalfont\huge\bfseries\thispagestyle{plain}}{}{0pt}{\Huge} %... spacing after chapter headings \titlespacing*{\chapter}{0pt}{0pt}{20pt} \fi %.. section spacing \titlespacing*{\section}{0pt}{3.5ex plus 1ex minus .2ex}{2.3ex plus .2ex} \titlespacing*{\subsection}{0pt}{2ex plus 1ex minus .2ex}{1.5ex plus .2ex} \titlespacing*{\subsubsection}{0pt}{2ex plus 1ex minus .2ex}{1ex plus .2ex} \titlespacing*{\paragraph}{0pt}{2ex plus 1ex minus .2ex}{1em} \titlespacing*{\subparagraph}{\parindent}{2ex plus 1ex minus .2ex}{1em} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% Page styles (e.g. headers and footers) \pagestyle{fancy} \fancyhf{} \rhead{\slshape \thestardocinitials{}/\thestardocnumber{} \leftmark} \lhead{\thepage} \renewcommand{\headrulewidth}{0.0pt} \ifwithchapters \renewcommand{\chaptermark}[1]{ \markboth{#1}{}} \else \renewcommand{\sectionmark}[1]{ \markboth{#1}{}} \fi % .. Reset the plain pagestyle (used on chapter pages) to only have % the page number and no rules. \fancypagestyle{plain}{% \fancyhf{}% \iftwoside \fancyhead[RE,LO]{\thepage}% \fancyhead[LE,RO]{\slshape \thestardocinitials{}/\thestardocnumber{}\nouppercase{---\leftmark}}% \else \fancyhead[LO]{\thepage} \fancyhead[RO]{\slshape \thestardocinitials{}/\thestardocnumber{}\nouppercase{---\leftmark}}% \fi \renewcommand{\headrulewidth}{0pt}% \renewcommand{\footrulewidth}{0pt}% } % ensure correct chaptermakr is used when in pagestyle plain \pagestyle{plain} \fancyhf{} \iftwoside \fancyhead[LE,RO]{\slshape \thestardocinitials{}/\thestardocnumber{} \nouppercase{---\leftmark}} \fancyhead[RE,LO]{\thepage} \else \lhead{\slshape \thestardocinitials{}/\thestardocnumber{} \nouppercase{---\leftmark}} \rhead{\thepage} \fi \renewcommand{\headrulewidth}{0.0pt} \ifwithchapters \renewcommand{\chaptermark}[1]{ \markboth{#1}{}} \else \renewcommand{\sectionmark}[1]{ \markboth{#1}{}} \fi \renewcommand{\headrulewidth}{0pt}% \renewcommand{\footrulewidth}{0pt}% \ifwithchapters \renewcommand{\chaptermark}[1]{\markboth{{#1}}{}}% \else \renewcommand{\sectionmark}[1]{\markboth{{#1}}{}}% \fi %% Select the fancy pagestyle as default \pagestyle{fancy} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % General spacing \setlength{\headheight}{1.5cm} \setlength{\parskip}{\medskipamount} \setlength{\parindent}{0pt} \renewcommand{\arraystretch}{1.5} %%%% Set up defaults for floats % maximum size of 'top area' \renewcommand{\topfraction}{0.9} % maximum size of 'bottom area' \renewcommand{\bottomfraction}{0.9} % minimum amount of text on a non-float page \renewcommand{\textfraction}{0.1} %Enumerate list appearance \setlist[enumerate,1]{label=(\arabic*)} % macros for typesetting parameters \providecommand{\aparam}[1]{\texttt{#1}} % ADAM parameter \providecommand{\cparam}[1]{\texttt{#1}} % CONFIG parameter \providecommand{\ndfcomp}[1]{\texttt{#1}} % NDF component \newcommand{\menuitem}[2]{\item[\protect{\hyperref[#1]{#1}}] #2} \newcommand{\classitem}[1]{\item [\protect{\hyperref[#1]{#1}}]} ast-8.3.0/prism.h0000664000175000017500000001607213004147321010540 00000000000000#if !defined( PRISM_INCLUDED ) /* Include this file only once */ #define PRISM_INCLUDED /* *+ * Name: * prism.h * Type: * C include file. * Purpose: * Define the interface to the Prism class. * Invocation: * #include "prism.h" * Description: * This include file defines the interface to the Prism class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The Prism class implement a Region which represents an extrusion of * another Region into higher dimensions. For instance, a Prism can be * used to represent a cylinder, which is an extrusion of a circle into a * 3rd dimension. * Inheritance: * The Prism class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 17-DEC-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "region.h" /* Coordinate regions (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* Prism structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif typedef struct AstPrism { /* Attributes inherited from the parent class. */ AstRegion region; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstRegion *region1; /* First component Region */ AstRegion *region2; /* Second component Region */ } AstPrism; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPrismVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstPrismVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstPrismGlobals { AstPrismVtab Class_Vtab; int Class_Init; } AstPrismGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitPrismGlobals_( AstPrismGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Prism) /* Check class membership */ astPROTO_ISA(Prism) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPrism *astPrism_( void *, void *, const char *, int *, ...); #else AstPrism *astPrismId_( void *, void *, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPrism *astInitPrism_( void *, size_t, int, AstPrismVtab *, const char *, AstRegion *, AstRegion *, int * ); /* Vtab initialiser. */ void astInitPrismVtab_( AstPrismVtab *, const char *, int * ); /* Loader. */ AstPrism *astLoadPrism_( void *, size_t, AstPrismVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ AstRegion *astConvertToPrism_( AstRegion *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPrism(this) astINVOKE_CHECK(Prism,this,0) #define astVerifyPrism(this) astINVOKE_CHECK(Prism,this,1) /* Test class membership. */ #define astIsAPrism(this) astINVOKE_ISA(Prism,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astPrism astINVOKE(F,astPrism_) #else #define astPrism astINVOKE(F,astPrismId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPrism(mem,size,init,vtab,name,reg1,reg2) \ astINVOKE(O,astInitPrism_(mem,size,init,vtab,name,reg1,reg2,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPrismVtab(vtab,name) astINVOKE(V,astInitPrismVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPrism(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPrism_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckPrism to validate Prism pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astConvertToPrism(this) astConvertToPrism_(this,STATUS_PTR) #endif #endif ast-8.3.0/permmap.h0000664000175000017500000002447513004147321011055 00000000000000#if !defined( PERMMAP_INCLUDED ) /* Include this file only once */ #define PERMMAP_INCLUDED /* *+ * Name: * permmap.h * Type: * C include file. * Purpose: * Define the interface to the PermMap class. * Invocation: * #include "permmap.h" * Description: * This include file defines the interface to the PermMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The PermMap class implements Mappings that perform permutation * of the order of coordinate values, possibly also accompanied by * changes in the number of coordinates (between input and output). * * In addition to permuting the coordinate order, coordinates may * also be assigned constant values which are unrelated to other * coordinate values. This facility is useful when the number of * coordinates is being increased, as it allows fixed values to be * assigned to the new coordinates. * Inheritance: * The PermMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astGetConstants * Obtain a copy of the constants array * astGetInPerm * Obtain a copy of the input permutation array * astGetOutPerm * Obtain a copy of the output permutation array * Other Class Functions: * Public: * astIsAPermMap * Test class membership. * astPermMap * Create a PermMap. * * Protected: * astCheckPermMap * Validate class membership. * astInitPermMap * Initialise a PermMap. * astInitPermMapVtab * Initialise the virtual function table for the PermMap class. * astLoadPermMap * Load a PermMap. * Macros: * None. * Type Definitions: * Public: * AstPermMap * PermMap object type. * * Protected: * AstPermMapVtab * PermMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 29-FEB-1996 (RFWS): * Original version. * 26-SEP-1996 (RFWS): * Added external interface and I/O facilities. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitPermMapVtab * method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* PermMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPermMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ int *inperm; /* Pointer to input permutation array */ int *outperm; /* Pointer to output permutation array */ double *constant; /* Pointer to array of constant values */ int permsplit; /* Method to use within MapSplit */ } AstPermMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPermMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double *(* GetConstants)( AstPermMap *, int * ); int *(* GetInPerm)( AstPermMap *, int * ); int *(* GetOutPerm)( AstPermMap *, int * ); void (* SetPermSplit)( AstPermMap *, int, int * ); void (* ClearPermSplit)( AstPermMap *, int * ); int (* TestPermSplit)( AstPermMap *, int * ); int (* GetPermSplit)( AstPermMap *, int * ); } AstPermMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstPermMapGlobals { AstPermMapVtab Class_Vtab; int Class_Init; } AstPermMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitPermMapGlobals_( AstPermMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(PermMap) /* Check class membership */ astPROTO_ISA(PermMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPermMap *astPermMap_( int, const int [], int, const int [], const double [], const char *, int *, ...); #else AstPermMap *astPermMapId_( int, const int [], int, const int [], const double [], const char *, ... )__attribute__((format(printf,6,7))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPermMap *astInitPermMap_( void *, size_t, int, AstPermMapVtab *, const char *, int, const int [], int, const int [], const double [], int * ); /* Vtab initialiser. */ void astInitPermMapVtab_( AstPermMapVtab *, const char *, int * ); /* Loader. */ AstPermMap *astLoadPermMap_( void *, size_t, AstPermMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ double *astGetConstants_( AstPermMap *, int * ); int *astGetInPerm_( AstPermMap *, int * ); int *astGetOutPerm_( AstPermMap *, int * ); void astSetPermSplit_( AstPermMap *, int, int * ); void astClearPermSplit_( AstPermMap *, int * ); int astTestPermSplit_( AstPermMap *, int * ); int astGetPermSplit_( AstPermMap *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPermMap(this) astINVOKE_CHECK(PermMap,this,0) #define astVerifyPermMap(this) astINVOKE_CHECK(PermMap,this,1) /* Test class membership. */ #define astIsAPermMap(this) astINVOKE_ISA(PermMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astPermMap astINVOKE(F,astPermMap_) #else #define astPermMap astINVOKE(F,astPermMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPermMap(mem,size,init,vtab,name,nin,inperm,nout,outperm,constant) \ astINVOKE(O,astInitPermMap_(mem,size,init,vtab,name,nin,inperm,nout,outperm,constant,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPermMapVtab(vtab,name) astINVOKE(V,astInitPermMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPermMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPermMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckPermMap to validate PermMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetConstants(this) astINVOKE(V,astGetConstants_(astCheckPermMap(this),STATUS_PTR)) #define astGetInPerm(this) astINVOKE(V,astGetInPerm_(astCheckPermMap(this),STATUS_PTR)) #define astGetOutPerm(this) astINVOKE(V,astGetOutPerm_(astCheckPermMap(this),STATUS_PTR)) #define astSetPermSplit(this,permsplit) astINVOKE(V,astSetPermSplit_(astCheckPermMap(this),permsplit,STATUS_PTR)) #define astClearPermSplit(this) astINVOKE(V,astClearPermSplit_(astCheckPermMap(this),STATUS_PTR)) #define astTestPermSplit(this) astINVOKE(V,astTestPermSplit_(astCheckPermMap(this),STATUS_PTR)) #define astGetPermSplit(this) astINVOKE(V,astGetPermSplit_(astCheckPermMap(this),STATUS_PTR)) #endif #endif ast-8.3.0/fkeymap.c0000664000175000017500000012276013004147321011037 00000000000000/* *+ * Name: * fkeymap.c * Purpose: * Define a FORTRAN 77 interface to the AST KeyMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the KeyMap class. * Routines Defined: * AST_ISAKEYMAP * AST_KEYMAP * AST_MAPCOPY * AST_MAPPUT0 * AST_MAPPUT1 * AST_MAPPUTU * AST_MAPGET0 * AST_MAPGET1 * AST_MAPGETELEM * AST_MAPPUTELEM * AST_MAPREMOVE * AST_MAPRENAME * AST_MAPSIZE * AST_MAPLENGTH * AST_MAPLENC * AST_MAPTYPE * AST_MAPKEY * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 13-NOV-2004 (DSB): * Original version. * 5-JUN-2006 (DSB): * Added support for single precision entries. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "keymap.h" /* C interface to the KeyMap class */ F77_LOGICAL_FUNCTION(ast_isakeymap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAKEYMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAKeyMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_keymap)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_KEYMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astKeyMap( "%s", options ) ); astFree( options ); ) return RESULT; } F77_SUBROUTINE(ast_mapput0a)( INTEGER(THIS), CHARACTER(KEY), INTEGER(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0A", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0A( astI2P( *THIS ), key, astI2P( *VALUE ), comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0c)( INTEGER(THIS), CHARACTER(KEY), CHARACTER(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_CHARACTER(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *value, *key; astAt( "AST_MAPPUT0C", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); value = astString( VALUE, VALUE_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0C( astI2P( *THIS ), key, value, comment ); astFree( key ); astFree( value ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0i)( INTEGER(THIS), CHARACTER(KEY), INTEGER(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0I", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0I( astI2P( *THIS ), key, *VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0s)( INTEGER(THIS), CHARACTER(KEY), WORD(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_WORD(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0W", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0S( astI2P( *THIS ), key, *VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0b)( INTEGER(THIS), CHARACTER(KEY), UBYTE(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_UBYTE(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0B", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0B( astI2P( *THIS ), key, *VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0d)( INTEGER(THIS), CHARACTER(KEY), DOUBLE(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_DOUBLE(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0D", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0D( astI2P( *THIS ), key, *VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput0r)( INTEGER(THIS), CHARACTER(KEY), REAL(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_REAL(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT0R", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut0F( astI2P( *THIS ), key, *VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1a)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), INTEGER_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_INTEGER_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; AstObject **values; int i; astAt( "AST_MAPPUT1A", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); values = astMalloc( sizeof( AstObject * )*(size_t)( *SIZE )); if( astOK ) { for( i = 0; i < *SIZE; i++ ) { values[ i ] = astI2P( VALUE[ i ] ); } } astMapPut1A( astI2P( *THIS ), key, *SIZE, values, comment ); astFree( values ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1c)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), CHARACTER_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_CHARACTER_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; const char **values; int i; astAt( "AST_MAPPUT1C", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); values = astMalloc( sizeof( const char * )*(size_t)( *SIZE )); if( astOK ) { for( i = 0; i < *SIZE; i++ ) { values[ i ] = astString( VALUE + i*VALUE_length, VALUE_length ); } } astMapPut1C( astI2P( *THIS ), key, *SIZE, values, comment ); if( astOK ) { for( i = 0; i < *SIZE; i++ ) astFree( (void *) values[ i ] ); } astFree( (void *) values ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1i)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), INTEGER_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_INTEGER_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT1I", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut1I( astI2P( *THIS ), key, *SIZE, VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1s)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), WORD_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_WORD_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT1W", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut1S( astI2P( *THIS ), key, *SIZE, VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1b)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), UBYTE_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_UBYTE_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT1B", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut1B( astI2P( *THIS ), key, *SIZE, VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1d)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), DOUBLE_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_DOUBLE_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT1D", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut1D( astI2P( *THIS ), key, *SIZE, VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapput1r)( INTEGER(THIS), CHARACTER(KEY), INTEGER(SIZE), REAL_ARRAY(VALUE), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(SIZE) GENPTR_REAL_ARRAY(VALUE) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUT1R", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPut1F( astI2P( *THIS ), key, *SIZE, VALUE, comment ); astFree( key ); astFree( comment ); ) } F77_SUBROUTINE(ast_mapputu)( INTEGER(THIS), CHARACTER(KEY), CHARACTER(COMMENT), INTEGER(STATUS) TRAIL(KEY) TRAIL(COMMENT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_CHARACTER(COMMENT) char *comment, *key; astAt( "AST_MAPPUTU", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); comment = astString( COMMENT, COMMENT_length ); astMapPutU( astI2P( *THIS ), key, comment ); astFree( key ); astFree( comment ); ) } F77_LOGICAL_FUNCTION(ast_mapget0i)( INTEGER(THIS), CHARACTER(KEY), INTEGER(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET0I", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0I( astI2P( *THIS ), key, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0s)( INTEGER(THIS), CHARACTER(KEY), WORD(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_WORD(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET0W", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0S( astI2P( *THIS ), key, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0b)( INTEGER(THIS), CHARACTER(KEY), UBYTE(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_UBYTE(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET0W", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0B( astI2P( *THIS ), key, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0d)( INTEGER(THIS), CHARACTER(KEY), DOUBLE(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_DOUBLE(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET0D", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0D( astI2P( *THIS ), key, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0r)( INTEGER(THIS), CHARACTER(KEY), REAL(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_REAL(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET0R", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0F( astI2P( *THIS ), key, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0c)( INTEGER(THIS), CHARACTER(KEY), CHARACTER(VALUE), INTEGER(L), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_CHARACTER(VALUE) GENPTR_INTEGER(L) F77_LOGICAL_TYPE(RESULT); char *key; const char *value; int i; astAt( "AST_MAPGET0C", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); value = NULL; RESULT = astMapGet0C( astI2P( *THIS ), key, &value ) ? F77_TRUE : F77_FALSE; astFree( key ); i = 0; if( value ) { for( ; value[ i ] && ( i < VALUE_length ); i++ ) { VALUE[ i ] = value[ i ]; } *L = i; } else { *L = 0; } if( VALUE ) { for( ; i < VALUE_length; i++ ) { VALUE[ i ] = ' '; } } ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget0a)( INTEGER(THIS), CHARACTER(KEY), INTEGER(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; AstObject *value; astAt( "AST_MAPGET0A", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet0A( astI2P( *THIS ), key, &value ) ? F77_TRUE : F77_FALSE; astFree( key ); *VALUE = astP2I( value ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1i)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), INTEGER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_INTEGER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET1I", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet1I( astI2P( *THIS ), key, *MXVAL, NVAL, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1d)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), DOUBLE_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_DOUBLE_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET1D", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet1D( astI2P( *THIS ), key, *MXVAL, NVAL, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1s)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), WORD_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_WORD_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET1W", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet1S( astI2P( *THIS ), key, *MXVAL, NVAL, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1b)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), UBYTE_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_UBYTE_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET1B", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet1B( astI2P( *THIS ), key, *MXVAL, NVAL, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1r)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), REAL_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_REAL_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGET1R", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGet1F( astI2P( *THIS ), key, *MXVAL, NVAL, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1a)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), INTEGER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_INTEGER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; AstObject **values; int i; astAt( "AST_MAPGET1A", NULL, 0 ); astWatchSTATUS( values = astMalloc( sizeof( AstObject *)*(size_t) *MXVAL ); key = astString( KEY, KEY_length ); RESULT = astMapGet1A( astI2P( *THIS ), key, *MXVAL, NVAL, values ) ? F77_TRUE : F77_FALSE; astFree( key ); if( astOK ) { for( i = 0; i < *NVAL; i++ ) VALUE[ i ] = astP2I( values[ i ] ); } astFree( values ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapget1c)( INTEGER(THIS), CHARACTER(KEY), INTEGER(MXVAL), INTEGER(NVAL), CHARACTER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(MXVAL) GENPTR_INTEGER(NVAL) GENPTR_CHARACTER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; char *values, *c, *d; int i, j, term; astAt( "AST_MAPGET1C", NULL, 0 ); astWatchSTATUS( values = astMalloc( sizeof( char )*(size_t) (*MXVAL)*( VALUE_length + 1 ) ); key = astString( KEY, KEY_length ); RESULT = astMapGet1C( astI2P( *THIS ), key, VALUE_length + 1, *MXVAL, NVAL, values ) ? F77_TRUE : F77_FALSE; astFree( key ); /* Loop round each string value returned in the array */ if( astOK ) { c = values; d = VALUE; for( i = 0; i < *NVAL; i++ ) { /* Loop round each of character in the "i"th element of the returned array. Copy characters from the work array until a terminating null is found. Replace this null by a space and replace all subsequent characters by spaces up to the end of the returned array element. */ term = 0; for( j = 0; j < VALUE_length; j++, d++, c++ ) { if( term ) { *d = ' '; } else if( (*d = *c) == 0 ) { *d = ' '; term = 1; } } /* Skip over the extra character at the end of each element in the work array. */ c++; } } astFree( values ); ) return RESULT; } F77_SUBROUTINE(ast_mapremove)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) char *key; astAt( "AST_MAPREMOVE", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapRemove( astI2P( *THIS ), key ); astFree( key ); ) } F77_SUBROUTINE(ast_maprename)( INTEGER(THIS), CHARACTER(OLDKEY), CHARACTER(NEWKEY), INTEGER(STATUS) TRAIL(OLDKEY) TRAIL(NEWKEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(OLDKEY) GENPTR_CHARACTER(NEWKEY) char *oldkey, *newkey; astAt( "AST_MAPRENAME", NULL, 0 ); astWatchSTATUS( oldkey = astString( OLDKEY, OLDKEY_length ); newkey = astString( NEWKEY, NEWKEY_length ); astMapRename( astI2P( *THIS ), oldkey, newkey ); astFree( oldkey ); astFree( newkey ); ) } F77_SUBROUTINE(ast_mapcopy)( INTEGER(THIS), INTEGER(THAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(THAT) astAt( "AST_MAPCOPY", NULL, 0 ); astWatchSTATUS( astMapCopy( astI2P( *THIS ), astI2P( *THAT ) ); ) } F77_INTEGER_FUNCTION(ast_mapsize)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_MAPSIZE", NULL, 0 ); astWatchSTATUS( RESULT = astMapSize( astI2P( *THIS ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_maplength)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) F77_INTEGER_TYPE(RESULT); char *key; astAt( "AST_MAPLENGTH", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapLength( astI2P( *THIS ), key ); astFree( key ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_maplenc)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) F77_INTEGER_TYPE(RESULT); char *key; astAt( "AST_MAPLENGTH", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapLenC( astI2P( *THIS ), key ); astFree( key ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_maptype)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) F77_INTEGER_TYPE(RESULT); char *key; astAt( "AST_MAPTYPE", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapType( astI2P( *THIS ), key ); astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_maphaskey)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPHASKEY", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapHasKey( astI2P( *THIS ), key ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapdefined)( INTEGER(THIS), CHARACTER(KEY), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPDEFINED", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapDefined( astI2P( *THIS ), key ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file keymap.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_mapkey_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_mapkey)( CHARACTER_RETURN_VALUE(RESULT), #endif INTEGER(THIS), INTEGER(INDEX), #if NO_CHAR_FUNCTION INTEGER(STATUS) TRAIL(RESULT) ) { #else INTEGER(STATUS) ) { #endif GENPTR_CHARACTER(RESULT) GENPTR_INTEGER(THIS) GENPTR_INTEGER(INDEX) const char *result; int i; astAt( "AST_MAPKEY", NULL, 0 ); astWatchSTATUS( result = astMapKey( astI2P( *THIS ), *INDEX - 1 ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ ) } F77_LOGICAL_FUNCTION(ast_mapgetelemi)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), INTEGER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_INTEGER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGETELEMI", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemI( astI2P( *THIS ), key, *ELEM - 1, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelemd)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), DOUBLE_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_DOUBLE_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGETELEMD", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemD( astI2P( *THIS ), key, *ELEM - 1, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelems)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), WORD_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_WORD_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGETELEMW", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemS( astI2P( *THIS ), key, *ELEM - 1, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelemb)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), UBYTE_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_UBYTE_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGETELEMB", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemB( astI2P( *THIS ), key, *ELEM - 1, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelemr)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), REAL_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_REAL_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; astAt( "AST_MAPGETELEMR", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemF( astI2P( *THIS ), key, *ELEM - 1, VALUE ) ? F77_TRUE : F77_FALSE; astFree( key ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelema)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), INTEGER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_INTEGER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; AstObject *ptr; astAt( "AST_MAPGETELEMA", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); RESULT = astMapGetElemA( astI2P( *THIS ), key, *ELEM - 1, &ptr ) ? F77_TRUE : F77_FALSE; astFree( key ); if( astOK ) *VALUE = astP2I( ptr ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_mapgetelemc)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), CHARACTER_ARRAY(VALUE), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_CHARACTER_ARRAY(VALUE) F77_LOGICAL_TYPE(RESULT); char *key; char *values, *c, *d; int j; astAt( "AST_MAPGETELEMC", NULL, 0 ); astWatchSTATUS( values = astMalloc( sizeof( char )*(size_t) ( VALUE_length + 1 ) ); key = astString( KEY, KEY_length ); RESULT = astMapGetElemC( astI2P( *THIS ), key, VALUE_length + 1, *ELEM - 1, values ) ? F77_TRUE : F77_FALSE; astFree( key ); /* Copy characters from the work array until a terminating null is found. Replace this null by a space and replace all subsequent characters by spaces up to the end of the returned array element. */ if( astOK ) { c = values; d = VALUE; for( j = 0; j < VALUE_length; j++, d++, c++ ) { if( (*d = *c) == 0 ) { *d = ' '; break; } } for( ; j < VALUE_length; j++, d++ ) *d = ' '; } astFree( values ); ) return RESULT; } F77_SUBROUTINE(ast_mapputelemi)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), INTEGER(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_INTEGER(VALUE) char *key; astAt( "AST_MAPPUTELEMI", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemI( astI2P( *THIS ), key, *ELEM - 1, *VALUE ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelems)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), WORD(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_WORD(VALUE) char *key; astAt( "AST_MAPPUTELEMW", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemS( astI2P( *THIS ), key, *ELEM - 1, *VALUE ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelemb)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), UBYTE(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_UBYTE(VALUE) char *key; astAt( "AST_MAPPUTELEMB", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemB( astI2P( *THIS ), key, *ELEM - 1, *VALUE ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelemd)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), DOUBLE(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_DOUBLE(VALUE) char *key; astAt( "AST_MAPPUTELEMD", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemD( astI2P( *THIS ), key, *ELEM - 1, *VALUE ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelemr)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), REAL(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_REAL(VALUE) char *key; astAt( "AST_MAPPUTELEMR", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemF( astI2P( *THIS ), key, *ELEM - 1, *VALUE ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelema)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), INTEGER(VALUE), INTEGER(STATUS) TRAIL(KEY) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_INTEGER(VALUE) char *key; astAt( "AST_MAPPUTELEMA", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); astMapPutElemA( astI2P( *THIS ), key, *ELEM - 1, astI2P( *VALUE ) ); astFree( key ); ) } F77_SUBROUTINE(ast_mapputelemc)( INTEGER(THIS), CHARACTER(KEY), INTEGER(ELEM), CHARACTER(VALUE), INTEGER(STATUS) TRAIL(KEY) TRAIL(VALUE) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(KEY) GENPTR_INTEGER(ELEM) GENPTR_CHARACTER(VALUE) char *key; char *value; astAt( "AST_MAPPUTELEMC", NULL, 0 ); astWatchSTATUS( key = astString( KEY, KEY_length ); value = astString( VALUE, VALUE_length ); astMapPutElemC( astI2P( *THIS ), key, *ELEM - 1, value ); astFree( key ); astFree( value ); ) } ast-8.3.0/switchmap.c0000664000175000017500000031113313004147321011374 00000000000000/* *class++ * Name: * SwitchMap * Purpose: * A Mapping that encapsulates a set of alternate Mappings. * Constructor Function: c astSwitchMap f AST_SWITCHMAP * Description: * A SwitchMap is a Mapping which represents a set of alternate * Mappings, each of which is used to transform positions within a * particular region of the input or output coordinate system of the * SwitchMap. * * A SwitchMap can encapsulate any number of Mappings, but they must * all have the same number of inputs (Nin attribute value) and the * same number of outputs (Nout attribute value). The SwitchMap itself * inherits these same values for its Nin and Nout attributes. Each of * these Mappings represents a "route" through the switch, and are * referred to as "route" Mappings below. Each route Mapping transforms * positions between the input and output coordinate space of the entire * SwitchMap, but only one Mapping will be used to transform any given * position. The selection of the appropriate route Mapping to use with * any given input position is made by another Mapping, called the * "selector" Mapping. Each SwitchMap encapsulates two selector * Mappings in addition to its route Mappings; one for use with the * SwitchMap's forward transformation (called the "forward selector * Mapping"), and one for use with the SwitchMap's inverse transformation * (called the "inverse selector Mapping"). The forward selector Mapping * must have the same number of inputs as the route Mappings, but * should have only one output. Likewise, the inverse selector Mapping * must have the same number of outputs as the route Mappings, but * should have only one input. * * When the SwitchMap is used to transform a position in the forward * direction (from input to output), each supplied input position is * first transformed by the forward transformation of the forward selector * Mapping. This produces a single output value for each input position * referred to as the selector value. The nearest integer to the selector * value is found, and is used to index the array of route Mappings (the * first supplied route Mapping has index 1, the second route Mapping has * index 2, etc). If the nearest integer to the selector value is less * than 1 or greater than the number of route Mappings, then the SwitchMap * output position is set to a value of AST__BAD on every axis. Otherwise, * the forward transformation of the selected route Mapping is used to * transform the supplied input position to produce the SwitchMap output * position. * * When the SwitchMap is used to transform a position in the inverse * direction (from "output" to "input"), each supplied "output" position * is first transformed by the inverse transformation of the inverse * selector Mapping. This produces a selector value for each "output" * position. Again, the nearest integer to the selector value is found, * and is used to index the array of route Mappings. If this selector * index value is within the bounds of the array of route Mappings, then * the inverse transformation of the selected route Mapping is used to * transform the supplied "output" position to produce the SwitchMap * "input" position. If the selector index value is outside the bounds * of the array of route Mappings, then the SwitchMap "input" position is * set to a value of AST__BAD on every axis. * * In practice, appropriate selector Mappings should be chosen to * associate a different route Mapping with each region of coordinate * space. Note that the SelectorMap class of Mapping is particularly * appropriate for this purpose. * * If a compound Mapping contains a SwitchMap in series with its own * inverse, the combination of the two adjacent SwitchMaps will be * replaced by a UnitMap when the compound Mapping is simplified using c astSimplify. f AST_SIMPLIFY. * Inheritance: * The SwitchMap class inherits from the Mapping class. * Attributes: * The SwitchMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The SwitchMap class does not define any new functions beyond those f The SwitchMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 13-MAR-2006 (DSB): * Original version. * 17-MAR-2006 (DSB): * Guard against AST__BAD selector values. * 9-MAY-2006 (DSB): * Check selector Mapping pointers are not NULL before calling * astEqual in Equal. *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 SwitchMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "unitmap.h" /* Unit Mappings */ #include "channel.h" /* I/O channels */ #include "switchmap.h" /* Interface definition for this class */ #include "frame.h" /* Frames */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SwitchMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SwitchMap,Class_Init) #define class_vtab astGLOBAL(SwitchMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSwitchMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstSwitchMap *astSwitchMapId_( void *, void *, int, void **, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *RemoveRegions( AstMapping *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetObjSize( AstObject *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static AstMapping *GetSelector( AstSwitchMap *, int, int *, int * ); static AstMapping *GetRoute( AstSwitchMap *, double, int *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two SwitchMaps are equivalent. * Type: * Private function. * Synopsis: * #include "switchmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * SwitchMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two SwitchMaps are equivalent. * Parameters: * this * Pointer to the first Object (a SwitchMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the SwitchMaps are equivalent, zero otherwise. * 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: */ AstMapping *fsmap1; AstMapping *fsmap2; AstMapping *ismap1; AstMapping *ismap2; AstMapping *rmap1; AstMapping *rmap2; AstSwitchMap *that; AstSwitchMap *this; int fsinv1; int fsinv2; int isinv1; int i; int isinv2; int nroute; int result; int rinv1; int rinv2; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two SwitchMap structures. */ this = (AstSwitchMap *) this_object; that = (AstSwitchMap *) that_object; /* Check the second object is a SwitchMap. We know the first is a SwitchMap since we have arrived at this implementation of the virtual function. */ if( astIsASwitchMap( that ) ) { /* Check they have the same number of route mappings. */ nroute = this->nroute; if( that->nroute == nroute ) { /* Get the forward selector Mappings from the two SwitchMaps. */ fsmap1 = GetSelector( this, 1, &fsinv1, status ); fsmap2 = GetSelector( that, 1, &fsinv2, status ); /* Are they equal? */ if( ( !fsmap1 && !fsmap2 ) || ( fsmap1 && fsmap2 && astEqual( fsmap1, fsmap2 ) ) ) { /* Get the inverse selector Mappings from the two SwitchMaps. */ ismap1 = GetSelector( this, 0, &isinv1, status ); ismap2 = GetSelector( that, 0, &isinv2, status ); /* Are they equal? */ if( ( !ismap1 && !ismap2 ) || ( ismap1 && ismap2 && astEqual( ismap1, ismap2 ) ) ) { /* Loop over the route mappings, breaking as soon as two unequal route Mappings are found. Re-instate the original values for the route Mapping Invert flag after testing the route Mappings for equality. */ result = 1; for( i = 0; result && i < nroute; i++ ) { rmap1 = GetRoute( this, (double) ( i + 1 ), &rinv1, status ); rmap2 = GetRoute( that, (double) ( i + 1 ), &rinv2, status ); if( !astEqual( rmap1, rmap2 ) ) result = 0; astSetInvert( rmap2, rinv2 ); astSetInvert( rmap1, rinv1 ); } } /* Reinstate the invert flags for the inverse selector Mappings. Ensure this is done in the opposite order to which the selector Mappings were obtained (in case they are in fact the same Mapping). */ if( ismap2 ) astSetInvert( ismap2, isinv2 ); if( ismap1 ) astSetInvert( ismap1, isinv1 ); } /* Reinstate the invert flags for the forward selector Mappings. Ensure this is done in the oppsote order to which the selector Mappings were obtained (in case they are in fact the same Mapping). */ if( fsmap2 ) astSetInvert( fsmap2, fsinv2 ); if( fsmap1 ) astSetInvert( fsmap1, fsinv1 ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "switchmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SwitchMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SwitchMap, * in bytes. * Parameters: * this * Pointer to the SwitchMap. * 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: */ AstSwitchMap *this; int i; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SwitchMap structure. */ this = (AstSwitchMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->fsmap ); result += astGetObjSize( this->ismap ); for( i = 0; i < this->nroute; i++ ) { result += astGetObjSize( this->routemap[ i ] ); } result += astGetObjSize( this->routeinv ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static AstMapping *GetRoute( AstSwitchMap *this, double sel, int *inv, int *status ){ /* * Name: * GetRoute * Purpose: * Return a pointer to a route Mapping, handling all Invert flags. * Type: * Private function. * Synopsis: * #include "switchmap.h" * AstMapping *GetRoute( AstSwitchMap *this, double sel, int *inv, int *status ) * Class Membership: * SwitchMap method. * Description: * This function returns a pointer to a route Mapping (specified by a * floating point selector value) for the given SwitchMap, taking account * of the state of the Invert flag of both the route Mapping and the * SwitchMap. * Parameters: * this * Pointer to the SwitchMap. * sel * The selector value. The nearest integer value (minus 1) is used * to index the array of route Mappings stored in the SwitchMap. A * NULL pointer is returned if the selector value is out of range. * inv * Pointer to an int in which to return the original value of the * Invert flag of the returned Mapping. The astSetInvert method * should be used to re-instate this value once all use of the Mapping * has been completed. * status * Pointer to the inherited status variable. * Returns: * A pointer to the route Mapping to use. Note, the returned pointer * should NOT be annulled when no longer needed. NULL is returned * (without error) if the SwitchMap does not have a route Mapping for the * requested selector value. The forward transformation of the * returned Mapping will implenment the forward transformation of the * required route Mapping (and vice-versa). */ /* Local Variables: */ AstMapping *ret; int rindex; /* Initialise */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* Check selector value is good. */ if( sel != AST__BAD ) { /* Convert the supplied floating point selector value into an integer index into the array of route Mappings held in the supplied SwitchMap. */ rindex = (int)( sel + 0.5 ) - 1; /* Return the null pointer if the index is out of range. */ if( rindex >= 0 && rindex < this->nroute ) { /* Get the required route Mapping. */ ret = ( this->routemap )[ rindex ]; /* Return its original invert flag. */ *inv = astGetInvert( ret ); /* Set the Invert flag back to the value it had when the SwitchMap was created. */ astSetInvert( ret, this->routeinv[ rindex ] ); /* If the SwitchMap has since been inverted, also invert the returned route Mapping, so that the forward transformation of the returned Mapping implements the forward transformation of the supplied SwitchMap (and vice-versa). */ if( astGetInvert( this ) ) astInvert( ret ); } } /* Return the pointer. */ return ret; } static AstMapping *GetSelector( AstSwitchMap *this, int fwd, int *inv, int *status ){ /* * Name: * GetSelector * Purpose: * Return a pointer to a selector Mapping, handling all Invert flags. * Type: * Private function. * Synopsis: * #include "switchmap.h" * AstMapping *GetSelector( AstSwitchMap *this, int fwd, int *inv, int *status ) * Class Membership: * SwitchMap method. * Description: * This function returns a pointer to either the forward or inverse * selector Mapping for the given SwitchMap, taking account of the * state of the Invert flag of bothe the selector Mapping and the * SwitchMap. * Parameters: * this * Pointer to the SwitchMap. * fwd * If non-zero, return the forward selector Mapping. Otherwise, * return the inverse selector Mapping. * inv * Pointer to an int in which to return the original value of the * Invert flag of the returned Mapping. The astSetInvert method * should be used to re-instate this value once all use of the Mapping * has been completed. * status * Pointer to the inherited status variable. * Returns: * A pointer to the selector Mapping to use. Note, the returned pointer * should NOT be annulled when no longer needed. NULL is returned * (without error) if the SwitchMap does not have a Mapping for the * requested selector. */ /* Local Variables: */ AstMapping *ret; int swinv; /* Initialise */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* See if the SwitchMap has been inverted. */ swinv = astGetInvert( this ); /* If the SwitchMap has been inverted, the forward and inverse selector Mappings should be reversed. */ if( ( !swinv && !fwd ) || ( swinv && fwd ) ){ ret = this->ismap; if( ret ) { *inv = astGetInvert( ret ); astSetInvert( ret, this->isinv ); } } else { ret = this->fsmap; if( ret ) { *inv = astGetInvert( ret ); astSetInvert( ret, this->fsinv ); } } if( ret && swinv ) astInvert( ret ); /* Return the pointer. */ return ret; } void astInitSwitchMapVtab_( AstSwitchMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSwitchMapVtab * Purpose: * Initialise a virtual function table for a SwitchMap. * Type: * Protected function. * Synopsis: * #include "switchmap.h" * void astInitSwitchMapVtab( AstSwitchMapVtab *vtab, const char *name ) * Class Membership: * SwitchMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SwitchMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsASwitchMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->Rate = Rate; mapping->RemoveRegions = RemoveRegions; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "SwitchMap", "Alternate regionalised Mapping" ); /* 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) ); } } #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: * SwitchMap 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: */ AstSwitchMap *this; /* Pointer to SwitchMap 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 SwitchMap structure. */ this = (AstSwitchMap *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->fsmap, mode, extra, fail ); if( !result ) result = astManageLock( this->ismap, mode, extra, fail ); for( i = 0; i < this->nroute; i++ ) { if( !result ) result = astManageLock( this->routemap[ i ], mode, extra, fail ); } return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a SwitchMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * SwitchMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated SwitchMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated SwitchMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated SwitchMap which is to be merged with * its neighbours. This should be a cloned copy of the SwitchMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * SwitchMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated SwitchMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstSwitchMap *map; AstMapping *new; int i; int nroute; int result; int fsinv_old; int isinv_old; int *rinv_old; AstMapping *sfsmap; AstMapping *sismap; int simp; AstMapping **srmap; AstSwitchMap *swneb; int ilo; int equal; /* Initialise.*/ result = -1; /* Check the inherited status. */ if ( !astOK ) return result; /* Get a pointer to this SwitchMap, and note the number of route Mappings. */ map = (AstSwitchMap *) this; nroute = map->nroute; /* Temporarily put the Invert flag of all encapsulated Mappings (both route and selector) back to the values they had when the SwitchMap was created, noting their current values so that they can be re-instated later. If the SwitchMap itself has been inverted, swap all the original invert flags. */ if( map->fsmap ) { fsinv_old = astGetInvert( map->fsmap ); astSetInvert( map->fsmap, map->fsinv ); } else { fsinv_old = 0; } if( map->ismap ) { isinv_old = astGetInvert( map->ismap ); astSetInvert( map->ismap, map->isinv ); } else { isinv_old = 0; } rinv_old = astMalloc( sizeof( int )*nroute ); if( astOK ) { for( i = 0; i < nroute; i++ ) { rinv_old[ i ] = astGetInvert( map->routemap[ i ] ); astSetInvert( map->routemap[ i ], map->routeinv[ i ] ); } } /* If possible, merge the SwitchMap with a neighbouring SwitchMap. */ /* =============================================================== */ /* Only do this if we are combining the Mappings in series. */ if( series ) { /* Is the higher neighbour a SwitchMap? If so get a pointer to it, and note the index of the lower of the two adjacent SwitchMaps. */ if( where < ( *nmap - 1 ) && astIsASwitchMap( ( *map_list )[ where + 1 ] ) ){ swneb = (AstSwitchMap *) ( *map_list )[ where + 1 ]; ilo = where; /* If not, is the lower neighbour a SwitchMap? If so get a pointer to it, and note the index of the lower of the two adjacent SwitchMaps. */ } else if( where > 0 && astIsASwitchMap( ( *map_list )[ where - 1 ] ) ){ swneb = (AstSwitchMap *) ( *map_list )[ where - 1 ]; ilo = where - 1; } else { swneb = NULL; } /* If a neighbouring SwitchMap was found, we can replace the pair by a UnitMap if the two SwitchMaps are equal but have opposite values for their Invert flags. Temporarily invert the neighbour, then compare the two SwitchMaps for equality, then re-invert the neighbour. */ if( swneb ) { astInvert( swneb ); equal = astEqual( map, swneb ); astInvert( swneb ); /* If the two SwitchMaps are equal but opposite, annul the first of the two Mappings, and replace it with a UnitMap. Also set the invert flag. */ if( equal ) { new = (AstMapping *) astUnitMap( astGetNin( ( *map_list )[ ilo ] ), "", status ); (void) astAnnul( ( *map_list )[ ilo ] ); ( *map_list )[ ilo ] = new; ( *invert_list )[ ilo ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ ilo + 1 ] ); for ( i = ilo + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = where; } } } /* Attempt to simplify the SwitchMap on its own. */ /* ============================================= */ /* Only do this if no change was made above. */ if( result == -1 ) { /* If the SwitchMap is inverted, create an equal SwitchMap which is not inverted. To do this, invert and swap the selector Mappings, and invert all the route Mappings. We use astSetInvert rather than astInvert because two or more more stored pointers may point to the same Mapping in which case that Mapping would be inverted more than once with unpredictable results. */ if( ( *invert_list )[ where ] ) { if( map->fsmap ) astSetInvert( map->fsmap, !(map->fsinv) ); if( map->ismap ) astSetInvert( map->ismap, !(map->isinv) ); for( i = 0; i < nroute; i++ ) { astSetInvert( map->routemap[ i ], !(map->routeinv[ i ]) ); } new = (AstMapping *) astSwitchMap( map->ismap, map->fsmap, nroute, (void **) map->routemap, "", status ); (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) new; ( *invert_list )[ where ] = 0; result = where; /* Otherwise, try to simplify each of the encapsulated Mappings, noting if any simplification takes place. */ } else { sfsmap = ( map->fsmap ) ? astSimplify( map->fsmap ) : NULL; sismap = ( map->ismap ) ? astSimplify( map->ismap ) : NULL; simp = ( sfsmap != map->fsmap ) || ( sismap != map->ismap ); srmap = astMalloc( sizeof( AstMapping * )*nroute ); if( astOK ) { for( i = 0; i < nroute; i++ ) { srmap[ i ] = astSimplify( map->routemap[ i ] ); simp = simp || ( srmap[ i ] != map->routemap[ i ] ); } } /* If any simplification took place, construct a new SwitchMap from these simplified Mappings. */ if( simp ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) astSwitchMap( sfsmap, sismap, nroute, (void **) srmap, "", status ); result = where; } /* Release resources. */ if( sfsmap ) sfsmap = astAnnul( sfsmap ); if( sismap ) sismap = astAnnul( sismap ); if( srmap ) { for( i = 0; i < nroute; i++ ) srmap[ i ] = astAnnul( srmap[ i ] ); srmap = astFree( srmap ); } } } /* Re-instate the original Invert values for the encapsulated Mappings. */ if( map->fsmap ) astSetInvert( map->fsmap, fsinv_old ); if( map->ismap ) astSetInvert( map->ismap, isinv_old ); if( rinv_old ) { for( i = 0; i < nroute; i++ ) { astSetInvert( map->routemap[ i ], rinv_old[ i ] ); } rinv_old = astFree( rinv_old ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static double Rate( AstMapping *this, 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 "switchmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * SwitchMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. Also evaluates the second derivative. * 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: * 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. */ /* Local Variables: */ AstSwitchMap *map; AstMapping *smap; AstMapping *rmap; double result; double sel; int fsinv; int rinv; int nin; /* Initialise. */ result = AST__BAD; /* Check inherited status */ if( !astOK ) return result; /* Get a pointer to the SwitchMap structure. */ map = (AstSwitchMap *) this; /* Get a pointer to the effective foward selector Mapping, and its current invert flag (this takes account of whether the SwtichMap has been inverted or not). This call resets the selector's invert flag temporarily back to the value it had when the SwitchMap was created. */ smap = GetSelector( map, 1, &fsinv, status ); /* If the SwitchMap has no forward selector Mapping, return AST__BAD. */ if( smap ) { /* Get the number of inputs */ nin = astGetNin( smap ); /* Transform the supplied position using the selector Mapping. The output value is the selector value that indicates which route Mapping to use. */ astTranN( smap, 1, nin, 1, at, 1, 1, 1, &sel ); /* Get the index of the route Mapping to use, and check it is valid (if not, return AST__BAD if not). This takes account of whether the SwitchMap has been inverted, and also temporarily re-instates the original value of the route Mapping's Invert flag . */ rmap = GetRoute( map, sel, &rinv, status ); if( rmap ) { /* Use the astRate method of the route Mapping. */ result = astRate( rmap, at, ax1, ax2 ); /* Reset the Invert flag for the route Mapping. */ astSetInvert( rmap, rinv ); } /* Reset the Invert flag for the selector Mapping. */ astSetInvert( smap, fsinv ); } /* Return the result. */ return result; } static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { /* * Name: * RemoveRegions * Purpose: * Remove any Regions from a Mapping. * Type: * Private function. * Synopsis: * #include "switchmap.h" * AstMapping *RemoveRegions( AstMapping *this, int *status ) * Class Membership: * SwitchMap 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 SwitchMap) 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 SwitchMap), then it is replaced with an equivalent UnitMap * in the returned Mapping. * * The implementation provided by the SwitchMap class invokes the * astRemoveRegions method on all the component Mappings, and joins * the results together into a new SwitchMap. * 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: */ AstMapping **temp; /* Array of new route Mappings */ AstMapping *newfsmap; /* New forward selector Mapping */ AstMapping *newismap; /* New inverse selector Mapping */ AstMapping *result; /* Result pointer to return */ AstSwitchMap *new; /* Pointer to new SwitchMap */ AstSwitchMap *this; /* Pointer to SwitchMap structure */ 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 SwitchMap. */ this = (AstSwitchMap *) this_mapping; /* Allocate an array to hold the modified Mapping pointers. */ temp = astMalloc( sizeof( AstMapping *)*( this->nroute ) ); if( astOK ) { /* Invoke the astRemoveRegions method on all the component Mappings. */ changed = 0; for( i = 0; i < this->nroute; i++ ) { temp[ i ] = astRemoveRegions( this->routemap[ i ] ); /* Note if any Mapping was changed. */ if( temp[ i ] != this->routemap[ 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( temp[ i ] ) ) { nax = astGetNin( temp[ i ] ); (void) astAnnul( temp[ i ] ); temp[ i ] = (AstMapping *) astUnitMap( nax, " ", status ); } } } /* And on the other ancillary Mappings */ if( this->fsmap ) { newfsmap = astRemoveRegions( this->fsmap ); if( newfsmap != this->fsmap ) { changed = 1; if( astIsAFrame( newfsmap ) ) { nax = astGetNin( newfsmap ); (void) astAnnul( newfsmap ); newfsmap = (AstMapping *) astUnitMap( nax, " ", status ); } } } else { newfsmap = NULL; } if( this->ismap ) { newismap = astRemoveRegions( this->ismap ); if( newismap != this->ismap ) { changed = 1; if( astIsAFrame( newismap ) ) { nax = astGetNin( newismap ); (void) astAnnul( newismap ); newismap = (AstMapping *) astUnitMap( nax, " ", status ); } } } else { newismap = NULL; } /* 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 Mapping to return. We take a deep copy of the supplied SwitchMap and then modify the Mappings so that we retain any extra information in the supplied SwitchMap. */ } else { new = astCopy( this ); for( i = 0; i < this->nroute; i++ ) { (void) astAnnul( new->routemap[ i ] ); new->routemap[ i ] = astClone( temp[ i ] ); } if( newfsmap ) { (void) astAnnul( new->fsmap ); new->fsmap = astClone( newfsmap ); } if( newismap ) { (void) astAnnul( new->ismap ); new->ismap = astClone( newismap ); } result = (AstMapping *) new; } /* Free resources. */ for( i = 0; i < this->nroute; i++ ) { temp[ i ] = astAnnul( temp[ i ] ); } if( newfsmap ) newfsmap = astAnnul( newfsmap ); if( newismap ) newismap = astAnnul( newismap ); } temp = astFree( temp ); /* Annul the returned Mapping if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } int astSwitchList_( AstSwitchMap *this, int invert, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* *+ * Name: * astSwitchList * Purpose: * Extract the selector and route Mappings from a SwitchMap. * Type: * Protected function. * Synopsis: * #include "switchmap.h" * int astSwitchList( AstSwitchMap *this, int invert, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * SwitchMap member function. * Description: * This function extracts the route and selector Mappings form a * SwitchMap. * Parameters: * this * Pointer to the SwitchMap to be decomposed (it is not actually * modified by this function). * invert * The value to which the SwitchMap's Invert attribute is to be * (notionally) set before performing the decomposition. Normally, * the value supplied here will be the actual Invert value obtained * from the SwitchMap (e.g. using astGetInvert). Sometimes, however, * when a SwitchMap is encapsulated within another structure, that * structure may retain an Invert value (in order to prevent external * interference) which should be used instead. * * Note that the actual Invert value of the SwitchMap supplied is * not used (or modified) by this function. * nmap * The address of an int in which to return a count of the number of * individual Mappings in the decomposition. The supplied value is * ignored. * map_list * Address of a pointer to an array of Mapping pointers. The value * supplied on entry is ignored. On exit, it points at a dynamically * allocated array containing Mapping pointers ("*nmap" in number) that * result from the decomposition requested. * * The returned Mapping pointers returned will identify the following * sequence of Mappings; forward selector mapping (or NULL if the * SwitchMap has no forward selector Mapping), inverse selector * mapping (or NULL if the SwitchMap has no inverse selector Mapping), * the route Mappings in the order they were supplied when the * SwitchMap was constructed. * * All the Mapping pointers returned by this function should be * annulled by the caller, using astAnnul, when no longer * required. The dynamic array holding these pointers should * also be freed, using astFree. * invert_list * Address of a pointer to an array of int. The value supplied on * entry is ignored. On exit, it points at a dynamically allocated * array containing Invert attribute values ("*nmap" in number) that * result from the decomposition requested. * * The returned Invert values returned identify the values which must * be assigned to the Invert attributes of the corresponding * Mappings (whose pointers are in the "*map_list" array) before * they are applied. Note that these values may differ from the * actual Invert attribute values of these Mappings, which are * not relevant. * * The dynamic array holding these values should be freed by the * caller, using astFree, when no longer required. * Returned Value: * The number of route Mappings stored in the SwitchMap. * Notes: * - It is unspecified to what extent the original SwitchMap and the * individual (decomposed) Mappings are inter-dependent. Consequently, * the individual Mappings cannot be modified without risking * modification of the original SwitchMap. * - If this function is invoked with the global error status set, * or if it should fail for any reason, then the *nmap value, the * list of Mapping pointers and the list of Invert values will all * be returned unchanged. *- */ /* Local Variables: */ AstMapping *map; /* Pointer to Mapping to return */ int inv; /* Original Invert flag for Mapping */ int i; /* Route Mapping index */ int oldinv; /* Original Invert flag for SwitchMap */ int result; /* Returned value */ /* Check the global error status. */ if ( !astOK ) return 0; /* Store the numbe of route Mappings */ result = this->nroute; *nmap = result + 2; /* Allocate the required arrays. */ *map_list = astMalloc( sizeof( AstMapping * )*(size_t) *nmap ); *invert_list = astMalloc( sizeof( int )*(size_t) *nmap ); /* Check the pointers can be used safely. */ if( astOK ) { /* Temporaily set the requested Invert flag for the SwitchMap. */ oldinv = astGetInvert( this ); astSetInvert( this, invert ); /* Get the forward selector Mapping. */ map = GetSelector( this, 1, &inv, status ); /* If the SwitchMap has a forward selector Mapping, return a clone of the Mapping pointer, and the invert flag to be used with it, then re-instate the original invert flag value (which was modified by GetSelector). */ if( map ) { ( *map_list )[ 0 ] = astClone( map ); ( *invert_list )[ 0 ] = astGetInvert( map ); astSetInvert( map, inv ); /* If the SwitchMap does not has a forward selector Mapping, return a NULL pointer. */ } else { ( *map_list )[ 0 ] = NULL; ( *invert_list )[ 0 ] = 0; } /* Likewise, get and return the inverse selector Mapping.*/ map = GetSelector( this, 0, &inv, status ); if( map ) { ( *map_list )[ 1 ] = astClone( map ); ( *invert_list )[ 1 ] = astGetInvert( map ); astSetInvert( map, inv ); } else { ( *map_list )[ 1 ] = NULL; ( *invert_list )[ 1 ] = 0; } /* Loop round all route Mappings. */ for( i = 0; i < result; i++ ){ /* Get the next route Mapping. */ map = GetRoute( this, (double) i + 1.0, &inv, status ); /* If the SwitchMap has a route Mapping for the current selector value, return a clone of the Mapping pointer, and the invert flag to be used with it, then re-instate the original invert flag value (which was modified by GetRoute). */ if( map ) { ( *map_list )[ i + 2 ] = astClone( map ); ( *invert_list )[ i + 2 ] = astGetInvert( map ); astSetInvert( map, inv ); /* If the SwitchMap does not has a route Mapping for the current selector value, return a NULL pointer. */ } else { ( *map_list )[ i + 2 ] = NULL; ( *invert_list )[ i + 2 ] = 0; } } /* Re-instate the original Ivert flag for the SwitchMap. */ astSetInvert( this, oldinv ); } /* If an error has occurred, free the returned arrays. */ if( !astOK ) { *map_list = astFree( *map_list ); *invert_list= astFree( *invert_list ); result= 0; *nmap = 0; } /* Return the result */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a SwitchMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "switchmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * SwitchMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a SwitchMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Mapping. * This implies applying each of the SwitchMap's component Mappings in turn, * either in series or in parallel. * Parameters: * this * Pointer to the SwitchMap. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the SwitchMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstMapping *rmap; AstMapping *selmap; AstPointSet *ps1; AstPointSet *ps1a; AstPointSet *ps2; AstPointSet *ps2a; AstPointSet *result; AstPointSet *selps; AstSwitchMap *map; double **in_ptr; double **out_ptr; double **ptr1; double **ptr2; double **sel_ptr; double *outv; double *sel; int *popmap; int iroute; int ipoint; int j; int k; int maxpop; int ncin; int ncout; int npoint; int nroute; int rindex; int rinv; int selinv; int totpop; /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SwitchMap. */ map = (AstSwitchMap *) this; /* Apply the parent Mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We now extend the parent astTransform method by applying the component Mappings of the SwitchMap to generate the output coordinate values. */ /* Get the number of input and output coords. */ if( forward ) { ncin = astGetNin( this ); ncout = astGetNout( this ); } else { ncin = astGetNout( this ); ncout = astGetNin( this ); } /* Get the appropriate selector Mapping. */ selmap = GetSelector( map, forward, &selinv, status ); /* Transform the supplied positions using the above selector Mapping. */ selps = astTransform( selmap, in, forward, NULL ); /* Get a pointer to the array holding the selector value. */ sel_ptr = astGetPoints( selps ); /* Get a pointer to the array holding the input values. */ in_ptr = astGetPoints( in ); /* Get a pointer to the array in which to store the results, and the total number of points being transformed. */ out_ptr = astGetPoints( result ); npoint = astGetNpoint( result ); /* We now count how many positions are to be tranformed by each of the route Mappings. */ nroute = map->nroute; popmap = astMalloc( sizeof( int )*nroute ); if( astOK ) { for( iroute = 0; iroute < nroute; iroute++ ) popmap[ iroute ] = 0; sel = sel_ptr[ 0 ]; for( ipoint = 0; ipoint < npoint; ipoint++,sel++ ) { if( *sel != AST__BAD ) { rindex = (int)( *sel + 0.5 ) - 1; if( rindex >= 0 && rindex < nroute ) ( popmap[ rindex ] )++; } } /* Find the number of points transformed by the most popular route Mapping. Also find the total number of points transformed by any route Mapping. */ totpop = 0; maxpop = 0; for( iroute = 0; iroute < nroute; iroute++ ) { if( popmap[ iroute ] > maxpop ) maxpop = popmap[ iroute ]; totpop += popmap[ iroute ]; } if( maxpop == 0 ) maxpop = 1; /* If some of the points are not transformed by any route Mapping. Initialise the whole output array to hold AST__BAD at every point. */ if( totpop < npoint ) { for( j = 0; j < ncout; j++ ) { outv = out_ptr[ j ]; for( ipoint = 0; ipoint < npoint; ipoint++ ) *(outv++) = AST__BAD; } } /* Create a PointSet large enough to hold all the supplied positions which are to be transformed by the most popular route Mapping. */ ps1 = astPointSet( maxpop, ncin, "", status ); ptr1 = astGetPoints( ps1 ); /* Create a PointSet large enough to hold all the output positions created by the most popular route Mapping. */ ps2 = astPointSet( maxpop, ncout, "", status ); ptr2 = astGetPoints( ps2 ); if( astOK ) { /* Loop round each route Mapping which is used by at least 1 point. */ for( iroute = 0; iroute < nroute; iroute++ ) { if( popmap[ iroute ] >0 ) { rmap = GetRoute( map, (double)( iroute + 1 ), &rinv, status ); /* Construct two PointSets of the correct size to hold the input and output points to be processed with the current route Mapping. We re-use the memory allocated for the largest route Mapping's PointSet. */ if( popmap[ iroute ] != maxpop ) { ps1a = astPointSet( popmap[ iroute ], ncin, "", status ); astSetPoints( ps1a, ptr1 ); ps2a = astPointSet( popmap[ iroute ], ncout, "", status ); astSetPoints( ps2a, ptr2 ); } else { ps1a = astClone( ps1 ); ps2a = astClone( ps2 ); } /* Fill the input PointSet with the input positions which are to be transformed using the current route Mapping. */ sel = sel_ptr[ 0 ]; k = 0; for( ipoint = 0; ipoint < npoint; ipoint++,sel++ ) { if( *sel != AST__BAD ) { rindex = (int)( *sel + 0.5 ) - 1; if( rindex == iroute ) { for( j = 0; j < ncin; j++ ) { ptr1[ j ][ k ] = in_ptr[ j ][ ipoint ]; } k++; } } } /* Use the route Mapping to transform this PointSet. */ (void) astTransform( rmap, ps1a, forward, ps2a ); /* Copy the axis values from the resulting PointSet back into the results array. */ sel = sel_ptr[ 0 ]; k = 0; for( ipoint = 0; ipoint < npoint; ipoint++,sel++ ) { if( *sel != AST__BAD ) { rindex = (int)( *sel + 0.5 ) - 1; if( rindex == iroute ) { for( j = 0; j < ncout; j++ ) { out_ptr[ j ][ ipoint ] = ptr2[ j ][ k ]; } k++; } } } /* Free resources. */ ps1a = astAnnul( ps1a ); ps2a = astAnnul( ps2a ); /* Re-instate the Invert flag for the route Mapping. */ astSetInvert( rmap, rinv ); } } } /* Free resources. */ ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } selps = astAnnul( selps ); popmap = astFree( popmap ); /* Re-instate the Invert flag of the selector Mapping. */ astSetInvert( selmap, selinv ); /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SwitchMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SwitchMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Mappings within the SwitchMap. */ /* Local Variables: */ AstSwitchMap *in; /* Pointer to input SwitchMap */ AstSwitchMap *out; /* Pointer to output SwitchMap */ int i; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SwitchMaps. */ in = (AstSwitchMap *) objin; out = (AstSwitchMap *) objout; /* For safety, start by clearing any references to the input component Mappings,etc, from the output SwitchMap. */ out->fsmap = NULL; out->ismap = NULL; out->routemap = NULL; out->routeinv = NULL; /* Make copies of these Mappings, etc, and store pointers to them in the output SwitchMap structure. */ if( in->fsmap ) out->fsmap = astCopy( in->fsmap ); if( in->ismap ) out->ismap = astCopy( in->ismap ); out->routemap = astMalloc( sizeof( AstMapping * )*( in->nroute ) ); out->routeinv = astMalloc( sizeof( int )*( in->nroute ) ); if( astOK ) { for( i = 0; i < in->nroute; i++ ) { out->routemap[ i ] = astCopy( in->routemap[ i ] ); out->routeinv[ i ] = in->routeinv[ i ]; } } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SwitchMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SwitchMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstSwitchMap *this; /* Pointer to SwitchMap */ int i; /* Obtain a pointer to the SwitchMap structure. */ this = (AstSwitchMap *) obj; /* Free dynamically allocated resources. */ if( this->fsmap ) this->fsmap = astAnnul( this->fsmap ); if( this->ismap ) this->ismap = astAnnul( this->ismap ); for( i = 0; i < this->nroute; i++ ) { this->routemap[ i ] = astAnnul( this->routemap[ i ] ); } this->routemap = astFree( this->routemap ); this->routeinv = astFree( this->routeinv ); /* Clear the remaining SwitchMap variables. */ this->nroute = 0; this->fsinv = 0; this->isinv = 0; } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SwitchMap 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 SwitchMap class to an output Channel. * Parameters: * this * Pointer to the SwitchMap 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 Variables: */ AstSwitchMap *this; int ival; int set; int i; char buf[ 20 ]; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SwitchMap structure. */ this = (AstSwitchMap *) this_object; /* Write out values representing the instance variables for the SwitchMap 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. */ /* Forward selector Mapping */ /* ------------------------ */ if( this->fsmap ) { astWriteObject( channel, "FSMap", 1, 1, this->fsmap, "Forward selector Mapping" ); /* Forward selector Invert flag. */ /* ----------------------------- */ ival = this->fsinv; set = ( ival != 0 ); astWriteInt( channel, "FSInv", set, 0, ival, ival ? "Fwd selector used in inverse direction" : "Fwd selector used in forward direction" ); } /* Inverse selector Mapping */ /* ------------------------ */ if( this->ismap ) { astWriteObject( channel, "ISMap", 1, 1, this->ismap, "Inverse selector Mapping" ); /* Forward selector Invert flag. */ /* ----------------------------- */ ival = this->isinv; set = ( ival != 0 ); astWriteInt( channel, "ISInv", set, 0, ival, ival ? "Inv selector used in inverse direction" : "Inv selector used in forward direction" ); } /* Loop to dump each route Mapping and its invert flag. */ /* ---------------------------------------------------- */ for( i = 0; i < this->nroute; i++ ) { sprintf( buf, "RMap%d", i + 1 ); astWriteObject( channel, buf, 1, 1, this->routemap[ i ], "Route Mapping" ); ival = this->routeinv[ i ]; set = ( ival != 0 ); sprintf( buf, "RInv%d", i + 1 ); astWriteInt( channel, buf, set, 0, ival, ival ? "Route Mapping used in inverse direction" : "Route Mapping used in forward direction" ); } } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASwitchMap and astCheckSwitchMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SwitchMap,Mapping) astMAKE_CHECK(SwitchMap) AstSwitchMap *astSwitchMap_( void *fsmap_void, void *ismap_void, int nroute, void **routemaps_void, const char *options, int *status, ...) { /* *+ * Name: * astSwitchMap * Purpose: * Create a SwitchMap. * Type: * Protected function. * Synopsis: * #include "switchmap.h" * AstSwitchMap *astSwitchMap( AstMapping *fsmap, AstMapping *ismap, * int nroute, AstMapping **routemaps, * const char *options, ... ) * Class Membership: * SwitchMap constructor. * Description: * This function creates a new SwitchMap and optionally initialises its * attributes. * Parameters: * fsmap * Pointer to the forward selector Mapping * ismap * Pointer to the inverse selector Mapping * nroute * The number of route Mappings. * routemaps * An array of pointers to the route Mappings. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new SwitchMap. The syntax used is the same as for the * astSet method and may include "printf" format specifiers identified * by "%" symbols in the normal way. * ... * 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 SwitchMap. * 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 SwitchMap constructor which is * available via the protected interface to the SwitchMap class. A * public interface is provided by the astSwitchMapId_ 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 * "map1" and "map2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSwitchMap *new; /* Pointer to new SwitchMap */ AstMapping *fsmap; /* Pointer to fwd selector Mapping */ AstMapping *ismap; /* Pointer to inv selector Mapping */ AstMapping **routemaps; /* Array of route Mapping pointers */ int i; /* Route Mappings index */ 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; /* Report an error if no route Mappings have been supplied. */ if( nroute <= 0 ) astError( AST__BDPAR, "astSwitchMap(SwitchMap): " "Bad number of route Mappings (%d) specified.", status, nroute ); /* Otherwise create an array to hold the route Mapping pointers. */ routemaps = astMalloc( sizeof( AstMapping * )*nroute ); /* Obtain and validate pointers to the Mapping structures provided. */ if( astOK ) { fsmap = fsmap_void ? astCheckMapping( fsmap_void ) : NULL; ismap = ismap_void ? astCheckMapping( ismap_void ) : NULL; for( i = 0; i < nroute; i++ ) { routemaps[ i ] = astCheckMapping( routemaps_void[ i ] ); } } if ( astOK ) { /* Initialise the SwitchMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSwitchMap( NULL, sizeof( AstSwitchMap ), !class_init, &class_vtab, "SwitchMap", fsmap, ismap, nroute, routemaps ); /* 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 SwitchMap'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 ); } } /* Free memory used to hold the route Mapping pointers. */ routemaps = astFree( routemaps ); /* Return a pointer to the new SwitchMap. */ return new; } AstSwitchMap *astSwitchMapId_( void *fsmap_void, void *ismap_void, int nroute, void **routemaps_void, const char *options, ... ) { /* *++ * Name: c astSwitchMap f AST_SWITCHMAP * Purpose: * Create a SwitchMap. * Type: * Public function. * Synopsis: c #include "switchmap.h" c AstSwitchMap *astSwitchMap( AstMapping *fsmap, AstMapping *ismap, c int nroute, AstMapping *routemaps[], c const char *options, ... ) f RESULT = AST_SWITCHMAP( FSMAP, ISMAP, NROUTE, ROUTEMAPS, OPTIONS, f STATUS ) * Class Membership: * SwitchMap constructor. * Description: * This function creates a new SwitchMap and optionally initialises * its attributes. * * A SwitchMap is a Mapping which represents a set of alternate * Mappings, each of which is used to transform positions within a * particular region of the input or output coordinate system of the * SwitchMap. * * A SwitchMap can encapsulate any number of Mappings, but they must * all have the same number of inputs (Nin attribute value) and the * same number of outputs (Nout attribute value). The SwitchMap itself * inherits these same values for its Nin and Nout attributes. Each of * these Mappings represents a "route" through the switch, and are * referred to as "route" Mappings below. Each route Mapping transforms * positions between the input and output coordinate space of the entire * SwitchMap, but only one Mapping will be used to transform any given * position. The selection of the appropriate route Mapping to use with * any given input position is made by another Mapping, called the * "selector" Mapping. Each SwitchMap encapsulates two selector * Mappings in addition to its route Mappings; one for use with the * SwitchMap's forward transformation (called the "forward selector * Mapping"), and one for use with the SwitchMap's inverse transformation * (called the "inverse selector Mapping"). The forward selector Mapping * must have the same number of inputs as the route Mappings, but * should have only one output. Likewise, the inverse selector Mapping * must have the same number of outputs as the route Mappings, but * should have only one input. * * When the SwitchMap is used to transform a position in the forward * direction (from input to output), each supplied input position is * first transformed by the forward transformation of the forward selector * Mapping. This produces a single output value for each input position * referred to as the selector value. The nearest integer to the selector * value is found, and is used to index the array of route Mappings (the * first supplied route Mapping has index 1, the second route Mapping has * index 2, etc). If the nearest integer to the selector value is less * than 1 or greater than the number of route Mappings, then the SwitchMap * output position is set to a value of AST__BAD on every axis. Otherwise, * the forward transformation of the selected route Mapping is used to * transform the supplied input position to produce the SwitchMap output * position. * * When the SwitchMap is used to transform a position in the inverse * direction (from "output" to "input"), each supplied "output" position * is first transformed by the inverse transformation of the inverse * selector Mapping. This produces a selector value for each "output" * position. Again, the nearest integer to the selector value is found, * and is used to index the array of route Mappings. If this selector * index value is within the bounds of the array of route Mappings, then * the inverse transformation of the selected route Mapping is used to * transform the supplied "output" position to produce the SwitchMap * "input" position. If the selector index value is outside the bounds * of the array of route Mappings, then the SwitchMap "input" position is * set to a value of AST__BAD on every axis. * * In practice, appropriate selector Mappings should be chosen to * associate a different route Mapping with each region of coordinate * space. Note that the SelectorMap class of Mapping is particularly * appropriate for this purpose. * * If a compound Mapping contains a SwitchMap in series with its own * inverse, the combination of the two adjacent SwitchMaps will be * replaced by a UnitMap when the compound Mapping is simplified using c astSimplify. f AST_SIMPLIFY. * Parameters: c fsmap f FSMAP = INTEGER (Given) * Pointer to the forward selector Mapping. This must have a * defined forward transformation, but need not have a defined * inverse transformation. It must have one output, and the number of * inputs must match the number of inputs of each of the supplied * route Mappings. c NULL f AST__NULL * may be supplied, in which case the SwitchMap will have an undefined * forward Mapping. c ismap f ISMAP = INTEGER (Given) * Pointer to the inverse selector Mapping. This must have a * defined inverse transformation, but need not have a defined * forward transformation. It must have one input, and the number of * outputs must match the number of outputs of each of the supplied * route Mappings. c NULL f AST__NULL * may be supplied, in which case the SwitchMap will have an undefined * inverse Mapping. c nroute f NROUTE = INTEGER (Given) * The number of supplied route Mappings. c routemaps f ROUTEMAPS( NROUTE ) = INTEGER (Given) * An array of pointers to the route Mappings. All the supplied * route Mappings must have common values for the Nin and Nout * attributes, and these values define the number of inputs and * outputs of the SwitchMap. 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 SwitchMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new SwitchMap. The syntax used is identical to that for the f AST_SET routine. 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 astSwitchMap() f AST_SWITCHMAP = INTEGER * A pointer to the new SwitchMap. * Notes: c - Note that the component Mappings supplied are not copied by c astSwitchMap (the new SwitchMap simply retains a reference to c them). They may continue to be used for other purposes, but c should not be deleted. If a SwitchMap containing a copy of its c component Mappings is required, then a copy of the SwitchMap should c be made using astCopy. f - Note that the component Mappings supplied are not copied by f AST_SWITCHMAP (the new SwitchMap simply retains a reference to f them). They may continue to be used for other purposes, but f should not be deleted. If a SwitchMap containing a copy of its f component Mappings is required, then a copy of the SwitchMap should f be made using AST_COPY. * - 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 astSwitchMap constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astSwitchMap_ 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 "map1" and "map2" parameters * are of type (void *) and are converted from an ID value to a * pointer and validated within the function itself. * - The variable argument list also prevents this function from * invoking astSwitchMap_ 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 */ AstSwitchMap *new; /* Pointer to new SwitchMap */ AstMapping *fsmap; /* Pointer to fwd selector Mapping */ AstMapping *ismap; /* Pointer to inv selector Mapping */ AstMapping **routemaps; /* Array of route Mapping pointers */ int i; /* Route Mappings index */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ new = NULL; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return new; /* Report an error if no route Mappings have been supplied. */ if( nroute <= 0 ) astError( AST__BDPAR, "astSwitchMap(SwitchMap): " " Bad number of route Mappings (%d) specified.", status, nroute ); /* Otherwise create an array to hold the route Mapping pointers. */ routemaps = astMalloc( sizeof( AstMapping * )*nroute ); /* Obtain and validate pointers to the Mapping structures provided. */ if( astOK ) { fsmap = fsmap_void ? astCheckMapping( astMakePointer(fsmap_void) ) : NULL; ismap = ismap_void ? astCheckMapping( astMakePointer(ismap_void) ) : NULL; for( i = 0; i < nroute; i++ ) { routemaps[ i ] = astVerifyMapping( astMakePointer(routemaps_void[ i ]) ); } } if ( astOK ) { /* Initialise the SwitchMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSwitchMap( NULL, sizeof( AstSwitchMap ), !class_init, &class_vtab, "SwitchMap", fsmap, ismap, nroute, routemaps ); /* 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 SwitchMap'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 ); } } /* Free memory used to hold the route Mapping pointers. */ routemaps = astFree( routemaps ); /* Return an ID value for the new SwitchMap. */ return astMakeId( new ); } AstSwitchMap *astInitSwitchMap_( void *mem, size_t size, int init, AstSwitchMapVtab *vtab, const char *name, AstMapping *fsmap, AstMapping *ismap, int nroute, AstMapping **routemaps, int *status ) { /* *+ * Name: * astInitSwitchMap * Purpose: * Initialise a SwitchMap. * Type: * Protected function. * Synopsis: * #include "switchmap.h" * AstSwitchMap *astInitSwitchMap( void *mem, size_t size, int init, * AstSwitchMapVtab *vtab, const char *name, * AstMapping *fsmap, AstMapping *ismap, * int nroute, AstMapping **routemaps ) * Class Membership: * SwitchMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new SwitchMap object. It allocates memory (if necessary) to * accommodate the SwitchMap plus any additional data associated with the * derived class. It then initialises a SwitchMap 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 SwitchMap at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SwitchMap is to be initialised. * This must be of sufficient size to accommodate the SwitchMap data * (sizeof(SwitchMap)) 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 SwitchMap (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 * SwitchMap structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the SwitchMap'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 SwitchMap. * 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 Object * astClass function). * fsmap * Pointer to the forward selector Mapping. * ismap * Pointer to the inverse selector Mapping. * nroute * The number of route Mappings supplied. * routemaps * An array holdiong pointers to the route Mappings. * Returned Value: * A pointer to the new SwitchMap. * 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: */ AstSwitchMap *new; /* Pointer to new SwitchMap */ int i; /* Loop count */ int nin; /* No. input coordinates for SwitchMap */ int nout; /* No. output coordinates for SwitchMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSwitchMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check that all route Mappings have common values for Nin and Nout.*/ nin = astGetNin( routemaps[ 0 ] ); nout = astGetNout( routemaps[ 0 ] ); for( i = 1; i < nroute; i++ ) { if( nin != astGetNin( routemaps[ i ] ) ){ if( astOK ) { astError( AST__BADNI, "astInitSwitchMap(%s): Route Mapping " "number %d has %d input(s) but the first route " "Mapping has %d input(s).", status, name, i + 1, astGetNin( routemaps[ i ] ), nin ); } } else if( nout != astGetNout( routemaps[ i ] ) ){ if( astOK ) { astError( AST__BADNO, "astInitSwitchMap(%s): Route Mapping " "number %d has %d output(s) but the first route " "Mapping has %d output(s).", status, name, i + 1, astGetNin( routemaps[ i ] ), nin ); } } } /* If supplied, report an error if fsmap has no forward transformation, or if it has an incorrect number of inputs or output. */ if( fsmap && astOK ) { if( !astGetTranForward( fsmap ) ) { astError( AST__INTRD, "astInitSwitchMap(%s): The forward selector Mapping " "is not able to transform coordinates in the forward direction.", status, name ); } else if( astGetNin( fsmap ) != nin ){ astError( AST__BADNI, "astInitSwitchMap(%s): The forward selector " "Mapping has %d input(s) but the SwitchMap has %d " "input(s).", status, name, astGetNin( fsmap ), nin ); } else if( astGetNout( fsmap ) != 1 ){ astError( AST__BADNO, "astInitSwitchMap(%s): The forward selector " "Mapping has %d outputs but should only have 1.", status, name, astGetNout( fsmap ) ); } } /* If supplied, report an error if ismap has no inverse transformation, or if it has an incorrect number of inputs or outputs. */ if( ismap && astOK ) { if( !astGetTranInverse( ismap ) ) { astError( AST__INTRD, "astInitSwitchMap(%s): The inverse selector Mapping " "is not able to transform coordinates in the inverse direction.", status, name ); } else if( nout != astGetNout( ismap ) ){ astError( AST__BADNO, "astInitSwitchMap(%s): The inverse selector " "Mapping has %d output(s) but the SwitchMap has %d " "output(s).", status, name, astGetNout( ismap ), nout ); } else if( astGetNin( ismap ) != 1 ){ astError( AST__BADNI, "astInitSwitchMap(%s): The inverse selector " "Mapping has %d inputs but should only have 1.", status, name, astGetNin( ismap ) ); } } /* Report an error if neither ismap nor fsmap were supplied. */ if( !fsmap && !ismap && astOK ) { astError( AST__INTRD, "astInitSwitchMap(%s): No selector Mappings " "supplied.", status, name ); } /* Initialise a Mapping structure (the parent class) as the first component within the SwitchMap structure, allocating memory if necessary. Specify the number of input and output coordinates and in which directions the Mapping should be defined. */ if ( astOK ) { new = (AstSwitchMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, ( fsmap != NULL ), ( ismap != NULL ) ); if ( astOK ) { /* Initialise the SwitchMap data. */ /* --------------------------- */ /* Store pointers to the selector Mappings. */ new->fsmap = fsmap ? astClone( fsmap ) : NULL; new->ismap = ismap ? astClone( ismap ) : NULL; /* Save the initial values of the inversion flags for these Mappings. */ new->fsinv = fsmap ? astGetInvert( fsmap ) : 0; new->isinv = ismap ? astGetInvert( ismap ) : 0; /* Create arrays for the route Mappings. */ new->routemap = astMalloc( sizeof( AstMapping * )*nroute ); new->routeinv = astMalloc( sizeof( int )*nroute ); /* Store pointers to the route Mappings and their invert flags. */ if( astOK ) { new->nroute = nroute; for( i = 0; i < nroute; i++ ) { new->routemap[ i ] = astClone( routemaps[ i ] ); new->routeinv[ i ] = astGetInvert( routemaps[ i ] ); } } else { new->nroute = 0; } /* 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; } AstSwitchMap *astLoadSwitchMap_( void *mem, size_t size, AstSwitchMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSwitchMap * Purpose: * Load a SwitchMap. * Type: * Protected function. * Synopsis: * #include "switchmap.h" * AstSwitchMap *astLoadSwitchMap( void *mem, size_t size, * AstSwitchMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SwitchMap loader. * Description: * This function is provided to load a new SwitchMap 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 * SwitchMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a SwitchMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the SwitchMap is to be * loaded. This must be of sufficient size to accommodate the * SwitchMap data (sizeof(SwitchMap)) 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 SwitchMap (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 SwitchMap 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(AstSwitchMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SwitchMap. If this is NULL, a pointer to * the (static) virtual function table for the SwitchMap 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 "SwitchMap" is used instead. * Returned Value: * A pointer to the new SwitchMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSwitchMap *new; AstMapping *rmap; int i; char buf[ 20 ]; /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this SwitchMap. In this case the SwitchMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSwitchMap ); vtab = &class_vtab; name = "SwitchMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSwitchMapVtab( 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 SwitchMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "SwitchMap" ); /* 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. */ /* Forward Selector Mapping and its Invert flag. */ /* --------------------------------------------- */ new->fsmap = astReadObject( channel, "fsmap", NULL ); new->fsinv = astReadInt( channel, "fsinv", 0 ); new->fsinv = ( new->fsinv != 0 ); /* Inverse Selector Mapping and its Invert flag. */ /* --------------------------------------------- */ new->ismap = astReadObject( channel, "ismap", NULL ); new->isinv = astReadInt( channel, "isinv", new->fsinv ); new->isinv = ( new->isinv != 0 ); /* Loop to load each route Mapping and its invert flag. */ /* ---------------------------------------------------- */ new->routemap = NULL; new->routeinv = NULL; i = 0; while( astOK ) { sprintf( buf, "rmap%d", i + 1 ); rmap = astReadObject( channel, buf, NULL ); if( rmap ) { new->routemap = astGrow( new->routemap, i + 1, sizeof( AstMapping *) ); new->routeinv = astGrow( new->routeinv, i + 1, sizeof( int ) ); if( astOK ) { new->routemap[ i ] = rmap; sprintf( buf, "rinv%d", i + 1 ); new->routeinv[ i ] = astReadInt( channel, buf, 0 ); new->routeinv[ i ] = ( new->routeinv[ i ] != 0 ); i++; } } else { break; } } /* Number of route Mappings. */ new->nroute = i; /* If an error occurred, clean up by deleting the new SwitchMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SwitchMap pointer. */ return new; } /* 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. */ /* None. */ ast-8.3.0/f77.h0000664000175000017500000011762513004147333010022 00000000000000/* *+ * Name: * f77.h and cnf.h * Purpose: * C - FORTRAN interace macros and prototypes * Language: * C (part ANSI, part not) * Type of Module: * C include file * Description: * For historical reasons two files, F77.h and cnf.h are required * but the have now been combined and for new code, only one is * necessary. * * This file defines the macros needed to write C functions that are * designed to be called from FORTRAN programs, and to do so in a * portable way. Arguments are normally passed by reference from a * FORTRAN program, and so the F77 macros arrange for a pointer to * all arguments to be available. This requires no work on most * machines, but will actually generate the pointers on a machine * that passes FORTRAN arguments by value. * Notes: * - Macros are provided to handle the conversion of logical data * values between the way that FORTRAN represents a value and the * way that C represents it. * - Macros are provided to convert variables between the FORTRAN and * C method of representing them. In most cases there is no * conversion required, the macros just arrange for a pointer to * the FORTRAN variable to be set appropriately. The possibility that * FORTRAN and C might use different ways of representing integer * and floating point values is considered remote, the macros are * really only there for completeness and to assist in the automatic * generation of C interfaces. * - For character variables the macros convert between * the FORTRAN method of representing them (fixed length, blank * filled strings) and the C method (variable length, null * terminated strings) using calls to the CNF functions. * Implementation Deficiencies: * - The macros support the K&R style of function definition, but * this file may not work with all K&R compilers as it contains * "#if defined" statements. These could be replaced with #ifdef's * if necessary. This has not been done as is would make the code * less clear and the need for support for K&R sytle definitions * should disappear as ANSI compilers become the default. * Copyright: * Copyright (C) 1991, 1993 Science & Engineering Research Council. * Copyright (C) 2006 Particle Physics and Astronomy Research Council. * Copyright (C) 2007,2008 Science and Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 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 General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA * 02110-1301, USA * Authors: * PMA: Peter Allan (Starlink, RAL) * AJC: Alan Chipperfield (Starlink, RAL) * TIMJ: Tim Jenness (JAC) * PWD: Peter W. Draper (JAC, Durham University) * {enter_new_authors_here} * History: * 23-MAY-1991 (PMA): * Original version. * 19-JUN-1991 (PMA): * Removed VMS versions of IM(EX)PORT_LOGICAL macros that tried * to convert data representations. * 24-JUN-1991 (PMA): * Changed the names of IMPORT macros to GENPTR. * Removed the EXPORT macros. * 27-JUN-1991 (PMA): * Modified DECstation specific stuff to allow use of the c89 * compiler. * 8-JUL-1991 (PMA): * Added macros to call FORTRAN from C. * 16-OCT-1991 (PMA): * Remove type_ARRAY2 definitions. * Remove the length argument from CHARACTER_ARRAY and the * dimension specifier from GENPTR_type_ARRAY. * Add extra brackets to F77_ISFALSE and F77_ISTRUE. * 25-OCT-1991 (PMA): * Changed "if defined(sun4)" to "if defined(sun)" * 2-JUN-1992 (PMA): * Changed "if defined(mips)" to "if defined(ultrix)" to prevent * those definitions being used on a Silicon Graphics machine. * 11-JUN-1992 (PMA): * Changed "if defined(ultrix)" back to "if defined(mips)" so that * it still works on OSF/1 on a DECstation. * Add support for general non-ANSI compilers, but not basic K&R * ones. * 12-JUN-1992 (PMA): * Change declaration of dummy scalar arguments to be const * pointers. Change declaration of dummy array arguments to be * const pointers. * 5-JAN-1993 (PMA): * Changed "if defined(mips)" so that it will recognise a * DECstation running Ultrix or OSF/1, but not a Silicon Graphics * workstation. * Change the definition of F77_BYTE_TYPE to add "signed". * Redefine this on VMS where signed is invalid syntax. * Add new types of UBYTE and UWORD. * 8-JAN-1993 (PMA): * Fix bug in the definition of CHARACTER_RETURN_VALUE. There was * an extraneous space. * Add a macro F77_POINTER_TYPE and use it to define POINTER. * 13-JAN-1993 (PMA): * Start to add support for K&R function definitions. These are * done on a per machine basis. * 16-APR-1993 (PMA): * Change the definition of F77_POINTER_TYPE from int to unsigned * int. * 7-MAY-1993 (PMA): * Change from using a null comment as a token concatenation * operator to using the internal macro _f77_x on non-ANSI * systems. * 10-MAY-1993 (PMA): * Finish adding K&R support. This will form version 2.0 of F77. * 10-MAY-1993 (PMA): * Add support for Alpha OSF/1. * 9-JUL-1993 (PMA): * Add further POINTER macros: POINTER_ARRAY, * GENPTR_POINTER_ARRAY, DECLARE_POINTER, DECLARE_POINTER_ARRAY, * POINTER_ARG, POINTER_ARRAY_ARG, F77_POINTER_FUNCTION, * KR_POINTER_ARRAY. * 24-AUG-1993 (PMA): * Add const to the VMS definitions of CHARACTER and CHARACTER_ARRAY. * 3-NOV-1993 (PMA): * Remove K&R stuff to a separate file. * Released on Unix as version 2.0 of CNF. * 11-NOV-1993 (PMA): * Return to using the null comment to concatenate text on non-ANSI * systems as _f77_x caused problems with the c89 -common flag on * DECstations. * 23-JAN-1996 (AJC): * Add SUBROUTINE, type_FUNCTION, SUBROUTINE_ARG, * type_FUNCTION_ARG, GENPTR_SUBROUTINE and GENPTR_type_FUNCTION * required for passed subroutine and function name. * 29-JAN-1996 (AJC): * Add the dynamic CHARACTER_ macros * and CHARACTER_ARG_TYPE * 22-FEB-1996 (AJC): * Add CHARACTER_RETURN_ARG * 23-MAY-1996 (AJC): * Add DECLARE_CHARACTER_ARRAY_DYN * F77_CREATE_CHARACTER_ARRAY * F77_CHARACTER_ARG_TYPE * 14-JUN-1996 (AJC): * Add DECLARE_LOGICAL_ARRAY_DYN * F77_CREATE_LOGICAL_ARRAY * 21-JUN-1996 (AJC): * Add cast to _ARRAY_ARGs to allow multidimensional arrays * 17-MAR-1998 (AJC): * Add DECLARE, CREATE and FREE dynamic array macros for all types * Changed CREATE_CHARACTER_ARRAY and CREATE_LOGICAL_ARRAY to use * number of elements rather than dimensions. * Add IMPORT, EXPORT and ASSOC macros * 22-JUL-1998 (AJC): * Combined F77.h and cnf.h * 23-SEP-1998 (AJC): * Input strings for cnf -> const char * * Input int arrays for cnf -> const int * * 4-NOV-1998 (AJC): * Bring cnf prototypes in line with .c routines * 8-FEB-1999 (AJC): * Added cnf_mem stuff * 9-FEB-1999 (AJC): * Use cnf_cptr/fptr for IMPORT/EXPORT_POINTER * 16-FEB-1999 (AJC): * Added missing cnf_fptr prototype * 23-JUN-1999 (AJC): * Change cnf_name to cnfName * and add macros for cnf_name * 1-DEC-1999 (AJC): * Add define cnf_free * 7-JAN-2000 (AJC): * Correct omission of F77_ASSOC_UBYTE_ARRAY * Correct F77_EXPORT_UWORD_ARRAY * 25-AUG-2005 (TIMJ): * Add cnfInitRTL * 23-FEB-2006 (TIMJ): * Add cnfRealloc * Use starMalloc rather than malloc in F77_CREATE_POINTER_ARRAY * (since it needs to match what goes on in cnfFree) * 21-JUN-2006 (PWD): * Changed to use a different return type for REAL functions. This * effects g77 under 64-bit, when the f2c bindings expect the return * value of a REAL function to be a double, not a float. * 25-SEP-2006 (PWD): * Introduced F77_CREATE_IMPORT_CHARACTER. Match length of * F77_CREATE_CHARACTER to result from cnfCref. * 13-JUL-2007 (PWD): * Parameterise the type of Fortran character string lengths. Can * be long. * 7-OCT-2008 (TIMJ): * Initialise pointers. * 11-MAY-2011 (DSB): * Added F77_LOCK * {enter_further_changes_here} * * Bugs: * {note_any_bugs_here} *- ------------------------------------------------------------------------------ */ #if !defined(CNF_MACROS) #define CNF_MACROS #include #include /* This initial sections defines values for all macros. These are the */ /* values that are generally appropriate to an ANSI C compiler on Unix. */ /* For macros that have different values on other systems, the macros */ /* should be undefined and then redefined in the system specific sections. */ /* At the end of this section, some macros are redefined if the compiler */ /* is non-ANSI. */ #if defined(__STDC__) || defined(VMS) #define CNF_CONST const #else #define CNF_CONST #endif /* ----- Macros common to calling C from FORTRAN and FORTRAN from C ---- */ /* --- External Names --- */ /* Macro to define the name of a Fortran routine or common block. This */ /* ends in an underscore on many Unix systems. */ #define F77_EXTERNAL_NAME(X) X ## _ /* --- Logical Values --- */ /* Define the values that are used to represent the logical values TRUE */ /* and FALSE in Fortran. */ #define F77_TRUE 1 #define F77_FALSE 0 /* Define macros that evaluate to C logical values, given a FORTRAN */ /* logical value. */ #define F77_ISTRUE(X) ( X ) #define F77_ISFALSE(X) ( !( X ) ) /* --- Common Blocks --- */ /* Macros used in referring to FORTRAN common blocks. */ #define F77_BLANK_COMMON @BLANK_COMMON_SYMBOL@ #define F77_NAMED_COMMON(B) F77_EXTERNAL_NAME(B) /* ------------------ Calling C from FORTRAN --------------------------- */ /* --- Data Types --- */ /* Define macros for all the Fortran data types (except COMPLEX, which is */ /* not handled by this package). */ #define F77_INTEGER_TYPE int #define F77_REAL_TYPE float #define F77_REAL_FUNCTION_TYPE float #define F77_DOUBLE_TYPE double #define F77_LOGICAL_TYPE int #define F77_CHARACTER_TYPE char #define F77_BYTE_TYPE signed char #define F77_WORD_TYPE short int #define F77_UBYTE_TYPE unsigned char #define F77_UWORD_TYPE unsigned short int /* Define macros for the type of a CHARACTER and CHARACTER_ARRAY argument */ #define F77_CHARACTER_ARG_TYPE char #define F77_CHARACTER_ARRAY_ARG_TYPE char /* Define a macro to use when passing arguments that STARLINK FORTRAN */ /* treats as a pointer. From the point of view of C, this type should be */ /* (void *), but it is declared as type unsigned int as we actually pass */ /* an INTEGER from the FORTRAN routine. The distinction is important for */ /* architectures where the size of an INTEGER is not the same as the size */ /* of a pointer. */ #define F77_POINTER_TYPE unsigned int /* --- Subroutine Names --- */ /* This declares that the C function returns a value of void. */ #define F77_SUBROUTINE(X) void F77_EXTERNAL_NAME(X) /* --- Function Names --- */ /* Macros to define the types and names of functions that return values. */ /* Due the the different ways that function return values could be */ /* implemented, it is better not to use functions, but to stick to using */ /* subroutines. */ /* Character functions are implemented, but in a way that cannot be */ /* guaranteed to be portable although it will work on VMS, SunOS, Ultrix */ /* and DEC OSF/1. It would be better to return the character value as a */ /* subroutine argument where possible, rather than use a character */ /* function. */ #define F77_INTEGER_FUNCTION(X) F77_INTEGER_TYPE F77_EXTERNAL_NAME(X) #define F77_REAL_FUNCTION(X) F77_REAL_FUNCTION_TYPE F77_EXTERNAL_NAME(X) #define F77_DOUBLE_FUNCTION(X) F77_DOUBLE_TYPE F77_EXTERNAL_NAME(X) #define F77_LOGICAL_FUNCTION(X) F77_LOGICAL_TYPE F77_EXTERNAL_NAME(X) #define F77_CHARACTER_FUNCTION(X) void F77_EXTERNAL_NAME(X) #define F77_BYTE_FUNCTION(X) F77_BYTE_TYPE F77_EXTERNAL_NAME(X) #define F77_WORD_FUNCTION(X) F77_WORD_TYPE F77_EXTERNAL_NAME(X) #define F77_UBYTE_FUNCTION(X) F77_UBYTE_TYPE F77_EXTERNAL_NAME(X) #define F77_UWORD_FUNCTION(X) F77_UWORD_TYPE F77_EXTERNAL_NAME(X) #define F77_POINTER_FUNCTION(X) F77_POINTER_TYPE F77_EXTERNAL_NAME(X) /* --- Character return value for a function --- */ #define CHARACTER_RETURN_VALUE(X) CHARACTER(X) TRAIL(X) #define CHARACTER_RETURN_ARG(X) CHARACTER_ARG(X) TRAIL_ARG(X) /* --- Dummy Arguments --- */ /* Macros for defining subroutine arguments. All these macros take a */ /* single argument; the name of the parameter. On most systems, a numeric */ /* argument is passed as a pointer. */ #define INTEGER(X) F77_INTEGER_TYPE *CNF_CONST X #define REAL(X) F77_REAL_TYPE *CNF_CONST X #define DOUBLE(X) F77_DOUBLE_TYPE *CNF_CONST X #define LOGICAL(X) F77_LOGICAL_TYPE *CNF_CONST X #define BYTE(X) F77_BYTE_TYPE *CNF_CONST X #define WORD(X) F77_WORD_TYPE *CNF_CONST X #define UBYTE(X) F77_UBYTE_TYPE *CNF_CONST X #define UWORD(X) F77_UWORD_TYPE *CNF_CONST X /* Pointer arguments. Define a pointer type for passing pointer values */ /* between subroutines. */ #define POINTER(X) F77_POINTER_TYPE *CNF_CONST X /* EXTERNAL arguments. Define a passed subroutine or function name */ #define SUBROUTINE(X) void (*X)() #define INTEGER_FUNCTION(X) F77_INTEGER_TYPE (*X)() #define REAL_FUNCTION(X) F77_REAL_TYPE (*X)() #define DOUBLE_FUNCTION(X) F77_DOUBLE_TYPE (*X)() #define LOGICAL_FUNCTION(X) F77_LOGICAL_TYPE (*X)() #define CHARACTER_FUNCTION(X) F77_CHARACTER_TYPE (*X)() #define BYTE_FUNCTION(X) F77_BYTE_TYPE (*X)() #define WORD_FUNCTION(X) F77_WORD_TYPE (*X)() #define UBYTE_FUNCTION(X) F77_UBYTE_TYPE (*X)() #define UWORD_FUNCTION(X) F77_UWORD_TYPE (*X)() #define POINTER_FUNCTION(X) F77_POINTER_TYPE (*X)() /* Array arguments. */ #define INTEGER_ARRAY(X) F77_INTEGER_TYPE *CNF_CONST X #define REAL_ARRAY(X) F77_REAL_TYPE *CNF_CONST X #define DOUBLE_ARRAY(X) F77_DOUBLE_TYPE *CNF_CONST X #define LOGICAL_ARRAY(X) F77_LOGICAL_TYPE *CNF_CONST X #define BYTE_ARRAY(X) F77_BYTE_TYPE *CNF_CONST X #define WORD_ARRAY(X) F77_WORD_TYPE *CNF_CONST X #define UBYTE_ARRAY(X) F77_UBYTE_TYPE *CNF_CONST X #define UWORD_ARRAY(X) F77_UWORD_TYPE *CNF_CONST X #define POINTER_ARRAY(X) F77_POINTER_TYPE *CNF_CONST X /* Macros to handle character arguments. */ /* Character arguments can be passed in many ways. The purpose of these */ /* macros and the GENPTR_CHARACTER macro (defined in the next section) is */ /* to generate a pointer to a character variable called ARG and an integer */ /* ARG_length containing the length of ARG. If these two variables are */ /* available directly from the argument list of the routine, then the */ /* GENPTR_CHARACTER macro is null, otherwise it works on intermediate */ /* variables. */ #define CHARACTER(X) F77_CHARACTER_TYPE *CNF_CONST X #define TRAIL(X) ,int X ## _length #define CHARACTER_ARRAY(X) F77_CHARACTER_TYPE *CNF_CONST X /* --- Getting Pointers to Arguments --- */ /* Macros that ensure that a pointer to each argument is available for the */ /* programmer to use. Usually this means that these macros are null. On */ /* VMS, a pointer to a character variable has to be generated. If a */ /* particular machine were to pass arguments by reference, rather than by */ /* value, then these macros would construct the appropriate pointers. */ #define GENPTR_INTEGER(X) #define GENPTR_REAL(X) #define GENPTR_DOUBLE(X) #define GENPTR_CHARACTER(X) #define GENPTR_LOGICAL(X) #define GENPTR_BYTE(X) #define GENPTR_WORD(X) #define GENPTR_UBYTE(X) #define GENPTR_UWORD(X) #define GENPTR_POINTER(X) #define GENPTR_INTEGER_ARRAY(X) #define GENPTR_REAL_ARRAY(X) #define GENPTR_DOUBLE_ARRAY(X) #define GENPTR_CHARACTER_ARRAY(X) #define GENPTR_LOGICAL_ARRAY(X) #define GENPTR_BYTE_ARRAY(X) #define GENPTR_WORD_ARRAY(X) #define GENPTR_UBYTE_ARRAY(X) #define GENPTR_UWORD_ARRAY(X) #define GENPTR_POINTER_ARRAY(X) #define GENPTR_SUBROUTINE(X) #define GENPTR_INTEGER_FUNCTION(X) #define GENPTR_REAL_FUNCTION(X) #define GENPTR_DOUBLE_FUNCTION(X) #define GENPTR_CHARACTER_FUNCTION(X) #define GENPTR_LOGICAL_FUNCTION(X) #define GENPTR_BYTE_FUNCTION(X) #define GENPTR_WORD_FUNCTION(X) #define GENPTR_UBYTE_FUNCTION(X) #define GENPTR_UWORD_FUNCTION(X) #define GENPTR_POINTER_FUNCTION(X) /* ------------------ Calling FORTRAN from C --------------------------- */ /* --- Declare variables --- */ #define DECLARE_INTEGER(X) F77_INTEGER_TYPE X #define DECLARE_REAL(X) F77_REAL_TYPE X #define DECLARE_DOUBLE(X) F77_DOUBLE_TYPE X #define DECLARE_LOGICAL(X) F77_LOGICAL_TYPE X #define DECLARE_BYTE(X) F77_BYTE_TYPE X #define DECLARE_WORD(X) F77_WORD_TYPE X #define DECLARE_UBYTE(X) F77_UBYTE_TYPE X #define DECLARE_UWORD(X) F77_UWORD_TYPE X #define DECLARE_POINTER(X) F77_POINTER_TYPE X #define DECLARE_CHARACTER(X,L) F77_CHARACTER_TYPE X[L]; \ const int X##_length = L /* --- Declare arrays --- */ #define DECLARE_INTEGER_ARRAY(X,D) F77_INTEGER_TYPE X[D] #define DECLARE_REAL_ARRAY(X,D) F77_REAL_TYPE X[D] #define DECLARE_DOUBLE_ARRAY(X,D) F77_DOUBLE_TYPE X[D] #define DECLARE_LOGICAL_ARRAY(X,D) F77_LOGICAL_TYPE X[D] #define DECLARE_BYTE_ARRAY(X,D) F77_BYTE_TYPE X[D] #define DECLARE_WORD_ARRAY(X,D) F77_WORD_TYPE X[D] #define DECLARE_UBYTE_ARRAY(X,D) F77_UBYTE_TYPE X[D] #define DECLARE_UWORD_ARRAY(X,D) F77_UWORD_TYPE X[D] #define DECLARE_POINTER_ARRAY(X,D) F77_POINTER_TYPE X[D] #define DECLARE_CHARACTER_ARRAY(X,L,D) F77_CHARACTER_TYPE X[D][L]; \ const int X##_length = L /* --- Declare and construct dynamic CHARACTER arguments --- */ #define DECLARE_CHARACTER_DYN(X) F77_CHARACTER_TYPE *X = NULL;\ int X##_length = 0 #define F77_CREATE_CHARACTER(X,L) X=cnfCref(L);\ X##_length = (L>0?L:1) /* Declare Dynamic Fortran arrays */ #define DECLARE_INTEGER_ARRAY_DYN(X) F77_INTEGER_TYPE *X = NULL #define DECLARE_REAL_ARRAY_DYN(X) F77_REAL_TYPE *X = NULL #define DECLARE_DOUBLE_ARRAY_DYN(X) F77_DOUBLE_TYPE *X = NULL #define DECLARE_LOGICAL_ARRAY_DYN(X) F77_LOGICAL_TYPE *X = NULL #define DECLARE_BYTE_ARRAY_DYN(X) F77_BYTE_TYPE *X = NULL #define DECLARE_WORD_ARRAY_DYN(X) F77_WORD_TYPE *X = NULL #define DECLARE_UBYTE_ARRAY_DYN(X) F77_UBYTE_TYPE *X = NULL #define DECLARE_UWORD_ARRAY_DYN(X) F77_UWORD_TYPE *X = NULL #define DECLARE_POINTER_ARRAY_DYN(X) F77_POINTER_TYPE *X = NULL #define DECLARE_CHARACTER_ARRAY_DYN(X) F77_CHARACTER_TYPE *X = NULL;\ int X##_length = 0 /* Create arrays dynamic Fortran arrays for those types which require */ /* Separate space for Fortran and C arrays */ /* Character and logical are already defined */ /* For most types there is nothing to do */ #define F77_CREATE_CHARACTER_ARRAY(X,L,N) \ {int f77dims[1];f77dims[0]=N;X=cnfCrefa(L,1,f77dims);X##_length=L;} #define F77_CREATE_CHARACTER_ARRAY_M(X,L,N,D) X=cnfCrefa(L,N,D);\ X##_length = L #define F77_CREATE_LOGICAL_ARRAY(X,N) \ {int f77dims[1];f77dims[0]=N;X=cnfCrela(1,f77dims);} #define F77_CREATE_LOGICAL_ARRAY_M(X,N,D) X=cnfCrela(N,D) #define F77_CREATE_INTEGER_ARRAY(X,N) #define F77_CREATE_REAL_ARRAY(X,N) #define F77_CREATE_DOUBLE_ARRAY(X,N) #define F77_CREATE_BYTE_ARRAY(X,N) #define F77_CREATE_UBYTE_ARRAY(X,N) #define F77_CREATE_WORD_ARRAY(X,N) #define F77_CREATE_UWORD_ARRAY(X,N) #define F77_CREATE_POINTER_ARRAY(X,N)\ X=(F77_POINTER_TYPE *) malloc(N*sizeof(F77_POINTER_TYPE)) /* Associate Fortran arrays with C arrays */ /* These macros ensure that there is space somewhere for the Fortran */ /* array. They are complemetary to the CREATE_type_ARRAY macros */ #define F77_ASSOC_CHARACTER_ARRAY(F,C) #define F77_ASSOC_LOGICAL_ARRAY(F,C) #define F77_ASSOC_INTEGER_ARRAY(F,C) F=C #define F77_ASSOC_REAL_ARRAY(F,C) F=C #define F77_ASSOC_DOUBLE_ARRAY(F,C) F=C #define F77_ASSOC_BYTE_ARRAY(F,C) F=C #define F77_ASSOC_UBYTE_ARRAY(F,C) F=C #define F77_ASSOC_WORD_ARRAY(F,C) F=C #define F77_ASSOC_UWORD_ARRAY(F,C) F=C #define F77_ASSOC_POINTER_ARRAY(F,C) /* Free created dynamic arrays */ /* Character and logical are already defined */ /* For most types there is nothing to do */ #define F77_FREE_INTEGER(X) #define F77_FREE_REAL(X) #define F77_FREE_DOUBLE(X) #define F77_FREE_BYTE(X) #define F77_FREE_UBYTE(X) #define F77_FREE_WORD(X) #define F77_FREE_UWORD(X) #define F77_FREE_POINTER(X) cnfFree((void *)X); #define F77_FREE_CHARACTER(X) cnfFreef( X ) #define F77_FREE_LOGICAL(X) cnfFree( (char *)X ) /* --- IMPORT and EXPORT of values --- */ /* Export C variables to Fortran variables */ #define F77_EXPORT_CHARACTER(C,F,L) cnfExprt(C,F,L) #define F77_EXPORT_DOUBLE(C,F) F=C #define F77_EXPORT_INTEGER(C,F) F=C #define F77_EXPORT_LOGICAL(C,F) F=C?F77_TRUE:F77_FALSE #define F77_EXPORT_REAL(C,F) F=C #define F77_EXPORT_BYTE(C,F) F=C #define F77_EXPORT_WORD(C,F) F=C #define F77_EXPORT_UBYTE(C,F) F=C #define F77_EXPORT_UWORD(C,F) F=C #define F77_EXPORT_POINTER(C,F) F=cnfFptr(C) #define F77_EXPORT_LOCATOR(C,F) cnfExpch(C,F,DAT__SZLOC) /* Allow for character strings to be NULL, protects strlen. Note this * does not allow lengths to differ. */ #define F77_CREATE_EXPORT_CHARACTER(C,F) \ if (C) { \ F77_CREATE_CHARACTER(F,strlen(C)); \ F77_EXPORT_CHARACTER(C,F,F##_length); \ } else { \ F77_CREATE_CHARACTER(F,1); \ F77_EXPORT_CHARACTER(" ",F,F##_length); \ } /* Export C arrays to Fortran */ /* Arrays are assumed to be 1-d so just the number of elements is given */ /* This may be OK for n-d arrays also */ /* CHARACTER arrays may be represented in C as arrays of arrays of char or */ /* as arrays of pointers to char (the _P variant) */ #define F77_EXPORT_CHARACTER_ARRAY(C,LC,F,LF,N) \ {int f77dims[1];f77dims[0]=N;cnfExprta(C,LC,F,LF,1,f77dims);} #define F77_EXPORT_CHARACTER_ARRAY_P(C,F,LF,N) \ {int f77dims[1];f77dims[0]=N;cnfExprtap(C,F,LF,1,f77dims);} #define F77_EXPORT_DOUBLE_ARRAY(C,F,N) F=(F77_DOUBLE_TYPE *)C #define F77_EXPORT_INTEGER_ARRAY(C,F,N) F=(F77_INTEGER_TYPE *)C #define F77_EXPORT_LOGICAL_ARRAY(C,F,N) \ {int f77dims[1];f77dims[0]=N;cnfExpla(C,F,1,f77dims);} #define F77_EXPORT_REAL_ARRAY(C,F,N) F=(F77_REAL_TYPE *)C #define F77_EXPORT_BYTE_ARRAY(C,F,N) F=(F77_BYTE_TYPE *)C #define F77_EXPORT_WORD_ARRAY(C,F,N) F=(F77_WORD_TYPE *)C #define F77_EXPORT_UBYTE_ARRAY(C,F,N) F=(F77_UBYTE_TYPE *)C #define F77_EXPORT_UWORD_ARRAY(C,F,N) F=(F77_UWORD_TYPE * )C #define F77_EXPORT_POINTER_ARRAY(C,F,N) \ {int f77i;for (f77i=0;f77i #endif #undef F77_CHARACTER_ARG_TYPE #define F77_CHARACTER_ARG_TYPE struct dsc$descriptor_s #undef F77_CHARACTER_ARRAY_ARG_TYPE #define F77_CHARACTER_ARRAY_ARG_TYPE struct dsc$descriptor_a #undef CHARACTER #define CHARACTER(X) F77_CHARACTER_ARG_TYPE *CNF_CONST X/**/_arg #undef TRAIL #define TRAIL(X) #undef CHARACTER_ARRAY #define CHARACTER_ARRAY(X) F77_CHARACTER_ARRAY_ARG_TYPE *CNF_CONST X/**/_arg #undef GENPTR_CHARACTER #define GENPTR_CHARACTER(X) \ F77_CHARACTER_TYPE *X = X/**/_arg->dsc$a_pointer; \ int X/**/_length = X/**/_arg->dsc$w_length; #undef GENPTR_CHARACTER_ARRAY #define GENPTR_CHARACTER_ARRAY(X) GENPTR_CHARACTER(X) /* --- Logical Values --- */ #undef F77_TRUE #define F77_TRUE -1 #undef F77_ISTRUE #define F77_ISTRUE(X) ( (X)&1 ) #undef F77_ISFALSE #define F77_ISFALSE(X) ( ! ( (X)&1 ) ) /* --- Common Blocks --- */ #undef F77_BLANK_COMMON #define F77_BLANK_COMMON $BLANK /* --- Declare Variables --- */ #undef DECLARE_CHARACTER #define DECLARE_CHARACTER(X,L) \ F77_CHARACTER_TYPE X[L]; const int X/**/_length = L; \ F77_CHARACTER_ARG_TYPE X/**/_descr = \ { L, DSC$K_DTYPE_T, DSC$K_CLASS_S, X }; \ F77_CHARACTER_ARG_TYPE *X/**/_arg = &X/**/_descr #undef DECLARE_CHARACTER_ARRAY #define DECLARE_CHARACTER_ARRAY(X,L,D) \ F77_CHARACTER_TYPE X[D][L]; const int X/**/_length = L; \ F77_CHARACTER_ARRAY_ARG_TYPE X/**/_descr = \ { L, DSC$K_DTYPE_T, DSC$K_CLASS_S, X }; \ F77_CHARACTER_ARRAY_ARG_TYPE *X/**/_arg = &X/**/_descr /* --- The dynamic allocation of character arguments --- */ #undef DECLARE_CHARACTER_DYN #define DECLARE_CHARACTER_DYN(X) int X/**/_length;\ F77_CHARACTER_ARG_TYPE *X/**/_arg;\ F77_CHARACTER_TYPE *X #undef DECLARE_CHARACTER_ARRAY_DYN #define DECLARE_CHARACTER_ARRAY_DYN(X) int X/**/_length;\ F77_CHARACTER_ARRAY_ARG_TYPE *X/**/_arg;\ F77_CHARACTER_TYPE *X #undef F77_CREATE_CHARACTER #define F77_CREATE_CHARACTER(X,L) X/**/_arg = cnfCref(L);\ X = X/**/_arg->dsc$a_pointer; \ X/**/_length = X/**/_arg->dsc$w_length #undef F77_CREATE_CHARACTER_ARRAY #define F77_CREATE_CHARACTER_ARRAY(X,L,N) \ {int f77dims[1];f77dims[0]=N;X/**/_arg=cnfCrefa(L,1,f77dims);X/**/_length=L;} #define F77_CREATE_CHARACTER_ARRAY_M(X,L,N,D) X/**/_arg = cnfCrefa(L,N,D);\ X = X/**/_arg->dsc$a_pointer; \ X/**/_length = X/**/_arg->dsc$w_length #undef F77_FREE_CHARACTER #define F77_FREE_CHARACTER(X) cnfFreef( X/**/_arg ) /* --- Pass arguments to a FORTRAN routine --- */ #undef CHARACTER_ARG #define CHARACTER_ARG(X) X/**/_arg #undef CHARACTER_ARRAY_ARG #define CHARACTER_ARRAY_ARG(X) X/**/_arg #undef TRAIL_ARG #define TRAIL_ARG(X) #endif /* VMS */ /* ----------------------------------------------------------------------- */ /*-------------------------- | DECstation Ultrix (cc) | | DECstation Ultrix (c89) | | DECstation OSF/1 | | Alpha OSF/1 | --------------------------*/ /* Do this complicated set of definitions as a single #if cannot be */ /* continued across multiple lines. */ #if defined(mips) && defined(ultrix) #define _dec_unix 1 #endif #if defined(__mips) && defined(__ultrix) #define _dec_unix 1 #endif #if defined(__mips__) && defined(__osf__) #define _dec_unix 1 #endif #if defined(__alpha) && defined(__osf__) #define _dec_unix 1 #endif #if _dec_unix /* The macros for Ultrix are the same as the standard ones except for ones */ /* dealing with logical values. The ANSI definitions work with the c89 */ /* compiler, and the non ANSI definitions work with the cc compiler. */ /* The same applies to DEC OSF/1, except that its cc compiler is ANSI */ /* compliant. */ /* --- Logical Values --- */ /* Redefine macros that evaluate to a C logical value, given a FORTRAN */ /* logical value. These definitions are only valid when used with the DEC */ /* FORTRAN for RISC compiler. If you are using the earlier FORTRAN for */ /* RISC compiler from MIPS, then these macros should be deleted. */ #undef F77_TRUE #define F77_TRUE -1 #undef F77_ISTRUE #define F77_ISTRUE(X) ( (X)&1 ) #undef F77_ISFALSE #define F77_ISFALSE(X) ( ! ( (X)&1 ) ) #endif /* DEC Unix */ /* *+ * Name: * cnf.h * Purpose: * Function prototypes for cnf routines * Language: * ANSI C * Type of Module: * C include file * Description: * These are the prototype definitions for the functions in the CNF * library. They are used used in mixing C and FORTRAN programs. * Copyright: * Copyright (C) 1991 Science & Engineering Research Council * Authors: * PMA: Peter Allan (Starlink, RAL) * AJC: Alan Chipperfield (Starlink, RAL) * {enter_new_authors_here} * History: * 23-MAY-1991 (PMA): * Original version. * 12-JAN-1996 (AJC): * Add cnf_cref and cnf_freef * 14-JUN-1996 (AJC): * Add cnf_crefa, imprta, exprta * crela, impla, expla * 18-JUL-1996 (AJC): * Add impch and expch * 17-MAR-1998 (AJC): * Add imprtap and exprtap * {enter_changes_here} * Bugs: * {note_any_bugs_here} *- ------------------------------------------------------------------------------ */ void cnfInitRTL( int, char** ); void *cnfCalloc( size_t, size_t ); void cnfCopyf( const char *source_f, int source_len, char *dest_f, int dest_len ); void *cnfCptr( F77_POINTER_TYPE ); char *cnfCreat( int length ); F77_CHARACTER_ARG_TYPE *cnfCref( int length ); F77_CHARACTER_ARG_TYPE *cnfCrefa( int length, int ndims, const int *dims ); char *cnfCreib( const char *source_f, int source_len ); char *cnfCreim( const char *source_f, int source_len ); F77_LOGICAL_TYPE *cnfCrela( int ndims, const int *dims ); void cnfExpch( const char *source_c, char *dest_f, int nchars ); void cnfExpla( const int *source_c, F77_LOGICAL_TYPE *dest_f, int ndims, const int *dims ); void cnfExpn( const char *source_c, int max, char *dest_f, int dest_len ); void cnfExprt( const char *source_c, char *dest_f, int dest_len ); void cnfExprta( const char *source_c, int source_len, char *dest_f, int dest_len, int ndims, const int *dims ); void cnfExprtap( char *const *source_c, char *dest_f, int dest_len, int ndims, const int *dims ); F77_POINTER_TYPE cnfFptr( void *cpointer ); void cnfFree( void * ); void cnfFreef( F77_CHARACTER_ARG_TYPE *temp ); void cnfImpb( const char *source_f, int source_len, char *dest_c ); void cnfImpbn( const char *source_f, int source_len, int max, char *dest_c ); void cnfImpch( const char *source_f, int nchars, char *dest_c ); void cnfImpla( const F77_LOGICAL_TYPE *source_f, int *dest_c, int ndims, const int *dims ); void cnfImpn( const char *source_f, int source_len, int max, char *dest_c ); void cnfImprt( const char *source_f, int source_len, char *dest_c ); void cnfImprta( const char *source_f, int source_len, char *dest_c, int dest_len, int ndims, const int *dims ); void cnfImprtap( const char *source_f, int source_len, char *const *dest_c, int dest_len, int ndims, const int *dims ); int cnfLenc( const char *source_c ); int cnfLenf( const char *source_f, int source_len ); void *cnfMalloc( size_t ); void *cnfRealloc( void *, size_t ); int cnfRegp( void * ); void cnfUregp( void * ); void cnfLock( void ); void cnfUnlock( void ); #endif #ifndef CNF_OLD_DEFINED #define CNF_OLD_DEFINED /* Define old names to be new names */ #define cnf_calloc cnfCalloc #define cnf_copyf cnfCopyf #define cnf_cptr cnfCptr #define cnf_creat cnfCreat #define cnf_cref cnfCref #define cnf_crefa cnfCrefa #define cnf_creib cnfCreib #define cnf_creim cnfCreim #define cnf_crela cnfCrela #define cnf_expch cnfExpch #define cnf_expla cnfExpla #define cnf_expn cnfExpn #define cnf_exprt cnfExprt #define cnf_exprta cnfExprta #define cnf_exprtap cnfExprtap #define cnf_fptr cnfFptr #define cnf_free cnfFree #define cnf_freef cnfFreef #define cnf_impb cnfImpb #define cnf_impbn cnfImpbn #define cnf_impch cnfImpch #define cnf_impla cnfImpla #define cnf_impn cnfImpn #define cnf_imprt cnfImprt #define cnf_imprta cnfImprta #define cnf_imprtap cnfImprtap #define cnf_lenc cnfLenc #define cnf_lenf cnfLenf #define cnf_malloc cnfMalloc #define cnf_regp cnfRegp #define cnf_uregp cnfUregp #endif /* CNF_MACROS */ ast-8.3.0/fxmlchan.c0000664000175000017500000001007013004147321011171 00000000000000/* *+ * Name: * fxmlchan.c * Purpose: * Define a FORTRAN 77 interface to the AST XmlChan class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the XmlChan class. * Routines Defined: * AST_XMLCHAN * AST_ISAXMLCHAN * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 21-OCT-2003 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "channel.h" /* Provides wrapper functions */ #include "xmlchan.h" /* C interface to the XmlChan class */ #include /* Prototypes for external functions. */ /* ================================== */ /* This is the null function defined by the FORTRAN interface in fobject.c. */ F77_SUBROUTINE(ast_null)( void ); /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_INTEGER_FUNCTION(ast_xmlchan)( void (* SOURCE)(), void (* SINK)(), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; const char *(* source)( void ); int i; void (* sink)( const char * ); astAt( "AST_XMLCHAN", NULL, 0 ); astWatchSTATUS( /* Set the source and sink function pointers to NULL if a pointer to the null routine AST_NULL has been supplied. */ source = (const char *(*)( void )) SOURCE; if ( source == (const char *(*)( void )) F77_EXTERNAL_NAME(ast_null) ) { source = NULL; } sink = (void (*)( const char * )) SINK; if ( sink == (void (*)( const char * )) F77_EXTERNAL_NAME(ast_null) ) { sink = NULL; } options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astXmlChanFor( source, astSourceWrap, sink, astSinkWrap, "%s", options ) ); astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isaxmlchan)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAXMLCHAN", NULL, 0 ); astWatchSTATUS( RESULT = astIsAXmlChan( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } ast-8.3.0/zoommap.c0000664000175000017500000021450613004147321011065 00000000000000/* *class++ * Name: * ZoomMap * Purpose: * Zoom coordinates about the origin. * Constructor Function: c astZoomMap f AST_ZOOMMAP * Description: * The ZoomMap class implements a Mapping which performs a "zoom" * transformation by multiplying all coordinate values by the same * scale factor (the inverse transformation is performed by * dividing by this scale factor). The number of coordinate values * representing each point is unchanged. * Inheritance: * The ZoomMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * ZoomMap also has the following attributes: * * - Zoom: ZoomMap scale factor * Functions: c The ZoomMap class does not define any new functions beyond those f The ZoomMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 1-FEB-1996 (RFWS): * Original version. * 18-JUL-1996 (RFWS): * Updated to support attributes and an external interface. * 10-SEP-1996 (RFWS): * Added I/O facilities. * 4-JUN-1997 (RFWS): * Over-ride the MapMerge method to provide ZoomMap * simplification facilities. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitZoomMapVtab * method. * 10-MAY-2006 (DSB): * Override astEqual. *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 ZoomMap /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "unitmap.h" /* Unit Mappings */ #include "matrixmap.h" /* Matrix Mappings */ #include "zoommap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(ZoomMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(ZoomMap,Class_Init) #define class_vtab astGLOBAL(ZoomMap,Class_Vtab) #define getattrib_buff astGLOBAL(ZoomMap,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstZoomMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstZoomMap *astZoomMapId_( int, double, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *GetAttrib( AstObject *, const char *, int * );static double GetZoom( AstZoomMap *, 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 GetIsLinear( AstMapping *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestZoom( AstZoomMap *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearZoom( AstZoomMap *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetZoom( AstZoomMap *, double, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * ZoomMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * ZoomMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the ZoomMap. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstZoomMap *this; /* Pointer to the ZoomMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the ZoomMap structure. */ this = (AstZoomMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Zoom. */ /* ----- */ if ( !strcmp( attrib, "zoom" ) ) { astClearZoom( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two ZoomMaps are equivalent. * Type: * Private function. * Synopsis: * #include "zoommap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * ZoomMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two ZoomMaps are equivalent. * Parameters: * this * Pointer to the first Object (a ZoomMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the ZoomMaps are equivalent, zero otherwise. * 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: */ AstZoomMap *that; AstZoomMap *this; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two ZoomMap structures. */ this = (AstZoomMap *) this_object; that = (AstZoomMap *) that_object; /* Check the second object is a ZoomMap. We know the first is a ZoomMap since we have arrived at this implementation of the virtual function. */ if( astIsAZoomMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two ZoomMaps differ, it may still be possible for them to be equivalent. First compare the ZoomMaps if their Invert flags are the same. In this case all the attributes of the two ZoomMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { result = ( astEQUAL( this->zoom, that->zoom ) ); /* If the Invert flags for the two ZoomMaps differ, the attributes of the two ZoomMaps must be inversely related to each other. */ } else { result = ( astEQUAL( this->zoom, 1.0/that->zoom ) ); } } } /* 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 ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * ZoomMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a ZoomMap, formatted as a character string. * Parameters: * this * Pointer to the ZoomMap. * 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 ZoomMap, 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 ZoomMap. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstZoomMap *this; /* Pointer to the ZoomMap structure */ const char *result; /* Pointer value to return */ double zoom; /* Zoom attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the ZoomMap structure. */ this = (AstZoomMap *) 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. */ /* Zoom. */ /* ----- */ if ( !strcmp( attrib, "zoom" ) ) { zoom = astGetZoom( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, zoom ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* 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 ZoomMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * ZoomMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one. * Parameters: * this * Pointer to the ZoomMap. * status * Pointer to the inherited status variable. */ return 1; } void astInitZoomMapVtab_( AstZoomMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitZoomMapVtab * Purpose: * Initialise a virtual function table for a ZoomMap. * Type: * Protected function. * Synopsis: * #include "zoommap.h" * void astInitZoomMapVtab( AstZoomMapVtab *vtab, const char *name ) * Class Membership: * ZoomMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the ZoomMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAZoomMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearZoom = ClearZoom; vtab->GetZoom = GetZoom; vtab->SetZoom = SetZoom; vtab->TestZoom = TestZoom; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->MapSplit = MapSplit; mapping->Rate = Rate; mapping->GetIsLinear = GetIsLinear; /* Declare the class dump function. There is no copy constructor or destructor. */ astSetDump( vtab, Dump, "ZoomMap", "Zoom about the origin" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a ZoomMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * ZoomMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated ZoomMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated ZoomMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated ZoomMap which is to be merged with * its neighbours. This should be a cloned copy of the ZoomMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * ZoomMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated ZoomMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *map; /* Pointer to Mapping */ AstMapping *new; /* Pointer to replacement Mapping */ const char *class; /* Pointer to Mapping class string */ double *zooms; /* Pointer to zoom factor array */ double maxzoom; /* Maximum zoom factor */ double minzoom; /* Minimum zoom factor */ double zoom; /* Zoom factor */ int coord; /* Loop counter for coordinates */ int imap1; /* Index of first ZoomMap */ int imap2; /* Index of last ZoomMap */ int imap; /* Loop counter for Mappings */ int ncoord; /* Number of input/output coordinates */ int ngone; /* Number of Mappings eliminated */ int nin; /* Total number of input coordinates */ int nzoom; /* Number of zoom factors */ int result; /* Result value to return */ int simpler; /* Mapping(s) simplified? */ int single; /* Replacement is a single ZoomMap? */ int unit; /* Replacement Mapping is a UnitMap? */ /* Initialise the returned result. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ new = NULL; ngone = 0; simpler = 0; /* In series. */ /* ---------- */ /* Handle the case where the Mappings are connected in series. */ if ( series ) { /* Obtain the effective zoom factor of the nominated Mapping (which is a ZoomMap) when its Invert attribute is set to the value given. */ zoom = astGetZoom( ( *map_list )[ where ] ); if ( ( *invert_list )[ where ] ) zoom = 1.0 / zoom; /* Search adjacent lower-numbered Mappings and identify the class to which they belong. */ imap1 = where; while ( astOK && ( ( imap1 - 1 ) >= 0 ) ) { map = ( *map_list )[ imap1 - 1 ]; class = astGetClass( map ); if ( astOK ) { /* For each ZoomMap found, obtain the effective zoom factor (taking account of the associated invert flag value), and accumulate the overall zoom factor to be used for the simplified Mapping. */ if ( !strcmp( class, "ZoomMap" ) ) { if ( ( *invert_list )[ imap1 - 1 ] ) { zoom /= astGetZoom( map ); } else { zoom *= astGetZoom( map ); } /* UnitMaps have an effective zoom factor of unity, so we include them but they so have no effect. Quit looping when the first Mapping is found which is not a ZoomMap or a UnitMap. */ } else if ( strcmp( class, "UnitMap" ) ) { break; } imap1--; } } /* Similarly search adjacent higher-numbered ZoomMaps and UnitMaps and accumulate their effective zoom factors. */ imap2 = where; while ( astOK && ( ( imap2 + 1 ) < *nmap ) ) { map = ( *map_list )[ imap2 + 1 ]; class = astGetClass( map ); if ( astOK ) { if ( !strcmp( class, "ZoomMap" ) ) { if ( ( *invert_list )[ imap2 + 1 ] ) { zoom /= astGetZoom( map ); } else { zoom *= astGetZoom( map ); } } else if ( strcmp( class, "UnitMap" ) ) { break; } imap2++; } } /* Determine how many Mappings can be eliminated by condensing those found above into a single Mapping. */ ngone = imap2 - imap1; /* Determine if the replacement Mapping can be a UnitMap. This will be the case only if the accumulated zoom factor is unity (within some tolerable error). */ unit = ( fabs( zoom - 1.0 ) <= ( 8.0 * DBL_EPSILON ) ); /* Determine if simplification is possible. This will be so if (a) Mappings can be eliminated ("ngone" is non-zero), or (b) the replacement can be a UnitMap, or (c) where there was initially only one ZoomMap, its invert flag was set (it will always be cleared in the replacement Mapping). */ simpler = ngone || unit || ( *invert_list )[ where ]; /* Do nothing more unless simplification is possible. */ if ( simpler ) { /* Obtain the number of input/output coordinates for the replacement Mapping and create the appropriate replacement. */ nin = astGetNin( ( *map_list )[ where ] ); if ( unit ) { new = (AstMapping *) astUnitMap( nin, "", status ); } else { new = (AstMapping *) astZoomMap( nin, zoom, "", status ); } } /* In parallel. */ /* ------------ */ /* Handle the case where the Mappings are connected in parallel. */ } else { /* Obtain the number of input/output coordinates for the nominated Mapping. */ nin = astGetNin( ( *map_list )[ where ] ); /* Search adjacent lower-numbered Mappings and identify the class to which they belong. */ imap1 = where; while ( astOK && ( ( imap1 - 1 ) >= 0 ) ) { map = ( *map_list )[ imap1 - 1 ]; class = astGetClass( map ); if ( astOK ) { /* Quit looping when the first Mapping is found which is not a ZoomMap or a UnitMap. */ if ( strcmp( class, "ZoomMap" ) && strcmp( class, "UnitMap" ) ) break; /* Accumulate the total number of input/output coordinates for each adjacent ZoomMap and UnitMap found. */ nin += astGetNin( map ); imap1--; } } /* Similarly search adjacent higher-numbered Mappings and accumulate the number of input/output coordinates.*/ imap2 = where; while ( astOK && ( ( imap2 + 1 ) < *nmap ) ) { map = ( *map_list )[ imap2 + 1 ]; class = astGetClass( map ); if ( astOK ) { if ( strcmp( class, "ZoomMap" ) && strcmp( class, "UnitMap" ) ) break; nin += astGetNin( map ); imap2++; } } /* Allocate memory for an array of zoom factors, one for each input/output coordinate in the replacement Mapping. */ zooms = astMalloc( sizeof( double ) * (size_t) nin ); if ( astOK ) { /* Initialise. */ nzoom = 0; minzoom = DBL_MAX; maxzoom = -DBL_MAX; /* Loop through all the ZoomMaps and UnitMaps being merged and again identify the class to which they belong. */ for ( imap = imap1; astOK && ( imap <= imap2 ); imap++ ) { map = ( *map_list )[ imap ]; class = astGetClass( map ); if ( astOK ) { /* Set a default zoom factor of unity (for UnitMaps). If the Mapping is a ZoomMap, replace this with the effective zoom factor, taking account of the associated invert flag. */ zoom = 1.0; if ( !strcmp( class, "ZoomMap" ) ) { if ( ( *invert_list )[ imap ] ) { zoom = 1.0 / astGetZoom( map ); } else { zoom = astGetZoom( map ); } } /* Replicate the zoom factor in the zoom factor array, once for each input/output coordinate associated with the current Mapping. */ ncoord = astGetNin( map ); for ( coord = 0; coord < ncoord; coord++ ) { zooms[ nzoom++ ] = zoom; } /* Store the minimum and maximum zoom factors encountered. */ if ( zoom < minzoom ) minzoom = zoom; if ( zoom > maxzoom ) maxzoom = zoom; } } /* Determine how many Mappings can be eliminated by condensing those found above into a single Mapping. */ ngone = imap2 - imap1; /* Determine whether the replacement Mapping can be a single ZoomMap. This will be so if all the effective zoom factors were the same. */ single = ( minzoom == maxzoom ); /* Determine if the replacement Mapping can be a UnitMap. This will be so if all the effective zoom factors were equal to unity. */ unit = single && ( minzoom == 1.0 ); /* Determine if simplification is possible. This will be so if (a) Mappings can be eliminated ("ngone" is non-zero), or (b) the replacement can be a UnitMap, or (c) where there was initially only one ZoomMap, its invert flag was set (it will always be cleared in the replacement Mapping). */ simpler = ngone || unit || ( *invert_list )[ where ]; /* Do nothing more unless simplification is possible. */ if ( simpler ) { /* Create a replacement UnitMap or ZoomMap if appropriate. */ if ( unit ) { new = (AstMapping *) astUnitMap( nin, "", status ); } else if ( single ) { new = (AstMapping *) astZoomMap( nin, minzoom, "", status ); /* Otherwise, replace the original ZoomMaps and UnitMaps with a diagonal MatrixMap containing the zoom factors as its diagonal elements. */ } else { new = (AstMapping *) astMatrixMap( nin, nin, 1, zooms, "", status ); } } } /* Free the array of zoom factors. */ zooms = astFree( zooms ); } /* If OK, and simplification is possible, we now have a replacement Mapping and can insert it into the Mapping list. */ if ( astOK ) { if ( simpler ) { /* Annul the pointers to all the ZoomMaps that are being replaced. */ for ( imap = imap1; imap <= imap2; imap++ ) { ( *map_list )[ imap ] = astAnnul( ( *map_list )[ imap ] ); } /* Insert the new pointer and the associated invert flag. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Loop to close the resulting gap by moving subsequent elements down in the arrays. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - ngone ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - ngone ] = ( *invert_list )[ imap ]; } /* Clear the vacated elements at the end. */ for ( imap = *nmap - ngone; imap < *nmap; imap++ ) { ( *map_list )[ imap ] = NULL; ( *invert_list )[ imap ] = 0; } /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap ) -= ngone; result = imap1; } /* If an error occurred, but a new Mapping has been created, then annul it. */ } else { if ( new ) new = astAnnul( new ); } /* If an error occurred, clear the returned result. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } 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 * ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * ZoomMap 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 ZoomMap. This is only possible if the specified inputs * correspond to some subset of the ZoomMap outputs. That is, there * must exist a subset of the ZoomMap outputs for which each output * depends only on the selected ZoomMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied ZoomMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the ZoomMap to be split (the ZoomMap 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 ZoomMap, 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 ZoomMap 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 ZoomMap. 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: */ AstZoomMap *this; /* Pointer to ZoomMap structure */ int *result; /* Pointer to returned array */ int i; /* Loop count */ int iin; /* Mapping input index */ int mnin; /* No. of Mapping inputs */ int ok; /* Are input indices OK? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the ZoomMap structure. */ this = (AstZoomMap *) this_map; /* Allocate memory for the returned array and create a ZoomMap with the required number of axes. */ result = astMalloc( sizeof( int )*(size_t) nin ); *map = (AstMapping *) astZoomMap( nin, astGetZoom( this ), "", status ); /* Set its Invert attribute to be like the supplied ZoomMap. */ astSetInvert( *map, astGetInvert( this ) ); /* Check pointers can be used safely. */ if( astOK ) { /* Store the required output axis indices. At the same time check that each axis is valid. */ mnin = astGetNin( this ); ok = 1; for( i = 0; i < nin; i++ ) { iin = in[ i ]; if( iin >= 0 && iin < mnin ) { result[ i ] = iin; } else { ok = 0; break; } } /* If the "in" array contained any invalid values, free the returned resources. */ if( !ok ) { result = astFree( result ); *map = astAnnul( *map ); } } /* 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 double Rate( AstMapping *this, 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 "zoommap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * ZoomMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ /* Local Variables: */ double result; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Result is zero if the axes differ */ if( ax1 != ax2 ) { result = 0.0; /* Otherwise, get the zoom factor. */ } else { result = astGetZoom( (AstZoomMap *) this ); /* If the ZoomMap has been inverted, return the reciprocal of the zoom factor. */ if ( astGetInvert( this ) ) { if( result != AST__BAD && result != 0.0 ) { result = 1.0/result; } else { result = AST__BAD; } } } /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * ZoomMap member function (over-rides the astSetAttrib protected * method inherited from the Mapping class). * Description: * This function assigns an attribute value for a ZoomMap, 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 ZoomMap. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstZoomMap *this; /* Pointer to the ZoomMap structure */ double zoom; /* Zoom attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the ZoomMap structure. */ this = (AstZoomMap *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Zoom. */ /* ----- */ if ( nc = 0, ( 1 == astSscanf( setting, "zoom= %lf %n", &zoom, &nc ) ) && ( nc >= len ) ) { astSetZoom( this, zoom ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * ZoomMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a ZoomMap's attributes. * Parameters: * this * Pointer to the ZoomMap. * 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: */ AstZoomMap *this; /* Pointer to the ZoomMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the ZoomMap structure. */ this = (AstZoomMap *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Zoom. */ /* ----- */ if ( !strcmp( attrib, "zoom" ) ) { result = astTestZoom( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a ZoomMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "zoommap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * ZoomMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a ZoomMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required zoom * factor. * Parameters: * this * Pointer to the ZoomMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the ZoomMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstZoomMap *map; /* Pointer to ZoomMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double scale; /* Scale factor to implement zoom */ int coord; /* Loop counter for coordinates */ int ncoord_in; /* Number of coordinates per input point */ int npoint; /* Number of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the ZoomMap. */ map = (AstZoomMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Perform coordinate arithmetic. */ /* ------------------------------ */ /* Generate the coordinate scale factor, according to the direction of mapping required. */ scale = astGetZoom( map ); if ( !forward && astOK ) scale = 1.0 / scale; /* Loop to apply the scale factor to all the coordinate values, checking for (and propagating) bad values in the process. */ if ( astOK ) { for ( coord = 0; coord < ncoord_in; coord++ ) { for ( point = 0; point < npoint; point++ ) { if ( ptr_in[ coord ][ point ] == AST__BAD ) { ptr_out[ coord ][ point ] = AST__BAD; } else { ptr_out[ coord ][ point ] = ptr_in[ coord ][ point ] * scale; } } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * Zoom * Purpose: * ZoomMap scale factor. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the ZoomMap scale factor, by which * coordinate values are multiplied (by the forward transformation) * or divided (by the inverse transformation). The default value * is unity. * c Note that if a ZoomMap is inverted (e.g. by using astInvert), f Note that if a ZoomMap is inverted (e.g. by using AST_INVERT), * then the reciprocal of this zoom factor will, in effect, be * used. * * In general, Mapping attributes cannot be changed after the Mapping * has been created (the exception to this is the Invert attribute, * which can be changed at any time). However, several of the oldest * Mapping classes - including the ZoomMap class - were introduced * into the AST library before this restriction was enforced. To * reduce the chances of breaking existing software, the attributes of * such Mappings may still be changed, but only for Mapping instances * that have exactly one active reference. In other words, an error will * be reported if an attempt is made to set or clear an attribute of a * Mapping (other than the Invert attribute) if that Mapping has been * cloned. Mappings are cloned when they are incorporated into another * object such as a CmpMap or FrameSet, or when the c astClone f AST_CLONE * function is used. * Applicability: * ZoomMap * All ZoomMaps have this attribute. * Notes: * - The Zoom attribute may not be set to zero. *att-- */ /* This ia a double value with a value of 0.0 when undefined but yielding a default of 1.0. Setting it explicitly to 0.0 is not permitted except via astClearZoom. */ astMAKE_CLEAR1(ZoomMap,Zoom,zoom,0.0) astMAKE_GET(ZoomMap,Zoom,double,1.0,( ( this->zoom == 0.0 ) ? 1.0 : this->zoom )) /* Check for an attempt to set a value of zero and report an error if necessary (leaving the Zoom value unchanged). */ astMAKE_SET1(ZoomMap,Zoom,double,zoom,( ( value != 0.0 ) ? value : ( astError( AST__ZOOMI, "astSetZoom(%s): A zoom factor of zero is not allowed.", status, astGetClass( this ) ), this->zoom ) )) astMAKE_TEST(ZoomMap,Zoom,( this->zoom != 0.0 )) /* Copy constructor. */ /* ----------------- */ /* No copy constructor is needed, as a byte-by-byte copy suffices. */ /* Destructor. */ /* ----------- */ /* No destructor is needed as no memory, etc. needs freeing. */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for ZoomMap 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 ZoomMap class to an output Channel. * Parameters: * this * Pointer to the ZoomMap 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 Variables: */ AstZoomMap *this; /* Pointer to the ZoomMap structure */ double dval; /* Double value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the ZoomMap structure. */ this = (AstZoomMap *) this_object; /* Write out values representing the instance variables for the ZoomMap 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. */ /* Zoom. */ /* ----- */ set = TestZoom( this, status ); dval = set ? GetZoom( this, status ) : astGetZoom( this ); astWriteDouble( channel, "Zoom", set, 1, dval, "Zoom factor" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAZoomMap and astCheckZoomMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(ZoomMap,Mapping) astMAKE_CHECK(ZoomMap) AstZoomMap *astZoomMap_( int ncoord, double zoom, const char *options, int *status, ...) { /* *++ * Name: c astZoomMap f AST_ZOOMMAP * Purpose: * Create a ZoomMap. * Type: * Public function. * Synopsis: c #include "zoommap.h" c AstZoomMap *astZoomMap( int ncoord, double zoom, c const char *options, ... ) f RESULT = AST_ZOOMMAP( NCOORD, ZOOM, OPTIONS, STATUS ) * Class Membership: * ZoomMap constructor. * Description: * This function creates a new ZoomMap and optionally initialises its * attributes. * * A ZoomMap is a Mapping which "zooms" a set of points about the * origin by multiplying all coordinate values by the same scale * factor (the inverse transformation is performed by dividing by * this scale factor). * Parameters: c ncoord f NCOORD = INTEGER (Given) * The number of coordinate values for each point to be * transformed (i.e. the number of dimensions of the space in * which the points will reside). The same number is applicable * to both input and output points. c zoom f ZOOM = DOUBLE PRECISION (Given) * Initial scale factor by which coordinate values should be * multiplied (by the forward transformation) or divided (by the * inverse transformation). This factor may subsequently be * changed via the ZoomMap's Zoom attribute. It may be positive * or negative, but should not be zero. 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 ZoomMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new ZoomMap. The syntax used is identical to that for the f AST_SET routine. 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 astZoomMap() f AST_ZOOMMAP = INTEGER * A pointer to the new ZoomMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstZoomMap *new; /* Pointer to new ZoomMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the ZoomMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitZoomMap( NULL, sizeof( AstZoomMap ), !class_init, &class_vtab, "ZoomMap", ncoord, zoom ); /* 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 ZoomMap'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 ZoomMap. */ return new; } AstZoomMap *astZoomMapId_( int ncoord, double zoom, const char *options, ... ) { /* * Name: * astZoomMapId_ * Purpose: * Create a ZoomMap. * Type: * Private function. * Synopsis: * #include "zoommap.h" * AstZoomMap *astZoomMapId_( int ncoord, double zoom, * const char *options, ... ) * Class Membership: * ZoomMap constructor. * Description: * This function implements the external (public) interface to the * astZoomMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astZoomMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astZoomMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astZoomMap_. * Returned Value: * The ID value associated with the new ZoomMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstZoomMap *new; /* Pointer to new ZoomMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the ZoomMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitZoomMap( NULL, sizeof( AstZoomMap ), !class_init, &class_vtab, "ZoomMap", ncoord, zoom ); /* 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 ZoomMap'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 ZoomMap. */ return astMakeId( new ); } AstZoomMap *astInitZoomMap_( void *mem, size_t size, int init, AstZoomMapVtab *vtab, const char *name, int ncoord, double zoom, int *status ) { /* *+ * Name: * astInitZoomMap * Purpose: * Initialise a ZoomMap. * Type: * Protected function. * Synopsis: * #include "zoommap.h" * AstZoomMap *astInitZoomMap( void *mem, size_t size, int init, * AstZoomMapVtab *vtab, const char *name, * int ncoord, double zoom ) * Class Membership: * ZoomMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new ZoomMap object. It allocates memory (if necessary) to accommodate * the ZoomMap plus any additional data associated with the derived class. * It then initialises a ZoomMap 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 ZoomMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the ZoomMap is to be initialised. * This must be of sufficient size to accommodate the ZoomMap data * (sizeof(ZoomMap)) 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 ZoomMap (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 ZoomMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the ZoomMap'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 ZoomMap. * 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). * ncoord * The number of coordinate values per point. * zoom * The scale factor by which coordinate values are multiplied (by the * forward mapping) or divided (by the inverse mapping). This factor may * not be zero. * Returned Value: * A pointer to the new ZoomMap. * 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: */ AstZoomMap *new; /* Pointer to new ZoomMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitZoomMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the initialisation value(s) for validity, reporting an error if necessary. Prefix the error report with the name of the function and the class of object being processed. */ if ( zoom == 0.0 ) { astError( AST__ZOOMI, "astInitZoomMap(%s): A zoom factor of zero is not " "allowed.", status, name ); } else { /* Initialise a Mapping structure (the parent class) as the first component within the ZoomMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstZoomMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, ncoord, ncoord, 1, 1 ); if ( astOK ) { /* Initialise the ZoomMap data. */ /* ---------------------------- */ /* Store the zoom factor. */ new->zoom = zoom; /* If an error occurred, clean up by deleting the new ZoomMap. */ if ( !astOK ) new = astDelete( new ); } } /* Return a pointer to the new ZoomMap. */ return new; } AstZoomMap *astLoadZoomMap_( void *mem, size_t size, AstZoomMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadZoomMap * Purpose: * Load a ZoomMap. * Type: * Protected function. * Synopsis: * #include "zoommap.h" * AstZoomMap *astLoadZoomMap( void *mem, size_t size, * AstZoomMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * ZoomMap loader. * Description: * This function is provided to load a new ZoomMap 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 * ZoomMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a ZoomMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the ZoomMap is to be * loaded. This must be of sufficient size to accommodate the * ZoomMap data (sizeof(ZoomMap)) 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 ZoomMap (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 ZoomMap 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(AstZoomMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new ZoomMap. If this is NULL, a pointer * to the (static) virtual function table for the ZoomMap 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 "ZoomMap" is used instead. * Returned Value: * A pointer to the new ZoomMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstZoomMap *new; /* Pointer to the new ZoomMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this ZoomMap. In this case the ZoomMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstZoomMap ); vtab = &class_vtab; name = "ZoomMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitZoomMapVtab( 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 ZoomMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "ZoomMap" ); /* 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. */ /* Zoom. */ /* ----- */ new->zoom = astReadDouble( channel, "zoom", 0.0 ); if ( TestZoom( new, status ) ) SetZoom( new, new->zoom, status ); /* If an error occurred, clean up by deleting the new ZoomMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new ZoomMap pointer. */ return new; } /* 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. */ ast-8.3.0/ast_err.h0000664000175000017500000003735413004147334011057 00000000000000/* * C error define file for facility AST (1521) * Generated by the MESSGEN utility */ #ifndef AST_ERROR_DEFINED #define AST_ERROR_DEFINED /* attribute getting error */ enum { AST__ATGER = 233933154 }; /* messid=300 */ /* attribute setting error */ enum { AST__ATSER = 233933162 }; /* messid=301 */ /* attribute value invalid */ enum { AST__ATTIN = 233933170 }; /* messid=302 */ /* axis index invalid */ enum { AST__AXIIN = 233933178 }; /* messid=303 */ /* bad attribute name */ enum { AST__BADAT = 233933186 }; /* messid=304 */ /* zero-sized box given */ enum { AST__BADBX = 233933194 }; /* messid=305 */ /* bad input data */ enum { AST__BADIN = 233933202 }; /* messid=306 */ /* bad number of input coordinates */ enum { AST__BADNI = 233933210 }; /* messid=307 */ /* bad number of output coordinates */ enum { AST__BADNO = 233933218 }; /* messid=308 */ /* PolyMap contains illegal power value */ enum { AST__BADPW = 233933226 }; /* messid=309 */ /* ShiftMap contains no shift information */ enum { AST__BADSM = 233933234 }; /* messid=310 */ /* WinMap contains no bounds information */ enum { AST__BADWM = 233933242 }; /* messid=311 */ /* bad break index */ enum { AST__BDBRK = 233933250 }; /* messid=312 */ /* bad field specifier */ enum { AST__BDFMT = 233933258 }; /* messid=313 */ /* invalid FITS keyword value found */ enum { AST__BDFTS = 233933266 }; /* messid=314 */ /* inappropriate Object supplied */ enum { AST__BDOBJ = 233933274 }; /* messid=315 */ /* wrong number of clipping axes */ enum { AST__CLPAX = 233933282 }; /* messid=316 */ /* range of coordinates invalid */ enum { AST__CORNG = 233933290 }; /* messid=317 */ /* too many breaks in a curve */ enum { AST__CVBRK = 233933298 }; /* messid=318 */ /* array dimensions invalid */ enum { AST__DIMIN = 233933306 }; /* messid=319 */ /* date/time error */ enum { AST__DTERR = 233933314 }; /* messid=320 */ /* invalid use of astEnd */ enum { AST__ENDIN = 233933322 }; /* messid=321 */ /* end of input Channel encountered */ enum { AST__EOCHN = 233933330 }; /* messid=322 */ /* attempt to export Object pointer from level zero */ enum { AST__EXPIN = 233933338 }; /* messid=323 */ /* corrupted FitsChan supplied */ enum { AST__FCRPT = 233933346 }; /* messid=324 */ /* error while formatting coordinate value */ enum { AST__FMTER = 233933354 }; /* messid=325 */ /* Frame index invalid */ enum { AST__FRMIN = 233933362 }; /* messid=326 */ /* FrameSet invalid */ enum { AST__FRSIN = 233933370 }; /* messid=327 */ /* cannot convert FITS data value type */ enum { AST__FTCNV = 233933378 }; /* messid=328 */ /* low level graphics error */ enum { AST__GRFER = 233933386 }; /* messid=329 */ /* invalid Handle */ enum { AST__INHAN = 233933394 }; /* messid=330 */ /* incompatible numbers of coordinates */ enum { AST__INNCO = 233933402 }; /* messid=331 */ /* internal programming error */ enum { AST__INTER = 233933410 }; /* messid=332 */ /* incompatible transformation directions */ enum { AST__INTRD = 233933418 }; /* messid=333 */ /* circular dependency between KeyMaps */ enum { AST__KYCIR = 233933426 }; /* messid=334 */ /* class loader error */ enum { AST__LDERR = 233933434 }; /* messid=335 */ /* invalid lookup table increment */ enum { AST__LUTII = 233933442 }; /* messid=336 */ /* invalid number of lookup table elements */ enum { AST__LUTIN = 233933450 }; /* messid=337 */ /* requested memory size invalid */ enum { AST__MEMIN = 233933458 }; /* messid=338 */ /* not a 2d or 3d MatrixMap */ enum { AST__MTR23 = 233933466 }; /* messid=339 */ /* null rotation axis supplied */ enum { AST__MTRAX = 233933474 }; /* messid=340 */ /* bad matrix shapes for multiplication */ enum { AST__MTRML = 233933482 }; /* messid=341 */ /* null matrix supplied */ enum { AST__MTRMT = 233933490 }; /* messid=342 */ /* number of axes invalid */ enum { AST__NAXIN = 233933498 }; /* messid=343 */ /* number of characters invalid */ enum { AST__NCHIN = 233933506 }; /* messid=344 */ /* number of coordinates invalid */ enum { AST__NCOIN = 233933514 }; /* messid=345 */ /* number of coordinates per point invalid */ enum { AST__NCPIN = 233933522 }; /* messid=346 */ /* number of array elements invalid */ enum { AST__NELIN = 233933530 }; /* messid=347 */ /* number of output coordinates too small */ enum { AST__NOCTS = 233933538 }; /* messid=348 */ /* transformation not defined */ enum { AST__NODEF = 233933546 }; /* messid=349 */ /* required FITS keywords missing */ enum { AST__NOFTS = 233933554 }; /* messid=350 */ /* unable to allocate memory */ enum { AST__NOMEM = 233933562 }; /* messid=351 */ /* number of output points too small */ enum { AST__NOPTS = 233933570 }; /* messid=352 */ /* attribute is read-only */ enum { AST__NOWRT = 233933578 }; /* messid=353 */ /* number of points invalid */ enum { AST__NPTIN = 233933586 }; /* messid=354 */ /* Object invalid */ enum { AST__OBJIN = 233933594 }; /* messid=355 */ /* invalid Plot option */ enum { AST__OPT = 233933602 }; /* messid=356 */ /* points data structure invalid */ enum { AST__PDSIN = 233933610 }; /* messid=357 */ /* no numerical labels can be produced */ enum { AST__PLFMT = 233933618 }; /* messid=358 */ /* permutation invalid */ enum { AST__PRMIN = 233933626 }; /* messid=359 */ /* pointer invalid */ enum { AST__PTRIN = 233933634 }; /* messid=360 */ /* range of points invalid */ enum { AST__PTRNG = 233933642 }; /* messid=361 */ /* read error */ enum { AST__RDERR = 233933650 }; /* messid=362 */ /* invalid or corrupted Region structure supplied */ enum { AST__REGIN = 233933658 }; /* messid=363 */ /* invalid attempt to remove last Frame */ enum { AST__REMIN = 233933666 }; /* messid=364 */ /* sky coordinate system invalid */ enum { AST__SCSIN = 233933674 }; /* messid=365 */ /* axis selection invalid */ enum { AST__SELIN = 233933682 }; /* messid=366 */ /* bad SLALIB transformation type */ enum { AST__SLAIN = 233933690 }; /* messid=367 */ /* coordinate transformation not defined */ enum { AST__TRNND = 233933698 }; /* messid=368 */ /* unmatched quotes */ enum { AST__UNMQT = 233933706 }; /* messid=369 */ /* valid area too small */ enum { AST__VSMAL = 233933714 }; /* messid=370 */ /* non-existent longitude or latitude axis */ enum { AST__WCSAX = 233933722 }; /* messid=371 */ /* too few mapping coordinates */ enum { AST__WCSNC = 233933730 }; /* messid=372 */ /* invalid projection parameters */ enum { AST__WCSPA = 233933738 }; /* messid=373 */ /* unknown projection type */ enum { AST__WCSTY = 233933746 }; /* messid=374 */ /* too many Objects in use at once */ enum { AST__XSOBJ = 233933754 }; /* messid=375 */ /* zoom factor invalid */ enum { AST__ZOOMI = 233933762 }; /* messid=376 */ /* bad coordinate index */ enum { AST__BADCI = 233933770 }; /* messid=377 */ /* FrameSet integrity lost */ enum { AST__ILOST = 233933778 }; /* messid=378 */ /* error in IntraMap transformation function */ enum { AST__ITFER = 233933786 }; /* messid=379 */ /* IntraMap transformation function name invalid */ enum { AST__ITFNI = 233933794 }; /* messid=380 */ /* Mapping bounding box not found */ enum { AST__MBBNF = 233933802 }; /* messid=381 */ /* multiple registration of IntraMap transformation function */ enum { AST__MRITF = 233933810 }; /* messid=382 */ /* Object class unknown */ enum { AST__OCLUK = 233933818 }; /* messid=383 */ /* error while unformatting a coordinate value */ enum { AST__UNFER = 233933826 }; /* messid=384 */ /* unregistered IntraMap transformation function */ enum { AST__URITF = 233933834 }; /* messid=385 */ /* grid bounds invalid */ enum { AST__GBDIN = 233933842 }; /* messid=386 */ /* number of grid dimensions invalid */ enum { AST__NGDIN = 233933850 }; /* messid=387 */ /* positional accuracy tolerance invalid */ enum { AST__PATIN = 233933858 }; /* messid=388 */ /* sub-pixel interpolation scheme invalid */ enum { AST__SISIN = 233933866 }; /* messid=389 */ /* scale size in pixels invalid */ enum { AST__SSPIN = 233933874 }; /* messid=390 */ /* error in user-supplied sub-pixel interpolation function */ enum { AST__UINER = 233933882 }; /* messid=391 */ /* error in user-supplied 1-d sub-pixel interpolation kernel */ enum { AST__UK1ER = 233933890 }; /* messid=392 */ /* invalid comma in expression */ enum { AST__COMIN = 233933898 }; /* messid=393 */ /* invalid constant in expression */ enum { AST__CONIN = 233933906 }; /* messid=394 */ /* duplicate variable name */ enum { AST__DUVAR = 233933914 }; /* messid=395 */ /* invalid number of transformation functions */ enum { AST__INNTF = 233933922 }; /* messid=396 */ /* missing or invalid operand in expression */ enum { AST__MIOPA = 233933930 }; /* messid=397 */ /* missing or invalid operator in expression */ enum { AST__MIOPR = 233933938 }; /* messid=398 */ /* missing variable name */ enum { AST__MISVN = 233933946 }; /* messid=399 */ /* missing left parenthesis in expression */ enum { AST__MLPAR = 233933954 }; /* messid=400 */ /* missing right parenthesis in expression */ enum { AST__MRPAR = 233933962 }; /* messid=401 */ /* missing right hand side in function */ enum { AST__NORHS = 233933970 }; /* messid=402 */ /* undefined variable or function in expression */ enum { AST__UDVOF = 233933978 }; /* messid=403 */ /* variable name invalid */ enum { AST__VARIN = 233933986 }; /* messid=404 */ /* wrong number of function arguments in expression */ enum { AST__WRNFA = 233933994 }; /* messid=405 */ /* invalid units specification */ enum { AST__BADUN = 233934002 }; /* messid=406 */ /* no rest frequency is defined */ enum { AST__NORSF = 233934010 }; /* messid=407 */ /* no standard of rest is defined */ enum { AST__NOSOR = 233934018 }; /* messid=408 */ /* invalid SpecMap */ enum { AST__SPCIN = 233934026 }; /* messid=409 */ /* invalid XML name or prefix */ enum { AST__XMLNM = 233934034 }; /* messid=410 */ /* invalid XML comment text */ enum { AST__XMLCM = 233934042 }; /* messid=411 */ /* invalid XML processing instruction target text */ enum { AST__XMLPT = 233934050 }; /* messid=412 */ /* invalid XML content item index */ enum { AST__XMLIT = 233934058 }; /* messid=413 */ /* supplied XML document is not well formed */ enum { AST__XMLWF = 233934066 }; /* messid=414 */ /* Range of log axis scale includes zero */ enum { AST__ZERAX = 233934074 }; /* messid=415 */ /* Invalid parameters for offset sky coordinate system */ enum { AST__BADOC = 233934082 }; /* messid=416 */ /* error getting a named value from a KeyMap */ enum { AST__MPGER = 233934090 }; /* messid=417 */ /* invalid integer index supplied for a KeyMap entry */ enum { AST__MPIND = 233934098 }; /* messid=418 */ /* region cannot be re-centred */ enum { AST__REGCN = 233934106 }; /* messid=419 */ /* attribute has no usable value */ enum { AST__NOVAL = 233934114 }; /* messid=420 */ /* incompatible time scales */ enum { AST__INCTS = 233934122 }; /* messid=421 */ /* invalid TimeMap */ enum { AST__TIMIN = 233934130 }; /* messid=422 */ /* cannot use supplied AstroCoords info */ enum { AST__STCKEY = 233934138 }; /* messid=423 */ /* invalid AstroCoords index */ enum { AST__STCIND = 233934146 }; /* messid=424 */ /* cannot conserve flux whilst resampling an array of data */ enum { AST__CNFLX = 233934154 }; /* messid=425 */ /* Unknown AST tuning parameter name supplied */ enum { AST__TUNAM = 233934162 }; /* messid=426 */ /* Bad value supplied for a public function parameter */ enum { AST__BDPAR = 233934170 }; /* messid=427 */ /* Supplied FrameSet does not contain any independent axes */ enum { AST__3DFSET = 233934178 }; /* messid=428 */ /* Attempt to delete original Plot3D base Frame */ enum { AST__PXFRRM = 233934186 }; /* messid=429 */ /* Illegal syntax for string substitution template */ enum { AST__BADSUB = 233934194 }; /* messid=430 */ /* Incompatible flags for re-sampling or re-binning */ enum { AST__BADFLG = 233934202 }; /* messid=431 */ /* Error locking or unlocking an AST Object */ enum { AST__LCKERR = 233934210 }; /* messid=432 */ /* FITS keyword had undefined value */ enum { AST__FUNDEF = 233934218 }; /* messid=433 */ /* invalid integer index supplied for a KeyMap vector element */ enum { AST__MPVIN = 233934226 }; /* messid=434 */ /* operation specifier invalid */ enum { AST__OPRIN = 233934234 }; /* messid=435 */ /* no inside point found */ enum { AST__NONIN = 233934242 }; /* messid=436 */ /* requested key not found in KeyMap */ enum { AST__MPKER = 233934250 }; /* messid=437 */ /* error putting a named value into a KeyMap */ enum { AST__MPPER = 233934258 }; /* messid=438 */ /* Attempt made to add an entry to a locked KeyMap */ enum { AST__BADKEY = 233934266 }; /* messid=439 */ /* Bad data type */ enum { AST__BADTYP = 233934274 }; /* messid=440 */ /* Column already exists with different properties */ enum { AST__OLDCOL = 233934282 }; /* messid=441 */ /* Bad null value for a FITS table column */ enum { AST__BADNULL = 233934290 }; /* messid=442 */ /* Key string is too long */ enum { AST__BIGKEY = 233934298 }; /* messid=443 */ /* No such column exists in the table */ enum { AST__BADCOL = 233934306 }; /* messid=444 */ /* Table is too large */ enum { AST__BIGTAB = 233934314 }; /* messid=445 */ /* Invalid array size */ enum { AST__BADSIZ = 233934322 }; /* messid=446 */ /* Error reading WCS from FITS binary table */ enum { AST__BADTAB = 233934330 }; /* messid=447 */ /* Cannot access FITS binary table */ enum { AST__NOTAB = 233934338 }; /* messid=448 */ /* Error in levmar Levenberg-Marquardt code */ enum { AST__LEVMAR = 233934346 }; /* messid=449 */ /* Fit failed */ enum { AST__NOFIT = 233934354 }; /* messid=450 */ /* A transformation generated one or more NaN values */ enum { AST__ISNAN = 233934362 }; /* messid=451 */ /* write error */ enum { AST__WRERR = 233934370 }; /* messid=452 */ /* Bad variant Mapping name */ enum { AST__BDVNM = 233934378 }; /* messid=453 */ /* Attempt to add a variant Mapping to a mirror Frame */ enum { AST__MIRRO = 233934386 }; /* messid=454 */ /* Error in cminpack Levenberg-Marquardt code */ enum { AST__MNPCK = 233934394 }; /* messid=455 */ /* Supplied array has too many pixels */ enum { AST__EXSPIX = 233934402 }; /* messid=456 */ /* No mapping found between coordinate systems */ enum { AST__NOCNV = 233934410 }; /* messid=457 */ /* Attempt to change an immutable attribute */ enum { AST__IMMUT = 233934418 }; /* messid=458 */ #endif /* AST_ERROR_DEFINED */ ast-8.3.0/interval.c0000664000175000017500000051604313004147321011230 00000000000000/* *class++ * Name: * Interval * Purpose: * A region representing an interval on one or more axes of a Frame. * Constructor Function: c astInterval f AST_INTERVAL * Description: * The Interval class implements a Region which represents upper * and/or lower limits on one or more axes of a Frame. For a point to * be within the region represented by the Interval, the point must * satisfy all the restrictions placed on all the axes. The point is * outside the region if it fails to satisfy any one of the restrictions. * Each axis may have either an upper limit, a lower limit, both or * neither. If both limits are supplied but are in reverse order (so * that the lower limit is greater than the upper limit), then the * interval is an excluded interval, rather than an included interval. * * Note, The Interval class makes no allowances for cyclic nature of * some coordinate systems (such as SkyFrame coordinates). A Box * should usually be used in these cases since this requires the user * to think about suitable upper and lower limits, * Inheritance: * The Interval class inherits from the Region class. * Attributes: * The Interval class does not define any new attributes beyond * those which are applicable to all Regions. * Functions: c The Interval class does not define any new functions beyond those f The Interval class does not define any new routines beyond those * which are applicable to all Regions. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 29-OCT-2004 (DSB): * Original version. * 19-APR-2006 (DSB): * Negate the cached equivalent Box if the Interval has been negated. * 28-MAY-2007 (DSB): * Re-implemented BndBaseMesh. * 20-JAN-2009 (DSB): * Over-ride astRegBasePick. * 26-JAN-2009 (DSB): * Over-ride astMapMerge. * 4-NOV42-2013 (DSB): * - Change RegCentre so that it does not report an error for an unbounded * Interval if the centre is merely being inquired rather than set. This is * the documented behaviour of the astRegCentre method. * - Modify RegPins so that it can handle uncertainty regions that straddle * a discontinuity. Previously, such uncertainty Regions could have a huge * bounding box resulting in matching region being far too big. *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 Interval /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Abstract coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "box.h" /* Box Regions */ #include "nullregion.h" /* Null Regions */ #include "wcsmap.h" /* Definitons of AST__DPI etc */ #include "interval.h" /* Interface definition for this class */ #include "ellipse.h" /* Interface definition for ellipse class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mappings */ #include "cmpmap.h" /* Compound Mappings */ #include "cmpframe.h" /* Compound Frames */ #include "prism.h" /* Prism regions */ #include "pointlist.h" /* Lists of points in a Frame */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); static int (* parent_overlap)( AstRegion *, AstRegion *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (* parent_setunc)( AstRegion *, AstRegion *, int * ); static void (* parent_resetcache)( AstRegion *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Interval) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Interval,Class_Init) #define class_vtab astGLOBAL(Interval,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstIntervalVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstInterval *astIntervalId_( void *, const double[], const double[], void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstBox *Cache( AstInterval *, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *BndBaseMesh( AstRegion *, double *, double *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *RegBasePick( AstRegion *this, int, const int *, int * ); static AstRegion *GetDefUnc( AstRegion *, int * ); static AstRegion *MergeInterval( AstInterval *, AstRegion *, int, int * ); static double *RegCentre( AstRegion *this, double *, double **, int, int, int * ); static int *OneToOne( AstMapping *, int * ); static int GetBounded( AstRegion *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int Overlap( AstRegion *, AstRegion *, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static int RegTrace( AstRegion *, int, double *, double **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void IntervalPoints( AstInterval *, double *, double *, int *); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void ResetCache( AstRegion *this, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); static void SetUnc( AstRegion *, AstRegion *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static AstPointSet *BndBaseMesh( AstRegion *this, double *lbnd, double *ubnd, int *status ){ /* * Name: * BndBaseMesh * Purpose: * Return a PointSet containing points spread around part of the boundary * of a Region. * Type: * Private function. * Synopsis: * #include "interval.h" * AstPointSet *BndBaseMesh( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Interval method (over-rides the astBndBaseMesh method inherited from * the Region class). * Description: * This function returns a PointSet containing a set of points on the * boundary of the intersection between the supplied Region and the * supplied box. The points refer to the base Frame of the * encapsulated FrameSet. If the boundary of the supplied Region does * not intersect the supplied box, then a PointSet containing a single * bad point is returned. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array holding the lower limits of the axis values * within the required box. * ubnd * Pointer to an array holding the upper limits of the axis values * within the required box. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. The axis values in this PointSet will have * associated accuracies derived from the uncertainties which were * supplied when the Region was created. * * If the Region does not intersect the supplied box, the returned * PointSet will contain a single point with a value of AST__BAD on * every axis. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstBox *box; AstFrame *bfrm; AstInterval *this_interval; AstMapping *map; AstPointSet *result; double *lbndb; double *ubndb; double **ptr; int closed; int i; int nbase; /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Store a pointer to the interval. */ this_interval = (AstInterval *) this; /* If the Interval is effectively a Box, invoke the astBndBaseMesh function on the equivalent Box. A pointer to the equivalent Box will be stored in the Interval structure. */ box = Cache( (AstInterval *) this, status ); if( box ) { result = astBndBaseMesh( box, lbnd, ubnd ); /* If the Interval is not equivalent to a Box (i.e. if one or more bounds are missing)... */ } else { /* Find the base frame box that just encloses the supplied current Frame box. */ map = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); nbase = astGetNout( map ); lbndb = astMalloc( sizeof(double)*nbase ); ubndb = astMalloc( sizeof(double)*nbase ); if( astOK ) { for( i = 0; i < nbase; i++ ) { astMapBox( map, lbnd, ubnd, 1, i, lbndb + i, ubndb + i, NULL, NULL ); } /* Create a Box that is like this Interval except that missing bounds are inherited from the supplied limits. Check that the resulting box is closed. */ closed = 1; for( i = 0; i < nbase; i++ ) { if( this_interval->ubnd[ i ] != DBL_MAX ) ubndb[ i ] = this_interval->ubnd[ i ]; if( this_interval->lbnd[ i ] != -DBL_MAX ) lbndb[ i ] = this_interval->lbnd[ i ]; if( lbndb[ i ] > ubndb[ i ] ) closed = 0; } /* Cannot create the required mesh if the box is not closed. */ if( closed ) { /* Create the Box. */ bfrm = astGetFrame( this->frameset, AST__BASE ); box = astBox( bfrm, 1, lbndb, ubndb, NULL, "", status ); /* Create the required mesh. */ result = astRegBaseMesh( box ); /* Free resources */ bfrm = astAnnul( bfrm ); box = astAnnul( box ); /* If the boundary of the supplied Region does not intersect the box, return a PointSet containing a single bad position. */ } else { result = astPointSet( 1, nbase, "", status ); ptr = astGetPoints( result ); if( astOK ) { for( i = 0; i < nbase; i++ ) ptr[ i ][ 0 ] = AST__BAD; } } } /* Free resources. */ map = astAnnul( map ); lbndb = astFree( lbndb ); ubndb = astFree( ubndb ); } /* Return NULL if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the required pointer. */ return result; } static AstBox *Cache( AstInterval *this, int *status ){ /* * Name: * Cache * Purpose: * Calculate intermediate values and cache them in the Interval structure. * Type: * Private function. * Synopsis: * #include "interval.h" * AstBox *Cache( AstInterval *this, int *status ) * Class Membership: * Interval member function * Description: * This function uses the PointSet stored in the parent Region to calculate * some intermediate values which are useful in other methods. These * values are stored within the Interval structure. * Parameters: * this * Pointer to the Interval. * status * Pointer to the inherited status variable. * Returned Value: * If the Interval is equivalent to a Box, then a pointer to the * equivalent Box is returned. This is a copy of the pointer stored in * the Interval structure and should not be annulled. */ /* Local Variables: */ AstBox *bbox; /* Equivalent base Box */ AstFrame *bfrm; /* Interval base Frame */ AstFrame *cfrm; /* Interval current Frame */ AstRegion *map; /* Interval base->current Mapping */ AstRegion *reg; /* Pointer to this Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr; /* Pointer to data holding all axis limits */ double *lbnd; /* Pointer to array of lower axis limits */ double *ubnd; /* Pointer to array of upper axis limits */ int i; /* Axis index */ int isBox; /* Is this Interval equivalent to a Box? */ int nc; /* Number of base Frame axes */ int neg; /* Is the equivalent Box negated? */ /* Check the global error status. Also return if the cached information is up to date (i.e. not stale). */ if( !this->stale || !astOK ) return this->box; /* Get a pointer to the Region structure */ reg = (AstRegion *) this; /* The Interval structure contains a pointer to an equivalent Box structure. This Box structure is created below if the Interval is equivalent to a Box. Annul any previous box. */ if( this->box ) this->box = astAnnul( this->box ); /* Get the number of axes in the base Frame of the FrameSet encapsulated by the parent Region structure. */ nc = astGetNin( reg->frameset ); /* Get a pointer to the array holding the axis limits held in the PointSet encapsulated in the parent Region structure. */ ptr = astGetPoints( reg->points ); /* Allocate memory to hold the limits organised per point rather than per axis. */ lbnd = astMalloc( sizeof( double )*(size_t)nc ); ubnd = astMalloc( sizeof( double )*(size_t)nc ); /* Check these pointers can be used safely. */ if( ubnd ) { /* See if the Interval is effectively a (possibly negated) Box. Assume it is to begin with. */ isBox = 1; /* Initialisation to prevent compiler warnings. */ neg = 0; /* Check the limits on every axis. */ for( i = 0; i < nc; i++ ) { /* Copy the axis limits into the allocated arrays (these are needed by the Box constructor later on). */ lbnd[ i ] = ptr[ i ][ 0 ]; ubnd[ i ] = ptr[ i ][ 1 ]; /* The Interval is not a Box if any axis limit is missing. In this case use -DBL_MAX or +DBL_MAX as the limit to be stored in the Interval structure. */ if( lbnd[ i ] == AST__BAD ) lbnd[ i ] = -DBL_MAX; if( fabs( lbnd[ i ] ) == DBL_MAX ) isBox = 0; if( ubnd[ i ] == AST__BAD ) ubnd[ i ] = DBL_MAX; if( fabs( ubnd[ i ] ) == DBL_MAX ) isBox = 0; /* If this is the first axis, note if the axis interval is included or excluded. This is determined by whether the "lower limit" is greater than or less than the "upper limit". If the axis interval is excluded (lower limit greater than upper limit), then any equivalent Box will be a negated Box (i.e. will represent the outside of a box rather than the inside). */ if( i == 0 ){ neg = ( lbnd[ i ] > ubnd[ i ] ); /* The Interval is not a Box if the limits for this axis are not the same way round as those of the first axis. */ } else { if( neg ) { if( lbnd[ i ] < ubnd[ i ] ) isBox = 0; } else { if( lbnd[ i ] > ubnd[ i ] ) isBox = 0; } } } /* If the Interval is effectively an unnegated Box, create the equivalent Box, and store a pointer to it in the Interval structure. */ if( isBox && !neg ) { bfrm = astGetFrame( reg->frameset, AST__BASE ); cfrm = astGetFrame( reg->frameset, AST__CURRENT ); map = astGetMapping( reg->frameset, AST__BASE, AST__CURRENT ); unc = astTestUnc( reg ) ? astGetUncFrm( reg, AST__BASE ) : NULL; bbox = astBox( bfrm, 1, lbnd, ubnd, unc, "", status ); if( astIsAUnitMap( map ) ){ this->box = astClone( bbox ); } else { this->box = astMapRegion( bbox, map, cfrm ); } if( unc ) unc = astAnnul( unc ); cfrm = astAnnul( cfrm ); bfrm = astAnnul( bfrm ); map = astAnnul( map ); bbox = astAnnul( bbox ); /* If the supplied Interval has been negated, negate the equivalent Box. */ if( astGetNegated( this ) ) astNegate( this->box ); /* If the supplied Interval is closed, ensure the equivalent Box is closed. */ astSetClosed( this->box, astGetClosed( this ) ); } /* Store the axis limits in the Interval structure. */ if( this->lbnd ) astFree( this->lbnd ); if( this->ubnd ) astFree( this->ubnd ); this->lbnd = lbnd; this->ubnd = ubnd; } /* Indicate the cached information is no longer stale, and return a pointer to any equivalent Box. */ this->stale = 0; return this->box; } static int GetBounded( AstRegion *this, int *status ) { /* * Name: * GetBounded * Purpose: * Is the Region bounded? * Type: * Private function. * Synopsis: * #include "interval.h" * int GetBounded( AstRegion *this, int *status ) * Class Membership: * Interval method (over-rides the astGetBounded method inherited from * the Region class). * Description: * This function returns a flag indicating if the Region is bounded. * The implementation provided by the base Region class is suitable * for Region sub-classes representing the inside of a single closed * curve (e.g. Circle, Interval, Box, etc). Other sub-classes (such as * CmpRegion, PointList, etc ) may need to provide their own * implementations. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Region is bounded. Zero otherwise. */ /* Local Variables: */ int result; /* Returned result */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* The unnegated Interval is bounded only if there is an equivalent Box structure stored in the Interval structure. */ if( Cache( (AstInterval *) this, status ) ) result = 1; /* Return the required pointer. */ return result; } static AstRegion *GetDefUnc( AstRegion *this_region, int *status ) { /* * Name: * GetDefUnc * Purpose: * Obtain a pointer to the default uncertainty Region for a given Region. * Type: * Private function. * Synopsis: * #include "interval.h" * AstRegion *GetDefUnc( AstRegion *this, int *status ) * Class Membership: * Interval member function (over-rides the astGetDefUnc protected * method inherited from the Region class). * Description: * This function returns a pointer to a Region which represents the * default uncertainty associated with a position on the boundary of the * given Region. The returned Region refers to the base Frame within the * FrameSet encapsulated by the supplied Region. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the Region. This should be annulled (using astAnnul) * when no longer needed. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstBox *box; /* Pointer to equivalent Box */ AstFrame *bfrm; /* Base Frame of supplied Region */ AstInterval *this; /* Pointer to Interval structure */ AstRegion *result; /* Returned pointer */ double *lbnd; /* Ptr. to array holding axis lower bounds */ double *ubnd; /* Ptr. to array holding axis upper bounds */ double c; /* Central axis value */ double hw; /* Half width of uncertainty interval */ int i; /* Axis index */ int nax; /* Number of base Frame axes */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Interval structure. */ this = (AstInterval *) this_region; /* If this Interval is equivalent to a Box, get the default uncertainty for the equivalent Box and return it. */ box = Cache( this, status ); if( box ) { result = astGetDefUnc( box ); /* Otherwise, we use a box covering 1.0E-6 of each axis interval, centred on the origin. */ } else { /* Get a pointer to the base Frame. */ bfrm = astGetFrame( this_region->frameset, AST__BASE ); /* Get the number of base Frame axes. */ nax = astGetNaxes( bfrm ); /* Allocate arrays to hold the bounds of the uncertainty Box. */ lbnd = astMalloc( sizeof( double)*(size_t) nax ); ubnd = astMalloc( sizeof( double)*(size_t) nax ); if( astOK ) { /* Ensure cached information (e.g.bounds) is up to date. */ Cache( this, status ); /* Do each axis in turn */ for( i = 0; i < nax; i++ ) { /* If this axis has both limits, use 1.0E-6 of the difference between the limits. */ if( this->lbnd[ i ] != -DBL_MAX && this->ubnd[ i ] != DBL_MAX ) { hw = fabs( 0.5E-6*( this->ubnd[ i ] - this->lbnd[ i ] ) ); c = 0.5*( this->ubnd[ i ] + this->lbnd[ i ] ); if( hw == 0.0 ) hw = c*0.5E-6; ubnd[ i ] = c + hw; lbnd[ i ] = c - hw; /* Otherwise use zero. */ } else { ubnd[ i ] = 0.0; lbnd[ i ] = 0.0; } } /* Create the Box. */ result = (AstRegion *) astBox( bfrm, 1, lbnd, ubnd, NULL, "", status ); } /* Free resources. */ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); bfrm = astAnnul( bfrm ); } /* Return NULL if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the required pointer. */ return result; } void astInitIntervalVtab_( AstIntervalVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitIntervalVtab * Purpose: * Initialise a virtual function table for a Interval. * Type: * Protected function. * Synopsis: * #include "interval.h" * void astInitIntervalVtab( AstIntervalVtab *vtab, const char *name ) * Class Membership: * Interval vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Interval class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAInterval) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->IntervalPoints = IntervalPoints; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_overlap = region->Overlap; region->Overlap = Overlap; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_resetcache = region->ResetCache; region->ResetCache = ResetCache; parent_setunc = region->SetUnc; region->SetUnc = SetUnc; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->MapMerge = MapMerge; region->RegCentre = RegCentre; region->GetBounded = GetBounded; region->GetDefUnc = GetDefUnc; region->RegPins = RegPins; region->RegTrace = RegTrace; region->RegBaseMesh = RegBaseMesh; region->BndBaseMesh = BndBaseMesh; region->RegBaseBox = RegBaseBox; region->RegBasePick = RegBasePick; /* Declare the copy constructor, destructor and class dump functions. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Interval", "Axis intervals" ); /* 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) ); } } void IntervalPoints( AstInterval *this, double *lbnd, double *ubnd, int *status) { /* *+ * Name: * astIntervalPoints * Purpose: * Return the defining points of a Interval. * Type: * Protected function. * Synopsis: * #include "box.h" * astIntervalPoints( AstInterval *this, double *lbnd, double *ubnd ) * Class Membership: * Region virtual function. * Description: * This function returns the axis values at the points defining the * supplied Interval. * Parameters: * this * Pointer to the Interval. * lbnd * A pointer to an array in which to return the "lbnd" values * supplied when the Interval was constructed. These are in the * base Frame of the encapsilated FrameSet. * ubnd * A pointer to an array in which to return the "ubnd" values * supplied when the Interval was constructed. These are in the * base Frame of the encapsilated FrameSet. * Notes: * - It is assumed that the length of the supplied arrays is at least * equal to the number of axes in the base frame of the encapsulated * FrameSet. *- */ /* Local Variables: */ AstPointSet *pset; double **ptr; int nc; int i; /* Check the inherited status. */ if( !astOK ) return; /* Get a pointer to the PointSet holding the points defining the Interval. */ pset = ((AstRegion *) this)->points; /* Get a pointer to the PointSet's data arrays. */ ptr = astGetPoints( pset ); /* See how many axes each point in the PointSet has. */ nc = astGetNcoord( pset ); /* Copy the axis values from the PointSet into the supplied arrays. */ for( i = 0; i < nc; i++ ) { lbnd[ i ] = ptr[ i ] [ 0 ]; ubnd[ i ] = ptr[ i ] [ 1 ]; } } #if defined(THREAD_SAFE) static int ManageLock( AstObject *this_object, int mode, int extra, AstObject **fail, int *status ) { /* * Name: * ManageLock * Purpose: * Manage the thread lock on an Object. * Type: * Private function. * Synopsis: * #include "object.h" * AstObject *ManageLock( AstObject *this, int mode, int extra, * AstObject **fail, int *status ) * Class Membership: * Interval 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: */ AstInterval *this; /* Pointer to Interval structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Interval structure. */ this = (AstInterval *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->box, mode, extra, fail ); return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a Interval. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * Interval method (over-rides the protected astMapMerge method * inherited from the Region class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated Interval in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated Interval with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated Interval which is to be merged with * its neighbours. This should be a cloned copy of the Interval * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * Interval it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated Interval resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstInterval *oldint; /* Pointer to supplied Interval */ AstMapping *map; /* Pointer to adjacent Mapping */ AstMapping *new; /* Simplified or merged Region */ int i1; /* Index of first Mapping merged */ int i; /* Loop counter */ int result; /* Result value to return */ /* Initialise. */ result = -1; i1 = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Interval. */ oldint = (AstInterval *) this; /* First of all, see if the Interval can be replaced by a simpler Region, without reference to the neighbouring Regions in the list. */ /* =====================================================================*/ /* Try to simplify the Interval. If the pointer value has changed, we assume some simplification took place. */ new = astSimplify( oldint ); if( new != (AstMapping *) oldint ) { /* Annul the Interval pointer in the list and replace it with the new Region pointer, and indicate that the forward transformation of the returned Region should be used (not really needed but keeps things clean). */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the Interval itself could not be simplified, see if it can be merged with the Regions on either side of it in the list. We can only merge in parallel. */ /* =====================================================================*/ } else if( ! series ){ new = astAnnul( new ); /* Attempt to merge the Interval with its lower neighbour (if any). */ if( where > 0 ) { i1 = where - 1; map = ( *map_list )[ where - 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeInterval( oldint, (AstRegion *) map, 0, status ); } } /* If this did not produced a merged Region, attempt to merge the Interval with its upper neighbour (if any). */ if( !new && where < *nmap - 1 ) { i1 = where; map = ( *map_list )[ where + 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeInterval( oldint, (AstRegion *) map, 1, status ); } } /* If succesfull... */ if( new ){ /* Annul the first of the two Mappings, and replace it with the merged Region. Also clear the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = new; ( *invert_list )[ i1 ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i1 + 1 ] ); for ( i = i1 + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } } else { new = astAnnul( new ); } /* Return the result. */ return result; } static AstRegion *MergeInterval( AstInterval *this, AstRegion *reg, int intfirst, int *status ) { /* * Name: * MergeInterval * Purpose: * Attempt to merge a Interval with another Region to form a Region of * higher dimensionality. * Type: * Private function. * Synopsis: * #include "box.h" * AstRegion *MergeInterval( AstInterval *this, AstRegion *reg, * int intfirst, int *status ) * Class Membership: * Interval member function. * Description: * This function attempts to combine the supplied Regions together * into a Region of higher dimensionality. * Parameters: * this * Pointer to a Interval. * reg * Pointer to another Region. * intfirst * If non-zero, then the Interval axes are put first in the new Region. * Otherwise, the other Region's axes are put first. * status * Pointer to the inherited status value. * Returned Value: * A pointer to a new region, or NULL if the supplied Regions could * not be merged. */ /* Local Variables: */ AstFrame *bfrm; /* Pointer to base Frame for "result" */ AstFrame *cfrm; /* Pointer to current Frame for "result" */ AstFrame *frm_reg; /* Pointer to Frame from "reg" */ AstFrame *frm_this; /* Pointer to Frame from "this" */ AstMapping *bcmap; /* Base->current Mapping for "result" */ AstMapping *map_reg; /* Base->current Mapping from "reg" */ AstMapping *map_this; /* Base->current Mapping from "this" */ AstMapping *sbunc; /* Simplified uncertainty */ AstPointSet *pset_new; /* PointSet holding PointList axis values for new */ AstPointSet *pset_reg; /* PointSet holding PointList axis values for reg */ AstRegion *bunc; /* Base Frame uncertainty Region */ AstRegion *new; /* Pointer to new Interval in base Frame */ AstRegion *result; /* Pointer to returned Interval in current Frame */ AstRegion *unc_reg; /* Current Frame uncertainty Region from "reg" */ AstRegion *unc_this; /* Current Frame uncertainty Region from "this" */ double **ptr_new; /* Pointers to arrays holding new axis values */ double **ptr_reg; /* Pointers to arrays holding reg axis values */ double *centre; /* Array to hold Interval centre axis values */ double *corner; /* Array to hold Interval corner axis values */ double *lbnd; /* Array to hold lower axis bounds */ double *lbnd_unc; /* Array to hold uncertainty lower bounds */ double *p; /* Pointer to next input value */ double *q; /* Pointer to next output value */ double *ubnd; /* Array to hold upper axis bounds */ double *ubnd_unc; /* Array to hold uncertainty upper bounds */ double fac_reg; /* Ratio of used to default MeshSize for "reg" */ double fac_this; /* Ratio of used to default MeshSize for "this" */ double temp; /* Temporary storage */ int i; /* Loop count */ int j; /* Loop count */ int msz_reg; /* Original MeshSize for "reg" */ int msz_reg_set; /* Was MeshSize originally set for "reg"? */ int msz_this; /* Original MeshSize for "this" */ int msz_this_set; /* Was MeshSize originally set for "this"? */ int nax; /* Number of axes in "result" */ int nax_reg; /* Number of axes in "reg" */ int nax_this; /* Number of axes in "this" */ int neg_reg; /* Negated attribute value for other supplied Region */ int neg_this; /* Negated attribute value for supplied Interval */ int npnt; /* Number of points in PointList */ int ok; /* Can supplied Regions be merged? */ /* Initialise */ result = NULL; lbnd = NULL; ubnd = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get the Closed attributes of the two Regions. They must be the same in each Region if we are to merge the Regions. In addition, in order to merge, either both Regions must have a defined uncertainty, or neither Region must have a defined Uncertainty. */ if( astGetClosed( this ) == astGetClosed( reg ) && astTestUnc( this ) == astTestUnc( reg ) ) { /* Get the Nagated attributes of the two Regions. */ neg_this = astGetNegated( this ); neg_reg = astGetNegated( reg ); /* Get the number of axes in the two supplied Regions. */ nax_reg = astGetNaxes( reg ); nax_this = astGetNaxes( this ); /* If the Regions can be combined, get the number of axes the combination will have. */ nax = nax_reg + nax_this; /* Get the base Frames from the two Region FrameSets, and combine them into a single CmpFrame that will be used to create any new Region. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); frm_reg = astGetFrame( reg->frameset, AST__BASE ); if( intfirst ) { bfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { bfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); /* Indicate we do not yet have a merged Region. */ new = NULL; /* First attempt to merge with another Interval. The result will be an Interval. Both Intervals must be un-negated. */ if( astIsAInterval( reg ) && !neg_this && !neg_reg ) { /* Allocate memory to store the bounds of the returned Interval. */ lbnd = astMalloc( sizeof( double )*(size_t) nax ); ubnd = astMalloc( sizeof( double )*(size_t) nax ); /* Copy the limits from the supplied Intervals into the above arrays, in the requested order. */ if( intfirst ) { astIntervalPoints( this, lbnd, ubnd ); astIntervalPoints( reg, lbnd + nax_this, ubnd + nax_this ); } else { astIntervalPoints( reg, lbnd, ubnd ); astIntervalPoints( this, lbnd + nax_reg, ubnd + nax_reg ); } /* Create the new Interval, initially with no uncertainty. */ new = (AstRegion *) astInterval( bfrm, lbnd, ubnd, NULL, "", status ); /* Free resources .*/ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Now attempt to merge with a Box. The result will be an Interval. Both Regions must be un-negated. */ } else if( astIsABox( reg ) && !neg_this && !neg_reg ) { /* Allocate memory to store the bounds of the returned Interval. */ lbnd = astMalloc( sizeof( double )*(size_t) nax ); ubnd = astMalloc( sizeof( double )*(size_t) nax ); /* Get the bounds from the Interval and add them into the above arrays. */ if( intfirst ) { astIntervalPoints( this, lbnd, ubnd ); } else { astIntervalPoints( this, lbnd + nax_reg, ubnd + nax_reg ); } /* Copy the centre and corner from the supplied Box into the required part of the above arrays. */ if( intfirst ) { centre = lbnd + nax_this; corner = ubnd + nax_this; } else { centre = lbnd; corner = ubnd; } astBoxPoints( reg, centre, corner ); /* Convert these centre and corner positions into upper and lower bounds. */ if( astOK ) { for( i = 0; i < nax_reg; i++ ) { centre[ i ] = 2*centre[ i ] - corner[ i ]; if( centre[ i ] > corner[ i ] ) { temp = centre[ i ]; centre[ i ] = corner[ i ]; corner[ i ] = temp; } } } /* Create the new Interval, initially with no uncertainty. */ new = (AstRegion *) astInterval( bfrm, lbnd, ubnd, NULL, "", status ); /* Free resources .*/ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Now attempt to merge with a NullRegion. The result will be an Interval. The NullRegion must be negated and the Interval must not. */ } else if( astIsANullRegion( reg ) && !neg_this && neg_reg ) { /* Allocate memory to store the bounds of the returned Interval. */ lbnd = astMalloc( sizeof( double )*(size_t) nax ); ubnd = astMalloc( sizeof( double )*(size_t) nax ); /* Copy the limits from the supplied Interval into the above arrays. Store bad values for the other axes indicating they are unbounded. */ if( intfirst ) { astIntervalPoints( this, lbnd, ubnd ); for( i = nax_this; i < nax; i++ ) { lbnd[ i ] = AST__BAD; ubnd[ i ] = AST__BAD; } } else { for( i = 0; i < nax_reg; i++ ) { lbnd[ i ] = AST__BAD; ubnd[ i ] = AST__BAD; } astIntervalPoints( this, lbnd + nax_reg, ubnd + nax_reg ); } /* Create the new Interval, initially with no uncertainty. */ new = (AstRegion *) astInterval( bfrm, lbnd, ubnd, NULL, "", status ); /* Free resources .*/ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Now attempt to merge with a PointList. The result will be a PointList. Both Regions must be un-negated. */ } else if( astIsAPointList( reg ) && !neg_this && !neg_reg ) { /* We can only do this if the Interval has zero width on each axis (i.e. represents a point). Get the Interval bounds. */ lbnd = astMalloc( sizeof( double )*(size_t) nax_this ); ubnd = astMalloc( sizeof( double )*(size_t) nax_this ); astRegBaseBox( this, lbnd, ubnd ); /* Get the size of the Interval's uncertainty region. */ lbnd_unc = astMalloc( sizeof( double )*(size_t) nax_this ); ubnd_unc = astMalloc( sizeof( double )*(size_t) nax_this ); bunc = astGetUncFrm( this, AST__BASE ); astGetRegionBounds( bunc, lbnd, ubnd ); /* Set "ok" to zero if the Interval does not have zero width on any axis. Here "zero width" means a width less than half the uncertainty on the axis. We also replace the lower bound values in the "lbnd" array by the central values in the Interval. */ if( astOK ) { ok = 1; for( i = 0; i < nax_this; i++ ) { if( fabs( lbnd[ i ] - lbnd[ i ] ) > 0.25*fabs( ubnd_unc[ i ] - lbnd_unc[ i ] ) ) { ok = 0; break; } else { lbnd[ i ] = 0.5*( lbnd[ i ] + ubnd[ i ] ); } } /* If the Interval is a point, we go on to create a new PointList. */ if( ok ) { /* Get a PointSet holding the axis values in the supplied PointList data. Also get the number of points in the PointSet and pointers to the arrays holding the axis values. */ astPointListPoints( reg, &pset_reg ); npnt = astGetNpoint( pset_reg ); ptr_reg = astGetPoints( pset_reg ); /* Create a new PointSet with room for the same number of points, but with the extra required axes. Get pointers to its axis arrays. */ pset_new = astPointSet( npnt, nax, "", status ); ptr_new = astGetPoints( pset_new ); /* Copy the PointList axis values into the new PointSet, and then include the extra axis values defined by the Interval to each point. */ if( astOK ) { for( j = 0; j < nax_reg; j++ ) { p = ptr_reg[ j ]; q = ptr_new[ intfirst ? nax_this + j : j ]; for( i = 0; i < npnt; i++ ) *(q++) = *(p++); } for( j = 0; j < nax_this; j++ ) { p = lbnd + j; q = ptr_new[ intfirst ? j : nax_reg + j ]; for( i = 0; i < npnt; i++ ) *(q++) = *p; } /* Create the new PointList, initially with no uncertainty. */ new = (AstRegion *) astPointList( bfrm, pset_new, NULL, "", status ); } /* Free resources .*/ pset_new = astAnnul( pset_new ); pset_reg = astAnnul( pset_reg ); } } lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); lbnd_unc = astFree( lbnd_unc ); ubnd_unc = astFree( ubnd_unc ); bunc = astAnnul( bunc ); } /* If a new Region was created above, propagate remaining attributes of the supplied Region to it. */ if( new ) { astRegOverlay( new, this, 1 ); /* The above Prism constructors create the Prism with the correct value for the Nagated attribute (i.e. zero). Ensure the above call to astRegOverlay has not changed this. */ astClearNegated( new ); /* If both the supplied Regions have uncertainty, assign the new Region an uncertainty. */ if( astTestUnc( this ) && astTestUnc( reg ) ) { /* Get the uncertainties from the two supplied Regions. */ unc_this = astGetUncFrm( this, AST__BASE ); unc_reg = astGetUncFrm( reg, AST__BASE ); /* Combine them into a single Region (a Prism), in the correct order. */ if( intfirst ) { bunc = (AstRegion *) astPrism( unc_this, unc_reg, "", status ); } else { bunc = (AstRegion *) astPrism( unc_reg, unc_this, "", status ); } /* Attempt to simplify the Prism. */ sbunc = astSimplify( bunc ); /* Use the simplified Prism as the uncertainty for the returned Region. */ astSetUnc( new, sbunc ); /* Free resources. */ sbunc = astAnnul( sbunc ); bunc = astAnnul( bunc ); unc_reg = astAnnul( unc_reg ); unc_this = astAnnul( unc_this ); } /* Get the current Frames from the two Region FrameSets, and combine them into a single CmpFrame. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__CURRENT ); frm_reg = astGetFrame( reg->frameset, AST__CURRENT ); if( intfirst ) { cfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { cfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } /* Get the base -> current Mappings from the two Region FrameSets, and combine them into a single parallel CmpMap that connects bfrm and cfrm. */ map_this = astGetMapping( ((AstRegion *) this)->frameset, AST__BASE, AST__CURRENT ); map_reg = astGetMapping( reg->frameset, AST__BASE, AST__CURRENT ); if( intfirst ) { bcmap = (AstMapping *) astCmpMap( map_this, map_reg, 0, "", status ); } else { bcmap = (AstMapping *) astCmpMap( map_reg, map_this, 0, "", status ); } /* Map the new Region into the new current Frame. */ result = astMapRegion( new, bcmap, cfrm ); /* The filling factor in the returned is the product of the filling factors for the two supplied Regions. */ if( astTestFillFactor( reg ) || astTestFillFactor( this ) ) { astSetFillFactor( result, astGetFillFactor( reg )* astGetFillFactor( this ) ); } /* If the MeshSize value is set in either supplied Region, set a value for the returned Region which scales the default value by the product of the scaling factors for the two supplied Regions. First see if either MeshSize value is set. */ msz_this_set = astTestMeshSize( this ); msz_reg_set = astTestMeshSize( reg ); if( msz_this_set || msz_reg_set ) { /* If so, get the two MeshSize values (one of which may be a default value), and then clear them so that the default value will be returned in future. */ msz_this = astGetMeshSize( this ); msz_reg = astGetMeshSize( reg ); astClearMeshSize( this ); astClearMeshSize( reg ); /* Get the ratio of the used MeshSize to the default MeshSize for both Regions. */ fac_this = (double)msz_this/(double)astGetMeshSize( this ); fac_reg = (double)msz_reg/(double)astGetMeshSize( reg ); /* The MeshSize of the returned Returned is the default value scaled by the product of the two ratios found above. */ astSetMeshSize( result, fac_this*fac_reg*astGetMeshSize( result ) ); /* Re-instate the original MeshSize values for the supplied Regions (if set) */ if( msz_this_set ) astSetMeshSize( this, msz_this ); if( msz_reg_set ) astSetMeshSize( reg, msz_reg ); } /* Free remaining resources */ frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); map_this = astAnnul( map_this ); map_reg = astAnnul( map_reg ); bcmap = astAnnul( bcmap ); new = astAnnul( new ); cfrm = astAnnul( cfrm ); } bfrm = astAnnul( bfrm ); } /* If an error has occurred, annul the returned pointer. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int *OneToOne( AstMapping *map, int *status ){ /* * Name: * OneToOne * Purpose: * Does each output of the supplied Mapping depend on only one input? * Type: * Private function. * Synopsis: * #include "interval.h" * int OneToOne( AstMapping *map, int *status ) * Class Membership: * Interval method * Description: * This function returns a flag indicating if the Mapping is 1-to-1. * That is, if each output depends only on one input. * Parameters: * map * Pointer to the Mapping. * status * Pointer to the inherited status variable. * Returned Value: * If the Mapping is 1-to-1, a pointer to an array of ints is returned * (NULL is returned otherwise). There is one int for each output of * the supplied Mapping. The value of each int is the index of the * corresponding input which feeds the output. The array should be * freed using astFree when no longer needed. */ /* Local Variables: */ int *result; const char *class; int nout; int i; int *tt; AstMapping *tmap; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the number of outputs for the Mapping. */ nout = astGetNout( map ); /* The Mapping cannot be 1-to-1 if the number of inputs is different.*/ if( astGetNin( map ) == nout ) { /* Allocate an output array on the assumption that the Mapping is 1-to-1. */ result = astMalloc( sizeof( int )*(size_t) nout ); if( result ) { /* Check known specal cases for speed. */ class = astGetClass( map ); if( !strcmp( class, "WinMap" ) || !strcmp( class, "ZoomMap" ) || !strcmp( class, "UnitMap" ) || !strcmp( class, "ShiftMap" ) ){ /* Each output is fed by the corresponding input for these classes of Mapping. */ for( i = 0; i < nout; i++ ) result[ i ] = i; /* Now do the general case. */ } else { /* Loop round each input axis. */ for( i = 0; i < nout; i++ ) { /* Use astMapSplit to see if this input corresponds to a single output. */ tt = astMapSplit( map, 1, &i, &tmap ); /* If not, annul the returned array and break. */ if( !tmap ) { result = astFree( result ); break; /* If so, store the index of the corresponding input in the returned array and free resources. */ } else { result[ tt[ 0 ] ] = i; tt = astFree( tt ); if( astGetNout( tmap ) != 1 ) result = astFree( result ); tmap = astAnnul( tmap ); if( !result ) break; } } } } } /* Return the result */ return result; } static int Overlap( AstRegion *this, AstRegion *that, int *status ){ /* * Name: * Overlap * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "interval.h" * int Overlap( AstRegion *this, AstRegion *that, int *status ) * Class Membership: * Interval member function (over-rides the astOverlap method inherited * from the Region class). * Description: * This function returns an integer value indicating if the two * supplied Regions overlap. The two Regions are converted to a commnon * coordinate system before performing the check. If this conversion is * not possible (for instance because the two Regions represent areas in * different domains), then the check cannot be performed and a zero value * is returned to indicate this. * Parameters: * this * Pointer to the first Region. * that * Pointer to the second Region. * status * Pointer to the inherited status variable. * Returned Value: * astOverlap() * A value indicating if there is any overlap between the two Regions. * Possible values are: * * 0 - The check could not be performed because the second Region * could not be mapped into the coordinate system of the first * Region. * * 1 - There is no overlap between the two Regions. * * 2 - The first Region is completely inside the second Region. * * 3 - The second Region is completely inside the first Region. * * 4 - There is partial overlap between the two Regions. * * 5 - The Regions are identical. * * 6 - The second Region is the negation of the first Region. * Notes: * - The returned values 5 and 6 do not check the value of the Closed * attribute in the two Regions. * - A value of zero will be returned if this function is invoked with the * AST error status set, or if it should fail for any reason. */ /* Local Variables: */ AstFrame *frm; AstFrameSet *fs; AstMapping *map; AstMapping *map1; AstMapping *map2; AstMapping *map3; AstMapping *smap; AstMapping *tmap; AstPointSet *pset_that; AstRegion *unc_temp; AstRegion *unc_that; AstRegion *unc_this; double **ptr_that; double **ptr_thato; double **ptr_this; double *lbndu_that; double *lbndu_this; double *ubndu_that; double *ubndu_this; double err; double err_that; double err_this; double lb_that; double lb_this; double tmp; double ub_that; double ub_this; int *outperm; int ic; int inc_that; int inc_this; int lb_equal; int nc; int neg_that; int neg_this; int ov; int result; int ub_equal; static int newResult[ 5 ][ 5 ] = { { 1, 1, 1, 1, 1}, { 1, 2, 4, 4, 2}, { 1, 4, 3, 4, 3}, { 1, 4, 4, 4, 4}, { 1, 2, 3, 4, 5} }; /* Initialise */ result = 0; /* Check the inherited status. */ if ( !astOK ) return result; /* If both Regions are Intervals, we provide a specialised implementation. The implementation in the parent Region class assumes that at least one of the two Regions can be represented using a finite mesh of points on the boundary which is not the case with Intervals. The implementation in this class sees if the Mapping between the base Frames of the Intervals allows the axis limits to be transferred from one Frame ot the other. */ if( astIsAInterval( this ) && astIsAInterval( that ) ) { /* Get a FrameSet which connects the Frame represented by the second Interval to the Frame represented by the first Interval. Check that the conection is defined. */ fs = astConvert( that, this, "" ); if( fs ) { /* Get a pointer to the Mapping from base to current Frame in the second Interval */ map1 = astGetMapping( that->frameset, AST__BASE, AST__CURRENT ); /* Get the Mapping from the current Frame of the second Interval to the current Frame of the first Interval. */ map2 = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Get a pointer to the Mapping from current to base Frame in the first Interval. */ map3 = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); /* Combine these Mappings to get the Mapping from the base Frame of the second Interval to the base Frame of the first Interval. */ tmap = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); map = (AstMapping *) astCmpMap( tmap, map3, 1, "", status ); /* Simplify this Mapping. */ smap = astSimplify( map ); /* We can only proceed if each output of the simplified Mapping depends on only one input. Test this. */ outperm = OneToOne( smap, status ); if( outperm ){ /* Get the uncertainty Regions for both Intervals, expressed in the base Frames of the Intervals. */ unc_this = astGetUncFrm( this, AST__BASE ); unc_temp = astGetUncFrm( that, AST__BASE ); /* Map the uncertainty Region for the second Interval from the base Frame of the second Interval into the base Frame of the first Interval. */ frm = astGetFrame( this->frameset, AST__BASE ); unc_that = astMapRegion( unc_temp, smap, frm ); /* Get the bounding boxes of the two uncertainty Regions in the base Frame of the first Interval. */ nc = astGetNaxes( frm ); lbndu_this = astMalloc( sizeof( double )*(size_t)nc ); ubndu_this = astMalloc( sizeof( double )*(size_t)nc ); astGetRegionBounds( unc_this, lbndu_this, ubndu_this ); lbndu_that = astMalloc( sizeof( double )*(size_t)nc ); ubndu_that = astMalloc( sizeof( double )*(size_t)nc ); astGetRegionBounds( unc_that, lbndu_that, ubndu_that ); /* Transform the PointSet holding the limits for the second Interval into the Frame of the first Interval. */ pset_that = astTransform( smap, that->points, 1, NULL ); /* Get pointers for accesing the limits of the two Intervals, expressed in a common Frame (the base Frame of the first Interval). */ ptr_that = astGetPoints( pset_that ); ptr_thato = astGetPoints( that->points ); ptr_this = astGetPoints( this->points ); if( astOK ) { /* Check the limits on each base Frame axis in turn. */ for( ic = 0; ic < nc; ic++ ) { /* Get the widths of the two uncertainty boxes on this axis. */ err_this = ubndu_this[ ic ] - lbndu_this[ ic ]; err_that = ubndu_that[ ic ] - lbndu_that[ ic ]; /* Add this together in quadrature to get the tolerance for two values on the current axis to be considered equal. */ err = sqrt( err_that*err_that + err_this*err_this ); /* Get the limits on this axis from both Intervals. */ lb_this = ptr_this[ ic ][ 0 ]; ub_this = ptr_this[ ic ][ 1 ]; lb_that = ptr_that[ ic ][ 0 ]; ub_that = ptr_that[ ic ][ 1 ]; /* The limits for "that" have been mapped, which may have resulted in them being swapped. We need to unswap them in this case to prevent the swapping being used as an indication of a desire to use an excluded interval rather than an included interval. */ if( lb_that != AST__BAD && ub_that != AST__BAD ) { if( ptr_thato[ ic ][ 0 ] < ptr_thato[ ic ][ 1 ] ) { if( lb_that > ub_that ) { tmp = lb_that; lb_that = ub_that; ub_that = tmp; } } else { if( lb_that < ub_that ) { tmp = lb_that; lb_that = ub_that; ub_that = tmp; } } } /* If the regions are not closed, reduce the limits by the smallest amount possible. */ if( !astGetClosed( that ) ) { if( lb_that != AST__BAD && lb_that < DBL_MAX ) lb_that += DBL_EPSILON*fabs(lb_that); if( ub_that != AST__BAD && ub_that > -DBL_MAX ) ub_that -= DBL_EPSILON*fabs(ub_that); } if( !astGetClosed( this ) ) { if( lb_this != AST__BAD && lb_this < DBL_MAX ) lb_this += DBL_EPSILON*fabs(lb_this); if( ub_this != AST__BAD && ub_this > -DBL_MAX ) ub_this -= DBL_EPSILON*fabs(ub_this); } /* Replace any missing limits with suitable extreme values */ if( lb_this == AST__BAD ) lb_this = -DBL_MAX; if( ub_this == AST__BAD ) ub_this = DBL_MAX; if( lb_that == AST__BAD ) lb_that = -DBL_MAX; if( ub_that == AST__BAD ) ub_that = DBL_MAX; /* If the bounds are the wrong way round (indicating an excluded rather than an included axis range), swap them. Also set a flag indicating if the limits define an included or excluded range. */ inc_this = ( lb_this <= ub_this ); if( !inc_this ) { tmp = lb_this; lb_this = ub_this; ub_this = tmp; } inc_that = ( lb_that <= ub_that ); if( !inc_that ) { tmp = lb_that; lb_that = ub_that; ub_that = tmp; } /* Are the lower limits from the two Intervals effectively equal? Take care about DBL_MAX values causing overflow. */ lb_equal = astEQUALS( lb_this, lb_that, 1.0E9 ); if( !lb_equal && fabs(lb_this) != DBL_MAX && fabs(lb_that) != DBL_MAX ) { lb_equal = ( fabs( lb_this - lb_that) <= err ); } /* Are the upper limits from the two Intervals effectively equal? */ ub_equal = astEQUALS( ub_this, ub_that, 1.0E9 ); if( !ub_equal && fabs(ub_this) != DBL_MAX && fabs(ub_that) != DBL_MAX ) { ub_equal = ( fabs( ub_this - ub_that) <= err ); } /* If both the limits on this axis are effectively equal for the two Intervals, set "ov" to 5 if both Interval ranges are inclusive or both are exclusive, and set "ov" to 6 if one Interval range is exclusive and the other is inclusive. */ if( lb_equal && ub_equal ) { ov = ( inc_this == inc_that ) ? 5 : 6; /* See if the limits on this axis indicate overlap for the two Intervals. "ov" is set to 1 if there is no overlap, 2 if the first Interval range is completely inside the second Interval range, 3 if the second Interval range is completely inside the first Interval range, and 4 if there is partial overlap between the Interval ranges. */ } else if( inc_this ) { if( inc_that ) { if( lb_that <= lb_this && ub_that >= ub_this ) { ov = 2; } else if( lb_that >= lb_this && ub_that <= ub_this ) { ov = 3; } else if( ub_that >= lb_this && lb_that <= ub_this ) { ov = 4; } else { ov = 1; } } else { if( lb_that <= lb_this && ub_that >= ub_this ) { ov = 1; } else if( lb_that >= ub_this || ub_that <= lb_this ) { ov = 2; } else if( lb_this == -DBL_MAX && ub_this == DBL_MAX ) { ov = 3; } else { ov = 4; } } } else { if( inc_that ) { if( lb_this <= lb_that && ub_this >= ub_that ) { ov = 1; } else if( lb_this >= ub_that || ub_this <= lb_that ) { ov = 3; } else if( lb_that == -DBL_MAX && ub_that == DBL_MAX ) { ov = 2; } else { ov = 4; } } else { ov = 4; } } /* The returned value is initialised on the basis of the first axis overlap. */ if( ic == 0 ) { result = ov; /* For subsequent axes, combine the old result value with the new ov value to get the new result value. */ } else { result = newResult[ result - 1 ][ ov - 1 ]; } /* If we now know there is no overlap, there is no point in checking any remaining axes. */ if( result == 1 ) break; } /* The above logic assumed that neither of the Intervals has been negated. Decide on the value to return, taking into account whether either of the Intervals has been negated. */ neg_this = astGetNegated( this ); neg_that = astGetNegated( that ); if( result == 1 ) { if( neg_this ) { result = neg_that ? 4 : 3; } else if( neg_that ){ result = 2; } } else if( result == 2) { if( neg_this ) { result = neg_that ? 3 : 4; } else if( neg_that ){ result = 1; } } else if( result == 3) { if( neg_this ) { result = neg_that ? 2 : 1; } else if( neg_that ){ result = 4; } } else if( result == 4) { result = 4; } else if( result == 5) { if( neg_this ) { result = neg_that ? 5 : 6; } else if( neg_that ){ result = 6; } } } /* Free resources. */ pset_that = astAnnul( pset_that ); unc_this = astAnnul( unc_this ); unc_that = astAnnul( unc_that ); unc_temp = astAnnul( unc_temp ); frm = astAnnul( frm ); lbndu_this = astFree( lbndu_this ); ubndu_this = astFree( ubndu_this ); lbndu_that = astFree( lbndu_that ); ubndu_that = astFree( ubndu_that ); outperm = astFree( outperm ); } smap = astAnnul( smap ); map = astAnnul( map ); tmap = astAnnul( tmap ); map3 = astAnnul( map3 ); map2 = astAnnul( map2 ); map1 = astAnnul( map1 ); fs = astAnnul( fs ); } } /* If overlap could not be determined using the above implementation, try using the implementation inherited from the parent Region class. */ if( !result ) result = (*parent_overlap)( this, that, status ); /* If not OK, return zero. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "interval.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Interval member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstInterval *this; int nax; int i; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Interval structure */ this = (AstInterval *) this_region; /* Ensure the cached bounds are up to date. */ Cache( this, status ); /* Copy the cached bounds into the supplied arrays. */ nax = astGetNin( this_region->frameset ); for( i = 0; i < nax; i++ ) { lbnd[ i ] = this->lbnd[ i ]; ubnd[ i ] = this->ubnd[ i ]; } } static AstPointSet *RegBaseMesh( AstRegion *this_region, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "interval.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Interval member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. The axis values in this PointSet will have * associated accuracies derived from the accuracies which were * supplied when the Region was created. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstBox *box; /* The equivalent Box */ AstPointSet *result; /* Returned pointer */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the Interval is effectively a Box, invoke the astRegBaseMesh function on the equivalent Box. A pointer to the equivalent Box will be stored in the Interval structure. */ box = Cache( (AstInterval *) this_region, status ); if( box ) { result = astRegBaseMesh( box ); /* If the Interval is not equivalent to a Box, report an error. */ } else { astError( AST__INTER, "astRegBaseMesh(%s): The %s given is " "unbounded and therefore no boundary mesh can be " "produced (internal AST programming error).", status, astGetClass( this_region ), astGetClass( this_region ) ); } /* Return a pointer to the output PointSet. */ return result; } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "interval.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * Interval member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; /* The base Frame in the supplied Region */ AstFrame *frm; /* The base Frame in the returned Region */ AstPointSet *pset; /* Holds axis values defining the supplied Region */ AstRegion *bunc; /* The uncertainty in the supplied Region */ AstRegion *result; /* Returned Region */ AstRegion *unc; /* The uncertainty in the returned Region */ double **ptr; /* Holds axis values defining the supplied Region */ double *lbnd; /* Base Frm lower bound axis values */ double *ubnd; /* Base Frm upper bound axis values */ int i; /* Index of axis within returned Region */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the base Frame of the encapsulated FrameSet. */ bfrm = astGetFrame( this_region->frameset, AST__BASE ); /* Create a Frame by picking the selected axes from the base Frame of the encapsulated FrameSet. */ frm = astPickAxes( bfrm, naxes, axes, NULL ); /* Get the uncertainty Region (if any) within the base Frame of the supplied Region, and select the required axes from it. If the resulting Object is not a Region, annul it so that the returned Region will have no uncertainty. */ if( astTestUnc( this_region ) ) { bunc = astGetUncFrm( this_region, AST__BASE ); unc = astPickAxes( bunc, naxes, axes, NULL ); bunc = astAnnul( bunc ); if( ! astIsARegion( unc ) ) unc = astAnnul( unc ); } else { unc = NULL; } /* Get pointers to the coordinate data in the parent Region structure. */ pset = this_region->points; ptr = astGetPoints( pset ); /* Get space to hold the limits of the Interval in the new Frame. */ lbnd = astMalloc( sizeof( *lbnd )*naxes ); ubnd = astMalloc( sizeof( *ubnd )*naxes ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the limits for the selected axes into the arrays allocated above. */ for( i = 0; i < naxes; i++ ) { lbnd[ i ] = ptr[ axes[ i ] ][ 0 ]; ubnd[ i ] = ptr[ axes[ i ] ][ 1 ]; } /* Create the new Interval. */ result = (AstRegion *) astInterval( frm, lbnd, ubnd, unc, "", status ); } /* Free resources */ frm = astAnnul( frm ); bfrm = astAnnul( bfrm ); if( unc ) unc = astAnnul( unc ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Return a NULL pointer if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static double *RegCentre( AstRegion *this_region, double *cen, double **ptr, int index, int ifrm, int *status ){ /* * Name: * RegCentre * Purpose: * Re-centre a Region. * Type: * Private function. * Synopsis: * #include "interval.h" * double *RegCentre( AstRegion *this, double *cen, double **ptr, * int index, int ifrm, int *status ) * Class Membership: * Interval member function (over-rides the astRegCentre protected * method inherited from the Region class). * Description: * This function shifts the centre of the supplied Region to a * specified position, or returns the current centre of the Region. * Parameters: * this * Pointer to the Region. * cen * Pointer to an array of axis values, giving the new centre. * Supply a NULL value for this in order to use "ptr" and "index" to * specify the new centre. * ptr * Pointer to an array of points, one for each axis in the Region. * Each pointer locates an array of axis values. This is the format * returned by the PointSet method astGetPoints. Only used if "cen" * is NULL. * index * The index of the point within the arrays identified by "ptr" at * which is stored the coords for the new centre position. Only used * if "cen" is NULL. * ifrm * Should be AST__BASE or AST__CURRENT. Indicates whether the centre * position is supplied and returned in the base or current Frame of * the FrameSet encapsulated within "this". * status * Pointer to the inherited status variable. * Returned Value: * If both "cen" and "ptr" are NULL then a pointer to a newly * allocated dynamic array is returned which contains the centre * coords of the Region. This array should be freed using astFree when * no longer needed. If either of "ptr" or "cen" is not NULL, then a * NULL pointer is returned. * Notes: * - Some Region sub-classes do not have a centre. Such classes will report * an AST__INTER error code if this method is called with either "ptr" or * "cen" not NULL. If "ptr" and "cen" are both NULL, then no error is * reported if this method is invoked on a Region of an unsuitable class, * but NULL is always returned. */ /* Local Variables: */ AstInterval *this; /* Pointer to Interval structure */ AstBox *box; /* Pointer to equivalent Box structure */ double **bptr; /* Data pointers for Region PointSet */ double *lbnd; /* Pointer to new lower bound values */ double *ubnd; /* Pointer to new upper bound values */ double *result; /* Returned pointer */ int i; /* Coordinate index */ int nax; /* Number of axes */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get a pointer to the Interval structure. */ this = (AstInterval *) this_region; /* The Interval can only be re-centred if it is effectively a Box. */ box = Cache( (AstInterval *) this_region, status ); if( box ) { /* If the centre is being changed... */ if( cen || ptr ) { /* Set the new centre in the equivalent box. */ astRegCentre( box, cen, ptr, index, ifrm ); /* Get the new base Frame bounds from the Box. */ nax = astGetNin( this_region->frameset ); lbnd = astMalloc( sizeof( double )*nax ); ubnd = astMalloc( sizeof( double )*nax ); astRegBaseBox( box, lbnd, ubnd ); /* Store these bounds in the Interval structure. */ bptr = astGetPoints( this_region->points ); if( astOK ) { for( i = 0; i < nax; i++ ) { bptr[ i ][ 0 ] = lbnd[ i ]; bptr[ i ][ 1 ] = ubnd[ i ]; } } /* Free resources. */ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* If the centre is not being changed, just invoke the method on the equivalent box. */ } else { result = astRegCentre( box, NULL, NULL, 0, AST__BASE ); } /* If the Interval is not equivalent to a Box, report an error */ } else if( cen || ptr ) { astError( AST__REGCN, "astRegCentre(%s): The supplied %s is not a " "closed Interval and so cannot be re-centred.", status, astGetClass( this ), astGetClass( this ) ); } /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Interval. * Type: * Private function. * Synopsis: * #include "interval.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Interval member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Interval. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Interval "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Interval. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstBox *box; /* The equivalent Box */ AstInterval *large_int; /* Interval slightly larger than "this" */ AstInterval *small_int; /* Interval slightly smaller than "this" */ AstInterval *this; /* Pointer to the Interval structure. */ AstFrame *frm; /* Base Frame in supplied Interval */ AstPointSet *ps1; /* Points masked by larger Interval */ AstPointSet *ps2; /* Points masked by larger and smaller Intervals */ AstRegion *tunc; /* Uncertainity Region from "this" */ double **ptr; /* Pointer to axis values in "ps2" */ double *large_lbnd; /* Lower bounds of larger interval */ double *large_ubnd; /* Upper bounds of larger interval */ double *lbnd_tunc; /* Lower bounds of "this" uncertainty Region */ double *lbnd_unc; /* Lower bounds of supplied uncertainty Region */ double *p; /* Pointer to next axis value */ double *safe; /* An interior point in "this" */ double *small_lbnd; /* Lower bounds of smaller interval */ double *small_ubnd; /* Upper bounds of smaller interval */ double *ubnd_tunc; /* Upper bounds of "this" uncertainty Region */ double *ubnd_unc; /* Upper bounds of supplied uncertainty Region */ double *wid; /* Widths of "this" border */ double lb; /* Lower bound */ double ub; /* Upper bound */ double t; /* Swap space */ double w; /* Width */ int i; /* Axis index */ int j; /* Point index */ int nc; /* No. of axes in Interval base frame */ int np; /* No. of supplied points */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Interval structure. */ this = (AstInterval *) this_region; /* If the Interval is effectively a Box, invoke the astRegPins function on the equivalent Box. A pointer to the equivalent Box will be stored in the Interval structure. */ box = Cache( this, status ); if( box ) return astRegPins( box, pset, unc, mask ); /* Arrive here only if the Interval is not equivalent to a box (i.e. has at least one infinite boundary). Get the number of base Frame axes in the Interval, and check the supplied PointSet has the same number of axis values per point. */ frm = astGetFrame( this_region->frameset, AST__BASE ); nc = astGetNaxes( frm ); if( astGetNcoord( pset ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axis " "values per point (%d) in the supplied PointSet - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNcoord( pset ), nc ); } /* Get the number of axes in the uncertainty Region and check it is the same as above. */ if( unc && astGetNaxes( unc ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axes (%d) " "in the supplied uncertainty Region - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNaxes( unc ), nc ); } /* Get the centre of the region in the base Frame. We use this as a "safe" interior point within the region. */ safe = astRegCentre( this, NULL, NULL, 0, AST__BASE ); /* We now find the maximum distance on each axis that a point can be from the boundary of the Interval for it still to be considered to be on the boundary. First get the Region which defines the uncertainty within the Interval being checked (in its base Frame), re-centre it on the interior point found above (to avoid problems if the uncertainty region straddles a discontinuity), and get its bounding box. */ tunc = astGetUncFrm( this, AST__BASE ); if( safe ) astRegCentre( tunc, safe, NULL, 0, AST__CURRENT ); lbnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( tunc, lbnd_tunc, ubnd_tunc ); /* Also get the Region which defines the uncertainty of the supplied points and get its bounding box. First re-centre the uncertainty at the interior position to avoid problems from uncertainties that straddle a discontinuity. */ if( unc ) { if( safe ) astRegCentre( unc, safe, NULL, 0, AST__CURRENT ); lbnd_unc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_unc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); } else { lbnd_unc = NULL; ubnd_unc = NULL; } /* The required border width for each axis is half of the total width of the two bounding boxes. Use a zero sized box "unc" if no box was supplied. */ wid = astMalloc( sizeof( double )*(size_t) nc ); large_lbnd = astMalloc( sizeof( double )*(size_t) nc ); large_ubnd = astMalloc( sizeof( double )*(size_t) nc ); small_lbnd = astMalloc( sizeof( double )*(size_t) nc ); small_ubnd = astMalloc( sizeof( double )*(size_t) nc ); if( small_ubnd ) { if( unc ) { for( i = 0; i < nc; i++ ) { wid[ i ] = 0.5*( fabs( astAxDistance( frm, i + 1, lbnd_tunc[ i ], ubnd_tunc[ i ] ) ) + fabs( astAxDistance( frm, i + 1, lbnd_unc[ i ], ubnd_unc[ i ] ) ) ); } } else { for( i = 0; i < nc; i++ ) { wid[ i ] = 0.5*fabs( astAxDistance( frm, i + 1, lbnd_tunc[ i ], ubnd_tunc[ i ] ) ); } } /* Create two new Intervals, one of which is larger than "this" by the widths found above, and the other of which is smaller than "this" by the widths found above. */ for( i = 0; i < nc; i++ ) { lb = this->lbnd[ i ]; ub = this->ubnd[ i ]; if( lb > ub ) { t = ub; ub = lb; lb = t; } w = fabs( wid[ i ] ); if( lb != -DBL_MAX ){ large_lbnd[ i ] = lb - w; small_lbnd[ i ] = lb + w; } else { large_lbnd[ i ] = AST__BAD; small_lbnd[ i ] = AST__BAD; } if( ub != DBL_MAX ){ large_ubnd[ i ] = ub + w; small_ubnd[ i ] = ub - w; } else { large_ubnd[ i ] = AST__BAD; small_ubnd[ i ] = AST__BAD; } if( small_lbnd[ i ] > small_ubnd[ i ] ) { small_lbnd[ i ] = small_ubnd[ i ]; } } large_int = astInterval( frm, large_lbnd, large_ubnd, NULL, "", status ); small_int = astInterval( frm, small_lbnd, small_ubnd, NULL, "", status ); /* Negate the smaller interval.*/ astNegate( small_int ); /* Points are on the boundary of "this" if they are inside both the large interval and the negated small interval. First transform the supplied PointSet using the large interval, then transform them using the negated smaller Interval. */ ps1 = astTransform( large_int, pset, 1, NULL ); ps2 = astTransform( small_int, ps1, 1, NULL ); /* Get a point to the resulting axis values, and the number of axis values per axis. */ ptr = astGetPoints( ps2 ); np = astGetNpoint( ps2 ); /* If a mask array is to be returned, create one. */ if( mask ) { *mask = astMalloc( sizeof(int)*(size_t) np ); /* Check all the resulting points, setting mask values for all of them. */ if( astOK ) { /* Initialise the mask elements on the basis of the first axis values */ result = 1; p = ptr[ 0 ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } else { (*mask)[ j ] = 1; } } /* Now check for bad values on other axes. */ for( i = 1; i < nc; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } } } } /* If no output mask is to be made, we can break out of the check as soon as the first bad value is found. */ } else if( astOK ) { result = 1; for( i = 0; i < nc && result; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; break; } } } } /* Free resources. */ large_int = astAnnul( large_int ); small_int = astAnnul( small_int ); ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } tunc = astAnnul( tunc ); frm = astAnnul( frm ); lbnd_tunc = astFree( lbnd_tunc ); ubnd_tunc = astFree( ubnd_tunc ); if( unc ) lbnd_unc = astFree( lbnd_unc ); if( unc ) ubnd_unc = astFree( ubnd_unc ); wid = astFree( wid ); large_lbnd = astFree( large_lbnd ); large_ubnd = astFree( large_ubnd ); small_lbnd = astFree( small_lbnd ); small_ubnd = astFree( small_ubnd ); safe = astFree( safe ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static int RegTrace( AstRegion *this_region, int n, double *dist, double **ptr, int *status ){ /* *+ * Name: * RegTrace * Purpose: * Return requested positions on the boundary of a 2D Region. * Type: * Private function. * Synopsis: * #include "interval.h" * int astTraceRegion( AstRegion *this, int n, double *dist, double **ptr ); * Class Membership: * Interval member function (overrides the astTraceRegion method * inherited from the parent Region class). * Description: * This function returns positions on the boundary of the supplied * Region, if possible. The required positions are indicated by a * supplied list of scalar parameter values in the range zero to one. * Zero corresponds to some arbitrary starting point on the boundary, * and one corresponds to the end (which for a closed region will be * the same place as the start). * Parameters: * this * Pointer to the Region. * n * The number of positions to return. If this is zero, the function * returns without action (but the returned function value still * indicates if the method is supported or not). * dist * Pointer to an array of "n" scalar parameter values in the range * 0 to 1.0. * ptr * A pointer to an array of pointers. The number of elements in * this array should equal tthe number of axes in the Frame spanned * by the Region. Each element of the array should be a pointer to * an array of "n" doubles, in which to return the "n" values for * the corresponding axis. The contents of the arrays are unchanged * if the supplied Region belongs to a class that does not * implement this method. * Returned Value: * Non-zero if the astTraceRegion method is implemented by the class * of Region supplied, and zero if not. *- */ /* Local Variables; */ AstBox *box; int result; /* Initialise */ result = 0; /* Check inherited status. */ if( ! astOK ) return result; /* If the Interval is effectively a Box, invoke the astRegTrace function on the equivalent Box. A pointer to the equivalent Box will be stored in the Interval structure. */ box = Cache( (AstInterval *) this_region, status ); if( box ) result = astRegTrace( box, n, dist, ptr ); /* Return the result. */ return result; } static void ResetCache( AstRegion *this, int *status ){ /* * Name: * ResetCache * Purpose: * Clear cached information within the supplied Region. * Type: * Private function. * Synopsis: * #include "interval.h" * void ResetCache( AstRegion *this, int *status ) * Class Membership: * Region member function (overrides the astResetCache method * inherited from the parent Region class). * Description: * This function clears cached information from the supplied Region * structure. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ if( this ) { ( (AstInterval *) this )->stale = 1; (*parent_resetcache)( this, status ); } } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "interval.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Interval method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* Indicate that the cached intermediate information is now stale and should be recreated when next needed. */ astResetCache( this_region ); } static void SetUnc( AstRegion *this, AstRegion *unc, int *status ){ /* * Name: * SetUnc * Purpose: * Store uncertainty information in a Region. * Type: * Private function. * Synopsis: * #include "interval.h" * void SetUnc( AstRegion *this, AstRegion *unc, int *status ) * Class Membership: * Interval method (over-rides the astSetUnc method inherited from the * Region class). * Description: * Each Region (of any class) can have an "uncertainty" which specifies * the uncertainties associated with the boundary of the Region. This * information is supplied in the form of a second Region. The uncertainty * in any point on the boundary of a Region is found by shifting the * associated "uncertainty" Region so that it is centred at the boundary * point being considered. The area covered by the shifted uncertainty * Region then represents the uncertainty in the boundary position. * The uncertainty is assumed to be the same for all points. * * The uncertainty is usually specified when the Region is created, but * this function allows it to be changed at any time. * Parameters: * this * Pointer to the Region which is to be assigned a new uncertainty. * unc * Pointer to the new uncertainty Region. This must be either a Box, * a Circle or an Ellipse. A deep copy of the supplied Region will be * taken, so subsequent changes to the uncertainty Region using the * supplied pointer will have no effect on the Region "this". * status * Pointer to the inherited status variable. */ /* Check the inherited status. */ if( !astOK ) return; /* Invoke the astSetUnc method inherited from the parent Region class. */ (*parent_setunc)( this, unc, status ); /* Indicate that the cached intermediate information is now stale and should be recreated when next needed. */ astResetCache( this ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "interval.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Interval method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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: */ AstBox *box2; /* Box used to determine 1-to-1 axis correspondance */ AstBox *box; /* Box used to determine 1-to-1 axis correspondance */ AstInterval *this_interval;/* Pointer to Interval structure */ AstMapping *bfrm; /* Pointer to base Frame in supplied Interval */ AstMapping *cfrm; /* Pointer to current Frame in supplied Interval */ AstMapping *map; /* Base -> current Mapping after parent simplification */ AstMapping *result; /* Result pointer to return */ AstPointSet *pset2; /* PointSet containing current Frame test points */ AstPointSet *pset3; /* PointSet containing base Frame test points */ AstPointSet *psetb; /* PointSet holding base positions */ AstPointSet *psetc; /* PointSet holding current positions */ AstRegion *new; /* Pointer to Region simplfied by parent class */ AstRegion *sreg; /* Pointer to simplified Box */ AstRegion *this; /* Pointer to supplied Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr2; /* Pointer axis values in "pset2" */ double **ptr3; /* Pointer axis values in "pset3" */ double **ptr; /* Pointer to base Frame values defining Interval */ double **ptrb; /* Pointer to "psetb" axis values */ double **sptr; /* Pointer to simplified Interval bounds */ double *lbnd; /* Pointer to array of base Frame lower bounds */ double *slbnd; /* Pointer to array of current Frame lower bounds */ double *subnd; /* Pointer to array of current Frame upper bounds */ double *ubnd; /* Pointer to array of base Frame upper bounds */ double d; /* Distance between axis values */ double lb; /* Lower bound on axis values */ double lwid; /* Axis width below the Interval lower limit */ double maxd; /* Maximum currenrt Frame axis offset between test points */ double tmp; /* Temporary storage for swapping variable values */ double ub; /* Upperbound on axis values */ double uwid; /* Axis width above the Interval upper limit */ int bax; /* Base Frame axis index corresponding to "ic" */ int ic; /* Axis index */ int jc; /* Axis index */ int nc; /* No. of base Frame axis values per point */ int simpler; /* Has some simplication taken place? */ int snc; /* No. of current Frame axis values per point */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the supplied Region structure. */ this = (AstRegion *) this_mapping; /* Get a pointer to the supplied Interval structure. */ this_interval = (AstInterval *) this; /* If this Interval is equivalent to a Box, use the astTransform method of the equivalent Box. */ box = Cache( this_interval, status ); if( box ) { result = astSimplify( box ); /* Otherwise, we use a new implementation appropriate for unbounded intervals. */ } else { /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); if( new ) { /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* If the Mapping from base to current Frame is not a UnitMap, we attempt to simplify the Interval by re-defining it within its current Frame. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) ){ /* Take a copy of the Interval bounds (defined in the base Frame of the Intervals FrameSet) and replace any missing limits with arbitrary non-BAD values. This will give us a complete set of bounds defining a box within the base Frame of the Interval. */ ptr = astGetPoints( new->points ); nc = astGetNcoord( new->points ); lbnd = astMalloc( sizeof( double )*(size_t) nc ); ubnd = astMalloc( sizeof( double )*(size_t) nc ); if( astOK ) { for( ic = 0; ic < nc; ic++ ) { lbnd[ ic ] = ptr[ ic ][ 0 ]; ubnd[ ic ] = ptr[ ic ][ 1 ]; /* Ensure we have a good upper bound for this axis. */ if( ubnd[ ic ] == AST__BAD ) { if( lbnd[ ic ] == AST__BAD ) { ubnd[ ic ] = 1.0; } else if( lbnd[ ic ] > 0.0 ) { ubnd[ ic ] = lbnd[ ic ]*1.01; } else if( lbnd[ ic ] < 0.0 ) { ubnd[ ic ] = lbnd[ ic ]*0.99; } else { ubnd[ ic ] = 1.0; } } /* Ensure we have a good lower bound for this axis. */ if( lbnd[ ic ] == AST__BAD ) { if( ubnd[ ic ] > 0.0 ) { lbnd[ ic ] = ubnd[ ic ]*0.99; } else if( ubnd[ ic ] < 0.0 ) { lbnd[ ic ] = ubnd[ ic ]*1.01; } else { lbnd[ ic ] = 1.0; } } } } /* Transform the box corners found above into the current frame and then back into the base Frame, and ensure that the box encloses both the original and the new bounds. PermMaps with fewer outputs than inputs can cause the resulting base Frame positions to differ significantly from the original. */ psetb =astPointSet( 2, nc,"", status ); ptrb =astGetPoints( psetb ); if( astOK ) { for( ic = 0; ic < nc; ic++ ) { ptrb[ ic ][ 0 ] = lbnd[ ic ]; ptrb[ ic ][ 1 ] = ubnd[ ic ]; } } psetc = astTransform( map, psetb, 1, NULL ); (void) astTransform( map, psetc, 0, psetb ); if( astOK ) { for( ic = 0; ic < nc; ic++ ) { lb = ptrb[ ic ][ 0 ]; if( lb != AST__BAD ) { if( lb < lbnd[ ic ] ) lbnd[ ic ] = lb; if( lb > ubnd[ ic ] ) ubnd[ ic ] = lb; } ub = ptrb[ ic ][ 1 ]; if( ub != AST__BAD ) { if( ub < lbnd[ ic ] ) lbnd[ ic ] = ub; if( ub > ubnd[ ic ] ) ubnd[ ic ] = ub; } } } psetb = astAnnul( psetb ); psetc = astAnnul( psetc ); /* Limit this box to not exceed the limits imposed by the Interval.*/ Cache( this_interval, status ); for( ic = 0; ic < nc; ic++ ) { lb = this_interval->lbnd[ ic ] ; ub = this_interval->ubnd[ ic ] ; if( lb <= ub ) { if( lbnd[ ic ] < lb ) { lbnd[ ic ] = lb; } else if( lbnd[ ic ] > ub ) { lbnd[ ic ] = ub; } if( ubnd[ ic ] < lb ) { ubnd[ ic ] = lb; } else if( ubnd[ ic ] > ub ) { ubnd[ ic ] = ub; } } else { lwid = lb - lbnd[ ic ]; uwid = ubnd[ ic ] - ub; if( lwid > uwid ) { if( lbnd[ ic ] > lb ) lbnd[ ic ] = lb; if( ubnd[ ic ] > lb ) ubnd[ ic ] = lb; } else { if( lbnd[ ic ] < ub ) lbnd[ ic ] = ub; if( ubnd[ ic ] < ub ) ubnd[ ic ] = ub; } } /* Ensure the bounds are not equal */ if( lbnd[ ic ] == 0.0 && ubnd[ ic ] == 0.0 ) { ubnd[ ic ] = 1.0; } else if( astEQUALS( lbnd[ ic ], ubnd[ ic ], 1.0E9 ) ) { ubnd[ ic ] = astMAX( ubnd[ ic ], lbnd[ ic ] )*( 1.0E6*DBL_EPSILON ); } } /* Create a new Box representing the box found above. */ bfrm = astGetFrame( new->frameset, AST__BASE ); unc = astTestUnc( new ) ? astGetUncFrm( new, AST__BASE ) : NULL; box = astBox( bfrm, 1, lbnd, ubnd, unc, "", status ); if( unc ) unc = astAnnul( unc ); /* Modify this Box so that it has the same current Frame as this Interval. */ cfrm = astGetFrame( new->frameset, AST__CURRENT ); box2 = astMapRegion( box, map, cfrm ); /* Try simplifying the Box. */ sreg = (AstRegion *) astSimplify( box2 ); /* Only proceed if the Box was simplified */ if( sreg != (AstRegion *) box2 ) { /* If the simplified Box is a NullRegion return it. */ if( astIsANullRegion( sreg ) ) { (void) astAnnul( new ); new = astClone( sreg ); simpler = 1; /* If the simplified Box is a Box or an Interval... */ } else if( astIsABox( sreg ) || astIsAInterval( sreg ) ) { /* Get the bounds of the simplified Box. We assume that the base and current Frames in the simplified Box are the same. */ snc = astGetNin( sreg->frameset ); slbnd = astMalloc( sizeof( double )*(size_t)snc ); subnd = astMalloc( sizeof( double )*(size_t)snc ); if( astIsAInterval( sreg ) ) { sptr = astGetPoints( sreg->points ); if( astOK ) { for( ic = 0; ic < snc; ic++ ) { slbnd[ ic ] = sptr[ ic ][ 0 ]; subnd[ ic ] = sptr[ ic ][ 1 ]; } } } else { astRegBaseBox( sreg, slbnd, subnd ); } /* Now create a PointSet containing one point for each axis in the current (or equivalently, base ) Frame of the simplified Box, plus an extra point. */ pset2 = astPointSet( snc + 1, snc, "", status ); ptr2 = astGetPoints( pset2 ); /* Put the lower bounds of the simplified Box into the first point in this PointSet. The remaining points are displaced from this first point along each axis in turn. The length of each displacement is determined by the length of the box on the axis. */ if( astOK ) { for( ic = 0; ic < snc; ic++ ) { for( jc = 0; jc < snc + 1; jc++ ) { ptr2[ ic ][ jc ] = slbnd[ ic ]; } ptr2[ ic ][ ic + 1 ] = subnd[ ic ]; } } /* Transform this PointSet into the base Frame of this Interval using the inverse of the base->current Mapping. */ pset3 = astTransform( map, pset2, 0, NULL ); ptr3 = astGetPoints( pset3 ); if( astOK ) { /* Now consider each axis of the Interval's current Frame (i.e. each base Frame axis in the simplified Box). */ for( ic = 0; ic < snc; ic++ ) { /* Given that the Box simplified succesfully, we know that there is a one to one connection between the axes of the base and current Frame in this Interval, but we do not yet know which base Frame axis corresponds to which current Frame axis (and the number of base and current Frame axes need not be equal). We have two points on a line parallel to current Frame axis number "ic" (points zero and "ic+1" in "pset2"). Look at the corresponding base Frame positions (in "pset3), and see which base Frame axis they are parallel to. We look for the largest base Frame axis increment (this allows small non-zero displacements to occur on the other axes due to rounding errors). */ maxd = -DBL_MAX; bax = -1; for( jc = 0; jc < nc; jc++ ) { d = fabs( astAxDistance( bfrm, jc + 1, ptr3[ jc ][ 0 ], ptr3[ jc ][ ic + 1 ] ) ); if( d != AST__BAD && d > maxd ) { maxd = d; bax = jc; } } /* If the largest base Frame axis increment is zero, it must mean that the current Frame axis is not present in the base Frame. The only plausable cause of this is if the base->current Mapping contains a PermMap which introduces an extra axis, in which case the axis will have a fixed value (any other Mapping arrangement would have prevented the Box from simplifying). Therefore, set upper and lower limits for this axis to the same value. */ if( maxd <= 0.0 ) { if( slbnd[ ic ] == AST__BAD || subnd[ ic ] == AST__BAD ) { slbnd[ ic ] = AST__BAD; } else { slbnd[ ic ] = 0.5*( slbnd[ ic ] + subnd[ ic ] ); } subnd[ ic ] = slbnd[ ic ]; /* If we have found a base Frame axis which corresponds to the current Frame axis "ic", then look to see which limits are specified for the base Frame axis, and transfer missing limits to the current Frame. */ } else { if( ptr[ bax ][ 0 ] == AST__BAD ) slbnd[ ic ] = AST__BAD; if( ptr[ bax ][ 1 ] == AST__BAD ) subnd[ ic ] = AST__BAD; /* If the original limits were equal, ensure the new limits are equal (the code above modified the upper limit to ensure it was different to the lower limit). */ if( ptr[ bax ][ 1 ] == ptr[ bax ][ 0 ] ) { subnd[ ic ] = slbnd[ ic ]; /* If the original interval was an inclusion (ubnd > lbnd), ensure the new interval is also an inclusion by swapping the limits if required. */ } else if( ptr[ bax ][ 1 ] > ptr[ bax ][ 0 ] ) { if( subnd[ ic ] < slbnd[ ic ] ) { tmp = subnd[ ic ]; subnd[ ic ] = slbnd[ ic ]; slbnd[ ic ] = tmp; } /* If the original interval was an exclusion (ubnd < lbnd), ensure the new interval is also an exlusion by swapping the limits if required. */ } else if( ptr[ bax ][ 1 ] < ptr[ bax ][ 0 ] ) { if( subnd[ ic ] > slbnd[ ic ] ) { tmp = subnd[ ic ]; subnd[ ic ] = slbnd[ ic ]; slbnd[ ic ] = tmp; } } } } /* Create the simplified Interval from the current Frame limits found above, and use it in place of the original. */ unc = astTestUnc( new ) ? astGetUncFrm( new, AST__CURRENT ) : NULL; (void) astAnnul( new ); new = (AstRegion *) astInterval( cfrm, slbnd, subnd, unc, "", status ); if( unc ) unc = astAnnul( unc ); simpler = 1; } /* Free resources */ pset2 = astAnnul( pset2 ); pset3 = astAnnul( pset3 ); slbnd = astFree( slbnd ); subnd = astFree( subnd ); } } /* Free resources */ bfrm = astAnnul( bfrm ); cfrm = astAnnul( cfrm ); box = astAnnul( box ); box2 = astAnnul( box2 ); sreg = astAnnul( sreg ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); } /* Free resources */ map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } } } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Interval to transform a set of points. * Type: * Private function. * Synopsis: * #include "interval.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Interval member function (over-rides the astTransform protected * method inherited from the Region class). * Description: * This function takes a Interval and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the Interval. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the Interval. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstBox *box; /* Pointer to equivalent Box */ AstInterval *this; /* Pointer to Interval structure */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ AstRegion *reg; /* Pointer to Region structure */ AstRegion *unc; /* Uncertainty Region */ double **ptr_lims; /* Pointer to limits array */ double **ptr_out; /* Pointer to output coordinate data */ double **ptr_tmp; /* Pointer to base Frame coordinate data */ double *lbnd_unc; /* Lower bounds of uncertainty Region */ double *ubnd_unc; /* Upper bounds of uncertainty Region */ double lb; /* Base Frame axis lower bound */ double p; /* Input base Frame axis value */ double ub; /* Base Frame axis upper bound */ double wid; /* Half width of uncertainy Region */ int coord; /* Zero-based index for coordinates */ int ncoord_out; /* No. of coordinates per output point */ int ncoord_tmp; /* No. of coordinates per base Frame point */ int neg; /* Has the Region been negated? */ int npoint; /* No. of points */ int pass; /* Does this point pass the axis test? */ int point; /* Loop counter for points */ int setbad; /* Set the output point bad? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain pointers to the Region and to the Interval. */ reg = (AstRegion *) this_mapping; this = (AstInterval *) this_mapping; /* If this Interval is equivalent to a Box, use the astTransform method of the equivalent Box. */ box = Cache( this, status ); if( box ) { result = astTransform( box, in, forward, out ); /* Otherwise, we use a new implementation appropriate for unbounded intervals. */ } else { /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). This call also returns a pointer to the base Frame of the encapsulated FrameSet. Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( reg, in, 0, NULL, NULL ); /* Determine the numbers of points and coordinates per point from the base Frame PointSet and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( pset_tmp ); ncoord_tmp = astGetNcoord( pset_tmp ); ptr_tmp = astGetPoints( pset_tmp ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* Get a pointer to the array of axis limits */ ptr_lims = astGetPoints( reg->points ); /* See if the Region is negated. */ neg = astGetNegated( reg ); /* Indicate we have not yet got the bounding box of the uncertainty Region. */ lbnd_unc = NULL; ubnd_unc = NULL; unc = NULL; /* Perform coordinate arithmetic. */ if ( astOK ) { /* First deal with closed unnegated Intervals. */ /* ------------------------------------------- */ if( astGetClosed( reg ) ) { if( !neg ) { /* Loop round each point. */ for ( point = 0; point < npoint; point++ ) { /* Assume this point is inside the Region. We change this flag when we find the first axis for which the point does not pass the axis test. */ setbad = 0; /* Loop round each base Frame axis */ Cache( this, status ); for ( coord = 0; coord < ncoord_tmp; coord++ ) { p = ptr_tmp[ coord ][ point ]; lb = (this->lbnd)[ coord ]; ub = (this->ubnd)[ coord ]; /* If the limits are equal separate them slightly to give some tolerance. */ if( lb == ub ) { /* If not yet done so, get the bounding box of the uncertainty Region in the base Frame of the Interval */ if( !unc ) { unc = astGetUncFrm( reg, AST__BASE ); lbnd_unc = astMalloc( sizeof( double)*(size_t) ncoord_tmp ); ubnd_unc = astMalloc( sizeof( double)*(size_t) ncoord_tmp ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); } /* Set the gap between the limits to be equal to the uincertainty on this axis. */ if( astOK ) { wid = 0.5*( ubnd_unc[ coord ] - lbnd_unc[ coord ] ); lb -= wid; ub += wid; } } /* Bad input points should always be bad in the output. */ if( p == AST__BAD ) { setbad = 1; break; /* Does the current axis value pass the limits test for this axis? */ } else if( lb <= ub ) { pass = ( lb <= p && p <= ub ); } else { pass = ( p <= ub || lb <= p ); } /* If this point does not pass the test for this axis, then indicate that we should set the resulting output point bad and break since we now have a definite value for the inside/outside flag. */ if( !pass ) { setbad = 1; break; } } /* Set the axis values bad for this output point if required. */ if( setbad ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } /* Now deal with closed negated Intervals. */ /* --------------------------------------- */ } else { /* Loop round each point. */ for ( point = 0; point < npoint; point++ ) { /* Assume this point is outside the negated Region (i.e. inside the unnegated Region). We change this flag when we find the first axis for which the point passes the axis test. */ setbad = 1; /* Loop round each base Frame axis */ Cache( this, status ); for ( coord = 0; coord < ncoord_tmp; coord++ ) { p = ptr_tmp[ coord ][ point ]; lb = (this->lbnd)[ coord ]; ub = (this->ubnd)[ coord ]; /* Bad input points should always be bad in the output. */ if( p == AST__BAD ) { setbad = 1; break; /* Does the current axis value pass the limits test for this axis? */ } else if( lb <= ub ) { pass = ( p <= lb || ub <= p ); } else { pass = ( ub <= p && p <= lb ); } /* If this point passes the test for this axis, then indicate that we should not set the resulting output point bad and break since we now have a definite value for the inside/outside flag. */ if( pass ) { setbad = 0; break; } } /* Set the axis values bad for this output point if required. */ if( setbad ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Now deal with open unnegated Intervals. */ /* --------------------------------------- */ } else { if( !neg ) { /* Loop round each point. */ for ( point = 0; point < npoint; point++ ) { /* Assume this point is inside the Region. We change this flag when we find the first axis for which the point does not pass the axis test. */ setbad = 0; /* Loop round each base Frame axis */ Cache( this, status ); for ( coord = 0; coord < ncoord_tmp; coord++ ) { p = ptr_tmp[ coord ][ point ]; lb = (this->lbnd)[ coord ]; ub = (this->ubnd)[ coord ]; /* Bad input points should always be bad in the output. */ if( p == AST__BAD ) { setbad = 1; break; /* Does the current axis value pass the limits test for this axis? */ } else if( lb <= ub ) { pass = ( lb < p && p < ub ); } else { pass = ( p < ub || lb < p ); } /* If this point does not pass the test for this axis, then indicate that we should set the resulting output point bad and break since we now have a definite value for the inside/outside flag. */ if( !pass ) { setbad = 1; break; } } /* Set the axis values bad for this output point if required. */ if( setbad ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } /* Now deal with open negated Intervals. */ /* ------------------------------------- */ } else { /* Loop round each point. */ for ( point = 0; point < npoint; point++ ) { /* Assume this point is outside the negated Region (i.e. inside the unnegated Region). We change this flag when we find the first axis for which the point passes the axis test. */ setbad = 1; /* Loop round each base Frame axis */ Cache( this, status ); for ( coord = 0; coord < ncoord_tmp; coord++ ) { p = ptr_tmp[ coord ][ point ]; lb = (this->lbnd)[ coord ]; ub = (this->ubnd)[ coord ]; /* If the limits are equal separate them slightly to give some tolerance. */ if( lb == ub ) { /* If not yet done so, get the bounding box of the uncertainty Region in the base Frame of the Interval */ if( !unc ) { unc = astGetUncFrm( reg, AST__BASE ); lbnd_unc = astMalloc( sizeof( double)*(size_t) ncoord_tmp ); ubnd_unc = astMalloc( sizeof( double)*(size_t) ncoord_tmp ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); } /* Set the gap between the limits to be equal to the uincertainty on this axis. */ if( astOK ) { wid = 0.5*( ubnd_unc[ coord ] - lbnd_unc[ coord ] ); lb -= wid; ub += wid; } } /* Bad input points should always be bad in the output. */ if( p == AST__BAD ) { setbad = 1; break; /* Does the current axis value pass the limits test for this axis? */ } else if( lb <= ub ) { pass = ( p < lb || ub < p ); } else { pass = ( ub < p && p < lb ); } /* If this point passes the test for this axis, then indicate that we should not set the resulting output point bad and break since we now have a definite value for the inside/outside flag. */ if( pass ) { setbad = 0; break; } } /* Set the axis values bad for this output point if required. */ if( setbad ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } } } /* Free resources */ pset_tmp = astAnnul( pset_tmp ); if( lbnd_unc ) lbnd_unc = astFree( lbnd_unc ); if( ubnd_unc ) ubnd_unc = astFree( ubnd_unc ); if( unc ) unc = astAnnul( unc ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Interval objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Region objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstInterval *in; /* Pointer to input Interval */ AstInterval *out; /* Pointer to output Interval */ size_t nb; /* Number of bytes in limits array */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Intervals. */ in = (AstInterval *) objin; out = (AstInterval *) objout; /* For safety, first clear any references to the input memory from the output Interval. */ out->box = NULL; out->lbnd = NULL; out->ubnd = NULL; /* Note the number of bytes in each limits array */ nb = sizeof( double )*(size_t) astGetNin( ((AstRegion *) in)->frameset ); /* Copy dynamic memory contents */ if( in->box ) out->box = astCopy( in->box ); out->lbnd = astStore( NULL, in->lbnd, nb ); out->ubnd = astStore( NULL, in->ubnd, nb ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Interval objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Interval 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: */ AstInterval *this; /* Pointer to Interval */ /* Obtain a pointer to the Interval structure. */ this = (AstInterval *) obj; /* Annul all resources. */ if( this->box ) this->box = astAnnul( this->box ); this->lbnd = astFree( this->lbnd ); this->ubnd = astFree( this->ubnd ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Interval 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 Interval class to an output Channel. * Parameters: * this * Pointer to the Interval 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 Variables: */ AstInterval *this; /* Pointer to the Interval structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Interval structure. */ this = (AstInterval *) this_object; /* Write out values representing the instance variables for the Interval 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAInterval and astCheckInterval functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Interval,Region) astMAKE_CHECK(Interval) AstInterval *astInterval_( void *frame_void, const double lbnd[], const double ubnd[], AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astInterval f AST_INTERVAL * Purpose: * Create a Interval. * Type: * Public function. * Synopsis: c #include "interval.h" c AstInterval *astInterval( AstFrame *frame, const double lbnd[], c const double ubnd[], AstRegion *unc, c const char *options, ... ) f RESULT = AST_INTERVAL( FRAME, LBND, UBND, UNC, OPTIONS, STATUS ) * Class Membership: * Interval constructor. * Description: * This function creates a new Interval and optionally initialises its * attributes. * * A Interval is a Region which represents upper and/or lower limits on * one or more axes of a Frame. For a point to be within the region * represented by the Interval, the point must satisfy all the * restrictions placed on all the axes. The point is outside the region * if it fails to satisfy any one of the restrictions. Each axis may have * either an upper limit, a lower limit, both or neither. If both limits * are supplied but are in reverse order (so that the lower limit is * greater than the upper limit), then the interval is an excluded * interval, rather than an included interval. * * At least one axis limit must be supplied. * * Note, The Interval class makes no allowances for cyclic nature of * some coordinate systems (such as SkyFrame coordinates). A Box * should usually be used in these cases since this requires the user * to think about suitable upper and lower limits, * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. c lbnd f LBND( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the lower limits on each axis. * Set a value to AST__BAD to indicate that the axis has no lower * limit. c ubnd f UBND( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the upper limits on each axis. * Set a value to AST__BAD to indicate that the axis has no upper * limit. c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with the boundary of the Interval being created. * The uncertainty in any point on the boundary of the Interval is found by * shifting the supplied "uncertainty" Region so that it is centred at * the boundary point being considered. The area covered by the * shifted uncertainty Region then represents the uncertainty in the * boundary position. The uncertainty is assumed to be the same for * all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Interval. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the Interval being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 Interval. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Interval. The syntax used is identical to that for the f AST_SET routine. 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 astInterval() f AST_INTERVAL = INTEGER * A pointer to the new Interval. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstInterval *new; /* Pointer to new Interval */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the Interval, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitInterval( NULL, sizeof( AstInterval ), !class_init, &class_vtab, "Interval", frame, lbnd, ubnd, unc ); /* 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 Interval'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 Interval. */ return new; } AstInterval *astIntervalId_( void *frame_void, const double lbnd[], const double ubnd[], void *unc_void, const char *options, ... ) { /* * Name: * astIntervalId_ * Purpose: * Create a Interval. * Type: * Private function. * Synopsis: * #include "interval.h" * AstInterval *astIntervalId_( AstFrame *frame, const double lbnd[], * const double ubnd[], AstRegion *unc, * const char *options, ... ) * Class Membership: * Interval constructor. * Description: * This function implements the external (public) interface to the * astInterval constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astInterval_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astInterval_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astInterval_. * Returned Value: * The ID value associated with the new Interval. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstInterval *new; /* Pointer to new Interval */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* 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 NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the Interval, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitInterval( NULL, sizeof( AstInterval ), !class_init, &class_vtab, "Interval", frame, lbnd, ubnd, unc ); /* 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 Interval'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 Interval. */ return astMakeId( new ); } AstInterval *astInitInterval_( void *mem, size_t size, int init, AstIntervalVtab *vtab, const char *name, AstFrame *frame, const double lbnd[], const double ubnd[], AstRegion *unc, int *status ) { /* *+ * Name: * astInitInterval * Purpose: * Initialise a Interval. * Type: * Protected function. * Synopsis: * #include "interval.h" * AstInterval *astInitInterval( void *mem, size_t size, int init, AstIntervalVtab *vtab, * const char *name, AstFrame *frame, * const double lbnd[], const double ubnd[], * AstRegion *unc ) * Class Membership: * Interval initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Interval object. It allocates memory (if necessary) to accommodate * the Interval plus any additional data associated with the derived class. * It then initialises a Interval 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 Interval at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Interval is to be initialised. * This must be of sufficient size to accommodate the Interval data * (sizeof(Interval)) 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 Interval (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 Interval * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Interval'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 Interval. * 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 * A pointer to the Frame in which the region is defined. * lbnd * An array of double, with one element for each Frame axis * (Naxes attribute) containing the lower limits on each axis. * Set a value to AST__BAD to indicate that the axis has no lower * limit. Upper and ower limits can be reversed to create an * excluded interval rather than an included interval. * ubnd * An array of double, with one element for each Frame axis * (Naxes attribute) containing the upper limits on each axis. * Set a value to AST__BAD to indicate that the axis has no upper * limit. * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points on the boundary of the new Interval * being initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal to * 1.0E-6 of the dimensions of the new Interval's bounding box are used. * If an uncertainty Region is supplied, it must be either a Box, a * Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new Interval. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstInterval *new; /* Pointer to new Interval */ AstPointSet *pset; /* PointSet to pass to Region initialiser */ double **ptr; /* Pointer to coords data in pset */ int i; /* Axis index */ int nc; /* No. of axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* If necessary, initialise the virtual function table. */ if ( init ) astInitIntervalVtab( &class_vtab, name ); /* Initialise. */ new = NULL; /* Get the number of axis values required for each position. */ nc = astGetNaxes( frame ); /* Create a PointSet to hold the upper and lower bounds, and get pointers to the data arrays. */ pset = astPointSet( 2, nc, "", status ); ptr = astGetPoints( pset ); if( astOK ) { /* Copy the limits into the PointSet. */ for( i = 0; i < nc; i++ ) { ptr[ i ][ 0 ] = lbnd[ i ]; ptr[ i ][ 1 ] = ubnd[ i ]; } /* Initialise a Region structure (the parent class) as the first component within the Interval structure, allocating memory if necessary. */ new = (AstInterval *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, pset, unc ); if ( astOK ) { /* Initialise the Interval data. */ /* ----------------------------- */ new->lbnd = NULL; new->ubnd = NULL; new->box = NULL; new->stale = 1; /* If an error occurred, clean up by deleting the new Interval. */ if ( !astOK ) new = astDelete( new ); } } /* Free resources. */ pset = astAnnul( pset ); /* Return a pointer to the new Interval. */ return new; } AstInterval *astLoadInterval_( void *mem, size_t size, AstIntervalVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadInterval * Purpose: * Load a Interval. * Type: * Protected function. * Synopsis: * #include "interval.h" * AstInterval *astLoadInterval( void *mem, size_t size, AstIntervalVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Interval loader. * Description: * This function is provided to load a new Interval 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 * Interval structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Interval at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Interval is to be * loaded. This must be of sufficient size to accommodate the * Interval data (sizeof(Interval)) 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 Interval (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 Interval 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(AstInterval) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Interval. If this is NULL, a pointer * to the (static) virtual function table for the Interval 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 "Interval" is used instead. * Returned Value: * A pointer to the new Interval. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstInterval *new; /* Pointer to the new Interval */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Interval. In this case the Interval belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstInterval ); vtab = &class_vtab; name = "Interval"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitIntervalVtab( 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 Interval. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Interval" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ new->lbnd = NULL; new->ubnd = NULL; new->box = NULL; new->stale = 1; /* If an error occurred, clean up by deleting the new Interval. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Interval pointer. */ return new; } /* 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 astIntervalPoints_( AstInterval *this, double *lbnd, double *ubnd, int *status) { if ( !astOK ) return; (**astMEMBER(this,Interval,IntervalPoints))( this, lbnd, ubnd, status ); return; } ast-8.3.0/plot3d.c0000664000175000017500000105421013004147321010603 00000000000000/* *class++ * Name: * Plot3D * Purpose: * Provide facilities for 3D graphical output. * Constructor Function: c astPlot3D f AST_PLOT3D * Description: * A Plot3D is a specialised form of Plot that provides facilities * for producing 3D graphical output, including fully annotated 3D * coordinate grids. The base Frame in a Plot3D describes a 3-dimensional * "graphical" coordinate system. The axes of this coordinate system are * assumed to be right-handed (that is, if X appears horizontally to the * right and Y vertically upwards, then Z is out of the screen towards * the viewer), and are assumed to be equally scaled (that is, the same * units are used to measure positions on each of the 3 axes). The upper * and lower bounds of a volume within this graphical coordinate system * is specified when the Plot3D is created, and all subsequent graphics * are "drawn" in this volume. * * The Plot3D class does not itself include any ability to draw on a * graphics device. Instead it calls upon function in an externally * supplied module (the "grf3d" module) to do the required drawing. * A module should be written that implements the functions of the * grf3d interface using the facilities of a specific graphics system * This module should then be linked into the application so that the * Plot3D class can use its functions (see the description of the * ast_link commands for details of how to do this). The grf3d interface * defines a few simple functions for drawing primitives such as straight * lines, markers and character strings. These functions all accept * positions in the 3D graphics coordinate system (the base Frame of the * Plot3D), and so the grf3d module must also manage the projection of * these 3D coordinates onto the 2D viewing surface, including the choice * of "eye"/"camera" position, direction of viewing, etc. The AST * library includes a sample implementation of the grf3d interface * based on the PGPLOT graphics system (see file grf3d_pgplot.c). This * implementation also serves to document the grf3d interface itself and * should be consulted for details before writing a new implementation. * * The current Frame of a Plot3D describes a "physical" 3-dimensional * coordinate system, which is the coordinate system in which plotting * operations are specified when invoking the methods of the Plot3D * class. The results of each plotting operation are automatically * transformed into 3D graphical coordinates before being plotted * using the facilities of the grf3d module linked into the application. * Note, at least one of the three axes of the current Frame must be * independent of the other two current Frame axes. * * You may select different physical coordinate systems in which to * plot (including the native graphical coordinate system itself) * by selecting different Frames as the current Frame of a Plot3D, * using its Current attribute. * * Like any FrameSet, a Plot3D may also be used as a Frame. In this * case, it behaves like its current Frame, which describes the * physical coordinate system. * * When used as a Mapping, a Plot3D describes the inter-relation * between 3D graphical coordinates (its base Frame) and 3D physical * coordinates (its current Frame). * * Although the Plot3D class inherits from the Plot class, several of * the facilities of the Plot class are not available in the Plot3D * class, and an error will be reported if any attempt is made to use * them. Specifically, the Plot3D class does not support clipping * using the * astClip function. f AST_CLIP routine. * Nor does it support the specification of graphics primitive functions * at run-time using the c astGrfSet, astGrfPop, astGrfPush and astGetGrfContext functions. f AST_GRFSET, AST_GRFPOP, AST_GRFPUSH, and AST_GETGRFCONTEXT routines. * Inheritance: * The Plot3D class inherits from the Plot class. * Attributes: * In addition to those attributes common to all Plots, every * Plot3D also has the following attributes: * * - Norm: Normal vector defining the 2D plane used for text and markers * - RootCorner: Specifies which edges of the 3D box should be annotated. * * Some attributes of the Plot class refer to specific physical * coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic * Plot, the axis index must be 1 or 2, but for a Plot3D the axis index * can be 1, 2 or 3. * * Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, * DrawTitle, TitleGap, etc). Consult the Plot attribute documentation * for details. All other Plot attributes can be set for a specific * plane of the 3-d plot by appending one of the strings "_XY", "_XZ" * or "_YZ" to the end of the Plot attribute name. For instance, * "Grid_YZ" refers to the "Grid" attribute for the plane spanning * the second (Y) and third (Z) axes of the 3-d plot. * Functions: c The Plot3D class does not define any new functions beyond those f The Plot3D class does not define any new routines beyond those * which are applicable to all Plots. Note, however, that the * following methods inherited from the Plot class cannot be used with * a Plot3D and will report an error if called: c - astBoundingBox, astClip, astCurve, astGenCurve, c astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, astGridLine, c astPolyCurve. f - AST_BOUNDINGBOX, AST_CLIP, AST_CURVE, AST_GENCURVE, f AST_GETGRFCONTEXT, AST_GRFPOP, AST_GRFPUSH, AST_GRFSET, f AST_GRIDLINE, AST_POLYCURVE. * Copyright: * Copyright (C) 2007 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 6-JUN-2007 (DSB): * Original version. * 6-SEP-2007 (DSB): * Re-code the astGrid function. * 12-NOV-2007 (DSB): * Clear up compiler warnings. * 4-MAY-2012 (DSB): * Avoid segvio in Grid if no ticks are drawn. * 21-MAY-2012 (DSB): * In astLoadPlot3D, do not call SetRootCorner as it requires an * active graphics system to be present which may not yet have been * established. Also establish the grf routines to be used. * 5-OCT-2015 (DSB): * Allow Plot attributes to be set for specific planes. *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 Plot3D /* Integers identifying the 3 plotting surfaces */ #define XY 1 #define XZ 2 #define YZ 3 /* Integers identifying the 8 corners of the graphics cube. */ #define LLL 0 #define ULL 1 #define LUL 2 #define UUL 3 #define LLU 4 #define ULU 5 #define LUU 6 #define UUU 7 /* Identify the 4 edges of a Plot */ #define LEFT 0 #define TOP 1 #define RIGHT 2 #define BOTTOM 3 /* A macros that returns a pointer to the Plot that spans a given plane. */ #define GET_PLOT(plane) ( \ ( plane == XY ) ? this->plotxy : ( \ ( plane == XZ ) ? this->plotxz : ( \ ( plane == YZ ) ? this->plotyz : NULL ) ) ) /* * * Name: * MAKE_CLEAR3 * Purpose: * Implement a method to clear a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_CLEAR3(attr,component,assign,nval) * Class Membership: * Defined by the Plot3D class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPlot *this, int axis ) * * and an external interface function of the form: * * void astClear_( AstPlot *this, int axis ) * * which implement a method for clearing a single value in a specified * multi-valued attribute for an axis of a Plot3D. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearLabelAt"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR3(attr,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPlot3D *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astClear" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Assign the "clear" value. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attr##_( AstPlot3D *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Plot3D,Clear##attr))( this, axis, status ); \ } /* * * Name: * MAKE_GET3 * Purpose: * Implement a method to get a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_GET3(attr,type,bad_value,assign,nval) * Class Membership: * Defined by the Plot3D class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstPlot3D *this, int axis ) * * and an external interface function of the form: * * astGet_( AstPlot3D *this, int axis ) * * which implement a method for getting a single value from a specified * multi-valued attribute for an axis of a Plot3D. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. This can * use the string "axis" to represent the zero-based value index. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET3(attr,type,bad_value,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attr( AstPlot3D *this, int axis, int *status ) { \ type result; /* Result to be returned */ \ \ /* Initialise */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astGet" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attr##_( AstPlot3D *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Plot3D,Get##attr))( this, axis, status ); \ } /* * * Name: * MAKE_SET3 * Purpose: * Implement a method to set a single value in a multi-valued attribute * for a Plot3D. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_SET3(attr,type,component,assign,nval) * Class Membership: * Defined by the Plot3D class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot3D *this, int axis, value ) * * and an external interface function of the form: * * void astSet_( AstPlot3D *this, int axis, value ) * * which implement a method for setting a single value in a specified * multi-valued attribute for a Plot3D. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. LabelAt in "astSetLabelAt"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot3D's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET3(attr,type,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPlot3D *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astSet" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Store the new value in the structure component. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attr##_( AstPlot3D *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Plot3D,Set##attr))( this, axis, value, status ); \ } /* * * Name: * MAKE_TEST3 * Purpose: * Implement a method to test if a single value has been set in a * multi-valued attribute for a class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_TEST3(attr,assign,nval) * Class Membership: * Defined by the Plot3D class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( AstPlot3D *this, int axis ) * * and an external interface function of the form: * * int astTest_( AstPlot3D *this, int axis ) * * which implement a method for testing if a single value in a specified * multi-valued attribute has been set for a class. * Parameters: * attr * The name of the attribute to be tested, as it appears in the function * name (e.g. LabelAt in "astTestLabelAt"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. This can use the string "axis" to represent the zero-based * index of the value within the attribute. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_TEST3(attr,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attr( AstPlot3D *this, int axis, int *status ) { \ int result; /* Value to return */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astTest" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attr##_( AstPlot3D *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Plot3D,Test##attr))( this, axis, status ); \ } /* * * Name: * MAKE_CLEAR2 * Purpose: * Implement a method to clear an element-specific attribute inherited * from the Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_CLEAR2(attr) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPlot *this, int element ) * * which implements a method for clearing one of the element-specific * attributes (e.g. Size, Colour, Width, etc) inherited from the * parent Plot class. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearSize"). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR2(attr) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPlot *this_plot, int element, int *status ) { \ \ /* Local Variables: */ \ AstPlot3D *this; \ int axis3d; \ int elem2d1; \ int elem2d2; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Clear the attribute value in the parent Plot structure. */ \ (*parent_clear##attr)( this_plot, element, status ); \ \ /* If OK, clear the attribute in the encapsulated Plots. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ \ /* Get the zero-based index of the 3D axis to which the supplied element \ refers. Use an index of -1 to indicate that the element does not \ relate to a specific axis. Also get the corresponding elements to use \ with the two Plots that share the specified 3D axis. */ \ axis3d = Element2D( this, element, &elem2d1, &elem2d2, status ); \ \ /* If the element is not axis-specific, clear the attribute value in all \ three plots. */ \ if( axis3d == -1 ) { \ astClear##attr( this->plotxy, element ); \ astClear##attr( this->plotxz, element ); \ astClear##attr( this->plotyz, element ); \ \ /* Otherwise, clear the attribute in the two plots that share the \ specified 3D axis. */ \ } else { \ astClear##attr( GET_PLOT(this->axis_plot1[ axis3d ]), elem2d1 ); \ astClear##attr( GET_PLOT(this->axis_plot2[ axis3d ]), elem2d2 ); \ } \ } \ } /* * * Name: * MAKE_SET2 * Purpose: * Implement a method to set an element-specific attribute inherited * from the Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_SET2(attr,type) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot *this, int element, type value ) * * which implements a method for setting one of the element-specific * attributes (e.g. Size, Colour, Width, etc) inherited from the * parent Plot class. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearSize"). * type * The attribute data type. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_SET2(attr,type) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPlot *this_plot, int element, type value, int *status ) { \ \ /* Local Variables: */ \ AstPlot3D *this; \ int axis3d; \ int elem2d1; \ int elem2d2; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Set the attribute value in the parent Plot structure. */ \ (*parent_set##attr)( this_plot, element, value, status ); \ \ /* If OK, set the attribute in the encapsulated Plots. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ \ /* Get the zero-based index of the 3D axis to which the supplied element \ refers. Use an index of -1 to indicate that the element does not \ relate to a specific axis. Also get the corresponding elements to use \ with the two Plots that share the specified 3D axis. */ \ axis3d = Element2D( this, element, &elem2d1, &elem2d2, status ); \ \ /* If the element is not axis-specific, clear the attribute value in all \ three plots. */ \ if( axis3d == -1 ) { \ astSet##attr( this->plotxy, element, value ); \ astSet##attr( this->plotxz, element, value ); \ astSet##attr( this->plotyz, element, value ); \ \ /* Otherwise, clear the attribute in the two plots that share the \ specified 3D axis. */ \ } else { \ astSet##attr( GET_PLOT(this->axis_plot1[ axis3d ]), elem2d1, value ); \ astSet##attr( GET_PLOT(this->axis_plot2[ axis3d ]), elem2d2, value ); \ } \ } \ } /* * * Name: * MAKE_CLEAR1 * Purpose: * Implement a method to clear an attribute inherited from the Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_CLEAR1(attr) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPlot *this ) * * which implements a method for clearing a Plot3D attribute inherited * from the parent Plot class. It clears the attribute in all three * plots encapsulated within the Plot3D. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearLabelAt"). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR1(attr) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPlot *this_plot, int *status ) { \ \ /* Local Variables: */ \ AstPlot3D *this; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Clear the attribute value in the parent Plot structure. */ \ (*parent_clear##attr)( this_plot, status ); \ \ /* If OK, clear the attribute in all three of the encapsulated Plots. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ astClear##attr( this->plotxy ); \ astClear##attr( this->plotxz ); \ astClear##attr( this->plotyz ); \ } \ } /* * * Name: * MAKE_SET1 * Purpose: * Implement a method to set an attribute inherited from the Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_SET1(attr,type) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot *this, type value ) * * which implements a method for setting a Plot3D attribute inherited * from the parent Plot class. It sets the attribute in all three * plots encapsulated within the Plot3D. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. LabelAt in "astSetLabelAt"). * type * The C data type for the attribute value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_SET1(attr,type) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPlot *this_plot, type value, int *status ) { \ \ /* Local Variables: */ \ AstPlot3D *this; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Set the attribute value in the parent Plot structure. */ \ (*parent_set##attr)( this_plot, value, status ); \ \ /* If OK, set the attribute in all three of the encapsulated Plots. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ astSet##attr( this->plotxy, value ); \ astSet##attr( this->plotxz, value ); \ astSet##attr( this->plotyz, value ); \ } \ } /* * * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear an attribute inherited from the Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_CLEAR(attr,whichplots) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPlot *this, int axis ) * * which implements a method for clearing an axis specific Plot3D * attribute inherited from the parent Plot class. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearLabelAt"). * whichplots * A value indicating which Plots should be affected. A negative value * means "all threee plots", a value of zero means "just the two plots * that touch at the specified axis in 3D space", a positive value * means "just the Plot that is used to label th 3D axis." * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR(attr,whichplots) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPlot *this_plot, int axis, int *status ) { \ \ /* Local Variables: */ \ AstPlot *plot; \ AstPlot3D *this; \ int axis2d; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Clear the attribute value in the parent Plot structure. This will \ validate the axis index. */ \ (*parent_clear##attr)( this_plot, axis, status ); \ \ /* If OK, clear the attribute for the relevant axis, or axes, of the Plots \ encapsulated inside the Plot3D. First get a pointer to the Plot3D \ structure. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ \ /* If requested clear the attribute in all three Plots. */ \ if( whichplots < 0 ) { \ astClear##attr( this->plotxy, axis ); \ astClear##attr( this->plotxz, axis ); \ astClear##attr( this->plotyz, axis ); \ \ /* Each axis in 3D graphics space is described by two of the encapsulated \ Plots, but only one of these two Plots is used to generate labels for \ the axis. Now deal with cases where we are clearing the attribute \ value in both of the two Plots that describe the axis. */ \ } else if ( whichplots == 0 ) { \ if( axis == 0 ) { \ astClear##attr( this->plotxy, 0 ); \ astClear##attr( this->plotxz, 0 ); \ \ } else if( axis == 1 ) { \ astClear##attr( this->plotxy, 1 ); \ astClear##attr( this->plotyz, 0 ); \ \ } else { \ astClear##attr( this->plotxz, 1 ); \ astClear##attr( this->plotyz, 1 ); \ } \ \ /* Now deal with cases where we are clearing the attribute value only in \ the Plot that is used to label the axis. */ \ } else { \ plot = AxisPlot( this, axis, &axis2d, status ); \ astClear##attr( plot, axis2d ); \ } \ } \ } /* * * Name: * MAKE_GET * Purpose: * Implement a method to get the value of an attribute inherited from the * Plot class. * Type: * Private macro. * Synopsis: * #include "plot.h" * MAKE_GET(attr,type,bad_value) * Class Membership: * Defined by the Plot3D class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstPlot *this, int axis ) * * which implements a method for getting a value for an axis specific * attribute for a Plot3D. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET(attr,type,bad_value) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attr( AstPlot *this_plot, int axis, int *status ) { \ \ /* Local Variables: */ \ AstPlot *plot; \ AstPlot3D *this; \ int axis2d; \ type result; \ \ /* Initialise */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* See if the attribute value is set in the parent Plot structure. If so, \ use the parent get method to get its value. */ \ if( astTest##attr( this_plot, axis ) ) { \ result = (*parent_get##attr)( this_plot, axis, status ); \ \ /* If the attribute value is not set in the parent Plot structure, get \ the default value from the Plot that is used to label the 3D axis. The \ parent test method called above will have reported an error if the axis \ index is invalid, so check astOK here. */ \ } else if( astOK ) { \ this = (AstPlot3D *) this_plot; \ plot = AxisPlot( this, axis, &axis2d, status ); \ result = astGet##attr( plot, axis2d ); \ } \ \ /* Return the result. */ \ return result; \ } /* * * Name: * MAKE_SET * Purpose: * Implement a method to set a value for an attribute inherited from the * Plot class. * Type: * Private macro. * Synopsis: * #include "plot3d.h" * MAKE_SET(attr,type,whichplots) * Class Membership: * Defined by the Plot3d class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot *this, int axis, value ) * * which implements a method for setting a value for an axis specific * attribute inherited from the parent Plot class. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. LabelAt in "astSetLabelAt"). * type * The C type of the attribute. * whichplots * A value indicating which Plots should be affected. A negative value * means "all threee plots", a value of zero means "just the two plots * that touch at the specified axis in 3D space", a positive value * means "just the Plot that is used to label the 3D axis." * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET(attr,type,whichplots) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPlot *this_plot, int axis, type value, int *status ) { \ \ /* Local Variables: */ \ AstPlot3D *this; \ AstPlot *plot; \ int axis2d; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Set the supplied value in the parent Plot class. This will validate \ the axis index. */ \ (*parent_set##attr)( this_plot, axis, value, status ); \ \ /* If this went OK, also set the value for the appropriate axis of the \ appropriate encapsulated Plot(s). First get a pointer to the Plot3D \ structure. */ \ if( astOK ) { \ this = (AstPlot3D *) this_plot; \ \ /* If requested set the attribute in all three Plots. */ \ if( whichplots < 0 ) { \ astSet##attr( this->plotxy, axis, value ); \ astSet##attr( this->plotxz, axis, value ); \ astSet##attr( this->plotyz, axis, value ); \ \ /* Each axis in 3D graphics space is described by two of the encapsulated \ Plots, but only one of these two Plots is used to generate labels for \ the axis. First deal with cases where we are setting the attribute \ value in both of the two Plots that describe the axis. */ \ } else if( whichplots == 0 ) { \ if( axis == 0 ) { \ astSet##attr( this->plotxy, 0, value ); \ astSet##attr( this->plotxz, 0, value ); \ \ } else if( axis == 1 ) { \ astSet##attr( this->plotxy, 1, value ); \ astSet##attr( this->plotyz, 0, value ); \ \ } else { \ astSet##attr( this->plotxz, 1, value ); \ astSet##attr( this->plotyz, 1, value ); \ } \ \ /* Now deal with cases where we are setting the attribute value only in \ the Plot that is used to label the axis. */ \ } else { \ plot = AxisPlot( this, axis, &axis2d, status ); \ astSet##attr( plot, axis2d, value ); \ } \ } \ } /* 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 "cmpframe.h" /* Compound Frames */ #include "cmpmap.h" /* Compound Mappings */ #include "unitmap.h" /* Unit mappings */ #include "permmap.h" /* Axis permutations */ #include "winmap.h" /* Scale and shift mappings */ #include "frame.h" /* Coordinate systems */ #include "frameset.h" /* Inter-related coordinate systems */ #include "keymap.h" /* Hash array */ #include "plot.h" /* Interface definition for parent class */ #include "plot3d.h" /* Interface definition for this class */ #include "grf3d.h" /* The grf3D interface */ #include "pointset.h" /* Sets of points */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* 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 used or extended by this class. */ static AstObject *(* parent_cast)( AstObject *, AstObject *, int * ); static void (* parent_removeframe)( AstFrameSet *, int, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_equal)( AstObject *, AstObject *, int * ); static void (* parent_vset)( AstObject *, const char *, char **, va_list, int * ); static void (* parent_clear)( AstObject *, const char *, int * ); static void (* parent_clearcurrent)( AstFrameSet *, int * ); static void (* parent_setcurrent)( AstFrameSet *, int, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* A FrameSet pointer that is used when calling astCast. */ static AstFrameSet *dummy_frameset = NULL; #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Plot3D) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Plot3D,Class_Init) #define class_vtab astGLOBAL(Plot3D,Class_Vtab) #define getattrib_buff astGLOBAL(Plot3D,GetAttrib_Buff) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); static pthread_mutex_t mutex3 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX3 pthread_mutex_lock( &mutex3 ); #define UNLOCK_MUTEX3 pthread_mutex_unlock( &mutex3 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPlot3DVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #define LOCK_MUTEX3 #define UNLOCK_MUTEX3 #endif /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstFrameSet *Fset3D( AstFrameSet *, int, int * ); static AstKeyMap *GetGrfContext( AstPlot *, int * ); static AstObject *Cast( AstObject *, AstObject *, int * ); static AstPlot *AxisPlot( AstPlot3D *, int, int *, int * ); static AstPointSet *ExtendTicks( AstPlot *, AstPointSet *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *RootCornerString( int, int * ); static int Attr3D( AstKeyMap *, int, double, double *, int, int * ); static int Border( AstPlot *, int * ); static int Element2D( AstPlot3D *, int, int *, int *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetObjSize( AstObject *, int * ); static int Plot3DAttr( AstKeyMap *, int, double, double *, int ); static int Plot3DCap( AstKeyMap *, int, int ); static int Plot3DFlush( AstKeyMap * ); static int Plot3DLine( AstKeyMap *, int, const float *, const float * ); static int Plot3DMark( AstKeyMap *, int, const float *, const float *, int ); static int Plot3DQch( AstKeyMap *, float *, float * ); static int Plot3DScales( AstKeyMap *, float *, float * ); static int Plot3DText( AstKeyMap *, const char *, float, float, const char *, float, float ); static int Plot3DTxExt( AstKeyMap *, const char *, float, float, const char *, float, float, float *, float * ); static int RootCornerInt( const char *, int * ); static void BoundingBox( AstPlot *, float[2], float[2], int * ); static void ChangeRootCorner( AstPlot3D *, int, int, int * ); static void Clear( AstObject *, const char *, int * ); static void ClearCurrent( AstFrameSet *, int * ); static void Clip( AstPlot *, int, const double [], const double [], int * ); static void Copy( const AstObject *, AstObject *, int * ); static void CreatePlots( AstPlot3D *, AstFrameSet *, const float *, const double *, int * ); static void Curve( AstPlot *, const double [], const double [], int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void GenCurve( AstPlot *, AstMapping *, int * ); static void GrfPop( AstPlot *, int * ); static void GrfPush( AstPlot *, int * ); static void GrfSet( AstPlot *, const char *, AstGrfFun, int * ); static void Grid( AstPlot *, int * ); static void GridLine( AstPlot *, int, const double [], double, int * ); static void Mark( AstPlot *, int, int, int, const double *, int, int * ); static void PolyCurve( AstPlot *, int, int, int, const double *, int * ); static void RemoveFrame( AstFrameSet *, int, int * ); static void Set3DGrf( AstPlot3D *, AstPlot *, int, int * ); static void SetCurrent( AstFrameSet *, int, int * ); static void SetPlotAttr( AstPlot *, int, int[ 2 ], int * ); static void SetTickValues( AstPlot *, int, int, double *, int, double *, int * ); static void SplitFrameSet( AstFrameSet *, AstFrameSet **, int[2], int[2], AstFrameSet **, int[2], int[2], AstFrameSet **, int[2], int[2], int *, int * ); static void StoreAxisInfo( AstPlot3D *, int[2], int[2], int[2], int[2], int[2], int[2], int * ); static void Text( AstPlot *, const char *, const double [], const float [2], const char *, int * ); static void UpdatePlots( AstPlot3D *, int * ); static void VSet( AstObject *, const char *, char **, va_list, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Declare private member functions that access Plot3D attributes. --------------------------------------------------------------*/ /* Axis independent... */ #define DECLARE_PLOT3D_ACCESSORS(attr,type) \ static type Get##attr(AstPlot3D *,int *); \ static void Set##attr(AstPlot3D *,type,int *); \ static void Clear##attr(AstPlot3D *,int *); \ static int Test##attr(AstPlot3D *,int *); DECLARE_PLOT3D_ACCESSORS(RootCorner,int) #undef DECLARE_PLOT3D_ACCESSORS /* Axis specific... */ #define DECLARE_PLOT3D_ACCESSORS(attr,type) \ static type Get##attr(AstPlot3D *,int,int *); \ static void Set##attr(AstPlot3D *,int,type,int *); \ static void Clear##attr(AstPlot3D *,int,int *); \ static int Test##attr(AstPlot3D *,int,int *); DECLARE_PLOT3D_ACCESSORS(Norm,double) #undef DECLARE_PLOT3D_ACCESSORS /* Declare private member functions that access axis-specific attributes inherited from the Plot class. Also declare pointers to hold the parent function pointers. ----------------------------------------------------------------------*/ #define DECLARE_PLOT_ACCESSORS(attr,type) \ static type Get##attr(AstPlot *,int,int *); \ static void Set##attr(AstPlot *,int,type,int *); \ static void Clear##attr(AstPlot *,int,int *); \ static type (*parent_get##attr)(AstPlot *,int,int *); \ static void (*parent_set##attr)(AstPlot *,int,type,int *); \ static void (*parent_clear##attr)(AstPlot *,int,int *); DECLARE_PLOT_ACCESSORS(MinTick,int) DECLARE_PLOT_ACCESSORS(Abbrev,int) DECLARE_PLOT_ACCESSORS(Gap,double) DECLARE_PLOT_ACCESSORS(LogGap,double) DECLARE_PLOT_ACCESSORS(LogPlot,int) DECLARE_PLOT_ACCESSORS(LogTicks,int) DECLARE_PLOT_ACCESSORS(LogLabel,int) DECLARE_PLOT_ACCESSORS(LabelUp,int) DECLARE_PLOT_ACCESSORS(DrawAxes,int) DECLARE_PLOT_ACCESSORS(LabelUnits,int) DECLARE_PLOT_ACCESSORS(MinTickLen,double) DECLARE_PLOT_ACCESSORS(MajTickLen,double) DECLARE_PLOT_ACCESSORS(NumLab,int) DECLARE_PLOT_ACCESSORS(NumLabGap,double) DECLARE_PLOT_ACCESSORS(TextLab,int) DECLARE_PLOT_ACCESSORS(TextLabGap,double) #undef DECLARE_PLOT_ACCESSORS /* Declare private member functions that access element-specific attributes inherited from the Plot class. Also declare pointers to hold the parent function pointers. ----------------------------------------------------------------------*/ #define DECLARE_PLOT_ACCESSORS(attr,type) \ static void Set##attr(AstPlot *,int,type,int *); \ static void Clear##attr(AstPlot *,int,int *); \ static void (*parent_set##attr)(AstPlot *,int,type,int *); \ static void (*parent_clear##attr)(AstPlot *,int,int *); DECLARE_PLOT_ACCESSORS(Style,int) DECLARE_PLOT_ACCESSORS(Font,int) DECLARE_PLOT_ACCESSORS(Colour,int) DECLARE_PLOT_ACCESSORS(Width,double) DECLARE_PLOT_ACCESSORS(Size,double) #undef DECLARE_PLOT_ACCESSORS /* Declare private member functions that access attributes inherited from the Plot class that do not need to override the Get method. This includes attributes that are not axis-specific or that do not have dynamic defaults. Also declare pointers to hold the parent function pointers. ----------------------------------------------------------------------*/ #define DECLARE_PLOT_ACCESSORS(attr,type) \ static void Set##attr(AstPlot *,type,int *); \ static void Clear##attr(AstPlot *,int *); \ static void (*parent_set##attr)(AstPlot *,type,int *); \ static void (*parent_clear##attr)(AstPlot *,int *); DECLARE_PLOT_ACCESSORS(Ink,int) DECLARE_PLOT_ACCESSORS(Tol,double) DECLARE_PLOT_ACCESSORS(Invisible,int) DECLARE_PLOT_ACCESSORS(TickAll,int) DECLARE_PLOT_ACCESSORS(ForceExterior,int) DECLARE_PLOT_ACCESSORS(Border,int) DECLARE_PLOT_ACCESSORS(Clip,int) DECLARE_PLOT_ACCESSORS(ClipOp,int) DECLARE_PLOT_ACCESSORS(Escape,int) DECLARE_PLOT_ACCESSORS(Grid,int) DECLARE_PLOT_ACCESSORS(Labelling,int) #undef DECLARE_PLOT_ACCESSORS /* Member functions. */ /* ================= */ static int Attr3D( AstKeyMap *grfconID, int attr, double value, double *old_value, int prim, int *status ){ /* * Name: * Attr3D * Purpose: * Get or set the value of a 3D grf attribute. * Type: * Private function. * Synopsis: * #include "plot3d.h" * Attr3D( AstKeyMap *grfconID, int attr, double value, double *old_value, * int prim, int *status ) * Class Membership: * Plot3D member function. * Description: * This function gets or sets the current value of a specified graphics * attribute in the parent Plot structure of a Plot3D. It forwards the * call to the grf3D module being used by this Plot3D. It should be * registered with the parent Plot using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. * attr * An integer value identifying the required attribute. This should * be one of the symbolic values defined in grf.h. * value * A new value to store for the attribute. If this is AST__BAD * no value is stored. * old_value * A pointer to a double in which to return the attribute value. * If this is NULL, no value is returned. * prim * The sort of graphics primitive to be drawn with the new attribute. * Identified by one of the values defined in grf.h. * status * Pointer to the inherited status variable. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ int result; /* Check the inherited status. */ if( !astOK ) return 0; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Use the function in the external Grf3D module, selected at link-time using ast_link options. */ result = astG3DAttr( attr, value, old_value, prim ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Return the result. */ return result; } static AstPlot *AxisPlot( AstPlot3D *this, int axis3d, int *axis2d, int *status ){ /* * Name: * AxisPlot * Purpose: * Find the Plot used to label a 3D axis. * Type: * Private function. * Synopsis: * #include "plot3d.h" * AstPlot *AxisPlot( AstPlot3D *this, int axis3d, int *axis2d, int *status ) * Class Membership: * Plot method. * Description: * This function returns a pointer to the encapsulated 2D Plot that * is used to label the given 3D axis. It also returns the index * of the labelled axis within the 2D Plot. * Parameters: * this * Pointer to a Plot3D. * axis3d * A zero-based axis index within the Plot3D. * axis2d * Pointer to an int in which to put the index of the labelled axis * within the returned 2D Plot. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Plot used to label the 3D axis. Do not annul this * pointer. *- */ /* Local Variables: */ AstPlot *plot; /* Check the global status. */ if( !astOK ) return NULL; /* Return the required information form the Plot3D structure. */ plot = GET_PLOT( this->axis_plot1[ axis3d ] ); if( ! plot ) { astError( AST__INTER, "AxisPlot(Plot3D): Illegal value %d " "for axis3d (internal AST programming error).", status, this->axis_plot1[ axis3d ] ); } *axis2d = this->axis_index1[ axis3d ]; return plot; } static int Border( AstPlot *this_plot, int *status ){ /* * Name: * Border * Purpose: * Draw a border around valid regions of a Plot. * Type: * Private member function. * Synopsis: * #include "plot3d.h" * int Border( AstPlot *this, int *status ) * Class Membership: * Plot method (overrides the astBorder method inherited from the * Plot class) * Description: * This function draws a (line) border around regions of the * plotting area of a Plot which correspond to valid, unclipped * physical coordinates. For example, when plotting using an * all-sky map projection, this function could be used to draw the * boundary of the celestial sphere when it is projected on to the * plotting surface. * * If the entire plotting area contains valid, unclipped physical * coordinates, then the boundary will just be a rectangular box * around the edges of the plotting area. * Parameters: * this * Pointer to the Plot. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the plotting area is completely filled by * valid, unclipped physical coordinates (so that only a * rectangular box was drawn around the edge). Otherwise, one is * returned. * Notes: * - The Plot3D implementation of this method, invokes the astBorder * method on each of the three encapsulated Plots, and returns the * logical OR of the three returned flags. * - A value of zero will be returned if this function is invoked * with the AST error status set, or if it should fail for any * reason. * - An error results if either the current Frame or the base Frame * of the Plot is not 2-dimensional, or (for a Plot3D) 3-dimensional. * - An error also results if the transformation between the base * and current Frames of the Plot is not defined (i.e. the Plot's * TranForward attribute is zero). */ /* Local Variables: */ AstPlot3D *this; const char *class; const char *method; float x1; float y1; float z1; float x[ 2 ]; float y[ 2 ]; float z[ 2 ]; int flag1; int flag2; int flag3; int naxes; int ok; int result; int root_corner; /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_plot; /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astBorder"; class = astGetClass( this ); /* Check the base Frame of the Plot is 3-D. */ naxes = astGetNin( this ); if( naxes != 3 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 3.", status, method, class, naxes, class ); } /* Check the current Frame of the Plot is 3-D. */ naxes = astGetNout( this ); if( naxes != 3 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the current " "Frame of the supplied %s is invalid - this number should " "be 3.", status, method, class, naxes, class ); } /* Invoke the astBorder method on each of the three encapsulated Plots. */ flag1 = astBorder( this->plotxy ); flag2 = astBorder( this->plotxz ); flag3 = astBorder( this->plotyz ); /* If no bad values were encountered in any of the Plots, draw lines along the remaining plot edges. */ result = ( flag1 || flag2 || flag3 ); if( !result ) { /* The three remaining edges ot be drawn all meet at the corner diagonally opposite the root corner. Get the root corner. */ root_corner = astGetRootCorner( this ); /* The (x0,y0,z0) position is the graphics coords at the corner diagonally opposite the root corner. The x1, y1 and z1 values are the graphics x, y and z values at the ends of the three lines that remain to be drawn. */ if( root_corner & 1 ) { x[ 0 ] = this->gbox[ 0 ]; x1 = this->gbox[ 3 ]; } else { x[ 0 ] = this->gbox[ 3 ]; x1 = this->gbox[ 0 ]; } if( root_corner & 2 ) { y[ 0 ] = this->gbox[ 1 ]; y1 = this->gbox[ 4 ]; } else { y[ 0 ] = this->gbox[ 4 ]; y1 = this->gbox[ 1 ]; } if( root_corner & 4 ) { z[ 0 ] = this->gbox[ 2 ]; z1 = this->gbox[ 5 ]; } else { z[ 0 ] = this->gbox[ 5 ]; z1 = this->gbox[ 2 ]; } /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__BORDER_ID, 1, GRF__LINE, method, class ); /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Draw the remaining line parallel to the X axis. */ x[ 1 ] = x1; y[ 1 ] = y[ 0 ]; z[ 1 ] = z[ 0 ]; ok = astG3DLine( 2, x, y, z ); /* Draw the remaining line parallel to the Y axis. */ x[ 1 ] = x[ 0 ]; y[ 1 ] = y1; z[ 1 ] = z[ 0 ]; ok = ok && astG3DLine( 2, x, y, z ); /* Draw the remaining line parallel to the X axis. */ x[ 1 ] = x[ 0 ]; y[ 1 ] = y[ 0 ]; z[ 1 ] = z1; ok = ok && astG3DLine( 2, x, y, z ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__BORDER_ID, 0, GRF__LINE, method, class ); /* Report an error if anything went wrong in the grf3d module. */ if( !ok && astOK ) { astError( AST__GRFER, "%s(%s): Graphics error in astG3DLine. ", status, method, class ); } } /* Return zero if an error has occurrred. */ if( !astOK ) result = 0; /* Return a flag indicating if any bad values were encountered in any of the Plots. */ 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 "plot3d.h" * AstObject *Cast( AstObject *this, AstObject *obj, int *status ) * Class Membership: * Plot3D 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; */ 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 (Plot3D). A positive value is returned if Plot3D is a sub-class of "obj". A negative value is returned if "obj" is a sub-class of Plot3D. Zero is returned if "obj" is a Plot3D. AST__COUSIN is returned if "obj" is not on the same line of descent as Plot3D. */ generation_gap = astClassCompare( (AstObjectVtab *) &class_vtab, astVTAB( obj ) ); /* If "obj" is a Plot3D or a sub-class of Plot3D, 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 a Plot (the parent class), we cast by returning a deep copy of the Plot covering the XY face. */ } else if( generation_gap == 1 ) { new = astCopy( ( (AstPlot3D *) this_object)->plotxy ); /* If "obj" is a FrameSet or higher, we attempt to use the implementation inherited from the parent class to cast the FrameSet component into the class indicated by "obj". */ } else { new = (*parent_cast)( this_object, obj, status ); } /* Return the new pointer. */ return new; } static void ChangeRootCorner( AstPlot3D *this, int old, int new, int *status ){ /* * Name: * ChangeRootCorner * Purpose: * Use a new RootCorner value. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void ChangeRootCorner( AstPlot3D *this, int old, int new, int *status ) * Class Membership: * Plot method. * Description: * This function sets the attributes of the encapsulated Plots so that * labels appear on the edges of the 3D graphics cube that join at the * specified new root corner. It also reverses the graphics axes in * the encapsulated Plots as required in order to ensure that the Plots * look "normal" when viewed from the outside of the 3D graphics cube. * This happens if a the Plot used to label a specific axis moves from * one face the the 3D graphics cube to the opposite face. * Parameters: * this * Pointer to a Plot3D. * old * The old RootCorner value. * new * The new RootCorner value. * status * Pointer to the inherited status variable. * Notes: * - Each RootCorner value is in the range 0 to 7 and is a 3 bit * bit-mask. Bit 0 describes the 3D graphics X axis, bit 1 describes * the graphics Y axis and bit 2 describes the graphics Z axis. If a * bit is set it means that the corner is at the upper bound on the * corresponding axis. If a bit is unset it means that the corner is * at the lower bound on the corresponding axis. *- */ /* Local Variables: */ AstKeyMap *grfcon; AstPlot *plot; AstPlot *plots[ 24 ]; int edges[ 24 ]; int axes[ 24 ]; int axis2d; int edge; int i; int np; int xeqy; int xeqz; /* Check the global status. */ if( !astOK ) return; /* If the corner has moved on the 3D X axis (from upper X bound to lower X bound or vice-versa), mirror the axis of the encapsulated Plot that is perpendicular to the 3D X axis. This means that the Plot can be thought of as being viewed from the outside of the 3D graphics cube. Also, update the constant X axis value at which the YZ plane is drawn. */ if( ( old & 1 ) != ( new & 1 ) ) astMirror( this->plotyz, 0 ); grfcon = (AstKeyMap *) astGetGrfContext( this->plotyz ); astMapPut0D( grfcon, "Gcon", this->gbox[ ( new & 1 ) ? 3 : 0 ], "Constant X value" ); astMapPut0I( grfcon, "RootCorner", new, "Labelled corner" ); grfcon= astAnnul( grfcon ); /* Likewise mirror the other two axes if required. */ if( ( old & 2 ) != ( new & 2 ) ) astMirror( this->plotxz, 0 ); grfcon = (AstKeyMap *) astGetGrfContext( this->plotxz ); astMapPut0D( grfcon, "Gcon", this->gbox[ ( new & 2 ) ? 4 : 1 ], "Constant Y value" ); astMapPut0I( grfcon, "RootCorner", new, "Labelled corner" ); grfcon= astAnnul( grfcon ); if( ( old & 4 ) != ( new & 4 ) ) astMirror( this->plotxy, 0 ); grfcon = (AstKeyMap *) astGetGrfContext( this->plotxy ); astMapPut0D( grfcon, "Gcon", this->gbox[ ( new & 4 ) ? 5 : 2 ], "Constant Z value" ); astMapPut0I( grfcon, "RootCorner", new, "Labelled corner" ); grfcon= astAnnul( grfcon ); /* Set a flag saying whether the limits are equal at the new corner for the X and Y axes. */ xeqy = ( ( ( new & 1 ) > 0 ) == ( ( new & 2 ) > 0 ) ); /* Set a flag saying whether the limits are equal at the new corner for the X and Z axes. */ xeqz = ( ( ( new & 1 ) > 0 ) == ( ( new & 4 ) > 0 ) ); /* Ensure all Edge attributes are clear. This means that the public attribute accessors routines used below will return dynamic defaults for the Edge attributes. */ astClearEdge( this->plotxy, 0 ); astClearEdge( this->plotxy, 1 ); astClearEdge( this->plotxz, 0 ); astClearEdge( this->plotxz, 1 ); astClearEdge( this->plotyz, 0 ); astClearEdge( this->plotyz, 1 ); /* So far we have recorded no edges changes. */ np = 0; /* We now adjust the Edge attributes in the Plot used to annotate the 3D X axis in order to get the X axis labels on the correct edge of the 3D graphics cube. Get the Plot used to produce X axis labels (this will be either this->plotxy or this->plotxz). */ plot = AxisPlot( this, 0, &axis2d, status ); /* See what edge of the Plot is used to annotate the first of the two WCS axis described by the 2D Plot. If the Edge(1) attribute has not been assigned a value, then a dynamic default will be used by the Plot class. We want to know what this dynamic default is, so we first cleared the attribute above. Now we set the attribute value explicitly to the dynamic default returned by astGetC. Note, we use astGetC rather than astGetEdge because the dynamic default is not calculated when calling astGetEdge. */ astSetC( plot, "Edge(1)", astGetC( plot, "Edge(1)" )); edge = astGetEdge( plot, 0 ); astClearEdge( plot, 0 ); /* If the 3D X axis is labelled using the Plot that spans the XY plane... */ if( plot == this->plotxy ) { /* ... and if the new root corner is at the upper limit on the Y axis... */ if( new & 2 ) { /* If the first WCS axis is currently labelled on either the top or bottom edge, ensure it is labelled on the upper Y (top) edge. */ if( edge == 3 || edge == 1 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = TOP; /* Otherwise ensure that the second WCS axis is labelled on the upper Y (top) edge. */ } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = TOP; } /* If the new root corner is at the lower limit on the Y axis... */ } else { /* If the first WCS axis is currently labelled on either the top or bottom edge, ensure it is labelled on the lower Y (bottom) edge. */ if( edge == 3 || edge == 1 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = BOTTOM; /* Otherwise ensure that the second WCS axis is labelled on the lower Y (bottom) edge. */ } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = BOTTOM; } } /* If the 3D X axis is labelled using the Plot that spans the XZ plane... */ } else { /* ... and if the new root corner is at the upper limit on the Z axis... */ if( new & 4 ) { /* If the first WCS axis is currently labelled on either the top or bottom edge, ensure it is labelled on the upper Z (top) edge. */ if( edge == 3 || edge == 1 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = TOP; /* Otherwise ensure that the second WCS axis is labelled on the upper Y (top) edge. */ } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = TOP; } /* If the new root corner is at the lower limit on the Z axis... */ } else { /* If the first WCS axis is currently labelled on either the top or bottom edge, ensure it is labelled on the lower Z (bottom) edge. */ if( edge == 3 || edge == 1 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = BOTTOM; /* Otherwise ensure that the second WCS axis is labelled on the lower Z (bottom) edge. */ } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = BOTTOM; } } } /* We now adjust the Edge attributes in the Plot used to annotate the 3D Y axis in order to get the Y axis labels on the correct edge of the 3D graphics cube. Get the Plot used to produce Y axis labels. */ plot = AxisPlot( this, 1, &axis2d, status ); /* See what edge of the Plot is used to annotate the first of the two WCS axis described by the Plot. */ astSetC( plot, "Edge(1)", astGetC( plot, "Edge(1)" )); edge = astGetEdge( plot, 0 ); astClearEdge( plot, 0 ); /* If the 3D Y axis is labelled using the Plot that spans the XY plane... */ if( plot == this->plotxy ) { /* ... and if the new root corner is at the same limit on the X and Z axes, put Y labels on the right side of the Plot. */ if( xeqz ) { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = RIGHT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = RIGHT; } /* If the new root corner is at a different limit on the X and Z axes, put Y labels on the left side of the Plot. */ } else { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = LEFT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = LEFT; } } /* If the 3D Y axis is labelled using the Plot that spans the YZ plane... */ } else { /* ... and if the new root corner is at the upper Z limit, put Y labels on the top of the Plot. */ if( new & 4 ) { if( edge == 1 || edge == 3 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = TOP; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = TOP; } /* If the new root corner is at the lower Z limit, put Y labels on the bottom of the Plot. */ } else { if( edge == 1 || edge == 3 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = BOTTOM; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = BOTTOM; } } } /* We now adjust the Edge attributes in the Plot used to annotate the 3D Z axis in order to get the Z axis labels on the correct edge of the 3D graphics cube. Get the Plot used to produce Z axis labels. */ plot = AxisPlot( this, 2, &axis2d, status ); /* See what edge of the Plot is used to annotate the first of the two WCS axis described by the Plot. */ astSetC( plot, "Edge(1)", astGetC( plot, "Edge(1)" )); edge = astGetEdge( plot, 0 ); astClearEdge( plot, 0 ); /* If the 3D Z axis is labelled using the Plot that spans the XZ plane... */ if( plot == this->plotxz ) { /* ... and if the new root corner is at the same limit on the X and Y axes, put Z labels on the left side of the Plot. */ if( xeqy ) { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = LEFT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = LEFT; } /* If the new root corner is at a different limit on the X and Y axes, put Y labels on the right side of the Plot. */ } else { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = RIGHT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = RIGHT; } } /* If the 3D Z axis is labelled using the Plot that spans the YZ plane... */ } else { /* ... and if the new root corner is at the same limit on the X and Y axes, put Z labels on the right side of the Plot. */ if( xeqz ) { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = RIGHT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = RIGHT; } /* If the new root corner is at a different limit on the X and Y axes, put Y labels on the left side of the Plot. */ } else { if( edge == 0 || edge == 2 ) { plots[ np ] = plot; axes[ np ] = 0; edges[ np++ ] = LEFT; } else { plots[ np ] = plot; axes[ np ] = 1; edges[ np++ ] = LEFT; } } } /* Apply the set of edge changes determined above. */ for( i = 0; i < np; i++ ) { astSetEdge( plots[ i ], axes[ i ], edges[ i ] ); } /* Ensure that the 2 Plot axes that are not being used have suitable values for their attributes. That is, no labels are drawn, and the ticked edges are the one that meet at the new RootCorner. */ if( !astTestEdge( this->plotxy, 0 ) ) { astSetEdge( this->plotxy, 0, ( new & 2 ) ? TOP : BOTTOM ); } if( !astTestEdge( this->plotxy, 1 ) ) { astSetEdge( this->plotxy, 1, xeqz ? RIGHT: LEFT ); } if( !astTestEdge( this->plotxz, 0 ) ) { astSetEdge( this->plotxz, 0, ( new & 4 ) ? TOP : BOTTOM ); } if( !astTestEdge( this->plotxz, 1 ) ) { astSetEdge( this->plotxz, 1, xeqy ? LEFT : RIGHT ); } if( !astTestEdge( this->plotyz, 0 ) ) { astSetEdge( this->plotyz, 0, ( new & 4 ) ? TOP : BOTTOM ); } if( !astTestEdge( this->plotyz, 1 ) ) { astSetEdge( this->plotyz, 1, xeqy ? RIGHT : LEFT ); } } static void Clear( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * Clear * Purpose: * Clear attribute values for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void Clear( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot3D 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 Plot3D. 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 Plot3D. * 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 Plot3D (if * possible) by appropriately modifying the three encapsulated Plots. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent astClear method to clear the Plot3D's attribute values. */ (*parent_clear)( this_object, attrib, status ); /* Update the three 2D Plots stored in the Plot3D structure so that they reflect this modified FrameSet. */ UpdatePlots( (AstPlot3D *) this_object, status ); } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot.h" * void ClearAttrib( AstObject *this, const char *attrib ) * Class Membership: * Plot3D member function (over-rides the astClearAttrib protected * method inherited from the Plot class). * Description: * This function clears the value of a specified attribute for a * Plot3D, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Plot3D. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. */ /* Local Variables: */ AstPlot3D *this; /* Pointer to the Plot3D structure */ AstPlot *plot; /* Pointer to specific Plot */ char attname[50]; /* Plot attribute base name */ char patt[50]; /* Plot attribute full name */ char spec[10]; /* Plane specification */ int axis; /* Axis index */ int len; /* Length of attrib string */ int nc; /* Number of characters read */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* Norm. */ /* ----------- */ if ( !strcmp( attrib, "norm" ) ) { astClearNorm( this, 0 ); astClearNorm( this, 1 ); astClearNorm( this, 2 ); /* Norm(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "norm(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearNorm( this, axis - 1 ); /* RootCorner. */ /* ----------- */ } else if ( !strcmp( attrib, "rootcorner" ) ) { astClearRootCorner( this ); /* ..._XY etc */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( attrib, "%[a-z]_%[xyz]%n", attname, spec, &nc ) ) ) { if( !strcmp( spec, "xy" ) || !strcmp( spec, "yx" ) ) { plot = this->plotxy; } else if( !strcmp( spec, "xz" ) || !strcmp( spec, "zx" ) ) { plot = this->plotyz; } else if( !strcmp( spec, "yz" ) || !strcmp( spec, "zy" ) ) { plot = this->plotxz; } else { plot = NULL; } if( plot ) { sprintf( patt, "%s%s", attname, attrib + nc ); astClearAttrib( plot, patt ); } else { (*parent_clearattrib)( this_object, attrib, status ); } /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearCurrent( AstFrameSet *this_frameset, int *status ) { /* * Name: * ClearCurrent * Purpose: * Clear the value of the Current attribute for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int astClearCurrent( AstFrameSet *this ) * Class Membership: * Plot3D member function (over-rides the public astClearCurrent method * inherited from the FrameSet class). * Description: * This function clears the value of the Current attribute for a * Plot3D. This attribute is an index that identifies the current * Frame for the Plot3D. * Parameters: * this * Pointer to the Plot3D. */ /* Invoke the parent astClearCurrent method. */ (*parent_clearcurrent)( this_frameset, status ); /* Update the three 2D Plots stored in the Plot3D structure so that they reflect this modified FrameSet. */ UpdatePlots( (AstPlot3D *) this_frameset, status ); } static void ClearRootCorner( AstPlot3D *this, int *status ){ /* *+ * Name: * astClearRootCorner * Purpose: * Clear the RootCorner attribute. * Type: * Protected virtual function. * Synopsis: * #include "plot3d.h" * void astClearRootCorner( AstPlot3D *this ) * Class Membership: * Plot method. * Description: * This function clears the RootCorner attribute. * Parameters: * this * Pointer to a Plot3D. *- */ /* Local Variables: */ int old; int new; /* Check the global status. */ if( !astOK ) return; /* Get the current rootcorner value. */ old = astGetRootCorner( this ); /* Clear the RootCorner attribute. */ this->rootcorner = -1; /* Get the new (default) rootcorner value. */ new = astGetRootCorner( this ); /* If the root corner has changed, mirror any axes of the encapsulated Plots that need mirroring (this is done to ensure that Plots look right when viewed from the outside of the graphics cube), and modify the Edge attributes in the encapsulated Plots to ensure the labels appear on the requested edges of the 3D graphics cube. . */ if( old != new ) ChangeRootCorner( this, old, new, status ); } static void CreatePlots( AstPlot3D *this, AstFrameSet *fset, const float *gbox, const double *bbox, int *status ) { /* * Name: * CreatePlots * Purpose: * Create three 2D plots and store in the Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void CreatePlots( AstPlot3D *this, AstFrameSet *fset, const float *gbox, const double *bbox, int *status ) * Class Membership: * Plot3D method. * Description: * This function splits the supplied FrameSet up into 3 independent 2D * FrameSets, each describing a 2D plane in the supplied 3D FrameSet. * It then uses these 2D FrameSets to create three Plots, one for each * plane in the graphics plotting space, and stores them in the Plot3D. * * Each of the three Plots is notionally pasted onto one face of the * 3D graphics cube (the RootCorner attribute is used to determine which * of the two parallel faces a particular Plot is pasted onto). The * Plot is pasted in such a way that, when viewed from the outside of * the graphics cube, the first graphics axis increases left to right * and the second increases bottom to top (this assumes that "up" is * parallel to the 3D Z axis). * * Initially, the Plots are created assuming the default RootCorner * value ("LLL"). They will be changed later if the value of the * RootCorner attribute is changed. * Parameters: * this * Pointer to the Plot3D. * fset * Pointer to the FrameSet. * gbox * A pointer to an array of 6 values giving the graphics coordinates * of the bottom left and top right corners of a box on the graphics * output device. The first triple of values should be the graphics * coordinates of the bottom left corner of the box and the second * triple of values are the graphics coordinates of the top right corner. * bbox * A pointer to an array of 6 values giving the coordinates in the * supplied Frame or base Frame of the supplied FrameSet at the bottom * left and top right corners of the box specified by parameter gbox. * These should be supplied in the same order as for parameter "gbox". * status * Pointer to the inherited status variable. * Notes: * - Each returned plot has 3 Frames: Frame 1 is the base (GRAPHICS) * Frame; Frame 2 is spanned by 2 of the 3 axes in the base Frame of * the supplied FrameSet; Frame 3 is the current Frame and is spanned * by 2 of the 3 axes in the current Frame of the supplied FrameSet. * Any future changes to this function that alter this structure should * reflected in equivalent changes to function UpdatePlots. */ /* Local Variables: */ AstFrameSet *fsetxy; AstFrameSet *fsetxz; AstFrameSet *fsetyz; double basebox2d[ 4 ]; float graphbox2d[ 4 ]; int baseplane; int labelxy[ 2 ]; int labelxz[ 2 ]; int labelyz[ 2 ]; int wcsxy[ 2 ]; int wcsxz[ 2 ]; int wcsyz[ 2 ]; /* Check the inherited status. */ if( !astOK ) return; /* Split the supplied FrameSet up into 3 FrameSets, each with a 2D base and current Frame. Each of these FrameSets describes one plane of the 3D cube. One of them will be spanned by two axes picked from the supplied 3D FrameSet. The other two FrameSets will each include a copy of the remaining 3rd axis from the supplied FrameSet, plus an extra dummy axis. These dummy axes will never be labelled. */ SplitFrameSet( fset, &fsetxy, labelxy, wcsxy, &fsetxz, labelxz, wcsxz, &fsetyz, labelyz, wcsyz, &baseplane, status ); /* If OK, annul any existing 2D plots. */ if( astOK ) { if( this->plotxy ) this->plotxy = astAnnul( this->plotxy ); if( this->plotxz ) this->plotxz = astAnnul( this->plotxz ); if( this->plotyz ) this->plotyz = astAnnul( this->plotyz ); /* Create three Plots; one for each 2D plane in the graphics plotting space. Set the attributes of these plots so that the required axes are labelled and other axes are left blank. The "graphbox2d" and "basebox2d" values used to create each Plot define the sense, as well as the extent, of each axis. The first pair of values in each give the lower left corner of the Plot and the second pair give the top right corner. We want each Plot to have X increasing left to right and Y increasing bottom to top when viewed from the outside of the cube. We assume an initial RootCorner value of "LLL" (that is, the Plots are pasted onto the cube faces that meet at the lower limit on every axis). */ graphbox2d[ 0 ] = gbox[ 3 ]; graphbox2d[ 1 ] = gbox[ 1 ]; graphbox2d[ 2 ] = gbox[ 0 ]; graphbox2d[ 3 ] = gbox[ 4 ]; basebox2d[ 0 ] = bbox[ 3 ]; basebox2d[ 1 ] = bbox[ 1 ]; basebox2d[ 2 ] = bbox[ 0 ]; basebox2d[ 3 ] = bbox[ 4 ]; if( this->plotxy ) this->plotxy = astAnnul( this->plotxy ); this->plotxy = astPlot( fsetxy, graphbox2d, basebox2d, "", status ); SetPlotAttr( this->plotxy, XY, labelxy, status ); graphbox2d[ 0 ] = gbox[ 0 ]; graphbox2d[ 1 ] = gbox[ 2 ]; graphbox2d[ 2 ] = gbox[ 3 ]; graphbox2d[ 3 ] = gbox[ 5 ]; basebox2d[ 0 ] = bbox[ 0 ]; basebox2d[ 1 ] = bbox[ 2 ]; basebox2d[ 2 ] = bbox[ 3 ]; basebox2d[ 3 ] = bbox[ 5 ]; this->plotxz = astPlot( fsetxz, graphbox2d, basebox2d, "", status ); SetPlotAttr( this->plotxz, XZ, labelxz, status ); graphbox2d[ 0 ] = gbox[ 4 ]; graphbox2d[ 1 ] = gbox[ 2 ]; graphbox2d[ 2 ] = gbox[ 1 ]; graphbox2d[ 3 ] = gbox[ 5 ]; basebox2d[ 0 ] = bbox[ 4 ]; basebox2d[ 1 ] = bbox[ 2 ]; basebox2d[ 2 ] = bbox[ 1 ]; basebox2d[ 3 ] = bbox[ 5 ]; this->plotyz = astPlot( fsetyz, graphbox2d, basebox2d, "", status ); SetPlotAttr( this->plotyz, YZ, labelyz, status ); /* Store information that allows each 3D WCS axis to be associatedf with a pair of Plots. Also store the WCS axis within each Plot that corresponds to the 3D WCS axis. */ StoreAxisInfo( this, labelxy, wcsxy, labelxz, wcsxz, labelyz, wcsyz, status ); /* Store the Plot that spans two connected 3D axes. */ this->baseplot = baseplane; /* Free resources */ fsetxy = astAnnul( fsetxy ); fsetxz = astAnnul( fsetxz ); fsetyz = astAnnul( fsetyz ); } } static int Element2D( AstPlot3D *this, int element, int *elem2d1, int *elem2d2, int *status ){ /* * Name: * Element2D * Purpose: * Convert a 3D graphics element identifier to a corresponding pair of * 2D identifiers. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Element2D( AstPlot3D *this, int element, int *elem2d1, * int *elem2d2, int *status ) * Class Membership: * Plot3D method. * Description: * This function takes an integer identifier for an element of a 3D * annotated grid (e.g. ticks, axis 1 labels, border, etc), and returns * a element identifers that can be used with the encapsualted 2D Plots. * Parameters: * this * Pointer to the Plot2D structure. * element * The 3D element identifier to convert. * elem2d1 * Pointer to an int in which to return the 2D element identifier * to use with the first of the two Plots that span the axis to * which the 3D element identifier refers. Returned holding 0 if * the given 3D element identifier is not axis specific. * elem2d2 * Pointer to an int in which to return the 2D element identifier * to use with the second of the two Plots that span the axis to * which the 3D element identifier refers. Returned holding 0 if * the given 3D element identifier is not axis specific. * status * Pointer to the inherited status variable. * Returned Value: * The zero-based index of the 3D axis to which the given element * identifier refers, or -1 if the element identifier is not axis * specific. */ /* Local Variables: */ int axis3d; /* Check the global error status. */ if ( !astOK ) return 0; /* Get the zero-based index of the 3D axis to which the supplied element refers. Use an index of -1 to indicate that the element does not relate to a specific axis. Also get the corresponding element to use with the two Plots that share the speified 3D axis. */ /* Define a macro used to set the 2d element identifiers for a given 3d element identifier. */ #define SET_ELEM2D(id1,id2) \ *elem2d1 = this->axis_index1[ axis3d ] ? id2 : id1; \ *elem2d2 = this->axis_index2[ axis3d ] ? id2 : id1; if( element == AST__BORDER_ID ){ axis3d = -1; } else if( element == AST__CURVE_ID ){ axis3d = -1; } else if( element == AST__TITLE_ID ){ axis3d = -1; } else if( element == AST__MARKS_ID ){ axis3d = -1; } else if( element == AST__TEXT_ID ){ axis3d = -1; } else if( element == AST__AXIS1_ID ){ axis3d = 0; SET_ELEM2D(AST__AXIS1_ID,AST__AXIS2_ID) } else if( element == AST__AXIS2_ID ){ axis3d = 1; SET_ELEM2D(AST__AXIS1_ID,AST__AXIS2_ID) } else if( element == AST__AXIS3_ID ){ axis3d = 2; SET_ELEM2D(AST__AXIS1_ID,AST__AXIS2_ID) } else if( element == AST__NUMLAB1_ID ){ axis3d = 0; SET_ELEM2D(AST__NUMLAB1_ID,AST__NUMLAB2_ID) } else if( element == AST__NUMLAB2_ID ){ axis3d = 1; SET_ELEM2D(AST__NUMLAB1_ID,AST__NUMLAB2_ID) } else if( element == AST__NUMLAB3_ID ){ axis3d = 2; SET_ELEM2D(AST__NUMLAB1_ID,AST__NUMLAB2_ID) } else if( element == AST__TEXTLAB1_ID ){ axis3d = 0; SET_ELEM2D(AST__TEXTLAB1_ID,AST__TEXTLAB2_ID) } else if( element == AST__TEXTLAB2_ID ){ axis3d = 1; SET_ELEM2D(AST__TEXTLAB1_ID,AST__TEXTLAB2_ID) } else if( element == AST__TEXTLAB3_ID ){ axis3d = 2; SET_ELEM2D(AST__TEXTLAB1_ID,AST__TEXTLAB2_ID) } else if( element == AST__TICKS1_ID ){ axis3d = 0; SET_ELEM2D(AST__TICKS1_ID,AST__TICKS2_ID) } else if( element == AST__TICKS2_ID ){ axis3d = 1; SET_ELEM2D(AST__TICKS1_ID,AST__TICKS2_ID) } else if( element == AST__TICKS3_ID ){ axis3d = 2; SET_ELEM2D(AST__TICKS1_ID,AST__TICKS2_ID) } else if( element == AST__GRIDLINE1_ID ){ axis3d = 0; SET_ELEM2D(AST__GRIDLINE1_ID,AST__GRIDLINE2_ID) } else if( element == AST__GRIDLINE2_ID ){ axis3d = 1; SET_ELEM2D(AST__GRIDLINE1_ID,AST__GRIDLINE2_ID) } else if( element == AST__GRIDLINE3_ID ){ axis3d = 2; SET_ELEM2D(AST__GRIDLINE1_ID,AST__GRIDLINE2_ID) } else { axis3d = 0; astError( AST__INTER, "Element2D(Plot3D): The MAKE_CLEAR2 macro " "does not yet support element index %d (internal " "AST programming error).", status, element ); } #undef SET_ELEM2D return axis3d; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Plot3Ds are equivalent. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * Plot3D member function (over-rides the astEqual protected * method inherited from the Plot Object class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Plot3Ds are equivalent. * Parameters: * this * Pointer to the first Plot3D. * that * Pointer to the second Plot3D. * status * Pointer to the inherited status variable. * Returned Value: * One if the Plot3Ds are equivalent, zero otherwise. * 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: */ AstPlot3D *that; /* Pointer to the second Plot3D structure */ AstPlot3D *this; /* Pointer to the first Plot3D structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the Equal method inherited from the parent Plot class. This checks that the Plots are both of the same class (amongst other things). */ if( (*parent_equal)( this_object, that_object, status ) ) { /* Obtain pointers to the two Plot3D structures. */ this = (AstPlot3D *) this_object; that = (AstPlot3D *) that_object; /* Check the encapsulated Plots for equality. */ result = ( astEqual( this->plotxz, that->plotxz ) && astEqual( this->plotyz, that->plotyz ) && astEqual( this->plotxy, that->plotxy ) ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static AstPointSet *ExtendTicks( AstPlot *plot, AstPointSet *ticks, int *status ){ /* * Name: * ExtendTicks * Purpose: * Add an extra tick to the start and end of a list of tick marks. * Type: * Private function. * Synopsis: * #include "plot3d.h" * AstPointSet *ExtendTicks( AstPlot *plot, AstPointSet *ticks, int *status ) * Class Membership: * Plot3D method. * Description: * This function takes a list of tick marks drawn using the supplied * Plot, and adds in an extra tick mark at the start and end of the * supplied list of ticks, returning the expanded list in a new * PointSet. The extra points are guaranteed to fall outside the area * enclosed within the supplied Plot. * Parameters: * plot * The Plot that was used to generate the list of tick marks. * ticks * A PointSet holding the 2D graphics coordinates (within the base * Frame of the supplied Plot) at which each tick mark starts. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a new PointSet that has 2 more entries than the * supplied PointSet. The first point is a new tick mark, then comes * all the ticks mark positions supplied in "ticks", and finally there * is another new tick mark. */ /* Local Variables: */ AstPointSet *result; double **ptr_in; double **ptr_out; double *a_in; double *a_out; double *b_in; double *b_out; double *p; double delta; double hi; double lo; double range[ 2 ]; double v; int axis; int i; int increasing; int np; /* Check inherited status */ if( !astOK || !ticks ) return NULL; /* Get the number of tick marsk in the supplied PointSet and get pointers to the 3D Graphics values contained in the PointSet. */ np = astGetNpoint( ticks ); ptr_in = astGetPoints( ticks ); /* Create the returned PointSet with room for an extra pair of ticks. Get pointers to its data arrays */ result = astPointSet( np + 2, 2, "", status ); ptr_out = astGetPoints( result ); /* Check the pointers can be used safely. */ if( astOK ) { /* Find the index of the 2D graphics axis (0 or 1) that varies along the set of tick marks. We do this by finding the max and min value supplied for each axis, and then choosing the axis that has the highest range. */ for( axis = 0; axis < 2; axis++ ) { hi = -DBL_MAX; lo = DBL_MAX; p = ptr_in[ axis ]; for( i = 0; i < np; i++, p++ ) { v = *p; if( v != AST__BAD ) { if( v > hi ) hi = v; if( v < lo ) lo = v; } } if( lo != DBL_MAX ) { range[ axis ] = hi - lo; } else { astError( AST__INTER, "ExtendTicks{Plot3D): no good ticks on " "axis %d (internal AST prgramming error).", status, axis ); } } /* Get the index of the axis with the largest range (the other range should be zero). */ axis = ( range[ 0 ] > range[ 1 ] ) ? 0 : 1; /* Copy the input graphics positions to the output PointSet, and add an extra position at the beginning and end of the output PointSet. */ if( axis == 0 ) { lo = plot->xlo; hi = plot->xhi; a_in = ptr_in[ 0 ]; b_in = ptr_in[ 1 ]; a_out = ptr_out[ 0 ]; b_out = ptr_out[ 1 ]; } else { lo = plot->ylo; hi = plot->yhi; a_in = ptr_in[ 1 ]; b_in = ptr_in[ 0 ]; a_out = ptr_out[ 1 ]; b_out = ptr_out[ 0 ]; } delta = 0.2*( hi - lo ); if( a_in[ 0 ] < a_in[ 1 ] ) { increasing = 1; *(a_out++) = lo - delta; } else { increasing = 0; *(a_out++) = hi + delta; } *(b_out++) = *b_in; for( i = 0; i < np; i++ ) { *(a_out++) = *(a_in++); *(b_out++) = *(b_in++); } *(b_out++) = b_in[ -1 ]; if( increasing ) { *(a_out++) = hi + delta; } else { *(a_out++) = lo - delta; } } /* Return the extended PointSet. */ return result; } static AstFrameSet *Fset3D( AstFrameSet *fset, int ifrm, int *status ) { /* * Name: * Fset3D * Purpose: * Create a FrameSet with no more than 3 dimensions for a given Frame. * Type: * Private function. * Synopsis: * #include "plot3d.h" * AstFrameSet *Fset3D( AstFrameSet *fset, int ifrm, int *status ) * Class Membership: * Plot3D method. * Description: * This function checks a specified Frame in the supplied FrameSet. * If the Frame has more than 3 dimensions, a new Frame is added to * the FrameSet containing just the first three axes of the specified * Frame. A PermMap is used to connect this Frame to the specified * Frame, which supplied bad values for any missing axes. If the * specified Frame is the base Frame in the supplied FrameSet, then the * new Frame becomes the base Frame in the returned FrameSet. Like-wise, * if the specified Frame is the current Frame, then the new Frame * will be the current Frame in the returned FrameSet. * * If the specified Frame does not have more than 3 axes, then a clone * of the FrameSet pointer is returned, otherwise the returned pointer * points to a copy of the supplied FrameSet with the new 3-D Frame * added. * Parameters: * fset * Pointer to the FrameSet. * ifrm * The index of the Frame to check. This should be AST__BASE or * AST_CURRENT. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a FrameSet in which the Frame with index given by ifrm * has no more than 3 axes. */ /* Local Variables: */ AstFrame *frm; AstFrame *newfrm; AstFrameSet *ret; AstPermMap *map; double zero; int *inperm; int axes[3]; int i; int ic; int nax; /* Check the inherited status. */ if( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ map = NULL; /* Get a pointer to the requested Frame in the supplied FrameSet. */ frm = astGetFrame( fset, ifrm ); /* See how many dimensions the specified Frame of the supplied FrameSet has. */ nax = astGetNaxes( frm ); /* If it is more than 3-dimensionbal, create a 3D Frame by picking axes 1, 2 and 3 from the original Frame. */ if( nax > 3 ) { axes[ 0 ] = 0; axes[ 1 ] = 1; axes[ 2 ] = 2; newfrm = astPickAxes( frm, 3, axes, NULL ); /* Create a PermMap to describe the mapping between the two Frames. Use zero as the value for unknown axes (the optional mapping which can be returned by astPickAxes uses AST__BAD for unknown axes). */ inperm = (int *) astMalloc( sizeof(int)*(size_t) nax ); if( astOK ){ inperm[ 0 ] = 0; inperm[ 1 ] = 1; inperm[ 2 ] = 2; for( i = 3; i < nax; i++ ) inperm[ i ] = -1; zero = 0.0; map = astPermMap( nax, inperm, 3, axes, &zero, "", status ); inperm = (int *) astFree( (void *) inperm ); } /* Get a copy of the supplied FrameSet. */ ret = astCopy( fset ); /* Add the new Frame to the FrameSet (it becomes the current Frame). */ ic = astGetCurrent( ret ); astAddFrame( ret, ifrm, map, newfrm ); newfrm = astAnnul( newfrm ); /* If the new Frame was derived from the base frame, set the new base Frame, and re-instate the original current Frame */ if( ifrm == AST__BASE ){ astSetBase( ret, astGetCurrent( ret ) ); astSetCurrent( ret, ic ); } /* If the specified Frame in the supplied FrameSet is 3-dimensional, just return a clone of it. */ } else { ret = astClone( fset ); } /* Annul the pointer to the original Frame. */ frm = astAnnul( frm ); return ret; } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot3D member function (over-rides the protected astGetAttrib * method inherited from the FrameSet class). * Description: * This function returns a pointer to the value of a specified * attribute for a Plot3D, formatted as a character string. * Parameters: * this * Pointer to the Plot3D. * 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 Plot3D, 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 Plot3D. 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: */ AstPlot *plot; /* Pointer to specific Plot */ AstPlot3D *this; /* Pointer to the Plot3D structure */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char attname[50]; /* Plot attribute base name */ char patt[50]; /* Plot attribute full name */ char spec[10]; /* Plane specification */ const char *result; /* Pointer value to return */ double dval; /* Floating point attribute value */ int axis; /* Axis index */ int ival; /* Int attribute value */ int len; /* Length of attrib string */ int nc; /* Number of character read */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* Norm(axis). */ /* ----------- */ if ( nc = 0, ( 1 == astSscanf( attrib, "norm(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetNorm( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* RootCorner. */ /* ----------- */ } else if ( !strcmp( attrib, "rootcorner" ) ) { ival = astGetRootCorner( this ); result = RootCornerString( ival, status ); if( !result && astOK ) { astError( AST__INTER, "astGetAttrib(Plot3D): Illegal value %d " "for RootCorner attribute (internal AST programming " "error).", status, ival ); } /* ..._XY etc */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( attrib, "%[a-z]_%[xyz]%n", attname, spec, &nc ) ) ) { if( !strcmp( spec, "xy" ) || !strcmp( spec, "yx" ) ) { plot = this->plotxy; } else if( !strcmp( spec, "xz" ) || !strcmp( spec, "zx" ) ) { plot = this->plotyz; } else if( !strcmp( spec, "yz" ) || !strcmp( spec, "zy" ) ) { plot = this->plotxz; } else { plot = NULL; } if( plot ) { sprintf( patt, "%s%s", attname, attrib + nc ); result = astGetAttrib( plot, patt ); } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Plot3D member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Plot3D, * in bytes. * Parameters: * this * Pointer to the Plot3D. * 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: */ AstPlot3D *this; /* Pointer to Plot3D structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->plotxy ); result += astGetObjSize( this->plotxz ); result += astGetObjSize( this->plotyz ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void Grid( AstPlot *this_plot, int *status ) { /* * Name: * Grid * Purpose: * Draw a set of labelled coordinate axes. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void Grid( AstPlot *this, int *status ) * Class Membership: * Plot member function (over-rides the astGrid method inherited from * the Plot class). * Description: * This function draws a complete annotated set of 3-dimensional * coordinate axes for a Plot3D with (optionally) a coordinate grid * superimposed. * Parameters: * this * Pointer to the Plot3D. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot *baseplot; AstPlot *plot; AstPlot3D *this; AstPointSet *majticks; AstPointSet *minticks; AstPointSet *tmp; AstPointSet *wcsmajticks; AstPointSet *wcsminticks; const char *edge; double **ptrmin; double **ptrmaj; double gcon; int base_wax2d; int itick; int new_gaxis; int new_plot; int new_wax2d; int nmaj; int nmin; int perm[ 2 ]; int rootcorner; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_plot; /* Invoke the astGrid method on the 2D base Plot. Both WCS axes in this Plot are inherited from the 3D FrameSet that was supplied when the Plot3D was constructed, and will be labelled. The other two Plots encapsulated in the Plot3D only inherit a single axis from the original 3D FrameSet (a dummy axis is used for the second WCS axis in these Plots). */ baseplot = GET_PLOT( this->baseplot ); astGrid( baseplot ); /* We next use astGrid to draw a grid on the 2D plane that shares the first base plot graphics axis. Get the identifier for this Plot and the 2D graphics axis index within the Plot that corresponds to the first base plot graphics axis. Also get the constant value on the 3rd graphics axis over the base plot */ rootcorner = astGetRootCorner( this ); if( this->baseplot == XY ) { new_plot = XZ; new_gaxis = 0; gcon = this->gbox[ ( rootcorner & 4 ) ? 5 : 2 ]; } else if( this->baseplot == XZ ) { new_plot = XY; new_gaxis = 0; gcon = this->gbox[ ( rootcorner & 2 ) ? 4 : 1 ]; } else { new_plot = XY; new_gaxis = 1; gcon = this->gbox[ ( rootcorner & 1 ) ? 3 : 0 ]; } /* Get a pointer to the Plot upon which astGrid is about to be invoked. */ plot = GET_PLOT( new_plot ); /* Find which 2D WCS axis was labelled on graphics axis 0 (the bottom or top edge) of the base plot. */ if( ( edge = astGetC( baseplot, "Edge(1)" ) ) ) { base_wax2d = ( !strcmp( edge, "bottom" ) || !strcmp( edge, "top" ) ) ? 0 : 1; } else { base_wax2d = 0; } /* Get the 2D graphics coords within the base Plot at which the tick marks were drawn for this 2D WCS axis. Extend the PointSets holding the major tick values to include an extra tick above and below the ticks drawn by astGrid. These extra ticks are placed outside the bounds of the plot. This ensures that the curves on the other axis extend the full width of the plot. */ tmp = astGetDrawnTicks( baseplot, base_wax2d, 1 ); if( tmp ) { majticks = ExtendTicks( baseplot, tmp, status ); nmaj = astGetNpoint( majticks ); ptrmaj = astGetPoints( majticks ); tmp = astAnnul( tmp ); } else { majticks = NULL; nmaj = 0; ptrmaj = NULL; } minticks = astGetDrawnTicks( baseplot, base_wax2d, 0 ); if( minticks ) { nmin = astGetNpoint( minticks ); ptrmin = astGetPoints( minticks ); } else { nmin = 0; ptrmin = NULL; } /* All the tick marks will have a constant value for the 2D graphics axis that is not being ticked (axis 1 at the moment). Change this constant value to be the value appropriate to the new Plot. */ if( ptrmaj && ptrmin ) { for( itick = 0; itick < nmaj; itick++ ) ptrmaj[ 1 ][ itick ] = gcon; for( itick = 0; itick < nmin; itick++ ) ptrmin[ 1 ][ itick ] = gcon; } /* If required, permute the axes in the tick mark positions. */ if( new_gaxis != 0 ) { perm[ 0 ] = 1; perm[ 1 ] = 0; if( majticks ) astPermPoints( majticks, 1, perm ); if( minticks ) astPermPoints( minticks, 1, perm ); } /* Transform the tick mark positions from 2D graphics coords to 2D WCS coords. */ wcsmajticks = majticks ? astTransform( plot, majticks, 1, NULL ) : NULL; wcsminticks = minticks ? astTransform( plot, minticks, 1, NULL ) : NULL; /* Find the index of the 2D WCS axis that will be labelled on the bottom or top edge (i.e. 2D graphics axis zero) of the new Plot. */ if( ( edge = astGetC( plot, "Edge(1)" ) ) ) { new_wax2d = ( !strcmp( edge, "bottom" ) || !strcmp( edge, "top" ) ) ? 0 : 1; } else { new_wax2d = 0; } /* Use the other WCS axis if we are ticking the left or right edge (i.e. 2D graphics axis one) of the new Plot. This gives us the index of the 2D WCS axis for which tick values are to be stored in the Plot. */ if( new_gaxis == 1 ) new_wax2d = 1 - new_wax2d; /* Store the tick mark values to be used on this WCS axis. */ ptrmaj = wcsmajticks ? astGetPoints( wcsmajticks ) : NULL; ptrmin = wcsminticks ? astGetPoints( wcsminticks ) : NULL; if( ptrmaj && ptrmin ) { astSetTickValues( plot, new_wax2d, nmaj, ptrmaj[ new_gaxis ], nmin, ptrmin[ new_gaxis ] ); } /* Invoke the astGrid method on this plot. */ astGrid( plot ); /* Clear the stored tick values in the plot. */ astSetTickValues( plot, new_wax2d, 0, NULL, 0, NULL ); /* Free resources */ if( wcsmajticks ) wcsmajticks = astAnnul( wcsmajticks ); if( wcsminticks ) wcsminticks = astAnnul( wcsminticks ); if( majticks ) majticks = astAnnul( majticks ); if( minticks ) minticks = astAnnul( minticks ); /* We next use astGrid to draw a grid on the 2D plane that shares the second base plot graphics axis. Get the identifier for this Plot and the 2D graphics axis index within the Plot that corresponds to the first base plot graphics axis. */ if( this->baseplot == XY ) { new_plot = YZ; new_gaxis = 0; } else if( this->baseplot == XZ ) { new_plot = YZ; new_gaxis = 1; } else { new_plot = XZ; new_gaxis = 1; } /* Get a pointer to the Plot upon which astGrid is about to be invoked. */ plot = GET_PLOT( new_plot ); /* Find which 2D WCS axis was labelled on graphics axis 1 (the left or right edge) of the base plot. */ base_wax2d = 1 - base_wax2d; /* Get the 2D graphics coords within the base Plot at which the tick marks were drawn for this 2D WCS axis. Extend the PointSets holding the major tick values to include an extra tick above and below the ticks drawn by astGrid. These extra ticks are placed outside the bounds of the plot. This ensures that the curves on the other axis extend the full width of the plot. */ tmp = astGetDrawnTicks( baseplot, base_wax2d, 1 ); if( tmp ) { majticks = ExtendTicks( baseplot, tmp, status ); nmaj = astGetNpoint( majticks ); ptrmaj = astGetPoints( majticks ); tmp = astAnnul( tmp ); } else { majticks = NULL; nmaj = 0; ptrmaj = NULL; } minticks = astGetDrawnTicks( baseplot, base_wax2d, 0 ); if( minticks ) { nmin = astGetNpoint( minticks ); ptrmin = astGetPoints( minticks ); } else { nmin = 0; ptrmin = NULL; } /* All the tick marks will have a constant value for the 2D graphics axis that is not being ticked (axis 0 at the moment). Change this constant value to be the value appropriate to the new Plot. */ if( ptrmaj && ptrmin ) { for( itick = 0; itick < nmaj; itick++ ) ptrmaj[ 0 ][ itick ] = gcon; for( itick = 0; itick < nmin; itick++ ) ptrmin[ 0 ][ itick ] = gcon; } /* If required, permute the axes in the tick mark positions. */ if( new_gaxis != 1 ) { perm[ 0 ] = 1; perm[ 1 ] = 0; if( majticks ) astPermPoints( majticks, 1, perm ); if( minticks ) astPermPoints( minticks, 1, perm ); } /* Transform the tick mark positions from 2D graphics coords to 2D WCS coords. */ wcsmajticks = majticks ? astTransform( plot, majticks, 1, NULL ) : NULL; wcsminticks = minticks ? astTransform( plot, minticks, 1, NULL ) : NULL; /* Find the index of the 2D WCS axis that will be labelled on the bottom or top edge (i.e. 2D graphics axis zero) of the new Plot. */ if( ( edge = astGetC( plot, "Edge(1)" ) ) ) { new_wax2d = ( !strcmp( edge, "bottom" ) || !strcmp( edge, "top" ) ) ? 0 : 1; } else { new_wax2d = 0; } /* Use the other WCS axis if we are ticking the left or right edge (i.e. 2D graphics axis one) of the new Plot. This gives us the index of the 2D WCS axis for which tick values are to be stored in the Plot. */ if( new_gaxis == 1 ) new_wax2d = 1 - new_wax2d; /* Store the tick mark values to be used on this WCS axis. */ ptrmaj = wcsmajticks ? astGetPoints( wcsmajticks ) : NULL; ptrmin = wcsminticks ? astGetPoints( wcsminticks ) : NULL; if( ptrmaj && ptrmin ) { astSetTickValues( plot, new_wax2d, nmaj, ptrmaj[ new_gaxis ], nmin, ptrmin[ new_gaxis ] ); } /* Invoke the astGrid method on this plot. */ astGrid( plot ); /* Clear the stored tick values in the plot. */ astSetTickValues( plot, new_wax2d, 0, NULL, 0, NULL ); /* Free resources */ if( wcsmajticks ) wcsmajticks = astAnnul( wcsmajticks ); if( wcsminticks ) wcsminticks = astAnnul( wcsminticks ); if( majticks ) majticks = astAnnul( majticks ); if( minticks ) minticks = astAnnul( minticks ); } void astInitPlot3DVtab_( AstPlot3DVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPlot3DVtab * Purpose: * Initialise a virtual function table for a Plot3D. * Type: * Protected function. * Synopsis: * #include "plot3d.h" * void astInitPlot3DVtab( AstPlot3DVtab *vtab, const char *name ) * Class Membership: * Plot3D vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Plot3D 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 */ AstFrame *dummy_frame; /* The Frame to put in dummy_frameset */ AstPlotVtab *plot; /* Pointer to Plot component of Vtab */ AstFrameSetVtab *fset; /* Pointer to FrameSet 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. */ astInitPlotVtab( (AstPlotVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPlot3D) 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 = &(((AstPlotVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ #define SET_PLOT3D_ACCESSORS(attr) \ vtab->Set##attr = Set##attr; \ vtab->Get##attr = Get##attr; \ vtab->Test##attr = Test##attr; \ vtab->Clear##attr = Clear##attr; SET_PLOT3D_ACCESSORS(RootCorner) SET_PLOT3D_ACCESSORS(Norm) #undef SET_PLOT3D_ACCESSORS /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; fset = (AstFrameSetVtab *) vtab; mapping = (AstMappingVtab *) vtab; plot = (AstPlotVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_equal = object->Equal; object->Equal = Equal; parent_vset = object->VSet; object->VSet = VSet; parent_cast = object->Cast; object->Cast = Cast; parent_clear = object->Clear; object->Clear = Clear; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_clearcurrent = fset->ClearCurrent; fset->ClearCurrent = ClearCurrent; parent_setcurrent = fset->SetCurrent; fset->SetCurrent = SetCurrent; parent_removeframe = fset->RemoveFrame; fset->RemoveFrame = RemoveFrame; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif /* Define a macro to override attribute accessors inherited from the parent Plot class. First do axis specific attributes. */ #define SET_PLOT_ACCESSORS(attr) \ parent_get##attr = plot->Get##attr; \ plot->Get##attr = Get##attr; \ parent_set##attr = plot->Set##attr; \ plot->Set##attr = Set##attr; \ parent_clear##attr = plot->Clear##attr; \ plot->Clear##attr = Clear##attr; /* Use the above macro to override all the inherited attribute accessors. */ SET_PLOT_ACCESSORS(MinTick) SET_PLOT_ACCESSORS(Abbrev) SET_PLOT_ACCESSORS(Gap) SET_PLOT_ACCESSORS(LogGap) SET_PLOT_ACCESSORS(LogPlot) SET_PLOT_ACCESSORS(LogTicks) SET_PLOT_ACCESSORS(LogLabel) SET_PLOT_ACCESSORS(LabelUp) SET_PLOT_ACCESSORS(DrawAxes) SET_PLOT_ACCESSORS(LabelUnits) SET_PLOT_ACCESSORS(MinTickLen) SET_PLOT_ACCESSORS(MajTickLen) SET_PLOT_ACCESSORS(NumLab) SET_PLOT_ACCESSORS(NumLabGap) SET_PLOT_ACCESSORS(TextLab) SET_PLOT_ACCESSORS(TextLabGap) #undef SET_PLOT_ACCESSORS /* Now do attributes that are not axis specific. */ #define SET_PLOT_ACCESSORS(attr) \ parent_set##attr = plot->Set##attr; \ plot->Set##attr = Set##attr; \ parent_clear##attr = plot->Clear##attr; \ plot->Clear##attr = Clear##attr; SET_PLOT_ACCESSORS(Ink) SET_PLOT_ACCESSORS(Tol) SET_PLOT_ACCESSORS(Invisible) SET_PLOT_ACCESSORS(TickAll) SET_PLOT_ACCESSORS(ForceExterior) SET_PLOT_ACCESSORS(Border) SET_PLOT_ACCESSORS(Clip) SET_PLOT_ACCESSORS(ClipOp) SET_PLOT_ACCESSORS(Escape) SET_PLOT_ACCESSORS(Grid) SET_PLOT_ACCESSORS(Labelling) SET_PLOT_ACCESSORS(Style) SET_PLOT_ACCESSORS(Font) SET_PLOT_ACCESSORS(Colour) SET_PLOT_ACCESSORS(Width) SET_PLOT_ACCESSORS(Size) #undef SET_PLOT_ACCESSORS /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ plot->Grid = Grid; plot->Text = Text; plot->SetTickValues = SetTickValues; plot->PolyCurve = PolyCurve; plot->Border = Border; plot->BoundingBox = BoundingBox; plot->GetGrfContext = GetGrfContext; plot->GrfPop = GrfPop; plot->GrfPush = GrfPush; plot->GrfSet = GrfSet; plot->GridLine = GridLine; plot->Mark = Mark; plot->Curve = Curve; plot->GenCurve = GenCurve; plot->Clip = Clip; mapping->Transform = Transform; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "Plot3D", "Provide facilities for 3D graphical output" ); /* Create a FrameSet that can be used when calling astCast to indicate the class to which we want to cast. */ LOCK_MUTEX3 if( !dummy_frameset ) { dummy_frame = astFrame( 1, " ", status ); dummy_frameset = astFrameSet( dummy_frame, " ", status ); dummy_frame = astAnnul( dummy_frame ); } UNLOCK_MUTEX3 /* 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) ); } } #if defined(THREAD_SAFE) static int ManageLock( AstObject *this_object, int mode, int extra, AstObject **fail, int *status ) { /* * Name: * ManageLock * Purpose: * Manage the thread lock on an Object. * Type: * Private function. * Synopsis: * #include "object.h" * AstObject *ManageLock( AstObject *this, int mode, int extra, * AstObject **fail, int *status ) * Class Membership: * CmpMap member function (over-rides the astManageLock protected * method inherited from the parent class). * Description: * This function manages the thread lock on the supplied Object. The * lock can be locked, unlocked or checked by this function as * deteremined by parameter "mode". See astLock for details of the way * these locks are used. * Parameters: * this * Pointer to the Object. * mode * An integer flag indicating what the function should do: * * AST__LOCK: Lock the Object for exclusive use by the calling * thread. The "extra" value indicates what should be done if the * Object is already locked (wait or report an error - see astLock). * * AST__UNLOCK: Unlock the Object for use by other threads. * * AST__CHECKLOCK: Check that the object is locked for use by the * calling thread (report an error if not). * extra * Extra mode-specific information. * fail * If a non-zero function value is returned, a pointer to the * Object that caused the failure is returned at "*fail". This may * be "this" or it may be an Object contained within "this". Note, * the Object's reference count is not incremented, and so the * returned pointer should not be annulled. A NULL pointer is * returned if this function returns a value of zero. * status * Pointer to the inherited status variable. * Returned Value: * A local status value: * 0 - Success * 1 - Could not lock or unlock the object because it was already * locked by another thread. * 2 - Failed to lock a POSIX mutex * 3 - Failed to unlock a POSIX mutex * 4 - Bad "mode" value supplied. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ AstPlot3D *this; /* Pointer to Plot3D structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->plotxy, mode, extra, fail ); if( !result ) result = astManageLock( this->plotxz, mode, extra, fail ); if( !result ) result = astManageLock( this->plotyz, mode, extra, fail ); return result; } #endif static void Mark( AstPlot *this_plot, int nmark, int ncoord, int indim, const double *in, int type, int *status ){ /* * Name: * Mark * Purpose: * Draw a set of markers for a Plot3D. * Type: * Private member function. * Synopsis: * #include "plot3d.h" * void Mark( AstPlot *this, int nmark, int ncoord, int indim, * const double *in, int type, int *status ) * Class Membership: * Plot3d member function (overrides the astMark method inherited form * the parent Plot class). * Description: * This function draws a set of markers (symbols) at positions * specified in the physical coordinate system of a Plot3D. The * positions are transformed into graphical coordinates to * determine where the markers should appear within the plotting * area. * * They are drawn on a 2D plane that has a normal vector given by the * current value of the Plot3D's "Norm" attribute. * Parameters: * this * Pointer to the Plot3D. * nmark * The number of markers to draw. This may be zero, in which * case nothing will be drawn. * ncoord * The number of coordinates being supplied for each mark * (i.e. the number of axes in the current Frame of the Plot, as * given by its Naxes attribute). * indim * The number of elements along the second dimension of the "in" * array (which contains the marker coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value * given should not be less than "nmark". * in * The address of the first element of a 2-dimensional array of * shape "[ncoord][indim]" giving the * physical coordinates of the points where markers are to be * drawn. These should be stored such that the value of * coordinate number "coord" for input mark number "mark" is * found in element "in[coord][mark]". * type * A value specifying the type (e.g. shape) of marker to be * drawn. The set of values which may be used (and the shapes * that will result) is determined by the underlying graphics * system. * status * Pointer to the inherited status variable. * Notes: * - Markers are not drawn at positions which have any coordinate * equal to the value AST__BAD (or where the transformation into * graphical coordinates yields coordinates containing the value * AST__BAD). * - An error results if the base Frame of the Plot is not 3-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). */ /* Local Variables: */ AstMapping *mapping; /* Pointer to graphics->physical mapping */ AstPlot3D *this; /* Pointer to the Plot3D structure */ AstPointSet *pset1; /* PointSet holding physical positions */ AstPointSet *pset2; /* PointSet holding graphics positions */ const char *class; /* Object class */ const char *method; /* Current method */ const double **ptr1; /* Pointer to physical positions */ double **ptr2; /* Pointer to graphics positions */ double *xpd; /* Pointer to next double precision x value */ double *ypd; /* Pointer to next double precision y value */ double *zpd; /* Pointer to next double precision z value */ float *x; /* Pointer to single precision x values */ float *xpf; /* Pointer to next single precision x value */ float *y; /* Pointer to single precision y values */ float *ypf; /* Pointer to next single precision y value */ float *z; /* Pointer to single precision z values */ float *zpf; /* Pointer to next single precision z value */ float norm[ 3 ]; /* Single precision normal vector */ int axis; /* Axis index */ int i; /* Loop count */ int naxes; /* No. of axes in the base Frame */ int nn; /* Number of good marker positions */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_plot; /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astMark"; class = astClass( this ); /* Check the base Frame of the Plot is 3-D. */ naxes = astGetNin( this ); if( naxes != 3 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 3.", status, method, class, naxes, class ); } /* Also validate the input array dimension argument. */ if ( astOK && ( indim < nmark ) ) { astError( AST__DIMIN, "%s(%s): The input array dimension value " "(%d) is invalid.", status, method, class, indim ); astError( AST__DIMIN, "This should not be less than the number of " "markers being drawn (%d).", status, nmark ); } /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__MARKS_ID, 1, GRF__MARK, method, class ); /* Create a PointSet to hold the supplied physical coordinates. */ pset1 = astPointSet( nmark, ncoord, "", status ); /* Allocate memory to hold pointers to the first value on each axis. */ ptr1 = (const double **) astMalloc( sizeof( const double * )* (size_t)( ncoord )); /* Check the pointer can be used, then store pointers to the first value on each axis. */ if( astOK ){ for( axis = 0; axis < ncoord; axis++ ){ ptr1[ axis ] = in + axis*indim; } } /* Store these pointers in the PointSet. */ astSetPoints( pset1, (double **) ptr1 ); /* Transform the supplied data from the current frame (i.e. physical coordinates) to the base frame (i.e. graphics coordinates) using the inverse Mapping defined by the Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); pset2 = astTransform( mapping, pset1, 0, NULL ); mapping = astAnnul( mapping ); /* Get pointers to the graphics coordinates. */ ptr2 = astGetPoints( pset2 ); /* Allocate memory to hold single precision versions of the graphics coordinates. */ x = (float *) astMalloc( sizeof( float )*(size_t) nmark ); y = (float *) astMalloc( sizeof( float )*(size_t) nmark ); z = (float *) astMalloc( sizeof( float )*(size_t) nmark ); /* Check the pointers can be used. */ if( astOK ){ /* Store pointers to the next single and double precision x, y and z values. */ xpf = x; ypf = y; zpf = z; xpd = ptr2[ 0 ]; ypd = ptr2[ 1 ]; zpd = ptr2[ 2 ]; /* Convert the double precision values to single precision, rejecting any bad marker positions. */ nn = 0; for( i = 0; i < nmark; i++ ){ if( *xpd != AST__BAD && *ypd != AST__BAD && *zpd != AST__BAD ){ nn++; *(xpf++) = (float) *(xpd++); *(ypf++) = (float) *(ypd++); *(zpf++) = (float) *(zpd++); } else { xpd++; ypd++; zpd++; } } /* If the nornmal vector has non-zero length, draw the remaining markers. */ norm[ 0 ] = (float) astGetNorm( this, 0 ); norm[ 1 ] = (float) astGetNorm( this, 1 ); norm[ 2 ] = (float) astGetNorm( this, 2 ); if( norm[ 0 ] != 0.0 || norm[ 1 ] != 0.0 || norm[ 2 ] != 0.0 ){ /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; if( !astG3DMark( nn, x, y, z, type, norm ) ) { astError( AST__GRFER, "%s(%s): Graphics error in astG3DMark. ", status, method, class ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } else if( astOK ) { astError( AST__ATTIN, "%s(%s): The vector specified by the Norm " "attribute has zero length.", status, method, class ); } } /* Free the memory used to store single precision graphics coordinates. */ x = (float *) astFree( (void *) x ); y = (float *) astFree( (void *) y ); z = (float *) astFree( (void *) z ); /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free the memory holding the pointers to the first value on each axis. */ ptr1 = (const double **) astFree( (void *) ptr1 ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__MARKS_ID, 0, GRF__MARK, method, class ); /* Return */ return; } static int Plot3DAttr( AstKeyMap *grfconID, int attr, double value, double *old_value, int prim ){ /* * Name: * Plot3DAttr * Purpose: * Get or set the value of a 3D grf attribute. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DAttr( AstKeyMap *grfconID, int attr, double value, * double *old_value, int prim ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * get or set the current value of a specified graphics attribute. It * forwards the call to the grf3D module being used by this Plot3D. It * should be registered with each of the 2D Plots using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is used to identify which of * the three Plots is calling this function. * attr * An integer value identifying the required attribute. This should * be one of the symbolic values defined in grf.h. * value * A new value to store for the attribute. If this is AST__BAD * no value is stored. * old_value * A pointer to a double in which to return the attribute value. * If this is NULL, no value is returned. * prim * The sort of graphics primitive to be drawn with the new attribute. * Identified by one of the values defined in grf.h. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ int result; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return 0; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Use the function in the external Grf3D module, selected at link-time using ast_link options. Note, attribute values are the same for each of the three Plot. */ result = astG3DAttr( attr, value, old_value, prim ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Return the result. */ return result; } static int Plot3DCap( AstKeyMap *grfconID, int cap, int value ){ /* * Name: * Plot3DCap * Purpose: * Determine if the 3D grf module has a given capability. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DCap( AstKeyMap *grfconID, int cap, int value ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * determine if a given graphics capability is available. It forwards * the call to the grf3D module being used by this Plot3D. It should be * registered with each of the 2D Plots using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * cap * The capability being inquired about. This will be one of the * following constants defined in grf.h: GRF__SCALES, GRF__MJUST, * GRF__ESC, * value * The use of this parameter depends on the value of "cap" as * described in the documentation for the astGrfSet function in the * Plot class. * Returned Value: * The value returned by the function depends on the value of "cap" * as described in the astGrfSet documentation. Zero is returned if * the supplied capability is not recognised. */ /* Local Variables: */ int result; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return 0; /* The astGScales function is implemented by code within the Plot3D class (not within the grf3D module). The Plot3D class assumes all axes are equally scaled. */ if( cap == GRF__SCALES ) { result = 1; /* All grf3D modules are assumed to support "M" justification. */ } else if( cap == GRF__MJUST ) { result = 1; /* Forward all other capability requests to the grf3D module. */ } else { /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; result = astG3DCap( cap, value ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } /* Return the result. */ return result; } static int Plot3DFlush( AstKeyMap *grfconID ){ /* * Name: * Plot3DFlush * Purpose: * Flush any buffered graphical output. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DFlush( AstKeyMap *grfconID ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * ensure that the display device is up-to-date by flushing any pending * graphics to the output device. It forwards the call to the grf3D module * being used by this Plot3D. It should be registered with each of the * 2D Plots using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ int result; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return 0; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Use the function in the external Grf3D module, selected at link-time using ast_link options. */ result = astG3DFlush(); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Return the result. */ return result; } static int Plot3DLine( AstKeyMap *grfconID, int n, const float *x, const float *y ){ /* * Name: * Plot3DLine * Purpose: * Draw a polyline on a 2D surface. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DLine( AstKeyMap *grfconID, int n, const float *x, * const float *y ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * draw a polyline. It forwards the call to the grf3D module being used * by this Plot3D. It should be registered with each of the 2D Plots * using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ AstKeyMap *grfcon; double gcon; float *work; float *x3d = NULL; float *y3d = NULL; float *z3d = NULL; int i; int plane; int result = 0; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return result; /* Get a genuine pointer from the supplied grfcon identifier. */ grfcon = astMakePointer( grfconID ); /* Report an error if no grfcon object was supplied. */ if( !grfcon ) { astError( AST__INTER, "astG3DLine(Plot3D): No grfcon Object supplied " "(internal AST programming error)." , status); /* If a grfcon Object was supplied, get the graphics box array out of it. */ } else if( !astMapGet0D( grfcon, "Gcon", &gcon ) ) { astError( AST__INTER, "astG3DLine(Plot3D): No \"Gcon\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* Also get the plane index out of it. */ } else if( !astMapGet0I( grfcon, "Plane", &plane ) ) { astError( AST__INTER, "astG3DLine(Plot3D): No \"Plane\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); } /* Allocate memory to hold the "n" values for the missing coordinate. */ work = astMalloc( sizeof( float )*(size_t) n ); if( work ) { /* Set up pointers to the x, y and z arrays in the 3D graphics system. Fill the missing array with suitable values (the constant value of the third axis on the plane being drawn). */ if( plane == XY ) { x3d = (float *) x; y3d = (float *) y; z3d = work; for( i = 0; i < n; i++ ) z3d[ i ] = gcon; } else if( plane == XZ ) { x3d = (float *) x; y3d = work; z3d = (float *) y; for( i = 0; i < n; i++ ) y3d[ i ] = gcon; } else if( plane == YZ ) { x3d = work; y3d = (float *) x; z3d = (float *) y; for( i = 0; i < n; i++ ) x3d[ i ] = gcon; } else { astError( AST__INTER, "astG3DLine(Plot3D): Illegal plane " "identifier %d supplied (internal AST programming " "error).", status, plane ); } /* If ok, draw the lines in the 3D graphics coordinate space. */ if( x3d ) { /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Draw the line */ result = astG3DLine( n, x3d, y3d, z3d ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } } /* Free resources. */ work = astFree( work ); /* Return the result. */ return result; } static int Plot3DMark( AstKeyMap *grfconID, int n, const float *x, const float *y, int type ){ /* * Name: * Plot3DMark * Purpose: * Draw a set of markers. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DMark( AstKeyMap *grfconID, int n, const float *x, * const float *y, int type ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * draw a set of markers. It forwards the call to the grf3D module being * used by this Plot3D. It should be registered with each of the 2D Plots * using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * n * The number of markers to draw. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * type * An integer which can be used to indicate the type of marker symbol * required. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ AstKeyMap *grfcon; double gcon; float *work; float *x3d = NULL; float *y3d = NULL; float *z3d = NULL; float norm[ 3 ]; int i; int plane; int rc; int result = 0; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return result; /* Get a genuine pointer from the supplied grfcon identifier. */ grfcon = astMakePointer( grfconID ); /* Report an error if no grfcon object was supplied. */ if( !grfcon ) { astError( AST__INTER, "astG3DMark(Plot3D): No grfcon Object supplied " "(internal AST programming error)." , status); /* If a grfcon Object was supplied, get the graphics box array out of it. */ } else if( !astMapGet0D( grfcon, "Gcon", &gcon ) ) { astError( AST__INTER, "astG3DMark(Plot3D): No \"Gcon\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* If a grfcon Object was supplied, get the RootCorner value out of it. */ } else if( !astMapGet0I( grfcon, "RootCorner", &rc ) ) { astError( AST__INTER, "astG3DLine(Plot3D): No \"RootCornern\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* Also get the plane index out of it. */ } else if( !astMapGet0I( grfcon, "Plane", &plane ) ) { astError( AST__INTER, "astG3DMark(Plot3D): No \"Plane\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); } /* Allocate memory to hold the "n" values for the missing coordinate. */ work = astMalloc( sizeof( float )*(size_t) n ); if( work ) { /* Set up pointers to the x, y and z arrays in the 3D graphics system. Fill the missing array with suitable values (the constant value of the third axis on the plane being drawn). Set the normal vector for the markers so that they are drawn in the plane described by the Plot.*/ if( plane == XY ) { x3d = (float *) x; y3d = (float *) y; z3d = work; for( i = 0; i < n; i++ ) z3d[ i ] = gcon; norm[ 0 ] = 0; norm[ 1 ] = 0; norm[ 2 ] = ( rc & 4 ) ? 1 : -1; } else if( plane == XZ ) { x3d = (float *) x; y3d = work; z3d = (float *) y; for( i = 0; i < n; i++ ) y3d[ i ] = gcon; norm[ 0 ] = 0; norm[ 1 ] = ( rc & 2 ) ? 1 : -1; norm[ 2 ] = 0; } else if( plane == YZ ) { x3d = work; y3d = (float *) x; z3d = (float *) y; for( i = 0; i < n; i++ ) x3d[ i ] = gcon; norm[ 0 ] = ( rc & 1 ) ? 1 : -1; norm[ 1 ] = 0; norm[ 2 ] = 0; } else { astError( AST__INTER, "astG3DMark(Plot3D): Illegal plane " "identifier %d supplied (internal AST programming " "error).", status, plane ); } /* If ok, draw the markers in the 3D graphics coordinate space. */ if( x3d ) { /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Draw the markers */ result = astG3DMark( n, x3d, y3d, z3d, type, norm ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } } /* Free resources. */ work = astFree( work ); /* Return the result. */ return result; } static int Plot3DQch( AstKeyMap *grfconID, float *chv, float *chh ){ /* * Name: * Plot3DQch * Purpose: * Get the current text size. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DQch( AstKeyMap *grfconID, float *chv, float *chh ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * get the current text size. It forwards the call to the grf3D module * being used by this Plot3D. It should be registered with each of the * 2D Plots using astGrfSet. * * The grf3D module assumes that the 3D graphics axes are equally * scaled and therefore the text height does not depend on the text * orientation. Therefore, "chv" and "chh" are returned holding the * same value. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * chv * A pointer to the float which is to receive the height of * characters drawn with a vertical baseline in the 2D Plot. This * will be an increment in the 2D X axis. * chh * A pointer to the float which is to receive the height of * characters drawn with a horizontal baseline in the 2D Plot. This * will be an increment in the 2D Y axis. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ int result; float ch; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return 0; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Use the function in the external Grf3D module, selected at link-time using ast_link options. Note, text height is the same for each of the three Plot. */ result = astG3DQch( &ch ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Store the value in both the returned values. */ *chv = ch; *chh = ch; /* Return the error flag. */ return result; } static int Plot3DScales( AstKeyMap *grfconID, float *alpha, float *beta ){ /* * Name: * Plot3DScales * Purpose: * Get the 2D axis scales. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DScales( AstKeyMap *grfconID, float *alpha, float *beta ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * get the relative scales of the 2D axes. Since the grf3D module * assumes that all graphics axes are equally scaled, it just returns 1.0 * for alpha and beta. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * alpha * A pointer to the float which is to receive the scale for the X * axis * beta * A pointer to the float which is to receive the scale for the Y * axis * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ *alpha = 1.0; *beta = 1.0; return 1; } static int Plot3DText( AstKeyMap *grfconID, const char *text, float x, float y, const char *just, float upx, float upy ){ /* * Name: * Plot3DText * Purpose: * Draw a text string. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DText( AstKeyMap *grfconID, const char *text, float x, float y, * const char *just, float upx, float upy ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * draw a text string. It forwards the call to the grf3D module being * used by this Plot3D. It should be registered with each of the 2D Plots * using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. * upx * The x component of the up-vector for the text. * upy * The y component of the up-vector for the text. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ AstKeyMap *grfcon; double gcon; float norm[ 3 ]; float ref[ 3 ]; float up[ 3 ]; int plane; int rc; int result = 0; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return result; /* Get a genuine pointer from the supplied grfcon identifier. */ grfcon = astMakePointer( grfconID ); /* Report an error if no grfcon object was supplied. */ if( !grfcon ) { astError( AST__INTER, "astG3DText(Plot3D): No grfcon Object supplied " "(internal AST programming error)." , status); /* If a grfcon Object was supplied, get the graphics box array out of it. */ } else if( !astMapGet0D( grfcon, "Gcon", &gcon ) ) { astError( AST__INTER, "astG3DText(Plot3D): No \"Gcon\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* If a grfcon Object was supplied, get the RootCorner value out of it. */ } else if( !astMapGet0I( grfcon, "RootCorner", &rc ) ) { astError( AST__INTER, "astG3DLine(Plot3D): No \"RootCornern\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* Also get the plane index out of it. */ } else if( !astMapGet0I( grfcon, "Plane", &plane ) ) { astError( AST__INTER, "astG3DText(Plot3D): No \"Plane\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* If OK, draw the text. */ } else { /* Set up the reference, up and normal vectors so that the text appears on the required plane. */ if( plane == XY ) { ref[ 0 ] = x; ref[ 1 ] = y; ref[ 2 ] = gcon; norm[ 0 ] = 0; norm[ 1 ] = 0; norm[ 2 ] = ( rc & 4 ) ? 1 : -1; up[ 0 ] = upx; up[ 1 ] = upy; up[ 2 ] = 0; } else if( plane == XZ ) { ref[ 0 ] = x; ref[ 1 ] = gcon; ref[ 2 ] = y; norm[ 0 ] = 0; norm[ 1 ] = ( rc & 2 ) ? 1 : -1; norm[ 2 ] = 0; up[ 0 ] = upx; up[ 1 ] = 0; up[ 2 ] = upy; } else if( plane == YZ ) { ref[ 0 ] = gcon; ref[ 1 ] = x; ref[ 2 ] = y; norm[ 0 ] = ( rc & 1 ) ? 1 : -1; norm[ 1 ] = 0; norm[ 2 ] = 0; up[ 0 ] = 0; up[ 1 ] = upx; up[ 2 ] = upy; } else { astError( AST__INTER, "astG3DText(Plot3D): Illegal plane " "identifier %d supplied (internal AST programming " "error).", status, plane ); } /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If ok, draw the markers in the 3D graphics coordinate space. */ if( astOK ) result = astG3DText( text, ref, just, up, norm ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } /* Return the result. */ return result; } static int Plot3DTxExt( AstKeyMap *grfconID, const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb ){ /* * Name: * Plot3DTxExt * Purpose: * Determine the plotted extent of a text string. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int Plot3DTxExt( AstKeyMap *grfconID, const char *text, float x, * float y, const char *just, float upx, float upy, * float *xb, float *yb ) * Class Membership: * Plot3D member function. * Description: * This function is called by one of the three encapsulated 2D Plots to * determine the extent a string would have if plotted using Plot3DText. * It forwards the call to the grf3D module being used by this Plot3D. It * should be registered with each of the 2D Plots using astGrfSet. * Parameters: * grfconID * The Plot's GrfContext KeyMap. This is * used to identify which of the three Plots is calling this function. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. * upx * The x component of the up-vector for the text. * upy * The y component of the up-vector for the text. * xb * An array of 4 elements in which to return the x coordinate of * each corner of the bounding box. * yb * An array of 4 elements in which to return the y coordinate of * each corner of the bounding box. * Returned Value: * An integer value of 0 is returned if an error occurs, and 1 otherwise. */ /* Local Variables: */ AstKeyMap *grfcon; double gcon; float *xb3d = NULL; float *yb3d = NULL; float *zb3d = NULL; float bl[ 3 ]; float norm[ 3 ]; float ref[ 3 ]; float unused[ 4 ]; float up[ 3 ]; int plane; int rc; int result = 0; int *status; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the inherited status. */ if( !astOK ) return result; /* Get a genuine pointer from the supplied grfcon identifier. */ grfcon = astMakePointer( grfconID ); /* Report an error if no grfcon object was supplied. */ if( !grfcon ) { astError( AST__INTER, "astG3DTxExt(Plot3D): No grfcon Object supplied " "(internal AST programming error)." , status); /* If a grfcon Object was supplied, get the graphics box array out of it. */ } else if( !astMapGet0D( grfcon, "Gcon", &gcon ) ) { astError( AST__INTER, "astG3DTxExt(Plot3D): No \"Gcon\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* If a grfcon Object was supplied, get the RootCorner value out of it. */ } else if( !astMapGet0I( grfcon, "RootCorner", &rc ) ) { astError( AST__INTER, "astG3DLine(Plot3D): No \"RootCornern\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* Also get the plane index out of it. */ } else if( !astMapGet0I( grfcon, "Plane", &plane ) ) { astError( AST__INTER, "astG3DTxExt(Plot3D): No \"Plane\" key found " "in the supplied grfcon Object (internal AST programming " "error)." , status); /* If OK, get the extent of the text. */ } else { /* Set up the reference, up and normal vectors so that the text appears on the required plane. */ if( plane == XY ) { ref[ 0 ] = x; ref[ 1 ] = y; ref[ 2 ] = gcon; norm[ 0 ] = 0; norm[ 1 ] = 0; norm[ 2 ] = ( rc & 4 ) ? 1 : -1; up[ 0 ] = upx; up[ 1 ] = upy; up[ 2 ] = 0; xb3d = xb; yb3d = yb; zb3d = unused; } else if( plane == XZ ) { ref[ 0 ] = x; ref[ 1 ] = gcon; ref[ 2 ] = y; norm[ 0 ] = 0; norm[ 1 ] = ( rc & 2 ) ? 1 : -1; norm[ 2 ] = 0; up[ 0 ] = upx; up[ 1 ] = 0; up[ 2 ] = upy; xb3d = xb; yb3d = unused; zb3d = yb; } else if( plane == YZ ) { ref[ 0 ] = gcon; ref[ 1 ] = x; ref[ 2 ] = y; norm[ 0 ] = ( rc & 1 ) ? 1 : -1; norm[ 1 ] = 0; norm[ 2 ] = 0; up[ 0 ] = 0; up[ 1 ] = upx; up[ 2 ] = upy; xb3d = unused; yb3d = xb; zb3d = yb; } else { astError( AST__INTER, "astG3DTxExt(Plot3D): Illegal plane " "identifier %d supplied (internal AST programming " "error).", status, plane ); } /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If ok, get the extent of the text. */ if( astOK ) result = astG3DTxExt( text, ref, just, up, norm, xb3d, yb3d, zb3d, bl ); /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } /* Return the result. */ return result; } static void PolyCurve( AstPlot *this, int npoint, int ncoord, int indim, const double *in, int *status ){ /* * Name: * PolyCurve * Purpose: * Draw a series of connected geodesic curves. * Type: * Private member function. * Synopsis: * #include "plot3d.h" * void PolyCurve( AstPlot *this, int npoint, int ncoord, int indim, * const double *in, int *status ) * Class Membership: * Plot method (overrides the astPolyCurve method inherited form the * Plot class) * Description: * This function joins a series of points specified in the physical * coordinate system of a Plot by drawing a sequence of geodesic * curves. It is equivalent to making repeated use of the astCurve * function (q.v.), except that astPolyCurve will generally be more * efficient when drawing many geodesic curves end-to-end. A * typical application of this might be in drawing contour lines. * * As with astCurve, full account is taken of the Mapping between * physical and graphical coordinate systems. This includes any * discontinuities and clipping established using astClip. * Parameters: * this * Pointer to the Plot. * npoint * The number of points between which geodesic curves are to be drawn. * ncoord * The number of coordinates being supplied for each point (i.e. * the number of axes in the current Frame of the Plot, as given * by its Naxes attribute). * indim * The number of elements along the second dimension of the "in" * array (which contains the input coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value * given should not be less than "npoint". * in * The address of the first element in a 2-dimensional array of shape * "[ncoord][indim]" giving the * physical coordinates of the points which are to be joined in * sequence by geodesic curves. These should be stored such that * the value of coordinate number "coord" for point number * "point" is found in element "in[coord][point]". * status * Pointer to the inherited status variable. * Notes: * - No curve is drawn on either side of any point which has any * coordinate equal to the value AST__BAD. * - An error results if the base Frame of the Plot is not * 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). */ /* Check the global error status. */ if ( !astOK ) return; astError( AST__INTER, "astPolyCurve(%s): The astPolyCurve " "method cannot be used with a %s (programming error).", status, astGetClass( this ), astGetClass( this ) ); } static void RemoveFrame( AstFrameSet *this_fset, int iframe, int *status ) { /* * Name: * RemoveFrame * Purpose: * Remove a Frame from a Plot3D. * Type: * Public virtual function. * Synopsis: * #include "plot.h" * void RemoveFrame( AstFrameSet *this_fset, int iframe, int *status ) * Class Membership: * Plot3D member function (over-rides the astRemoveFrame public * method inherited from the Plot class). * Description: * This function removes a Frame from a Plot3D. All other Frames * in the Plot3D have their indices re-numbered from one (if * necessary), but are otherwise unchanged. * * If the index of the original base Frame is changed, the index value * stored in the Plot3D is updated. If the base Frame itself is * removed, an error is reported. * Parameters: * this_fset * Pointer to the FrameSet component of the Plot3D. * iframe * The index within the Plot3D of the Frame to be removed. * This value should lie in the range from 1 to the number of * Frames in the Plot3D (as given by its Nframe attribute). * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot3D *this; /* Pointer to Plot3D structure */ int ifrm; /* Validated frame index */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_fset; /* Validate the frame index. This translated AST__BASE and AST__CURRENT into actual Frame indices. */ ifrm = astValidateFrameIndex( this_fset, iframe, "astRemoveFrame" ); /* Report an error if an attempt is made to delete the Frame that defines the mapping onto the screen (the original base Frame in the FrameSet supplied when the Plot3D was constructed). */ if( ifrm == this->pix_frame ){ astError( AST__PXFRRM, "astRemoveFrame(%s): Cannot delete Frame " "number %d from the supplied %s since it is the Frame " "that defines the mapping onto the graphics plane.", status, astGetClass( this ), iframe, astGetClass( this ) ); /* Otherwise, invoke the parent astRemoveFrame method to remove the Frame. */ } else { (*parent_removeframe)( this_fset, iframe, status ); /* If the index of the removed Frame is smaller than the original base Frame index, then decrement the original base Frame index so that the same Frame will be used in future. */ if( astOK ){ if( ifrm < this->pix_frame ) (this->pix_frame)--; } } } static int RootCornerInt( const char *rootcorner, int *status ){ /* * Name: * RootCornerInt * Purpose: * Convert a RootCorner string to an integer. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int RootCornerInt( const char *rootcorner, int *status ) * Class Membership: * Plot3D method. * Description: * This function converts a RootCorner string to an integer. * Parameters: * rootcorner * The string value to convert. Should be 3 characters long * and contain nothing but "U" or "L" (upper or lower case). * status * Pointer to the inherited status variable. * Returned Value: * The integer value that is is the protected equivalent of the * supplied string. A negative value is returned if an error has * already occurred, of the supplied string is not legal. */ /* Local Variables: */ int result; /* Initialise */ result = -1; /* Check the inherited status. */ if( !astOK ) return result; /* Compare thr supplied value with every legal value. */ if( astChrMatch( rootcorner, "LLL" ) ) { result = LLL; } else if( astChrMatch( rootcorner, "ULL" ) ) { result = ULL; } else if( astChrMatch( rootcorner, "LUL" ) ) { result = LUL; } else if( astChrMatch( rootcorner, "UUL" ) ) { result = UUL; } else if( astChrMatch( rootcorner, "LLU" ) ) { result = LLU; } else if( astChrMatch( rootcorner, "ULU" ) ) { result = ULU; } else if( astChrMatch( rootcorner, "LUU" ) ) { result = LUU; } else if( astChrMatch( rootcorner, "UUU" ) ) { result = UUU; } /* Return the result. */ return result; } static const char *RootCornerString( int rootcorner, int *status ){ /* * Name: * RootCornerString * Purpose: * Convert a RootCorner integer to a string. * Type: * Private function. * Synopsis: * #include "plot3d.h" * const char *RootCornerString( int rootcorner, int *status ) * Class Membership: * Plot3D method. * Description: * This function converts a RootCorner integer to a string. * Parameters: * rootcorner * The integer value to convert. Should be in the range 0 to 7. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a static string that is the public equivalent of the * supplied integer. A NULL pointer is returned if an error has * already occurred, of the supplied integer is not legal. */ /* Local Variables: */ char *result; /* Initialise */ result = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Compare thr supplied value with every legal value. */ if( rootcorner == LLL ) { result = "LLL"; } else if( rootcorner == ULL ) { result = "ULL"; } else if( rootcorner == LUL ) { result = "LUL"; } else if( rootcorner == UUL ) { result = "UUL"; } else if( rootcorner == LLU ) { result = "LLU"; } else if( rootcorner == ULU ) { result = "ULU"; } else if( rootcorner == LUU ) { result = "LUU"; } else if( rootcorner == UUU ) { result = "UUU"; } /* Return the result. */ return result; } static void Set3DGrf( AstPlot3D *this, AstPlot *plot, int plane, int *status ){ /* * Name: * Set3DGrf * Purpose: * Associate GRF functions with a Plot. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void Set3DGrf( AstPlot3D *this, AstPlot *plot, int plane, int *status ) * Class Membership: * Plot3D method. * Description: * This function registers grf functions defined in this class with * the supplied Plot, so that, whenever the Plot draws anything, the * plotting request is caught by this class and converted into an * appropriate grf3D call. * Parameters: * this * Pointer to the Plot3D. * plot * Pointer to the Plot. * plane * An integer identifier for the plane within 3D GRAPHICS * coordinates upon which the supplied Plot should draw. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstKeyMap *grfcon; /* Check the global error status. */ if ( !astOK ) return; /* Register the plotting functions defined in this class, so that the plot will call these functions to do its 2D plotting. */ astGrfSet( plot, "Attr", (AstGrfFun) Plot3DAttr ); astGrfSet( plot, "Cap", (AstGrfFun) Plot3DCap ); astGrfSet( plot, "Flush", (AstGrfFun) Plot3DFlush ); astGrfSet( plot, "Line", (AstGrfFun) Plot3DLine ); astGrfSet( plot, "Mark", (AstGrfFun) Plot3DMark ); astGrfSet( plot, "Qch", (AstGrfFun) Plot3DQch ); astGrfSet( plot, "Scales", (AstGrfFun) Plot3DScales ); astGrfSet( plot, "Text", (AstGrfFun) Plot3DText ); astGrfSet( plot, "TxExt", (AstGrfFun) Plot3DTxExt ); /* Ensure that the Plot uses the grf interface registered using astGrfSet. */ astSetGrf( plot, 1 ); /* When the above functions are called, they need to know which plane they are drawing on. So we put this information into the GrfContext KeyMap stored in the Plot. This KeyMap will be passed to the above drawing functions when they are called from within the Plot class. */ grfcon = astGetGrfContext( plot ); astMapPut0I( grfcon, "Plane", plane, "The 2D plane being drawn on" ); if( plane == XY ) { astMapPut0D( grfcon, "Gcon", this->gbox[2], "Constant Z value" ); } else if( plane == XZ ) { astMapPut0D( grfcon, "Gcon", this->gbox[1], "Constant Y value" ); } else { astMapPut0D( grfcon, "Gcon", this->gbox[0], "Constant X value" ); } astMapPut0I( grfcon, "RootCorner", astGetRootCorner(this), "The labelled corner" ); grfcon = astAnnul( grfcon ); } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Plot3D member function (over-rides the astSetAttrib protected * method inherited from the Plot class). * Description: * This function assigns an attribute value for a Plot3D, 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 Plot3D. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot *plot; /* Pointer to specific Plot */ AstPlot3D *this; /* Pointer to the Plot3D structure */ char pat[30]; /* Regular expression pattern */ char spec[10]; /* Plane specification */ const char *null = ""; /* Pointer to null string */ const char *psetting; /* Pointer to plot-specific attrib setting */ double dval; /* Floating point attribute value */ int axis; /* Axis index */ int ival; /* Int attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Norm(axis). */ /* ----------- */ if ( nc = 0, ( 2 == astSscanf( setting, "norm(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetNorm( this, axis - 1, dval ); /* RootCorner. */ /* ----------- */ } else if( nc = 0, ( 0 == astSscanf( setting, "rootcorner=%n%*[^\n]%n", &ival, &nc ) ) && ( nc >= len ) ) { ival = RootCornerInt( setting + ival, status ); if( astOK && ival < 0 ) { astError( AST__ATTIN, "astSetAttrib(Plot3D): Unusable value \"%s\" " "given for attribute RootCorner.", status, setting + ival ); } else { astSetRootCorner( this, ival ); } /* ..._XY etc */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "%*[a-z]_%[xyz]%n", spec, &nc ) ) ) { if( !strcmp( spec, "xy" ) || !strcmp( spec, "yx" ) ) { plot = this->plotxy; } else if( !strcmp( spec, "xz" ) || !strcmp( spec, "zx" ) ) { plot = this->plotyz; } else if( !strcmp( spec, "yz" ) || !strcmp( spec, "zy" ) ) { plot = this->plotxz; } else { plot = NULL; } if( plot ) { sprintf( pat, ".*(_%s).*", spec ); psetting = astChrSub( setting, pat, &null, 1 ); astSetAttrib( plot, psetting ); psetting = astFree( (void *) psetting ); } else { (*parent_setattrib)( this_object, setting, status ); } /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static void SetCurrent( AstFrameSet *this_frameset, int iframe, int *status ) { /* * Name: * SetCurrent * Purpose: * Set a value for the Current attribute of a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int astSetCurrent( AstFrameSet *this, int iframe, int *status ) * Class Membership: * Plot3D member function (over-rides the public astSetCurrent method * inherited from the FrameSet class). * Description: * This function sets a value for the Current attribute of a * Plot3D. This attribute is an index that identifies the current * Frame for the Plot3D. * Parameters: * this * Pointer to the Plot3D. * iframe * Value to be set for the Current attribute. * status * Pointer to the inherited status variable. */ /* Invoke the parent astSetCurrent method. */ (*parent_setcurrent)( this_frameset, iframe, status ); /* Update the three 2D Plots stored in the Plot3D structure so that they reflect this modified FrameSet. */ UpdatePlots( (AstPlot3D *) this_frameset, status ); } static void SetPlotAttr( AstPlot *plot, int plane, int label[ 2 ], int *status ){ /* * Name: * SetPlotAttr * Purpose: * Set the attributes ofr one of the encapsulated Plots. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void SetPlotAttr( AstPlot *plot, int plane, int label[ 2 ], int *status ) * Class Membership: * Plot3D method. * Description: * This function sets the attributes of one of the encapsulated Plots. * Parameters: * plot * Pointer to the Plot to modify. * plane * The 3D plane spanned by the 2D plot. * label * Array indicating if each WCS axis should be labelled or not. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int axis; /* Check the inherited status. */ if( !astOK ) return; /* Ensure that the Plot uses the grf interface registered using astGrfSet. */ astSetGrf( plot, 1 ); /* Ensure that no title is drawn. */ astSetDrawTitle( plot, 0 ); /* For each axis, ensure that no axis labels or ticks are produced unless the axis is indicated as a labelled axis in the supplied array. */ for( axis = 0; axis < 2; axis++ ) { if( !label[ axis ] ) { astSetLabelUnits( plot, axis, 0 ); astSetNumLab( plot, axis, 0 ); astSetTextLab( plot, axis, 0 ); } } } static void SetRootCorner( AstPlot3D *this, int rootcorner, int *status ){ /* *+ * Name: * astSetRootCorner * Purpose: * Set a new value for the RootCorner attribute. * Type: * Protected virtual function. * Synopsis: * #include "plot3d.h" * void astSetRootCorner( AstPlot3D *this, int rootcorner ) * Class Membership: * Plot method. * Description: * This function sets a new value for the RootCorner attribute. * Parameters: * this * Pointer to a Plot3D. * rootcorner * The new RootCorner value. *- */ /* Check the global status. */ if( !astOK ) return; /* Report an error if the new value is out of bounds. */ if( rootcorner < 0 || rootcorner > 7 ){ astError( AST__ATTIN, "astSetRootCorner(Plot3D): Invalid value %d " "supplied for RootCorner attribute", status,rootcorner); /* If the new corner is OK, mirror any axes of the encapsulated Plots that need mirroring (this is done to ensure that Plots look right when viewed from the outside of the graphics cube), and modify the Edge attributes in the encapsulated Plots to ensure the labels appear on the requested edges of the 3D graphics cube. . */ } else { ChangeRootCorner( this, astGetRootCorner(this), rootcorner, status ); /* Store the new value. */ this->rootcorner = rootcorner; } } static void SetTickValues( AstPlot *this, int axis, int nmajor, double *major, int nminor, double *minor, int *status ){ /* * Name: * SetTickValues * Purpose: * Store the tick mark values to use for a given Plot axis. * Type: * Private member function. * Synopsis: * #include "plot3d.h" * void SetTickValues( AstPlot *this, int axis, int nmajor, * double *major, int nminor, double *minor, int *status ) * Class Membership: * Plot method (overrides the astSetTickValues method inherited form * the Plot class) * Description: * This function stores a set of tick mark values that should be used by * subsequent calls to astGrid. * Parameters: * this * Pointer to a Plot. * axis * The zero-based index of the axis for which tick marks values * have been supplied. * nmajor * The number of major tick mark values. If zero is supplied then * the other parameters are ignored, and subsequent calls to * astGrid will itself determine the tick values to be used. * major * Pointer to an array holding "nmajor" values for axis "axis" in * the current Frame of the suppled Plot. Major tick marks will be * drawn at these values. * nminor * The number of minor tick mark values. * minor * Pointer to an array holding "nminor" values for axis "axis" in * the current Frame of the suppled Plot. Minor tick marks will be * drawn at these values. * status * Pointer to the inherited status variable. */ /* Check the global status. */ if( !astOK ) return; astError( AST__INTER, "astSetTickValues(%s): The astSetTickValues " "method cannot be used with a %s (programming error).", status, astGetClass( this ), astGetClass( this ) ); } static void SplitFrameSet( AstFrameSet *fset, AstFrameSet **fsetxy, int labelxy[2], int wcsxy[2], AstFrameSet **fsetxz, int labelxz[2], int wcsxz[2], AstFrameSet **fsetyz, int labelyz[2], int wcsyz[2], int *baseplane, int *status ){ /* * Name: * SplitFrameSet * Purpose: * Split a 3D FrameSet into three 2D FrameSets. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void SplitFrameSet( AstFrameSet *fset, * AstFrameSet **fsetxy, int labelxy[2], int wcsxy[2], * AstFrameSet **fsetxz, int labelxz[2], int wcsxz[2], * AstFrameSet **fsetyz, int labelyz[2], int wcsyz[2], * int *baseplane, int *status ) * Class Membership: * Plot3D member function * Description: * This function returns 3 FrameSets, each of which has 2-dimensional * base and current Frames. Each of the 2D base Frames span a single * plane in the 3D base Frame of the supplied FrameSet. Likewise, each * of the 2D current Frames span a single plane in the 3D current Frame * of the supplied FrameSet. An error is reported if there is no * one-to-one association between the three planes in the supplied * current Frame and the 3 planes in the supplied base Frame. * Parameters: * fset * Pointer to a FrameSet that has a 3D base Frame and a 3D current * Frame. * fsetxy * Pointer to a location at which to return a pointer to a new FrameSet * that has a 2D base Frame and a 2D current. The base Frame spans * axes 1 and 2 of the 3D base Frame in "fset". * labelxy * Returned holding flags indicating if the two axes of the current * Frame in *fsetxy should be labelled or not. * wcsxy * Returned holding the zero based axis index within the current Frame * of the supplied FrameSet that corresponds to each of the two * current Frame axes in the "fsetxy" FrameSet. * fsetxz * Pointer to a location at which to return a pointer to a new FrameSet * that has a 2D base Frame and a 2D current. The base Frame spans * axes 1 and 3 of the 3D base Frame in "fset". * labelxz * Returned holding flags indicating if the two axes of the current * Frame in *fsetxz should be labelled or not. * wcsxz * Returned holding the zero based axis index within the current Frame * of the supplied FrameSet that corresponds to each of the two * current Frame axes in the "fsetxz" FrameSet. * fsetyz * Pointer to a location at which to return a pointer to a new FrameSet * that has a 2D base Frame and a 2D current. The base Frame spans * axes 2 and 3 of the 3D base Frame in "fset". * labelyz * Returned holding flags indicating if the two axes of the current * Frame in *fsetyz should be labelled or not. * wcsyz * Returned holding the zero based axis index within the current Frame * of the supplied FrameSet that corresponds to each of the two * current Frame axes in the "fsetxy" FrameSet. * baseplane * Index of the plane that is spanned by two connected 3D axes. * status * Pointer to the inherited status variable. * Notes: * - Null pointers will be returned for the three new FrameSets if this * function is invoked with the global status set, or if it should fail * for any reason. * - Each returned FrameSet has 2 Frames: Frame 1 is the base Frame * and is spanned by 2 of the 3 axes in the base Frame of the supplied * FrameSet; Frame 2 is the current Frame and is spanned by 2 of the 3 * axes in the current Frame of the supplied FrameSet. Any future changes * to this function that alter this structure should reflected in * equivalent changes to functions CreatePlots and UpdatePlots. */ /* Local Variables: */ AstFrame *bfrm2d; AstFrame *bfrm; AstFrame *cfrm1d; AstFrame *cfrm2d; AstFrame *cfrm; AstFrame *dummy; AstFrameSet *fset1; AstFrameSet *fset2; AstFrameSet *fset3; AstMapping *map1d; AstMapping *map2d; AstMapping *map; AstMapping *smap; AstUnitMap *unit1d; int *axout; int *other_axout; int axin2[ 2 ]; int axin[ 2 ]; int i; int label1[ 2 ]; int label2[ 2 ]; int label3[ 2 ]; int other_axin; int wcsax1[ 2 ]; int wcsax2[ 2 ]; int wcsax3[ 2 ]; /* Initialise. */ *fsetxy = NULL; *fsetxz = NULL; *fsetyz = NULL; *baseplane = 0; /* Check the global error status. */ if ( !astOK ) return; /* Get the simplified base -> current Mapping form the supplied FrameSet. Also get the base and current Frames themselves. */ map = astGetMapping( fset, AST__BASE, AST__CURRENT ); smap = astSimplify( map ); map = astAnnul( map ); cfrm = astGetFrame( fset, AST__CURRENT ); bfrm = astGetFrame( fset, AST__BASE ); /* Create a 1D UnitMap. */ unit1d = astUnitMap( 1, "", status ); /* First try to identify a pair of base Frame axes that map onto a pair of current Frame axes. This will be the case for instance if the 3D FrameSet describes a spectral cube in which two of the axes are spanned by a SkyFrame. We try all three possible pairs of axes in turn until a pair is found succesfully. */ for( i = 0; i < 3 && ! *fsetxy; i++ ) { axin[ 0 ] = ( i < 2 ) ? 0 : 1; axin[ 1 ] = ( i == 0 ) ? 1 : 2; /* Try to get a Mapping that connects the inputs given by axin to a distinct subset of outputs. */ axout = astMapSplit( smap, 2, axin, &map2d ); /* If succesful, check that the 2 inputs correspond to exactly 2 outputs. */ if( map2d ){ if( astGetNout( map2d ) == 2 ) { /* Get the index of the other input axis (the one not included in the pair). */ other_axin = 3 - axin[ 0 ] - axin[ 1 ]; /* Try to get a Mapping that connects this remaining input to a distinct subset of outputs. */ other_axout = astMapSplit( smap, 1, &other_axin, &map1d ); /* If succesful, check that the 1 input correspond to exactly 1 output. */ if( map1d ){ if( astGetNout( map1d ) == 1 ) { /* Pick the two axes from the 3D base and current Frames that correspond to the paired axes found above. */ bfrm2d = astPickAxes( bfrm, 2, axin, NULL ); cfrm2d = astPickAxes( cfrm, 2, axout, NULL ); /* Pick the axis from the 3D current Frame that correspond to the other axis. */ cfrm1d = astPickAxes( cfrm, 1, other_axout, NULL ); /* Construct a FrameSet using these 2D Frames and Mapping. */ fset1 = astFrameSet( bfrm2d, "", status ); astAddFrame( fset1, AST__BASE, map2d, cfrm2d ); bfrm2d = astAnnul( bfrm2d ); cfrm2d = astAnnul( cfrm2d ); map2d = astAnnul( map2d ); /* Indicate that both axes in the current Frame of this FrameSet should be labelled. */ label1[ 0 ] = 1; label1[ 1 ] = 1; /* Store the index of the axis within the supplied current Frame that corresponds to each axis in the current Frame of the FrameSet created above. */ wcsax1[ 0 ] = axout[ 0 ]; wcsax1[ 1 ] = axout[ 1 ]; /* Pick the two axes from the 3D base Frame that correspond to the first of the paired axes, and the unpaired axis. Order them so that we get the 2 axes in the order xy, xz or yz. Also, store the index of the axis within the supplied current Frame that corresponds to each axis in the current Frame of the FrameSet created below. */ if( i < 2 ) { axin2[ 0 ] = axin[ 0 ]; axin2[ 1 ] = other_axin; wcsax2[ 0 ] = axout[ 0 ]; wcsax2[ 1 ] = other_axout[ 0 ]; } else { axin2[ 0 ] = other_axin; axin2[ 1 ] = axin[ 0 ]; wcsax2[ 0 ] = other_axout[ 0 ]; wcsax2[ 1 ] = axout[ 0 ]; } bfrm2d = astPickAxes( bfrm, 2, axin2, NULL ); /* The corresponding current Frame in the new FrameSet will be a compound 2D Frame holding the other current Frame axis and a copy of the input base Frame axis. Combine them so that we get the 2 axes in the order xy, xz or yz. */ dummy = astPickAxes( bfrm, 1, axin, NULL ); if( i < 2 ) { cfrm2d = (AstFrame *) astCmpFrame( dummy, cfrm1d, "", status ); } else { cfrm2d = (AstFrame *) astCmpFrame( cfrm1d, dummy, "", status ); } dummy = astAnnul( dummy ); /* The Mapping that joins this 2D base Frame to the 2D current Frame uses the above 1D mapping for the other axis, and a UnitMap for the copied base Frame axis. */ if( i < 2 ) { map2d = (AstMapping *) astCmpMap( unit1d, map1d, 0, "", status ); } else { map2d = (AstMapping *) astCmpMap( map1d, unit1d, 0, "", status ); } /* Construct a FrameSet using these 2D Frames and Mapping. */ fset2 = astFrameSet( bfrm2d, "", status ); astAddFrame( fset2, AST__BASE, map2d, cfrm2d ); bfrm2d = astAnnul( bfrm2d ); cfrm2d = astAnnul( cfrm2d ); map2d = astAnnul( map2d ); /* Indicate that only one of the axes in the current Frame of this FrameSet should be labelled. */ if( i < 2 ) { label2[ 0 ] = 0; label2[ 1 ] = 1; } else { label2[ 0 ] = 1; label2[ 1 ] = 0; } /* Pick the two axes from the 3D base Frame that correspond to the second of the paired axes, and the unpaired axis. Order them so that we get the 2 axes in the order xy, xz or yz. Also, store the index of the axis within the supplied current Frame that corresponds to each axis in the current Frame of the FrameSet created below. */ if( i == 0 ) { axin2[ 0 ] = axin[ 1 ]; axin2[ 1 ] = other_axin; wcsax3[ 0 ] = axout[ 1 ]; wcsax3[ 1 ] = other_axout[ 0 ]; } else { axin2[ 0 ] = other_axin; axin2[ 1 ] = axin[ 1 ]; wcsax3[ 0 ] = other_axout[ 0 ]; wcsax3[ 1 ] = axout[ 1 ]; } bfrm2d = astPickAxes( bfrm, 2, axin2, NULL ); /* The corresponding current Frame in the new FrameSet will be a compound 2D Frame holding the other current Frame axis and a copy of the input base Frame axis. Combine them so that we get the 2 axes in the order xy, xz or yz. */ dummy = astPickAxes( bfrm, 1, axin + 1, NULL ); if( i == 0 ) { cfrm2d = (AstFrame *) astCmpFrame( dummy, cfrm1d, "", status ); } else { cfrm2d = (AstFrame *) astCmpFrame( cfrm1d, dummy, "", status ); } dummy = astAnnul( dummy ); /* The Mapping that joins this 2D base Frame to the 2D current Frame uses the above 1D mapping for the other axis, and a UnitMap for the copied base Frame axis. */ if( i == 0 ) { map2d = (AstMapping *) astCmpMap( unit1d, map1d, 0, "", status ); } else { map2d = (AstMapping *) astCmpMap( map1d, unit1d, 0, "", status ); } /* Construct a FrameSet using these 2D Frames and Mapping. */ fset3 = astFrameSet( bfrm2d, "", status ); astAddFrame( fset3, AST__BASE, map2d, cfrm2d ); bfrm2d = astAnnul( bfrm2d ); cfrm2d = astAnnul( cfrm2d ); map2d = astAnnul( map2d ); /* Indicate that neither axis in the current Frame of this FrameSet should be labelled. */ label3[ 0 ] = 0; label3[ 1 ] = 0; /* Store each FrameSet in the correct returned pointer. */ if( i == 0 ) { *baseplane = XY; *fsetxy = fset1; *fsetxz = fset2; *fsetyz = fset3; labelxy[ 0 ] = label1[ 0 ]; labelxy[ 1 ] = label1[ 1 ]; labelxz[ 0 ] = label2[ 0 ]; labelxz[ 1 ] = label2[ 1 ]; labelyz[ 0 ] = label3[ 0 ]; labelyz[ 1 ] = label3[ 1 ]; wcsxy[ 0 ] = wcsax1[ 0 ]; wcsxy[ 1 ] = wcsax1[ 1 ]; wcsxz[ 0 ] = wcsax2[ 0 ]; wcsxz[ 1 ] = wcsax2[ 1 ]; wcsyz[ 0 ] = wcsax3[ 0 ]; wcsyz[ 1 ] = wcsax3[ 1 ]; } else if( i == 1 ) { *baseplane = XZ; *fsetxy = fset2; *fsetxz = fset1; *fsetyz = fset3; labelxy[ 0 ] = label2[ 0 ]; labelxy[ 1 ] = label2[ 1 ]; labelxz[ 0 ] = label1[ 0 ]; labelxz[ 1 ] = label1[ 1 ]; labelyz[ 0 ] = label3[ 0 ]; labelyz[ 1 ] = label3[ 1 ]; wcsxy[ 0 ] = wcsax2[ 0 ]; wcsxy[ 1 ] = wcsax2[ 1 ]; wcsxz[ 0 ] = wcsax1[ 0 ]; wcsxz[ 1 ] = wcsax1[ 1 ]; wcsyz[ 0 ] = wcsax3[ 0 ]; wcsyz[ 1 ] = wcsax3[ 1 ]; } else { *baseplane = YZ; *fsetxy = fset2; *fsetxz = fset3; *fsetyz = fset1; labelxy[ 0 ] = label2[ 0 ]; labelxy[ 1 ] = label2[ 1 ]; labelxz[ 0 ] = label3[ 0 ]; labelxz[ 1 ] = label3[ 1 ]; labelyz[ 0 ] = label1[ 0 ]; labelyz[ 1 ] = label1[ 1 ]; wcsxy[ 0 ] = wcsax2[ 0 ]; wcsxy[ 1 ] = wcsax2[ 1 ]; wcsxz[ 0 ] = wcsax3[ 0 ]; wcsxz[ 1 ] = wcsax3[ 1 ]; wcsyz[ 0 ] = wcsax1[ 0 ]; wcsyz[ 1 ] = wcsax1[ 1 ]; } /* Free resources */ cfrm1d = astAnnul( cfrm1d ); } /* Free resources */ map1d = astAnnul( map1d ); other_axout = astFree( other_axout ); } } /* Free resources */ if( map2d ) map2d = astAnnul( map2d ); axout = astFree( axout ); /* Leave the loop if we now have the required FrameSets, or an error has occurred. */ if( *fsetxy || !astOK ) break; } } /* Free resources */ cfrm = astAnnul( cfrm ); bfrm = astAnnul( bfrm ); smap = astAnnul( smap ); unit1d = astAnnul( unit1d ); /* Return null pointers if an error has occurred. */ if( !astOK ) { *fsetxy = astAnnul( *fsetxy ); *fsetxz = astAnnul( *fsetxz ); *fsetyz = astAnnul( *fsetyz ); /* Report an error if the supplied FrameSet could not be split into 3 independent 2D planes. */ } if( ! *fsetxy ) { astError( AST__3DFSET, "astInitPlot3D(Plot3D): Supplied %s contains " "no independent axes.", status, astGetClass( fset ) ); } } static void StoreAxisInfo( AstPlot3D *this, int labelxy[2], int wcsxy[2], int labelxz[2], int wcsxz[2], int labelyz[2], int wcsyz[2], int *status ) { /* * Name: * StoreAxisInfo * Purpose: * Store information connecting 3D axis with associuated 2D Plot axes. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void StoreAxisInfo( AstPlot3D *this, int labelxy[2], int wcsxy[2], * int labelxz[2], int wcsxz[2], int labelyz[2], * int wcsyz[2], int *status ) * Class Membership: * Plot3D method. * Description: * This function stores information inside the Plot3D that allows each * 3D axis to be associated with the 2 Plots that share the 3D axis, * and with the axis index within each of these two Plots. * Parameters: * this * Pointer to the Plot3D. * labelxy * Flags indicating if the two axes of the current Frame in the XY * Plot should be labelled or not. * wcsxy * The zero based axis index within the 3D current Frame that * corresponds to each of the two current Frame axes in the XY Plot. * A value of -1 should be used for 2D axes that do not correspond * to any 3D axis. * labelxz * Flags indicating if the two axes of the current Frame in the XZ * Plot should be labelled or not. * wcsxz * The zero based axis index within the 3D current Frame that * corresponds to each of the two current Frame axes in the XZ Plot. * A value of -1 should be used for 2D axes that do not correspond * to any 3D axis. * labelyz * Flags indicating if the two axes of the current Frame in the YZ * Plot should be labelled or not. * wcsyz * The zero based axis index within the 3D current Frame that * corresponds to each of the two current Frame axes in the YZ Plot. * A value of -1 should be used for 2D axes that do not correspond * to any 3D axis. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int axis2d; int axis3d; int gotfirst; int gotsecond; int temp; /* Check the inherited status. */ if( !astOK ) return; /* Store information that allows each 3D WCS axis to be associated with a pair of Plots. Also store the WCS axis within each Plot that corresponds to the 3D WCS axis. Do each 3D WCS axis in turn. */ for( axis3d = 0; axis3d < 3; axis3d++ ) { /* Indicate we have not yet found either of the two Plots that share the current 3D axis. */ gotfirst = 0; gotsecond = 0; /* Check each of the 2 axes in the plot spanning the XY face of the 3D graphics cube. Break early if we have found both Plots for the current 3D WCS axis. */ for( axis2d = 0; axis2d < 2 && !gotsecond; axis2d++ ) { /* See if this 2D axis corresponds to the required 3D axis. If so, store the Plot identifier and the 2D axis index. */ if( wcsxy[ axis2d ] == axis3d ) { if( gotfirst ) { this->axis_plot2[ axis3d ] = XY; this->axis_index2[ axis3d ] = axis2d; gotsecond = 1; } else { this->axis_plot1[ axis3d ] = XY; this->axis_index1[ axis3d ] = axis2d; gotfirst = 1; } } } /* Check the plot spanning the XZ face in the same way. */ for( axis2d = 0; axis2d < 2 && !gotsecond; axis2d++ ) { if( wcsxz[ axis2d ] == axis3d ) { if( gotfirst ) { this->axis_plot2[ axis3d ] = XZ; this->axis_index2[ axis3d ] = axis2d; gotsecond = 1; } else { this->axis_plot1[ axis3d ] = XZ; this->axis_index1[ axis3d ] = axis2d; gotfirst = 1; } } } /* Check the plot spanning the YZ face in the same way. */ for( axis2d = 0; axis2d < 2 && !gotsecond; axis2d++ ) { if( wcsyz[ axis2d ] == axis3d ) { if( gotfirst ) { this->axis_plot2[ axis3d ] = YZ; this->axis_index2[ axis3d ] = axis2d; gotsecond = 1; } else { this->axis_plot1[ axis3d ] = YZ; this->axis_index1[ axis3d ] = axis2d; gotfirst = 1; } } } } /* Ensure that the first Plot within each pair is the one that is used to generate labels for the 3D axis. */ for( axis2d = 0; axis2d < 2; axis2d++ ) { if( labelxy[ axis2d ] ) { axis3d = wcsxy[ axis2d ]; if( this->axis_plot1[ axis3d ] != XY ){ temp = this->axis_plot1[ axis3d ]; this->axis_plot1[ axis3d ] = this->axis_plot2[ axis3d ]; this->axis_plot2[ axis3d ] = temp; temp = this->axis_index1[ axis3d ]; this->axis_index1[ axis3d ] = this->axis_index2[ axis3d ]; this->axis_index1[ axis3d ] = temp; } } } for( axis2d = 0; axis2d < 2; axis2d++ ) { if( labelxz[ axis2d ] ) { axis3d = wcsxz[ axis2d ]; if( this->axis_plot1[ axis3d ] != XZ ){ temp = this->axis_plot1[ axis3d ]; this->axis_plot1[ axis3d ] = this->axis_plot2[ axis3d ]; this->axis_plot2[ axis3d ] = temp; temp = this->axis_index1[ axis3d ]; this->axis_index1[ axis3d ] = this->axis_index2[ axis3d ]; this->axis_index1[ axis3d ] = temp; } } } for( axis2d = 0; axis2d < 2; axis2d++ ) { if( labelyz[ axis2d ] ) { axis3d = wcsyz[ axis2d ]; if( this->axis_plot1[ axis3d ] != YZ ){ temp = this->axis_plot1[ axis3d ]; this->axis_plot1[ axis3d ] = this->axis_plot2[ axis3d ]; this->axis_plot2[ axis3d ] = temp; temp = this->axis_index1[ axis3d ]; this->axis_index1[ axis3d ] = this->axis_index2[ axis3d ]; this->axis_index1[ axis3d ] = temp; } } } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot3D member function (over-rides the astTestAttrib protected * method inherited from the Plot class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Plot3D's attributes. * Parameters: * this * Pointer to the Plot3D. * 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: */ AstPlot *plot; /* Pointer to specific Plot */ AstPlot3D *this; /* Pointer to the Plot3D structure */ char attname[50]; /* Plot attribute base name */ char patt[50]; /* Plot attribute full name */ char spec[10]; /* Plane specification */ int axis; /* Axis index */ int len; /* Length of attrib string */ int nc; /* Number of character read */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* Norm. */ /* ----- */ if ( !strcmp( attrib, "norm" ) ) { result = astTestNorm( this, 0 ) || astTestNorm( this, 1 ) || astTestNorm( this, 2 ); /* Norm(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "norm(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestNorm( this, axis - 1 ); /* RootCorner. */ /* ----------- */ } else if ( !strcmp( attrib, "rootcorner" ) ) { result = astTestRootCorner( this ); /* ..._XY etc */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( attrib, "%[a-z]_%[xyz]%n", attname, spec, &nc ) ) ) { if( !strcmp( spec, "xy" ) || !strcmp( spec, "yx" ) ) { plot = this->plotxy; } else if( !strcmp( spec, "xz" ) || !strcmp( spec, "zx" ) ) { plot = this->plotyz; } else if( !strcmp( spec, "yz" ) || !strcmp( spec, "zy" ) ) { plot = this->plotxz; } else { plot = NULL; } if( plot ) { sprintf( patt, "%s%s", attname, attrib + nc ); result = astTestAttrib( plot, patt ); } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static void Text( AstPlot *this_plot, const char *text, const double pos[], const float up[], const char *just, int *status ){ /* * Name: * Text * Purpose: * Draw a text string for a Plot3D. * Type: * Private member function. * Synopsis: * #include "plot3d.h" * void Text( AstPlot *this, const char *text, const double pos[], * const float up[], const char *just, int *status ) * Class Membership: * Plot3D method (overrides the Text method inherited form the Plot * class). * Description: * This function draws a string of text at a position specified in * the physical coordinate system of a Plot3D. The physical position * is transformed into graphical coordinates to determine where the * text should appear within the plotting area. * * The text is drawn on a 2D plane that has a normal vector given by the * current value of the Plot3D's "Norm" attribute. * Parameters: * this * Pointer to the Plot3D. * text * Pointer to a null-terminated character string containing the * text to be drawn. Trailing white space is ignored. * pos * An array, with one element for each axis of the Plot3D, giving * the physical coordinates of the point where the reference * position of the text string is to be placed. * up * An array holding the components of a vector in the "up" * direction of the text (in graphical coordinates). For * example, to get horizontal text, the vector {0.0f,1.0f} should * be supplied. "Up" is taken to be the projection of the positive * Z axis onto the plane specified by the current value of the * just * Pointer to a null-terminated character string identifying the * reference point for the text being drawn. The first character in * this string identifies the reference position in the "up" direction * and may be "B" (baseline), "C" (centre), "T" (top) or "M" (bottom). * The second character identifies the side-to-side reference position * and may be "L" (left), "C" (centre) or "R" (right ). The string is * case-insensitive, and only the first two characters are significant. * * For example, a value of "BL" means that the left end of the * baseline of the original (un-rotated) text is to be drawn at the * position given by "pos". * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMapping *mapping; /* Pointer to graphics->physical mapping */ AstPlot3D *this; /* Pointer to the Plot3D structure */ AstPointSet *pset1; /* PointSet holding physical positions */ AstPointSet *pset2; /* PointSet holding graphics positions */ char *ltext; /* Local copy of "text" excluding trailing spaces */ char ljust[3]; /* Upper case copy of "just" */ const char *class; /* Object class */ const char *method; /* Current method */ const double **ptr1; /* Pointer to physical positions */ double **ptr2; /* Pointer to graphics positions */ float norm[ 3 ]; /* Single precision normal vector */ float ref[ 3 ]; /* Single precision ref position */ int axis; /* Axis index */ int escs; /* Original astEscapes value */ int naxes; /* No. of axes in the base Frame */ int ncoord; /* No. of axes in the current Frame */ int ulen; /* Length of "text" excluding trailing spaces */ /* Check the global error status. */ if ( !astOK || !text ) return; /* Store a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_plot; /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astText"; class = astClass( this ); /* Check the base Frame of the Plot is 3-D. */ naxes = astGetNin( this ); if( naxes != 3 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 3.", status, method, class, naxes, class ); } /* Ensure AST functions do not included graphical escape sequences in any returned text strings. This is because the Plot3D implementation of this method cannot currently handle graphical escape sequences. */ escs = astEscapes( 0 ); /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__TEXT_ID, 1, GRF__TEXT, method, class ); /* Get the number of coordinates in the physical coordinate frame. */ ncoord = astGetNout( this ); /* Create a PointSet to hold the supplied physical coordinates. */ pset1 = astPointSet( 1, ncoord, "", status ); /* Allocate memory to hold pointers to the first value on each axis. */ ptr1 = (const double **) astMalloc( sizeof( const double * )* (size_t)( ncoord )); /* Check the pointer can be used, then store pointers to the first value on each axis. */ if( astOK ){ for( axis = 0; axis < ncoord; axis++ ){ ptr1[ axis ] = pos + axis; } } /* Store these pointers in the PointSet. */ astSetPoints( pset1, (double **) ptr1 ); /* Transform the supplied data from the current frame (i.e. physical coordinates) to the base frame (i.e. graphics coordinates) using the inverse Mapping defined by the Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); pset2 = astTransform( mapping, pset1, 0, NULL ); mapping = astAnnul( mapping ); /* Get pointers to the graphics coordinates. */ ptr2 = astGetPoints( pset2 ); /* Take a copy of the string excluding any trailing white space. */ ulen = astChrLen( text ); ltext = (char *) astStore( NULL, (void *) text, ulen + 1 ); /* Check the pointers can be used. */ if( astOK ){ /* Terminate the local copy of the text string. */ ltext[ ulen ] = 0; /* Produce an upper-case copy of the first two characters in "just". */ ljust[0] = (char) toupper( (int) just[0] ); ljust[1] = (char) toupper( (int) just[1] ); ljust[2] = 0; /* Convert the double precision values to single precision, checking for bad positions. */ if( ptr2[0][0] != AST__BAD && ptr2[1][0] != AST__BAD && ptr2[2][0] != AST__BAD ){ ref[ 0 ] = (float) ptr2[0][0]; ref[ 1 ] = (float) ptr2[1][0]; ref[ 2 ] = (float) ptr2[2][0]; /* If the nornmal vector has non-zero length, draw the text. */ norm[ 0 ] = (float) astGetNorm( this, 0 ); norm[ 1 ] = (float) astGetNorm( this, 1 ); norm[ 2 ] = (float) astGetNorm( this, 2 ); /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; if( norm[ 0 ] != 0.0 || norm[ 1 ] != 0.0 || norm[ 2 ] != 0.0 ){ if( !astG3DText( ltext, ref, ljust, (float *) up, norm ) ) { astError( AST__GRFER, "%s(%s): Graphics error in astG3DText. ", status, method, class ); } } else if( astOK ) { astError( AST__ATTIN, "%s(%s): The vector specified by the Norm " "attribute has zero length.", status, method, class ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; } /* Free the local copy of the string. */ ltext = (char *) astFree( (void *) ltext ); } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free the memory holding the pointers to the first value on each axis. */ ptr1 = (const double **) astFree( (void *) ptr1 ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__TEXT_ID, 0, GRF__TEXT, method, class ); /* Restore the original value of the flag which says whether graphical escape sequences should be incldued in any returned text strings. */ astEscapes( escs ); /* Return */ return; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Use a Plot to transform a set of points. * Type: * Private function. * Synopsis: * #include "plot3d.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Plot3D member function (over-rides the astTransform protected * method inherited from the Plot class). * Description: * This function takes a Plot3D and a set of points encapsulated in a * PointSet and transforms the points from graphics coordinates to * physical coordinates (in the forward direction). No clipping or * normalisation is applied. * Parameters: * this * Pointer to the Plot3D. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Plot being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstMapping *map; /* Pointer to the mapping */ AstPointSet *result; /* Positions in output Frame */ AstPlot3D *this; /* The Plot3D */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the Plot3D. */ this = (AstPlot3D *) this_mapping; /* Get the Mapping from the base to the current Frame. */ map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Do the transformation. */ result = astTransform( map, in, forward, out ); /* Annul the mapping. */ map = astAnnul( map ); /* If an error has occurred, annul the result. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static void UpdatePlots( AstPlot3D *this, int *status ) { /* * Name: * UpdatePlots * Purpose: * Update the three 2D plots stored in the Plot3D. * Type: * Private function. * Synopsis: * #include "plot3d.h" * void UpdatePlots( AstPlot3D *this ) * Class Membership: * Plot3D method. * Description: * This function splits the parent FrameSet up into 3 independent 2D * FrameSets, each describing a 2D plane in the supplied 3D FrameSet. * It then uses these 2D FrameSets to update the three Plots in the * Plot3D, by removing the existing current Frame and adding in the * new current Frame with the associated Mapping. * Parameters: * this * Pointer to the Plot3D. * Notes: * - Each of the 3 plots has 3 Frames: Frame 1 is the base (GRAPHICS) * Frame; Frame 2 is spanned by 2 of the 3 axes in the base Frame of * the supplied FrameSet; Frame 3 is the current Frame and is spanned * by 2 of the 3 axes in the current Frame of the supplied FrameSet. * Any future changes to this function that alter this structure should * reflected in equivalewnt changes to function CreatePlots. */ /* Local Variables: */ AstFrame *frm; AstFrameSet *fsetxy; AstFrameSet *fsetxz; AstFrameSet *fsetyz; AstFrameSet *fset; AstMapping *map; int baseplane; int labelxy[ 2 ]; int labelxz[ 2 ]; int labelyz[ 2 ]; int wcsxy[ 2 ]; int wcsxz[ 2 ]; int wcsyz[ 2 ]; int rootcorner; /* Check the inherited status. */ if( !astOK ) return; /* Return without action if the Plot3D does not contain the three 2D Plots. This may be the case for instance if this function is called before the Plot3D is fully constructed. */ if( this->plotxy && this->plotxz && this->plotyz ){ /* We need a FrameSet that is equivalent to the one that was used to construct the Plot3D (i.e. a FrameSet that does not have the GRAPHICS Frame that was added by the Plot3D constructor). So take a copy of the parent FrameSet, remove the GRAPHICS Frame (Frame 1) and set the base Frame to be the Frame that was the base Frame when the Plot3D was constructed. */ fset = (AstFrameSet *) astCast( this, dummy_frameset ); astSetBase( fset, this->pix_frame ); astRemoveFrame( fset, 1 ); /* Split the supplied FrameSet up into 3 FrameSets, each with a 2D base and current Frame. Each of these FrameSets describes one plane of the 3D cube. */ SplitFrameSet( fset, &fsetxy, labelxy, wcsxy, &fsetxz, labelxz, wcsxz, &fsetyz, labelyz, wcsyz, &baseplane, status ); /* First do the XY Plot. Extract the current Frame and base->current Mapping from the new FrameSet. It is assumed that he base Frame in the new FrameSet is equivalent to Frame 2 in the existing Plot. This assumption is based on the way the CreatePlots and SplitFrameSet functions work, and should be reviewed if either of these functions is changed. */ frm = astGetFrame( fsetxy, 2 ); map = astGetMapping( fsetxy, 1, 2 ); /* Add the new Frame into the existing Plot using the Mapping to connect it to Frame 2 in the Plot. It becomes the current Frame in the Plot. */ astAddFrame( this->plotxy, 2, map, frm ); /* Delete the original current Frame in the Plot since it is not needed any more. */ astRemoveFrame( this->plotxy, 3 ); /* Set the Plot attributes. */ SetPlotAttr( this->plotxy, XY, labelxy, status ); /* Free resources */ fsetxy = astAnnul( fsetxy ); map = astAnnul( map ); frm = astAnnul( frm ); /* Do the same for the XZ plot. */ frm = astGetFrame( fsetxz, 2 ); map = astGetMapping( fsetxz, 1, 2 ); astAddFrame( this->plotxz, 2, map, frm ); astRemoveFrame( this->plotxz, 3 ); SetPlotAttr( this->plotxz, XZ, labelxz, status ); fsetxz = astAnnul( fsetxz ); map = astAnnul( map ); frm = astAnnul( frm ); /* Do the same for the YZ plot. */ frm = astGetFrame( fsetyz, 2 ); map = astGetMapping( fsetyz, 1, 2 ); astAddFrame( this->plotyz, 2, map, frm ); astRemoveFrame( this->plotyz, 3 ); SetPlotAttr( this->plotyz, YZ, labelyz, status ); fsetyz = astAnnul( fsetyz ); map = astAnnul( map ); frm = astAnnul( frm ); /* Store information that allows each 3D WCS axis to be associatedf with a pair of Plots. Also store the WCS axis within each Plot that corresponds to the 3D WCS axis. */ StoreAxisInfo( this, labelxy, wcsxy, labelxz, wcsxz, labelyz, wcsyz, status ); /* Set up the Edges attributes in the encapsulated Plots to produce labels on the required edges of the 3D graphics cube. */ rootcorner = astGetRootCorner( this ); ChangeRootCorner( this, rootcorner, rootcorner, status ); /* Store the plane spanned by two connected 3D axes. */ this->baseplot = baseplane; /* Free remaining resources */ fset = astAnnul( fset ); } } static void VSet( AstObject *this_object, const char *settings, char **text, va_list args, int *status ) { /* * Name: * VSet * Purpose: * Set values for a Plot3D'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: * Plot3D member function (over-rides the protected astVSet * method inherited from the Object class). * Description: * This function assigns a set of attribute values for a Plot3D, * 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 Plot3D. * 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 Plot3D (if * possible) by appropriately modifying the three encapsulated Plots. */ /* Invoke the parent astVSet method to set the Plot3D's attribute values. */ (*parent_vset)( this_object, settings, text, args, status ); /* Update the three 2D Plots stored in the Plot3D structure so that they reflect this modified FrameSet. */ UpdatePlots( (AstPlot3D *) this_object, status ); } /* Functions which access Plot3D class attributes. */ /* ----------------------------------------------- */ /* RootCorner. */ /* ----------- */ /* *att++ * Name: * RootCorner * Purpose: * Specifies which edges of the 3D box should be annotated. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * which edges of the cube enclosing the 3D graphics space are used * for displaying numerical and descriptive axis labels. The attribute * value identifies one of the eight corners of the cube within * which graphics are being drawn (i.e. the cube specified by the c "graphbox" parameter when astPlot3D f GRAPHBOX argument when AST_PLOT3D * was called tp create the Plot3D). Axis labels and tick marks will * be placed on the three cube edges that meet at the given corner. * * The attribute value should consist of three character, each of * which must be either "U" or "L". The first character in the string * specifies the position of the corner on the first graphics axis. * If the character is "U" then the corner is at the upper bound on the * first graphics axis. If it is "L", then the corner is at the lower * bound on the first axis. Likewise, the second and third characters * in the string specify the location of the corner on the second and * third graphics axes. * * For instance, corner "LLL" is the corner that is at the lower bound * on all three graphics axes, and corner "ULU" is at the upper bound * on axes 1 and 3 but at the lower bound on axis 2. * * The default value is "LLL". * Applicability: * Plot3D * All Plot3Ds have this attribute. *att-- */ /* Internally, the RootCorner is represented as an integer bit mask, with bit zero for the X axis, bit 1 for the Y axis and bit 2 for the Z axis. A bit is set if the corner is at the upper bound on the axis and unset if it is at the lower bound. A value of -1 indicates that the attribue has not been assigned a value. */ astMAKE_GET(Plot3D,RootCorner,int,0,( this->rootcorner == -1 ? 0 : this->rootcorner)) astMAKE_TEST(Plot3D,RootCorner,( this->rootcorner != -1 )) /* Norm(axis). */ /* ----------- */ /* *att++ * Name: * Norm(axis) * Purpose: * Specifies the plane upon which a Plot3D draws text and markers. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of text and markers drawn * by a Plot3D. It specifies the orientation of the plane upon which * text and markers will be drawn by all subsequent invocations of the c astText and astMark functions. f AST_TEXT and AST_MARK functions. * * When setting or getting the Norm attribute, the attribute name must * be qualified by an axis index in the range 1 to 3. The 3 elements of * the Norm attribute are together interpreted as a vector in 3D graphics * coordinates that is normal to the plane upon which text and marks * should be drawn. When testing or clearing the attribute, the axis * index is optional. If no index is supplied, then clearing the Norm * attribute will clear all three elements, and testing the Norm attribute * will return a non-zero value if any of the three elements are set. * * The default value is 1.0 for each of the 3 elements. The length of * the vector is insignificant, but an error will be reported when * attempting to draw text or markers if the vector has zero length. * Applicability: * Plot * All Plot3Ds have this attribute. *att-- */ MAKE_CLEAR3(Norm,norm,AST__BAD,3) MAKE_SET3(Norm,double,norm,value,3) MAKE_TEST3(Norm,( this->norm[axis] != AST__BAD ),3) MAKE_GET3(Norm,double,AST__BAD,(this->norm[axis]!=AST__BAD?this->norm[axis]:1.0),3) /* Functions which access Plot class attributes. */ /* --------------------------------------------- */ /* First do axis specific attributes. */ #define MAKE_ALL(attr,type,badval,whichplots) \ MAKE_CLEAR(attr,whichplots) \ MAKE_SET(attr,type,whichplots) \ MAKE_GET(attr,type,badval ) MAKE_ALL(MinTick,int,0,0) MAKE_ALL(Abbrev,int,0,1) MAKE_ALL(Gap,double,AST__BAD,1) MAKE_ALL(LogGap,double,AST__BAD,1) MAKE_ALL(LogPlot,int,0,0) MAKE_ALL(LogTicks,int,0,0) MAKE_ALL(LogLabel,int,0,1) MAKE_ALL(LabelUp,int,0,1) MAKE_ALL(DrawAxes,int,0,0) MAKE_ALL(LabelUnits,int,0,1) MAKE_ALL(MinTickLen,double,0.0,0) MAKE_ALL(MajTickLen,double,0.0,0) MAKE_ALL(NumLab,int,0,1) MAKE_ALL(NumLabGap,double,AST__BAD,1) MAKE_ALL(TextLab,int,0,1) MAKE_ALL(TextLabGap,double,AST__BAD,1) #undef MAKE_ALL /* Now do attributes that are not axis specific. */ #define MAKE_ALL(attr,type) \ MAKE_CLEAR1(attr) \ MAKE_SET1(attr,type) MAKE_ALL(Ink,int) MAKE_ALL(Tol,double) MAKE_ALL(Invisible,int) MAKE_ALL(TickAll,int) MAKE_ALL(ForceExterior,int) MAKE_ALL(Border,int) MAKE_ALL(Clip,int) MAKE_ALL(ClipOp,int) MAKE_ALL(Escape,int) MAKE_ALL(Grid,int) MAKE_ALL(Labelling,int) #undef MAKE_ALL /* First do element-specific attributes. */ #define MAKE_ALL(attr,type) \ MAKE_CLEAR2(attr) \ MAKE_SET2(attr,type) MAKE_ALL(Style,int) MAKE_ALL(Font,int) MAKE_ALL(Colour,int) MAKE_ALL(Width,double) MAKE_ALL(Size,double) #undef MAKE_ALL /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Plot3D objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Plot3D 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: */ AstPlot3D *in; /* Pointer to input Plot3D */ AstPlot3D *out; /* Pointer to output Plot3D */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Plot3Ds. */ in = (AstPlot3D *) objin; out = (AstPlot3D *) objout; /* Nullify the pointers stored in the output object since these will currently be pointing at the input data (since the output is a simple byte-for-byte copy of the input). Otherwise, the input data could be freed by accidient if the output object is deleted due to an error occuring in this function. */ out->plotxy = NULL; out->plotxz = NULL; out->plotyz = NULL; /* Copy the encapsulated Plots */ if( in->plotxy ) out->plotxy = astCopy( in->plotxy ); if( in->plotxz ) out->plotxz = astCopy( in->plotxz ); if( in->plotyz ) out->plotyz = astCopy( in->plotyz ); /* If an error has occurred, free the output resources. */ if( !astOK ) Delete( (AstObject *) out, status ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Plot3D objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Plot3D 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: */ AstPlot3D *this; /* Release the memory referred to in the Plot3D structure. */ this = (AstPlot3D *) obj; if( this ) { this->plotxy = astDelete( this->plotxy ); this->plotxz = astDelete( this->plotxz ); this->plotyz = astDelete( this->plotyz ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Plot3D 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 Plot3D class to an output Channel. * Parameters: * this * Pointer to the Plot3D whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Local Constants: */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstPlot3D *this; double dval; char key[ KEY_LEN + 1 ]; int axis; int helpful; int ival; int set; const char *text; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot3D structure. */ this = (AstPlot3D *) this_object; /* Write out values representing the instance variables for the Plot3D 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. */ /* Norm. */ /* ----- */ for ( axis = 0; axis < 3; axis++ ) { dval = astGetNorm( this, axis ); helpful = ( dval != -DBL_MAX ); (void) sprintf( key, "Norm%d", axis + 1 ); astWriteDouble( channel, key, 0, helpful, dval, "Text plane normal vector"); } /* RootCorner. */ /* ----------- */ set = TestRootCorner( this, status ); ival = set ? GetRootCorner( this, status ) : astGetRootCorner( this ); text = RootCornerString( ival, status ); if( text ) { astWriteString( channel, "RootCn", set, 1, text, "Corner where labelled axes meet" ); } else if( astOK ) { astError( AST__INTER, "astDump(Plot3D): Illegal value %d found for " "RootCorner attribute (interbal AST programming error).", status, ival ); } /* Labelled axes */ astWriteInt( channel, "AxPlX1", 1, 1, this->axis_plot1[0], "Plot used to label the 3D X axis" ); astWriteInt( channel, "AxPlY1", 1, 1, this->axis_plot1[1], "Plot used to label the 3D Y axis" ); astWriteInt( channel, "AxPlZ1", 1, 1, this->axis_plot1[2], "Plot used to label the 3D Z axis" ); astWriteInt( channel, "AxInX1", 1, 1, this->axis_index1[0], "Plot axis index used to label the 3D X axis" ); astWriteInt( channel, "AxInY1", 1, 1, this->axis_index1[1], "Plot axis index used to label the 3D Y axis" ); astWriteInt( channel, "AxInZ1", 1, 1, this->axis_index1[2], "Plot axis index used to label the 3D Z axis" ); /* Unlabelled axes */ astWriteInt( channel, "AxPlX2", 1, 1, this->axis_plot2[0], "Other Plot touching the 3D X axis" ); astWriteInt( channel, "AxPlY2", 1, 1, this->axis_plot2[1], "Other Plot touching the 3D Y axis" ); astWriteInt( channel, "AxPlZ2", 1, 1, this->axis_plot2[2], "Other Plot touching the 3D Z axis" ); astWriteInt( channel, "AxInX2", 1, 1, this->axis_index2[0], "Other Plot axis index touching the 3D X axis" ); astWriteInt( channel, "AxInY2", 1, 1, this->axis_index2[1], "Other Plot axis index touching the 3D Y axis" ); astWriteInt( channel, "AxInZ2", 1, 1, this->axis_index2[2], "Other Plot axis index touching the 3D Z axis" ); /* The Plot that spans the two connected axes. */ astWriteInt( channel, "BasePl", 1, 1, this->baseplot, "Plot spanning two connected 3D axes" ); /* XY Plot */ astWriteObject( channel, "PlotXY", 1, 1, this->plotxy, "Plot describing the XY plane" ); /* XZ Plot */ astWriteObject( channel, "PlotXZ", 1, 1, this->plotxz, "Plot describing the XZ plane" ); /* YZ Plot */ astWriteObject( channel, "PlotYZ", 1, 1, this->plotyz, "Plot describing the YZ plane" ); /* The index within the Plot3D FrameSet, of the original base Frame in the FrameSet supplied when the Plot3D was constructed. */ astWriteInt( channel, "PixFrm", 1, 0, this->pix_frame, "Index of original base Frame" ); /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPlot3D and astCheckPlot3D functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Plot3D,Plot) astMAKE_CHECK(Plot3D) AstPlot3D *astPlot3D_( void *frame_void, const float *graphbox, const double *basebox, const char *options, int *status, ...) { /* *+ * Name: * astPlot3D * Purpose: * Create a Plot3D. * Type: * Protected function. * Synopsis: * #include "plot3d.h" * AstPlot3D *astPlot3D( AstFrame *frame, const float *graphbox, * const double *basebox, const char *options, ..., int *status ) * Class Membership: * Plot3D constructor. * Description: * This function creates a new Plot3D and optionally initialises its * attributes. * * The supplied Frame (or the base frame if a FrameSet was supplied) is * assumed to be related to the graphics world coordinate system by a * simple shift and scale along each axis. The mapping between graphics * world coordinates and this Frame is specified by supplying the * coordinates in both systems at the lower bounds and upper bounds corners * of a box on the graphics device. By default, no graphics will be * produced outside the supplied box, but this default behaviour can be * changed by setting explicit values for the various clipping attributes. * Parameters: * frame * A pointer to a Frame or FrameSet to be annotated. If a NULL pointer * is supplied, then a default 3-D Frame will be created to which labels, * etc, can be attached by setting the relevant Frame attributes. * graphbox * A pointer to an array of 6 values giving the graphics world * coordinates of the lower bounds and upper bound corners of a box on * the graphics output device. The first triple of values should be the * coordinates of the lower bounds corner of the box and the second * triple of values should be the coordinates of the upper bounds corner. * basebox * A pointer to an array of 6 values giving the coordinates in the * supplied Frame, or base frame of the supplied FrameSet, at the * lower bounds corner and upper bounds corners of the box specified * by parameter graphbox. These should be supplied in the same order as * for parameter "graphbox". * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Plot3D. 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 Plot3D. * 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 Plot3D constructor which * is available via the protected interface to the Plot3D class. * A public interface is provided by the astPlot3DId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstPlot3D *new; /* Pointer to new Plot3D */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ new = NULL; /* Obtain and validate a pointer to any supplied Frame structure. */ if( frame_void ){ frame = astCheckFrame( frame_void ); } else { frame = NULL; } /* Check the pointer can be used. */ if ( astOK ) { /* Initialise the Plot3D, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPlot3D( NULL, sizeof( AstPlot3D ), !class_init, &class_vtab, "Plot3D", frame, graphbox, basebox ); /* 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 Plot'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 Plot. */ return new; } AstPlot3D *astInitPlot3D_( void *mem, size_t size, int init, AstPlot3DVtab *vtab, const char *name, AstFrame *frame, const float *graphbox, const double *basebox, int *status ) { /* *+ * Name: * astInitPlot3D * Purpose: * Initialise a Plot3D. * Type: * Protected function. * Synopsis: * #include "plot3d.h" * AstPlot3D *astInitPlot3D( void *mem, size_t size, int init, * AstPlotVtab *vtab, const char *name, * AstFrame *frame, const float *graphbox, * const double *basebox ) * Class Membership: * Plot3D initialiser. * Description: * This function is provided for use by class implementations to * initialise a new Plot3D object. It allocates memory (if * necessary) to accommodate the Plot3D plus any additional data * associated with the derived class. It then initialises a * Plot3D 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 Plot3D at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Plot3D is to be * created. This must be of sufficient size to accommodate the * Plot3D data (sizeof(Plot3D)) 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 Plot3D (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 Plot3D structure, so a valid value must be supplied * even if not required for allocating memory. * init * A logical flag indicating if the Plot3D'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 Plot3D. * 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). * fset * A pointer to the Frame or Frameset to be annotated. * graphbox * A pointer to an array of 6 values giving the graphics coordinates * of the bottom left and top right corners of a box on the graphics * output device. The first triple of values should be the graphics * coordinates of the bottom left corner of the box and the second * triple of values are the graphics coordinates of the top right corner. * basebox * A pointer to an array of 6 values giving the coordinates in the * supplied Frame or base Frame of the supplied FrameSet at the bottom * left and top right corners of the box specified by parameter graphbox. * These should be supplied in the same order as for parameter "graphbox". * Returned Value: * A pointer to the new Plot3D. * 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 *baseframe = NULL; /* Pointer to base frame */ AstFrame *graphicsframe = NULL; /* Pointer to graphics frame */ AstFrameSet *fset0 = NULL; /* The n-D FrameSet to be annotated */ AstFrameSet *fset = NULL; /* The 2-D FrameSet to be annotated */ AstMapping *map = NULL; /* Mapping for converting bbox -> gbox */ AstPlot3D *new = NULL; /* Pointer to new Plot3D */ char *mess = NULL; /* Pointer to a descriptive message */ double djunkbox[ 4 ] = { 0.0, 0.0, 1.0, 1.0 }; /* Dummy 2D basebox */ float fjunkbox[ 4 ] = { 0.0, 0.0, 1.0, 1.0 }; /* Dummy 2D graphbox */ int bi; /* Index of base frame */ int ci; /* Index of current frame */ int i; /* Loop count */ int ii; /* Loop count */ int naxes; /* No. of axes in frame */ int nfrm; /* Number of Frames in frameset */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPlot3DVtab( vtab, name ); /* First of all we need to ensure that we have a FrameSet and a base Frame on which to base the new Plot3D. If a NULL Frame pointer was supplied, create a default 3-D Frame, and then create a FrameSet containing just this default Frame. Also store a pointer to a message which can be used to describe the object within error messages. */ if( !frame ){ baseframe = astFrame( 3, "", status ); fset = astFrameSet( baseframe, "", status ); mess = "default 3-d Frame"; /* If an object was supplied, report an error if it is not a Frame or an object derived from a Frame (such as a FrameSet). */ } else if( !astIsAFrame( frame ) ){ if( astOK ){ astError( AST__BDOBJ, "astInitPlot3D(%s): Supplied Object (class '%s') " "is not a Frame.", status, name, astGetClass( frame ) ); } /* If the supplied object is a Plot3D or an object derived from a Plot3D (a Plot3D is a sort of Frame and so will pass the above test), extract a FrameSet from the Plot3D, and clear the Domain attribute for any existing Frames which have Domain GRAPHICS. */ } else if( astIsAPlot3D( frame ) ){ fset0 = astFrameSet( frame, "", status ); fset = astCopy( fset0 ); fset0 = astAnnul( fset0 ); for( i = 0; i < astGetNframe( fset ); i++ ) { graphicsframe = astGetFrame( fset, i ); if( !strcmp( astGetDomain( graphicsframe ), "GRAPHICS" ) ) { astClearDomain( graphicsframe ); } graphicsframe = astAnnul( graphicsframe ); } baseframe = astGetFrame( fset, astGetBase( fset ) ); mess = "base Frame of the supplied Plot3D"; /* If the object is not a FrameSet, create a FrameSet holding the supplied Frame. If the Frame is not 3D, an extra 3D Frame is included in the FrameSet derived from axes 1, 2 and 3 of the supplied Frame. This new Frame becomes the base Frame. */ } else if( !astIsAFrameSet( frame ) ){ fset0 = astFrameSet( frame, "", status ); mess = "supplied Frame"; fset = Fset3D( fset0, AST__BASE, status ); fset0 = astAnnul( fset0 ); baseframe = astGetFrame( fset, astGetBase( fset ) ); /* If a FrameSet was supplied, ensure it has a 3D base Frame. If the supplied FrameSet is not 3D, then a new base Frame is inserted into it which is derived from axes 1, 2 and 3 of the original base Frame. */ } else { fset = Fset3D( (AstFrameSet *) frame, AST__BASE, status ); baseframe = astGetFrame( fset, astGetBase( fset ) ); mess = "base Frame of the supplied FrameSet"; } /* Check that there are 3 axes in the base frame of the FrameSet. */ naxes = astGetNaxes( baseframe ); if ( naxes != 3 && astOK ) { astError( AST__NAXIN, "astInitPlot3D(%s): Number of axes (%d) in the %s " "is invalid - this number should be 3.", status, name, naxes, mess ); } /* Check that no dimension of the graphbox is bad. */ if( astISBAD(graphbox[0]) || astISBAD(graphbox[1]) || astISBAD(graphbox[2]) || astISBAD(graphbox[3]) || astISBAD(graphbox[4]) || astISBAD(graphbox[5]) ) { astError( AST__BADBX, "astInitPlot3D(%s): The plotting volume has undefined limits " "in the graphics world coordinate system.", status, name ); } /* Check that no dimension of the graphbox is zero. */ if( ( graphbox[ 3 ] == graphbox[ 0 ] || graphbox[ 4 ] == graphbox[ 1 ] || graphbox[ 5 ] == graphbox[ 2 ] ) && astOK ){ astError( AST__BADBX, "astInitPlot3D(%s): The plotting volume has zero size " "in the graphics world coordinate system.", status, name ); } /* Check that no dimension of the basebox is bad. */ if( astISBAD(basebox[0]) || astISBAD(basebox[1]) || astISBAD(basebox[2]) || astISBAD(basebox[3]) || astISBAD(basebox[4]) || astISBAD(basebox[5]) ) { astError( AST__BADBX, "astInitPlot3D(%s): The limits of " "the %s are undefined or bad.", status, name, name ); } /* Create a Frame which describes the graphics world coordinate system. */ graphicsframe = astFrame( 3, "Domain=GRAPHICS,Title=Graphical Coordinates", status ); /* Initialise a 2D Plot structure (the parent class) as the first component within the Plot3D structure, allocating memory if necessary. We supply dummy arguments since we will not be using the parent Plot class to draw anything. We supply a NULL vtab pointer so that methods defined by the Plot class will be used during the construction of the Plot3D. Once the Plot3D is fully constructed, we will use astSetVtab to establish the correct vtab. */ new = (AstPlot3D *) astInitPlot( mem, size, 0, NULL, name, NULL, fjunkbox, djunkbox ); if ( astOK ) { /* Initialise the Plot3D data. */ /* ----------------------------- */ /* Remove all Frames from the parent FrameSet except for the base (2D graphics) Frame (we leave this last Frame since an error is reported if the last Frame is removed from a FrameSet). We do this by repeatedly removing the first Frame, causing all remaining Frames to have their index reduced by 1. When the base Frame arrives at index 1, we skip it and start removing the second frame instead. */ nfrm = astGetNframe( new ); i = 1; for( ii = 0; ii < nfrm; ii++ ) { if( i > 1 || astGetBase( new ) != 1 ) { astRemoveFrame( new, i ); } else { i = 2; } } /* Add in the 3D graphics Frame, using a PermMap to connect it to the 2D graphics Frame. */ map = (AstMapping *) astPermMap( 2, NULL, 3, NULL, NULL, "", status ); astAddFrame( new, 1, map, graphicsframe ); map = astAnnul( map ); /* And remove the 2D GRAPHICS Frame, leaving just the 3D GRAPHICS Frame in the FrameSet, with index 1. */ astRemoveFrame( new, 1 ); /* Get the index of the current (physical) and base (pixel) Frames in the supplied FrameSet. */ bi = astGetBase( fset ); ci = astGetCurrent( fset ); /* Temporarily set the current Frame to be the pixel frame. */ astSetCurrent( fset, bi ); /* Get a double precision version of "graphbox", and store it in the Plot3D structure. */ new->gbox[ 0 ] = (double) graphbox[ 0 ]; new->gbox[ 1 ] = (double) graphbox[ 1 ]; new->gbox[ 2 ] = (double) graphbox[ 2 ]; new->gbox[ 3 ] = (double) graphbox[ 3 ]; new->gbox[ 4 ] = (double) graphbox[ 4 ]; new->gbox[ 5 ] = (double) graphbox[ 5 ]; /* The base Frame of the supplied FrameSet is mapped linearly onto the graphics frame. Create a WinMap that maps the base box (within the base Frame of the supplied FrameSet) onto the graphics box. */ map = (AstMapping *) astWinMap( 3, new->gbox, new->gbox + 3, basebox, basebox + 3, "", status ); /* Add the supplied FrameSet into the Plot3D (i.e. FrameSet) created earlier. This leaves the graphics frame with index 1 in the returned Plot3D. */ astAddFrame( (AstFrameSet *) new, 1, map, fset ); map = astAnnul( map ); /* Set the current Frame in the Plot to be the physical coordinate Frame (with index incremented by one because the graphics Frame has been added). */ astSetCurrent( (AstFrameSet *) new, ci + 1 ); /* Note the index of the original base Frame in the Plot3D FrameSet */ new->pix_frame = bi + 1; /* Re-establish the original current Frame in the supplied FrameSet. */ astSetCurrent( fset, ci ); /* Initialise the Plot pointers. */ new->plotxy = NULL; new->plotxz = NULL; new->plotyz = NULL; /* Initialise other attributes */ new->rootcorner = -1; /* Initialise the normal vector to the plane used by astText and astMark. */ new->norm[ 0 ] = AST__BAD; new->norm[ 1 ] = AST__BAD; new->norm[ 2 ] = AST__BAD; /* Create three 2D Plots to describe the three planes in the cube. */ CreatePlots( new, fset, graphbox, basebox, status ); /* Ensure that attempts to use the graphics interface of the parent Plot structure get forwarded to the relevant 3D routines defined in this class. */ astGrfSet( new, "Attr", (AstGrfFun) Attr3D ); astSetGrf( new, 1 ); /* Change the virtual function table stored in the new Plot3D, from the Plot vtab (established when astINitPlot was called above), to the supplied vtab. */ if( vtab ) astSetVtab( new, vtab ); /* Ensure that these Plots use the grf functions defined by this class (Plot3D). This means that whenever a Plot draws anything, it will use the appropriate grf function defined in this class to do the drawing. The grf functions defined in this class, convert the grf call into a grf3D call apprpriate the plane spanned by the Plot. */ Set3DGrf( new, new->plotxy, XY, status ); Set3DGrf( new, new->plotxz, XZ, status ); Set3DGrf( new, new->plotyz, YZ, status ); /* Set up the Edges attributes in the encapsulated Plots so that labels appear on the requited edges. Initially, the root corner is "LLL" (i.e. the lower bound on every axis). */ ChangeRootCorner( new, 0, 0, status ); } /* Annul the frame. */ graphicsframe = astAnnul( graphicsframe ); /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); /* Annul the pointer to the base Frame and FrameSet. */ baseframe = astAnnul( baseframe ); fset = astAnnul( fset ); /* Return a pointer to the new object. */ return new; } AstPlot3D *astLoadPlot3D_( void *mem, size_t size, AstPlot3DVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPlot3D * Purpose: * Load a Plot3D. * Type: * Protected function. * Synopsis: * #include "plot3d.h" * AstPlot3D *astLoadPlot3D( void *mem, size_t size, * AstPlot3DVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Plot3D loader. * Description: * This function is provided to load a new Plot3D 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 * Plot3D structure in this memory, using data read from the * input Channel. * Parameters: * mem * A pointer to the memory into which the Plot3D is to be * loaded. This must be of sufficient size to accommodate the * Plot3D data (sizeof(Plot3D)) 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 Plot3D (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 Plot3D 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(AstPlot3D) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Plot3D. If this is NULL, a pointer * to the (static) virtual function table for the Plot3D 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 "Plot3D" is used instead. * Returned Value: * A pointer to the new Plot3D. * 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: */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ astDECLARE_GLOBALS AstPlot3D *new; char key[ KEY_LEN + 1 ]; char *text; int axis; int i; /* Initialise. */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Plot3D. In this case the Plot3D belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPlot3D ); vtab = &class_vtab; name = "Plot3D"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPlot3DVtab( vtab, name ); class_init = 1; } } /* Allocate memory to hold the new Object. We allocate it now rather than waiting for astInitObject to allocate it so that we can pass a NULL vtab pointer to the Plot loader, thus causing the Plot loader to use the function implementations provided by the Plot class rather than those provided by the class being instantiated. */ if( !mem ) mem = astMalloc( size ); /* 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 Plot3D. Pass a NULL vtab pointer so that the "new" object will be loaded using Plot methods rather than than Plot3D methods. This is important because the implementations provided by the Plot3D class for the Plot attribute accessors require the existence of the encapsulated Plots held within the Plot3D, but these have not yet been created. */ new = astLoadPlot( mem, size, NULL, name, channel ); if ( astOK ) { /* Now modify the new object to use the supplied vtab. */ astSetVtab( new, vtab ); /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "Plot3D" ); /* 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. */ /* Norm. */ /* ----- */ for( axis = 0; axis < 3; axis++ ) { (void) sprintf( key, "norm%d", axis + 1 ); new->norm[ axis ] = astReadDouble( channel, key, AST__BAD ); if( TestNorm( new, axis, status ) ) SetNorm( new, axis, new->norm[ axis ], status ); } /* RootCorner. */ /* ----------- */ text = astReadString( channel, "rootcn", " " ); if( astOK && strcmp( text, " " ) ) { new->rootcorner = RootCornerInt( text, status ); if( new->rootcorner < 0 && astOK ) { astError( AST__INTER, "astRead(Plot3D): Corrupt Plot3D contains " "invalid RootCorner attribute value (%s).", status, text ); } } else { new->rootcorner = -1; } text = astFree( text ); /* Labelled axes */ new->axis_plot1[0] = astReadInt( channel, "axplx1", -1 ); new->axis_plot1[1] = astReadInt( channel, "axply1", -1 ); new->axis_plot1[2] = astReadInt( channel, "axplz1", -1 ); new->axis_index1[0] = astReadInt( channel, "axinx1", -1 ); new->axis_index1[1] = astReadInt( channel, "axiny1", -1 ); new->axis_index1[2] = astReadInt( channel, "axinz1", -1 ); /* Unlabelled axes */ new->axis_plot2[0] = astReadInt( channel, "axplx2", -1 ); new->axis_plot2[1] = astReadInt( channel, "axply2", -1 ); new->axis_plot2[2] = astReadInt( channel, "axplz2", -1 ); new->axis_index2[0] = astReadInt( channel, "axinx2", -1 ); new->axis_index2[1] = astReadInt( channel, "axiny2", -1 ); new->axis_index2[2] = astReadInt( channel, "axinz2", -1 ); /* Plot that spans two connected 3D axes. */ new->baseplot = astReadInt( channel, "basepl", -1 ); /* XY Plot */ new->plotxy = astReadObject( channel, "plotxy", NULL ); /* XZ Plot */ new->plotxz = astReadObject( channel, "plotxz", NULL ); /* YZ Plot */ new->plotyz = astReadObject( channel, "plotyz", NULL ); /* The index within the Plot3D FrameSet, of the original base Frame in the FrameSet supplied when the Plot3D was constructed. */ new->pix_frame = astReadInt( channel, "pixfrm", AST__NOFRAME ); /* Ensure that these Plots use the grf functions defined by this class (Plot3D). This means that whener a Plot draws anything, it will use the appropriate grf function defined in this class to do the drawing. The grf functions defined in this class, convert the grf call into a grf3D call apprpriate the plane spanned by the Plot. */ Set3DGrf( new, new->plotxy, XY, status ); Set3DGrf( new, new->plotxz, XZ, status ); Set3DGrf( new, new->plotyz, YZ, status ); /* For attributes of the parent Plot class will have been loaded each attribute that has a set value in the parent Plot structure, re-set the value so that it gets copied to the copy the to the encapsulated Plots. First do axis specific attributes. */ #define COPY_ATTR(attr,nval) \ for( i = 0; i < nval; i++ ) { \ if( astTest##attr(new,i) ) astSet##attr(new,i,astGet##attr(new,i)); \ } COPY_ATTR(MinTick,3) COPY_ATTR(Abbrev,3) COPY_ATTR(Gap,3) COPY_ATTR(LogGap,3) COPY_ATTR(LogPlot,3) COPY_ATTR(LogTicks,3) COPY_ATTR(LogLabel,3) COPY_ATTR(LabelUp,3) COPY_ATTR(DrawAxes,3) COPY_ATTR(LabelUnits,3) COPY_ATTR(MinTickLen,3) COPY_ATTR(MajTickLen,3) COPY_ATTR(NumLab,3) COPY_ATTR(NumLabGap,3) COPY_ATTR(TextLab,3) COPY_ATTR(TextLabGap,3) COPY_ATTR(Style,AST__NPID) COPY_ATTR(Font,AST__NPID) COPY_ATTR(Colour,AST__NPID) COPY_ATTR(Width,AST__NPID) COPY_ATTR(Size,AST__NPID) #undef COPY_ATTR /* Now do attributes that are not axis specific. */ #define COPY_ATTR(attr) \ if( astTest##attr(new) ) astSet##attr(new,astGet##attr(new)); COPY_ATTR(Ink) COPY_ATTR(Tol) COPY_ATTR(Invisible) COPY_ATTR(TickAll) COPY_ATTR(ForceExterior) COPY_ATTR(Border) COPY_ATTR(Clip) COPY_ATTR(ClipOp) COPY_ATTR(Escape) COPY_ATTR(Grid) COPY_ATTR(Labelling) #undef COPY_ATTR /* If an error occurred, clean up by deleting the new Plot3D. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Plot3D 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 astClearRootCorner_( AstPlot3D *this, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Plot3D,ClearRootCorner))( this, status ); } void astSetRootCorner_( AstPlot3D *this, int value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Plot3D,SetRootCorner))( this, value, status ); } /* Special public interface functions. */ /* =================================== */ /* These provide the public interface to certain special functions whose public interface cannot be handled using macros (such as astINVOKE) alone. In general, they are named after the corresponding protected version of the function, but with "Id" appended to the name. */ /* Public Interface Function Prototypes. */ /* ------------------------------------- */ /* The following functions have public prototypes only (i.e. no protected prototypes), so we must provide local prototypes for use within this module. */ AstPlot3D *astPlot3DId_( void *frame_void, const float graphbox[6], const double basebox[6], const char *, ... ); /* Special interface function implementations. */ /* ------------------------------------------- */ AstPlot3D *astPlot3DId_( void *frame_void, const float graphbox[6], const double basebox[6], const char *options, ... ) { /* *++ * Name: c astPlot3D f AST_PLOT3D * Purpose: * Create a Plot3D. * Type: * Public function. * Synopsis: c #include "plot3d.h" c AstPlot3D *astPlot3D( AstFrame *frame, const float graphbox[ 6 ], c const double basebox[ 6 ], const char *options, ... ) f RESULT = AST_PLOT3D( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS ) * Class Membership: * Plot3D constructor. * Description: * This function creates a new Plot3D and optionally initialises * its attributes. * * A Plot3D is a specialised form of Plot that provides facilities * for producing 3D graphical output. * Parameters: c frame f FRAME = INTEGER (Given) * Pointer to a Frame describing the physical coordinate system * in which to plot. A pointer to a FrameSet may also be given, * in which case its current Frame will be used to define the * physical coordinate system and its base Frame will be mapped * on to graphical coordinates (see below). * * If a null Object pointer (AST__NULL) is given, a default * 3-dimensional Frame will be used to describe the physical * coordinate system. Labels, etc. may then be attached to this * by setting the appropriate Frame attributes * (e.g. Label(axis)) for the Plot. c graphbox f GRAPHBOX( 6 ) = REAL (Given) * An array giving the position and extent of the plotting volume * (within the plotting space of the underlying graphics system) * in which graphical output is to appear. This must be * specified using graphical coordinates appropriate to the * underlying graphics system. * * The first triple of values should give the coordinates of the * bottom left corner of the plotting volume and the second triple * should give the coordinates of the top right corner. The * coordinate on the horizontal axis should be given first in * each pair. Note that the order in which these points are * given is important because it defines up, down, left and * right for subsequent graphical operations. c basebox f BASEBOX( 6 ) = DOUBLE PRECISION (Given) * An array giving the coordinates of two points in the supplied * Frame (or in the base Frame if a FrameSet was supplied) which * correspond to the bottom left and top right corners of the * plotting volume, as specified above. This range of coordinates * will be mapped linearly on to the plotting area. The * coordinates should be given in the same order as above. 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 Plot3D. 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 Plot3D. 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 astPlot3D() f AST_PLOT3D = INTEGER * A pointer to the new Plot3D. * Notes: * - The base Frame of the returned Plot3D will be a new Frame which * is created by this function to represent the coordinate system * of the underlying graphics system (graphical coordinates). It is * given a Frame index of 1 within the Plot3D. The choice of base * Frame (Base attribute) should not, in general, be changed once a * Plot3D has been created (although you could use this as a way of * moving the plotting area around on the plotting surface). c - If a Frame is supplied (via the "frame" pointer), then it f - If a Frame is supplied (via the FRAME pointer), then it * becomes the current Frame of the new Plot3D and is given a Frame * index of 2. c - If a FrameSet is supplied (via the "frame" pointer), then f - If a FrameSet is supplied (via the FRAME pointer), then * all the Frames within this FrameSet become part of the new Plot3D * (where their Frame indices are increased by 1), with the * FrameSet's current Frame becoming the current Frame of the Plot3D. * - At least one of the three axes of the current Frame must be * independent of the other two current Frame axes. * - If a null Object pointer (AST__NULL) is supplied (via the c "frame" pointer), then the returned Plot3D will contain two f FRAME pointer), then the returned Plot3D will contain two * Frames, both created by this function. The base Frame will * describe graphics coordinates (as above) and the current Frame * will be a basic Frame with no attributes set (this will * therefore give default values for such things as the Plot3D Title * and the Label on each axis). Physical coordinates will be mapped * linearly on to graphical coordinates. * - An error will result if the Frame supplied (or the base Frame * if a FrameSet was supplied) is not 3-dimensional. * - 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 astPlot3D constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astPlot3D_ 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 astPlot3D_ directly, so it must be a * re-implementation of it in all respects, except for the final * conversion of the result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstPlot3D *new; /* Pointer to new Plot3D */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ new = NULL; /* Obtain a Frame pointer from any ID supplied and validate the pointer to ensure it identifies a valid Frame. */ if( frame_void ){ frame = astVerifyFrame( astMakePointer( frame_void ) ); } else { frame = NULL; } /* Check the pointer can be used. */ if ( astOK ) { /* Initialise the Plot3D, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPlot3D( NULL, sizeof( AstPlot3D ), !class_init, &class_vtab, "Plot3D", frame, graphbox, basebox ); /* 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 Plot3D'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 Plot3D. */ return astMakeId( new ); } /* Macros that define method to override the methods of the Plot class that are not currently implemented by this class. They just report an error if called. */ #define METHOD1(name) \ static void name(ARGLIST,int *status){ \ if( !astOK ) return; \ astError( AST__INTER, "ast##name(%s): The ast##name " \ "method cannot be used with a %s (programming error).", status, \ astGetClass( this ), astGetClass( this ) ); \ } #define METHOD2(name,rettype,retval) \ static rettype name(ARGLIST,int *status){ \ if( !astOK ) return retval; \ astError( AST__INTER, "ast##name(%s): The ast##name " \ "method cannot be used with a %s (programming error).", status, \ astGetClass( this ), astGetClass( this ) ); \ return retval; \ } #define ARGLIST AstPlot *this METHOD2(GetGrfContext,AstKeyMap *,NULL) #undef ARGLIST #define ARGLIST AstPlot *this METHOD1(GrfPop) #undef ARGLIST #define ARGLIST AstPlot *this METHOD1(GrfPush) #undef ARGLIST #define ARGLIST AstPlot *this, const char *name, AstGrfFun fun METHOD1(GrfSet) #undef ARGLIST #define ARGLIST AstPlot *this, int axis, const double start[], double length METHOD1(GridLine) #undef ARGLIST #define ARGLIST AstPlot *this, float lbnd[2], float ubnd[2] METHOD1(BoundingBox) #undef ARGLIST #define ARGLIST AstPlot *this, int iframe, const double lbnd[], const double ubnd[] METHOD1(Clip) #undef ARGLIST #define ARGLIST AstPlot *this, const double start[], const double finish[] METHOD1(Curve) #undef ARGLIST #define ARGLIST AstPlot *this, AstMapping *map METHOD1(GenCurve) #undef ARGLIST ast-8.3.0/mapping.c0000664000175000017500000371754113004147321011050 00000000000000/* *class++ * Name: * Mapping * Purpose: * Inter-relate two coordinate systems. * Constructor Function: * None. * Description: * This class provides the basic facilities for transforming a set * of coordinates (representing "input" points) to give a new set * of coordinates (representing "output" points). It is used to * describe the relationship which exists between two different * coordinate systems and to implement operations which make use of * this (such as transforming coordinates and resampling grids of * data). However, the Mapping class does not have a constructor * function of its own, as it is simply a container class for a * family of specialised Mappings which implement particular types * of coordinate transformation. * Inheritance: * The Mapping class inherits from the Object class. * Attributes: * In addition to those attributes common to all Objects, every * Mapping also has the following attributes: * * - Invert: Mapping inversion flag * - IsLinear: Is the Mapping linear? * - IsSimple: Has the Mapping been simplified? * - Nin: Number of input coordinates for a Mapping * - Nout: Number of output coordinates for a Mapping * - Report: Report transformed coordinates? * - TranForward: Forward transformation defined? * - TranInverse: Inverse transformation defined? * Functions: c In addition to those functions applicable to all Objects, the c following functions may also be applied to all Mappings: f In addition to those routines applicable to all Objects, the f following routines may also be applied to all Mappings: * c - astDecompose: Decompose a Mapping into two component Mappings c - astTranGrid: Transform a grid of positions c - astInvert: Invert a Mapping c - astLinearApprox: Calculate a linear approximation to a Mapping c - astMapBox: Find a bounding box for a Mapping c - astMapSplit: Split a Mapping up into parallel component Mappings c - astQuadApprox: Calculate a quadratic approximation to a 2D Mapping c - astRate: Calculate the rate of change of a Mapping output c - astRebin: Rebin a region of a data grid c - astRebinSeq: Rebin a region of a sequence of data grids c - astResample: Resample a region of a data grid c - astRemoveRegions: Remove any Regions from a Mapping c - astSimplify: Simplify a Mapping c - astTran1: Transform 1-dimensional coordinates c - astTran2: Transform 2-dimensional coordinates c - astTranN: Transform N-dimensional coordinates c - astTranP: Transform N-dimensional coordinates held in separate arrays f - AST_DECOMPOSE: Decompose a Mapping into two component Mappings f - AST_TRANGRID: Transform a grid of positions f - AST_INVERT: Invert a Mapping f - AST_LINEARAPPROX: Calculate a linear approximation to a Mapping f - AST_QUADAPPROX: Calculate a quadratic approximation to a 2D Mapping f - AST_MAPBOX: Find a bounding box for a Mapping f - AST_MAPSPLIT: Split a Mapping up into parallel component Mappings f - AST_RATE: Calculate the rate of change of a Mapping output f - AST_REBIN: Rebin a region of a data grid f - AST_REBINSEQ: Rebin a region of a sequence of data grids f - AST_REMOVEREGIONS: Remove any Regions from a Mapping f - AST_RESAMPLE: Resample a region of a data grid f - AST_SIMPLIFY: Simplify a Mapping f - AST_TRAN1: Transform 1-dimensional coordinates f - AST_TRAN2: Transform 2-dimensional coordinates f - AST_TRANN: Transform N-dimensional coordinates * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * MBT: Mark Taylor (Starlink) * DSB: David S. Berry (Starlink) * History: * 1-FEB-1996 (RFWS): * Original version. * 29-FEB-1996 (RFWS): * Minor improvements to error messages. * 15-JUL-1996 (RFWS): * Support external interface. * 13-DEC-1996 (RFWS): * Added the astMapMerge method. * 13-DEC-1996 (RFWS): * Added the astSimplify method. * 27-MAY-1997 (RFWS): * Improved the astSimplify method to use astMapMerge to * simplify a single Mapping where possible. * 29-MAY-1998 (RFWS): * Added the MapBox method. * 13-NOV-1998 (RFWS): * Made default MapBox convergence accuracy larger (i.e. less * accurate). * 10-DEC-1998 (RFWS): * First useful implementation of astResample. * 16-AUG-1999 (RFWS): * Fixed bug in SpecialBounds - wrong number of coordinates being used * when checking for bad output coordinate values. * 17-AUG-1999 (RFWS): * Improved the convergence security of MapBox (return to older but * less efficient setting). * 24-NOV-2000 (MBT): * Fixed bug (function being invoked as wrong type) in AST__UINTERP * scheme, and added new AST__BLOCKAVE scheme, in astResample. * 9-JAN-2001 (DSB): * Changed in and out arguments for TranN from type "double (*)[]" * to "double *". * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitMappingVtab * method. * 10-JUL-2003 (DSB): * Added method astRate. * 2-SEP-2004 (DSB): * Free resources before leaving astRate. * 31-AUG-2004 (DSB): * Make the LinearApprox function protected rather than private, * rename it to astLinearApprox, and make the bounds parameters of * type double rather than int. Also, correct the size of the fit * coefficient array (was "(nin+1)*nout", now is "(nout+1)*nin"). * Also correct the index of the first gradient coefficient from * "fit+nout" to "fit+nin". These errors have probably never been * noticed because they make no difference if nin=nout, which is * usually the case. * 6-SEP-2004 (DSB): * Make astRate more robust by adding checks for unusal conditions. * 20-SEP-2004 (DSB): * Make the LinearApprox function public and change its interface * to be more appropriate for public use. This involved swapping the * direction of the fit (the original astLinearApprox fitted the * inverse transformation, but the public version now fits the forwrd * transformation). * 4-OCT-2004 (DSB): * Modify astMapList to return flag indicating presence of inverted * CmpMaps in supplied Mapping. * 9-NOV-2004 (DSB): * Override astEqual method. * 6-DEC-2004 (DSB): * Remove the second derivative estimate from the astRate function * since CmpMap has trouble calculating it. * 17-DEC-2004 (DSB): * Added astMapSplit * 22-APR-2005 (DSB): * Modified SpecialBounds to handle cases where some irrelevant * output always produces bad values (e.g. a PermMap may do this). * 30-JUN-2005 (DSB): * Added astRebin. * 7-JUL-2005 (DSB): * Make MapSplit public rather than protected. * 11-AUG-2005 (DSB): * Added the AST__CONSERVEFLUX flag (used by astResampleX). * 17-AUG-2005 (DSB): * Added the AST__SOMBCOS kernel. * 31-AUG-2005 (DSB): * Added astRebinSeq. * 9-SEP-2005 (DSB): * Corrected axis indices returned by public interface for astMapSplit. * 31-JAN-2006 (DSB): * Added IsSimple attribute. * 2-FEB-2006 (DSB): * Corrections to prologue of astLinearApprox. * 16-FEB-2006 (DSB): * Some speed optimisations to rebinning code. * 2-MAR-2006 (DSB): * Use HAVE_LONG_DOUBLE in place of AST_LONG_DOUBLE * 7-MAR-2006 (DSB): * Added astTranGrid. * 14-MAR-2006 (DSB): * - The constructor no longer reports an error if the resulting * Mapping cannot transform points in either direction. This is * because it may be possible to simplify such a Mapping and the * simplified Mapping may have defined transformations. E.g. if a * Mapping which has only a forward transformation is combined in * series with its own inverse, the combination CmpMap will simplify * to a UnitMap (usually). * - Reset the "issimple" flag when the Invert flag is changed. * 9-MAY-2006 (DSB): * Correct upper bounds for idim in RebinWithblocking. Also, remove * the single precision "F" instantiation of the MAKE_REBINSEQ macro. * Also correct the "nout = astGetNin" line in the MAKE_REBINSEQ * macro to "nout = astGetNout". * 12-MAY-2006 (DSB): * Modify SpecialBounds to include points slightly inside the * corners. This is because some Mappings may have singularies at * the the edges. * 17-MAY-2006 (DSB): * Correct the "nout = astGetNin" line in the MAKE_RESAMPLE * and MAKE_REBIN macros to "nout = astGetNout". * 7-JUL-2006 (DSB): * Change -CHAR_MAX value (used as a "not set" value for boolean * attributes) to +CHAR_MAX, since some compilers do not allow * chars to have negative values. * 23-AUG-2006 (DSB): * Change the Equal function so that it reports an error when * called, rather than using astSimplify to determine if two Mappings * are equal. All concrete Mapping classes should now provide * their own implementation of astEqual, avoiding the use of * astSimplify. This is so that astSimplify can use astEqual safely * (i.e. without danger of entering an infinite loop). * 24-NOV-2006 (DSB): * Allow astRebinSeq to be called with a NULL pointer for the input * data array. * 14-MAR-2007 (DSB): * Modify astRebinSeq to allow input variances to be used as weights. * 19-MAR-2007 (DSB): * Fix bug in LINEAR_2D macro that caused bad input pixel values to be * treated as good. * 16-APR-2007 (DSB): * Account for reduction in number of degrees of freedom when * calculating output variances on the basis of spread of input values in * astReinSeq. * 28-APR-2007 (DSB): * Correct code within Rebin... and Resample... functions that provides * optimal handling for 1- and 2- dimensional mappings. Previously, the * check for whether or not to use these optimisations was based only on * the dimensionality of either input (Rebin) or output (Resample). This * could cause the optimised code to be used at inappropriate times, * leading to an incorrect effective Mapping between input and output. The * checks now check both input and output dimensionality in all cases. * 3-MAY-2007 (DSB): * An extra parameter ("nused") has been added to astRebinSeq, and * all the rebinning stuff has been modified to keep "nused" up to date. * This is needed to correct a fault in the generation of GENVAR * variances. * 12-DEC-2007 (DSB): * Some rebinning kernels (e.g. SINCSINC) have negative values and * can result in overall negative output weights. Therefore do not * set output pixels with negative weights bad. * 6-MAR-2008 (DSB): * Add an option for astResample to leave unchanged any output pixels * for which an interpolated value cannot be obtained. This is * controlled by the new AST__NOBAD flag. * 7-MAY-2008 (DSB): * Clarified meaning of AST__GENVAR, AST__USEVAR and AST__VARWGT flags * in astRebinSeq. * 9-MAY-2008 (DSB): * Prevent memory over-run in RebinSeq. * 5-MAY-2009 (DSB): * Added astRemoveRegions. * 11-NOV-2009 (DSB): * In astRebinSeq initialise "*nused" to zero (as documented) if the * AST__REBININIT flag is supplied. * 17-NOV-2009 (DSB): * Added AST_DISVAR flag for use with astRebinSeq. * 15-DEC-2009 (DSB): * Ensure that all axes span at least one pixel when calling * astLinearApprox. * 18-DEC-2009 (DSB): * When using a 1D spreading kernel (in astRebin(Seq)), if the kernel * is not contained completely within the output array, reflect the * section of the kernel that falls outside the output array back into * the output array so that no flux is lost. Also discovered that the * n-D code (i.e. the KERNEL_ND macro) incorrectly uses the first * user-supplied parameter as the full kernel width rather than the * half-width. This has been fixed. * 26-FEB-2010 (DSB): * Add astQuadApprox. * 27-FEB-2010 (DSB): * - Make astQuadApprox faster, and fix a bug in the calculation of * the matrix. * 7-JUN-2010 (DSB): * In the KERNEL_D rebinning macros, correct the test for the * central point being outside the bounds of the output image. * 13-AUG-2010 (DSB): * In astRebinSeq, scale WLIM to take account of weighting by * input variances. * 13-DEC-2010 (DSB): * Ensure that astMapSplit returns a Mapping that is independent of * the supplied Mapping (i.e. return a deep copy). This means that * subsequent changes to the supplied Mapping cannot affect the returned * Mapping. * 10-FEB-2011 (DSB): * When rebinning (in macros NEAR_1/2/ND, KERNEL_1/2/ND, LINEAR_1/2/ND), * do not treat a zero variance as bad unless the reciprocals of the * variances are being used as weights. * 16-JUN-2011 (DSB): * Allow a check for NaNs to be performed as a debugging tool after * every invocation of astTransform. This is controlled by the * AST_REPLACE_NAN environment variable: if unset, no check is * performed, if set to "1" NaNs are changed to AST__BAD but no * error is reported, if set to anything else NaNs are changed to * AST__BAD and an error is reported. * 6-JUL-2012 (DSB): * The astRebinSeq family was normalising the returned data and * variances values incorrectly, when the AST__REBINEND flag was * supplied. The exact size of the error depended on the nature of * the Mapping and the spreading method, and so is hard to predict. * 20-JUL-2012 (DSB): * Major re-structuring of astRebinSeq to add further * corrections to the normalisation. The model is now that each * input array is first rebinned and then scaled to preserve the * total data sum, and then each final output pixel is the weighed * mean of all the aligned rebinned pixels. * 13-AUG-2012 (DSB): * Added AST__NONORM flag for asstRebuinSeq. * 30-AUG_2012 (DSB): * Added AST__CONSERVEFLUX flag for astRebinSeq. * 10-SEP-2012 (DSB): * Cater for Mappings that have different numbers of inputs and * outputs when finding the flux conservation factor within * astRebinSeq and astResample. * 1-OCT-2012 (DSB): * Ensure astRebinSeq does not create any negative output * variances. * 2-OCT-2012 (DSB): * - Check for Infs as well as NaNs. * - In Rate, break out of the loop if the RMS is very small, not * just if it is exactly zero. * 5-OCT-2012 (DSB): * Complete re-write of Rate. It's now much simpler, faster and * more reliable. * 16-OCT-2012 (DSB): * In MatrixDet, ignore rows/columns filled with AST_BAD as well as * rows/columns filled with zeros. * 26-APR-2013 (DSB): * Change the "nused" parameter of astRebinSeq from "int *" to * "size_t *" to allow greater amounts of data to be pasted into * the output array. * 29-APR-2013 (DSB): * No sot simplify Mappings that have a set value for their Ident * attribute. If an Ident value has been set then it means that we * should be trying to preserve the identify of the Mapping. This * is implemented via a new protected method (astDoNotSimplify) which * is overridden by the Frame class so that this restriction applies * only to genuine Mappings, not Frames. * 9-MAY-2013 (DSB): * Change the "nused" parameter of astRebinSeq from "size_t *" to * "int64_t *" to cater for systems where "size_t" is only 32 bits long. * 20-MAY-2013 (DSB): * Always perform a linear fit in RebinAdaptively if flux * conservation is requested. * 18-JUL-2013 (DSB): * Correct logic for determining whether to divide or not in * RebinAdaptively. The old logic could lead to infinite recursion. * 1-SEP-2014 (DSB): * Modify astLinearAPprox to avoid using regularly placed * test points, as such regular placement may result in * non-representative behaviour. * 25-SEP-2014 (DSB): * Add support for B and UB data types to astRebin and astRebinSeq. * 23-OCT-2014 (DSB): * Report an error if arrays have too many pixels to count in a 32 * bit int (astTranGrid, astResample, astRebin and astRebinSeq). * 23-APR-2015 (DSB): * Use one bit of this->flags to store the "IsSimple" attribute * rather using a whole char (this->issimple). *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 Mapping /* Define numerical constants for use in thie module. */ #define GETATTRIB_BUFF_LEN 50 #define RATEFUN_MAX_CACHE 5 #define RATE_ORDER 8 /* Include files. */ /* ============== */ /* Configuration results */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* 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 "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #include "mapping.h" /* Interface definition for this class */ #include "cmpmap.h" /* Compund Mappings */ #include "unitmap.h" /* Unit Mappings */ #include "permmap.h" /* Axis permutations */ #include "winmap.h" /* Window scalings */ #include "pal.h" /* SLALIB interface */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* Module type definitions. */ /* ======================== */ /* Enum to represent the data type when resampling a grid of data. */ typedef enum DataType { #if HAVE_LONG_DOUBLE /* Not normally implemented */ TYPE_LD, #endif TYPE_D, TYPE_F, TYPE_L, TYPE_UL, TYPE_K, TYPE_UK, TYPE_I, TYPE_UI, TYPE_S, TYPE_US, TYPE_B, TYPE_UB } DataType; /* Data structure to hold information about a Mapping for use by optimisation algorithms. */ typedef struct MapData { AstMapping *mapping; /* Pointer to the Mapping */ AstPointSet *pset_in; /* Pointer to input PointSet */ AstPointSet *pset_out; /* Pointer to output PointSet */ double *lbnd; /* Pointer to lower constraints on input */ double *ubnd; /* Pointer to upper constraints on input */ double **ptr_in; /* Pointer to input PointSet coordinates */ double **ptr_out; /* Pointer to output PointSet coordinates */ int coord; /* Index of output coordinate to optimise */ int forward; /* Use forward transformation? */ int negate; /* Negate the output value? */ int nin; /* Number of input coordinates per point */ int nout; /* Number of output coordinates per point */ } MapData; /* Convert from floating point to floating point or integer */ #define CONV(IntType,val) ( ( IntType ) ? (int) ( (val) + (((val)>0)?0.5:-0.5) ) : (val) ) /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static int (* parent_equal)( AstObject *, AstObject *, int * ); /* 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->Unsimplified_Mapping = NULL; \ globals->Rate_Disabled = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Mapping) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Mapping,Class_Init) #define class_vtab astGLOBAL(Mapping,Class_Vtab) #define getattrib_buff astGLOBAL(Mapping,GetAttrib_Buff) #define unsimplified_mapping astGLOBAL(Mapping,Unsimplified_Mapping) #define rate_disabled astGLOBAL(Mapping,Rate_Disabled) #define ratefun_pset1_cache astGLOBAL(Mapping,RateFun_Pset1_Cache) #define ratefun_pset2_cache astGLOBAL(Mapping,RateFun_Pset2_Cache) #define ratefun_next_slot astGLOBAL(Mapping,RateFun_Next_Slot) #define ratefun_pset_size astGLOBAL(Mapping,RateFun_Pset_Size) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffer returned by GetAttrib. */ static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ]; /* Pointer to origin (unsimplified) Mapping, only used for reporting error messages. */ static AstMapping *unsimplified_mapping = NULL; /* A flag which indicates if the astRate method should be disabled in order to improve algorithm speed in cases where the rate value is not significant. If astRate is disabled then it always returns a constant value of 1.0. */ static int rate_disabled = 0; /* static values used in function "RateFun". */ static AstPointSet *ratefun_pset1_cache[ RATEFUN_MAX_CACHE ]; static AstPointSet *ratefun_pset2_cache[ RATEFUN_MAX_CACHE ]; static int ratefun_next_slot; static int ratefun_pset_size[ RATEFUN_MAX_CACHE ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstMappingVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* Prototypes for private member functions. */ /* ======================================== */ #define DECLARE_GENERIC(X,Xtype) \ static int InterpolateKernel1##X( AstMapping *, int, const int *, const int *, \ const Xtype *, const Xtype *, int, \ const int *, const double *const *, \ void (*)( double, const double *, int, \ double *, int * ), \ void (*)( double, const double *, int, \ double * ), \ int, const double *, int, Xtype, \ Xtype *, Xtype *, int * );\ \ static int InterpolateLinear##X( int, const int *, const int *, const Xtype *, \ const Xtype *, int, const int *, \ const double *const *, int, Xtype, Xtype *, \ Xtype *, int * ); \ \ static int InterpolateNearest##X( int, const int *, const int *, const Xtype *, \ const Xtype *, int, const int *, \ const double *const *, int, Xtype, Xtype *, \ Xtype *, int * ); \ \ static int Resample##X( AstMapping *, int, const int [], const int [], \ const Xtype [], const Xtype [], int, \ void (*)( void ), const double [], int, double, int, \ Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ \ static void ConserveFlux##X( double, int, const int *, Xtype, Xtype *, Xtype *, \ int * ); \ \ static void InterpolateBlockAverage##X( int, const int[], const int[], \ const Xtype [], const Xtype [], int, const int[], \ const double *const[], const double[], int, \ Xtype, Xtype *, Xtype *, int * ); DECLARE_GENERIC(B,signed char) DECLARE_GENERIC(D,double) DECLARE_GENERIC(F,float) DECLARE_GENERIC(I,int) DECLARE_GENERIC(K,INT_BIG) DECLARE_GENERIC(L,long int) DECLARE_GENERIC(S,short int) DECLARE_GENERIC(UB,unsigned char) DECLARE_GENERIC(UI,unsigned int) DECLARE_GENERIC(UK,UINT_BIG) DECLARE_GENERIC(UL,unsigned long int) DECLARE_GENERIC(US,unsigned short int) #if HAVE_LONG_DOUBLE /* Not normally implemented */ DECLARE_GENERIC(LD,long double) #endif #undef DECLARE_GENERIC #define DECLARE_GENERIC(X,Xtype) \ static void Rebin##X( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], int, \ double, int, Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ \ static void RebinSeq##X( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], \ int, double, int, Xtype, int, const int [], \ const int [], const int [], const int [], Xtype [], \ Xtype [], double [], int64_t *, int * ); \ \ static void SpreadKernel1##X( AstMapping *, int, const int *, const int *, \ const Xtype *, const Xtype *, double, int, const int *, \ const double *const *, \ void (*)( double, const double *, int, double *, int * ), \ int, const double *, int, Xtype, int, Xtype *, \ Xtype *, double *, int64_t *, int * ); \ \ static void SpreadLinear##X( int, const int *, const int *, const Xtype *, \ const Xtype *, double, int, const int *, const double *const *, \ int, Xtype, int, Xtype *, Xtype *, double *, int64_t *, \ int * ); \ \ static void SpreadNearest##X( int, const int *, const int *, const Xtype *, \ const Xtype *, double, int, const int *, const double *const *, \ int, Xtype, int, Xtype *, Xtype *, double *, \ int64_t *, int * ); DECLARE_GENERIC(D,double) DECLARE_GENERIC(F,float) DECLARE_GENERIC(I,int) DECLARE_GENERIC(UB,unsigned char) DECLARE_GENERIC(B,signed char) #if HAVE_LONG_DOUBLE /* Not normally implemented */ DECLARE_GENERIC(LD,long double) #endif #undef DECLARE_GENERIC static AstMapping *RemoveRegions( AstMapping *, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static double FindGradient( AstMapping *, double *, int, int, double, double, double *, int * ); static double J1Bessel( double, int * ); static double LocalMaximum( const MapData *, double, double, double [], int * ); static double MapFunction( const MapData *, const double [], int *, int * ); static double MatrixDet( int, int, const double *, int * ); static double MaxD( double, double, int * ); static double NewVertex( const MapData *, int, double, double [], double [], int *, double [], int * ); static double Random( long int *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static double UphillSimplex( const MapData *, double, int, const double [], double [], double *, int *, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetInvert( AstMapping *, int * ); static int GetIsLinear( AstMapping *, int * ); static int GetIsSimple( AstMapping *, int * ); static int GetNin( AstMapping *, int * ); static int GetNout( AstMapping *, int * ); static int GetReport( AstMapping *, int * ); static int GetTranForward( AstMapping *, int * ); static int GetTranInverse( AstMapping *, int * ); static int LinearApprox( AstMapping *, const double *, const double *, double, double *, int * ); static int MapList( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int MaxI( int, int, int * ); static int MinI( int, int, int * ); static int DoNotSimplify( AstMapping *, int * ); static int QuadApprox( AstMapping *, const double[2], const double[2], int, int, double *, double *, int * ); static int RebinAdaptively( AstMapping *, int, const int *, const int *, const void *, const void *, DataType, int, const double *, int, double, int, const void *, int, const int *, const int *, const int *, const int *, int, void *, void *, double *, int64_t *, int * ); static int RebinWithBlocking( AstMapping *, const double *, int, const int *, const int *, const void *, const void *, DataType, int, const double *, int, const void *, int, const int *, const int *, const int *, const int *, int, void *, void *, double *, int64_t *, int * ); static int ResampleAdaptively( AstMapping *, int, const int *, const int *, const void *, const void *, DataType, int, void (*)( void ), const double *, int, double, int, const void *, int, const int *, const int *, const int *, const int *, void *, void *, int * ); static int ResampleSection( AstMapping *, const double *, int, const int *, const int *, const void *, const void *, DataType, int, void (*)( void ), const double *, double, int, const void *, int, const int *, const int *, const int *, const int *, void *, void *, int * ); static int ResampleWithBlocking( AstMapping *, const double *, int, const int *, const int *, const void *, const void *, DataType, int, void (*)( void ), const double *, int, const void *, int, const int *, const int *, const int *, const int *, void *, void *, int * ); static int SpecialBounds( const MapData *, double *, double *, double [], double [], int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestInvert( AstMapping *, int * ); static int TestReport( AstMapping *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearInvert( AstMapping *, int * ); static void ClearReport( AstMapping *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Decompose( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void Gauss( double, const double [], int, double *, int * ); static void GlobalBounds( MapData *, double *, double *, double [], double [], int * ); static void Invert( AstMapping *, int * ); static void MapBox( AstMapping *, const double [], const double [], int, int, double *, double *, double [], double [], int * ); static void RateFun( AstMapping *, double *, int, int, int, double *, double *, int * ); static void RebinSection( AstMapping *, const double *, int, const int *, const int *, const void *, const void *, double, DataType, int, const double *, int, const void *, int, const int *, const int *, const int *, const int *, int, void *, void *, double *, int64_t *, int * ); static void ReportPoints( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetInvert( AstMapping *, int, int * ); static void SetReport( AstMapping *, int, int * ); static void Sinc( double, const double [], int, double *, int * ); static void SincCos( double, const double [], int, double *, int * ); static void SincGauss( double, const double [], int, double *, int * ); static void SincSinc( double, const double [], int, double *, int * ); static void Somb( double, const double [], int, double *, int * ); static void SombCos( double, const double [], int, double *, int * ); static void Tran1( AstMapping *, int, const double [], int, double [], int * ); static void Tran2( AstMapping *, int, const double [], const double [], int, double [], double [], int * ); static void TranGrid( AstMapping *, int, const int[], const int[], double, int, int, int, int, double *, int * ); static void TranGridAdaptively( AstMapping *, int, const int[], const int[], const int[], const int[], double, int, int, double *[], int * ); static void TranGridSection( AstMapping *, const double *, int, const int *, const int *, const int *, const int *, int, double *[], int * ); static void TranGridWithBlocking( AstMapping *, const double *, int, const int *, const int *, const int *, const int *, int, double *[], int * ); static void TranN( AstMapping *, int, int, int, const double *, int, int, int, double *, int * ); static void TranP( AstMapping *, int, int, const double *[], int, int, double *[], int * ); static void ValidateMapping( AstMapping *, int, int, int, int, const char *, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Mapping member function (over-rides the astClearAttrib protected * method inherited from the Object class). * Description: * This function clears the value of a specified attribute for a * Mapping, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Mapping. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMapping *this; /* Pointer to the Mapping structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Mapping structure. */ this = (AstMapping *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Invert. */ /* ------- */ if ( !strcmp( attrib, "invert" ) ) { astClearInvert( this ); /* Report. */ /* ------- */ } else if ( !strcmp( attrib, "report" ) ) { astClearReport( this ); /* If the name was not recognised, test if it matches any of the read-only attributes of this class. If it does, then report an error. */ } else if ( !strcmp( attrib, "nin" ) || !strcmp( attrib, "nout" ) || !strcmp( attrib, "issimple" ) || !strcmp( attrib, "islinear" ) || !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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } /* * Name: * ConserveFlux * Purpose: * Scale the output data and variance values produced by ResampleSection * by the given flux conservation factor. * Type: * Private function. * Synopsis: * #include "mapping.h" * void ConserveFlux( double factor, int npoint, const int *offset, * badval, *out, * *out_var ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which scale the supplied resampled data * values by the given flux conservation factor. It also scales any * variances by the square of the factor. * Parameters: * factor * The flux conservation factor. This should be the ratio of the * output pixel size to the input pixel size, in the locality of * the supplied data values. * npoint * The number of points at which the input grid was resampled. * offset * Pointer to an array of integers with "npoint" elements. For * each output point, this array should contain the zero-based * offset in the output array(s) (i.e. the "out" and, * optionally, the "out_var" arrays) at which the resampled * output value(s) is stored. * badval * This parameter specifies the value which is used to identify * bad data and/or variance values in the output array(s). * out * Pointer to an array in which the resampled data is supplied. Note * that details of how the output grid maps on to this array * (e.g. the storage order, number of dimensions, etc.) is * arbitrary and is specified entirely by means of the "offset" * array. The "out" array should therefore contain sufficient * elements to accommodate the "offset" values supplied. There * is no requirement that all elements of the "out" array should * be assigned values, and any which are not addressed by the * contents of the "offset" array will be left unchanged. * out_var * An optional pointer to an array with the same data type and * size as the "out" array, in which variance estimates for * the resampled values are supplied. If no output variance estimates * are available, a NULL pointer should be given. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_CONSERVEFLUX(X,Xtype) \ static void ConserveFlux##X( double factor, int npoint, const int *offset, \ Xtype badval, Xtype *out, Xtype *out_var, int *status ) { \ \ /* Local Variables: */ \ int off_out; /* Pixel offset into output array */ \ int point; /* Loop counter for output points */ \ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ for ( point = 0; point < npoint; point++ ) { \ off_out = offset[ point ]; \ if( out[ off_out ] != badval ) out[ off_out ] *= factor; \ } \ \ if( out_var ) { \ factor *= factor; \ for ( point = 0; point < npoint; point++ ) { \ off_out = offset[ point ]; \ if( out_var[ off_out ] != badval ) out_var[ off_out ] *= factor; \ } \ } \ } /* Expand the macro above to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_CONSERVEFLUX(LD,long double) #endif MAKE_CONSERVEFLUX(D,double) MAKE_CONSERVEFLUX(F,float) MAKE_CONSERVEFLUX(K,INT_BIG) MAKE_CONSERVEFLUX(L,long int) MAKE_CONSERVEFLUX(I,int) MAKE_CONSERVEFLUX(S,short int) MAKE_CONSERVEFLUX(B,signed char) MAKE_CONSERVEFLUX(UL,unsigned long int) MAKE_CONSERVEFLUX(UI,unsigned int) MAKE_CONSERVEFLUX(UK,UINT_BIG) MAKE_CONSERVEFLUX(US,unsigned short int) MAKE_CONSERVEFLUX(UB,unsigned char) /* Undefine the macros used above. */ #undef MAKE_CONSERVEFLUX static void Decompose( AstMapping *this, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { /* *+ * Name: * astDecompose * Purpose: * Decompose a Mapping into two component Mappings. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * void astDecompose( AstMapping *this, AstMapping **map1, * AstMapping **map2, int *series, int *invert1, * int *invert2 ) * Class Membership: * Mapping method. * Description: * This function returns pointers to two Mappings which, when applied * either in series or parallel, are equivalent to the supplied Mapping. * * Since the Frame class inherits from the Mapping class, Frames can * be considered as special types of Mappings and so this method can * be used to decompose CmpMaps, CmpFrames, CmpRegions or Prisms. * Parameters: * this * Pointer to the Mapping. * map1 * Address of a location to receive a pointer to first component * Mapping. * map2 * Address of a location to receive a pointer to second component * Mapping. * series * Address of a location to receive a value indicating if the * component Mappings are applied in series or parallel. A non-zero * value means that the supplied Mapping is equivalent to applying map1 * followed by map2 in series. A zero value means that the supplied * Mapping is equivalent to applying map1 to the lower numbered axes * and map2 to the higher numbered axes, in parallel. * invert1 * The value of the Invert attribute to be used with map1. * invert2 * The value of the Invert attribute to be used with map2. * Applicability: * CmpMap * If the supplied Mapping is a CmpMap, then map1 and map2 will be * returned holding pointers to the component Mappings used to * create the CmpMap, either in series or parallel. * Mapping * For any class of Mapping other than a CmpMap, map1 will be * returned holding a clone of the supplied Mapping pointer, and map2 * will be returned holding a NULL pointer. * CmpFrame * If the supplied Mapping is a CmpFrame, then map1 and map2 will be * returned holding pointers to the component Frames used to * create the CmpFrame. The component Frames are considered to be in * applied in parallel. * Frame * For any class of Frame other than a CmpFrame, map1 will be * returned holding a clone of the supplied Frame pointer, and map2 * will be returned holding a NULL pointer. * Notes: * - Any changes made to the component Mappings using the returned * pointers will be reflected in the supplied Mapping. * - The returned Invert values should be used in preference to the * current values of the Invert attribute in map1 and map2. This is * because the attributes may have changed value since the Mappings * were combined. * Implementation Notes: * - This function implements the basic astDecompose method * available via the protected interface to the Frame class. The * public interface to this method is provided by the * astDecomposeId_ function. *- */ /* Check the global error status. */ if ( !astOK ) return; /* The basic Mapping class returns a clone of the supplied Mapping as map1 and a NULL pointer as map2. */ if( map1 ) *map1 = astClone( this ); if( map2 ) *map2 = NULL; if( series ) *series = 1; if( invert1 ) *invert1 = astGetInvert( this ); if( invert2 ) *invert2 = 0; } static int DoNotSimplify( AstMapping *this, int *status ) { /* *+ * Name: * astMapMerge * Purpose: * Check if a Mapping is appropriate for simplification. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astDoNotSImplify( AstMapping *this ); * Class Membership: * Mapping method. * Description: * This function returns a flag indivating if the supplied Mapping is * appropriate for simplification. * Parameters: * this * Pointer to the Mapping. * Returned Value: * Non-zero if the supplied Mapping is not appropriate for * simplification, and zero otherwise. * Notes: * - A value of 0 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Check inherited status. */ if( !astOK ) return 0; /* Mappings that have a set value for the Ident attribute should not be simplified since we want to preserve their individual identify (otherwise why would the user have given them an Ident value?). */ return astTestIdent( this ); } int astRateState_( int disabled, int *status ) { /* *+ * Name: * astRateState * Purpose: * Control whether the astRate method is disabled or not. * Type: * Protected function. * Synopsis: * #include "mapping.h" * int astRateState( int disabled ) * Class Membership: * Mapping member function * Description: * Some algorithms which use use the astRate method do not actually need * to know what the Rate value is. For instance, when the Plot class draws * a border it evaluates the GRAPHICS->Current Mapping hundreds of time. * If the Mapping includes a RateMap then this can be very very slow * (depending on how the astRate method is implemented). In fact the * border drawing algorithm onlyneeds to know if the result is bad or * not - the actual value produced by the Mappign does not matter. * * Such algorithms can be speeded up by forcing the astRate method to * return a constant value rather than actually doing the numerical * differentiation. This can be accomplised by calling this method prior * to implementing the algorithm. It should be called at the end in * order to re-instate the original disabled flag. * Parameters: * disabled * The new value for the astRate disabled flag. * Returned Value: * The original value of the astRate disabled flag. *- */ astDECLARE_GLOBALS int result; astGET_GLOBALS(NULL); result = rate_disabled; rate_disabled = disabled; return result; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Mappings are equivalent. * Type: * Private function. * Synopsis: * #include "mapping.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * Mapping member function (over-rides the astEqual protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Mappings are equivalent. * * The implementation provided by this class (the base Mapping class) * simply reports an error when called, since all concrete Mapping * subclasses should provide their own implementation. * * Note, sub-class implementations should not use astSimplify (e.g. * combining the two Mapping and then simplifying it), since the * astSimplify method for certain classes (e.g. CmpMap) may use * astEqual. Consequently, if astEqual called astSimplify, there would * be possibilities for infinite loops. * Parameters: * this * Pointer to the first Object (a Mapping). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the Frames are equivalent, zero otherwise. * Notes: * - The two Mappings are considered equivalent if the combination of * the first in series with the inverse of the second simplifies to a * UnitMap. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the Equal method inherited from the parent Object class. This checks that the Objects are both of the same class (amongst other things). */ if( (*parent_equal)( this_object, that_object, status ) ) { /* Report an error since the concrete sub-class should have over-riden this method. */ astError( AST__INTER, "astEqual(Mapping): The %s class does " "not override the abstract astEqual method inherited " "from the base Mapping class (internal AST programming " "error).", status, astGetClass( this_object ) ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static double FindGradient( AstMapping *map, double *at, int ax1, int ax2, double x0, double h, double *range, int *status ){ /* * Name: * FindGradient * Purpose: * Find the mean gradient in an interval, and the range of gradients * within the interval. * Type: * Private function. * Synopsis: * #include "mapping.h" * double FindGradient( AstMapping *map, double *at, int ax1, int ax2, * double x0, double h, double *range, int *status ) * Class Membership: * Mapping method. * Description: * This function finds the mean gradient in an interval, and the range * of gradients within the interval. * Parameters: * map * Pointer to a Mapping which yields the value of the function at x. * The Mapping may have any number of inputs and outputs; the specific * output representing the function value, f, is specified by ax1 and * the specific input representing the argument, x, is specified by ax2. * at * A pointer to an array holding axis values at the position at which * the function is to be evaluated. The number of values supplied * must equal the number of inputs to the Mapping. The value supplied * for axis "ax2" is ignored (the value of "x" is used for axis "ax2"). * ax1 * The zero-based index of the Mapping output which is to be * differentiated. Set this to -1 to allocate, or -2 to release, * the static resources used by this function. * ax2 * The zero-based index of the Mapping input which is to be varied. * x0 * The central axis value at which the function is to be evaluated. * h * The interval over which the fitting is to be performed. * range * A pointer to a location at which to return the range of * gradients found within the interval. * status * Pointer to the inherited status variable. * Returns: * The mean gradient, or AST__BAD if the mean gradient cannot be * calculated. */ /* Local Variables: */ double dh; double g; double gmax; double gmin; double ret; double x1; double x2; double x[ RATE_ORDER + 2 ]; double y1; double y2; double y[ RATE_ORDER + 2 ]; int i0; int i; int ngood; /* Initialise */ ret = AST__BAD; /* Check the global error status. */ if ( !astOK ) return ret; /* Store the x values at (RATE_ORDER+1) evenly spaced points over the interval "h" centred on "x0". */ i0 = RATE_ORDER/2; dh = h/RATE_ORDER; for( i = 0; i <= RATE_ORDER; i++ ) { x[ i ] = x0 + ( i - i0 )*dh; } /* Get the function values at these positions. */ RateFun( map, at, ax1, ax2, RATE_ORDER + 1, x, y, status ); /* Find the maximum and minimum mean gradient within any sub-interval, and note the (x,y) values at the first and last good point within the interval. */ y1 = AST__BAD; y2 = AST__BAD; gmax = AST__BAD; gmin = AST__BAD; ngood = 0; for( i = 0; i < RATE_ORDER; i++ ) { if( y[ i + 1 ] !=AST__BAD && y[ i ] != AST__BAD && x[ i + 1 ] != x[ i ] ) { ngood++; g = ( y[ i + 1 ] - y[ i ] )/( x[ i + 1 ] - x[ i ] ); if( ngood == 1 ) { gmax = gmin = g; } else if( g < gmin ) { gmin = g; } else if( g > gmax) { gmax = g; } if( y1 == AST__BAD ) { y1 = y[ i ]; x1 = x[ i ]; } y2 = y[ i + 1 ]; x2 = x[ i + 1 ]; } } /* If two or more sub-intervals were usable, return the range of gradients found, and the mean gradient. */ if( ngood > 1 ) { ret = ( y2 - y1 )/( x2 - x1 ); if( range ) *range = ( gmax - gmin ); } return ret; } static void Gauss( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * Gauss * Purpose: * 1-dimensional Gaussian spreading kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void Gauss( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * spreading kernel. The function used is exp(-k*x*x). * Parameters: * offset * The offset of a pixel from the central output point, measured * in pixels. * params * The first element of this array should give a value for "k" * in the exp(-k*x*x) term. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Calculate the result. */ *value = exp( -params[ 0 ] * offset * offset ); } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Mapping member function (over-rides the protected astGetAttrib * method inherited from the Object class). * Description: * This function returns a pointer to the value of a specified * attribute for a Mapping, formatted as a character string. * Parameters: * this * Pointer to the Mapping. * 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 Mapping, 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 Mapping. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *this; /* Pointer to the Mapping structure */ const char *result; /* Pointer value to return */ int invert; /* Invert attribute value */ int islinear; /* IsLinear attribute value */ int issimple; /* IsSimple attribute value */ int nin; /* Nin attribute value */ int nout; /* Nout attribute value */ int report; /* Report attribute value */ int tran_forward; /* TranForward attribute value */ int tran_inverse; /* TranInverse attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Mapping structure. */ this = (AstMapping *) 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. */ /* Invert. */ /* ------- */ if ( !strcmp( attrib, "invert" ) ) { invert = astGetInvert( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", invert ); result = getattrib_buff; } /* IsLinear. */ /* --------- */ } else if ( !strcmp( attrib, "islinear" ) ) { islinear = astGetIsLinear( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", islinear ); result = getattrib_buff; } /* IsSimple. */ /* --------- */ } else if ( !strcmp( attrib, "issimple" ) ) { issimple = astGetIsSimple( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", issimple ); result = getattrib_buff; } /* Nin. */ /* ---- */ } else if ( !strcmp( attrib, "nin" ) ) { nin = astGetNin( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", nin ); result = getattrib_buff; } /* Nout. */ /* ----- */ } else if ( !strcmp( attrib, "nout" ) ) { nout = astGetNout( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", nout ); 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" ) ) { tran_forward = astGetTranForward( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", tran_forward ); result = getattrib_buff; } /* TranInverse. */ /* ------------ */ } else if ( !strcmp( attrib, "traninverse" ) ) { tran_inverse = astGetTranInverse( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", tran_inverse ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetIsLinear( AstMapping *this, int *status ) { /* *+ * Name: * astGetIsLinear * Purpose: * Determine if a Mapping is an instance of a linear Mapping class. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astGetIsLinear( AstMapping *this ) * Class Membership: * Mapping method. * Description: * This function returns a value indicating whether a Mapping is * a member of a class of linear Mappings. The base Mapping class * returns a value of zero. Linear Mapping classes should over-ride * this function to return a non-zero value. * Parameters: * this * Pointer to the Mapping. * Returned Value: * One if the Mapping is a member of a linear Mapping class. Zero * 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. *- */ return 0; } static int GetNin( AstMapping *this, int *status ) { /* *+ * Name: * astGetNin * Purpose: * Get the number of input coordinates for a Mapping. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astGetNin( AstMapping *this ) * Class Membership: * Mapping method. * Description: * This function returns the number of input coordinate values * required per point by a Mapping (i.e. the number of dimensions * of the space in which input points reside). * Parameters: * this * Pointer to the Mapping. * 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: */ int invert; /* Invert attribute value */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* Obtain the Nin value. */ if ( astOK ) result = invert ? this->nout : this->nin; /* Return the result. */ return result; } static int GetNout( AstMapping *this, int *status ) { /* *+ * Name: * astGetNout * Purpose: * Get the number of output coordinates for a Mapping. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astGetNout( AstMapping *this ) * Class Membership: * Mapping method. * Description: * This function returns the number of output coordinate values * generated per point by a Mapping (i.e. the number of dimensions * of the space in which output points reside). * Parameters: * this * Pointer to the Mapping. * Returned Value: * Number of coordinate values generated. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ int invert; /* Invert attribute value */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* Obtain the Nout value. */ if ( astOK ) result = invert ? this->nin : this->nout; /* Return the result. */ return result; } static int GetTranForward( AstMapping *this, int *status ) { /* *+ * Name: * astGetTranForward * Purpose: * Determine if a Mapping defines a forward coordinate transformation. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astGetTranForward( AstMapping *this ) * Class Membership: * Mapping method. * Description: * This function returns a value indicating whether a Mapping is * able to perform a coordinate transformation in the "forward" * direction. * Parameters: * this * Pointer to the Mapping. * 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: */ int invert; /* Mapping inverted? */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* If OK, obtain the result. */ if ( astOK ) result = invert ? this->tran_inverse : this->tran_forward; /* Return the result. */ return result; } static int GetTranInverse( AstMapping *this, int *status ) { /* *+ * Name: * astGetTranInverse * Purpose: * Determine if a Mapping defines an inverse coordinate transformation. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astGetTranInverse( AstMapping *this ) * Class Membership: * Mapping method. * Description: * This function returns a value indicating whether a Mapping is * able to perform a coordinate transformation in the "inverse" * direction. * Parameters: * this * Pointer to the Mapping. * 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: */ int invert; /* Mapping inverted? */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Determine if the Mapping has been inverted. */ invert = astGetInvert( this ); /* If OK, obtain the result. */ if ( astOK ) result = invert ? this->tran_forward : this->tran_inverse; /* Return the result. */ return result; } static void GlobalBounds( MapData *mapdata, double *lbnd, double *ubnd, double xl[], double xu[], int *status ) { /* * Name: * GlobalBounds * Purpose: * Estimate global coordinate bounds for a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GlobalBounds( MapData *mapdata, double *lbnd, double *ubnd, * double xl[], double xu[], int *status ); * Class Membership: * Mapping member function. * Description: * This function estimates the global lower and upper bounds of a * Mapping function within a constrained region of its input * coordinate space. It uses a robust global optimisation algorithm * based on the selection of pseudo-random starting positions, * followed by the location of local minima and maxima using the * downhill (or uphill) simplex method. The algorithm will cope * with the case where there are several competing minima (or * maxima) with nearly equal values. It attempts to locate the * global bounds to full machine precision when possible. * Parameters: * mapdata * Pointer to a MapData structure describing the Mapping * function, its coordinate constraints, etc. * lbnd * Pointer to a double. On entry, this should contain a * previously-obtained upper limit on the global lower bound, or * AST__BAD if no such limit is available. On exit, it will be * updated with a new estimate of the global lower bound, if a * better one has been found. * ubnd * Pointer to a double. On entry, this should contain a * previously-obtained lower limit on the global upper bound, or * AST__BAD if no such limit is available. On exit, it will be * updated with a new estimate of the global upper bound, if a * better one has been found. * xl * Pointer to an array of double, with one element for each * input coordinate. On entry, if *lbnd is not equal to AST__OK, * this should contain the input coordinates of a point at which * the Mapping function takes the value *lbnd. On exit, this * function returns the position of a (not necessarily unique) * input point at which the Mapping function takes the value of * the new global lower bound. This array is not altered if an * improved estimate of the global lower bound cannot be found. * xu * Pointer to an array of double, with one element for each * input coordinate. On entry, if *ubnd is not equal to AST__OK, * this should contain the input coordinates of a point at which * the Mapping function takes the value *ubnd. On exit, this * function returns the position of a (not necessarily unique) * input point at which the Mapping function takes the value of * the new global upper bound. This array is not altered if an * improved estimate of the global upper bound cannot be found. * status * Pointer to the inherited status variable. * Notes: * - The efficiency of this function will usually be improved if * previously-obtained estimates of the extrema and their locations * are provided. * - The values returned via "lbnd", "ubnd", "xl" and "xu" will be * set to the value AST__BAD if this function should fail for any * reason. Their initial values on entry will not be altered if the * function is invoked with the global error status set. */ /* Local Constants: */ const double default_acc = 3.0e-5; /* Default convergence accuracy */ const int maxiter = 10000; /* Maximum number of iterations */ const int minsame = 5; /* Minimum no. consistent extrema required */ const int nbatch = 32; /* No. function samples obtained per batch */ /* Local Variables: */ AstPointSet *pset_in; /* Input PointSet for batch transformation */ AstPointSet *pset_out; /* Output PointSet for batch transformation */ double **ptr_in; /* Pointer to batch input coordinates */ double **ptr_out; /* Pointer to batch output coordinates */ double *active_hi; /* Estimated upper limits of active region */ double *active_lo; /* Estimated lower limits of active region */ double *sample_hi; /* Upper limits of sampled region */ double *sample_lo; /* Lower limits of sampled region */ double *sample_width; /* Nominal widths of sampled region */ double *x; /* Pointer to array of coordinates */ double acc; /* Convergence accuracy for finding maximum */ double active_width; /* Estimated width of active region */ double new_max; /* Value of new local maximum */ double new_min; /* Value of new local minimum */ double oversize; /* Over-size factor for sampled region */ double random; /* Pseudo-random number */ int bad; /* Transformed position is bad? */ int batch; /* Next element to use in position batch */ int coord; /* Loop counter for coordinates */ int done_max; /* Satisfactory global maximum found? */ int done_min; /* Satisfactory global minimum found? */ int iter; /* Loop counter for iterations */ int ncoord; /* Number of coordinates in search space */ int nmax; /* Number of local maxima found */ int nmin; /* Number of local minima found */ int nsame_max; /* Number of equivalent local maxima found */ int nsame_min; /* Number of equivalent local minima found */ long int seed = 1776655449; /* Arbitrary pseudo-random number seed */ /* Check the global error status */ if ( !astOK ) return; /* Initialise. */ done_max = 0; done_min = 0; nmax = 0; nmin = 0; nsame_max = 0; nsame_min = 0; pset_in = NULL; pset_out = NULL; ptr_in = NULL; ptr_out = NULL; oversize = 0; bad = 0; /* Extract the number of input coordinates for the Mapping function and allocate workspace. */ ncoord = mapdata->nin; active_hi = astMalloc( sizeof( double ) * (size_t) ncoord ); active_lo = astMalloc( sizeof( double ) * (size_t) ncoord ); sample_hi = astMalloc( sizeof( double ) * (size_t) ncoord ); sample_lo = astMalloc( sizeof( double ) * (size_t) ncoord ); sample_width = astMalloc( sizeof( double ) * (size_t) ncoord ); x = astMalloc( sizeof( double ) * (size_t) ncoord ); if ( astOK ) { /* Calculate the factor by which the size of the region we sample will exceed the size of the Mapping function's active region (the region where the transformed coordinates are non-bad) in each dimension. This is chosen so that the volume ratio will be 2. */ oversize = pow( 2.0, 1.0 / (double) ncoord ); /* Initialise the limits of the active region to unknown. */ for ( coord = 0; coord < ncoord; coord++ ) { active_lo[ coord ] = DBL_MAX;; active_hi[ coord ] = -DBL_MAX; /* Initialise the nominal widths of the sampled region to be the actual widths of the search region times the over-size factor. */ sample_width[ coord ] = ( mapdata->ubnd[ coord ] - mapdata->lbnd[ coord ] ) * oversize; /* Initialise the sampled region to match the search region. */ sample_lo[ coord ] = mapdata->lbnd[ coord ]; sample_hi[ coord ] = mapdata->ubnd[ coord ]; } /* Set up position buffer. */ /* ======================= */ /* Create two PointSets to act as buffers to hold a complete batch of input and output coordinates. Obtain pointers to their coordinate arrays. */ pset_in = astPointSet( nbatch, ncoord, "", status ); pset_out = astPointSet( nbatch, mapdata->nout, "", status ); ptr_in = astGetPoints( pset_in ); ptr_out = astGetPoints( pset_out ); /* Initialise the next element to be used in the position buffer to indicate that the buffer is initially empty. */ batch = nbatch; } /* Define a macro to fill the position buffer with a set of pseudo-random positions and to transform them. */ #define FILL_POSITION_BUFFER {\ \ /* We first generate a suitable volume over which to distribute the\ batch of pseudo-random positions. Initially, this will be the\ entire search volume, but if we find that the only non-bad\ transformed coordinates we obtain are restricted to a small\ sub-region of this input volume, then we reduce the sampled volume\ so as to concentrate more on the active region. */\ \ /* Loop through each input coordinate, checking that at least one\ non-bad transformed point has been obtained. If not, we do not\ adjust the sampled volume, as we do not yet know where the active\ region lies. */\ for ( coord = 0; coord < ncoord; coord++ ) {\ if ( active_hi[ coord ] >= active_lo[ coord ] ) {\ \ /* Estimate the width of the active region from the range of input\ coordinates that have so far produced non-bad transformed\ coordinates. */\ active_width = active_hi[ coord ] - active_lo[ coord ];\ \ /* If the current width of the sampled volume exceeds this estimate by\ more than the required factor, then reduce the width of the sampled\ volume. The rate of reduction is set so that the volume of the\ sampled region can halve with every fourth batch of positions. */\ if ( ( active_width * oversize ) < sample_width[ coord ] ) {\ sample_width[ coord ] /= pow( oversize, 0.25 );\ \ /* If the width of the sampled volume does not exceed that of the\ known active region by the required factor, then adjust it so that\ it does. Note that we must continue to sample some points outside\ the known active region in case we have missed any (in which case\ the sampled region will expand again to include them). */\ } else if ( ( active_width * oversize ) > sample_width[ coord ] ) {\ sample_width[ coord ] = active_width * oversize;\ }\ \ /* Calculate the lower and upper bounds on the sampled volume, using\ the new width calculated above and centring it on the active\ region, as currently known. */\ sample_lo[ coord ] = ( active_lo[ coord ] + active_hi[ coord ] -\ sample_width[ coord ] ) * 0.5;\ sample_hi[ coord ] = ( active_lo[ coord ] + active_hi[ coord ] +\ sample_width[ coord ] ) * 0.5;\ \ /* Ensure that the sampled region does not extend beyond the original\ search region. */\ if ( sample_lo[ coord ] < mapdata->lbnd[ coord ] ) {\ sample_lo[ coord ] = mapdata->lbnd[ coord ];\ }\ if ( sample_hi[ coord ] > mapdata->ubnd[ coord ] ) {\ sample_hi[ coord ] = mapdata->ubnd[ coord ];\ }\ }\ }\ \ /* Having determined the size of the sampled volume, create a batch of\ pseudo-random positions uniformly distributed within it. */\ for ( batch = 0; batch < nbatch; batch++ ) {\ for ( coord = 0; coord < ncoord; coord++ ) {\ random = Random( &seed, status );\ ptr_in[ coord ][ batch ] = sample_lo[ coord ] * random +\ sample_hi[ coord ] * ( 1.0 - random );\ }\ }\ \ /* Transform these positions. We process them in a single batch in\ order to minimise the overheads in doing this. */\ (void) astTransform( mapdata->mapping, pset_in, mapdata->forward,\ pset_out );\ \ /* Indicate that the position buffer is now full. */\ batch = 0;\ } /* Fill the position buffer using the above macro. (Note that because we do not yet have an estimate of the size of the active region, this does not change the sampled region size from our earlier initialised values. */ FILL_POSITION_BUFFER; /* Iterate. */ /* ======== */ /* Loop to perform up to "maxiter" iterations to estimate the global minimum and maximum. */ for ( iter = 0; astOK && ( iter < maxiter ); iter++ ) { /* Determine the search accuracy. */ /* ============================== */ /* Decide the accuracy to which local extrema should be found. The intention here is to optimise performance, especially where one extremum lies near zero and so could potentially be found to unnecessarily high precision. If we make a mis-assumption (the code below is not fool-proof), we will slow things down for this iteration, but the error will be corrected in future iterations once better estimates are available. */ /* If we have no current estimate of either global extremum, we assume the values we eventually obtain will be of order unity and required to the default accuracy. */ acc = default_acc; /* If we already have an estimate of both global extrema, we set the accuracy level so that the difference between them will be known to the default accuracy. */ if ( ( *lbnd != AST__BAD ) && ( *ubnd != AST__BAD ) ) { acc = fabs( *ubnd - *lbnd ) * default_acc; /* If we have an estimate of only one global extremum, we assume that the difference between the two global extrema will eventually be of the same order as the estimate we currently have, so long as this is not less than unity. */ } else if ( *lbnd != AST__BAD ) { if ( fabs( *lbnd ) > 1.0 ) acc = fabs( *lbnd) * default_acc; } else if ( *ubnd != AST__BAD ) { if ( fabs( *ubnd ) > 1.0 ) acc = fabs( *ubnd) * default_acc; } /* Search for a new local minimum. */ /* =============================== */ /* If we are still searching for the global minimum, then obtain a set of starting coordinates from which to find a new local minimum. */ if ( !done_min ) { /* On the first iteration, start searching at the position where the best estimate of the global minimum (if any) has previously been found. We know that this produces non-bad transformed coordinates. */ bad = 0; if ( !iter && ( *lbnd != AST__BAD ) ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = xl[ coord ]; } /* Otherwise, if no estimate of the global minimum is available, then start searching at the position where the best estimate of the global maximum (if any) has been found. This may be a long way from a local minimum, but at least it will yield a non-bad value for the Mapping function, so some sort of estimate of the global minimum will be obtained. This is important in cases where finding the active region of the function is the main problem. Note that this condition can only occur once, since the global minimum will have an estimate on the next iteration. */ } else if ( ( *lbnd == AST__BAD ) && ( *ubnd != AST__BAD ) ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = xu[ coord ]; } /* Having exhausted the above possibilities, we use pseudo-random starting positions which are uniformly distributed throughout the search volume. First check to see if the buffer containing such positions is empty and refill it if necessary. */ } else { if ( batch >= nbatch ) FILL_POSITION_BUFFER; /* Test the next available set of output (transformed) coordinates in the position buffer to see if they are bad. */ if ( astOK ) { for ( coord = 0; coord < mapdata->nout; coord++ ) { bad = ( ptr_out[ coord ][ batch ] == AST__BAD ); if ( bad ) break; } /* If not, we have a good starting position for finding a local minimum, so extract the corresponding input coordinates. */ if ( !bad ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = ptr_in[ coord ][ batch ]; } } /* Increment the position buffer location. */ batch++; } } /* If we do not have a good starting position, we can't do anything more on this iteration. A new position will be obtained and tested on the next iteration and this (we hope) will eventually identify a suitable starting point. */ if ( astOK && !bad ) { /* Form estimates of the lower and upper limits of the active region from the starting positions used. */ for ( coord = 0; coord < ncoord; coord++ ) { if ( x[ coord ] < active_lo[ coord ] ) { active_lo[ coord ] = x[ coord ]; } if ( x[ coord ] > active_hi[ coord ] ) { active_hi[ coord ] = x[ coord ]; } } /* Indicate that the Mapping function should be negated (because we want a local minimum) and then search for a local maximum in this negated function. If the result is non-bad (as it should always be, barring an error), then negate it to obtain the value of the local minimum found. */ mapdata->negate = 1; new_min = LocalMaximum( mapdata, acc, 0.01, x, status ); if ( new_min != AST__BAD ) { new_min = -new_min; /* Update the estimates of the lower and upper bounds of the active region to take account of where the minimum was found. */ for ( coord = 0; coord < ncoord; coord++ ) { if ( x[ coord ] < active_lo[ coord ] ) { active_lo[ coord ] = x[ coord ]; } if ( x[ coord ] > active_hi[ coord ] ) { active_hi[ coord ] = x[ coord ]; } } /* Count the number of times we successfully locate a local minimum (ignoring the fact they might all be the same one). */ nmin++; /* Update the global minimum. */ /* ========================== */ /* If this is the first estimate of the global minimum, then set to one the count of the number of consecutive iterations where this estimate remains unchanged. Store the minimum value and its position. */ if ( *lbnd == AST__BAD ) { nsame_min = 1; *lbnd = new_min; for ( coord = 0; coord < ncoord; coord++ ) { xl[ coord ] = x[ coord ]; } /* Otherwise, test if this local minimum is lower than the previous estimate of the global minimum. If so, then reset the count of unchanged estimates of the global mimimum to one if the difference exceeds the accuracy with which the minimum was found (i.e. if we have found a significantly different minimum). Otherwise, just increment this count (because we have found the same minimum but by chance with slightly improved accuracy). Store the new minimum and its position. */ } else if ( new_min < *lbnd ) { nsame_min = ( ( *lbnd - new_min ) > acc ) ? 1 : nsame_min + 1; *lbnd = new_min; for ( coord = 0; coord < ncoord; coord++ ) { xl[ coord ] = x[ coord ]; } /* If the latest local minimum is no improvement on previous estimates of the global minimum, then increment the count of unchanged estimates of the global mimimum, but do not save the new one. */ } else { nsame_min++; } /* Determine if a satisfactory estimate of the global minimum has been obtained. It has if the number of consecutive local minima which have not significantly improved the estimate is at least equal to "minsame", and at least 30% of the total number of local minima found. */ if ( ( nsame_min >= minsame ) && ( nsame_min >= (int) ( 0.3f * (float) nmin + 0.5f ) ) ) { done_min = 1; } } } } /* Search for a new local maximum. */ /* =============================== */ /* Now repeat all of the above to find a new local maximum which estimates the global maximum. */ if ( !done_max ) { /* Choose a suitable starting position, based on one already available if appropriate. */ if ( !iter && ( *ubnd != AST__BAD ) ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = xu[ coord ]; } } else if ( ( *ubnd == AST__BAD ) && ( *lbnd != AST__BAD ) ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = xl[ coord ]; } /* Otherwise use a pseudo-random position, refilling the position buffer if necessary. Check if the transformed coordinates are bad. */ } else { if ( batch >= nbatch ) FILL_POSITION_BUFFER; if ( astOK ) { for ( coord = 0; coord < mapdata->nout; coord++ ) { bad = ( ptr_out[ coord ][ batch ] == AST__BAD ); if ( bad ) break; } if ( !bad ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ coord ] = ptr_in[ coord ][ batch ]; } } batch++; } } /* If the coordinates are OK, update the active region limits. */ if ( astOK && !bad ) { for ( coord = 0; coord < ncoord; coord++ ) { if ( x[ coord ] < active_lo[ coord ] ) { active_lo[ coord ] = x[ coord ]; } if ( x[ coord ] > active_hi[ coord ] ) { active_hi[ coord ] = x[ coord ]; } } /* Find a local maximum in the Mapping function. */ mapdata->negate = 0; new_max = LocalMaximum( mapdata, acc, 0.01, x, status ); if ( new_max != AST__BAD ) { /* Use the result to further update the active region limits. */ for ( coord = 0; coord < ncoord; coord++ ) { if ( x[ coord ] < active_lo[ coord ] ) { active_lo[ coord ] = x[ coord ]; } if ( x[ coord ] > active_hi[ coord ] ) { active_hi[ coord ] = x[ coord ]; } } /* Count the number of local maxima found. */ nmax++; /* Update the estimate of the global maximum. */ if ( *ubnd == AST__BAD ) { nsame_max = 1; *ubnd = new_max; for ( coord = 0; coord < ncoord; coord++ ) { xu[ coord ] = x[ coord ]; } } else if ( new_max > *ubnd ) { nsame_max = ( ( new_max - *ubnd ) > acc ) ? 1 : nsame_max + 1; *ubnd = new_max; for ( coord = 0; coord < ncoord; coord++ ) { xu[ coord ] = x[ coord ]; } } else { nsame_max++; } /* Test for a satisfactory global maximum estimate. */ if ( ( nsame_max >= minsame ) && ( nsame_max >= (int) ( 0.3f * (float) nmax + 0.5 ) ) ) { done_max = 1; } } } } /* Quit iterating once both the global minimum and the global maximum have been found. */ if ( done_min && done_max ) break; } /* Free workspace. */ active_hi = astFree( active_hi ); active_lo = astFree( active_lo ); sample_hi = astFree( sample_hi ); sample_lo = astFree( sample_lo ); sample_width = astFree( sample_width ); x = astFree( x ); /* Annul temporary PointSets. */ pset_in = astAnnul( pset_in ); pset_out = astAnnul( pset_out ); /* If the global minimum has been found, attempt to polish the result to machine precision by requesting that it be found with an accuracy tolerance of zero (subject to the maximum number of iterations that LocalMaximum will perform,). */ if ( astOK ) { if ( *lbnd != AST__BAD ) { mapdata->negate = 1; *lbnd = LocalMaximum( mapdata, 0.0, sqrt( DBL_EPSILON ), xl, status ); if ( *lbnd != AST__BAD ) *lbnd = - *lbnd; } /* Similarly polish the estimate of the global maximum. */ if ( *ubnd != AST__BAD ) { mapdata->negate = 0; *ubnd = LocalMaximum( mapdata, 0.0, sqrt( DBL_EPSILON ), xu, status ); } /* If either extremum could not be found, then report an error. */ if ( ( *lbnd == AST__BAD ) || ( *ubnd == AST__BAD ) ) { astError( AST__MBBNF, "astMapBox(%s): No valid output coordinates " "(after %d test points).", status, astGetClass( mapdata->mapping ), 2 * maxiter ); } /* If an error occurred, then return bad extremum values and coordinates. */ if ( !astOK ) { *lbnd = AST__BAD; *ubnd = AST__BAD; for ( coord = 0; coord < ncoord; coord++ ) { xl[ coord ] = AST__BAD; xu[ coord ] = AST__BAD; } } } /* Undefine macros local to this function. */ #undef FILL_POSITION_BUFFER } void astInitMappingVtab_( AstMappingVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitMappingVtab * Purpose: * Initialise a virtual function table for a Mapping. * Type: * Protected function. * Synopsis: * #include "mapping.h" * void astInitMappingVtab( AstMappingVtab *vtab, const char *name ) * Class Membership: * Mapping vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Mapping class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ /* 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. */ astInitObjectVtab( (AstObjectVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAMapping) 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 = &(((AstObjectVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ #define VTAB_GENERIC(X) \ vtab->Resample##X = Resample##X; VTAB_GENERIC(B) VTAB_GENERIC(D) VTAB_GENERIC(F) VTAB_GENERIC(I) VTAB_GENERIC(K) VTAB_GENERIC(L) VTAB_GENERIC(S) VTAB_GENERIC(UB) VTAB_GENERIC(UI) VTAB_GENERIC(UK) VTAB_GENERIC(UL) VTAB_GENERIC(US) #if HAVE_LONG_DOUBLE /* Not normally implemented */ VTAB_GENERIC(LD) #endif #undef VTAB_GENERIC #define VTAB_GENERIC(X) \ vtab->Rebin##X = Rebin##X; \ vtab->RebinSeq##X = RebinSeq##X; VTAB_GENERIC(D) VTAB_GENERIC(F) VTAB_GENERIC(I) VTAB_GENERIC(B) VTAB_GENERIC(UB) #if HAVE_LONG_DOUBLE /* Not normally implemented */ VTAB_GENERIC(LD) #endif #undef VTAB_GENERIC vtab->ClearInvert = ClearInvert; vtab->ClearReport = ClearReport; vtab->Decompose = Decompose; vtab->DoNotSimplify = DoNotSimplify; vtab->GetInvert = GetInvert; vtab->GetIsLinear = GetIsLinear; vtab->GetIsSimple = GetIsSimple; vtab->GetNin = GetNin; vtab->GetNout = GetNout; vtab->GetReport = GetReport; vtab->GetTranForward = GetTranForward; vtab->GetTranInverse = GetTranInverse; vtab->Invert = Invert; vtab->LinearApprox = LinearApprox; vtab->MapBox = MapBox; vtab->MapList = MapList; vtab->MapMerge = MapMerge; vtab->MapSplit = MapSplit; vtab->QuadApprox = QuadApprox; vtab->Rate = Rate; vtab->ReportPoints = ReportPoints; vtab->RemoveRegions = RemoveRegions; vtab->SetInvert = SetInvert; vtab->SetReport = SetReport; vtab->Simplify = Simplify; vtab->TestInvert = TestInvert; vtab->TestReport = TestReport; vtab->Tran1 = Tran1; vtab->Tran2 = Tran2; vtab->TranGrid = TranGrid; vtab->TranN = TranN; vtab->TranP = TranP; vtab->Transform = Transform; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_equal = object->Equal; object->Equal = Equal; /* Declare the destructor, copy constructor and dump function. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Mapping", "Mapping between 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) ); } } /* * Name: * InterpolateKernel1 * Purpose: * Resample a data grid, using a 1-d interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * int InterpolateKernel1( AstMapping *this, int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const *in, const *in_var, * int npoint, const int *offset, * const double *const *coords, * void (* kernel)( double, const double [], int, * double *, int * ), * void (* fkernel)( double, const double [], int, * double * ), * int neighb, const double *params, int flags, * badval, * *out, *out_var ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which resample a rectangular input * grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each output * grid point may be mapped on to a position in the input grid in * an arbitrary way. The input and output grids may have any number * of dimensions, not necessarily equal. * * Where the positions given do not correspond with a pixel centre * in the input grid, interpolation is performed using a weighted * sum of the surrounding pixel values. The weights are determined * by a separable kernel which is the product of a 1-dimensional * kernel function evaluated along each input dimension. A pointer * should be supplied to the 1-dimensional kernel function to be * used. * Parameters: * this * Pointer to the Mapping being used in the resampling operation * (this is only used for constructing error messages). * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input grid, its extent along a particular * (i'th) dimension being ubnd_in[i]-lbnd_in[i]+1 (assuming "i" * is zero-based). They also define the input grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be resampled (with an element * for each pixel in the input grid). The numerical type of * these data should match the function used, as given by the * suffix on the function name. The storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly * (i.e. Fortran array storage order). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. * * If no variance estimates are required, a NULL pointer should * be given. * npoint * The number of points at which the input grid is to be * resampled. * offset * Pointer to an array of integers with "npoint" elements. For * each output point, this array should contain the zero-based * offset in the output array(s) (i.e. the "out" and, * optionally, the "out_var" arrays) at which the resampled * output value(s) should be stored. * coords * An array of pointers to double, with "ndim_in" * elements. Element "coords[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contains the values of coordinate number "coord" for each * interpolation point. The value of coordinate number "coord" * for interpolation point number "point" is therefore given by * "coords[coord][point]" (assuming both indices to be * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding output data (and * variance) will be set to the value given by "badval" (unles the * AST__NOBAD flag is specified). * kernel * Pointer to the 1-dimensional kernel function to be used. * fkernel * Pointer to the 1-dimensional kernel function to be used with no * trailing status argument. This is only used if "kernel" is NULL. * neighb * The number of neighbouring pixels in each dimension (on each * side of the interpolation position) which are to contribute * to the interpolated value. This value should be at least 1. * params * Pointer to an optional array of parameter values to be passed * to the interpolation kernel function. If no parameters are * required by this function, then a NULL pointer may be * supplied. * flags * The bitwise OR of a set of flag values which provide * additional control over the resampling operation. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. Unles the AST__NOBAD flag is specified in "flags", the * same value will also be used to flag any output array elements * for which resampled values could not be obtained. The output * arrays(s) may be flagged with this value whether or not the * AST__USEBAD flag is set (the function return value indicates * whether any such values have been produced). * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. Note * that details of how the output grid maps on to this array * (e.g. the storage order, number of dimensions, etc.) is * arbitrary and is specified entirely by means of the "offset" * array. The "out" array should therefore contain sufficient * elements to accommodate the "offset" values supplied. There * is no requirement that all elements of the "out" array should * be assigned values, and any which are not addressed by the * contents of the "offset" array will be left unchanged. * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. It is addressed in * exactly the same way (via the "offset" array) as the "out" * array. The values returned are estimates of the statistical * variance of the corresponding values in the "out" array, on * the assumption that all errors in input grid values (in the * "in" array) are statistically independent and that their * variance estimates (in the "in_var" array) may simply be * summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * Returned Value: * The number of output grid points for which no valid output value * could be obtained. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. * - A value of zero will be returned if any of these functions is * invoked with the global error status set, or if it should fail * for any reason. */ /* Define macros to implement the function for a specific data type. */ #define MAKE_INTERPOLATE_KERNEL1(X,Xtype,Xfloating,Xfloattype,Xsigned) \ static int InterpolateKernel1##X( AstMapping *this, int ndim_in, \ const int *lbnd_in, const int *ubnd_in, \ const Xtype *in, const Xtype *in_var, \ int npoint, const int *offset, \ const double *const *coords, \ void (* kernel)( double, const double [], \ int, double *, int * ), \ void (* fkernel)( double, const double [], \ int, double * ), \ int neighb, const double *params, \ int flags, Xtype badval, \ Xtype *out, Xtype *out_var, int *status ) { \ \ /* Local Variables: */ \ astDECLARE_GLOBALS /* Thread-specific data */ \ Xfloattype hi_lim; /* Upper limit on output values */ \ Xfloattype lo_lim; /* Lower limit on output values */ \ Xfloattype sum; /* Weighted sum of pixel data values */ \ Xfloattype sum_var; /* Weighted sum of pixel variance values */ \ Xfloattype val; /* Data value to be assigned to output */ \ Xfloattype val_var; /* Variance to be assigned to output */ \ Xfloattype wtsum; /* Sum of weight values */ \ Xfloattype wtsum_sq; /* Square of sum of weights */ \ Xtype var; /* Variance value */ \ double **wtptr; /* Pointer to array of weight pointers */ \ double **wtptr_last; /* Array of highest weight pointer values */ \ double *kval; /* Pointer to array of kernel values */ \ double *wtprod; /* Accumulated weight value array pointer */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double pixwt; /* Weight to apply to individual pixel */ \ double wt_y; /* Value of y-dependent pixel weight */ \ double x; /* x coordinate value */ \ double xmax; /* x upper limit */ \ double xmin; /* x lower limit */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ double ymax; /* y upper limit */ \ double ymin; /* y lower limit */ \ int *hi; /* Pointer to array of upper indices */ \ int *lo; /* Pointer to array of lower indices */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int bad_var; /* Output variance bad? */ \ int done; /* All pixel indices done? */ \ int hi_x; /* Upper pixel index (x dimension) */ \ int hi_y; /* Upper pixel index (y dimension) */ \ int idim; /* Loop counter for dimensions */ \ int ii; /* Loop counter for dimensions */ \ int ix; /* Pixel index in input grid x dimension */ \ int ixn; /* Pixel index in input grid (n-d) */ \ int iy; /* Pixel index in input grid y dimension */ \ int kerror; /* Error signalled by kernel function? */ \ int lo_x; /* Lower pixel index (x dimension) */ \ int lo_y; /* Lower pixel index (y dimension) */ \ int nobad; /* Was the AST__NOBAD flag set? */ \ int off1; /* Input pixel offset due to y index */ \ int off_in; /* Offset to input pixel */ \ int off_out; /* Offset to output pixel */ \ int pixel; /* Offset to input pixel containing point */ \ int point; /* Loop counter for output points */ \ int result; /* Result value to return */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int ystride; /* Stride along input grid y dimension */ \ \ /* Initialise. */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get a pointer to a structure holding thread-specific global data values */ \ astGET_GLOBALS(this); \ \ /* Further initialisation. */ \ kerror = 0; \ sum_var = 0; \ val = 0; \ val_var = 0; \ wtsum = 0; \ bad = 0; \ bad_var = 0; \ sum = 0.0; \ \ /* Determine if we are processing bad pixels or variances. */ \ nobad = flags & AST__NOBAD; \ usebad = flags & AST__USEBAD; \ usevar = in_var && out_var; \ \ /* Set up limits for checking output values to ensure that they do not \ overflow the range of the data type being used. */ \ lo_lim = LO_##X; \ hi_lim = HI_##X; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_in == 1 ) { \ \ /* Calculate the coordinate limits of the input grid. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Four more cases as above, but this time with the AST__NOBAD flag \ un-set. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ \ /* Exit point on error in kernel function */ \ Kernel_Error_1d: ; \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_in == 2 ) { \ \ /* Allocate workspace. */ \ kval = astMalloc( sizeof( double ) * (size_t) ( 2 * neighb ) ); \ if ( astOK ) { \ \ /* Calculate the stride along the y dimension of the input grid. */ \ ystride = ubnd_in[ 0 ] - lbnd_in[ 0 ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ ymin = (double) lbnd_in[ 1 ] - 0.5; \ ymax = (double) ubnd_in[ 1 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Another four cases, as above, but this time without the AST__NOBAD \ flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ \ /* Exit point on error in kernel function */ \ Kernel_Error_2d: ; \ } \ \ /* Free the workspace. */ \ kval = astFree( kval ); \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ hi = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ lo = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ kval = astMalloc( sizeof( double ) * (size_t) \ ( 2 * neighb * ndim_in ) ); \ wtprod = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ wtptr = astMalloc( sizeof( double * ) * (size_t) ndim_in ); \ wtptr_last = astMalloc( sizeof( double * ) * (size_t) ndim_in ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the input grid. */ \ for ( s = 1, idim = 0; idim < ndim_in; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_in[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_in[ idim ] + 0.5; \ } \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Another 4 cases as above, but this time with the AST__NOBAD flag \ un-set. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ \ /* Exit point on error in kernel function */ \ Kernel_Error_Nd: ;\ } \ \ /* Free the workspace. */ \ hi = astFree( hi ); \ lo = astFree( lo ); \ stride = astFree( stride ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ kval = astFree( kval ); \ wtprod = astFree( wtprod ); \ wtptr = astFree( wtptr ); \ wtptr_last = astFree( wtptr_last ); \ } \ \ /* If an error occurred in the kernel function, then report a \ contextual error message. */ \ if ( kerror ) { \ astError( astStatus, "astResample"#X"(%s): Error signalled by " \ "user-supplied 1-d interpolation kernel.", status, \ astGetClass( unsimplified_mapping ) ); \ } \ \ /* If an error has occurred, clear the returned result. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 1-dimensional case. */ #define ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid, or is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If input bad pixels must be detected, then obtain the offset along \ the input grid x dimension of the input pixel which contains the \ current coordinate, and calculate this pixel's offset from the \ start of the input array. */ \ if ( Usebad ) { \ pixel = (int) floor( x + 0.5 ) - lbnd_in[ 0 ]; \ \ /* Test if the pixel is bad. */ \ bad = ( in[ pixel ] == badval ); \ } \ \ /* If OK, calculate the lowest and highest indices (in the x \ dimension) of the region of neighbouring pixels that will \ contribute to the interpolated result. Constrain these values to \ lie within the input grid. */ \ if ( !bad ) { \ ix = (int) floor( x ); \ lo_x = MaxI( ix - neighb + 1, lbnd_in[ 0 ], status ); \ hi_x = MinI( ix + neighb, ubnd_in[ 0 ], status ); \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ \ /* Loop to inspect all the contributing pixels, calculating the offset \ of each pixel from the start of the input array. */ \ off_in = lo_x - lbnd_in[ 0 ]; \ for ( ix = lo_x; ix <= hi_x; ix++, off_in++ ) { \ \ /* If necessary, test if the input pixel is bad. If not, calculate its \ weight by evaluating the kernel function. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ if( kernel ) { \ ( *kernel )( (double) ix - x, params, flags, &pixwt, status ); \ } else { \ ( *fkernel )( (double) ix - x, params, flags, &pixwt ); \ } \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_Error_1d; \ } \ \ /* Form the weighted sums required for finding the interpolated \ value. */ \ sum += ( (Xfloattype) pixwt ) * ( (Xfloattype) in[ off_in ] ); \ wtsum += (Xfloattype) pixwt; \ \ /* If a variance estimate is required and it still seems possible to \ obtain one, then obtain the variance value associated with the \ current input pixel. */ \ if ( Usevar ) { \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ var = in_var[ off_in ]; \ \ /* If necessary, test if this value is bad (if the data type is \ signed, also check that it is not negative). */ \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If any bad input variance value is obtained, we cannot generate a \ valid output variance estimate. Otherwise, form the sum needed to \ calculate this estimate. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ sum_var += ( (Xfloattype) ( pixwt * pixwt ) ) * \ ( (Xfloattype) var ); \ } \ } \ } \ } \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 2-dimensional case. */ #define ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid, or is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If not, then similarly obtain and test the y coordinate. */ \ y = coords[ 1 ][ point ]; \ bad = ( y < ymin ) || ( y >= ymax ) || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* If input bad pixels must be detected, then obtain the offsets along \ each input grid dimension of the input pixel which contains the \ current coordinates, and calculate this pixel's offset from the \ start of the input array. */ \ if ( Usebad ) { \ ix = (int) floor( x + 0.5 ); \ iy = (int) floor( y + 0.5 ); \ pixel = ix - lbnd_in[ 0 ] + ystride * ( iy - lbnd_in[ 1 ] ); \ \ /* Test if the pixel is bad. */ \ bad = ( in[ pixel ] == badval ); \ } \ \ /* If OK, calculate the lowest and highest indices (in each dimension) \ of the region of neighbouring pixels that will contribute to the \ interpolated result. Constrain these values to lie within the input \ grid. */ \ if ( !bad ) { \ ix = (int) floor( x ); \ lo_x = MaxI( ix - neighb + 1, lbnd_in[ 0 ], status ); \ hi_x = MinI( ix + neighb, ubnd_in[ 0 ], status ); \ iy = (int) floor( y ); \ lo_y = MaxI( iy - neighb + 1, lbnd_in[ 1 ], status ); \ hi_y = MinI( iy + neighb, ubnd_in[ 1 ], status ); \ \ /* Loop to evaluate the kernel function along the x dimension, storing \ the resulting values. The function's argument is the offset of the \ contributing pixel (along this dimension) from the input \ position. */ \ for ( ix = lo_x; ix <= hi_x; ix++ ) { \ if( kernel ) { \ ( *kernel )( (double) ix - x, params, flags, \ kval + ix - lo_x, status ); \ } else { \ ( *fkernel )( (double) ix - x, params, flags, \ kval + ix - lo_x ); \ } \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_Error_2d; \ } \ } \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ \ /* Loop over the y index to inspect all the contributing pixels, while \ keeping track of their offset within the input array. Evaluate the \ kernel function for each y index value. */ \ off1 = lo_x - lbnd_in[ 0 ] + ystride * ( lo_y - lbnd_in[ 1 ] ); \ for ( iy = lo_y; iy <= hi_y; iy++, off1 += ystride ) { \ if( kernel ) { \ ( *kernel )( (double) iy - y, params, flags, &wt_y, status ); \ } else { \ ( *fkernel )( (double) iy - y, params, flags, &wt_y ); \ } \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_Error_2d; \ } \ \ /* Loop over the x index, calculating the pixel offset in the input \ array. */ \ off_in = off1; \ for ( ix = lo_x; ix <= hi_x; ix++, off_in++ ) { \ \ /* If necessary, test if the input pixel is bad. If not, calculate its \ weight as the product of the kernel function's value for the x and \ y dimensions. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ pixwt = kval[ ix - lo_x ] * wt_y; \ \ /* Form the weighted sums required for finding the interpolated \ value. */ \ sum += ( (Xfloattype) pixwt ) * \ ( (Xfloattype) in[ off_in ] ); \ wtsum += (Xfloattype) pixwt; \ \ /* If a variance estimate is required and it still seems possible to \ obtain one, then obtain the variance value associated with the \ current input pixel. */ \ if ( Usevar ) { \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ var = in_var[ off_in ]; \ \ /* If necessary, test if this value is bad (if the data type is \ signed, also check that it is not negative). */ \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If any bad input variance value is obtained, we cannot generate a \ valid output variance estimate. Otherwise, form the sum needed to \ calculate this estimate. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || \ !bad_var ) { \ sum_var += ( (Xfloattype) ( pixwt * pixwt ) ) * \ ( (Xfloattype) var ); \ } \ } \ } \ } \ } \ } \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the n-dimensional case. */ #define ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Initialise offsets into the input array. Then loop to obtain each \ coordinate associated with the current output point. */ \ pixel = 0; \ off_in = 0; \ for ( idim = 0; idim < ndim_in; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate lies outside the input grid, or is bad. If \ either is true, the corresponding output pixel value will be bad, \ so give up on this point. */ \ bad = ( xn < xn_min[ idim ] ) || ( xn >= xn_max[ idim ] ) || \ ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* If input bad pixels must be detected, then obtain the index along \ the current input grid dimension of the pixel which contains this \ coordinate and accumulate the pixel's offset from the start of the \ input array. */ \ if ( Usebad ) { \ pixel += stride[ idim ] * \ ( (int) floor( xn + 0.5 ) - lbnd_in[ idim ] ); \ } \ \ /* Calculate the lowest and highest indices (in the current dimension) \ of the region of neighbouring pixels that will contribute to the \ interpolated result. Constrain these values to lie within the input \ grid. */ \ ixn = (int) floor( xn ); \ lo[ idim ] = MaxI( ixn - neighb + 1, lbnd_in[ idim ], status ); \ hi[ idim ] = MinI( ixn + neighb, ubnd_in[ idim ], status ); \ \ /* Accumulate the offset (from the start of the input array) of the \ contributing pixel which has the lowest index in each dimension. */ \ off_in += stride[ idim ] * ( lo[ idim ] - lbnd_in[ idim ] ); \ } \ \ /* Once the input pixel which contains the required coordinates has \ been identified, test if it is bad, if necessary. */ \ if ( Usebad ) bad = bad || ( in[ pixel ] == badval ); \ \ /* If OK, loop to evaluate the kernel function which will be used to \ weight the contributions from surrounding pixels. */ \ if ( !bad ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ \ /* Set up an array of pointers to locate kernel values (stored in the \ "kval" array) for each dimension. Initially, each of these pointers \ locates the first weight value which applies to the contributing \ pixel with the lowest index in each dimension. */ \ wtptr[ idim ] = kval + ( 2 * neighb * idim ); \ \ /* Also set up pointers to the last weight value in each dimension. */ \ wtptr_last[ idim ] = wtptr[ idim ] + ( hi[ idim ] - lo[ idim ] ); \ \ /* Loop to evaluate the kernel function along each dimension, storing \ the resulting values. The function's argument is the offset of the \ contributing pixel (along the relevant dimension) from the input \ point. */ \ xn = coords[ idim ][ point ]; \ for ( ixn = lo[ idim ]; ixn <= hi[ idim ]; ixn++ ) { \ if( kernel ) { \ ( *kernel )( (double) ixn - xn, params, flags, \ wtptr[ idim ] + ixn - lo[ idim ], status ); \ } else { \ ( *fkernel )( (double) ixn - xn, params, flags, \ wtptr[ idim ] + ixn - lo[ idim ] ); \ } \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_Error_Nd; \ } \ } \ } \ \ /* Initialise, and loop over the neighbouring input pixels to obtain \ an interpolated value. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ idim = ndim_in - 1; \ wtprod[ idim ] = 1.0; \ done = 0; \ do { \ \ /* Each contributing pixel is weighted by the product of the kernel \ weight factors evaluated along each input dimension. However, since \ we typically only change the index of one dimension at a time, we \ can avoid forming this product repeatedly by retaining an array of \ accumulated products for all higher dimensions. We need then only \ update the lower elements in this array, corresponding to those \ dimensions whose index has changed. We do this here, "idim" being \ the index of the most significant dimension to have changed. Note \ that on the first pass, all dimensions are considered changed, \ causing this array to be initialised. */ \ for ( ii = idim; ii >= 1; ii-- ) { \ wtprod[ ii - 1 ] = wtprod[ ii ] * *( wtptr[ ii ] ); \ } \ \ /* If necessary, test each pixel which may contribute to the result to \ see if it is bad. If not, obtain its weight from the accumulated \ product of weights. Also multiply by the weight for dimension zero, \ which is not included in the "wtprod" array). */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ pixwt = wtprod[ 0 ] * *( wtptr[ 0 ] ); \ \ /* Form the weighted sums required for finding the interpolated \ value. */ \ sum += ( (Xfloattype) pixwt ) * ( (Xfloattype) in[ off_in ] ); \ wtsum += (Xfloattype) pixwt; \ \ /* If a variance estimate is required and it still seems possible to \ obtain one, then obtain the variance value associated with the \ current input pixel. */ \ if ( Usevar ) { \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ var = in_var[ off_in ]; \ \ /* If necessary, test if this value is bad (if the data type is \ signed, also check that it is not negative). */ \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If any bad input variance value is obtained, we cannot generate a \ valid output variance estimate. Otherwise, form the sum needed to \ calculate this estimate. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ sum_var += ( (Xfloattype) ( pixwt * pixwt ) ) * \ ( (Xfloattype) var ); \ } \ } \ } \ } \ \ /* Now update the weight value pointers and pixel offset to refer to \ the next input pixel to be considered. */ \ idim = 0; \ do { \ \ /* The first input dimension whose weight value pointer has not yet \ reached its final value has this pointer incremented, and the pixel \ offset into the input array is updated accordingly. */ \ if ( wtptr[ idim ] != wtptr_last[ idim ] ) { \ wtptr[ idim ]++; \ off_in += stride[ idim ]; \ break; \ \ /* Any earlier dimensions (which have reached the final pointer value) \ have this pointer returned to its lowest value. Again, the pixel \ offset into the input image is updated accordingly. */ \ } else { \ wtptr[ idim ] -= ( hi[ idim ] - lo[ idim ] ); \ off_in -= stride[ idim ] * \ ( hi[ idim ] - lo[ idim ] ); \ done = ( ++idim == ndim_in ); \ } \ } while ( !done ); \ } while ( !done ); \ } /* This subsidiary macro calculates the interpolated output value (and variance) from the sums over contributing pixels, checks the results for validity, and assigns them to the output array(s). */ #define CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Usebad,Usevar,Nobad) \ \ /* If the output data value has not yet been flagged as bad, then \ check that an interpolated value can actually be produced. First \ check that the sum of weights is not zero. */ \ if ( !bad ) { \ bad = ( wtsum == (Xfloattype) 0.0 ); \ \ /* If OK, calculate the interpolated value. Then, if the output data \ type is not floating point, check that this value will not overflow \ the available output range. */ \ if ( !bad ) { \ val = sum / wtsum; \ if ( !( Xfloating ) ) { \ bad = ( val <= lo_lim ) || ( val >= hi_lim ); \ } \ } \ \ /* If no interpolated data value can be produced, then no associated \ variance will be required either. */ \ if ( ( Usevar ) && bad ) bad_var = 1; \ } \ \ /* Now perform similar checks on the output variance value (if \ required). This time we check that the square of the sum of \ weights is not zero (since this might underflow before the sum of \ weights). Again we also check to prevent the result overflowing the \ output data type. */ \ if ( ( Usevar ) && !bad_var ) { \ wtsum_sq = wtsum * wtsum; \ bad_var = ( wtsum_sq == (Xfloattype) 0.0 ); \ if ( !bad_var ) { \ val_var = sum_var / wtsum_sq; \ if ( !( Xfloating ) ) { \ bad_var = ( val_var <= lo_lim ) || ( val_var >= hi_lim ); \ } \ } \ } \ \ /* Obtain the pixel offset into the output array. */ \ off_out = offset[ point ]; \ \ /* Assign a bad output value (and variance) if required and count it. */ \ if ( bad ) { \ if( !Nobad ) { \ out[ off_out ] = badval; \ if ( Usevar ) out_var[ off_out ] = badval; \ } \ result++; \ \ /* Otherwise, assign the interpolated value. If the output data type \ is floating point, the result can be stored directly, otherwise we \ must round to the nearest integer. */ \ } else { \ if ( Xfloating ) { \ out[ off_out ] = (Xtype) val; \ } else { \ out[ off_out ] = (Xtype) ( val + ( ( val >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ \ /* If a variance estimate is required but none can be obtained, then \ store a bad output variance value and count it. */ \ if ( Usevar ) { \ if ( bad_var ) { \ if( !Nobad ) { \ out_var[ off_out ] = badval; \ } \ result++; \ \ /* Otherwise, store the variance estimate, rounding to the nearest \ integer if necessary. */ \ } else { \ if ( Xfloating ) { \ out_var[ off_out ] = (Xtype) val_var; \ } else { \ out_var[ off_out ] = (Xtype) ( val_var + \ ( ( val_var >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ } \ } \ } /* These subsidiary macros define limits for range checking of results before conversion to the final data type. For each data type code , HI_ gives the least positive floating point value which just overflows that data type towards plus infinity, while LO_ gives the least negative floating point value which just overflows that data type towards minus infinity. Thus, a floating point value must satisfy LO is a floating point type, the limits are not actually used, but must be present to permit error-free compilation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define HI_LD ( 0.0L ) #define LO_LD ( 0.0L ) #endif #define HI_D ( 0.0 ) #define LO_D ( 0.0 ) #define HI_F ( 0.0f ) #define LO_F ( 0.0f ) #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define HI_K ( 0.5L + (long double) LONG_MAX ) #define LO_K ( -0.5L + (long double) LONG_MIN ) #define HI_UK ( 0.5L + (long double) ULONG_MAX ) #define LO_UK ( -0.5L ) #define HI_L ( 0.5L + (long double) LONG_MAX ) #define LO_L ( -0.5L + (long double) LONG_MIN ) #define HI_UL ( 0.5L + (long double) ULONG_MAX ) #define LO_UL ( -0.5L ) #else #define HI_K ( 0.5 + (double) LONG_MAX ) #define LO_K ( -0.5 + (double) LONG_MIN ) #define HI_UK ( 0.5 + (double) ULONG_MAX ) #define LO_UK ( -0.5 ) #define HI_L ( 0.5 + (double) LONG_MAX ) #define LO_L ( -0.5 + (double) LONG_MIN ) #define HI_UL ( 0.5 + (double) ULONG_MAX ) #define LO_UL ( -0.5 ) #endif #define HI_I ( 0.5 + (double) INT_MAX ) #define LO_I ( -0.5 + (double) INT_MIN ) #define HI_UI ( 0.5 + (double) UINT_MAX ) #define LO_UI ( -0.5 ) #define HI_S ( 0.5f + (float) SHRT_MAX ) #define LO_S ( -0.5f + (float) SHRT_MIN ) #define HI_US ( 0.5f + (float) USHRT_MAX ) #define LO_US ( -0.5f ) #define HI_B ( 0.5f + (float) SCHAR_MAX ) #define LO_B ( -0.5f + (float) SCHAR_MIN ) #define HI_UB ( 0.5f + (float) UCHAR_MAX ) #define LO_UB ( -0.5f ) /* This subsidiary macro tests for negative variance values. This check is required only for signed data types. */ #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ bad_var = bad_var || ( var < ( (Xtype) 0 ) ); /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_KERNEL1(LD,long double,1,long double,1) MAKE_INTERPOLATE_KERNEL1(L,long int,0,long double,1) MAKE_INTERPOLATE_KERNEL1(K,INT_BIG,0,long double,1) #else MAKE_INTERPOLATE_KERNEL1(L,long int,0,double,1) MAKE_INTERPOLATE_KERNEL1(K,INT_BIG,0,double,1) #endif MAKE_INTERPOLATE_KERNEL1(D,double,1,double,1) MAKE_INTERPOLATE_KERNEL1(F,float,1,float,1) MAKE_INTERPOLATE_KERNEL1(I,int,0,double,1) MAKE_INTERPOLATE_KERNEL1(S,short int,0,float,1) MAKE_INTERPOLATE_KERNEL1(B,signed char,0,float,1) /* Re-define the macro for testing for negative variances to do nothing. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) /* Expand the main macro above to generate a function for each required unsigned data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_KERNEL1(UL,unsigned long int,0,long double,0) MAKE_INTERPOLATE_KERNEL1(UK,UINT_BIG,0,long double,0) #else MAKE_INTERPOLATE_KERNEL1(UL,unsigned long int,0,double,0) MAKE_INTERPOLATE_KERNEL1(UK,UINT_BIG,0,double,0) #endif MAKE_INTERPOLATE_KERNEL1(UI,unsigned int,0,double,0) MAKE_INTERPOLATE_KERNEL1(US,unsigned short int,0,float,0) MAKE_INTERPOLATE_KERNEL1(UB,unsigned char,0,float,0) /* Undefine the macros used above. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #if HAVE_LONG_DOUBLE /* Not normally implemented */ #undef HI_LD #undef LO_LD #endif #undef HI_D #undef LO_D #undef HI_F #undef LO_F #undef HI_L #undef LO_L #undef HI_UL #undef LO_UL #undef HI_K #undef LO_K #undef HI_UK #undef LO_UK #undef HI_I #undef LO_I #undef HI_UI #undef LO_UI #undef HI_S #undef LO_S #undef HI_US #undef LO_US #undef HI_B #undef LO_B #undef HI_UB #undef LO_UB #undef CALC_AND_ASSIGN_OUTPUT #undef ASSEMBLE_INPUT_ND #undef ASSEMBLE_INPUT_2D #undef ASSEMBLE_INPUT_1D #undef MAKE_INTERPOLATE_KERNEL1 /* * Name: * InterpolateLinear * Purpose: * Resample a data grid, using the linear interpolation scheme. * Type: * Private function. * Synopsis: * #include "mapping.h" * int InterpolateLinear( int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const *in, const *in_var, * int npoint, const int *offset, * const double *const *coords, * int flags, badval, * *out, *out_var ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which resample a rectangular input * grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each output * grid point may be mapped on to a position in the input grid in * an arbitrary way. Where the positions given do not correspond * with a pixel centre in the input grid, the interpolation scheme * used is linear interpolation between the centres of the nearest * neighbouring pixels in each dimension (there are 2 nearest * neighbours in 1 dimension, 4 in 2 dimensions, 8 in 3 dimensions, * etc.). * Parameters: * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input grid, its extent along a particular * (i'th) dimension being ubnd_in[i]-lbnd_in[i]+1 (assuming "i" * is zero-based). They also define the input grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be resampled (with an element * for each pixel in the input grid). The numerical type of * these data should match the function used, as given by the * suffix on the function name. The storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly * (i.e. Fortran array storage order). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. * * If no variance estimates are required, a NULL pointer should * be given. * npoint * The number of points at which the input grid is to be * resampled. * offset * Pointer to an array of integers with "npoint" elements. For * each output point, this array should contain the zero-based * offset in the output array(s) (i.e. the "out" and, * optionally, the "out_var" arrays) at which the resampled * output value(s) should be stored. * coords * An array of pointers to double, with "ndim_in" * elements. Element "coords[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contains the values of coordinate number "coord" for each * interpolation point. The value of coordinate number "coord" * for interpolation point number "point" is therefore given by * "coords[coord][point]" (assuming both indices to be * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding output data (and * variance) will be set to the value given by "badval" (unles the * AST__NOBAD flag is specified). * flags * The bitwise OR of a set of flag values which control the * operation of the function. Currently, only the flag * AST__USEBAD is significant and indicates whether there are * "bad" (i.e. missing) data in the input array(s) which must be * recognised and propagated to the output array(s). If this * flag is not set, all input values are treated literally. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. Unles the AST__NOBAD flag is specified in "flags", the * same value will also be used to flag any output array elements * for which resampled values could not be obtained. The output * arrays(s) may be flagged with this value whether or not the * AST__USEBAD flag is set (the function return value indicates * whether any such values have been produced). * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. Note * that details of how the output grid maps on to this array * (e.g. the storage order, number of dimensions, etc.) is * arbitrary and is specified entirely by means of the "offset" * array. The "out" array should therefore contain sufficient * elements to accommodate the "offset" values supplied. There * is no requirement that all elements of the "out" array should * be assigned values, and any which are not addressed by the * contents of the "offset" array will be left unchanged. * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. It is addressed in * exactly the same way (via the "offset" array) as the "out" * array. The values returned are estimates of the statistical * variance of the corresponding values in the "out" array, on * the assumption that all errors in input grid values (in the * "in" array) are statistically independent and that their * variance estimates (in the "in_var" array) may simply be * summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * Returned Value: * The number of output grid points to which a data value (or a * variance value if relevant) equal to "badval" has been assigned * because no valid output value could be obtained. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. * - A value of zero will be returned if any of these functions is * invoked with the global error status set, or if it should fail * for any reason. */ /* Define macros to implement the function for a specific data type. */ #define MAKE_INTERPOLATE_LINEAR(X,Xtype,Xfloating,Xfloattype,Xsigned) \ static int InterpolateLinear##X( int ndim_in, \ const int *lbnd_in, const int *ubnd_in, \ const Xtype *in, const Xtype *in_var, \ int npoint, const int *offset, \ const double *const *coords, \ int flags, Xtype badval, \ Xtype *out, Xtype *out_var, int *status ) { \ \ /* Local Variables: */ \ Xfloattype sum; /* Weighted sum of pixel data values */ \ Xfloattype sum_var; /* Weighted sum of pixel variance values */ \ Xfloattype val; /* Value to be asigned to output pixel */ \ Xfloattype wtsum; /* Sum of weight values */ \ Xtype var; /* Variance value */ \ double *frac_hi; /* Pointer to array of weights */ \ double *frac_lo; /* Pointer to array of weights */ \ double *wt; /* Pointer to array of weights */ \ double *wtprod; /* Array of accumulated weights pointer */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double frac_hi_x; /* Pixel weight (x dimension) */ \ double frac_hi_y; /* Pixel weight (y dimension) */ \ double frac_lo_x; /* Pixel weight (x dimension) */ \ double frac_lo_y; /* Pixel weight (y dimension) */ \ double pixwt; /* Weight to apply to individual pixel */ \ double x; /* x coordinate value */ \ double xmax; /* x upper limit */ \ double xmin; /* x lower limit */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ double ymax; /* y upper limit */ \ double ymin; /* y lower limit */ \ int *dim; /* Pointer to array of pixel indices */ \ int *hi; /* Pointer to array of upper indices */ \ int *lo; /* Pointer to array of lower indices */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int bad_var; /* Output variance bad? */ \ int done; /* All pixel indices done? */ \ int hi_x; /* Upper pixel index (x dimension) */ \ int hi_y; /* Upper pixel index (y dimension) */ \ int idim; /* Loop counter for dimensions */ \ int ii; /* Loop counter for weights */ \ int ix; /* Pixel index in input grid x dimension */ \ int ixn; /* Pixel index (n-d) */ \ int iy; /* Pixel index in input grid y dimension */ \ int lo_x; /* Lower pixel index (x dimension) */ \ int lo_y; /* Lower pixel index (y dimension) */ \ int nobad; /* Was the AST__NOBAD flag set? */ \ int off_in; /* Offset to input pixel */ \ int off_lo; /* Offset to "first" input pixel */ \ int off_out; /* Offset to output pixel */ \ int pixel; /* Offset to input pixel containing point */ \ int point; /* Loop counter for output points */ \ int result; /* Result value to return */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int ystride; /* Stride along input grid y dimension */ \ \ /* Initialise. */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Initialise variables to avoid "used of uninitialised variable" \ messages from dumb compilers. */ \ sum = 0; \ sum_var = 0; \ wtsum = 0; \ bad = 0; \ bad_var = 0; \ \ /* Determine if we are processing bad pixels or variances. */ \ nobad = flags & AST__NOBAD; \ usebad = flags & AST__USEBAD; \ usevar = in_var && out_var; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_in == 1 ) { \ \ /* Calculate the coordinate limits of the input grid. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,0,1) \ } \ } \ } \ \ /* Four more cases as above, but this time with the AST__NOBAD flag \ un-set. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,0,0) \ } \ } \ } \ } \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_in == 2 ) { \ \ /* Calculate the stride along the y dimension of the input grid. */ \ ystride = ubnd_in[ 0 ] - lbnd_in[ 0 ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ ymin = (double) lbnd_in[ 1 ] - 0.5; \ ymax = (double) ubnd_in[ 1 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,0,1) \ } \ } \ } \ \ /* Four more case as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ 0,0,0) \ } \ } \ } \ } \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ dim = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ frac_hi = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ frac_lo = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ hi = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ lo = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ wt = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ wtprod = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the input grid. */ \ for ( s = 1, idim = 0; idim < ndim_in; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_in[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_in[ idim ] + 0.5; \ } \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,0,0,1) \ } \ } \ } \ \ /* Four more case as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype, \ Xsigned,0,0,0) \ } \ } \ } \ } \ } \ \ /* Free the workspace. */ \ dim = astFree( dim ); \ frac_hi = astFree( frac_hi ); \ frac_lo = astFree( frac_lo ); \ hi = astFree( hi ); \ lo = astFree( lo ); \ stride = astFree( stride ); \ wt = astFree( wt ); \ wtprod = astFree( wtprod ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ } \ \ /* If an error has occurred, clear the returned result. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 1-dimensional case. */ #define ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid. Also test if it is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If input bad pixels must be detected, then obtain the offset along \ the input grid x dimension of the input pixel which contains the \ current coordinate and calculate this pixel's offset from the start \ of the input array. */ \ if ( Usebad ) { \ pixel = (int) floor( x + 0.5 ) - lbnd_in[ 0 ]; \ \ /* Test if the pixel is bad. */ \ bad = ( in[ pixel ] == badval ); \ } \ \ /* If OK, obtain the indices along the input grid x dimension of the \ two adjacent pixels which will contribute to the interpolated \ result. Also obtain the fractional weight to be applied to each of \ these pixels. */ \ if ( !bad ) { \ lo_x = (int) floor( x ); \ hi_x = lo_x + 1; \ frac_lo_x = (double) hi_x - x; \ frac_hi_x = 1.0 - frac_lo_x; \ \ /* Obtain the offset within the input array of the first pixel to be \ used for interpolation (the one with the smaller index). */ \ off_lo = lo_x - lbnd_in[ 0 ]; \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ if ( ( Xsigned ) || ( Usebad ) ) bad_var = 0; \ } \ \ /* For each of the two pixels which may contribute to the result, \ test if the pixel index lies within the input grid. Where it does, \ accumulate the sums required for forming the interpolated \ result. In each case, we supply the pixel's offset within the input \ array and the weight to be applied to it. */ \ if ( lo_x >= lbnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo,frac_lo_x,Xtype, \ Xfloattype,Xsigned,Usebad,Usevar) \ } \ if ( hi_x <= ubnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo + 1,frac_hi_x,Xtype, \ Xfloattype,Xsigned,Usebad,Usevar) \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 2-dimensional case. */ #define ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid. Also test if it is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If OK, then similarly obtain and test the y coordinate. */ \ y = coords[ 1 ][ point ]; \ bad = ( y < ymin ) || ( y >= ymax ) || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* If input bad pixels must be detected, then obtain the offsets along \ each input grid dimension of the input pixel which contains the \ current coordinates. */ \ if ( Usebad ) { \ ix = (int) floor( x + 0.5 ); \ iy = (int) floor( y + 0.5 ); \ \ /* Calculate this pixel's offset from the start of the input array. */ \ pixel = ix - lbnd_in[ 0 ] + ystride * ( iy - lbnd_in[ 1 ] ); \ \ /* Test if the pixel is bad. */ \ bad = ( in[ pixel ] == badval ); \ } \ \ /* If OK, obtain the indices along the input grid x dimension of the \ two adjacent pixels which will contribute to the interpolated \ result. Also obtain the fractional weight to be applied to each of \ these pixels. */ \ if ( !bad ) { \ lo_x = (int) floor( x ); \ hi_x = lo_x + 1; \ frac_lo_x = (double) hi_x - x; \ frac_hi_x = 1.0 - frac_lo_x; \ \ /* Repeat this process for the y dimension. */ \ lo_y = (int) floor( y ); \ hi_y = lo_y + 1; \ frac_lo_y = (double) hi_y - y; \ frac_hi_y = 1.0 - frac_lo_y; \ \ /* Obtain the offset within the input array of the first pixel to be \ used for interpolation (the one with the smaller index along both \ dimensions). */ \ off_lo = lo_x - lbnd_in[ 0 ] + ystride * ( lo_y - lbnd_in[ 1 ] ); \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ if ( ( Xsigned ) || ( Usebad ) ) bad_var = 0; \ } \ \ /* For each of the four pixels which may contribute to the result, \ test if the pixel indices lie within the input grid. Where they do, \ accumulate the sums required for forming the interpolated \ result. In each case, we supply the pixel's offset within the input \ array and the weight to be applied to it. */ \ if ( lo_y >= lbnd_in[ 1 ] ) { \ if ( lo_x >= lbnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo, \ frac_lo_x * frac_lo_y,Xtype, \ Xfloattype, Xsigned, \ Usebad,Usevar) \ } \ if ( hi_x <= ubnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo + 1, \ frac_hi_x * frac_lo_y,Xtype, \ Xfloattype,Xsigned, \ Usebad,Usevar) \ } \ } \ if ( hi_y <= ubnd_in[ 1 ] ) { \ if ( lo_x >= lbnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo + ystride, \ frac_lo_x * frac_hi_y,Xtype, \ Xfloattype,Xsigned, \ Usebad,Usevar) \ } \ if ( hi_x <= ubnd_in[ 0 ] ) { \ FORM_LINEAR_INTERPOLATION_SUM(off_lo + ystride + 1, \ frac_hi_x * frac_hi_y,Xtype, \ Xfloattype,Xsigned, \ Usebad,Usevar) \ } \ } \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the n-dimensional case. */ #define ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Initialise offsets into the input array. Then loop to obtain each coordinate associated with the current output point. */ \ off_in = 0; \ if ( Usebad ) pixel = 0; \ for ( idim = 0; idim < ndim_in; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate lies outside the input grid. Also test if \ it is bad. If either is true, the corresponding output pixel value \ will be bad, so give up on this point. */ \ bad = ( xn < xn_min[ idim ] ) || ( xn >= xn_max[ idim ] ) || \ ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* If input bad pixels must be detected, obtain the index along the \ current input grid dimension of the pixel which contains this \ coordinate and accumulate the pixel's offset from the start of the \ input array. */ \ if ( Usebad ) { \ pixel += stride[ idim ] * \ ( (int) floor( xn + 0.5 ) - lbnd_in[ idim ] ); \ } \ \ /* Obtain the indices along the current dimension of the input grid of \ the two (usually adjacent) pixels which will contribute to the \ output value. If necessary, however, restrict each index to ensure \ it does not lie outside the input grid. Also calculate the \ fractional weight to be given to each pixel in order to interpolate \ linearly between them. */ \ ixn = (int) floor( xn ); \ lo[ idim ] = MaxI( ixn, lbnd_in[ idim ], status ); \ hi[ idim ] = MinI( ixn + 1, ubnd_in[ idim ], status ); \ frac_lo[ idim ] = 1.0 - fabs( xn - (double) lo[ idim ] ); \ frac_hi[ idim ] = 1.0 - fabs( xn - (double) hi[ idim ] ); \ \ /* Store the lower index involved in interpolation along each \ dimension and accumulate the offset from the start of the input \ array of the pixel which has these indices. */ \ dim[ idim ] = lo[ idim ]; \ off_in += stride[ idim ] * ( lo[ idim ] - lbnd_in[ idim ] ); \ \ /* Also store the fractional weight associated with the lower pixel \ along each dimension. */ \ wt[ idim ] = frac_lo[ idim ]; \ } \ \ /* If the input pixel which contains the required coordinates has \ been identified, test if it is bad. */ \ if ( Usebad ) bad = bad || ( in[ pixel ] == badval ); \ \ /* If OK, initialise and loop over adjacent input pixels to obtain an \ interpolated value. */ \ if ( !bad ) { \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ if ( ( Xsigned ) || ( Usebad ) ) bad_var = 0; \ } \ idim = ndim_in - 1; \ wtprod[ idim ] = 1.0; \ done = 0; \ do { \ \ /* Each contributing pixel is weighted by the product of the weights \ which account for the displacement of its centre from the required \ position along each dimension. However, since we typically only \ change the index of one dimension at a time, we can avoid forming \ this product repeatedly by retaining an array of accumulated weight \ products for all higher dimensions. We need then only update the \ lower elements in this array, corresponding to those dimensions \ whose index has changed. We do this here, "idim" being the index of \ the most significant dimension to have changed. Note that on the \ first pass, all dimensions are considered changed, causing this \ array to be initialised. */ \ for ( ii = idim; ii >= 1; ii-- ) { \ wtprod[ ii - 1 ] = wtprod[ ii ] * wt[ ii ]; \ } \ \ /* Accumulate the sums required for forming the interpolated \ result. We supply the pixel's offset within the input array and the \ weight to be applied to it. The pixel weight is formed by including \ the weight factor for dimension zero, since this is not included in \ the "wtprod" array. */ \ FORM_LINEAR_INTERPOLATION_SUM(off_in,wtprod[ 0 ] * wt[ 0 ], \ Xtype,Xfloattype,Xsigned, \ Usebad,Usevar) \ \ /* Now update the indices, offset and weight factors to refer to the \ next input pixel to be considered. */ \ idim = 0; \ do { \ \ /* The first input dimension which still refers to the pixel with the \ lower of the two possible indices is switched to refer to the other \ pixel (with the higher index). The offset into the input array and \ the fractional weight factor for this dimension are also updated \ accordingly. */ \ if ( dim[ idim ] != hi[ idim ] ) { \ dim[ idim ] = hi[ idim ]; \ off_in += stride[ idim ]; \ wt[ idim ] = frac_hi[ idim ]; \ break; \ \ /* Any earlier dimensions (referring to the higher index) are switched \ back to the lower index, if not already there, before going on to \ consider the next dimension. (This process is the same as \ incrementing a binary number and propagating overflows up through \ successive digits, except that dimensions where the "lo" and "hi" \ values are the same can only take one value.) The process stops at \ the first attempt to return the final dimension to the lower \ index. */ \ } else { \ if ( dim[ idim ] != lo[ idim ] ) { \ dim[ idim ] = lo[ idim ]; \ off_in -= stride[ idim ]; \ wt[ idim ] = frac_lo[ idim ]; \ } \ done = ( ++idim == ndim_in ); \ } \ } while ( !done ); \ } while ( !done ); \ } /* This subsidiary macro adds the contribution from a specified input pixel to the accumulated sums for forming the linearly interpolated value. */ #define FORM_LINEAR_INTERPOLATION_SUM(off,wt,Xtype,Xfloattype,Xsigned, \ Usebad,Usevar) \ \ /* Obtain the offset of the input pixel to use. */ \ off_in = ( off ); \ \ /* If necessary, test if this pixel is bad. If not, then obtain the \ weight to apply to it. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ pixwt = ( wt ); \ \ /* Increment the weighted sum of pixel values and the sum of weights. */ \ sum += ( (Xfloattype) in[ off_in ] ) * ( (Xfloattype) pixwt ); \ wtsum += (Xfloattype) pixwt; \ \ /* If an output variance estimate is to be generated, and it still \ seems possible to produce one, then obtain the input variance \ value. */ \ if ( Usevar ) { \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ var = in_var[ off_in ]; \ \ /* Test if the variance value is bad (if the data type is signed, also \ check that it is not negative). */ \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If OK, increment the weighted sum of variance values. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ sum_var += ( (Xfloattype) ( pixwt * pixwt ) ) * \ ( (Xfloattype) var ); \ } \ } \ } \ } /* This subsidiary macro calculates the interpolated output value (and variance) from the sums over contributing pixels and assigns them to the output array(s). */ #define CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Xsigned, \ Usebad,Usevar,Nobad) \ \ /* Obtain the pixel offset into the output array. */ \ off_out = offset[ point ]; \ \ /* Assign a bad output value (and variance) if required and count it. */ \ if ( bad ) { \ if( !Nobad ) { \ out[ off_out ] = badval; \ if ( Usevar ) out_var[ off_out ] = badval; \ } \ result++; \ \ /* Otherwise, calculate the interpolated value. If the output data \ type is floating point, this result can be stored directly, \ otherwise we must round to the nearest integer. */ \ } else { \ val = sum / wtsum; \ if ( Xfloating ) { \ out[ off_out ] = (Xtype) val; \ } else { \ out[ off_out ] = (Xtype) ( val + ( ( val >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ \ /* If a variance estimate is required but none can be obtained, then \ store a bad output variance value and count it. */ \ if ( Usevar ) { \ if ( ( ( Xsigned ) || ( Usebad ) ) && bad_var ) { \ if( !Nobad ) out_var[ off_out ] = badval; \ result++; \ \ /* Otherwise, calculate the variance estimate and store it, rounding \ to the nearest integer if necessary. */ \ } else { \ val = sum_var / ( wtsum * wtsum ); \ if ( Xfloating ) { \ out_var[ off_out ] = (Xtype) val; \ } else { \ out_var[ off_out ] = (Xtype) ( val + \ ( ( val >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ } \ } \ } /* This subsidiary macro tests for negative variance values in the macros above. This check is required only for signed data types. */ #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ bad_var = bad_var || ( var < ( (Xtype) 0 ) ); /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_LINEAR(LD,long double,1,long double,1) MAKE_INTERPOLATE_LINEAR(L,long int,0,long double,1) MAKE_INTERPOLATE_LINEAR(K,INT_BIG,0,long double,1) #else MAKE_INTERPOLATE_LINEAR(L,long int,0,double,1) MAKE_INTERPOLATE_LINEAR(K,INT_BIG,0,double,1) #endif MAKE_INTERPOLATE_LINEAR(D,double,1,double,1) MAKE_INTERPOLATE_LINEAR(F,float,1,float,1) MAKE_INTERPOLATE_LINEAR(I,int,0,double,1) MAKE_INTERPOLATE_LINEAR(S,short int,0,float,1) MAKE_INTERPOLATE_LINEAR(B,signed char,0,float,1) /* Re-define the macro for testing for negative variances to do nothing. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) /* Expand the main macro above to generate a function for each required unsigned data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_LINEAR(UL,unsigned long int,0,long double,0) MAKE_INTERPOLATE_LINEAR(UK,UINT_BIG,0,long double,0) #else MAKE_INTERPOLATE_LINEAR(UL,unsigned long int,0,double,0) MAKE_INTERPOLATE_LINEAR(UK,UINT_BIG,0,double,0) #endif MAKE_INTERPOLATE_LINEAR(UI,unsigned int,0,double,0) MAKE_INTERPOLATE_LINEAR(US,unsigned short int,0,float,0) MAKE_INTERPOLATE_LINEAR(UB,unsigned char,0,float,0) /* Undefine the macros uxsed above. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #undef CALC_AND_ASSIGN_OUTPUT #undef FORM_LINEAR_INTERPOLATION_SUM #undef ASSEMBLE_INPUT_ND #undef ASSEMBLE_INPUT_2D #undef ASSEMBLE_INPUT_1D #undef MAKE_INTERPOLATE_LINEAR /* * Name: * InterpolateNearest * Purpose: * Resample a data grid, using the nearest-pixel interpolation scheme. * Type: * Private function. * Synopsis: * #include "mapping.h" * int InterpolateNearest( int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const *in, const *in_var, * int npoint, const int *offset, * const double *const *coords, * int flags, badval, * *out, *out_var ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which resample a rectangular input * grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each output * grid point may be mapped on to a position in the input grid in * an arbitrary way. Where the positions given do not correspond * with a pixel centre in the input grid, the interpolation scheme * used is simply to select the nearest pixel (i.e. the one whose * bounds contain the supplied position). * Parameters: * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input grid, its extent along a particular * (i'th) dimension being ubnd_in[i]-lbnd_in[i]+1 (assuming "i" * is zero-based). They also define the input grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be resampled (with an element * for each pixel in the input grid). The numerical type of * these data should match the function used, as given by the * suffix on the function name. The storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly * (i.e. Fortran array storage order). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. * * If no variance estimates are required, a NULL pointer should * be given. * npoint * The number of points at which the input grid is to be * resampled. * offset * Pointer to an array of integers with "npoint" elements. For * each output point, this array should contain the zero-based * offset in the output array(s) (i.e. the "out" and, * optionally, the "out_var" arrays) at which the resampled * output value(s) should be stored. * coords * An array of pointers to double, with "ndim_in" * elements. Element "coords[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contains the values of coordinate number "coord" for each * interpolation point. The value of coordinate number "coord" * for interpolation point number "point" is therefore given by * "coords[coord][point]" (assuming both indices to be * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding output data (and * variance) will be set to the value given by "badval" (unles the * AST__NOBAD flag is specified). * flags * The bitwise OR of a set of flag values which control the * operation of the function. Currently, only the flag * AST__USEBAD is significant and indicates whether there are * "bad" (i.e. missing) data in the input array(s) which must be * recognised and propagated to the output array(s). If this * flag is not set, all input values are treated literally. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. Unles the AST__NOBAD flag is specified in "flags", the * same value will also be used to flag any output array elements * for which resampled values could not be obtained. The output * arrays(s) may be flagged with this value whether or not the * AST__USEBAD flag is set (the function return value indicates * whether any such values have been produced). * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. Note * that details of how the output grid maps on to this array * (e.g. the storage order, number of dimensions, etc.) is * arbitrary and is specified entirely by means of the "offset" * array. The "out" array should therefore contain sufficient * elements to accommodate the "offset" values supplied. There * is no requirement that all elements of the "out" array should * be assigned values, and any which are not addressed by the * contents of the "offset" array will be left unchanged. * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. It is addressed in * exactly the same way (via the "offset" array) as the "out" * array. The values returned are estimates of the statistical * variance of the corresponding values in the "out" array, on * the assumption that all errors in input grid values (in the * "in" array) are statistically independent and that their * variance estimates (in the "in_var" array) may simply be * summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * Returned Value: * The number of output grid points to which a data value (or a * variance value if relevant) equal to "badval" has been assigned * because no valid output value could be obtained. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. * - A value of zero will be returned if any of these functions is * invoked with the global error status set, or if it should fail * for any reason. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_INTERPOLATE_NEAREST(X,Xtype,Xsigned) \ static int InterpolateNearest##X( int ndim_in, \ const int *lbnd_in, const int *ubnd_in, \ const Xtype *in, const Xtype *in_var, \ int npoint, const int *offset, \ const double *const *coords, \ int flags, Xtype badval, \ Xtype *out, Xtype *out_var, int *status ) { \ \ /* Local Variables: */ \ Xtype var; /* Variance value */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double x; /* x coordinate value */ \ double xmax; /* x upper limit */ \ double xmin; /* x lower limit */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ double ymax; /* y upper limit */ \ double ymin; /* y lower limit */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int idim; /* Loop counter for dimensions */ \ int ix; /* Number of pixels offset in x direction */ \ int ixn; /* Number of pixels offset (n-d) */ \ int iy; /* Number of pixels offset in y direction */ \ int nobad; /* Was the AST__NOBAD flag set? */ \ int off_in; /* Pixel offset into input array */ \ int off_out; /* Pixel offset into output array */ \ int point; /* Loop counter for output points */ \ int result; /* Returned result value */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int ystride; /* Stride along input grid y direction */ \ \ /* Initialise. */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Initialise variables to avoid "used of uninitialised variable" \ messages from dumb compilers. */ \ bad = 0; \ off_in = 0; \ \ /* Determine if we are processing bad pixels or variances. */ \ nobad = flags & AST__NOBAD; \ usebad = flags & AST__USEBAD; \ usevar = in_var && out_var; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_in == 1 ) { \ \ /* Calculate the coordinate limits of the input array. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,1) \ } \ } \ } \ \ /* Four more cases as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,0) \ } \ } \ } \ } \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_in == 2 ) { \ \ /* Calculate the stride along the y dimension of the input grid. */ \ ystride = ubnd_in[ 0 ] - lbnd_in[ 0 ] + 1; \ \ /* Calculate the coordinate limits of the input array in each \ dimension. */ \ xmin = (double) lbnd_in[ 0 ] - 0.5; \ xmax = (double) ubnd_in[ 0 ] + 0.5; \ ymin = (double) lbnd_in[ 1 ] - 0.5; \ ymax = (double) ubnd_in[ 1 ] + 0.5; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,1) \ } \ } \ } \ \ /* Four more cases as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,0) \ } \ } \ } \ } \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the input grid. */ \ for ( s = 1, idim = 0; idim < ndim_in; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_in[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_in[ idim ] + 0.5; \ } \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,1) \ } \ } \ } \ \ /* Another 4 cases as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,0,0,0) \ } \ } \ } \ } \ } \ \ /* Free the workspace. */ \ stride = astFree( stride ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ } \ \ /* If an error has occurred, clear the returned result. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 1-dimensional case. */ #define ASSEMBLE_INPUT_1D(X,Xtype,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid, or is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If not, then obtain the offset within the input grid of the pixel \ which contains the current point. */ \ off_in = (int) floor( x + 0.5 ) - lbnd_in[ 0 ]; \ \ /* If necessary, test if the input pixel is bad. */ \ if ( Usebad ) bad = ( in[ off_in ] == badval ); \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 2-dimensional case. */ #define ASSEMBLE_INPUT_2D(X,Xtype,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the input grid, or is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If not, then similarly obtain and test the y coordinate. */ \ y = coords[ 1 ][ point ]; \ bad = ( y < ymin ) || ( y >= ymax ) || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* Obtain the offsets along each input grid dimension of the input \ pixel which contains the current point. */ \ ix = (int) floor( x + 0.5 ) - lbnd_in[ 0 ]; \ iy = (int) floor( y + 0.5 ) - lbnd_in[ 1 ]; \ \ /* Calculate this pixel's offset from the start of the input array. */ \ off_in = ix + ystride * iy; \ \ /* If necessary, test if the input pixel is bad. */ \ if ( Usebad ) bad = ( in[ off_in ] == badval ); \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the n-dimensional case. */ #define ASSEMBLE_INPUT_ND(X,Xtype,Usebad,Usevar) \ \ /* Initialise the offset into the input array. Then loop to obtain \ each coordinate associated with the current output point. */ \ off_in = 0; \ for ( idim = 0; idim < ndim_in; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate lies outside the input grid, or is bad. If \ either is true, the corresponding output pixel value will be bad, \ so give up on this point. */ \ bad = ( xn < xn_min[ idim ] ) || ( xn >= xn_max[ idim ] ) || \ ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* Obtain the offset along the current input grid dimension of the \ input pixel which contains the current point. */ \ ixn = (int) floor( xn + 0.5 ) - lbnd_in[ idim ]; \ \ /* Accumulate this pixel's offset from the start of the input \ array. */ \ off_in += ixn * stride[ idim ]; \ } \ \ /* Once the required input pixel has been located, test if it is \ bad, if necessary. */ \ if ( Usebad ) bad = bad || ( in[ off_in ] == badval ); /* This subsidiary macro assigns the output value (and variance) to the output array(s). */ #define CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xsigned,Usebad,Usevar,Nobad) \ \ /* Obtain the pixel offset into the output array. */ \ off_out = offset[ point ]; \ \ /* If the input data value is bad, assign a bad output value (and \ variance, if required) and count it. */ \ if ( bad ) { \ if( !Nobad ) { \ out[ off_out ] = badval; \ if ( Usevar ) out_var[ off_out ] = badval; \ } \ result++; \ \ /* Otherwise, assign the value obtained from the input grid. */ \ } else { \ out[ off_out ] = in[ off_in ]; \ \ /* If required, obtain the associated variance value. If necessary, \ test if it is bad (if the data type is signed, also check that it \ is not negative). */ \ if ( Usevar ) { \ var = in_var[ off_in ]; \ if ( Usebad ) bad = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If the variance value can be bad, and is, then store a bad value in \ the output array and count it. Otherwise, store the variance \ value. */ \ if ( ( ( Xsigned ) || ( Usebad ) ) && bad ) { \ if( !Nobad ) out_var[ off_out ] = badval; \ result++; \ } else { \ out_var[ off_out ] = var; \ } \ } \ } /* This subsidiary macro tests for negative variance values in the macros above. This check is required only for signed data types. */ #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ bad = bad || ( var < ( (Xtype) 0 ) ); /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_NEAREST(LD,long double,1) #endif MAKE_INTERPOLATE_NEAREST(D,double,1) MAKE_INTERPOLATE_NEAREST(F,float,1) MAKE_INTERPOLATE_NEAREST(L,long int,1) MAKE_INTERPOLATE_NEAREST(K,INT_BIG,1) MAKE_INTERPOLATE_NEAREST(I,int,1) MAKE_INTERPOLATE_NEAREST(S,short int,1) MAKE_INTERPOLATE_NEAREST(B,signed char,1) /* Re-define the macro for testing for negative variances to do nothing. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) /* Expand the main macro above to generate a function for each required unsigned data type. */ MAKE_INTERPOLATE_NEAREST(UK,UINT_BIG,0) MAKE_INTERPOLATE_NEAREST(UL,unsigned long int,0) MAKE_INTERPOLATE_NEAREST(UI,unsigned int,0) MAKE_INTERPOLATE_NEAREST(US,unsigned short int,0) MAKE_INTERPOLATE_NEAREST(UB,unsigned char,0) /* Undefine the macros used above. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #undef CALC_AND_ASSIGN_OUTPUT #undef ASSEMBLE_INPUT_ND #undef ASSEMBLE_INPUT_2D #undef ASSEMBLE_INPUT_1D #undef MAKE_INTERPOLATE_NEAREST /* * Name: * InterpolateBlockAverage * Purpose: * Resample a data grid, using multidimensional block averaging. * Type: * Private function. * Synopsis: * #include "mapping.h" * void InterpolateBlockAverage( int ndim_in, * const int lbnd_in[], * const int ubnd_in[], * const in[], * const in_var[], * int npoint, const int offset[], * const double *const coords[], * const double params[], int flags, * badval, *out, * *out_var, int *nbad ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which resample a rectangular input * grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. To generate * an output grid pixel, a block average is taken over an ndim- * dimensional hypercube of pixels in the input grid. If variances * are being used then the input pixels will be weighted according * to the reciprocals of the corresponding variance values, and * input pixels without a valid variance will be ignored; * otherwise an unweighted average will be taken over * all non-bad pixels in the cube. The size of the cube over which * the average is taken is determined by the first element of the * params array. * * This "interpolation" scheme is appropriate where an input grid * is to be resampled onto a much coarser output grid. * Parameters: * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input grid, its extent along a particular * (i'th) dimension being ubnd_in[i]-lbnd_in[i]+1 (assuming "i" * is zero-based). They also define the input grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be resampled (with an element * for each pixel in the input grid). The numerical type of * these data should match the function used, as given by the * suffix on the function name. The storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly * (i.e. Fortran array storage order). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. * * If no variance estimates are required, a NULL pointer should * be given. * npoint * The number of points at which the input grid is to be * resampled. * offset * Pointer to an array of integers with "npoint" elements. For * each output point, this array should contain the zero-based * offset in the output array(s) (i.e. the "out" and, * optionally, the "out_var" arrays) at which the resampled * output value(s) should be stored. * coords * An array of pointers to double, with "ndim_in" * elements. Element "coords[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contains the values of coordinate number "coord" for each * interpolation point. The value of coordinate number "coord" * for interpolation point number "point" is therefore given by * "coords[coord][point]" (assuming both indices to be * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding output data (and * variance) will be set to the value given by "badval" (unles the * AST__NOBAD flag is specified). * params * A pointer to an array of doubles giving further information * about how the resampling is to proceed. Only the first * element is significant; the nearest integer to this gives * the number of pixels on either side of the central input * grid pixel to use in each dimension. Therefore * (1 + 2*params[0])**ndim_in pixels will be averaged over to * generate each output pixel. * flags * The bitwise OR of a set of flag values which control the * operation of the function. Currently, only the flag * AST__USEBAD is significant and indicates whether there are * "bad" (i.e. missing) data in the input array(s) which must be * recognised and propagated to the output array(s). If this * flag is not set, all input values are treated literally. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. Unles the AST__NOBAD flag is specified in "flags", the * same value will also be used to flag any output array elements * for which resampled values could not be obtained. The output * arrays(s) may be flagged with this value whether or not the * AST__USEBAD flag is set (the function return value indicates * whether any such values have been produced). * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. Note * that details of how the output grid maps on to this array * (e.g. the storage order, number of dimensions, etc.) is * arbitrary and is specified entirely by means of the "offset" * array. The "out" array should therefore contain sufficient * elements to accommodate the "offset" values supplied. There * is no requirement that all elements of the "out" array should * be assigned values, and any which are not addressed by the * contents of the "offset" array will be left unchanged. * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. It is addressed in * exactly the same way (via the "offset" array) as the "out" * array. The values returned are estimates of the statistical * variance of the corresponding values in the "out" array, on * the assumption that all errors in input grid values (in the * "in" array) are statistically independent and that their * variance estimates (in the "in_var" array) may simply be * summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * nbad * Pointer to an int in which to return the number of * interpolation points at which an output data value (and/or a * variance value if relevant) equal to "badval" has been * assigned because no valid interpolated value could be * obtained. The maximum value that will be returned is * "npoint" and the minimum is zero (indicating that all output * values were successfully obtained). * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_INTERPOLATE_BLOCKAVE(X,Xtype,Xfloating,Xfloattype,Xsigned) \ static void InterpolateBlockAverage##X( int ndim_in, \ const int lbnd_in[], \ const int ubnd_in[], \ const Xtype in[], \ const Xtype in_var[], \ int npoint, const int offset[], \ const double *const coords[], \ const double params[], int flags, \ Xtype badval, Xtype *out, \ Xtype *out_var, int *nbad ) { \ \ /* Local Variables: */ \ Xfloattype hi_lim; /* Upper limit on output values */ \ Xfloattype lo_lim; /* Lower limit on output values */ \ Xfloattype pixwt; /* Weight to apply to individual pixel */ \ Xfloattype sum; /* Weighted sum of pixel data values */ \ Xfloattype sum_var; /* Weighted sum of pixel variance values */ \ Xfloattype val; /* Data value to be assigned to output */ \ Xfloattype val_var; /* Variance to be assigned to output */ \ Xfloattype wtsum; /* Sum of weight values */ \ Xfloattype wtsum_sq; /* Square of sum of weights */ \ Xtype var; /* Variance value */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double x; /* x coordinate value */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ int *hi; /* Pointer to array of upper indices */ \ int *ixm; /* Pointer to array of current indices */ \ int *lo; /* Pointer to array of lower indices */ \ int *status; /* Pointer to inherited status value */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int bad_var; /* Output variance bad? */ \ int done; /* All pixel indices done? */ \ int hi_x; /* Upper pixel index (x dimension) */ \ int hi_y; /* Upper pixel index (y dimension) */ \ int idim; /* Loop counter for dimensions */ \ int ix; /* Pixel index in input grid x dimension */ \ int ixn; /* Pixel index in input grid (n-d) */ \ int iy; /* Pixel index in input grid y dimension */ \ int lo_x; /* Lower pixel index (x dimension) */ \ int lo_y; /* Lower pixel index (y dimension) */ \ int neighb; /* Number of adjacent pixels on each side */ \ int nobad; /* Was the AST__NOBAD flag set? */ \ int off1; /* Input pixel offset due to y index */ \ int off_in; /* Offset to input pixel */ \ int off_out; /* Offset to output pixel */ \ int point; /* Loop counter for output points */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int ystride; /* Stride along input grid y dimension */ \ \ /* Initialise. */ \ *nbad = 0; \ \ /* Get a pointer to the inherited status argument. */ \ status = astGetStatusPtr; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Initialise variables to avoid "used of uninitialised variable" \ messages from dumb compilers. */ \ val = 0; \ val_var = 0; \ sum_var = 0; \ wtsum = 0; \ bad = 0; \ bad_var = 0; \ \ /* Determine if we are processing bad pixels or variances. */ \ nobad = flags & AST__NOBAD; \ usebad = flags & AST__USEBAD; \ usevar = in_var && out_var; \ \ /* Set the number of pixels each side of central pixel to use. */ \ neighb = (int) floor( params[ 0 ] + 0.5 ); \ \ /* Set up limits for checking output values to ensure that they do not \ overflow the range of the data type being used. */ \ lo_lim = LO_##X; \ hi_lim = HI_##X; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_in == 1 ) { \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Another 4 cases as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_in == 2 ) { \ \ /* Calculate the stride along the y dimension of the input grid. */ \ ystride = ubnd_in[ 0 ] - lbnd_in[ 0 ] + 1; \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Another 4 cases as above, but without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ hi = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ lo = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ ixm = astMalloc( sizeof( int ) * (size_t) ndim_in ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_in ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the input grid. */ \ for ( s = 1, idim = 0; idim < ndim_in; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ \ /* Calculate the coordinate limits of the input grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_in[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_in[ idim ] + 0.5; \ } \ \ /* Identify four cases, according to whether bad pixels and/or \ variances are being processed. In each case, loop through all the \ output points to (a) assemble the input data needed to form the \ interpolated value, and (b) calculate the result and assign it to \ the output arrays(s). In each case we assign constant values (0 or \ 1) to the "Usebad" and "Usevar" flags so that code for handling bad \ pixels and variances can be eliminated when not required. */ \ if ( nobad ) { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,1) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,1) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,1) \ } \ } \ } \ \ /* Another 4 cases as above, but this time without the AST__NOBAD flag. */ \ } else { \ if ( usebad ) { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,1,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,1,0,0) \ } \ } \ } else { \ if ( usevar ) { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,1) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,1,0) \ } \ } else { \ for ( point = 0; point < npoint; point++ ) { \ ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,0,0) \ CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,0,0,0) \ } \ } \ } \ } \ } \ \ /* Free the workspace. */ \ hi = astFree( hi ); \ lo = astFree( lo ); \ stride = astFree( stride ); \ ixm = astFree( ixm ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ } \ \ /* If an error has occurred, clear the returned result. */ \ if ( !astOK ) *nbad = 0; \ \ /* Return. */ \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 1-dimensional case. */ #define ASSEMBLE_INPUT_1D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x == AST__BAD ); \ \ /* Note we do not need to check here whether the pixel in this position is \ bad; if any pixels in the cube are good we can form an average. */ \ \ /* If OK, calculate the lowest and highest indices (in the x \ dimension) of the region of neighbouring pixels that will \ contribute to the interpolated result. Constrain these values to \ lie within the input grid. */ \ if ( !bad ) { \ ix = (int) floor( x ); \ lo_x = MaxI( ix - neighb + 1, lbnd_in[ 0 ], status ); \ hi_x = MinI( ix + neighb, ubnd_in[ 0 ], status ); \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ \ /* Loop to inspect all the contributing pixels, calculating the offset \ of each pixel from the start of the input array. */ \ off_in = lo_x - lbnd_in[ 0 ]; \ for ( ix = lo_x; ix <= hi_x; ix++, off_in++ ) { \ \ /* If necessary, test if the input pixel is bad. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ \ /* If we are using variances, then check that the variance is valid; \ if it is invalid then ignore this pixel altogether. */ \ if ( Usevar ) { \ var = in_var[ off_in ]; \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If variance is valid then accumulate suitably weighted values into \ the totals. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ pixwt = (Xfloattype) 1.0 / var; \ sum += pixwt * ( (Xfloattype) in[ off_in ] ); \ wtsum += pixwt; \ sum_var += pixwt; \ } \ \ /* If we are not using variances, then accumulate values into the \ totals with a weighting of unity. */ \ } else { \ sum += (Xfloattype) in[ off_in ]; \ wtsum++; \ } \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the 2-dimensional case. */ #define ASSEMBLE_INPUT_2D(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Obtain the x coordinate of the current point and test if it is bad. */ \ x = coords[ 0 ][ point ]; \ bad = ( x == AST__BAD ); \ if ( !bad ) { \ \ /* If not, then similarly obtain and test the y coordinate. */ \ y = coords[ 1 ][ point ]; \ bad = ( y == AST__BAD ); \ \ /* Note we do not need to check here whether the pixel in this position is \ bad; if any pixels in the cube are good we can form an average. */ \ \ /* If OK, calculate the lowest and highest indices (in each dimension) \ of the region of neighbouring pixels that will contribute to the \ interpolated result. Constrain these values to lie within the input \ grid. */ \ if ( !bad ) { \ ix = (int) floor( x ); \ lo_x = MaxI( ix - neighb + 1, lbnd_in[ 0 ], status ); \ hi_x = MinI( ix + neighb, ubnd_in[ 0 ], status ); \ iy = (int) floor( y ); \ lo_y = MaxI( iy - neighb + 1, lbnd_in[ 1 ], status ); \ hi_y = MinI( iy + neighb, ubnd_in[ 1 ], status ); \ \ /* Initialise sums for forming the interpolated result. */ \ sum = (Xfloattype) 0.0; \ wtsum = (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ \ /* Loop to inspect all the contributing pixels, calculating the offset \ of each pixel from the start of the input array. */ \ off1 = lo_x - lbnd_in[ 0 ] + ystride * ( lo_y - lbnd_in[ 1 ] ); \ for ( iy = lo_y; iy <= hi_y; iy++, off1 += ystride ) { \ off_in = off1; \ for ( ix = lo_x; ix <= hi_x; ix++, off_in++ ) { \ \ /* If necessary, test if the input pixel is bad. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ \ /* If we are using variances, then check that the variance is valid; \ if it is invalid then ignore this pixel altogether. */ \ if ( Usevar ) { \ var = in_var[ off_in ]; \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If variance is valid then accumulate suitably weighted values into \ the totals. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ pixwt = (Xfloattype) 1.0 / var; \ sum += pixwt * ( (Xfloattype) in[ off_in ] ); \ wtsum += pixwt; \ sum_var += pixwt; \ } \ \ /* If we are not using variances, then accumulate values into the \ totals with a weighting of unity. */ \ } else { \ sum += (Xfloattype) in[ off_in ]; \ wtsum++; \ } \ } \ } \ } \ } \ } /* This subsidiary macro assembles the input data needed in preparation for forming the interpolated value in the n-dimensional case. */ #define ASSEMBLE_INPUT_ND(X,Xtype,Xfloating,Xfloattype,Xsigned,Usebad,Usevar) \ \ /* Initialise offsets into the input array. then loop to obtain each \ coordinate associated with the current output poitn. */ \ off_in = 0; \ for ( idim = 0; idim < ndim_in; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate is bad. If so give up on this point. */ \ bad = ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* Calculate the lowest and highest indices (in the current dimension) \ of the region of neighbouring pixels that will contribute to the \ interpolated result. Constrain these values to lie within the input \ grid. */ \ ixn = (int) floor( xn ); \ lo[ idim ] = MaxI( ixn - neighb + 1, lbnd_in[ idim ], status ); \ hi[ idim ] = MinI( ixn + neighb, ubnd_in[ idim ], status ); \ \ /* If the cube has a zero dimension then no data can come from it. */ \ bad = ( lo[ idim ] > hi[ idim ] ); \ if ( bad ) break; \ \ /* Accumulate the offset (from the start of the input array) of the \ contributing pixel which has the lowest index in each dimension. */ \ off_in += stride[ idim ] * ( lo[ idim ] - lbnd_in[ idim ] ); \ \ /* Initialise an array to keep track of the current position in the \ input cube. */ \ ixm[ idim ] = lo[ idim ]; \ } \ \ /* Note we do not need to check here whether the pixel in this position is \ bad; if any pixels in the cube are good we can form an average. */ \ \ /* If OK, initialise sums for forming the interpolated result. */ \ if ( !bad ) { \ sum = (Xfloattype) 0.0; \ wtsum= (Xfloattype) 0.0; \ if ( Usevar ) { \ sum_var = (Xfloattype) 0.0; \ bad_var = 0; \ } \ \ /* Loop to inspect all the contributing pixels, calculating the offset \ of each pixel from the start of the input array. */ \ do { \ \ /* If necessary, test if the input pixel is bad. */ \ if ( !( Usebad ) || ( in[ off_in ] != badval ) ) { \ \ /* If we are using variances, then check that the variance is valid; \ if it is invalid then ignore this pixel altogether. */ \ if ( Usevar ) { \ var = in_var[ off_in ]; \ if ( Usebad ) bad_var = ( var == badval ); \ CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ \ /* If variance is valid then accumulate suitably weighted values into \ the totals. */ \ if ( !( ( Xsigned ) || ( Usebad ) ) || !bad_var ) { \ pixwt = (Xfloattype) 1.0 / var; \ sum += pixwt * ( (Xfloattype) in[ off_in ] ); \ wtsum += pixwt; \ sum_var += pixwt; \ } \ \ /* If we are not using variances, then accumulate values into the \ totals with a weighting of unity. */ \ } else { \ sum += (Xfloattype) in[ off_in ]; \ wtsum++; \ } \ } \ \ /* Locate the next pixel in the input cube; try incrementing the lowest \ dimension index first, if that rolls over increment the next \ dimension index, and so on. */ \ for ( idim = 0; idim < ndim_in; idim++ ) { \ if ( ixm[ idim ] < hi[ idim ] ) { \ off_in += stride[ idim ]; \ ixm[ idim ]++; \ break; \ } else { \ off_in -= stride[ idim ] * ( hi[ idim ] - lo[ idim ] ); \ ixm[ idim ] = lo[ idim ]; \ } \ } \ \ /* If the highest dimension index has rolled over, we have done all \ the pixels in the cube. */ \ done = ( idim == ndim_in ); \ } while ( !done ); \ } /* This subsidiary macro calculates the interpolated output value (and variance) from the sums over contributing pixels, checks the results for validity, and assigns them to the output array(s). */ #define CALC_AND_ASSIGN_OUTPUT(X,Xtype,Xfloating,Xfloattype,Usebad,Usevar,Nobad) \ \ /* If the output data value has not yet been flagged as bad, then \ check that an interpolated value can actually be produced. First \ check that the sum of weights is not zero. */ \ if ( !bad ) { \ bad = ( wtsum == (Xfloattype) 0.0 ); \ \ /* If OK, calculate the interpolated value. Then, if the output data \ type is not floating point, check that this value will not overflow \ the available output range. */ \ if ( !bad ) { \ val = sum / wtsum; \ if ( !( Xfloating ) ) { \ bad = ( val <= lo_lim ) || ( val >= hi_lim ); \ } \ } \ \ /* If no interpolated data value can be produced, then no associated \ variance will be required either. */ \ if ( ( Usevar ) && bad ) bad_var = 1; \ } \ \ /* Now perform similar checks on the output variance value (if \ required). This time we check that the square of the sum of \ weights is not zero (since this might underflow before the sum of \ weights). Again we also check to prevent the result overflowing the \ output data type. */ \ if ( ( Usevar ) && !bad_var ) { \ wtsum_sq = wtsum * wtsum; \ bad_var = ( wtsum_sq == (Xfloattype) 0.0 ); \ if ( !bad_var ) { \ val_var = sum_var / wtsum_sq; \ if ( !( Xfloating ) ) { \ bad_var = ( val_var <= lo_lim ) || ( val_var >= hi_lim ); \ } \ } \ } \ \ /* Obtain the pixel offset into the output array. */ \ off_out = offset[ point ]; \ \ /* Assign a bad output value (and variance) if required and count it. */ \ if ( bad ) { \ if( !Nobad ) { \ out[ off_out ] = badval; \ if ( Usevar ) out_var[ off_out ] = badval; \ } \ (*nbad)++; \ \ /* Otherwise, assign the interpolated value. If the output data type \ is floating point, the result can be stored directly, otherwise we \ must round to the nearest integer. */ \ } else { \ if ( Xfloating ) { \ out[ off_out ] = (Xtype) val; \ } else { \ out[ off_out ] = (Xtype) ( val + ( ( val >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ \ /* If a variance estimate is required but none can be obtained, then \ store a bad output variance value and count it. */ \ if ( Usevar ) { \ if ( bad_var ) { \ if( !Nobad ) out_var[ off_out ] = badval; \ (*nbad)++; \ \ /* Otherwise, store the variance estimate, rounding to the nearest \ integer if necessary. */ \ } else { \ if ( Xfloating ) { \ out_var[ off_out ] = (Xtype) val_var; \ } else { \ out_var[ off_out ] = (Xtype) ( val_var + \ ( ( val_var >= (Xfloattype) 0.0 ) ? \ ( (Xfloattype) 0.5 ) : \ ( (Xfloattype) -0.5 ) ) ); \ } \ } \ } \ } /* These subsidiary macros define limits for range checking of results before conversion to the final data type. For each data type code , HI_ gives the least positive floating point value which just overflows that data type towards plus infinity, while LO_ gives the least negative floating point value which just overflows that data type towards minus infinity. Thus, a floating point value must satisfy LO is a floating point type, the limits are not actually used, but must be present to permit error-free compilation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define HI_LD ( 0.0L ) #define LO_LD ( 0.0L ) #endif #define HI_D ( 0.0 ) #define LO_D ( 0.0 ) #define HI_F ( 0.0f ) #define LO_F ( 0.0f ) #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define HI_L ( 0.5L + (long double) LONG_MAX ) #define LO_L ( -0.5L + (long double) LONG_MIN ) #define HI_UL ( 0.5L + (long double) ULONG_MAX ) #define LO_UL ( -0.5L ) #define HI_K ( 0.5L + (long double) LONG_MAX ) #define LO_K ( -0.5L + (long double) LONG_MIN ) #define HI_UK ( 0.5L + (long double) ULONG_MAX ) #define LO_UK ( -0.5L ) #else #define HI_L ( 0.5 + (double) LONG_MAX ) #define LO_L ( -0.5 + (double) LONG_MIN ) #define HI_UL ( 0.5 + (double) ULONG_MAX ) #define LO_UL ( -0.5 ) #define HI_K ( 0.5 + (double) LONG_MAX ) #define LO_K ( -0.5 + (double) LONG_MIN ) #define HI_UK ( 0.5 + (double) ULONG_MAX ) #define LO_UK ( -0.5 ) #endif #define HI_I ( 0.5 + (double) INT_MAX ) #define LO_I ( -0.5 + (double) INT_MIN ) #define HI_UI ( 0.5 + (double) UINT_MAX ) #define LO_UI ( -0.5 ) #define HI_S ( 0.5f + (float) SHRT_MAX ) #define LO_S ( -0.5f + (float) SHRT_MIN ) #define HI_US ( 0.5f + (float) USHRT_MAX ) #define LO_US ( -0.5f ) #define HI_B ( 0.5f + (float) SCHAR_MAX ) #define LO_B ( -0.5f + (float) SCHAR_MIN ) #define HI_UB ( 0.5f + (float) UCHAR_MAX ) #define LO_UB ( -0.5f ) /* This subsidiary macro tests for negative variance values. This check is required only for signed data types. */ #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) \ bad_var = bad_var || ( var < ( (Xtype) 0 ) ); /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_BLOCKAVE(LD,long double,1,long double,1) MAKE_INTERPOLATE_BLOCKAVE(L,long int,0,long double,1) MAKE_INTERPOLATE_BLOCKAVE(K,INT_BIG,0,long double,1) #else MAKE_INTERPOLATE_BLOCKAVE(L,long int,0,double,1) MAKE_INTERPOLATE_BLOCKAVE(K,INT_BIG,0,double,1) #endif MAKE_INTERPOLATE_BLOCKAVE(D,double,1,double,1) MAKE_INTERPOLATE_BLOCKAVE(F,float,1,float,1) MAKE_INTERPOLATE_BLOCKAVE(I,int,0,double,1) MAKE_INTERPOLATE_BLOCKAVE(S,short int,0,float,1) MAKE_INTERPOLATE_BLOCKAVE(B,signed char,0,float,1) /* Re-define the macro for testing for negative variances to do nothing. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #define CHECK_FOR_NEGATIVE_VARIANCE(Xtype) /* Expand the main macro above to generate a function for each required unsigned data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_INTERPOLATE_BLOCKAVE(UL,unsigned long int,0,long double,0) MAKE_INTERPOLATE_BLOCKAVE(UK,UINT_BIG,0,long double,0) #else MAKE_INTERPOLATE_BLOCKAVE(UL,unsigned long int,0,double,0) MAKE_INTERPOLATE_BLOCKAVE(UK,UINT_BIG,0,double,0) #endif MAKE_INTERPOLATE_BLOCKAVE(UI,unsigned int,0,double,0) MAKE_INTERPOLATE_BLOCKAVE(US,unsigned short int,0,float,0) MAKE_INTERPOLATE_BLOCKAVE(UB,unsigned char,0,float,0) /* Undefine the macros used above. */ #undef CHECK_FOR_NEGATIVE_VARIANCE #if HAVE_LONG_DOUBLE /* Not normally implemented */ #undef HI_LD #undef LO_LD #endif #undef HI_D #undef LO_D #undef HI_F #undef LO_F #undef HI_L #undef LO_L #undef HI_UL #undef LO_UL #undef HI_K #undef LO_K #undef HI_UK #undef LO_UK #undef HI_I #undef LO_I #undef HI_UI #undef LO_UI #undef HI_S #undef LO_S #undef HI_US #undef LO_US #undef HI_B #undef LO_B #undef HI_UB #undef LO_UB #undef CALC_AND_ASSIGN_OUTPUT #undef ASSEMBLE_INPUT_ND #undef ASSEMBLE_INPUT_2D #undef ASSEMBLE_INPUT_1D #undef MAKE_INTERPOLATE_BLOCKAVE static void Invert( AstMapping *this, int *status ) { /* *++ * Name: c astInvert f AST_INVERT * Purpose: * Invert a Mapping. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astInvert( AstMapping *this ) f CALL AST_INVERT( THIS, STATUS ) * Class Membership: * Mapping method. * Description: c This function inverts a Mapping by reversing the boolean sense f This routine inverts a Mapping by reversing the boolean sense * of its Invert attribute. If this attribute is zero (the * default), the Mapping will transform coordinates in the way * specified when it was created. If it is non-zero, the input and * output coordinates will be inter-changed so that the direction * of the Mapping is reversed. This will cause it to display the * inverse of its original behaviour. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ int invert; /* New Invert attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Determine the new Invert attribute value. */ invert = !astGetInvert( this ); /* Clear the old value. */ astClearInvert( this ); /* If the resulting default value is not the one required, then set a new value explicitly. */ if ( astGetInvert( this ) != invert ) astSetInvert( this, invert ); } static double J1Bessel( double x, int *status ) { /* * Name: * J1Bessel * Purpose: * Calculates the first-order Bessel function of the first kind. * Type: * Private function. * Synopsis: * #include "mapping.h" * double J1Bessel( double x, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of the first-order Bessel function * of the first kind. * Parameters: * x * The argument for J1. * status * Pointer to the inherited status variable. * Returned Value: * The calculated J1(x) value. * Notes: * - The algorithm is taken from the SCUBA routine SCULIB_BESSJ1, by * J.Lightfoot. * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ static double p1 = 1.0; static double p2 = 0.183105E-2; static double p3 = -0.3516396496E-4; static double p4 = 0.2457520174E-5; static double p5 = -0.240337019E-6; static double q1 = 0.04687499995; static double q2 = -0.2002690873E-3; static double q3 = 0.8449199096E-5; static double q4 = -0.88228987E-6; static double q5 = 0.105787412E-6; static double r1 = 72362614232.0; static double r2 = -7895059235.0; static double r3 = 242396853.1; static double r4 = -2972611.439; static double r5 = 15704.48260; static double r6 = -30.16036606; static double s1 = 144725228442.0; static double s2 = 2300535178.0; static double s3 = 18583304.74; static double s4 = 99447.43394; static double s5 = 376.9991397; static double s6 = 1.0; double ax; double xx; double z; double y; double value; int s; /* Calculate the value */ ax = fabs( x ); if( ax < 8.0 ) { y = x*x; value = x*( r1 + y*( r2 + y*( r3 + y*( r4 + y*( r5 + y*r6 ) ) ) ) ) / ( s1 + y*( s2 + y*( s3 + y*( s4 + y*( s5 + y*s6 ) ) ) ) ); } else { s = ( x >= 0.0 ) ? 1 : -1; z = 8.0 / ax; y = z*z; xx = ax - 2.356194491; value = sqrt ( 0.636619772/ax )*( cos( xx )*( p1 + y*( p2 + y* ( p3 + y*( p4 + y*p5 ) ) ) )-z*sin( xx )*( q1 + y*( q2 + y*( q3 + y* ( q4 + y*q5 ) ) ) ) )*s; } return value; } static int LinearApprox( AstMapping *this, const double *lbnd, const double *ubnd, double tol, double *fit, int *status ) { /* *++ * Name: c astLinearApprox f AST_LINEARAPPROX * Purpose: * Obtain a linear approximation to a Mapping, if appropriate. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c int astLinearApprox( AstMapping *this, const double *lbnd, c const double *ubnd, double tol, double *fit ) f RESULT = AST_LINEARAPPROX( THIS, LBND, UBND, TOL, FIT, STATUS ) * Class Membership: * Mapping function. * Description: * This function tests the forward coordinate transformation * implemented by a Mapping over a given range of input coordinates. If * the transformation is found to be linear to a specified level of * accuracy, then an array of fit coefficients is returned. These * may be used to implement a linear approximation to the Mapping's * forward transformation within the specified range of output coordinates. * If the transformation is not sufficiently linear, no coefficients * are returned. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping. c lbnd f LBND( * ) = DOUBLE PRECISION (Given) c Pointer to an array of doubles f An array * containing the lower bounds of a box defined within the input * coordinate system of the Mapping. The number of elements in this * array should equal the value of the Mapping's Nin attribute. This * box should specify the region over which linearity is required. c ubnd f UBND( * ) = DOUBLE PRECISION (Given) c Pointer to an array of doubles f An array * containing the upper bounds of the box specifying the region over * which linearity is required. c tol f TOL = DOUBLE PRECISION (Given) * The maximum permitted deviation from linearity, expressed as * a positive Cartesian displacement in the output coordinate * space of the Mapping. If a linear fit to the forward * transformation of the Mapping deviates from the true transformation * by more than this amount at any point which is tested, then no fit * coefficients will be returned. c fit f FIT( * ) = DOUBLE PRECISION (Returned) c Pointer to an array of doubles f An array * in which to return the co-efficients of the linear * approximation to the specified transformation. This array should * have at least "( Nin + 1 ) * Nout", elements. The first Nout elements * hold the constant offsets for the transformation outputs. The * remaining elements hold the gradients. So if the Mapping has 2 inputs * and 3 outputs the linear approximation to the forward transformation * is: * c X_out = fit[0] + fit[3]*X_in + fit[4]*Y_in f X_out = fit(1) + fit(4)*X_in + fit(5)*Y_in * c Y_out = fit[1] + fit[5]*X_in + fit[6]*Y_in f Y_out = fit(2) + fit(6)*X_in + fit(7)*Y_in * c Z_out = fit[2] + fit[7]*X_in + fit[8]*Y_in f Z_out = fit(3) + fit(8)*X_in + fit(9)*Y_in * f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astLinearApprox() f AST_LINEARAPPROX = LOGICAL * If the forward transformation is sufficiently linear, c a non-zero value is returned. Otherwise zero is returned f .TRUE is returned. Otherwise .FALSE. is returned * and the fit co-efficients are set to AST__BAD. * Notes: * - This function fits the Mapping's forward transformation. To fit * the inverse transformation, the Mapping should be inverted using c astInvert f AST_INVERT * before invoking this function. c - A value of zero f - A value of .FALSE. * will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *-- * Implementation Deficiencies: * Sub-classes which implement linear mappings should probably * over-ride this function to get better accuracy and faster execution, * but currently they do not. */ /* Local Variables: */ AstPointSet *pset_in_f; /* PointSet for input fitting points */ AstPointSet *pset_in_t; /* PointSet for input test points */ AstPointSet *pset_out_f; /* PointSet for output fitting points */ AstPointSet *pset_out_t; /* PointSet for output test points */ double **ptr_in_f; /* Input coordinate array pointers */ double **ptr_in_t; /* Input coordinate array pointers */ double **ptr_out_f; /* Output coordinate array pointers */ double **ptr_out_t; /* Output coordinate array pointers */ double *grad; /* Pointer to matrix of gradients */ double *zero; /* Pointer to array of zero point values */ double diff; /* Difference in coordinate values */ double err; /* Sum of squared error */ double frac; /* Fraction of input coordinate range */ double in1; /* Input coordinate value */ double in2; /* Input coordinate value */ double indiff; /* Difference in input coordinate values */ double out1; /* Output coordinate value */ double out2; /* Output coordinate value */ double x0; /* Coordinate of grid centre */ double y; /* Output coordinate (transformed) */ double yfit; /* Coordinate resulting from fit */ double z; /* Sum for calculating zero points */ int *vertex; /* Pointer to flag array for vertices */ int coord_in; /* Loop counter for input coordinates */ int coord_out; /* Loop counter for output coordinates. */ int done; /* All vertices visited? */ int face1; /* Index of first face coordinates */ int face2; /* Index of second face coordinates */ int face; /* Loop counter for faces */ int ii; /* Index into gradient matrix */ int linear; /* Mapping is linear? */ int nc; /* Number of coeffs in fit */ int ndim_in; /* Number of Mapping inputs */ int ndim_out; /* Number of Mapping outputs */ int npoint; /* Number of test points required */ int point; /* Counter for points */ int result; /* Returned flag */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ linear = 1; grad = NULL; zero = NULL; /* Get the number of Mapping output and inputs. */ ndim_in = astGetNin( this ); ndim_out = astGetNout( this ); /* Store the number of coefficients in the fit.*/ nc = ( ndim_in + 1 ) * ndim_out; /* Create a PointSet to hold input coordinates and obtain a pointer to its coordinate arrays. */ pset_in_f = astPointSet( 2 * ndim_in, ndim_in, "", status ); ptr_in_f = astGetPoints( pset_in_f ); if ( astOK ) { /* Set up and transform an initial set of points. */ /* ---------------------------------------------- */ /* Loop to set up input coordinates at the centre of each face of the input grid, storing them in the PointSet created above. */ point = 0; for ( face = 0; face < ( 2 * ndim_in ); face++ ) { for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in_f[ coord_in ][ point ] = 0.5 * ( lbnd[ coord_in ] + ubnd[ coord_in ] ); } ptr_in_f[ face / 2 ][ point ] = ( face % 2 ) ? ubnd[ face / 2 ] : lbnd[ face / 2 ]; point++; } } /* Transform these coordinates into the output grid's coordinate system and obtain an array of pointers to the resulting coordinate data. */ pset_out_f = astTransform( this, pset_in_f, 1, NULL ); ptr_out_f = astGetPoints( pset_out_f ); if ( astOK ) { /* Fit a linear approximation to the points. */ /* ----------------------------------------- */ /* Obtain pointers to the locations in the fit coefficients array where the gradients and zero points should be stored. */ grad = fit + ndim_out; zero = fit; /* On the assumption that the transformation applied above is approximately linear, loop to determine the matrix of gradients and the zero points which describe it. */ ii = 0; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { z = 0.0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { /* Find the indices of opposite faces in each input dimension. */ face1 = 2 * coord_in; face2 = face1 + 1; /* Obtain the input and output coordinates at these face centres. */ in1 = ptr_in_f[ coord_in ][ face1 ]; in2 = ptr_in_f[ coord_in ][ face2 ]; out1 = ptr_out_f[ coord_out ][ face1 ]; out2 = ptr_out_f[ coord_out ][ face2 ]; /* Check whether any transformed coordinates are bad. If so, the transformation cannot be linear, so give up trying to fit it. */ if ( ( out1 == AST__BAD ) || ( out2 == AST__BAD ) ) { linear = 0; break; } /* If possible, determine the gradient along this dimension, storing it in the appropriate element of the gradient matrix. */ indiff = in2 - in1; if ( indiff != 0.0 ) { grad[ ii++ ] = ( out2 - out1 ) / indiff; } else { grad[ ii++ ] = 0.0; } /* Accumulate the sum used to determine the zero point. */ z += ( out1 + out2 ); } /* Also quit the outer loop if a linear fit cannot be obtained. */ if ( !linear ) break; /* Determine the average zero point from all dimensions. */ zero[ coord_out ] = z / (double) ( 2 * ndim_in ); } /* If a linear fit was obtained, its zero points will be appropriate to an input coordinate system with an origin at the centre of the input grid (we assume this to simplify the calculations above). To correct for this, we transform the actual input coordinates of the grid's centre through the matrix of gradients and subtract the resulting coordinates from the zero point values. The zero points are then correct for the actual output and input coordinate systems we are using. */ if ( linear ) { ii = 0; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { x0 = 0.5 * ( lbnd[ coord_in ] + ubnd[ coord_in ] ); zero[ coord_out ] -= grad[ ii++ ] * x0; } } } } /* Annul the pointers to the PointSets used above. */ pset_out_f = astAnnul( pset_out_f ); pset_in_f = astAnnul( pset_in_f ); /* Calculate the number of test points required. */ /* --------------------------------------------- */ /* If we have obtained a linear fit above, it will (by construction) be exact at the centre of each face of the input grid. However, it may not fit anywhere else. We therefore set up some test points to determine if it is an adequate approximation elsewhere. */ if ( astOK && linear ) { /* Calculate the number of test points required to place one at each vertex of the grid. */ npoint = 1; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { npoint *= 2; } /* Now calculate the total number of test points required, also allowing one at the centre, one at half the distance to each face, and one at half the distance to each vertex. */ npoint = 1 + 2 * ( ndim_in + npoint ); /* Set up test points in the input coordinate system. */ /* --------------------------------------------------- */ /* Create a PointSet to hold the test coordinates and obtain an array of pointers to its coordinate data. */ pset_in_t = astPointSet( npoint, ndim_in, "", status ); ptr_in_t = astGetPoints( pset_in_t ); if ( astOK ) { /* If the input array is 1-dimensional, the face and vertex positions calculated below will co-incide. Therefore, we simply distribute the required number of test points uniformly throughout the input coordinate range (avoiding the end-points, where the fit has been obtained). The coordinates are stored in the PointSet created above. */ if ( ndim_in == 1 ) { for ( point = 0; point < npoint; point++ ) { frac = ( (double) ( point + 1 ) ) / (double) ( npoint + 1 ); ptr_in_t[ 0 ][ point ] = ( 1.0 - frac ) * lbnd[ 0 ] + frac * ubnd[ 0 ]; } /* Otherwise, generate one point at the grid centre (offset slightly since the exact centre may not be very representative). */ } else { point = 0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in_t[ coord_in ][ point ] = 0.49 * lbnd[ coord_in ] + 0.51 * ubnd[ coord_in ]; } point++; /* Similarly generate a point half way between the grid centre and the centre of each face. Again introduce some small random offsets to break any regularity in the grid. */ for ( face = 0; face < ( 2 * ndim_in ); face++ ) { for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in_t[ coord_in ][ point ] = 0.48 * lbnd[ coord_in ] + 0.52 * ubnd[ coord_in ]; } ptr_in_t[ face / 2 ][ point ] = ( 0.51 * ( ( ( face % 2 ) ? ubnd[ face / 2 ] : lbnd[ face / 2 ] ) ) + 0.49 * ptr_in_t[ face / 2 ][ 0 ] ); point++; } /* Allocate workspace and initialise flags for identifying the vertices. */ vertex = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { vertex[ coord_in ] = 0; } /* Now loop to visit each input grid vertex. */ done = 0; do { /* Generate a test point at each vertex. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in_t[ coord_in ][ point ] = vertex[ coord_in ] ? ubnd[ coord_in ] : lbnd[ coord_in ]; /* Also place one half way between the grid centre and each vertex. */ ptr_in_t[ coord_in ][ point + 1 ] = ( 0.52 * ptr_in_t[ coord_in ][ point ] + 0.48 * ptr_in_t[ coord_in ][ 0 ] ); } point += 2; /* Now update the array of vertex flags to identify the next vertex. */ coord_in = 0; do { /* The least significant dimension which does not have its upper bound as one of the vertex coordinates is changed to use its upper bound in the next vertex. */ if ( !vertex[ coord_in ] ) { vertex[ coord_in ] = 1; break; /* Any less significant dimensions whose upper bounds are already being used are changed to use their lower bounds in the next vertex. */ } else { vertex[ coord_in ] = 0; /* All vertices have been visited when the most significant dimension is changed back to using its lower bound. */ done = ( ++coord_in == ndim_in ); } } while ( !done ); } while ( !done ); } /* Free the workspace used for vertex flags. */ vertex = astFree( vertex ); } /* Transform the test points. */ /* -------------------------- */ /* Use the Mapping to transform the test points into the output grid's coordinate system, obtaining a pointer to the resulting arrays of output coordinates. */ pset_out_t = astTransform( this, pset_in_t, 1, NULL ); ptr_out_t = astGetPoints( pset_out_t ); /* Test the linear fit for accuracy. */ /* --------------------------------- */ /* If OK so far, then loop to use this fit to transform each test point and compare the result with the result of applying the Mapping. */ if ( astOK ) { for ( point = 0; point < npoint; point++ ) { /* Initialise the fitting error for the current point. */ err = 0.0; /* Obtain each output coordinate (produced by using the Mapping) in turn and check that it is not bad. If it is, then the transformation is not linear, so give up testing the fit. */ ii = 0; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { y = ptr_out_t[ coord_out ][ point ]; if ( y == AST__BAD ) { linear = 0; break; } /* Apply the fitted transformation to the input coordinates to obtain the approximate output coordinate value. */ yfit = zero[ coord_out ]; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { yfit += grad[ ii++ ] * ptr_in_t[ coord_in ][ point ]; } /* Form the sum of squared differences between the Mapping's transformation and the fit. */ diff = ( y - yfit ); err += diff * diff; } /* Quit the outer loop if the Mapping is found to be non-linear. */ if ( !linear ) break; /* Test if the Cartesian distance between the true output coordinate and the approximate one exceeds the accuracy tolerance. If this happens for any test point, we declare the Mapping non-linear and give up. */ if ( sqrt( err ) > tol ) { linear = 0; break; } } } /* Annul the pointers to the PointSets used above. */ pset_out_t = astAnnul( pset_out_t ); } pset_in_t = astAnnul( pset_in_t ); } /* If an error occurred, or the Mapping was found to be non-linear, then set the coefficients to AST_BAD. Otherwise, set the returned flag to indicate that the fit was succesful. */ if ( !astOK || !linear ) { for( ii = 0; ii < nc; ii++ ) fit[ ii ] = AST__BAD; } else { result = 1; } /* Return the result. */ return result; } static double LocalMaximum( const MapData *mapdata, double acc, double fract, double x[], int *status ) { /* * Name: * LocalMaximum * Purpose: * Find a local maximum in a Mapping function. * Type: * Private function. * Synopsis: * #include "mapping.h" * double LocalMaximum( const MapData *mapdata, double acc, double fract, * double x[], int *status ); * Class Membership: * Mapping member function. * Description: * This function finds a local maximum in the Mapping function * supplied. It employs the modified simplex method (as * implemented by UphillSimplex), but repeatedly re-starts the * simplex algorithm and tests for convergence of successive * maxima, so as to further improve robustness on difficult * problems. * Parameters: * mapdata * Pointer to a MapData structure describing the Mapping * function, its coordinate constraints, etc. * acc * The required accuracy with which the maximum is to be found. * fract * A value between 0.0 and 1.0 which determines the initial step * length along each coordinate axis. It should be given as a * fraction of the difference between the upper and lower * constraint values for each axis (as specified in the * "mapdata" structure). * x * Pointer to an array of double containing the coordinates of * an initial estimate of the position of the maximum. On exit, * this will be updated to contain the best estimate of the * maximum's position, as found by this function. * status * Pointer to the inherited status variable. * Returned Value: * The best estimate of the Mapping function's maximum value. * Notes: * - A value of AST__BAD will be returned, and no useful * information about a solution will be produced, if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Constants: */ const int maxcall = 1500; /* Maximum number of function evaluations */ const int maxiter = 5; /* Maximum number of iterations */ /* Local Variables: */ double *dx; /* Pointer to array of step lengths */ double err; /* Simplex error estimate */ double maximum; /* Simplex maximum value */ double middle; /* Middle coordinate between bounds */ double result; /* Result value to return */ int coord; /* Loop counter for coordinates */ int done; /* Iterations complete? */ int iter; /* Loop counter for iterations */ int ncall; /* Number of function calls (junk) */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialise to avoid compiler warnings. */ err = 0.0; /* Allocate workspace. */ dx = astMalloc( sizeof( double ) * (size_t) mapdata->nin ); /* Perform iterations to repeatedly identify a local maximum. */ for ( iter = 0; astOK && ( iter < maxiter ); iter++ ) { /* Set up initial step lengths along each coordinate axis, adjusting their signs to avoid placing points outside the coordinate constraints (i.e. step away from the closer boundary on each axis). */ for ( coord = 0; coord < mapdata->nin; coord++ ) { middle = 0.5 * ( mapdata->lbnd[ coord ] + mapdata->ubnd[ coord ] ); dx[ coord ] = fract * ( mapdata->ubnd[ coord ] - mapdata->lbnd[ coord ] ); if ( x[ coord ] > middle ) dx[ coord ] = -dx[ coord ]; } /* Find an approximation to a local maximum using the simplex method and check for errors. */ maximum = UphillSimplex( mapdata, acc, maxcall, dx, x, &err, &ncall, status ); if ( astOK ) { /* Use this maximum value if no previous maximum has been found. */ if ( result == AST__BAD ) { result = maximum; /* Otherwise use it only if it improves on the previous maximum. */ } else if ( maximum >= result ) { /* We iterate, re-starting the simplex algorithm from its previous best position so as to guard against premature false convergence. Iterations continue until the improvement in the maximum is no greater than the required accuracy (and the simplex algorithm itself has converged to the required accuracy). Note when iterations should cease. */ done = ( ( ( maximum - result ) <= acc ) && ( err <= acc ) ); /* Store the best maximum and quit iterating if appropriate. */ result = maximum; if ( done ) break; } /* Otherwise, decrement the initial step size for the next iteration. */ fract /= 1000.0; } } /* Free the workspace. */ dx = astFree( dx ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = AST__BAD; /* return the result. */ return result; } static void MapBox( AstMapping *this, const double lbnd_in[], const double ubnd_in[], int forward, int coord_out, double *lbnd_out, double *ubnd_out, double xl[], double xu[], int *status ) { /* *+ * Name: * astMapBox * Purpose: * Find a bounding box for a Mapping. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * void astMapBox( AstMapping *this, * const double lbnd_in[], const double ubnd_in[], * int forward, int coord_out, * double *lbnd_out, double *ubnd_out, * double xl[], double xu[] ); * Class Membership: * Mapping method. * Description: * This function allows you to find the "bounding box" which just * encloses another box after it has been transformed by a Mapping * (using either its forward or inverse transformation). A typical * use might be to calculate the size which an image would have * after being transformed by the Mapping. * * The function works on one dimension at a time. When supplied * with the lower and upper bounds of a rectangular region (box) of * input coordinate space, it finds the lowest and highest values * taken by a nominated output coordinate within that * region. Optionally, it also returns the input coordinates where * these bounding values are attained. It should be used repeatedly * if the extent of the bounding box is required in more than one * dimension. * Parameters: * this * Pointer to the Mapping. * lbnd_in * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the lower bound * of the input box in each dimension. * ubnd_in * Pointer to an array of double, with one element for each * Mapping input coordinate. This should contain the upper bound * of the input box in each dimension. * * Note that it is permissible for the lower bound to exceed the * corresponding upper bound, as the values will simply be * swapped before use. * forward * If this value is non-zero, then the Mapping's forward * transformation will be used to transform the input * box. Otherwise, its inverse transformation will be used. * * (If the inverse transformation is selected, then references * to "input" and "output" coordinates in this description * should be transposed. For example, the size of the "lbnd_in" * and "ubnd_in" arrays should match the number of output * coordinates, as given by the Mapping's Nout attribute.) * coord_out * The (zero-based) index of the output coordinate for which the * lower and upper bounds are required. * lbnd_out * Pointer to a double in which to return the lowest value taken * by the nominated output coordinate within the specified * region of input coordinate space. * ubnd_out * Pointer to a double in which to return the highest value * taken by the nominated output coordinate within the specified * region of input coordinate space. * xl * An optional pointer to an array of double, with one element * for each Mapping input coordinate. If given, this array will * be filled with the coordinates of an input point (although * not necessarily a unique one) for which the nominated output * coordinate takes the lower bound value returned in * "*lbnd_out". * * If these coordinates are not required, a NULL pointer may be * supplied. * xu * An optional pointer to an array of double, with one element * for each Mapping input coordinate. If given, this array will * be filled with the coordinates of an input point (although * not necessarily a unique one) for which the nominated output * coordinate takes the upper bound value returned in * "*ubnd_out". * * If these coordinates are not required, a NULL pointer may be * supplied. * Notes: * - Any input points which are transformed by the Mapping to give * output coordinates containing the value AST__BAD are regarded as * invalid and are ignored, They will make no contribution to * determining the output bounds, even although the nominated * output coordinate might still have a valid value at such points. * - An error will occur if the required output bounds cannot be * found. Typically, this might occur if all the input points which * the function considers turn out to be invalid (see above). The * number of points considered before generating such an error is * quite large, however, so this is unlikely to occur by accident * unless valid points are restricted to a very small subset of the * input coordinate space. * - The values returned via "lbnd_out", "ubnd_out", "xl" and "xu" * will be set to the value AST__BAD if this function should fail * for any reason. Their initial values on entry will not be * altered if the function is invoked with the global error status * set. *- * Implementation Notes: * - This function implements the basic astMapBox method available * via the protected interface to the Mapping class. The public * interface to this method is provided by the astMapBoxId_ * function. */ /* Local Variables: */ MapData mapdata; /* Structure to describe Mapping function */ double *x_l; /* Pointer to coordinate workspace */ double *x_u; /* Pointer to coordinate workspace */ double lbnd; /* Required lower bound */ double ubnd; /* Required upper bound */ int coord; /* Loop counter for coordinates. */ int nin; /* Effective number of input coordinates */ int nout; /* Effective number of output coordinates */ int refine; /* Can bounds be refined? */ /* Check the global error status. */ if ( !astOK ) return; /* Initialisation to avoid compiler warnings. */ lbnd = AST__BAD; ubnd = AST__BAD; /* Obtain the effective numbers of input and output coordinates for the Mapping, taking account of which transformation is to be used. */ nin = forward ? astGetNin( this ) : astGetNout( this ); nout = forward ? astGetNout( this ) : astGetNin( this ); /* Check that the output coordinate index supplied is valid and report an error if it is not. Use public (one-based) coordinate numbering in the error message. */ if ( astOK ) { if ( ( coord_out < 0 ) || ( coord_out >= nout ) ) { astError( AST__BADCI, "astMapBox(%s): Output coordinate index (%d) " "invalid - it should be in the range 1 to %d.", status, astGetClass( this ), coord_out + 1, nout ); } } /* Initialise a MapData structure to describe the Mapping function whose limits are to be found. Since it may be evaluated many times, we attempt to simplify the Mapping supplied. */ if ( astOK ) { mapdata.mapping = astSimplify( this ); /* Store the number of input/output coordinates and the index of the output coordinate in which we are interested. */ mapdata.nin = nin; mapdata.nout = nout; mapdata.coord = coord_out; /* Note which Mapping transformation is being used. */ mapdata.forward = forward; /* Store pointers to arrays which will contain the input coordinate bounds. */ mapdata.lbnd = astMalloc( sizeof( double ) * (size_t) nin ); mapdata.ubnd = astMalloc( sizeof( double ) * (size_t) nin ); /* Create PointSets for passing coordinate data to and from the Mapping. */ mapdata.pset_in = astPointSet( 1, nin, "", status ); mapdata.pset_out = astPointSet( 1, nout, "", status ); /* Obtain pointers to these PointSets' coordinate arrays. */ mapdata.ptr_in = astGetPoints( mapdata.pset_in ); mapdata.ptr_out = astGetPoints( mapdata.pset_out ); /* Allocate workspace for the returned input coordinates. */ x_l = astMalloc( sizeof( double ) * (size_t) nin ); x_u = astMalloc( sizeof( double ) * (size_t) nin ); if ( astOK ) { /* Initialise the output bounds and corresponding input coordinates to "unknown". */ for ( coord = 0; coord < nin; coord++ ) { x_l[ coord ] = AST__BAD; x_u[ coord ] = AST__BAD; /* Initialise the input bounds, ensuring they are the correct way around (if not already supplied this way). */ mapdata.lbnd[ coord ] = ( lbnd_in[ coord ] < ubnd_in[ coord ] ) ? lbnd_in[ coord ] : ubnd_in[ coord ]; mapdata.ubnd[ coord ] = ( ubnd_in[ coord ] > lbnd_in[ coord ] ) ? ubnd_in[ coord ] : lbnd_in[ coord ]; } /* First examine a set of special input points to obtain an initial estimate of the required output bounds. Do this only so long as the number of points involved is not excessive. */ if ( nin <= 12 ) { refine = SpecialBounds( &mapdata, &lbnd, &ubnd, x_l, x_u, status ); } else { refine = 1; } /* Then attempt to refine this estimate using a global search algorithm. */ if( refine ) GlobalBounds( &mapdata, &lbnd, &ubnd, x_l, x_u, status ); /* If an error occurred, generate a contextual error message. */ if ( !astOK ) { astError( astStatus, "Unable to find a bounding box for a %s.", status, astGetClass( this ) ); } } /* Return the output bounds and, if required, the input coordinate values which correspond with them. */ if ( astOK ) { *lbnd_out = lbnd; *ubnd_out = ubnd; for ( coord = 0; coord < nin; coord++ ) { if ( xl ) xl[ coord ] = x_l[ coord ]; if ( xu ) xu[ coord ] = x_u[ coord ]; } } /* Annul the simplified Mapping pointer and the temporary PointSets. Also free the workspace. */ mapdata.mapping = astAnnul( mapdata.mapping ); mapdata.lbnd = astFree( mapdata.lbnd ); mapdata.ubnd = astFree( mapdata.ubnd ); mapdata.pset_in = astAnnul( mapdata.pset_in ); mapdata.pset_out = astAnnul( mapdata.pset_out ); x_l = astFree( x_l ); x_u = astFree( x_u ); } /* If an error occurred, then return bad bounds values and coordinates. */ if ( !astOK ) { *lbnd_out = AST__BAD; *ubnd_out = AST__BAD; for ( coord = 0; coord < nin; coord++ ) { if ( xl ) xl[ coord ] = AST__BAD; if ( xu ) xu[ coord ] = AST__BAD; } } } static double MapFunction( const MapData *mapdata, const double in[], int *ncall, int *status ) { /* * Name: * MapFunction * Purpose: * Return the value of a selected transformed coordinate. * Type: * Private function. * Synopsis: * #include "mapping.h" * double MapFunction( const MapData *mapdata, const double in[], * int *ncall, int *status ); * Class Membership: * Mapping member function. * Description: * This function takes a set of input coordinates and applies a * Mapping's coordinate transformation to them. It then returns the * value of one of the transformed coordinates. * * It is provided for use by optimisation functions (e.g. those * used for finding bounding boxes). The Mapping to be used and * associated parameters (such as constraints on the range of input * coordinates and the index of the output coordinate to be * returned) are supplied in a MapData structure. The value * returned will be negated if the "negate" component of this * structure is non-zero. * * The value AST__BAD will be returned by this function if the * input coordinates lie outside the constrained range given in * the MapData structure, or if any of the transformed output * coordinates is bad. * Parameters: * mapdata * Pointer to a MapData structure which describes the Mapping to * be used. * in * A double array containing the input coordinates of a single point. * ncall * Pointer to an int containing a count of the number of times * the Mapping's coordinate transformation has been used. This * value will be updated to reflect any use made by this * function. Normally, this means incrementing the value by 1, * but this will be omitted if the input coordinates supplied * are outside the constrained range so that no transformation * is performed. * status * Pointer to the inherited status variable. * Returned Value: * The selected output coordinate value, or AST__BAD, as appropriate. * 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: */ double result; /* Result to be returned */ int bad; /* Output coordinates invalid? */ int coord_in; /* Loop counter for input coordinates */ int coord_out; /* Loop counter for output coordinates */ int outside; /* Input point outside bounds? */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* See if the input point lies outside the required bounds. */ outside = 0; for ( coord_in = 0; coord_in < mapdata->nin; coord_in++ ) { if ( ( in[ coord_in ] < mapdata->lbnd[ coord_in ] ) || ( in[ coord_in ] > mapdata->ubnd[ coord_in ] ) ) { outside = 1; break; } /* Also store the input coordinates in the memory associated with the Mapping's input PointSet. */ mapdata->ptr_in[ coord_in ][ 0 ] = in[ coord_in ]; } /* If the input coordinates are within bounds, transform them, using the PointSets identified in the "mapdata" structure. */ if ( !outside ) { (void) astTransform( mapdata->mapping, mapdata->pset_in, mapdata->forward, mapdata->pset_out ); /* Increment the number of calls to astTransform and check the error status. */ ( *ncall )++; if ( astOK ) { /* If OK, test if any of the output coordinates is bad. */ bad = 0; for ( coord_out = 0; coord_out < mapdata->nout; coord_out++ ) { if ( mapdata->ptr_out[ coord_out ][ 0 ] == AST__BAD ) { bad = 1; break; } } /* If not, then extract the required output coordinate, negating it if necessary. */ if ( !bad ) { result = mapdata->ptr_out[ mapdata->coord ][ 0 ]; if ( mapdata->negate ) result = -result; } } } /* Return the result. */ return result; } static int MapList( AstMapping *this, int series, int invert, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* *+ * Name: * astMapList * Purpose: * Decompose a Mapping into a sequence of simpler Mappings. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astMapList( AstMapping *this, int series, int invert, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * Mapping method. * Description: * This function decomposes a Mapping (which, in derived classes, * may be a compound Mapping) into a sequence of simpler Mappings * which may be applied in sequence to achieve the same effect. The * Mapping is decomposed as far as possible, but it is not * guaranteed that this will necessarily yield any more than one * Mapping, which may actually be the original one supplied. * * This function is provided to support both the simplification of * compound Mappings, and the analysis of Mapping structure so that * particular forms can be recognised. * Parameters: * this * Pointer to the Mapping to be decomposed (the Mapping is not * actually modified by this function). * series * If this value is non-zero, an attempt will be made to * decompose the Mapping into a sequence of equivalent Mappings * which can be applied in series (i.e. one after the other). If * it is zero, the decomposition will instead yield Mappings * which can be applied in parallel (i.e. on successive sub-sets * of the input/output coordinates). * invert * The value to which the Mapping's Invert attribute is to be * (notionally) set before performing the * decomposition. Normally, the value supplied here will be the * actual Invert value obtained from the Mapping (e.g. using * astGetInvert). Sometimes, however, when a Mapping is * encapsulated within another structure, that structure may * retain an Invert value (in order to prevent external * interference) which should be used instead. * * Note that the actual Invert value of the Mapping supplied is * not used (or modified) by this function. * nmap * The address of an int which holds a count of the number of * individual Mappings in the decomposition. On entry, this * should count the number of Mappings already in the * "*map_list" array (below). On exit, it is updated to include * any new Mappings appended by this function. * map_list * Address of a pointer to an array of Mapping pointers. On * entry, this array pointer should either be NULL (if no * Mappings have yet been obtained) or should point at a * dynamically allocated array containing Mapping pointers * ("*nmap" in number) which have been obtained from a previous * invocation of this function. * * On exit, the dynamic array will be enlarged to contain any * new Mapping pointers that result from the decomposition * requested. These pointers will be appended to any previously * present, and the array pointer will be updated as necessary * to refer to the enlarged array (any space released by the * original array will be freed automatically). * * The new Mapping pointers returned will identify a sequence of * Mappings which, when applied in order, will perform a forward * transformation equivalent to that of the original Mapping * (after its Invert flag has first been set to the value * requested above). The Mappings should be applied in series or * in parallel according to the type of decomposition requested. * * All the Mapping pointers returned by this function should be * annulled by the caller, using astAnnul, when no longer * required. The dynamic array holding these pointers should * also be freed, using astFree. * invert_list * Address of a pointer to an array of int. On entry, this array * pointer should either be NULL (if no Mappings have yet been * obtained) or should point at a dynamically allocated array * containing Invert attribute values ("*nmap" in number) which * have been obtained from a previous invocation of this * function. * * On exit, the dynamic array will be enlarged to contain any * new Invert attribute values that result from the * decomposition requested. These values will be appended to any * previously present, and the array pointer will be updated as * necessary to refer to the enlarged array (any space released * by the original array will be freed automatically). * * The new Invert values returned identify the values which must * be assigned to the Invert attributes of the corresponding * Mappings (whose pointers are in the "*map_list" array) before * they are applied. Note that these values may differ from the * actual Invert attribute values of these Mappings, which are * not relevant. * * The dynamic array holding these values should be freed by the * caller, using astFree, when no longer required. * Returned Value: * A non-zero value is returned if the supplied Mapping contained any * inverted CmpMaps. * Notes: * - It is unspecified to what extent the original Mapping and the * individual (decomposed) Mappings are * inter-dependent. Consequently, the individual Mappings cannot be * modified without risking modification of the original. * - If this function is invoked with the global error status set, * or if it should fail for any reason, then the *nmap value, the * list of Mapping pointers and the list of Invert values will all * be returned unchanged. *- */ /* Check the global error status. */ if ( !astOK ) return 0; /* Since we are dealing with a basic Mapping, only one new Mapping pointer will be returned. Extend the dynamic arrays to accommodate this Mapping. */ *map_list = astGrow( *map_list, *nmap + 1, sizeof( AstMapping * ) ); *invert_list = astGrow( *invert_list, *nmap + 1, sizeof( int ) ); if ( astOK ) { /* Return the invert flag value for the Mapping and a clone of the Mapping pointer. */ ( *invert_list )[ *nmap ] = ( invert != 0 ); ( *map_list )[ *nmap ] = astClone( this ); /* If OK, return the new Mapping count. */ if ( astOK ) ( *nmap )++; } return 0; } static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* *+ * Name: * astMapMerge * Purpose: * Simplify a sequence of Mappings. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int astMapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * Mapping method. * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated Mapping in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated Mapping with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated Mapping which is to be merged with * its neighbours. This should be a cloned copy of the Mapping * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * Mapping it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated Mapping resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* This is the default method which is inherited by all Mappings which do not explicitly provide their own simplification method. Return -1 to indicate that no simplification is provided. */ return -1; } static int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ){ /* *+ * Name: * astMapSplit * Purpose: * Create a Mapping representing a subset of the inputs of an existing * Mapping. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * int *astMapSplit( AstMapping *this, int nin, const int *in, * AstMapping **map ) * Class Membership: * Mapping method. * Description: * This function creates a new Mapping by picking specified inputs from * an existing Mapping. This is only possible if the specified inputs * correspond to some subset of the Mapping outputs. That is, there * must exist a subset of the Mapping outputs for which each output * depends only on the selected Mapping inputs, and not on any of the * inputs which have not been selected. Also, any output which is not in * this subset must not depend on any of the selected inputs. If these * conditions are not met by the supplied Mapping, then a NULL Mapping * is returned. * Parameters: * this * Pointer to the Mapping to be split (the Mapping 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 Mapping, 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 differetn to "nin"). A NULL pointer will be * returned if the supplied Mapping has no subset of outputs which * depend only on the selected inputs. The returned Mapping is a * deep copy of the required parts of the supplied Mapping. * 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 Mapping. 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. *- * Implementation Notes: * - This function implements the basic astMapSplit method available * via the protected interface to the Mapping class. The public * interface to this method is provided by the astMapSplitId_ * function. */ /* Local Variables: */ AstCmpMap *rmap; /* Unsimplified result mapping */ AstPermMap *pm; /* PermMap which rearranges the inputs */ int *outperm; /* PermMap output axis permutation array */ int *result; /* Pointer to returned array */ int iin; /* Input index */ int iout; /* Output index */ int mapnin; /* Number of Mapping inputs */ int nout; /* No of outputs */ int ok; /* Can the supplied "in" array be used? */ int perm; /* Are the inputs permuted? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Verify the input axis indices.*/ mapnin = astGetNin( this ); for( iin = 0; iin < nin; iin++ ){ if( in[ iin ] < 0 || in[ iin ] >= mapnin ) { astError( AST__AXIIN, "astMapSplit(%s): One of the supplied Mapping " "input indices has value %d which is invalid; it should " "be in the range 1 to %d.", status, astGetClass( this ), in[ iin ] + 1, mapnin ); break; } } /* Since we are dealing with a basic Mapping, we can only create the required output Mapping if all inputs are being selected. */ if( nin == mapnin ) { /* The inputs may have been selected in a different order to that in which they occur in the supplied Mapping. We therefore create a PermMap which rearranges the inputs into the order they have in the supplied Mapping. The supplied "in" array can act as the PermMap's "inperm" array. Allocate memory for the "outperm" array. */ outperm = astMalloc( sizeof(int)*(size_t) nin ); if( astOK ) { /* Store the input index for each output in the outperm array and check that each input has been selected once and only once. Also set a flag indicating if a PermMap is needed. */ perm = 0; ok = 1; for( iout = 0; iout < nin; iout++ ) outperm[ iout ] = -1; for( iin = 0; iin < nin; iin++ ) { iout = in[ iin ]; if( outperm[ iout ] != -1 ) { ok = 0; break; } else { outperm[ iout ] = iin; } } for( iout = 0; iout < nin; iout++ ) { if( outperm[ iout ] == -1 ) { ok = 0; break; } else if( outperm[ iout ] != iout ) { perm = 1; } } if( ok ) { /* Allocate the array to hold the returned output indices. */ nout = astGetNout( this ); result = astMalloc( sizeof(int)*(size_t) nout ); if( astOK ) { /* The outputs are copied from the supplied Mapping. */ for( iout = 0; iout < nout; iout++ ) result[ iout ] = iout; /* If the inputs are to be permuted, create the PermMap. */ if( perm ) { pm = astPermMap( nin, in, nin, outperm, NULL, "", status ); /* The returned Mapping is a series CmpMap containing this PermMap followed by the supplied Mapping. */ rmap = astCmpMap( pm, this, 1, "", status ); *map = astSimplify( rmap ); rmap = astAnnul( rmap ); /* Annul the PermMap pointer. */ pm = astAnnul( pm ); /* If no input permutation is needed, the resturned Mapping is just the supplied Mapping. */ } else { *map = astClone( this ); } } } /* Free resources. */ outperm = astFree( outperm ); } } /* Free resources if an error has occurred. */ if( !astOK ) { result = astFree( result ); *map = astAnnul( *map ); } /* Return the list of output indices. */ return result; } static double MatrixDet( int nrow, int ncol, const double *matrix, int *status ){ /* * Name: * MatrixDet * Purpose: * Return the determinant of a matrix. * Type: * Private function. * Synopsis: * #include "mapping.h" * double MatrixDet( int nrow, int ncol, const double *matrix, int *status ) * Class Membership: * Mapping member function. * Description: * This function returns the determinant of the supplied matrix. Any * rows or columns that hold only zeros or AST_BAD values are first * removed from the matrix. If the resulting matrix is not square, a * value of AST__BAD is returned for the determinant. * Parameters: * nrow * The number of rows in the matrix. * ncol * The number of columns in the matrix. * matrix * The matrix element values. The first row of "ncol" elements * should be supplied first, followed by the second row, etc. * status * Pointer to the inherited status variable. * Returned Value: * The determinant, or AST__BAD if the determinant could not be * caclculated. */ /* Local Variables: */ const double *sqmat; const double *m; double *a; double *y; double result; int *iw; int *usecol; int *userow; int i; int icol; int irow; int jf; int ncoluse; int ndim; int nrowuse; /* Initialise */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise... */ sqmat = NULL; nrowuse = 0; ncoluse = 0; /* Flag any rows and columns that should be ignored because they contain only bad values or zeros. */ userow = astCalloc( nrow, sizeof( *userow ) ); usecol = astCalloc( ncol, sizeof( *userow ) ); if( astOK ) { m = matrix; for( irow = 0; irow < nrow; irow++ ) { for( icol = 0; icol < ncol; icol++,m++ ) { if( *m != AST__BAD && *m != 0.0 ) { usecol[ icol ] = 1; userow[ irow ] = 1; } } } /* Find the number of usable rows and columns. */ for( irow = 0; irow < nrow; irow++ ) { if( userow[ irow ] ) nrowuse++; } for( icol = 0; icol < ncol; icol++ ) { if( usecol[ icol ] ) ncoluse++; } } /* Return AST__BAD if the resulting matrix is not square. */ if( ncoluse == nrowuse ) { ndim = ncoluse; /* If any rows or columns contained just bad or zero values, create a new matrix that excludes them. */ if( ncol > ndim || nrow > ndim ) { sqmat = astMalloc( ndim*ndim*sizeof(*sqmat) ); if( astOK ) { m = matrix; a = (double *) sqmat; for( irow = 0; irow < nrow; irow++ ) { if( userow[ irow ] ) { for( icol = 0; icol < ncol; icol++,m++ ) { if( usecol[ icol ] ) *(a++) = *m; } } else { m += ncol; } } } /* If no rows or columns contained just bad values, use the supplied matrix. */ } else { sqmat = matrix; } /* Calculate the determinant of the modified matrix */ if( ndim == 1 ) { result = sqmat[ 0 ]; } else if( ndim == 2 ) { result = sqmat[ 0 ]*sqmat[ 3 ] - sqmat[ 1 ]*sqmat[ 2 ]; } else { a = astStore( NULL, sqmat, sizeof( double )*(size_t) (ndim*ndim) ); iw = astMalloc( sizeof( int )*(size_t) ndim ); y = astMalloc( sizeof( double )*(size_t) ndim ); if( y ) { for( i = 0; i < ndim; i++ ) y[ i ] = 1.0; palDmat( ndim, a, y, &result, &jf, iw ); } y = astFree( y ); iw = astFree( iw ); a = astFree( a ); } } /* Free the square matrix if it was allocated here. */ if( sqmat != matrix ) sqmat = astFree( (void *) sqmat ); /* Free the usable row/column flags. */ userow = astFree( userow ); usecol = astFree( usecol ); return result; } static double MaxD( double a, double b, int *status ) { /* * Name: * MaxD * Purpose: * Return the maximum of two double values. * Type: * Private function. * Synopsis: * #include "mapping.h" * double MaxD( double a, double b, int *status ) * Class Membership: * Mapping member function. * Description: * This function returns the maximum of two double values. * Parameters: * a * The first value. * b * The second value. * status * Pointer to the inherited status variable. * Returned Value: * The maximum. */ /* Return the larger value. */ return ( a > b ) ? a : b; } static int MaxI( int a, int b, int *status ) { /* * Name: * MaxI * Purpose: * Return the maximum of two integer values. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MaxI( int a, int b, int *status ) * Class Membership: * Mapping member function. * Description: * This function returns the maximum of two integer values. * Parameters: * a * The first value. * b * The second value. * status * Pointer to the inherited status variable. * Returned Value: * The maximum. */ /* Return the larger value. */ return ( a > b ) ? a : b; } static int MinI( int a, int b, int *status ) { /* * Name: * MinI * Purpose: * Return the minimum of two integer values. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MinI( int a, int b, int *status ) * Class Membership: * Mapping member function. * Description: * This function returns the minimum of two integer values. * Parameters: * a * The first value. * b * The second value. * status * Pointer to the inherited status variable. * Returned Value: * The minimum. */ /* Return the smaller value. */ return ( a < b ) ? a : b; } static double NewVertex( const MapData *mapdata, int lo, double scale, double x[], double f[], int *ncall, double xnew[], int *status ) { /* * Name: * NewVertex * Purpose: * Locate a new vertex for a simplex. * Type: * Private function. * Synopsis: * #include "mapping.h" * double NewVertex( const MapData *mapdata, int lo, double scale, * double x[], double f[], int *ncall, double xnew[], int *status ); * Class Membership: * Mapping member function. * Description: * This function is provided for use during optimisation of a * Mapping function using the simplex method. It generates the * coordinates of a new simplex vertex and evaluates the Mapping * function at that point. If the function's value is better then * (i.e. larger than) the value at the previously worst vertex, * then it is used to replace that vertex. * Parameters: * mapdata * Pointer to a MapData structure which describes the Mapping * function to be used. * lo * The (zero-based) index of the simplex vertex which initially * has the worst (lowest) value. * scale * The scale factor to be used to generate the new vertex. The * distance of the worst vertex from the centre of the face * opposite it is scaled by this factor to give the new vertex * position. Negative factors result in reflection through this * opposite face. * x * An array of double containing the coordinates of the vertices * of the simplex. The coordinates of the first vertex are * stored first, then those of the second vertex, etc. This * array will be updated by this function if the new vertex is * used to replace an existing one. * f * An array of double containing the Mapping function values at * each vertex of the simplex. This array will be updated by * this function if the new vertex is used to replace an * existing one. * ncall * Pointer to an int containing a count of the number of times * the Mapping function has been invoked. This value will be * updated to reflect the actions of this function. * xnew * An array of double with one element for each input coordinate * of the Mapping function. This is used as workspace. * status * Pointer to the inherited status variable. * Returned Value: * The Mapping function value at the new vertex. This value is * returned whether or not the new vertex replaces an existing one. * Notes: * - A value of AST__BAD will be returned by this function if it is * invoked with the global error status set, or if it should fail * for any reason. * - A value of AST__BAD will also be returned if the new vertex * lies outside the constrained range of input coordinates * associated with the Mapping function (as specified in the * MapData structure supplied) or if any of the transformed output * coordinates produced by the underlying Mapping is bad. In either * case the new vertex will not be used to replace an existing one. */ /* Local Variables: */ double fnew; /* Function value at new vertex */ double xface; /* Coordinate of centre of magnification */ int coord; /* Loop counter for coordinates */ int ncoord; /* Number of coordinates */ int nvertex; /* Number of simplex vertices */ int vertex; /* Loop counter for vertices */ /* Initialise. */ fnew = AST__BAD; /* Check the global error status. */ if ( !astOK ) return fnew; /* Obtain the number of Mapping input coordinates from the MapData structure and calculate the number of simplex vertices. */ ncoord = mapdata->nin; nvertex = ncoord + 1; /* Loop to obtain each coordinate of the new vertex. */ for ( coord = 0; coord < ncoord; coord++ ) { /* Loop over all vertices except the lowest one and average their coordinates. This gives the coordinate of the centre of the face opposite the lowest vertex, which will act as the centre of magnification. */ xface = 0.0; for ( vertex = 0; vertex < nvertex; vertex++ ) { if ( vertex != lo ) { /* Divide each coordinate by the number of vertices as the sum is accumulated in order to minimise the risk of overflow. */ xface += x[ vertex * ncoord + coord ] / ( (double ) ( nvertex - 1 ) ); } } /* Magnify the lowest vertex's distance from this point by the required factor to give the coordinates of the new vertex. */ xnew[ coord ] = xface + ( x[ lo * ncoord + coord ] - xface ) * scale; } /* Evaluate the Mapping function at the new vertex. */ fnew = MapFunction( mapdata, xnew, ncall, status ); /* If the result is not bad and exceeds the previous value at the lowest vertex, then replace the lowest vertex with this new one. */ if ( astOK && ( fnew != AST__BAD ) && ( fnew > f[ lo ] ) ) { for ( coord = 0; coord < ncoord; coord++ ) { x[ lo * ncoord + coord ] = xnew[ coord ]; } f[ lo ] = fnew; } /* Return the value at the new vertex. */ return fnew; } static int QuadApprox( AstMapping *this, const double lbnd[2], const double ubnd[2], int nx, int ny, double *fit, double *rms, int *status ){ /* *++ * Name: c astQuadApprox f AST_QUADAPPROX * Purpose: * Obtain a quadratic approximation to a 2D Mapping. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c int QuadApprox( AstMapping *this, const double lbnd[2], c const double ubnd[2], int nx, int ny, double *fit, c double *rms ) f RESULT = AST_QUADAPPROX( THIS, LBND, UBND, NX, NY, FIT, RMS, STATUS ) * Class Membership: * Mapping function. * Description: * This function returns the co-efficients of a quadratic fit to the * supplied Mapping over the input area specified by c "lbnd" and "ubnd". f LBND and UBND. * The Mapping must have 2 inputs, but may have any number of outputs. * The i'th Mapping output is modelled as a quadratic function of the * 2 inputs (x,y): * * output_i = a_i_0 + a_i_1*x + a_i_2*y + a_i_3*x*y + a_i_4*x*x + * a_i_5*y*y * c The "fit" f The FIT * array is returned holding the values of the co-efficients a_0_0, * a_0_1, etc. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping. c lbnd f LBND( * ) = DOUBLE PRECISION (Given) c Pointer to an array of doubles f An array * containing the lower bounds of a box defined within the input * coordinate system of the Mapping. The number of elements in this * array should equal the value of the Mapping's Nin attribute. This * box should specify the region over which the fit is to be * performed. c ubnd f UBND( * ) = DOUBLE PRECISION (Given) c Pointer to an array of doubles f An array * containing the upper bounds of the box specifying the region over * which the fit is to be performed. c nx f NX = INTEGER (Given) * The number of points to place along the first Mapping input. The * first point is at c "lbnd[0]" and the last is at "ubnd[0]". f LBND( 1 ) and the last is at UBND( 1 ). * If a value less than three is supplied a value of three will be used. c ny f NY = INTEGER (Given) * The number of points to place along the second Mapping input. The * first point is at c "lbnd[1]" and the last is at "ubnd[1]". f LBND( 2 ) and the last is at UBND( 2 ). * If a value less than three is supplied a value of three will be used. c fit f FIT( * ) = DOUBLE PRECISION (Returned) c Pointer to an array of doubles f An array * in which to return the co-efficients of the quadratic * approximation to the specified transformation. This array should * have at least "6*Nout", elements. The first 6 elements hold the * fit to the first Mapping output. The next 6 elements hold the * fit to the second Mapping output, etc. So if the Mapping has 2 * inputs and 2 outputs the quadratic approximation to the forward * transformation is: * c X_out = fit[0] + fit[1]*X_in + fit[2]*Y_in + fit[3]*X_in*Y_in + c fit[4]*X_in*X_in + fit[5]*Y_in*Y_in c Y_out = fit[6] + fit[7]*X_in + fit[8]*Y_in + fit[9]*X_in*Y_in + c fit[10]*X_in*X_in + fit[11]*Y_in*Y_in f X_out = fit(1) + fit(2)*X_in + fit(3)*Y_in + fit(4)*X_in*Y_in + f fit(5)*X_in*X_in + fit(6)*Y_in*Y_in f Y_out = fit(7) + fit(8)*X_in + fit(9)*Y_in + fit(10)*X_in*Y_in + f fit(11)*X_in*X_in + fit(12)*Y_in*Y_in * c rms f RMS = DOUBLE PRECISION (Returned) c Pointer to a double in which to return the f The * RMS residual between the fit and the Mapping, summed over all * Mapping outputs. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astQuadApprox() f AST_QUADAPPROX = LOGICAL * If a quadratic approximation was created, c a non-zero value is returned. Otherwise zero is returned f .TRUE is returned. Otherwise .FALSE. is returned * and the fit co-efficients are set to AST__BAD. * Notes: * - This function fits the Mapping's forward transformation. To fit * the inverse transformation, the Mapping should be inverted using c astInvert f AST_INVERT * before invoking this function. c - A value of zero f - A value of .FALSE. * 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 *pset1; AstPointSet *pset2; double **pdat1; double **pdat2; double *ofit; double *px; double *py; double *pz; double det; double dx; double dy; double mat[ 6*6 ]; double sx2; double sx2y2; double sx2y; double sx3; double sx3y; double sx4; double sx; double sxy2; double sxy3; double sxy; double sy2; double sy3; double sy4; double sy; double sz; double sz2; double szx2; double szx; double szxy; double szy2; double szy; double x; double xx; double xy; double y; double yy; double z; int i; int iout; int iw[ 6 ]; int ix; int iy; int n; int nin; int nout; int np; int ntot; int result; int sing; /* Initialise the returned values. */ result = 0; fit[ 0 ] = AST__BAD; *rms = AST__BAD; ntot = 0; /* Check the global error status. */ if( !astOK ) return result; /* Get the number of Mapping inputs and outputs. Report an error if not correct. */ nin = astGetI( this, "Nin" ); nout = astGetI( this, "Nout" ); if( nin != 2 && astOK ) { astError( AST__BADNI, "astQuadApprox(%s): Input Mapping has %d %s - " "it must have 2 inputs.", status, astGetClass( this ), nin, (nin==1)?"input":"inputs" ); } /* Ensure we are using at least 3 points on each of the two input axes. */ if( nx < 3 ) nx = 3; if( ny < 3 ) ny = 3; /* Get the total number of grid points. */ np = nx*ny; /* Create a PointSet to hold the 2D grid of input positions. */ pset1 = astPointSet( np, 2, " ", status ); pdat1 = astGetPoints( pset1 ); /* Create a PointSet to hold the N-D grid of output positions. */ pset2 = astPointSet( np, nout, " ", status ); pdat2 = astGetPoints( pset2 ); /* Check the memory allocation (and everything else) was succesful. */ if( astOK ) { /* Find the cell dimensions on X and Y input axes. */ dx = ( ubnd[ 0 ] - lbnd[ 0 ] )/( nx - 1 ); dy = ( ubnd[ 1 ] - lbnd[ 1 ] )/( ny - 1 ); /* Create a regular grid of input positions. */ px = pdat1[ 0 ]; py = pdat1[ 1 ]; for( iy = 0; iy < ny; iy++ ) { x = lbnd[ 0 ]; y = lbnd[ 1 ] + iy*dy; for( ix = 0; ix < nx; ix++ ) { *(px++) = x; *(py++) = y; x += dx; } } /* Use the supplied Mapping to transform this grid into the output space. */ (void) astTransform( this, pset1, 1, pset2 ); /* Assume the approximation can be created. */ result = 1; *rms = 0.0; /* Loop round each Mapping output. */ for( iout = 0; iout < nout && astOK; iout++ ) { /* Get a pointer to the first element of the fit array for this output. */ ofit = fit + 6*iout; /* Form the required sums. */ n = 0; sx = 0.0; sy = 0.0; sxy = 0.0; sx2 = 0.0; sy2 = 0.0; sx2y = 0.0; sx3 = 0.0; sxy2 = 0.0; sy3 = 0.0; sx2y2 = 0.0; sx3y = 0.0; sxy3 = 0.0; sx4 = 0.0; sy4 = 0.0; sz = 0.0; sz2 = 0.0; szx = 0.0; szy = 0.0; szxy = 0.0; szx2 = 0.0; szy2 = 0.0; px = pdat1[ 0 ]; py = pdat1[ 1 ]; pz = pdat2[ iout ]; for( i = 0; i < np; i++ ) { x = *(px++); y = *(py++); z = *(pz++); if( z != AST__BAD ) { xx = x*x; yy = y*y; xy = x*y; n++; sx += x; sy += y; sxy += xy; sx2 += xx; sy2 += yy; sx2y += xx*y; sx3 += xx*x; sxy2 += x*yy; sy3 += yy*y; sx2y2 += xx*yy; sx3y += xx*xy; sxy3 += xy*yy; sx4 += xx*xx; sy4 += yy*yy; sz += z; sz2 += z*z; szx += z*x; szy += z*y; szxy += z*xy; szx2 += z*xx; szy2 += z*yy; } } /* Form a matrix (M) and vector (V) such that M.X = V, where X is the solution vector holding the required best fit parameter values (V is stored in ofit). */ mat[ 0 ] = n; mat[ 1 ] = sx; mat[ 2 ] = sy; mat[ 3 ] = sxy; mat[ 4 ] = sx2; mat[ 5 ] = sy2; mat[ 6 ] = sx; mat[ 7 ] = sx2; mat[ 8 ] = sxy; mat[ 9 ] = sx2y; mat[ 10 ] = sx3; mat[ 11 ] = sxy2; mat[ 12 ] = sy; mat[ 13 ] = sxy; mat[ 14 ] = sy2; mat[ 15 ] = sxy2; mat[ 16 ] = sx2y; mat[ 17 ] = sy3; mat[ 18 ] = sxy; mat[ 19 ] = sx2y; mat[ 20 ] = sxy2; mat[ 21 ] = sx2y2; mat[ 22 ] = sx3y; mat[ 23 ] = sxy3; mat[ 24 ] = sx2; mat[ 25 ] = sx3; mat[ 26 ] = sx2y; mat[ 27 ] = sx3y; mat[ 28 ] = sx4; mat[ 29 ] = sx2y2; mat[ 30 ] = sy2; mat[ 31 ] = sxy2; mat[ 32 ] = sy3; mat[ 33 ] = sxy3; mat[ 34 ] = sx2y2; mat[ 35 ] = sy4; ofit[ 0 ] = sz; ofit[ 1 ] = szx; ofit[ 2 ] = szy; ofit[ 3 ] = szxy; ofit[ 4 ] = szx2; ofit[ 5 ] = szy2; /* Now find the solution vector (the solution over-writes teh current contents of "ofit"). */ palDmat( 6, mat, ofit, &det, &sing, iw ); /* If the fit failed, fill the coefficient array with bad values. */ if( sing != 0 ) { for( i = 0; i < 6; i++ ) ofit[ i ] = AST__BAD; result = 0; break; /* If the fit succeeded, update the summ of the squared residuals. */ } else { ntot += n; *rms += ofit[ 0 ]*ofit[ 0 ]*n + 2*ofit[ 0 ]*ofit[ 1 ]*sx + 2*ofit[ 0 ]*ofit[ 2 ]*sy + 2*( ofit[ 0 ]*ofit[ 3 ] + ofit[ 1 ]*ofit[ 2 ] )*sxy + ( 2*ofit[ 0 ]*ofit[ 4 ] + ofit[ 1 ]*ofit[ 1 ] )*sx2 + ( 2*ofit[ 0 ]*ofit[ 5 ] + ofit[ 2 ]*ofit[ 2 ] )*sy2 + 2*ofit[ 1 ]*ofit[ 4 ]*sx3 + 2*( ofit[ 1 ]*ofit[ 3 ] + ofit[ 2 ]*ofit[ 4 ] )*sx2y + 2*( ofit[ 1 ]*ofit[ 5 ] + ofit[ 2 ]*ofit[ 3 ] )*sxy2 + 2*ofit[ 2 ]*ofit[ 5 ]*sy3 + ofit[ 4 ]*ofit[ 4 ]*sx4 + 2*ofit[ 3 ]*ofit[ 4 ]*sx3y + ( 2*ofit[ 4 ]*ofit[ 5 ] + ofit[ 3 ]*ofit[ 3 ] )*sx2y2 + 2*ofit[ 3 ]*ofit[ 5 ]*sxy3 + ofit[ 5 ]*ofit[ 5 ]*sy4 + sz2 - 2*( ofit[ 0 ]*sz + ofit[ 1 ]*szx + ofit[ 2 ]*szy + ofit[ 3 ]*szxy + ofit[ 4 ]*szx2 + ofit[ 5 ]*szy2 ); } } } /* Free resources. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Return AST__BAD if anything went wrong. */ if( !astOK || ntot == 0 ) { result = 0; fit[ 0 ] = AST__BAD; *rms = AST__BAD; /* Otherwise normalise the returned RMS. */ } else { if( *rms > 0.0 ) { *rms = sqrt( *rms/ntot ); } else { *rms = 0.0; } } /* Return result */ return result; } static double Random( long int *seed, int *status ) { /* * Name: * Random * Purpose: * Return a pseudo-random value in the range 0 to 1. * Type: * Private function. * Synopsis: * #include "mapping.h" * double Random( long int *seed, int *status ); * Class Membership: * Mapping member function. * Description: * This function returns a pseudo-random double value from a PDF * uniformly distributed in the range 0 to 1. It also updates a * seed value so that a sequence of pseudo-random values may be * obtained with successive invocations. * Parameters: * seed * Pointer to a long int which should initially contain a * non-zero seed value. This will be updated with a new seed * which may be supplied on the next invocation in order to * obtain a different pseudo-random value. * status * Pointer to the inherited status variable. * Returned Value: * The pseudo-random value. */ /* Local Variables: */ long int i; /* Temporary storage */ /* This a basic random number generator using constants given in Numerical Recipes (Press et al.). */ i = *seed / 127773; *seed = ( *seed - i * 127773 ) * 16807 - i * 2836; if ( *seed < 0 ) *seed += 2147483647; /* Return the result as a double value in the range 0 to 1. */ return ( (double) ( *seed - 1 ) ) / (double) 2147483646; } static double Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ){ /* *+ * Name: * astRate * Purpose: * Calculate the rate of change of a Mapping output. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * result = astRate( AstMapping *this, double *at, int ax1, int ax2 ) * Class Membership: * Mapping method. * Description: * 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 the mean gradient within a small interval centred on * the supplied position. The interval size is selected automatically * to minimise the error on the returned value. For large intervals, * the error is dominated by changes in the gradient of the * transformation. For small intervals, the error is dominated by * rounding errors. The best interval is the one that gives the most * consistent measure of the gradient within the interval. To find this * consistency, each candidate interval is subdivided into eight * sub-intervals, the mean gradient within each sub-interval is found, * and the associated consistency measure is then the difference between * the maximum and minimum sub-interval gradient found within the interval. * 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). * 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. *- * Implementation Notes: * - This function implements the basic astRate method available * via the protected interface to the Mapping class. The public * interface to this method is provided by the astRateId_ * function. */ #define NN 50 /* Local Variables: */ double h0; double h; double mean; double minrange; double range0; double range; double ret; double x0; double y[2*NN+1]; double z[2*NN+1]; int ibot; int iin; int iret; int itop; int nin; int nout; /* Initialise */ ret = AST__BAD; /* Check the global error status. */ if ( !astOK ) return ret; /* Allocate resources */ RateFun( NULL, NULL, -1, 0, 0, NULL, NULL, status ); /* Obtain the numbers of input and output coordinates for the Mapping. */ nin = astGetNin( this ); nout = astGetNout( this ); /* Validate the output index. */ if ( astOK && ( ax1 < 0 || ax1 >= nout ) ) { astError( AST__AXIIN, "astRate(%s): The supplied Mapping output " "index (%d) is invalid; it should be in the range 1 to %d.", status, astGetClass( this ), ax1 + 1, nout ); } /* Validate the input index. */ if ( astOK && ( ax2 < 0 || ax2 >= nin ) ) { astError( AST__AXIIN, "astRate(%s): The supplied Mapping input " "index (%d) is invalid; it should be in the range 1 to %d.", status, astGetClass( this ), ax2 + 1, nin ); } /* Check the Mapping has a forward transformation. */ if ( astOK && !astGetTranForward( this ) ) { astError( AST__NODEF, "astRate(%s): The supplied Mapping does not " "have a defined forward transformation.", status, astGetClass( this ) ); } /* Save the central value on the Mapping input which is to be varied. */ x0 = at[ ax2 ]; /* If it is bad, return bad values. */ if( astOK && x0 != AST__BAD ) { /* The required derivative is formed by evaluating the transformation at two positions close to "x0", and dividing the change in y by the change in x. The complexity comes in deciding how close to "x0" the two points should be. If the points are too far apart, the gradient of the function may vary significantly between the two points and so we have little confidence that he mean gradient in the interval is a good estimate of the gradient at "x0". On the other hand if the points are too close together, rounding errors will make the gradient value unreliable. The optimal interval is found by testing a number of different intervals as follows. Each interval is split into NDIV equal sub-intervals, and the gradient in each sub-interval is found. The max and min gradient for any of these sub-intervals is found, and the difference between them is used as an estimate of the reliability of the mean gradient within the whole interval. The interval with the greatest reliability is used to define the returned gradient. The initial estimate of the interval size is a fixed small fraction of the supplied "x0" value, or 1.0 if "x0" is zero. */ h0 = ( x0 != 0.0 ) ? DBL_EPSILON*1.0E9*fabs( x0 ) : 1.0; /* Attempt to find the mean gradient, and the range of gradients, within an interval of size "h0" centred on "x0". If this cannot be done, increase "h0" by a factor fo ten repeatedly until it can be done, or a silly large interval size is reached. */ mean = AST__BAD; while( mean == AST__BAD && h0 < 1.0E-10*DBL_MAX ) { h0 *= 10; mean = FindGradient( this, at, ax1, ax2, x0, h0, &range0, status ); } /* If this was not successful, return AST__BAD as the function value. */ if( mean != AST__BAD ) { /* We now search through a range of larger interval sizes, to see if any produce a more reliable mean gradient estimate (i.e. have a smaller range of gradients within the interval ). After that we search through a range of smaller interval sizes. The gradient range and mean gradient for each interval size are stored in arrays "y" and "z" respectively. "iret" is the index of the most reliable interval found so far (i.e. the one with the smallest range of sub-interval gradients). The original interval "h0" is stored in the middle element of these arrays (index "NN"). Intervals are stored in monotonic order of interval size in the arrays. */ iret = NN; y[ NN ] = range0; z[ NN ] = mean; minrange = range0; /* itop is the index of the last array elements to store calculated values. */ itop = NN; /* Loop round increasing the interval size by a factor of four each time round. */ h = h0; for( iin = NN + 1; iin <= 2*NN && astOK; iin++ ){ h *= 4.0; /* Calculate the mean gradient, and the range of gradients, using the current interval size. */ mean = FindGradient( this, at, ax1, ax2, x0, h, &range, status ); /* If it could be done, store the values in the arrays. */ if( mean != AST__BAD ) { itop++; z[ itop ] = mean; y[ itop ] = range; /* Look for the smallest range, and note its index in the arrays. */ if( range < minrange ) { minrange = range; iret = itop; /* If a range of zero is encountered, we only believe it if the previous interval also had zero range. Otherwise, it's probably just a numerical fluke. If the previous interval also had a range of zero, we can forget the rest of the algorithm since the supplied transformation is linear and we now have its gradient. So leave the loop. */ } else if( range == 0.0 && y[ iin - 1 ] == 0 ) { iret = itop; break; } /* Stop looping when the interval range is 100 times the original interval range. */ if( range > 100*range0 ) break; } } /* Record the minimum range found so far. */ range0 = minrange; /* ibot is the index of the first array elements to store calculated values. */ ibot = NN; /* Loop round decreasing the interval size by a factor of four each time round. This is just like the last loop, but goes the other way, to lower indices. */ h = h0; for( iin = NN - 1; iin >= 0 && astOK; iin-- ){ h /= 4.0; mean = FindGradient( this, at, ax1, ax2, x0, h, &range, status ); if( mean != AST__BAD ) { ibot--; z[ ibot ] = mean; y[ ibot ] = range; if( range < minrange ) { minrange = range; iret = ibot; } else if( range == 0.0 && y[ iin + 1 ] == 0 ) { iret = ibot; break; } if( range > 100*range0 ) break; } } /* If the smallest gradient range in any interval was zero, we only believe it if the adjacent interval size also had zero range. */ if( minrange == 0.0 ) { if( ( iret > ibot && y[ iret - 1 ] == 0 ) || ( iret < itop && y[ iret + 1 ] == 0 ) ) { ret = z[ iret ]; /* Otherwise, search for the smallest gradient range, ignoring values exactly equal to zero, and return the corresponding mean interval gradient. */ } else { for( iin = ibot; iin <= itop; iin++ ){ if( y[ iin ] > 0.0 ){ if( minrange == 0 || y[ iin ] < minrange ) { minrange = y[ iin ]; ret = z[ iin ]; } } } } /* If the minimum range was non-zero, we can just return the corresponding mean gradient. */ } else { ret = z[ iret ]; } } } /* Free resources */ RateFun( NULL, NULL, -2, 0, 0, NULL, NULL, status ); /* Return the result. */ return ret; #undef NN } static void RateFun( AstMapping *map, double *at, int ax1, int ax2, int n, double *x, double *y, int *status ) { /* * Name: * RateFun * Purpose: * Find the value of the function currently being differentiated by the * astRate method. * Type: * Private function. * Synopsis: * #include "mapping.h" * void RateFun( AstMapping *map, double *at, int ax1, int ax2, * int n, double *x, double *y, int *status ) * Class Membership: * Mapping method. * Description: * This is a service function for the astRate method. It evaluates the * function being differentiated at specified axis values. * * This function uses static resources in order to avoid the overhead * of creating new PointSets each time this function is called. These * static resources which must be initialised before the first invocation * with a given Mapping, and must be released after the final invocation. * See "ax1". * Parameters: * map * Pointer to a Mapping which yields the value of the function at x. * The Mapping may have any number of inputs and outputs; the specific * output representing the function value, f, is specified by ax1 and * the specific input representing the argument, x, is specified by ax2. * at * A pointer to an array holding axis values at the position at which * the function is to be evaluated. The number of values supplied * must equal the number of inputs to the Mapping. The value supplied * for axis "ax2" is ignored (the value of "x" is used for axis "ax2"). * ax1 * The zero-based index of the Mapping output which is to be * differentiated. Set this to -1 to allocate, or -2 to release, * the static resources used by this function. * ax2 * The zero-based index of the Mapping input which is to be varied. * n * The number of elements in the "x" and "y" arrays. This should not * be greater than 2*RATE_ORDER. * x * The value of the Mapping input specified by ax2 at which the * function is to be evaluated. If "ax2" is set to -1, then the * supplied value is used as flag indicating if the static resources * used by this function should be initialised (if x >= 0 ) or * freed (if x < 0). * y * An array in which to return the function values at the positions * given in "x". * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS AstPointSet *pset1; AstPointSet *pset2; double **ptr1; double **ptr2; double *oldx; double *oldy; double *p; double xx; int i; int k; int nin; int nout; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(map); /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ pset2 = NULL; /* If required, initialise things. */ if( ax1 == -1 ) { for( i = 0; i < RATEFUN_MAX_CACHE; i++ ) { ratefun_pset_size[ i ] = 0; ratefun_pset1_cache[ i ] = NULL; ratefun_pset2_cache[ i ] = NULL; } ratefun_next_slot = 0; /* If required, clean up. */ } else if( ax1 == -2 ) { for( i = 0; i < RATEFUN_MAX_CACHE; i++ ) { ratefun_pset_size[ i ] = 0; if( ratefun_pset1_cache[ i ] ) ratefun_pset1_cache[ i ] = astAnnul( ratefun_pset1_cache[ i ] ); if( ratefun_pset2_cache[ i ] ) ratefun_pset2_cache[ i ] = astAnnul( ratefun_pset2_cache[ i ] ); } ratefun_next_slot = 0; /* Otherwise do the transformations. */ } else { /* See if we have already created PointSets of the correct size. */ pset1 = NULL; for( i = 0; i < RATEFUN_MAX_CACHE; i++ ) { if( ratefun_pset_size[ i ] == n ) { pset1 = ratefun_pset1_cache[ i ]; pset2 = ratefun_pset2_cache[ i ]; break; } } /* If we have not, create new PointSets now. */ if( pset1 == NULL ) { nin = astGetNin( map ); pset1 = astPointSet( n, nin, "", status ); ptr1 = astGetPoints( pset1 ); nout = astGetNout( map ); pset2 = astPointSet( n, nout, "", status ); ptr2 = astGetPoints( pset2 ); /* Store the input position in the input PointSet. */ for( i = 0; i < nin; i++ ) { xx = at[ i ]; p = ptr1[ i ]; for( k = 0; k < n; k++, p++ ) *p = xx; } /* Add these new PointSets to the cache, removing any existing PointSets. */ if( ratefun_pset_size[ ratefun_next_slot ] > 0 ) { (void) astAnnul( ratefun_pset1_cache[ ratefun_next_slot ] ); (void) astAnnul( ratefun_pset2_cache[ ratefun_next_slot ] ); } ratefun_pset1_cache[ ratefun_next_slot ] = pset1; ratefun_pset2_cache[ ratefun_next_slot ] = pset2; ratefun_pset_size[ ratefun_next_slot ] = n; if( ++ratefun_next_slot == RATEFUN_MAX_CACHE ) ratefun_next_slot = 0; /* If existing PointSets were found, get there data arrays. */ } else { ptr1 = astGetPoints( pset1 ); ptr2 = astGetPoints( pset2 ); } /* Store the input X values in the input PointSet data array. */ oldx = ptr1[ ax2 ]; ptr1[ ax2 ] = x; /* Store the output Y values in the output PointSet data array. */ oldy = ptr2[ ax1 ]; ptr2[ ax1 ] = y; /* Transform the positions. */ (void) astTransform( map, pset1, 1, pset2 ); /* Re-instate the original arrays in the PointSets. */ ptr1[ ax2 ] = oldx; ptr2[ ax1 ] = oldy; } } /* *++ * Name: c astRebin f AST_REBIN * Purpose: * Rebin a region of a data grid. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astRebin( AstMapping *this, double wlim, int ndim_in, c const int lbnd_in[], const int ubnd_in[], c const in[], const in_var[], c int spread, const double params[], int flags, c double tol, int maxpix, c badval, int ndim_out, c const int lbnd_out[], const int ubnd_out[], c const int lbnd[], const int ubnd[], c out[], out_var[] ); f CALL AST_REBIN( THIS, WLIM, NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, f SPREAD, PARAMS, FLAGS, f TOL, MAXPIX, BADVAL, f NDIM_OUT, LBND_OUT, UBND_OUT, f LBND, UBND, OUT, OUT_VAR, STATUS ) * Class Membership: * Mapping method. * Description: * This is a set of functions for rebinning gridded data (e.g. an * image) under the control of a geometrical transformation, which * is specified by a Mapping. The functions operate on a pair of * data grids (input and output), each of which may have any number * of dimensions. Rebinning may be restricted to a specified * region of the input grid. An associated grid of error estimates * associated with the input data may also be supplied (in the form * of variance values), so as to produce error estimates for the * rebined output data. Propagation of missing data (bad pixels) * is supported. * * Note, if you will be rebining a sequence of input arrays and then * co-adding them into a single array, the alternative c astRebinSeq functions f AST_REBINSEQ routines * will in general be more efficient. * * You should use a rebinning function which matches the numerical * type of the data you are processing by replacing in c the generic function name astRebin by an appropriate 1- or f the generic function name AST_REBIN by an appropriate 1- or * 2-character type code. For example, if you are rebinning data c with type "float", you should use the function astRebinF (see f with type REAL, you should use the function AST_REBINR (see * the "Data Type Codes" section below for the codes appropriate to * other numerical types). * * Rebinning of the grid of input data is performed by transforming * the coordinates of the centre of each input grid element (or pixel) * into the coordinate system of the output grid. The input pixel * value is then divided up and assigned to the output pixels in the * neighbourhood of the central output coordinates. A choice of * schemes are provided for determining how each input pixel value is * divided up between the output pixels. In general, each output pixel * may be assigned values from more than one input pixel. All * contributions to a given output pixel are summed to produce the * final output pixel value. Output pixels can be set to the supplied * bad value if they receive contributions from an insufficient number * of input pixels. This is controlled by the c "wlim" parameter. f WLIM argument. * * Input pixel coordinates are transformed into the coordinate * system of the output grid using the forward transformation of the * Mapping which is supplied. This means that geometrical features * in the input data are subjected to the Mapping's forward * transformation as they are transferred from the input to the * output grid. * * In practice, transforming the coordinates of every pixel of a * large data grid can be time-consuming, especially if the Mapping * involves complicated functions, such as sky projections. To * improve performance, it is therefore possible to approximate * non-linear Mappings by a set of linear transformations which are * applied piece-wise to separate sub-regions of the data. This * approximation process is applied automatically by an adaptive * algorithm, under control of an accuracy criterion which * expresses the maximum tolerable geometrical distortion which may * be introduced, as a fraction of a pixel. * * This algorithm first attempts to approximate the Mapping with a * linear transformation applied over the whole region of the * input grid which is being used. If this proves to be * insufficiently accurate, the input region is sub-divided into * two along its largest dimension and the process is repeated * within each of the resulting sub-regions. This process of * sub-division continues until a sufficiently good linear * approximation is found, or the region to which it is being * applied becomes too small (in which case the original Mapping is * used directly). * Parameters: c this f THIS = INTEGER (Given) * Pointer to a Mapping, whose forward transformation will be * used to transform the coordinates of pixels in the input * grid into the coordinate system of the output grid. * * The number of input coordinates used by this Mapping (as * given by its Nin attribute) should match the number of input c grid dimensions given by the value of "ndim_in" f grid dimensions given by the value of NDIM_IN * below. Similarly, the number of output coordinates (Nout * attribute) should match the number of output grid dimensions c given by "ndim_out". f given by NDIM_OUT. c wlim f WLIM = DOUBLE PRECISION (Given) * Gives the required number of input pixel values which must contribute * to an output pixel in order for the output pixel value to be * considered valid. If the sum of the input pixel weights contributing * to an output pixel is less than the supplied c "wlim" f WLIM * value, then the output pixel value is returned set to the * supplied bad value. c ndim_in f NDIM_IN = INTEGER (Given) * The number of dimensions in the input grid. This should be at * least one. c lbnd_in f LBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c ubnd_in f UBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd_in" and "ubnd_in" together define the shape f Note that LBND_IN and UBND_IN together define the shape * and size of the input grid, its extent along a particular c (j'th) dimension being ubnd_in[j]-lbnd_in[j]+1 (assuming the c index "j" to be zero-based). They also define f (J'th) dimension being UBND_IN(J)-LBND_IN(J)+1. They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. c in f IN( * ) = (Given) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * input grid, containing the input data to be rebined. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if c you are using astRebinF, the type of each array element c should be "float"). f you are using AST_REBINR, the type of each array element f should be REAL). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c in_var f IN_VAR( * ) = (Given) c An optional pointer to a second array with the same size and c type as the "in" array. If given, this should contain a set c of non-negative values which represent estimates of the c statistical variance associated with each element of the "in" c array. If this array is supplied (together with the c corresponding "out_var" array), then estimates of the c variance of the rebined output data will be calculated. c c If no input variance estimates are being provided, a NULL c pointer should be given. f An optional second array with the same size and type as the f IN array. If the AST__USEVAR flag is set via the FLAGS f argument (below), this array should contain a set of f non-negative values which represent estimates of the f statistical variance associated with each element of the IN f array. Estimates of the variance of the rebined output data f will then be calculated. f f If the AST__USEVAR flag is not set, no input variance f estimates are required and this array will not be used. A f dummy (e.g. one-element) array may then be supplied. c spread f SPREAD = INTEGER (Given) c This parameter specifies the scheme to be used for dividing f This argument specifies the scheme to be used for dividing * each input data value up amongst the corresponding output pixels. * It may be used to select * from a set of pre-defined schemes by supplying one of the * values described in the "Pixel Spreading Schemes" * section below. If a value of zero is supplied, then the * default linear spreading scheme is used (equivalent to * supplying the value AST__LINEAR). c params f PARAMS( * ) = DOUBLE PRECISION (Given) c An optional pointer to an array of double which should contain f An optional array which should contain * any additional parameter values required by the pixel * spreading scheme. If such parameters are required, this * will be noted in the "Pixel Spreading Schemes" * section below. * c If no additional parameters are required, this array is not c used and a NULL pointer may be given. f If no additional parameters are required, this array is not f used. A dummy (e.g. one-element) array may then be supplied. c flags f FLAGS = INTEGER (Given) c The bitwise OR of a set of flag values which may be used to f The sum of a set of flag values which may be used to * provide additional control over the rebinning operation. See * the "Control Flags" section below for a description of the * options available. If no flag values are to be set, a value * of zero should be given. c tol f TOL = DOUBLE PRECISION (Given) * The maximum tolerable geometrical distortion which may be * introduced as a result of approximating non-linear Mappings * by a set of piece-wise linear transformations. This should be * expressed as a displacement in pixels in the output grid's * coordinate system. * * If piece-wise linear approximation is not required, a value * of zero may be given. This will ensure that the Mapping is * used without any approximation, but may increase execution * time. * * If the value is too high, discontinuities between the linear * approximations used in adjacent panel will be higher, and may * cause the edges of the panel to be visible when viewing the output * image at high contrast. If this is a problem, reduce the * tolerance value used. c maxpix f MAXPIX = INTEGER (Given) * A value which specifies an initial scale size (in pixels) for * the adaptive algorithm which approximates non-linear Mappings * with piece-wise linear transformations. Normally, this should * be a large value (larger than any dimension of the region of * the input grid being used). In this case, a first attempt to * approximate the Mapping by a linear transformation will be * made over the entire input region. * * If a smaller value is used, the input region will first be c divided into sub-regions whose size does not exceed "maxpix" f divided into sub-regions whose size does not exceed MAXPIX * pixels in any dimension. Only at this point will attempts at * approximation commence. * * This value may occasionally be useful in preventing false * convergence of the adaptive algorithm in cases where the * Mapping appears approximately linear on large scales, but has * irregularities (e.g. holes) on smaller scales. A value of, * say, 50 to 100 pixels can also be employed as a safeguard in * general-purpose software, since the effect on performance is * minimal. * * If too small a value is given, it will have the effect of * inhibiting linear approximation altogether (equivalent to c setting "tol" to zero). Although this may degrade f setting TOL to zero). Although this may degrade * performance, accurate results will still be obtained. c badval f BADVAL = (Given) * This argument should have the same type as the elements of c the "in" array. It specifies the value used to flag missing f the IN array. It specifies the value used to flag missing * data (bad pixels) in the input and output arrays. * c If the AST__USEBAD flag is set via the "flags" parameter, f If the AST__USEBAD flag is set via the FLAGS argument, c then this value is used to test for bad pixels in the "in" c (and "in_var") array(s). f then this value is used to test for bad pixels in the IN f (and IN_VAR) array(s). * * In all cases, this value is also used to flag any output c elements in the "out" (and "out_var") array(s) for which f elements in the OUT (and OUT_VAR) array(s) for which * rebined values could not be obtained (see the "Propagation * of Missing Data" section below for details of the * circumstances under which this may occur). c ndim_out f NDIM_OUT = INTEGER (Given) * The number of dimensions in the output grid. This should be * at least one. It need not necessarily be equal to the number * of dimensions in the input grid. c lbnd_out f LBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the first pixel * in the output grid along each dimension. c ubnd_out f UBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the last pixel in * the output grid along each dimension. * c Note that "lbnd_out" and "ubnd_out" together define the f Note that LBND_OUT and UBND_OUT together define the * shape, size and coordinate system of the output grid in the c same way as "lbnd_in" and "ubnd_in" define the shape, size f same way as LBND_IN and UBND_IN define the shape, size * and coordinate system of the input grid. c lbnd f LBND( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the first pixel in the region * of the input grid which is to be included in the rebined output * array. c ubnd f UBND( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the last pixel in the region of * the input grid which is to be included in the rebined output * array. * c Note that "lbnd" and "ubnd" together define the shape and f Note that LBND and UBND together define the shape and * position of a (hyper-)rectangular region of the input grid * which is to be included in the rebined output array. This region * should lie wholly within the extent of the input grid (as c defined by the "lbnd_in" and "ubnd_in" arrays). Regions of f defined by the LBND_IN and UBND_IN arrays). Regions of * the input grid lying outside this region will not be used. c out f OUT( * ) = (Returned) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * output grid, in which the rebined data values will be * returned. The numerical type of this array should match that c of the "in" array, and the data storage order should be such f of the IN array, and the data storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c out_var f OUT_VAR( * ) = (Returned) c An optional pointer to an array with the same type and size c as the "out" array. If given, this array will be used to c return variance estimates for the rebined data values. This c array will only be used if the "in_var" array has also been c supplied. f An optional array with the same type and size as the OUT f array. If the AST__USEVAR flag is set via the FLAGS argument, f this array will be used to return variance estimates for the f rebined data values. * * The output variance values will be calculated on the * assumption that errors on the input data values are * statistically independent and that their variance estimates * may simply be summed (with appropriate weighting factors) * when several input pixels contribute to an output data * value. If this assumption is not valid, then the output error * estimates may be biased. In addition, note that the * statistical errors on neighbouring output data values (as * well as the estimates of those errors) may often be * correlated, even if the above assumption about the input data * is correct, because of the pixel spreading schemes * employed. * c If no output variance estimates are required, a NULL pointer c should be given. f If the AST__USEVAR flag is not set, no output variance f estimates will be calculated and this array will not be f used. A dummy (e.g. one-element) array may then be supplied. f STATUS = INTEGER (Given and Returned) f The global status. * Data Type Codes: * To select the appropriate rebinning function, you should c replace in the generic function name astRebin with a f replace in the generic function name AST_REBIN with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: c - D: double c - F: float c - I: int c - B: byte (signed char) c - UB: unsigned byte (unsigned char) f - D: DOUBLE PRECISION f - R: REAL f - I: INTEGER f - B: BYTE (treated as signed) f - UB: BYTE (treated as unsigned) * c For example, astRebinD would be used to process "double" c data, while astRebinI would be used to process "int" c data, etc. f For example, AST_REBIND would be used to process DOUBLE f PRECISION data, while AST_REBINI would be used to process f integer data (stored in an INTEGER array), etc. * * Note that, unlike c astResample, the astRebin f AST_RESAMPLE, the AST_REBIN * set of functions does not yet support unsigned integer data types * or integers of different sizes. * Pixel Spreading Schemes: * The pixel spreading scheme specifies the Point Spread Function (PSF) * applied to each input pixel value as it is copied into the output * array. It can be thought of as the inverse of the sub-pixel * interpolation schemes used by the c astResample f AST_RESAMPLE * group of functions. That is, in a sub-pixel interpolation scheme the * kernel specifies the weight to assign to each input pixel when * forming the weighted mean of the input pixels, whereas the kernel in a * pixel spreading scheme specifies the fraction of the input data value * which is to be assigned to each output pixel. As for interpolation, the * choice of suitable pixel spreading scheme involves stricking a balance * between schemes which tend to degrade sharp features in the data by * smoothing them, and those which attempt to preserve sharp features but * which often tend to introduce unwanted artifacts. See the c astResample f AST_RESAMPLE * documentation for further discussion. * * The binning algorithm used has the ability to introduce artifacts * not seen when using a resampling algorithm. Particularly, when * viewing the output image at high contrast, systems of curves lines * covering the entire image may be visible. These are caused by a * beating effect between the input pixel positions and the output pixels * position, and their nature and strength depend critically upon the * nature of the Mapping and the spreading function being used. In * general, the nearest neighbour spreading function demonstrates this * effect more clearly than the other functions, and for this reason * should be used with caution. * * The following values (defined in the c "ast.h" header file) f AST_PAR include file) * may be assigned to the c "spread" f SPREAD * parameter. See the c astResample f AST_RESAMPLE * documentation for details of these schemes including the use of the c "fspread" and "params" parameters: f FSPREAD and PARAMS arguments: * * - AST__NEAREST * - AST__LINEAR * - AST__SINC * - AST__SINCSINC * - AST__SINCCOS * - AST__SINCGAUSS * - AST__SOMBCOS * * In addition, the following schemes can be used with f AST_REBIN but not with AST_RESAMPLE: c astRebin but not with astResample: * * - AST__GAUSS: This scheme uses a kernel of the form exp(-k*x*x), with k * a positive constant determined by the full-width at half-maximum (FWHM). * The FWHM should be supplied in units of output pixels by means of the c "params[1]" f PARAMS(2) * value and should be at least 0.1. The c "params[0]" f PARAMS(1) * value should be used to specify at what point the Gaussian is truncated * to zero. This should be given as a number of output pixels on either * side of the central output point in each dimension (the nearest integer * value is used). * Control Flags: c The following flags are defined in the "ast.h" header file and f The following flags are defined in the AST_PAR include file and * may be used to provide additional control over the rebinning * process. Having selected a set of flags, you should supply the c bitwise OR of their values via the "flags" parameter: f sum of their values via the FLAGS argument: * * - AST__USEBAD: Indicates that there may be bad pixels in the * input array(s) which must be recognised by comparing with the c value given for "badval" and propagated to the output array(s). f value given for BADVAL and propagated to the output array(s). * If this flag is not set, all input values are treated literally c and the "badval" value is only used for flagging output array f and the BADVAL value is only used for flagging output array * values. f - AST__USEVAR: Indicates that variance information should be f processed in order to provide estimates of the statistical error f associated with the rebined values. If this flag is not set, f no variance processing will occur and the IN_VAR and OUT_VAR f arrays will not be used. (Note that this flag is only available f in the Fortran interface to AST.) * Propagation of Missing Data: * Instances of missing data (bad pixels) in the output grid are c identified by occurrences of the "badval" value in the "out" f identified by occurrences of the BADVAL value in the OUT * array. These are produced if the sum of the weights of the * contributing input pixels is less than c "wlim". f WLIM. * * An input pixel is considered bad (and is consequently ignored) if * its c data value is equal to "badval" and the AST__USEBAD flag is c set via the "flags" parameter. f data value is equal to BADVAL and the AST__USEBAD flag is f set via the FLAGS argument. * * In addition, associated output variance estimates (if c calculated) may be declared bad and flagged with the "badval" c value in the "out_var" array for similar reasons. f calculated) may be declared bad and flagged with the BADVAL f value in the OUT_VAR array for similar reasons. *-- */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_REBIN(X,Xtype,IntType) \ static void Rebin##X( AstMapping *this, double wlim, int ndim_in, \ const int lbnd_in[], const int ubnd_in[], \ const Xtype in[], const Xtype in_var[], \ int spread, const double params[], int flags, \ double tol, int maxpix, Xtype badval, \ int ndim_out, const int lbnd_out[], \ const int ubnd_out[], const int lbnd[], \ const int ubnd[], Xtype out[], Xtype out_var[], int *status ) { \ \ /* Local Variables: */ \ astDECLARE_GLOBALS /* Thread-specific data */ \ const char *badflag; /* Name of illegal flag */ \ AstMapping *simple; /* Pointer to simplified Mapping */ \ Xtype *d; /* Pointer to next output data value */ \ Xtype *v; /* Pointer to next output variance value */ \ double *w; /* Pointer to next weight value */ \ double *work; /* Pointer to weight array */ \ int idim; /* Loop counter for coordinate dimensions */ \ int ipix_out; /* Index into output array */ \ int nin; /* Number of Mapping input coordinates */ \ int nout; /* Number of Mapping output coordinates */ \ int npix; /* Number of pixels in input region */ \ int npix_out; /* Number of pixels in output array */ \ int64_t mpix; /* Number of pixels for testing */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to a structure holding thread-specific global data values */ \ astGET_GLOBALS(this); \ \ /* Obtain values for the Nin and Nout attributes of the Mapping. */ \ nin = astGetNin( this ); \ nout = astGetNout( this ); \ \ /* If OK, check that the number of input grid dimensions matches the \ number required by the Mapping and is at least 1. Report an error \ if necessary. */ \ if ( astOK && ( ( ndim_in != nin ) || ( ndim_in < 1 ) ) ) { \ astError( AST__NGDIN, "astRebin"#X"(%s): Bad number of input grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_in ); \ if ( ndim_in != nin ) { \ astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ "to specify an input position.", status, \ astGetClass( this ), nin, ( nin == 1 ) ? "" : "s" ); \ } \ } \ \ /* If OK, also check that the number of output grid dimensions matches \ the number required by the Mapping and is at least 1. Report an \ error if necessary. */ \ if ( astOK && ( ( ndim_out != nout ) || ( ndim_out < 1 ) ) ) { \ astError( AST__NGDIN, "astRebin"#X"(%s): Bad number of output grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_out ); \ if ( ndim_out != nout ) { \ astError( AST__NGDIN, "The %s given generates %s%d coordinate " \ "value%s for each output position.", status, astGetClass( this ), \ ( nout < ndim_out ) ? "only " : "", nout, \ ( nout == 1 ) ? "" : "s" ); \ } \ } \ \ /* Check that the lower and upper bounds of the input grid are \ consistent. Report an error if any pair is not. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ if ( lbnd_in[ idim ] > ubnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebin"#X"(%s): Lower bound of " \ "input grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_in[ idim ], ubnd_in[ idim ] ); \ astError( AST__GBDIN, "Error in input dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the input. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebin"#X"(%s): Supplied input array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Check that the positional accuracy tolerance supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( tol < 0.0 ) ) { \ astError( AST__PATIN, "astRebin"#X"(%s): Invalid positional " \ "accuracy tolerance (%.*g pixel).", status, \ astGetClass( this ), DBL_DIG, tol ); \ astError( AST__PATIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the initial scale size in pixels supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( maxpix < 0 ) ) { \ astError( AST__SSPIN, "astRebin"#X"(%s): Invalid initial scale " \ "size in pixels (%d).", status, astGetClass( this ), maxpix ); \ astError( AST__SSPIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the lower and upper bounds of the output grid are \ consistent. Report an error if any pair is not. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_out; idim++ ) { \ if ( lbnd_out[ idim ] > ubnd_out[ idim ] ) { \ astError( AST__GBDIN, "astRebin"#X"(%s): Lower bound of " \ "output grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_out[ idim ], ubnd_out[ idim ] ); \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the output. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebin"#X"(%s): Supplied output array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Similarly check the bounds of the input region. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_out; idim++ ) { \ if ( lbnd[ idim ] > ubnd[ idim ] ) { \ astError( AST__GBDIN, "astRebin"#X"(%s): Lower bound of " \ "input region (%d) exceeds corresponding upper " \ "bound (%d).", status, astGetClass( this ), \ lbnd[ idim ], ubnd[ idim ] ); \ \ /* Also check that the input region lies wholly within the input \ grid. */ \ } else if ( lbnd[ idim ] < lbnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebin"#X"(%s): Lower bound of " \ "input region (%d) is less than corresponding " \ "bound of input grid (%d).", status, astGetClass( this ), \ lbnd[ idim ], lbnd_in[ idim ] ); \ } else if ( ubnd[ idim ] > ubnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebin"#X"(%s): Upper bound of " \ "input region (%d) exceeds corresponding " \ "bound of input grid (%d).", status, astGetClass( this ), \ ubnd[ idim ], ubnd_in[ idim ] ); \ } else { \ mpix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* Say which dimension produced the error. */ \ if ( !astOK ) { \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the input region. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebin"#X"(%s): Supplied input region " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* If OK, loop to determine how many input pixels are to be binned. */ \ simple = NULL; \ npix = 1; \ npix_out = 1; \ unsimplified_mapping = this; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ npix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* Loop to determine how many pixels the output array contains. */ \ for ( idim = 0; idim < ndim_out; idim++ ) { \ npix_out *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ } \ \ /* If there are sufficient pixels to make it worthwhile, simplify the \ Mapping supplied to improve performance. Otherwise, just clone the \ Mapping pointer. Note we have already saved a pointer to the original \ Mapping so that lower-level functions can use it if they need to report \ an error. */ \ if ( npix > 1024 ) { \ simple = astSimplify( this ); \ } else { \ simple = astClone( this ); \ } \ } \ \ /* Report an error if the forward transformation of this simplified \ Mapping is not defined. */ \ if ( !astGetTranForward( simple ) && astOK ) { \ astError( AST__TRNND, "astRebin"#X"(%s): An forward coordinate " \ "transformation is not defined by the %s supplied.", status, \ astGetClass( unsimplified_mapping ), \ astGetClass( unsimplified_mapping ) ); \ } \ \ /* Report an error if any illegal flags were supplied. */ \ if( flags & AST__REBININIT ) { \ badflag = "AST__REBININIT"; \ } else if( flags & AST__REBINEND ) { \ badflag = "AST__REBINEND"; \ } else if( flags & AST__GENVAR ) { \ badflag = "AST__GENVAR"; \ } else if( flags & AST__DISVAR ) { \ badflag = "AST__DISVAR"; \ } else if( flags & AST__VARWGT ) { \ badflag = "AST__VARWGT"; \ } else if( flags & AST__NONORM ) { \ badflag = "AST__NONORM"; \ } else if( flags & AST__CONSERVEFLUX ) { \ badflag = "AST__CONSERVEFLUX"; \ } else if( flags & ~( AST__USEBAD + AST__USEVAR ) ) { \ badflag = "unknown"; \ } else { \ badflag = NULL; \ } \ if ( badflag && astOK ) { \ astError( AST__BADFLG, "astRebin"#X"(%s): An illegal flag (%s) " \ "was included in the 'flags' argument.", status, \ astGetClass( unsimplified_mapping ), badflag ); \ } \ \ /* If required, allocate work array to hold the sum of the weights \ contributing to each output pixel, and initialise it to zero. */ \ if( wlim > 0.0 ) { \ work = astMalloc( sizeof( double )*(size_t) npix_out ); \ if( work ) { \ w = work; \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++ ) *(w++) = 0.0; \ } \ } else { \ work = NULL; \ } \ \ /* Initialise the output arrays to hold zeros. */ \ d = out; \ if( out_var ) { \ v = out_var; \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++, v++ ) { \ *d = 0; \ *v = 0; \ } \ } else { \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++ ) { \ *d = 0; \ } \ } \ \ /* Perform the rebinning. Note that we pass all gridded data, the \ spread function and the bad pixel value by means of pointer \ types that obscure the underlying data type. This is to avoid \ having to replicate functions unnecessarily for each data \ type. However, we also pass an argument that identifies the data \ type we have obscured. */ \ if( RebinAdaptively( simple, ndim_in, lbnd_in, ubnd_in, \ (const void *) in, (const void *) in_var, \ TYPE_##X, spread, \ params, flags, tol, maxpix, \ (const void *) &badval, \ ndim_out, lbnd_out, ubnd_out, \ lbnd, ubnd, npix_out, \ (void *) out, (void *) out_var, work, \ NULL, status ) && astOK ) { \ astError( AST__CNFLX, "astRebin"#X"(%s): Flux conservation was " \ "requested but could not be performed because the " \ "forward transformation of the supplied Mapping " \ "is too non-linear.", status, astGetClass( this ) ); \ } \ \ /* If required set output pixels bad if they have a total weight less \ than "wlim". */ \ if( work ) { \ w = work; \ d = out; \ if( out_var ) { \ v = out_var; \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++, w++, v++ ) { \ if( fabs( *w ) < wlim ) { \ *d = badval; \ *v = badval; \ } \ } \ } else { \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++, w++ ) { \ if( fabs( *w ) < wlim ) *d = badval; \ } \ } \ \ /* Free the work array. */ \ work = astFree( work ); \ } \ \ /* Annul the pointer to the simplified/cloned Mapping. */ \ simple = astAnnul( simple ); \ \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_REBIN(LD,long double,0) #endif MAKE_REBIN(D,double,0) MAKE_REBIN(F,float,0) MAKE_REBIN(I,int,1) MAKE_REBIN(B,signed char,1) MAKE_REBIN(UB,unsigned char,1) /* Undefine the macro. */ #undef MAKE_REBIN static int RebinAdaptively( AstMapping *this, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, DataType type, int spread, const double *params, int flags, double tol, int maxpix, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, int npix_out, void *out, void *out_var, double *work, int64_t *nused, int *status ){ /* * Name: * RebinAdaptively * Purpose: * Rebin a section of a data grid adaptively. * Type: * Private function. * Synopsis: * #include "mapping.h" * int RebinAdaptively( AstMapping *this, int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const void *in, const void *in_var, * DataType type, int spread, * const double *params, int flags, double tol, * int maxpix, const void *badval_ptr, * int ndim_out, const int *lbnd_out, * const int *ubnd_out, const int *lbnd, * const int *ubnd, int npix_out, void *out, * void *out_var, double *work, int64_t *nused, * int *status ) * Class Membership: * Mapping member function. * Description: * This function rebins a specified section of a rectangular grid of * data (with any number of dimensions) into another rectangular grid * (with a possibly different number of dimensions). The coordinate * transformation used to convert input pixel coordinates into positions * in the output grid is given by the forward transformation of the * Mapping which is supplied. Any pixel spreading scheme may be specified * for distributing the flux of an input pixel amongst the output * pixels. * * This function is very similar to RebinWithBlocking and RebinSection * which lie below it in the calling hierarchy. However, this function * also attempts to adapt to the Mapping supplied and to sub-divide the * section being rebinned into smaller sections within which a linear * approximation to the Mapping may be used. This reduces the number of * Mapping evaluations, thereby improving efficiency particularly when * complicated Mappings are involved. * Parameters: * this * Pointer to a Mapping, whose forward transformation may be * used to transform the coordinates of pixels in the input * grid into associated positions in the output grid. * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be rebinned (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the rebinned data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * spread * A value selected from a set of pre-defined macros to identify * which pixel spread function should be used. * params * Pointer to an optional array of parameters that may be passed * to the pixel spread algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * flags * The bitwise OR of a set of flag values which provide additional * control over the resampling operation. * tol * The maximum permitted positional error in transforming input * pixel positions into the output grid in order to rebin * it. This should be expressed as a displacement in pixels in * the output grid's coordinate system. If the Mapping's forward * transformation can be approximated by piecewise linear functions * to this accuracy, then such functions may be used instead of the * Mapping in order to improve performance. Otherwise, every input * pixel position will be transformed individually using the Mapping. * * If linear approximation is not required, a "tol" value of * zero may be given. This will ensure that the Mapping is used * without any approximation. * maxpix * A value which specifies the largest scale size on which to * search for non-linearities in the Mapping supplied. This * value should be expressed as a number of pixels in the input * grid. The function will break the input section specified * into smaller sub-sections (if necessary), each no larger than * "maxpix" pixels in any dimension, before it attempts to * approximate the Mapping by a linear function over each * sub-section. * * If the value given is larger than the largest dimension of * the input section (the normal recommendation), the function * will initially search for non-linearity on a scale determined * by the size of the input section. This is almost always * satisfactory. Very occasionally, however, a Mapping may * appear linear on this scale but nevertheless have smaller * irregularities (e.g. "holes") in it. In such cases, "maxpix" * may be set to a suitably smaller value so as to ensure this * non-linearity is not overlooked. Typically, a value of 50 to * 100 pixels might be suitable and should have little effect on * performance. * * If too small a value is given, however, it will have the * effect of preventing linear approximation occurring at all * (equivalent to setting "tol" to zero). Although this may * degrade performance, accurate results will still be obtained. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which rebinned values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the first pixel in the * section of the input data grid which is to be rebinned. * ubnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the last pixel in the * section of the input data grid which is to be rebinned. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the input grid which is to be rebinned. This section * should lie wholly within the extent of the input grid (as defined * by the "lbnd_out" and "ubnd_out" arrays). Regions of the input * grid lying outside this section will be ignored. * npix_out * The number of pixels in the output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * work * An optional pointer to a double array with the same size as * the "out" array. The contents of this array (if supplied) are * incremented by the accumulated weights assigned to each output pixel. * If no accumulated weights are required, a NULL pointer should be * given. * nused * An optional pointer to a int64_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * status * Pointer to the inherited status variable. * Returned Value: * A non-zero value is returned if "flags" included AST__CONSERVEFLUX (i.e. * flux conservation was requested), but the forward transformation of the * supplied Mapping had zero determinant everywhere within the region * being binned (no error is reported if this happens). Zero is returned * otherwise. */ /* Local Variables: */ double *flbnd; /* Array holding floating point lower bounds */ double *fubnd; /* Array holding floating point upper bounds */ double *linear_fit; /* Pointer to array of fit coefficients */ int *hi; /* Pointer to array of section upper bounds */ int *lo; /* Pointer to array of section lower bounds */ int coord_in; /* Loop counter for input coordinates */ int dim; /* Output section dimension size */ int dimx; /* Dimension with maximum section extent */ int divide; /* Sub-divide the output section? */ int i; /* Loop count */ int isLinear; /* Is the transformation linear? */ int mxdim; /* Largest output section dimension size */ int need_fit; /* Do we need to perform a linear fit? */ int npix; /* Number of pixels in output section */ int npoint; /* Number of points for obtaining a fit */ int nvertex; /* Number of vertices of output section */ int result; /* Returned value */ int res1; /* Flux conservation error in 1st section? */ int res2; /* Flux conservation error in 2nd section? */ int toobig; /* Section too big (must sub-divide)? */ int toosmall; /* Section too small to sub-divide? */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ npix = 1; mxdim = 0; dimx = 1; nvertex = 1; /* Loop through the input grid dimensions. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { /* Obtain the extent in each dimension of the input section which is to be rebinned, and calculate the total number of pixels it contains. */ dim = ubnd[ coord_in ] - lbnd[ coord_in ] + 1; npix *= dim; /* Find the maximum dimension size of this input section and note which dimension has this size. */ if ( dim > mxdim ) { mxdim = dim; dimx = coord_in; } /* Calculate how many vertices the output section has. */ nvertex *= 2; } /* Calculate how many sample points will be needed (by the astLinearApprox function) to obtain a linear fit to the Mapping's forward transformation. */ npoint = 1 + 4 * ndim_in + 2 * nvertex; /* If the number of pixels in the input section is not at least 4 times this number, we will probably not save significant time by attempting to obtain a linear fit, so note that the input section is too small. */ toosmall = ( npix < ( 4 * npoint ) ); /* Note if the maximum dimension of the input section exceeds the user-supplied scale factor. */ toobig = ( maxpix < mxdim ); /* Indicate we do not yet have a linear fit. */ linear_fit = NULL; /* Initialise a flag indicating if we need to perform a linear fit. This is always the case if flux conservation was requested. */ need_fit = ( flags & AST__CONSERVEFLUX ); /* If the output section is too small to be worth obtaining a linear fit, or if the accuracy tolerance is zero, we will not sub-divide. This means that the Mapping will be used to transform each pixel's coordinates and no linear approximation will be used. */ if ( toosmall || ( tol == 0.0 ) ) { divide = 0; /* Otherwise, if the largest input section dimension exceeds the scale length given, we will sub-divide. This offers the possibility of obtaining a linear approximation to the Mapping over a reduced range of input coordinates (which will be handled by a recursive invocation of this function). */ } else if ( toobig ) { divide = 1; /* If neither of the above apply, we need to do a fit regardless of whether flux conservation was requested or not. Whether we divide or not will depend on whether the Mapping is linear or not. Assume for the moment that the Mapping is not linear and so we will divide. */ } else { need_fit = 1; divide = 1; } /* If required, attempt to fit a linear approximation to the Mapping's forward transformation over the range of coordinates covered by the input section. We need to temporarily copy the integer bounds into floating point arrays to use astLinearApprox. */ if( need_fit ) { /* Allocate memory for floating point bounds and for the coefficient array */ flbnd = astMalloc( sizeof( double )*(size_t) ndim_in ); fubnd = astMalloc( sizeof( double )*(size_t) ndim_in ); linear_fit = astMalloc( sizeof( double )* (size_t) ( ndim_out*( ndim_in + 1 ) ) ); if( astOK ) { /* Copy the bounds into these arrays, and change them so that they refer to the lower and upper edges of the cell rather than the centre. This is essential if one of the axes is spanned by a single cell, since otherwise the upper and lower bounds would be identical. */ for( i = 0; i < ndim_in; i++ ) { flbnd[ i ] = (double) lbnd[ i ] - 0.5; fubnd[ i ] = (double) ubnd[ i ] + 0.5; } /* Get the linear approximation to the forward transformation. */ isLinear = astLinearApprox( this, flbnd, fubnd, tol, linear_fit ); /* Free the coeff array if the inverse transformation is not linear. */ if( !isLinear ) linear_fit = astFree( linear_fit ); } else { linear_fit = astFree( linear_fit ); } /* Free resources */ flbnd = astFree( flbnd ); fubnd = astFree( fubnd ); /* If a linear fit was obtained, we will use it and therefore do not wish to sub-divide further. Otherwise, we sub-divide (unless the section is too small or too big as determined earlier) in the hope that this may result in a linear fit next time. */ if( linear_fit ) divide = 0; } /* If no sub-division is required, perform rebinning (in a memory-efficient manner, since the section we are rebinning might still be very large). This will use the linear fit, if obtained above. */ if ( astOK ) { if ( !divide ) { result = RebinWithBlocking( this, linear_fit, ndim_in, lbnd_in, ubnd_in, in, in_var, type, spread, params, flags, badval_ptr, ndim_out, lbnd_out, ubnd_out, lbnd, ubnd, npix_out, out, out_var, work, nused, status ); /* Otherwise, allocate workspace to perform the sub-division. */ } else { lo = astMalloc( sizeof( int ) * (size_t) ndim_in ); hi = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Initialise the bounds of a new input section to match the original input section. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { lo[ coord_in ] = lbnd[ coord_in ]; hi[ coord_in ] = ubnd[ coord_in ]; } /* Replace the upper bound of the section's largest dimension with the mid-point of the section along this dimension, rounded downwards. */ hi[ dimx ] = (int) floor( 0.5 * (double) ( lbnd[ dimx ] + ubnd[ dimx ] ) ); /* Rebin the resulting smaller section using a recursive invocation of this function. */ res1 = RebinAdaptively( this, ndim_in, lbnd_in, ubnd_in, in, in_var, type, spread, params, flags, tol, maxpix, badval_ptr, ndim_out, lbnd_out, ubnd_out, lo, hi, npix_out, out, out_var, work, nused, status ); /* Now set up a second section which covers the remaining half of the original input section. */ lo[ dimx ] = hi[ dimx ] + 1; hi[ dimx ] = ubnd[ dimx ]; /* If this section contains pixels, resample it in the same way, summing the returned values. */ if ( lo[ dimx ] <= hi[ dimx ] ) { res2 = RebinAdaptively( this, ndim_in, lbnd_in, ubnd_in, in, in_var, type, spread, params, flags, tol, maxpix, badval_ptr, ndim_out, lbnd_out, ubnd_out, lo, hi, npix_out, out, out_var, work, nused, status ); } else { res2 = 0; } /* If neither section could be rebinned because of an indeterminant mapping, return a result indicating this. */ result = ( res1 && res2 ); } /* Free the workspace. */ lo = astFree( lo ); hi = astFree( hi ); } } /* If coefficients for a linear fit were obtained, then free the space they occupy. */ if ( linear_fit ) linear_fit = astFree( linear_fit ); /* Retyurn a flag indicating if no part of the array could be binned because of an indeterminate Mapping. */ return result; } static void RebinSection( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, double infac, DataType type, int spread, const double *params, int flags, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, int npix_out, void *out, void *out_var, double *work, int64_t *nused, int *status ) { /* * Name: * RebinSection * Purpose: * Rebin a section of a data grid. * Type: * Private function. * Synopsis: * #include "mapping.h" * void RebinSection( AstMapping *this, const double *linear_fit, * int ndim_in, const int *lbnd_in, const int *ubnd_in, * const void *in, const void *in_var, double infac, * DataType type, int spread, const double *params, * int flags, const void *badval_ptr, int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const int *lbnd, const int *ubnd, int npix_out, * void *out, void *out_var, double *work, * int64_t *nused, int *status ) * Class Membership: * Mapping member function. * Description: * This function rebins a specified section of a rectangular grid of * data (with any number of dimensions) into another rectangular grid * (with a possibly different number of dimensions). The coordinate * transformation used to convert input pixel coordinates into positions * in the output grid is given by the forward transformation of the * Mapping which is supplied or, alternatively, by a linear approximation * fitted to a Mapping's forward transformation. Any pixel spreading scheme * may be specified for distributing the flux of an input pixel amongst * the output pixels. * Parameters: * this * Pointer to a Mapping, whose forward transformation may be * used to transform the coordinates of pixels in the input * grid into associated positions in the output grid. * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's forward coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * forward transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be rebinned (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the rebinned data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * infac * A factor by which to multiply the input data values before use. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * spread * A value selected from a set of pre-defined macros to identify * which pixel spread function should be used. * params * Pointer to an optional array of parameters that may be passed * to the pixel spread algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * flags * The bitwise OR of a set of flag values which provide additional * control over the resampling operation. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which rebinned values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the first pixel in the * section of the input data grid which is to be rebinned. * ubnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the last pixel in the * section of the input data grid which is to be rebinned. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the input grid which is to be rebinned. This section * should lie wholly within the extent of the input grid (as defined * by the "lbnd_out" and "ubnd_out" arrays). Regions of the input * grid lying outside this section will be ignored. * npix_out * The number of pixels in the output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * work * An optional pointer to a double array with the same size as * the "out" array. The contents of this array (if supplied) are * incremented by the accumulated weights assigned to each output pixel. * If no accumulated weights are required, a NULL pointer should be * given. * nused * An optional pointer to a int64_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * Notes: * - This function does not take steps to limit memory usage if the * grids supplied are large. To resample large grids in a more * memory-efficient way, the ResampleWithBlocking function should * be used. */ /* Local Variables: */ astDECLARE_GLOBALS /* Thread-specific data */ AstPointSet *pset_in; /* Input PointSet for transformation */ AstPointSet *pset_out; /* Output PointSet for transformation */ const double *grad; /* Pointer to gradient matrix of linear fit */ const double *zero; /* Pointer to zero point array of fit */ double **ptr_in; /* Pointer to input PointSet coordinates */ double **ptr_out; /* Pointer to output PointSet coordinates */ double *accum; /* Pointer to array of accumulated sums */ double x1; /* Interim x coordinate value */ double xx1; /* Initial x coordinate value */ double y1; /* Interim y coordinate value */ double yy1; /* Initial y coordinate value */ int *dim; /* Pointer to array of output pixel indices */ int *offset; /* Pointer to array of output pixel offsets */ int *stride; /* Pointer to array of output grid strides */ int coord_in; /* Loop counter for input dimensions */ int coord_out; /* Loop counter for output dimensions */ int done; /* All pixel indices done? */ int i1; /* Interim offset into "accum" array */ int i2; /* Final offset into "accum" array */ int idim; /* Loop counter for dimensions */ int ix; /* Loop counter for output x coordinate */ int iy; /* Loop counter for output y coordinate */ int neighb; /* Number of neighbouring pixels */ int npoint; /* Number of output points (pixels) */ int off1; /* Interim pixel offset into output array */ int off2; /* Interim pixel offset into output array */ int off; /* Final pixel offset into output array */ int point; /* Counter for output points (pixels ) */ int s; /* Temporary variable for strides */ const double *par; /* Pointer to parameter array */ double fwhm; /* Full width half max. of gaussian */ double lpar[ 1 ]; /* Local parameter array */ void (* kernel)( double, const double [], int, double *, int * ); /* Kernel fn. */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to a structure holding thread-specific global data values */ astGET_GLOBALS(this); /* Further initialisation. */ pset_in = NULL; ptr_in = NULL; ptr_out = NULL; pset_out = NULL; neighb = 0; kernel = NULL; /* Calculate the number of input points, as given by the product of the input grid dimensions. */ for ( npoint = 1, coord_in = 0; coord_in < ndim_in; coord_in++ ) { npoint *= ubnd[ coord_in ] - lbnd[ coord_in ] + 1; } /* Allocate workspace. */ offset = astMalloc( sizeof( int ) * (size_t) npoint ); stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Calculate the stride for each input grid dimension. */ off = 0; s = 1; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { stride[ coord_in ] = s; s *= ubnd_in[ coord_in ] - lbnd_in[ coord_in ] + 1; } /* A linear fit to the Mapping is available. */ /* ========================================= */ if ( linear_fit ) { /* If a linear fit to the Mapping has been provided, then obtain pointers to the array of gradients and zero-points comprising the fit. */ grad = linear_fit + ndim_out; zero = linear_fit; /* Create a PointSet to hold the output grid coordinates and obtain an array of pointers to its coordinate data. */ pset_out = astPointSet( npoint, ndim_out, "", status ); ptr_out = astGetPoints( pset_out ); if ( astOK ) { /* Initialise the count of input points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ( ndim_in == 1 ) && ( ndim_out == 1 ) ) { /* Loop through the pixels of the input grid and transform their x coordinates into the output grid's coordinate system using the linear fit supplied. Store the results in the PointSet created above. */ off = lbnd[ 0 ] - lbnd_in[ 0 ]; xx1 = zero[ 0 ] + grad[ 0 ] * (double) lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = xx1; xx1 += grad[ 0 ]; offset[ point++ ] = off++; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ( ndim_in == 2 ) && ( ndim_out == 2 ) ) { /* Loop through the range of y coordinates in the input grid and calculate interim values of the output coordinates using the linear fit supplied. */ x1 = zero[ 0 ] + grad[ 1 ] * (double) ( lbnd[ 1 ] - 1 ); y1 = zero[ 1 ] + grad[ 3 ] * (double) ( lbnd[ 1 ] - 1 ); off1 = stride[ 1 ] * ( lbnd[ 1 ] - lbnd_in[ 1 ] - 1 ) - lbnd_in[ 0 ]; for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { x1 += grad[ 1 ]; y1 += grad[ 3 ]; /* Also calculate an interim pixel offset into the input array. */ off1 += stride[ 1 ]; /* Now loop through the range of input x coordinates and calculate the final values of the input coordinates, storing the results in the PointSet created above. */ xx1 = x1 + grad[ 0 ] * (double) lbnd[ 0 ]; yy1 = y1 + grad[ 2 ] * (double) lbnd[ 0 ]; off = off1 + lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = xx1; xx1 += grad[ 0 ]; ptr_out[ 1 ][ point ] = yy1; yy1 += grad[ 2 ]; /* Also calculate final pixel offsets into the input array. */ offset[ point++ ] = off++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ accum = astMalloc( sizeof( double ) * (size_t) ( ndim_in * ndim_out ) ); dim = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Initialise an array of pixel indices for the input grid which refer to the first pixel which we will rebin. Also calculate the offset of this pixel within the input array. */ off = 0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { dim[ coord_in ] = lbnd[ coord_in ]; off += stride[ coord_in ] * ( dim[ coord_in ] - lbnd_in[ coord_in ] ); } /* To calculate each output grid coordinate we must perform a matrix multiply on the input grid coordinates (using the gradient matrix) and then add the zero points. However, since we will usually only be altering one input coordinate at a time (the least significant), we can avoid the full matrix multiply by accumulating partial sums for the most significant input coordinates and only altering those sums which need to change each time. The zero points never change, so we first fill the "most significant" end of the "accum" array with these. */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { accum[ ( coord_out + 1 ) * ndim_in - 1 ] = zero[ coord_out ]; } coord_in = ndim_in - 1; /* Now loop to process each input pixel. */ for ( done = 0; !done; point++ ) { /* To generate the output coordinate that corresponds to the current input pixel, we work down from the most significant dimension whose index has changed since the previous pixel we considered (given by "coord_in"). For each affected dimension, we accumulate in "accum" the matrix sum (including the zero point) for that dimension and all higher input dimensions. We must accumulate a separate set of sums for each output coordinate we wish to produce. (Note that for the first pixel we process, all dimensions are considered "changed", so we start by initialising the whole "accum" array.) */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { /* ptr_out[ coord_out ][ point ] = zero[ coord_out ]; for ( idim = 0; idim < ndim_in; idim++ ) { ptr_out[ coord_out ][ point ] += grad[ idim + coord_out*ndim_in ] * dim[ idim ]; } */ i1 = coord_out * ndim_in; for ( idim = coord_in; idim >= 1; idim-- ) { i2 = i1 + idim; accum[ i2 - 1 ] = accum[ i2 ] + dim[ idim ] * grad[ i2 ]; } /* The output coordinate for each dimension is given by the accumulated sum for input dimension zero (giving the sum over all input dimensions). We do not store this in the "accum" array, but assign the result directly to the coordinate array of the PointSet created earlier. */ ptr_out[ coord_out ][ point ] = accum[ i1 ] + dim[ 0 ] * grad[ i1 ]; } /* Store the offset of the current pixel in the input array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next input pixel. */ coord_in = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the input array is updated accordingly. */ if ( dim[ coord_in ] < ubnd[ coord_in ] ) { dim[ coord_in ]++; off += stride[ coord_in ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the input pixel offset is decremented appropriately. */ } else { dim[ coord_in ] = lbnd[ coord_in ]; off -= stride[ coord_in ] * ( ubnd[ coord_in ] - lbnd[ coord_in ] ); /* All the output pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_in == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ accum = astFree( accum ); dim = astFree( dim ); } } /* No linear fit to the Mapping is available. */ /* ========================================== */ } else { /* Create a PointSet to hold the coordinates of the input pixels and obtain a pointer to its coordinate data. */ pset_in = astPointSet( npoint, ndim_in, "", status ); ptr_in = astGetPoints( pset_in ); if ( astOK ) { /* Initialise the count of input points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ndim_in == 1 && ndim_out == 1 ) { /* Loop through the required range of input x coordinates, assigning the coordinate values to the PointSet created above. Also store a pixel offset into the input array. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = (double) ix; offset[ point++ ] = ix - lbnd_in[ 0 ]; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ndim_in == 2 && ndim_out == 2) { /* Loop through the required range of input y coordinates, calculating an interim pixel offset into the input array. */ off1 = stride[ 1 ] * ( lbnd[ 1 ] - lbnd_in[ 1 ] - 1 ) - lbnd_in[ 0 ]; for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { off1 += stride[ 1 ]; /* Loop through the required range of input x coordinates, assigning the coordinate values to the PointSet created above. Also store a final pixel offset into the input array. */ off2 = off1 + lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = (double) ix; ptr_in[ 1 ][ point ] = (double) iy; offset[ point++ ] = off2++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ dim = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Initialise an array of pixel indices for the input grid which refer to the first pixel to be rebinned. Also calculate the offset of this pixel within the input array. */ off = 0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { dim[ coord_in ] = lbnd[ coord_in ]; off += stride[ coord_in ] * ( dim[ coord_in ] - lbnd_in[ coord_in ] ); } /* Loop to generate the coordinates of each input pixel. */ for ( done = 0; !done; point++ ) { /* Copy each pixel's coordinates into the PointSet created above. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in[ coord_in ][ point ] = (double) dim[ coord_in ]; } /* Store the offset of the pixel in the input array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next input pixel. */ coord_in = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the input array is updated accordingly. */ if ( dim[ coord_in ] < ubnd[ coord_in ] ) { dim[ coord_in ]++; off += stride[ coord_in ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the input pixel offset is decremented appropriately. */ } else { dim[ coord_in ] = lbnd[ coord_in ]; off -= stride[ coord_in ] * ( ubnd[ coord_in ] - lbnd[ coord_in ] ); /* All the input pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_in == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ dim = astFree( dim ); } /* When all the input pixel coordinates have been generated, use the Mapping's forward transformation to generate the output coordinates from them. Obtain an array of pointers to the resulting coordinate data. */ pset_out = astTransform( this, pset_in, 1, NULL ); ptr_out = astGetPoints( pset_out ); } /* Annul the PointSet containing the input coordinates. */ pset_in = astAnnul( pset_in ); } } /* Rebin the input grid. */ /* ------------------------ */ if( astOK ) { /* Identify the pixel spreading scheme to be used. */ /* Nearest pixel. */ /* -------------- */ switch ( spread ) { case AST__NEAREST: /* Define a macro to use a "case" statement to invoke the nearest-pixel spreading function appropriate to a given data type. */ #define CASE_NEAREST(X,Xtype) \ case ( TYPE_##X ): \ SpreadNearest##X( ndim_out, lbnd_out, ubnd_out, \ (Xtype *) in, (Xtype *) in_var, \ infac, npoint, offset, \ (const double *const *) ptr_out, \ flags, *( (Xtype *) badval_ptr ), \ npix_out, (Xtype *) out, \ (Xtype *) out_var, work, nused, status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_NEAREST(LD,long double) #endif CASE_NEAREST(D,double) CASE_NEAREST(F,float) CASE_NEAREST(I,int) CASE_NEAREST(B,signed char) CASE_NEAREST(UB,unsigned char) case ( TYPE_L ): break; case ( TYPE_K ): break; case ( TYPE_S ): break; case ( TYPE_UL ): break; case ( TYPE_UI ): break; case ( TYPE_UK ): break; case ( TYPE_US ): break; } break; /* Undefine the macro. */ #undef CASE_NEAREST /* Linear spreading. */ /* ----------------- */ /* Note this is also the default if zero is given. */ case AST__LINEAR: case 0: /* Define a macro to use a "case" statement to invoke the linear spreading function appropriate to a given data type. */ #define CASE_LINEAR(X,Xtype) \ case ( TYPE_##X ): \ SpreadLinear##X( ndim_out, lbnd_out, ubnd_out,\ (Xtype *) in, (Xtype *) in_var, \ infac, npoint, offset, \ (const double *const *) ptr_out, \ flags, *( (Xtype *) badval_ptr ), \ npix_out, (Xtype *) out, \ (Xtype *) out_var, work, nused, status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_LINEAR(LD,long double) #endif CASE_LINEAR(D,double) CASE_LINEAR(F,float) CASE_LINEAR(I,int) CASE_LINEAR(B,signed char) CASE_LINEAR(UB,unsigned char) case ( TYPE_L ): break; case ( TYPE_K ): break; case ( TYPE_S ): break; case ( TYPE_UL ): break; case ( TYPE_UI ): break; case ( TYPE_UK ): break; case ( TYPE_US ): break; } break; /* Undefine the macro. */ #undef CASE_LINEAR /* Spreading using a 1-d kernel. */ /* ----------------------------- */ case AST__SINC: case AST__SINCCOS: case AST__SINCGAUSS: case AST__GAUSS: case AST__SINCSINC: case AST__SOMB: case AST__SOMBCOS: /* Obtain a pointer to the appropriate 1-d kernel function (either internal or user-defined) and set up any parameters it may require. */ par = NULL; switch ( spread ) { /* sinc(pi*x) */ /* ---------- */ /* Assign the kernel function. */ case AST__SINC: kernel = Sinc; /* Calculate the number of neighbouring pixels to use. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) { neighb = 2; } else { neighb = MaxI( 1, neighb, status ); } break; /* somb(pi*x) */ /* ---------- */ /* Assign the kernel function. */ case AST__SOMB: kernel = Somb; /* Calculate the number of neighbouring pixels to use. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) { neighb = 2; } else { neighb = MaxI( 1, neighb, status ); } break; /* sinc(pi*x)*cos(k*pi*x) */ /* ---------------------- */ /* Assign the kernel function. */ case AST__SINCCOS: kernel = SincCos; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; /* sinc(pi*x)*exp(-k*x*x) */ /* ---------------------- */ /* Assign the kernel function. */ case AST__SINCGAUSS: kernel = SincGauss; /* Constrain the full width half maximum of the gaussian factor. */ fwhm = MaxD( 0.1, params[ 1 ], status ); /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 4.0 * log( 2.0 ) / ( fwhm * fwhm ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, use the number of neighbouring pixels required by the width of the kernel (out to where the gaussian term falls to 1% of its peak value). */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = (int) ceil( sqrt( -log( 0.01 ) / lpar[ 0 ] ) ); break; /* exp(-k*x*x) */ /* ----------- */ /* Assign the kernel function. */ case AST__GAUSS: kernel = Gauss; /* Constrain the full width half maximum of the gaussian. */ fwhm = MaxD( 0.1, params[ 1 ], status ); /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 4.0 * log( 2.0 ) / ( fwhm * fwhm ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, use the number of neighbouring pixels required by the width of the kernel (out to where the gaussian term falls to 1% of its peak value). */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = (int) ceil( sqrt( -log( 0.01 ) / lpar[ 0 ] ) ); break; /* somb(pi*x)*cos(k*pi*x) */ /* ---------------------- */ /* Assign the kernel function. */ case AST__SOMBCOS: kernel = SombCos; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; /* sinc(pi*x)*sinc(k*pi*x) */ /* ----------------------- */ /* Assign the kernel function. */ case AST__SINCSINC: kernel = SincSinc; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; } /* Define a macro to use a "case" statement to invoke the 1-d kernel interpolation function appropriate to a given data type, passing it the pointer to the kernel function obtained above. */ #define CASE_KERNEL1(X,Xtype) \ case ( TYPE_##X ): \ SpreadKernel1##X( this, ndim_out, lbnd_out, ubnd_out, \ (Xtype *) in, (Xtype *) in_var, \ infac, npoint, offset, \ (const double *const *) ptr_out, \ kernel, neighb, par, flags, \ *( (Xtype *) badval_ptr ), \ npix_out, (Xtype *) out, \ (Xtype *) out_var, work, nused, \ status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_KERNEL1(LD,long double) #endif CASE_KERNEL1(D,double) CASE_KERNEL1(F,float) CASE_KERNEL1(I,int) CASE_KERNEL1(B,signed char) CASE_KERNEL1(UB,unsigned char) case ( TYPE_L ): break; case ( TYPE_K ): break; case ( TYPE_S ): break; case ( TYPE_UL ): break; case ( TYPE_UI ): break; case ( TYPE_UK ): break; case ( TYPE_US ): break; } break; /* Undefine the macro. */ #undef CASE_KERNEL1 /* Error: invalid pixel spreading scheme specified. */ /* ------------------------------------------------ */ default: /* Define a macro to report an error message appropriate to a given data type. */ #define CASE_ERROR(X) \ case TYPE_##X: \ astError( AST__SISIN, "astRebin"#X"(%s): Invalid " \ "pixel spreading scheme (%d) specified.", status, \ astGetClass( unsimplified_mapping ), spread ); \ break; /* Use the above macro to report an appropriate error message. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_ERROR(LD) #endif CASE_ERROR(D) CASE_ERROR(F) CASE_ERROR(I) CASE_ERROR(B) CASE_ERROR(UB) case ( TYPE_L ): break; case ( TYPE_K ): break; case ( TYPE_S ): break; case ( TYPE_UL ): break; case ( TYPE_UI ): break; case ( TYPE_UK ): break; case ( TYPE_US ): break; } break; /* Undefine the macro. */ #undef CASE_ERROR } } /* Annul the PointSet used to hold output coordinates. */ pset_out = astAnnul( pset_out ); /* Free the workspace. */ offset = astFree( offset ); stride = astFree( stride ); } /* *++ * Name: c astRebinSeq f AST_REBINSEQ * Purpose: * Rebin a region of a sequence of data grids. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astRebinSeq( AstMapping *this, double wlim, int ndim_in, c const int lbnd_in[], const int ubnd_in[], c const in[], const in_var[], c int spread, const double params[], int flags, c double tol, int maxpix, badval, c int ndim_out, const int lbnd_out[], c const int ubnd_out[], const int lbnd[], c const int ubnd[], out[], out_var[], c double weights[], int64_t *nused ); f CALL AST_REBINSEQ( THIS, WLIM, NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, f SPREAD, PARAMS, FLAGS, TOL, MAXPIX, BADVAL, f NDIM_OUT, LBND_OUT, UBND_OUT, LBND, UBND, OUT, f OUT_VAR, WEIGHTS, NUSED, STATUS ) * Class Membership: * Mapping method. * Description: * This set of c functions is identical to astRebin f routines is identical to AST_REBIN * except that the rebinned input data is added into the supplied * output arrays, rather than simply over-writing the contents of the * output arrays. Thus, by calling this c function f routine * repeatedly, a sequence of input arrays can be rebinned and accumulated * into a single output array, effectively forming a mosaic of the * input data arrays. * * In addition, the weights associated with each output pixel are * returned. The weight of an output pixel indicates the number of input * pixels which have been accumulated in that output pixel. If the entire * value of an input pixel is assigned to a single output pixel, then the * weight of that output pixel is incremented by one. If some fraction of * the value of an input pixel is assigned to an output pixel, then the * weight of that output pixel is incremented by the fraction used. * * The start of a new sequence is indicated by specifying the * AST__REBININIT flag via the c "flags" parameter. f FLAGS argument. * This causes the supplied arrays to be filled with zeros before the * rebinned input data is added into them. Subsequenct invocations * within the same sequence should omit the AST__REBININIT flag. * * The last call in a sequence is indicated by specifying the * AST__REBINEND flag. Depending on which flags are supplied, this may * cause the output data and variance arrays to be normalised before * being returned. This normalisation consists of dividing the data * array by the weights array, and can eliminate artifacts which may be * introduced into the rebinned data as a consequence of aliasing * between the input and output grids. This results in each output * pixel value being the weighted mean of the input pixel values that * fall in the neighbourhood of the output pixel (rather like c astResample). f AST_RESAMPLE). * Optionally, these normalised * values can then be multiplied by a scaling factor to ensure that the * total data sum in any small area is unchanged. This scaling factor * is equivalent to the number of input pixel values that fall into each * output pixel. In addition to * normalisation of the output data values, any output variances are * also appropriately normalised, and any output data values with * weight less than c "wlim" are set to "badval". f WLIM are set to BADVAL. * * Output variances can be generated in two ways; by rebinning the supplied * input variances with appropriate weights, or by finding the spread of * input data values contributing to each output pixel (see the AST__GENVAR * and AST__USEVAR flags). * Parameters: c this f THIS = INTEGER (Given) * Pointer to a Mapping, whose forward transformation will be * used to transform the coordinates of pixels in the input * grid into the coordinate system of the output grid. * * The number of input coordinates used by this Mapping (as * given by its Nin attribute) should match the number of input c grid dimensions given by the value of "ndim_in" f grid dimensions given by the value of NDIM_IN * below. Similarly, the number of output coordinates (Nout * attribute) should match the number of output grid dimensions c given by "ndim_out". f given by NDIM_OUT. c If "in" is NULL, the Mapping will not be used, but a valid c Mapping must still be supplied. c wlim f WLIM = DOUBLE PRECISION (Given) * This value is only used if the AST__REBINEND flag is specified * via the c "flags" parameter. f FLAGS argument. * It gives the required number of input pixel values which must * contribute to an output pixel (i.e. the output pixel weight) in * order for the output pixel value to be considered valid. If the sum * of the input pixel weights contributing to an output pixel is less * than the supplied c "wlim" f WLIM * value, then the output pixel value is returned set to the * supplied bad value. If the supplied value is less than 1.0E-10 * then 1.0E-10 is used instead. c ndim_in f NDIM_IN = INTEGER (Given) * The number of dimensions in the input grid. This should be at * least one. c Not used if "in" is NULL. c lbnd_in f LBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c Not used if "in" is NULL. c ubnd_in f UBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd_in" and "ubnd_in" together define the shape f Note that LBND_IN and UBND_IN together define the shape * and size of the input grid, its extent along a particular c (j'th) dimension being ubnd_in[j]-lbnd_in[j]+1 (assuming the c index "j" to be zero-based). They also define f (J'th) dimension being UBND_IN(J)-LBND_IN(J)+1. They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. c Not used if "in" is NULL. c in f IN( * ) = (Given) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * input grid, containing the input data to be rebined. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if c you are using astRebinSeqF, the type of each array element c should be "float"). f you are using AST_REBINSEQR, the type of each array element f should be REAL). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c If a NULL pointer is supplied for "in", then no data is added to c the output arrays, but any initialisation or normalisation c requested by "flags" is still performed. c in_var f IN_VAR( * ) = (Given) * An optional c pointer to a * second array with the same size and type as the c "in" f IN * array. If given, this should contain a set of non-negative values * which represent estimates of the statistical variance associated * with each element of the c "in" f IN * array. * If neither the AST__USEVAR nor the AST__VARWGT flag is set, no * input variance estimates are required and this f array c pointer * will not be used. f A dummy (e.g. one-element) array c A NULL pointer * may then be supplied. c spread f SPREAD = INTEGER (Given) c This parameter specifies the scheme to be used for dividing f This argument specifies the scheme to be used for dividing * each input data value up amongst the corresponding output pixels. * It may be used to select * from a set of pre-defined schemes by supplying one of the * values described in the "Pixel Spreading Schemes" * section in the description of the c astRebin functions. f AST_REBIN routines. * If a value of zero is supplied, then the default linear spreading * scheme is used (equivalent to supplying the value AST__LINEAR). c Not used if "in" is NULL. c params f PARAMS( * ) = DOUBLE PRECISION (Given) c An optional pointer to an array of double which should contain f An optional array which should contain * any additional parameter values required by the pixel * spreading scheme. If such parameters are required, this * will be noted in the "Pixel Spreading Schemes" section in the * description of the c astRebin functions. f AST_REBIN routines. * c If no additional parameters are required, this array is not c used and a NULL pointer may be given. f If no additional parameters are required, this array is not f used. A dummy (e.g. one-element) array may then be supplied. c Not used if "in" is NULL. c flags f FLAGS = INTEGER (Given) c The bitwise OR of a set of flag values which may be used to f The sum of a set of flag values which may be used to * provide additional control over the rebinning operation. See * the "Control Flags" section below for a description of the * options available. If no flag values are to be set, a value * of zero should be given. c tol f TOL = DOUBLE PRECISION (Given) * The maximum tolerable geometrical distortion which may be * introduced as a result of approximating non-linear Mappings * by a set of piece-wise linear transformations. This should be * expressed as a displacement in pixels in the output grid's * coordinate system. * * If piece-wise linear approximation is not required, a value * of zero may be given. This will ensure that the Mapping is * used without any approximation, but may increase execution * time. * * If the value is too high, discontinuities between the linear * approximations used in adjacent panel will be higher, and may * cause the edges of the panel to be visible when viewing the output * image at high contrast. If this is a problem, reduce the * tolerance value used. c Not used if "in" is NULL. c maxpix f MAXPIX = INTEGER (Given) * A value which specifies an initial scale size (in pixels) for * the adaptive algorithm which approximates non-linear Mappings * with piece-wise linear transformations. Normally, this should * be a large value (larger than any dimension of the region of * the input grid being used). In this case, a first attempt to * approximate the Mapping by a linear transformation will be * made over the entire input region. * * If a smaller value is used, the input region will first be c divided into sub-regions whose size does not exceed "maxpix" f divided into sub-regions whose size does not exceed MAXPIX * pixels in any dimension. Only at this point will attempts at * approximation commence. * * This value may occasionally be useful in preventing false * convergence of the adaptive algorithm in cases where the * Mapping appears approximately linear on large scales, but has * irregularities (e.g. holes) on smaller scales. A value of, * say, 50 to 100 pixels can also be employed as a safeguard in * general-purpose software, since the effect on performance is * minimal. * * If too small a value is given, it will have the effect of * inhibiting linear approximation altogether (equivalent to c setting "tol" to zero). Although this may degrade f setting TOL to zero). Although this may degrade * performance, accurate results will still be obtained. c Not used if "in" is NULL. c badval f BADVAL = (Given) * This argument should have the same type as the elements of c the "in" array. It specifies the value used to flag missing f the IN array. It specifies the value used to flag missing * data (bad pixels) in the input and output arrays. * c If the AST__USEBAD flag is set via the "flags" parameter, f If the AST__USEBAD flag is set via the FLAGS argument, c then this value is used to test for bad pixels in the "in" c (and "in_var") array(s). f then this value is used to test for bad pixels in the IN f (and IN_VAR) array(s). * * In all cases, this value is also used to flag any output c elements in the "out" (and "out_var") array(s) for which f elements in the OUT (and OUT_VAR) array(s) for which * rebined values could not be obtained (see the "Propagation * of Missing Data" section below for details of the * circumstances under which this may occur). c ndim_out f NDIM_OUT = INTEGER (Given) * The number of dimensions in the output grid. This should be * at least one. It need not necessarily be equal to the number * of dimensions in the input grid. c lbnd_out f LBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the first pixel * in the output grid along each dimension. c ubnd_out f UBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the last pixel in * the output grid along each dimension. * c Note that "lbnd_out" and "ubnd_out" together define the f Note that LBND_OUT and UBND_OUT together define the * shape, size and coordinate system of the output grid in the c same way as "lbnd_in" and "ubnd_in" define the shape, size f same way as LBND_IN and UBND_IN define the shape, size * and coordinate system of the input grid. c lbnd f LBND( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the first pixel in the region * of the input grid which is to be included in the rebined output * array. c Not used if "in" is NULL. c ubnd f UBND( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the last pixel in the region of * the input grid which is to be included in the rebined output * array. * c Note that "lbnd" and "ubnd" together define the shape and f Note that LBND and UBND together define the shape and * position of a (hyper-)rectangular region of the input grid * which is to be included in the rebined output array. This region * should lie wholly within the extent of the input grid (as c defined by the "lbnd_in" and "ubnd_in" arrays). Regions of f defined by the LBND_IN and UBND_IN arrays). Regions of * the input grid lying outside this region will not be used. c Not used if "in" is NULL. c out f OUT( * ) = (Given and Returned) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * output grid. The rebined data values will be added into the * original contents of this array. The numerical type of this array * should match that of the c "in" array, and the data storage order should be such f IN array, and the data storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c out_var f OUT_VAR( * ) = (Given and Returned) * A c pointer to an * array with the same type and size as the c "out" f OUT * array. This c pointer f array * will only be used if the AST__USEVAR or AST__GENVAR flag is set f via the FLAGS argument, f via the "flags" parameter, * in which case variance estimates for the rebined data values will * be added into the array. If neither the AST__USEVAR flag nor the * AST__GENVAR flag is set, no output variance estimates will be * calculated and this c pointer f array * will not be used. A c NULL pointer f dummy (e.g. one-element) array * may then be supplied. c weights f WEIGHTS( * ) = DOUBLE PRECISION (Given and Returned) c Pointer to an array of double, f An array * with one or two elements for each pixel in the output grid, * depending on whether or not the AST__GENVAR flag has been supplied * via the c "flags" parameter. f FLAGS parameter. * If AST__GENVAR has not been specified then the array should have * one element for each output pixel, and it will be used to * accumulate the weight associated with each output pixel. * If AST__GENVAR has been specified then the array should have * two elements for each output pixel. The first half of the array * is again used to accumulate the weight associated with each output * pixel, and the second half is used to accumulate the square of * the weights. In each half, the data storage order should be such that * the index of the first grid dimension varies most rapidly and that of * the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c nused f NUSED = INTEGER*8 (Given and Returned) c A pointer to an int64_t containing the f The * number of input data values that have been added into the output * array so far. The supplied value is incremented on exit by the * number of input values used. The value is initially set to zero * if the AST__REBININIT flag is set in c "flags". f FLAGS. f STATUS = INTEGER (Given and Returned) f The global status. * Data Type Codes: * To select the appropriate rebinning function, you should c replace in the generic function name astRebinSeq with a f replace in the generic function name AST_REBINSEQ with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: c - D: double c - F: float c - I: int c - B: byte (signed char) c - UB: unsigned byte (unsigned char) f - D: DOUBLE PRECISION f - R: REAL f - I: INTEGER f - B: BYTE (treated as signed) f - UB: BYTE (treated as unsigned) * c For example, astRebinSeqD would be used to process "double" c data, while astRebinSeqI would be used to process "int" c data, etc. f For example, AST_REBIND would be used to process DOUBLE f PRECISION data, while AST_REBINI would be used to process f integer data (stored in an INTEGER array), etc. * * Note that, unlike c astResample, the astRebinSeq f AST_RESAMPLE, the AST_REBINSEQ * set of functions does not yet support unsigned integer data types * or integers of different sizes. * Control Flags: c The following flags are defined in the "ast.h" header file and f The following flags are defined in the AST_PAR include file and * may be used to provide additional control over the rebinning * process. Having selected a set of flags, you should supply the c bitwise OR of their values via the "flags" parameter: f sum of their values via the FLAGS argument: * * - AST__REBININIT: Used to mark the first call in a sequence. It indicates * that the supplied c "out", "out_var" and "weights" f OUT, OUT_VAR and WEIGHTS * arrays should be filled with zeros (thus over-writing any supplied * values) before adding the rebinned input data into them. This flag * should be used when rebinning the first input array in a sequence. * - AST__REBINEND: Used to mark the last call in a sequence. It causes * each value in the c "out" and "out_var" f OUT and OUT_VAR * arrays to be divided by a normalisation factor before being * returned. The normalisation factor for each output data value is just * the corresponding value from the weights array. The normalisation * factor for each output variance value is the square of the data value * normalisation factor (see also AST__CONSERVEFLUX). It also causes * output data values to be set bad if the corresponding weight is less * than the value supplied for c parameter "wlim". f argument WLIM. * It also causes any temporary values stored in the output variance array * (see flag AST__GENVAR below) to be converted into usable variance values. * Note, this flag is ignored if the AST__NONORM flag is set. * - AST__USEBAD: Indicates that there may be bad pixels in the * input array(s) which must be recognised by comparing with the c value given for "badval" and propagated to the output array(s). f value given for BADVAL and propagated to the output array(s). * If this flag is not set, all input values are treated literally c and the "badval" value is only used for flagging output array f and the BADVAL value is only used for flagging output array * values. * - AST__USEVAR: Indicates that output variance estimates should be * created by rebinning the supplied input variance estimates. An * error will be reported if both this flag and the AST__GENVAR flag * are supplied. * - AST__GENVAR: Indicates that output variance estimates should be * created based on the spread of input data values contributing to each * output pixel. An error will be reported if both this flag and the * AST__USEVAR flag are supplied. If the AST__GENVAR flag is specified, * the supplied output variance array is first used as a work array to * accumulate the temporary values needed to generate the output * variances. When the sequence ends (as indicated by the * AST__REBINEND flag), the contents of the output variance array are * converted into the required variance estimates. If the generation of * such output variances is required, this flag should be used on every * invocation of this c function f routine * within a sequence, and any supplied input variances will have no effect * on the output variances (although input variances will still be used * to weight the input data if the AST__VARWGT flag is also supplied). * The statistical meaning of these output varianes is determined by * the presence or absence of the AST__DISVAR flag (see below). * - AST__DISVAR: This flag is ignored unless the AST__GENVAR flag * has also been specified. It determines the statistical meaning of * the generated output variances. If AST__DISVAR is not specified, * generated variances represent variances on the output mean values. If * AST__DISVAR is specified, the generated variances represent the variance * of the distribution from which the input values were taken. Each output * variance created with AST__DISVAR will be larger than that created * without AST__DISVAR by a factor equal to the number of input samples * that contribute to the output sample. * - AST__VARWGT: Indicates that the input data should be weighted by * the reciprocal of the input variances. Otherwise, all input data are * given equal weight. If this flag is specified, the calculation of the * output variances (if any) is modified to take account of the * varying weights assigned to the input data values. * - AST__NONORM: If the simple unnormalised sum of all input data falling * in each output pixel is required, then this flag should be set on * each call in the sequence and the AST__REBINEND should not be used * on the last call. In this case c NULL pointers can be supplied for "weights" and "nused". f WEIGHTS and NUSED are ignored. * This flag cannot be used with the AST__CONSERVEFLUX, AST__GENVAR * or AST__VARWGT flag. * - AST__CONSERVEFLUX: Indicates that the normalized output pixel values * generated by the AST__REBINEND flag should be scaled in such a way as * to preserve the total data value in a feature on the sky. Without this * flag, each normalised output pixel value represents a weighted mean * of the input data values around the corresponding input position. f (i.e. AST_REBINSEQ behaves similarly to AST_RESAMPLE). This f (i.e. AST_REBINSEQ behaves similarly to AST_RESAMPLE). This * is appropriate if the input data represents the spatial density of * some quantity (e.g. surface brightness in Janskys per square * arc-second) because the output pixel values will have the same * normalisation and units as the input pixel values. However, if the * input data values represent flux (or some other physical quantity) * per pixel, then the AST__CONSERVEFLUX flag could be of use. It causes * each output pixel value to be scaled by the ratio of the output pixel * size to the input pixel size. * * This flag can only be used if the Mapping is successfully approximated * by one or more linear transformations. Thus an error will be reported * if it used when the c "tol" parameter f TOL argument * is set to zero (which stops the use of linear approximations), or * if the Mapping is too non-linear to be approximated by a piece-wise * linear transformation. The ratio of output to input pixel size is * evaluated once for each panel of the piece-wise linear approximation to * the Mapping, and is assumed to be constant for all output pixels in the * panel. The scaling factors for adjacent panels will in general * differ slightly, and so the joints between panels may be visible when * viewing the output image at high contrast. If this is a problem, * reduce the value of the c "tol" parameter f TOL argument * until the difference between adjacent panels is sufficiently small * to be insignificant. * * This flag should normally be supplied on each invocation of c astRebinSeq f AST_REBINSEQ * within a given sequence. * * Note, this flag cannot be used in conjunction with the AST__NOSCALE * flag (an error will be reported if both flags are specified). * Propagation of Missing Data: * Instances of missing data (bad pixels) in the output grid are c identified by occurrences of the "badval" value in the "out" f identified by occurrences of the BADVAL value in the OUT * array. These are only produced if the AST__REBINEND flag is * specified and a pixel has zero weight. * * An input pixel is considered bad (and is consequently ignored) if * its c data value is equal to "badval" and the AST__USEBAD flag is c set via the "flags" parameter. f data value is equal to BADVAL and the AST__USEBAD flag is f set via the FLAGS argument. * * In addition, associated output variance estimates (if c calculated) may be declared bad and flagged with the "badval" c value in the "out_var" array for similar reasons. f calculated) may be declared bad and flagged with the BADVAL f value in the OUT_VAR array for similar reasons. *-- */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_REBINSEQ(X,Xtype,IntType) \ static void RebinSeq##X( AstMapping *this, double wlim, int ndim_in, \ const int lbnd_in[], const int ubnd_in[], \ const Xtype in[], const Xtype in_var[], \ int spread, const double params[], int flags, \ double tol, int maxpix, Xtype badval, \ int ndim_out, const int lbnd_out[], \ const int ubnd_out[], const int lbnd[], \ const int ubnd[], Xtype out[], Xtype out_var[], \ double weights[], int64_t *nused, int *status ) { \ \ /* Local Variables: */ \ AstMapping *simple; /* Pointer to simplified Mapping */ \ Xtype *d; /* Pointer to next output data value */ \ Xtype *v; /* Pointer to next output variance value */ \ astDECLARE_GLOBALS /* Thread-specific data */ \ double *w; /* Pointer to next weight value */ \ double mwpip; /* Mean weight per input pixel */ \ double neff; /* Effective number of contributing input pixels */ \ double sw; /* Sum of weights at output pixel */ \ double wgt; /* Output pixel weight */ \ int i; /* Loop counter for output pixels */ \ int idim; /* Loop counter for coordinate dimensions */ \ int ipix_out; /* Index into output array */ \ int nin; /* Number of Mapping input coordinates */ \ int nout; /* Number of Mapping output coordinates */ \ int npix; /* Number of pixels in input region */ \ int npix_out; /* Number of pixels in output array */ \ int64_t mpix; /* Number of pixels for testing */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to a structure holding thread-specific global data values */ \ astGET_GLOBALS(this); \ \ /* Loop to determine how many pixels the output array contains. */ \ npix_out = 1; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ npix_out *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ } \ \ /* Obtain values for the Nin and Nout attributes of the Mapping. */ \ nin = astGetNin( this ); \ nout = astGetNout( this ); \ \ /* If OK, also check that the number of output grid dimensions matches \ the number required by the Mapping and is at least 1. Report an \ error if necessary. */ \ if ( astOK && ( ( ndim_out != nout ) || ( ndim_out < 1 ) ) ) { \ astError( AST__NGDIN, "astRebinSeq"#X"(%s): Bad number of output grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_out ); \ if ( ndim_out != nout ) { \ astError( AST__NGDIN, "The %s given generates %s%d coordinate " \ "value%s for each output position.", status, astGetClass( this ), \ ( nout < ndim_out ) ? "only " : "", nout, \ ( nout == 1 ) ? "" : "s" ); \ } \ } \ \ /* If no input data was supplied, jump to the normalisation section. */ \ simple = NULL; \ if( in ) { \ \ /* If OK, check that the number of input grid dimensions matches the \ number required by the Mapping and is at least 1. Report an error \ if necessary. */ \ if ( astOK && ( ( ndim_in != nin ) || ( ndim_in < 1 ) ) ) { \ astError( AST__NGDIN, "astRebinSeq"#X"(%s): Bad number of input grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_in ); \ if ( ndim_in != nin ) { \ astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ "to specify an input position.", status, \ astGetClass( this ), nin, ( nin == 1 ) ? "" : "s" ); \ } \ } \ \ /* Check that the lower and upper bounds of the input grid are \ consistent. Report an error if any pair is not. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ if ( lbnd_in[ idim ] > ubnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebinSeq"#X"(%s): Lower bound of " \ "input grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_in[ idim ], ubnd_in[ idim ] ); \ astError( AST__GBDIN, "Error in input dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the input. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebinSeq"#X"(%s): Supplied input array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Ensure any supplied "in_var" pointer is ignored if no input variances are \ needed. */ \ if( !( flags & AST__USEVAR ) && !( flags & AST__VARWGT ) ) { \ in_var = NULL; \ } \ \ /* Ensure any supplied "out_var" pointer is ignored if no output variances \ being created. */ \ if( !( flags & AST__USEVAR ) && !( flags & AST__GENVAR ) ) { \ out_var = NULL; \ } \ \ /* Check that the positional accuracy tolerance supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( tol < 0.0 ) ) { \ astError( AST__PATIN, "astRebinSeq"#X"(%s): Invalid positional " \ "accuracy tolerance (%.*g pixel).", status, \ astGetClass( this ), DBL_DIG, tol ); \ astError( AST__PATIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the initial scale size in pixels supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( maxpix < 0 ) ) { \ astError( AST__SSPIN, "astRebinSeq"#X"(%s): Invalid initial scale " \ "size in pixels (%d).", status, astGetClass( this ), maxpix ); \ astError( AST__SSPIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the lower and upper bounds of the output grid are \ consistent. Report an error if any pair is not. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_out; idim++ ) { \ if ( lbnd_out[ idim ] > ubnd_out[ idim ] ) { \ astError( AST__GBDIN, "astRebinSeq"#X"(%s): Lower bound of " \ "output grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_out[ idim ], ubnd_out[ idim ] ); \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the output. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebinSeq"#X"(%s): Supplied output array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Similarly check the bounds of the input region. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ if ( lbnd[ idim ] > ubnd[ idim ] ) { \ astError( AST__GBDIN, "astRebinSeq"#X"(%s): Lower bound of " \ "input region (%d) exceeds corresponding upper " \ "bound (%d).", status, astGetClass( this ), \ lbnd[ idim ], ubnd[ idim ] ); \ \ /* Also check that the input region lies wholly within the input \ grid. */ \ } else if ( lbnd[ idim ] < lbnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebinSeq"#X"(%s): Lower bound of " \ "input region (%d) is less than corresponding " \ "bound of input grid (%d).", status, astGetClass( this ), \ lbnd[ idim ], lbnd_in[ idim ] ); \ } else if ( ubnd[ idim ] > ubnd_in[ idim ] ) { \ astError( AST__GBDIN, "astRebinSeq"#X"(%s): Upper bound of " \ "input region (%d) exceeds corresponding " \ "bound of input grid (%d).", status, astGetClass( this ), \ ubnd[ idim ], ubnd_in[ idim ] ); \ } else { \ mpix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* Say which dimension produced the error. */ \ if ( !astOK ) { \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the input region. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astRebinSeq"#X"(%s): Supplied input region " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Check that only one of AST__USEVAR and ASR__GENVAR has been supplied. */ \ if( ( flags & AST__USEVAR ) && ( flags & AST__GENVAR ) ) { \ if( astOK ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): Incompatible flags " \ "AST__GENVAR and AST__USEVAR have been specified " \ "together (programming error).", status, astGetClass( this ) ); \ } \ } \ \ /* If AST__USEVAR or AST_VARWGT has been specified, check we have an \ input variance array. */ \ if( !in_var && astOK ) { \ if( ( flags & AST__USEVAR ) ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): The AST__USEVAR flag " \ "was specified but no input variance array was supplied " \ "(programming error).", status, astGetClass( this ) ); \ } else if( ( flags & AST__VARWGT ) ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): The AST__VARWGT flag " \ "was specified but no input variance array was supplied " \ "(programming error).", status, astGetClass( this ) ); \ } \ } \ \ /* If AST__USEVAR or AST_GENVAR has been specified, check we have an \ output variance array. */ \ if( !out_var && astOK ) { \ if( ( flags & AST__USEVAR ) ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): The AST__USEVAR flag " \ "was specified but no output variance array was supplied " \ "(programming error).", status, astGetClass( this ) ); \ } else if( ( flags & AST__GENVAR ) ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): The AST__GENVAR flag " \ "was specified but no output variance array was supplied " \ "(programming error).", status, astGetClass( this ) ); \ } \ } \ \ /* If the AST__NONORM flag has been supplied, check no incompatible flags have \ been specified. */ \ if( flags & AST__NONORM ) { \ if( ( flags & AST__GENVAR ) && astOK ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): Incompatible flags " \ "AST__GENVAR and AST__NONORM have been specified " \ "together (programming error).", status, astGetClass( this ) ); \ } else if( ( flags & AST__VARWGT ) && astOK ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): Incompatible flags " \ "AST__VARWGT and AST__NONORM have been specified " \ "together (programming error).", status, astGetClass( this ) ); \ } else if( ( flags & AST__CONSERVEFLUX ) && astOK ) { \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): Incompatible flags " \ "AST__CONSERVEFLUX and AST__NONORM have been specified " \ "together (programming error).", status, astGetClass( this ) ); \ } \ \ /* If the AST__NONORM flag has not been supplied, check that a weights array \ and nused pointer have been supplied. */ \ } else if( !weights ){ \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): No weights array " \ "supplied (programming error).", status, \ astGetClass( this ) ); \ } else if( !nused ){ \ astError( AST__BDPAR, "astRebinSeq"#X"(%s): No 'nused' pointer " \ "supplied (programming error).", status, \ astGetClass( this ) ); \ } \ \ /* If OK, loop to determine how many input pixels are to be binned. */ \ npix = 1; \ unsimplified_mapping = this; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ npix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* If there are sufficient pixels to make it worthwhile, simplify the \ Mapping supplied to improve performance. Otherwise, just clone the \ Mapping pointer. Note we have already saved a pointer to the original \ Mapping so that lower-level functions can use it if they need to report \ an error. */ \ if ( npix > 1024 ) { \ simple = astSimplify( this ); \ } else { \ simple = astClone( this ); \ } \ } \ \ /* Report an error if the forward transformation of this simplified \ Mapping is not defined. */ \ if ( !astGetTranForward( simple ) && astOK ) { \ astError( AST__TRNND, "astRebinSeq"#X"(%s): An forward coordinate " \ "transformation is not defined by the %s supplied.", status, \ astGetClass( unsimplified_mapping ), \ astGetClass( unsimplified_mapping ) ); \ } \ \ /* If required, initialise the output arrays to hold zeros. */ \ if( flags & AST__REBININIT ) { \ d = out; \ if( out_var ) { \ v = out_var; \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++, v++ ) { \ *d = 0; \ *v = 0; \ } \ } else { \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, d++ ) { \ *d = 0; \ } \ } \ if( weights ) { \ w = weights; \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, w++ ) { \ *w = 0; \ } \ if( flags & AST__GENVAR ) { \ for( ipix_out = 0; ipix_out < npix_out; ipix_out++, w++ ) *w = 0; \ } \ } \ if( nused ) *nused = 0; \ } \ \ /* Paste the input values into the supplied output arrays. */ \ if( RebinAdaptively( simple, ndim_in, lbnd_in, ubnd_in, \ (const void *) in, (const void *) in_var, \ TYPE_##X, spread, params, flags, \ tol, maxpix, (const void *) &badval, \ ndim_out, lbnd_out, ubnd_out, lbnd, \ ubnd, npix_out, (void *) out, \ (void *) out_var, weights, nused, status ) ) { \ astError( AST__CNFLX, "astRebinSeq"#X"(%s): Flux conservation was " \ "requested but could not be performed because the " \ "forward transformation of the supplied Mapping " \ "is too non-linear.", status, astGetClass( this ) ); \ } \ \ /* Annul the pointer to the simplified/cloned Mapping. */ \ simple = astAnnul( simple ); \ \ } \ \ /* If required, finalise the sequence. */ \ if( ( flags & AST__REBINEND ) && !( flags & AST__NONORM ) && \ weights && nused ) { \ \ /* Ensure "wlim" is not zero. */ \ if( wlim < 1.0E-10 ) wlim = 1.0E-10; \ \ /* If it will be needed, find the average weight per input pixel. */ \ if( !( flags & AST__GENVAR ) && *nused > 0 ) { \ sw = 0.0; \ for( i = 0; i < npix_out; i++ ) { \ sw += weights[ i ]; \ } \ mwpip = sw/( *nused ); \ } else { \ mwpip = AST__BAD; \ } \ \ /* Normalise each output pixel. */ \ for( i = 0; i < npix_out; i++ ) { \ \ /* Find the effective number of input samples that contribute to the \ output sample. To do this properly requires the sum of the squared \ weights in each output pixel, but this is only available if AST__GENVAR \ flag is in use. In order to avoid changing the API for astRebinSeq, we \ honour this long-standing restriction, and use an approximation if \ AST__GENVAR is not in use. */ \ wgt = weights[ i ]; \ if( flags & AST__GENVAR ) { \ if( wgt > 0.0 && weights[ i + npix_out ] > 0 ) { \ neff = (wgt*wgt)/weights[ i + npix_out ]; \ } else { \ neff = 0.0; \ } \ \ /* If the sum of the squared weights is not available, compare the weight \ for this output pixel with the mean weight per input pixel. */ \ } else if( mwpip != AST__BAD ){ \ neff = wgt/mwpip; \ \ } else if( astOK ) { \ astError( AST__BADIN, "astRebinSeq"#X"(%s): The overlap " \ "between the %d-d input array and the %d-d output " \ "array contains no pixels with good data %svalues.", \ status, astGetClass( this ), nin, nout, \ in_var ? "and variance " : "" ); \ } \ \ /* Assign bad values to unused output pixels. */ \ if( neff < wlim || neff == 0.0 ) { \ out[ i ] = badval; \ if( out_var ) out_var[ i ] = badval; \ \ /* Otherwise, normalise the returned data value. No need to check "wgt" \ since it must be larger than zero since neff is larger than wlim. */ \ } else { \ out[ i ] /= wgt; \ \ /* Normalise the returned variance: propagated from input variances... */ \ if( out_var ) { \ if( flags & AST__USEVAR ) { \ out_var[ i ] /= wgt*wgt; \ \ /* Normalise the returned variance: from spread of input values... */ \ } else if( flags & AST__GENVAR && neff > 1.0 ) { \ out_var[ i ] /= wgt; \ out_var[ i ] -= out[ i ]*out[ i ]; \ if( out_var[ i ] < 0.0 ) out_var[ i ] = 0.0; \ \ /* If output variances are estimates of the variance of the distribution \ from which the input values were sampled... */ \ if( flags & AST__DISVAR ) { \ out_var[ i ] *= neff/( neff - 1.0 ); \ \ /* If output variances are estimates of the error on the mean data value... */ \ } else { \ out_var[ i ] *= 1.0/( neff - 1.0 ); \ } \ \ } else { \ out_var[ i ] = badval; \ } \ } \ } \ } \ } \ \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_REBINSEQ(LD,long double,0) #endif MAKE_REBINSEQ(D,double,0) MAKE_REBINSEQ(F,float,0) MAKE_REBINSEQ(I,int,1) MAKE_REBINSEQ(B,signed char,1) MAKE_REBINSEQ(UB,unsigned char,1) /* Undefine the macro. */ #undef MAKE_REBINSEQ static int RebinWithBlocking( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, DataType type, int spread, const double *params, int flags, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, int npix_out, void *out, void *out_var, double *work, int64_t *nused, int *status ) { /* * Name: * RebinWithBlocking * Purpose: * Rebin a section of a data grid in a memory-efficient way. * Type: * Private function. * Synopsis: * #include "mapping.h" * int RebinWithBlocking( AstMapping *this, const double *linear_fit, * int ndim_in, const int *lbnd_in, * const int *ubnd_in, const void *in, * const void *in_var, DataType type, * int spread, const double *params, int flags, * const void *badval_ptr, int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const int *lbnd, const int *ubnd, int npix_out, * void *out, void *out_var, double *work, * int64_t *nused, int *status ) * Class Membership: * Mapping member function. * Description: * This function rebins a specified section of a rectangular grid of * data (with any number of dimensions) into another rectangular grid * (with a possibly different number of dimensions). The coordinate * transformation used to convert input pixel coordinates into positions * in the output grid is given by the forward transformation of the * Mapping which is supplied. Any pixel spreading scheme may be specified * for distributing the flux of an input pixel amongst the output * pixels. * * This function is very similar to RebinSection, except that in * order to limit memory usage and to ensure locality of reference, * it divides the input grid up into "blocks" which have a limited * extent along each input dimension. Each block, which will not * contain more than a pre-determined maximum number of pixels, is * then passed to RebinSection for resampling. * Parameters: * this * Pointer to a Mapping, whose forward transformation may be * used to transform the coordinates of pixels in the input * grid into associated positions in the output grid. * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's forward coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * forward transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be rebinned (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the rebinned data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * spread * A value selected from a set of pre-defined macros to identify * which pixel spread function should be used. * params * Pointer to an optional array of parameters that may be passed * to the pixel spread algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * flags * The bitwise OR of a set of flag values which provide additional * control over the resampling operation. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which rebinned values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the first pixel in the * section of the input data grid which is to be rebinned. * ubnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the last pixel in the * section of the input data grid which is to be rebinned. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the input grid which is to be rebinned. This section * should lie wholly within the extent of the input grid (as defined * by the "lbnd_out" and "ubnd_out" arrays). Regions of the input * grid lying outside this section will be ignored. * npix_out * The number of pixels in the output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * work * An optional pointer to a double array with the same size as * the "out" array. The contents of this array (if supplied) are * incremented by the accumulated weights assigned to each output pixel. * If no accumulated weights are required, a NULL pointer should be * given. * nused * An optional pointer to a int64_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * Returned Value: * A non-zero value is returned if "flags" included AST__CONSERVEFLUX (i.e. * flux conservation was requested), but the supplied linear fit to the * forward transformation of the Mapping had zero determinant (no error * is reported if this happens). Zero is returned otherwise. */ /* Local Constants: */ const int mxpix = 2 * 1024; /* Maximum number of pixels in a block (this relatively small number seems to give best performance) */ /* Local Variables: */ double factor; /* Flux conservation factor */ int *dim_block; /* Pointer to array of block dimensions */ int *lbnd_block; /* Pointer to block lower bound array */ int *ubnd_block; /* Pointer to block upper bound array */ int dim; /* Dimension size */ int done; /* All blocks rebinned? */ int hilim; /* Upper limit on maximum block dimension */ int idim; /* Loop counter for dimensions */ int lolim; /* Lower limit on maximum block dimension */ int mxdim_block; /* Maximum block dimension */ int npix; /* Number of pixels in block */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate workspace. */ lbnd_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); ubnd_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); dim_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Find the optimum block size. */ /* ---------------------------- */ /* We first need to find the maximum extent which a block of input pixels may have in each dimension. We determine this by taking the input grid extent in each dimension and then limiting the maximum dimension size until the resulting number of pixels is sufficiently small. This approach allows the block shape to approximate (or match) the input grid shape when appropriate. */ /* First loop to calculate the total number of input pixels and the maximum input dimension size. */ npix = 1; mxdim_block = 0; for ( idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= dim; if ( mxdim_block < dim ) mxdim_block = dim; } /* If the number of input pixels is too large for a single block, we perform iterations to determine the optimum upper limit on a block's dimension size. Initialise the limits on this result. */ if ( npix > mxpix ) { lolim = 1; hilim = mxdim_block; /* Loop to perform a binary chop, searching for the best result until the lower and upper limits on the result converge to adjacent values. */ while ( ( hilim - lolim ) > 1 ) { /* Form a new estimate from the mid-point of the previous limits. */ mxdim_block = ( hilim + lolim ) / 2; /* See how many pixels a block contains if its maximum dimension is limited to this new value. */ for ( npix = 1, idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= ( dim < mxdim_block ) ? dim : mxdim_block; } /* Update the appropriate limit, according to whether the number of pixels is too large or too small. */ *( ( npix <= mxpix ) ? &lolim : &hilim ) = mxdim_block; } /* When iterations have converged, obtain the maximum limit on the dimension size of a block which results in no more than the maximum allowed number of pixels per block. However, ensure that all block dimensions are at least 2. */ mxdim_block = lolim; } if ( mxdim_block < 2 ) mxdim_block = 2; /* Calculate the block dimensions by applying this limit to the output grid dimensions. */ for ( idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; dim_block[ idim ] = ( dim < mxdim_block ) ? dim : mxdim_block; /* Also initialise the lower and upper bounds of the first block of output grid pixels to be rebinned, ensuring that this does not extend outside the grid itself. */ lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); } /* Determine the flux conservation constant if needed. */ /* --------------------------------------------------- */ factor = 1.0; if( flags & AST__CONSERVEFLUX ) { if( linear_fit ) { factor = MatrixDet( ndim_out, ndim_in, linear_fit + ndim_out, status ); if( factor != 0.0 ) { factor = 1.0/factor; } else { result = 1; } } else { result = 1; } } /* Rebin each block of input pixels. */ /* --------------------------------- */ /* Loop to generate the extent of each block of input pixels and to rebin them. */ done = result; while ( !done && astOK ) { /* Rebin the current block, accumulating the sum of bad pixels produced. */ RebinSection( this, linear_fit, ndim_in, lbnd_in, ubnd_in, in, in_var, factor, type, spread, params, flags, badval_ptr, ndim_out, lbnd_out, ubnd_out, lbnd_block, ubnd_block, npix_out, out, out_var, work, nused, status ); /* Update the block extent to identify the next block of input pixels. */ idim = 0; do { /* We find the least significant dimension where the upper bound of the block has not yet reached the upper bound of the region of the input grid which we are rebinning. The block's position is then incremented by one block extent along this dimension, checking that the resulting extent does not go outside the region being rebinned. */ if ( ubnd_block[ idim ] < ubnd[ idim ] ) { lbnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ], ubnd[ idim ], status ); ubnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); break; /* If any less significant dimensions are found where the upper bound of the block has reached its maximum value, we reset the block to its lowest position. */ } else { lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); /* All the blocks have been processed once the position along the most significant dimension has been reset. */ done = ( ++idim == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ lbnd_block = astFree( lbnd_block ); ubnd_block = astFree( ubnd_block ); dim_block = astFree( dim_block ); /* Return a flag indicating if there was an error conserving flux. */ return result; } static AstMapping *RemoveRegions( AstMapping *this, int *status ) { /* *++ * Name: c astRemoveRegions f AST_REMOVEREGIONS * Purpose: * Remove any Regions from a Mapping. * Type: * Public function. * Synopsis: c #include "mapping.h" c AstMapping *astRemoveRegions( AstMapping *this ) f RESULT = AST_REMOVEREGIONS( THIS, STATUS ) * Class Membership: * Mapping method. * Description: * This function searches the suppliedMapping (which may be a * compound Mapping such as a CmpMap) for any component Mappings * that are instances of the AST Region class. It then creates a new * Mapping from which all Regions have been removed. If a Region * cannot simply be removed (for instance, if it is a component of a * parallel CmpMap), then it is replaced with an equivalent UnitMap * in the returned Mapping. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the original Mapping. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astRemoveRegions() f AST_REMOVEREGIONS = INTEGER * A new pointer to the (possibly modified) Mapping. * Applicability: * CmpFrame * If the supplied Mapping is a CmpFrame, any component Frames that * are instances of the Region class are replaced by the equivalent * Frame. * FrameSet * If the supplied Mapping is a FrameSet, the returned Mapping * will be a copy of the supplied FrameSet in which Regions have * been removed from all the inter-Frame Mappings, and any Frames * which are instances of the Region class are repalced by the * equivalent Frame. * Mapping * This function applies to all Mappings. * Region * If the supplied Mapping is a Region, the returned Mapping will * be the equivalent Frame. * Notes: * - This function can safely be applied even to Mappings which * contain no Regions. If no Regions are found, it c behaves exactly like astClone and returns a pointer to the f behaves exactly like AST_CLONE and returns a pointer to the * original Mapping. * - The Mapping returned by this function may not be independent * of the original (even if some Regions were removed), and * modifying it may therefore result in indirect modification of * the original. If a completely independent result is required, a c copy should be made using astCopy. f copy should be made using AST_COPY. * - 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. *-- */ /* This base iplementation just returns a clone of the supplied Mapping pointer. Sub-classes should override it as necessary. */ return astClone( this ); } static void ReportPoints( AstMapping *this, int forward, AstPointSet *in_points, AstPointSet *out_points, int *status ) { /* *+ * Name: * astReportPoints * Purpose: * Report the effect of transforming a set of points using a Mapping. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * void astReportPoints( AstMapping *this, int forward, * AstPointSet *in_points, AstPointSet *out_points ) * Class Membership: * Mapping method. * Description: * This function reports the coordinates of a set of points before * and after being transformed by a Mapping, by writing them to * standard output. * Parameters: * this * Pointer to the Mapping. * forward * A non-zero value indicates that the Mapping'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 Mapping was * applied. * out_points * Pointer to a PointSet which is associated with the * coordinates of the same set of points after the Mapping has * been applied. * Notes: * - This method is provided as a development and debugging aid to * be invoked when coordinates are transformed by public Mapping * methods and under control of the "Report" Mapping attribute. * - Derived clases may over-ride this method in order to change * the way in which coordinates are formatted, etc. *- */ /* Local Variables: */ 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 the numbers of points and coordinates associated with each PointSet. */ npoint_in = astGetNpoint( in_points ); npoint_out = astGetNpoint( out_points ); ncoord_in = astGetNcoord( in_points ); ncoord_out = astGetNcoord( out_points ); /* Obtain the pointers that give access to the coordinate data associated with each PointSet. */ ptr_in = astGetPoints( in_points ); ptr_out = astGetPoints( out_points ); /* In the event that both PointSets don't contain equal numbers of points (this shouldn't actually happen), simply use the minimum number. */ npoint = ( npoint_in < npoint_out ) ? npoint_in : npoint_out; /* Loop to report the effect of the Mapping on each point in turn. */ for ( point = 0; point < npoint; point++ ) { /* Report the input coordinates (in parentheses and separated by commas). Replace coordinate values of AST__BAD with the string "" to indicate missing values. */ printf( "(" ); for ( coord = 0; coord < ncoord_in; coord++ ) { if ( ptr_in[ coord ][ point ] == AST__BAD ) { printf( "%s", coord ? ", " : "" ); } else { printf( "%s%.*g", coord ? ", " : "", DBL_DIG, ptr_in[ coord ][ point ] ); } } /* Similarly report the output coordinates. */ printf( ") --> (" ); for ( coord = 0; coord < ncoord_out; coord++ ) { if ( ptr_out[ coord ][ point ] == AST__BAD ) { printf( "%s", coord ? ", " : "" ); } else { printf( "%s%.*g", coord ? ", " : "", DBL_DIG, ptr_out[ coord ][ point ] ); } } printf( ")\n" ); } } /* *++ * Name: c astResample f AST_RESAMPLE * Purpose: * Resample a region of a data grid. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c int astResample( AstMapping *this, int ndim_in, c const int lbnd_in[], const int ubnd_in[], c const in[], const in_var[], c int interp, void (* finterp)( void ), c const double params[], int flags, c double tol, int maxpix, c badval, int ndim_out, c const int lbnd_out[], const int ubnd_out[], c const int lbnd[], const int ubnd[], c out[], out_var[] ); f RESULT = AST_RESAMPLE( THIS, NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, f INTERP, FINTERP, PARAMS, FLAGS, f TOL, MAXPIX, BADVAL, f NDIM_OUT, LBND_OUT, UBND_OUT, f LBND, UBND, OUT, OUT_VAR, STATUS ) * Class Membership: * Mapping method. * Description: * This is a set of functions for resampling gridded data (e.g. an * image) under the control of a geometrical transformation, which * is specified by a Mapping. The functions operate on a pair of * data grids (input and output), each of which may have any number * of dimensions. Resampling may be restricted to a specified * region of the output grid. An associated grid of error estimates * associated with the input data may also be supplied (in the form * of variance values), so as to produce error estimates for the * resampled output data. Propagation of missing data (bad pixels) * is supported. * * You should use a resampling function which matches the numerical * type of the data you are processing by replacing in c the generic function name astResample by an appropriate 1- or f the generic function name AST_RESAMPLE by an appropriate 1- or * 2-character type code. For example, if you are resampling data c with type "float", you should use the function astResampleF (see f with type REAL, you should use the function AST_RESAMPLER (see * the "Data Type Codes" section below for the codes appropriate to * other numerical types). * * Resampling of the grid of input data is performed by * transforming the coordinates of the centre of each output grid * element (or pixel) into the coordinate system of the input grid. * Since the resulting coordinates will not, in general, coincide * with the centre of an input pixel, sub-pixel interpolation is * performed between the neighbouring input pixels. This produces a * resampled value which is then assigned to the output pixel. A * choice of sub-pixel interpolation schemes is provided, but you * may also implement your own. * * This algorithm samples the input data value, it does not integrate * it. Thus total data value in the input image will not, in general, * be conserved. However, an option is provided (see the "Control Flags" * section below) which can produce approximate flux conservation by * scaling the output values using the ratio of the output pixel size * to the input pixel size. However, if accurate flux conservation is * important to you, consder using the c astRebin or astRebinSeq family of functions f AST_REBIN or AST_REBINSEQ family of routines * instead. * * Output pixel coordinates are transformed into the coordinate * system of the input grid using the inverse transformation of the * Mapping which is supplied. This means that geometrical features * in the input data are subjected to the Mapping's forward * transformation as they are transferred from the input to the * output grid (although the Mapping's forward transformation is * not explicitly used). * * In practice, transforming the coordinates of every pixel of a * large data grid can be time-consuming, especially if the Mapping * involves complicated functions, such as sky projections. To * improve performance, it is therefore possible to approximate * non-linear Mappings by a set of linear transformations which are * applied piece-wise to separate sub-regions of the data. This * approximation process is applied automatically by an adaptive * algorithm, under control of an accuracy criterion which * expresses the maximum tolerable geometrical distortion which may * be introduced, as a fraction of a pixel. * * This algorithm first attempts to approximate the Mapping with a * linear transformation applied over the whole region of the * output grid which is being used. If this proves to be * insufficiently accurate, the output region is sub-divided into * two along its largest dimension and the process is repeated * within each of the resulting sub-regions. This process of * sub-division continues until a sufficiently good linear * approximation is found, or the region to which it is being * applied becomes too small (in which case the original Mapping is * used directly). * Parameters: c this f THIS = INTEGER (Given) * Pointer to a Mapping, whose inverse transformation will be * used to transform the coordinates of pixels in the output * grid into the coordinate system of the input grid. This * yields the positions which are used to obtain resampled * values by sub-pixel interpolation within the input grid. * * The number of input coordinates used by this Mapping (as * given by its Nin attribute) should match the number of input c grid dimensions given by the value of "ndim_in" f grid dimensions given by the value of NDIM_IN * below. Similarly, the number of output coordinates (Nout * attribute) should match the number of output grid dimensions c given by "ndim_out". f given by NDIM_OUT. c ndim_in f NDIM_IN = INTEGER (Given) * The number of dimensions in the input grid. This should be at * least one. c lbnd_in f LBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c ubnd_in f UBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd_in" and "ubnd_in" together define the shape f Note that LBND_IN and UBND_IN together define the shape * and size of the input grid, its extent along a particular c (j'th) dimension being ubnd_in[j]-lbnd_in[j]+1 (assuming the c index "j" to be zero-based). They also define f (J'th) dimension being UBND_IN(J)-LBND_IN(J)+1. They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. c in f IN( * ) = (Given) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * input grid, containing the input data to be resampled. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if c you are using astResampleF, the type of each array element c should be "float"). f you are using AST_RESAMPLER, the type of each array element f should be REAL). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c in_var f IN_VAR( * ) = (Given) c An optional pointer to a second array with the same size and c type as the "in" array. If given, this should contain a set c of non-negative values which represent estimates of the c statistical variance associated with each element of the "in" c array. If this array is supplied (together with the c corresponding "out_var" array), then estimates of the c variance of the resampled output data will be calculated. c c If no input variance estimates are being provided, a NULL c pointer should be given. f An optional second array with the same size and type as the f IN array. If the AST__USEVAR flag is set via the FLAGS f argument (below), this array should contain a set of f non-negative values which represent estimates of the f statistical variance associated with each element of the IN f array. Estimates of the variance of the resampled output data f will then be calculated. f f If the AST__USEVAR flag is not set, no input variance f estimates are required and this array will not be used. A f dummy (e.g. one-element) array may then be supplied. c interp f INTERP = INTEGER (Given) c This parameter specifies the scheme to be used for sub-pixel f This argument specifies the scheme to be used for sub-pixel * interpolation within the input grid. It may be used to select * from a set of pre-defined schemes by supplying one of the * values described in the "Sub-Pixel Interpolation Schemes" * section below. If a value of zero is supplied, then the * default linear interpolation scheme is used (equivalent to * supplying the value AST__LINEAR). * * Alternatively, you may supply a value which indicates that c you will provide your own function to perform sub-pixel c interpolation by means of the "finterp " parameter. Again, see f you will provide your own routine to perform sub-pixel f interpolation by means of the FINTERP argument. Again, see * the "Sub-Pixel Interpolation Schemes" section below for * details. c finterp f FINTERP = SUBROUTINE (Given) c If the value given for the "interp" parameter indicates that c you will provide your own function for sub-pixel c interpolation, then a pointer to that function should be c given here. For details of the interface which the function c should have (several are possible, depending on the value of c "interp"), see the "Sub-Pixel Interpolation Schemes" section c below. f If the value given for the INTERP argument indicates that you f will provide your own routine for sub-pixel interpolation, f then the name of that routine should be given here (the name f should also appear in a Fortran EXTERNAL statement in the f routine which invokes AST_RESAMPLE). For details of the f interface which the routine should have (several are f possible, depending on the value of INTERP), see the f "Sub-Pixel Interpolation Schemes" section below. * c If the "interp" parameter has any other value, corresponding c to one of the pre-defined interpolation schemes, then this c function will not be used and you may supply a NULL pointer. f If the INTERP argument has any other value, corresponding to f one of the pre-defined interpolation schemes, then this f routine will not be used and you may supply the null routine f AST_NULL here (note only one underscore). No EXTERNAL f statement is required for this routine, so long as the AST_PAR f include file has been used. c params f PARAMS( * ) = DOUBLE PRECISION (Given) c An optional pointer to an array of double which should contain f An optional array which should contain * any additional parameter values required by the sub-pixel * interpolation scheme. If such parameters are required, this * will be noted in the "Sub-Pixel Interpolation Schemes" c section below (you may also use this array to pass values c to your own interpolation function). f section below (you may also use this array to pass values f to your own interpolation routine). * c If no additional parameters are required, this array is not c used and a NULL pointer may be given. f If no additional parameters are required, this array is not f used. A dummy (e.g. one-element) array may then be supplied. c flags f FLAGS = INTEGER (Given) c The bitwise OR of a set of flag values which may be used to f The sum of a set of flag values which may be used to * provide additional control over the resampling operation. See * the "Control Flags" section below for a description of the * options available. If no flag values are to be set, a value * of zero should be given. c tol f TOL = DOUBLE PRECISION (Given) * The maximum tolerable geometrical distortion which may be * introduced as a result of approximating non-linear Mappings * by a set of piece-wise linear transformations. This should be * expressed as a displacement in pixels in the input grid's * coordinate system. * * If piece-wise linear approximation is not required, a value * of zero may be given. This will ensure that the Mapping is * used without any approximation, but may increase execution * time. c maxpix f MAXPIX = INTEGER (Given) * A value which specifies an initial scale size (in pixels) for * the adaptive algorithm which approximates non-linear Mappings * with piece-wise linear transformations. Normally, this should * be a large value (larger than any dimension of the region of * the output grid being used). In this case, a first attempt to * approximate the Mapping by a linear transformation will be * made over the entire output region. * * If a smaller value is used, the output region will first be c divided into sub-regions whose size does not exceed "maxpix" f divided into sub-regions whose size does not exceed MAXPIX * pixels in any dimension. Only at this point will attempts at * approximation commence. * * This value may occasionally be useful in preventing false * convergence of the adaptive algorithm in cases where the * Mapping appears approximately linear on large scales, but has * irregularities (e.g. holes) on smaller scales. A value of, * say, 50 to 100 pixels can also be employed as a safeguard in * general-purpose software, since the effect on performance is * minimal. * * If too small a value is given, it will have the effect of * inhibiting linear approximation altogether (equivalent to c setting "tol" to zero). Although this may degrade f setting TOL to zero). Although this may degrade * performance, accurate results will still be obtained. c badval f BADVAL = (Given) * This argument should have the same type as the elements of c the "in" array. It specifies the value used to flag missing f the IN array. It specifies the value used to flag missing * data (bad pixels) in the input and output arrays. * c If the AST__USEBAD flag is set via the "flags" parameter, f If the AST__USEBAD flag is set via the FLAGS argument, c then this value is used to test for bad pixels in the "in" c (and "in_var") array(s). f then this value is used to test for bad pixels in the IN f (and IN_VAR) array(s). * c Unless the AST__NOBAD flag is set via the "flags" parameter, f Unless the AST__NOBAD flag is set via the FLAGS argument, * this value is also used to flag any output c elements in the "out" (and "out_var") array(s) for which f elements in the OUT (and OUT_VAR) array(s) for which * resampled values could not be obtained (see the "Propagation * of Missing Data" section below for details of the c circumstances under which this may occur). The astResample f circumstances under which this may occur). The AST_RESAMPLE * function return value indicates whether any such values have * been produced. If the AST__NOBAD flag is set. then output array * elements for which no resampled value could be obtained are * left set to the value they had on entry to this function. c ndim_out f NDIM_OUT = INTEGER (Given) * The number of dimensions in the output grid. This should be * at least one. It need not necessarily be equal to the number * of dimensions in the input grid. c lbnd_out f LBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the first pixel * in the output grid along each dimension. c ubnd_out f UBND_OUT( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the centre of the last pixel in * the output grid along each dimension. * c Note that "lbnd_out" and "ubnd_out" together define the f Note that LBND_OUT and UBND_OUT together define the * shape, size and coordinate system of the output grid in the c same way as "lbnd_in" and "ubnd_in" define the shape, size f same way as LBND_IN and UBND_IN define the shape, size * and coordinate system of the input grid. c lbnd f LBND( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the first pixel in the region * of the output grid for which a resampled value is to be * calculated. c ubnd f UBND( NDIM_OUT ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_out" elements, f An array * containing the coordinates of the last pixel in the region of * the output grid for which a resampled value is to be * calculated. * c Note that "lbnd" and "ubnd" together define the shape and f Note that LBND and UBND together define the shape and * position of a (hyper-)rectangular region of the output grid * for which resampled values should be produced. This region * should lie wholly within the extent of the output grid (as c defined by the "lbnd_out" and "ubnd_out" arrays). Regions of f defined by the LBND_OUT and UBND_OUT arrays). Regions of * the output grid lying outside this region will not be * modified. c out f OUT( * ) = (Returned) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * output grid, into which the resampled data values will be * returned. The numerical type of this array should match that c of the "in" array, and the data storage order should be such f of the IN array, and the data storage order should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c out_var f OUT_VAR( * ) = (Returned) c An optional pointer to an array with the same type and size c as the "out" array. If given, this array will be used to c return variance estimates for the resampled data values. This c array will only be used if the "in_var" array has also been c supplied. f An optional array with the same type and size as the OUT f array. If the AST__USEVAR flag is set via the FLAGS argument, f this array will be used to return variance estimates for the f resampled data values. * * The output variance values will be calculated on the * assumption that errors on the input data values are * statistically independent and that their variance estimates * may simply be summed (with appropriate weighting factors) * when several input pixels contribute to an output data * value. If this assumption is not valid, then the output error * estimates may be biased. In addition, note that the * statistical errors on neighbouring output data values (as * well as the estimates of those errors) may often be * correlated, even if the above assumption about the input data * is correct, because of the sub-pixel interpolation schemes * employed. * c If no output variance estimates are required, a NULL pointer c should be given. f If the AST__USEVAR flag is not set, no output variance f estimates will be calculated and this array will not be f used. A dummy (e.g. one-element) array may then be supplied. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astResample() f AST_RESAMPLE = INTEGER * The number of output pixels for which no valid resampled value * could be obtained. Thus, in the absence of any error, a returned * value of zero indicates that all the required output pixels * received valid resampled data values (and variances). See the c "badval" and "flags" parameters. f BADVAL and FLAGS arguments. * 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. * Data Type Codes: * To select the appropriate resampling function, you should c replace in the generic function name astResample with a f replace in the generic function name AST_RESAMPLE with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: c - D: double c - F: float c - L: long int (may be 32 or 64 bit) c - K: 64 bit int c - UL: unsigned long int (may be 32 or 64 bit) c - UK: unsigned 64 bit int c - I: int c - UI: unsigned int c - S: short int c - US: unsigned short int c - B: byte (signed char) c - UB: unsigned byte (unsigned char) f - D: DOUBLE PRECISION f - R: REAL f - I: INTEGER f - UI: INTEGER (treated as unsigned) f - S: INTEGER*2 (short integer) f - US: INTEGER*2 (short integer, treated as unsigned) f - B: BYTE (treated as signed) f - UB: BYTE (treated as unsigned) * c For example, astResampleD would be used to process "double" c data, while astResampleS would be used to process "short int" c data, etc. f For example, AST_RESAMPLED would be used to process DOUBLE f PRECISION data, while AST_RESAMPLES would be used to process f short integer data (stored in an INTEGER*2 array), etc. f f For compatibility with other Starlink facilities, the codes W f and UW are provided as synonyms for S and US respectively (but f only in the Fortran interface to AST). * Sub-Pixel Interpolation Schemes: * There is no such thing as a perfect sub-pixel interpolation * scheme and, in practice, all resampling will result in some * degradation of gridded data. A range of schemes is therefore * provided, from which you can choose the one which best suits * your needs. * * In general, a balance must be struck between schemes which tend * to degrade sharp features in the data by smoothing them, and * those which attempt to preserve sharp features. The latter will * often tend to introduce unwanted oscillations, typically visible * as "ringing" around sharp features and edges, especially if the * data are under-sampled (i.e. if the sharpest features are less * than about two pixels across). In practice, a good interpolation * scheme is likely to be a compromise and may exhibit some aspects * of both these features. * * For under-sampled data, some interpolation schemes may appear to * preserve data resolution because they transform single input * pixels into single output pixels, rather than spreading their * data between several output pixels. While this may look * better cosmetically, it can result in a geometrical shift of * sharp features in the data. You should beware of this if you * plan to use such features (e.g.) for image alignment. * * The following are two easy-to-use sub-pixel interpolation * schemes which are generally applicable. They are selected by c supplying the appropriate value (defined in the "ast.h" header c file) via the "interp" parameter. In these cases, the "finterp" c and "params" parameters are not used: f supplying the appropriate value (defined in the AST_PAR include f file) via the INTERP argument. In these cases, the FINTERP f and PARAMS arguments are not used: * * - AST__NEAREST: This is the simplest possible scheme, in which * the value of the input pixel with the nearest centre to the * interpolation point is used. This is very quick to execute and * will preserve single-pixel features in the data, but may * displace them by up to half their width along each dimension. It * often gives a good cosmetic result, so is useful for quick-look * processing, but is unsuitable if accurate geometrical * transformation is required. * - AST__LINEAR: This is the default scheme, which uses linear * interpolation between the nearest neighbouring pixels in the * input grid (there are two neighbours in one dimension, four * neighbours in two dimensions, eight in three dimensions, * etc.). It is superior to the nearest-pixel scheme (above) in not * displacing features in the data, yet it still executes fairly * rapidly. It is generally a safe choice if you do not have any * particular reason to favour another scheme, since it cannot * introduce oscillations. However, it does introduce some spatial * smoothing which varies according to the distance of the * interpolation point from the neighbouring pixels. This can * degrade the shape of sharp features in the data in a * position-dependent way. It may also show in the output variance * grid (if used) as a pattern of stripes or fringes. * * An alternative set of interpolation schemes is based on forming * the interpolated value from the weighted sum of a set of * surrounding pixel values (not necessarily just the nearest * neighbours). This approach has its origins in the theory of * digital filtering, in which interpolated values are obtained by * conceptually passing the sampled data (represented by a grid of * delta functions) through a linear filter which implements a * convolution. Because the convolution kernel is continuous, the * convolution yields a continuous function which may then be * evaluated at fractional pixel positions. The (possibly * multi-dimensional) kernel is usually regarded as "separable" and * formed from the product of a set of identical 1-dimensional * kernel functions, evaluated along each dimension. Different * interpolation schemes are then distinguished by the choice of * this 1-dimensional interpolation kernel. The number of * surrounding pixels which contribute to the result may also be * varied. * * From a practical standpoint, it is useful to divide the weighted * sum of pixel values by the sum of the weights when determining * the interpolated value. Strictly, this means that a true * convolution is no longer being performed. However, the * distinction is rarely important in practice because (for * slightly subtle reasons) the sum of weights is always * approximately constant for good interpolation kernels. The * advantage of this technique, which is used here, is that it can * easily accommodate missing data and tends to minimise unwanted * oscillations at the edges of the data grid. * * In the following schemes, which are based on a 1-dimensional c interpolation kernel, the first element of the "params" array f interpolation kernel, the first element of the PARAMS array * should be used to specify how many pixels are to contribute to the * interpolated result on either side of the interpolation point in * each dimension (the nearest integer value is used). Execution time * increases rapidly with this number. Typically, a value of 2 is * appropriate and the minimum value used will be 1 (i.e. two pixels * altogether, one on either side of the interpolation point). c A value of zero or less may be given for "params[0]" f A value of zero or less may be given for PARAMS(1) * to indicate that a suitable number of pixels should be calculated * automatically. * c In each of these cases, the "finterp" parameter is not used: f In each of these cases, the FINTERP argument is not used: * * - AST__GAUSS: This scheme uses a kernel of the form exp(-k*x*x), with * k a positive constant. The full-width at half-maximum (FWHM) is * given by c "params[1]" f PARAMS(2) f value, which should be at least 0.1 (in addition, setting PARAMS(1) * to zero will select the number of contributing pixels so as to utilise * the width of the kernel out to where the envelope declines to 1% of its * maximum value). This kernel suppresses noise at the expense of * smoothing the output array. * - AST__SINC: This scheme uses a sinc(pi*x) kernel, where x is the * pixel offset from the interpolation point and sinc(z)=sin(z)/z. This * sometimes features as an "optimal" interpolation kernel in books on * image processing. Its supposed optimality depends on the assumption * that the data are band-limited (i.e. have no spatial frequencies above * a certain value) and are adequately sampled. In practice, astronomical * data rarely meet these requirements. In addition, high spatial * frequencies are often present due (e.g.) to image defects and cosmic * ray events. Consequently, substantial ringing can be experienced with * this kernel. The kernel also decays slowly with distance, so that * many surrounding pixels are required, leading to poor performance. * Abruptly truncating it, by using only a few neighbouring pixels, c improves performance and may reduce ringing (if "params[0]" is set to f improves performance and may reduce ringing (if PARAMS(1) is set to * zero, then only two pixels will be used on either side). However, a * more gradual truncation, as implemented by other kernels, is generally * to be preferred. This kernel is provided mainly so that you can * convince yourself not to use it! * - AST__SINCSINC: This scheme uses an improved kernel, of the form * sinc(pi*x).sinc(k*pi*x), with k a constant, out to the point where * sinc(k*pi*x) goes to zero, and zero beyond. The second sinc() factor * provides an "envelope" which gradually rolls off the normal sinc(pi*x) * kernel at large offsets. The width of this envelope is specified by * giving the number of pixels offset at which it goes to zero by means c of the "params[1]" value, which should be at least 1.0 (in addition, c setting "params[0]" to zero will select the number of contributing f of the PARAMS(2) value, which should be at least 1.0 (in addition, f setting PARAMS(1) to zero will select the number of contributing * pixels so as to utilise the full width of the kernel, out to where it c reaches zero). The case given by "params[0]=2, params[1]=2" is typically f reaches zero). The case given by PARAMS(1)=2, PARAMS(2)=2 is typically * a good choice and is sometimes known as the Lanczos kernel. This is a * valuable general-purpose interpolation scheme, intermediate in its * visual effect on images between the AST__NEAREST and AST__LINEAR * schemes. Although the kernel is slightly oscillatory, ringing is * adequately suppressed if the data are well sampled. * - AST__SINCCOS: This scheme uses a kernel of the form * sinc(pi*x).cos(k*pi*x), with k a constant, out to the point where * cos(k*pi*x) goes to zero, and zero beyond. As above, the cos() factor * provides an envelope which gradually rolls off the sinc() kernel * at large offsets. The width of this envelope is specified by giving * the number of pixels offset at which it goes to zero by means c of the "params[1]" value, which should be at least 1.0 (in addition, c setting "params[0]" to zero will select the number of contributing f of the PARAMS(2) value, which should be at least 1.0 (in addition, f setting PARAMS(1) to zero will select the number of contributing * pixels so as to utilise the full width of the kernel, out to where it * reaches zero). This scheme gives similar results to the * AST__SINCSINC scheme, which it resembles. * - AST__SINCGAUSS: This scheme uses a kernel of the form * sinc(pi*x).exp(-k*x*x), with k a positive constant. Here, the sinc() * kernel is rolled off using a Gaussian envelope which is specified by c giving its full-width at half-maximum (FWHM) by means of the "params[1]" c value, which should be at least 0.1 (in addition, setting "params[0]" f giving its full-width at half-maximum (FWHM) by means of the PARAMS(2) f value, which should be at least 0.1 (in addition, setting PARAMS(1) * to zero will select the number of contributing pixels so as to utilise * the width of the kernel out to where the envelope declines to 1% of its * maximum value). On astronomical images and spectra, good results are * often obtained by approximately matching the FWHM of the c envelope function, given by "params[1]", to the point spread function f envelope function, given by PARAMS(2), to the point spread function * of the input data. However, there does not seem to be any theoretical * reason for this. * - AST__SOMB: This scheme uses a somb(pi*x) kernel (a "sombrero" * function), where x is the pixel offset from the interpolation point * and somb(z)=2*J1(z)/z (J1 is a Bessel function of the first kind of * order 1). It is similar to the AST__SINC kernel, and has the same * parameter usage. * - AST__SOMBCOS: This scheme uses a kernel of the form * somb(pi*x).cos(k*pi*x), with k a constant, out to the point where * cos(k*pi*x) goes to zero, and zero beyond. It is similar to the * AST__SINCCOS kernel, and has the same parameter usage. * * In addition, the following schemes are provided which are not based * on a 1-dimensional kernel: * * - AST__BLOCKAVE: This scheme simply takes an average of all the * pixels on the input grid in a cube centred on the interpolation * point. The number of pixels in the cube is determined by the c value of the first element of the "params" array, which gives f value of the first element of the PARAMS array, which gives * the number of pixels in each dimension on either side of the c central point. Hence a block of (2 * params[0])^ndim_in f central point. Hence a block of (2 * PARAMS(1))**NDIM_IN * pixels in the input grid will be examined to determine the * value of the output pixel. If the variance is not being used c (var_in or var_out = NULL) then all valid pixels in this cube f (USEVAR = .FALSE.) then all valid pixels in this cube * will be averaged in to the result with equal weight. * If variances are being used, then each input pixel will be * weighted proportionally to the reciprocal of its variance; any * pixel without a valid variance will be discarded. This scheme * is suitable where the output grid is much coarser than the * input grid; if the ratio of pixel sizes is R then a suitable c value of params[0] may be R/2. f value of PARAMS(1) may be R/2. * c Finally, supplying the following values for "interp" allows you c to implement your own sub-pixel interpolation scheme by means of c your own function. You should supply a pointer to this function c via the "finterp" parameter: f Finally, supplying the following values for INTERP allows you to f implement your own sub-pixel interpolation scheme by means of f your own routine. You should supply the name of this routine via f the FINTERP argument: * c - AST__UKERN1: In this scheme, you supply a function to evaluate c your own 1-dimensional interpolation kernel, which is then used c to perform sub-pixel interpolation (as described above). The c function you supply should have the same interface as the c fictitious astUkern1 function (q.v.). In addition, a value c should be given via "params[0]" to specify the number of c neighbouring pixels which are to contribute to each interpolated c value (in the same way as for the pre-defined interpolation c schemes described above). Other elements of the "params" array c are available to pass values to your interpolation function. f - AST__UKERN1: In this scheme, you supply a routine to evaluate f your own 1-dimensional interpolation kernel, which is then used f to perform sub-pixel interpolation (as described above). The f routine you supply should have the same interface as the f fictitious AST_UKERN1 routine (q.v.). In addition, a value f should be given via PARAMS(1) to specify the number of f neighbouring pixels which are to contribute to each interpolated f value (in the same way as for the pre-defined interpolation f schemes described above). Other elements of the PARAMS array f are available to pass values to your interpolation routine. * c - AST__UINTERP: This is a completely general scheme, in which c your interpolation function has access to all of the input c data. This allows you to implement any interpolation algorithm c you choose, which could (for example) be non-linear, or c adaptive. In this case, the astResample functions play no c role in the sub-pixel interpolation process and simply handle c the geometrical transformation of coordinates and other c housekeeping. The function you supply should have the same c interface as the fictitious astUinterp function (q.v.). In this c case, the "params" parameter is not used by astResample, but c is available to pass values to your interpolation function. f - AST__UINTERP: This is a completely general scheme, in which f your interpolation routine has access to all of the input f data. This allows you to implement any interpolation algorithm f you choose, which could (for example) be non-linear, or f adaptive. In this case, the AST_RESAMPLE functions play no f role in the sub-pixel interpolation process and simply handle f the geometrical transformation of coordinates and other f housekeeping. The routine you supply should have the same f interface as the fictitious AST_UINTERP routine (q.v.). In this f case, the PARAMS argument is not used by AST_RESAMPLE, but f is available to pass values to your interpolation routine. * Control Flags: c The following flags are defined in the "ast.h" header file and f The following flags are defined in the AST_PAR include file and * may be used to provide additional control over the resampling * process. Having selected a set of flags, you should supply the c bitwise OR of their values via the "flags" parameter: f sum of their values via the FLAGS argument: * * - AST__NOBAD: Indicates that any output array elements for which no * resampled value could be obtained should be left set to the value * they had on entry to this function. If this flag is not supplied, * such output array elements are set to the value supplied for c parameter "badval". Note, this flag cannot be used in conjunction f argument BADVAL. Note, this flag cannot be used in conjunction * with the AST__CONSERVEFLUX flag (an error will be reported if both * flags are specified). * - AST__URESAMP1, 2, 3 & 4: A set of four flags which are * reserved for your own use. They may be used to pass private c information to any sub-pixel interpolation function which you f information to any sub-pixel interpolation routine which you * implement yourself. They are ignored by all the pre-defined * interpolation schemes. * - AST__USEBAD: Indicates that there may be bad pixels in the * input array(s) which must be recognised by comparing with the c value given for "badval" and propagated to the output array(s). f value given for BADVAL and propagated to the output array(s). * If this flag is not set, all input values are treated literally c and the "badval" value is only used for flagging output array f and the BADVAL value is only used for flagging output array * values. f - AST__USEVAR: Indicates that variance information should be f processed in order to provide estimates of the statistical error f associated with the resampled values. If this flag is not set, f no variance processing will occur and the IN_VAR and OUT_VAR f arrays will not be used. (Note that this flag is only available f in the Fortran interface to AST.) * - AST__CONSERVEFLUX: Indicates that the output pixel values should * be scaled in such a way as to preserve (approximately) the total data * value in a feature on the sky. Without this flag, each output pixel * value represents an instantaneous sample of the input data values at * the corresponding input position. This is appropriate if the input * data represents the spatial density of some quantity (e.g. surface * brightness in Janskys per square arc-second) because the output * pixel values will have the same normalisation and units as the * input pixel values. However, if the input data values represent * flux (or some other physical quantity) per pixel, then the * AST__CONSERVEFLUX flag could be used. This causes each output * pixel value to be scaled by the ratio of the output pixel size to * the input pixel size. * * This flag can only be used if the Mapping is successfully approximated * by one or more linear transformations. Thus an error will be reported * if it used when the c "tol" parameter f TOL argument * is set to zero (which stops the use of linear approximations), or * if the Mapping is too non-linear to be approximated by a piece-wise * linear transformation. The ratio of output to input pixel size is * evaluated once for each panel of the piece-wise linear approximation to * the Mapping, and is assumed to be constant for all output pixels in the * panel. The scaling factors for adjacent panels will in general * differ slightly, and so the joints between panels may be visible when * viewing the output image at high contrast. If this is a problem, * reduce the value of the c "tol" parameter f TOL argument * until the difference between adjacent panels is sufficiently small * to be insignificant. * * Note, this flag cannot be used in conjunction with the AST__NOBAD * flag (an error will be reported if both flags are specified). * Propagation of Missing Data: * Unless the AST__NOBAD flag is specified, instances of missing data * (bad pixels) in the output grid are c identified by occurrences of the "badval" value in the "out" f identified by occurrences of the BADVAL value in the OUT * array. These may be produced if any of the following happen: * * - The input position (the transformed position of the output * pixel's centre) lies outside the boundary of the grid of input * pixels. * - The input position lies inside the boundary of a bad input * pixel. In this context, an input pixel is considered bad if its c data value is equal to "badval" and the AST__USEBAD flag is c set via the "flags" parameter. f data value is equal to BADVAL and the AST__USEBAD flag is f set via the FLAGS argument. * (Positions which have half-integral coordinate values, and * therefore lie on a pixel boundary, are regarded as lying within * the pixel with the larger, i.e. more positive, index.) * - The set of neighbouring input pixels (excluding those which * are bad) is unsuitable for calculating an interpolated * value. Whether this is true may depend on the sub-pixel * interpolation scheme in use. * - The interpolated value lies outside the range which can be c represented using the data type of the "out" array. f represented using the data type of the OUT array. * * In addition, associated output variance estimates (if c calculated) may be declared bad and flagged with the "badval" c value in the "out_var" array under any of the following f calculated) may be declared bad and flagged with the BADVAL f value in the OUT_VAR array under any of the following * circumstances: * c - The associated resampled data value (in the "out" array) is bad. f - The associated resampled data value (in the OUT array) is bad. * - The set of neighbouring input pixels which contributed to the * output data value do not all have valid variance estimates * associated with them. In this context, an input variance * estimate may be regarded as bad either because it has the value c "badval" (and the AST__USEBAD flag is set), or because it is f BADVAL (and the AST__USEBAD flag is set), or because it is * negative. * - The set of neighbouring input pixels for which valid variance * values are available is unsuitable for calculating an overall * variance value. Whether this is true may depend on the sub-pixel * interpolation scheme in use. * - The variance value lies outside the range which can be c represented using the data type of the "out_var" array. f represented using the data type of the OUT_VAR array. * * If the AST__NOBAD flag is specified via c parameter "flags", f argument FLAGS, * then output array elements that would otherwise be set to c "badval" f BADVAL * are instead left holding the value they had on entry to this * function. The number of such array elements is returned as * the function value. *-- */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_RESAMPLE(X,Xtype) \ static int Resample##X( AstMapping *this, int ndim_in, \ const int lbnd_in[], const int ubnd_in[], \ const Xtype in[], const Xtype in_var[], \ int interp, void (* finterp)( void ), \ const double params[], int flags, double tol, \ int maxpix, Xtype badval, \ int ndim_out, const int lbnd_out[], \ const int ubnd_out[], const int lbnd[], \ const int ubnd[], Xtype out[], Xtype out_var[], int *status ) { \ \ /* Local Variables: */ \ astDECLARE_GLOBALS /* Thread-specific data */ \ AstMapping *simple; /* Pointer to simplified Mapping */ \ int idim; /* Loop counter for coordinate dimensions */ \ int nin; /* Number of Mapping input coordinates */ \ int nout; /* Number of Mapping output coordinates */ \ int npix; /* Number of pixels in output region */ \ int result; /* Result value to return */ \ int64_t mpix; /* Number of pixels for testing */ \ \ /* Initialise. */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get a pointer to a structure holding thread-specific global data values */ \ astGET_GLOBALS(this); \ \ /* Obtain values for the Nin and Nout attributes of the Mapping. */ \ nin = astGetNin( this ); \ nout = astGetNout( this ); \ \ /* If OK, check that the number of input grid dimensions matches the \ number required by the Mapping and is at least 1. Report an error \ if necessary. */ \ if ( astOK && ( ( ndim_in != nin ) || ( ndim_in < 1 ) ) ) { \ astError( AST__NGDIN, "astResample"#X"(%s): Bad number of input grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_in ); \ if ( ndim_in != nin ) { \ astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ "to specify an input position.", status, \ astGetClass( this ), nin, ( nin == 1 ) ? "" : "s" ); \ } \ } \ \ /* If OK, also check that the number of output grid dimensions matches \ the number required by the Mapping and is at least 1. Report an \ error if necessary. */ \ if ( astOK && ( ( ndim_out != nout ) || ( ndim_out < 1 ) ) ) { \ astError( AST__NGDIN, "astResample"#X"(%s): Bad number of output grid " \ "dimensions (%d).", status, astGetClass( this ), ndim_out ); \ if ( ndim_out != nout ) { \ astError( AST__NGDIN, "The %s given generates %s%d coordinate " \ "value%s for each output position.", status, astGetClass( this ), \ ( nout < ndim_out ) ? "only " : "", nout, \ ( nout == 1 ) ? "" : "s" ); \ } \ } \ \ /* Check that the lower and upper bounds of the input grid are \ consistent. Report an error if any pair is not. Also get the number \ of pixels in the input grid. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_in; idim++ ) { \ if ( lbnd_in[ idim ] > ubnd_in[ idim ] ) { \ astError( AST__GBDIN, "astResample"#X"(%s): Lower bound of " \ "input grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_in[ idim ], ubnd_in[ idim ] ); \ astError( AST__GBDIN, "Error in input dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_in[ idim ] - lbnd_in[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the input. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astResample"#X"(%s): Supplied input array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Check that the positional accuracy tolerance supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( tol < 0.0 ) ) { \ astError( AST__PATIN, "astResample"#X"(%s): Invalid positional " \ "accuracy tolerance (%.*g pixel).", status, \ astGetClass( this ), DBL_DIG, tol ); \ astError( AST__PATIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the initial scale size in pixels supplied is valid and \ report an error if necessary. */ \ if ( astOK && ( maxpix < 0 ) ) { \ astError( AST__SSPIN, "astResample"#X"(%s): Invalid initial scale " \ "size in pixels (%d).", status, astGetClass( this ), maxpix ); \ astError( AST__SSPIN, "This value should not be less than zero." , status); \ } \ \ /* Check that the lower and upper bounds of the output grid are \ consistent. Report an error if any pair is not. Also get the \ number of pixels in the output array. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_out; idim++ ) { \ if ( lbnd_out[ idim ] > ubnd_out[ idim ] ) { \ astError( AST__GBDIN, "astResample"#X"(%s): Lower bound of " \ "output grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd_out[ idim ], ubnd_out[ idim ] ); \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } else { \ mpix *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the output. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astResample"#X"(%s): Supplied output array " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* Similarly check the bounds of the output region. */ \ mpix = 1; \ if ( astOK ) { \ for ( idim = 0; idim < ndim_out; idim++ ) { \ if ( lbnd[ idim ] > ubnd[ idim ] ) { \ astError( AST__GBDIN, "astResample"#X"(%s): Lower bound of " \ "output region (%d) exceeds corresponding upper " \ "bound (%d).", status, astGetClass( this ), \ lbnd[ idim ], ubnd[ idim ] ); \ \ /* Also check that the output region lies wholly within the output \ grid. */ \ } else if ( lbnd[ idim ] < lbnd_out[ idim ] ) { \ astError( AST__GBDIN, "astResample"#X"(%s): Lower bound of " \ "output region (%d) is less than corresponding " \ "bound of output grid (%d).", status, astGetClass( this ), \ lbnd[ idim ], lbnd_out[ idim ] ); \ } else if ( ubnd[ idim ] > ubnd_out[ idim ] ) { \ astError( AST__GBDIN, "astResample"#X"(%s): Upper bound of " \ "output region (%d) exceeds corresponding " \ "bound of output grid (%d).", status, astGetClass( this ), \ ubnd[ idim ], ubnd_out[ idim ] ); \ } else { \ mpix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* Say which dimension produced the error. */ \ if ( !astOK ) { \ astError( AST__GBDIN, "Error in output dimension %d.", status, \ idim + 1 ); \ break; \ } \ } \ } \ \ /* Report an error if there are too many pixels in the output region. */ \ if ( astOK && (int) mpix != mpix ) { \ astError( AST__EXSPIX, "astResample"#X"(%s): Supplied output region " \ "contains too many pixels (%g): must be fewer than %d.", \ status, astGetClass( this ), (double) mpix, INT_MAX ); \ } \ \ /* If we are conserving flux, check "tol" is not zero. */ \ if( ( flags & AST__CONSERVEFLUX ) && astOK ) { \ if( tol == 0.0 ) { \ astError( AST__CNFLX, "astResample"#X"(%s): Flux conservation was " \ "requested but cannot be performed because zero tolerance " \ "was also specified.", status, astGetClass( this ) ); \ \ /* Also check "nin" and "nout" are equal. */ \ } else if( nin != nout ) { \ astError( AST__CNFLX, "astResample"#X"(%s): Flux conservation was " \ "requested but cannot be performed because the Mapping " \ "has different numbers of inputs and outputs.", status, \ astGetClass( this ) ); \ } \ } \ \ /* If OK, loop to determine how many pixels require resampled values. */ \ simple = NULL; \ if ( astOK ) { \ npix = 1; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ npix *= ubnd[ idim ] - lbnd[ idim ] + 1; \ } \ \ /* If there are sufficient pixels to make it worthwhile, simplify the \ Mapping supplied to improve performance. Otherwise, just clone the \ Mapping pointer. Note we save a pointer to the original Mapping so \ that lower-level functions can use it if they need to report an \ error. */ \ unsimplified_mapping = this; \ if ( npix > 1024 ) { \ simple = astSimplify( this ); \ } else { \ simple = astClone( this ); \ } \ } \ \ /* Report an error if the inverse transformation of this simplified \ Mapping is not defined. */ \ if ( !astGetTranInverse( simple ) && astOK ) { \ astError( AST__TRNND, "astResample"#X"(%s): An inverse coordinate " \ "transformation is not defined by the %s supplied.", status, \ astGetClass( unsimplified_mapping ), \ astGetClass( unsimplified_mapping ) ); \ } \ \ /* Perform the resampling. Note that we pass all gridded data, the \ interpolation function and the bad pixel value by means of pointer \ types that obscure the underlying data type. This is to avoid \ having to replicate functions unnecessarily for each data \ type. However, we also pass an argument that identifies the data \ type we have obscured. */ \ result = ResampleAdaptively( simple, ndim_in, lbnd_in, ubnd_in, \ (const void *) in, (const void *) in_var, \ TYPE_##X, interp, finterp, \ params, flags, tol, maxpix, \ (const void *) &badval, \ ndim_out, lbnd_out, ubnd_out, \ lbnd, ubnd, \ (void *) out, (void *) out_var, status ); \ \ /* Annul the pointer to the simplified/cloned Mapping. */ \ simple = astAnnul( simple ); \ \ /* If an error occurred, clear the returned result. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_RESAMPLE(LD,long double) #endif MAKE_RESAMPLE(D,double) MAKE_RESAMPLE(F,float) MAKE_RESAMPLE(L,long int) MAKE_RESAMPLE(UL,unsigned long int) MAKE_RESAMPLE(K,INT_BIG) MAKE_RESAMPLE(UK,UINT_BIG) MAKE_RESAMPLE(I,int) MAKE_RESAMPLE(UI,unsigned int) MAKE_RESAMPLE(S,short int) MAKE_RESAMPLE(US,unsigned short int) MAKE_RESAMPLE(B,signed char) MAKE_RESAMPLE(UB,unsigned char) /* Undefine the macro. */ #undef MAKE_RESAMPLE static int ResampleAdaptively( AstMapping *this, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, DataType type, int interp, void (* finterp)( void ), const double *params, int flags, double tol, int maxpix, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, void *out, void *out_var, int *status ) { /* * Name: * ResampleAdaptively * Purpose: * Resample a section of a data grid adaptively. * Type: * Private function. * Synopsis: * #include "mapping.h" * int ResampleAdaptively( AstMapping *this, int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const void *in, const void *in_var, * DataType type, int interp, void (* finterp)( void ), * const double *params, int flags, double tol, * int maxpix, const void *badval_ptr, * int ndim_out, const int *lbnd_out, * const int *ubnd_out, const int *lbnd, * const int *ubnd, void *out, void *out_var ) * Class Membership: * Mapping member function. * Description: * This function resamples a rectangular grid of data (with any * number of dimensions) into a specified section of another * rectangular grid (with a possibly different number of * dimensions). The coordinate transformation used to convert * output pixel coordinates into positions in the input grid is * given by the inverse transformation of the Mapping which is * supplied. Any pixel interpolation scheme may be specified for * interpolating between the pixels of the input grid. * * This function is very similar to ResampleWithBlocking and * ResampleSection which lie below it in the calling * hierarchy. However, this function also attempts to adapt to the * Mapping supplied and to sub-divide the section being resampled * into smaller sections within which a linear approximation to the * Mapping may be used. This reduces the number of Mapping * evaluations, thereby improving efficiency particularly when * complicated Mappings are involved. * Parameters: * this * Pointer to a Mapping, whose inverse transformation may be * used to transform the coordinates of pixels in the output * grid into associated positions in the input grid, from which * the output pixel values should be derived (by interpolation * if necessary). * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be resampled (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the resampled data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * interp * A value selected from a set of pre-defined macros to identify * which sub-pixel interpolation algorithm should be used. * finterp * If "interp" is set to a value which requires a user-supplied * function, then a pointer to that function shoild be given * here. Otherwise, this value is not used and may be a NULL * pointer. * params * Pointer to an optional array of parameters that may be passed * to the interpolation algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * flags * The bitwise OR of a set of flag values which provide * additional control over the resampling operation. * tol * The maximum permitted positional error in transforming output * pixel positions into the input grid in order to resample * it. This should be expressed as a displacement in pixels in * the input grid's coordinate system. If the Mapping's inverse * transformation can be approximated by piecewise linear * functions to this accuracy, then such functions may be used * instead of the Mapping in order to improve * performance. Otherwise, every output pixel position will be * transformed individually using the Mapping. * * If linear approximation is not required, a "tol" value of * zero may be given. This will ensure that the Mapping is used * without any approximation. * maxpix * A value which specifies the largest scale size on which to * search for non-linearities in the Mapping supplied. This * value should be expressed as a number of pixels in the output * grid. The function will break the output section specified * into smaller sub-sections (if necessary), each no larger than * "maxpix" pixels in any dimension, before it attempts to * approximate the Mapping by a linear function over each * sub-section. * * If the value given is larger than the largest dimension of * the output section (the normal recommendation), the function * will initially search for non-linearity on a scale determined * by the size of the output section. This is almost always * satisfactory. Very occasionally, however, a Mapping may * appear linear on this scale but nevertheless have smaller * irregularities (e.g. "holes") in it. In such cases, "maxpix" * may be set to a suitably smaller value so as to ensure this * non-linearity is not overlooked. Typically, a value of 50 to * 100 pixels might be suitable and should have little effect on * performance. * * If too small a value is given, however, it will have the * effect of preventing linear approximation occurring at all * (equivalent to setting "tol" to zero). Although this may * degrade performance, accurate results will still be obtained. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. Unless the AST__NOBAD flag is set, the same value will * also be used to flag any output array elements for which * resampled values could not be obtained. The output arrays(s) * may be flagged with this value whether or not the AST__USEBAD * flag is set (the function return value indicates whether any * such values have been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the first pixel in the * section of the output data grid for which a value is * required. * ubnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the last pixel in the * section of the output data grid for which a value is * required. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the output grid for which resampled values are * required. This section should lie wholly within the extent of * the output grid (as defined by the "lbnd_out" and "ubnd_out" * arrays). Regions of the output grid lying outside this section * will not be modified. * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * Returned Value: * The number of output grid points for which no valid output value * could be obtained. * 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: */ double *flbnd; /* Array holding floating point lower bounds */ double *fubnd; /* Array holding floating point upper bounds */ double *linear_fit; /* Pointer to array of fit coefficients */ int *hi; /* Pointer to array of section upper bounds */ int *lo; /* Pointer to array of section lower bounds */ int coord_out; /* Loop counter for output coordinates */ int dim; /* Output section dimension size */ int dimx; /* Dimension with maximum section extent */ int divide; /* Sub-divide the output section? */ int i; /* Loop count */ int isLinear; /* Is the transformation linear? */ int mxdim; /* Largest output section dimension size */ int npix; /* Number of pixels in output section */ int npoint; /* Number of points for obtaining a fit */ int nvertex; /* Number of vertices of output section */ int result; /* Result value to return */ int toobig; /* Section too big (must sub-divide)? */ int toosmall; /* Section too small to sub-divide? */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ npix = 1; mxdim = 0; dimx = 1; nvertex = 1; /* Loop through the output grid dimensions. */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { /* Obtain the extent in each dimension of the output section which is to receive resampled values, and calculate the total number of pixels it contains. */ dim = ubnd[ coord_out ] - lbnd[ coord_out ] + 1; npix *= dim; /* Find the maximum dimension size of this output section and note which dimension has this size. */ if ( dim > mxdim ) { mxdim = dim; dimx = coord_out; } /* Calculate how many vertices the output section has. */ nvertex *= 2; } /* Calculate how many sample points will be needed (by the astLinearApprox function) to obtain a linear fit to the Mapping's inverse transformation. */ npoint = 1 + 4 * ndim_out + 2 * nvertex; /* If the number of pixels in the output section is not at least 4 times this number, we will probably not save significant time by attempting to obtain a linear fit, so note that the output section is too small. */ toosmall = ( npix < ( 4 * npoint ) ); /* Note if the maximum dimension of the output section exceeds the user-supplied scale factor. */ toobig = ( maxpix < mxdim ); /* Assume the Mapping is significantly non-linear before deciding whether to sub-divide the output section. */ linear_fit = NULL; /* If the output section is too small to be worth obtaining a linear fit, or if the accuracy tolerance is zero, we will not sub-divide. This means that the Mapping will be used to transform each pixel's coordinates and no linear approximation will be used. */ if ( toosmall || ( tol == 0.0 ) ) { divide = 0; /* Otherwise, if the largest output section dimension exceeds the scale length given, we will sub-divide. This offers the possibility of obtaining a linear approximation to the Mapping over a reduced range of output coordinates (which will be handled by a recursive invocation of this function). */ } else if ( toobig ) { divide = 1; /* If neither of the above apply, then attempt to fit a linear approximation to the Mapping's inverse transformation over the range of coordinates covered by the output section. We need to temporarily copy the integer bounds into floating point arrays to use astLinearApprox. */ } else { /* Allocate memory for floating point bounds and for the coefficient array */ flbnd = astMalloc( sizeof( double )*(size_t) ndim_out ); fubnd = astMalloc( sizeof( double )*(size_t) ndim_out ); linear_fit = astMalloc( sizeof( double )* (size_t) ( ndim_in*( ndim_out + 1 ) ) ); if( astOK ) { /* Copy the bounds into these arrays, and change them so that they refer to the lower and upper edges of the cell rather than the centre. This is essential if one of the axes is spanned by a single cell, since otherwise the upper and lower bounds would be identical. */ for( i = 0; i < ndim_out; i++ ) { flbnd[ i ] = (double) lbnd[ i ] - 0.5; fubnd[ i ] = (double) ubnd[ i ] + 0.5; } /* Get the linear approximation to the inverse transformation. The astLinearApprox function fits the forward transformation so temporarily invert the Mapping in order to get a fit to the inverse transformation. */ astInvert( this ); isLinear = astLinearApprox( this, flbnd, fubnd, tol, linear_fit ); astInvert( this ); /* Free the coeff array if the inverse transformation is not linear. */ if( !isLinear ) linear_fit = astFree( linear_fit ); } else { linear_fit = astFree( linear_fit ); } /* Free resources */ flbnd = astFree( flbnd ); fubnd = astFree( fubnd ); /* If a linear fit was obtained, we will use it and therefore do not wish to sub-divide further. Otherwise, we sub-divide in the hope that this may result in a linear fit next time. */ divide = !linear_fit; } /* If no sub-division is required, perform resampling (in a memory-efficient manner, since the section we are resampling might still be very large). This will use the linear fit, if obtained above. */ if ( astOK ) { if ( !divide ) { result = ResampleWithBlocking( this, linear_fit, ndim_in, lbnd_in, ubnd_in, in, in_var, type, interp, finterp, params, flags, badval_ptr, ndim_out, lbnd_out, ubnd_out, lbnd, ubnd, out, out_var, status ); /* Otherwise, allocate workspace to perform the sub-division. */ } else { lo = astMalloc( sizeof( int ) * (size_t) ndim_out ); hi = astMalloc( sizeof( int ) * (size_t) ndim_out ); if ( astOK ) { /* Initialise the bounds of a new output section to match the original output section. */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { lo[ coord_out ] = lbnd[ coord_out ]; hi[ coord_out ] = ubnd[ coord_out ]; } /* Replace the upper bound of the section's largest dimension with the mid-point of the section along this dimension, rounded downwards. */ hi[ dimx ] = (int) floor( 0.5 * (double) ( lbnd[ dimx ] + ubnd[ dimx ] ) ); /* Resample the resulting smaller section using a recursive invocation of this function. */ result = ResampleAdaptively( this, ndim_in, lbnd_in, ubnd_in, in, in_var, type, interp, finterp, params, flags, tol, maxpix, badval_ptr, ndim_out, lbnd_out, ubnd_out, lo, hi, out, out_var, status ); /* Now set up a second section which covers the remaining half of the original output section. */ lo[ dimx ] = hi[ dimx ] + 1; hi[ dimx ] = ubnd[ dimx ]; /* If this section contains pixels, resample it in the same way, summing the returned values. */ if ( lo[ dimx ] <= hi[ dimx ] ) { result += ResampleAdaptively( this, ndim_in, lbnd_in, ubnd_in, in, in_var, type, interp, finterp, params, flags, tol, maxpix, badval_ptr, ndim_out, lbnd_out, ubnd_out, lo, hi, out, out_var, status ); } } /* Free the workspace. */ lo = astFree( lo ); hi = astFree( hi ); } } /* If coefficients for a linear fit were obtained, then free the space they occupy. */ if ( linear_fit ) linear_fit = astFree( linear_fit ); /* If an error occurred, clear the returned result. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static int ResampleSection( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, DataType type, int interp, void (* finterp)( void ), const double *params, double factor, int flags, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, void *out, void *out_var, int *status ) { /* * Name: * ResampleSection * Purpose: * Resample a section of a data grid. * Type: * Private function. * Synopsis: * #include "mapping.h" * int ResampleSection( AstMapping *this, const double *linear_fit, * int ndim_in, const int *lbnd_in, const int *ubnd_in, * const void *in, const void *in_var, * DataType type, int interp, void (* finterp)( void ), * const double *params, double factor, int flags, * const void *badval_ptr, int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const int *lbnd, const int *ubnd, * void *out, void *out_var ) * Class Membership: * Mapping member function. * Description: * This function resamples a rectangular grid of data (with any * number of dimensions) into a specified section of another * rectangular grid (with a possibly different number of * dimensions). The coordinate transformation used is given by the * inverse transformation of the Mapping which is supplied or, * alternatively, by a linear approximation fitted to a Mapping's * inverse transformation. Any pixel interpolation scheme may be * specified for interpolating between the pixels of the input * grid. * Parameters: * this * Pointer to a Mapping, whose inverse transformation may be * used to transform the coordinates of pixels in the output * grid into associated positions in the input grid, from which * the output pixel values should be derived (by interpolation * if necessary). * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's inverse coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * inverse transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be resampled (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the resampled data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * interp * A value selected from a set of pre-defined macros to identify * which sub-pixel interpolation algorithm should be used. * finterp * If "interp" is set to a value which requires a user-supplied * function, then a pointer to that function shoild be given * here. Otherwise, this value is not used and may be a NULL * pointer. * params * Pointer to an optional array of parameters that may be passed * to the interpolation algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * factor * A factor by which to scale the resampled output data values before * returning them. If flux is being conserved this should be set to * the ratio of the output pixel size to the input pixel size in the * section. Otherwise it should be set to 1.0. * flags * The bitwise OR of a set of flag values which provide * additional control over the resampling operation. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. Unless the AST__NOBAD flag is set, the same value will * also be used to flag any output array elements for which * resampled values could not be obtained. The output arrays(s) * may be flagged with this value whether or not the AST__USEBAD * flag is set (the function return value indicates whether any * such values have been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the first pixel in the * section of the output data grid for which a value is * required. * ubnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the last pixel in the * section of the output data grid for which a value is * required. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the output grid for which resampled values are * required. This section should lie wholly within the extent of * the output grid (as defined by the "lbnd_out" and "ubnd_out" * arrays). Regions of the output grid lying outside this section * will not be modified. * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * Returned Value: * The number of output grid points for which no valid output value * could be obtained. * Notes: * - This function does not take steps to limit memory usage if the * grids supplied are large. To resample large grids in a more * memory-efficient way, the ResampleWithBlocking function should * be used. * - 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 /* Thread-specific data */ AstPointSet *pset_in; /* Input PointSet for transformation */ AstPointSet *pset_out; /* Output PointSet for transformation */ const double *grad; /* Pointer to gradient matrix of linear fit */ const double *par; /* Pointer to parameter array */ const double *zero; /* Pointer to zero point array of fit */ double **ptr_in; /* Pointer to input PointSet coordinates */ double **ptr_out; /* Pointer to output PointSet coordinates */ double *accum; /* Pointer to array of accumulated sums */ double fwhm; /* Full width half max. of gaussian */ double lpar[ 1 ]; /* Local parameter array */ double x1; /* Interim x coordinate value */ double y1; /* Interim y coordinate value */ int *dim; /* Pointer to array of output pixel indices */ int *offset; /* Pointer to array of output pixel offsets */ int *stride; /* Pointer to array of output grid strides */ int conserve; /* Conserve flux? */ int coord_in; /* Loop counter for input dimensions */ int coord_out; /* Loop counter for output dimensions */ int done; /* All pixel indices done? */ int i1; /* Interim offset into "accum" array */ int i2; /* Final offset into "accum" array */ int idim; /* Loop counter for dimensions */ int ix; /* Loop counter for output x coordinate */ int iy; /* Loop counter for output y coordinate */ int nbad; /* Number of pixels assigned a bad value */ int neighb; /* Number of neighbouring pixels */ int npoint; /* Number of output points (pixels) */ int off1; /* Interim pixel offset into output array */ int off; /* Final pixel offset into output array */ int point; /* Counter for output points (pixels ) */ int result; /* Result value to be returned */ int s; /* Temporary variable for strides */ int usevar; /* Process variance array? */ void (* gifunc)( void ); /* General interpolation function */ void (* kernel)( double, const double [], int, double *, int * ); /* Kernel fn. */ void (* fkernel)( double, const double [], int, double * ); /* User kernel fn. */ /* Initialise. */ result = 0; /* Get a pointer to a structure holding thread-specific global data values */ astGET_GLOBALS(this); /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ pset_in = NULL; ptr_in = NULL; neighb = 0; gifunc = NULL; kernel = NULL; fkernel = NULL; /* See if we are conserving flux */ conserve = flags & AST__CONSERVEFLUX; /* If we are conserving flux, then we need some way to tell which output array elements have been assigned a value and which have not. If the AST__NOBAD flag has been specified then this is not possible to report an error. */ if( ( flags & AST__NOBAD ) && conserve ) { astError( AST__BADFLG, "astResample: Cannot use the AST__NOBAD and " "AST__CONSERVEFLUX flags together (programming error)." , status); } /* Calculate the number of output points, as given by the product of the output grid dimensions. */ for ( npoint = 1, coord_out = 0; coord_out < ndim_out; coord_out++ ) { npoint *= ubnd[ coord_out ] - lbnd[ coord_out ] + 1; } /* Allocate workspace. */ offset = astMalloc( sizeof( int ) * (size_t) npoint ); stride = astMalloc( sizeof( int ) * (size_t) ndim_out ); if ( astOK ) { /* Calculate the stride for each output grid dimension. */ off = 0; s = 1; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { stride[ coord_out ] = s; s *= ubnd_out[ coord_out ] - lbnd_out[ coord_out ] + 1; } /* A linear fit to the Mapping is available. */ /* ========================================= */ if ( linear_fit ) { /* If a linear fit to the Mapping has been provided, then obtain pointers to the array of gradients and zero-points comprising the fit. */ grad = linear_fit + ndim_in; zero = linear_fit; /* Create a PointSet to hold the input grid coordinates and obtain an array of pointers to its coordinate data. */ pset_in = astPointSet( npoint, ndim_in, "", status ); ptr_in = astGetPoints( pset_in ); if ( astOK ) { /* Initialise the count of output points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ( ndim_in == 1 ) && ( ndim_out == 1 ) ) { /* Loop through the pixels of the output grid and transform their x coordinates into the input grid's coordinate system using the linear fit supplied. Store the results in the PointSet created above. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = zero[ 0 ] + grad[ 0 ] * (double) ix; /* Calculate the offset of each pixel within the output array. */ offset[ point ] = ix - lbnd_out[ 0 ]; point++; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ( ndim_in == 2 ) && ( ndim_out == 2 ) ) { /* Loop through the range of y coordinates in the output grid and calculate interim values of the input coordinates using the linear fit supplied. */ for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { x1 = zero[ 0 ] + grad[ 1 ] * (double) iy; y1 = zero[ 1 ] + grad[ 3 ] * (double) iy; /* Also calculate an interim pixel offset into the output array. */ off1 = stride[ 1 ] * ( iy - lbnd_out[ 1 ] ) - lbnd_out[ 0 ]; /* Now loop through the range of output x coordinates and calculate the final values of the input coordinates, storing the results in the PointSet created above. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = x1 + grad[ 0 ] * (double) ix; ptr_in[ 1 ][ point ] = y1 + grad[ 2 ] * (double) ix; /* Also calculate final pixel offsets into the output array. */ offset[ point ] = off1 + ix; point++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ accum = astMalloc( sizeof( double ) * (size_t) ( ndim_in * ndim_out ) ); dim = astMalloc( sizeof( int ) * (size_t) ndim_out ); if ( astOK ) { /* Initialise an array of pixel indices for the output grid which refer to the first pixel for which we require a value. Also calculate the offset of this pixel within the output array. */ off = 0; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { dim[ coord_out ] = lbnd[ coord_out ]; off += stride[ coord_out ] * ( dim[ coord_out ] - lbnd_out[ coord_out ] ); } /* To calculate each input grid coordinate we must perform a matrix multiply on the output grid coordinates (using the gradient matrix) and then add the zero points. However, since we will usually only be altering one output coordinate at a time (the least significant), we can avoid the full matrix multiply by accumulating partial sums for the most significant output coordinates and only altering those sums which need to change each time. The zero points never change, so we first fill the "most significant" end of the "accum" array with these. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { accum[ ( coord_in + 1 ) * ndim_out - 1 ] = zero[ coord_in ]; } coord_out = ndim_out - 1; /* Now loop to process each output pixel. */ for ( done = 0; !done; point++ ) { /* To generate the input coordinate that corresponds to the current output pixel, we work down from the most significant dimension whose index has changed since the previous pixel we considered (given by "coord_out"). For each affected dimension, we accumulate in "accum" the matrix sum (including the zero point) for that dimension and all higher output dimensions. We must accumulate a separate set of sums for each input coordinate we wish to produce. (Note that for the first pixel we process, all dimensions are considered "changed", so we start by initialising the whole "accum" array.) */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { i1 = coord_in * ndim_out; for ( idim = coord_out; idim >= 1; idim-- ) { i2 = i1 + idim; accum[ i2 - 1 ] = accum[ i2 ] + dim[ idim ] * grad[ i2 ]; } /* The input coordinate for each dimension is given by the accumulated sum for output dimension zero (giving the sum over all output dimensions). We do not store this in the "accum" array, but assign the result directly to the coordinate array of the PointSet created earlier. */ ptr_in[ coord_in ][ point ] = accum[ i1 ] + dim[ 0 ] * grad[ i1 ]; } /* Store the offset of the current pixel in the output array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next output pixel. */ coord_out = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the output array is updated accordingly. */ if ( dim[ coord_out ] < ubnd[ coord_out ] ) { dim[ coord_out ]++; off += stride[ coord_out ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the output pixel offset is decremented appropriately. */ } else { dim[ coord_out ] = lbnd[ coord_out ]; off -= stride[ coord_out ] * ( ubnd[ coord_out ] - lbnd[ coord_out ] ); /* All the output pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_out == ndim_out ); } } while ( !done ); } } /* Free the workspace. */ accum = astFree( accum ); dim = astFree( dim ); } } /* No linear fit to the Mapping is available. */ /* ========================================== */ } else { /* If flux conseravtion was requested, report an error, since we can only conserve flux if a linear approximation is available. */ if( conserve && astOK ) { astError( AST__CNFLX, "astResampleSection(%s): Flux conservation " "was requested but cannot be performed because either the Mapping " "is too non-linear, or the requested tolerance is too small.", status, astGetClass( this ) ); } /* Create a PointSet to hold the coordinates of the output pixels and obtain a pointer to its coordinate data. */ pset_out = astPointSet( npoint, ndim_out, "", status ); ptr_out = astGetPoints( pset_out ); if ( astOK ) { /* Initialise the count of output points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ndim_out == 1 && ndim_in == 1 ) { /* Loop through the required range of output x coordinates, assigning the coordinate values to the PointSet created above. Also store a pixel offset into the output array. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = (double) ix; offset[ point ] = ix - lbnd_out[ 0 ]; /* Increment the count of output pixels. */ point++; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ndim_out == 2 && ndim_in == 2 ) { /* Loop through the required range of output y coordinates, calculating an interim pixel offset into the output array. */ for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { off1 = stride[ 1 ] * ( iy - lbnd_out[ 1 ] ) - lbnd_out[ 0 ]; /* Loop through the required range of output x coordinates, assigning the coordinate values to the PointSet created above. Also store a final pixel offset into the output array. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = (double) ix; ptr_out[ 1 ][ point ] = (double) iy; offset[ point ] = off1 + ix; /* Increment the count of output pixels. */ point++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ dim = astMalloc( sizeof( int ) * (size_t) ndim_out ); if ( astOK ) { /* Initialise an array of pixel indices for the output grid which refer to the first pixel for which we require a value. Also calculate the offset of this pixel within the output array. */ off = 0; for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { dim[ coord_out ] = lbnd[ coord_out ]; off += stride[ coord_out ] * ( dim[ coord_out ] - lbnd_out[ coord_out ] ); } /* Loop to generate the coordinates of each output pixel. */ for ( done = 0; !done; point++ ) { /* Copy each pixel's coordinates into the PointSet created above. */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { ptr_out[ coord_out ][ point ] = (double) dim[ coord_out ]; } /* Store the offset of the pixel in the output array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next output pixel. */ coord_out = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the output array is updated accordingly. */ if ( dim[ coord_out ] < ubnd[ coord_out ] ) { dim[ coord_out ]++; off += stride[ coord_out ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the output pixel offset is decremented appropriately. */ } else { dim[ coord_out ] = lbnd[ coord_out ]; off -= stride[ coord_out ] * ( ubnd[ coord_out ] - lbnd[ coord_out ] ); /* All the output pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_out == ndim_out ); } } while ( !done ); } } /* Free the workspace. */ dim = astFree( dim ); } /* When all the output pixel coordinates have been generated, use the Mapping's inverse transformation to generate the input coordinates from them. Obtain an array of pointers to the resulting coordinate data. */ pset_in = astTransform( this, pset_out, 0, NULL ); ptr_in = astGetPoints( pset_in ); } /* Annul the PointSet containing the output coordinates. */ pset_out = astAnnul( pset_out ); } } /* Resample the input grid. */ /* ------------------------ */ /* Determine if a variance array is to be processed. */ usevar = ( in_var && out_var ); /* If the input coordinates have been produced successfully, identify the input grid resampling method to be used. */ if ( astOK ) { /* Nearest pixel. */ /* -------------- */ switch ( interp ) { case AST__NEAREST: /* Define a macro to use a "case" statement to invoke the nearest-pixel interpolation function appropriate to a given data type. */ #define CASE_NEAREST(X,Xtype) \ case ( TYPE_##X ): \ result = \ InterpolateNearest##X( ndim_in, lbnd_in, ubnd_in, \ (Xtype *) in, (Xtype *) in_var, \ npoint, offset, \ (const double *const *) ptr_in, \ flags, *( (Xtype *) badval_ptr ), \ (Xtype *) out, (Xtype *) out_var, status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_NEAREST(LD,long double) #endif CASE_NEAREST(D,double) CASE_NEAREST(F,float) CASE_NEAREST(L,long int) CASE_NEAREST(UL,unsigned long int) CASE_NEAREST(K,INT_BIG) CASE_NEAREST(UK,UINT_BIG) CASE_NEAREST(I,int) CASE_NEAREST(UI,unsigned int) CASE_NEAREST(S,short int) CASE_NEAREST(US,unsigned short int) CASE_NEAREST(B,signed char) CASE_NEAREST(UB,unsigned char) } break; /* Undefine the macro. */ #undef CASE_NEAREST /* Linear interpolation. */ /* --------------------- */ /* Note this is also the default if zero is given. */ case AST__LINEAR: case 0: /* Define a macro to use a "case" statement to invoke the linear interpolation function appropriate to a given data type. */ #define CASE_LINEAR(X,Xtype) \ case ( TYPE_##X ): \ result = \ InterpolateLinear##X( ndim_in, lbnd_in, ubnd_in,\ (Xtype *) in, (Xtype *) in_var, \ npoint, offset, \ (const double *const *) ptr_in, \ flags, *( (Xtype *) badval_ptr ), \ (Xtype *) out, (Xtype *) out_var, status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_LINEAR(LD,long double) #endif CASE_LINEAR(D,double) CASE_LINEAR(F,float) CASE_LINEAR(L,long int) CASE_LINEAR(UL,unsigned long int) CASE_LINEAR(K,INT_BIG) CASE_LINEAR(UK,UINT_BIG) CASE_LINEAR(I,int) CASE_LINEAR(UI,unsigned int) CASE_LINEAR(S,short int) CASE_LINEAR(US,unsigned short int) CASE_LINEAR(B,signed char) CASE_LINEAR(UB,unsigned char) } break; /* Undefine the macro. */ #undef CASE_LINEAR /* Interpolation using a 1-d kernel. */ /* --------------------------------- */ case AST__GAUSS: case AST__SINC: case AST__SINCCOS: case AST__SINCGAUSS: case AST__SINCSINC: case AST__SOMB: case AST__SOMBCOS: case AST__UKERN1: /* User-supplied 1-d kernel function */ /* Obtain a pointer to the appropriate 1-d kernel function (either internal or user-defined) and set up any parameters it may require. */ par = NULL; switch ( interp ) { /* sinc(pi*x) interpolation. */ /* ------------------------- */ /* Assign the kernel function. */ case AST__SINC: kernel = Sinc; /* Calculate the number of neighbouring pixels to use. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) { neighb = 2; } else { neighb = MaxI( 1, neighb, status ); } break; /* sinc(pi*x)*cos(k*pi*x) interpolation. */ /* ------------------------------------- */ /* Assign the kernel function. */ case AST__SINCCOS: kernel = SincCos; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; /* somb(pi*x) interpolation. */ /* ------------------------- */ /* Assign the kernel function. */ case AST__SOMB: kernel = Somb; /* Calculate the number of neighbouring pixels to use. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) { neighb = 2; } else { neighb = MaxI( 1, neighb, status ); } break; /* somb(pi*x)*cos(k*pi*x) interpolation. */ /* ------------------------------------- */ /* Assign the kernel function. */ case AST__SOMBCOS: kernel = SombCos; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; /* sinc(pi*x)*exp(-k*x*x) interpolation. */ /* ------------------------------------- */ /* Assign the kernel function. */ case AST__SINCGAUSS: kernel = SincGauss; /* Constrain the full width half maximum of the gaussian factor. */ fwhm = MaxD( 0.1, params[ 1 ], status ); /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 4.0 * log( 2.0 ) / ( fwhm * fwhm ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, use the number of neighbouring pixels required by the width of the kernel (out to where the gaussian term falls to 1% of its peak value). */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = (int) ceil( sqrt( -log( 0.01 ) / lpar[ 0 ] ) ); break; /* exp(-k*x*x) interpolation. */ /* -------------------------- */ /* Assign the kernel function. */ case AST__GAUSS: kernel = Gauss; /* Constrain the full width half maximum of the gaussian. */ fwhm = MaxD( 0.1, params[ 1 ], status ); /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 4.0 * log( 2.0 ) / ( fwhm * fwhm ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, use the number of neighbouring pixels required by the width of the kernel (out to where the gaussian term falls to 1% of its peak value). */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = (int) ceil( sqrt( -log( 0.01 ) / lpar[ 0 ] ) ); break; /* sinc(pi*x)*sinc(k*pi*x) interpolation. */ /* -------------------------------------- */ /* Assign the kernel function. */ case AST__SINCSINC: kernel = SincSinc; /* Store the required value of "k" in a local parameter array and pass this array to the kernel function. */ lpar[ 0 ] = 0.5 / MaxD( 1.0, params[ 1 ], status ); par = lpar; /* Obtain the number of neighbouring pixels to use. If this is zero or less, the number will be calculated automatically below. */ neighb = (int) floor( params[ 0 ] + 0.5 ); if ( neighb <= 0 ) neighb = INT_MAX; /* Calculate the maximum number of neighbouring pixels required by the width of the kernel, and use this value if preferable. */ neighb = MinI( neighb, (int) ceil( MaxD( 1.0, params[ 1 ], status ) ), status ); break; /* User-supplied kernel. */ /* --------------------- */ /* Assign the kernel function. */ case AST__UKERN1: fkernel = (void (*)( double, const double [], int, double * )) finterp; /* Calculate the number of neighbouring pixels to use. */ neighb = MaxI( 1, (int) floor( params[ 0 ] + 0.5 ), status ); /* Pass a pointer to the "params" array. */ par = params; break; } /* Define a macro to use a "case" statement to invoke the 1-d kernel interpolation function appropriate to a given data type, passing it the pointer to the kernel function obtained above. */ #define CASE_KERNEL1(X,Xtype) \ case ( TYPE_##X ): \ result = \ InterpolateKernel1##X( this, ndim_in, lbnd_in, ubnd_in, \ (Xtype *) in, (Xtype *) in_var, \ npoint, offset, \ (const double *const *) ptr_in, \ kernel, fkernel, neighb, par, flags, \ *( (Xtype *) badval_ptr ), \ (Xtype *) out, (Xtype *) out_var, status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_KERNEL1(LD,long double) #endif CASE_KERNEL1(D,double) CASE_KERNEL1(F,float) CASE_KERNEL1(L,long int) CASE_KERNEL1(UL,unsigned long int) CASE_KERNEL1(K,INT_BIG) CASE_KERNEL1(UK,UINT_BIG) CASE_KERNEL1(I,int) CASE_KERNEL1(UI,unsigned int) CASE_KERNEL1(S,short int) CASE_KERNEL1(US,unsigned short int) CASE_KERNEL1(B,signed char) CASE_KERNEL1(UB,unsigned char) } break; /* Undefine the macro. */ #undef CASE_KERNEL1 /* General sub-pixel interpolation function. */ /* ----------------------------------------- */ case AST__BLOCKAVE: case AST__UINTERP: /* Define a macro to use a "case" statement to invoke the general sub-pixel interpolation function appropriate to a given type and the selected value of the interp variable. */ #define CASE_GINTERP(X,Xtype) \ case ( TYPE_##X ): \ \ /* Obtain a pointer to the appropriate general interpolation function \ (either internal or user-defined) and set up any parameters it may \ require. */ \ switch ( interp ) { \ \ /* Block averaging interpolation. */ \ /* ------------------------------ */ \ case AST__BLOCKAVE: \ gifunc = (void (*)( void )) InterpolateBlockAverage##X; \ break; \ \ /* User-supplied sub-pixel interpolation function. */ \ /* ----------------------------------------------- */ \ case AST__UINTERP: \ gifunc = (void (*)( void )) finterp; \ break; \ } \ \ /* Invoke the general interpolation function. It has to be cast to the \ right type (i.e. a function with the correctly typed arguments) \ to prevent default promotion (to int or double) of its arguments. \ The cast here corresponds to the declaration of ast_resample_uinterp##Xtype. */ \ ( *( (void (*)( int, const int[], const int[], \ const Xtype[], \ const Xtype[], \ int, const int[], \ const double *const[], \ const double[], int, \ Xtype, \ Xtype *, \ Xtype *, \ int * )) \ gifunc ) )( ndim_in, lbnd_in, ubnd_in, \ (Xtype *) in, \ (Xtype *) ( usevar ? in_var : NULL ), \ npoint, offset, \ (const double *const *) ptr_in, \ params, flags, \ *( (Xtype *) badval_ptr ), \ (Xtype *) out, \ (Xtype *) ( usevar ? out_var : NULL ), \ &nbad ); \ if ( astOK ) { \ result += nbad; \ } else { \ astError( astStatus, "astResample"#X"(%s): Error " \ "signalled by user-supplied sub-pixel " \ "interpolation function.", status, \ astGetClass( unsimplified_mapping ) ); \ } \ break; /* Use the above macro to invoke the function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_GINTERP(LD,long double) #endif CASE_GINTERP(D,double) CASE_GINTERP(F,float) CASE_GINTERP(L,long int) CASE_GINTERP(UL,unsigned long int) CASE_GINTERP(K,INT_BIG) CASE_GINTERP(UK,UINT_BIG) CASE_GINTERP(I,int) CASE_GINTERP(UI,unsigned int) CASE_GINTERP(S,short int) CASE_GINTERP(US,unsigned short int) CASE_GINTERP(B,signed char) CASE_GINTERP(UB,unsigned char) } break; /* Undefine the macro. */ #undef CASE_GINTERP /* Error: invalid interpolation scheme specified. */ /* ---------------------------------------------- */ default: /* Define a macro to report an error message appropriate to a given data type. */ #define CASE_ERROR(X) \ case TYPE_##X: \ astError( AST__SISIN, "astResample"#X"(%s): Invalid " \ "sub-pixel interpolation scheme (%d) specified.", status, \ astGetClass( unsimplified_mapping ), interp ); \ break; /* Use the above macro to report an appropriate error message. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_ERROR(LD) #endif CASE_ERROR(D) CASE_ERROR(F) CASE_ERROR(L) CASE_ERROR(UL) CASE_ERROR(K) CASE_ERROR(UK) CASE_ERROR(I) CASE_ERROR(UI) CASE_ERROR(S) CASE_ERROR(US) CASE_ERROR(B) CASE_ERROR(UB) } break; /* Undefine the macro. */ #undef CASE_ERROR } } /* Now scale the output values to conserve flux if required. */ if( conserve ) { /* Define a macro to use a "case" statement to invoke the function appropriate to a given data type. These simply multiple the output data value by the factor, and the output variance by the square of the factor. */ #define CASE_CONSERVE(X,Xtype) \ case ( TYPE_##X ): \ ConserveFlux##X( factor, npoint, offset, *( (Xtype *) badval_ptr ), \ (Xtype *) out, \ (Xtype *) ( usevar ? out_var : NULL ), status ); \ break; /* Use the above macro to invoke the appropriate function. */ switch ( type ) { #if HAVE_LONG_DOUBLE /* Not normally implemented */ CASE_CONSERVE(LD,long double) #endif CASE_CONSERVE(D,double) CASE_CONSERVE(F,float) CASE_CONSERVE(L,long int) CASE_CONSERVE(UL,unsigned long int) CASE_CONSERVE(K,INT_BIG) CASE_CONSERVE(UK,UINT_BIG) CASE_CONSERVE(I,int) CASE_CONSERVE(UI,unsigned int) CASE_CONSERVE(S,short int) CASE_CONSERVE(US,unsigned short int) CASE_CONSERVE(B,signed char) CASE_CONSERVE(UB,unsigned char) } /* Undefine the macro. */ #undef CASE_CONSERVE } /* Annul the PointSet used to hold input coordinates. */ pset_in = astAnnul( pset_in ); /* Free the workspace. */ offset = astFree( offset ); stride = astFree( stride ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static int ResampleWithBlocking( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const void *in, const void *in_var, DataType type, int interp, void (* finterp)( void ), const double *params, int flags, const void *badval_ptr, int ndim_out, const int *lbnd_out, const int *ubnd_out, const int *lbnd, const int *ubnd, void *out, void *out_var, int *status ) { /* * Name: * ResampleWithBlocking * Purpose: * Resample a section of a data grid in a memory-efficient way. * Type: * Private function. * Synopsis: * #include "mapping.h" * int ResampleWithBlocking( AstMapping *this, const double *linear_fit, * int ndim_in, * const int *lbnd_in, const int *ubnd_in, * const void *in, const void *in_var, * DataType type, int interp, void (* finterp)( void ), * const double *params, int flags, * const void *badval_ptr, int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const int *lbnd, const int *ubnd, * void *out, void *out_var, int *status ) * Class Membership: * Mapping member function. * Description: * This function resamples a rectangular grid of data (with any * number of dimensions) into a specified section of another * rectangular grid (with a possibly different number of * dimensions). The coordinate transformation used is given by the * inverse transformation of the Mapping which is supplied or, * alternatively, by a linear approximation fitted to a Mapping's * inverse transformation. Any pixel interpolation scheme may be * specified for interpolating between the pixels of the input * grid. * * This function is very similar to ResampleSection, except that in * order to limit memory usage and to ensure locality of reference, * it divides the output grid up into "blocks" which have a limited * extent along each output dimension. Each block, which will not * contain more than a pre-determined maximum number of pixels, is * then passed to ResampleSection for resampling. * Parameters: * this * Pointer to a Mapping, whose inverse transformation may be * used to transform the coordinates of pixels in the output * grid into associated positions in the input grid, from which * the output pixel values should be derived (by interpolation * if necessary). * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's inverse coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * inverse transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * in * Pointer to the input array of data to be resampled (with one * element for each pixel in the input grid). The numerical type * of these data should match the "type" value (below). The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * in_var * An optional pointer to a second array of positive numerical * values (with the same size and data type as the "in" array), * which represent estimates of the statistical variance * associated with each element of the "in" array. If this * second array is given (along with the corresponding "out_var" * array), then estimates of the variance of the resampled data * will also be returned. * * If no variance estimates are required, a NULL pointer should * be given. * type * A value taken from the "DataType" enum, which specifies the * data type of the input and output arrays containing the * gridded data (and variance) values. * interp * A value selected from a set of pre-defined macros to identify * which sub-pixel interpolation algorithm should be used. * finterp * If "interp" is set to a value which requires a user-supplied * function, then a pointer to that function shoild be given * here. Otherwise, this value is not used and may be a NULL * pointer. * params * Pointer to an optional array of parameters that may be passed * to the interpolation algorithm, if required. If no parameters * are required, a NULL pointer should be supplied. * flags * The bitwise OR of a set of flag values which provide * additional control over the resampling operation. * badval_ptr * If the AST__USEBAD flag is set (above), this parameter is a * pointer to a value which is used to identify bad data and/or * variance values in the input array(s). The referenced value's * data type must match that of the "in" (and "in_var") * arrays. Unless the AST__NOBAD flag is set, the same value will * also be used to flag any output array elements for which * resampled values could not be obtained. The output arrays(s) * may be flagged with this value whether or not the AST__USEBAD * flag is set (the function return value indicates whether any * such values have been produced). * ndim_out * The number of dimensions in the output grid. This should be * at least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output data grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output data grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output data grid in the same way as "lbnd_in" * and "ubnd_in" define the shape and size of the input grid * (see above). * lbnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the first pixel in the * section of the output data grid for which a value is * required. * ubnd * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the last pixel in the * section of the output data grid for which a value is * required. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the output grid for which resampled values are * required. This section should lie wholly within the extent of * the output grid (as defined by the "lbnd_out" and "ubnd_out" * arrays). Regions of the output grid lying outside this section * will not be modified. * out * Pointer to an array with the same data type as the "in" * array, into which the resampled data will be returned. The * storage order should be such that the coordinate of the first * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order is used). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the resampled values may be returned. This array will only be * used if the "in_var" array has been given. * * If no output variance estimates are required, a NULL pointer * should be given. * status * Pointer to the inherited status variable. * Returned Value: * The number of output grid points for which no valid output value * could be obtained. * 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 Constants: */ const int mxpix = 2 * 1024; /* Maximum number of pixels in a block (this relatively small number seems to give best performance) */ /* Local Variables: */ double factor; /* Flux conservation factor */ int *dim_block; /* Pointer to array of block dimensions */ int *lbnd_block; /* Pointer to block lower bound array */ int *ubnd_block; /* Pointer to block upper bound array */ int dim; /* Dimension size */ int done; /* All blocks resampled? */ int hilim; /* Upper limit on maximum block dimension */ int idim; /* Loop counter for dimensions */ int lolim; /* Lower limit on maximum block dimension */ int mxdim_block; /* Maximum block dimension */ int npix; /* Number of pixels in block */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate workspace. */ lbnd_block = astMalloc( sizeof( int ) * (size_t) ndim_out ); ubnd_block = astMalloc( sizeof( int ) * (size_t) ndim_out ); dim_block = astMalloc( sizeof( int ) * (size_t) ndim_out ); if ( astOK ) { /* Find the optimum block size. */ /* ---------------------------- */ /* We first need to find the maximum extent which a block of output pixels may have in each dimension. We determine this by taking the output grid extent in each dimension and then limiting the maximum dimension size until the resulting number of pixels is sufficiently small. This approach allows the block shape to approximate (or match) the output grid shape when appropriate. */ /* First loop to calculate the total number of output pixels and the maximum output dimension size. */ npix = 1; mxdim_block = 0; for ( idim = 0; idim < ndim_out; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= dim; if ( mxdim_block < dim ) mxdim_block = dim; } /* If the number of output pixels is too large for a single block, we perform iterations to determine the optimum upper limit on a block's dimension size. Initialise the limits on this result. */ if ( npix > mxpix ) { lolim = 1; hilim = mxdim_block; /* Loop to perform a binary chop, searching for the best result until the lower and upper limits on the result converge to adjacent values. */ while ( ( hilim - lolim ) > 1 ) { /* Form a new estimate from the mid-point of the previous limits. */ mxdim_block = ( hilim + lolim ) / 2; /* See how many pixels a block contains if its maximum dimension is limited to this new value. */ for ( npix = 1, idim = 0; idim < ndim_out ; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= ( dim < mxdim_block ) ? dim : mxdim_block; } /* Update the appropriate limit, according to whether the number of pixels is too large or too small. */ *( ( npix <= mxpix ) ? &lolim : &hilim ) = mxdim_block; } /* When iterations have converged, obtain the maximum limit on the dimension size of a block which results in no more than the maximum allowed number of pixels per block. However, ensure that all block dimensions are at least 2. */ mxdim_block = lolim; } if ( mxdim_block < 2 ) mxdim_block = 2; /* Calculate the block dimensions by applying this limit to the output grid dimensions. */ for ( idim = 0; idim < ndim_out ; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; dim_block[ idim ] = ( dim < mxdim_block ) ? dim : mxdim_block; /* Also initialise the lower and upper bounds of the first block of output grid pixels to be resampled, ensuring that this does not extend outside the grid itself. */ lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); } /* Determine the flux conservation constant if needed. */ /* --------------------------------------------------- */ if( ( flags & AST__CONSERVEFLUX ) && linear_fit ) { factor = MatrixDet( ndim_in, ndim_out, linear_fit + ndim_in, status ); } else { factor = 1.0; } /* Resample each block of output pixels. */ /* ------------------------------------- */ /* Loop to generate the extent of each block of output pixels and to resample them. */ done = 0; while ( !done && astOK ) { /* Resample the current block, accumulating the sum of bad pixels produced. */ result += ResampleSection( this, linear_fit, ndim_in, lbnd_in, ubnd_in, in, in_var, type, interp, finterp, params, factor, flags, badval_ptr, ndim_out, lbnd_out, ubnd_out, lbnd_block, ubnd_block, out, out_var, status ); /* Update the block extent to identify the next block of output pixels. */ idim = 0; do { /* We find the least significant dimension where the upper bound of the block has not yet reached the upper bound of the region of the output grid which we are resampling. The block's position is then incremented by one block extent along this dimension, checking that the resulting extent does not go outside the region being resampled. */ if ( ubnd_block[ idim ] < ubnd[ idim ] ) { lbnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ], ubnd[ idim ], status ); ubnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); break; /* If any less significant dimensions are found where the upper bound of the block has reached its maximum value, we reset the block to its lowest position. */ } else { lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); /* All the blocks have been processed once the position along the most significant dimension has been reset. */ done = ( ++idim == ndim_out ); } } while ( !done ); } } /* Free the workspace. */ lbnd_block = astFree( lbnd_block ); ubnd_block = astFree( ubnd_block ); dim_block = astFree( dim_block ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * Mapping member function (over-rides the astSetAttrib protected * method inherited from the Object class). * Description: * This function assigns an attribute value for a Mapping, 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 Mapping. * setting * Pointer to a null terminated string specifying the new attribute * value. */ /* Local Variables: */ AstMapping *this; /* Pointer to the Mapping structure */ int invert; /* Invert attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ int report; /* Report attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Mapping structure. */ this = (AstMapping *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Invert. */ /* ------- */ if ( nc = 0, ( 1 == astSscanf( setting, "invert= %d %n", &invert, &nc ) ) && ( nc >= len ) ) { astSetInvert( this, invert ); /* Report. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "report= %d %n", &report, &nc ) ) && ( nc >= len ) ) { astSetReport( this, report ); /* 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( "nin" ) || MATCH( "nout" ) || MATCH( "islinear" ) || MATCH( "issimple" ) || 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static void Sinc( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * Sinc * Purpose: * 1-dimensional sinc(pi*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void Sinc( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is sinc(pi*x), where * sinc(z)=sin(z)/z. * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * Not used. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise a local value for pi. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); init = 1; } /* Scale the offset. */ offset *= pi; /* Evaluate the function. */ *value = ( offset != 0.0 ) ? ( sin( offset ) / offset ) : 1.0; } static void SincCos( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * SincCos * Purpose: * 1-dimensional sinc(pi*x)*cos(k*pi*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SincCos( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is sinc(pi*x)*cos(k*pi*x) * out to the point where cos(k*pi*x) = 0, and zero beyond. Here, * sinc(z)=sin(z)/z. * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * The first element of this array should give a value for "k" * in the cos(k*pi*x) term. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ double offset_k; /* Scaled offset */ static double halfpi; /* Value of pi/2 */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise local values for pi and pi/2. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); halfpi = 0.5 * pi; init = 1; } /* Multiply the offset by pi and remove its sign. */ offset = pi * fabs( offset ); /* Find the offset scaled by the "k" factor. */ offset_k = offset * params[ 0 ]; /* If the cos(k*pi*x) term has not reached zero, calculate the result. */ if ( offset_k < halfpi ) { *value = ( ( offset != 0.0 ) ? ( sin( offset ) / offset ) : 1.0 ) * cos( offset_k ); /* Otherwise, the result is zero. */ } else { *value = 0.0; } } static void SincGauss( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * SincGauss * Purpose: * 1-dimensional sinc(pi*x)*exp(-k*x*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SincGauss( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is sinc(pi*x)*exp(-k*x*x), * where sinc(z)=sin(z)/z. * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * The first element of this array should give a value for "k" * in the exp(-k*x*x) term. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ double offset_pi; /* Offset multiplied by pi */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise a local value for pi. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); init = 1; } /* Find the offset scaled by pi. */ offset_pi = pi * offset; /* Calculate the result. */ *value = ( ( offset_pi != 0.0 ) ? ( sin( offset_pi ) / offset_pi ) : 1.0 ) * exp( -params[ 0 ] * offset * offset ); } static void SincSinc( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * SincSinc * Purpose: * 1-dimensional sinc(pi*x)*sinc(k*pi*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SincSinc( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is sinc(pi*x)*sinc(k*pi*x), * out to the point where sinc(k*pi*x)=0, and zero beyond. Here, * sinc(z)=sin(z)/z. * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * The first element of this array should give a value for "k" * in the sinc(k*pi*x) term. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ double offset_k; /* Scaled offset */ static double halfpi; /* Value of pi/2 */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise local values for pi and pi/2. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); halfpi = 0.5 * pi; init = 1; } /* Multiply the offset by pi and remove its sign. */ offset = pi * fabs( offset ); /* Find the offset scaled by the "k" factor. */ offset_k = offset * params[ 0 ]; /* If the sinc(k*pi*x) term has not reached zero, calculate the result. */ if ( offset_k < halfpi ) { *value = ( ( offset != 0.0 ) ? ( sin( offset ) / offset ) : 1.0 ) * ( ( offset_k != 0.0 ) ? ( sin( offset_k ) / offset_k ) : 1.0 ); /* Otherwise, the result is zero. */ } else { *value = 0.0; } } static AstMapping *Simplify( AstMapping *this, int *status ) { /* *++ * Name: c astSimplify f AST_SIMPLIFY * Purpose: * Simplify a Mapping. * Type: * Public function. * Synopsis: c #include "mapping.h" c AstMapping *astSimplify( AstMapping *this ) f RESULT = AST_SIMPLIFY( THIS, STATUS ) * Class Membership: * Mapping method. * Description: * This function simplifies a Mapping (which may be a compound * Mapping such as a CmpMap) to eliminate redundant computational * steps, or to merge separate steps which can be performed more * efficiently in a single operation. * * As a simple example, a Mapping which multiplied coordinates by * 5, and then multiplied the result by 10, could be simplified to * a single step which multiplied by 50. Similarly, a Mapping which * multiplied by 5, and then divided by 5, could be reduced to a * simple copying operation. * * This function should typically be applied to Mappings which have * undergone substantial processing or have been formed by merging * other Mappings. It is of potential benefit, for example, in * reducing execution time if applied before using a Mapping to * transform a large number of coordinates. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the original Mapping. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astSimplify() f AST_SIMPLIFY = INTEGER * A new pointer to the (possibly simplified) Mapping. * Applicability: * Mapping * This function applies to all Mappings. * FrameSet * If the supplied Mapping is a FrameSet, the returned Mapping * will be a copy of the supplied FrameSet in which all the * inter-Frame Mappings have been simplified. * Notes: * - Mappings that have a set value for their Ident attribute are * left unchanged after simplification. This is so that their * individual identity is preserved. This restriction does not * apply to the simplification of Frames. * - This function can safely be applied even to Mappings which * cannot be simplified. If no simplification is possible, it c behaves exactly like astClone and returns a pointer to the f behaves exactly like AST_CLONE and returns a pointer to the * original Mapping. * - The Mapping returned by this function may not be independent * of the original (even if simplification was possible), and * modifying it may therefore result in indirect modification of * the original. If a completely independent result is required, a c copy should be made using astCopy. f copy should be made using AST_COPY. * - 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: */ AstMapping **map_list; /* Pointer to array of Mapping pointers */ AstMapping *map; /* Cloned pointer to nominated Mapping */ AstMapping *result; /* Pointer to result Mapping */ int *invert_list; /* Pointer to array of invert flags */ int imap; /* Loop counter for Mappings */ int modified; /* Index of first modified element */ int nmap; /* Number of Mappings */ int simpler; /* Simplification achieved? */ /* Initialise. */ result = NULL; /* Check the inherited status. */ if ( !astOK ) return result; /* Initialise dynamic arrays of Mapping pointers and associated invert flags. */ nmap = 0; map_list = NULL; invert_list = NULL; /* Build a Mapping list to contain this Mapping (the list should only have 1 element). */ astMapList( this, 1, astGetInvert( this ), &nmap, &map_list, &invert_list ); /* Pass the list repeatedly to the "astMapMerge" method for simplification. */ simpler = 0; while ( astOK ) { map = astClone( map_list[ 0 ] ); modified = astMapMerge( map, 0, 1, &nmap, &map_list, &invert_list ); map = astAnnul( map ); /* Quit looping if the number of Mappings increases above 1, or if no further change occurs. Note if any simplification was achieved. */ if ( ( nmap > 1 ) || ( modified < 0 ) ) break; simpler = 1; } /* Check whether simplification has occurred. If not, simply clone the original Mapping pointer. This is what will normally happen for Mapping classes which inherit the default (null) "astMapMerge" method from this class and do not define one of their own. */ if ( astOK ) { if ( !simpler || ( nmap > 1 ) ) { result = astClone( this ); /* If simplification occurred, test if the resulting Mapping has the Invert attribute value we want. If so, we can simply clone a pointer to it. */ } else { if ( invert_list[ 0 ] == astGetInvert( map_list[ 0 ] ) ) { result = astClone( map_list[ 0 ] ); /* If not, we must make a copy. */ } else { result = astCopy( map_list[ 0 ] ); /* Either clear the copy's Invert attribute, or set it to 1, as required. */ if ( invert_list[ 0 ] ) { astSetInvert( result, 1 ); } else { astClearInvert( result ); } } } } /* Loop to annul all the pointers in the Mapping list. */ for ( imap = 0; imap < nmap; imap++ ) { map_list[ imap ] = astAnnul( map_list[ imap ] ); } /* Free the dynamic arrays. */ map_list = astFree( map_list ); invert_list = astFree( invert_list ); /* If an error occurred, annul the returned Mapping. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void Somb( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * Somb * Purpose: * 1-dimensional somb(pi*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void Somb( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is somb(pi*x), where * somb(z)=2*J1(z)/z (J1 is a Bessel function of the first kind of * order 1). * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * Not used. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise a local value for pi. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); init = 1; } /* Scale the offset. */ offset *= pi; /* Evaluate the function. */ *value = ( offset != 0.0 ) ? ( 2.0*J1Bessel( offset, status ) / offset ) : 1.0; } static void SombCos( double offset, const double params[], int flags, double *value, int *status ) { /* * Name: * SombCos * Purpose: * 1-dimensional somb(pi*x)*cos(k*pi*x) interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SombCos( double offset, const double params[], int flags, * double *value, int *status ) * Class Membership: * Mapping member function. * Description: * This function calculates the value of a 1-dimensional sub-pixel * interpolation kernel. The function used is somb(pi*x)*cos(k*pi*x) * out to the point where cos(k*pi*x) = 0, and zero beyond. Here, * somb(z)=2*J1(z)/z (J1 is a Bessel function of the first kind of * order 1). * Parameters: * offset * The offset of a pixel from the interpolation point, measured * in pixels. * params * The first element of this array should give a value for "k" * in the cos(k*pi*x) term. * flags * Not used. * value * Pointer to a double to receive the calculated kernel value. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error checking and does not * generate errors. */ /* Local Variables: */ double offset_k; /* Scaled offset */ static double halfpi; /* Value of pi/2 */ static double pi; /* Value of pi */ static int init = 0; /* Initialisation flag */ /* On the first invocation, initialise local values for pi and pi/2. Do this only once. */ if ( !init ) { pi = acos( -1.0 ); halfpi = 0.5 * pi; init = 1; } /* Multiply the offset by pi and remove its sign. */ offset = pi * fabs( offset ); /* Find the offset scaled by the "k" factor. */ offset_k = offset * params[ 0 ]; /* If the cos(k*pi*x) term has not reached zero, calculate the result. */ if ( offset_k < halfpi ) { *value = ( ( offset != 0.0 ) ? ( J1Bessel( offset, status ) / offset ) : 1.0 ) * cos( offset_k ); /* Otherwise, the result is zero. */ } else { *value = 0.0; } } static int SpecialBounds( const MapData *mapdata, double *lbnd, double *ubnd, double xl[], double xu[], int *status ) { /* * Name: * SpecialBounds * Purpose: * Estimate coordinate bounds using special points. * Type: * Private function. * Synopsis: * #include "mapping.h" * int SpecialBounds( const MapData *mapdata, double *lbnd, double *ubnd, * double xl[], double xu[], int *status ); * Class Membership: * Mapping member function. * Description: * This function makes a rough estimate of the lower and upper * bounds of a Mapping function over a constrained region of its * input coordinate space by transforming a set of special test * points. The points used lie at the corners of the constrained * region, at the centre of each of its faces, at its centroid, and * (if within the coordinate constraints) the origin. * * In many practical cases, the true extrema may actually lie at * one or other of these points, in which case the true bounds will * be found. In other cases, this function only provides an * approximate limit on each bound (there is no way of telling if * this is the case, however). In either case, having these initial * estimates can speed subsequent searches to find the global * extrema as well as making that search more secure * Parameters: * mapdata * Pointer to a MapData structure describing the Mapping * function, its coordinate constraints, etc. * lbnd * Pointer to a double. On entry, this should contain a * previously-obtained upper limit on the lower bound, or * AST__BAD if no such limit is available. On exit, it will be * updated with a new estimate of the lower bound, if a better * one has been found. * ubnd * Pointer to a double. On entry, this should contain a * previously-obtained lower limit on the upper bound, or * AST__BAD if no such limit is available. On exit, it will be * updated with a new estimate of the upper bound, if a better * one has been found. * xl * Pointer to an array of double, with one element for each * input coordinate, in which to return the position of a (not * necessarily unique) input point at which the lower output * bound is reached. This array is not altered if an improved * estimate of the lower bound cannot be found. * xu * Pointer to an array of double, with one element for each * input coordinate, in which to return the position of a (not * necessarily unique) input point at which the upper output * bound is reached. This array is not altered if an improved * estimate of the upper bound cannot be found. * status * Pointer to the inherited status variable. * Returned: * A flag indicating if the returned values can be refined. */ /* Local Variables: */ AstPointSet *pset_in; /* PointSet for input coordinates */ AstPointSet *pset_out; /* PointSet for output coordinates */ double **ptr_in; /* Pointer to input coordinates */ double **ptr_out; /* Pointer to output coordinates */ double *sxl; /* Secondary xl values */ double *sxu; /* Secondary xu values */ double f; /* Output coordinate value */ double slbnd; /* Secondary lbnd value */ double subnd; /* Secondary lbnd value */ int *limit; /* Workspace for lower/upper limit flags */ int bad; /* Output coordinate bad? */ int coord; /* Loop counter for coordinates */ int done; /* All corners done? */ int face; /* Loop counter for faces */ int ic; /* Index of corner */ int icen; /* Index of centroid point */ int ncorner; /* Number of corners */ int ncoord; /* Number of input coordinates */ int npoint; /* Number of points */ int origin; /* Origin lies within bounds? */ int point; /* Loop counter for points */ int result; /* Returned flag */ /* Initialise */ result = 1; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ pset_out = NULL; /* Obtain the number of coordinate axes and calculate the number of points required in order to place one at every corner of the constrained region of the coordinate space. */ ncoord = mapdata->nin; for ( npoint = 1, coord = 0; coord < ncoord; coord++ ) npoint *= 2; /* Also include a second point at each corner,offset slightly from the corner towards the centroid */ ncorner = npoint; npoint *= 2; /* Also include placing one at the centre of every face and one at the centroid of the constrained coordinate space. */ npoint += 2 * ncoord + 1; /* Determine if the origin lies within the bounds. If so, include it as a further point. */ origin = 1; for ( coord = 0; coord < ncoord; coord++ ) { if ( ( mapdata->lbnd[ coord ] > 0.0 ) || ( mapdata->ubnd[ coord ] < 0.0 ) ) { origin = 0; break; } } if ( origin ) npoint++; /* Initialise secondary bounds to be the supplied primary bounds */ slbnd = *lbnd; subnd = *ubnd; /* Create workspace for ssecondary xl xu values */ sxl = astMalloc( sizeof(double)*(size_t) ncoord ); sxu = astMalloc( sizeof(double)*(size_t) ncoord ); /* Create a PointSet to hold the coordinates and obtain a pointer to its coordinate values. Also allocate workspace for calculating the corner coordinates. */ pset_in = astPointSet( npoint, ncoord, "", status ); ptr_in = astGetPoints( pset_in ); limit = astMalloc( sizeof( int ) * (size_t) ncoord ); if ( astOK ) { /* Initialise the workspace. */ for ( coord = 0; coord < ncoord; coord++ ) limit[ coord ] = 0; /* Loop to visit every corner. */ point = 0; done = 0; do { /* At each corner, translate the contents of the "limit" array (containing zeros and ones) into the lower or upper bound on the corresponding axis. This gives the coordinates of the corner, which we store in the input PointSet. */ for ( coord = 0; coord < ncoord; coord++ ) { ptr_in[ coord ][ point ] = limit[ coord ] ? mapdata->ubnd[ coord ] : mapdata->lbnd[ coord ]; } /* Increment the count of points (i.e. corners). */ point++; /* Now update the limit array to identify the next corner. */ coord = 0; do { /* Flip the first zero found to become a one. This gives a new corner. */ if ( !limit[ coord ] ) { limit[ coord ] = 1; break; /* However, first flip any previous ones to become zeros and then examine the next element. We have processed all corners once the array is entirely filled with ones. */ } else { limit[ coord ] = 0; done = ( ++coord == ncoord ); } } while ( !done ); } while ( !done ); /* Once the corners have been processed, loop to consider the centre of each face. */ for ( face = 0; face < ( 2 * ncoord ); face++ ) { /* First calculate the centroid value for each coordinate. Then set one of these coordinates to the bound where the face lies. */ for ( coord = 0; coord < ncoord; coord++ ) { ptr_in[ coord ][ point ] = 0.5 * ( mapdata->lbnd[ coord ] + mapdata->ubnd[ coord ] ); } ptr_in[ face / 2 ][ point ] = ( face % 2 ) ? mapdata->lbnd[ face / 2 ] : mapdata->ubnd[ face / 2 ]; /* Increment the count of points. */ point++; } /* Place a point at the centroid of the constrained coordinate space. */ for ( coord = 0; coord < ncoord; coord++ ) { ptr_in[ coord ][ point ] = 0.5 * ( mapdata->lbnd[ coord ] + mapdata->ubnd[ coord ] ); } icen = point++; /* Add a set of positions which are offset slightly from each corner towards the centroid. */ for ( ic = 0; ic < ncorner; ic++ ) { for ( coord = 0; coord < ncoord; coord++ ) { ptr_in[ coord ][ point ] = 0.999*ptr_in[ coord ][ ic ] + 0.001*ptr_in[ coord ][ icen ]; } point++; } /* Finally, add the origin, if it lies within the constraints. */ if ( origin ) { for ( coord = 0; coord < ncoord; coord++ ) { ptr_in[ coord ][ point ] = 0.0; } } /* Once all the input coordinates have been calculated, transform them and obtain a pointer to the resulting coordinate values. */ pset_out = astTransform( mapdata->mapping, pset_in, mapdata->forward, NULL ); ptr_out = astGetPoints( pset_out ); if ( astOK ) { /* Loop through each point and test if any of its transformed coordinates is bad. */ for ( point = 0; point < npoint; point++ ) { bad = 0; for ( coord = 0; coord < mapdata->nout; coord++ ) { if ( ptr_out[ coord ][ point ] == AST__BAD ) { bad = 1; break; } } /* If so, we ignore the point. Otherwise, extract the required coordinate. */ f = ptr_out[ mapdata->coord ][ point ]; if ( !bad ) { /* Use this to update the lower and upper bounds we are seeking. If either bound is updated, also store the coordinates of the corresponding input point. */ if ( ( *lbnd == AST__BAD ) || ( f < *lbnd ) ) { *lbnd = f; for ( coord = 0; coord < ncoord; coord++ ) { xl[ coord ] = ptr_in[ coord ][ point ]; } } if ( ( *ubnd == AST__BAD ) || ( f > *ubnd ) ) { *ubnd = f; for ( coord = 0; coord < ncoord; coord++ ) { xu[ coord ] = ptr_in[ coord ][ point ]; } } /* If this point has a bad coord value, it may still be useful if the required coord value is not bad. In this case, extract the required coordinate. */ } else if ( f != AST__BAD ) { /* Use this to update secondary lower and upper bounds we are seeking. These will be returned if no primary values are found via the previous code block. */ if ( ( slbnd == AST__BAD ) || ( f < slbnd ) ) { slbnd = f; for ( coord = 0; coord < ncoord; coord++ ) { sxl[ coord ] = ptr_in[ coord ][ point ]; } } if ( ( subnd == AST__BAD ) || ( f > subnd ) ) { subnd = f; for ( coord = 0; coord < ncoord; coord++ ) { sxu[ coord ] = ptr_in[ coord ][ point ]; } } } } /* If no primary values could be found, use secondary values. */ if( *lbnd == AST__BAD && *ubnd == AST__BAD ) { *lbnd = slbnd; *ubnd = subnd; for ( coord = 0; coord < ncoord; coord++ ) { xu[ coord ] = sxu[ coord ]; xl[ coord ] = sxl[ coord ]; } result = ( slbnd == AST__BAD || subnd == AST__BAD ); } } } /* Free workspace */ sxl = astFree( sxl ); sxu = astFree( sxu ); /* Annul the temporary PointSets and free the workspace. */ pset_in = astAnnul( pset_in ); pset_out = astAnnul( pset_out ); limit = astFree( limit ); return result; } /* * Name: * SpreadKernel1 * Purpose: * Rebin a data grid, using a 1-d interpolation kernel. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SpreadKernel1( AstMapping *this, int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const *in, const *in_var, * double infac, int npoint, const int *offset, * const double *const *coords, * void (* kernel)( double, const double [], int, * double *, int * ), * int neighb, const double *params, int flags, * badval, int npix_out, *out, * *out_var, double *work, int64_t *nused, * int *status ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which rebins a rectangular region of an * input grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each input * grid point may be mapped on to a position in the output grid in * an arbitrary way. The input and output grids may have any number * of dimensions, not necessarily equal. * * Where the input positions given do not correspond with a pixel centre * in the output grid, the each input pixel value is spread out between the * surrounding output pixels using weights determined by a separable kernel * which is the product of a 1-dimensional kernel function evaluated along * each output dimension. A pointer should be supplied to the 1-dimensional * kernel function to be used. * Parameters: * this * Pointer to the Mapping being used in the rebinning operation * (this is only used for constructing error messages). * ndim_out * The number of dimensions in the output grid. This should be at * least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output grid, its extent along a particular * (i'th) dimension being ubnd_out[i]-lbnd_out[i]+1 (assuming "i" * is zero-based). They also define the output grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be rebinned. The numerical type * of these data should match the function used, as given by the * suffix on the function name. Note that details of how the input * grid maps on to this array (e.g. the storage order, number of * dimensions, etc.) is arbitrary and is specified entirely by means * of the "offset" array. The "in" array should therefore contain * sufficient elements to accommodate the "offset" values supplied. * There is no requirement that all elements of the "in" array * should be rebinned, and any which are not addressed by the * contents of the "offset" array will be ignored. * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. It is addressed in exactly the same way (via the * "offset" array) as the "in" array. * * If no variance estimates are required, a NULL pointer should * be given. * infac * A factor by which to multiply the input data values before use. * npoint * The number of input points which are to be rebinned. * offset * Pointer to an array of integers with "npoint" elements. For * each input point, this array should contain the zero-based * offset in the input array(s) (i.e. the "in" and, optionally, * the "in_var" arrays) from which the value to be rebinned should * be obtained. * coords * An array of pointers to double, with "ndim_out" elements. * Element "coords[coord]" should point at the first element of * an array of double (with "npoint" elements) which contains the * values of coordinate number "coord" for each point being * rebinned. The value of coordinate number "coord" for * rebinning point number "point" is therefore given by * "coords[coord][point]" (assuming both indices are * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding input data (and * variance) value will be ignored. * kernel * Pointer to the 1-dimensional kernel function to be used. * neighb * The number of neighbouring pixels in each dimension (on each * side of the interpolation position) which are to receive * contributions from the input pixel value. This value should be at * least 1. * params * Pointer to an optional array of parameter values to be passed * to the kernel function. If no parameters are required by this * function, then a NULL pointer may be supplied. * flags * The bitwise OR of a set of flag values which control the * operation of the function. These are chosend from: * * - AST__USEBAD: indicates whether there are "bad" (i.e. missing) data * in the input array(s) which must be recognised. If this flag is not * set, all input values are treated literally. * - AST__GENVAR: Indicates that output variances should be generated * from the spread of values contributing to each output pixel. * - AST__USEVAR: Indicates that output variances should be generated * by rebinning the input variances. * - AST__VARWGT: Indicates that input variances should be used to * create weights for the input data values. * * Only one of AST__GENVAR and AST__USEVAR should be supplied. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which resampled values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * npix_out * Number of pixels in output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the index of the first grid * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. The values returned * are estimates of the statistical variance of the corresponding * values in the "out" array, on the assumption that all errors in * input grid values (in the "in" array) are statistically independent * and that their variance estimates (in the "in_var" array) may * simply be summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * work * A pointer to an array with the same data type and size as the "out" * array which is used as work space. The values in the supplied * array are incremented on exit by the sum of the weights used * with each output pixel. * nused * An optional pointer to a int64_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. */ /* Define macros to implement the function for a specific data type. */ #define MAKE_SPREAD_KERNEL1(X,Xtype,IntType) \ static void SpreadKernel1##X( AstMapping *this, int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const Xtype *in, const Xtype *in_var, \ double infac, int npoint, const int *offset, \ const double *const *coords, \ void (* kernel)( double, const double [], \ int, double *, int * ), \ int neighb, const double *params, \ int flags, Xtype badval, int npix_out, \ Xtype *out, Xtype *out_var, double *work, \ int64_t *nused, int *status ) { \ \ /* Local Variables: */ \ astDECLARE_GLOBALS /* Thread-specific data */ \ Xtype c; \ Xtype in_val; /* Input pixel value */ \ double **wtptr; /* Pointer to array of weight pointers */ \ double **wtptr_last; /* Array of highest weight pointer values */ \ double *filter; /* Pointer to Nd array of filter values */ \ double *kp; /* Pointer to next weight values */ \ double *kstart; /* Pointer to next kernel value */ \ double *kval; /* Pointer to 1d array of kernel values */ \ double *wtprod; /* Accumulated weight value array pointer */ \ double *xfilter; /* Pointer to 1d array of x axis filter values */ \ double *xnl; /* Pointer to previous ofset array (n-d) */ \ double pfac; /* Input weight with extra supplied factor */ \ double pixwt; /* Weight to apply to individual pixel */ \ double sum; /* Sum of all filter values */ \ double wgt; /* Weight for input value */ \ double x; /* x coordinate value */ \ double xn; /* Coordinate value (n-d) */ \ double xx; /* X offset */ \ double xxl; /* Previous X offset */ \ double xxn; \ double y; /* y coordinate value */ \ double yy; /* Y offset */ \ double yyl; /* Previous Y offset */ \ int *hi; /* Pointer to array of upper indices */ \ int *jhi; /* Pointer to array of filter upper indices */ \ int *jlo; /* Pointer to array of filter lower indices */ \ int *lo; /* Pointer to array of lower indices */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int done; /* All pixel indices done? */ \ int genvar; /* Generate output variances? */ \ int hi_ix; /* Upper output pixel index (x dimension) */ \ int hi_iy; /* Upper output pixel index (y dimension) */ \ int hi_jx; /* Upper filter pixel index (x dimension) */ \ int hi_jy; /* Upper filter pixel index (y dimension) */ \ int idim; /* Loop counter for dimensions */ \ int ii; /* Loop counter for dimensions */ \ int ix; /* Pixel index in output grid x dimension */ \ int iy; /* Pixel index in output grid y dimension */ \ int jjx; /* Reflected pixel index in filter grid x dimension */ \ int jjy; /* Reflected pixel index in filter grid y dimension */ \ int jx; /* Pixel index in filter grid x dimension */ \ int jxn; \ int jy; /* Pixel index in filter grid y dimension */ \ int kerror; /* Error signalled by kernel function? */ \ int lo_ix; /* Lower output pixel index (x dimension) */ \ int lo_iy; /* Lower output pixel index (y dimension) */ \ int lo_jx; /* Lower filter pixel index (x dimension) */ \ int lo_jy; /* Lower filter pixel index (y dimension) */ \ int nb2; /* The total number of neighbouring pixels */ \ int nf; /* Number of pixels in filter array */ \ int nwx; /* Used X width of kernel function (*2) */ \ int nwy; /* Used Y width of kernel function (*2) */ \ int off1; /* Input pixel offset due to y index */ \ int off_in; /* Offset to input pixel */ \ int off_out; /* Offset to output pixel */ \ int off_xedge; /* Does filter box overlap array edge on the X axis? */ \ int off_yedge; /* Does filter box overlap array edge on the Y axis? */ \ int point; /* Loop counter for output points */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int varwgt; /* Use input variances as weights? */ \ int ystride; /* Stride along input grid y dimension */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to a structure holding thread-specific global data values */ \ astGET_GLOBALS(this); \ \ /* Further initialisation. */ \ kerror = 0; \ sum = 0.0; \ bad = 0; \ \ /* Find the total number of pixels in the filter used to spread a single \ input pixel into the output image. */ \ nb2 = 2*neighb; \ nf = 1; \ for ( idim = 0; idim < ndim_out; idim++ ) nf *= nb2; \ \ /* Allocate workspace to hold the filter values. */ \ filter = astMalloc( sizeof( double ) * (size_t) nf ); \ if ( astOK ) { \ \ /* Determine if we are processing bad pixels or variances. */ \ usebad = flags & AST__USEBAD; \ usevar = 0; \ genvar = 0; \ if( flags & AST__GENVAR ) { \ genvar = out_var && work; \ } else if( flags & AST__USEVAR ) { \ usevar = in_var && out_var; \ } \ varwgt = ( flags & AST__VARWGT ) && in_var && work; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_out == 1 ) { \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_1D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_1D(X,Xtype,1,0,1,IntType,1) \ } else { \ KERNEL_1D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ KERNEL_1D(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_1D(X,Xtype,0,0,1,IntType,1) \ } else { \ KERNEL_1D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_1D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_1D(X,Xtype,1,0,1,IntType,0) \ } else { \ KERNEL_1D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ KERNEL_1D(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_1D(X,Xtype,0,0,1,IntType,0) \ } else { \ KERNEL_1D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Exit point on error in kernel function */ \ Kernel_SError_1d: ; \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_out == 2 ) { \ \ /* Allocate workspace to hold the X axis filter values. */ \ xfilter = astMalloc( sizeof( double ) * (size_t) nb2 ); \ \ /* Calculate the stride along the y dimension of the output grid. */ \ ystride = ubnd_out[ 0 ] - lbnd_out[ 0 ] + 1; \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_2D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_2D(X,Xtype,1,0,1,IntType,1) \ } else { \ KERNEL_2D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ KERNEL_2D(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_2D(X,Xtype,0,0,1,IntType,1) \ } else { \ KERNEL_2D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_2D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_2D(X,Xtype,1,0,1,IntType,0) \ } else { \ KERNEL_2D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ KERNEL_2D(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_2D(X,Xtype,0,0,1,IntType,0) \ } else { \ KERNEL_2D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Free work space */ \ xfilter = astFree( xfilter ); \ \ /* Exit point on error in kernel function */ \ Kernel_SError_2d: ; \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ hi = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ lo = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ jhi = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ jlo = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ stride = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ xnl = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ kval = astMalloc( sizeof( double ) * (size_t) \ ( nb2 * ndim_out ) ); \ wtprod = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ wtptr = astMalloc( sizeof( double * ) * (size_t) ndim_out ); \ wtptr_last = astMalloc( sizeof( double * ) * (size_t) ndim_out ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the output grid. */ \ for ( s = 1, idim = 0; idim < ndim_out; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ xnl[ idim ] = AST__BAD; \ } \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_ND(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_ND(X,Xtype,1,0,1,IntType,1) \ } else { \ KERNEL_ND(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ KERNEL_ND(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ KERNEL_ND(X,Xtype,0,0,1,IntType,1) \ } else { \ KERNEL_ND(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ KERNEL_ND(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_ND(X,Xtype,1,0,1,IntType,0) \ } else { \ KERNEL_ND(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ KERNEL_ND(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ KERNEL_ND(X,Xtype,0,0,1,IntType,0) \ } else { \ KERNEL_ND(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Exit point on error in kernel function */ \ Kernel_SError_Nd: ;\ } \ \ /* Free the workspace. */ \ hi = astFree( hi ); \ lo = astFree( lo ); \ jhi = astFree( jhi ); \ jlo = astFree( jlo ); \ stride = astFree( stride ); \ xnl = astFree( xnl ); \ kval = astFree( kval ); \ wtprod = astFree( wtprod ); \ wtptr = astFree( wtptr ); \ wtptr_last = astFree( wtptr_last ); \ } \ filter = astFree( filter ); \ }\ \ /* If an error occurred in the kernel function, then report a \ contextual error message. */ \ if ( kerror ) { \ astError( astStatus, "astRebin"#X"(%s): Error signalled by " \ "user-supplied 1-d interpolation kernel.", status, \ astGetClass( unsimplified_mapping ) ); \ } \ \ } #define KERNEL_1D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* We do not yet have a previous filter position. */ \ xxl = AST__BAD; \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the x coordinate of the current point and test if it is bad. \ Also test that the central point falls within the output array. */ \ x = coords[ 0 ][ point ]; \ ix = (int) floor( x + 0.5 ); \ if( ix < lbnd_out[ 0 ] || ix > ubnd_out[ 0 ] ) bad = 1; \ bad = bad || ( x == AST__BAD ); \ \ /* If OK, calculate the lowest and highest indices (in the x \ dimension) of the region of neighbouring output pixels that will \ receive contributions from the current input pixel. Constrain these \ values to lie within the output grid. */ \ if ( !bad ) { \ ix = (int) floor( x ) - neighb + 1; \ lo_ix = MaxI( ix, lbnd_out[ 0 ], status ); \ hi_ix = MinI( ix + nb2 - 1, ubnd_out[ 0 ], status ); \ \ /* Skip to the next input point if the current input point makes no \ contribution to any output pixel. */ \ if( lo_ix <= hi_ix ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* Convert these output indices to the corresponding indices \ within a box [ 0, 2*neighb ] holding the kernel values. */ \ lo_jx = lo_ix - ix; \ hi_jx = hi_ix - ix; \ \ /* See if the kernel extends off the edge of the output array. */ \ nwx = hi_jx - lo_jx + 1; \ off_xedge = ( nwx < nb2 ); \ \ /* Use the kernel function to fill the work array with weights for all output \ pixels whether or not they fall within the output array. At the same \ time find the sum of all the factors. */ \ xx = (double) ix - x; \ if( xx != xxl || off_xedge ) { \ sum = 0.0; \ \ /* First handle cases where the kernel box overlaps an edge of the output \ array. In these cases, in order to conserve flux, the bit of the \ kernel function that is off the edge is reflected back onto the array. \ Care must be taken since the reflected part of the kernel may itself \ overlap the opposite edge of the array, in which case the overlapping \ part must again be reflected back onto the array. This iterative \ reflection is implemented using a fractional division (%) operator. */ \ if( off_xedge ) { \ nwx *= 2; \ xxl = AST__BAD; \ for( jx = 0; jx < nb2; jx++ ) filter[ jx ] = 0.0; \ \ for ( jx = 0; jx < nb2; jx++ ) { \ ( *kernel )( xx, params, flags, &pixwt, status ); \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_1d; \ } \ \ jjx = ( jx - lo_jx ) % nwx + lo_jx; \ if( jjx < lo_jx ) jjx += nwx; \ if( jjx > hi_jx ) jjx = 2*hi_jx - jjx + 1; \ \ filter[ jjx ] += pixwt; \ sum += pixwt; \ xx += 1.0; \ } \ \ /* Now handle cases where the kernel box is completely within the output \ array. */ \ } else { \ xxl = xx; \ \ for ( jx = 0; jx < nb2; jx++ ) { \ ( *kernel )( xx, params, flags, &pixwt, status ); \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_1d; \ } \ \ /* Store the kernel factor and increment the sum of all factors. */ \ filter[ jx ] = pixwt; \ sum += pixwt; \ xx += 1.0; \ } \ \ } \ \ /* Ensure we do not divide by zero. */ \ if( sum == 0.0 ) sum = 1.0; \ } \ \ /* If we are using the input data variances as weights, calculate the \ total weight, incorporating the normalisation factor for the kernel. */ \ if( Varwgt ) { \ wgt = 1.0/(sum*in_var[ off_in ]); \ \ /* If we are not using input variances as weights, the weight is just the \ kernel normalisation factor. */ \ } else { \ wgt = 1.0/sum; \ } \ \ /* Loop round all the output pixels which receive contributions from this \ input pixel, calculating the offset of each pixel from the start of the \ input array. */ \ off_out = lo_ix - lbnd_out[ 0 ]; \ for ( jx = lo_jx; jx <= hi_jx; jx++, off_out++ ) { \ \ /* Retrieve the weight for the current output pixel and normalise it. */ \ pixwt = wgt*filter[ jx ]; \ pfac = pixwt*infac; \ \ /* Update the output pixel with the required fraction of the input pixel \ value. */ \ c = CONV(IntType,pfac*in_val); \ \ if( work ) { \ out[ off_out ] += c; \ work[ off_out ] += pixwt; \ } else {\ out[ off_out ] += c; \ } \ \ if ( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ \ } \ } \ } \ } #define KERNEL_2D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* We do not yet have a previous filter position. */ \ xxl = AST__BAD; \ yyl = AST__BAD; \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the x coordinate of the current point and test if it is bad. \ Also test that the central point falls within the output array. */ \ x = coords[ 0 ][ point ]; \ ix = (int) floor( x + 0.5 ); \ if( ix < lbnd_out[ 0 ] || ix > ubnd_out[ 0 ] ) bad = 1; \ bad = bad || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* Similarly obtain and test the y coordinate. */ \ y = coords[ 1 ][ point ]; \ iy = (int) floor( y + 0.5 ); \ if( iy < lbnd_out[ 1 ] || iy > ubnd_out[ 1 ] ) bad = 1; \ bad = bad || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* If OK, calculate the lowest and highest indices (in each dimension) \ of the region of neighbouring output pixels which will receive \ contributions from the current input pixel. Constrain these values \ to lie within the input grid. */ \ ix = (int) floor( x ) - neighb + 1; \ lo_ix = MaxI( ix, lbnd_out[ 0 ], status ); \ hi_ix = MinI( ix + nb2 - 1, ubnd_out[ 0 ], status ); \ iy = (int) floor( y ) - neighb + 1; \ lo_iy = MaxI( iy, lbnd_out[ 1 ], status ); \ hi_iy = MinI( iy + nb2 - 1, ubnd_out[ 1 ], status ); \ \ /* Skip to the next input point if the current input point makes no \ contribution to any output pixel. */ \ if( lo_ix <= hi_ix && lo_iy <= hi_iy ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* Convert these output indices to the corresponding indices \ within a box [ 0:2*neighb, 0:2*neighb ] holding the kernel values. */ \ lo_jx = lo_ix - ix; \ hi_jx = hi_ix - ix; \ lo_jy = lo_iy - iy; \ hi_jy = hi_iy - iy; \ \ /* See if the kernel extends off the edge of the output array on either \ axis. */ \ nwx = hi_jx - lo_jx + 1; \ nwy = hi_jy - lo_jy + 1; \ off_xedge = ( nwx < nb2 ); \ off_yedge = ( nwy < nb2 ); \ \ /* Loop to evaluate the kernel function along the y dimension, storing \ the resulting weight values in all elements of each associated row \ in the kvar array. The function's argument is the offset of the \ output pixel (along this dimension) from the central output \ position. */ \ yy = (double) iy - y; \ xx = (double) ix - x; \ if( xx != xxl || yy != yyl || off_xedge || off_yedge ) { \ \ /* First handle cases where the kernel box extends beyond the top or \ bottom edge of the output array. In these cases, in order to conserve \ flux, the bit of the kernel function that is off the edge is reflected \ back onto the array. Care must be taken since the reflected part of the \ kernel may itself overlap the opposite edge of the array, in which \ case the overlapping part must again be reflected back onto the \ array. This iterative reflection is implemented using a fractional \ division (%) operator. */ \ if( off_yedge ) { \ nwy *= 2; \ xxl = AST__BAD; \ yyl = AST__BAD; \ for( jy = 0; jy < nb2*nb2; jy++ ) filter[ jy ] = 0.0; \ \ for ( jy = 0; jy < nb2; jy++ ) { \ ( *kernel )( yy, params, flags, &pixwt, status ); \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_2d; \ } \ \ jjy = ( jy - lo_jy ) % nwy + lo_jy; \ if( jjy < lo_jy ) jjy += nwy; \ if( jjy > hi_jy ) jjy = 2*hi_jy - jjy + 1; \ \ kp = filter + jjy*nb2; \ for( jx = 0; jx < nb2; jx++ ) *(kp++) += pixwt; \ yy += 1.0; \ } \ \ /* Now handles cases where the kernel does not overlap the top or bottom edge \ of the output array. */ \ } else { \ xxl = xx; \ yyl = yy; \ kp = filter; \ for ( jy = 0; jy < nb2; jy++ ) { \ ( *kernel )( yy, params, flags, &pixwt, status ); \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_2d; \ } \ \ /* Store the kernel factor in all elements of the current row. */ \ for( jx = 0; jx < nb2; jx++ ) *(kp++) = pixwt; \ \ /* Move on to the next row. */ \ yy += 1.0; \ } \ } \ \ /* Loop to evaluate the kernel function along the x dimension, multiplying \ the resulting weight values by the values already stored in the the \ associated column in the kvar array. The function's argument is the \ offset of the output pixel (along this dimension) from the central output \ position. Also form the total data sum in the filter array. First \ handle cases where the kernel overlaps the left or right edge of the \ output array. */ \ sum = 0.0; \ \ /* First deal with cases where the kernel extends beyond the left or \ right edge of the output array. */ \ if( off_xedge ) { \ nwx *= 2; \ xxl = AST__BAD; \ for( jx = 0; jx < nb2; jx++ ) xfilter[ jx ] = 0.0; \ \ for ( jx = 0; jx < nb2; jx++ ) { \ ( *kernel )( xx, params, flags, &pixwt, status ); \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_2d; \ } \ \ jjx = ( jx - lo_jx ) % nwx + lo_jx; \ if( jjx < lo_jx ) jjx += nwx; \ if( jjx > hi_jx ) jjx = 2*hi_jx - jjx + 1; \ \ xfilter[ jjx ] += pixwt; \ xx += 1.0; \ } \ \ for ( jx = 0; jx < nb2; jx++ ) { \ kp = filter + jx; \ for( jy = 0; jy < nb2; jy++, kp += nb2 ) { \ *kp *= xfilter[ jx ]; \ sum += *kp; \ } \ } \ \ /* Now deal with cases where the kernel does not extends beyond the left or \ right edge of the output array. */ \ } else { \ \ for ( jx = 0; jx < nb2; jx++ ) { \ ( *kernel )( xx, params, flags, &pixwt, status ); \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_2d; \ } \ \ /* Multiply the kernel factor by all elements of the current column. */ \ kp = filter + jx; \ for( jy = 0; jy < nb2; jy++, kp += nb2 ) { \ *kp *= pixwt; \ sum += *kp; \ } \ \ /* Move on to the next column. */ \ xx += 1.0; \ } \ } \ \ /* Ensure we do not divide by zero. */ \ if( sum == 0.0 ) sum = 1.0; \ } \ \ /* If we are using the input data variances as weights, calculate the \ total weight, incorporating the normalisation factor for the kernel. */ \ if( Varwgt ) { \ wgt = 1.0/(sum*in_var[ off_in ]); \ \ /* If we are not using input variances as weights, the weight is just the \ kernel normalisation factor. */ \ } else { \ wgt = 1.0/sum; \ } \ \ /* Find the offset into the output array at the first modified output pixel \ in the first modified row. */ \ off1 = lo_ix - lbnd_out[ 0 ] + ystride * ( lo_iy - lbnd_out[ 1 ] ); \ \ /* Loop over the affected output rows again. */ \ for ( jy = lo_jy; jy <= hi_jy; jy++, off1 += ystride ) { \ \ /* Save the offset of the first output pixel to be modified in the \ current row. */ \ off_out = off1; \ \ /* Get a pointer to the first weight value which will be used. */ \ kp = filter + lo_jx + jy*nb2; \ \ /* Loop over the affected output columns again. */ \ for ( jx = lo_jx; jx <= hi_jx; jx++, off_out++, kp++ ) { \ \ /* Calculate the weight for this output pixel and normalise it. */ \ pixwt = wgt*( *kp ); \ \ /* Update the output pixel with the required fraction of the input pixel \ value. */ \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ \ out[ off_out ] += c; \ if( work ) work[ off_out ] += pixwt; \ \ if ( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ } \ } \ } \ } \ } \ } #define KERNEL_ND(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* We do not yet have a normalising factor */ \ sum = AST__BAD; \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Initialise offsets into the output array. Then loop to obtain each \ coordinate associated with the current output point. Set a flag \ indicating if any output pixel will be modified. */ \ if( !bad ) { \ off_out = 0; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate is bad. If true, the corresponding output pixel \ value will be bad, so give up on this point. */ \ ix = (int) floor( xn + 0.5 ); \ if( ix < lbnd_out[ idim ] || ix > ubnd_out[ idim ] ) bad = 1; \ bad = bad || ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* Calculate the lowest and highest indices (in the current dimension) \ of the region of neighbouring output pixels that will be modified. \ Constrain these values to lie within the output grid. */ \ ix = (int) floor( xn ) - neighb + 1; \ lo[ idim ] = MaxI( ix, lbnd_out[ idim ], status ); \ hi[ idim ] = MinI( ix + nb2 - 1, ubnd_out[ idim ], status ); \ jlo[ idim ] = lo[ idim ] - ix; \ jhi[ idim ] = hi[ idim ] - ix; \ \ /* Check there is some overlap with the output array on this axis. */ \ if( lo[ idim ] > hi[ idim ] ) { \ bad = 1; \ break; \ } \ \ /* Accumulate the offset (from the start of the output array) of the \ modified output pixel which has the lowest index in each dimension. */ \ off_out += stride[ idim ] * ( lo[ idim ] - lbnd_out[ idim ] ); \ \ /* Set up an array of pointers to locate the first filter pixel (stored in the \ "kval" array) for each dimension. */ \ wtptr[ idim ] = kval + nb2*idim; \ wtptr_last[ idim ] = wtptr[ idim ] + nb2 - 1; \ \ /* See if the kernel extends off the edge of the output array on the current \ axis. */ \ lo_jx = jlo[ idim ]; \ hi_jx = jhi[ idim ]; \ nwx = hi_jx - lo_jx + 1; \ off_xedge = ( nwx < nb2 ); \ \ /* Loop to evaluate the kernel function along each dimension, storing \ the resulting values. The function's argument is the offset of the \ output pixel (along the relevant dimension) from the central output \ point. */ \ xxn = (double) ix - xn; \ if( xxn != xnl[ idim ] || off_xedge ) { \ sum = AST__BAD; \ \ /* First handle cases where the kernel box overlaps an edge of the output \ array. In these cases, in order to conserve flux, the bit of the \ kernel function that is off the edge is reflected back onto the array. \ Care must be taken since the reflected part of the kernel may itself \ overlap the opposite edge of the array, in which case the overlapping \ part must again be reflected back onto the array. This iterative \ reflection is implemented using a fractional division (%) operator. */ \ if( off_xedge ) { \ nwx *= 2; \ xnl[ idim ] = AST__BAD; \ kp = wtptr[ idim ]; \ for( jx = 0; jx < nb2; jx++ ) *(kp++) = 0.0; \ \ kp = wtptr[ idim ]; \ for ( jx = 0; jx < nb2; jx++ ) { \ ( *kernel )( xxn, params, flags, &pixwt, status ); \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_1d; \ } \ \ jjx = ( jx - lo_jx ) % nwx + lo_jx; \ if( jjx < lo_jx ) jjx += nwx; \ if( jjx > hi_jx ) jjx = 2*hi_jx - jjx + 1; \ \ kp[ jjx ] += pixwt; \ xxn += 1.0; \ } \ \ /* Now handle cases where the kernel box is completely within the output \ array. */ \ } else { \ xnl[ idim ] = xxn; \ for ( jxn = 0; jxn < nb2; jxn++ ) { \ ( *kernel )( xxn, params, flags, wtptr[ idim ] + jxn, status ); \ \ /* Check for errors arising in the kernel function. */ \ if ( !astOK ) { \ kerror = 1; \ goto Kernel_SError_Nd; \ } \ \ /* Increment the kernel position. */ \ xxn += 1.0; \ } \ } \ } \ } \ \ /* If OK... */ \ if ( !bad ) { \ \ /* We only need to modify the normalising factor if the weight values \ have changed. */ \ if( sum == AST__BAD ) { \ \ /* The kernel value to use for each output pixel is the product of the \ kernel values for each individual axis at that point. To conserve \ flux we need to make sure that the sum of these kernel products is unity. \ So loop over the values now to find the total sum of all kernel values. */ \ idim = ndim_out - 1; \ wtprod[ idim ] = 1.0; \ done = 0; \ sum = 0; \ do { \ \ /* Each modified output pixel has a weight equal to the product of the kernel \ weight factors evaluated along each input dimension. However, since \ we typically only change the index of one dimension at a time, we \ can avoid forming this product repeatedly by retaining an array of \ accumulated products for all higher dimensions. We need then only \ update the lower elements in this array, corresponding to those \ dimensions whose index has changed. We do this here, "idim" being \ the index of the most significant dimension to have changed. Note \ that on the first pass, all dimensions are considered changed, \ causing this array to be initialised. */ \ for ( ii = idim; ii >= 1; ii-- ) { \ wtprod[ ii - 1 ] = wtprod[ ii ] * *( wtptr[ ii ] ); \ } \ \ /* Obtain the weight of each pixel from the accumulated product of \ weights. Also multiply by the weight for dimension zero, which is not \ included in the "wtprod" array). Increment the sum of all weights. */ \ sum += wtprod[ 0 ] * *( wtptr[ 0 ] ); \ \ /* Now update the weight value pointers and pixel offset to refer to \ the next output pixel to be considered. */ \ idim = 0; \ do { \ \ /* The first input dimension whose weight value pointer has not yet \ reached its final value has this pointer incremented. */ \ if ( wtptr[ idim ] != wtptr_last[ idim ] ) { \ wtptr[ idim ]++; \ break; \ \ /* Any earlier dimensions (which have reached the final pointer value) \ have this pointer returned to its lowest value. */ \ } else { \ wtptr[ idim ] -= nb2 - 1; \ done = ( ++idim == ndim_out ); \ } \ } while ( !done ); \ } while ( !done ); \ \ /* Ensure we do not divide by zero. */ \ if( sum == 0.0 ) sum = 1.0; \ } \ \ /* Re-initialise the weights pointers to refer to the first and last \ filter pixels which overlaps the output array. */ \ kstart = kval; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ wtptr[ idim ] = kstart + jlo[ idim ]; \ wtptr_last[ idim ] = kstart + jhi[ idim ]; \ kstart += nb2; \ } \ \ /* If we are using the input data variances as weights, calculate the \ total weight, incorporating the normalisation factor for the kernel. */ \ if( Varwgt ) { \ wgt = 1.0/(sum*in_var[ off_in ]); \ \ /* If we are not using input variances as weights, the weight is just the \ kernel normalisation factor. */ \ } else { \ wgt = 1.0/sum; \ } \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* Initialise, and loop over the neighbouring output pixels to divide up \ the input pixel value between them. */ \ idim = ndim_out - 1; \ wtprod[ idim ] = 1.0; \ done = 0; \ do { \ \ /* Each modified output pixel has a weight equal to the product of the kernel \ weight factors evaluated along each input dimension. However, since \ we typically only change the index of one dimension at a time, we \ can avoid forming this product repeatedly by retaining an array of \ accumulated products for all higher dimensions. We need then only \ update the lower elements in this array, corresponding to those \ dimensions whose index has changed. We do this here, "idim" being \ the index of the most significant dimension to have changed. Note \ that on the first pass, all dimensions are considered changed, \ causing this array to be initialised. */ \ for ( ii = idim; ii >= 1; ii-- ) { \ wtprod[ ii - 1 ] = wtprod[ ii ] * *( wtptr[ ii ] ); \ } \ \ /* Obtain the weight of each pixel from the accumulated \ product of weights. Also multiply by the weight for dimension zero, \ which is not included in the "wtprod" array). */ \ pixwt = ( wtprod[ 0 ] * *( wtptr[ 0 ] ) )*wgt; \ \ /* Update the output pixel with the required fraction of the input pixel \ value. */ \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ \ if( work ) { \ out[ off_out ] += c; \ work[ off_out ] += pixwt; \ } else {\ out[ off_out ] += c; \ } \ \ if ( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ \ /* Now update the weight value pointers and pixel offset to refer to \ the next output pixel to be considered. */ \ idim = 0; \ do { \ \ /* The first input dimension whose weight value pointer has not yet \ reached its final value has this pointer incremented, and the pixel \ offset into the input array is updated accordingly. */ \ if ( wtptr[ idim ] != wtptr_last[ idim ] ) { \ wtptr[ idim ]++; \ off_out += stride[ idim ]; \ break; \ \ /* Any earlier dimensions (which have reached the final pointer value) \ have this pointer returned to its lowest value. Again, the pixel \ offset into the input image is updated accordingly. */ \ } else { \ wtptr[ idim ] -= ( hi[ idim ] - lo[ idim ] ); \ off_out -= stride[ idim ] * \ ( hi[ idim ] - lo[ idim ] ); \ done = ( ++idim == ndim_out ); \ } \ } while ( !done ); \ } while ( !done ); \ } \ } \ } /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_SPREAD_KERNEL1(LD,long double,0) #endif MAKE_SPREAD_KERNEL1(D,double,0) MAKE_SPREAD_KERNEL1(F,float,0) MAKE_SPREAD_KERNEL1(I,int,1) MAKE_SPREAD_KERNEL1(B,signed char,1) MAKE_SPREAD_KERNEL1(UB,unsigned char,1) /* Undefine the macros used above. */ #undef KERNEL_ND #undef KERNEL_2D #undef KERNEL_1D #undef MAKE_SPREAD_KERNEL1 /* * Name: * SpreadLinear * Purpose: * Rebin a data grid, using the linear spreading scheme. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SpreadLinear( int ndim_out, * const int *lbnd_out, const int *ubnd_out, * const *in, const *in_var, * double infac, int npoint, const int *offset, * const double *const *coords, int flags, * badval, int npix_out, *out, * *out_var, double *work, int64_t *nused ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which rebins a rectangular region of an * input grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each input * grid point may be mapped on to a position in the output grid in * an arbitrary way. Where the positions given do not correspond * with a pixel centre in the input grid, the spreading scheme * used divides the input pixel value up linearly between the * nearest neighbouring output pixels in each dimension (there are 2 * nearest neighbours in 1 dimension, 4 in 2 dimensions, 8 in 3 * dimensions, etc.). * Parameters: * ndim_out * The number of dimensions in the output grid. This should be at * least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output grid, its extent along a particular * (i'th) dimension being ubnd_out[i]-lbnd_out[i]+1 (assuming "i" * is zero-based). They also define the output grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be rebinned. The numerical type * of these data should match the function used, as given by the * suffix on the function name. Note that details of how the input * grid maps on to this array (e.g. the storage order, number of * dimensions, etc.) is arbitrary and is specified entirely by means * of the "offset" array. The "in" array should therefore contain * sufficient elements to accommodate the "offset" values supplied. * There is no requirement that all elements of the "in" array * should be rebinned, and any which are not addressed by the * contents of the "offset" array will be ignored. * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. It is addressed in exactly the same way (via the * "offset" array) as the "in" array. * * If no variance estimates are required, a NULL pointer should * be given. * infac * A factor by which to multiply the input data values before use. * npoint * The number of input points which are to be rebinned. * offset * Pointer to an array of integers with "npoint" elements. For * each input point, this array should contain the zero-based * offset in the input array(s) (i.e. the "in" and, optionally, * the "in_var" arrays) from which the value to be rebinned should * be obtained. * coords * An array of pointers to double, with "ndim_out" elements. * Element "coords[coord]" should point at the first element of * an array of double (with "npoint" elements) which contains the * values of coordinate number "coord" for each point being * rebinned. The value of coordinate number "coord" for * rebinning point number "point" is therefore given by * "coords[coord][point]" (assuming both indices are * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding input data (and * variance) value will be ignored. * The bitwise OR of a set of flag values which control the * operation of the function. These are chosend from: * * - AST__USEBAD: indicates whether there are "bad" (i.e. missing) data * in the input array(s) which must be recognised. If this flag is not * set, all input values are treated literally. * - AST__GENVAR: Indicates that any input variances are to be * ignored, and that the output variances should be generated from * the spread of values contributing to each output pixel. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which resampled values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * npix_out * Number of pixels in output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the index of the first grid * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. The values returned * are estimates of the statistical variance of the corresponding * values in the "out" array, on the assumption that all errors in * input grid values (in the "in" array) are statistically independent * and that their variance estimates (in the "in_var" array) may * simply be summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * work * An optional pointer to a double array with the same size as * the "out" array. The contents of this array (if supplied) are * incremented by the accumulated weights assigned to each output pixel. * If no accumulated weights are required, a NULL pointer should be * given. * nused * An optional pointer to a int64_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. */ /* Define macros to implement the function for a specific data type. */ #define MAKE_SPREAD_LINEAR(X,Xtype,IntType) \ static void SpreadLinear##X( int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const Xtype *in, const Xtype *in_var, \ double infac, int npoint, const int *offset, \ const double *const *coords, int flags, \ Xtype badval, int npix_out, Xtype *out, \ Xtype *out_var, double *work, int64_t *nused, \ int *status ) { \ \ /* Local Variables: */ \ Xtype c; /* Contribution to output value */ \ Xtype in_val; /* Input value */ \ double *frac_hi; /* Pointer to array of weights */ \ double *frac_lo; /* Pointer to array of weights */ \ double *wt; /* Pointer to array of weights */ \ double *wtprod; /* Array of accumulated weights pointer */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double frac_hi_x; /* Pixel weight (x dimension) */ \ double frac_hi_y; /* Pixel weight (y dimension) */ \ double frac_lo_x; /* Pixel weight (x dimension) */ \ double frac_lo_y; /* Pixel weight (y dimension) */ \ double pfac; /* Scaled pixel weight */ \ double pixwt; /* Total pixel weight */ \ double wgt; /* Weight for input value */ \ double x; /* x coordinate value */ \ double xmax; /* x upper limit */ \ double xmin; /* x lower limit */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ double ymax; /* y upper limit */ \ double ymin; /* y lower limit */ \ int *dim; /* Pointer to array of pixel indices */ \ int *hi; /* Pointer to array of upper indices */ \ int *lo; /* Pointer to array of lower indices */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int done; /* All pixel indices done? */ \ int genvar; /* Generate output variances? */ \ int hi_x; /* Upper pixel index (x dimension) */ \ int hi_y; /* Upper pixel index (y dimension) */ \ int idim; /* Loop counter for dimensions */ \ int ii; /* Loop counter for weights */ \ int ixn; /* Pixel index (n-d) */ \ int lo_x; /* Lower pixel index (x dimension) */ \ int lo_y; /* Lower pixel index (y dimension) */ \ int off; /* Total offset to input pixel */ \ int off_in; /* Offset to input pixel */ \ int off_lo; /* Offset to "first" input pixel */ \ int off_out; /* Offset to output pixel */ \ int point; /* Loop counter for output points */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int varwgt; /* Use input variances as weights? */ \ int ystride; /* Stride along input grid y dimension */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Initialise variables to avoid "used of uninitialised variable" \ messages from dumb compilers. */ \ bad = 0; \ \ /* Determine if we are processing bad pixels or variances. */ \ usebad = flags & AST__USEBAD; \ usevar = 0; \ genvar = 0; \ if( flags & AST__GENVAR ) { \ genvar = out_var && work; \ } else if( flags & AST__USEVAR ) { \ usevar = in_var && out_var; \ } \ varwgt = ( flags & AST__VARWGT ) && in_var && work; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_out == 1 ) { \ \ /* Calculate the coordinate limits of the input grid. */ \ xmin = (double) lbnd_out[ 0 ] - 0.5; \ xmax = (double) ubnd_out[ 0 ] + 0.5; \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_1D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ LINEAR_1D(X,Xtype,1,0,1,IntType,1) \ } else { \ LINEAR_1D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ LINEAR_1D(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ LINEAR_1D(X,Xtype,0,0,1,IntType,1) \ } else { \ LINEAR_1D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_1D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ LINEAR_1D(X,Xtype,1,0,1,IntType,0) \ } else { \ LINEAR_1D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ LINEAR_1D(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ LINEAR_1D(X,Xtype,0,0,1,IntType,0) \ } else { \ LINEAR_1D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_out == 2 ) { \ \ /* Calculate the stride along the y dimension of the output grid. */ \ ystride = ubnd_out[ 0 ] - lbnd_out[ 0 ] + 1; \ \ /* Calculate the coordinate limits of the output grid in each \ dimension. */ \ xmin = (double) lbnd_out[ 0 ] - 0.5; \ xmax = (double) ubnd_out[ 0 ] + 0.5; \ ymin = (double) lbnd_out[ 1 ] - 0.5; \ ymax = (double) ubnd_out[ 1 ] + 0.5; \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_2D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ LINEAR_2D(X,Xtype,1,0,1,IntType,1) \ } else { \ LINEAR_2D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ LINEAR_2D(X,Xtype,0,1,0,IntType,1) \ }else if ( genvar ) { \ LINEAR_2D(X,Xtype,0,0,1,IntType,1) \ } else { \ LINEAR_2D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_2D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ LINEAR_2D(X,Xtype,1,0,1,IntType,0) \ } else { \ LINEAR_2D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ LINEAR_2D(X,Xtype,0,1,0,IntType,0) \ }else if ( genvar ) { \ LINEAR_2D(X,Xtype,0,0,1,IntType,0) \ } else { \ LINEAR_2D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ dim = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ frac_hi = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ frac_lo = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ hi = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ lo = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ stride = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ wt = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ wtprod = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the output grid. */ \ for ( s = 1, idim = 0; idim < ndim_out; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ \ /* Calculate the coordinate limits of the output grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_out[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_out[ idim ] + 0.5; \ } \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_ND(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ LINEAR_ND(X,Xtype,1,0,1,IntType,1) \ } else { \ LINEAR_ND(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ LINEAR_ND(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ LINEAR_ND(X,Xtype,0,0,1,IntType,1) \ } else { \ LINEAR_ND(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ LINEAR_ND(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ LINEAR_ND(X,Xtype,1,0,1,IntType,0) \ } else { \ LINEAR_ND(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ LINEAR_ND(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ LINEAR_ND(X,Xtype,0,0,1,IntType,0) \ } else { \ LINEAR_ND(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ } \ \ /* Free the workspace. */ \ dim = astFree( dim ); \ frac_hi = astFree( frac_hi ); \ frac_lo = astFree( frac_lo ); \ hi = astFree( hi ); \ lo = astFree( lo ); \ stride = astFree( stride ); \ wt = astFree( wt ); \ wtprod = astFree( wtprod ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ } \ \ } #define LINEAR_1D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the output grid. Also test if it is bad. */ \ x = coords[ 0 ][ point ]; \ bad = bad || ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ \ /* If OK, obtain the indices along the output grid x dimension of the \ two adjacent output pixels which will receive contributions from the \ input pixel. Also obtain the fractional weight to be applied to each of \ these pixels. */ \ if ( !bad ) { \ lo_x = (int) floor( x ); \ hi_x = lo_x + 1; \ frac_lo_x = (double) hi_x - x; \ frac_hi_x = 1.0 - frac_lo_x; \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* Obtain the offset within the output array of the first pixel to be \ updated (the one with the smaller index). */ \ off_lo = lo_x - lbnd_out[ 0 ]; \ \ /* If we are using the input data variances as weights, calculate the \ weight, and scale the fractions of each input pixel by the weight. */ \ if( Varwgt ) { \ wgt = 1.0/in_var[ off_in ]; \ frac_lo_x *= wgt; \ frac_hi_x *= wgt; \ } \ \ /* For each of the two pixels which may be updated, test if the pixel index \ lies within the output grid. Where it does, update the output pixel \ with the required fraction of the input pixel value. */ \ if ( lo_x >= lbnd_out[ 0 ] ) { \ pfac = frac_lo_x*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off_lo ] += CONV(IntType, c ); \ if( work ) work[ off_lo ] += frac_lo_x; \ if ( Usevar ) { \ out_var[ off_lo ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && frac_lo_x != 0.0 ) { \ out_var[ off_lo ] += c*c/frac_lo_x; \ work[ off_lo + npix_out ] += frac_lo_x*frac_lo_x; \ } \ } \ if ( hi_x <= ubnd_out[ 0 ] ) { \ pfac = frac_hi_x*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off_lo + 1 ] += CONV(IntType, c ); \ if( work ) work[ off_lo + 1 ] += frac_hi_x; \ if ( Usevar ) { \ out_var[ off_lo + 1 ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && frac_hi_x != 0.0 ) { \ out_var[ off_lo + 1 ] += c*c/frac_hi_x; \ work[ off_lo + 1 + npix_out ] += frac_hi_x*frac_hi_x; \ } \ } \ } \ } #define LINEAR_2D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the x coordinate of the current point and test if it lies \ outside the output grid. Also test if it is bad. */ \ y = coords[ 1 ][ point ]; \ bad = bad || ( y < ymin ) || ( y >= ymax ) || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* Similarly obtain and test the y coordinate. */ \ x = coords[ 0 ][ point ]; \ bad = bad || ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* If OK, obtain the indices along the output grid x dimension of the \ two adjacent pixels which recieve contributions from the input pixel. \ Also obtain the fractional weight to be applied to each of \ these pixels. */ \ lo_x = (int) floor( x ); \ hi_x = lo_x + 1; \ frac_lo_x = (double) hi_x - x; \ frac_hi_x = 1.0 - frac_lo_x; \ \ /* Repeat this process for the y dimension. */ \ lo_y = (int) floor( y ); \ hi_y = lo_y + 1; \ frac_lo_y = (double) hi_y - y; \ frac_hi_y = 1.0 - frac_lo_y; \ \ /* If we are using the input data variances as weights, calculate the \ weight, and scale the fractions of each input pixel by the weight. \ Since the product of two fractions is always used ot scale the input \ data values, we use the square root of the reciprocal of the variance \ as the weight (so that when the product of two fractions is taken, \ the square roots multiply together to give the required 1/variance \ weight). */ \ if( Varwgt ) { \ wgt = 1.0/sqrt( in_var[ off_in ] ); \ frac_lo_x *= wgt; \ frac_hi_x *= wgt; \ frac_lo_y *= wgt; \ frac_hi_y *= wgt; \ } \ \ /* Obtain the offset within the output array of the first pixel to be \ updated (the one with the smaller index along both dimensions). */ \ off_lo = lo_x - lbnd_out[ 0 ] + ystride * ( lo_y - lbnd_out[ 1 ] ); \ \ /* For each of the four pixels which may be updated, test if the pixel indices \ lie within the output grid. Where they do, update the output pixel \ with the required fraction of the input pixel value. */ \ if ( lo_y >= lbnd_out[ 1 ] ) { \ if ( lo_x >= lbnd_out[ 0 ] ) { \ pixwt = frac_lo_x * frac_lo_y; \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off_lo ] += CONV(IntType, c ); \ if( work ) work[ off_lo ] += pixwt; \ if ( Usevar ) { \ out_var[ off_lo ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off_lo ] += c*c/pixwt; \ work[ off_lo + npix_out ] += pixwt*pixwt; \ } \ } \ if ( hi_x <= ubnd_out[ 0 ] ) { \ off = off_lo + 1; \ pixwt = frac_hi_x * frac_lo_y; \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off ] += CONV(IntType, c ); \ if( work ) work[ off ] += pixwt; \ if ( Usevar ) { \ out_var[ off ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off ] += c*c/pixwt; \ work[ off + npix_out ] += pixwt*pixwt; \ } \ } \ } \ if ( hi_y <= ubnd_out[ 1 ] ) { \ if ( lo_x >= lbnd_out[ 0 ] ) { \ off = off_lo + ystride; \ pixwt = frac_lo_x * frac_hi_y; \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off ] += CONV(IntType, c ); \ if( work ) work[ off ] += pixwt; \ if ( Usevar ) { \ out_var[ off ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off ] += c*c/pixwt; \ work[ off + npix_out ] += pixwt*pixwt; \ } \ } \ if ( hi_x <= ubnd_out[ 0 ] ) { \ off = off_lo + ystride + 1; \ pixwt = frac_hi_x * frac_hi_y; \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off ] += CONV(IntType, c ); \ if( work ) work[ off ] += pixwt; \ if ( Usevar ) { \ out_var[ off ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off ] += c*c/pixwt; \ work[ off + npix_out ] += pixwt*pixwt; \ } \ } \ } \ } \ } \ } #define LINEAR_ND(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Initialise offsets into the output array. Then loop to obtain each \ coordinate associated with the current output point. */ \ if( !bad ) { \ off_out = 0; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate lies outside the output grid. Also test if \ it is bad. If either is true, the corresponding output pixel value \ will be bad, so give up on this point. */ \ bad = ( xn < xn_min[ idim ] ) || ( xn >= xn_max[ idim ] ) || \ ( xn == AST__BAD ); \ if ( bad ) break; \ \ /* Obtain the indices along the current dimension of the output grid of \ the two (usually adjacent) pixels which will be updated. If necessary, \ however, restrict each index to ensure it does not lie outside the \ input grid. Also calculate the fractional weight to be given to each \ pixel in order to divide the input value linearly between them. */ \ ixn = (int) floor( xn ); \ lo[ idim ] = MaxI( ixn, lbnd_out[ idim ], status ); \ hi[ idim ] = MinI( ixn + 1, ubnd_out[ idim ], status ); \ frac_lo[ idim ] = 1.0 - fabs( xn - (double) lo[ idim ] ); \ frac_hi[ idim ] = 1.0 - fabs( xn - (double) hi[ idim ] ); \ \ /* Store the lower index involved in spreading along each \ dimension and accumulate the offset from the start of the output \ array of the pixel which has these indices. */ \ dim[ idim ] = lo[ idim ]; \ off_out += stride[ idim ] * ( lo[ idim ] - lbnd_out[ idim ] ); \ \ /* Also store the fractional weight associated with the lower pixel \ along each dimension. */ \ wt[ idim ] = frac_lo[ idim ]; \ } \ \ /* If we are using the input data variances as weights, calculate the \ weight, and scale the fractions of each input pixel by the weight. */ \ if( Varwgt ) { \ wgt = pow( in_var[ off_in ], -1.0/(double)ndim_out ); \ for ( idim = 0; idim < ndim_out; idim++ ) { \ frac_lo[ idim ] *= wgt; \ frac_hi[ idim ] *= wgt; \ wt[ idim ] = frac_lo[ idim ]; \ } \ } \ \ /* If OK, increment the number of input pixels pasted into the output array. */ \ if ( !bad ) { \ if( nused ) (*nused)++; \ \ /* Loop over adjacent output pixels to divide up the input value. */ \ idim = ndim_out - 1; \ wtprod[ idim ] = 1.0; \ done = 0; \ do { \ \ /* Each pixel pixel to be updated has a total weight equal to the product \ of the weights which account for the displacement of its centre from \ the required position along each dimension. However, since we typically \ only change the index of one dimension at a time, we can avoid forming \ this product repeatedly by retaining an array of accumulated weight \ products for all higher dimensions. We need then only update the \ lower elements in this array, corresponding to those dimensions \ whose index has changed. We do this here, "idim" being the index of \ the most significant dimension to have changed. Note that on the \ first pass, all dimensions are considered changed, causing this \ array to be initialised. */ \ for ( ii = idim; ii >= 1; ii-- ) { \ wtprod[ ii - 1 ] = wtprod[ ii ] * wt[ ii ]; \ } \ \ /* Update the relevent output pixel. The pixel weight is formed by including \ the weight factor for dimension zero, since this is not included in \ the "wtprod" array. */ \ pixwt = wtprod[ 0 ] * wt[ 0 ]; \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ out[ off_out ] += CONV(IntType, c ); \ if( work ) work[ off_out ] += pixwt; \ if ( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ } else if ( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ \ /* Now update the indices, offset and weight factors to refer to the \ next output pixel to be updated. */ \ idim = 0; \ do { \ \ /* The first input dimension which still refers to the pixel with the \ lower of the two possible indices is switched to refer to the other \ pixel (with the higher index). The offset into the output array and \ the fractional weight factor for this dimension are also updated \ accordingly. */ \ if ( dim[ idim ] != hi[ idim ] ) { \ dim[ idim ] = hi[ idim ]; \ off_out += stride[ idim ]; \ wt[ idim ] = frac_hi[ idim ]; \ break; \ \ /* Any earlier dimensions (referring to the higher index) are switched \ back to the lower index, if not already there, before going on to \ consider the next dimension. (This process is the same as \ incrementing a binary number and propagating overflows up through \ successive digits, except that dimensions where the "lo" and "hi" \ values are the same can only take one value.) The process stops at \ the first attempt to return the final dimension to the lower \ index. */ \ } else { \ if ( dim[ idim ] != lo[ idim ] ) { \ dim[ idim ] = lo[ idim ]; \ off_out -= stride[ idim ]; \ wt[ idim ] = frac_lo[ idim ]; \ } \ done = ( ++idim == ndim_out ); \ } \ } while ( !done ); \ } while ( !done ); \ } \ } \ } /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_SPREAD_LINEAR(LD,long double,0) #endif MAKE_SPREAD_LINEAR(D,double,0) MAKE_SPREAD_LINEAR(F,float,0) MAKE_SPREAD_LINEAR(I,int,1) MAKE_SPREAD_LINEAR(B,signed char,1) MAKE_SPREAD_LINEAR(UB,unsigned char,1) /* Undefine the macros used above. */ #undef LINEAR_1D #undef LINEAR_2D #undef LINEAR_ND #undef MAKE_SPREAD_LINEAR /* * Name: * SpreadNearest * Purpose: * Rebin a data grid, using the nearest-pixel spreading scheme. * Type: * Private function. * Synopsis: * #include "mapping.h" * void SpreadNearest( int ndim_out, const int *lbnd_out, * const int *ubnd_out, const *in, * const *in_var, double infac, int npoint, * const int *offset, const double *const *coords, * int flags, badval, int npix_out, *out, * *out_var, double *work, int64_t *nused, * int *status ) * Class Membership: * Mapping member function. * Description: * This is a set of functions which rebins a rectangular region of an * input grid of data (and, optionally, associated statistical variance * values) so as to place them into a new output grid. Each input * grid point may be mapped on to a position in the output grid in * an arbitrary way. Where the positions given do not correspond * with a pixel centre in the output grid, the spreading scheme * used is simply to select the nearest pixel (i.e. the one whose * bounds contain the supplied position). * Parameters: * ndim_out * The number of dimensions in the output grid. This should be at * least one. * lbnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the first * pixel in the output grid along each dimension. * ubnd_out * Pointer to an array of integers, with "ndim_out" elements. * This should give the coordinates of the centre of the last * pixel in the output grid along each dimension. * * Note that "lbnd_out" and "ubnd_out" together define the shape * and size of the output grid, its extent along a particular * (i'th) dimension being ubnd_out[i]-lbnd_out[i]+1 (assuming "i" * is zero-based). They also define the output grid's coordinate * system, with each pixel being of unit extent along each * dimension with integral coordinate values at its centre. * in * Pointer to the array of data to be rebinned. The numerical type * of these data should match the function used, as given by the * suffix on the function name. Note that details of how the input * grid maps on to this array (e.g. the storage order, number of * dimensions, etc.) is arbitrary and is specified entirely by means * of the "offset" array. The "in" array should therefore contain * sufficient elements to accommodate the "offset" values supplied. * There is no requirement that all elements of the "in" array * should be rebinned, and any which are not addressed by the * contents of the "offset" array will be ignored. * in_var * An optional pointer to a second array of positive numerical * values (with the same size and type as the "in" array), which * represent estimates of the statistical variance associated * with each element of the "in" array. If this second array is * given (along with the corresponding "out_var" array), then * estimates of the variance of the resampled data will also be * returned. It is addressed in exactly the same way (via the * "offset" array) as the "in" array. * * If no variance estimates are required, a NULL pointer should * be given. * infac * A factor by which to multiply the input data values before use. * npoint * The number of input points which are to be rebinned. * offset * Pointer to an array of integers with "npoint" elements. For * each input point, this array should contain the zero-based * offset in the input array(s) (i.e. the "in" and, optionally, * the "in_var" arrays) from which the value to be rebinned should * be obtained. * coords * An array of pointers to double, with "ndim_out" elements. * Element "coords[coord]" should point at the first element of * an array of double (with "npoint" elements) which contains the * values of coordinate number "coord" for each point being * rebinned. The value of coordinate number "coord" for * rebinning point number "point" is therefore given by * "coords[coord][point]" (assuming both indices are * zero-based). If any point has a coordinate value of AST__BAD * associated with it, then the corresponding input data (and * variance) value will be ignored. * flags * The bitwise OR of a set of flag values which control the * operation of the function. These are chosend from: * * - AST__USEBAD: indicates whether there are "bad" (i.e. missing) data * in the input array(s) which must be recognised. If this flag is not * set, all input values are treated literally. * - AST__GENVAR: Indicates that output variances should be generated * from the spread of values contributing to each output pixel. * - AST__USEVAR: Indicates that output variances should be generated * by rebinning the input variances. * - AST__VARWGT: Indicates that input variances should be used to * create weights for the input data values. * * Only one of AST__GENVAR and AST__USEVAR should be supplied. * badval * If the AST__USEBAD flag is set in the "flags" value (above), * this parameter specifies the value which is used to identify * bad data and/or variance values in the input array(s). Its * numerical type must match that of the "in" (and "in_var") * arrays. The same value will also be used to flag any output * array elements for which resampled values could not be * obtained. The output arrays(s) may be flagged with this * value whether or not the AST__USEBAD flag is set (the * function return value indicates whether any such values have * been produced). * npix_out * Number of pixels in output array. * out * Pointer to an array with the same data type as the "in" * array, into which the rebinned data will be returned. The * storage order should be such that the index of the first grid * dimension varies most rapidly and that of the final dimension * least rapidly (i.e. Fortran array storage order). * out_var * An optional pointer to an array with the same data type and * size as the "out" array, into which variance estimates for * the rebinned values may be returned. This array will only be * used if the "in_var" array has been given. The values returned * are estimates of the statistical variance of the corresponding * values in the "out" array, on the assumption that all errors in * input grid values (in the "in" array) are statistically independent * and that their variance estimates (in the "in_var" array) may * simply be summed (with appropriate weighting factors). * * If no output variance estimates are required, a NULL pointer * should be given. * work * A pointer to an array with the same data type and size as the "out" * array which is used as work space. The values in the supplied * array are incremented on exit by the sum of the weights used * with each output pixel. * nused * An optional pointer to a size_t which will be incremented by the * number of input values pasted into the output array. Ignored if NULL. * Notes: * - There is a separate function for each numerical type of * gridded data, distinguished by replacing the in the function * name by the appropriate 1- or 2-character suffix. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_SPREAD_NEAREST(X,Xtype,IntType) \ static void SpreadNearest##X( int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const Xtype *in, const Xtype *in_var, \ double infac, int npoint, const int *offset, \ const double *const *coords, int flags, \ Xtype badval, int npix_out, Xtype *out, \ Xtype *out_var, double *work, int64_t *nused, \ int *status ) { \ \ /* Local Variables: */ \ Xtype c; /* Contribution to output value */ \ Xtype in_val; /* Input data value */ \ double *xn_max; /* Pointer to upper limits array (n-d) */ \ double *xn_min; /* Pointer to lower limits array (n-d) */ \ double pfac; /* Input weight with extra supplied factor */ \ double pixwt; /* Weight for input value */ \ double x; /* x coordinate value */ \ double xmax; /* x upper limit */ \ double xmin; /* x lower limit */ \ double xn; /* Coordinate value (n-d) */ \ double y; /* y coordinate value */ \ double ymax; /* y upper limit */ \ double ymin; /* y lower limit */ \ int *stride; /* Pointer to array of dimension strides */ \ int bad; /* Output pixel bad? */ \ int genvar; /* Generate output variances? */ \ int idim; /* Loop counter for dimensions */ \ int ix; /* Number of pixels offset in x direction */ \ int ixn; /* Number of pixels offset (n-d) */ \ int iy; /* Number of pixels offset in y direction */ \ int off_in; /* Pixel offset into input array */ \ int off_out; /* Pixel offset into output array */ \ int point; /* Loop counter for output points */ \ int s; /* Temporary variable for strides */ \ int usebad; /* Use "bad" input pixel values? */ \ int usevar; /* Process variance array? */ \ int varwgt; /* Use input variances as weights? */ \ int ystride; /* Stride along input grid y direction */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Determine if we are processing bad pixels or variances. */ \ usebad = flags & AST__USEBAD; \ usevar = 0; \ genvar = 0; \ if( flags & AST__GENVAR ) { \ genvar = out_var && work; \ } else if( flags & AST__USEVAR ) { \ usevar = in_var && out_var; \ } \ varwgt = ( flags & AST__VARWGT ) && in_var && work; \ \ /* Handle the 1-dimensional case optimally. */ \ /* ---------------------------------------- */ \ if ( ndim_out == 1 ) { \ \ /* Calculate the coordinate limits of the output array. */ \ xmin = (double) lbnd_out[ 0 ] - 0.5; \ xmax = (double) ubnd_out[ 0 ] + 0.5; \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_1D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_1D(X,Xtype,1,0,1,IntType,1) \ } else { \ NEAR_1D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ NEAR_1D(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_1D(X,Xtype,0,0,1,IntType,1) \ } else { \ NEAR_1D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_1D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_1D(X,Xtype,1,0,1,IntType,0) \ } else { \ NEAR_1D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ NEAR_1D(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_1D(X,Xtype,0,0,1,IntType,0) \ } else { \ NEAR_1D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Handle the 2-dimensional case optimally. */ \ /* ---------------------------------------- */ \ } else if ( ndim_out == 2 ) { \ \ /* Calculate the stride along the y dimension of the output grid. */ \ ystride = ubnd_out[ 0 ] - lbnd_out[ 0 ] + 1; \ \ /* Calculate the coordinate limits of the output array in each \ dimension. */ \ xmin = (double) lbnd_out[ 0 ] - 0.5; \ xmax = (double) ubnd_out[ 0 ] + 0.5; \ ymin = (double) lbnd_out[ 1 ] - 0.5; \ ymax = (double) ubnd_out[ 1 ] + 0.5; \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_2D(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_2D(X,Xtype,1,0,1,IntType,1) \ } else { \ NEAR_2D(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ NEAR_2D(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_2D(X,Xtype,0,0,1,IntType,1) \ } else { \ NEAR_2D(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_2D(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_2D(X,Xtype,1,0,1,IntType,0) \ } else { \ NEAR_2D(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ NEAR_2D(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_2D(X,Xtype,0,0,1,IntType,0) \ } else { \ NEAR_2D(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ \ /* Handle other numbers of dimensions. */ \ /* ----------------------------------- */ \ } else { \ \ /* Allocate workspace. */ \ stride = astMalloc( sizeof( int ) * (size_t) ndim_out ); \ xn_max = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ xn_min = astMalloc( sizeof( double ) * (size_t) ndim_out ); \ if ( astOK ) { \ \ /* Calculate the stride along each dimension of the output grid. */ \ for ( s = 1, idim = 0; idim < ndim_out; idim++ ) { \ stride[ idim ] = s; \ s *= ubnd_out[ idim ] - lbnd_out[ idim ] + 1; \ \ /* Calculate the coordinate limits of the output grid in each \ dimension. */ \ xn_min[ idim ] = (double) lbnd_out[ idim ] - 0.5; \ xn_max[ idim ] = (double) ubnd_out[ idim ] + 0.5; \ } \ \ /* Identify eight cases, according to whether bad pixels and/or variances \ are being processed and/or used. In each case we assign constant values \ (0 or 1) to the "Usebad", "Usevar" and "Varwgt" flags so that code for \ handling bad pixels and variances can be eliminated by the compiler's \ optimisation system when not required. */ \ if( varwgt ) { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_ND(X,Xtype,1,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_ND(X,Xtype,1,0,1,IntType,1) \ } else { \ NEAR_ND(X,Xtype,1,0,0,IntType,1) \ } \ } else { \ if ( usevar ) { \ NEAR_ND(X,Xtype,0,1,0,IntType,1) \ } else if ( genvar ) { \ NEAR_ND(X,Xtype,0,0,1,IntType,1) \ } else { \ NEAR_ND(X,Xtype,0,0,0,IntType,1) \ } \ } \ } else { \ if ( usebad ) { \ if ( usevar ) { \ NEAR_ND(X,Xtype,1,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_ND(X,Xtype,1,0,1,IntType,0) \ } else { \ NEAR_ND(X,Xtype,1,0,0,IntType,0) \ } \ } else { \ if ( usevar ) { \ NEAR_ND(X,Xtype,0,1,0,IntType,0) \ } else if ( genvar ) { \ NEAR_ND(X,Xtype,0,0,1,IntType,0) \ } else { \ NEAR_ND(X,Xtype,0,0,0,IntType,0) \ } \ } \ } \ } \ \ /* Free the workspace. */ \ stride = astFree( stride ); \ xn_max = astFree( xn_max ); \ xn_min = astFree( xn_min ); \ } \ \ } #define NEAR_1D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the output x coordinate corresponding to the centre of the \ current input pixel and test if it lies outside the output grid, or \ is bad. */ \ x = coords[ 0 ][ point ]; \ bad = bad || ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* If not, then obtain the offset within the output grid of the pixel \ which contains the current input point. */ \ off_out = (int) floor( x + 0.5 ) - lbnd_out[ 0 ]; \ \ /* If we are using the input data variances as weights, calculate the \ weight. */ \ if( Varwgt ) { \ pixwt = 1.0/in_var[ off_in ]; \ } else { \ pixwt = 1.0; \ } \ \ /* Get the weighted input data value, including any extra scaling. */ \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ \ /* Increment the value of this output pixel by the weighted input pixel \ value, and increment the sum of the weights. */ \ out[ off_out ] += CONV(IntType, c ); \ if( work ) work[ off_out ] += pixwt; \ \ /* If output variances are being calculated on the basis of the input \ variances, then we also store the required sum in "out_var". */ \ if( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ \ /* If output variances are being calculated on the basis of the spread of \ input values, we need the sum of the squared weighted data values, the \ sum of the weights (already in the first half of the "work" array), and \ the sum of the squared weights. */ \ } else if( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ } \ } #define NEAR_2D(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ /* Obtain the output y coordinate corresponding to the centre of the \ current input pixel and test if it lies outside the output grid, or \ is bad. */ \ y = coords[ 1 ][ point ]; \ bad = bad || ( y < ymin ) || ( y >= ymax ) || ( y == AST__BAD ); \ if ( !bad ) { \ \ /* Obtain the output x coordinate corresponding to the centre of the \ current input pixel and test if it lies outside the output grid, or \ is bad. */ \ x = coords[ 0 ][ point ]; \ bad = bad || ( x < xmin ) || ( x >= xmax ) || ( x == AST__BAD ); \ if ( !bad ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* Obtain the offsets along each output grid dimension of the output \ pixel which is to receive the input pixel value. */ \ ix = (int) floor( x + 0.5 ) - lbnd_out[ 0 ]; \ iy = (int) floor( y + 0.5 ) - lbnd_out[ 1 ]; \ \ /* Calculate this pixel's offset from the start of the output array. */ \ off_out = ix + ystride * iy; \ \ /* If we are using the input data variances as weights, calculate the \ weight. */ \ if( Varwgt ) { \ pixwt = 1.0/in_var[ off_in ]; \ } else { \ pixwt = 1.0; \ } \ \ /* Get the weighted input data value, including any extra scaling. */ \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ \ /* Increment the value of this output pixel by the weighted input pixel \ value, and increment the sum of the weights. */ \ out[ off_out ] += CONV(IntType, c ); \ if( work ) work[ off_out ] += pixwt; \ \ /* If output variances are being calculated on the basis of the input \ variances, then we also store the required sum in "out_var". */ \ if( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ \ /* If output variances are being calculated on the basis of the spread of \ input values, we need the sum of the squared weighted data values, the \ sum of the weights (already in the first half of the "work" array), and \ the sum of the squared weights. */ \ } else if( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ } \ } \ } #define NEAR_ND(X,Xtype,Usebad,Usevar,Genvar,IntType,Varwgt) \ \ /* Loop round all input points which are to be rebinned. */ \ for( point = 0; point < npoint; point++ ) { \ \ /* Obtain the input data value which is to be added into the output array. */ \ off_in = offset[ point ]; \ in_val = in[ off_in ]; \ \ /* If necessary, test if the input data value or variance is bad. If we \ are using the reciprocal of the input variances as weights, then \ variance values of zero are also effectively bad (but we can use input \ variances of zero otherwise). */ \ if ( Usebad ) { \ bad = ( in_val == badval ); \ if ( Varwgt ) { \ bad = bad || ( in_var[ off_in ] == badval ) \ || ( in_var[ off_in ] <= 0.0 ); \ } else if ( Usevar ) { \ bad = bad || ( in_var[ off_in ] == badval ); \ } \ } else { \ if ( Varwgt ) { \ bad = ( in_var[ off_in ] <= 0.0 ); \ } else { \ bad = 0; \ } \ } \ \ if( !bad ) { \ \ /* Initialise the offset into the output array. Then loop to obtain \ each coordinate associated with the current output point. */ \ off_out = 0; \ for ( idim = 0; idim < ndim_out; idim++ ) { \ xn = coords[ idim ][ point ]; \ \ /* Test if the coordinate lies outside the output grid, or is bad. If \ either is true, the corresponding input pixel value will be ignored, \ so give up on this point. */ \ bad = ( xn < xn_min[ idim ] ) || ( xn >= xn_max[ idim ] ) || \ ( xn == AST__BAD ); \ if ( bad ) { \ break; \ } \ \ /* Obtain the offset along the current output grid dimension of the \ output pixel which is to receive the input pixel value. */ \ ixn = (int) floor( xn + 0.5 ) - lbnd_out[ idim ]; \ \ /* Accumulate this pixel's offset from the start of the output array. */ \ off_out += ixn * stride[ idim ]; \ } \ \ if( !bad ) { \ \ /* Increment the number of input pixels pasted into the output array. */ \ if( nused ) (*nused)++; \ \ /* If we are using the input data variances as weights, calculate the \ weight. */ \ if( Varwgt ) { \ pixwt = 1.0/in_var[ off_in ]; \ } else { \ pixwt = 1.0; \ } \ \ /* Get the weighted input data value, including any extra scaling. */ \ pfac = pixwt*infac; \ c = CONV(IntType,pfac*in_val); \ \ /* Increment the value of this output pixel by the weighted input pixel \ value, and increment the sum of the weights. */ \ out[ off_out ] += CONV(IntType, c ); \ if( work ) work[ off_out ] += pixwt; \ \ /* If output variances are being calculated on the basis of the input \ variances, then we also store the required sum in "out_var". */ \ if( Usevar ) { \ out_var[ off_out ] += CONV(IntType,in_var[ off_in ]*pfac*pfac); \ \ /* If output variances are being calculated on the basis of the spread of \ input values, we need the sum of the squared weighted data values, the \ sum of the weights (already in the first half of the "work" array), and \ the sum of the squared weights. */ \ } else if( Genvar && pixwt != 0.0 ) { \ out_var[ off_out ] += c*c/pixwt; \ work[ off_out + npix_out ] += pixwt*pixwt; \ } \ } \ } \ } /* Expand the main macro above to generate a function for each required signed data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_SPREAD_NEAREST(LD,long double,0) #endif MAKE_SPREAD_NEAREST(D,double,0) MAKE_SPREAD_NEAREST(F,float,0) MAKE_SPREAD_NEAREST(I,int,1) MAKE_SPREAD_NEAREST(B,signed char,1) MAKE_SPREAD_NEAREST(UB,unsigned char,1) /* Undefine the macros used above. */ #undef NEAR_ND #undef NEAR_2D #undef NEAR_1D #undef MAKE_SPREAD_NEAREST static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Mapping. * Type: * Private function. * Synopsis: * #include "mapping.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Mapping member function (over-rides the astTestAttrib protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Mapping's attributes. * Parameters: * this * Pointer to the Mapping. * 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: */ AstMapping *this; /* Pointer to the Mapping structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Mapping structure. */ this = (AstMapping *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Invert. */ /* ------- */ if ( !strcmp( attrib, "invert" ) ) { result = astTestInvert( this ); /* Report. */ /* ------- */ } else if ( !strcmp( attrib, "report" ) ) { result = astTestReport( this ); /* If the name is not recognised, test if it matches any of the read-only attributes of this class. If it does, then return zero. */ } else if ( !strcmp( attrib, "nin" ) || !strcmp( attrib, "islinear" ) || !strcmp( attrib, "issimple" ) || !strcmp( attrib, "nout" ) || !strcmp( attrib, "tranforward" ) || !strcmp( attrib, "traninverse" ) ) { result = 0; /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static void Tran1( AstMapping *this, int npoint, const double xin[], int forward, double xout[], int *status ) { /* *++ * Name: c astTran1 f AST_TRAN1 * Purpose: * Transform 1-dimensional coordinates. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astTran1( AstMapping *this, int npoint, const double xin[], c int forward, double xout[] ) f CALL AST_TRAN1( THIS, NPOINT, XIN, FORWARD, XOUT, STATUS ) * Class Membership: * Mapping method. * Description: c This function applies a Mapping to transform the coordinates of f This routine applies a Mapping to transform the coordinates of * a set of points in one dimension. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be applied. c npoint f NPOINT = INTEGER (Given) * The number of points to be transformed. c xin f XIN( NPOINT ) = DOUBLE PRECISION (Given) c An array of "npoint" coordinate values for the input f An array of coordinate values for the input * (untransformed) points. c forward f FORWARD = LOGICAL (Given) c A non-zero value indicates that the Mapping's forward c coordinate transformation is to be applied, while a zero c value indicates that the inverse transformation should be c used. f A .TRUE. value indicates that the Mapping's forward f coordinate transformation is to be applied, while a .FALSE. f value indicates that the inverse transformation should be f used. c xout f XOUT( NPOINT ) = DOUBLE PRECISION (Returned) c An array (with "npoint" elements) into which the f An array into which the * coordinates of the output (transformed) points will be written. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The Mapping supplied must have the value 1 for both its Nin * and Nout attributes. *-- */ /* Local Variables: */ AstPointSet *in_points; /* Pointer to input PointSet */ AstPointSet *out_points; /* Pointer to output PointSet */ const double *in_ptr[ 1 ]; /* Array of input data pointers */ double *out_ptr[ 1 ]; /* Array of output data pointers */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the Mapping and numbers of points/coordinates. */ ValidateMapping( this, forward, npoint, 1, 1, "astTran1", status ); /* Set up pointers to the input and output coordinate arrays. */ if ( astOK ) { in_ptr[ 0 ] = xin; out_ptr[ 0 ] = xout; /* Create PointSets to describe the input and output points. */ in_points = astPointSet( npoint, 1, "", status ); out_points = astPointSet( npoint, 1, "", status ); /* Associate the data pointers with the PointSets (note we must explicitly remove the "const" qualifier from the input data here, although they will not be modified). */ astSetPoints( in_points, (double **) in_ptr ); astSetPoints( out_points, out_ptr ); /* Apply the required transformation to the coordinates. */ (void) astTransform( this, in_points, forward, out_points ); /* If the Mapping's Report attribute is set, report the effect the Mapping has had on the coordinates. */ if ( astGetReport( this ) ) astReportPoints( this, forward, in_points, out_points ); /* Delete the two PointSets. */ in_points = astDelete( in_points ); out_points = astDelete( out_points ); } } static void Tran2( AstMapping *this, int npoint, const double xin[], const double yin[], int forward, double xout[], double yout[], int *status ) { /* *++ * Name: c astTran2 f AST_TRAN2 * Purpose: * Transform 2-dimensional coordinates. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astTran2( AstMapping *this, c int npoint, const double xin[], const double yin[], c int forward, double xout[], double yout[] ) f CALL AST_TRAN2( THIS, NPOINT, XIN, YIN, FORWARD, XOUT, YOUT, STATUS ) * Class Membership: * Mapping method. * Description: c This function applies a Mapping to transform the coordinates of f This routine applies a Mapping to transform the coordinates of * a set of points in two dimensions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be applied. c npoint f NPOINT = INTEGER (Given) * The number of points to be transformed. c xin f XIN( NPOINT ) = DOUBLE PRECISION (Given) c An array of "npoint" X-coordinate values for the input f An array of X-coordinate values for the input * (untransformed) points. c yin f YIN( NPOINT ) = DOUBLE PRECISION (Given) c An array of "npoint" Y-coordinate values for the input f An array of Y-coordinate values for the input * (untransformed) points. c forward f FORWARD = LOGICAL (Given) c A non-zero value indicates that the Mapping's forward c coordinate transformation is to be applied, while a zero c value indicates that the inverse transformation should be c used. f A .TRUE. value indicates that the Mapping's forward f coordinate transformation is to be applied, while a .FALSE. f value indicates that the inverse transformation should be f used. c xout f XOUT( NPOINT ) = DOUBLE PRECISION (Returned) c An array (with "npoint" elements) into which the f An array into which the * X-coordinates of the output (transformed) points will be written. c yout f YOUT( NPOINT ) = DOUBLE PRECISION (Returned) c An array (with "npoint" elements) into which the f An array into which the * Y-coordinates of the output (transformed) points will be written. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The Mapping supplied must have the value 2 for both its Nin * and Nout attributes. *-- */ /* Local Variables: */ AstPointSet *in_points; /* Pointer to input PointSet */ AstPointSet *out_points; /* Pointer to output PointSet */ const double *in_ptr[ 2 ]; /* Array of input data pointers */ double *out_ptr[ 2 ]; /* Array of output data pointers */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the Mapping and the numbers of points/coordinates. */ ValidateMapping( this, forward, npoint, 2, 2, "astTran2", status ); /* Set up pointers to the input and output coordinate arrays. */ if ( astOK ) { in_ptr[ 0 ] = xin; in_ptr[ 1 ] = yin; out_ptr[ 0 ] = xout; out_ptr[ 1 ] = yout; /* Create PointSets to describe the input and output points. */ in_points = astPointSet( npoint, 2, "", status ); out_points = astPointSet( npoint, 2, "", status ); /* Associate the data pointers with the PointSets (note we must explicitly remove the "const" qualifier from the input data here, although they will not be modified). */ astSetPoints( in_points, (double **) in_ptr ); astSetPoints( out_points, out_ptr ); /* Apply the required transformation to the coordinates. */ (void) astTransform( this, in_points, forward, out_points ); /* If the Mapping's Report attribute is set, report the effect the Mapping has had on the coordinates. */ if ( astGetReport( this ) ) astReportPoints( this, forward, in_points, out_points ); /* Delete the two PointSets. */ in_points = astDelete( in_points ); out_points = astDelete( out_points ); } } static void TranGrid( AstMapping *this, int ncoord_in, const int lbnd[], const int ubnd[], double tol, int maxpix, int forward, int ncoord_out, int outdim, double *out, int *status ) { /* *++ * Name: c astTranGrid f AST_TRANGRID * Purpose: * Transform a grid of positions * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astTranGrid( AstMapping *this, int ncoord_in, c const int lbnd[], const int ubnd[], c double tol, int maxpix, int forward, c int ncoord_out, int outdim, double *out ); f CALL AST_TRANGRID( THIS, NCOORD_IN, LBND, UBND, TOL, MAXPIX, f FORWARD, NCOORD_OUT, OUTDIM, OUT, STATUS ) * Class Membership: * Mapping method. * Description: * This function uses the supplied Mapping to transforms a regular square * grid of points covering a specified box. It attempts to do this * quickly by first approximating the Mapping with a linear transformation * applied over the whole region of the input grid which is being used. * If this proves to be insufficiently accurate, the input region is * sub-divided into two along its largest dimension and the process is * repeated within each of the resulting sub-regions. This process of * sub-division continues until a sufficiently good linear approximation * is found, or the region to which it is being applied becomes too small * (in which case the original Mapping is used directly). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be applied. c ncoord_in f NCOORD_IN = INTEGER (Given) * The number of coordinates being supplied for each box corner * (i.e. the number of dimensions of the space in which the * input points reside). c lbnd f LBND( NCOORD_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ncoord_in" elements, f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c ubnd f UBND( NCOORD_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ncoord_in" elements, f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd" and "ubnd" together define the shape f Note that LBND and UBND together define the shape * and size of the input grid, its extent along a particular c (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the c index "j" to be zero-based). They also define f (J'th) dimension being UBND(J)-LBND(J)+1. They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. c tol f TOL = DOUBLE PRECISION (Given) * The maximum tolerable geometrical distortion which may be * introduced as a result of approximating non-linear Mappings * by a set of piece-wise linear transformations. This should be * expressed as a displacement within the output coordinate system * of the Mapping. * * If piece-wise linear approximation is not required, a value * of zero may be given. This will ensure that the Mapping is * used without any approximation, but may increase execution * time. * * If the value is too high, discontinuities between the linear * approximations used in adjacent panel will be higher. If this * is a problem, reduce the tolerance value used. c maxpix f MAXPIX = INTEGER (Given) * A value which specifies an initial scale size (in input grid points) * for the adaptive algorithm which approximates non-linear Mappings * with piece-wise linear transformations. Normally, this should * be a large value (larger than any dimension of the region of * the input grid being used). In this case, a first attempt to * approximate the Mapping by a linear transformation will be * made over the entire input region. * * If a smaller value is used, the input region will first be c divided into sub-regions whose size does not exceed "maxpix" f divided into sub-regions whose size does not exceed MAXPIX * grid points in any dimension. Only at this point will attempts * at approximation commence. * * This value may occasionally be useful in preventing false * convergence of the adaptive algorithm in cases where the * Mapping appears approximately linear on large scales, but has * irregularities (e.g. holes) on smaller scales. A value of, * say, 50 to 100 grid points can also be employed as a safeguard * in general-purpose software, since the effect on performance is * minimal. * * If too small a value is given, it will have the effect of * inhibiting linear approximation altogether (equivalent to c setting "tol" to zero). Although this may degrade f setting TOL to zero). Although this may degrade * performance, accurate results will still be obtained. c forward f FORWARD = LOGICAL (Given) c A non-zero value indicates that the Mapping's forward c coordinate transformation is to be applied, while a zero c value indicates that the inverse transformation should be c used. f A .TRUE. value indicates that the Mapping's forward f coordinate transformation is to be applied, while a .FALSE. f value indicates that the inverse transformation should be f used. c ncoord_out f NCOORD_OUT = INTEGER (Given) * The number of coordinates being generated by the Mapping for * each output point (i.e. the number of dimensions of the * space in which the output points reside). This need not be c the same as "ncoord_in". f the same as NCOORD_IN. c outdim f OUTDIM = INTEGER (Given) c The number of elements along the second dimension of the "out" f The number of elements along the first dimension of the OUT * array (which will contain the output coordinates). The value * given should not be less than the number of points in the grid. c out f OUT( OUTDIM, NCOORD_OUT ) = DOUBLE PRECISION (Returned) c The address of the first element in a 2-dimensional array of c shape "[ncoord_out][outdim]", into c which the coordinates of the output (transformed) points will c be written. These will be stored such that the value of c coordinate number "coord" for output point number "point" c will be found in element "out[coord][point]". f An array into which the coordinates of the output f (transformed) points will be written. These will be stored f such that the value of coordinate number COORD for output f point number POINT will be found in element OUT(POINT,COORD). * The points are ordered such that the first axis of the input * grid changes most rapidly. For example, if the input grid is * 2-dimensional and extends from (2,-1) to (3,1), the output * points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), * (2,1), (3,1). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - If the forward coordinate transformation is being applied, the c Mapping supplied must have the value of "ncoord_in" for its Nin c attribute and the value of "ncoord_out" for its Nout attribute. If c the inverse transformation is being applied, these values should c be reversed. f - If the forward coordinate transformation is being applied, the f Mapping supplied must have the value of NCOORD_IN for its Nin f attribute and the value of NCOORD_OUT for its Nout attribute. If f the inverse transformation is being applied, these values should f be reversed. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Thread-specific data */ AstMapping *simple; /* Pointer to simplified Mapping */ double **out_ptr; /* Pointer to array of output data pointers */ int coord; /* Loop counter for coordinates */ int idim; /* Loop counter for coordinate dimensions */ int npoint; /* Number of points in the grid */ int64_t mpix; /* Number of points for testing */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to a structure holding thread-specific global data values */ astGET_GLOBALS(this); /* Calculate the number of points in the grid, and check that the lower and upper bounds of the input grid are consistent. Report an error if any pair is not. */ mpix = 1; for ( idim = 0; idim < ncoord_in; idim++ ) { if ( lbnd[ idim ] > ubnd[ idim ] ) { astError( AST__GBDIN, "astTranGrid(%s): Lower bound of " "input grid (%d) exceeds corresponding upper bound " "(%d).", status, astGetClass( this ), lbnd[ idim ], ubnd[ idim ] ); astError( AST__GBDIN, "Error in input dimension %d.", status, idim + 1 ); break; } else { mpix *= ubnd[ idim ] - lbnd[ idim ] + 1; } } /* Report an error if there are too many pixels in the input. */ npoint = mpix; if ( astOK && npoint != mpix ) { astError( AST__EXSPIX, "astTranGrid(%s): Supplied grid " "contains too many points (%g): must be fewer than %d.", status, astGetClass( this ), (double) mpix, INT_MAX/ncoord_out ); } mpix = outdim*ncoord_out; if ( astOK && (int) mpix != mpix ) { astError( AST__EXSPIX, "astTranGrid(%s): Supplied output array " "contains too many pixels (%g): must be fewer than %d.", status, astGetClass( this ), (double) mpix, INT_MAX ); } /* Validate the mapping and numbers of points/coordinates. */ ValidateMapping( this, forward, npoint, ncoord_in, ncoord_out, "astTranGrid", status ); /* Check that the positional accuracy tolerance supplied is valid and report an error if necessary. */ if ( astOK && ( tol < 0.0 ) ) { astError( AST__PATIN, "astTranGrid(%s): Invalid positional " "accuracy tolerance (%.*g pixel).", status, astGetClass( this ), DBL_DIG, tol ); astError( AST__PATIN, "This value should not be less than zero." , status); } /* Check that the initial scale size in grid points supplied is valid and report an error if necessary. */ if ( astOK && ( maxpix < 0 ) ) { astError( AST__SSPIN, "astTranGrid(%s): Invalid initial scale " "size in grid points (%d).", status, astGetClass( this ), maxpix ); astError( AST__SSPIN, "This value should not be less than zero." , status); } /* Validate the output array dimension argument. */ if ( astOK && ( outdim < npoint ) ) { astError( AST__DIMIN, "astTranGrid(%s): The output array dimension value " "(%d) is invalid.", status, astGetClass( this ), outdim ); astError( AST__DIMIN, "This should not be less than the number of " "grid points being transformed (%d).", status, npoint ); } /* If there are sufficient pixels to make it worthwhile, simplify the Mapping supplied to improve performance. Otherwise, just clone the Mapping pointer. Note we save a pointer to the original Mapping so that lower-level functions can use it if they need to report an error. */ simple = NULL; unsimplified_mapping = this; if ( astOK ) { if ( npoint > 1024 ) { simple = astSimplify( this ); /* Report an error if the required transformation of this simplified Mapping is not defined. */ if( astOK ) { if ( forward && !astGetTranForward( simple ) ) { astError( AST__TRNND, "astTranGrid(%s): A forward coordinate " "transformation is not defined by the %s supplied.", status, astGetClass( unsimplified_mapping ), astGetClass( unsimplified_mapping ) ); } else if ( !forward && !astGetTranInverse( simple ) ) { astError( AST__TRNND, "astTranGrid(%s): An inverse coordinate " "transformation is not defined by the %s supplied.", status, astGetClass( unsimplified_mapping ), astGetClass( unsimplified_mapping ) ); } } } else { simple = astClone( this ); } /* Allocate memory to hold the array of output data pointers. */ out_ptr = astMalloc( sizeof( double * ) * (size_t) ncoord_out ); /* Initialise the output data pointers to point into the "out" array. */ if ( astOK ) { for ( coord = 0; coord < ncoord_out; coord++ ) { out_ptr[ coord ] = out + coord * outdim; } /* If required, temporarily invert the Mapping. */ if( !forward ) astInvert( simple ); /* Perform the transformation. */ TranGridAdaptively( simple, ncoord_in, lbnd, ubnd, lbnd, ubnd, tol, maxpix, ncoord_out, out_ptr, status ); /* If required, uninvert the Mapping. */ if( !forward ) astInvert( simple ); } /* Free the memory used for the data pointers. */ out_ptr = astFree( out_ptr ); /* Annul the pointer to the simplified/cloned Mapping. */ simple = astAnnul( simple ); } } static void TranGridAdaptively( AstMapping *this, int ncoord_in, const int *lbnd_in, const int *ubnd_in, const int lbnd[], const int ubnd[], double tol, int maxpix, int ncoord_out, double *out[], int *status ){ /* * Name: * TranGridAdaptively * Purpose: * Transform grid positions adaptively. * Type: * Private function. * Synopsis: * #include "mapping.h" * void TranGridAdaptively( AstMapping *this, int ncoord_in, * const int *lbnd_in, const int *ubnd_in, * const int lbnd[], const int ubnd[], * double tol, int maxpix, int ncoord_out, * double *out[] ) * Class Membership: * Mapping member function. * Description: * This function transforms grid points within a specified section of a * rectangular grid (with any number of dimensions) using the forward * transformation of the specified Mapping. * * This function is very similar to TranGridWithBlocking and TranGridSection * which lie below it in the calling hierarchy. However, this function * also attempts to adapt to the Mapping supplied and to sub-divide the * section being transformed into smaller sections within which a linear * approximation to the Mapping may be used. This reduces the number of * Mapping evaluations, thereby improving efficiency particularly when * complicated Mappings are involved. * Parameters: * this * Pointer to the Mapping to be applied. The forward transformation * is used. * ncoord_in * The number of coordinates being supplied for each box corner * (i.e. the number of dimensions of the space in which the * input points reside). * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the whole input grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * lbnd * Pointer to an array of integers, with "ncoord_in" elements, * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. * ubnd * Pointer to an array of integers, with "ncoord_in" elements, * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * * Note that "lbnd" and "ubnd" together define the shape * and size of the input grid, its extent along a particular * (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the * index "j" to be zero-based). They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. * tol * The maximum tolerable geometrical distortion which may be * introduced as a result of approximating non-linear Mappings * by a set of piece-wise linear transformations. This should be * expressed as a displacement in pixels in the output grid's * coordinate system. * * If piece-wise linear approximation is not required, a value * of zero may be given. This will ensure that the Mapping is * used without any approximation, but may increase execution * time. * * If the value is too high, discontinuities between the linear * approximations used in adjacent panel will be higher. If this * is a problem, reduce the tolerance value used. * maxpix * A value which specifies an initial scale size (in grid points) * for the adaptive algorithm which approximates non-linear Mappings * with piece-wise linear transformations. Normally, this should * be a large value (larger than any dimension of the region of * the input grid being used). In this case, a first attempt to * approximate the Mapping by a linear transformation will be * made over the entire input region. * * If a smaller value is used, the input region will first be * divided into sub-regions whose size does not exceed "maxpix" * grid points in any dimension. Only at this point will attempts * at approximation commence. * * This value may occasionally be useful in preventing false * convergence of the adaptive algorithm in cases where the * Mapping appears approximately linear on large scales, but has * irregularities (e.g. holes) on smaller scales. A value of, * say, 50 to 100 grid points can also be employed as a safeguard * in general-purpose software, since the effect on performance is * minimal. * * If too small a value is given, it will have the effect of * inhibiting linear approximation altogether (equivalent to * setting "tol" to zero). Although this may degrade * performance, accurate results will still be obtained. * ncoord_out * The number of dimensions of the space in which the output points * reside. * out * Pointer to an array with "ndim_out" elements. Element [i] of * this array is a pointer to an array in which to store the * transformed values for output axis "i". The points are ordered * such that the first axis of the input grid changes most rapidly. * For example, if the input grid is 2-dimensional and extends from * (2,-1) to (3,1), the output points will be stored in the order * (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). */ /* Local Variables: */ double *flbnd; /* Array holding floating point lower bounds */ double *fubnd; /* Array holding floating point upper bounds */ double *linear_fit; /* Pointer to array of fit coefficients */ int *hi; /* Pointer to array of section upper bounds */ int *lo; /* Pointer to array of section lower bounds */ int coord_in; /* Loop counter for input coordinates */ int dim; /* Output section dimension size */ int dimx; /* Dimension with maximum section extent */ int divide; /* Sub-divide the output section? */ int i; /* Loop count */ int isLinear; /* Is the transformation linear? */ int mxdim; /* Largest output section dimension size */ int npix; /* Number of pixels in output section */ int npoint; /* Number of points for obtaining a fit */ int nvertex; /* Number of vertices of output section */ int toobig; /* Section too big (must sub-divide)? */ int toosmall; /* Section too small to sub-divide? */ /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ npix = 1; mxdim = 0; dimx = 1; nvertex = 1; /* Loop through the input grid dimensions. */ for ( coord_in = 0; coord_in < ncoord_in; coord_in++ ) { /* Obtain the extent in each dimension of the input section which is to be rebinned, and calculate the total number of pixels it contains. */ dim = ubnd[ coord_in ] - lbnd[ coord_in ] + 1; npix *= dim; /* Find the maximum dimension size of this input section and note which dimension has this size. */ if ( dim > mxdim ) { mxdim = dim; dimx = coord_in; } /* Calculate how many vertices the output section has. */ nvertex *= 2; } /* Calculate how many sample points will be needed (by the astLinearApprox function) to obtain a linear fit to the Mapping's forward transformation. */ npoint = 1 + 4 * ncoord_in + 2 * nvertex; /* If the number of pixels in the input section is not at least 4 times this number, we will probably not save significant time by attempting to obtain a linear fit, so note that the input section is too small. */ toosmall = ( npix < ( 4 * npoint ) ); /* Note if the maximum dimension of the input section exceeds the user-supplied scale factor. */ toobig = ( maxpix < mxdim ); /* Assume the Mapping is significantly non-linear before deciding whether to sub-divide the output section. */ linear_fit = NULL; /* If the output section is too small to be worth obtaining a linear fit, or if the accuracy tolerance is zero, we will not sub-divide. This means that the Mapping will be used to transform each pixel's coordinates and no linear approximation will be used. */ if ( toosmall || ( tol == 0.0 ) ) { divide = 0; /* Otherwise, if the largest input section dimension exceeds the scale length given, we will sub-divide. This offers the possibility of obtaining a linear approximation to the Mapping over a reduced range of input coordinates (which will be handled by a recursive invocation of this function). */ } else if ( toobig ) { divide = 1; /* If neither of the above apply, then attempt to fit a linear approximation to the forward transformation of the Mapping over the range of coordinates covered by the input section. We need to temporarily copy the integer bounds into floating point arrays to use astLinearApprox. */ } else { /* Allocate memory for floating point bounds and for the coefficient array */ flbnd = astMalloc( sizeof( double )*(size_t) ncoord_in ); fubnd = astMalloc( sizeof( double )*(size_t) ncoord_in ); linear_fit = astMalloc( sizeof( double )* (size_t) ( ncoord_out*( ncoord_in + 1 ) ) ); if( astOK ) { /* Copy the bounds into these arrays, and change them so that they refer to the lower and upper edges of the cell rather than the centre. This is essential if one of the axes is spanned by a single cell, since otherwise the upper and lower bounds would be identical. */ for( i = 0; i < ncoord_in; i++ ) { flbnd[ i ] = (double) lbnd[ i ] - 0.5; fubnd[ i ] = (double) ubnd[ i ] + 0.5; } /* Get the linear approximation to the forward transformation. */ isLinear = astLinearApprox( this, flbnd, fubnd, tol, linear_fit ); /* Free the coeff array if the inverse transformation is not linear. */ if( !isLinear ) linear_fit = astFree( linear_fit ); } else { linear_fit = astFree( linear_fit ); } /* Free resources */ flbnd = astFree( flbnd ); fubnd = astFree( fubnd ); /* If a linear fit was obtained, we will use it and therefore do not wish to sub-divide further. Otherwise, we sub-divide in the hope that this may result in a linear fit next time. */ divide = !linear_fit; } /* If no sub-division is required, perform the transformation (in a memory-efficient manner, since the section we are rebinning might still be very large). This will use the linear fit, if obtained above. */ if ( astOK ) { if ( !divide ) { TranGridWithBlocking( this, linear_fit, ncoord_in, lbnd_in, ubnd_in, lbnd, ubnd, ncoord_out, out, status ); /* Otherwise, allocate workspace to perform the sub-division. */ } else { lo = astMalloc( sizeof( int ) * (size_t) ncoord_in ); hi = astMalloc( sizeof( int ) * (size_t) ncoord_in ); if ( astOK ) { /* Initialise the bounds of a new input section to match the original input section. */ for ( coord_in = 0; coord_in < ncoord_in; coord_in++ ) { lo[ coord_in ] = lbnd[ coord_in ]; hi[ coord_in ] = ubnd[ coord_in ]; } /* Replace the upper bound of the section's largest dimension with the mid-point of the section along this dimension, rounded downwards. */ hi[ dimx ] = (int) floor( 0.5 * (double) ( lbnd[ dimx ] + ubnd[ dimx ] ) ); /* Rebin the resulting smaller section using a recursive invocation of this function. */ TranGridAdaptively( this, ncoord_in, lbnd_in, ubnd_in, lo, hi, tol, maxpix, ncoord_out, out, status ); /* Now set up a second section which covers the remaining half of the original input section. */ lo[ dimx ] = hi[ dimx ] + 1; hi[ dimx ] = ubnd[ dimx ]; /* If this section contains pixels, transform it in the same way. */ if ( lo[ dimx ] <= hi[ dimx ] ) { TranGridAdaptively( this, ncoord_in, lbnd_in, ubnd_in, lo, hi, tol, maxpix, ncoord_out, out, status ); } } /* Free the workspace. */ lo = astFree( lo ); hi = astFree( hi ); } } /* If coefficients for a linear fit were obtained, then free the space they occupy. */ if ( linear_fit ) linear_fit = astFree( linear_fit ); } static void TranGridSection( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const int *lbnd, const int *ubnd, int ndim_out, double *out[], int *status ){ /* * Name: * TranGridSection * Purpose: * Transform grid points within a section of a rectangular grid. * Type: * Private function. * Synopsis: * #include "mapping.h" * void TranGridSection( AstMapping *this, const double *linear_fit, * int ndim_in, const int *lbnd_in, * const int *ubnd_in, const int *lbnd, * const int *ubnd, int ndim_out, double *out[] ) * Class Membership: * Mapping member function. * Description: * This function transforms grid points within a specified section of a * rectangular grid (with any number of dimensions) using a specified * Mapping or, alternatively, a linear approximation fitted to the * Mapping's forward transformation. * Parameters: * this * Pointer to a Mapping, whose forward transformation may be * used to transform the coordinates of points in the input * grid. * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's forward coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * forward transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input data grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input data grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the input data grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * lbnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the first pixel in the * section of the input data grid which is to be rebinned. * ubnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the last pixel in the * section of the input data grid which is to be rebinned. * * Note that "lbnd" and "ubnd" define the shape and position of * the section of the input grid which is to be rebinned. This section * should lie wholly within the extent of the input grid (as defined * by the "lbnd_out" and "ubnd_out" arrays). Regions of the input * grid lying outside this section will be ignored. * ndim_out * The number of dimensions in the output grid. This should be * at least one. * out * Pointer to an array with "ndim_out" elements. Element [i] of * this array is a pointer to an array in which to store the * transformed values for output axis "i". The points are ordered * such that the first axis of the input grid changes most rapidly. * For example, if the input grid is 2-dimensional and extends from * (2,-1) to (3,1), the output points will be stored in the order * (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). * Notes: * - This function does not take steps to limit memory usage if the * grids supplied are large. To resample large grids in a more * memory-efficient way, the ResampleWithBlocking function should * be used. */ /* Local Variables: */ AstPointSet *pset_in; /* Input PointSet for transformation */ AstPointSet *pset_out; /* Output PointSet for transformation */ const double *grad; /* Pointer to gradient matrix of linear fit */ const double *zero; /* Pointer to zero point array of fit */ double **ptr_in; /* Pointer to input PointSet coordinates */ double **ptr_out; /* Pointer to output PointSet coordinates */ double *accum; /* Pointer to array of accumulated sums */ double x1; /* Interim x coordinate value */ double xx1; /* Initial x coordinate value */ double y1; /* Interim y coordinate value */ double yy1; /* Initial y coordinate value */ int *dim; /* Pointer to array of output pixel indices */ int *offset; /* Pointer to array of output pixel offsets */ int *stride; /* Pointer to array of output grid strides */ int coord_in; /* Loop counter for input dimensions */ int coord_out; /* Loop counter for output dimensions */ int done; /* All pixel indices done? */ int i1; /* Interim offset into "accum" array */ int i2; /* Final offset into "accum" array */ int idim; /* Loop counter for dimensions */ int ix; /* Loop counter for output x coordinate */ int iy; /* Loop counter for output y coordinate */ int npoint; /* Number of output points (pixels) */ int off1; /* Interim pixel offset into output array */ int off2; /* Interim pixel offset into output array */ int off; /* Final pixel offset into output array */ int point; /* Counter for output points (pixels ) */ int s; /* Temporary variable for strides */ /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ pset_in = NULL; ptr_in = NULL; ptr_out = NULL; pset_out = NULL; /* Calculate the number of input points, as given by the product of the input grid dimensions. */ for ( npoint = 1, coord_in = 0; coord_in < ndim_in; coord_in++ ) { npoint *= ubnd[ coord_in ] - lbnd[ coord_in ] + 1; } /* Allocate workspace. */ offset = astMalloc( sizeof( int ) * (size_t) npoint ); stride = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Calculate the stride for each input grid dimension. */ off = 0; s = 1; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { stride[ coord_in ] = s; s *= ubnd_in[ coord_in ] - lbnd_in[ coord_in ] + 1; } /* A linear fit to the Mapping is available. */ /* ========================================= */ if ( linear_fit ) { /* If a linear fit to the Mapping has been provided, then obtain pointers to the array of gradients and zero-points comprising the fit. */ grad = linear_fit + ndim_out; zero = linear_fit; /* Create a PointSet to hold the output grid coordinates and obtain an array of pointers to its coordinate data. */ pset_out = astPointSet( npoint, ndim_out, "", status ); ptr_out = astGetPoints( pset_out ); if ( astOK ) { /* Initialise the count of input points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ( ndim_in == 1 ) && ( ndim_out == 1 ) ) { /* Loop through the pixels of the input grid and transform their x coordinates into the output grid's coordinate system using the linear fit supplied. Store the results in the PointSet created above. */ off = lbnd[ 0 ] - lbnd_in[ 0 ]; xx1 = zero[ 0 ] + grad[ 0 ] * (double) lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = xx1; xx1 += grad[ 0 ]; offset[ point++ ] = off++; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ( ndim_in == 2 ) && ( ndim_out == 2 ) ) { /* Loop through the range of y coordinates in the input grid and calculate interim values of the output coordinates using the linear fit supplied. */ x1 = zero[ 0 ] + grad[ 1 ] * (double) ( lbnd[ 1 ] - 1 ); y1 = zero[ 1 ] + grad[ 3 ] * (double) ( lbnd[ 1 ] - 1 ); off1 = stride[ 1 ] * ( lbnd[ 1 ] - lbnd_in[ 1 ] - 1 ) - lbnd_in[ 0 ]; for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { x1 += grad[ 1 ]; y1 += grad[ 3 ]; /* Also calculate an interim pixel offset into the input array. */ off1 += stride[ 1 ]; /* Now loop through the range of input x coordinates and calculate the final values of the input coordinates, storing the results in the PointSet created above. */ xx1 = x1 + grad[ 0 ] * (double) lbnd[ 0 ]; yy1 = y1 + grad[ 2 ] * (double) lbnd[ 0 ]; off = off1 + lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_out[ 0 ][ point ] = xx1; xx1 += grad[ 0 ]; ptr_out[ 1 ][ point ] = yy1; yy1 += grad[ 2 ]; /* Also calculate final pixel offsets into the input array. */ offset[ point++ ] = off++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ accum = astMalloc( sizeof( double ) * (size_t) ( ndim_in * ndim_out ) ); dim = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Initialise an array of pixel indices for the input grid which refer to the first pixel which we will rebin. Also calculate the offset of this pixel within the input array. */ off = 0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { dim[ coord_in ] = lbnd[ coord_in ]; off += stride[ coord_in ] * ( dim[ coord_in ] - lbnd_in[ coord_in ] ); } /* To calculate each output grid coordinate we must perform a matrix multiply on the input grid coordinates (using the gradient matrix) and then add the zero points. However, since we will usually only be altering one input coordinate at a time (the least significant), we can avoid the full matrix multiply by accumulating partial sums for the most significant input coordinates and only altering those sums which need to change each time. The zero points never change, so we first fill the "most significant" end of the "accum" array with these. */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { accum[ ( coord_out + 1 ) * ndim_in - 1 ] = zero[ coord_out ]; } coord_in = ndim_in - 1; /* Now loop to process each input pixel. */ for ( done = 0; !done; point++ ) { /* To generate the output coordinate that corresponds to the current input pixel, we work down from the most significant dimension whose index has changed since the previous pixel we considered (given by "coord_in"). For each affected dimension, we accumulate in "accum" the matrix sum (including the zero point) for that dimension and all higher input dimensions. We must accumulate a separate set of sums for each output coordinate we wish to produce. (Note that for the first pixel we process, all dimensions are considered "changed", so we start by initialising the whole "accum" array.) */ for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { i1 = coord_out * ndim_in; for ( idim = coord_in; idim >= 1; idim-- ) { i2 = i1 + idim; accum[ i2 - 1 ] = accum[ i2 ] + dim[ idim ] * grad[ i2 ]; } /* The output coordinate for each dimension is given by the accumulated sum for input dimension zero (giving the sum over all input dimensions). We do not store this in the "accum" array, but assign the result directly to the coordinate array of the PointSet created earlier. */ ptr_out[ coord_out ][ point ] = accum[ i1 ] + dim[ 0 ] * grad[ i1 ]; } /* Store the offset of the current pixel in the input array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next input pixel. */ coord_in = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the input array is updated accordingly. */ if ( dim[ coord_in ] < ubnd[ coord_in ] ) { dim[ coord_in ]++; off += stride[ coord_in ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the input pixel offset is decremented appropriately. */ } else { dim[ coord_in ] = lbnd[ coord_in ]; off -= stride[ coord_in ] * ( ubnd[ coord_in ] - lbnd[ coord_in ] ); /* All the output pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_in == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ accum = astFree( accum ); dim = astFree( dim ); } } /* No linear fit to the Mapping is available. */ /* ========================================== */ } else { /* Create a PointSet to hold the coordinates of the input pixels and obtain a pointer to its coordinate data. */ pset_in = astPointSet( npoint, ndim_in, "", status ); ptr_in = astGetPoints( pset_in ); if ( astOK ) { /* Initialise the count of input points. */ point = 0; /* Handle the 1-dimensional case optimally. */ /* ---------------------------------------- */ if ( ndim_in == 1 && ndim_out == 1 ) { /* Loop through the required range of input x coordinates, assigning the coordinate values to the PointSet created above. Also store a pixel offset into the input array. */ for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = (double) ix; offset[ point++ ] = ix - lbnd_in[ 0 ]; } /* Handle the 2-dimensional case optimally. */ /* ---------------------------------------- */ } else if ( ndim_in == 2 && ndim_out == 2 ) { /* Loop through the required range of input y coordinates, calculating an interim pixel offset into the input array. */ off1 = stride[ 1 ] * ( lbnd[ 1 ] - lbnd_in[ 1 ] - 1 ) - lbnd_in[ 0 ]; for ( iy = lbnd[ 1 ]; iy <= ubnd[ 1 ]; iy++ ) { off1 += stride[ 1 ]; /* Loop through the required range of input x coordinates, assigning the coordinate values to the PointSet created above. Also store a final pixel offset into the input array. */ off2 = off1 + lbnd[ 0 ]; for ( ix = lbnd[ 0 ]; ix <= ubnd[ 0 ]; ix++ ) { ptr_in[ 0 ][ point ] = (double) ix; ptr_in[ 1 ][ point ] = (double) iy; offset[ point++ ] = off2++; } } /* Handle other numbers of dimensions. */ /* ----------------------------------- */ } else { /* Allocate workspace. */ dim = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Initialise an array of pixel indices for the input grid which refer to the first pixel to be rebinned. Also calculate the offset of this pixel within the input array. */ off = 0; for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { dim[ coord_in ] = lbnd[ coord_in ]; off += stride[ coord_in ] * ( dim[ coord_in ] - lbnd_in[ coord_in ] ); } /* Loop to generate the coordinates of each input pixel. */ for ( done = 0; !done; point++ ) { /* Copy each pixel's coordinates into the PointSet created above. */ for ( coord_in = 0; coord_in < ndim_in; coord_in++ ) { ptr_in[ coord_in ][ point ] = (double) dim[ coord_in ]; } /* Store the offset of the pixel in the input array. */ offset[ point ] = off; /* Now update the array of pixel indices to refer to the next input pixel. */ coord_in = 0; do { /* The least significant index which currently has less than its maximum value is incremented by one. The offset into the input array is updated accordingly. */ if ( dim[ coord_in ] < ubnd[ coord_in ] ) { dim[ coord_in ]++; off += stride[ coord_in ]; break; /* Any less significant indices which have reached their maximum value are returned to their minimum value and the input pixel offset is decremented appropriately. */ } else { dim[ coord_in ] = lbnd[ coord_in ]; off -= stride[ coord_in ] * ( ubnd[ coord_in ] - lbnd[ coord_in ] ); /* All the input pixels have been processed once the most significant pixel index has been returned to its minimum value. */ done = ( ++coord_in == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ dim = astFree( dim ); } /* When all the input pixel coordinates have been generated, use the Mapping's forward transformation to generate the output coordinates from them. Obtain an array of pointers to the resulting coordinate data. */ pset_out = astTransform( this, pset_in, 1, NULL ); ptr_out = astGetPoints( pset_out ); } /* Annul the PointSet containing the input coordinates. */ pset_in = astAnnul( pset_in ); } } /* Copy the output coordinates into the correct positions within the supplied "out" array. */ /* ================================================================= */ if( astOK ) { for ( coord_out = 0; coord_out < ndim_out; coord_out++ ) { for ( point = 0; point < npoint; point++ ) { out[ coord_out ][ offset[ point ] ] = ptr_out[ coord_out ][ point ]; } } } /* Annul the PointSet used to hold output coordinates. */ pset_out = astAnnul( pset_out ); /* Free the workspace. */ offset = astFree( offset ); stride = astFree( stride ); } static void TranGridWithBlocking( AstMapping *this, const double *linear_fit, int ndim_in, const int *lbnd_in, const int *ubnd_in, const int *lbnd, const int *ubnd, int ndim_out, double *out[], int *status ){ /* * Name: * TranGridWithBlocking * Purpose: * Transforms positions in a section of a grid in a memory-efficient way. * Type: * Private function. * Synopsis: * #include "mapping.h" * void TranGridWithBlocking( AstMapping *this, const double *linear_fit, * int ndim_in, const int *lbnd_in, * const int *ubnd_in, const int *lbnd, * const int *ubnd, int ndim_out, * double *out[], int *status ) * Class Membership: * Mapping member function. * Description: * This function transforms positions within a specified section of a * rectangular grid (with any number of dimensions) using the forward * transformation of the supplied Mapping. * * This function is very similar to TranGridSection, except that in * order to limit memory usage and to ensure locality of reference, * it divides the input grid up into "blocks" which have a limited * extent along each input dimension. Each block, which will not * contain more than a pre-determined maximum number of pixels, is * then passed to TranGridSection for transformation. * Parameters: * this * Pointer to a Mapping, whose forward transformation may be * used to transform the coordinates of pixels in the input * grid into associated positions in the output grid. * * The number of input coordintes for the Mapping (Nin * attribute) should match the value of "ndim_in" (below), and * the number of output coordinates (Nout attribute) should * match the value of "ndim_out". * linear_fit * Pointer to an optional array of double which contains the * coefficients of a linear fit which approximates the above * Mapping's forward coordinate transformation. If this is * supplied, it will be used in preference to the above Mapping * when transforming coordinates. This may be used to enhance * performance in cases where evaluation of the Mapping's * forward transformation is expensive. If no linear fit is * available, a NULL pointer should be supplied. * * The way in which the fit coefficients are stored in this * array and the number of array elements are as defined by the * astLinearApprox function. * ndim_in * The number of dimensions in the input grid. This should be at * least one. * lbnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the first * pixel in the input grid along each dimension. * ubnd_in * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the centre of the last * pixel in the input grid along each dimension. * * Note that "lbnd_in" and "ubnd_in" together define the shape * and size of the whole input grid, its extent along a * particular (i'th) dimension being (ubnd_in[i] - lbnd_in[i] + * 1). They also define the input grid's coordinate system, with * each pixel being of unit extent along each dimension with * integral coordinate values at its centre. * lbnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the first pixel in the * section of the input data grid which is to be transformed. * ubnd * Pointer to an array of integers, with "ndim_in" elements. * This should give the coordinates of the last pixel in the * section of the input data grid which is to be transformed. * * Note that "lbnd" and "ubnd" define the shape and position of the * section of the input grid which is to be transformed. * ndim_out * The number of dimensions in the output grid. This should be * at least one. * out * Pointer to an array with "ndim_out" elements. Element [i] of * this array is a pointer to an array in which to store the * transformed values for output axis "i". The points are ordered * such that the first axis of the input grid changes most rapidly. * For example, if the input grid is 2-dimensional and extends from * (2,-1) to (3,1), the output points will be stored in the order * (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). * status * Pointer to the inherited status variable. */ /* Local Constants: */ const int mxpix = 2 * 1024; /* Maximum number of pixels in a block (this relatively small number seems to give best performance) */ /* Local Variables: */ int *dim_block; /* Pointer to array of block dimensions */ int *lbnd_block; /* Pointer to block lower bound array */ int *ubnd_block; /* Pointer to block upper bound array */ int dim; /* Dimension size */ int done; /* All blocks rebinned? */ int hilim; /* Upper limit on maximum block dimension */ int idim; /* Loop counter for dimensions */ int lolim; /* Lower limit on maximum block dimension */ int mxdim_block; /* Maximum block dimension */ int npix; /* Number of pixels in block */ /* Check the global error status. */ if ( !astOK ) return; /* Allocate workspace. */ lbnd_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); ubnd_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); dim_block = astMalloc( sizeof( int ) * (size_t) ndim_in ); if ( astOK ) { /* Find the optimum block size. */ /* ---------------------------- */ /* We first need to find the maximum extent which a block of input pixels may have in each dimension. We determine this by taking the input grid extent in each dimension and then limiting the maximum dimension size until the resulting number of pixels is sufficiently small. This approach allows the block shape to approximate (or match) the input grid shape when appropriate. */ /* First loop to calculate the total number of input pixels and the maximum input dimension size. */ npix = 1; mxdim_block = 0; for ( idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= dim; if ( mxdim_block < dim ) mxdim_block = dim; } /* If the number of input pixels is too large for a single block, we perform iterations to determine the optimum upper limit on a block's dimension size. Initialise the limits on this result. */ if ( npix > mxpix ) { lolim = 1; hilim = mxdim_block; /* Loop to perform a binary chop, searching for the best result until the lower and upper limits on the result converge to adjacent values. */ while ( ( hilim - lolim ) > 1 ) { /* Form a new estimate from the mid-point of the previous limits. */ mxdim_block = ( hilim + lolim ) / 2; /* See how many pixels a block contains if its maximum dimension is limited to this new value. */ for ( npix = 1, idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; npix *= ( dim < mxdim_block ) ? dim : mxdim_block; } /* Update the appropriate limit, according to whether the number of pixels is too large or too small. */ *( ( npix <= mxpix ) ? &lolim : &hilim ) = mxdim_block; } /* When iterations have converged, obtain the maximum limit on the dimension size of a block which results in no more than the maximum allowed number of pixels per block. However, ensure that all block dimensions are at least 2. */ mxdim_block = lolim; } if ( mxdim_block < 2 ) mxdim_block = 2; /* Calculate the block dimensions by applying this limit to the output grid dimensions. */ for ( idim = 0; idim < ndim_in; idim++ ) { dim = ubnd[ idim ] - lbnd[ idim ] + 1; dim_block[ idim ] = ( dim < mxdim_block ) ? dim : mxdim_block; /* Also initialise the lower and upper bounds of the first block of output grid pixels to be rebinned, ensuring that this does not extend outside the grid itself. */ lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); } /* Transform each block of input grid positions. */ /* --------------------------------------------- */ /* Loop to generate the extent of each block of input grid positions and to transform them. */ done = 0; while ( !done && astOK ) { /* Rebin the current block, accumulating the sum of bad pixels produced. */ TranGridSection( this, linear_fit, ndim_in, lbnd_in, ubnd_in, lbnd_block, ubnd_block, ndim_out, out, status ); /* Update the block extent to identify the next block of input pixels. */ idim = 0; do { /* We find the least significant dimension where the upper bound of the block has not yet reached the upper bound of the region of the input grid which we are rebinning. The block's position is then incremented by one block extent along this dimension, checking that the resulting extent does not go outside the region being rebinned. */ if ( ubnd_block[ idim ] < ubnd[ idim ] ) { lbnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ], ubnd[ idim ], status ); ubnd_block[ idim ] = MinI( lbnd_block[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); break; /* If any less significant dimensions are found where the upper bound of the block has reached its maximum value, we reset the block to its lowest position. */ } else { lbnd_block[ idim ] = lbnd[ idim ]; ubnd_block[ idim ] = MinI( lbnd[ idim ] + dim_block[ idim ] - 1, ubnd[ idim ], status ); /* All the blocks have been processed once the position along the most significant dimension has been reset. */ done = ( ++idim == ndim_in ); } } while ( !done ); } } /* Free the workspace. */ lbnd_block = astFree( lbnd_block ); ubnd_block = astFree( ubnd_block ); dim_block = astFree( dim_block ); } static void TranN( AstMapping *this, int npoint, int ncoord_in, int indim, const double *in, int forward, int ncoord_out, int outdim, double *out, int *status ) { /* *++ * Name: c astTranN f AST_TRANN * Purpose: * Transform N-dimensional coordinates. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astTranN( AstMapping *this, int npoint, c int ncoord_in, int indim, const double *in, c int forward, c int ncoord_out, int outdim, double *out ) f CALL AST_TRANN( THIS, NPOINT, f NCOORD_IN, INDIM, IN, f FORWARD, NCOORD_OUT, OUTDIM, OUT, STATUS ) * Class Membership: * Mapping method. * Description: c This function applies a Mapping to transform the coordinates of f This routine applies a Mapping to transform the coordinates of * a set of points in an arbitrary number of dimensions. It is the * appropriate routine to use if the coordinates are not purely 1- * or 2-dimensional and are stored in a single array (which they * need not fill completely). c c If the coordinates are not stored in a single array, then the c astTranP function might be more suitable. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be applied. c npoint f NPOINT = INTEGER (Given) * The number of points to be transformed. c ncoord_in f NCOORD_IN = INTEGER (Given) * The number of coordinates being supplied for each input point * (i.e. the number of dimensions of the space in which the * input points reside). c indim f INDIM = INTEGER (Given) c The number of elements along the second dimension of the "in" f The number of elements along the first dimension of the IN * array (which contains the input coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value c given should not be less than "npoint". f given should not be less than NPOINT. c in f IN( INDIM, NCOORD_IN ) = DOUBLE PRECISION (Given) c The address of the first element in a 2-dimensional array of c shape "[ncoord_in][indim]", c containing the coordinates of the input (untransformed) c points. These should be stored such that the value of c coordinate number "coord" for input point number "point" is c found in element "in[coord][point]". f An array containing the coordinates of the input f (untransformed) points. These should be stored such that the f value of coordinate number COORD for input point number POINT f is found in element IN(POINT,COORD). c forward f FORWARD = LOGICAL (Given) c A non-zero value indicates that the Mapping's forward c coordinate transformation is to be applied, while a zero c value indicates that the inverse transformation should be c used. f A .TRUE. value indicates that the Mapping's forward f coordinate transformation is to be applied, while a .FALSE. f value indicates that the inverse transformation should be f used. c ncoord_out f NCOORD_OUT = INTEGER (Given) * The number of coordinates being generated by the Mapping for * each output point (i.e. the number of dimensions of the * space in which the output points reside). This need not be c the same as "ncoord_in". f the same as NCOORD_IN. c outdim f OUTDIM = INTEGER (Given) c The number of elements along the second dimension of the "out" f The number of elements along the first dimension of the OUT * array (which will contain the output coordinates). This value * is required so that the coordinate values can be correctly * located if they will not entirely fill this array. The value c given should not be less than "npoint". f given should not be less than NPOINT. c out f OUT( OUTDIM, NCOORD_OUT ) = DOUBLE PRECISION (Returned) c The address of the first element in a 2-dimensional array of c shape "[ncoord_out][outdim]", into c which the coordinates of the output (transformed) points will c be written. These will be stored such that the value of c coordinate number "coord" for output point number "point" c will be found in element "out[coord][point]". f An array into which the coordinates of the output f (transformed) points will be written. These will be stored f such that the value of coordinate number COORD for output f point number POINT will be found in element OUT(POINT,COORD). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - If the forward coordinate transformation is being applied, the c Mapping supplied must have the value of "ncoord_in" for its Nin c attribute and the value of "ncoord_out" for its Nout attribute. If c the inverse transformation is being applied, these values should c be reversed. f - If the forward coordinate transformation is being applied, the f Mapping supplied must have the value of NCOORD_IN for its Nin f attribute and the value of NCOORD_OUT for its Nout attribute. If f the inverse transformation is being applied, these values should f be reversed. *-- */ /* Local Variables: */ AstPointSet *in_points; /* Pointer to input PointSet */ AstPointSet *out_points; /* Pointer to output PointSet */ const double **in_ptr; /* Pointer to array of input data pointers */ double **out_ptr; /* Pointer to array of output data pointers */ int coord; /* Loop counter for coordinates */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the mapping and numbers of points/coordinates. */ ValidateMapping( this, forward, npoint, ncoord_in, ncoord_out, "astTranN", status ); /* Also validate the input array dimension argument. */ if ( astOK && ( indim < npoint ) ) { astError( AST__DIMIN, "astTranN(%s): The input array dimension value " "(%d) is invalid.", status, astGetClass( this ), indim ); astError( AST__DIMIN, "This should not be less than the number of " "points being transformed (%d).", status, npoint ); } /* Similarly, validate the output array dimension argument. */ if ( astOK && ( outdim < npoint ) ) { astError( AST__DIMIN, "astTranN(%s): The output array dimension value " "(%d) is invalid.", status, astGetClass( this ), outdim ); astError( AST__DIMIN, "This should not be less than the number of " "points being transformed (%d).", status, npoint ); } /* Allocate memory to hold the arrays of input and output data pointers. */ if ( astOK ) { in_ptr = (const double **) astMalloc( sizeof( const double * ) * (size_t) ncoord_in ); out_ptr = astMalloc( sizeof( double * ) * (size_t) ncoord_out ); #ifdef DEBUG { int i, ns; ns = ncoord_out*outdim; for( i = 0; i < ns; i++ ) out[ i ] = 0.0; } #endif /* Initialise the input data pointers to locate the coordinate data in the "in" array. */ if ( astOK ) { for ( coord = 0; coord < ncoord_in; coord++ ) { in_ptr[ coord ] = in + coord * indim; } /* Similarly initialise the output data pointers to point into the "out" array. */ for ( coord = 0; coord < ncoord_out; coord++ ) { out_ptr[ coord ] = out + coord * outdim; } /* Create PointSets to describe the input and output points. */ in_points = astPointSet( npoint, ncoord_in, "", status ); out_points = astPointSet( npoint, ncoord_out, "", status ); /* Associate the data pointers with the PointSets (note we must explicitly remove the "const" qualifier from the input data here, although they will not be modified). */ astSetPoints( in_points, (double **) in_ptr ); astSetPoints( out_points, out_ptr ); /* Apply the required transformation to the coordinates. */ (void) astTransform( this, in_points, forward, out_points ); /* If the Mapping's Report attribute is set, report the effect the Mapping has had on the coordinates. */ if ( astGetReport( this ) ) astReportPoints( this, forward, in_points, out_points ); /* Delete the two PointSets. */ in_points = astDelete( in_points ); out_points = astDelete( out_points ); } /* Free the memory used for the data pointers. */ in_ptr = (const double **) astFree( (void *) in_ptr ); out_ptr = astFree( out_ptr ); } } static void TranP( AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[], int *status ) { /* c++ * Name: * astTranP * Purpose: * Transform N-dimensional coordinates held in separate arrays. * Type: * Public virtual function. * Synopsis: * #include "mapping.h" * void astTranP( AstMapping *this, int npoint, * int ncoord_in, const double *ptr_in[], * int forward, int ncoord_out, double *ptr_out[] ) * Class Membership: * Mapping method. * Description: * This function applies a Mapping to transform the coordinates of * a set of points in an arbitrary number of dimensions. It is the * appropriate routine to use if the coordinates are not purely 1- * or 2-dimensional and are stored in separate arrays, since each * coordinate array is located by supplying a separate pointer to * it. * * If the coordinates are stored in a single (2-dimensional) array, * then the astTranN function might be more suitable. * Parameters: * this * Pointer to the Mapping to be applied. * npoint * The number of points to be transformed. * ncoord_in * The number of coordinates being supplied for each input point * (i.e. the number of dimensions of the space in which the * input points reside). * ptr_in * An array of pointers to double, with "ncoord_in" * elements. Element "ptr_in[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contain the values of coordinate number "coord" for each * input (untransformed) point. The value of coordinate number * "coord" for input point number "point" is therefore given by * "ptr_in[coord][point]" (assuming both indices are * zero-based). * forward * A non-zero value indicates that the Mapping's forward * coordinate transformation is to be applied, while a zero * value indicates that the inverse transformation should be * used. * ncoord_out * The number of coordinates being generated by the Mapping for * each output point (i.e. the number of dimensions of the space * in which the output points reside). This need not be the same * as "ncoord_in". * ptr_out * An array of pointers to double, with "ncoord_out" * elements. Element "ptr_out[coord]" should point at the first * element of an array of double (with "npoint" elements) into * which the values of coordinate number "coord" for each output * (transformed) point will be written. The value of coordinate * number "coord" for output point number "point" will therefore * be found in "ptr_out[coord][point]". * Notes: * - If the forward coordinate transformation is being applied, the * Mapping supplied must have the value of "ncoord_in" for its Nin * attribute and the value of "ncoord_out" for its Nout * attribute. If the inverse transformation is being applied, these * values should be reversed. * - This routine is not available in the Fortran 77 interface to * the AST library. c-- */ /* Local Variables: */ AstPointSet *in_points; /* Pointer to input PointSet */ AstPointSet *out_points; /* Pointer to output PointSet */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the Mapping and number of points/coordinates. */ ValidateMapping( this, forward, npoint, ncoord_in, ncoord_out, "astTranP", status ); /* Create PointSets to describe the input and output points. */ if ( astOK ) { in_points = astPointSet( npoint, ncoord_in, "", status ); out_points = astPointSet( npoint, ncoord_out, "", status ); /* Associate the data pointers with the PointSets (note we must explicitly remove the "const" qualifier from the input data here, although they will not be modified). */ astSetPoints( in_points, (double **) ptr_in ); astSetPoints( out_points, ptr_out ); /* Apply the required transformation to the coordinates. */ (void) astTransform( this, in_points, forward, out_points ); /* If the Mapping's Report attribute is set, report the effect the Mapping has had on the coordinates. */ if ( astGetReport( this ) ) astReportPoints( this, forward, in_points, out_points ); /* Delete the two PointSets. */ in_points = astDelete( in_points ); out_points = astDelete( out_points ); } } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* *+ * Name: * astTransform * Purpose: * Transform a set of points. * Type: * Protected virtual function. * Synopsis: * #include "mapping.h" * AstPointSet *astTransform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out ) * Class Membership: * Mapping method. * Description: * This function takes a Mapping and a set of points encapsulated * in a PointSet, and applies either the forward or inverse * coordinate transformation (if defined by the Mapping) to the * points. * Parameters: * this * Pointer to the Mapping. The nature of the coordinate * transformation will depend on the class of Mapping * supplied. Note that there is no constructor for the Mapping * class itself, so this object should be from a derived class. * in * Pointer to the PointSet holding the input coordinate data. * forward * A non-zero value indicates that the forward coordinate * transformation should be applied, while a zero value requests * the inverse transformation. * out * Pointer to a PointSet which will hold the transformed * (output) coordinate values. A NULL value may also be given, * in which case a new PointSet will be created by this * function. * Returned Value: * Pointer to the output (possibly new) PointSet. * Notes: * - An error will result if the Mapping 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 * Mapping being applied (or number of output coordinates if the * inverse transformation is requested). * - 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 Mapping 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: */ AstPointSet *result; /* Pointer to output PointSet */ int def; /* Coordinate transformation defined? */ int ncoord_in; /* Number of input PointSet coordinates */ int ncoord_out; /* Number of coordinates in output PointSet */ int nin; /* Number of input Mapping coordinates */ int nout; /* Number of output Mapping coordinates */ int npoint; /* Number of points to transform */ int npoint_out; /* Number of points in output PointSet */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise. */ result = NULL; /* Determine if a coordinate transformation is defined for the requested direction. */ def = forward ? astGetTranForward( this ) : astGetTranInverse( this ); /* Report an error if the transformation is not defined. */ if ( astOK && !def ) { astError( AST__TRNND, "astTransform(%s): %s coordinate transformation " "is not defined by the %s supplied.", status, astGetClass( this ), forward ? "A forward" : "An inverse", astGetClass( this ) ); } /* Obtain the effective number of input and output coordinate values for the transformation to be performed, taking account of the transformation direction required. Note we use Mapping methods to obtain these values, as this will take account of whether the Mapping has been inverted. */ nin = forward ? astGetNin( this ) : astGetNout( this ); nout = forward ? astGetNout( this ) : astGetNin( this ); /* Obtain the number of input points to transform and the number of coordinate values per input point. */ npoint = astGetNpoint( in ); ncoord_in = astGetNcoord( in ); /* If OK, check that the number of input coordinates matches the number required by the mapping. Report an error if these numbers do not match. */ if ( astOK && ( ncoord_in != nin ) ) { astError( AST__NCPIN, "astTransform(%s): Bad number of coordinate " "values (%d) in input %s.", status, astGetClass( this ), ncoord_in, astGetClass( in ) ); astError( AST__NCPIN, "The %s given requires %d coordinate value(s) for " "each input point.", status, astGetClass( this ), nin ); } /* If still OK, and a non-NULL pointer has been given for the output PointSet, then obtain the number of points and number of coordinates per point for this PointSet. */ if ( astOK && out ) { npoint_out = astGetNpoint( out ); ncoord_out = astGetNcoord( out ); /* Check that the dimensions of this PointSet are adequate to accommodate the output coordinate values and report an error if they are not. */ if ( astOK ) { if ( npoint_out < npoint ) { astError( AST__NOPTS, "astTransform(%s): Too few points (%d) in " "output %s.", status, astGetClass( this ), npoint_out, astGetClass( out ) ); astError( AST__NOPTS, "The %s needs space to hold %d transformed " "point(s).", status, astGetClass( this ), npoint ); } else if ( ncoord_out < nout ) { astError( AST__NOCTS, "astTransform(%s): Too few coordinate " "values per point (%d) in output %s.", status, astGetClass( this ), ncoord_out, astGetClass( out ) ); astError( AST__NOCTS, "The %s supplied needs space to store %d " "coordinate value(s) per transformed point.", status, astGetClass( this ), nout ); } } } /* If all the validation stages are passed successfully, and a NULL output pointer was given, then create a new PointSet to encapsulate the output coordinate data. */ if ( astOK ) { if ( !out ) { result = astPointSet( npoint, nout, "", status ); /* Otherwise, use the PointSet supplied. */ } else { result = out; } } /* Return a pointer to the output PointSet. Note that we do not actually transform (or even copy) the coordinates. This is left for derived classes to implement. */ return result; } /* *++ * Name: c astUinterp f AST_UINTERP * Purpose: * Perform sub-pixel interpolation on a grid of data. * Type: * Fictitious function. * Synopsis: c #include "mapping.h" c void astUinterp( int ndim_in, const int lbnd_in[], const int ubnd_in[], c const in[], const in_var[], c int npoint, const int offset[], c const double *const coords[], const double params[], c int flags, badval, c out[], out_var[], int *nbad ) f CALL AST_UINTERP( NDIM_IN, LBND_IN, UBND_IN, IN, IN_VAR, f NPOINT, OFFSET, COORDS, PARAMS, FLAGS, BADVAL, f OUT, OUT_VAR, NBAD, STATUS ) * Class Membership: * Mapping member function. * Description: c This is a fictitious function which does not actually c exist. Instead, this description constitutes a template so that c you may implement a function with this interface for yourself c (and give it any name you wish). A pointer to such a function c may be passed via the "finterp" parameter of the astResample c functions (q.v.) in order to perform sub-pixel interpolation c during resampling of gridded data (you must also set the c "interp" parameter of astResample to the value c AST__UINTERP). This allows you to use your own interpolation c algorithm in addition to those which are pre-defined. f This is a fictitious routine which does not actually f exist. Instead, this description constitutes a template so that f you may implement a routine with this interface for yourself f (and give it any name you wish). Such a routine f may be passed via the FINTERP argument of the AST_RESAMPLE f functions (q.v.) in order to perform sub-pixel interpolation f during resampling of gridded data (you must also set the f INTERP argument of AST_RESAMPLE to the value f AST__UINTERP). This allows you to use your own interpolation f algorithm in addition to those which are pre-defined. * c The function interpolates an input grid of data (and, f The routine interpolates an input grid of data (and, * optionally, processes associated statistical variance estimates) * at a specified set of points. * Parameters: c ndim_in f NDIM_IN = INTEGER (Given) * The number of dimensions in the input grid. This will be at * least one. c lbnd_in f LBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c ubnd_in f UBND_IN( NDIM_IN ) = INTEGER (Given) c Pointer to an array of integers, with "ndim_in" elements, f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd_in" and "ubnd_in" together define the shape, f Note that LBND_IN and UBND_IN together define the shape, * size and coordinate system of the input grid in the same c way as they do in astResample. f way as they do in AST_RESAMPLE. c in f IN( * ) = (Given) c Pointer to an array, with one element for each pixel in the f An array, with one element for each pixel in the * input grid, containing the input data. This will be the same c array as was passed to astResample via the "in" parameter. f array as was passed to AST_RESAMPLE via the IN argument. * The numerical type of this array should match that of the * data being processed. c in_var f IN_VAR( * ) = (Given) c Pointer to an optional second array with the same size and c type as the "in" array. If given, this will contain the set c of variance values associated with the input data and will be c the same array as was passed to astResample via the c "in_var" parameter. f An optional second array with the same size and type as the f IN array. This will only be given if the AST__USEVAR flag is f set via the FLAGS argument (below). If given, it will contain f the set of variance values associated with the input data and f will be the same array as was passed to AST_RESAMPLE via f the IN_VAR argument. * c If no variance values are being processed, this will be a c NULL pointer. f If the AST__USEVAR flag is not set, then no variance values f are being processed. In this case, this array of variance f values may be a dummy (e.g. one-element) array and should not f be used. c npoint f NPOINT = INTEGER (Given) * The number of points at which the input grid is to be * interpolated. This will be at least one. c offset f OFFSET( NPOINT ) = INTEGER (Given) c Pointer to an array of integers with "npoint" elements. For c each interpolation point, this will contain the zero-based c index in the "out" (and "out_var") array(s) at which the c interpolated value (and its variance, if required) should be c stored. For example, the interpolated value for point number c "point" should be stored in "out[offset[point]]" (assuming c the index "point" is zero-based). f For each interpolation point, this array will contain the f offset from the start of the OUT (and OUT_VAR) array(s) at f which the interpolated value (and its variance, if required) f should be stored. For example, the interpolated value for f point number POINT should be stored in OUT(1+OFFSET(POINT)). c coords f COORDS( NPOINT, NDIM_IN ) = DOUBLE PRECISION (Given) c An array of pointers to double, with "ndim_in" c elements. Element "coords[coord]" will point at the first c element of an array of double (with "npoint" elements) which c contains the values of coordinate number "coord" for each c interpolation point. The value of coordinate number "coord" c for interpolation point number "point" is therefore given by c "coords[coord][point]" (assuming both indices are c zero-based). f A 2-dimensional array containing the coordinates of the f points at which interpolation should be performed. These will f be stored so that coordinate number COORD for interpolation f point number POINT is found in element COORDS(POINT,COORD). * * If any interpolation point has any of its coordinates equal c to the value AST__BAD (as defined in the "ast.h" header f to the value AST__BAD (as defined in the AST_PAR include * file), then the corresponding output data (and variance) c should either be set to the value given by "badval", f should either be set to the value given by BADVAL, * or left unchanged, depending on whether the AST__NOBAD flag is c specified by "flags". f specified by FLAGS. c params f PARAMS( * ) = DOUBLE PRECISION (Given) c This will be a pointer to the same array as was given via the c "params" parameter of astResample. You may use this to f This will be the same array as was given via the f PARAMS argument of AST_RESAMPLE. You may use this to * pass any additional parameter values required by your * interpolation algorithm. c flags f FLAGS = INTEGER (Given) c This will be the same value as was given via the "flags" c parameter of astResample. You may test this value to f This will be the same value as was given via the FLAGS f argument of AST_RESAMPLE. You may test this value to * provide additional control over the operation of your * resampling algorithm. Note that the special flag values * AST__URESAMP1, 2, 3 & 4 are reserved for you to use for your * own purposes and will not clash with other pre-defined flag c values (see astResample). f values (see AST_RESAMPLE). c badval f BADVAL = (Given) c This will be the same value as was given via the "badval" c parameter of astResample, and will have the same numerical c type as the data being processed (i.e. as elements of the c "in" array). It should be used to test for bad pixels in the c input grid (but only if the AST__USEBAD flag is set via the c "flags" parameter) and (unless the AST__NOBAD flag is set in c "flags") for identifying bad output values in c the "out" (and "out_var") array(s). f This will be the same value as was given for the BADVAL f argument of AST_RESAMPLE, and will have the same numerical f type as the data being processed (i.e. as elements of the IN f array). It should be used to test for bad pixels in the f input grid (but only if the AST__USEBAD flag is set via the f FLAGS argument) and (unless the AST__NOBAD flag is set in f FLAGS) for identifying bad output values in the OUT (and f OUT_VAR) array(s). c out f OUT( * ) = (Returned) c Pointer to an array with the same numerical type as the "in" f An array with the same numerical type as the IN * array, into which the interpolated data values should be * returned. Note that details of the storage order and number * of dimensions of this array are not required, since the c "offset" array contains all necessary information about where f OFFSET array contains all necessary information about where * each returned value should be stored. * c In general, not all elements of this array (or the "out_var" f In general, not all elements of this array (or the OUT_VAR * array below) may be used in any particular invocation of the c function. Those which are not used should be returned f routine. Those which are not used should be returned * unchanged. c out_var f OUT_VAR( * ) = (Returned) c Pointer to an optional array with the same type and size as c the "out" array, into which variance estimates for the c resampled values should be returned. This array will only be c given if the "in_var" array has also been given. f An optional array with the same type and size as the OUT f array, into which variance estimates for the resampled values f should be returned. This array will only be given if the f AST__USEVAR flag is set via the FLAGS argument. * c If given, it is addressed in exactly the same way (via the c "offset" array) as the "out" array. The values returned c should be estimates of the statistical variance of the c corresponding values in the "out" array, on the assumption c that all errors in input data values are statistically c independent and that their variance estimates may simply be c summed (with appropriate weighting factors). f If given, it is addressed in exactly the same way (via the f OFFSET array) as the OUT array. The values returned should be f estimates of the statistical variance of the corresponding f values in the OUT array, on the assumption that all errors in f input data values are statistically independent and that f their variance estimates may simply be summed (with f appropriate weighting factors). * c If no output variance estimates are required, a NULL pointer c will be given. f If the AST__USEVAR flag is not set, then variance values are f not being processed. In this case, this array may be a dummy f (e.g. one-element) array and should not be used. c nbad f NBAD = INTEGER (Returned) c Pointer to an int in which to return the number of interpolation c points at f This should return the number of interpolation points at * which no valid interpolated value could be obtained. The maximum c value that should be returned is "npoint", and the minimum is f value that should be returned is NPOINT, and the minimum is * zero (indicating that all output values were successfully * obtained). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The data type indicates the numerical type of the data c being processed, as for astResample. f being processed, as for AST_RESAMPLE. c - This function will typically be invoked more than once for each c invocation of astResample. f - This routine will typically be invoked more than once for each f invocation of AST_RESAMPLE. c - If an error occurs within this function, it should use c astSetStatus to set the AST error status to an error value. c This will cause an immediate return from astResample. The error c value AST__UINER is available for this purpose, but other values may c also be used (e.g. if you wish to distinguish different types of c error). f - If an error occurs within this routine, it should set the f STATUS argument to an error value before returning. This will f cause an immediate return from AST_RESAMPLE. The error value f AST__UINER is available for this purpose, but other values may also f be used (e.g. if you wish to distinguish different types of error). f The AST__UINER error value is defined in the AST_ERR include file. *-- */ /* Note the above is just a description to act as a template. The function does not actually exist. */ /* *++ * Name: c astUkern1 f AST_UKERN1 * Purpose: * 1-dimensional sub-pixel interpolation kernel. * Type: * Fictitious function. * Synopsis: c #include "mapping.h" c void astUkern1( double offset, const double params[], int flags, c double *value ) f CALL AST_UKERN1( OFFSET, PARAMS, FLAGS, VALUE, STATUS ) * Class Membership: * Mapping member function. * Description: c This is a fictitious function which does not actually c exist. Instead, this description constitutes a template so that c you may implement a function with this interface for yourself c (and give it any name you wish). A pointer to such a function c may be passed via the "finterp" parameter of the astResample c functions (q.v.) in order to supply a 1-dimensional c interpolation kernel to the algorithm which performs sub-pixel c interpolation during resampling of gridded data (you must also c set the "interp" parameter of astResample to the value c AST__UKERN1). This allows you to use your own interpolation c kernel in addition to those which are pre-defined. f This is a fictitious routine which does not actually f exist. Instead, this description constitutes a template so that f you may implement a routine with this interface for yourself f (and give it any name you wish). Such a routine f may be passed via the FINTERP argument of the AST_RESAMPLE f functions (q.v.) in order to supply a 1-dimensional f interpolation kernel to the algorithm which performs sub-pixel f interpolation during resampling of gridded data (you must also f set the INTERP argument of AST_RESAMPLE to the value f AST__UKERN1). This allows you to use your own interpolation f kernel in addition to those which are pre-defined. * c The function calculates the value of a 1-dimensional sub-pixel f The routine calculates the value of a 1-dimensional sub-pixel * interpolation kernel. This determines how the weight given to * neighbouring pixels in calculating an interpolated value depends * on the pixel's offset from the interpolation point. In more than * one dimension, the weight assigned to a pixel is formed by * evaluating this 1-dimensional kernel using the offset along each * dimension in turn. The product of the returned values is then * used as the pixel weight. * Parameters: c offset f OFFSET = DOUBLE PRECISION (Given) * This will be the offset of the pixel from the interpolation * point, measured in pixels. This value may be positive or * negative, but for most practical interpolation schemes its * sign should be ignored. c params f PARAMS( * ) = DOUBLE PRECISION (Given) c This will be a pointer to the same array as was given via the c "params" parameter of astResample. You may use this to f This will be the same array as was given via the f PARAMS argument of AST_RESAMPLE. You may use this to * pass any additional parameter values required by your kernel, c but note that "params[0]" will already have been used to specify f but note that PARAMS(1) will already have been used to specify * the number of neighbouring pixels which contribute to the * interpolated value. c flags f FLAGS = INTEGER (Given) c This will be the same value as was given via the "flags" c parameter of astResample. You may test this value to f This will be the same value as was given via the FLAGS f argument of AST_RESAMPLE. You may test this value to * provide additional control over the operation of your c function. Note that the special flag values AST__URESAMP1, 2, f routine. Note that the special flag values AST__URESAMP1, 2, * 3 & 4 are reserved for you to use for your own purposes and * will not clash with other pre-defined flag c values (see astResample). f values (see AST_RESAMPLE). c value f VALUE = DOUBLE PRECISION (Returned) c Pointer to a double to receive the calculated kernel value, f The calculated kernel value, * which may be positive or negative. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Not all functions make good interpolation kernels. In general, * acceptable kernels tend to be symmetrical about zero, to have a * positive peak (usually unity) at zero, and to evaluate to zero * whenever the pixel offset has any other integral value (this * ensures that the interpolated values pass through the original * data). An interpolation kernel may or may not have regions with * negative values. You should consult a good book on image * processing for more details. c - If an error occurs within this function, it should use c astSetStatus to set the AST error status to an error value. c This will cause an immediate return from astResample. The error c value AST__UK1ER is available for this purpose, but other values may c also be used (e.g. if you wish to distinguish different types of c error). f - If an error occurs within this routine, it should set the f STATUS argument to an error value before returning. This will f cause an immediate return from AST_RESAMPLE. The error value f AST__UK1ER is available for this purpose, but other values may also f be used (e.g. if you wish to distinguish different types of error). f The AST__UK1ER error value is defined in the AST_ERR include file. *-- */ /* Note the above is just a description to act as a template. The function does not actually exist. */ static double UphillSimplex( const MapData *mapdata, double acc, int maxcall, const double dx[], double xmax[], double *err, int *ncall, int *status ) { /* * Name: * UphillSimplex * Purpose: * Find a function maximum using a modification of the simplex method. * Type: * Private function. * Synopsis: * #include "mapping.h" * double UphillSimplex( const MapData *mapdata, double acc, int maxcall, * const double dx[], double xmax[], double *err, * int *ncall, int *status ); * Class Membership: * Mapping member function. * Description: * This function applies a modification of the simplex method to * find a local maximum in the value returned by a Mapping * function. The modification used allows the method to cope with * coordinate constraints and (equivalently) regions where the * function returns "bad" values. The method is robust and not * susceptible to overflow, so is suitable for applying to Mapping * functions of unknown form. * Parameters: * mapdata * Pointer to a MapData structure which describes the Mapping * function, its coordinate constraints, etc. * acc * The accuracy required in the value of the maximum. * maxcall * The maximum number of Mapping function evaluations to use. * dx * Pointer to an array of double containing an offset along each * input coordinate for the Mapping function supplied. These * offsets will be used to construct the initial simplex * (i.e. they are the initial "step lengths" for each * coordinate) and may be positive or negative. * xmax * Pointer to an array of double which contains the coordinates * of an initial estimate of the location of the maximum. On * exit, this will be updated to contain the best estimate of * the location of the maximum as generated by this function. * err * Pointer to a double in which to return an estimate of the * error in the value of the maximum found. For normal * convergence, this should be no larger than "acc". However, if * the maximum number of Mapping function evaluations is * reached, the returned value may be larger than this, although * it should still be valid. In such cases, re-starting the * algorithm at the new location returned in "xmax" may be * advisable. * ncall * Pointer to an int in which the number of Mapping function * evaluations will be returned. * status * Pointer to the inherited status variable. * Returned Value: * An estimate of the Mapping function value at the local maximum. * Notes: * - The function may return before the requested accuracy has been * met and before all Mapping function evaluations have been * made. This signifies that an excessive number of function values * have been needed outside the coordinate constraints. This is * only likely if the function is unable to make progress near such * a constraint, in which case the algorithm should probably be * re-started. * - A value of AST__BAD will be returned if no maximum could be * found. This means that all the Mapping function evaluations * performed returned a value of AST__BAD. * - A value of AST__BAD will also be returned and no useful * information about a solution will be produced if this routine is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Constants: */ const double factor = 3.0; /* Simplex contraction/expansion factor */ /* Local Variables: */ double *f; /* Pointer to array of function values */ double *x; /* Pointer to array of vertex coordinates */ double *xnew; /* Pointer to workspace array */ double fnew; /* New function value */ double fsave; /* Saved function value */ double offset; /* Coordinate difference between vertices */ double range; /* Range of simplex values */ double result; /* Value to return */ double tmp; /* Temporary store for coordinate */ int coord; /* Loop counter for coordinates */ int hi; /* Index of best vertex */ int lo; /* Index of worst vertex */ int ncalla; /* Number of function calls attempted */ int ncoord; /* Number of function dimensions */ int nextlo; /* Index of second worst vertex */ int nvertex; /* Number of simplex vertices */ int vertex; /* Loop counter for vertices */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ *err = DBL_MAX; *ncall = 0; /* Obtain the number of input coordinates for the Mapping function and calculate the number of simplex vertices. */ ncoord = mapdata->nin; nvertex = ncoord + 1; /* Allocate workspace. */ f = astMalloc( sizeof( double ) * (size_t) nvertex ); x = astMalloc( sizeof( double ) * (size_t) ( ncoord * nvertex ) ); xnew = astMalloc( sizeof( double ) * (size_t) ncoord ); if ( astOK ) { /* Loop to set up an initial simplex. */ for ( vertex = 0; vertex < nvertex; vertex++ ) { for ( coord = 0; coord < ncoord; coord++ ) { tmp = xmax[ coord ]; /* Displace each point (except the first) the required amount along one of the axes to generate the coordinates of the simplex vertices. */ if ( coord == ( vertex - 1 ) ) tmp += dx[ coord ]; x[ vertex * ncoord + coord ] = tmp; } /* Evaluate the Mapping function at each vertex. */ f[ vertex ] = MapFunction( mapdata, &x[ vertex * ncoord ], ncall, status ); if ( f[ vertex ] == AST__BAD ) f[ vertex ] = -DBL_MAX; } /* Initialise the number of times we attempt to call the Mapping function (not necessarily the same as the number of times it was actually called, which is stored in *ncall). */ ncalla = nvertex; /* Loop until convergence is reached or an error occurs. */ while( astOK ) { /* Initialise the index of the lowest vertex of the simplex, the next lowest vertex and the highest vertex. */ lo = ( f[ 0 ] < f[ 1 ] ) ? 0 : 1; nextlo = 1 - lo; hi = 0; /* Loop to inspect each vertex and update these values. Ensure that in the case of equal vertices, the first one is taken to be the highest. This makes the maximisation stable (so that if no better maximum can be found, the original position is returned rather than a nearby position that yields the same function value). */ for ( vertex = 0; vertex < nvertex; vertex++ ) { if ( f[ vertex ] <= f[ lo ] ) { nextlo = lo; lo = vertex; } else if ( ( f[ vertex ] <= f[ nextlo ] ) && ( vertex != lo ) ) { nextlo = vertex; } if ( f[ vertex ] > f[ hi ] ) hi = vertex; } /* Estimate the error on the result as the difference between the highest and lowest simplex vertices. */ if ( ( f[ hi ] == -DBL_MAX ) || ( f[ lo ] == -DBL_MAX ) ) { range = DBL_MAX; } else { range = f[ hi ] - f[ lo ]; } /* Test for convergence. Ideally, the accuracy criterion should have been met. However, also quit if the maximum number of Mapping function evaluations has been reached, or the number of points at which function values have been requested reaches three times this limit (this latter number will typically be larger because points lying outside the coordinate constraints do not result in the Mapping function being evaluated). */ if ( range <= fabs( acc ) || ( *ncall >= maxcall ) || ( ncalla >= ( 3 * maxcall ) ) ) { /* If quitting, return the coordinates and function value at the best simplex vertex, and the error estimate. */ for ( coord = 0; coord < ncoord; coord++ ) { xmax[ coord ] = x[ hi * ncoord + coord ]; } result = ( f[ hi ] == -DBL_MAX ) ? AST__BAD : f[ hi ]; *err = range; break; } /* If performing another iteration, first try reflecting the worst vertex through the opposite face of the simplex. Check for errors. */ fnew = NewVertex( mapdata, lo, -1.0, x, f, ncall, xnew, status ); ncalla++; if ( astOK ) { /* If this results in a point lying in a forbiddden region (either outside the coordinate constraints or where the Mapping function yields bad coordinate values), then we must make a departure from the standard simplex algorithm. This is because the inability to make forward progress in this case can cause the simplex to repeatedly contract about each face (except one) in turn. This mechanism normally results in lateral contraction as the simplex attempts to squeeze through a narrow gap which is impeding progress. However, in this case there is no gap to get through, so the lateral contraction can eventually make the simplex become degenerate (due to rounding). This prevents it from expanding laterally again and exploring the region adjacent to the constraint boundary once it has become small enough. */ if ( fnew == AST__BAD ) { /* To overcome this, we instead contract the worst simplex vertex towards the best vertex (this has the cumulative effect of contracting the simplex without changing its shape). First find the offset in each coordinate between these two vertices. */ for ( coord = 0; coord < ncoord; coord++ ) { offset = x[ lo * ncoord + coord ] - x[ hi * ncoord + coord ]; /* Scale the offset to obtain the new coordinate. */ x[ lo * ncoord + coord ] = x[ hi * ncoord + coord ] + offset / factor; /* If the distance between the two vertices has not decreased, we are in a region where rounding errors prevent them approaching each other any more closely, so simply set them equal. */ if ( fabs( x[ lo * ncoord + coord ] - x[ hi * ncoord + coord ] ) >= fabs( offset ) ) { x[ lo * ncoord + coord ] = x[ hi * ncoord + coord ]; } } /* Evaluate the Mapping function at the new vertex. */ f[ lo ] = MapFunction( mapdata, &x[ lo * ncoord ], ncall, status ); if ( f[ lo ] == AST__BAD ) f[ lo ] = -DBL_MAX; ncalla++; /* We now return to the standard simplex algorithm. If the new vertex is a new maximum, then see if more of the same is even better by trying to expand the best vertex away from the opposite face. */ } else if ( fnew >= f[ hi ] ) { fnew = NewVertex( mapdata, lo, factor, x, f, ncall, xnew, status ); ncalla++; /* Otherwise, if the new vertex was no improvement on the second worst, then try contracting the worst vertex towards the opposite face. */ } else if ( fnew <= f[ nextlo ] ) { fsave = f[ lo ]; fnew = NewVertex( mapdata, lo, 1.0 / factor, x, f, ncall, xnew, status ); ncalla++; /* If this didn't result in any improvement, then contract the entire simplex towards the best vertex. Use the same approach as earlier to protect against rounding so that all the simplex vertices will eventually coalesce if this process is repeated enough times. */ if ( astOK && ( fnew <= fsave ) ) { for ( vertex = 0; vertex < nvertex; vertex++ ) { if ( vertex != hi ) { for ( coord = 0; coord < ncoord; coord++ ) { offset = x[ vertex * ncoord + coord ] - x[ hi * ncoord + coord ]; x[ vertex * ncoord + coord ] = x[ hi * ncoord + coord ] + offset / factor; if ( fabs( x[ vertex * ncoord + coord ] - x[ hi * ncoord + coord ] ) >= fabs( offset ) ) { x[ vertex * ncoord + coord ] = x[ hi * ncoord + coord ]; } } /* Evaluate the Mapping function at each new vertex. */ f[ vertex ] = MapFunction( mapdata, &x[ vertex * ncoord ], ncall, status ); if ( f[ vertex ] == AST__BAD ) f[ vertex ] = -DBL_MAX; ncalla++; } } } } } } } /* Free workspace. */ f = astFree( f ); x = astFree( x ); xnew = astFree( xnew ); /* If an error occurred, clear the returned result. */ if ( !astOK ) result = AST__BAD; /* Return the result. */ return result; } static void ValidateMapping( AstMapping *this, int forward, int npoint, int ncoord_in, int ncoord_out, const char *method, int *status ) { /* * Name: * ValidateMapping * Purpose: * Validate a Mapping for use to transform coordinates. * Type: * Private function. * Synopsis: * #include "mapping.h" * void ValidateMapping( AstMapping *this, int forward, * int npoint, int ncoord_in, int ncoord_out, * const char *method, int *status ) * Class Membership: * Mapping member function. * Description: * This function checks that a Mapping is suitable for transforming * a set of points. It also checks that the number of points and * the number of coordinate values per point is valid. If an error * is detected, the global error status is set and an error report * made. Otherwise, the function returns without further action. * Parameters: * this * Pointer to the Mapping. * forward * A non-zero value indicates that the forward coordinate * transformation is to be checked, while a zero value requests * the inverse transformation. * npoint * The number of points being transformed. * ncoord_in * The number of coordinates associated with each input point. * ncoord_out * The number of coordinates associated with each output point. * method * Pointer to a null terminated character string containing the * name of the method which invoked this function to validate a * Mapping. This is used solely for constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int nin; /* Mapping Nin attribute value */ int nout; /* Mapping Nout attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Report an error if the requested transformation is not defined. */ if ( !( forward ? astGetTranForward( this ) : astGetTranInverse( this ) ) && astOK ) { astError( AST__TRNND, "%s(%s): %s coordinate transformation " "is not defined by the %s supplied.", status, method, astGetClass( this ), ( forward ? "A forward" : "An inverse" ), astGetClass( this ) ); } /* Obtain the effective values of the Nin and Nout attributes for the Mapping. */ nin = forward ? astGetNin( this ) : astGetNout( this ); nout = forward ? astGetNout( this ) : astGetNin( this ); /* If OK, check that the number of input coordinates matches the number required by the Mapping. Report an error if these numbers do not match. */ if ( astOK && ( ncoord_in != nin ) ) { astError( AST__NCPIN, "%s(%s): Bad number of input coordinate values " "(%d).", status, method, astGetClass( this ), ncoord_in ); astError( AST__NCPIN, "The %s given requires %d coordinate value%s for " "each input point.", status, astGetClass( this ), nin, ( nin == 1 ) ? "" : "s" ); } /* If OK, also check that the number of output coordinates matches the number required by the Mapping. Report an error if these numbers do not match. */ if ( astOK && ( ncoord_out != nout ) ) { astError( AST__NCPIN, "%s(%s): Bad number of output coordinate values " "(%d).", status, method, astGetClass( this ), ncoord_out ); astError( AST__NCPIN, "The %s given generates %s%d coordinate value%s " "for each output point.", status, astGetClass( this ), ( nout < ncoord_out ) ? "only " : "", nout, ( nout == 1 ) ? "" : "s" ); } /* Check that the number of points being transformed is not negative and report an error if necessary. */ if ( astOK && ( npoint < 0 ) ) { astError( AST__NPTIN, "%s(%s): Number of points to be transformed (%d) " "is invalid.", status, method, astGetClass( this ), npoint ); } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. */ /* *att++ * Name: * Invert * Purpose: * Mapping inversion flag. * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls which one of a Mapping's two possible * coordinate transformations is considered the "forward" * transformation (the other being the "inverse" * transformation). If the attribute value is zero (the default), * the Mapping's behaviour will be the same as when it was first * created. However, if it is non-zero, its two transformations * will be inter-changed, so that the Mapping displays the inverse * of its original behaviour. * * Inverting the boolean sense of the Invert attribute will cause * the values of a Mapping's Nin and Nout attributes to be * interchanged. The values of its TranForward and TranInverse * attributes will also be interchanged. This operation may be c performed with the astInvert function. f performed with the AST_INVERT routine. * Applicability: * Mapping * All Mappings have this attribute. * UnitMap * The value of the Invert attribute has no effect on the * behaviour of a UnitMap. * FrameSet * Inverting the boolean sense of the Invert attribute for a * FrameSet will cause its base and current Frames (and its Base * and Current attributes) to be interchanged. This, in turn, * may affect other properties and attributes of the FrameSet * (such as Nin, Nout, Naxes, TranForward, TranInverse, * etc.). The Invert attribute of a FrameSet is not itself * affected by selecting a new base or current Frame. *att-- */ /* This ia a boolean value (0 or 1) with a value of CHAR_MAX when undefined but yielding a default of zero. */ astMAKE_CLEAR(Mapping,Invert,invert,CHAR_MAX) astMAKE_GET(Mapping,Invert,int,0,( ( this->invert == CHAR_MAX ) ? 0 : this->invert )) astMAKE_SET(Mapping,Invert,int,invert,( (this->flags&=~AST__ISSIMPLE_FLAG),(value!=0) )) astMAKE_TEST(Mapping,Invert,( this->invert != CHAR_MAX )) /* *att++ * Name: * IsLinear * Purpose: * Is the Mapping linear? * Type: * Public attribute. * Synopsis: * Integer (boolean), read-only. * Description: * This attribute indicates whether a Mapping is an instance of a * class that always represents a linear transformation. Note, some * Mapping classes can represent linear or non-linear transformations * (the MathMap class for instance). Such classes have a zero value for * the IsLinear attribute. Specific instances of such classes can be * tested for linearity using the * astLinearApprox function. * AST_LINEARAPPROX routine. * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * The IsLinear value for a CmpMap is determined by the classes * of the encapsulated Mappings. For instance, a CmpMap that combines * a ZoomMap and a ShiftMap will have a non-zero value for its IsLinear * attribute, but a CmpMap that contains a MathMap will have a * value of zero for its IsLinear attribute. * Frame * The IsLinear value for a Frame is 1 (since a Frame is equivalent * to a UnitMap). * FrameSet * The IsLinear value for a FrameSet is obtained from the Mapping * from the base Frame to the current Frame. *att-- */ /* *att++ * Name: * IsSimple * Purpose: * Has the Mapping been simplified? * Type: * Public attribute. * Synopsis: * Integer (boolean), read-only. * Description: * This attribute indicates whether a Mapping has been simplified * by the c astSimplify f AST_SIMPLIFY * method. If the IsSimple value is non-zero, then the Mapping has * been simplified and so there is nothing to be gained by simplifying * it again. Indeed, the c astSimplify f AST_SIMPLIFY * method will immediately return the Mapping unchanged if the IsSimple * attribute indicates that the Mapping has already been simplified. * Applicability: * Mapping * All Mappings have this attribute. * Frame * All classes of Frame return zero for the IsSimple attribute. * This is because changes can be made to a Frame which affect the * Mapping represented by the Frame, and so there can be no * guarantee that the Mapping may not need re-simplifying. Most * non-Frame Mappings, on the other hand, are immutable and so when * they are simplified it is certain that they weill remain in a * simple state. *att-- */ astMAKE_GET(Mapping,IsSimple,int,0,((this->flags)&AST__ISSIMPLE_FLAG)) /* *att++ * Name: * Nin * Purpose: * Number of input coordinates for a Mapping. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute gives the number of coordinate values required to * specify an input point for a Mapping (i.e. the number of * dimensions of the space in which the Mapping's input points * reside). * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * If a CmpMap's component Mappings are joined in series, then * its Nin attribute is equal to the Nin attribute of the first * component (or to the Nout attribute of the second component * if the the CmpMap's Invert attribute is non-zero). * * If a CmpMap's component Mappings are joined in parallel, then * its Nin attribute is given by the sum of the Nin attributes * of each component (or to the sum of their Nout attributes if * the CmpMap's Invert attribute is non-zero). * Frame * The Nin attribute for a Frame is always equal to the number * of Frame axes (Naxes attribute). * FrameSet * The Nin attribute of a FrameSet is equal to the number of * axes (Naxes attribute) of its base Frame (as specified by the * FrameSet's Base attribute). The Nin attribute value may * therefore change if a new base Frame is selected. *att-- */ /* *att++ * Name: * Nout * Purpose: * Number of output coordinates for a Mapping. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute gives the number of coordinate values generated * by a Mapping to specify each output point (i.e. the number of * dimensions of the space in which the Mapping's output points * reside). * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * If a CmpMap's component Mappings are joined in series, then * its Nout attribute is equal to the Nout attribute of the * second component (or to the Nin attribute of the first * component if the the CmpMap's Invert attribute is non-zero). * * If a CmpMap's component Mappings are joined in parallel, then * its Nout attribute is given by the sum of the Nout attributes * of each component (or to the sum of their Nin attributes if * the CmpMap's Invert attribute is non-zero). * Frame * The Nout attribute for a Frame is always equal to the number * of Frame axes (Naxes attribute). * FrameSet * The Nout attribute of a FrameSet is equal to the number of * FrameSet axes (Naxes attribute) which, in turn, is equal to * the Naxes attribute of the FrameSet's current Frame (as * specified by the Current attribute). The Nout attribute value * may therefore change if a new current Frame is selected. *att-- */ /* *att++ * Name: * Report * Purpose: * Report transformed coordinates? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls whether coordinate values are reported * whenever a Mapping is used to transform a set of points. If its * value is zero (the default), no report is made. However, if it * is non-zero, the coordinates of each point are reported (both * before and after transformation) by writing them to standard * output. * * This attribute is provided as an aid to debugging, and to avoid * having to report values explicitly in simple programs. * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * When applied to a compound Mapping (CmpMap), only the Report * attribute of the CmpMap, and not those of its component * Mappings, is used. Coordinate information is never reported * for the component Mappings individually, only for the * complete CmpMap. * Frame * When applied to any Frame, the formatting capabilities of the c Frame (as provided by the astFormat function) will be used to f Frame (as provided by the AST_FORMAT function) will be used to * format the reported coordinates. * FrameSet * When applied to any FrameSet, the formatting capabilities of * the base and current Frames will be used (as above) to * individually format the input and output coordinates, as * appropriate. The Report attribute of a FrameSet is not itself * affected by selecting a new base or current Frame, but the * resulting formatting capabilities may be. * Notes: * - Unlike most other attributes, the value of the Report * attribute is not transferred when a Mapping is copied. Instead, * its value is undefined (and therefore defaults to zero) in any * copy. Similarly, it becomes undefined in any external c representation of a Mapping produced by the astWrite function. f representation of a Mapping produced by the AST_WRITE routine. *att-- */ /* This ia a boolean value (0 or 1) with a value of CHAR_MAX when undefined but yielding a default of zero. */ astMAKE_CLEAR(Mapping,Report,report,CHAR_MAX) astMAKE_GET(Mapping,Report,int,0,( ( this->report == CHAR_MAX ) ? 0 : this->report )) astMAKE_SET(Mapping,Report,int,report,( value != 0 )) astMAKE_TEST(Mapping,Report,( this->report != CHAR_MAX )) /* *att++ * Name: * TranForward * Purpose: * Forward transformation defined? * Type: * Public attribute. * Synopsis: * Integer (boolean), read-only. * Description: * This attribute indicates whether a Mapping is able to transform * coordinates in the "forward" direction (i.e. converting input * coordinates into output coordinates). If this attribute is * non-zero, the forward transformation is available. Otherwise, it * is not. * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * The TranForward attribute value for a CmpMap is given by the * boolean AND of the value for each component Mapping. * FrameSet * The TranForward attribute of a FrameSet applies to the * transformation which converts between the FrameSet's base * Frame and its current Frame (as specified by the Base and * Current attributes). This value is given by the boolean AND * of the TranForward values which apply to each of the * individual sub-Mappings required to perform this conversion. * The TranForward attribute value for a FrameSet may therefore * change if a new Base or Current Frame is selected. * Notes: * - An error will result if a Mapping with a TranForward value of * zero is used to transform coordinates in the forward direction. *att-- */ /* *att++ * Name: * TranInverse * Purpose: * Inverse transformation defined? * Type: * Public attribute. * Synopsis: * Integer (boolean), readonly. * Description: * This attribute indicates whether a Mapping is able to transform * coordinates in the "inverse" direction (i.e. converting output * coordinates back into input coordinates). If this attribute is * non-zero, the inverse transformation is available. Otherwise, it * is not. * Applicability: * Mapping * All Mappings have this attribute. * CmpMap * The TranInverse attribute value for a CmpMap is given by the * boolean AND of the value for each component Mapping. * FrameSet * The TranInverse attribute of a FrameSet applies to the * transformation which converts between the FrameSet's current * Frame and its base Frame (as specified by the Current and * Base attributes). This value is given by the boolean AND of * the TranInverse values which apply to each of the individual * sub-Mappings required to perform this conversion. * The TranInverse attribute value for a FrameSet may therefore * change if a new Base or Current Frame is selected. * Notes: * - An error will result if a Mapping with a TranInverse value of * zero is used to transform coordinates in the inverse direction. *att-- */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Mapping objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Mapping objects. * Parameters: * objin * Pointer to the Mapping to be copied. * objout * Pointer to the Mapping being constructed. * status * Pointer to the inherited status variable. * Notes: * - This constructor exists simply to ensure that the "Report" * attribute is cleared in any copy made of a Mapping. */ /* Local Variables: */ AstMapping *out; /* Pointer to output Mapping */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the output Mapping. */ out = (AstMapping *) objout; /* Clear the output Report attribute. */ out->report = CHAR_MAX; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Mapping objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Mapping objects. * Parameters: * obj * Pointer to the Mapping to be deleted. * status * Pointer to the inherited status variable. * Notes: * - This destructor does nothing and exists only to maintain a * one-to-one correspondence between destructors and copy * constructors. */ /* Return without action. */ } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Mapping 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 Mapping class to an output Channel. * Parameters: * this * Pointer to the Mapping 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 Variables: */ AstMapping *this; /* Pointer to the Mapping structure */ int invert; /* Mapping inverted? */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Mapping structure. */ this = (AstMapping *) this_object; /* Write out values representing the instance variables for the Mapping 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. */ /* Determine if the Mapping is inverted. The output values (e.g. number of input and output coordinates) will refer to the Mapping ***before*** this inversion flag is applied, but we need it when using (e.g.) the astGetNin/astGetNout methods to determine which one will return the required value. */ invert = astGetInvert( this ); /* (NB. there is a subtle point here that dictates the extent to which this inversion flag can be used... All use of methods (such as astGetInvert, which might be over-ridden by derived classes) must be restricted to determining the values of "unset" output quantities only (below). This is because when re-loading the Mapping, the derived classes will not have been loaded at the point when these values are re-read - hence any value whose interpretation depends on these methods cannot be reliably recovered.) */ /* Nin. */ /* ---- */ /* Use the instance variable directly to avoid the effect of the Invert attribute on the private member function. Treat zero as the default. */ set = ( this->nin != 0 ); ival = set ? this->nin : ( !invert ? astGetNin( this ) : astGetNout( this ) ); astWriteInt( channel, "Nin", set, 0, ival, "Number of input coordinates" ); /* Nout. */ /* ----- */ /* Use the instance variable directly. Treat zero as the default. */ set = ( this->nout != this->nin ); ival = set ? this->nout : ( !invert ? astGetNout( this ) : astGetNin( this ) ); astWriteInt( channel, "Nout", set, 0, ival, "Number of output coordinates" ); /* IsSimple. */ /* --------- */ ival = astGetIsSimple( this ); astWriteInt( channel, "IsSimp", ival, 0, ival, ival ? "Mapping has been simplified" : "Mapping has not been simplified" ); /* Invert. */ /* ------- */ set = TestInvert( this, status ); ival = set ? GetInvert( this, status ) : astGetInvert( this ); astWriteInt( channel, "Invert", set, 0, ival, ival ? "Mapping inverted" : "Mapping not inverted" ); /* TranForward. */ /* ------------ */ /* Use the instance variable directly. Treat 1 as the default. */ set = ( this->tran_forward == 0 ); ival = set ? this->tran_forward : ( !invert ? astGetTranForward( this ) : astGetTranInverse( this ) ); astWriteInt( channel, "Fwd", set, 0, ival, ival ? "Forward transformation defined" : "Forward transformation not defined" ); /* TranInverse. */ /* ------------ */ /* Use the instance variable directly. Treat 1 as the default. */ set = ( this->tran_inverse == 0 ); ival = set ? this->tran_inverse : ( !invert ? astGetTranInverse( this ) : astGetTranForward( this ) ); astWriteInt( channel, "Inv", set, 0, ival, ival ? "Inverse transformation defined" : "Inverse transformation not defined" ); /* Report. */ /* ------- */ set = TestReport( this, status ); ival = set ? GetReport( this, status ) : astGetReport( this ); astWriteInt( channel, "Report", set, 0, ival, ival ? "Report coordinate transformations" : "Don't report coordinate transformations" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAMapping and astCheckMapping functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Mapping,Object) astMAKE_CHECK(Mapping) AstMapping *astInitMapping_( void *mem, size_t size, int init, AstMappingVtab *vtab, const char *name, int nin, int nout, int tran_forward, int tran_inverse, int *status ) { /* *+ * Name: * astInitMapping * Purpose: * Initialise a Mapping. * Type: * Protected function. * Synopsis: * #include "mapping.h" * AstMapping *astInitMapping( void *mem, size_t size, int init, * AstMappingVtab *vtab, const char *name, * int nin, int nout, * int tran_forward, int tran_inverse ) * Class Membership: * Mapping initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Mapping object. It allocates memory (if necessary) to accommodate * the Mapping plus any additional data associated with the derived class. * It then initialises a Mapping 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 Mapping at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Mapping is to be initialised. * This must be of sufficient size to accommodate the Mapping data * (sizeof(Mapping)) 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 Mapping (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 Mapping * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Mapping'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 Mapping. * 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). * nin * The number of coordinate values per input point. * nout * The number of coordinate vales per output point. * tran_forward * A non-zero value indicates that the Mapping will be able to * transform coordinates in the forward direction. A zero value * indicates that it will not. * tran_inverse * A non-zero value indicates that the Mapping will be able to * transform coordinates in the inverse direction. A zero value * indicates that it will not. * Returned Value: * A pointer to the new Mapping. * Notes: * - The Mappings produced by this function implement all the basic methods * defined by the Mapping class. However, their astTransform method does not * actually perform any coordinate transformation (although it performs all * necessary argument validation and creates an output PointSet if * necessary, leaving its coordinate values undefined). * - This means that Mappings produced by this function are of limited use * on their own, but may easily be extended by a derived class simply by * over-riding the astTransform method to add the necessary coordinate * arithmetic. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. *- */ /* Local Variables: */ AstMapping *new; /* Pointer to new Mapping */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitMappingVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the initialisation values for validity, reporting an error if necessary. */ if ( nin < 0 ) { astError( AST__BADNI, "astInitMapping(%s): Bad number of input " "coordinates (%d).", status, name, nin ); astError( AST__BADNI, "This number should be zero or more." , status); } else if ( nout < 0 ) { astError( AST__BADNO, "astInitMapping(%s): Bad number of output " "coordinates (%d).", status, name, nout ); astError( AST__BADNI, "This number should be zero or more." , status); } /* Initialise an Object structure (the parent class) as the first component within the Mapping structure, allocating memory if necessary. */ new = (AstMapping *) astInitObject( mem, size, 0, (AstObjectVtab *) vtab, name ); if ( astOK ) { /* Initialise the Mapping data. */ /* ---------------------------- */ /* Store the numbers of input and output coordinates. */ new->nin = nin; new->nout = nout; /* Store the flags indicating which coordinate transformations are defined (constrain these values to 0 or 1). */ new->tran_forward = ( tran_forward != 0 ); new->tran_inverse = ( tran_inverse != 0 ); /* Initialise other attributes to their undefined values. */ new->invert = CHAR_MAX; new->report = CHAR_MAX; new->flags = 0; /* 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; } AstMapping *astLoadMapping_( void *mem, size_t size, AstMappingVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadMapping * Purpose: * Load a Mapping. * Type: * Protected function. * Synopsis: * #include "mapping.h" * AstMapping *astLoadMapping( void *mem, size_t size, * AstMappingVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * Mapping loader. * Description: * This function is provided to load a new Mapping 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 * Mapping structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Mapping at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Mapping is to be * loaded. This must be of sufficient size to accommodate the * Mapping data (sizeof(Mapping)) 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 Mapping (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 Mapping 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(AstMapping) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Mapping. If this is NULL, a pointer * to the (static) virtual function table for the Mapping 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 "Mapping" is used instead. * Returned Value: * A pointer to the new Mapping. * Notes: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *new; /* Pointer to the new Mapping */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Mapping. In this case the Mapping belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstMapping ); vtab = &class_vtab; name = "Mapping"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitMappingVtab( 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 Mapping. */ new = astLoadObject( mem, size, (AstObjectVtab *) 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, "Mapping" ); /* 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. */ /* Initialise bitwise flags to zero. */ new->flags = 0; /* Nin. */ /* ---- */ new->nin = astReadInt( channel, "nin", 0 ); if ( new->nin < 0 ) new->nin = 0; /* Nout. */ /* ----- */ new->nout = astReadInt( channel, "nout", new->nin ); if ( new->nout < 0 ) new->nout = 0; /* Invert. */ /* ------- */ new->invert = astReadInt( channel, "invert", CHAR_MAX ); if ( TestInvert( new, status ) ) SetInvert( new, new->invert, status ); /* IsSimple. */ /* --------- */ if( astReadInt( channel, "issimp", 0 ) ) new->flags |= AST__ISSIMPLE_FLAG; /* TranForward. */ /* ------------ */ new->tran_forward = ( astReadInt( channel, "fwd", 1 ) != 0 ); /* TranInverse. */ /* ------------ */ new->tran_inverse = ( astReadInt( channel, "inv", 1 ) != 0 ); /* Report. */ /* ------- */ new->report = astReadInt( channel, "report", CHAR_MAX ); if ( TestReport( new, status ) ) SetReport( new, new->report, status ); /* If an error occurred, clean up by deleting the new Mapping. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Mapping pointer. */ return new; } /* 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 astDecompose_( AstMapping *this, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,Decompose))( this, map1, map2, series, invert1, invert2, status ); } int astGetNin_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,GetNin))( this, status ); } int astGetNout_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,GetNout))( this, status ); } int astGetIsLinear_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,GetIsLinear))( this, status ); } int astGetTranForward_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,GetTranForward))( this, status ); } int astGetTranInverse_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,GetTranInverse))( this, status ); } void astInvert_( AstMapping *this, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,Invert))( this, status ); } void astMapBox_( AstMapping *this, const double lbnd_in[], const double ubnd_in[], int forward, int coord_out, double *lbnd_out, double *ubnd_out, double xl[], double xu[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,MapBox))( this, lbnd_in, ubnd_in, forward, coord_out, lbnd_out, ubnd_out, xl, xu, status ); } int astMapList_( AstMapping *this, int series, int invert, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,MapList))( this, series, invert, nmap, map_list, invert_list, status ); } int *astMapSplit_( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ){ int *result = NULL; AstMapping *tmap; if( map ) *map = NULL; if ( !astOK ) return NULL; result = (**astMEMBER(this,Mapping,MapSplit))( this, nin, in, &tmap, status ); if( tmap ) { *map = astCopy( tmap ); tmap = astAnnul( tmap ); } return result; } int astMapMerge_( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { if ( !astOK || astDoNotSimplify( this ) ) return -1; return (**astMEMBER(this,Mapping,MapMerge))( this, where, series, nmap, map_list, invert_list, status ); } int astDoNotSimplify_( AstMapping *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,DoNotSimplify))( this, status ); } void astReportPoints_( AstMapping *this, int forward, AstPointSet *in_points, AstPointSet *out_points, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,ReportPoints))( this, forward, in_points, out_points, status ); } #define MAKE_RESAMPLE_(X,Xtype) \ int astResample##X##_( AstMapping *this, int ndim_in, const int *lbnd_in, \ const int *ubnd_in, const Xtype *in, \ const Xtype *in_var, int interp, \ void (* finterp)( void ), const double *params, \ int flags, double tol, int maxpix, Xtype badval, \ int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const int *lbnd, const int *ubnd, Xtype *out, \ Xtype *out_var, int *status ) { \ if ( !astOK ) return 0; \ return (**astMEMBER(this,Mapping,Resample##X))( this, ndim_in, lbnd_in, \ ubnd_in, in, in_var, \ interp, finterp, params, \ flags, tol, maxpix, \ badval, ndim_out, \ lbnd_out, ubnd_out, \ lbnd, ubnd, \ out, out_var, status ); \ } #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_RESAMPLE_(LD,long double) #endif MAKE_RESAMPLE_(D,double) MAKE_RESAMPLE_(F,float) MAKE_RESAMPLE_(L,long int) MAKE_RESAMPLE_(UL,unsigned long int) MAKE_RESAMPLE_(I,int) MAKE_RESAMPLE_(UI,unsigned int) MAKE_RESAMPLE_(K,INT_BIG) MAKE_RESAMPLE_(UK,UINT_BIG) MAKE_RESAMPLE_(S,short int) MAKE_RESAMPLE_(US,unsigned short int) MAKE_RESAMPLE_(B,signed char) MAKE_RESAMPLE_(UB,unsigned char) #undef MAKE_RESAMPLE_ #define MAKE_REBIN_(X,Xtype) \ void astRebin##X##_( AstMapping *this, double wlim, int ndim_in, const int *lbnd_in, \ const int *ubnd_in, const Xtype *in, \ const Xtype *in_var, int interp, \ const double *params, \ int flags, double tol, int maxpix, Xtype badval, \ int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const int *lbnd, const int *ubnd, Xtype *out, \ Xtype *out_var, int *status ) { \ if ( !astOK ) return; \ (**astMEMBER(this,Mapping,Rebin##X))( this, wlim, ndim_in, lbnd_in, \ ubnd_in, in, in_var, \ interp, params, \ flags, tol, maxpix, \ badval, ndim_out, \ lbnd_out, ubnd_out, \ lbnd, ubnd, \ out, out_var, status ); \ } #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_REBIN_(LD,long double) #endif MAKE_REBIN_(D,double) MAKE_REBIN_(F,float) MAKE_REBIN_(I,int) MAKE_REBIN_(B,signed char) MAKE_REBIN_(UB,unsigned char) #undef MAKE_REBIN_ #define MAKE_REBINSEQ_(X,Xtype) \ void astRebinSeq##X##_( AstMapping *this, double wlim, int ndim_in, const int *lbnd_in, \ const int *ubnd_in, const Xtype *in, \ const Xtype *in_var, int interp, \ const double *params, \ int flags, double tol, int maxpix, Xtype badval, \ int ndim_out, \ const int *lbnd_out, const int *ubnd_out, \ const int *lbnd, const int *ubnd, Xtype *out, \ Xtype *out_var, double *weights, int64_t *nused, \ int *status ) { \ if ( !astOK ) return; \ (**astMEMBER(this,Mapping,RebinSeq##X))( this, wlim, ndim_in, lbnd_in, \ ubnd_in, in, in_var, \ interp, params, \ flags, tol, maxpix, \ badval, ndim_out, \ lbnd_out, ubnd_out, \ lbnd, ubnd, out, out_var, \ weights, nused, status ); \ } #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_REBINSEQ_(LD,long double) #endif MAKE_REBINSEQ_(D,double) MAKE_REBINSEQ_(F,float) MAKE_REBINSEQ_(I,int) MAKE_REBINSEQ_(B,signed char) MAKE_REBINSEQ_(UB,unsigned char) #undef MAKE_REBINSEQ_ double astRate_( AstMapping *this, double *at, int ax1, int ax2, int *status ){ astDECLARE_GLOBALS if ( !astOK ) return AST__BAD; astGET_GLOBALS(this); if( ax1 < 0 || ax1 >= astGetNout( this ) ) { astError( AST__AXIIN, "astRate(%s): Invalid output index (%d) " "specified - should be in the range 1 to %d.", status, astGetClass( this ), ax1 + 1, astGetNout( this ) ); } else if( ax2 < 0 || ax2 >= astGetNin( this ) ) { astError( AST__AXIIN, "astRate(%s): Invalid input index (%d) " "specified - should be in the range 1 to %d.", status, astGetClass( this ), ax2 + 1, astGetNin( this ) ); } if( rate_disabled ) { return ( at[ ax2 ] != AST__BAD ) ? 1.0 : AST__BAD; } else { return (**astMEMBER(this,Mapping,Rate))( this, at, ax1, ax2, status ); } } AstMapping *astRemoveRegions_( AstMapping *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Mapping,RemoveRegions))( this, status ); } AstMapping *astSimplify_( AstMapping *this, int *status ) { AstMapping *result; if ( !astOK ) return NULL; if( !astGetIsSimple( this ) && !astDoNotSimplify( this ) ) { result = (**astMEMBER(this,Mapping,Simplify))( this, status ); if( result ) result->flags |= AST__ISSIMPLE_FLAG; /* Indicate simplification has been done */ } else { result = astClone( this ); } return result; } AstPointSet *astTransform_( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { AstPointSet *result; if ( !astOK ) return NULL; result = (**astMEMBER(this,Mapping,Transform))( this, in, forward, out, status ); (void) astReplaceNaN( result ); return result; } void astTran1_( AstMapping *this, int npoint, const double xin[], int forward, double xout[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,Tran1))( this, npoint, xin, forward, xout, status ); } void astTran2_( AstMapping *this, int npoint, const double xin[], const double yin[], int forward, double xout[], double yout[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,Tran2))( this, npoint, xin, yin, forward, xout, yout, status ); } void astTranGrid_( AstMapping *this, int ncoord_in, const int lbnd[], const int ubnd[], double tol, int maxpix, int forward, int ncoord_out, int outdim, double *out, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,TranGrid))( this, ncoord_in, lbnd, ubnd, tol, maxpix, forward, ncoord_out, outdim, out, status ); } void astTranN_( AstMapping *this, int npoint, int ncoord_in, int indim, const double *in, int forward, int ncoord_out, int outdim, double *out, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,TranN))( this, npoint, ncoord_in, indim, in, forward, ncoord_out, outdim, out, status ); } void astTranP_( AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Mapping,TranP))( this, npoint, ncoord_in, ptr_in, forward, ncoord_out, ptr_out, status ); } int astLinearApprox_( AstMapping *this, const double *lbnd, const double *ubnd, double tol, double *fit, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,LinearApprox))( this, lbnd, ubnd, tol, fit, status ); } int astQuadApprox_( AstMapping *this, const double lbnd[2], const double ubnd[2], int nx, int ny, double *fit, double *rms, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Mapping,QuadApprox))( this, lbnd, ubnd, nx, ny, fit, rms, status ); } /* 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. */ void DecomposeId_( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); void MapBoxId_( AstMapping *, const double [], const double [], int, int, double *, double *, double [], double [], int * ); double astRateId_( AstMapping *, double *, int, int, int * ); void astMapSplitId_( AstMapping *, int, const int *, int *, AstMapping **, int * ); /* Special interface function implementations. */ /* ------------------------------------------- */ void astDecomposeId_( AstMapping *this, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { /* *++ * Name: c astDecompose f AST_DECOMPOSE * Purpose: * Decompose a Mapping into two component Mappings. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astDecompose( AstMapping *this, AstMapping **map1, c AstMapping **map2, int *series, int *invert1, c int *invert2 ) f CALL AST_DECOMPOSE( THIS, MAP1, MAP2, SERIES, INVERT1, INVERT2, STATUS ) * Class Membership: * Mapping method. * Description: c This function returns pointers to two Mappings which, when applied f This routine returns pointers to two Mappings which, when applied * either in series or parallel, are equivalent to the supplied Mapping. * * Since the Frame class inherits from the Mapping class, Frames can * be considered as special types of Mappings and so this method can * be used to decompose either CmpMaps or CmpFrames. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping. c map1 f MAP1 = INTEGER (Returned) c Address of a location to receive a pointer to first component f A pointer to first component * Mapping. c map2 f MAP2 = INTEGER (Returned) c Address of a location to receive a pointer to second component f A pointer to second component * Mapping. c series f SERIES = LOGICAL (Returned) c Address of a location to receive a value indicating if the c component Mappings are applied in series or parallel. A non-zero c value means that the supplied Mapping is equivalent to applying map1 c followed by map2 in series. A zero value means that the supplied c Mapping is equivalent to applying map1 to the lower numbered axes c and map2 to the higher numbered axes, in parallel. f Indicates if the f component Mappings are applied in series or parallel. A .TRUE. f value means that the supplied Mapping is equivalent to applying MAP1 f followed by MAP2 in series. A zero value means that the supplied f Mapping is equivalent to applying MAP1 to the lower numbered axes f and MAP2 to the higher numbered axes, in parallel. c invert1 f INVERT1 = INTEGER (Returned) c The value of the Invert attribute to be used with map1. f The value of the Invert attribute to be used with MAP1. c invert2 f INVERT2 = INTEGER (Returned) c The value of the Invert attribute to be used with map2. f The value of the Invert attribute to be used with MAP2. * Applicability: * CmpMap c If the supplied Mapping is a CmpMap, then map1 and map2 will be f If the supplied Mapping is a CmpMap, then MAP1 and MAP2 will be * returned holding pointers to the component Mappings used to * create the CmpMap, either in series or parallel. Note, changing * the Invert attribute of either of the component Mappings using * the returned pointers will have no effect on the supplied CmpMap. * This is because the CmpMap remembers and uses the original settings * of the Invert attributes (that is, the values of the Invert * attributes when the CmpMap was first created). These are the c Invert values which are returned in invert1 and invert2. f Invert values which are returned in INVERT1 and INVERT2. * TranMap c If the supplied Mapping is a TranMap, then map1 and map2 will be f If the supplied Mapping is a TranMap, then MAP1 and MAP2 will be * returned holding pointers to the forward and inverse Mappings * represented by the TranMap (zero will be returned for c series). f SERIES). * Note, changing the Invert attribute of * either of the component Mappings using the returned pointers will * have no effect on the supplied TranMap. This is because the TranMap * remembers and uses the original settings of the Invert attributes * (that is, the values of the Invert attributes when the TranMap was * first created). These are the c Invert values which are returned in invert1 and invert2. f Invert values which are returned in INVERT1 and INVERT2. * Mapping c For any class of Mapping other than a CmpMap, map1 will be c returned holding a clone of the supplied Mapping pointer, and map2 c will be returned holding a NULL pointer. Invert1 will be returned c holding the current value of the Invert attribute for the supplied c Mapping, and invert2 will be returned holding zero. f For any class of Mapping other than a CmpMap, MAP1 will be f returned holding a clone of the supplied Mapping pointer, and MAP2 f will be returned holding AST__NULL. INVERT1 will be returned f holding the current value of the Invert attribute for the supplied f Mapping, and INVERT2 will be returned holding zero. * CmpFrame c If the supplied Mapping is a CmpFrame, then map1 and map2 will be f If the supplied Mapping is a CmpFrame, then MAP1 and MAP2 will be * returned holding pointers to the component Frames used to * create the CmpFrame. The component Frames are considered to be in * applied in parallel. * Frame c For any class of Frame other than a CmpFrame, map1 will be c returned holding a clone of the supplied Frame pointer, and map2 c will be returned holding a NULL pointer. f For any class of Frame other than a CmpFrame, MAP1 will be f returned holding a clone of the supplied Frame pointer, and MAP2 f will be returned holding AST__NULL. * Notes: * - The returned Invert values should be used in preference to the * current values of the Invert attribute in map1 and map2. This is * because the attributes may have changed value since the Mappings * were combined. * - Any changes made to the component Mappings using the returned * pointers will be reflected in the supplied Mapping. *-- * Implementation Notes: * This function implements the public interface for the * astDecompose method. It is identical to astDecompose_ except for * the following: * * - ID values are returned via the "map1" and "map2" parameters * instead of true C pointers. This is required because this * conversion cannot be performed by the macro that invokes the * function. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the normal astDecompose_ function to decompose the Mapping. */ astDecompose( this, map1, map2, series, invert1, invert2 ); /* If required, return ID values for the component Mappings. */ if ( map1 ) *map1 = astMakeId( *map1 ); if ( map2 ) *map2 = astMakeId( *map2 ); } void astMapBoxId_( AstMapping *this, const double lbnd_in[], const double ubnd_in[], int forward, int coord_out, double *lbnd_out, double *ubnd_out, double xl[], double xu[], int *status ) { /* *++ * Name: c astMapBox f AST_MAPBOX * Purpose: * Find a bounding box for a Mapping. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astMapBox( AstMapping *this, c const double lbnd_in[], const double ubnd_in[], c int forward, int coord_out, c double *lbnd_out, double *ubnd_out, c double xl[], double xu[] ); f CALL AST_MAPBOX( THIS, LBND_IN, UBND_IN, FORWARD, COORD_OUT, f LBND_OUT, UBND_OUT, XL, XU, STATUS ) * Class Membership: * Mapping method. * Description: c This function allows you to find the "bounding box" which just c encloses another box after it has been transformed by a Mapping c (using either its forward or inverse transformation). A typical c use might be to calculate the size of an image after being c transformed by a Mapping. f This routine allows you to find the "bounding box" which just f encloses another box after it has been transformed by a Mapping f (using either its forward or inverse transformation). A typical f use might be to calculate the size of an image after being f transformed by a Mapping. * c The function works on one dimension at a time. When supplied c with the lower and upper bounds of a rectangular region (box) of c input coordinate space, it finds the lowest and highest values c taken by a nominated output coordinate within that c region. Optionally, it also returns the input coordinates where c these bounding values are attained. It should be used repeatedly c to obtain the extent of the bounding box in more than one c dimension. f The routine works on one dimension at a time. When supplied with f the lower and upper bounds of a rectangular region (box) of f input coordinate space, it finds the lowest and highest values f taken by a nominated output coordinate within that region. It f also returns the input coordinates where these bounding values f are attained. It should be used repeatedly to obtain the extent f of the bounding box in more than one dimension. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping. c lbnd_in f LBND_IN( * ) = DOUBLE PRECISION (Given) c Pointer to an array of double, with one element for each c Mapping input coordinate. This should contain the lower bound c of the input box in each input dimension. f An array with one element for each Mapping input f coordinate. This should contain the lower bound of the input f box in each input dimension. c ubnd_in f UBND_IN( * ) = DOUBLE PRECISION (Given) c Pointer to an array of double, with one element for each c Mapping input coordinate. This should contain the upper bound c of the input box in each input dimension. f An array with one element for each Mapping input f coordinate. This should contain the upper bound of the input f box in each input dimension. * * Note that it is permissible for the upper bound to be less * than the corresponding lower bound, as the values will simply * be swapped before use. c forward f FORWARD = LOGICAL (Given) c If this value is non-zero, then the Mapping's forward c transformation will be used to transform the input c box. Otherwise, its inverse transformation will be used. f If this value is .TRUE., then the Mapping's forward f transformation will be used to transform the input f box. Otherwise, its inverse transformation will be used. * c (If the inverse transformation is selected, then references c to "input" and "output" coordinates in this description c should be transposed. For example, the size of the "lbnd_in" c and "ubnd_in" arrays should match the number of output c coordinates, as given by the Mapping's Nout c attribute. Similarly, the "coord_out" parameter, below, c should nominate one of the Mapping's input coordinates.) f (If the inverse transformation is selected, then references f to "input" and "output" coordinates in this description f should be transposed. For example, the size of the LBND_IN f and UBND_IN arrays should match the number of output f coordinates, as given by the Mapping's Nout attribute. f Similarly, the COORD_OUT argument, below, should nominate one f of the Mapping's input coordinates.) c coord_out f COORD_OUT = INTEGER (Given) * The index of the output coordinate for which the lower and * upper bounds are required. This value should be at least one, * and no larger than the number of Mapping output coordinates. c lbnd_out f LBND_OUT = DOUBLE PRECISION (Returned) c Pointer to a double in which to return the lowest value taken c by the nominated output coordinate within the specified c region of input coordinate space. f The lowest value taken by the nominated output coordinate f within the specified region of input coordinate space. c ubnd_out f UBND_OUT = DOUBLE PRECISION (Returned) c Pointer to a double in which to return the highest value c taken by the nominated output coordinate within the specified c region of input coordinate space. f The highest value taken by the nominated output coordinate f within the specified region of input coordinate space. c xl f XL( * ) = DOUBLE PRECISION (Returned) c An optional pointer to an array of double, with one element c for each Mapping input coordinate. If given, this array will c be filled with the coordinates of an input point (although c not necessarily a unique one) for which the nominated output c coordinate attains the lower bound value returned in c "*lbnd_out". c c If these coordinates are not required, a NULL pointer may be c supplied. f An array with one element for each Mapping input f coordinate. This will return the coordinates of an input f point (although not necessarily a unique one) for which the f nominated output coordinate attains the lower bound value f returned in LBND_OUT. c xu f XU( * ) = DOUBLE PRECISION (Returned) c An optional pointer to an array of double, with one element c for each Mapping input coordinate. If given, this array will c be filled with the coordinates of an input point (although c not necessarily a unique one) for which the nominated output c coordinate attains the upper bound value returned in c "*ubnd_out". c c If these coordinates are not required, a NULL pointer may be c supplied. f An array with one element for each Mapping input f coordinate. This will return the coordinates of an input f point (although not necessarily a unique one) for which the f nominated output coordinate attains the upper bound value f returned in UBND_OUT. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Any input points which are transformed by the Mapping to give * output coordinates containing the value AST__BAD are regarded as * invalid and are ignored. They will make no contribution to * determining the output bounds, even although the nominated * output coordinate might still have a valid value at such points. c - An error will occur if the required output bounds cannot be c found. Typically, this might happen if all the input points c which the function considers turn out to be invalid (see c above). The number of points considered before generating such c an error is quite large, so this is unlikely to occur by c accident unless valid points are restricted to a very small c subset of the input coordinate space. f - An error will occur if the required output bounds cannot be f found. Typically, this might happen if all the input points f which the routine considers turn out to be invalid (see f above). The number of points considered before generating such f an error is quite large, so this is unlikely to occur by f accident unless valid points are restricted to a very small f subset of the input coordinate space. c - The values returned via "lbnd_out", "ubnd_out", "xl" and "xu" c will be set to the value AST__BAD if this function should fail c for any reason. Their initial values on entry will not be c altered if the function is invoked with the AST error status c set. f - The values returned via LBND_OUT, UBND_OUT, XL and XU will be f set to the value AST__BAD if this routine should fail for any f reason. Their initial values on entry will not be altered if the f routine is invoked with STATUS set to an error value. *-- * Implementation Notes: * This function implements the public interface for the astMapBox * method. It is identical to astMapBox_ except that the nominated * output coordinate given in "coord_out" is decremented by one * before use. This is to allow the public interface to use * one-based coordinate numbering (internally, zero-based * coordinate numbering is used). */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the protected version of this function with the "coord_out" value decremented. */ astMapBox( this, lbnd_in, ubnd_in, forward, coord_out - 1, lbnd_out, ubnd_out, xl, xu ); } double astRateId_( AstMapping *this, double *at, int ax1, int ax2, int *status ){ /* *++ * Name: c astRate f AST_RATE * Purpose: * Calculate the rate of change of a Mapping output. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c double astRate( AstMapping *this, double *at, int ax1, int ax2 ) f RESULT = AST_RATE( THIS, AT, AX1, AX2, STATUS ) * Class Membership: * Mapping method. * Description: c This function f This routine * 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. This method produces * good accuracy but can involve evaluating the Mapping 100 or more * times. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be applied. c at f AT( * ) = DOUBLE PRECISION (Given) c The address of an f 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. c ax1 f AX1 = INTEGER (Given) * The index of the Mapping output for which the rate of change is to * be found (output numbering starts at 1 for the first output). c ax2 f AX2 = INTEGER (Given) * The index of the Mapping input which is to be varied in order to * find the rate of change (input numbering starts at 1 for the first * input). f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astRate() f AST_RATE = DOUBLE PRECISION c The rate of change of Mapping output "ax1" with respect to input c "ax2", evaluated at "at", or AST__BAD if the value cannot be c calculated. f The rate of change of Mapping output AX1 with respect to input f AX2, evaluated at AT, or AST__BAD if the value cannot be f 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. *-- * Implementation Notes: * This function implements the public interface for the astRate * method. It is identical to astRate_ except that the nominated * coordinates given in "ax1" and "ax2" are decremented by one * before use. This is to allow the public interface to use * one-based coordinate numbering (internally, zero-based * coordinate numbering is used). */ /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* Invoke the protected version of this function with the axis indices decremented. */ return astRate( this, at, ax1 - 1, ax2 - 1 ); } void astMapSplitId_( AstMapping *this, int nin, const int *in, int *out, AstMapping **map, int *status ){ /* *++ * Name: c astMapSplit f AST_MAPSPLIT * Purpose: * Split a Mapping up into parallel component Mappings. * Type: * Public virtual function. * Synopsis: c #include "mapping.h" c void astMapSplit( AstMapping *this, int nin, const int *in, int *out, c AstMapping **map ) f CALL AST_MAPSPLIT( THIS, NIN, IN, OUT, MAP, STATUS ) * Class Membership: * Mapping method. * Description: c This function f This routine * creates a new Mapping which connects specified inputs within a * supplied Mapping to the corresponding outputs of the supplied Mapping. * This is only possible if the specified inputs correspond to some * subset of the Mapping outputs. That is, there must exist a subset of * the Mapping outputs for which each output depends only on the selected * Mapping inputs, and not on any of the inputs which have not been * selected. Also, any output which is not in this subset must not depend * on any of the selected inputs. If these conditions are not met by the * supplied Mapping, then c a NULL f an AST__NULL * Mapping pointer is returned. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Mapping to be split. c nin f NIN = INTEGER (Given) c The number of inputs to pick from "this". f The number of inputs to pick from THIS. c in f IN( NIN ) = INTEGER (Given) c Pointer to an f An * array holding the indices within the supplied Mapping of the inputs * which are to be picked from the Mapping. c This array should have "nin" elements. * If "Nin" is the number of inputs of the supplied Mapping, then each * element should have a value in the range 1 to Nin. c out f OUT( * ) = INTEGER (Returned) c Pointer to an f An * array in which to return the indices of the outputs of the supplied * Mapping which are fed by the picked inputs. A value of one is * used to refer to the first Mapping output. The supplied array should * have a length at least equal to the number of outputs in the * supplied Mapping. The number of values stored in the array on * exit will equal the number of outputs in the returned Mapping. * The i'th element in the returned array holds the index within * the supplied Mapping which corresponds to the i'th output of * the returned Mapping. c map f MAP = INTEGER (Returned) c Address of a location at which to return a pointer to the f The * returned Mapping. This Mapping will have c "nin" inputs (the number of outputs may be different to "nin"). NULL f NIN inputs (the number of outputs may be different to NIN). AST__NULL * is returned if the supplied Mapping has no subset of outputs which * depend only on the selected inputs. The returned Mapping is a * deep copy of the required parts of the supplied Mapping. * Notes: * - If this c function f routine * is invoked with the global error status set, or if it should fail for * any reason, then c a NULL value f AST__NULL * will be returned for c the "map" pointer. f MAP. *-- * Implementation Notes: * - This function implements the astMapSplit method available via the * public interface to the Mapping class and uses 1-based axis indices. * The protected interface method is provided by the astMapSplit function * and uses zero-based axis indices. Also, an ID value is returned for * "map" rather than a pointer. */ /* Local Variables: */ int *in_zero; /* Pointer to array of zero-based input indices */ int *result; /* Pointer to array of zero-based output indices*/ int i; /* Axis index */ int nout; /* No of outputs */ /* Initialise */ *map = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Decrement the axis indices by 1. */ in_zero = astMalloc( sizeof( int )*(size_t) nin ); if( in_zero ) { for( i = 0; i < nin; i++ ) in_zero[ i ] = in[ i ] - 1; /* Invoked the protected astMapSplit functon. */ result = astMapSplit( this, nin, in_zero, map ); /* If succesful, copy the output axes to the supplied array. */ if( result ) { nout = astGetNout( *map ); for( i = 0; i < nout; i++ ) out[ i ] = result[ i ] + 1; /* Free resurces. */ result = astFree( result ); } in_zero = astFree( in_zero ); } /* Free the returned Mapping if an error has occurred. */ if( !astOK ) *map = astAnnul( *map ); /* Return an ID value for the Mapping. */ *map = astMakeId( *map ); } ast-8.3.0/fstcsearchlocation.c0000664000175000017500000000724213004147321013256 00000000000000/* *+ * Name: * fstcsearchlocation.c * Purpose: * Define a FORTRAN 77 interface to the AST StcSearchLocation class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the StcSearchLocation class. * Routines Defined: * AST_ISASTCSEARCHLOCATION * AST_STCSEARCHLOCATION * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-NOV-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "stcsearchlocation.h" /* C interface to the StcSearchLocation class */ F77_LOGICAL_FUNCTION(ast_isastcsearchlocation)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASTCSEARCHLOCATION", NULL, 0 ); astWatchSTATUS( RESULT = astIsAStcSearchLocation( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_stcsearchlocation)( INTEGER(REG), INTEGER(NCOORDS), INTEGER_ARRAY(COORDS), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(REG) GENPTR_INTEGER(NCOORDS) GENPTR_CHARACTER(OPTIONS) GENPTR_INTEGER_ARRAY(COORDS) AstKeyMap **coords; F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_STCSEARCHLOCATION", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } /* Convert supplied integers to pointers. */ coords = astMalloc( sizeof( AstKeyMap * )*(size_t)( *NCOORDS )); if( astOK ) { for( i = 0; i < *NCOORDS; i++ ) { coords[ i ] = (AstKeyMap *) astMakePointer( astI2P( COORDS[ i ] )); } } RESULT = astP2I( astStcSearchLocation( astI2P( *REG ), *NCOORDS, coords, "%s", options ) ); astFree( coords ); astFree( options ); ) return RESULT; } ast-8.3.0/fbox.c0000664000175000017500000000651313004147321010336 00000000000000/* *+ * Name: * fbox.c * Purpose: * Define a FORTRAN 77 interface to the AST Box class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Box class. * Routines Defined: * AST_ISABOX * AST_BOX * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-MAR-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "box.h" /* C interface to the Box class */ F77_LOGICAL_FUNCTION(ast_isabox)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISABOX", NULL, 0 ); astWatchSTATUS( RESULT = astIsABox( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_box)( INTEGER(FRAME), INTEGER(FORM), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_INTEGER(FORM) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_BOX", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astBox( astI2P( *FRAME ), *FORM, POINT1, POINT2, astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/winmap.h0000664000175000017500000002145513004147321010702 00000000000000#if !defined( WINMAP_INCLUDED ) /* Include this file only once */ #define WINMAP_INCLUDED /* *+ * Name: * winmap.h * Type: * C include file. * Purpose: * Define the interface to the WinMap class. * Invocation: * #include "winmap.h" * Description: * This include file defines the interface to the WinMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The WinMap class implements Mappings which maps one window onto * another window by scaling and shifting the values on each axis. * Inheritance: * The WinMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * ClearAttrib * Clear an attribute value for a WinMap. * GetAttrib * Get an attribute value for a WinMap. * SetAttrib * Set an attribute value for a WinMap. * TestAttrib * Test if an attribute value has been set for a WinMap. * astMapMerge * Simplify a sequence of Mappings containing a WinMap. * astTransform * Apply a WinMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astWinTerms * Obtain copies of the shift and scale terms used by a WinMap. * Other Class Functions: * Public: * astIsAWinMap * Test class membership. * astWinMap * Create a WinMap. * * Protected: * astCheckWinMap * Validate class membership. * astInitWinMap * Initialise a WinMap. * astInitWinMapVtab * Initialise the virtual function table for the WinMap class. * astLoadWinMap * Load a WinMap. * Macros: * None. * Type Definitions: * Public: * AstWinMap * WinMap object type. * * Protected: * AstWinMapVtab * WinMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 23-OCT-1996 (DSB): * Original version. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitWinMapVtab * method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* WinMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstWinMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *a; /* Pointer to array of shifts */ double *b; /* Pointer to array of scale factors */ } AstWinMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstWinMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* WinTerms)( AstWinMap *, double **, double **, int * ); } AstWinMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstWinMapGlobals { AstWinMapVtab Class_Vtab; int Class_Init; } AstWinMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitWinMapGlobals_( AstWinMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(WinMap) /* Check class membership */ astPROTO_ISA(WinMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstWinMap *astWinMap_( int, const double [], const double [], const double [], const double [], const char *, int *, ...); #else AstWinMap *astWinMapId_( int, const double [], const double [], const double [], const double [], const char *, ... )__attribute__((format(printf,6,7))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstWinMap *astInitWinMap_( void *, size_t, int, AstWinMapVtab *, const char *, int, const double *, const double *, const double *, const double *, int * ); /* Vtab initialiser. */ void astInitWinMapVtab_( AstWinMapVtab *, const char *, int * ); /* Loader. */ AstWinMap *astLoadWinMap_( void *, size_t, AstWinMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astWinTerms_( AstWinMap *, double **, double **, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckWinMap(this) astINVOKE_CHECK(WinMap,this,0) #define astVerifyWinMap(this) astINVOKE_CHECK(WinMap,this,1) /* Test class membership. */ #define astIsAWinMap(this) astINVOKE_ISA(WinMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astWinMap astINVOKE(F,astWinMap_) #else #define astWinMap astINVOKE(F,astWinMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define \ astInitWinMap(mem,size,init,vtab,name,ncoord,c1_in,c2_in,c1_out,c2_out) \ astINVOKE(O,astInitWinMap_(mem,size,init,vtab,name,ncoord,c1_in,c2_in,c1_out,c2_out,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitWinMapVtab(vtab,name) astINVOKE(V,astInitWinMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadWinMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadWinMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckWinMap to validate WinMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astWinTerms(this,scale,shift) \ astINVOKE(V,astWinTerms_(astCheckWinMap(this),scale,shift,STATUS_PTR)) #endif #endif ast-8.3.0/box.h0000664000175000017500000001631113004147321010172 00000000000000#if !defined( BOX_INCLUDED ) /* Include this file only once */ #define BOX_INCLUDED /* *+ * Name: * box.h * Type: * C include file. * Purpose: * Define the interface to the Box class. * Invocation: * #include "box.h" * Description: * This include file defines the interface to the Box class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The Box class implement a Region which represents a simple interval * on each axis of the encapsulated Frame * Inheritance: * The Box class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-MAR-2003 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "region.h" /* Coordinate regions (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* Box structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstBox { /* Attributes inherited from the parent class. */ AstRegion region; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *extent; /* Original axis half-widths */ double *centre; /* Box centre coords */ double *lo; /* Low limits */ double *hi; /* High limits */ double *geolen; /* Geodesic half-dimensions of box */ int stale; /* Is other info out of date? */ } AstBox; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstBoxVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ void (* BoxPoints)( AstBox *, double *, double *, int *); } AstBoxVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstBoxGlobals { AstBoxVtab Class_Vtab; int Class_Init; } AstBoxGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitBoxGlobals_( AstBoxGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Box) /* Check class membership */ astPROTO_ISA(Box) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstBox *astBox_( void *, int, const double[], const double[], AstRegion *, const char *, int *, ...); #else AstBox *astBoxId_( void *, int, const double[], const double[], AstRegion *, const char *, ... )__attribute__((format(printf,6,7))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstBox *astInitBox_( void *, size_t, int, AstBoxVtab *, const char *, AstFrame *, int, const double[], const double[], AstRegion *, int * ); /* Vtab initialiser. */ void astInitBoxVtab_( AstBoxVtab *, const char *, int * ); /* Loader. */ AstBox *astLoadBox_( void *, size_t, AstBoxVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ void astBoxPoints_( AstBox *, double *, double *, int *); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckBox(this) astINVOKE_CHECK(Box,this,0) #define astVerifyBox(this) astINVOKE_CHECK(Box,this,1) /* Test class membership. */ #define astIsABox(this) astINVOKE_ISA(Box,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astBox astINVOKE(F,astBox_) #else #define astBox astINVOKE(F,astBoxId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitBox(mem,size,init,vtab,name,frame,form,p1,p2,unc) \ astINVOKE(O,astInitBox_(mem,size,init,vtab,name,frame,form,p1,p2,unc,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitBoxVtab(vtab,name) astINVOKE(V,astInitBoxVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadBox(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadBox_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckBox to validate Box pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astBoxPoints(this,centre,corner) astINVOKE(V,astBoxPoints_(astCheckBox(this),centre,corner,STATUS_PTR)) #endif #endif ast-8.3.0/fpcdmap.c0000664000175000017500000000616713004147321011017 00000000000000/* *+ * Name: * fpcdmap.c * Purpose: * Define a FORTRAN 77 interface to the AST PcdMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the PcdMap class. * Routines Defined: * AST_ISAPCDMAP * AST_PCDMAP * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 19-MAY-1999 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "pcdmap.h" /* C interface to the PcdMap class */ F77_LOGICAL_FUNCTION(ast_isapcdmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPCDMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPcdMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_pcdmap)( DOUBLE(DISCO), DOUBLE_ARRAY(PCDCEN), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_DOUBLE(DISCO) GENPTR_DOUBLE_ARRAY(PCDCEN) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_PCDMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPcdMap( *DISCO, PCDCEN, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/cmpregion.h0000664000175000017500000001764513004147321011400 00000000000000#if !defined( CMPREGION_INCLUDED ) /* Include this file only once */ #define CMPREGION_INCLUDED /* *+ * Name: * cmpregion.h * Type: * C include file. * Purpose: * Define the interface to the CmpRegion class. * Invocation: * #include "cmpregion.h" * Description: * This include file defines the interface to the CmpRegion class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The CmpRegion class implement a Region which represents a simple interval * on each axis of the encapsulated Frame * Inheritance: * The CmpRegion class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 11-OCT-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "region.h" /* Coordinate regions (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ /* Boolean operators */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__AND 1 #define AST__OR 2 #define AST__XOR 3 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* CmpRegion structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstCmpRegion { /* Attributes inherited from the parent class. */ AstRegion region; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstRegion *region1; /* First component Region */ AstRegion *region2; /* Second component Region */ int oper; /* Boolean operator */ double *rvals[ 2 ]; /* Used boundary length at each break */ double *offs[ 2 ]; /* Jump at each break */ int nbreak[ 2 ]; /* Number of breaks */ double d0[ 2 ]; /* Total used boundary length */ double dtot[ 2 ]; /* Total boundary length */ AstRegion *xor1; /* First XORed Region */ AstRegion *xor2; /* Second XORed Region */ int bounded; /* Is this CmpRegion bounded? */ } AstCmpRegion; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstCmpRegionVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* CmpRegionList)( AstCmpRegion *, int *, AstRegion ***, int * ); } AstCmpRegionVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstCmpRegionGlobals { AstCmpRegionVtab Class_Vtab; int Class_Init; } AstCmpRegionGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitCmpRegionGlobals_( AstCmpRegionGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(CmpRegion) /* Check class membership */ astPROTO_ISA(CmpRegion) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstCmpRegion *astCmpRegion_( void *, void *, int, const char *, int *, ...); #else AstCmpRegion *astCmpRegionId_( void *, void *, int, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstCmpRegion *astInitCmpRegion_( void *, size_t, int, AstCmpRegionVtab *, const char *, AstRegion *, AstRegion *, int, int * ); /* Vtab initialiser. */ void astInitCmpRegionVtab_( AstCmpRegionVtab *, const char *, int * ); /* Loader. */ AstCmpRegion *astLoadCmpRegion_( void *, size_t, AstCmpRegionVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astCmpRegionList_( AstCmpRegion *, int *, AstRegion ***, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckCmpRegion(this) astINVOKE_CHECK(CmpRegion,this,0) #define astVerifyCmpRegion(this) astINVOKE_CHECK(CmpRegion,this,1) /* Test class membership. */ #define astIsACmpRegion(this) astINVOKE_ISA(CmpRegion,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astCmpRegion astINVOKE(F,astCmpRegion_) #else #define astCmpRegion astINVOKE(F,astCmpRegionId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitCmpRegion(mem,size,init,vtab,name,reg1,reg2,oper) \ astINVOKE(O,astInitCmpRegion_(mem,size,init,vtab,name,reg1,reg2,oper,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitCmpRegionVtab(vtab,name) astINVOKE(V,astInitCmpRegionVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadCmpRegion(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadCmpRegion_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckCmpRegion to validate CmpRegion pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astCmpRegionList(this,nreg,reg_list) \ astINVOKE(V,astCmpRegionList_(this,nreg,reg_list,STATUS_PTR)) #endif #endif ast-8.3.0/globals.c0000664000175000017500000001521313004147321011020 00000000000000#if defined( THREAD_SAFE ) #define astCLASS #include "globals.h" #include "error.h" #include #include #include /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* Select the appropriate memory management functions. These will be the system's malloc, free and realloc unless AST was configured with the "--with-starmem" option, in which case they will be the starmem malloc, free and realloc. */ #ifdef HAVE_STAR_MEM_H # include # define MALLOC starMalloc # define FREE starFree # define REALLOC starRealloc #else # define MALLOC malloc # define FREE free # define REALLOC realloc #endif /* Module variables */ /* ================ */ /* A count of the number of thread-specific data structures created so far. Create a mutex to serialise access to this static variable. */ static int nthread = 0; static pthread_mutex_t nthread_mutex = PTHREAD_MUTEX_INITIALIZER; /* External variables visible throughout AST */ /* ========================================= */ /* Set a flag indicating that the thread-specific data key has not yet been created. */ pthread_once_t starlink_ast_globals_initialised = PTHREAD_ONCE_INIT; /* Declare the pthreads key that will be associated with the thread-specific data for each thread. */ pthread_key_t starlink_ast_globals_key; /* Declare the pthreads key that will be associated with the thread-specific status value for each thread. */ pthread_key_t starlink_ast_status_key; /* Function definitions: */ /* ===================== */ void astGlobalsCreateKey_( void ) { /* *+ * Name: * astGlobalsCreateKey_ * Purpose: * Create the thread specific data key used for accessing global data. * Type: * Protected function. * Synopsis: * #include "globals.h" * astGlobalsCreateKey_() * Description: * This function creates the thread-specific data key. It is called * once only by the pthread_once function, which is invoked via the * astGET_GLOBALS(this) macro by each AST function that requires access to * global data. * Returned Value: * Zero for success. *- */ /* Create the key used to access thread-specific global data values. Report an error if it fails. */ if( pthread_key_create( &starlink_ast_globals_key, NULL ) ) { fprintf( stderr, "ast: Failed to create Thread-Specific Data key" ); /* If succesful, create the key used to access the thread-specific status value. Report an error if it fails. */ } else if( pthread_key_create( &starlink_ast_status_key, NULL ) ) { fprintf( stderr, "ast: Failed to create Thread-Specific Status key" ); } } AstGlobals *astGlobalsInit_( void ) { /* *+ * Name: * astGlobalsInit * Purpose: * Create and initialise a structure holding thread-specific global * data values. * Type: * Protected function. * Synopsis: * #include "globals.h" * AstGlobals *astGlobalsInit; * Description: * This function allocates memory to hold thread-specific global data * for use throughout AST, and initialises it. * Returned Value: * Pointer to the structure holding global data values for the * currently executing thread. *- */ /* Local Variables: */ AstGlobals *globals; AstStatusBlock *status; /* Allocate memory to hold the global data values for the currently executing thread. Use malloc rather than astMalloc (the AST memory module uses global data managed by this module and so using astMalloc could put us into an infinite loop). */ globals = MALLOC( sizeof( AstGlobals ) ); if ( !globals ){ fprintf( stderr, "ast: Failed to allocate memory to hold AST " "global data values" ); /* Initialise the global data values. */ } else { /* Each thread has a unique integer identifier. */ pthread_mutex_lock( &nthread_mutex ); globals->thread_identifier = nthread++; pthread_mutex_unlock( &nthread_mutex ); #define INIT(class) astInit##class##Globals_( &(globals->class) ); INIT( Error ); INIT( Memory ); INIT( Object ); INIT( Axis ); INIT( Mapping ); INIT( Frame ); INIT( Channel ); INIT( CmpMap ); INIT( KeyMap ); INIT( FitsChan ); INIT( FitsTable ); INIT( CmpFrame ); INIT( DSBSpecFrame ); INIT( FrameSet ); INIT( LutMap ); INIT( MathMap ); INIT( PcdMap ); INIT( PointSet ); INIT( SkyAxis ); INIT( SkyFrame ); INIT( SlaMap ); INIT( SpecFrame ); INIT( SphMap ); INIT( TimeFrame ); INIT( WcsMap ); INIT( ZoomMap ); INIT( FluxFrame ); INIT( SpecFluxFrame ); INIT( GrismMap ); INIT( IntraMap ); INIT( Plot ); INIT( Plot3D ); INIT( Region ); INIT( Xml ); INIT( XmlChan ); INIT( Box ); INIT( Circle ); INIT( CmpRegion ); INIT( DssMap ); INIT( Ellipse ); INIT( Interval ); INIT( MatrixMap ); INIT( NormMap ); INIT( NullRegion ); INIT( PermMap ); INIT( PointList ); INIT( PolyMap ); INIT( Polygon ); INIT( Prism ); INIT( RateMap ); INIT( SelectorMap ); INIT( ShiftMap ); INIT( SpecMap ); INIT( Stc ); INIT( StcCatalogEntryLocation ); INIT( StcObsDataLocation ); INIT( SwitchMap ); INIT( Table ); INIT( TimeMap ); INIT( TranMap ); INIT( UnitMap ); INIT( UnitNormMap ); INIT( WinMap ); INIT( StcResourceProfile ); INIT( StcSearchLocation ); INIT( StcsChan ); #undef INIT /* Save the pointer as the value of the starlink_ast_globals_key thread-specific data key. */ if( pthread_setspecific( starlink_ast_globals_key, globals ) ) { fprintf( stderr, "ast: Failed to store Thread-Specific Data pointer." ); /* We also take this opportunity to allocate and initialise the thread-specific status value. */ } else { status = MALLOC( sizeof( AstStatusBlock ) ); if( status ) { status->internal_status = 0; status->status_ptr = &( status->internal_status ); /* If succesful, store the pointer to this memory as the value of the status key for the currently executing thread. Report an error if this fails. */ if( pthread_setspecific( starlink_ast_status_key, status ) ) { fprintf( stderr, "ast: Failed to store Thread-Specific Status pointer." ); } } else { fprintf( stderr, "ast: Failed to allocate memory for Thread-Specific Status pointer." ); } } } /* Return a pointer to the data structure holding the global data values. */ return globals; } #endif ast-8.3.0/table.c0000664000175000017500000052453613004147321010501 00000000000000/* *class++ * Name: * Table * Purpose: * A 2-dimensional table of values. * Constructor Function: c astTable f AST_TABLE * Description: * The Table class is a type of KeyMap that represents a two-dimensional * table of values. The c astMapGet... and astMapPut... f AST_MAPGET... and AST_MAPPUT... * methods provided by the KeyMap class should be used for storing and * retrieving values from individual cells within a Table. Each entry * in the KeyMap represents a single cell of the table and has an * associated key of the form "(i)" where "" is the * upper-case name of a table column and "i" is the row index (the * first row is row 1). Keys of this form should always be used when * using KeyMap methods to access entries within a Table. * * Columns must be declared using the c astAddColumn f AST_ADDCOLUMN * method before values can be stored within them. This also fixes the * type and shape of the values that may be stored in any cell of the * column. Cells may contain scalar or vector values of any data type * supported by the KeyMap class. Multi-dimensional arrays may also be * stored, but these must be vectorised when storing and retrieving * them within a table cell. All cells within a single column must * have the same type and shape, as specified when the column is added * to the Table. * * Tables may have parameters that describe global properties of the * entire table. These are stored as entries in the parent KeyMap and * can be access using the get and set method of the KeyMap class. * However, parameters must be declared using the c astAddParameter f AST_ADDPARAMETER * method before being accessed. * * Note - since accessing entries within a KeyMap is a relatively slow * process, it is not recommended to use the Table class to store * very large tables. * Inheritance: * The Table class inherits from the KeyMap class. * Attributes: * In addition to those attributes common to all KeyMaps, every * Table also has the following attributes: * * - ColumnLenC(column): The largest string length of any value in a column * - ColumnLength(column): The number of elements in each value in a column * - ColumnNdim(column): The number of axes spanned by each value in a column * - ColumnType(column): The data type of each value in a column * - ColumnUnit(column): The unit string describing each value in a column * - Ncolumn: The number of columns currently in the Table * - Nrow: The number of rows currently in the Table * - Nparameter: The number of global parameters currently in the Table * Functions: c In addition to those functions applicable to all KeyMaps, the c following functions may also be applied to all Tables: f In addition to those routines applicable to all KeyMaps, the f following routines may also be applied to all Tables: * c - astAddColumn: Add a new column definition to a Table c - astAddParameter: Add a new global parameter definition to a Table c - astColumnName: Return the name of the column with a given index c - astColumnShape: Return the shape of the values in a named column c - astHasColumn: Checks if a column exists in a Table c - astHasParameter: Checks if a global parameter exists in a Table c - astParameterName: Return the name of the parameter with a given index c - astPurgeRows: Remove all empty rows from a Table c - astRemoveColumn: Remove a column from a Table c - astRemoveParameter: Remove a global parameter from a Table c - astRemoveRow: Remove a row from a Table f - AST_ADDCOLUMN: Add a new column definition to a Table f - AST_ADDPARAMETER: Add a new global parameter definition to a Table f - AST_COLUMNNAME: Return the name of the column with a given index f - AST_COLUMNSHAPE: Return the shape of the values in a named column f - AST_HASCOLUMN: Checks if a column exists in a Table f - AST_HASPARAMETER: Checks if a global parameter exists in a Table f - AST_PARAMETERNAME: Return the name of the parameter with a given index f - AST_PURGEROWS: Remove all empty rows from a Table f - AST_REMOVECOLUMN: Remove a column from a Table f - AST_REMOVEPARAMETER: Remove a global parameter from a Table f - AST_REMOVEROW: Remove a row from a Table * Copyright: * Copyright (C) 2010-2011 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-NOV-2010 (DSB): * Original version. * 13-MAY-2011 (DSB): * Added support for table parameters. * 16-NOV-2013 (DSB): * Fix bug in forming keys in GetColumnLenC. *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 Table /* Fixed KeyMap entry names */ #define LENGTH "Length" #define NAME "Name" #define NROW "Nrow" #define SHAPE "Shape" #define SIZE "Size" #define TYPE "Type" #define UNIT "Unit" /* A function macro that puts quotes around a value */ #define STRING(w) #w /* Include 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 "keymap.h" /* Coordinate keymaps (parent class) */ #include "channel.h" /* I/O channels */ #include "table.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static void (* parent_setkeycase)( AstKeyMap *, int, int * ); static void (* parent_clearkeycase)( AstKeyMap *, int * ); static int (* parent_equal)( AstObject *, AstObject *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_mapget0a)( AstKeyMap *, const char *, AstObject * *, int *); static int (* parent_mapget0c)( AstKeyMap *, const char *, const char **, int *); static int (* parent_mapget0d)( AstKeyMap *, const char *, double *, int *); static int (* parent_mapget0f)( AstKeyMap *, const char *, float *, int *); static int (* parent_mapget0i)( AstKeyMap *, const char *, int *, int *); static int (* parent_mapget0p)( AstKeyMap *, const char *, void **, int *); static int (* parent_mapget0b)( AstKeyMap *, const char *, unsigned char *, int *); static int (* parent_mapget0s)( AstKeyMap *, const char *, short int *, int *); static int (* parent_mapget1a)( AstKeyMap *, const char *, int, int *, AstObject **, int * ); static int (* parent_mapget1c)( AstKeyMap *, const char *, int, int, int *, char *, int * ); static int (* parent_mapget1d)( AstKeyMap *, const char *, int, int *, double *, int * ); static int (* parent_mapget1f)( AstKeyMap *, const char *, int, int *, float *, int * ); static int (* parent_mapget1i)( AstKeyMap *, const char *, int, int *, int *, int * ); static int (* parent_mapget1p)( AstKeyMap *, const char *, int, int *, void **, int * ); static int (* parent_mapget1s)( AstKeyMap *, const char *, int, int *, short int *, int * ); static int (* parent_mapget1b)( AstKeyMap *, const char *, int, int *, unsigned char *, int * ); static int (* parent_mapgetelema)( AstKeyMap *, const char *, int, AstObject **, int * ); static int (* parent_mapgetelemc)( AstKeyMap *, const char *, int, int, char *, int * ); static int (* parent_mapgetelemd)( AstKeyMap *, const char *, int, double *, int * ); static int (* parent_mapgetelemf)( AstKeyMap *, const char *, int, float *, int * ); static int (* parent_mapgetelemi)( AstKeyMap *, const char *, int, int *, int * ); static int (* parent_mapgetelemp)( AstKeyMap *, const char *, int, void **, int * ); static int (* parent_mapgetelems)( AstKeyMap *, const char *, int, short int *, int * ); static int (* parent_mapgetelemb)( AstKeyMap *, const char *, int, unsigned char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_mapput0a)( AstKeyMap *, const char *, AstObject *, const char *, int *); static void (* parent_mapput0c)( AstKeyMap *, const char *, const char *, const char *, int *); static void (* parent_mapput0d)( AstKeyMap *, const char *, double, const char *, int *); static void (* parent_mapput0f)( AstKeyMap *, const char *, float, const char *, int *); static void (* parent_mapput0i)( AstKeyMap *, const char *, int, const char *, int *); static void (* parent_mapput0p)( AstKeyMap *, const char *, void *, const char *, int *); static void (* parent_mapput0b)( AstKeyMap *, const char *, unsigned char, const char *, int *); static void (* parent_mapput0s)( AstKeyMap *, const char *, short int, const char *, int *); static void (* parent_mapput1a)( AstKeyMap *, const char *, int, AstObject *const [], const char *, int * ); static void (* parent_mapput1c)( AstKeyMap *, const char *, int, const char *const [], const char *, int * ); static void (* parent_mapput1d)( AstKeyMap *, const char *, int, const double *, const char *, int * ); static void (* parent_mapput1f)( AstKeyMap *, const char *, int, const float *, const char *, int * ); static void (* parent_mapput1i)( AstKeyMap *, const char *, int, const int *, const char *, int * ); static void (* parent_mapput1p)( AstKeyMap *, const char *, int, void *const [], const char *, int * ); static void (* parent_mapput1b)( AstKeyMap *, const char *, int, const unsigned char *, const char *, int * ); static void (* parent_mapput1s)( AstKeyMap *, const char *, int, const short int *, const char *, int * ); static void (* parent_mapputelema)( AstKeyMap *, const char *, int, AstObject *, int * ); static void (* parent_mapputelemc)( AstKeyMap *, const char *, int, const char *, int * ); static void (* parent_mapputelemd)( AstKeyMap *, const char *, int, double, int * ); static void (* parent_mapputelemf)( AstKeyMap *, const char *, int, float, int * ); static void (* parent_mapputelemi)( AstKeyMap *, const char *, int, int, int * ); static void (* parent_mapputelemp)( AstKeyMap *, const char *, int, void *, int * ); static void (* parent_mapputelemb)( AstKeyMap *, const char *, int, unsigned char, int * ); static void (* parent_mapputelems)( AstKeyMap *, const char *, int, short int, int * ); static void (* parent_mapremove)( AstKeyMap *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_mapputu)( AstKeyMap *, const char *, const char *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Table) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Table,Class_Init) #define class_vtab astGLOBAL(Table,Class_Vtab) #define getattrib_buff astGLOBAL(Table,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstTableVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstTable *astTableId_( const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstKeyMap *ColumnProps( AstTable *, int * ); static AstKeyMap *ParameterProps( AstTable *, int * ); static const char *ColumnName( AstTable *, int index, int * ); static const char *ParameterName( AstTable *, int index, int * ); static const char *GetColumnUnit( AstTable *, const char *, int * ); static const char *TypeString( int ); static int Equal( AstObject *, AstObject *, int * ); static int GetColumnLenC( AstTable *, const char *, int * ); static int GetColumnLength( AstTable *, const char *, int * ); static int GetColumnNdim( AstTable *, const char *, int * ); static int GetColumnType( AstTable *, const char *, int * ); static int GetNcolumn( AstTable *, int * ); static int GetNparameter( AstTable *, int * ); static int GetObjSize( AstObject *, int * ); static int HasColumn( AstTable *, const char *, int *); static int HasParameter( AstTable *, const char *, int *); static int MapGet0A( AstKeyMap *, const char *, AstObject **, int * ); static int MapGet0B( AstKeyMap *, const char *, unsigned char *, int * ); static int MapGet0C( AstKeyMap *, const char *, const char **, int * ); static int MapGet0D( AstKeyMap *, const char *, double *, int * ); static int MapGet0F( AstKeyMap *, const char *, float *, int * ); static int MapGet0I( AstKeyMap *, const char *, int *, int * ); static int MapGet0P( AstKeyMap *, const char *, void **, int * ); static int MapGet0S( AstKeyMap *, const char *, short int *, int * ); static int MapGet1A( AstKeyMap *, const char *, int, int *, AstObject **, int * ); static int MapGet1B( AstKeyMap *, const char *, int, int *, unsigned char *, int * ); static int MapGet1C( AstKeyMap *, const char *, int, int, int *, char *, int * ); static int MapGet1D( AstKeyMap *, const char *, int, int *, double *, int * ); static int MapGet1F( AstKeyMap *, const char *, int, int *, float *, int * ); static int MapGet1I( AstKeyMap *, const char *, int, int *, int *, int * ); static int MapGet1P( AstKeyMap *, const char *, int, int *, void **, int * ); static int MapGet1S( AstKeyMap *, const char *, int, int *, short int *, int * ); static int MapGetElemA( AstKeyMap *, const char *, int, AstObject **, int * ); static int MapGetElemB( AstKeyMap *, const char *, int, unsigned char *, int * ); static int MapGetElemC( AstKeyMap *, const char *, int, int, char *, int * ); static int MapGetElemD( AstKeyMap *, const char *, int, double *, int * ); static int MapGetElemF( AstKeyMap *, const char *, int, float *, int * ); static int MapGetElemI( AstKeyMap *, const char *, int, int *, int * ); static int MapGetElemP( AstKeyMap *, const char *, int, void **, int * ); static int MapGetElemS( AstKeyMap *, const char *, int, short int *, int * ); static int ParseKey( AstTable *, const char *, int, char *, int *, AstKeyMap **, const char *, int * ); static void AddColumn( AstTable *, const char *, int, int, int *, const char *, int * ); static void AddParameter( AstTable *, const char *, int * ); static void ColumnShape( AstTable *, const char *, int, int *, int *, int *); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void MapPut0A( AstKeyMap *, const char *, AstObject *, const char *, int * ); static void MapPut0B( AstKeyMap *, const char *, unsigned char, const char *, int * ); static void MapPut0C( AstKeyMap *, const char *, const char *, const char *, int * ); static void MapPut0D( AstKeyMap *, const char *, double, const char *, int * ); static void MapPut0F( AstKeyMap *, const char *, float, const char *, int * ); static void MapPut0I( AstKeyMap *, const char *, int, const char *, int * ); static void MapPut0P( AstKeyMap *, const char *, void *, const char *, int * ); static void MapPut0S( AstKeyMap *, const char *, short int, const char *, int * ); static void MapPut1A( AstKeyMap *, const char *, int, AstObject *const [], const char *, int * ); static void MapPut1B( AstKeyMap *, const char *, int, const unsigned char *, const char *, int * ); static void MapPut1C( AstKeyMap *, const char *, int, const char *const [], const char *, int * ); static void MapPut1D( AstKeyMap *, const char *, int, const double *, const char *, int * ); static void MapPut1F( AstKeyMap *, const char *, int, const float *, const char *, int * ); static void MapPut1I( AstKeyMap *, const char *, int, const int *, const char *, int * ); static void MapPut1P( AstKeyMap *, const char *, int, void *const [], const char *, int * ); static void MapPut1S( AstKeyMap *, const char *, int, const short int *, const char *, int * ); static void MapPutElemA( AstKeyMap *, const char *, int, AstObject *, int * ); static void MapPutElemB( AstKeyMap *, const char *, int, unsigned char, int * ); static void MapPutElemC( AstKeyMap *, const char *, int, const char *, int * ); static void MapPutElemD( AstKeyMap *, const char *, int, double, int * ); static void MapPutElemF( AstKeyMap *, const char *, int, float, int * ); static void MapPutElemI( AstKeyMap *, const char *, int, int, int * ); static void MapPutElemP( AstKeyMap *, const char *, int, void *, int * ); static void MapPutElemS( AstKeyMap *, const char *, int, short int, int * ); static void MapPutU( AstKeyMap *, const char *, const char *, int * ); static void PurgeRows( AstTable *, int * ); static void RemoveColumn( AstTable *, const char *, int * ); static void RemoveParameter( AstTable *, const char *, int * ); static void RemoveRow( AstTable *, int, int * ); static void SetKeyCase( AstKeyMap *, int, int * ); static void ClearKeyCase( AstKeyMap *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static int GetNrow( AstTable *, int * ); static void SetNrow( AstTable *, int, int * ); static int GetNcolumn( AstTable *, int * ); static int GetNparameter( AstTable *, int * ); /* Member functions. */ /* ================= */ static void AddColumn( AstTable *this, const char *name, int type, int ndim, int *dims, const char *unit, int *status ) { /* *++ * Name: c astAddColumn f AST_ADDCOLUMN * Purpose: * Add a new column definition to a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astAddColumn( AstTable *this, const char *name, int type, int ndim, c int *dims, const char *unit ) f CALL AST_ADDCOLUMN( THIS, NAME, TYPE, NDIM, DIMS, UNIT, STATUS ) * Class Membership: * Table method. * Description: * Adds the definition of a new column to the supplied table. Initially, * the column is empty. Values may be added subsequently using the * methods of the KeyMap class. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c name f NAME = CHARACTER * ( * ) (Given) * The column name. Trailing spaces are ignored (all other spaces * are significant). The supplied string is converted to upper case. c type f TYPE = INTEGER (Given) * The data type associated with the column. See "Applicability:" * below. c ndim f NDIM = INTEGER (Given) * The number of dimensions spanned by the values stored in a single * cell of the column. Zero if the column holds scalar values. c dims f DIMS( NDIM ) = INTEGER (Given) * An array holding the the lengths of each of the axes spanned by * the values stored in a single cell of the column. Ignored if the * column holds scalara values. c unit f UNIT = CHARACTER * ( * ) (Given) * A string specifying the units of the column. Supply a blank * string if the column is unitless. f STATUS = INTEGER (Given and Returned) f The global status. * Applicability: * Table * Tables can hold columns with any of the following data types - * AST__INTTYPE (for integer), AST__SINTTYPE (for c short int), f INTEGER*2), * AST__BYTETYPE (for c unsigned bytes - i.e. unsigned chars), f bytes), * AST__DOUBLETYPE (for double * precision floating point), AST__FLOATTYPE (for single * precision floating point), AST__STRINGTYPE (for character string), * AST__OBJECTTYPE (for AST Object pointer), AST__POINTERTYPE (for * arbitrary C pointer) or AST__UNDEFTYPE (for undefined values * created by c astMapPutU). f AST_MAPPUTU). * FitsTable * FitsTables can hold columns with any of the following data types - * AST__INTTYPE (for integer), AST__SINTTYPE (for c short int), f INTEGER*2), * AST__BYTETYPE (for c unsigned bytes - i.e. unsigned chars), f bytes), * AST__DOUBLETYPE (for double * precision floating point), AST__FLOATTYPE (for single * precision floating point), AST__STRINGTYPE (for character string). * Notes: * - This c function f routine * returns without action if a column already exists in the Table * with the supplied name and properties. However an error is * reported if any of the properties differ. *-- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding all column details */ AstKeyMap *col_km; /* KeyMap holding new column details */ const char *oldunit; /* Pointer to the old coumn unit string */ int *olddims; /* Shape of pre-existing column */ int idim; /* Axis index */ int namlen; /* Used length of "name" */ int nval; /* Number of values returned */ int oldtype; /* Data type of pre-existing column */ /* Check the global error status. */ if ( !astOK ) return; /* Verify supplied values. */ namlen = astChrLen( name ); if( namlen == 0 ) { astError( AST__BADKEY, "astAddColumn(%s): Illegal blank column name " "supplied.", status, astGetClass( this ) ); } else if( namlen > AST__MXCOLNAMLEN ) { astError( AST__BADKEY, "astAddColumn(%s): Column name '%s' is too " "long (must be no more than %d characters).", status, astGetClass( this ), name, AST__MXCOLNAMLEN ); } else if( ndim < 0 ) { astError( AST__NAXIN, "astAddColumn(%s): No of axes (%d) for values in " "new column %s is invalid.", status, astGetClass( this ), ndim, name ); } else if( TypeString( type ) == NULL ) { astError( AST__NAXIN, "astAddColumn(%s): Bad data type supplied (%d) " "for new column %s.", status, astGetClass( this ), type, name ); } else { for( idim = 0; idim < ndim; idim++ ) { if( dims[ idim ] < 1 ) { astError( AST__DIMIN, "astAddColumn(%s): Length of axis %d (%d) " "for new column %s is invalid.", status, astGetClass( this ), idim + 1, dims[ idim ], name ); break; } } } /* If there is already a column with the given name, check its properties match the supplied properties. */ if( astOK ) { cols = astColumnProps( this ); if( astMapGet0A( cols, name, &col_km ) ) { astMapGet0I( col_km, TYPE, &oldtype ); if( oldtype != type && astOK ) { astError( AST__OLDCOL, "astAddColumn(%s): A column called " "%s already exists in the table with a different " "data type (%s).", status, astGetClass( this ), name, TypeString( oldtype ) ); } if( !astMapGet0C( col_km, UNIT, &oldunit ) ) oldunit = ""; if( strcmp( oldunit, unit ) && astOK ) { astError( AST__OLDCOL, "astAddColumn(%s): A column called " "%s already exists in the table with a different " "unit string ('%s').", status, astGetClass( this ), name, oldunit ); } if( ndim != astMapLength( col_km, SHAPE ) && astOK ) { astError( AST__OLDCOL, "astAddColumn(%s): A column called " "%s already exists in the table with a different " "number of axes (%d).", status, astGetClass( this ), name, astMapLength( col_km, SHAPE ) ); } if( ndim > 0 && astOK ) { olddims = astMalloc( sizeof( int )*ndim ); (void) astMapGet1I( col_km, SHAPE, ndim, &nval, olddims ); for( idim = 0; idim < ndim && astOK; idim++ ) { if( dims[ idim ] != olddims[ idim ] ) { astError( AST__OLDCOL, "astAddColumn(%s): A column called " "%s already exists in the table with a different " "shape.", status, astGetClass( this ), name ); } } olddims = astFree( olddims ); } /* Otherwise, add a new column to the table. */ } else { /* Add a suitable entry describing the column to the Columns KeyMap. */ col_km = astKeyMap( " ", status ); astMapPut0C( col_km, NAME, name, NULL ); astMapPut0I( col_km, TYPE, type, NULL ); if( ndim ) astMapPut1I( col_km, SHAPE, ndim, dims, NULL ); astMapPut0C( col_km, UNIT, unit, NULL ); /* Put the column KeyMap into the KeyMap holding details of all columns. Use the column name as the key. */ astMapPut0A( cols, name, col_km, NULL ); } /* Annul the local KeyMap pointers. */ col_km = astAnnul( col_km ); cols = astAnnul( cols ); } } static void AddParameter( AstTable *this, const char *name, int *status ) { /* *++ * Name: c astAddParameter f AST_ADDPARAMETER * Purpose: * Add a new global parameter definition to a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astAddParameter( AstTable *this, const char *name ) f CALL AST_ADDPARAMETER( THIS, NAME, STATUS ) * Class Membership: * Table method. * Description: * Adds the definition of a new global parameter to the supplied * table. Note, this does not store a value for the parameter. To get * or set the parameter value, the methods of the paremt KeyMap class * should be used, using the name of the parameter as the key. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c name f NAME = CHARACTER * ( * ) (Given) * The parameter name. Trailing spaces are ignored (all other spaces * are significant). The supplied string is converted to upper case. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Unlike columns, the definition of a parameter does not specify its type, * size or dimensionality. *-- */ /* Local Variables: */ AstKeyMap *pars; /* KeyMap holding all parameter details */ int namlen; /* Used length of "name" */ /* Check the global error status. */ if ( !astOK ) return; /* Verify supplied values. */ namlen = astChrLen( name ); if( namlen == 0 ) { astError( AST__BADKEY, "astAddParameter(%s): Illegal blank parameter name " "supplied.", status, astGetClass( this ) ); } else if( namlen > AST__MXCOLNAMLEN ) { astError( AST__BADKEY, "astAddParameter(%s): Parameter name '%s' is too " "long (must be no more than %d characters).", status, astGetClass( this ), name, AST__MXCOLNAMLEN ); } /* Do nothing if there is already a parameter with the given name. */ if( astOK ) { pars = astParameterProps( this ); if( !astMapHasKey( pars, name ) ) { /* Add a suitable entry to the Parameters KeyMap. The value is arbitrary and currently unused. */ astMapPut0I( pars, name, 1, NULL ); } /* Annul the local KeyMap pointer. */ pars = astAnnul( pars ); } } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void ClearAttrib( AstObject *this, const char *attrib ) * Class Membership: * Table member function (over-rides the astClearAttrib protected * method inherited from the KeyMap class). * Description: * This function clears the value of a specified attribute for a * Table, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Table. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. */ /* Local Variables: */ AstTable *this; int nc; int len; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Table structure. */ this = (AstTable *) this_object; /* Get the length of the attribute string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* None yet */ /* Define a macro to see if the attribute string matches any of the read-only column attributes of this class. */ #define MATCH(attr) \ ( nc = 0, ( 0 == astSscanf( attrib, attr "(%*s)%n", &nc ) ) && \ ( nc >= len ) ) /* 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. */ if ( !strcmp( attrib, "nrow" ) || !strcmp( attrib, "ncolumn" ) || !strcmp( attrib, "nparameter" ) || MATCH( "columnlenc" ) || MATCH( "columnlength" ) || MATCH( "columnndim" ) || MATCH( "columntype" ) || MATCH( "columnunit" ) ) { 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } #undef MATCH } static void ClearKeyCase( AstKeyMap *this, int *status ) { /* * Name: * ClearKeyCase * Purpose: * Clear the KeyCase attribute value for a Table. * Type: * Private function. * Synopsis: * #include "keymape.h" * void ClearKeyCase( AstKeyMap *this, int *status ) * Class Membership: * Table member function (over-rides the astClearKeyCase protected * method inherited from the KeyMap class). * Description: * This function clears the value of the KeyCase attribute for a * Table. For a Table, the KeyCase attribute cannot be changed so this * function exits without action. * Parameters: * this * Pointer to the Table. */ } static const char *ColumnName( AstTable *this, int index, int *status ) { /* *++ * Name: c astColumnName f AST_COLUMNNAME * Purpose: * Get the name of the column at a given index within the Table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c const char *astColumnName( AstTable *this, int index ) f RESULT = AST_COLUMNNAME( THIS, INDEX, STATUS ) * Class Membership: * Table method. * Description: * This function returns a string holding the name of the column with * the given index within the Table. * * This function is intended primarily as a means of iterating round all * the columns in a Table. For this purpose, the number of columns in * the Table is given by the Ncolumn attribute of the Table. This function * could then be called in a loop, with the index value going from c zero to one less than Ncolumn. f one to Ncolumn. * * Note, the index associated with a column decreases monotonically with * the age of the column: the oldest Column in the Table will have index * one, and the Column added most recently to the Table will have the * largest index. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c index f INDEX = INTEGER (Given) * The index into the list of columns. The first column has index * one, and the last has index "Ncolumn". f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astColumnName() c A pointer to a null-terminated string containing the f AST_COLUMNNAME = CHARACTER * ( AST__SZCHR ) f The * upper case column name. * Notes: c - The returned pointer is guaranteed to remain valid and the c string to which it points will not be over-written for a total c of 50 successive invocations of this function. After this, the c memory containing the string may be re-used, so a copy of the c string should be made if it is needed for longer than this. c - A NULL pointer will be returned if this function is invoked c with the AST error status set, or if it should fail for any c reason. f - A blank string will be returned if this function is invoked f with STATUS set to an error value, or if it should fail for any f reason. *-- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ const char *result; /* Check the global error status. */ if ( !astOK ) return NULL; /* Get apointer to the KeyMap holding all column definitions. */ cols = astColumnProps( this ); /* Issue a more useful error message than that issued by astMapKey if the index is invalid. */ if( index < 1 || index > astMapSize( cols ) ) { astError( AST__MPIND, "astColumnName(%s): Cannot find column " "%d (zero-based) of the %s - invalid index.", status, astGetClass( this ), index, astGetClass( this ) ); } /* Get the column name. */ result = astMapKey( cols, index - 1 ); /* Free resources. */ cols = astAnnul( cols ); /* Return a pointer to the required column name. */ return result; } static AstKeyMap *ColumnProps( AstTable *this, int *status ) { /* *+ * Name: * astColumnProps * Purpose: * Returns a pointer to the KeyMap holding column properties. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * AstKeyMap *astColumnProps( AstTable *this ) * Class Membership: * Table method. * Description: * This function returns a pointer to the KeyMap that holds * definitions of all the coumns added to the Table. * Parameters: * this * Pointer to the Table. * Returned Value: * A pointer to the KeyMap. It shpould be annulled using astAnnul * when no longer needed. *- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Return a cloned pointer to the required KeyMap. */ return astClone( this->columns ); } static void ColumnShape( AstTable *this, const char *column, int mxdim, int *ndim, int *dims, int *status ){ /* *++ * Name: c astColumnShape f AST_COLUMNSHAPE * Purpose: * Returns the shape of the values in a named column. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astColumnShape( AstTable *this, const char *column, int mxdim, c int *ndim, int *dims ) f CALL AST_COLUMNSHAPE( THIS, COLUMN, MXDIM, NDIM, DIMS, STATUS ) * Class Membership: * Table method. * Description: c This function f This routine * returns the number of dimensions spaned by each value in a named * column of a Table, together with the length of each dimension. * These are the values supplied when the column was created using c astAddColumn. f AST_ADDCOLUMN. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c column f COLUMN = CHARACTER * ( * ) (Given) * The character string holding the upper case name of the column. Trailing * spaces are ignored. c mxdim f MXDIM = INTEGER (Given) * The length of the c "dims" array. f DIMS array. c ndim f NDIM = INTEGER (Returned) c Pointer to an int in which to return the f The * number of dimensions spanned by values in the named column. * This will be zero if the column contains scalar values. c dims f DIMS( MXDIM ) = INTEGER (Returned) c Pointer to an f An * array in which to return the length of each dimension. Any * excess trailing elements will be filled with the value 1. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - No error is reported if the requested column cannot be found in the * given Table. A value of zero is returned for c "ndim" and the supplied values in "dims" f NDIM and the supplied values in DIMS * are left unchanged. * - A value of zero is returned for c "ndim" f NDIM * if an error occurs. *-- */ /* Local Variables: */ AstKeyMap *cols; /* Pointer to KeyMap holding all column info */ AstKeyMap *col_km; /* Pointer to KeyMap holding requested column info */ int idim; /* Axis index */ /* Initialise */ *ndim = 0; /* Check the inherited status. */ if( !astOK ) return; /* Get the KeyMap holding information about the requested column. */ cols = astColumnProps( this ); if( astMapGet0A( cols, column, &col_km ) ) { /* Get the shape of the column values. */ (void) astMapGet1I( col_km, SHAPE, mxdim, ndim, dims ); /* Fill excess array elements with 1. */ for( idim = *ndim; idim < mxdim; idim++ ) dims[ idim ] = 1; /* Free resources. */ col_km = astAnnul( col_km ); } cols = astAnnul( cols ); /* If an error has occurred, set ndim to zero. */ if( !astOK ) *ndim = 0; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Tables are equivalent. * Type: * Private function. * Synopsis: * #include "table.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * Table member function (over-rides the astEqual protected * method inherited from the astKeyMap class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Tables are equivalent. * Parameters: * this * Pointer to the first Object (a Table). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the Tables are equivalent, zero otherwise. * 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: */ AstKeyMap *this_km; AstKeyMap *that_km; AstTable *that; AstTable *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two Table structures. */ this = (AstTable *) this_object; that = (AstTable *) that_object; /* Check the second object is a Table. We know the first is a Table since we have arrived at this implementation of the virtual function. */ if( astIsATable( that ) ) { /* Check the Tables are equal when compared as KeyMaps. */ if( (*parent_equal)( this_object, that_object, status ) ) { /* Check the Columns KeyMaps are equal. */ this_km = astColumnProps( this ); that_km = astColumnProps( that ); result = astEqual( this_km, that_km ); this_km = astAnnul( this_km ); that_km = astAnnul( that_km ); /* Check the Parameter KeyMaps are equal. */ this_km = astParameterProps( this ); that_km = astParameterProps( that ); result = astEqual( this_km, that_km ); this_km = astAnnul( this_km ); that_km = astAnnul( that_km ); } } /* 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 Table. * Type: * Private function. * Synopsis: * #include "table.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Table member function (over-rides the protected astGetAttrib * method inherited from the KeyMap class). * Description: * This function returns a pointer to the value of a specified * attribute for a Table, formatted as a character string. * Parameters: * this * Pointer to the Table. * 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 Table, 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 Table. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char cname[ AST__MXCOLNAMLEN + 1 ]; /* Column name */ AstTable *this; /* Pointer to the Table structure */ const char *result; /* Pointer value to return */ int ival; /* Int attribute value */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Table structure. */ this = (AstTable *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* Table properties */ /* ================ */ /* Ncolumn */ /* ------- */ if( !strcmp( attrib, "ncolumn" ) ) { ival = astGetNcolumn( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Nrow */ /* ---- */ } else if( !strcmp( attrib, "nrow" ) ) { ival = astGetNrow( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Nparameter */ /* ---------- */ } else if( !strcmp( attrib, "nparameter" ) ) { ival = astGetNparameter( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Column properties */ /* ================= */ /* A macro that gives the scannf pattern to test for a given column property. Needed since the buffer length is defined by a macro (AST__MXCOLNAMLEN). */ #define PATTERN(cnam,blen) #cnam "(%" STRING(blen) "[^()])%n" /* ColumnNdim */ } else if ( nc = 0, ( 1 == astSscanf( attrib, PATTERN(columnndim,AST__MXCOLNAMLEN), cname, &nc ) ) && ( nc >= len ) ) { ival = astGetColumnNdim( this, cname ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ColumnLenC */ } else if ( nc = 0, ( 1 == astSscanf( attrib, PATTERN(columnlenc,AST__MXCOLNAMLEN), cname, &nc ) ) && ( nc >= len ) ) { ival = astGetColumnLenC( this, cname ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ColumnType */ } else if ( nc = 0, ( 1 == astSscanf( attrib, PATTERN(columntype,AST__MXCOLNAMLEN), cname, &nc ) ) && ( nc >= len ) ) { ival = astGetColumnType( this, cname ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ColumnLength */ } else if ( nc = 0, ( 1 == astSscanf( attrib, PATTERN(columnlength,AST__MXCOLNAMLEN), cname, &nc ) ) && ( nc >= len ) ) { ival = astGetColumnLength( this, cname ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ColumnUnit */ } else if ( nc = 0, ( 1 == astSscanf( attrib, PATTERN(columnunit,AST__MXCOLNAMLEN), cname, &nc ) ) && ( nc >= len ) ) { result = astGetColumnUnit( this, cname ); #undef PATTERN /* Unknown attributes */ /* ================== */ /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetColumnLenC( AstTable *this, const char *column, int *status ) { /* *+ * Name: * astGetColumnLenC * Purpose: * Get the maximum formatted length of any value in a column. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetColumnLenC( AstTable *this, const char *column ) * Class Membership: * Table method. * Description: * This function returns the minimum length which a character variable * must have in order to be able to store the longest value currently * present (at any row) in a specified column of the supplied Table. If * the named column holds vector values, then the returned value is * the length of the longest element of the vector value. * Parameters: * this * Pointer to the Table. * column * The character string holding the upper-case name of the column. * Trailing spaces are ignored. An error is reported if the supplied * column is not found in the Table. * Returned Value: * The length (i.e. number of characters) of the longest formatted * value associated with the named column. This does not include the * trailing null character. * Notes: * - Automatic data type conversion occurs if the named column holds * numerical values. * - An error will be reported if named column does not exist or cannot * be formatted as a character * string. * - A function value of zero will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ char key[ AST__MXCOLKEYLEN ]; /* Current cell key string */ int irow; /* Current row index */ int len; /* Length needed to format current cell */ int nrow; /* Number of rows in table */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get the KeyMap holding information about all columns. */ cols = astColumnProps( this ); /* Check the table contains the requested column. */ if( astMapHasKey( cols, column ) ) { /* Loop round all rows in the table. */ nrow = astGetNrow( this ); for( irow = 1; irow <= nrow; irow++ ) { /* Format the cell name. */ sprintf( key, "%.*s(%d)", (int) astChrLen(column), column, irow ); /* Get the maximum length needed to format a string in the current row/column. */ len = astMapLenC( this, key ); /* Return the largest value found for any row. */ if( len > result ) result = len; } /* Report an error if the column does not exist. */ } else if( astOK ) { astError( AST__BADCOL, "astGetColumnLenC(%s): No column named '%s' " "exists in the table.", status, astGetClass( this ), column ); } /* Free resources */ cols = astAnnul( cols ); /* Return AST__BADTYPE if an error occurred. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static int GetColumnLength( AstTable *this, const char *column, int *status ) { /* *+ * Name: * astGetColumnLength * Purpose: * Get the number of elements in each value in a column. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetColumnLength( AstTable *this, const char *column ) * Class Membership: * Table method. * Description: * This function returns the number of elements in each value stored * in a named column. Each value can be a scalar (in which case the * ColumnLength attribute has a value of 1), or a multi-dimensional * array ( in which case the ColumnLength value is equal to the * product of the array dimensions). * Parameters: * this * Pointer to the Table. * column * The character string holding the upper-case name of the column. * Trailing spaces are ignored. An error is reported if the supplied * column is not found in the Table. * Returned Value: * The number of elements in each column value. * Notes: * - An error will be reported if named column does not exist or cannot * be formatted as a character * string. * - A function value of zero will be returned if an error has already * occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ AstKeyMap *col_km; /* KeyMap holding requested column definition */ AstKeyMap *cols; /* KeyMap holding all column definitions */ int *dims; /* Pointer to array holding dimensions */ int idim; /* Index of dimension */ int ndim; /* Number of dimensions */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get the KeyMap holding information about all columns. */ cols = astColumnProps( this ); /* Get the KeyMap holding information about the requested column. */ if( astMapGet0A( cols, column, &col_km ) ) { /* If the Column properties includes the length, return it. Otherwise, calculate the length and store it in the KeyMap as a column property. */ if( ! astMapGet0I( col_km, LENGTH, &result ) ) { /* Get the number of axes spanned by each column value, and allocate an array big enough to hold the dimensions of these axes. */ ndim = astMapLength( col_km, SHAPE ); dims = astMalloc( sizeof( int )*ndim ); if( astOK ) { /* Get the dimensions. */ astMapGet1I( col_km, SHAPE, ndim, &ndim, dims ); /* Find the number of elements. */ result = 1; for( idim = 0; idim < ndim; idim++ ) { result *= dims[ idim ]; } /* Store the result in the column KeyMap. */ astMapPut0I( col_km, LENGTH, result, NULL ); } dims = astFree( dims ); } /* Free resources */ col_km = astAnnul( col_km ); /* Report an error if the column does not exist. */ } else if( astOK ) { astError( AST__BADCOL, "astGetColumnLength(%s): No column named '%s' " "exists in the table.", status, astGetClass( this ), column ); } /* Free resources */ cols = astAnnul( cols ); /* Return AST__BADTYPE if an error occurred. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static int GetColumnNdim( AstTable *this, const char *column, int *status ) { /* *+ * Name: * astGetColumnNdim * Purpose: * Get the number of dimensions for a column in a Table. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetColumnNdim( AstTable *this, const char *column ) * Class Membership: * Table method. * Description: * This function attribute holds the number of axes spanned by each value * in a column. If each cell in the column is a scalar, ColumnNdim will * be zero. If each cell in the column is a 1D spectrum, ColumnNdim will * be one. If each cell in the column is a 2D image, ColumnNdim will be * two, etc. * Parameters: * this * Pointer to the Table. * column * The character string holding the upper-case name of the column. * Trailing spaces are ignored. An error is reported if the supplied * column is not found in the Table. * Returned Value: * The number of dimensions - zero for a scalar. * Notes: * - A function value of zero will be returned if an error has * already occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ AstKeyMap *col_km; /* Pointer to KeyMap holding column info */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get the KeyMap holding information about all columns. */ cols = astColumnProps( this ); /* Get the KeyMap holding information about the requested column. */ if( astMapGet0A( cols, column, &col_km ) ) { /* Get the number of dimensions. */ result = astMapLength( col_km, SHAPE ); /* Free resources */ col_km = astAnnul( col_km ); /* Report an error if the column does not exist. */ } else if( astOK ) { astError( AST__BADCOL, "astGetColumnNdim(%s): No column named '%s' " "exists in the table.", status, astGetClass( this ), column ); } cols = astAnnul( cols ); /* Return AST__BADTYPE if an error occurred. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static int GetColumnType( AstTable *this, const char *column, int *status ) { /* *+ * Name: * astGetColumnType * Purpose: * Get the data type of a column in a Table. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetColumnType( AstTable *this, const char *column ) * Class Membership: * Table method. * Description: * This function returns a value indicating the data type of a * named column in a Table. This is the data type which was used * when the column was added to the Table using astAddColumn. * Parameters: * this * Pointer to the Table. * column * The character string holding the upper-case name of the column. * Trailing spaces are ignored. An error is reported if the supplied * column is not found in the Table. * Returned Value: * One of AST__INTTYPE (for integer), AST__SINTTYPE (for short int), * AST__BYTETYPE (for unsigned bytes - i.e. unsigned chars), * AST__DOUBLETYPE (for double precision floating point), * AST__FLOATTYPE (for single precision floating point), AST__STRINGTYPE * (for character string), AST__OBJECTTYPE (for AST Object pointer), * AST__POINTERTYPE (for arbitrary C pointer) or AST__UNDEFTYPE (for * undefined values created by astMapPutU). * Notes: * - A function value of AST__BADTYPE will be returned if an error has * already occurred, or if this function should fail for any reason. *- */ /* Local Variables: */ AstKeyMap *cols; /* Pointer to KeyMap holding all column info */ AstKeyMap *col_km; /* Pointer to KeyMap holding requested column info */ int result; /* Returned value */ /* Initialise */ result = AST__BADTYPE; /* Check the global error status. */ if ( !astOK ) return result; /* Get the KeyMap holding information about the requested column. */ cols = astColumnProps( this ); if( astMapGet0A( cols, column, &col_km ) ) { /* Get the column data type. */ (void) astMapGet0I( col_km, TYPE, &result ); /* Annul the KeyMap pointer. */ col_km = astAnnul( col_km ); /* Report an error if the column does not exist. */ } else if( astOK ) { astError( AST__BADCOL, "astGetColumnType(%s): No column named '%s' " "exists in the table.", status, astGetClass( this ), column ); } cols = astAnnul( cols ); /* Return AST__BADTYPE if an error occurred. */ if( !astOK ) result = AST__BADTYPE; /* Return the result. */ return result; } static const char *GetColumnUnit( AstTable *this, const char *column, int *status ) { /* *+ * Name: * astGetColumnUnit * Purpose: * Get the unit string for a column in a Table. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * const char *astGetColumnUnit( AstTable *this, const char *column ) * Class Membership: * Table method. * Description: * This function returns the unit string for a named column in a Table. * This is the unit string that was provided when the column was added to * the Table using astAddColumn. * Parameters: * this * Pointer to the Table. * column * The character string holding the upper-case name of the column. * Trailing spaces are ignored. An error is reported if the supplied * column is not found in the Table. * Returned Value: * A pointer to a null-terminated string containing the column units. *- */ /* Local Variables: */ AstKeyMap *col_km; /* Pointer to KeyMap holding requested column info */ AstKeyMap *cols; /* Pointer to KeyMap holding all column info */ const char *result; /* Returned value */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the KeyMap holding information about the requested column. */ cols = astColumnProps( this ); if( astMapGet0A( cols, column, &col_km ) ) { /* Get the column unit string. */ (void) astMapGet0C( col_km, UNIT, &result ); /* Annul the KeyMap pointer. */ col_km = astAnnul( col_km ); /* Report an error if the column does not exist. */ } else if( astOK ) { astError( AST__BADCOL, "astGetColumnUnit(%s): No column named '%s' " "exists in the table.", status, astGetClass( this ), column ); } cols = astAnnul( cols ); /* Return NULL if an error occurred. */ if( !astOK ) result = NULL; /* Return the result. */ return result; } static int GetNcolumn( AstTable *this, int *status ) { /* *+ * Name: * astGetNcolumn * Purpose: * Get the number of columns in a Table. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetNcolumn( AstTable *this ) * Class Membership: * Table method. * Description: * This function returns the number of columns currently in the Table. * Parameters: * this * Pointer to the Table. * Returned Value: * Number of columns. * 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: */ AstKeyMap *cols; int result; /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the KeyMap holding the column definitions. */ cols = astColumnProps( this ); /* Get the number of column definitions in the KeyMap. */ result = astMapSize( cols ); /* Annul the KeyMap pointer. */ cols = astAnnul( cols ); /* Return the result. */ return result; } static int GetNparameter( AstTable *this, int *status ) { /* *+ * Name: * astGetNparameter * Purpose: * Get the number of global parameters in a Table. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * int astGetNparameter( AstTable *this ) * Class Membership: * Table method. * Description: * This function returns the number of global parameters currently in the Table. * Parameters: * this * Pointer to the Table. * Returned Value: * Number of parameters. * 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: */ AstKeyMap *pars; int result; /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the KeyMap holding the parameter definitions. */ pars = astParameterProps( this ); /* Get the number of parameter definitions in the KeyMap. */ result = astMapSize( pars ); /* Annul the KeyMap pointer. */ pars = astAnnul( pars ); /* Return the result. */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "table.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Table member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Tables, * in bytes. * Parameters: * this * Pointer to the Table. * status * Pointer to the inherited status variable. * Returned Value: * The Table 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: */ AstKeyMap *km; /* KeyMap holding column/parameter definitions */ AstTable *this; /* Pointer to Table structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Table structure. */ this = (AstTable *) this_object; /* Invoke the GetObjSize method inherited from the parent KeyMap class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); km = astColumnProps( this ); result += astGetObjSize( km ); km = astAnnul( km ); km = astParameterProps( this ); result += astGetObjSize( km ); km = astAnnul( km ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int HasColumn( AstTable *this, const char *column, int *status ){ /* *++ * Name: c astHasColumn f AST_HASCOLUMN * Purpose: * Returns a flag indicating if a column is present in a Table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c int astHasColumn( AstTable *this, const char *column ) f RESULT = AST_HASCOLUMN( THIS, COLUMN, STATUS ) * Class Membership: * Table method. * Description: c This function f This routine * returns a flag indicating if a named column exists in a Table, for * instance, by having been added to to the Table using c astAddColumn. f AST_ADDCOLUMN. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c column f COLUMN = CHARACTER * ( * ) (Given) * The character string holding the upper case name of the column. Trailing * spaces are ignored. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - A value of c zero f .FALSE. * is returned for if an error occurs. *-- */ /* Local Variables: */ AstKeyMap *cols; int result; /* Initialise */ result = 0; /* Check the inherited status. */ if( !astOK ) return result; /* Get the KeyMap holding information about all columns. */ cols = astColumnProps( this ); /* Seeif it contains an entry for the named column. */ result = astMapHasKey( cols, column ); /* Free resources. */ cols = astAnnul( cols ); /* If an error has occurred, return zero. */ if( !astOK ) result = 0; return result; } static int HasParameter( AstTable *this, const char *parameter, int *status ){ /* *++ * Name: c astHasParameter f AST_HASPARAMETER * Purpose: * Returns a flag indicating if a named global parameter is present in a Table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c int astHasParameter( AstTable *this, const char *parameter ) f RESULT = AST_HASPARAMETER( THIS, PARAMETER, STATUS ) * Class Membership: * Table method. * Description: c This function f This routine * returns a flag indicating if a named parameter exists in a Table, for * instance, by having been added to to the Table using c astAddParameter. f AST_ADDPARAMETER. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c parameter f PARAMETER = CHARACTER * ( * ) (Given) * The character string holding the upper case name of the parameter. Trailing * spaces are ignored. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - A value of c zero f .FALSE. * is returned for if an error occurs. *-- */ /* Local Variables: */ AstKeyMap *pars; int result; /* Initialise */ result = 0; /* Check the inherited status. */ if( !astOK ) return result; /* Get the KeyMap holding information about all parameters. */ pars = astParameterProps( this ); /* See if it contains an entry for the named parameter. */ result = astMapHasKey( pars, parameter ); /* Free resources. */ pars = astAnnul( pars ); /* If an error has occurred, return zero. */ if( !astOK ) result = 0; return result; } void astInitTableVtab_( AstTableVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTableVtab * Purpose: * Initialise a virtual function table for a Table. * Type: * Protected function. * Synopsis: * #include "table.h" * void astInitTableVtab( AstTableVtab *vtab, const char *name ) * Class Membership: * Table vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Table class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstKeyMapVtab *keymap; /* Pointer to KeyMap 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. */ astInitKeyMapVtab( (AstKeyMapVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsATable) 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 = &(((AstKeyMapVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->AddColumn = AddColumn; vtab->AddParameter = AddParameter; vtab->ColumnName = ColumnName; vtab->ParameterName = ParameterName; vtab->ColumnProps = ColumnProps; vtab->ColumnShape = ColumnShape; vtab->GetColumnLenC = GetColumnLenC; vtab->GetColumnLength = GetColumnLength; vtab->GetColumnNdim = GetColumnNdim; vtab->GetColumnType = GetColumnType; vtab->GetColumnUnit = GetColumnUnit; vtab->GetNcolumn = GetNcolumn; vtab->GetNparameter = GetNparameter; vtab->GetNrow = GetNrow; vtab->HasColumn = HasColumn; vtab->HasParameter = HasParameter; vtab->ParameterProps = ParameterProps; vtab->PurgeRows = PurgeRows; vtab->RemoveColumn = RemoveColumn; vtab->RemoveParameter = RemoveParameter; vtab->RemoveRow = RemoveRow; vtab->SetNrow = SetNrow; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; keymap = (AstKeyMapVtab *) vtab; parent_equal = object->Equal; object->Equal = Equal; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_mapremove = keymap->MapRemove; /* Define convenience macros for overriding methods inherited from the parent KeyMap class using all data type supported by KeyMap. */ #define OVERRIDE(method,code,methodlc,codelc) \ parent_##methodlc##codelc = keymap->method##code; \ keymap->method##code = method##code; \ #define OVERRIDE_METHOD(method,methodlc) \ OVERRIDE(method,A,methodlc,a) \ OVERRIDE(method,P,methodlc,p) \ OVERRIDE(method,C,methodlc,c) \ OVERRIDE(method,D,methodlc,d) \ OVERRIDE(method,F,methodlc,f) \ OVERRIDE(method,I,methodlc,i) \ OVERRIDE(method,S,methodlc,s) \ OVERRIDE(method,B,methodlc,b) /* Use these macros to override the required methods. */ OVERRIDE_METHOD(MapPut0,mapput0) OVERRIDE_METHOD(MapGet0,mapget0) OVERRIDE_METHOD(MapPut1,mapput1) OVERRIDE_METHOD(MapGet1,mapget1) OVERRIDE_METHOD(MapPutElem,mapputelem) OVERRIDE_METHOD(MapGetElem,mapgetelem) OVERRIDE(MapPut,U,mapput,u) OVERRIDE(SetKeyCase,,setkeycase,) OVERRIDE(ClearKeyCase,,clearkeycase,) /* Remove the macros. */ #undef OVERRIDE_METHOD #undef OVERRIDE /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "Table", "Two-dimensional table of data values" ); /* 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) ); } } #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: * Table 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: */ AstTable *this; /* Pointer to Table structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Table structure. */ this = (AstTable *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result && this->columns ) result = astManageLock( this->columns, mode, extra, fail ); if( !result && this->parameters ) result = astManageLock( this->parameters, mode, extra, fail ); /* Return the result. */ return result; } #endif /* * Name: * MapGet0 * Purpose: * Get a scalar value from a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int MapGet0( AstKeyMap *this, const char *key, type *value ); * Class Membership: * Table member function (over-rides the astMapGet0 method inherited * from the KeyMap class). * Description: * This is a set of functions for retrieving a scalar value from a * cell of a Table. You should replace in the generic function name * MapGet0 by an appropriate 1-character type code (see the "Data * Type Codes" section in the astMapGet0 docs). The stored value is * converted to the data type indiced by before being returned (an * error is reported if it is not possible to convert the stored value * to the requested data type). * Parameters: * this * Pointer to the Table. * key * A character string identifying the cell from which the value is * to be retrieved. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * value * A pointer to a buffer in which to return the requested value. * If the requested cell is not found, or if it is found but has an * undefined value (see astMapPutU), then the contents of the buffer * on entry to this function will be unchanged on exit. For pointer * types ("A" and "C"), the buffer should be a suitable pointer, and * the address of this pointer should be supplied as the "value" * parameter. * status * Pointer to inherited status value. * Returned Value: * A non-zero value is returned if the requested key name was found, and * does not have an undefined value (see astMapPutU). Zero is returned * otherwise. * Notes: * - No error is reported if the requested cell cannot be found in the * given KeyMap, but a zero value will be returned as the function value. * The supplied buffer will be returned unchanged. * - Key names are case insensitive, and white space is considered * significant. * - If the stored value is a vector value, then the first value in * the vector will be returned. * - A string pointer returned by astMapGet0C is guaranteed to remain * valid and the string to which it points will not be over-written for * a total of 50 successive invocations of this function. After this, * the memory containing the string may be re-used, so a copy of * the string should be made if it is needed for longer than this. * - If the returned value is an AST Object pointer, the Object's reference * count is incremented by this call. Any subsequent changes made to * the Object using the returned pointer will be reflected in any * any other active pointers for the Object. The returned pointer * should be annulled using astAnnul when it is no longer needed. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_MAPGET0(X,Xlc,Xtype,Itype) \ static int MapGet0##X( AstKeyMap *this_keymap, const char *key, Xtype *value, \ int *status ) { \ \ /* Local Variables: */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ int result; /* Returned flag */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to get the value of hte parameter. */ \ if( astHasParameter( this, key ) ) { \ result = (*parent_mapget0##Xlc)( this_keymap, key, value, status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, astGetKeyError( this ), colname, &irow, \ NULL, "astMapGet0" #X, status ) ) { \ \ /* If the row index is larger than the current number of rows in the \ table, do nothing more. */ \ if( irow <= astGetNrow( this ) ){ \ \ /* Use the astMapGet0 method in the parent keyMap class to get the \ cell contents. */ \ result = (*parent_mapget0##Xlc)( this_keymap, key, value, status ); \ } \ } \ \ /* If an error occurred, return zero. */ \ if( !astOK ) result = 0; \ \ /* Return the result.*/ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPGET0(I,i,int,AST__INTTYPE) MAKE_MAPGET0(D,d,double,AST__DOUBLETYPE) MAKE_MAPGET0(F,f,float,AST__FLOATTYPE) MAKE_MAPGET0(C,c,const char *,AST__STRINGTYPE) MAKE_MAPGET0(A,a,AstObject *,AST__OBJECTTYPE) MAKE_MAPGET0(P,p,void *,AST__POINTERTYPE) MAKE_MAPGET0(S,s,short int,AST__SINTTYPE) MAKE_MAPGET0(B,b,unsigned char,AST__BYTETYPE) /* Undefine the macro. */ #undef MAKE_MAPGET0 /* * Name: * MapGet1 * Purpose: * Get a vector value from a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int MapGet1( AstKeyMap *this, const char *key, int mxval, * int *nval, type *value ) * int MapGet1C( AstKeyMap *this, const char *key, int l, int mxval, * int *nval, const char *value ) * Class Membership: * Table member function (over-rides the astMapGet1 method inherited * from the KeyMap class). * Description: * This is a set of functions for retrieving a vector value from a * cell of a Table. You should replace in the generic function name * MapGet1 by an appropriate 1-character type code (see the "Data * Type Codes" section in the astMapGet1 docs). The stored value is * converted to the data type indiced by before being returned (an * error is reported if it is not possible to convert the stored value * to the requested data type). * * Note, the MapGet1C function has an extra parameter "l" which * specifies the maximum length of each string to be stored in the * "value" buffer (see the "astMapGet1C" docs). * Parameters: * this * Pointer to the Table. * key * A character string identifying the cell from which the value is * to be retrieved. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * mxval * The number of elements in the "value" array. * nval * The address of an integer in which to put the number of elements * stored in the "value" array. Any unused elements of the array are * left unchanged. * value * A pointer to an array in which to return the requested values. * If the requested cell is not found, or if it is found but has an * undefined value (see astMapPutU), then the contents of the buffer * on entry to this function will be unchanged on exit. * status * Pointer to inherited status value. * Returned Value: * A non-zero value is returned if the requested key name was found, and * does not have an undefined value (see astMapPutU). Zero is returned * otherwise. * MapGet1C: * The "value" buffer supplied to the MapGet1C function should be a * pointer to a character array with "mxval*l" elements, where "l" is * the maximum length of a string to be returned. The value of "l" * should be supplied as an extra parameter following "key" when * invoking MapGet1C, and should include space for a terminating * null character. * Notes: * - No error is reported if the requested cell cannot be found in the * given KeyMap, but a zero value will be returned as the function value. * The supplied buffer will be returned unchanged. * - Key names are case insensitive, and white space is considered * significant. * - If the stored value is a scalar value, then the value will be * returned in the first element of the supplied array, and "nval" * will be returned set to 1. */ /* Define a macro to implement the function for a specific data type (excluding "C" since that needs an extra parameter). */ #define MAKE_MAPGET1(X,Xlc,Xtype,Itype) \ static int MapGet1##X( AstKeyMap *this_keymap, const char *key, int mxval, int *nval, \ Xtype *value, int *status ) { \ \ /* Local Variables: */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ int result; /* Returned flag */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to get the value of hte parameter. */ \ if( astHasParameter( this, key ) ) { \ result = (*parent_mapget1##Xlc)( this_keymap, key, mxval, nval, \ value, status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, astGetKeyError( this ), colname, &irow, \ NULL, "astMapGet1" #X, status ) ) { \ \ /* If the row index is larger than the current number of rows in the \ table, do nothing more. */ \ if( irow <= astGetNrow( this ) ){ \ \ /* Use the astMapGet1 method in the parent keyMap class to get the \ cell contents. */ \ result = (*parent_mapget1##Xlc)( this_keymap, key, mxval, nval, \ value, status ); \ } \ } \ \ /* If an error occurred, return zero. */ \ if( !astOK ) result = 0; \ \ /* Return the result.*/ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPGET1(I,i,int,AST__INTTYPE) MAKE_MAPGET1(D,d,double,AST__DOUBLETYPE) MAKE_MAPGET1(F,f,float,AST__FLOATTYPE) MAKE_MAPGET1(A,a,AstObject *,AST__OBJECTTYPE) MAKE_MAPGET1(P,p,void *,AST__POINTERTYPE) MAKE_MAPGET1(S,s,short int,AST__SINTTYPE) MAKE_MAPGET1(B,b,unsigned char,AST__BYTETYPE) /* Undefine the macro. */ #undef MAKE_MAPGET1 static int MapGet1C( AstKeyMap *this_keymap, const char *key, int l, int mxval, int *nval, char *value, int *status ) { /* * Name: * MapGet1C * Purpose: * Get a vector value from a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int MapGet1C( AstKeyMap *this, const char *key, int l, int mxval, * int *nval, const char *value ) * Class Membership: * Table member function (over-rides the astMapGet1C method inherited * from the KeyMap class). * Description: * This is the implementation of MapGet1 for = "C". We * cannot use the MAKE_MAPGET1 macro for this because the string * version of this function has an extra parameter giving the maximum * length of each string which can be stored in the supplied buffer. * Parameters: * (see MapGet1) */ /* Local Variables: */ AstTable *this; /* Pointer to Table structure */ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ int irow; /* Row index within key string */ int result; /* Returned flag */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Table structure. */ this = (AstTable *) this_keymap; /* If the key is the name of a global table parameter, use the parent method to get the value of hte parameter. */ if( astHasParameter( this, key ) ) { result = (*parent_mapget1c)( this_keymap, key, l, mxval, nval, value, status ); /* Check the supplied key looks like a table cell key, and get the the column name and the row number. Also checks that the table contains a column with the specified name. */ } else if( ParseKey( this, key, astGetKeyError( this ), colname, &irow, NULL, "astMapGet1C", status ) ) { /* If the row index is larger than the current number of rows in the table, do nothing more. */ if( irow <= astGetNrow( this ) ){ /* Use the astMapGet1 method in the parent keyMap class to get the cell contents. */ result = (*parent_mapget1c)( this_keymap, key, l, mxval, nval, value, status ); } } /* If an error occurred, return zero. */ if( !astOK ) result = 0; /* Return the result.*/ return result; } /* * Name: * MapGetElem * Purpose: * Get a single element of a vector value from a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int MapGetElem( AstKeyMap *this, const char *key, int elem, * type *value, int *status ) * int MapGetElemC( AstKeyMap *this, const char *key, int l, int elem, * char *value, int *status ) * Class Membership: * Table member function (over-rides the astMapGetElem method inherited * from the KeyMap class). * Description: * This is a set of functions for retrieving a single element of a vector * value from a cell of a Table. You should replace in the generic * function name MapGetElem by an appropriate 1-character type code * (see the "Data Type Codes" section in the astMapGetElem docs). The * stored value is converted to the data type indiced by before being * returned (an error is reported if it is not possible to convert the * stored value to the requested data type). * * Note, the MapGetElemC function has an extra parameter "l" which * specifies the maximum length of each string to be stored in the * "value" buffer (see the "MapGetElemC" docs). * Parameters: * this * Pointer to the Table. * key * A character string identifying the cell from which the value is * to be retrieved. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * elem * The index of the vector element to modify, starting at zero. * If the index is outside the range of the vector, an error will * be reported. * value * A pointer to a buffer in which to return the requested values. * If the requested cell is not found, or if it is found but has an * undefined value (see astMapPutU), then the contents of the buffer * on entry to this function will be unchanged on exit. * status * Pointer to inherited status value. * Returned Value: * A non-zero value is returned if the requested key name was found, and * does not have an undefined value (see astMapPutU). Zero is returned * otherwise. * MapGetElemC: * The "value" buffer supplied to the MapGetElemC function should be a * pointer to a character array with "l" elements, where "l" is * the maximum length of a string to be returned. The value of "l" * should be supplied as an extra parameter following "key" when * invoking MapGetElemC, and should include space for a terminating * null character. * Notes: * - No error is reported if the requested cell cannot be found in the * given KeyMap, but a zero value will be returned as the function value. * The supplied buffer will be returned unchanged. * - Key names are case insensitive, and white space is considered * significant. * - If the stored value is a scalar value, then the value will be * returned in the first element of the supplied array, and "nval" * will be returned set to 1. */ /* Define a macro to implement the function for a specific data type (excluding "C" since that needs an extra parameter). */ #define MAKE_MAPGETELEM(X,Xlc,Xtype,Itype) \ static int MapGetElem##X( AstKeyMap *this_keymap, const char *key, int elem, \ Xtype *value, int *status ) { \ \ /* Local Variables: */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ int result; /* Returned flag */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to get the value of hte parameter. */ \ if( astHasParameter( this, key ) ) { \ result = (*parent_mapgetelem##Xlc)( this_keymap, key, elem, \ value, status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, astGetKeyError( this ), colname, &irow, \ NULL, "astMapGetElem" #X, status ) ) { \ \ /* If the row index is larger than the current number of rows in the \ table, do nothing more. */ \ if( irow <= astGetNrow( this ) ){ \ \ /* Use the astMapGetElem method in the parent keyMap class to get the \ cell contents. */ \ result = (*parent_mapgetelem##Xlc)( this_keymap, key, elem, \ value, status ); \ } \ } \ \ /* If an error occurred, return zero. */ \ if( !astOK ) result = 0; \ \ /* Return the result.*/ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPGETELEM(I,i,int,AST__INTTYPE) MAKE_MAPGETELEM(D,d,double,AST__DOUBLETYPE) MAKE_MAPGETELEM(F,f,float,AST__FLOATTYPE) MAKE_MAPGETELEM(A,a,AstObject *,AST__OBJECTTYPE) MAKE_MAPGETELEM(P,p,void *,AST__POINTERTYPE) MAKE_MAPGETELEM(S,s,short int,AST__SINTTYPE) MAKE_MAPGETELEM(B,b,unsigned char,AST__BYTETYPE) /* Undefine the macro. */ #undef MAKE_MAPGETELEM static int MapGetElemC( AstKeyMap *this_keymap, const char *key, int l, int elem, char *value, int *status ) { /* * Name: * MapGetElemC * Purpose: * Get a single element of a vector value from a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int MapGetElemC( AstKeyMap *this, const char *key, int l, int elem, * char *value, int *status ) * Class Membership: * Table member function (over-rides the astMapGetElemC method inherited * from the KeyMap class). * Description: * This is the implementation of MapGetElem for = "C". We * cannot use the MAKE_MAPGETELEM macro for this because the string * version of this function has an extra parameter giving the maximum * length of each string which can be stored in the supplied buffer. * Parameters: * (see MapGetElem) */ /* Local Variables: */ AstTable *this; /* Pointer to Table structure */ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ int irow; /* Row index within key string */ int result; /* Returned flag */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Table structure. */ this = (AstTable *) this_keymap; /* If the key is the name of a global table parameter, use the parent method to get the value of hte parameter. */ if( astHasParameter( this, key ) ) { result = (*parent_mapgetelemc)( this_keymap, key, l, elem, value, status ); /* Check the supplied key looks like a table cell key, and get the the column name and the row number. Also checks that the table contains a column with the specified name. */ } else if( ParseKey( this, key, astGetKeyError( this ), colname, &irow, NULL, "astMapGetElemC", status ) ) { /* If the row index is larger than the current number of rows in the table, do nothing more. */ if( irow <= astGetNrow( this ) ){ /* Use the astMapGetElem method in the parent keyMap class to get the cell contents. */ result = (*parent_mapgetelemc)( this_keymap, key, l, elem, value, status ); } } /* If an error occurred, return zero. */ if( !astOK ) result = 0; /* Return the result.*/ return result; } /* * Name: * MapPut0 * Purpose: * Stores a scalar value in a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void MapPut0( AstKeyMap *this, const char *key, type value, * const char *comment, int *status ) * Class Membership: * Table member function (over-rides the astMapPut0 method inherited * from the KeyMap class). * Description: * This is a set of functions for storing a scalar value in a cell of * a Table. You should use a function which matches the data type of the * data you wish to add to the Table by replacing in the generic * function name MapPut0 by an appropriate 1-character type code (see * the "Data Type Codes" section in the astMapPut0 docs). * Parameters: * this * Pointer to the Table in which to store the supplied value. * key * A character string identifying the cell in which the value is * to be stored. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * value * The value to be stored. The data type of this value should match * the 1-character type code appended to the function name (e.g. if * you are using astMapPut0A, the type of this value should be "pointer * to AstObject"). An error will be reported if this data type is * different to the data type assigned to the column when it was * created via astAddColumn. * comment * A pointer to a null-terminated comment string to be stored with the * value. A NULL pointer may be supplied, in which case no comment is * stored. * status * Pointer to inherited status value. * Notes: * - Key names are case insensitive, and white space is considered * significant. * - The new value will replace any old value already stored in the * Table for the specified cell. * - If the stored value is an AST Object pointer, the Object's reference * count is incremented by this call. Any subsequent changes made to * the Object using the returned pointer will be reflected in any * any other active pointers for the Object, including any obtained * later using astMapget0A. The reference count for the Object will be * decremented when the KeyMap is destroyed, or the entry is removed or * over-written with a different pointer. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_MAPPUT0(X,Xlc,Xtype,Itype,ValExp) \ static void MapPut0##X( AstKeyMap *this_keymap, const char *key, Xtype value, \ const char *comment, int *status ) { \ \ /* Local Variables: */ \ AstKeyMap *col_km; /* KeyMap holding details of the requested column */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ int type; /* Data type of the requested column */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to put the value of the parameter. */ \ if( astHasParameter( this, key ) ) { \ (*parent_mapput0##Xlc)( this_keymap, key, value, comment, status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, 1, colname, &irow, &col_km, "astMapPut0" #X, \ status ) ) { \ \ /* Check the column holds scalar values of the type implied by the \ code in the function name. */ \ (void) astMapGet0I( col_km, TYPE, &type ); \ if( type != Itype && astOK ) { \ astError( AST__BADTYP, "astMapPut0" #X "(%s): Failed to store a " \ #Xtype " value for cell \"%s\": column %s holds %s " \ "values.", status, astGetClass( this ), key, colname, \ TypeString( type ) ); \ } \ \ if( astMapHasKey( col_km, SHAPE ) && astOK ) { \ astError( AST__BADTYP, "astMapPut0" #X "(%s): Failed to store a " \ "scalar value for cell \"%s\": column %s holds vector " \ " values.", status, astGetClass( this ), key, colname ); \ } \ \ /* If the row index is larger than the current number of rows in the \ table, update the number of rows in the table. */ \ if( irow > astGetNrow( this ) ) astSetNrow( this, irow ); \ \ /* Use the astMapPut0 method in the parent keyMap class to store the \ new cell contents. */ \ (*parent_mapput0##Xlc)( this_keymap, key, value, comment, status ); \ \ /* Free resources. */ \ col_km = astAnnul( col_km ); \ } \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPPUT0(I,i,int,AST__INTTYPE,value) MAKE_MAPPUT0(D,d,double,AST__DOUBLETYPE,value) MAKE_MAPPUT0(F,f,float,AST__FLOATTYPE,value) MAKE_MAPPUT0(C,c,const char *,AST__STRINGTYPE,astStore(NULL,value,strlen(value)+1)) MAKE_MAPPUT0(A,a,AstObject *,AST__OBJECTTYPE,(value?astClone(value):NULL)) MAKE_MAPPUT0(P,p,void *,AST__POINTERTYPE,value) MAKE_MAPPUT0(S,s,short int,AST__SINTTYPE,value) MAKE_MAPPUT0(B,b,unsigned char,AST__BYTETYPE,value) /* Undefine the macro. */ #undef MAKE_MAPPUT0 /* * Name: * MapPut1 * Purpose: * Stores a vectorised value in a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void MapPut1( AstKeyMap *this, const char *key, int size, * const type value[], const char *comment, * int *status ); * Class Membership: * Table member function (over-rides the astMapPut1 method inherited * from the KeyMap class). * Description: * This is a set of functions for storing a vectorised value in a cell of * a Table. You should use a function which matches the data type of the * data you wish to add to the Table by replacing in the generic * function name MapPut1 by an appropriate 1-character type code (see * the "Data Type Codes" section in the astMapPut1 docs). * Parameters: * this * Pointer to the Table in which to store the supplied value. * key * A character string identifying the cell in which the value is * to be stored. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * size * The number of elements in the supplied array of values. * value * The value to be stored. The data type of this value should match * the 1-character type code appended to the function name (e.g. if * you are using astMapPut0A, the type of this value should be "pointer * to AstObject"). An error will be reported if this data type is * different to the data type assigned to the column when it was * created via astAddColumn. * comment * A pointer to a null-terminated comment string to be stored with the * value. A NULL pointer may be supplied, in which case no comment is * stored. * status * Pointer to inherited status value. * Notes: * - Key names are case insensitive, and white space is considered * significant. * - The new value will replace any old value already stored in the * Table for the specified cell. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_MAPPUT1(X,Xlc,Xtype,Itype,ValExp) \ static void MapPut1##X( AstKeyMap *this_keymap, const char *key, int size, \ Xtype value[], const char *comment, \ int *status ) { \ \ /* Local Variables: */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to put the value of the parameter. */ \ if( astHasParameter( this, key ) ) { \ (*parent_mapput1##Xlc)( this_keymap, key, size, value, \ comment, status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, 1, colname, &irow, NULL, "astMapPut1" #X, \ status ) ) { \ \ /* Check the column holds vector values of the type implied by the \ code in the function name. */ \ if( astGetColumnType( this, colname ) != Itype && astOK ) { \ astError( AST__BADTYP, "astMapPut1" #X "(%s): Failed to store " \ #Xtype " values for cell \"%s\": column %s holds %s values.", \ status, astGetClass( this ), key, colname, \ TypeString( astGetColumnType( this, colname ) ) ); \ } \ \ /* Check the column holds vectors with length equal to the supplied vector. */ \ if( astGetColumnLength( this, colname ) != size && astOK ) { \ astError( AST__BADTYP, "astMapPut1" #X "(%s): Failed to " \ "store a vector value for cell \"%s\": column " \ "%s needs %d values per cell but %d were supplied.", \ status, astGetClass( this ), key, colname, \ astGetColumnLength( this, colname ), size ); \ } \ \ /* If all is OK, update the number of rows in the table if required, and \ store the vector in the parent KeyMap. */ \ if( astOK ) { \ if( irow > astGetNrow( this ) ) astSetNrow( this, irow ); \ (*parent_mapput1##Xlc)( this_keymap, key, size, value, \ comment, status ); \ } \ \ } \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPPUT1(D,d,const double,AST__DOUBLETYPE,value[i]) MAKE_MAPPUT1(F,f,const float,AST__FLOATTYPE,value[i]) MAKE_MAPPUT1(I,i,const int,AST__INTTYPE,value[i]) MAKE_MAPPUT1(C,c,const char *const,AST__STRINGTYPE,astStore(NULL,value[i],strlen(value[i])+1)) MAKE_MAPPUT1(A,a,AstObject *const,AST__OBJECTTYPE,(value[i]?astClone(value[i]):NULL)) MAKE_MAPPUT1(P,p,void *const,AST__POINTERTYPE,value[i]) MAKE_MAPPUT1(S,s,const short int,AST__SINTTYPE,value[i]) MAKE_MAPPUT1(B,b,const unsigned char,AST__BYTETYPE,value[i]) /* Undefine the macro. */ #undef MAKE_MAPPUT1 /* * Name: * MapPutElem * Purpose: * Put a value into an element of a vector value in a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void MapPutElem( AstKeyMap *this, const char *key, int elem, * type *value, int *status ) * Class Membership: * Table member function (over-rides the astMapPutElem method inherited * from the KeyMap class). * Description: * This is a set of functions for storing a value in a single element * of a vector value stored in a cell of a Table. You should use a * function which matches the data type of the data you wish to add to * the Table by replacing in the generic function name MapPutElem * by an appropriate 1-character type code (see the "Data Type Codes" * section in the astMapPutElem docs). * Parameters: * this * Pointer to the Table in which to store the supplied value. * key * A character string identifying the cell in which the value is * to be stored. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * elem * The index of the vector element to modify, starting at zero. * If the index is outside the range of the vector, an error will * be reported. * value * The value to be stored. The data type of this value should match * the 1-character type code appended to the function name (e.g. if * you are using astMapPut0A, the type of this value should be "pointer * to AstObject"). An error will be reported if this data type is * different to the data type assigned to the column when it was * created via astAddColumn. * status * Pointer to inherited status value. * Notes: * - Key names are case insensitive, and white space is considered * significant. * - The new value will replace any old value already stored in the * Table for the specified cell. * - If the stored value is an AST Object pointer, the Object's reference * count is incremented by this call. Any subsequent changes made to * the Object using the returned pointer will be reflected in any * any other active pointers for the Object, including any obtained * later using astMapget0A. The reference count for the Object will be * decremented when the KeyMap is destroyed, or the entry is removed or * over-written with a different pointer. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_MAPPUTELEM(X,Xlc,Xtype,Itype) \ static void MapPutElem##X( AstKeyMap *this_keymap, const char *key, int elem, \ Xtype value, int *status ) { \ \ /* Local Variables: */ \ AstTable *this; /* Pointer to Table structure */ \ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ \ int irow; /* Row index within key string */ \ int type; /* Data type of the requested column */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Get a pointer to the Table structure. */ \ this = (AstTable *) this_keymap; \ \ /* If the key is the name of a global table parameter, use the parent \ method to put the value of the parameter. */ \ if( astHasParameter( this, key ) ) { \ (*parent_mapputelem##Xlc)( this_keymap, key, elem, value, \ status ); \ \ /* Check the supplied key looks like a table cell key, and get the \ the column name and the row number. Also checks that the table \ contains a column with the specified name. */ \ } else if( ParseKey( this, key, 1, colname, &irow, NULL, "astMapPutElem" #X, \ status ) ) { \ \ /* Check the column holds vector values of the type implied by the \ code in the function name. */ \ type = astGetColumnType( this, colname ); \ if( type != Itype && astOK ) { \ astError( AST__BADTYP, "astMapPutElem" #X "(%s): Failed to store a " \ #Xtype " value in cell \"%s\": column %s holds %s values.", \ status, astGetClass( this ), key, colname, \ TypeString( type ) ); \ } \ \ /* Check the column holds vectors with length equal to the supplied vector. */ \ if( astGetColumnLength( this, colname ) <= elem && astOK ) { \ astError( AST__BADTYP, "astMapPutElem" #X "(%s): Failed to " \ "store a value for element %d (zero-based) of " \ "cell \"%s\": column %s has only %d values per " \ "cell.", status, astGetClass( this ), elem, key, \ colname, astGetColumnLength( this, colname ) ); \ } \ \ /* If all is OK, update the number of rows in the table if required, and \ store the value in the parent KeyMap. */ \ if( astOK ) { \ if( irow > astGetNrow( this ) ) astSetNrow( this, irow ); \ (*parent_mapputelem##Xlc)( this_keymap, key, elem, value, \ status ); \ } \ } \ } /* Expand the above macro to generate a function for each required data type. */ MAKE_MAPPUTELEM(I,i,int,AST__INTTYPE) MAKE_MAPPUTELEM(D,d,double,AST__DOUBLETYPE) MAKE_MAPPUTELEM(F,f,float,AST__FLOATTYPE) MAKE_MAPPUTELEM(A,a,AstObject *,AST__OBJECTTYPE) MAKE_MAPPUTELEM(P,p,void *,AST__POINTERTYPE) MAKE_MAPPUTELEM(C,c,const char *,AST__STRINGTYPE) MAKE_MAPPUTELEM(S,s,short int,AST__SINTTYPE) MAKE_MAPPUTELEM(B,b,unsigned char,AST__BYTETYPE) /* Undefine the macro. */ #undef MAKE_MAPPUTELEM static void MapPutU( AstKeyMap *this_keymap, const char *key, const char *comment, int *status ) { /* * Name: * MapPutU * Purpose: * Stores a undefined value in a cell of a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void MapPutU( AstKeyMap *this, const char *key, const char *comment, * int *status ) * Class Membership: * Table member function (over-rides the astMapPutU method inherited * from the KeyMap class). * Description: * This function adds a new cell to a Table, but no value is stored with * the cell. The cell therefore has a special data type represented by * symbolic constant AST__UNDEFTYPE. * * An example use is to add cells with undefined values to a Table * prior to locking them with the MapLocked attribute. Such cells * can act as placeholders for values that can be added to the KeyMap * later. * Parameters: * this * Pointer to the Table in which to store the supplied value. * key * A character string identifying the cell in which the value is * to be stored. It should have the form "COLNAME(irow)", where * "COLNAME" is replaced by the name of a column that has been * defined previously using the astAddColumn method, and "irow" is * an integer row index (the first row is row 1). * comment * A pointer to a null-terminated comment string to be stored with the * value. A NULL pointer may be supplied, in which case no comment is * stored. * status * Pointer to inherited status value. * Notes: * - Key names are case insensitive, and white space is considered * significant. * - The new undefined value will replace any old value already stored in * the Table for the specified cell. */ /* Local Variables: */ AstTable *this; /* Pointer to Table structure */ char colname[ AST__MXCOLNAMLEN + 1 ]; /* Column name read from string */ int irow; /* Row index within key string */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Table structure. */ this = (AstTable *) this_keymap; /* If the key is the name of a global table parameter, use the parent method to put the value of the parameter. */ if( astHasParameter( this, key ) ) { (*parent_mapputu)( this_keymap, key, comment, status ); /* Check the supplied key looks like a table cell key, and get the the column name and the row number. Also checks that the table contains a column with the specified name. */ } else if( ParseKey( this, key, 1, colname, &irow, NULL, "astMapPutU", status ) ) { /* If the row index is larger than the current number of rows in the table, update the number of rows in the table. */ if( irow > astGetNrow( this ) ) astSetNrow( this, irow ); /* Use the astMapPutU method in the parent keyMap class to store the new cell contents. */ (*parent_mapputu)( this_keymap, key, comment, status ); } } static const char *ParameterName( AstTable *this, int index, int *status ) { /* *++ * Name: c astParameterName f AST_PARAMETERNAME * Purpose: * Get the name of the global parameter at a given index within the Table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c const char *astParameterName( AstTable *this, int index ) f RESULT = AST_PARAMETERNAME( THIS, INDEX, STATUS ) * Class Membership: * Table method. * Description: * This function returns a string holding the name of the global parameter with * the given index within the Table. * * This function is intended primarily as a means of iterating round all * the parameters in a Table. For this purpose, the number of parameters in * the Table is given by the Nparameter attribute of the Table. This function * could then be called in a loop, with the index value going from c zero to one less than Nparameter. f one to Nparameter. * * Note, the index associated with a parameter decreases monotonically with * the age of the parameter: the oldest Parameter in the Table will have index * one, and the Parameter added most recently to the Table will have the * largest index. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c index f INDEX = INTEGER (Given) * The index into the list of parameters. The first parameter has index * one, and the last has index "Nparameter". f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astParameterName() c A pointer to a null-terminated string containing the f AST_PARAMETERNAME = CHARACTER * ( AST__SZCHR ) f The * upper case parameter name. * Notes: c - The returned pointer is guaranteed to remain valid and the c string to which it points will not be over-written for a total c of 50 successive invocations of this function. After this, the c memory containing the string may be re-used, so a copy of the c string should be made if it is needed for longer than this. c - A NULL pointer will be returned if this function is invoked c with the AST error status set, or if it should fail for any c reason. f - A blank string will be returned if this function is invoked f with STATUS set to an error value, or if it should fail for any f reason. *-- */ /* Local Variables: */ AstKeyMap *pars; /* KeyMap holding parameter definitions */ const char *result; /* Check the global error status. */ if ( !astOK ) return NULL; /* Get apointer to the KeyMap holding all parameter definitions. */ pars = astParameterProps( this ); /* Issue a more useful error message than that issued by astMapKey if the index is invalid. */ if( index < 1 || index > astMapSize( pars ) ) { astError( AST__MPIND, "astParameterName(%s): Cannot find parameter " "%d (zero-based) of the %s - invalid index.", status, astGetClass( this ), index, astGetClass( this ) ); } /* Get the parameter name. */ result = astMapKey( pars, index - 1 ); /* Free resources. */ pars = astAnnul( pars ); /* Return a pointer to the required parameter name. */ return result; } static AstKeyMap *ParameterProps( AstTable *this, int *status ) { /* *+ * Name: * astParameterProps * Purpose: * Returns a pointer to the KeyMap holding parameter properties. * Type: * Protected virtual function. * Synopsis: * #include "table.h" * AstKeyMap *astParameterProps( AstTable *this ) * Class Membership: * Table method. * Description: * This function returns a pointer to the KeyMap that holds * definitions of all the parameters added to the Table. * Parameters: * this * Pointer to the Table. * Returned Value: * A pointer to the KeyMap. It should be annulled using astAnnul * when no longer needed. *- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Return a cloned pointer to the required KeyMap. */ return astClone( this->parameters ); } static int ParseKey( AstTable *this, const char *key, int report, char colname[ AST__MXCOLNAMLEN + 1 ], int *irow, AstKeyMap **col_km, const char *method, int *status ){ /* * Name: * ParseKey * Purpose: * Find the column name and row index in a KeyMap key. * Type: * Private function. * Synopsis: * #include "table.h" * int ParseKey( AstTable *this, const char *key, int report, * char colname[ AST__MXCOLNAMLEN + 1 ], int *irow, * AstKeyMap **col_km, const char *method, int *status ) * Class Membership: * Table member function * Description: * This function checks that the supplied KeyMap key conforms to the * format expected for Table cells: i.e. "COLNAME(irow)", where * "COLNAME" is the name of a column and "irow" is an integer row * index (the first row is row 1), An error is reported if this is * not the case. * Parameters: * this * Pointer to the table. * key * The key string to test. * report * If non-zero, an error will be reported if the key does not * correspond to a cell of an existing column. Otherwise, no * error will be reported. * colname * A buffer in which to return the column name. * irow * Address of an int in which to return the row index. * col_km * Address of a KeyMap pointer in which to return a pointer to the * KeyMap holding the information about the column. The returned * KeyMap pointer should be annulled using astAnnul when no lngerr * needed. If "col_km" is NULL, no KeyMap pointer is returned. * method * Pointer to a string holding the name of the method to include in * any error message. * status * Address of the inherited status value. * Returned Value: * Zero is returned if the key is not a valid Table cell key, or if an * error occurs. */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ int result; /* Returned flag */ int collen; /* Length of column name */ int nctot; /* Number of characters read */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Check the supplied key looks like a table cell key, and extract the column name and row number. */ nctot = 0; if( 1 == astSscanf( key, "%*[^(]%n(%d) %n", &collen, irow, &nctot ) && ( nctot >= strlen( key ) ) ) { /* Check the column name is not too long. */ if( collen > AST__MXCOLNAMLEN ) { if( report ) { astError( AST__BADKEY, "%s(%s): Failed to store a value for cell " "\"%s\": column name is too long.", status, method, astGetClass( this ), key ); } /* Check the row index is positive. */ } else if( *irow < 1 ) { if( report ) { astError( AST__BADKEY, "%s(%s): Failed to store a value for cell " "\"%s\": row index %d is invalid.", status, method, astGetClass( this ), key, *irow ); } /* If the key looks OK so far... */ } else { /* Convert the column name to upper case and store in the returned buffer. */ astChrCase( key, colname, 1, collen + 1 ); colname[ collen ] = 0; /* check that the column exists in the Table, returning a pointer to the column KeyMap is reequired. */ cols = astColumnProps( this ); if( col_km ) { result = astMapGet0A( cols, colname, col_km ); } else { result = astMapHasKey( cols, colname ); } cols = astAnnul( cols ); /* Report an error if the table does not contain the specified column. */ if( !result && astOK && report) { astError( AST__BADKEY, "%s(%s): Failed to store a value for " "cell \"%s\": the table does not contain a column " "called '%s'.", status, method, astGetClass( this ), key, colname ); } } /* Report an error if the cell key has the wrong format. */ } else if( report ) { astError( AST__BADKEY, "%s(%s): Failed to store a value for cell " "\"%s\": the cell name is invalid.", status, method, astGetClass( this ), key ); } /* Return the result.*/ return result; } static void PurgeRows( AstTable *this, int *status ) { /* *++ * Name: c astPurgeRows f AST_PURGEROWS * Purpose: * Remove all empty rows from a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astPurgeRows( AstTable *this ) f CALL AST_PURGEROWS( THIS, STATUS ) * Class Membership: * Table method. * Description: * This function removes all empty rows from the Table, renaming * the key associated with each table cell accordingly. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ char newkey[ AST__MXCOLKEYLEN + 1 ]; /* New cell key string */ char oldkey[ AST__MXCOLKEYLEN + 1 ]; /* Old cell key string */ const char *col; /* Column name */ const char *key; /* Pointer to key string */ const char *op; /* Pointer to opening parenthesis */ int *w1; /* Work space pointer */ int icol; /* Column index */ int inew; /* New row index */ int iold; /* Old row index */ int ncol; /* Number of columns in table */ int nrow; /* Number of rows in table */ int reset; /* Start a new pass through the KeyMap? */ /* Check the global error status. */ if ( !astOK ) return; /* Get the number of rows in the table. */ nrow = astGetNrow( this ); /* Create workspace to hold the number of defined values stored in each row. Initialise every row to have zero defined values. */ w1 = astCalloc( nrow, sizeof( int ) ); if( astOK ) { /* Iterate round all keys in the KeyMap. */ reset = 1; while( ( key = astMapIterate( this, reset ) ) && astOK ) { reset = 0; /* Extract the row number from the key. */ op = strchr( key, '(' ); if( !op || astSscanf( op + 1, "%d", &iold ) != 1 || iold > nrow ) { astError( AST__INTER, "astPurgeRows(%s): Illegal key '%s' " "found in a %s (internal programming error).", status, astGetClass( this ), key, astGetClass( this ) ); /* Increment the number of values in this row. Note row indices are one-based. */ } else { w1[ iold - 1 ]++; } } /* Loop round all columns in the Table. */ ncol = astGetNcolumn( this ); inew = nrow; for( icol = 1; icol <= ncol; icol++ ) { /* Get the column name */ col = astColumnName( this, icol ); /* Loop round all the old row numbers. Skip empty rows.*/ inew = 0; for( iold = 0; iold < nrow; iold++ ) { if( w1[ iold ] > 0 ) { /* Increment the row number to use in place of the old row number. If the old and new row numbers are the same, we do not need to rename the cell. */ if( iold != inew++ ) { /* For the old and new cell names */ sprintf( oldkey, "%s(%d)", col, iold + 1 ); sprintf( newkey, "%s(%d)", col, inew ); /* Rename the KeyMap entry. */ astMapRename( this, oldkey, newkey ); } } } /* If all rows were used, we do not need to check any more columns. */ if( iold == inew ) break; } /* Store the new number of rows. */ astSetNrow( this, inew ); } /* Free resources. */ w1 = astFree( w1 ); } static void RemoveColumn( AstTable *this, const char *name, int *status ) { /* *++ * Name: c astRemoveColumn f AST_REMOVECOLUMN * Purpose: * Remove a column from a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astRemoveColumn( AstTable *this, const char *name ) f CALL AST_REMOVECOLUMN( THIS, NAME, STATUS ) * Class Membership: * Table method. * Description: * This function removes a specified column from the supplied table. * The c function f routine * returns without action if the named column does not exist in the * Table (no error is reported). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c name f NAME = CHARACTER * ( * ) (Given) * The column name. Trailing spaces are ignored (all other spaces * are significant). Case is significant. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ char key[ AST__MXCOLKEYLEN + 1 ]; /* Cell key string */ int irow; /* Row index */ int namlen; /* Used length of "name" */ int nrow; /* Number of rows in table */ /* Check the global error status. */ if ( !astOK ) return; /* Verify supplied values. */ namlen = astChrLen( name ); if( namlen == 0 ) { astError( AST__BADKEY, "astRemoveColumn(%s): Illegal blank column name " "supplied.", status, astGetClass( this ) ); } /* Get the number of rows in the table. */ nrow = astGetNrow( this ); /* If there is no column with the given name in the Table, do nothing more. */ cols = astColumnProps( this ); if( astOK && astMapHasKey( cols, name ) ) { /* Remove the column description from the columns keymap. */ astMapRemove( cols, name ); /* Remove any column cells with defined values from the parent KeyMap. */ for( irow = 1; irow <= nrow; irow++ ) { sprintf( key, "%.*s(%d)", namlen, name, irow ); (*parent_mapremove)( (AstKeyMap *) this, key, status ); } } cols = astAnnul( cols ); } static void RemoveParameter( AstTable *this, const char *name, int *status ) { /* *++ * Name: c astRemoveParameter f AST_REMOVEPARAMETER * Purpose: * Remove a global parameter from a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astRemoveParameter( AstTable *this, const char *name ) f CALL AST_REMOVEPARAMETER( THIS, NAME, STATUS ) * Class Membership: * Table method. * Description: * This function removes a specified global parameter from the supplied table. * The c function f routine * returns without action if the named parameter does not exist in the * Table (no error is reported). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c name f NAME = CHARACTER * ( * ) (Given) * The parameter name. Trailing spaces are ignored (all other spaces * are significant). Case is significant. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstKeyMap *pars; /* KeyMap holding parameter definitions */ /* Check the global error status. */ if ( !astOK ) return; /* Verify supplied values. */ if( astChrLen( name ) == 0 ) { astError( AST__BADKEY, "astRemoveParameter(%s): Illegal blank parameter name " "supplied.", status, astGetClass( this ) ); } /* If there is no parameter with the given name in the Table, do nothing more. */ pars = astParameterProps( this ); if( astOK && astMapHasKey( pars, name ) ) { /* Remove the parameter description from the parameters keymap. */ astMapRemove( pars, name ); /* Remove any entry holding the parameter value from the parent KeyMap. */ (*parent_mapremove)( (AstKeyMap *) this, name, status ); } pars = astAnnul( pars ); } static void RemoveRow( AstTable *this, int index, int *status ) { /* *++ * Name: c astRemoveRow f AST_REMOVEROW * Purpose: * Remove a row from a table. * Type: * Public virtual function. * Synopsis: c #include "table.h" c void astRemoveRow( AstTable *this, int index ) f CALL AST_REMOVEROW( THIS, INDEX, STATUS ) * Class Membership: * Table method. * Description: * This function removes a specified row from the supplied table. * The c function f routine * returns without action if the row does not exist in the * Table (no error is reported). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Table. c index f INDEX = INTEGER (Given) * The index of the row to be removed. The first row has index 1. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstKeyMap *cols; /* KeyMap holding column definitions */ char key[ AST__MXCOLKEYLEN + 1 ]; /* Cell key string */ const char *col; /* Column name */ int icol; /* Column index */ int ncol; /* Number of columns in table */ int nrow; /* Number of rows in table */ /* Check the global error status. */ if ( !astOK ) return; /* Get the number of rows in the table. */ nrow = astGetNrow( this ); /* Do nothing if the specified row is out of bounds. */ if( index > 0 && index <= nrow ) { /* Loop round all columns in the table. */ cols = astColumnProps( this ); ncol = astMapSize( cols ); for( icol = 0; icol < ncol; icol++ ) { col = astMapKey( cols, icol ); /* Remove the cell of the current column at the requested row. */ sprintf( key, "%s(%d)", col, index ); (*parent_mapremove)( (AstKeyMap *) this, key, status ); } cols = astAnnul( cols ); /* If the removed row was the last row, reduce the number of rows in the Table. */ if( index == nrow ) astSetNrow( this, index - 1 ); } } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Table. * Type: * Private function. * Synopsis: * #include "table.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Table member function (over-rides the astSetAttrib protected * method inherited from the KeyMap class). * Description: * This function assigns an attribute value for a Table, 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 Table. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstTable *this; /* Pointer to the Table structure */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Table structure. */ this = (AstTable *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* None as yet */ /* 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 ) ) #define MATCH2(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "(%*s) =%*[^\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. */ if ( MATCH( "ncolumn" ) || MATCH( "nparameter" ) || MATCH( "nrow" ) || MATCH2( "columnlenc" ) || MATCH2( "columnlength" ) || MATCH2( "columnndim" ) || MATCH2( "columntype" ) || MATCH2( "columnunit" ) ) { 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH #undef MATCH2 } static void SetKeyCase( AstKeyMap *this, int keycase, int *status ) { /* * Name: * SetKeyCase * Purpose: * Set a value for the KeyCase attribute value for a Table. * Type: * Private function. * Synopsis: * #include "keymape.h" * void SetKeyCase( AstKeyMap *this, int keycase, int *status ) * Class Membership: * Table member function (over-rides the astSetKeyCase protected * method inherited from the KeyMap class). * Description: * This function assigns a new valeu to the KeyCase attribute for a * Table. For a Table, the KeyCase attribute cannot be changed so this * function exits without action. * Parameters: * this * Pointer to the Table. * keycase * The new value to set. */ } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Table. * Type: * Private function. * Synopsis: * #include "table.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Table member function (over-rides the astTestAttrib protected * method inherited from the KeyMap class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Table's attributes. * Parameters: * this * Pointer to the Table. * 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: */ int len; /* Length of attribute string */ int nc; /* Number of characters read by astSscanf */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get the length of the attribute string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* None as yet */ /* Define a macro to see if the attribute string matches any of the read-only column attributes of this class. */ #define MATCH(attr) \ ( nc = 0, ( 0 == astSscanf( attrib, attr "(%*s)%n", &nc ) ) && \ ( nc >= len ) ) /* 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. */ if ( !strcmp( attrib, "ncolumn" ) || !strcmp( attrib, "nparameter" ) || !strcmp( attrib, "nrow" ) || MATCH( "columnlenc" ) || MATCH( "columnlength" ) || MATCH( "columnndim" ) || MATCH( "columntype" ) || MATCH( "columnunit" ) ) { result = 0; /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; #undef MATCH } static const char *TypeString( int type ) { /* * Name: * TypeString * Purpose: * Return a pointer to a string describing a data type. * Type: * Private function. * Synopsis: * const char *TypeString( int type ); * Description: * This function returns a pointer to a string describing a data type. * Parameters: * type * The integer data type code. * Returned Value: * Pointer to a a string descirbing the data type (typically the C * data type). */ /* Local Variables: */ const char *result; /* Compare the supplied type code against each supported value. */ if( type == AST__INTTYPE ) { result = "int"; } else if( type == AST__BYTETYPE ) { result = "byte"; } else if( type == AST__DOUBLETYPE ) { result = "double"; } else if( type == AST__STRINGTYPE ) { result = "string"; } else if( type == AST__OBJECTTYPE ) { result = "Object"; } else if( type == AST__FLOATTYPE ) { result = "float"; } else if( type == AST__POINTERTYPE ) { result = "pointer"; } else if( type == AST__SINTTYPE ) { result = "short int"; } else if( type == AST__UNDEFTYPE ) { result = "undefined"; } else { result = NULL; } /* Return the result. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * ColumnLenC(column) * Purpose: * The largest string length of any value in a column * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the minimum length which a character variable * must have in order to be able to store the longest value currently * present (at any row) in a specified column of the supplied Table. c This does not include room for a trailing null character. * The required column name should be placed inside the parentheses in * the attribute name. If the named column holds vector values, then * the attribute value is the length of the longest element of the * vector value. * Applicability: * Table * All Tables have this attribute. * Notes: * - If the named column holds numerical values, the length returned * is the length of the largest string that would be generated if the * column values were accessed as strings. *att-- */ /* *att++ * Name: * ColumnLength(column) * Purpose: * The number of elements in each value in a column * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the number of elements in each value stored * in a named column. Each value can be a scalar (in which case the * ColumnLength attribute has a value of 1), or a multi-dimensional * array ( in which case the ColumnLength value is equal to the * product of the array dimensions). * Applicability: * Table * All Tables have this attribute. *att-- */ /* *att++ * Name: * ColumnNdim(column) * Purpose: * The number of axes spanned by each value in a column * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the number of axes spanned by each value in a * column. If each cell in the column is a scalar, ColumnNdim will be * zero. If each cell in the column is a 1D spectrum, ColumnNdim will * be one. If each cell in the column is a 2D image, ColumnNdim will be * two, etc. The required column name should be placed inside the * parentheses in the attribute name. * Applicability: * Table * All Tables have this attribute. *att-- */ /* *att++ * Name: * ColumnType(column) * Purpose: * The data type of each value in a column * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds a integer value indicating the data type of * a named column in a Table. This is the data type which was used * when the column was added to the Table using astAddColumn. The * required column name should be placed inside the parentheses in * the attribute name. * * The attribute value will be one of AST__INTTYPE (for integer), * AST__SINTTYPE (for c short int), f INTEGER*2), * AST__BYTETYPE (for c unsigned bytes - i.e. unsigned chars), f bytes), * AST__DOUBLETYPE (for double * precision floating point), AST__FLOATTYPE (for single * precision floating point), AST__STRINGTYPE (for character string), * AST__OBJECTTYPE (for AST Object pointer), AST__POINTERTYPE (for * arbitrary C pointer) or AST__UNDEFTYPE (for undefined values * created by c astMapPutU). f AST_MAPPUTU). * Applicability: * Table * All Tables have this attribute. *att-- */ /* *att++ * Name: * Ncolumn * Purpose: * The number of columns in the table. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the number of columns currently in the table. Columns * are added and removed using the c astAddColumn and astRemoveColumn f AST_ADDCOLUMN and AST_REMOVECOLUMN * functions. * Applicability: * Table * All Tables have this attribute. *att-- */ /* *att++ * Name: * Nparameter * Purpose: * The number of global parameters in the table. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the number of global parameters currently in the table. * Parameters are added and removed using the c astAddParameter and astRemoveParameter f AST_ADDPARAMETER and AST_REMOVEPARAMETER * functions. * Applicability: * Table * All Tables have this attribute. *att-- */ /* *att++ * Name: * Nrow * Purpose: * The number of rows in the table. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This attribute holds the index of the last row to which any * contents have been added using any of the * astMapPut... * AST_MAPPUT... * functions. The first row has index 1. * Applicability: * Table * All Tables have this attribute. *att-- */ astMAKE_GET(Table,Nrow,int,0,this->nrow) astMAKE_SET(Table,Nrow,int,nrow,value) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Table objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Table objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Mappings within the Table. */ /* Local Variables: */ AstTable *in; /* Pointer to input Table */ AstTable *out; /* Pointer to output Table */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Tables. */ in = (AstTable *) objin; out = (AstTable *) objout; /* Make copies of the component KeyMaps and store pointers to them in the output Table structure. */ out->columns = in->columns ? astCopy( in->columns ) : NULL; out->parameters = in->parameters ? astCopy( in->parameters ) : NULL; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Table objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Table objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstTable *this; /* Pointer to Table */ /* Obtain a pointer to the Table structure. */ this = (AstTable *) obj; /* Annul the pointers to the component KeyMaps. */ if( this->columns ) this->columns = astAnnul( this->columns ); if( this->parameters ) this->parameters = astAnnul( this->parameters ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Table 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 Table class to an output Channel. * Parameters: * this * Pointer to the Table 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 Variables: */ AstTable *this; /* Pointer to the Table structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Table structure. */ this = (AstTable *) this_object; /* Write out values representing the instance variables for the Table class. Note, the primitive data in the Table will be written out by the parent KeyMap Dump function. This function deals just with the extra information held in the Table structure. */ /* Write out the number of rows in the table. */ astWriteInt( channel, "Nrow", 1, 1, astGetNrow( this ), "Number of rows in table" ); /* Write out the KeyMap holding definitions of each column. */ if( this->columns ) { astWriteObject( channel, "Columns", 1, 0, this->columns, "KeyMap holding " "column definitions" ); } /* Write out the KeyMap holding definitions of each global parameter. */ if( this->parameters ) { astWriteObject( channel, "Params", 1, 0, this->parameters, "KeyMap holding " "parameter definitions" ); } } /* Standard class functions. */ /* ========================= */ /* Implement the astIsATable and astCheckTable functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Table,KeyMap) astMAKE_CHECK(Table) AstTable *astTable_( const char *options, int *status, ...) { /* *++ * Name: c astTable f AST_TABLE * Purpose: * Create a Table. * Type: * Public function. * Synopsis: c #include "table.h" c AstTable *astTable( const char *options, ... ) f RESULT = AST_TABLE( OPTIONS, STATUS ) * Class Membership: * Table constructor. * Description: * This function creates a new empty Table and optionally initialises * its attributes. * * The Table class is a type of KeyMap that represents a two-dimensional * table of values. The c astMapGet... and astMapPut... f AST_MAPGET... and AST_MAPPUT... * methods provided by the KeyMap class should be used for storing and * retrieving values from individual cells within a Table. Each entry * in the KeyMap represents a single cell of the table and has an * associated key of the form "(i)" where "" is the name of a * table column and "i" is the row index (the first row is row 1). Keys * of this form should always be used when using KeyMap methods to access * entries within a Table. * * Columns must be declared using the c astAddColumn f AST_ADDCOLUMN * method before values can be stored within them. This also fixes the * type and shape of the values that may be stored in any cell of the * column. Cells may contain scalar or vector values of any data type * supported by the KeyMap class. Multi-dimensional arrays may also be * stored, but these must be vectorised when storing and retrieving * them within a table cell. All cells within a single column must * have the same type and shape (specified when the column is declared). * * Tables may have parameters that describe global properties of the * entire table. These are stored as entries in the parent KeyMap and * can be access using the get and set method of the KeyMap class. * However, parameters must be declared using the c astAddParameter f AST_ADDPARAMETER * method before being accessed. * * Note - since accessing entries within a KeyMap is a relatively slow * process, it is not recommended to use the Table class to store * very large tables. * Parameters: 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 Table. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Table. The syntax used is identical to that for the f AST_SET routine. 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 astTable() f AST_TABLE = INTEGER * A pointer to the new Table. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list described above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTable *new; /* Pointer to new Table */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the Table, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTable( NULL, sizeof( AstTable ), !class_init, &class_vtab, "Table" ); /* 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 Table'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 Table. */ return new; } AstTable *astTableId_( const char *options, ... ) { /* * Name: * astTableId_ * Purpose: * Create a Table. * Type: * Private function. * Synopsis: * #include "table.h" * AstTable *astTableId_( const char *options, ... ) * Class Membership: * Table constructor. * Description: * This function implements the external (public) interface to the * astTable constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astTable_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astTable_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astTable_. * Returned Value: * The ID value associated with the new Table. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTable *new; /* Pointer to new Table */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the Table, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTable( NULL, sizeof( AstTable ), !class_init, &class_vtab, "Table" ); /* 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 Table'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 Table. */ return astMakeId( new ); } AstTable *astInitTable_( void *mem, size_t size, int init, AstTableVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTable * Purpose: * Initialise a Table. * Type: * Protected function. * Synopsis: * #include "table.h" * AstTable *astInitTable( void *mem, size_t size, int init, * AstTableVtab *vtab, const char *name ) * Class Membership: * Table initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Table object. It allocates memory (if necessary) to accommodate * the Table plus any additional data associated with the derived class. * It then initialises a Table 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 Table at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Table is to be initialised. * This must be of sufficient size to accommodate the Table data * (sizeof(Table)) 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 Table (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 Table * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Table'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 Table. * 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). * Returned Value: * A pointer to the new Table. * 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: */ AstTable *new; /* Pointer to new Table */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitTableVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a KeyMap structure (the parent class) as the first component within the Table structure, allocating memory if necessary. Specify that the KeyMap should be defined in both the forward and inverse directions. */ new = (AstTable *) astInitKeyMap( mem, size, 0, (AstKeyMapVtab *) vtab, name ); if ( astOK ) { /* Initialise the Table data. */ /* ---------------------------- */ new->nrow = 0; new->columns = astKeyMap( "KeyCase=0,Sortby=AgeDown", status ); new->parameters = astKeyMap( "KeyCase=0,Sortby=AgeDown", status ); /* Tables require the KeyCase attribute to be zero. */ (*parent_setkeycase)( (AstKeyMap *) new, 0, status ); /* If an error occurred, clean up by deleting the new Table. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new Table. */ return new; } AstTable *astLoadTable_( void *mem, size_t size, AstTableVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadTable * Purpose: * Load a Table. * Type: * Protected function. * Synopsis: * #include "table.h" * AstTable *astLoadTable( void *mem, size_t size, AstTableVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Table loader. * Description: * This function is provided to load a new Table 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 * Table structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Table at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Table is to be * loaded. This must be of sufficient size to accommodate the * Table data (sizeof(Table)) 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 Table (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 Table 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(AstTable) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Table. If this is NULL, a pointer * to the (static) virtual function table for the Table 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 "Table" is used instead. * Returned Value: * A pointer to the new Table. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTable *new; /* Pointer to the new Table */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Table. In this case the Table belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstTable ); vtab = &class_vtab; name = "Table"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitTableVtab( 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 Table. */ new = astLoadKeyMap( mem, size, (AstKeyMapVtab *) 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, "Table" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* The number of rows. */ new->nrow = astReadInt( channel, "nrow", 0 ); /* KeyMap holding columns definitions. */ new->columns = astReadObject( channel, "columns", NULL ); /* KeyMap holding parameter definitions. */ new->parameters = astReadObject( channel, "params", NULL ); /* If an error occurred, clean up by deleting the new Table. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Table pointer. */ return new; } /* 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 astAddColumn_( AstTable *this, const char *name, int type, int ndim, int *dims, const char *unit, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Table,AddColumn))(this,name,type,ndim,dims,unit,status); } void astAddParameter_( AstTable *this, const char *name, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Table,AddParameter))(this,name,status); } void astRemoveColumn_( AstTable *this, const char *name, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Table,RemoveColumn))(this,name,status); } void astRemoveParameter_( AstTable *this, const char *name, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Table,RemoveParameter))(this,name,status); } void astRemoveRow_( AstTable *this, int index, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Table,RemoveRow))(this,index,status); } void astPurgeRows_( AstTable *this, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Table,PurgeRows))(this,status); } int astGetNcolumn_( AstTable *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetNcolumn))( this, status ); } int astGetNparameter_( AstTable *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetNparameter))( this, status ); } const char *astColumnName_( AstTable *this, int index, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Table,ColumnName))(this,index,status); } const char *astParameterName_( AstTable *this, int index, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Table,ParameterName))(this,index,status); } int astGetColumnType_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetColumnType))(this,column,status); } const char *astGetColumnUnit_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Table,GetColumnUnit))(this,column,status); } int astGetColumnLenC_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetColumnLenC))(this,column,status); } int astGetColumnLength_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetColumnLength))(this,column,status); } int astGetColumnNdim_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,GetColumnNdim))(this,column,status); } void astColumnShape_( AstTable *this, const char *column, int mxdim, int *ndim, int *dims, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Table,ColumnShape))( this, column, mxdim, ndim, dims, status ); } AstKeyMap *astColumnProps_( AstTable *this, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Table,ColumnProps))(this,status); } AstKeyMap *astParameterProps_( AstTable *this, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Table,ParameterProps))(this,status); } int astHasColumn_( AstTable *this, const char *column, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,HasColumn))(this,column,status); } int astHasParameter_( AstTable *this, const char *parameter, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Table,HasParameter))(this,parameter,status); } ast-8.3.0/xmlchan.h0000664000175000017500000002521213004147321011034 00000000000000#if !defined( XMLCHAN_INCLUDED ) /* Include this file only once */ #define XMLCHAN_INCLUDED /* *+ * Name: * xmlchan.h * Type: * C include file. * Purpose: * Define the interface to the XmlChan class. * Invocation: * #include "xmlchan.h" * Description: * This include file defines the interface to the XmlChan class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The XmlChan class provides facilities for reading and writing AST * Objects in the form of XML. * Inheritance: * The XmlChan class inherits from the Channel class. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 10-OCT-2003 (DSB): *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" /* I/O channels (parent class) */ #include "keymap.h" /* Mappings of keys to values */ #include "xml.h" /* AST XML facilities */ /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* URI defining the starlink AST XML namespace */ #define AST__XMLNS "http://www.starlink.ac.uk/ast/xml/" /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* XmlChan structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstXmlChan { /* Attributes inherited from the parent class. */ AstChannel channel; /* Parent class structure */ /* Attributes specific to objects in this class. */ const char *objectname; /* Name of Object currently being written. */ const char *objectcomment; /* Comment for Object currently being written. */ int objectset; /* Is the Object currently being written set? */ AstXmlParent *container; /* XmlParent to which content will be added */ AstXmlDocument *readcontext;/* XmlDocument giving context for current read */ int write_isa; /* Is the next "isA" really needed? */ int xmllength; /* Buffer length */ int xmlformat; /* Output format to use when writing */ int formatdef; /* Default format */ char *xmlprefix; /* Namespace prefix */ int reset_source; /* Read a new line from the source ? */ const char *isa_class; /* Class being loaded */ } AstXmlChan; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstXmlChanVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstChannelVtab channel_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetXmlLength)( AstXmlChan *, int * ); int (* TestXmlLength)( AstXmlChan *, int * ); void (* ClearXmlLength)( AstXmlChan *, int * ); void (* SetXmlLength)( AstXmlChan *, int, int * ); int (* GetXmlFormat)( AstXmlChan *, int * ); int (* TestXmlFormat)( AstXmlChan *, int * ); void (* ClearXmlFormat)( AstXmlChan *, int * ); void (* SetXmlFormat)( AstXmlChan *, int, int * ); const char * (* GetXmlPrefix)( AstXmlChan *, int * ); int (* TestXmlPrefix)( AstXmlChan *, int * ); void (* ClearXmlPrefix)( AstXmlChan *, int * ); void (* SetXmlPrefix)( AstXmlChan *, const char *, int * ); } AstXmlChanVtab; #if defined(THREAD_SAFE) typedef struct AstXmlChanGlobals { AstXmlChanVtab Class_Vtab; int Class_Init; AstXmlChan *IsUsable_This; char GetAttrib_Buff[ 51 ]; char *GetNextChar_C; char *GetNextChar_Buf; } AstXmlChanGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(XmlChan) /* Check class membership */ astPROTO_ISA(XmlChan) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstXmlChan *astXmlChan_( const char *(*)( void ), void (*)( const char * ), const char *, int *, ...); #else AstXmlChan *astXmlChanId_( const char *(*)( void ), void (*)( const char * ), const char *, ... )__attribute__((format(printf,3,4))); AstXmlChan *astXmlChanForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstXmlChan *astInitXmlChan_( void *, size_t, int, AstXmlChanVtab *, const char *, const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), int * ); /* Vtab initialiser. */ void astInitXmlChanVtab_( AstXmlChanVtab *, const char *, int * ); /* Loader. */ AstXmlChan *astLoadXmlChan_( void *, size_t, AstXmlChanVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitXmlChanGlobals_( AstXmlChanGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astGetXmlLength_( AstXmlChan *, int * ); int astTestXmlLength_( AstXmlChan *, int * ); void astClearXmlLength_( AstXmlChan *, int * ); void astSetXmlLength_( AstXmlChan *, int, int * ); int astGetXmlFormat_( AstXmlChan *, int * ); int astTestXmlFormat_( AstXmlChan *, int * ); void astClearXmlFormat_( AstXmlChan *, int * ); void astSetXmlFormat_( AstXmlChan *, int, int * ); const char * astGetXmlPrefix_( AstXmlChan *, int * ); int astTestXmlPrefix_( AstXmlChan *, int * ); void astClearXmlPrefix_( AstXmlChan *, int * ); void astSetXmlPrefix_( AstXmlChan *, const char *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckXmlChan(this) astINVOKE_CHECK(XmlChan,this,0) #define astVerifyXmlChan(this) astINVOKE_CHECK(XmlChan,this,1) /* Test class membership. */ #define astIsAXmlChan(this) astINVOKE_ISA(XmlChan,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astXmlChan astINVOKE(F,astXmlChan_) #else #define astXmlChan astINVOKE(F,astXmlChanId_) #define astXmlChanFor astINVOKE(F,astXmlChanForId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitXmlChan(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap) \ astINVOKE(O,astInitXmlChan_(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitXmlChanVtab(vtab,name) astINVOKE(V,astInitXmlChanVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadXmlChan(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadXmlChan_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckXmlChan to validate XmlChan pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearXmlLength(this) astINVOKE(V,astClearXmlLength_(astCheckXmlChan(this),STATUS_PTR)) #define astGetXmlLength(this) astINVOKE(V,astGetXmlLength_(astCheckXmlChan(this),STATUS_PTR)) #define astSetXmlLength(this,xmllength) astINVOKE(V,astSetXmlLength_(astCheckXmlChan(this),xmllength,STATUS_PTR)) #define astTestXmlLength(this) astINVOKE(V,astTestXmlLength_(astCheckXmlChan(this),STATUS_PTR)) #define astClearXmlFormat(this) astINVOKE(V,astClearXmlFormat_(astCheckXmlChan(this),STATUS_PTR)) #define astGetXmlFormat(this) astINVOKE(V,astGetXmlFormat_(astCheckXmlChan(this),STATUS_PTR)) #define astSetXmlFormat(this,xmlformat) astINVOKE(V,astSetXmlFormat_(astCheckXmlChan(this),xmlformat,STATUS_PTR)) #define astTestXmlFormat(this) astINVOKE(V,astTestXmlFormat_(astCheckXmlChan(this),STATUS_PTR)) #define astClearXmlPrefix(this) astINVOKE(V,astClearXmlPrefix_(astCheckXmlChan(this),STATUS_PTR)) #define astGetXmlPrefix(this) astINVOKE(V,astGetXmlPrefix_(astCheckXmlChan(this),STATUS_PTR)) #define astSetXmlPrefix(this,xmlpref) astINVOKE(V,astSetXmlPrefix_(astCheckXmlChan(this),xmlpref,STATUS_PTR)) #define astTestXmlPrefix(this) astINVOKE(V,astTestXmlPrefix_(astCheckXmlChan(this),STATUS_PTR)) #endif #endif ast-8.3.0/dsbspecframe.h0000664000175000017500000002415613004147321012046 00000000000000#if !defined( DSBSPECFRAME_INCLUDED ) /* Include this file only once */ #define DSBSPECFRAME_INCLUDED /* *+ * Name: * dsbspecframe.h * Type: * C include file. * Purpose: * Define the interface to the DSBSpecFrame class. * Invocation: * #include "dsbspecframe.h" * Description: * This include file defines the interface to the DSBSpecFrame class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The DSBSpecFrame class inherits from the SpecFrame class. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 5-AUG-2004 (DSB): * Original version. * 27-OCT-2006 (DSB): * Added AlignSideBand. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "specframe.h" /* Spectral coord systems (parent class) */ /* C header files. */ /* --------------- */ /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* DSBSpecFrame structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstDSBSpecFrame { /* Attributes inherited from the parent class. */ AstSpecFrame specframe; /* Parent class structure */ /* Attributes specific to objects in this class. */ double dsbcentre; /* Centre frequency */ double ifr; /* Intermediate frequency */ int sideband; /* Current sideband */ int alignsideband; /* Aligns sidebands? */ } AstDSBSpecFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstDSBSpecFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstSpecFrameVtab specframe_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (* GetDSBCentre)( AstDSBSpecFrame *, int * ); int (* TestDSBCentre)( AstDSBSpecFrame *, int * ); void (* ClearDSBCentre)( AstDSBSpecFrame *, int * ); void (* SetDSBCentre)( AstDSBSpecFrame *, double, int * ); double (* GetIF)( AstDSBSpecFrame *, int * ); int (* TestIF)( AstDSBSpecFrame *, int * ); void (* ClearIF)( AstDSBSpecFrame *, int * ); void (* SetIF)( AstDSBSpecFrame *, double, int * ); int (* GetSideBand)( AstDSBSpecFrame *, int * ); int (* TestSideBand)( AstDSBSpecFrame *, int * ); void (* ClearSideBand)( AstDSBSpecFrame *, int * ); void (* SetSideBand)( AstDSBSpecFrame *, int, int * ); int (* GetAlignSideBand)( AstDSBSpecFrame *, int * ); int (* TestAlignSideBand)( AstDSBSpecFrame *, int * ); void (* ClearAlignSideBand)( AstDSBSpecFrame *, int * ); void (* SetAlignSideBand)( AstDSBSpecFrame *, int, int * ); double (* GetImagFreq)( AstDSBSpecFrame *, int * ); } AstDSBSpecFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstDSBSpecFrameGlobals { AstDSBSpecFrameVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; char GetLabel_Buff[ 101 ]; } AstDSBSpecFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(DSBSpecFrame) /* Check class membership */ astPROTO_ISA(DSBSpecFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstDSBSpecFrame *astDSBSpecFrame_( const char *, int *, ...); #else AstDSBSpecFrame *astDSBSpecFrameId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstDSBSpecFrame *astInitDSBSpecFrame_( void *, size_t, int, AstDSBSpecFrameVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitDSBSpecFrameVtab_( AstDSBSpecFrameVtab *, const char *, int * ); /* Loader. */ AstDSBSpecFrame *astLoadDSBSpecFrame_( void *, size_t, AstDSBSpecFrameVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitDSBSpecFrameGlobals_( AstDSBSpecFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ double astGetDSBCentre_( AstDSBSpecFrame *, int * ); int astTestDSBCentre_( AstDSBSpecFrame *, int * ); void astClearDSBCentre_( AstDSBSpecFrame *, int * ); void astSetDSBCentre_( AstDSBSpecFrame *, double, int * ); double astGetIF_( AstDSBSpecFrame *, int * ); int astTestIF_( AstDSBSpecFrame *, int * ); void astClearIF_( AstDSBSpecFrame *, int * ); void astSetIF_( AstDSBSpecFrame *, double, int * ); int astGetSideBand_( AstDSBSpecFrame *, int * ); int astTestSideBand_( AstDSBSpecFrame *, int * ); void astClearSideBand_( AstDSBSpecFrame *, int * ); void astSetSideBand_( AstDSBSpecFrame *, int, int * ); int astGetAlignSideBand_( AstDSBSpecFrame *, int * ); int astTestAlignSideBand_( AstDSBSpecFrame *, int * ); void astClearAlignSideBand_( AstDSBSpecFrame *, int * ); void astSetAlignSideBand_( AstDSBSpecFrame *, int, int * ); double astGetImagFreq_( AstDSBSpecFrame *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckDSBSpecFrame(this) astINVOKE_CHECK(DSBSpecFrame,this,0) #define astVerifyDSBSpecFrame(this) astINVOKE_CHECK(DSBSpecFrame,this,1) /* Test class membership. */ #define astIsADSBSpecFrame(this) astINVOKE_ISA(DSBSpecFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astDSBSpecFrame astINVOKE(F,astDSBSpecFrame_) #else #define astDSBSpecFrame astINVOKE(F,astDSBSpecFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define \ astInitDSBSpecFrame(mem,size,init,vtab,name) \ astINVOKE(O,astInitDSBSpecFrame_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitDSBSpecFrameVtab(vtab,name) astINVOKE(V,astInitDSBSpecFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadDSBSpecFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadDSBSpecFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckDSBSpecFrame to validate DSBSpecFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetDSBCentre(this) \ astINVOKE(V,astGetDSBCentre_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astTestDSBCentre(this) \ astINVOKE(V,astTestDSBCentre_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astClearDSBCentre(this) \ astINVOKE(V,astClearDSBCentre_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astSetDSBCentre(this,val) \ astINVOKE(V,astSetDSBCentre_(astCheckDSBSpecFrame(this),val,STATUS_PTR)) #define astGetIF(this) \ astINVOKE(V,astGetIF_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astTestIF(this) \ astINVOKE(V,astTestIF_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astClearIF(this) \ astINVOKE(V,astClearIF_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astSetIF(this,val) \ astINVOKE(V,astSetIF_(astCheckDSBSpecFrame(this),val,STATUS_PTR)) #define astGetSideBand(this) \ astINVOKE(V,astGetSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astTestSideBand(this) \ astINVOKE(V,astTestSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astClearSideBand(this) \ astINVOKE(V,astClearSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astSetSideBand(this,val) \ astINVOKE(V,astSetSideBand_(astCheckDSBSpecFrame(this),val,STATUS_PTR)) #define astGetAlignSideBand(this) \ astINVOKE(V,astGetAlignSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astTestAlignSideBand(this) \ astINVOKE(V,astTestAlignSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astClearAlignSideBand(this) \ astINVOKE(V,astClearAlignSideBand_(astCheckDSBSpecFrame(this),STATUS_PTR)) #define astSetAlignSideBand(this,val) \ astINVOKE(V,astSetAlignSideBand_(astCheckDSBSpecFrame(this),val,STATUS_PTR)) #define astGetImagFreq(this) \ astINVOKE(V,astGetImagFreq_(astCheckDSBSpecFrame(this),STATUS_PTR)) #endif #endif ast-8.3.0/fchannel.c0000664000175000017500000003445713004147321011166 00000000000000/* *+ * Name: * fchannel.c * Purpose: * Define a FORTRAN 77 interface to the AST Channel class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Channel class. * Routines Defined: * AST_CHANNEL * AST_ISACHANNEL * AST_READ * AST_WRITE * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 6-SEP-1996 (RFWS): * Original version. * 12-DEC-1996 (RFWS): * Added SOURCE and SINK arguments to AST_CHANNEL. * 13-NOV-2003 (DSB): * Made SourceWrap and SinkWrap into protected functions rather * than private functions, so that they can be used in fxmlchan.c */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "channel.h" /* C interface to the Channel class */ #include /* Module Variables. */ /* ================= */ static char *line_in = NULL; /* Pointer to incoming line of text */ static const char *line_out = NULL; /* Pointer to outgoing line of text */ /* Prototypes for external functions. */ /* ================================== */ /* This is the null function defined by the FORTRAN interface in fobject.c. */ F77_SUBROUTINE(ast_null)( void ); /* Source and sink function interfaces. */ /* ==================================== */ /* These functions are concerned with allowing FORTRAN implementations of Channel source and sink functions to be passed to the Channel class and invoked when necessary by C code in the main class implementation. All FORTRAN-specific aspects of this interface are encapsulated here. */ F77_SUBROUTINE(ast_getline)( CHARACTER(LINE), INTEGER(L), INTEGER(STATUS) TRAIL(LINE) ) { /* f++ * Name: * AST_GETLINE * Purpose: * Obtain text to be written by a Channel sink routine. * Type: * Public function. * Synopsis: * CALL AST_GETLINE( LINE, L, STATUS ) * Description: * This routine should only be used when implementing a routine * which will be passed as the SINK argument to AST_CHANNEL. It * should be used to obtain (from the AST library) each line of * text which is to be written to the external data sink. One such * line should be obtained in this way for each invocation of the * sink routine. * Parameters: * LINE = CHARACTER * ( * ) (Returned) * The line of text to be written. Depending on the length of * character variable supplied, the returned text may be * truncated if necessary. Note, however, that it will not be * padded with blanks in order to fill this variable. * L = INTEGER (Returned) * The number of characters returned, which may be zero. Note * that characters beyond the L'th character in the LINE * variable are not modified and may therefore contain junk. * STATUS = INTEGER (Given and Returned) * The global status. * Notes: * - This routine is only available in the Fortran interface to the * AST library. f-- */ /* Argument Pointers: */ GENPTR_CHARACTER(LINE) GENPTR_INTEGER(L) /* Local Variables: */ int i; /* Loop counter for characters */ /* Set the error context and watch the STATUS value. */ astAt( "AST_GETLINE", NULL, 0 ); astWatchSTATUS( /* Initialise the returned string length. */ *L = 0; /* Check the global error status. */ if ( !astOK ) return; /* If there is no outgoing line ready (e.g. if this routine has been called at an inappropriate point), we simply return nothing. Otherwise, loop to copy the text into the character argument supplied, ensuring that its length is not exceeded. */ if ( line_out ) { for ( i = 0; line_out[ i ] && ( i < LINE_length ); i++ ) { LINE[ i ] = line_out[ i ]; } /* Return the number of characters copied. */ *L = i; } ) } F77_SUBROUTINE(ast_putline)( CHARACTER(LINE), INTEGER(L), INTEGER(STATUS) TRAIL(LINE) ) { /* f++ * Name: * AST_PUTLINE * Purpose: * Store a text line read by a Channel source routine. * Type: * Public function. * Synopsis: * CALL AST_PUTLINE( LINE, L, STATUS ) * Description: * This routine should only be used when implementing a routine * which will be passed as the SOURCE argument to AST_CHANNEL. It * should be used to pass back (to the AST library) each line of * text read from the external data source. One such line should be * passed back in this way for each invocation of the source * routine. * Parameters: * LINE = CHARACTER * ( * ) (Given) * A character string containing the line of input text which * has been read. * L = INTEGER (Given) * The number of characters in the input line, which may be * zero. If there is no more input available (e.g. an end of * file has been reached), this value should be set negative and * this will terminate the read operation on the Channel. * STATUS = INTEGER (Given and Returned) * The global status. * Notes: * - This routine is only available in the Fortran interface to the * AST library. f-- */ /* Argument Pointers: */ GENPTR_CHARACTER(LINE) GENPTR_INTEGER(L) /* Local Variables: */ int l; /* Number of characters in line */ /* Set the error context and watch the STATUS value. */ astAt( "AST_PUTLINE", NULL, 0 ); astWatchSTATUS( /* Initialise the incoming line pointer. */ line_in = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Obtain the number of characters in the line. */ l = *L; /* Negative values (or STATUS set) indicate end of input. If the value is not negative, limit the number of characters to the length of the character variable supplied. */ if ( l >= 0 ) { if ( l > LINE_length ) l = LINE_length; /* Create a dynamic string and fill it with the incoming data. Store the resulting pointer, which will be picked up by the SourceWrap function. */ line_in = astString( LINE, l ); } ) } void astSinkWrap_( void (* sink)( const char * ), const char *line, int *status ) { /* *+ * Name: * astSinkWrap * Purpose: * Wrapper function to invoke a FORTRAN Channel sink function. * Type: * Protected function. * Synopsis: * void astSinkWrap( void (* sink)( const char * ), const char *line ) * Description: * This function invokes the sink function whose pointer is * supplied in order to write an output line to an external data * store. * Parameters: * sink * Pointer to a sink function. This should result from a cast * applied to a pointer to a function, with a single FORTRAN * INTEGER error status argument, that returns void. This is * the form of Channel sink function employed by the FORTRAN * language interface to the AST library. * line * Pointer to a constant null-terminated string containing the * line of output text. *- */ /* Local Variables; */ DECLARE_INTEGER(STATUS); /* FORTRAN error status variable */ /* Check the global error status. */ if ( !astOK ) return; /* Store the pointer to the output text line in the (static) "line_out" variable, where it will be accessed by the sink function invoking AST_GETLINE. */ line_out = line; /* Cast the sink function pointer to a pointer to the FORTRAN subroutine and then invoke it. Transfer the AST error status to and from the subroutine's error status argument. */ STATUS = astStatus; ( *(void (*)()) sink )( INTEGER_ARG(&STATUS) ); astSetStatus( STATUS ); /* Clear the outgoing line pointer. */ line_out = NULL; } char *astSourceWrap_( const char *(* source)( void ), int *status ) { /* *+ * Name: * astSourceWrap * Purpose: * Wrapper function to invoke a FORTRAN Channel source function. * Type: * Protected function. * Synopsis: * char *astSourceWrap( const char *(* source)( void ) ) * Description: * This function invokes the source function whose pointer is * supplied in order to read the next input line from an external * data store. It then returns a pointer to a dynamic string * containing a copy of the text that was read. * Parameters: * source * Pointer to a source function. This should result from a cast * applied to a pointer to a function, with a single FORTRAN * INTEGER error status argument, that returns void. This is * the form of Channel source function employed by the FORTRAN * language interface to the AST library. * Returned Value: * A pointer to a dynamically allocated, null terminated string * containing a copy of the text that was read. This string must be * freed by the caller (using astFree) when no longer required. * * A NULL pointer will be returned if there is no more input text * to read. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set or if it should fail * for any reason. *- */ /* Local Variables: */ DECLARE_INTEGER(STATUS); /* FORTRAN error status variable */ char *result; /* Result pointer to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise the incoming line pointer. */ line_in = NULL; /* Cast the source function pointer to a pointer to the FORTRAN subroutine and then invoke it. Transfer the AST error status to and from the subroutine's error status argument. */ STATUS = astStatus; ( *(void (*)()) source )( INTEGER_ARG(&STATUS) ); astSetStatus( STATUS ); /* This should result in a pointer to a dynamic string containing the input text being stored in the (static) "line_in" variable as a result of the source function invoking AST_PUTLINE. Save this string pointer and clear the original. */ result = line_in; line_in = NULL; /* If an error occurred, free the returned string. */ if ( ! astOK ) result = astFree( result ); /* Return the result. */ return result; } /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_INTEGER_FUNCTION(ast_channel)( void (* SOURCE)(), void (* SINK)(), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; const char *(* source)( void ); int i; void (* sink)( const char * ); astAt( "AST_CHANNEL", NULL, 0 ); astWatchSTATUS( /* Set the source and sink function pointers to NULL if a pointer to the null routine AST_NULL has been supplied. */ source = (const char *(*)( void )) SOURCE; if ( source == (const char *(*)( void )) F77_EXTERNAL_NAME(ast_null) ) { source = NULL; } sink = (void (*)( const char * )) SINK; if ( sink == (void (*)( const char * )) F77_EXTERNAL_NAME(ast_null) ) { sink = NULL; } options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astChannelFor( source, astSourceWrap, sink, astSinkWrap, "%s", options ) ); astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isachannel)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISACHANNEL", NULL, 0 ); astWatchSTATUS( RESULT = astIsAChannel( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_read)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_READ", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astRead( astI2P( *THIS ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_write)( INTEGER(THIS), INTEGER(OBJECT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(OBJECT) F77_INTEGER_TYPE(RESULT); astAt( "AST_WRITE", NULL, 0 ); astWatchSTATUS( RESULT = astWrite( astI2P( *THIS ), astI2P( *OBJECT ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_warnings)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_WARNINGS", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astWarnings( astI2P( *THIS ) ) ); ) return RESULT; } ast-8.3.0/ast_par.source0000664000175000017500000004330613004147320012107 00000000000000*+ * Name: * AST_PAR * Purpose: * Define the Fortran 77 interface to the AST library. * Language: * Fortran 77 * Type of Module: * Include file. * Description: * This file contains definitions which are required by Fortran 77 * programs which use the AST library. * Authors: * RFWS: R.F. Warren-Smith (STARLINK) * MBT: Mark Taylor (STARLINK) * DSB: David S. Berry * History: * 12-NOV-1996 (RFWS): * Original version. * 18-MAR-1998 (RFWS): * Added definitions for the IntraMap class. * 21-DEC-1998 (RFWS): * Added resampling definitions for the Mapping class. * 15-NOV-1999 (RFWS): * Added definitions for PcdMap. * 24-NOV-2000 (MBT): * Added AST__BLOCKAVE interpolation scheme. * 22-JUN-2001 (DSB): * Added AST_OFFSET2 and AST_ANGLE to Frame class. * 6-SEP-2001 (DSB): * Added AST_AXDISTANCE and AST_AXOFFSET to Frame class. * 12-SEP-2001 (DSB): * Added AST_BEAR to Frame class. * 21-SEP-2001 (DSB): * Replaced AST_BEAR by AST_AXANGLE. * 28-JAN-2003 (DSB): * Added AST_GETACTIVEUNIT. * 14-FEB-2003 (DSB): * Added new values for WcsMap projections. * 30-APR-2003 (DSB): * Added AST_VERSION. * 15-JUL-2003 (DSB): * Added AST_RATE, POLYMAP, SHIFTMAP and GRISMMAP functions. * 13-NOV-2003 (DSB): * Added XmlChan class. * 9-NOV-2004 (DSB): * Added all initial Region classes. * 19-NOV-2004 (DSB): * Added KeyMap. * 16-JUN-2005 (DSB): * Added TimeMap and TimeFrame. * 1-SEP-2005 (DSB): * Added AST__REBININIT and AST__REBINNORM. * 17-FEB-2006 (DSB): * Added AST_ESCAPES. * 9-FEB-2007 (DSB): * Use a double precision constant to initialise AST__UNDEFF. * 4-DEC-2008 (TIMJ): * Add AST_TESTFITS. Remove AST__UNDEF * 6-FEB-2009 (DSB): * Added StcsChan class. * 26-OCT-2016 (DSB): * Make angle constants double precision. *- * Length of character string returned by a character function. INTEGER AST__SZCHR PARAMETER ( AST__SZCHR = 200 ) * Bad coordinate value. DOUBLE PRECISION AST__BAD PARAMETER ( AST__BAD = ) * Double precision NaN flag (this value is not actually a NaN itself). DOUBLE PRECISION AST__NAN PARAMETER ( AST__NAN = ) * Single precision NaN flag (this value is not actually a NaN itself). REAL AST__NANR PARAMETER ( AST__NANR = ) * Error module. LOGICAL AST_OK INTEGER AST_STATUS * Object class. EXTERNAL AST_NULL INTEGER AST__NULL PARAMETER ( AST__NULL = 0 ) INTEGER AST__TUNULL PARAMETER ( AST__TUNULL = -99999 ) CHARACTER AST__TUNULLC*11 PARAMETER ( AST__TUNULLC = '' ) CHARACTER * ( AST__SZCHR ) AST_GETC DOUBLE PRECISION AST_GETD INTEGER AST_CLONE INTEGER AST_COPY LOGICAL AST_EQUAL INTEGER AST_GETI INTEGER AST_VERSION LOGICAL AST_GETL LOGICAL AST_ISAOBJECT LOGICAL AST_TEST LOGICAL AST_HASATTRIBUTE LOGICAL AST_SAME INTEGER AST_TUNE REAL AST_GETR LOGICAL AST_CHRSUB * Channel class. INTEGER AST_CHANNEL INTEGER AST_READ INTEGER AST_WRITE LOGICAL AST_ISACHANNEL INTEGER AST_WARNINGS * FitsChan class. INTEGER AST_FITSCHAN LOGICAL AST_FINDFITS LOGICAL AST_ISAFITSCHAN LOGICAL AST_GETFITSCF LOGICAL AST_GETFITSCI LOGICAL AST_GETFITSF LOGICAL AST_GETFITSI LOGICAL AST_GETFITSL LOGICAL AST_GETFITSS LOGICAL AST_GETFITSCN LOGICAL AST_TESTFITS INTEGER AST_GETTABLES CHARACTER AST__TABEXTNAME*7 PARAMETER ( AST__TABEXTNAME = 'WCS-TAB' ) INTEGER AST__NOTYPE PARAMETER ( AST__NOTYPE = -1 ) INTEGER AST__COMMENT PARAMETER ( AST__COMMENT = 0 ) INTEGER AST__INT PARAMETER ( AST__INT = 1 ) INTEGER AST__FLOAT PARAMETER ( AST__FLOAT = 2 ) INTEGER AST__STRING PARAMETER ( AST__STRING = 3 ) INTEGER AST__COMPLEXF PARAMETER ( AST__COMPLEXF = 4 ) INTEGER AST__COMPLEXI PARAMETER ( AST__COMPLEXI = 5 ) INTEGER AST__LOGICAL PARAMETER ( AST__LOGICAL = 6 ) INTEGER AST__CONTINUE PARAMETER ( AST__CONTINUE = 7 ) INTEGER AST__UNDEF PARAMETER ( AST__UNDEF = 8 ) * Mapping Class. INTEGER AST__URESAMP1 PARAMETER ( AST__URESAMP1 = 1 ) INTEGER AST__URESAMP2 PARAMETER ( AST__URESAMP2 = 2 ) INTEGER AST__URESAMP3 PARAMETER ( AST__URESAMP3 = 4 ) INTEGER AST__URESAMP4 PARAMETER ( AST__URESAMP4 = 8 ) INTEGER AST__USEVAR PARAMETER ( AST__USEVAR = 16 ) INTEGER AST__USEBAD PARAMETER ( AST__USEBAD = 32 ) INTEGER AST__CONSERVEFLUX PARAMETER ( AST__CONSERVEFLUX = 64 ) INTEGER AST__REBININIT PARAMETER ( AST__REBININIT = 128 ) INTEGER AST__REBINEND PARAMETER ( AST__REBINEND = 256 ) INTEGER AST__GENVAR PARAMETER ( AST__GENVAR = 512 ) INTEGER AST__VARWGT PARAMETER ( AST__VARWGT = 1024 ) INTEGER AST__NOBAD PARAMETER ( AST__NOBAD = 2048 ) INTEGER AST__DISVAR PARAMETER ( AST__DISVAR = 4096 ) INTEGER AST__NONORM PARAMETER ( AST__NONORM = 8192 ) INTEGER AST__UKERN1 PARAMETER ( AST__UKERN1 = 1 ) c Not yet implemented c INTEGER AST__UKERNN c PARAMETER ( AST__UKERNN = 2 ) INTEGER AST__UINTERP PARAMETER ( AST__UINTERP = 3 ) INTEGER AST__NEAREST PARAMETER ( AST__NEAREST = 4 ) INTEGER AST__LINEAR PARAMETER ( AST__LINEAR = 5 ) INTEGER AST__SINC PARAMETER ( AST__SINC = 6 ) INTEGER AST__SINCSINC PARAMETER ( AST__SINCSINC = 7 ) INTEGER AST__SINCCOS PARAMETER ( AST__SINCCOS = 8 ) INTEGER AST__SINCGAUSS PARAMETER ( AST__SINCGAUSS = 9 ) INTEGER AST__BLOCKAVE PARAMETER ( AST__BLOCKAVE = 10 ) INTEGER AST__GAUSS PARAMETER ( AST__GAUSS = 11 ) INTEGER AST__SOMB PARAMETER ( AST__SOMB = 12 ) INTEGER AST__SOMBCOS PARAMETER ( AST__SOMBCOS = 13 ) INTEGER AST_RESAMPLEB INTEGER AST_RESAMPLED INTEGER AST_RESAMPLEI INTEGER AST_RESAMPLEK INTEGER AST_RESAMPLER INTEGER AST_RESAMPLES INTEGER AST_RESAMPLEUB INTEGER AST_RESAMPLEUI INTEGER AST_RESAMPLEUK INTEGER AST_RESAMPLEUS INTEGER AST_RESAMPLEUW INTEGER AST_RESAMPLEW INTEGER AST_REMOVEREGIONS INTEGER AST_SIMPLIFY LOGICAL AST_ISAMAPPING LOGICAL AST_LINEARAPPROX LOGICAL AST_QUADAPPROX DOUBLE PRECISION AST_RATE * CmpMap class. INTEGER AST_CMPMAP LOGICAL AST_ISACMPMAP * Frame class. CHARACTER * ( AST__SZCHR ) AST_FORMAT DOUBLE PRECISION AST_DISTANCE INTEGER AST_CONVERT INTEGER AST_FINDFRAME INTEGER AST_FRAME INTEGER AST_PICKAXES INTEGER AST_UNFORMAT LOGICAL AST_ISAFRAME LOGICAL AST_GETACTIVEUNIT DOUBLE PRECISION AST_ANGLE DOUBLE PRECISION AST_OFFSET2 DOUBLE PRECISION AST_AXDISTANCE DOUBLE PRECISION AST_AXOFFSET DOUBLE PRECISION AST_AXANGLE * CmpFrame class. INTEGER AST_CMPFRAME LOGICAL AST_ISACMPFRAME * FrameSet class. INTEGER AST__BASE PARAMETER ( AST__BASE = 0 ) INTEGER AST__CURRENT PARAMETER ( AST__CURRENT = -1 ) INTEGER AST__NOFRAME PARAMETER ( AST__NOFRAME = -99 ) INTEGER AST_FRAMESET INTEGER AST_GETFRAME INTEGER AST_GETMAPPING LOGICAL AST_ISAFRAMESET * IntraMap class. INTEGER AST__NOFWD PARAMETER ( AST__NOFWD = 1 ) INTEGER AST__NOINV PARAMETER ( AST__NOINV = 2 ) INTEGER AST__SIMPFI PARAMETER ( AST__SIMPFI = 4 ) INTEGER AST__SIMPIF PARAMETER ( AST__SIMPIF = 8 ) INTEGER AST__ANY PARAMETER ( AST__ANY = -66 ) INTEGER AST_INTRAMAP LOGICAL AST_ISAINTRAMAP * LutMap class. INTEGER AST_LUTMAP LOGICAL AST_ISALUTMAP * PcdMap class. INTEGER AST_PCDMAP LOGICAL AST_ISAPCDMAP * Plot class. INTEGER AST_PLOT LOGICAL AST_BORDER INTEGER AST_GETGRFCONTEXT LOGICAL AST_ISAPLOT INTEGER AST_ESCAPES CHARACTER * ( AST__SZCHR ) AST_STRIPESCAPES * SkyFrame class. INTEGER AST_SKYFRAME LOGICAL AST_ISASKYFRAME INTEGER AST_SKYOFFSETMAP * SpecFrame class. INTEGER AST_SPECFRAME LOGICAL AST_ISASPECFRAME * DSBSpecFrame class. INTEGER AST_DSBSPECFRAME LOGICAL AST_ISADSBSPECFRAME * MathMap class. INTEGER AST_MATHMAP LOGICAL AST_ISAMATHMAP * MatrixMap class. INTEGER AST_MATRIXMAP LOGICAL AST_ISAMATRIXMAP * PermMap class. INTEGER AST_PERMMAP LOGICAL AST_ISAPERMMAP * PolyMap class. INTEGER AST_POLYMAP LOGICAL AST_ISAPOLYMAP INTEGER AST_POLYTRAN * SlaMap class. INTEGER AST_SLAMAP LOGICAL AST_ISASLAMAP * SpecMap class. INTEGER AST_SPECMAP LOGICAL AST_ISASPECMAP * SphMap class. INTEGER AST_SPHMAP LOGICAL AST_ISASPHMAP * UnitMap class. INTEGER AST_UNITMAP LOGICAL AST_ISAUNITMAP * WcsMap class. INTEGER AST__WCSMX PARAMETER ( AST__WCSMX = 10 ) DOUBLE PRECISION AST__DPI PARAMETER ( AST__DPI = 3.1415926535897932384626433832795028842D0 ) DOUBLE PRECISION AST__DPIBY2 PARAMETER ( AST__DPIBY2 = 1.5707963267948966192313216916397514D0 ) DOUBLE PRECISION AST__DD2R PARAMETER ( AST__DD2R = 0.017453292519943295769236907684886127D0 ) DOUBLE PRECISION AST__DR2D PARAMETER ( AST__DR2D = 57.29577951308232087679815481410517033D0 ) INTEGER AST__AIR PARAMETER ( AST__AIR = 9 ) INTEGER AST__AIT PARAMETER ( AST__AIT = 17 ) INTEGER AST__ARC PARAMETER ( AST__ARC = 6 ) INTEGER AST__AZP PARAMETER ( AST__AZP = 1 ) INTEGER AST__BON PARAMETER ( AST__BON = 22 ) INTEGER AST__CAR PARAMETER ( AST__CAR = 12 ) INTEGER AST__CEA PARAMETER ( AST__CEA = 11 ) INTEGER AST__COD PARAMETER ( AST__COD = 20 ) INTEGER AST__COE PARAMETER ( AST__COE = 19 ) INTEGER AST__COO PARAMETER ( AST__COO = 21 ) INTEGER AST__COP PARAMETER ( AST__COP = 18 ) INTEGER AST__CSC PARAMETER ( AST__CSC = 25 ) INTEGER AST__CYP PARAMETER ( AST__CYP = 10 ) INTEGER AST__GLS PARAMETER ( AST__GLS = 28 ) INTEGER AST__HPX PARAMETER ( AST__HPX = 30 ) INTEGER AST__MER PARAMETER ( AST__MER = 13 ) INTEGER AST__MOL PARAMETER ( AST__MOL = 16 ) INTEGER AST__NCP PARAMETER ( AST__NCP = 27 ) INTEGER AST__PAR PARAMETER ( AST__PAR = 15 ) INTEGER AST__PCO PARAMETER ( AST__PCO = 23 ) INTEGER AST__QSC PARAMETER ( AST__QSC = 26 ) INTEGER AST__SFL PARAMETER ( AST__SFL = 14 ) INTEGER AST__SIN PARAMETER ( AST__SIN = 5 ) INTEGER AST__STG PARAMETER ( AST__STG = 4 ) INTEGER AST__SZP PARAMETER ( AST__SZP = 2 ) INTEGER AST__TAN PARAMETER ( AST__TAN = 3 ) INTEGER AST__TPN PARAMETER ( AST__TPN = 29 ) INTEGER AST__TSC PARAMETER ( AST__TSC = 24 ) INTEGER AST__XPH PARAMETER ( AST__XPH = 31 ) INTEGER AST__ZEA PARAMETER ( AST__ZEA = 8 ) INTEGER AST__ZPN PARAMETER ( AST__ZPN = 7 ) INTEGER AST__WCSBAD PARAMETER ( AST__WCSBAD = 32 ) INTEGER AST_WCSMAP LOGICAL AST_ISAWCSMAP * ShiftMap class. INTEGER AST_SHIFTMAP LOGICAL AST_ISASHIFTMAP * WinMap class. INTEGER AST_WINMAP LOGICAL AST_ISAWINMAP * ZoomMap class. INTEGER AST_ZOOMMAP LOGICAL AST_ISAZOOMMAP * GrismMap class. INTEGER AST_GRISMMAP LOGICAL AST_ISAGRISMMAP * XmlChan class. INTEGER AST_XMLCHAN LOGICAL AST_ISAXMLCHAN * TranMap class. INTEGER AST_TRANMAP LOGICAL AST_ISATRANMAP * Region class. INTEGER AST_REGION INTEGER AST_GETUNC INTEGER AST_GETREGIONFRAME LOGICAL AST_ISAREGION INTEGER AST_MAPREGION INTEGER AST_OVERLAP INTEGER AST_MASKB INTEGER AST_MASKD INTEGER AST_MASKI INTEGER AST_MASKR INTEGER AST_MASKS INTEGER AST_MASKUB INTEGER AST_MASKUI INTEGER AST_MASKUS INTEGER AST_MASKUW INTEGER AST_MASKW * Box class. INTEGER AST_BOX LOGICAL AST_ISABOX * PointList class. INTEGER AST_POINTLIST LOGICAL AST_ISAPOINTLIST * Polygon class. INTEGER AST_POLYGON LOGICAL AST_ISAPOLYGON INTEGER AST_DOWNSIZE INTEGER AST_OUTLINED INTEGER AST_OUTLINER INTEGER AST_OUTLINEI INTEGER AST_OUTLINEUI INTEGER AST_OUTLINES INTEGER AST_OUTLINEUS INTEGER AST_OUTLINEW INTEGER AST_OUTLINEUW INTEGER AST_OUTLINEB INTEGER AST_OUTLINEUB INTEGER AST_CONVEXD INTEGER AST_CONVEXR INTEGER AST_CONVEXI INTEGER AST_CONVEXUI INTEGER AST_CONVEXS INTEGER AST_CONVEXUS INTEGER AST_CONVEXW INTEGER AST_CONVEXUW INTEGER AST_CONVEXB INTEGER AST_CONVEXUB INTEGER AST__LE PARAMETER( AST__LE = 2 ) INTEGER AST__EQ PARAMETER( AST__EQ = 3 ) INTEGER AST__GE PARAMETER( AST__GE = 4 ) INTEGER AST__GT PARAMETER( AST__GT = 5 ) INTEGER AST__NE PARAMETER( AST__NE = 6 ) * Circle class. INTEGER AST_CIRCLE LOGICAL AST_ISACIRCLE * Ellipse class. INTEGER AST_ELLIPSE LOGICAL AST_ISAELLIPSE * NullRegion class. INTEGER AST_NULLREGION LOGICAL AST_ISANULLREGION * Interval class. INTEGER AST_INTERVAL LOGICAL AST_ISAINTERVAL * Prism class. INTEGER AST_PRISM LOGICAL AST_ISAPRISM * CmpRegion class. INTEGER AST_CMPREGION LOGICAL AST_ISACMPREGION INTEGER AST__AND PARAMETER( AST__AND = 1 ) INTEGER AST__OR PARAMETER( AST__OR = 2 ) INTEGER AST__XOR PARAMETER( AST__XOR = 3 ) * KeyMap class. INTEGER AST_KEYMAP LOGICAL AST_ISAKEYMAP LOGICAL AST_MAPGET0I LOGICAL AST_MAPGET0S LOGICAL AST_MAPGET0B LOGICAL AST_MAPGET0D LOGICAL AST_MAPGET0R LOGICAL AST_MAPGET0C LOGICAL AST_MAPGET0A LOGICAL AST_MAPGET1I LOGICAL AST_MAPGET1B LOGICAL AST_MAPGET1S LOGICAL AST_MAPGET1D LOGICAL AST_MAPGET1R LOGICAL AST_MAPGET1C LOGICAL AST_MAPGET1A LOGICAL AST_MAPGETELEMI LOGICAL AST_MAPGETELEMS LOGICAL AST_MAPGETELEMB LOGICAL AST_MAPGETELEMD LOGICAL AST_MAPGETELEMR LOGICAL AST_MAPGETELEMC LOGICAL AST_MAPGETELEMA INTEGER AST_MAPSIZE INTEGER AST_MAPLENGTH INTEGER AST_MAPLENC INTEGER AST_MAPTYPE LOGICAL AST_MAPHASKEY LOGICAL AST_MAPDEFINED CHARACTER * ( AST__SZCHR ) AST_MAPKEY INTEGER AST__BADTYPE PARAMETER ( AST__BADTYPE = 0) INTEGER AST__INTTYPE PARAMETER ( AST__INTTYPE = 1) INTEGER AST__DOUBLETYPE PARAMETER ( AST__DOUBLETYPE = 2) INTEGER AST__STRINGTYPE PARAMETER ( AST__STRINGTYPE = 3) INTEGER AST__OBJECTTYPE PARAMETER ( AST__OBJECTTYPE = 4) INTEGER AST__FLOATTYPE PARAMETER ( AST__FLOATTYPE = 5) INTEGER AST__SINTTYPE PARAMETER ( AST__SINTTYPE = 7) INTEGER AST__UNDEFTYPE PARAMETER ( AST__UNDEFTYPE = 8) INTEGER AST__BYTETYPE PARAMETER ( AST__BYTETYPE = 9) * FluxFrame class. INTEGER AST_FLUXFRAME LOGICAL AST_ISAFLUXFRAME * SpecFluxFrame class. INTEGER AST_SPECFLUXFRAME LOGICAL AST_ISASPECFLUXFRAME * NormMap class. INTEGER AST_NORMMAP LOGICAL AST_ISANORMMAP * RateMap class. INTEGER AST_RATEMAP LOGICAL AST_ISARATEMAP * TimeFrame class. INTEGER AST_TIMEFRAME LOGICAL AST_ISATIMEFRAME DOUBLE PRECISION AST_CURRENTTIME INTEGER AST__LT PARAMETER( AST__LT = 11 ) * TimeMap class. INTEGER AST_TIMEMAP LOGICAL AST_ISATIMEMAP * Stc class. LOGICAL AST_ISASTC INTEGER AST_GETSTCREGION INTEGER AST_GETSTCCOORD INTEGER AST_GETSTCNCOORD CHARACTER AST__STCNAME*4 PARAMETER ( AST__STCNAME = 'Name' ) CHARACTER AST__STCVALUE*5 PARAMETER ( AST__STCVALUE = 'Value' ) CHARACTER AST__STCERROR*5 PARAMETER ( AST__STCERROR = 'Error' ) CHARACTER AST__STCRES*10 PARAMETER ( AST__STCRES = 'Resolution' ) CHARACTER AST__STCSIZE*4 PARAMETER ( AST__STCSIZE = 'Size' ) CHARACTER AST__STCPIXSZ*7 PARAMETER ( AST__STCPIXSZ = 'PixSize' ) * StcSearchLocation class. LOGICAL AST_ISASTCSEARCHLOCATION INTEGER AST_STCSEARCHLOCATION * StcCatalogEntryLocation class. LOGICAL AST_ISASTCCATALOGENTRYLOCATION INTEGER AST_STCCATALOGENTRYLOCATION * StcResourceProfile class. LOGICAL AST_ISASTCRESOURCEPROFILE INTEGER AST_STCRESOURCEPROFILE * StcObsDataLocation class. LOGICAL AST_ISASTCOBSDATALOCATION INTEGER AST_STCOBSDATALOCATION * SwitchMap class. INTEGER AST_SWITCHMAP LOGICAL AST_ISASWITCHMAP * SelectorMap class. INTEGER AST_SELECTORMAP LOGICAL AST_ISASELECTORMAP * Plot3D class. INTEGER AST_PLOT3D LOGICAL AST_ISAPLOT3D * StcsChan class. INTEGER AST_STCSCHAN LOGICAL AST_ISASTCSCHAN * Table class. INTEGER AST_TABLE LOGICAL AST_ISATABLE LOGICAL AST_HASCOLUMN CHARACTER * ( AST__SZCHR ) AST_COLUMNNAME LOGICAL AST_HASPARAMETER CHARACTER * ( AST__SZCHR ) AST_PARAMETERNAME * FitsTable class. INTEGER AST_FITSTABLE LOGICAL AST_ISAFITSTABLE INTEGER AST_COLUMNNULL INTEGER AST_COLUMNSIZE INTEGER AST_GETTABLEHEADER * UnitNormMap class. INTEGER AST_UNITNORMMAP LOGICAL AST_ISAUNITNORMMAP ast-8.3.0/fobject.c0000664000175000017500000004301113004147321011006 00000000000000/* *+ * Name: * fobject.c * Purpose: * Define a FORTRAN 77 interface to the AST Object class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Object class. * Routines Defined: * AST_ANNUL * AST_BEGIN * AST_CLEAR * AST_CLONE * AST_COPY * AST_DELETE * AST_END * AST_ESCAPES * AST_EXEMPT * AST_EXPORT * AST_GET(C,D,I,L,R) * AST_ISAOBJECT * AST_NULL * AST_SET * AST_SET(C,D,I,L,R) * AST_SHOW * AST_VERSION * AST_LISTISSUED (only if macro DEBUG is defined) * AST_SETWATCHID (only if macro DEBUG is defined) * AST_TUNE * AST_TUNEC * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 20-JUN-1996 (RFWS): * Original version. * 9-SEP-1996 (RFWS): * Added AST_SHOW. * 11-DEC-1996 (RFWS): * Added AST_NULL. * 14-JUL-1997 (RFWS): * Add AST_EXEMPT function. * 30-APR-2003 (DSB): * Add AST_VERSION function. * 7-FEB-2004 (DSB): * Add AST_ESCAPES function. * 27-JAN-2005 (DSB): * Added AST_LISTISSUED and AST_SETWATCHID so that DEBUG facilities * can be used from fortran. * 7-FEB-2006 (DSB): * Added AST_TUNE. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 13-OCT-2011 (DSB): * Added AST_TUNEC. *- */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* AST headers */ /* ----------- */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "object.h" /* C interface to the Object class */ F77_SUBROUTINE(ast_annul)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_ANNUL", NULL, 0 ); astWatchSTATUS( *THIS = astP2I( astAnnul( astI2P( *THIS ) ) ); ) } F77_SUBROUTINE(ast_begin)( INTEGER(STATUS) ) { astAt( "AST_BEGIN", NULL, 0 ); astWatchSTATUS( int dummy = *status; /* Avoid "unused variable 'status'" messages */ *status = dummy; astBegin; ) } F77_SUBROUTINE(ast_clear)( INTEGER(THIS), CHARACTER(ATTRIB), INTEGER(STATUS) TRAIL(ATTRIB) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) char *attrib; astAt( "AST_CLEAR", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); astClear( astI2P( *THIS ), attrib ); astFree( attrib ); ) } F77_INTEGER_FUNCTION(ast_clone)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_CLONE", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astClone( astI2P( *THIS ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_version)( ) { int status_value = 0; int *STATUS = &status_value; int *status = &status_value; astAt( "AST_VERSION", NULL, 0 ); return astVersion; } F77_INTEGER_FUNCTION(ast_escapes)( INTEGER(NEWVAL), INTEGER(STATUS) ) { GENPTR_INTEGER(NEWVAL) F77_INTEGER_TYPE(RESULT); astAt( "AST_ESCAPES", NULL, 0 ); astWatchSTATUS( RESULT = astEscapes( *NEWVAL ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_copy)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_COPY", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astCopy( astI2P( *THIS ) ) ); ) return RESULT; } F77_SUBROUTINE(ast_delete)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_DELETE", NULL, 0 ); astWatchSTATUS( *THIS = astP2I( astDelete( astI2P( *THIS ) ) ); ) } F77_SUBROUTINE(ast_end)( INTEGER(STATUS) ) { astAt( "AST_END", NULL, 0 ); astWatchSTATUS( astEnd; ) } F77_SUBROUTINE(ast_exempt)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_EXEMPT", NULL, 0 ); astWatchSTATUS( astExempt( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_export)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_EXPORT", NULL, 0 ); astWatchSTATUS( astExport( astI2P( *THIS ) ); ) } #define MAKE_GETX(name,code,TYPE,CODE,type) \ F77_##TYPE##_FUNCTION(ast_get##code)( INTEGER(THIS), \ CHARACTER(ATTRIB), \ INTEGER(STATUS) \ TRAIL(ATTRIB) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_CHARACTER(ATTRIB) \ F77_##TYPE##_TYPE(RESULT); \ char *attrib; \ \ astAt( name, NULL, 0 ); \ astWatchSTATUS( \ attrib = astString( ATTRIB, ATTRIB_length ); \ RESULT = astGet##CODE( astI2P( *THIS ), attrib ); \ astFree( attrib ); \ ) \ return RESULT; \ } MAKE_GETX("AST_GETD",d,DOUBLE,D,double) MAKE_GETX("AST_GETI",i,INTEGER,L,long) MAKE_GETX("AST_GETR",r,REAL,D,double) /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file object.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_getc_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_getc)( CHARACTER_RETURN_VALUE(RESULT), #endif INTEGER(THIS), CHARACTER(ATTRIB), INTEGER(STATUS) #if NO_CHAR_FUNCTION TRAIL(RESULT) #endif TRAIL(ATTRIB) ) { GENPTR_CHARACTER(RESULT) GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) char *attrib; const char *result; int i; astAt( "AST_GETC", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); result = astGetC( astI2P( *THIS ), attrib ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ astFree( attrib ); ) } F77_LOGICAL_FUNCTION(ast_getl)( INTEGER(THIS), CHARACTER(ATTRIB), INTEGER(STATUS) TRAIL(ATTRIB) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) F77_LOGICAL_TYPE(RESULT); char *attrib; astAt( "AST_GETL", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); RESULT = astGetL( astI2P( *THIS ), attrib ) ? F77_TRUE : F77_FALSE; astFree( attrib ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isaobject)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAOBJECT", NULL, 0 ); astWatchSTATUS( RESULT = astIsAObject( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_SUBROUTINE(ast_null)( void ) {} /* Omit the C variable length argument list here. */ F77_SUBROUTINE(ast_set)( INTEGER(THIS), CHARACTER(SETTING), INTEGER(STATUS) TRAIL(SETTING) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(SETTING) char *setting; int i; int quoted; astAt( "AST_SET", NULL, 0 ); astWatchSTATUS( setting = astString( SETTING, SETTING_length ); /* Truncate the string to exclude any trailing spaces. */ astChrTrunc( setting ); /* Change ',' to '\n' (which is what astSet normally does to its second argument internally to separate the fields). This then allows "setting" to be provided as an additional string value to be formatted using "%s". This avoids interpretation of its contents (e.g. '%') as C format specifiers. */ if ( astOK ) { quoted = 0; for ( i = 0; setting[ i ]; i++ ) { if( !quoted ) { if ( setting[ i ] == ',' ) { setting[ i ] = '\n'; } else if( setting[ i ] == '"' ) { quoted = 1; } } else if( setting[ i ] == '"' ){ quoted = 0; } } } astSet( astI2P( *THIS ), "%s", setting ); astFree( setting ); ) } #define MAKE_SETX(name,code,TYPE,CODE,type) \ F77_SUBROUTINE(ast_set##code)( INTEGER(THIS), \ CHARACTER(ATTRIB), \ TYPE(VALUE), \ INTEGER(STATUS) \ TRAIL(ATTRIB) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_CHARACTER(ATTRIB) \ GENPTR_##TYPE(VALUE) \ char *attrib; \ \ astAt( name, NULL, 0 ); \ astWatchSTATUS( \ attrib = astString( ATTRIB, ATTRIB_length ); \ astSet##CODE( astI2P( *THIS ), attrib, *VALUE ); \ astFree( attrib ); \ ) \ } MAKE_SETX("AST_SETD",d,DOUBLE,D,double) MAKE_SETX("AST_SETR",r,REAL,D,double) MAKE_SETX("AST_SETI",i,INTEGER,L,long) F77_SUBROUTINE(ast_setc)( INTEGER(THIS), CHARACTER(ATTRIB), CHARACTER(VALUE), INTEGER(STATUS) TRAIL(ATTRIB) TRAIL(VALUE) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) GENPTR_CHARACTER(VALUE) char *attrib, *value; astAt( "AST_SETC", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); value = astString( VALUE, VALUE_length ); /* Truncate the strings to exclude any trailing spaces. */ astChrTrunc( attrib ); astChrTrunc( value ); astSetC( astI2P( *THIS ), attrib, value ); astFree( attrib ); astFree( value ); ) } F77_SUBROUTINE(ast_setl)( INTEGER(THIS), CHARACTER(ATTRIB), LOGICAL(VALUE), INTEGER(STATUS) TRAIL(ATTRIB) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) GENPTR_LOGICAL(VALUE) char *attrib; astAt( "AST_SETL", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); astSetI( astI2P( *THIS ), attrib, F77_ISTRUE( *VALUE ) ? 1 : 0 ); astFree( attrib ); ) } F77_SUBROUTINE(ast_show)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_SHOW", NULL, 0 ); astWatchSTATUS( astShow( astI2P( *THIS ) ); ) } F77_LOGICAL_FUNCTION(ast_test)( INTEGER(THIS), CHARACTER(ATTRIB), INTEGER(STATUS) TRAIL(ATTRIB) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) F77_LOGICAL_TYPE(RESULT); char *attrib; astAt( "AST_TEST", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); RESULT = astTest( astI2P( *THIS ), attrib ) ? F77_TRUE : F77_FALSE; astFree( attrib ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_hasattribute)( INTEGER(THIS), CHARACTER(ATTRIB), INTEGER(STATUS) TRAIL(ATTRIB) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(ATTRIB) F77_LOGICAL_TYPE(RESULT); char *attrib; astAt( "AST_HASATTRIBUTE", NULL, 0 ); astWatchSTATUS( attrib = astString( ATTRIB, ATTRIB_length ); RESULT = astHasAttribute( astI2P( *THIS ), attrib ) ? F77_TRUE : F77_FALSE; astFree( attrib ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_same)( INTEGER(THIS), INTEGER(THAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(THAT) F77_LOGICAL_TYPE(RESULT); astAt( "AST_SAME", NULL, 0 ); astWatchSTATUS( RESULT = astSame( astI2P( *THIS ), astI2P( *THAT ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } #ifdef MEM_DEBUG F77_SUBROUTINE(ast_beginpm)( void ) { int status = 0; astBeginPM_( &status ); } F77_SUBROUTINE(ast_endpm)( void ) { int status = 0; astEndPM_( &status ); } F77_SUBROUTINE(ast_activememory)( CHARACTER(TEXT) TRAIL(TEXT) ) { GENPTR_CHARACTER(TEXT) char *text; int status_value; int *status = &status_value; *status = 0; astBeginPM; text = astString( TEXT, TEXT_length ); astEndPM; astActiveMemory( text ); astFree( text ); } F77_SUBROUTINE(ast_watchmemory)( INTEGER(ID) ) { GENPTR_INTEGER(ID) astWatchMemory( *ID ); } F77_SUBROUTINE(ast_flushmemory)( INTEGER(LEAK) ) { GENPTR_INTEGER(LEAK) int status = 0; astFlushMemory_( *LEAK, &status ); } #else F77_SUBROUTINE(ast_activememory)( CHARACTER(TEXT) TRAIL(TEXT) ) { GENPTR_CHARACTER(TEXT) } F77_SUBROUTINE(ast_watchmemory)( INTEGER(ID) ) { GENPTR_INTEGER(ID) } F77_SUBROUTINE(ast_flushmemory)( INTEGER(LEAK) ) { GENPTR_INTEGER(LEAK) } F77_SUBROUTINE(ast_beginpm)( void ) { } F77_SUBROUTINE(ast_endpm)( void ) { } #endif F77_INTEGER_FUNCTION(ast_tune)( CHARACTER(NAME), INTEGER(VALUE), INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(VALUE) GENPTR_CHARACTER(NAME) F77_INTEGER_TYPE(RESULT); char *name; astAt( "AST_TUNE", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); RESULT = astTune( name, *VALUE ); name = astFree( name ); ) return RESULT; } F77_SUBROUTINE(ast_tunec)( CHARACTER(NAME), CHARACTER(VALUE), CHARACTER(BUFF), INTEGER(STATUS) TRAIL(NAME) TRAIL(VALUE) TRAIL(BUFF) ) { GENPTR_CHARACTER(NAME) GENPTR_CHARACTER(VALUE) GENPTR_CHARACTER(BUFF) char *name; char *value; char *buff; astAt( "AST_TUNEC", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); value = astString( VALUE, VALUE_length ); if( value && !strcmp( value, AST__TUNULLC ) ) value = astFree( value ); buff = astMalloc( BUFF_length + 1 ); astTuneC( name, value, buff, BUFF_length + 1 ); int i = 0; if( astOK ) { for ( ; buff[ i ] && i < BUFF_length; i++ ) { BUFF[ i ] = buff[ i ]; } } while ( i < BUFF_length ) BUFF[ i++ ] = ' '; /* Pad with blanks */ buff = astFree( buff ); name = astFree( name ); value = astFree( value ); ) } F77_LOGICAL_FUNCTION(ast_chrsub)( CHARACTER(TEST), CHARACTER(PATTERN), CHARACTER(RESULT), INTEGER(STATUS) TRAIL(TEST) TRAIL(PATTERN) TRAIL(RESULT) ) { GENPTR_CHARACTER(TEST) GENPTR_CHARACTER(PATTERN) GENPTR_CHARACTER(RESULT) F77_LOGICAL_TYPE(MATCH); char *test, *pattern, *result; int i; astAt( "AST_CHRSUB", NULL, 0 ); astWatchSTATUS( test = astString( TEST, TEST_length ); pattern = astString( PATTERN, PATTERN_length ); if( pattern ) { test[ astChrLen( test ) ] = 0; pattern[ astChrLen( pattern ) ] = 0; } result = astChrSub( test, pattern, NULL, 0 ); i = 0; if( result ) { MATCH = F77_TRUE; for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } result = astFree( result ); } else { MATCH = F77_FALSE; } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ test = astFree( test ); pattern = astFree( pattern ); ) return MATCH; } F77_LOGICAL_FUNCTION(ast_equal)( INTEGER(THIS), INTEGER(THAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(THAT) F77_LOGICAL_TYPE(RESULT); astAt( "AST_EQUAL", NULL, 0 ); astWatchSTATUS( RESULT = astEqual( astI2P( *THIS ), astI2P( *THAT ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } ast-8.3.0/stcobsdatalocation.c0000664000175000017500000011144413004147321013260 00000000000000/* *class++ * Name: * StcObsDataLocation * Purpose: * Correspond to the IVOA ObsDataLocation class. * Constructor Function: c astStcObsDataLocation f AST_STCOBSDATALOCATION * Description: * The StcObsDataLocation class is a sub-class of Stc used to describe * the coordinate space occupied by a particular observational dataset. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * * An STC ObsDataLocation element specifies the extent of the * observation within a specified coordinate system, and also specifies * the observatory location within a second coordinate system. * * The AST StcObsDataLocation class inherits from Stc, and therefore * an StcObsDataLocation can be used directly as an Stc. When used * in this way, the StcObsDataLocation describes the location of the * observation (not the observatory). * * Eventually, this class will have a method for returning an Stc * describing the observatory location. However, AST currently does not * include any classes of Frame for describing terrestrial or solar * system positions. Therefore, the provision for returning observatory * location as an Stc is not yet available. However, for terrestrial * observations, the position of the observatory can still be recorded * using the ObsLon and ObsLat attributes of the Frame encapsulated * within the Stc representing the observation location (this assumes * the observatory is located at sea level). * Inheritance: * The StcObsDataLocation class inherits from the Stc class. * Attributes: * The StcObsDataLocation class does not define any new attributes beyond * those which are applicable to all Stcs. * Functions: c The StcObsDataLocation class does not define any new functions beyond those f The StcObsDataLocation class does not define any new routines beyond those * which are applicable to all Stcs. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 25-APR-2005 (DSB): * Original version. * 14-FEB-2006 (DSB): * Override astGetObjSize. *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 StcObsDataLocation /* Include 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 "stc.h" /* Coordinate stcs (parent class) */ #include "channel.h" /* I/O channels */ #include "region.h" /* Regions within coordinate systems */ #include "pointlist.h" /* Points within coordinate systems */ #include "stcobsdatalocation.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(StcObsDataLocation) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(StcObsDataLocation,Class_Init) #define class_vtab astGLOBAL(StcObsDataLocation,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstStcObsDataLocationVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstStcObsDataLocation *astStcObsDataLocationId_( void *, int, AstKeyMap **, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void StcSetObs( AstStcObsDataLocation *, AstPointList *, int * ); static int GetObjSize( AstObject *, int * ); /* Member functions. */ /* ================= */ static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "stcobsdatalocation.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * StcObsDataLocation member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied StcObsDataLocation, * in bytes. * Parameters: * this * Pointer to the StcObsDataLocation. * 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: */ AstStcObsDataLocation *this; /* Pointer to StcObsDataLocation structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the StcObsDataLocation structure. */ this = (AstStcObsDataLocation *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->obs ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitStcObsDataLocationVtab_( AstStcObsDataLocationVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitStcObsDataLocationVtab * Purpose: * Initialise a virtual function table for a StcObsDataLocation. * Type: * Protected function. * Synopsis: * #include "stcobsdatalocation.h" * void astInitStcObsDataLocationVtab( AstStcObsDataLocationVtab *vtab, const char *name ) * Class Membership: * StcObsDataLocation vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the StcObsDataLocation 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstStcVtab *stc; /* Pointer to Stc 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. */ astInitStcVtab( (AstStcVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAStcObsDataLocation) 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 = &(((AstStcVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; stc = (AstStcVtab *) vtab; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ vtab->StcSetObs = StcSetObs; /* Declare the copy constructor, destructor and class dump functions. */ astSetDump( vtab, Dump, "StcObsDataLocation", "Observation coverage" ); astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); /* 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 StcSetObs( AstStcObsDataLocation *this, AstPointList *obs, int *status ) { /* *+ * Name: * astStcSetObs * Purpose: * Set the observatory position within an StcObsDataLocation. * Type: * Protected function. * Synopsis: * #include "region.h" * void astStcSetObs( AstStcObsDataLocation *this, AstPointList *obs ) * Class Membership: * StcObsDataLocation virtual function * Description: * This function stores a clone of the supplied PointList pointer * within the supplied StcObsDataLocation, first annulling any * pointer already stored in the StcObsDataLocation. * Parameters: * this * Pointer to the StcObsDataLocation. * obs * Pointer to a PointList defining the observatory position. NULL * may be supplied in which case any existing observatory position * is removed. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Free any existing obseravtory position PointList. */ if( this->obs ) this->obs = astAnnul( this->obs ); /* Store any supplied pointer. */ if( obs ) this->obs = astClone( obs ); } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for StcObsDataLocation objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for StcObsDataLocation * objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Regions within the StcObsDataLocation. */ /* Local Variables: */ AstStcObsDataLocation *in; /* Pointer to input StcObsDataLocation */ AstStcObsDataLocation *out; /* Pointer to output StcObsDataLocation */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output StcObsDataLocations. */ in = (AstStcObsDataLocation *) objin; out = (AstStcObsDataLocation *) objout; /* For safety, start by clearing any references to the input component Regions, etc, from the output StcObsDataLocation. */ out->obs = NULL; /* Make a copy of the Observatory location */ if( in->obs ) out->obs = astCopy( in->obs ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for StcObsDataLocation objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for StcObsDataLocation objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstStcObsDataLocation *this; /* Pointer to StcObsDataLocation */ /* Obtain a pointer to the StcObsDataLocation structure. */ this = (AstStcObsDataLocation *) obj; /* Annul the pointer to the observatory location Region. */ if( this->obs ) this->obs = astAnnul( this->obs ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for StcObsDataLocation 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 StcObsDataLocation class to an output Channel. * Parameters: * this * Pointer to the StcObsDataLocation 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 Variables: */ AstStcObsDataLocation *this; /* Pointer to the StcObsDataLocation structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the StcObsDataLocation structure. */ this = (AstStcObsDataLocation *) this_object; /* Write out values representing the instance variables for the StcObsDataLocation 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. */ /* Observatory position. */ /* --------------------- */ astWriteObject( channel, "ObsLoc", 1, 1, this->obs, "Observatory position" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAStcObsDataLocation and astCheckStcObsDataLocation functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(StcObsDataLocation,Stc) astMAKE_CHECK(StcObsDataLocation) AstStcObsDataLocation *astStcObsDataLocation_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, int *status, ...) { /* *++ * Name: c astStcObsDataLocation f AST_STCOBSDATALOCATION * Purpose: * Create a StcObsDataLocation. * Type: * Public function. * Synopsis: c #include "stcobsdatalocation.h" c AstStcObsDataLocation *astStcObsDataLocation( AstRegion *region, c int ncoords, AstKeyMap *coords[], const char *options, ... ) f RESULT = AST_STCOBSDATALOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) * Class Membership: * StcObsDataLocation constructor. * Description: * This function creates a new StcObsDataLocation and optionally initialises its * attributes. * * The StcObsDataLocation class is a sub-class of Stc used to describe * the coverage of the datasets contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Parameters: c region f REGION = INTEGER (Given) * Pointer to the encapsulated Region. c ncoords f NCOORDS = INTEGER (Given) c The length of the "coords" array. Supply zero if "coords" is NULL. f The length of the COORDS array. Supply zero if COORDS should be f ignored. c coords f COORDS( NCOORDS ) = INTEGER (Given) c Pointer to an array holding "ncoords" AstKeyMap pointers (if "ncoords" f An array holding NCOORDS AstKeyMap pointers (if NCOORDS * is zero, the supplied value is ignored). Each supplied KeyMap * describes the contents of a single STC element, and * should have elements with keys given by constants AST__STCNAME, * AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. Any of these elements may be omitted, but no other * elements should be included. If supplied, the AST__STCNAME element * should be a vector of character string pointers holding the "Name" * item for each axis in the coordinate system represented by c "region". f REGION. * Any other supplied elements should be scalar elements, each holding * a pointer to a Region describing the associated item of ancillary * information (error, resolution, size, pixel size or value). These * Regions should describe a volume within the coordinate system c represented by "region". f represented by REGION. 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 StcObsDataLocation. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new StcObsDataLocation. The syntax used is identical to that for the f AST_SET routine. 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 astStcObsDataLocation() f AST_STCOBSDATALOCATION = INTEGER * A pointer to the new StcObsDataLocation. * Notes: * - A deep copy is taken of the supplied Region. This means that * any subsequent changes made to the encapsulated Region using the * supplied pointer will have no effect on the Stc. * - 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstRegion *region; /* Pointer to Region structure */ AstStcObsDataLocation *new; /* Pointer to new StcObsDataLocation */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the Region structure provided. */ region = astCheckRegion( region_void ); /* Initialise the StcObsDataLocation, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcObsDataLocation( NULL, sizeof( AstStcObsDataLocation ), !class_init, &class_vtab, "StcObsDataLocation", region, ncoords, coords ); /* 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 StcObsDataLocation'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 StcObsDataLocation. */ return new; } AstStcObsDataLocation *astStcObsDataLocationId_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, ... ) { /* * Name: * astStcObsDataLocationId_ * Purpose: * Create a StcObsDataLocation. * Type: * Private function. * Synopsis: * #include "stcobsdatalocation.h" * AstStcObsDataLocation *astStcObsDataLocationId( AstRegion *region, * int ncoords, AstKeyMap *coords[], const char *options, ..., int *status ) * Class Membership: * StcObsDataLocation constructor. * Description: * This function implements the external (public) interface to the * astStcObsDataLocation constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astStcObsDataLocation_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astStcObsDataLocation_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astStcObsDataLocation_. * status * Pointer to the inherited status variable. * Returned Value: * The ID value associated with the new StcObsDataLocation. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstKeyMap **keymaps; /* Pointer to array of KeyMap pointers */ AstRegion *region; /* Pointer to Region structure */ AstStcObsDataLocation *new; /* Pointer to new StcObsDataLocation */ int icoord; /* Keymap index */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain a Region pointer from the supplied ID and validate the pointer to ensure it identifies a valid Region. */ region = astVerifyRegion( astMakePointer( region_void ) ); /* Obtain pointer from the supplied KeyMap ID's and validate the pointers to ensure it identifies a valid KeyMap. */ keymaps = astMalloc( sizeof( AstKeyMap * )*(size_t) ncoords ); if( keymaps ) { for( icoord = 0; icoord < ncoords; icoord++ ) { keymaps[ icoord ] = astVerifyKeyMap( astMakePointer( coords[ icoord ] ) ); } } /* Initialise the StcObsDataLocation, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcObsDataLocation( NULL, sizeof( AstStcObsDataLocation ), !class_init, &class_vtab, "StcObsDataLocation", region, ncoords, keymaps ); /* Free resources. */ keymaps = astFree( keymaps ); /* 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 StcObsDataLocation'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 StcObsDataLocation. */ return astMakeId( new ); } AstStcObsDataLocation *astInitStcObsDataLocation_( void *mem, size_t size, int init, AstStcObsDataLocationVtab *vtab, const char *name, AstRegion *region, int ncoords, AstKeyMap **coords, int *status ) { /* *+ * Name: * astInitStcObsDataLocation * Purpose: * Initialise a StcObsDataLocation. * Type: * Protected function. * Synopsis: * #include "stcobsdatalocation.h" * AstStcObsDataLocation *astInitStcObsDataLocation_( void *mem, size_t size, * int init, AstStcObsDataLocationVtab *vtab, * const char *name, AstRegion *region, * int ncoords, AstKeyMap **coords ) * Class Membership: * StcObsDataLocation initialiser. * Description: * This function is provided for use by class implementations to initialise * a new StcObsDataLocation object. It allocates memory (if necessary) to accommodate * the StcObsDataLocation plus any additional data associated with the derived class. * It then initialises a StcObsDataLocation 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 StcObsDataLocation at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the StcObsDataLocation is to be initialised. * This must be of sufficient size to accommodate the StcObsDataLocation data * (sizeof(StcObsDataLocation)) 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 StcObsDataLocation (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 StcObsDataLocation * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the StcObsDataLocation'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 StcObsDataLocation. * 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). * region * A pointer to the Region encapsulated by the StcObsDataLocation. * ncoords * Number of KeyMap pointers supplied in "coords". Can be zero. * Ignored if "coords" is NULL. * coords * Pointer to an array of "ncoords" KeyMap pointers, or NULL if * "ncoords" is zero. Each KeyMap defines defines a single * element, and should have elements with keys given by constants * AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. These elements hold values for the corresponding * components of the STC AstroCoords element. Any of these elements may * be omitted, but no other elements should be included. All supplied * elements should be vector elements, with vector length less than or * equal to the number of axes in the supplied Region. The data type of * all elements should be "double", except for AST__STCNAME which should * be "character string". If no value is available for a given axis, then * AST__BAD (or NULL for the AST__STCNAME element) should be stored in * the vector at the index corresponding to the axis (trailing axes * can be omitted completely from the KeyMap). * Returned Value: * A pointer to the new StcObsDataLocation. * 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: */ AstStcObsDataLocation *new; /* Pointer to new StcObsDataLocation */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitStcObsDataLocationVtab( vtab, name ); /* Initialise a Stc structure (the parent class) as the first component within the StcObsDataLocation structure, allocating memory if necessary. */ new = (AstStcObsDataLocation *) astInitStc( mem, size, 0, (AstStcVtab *) vtab, name, region, ncoords, coords ); /* If succesful, initialise properties of the StcObsDataLocation. */ if( new ) { new->obs = NULL; } /* If an error occurred, clean up by deleting the new StcObsDataLocation. */ if ( !astOK ) new = astDelete( new ); /* Return a pointer to the new StcObsDataLocation. */ return new; } AstStcObsDataLocation *astLoadStcObsDataLocation_( void *mem, size_t size, AstStcObsDataLocationVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadStcObsDataLocation * Purpose: * Load a StcObsDataLocation. * Type: * Protected function. * Synopsis: * #include "stcobsdatalocation.h" * AstStcObsDataLocation *astLoadStcObsDataLocation( void *mem, size_t size, AstStcObsDataLocationVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * StcObsDataLocation loader. * Description: * This function is provided to load a new StcObsDataLocation 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 * StcObsDataLocation structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a StcObsDataLocation at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the StcObsDataLocation is to be * loaded. This must be of sufficient size to accommodate the * StcObsDataLocation data (sizeof(StcObsDataLocation)) 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 StcObsDataLocation (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 StcObsDataLocation 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(AstStcObsDataLocation) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new StcObsDataLocation. If this is NULL, a pointer * to the (static) virtual function table for the StcObsDataLocation 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 "StcObsDataLocation" is used instead. * Returned Value: * A pointer to the new StcObsDataLocation. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstStcObsDataLocation *new; /* Pointer to the new StcObsDataLocation */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this StcObsDataLocation. In this case the StcObsDataLocation belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstStcObsDataLocation ); vtab = &class_vtab; name = "StcObsDataLocation"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitStcObsDataLocationVtab( 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 StcObsDataLocation. */ new = astLoadStc( mem, size, (AstStcVtab *) 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, "StcObsDataLocation" ); /* 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. */ /* Observatory position. */ /* --------------------- */ new->obs = astReadObject( channel, "obsloc", NULL ); /* If an error occurred, clean up by deleting the new StcObsDataLocation. */ if ( !astOK ) new = astDelete( new ); } /* Return the new StcObsDataLocation pointer. */ return new; } /* 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 astStcSetObs_( AstStcObsDataLocation *this, AstPointList *obs, int *status ){ if ( !astOK ) return; (**astMEMBER(this,StcObsDataLocation,StcSetObs))( this, obs, status ); } ast-8.3.0/Makefile.in0000664000175000017500000103254713004147327011316 00000000000000# Makefile.in generated by automake 1.14.1-starlink from Makefile.am. # @configure_input@ # Copyright (C) 1994-2013 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY, to the extent permitted by law; without # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. @SET_MAKE@ VPATH = @srcdir@ am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' am__make_running_with_option = \ case $${target_option-} in \ ?) ;; \ *) echo "am__make_running_with_option: internal error: invalid" \ "target option '$${target_option-}' specified" >&2; \ exit 1;; \ esac; \ has_opt=no; \ sane_makeflags=$$MAKEFLAGS; \ if $(am__is_gnu_make); then \ sane_makeflags=$$MFLAGS; \ else \ case $$MAKEFLAGS in \ *\\[\ \ ]*) \ bs=\\; \ sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ esac; \ fi; \ skip_next=no; \ strip_trailopt () \ { \ flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ }; \ for flg in $$sane_makeflags; do \ test $$skip_next = yes && { skip_next=no; continue; }; \ case $$flg in \ *=*|--*) continue;; \ -*I) strip_trailopt 'I'; skip_next=yes;; \ -*I?*) strip_trailopt 'I';; \ -*O) strip_trailopt 'O'; skip_next=yes;; \ -*O?*) strip_trailopt 'O';; \ -*l) strip_trailopt 'l'; skip_next=yes;; \ -*l?*) strip_trailopt 'l';; \ -[dEDm]) skip_next=yes;; \ -[JT]) skip_next=yes;; \ esac; \ case $$flg in \ *$$target_option*) has_opt=yes; break;; \ esac; \ done; \ test $$has_opt = yes am__make_dryrun = (target_option=n; $(am__make_running_with_option)) am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) pkgdatadir = $(datadir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ pkglibexecdir = $(libexecdir)/@PACKAGE@ am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c INSTALL_HEADER = $(INSTALL_DATA) transform = $(program_transform_name) NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = : NORMAL_UNINSTALL = : PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ noinst_PROGRAMS = astbad$(EXEEXT) TESTS = ast_test$(EXEEXT) check_PROGRAMS = ast_test$(EXEEXT) subdir = . DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \ $(top_srcdir)/configure $(am__configure_deps) \ $(srcdir)/config.h.in $(srcdir)/component.xml.in \ $(srcdir)/ast_link.in $(srcdir)/ast_link_adam.in \ $(srcdir)/object.h.in $(srcdir)/f77.h.in $(srcdir)/ast_cpp.in \ $(dist_bin_SCRIPTS) $(dist_noinst_SCRIPTS) \ $(top_srcdir)/build-aux/depcomp $(include_MESSAGES) \ $(srcdir)/AST_ERR $(srcdir)/ast_err.h $(srcdir)/fac_1521_err \ $(dist_pkgdata_DATA) $(dist_starnews_DATA) $(include_HEADERS) \ $(top_srcdir)/build-aux/test-driver $(stardocs_DATA) COPYING \ COPYING.LIB COPYING.LESSER build-aux/compile \ build-aux/config.guess build-aux/config.sub build-aux/depcomp \ build-aux/install-sh build-aux/missing build-aux/ltmain.sh \ $(top_srcdir)/build-aux/compile \ $(top_srcdir)/build-aux/config.guess \ $(top_srcdir)/build-aux/config.sub \ $(top_srcdir)/build-aux/install-sh \ $(top_srcdir)/build-aux/ltmain.sh \ $(top_srcdir)/build-aux/missing ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \ configure.lineno config.status.lineno mkinstalldirs = $(install_sh) -d CONFIG_HEADER = config.h CONFIG_CLEAN_FILES = component.xml ast_link ast_link_adam object.h \ f77.h ast_cpp CONFIG_CLEAN_VPATH_FILES = am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; am__vpath_adj = case $$p in \ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ *) f=$$p;; \ esac; am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; am__install_max = 40 am__nobase_strip_setup = \ srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` am__nobase_strip = \ for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" am__nobase_list = $(am__nobase_strip_setup); \ for p in $$list; do echo "$$p $$p"; done | \ sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ if (++n[$$2] == $(am__install_max)) \ { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ END { for (dir in files) print dir, files[dir] }' am__base_list = \ sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' am__uninstall_files_from_dir = { \ test -z "$$files" \ || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ $(am__cd) "$$dir" && rm -f $$files; }; \ } am__installdirs = "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" \ "$(DESTDIR)$(bindir)" "$(DESTDIR)$(includedir)" \ "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(starnewsdir)" \ $(DESTDIR)$(stardocsdir) "$(DESTDIR)$(starfacsdir)" \ "$(DESTDIR)$(includedir)" "$(DESTDIR)$(includedir)" LTLIBRARIES = $(lib_LTLIBRARIES) @EXTERNAL_PAL_FALSE@libast_la_DEPENDENCIES = libast_pal.la @EXTERNAL_PAL_TRUE@libast_la_DEPENDENCIES = $(libdir)/libpal.la am__libast_la_SOURCES_DIST = axis.c box.c channel.c circle.c \ cmpframe.c cmpmap.c cmpregion.c dsbspecframe.c dssmap.c \ ellipse.c error.c fitschan.c fitstable.c fluxframe.c frame.c \ frameset.c globals.c grismmap.c interval.c intramap.c keymap.c \ loader.c lutmap.c mapping.c mathmap.c matrixmap.c memory.c \ normmap.c nullregion.c object.c pcdmap.c permmap.c plot.c \ plot3d.c pointlist.c pointset.c polygon.c polymap.c prism.c \ ratemap.c region.c selectormap.c shiftmap.c skyaxis.c \ skyframe.c slamap.c specfluxframe.c specframe.c specmap.c \ sphmap.c stc.c stccatalogentrylocation.c stcobsdatalocation.c \ stcresourceprofile.c stcschan.c stcsearchlocation.c \ switchmap.c table.c timeframe.c timemap.c tranmap.c unit.c \ unitmap.c unitnormmap.c wcsmap.c winmap.c xml.c xmlchan.c \ zoommap.c c2f77.c fbox.c fchannel.c fcircle.c fcmpframe.c \ fcmpmap.c fcmpregion.c fdsbspecframe.c fdssmap.c fellipse.c \ ferror.c ffitschan.c ffitstable.c ffluxframe.c fframe.c \ fframeset.c fgrismmap.c finterval.c fintramap.c fkeymap.c \ flutmap.c fmapping.c fmathmap.c fmatrixmap.c fnormmap.c \ fnullregion.c fobject.c fpcdmap.c fpermmap.c fplot.c fplot3d.c \ fpointlist.c fpolygon.c fpolymap.c fprism.c fratemap.c \ fregion.c fselectormap.c fshiftmap.c fskyframe.c fslamap.c \ fspecfluxframe.c fspecframe.c fspecmap.c fsphmap.c fstc.c \ fstccatalogentrylocation.c fstcobsdatalocation.c \ fstcresourceprofile.c fstcschan.c fstcsearchlocation.c \ fswitchmap.c ftable.c ftimeframe.c ftimemap.c ftranmap.c \ funitmap.c funitnormmap.c fwcsmap.c fwinmap.c fxmlchan.c \ fzoommap.c xml.h wcstrig.h proj.h memory.h error.h globals.h \ unit.h ast_err.h version.h object.h keymap.h table.h \ fitstable.h pointset.h axis.h skyaxis.h mapping.h cmpmap.h \ dssmap.h grismmap.h intramap.h lutmap.h mathmap.h matrixmap.h \ pcdmap.h permmap.h polymap.h ratemap.h normmap.h shiftmap.h \ slamap.h specmap.h sphmap.h timemap.h selectormap.h \ switchmap.h tranmap.h unitmap.h unitnormmap.h wcsmap.h \ winmap.h zoommap.h frame.h cmpframe.h specfluxframe.h \ fluxframe.h frameset.h plot.h plot3d.h skyframe.h specframe.h \ dsbspecframe.h region.h box.h circle.h cmpregion.h ellipse.h \ interval.h nullregion.h pointlist.h polygon.h prism.h stc.h \ stcresourceprofile.h stcsearchlocation.h \ stccatalogentrylocation.h stcobsdatalocation.h timeframe.h \ channel.h fitschan.h stcschan.h xmlchan.h ems.h err.h Ers.h \ f77.h grf.h grf3d.h pg3d.h loader.h pal2ast.h erfa2ast.h \ wcsmath.h c2f77.h GRF_PAR AST_ERR cminpack/cminpack.h \ cminpack/cminpackP.h cminpack/lmder1.c cminpack/lmder.c \ cminpack/dpmpar.c cminpack/enorm.c cminpack/qrfac.c \ cminpack/lmpar.c cminpack/qrsolv.c proj.c tpn.c wcstrig.c am__objects_1 = libast_la-axis.lo libast_la-box.lo \ libast_la-channel.lo libast_la-circle.lo libast_la-cmpframe.lo \ libast_la-cmpmap.lo libast_la-cmpregion.lo \ libast_la-dsbspecframe.lo libast_la-dssmap.lo \ libast_la-ellipse.lo libast_la-error.lo libast_la-fitschan.lo \ libast_la-fitstable.lo libast_la-fluxframe.lo \ libast_la-frame.lo libast_la-frameset.lo libast_la-globals.lo \ libast_la-grismmap.lo libast_la-interval.lo \ libast_la-intramap.lo libast_la-keymap.lo libast_la-loader.lo \ libast_la-lutmap.lo libast_la-mapping.lo libast_la-mathmap.lo \ libast_la-matrixmap.lo libast_la-memory.lo \ libast_la-normmap.lo libast_la-nullregion.lo \ libast_la-object.lo libast_la-pcdmap.lo libast_la-permmap.lo \ libast_la-plot.lo libast_la-plot3d.lo libast_la-pointlist.lo \ libast_la-pointset.lo libast_la-polygon.lo \ libast_la-polymap.lo libast_la-prism.lo libast_la-ratemap.lo \ libast_la-region.lo libast_la-selectormap.lo \ libast_la-shiftmap.lo libast_la-skyaxis.lo \ libast_la-skyframe.lo libast_la-slamap.lo \ libast_la-specfluxframe.lo libast_la-specframe.lo \ libast_la-specmap.lo libast_la-sphmap.lo libast_la-stc.lo \ libast_la-stccatalogentrylocation.lo \ libast_la-stcobsdatalocation.lo \ libast_la-stcresourceprofile.lo libast_la-stcschan.lo \ libast_la-stcsearchlocation.lo libast_la-switchmap.lo \ libast_la-table.lo libast_la-timeframe.lo libast_la-timemap.lo \ libast_la-tranmap.lo libast_la-unit.lo libast_la-unitmap.lo \ libast_la-unitnormmap.lo libast_la-wcsmap.lo \ libast_la-winmap.lo libast_la-xml.lo libast_la-xmlchan.lo \ libast_la-zoommap.lo @NOFORTRAN_FALSE@am__objects_2 = libast_la-c2f77.lo libast_la-fbox.lo \ @NOFORTRAN_FALSE@ libast_la-fchannel.lo libast_la-fcircle.lo \ @NOFORTRAN_FALSE@ libast_la-fcmpframe.lo libast_la-fcmpmap.lo \ @NOFORTRAN_FALSE@ libast_la-fcmpregion.lo \ @NOFORTRAN_FALSE@ libast_la-fdsbspecframe.lo \ @NOFORTRAN_FALSE@ libast_la-fdssmap.lo libast_la-fellipse.lo \ @NOFORTRAN_FALSE@ libast_la-ferror.lo libast_la-ffitschan.lo \ @NOFORTRAN_FALSE@ libast_la-ffitstable.lo \ @NOFORTRAN_FALSE@ libast_la-ffluxframe.lo libast_la-fframe.lo \ @NOFORTRAN_FALSE@ libast_la-fframeset.lo libast_la-fgrismmap.lo \ @NOFORTRAN_FALSE@ libast_la-finterval.lo libast_la-fintramap.lo \ @NOFORTRAN_FALSE@ libast_la-fkeymap.lo libast_la-flutmap.lo \ @NOFORTRAN_FALSE@ libast_la-fmapping.lo libast_la-fmathmap.lo \ @NOFORTRAN_FALSE@ libast_la-fmatrixmap.lo libast_la-fnormmap.lo \ @NOFORTRAN_FALSE@ libast_la-fnullregion.lo libast_la-fobject.lo \ @NOFORTRAN_FALSE@ libast_la-fpcdmap.lo libast_la-fpermmap.lo \ @NOFORTRAN_FALSE@ libast_la-fplot.lo libast_la-fplot3d.lo \ @NOFORTRAN_FALSE@ libast_la-fpointlist.lo libast_la-fpolygon.lo \ @NOFORTRAN_FALSE@ libast_la-fpolymap.lo libast_la-fprism.lo \ @NOFORTRAN_FALSE@ libast_la-fratemap.lo libast_la-fregion.lo \ @NOFORTRAN_FALSE@ libast_la-fselectormap.lo \ @NOFORTRAN_FALSE@ libast_la-fshiftmap.lo libast_la-fskyframe.lo \ @NOFORTRAN_FALSE@ libast_la-fslamap.lo \ @NOFORTRAN_FALSE@ libast_la-fspecfluxframe.lo \ @NOFORTRAN_FALSE@ libast_la-fspecframe.lo libast_la-fspecmap.lo \ @NOFORTRAN_FALSE@ libast_la-fsphmap.lo libast_la-fstc.lo \ @NOFORTRAN_FALSE@ libast_la-fstccatalogentrylocation.lo \ @NOFORTRAN_FALSE@ libast_la-fstcobsdatalocation.lo \ @NOFORTRAN_FALSE@ libast_la-fstcresourceprofile.lo \ @NOFORTRAN_FALSE@ libast_la-fstcschan.lo \ @NOFORTRAN_FALSE@ libast_la-fstcsearchlocation.lo \ @NOFORTRAN_FALSE@ libast_la-fswitchmap.lo libast_la-ftable.lo \ @NOFORTRAN_FALSE@ libast_la-ftimeframe.lo libast_la-ftimemap.lo \ @NOFORTRAN_FALSE@ libast_la-ftranmap.lo libast_la-funitmap.lo \ @NOFORTRAN_FALSE@ libast_la-funitnormmap.lo \ @NOFORTRAN_FALSE@ libast_la-fwcsmap.lo libast_la-fwinmap.lo \ @NOFORTRAN_FALSE@ libast_la-fxmlchan.lo libast_la-fzoommap.lo am__objects_3 = am__objects_4 = $(am__objects_3) am__dirstamp = $(am__leading_dot)dirstamp am__objects_5 = cminpack/libast_la-lmder1.lo \ cminpack/libast_la-lmder.lo cminpack/libast_la-dpmpar.lo \ cminpack/libast_la-enorm.lo cminpack/libast_la-qrfac.lo \ cminpack/libast_la-lmpar.lo cminpack/libast_la-qrsolv.lo am__objects_6 = libast_la-proj.lo libast_la-tpn.lo \ libast_la-wcstrig.lo am_libast_la_OBJECTS = $(am__objects_1) $(am__objects_2) \ $(am__objects_4) $(am__objects_3) $(am__objects_3) \ $(am__objects_5) $(am__objects_6) nodist_libast_la_OBJECTS = libast_la_OBJECTS = $(am_libast_la_OBJECTS) \ $(nodist_libast_la_OBJECTS) AM_V_lt = $(am__v_lt_@AM_V@) am__v_lt_ = $(am__v_lt_@AM_DEFAULT_V@) am__v_lt_0 = --silent am__v_lt_1 = libast_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(libast_la_CFLAGS) \ $(CFLAGS) $(STAR_LDFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_drama_la_LIBADD = am_libast_drama_la_OBJECTS = libast_drama_la-err_drama.lo libast_drama_la_OBJECTS = $(am_libast_drama_la_OBJECTS) libast_drama_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_drama_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_ems_la_LIBADD = am_libast_ems_la_OBJECTS = libast_ems_la-err_ems.lo libast_ems_la_OBJECTS = $(am_libast_ems_la_OBJECTS) libast_ems_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(libast_ems_la_CFLAGS) \ $(CFLAGS) $(STAR_LDFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_err_la_LIBADD = am_libast_err_la_OBJECTS = libast_err_la-err_null.lo libast_err_la_OBJECTS = $(am_libast_err_la_OBJECTS) libast_err_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(libast_err_la_CFLAGS) \ $(CFLAGS) $(STAR_LDFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_grf3d_la_LIBADD = am_libast_grf3d_la_OBJECTS = libast_grf3d_la-grf3d.lo libast_grf3d_la_OBJECTS = $(am_libast_grf3d_la_OBJECTS) libast_grf3d_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_grf3d_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_grf_2_0_la_LIBADD = am_libast_grf_2_0_la_OBJECTS = libast_grf_2_0_la-grf_2.0.lo libast_grf_2_0_la_OBJECTS = $(am_libast_grf_2_0_la_OBJECTS) libast_grf_2_0_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_grf_2_0_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_grf_3_2_la_LIBADD = am_libast_grf_3_2_la_OBJECTS = libast_grf_3_2_la-grf_3.2.lo libast_grf_3_2_la_OBJECTS = $(am_libast_grf_3_2_la_OBJECTS) libast_grf_3_2_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_grf_3_2_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_grf_5_6_la_LIBADD = am_libast_grf_5_6_la_OBJECTS = libast_grf_5_6_la-grf_5.6.lo libast_grf_5_6_la_OBJECTS = $(am_libast_grf_5_6_la_OBJECTS) libast_grf_5_6_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_grf_5_6_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_pal_la_LIBADD = am__objects_7 = libast_pal_la-palwrap.lo am_libast_pal_la_OBJECTS = $(am__objects_7) libast_pal_la_OBJECTS = $(am_libast_pal_la_OBJECTS) libast_pal_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(libast_pal_la_CFLAGS) \ $(CFLAGS) $(STAR_LDFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ @EXTERNAL_PAL_FALSE@am_libast_pal_la_rpath = -rpath $(libdir) libast_pgplot_la_LIBADD = am__libast_pgplot_la_SOURCES_DIST = grf_pgplot.c grf_5.6.c @NOFORTRAN_FALSE@am__objects_8 = libast_pgplot_la-grf_pgplot.lo @NOFORTRAN_TRUE@am__objects_8 = libast_pgplot_la-grf_5.6.lo am_libast_pgplot_la_OBJECTS = $(am__objects_8) libast_pgplot_la_OBJECTS = $(am_libast_pgplot_la_OBJECTS) libast_pgplot_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_pgplot_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ libast_pgplot3d_la_LIBADD = am__libast_pgplot3d_la_SOURCES_DIST = grf3d_pgplot.c grf3d.c @NOFORTRAN_FALSE@am__objects_9 = libast_pgplot3d_la-grf3d_pgplot.lo @NOFORTRAN_TRUE@am__objects_9 = libast_pgplot3d_la-grf3d.lo am_libast_pgplot3d_la_OBJECTS = $(am__objects_9) libast_pgplot3d_la_OBJECTS = $(am_libast_pgplot3d_la_OBJECTS) libast_pgplot3d_la_LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC \ $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=link $(CCLD) \ $(libast_pgplot3d_la_CFLAGS) $(CFLAGS) $(STAR_LDFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ PROGRAMS = $(noinst_PROGRAMS) am_ast_test_OBJECTS = ast_test.$(OBJEXT) ast_test_OBJECTS = $(am_ast_test_OBJECTS) ast_test_DEPENDENCIES = libast.la libast_pal.la libast_grf_3.2.la \ libast_grf_5.6.la libast_grf_2.0.la libast_grf3d.la \ libast_err.la am_astbad_OBJECTS = astbad.$(OBJEXT) astbad_OBJECTS = $(am_astbad_OBJECTS) astbad_LDADD = $(LDADD) SCRIPTS = $(bin_SCRIPTS) $(dist_bin_SCRIPTS) $(dist_noinst_SCRIPTS) \ $(noinst_SCRIPTS) AM_V_P = $(am__v_P_@AM_V@) am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) am__v_P_0 = false am__v_P_1 = : AM_V_GEN = $(am__v_GEN_@AM_V@) am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) am__v_GEN_0 = @echo " GEN " $@; am__v_GEN_1 = AM_V_at = $(am__v_at_@AM_V@) am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) am__v_at_0 = @ am__v_at_1 = DEFAULT_INCLUDES = -I.@am__isrc@ depcomp = $(SHELL) $(top_srcdir)/build-aux/depcomp am__depfiles_maybe = depfiles am__mv = mv -f COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) \ $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) \ $(CFLAGS) LTCOMPILE = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) \ $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) \ $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) AM_V_CC = $(am__v_CC_@AM_V@) am__v_CC_ = $(am__v_CC_@AM_DEFAULT_V@) am__v_CC_0 = @echo " CC " $@; am__v_CC_1 = CCLD = $(CC) LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) \ $(STAR_LDFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ AM_V_CCLD = $(am__v_CCLD_@AM_V@) am__v_CCLD_ = $(am__v_CCLD_@AM_DEFAULT_V@) am__v_CCLD_0 = @echo " CCLD " $@; am__v_CCLD_1 = SOURCES = $(libast_la_SOURCES) $(nodist_libast_la_SOURCES) \ $(libast_drama_la_SOURCES) $(libast_ems_la_SOURCES) \ $(libast_err_la_SOURCES) $(libast_grf3d_la_SOURCES) \ $(libast_grf_2_0_la_SOURCES) $(libast_grf_3_2_la_SOURCES) \ $(libast_grf_5_6_la_SOURCES) $(libast_pal_la_SOURCES) \ $(libast_pgplot_la_SOURCES) $(libast_pgplot3d_la_SOURCES) \ $(ast_test_SOURCES) $(astbad_SOURCES) DIST_SOURCES = $(am__libast_la_SOURCES_DIST) \ $(libast_drama_la_SOURCES) $(libast_ems_la_SOURCES) \ $(libast_err_la_SOURCES) $(libast_grf3d_la_SOURCES) \ $(libast_grf_2_0_la_SOURCES) $(libast_grf_3_2_la_SOURCES) \ $(libast_grf_5_6_la_SOURCES) $(libast_pal_la_SOURCES) \ $(am__libast_pgplot_la_SOURCES_DIST) \ $(am__libast_pgplot3d_la_SOURCES_DIST) $(ast_test_SOURCES) \ $(astbad_SOURCES) am__can_run_installinfo = \ case $$AM_UPDATE_INFO_DIR in \ n|no|NO) false;; \ *) (install-info --version) >/dev/null 2>&1;; \ esac MESSAGES = $(include_MESSAGES) INSTALL_MESSAGE = $(INSTALL_DATA) stardocsDATA_INSTALL = $(INSTALL_DATA) DATA = $(dist_pkgdata_DATA) $(dist_starnews_DATA) $(stardocs_DATA) \ $(starfacs_DATA) HEADERS = $(include_HEADERS) $(nodist_include_HEADERS) am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) \ $(LISP)config.h.in # Read a list of newline-separated strings from the standard input, # and print each of them once, without duplicates. Input order is # *not* preserved. am__uniquify_input = $(AWK) '\ BEGIN { nonempty = 0; } \ { items[$$0] = 1; nonempty = 1; } \ END { if (nonempty) { for (i in items) print i; }; } \ ' # Make sure the list of sources is unique. This is necessary because, # e.g., the same source file might be shared among _SOURCES variables # for different programs/libraries. am__define_uniq_tagged_files = \ list='$(am__tagged_files)'; \ unique=`for i in $$list; do \ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ done | $(am__uniquify_input)` ETAGS = etags CTAGS = ctags CSCOPE = cscope AM_RECURSIVE_TARGETS = cscope check recheck am__tty_colors_dummy = \ mgn= red= grn= lgn= blu= brg= std=; \ am__color_tests=no am__tty_colors = { \ $(am__tty_colors_dummy); \ if test "X$(AM_COLOR_TESTS)" = Xno; then \ am__color_tests=no; \ elif test "X$(AM_COLOR_TESTS)" = Xalways; then \ am__color_tests=yes; \ elif test "X$$TERM" != Xdumb && { test -t 1; } 2>/dev/null; then \ am__color_tests=yes; \ fi; \ if test $$am__color_tests = yes; then \ red=''; \ grn=''; \ lgn=''; \ blu=''; \ mgn=''; \ brg=''; \ std=''; \ fi; \ } am__recheck_rx = ^[ ]*:recheck:[ ]* am__global_test_result_rx = ^[ ]*:global-test-result:[ ]* am__copy_in_global_log_rx = ^[ ]*:copy-in-global-log:[ ]* # A command that, given a newline-separated list of test names on the # standard input, print the name of the tests that are to be re-run # upon "make recheck". am__list_recheck_tests = $(AWK) '{ \ recheck = 1; \ while ((rc = (getline line < ($$0 ".trs"))) != 0) \ { \ if (rc < 0) \ { \ if ((getline line2 < ($$0 ".log")) < 0) \ recheck = 0; \ break; \ } \ else if (line ~ /$(am__recheck_rx)[nN][Oo]/) \ { \ recheck = 0; \ break; \ } \ else if (line ~ /$(am__recheck_rx)[yY][eE][sS]/) \ { \ break; \ } \ }; \ if (recheck) \ print $$0; \ close ($$0 ".trs"); \ close ($$0 ".log"); \ }' # A command that, given a newline-separated list of test names on the # standard input, create the global log from their .trs and .log files. am__create_global_log = $(AWK) ' \ function fatal(msg) \ { \ print "fatal: making $@: " msg | "cat >&2"; \ exit 1; \ } \ function rst_section(header) \ { \ print header; \ len = length(header); \ for (i = 1; i <= len; i = i + 1) \ printf "="; \ printf "\n\n"; \ } \ { \ copy_in_global_log = 1; \ global_test_result = "RUN"; \ while ((rc = (getline line < ($$0 ".trs"))) != 0) \ { \ if (rc < 0) \ fatal("failed to read from " $$0 ".trs"); \ if (line ~ /$(am__global_test_result_rx)/) \ { \ sub("$(am__global_test_result_rx)", "", line); \ sub("[ ]*$$", "", line); \ global_test_result = line; \ } \ else if (line ~ /$(am__copy_in_global_log_rx)[nN][oO]/) \ copy_in_global_log = 0; \ }; \ if (copy_in_global_log) \ { \ rst_section(global_test_result ": " $$0); \ while ((rc = (getline line < ($$0 ".log"))) != 0) \ { \ if (rc < 0) \ fatal("failed to read from " $$0 ".log"); \ print line; \ }; \ printf "\n"; \ }; \ close ($$0 ".trs"); \ close ($$0 ".log"); \ }' # Restructured Text title. am__rst_title = { sed 's/.*/ & /;h;s/./=/g;p;x;s/ *$$//;p;g' && echo; } # Solaris 10 'make', and several other traditional 'make' implementations, # pass "-e" to $(SHELL), and POSIX 2008 even requires this. Work around it # by disabling -e (using the XSI extension "set +e") if it's set. am__sh_e_setup = case $$- in *e*) set +e;; esac # Default flags passed to test drivers. am__common_driver_flags = \ --color-tests "$$am__color_tests" \ --enable-hard-errors "$$am__enable_hard_errors" \ --expect-failure "$$am__expect_failure" # To be inserted before the command running the test. Creates the # directory for the log if needed. Stores in $dir the directory # containing $f, in $tst the test, in $log the log. Executes the # developer- defined test setup AM_TESTS_ENVIRONMENT (if any), and # passes TESTS_ENVIRONMENT. Set up options for the wrapper that # will run the test scripts (or their associated LOG_COMPILER, if # thy have one). am__check_pre = \ $(am__sh_e_setup); \ $(am__vpath_adj_setup) $(am__vpath_adj) \ $(am__tty_colors); \ srcdir=$(srcdir); export srcdir; \ case "$@" in \ */*) am__odir=`echo "./$@" | sed 's|/[^/]*$$||'`;; \ *) am__odir=.;; \ esac; \ test "x$$am__odir" = x"." || test -d "$$am__odir" \ || $(MKDIR_P) "$$am__odir" || exit $$?; \ if test -f "./$$f"; then dir=./; \ elif test -f "$$f"; then dir=; \ else dir="$(srcdir)/"; fi; \ tst=$$dir$$f; log='$@'; \ if test -n '$(DISABLE_HARD_ERRORS)'; then \ am__enable_hard_errors=no; \ else \ am__enable_hard_errors=yes; \ fi; \ case " $(XFAIL_TESTS) " in \ *[\ \ ]$$f[\ \ ]* | *[\ \ ]$$dir$$f[\ \ ]*) \ am__expect_failure=yes;; \ *) \ am__expect_failure=no;; \ esac; \ $(AM_TESTS_ENVIRONMENT) $(TESTS_ENVIRONMENT) # A shell command to get the names of the tests scripts with any registered # extension removed (i.e., equivalently, the names of the test logs, with # the '.log' extension removed). The result is saved in the shell variable # '$bases'. This honors runtime overriding of TESTS and TEST_LOGS. Sadly, # we cannot use something simpler, involving e.g., "$(TEST_LOGS:.log=)", # since that might cause problem with VPATH rewrites for suffix-less tests. # See also 'test-harness-vpath-rewrite.sh' and 'test-trs-basic.sh'. am__set_TESTS_bases = \ bases='$(TEST_LOGS)'; \ bases=`for i in $$bases; do echo $$i; done | sed 's/\.log$$//'`; \ bases=`echo $$bases` RECHECK_LOGS = $(TEST_LOGS) TEST_SUITE_LOG = test-suite.log TEST_EXTENSIONS = @EXEEXT@ .test LOG_DRIVER = $(SHELL) $(top_srcdir)/build-aux/test-driver LOG_COMPILE = $(LOG_COMPILER) $(AM_LOG_FLAGS) $(LOG_FLAGS) am__set_b = \ case '$@' in \ */*) \ case '$*' in \ */*) b='$*';; \ *) b=`echo '$@' | sed 's/\.log$$//'`; \ esac;; \ *) \ b='$*';; \ esac am__test_logs1 = $(TESTS:=.log) am__test_logs2 = $(am__test_logs1:@EXEEXT@.log=.log) TEST_LOGS = $(am__test_logs2:.test.log=.log) TEST_LOG_DRIVER = $(SHELL) $(top_srcdir)/build-aux/test-driver TEST_LOG_COMPILE = $(TEST_LOG_COMPILER) $(AM_TEST_LOG_FLAGS) \ $(TEST_LOG_FLAGS) DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) distdir = $(PACKAGE)-$(VERSION) top_distdir = $(distdir) am__remove_distdir = \ if test -d "$(distdir)"; then \ find "$(distdir)" -type d ! -perm -200 -exec chmod u+w {} ';' \ && rm -rf "$(distdir)" \ || { sleep 5 && rm -rf "$(distdir)"; }; \ else :; fi am__post_remove_distdir = $(am__remove_distdir) DIST_ARCHIVES = $(distdir).tar.gz GZIP_ENV = --best DIST_TARGETS = dist-gzip distuninstallcheck_listfiles = find . -type f -print am__distuninstallcheck_listfiles = $(distuninstallcheck_listfiles) \ | sed 's|^\./|$(prefix)/|' | grep -v '$(infodir)/dir$$' distcleancheck_listfiles = find . -type f -print # Use AM_MAKEFLAGS to pass the value of the MANIFEST variable into # submakes (not all makes do this automatically). This can still be # overridden with a setting of this variable on the $(MAKE) command # line. I think we really shouldn't be setting this variable -- if # it causes a problem for anyone, we should edit a new variable in to # the .am templates. AM_MAKEFLAGS = MANIFEST=$(MANIFEST) REAL_INSTALL = install-am # Set to : to emit manifest lines, too # (don't actually do this here -- it's done within install-manifest below). MANIFEST = false ACLOCAL = @ACLOCAL@ AMTAR = @AMTAR@ AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ AR = @AR@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ CYGPATH_W = @CYGPATH_W@ DEFS = @DEFS@ DEPDIR = @DEPDIR@ DLLTOOL = @DLLTOOL@ DSYMUTIL = @DSYMUTIL@ DUMPBIN = @DUMPBIN@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ EXEEXT = @EXEEXT@ EXTERNAL_PAL = @EXTERNAL_PAL@ FC = @FC@ FCFLAGS = @FCFLAGS@ FCLIBS = @FCLIBS@ FGREP = @FGREP@ FORTRAN = @FORTRAN@ GIT = @GIT@ GREP = @GREP@ INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ LATEX2DVI = @LATEX2DVI@ LD = @LD@ LDFLAGS = @LDFLAGS@ LIBOBJS = @LIBOBJS@ LIBPAL = @LIBPAL@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ LIPO = @LIPO@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ MAKEINFO = @MAKEINFO@ MANIFEST_TOOL = @MANIFEST_TOOL@ MESSGEN = @MESSGEN@ MKDIR_P = @MKDIR_P@ NM = @NM@ NMEDIT = @NMEDIT@ OBJDUMP = @OBJDUMP@ OBJEXT = @OBJEXT@ OTOOL = @OTOOL@ OTOOL64 = @OTOOL64@ PACKAGE = @PACKAGE@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ PACKAGE_NAME = @PACKAGE_NAME@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PACKAGE_VERSION_INTEGER = @PACKAGE_VERSION_INTEGER@ PACKAGE_VERSION_MAJOR = @PACKAGE_VERSION_MAJOR@ PACKAGE_VERSION_MINOR = @PACKAGE_VERSION_MINOR@ PACKAGE_VERSION_RELEASE = @PACKAGE_VERSION_RELEASE@ PATH_SEPARATOR = @PATH_SEPARATOR@ PAX = @PAX@ PERL = @PERL@ PREDIST = @PREDIST@ PROLAT = @PROLAT@ RANLIB = @RANLIB@ REAL_FUNCTION_TYPE = @REAL_FUNCTION_TYPE@ SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ STAR2HTML = @STAR2HTML@ STARLINK = @STARLINK@ STAR_CPPFLAGS = @STAR_CPPFLAGS@ STAR_DEPENDENCIES_ATTRIBUTES = @STAR_DEPENDENCIES_ATTRIBUTES@ STAR_DEPENDENCIES_CHILDREN = @STAR_DEPENDENCIES_CHILDREN@ STAR_DOCUMENTATION = @STAR_DOCUMENTATION@ STAR_FCFLAGS = @STAR_FCFLAGS@ STAR_FFLAGS = @STAR_FFLAGS@ STAR_LATEX_DOCUMENTATION = @STAR_LATEX_DOCUMENTATION@ STAR_LDFLAGS = @STAR_LDFLAGS@ STAR_MANIFEST_DIR = @STAR_MANIFEST_DIR@ STAR_SOURCE_ROOT_DIR = @STAR_SOURCE_ROOT_DIR@ STRIP = @STRIP@ TAR = @TAR@ THREADS = @THREADS@ TRAIL_TYPE = @TRAIL_TYPE@ VERSION = @VERSION@ abs_builddir = @abs_builddir@ abs_srcdir = @abs_srcdir@ abs_top_builddir = @abs_top_builddir@ abs_top_srcdir = @abs_top_srcdir@ ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ ac_ct_FC = @ac_ct_FC@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ am__tar = @am__tar@ am__untar = @am__untar@ bindir = @bindir@ build = @build@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ builddir = @builddir@ datadir = @datadir@ datarootdir = @datarootdir@ docdir = @docdir@ dvidir = @dvidir@ exec_prefix = @exec_prefix@ host = @host@ host_alias = @host_alias@ host_cpu = @host_cpu@ host_os = @host_os@ host_vendor = @host_vendor@ htmldir = @htmldir@ includedir = @includedir@ infodir = @infodir@ install_sh = @install_sh@ libdir = @libdir@ libexecdir = @libexecdir@ localedir = @localedir@ localstatedir = @localstatedir@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ pdfdir = @pdfdir@ prefix = @prefix@ program_transform_name = @program_transform_name@ psdir = @psdir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ stardocsdir = @stardocsdir@ staretcdir = @staretcdir@ starexamplesdir = @starexamplesdir@ starfacsdir = @starfacsdir@ starhelpdir = @starhelpdir@ starnewsdir = @starnewsdir@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ # First declare various groups of files. These were initially extracted # from the grp.make file, as constructed by the SDT newdev command GRP_C_ROUTINES = \ axis.c \ box.c \ channel.c \ circle.c \ cmpframe.c \ cmpmap.c \ cmpregion.c \ dsbspecframe.c \ dssmap.c \ ellipse.c \ error.c \ fitschan.c \ fitstable.c \ fluxframe.c \ frame.c \ frameset.c \ globals.c \ grismmap.c \ interval.c \ intramap.c \ keymap.c \ loader.c \ lutmap.c \ mapping.c \ mathmap.c \ matrixmap.c \ memory.c \ normmap.c \ nullregion.c \ object.c \ pcdmap.c \ permmap.c \ plot.c \ plot3d.c \ pointlist.c \ pointset.c \ polygon.c \ polymap.c \ prism.c \ ratemap.c \ region.c \ selectormap.c \ shiftmap.c \ skyaxis.c \ skyframe.c \ slamap.c \ specfluxframe.c \ specframe.c \ specmap.c \ sphmap.c \ stc.c \ stccatalogentrylocation.c \ stcobsdatalocation.c \ stcresourceprofile.c \ stcschan.c \ stcsearchlocation.c \ switchmap.c \ table.c \ timeframe.c \ timemap.c \ tranmap.c \ unit.c \ unitmap.c \ unitnormmap.c \ wcsmap.c \ winmap.c \ xml.c \ xmlchan.c \ zoommap.c # The C source files required for the Fortran interface @NOFORTRAN_FALSE@F_C_ROUTINES = \ @NOFORTRAN_FALSE@ c2f77.c \ @NOFORTRAN_FALSE@ fbox.c \ @NOFORTRAN_FALSE@ fchannel.c \ @NOFORTRAN_FALSE@ fcircle.c \ @NOFORTRAN_FALSE@ fcmpframe.c \ @NOFORTRAN_FALSE@ fcmpmap.c \ @NOFORTRAN_FALSE@ fcmpregion.c \ @NOFORTRAN_FALSE@ fdsbspecframe.c \ @NOFORTRAN_FALSE@ fdssmap.c \ @NOFORTRAN_FALSE@ fellipse.c \ @NOFORTRAN_FALSE@ ferror.c \ @NOFORTRAN_FALSE@ ffitschan.c \ @NOFORTRAN_FALSE@ ffitstable.c \ @NOFORTRAN_FALSE@ ffluxframe.c \ @NOFORTRAN_FALSE@ fframe.c \ @NOFORTRAN_FALSE@ fframeset.c \ @NOFORTRAN_FALSE@ fgrismmap.c \ @NOFORTRAN_FALSE@ finterval.c \ @NOFORTRAN_FALSE@ fintramap.c \ @NOFORTRAN_FALSE@ fkeymap.c \ @NOFORTRAN_FALSE@ flutmap.c \ @NOFORTRAN_FALSE@ fmapping.c \ @NOFORTRAN_FALSE@ fmathmap.c \ @NOFORTRAN_FALSE@ fmatrixmap.c \ @NOFORTRAN_FALSE@ fnormmap.c \ @NOFORTRAN_FALSE@ fnullregion.c \ @NOFORTRAN_FALSE@ fobject.c \ @NOFORTRAN_FALSE@ fpcdmap.c \ @NOFORTRAN_FALSE@ fpermmap.c \ @NOFORTRAN_FALSE@ fplot.c \ @NOFORTRAN_FALSE@ fplot3d.c \ @NOFORTRAN_FALSE@ fpointlist.c \ @NOFORTRAN_FALSE@ fpolygon.c \ @NOFORTRAN_FALSE@ fpolymap.c \ @NOFORTRAN_FALSE@ fprism.c \ @NOFORTRAN_FALSE@ fratemap.c \ @NOFORTRAN_FALSE@ fregion.c \ @NOFORTRAN_FALSE@ fselectormap.c \ @NOFORTRAN_FALSE@ fshiftmap.c \ @NOFORTRAN_FALSE@ fskyframe.c \ @NOFORTRAN_FALSE@ fslamap.c \ @NOFORTRAN_FALSE@ fspecfluxframe.c \ @NOFORTRAN_FALSE@ fspecframe.c \ @NOFORTRAN_FALSE@ fspecmap.c \ @NOFORTRAN_FALSE@ fsphmap.c \ @NOFORTRAN_FALSE@ fstc.c \ @NOFORTRAN_FALSE@ fstccatalogentrylocation.c \ @NOFORTRAN_FALSE@ fstcobsdatalocation.c \ @NOFORTRAN_FALSE@ fstcresourceprofile.c \ @NOFORTRAN_FALSE@ fstcschan.c \ @NOFORTRAN_FALSE@ fstcsearchlocation.c \ @NOFORTRAN_FALSE@ fswitchmap.c \ @NOFORTRAN_FALSE@ ftable.c \ @NOFORTRAN_FALSE@ ftimeframe.c \ @NOFORTRAN_FALSE@ ftimemap.c \ @NOFORTRAN_FALSE@ ftranmap.c \ @NOFORTRAN_FALSE@ funitmap.c \ @NOFORTRAN_FALSE@ funitnormmap.c \ @NOFORTRAN_FALSE@ fwcsmap.c \ @NOFORTRAN_FALSE@ fwinmap.c \ @NOFORTRAN_FALSE@ fxmlchan.c \ @NOFORTRAN_FALSE@ fzoommap.c @NOFORTRAN_TRUE@F_C_ROUTINES = # Header files which contribute to the "ast.h" file, organised to correspond # with the class hierarchy. AST_H_FILES = \ xml.h \ wcstrig.h \ proj.h \ memory.h \ error.h \ globals.h \ unit.h \ ast_err.h \ version.h \ object.h \ keymap.h \ table.h \ fitstable.h \ pointset.h \ axis.h \ skyaxis.h \ mapping.h \ cmpmap.h \ dssmap.h \ grismmap.h \ intramap.h \ lutmap.h \ mathmap.h \ matrixmap.h \ pcdmap.h \ permmap.h \ polymap.h \ ratemap.h \ normmap.h \ shiftmap.h \ slamap.h \ specmap.h \ sphmap.h \ timemap.h \ selectormap.h \ switchmap.h \ tranmap.h \ unitmap.h \ unitnormmap.h \ wcsmap.h \ winmap.h \ zoommap.h \ frame.h \ cmpframe.h \ specfluxframe.h \ fluxframe.h \ frameset.h \ plot.h \ plot3d.h \ skyframe.h \ specframe.h \ dsbspecframe.h \ region.h \ box.h \ circle.h \ cmpregion.h \ ellipse.h \ interval.h \ nullregion.h \ pointlist.h \ polygon.h \ prism.h \ stc.h \ stcresourceprofile.h \ stcsearchlocation.h \ stccatalogentrylocation.h \ stcobsdatalocation.h \ timeframe.h \ channel.h \ fitschan.h \ stcschan.h \ xmlchan.h # All the (C) include files required to build the library. GRP_C_INCLUDE_FILES = \ $(AST_H_FILES) \ ems.h \ err.h \ Ers.h \ f77.h \ grf.h \ grf3d.h \ pg3d.h \ loader.h \ pal2ast.h \ skyaxis.h \ erfa2ast.h \ stc.h \ stcresourceprofile.h \ stcsearchlocation.h \ stccatalogentrylocation.h \ stcobsdatalocation.h \ wcsmath.h \ wcstrig.h \ xmlchan.h @NOFORTRAN_FALSE@F_C_INCLUDE_FILES = \ @NOFORTRAN_FALSE@ c2f77.h @NOFORTRAN_TRUE@F_C_INCLUDE_FILES = # The following list should include AST_PAR, but that must not be # distributed, and so it is listed separately in # nodist_libast_la_SOURCES below. @NOFORTRAN_FALSE@GRP_F_INCLUDE_FILES = \ @NOFORTRAN_FALSE@ GRF_PAR \ @NOFORTRAN_FALSE@ AST_ERR @NOFORTRAN_TRUE@GRP_F_INCLUDE_FILES = # If we have no Fortran we are not building f77.h and we probably # do not want a Fortran runtime. This requires that PGPLOT is disabled. # We replace it with the stub GRF interface. An alternative would # be to have the PGPLOT wrappers use a preprocessor symbol to build # the pgplot to always error if used. @NOFORTRAN_FALSE@GRF_PGPLOT_SOURCES = \ @NOFORTRAN_FALSE@ grf_pgplot.c @NOFORTRAN_TRUE@GRF_PGPLOT_SOURCES = \ @NOFORTRAN_TRUE@ grf_5.6.c @NOFORTRAN_FALSE@GRF3D_PGPLOT_SOURCES = \ @NOFORTRAN_FALSE@ grf3d_pgplot.c @NOFORTRAN_TRUE@GRF3D_PGPLOT_SOURCES = \ @NOFORTRAN_TRUE@ grf3d.c DOCUMENTATION_PRODUCTS = $(PAPER_DOCUMENTATION) $(HYPER_DOCUMENTATION) PAPER_DOCUMENTATION = sun210.tex sun211.tex sun210.pdf sun211.pdf HYPER_DOCUMENTATION = sun210.htx_tar sun211.htx_tar PDF_FIGURES = \ cmpframe.pdf \ complex.pdf \ frames.pdf \ frameset.pdf \ fronta.pdf \ fronta_bw.pdf \ frontb.pdf \ frontb_bw.pdf \ frontc.pdf \ frontc_bw.pdf \ fsalign.pdf \ fsconvert.pdf \ fsexample.pdf \ fsmerge.pdf \ fsremap.pdf \ gridplot.pdf \ gridplot_bw.pdf \ mapping.pdf \ overgrid.pdf \ overgrid_bw.pdf \ parallel.pdf \ series.pdf \ simpexamp.pdf WCSLIB_FILES = \ proj.c \ tpn.c \ proj.h \ wcstrig.c \ wcsmath.h \ wcstrig.h STAR_PAL_FILES = \ pal/pal.h \ pal/palAddet.c \ pal/palAmpqk.c \ pal/palCaldj.c \ pal/palDat.c \ pal/palDe2h.c \ pal/palDeuler.c \ pal/palDh2e.c \ pal/palDjcal.c \ pal/palDmat.c \ pal/palDrange.c \ pal/palDs2tp.c \ pal/palDtp2s.c \ pal/palDtps2c.c \ pal/palDtt.c \ pal/palEcmat.c \ pal/palEqgal.c \ pal/palEtrms.c \ pal/palEvp.c \ pal/palFk45z.c \ pal/palFk524.c \ pal/palFk54z.c \ pal/palGaleq.c \ pal/palGalsup.c \ pal/palMappa.c \ pal/palMapqkz.c \ pal/palOne2One.c \ pal/palPrebn.c \ pal/palPrec.c \ pal/palPrenut.c \ pal/palPvobs.c \ pal/palRvgalc.c \ pal/palRvlg.c \ pal/palRvlsrd.c \ pal/palRvlsrk.c \ pal/palSubet.c \ pal/palSupgal.c \ pal/pal1sofa.h \ pal/palmac.h ERFA_FILES = \ erfa/00READ.ME \ erfa/erfa.h \ erfa/erfam.h \ erfa/a2af.c \ erfa/a2tf.c \ erfa/af2a.c \ erfa/anp.c \ erfa/anpm.c \ erfa/bi00.c \ erfa/bp00.c \ erfa/bp06.c \ erfa/bpn2xy.c \ erfa/c2i00a.c \ erfa/c2i00b.c \ erfa/c2i06a.c \ erfa/c2ibpn.c \ erfa/c2ixy.c \ erfa/c2ixys.c \ erfa/c2s.c \ erfa/c2t00a.c \ erfa/c2t00b.c \ erfa/c2t06a.c \ erfa/c2tcio.c \ erfa/c2teqx.c \ erfa/c2tpe.c \ erfa/c2txy.c \ erfa/cal2jd.c \ erfa/cp.c \ erfa/cpv.c \ erfa/cr.c \ erfa/d2dtf.c \ erfa/d2tf.c \ erfa/dat.c \ erfa/dtdb.c \ erfa/dtf2d.c \ erfa/ee00.c \ erfa/ee00a.c \ erfa/ee00b.c \ erfa/ee06a.c \ erfa/eect00.c \ erfa/eform.c \ erfa/eo06a.c \ erfa/eors.c \ erfa/epb.c \ erfa/epb2jd.c \ erfa/epj.c \ erfa/epj2jd.c \ erfa/epv00.c \ erfa/eqeq94.c \ erfa/era00.c \ erfa/fad03.c \ erfa/fae03.c \ erfa/faf03.c \ erfa/faju03.c \ erfa/fal03.c \ erfa/falp03.c \ erfa/fama03.c \ erfa/fame03.c \ erfa/fane03.c \ erfa/faom03.c \ erfa/fapa03.c \ erfa/fasa03.c \ erfa/faur03.c \ erfa/fave03.c \ erfa/fk52h.c \ erfa/fk5hip.c \ erfa/fk5hz.c \ erfa/fw2m.c \ erfa/fw2xy.c \ erfa/gc2gd.c \ erfa/gc2gde.c \ erfa/gd2gc.c \ erfa/gd2gce.c \ erfa/gmst00.c \ erfa/gmst06.c \ erfa/gmst82.c \ erfa/gst00a.c \ erfa/gst00b.c \ erfa/gst06.c \ erfa/gst06a.c \ erfa/gst94.c \ erfa/h2fk5.c \ erfa/hfk5z.c \ erfa/ir.c \ erfa/jd2cal.c \ erfa/jdcalf.c \ erfa/num00a.c \ erfa/num00b.c \ erfa/num06a.c \ erfa/numat.c \ erfa/nut00a.c \ erfa/nut00b.c \ erfa/nut06a.c \ erfa/nut80.c \ erfa/nutm80.c \ erfa/obl06.c \ erfa/obl80.c \ erfa/p06e.c \ erfa/p2pv.c \ erfa/p2s.c \ erfa/pap.c \ erfa/pas.c \ erfa/pb06.c \ erfa/pdp.c \ erfa/pfw06.c \ erfa/plan94.c \ erfa/pm.c \ erfa/pmat00.c \ erfa/pmat06.c \ erfa/pmat76.c \ erfa/pmp.c \ erfa/pn.c \ erfa/pn00.c \ erfa/pn00a.c \ erfa/pn00b.c \ erfa/pn06.c \ erfa/pn06a.c \ erfa/pnm00a.c \ erfa/pnm00b.c \ erfa/pnm06a.c \ erfa/pnm80.c \ erfa/pom00.c \ erfa/ppp.c \ erfa/ppsp.c \ erfa/pr00.c \ erfa/prec76.c \ erfa/pv2p.c \ erfa/pv2s.c \ erfa/pvdpv.c \ erfa/pvm.c \ erfa/pvmpv.c \ erfa/pvppv.c \ erfa/pvstar.c \ erfa/pvu.c \ erfa/pvup.c \ erfa/pvxpv.c \ erfa/pxp.c \ erfa/refco.c \ erfa/rm2v.c \ erfa/rv2m.c \ erfa/rx.c \ erfa/rxp.c \ erfa/rxpv.c \ erfa/rxr.c \ erfa/ry.c \ erfa/rz.c \ erfa/s00.c \ erfa/s00a.c \ erfa/s00b.c \ erfa/s06.c \ erfa/s06a.c \ erfa/s2c.c \ erfa/s2p.c \ erfa/s2pv.c \ erfa/s2xpv.c \ erfa/sepp.c \ erfa/seps.c \ erfa/sp00.c \ erfa/starpm.c \ erfa/starpv.c \ erfa/sxp.c \ erfa/sxpv.c \ erfa/taitt.c \ erfa/taiut1.c \ erfa/taiutc.c \ erfa/tcbtdb.c \ erfa/tcgtt.c \ erfa/tdbtcb.c \ erfa/tdbtt.c \ erfa/tf2a.c \ erfa/tf2d.c \ erfa/tr.c \ erfa/trxp.c \ erfa/trxpv.c \ erfa/tttai.c \ erfa/tttcg.c \ erfa/tttdb.c \ erfa/ttut1.c \ erfa/ut1tai.c \ erfa/ut1tt.c \ erfa/ut1utc.c \ erfa/utctai.c \ erfa/utcut1.c \ erfa/xy06.c \ erfa/xys00a.c \ erfa/xys00b.c \ erfa/xys06a.c \ erfa/zp.c \ erfa/zpv.c \ erfa/zr.c PAL_FILES = \ palwrap.c \ pal.h \ erfa.h \ erfam.h CMINPACK_FILES = \ cminpack/cminpack.h \ cminpack/cminpackP.h \ cminpack/lmder1.c \ cminpack/lmder.c \ cminpack/dpmpar.c \ cminpack/enorm.c \ cminpack/qrfac.c \ cminpack/lmpar.c \ cminpack/qrsolv.c bin_SCRIPTS = ast_link dist_bin_SCRIPTS = ast_link_adam noinst_SCRIPTS = ast_cpp dist_noinst_SCRIPTS = makeh # Scripts are not distributed by default (since they might be derived objects) # Add these to the distribution below. In fact, it would be useful # and straightforward to make ast_link{,_adam} derived, since they # could then have installation directories painlessly edited in to # them. This might be a requirement for scripts which supported # linking against shared libraries. # Headers required by library users. Both of the following lines # indicate headers which are installed. include_HEADERS = GRF_PAR grf.h grf3d.h # Following are generated, so should not be distributed. nodist_include_HEADERS = ast.h AST_PAR include_MESSAGES = AST_ERR ast_err.h @EXTERNAL_PAL_FALSE@PAL_LIB = libast_pal.la @EXTERNAL_PAL_TRUE@PAL_LIB = lib_LTLIBRARIES = \ $(PAL_LIB) \ libast.la \ libast_err.la \ libast_ems.la \ libast_drama.la \ libast_grf3d.la \ libast_grf_2.0.la \ libast_grf_3.2.la \ libast_grf_5.6.la \ libast_pgplot.la \ libast_pgplot3d.la stardocs_DATA = @STAR_LATEX_DOCUMENTATION@ dist_starnews_DATA = ast.news dist_pkgdata_DATA = COPYING COPYING.LESSER COPYING.LIB # Make all library code position independent by default. This is handy for # creating shareable libraries from the static ones (Java JNI libraries). # Note we do not simply set the AM_CFLAGS variable, as this would also # apply to programs compiled without using libtool, possibly causing the # compilation to fail. @NOPIC_FALSE@@NOTHREADS_FALSE@libast_la_CFLAGS = $(AM_CFLAGS) -prefer-pic -DTHREAD_SAFE @NOPIC_TRUE@@NOTHREADS_FALSE@libast_la_CFLAGS = $(AM_CFLAGS) -DTHREAD_SAFE @NOTHREADS_TRUE@libast_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_err_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_ems_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_drama_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_grf3d_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_grf_2_0_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_grf_3_2_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_grf_5_6_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_pgplot_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_pgplot3d_la_CFLAGS = $(AM_CFLAGS) -prefer-pic @NOPIC_FALSE@libast_pal_la_CFLAGS = $(AM_CFLAGS) -prefer-pic # The module containing the main AST classes libast_la_SOURCES = \ $(GRP_C_ROUTINES) \ $(F_C_ROUTINES) \ $(GRP_C_INCLUDE_FILES) \ $(F_C_INCLUDE_FILES) \ $(GRP_F_INCLUDE_FILES) \ $(CMINPACK_FILES) \ $(WCSLIB_FILES) \ ast_err.h @EXTERNAL_PAL_FALSE@libast_la_LIBADD = libast_pal.la # Ensure libast links against libraries containing functions used within # libast. If AST is configured --with-external-pal, then the internal # libast_pal library will be empty, and we link to an external PAL # library instead. @EXTERNAL_PAL_TRUE@libast_la_LIBADD = $(libdir)/libpal.la # AST_PAR is really part of GRP_F_INCLUDE_FILES, but it must not be # distributed, so list it separately. nodist_libast_la_SOURCES = \ ast.h \ AST_PAR # The default error reporting module. libast_err_la_SOURCES = err_null.c # The error reporting module that uses EMS to deliver errors. libast_ems_la_SOURCES = err_ems.c # The error reporting module that uses DRAMA Ers to deliver errors. libast_drama_la_SOURCES = err_drama.c # The module containing null implementations of the 3D graphics routines # required by AST libast_grf3d_la_SOURCES = grf3d.c # The module containing null implementations of the graphics routines # required by AST V2.0 libast_grf_2_0_la_SOURCES = grf_2.0.c # The module containing null implementations of the graphics routines # added by AST V3.2 and not present in V2.0 libast_grf_3_2_la_SOURCES = grf_3.2.c # The module containing null implementations of the graphics routines # added by AST V5.6 and not present in V3.2 libast_grf_5_6_la_SOURCES = grf_5.6.c # The graphics module that uses PGPLOT for 2D graphical output. libast_pgplot_la_SOURCES = $(GRF_PGPLOT_SOURCES) # The graphics module that uses PGPLOT for 3D graphical output. libast_pgplot3d_la_SOURCES = $(GRF3D_PGPLOT_SOURCES) # Positional astronomy libraries. libast_pal_la_SOURCES = $(PAL_FILES) # The following files are built by the targets in this makefile. MAINTAINERCLEANFILES = version.h builddocs addversion \ ast.h $(DOCUMENTATION_PRODUCTS) CLEANFILES = AST_PAR ast.h astbad_SOURCES = astbad.c pointset.h # ast_link is generated from ast_link.in; ast_link_adam does not # need configuration, and so is not mentioned in AC_CONFIG_FILES within # configure.ac, and so is not distributed automatically. # # makeh is required in order to build ast.h after distribution (see below). EXTRA_DIST = ast_par.source sun210_figures sun211_figures pal erfa cminpack # AST_ERR and ast_err.h are `generated source files', and so must be # generated before any other compilations are done. Note that these # files are generated on the distribution host, and so this # declaration has no effect post-distribution. # # AST_PAR is also a generated source file, but it should _not_ be # included in the list of BUILT_SOURCES, otherwise `make' tries to make # it before it makes the `astbad' program it depends on. Instead, # just rely on the dependencies expressed in the main body above to # have AST_PAR built before it is needed. # # version.h is included by object.h, and thus indirectly by most modules. # It's most straightforward to build it at the beginning. BUILT_SOURCES = AST_ERR ast_err.h version.h # Make pre-distribution files. These are files which are required for # building the distribution, but are not themselves distributed. # The source files here should be mentioned in STAR_PREDIST_SOURCES in # configure.ac @PREDIST@predist_subs = sed \ @PREDIST@ -e 's,@PACKAGE_VERSION\@,$(PACKAGE_VERSION),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MAJOR\@,$(PACKAGE_VERSION_MAJOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MINOR\@,$(PACKAGE_VERSION_MINOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_RELEASE\@,$(PACKAGE_VERSION_RELEASE),' \ @PREDIST@ -e 's,@PERL\@,$(PERL),' \ @PREDIST@ -e 's,@STARLINK\@,$(STARLINK),' ast_test_SOURCES = ast_test.c #ast_test_LDADD = `ast_link` # Expand ast_link to avoid libast_pass2, which causes problems for Solaris ast_test_LDADD = @LIBPAL@ libast.la libast_pal.la libast_grf_3.2.la libast_grf_5.6.la libast_grf_2.0.la libast_grf3d.la libast_err.la -lm starfacs_DATA = fac_1521_err all: $(BUILT_SOURCES) config.h $(MAKE) $(AM_MAKEFLAGS) all-am .SUFFIXES: .SUFFIXES: .c .dvi .htx_tar .lo .log .o .obj .pdf .ps .test .test$(EXEEXT) .tex .trs am--refresh: Makefile @: $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ echo ' cd $(srcdir) && $(AUTOMAKE) --startree'; \ $(am__cd) $(srcdir) && $(AUTOMAKE) --startree \ && exit 0; \ exit 1;; \ esac; \ done; \ echo ' cd $(top_srcdir) && $(AUTOMAKE) --startree Makefile'; \ $(am__cd) $(top_srcdir) && \ $(AUTOMAKE) --startree Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ *config.status*) \ echo ' $(SHELL) ./config.status'; \ $(SHELL) ./config.status;; \ *) \ echo ' cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $@ $(am__depfiles_maybe);; \ esac; $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) $(SHELL) ./config.status --recheck $(top_srcdir)/configure: $(am__configure_deps) $(am__cd) $(srcdir) && $(AUTOCONF) $(ACLOCAL_M4): $(am__aclocal_m4_deps) $(am__cd) $(srcdir) && $(ACLOCAL) $(ACLOCAL_AMFLAGS) $(am__aclocal_m4_deps): config.h: stamp-h1 @test -f $@ || rm -f stamp-h1 @test -f $@ || $(MAKE) $(AM_MAKEFLAGS) stamp-h1 stamp-h1: $(srcdir)/config.h.in $(top_builddir)/config.status @rm -f stamp-h1 cd $(top_builddir) && $(SHELL) ./config.status config.h $(srcdir)/config.h.in: $(am__configure_deps) ($(am__cd) $(top_srcdir) && $(AUTOHEADER)) rm -f stamp-h1 touch $@ distclean-hdr: -rm -f config.h stamp-h1 component.xml: $(top_builddir)/config.status $(srcdir)/component.xml.in cd $(top_builddir) && $(SHELL) ./config.status $@ ast_link: $(top_builddir)/config.status $(srcdir)/ast_link.in cd $(top_builddir) && $(SHELL) ./config.status $@ ast_link_adam: $(top_builddir)/config.status $(srcdir)/ast_link_adam.in cd $(top_builddir) && $(SHELL) ./config.status $@ object.h: $(top_builddir)/config.status $(srcdir)/object.h.in cd $(top_builddir) && $(SHELL) ./config.status $@ f77.h: $(top_builddir)/config.status $(srcdir)/f77.h.in cd $(top_builddir) && $(SHELL) ./config.status $@ ast_cpp: $(top_builddir)/config.status $(srcdir)/ast_cpp.in cd $(top_builddir) && $(SHELL) ./config.status $@ install-libLTLIBRARIES: $(lib_LTLIBRARIES) @$(NORMAL_INSTALL) @list='$(lib_LTLIBRARIES)'; test -n "$(libdir)" || list=; \ list2=; for p in $$list; do \ if test -f $$p; then \ list2="$$list2 $$p"; \ else :; fi; \ done; \ test -z "$$list2" || { \ echo " $(MKDIR_P) '$(DESTDIR)$(libdir)'"; \ $(MKDIR_P) "$(DESTDIR)$(libdir)" || exit 1; \ echo " $(LIBTOOL) $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=install $(INSTALL) $(INSTALL_STRIP_FLAG) $$list2 '$(DESTDIR)$(libdir)'"; \ $(LIBTOOL) $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=install $(INSTALL) $(INSTALL_STRIP_FLAG) $$list2 "$(DESTDIR)$(libdir)"; \ if $(MANIFEST); then \ for p in $$list2; do \ echo "MANIFEST:$(DESTDIR)$(libdir)/$$p"; \ expr $$p : '.*\.la$$' >/dev/null || \ { echo "Installing non-la file $$p!"; exit 1; }; \ (. ./$$p; \ if test -n "$$library_names"; then \ for l in $$library_names; do \ echo "MANIFEST:$(DESTDIR)$$libdir/$$l"; \ done; \ fi; \ if test -n "$$old_library"; then \ echo "MANIFEST:$(DESTDIR)$$libdir/$$old_library"; \ else :; fi; \ ); \ done; \ else :; fi; \ } uninstall-libLTLIBRARIES: @$(NORMAL_UNINSTALL) @list='$(lib_LTLIBRARIES)'; test -n "$(libdir)" || list=; \ for p in $$list; do \ $(am__strip_dir) \ echo " $(LIBTOOL) $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=uninstall rm -f '$(DESTDIR)$(libdir)/$$f'"; \ $(LIBTOOL) $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=uninstall rm -f "$(DESTDIR)$(libdir)/$$f"; \ done clean-libLTLIBRARIES: -test -z "$(lib_LTLIBRARIES)" || rm -f $(lib_LTLIBRARIES) @list='$(lib_LTLIBRARIES)'; \ locs=`for p in $$list; do echo $$p; done | \ sed 's|^[^/]*$$|.|; s|/[^/]*$$||; s|$$|/so_locations|' | \ sort -u`; \ test -z "$$locs" || { \ echo rm -f $${locs}; \ rm -f $${locs}; \ } cminpack/$(am__dirstamp): @$(MKDIR_P) cminpack @: > cminpack/$(am__dirstamp) cminpack/$(DEPDIR)/$(am__dirstamp): @$(MKDIR_P) cminpack/$(DEPDIR) @: > cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-lmder1.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-lmder.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-dpmpar.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-enorm.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-qrfac.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-lmpar.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) cminpack/libast_la-qrsolv.lo: cminpack/$(am__dirstamp) \ cminpack/$(DEPDIR)/$(am__dirstamp) libast.la: $(libast_la_OBJECTS) $(libast_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_la_LINK) -rpath $(libdir) $(libast_la_LDFLAGS) $(libast_la_OBJECTS) $(libast_la_LIBADD) $(LIBS) libast_drama.la: $(libast_drama_la_OBJECTS) $(libast_drama_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_drama_la_LINK) -rpath $(libdir) $(libast_drama_la_LDFLAGS) $(libast_drama_la_OBJECTS) $(libast_drama_la_LIBADD) $(LIBS) libast_ems.la: $(libast_ems_la_OBJECTS) $(libast_ems_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_ems_la_LINK) -rpath $(libdir) $(libast_ems_la_LDFLAGS) $(libast_ems_la_OBJECTS) $(libast_ems_la_LIBADD) $(LIBS) libast_err.la: $(libast_err_la_OBJECTS) $(libast_err_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_err_la_LINK) -rpath $(libdir) $(libast_err_la_LDFLAGS) $(libast_err_la_OBJECTS) $(libast_err_la_LIBADD) $(LIBS) libast_grf3d.la: $(libast_grf3d_la_OBJECTS) $(libast_grf3d_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_grf3d_la_LINK) -rpath $(libdir) $(libast_grf3d_la_LDFLAGS) $(libast_grf3d_la_OBJECTS) $(libast_grf3d_la_LIBADD) $(LIBS) libast_grf_2.0.la: $(libast_grf_2_0_la_OBJECTS) $(libast_grf_2_0_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_grf_2_0_la_LINK) -rpath $(libdir) $(libast_grf_2_0_la_LDFLAGS) $(libast_grf_2_0_la_OBJECTS) $(libast_grf_2_0_la_LIBADD) $(LIBS) libast_grf_3.2.la: $(libast_grf_3_2_la_OBJECTS) $(libast_grf_3_2_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_grf_3_2_la_LINK) -rpath $(libdir) $(libast_grf_3_2_la_LDFLAGS) $(libast_grf_3_2_la_OBJECTS) $(libast_grf_3_2_la_LIBADD) $(LIBS) libast_grf_5.6.la: $(libast_grf_5_6_la_OBJECTS) $(libast_grf_5_6_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_grf_5_6_la_LINK) -rpath $(libdir) $(libast_grf_5_6_la_LDFLAGS) $(libast_grf_5_6_la_OBJECTS) $(libast_grf_5_6_la_LIBADD) $(LIBS) libast_pal.la: $(libast_pal_la_OBJECTS) $(libast_pal_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_pal_la_LINK) $(am_libast_pal_la_rpath) $(libast_pal_la_LDFLAGS) $(libast_pal_la_OBJECTS) $(libast_pal_la_LIBADD) $(LIBS) libast_pgplot.la: $(libast_pgplot_la_OBJECTS) $(libast_pgplot_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_pgplot_la_LINK) -rpath $(libdir) $(libast_pgplot_la_LDFLAGS) $(libast_pgplot_la_OBJECTS) $(libast_pgplot_la_LIBADD) $(LIBS) libast_pgplot3d.la: $(libast_pgplot3d_la_OBJECTS) $(libast_pgplot3d_la_DEPENDENCIES) $(AM_V_CCLD)$(libast_pgplot3d_la_LINK) -rpath $(libdir) $(libast_pgplot3d_la_LDFLAGS) $(libast_pgplot3d_la_OBJECTS) $(libast_pgplot3d_la_LIBADD) $(LIBS) clean-checkPROGRAMS: @list='$(check_PROGRAMS)'; test -n "$$list" || exit 0; \ echo " rm -f" $$list; \ rm -f $$list || exit $$?; \ test -n "$(EXEEXT)" || exit 0; \ list=`for p in $$list; do echo "$$p"; done | sed 's/$(EXEEXT)$$//'`; \ echo " rm -f" $$list; \ rm -f $$list clean-noinstPROGRAMS: @list='$(noinst_PROGRAMS)'; test -n "$$list" || exit 0; \ echo " rm -f" $$list; \ rm -f $$list || exit $$?; \ test -n "$(EXEEXT)" || exit 0; \ list=`for p in $$list; do echo "$$p"; done | sed 's/$(EXEEXT)$$//'`; \ echo " rm -f" $$list; \ rm -f $$list ast_test$(EXEEXT): $(ast_test_OBJECTS) $(ast_test_DEPENDENCIES) $(EXTRA_ast_test_DEPENDENCIES) @rm -f ast_test$(EXEEXT) $(AM_V_CCLD)$(LINK) $(ast_test_LDFLAGS) $(ast_test_OBJECTS) $(ast_test_LDADD) $(LIBS) astbad$(EXEEXT): $(astbad_OBJECTS) $(astbad_DEPENDENCIES) $(EXTRA_astbad_DEPENDENCIES) @rm -f astbad$(EXEEXT) $(AM_V_CCLD)$(LINK) $(astbad_LDFLAGS) $(astbad_OBJECTS) $(astbad_LDADD) $(LIBS) install-binSCRIPTS: $(bin_SCRIPTS) @$(NORMAL_INSTALL) @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(bindir)'"; \ $(MKDIR_P) "$(DESTDIR)$(bindir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ if test -f "$$d$$p"; then echo "$$d$$p"; echo "$$p"; else :; fi; \ done | \ sed -e 'p;s,.*/,,;n' \ -e 'h;s|.*|.|' \ -e 'p;x;s,.*/,,;$(transform)' | sed 'N;N;N;s,\n, ,g' | \ $(AWK) 'BEGIN { files["."] = ""; dirs["."] = 1; } \ { d=$$3; if (dirs[d] != 1) { print "d", d; dirs[d] = 1 } \ if ($$2 == $$4) { files[d] = files[d] " " $$1; \ if (++n[d] == $(am__install_max)) { \ print "f", d, files[d]; n[d] = 0; files[d] = "" } } \ else { print "f", d "/" $$4, $$1 } } \ END { for (d in files) print "f", d, files[d] }' | \ while read type dir files; do \ if test "$$dir" = .; then dir=; else dir=/$$dir; fi; \ test -z "$$files" || { \ echo " $(INSTALL_SCRIPT) $$files '$(DESTDIR)$(bindir)$$dir'"; \ $(INSTALL_SCRIPT) $$files "$(DESTDIR)$(bindir)$$dir" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(bindir)$$dir/$$f" || :; \ done; \ } \ done uninstall-binSCRIPTS: @$(NORMAL_UNINSTALL) @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || exit 0; \ files=`for p in $$list; do echo "$$p"; done | \ sed -e 's,.*/,,;$(transform)'`; \ dir='$(DESTDIR)$(bindir)'; $(am__uninstall_files_from_dir) install-dist_binSCRIPTS: $(dist_bin_SCRIPTS) @$(NORMAL_INSTALL) @list='$(dist_bin_SCRIPTS)'; test -n "$(bindir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(bindir)'"; \ $(MKDIR_P) "$(DESTDIR)$(bindir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ if test -f "$$d$$p"; then echo "$$d$$p"; echo "$$p"; else :; fi; \ done | \ sed -e 'p;s,.*/,,;n' \ -e 'h;s|.*|.|' \ -e 'p;x;s,.*/,,;$(transform)' | sed 'N;N;N;s,\n, ,g' | \ $(AWK) 'BEGIN { files["."] = ""; dirs["."] = 1; } \ { d=$$3; if (dirs[d] != 1) { print "d", d; dirs[d] = 1 } \ if ($$2 == $$4) { files[d] = files[d] " " $$1; \ if (++n[d] == $(am__install_max)) { \ print "f", d, files[d]; n[d] = 0; files[d] = "" } } \ else { print "f", d "/" $$4, $$1 } } \ END { for (d in files) print "f", d, files[d] }' | \ while read type dir files; do \ if test "$$dir" = .; then dir=; else dir=/$$dir; fi; \ test -z "$$files" || { \ echo " $(INSTALL_SCRIPT) $$files '$(DESTDIR)$(bindir)$$dir'"; \ $(INSTALL_SCRIPT) $$files "$(DESTDIR)$(bindir)$$dir" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(bindir)$$dir/$$f" || :; \ done; \ } \ done uninstall-dist_binSCRIPTS: @$(NORMAL_UNINSTALL) @list='$(dist_bin_SCRIPTS)'; test -n "$(bindir)" || exit 0; \ files=`for p in $$list; do echo "$$p"; done | \ sed -e 's,.*/,,;$(transform)'`; \ dir='$(DESTDIR)$(bindir)'; $(am__uninstall_files_from_dir) mostlyclean-compile: -rm -f *.$(OBJEXT) -rm -f cminpack/*.$(OBJEXT) -rm -f cminpack/*.lo distclean-compile: -rm -f *.tab.c @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ast_test.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/astbad.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_drama_la-err_drama.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_ems_la-err_ems.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_err_la-err_null.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_grf3d_la-grf3d.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_grf_2_0_la-grf_2.0.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_grf_3_2_la-grf_3.2.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_grf_5_6_la-grf_5.6.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-axis.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-box.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-c2f77.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-channel.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-circle.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-cmpframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-cmpmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-cmpregion.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-dsbspecframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-dssmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ellipse.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-error.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fbox.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fchannel.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fcircle.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fcmpframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fcmpmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fcmpregion.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fdsbspecframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fdssmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fellipse.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ferror.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ffitschan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ffitstable.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ffluxframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fframeset.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fgrismmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-finterval.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fintramap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fitschan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fitstable.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fkeymap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-flutmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fluxframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fmapping.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fmathmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fmatrixmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fnormmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fnullregion.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fobject.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fpcdmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fpermmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fplot.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fplot3d.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fpointlist.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fpolygon.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fpolymap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fprism.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-frame.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-frameset.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fratemap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fregion.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fselectormap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fshiftmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fskyframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fslamap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fspecfluxframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fspecframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fspecmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fsphmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstc.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstccatalogentrylocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstcobsdatalocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstcresourceprofile.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstcschan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fstcsearchlocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fswitchmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ftable.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ftimeframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ftimemap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ftranmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-funitmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-funitnormmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fwcsmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fwinmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fxmlchan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-fzoommap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-globals.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-grismmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-interval.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-intramap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-keymap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-loader.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-lutmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-mapping.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-mathmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-matrixmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-memory.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-normmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-nullregion.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-object.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-pcdmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-permmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-plot.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-plot3d.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-pointlist.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-pointset.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-polygon.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-polymap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-prism.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-proj.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-ratemap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-region.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-selectormap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-shiftmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-skyaxis.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-skyframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-slamap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-specfluxframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-specframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-specmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-sphmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stc.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stccatalogentrylocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stcobsdatalocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stcresourceprofile.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stcschan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-stcsearchlocation.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-switchmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-table.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-timeframe.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-timemap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-tpn.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-tranmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-unit.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-unitmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-unitnormmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-wcsmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-wcstrig.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-winmap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-xml.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-xmlchan.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_la-zoommap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_pal_la-palwrap.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_pgplot3d_la-grf3d.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_pgplot3d_la-grf3d_pgplot.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_pgplot_la-grf_5.6.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/libast_pgplot_la-grf_pgplot.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-dpmpar.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-enorm.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-lmder.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-lmder1.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-lmpar.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-qrfac.Plo@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@cminpack/$(DEPDIR)/libast_la-qrsolv.Plo@am__quote@ .c.o: @am__fastdepCC_TRUE@ $(AM_V_CC)depbase=`echo $@ | sed 's|[^/]*$$|$(DEPDIR)/&|;s|\.o$$||'`;\ @am__fastdepCC_TRUE@ $(COMPILE) -MT $@ -MD -MP -MF $$depbase.Tpo -c -o $@ $< &&\ @am__fastdepCC_TRUE@ $(am__mv) $$depbase.Tpo $$depbase.Po @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c -o $@ $< .c.obj: @am__fastdepCC_TRUE@ $(AM_V_CC)depbase=`echo $@ | sed 's|[^/]*$$|$(DEPDIR)/&|;s|\.obj$$||'`;\ @am__fastdepCC_TRUE@ $(COMPILE) -MT $@ -MD -MP -MF $$depbase.Tpo -c -o $@ `$(CYGPATH_W) '$<'` &&\ @am__fastdepCC_TRUE@ $(am__mv) $$depbase.Tpo $$depbase.Po @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c -o $@ `$(CYGPATH_W) '$<'` .c.lo: @am__fastdepCC_TRUE@ $(AM_V_CC)depbase=`echo $@ | sed 's|[^/]*$$|$(DEPDIR)/&|;s|\.lo$$||'`;\ @am__fastdepCC_TRUE@ $(LTCOMPILE) -MT $@ -MD -MP -MF $$depbase.Tpo -c -o $@ $< &&\ @am__fastdepCC_TRUE@ $(am__mv) $$depbase.Tpo $$depbase.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LTCOMPILE) -c -o $@ $< libast_la-axis.lo: axis.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-axis.lo -MD -MP -MF $(DEPDIR)/libast_la-axis.Tpo -c -o libast_la-axis.lo `test -f 'axis.c' || echo '$(srcdir)/'`axis.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-axis.Tpo $(DEPDIR)/libast_la-axis.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='axis.c' object='libast_la-axis.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-axis.lo `test -f 'axis.c' || echo '$(srcdir)/'`axis.c libast_la-box.lo: box.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-box.lo -MD -MP -MF $(DEPDIR)/libast_la-box.Tpo -c -o libast_la-box.lo `test -f 'box.c' || echo '$(srcdir)/'`box.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-box.Tpo $(DEPDIR)/libast_la-box.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='box.c' object='libast_la-box.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-box.lo `test -f 'box.c' || echo '$(srcdir)/'`box.c libast_la-channel.lo: channel.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-channel.lo -MD -MP -MF $(DEPDIR)/libast_la-channel.Tpo -c -o libast_la-channel.lo `test -f 'channel.c' || echo '$(srcdir)/'`channel.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-channel.Tpo $(DEPDIR)/libast_la-channel.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='channel.c' object='libast_la-channel.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-channel.lo `test -f 'channel.c' || echo '$(srcdir)/'`channel.c libast_la-circle.lo: circle.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-circle.lo -MD -MP -MF $(DEPDIR)/libast_la-circle.Tpo -c -o libast_la-circle.lo `test -f 'circle.c' || echo '$(srcdir)/'`circle.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-circle.Tpo $(DEPDIR)/libast_la-circle.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='circle.c' object='libast_la-circle.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-circle.lo `test -f 'circle.c' || echo '$(srcdir)/'`circle.c libast_la-cmpframe.lo: cmpframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-cmpframe.lo -MD -MP -MF $(DEPDIR)/libast_la-cmpframe.Tpo -c -o libast_la-cmpframe.lo `test -f 'cmpframe.c' || echo '$(srcdir)/'`cmpframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-cmpframe.Tpo $(DEPDIR)/libast_la-cmpframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cmpframe.c' object='libast_la-cmpframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-cmpframe.lo `test -f 'cmpframe.c' || echo '$(srcdir)/'`cmpframe.c libast_la-cmpmap.lo: cmpmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-cmpmap.lo -MD -MP -MF $(DEPDIR)/libast_la-cmpmap.Tpo -c -o libast_la-cmpmap.lo `test -f 'cmpmap.c' || echo '$(srcdir)/'`cmpmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-cmpmap.Tpo $(DEPDIR)/libast_la-cmpmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cmpmap.c' object='libast_la-cmpmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-cmpmap.lo `test -f 'cmpmap.c' || echo '$(srcdir)/'`cmpmap.c libast_la-cmpregion.lo: cmpregion.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-cmpregion.lo -MD -MP -MF $(DEPDIR)/libast_la-cmpregion.Tpo -c -o libast_la-cmpregion.lo `test -f 'cmpregion.c' || echo '$(srcdir)/'`cmpregion.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-cmpregion.Tpo $(DEPDIR)/libast_la-cmpregion.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cmpregion.c' object='libast_la-cmpregion.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-cmpregion.lo `test -f 'cmpregion.c' || echo '$(srcdir)/'`cmpregion.c libast_la-dsbspecframe.lo: dsbspecframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-dsbspecframe.lo -MD -MP -MF $(DEPDIR)/libast_la-dsbspecframe.Tpo -c -o libast_la-dsbspecframe.lo `test -f 'dsbspecframe.c' || echo '$(srcdir)/'`dsbspecframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-dsbspecframe.Tpo $(DEPDIR)/libast_la-dsbspecframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='dsbspecframe.c' object='libast_la-dsbspecframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-dsbspecframe.lo `test -f 'dsbspecframe.c' || echo '$(srcdir)/'`dsbspecframe.c libast_la-dssmap.lo: dssmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-dssmap.lo -MD -MP -MF $(DEPDIR)/libast_la-dssmap.Tpo -c -o libast_la-dssmap.lo `test -f 'dssmap.c' || echo '$(srcdir)/'`dssmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-dssmap.Tpo $(DEPDIR)/libast_la-dssmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='dssmap.c' object='libast_la-dssmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-dssmap.lo `test -f 'dssmap.c' || echo '$(srcdir)/'`dssmap.c libast_la-ellipse.lo: ellipse.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ellipse.lo -MD -MP -MF $(DEPDIR)/libast_la-ellipse.Tpo -c -o libast_la-ellipse.lo `test -f 'ellipse.c' || echo '$(srcdir)/'`ellipse.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ellipse.Tpo $(DEPDIR)/libast_la-ellipse.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ellipse.c' object='libast_la-ellipse.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ellipse.lo `test -f 'ellipse.c' || echo '$(srcdir)/'`ellipse.c libast_la-error.lo: error.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-error.lo -MD -MP -MF $(DEPDIR)/libast_la-error.Tpo -c -o libast_la-error.lo `test -f 'error.c' || echo '$(srcdir)/'`error.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-error.Tpo $(DEPDIR)/libast_la-error.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='error.c' object='libast_la-error.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-error.lo `test -f 'error.c' || echo '$(srcdir)/'`error.c libast_la-fitschan.lo: fitschan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fitschan.lo -MD -MP -MF $(DEPDIR)/libast_la-fitschan.Tpo -c -o libast_la-fitschan.lo `test -f 'fitschan.c' || echo '$(srcdir)/'`fitschan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fitschan.Tpo $(DEPDIR)/libast_la-fitschan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fitschan.c' object='libast_la-fitschan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fitschan.lo `test -f 'fitschan.c' || echo '$(srcdir)/'`fitschan.c libast_la-fitstable.lo: fitstable.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fitstable.lo -MD -MP -MF $(DEPDIR)/libast_la-fitstable.Tpo -c -o libast_la-fitstable.lo `test -f 'fitstable.c' || echo '$(srcdir)/'`fitstable.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fitstable.Tpo $(DEPDIR)/libast_la-fitstable.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fitstable.c' object='libast_la-fitstable.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fitstable.lo `test -f 'fitstable.c' || echo '$(srcdir)/'`fitstable.c libast_la-fluxframe.lo: fluxframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fluxframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fluxframe.Tpo -c -o libast_la-fluxframe.lo `test -f 'fluxframe.c' || echo '$(srcdir)/'`fluxframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fluxframe.Tpo $(DEPDIR)/libast_la-fluxframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fluxframe.c' object='libast_la-fluxframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fluxframe.lo `test -f 'fluxframe.c' || echo '$(srcdir)/'`fluxframe.c libast_la-frame.lo: frame.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-frame.lo -MD -MP -MF $(DEPDIR)/libast_la-frame.Tpo -c -o libast_la-frame.lo `test -f 'frame.c' || echo '$(srcdir)/'`frame.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-frame.Tpo $(DEPDIR)/libast_la-frame.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='frame.c' object='libast_la-frame.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-frame.lo `test -f 'frame.c' || echo '$(srcdir)/'`frame.c libast_la-frameset.lo: frameset.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-frameset.lo -MD -MP -MF $(DEPDIR)/libast_la-frameset.Tpo -c -o libast_la-frameset.lo `test -f 'frameset.c' || echo '$(srcdir)/'`frameset.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-frameset.Tpo $(DEPDIR)/libast_la-frameset.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='frameset.c' object='libast_la-frameset.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-frameset.lo `test -f 'frameset.c' || echo '$(srcdir)/'`frameset.c libast_la-globals.lo: globals.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-globals.lo -MD -MP -MF $(DEPDIR)/libast_la-globals.Tpo -c -o libast_la-globals.lo `test -f 'globals.c' || echo '$(srcdir)/'`globals.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-globals.Tpo $(DEPDIR)/libast_la-globals.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='globals.c' object='libast_la-globals.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-globals.lo `test -f 'globals.c' || echo '$(srcdir)/'`globals.c libast_la-grismmap.lo: grismmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-grismmap.lo -MD -MP -MF $(DEPDIR)/libast_la-grismmap.Tpo -c -o libast_la-grismmap.lo `test -f 'grismmap.c' || echo '$(srcdir)/'`grismmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-grismmap.Tpo $(DEPDIR)/libast_la-grismmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grismmap.c' object='libast_la-grismmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-grismmap.lo `test -f 'grismmap.c' || echo '$(srcdir)/'`grismmap.c libast_la-interval.lo: interval.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-interval.lo -MD -MP -MF $(DEPDIR)/libast_la-interval.Tpo -c -o libast_la-interval.lo `test -f 'interval.c' || echo '$(srcdir)/'`interval.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-interval.Tpo $(DEPDIR)/libast_la-interval.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='interval.c' object='libast_la-interval.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-interval.lo `test -f 'interval.c' || echo '$(srcdir)/'`interval.c libast_la-intramap.lo: intramap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-intramap.lo -MD -MP -MF $(DEPDIR)/libast_la-intramap.Tpo -c -o libast_la-intramap.lo `test -f 'intramap.c' || echo '$(srcdir)/'`intramap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-intramap.Tpo $(DEPDIR)/libast_la-intramap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='intramap.c' object='libast_la-intramap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-intramap.lo `test -f 'intramap.c' || echo '$(srcdir)/'`intramap.c libast_la-keymap.lo: keymap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-keymap.lo -MD -MP -MF $(DEPDIR)/libast_la-keymap.Tpo -c -o libast_la-keymap.lo `test -f 'keymap.c' || echo '$(srcdir)/'`keymap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-keymap.Tpo $(DEPDIR)/libast_la-keymap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='keymap.c' object='libast_la-keymap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-keymap.lo `test -f 'keymap.c' || echo '$(srcdir)/'`keymap.c libast_la-loader.lo: loader.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-loader.lo -MD -MP -MF $(DEPDIR)/libast_la-loader.Tpo -c -o libast_la-loader.lo `test -f 'loader.c' || echo '$(srcdir)/'`loader.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-loader.Tpo $(DEPDIR)/libast_la-loader.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='loader.c' object='libast_la-loader.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-loader.lo `test -f 'loader.c' || echo '$(srcdir)/'`loader.c libast_la-lutmap.lo: lutmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-lutmap.lo -MD -MP -MF $(DEPDIR)/libast_la-lutmap.Tpo -c -o libast_la-lutmap.lo `test -f 'lutmap.c' || echo '$(srcdir)/'`lutmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-lutmap.Tpo $(DEPDIR)/libast_la-lutmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='lutmap.c' object='libast_la-lutmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-lutmap.lo `test -f 'lutmap.c' || echo '$(srcdir)/'`lutmap.c libast_la-mapping.lo: mapping.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-mapping.lo -MD -MP -MF $(DEPDIR)/libast_la-mapping.Tpo -c -o libast_la-mapping.lo `test -f 'mapping.c' || echo '$(srcdir)/'`mapping.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-mapping.Tpo $(DEPDIR)/libast_la-mapping.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='mapping.c' object='libast_la-mapping.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-mapping.lo `test -f 'mapping.c' || echo '$(srcdir)/'`mapping.c libast_la-mathmap.lo: mathmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-mathmap.lo -MD -MP -MF $(DEPDIR)/libast_la-mathmap.Tpo -c -o libast_la-mathmap.lo `test -f 'mathmap.c' || echo '$(srcdir)/'`mathmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-mathmap.Tpo $(DEPDIR)/libast_la-mathmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='mathmap.c' object='libast_la-mathmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-mathmap.lo `test -f 'mathmap.c' || echo '$(srcdir)/'`mathmap.c libast_la-matrixmap.lo: matrixmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-matrixmap.lo -MD -MP -MF $(DEPDIR)/libast_la-matrixmap.Tpo -c -o libast_la-matrixmap.lo `test -f 'matrixmap.c' || echo '$(srcdir)/'`matrixmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-matrixmap.Tpo $(DEPDIR)/libast_la-matrixmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='matrixmap.c' object='libast_la-matrixmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-matrixmap.lo `test -f 'matrixmap.c' || echo '$(srcdir)/'`matrixmap.c libast_la-memory.lo: memory.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-memory.lo -MD -MP -MF $(DEPDIR)/libast_la-memory.Tpo -c -o libast_la-memory.lo `test -f 'memory.c' || echo '$(srcdir)/'`memory.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-memory.Tpo $(DEPDIR)/libast_la-memory.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='memory.c' object='libast_la-memory.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-memory.lo `test -f 'memory.c' || echo '$(srcdir)/'`memory.c libast_la-normmap.lo: normmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-normmap.lo -MD -MP -MF $(DEPDIR)/libast_la-normmap.Tpo -c -o libast_la-normmap.lo `test -f 'normmap.c' || echo '$(srcdir)/'`normmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-normmap.Tpo $(DEPDIR)/libast_la-normmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='normmap.c' object='libast_la-normmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-normmap.lo `test -f 'normmap.c' || echo '$(srcdir)/'`normmap.c libast_la-nullregion.lo: nullregion.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-nullregion.lo -MD -MP -MF $(DEPDIR)/libast_la-nullregion.Tpo -c -o libast_la-nullregion.lo `test -f 'nullregion.c' || echo '$(srcdir)/'`nullregion.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-nullregion.Tpo $(DEPDIR)/libast_la-nullregion.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='nullregion.c' object='libast_la-nullregion.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-nullregion.lo `test -f 'nullregion.c' || echo '$(srcdir)/'`nullregion.c libast_la-object.lo: object.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-object.lo -MD -MP -MF $(DEPDIR)/libast_la-object.Tpo -c -o libast_la-object.lo `test -f 'object.c' || echo '$(srcdir)/'`object.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-object.Tpo $(DEPDIR)/libast_la-object.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='object.c' object='libast_la-object.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-object.lo `test -f 'object.c' || echo '$(srcdir)/'`object.c libast_la-pcdmap.lo: pcdmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-pcdmap.lo -MD -MP -MF $(DEPDIR)/libast_la-pcdmap.Tpo -c -o libast_la-pcdmap.lo `test -f 'pcdmap.c' || echo '$(srcdir)/'`pcdmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-pcdmap.Tpo $(DEPDIR)/libast_la-pcdmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='pcdmap.c' object='libast_la-pcdmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-pcdmap.lo `test -f 'pcdmap.c' || echo '$(srcdir)/'`pcdmap.c libast_la-permmap.lo: permmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-permmap.lo -MD -MP -MF $(DEPDIR)/libast_la-permmap.Tpo -c -o libast_la-permmap.lo `test -f 'permmap.c' || echo '$(srcdir)/'`permmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-permmap.Tpo $(DEPDIR)/libast_la-permmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='permmap.c' object='libast_la-permmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-permmap.lo `test -f 'permmap.c' || echo '$(srcdir)/'`permmap.c libast_la-plot.lo: plot.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-plot.lo -MD -MP -MF $(DEPDIR)/libast_la-plot.Tpo -c -o libast_la-plot.lo `test -f 'plot.c' || echo '$(srcdir)/'`plot.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-plot.Tpo $(DEPDIR)/libast_la-plot.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='plot.c' object='libast_la-plot.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-plot.lo `test -f 'plot.c' || echo '$(srcdir)/'`plot.c libast_la-plot3d.lo: plot3d.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-plot3d.lo -MD -MP -MF $(DEPDIR)/libast_la-plot3d.Tpo -c -o libast_la-plot3d.lo `test -f 'plot3d.c' || echo '$(srcdir)/'`plot3d.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-plot3d.Tpo $(DEPDIR)/libast_la-plot3d.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='plot3d.c' object='libast_la-plot3d.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-plot3d.lo `test -f 'plot3d.c' || echo '$(srcdir)/'`plot3d.c libast_la-pointlist.lo: pointlist.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-pointlist.lo -MD -MP -MF $(DEPDIR)/libast_la-pointlist.Tpo -c -o libast_la-pointlist.lo `test -f 'pointlist.c' || echo '$(srcdir)/'`pointlist.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-pointlist.Tpo $(DEPDIR)/libast_la-pointlist.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='pointlist.c' object='libast_la-pointlist.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-pointlist.lo `test -f 'pointlist.c' || echo '$(srcdir)/'`pointlist.c libast_la-pointset.lo: pointset.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-pointset.lo -MD -MP -MF $(DEPDIR)/libast_la-pointset.Tpo -c -o libast_la-pointset.lo `test -f 'pointset.c' || echo '$(srcdir)/'`pointset.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-pointset.Tpo $(DEPDIR)/libast_la-pointset.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='pointset.c' object='libast_la-pointset.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-pointset.lo `test -f 'pointset.c' || echo '$(srcdir)/'`pointset.c libast_la-polygon.lo: polygon.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-polygon.lo -MD -MP -MF $(DEPDIR)/libast_la-polygon.Tpo -c -o libast_la-polygon.lo `test -f 'polygon.c' || echo '$(srcdir)/'`polygon.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-polygon.Tpo $(DEPDIR)/libast_la-polygon.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='polygon.c' object='libast_la-polygon.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-polygon.lo `test -f 'polygon.c' || echo '$(srcdir)/'`polygon.c libast_la-polymap.lo: polymap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-polymap.lo -MD -MP -MF $(DEPDIR)/libast_la-polymap.Tpo -c -o libast_la-polymap.lo `test -f 'polymap.c' || echo '$(srcdir)/'`polymap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-polymap.Tpo $(DEPDIR)/libast_la-polymap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='polymap.c' object='libast_la-polymap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-polymap.lo `test -f 'polymap.c' || echo '$(srcdir)/'`polymap.c libast_la-prism.lo: prism.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-prism.lo -MD -MP -MF $(DEPDIR)/libast_la-prism.Tpo -c -o libast_la-prism.lo `test -f 'prism.c' || echo '$(srcdir)/'`prism.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-prism.Tpo $(DEPDIR)/libast_la-prism.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='prism.c' object='libast_la-prism.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-prism.lo `test -f 'prism.c' || echo '$(srcdir)/'`prism.c libast_la-ratemap.lo: ratemap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ratemap.lo -MD -MP -MF $(DEPDIR)/libast_la-ratemap.Tpo -c -o libast_la-ratemap.lo `test -f 'ratemap.c' || echo '$(srcdir)/'`ratemap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ratemap.Tpo $(DEPDIR)/libast_la-ratemap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ratemap.c' object='libast_la-ratemap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ratemap.lo `test -f 'ratemap.c' || echo '$(srcdir)/'`ratemap.c libast_la-region.lo: region.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-region.lo -MD -MP -MF $(DEPDIR)/libast_la-region.Tpo -c -o libast_la-region.lo `test -f 'region.c' || echo '$(srcdir)/'`region.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-region.Tpo $(DEPDIR)/libast_la-region.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='region.c' object='libast_la-region.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-region.lo `test -f 'region.c' || echo '$(srcdir)/'`region.c libast_la-selectormap.lo: selectormap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-selectormap.lo -MD -MP -MF $(DEPDIR)/libast_la-selectormap.Tpo -c -o libast_la-selectormap.lo `test -f 'selectormap.c' || echo '$(srcdir)/'`selectormap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-selectormap.Tpo $(DEPDIR)/libast_la-selectormap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='selectormap.c' object='libast_la-selectormap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-selectormap.lo `test -f 'selectormap.c' || echo '$(srcdir)/'`selectormap.c libast_la-shiftmap.lo: shiftmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-shiftmap.lo -MD -MP -MF $(DEPDIR)/libast_la-shiftmap.Tpo -c -o libast_la-shiftmap.lo `test -f 'shiftmap.c' || echo '$(srcdir)/'`shiftmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-shiftmap.Tpo $(DEPDIR)/libast_la-shiftmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='shiftmap.c' object='libast_la-shiftmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-shiftmap.lo `test -f 'shiftmap.c' || echo '$(srcdir)/'`shiftmap.c libast_la-skyaxis.lo: skyaxis.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-skyaxis.lo -MD -MP -MF $(DEPDIR)/libast_la-skyaxis.Tpo -c -o libast_la-skyaxis.lo `test -f 'skyaxis.c' || echo '$(srcdir)/'`skyaxis.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-skyaxis.Tpo $(DEPDIR)/libast_la-skyaxis.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='skyaxis.c' object='libast_la-skyaxis.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-skyaxis.lo `test -f 'skyaxis.c' || echo '$(srcdir)/'`skyaxis.c libast_la-skyframe.lo: skyframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-skyframe.lo -MD -MP -MF $(DEPDIR)/libast_la-skyframe.Tpo -c -o libast_la-skyframe.lo `test -f 'skyframe.c' || echo '$(srcdir)/'`skyframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-skyframe.Tpo $(DEPDIR)/libast_la-skyframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='skyframe.c' object='libast_la-skyframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-skyframe.lo `test -f 'skyframe.c' || echo '$(srcdir)/'`skyframe.c libast_la-slamap.lo: slamap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-slamap.lo -MD -MP -MF $(DEPDIR)/libast_la-slamap.Tpo -c -o libast_la-slamap.lo `test -f 'slamap.c' || echo '$(srcdir)/'`slamap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-slamap.Tpo $(DEPDIR)/libast_la-slamap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='slamap.c' object='libast_la-slamap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-slamap.lo `test -f 'slamap.c' || echo '$(srcdir)/'`slamap.c libast_la-specfluxframe.lo: specfluxframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-specfluxframe.lo -MD -MP -MF $(DEPDIR)/libast_la-specfluxframe.Tpo -c -o libast_la-specfluxframe.lo `test -f 'specfluxframe.c' || echo '$(srcdir)/'`specfluxframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-specfluxframe.Tpo $(DEPDIR)/libast_la-specfluxframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='specfluxframe.c' object='libast_la-specfluxframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-specfluxframe.lo `test -f 'specfluxframe.c' || echo '$(srcdir)/'`specfluxframe.c libast_la-specframe.lo: specframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-specframe.lo -MD -MP -MF $(DEPDIR)/libast_la-specframe.Tpo -c -o libast_la-specframe.lo `test -f 'specframe.c' || echo '$(srcdir)/'`specframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-specframe.Tpo $(DEPDIR)/libast_la-specframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='specframe.c' object='libast_la-specframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-specframe.lo `test -f 'specframe.c' || echo '$(srcdir)/'`specframe.c libast_la-specmap.lo: specmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-specmap.lo -MD -MP -MF $(DEPDIR)/libast_la-specmap.Tpo -c -o libast_la-specmap.lo `test -f 'specmap.c' || echo '$(srcdir)/'`specmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-specmap.Tpo $(DEPDIR)/libast_la-specmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='specmap.c' object='libast_la-specmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-specmap.lo `test -f 'specmap.c' || echo '$(srcdir)/'`specmap.c libast_la-sphmap.lo: sphmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-sphmap.lo -MD -MP -MF $(DEPDIR)/libast_la-sphmap.Tpo -c -o libast_la-sphmap.lo `test -f 'sphmap.c' || echo '$(srcdir)/'`sphmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-sphmap.Tpo $(DEPDIR)/libast_la-sphmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='sphmap.c' object='libast_la-sphmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-sphmap.lo `test -f 'sphmap.c' || echo '$(srcdir)/'`sphmap.c libast_la-stc.lo: stc.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stc.lo -MD -MP -MF $(DEPDIR)/libast_la-stc.Tpo -c -o libast_la-stc.lo `test -f 'stc.c' || echo '$(srcdir)/'`stc.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stc.Tpo $(DEPDIR)/libast_la-stc.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stc.c' object='libast_la-stc.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stc.lo `test -f 'stc.c' || echo '$(srcdir)/'`stc.c libast_la-stccatalogentrylocation.lo: stccatalogentrylocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stccatalogentrylocation.lo -MD -MP -MF $(DEPDIR)/libast_la-stccatalogentrylocation.Tpo -c -o libast_la-stccatalogentrylocation.lo `test -f 'stccatalogentrylocation.c' || echo '$(srcdir)/'`stccatalogentrylocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stccatalogentrylocation.Tpo $(DEPDIR)/libast_la-stccatalogentrylocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stccatalogentrylocation.c' object='libast_la-stccatalogentrylocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stccatalogentrylocation.lo `test -f 'stccatalogentrylocation.c' || echo '$(srcdir)/'`stccatalogentrylocation.c libast_la-stcobsdatalocation.lo: stcobsdatalocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stcobsdatalocation.lo -MD -MP -MF $(DEPDIR)/libast_la-stcobsdatalocation.Tpo -c -o libast_la-stcobsdatalocation.lo `test -f 'stcobsdatalocation.c' || echo '$(srcdir)/'`stcobsdatalocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stcobsdatalocation.Tpo $(DEPDIR)/libast_la-stcobsdatalocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stcobsdatalocation.c' object='libast_la-stcobsdatalocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stcobsdatalocation.lo `test -f 'stcobsdatalocation.c' || echo '$(srcdir)/'`stcobsdatalocation.c libast_la-stcresourceprofile.lo: stcresourceprofile.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stcresourceprofile.lo -MD -MP -MF $(DEPDIR)/libast_la-stcresourceprofile.Tpo -c -o libast_la-stcresourceprofile.lo `test -f 'stcresourceprofile.c' || echo '$(srcdir)/'`stcresourceprofile.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stcresourceprofile.Tpo $(DEPDIR)/libast_la-stcresourceprofile.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stcresourceprofile.c' object='libast_la-stcresourceprofile.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stcresourceprofile.lo `test -f 'stcresourceprofile.c' || echo '$(srcdir)/'`stcresourceprofile.c libast_la-stcschan.lo: stcschan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stcschan.lo -MD -MP -MF $(DEPDIR)/libast_la-stcschan.Tpo -c -o libast_la-stcschan.lo `test -f 'stcschan.c' || echo '$(srcdir)/'`stcschan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stcschan.Tpo $(DEPDIR)/libast_la-stcschan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stcschan.c' object='libast_la-stcschan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stcschan.lo `test -f 'stcschan.c' || echo '$(srcdir)/'`stcschan.c libast_la-stcsearchlocation.lo: stcsearchlocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-stcsearchlocation.lo -MD -MP -MF $(DEPDIR)/libast_la-stcsearchlocation.Tpo -c -o libast_la-stcsearchlocation.lo `test -f 'stcsearchlocation.c' || echo '$(srcdir)/'`stcsearchlocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-stcsearchlocation.Tpo $(DEPDIR)/libast_la-stcsearchlocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='stcsearchlocation.c' object='libast_la-stcsearchlocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-stcsearchlocation.lo `test -f 'stcsearchlocation.c' || echo '$(srcdir)/'`stcsearchlocation.c libast_la-switchmap.lo: switchmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-switchmap.lo -MD -MP -MF $(DEPDIR)/libast_la-switchmap.Tpo -c -o libast_la-switchmap.lo `test -f 'switchmap.c' || echo '$(srcdir)/'`switchmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-switchmap.Tpo $(DEPDIR)/libast_la-switchmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='switchmap.c' object='libast_la-switchmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-switchmap.lo `test -f 'switchmap.c' || echo '$(srcdir)/'`switchmap.c libast_la-table.lo: table.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-table.lo -MD -MP -MF $(DEPDIR)/libast_la-table.Tpo -c -o libast_la-table.lo `test -f 'table.c' || echo '$(srcdir)/'`table.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-table.Tpo $(DEPDIR)/libast_la-table.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='table.c' object='libast_la-table.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-table.lo `test -f 'table.c' || echo '$(srcdir)/'`table.c libast_la-timeframe.lo: timeframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-timeframe.lo -MD -MP -MF $(DEPDIR)/libast_la-timeframe.Tpo -c -o libast_la-timeframe.lo `test -f 'timeframe.c' || echo '$(srcdir)/'`timeframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-timeframe.Tpo $(DEPDIR)/libast_la-timeframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='timeframe.c' object='libast_la-timeframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-timeframe.lo `test -f 'timeframe.c' || echo '$(srcdir)/'`timeframe.c libast_la-timemap.lo: timemap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-timemap.lo -MD -MP -MF $(DEPDIR)/libast_la-timemap.Tpo -c -o libast_la-timemap.lo `test -f 'timemap.c' || echo '$(srcdir)/'`timemap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-timemap.Tpo $(DEPDIR)/libast_la-timemap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='timemap.c' object='libast_la-timemap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-timemap.lo `test -f 'timemap.c' || echo '$(srcdir)/'`timemap.c libast_la-tranmap.lo: tranmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-tranmap.lo -MD -MP -MF $(DEPDIR)/libast_la-tranmap.Tpo -c -o libast_la-tranmap.lo `test -f 'tranmap.c' || echo '$(srcdir)/'`tranmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-tranmap.Tpo $(DEPDIR)/libast_la-tranmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='tranmap.c' object='libast_la-tranmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-tranmap.lo `test -f 'tranmap.c' || echo '$(srcdir)/'`tranmap.c libast_la-unit.lo: unit.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-unit.lo -MD -MP -MF $(DEPDIR)/libast_la-unit.Tpo -c -o libast_la-unit.lo `test -f 'unit.c' || echo '$(srcdir)/'`unit.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-unit.Tpo $(DEPDIR)/libast_la-unit.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='unit.c' object='libast_la-unit.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-unit.lo `test -f 'unit.c' || echo '$(srcdir)/'`unit.c libast_la-unitmap.lo: unitmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-unitmap.lo -MD -MP -MF $(DEPDIR)/libast_la-unitmap.Tpo -c -o libast_la-unitmap.lo `test -f 'unitmap.c' || echo '$(srcdir)/'`unitmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-unitmap.Tpo $(DEPDIR)/libast_la-unitmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='unitmap.c' object='libast_la-unitmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-unitmap.lo `test -f 'unitmap.c' || echo '$(srcdir)/'`unitmap.c libast_la-unitnormmap.lo: unitnormmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-unitnormmap.lo -MD -MP -MF $(DEPDIR)/libast_la-unitnormmap.Tpo -c -o libast_la-unitnormmap.lo `test -f 'unitnormmap.c' || echo '$(srcdir)/'`unitnormmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-unitnormmap.Tpo $(DEPDIR)/libast_la-unitnormmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='unitnormmap.c' object='libast_la-unitnormmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-unitnormmap.lo `test -f 'unitnormmap.c' || echo '$(srcdir)/'`unitnormmap.c libast_la-wcsmap.lo: wcsmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-wcsmap.lo -MD -MP -MF $(DEPDIR)/libast_la-wcsmap.Tpo -c -o libast_la-wcsmap.lo `test -f 'wcsmap.c' || echo '$(srcdir)/'`wcsmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-wcsmap.Tpo $(DEPDIR)/libast_la-wcsmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='wcsmap.c' object='libast_la-wcsmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-wcsmap.lo `test -f 'wcsmap.c' || echo '$(srcdir)/'`wcsmap.c libast_la-winmap.lo: winmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-winmap.lo -MD -MP -MF $(DEPDIR)/libast_la-winmap.Tpo -c -o libast_la-winmap.lo `test -f 'winmap.c' || echo '$(srcdir)/'`winmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-winmap.Tpo $(DEPDIR)/libast_la-winmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='winmap.c' object='libast_la-winmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-winmap.lo `test -f 'winmap.c' || echo '$(srcdir)/'`winmap.c libast_la-xml.lo: xml.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-xml.lo -MD -MP -MF $(DEPDIR)/libast_la-xml.Tpo -c -o libast_la-xml.lo `test -f 'xml.c' || echo '$(srcdir)/'`xml.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-xml.Tpo $(DEPDIR)/libast_la-xml.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='xml.c' object='libast_la-xml.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-xml.lo `test -f 'xml.c' || echo '$(srcdir)/'`xml.c libast_la-xmlchan.lo: xmlchan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-xmlchan.lo -MD -MP -MF $(DEPDIR)/libast_la-xmlchan.Tpo -c -o libast_la-xmlchan.lo `test -f 'xmlchan.c' || echo '$(srcdir)/'`xmlchan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-xmlchan.Tpo $(DEPDIR)/libast_la-xmlchan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='xmlchan.c' object='libast_la-xmlchan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-xmlchan.lo `test -f 'xmlchan.c' || echo '$(srcdir)/'`xmlchan.c libast_la-zoommap.lo: zoommap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-zoommap.lo -MD -MP -MF $(DEPDIR)/libast_la-zoommap.Tpo -c -o libast_la-zoommap.lo `test -f 'zoommap.c' || echo '$(srcdir)/'`zoommap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-zoommap.Tpo $(DEPDIR)/libast_la-zoommap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='zoommap.c' object='libast_la-zoommap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-zoommap.lo `test -f 'zoommap.c' || echo '$(srcdir)/'`zoommap.c libast_la-c2f77.lo: c2f77.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-c2f77.lo -MD -MP -MF $(DEPDIR)/libast_la-c2f77.Tpo -c -o libast_la-c2f77.lo `test -f 'c2f77.c' || echo '$(srcdir)/'`c2f77.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-c2f77.Tpo $(DEPDIR)/libast_la-c2f77.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='c2f77.c' object='libast_la-c2f77.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-c2f77.lo `test -f 'c2f77.c' || echo '$(srcdir)/'`c2f77.c libast_la-fbox.lo: fbox.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fbox.lo -MD -MP -MF $(DEPDIR)/libast_la-fbox.Tpo -c -o libast_la-fbox.lo `test -f 'fbox.c' || echo '$(srcdir)/'`fbox.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fbox.Tpo $(DEPDIR)/libast_la-fbox.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fbox.c' object='libast_la-fbox.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fbox.lo `test -f 'fbox.c' || echo '$(srcdir)/'`fbox.c libast_la-fchannel.lo: fchannel.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fchannel.lo -MD -MP -MF $(DEPDIR)/libast_la-fchannel.Tpo -c -o libast_la-fchannel.lo `test -f 'fchannel.c' || echo '$(srcdir)/'`fchannel.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fchannel.Tpo $(DEPDIR)/libast_la-fchannel.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fchannel.c' object='libast_la-fchannel.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fchannel.lo `test -f 'fchannel.c' || echo '$(srcdir)/'`fchannel.c libast_la-fcircle.lo: fcircle.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fcircle.lo -MD -MP -MF $(DEPDIR)/libast_la-fcircle.Tpo -c -o libast_la-fcircle.lo `test -f 'fcircle.c' || echo '$(srcdir)/'`fcircle.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fcircle.Tpo $(DEPDIR)/libast_la-fcircle.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fcircle.c' object='libast_la-fcircle.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fcircle.lo `test -f 'fcircle.c' || echo '$(srcdir)/'`fcircle.c libast_la-fcmpframe.lo: fcmpframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fcmpframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fcmpframe.Tpo -c -o libast_la-fcmpframe.lo `test -f 'fcmpframe.c' || echo '$(srcdir)/'`fcmpframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fcmpframe.Tpo $(DEPDIR)/libast_la-fcmpframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fcmpframe.c' object='libast_la-fcmpframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fcmpframe.lo `test -f 'fcmpframe.c' || echo '$(srcdir)/'`fcmpframe.c libast_la-fcmpmap.lo: fcmpmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fcmpmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fcmpmap.Tpo -c -o libast_la-fcmpmap.lo `test -f 'fcmpmap.c' || echo '$(srcdir)/'`fcmpmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fcmpmap.Tpo $(DEPDIR)/libast_la-fcmpmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fcmpmap.c' object='libast_la-fcmpmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fcmpmap.lo `test -f 'fcmpmap.c' || echo '$(srcdir)/'`fcmpmap.c libast_la-fcmpregion.lo: fcmpregion.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fcmpregion.lo -MD -MP -MF $(DEPDIR)/libast_la-fcmpregion.Tpo -c -o libast_la-fcmpregion.lo `test -f 'fcmpregion.c' || echo '$(srcdir)/'`fcmpregion.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fcmpregion.Tpo $(DEPDIR)/libast_la-fcmpregion.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fcmpregion.c' object='libast_la-fcmpregion.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fcmpregion.lo `test -f 'fcmpregion.c' || echo '$(srcdir)/'`fcmpregion.c libast_la-fdsbspecframe.lo: fdsbspecframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fdsbspecframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fdsbspecframe.Tpo -c -o libast_la-fdsbspecframe.lo `test -f 'fdsbspecframe.c' || echo '$(srcdir)/'`fdsbspecframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fdsbspecframe.Tpo $(DEPDIR)/libast_la-fdsbspecframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fdsbspecframe.c' object='libast_la-fdsbspecframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fdsbspecframe.lo `test -f 'fdsbspecframe.c' || echo '$(srcdir)/'`fdsbspecframe.c libast_la-fdssmap.lo: fdssmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fdssmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fdssmap.Tpo -c -o libast_la-fdssmap.lo `test -f 'fdssmap.c' || echo '$(srcdir)/'`fdssmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fdssmap.Tpo $(DEPDIR)/libast_la-fdssmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fdssmap.c' object='libast_la-fdssmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fdssmap.lo `test -f 'fdssmap.c' || echo '$(srcdir)/'`fdssmap.c libast_la-fellipse.lo: fellipse.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fellipse.lo -MD -MP -MF $(DEPDIR)/libast_la-fellipse.Tpo -c -o libast_la-fellipse.lo `test -f 'fellipse.c' || echo '$(srcdir)/'`fellipse.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fellipse.Tpo $(DEPDIR)/libast_la-fellipse.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fellipse.c' object='libast_la-fellipse.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fellipse.lo `test -f 'fellipse.c' || echo '$(srcdir)/'`fellipse.c libast_la-ferror.lo: ferror.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ferror.lo -MD -MP -MF $(DEPDIR)/libast_la-ferror.Tpo -c -o libast_la-ferror.lo `test -f 'ferror.c' || echo '$(srcdir)/'`ferror.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ferror.Tpo $(DEPDIR)/libast_la-ferror.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ferror.c' object='libast_la-ferror.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ferror.lo `test -f 'ferror.c' || echo '$(srcdir)/'`ferror.c libast_la-ffitschan.lo: ffitschan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ffitschan.lo -MD -MP -MF $(DEPDIR)/libast_la-ffitschan.Tpo -c -o libast_la-ffitschan.lo `test -f 'ffitschan.c' || echo '$(srcdir)/'`ffitschan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ffitschan.Tpo $(DEPDIR)/libast_la-ffitschan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ffitschan.c' object='libast_la-ffitschan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ffitschan.lo `test -f 'ffitschan.c' || echo '$(srcdir)/'`ffitschan.c libast_la-ffitstable.lo: ffitstable.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ffitstable.lo -MD -MP -MF $(DEPDIR)/libast_la-ffitstable.Tpo -c -o libast_la-ffitstable.lo `test -f 'ffitstable.c' || echo '$(srcdir)/'`ffitstable.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ffitstable.Tpo $(DEPDIR)/libast_la-ffitstable.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ffitstable.c' object='libast_la-ffitstable.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ffitstable.lo `test -f 'ffitstable.c' || echo '$(srcdir)/'`ffitstable.c libast_la-ffluxframe.lo: ffluxframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ffluxframe.lo -MD -MP -MF $(DEPDIR)/libast_la-ffluxframe.Tpo -c -o libast_la-ffluxframe.lo `test -f 'ffluxframe.c' || echo '$(srcdir)/'`ffluxframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ffluxframe.Tpo $(DEPDIR)/libast_la-ffluxframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ffluxframe.c' object='libast_la-ffluxframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ffluxframe.lo `test -f 'ffluxframe.c' || echo '$(srcdir)/'`ffluxframe.c libast_la-fframe.lo: fframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fframe.Tpo -c -o libast_la-fframe.lo `test -f 'fframe.c' || echo '$(srcdir)/'`fframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fframe.Tpo $(DEPDIR)/libast_la-fframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fframe.c' object='libast_la-fframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fframe.lo `test -f 'fframe.c' || echo '$(srcdir)/'`fframe.c libast_la-fframeset.lo: fframeset.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fframeset.lo -MD -MP -MF $(DEPDIR)/libast_la-fframeset.Tpo -c -o libast_la-fframeset.lo `test -f 'fframeset.c' || echo '$(srcdir)/'`fframeset.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fframeset.Tpo $(DEPDIR)/libast_la-fframeset.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fframeset.c' object='libast_la-fframeset.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fframeset.lo `test -f 'fframeset.c' || echo '$(srcdir)/'`fframeset.c libast_la-fgrismmap.lo: fgrismmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fgrismmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fgrismmap.Tpo -c -o libast_la-fgrismmap.lo `test -f 'fgrismmap.c' || echo '$(srcdir)/'`fgrismmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fgrismmap.Tpo $(DEPDIR)/libast_la-fgrismmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fgrismmap.c' object='libast_la-fgrismmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fgrismmap.lo `test -f 'fgrismmap.c' || echo '$(srcdir)/'`fgrismmap.c libast_la-finterval.lo: finterval.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-finterval.lo -MD -MP -MF $(DEPDIR)/libast_la-finterval.Tpo -c -o libast_la-finterval.lo `test -f 'finterval.c' || echo '$(srcdir)/'`finterval.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-finterval.Tpo $(DEPDIR)/libast_la-finterval.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='finterval.c' object='libast_la-finterval.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-finterval.lo `test -f 'finterval.c' || echo '$(srcdir)/'`finterval.c libast_la-fintramap.lo: fintramap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fintramap.lo -MD -MP -MF $(DEPDIR)/libast_la-fintramap.Tpo -c -o libast_la-fintramap.lo `test -f 'fintramap.c' || echo '$(srcdir)/'`fintramap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fintramap.Tpo $(DEPDIR)/libast_la-fintramap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fintramap.c' object='libast_la-fintramap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fintramap.lo `test -f 'fintramap.c' || echo '$(srcdir)/'`fintramap.c libast_la-fkeymap.lo: fkeymap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fkeymap.lo -MD -MP -MF $(DEPDIR)/libast_la-fkeymap.Tpo -c -o libast_la-fkeymap.lo `test -f 'fkeymap.c' || echo '$(srcdir)/'`fkeymap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fkeymap.Tpo $(DEPDIR)/libast_la-fkeymap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fkeymap.c' object='libast_la-fkeymap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fkeymap.lo `test -f 'fkeymap.c' || echo '$(srcdir)/'`fkeymap.c libast_la-flutmap.lo: flutmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-flutmap.lo -MD -MP -MF $(DEPDIR)/libast_la-flutmap.Tpo -c -o libast_la-flutmap.lo `test -f 'flutmap.c' || echo '$(srcdir)/'`flutmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-flutmap.Tpo $(DEPDIR)/libast_la-flutmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='flutmap.c' object='libast_la-flutmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-flutmap.lo `test -f 'flutmap.c' || echo '$(srcdir)/'`flutmap.c libast_la-fmapping.lo: fmapping.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fmapping.lo -MD -MP -MF $(DEPDIR)/libast_la-fmapping.Tpo -c -o libast_la-fmapping.lo `test -f 'fmapping.c' || echo '$(srcdir)/'`fmapping.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fmapping.Tpo $(DEPDIR)/libast_la-fmapping.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fmapping.c' object='libast_la-fmapping.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fmapping.lo `test -f 'fmapping.c' || echo '$(srcdir)/'`fmapping.c libast_la-fmathmap.lo: fmathmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fmathmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fmathmap.Tpo -c -o libast_la-fmathmap.lo `test -f 'fmathmap.c' || echo '$(srcdir)/'`fmathmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fmathmap.Tpo $(DEPDIR)/libast_la-fmathmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fmathmap.c' object='libast_la-fmathmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fmathmap.lo `test -f 'fmathmap.c' || echo '$(srcdir)/'`fmathmap.c libast_la-fmatrixmap.lo: fmatrixmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fmatrixmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fmatrixmap.Tpo -c -o libast_la-fmatrixmap.lo `test -f 'fmatrixmap.c' || echo '$(srcdir)/'`fmatrixmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fmatrixmap.Tpo $(DEPDIR)/libast_la-fmatrixmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fmatrixmap.c' object='libast_la-fmatrixmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fmatrixmap.lo `test -f 'fmatrixmap.c' || echo '$(srcdir)/'`fmatrixmap.c libast_la-fnormmap.lo: fnormmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fnormmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fnormmap.Tpo -c -o libast_la-fnormmap.lo `test -f 'fnormmap.c' || echo '$(srcdir)/'`fnormmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fnormmap.Tpo $(DEPDIR)/libast_la-fnormmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fnormmap.c' object='libast_la-fnormmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fnormmap.lo `test -f 'fnormmap.c' || echo '$(srcdir)/'`fnormmap.c libast_la-fnullregion.lo: fnullregion.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fnullregion.lo -MD -MP -MF $(DEPDIR)/libast_la-fnullregion.Tpo -c -o libast_la-fnullregion.lo `test -f 'fnullregion.c' || echo '$(srcdir)/'`fnullregion.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fnullregion.Tpo $(DEPDIR)/libast_la-fnullregion.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fnullregion.c' object='libast_la-fnullregion.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fnullregion.lo `test -f 'fnullregion.c' || echo '$(srcdir)/'`fnullregion.c libast_la-fobject.lo: fobject.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fobject.lo -MD -MP -MF $(DEPDIR)/libast_la-fobject.Tpo -c -o libast_la-fobject.lo `test -f 'fobject.c' || echo '$(srcdir)/'`fobject.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fobject.Tpo $(DEPDIR)/libast_la-fobject.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fobject.c' object='libast_la-fobject.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fobject.lo `test -f 'fobject.c' || echo '$(srcdir)/'`fobject.c libast_la-fpcdmap.lo: fpcdmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fpcdmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fpcdmap.Tpo -c -o libast_la-fpcdmap.lo `test -f 'fpcdmap.c' || echo '$(srcdir)/'`fpcdmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fpcdmap.Tpo $(DEPDIR)/libast_la-fpcdmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fpcdmap.c' object='libast_la-fpcdmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fpcdmap.lo `test -f 'fpcdmap.c' || echo '$(srcdir)/'`fpcdmap.c libast_la-fpermmap.lo: fpermmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fpermmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fpermmap.Tpo -c -o libast_la-fpermmap.lo `test -f 'fpermmap.c' || echo '$(srcdir)/'`fpermmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fpermmap.Tpo $(DEPDIR)/libast_la-fpermmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fpermmap.c' object='libast_la-fpermmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fpermmap.lo `test -f 'fpermmap.c' || echo '$(srcdir)/'`fpermmap.c libast_la-fplot.lo: fplot.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fplot.lo -MD -MP -MF $(DEPDIR)/libast_la-fplot.Tpo -c -o libast_la-fplot.lo `test -f 'fplot.c' || echo '$(srcdir)/'`fplot.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fplot.Tpo $(DEPDIR)/libast_la-fplot.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fplot.c' object='libast_la-fplot.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fplot.lo `test -f 'fplot.c' || echo '$(srcdir)/'`fplot.c libast_la-fplot3d.lo: fplot3d.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fplot3d.lo -MD -MP -MF $(DEPDIR)/libast_la-fplot3d.Tpo -c -o libast_la-fplot3d.lo `test -f 'fplot3d.c' || echo '$(srcdir)/'`fplot3d.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fplot3d.Tpo $(DEPDIR)/libast_la-fplot3d.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fplot3d.c' object='libast_la-fplot3d.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fplot3d.lo `test -f 'fplot3d.c' || echo '$(srcdir)/'`fplot3d.c libast_la-fpointlist.lo: fpointlist.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fpointlist.lo -MD -MP -MF $(DEPDIR)/libast_la-fpointlist.Tpo -c -o libast_la-fpointlist.lo `test -f 'fpointlist.c' || echo '$(srcdir)/'`fpointlist.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fpointlist.Tpo $(DEPDIR)/libast_la-fpointlist.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fpointlist.c' object='libast_la-fpointlist.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fpointlist.lo `test -f 'fpointlist.c' || echo '$(srcdir)/'`fpointlist.c libast_la-fpolygon.lo: fpolygon.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fpolygon.lo -MD -MP -MF $(DEPDIR)/libast_la-fpolygon.Tpo -c -o libast_la-fpolygon.lo `test -f 'fpolygon.c' || echo '$(srcdir)/'`fpolygon.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fpolygon.Tpo $(DEPDIR)/libast_la-fpolygon.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fpolygon.c' object='libast_la-fpolygon.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fpolygon.lo `test -f 'fpolygon.c' || echo '$(srcdir)/'`fpolygon.c libast_la-fpolymap.lo: fpolymap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fpolymap.lo -MD -MP -MF $(DEPDIR)/libast_la-fpolymap.Tpo -c -o libast_la-fpolymap.lo `test -f 'fpolymap.c' || echo '$(srcdir)/'`fpolymap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fpolymap.Tpo $(DEPDIR)/libast_la-fpolymap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fpolymap.c' object='libast_la-fpolymap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fpolymap.lo `test -f 'fpolymap.c' || echo '$(srcdir)/'`fpolymap.c libast_la-fprism.lo: fprism.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fprism.lo -MD -MP -MF $(DEPDIR)/libast_la-fprism.Tpo -c -o libast_la-fprism.lo `test -f 'fprism.c' || echo '$(srcdir)/'`fprism.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fprism.Tpo $(DEPDIR)/libast_la-fprism.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fprism.c' object='libast_la-fprism.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fprism.lo `test -f 'fprism.c' || echo '$(srcdir)/'`fprism.c libast_la-fratemap.lo: fratemap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fratemap.lo -MD -MP -MF $(DEPDIR)/libast_la-fratemap.Tpo -c -o libast_la-fratemap.lo `test -f 'fratemap.c' || echo '$(srcdir)/'`fratemap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fratemap.Tpo $(DEPDIR)/libast_la-fratemap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fratemap.c' object='libast_la-fratemap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fratemap.lo `test -f 'fratemap.c' || echo '$(srcdir)/'`fratemap.c libast_la-fregion.lo: fregion.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fregion.lo -MD -MP -MF $(DEPDIR)/libast_la-fregion.Tpo -c -o libast_la-fregion.lo `test -f 'fregion.c' || echo '$(srcdir)/'`fregion.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fregion.Tpo $(DEPDIR)/libast_la-fregion.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fregion.c' object='libast_la-fregion.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fregion.lo `test -f 'fregion.c' || echo '$(srcdir)/'`fregion.c libast_la-fselectormap.lo: fselectormap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fselectormap.lo -MD -MP -MF $(DEPDIR)/libast_la-fselectormap.Tpo -c -o libast_la-fselectormap.lo `test -f 'fselectormap.c' || echo '$(srcdir)/'`fselectormap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fselectormap.Tpo $(DEPDIR)/libast_la-fselectormap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fselectormap.c' object='libast_la-fselectormap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fselectormap.lo `test -f 'fselectormap.c' || echo '$(srcdir)/'`fselectormap.c libast_la-fshiftmap.lo: fshiftmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fshiftmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fshiftmap.Tpo -c -o libast_la-fshiftmap.lo `test -f 'fshiftmap.c' || echo '$(srcdir)/'`fshiftmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fshiftmap.Tpo $(DEPDIR)/libast_la-fshiftmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fshiftmap.c' object='libast_la-fshiftmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fshiftmap.lo `test -f 'fshiftmap.c' || echo '$(srcdir)/'`fshiftmap.c libast_la-fskyframe.lo: fskyframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fskyframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fskyframe.Tpo -c -o libast_la-fskyframe.lo `test -f 'fskyframe.c' || echo '$(srcdir)/'`fskyframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fskyframe.Tpo $(DEPDIR)/libast_la-fskyframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fskyframe.c' object='libast_la-fskyframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fskyframe.lo `test -f 'fskyframe.c' || echo '$(srcdir)/'`fskyframe.c libast_la-fslamap.lo: fslamap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fslamap.lo -MD -MP -MF $(DEPDIR)/libast_la-fslamap.Tpo -c -o libast_la-fslamap.lo `test -f 'fslamap.c' || echo '$(srcdir)/'`fslamap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fslamap.Tpo $(DEPDIR)/libast_la-fslamap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fslamap.c' object='libast_la-fslamap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fslamap.lo `test -f 'fslamap.c' || echo '$(srcdir)/'`fslamap.c libast_la-fspecfluxframe.lo: fspecfluxframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fspecfluxframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fspecfluxframe.Tpo -c -o libast_la-fspecfluxframe.lo `test -f 'fspecfluxframe.c' || echo '$(srcdir)/'`fspecfluxframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fspecfluxframe.Tpo $(DEPDIR)/libast_la-fspecfluxframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fspecfluxframe.c' object='libast_la-fspecfluxframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fspecfluxframe.lo `test -f 'fspecfluxframe.c' || echo '$(srcdir)/'`fspecfluxframe.c libast_la-fspecframe.lo: fspecframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fspecframe.lo -MD -MP -MF $(DEPDIR)/libast_la-fspecframe.Tpo -c -o libast_la-fspecframe.lo `test -f 'fspecframe.c' || echo '$(srcdir)/'`fspecframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fspecframe.Tpo $(DEPDIR)/libast_la-fspecframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fspecframe.c' object='libast_la-fspecframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fspecframe.lo `test -f 'fspecframe.c' || echo '$(srcdir)/'`fspecframe.c libast_la-fspecmap.lo: fspecmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fspecmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fspecmap.Tpo -c -o libast_la-fspecmap.lo `test -f 'fspecmap.c' || echo '$(srcdir)/'`fspecmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fspecmap.Tpo $(DEPDIR)/libast_la-fspecmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fspecmap.c' object='libast_la-fspecmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fspecmap.lo `test -f 'fspecmap.c' || echo '$(srcdir)/'`fspecmap.c libast_la-fsphmap.lo: fsphmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fsphmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fsphmap.Tpo -c -o libast_la-fsphmap.lo `test -f 'fsphmap.c' || echo '$(srcdir)/'`fsphmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fsphmap.Tpo $(DEPDIR)/libast_la-fsphmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fsphmap.c' object='libast_la-fsphmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fsphmap.lo `test -f 'fsphmap.c' || echo '$(srcdir)/'`fsphmap.c libast_la-fstc.lo: fstc.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstc.lo -MD -MP -MF $(DEPDIR)/libast_la-fstc.Tpo -c -o libast_la-fstc.lo `test -f 'fstc.c' || echo '$(srcdir)/'`fstc.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstc.Tpo $(DEPDIR)/libast_la-fstc.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstc.c' object='libast_la-fstc.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstc.lo `test -f 'fstc.c' || echo '$(srcdir)/'`fstc.c libast_la-fstccatalogentrylocation.lo: fstccatalogentrylocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstccatalogentrylocation.lo -MD -MP -MF $(DEPDIR)/libast_la-fstccatalogentrylocation.Tpo -c -o libast_la-fstccatalogentrylocation.lo `test -f 'fstccatalogentrylocation.c' || echo '$(srcdir)/'`fstccatalogentrylocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstccatalogentrylocation.Tpo $(DEPDIR)/libast_la-fstccatalogentrylocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstccatalogentrylocation.c' object='libast_la-fstccatalogentrylocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstccatalogentrylocation.lo `test -f 'fstccatalogentrylocation.c' || echo '$(srcdir)/'`fstccatalogentrylocation.c libast_la-fstcobsdatalocation.lo: fstcobsdatalocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstcobsdatalocation.lo -MD -MP -MF $(DEPDIR)/libast_la-fstcobsdatalocation.Tpo -c -o libast_la-fstcobsdatalocation.lo `test -f 'fstcobsdatalocation.c' || echo '$(srcdir)/'`fstcobsdatalocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstcobsdatalocation.Tpo $(DEPDIR)/libast_la-fstcobsdatalocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstcobsdatalocation.c' object='libast_la-fstcobsdatalocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstcobsdatalocation.lo `test -f 'fstcobsdatalocation.c' || echo '$(srcdir)/'`fstcobsdatalocation.c libast_la-fstcresourceprofile.lo: fstcresourceprofile.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstcresourceprofile.lo -MD -MP -MF $(DEPDIR)/libast_la-fstcresourceprofile.Tpo -c -o libast_la-fstcresourceprofile.lo `test -f 'fstcresourceprofile.c' || echo '$(srcdir)/'`fstcresourceprofile.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstcresourceprofile.Tpo $(DEPDIR)/libast_la-fstcresourceprofile.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstcresourceprofile.c' object='libast_la-fstcresourceprofile.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstcresourceprofile.lo `test -f 'fstcresourceprofile.c' || echo '$(srcdir)/'`fstcresourceprofile.c libast_la-fstcschan.lo: fstcschan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstcschan.lo -MD -MP -MF $(DEPDIR)/libast_la-fstcschan.Tpo -c -o libast_la-fstcschan.lo `test -f 'fstcschan.c' || echo '$(srcdir)/'`fstcschan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstcschan.Tpo $(DEPDIR)/libast_la-fstcschan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstcschan.c' object='libast_la-fstcschan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstcschan.lo `test -f 'fstcschan.c' || echo '$(srcdir)/'`fstcschan.c libast_la-fstcsearchlocation.lo: fstcsearchlocation.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fstcsearchlocation.lo -MD -MP -MF $(DEPDIR)/libast_la-fstcsearchlocation.Tpo -c -o libast_la-fstcsearchlocation.lo `test -f 'fstcsearchlocation.c' || echo '$(srcdir)/'`fstcsearchlocation.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fstcsearchlocation.Tpo $(DEPDIR)/libast_la-fstcsearchlocation.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fstcsearchlocation.c' object='libast_la-fstcsearchlocation.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fstcsearchlocation.lo `test -f 'fstcsearchlocation.c' || echo '$(srcdir)/'`fstcsearchlocation.c libast_la-fswitchmap.lo: fswitchmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fswitchmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fswitchmap.Tpo -c -o libast_la-fswitchmap.lo `test -f 'fswitchmap.c' || echo '$(srcdir)/'`fswitchmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fswitchmap.Tpo $(DEPDIR)/libast_la-fswitchmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fswitchmap.c' object='libast_la-fswitchmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fswitchmap.lo `test -f 'fswitchmap.c' || echo '$(srcdir)/'`fswitchmap.c libast_la-ftable.lo: ftable.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ftable.lo -MD -MP -MF $(DEPDIR)/libast_la-ftable.Tpo -c -o libast_la-ftable.lo `test -f 'ftable.c' || echo '$(srcdir)/'`ftable.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ftable.Tpo $(DEPDIR)/libast_la-ftable.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ftable.c' object='libast_la-ftable.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ftable.lo `test -f 'ftable.c' || echo '$(srcdir)/'`ftable.c libast_la-ftimeframe.lo: ftimeframe.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ftimeframe.lo -MD -MP -MF $(DEPDIR)/libast_la-ftimeframe.Tpo -c -o libast_la-ftimeframe.lo `test -f 'ftimeframe.c' || echo '$(srcdir)/'`ftimeframe.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ftimeframe.Tpo $(DEPDIR)/libast_la-ftimeframe.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ftimeframe.c' object='libast_la-ftimeframe.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ftimeframe.lo `test -f 'ftimeframe.c' || echo '$(srcdir)/'`ftimeframe.c libast_la-ftimemap.lo: ftimemap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ftimemap.lo -MD -MP -MF $(DEPDIR)/libast_la-ftimemap.Tpo -c -o libast_la-ftimemap.lo `test -f 'ftimemap.c' || echo '$(srcdir)/'`ftimemap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ftimemap.Tpo $(DEPDIR)/libast_la-ftimemap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ftimemap.c' object='libast_la-ftimemap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ftimemap.lo `test -f 'ftimemap.c' || echo '$(srcdir)/'`ftimemap.c libast_la-ftranmap.lo: ftranmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-ftranmap.lo -MD -MP -MF $(DEPDIR)/libast_la-ftranmap.Tpo -c -o libast_la-ftranmap.lo `test -f 'ftranmap.c' || echo '$(srcdir)/'`ftranmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-ftranmap.Tpo $(DEPDIR)/libast_la-ftranmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='ftranmap.c' object='libast_la-ftranmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-ftranmap.lo `test -f 'ftranmap.c' || echo '$(srcdir)/'`ftranmap.c libast_la-funitmap.lo: funitmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-funitmap.lo -MD -MP -MF $(DEPDIR)/libast_la-funitmap.Tpo -c -o libast_la-funitmap.lo `test -f 'funitmap.c' || echo '$(srcdir)/'`funitmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-funitmap.Tpo $(DEPDIR)/libast_la-funitmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='funitmap.c' object='libast_la-funitmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-funitmap.lo `test -f 'funitmap.c' || echo '$(srcdir)/'`funitmap.c libast_la-funitnormmap.lo: funitnormmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-funitnormmap.lo -MD -MP -MF $(DEPDIR)/libast_la-funitnormmap.Tpo -c -o libast_la-funitnormmap.lo `test -f 'funitnormmap.c' || echo '$(srcdir)/'`funitnormmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-funitnormmap.Tpo $(DEPDIR)/libast_la-funitnormmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='funitnormmap.c' object='libast_la-funitnormmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-funitnormmap.lo `test -f 'funitnormmap.c' || echo '$(srcdir)/'`funitnormmap.c libast_la-fwcsmap.lo: fwcsmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fwcsmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fwcsmap.Tpo -c -o libast_la-fwcsmap.lo `test -f 'fwcsmap.c' || echo '$(srcdir)/'`fwcsmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fwcsmap.Tpo $(DEPDIR)/libast_la-fwcsmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fwcsmap.c' object='libast_la-fwcsmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fwcsmap.lo `test -f 'fwcsmap.c' || echo '$(srcdir)/'`fwcsmap.c libast_la-fwinmap.lo: fwinmap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fwinmap.lo -MD -MP -MF $(DEPDIR)/libast_la-fwinmap.Tpo -c -o libast_la-fwinmap.lo `test -f 'fwinmap.c' || echo '$(srcdir)/'`fwinmap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fwinmap.Tpo $(DEPDIR)/libast_la-fwinmap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fwinmap.c' object='libast_la-fwinmap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fwinmap.lo `test -f 'fwinmap.c' || echo '$(srcdir)/'`fwinmap.c libast_la-fxmlchan.lo: fxmlchan.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fxmlchan.lo -MD -MP -MF $(DEPDIR)/libast_la-fxmlchan.Tpo -c -o libast_la-fxmlchan.lo `test -f 'fxmlchan.c' || echo '$(srcdir)/'`fxmlchan.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fxmlchan.Tpo $(DEPDIR)/libast_la-fxmlchan.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fxmlchan.c' object='libast_la-fxmlchan.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fxmlchan.lo `test -f 'fxmlchan.c' || echo '$(srcdir)/'`fxmlchan.c libast_la-fzoommap.lo: fzoommap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-fzoommap.lo -MD -MP -MF $(DEPDIR)/libast_la-fzoommap.Tpo -c -o libast_la-fzoommap.lo `test -f 'fzoommap.c' || echo '$(srcdir)/'`fzoommap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-fzoommap.Tpo $(DEPDIR)/libast_la-fzoommap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='fzoommap.c' object='libast_la-fzoommap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-fzoommap.lo `test -f 'fzoommap.c' || echo '$(srcdir)/'`fzoommap.c cminpack/libast_la-lmder1.lo: cminpack/lmder1.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-lmder1.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-lmder1.Tpo -c -o cminpack/libast_la-lmder1.lo `test -f 'cminpack/lmder1.c' || echo '$(srcdir)/'`cminpack/lmder1.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-lmder1.Tpo cminpack/$(DEPDIR)/libast_la-lmder1.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/lmder1.c' object='cminpack/libast_la-lmder1.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-lmder1.lo `test -f 'cminpack/lmder1.c' || echo '$(srcdir)/'`cminpack/lmder1.c cminpack/libast_la-lmder.lo: cminpack/lmder.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-lmder.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-lmder.Tpo -c -o cminpack/libast_la-lmder.lo `test -f 'cminpack/lmder.c' || echo '$(srcdir)/'`cminpack/lmder.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-lmder.Tpo cminpack/$(DEPDIR)/libast_la-lmder.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/lmder.c' object='cminpack/libast_la-lmder.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-lmder.lo `test -f 'cminpack/lmder.c' || echo '$(srcdir)/'`cminpack/lmder.c cminpack/libast_la-dpmpar.lo: cminpack/dpmpar.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-dpmpar.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-dpmpar.Tpo -c -o cminpack/libast_la-dpmpar.lo `test -f 'cminpack/dpmpar.c' || echo '$(srcdir)/'`cminpack/dpmpar.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-dpmpar.Tpo cminpack/$(DEPDIR)/libast_la-dpmpar.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/dpmpar.c' object='cminpack/libast_la-dpmpar.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-dpmpar.lo `test -f 'cminpack/dpmpar.c' || echo '$(srcdir)/'`cminpack/dpmpar.c cminpack/libast_la-enorm.lo: cminpack/enorm.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-enorm.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-enorm.Tpo -c -o cminpack/libast_la-enorm.lo `test -f 'cminpack/enorm.c' || echo '$(srcdir)/'`cminpack/enorm.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-enorm.Tpo cminpack/$(DEPDIR)/libast_la-enorm.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/enorm.c' object='cminpack/libast_la-enorm.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-enorm.lo `test -f 'cminpack/enorm.c' || echo '$(srcdir)/'`cminpack/enorm.c cminpack/libast_la-qrfac.lo: cminpack/qrfac.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-qrfac.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-qrfac.Tpo -c -o cminpack/libast_la-qrfac.lo `test -f 'cminpack/qrfac.c' || echo '$(srcdir)/'`cminpack/qrfac.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-qrfac.Tpo cminpack/$(DEPDIR)/libast_la-qrfac.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/qrfac.c' object='cminpack/libast_la-qrfac.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-qrfac.lo `test -f 'cminpack/qrfac.c' || echo '$(srcdir)/'`cminpack/qrfac.c cminpack/libast_la-lmpar.lo: cminpack/lmpar.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-lmpar.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-lmpar.Tpo -c -o cminpack/libast_la-lmpar.lo `test -f 'cminpack/lmpar.c' || echo '$(srcdir)/'`cminpack/lmpar.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-lmpar.Tpo cminpack/$(DEPDIR)/libast_la-lmpar.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/lmpar.c' object='cminpack/libast_la-lmpar.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-lmpar.lo `test -f 'cminpack/lmpar.c' || echo '$(srcdir)/'`cminpack/lmpar.c cminpack/libast_la-qrsolv.lo: cminpack/qrsolv.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT cminpack/libast_la-qrsolv.lo -MD -MP -MF cminpack/$(DEPDIR)/libast_la-qrsolv.Tpo -c -o cminpack/libast_la-qrsolv.lo `test -f 'cminpack/qrsolv.c' || echo '$(srcdir)/'`cminpack/qrsolv.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) cminpack/$(DEPDIR)/libast_la-qrsolv.Tpo cminpack/$(DEPDIR)/libast_la-qrsolv.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='cminpack/qrsolv.c' object='cminpack/libast_la-qrsolv.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o cminpack/libast_la-qrsolv.lo `test -f 'cminpack/qrsolv.c' || echo '$(srcdir)/'`cminpack/qrsolv.c libast_la-proj.lo: proj.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-proj.lo -MD -MP -MF $(DEPDIR)/libast_la-proj.Tpo -c -o libast_la-proj.lo `test -f 'proj.c' || echo '$(srcdir)/'`proj.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-proj.Tpo $(DEPDIR)/libast_la-proj.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='proj.c' object='libast_la-proj.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-proj.lo `test -f 'proj.c' || echo '$(srcdir)/'`proj.c libast_la-tpn.lo: tpn.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-tpn.lo -MD -MP -MF $(DEPDIR)/libast_la-tpn.Tpo -c -o libast_la-tpn.lo `test -f 'tpn.c' || echo '$(srcdir)/'`tpn.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-tpn.Tpo $(DEPDIR)/libast_la-tpn.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='tpn.c' object='libast_la-tpn.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-tpn.lo `test -f 'tpn.c' || echo '$(srcdir)/'`tpn.c libast_la-wcstrig.lo: wcstrig.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -MT libast_la-wcstrig.lo -MD -MP -MF $(DEPDIR)/libast_la-wcstrig.Tpo -c -o libast_la-wcstrig.lo `test -f 'wcstrig.c' || echo '$(srcdir)/'`wcstrig.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_la-wcstrig.Tpo $(DEPDIR)/libast_la-wcstrig.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='wcstrig.c' object='libast_la-wcstrig.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_la_CFLAGS) $(CFLAGS) -c -o libast_la-wcstrig.lo `test -f 'wcstrig.c' || echo '$(srcdir)/'`wcstrig.c libast_drama_la-err_drama.lo: err_drama.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_drama_la_CFLAGS) $(CFLAGS) -MT libast_drama_la-err_drama.lo -MD -MP -MF $(DEPDIR)/libast_drama_la-err_drama.Tpo -c -o libast_drama_la-err_drama.lo `test -f 'err_drama.c' || echo '$(srcdir)/'`err_drama.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_drama_la-err_drama.Tpo $(DEPDIR)/libast_drama_la-err_drama.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='err_drama.c' object='libast_drama_la-err_drama.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_drama_la_CFLAGS) $(CFLAGS) -c -o libast_drama_la-err_drama.lo `test -f 'err_drama.c' || echo '$(srcdir)/'`err_drama.c libast_ems_la-err_ems.lo: err_ems.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_ems_la_CFLAGS) $(CFLAGS) -MT libast_ems_la-err_ems.lo -MD -MP -MF $(DEPDIR)/libast_ems_la-err_ems.Tpo -c -o libast_ems_la-err_ems.lo `test -f 'err_ems.c' || echo '$(srcdir)/'`err_ems.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_ems_la-err_ems.Tpo $(DEPDIR)/libast_ems_la-err_ems.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='err_ems.c' object='libast_ems_la-err_ems.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_ems_la_CFLAGS) $(CFLAGS) -c -o libast_ems_la-err_ems.lo `test -f 'err_ems.c' || echo '$(srcdir)/'`err_ems.c libast_err_la-err_null.lo: err_null.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_err_la_CFLAGS) $(CFLAGS) -MT libast_err_la-err_null.lo -MD -MP -MF $(DEPDIR)/libast_err_la-err_null.Tpo -c -o libast_err_la-err_null.lo `test -f 'err_null.c' || echo '$(srcdir)/'`err_null.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_err_la-err_null.Tpo $(DEPDIR)/libast_err_la-err_null.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='err_null.c' object='libast_err_la-err_null.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_err_la_CFLAGS) $(CFLAGS) -c -o libast_err_la-err_null.lo `test -f 'err_null.c' || echo '$(srcdir)/'`err_null.c libast_grf3d_la-grf3d.lo: grf3d.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf3d_la_CFLAGS) $(CFLAGS) -MT libast_grf3d_la-grf3d.lo -MD -MP -MF $(DEPDIR)/libast_grf3d_la-grf3d.Tpo -c -o libast_grf3d_la-grf3d.lo `test -f 'grf3d.c' || echo '$(srcdir)/'`grf3d.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_grf3d_la-grf3d.Tpo $(DEPDIR)/libast_grf3d_la-grf3d.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf3d.c' object='libast_grf3d_la-grf3d.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf3d_la_CFLAGS) $(CFLAGS) -c -o libast_grf3d_la-grf3d.lo `test -f 'grf3d.c' || echo '$(srcdir)/'`grf3d.c libast_grf_2_0_la-grf_2.0.lo: grf_2.0.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_2_0_la_CFLAGS) $(CFLAGS) -MT libast_grf_2_0_la-grf_2.0.lo -MD -MP -MF $(DEPDIR)/libast_grf_2_0_la-grf_2.0.Tpo -c -o libast_grf_2_0_la-grf_2.0.lo `test -f 'grf_2.0.c' || echo '$(srcdir)/'`grf_2.0.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_grf_2_0_la-grf_2.0.Tpo $(DEPDIR)/libast_grf_2_0_la-grf_2.0.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf_2.0.c' object='libast_grf_2_0_la-grf_2.0.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_2_0_la_CFLAGS) $(CFLAGS) -c -o libast_grf_2_0_la-grf_2.0.lo `test -f 'grf_2.0.c' || echo '$(srcdir)/'`grf_2.0.c libast_grf_3_2_la-grf_3.2.lo: grf_3.2.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_3_2_la_CFLAGS) $(CFLAGS) -MT libast_grf_3_2_la-grf_3.2.lo -MD -MP -MF $(DEPDIR)/libast_grf_3_2_la-grf_3.2.Tpo -c -o libast_grf_3_2_la-grf_3.2.lo `test -f 'grf_3.2.c' || echo '$(srcdir)/'`grf_3.2.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_grf_3_2_la-grf_3.2.Tpo $(DEPDIR)/libast_grf_3_2_la-grf_3.2.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf_3.2.c' object='libast_grf_3_2_la-grf_3.2.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_3_2_la_CFLAGS) $(CFLAGS) -c -o libast_grf_3_2_la-grf_3.2.lo `test -f 'grf_3.2.c' || echo '$(srcdir)/'`grf_3.2.c libast_grf_5_6_la-grf_5.6.lo: grf_5.6.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_5_6_la_CFLAGS) $(CFLAGS) -MT libast_grf_5_6_la-grf_5.6.lo -MD -MP -MF $(DEPDIR)/libast_grf_5_6_la-grf_5.6.Tpo -c -o libast_grf_5_6_la-grf_5.6.lo `test -f 'grf_5.6.c' || echo '$(srcdir)/'`grf_5.6.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_grf_5_6_la-grf_5.6.Tpo $(DEPDIR)/libast_grf_5_6_la-grf_5.6.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf_5.6.c' object='libast_grf_5_6_la-grf_5.6.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_grf_5_6_la_CFLAGS) $(CFLAGS) -c -o libast_grf_5_6_la-grf_5.6.lo `test -f 'grf_5.6.c' || echo '$(srcdir)/'`grf_5.6.c libast_pal_la-palwrap.lo: palwrap.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pal_la_CFLAGS) $(CFLAGS) -MT libast_pal_la-palwrap.lo -MD -MP -MF $(DEPDIR)/libast_pal_la-palwrap.Tpo -c -o libast_pal_la-palwrap.lo `test -f 'palwrap.c' || echo '$(srcdir)/'`palwrap.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_pal_la-palwrap.Tpo $(DEPDIR)/libast_pal_la-palwrap.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='palwrap.c' object='libast_pal_la-palwrap.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pal_la_CFLAGS) $(CFLAGS) -c -o libast_pal_la-palwrap.lo `test -f 'palwrap.c' || echo '$(srcdir)/'`palwrap.c libast_pgplot_la-grf_pgplot.lo: grf_pgplot.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot_la_CFLAGS) $(CFLAGS) -MT libast_pgplot_la-grf_pgplot.lo -MD -MP -MF $(DEPDIR)/libast_pgplot_la-grf_pgplot.Tpo -c -o libast_pgplot_la-grf_pgplot.lo `test -f 'grf_pgplot.c' || echo '$(srcdir)/'`grf_pgplot.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_pgplot_la-grf_pgplot.Tpo $(DEPDIR)/libast_pgplot_la-grf_pgplot.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf_pgplot.c' object='libast_pgplot_la-grf_pgplot.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot_la_CFLAGS) $(CFLAGS) -c -o libast_pgplot_la-grf_pgplot.lo `test -f 'grf_pgplot.c' || echo '$(srcdir)/'`grf_pgplot.c libast_pgplot_la-grf_5.6.lo: grf_5.6.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot_la_CFLAGS) $(CFLAGS) -MT libast_pgplot_la-grf_5.6.lo -MD -MP -MF $(DEPDIR)/libast_pgplot_la-grf_5.6.Tpo -c -o libast_pgplot_la-grf_5.6.lo `test -f 'grf_5.6.c' || echo '$(srcdir)/'`grf_5.6.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_pgplot_la-grf_5.6.Tpo $(DEPDIR)/libast_pgplot_la-grf_5.6.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf_5.6.c' object='libast_pgplot_la-grf_5.6.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot_la_CFLAGS) $(CFLAGS) -c -o libast_pgplot_la-grf_5.6.lo `test -f 'grf_5.6.c' || echo '$(srcdir)/'`grf_5.6.c libast_pgplot3d_la-grf3d_pgplot.lo: grf3d_pgplot.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot3d_la_CFLAGS) $(CFLAGS) -MT libast_pgplot3d_la-grf3d_pgplot.lo -MD -MP -MF $(DEPDIR)/libast_pgplot3d_la-grf3d_pgplot.Tpo -c -o libast_pgplot3d_la-grf3d_pgplot.lo `test -f 'grf3d_pgplot.c' || echo '$(srcdir)/'`grf3d_pgplot.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_pgplot3d_la-grf3d_pgplot.Tpo $(DEPDIR)/libast_pgplot3d_la-grf3d_pgplot.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf3d_pgplot.c' object='libast_pgplot3d_la-grf3d_pgplot.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot3d_la_CFLAGS) $(CFLAGS) -c -o libast_pgplot3d_la-grf3d_pgplot.lo `test -f 'grf3d_pgplot.c' || echo '$(srcdir)/'`grf3d_pgplot.c libast_pgplot3d_la-grf3d.lo: grf3d.c @am__fastdepCC_TRUE@ $(AM_V_CC)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot3d_la_CFLAGS) $(CFLAGS) -MT libast_pgplot3d_la-grf3d.lo -MD -MP -MF $(DEPDIR)/libast_pgplot3d_la-grf3d.Tpo -c -o libast_pgplot3d_la-grf3d.lo `test -f 'grf3d.c' || echo '$(srcdir)/'`grf3d.c @am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/libast_pgplot3d_la-grf3d.Tpo $(DEPDIR)/libast_pgplot3d_la-grf3d.Plo @AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='grf3d.c' object='libast_pgplot3d_la-grf3d.lo' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ @am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(STAR_CPPFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(libast_pgplot3d_la_CFLAGS) $(CFLAGS) -c -o libast_pgplot3d_la-grf3d.lo `test -f 'grf3d.c' || echo '$(srcdir)/'`grf3d.c mostlyclean-libtool: -rm -f *.lo clean-libtool: -rm -rf .libs _libs -rm -rf cminpack/.libs cminpack/_libs distclean-libtool: -rm -f libtool config.lt install-includeMESSAGES: $(include_MESSAGES) @$(NORMAL_INSTALL) @list='$(include_MESSAGES)'; test -n "$(includedir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(includedir)'"; \ $(MKDIR_P) "$(DESTDIR)$(includedir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_MESSAGE) $$files '$(DESTDIR)$(includedir)'"; \ $(INSTALL_MESSAGE) $$files "$(DESTDIR)$(includedir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(includedir)/$$f" || :; \ done; \ done uninstall-includeMESSAGES: @$(NORMAL_UNINSTALL) @list='$(include_MESSAGES)'; test -n "$(includedir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(includedir)'; $(am__uninstall_files_from_dir) # Compile messages for message file ast_err.msg. This requires that the # @MESSGEN@ substitution was requested in configure.ac, probably implicitly # by the STAR_MESSGEN macro. # # These rules are usable only in the predist state (since the .msg files # are typically not distributed), so should be activated only when in that # state. @PREDIST@AST_ERR: ast_err.msg @PREDIST@ $(MESSGEN) -F ast_err.msg @PREDIST@ast_err.h: ast_err.msg @PREDIST@ $(MESSGEN) -c ast_err.msg @PREDIST@fac_1521_err: ast_err.msg @PREDIST@ $(MESSGEN) -e ast_err.msg install-dist_pkgdataDATA: $(dist_pkgdata_DATA) @$(NORMAL_INSTALL) @list='$(dist_pkgdata_DATA)'; test -n "$(pkgdatadir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(pkgdatadir)'"; \ $(MKDIR_P) "$(DESTDIR)$(pkgdatadir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pkgdatadir)'"; \ $(INSTALL_DATA) $$files "$(DESTDIR)$(pkgdatadir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(pkgdatadir)/$$f" || :; \ done; \ done uninstall-dist_pkgdataDATA: @$(NORMAL_UNINSTALL) @list='$(dist_pkgdata_DATA)'; test -n "$(pkgdatadir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(pkgdatadir)'; $(am__uninstall_files_from_dir) install-dist_starnewsDATA: $(dist_starnews_DATA) @$(NORMAL_INSTALL) @list='$(dist_starnews_DATA)'; test -n "$(starnewsdir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(starnewsdir)'"; \ $(MKDIR_P) "$(DESTDIR)$(starnewsdir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(starnewsdir)'"; \ $(INSTALL_DATA) $$files "$(DESTDIR)$(starnewsdir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(starnewsdir)/$$f" || :; \ done; \ done uninstall-dist_starnewsDATA: @$(NORMAL_UNINSTALL) @list='$(dist_starnews_DATA)'; test -n "$(starnewsdir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(starnewsdir)'; $(am__uninstall_files_from_dir) install-stardocsDATA: $(stardocs_DATA) @$(NORMAL_INSTALL) $(mkdir_p) $(DESTDIR)$(stardocsdir) @list='$(stardocs_DATA)'; for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ f="`echo $$p | sed -e 's|^.*/||'`"; \ if expr "x$$p" : 'x.*\.htx_tar$$' >/dev/null; then \ if test -n "$(PAX)"; then \ if $(MANIFEST); then \ $(PAX) -f $$d$$p | \ sed 's+^+MANIFEST:$(DESTDIR)$(stardocsdir)/+'; \ fi; \ cat $$d$$p | (cd $(DESTDIR)$(stardocsdir); $(PAX) -r); \ elif test -n "$(TAR)"; then \ if $(MANIFEST); then \ cat $$d$$p | (cd $(DESTDIR)$(stardocsdir); $(TAR) xBpvf -) | sed 's+^+MANIFEST:$(DESTDIR)$(stardocsdir)/+'; \ else \ cat $$d$$p | (cd $(DESTDIR)$(stardocsdir); $(TAR) xBpf -); \ fi; \ else \ echo "Neither tar nor pax!!!" >&2; \ exit 1; \ fi; \ else \ echo " $(stardocsDATA_INSTALL) $$d$$p $(DESTDIR)$(stardocsdir)/$$f"; \ $(stardocsDATA_INSTALL) $$d$$p $(DESTDIR)$(stardocsdir)/$$f; \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(stardocsdir)/$$f" || :; \ fi; \ done uninstall-stardocsDATA: @$(NORMAL_UNINSTALL) @list='$(stardocs_DATA)'; for p in $$list; do \ f="`echo $$p | sed -e 's|^.*/||'`"; \ echo " rm -f $(DESTDIR)$(stardocsdir)/$$f"; \ rm -f $(DESTDIR)$(stardocsdir)/$$f; \ done install-starfacsDATA: $(starfacs_DATA) @$(NORMAL_INSTALL) @list='$(starfacs_DATA)'; test -n "$(starfacsdir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(starfacsdir)'"; \ $(MKDIR_P) "$(DESTDIR)$(starfacsdir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(starfacsdir)'"; \ $(INSTALL_DATA) $$files "$(DESTDIR)$(starfacsdir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(starfacsdir)/$$f" || :; \ done; \ done uninstall-starfacsDATA: @$(NORMAL_UNINSTALL) @list='$(starfacs_DATA)'; test -n "$(starfacsdir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(starfacsdir)'; $(am__uninstall_files_from_dir) install-includeHEADERS: $(include_HEADERS) @$(NORMAL_INSTALL) @list='$(include_HEADERS)'; test -n "$(includedir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(includedir)'"; \ $(MKDIR_P) "$(DESTDIR)$(includedir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_HEADER) $$files '$(DESTDIR)$(includedir)'"; \ $(INSTALL_HEADER) $$files "$(DESTDIR)$(includedir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(includedir)/$$f" || :; \ done; \ done uninstall-includeHEADERS: @$(NORMAL_UNINSTALL) @list='$(include_HEADERS)'; test -n "$(includedir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(includedir)'; $(am__uninstall_files_from_dir) install-nodist_includeHEADERS: $(nodist_include_HEADERS) @$(NORMAL_INSTALL) @list='$(nodist_include_HEADERS)'; test -n "$(includedir)" || list=; \ if test -n "$$list"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(includedir)'"; \ $(MKDIR_P) "$(DESTDIR)$(includedir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ echo " $(INSTALL_HEADER) $$files '$(DESTDIR)$(includedir)'"; \ $(INSTALL_HEADER) $$files "$(DESTDIR)$(includedir)" || exit $$?; \ for f in $$files; do \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(includedir)/$$f" || :; \ done; \ done uninstall-nodist_includeHEADERS: @$(NORMAL_UNINSTALL) @list='$(nodist_include_HEADERS)'; test -n "$(includedir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(includedir)'; $(am__uninstall_files_from_dir) ID: $(am__tagged_files) $(am__define_uniq_tagged_files); mkid -fID $$unique tags: tags-am TAGS: tags tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) set x; \ here=`pwd`; \ $(am__define_uniq_tagged_files); \ shift; \ if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ test -n "$$unique" || unique=$$empty_fix; \ if test $$# -gt 0; then \ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ "$$@" $$unique; \ else \ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ $$unique; \ fi; \ fi ctags: ctags-am CTAGS: ctags ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) $(am__define_uniq_tagged_files); \ test -z "$(CTAGS_ARGS)$$unique" \ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ $$unique GTAGS: here=`$(am__cd) $(top_builddir) && pwd` \ && $(am__cd) $(top_srcdir) \ && gtags -i $(GTAGS_ARGS) "$$here" cscope: cscope.files test ! -s cscope.files \ || $(CSCOPE) -b -q $(AM_CSCOPEFLAGS) $(CSCOPEFLAGS) -i cscope.files $(CSCOPE_ARGS) clean-cscope: -rm -f cscope.files cscope.files: clean-cscope cscopelist cscopelist: cscopelist-am cscopelist-am: $(am__tagged_files) list='$(am__tagged_files)'; \ case "$(srcdir)" in \ [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \ *) sdir=$(subdir)/$(srcdir) ;; \ esac; \ for i in $$list; do \ if test -f "$$i"; then \ echo "$(subdir)/$$i"; \ else \ echo "$$sdir/$$i"; \ fi; \ done >> $(top_builddir)/cscope.files distclean-tags: -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags -rm -f cscope.out cscope.in.out cscope.po.out cscope.files # Recover from deleted '.trs' file; this should ensure that # "rm -f foo.log; make foo.trs" re-run 'foo.test', and re-create # both 'foo.log' and 'foo.trs'. Break the recipe in two subshells # to avoid problems with "make -n". .log.trs: rm -f $< $@ $(MAKE) $(AM_MAKEFLAGS) $< # Leading 'am--fnord' is there to ensure the list of targets does not # expand to empty, as could happen e.g. with make check TESTS=''. am--fnord $(TEST_LOGS) $(TEST_LOGS:.log=.trs): $(am__force_recheck) am--force-recheck: @: $(TEST_SUITE_LOG): $(TEST_LOGS) @$(am__set_TESTS_bases); \ am__f_ok () { test -f "$$1" && test -r "$$1"; }; \ redo_bases=`for i in $$bases; do \ am__f_ok $$i.trs && am__f_ok $$i.log || echo $$i; \ done`; \ if test -n "$$redo_bases"; then \ redo_logs=`for i in $$redo_bases; do echo $$i.log; done`; \ redo_results=`for i in $$redo_bases; do echo $$i.trs; done`; \ if $(am__make_dryrun); then :; else \ rm -f $$redo_logs && rm -f $$redo_results || exit 1; \ fi; \ fi; \ if test -n "$$am__remaking_logs"; then \ echo "fatal: making $(TEST_SUITE_LOG): possible infinite" \ "recursion detected" >&2; \ else \ am__remaking_logs=yes $(MAKE) $(AM_MAKEFLAGS) $$redo_logs; \ fi; \ if $(am__make_dryrun); then :; else \ st=0; \ errmsg="fatal: making $(TEST_SUITE_LOG): failed to create"; \ for i in $$redo_bases; do \ test -f $$i.trs && test -r $$i.trs \ || { echo "$$errmsg $$i.trs" >&2; st=1; }; \ test -f $$i.log && test -r $$i.log \ || { echo "$$errmsg $$i.log" >&2; st=1; }; \ done; \ test $$st -eq 0 || exit 1; \ fi @$(am__sh_e_setup); $(am__tty_colors); $(am__set_TESTS_bases); \ ws='[ ]'; \ results=`for b in $$bases; do echo $$b.trs; done`; \ test -n "$$results" || results=/dev/null; \ all=` grep "^$$ws*:test-result:" $$results | wc -l`; \ pass=` grep "^$$ws*:test-result:$$ws*PASS" $$results | wc -l`; \ fail=` grep "^$$ws*:test-result:$$ws*FAIL" $$results | wc -l`; \ skip=` grep "^$$ws*:test-result:$$ws*SKIP" $$results | wc -l`; \ xfail=`grep "^$$ws*:test-result:$$ws*XFAIL" $$results | wc -l`; \ xpass=`grep "^$$ws*:test-result:$$ws*XPASS" $$results | wc -l`; \ error=`grep "^$$ws*:test-result:$$ws*ERROR" $$results | wc -l`; \ if test `expr $$fail + $$xpass + $$error` -eq 0; then \ success=true; \ else \ success=false; \ fi; \ br='==================='; br=$$br$$br$$br$$br; \ result_count () \ { \ if test x"$$1" = x"--maybe-color"; then \ maybe_colorize=yes; \ elif test x"$$1" = x"--no-color"; then \ maybe_colorize=no; \ else \ echo "$@: invalid 'result_count' usage" >&2; exit 4; \ fi; \ shift; \ desc=$$1 count=$$2; \ if test $$maybe_colorize = yes && test $$count -gt 0; then \ color_start=$$3 color_end=$$std; \ else \ color_start= color_end=; \ fi; \ echo "$${color_start}# $$desc $$count$${color_end}"; \ }; \ create_testsuite_report () \ { \ result_count $$1 "TOTAL:" $$all "$$brg"; \ result_count $$1 "PASS: " $$pass "$$grn"; \ result_count $$1 "SKIP: " $$skip "$$blu"; \ result_count $$1 "XFAIL:" $$xfail "$$lgn"; \ result_count $$1 "FAIL: " $$fail "$$red"; \ result_count $$1 "XPASS:" $$xpass "$$red"; \ result_count $$1 "ERROR:" $$error "$$mgn"; \ }; \ { \ echo "$(PACKAGE_STRING): $(subdir)/$(TEST_SUITE_LOG)" | \ $(am__rst_title); \ create_testsuite_report --no-color; \ echo; \ echo ".. contents:: :depth: 2"; \ echo; \ for b in $$bases; do echo $$b; done \ | $(am__create_global_log); \ } >$(TEST_SUITE_LOG).tmp || exit 1; \ mv $(TEST_SUITE_LOG).tmp $(TEST_SUITE_LOG); \ if $$success; then \ col="$$grn"; \ else \ col="$$red"; \ test x"$$VERBOSE" = x || cat $(TEST_SUITE_LOG); \ fi; \ echo "$${col}$$br$${std}"; \ echo "$${col}Testsuite summary for $(PACKAGE_STRING)$${std}"; \ echo "$${col}$$br$${std}"; \ create_testsuite_report --maybe-color; \ echo "$$col$$br$$std"; \ if $$success; then :; else \ echo "$${col}See $(subdir)/$(TEST_SUITE_LOG)$${std}"; \ if test -n "$(PACKAGE_BUGREPORT)"; then \ echo "$${col}Please report to $(PACKAGE_BUGREPORT)$${std}"; \ fi; \ echo "$$col$$br$$std"; \ fi; \ $$success || exit 1 check-TESTS: @list='$(RECHECK_LOGS)'; test -z "$$list" || rm -f $$list @list='$(RECHECK_LOGS:.log=.trs)'; test -z "$$list" || rm -f $$list @test -z "$(TEST_SUITE_LOG)" || rm -f $(TEST_SUITE_LOG) @set +e; $(am__set_TESTS_bases); \ log_list=`for i in $$bases; do echo $$i.log; done`; \ trs_list=`for i in $$bases; do echo $$i.trs; done`; \ log_list=`echo $$log_list`; trs_list=`echo $$trs_list`; \ $(MAKE) $(AM_MAKEFLAGS) $(TEST_SUITE_LOG) TEST_LOGS="$$log_list"; \ exit $$?; recheck: all $(check_PROGRAMS) @test -z "$(TEST_SUITE_LOG)" || rm -f $(TEST_SUITE_LOG) @set +e; $(am__set_TESTS_bases); \ bases=`for i in $$bases; do echo $$i; done \ | $(am__list_recheck_tests)` || exit 1; \ log_list=`for i in $$bases; do echo $$i.log; done`; \ log_list=`echo $$log_list`; \ $(MAKE) $(AM_MAKEFLAGS) $(TEST_SUITE_LOG) \ am__force_recheck=am--force-recheck \ TEST_LOGS="$$log_list"; \ exit $$? ast_test.log: ast_test$(EXEEXT) @p='ast_test$(EXEEXT)'; \ b='ast_test'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) .test.log: @p='$<'; \ $(am__set_b); \ $(am__check_pre) $(TEST_LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_TEST_LOG_DRIVER_FLAGS) $(TEST_LOG_DRIVER_FLAGS) -- $(TEST_LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) @am__EXEEXT_TRUE@.test$(EXEEXT).log: @am__EXEEXT_TRUE@ @p='$<'; \ @am__EXEEXT_TRUE@ $(am__set_b); \ @am__EXEEXT_TRUE@ $(am__check_pre) $(TEST_LOG_DRIVER) --test-name "$$f" \ @am__EXEEXT_TRUE@ --log-file $$b.log --trs-file $$b.trs \ @am__EXEEXT_TRUE@ $(am__common_driver_flags) $(AM_TEST_LOG_DRIVER_FLAGS) $(TEST_LOG_DRIVER_FLAGS) -- $(TEST_LOG_COMPILE) \ @am__EXEEXT_TRUE@ "$$tst" $(AM_TESTS_FD_REDIRECT) # Don't express a dependency via the directory .htx, or else make # tries to delete it as an intermediate (we can't specify # .PRECIOUS targets within this file). # # Requires that the STAR2HTML substitution was made in # configure.ac, probably implicitly by the STAR_LATEX_DOCUMENTATION macro. # # We do not require that star2html be available on the build system, # and so we distribute built HTX documentation. Thus the following rules # should be invoked only in the predist state. However there isn't a # file we can use to test whether we're in that state, so write the # test so that it will fail if star2html isn't available. # # If file $(<:.tex=.htx_tar.extras) is present, then it contains a list # of files, each one of which should be added to the .htx directory before # it is rolled up into a tarball. # # Ignore the exit status of star2html, as it can sometimes fail harmlessly. .tex.dvi: LATEX=latex; latex2dvi () { $(LATEX2DVI); }; \ latex2dvi ${<:.tex=} .dvi.ps: dvips -o $@ $< .tex.ps: LATEX=latex; latex2dvi () { $(LATEX2DVI); }; \ latex2dvi ${<:.tex=} dvips -o $@ $(<:.tex=.dvi) .tex.pdf: LATEX=pdflatex; latex2dvi () { $(LATEX2DVI); }; \ TEXINPUTS=${STARLINK}/share/latexsupport//:${TEXINPUTS} latex2dvi ${<:.tex=} .tex.htx_tar: - @STAR2HTML@ $(STAR2HTML_FLAGS) $< test -d ${<:.tex=.htx} if test -f ${<:.tex=.htx_tar.extras}; then \ for f in `cat ${<:.tex=.htx_tar.extras}`; do \ test -f "$$f" && cp "$$f" ${<:.tex=.htx} || true; \ done; else :; fi tar cf $@ ${<:.tex=.htx} distdir: $(DISTFILES) $(am__remove_distdir) test -d "$(distdir)" || mkdir "$(distdir)" @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ list='$(DISTFILES)'; \ dist_files=`for file in $$list; do echo $$file; done | \ sed -e "s|^$$srcdirstrip/||;t" \ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ case $$dist_files in \ */*) $(MKDIR_P) `echo "$$dist_files" | \ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ sort -u` ;; \ esac; \ for file in $$dist_files; do \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ if test -d $$d/$$file; then \ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ if test -d "$(distdir)/$$file"; then \ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ else \ test -f "$(distdir)/$$file" \ || cp -p $$d/$$file "$(distdir)/$$file" \ || exit 1; \ fi; \ done $(MAKE) $(AM_MAKEFLAGS) \ top_distdir="$(top_distdir)" distdir="$(distdir)" \ dist-hook -test -n "$(am__skip_mode_fix)" \ || find "$(distdir)" -type d ! -perm -755 \ -exec chmod u+rwx,go+rx {} \; -o \ ! -type d ! -perm -444 -links 1 -exec chmod a+r {} \; -o \ ! -type d ! -perm -400 -exec chmod a+r {} \; -o \ ! -type d ! -perm -444 -exec $(install_sh) -c -m a+r {} {} \; \ || chmod -R a+r "$(distdir)" dist-gzip: distdir tardir=$(distdir) && $(am__tar) | GZIP=$(GZIP_ENV) gzip -c >$(distdir).tar.gz $(am__post_remove_distdir) dist-bzip2: distdir tardir=$(distdir) && $(am__tar) | BZIP2=$${BZIP2--9} bzip2 -c >$(distdir).tar.bz2 $(am__post_remove_distdir) dist-lzip: distdir tardir=$(distdir) && $(am__tar) | lzip -c $${LZIP_OPT--9} >$(distdir).tar.lz $(am__post_remove_distdir) dist-xz: distdir tardir=$(distdir) && $(am__tar) | XZ_OPT=$${XZ_OPT--e} xz -c >$(distdir).tar.xz $(am__post_remove_distdir) dist-tarZ: distdir @echo WARNING: "Support for shar distribution archives is" \ "deprecated." >&2 @echo WARNING: "It will be removed altogether in Automake 2.0" >&2 tardir=$(distdir) && $(am__tar) | compress -c >$(distdir).tar.Z $(am__post_remove_distdir) dist-shar: distdir @echo WARNING: "Support for distribution archives compressed with" \ "legacy program 'compress' is deprecated." >&2 @echo WARNING: "It will be removed altogether in Automake 2.0" >&2 shar $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir).shar.gz $(am__post_remove_distdir) dist-zip: distdir -rm -f $(distdir).zip zip -rq $(distdir).zip $(distdir) $(am__post_remove_distdir) dist dist-all: $(MAKE) $(AM_MAKEFLAGS) $(DIST_TARGETS) am__post_remove_distdir='@:' $(am__post_remove_distdir) # This target untars the dist file and tries a VPATH configuration. Then # it guarantees that the distribution is self-contained by making another # tarfile. distcheck: dist case '$(DIST_ARCHIVES)' in \ *.tar.gz*) \ GZIP=$(GZIP_ENV) gzip -dc $(distdir).tar.gz | $(am__untar) ;;\ *.tar.bz2*) \ bzip2 -dc $(distdir).tar.bz2 | $(am__untar) ;;\ *.tar.lz*) \ lzip -dc $(distdir).tar.lz | $(am__untar) ;;\ *.tar.xz*) \ xz -dc $(distdir).tar.xz | $(am__untar) ;;\ *.tar.Z*) \ uncompress -c $(distdir).tar.Z | $(am__untar) ;;\ *.shar.gz*) \ GZIP=$(GZIP_ENV) gzip -dc $(distdir).shar.gz | unshar ;;\ *.zip*) \ unzip $(distdir).zip ;;\ esac chmod -R a-w $(distdir) chmod u+w $(distdir) mkdir $(distdir)/_build $(distdir)/_inst chmod a-w $(distdir) test -d $(distdir)/_build || exit 0; \ dc_install_base=`$(am__cd) $(distdir)/_inst && pwd | sed -e 's,^[^:\\/]:[\\/],/,'` \ && dc_destdir="$${TMPDIR-/tmp}/am-dc-$$$$/" \ && am__cwd=`pwd` \ && $(am__cd) $(distdir)/_build \ && ../configure \ $(AM_DISTCHECK_CONFIGURE_FLAGS) \ $(DISTCHECK_CONFIGURE_FLAGS) \ --srcdir=.. --prefix="$$dc_install_base" \ && $(MAKE) $(AM_MAKEFLAGS) \ && $(MAKE) $(AM_MAKEFLAGS) dvi \ && $(MAKE) $(AM_MAKEFLAGS) check \ && $(MAKE) $(AM_MAKEFLAGS) install \ && $(MAKE) $(AM_MAKEFLAGS) installcheck \ && $(MAKE) $(AM_MAKEFLAGS) uninstall \ && $(MAKE) $(AM_MAKEFLAGS) distuninstallcheck_dir="$$dc_install_base" \ distuninstallcheck \ && chmod -R a-w "$$dc_install_base" \ && ({ \ (cd ../.. && umask 077 && mkdir "$$dc_destdir") \ && $(MAKE) $(AM_MAKEFLAGS) DESTDIR="$$dc_destdir" install \ && $(MAKE) $(AM_MAKEFLAGS) DESTDIR="$$dc_destdir" uninstall \ && $(MAKE) $(AM_MAKEFLAGS) DESTDIR="$$dc_destdir" \ distuninstallcheck_dir="$$dc_destdir" distuninstallcheck; \ } || { rm -rf "$$dc_destdir"; exit 1; }) \ && rm -rf "$$dc_destdir" \ && $(MAKE) $(AM_MAKEFLAGS) dist \ && rm -rf $(DIST_ARCHIVES) \ && $(MAKE) $(AM_MAKEFLAGS) distcleancheck \ && cd "$$am__cwd" \ || exit 1 $(am__post_remove_distdir) @(echo "$(distdir) archives ready for distribution: "; \ list='$(DIST_ARCHIVES)'; for i in $$list; do echo $$i; done) | \ sed -e 1h -e 1s/./=/g -e 1p -e 1x -e '$$p' -e '$$x' distuninstallcheck: @test -n '$(distuninstallcheck_dir)' || { \ echo 'ERROR: trying to run $@ with an empty' \ '$$(distuninstallcheck_dir)' >&2; \ exit 1; \ }; \ $(am__cd) '$(distuninstallcheck_dir)' || { \ echo 'ERROR: cannot chdir into $(distuninstallcheck_dir)' >&2; \ exit 1; \ }; \ test `$(am__distuninstallcheck_listfiles) | wc -l` -eq 0 \ || { echo "ERROR: files left after uninstall:" ; \ if test -n "$(DESTDIR)"; then \ echo " (check DESTDIR support)"; \ fi ; \ $(distuninstallcheck_listfiles) ; \ exit 1; } >&2 distcleancheck: distclean @if test '$(srcdir)' = . ; then \ echo "ERROR: distcleancheck can only run from a VPATH build" ; \ exit 1 ; \ fi @test `$(distcleancheck_listfiles) | wc -l` -eq 0 \ || { echo "ERROR: files left in build directory after distclean:" ; \ $(distcleancheck_listfiles) ; \ exit 1; } >&2 check-am: all-am $(MAKE) $(AM_MAKEFLAGS) $(check_PROGRAMS) $(MAKE) $(AM_MAKEFLAGS) check-TESTS check: $(BUILT_SOURCES) $(MAKE) $(AM_MAKEFLAGS) check-am all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(SCRIPTS) $(MESSAGES) \ $(DATA) $(HEADERS) config.h all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(SCRIPTS) $(MESSAGES) \ $(DATA) $(HEADERS) config.h installdirs: for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(includedir)" "$(DESTDIR)$(pkgdatadir)" "$(DESTDIR)$(starnewsdir)" $(DESTDIR)$(stardocsdir) "$(DESTDIR)$(starfacsdir)" "$(DESTDIR)$(includedir)" "$(DESTDIR)$(includedir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install-exec: install-exec-am install-data: install-data-am uninstall: uninstall-am # If STAR_MANIFEST_DIR is defined and the MANIFEST variable has the # (default) string value 'false', then invoke the install-manifest # target, otherwise, do the real install rule. This means that if # this is being invoked from within an install-manifest rule further # up the process tree, we don't create another manifest, which would # stomp on the original. # # Any Makefile which does special installations should check the # $(MANIFEST) variable, which will be ':' or 'false', and if it is # true, emit a line to stdout, consisting of the string 'MANIFEST:' # followed by the full path of the file being installed. install: $(BUILT_SOURCES) $(MAKE) $(AM_MAKEFLAGS) all-am if test -n "$(STAR_MANIFEST_DIR)" -a $(MANIFEST) = false; then \ $(MAKE) $(AM_MAKEFLAGS) install-manifest; \ else \ $(MAKE) $(AM_MAKEFLAGS) $(REAL_INSTALL); \ fi install-manifest: $(mkdir_p) $(DESTDIR)$(STAR_MANIFEST_DIR) MFX=$${TMPDIR-/tmp}/manifest-$$$$-1; rm -f $$MFX; MF_INST_OK=:; \ { $(MAKE) MANIFEST=: $(REAL_INSTALL) \ || MF_INST_OK=false; } \ | tee $$MFX | grep -v '^MANIFEST:' || :; \ if $$MF_INST_OK; then \ MF=$${TMPDIR-/tmp}/manifest-$$$$-2; rm -f $$MF; \ ( echo ""; \ echo ""; \ echo ""; \ echo "$(PACKAGE_VERSION)"; \ echo ""; \ sed -n 's/^MANIFEST://p;' $$MFX; \ echo ""; \ echo ""; \ ) >$$MF; \ $(INSTALL_DATA) $$MF $(DESTDIR)$(STAR_MANIFEST_DIR)/$(PACKAGE); \ else \ echo "Installation of component $(DESTDIR)$(STAR_MANIFEST_DIR)/$(PACKAGE) failed" >&2; \ fi; \ rm -f $$MFX $$MF; \ $$MF_INST_OK install-am: all-am @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am installcheck: installcheck-am install-strip: if test -z '$(STRIP)'; then \ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ install; \ else \ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ fi mostlyclean-generic: -test -z "$(TEST_LOGS)" || rm -f $(TEST_LOGS) -test -z "$(TEST_LOGS:.log=.trs)" || rm -f $(TEST_LOGS:.log=.trs) -test -z "$(TEST_SUITE_LOG)" || rm -f $(TEST_SUITE_LOG) clean-generic: -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) -rm -f cminpack/$(DEPDIR)/$(am__dirstamp) -rm -f cminpack/$(am__dirstamp) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." -rm -f AST_ERR -rm -f ast_err.h -rm -f configure.log -rm -f fac_1521_err -rm -f make.log -rm -f starconf.status -test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES) -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) clean: clean-am clean-am: clean-checkPROGRAMS clean-generic clean-libLTLIBRARIES \ clean-libtool clean-noinstPROGRAMS mostlyclean-am distclean: distclean-am -rm -f $(am__CONFIG_DISTCLEAN_FILES) -rm -rf ./$(DEPDIR) cminpack/$(DEPDIR) -rm -f Makefile distclean-am: clean-am distclean-compile distclean-generic \ distclean-hdr distclean-libtool distclean-tags dvi: dvi-am dvi-am: html: html-am html-am: info: info-am info-am: install-data-am: install-dist_pkgdataDATA install-dist_starnewsDATA \ install-includeHEADERS install-includeMESSAGES \ install-nodist_includeHEADERS install-stardocsDATA \ install-starfacsDATA install-dvi: install-dvi-am install-dvi-am: install-exec-am: install-binSCRIPTS install-dist_binSCRIPTS \ install-libLTLIBRARIES @$(NORMAL_INSTALL) $(MAKE) $(AM_MAKEFLAGS) install-exec-hook install-html: install-html-am install-html-am: install-info: install-info-am install-info-am: install-man: install-pdf: install-pdf-am install-pdf-am: install-ps: install-ps-am install-ps-am: installcheck-am: maintainer-clean: maintainer-clean-am -rm -f $(am__CONFIG_DISTCLEAN_FILES) -rm -rf $(top_srcdir)/autom4te.cache -rm -rf ./$(DEPDIR) cminpack/$(DEPDIR) -rm -f Makefile maintainer-clean-am: distclean-am maintainer-clean-generic mostlyclean: mostlyclean-am mostlyclean-am: mostlyclean-compile mostlyclean-generic \ mostlyclean-libtool pdf: pdf-am pdf-am: ps: ps-am ps-am: uninstall-am: uninstall-binSCRIPTS uninstall-dist_binSCRIPTS \ uninstall-dist_pkgdataDATA uninstall-dist_starnewsDATA \ uninstall-includeHEADERS uninstall-includeMESSAGES \ uninstall-libLTLIBRARIES uninstall-nodist_includeHEADERS \ uninstall-stardocsDATA uninstall-starfacsDATA .MAKE: all check check-am install install-am install-exec-am \ install-strip .PHONY: CTAGS GTAGS TAGS all all-am am--refresh check check-TESTS \ check-am clean clean-checkPROGRAMS clean-cscope clean-generic \ clean-libLTLIBRARIES clean-libtool clean-noinstPROGRAMS cscope \ cscopelist-am ctags ctags-am dist dist-all dist-bzip2 \ dist-gzip dist-hook dist-lzip dist-shar dist-tarZ dist-xz \ dist-zip distcheck distclean distclean-compile \ distclean-generic distclean-hdr distclean-libtool \ distclean-tags distcleancheck distdir distuninstallcheck dvi \ dvi-am html html-am info info-am install install-am \ install-binSCRIPTS install-data install-data-am \ install-dist_binSCRIPTS install-dist_pkgdataDATA \ install-dist_starnewsDATA install-dvi install-dvi-am \ install-exec install-exec-am install-exec-hook install-html \ install-html-am install-includeHEADERS install-includeMESSAGES \ install-info install-info-am install-libLTLIBRARIES \ install-man install-manifest install-nodist_includeHEADERS \ install-pdf install-pdf-am install-ps install-ps-am \ install-stardocsDATA install-starfacsDATA install-strip \ installcheck installcheck-am installdirs maintainer-clean \ maintainer-clean-generic mostlyclean mostlyclean-compile \ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ recheck tags tags-am uninstall uninstall-am \ uninstall-binSCRIPTS uninstall-dist_binSCRIPTS \ uninstall-dist_pkgdataDATA uninstall-dist_starnewsDATA \ uninstall-includeHEADERS uninstall-includeMESSAGES \ uninstall-libLTLIBRARIES uninstall-nodist_includeHEADERS \ uninstall-stardocsDATA uninstall-starfacsDATA AST_PAR: ast_par.source astbad sed -e 's//'`./astbad AST__BAD | tr 'E' 'D'`'/' \ -e 's//'`./astbad AST__NAN | tr 'E' 'D'`'/' \ -e 's//'`./astbad AST__NANF | tr 'E' 'D'`'/' \ ast_par.source >$@ # ast.h depends on the error-facility files. ast.h _could_ be made # before distribution, but since it's generated from other distributed # files, it's more robust to distribute makeh and make ast.h on the # build host. ast.h: $(AST_H_FILES) ast_err.h makeh config.h @PERL@ ./makeh -s $(srcdir) $(AST_H_FILES) >$@ # Form a second link to the main object library (static and shared). This # is used when a second pass through the library is needed during linking # to resolve references made within other AST libraries (e.g. the grf # modules, etc), to functions defined within libast (e.g. memory management # and error reporting functions). Do not forget to change the contents of # the libast_pass2.la file to refer to libast_pass2.* rather than libast.*. # Use target install-exec-hook rather than install-exec-local so that the # soft links and files are created *after* the main library has been # installed. install-exec-hook: libast.la $(mkdir_p) $(DESTDIR)$(libdir) cd $(DESTDIR)$(libdir); \ for f in `ls libast.*`; do \ ff=`echo $$f | sed -e 's/libast/libast_pass2/'`; \ if test -f "$$ff"; then rm "$$ff"; fi; \ $(LN_S) $$f $$ff; \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(libdir)/$$ff" || :; \ done; \ if test -f "libast.la"; then \ if test -f "libast_pass2.la"; then rm "libast_pass2.la"; fi; \ sed -e 's/libast\./libast_pass2\./g' libast.la > libast_pass2.la; \ fi @PREDIST@version.h: version.h.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) version.h.in >$@ @PREDIST@builddocs: builddocs.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) builddocs.in >$@; chmod +x $@ @PREDIST@addversion: addversion.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) addversion.in >$@; chmod +x $@ # Documentation @PREDIST@$(PAPER_DOCUMENTATION): sun211_figures builddocs addversion @PREDIST@ ./builddocs # The contents of the sun211_figures directory is identical to that # sun210_figures sun211_figures: sun210_figures $(LN_S) sun210_figures sun211_figures # Need to include latex support files in the distribution tar ball so # that the docs can be built from the tex source files. Requires environment # variable STARLATEXSUPPORT to be deined. Is there a better way to do this? dist-hook: cp -p $(STARLATEXSUPPORT)/starlink.cls $(distdir)/ cp -p $(STARLATEXSUPPORT)/starabbrev.sty $(distdir)/ cp -p $(STARLATEXSUPPORT)/starstyle.sty $(distdir)/ cp -p $(STARLATEXSUPPORT)/sst.sty $(distdir)/ # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: ast-8.3.0/version.h0000664000175000017500000000431613004147574011103 00000000000000#if !defined( VERSION_INCLUDED ) #define VERSION_INCLUDED 1 /* *+ * Name: * version.h * Purpose: * Declare version numbers * Description: * Defines macros which expand to the components of the AST version * number, namely the major and minor version numbers, and the * release number. The version number as a string is available by * including the file config.h, which defines macros PACKAGE_STRING, * PACKAGE_VERSION and (equivalently to the latter) VERSION. * * For example, the version string `3.2.1' corresponds to major version * 3, minor version 2, release 1. * Macros defined: * AST__VMAJOR * The AST major version number * AST__VMINOR * The AST minor version number * AST__RELEASE * The AST release number * * For backwards compatibility, this module also declares macros * AST_MAJOR_VERS, AST_MINOR_VERS and AST_RELEASE. The AST__* * macros should be used in preference to these, since the latter * use (non-standard) single underscores. * 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 * . * Authors: * NG: Norman Gray (Starlink) * History: * 25-NOV-2003 (NG): * Original version *- */ /* The current version of AST is 8.3.0 */ #define AST__VMAJOR 8 #define AST__VMINOR 3 #define AST__RELEASE 0 /* Deprecated macros */ #define AST_MAJOR_VERS 8 #define AST_MINOR_VERS 3 #define AST_RELEASE 0 #endif /* #if ! defined(VERSION_INCLUDED) */ ast-8.3.0/specmap.c0000664000175000017500000050107013004147321011026 00000000000000/* *class++ * Name: * SpecMap * Purpose: * Sequence of spectral coordinate conversions. * Constructor Function: c astSpecMap (also see astSpecAdd) f AST_SPECMAP (also see AST_SPECADD) * Description: * A SpecMap is a specialised form of Mapping which can be used to * represent a sequence of conversions between standard spectral * coordinate systems. * * When an SpecMap is first created, it simply performs a unit c (null) Mapping. Using the astSpecAdd f (null) Mapping. Using the AST_SPECADD c function, a series of coordinate conversion steps may then be f routine, a series of coordinate conversion steps may then be * added. This allows multi-step conversions between a variety of * spectral coordinate systems to be assembled out of a set of building * blocks. * * Conversions are available to transform between standards of rest. * Such conversions need to know the source position as an RA and DEC. * This information can be supplied in the form of parameters for * the relevant conversions, in which case the SpecMap is 1-dimensional, * simply transforming the spectral axis values. This means that the * same source position will always be used by the SpecMap. However, this * may not be appropriate for an accurate description of a 3-D spectral * cube, where changes of spatial position can produce significant * changes in the Doppler shift introduced when transforming between * standards of rest. For this situation, a 3-dimensional SpecMap can * be created in which axes 2 and 3 correspond to the source RA and DEC * The SpecMap simply copies values for axes 2 and 3 from input to * output), but modifies axis 1 values (the spectral axis) appropriately. * * For details of the individual coordinate conversions available, c see the description of the astSpecAdd function. f see the description of the AST_SPECADD routine. * Inheritance: * The SpecMap class inherits from the Mapping class. * Attributes: * The SpecMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c In addition to those functions applicable to all Mappings, the c following function may also be applied to all SpecMaps: f In addition to those routines applicable to all Mappings, the f following routine may also be applied to all SpecMaps: * c - astSpecAdd: Add a spectral coordinate conversion to an SpecMap f - AST_SPECADD: Add a spectral coordinate conversion to an SpecMap * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 6-NOV-2002 (DSB): * Original version. * 14-JUL-2003 (DSB): * Added checks for NAN values produced by transformation functions. * 17-SEP-2003 (DSB): * - Improve FRTOAW accuracy by iterating. * - Changed Refrac to use algorithm given in FITS-WCS paper 3 * version dated 21/9/03. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 10-MAY-2006 (DSB): * Override astEqual. * 15-NOV-2006 (DSB): * Guard against division by zero when converting freq to wave in * SystemChange. * 18-JUN-2009 (DSB): * Add OBSALT argument to TPF2HL and HLF2TP conversions. * Change GEOLON/LAT to OBSLON/LAT for consistency with other * classes. * 2-OCT-2012 (DSB): * Check for Infs as well as NaNs. *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 SpecMap /* Codes to identify spectral coordinate conversions. */ #define AST__SPEC_NULL 0 /* Null value */ #define AST__FRTOVL 1 /* Frequency to relativistic velocity */ #define AST__VLTOFR 2 /* Relativistic velocity to Frequency */ #define AST__ENTOFR 3 /* Energy to frequency */ #define AST__FRTOEN 4 /* Frequency to energy */ #define AST__WNTOFR 5 /* Wave number to frequency */ #define AST__FRTOWN 6 /* Frequency to wave number */ #define AST__WVTOFR 7 /* Wavelength (vacuum) to frequency */ #define AST__FRTOWV 8 /* Frequency to wavelength (vacuum) */ #define AST__AWTOFR 9 /* Wavelength (air) to frequency */ #define AST__FRTOAW 10 /* Frequency to wavelength (air) */ #define AST__VRTOVL 11 /* Radio to relativistic velocity */ #define AST__VLTOVR 12 /* Relativistic to radio velocity */ #define AST__VOTOVL 13 /* Optical to relativistic velocity */ #define AST__VLTOVO 14 /* Relativistic to optical velocity */ #define AST__ZOTOVL 15 /* Redshift to relativistic velocity */ #define AST__VLTOZO 16 /* Relativistic velocity to redshift */ #define AST__BTTOVL 17 /* Beta factor to relativistic velocity */ #define AST__VLTOBT 18 /* Relativistic velocity to beta factor */ #define AST__USF2HL 19 /* User-defined to heliocentric frequency */ #define AST__HLF2US 20 /* Heliocentric to user-defined frequency */ #define AST__TPF2HL 21 /* Topocentric to heliocentric frequency */ #define AST__HLF2TP 22 /* Heliocentric to topocentric frequency */ #define AST__GEF2HL 23 /* Geocentric to heliocentric frequency */ #define AST__HLF2GE 24 /* Heliocentric to geocentric frequency */ #define AST__BYF2HL 25 /* Barycentric to heliocentric frequency */ #define AST__HLF2BY 26 /* Heliocentric to barycentric frequency */ #define AST__LKF2HL 27 /* LSRK to heliocentric frequency */ #define AST__HLF2LK 28 /* Heliocentric to LSRK frequency */ #define AST__LDF2HL 29 /* LSRD to heliocentric frequency */ #define AST__HLF2LD 30 /* Heliocentric to LSRD frequency */ #define AST__LGF2HL 31 /* Local group to heliocentric frequency */ #define AST__HLF2LG 32 /* Heliocentric to local group frequency */ #define AST__GLF2HL 33 /* Galactic to heliocentric frequency */ #define AST__HLF2GL 34 /* Heliocentric to galactic frequency */ /* Maximum number of arguments required by a conversion. */ #define MAX_ARGS 7 /* The alphabet (used for generating keywords for arguments). */ #define ALPHABET "abcdefghijklmnopqrstuvwxyz" /* Angle conversion */ #define PI 3.141592653589793238462643 #define PIBY2 (PI/2.0) #define D2R (PI/180.0) #define R2D (180.0/PI) /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "pal.h" /* SLALIB interface */ #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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "unitmap.h" /* Unit (null) Mappings */ #include "specmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double (* parent_rate)( AstMapping *, double *, int, int, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SpecMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SpecMap,Class_Init) #define class_vtab astGLOBAL(SpecMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSpecMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* Structure to hold parameters and intermediate values describing a reference frame */ typedef struct FrameDef { double obsalt; /* Observers geodetic altitude (m) */ double obslat; /* Observers geodetic latitude (rads) */ double obslon; /* Observers geodetic longitude (rads, +ve east) */ double epoch; /* Julian epoch of observation */ double refdec; /* RA of reference point (FK5 J2000) */ double refra; /* DEC of reference point (FK5 J2000) */ double veluser; /* Heliocentric velocity of user-defined system (m/s) */ double last; /* Local apparent sideral time */ double amprms[21]; /* Mean to apparent parameters */ double vuser[3]; /* Used-defined velocity as a FK5 J2000 vector */ double dvh[3]; /* Earth-sun velocity */ double dvb[3]; /* Barycentre-sun velocity */ } FrameDef; /* External 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. */ AstSpecMap *astSpecMapId_( int, int, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *CvtString( int, const char **, int *, int *, int *, int *, const char *[ MAX_ARGS ], int * ); static double BaryVel( double, double, FrameDef *, int * ); static double GalVel( double, double, FrameDef *, int * ); static double GeoVel( double, double, FrameDef *, int * ); static double LgVel( double, double, FrameDef *, int * ); static double LsrdVel( double, double, FrameDef *, int * ); static double LsrkVel( double, double, FrameDef *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static double Refrac( double, int * ); static double Rverot( double, double, double, double, double, int * ); static double TopoVel( double, double, FrameDef *, int * ); static double UserVel( double, double, FrameDef *, int * ); static int CvtCode( const char *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int FrameChange( int, int, double *, double *, double *, double *, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int SystemChange( int, int, double *, double *, int, int * ); static void AddSpecCvt( AstSpecMap *, int, const double *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void SpecAdd( AstSpecMap *, const char *, const double[], int * ); static int GetObjSize( AstObject *, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two SpecMaps are equivalent. * Type: * Private function. * Synopsis: * #include "specmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * SpecMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two SpecMaps are equivalent. * Parameters: * this * Pointer to the first Object (a SpecMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the SpecMaps are equivalent, zero otherwise. * 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: */ AstSpecMap *that; AstSpecMap *this; const char *argdesc[ MAX_ARGS ]; const char *comment; int argdec; int argra; int i, j; int nargs; int nin; int nout; int result; int szargs; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two SpecMap structures. */ this = (AstSpecMap *) this_object; that = (AstSpecMap *) that_object; /* Check the second object is a SpecMap. We know the first is a SpecMap since we have arrived at this implementation of the virtual function. */ if( astIsASpecMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two SpecMaps differ, it may still be possible for them to be equivalent. First compare the SpecMaps if their Invert flags are the same. In this case all the attributes of the two SpecMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { if( this->ncvt == that->ncvt ) { result = 1; for( i = 0; i < this->ncvt && result; i++ ) { if( this->cvttype[ i ] != that->cvttype[ i ] ) { result = 0; } else { CvtString( this->cvttype[ i ], &comment, &argra, &argdec, &nargs, &szargs, argdesc, status ); for( j = 0; j < nargs; j++ ) { if( !astEQUAL( this->cvtargs[ i ][ j ], that->cvtargs[ i ][ j ] ) ){ result = 0; break; } } } } } /* If the Invert flags for the two SpecMaps differ, the attributes of the two SpecMaps must be inversely related to each other. */ } else { /* In the specific case of a SpecMap, Invert flags must be equal. */ result = 0; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "specmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SpecMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SpecMap, * in bytes. * Parameters: * this * Pointer to the SpecMap. * 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: */ AstSpecMap *this; /* Pointer to SpecMap structure */ int result; /* Result value to return */ int cvt; /* Loop counter for coordinate conversions */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SpecMap structure. */ this = (AstSpecMap *) 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 ( cvt = 0; cvt < this->ncvt; cvt++ ) { result += astTSizeOf( this->cvtargs[ cvt ] ); } result += astTSizeOf( this->cvtargs ); result += astTSizeOf( this->cvttype ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void AddSpecCvt( AstSpecMap *this, int cvttype, const double *args, int *status ) { /* * Name: * AddSpecCvt * Purpose: * Add a coordinate conversion step to an SpecMap. * Type: * Private function. * Synopsis: * #include "specmap.h" * void AddSpecCvt( AstSpecMap *this, int cvttype, const double *args ) * Class Membership: * SpecMap member function. * Description: * This function allows one of the supported spectral coordinate * conversions to be appended to a SpecMap. When a SpecMap is first * created (using astSpecMap), it simply performs a unit mapping. By * using AddSpecCvt repeatedly, a series of coordinate conversions may * then be specified which the SpecMap will subsequently perform in * sequence. This allows a complex coordinate conversion to be * assembled out of the basic building blocks. The SpecMap will also * perform the inverse coordinate conversion (applying the individual * conversion steps in reverse) if required. * Parameters: * this * Pointer to the SpecMap. * cvttype * A code to identify which spectral coordinate conversion is to be * appended. See the "Coordinate Conversions" section for details * of those available. * args * Pointer to an array of double containing the argument values * required to fully specify the required coordinate * conversion. The number of arguments depends on the conversion * (see the "Coordinate Conversions" section for details). This * value is ignored and may be NULL if no arguments are required. * Returned Value: * void. * Coordinate Conversions: * The following values may be supplied for the "cvttype" parameter * in order to specify the coordinate conversion to be performed. * The argument(s) required to fully specify each conversion are * indicated in parentheses after each value, and described at the end * of the list. Values for these should be given in the array pointed * at by "args". * * AST__FRTOVL( RF ) * Convert frequency to relativistic velocity. * AST__VLTOFR( RF ) * Convert relativistic velocity to Frequency. * AST__ENTOFR * Convert energy to frequency. * AST__FRTOEN * Convert frequency to energy. * AST__WNTOFR * Convert wave number to frequency. * AST__FRTOWN * Convert frequency to wave number. * AST__WVTOFR * Convert wavelength (vacuum) to frequency. * AST__FRTOWV * Convert frequency to wavelength (vacuum). * AST__AWTOFR * Convert wavelength (air) to frequency. * AST__FRTOAW * Convert frequency to wavelength (air). * AST__VRTOVL * Convert radio to relativistic velocity. * AST__VLTOVR * Convert relativistic to radio velocity. * AST__VOTOVL * Convert optical to relativistic velocity. * AST__VLTOVO * Convert relativistic to optical velocity. * AST__ZOTOVL * Convert redshift to relativistic velocity. * AST__VLTOZO * Convert relativistic velocity to redshift. * AST__BTTOVL * Convert beta factor to relativistic velocity. * AST__VLTOBT * Convert relativistic velocity to beta factor. * AST_USF2HL( VOFF, RA, DEC ) * Convert frequency from a user-defined reference frame to * heliocentric. * AST__HLF2US( VOFF, RA, DEC ) * Convert frequency from heliocentric reference frame to * user-defined. * AST__TPF2HL( OBSLON, OBSLAT, OBSALT, EPOCH, RA, DEC ) * Convert from Topocentric to heliocentric frequency * AST__HLF2TP( OBSLON, OBSLAT, OBSALT, EPOCH, RA, DEC ) * Convert from Heliocentric to topocentric frequency. * AST__GEF2HL( EPOCH, RA, DEC ) * Convert from Geocentric to heliocentric frequency. * AST__HLF2GE( EPOCH, RA, DEC ) * Convert from Heliocentric to geocentric frequency. * AST__BYF2HL( EPOCH, RA, DEC ) * Convert from Barycentric to heliocentric frequency. * AST__HLF2BY( EPOCH, RA, DEC ) * Convert from Heliocentric to barycentric frequency. * AST__LKF2HL( RA, DEC ) * Convert from LSRK to heliocentric frequency. * AST__HLF2LK( RA, DEC ) * Convert from Heliocentric to LSRK frequency. * AST__LDF2HL( RA, DEC ) * Convert from LSRD to heliocentric frequency. * AST__HLF2LD( RA, DEC ) * Convert from Heliocentric to LSRD frequency. * AST__LGF2HL( RA, DEC ) * Convert from Local group to heliocentric frequency. * AST__HLF2LG( RA, DEC ) * Convert from Heliocentric to local group frequency. * AST__GLF2HL( RA, DEC ) * Convert from Galactic to heliocentric frequency. * AST__HLF2GL( RA, DEC ) * Convert from Heliocentric to galactic frequency. * * The units for the values processed by the above conversions are as * follows: * * - all velocities: metres per second. * - frequency: Hertz. * - all wavelengths: metres. * - energy: Joules. * - wave number: cycles per metre. * * The arguments used in the above conversions are as follows: * * - RF: Rest frequency (Hz). * - OBSALT: Geodetic altitude of observer (IAU 1975, metres). * - OBSLAT: Geodetic latitude of observer (IAU 1975, radians). * - OBSLON: Longitude of observer (radians, positive eastwards). * - EPOCH: Epoch of observation (UT1 expressed as a Modified Julian Date). * - RA: Right Ascension of source (radians, FK5 J2000). * - DEC: Declination of source (radians, FK5 J2000). * - VOFF: Velocity of the user-defined reference frame, towards the * position given by RA and DEC, measured in the heliocentric * reference frame. * * If the SpecMap is 3-dimensional, source positions are provided by the * values supplied to inputs 2 and 3 of the SpecMap (which are simply * copied to outputs 2 and 3). Note, usable values are still required * for the RA and DEC arguments in order to define the "user-defined" * reference frame used by USF2HL and HLF2US. However, AST__BAD can be * supplied for RA and DEC if the user-defined reference frame is not * required. * Notes: * - The specified conversion is appended only if the SpecMap's * Invert attribute is zero. If it is non-zero, this function * effectively prefixes the inverse of the conversion specified * instead. */ /* Local Variables: */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ const char *cvt_string; /* Pointer to conversion type string */ int argdec; /* Index of DEC argument */ int argra; /* Index of RA argument */ int i; /* Argument index */ int nargs; /* Number of user-supplied arguments */ int ncvt; /* Number of coordinate conversions */ int szargs; /* Size of arguments array */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the coordinate conversion type and obtain the number of required user-supplied arguments, and the size of the array in which to put the user-supplied arguments (the array meay leave room after the user-supplied arguments for various useful pre-calculated values). */ cvt_string = CvtString( cvttype, &comment, &argra, &argdec, &nargs, &szargs, argdesc, status ); /* If the coordinate conversion type was not valid, then report an error. */ if ( astOK && !cvt_string ) { astError( AST__SPCIN, "AddSpecCvt(%s): Invalid spectral coordinate " "conversion type (%d).", status, astGetClass( this ), (int) cvttype ); } /* Note the number of coordinate conversions already stored in the SpecMap. */ if ( astOK ) { ncvt = this->ncvt; /* Extend the array of conversion types and the array of pointers to their argument lists to accommodate the new one. */ this->cvttype = (int *) astGrow( this->cvttype, ncvt + 1, sizeof( int ) ); this->cvtargs = (double **) astGrow( this->cvtargs, ncvt + 1, sizeof( double * ) ); /* If OK, allocate memory and store a copy of the argument list, putting a pointer to the copy into the SpecMap. */ if ( astOK ) { this->cvtargs[ ncvt ] = astStore( NULL, args, sizeof( double ) * (size_t) szargs ); } /* Store the conversion type and increment the conversion count. Also put AST__BAD in any elements of the argument array which are beyond the end of the user-supplied arguments. These will be used to hold intermediate values calculated on the basis of the user-supplied arguments. */ if ( astOK ) { this->cvttype[ ncvt ] = cvttype; this->ncvt++; for( i = nargs; i < szargs; i++ ) this->cvtargs[ ncvt ][ i ] = AST__BAD; } } } static double BaryVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * BaryVel * Purpose: * Find the velocity of the earth-sun barycentre away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double BaryVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the earth-sun * barycentre away from a specified source position, at a given epoch, in * the frame of rest of the centre of the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Local Variables: */ double dpb[ 3 ]; /* Barycentric earth position vector */ double dph[ 3 ]; /* Heliocentric earth position vector */ double dvh[ 3 ]; /* Heliocentric earth velocity vector */ double v[ 3 ]; /* Source direction vector */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the Cartesian vector towards the source, in the Cartesian FK5 J2000 system. */ palDcs2c( ra, dec, v ); /* If not already done so, get the Earth/Sun velocity and position vectors in the same system. Speed is returned in units of AU/s. Store in the supplied frame definition structure. */ if( def->dvb[ 0 ] == AST__BAD ) { palEvp( def->epoch, 2000.0, def->dvb, dpb, dvh, dph ); /* Change the barycentric velocity of the earth into the heliocentric velocity of the barycentre. */ def->dvb[ 0 ] = dvh[ 0 ] - def->dvb[ 0 ]; def->dvb[ 1 ] = dvh[ 1 ] - def->dvb[ 1 ]; def->dvb[ 2 ] = dvh[ 2 ] - def->dvb[ 2 ]; } /* Return the component away from the source, of the velocity of the barycentre relative to the sun (in m/s). */ return -palDvdv( v, def->dvb )*149.597870E9; } static int CvtCode( const char *cvt_string, int *status ) { /* * Name: * CvtCode * Purpose: * Convert a conversion type from a string representation to a code value. * Type: * Private function. * Synopsis: * #include "specmap.h" * int CvtCode( const char *cvt_string, int *status ) * Class Membership: * SpecMap member function. * Description: * This function accepts a string used to repersent one of the * SpecMap coordinate conversions and converts it into a code * value for internal use. * Parameters: * cvt_string * Pointer to a constant null-terminated string representing a * spectral coordinate conversion. This is case sensitive and should * contain no unnecessary white space. * status * Pointer to the inherited status variable. * Returned Value: * The equivalent conversion code. If the string was not * recognised, the code AST__SPEC_NULL is returned, without error. * Notes: * - A value of AST__SPEC_NULL will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ int result; /* Result value to return */ /* Initialise. */ result = AST__SPEC_NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Test the string against each recognised value in turn and assign the result. */ if ( astChrMatch( cvt_string, "FRTOVL" ) ) { result = AST__FRTOVL; } else if ( astChrMatch( cvt_string, "VLTOFR" ) ) { result = AST__VLTOFR; } else if ( astChrMatch( cvt_string, "VLTOFR" ) ) { result = AST__VLTOFR; } else if ( astChrMatch( cvt_string, "ENTOFR" ) ) { result = AST__ENTOFR; } else if ( astChrMatch( cvt_string, "FRTOEN" ) ) { result = AST__FRTOEN; } else if ( astChrMatch( cvt_string, "WNTOFR" ) ) { result = AST__WNTOFR; } else if ( astChrMatch( cvt_string, "FRTOWN" ) ) { result = AST__FRTOWN; } else if ( astChrMatch( cvt_string, "WVTOFR" ) ) { result = AST__WVTOFR; } else if ( astChrMatch( cvt_string, "FRTOWV" ) ) { result = AST__FRTOWV; } else if ( astChrMatch( cvt_string, "AWTOFR" ) ) { result = AST__AWTOFR; } else if ( astChrMatch( cvt_string, "FRTOAW" ) ) { result = AST__FRTOAW; } else if ( astChrMatch( cvt_string, "VRTOVL" ) ) { result = AST__VRTOVL; } else if ( astChrMatch( cvt_string, "VLTOVR" ) ) { result = AST__VLTOVR; } else if ( astChrMatch( cvt_string, "VOTOVL" ) ) { result = AST__VOTOVL; } else if ( astChrMatch( cvt_string, "VLTOVO" ) ) { result = AST__VLTOVO; } else if ( astChrMatch( cvt_string, "ZOTOVL" ) ) { result = AST__ZOTOVL; } else if ( astChrMatch( cvt_string, "VLTOZO" ) ) { result = AST__VLTOZO; } else if ( astChrMatch( cvt_string, "BTTOVL" ) ) { result = AST__BTTOVL; } else if ( astChrMatch( cvt_string, "VLTOBT" ) ) { result = AST__VLTOBT; } else if ( astChrMatch( cvt_string, "USF2HL" ) ) { result = AST__USF2HL; } else if ( astChrMatch( cvt_string, "HLF2US" ) ) { result = AST__HLF2US; } else if ( astChrMatch( cvt_string, "TPF2HL" ) ) { result = AST__TPF2HL; } else if ( astChrMatch( cvt_string, "HLF2TP" ) ) { result = AST__HLF2TP; } else if ( astChrMatch( cvt_string, "GEF2HL" ) ) { result = AST__GEF2HL; } else if ( astChrMatch( cvt_string, "HLF2GE" ) ) { result = AST__HLF2GE; } else if ( astChrMatch( cvt_string, "BYF2HL" ) ) { result = AST__BYF2HL; } else if ( astChrMatch( cvt_string, "HLF2BY" ) ) { result = AST__HLF2BY; } else if ( astChrMatch( cvt_string, "LKF2HL" ) ) { result = AST__LKF2HL; } else if ( astChrMatch( cvt_string, "HLF2LK" ) ) { result = AST__HLF2LK; } else if ( astChrMatch( cvt_string, "LDF2HL" ) ) { result = AST__LDF2HL; } else if ( astChrMatch( cvt_string, "HLF2LD" ) ) { result = AST__HLF2LD; } else if ( astChrMatch( cvt_string, "LGF2HL" ) ) { result = AST__LGF2HL; } else if ( astChrMatch( cvt_string, "HLF2LG" ) ) { result = AST__HLF2LG; } else if ( astChrMatch( cvt_string, "GLF2HL" ) ) { result = AST__GLF2HL; } else if ( astChrMatch( cvt_string, "HLF2GL" ) ) { result = AST__HLF2GL; } /* Return the result. */ return result; } static const char *CvtString( int cvt_code, const char **comment, int *argra, int *argdec, int *nargs, int *szargs, const char *arg[ MAX_ARGS ], int *status ) { /* * Name: * CvtString * Purpose: * Convert a conversion type from a code value to a string representation. * Type: * Private function. * Synopsis: * #include "specmap.h" * const char *CvtString( int cvt_code, const char **comment, * int *argra, int *argdec, int *nargs, * int *szargs, const char *arg[ MAX_ARGS ], int *status ) * Class Membership: * SpecMap member function. * Description: * This function accepts a code value used to represent one of the * SpecMap coordinate conversions and converts it into an * equivalent string representation. It also returns a descriptive * comment and information about the arguments required in order to * perform the conversion. * Parameters: * cvt_code * The conversion code. * comment * Address of a location to return a pointer to a constant * null-terminated string containing a description of the * conversion. * argra * Address of an int in which to return the index of the argument * corresponding to the source RA. Returned equal to -1 if the * conversion does not have a source RA argument. * argdec * Address of an int in which to return the index of the argument * corresponding to the source DEC. Returned equal to -1 if the * conversion does not have a source DEC argument. * nargs * Address of an int in which to return the number of arguments * required from the user in order to perform the conversion (may * be zero). * szargs * Address of an int in which to return the number of arguments * associated with the conversion. This may be bigger than "nargs" * if the conversion can pre-calculate useful values on the basis * of the user-supplied values. Such precalculated values are * stored after the last user-supplied argument. * arg * An array in which to return a pointer to a constant * null-terminated string for each argument (above) containing a * description of what each argument represents. This includes both * user-supplied arguments and pre-calculated values. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated string representation of * the conversion code value supplied. If the code supplied is not * valid, a NULL pointer will be returned, without error. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Result pointer to return */ /* Initialise the returned values. */ *comment = NULL; *nargs = 0; *argra = -1; *argdec = -1; result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Test for each valid code value in turn and assign the appropriate return values. */ switch ( cvt_code ) { case AST__FRTOVL: *comment = "Convert frequency to rel. velocity"; result = "FRTOVL"; *nargs = 1; *szargs = 1; arg[ 0 ] = "Rest frequency (Hz)"; break; case AST__VLTOFR: *comment = "Convert rel. velocity to frequency"; result = "VLTOFR"; *nargs = 1; *szargs = 1; arg[ 0 ] = "Rest frequency (Hz)"; break; case AST__ENTOFR: *comment = "Convert energy to frequency"; result = "ENTOFR"; *nargs = 0; *szargs = 0; break; case AST__FRTOEN: *comment = "Convert frequency to energy"; result = "FRTOEN"; *nargs = 0; *szargs = 0; break; case AST__WNTOFR: *comment = "Convert wave number to frequency"; result = "WNTOFR"; *nargs = 0; *szargs = 0; break; case AST__FRTOWN: *comment = "Convert frequency to wave number"; result = "FRTOWN"; *nargs = 0; *szargs = 0; break; case AST__WVTOFR: *comment = "Convert wavelength (vacuum) to frequency"; result = "WVTOFR"; *nargs = 0; *szargs = 0; break; case AST__FRTOWV: *comment = "Convert frequency to wavelength (vacuum)"; result = "FRTOWV"; *nargs = 0; *szargs = 0; break; case AST__AWTOFR: *comment = "Convert wavelength (air) to frequency"; result = "AWTOFR"; *nargs = 0; *szargs = 0; break; case AST__FRTOAW: *comment = "Convert frequency to wavelength (air)"; result = "FRTOAW"; *nargs = 0; *szargs = 0; break; case AST__VRTOVL: *comment = "Convert radio to rel. velocity"; result = "VRTOVL"; *nargs = 0; *szargs = 0; break; case AST__VLTOVR: *comment = "Convert relativistic to radio velocity"; result = "VLTOVR"; *nargs = 0; *szargs = 0; break; case AST__VOTOVL: *comment = "Convert optical to rel. velocity"; result = "VOTOVL"; *nargs = 0; *szargs = 0; break; case AST__VLTOVO: *comment = "Convert relativistic to optical velocity"; result = "VLTOVO"; *nargs = 0; *szargs = 0; break; case AST__ZOTOVL: *comment = "Convert redshift to rel. velocity"; result = "ZOTOVL"; *nargs = 0; *szargs = 0; break; case AST__VLTOZO: *comment = "Convert rel. velocity to redshift"; result = "VLTOZO"; *nargs = 0; *szargs = 0; break; case AST__BTTOVL: *comment = "Convert beta factor to rel. velocity"; result = "BTTOVL"; *nargs = 0; *szargs = 0; break; case AST__VLTOBT: *comment = "Convert rel. velocity to beta factor"; result = "VLTOBT"; *nargs = 0; *szargs = 0; break; case AST__USF2HL: *comment = "Convert from user-defined to heliocentric frequency"; result = "USF2HL"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "Velocity offset (m/s)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__HLF2US: *comment = "Convert from heliocentric to user-defined frequency"; result = "HLF2US"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "Velocity offset (m/s)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__TPF2HL: *comment = "Convert from Topocentric to heliocentric frequency"; result = "TPF2HL"; *argra = 4; *argdec = 5; *nargs = 6; *szargs = 7; arg[ 0 ] = "Longitude (positive eastwards, radians)"; arg[ 1 ] = "Latitude (geodetic, radians)"; arg[ 2 ] = "Altitude (geodetic, metres)"; arg[ 3 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 4 ] = "RA of source (FK5 J2000, radians)"; arg[ 5 ] = "DEC of source (FK5 J2000, radians)"; arg[ 6 ] = "Frequency correction factor"; break; case AST__HLF2TP: *comment = "Convert from Heliocentric to topocentric frequency"; result = "HLF2TP"; *argra = 4; *argdec = 5; *nargs = 6; *szargs = 7; arg[ 0 ] = "Longitude (positive eastwards, radians)"; arg[ 1 ] = "Latitude (geodetic, radians)"; arg[ 2 ] = "Altitude (geodetic, metres)"; arg[ 3 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 4 ] = "RA of source (FK5 J2000, radians)"; arg[ 5 ] = "DEC of source (FK5 J2000, radians)"; arg[ 6 ] = "Frequency correction factor"; break; case AST__GEF2HL: *comment = "Convert from Geocentric to heliocentric frequency"; result = "GEF2HL"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__HLF2GE: *comment = "Convert from Heliocentric to geocentric frequency"; result = "HLF2GE"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__BYF2HL: *comment = "Convert from Barycentric to heliocentric frequency"; result = "BYF2HL"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__HLF2BY: *comment = "Convert from Heliocentric to barycentric frequency"; result = "HLF2BY"; *argra = 1; *argdec = 2; *nargs = 3; *szargs = 4; arg[ 0 ] = "UT1 epoch of observaton (Modified Julian Date)"; arg[ 1 ] = "RA of source (FK5 J2000, radians)"; arg[ 2 ] = "DEC of source (FK5 J2000, radians)"; arg[ 3 ] = "Frequency correction factor"; break; case AST__LKF2HL: *comment = "Convert from LSRK to heliocentric frequency"; result = "LKF2HL"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__HLF2LK: *comment = "Convert from Heliocentric to LSRK frequency"; result = "HLF2LK"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__LDF2HL: *comment = "Convert from LSRD to heliocentric frequency"; result = "LDF2HL"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__HLF2LD: *comment = "Convert from Heliocentric to LSRD frequency"; result = "HLF2LD"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__LGF2HL: *comment = "Convert from Local group to heliocentric frequency"; result = "LGF2HL"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__HLF2LG: *comment = "Convert from Heliocentric to local group frequency"; result = "HLF2LG"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__GLF2HL: *comment = "Convert from Galactic to heliocentric frequency"; result = "GLF2HL"; *argra = 0; *argdec = 1; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; case AST__HLF2GL: *comment = "Convert from Heliocentric to galactic frequency"; *argra = 0; *argdec = 1; result = "HLF2GL"; *nargs = 2; *szargs = 3; arg[ 0 ] = "RA of source (FK5 J2000, radians)"; arg[ 1 ] = "DEC of source (FK5 J2000, radians)"; arg[ 2 ] = "Frequency correction factor"; break; } /* Return the result. */ return result; } static int FrameChange( int cvt_code, int np, double *ra, double *dec, double *freq, double *args, int forward, int *status ){ /* * Name: * FrameChange * Purpose: * Apply a doppler shift caused by a change of reference frame. * Type: * Private function. * Synopsis: * #include "specmap.h" * int FrameChange( int cvt_code, int np, double *ra, double *dec, * double *freq, double *args, int forward, int *status ) * Class Membership: * SpecMap method. * Description: * This function modifies the supplied frequency values in order to * apply a doppler shift caused by a change of the observers rest-frame. * Parameters: * cvt_code * A code indicating the conversion to be applied. If the code does * not correspond to a change of rest-frame, then the supplied * frequencies are left unchanged and zero is returned as the * function value. * np * The number of frequency values to transform. * ra * Pointer to an array of "np" RA (J2000 FK5) values at which the * "np" frequencies are observed. These are unchanged on exit. If a * NULL pointer is supplied, then all frequencies are assumed to be * observed at the single RA value given by "refra" * dec * Pointer to an array of "np" Dec (J2000 FK5) values at which the * "np" frequencies are observed. These are unchanged on exit. If a * NULL pointer is supplied, then all frequencies are assumed to be * observed at the single Dec value given by "refdec" * freq * Pointer to an array of "np" frequency values, measured in the * input rest-frame. These are modified on return to hold the * corresponding values measured in the output rest-frame. * args * Pointer to an array holding the conversion arguments. The number * of arguments expected depends on the particular conversion being * used. * forward * Should the conversion be applied in the forward or inverse * direction? Non-zero for forward, zero for inverse. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the supplied conversion code corresponds to a change of * reference frame. Zoer otherwise (in which case the upplied values * will not have been changed). * Notes: * - The "args" array contains RA and DEC values which give the "source" * position (FK5 J2000). If a NULL value is supplied for the "ra" * parameter, then these args define the position of all the frequency * values. In addition they also define the direction of motion of * the "user-defined" rest-frame (see "veluser"). Thus they should still * be supplied even if "ra" is NULL. */ /* Local Variables: */ FrameDef def; /* Structure holding frame parameters */ double (* cvtFunc)( double, double, FrameDef *, int * ); /* Pointer to conversion function */ double *fcorr; /* Pointer to frequency correction factor */ double *pdec; /* Pointer to next Dec value */ double *pf; /* Pointer to next frequency value */ double *pra; /* Pointer to next RA value */ double factor; /* Frequency correction factor */ double s; /* Velocity correction (m/s) */ int i; /* Loop index */ int result; /* Returned value */ int sign; /* Sign for velocity correction */ /* Check inherited status. */ if( !astOK ) return 0; /* Initialise */ cvtFunc = NULL; fcorr = NULL; sign = 0; /* Set the return value to indicate that the supplied conversion code represents a change of rest-frame. */ result = 1; /* Initialise a structure which stores parameters which define the transformation. */ def.obsalt = AST__BAD; def.obslat = AST__BAD; def.obslon = AST__BAD; def.epoch = AST__BAD; def.refdec = AST__BAD; def.refra = AST__BAD; def.veluser = AST__BAD; def.last = AST__BAD; def.amprms[ 0 ] = AST__BAD; def.vuser[ 0 ] = AST__BAD; def.dvh[ 0 ] = AST__BAD; def.dvb[ 0 ] = AST__BAD; /* Test for each rest-frame code value in turn and assign the appropriate values. */ switch ( cvt_code ) { case AST__USF2HL: cvtFunc = UserVel; def.veluser = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = -1; break; case AST__HLF2US: cvtFunc = UserVel; def.veluser = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = +1; break; case AST__TPF2HL: cvtFunc = TopoVel; def.obslon = args[ 0 ]; def.obslat = args[ 1 ]; def.obsalt = args[ 2 ]; def.epoch = args[ 3 ]; def.refra = args[ 4 ]; def.refdec = args[ 5 ]; fcorr = args + 6; sign = -1; break; case AST__HLF2TP: cvtFunc = TopoVel; def.obslon = args[ 0 ]; def.obslat = args[ 1 ]; def.obsalt = args[ 2 ]; def.epoch = args[ 3 ]; def.refra = args[ 4 ]; def.refdec = args[ 5 ]; fcorr = args + 6; sign = +1; break; case AST__GEF2HL: cvtFunc = GeoVel; def.epoch = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = -1; break; case AST__HLF2GE: cvtFunc = GeoVel; def.epoch = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = +1; break; case AST__BYF2HL: cvtFunc = BaryVel; def.epoch = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = -1; break; case AST__HLF2BY: cvtFunc = BaryVel; def.epoch = args[ 0 ]; def.refra = args[ 1 ]; def.refdec = args[ 2 ]; fcorr = args + 3; sign = +1; break; case AST__LKF2HL: cvtFunc = LsrkVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = -1; break; case AST__HLF2LK: cvtFunc = LsrkVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = +1; break; case AST__LDF2HL: cvtFunc = LsrdVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = -1; break; case AST__HLF2LD: cvtFunc = LsrdVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = +1; break; case AST__LGF2HL: cvtFunc = LgVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = -1; break; case AST__HLF2LG: cvtFunc = LgVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = +1; break; case AST__GLF2HL: cvtFunc = GalVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = -1; break; case AST__HLF2GL: cvtFunc = GalVel; def.refra = args[ 0 ]; def.refdec = args[ 1 ]; fcorr = args + 2; sign = +1; break; /* If the supplied code does not represent a change of rest-frame, clear the returned flag. */ default: result = 0; } /* Check we have a rest-frame code. */ if( result ) { /* First deal with cases where we have a single source position (given by refra and refdec). */ if( !ra ) { /* If the frequency correction factor has not been found, find it now. */ if( *fcorr == AST__BAD ) { /* Get the velocity correction. This is the component of the velocity of the output system, away from the source, as measured in the input system. */ s = sign*cvtFunc( def.refra, def.refdec, &def, status ); /* Find the factor by which to correct supplied frequencies. If the velocity correction is positive, the output frequency wil be lower than the input frequency. */ if( s < AST__C && s > -AST__C ) { *fcorr = sqrt( ( AST__C - s )/( AST__C + s ) ); } } /* Correct each supplied frequency. */ if( *fcorr != AST__BAD && *fcorr != 0.0 ) { factor = forward ? *fcorr : 1.0 / ( *fcorr ); pf = freq; for( i = 0; i < np; i++, pf++ ) { if( *pf != AST__BAD ) *pf *= factor; } /* Set returned values bad if the velocity correction is un-physical. */ } else { pf = freq; for( i = 0; i < np; i++ ) *(pf++) = AST__BAD; } /* Now deal with cases where each frequency value has its own source position. */ } else { /* Invert the sign if we are doing a inverse transformation. */ if( !forward ) sign = -sign; /* Loop round each value. */ pf = freq; pra = ra; pdec = dec; for( i = 0; i < np; i++ ) { /* If the ra or dec is bad, store a bad frequency. */ if( *pra == AST__BAD || *pdec == AST__BAD || *pf == AST__BAD ) { *pf = AST__BAD; /* Otherwise, produce a corrected frequency. */ } else { /* Get the velocity correction. */ s = sign*cvtFunc( *pra, *pdec, &def, status ); /* Correct this frequency, if possible. Otherwise set bad. */ if( s < AST__C && s > -AST__C ) { *pf *= sqrt( ( AST__C - s )/( AST__C + s ) ); } else { *pf = AST__BAD; } } /* Move on to the next position. */ pf++; pra++; pdec++; } } } /* Return the result. */ return result; } static double GalVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * GalVel * Purpose: * Find the velocity of the galactic centre away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double GalVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the galactic * centre away from a specified source position, in the frame of rest * of the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Local Variables: */ double s1, s2; /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the component away from the source, of the velocity of the sun relative to the dynamic LSR (in km/s). */ s1 = (double) palRvlsrd( (float) ra, (float) dec ); /* Get the component away from the source, of the velocity of the dynamic LSR relative to the galactic centre (in km/s). */ s2 = (double) palRvgalc( (float) ra, (float) dec ); /* Return the total velocity of the galactic centre away from the source, relative to the sun, in m/s. */ return -1000.0*( s1 + s2 ); } static double GeoVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * GeoVel * Purpose: * Find the velocity of the earth away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double GeoVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the earth away * from a specified source position, at a given epoch, in the frame of * rest of the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Local Variables: */ double dpb[ 3 ]; /* Barycentric earth position vector */ double dph[ 3 ]; /* Heliocentric earth position vector */ double dvb[ 3 ]; /* Barycentric earth velocity vector */ double v[ 3 ]; /* Source direction vector */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the Cartesian vector towards the source, in the Cartesian FK5 J2000 system. */ palDcs2c( ra, dec, v ); /* If not already done so, get the Earth/Sun velocity and position vectors in the same system. Speed is returned in units of AU/s. Store in the supplied frame definition structure. */ if( def->dvh[ 0 ] == AST__BAD ) palEvp( def->epoch, 2000.0, dvb, dpb, def->dvh, dph ); /* Return the component away from the source, of the velocity of the earths centre relative to the sun (in m/s). */ return -palDvdv( v, def->dvh )*149.597870E9; } void astInitSpecMapVtab_( AstSpecMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSpecMapVtab * Purpose: * Initialise a virtual function table for a SpecMap. * Type: * Protected function. * Synopsis: * #include "specmap.h" * void astInitSpecMapVtab( AstSpecMapVtab *vtab, const char *name ) * Class Membership: * SpecMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SpecMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsASpecMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->SpecAdd = SpecAdd; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_rate = mapping->Rate; mapping->Rate = Rate; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "SpecMap", "Conversion between spectral 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 double LgVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * LgVel * Purpose: * Find the velocity of the Local Group away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double LgVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the Local Group velocity away * from a specified source position, in the frame of rest of the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Return the component away from the source, of the velocity of the local group relative to the sun (in m/s). */ return -1000.0*palRvlg( (float) ra, (float) dec ); } static double LsrdVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * LsrdVel * Purpose: * Find the velocity of the Dynamical LSR away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double LsrdVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the Dynamical * LSR away from a specified source position, in the frame of rest of * the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the component away from the source, of the velocity of the sun relative to the dynamical LSR (in m/s). This can also be thought of as the velocity of the LSR towards the source relative to the sun. Return the negated value (i.e. velocity of lsrd *away from* the source. */ return -1000.0*palRvlsrd( (float) ra, (float) dec ); } static double LsrkVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * LsrkVel * Purpose: * Find the velocity of the Kinematic LSR away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double LsrkVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the Kinematic * LSR away from a specified source position, in the frame of rest of * the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the component away from the source, of the velocity of the sun relative to the kinematic LSR (in m/s). This can also be thought of as the velocity of the LSR towards the source relative to the sun. Return the negated value (i.e. velocity of lsrk *away from* the source. */ return -1000.0*palRvlsrk( (float) ra, (float) dec ); } static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a SpecMap. * Type: * Private function. * Synopsis: * #include "mapping.h * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * SpecMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated SpecMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated SpecMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated SpecMap which is to be merged with * its neighbours. This should be a cloned copy of the SpecMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * SpecMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated SpecMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *new; /* Pointer to replacement Mapping */ AstSpecMap *specmap; /* Pointer to SpecMap */ const char *argdesc[ MAX_ARGS ]; /* Argument descriptions (junk) */ const char *class; /* Pointer to Mapping class string */ const char *comment; /* Pointer to comment string (junk) */ double (*cvtargs)[ MAX_ARGS ]; /* Pointer to argument arrays */ double tmp; /* Temporary storage */ int *cvttype; /* Pointer to transformation type codes */ int *szarg; /* Pointer to argument count array */ int argdec; /* Index of DEC argument */ int argra; /* Index of RA argument */ int done; /* Finished (no further simplification)? */ int iarg; /* Loop counter for arguments */ int icvt1; /* Loop initial value */ int icvt2; /* Loop final value */ int icvt; /* Loop counter for transformation steps */ int ikeep; /* Index to store step being kept */ int imap1; /* Index of first SpecMap to merge */ int imap2; /* Index of last SpecMap to merge */ int imap; /* Loop counter for Mappings */ int inc; /* Increment for transformation step loop */ int invert; /* SpecMap applied in inverse direction? */ int istep; /* Loop counter for transformation steps */ int keep; /* Keep transformation step? */ int narg; /* Number of user-supplied arguments */ int ngone; /* Number of Mappings eliminated */ int nin; /* Numbr of axes for SpecMaps being merged */ int nstep0; /* Original number of transformation steps */ int nstep; /* Total number of transformation steps */ int result; /* Result value to return */ int simpler; /* Simplification possible? */ int unit; /* Replacement Mapping is a UnitMap? */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* SpecMaps can only be merged if they are in series (or if there is only one Mapping present, in which case it makes no difference), so do nothing if they are not. */ if ( series || ( *nmap == 1 ) ) { /* Save the number of inputs for the SpecMap. */ nin = astGetNin( this ); /* Initialise the number of transformation steps to be merged to equal the number in the nominated SpecMap. */ nstep = ( (AstSpecMap *) ( *map_list )[ where ] )->ncvt; /* Search adjacent lower-numbered Mappings until one is found which is not a SpecMap, or is a SpecMap with a different number of axes. Accumulate the number of transformation steps involved in any SpecMaps found. */ imap1 = where; while ( ( imap1 - 1 >= 0 ) && astOK ) { class = astGetClass( ( *map_list )[ imap1 - 1 ] ); if ( !astOK || strcmp( class, "SpecMap" ) || astGetNin( ( *map_list )[ imap1 - 1 ] ) != nin ) break; nstep += ( (AstSpecMap *) ( *map_list )[ imap1 - 1 ] )->ncvt; imap1--; } /* Similarly search adjacent higher-numbered Mappings. */ imap2 = where; while ( ( imap2 + 1 < *nmap ) && astOK ) { class = astGetClass( ( *map_list )[ imap2 + 1 ] ); if ( !astOK || strcmp( class, "SpecMap" ) || astGetNin( ( *map_list )[ imap2 + 1 ] ) != nin ) break; nstep += ( (AstSpecMap *) ( *map_list )[ imap2 + 1 ] )->ncvt; imap2++; } /* Remember the initial number of transformation steps. */ nstep0 = nstep; /* Allocate memory for accumulating a list of all the transformation steps involved in all the SpecMaps found. */ cvttype = astMalloc( sizeof( int ) * (size_t) nstep ); cvtargs = astMalloc( sizeof( double[ MAX_ARGS ] ) * (size_t) nstep ); szarg = astMalloc( sizeof( int ) * (size_t) nstep ); /* Loop to obtain the transformation data for each SpecMap being merged. */ nstep = 0; for ( imap = imap1; astOK && ( imap <= imap2 ); imap++ ) { /* Obtain a pointer to the SpecMap and note if it is being applied in its inverse direction. */ specmap = (AstSpecMap *) ( *map_list )[ imap ]; invert = ( *invert_list )[ imap ]; /* Set up loop limits and an increment to scan the transformation steps in each SpecMap in either the forward or reverse direction, as dictated by the associated "invert" value. */ icvt1 = invert ? specmap->ncvt - 1 : 0; icvt2 = invert ? -1 : specmap->ncvt; inc = invert ? -1 : 1; /* Loop through each transformation step in the SpecMap. */ for ( icvt = icvt1; icvt != icvt2; icvt += inc ) { /* Store the transformation type code and use "CvtString" to determine the associated number of arguments. Then store these arguments. */ cvttype[ nstep ] = specmap->cvttype[ icvt ]; (void) CvtString( cvttype[ nstep ], &comment, &argra, &argdec, &narg, szarg + nstep, argdesc, status ); if ( !astOK ) break; for ( iarg = 0; iarg < szarg[ nstep ]; iarg++ ) { cvtargs[ nstep ][ iarg ] = specmap->cvtargs[ icvt ][ iarg ]; } /* If the SpecMap is inverted, we must not only accumulate its transformation steps in reverse, but also apply them in reverse. For some steps this means changing arguments, for some it means changing the transformation type code to a complementary value, and for others it means both. Define macros to perform each of the required changes. */ /* Macro to exchange a transformation type code for its inverse (and vice versa). */ #define SWAP_CODES( code1, code2 ) \ if ( cvttype[ nstep ] == code1 ) { \ cvttype[ nstep ] = code2; \ } else if ( cvttype[ nstep ] == code2 ) { \ cvttype[ nstep ] = code1; \ } /* Macro to exchange a transformation type code for its inverse (and vice versa), and reciprocate a specified argument. */ #define SWAP_CODES2( code1, code2, jarg ) \ if ( cvttype[ nstep ] == code1 ) { \ cvttype[ nstep ] = code2; \ tmp = cvtargs[ nstep ][ jarg ]; \ if( tmp != AST__BAD && tmp != 0.0 ) { \ cvtargs[ nstep ][ jarg ] = 1.0/tmp; \ } else { \ cvtargs[ nstep ][ jarg ] = AST__BAD; \ } \ } else if ( cvttype[ nstep ] == code2 ) { \ cvttype[ nstep ] = code1; \ tmp = cvtargs[ nstep ][ jarg ]; \ if( tmp != AST__BAD && tmp != 0.0 ) { \ cvtargs[ nstep ][ jarg ] = 1.0/tmp; \ } else { \ cvtargs[ nstep ][ jarg ] = AST__BAD; \ } \ } /* Macro to exchange a transformation type code for its inverse (and vice versa), and negate a specified argument. */ #define SWAP_CODES3( code1, code2, jarg ) \ if ( cvttype[ nstep ] == code1 ) { \ cvttype[ nstep ] = code2; \ tmp = cvtargs[ nstep ][ jarg ]; \ if( tmp != AST__BAD ) { \ cvtargs[ nstep ][ jarg ] = -tmp; \ } \ } else if ( cvttype[ nstep ] == code2 ) { \ cvttype[ nstep ] = code1; \ tmp = cvtargs[ nstep ][ jarg ]; \ if( tmp != AST__BAD ) { \ cvtargs[ nstep ][ jarg ] = -tmp; \ } \ } /* Use these macros to apply the changes where needed. */ if ( invert ) { /* Exchange transformation codes for their inverses. */ SWAP_CODES( AST__FRTOVL, AST__VLTOFR ) SWAP_CODES( AST__ENTOFR, AST__FRTOEN ) SWAP_CODES( AST__WNTOFR, AST__FRTOWN ) SWAP_CODES( AST__WVTOFR, AST__FRTOWV ) SWAP_CODES( AST__AWTOFR, AST__FRTOAW ) SWAP_CODES( AST__VRTOVL, AST__VLTOVR ) SWAP_CODES( AST__VOTOVL, AST__VLTOVO ) SWAP_CODES( AST__ZOTOVL, AST__VLTOZO ) SWAP_CODES( AST__BTTOVL, AST__VLTOBT ) /* Exchange transformation codes for their inverses, and reciprocate the frequency correction factor. */ SWAP_CODES2( AST__TPF2HL, AST__HLF2TP, 6 ) SWAP_CODES2( AST__USF2HL, AST__HLF2US, 3 ) SWAP_CODES2( AST__GEF2HL, AST__HLF2GE, 3 ) SWAP_CODES2( AST__BYF2HL, AST__HLF2BY, 3 ) SWAP_CODES2( AST__LKF2HL, AST__HLF2LK, 2 ) SWAP_CODES2( AST__LDF2HL, AST__HLF2LD, 2 ) SWAP_CODES2( AST__LGF2HL, AST__HLF2LG, 2 ) SWAP_CODES2( AST__GLF2HL, AST__HLF2GL, 2 ) } /* Undefine the local macros. */ #undef SWAP_CODES #undef SWAP_CODES2 #undef SWAP_CODES3 /* Count the transformation steps. */ nstep++; } } /* Loop to simplify the sequence of transformation steps until no further improvement is possible. */ done = 0; while ( astOK && !done ) { /* Examine each remaining transformation step in turn. */ ikeep = -1; for ( istep = 0; istep < nstep; istep++ ) { /* Initially assume we will retain the current step. */ keep = 1; /* The only simplifications for the conversions currently in this class act to combine adjacent transformation steps, so only apply them while there are at least 2 steps left. */ if ( istep < ( nstep - 1 ) ) { /* Define a macro to test if two adjacent transformation type codes have specified values. */ #define PAIR_CVT( code1, code2 ) \ ( ( cvttype[ istep ] == code1 ) && \ ( cvttype[ istep + 1 ] == code2 ) ) /* Define a macro to test if two adjacent transformation type codes have specified values, either way round. */ #define PAIR_CVT2( code1, code2 ) \ ( ( PAIR_CVT( code1, code2 ) ) || \ ( PAIR_CVT( code2, code1 ) ) ) /* If a correction is followed by its inverse, and the user-supplied argument values are unchanged (we do not need to test values stored in the argument array which were not supplied by the user), we can eliminate them. First check for conversions which have no user-supplied arguments. */ if ( PAIR_CVT2( AST__ENTOFR, AST__FRTOEN ) || PAIR_CVT2( AST__WNTOFR, AST__FRTOWN ) || PAIR_CVT2( AST__WVTOFR, AST__FRTOWV ) || PAIR_CVT2( AST__AWTOFR, AST__FRTOAW ) || PAIR_CVT2( AST__VRTOVL, AST__VLTOVR ) || PAIR_CVT2( AST__VOTOVL, AST__VLTOVO ) || PAIR_CVT2( AST__ZOTOVL, AST__VLTOZO ) || PAIR_CVT2( AST__BTTOVL, AST__VLTOBT ) ) { istep++; keep = 0; /* Now check for conversions which have a single user-supplied argument. */ } else if( PAIR_CVT2( AST__FRTOVL, AST__VLTOFR ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) ) { istep++; keep = 0; /* Now check for conversions which have two user-supplied arguments. */ } else if( ( PAIR_CVT2( AST__LKF2HL, AST__HLF2LK ) || PAIR_CVT2( AST__LDF2HL, AST__HLF2LD ) || PAIR_CVT2( AST__LGF2HL, AST__HLF2LG ) || PAIR_CVT2( AST__GLF2HL, AST__HLF2GL ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 1 ] ) ) { istep++; keep = 0; /* Now check for conversions which have three user-supplied arguments. */ } else if( ( PAIR_CVT2( AST__GEF2HL, AST__HLF2GE ) || PAIR_CVT2( AST__BYF2HL, AST__HLF2BY ) || PAIR_CVT2( AST__USF2HL, AST__HLF2US ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 1 ] ) && astEQUAL( cvtargs[ istep ][ 2 ], cvtargs[ istep + 1 ][ 2 ] ) ) { istep++; keep = 0; /* Now check for conversions which have six user-supplied arguments (currently no conversions have four or five user-supplied arguments). */ } else if( ( PAIR_CVT2( AST__TPF2HL, AST__HLF2TP ) ) && astEQUAL( cvtargs[ istep ][ 0 ], cvtargs[ istep + 1 ][ 0 ] ) && astEQUAL( cvtargs[ istep ][ 1 ], cvtargs[ istep + 1 ][ 1 ] ) && astEQUAL( cvtargs[ istep ][ 2 ], cvtargs[ istep + 1 ][ 2 ] ) && astEQUAL( cvtargs[ istep ][ 3 ], cvtargs[ istep + 1 ][ 3 ] ) && astEQUAL( cvtargs[ istep ][ 4 ], cvtargs[ istep + 1 ][ 4 ] ) && astEQUAL( cvtargs[ istep ][ 5 ], cvtargs[ istep + 1 ][ 5 ] ) ) { istep++; keep = 0; } /* Undefine the local macros. */ #undef PAIR_CVT #undef PAIR_CVT2 } /* If the current transformation (possibly modified above) is being kept, then increment the index that identifies its new location in the list of transformation steps. */ if ( keep ) { ikeep++; /* If the new location is different to its current location, copy the transformation data into the new location. */ if ( ikeep != istep ) { cvttype[ ikeep ] = cvttype[ istep ]; for ( iarg = 0; iarg < szarg[ istep ]; iarg++ ) { cvtargs[ ikeep ][ iarg ] = cvtargs[ istep ][ iarg ]; } szarg[ ikeep ] = szarg[ istep ]; } } } /* Note if no simplification was achieved on this iteration (i.e. the number of transformation steps was not reduced). This is the signal to quit. */ done = ( ( ikeep + 1 ) >= nstep ); /* Note how many transformation steps now remain. */ nstep = ikeep + 1; } /* Determine how many Mappings can be eliminated by condensing all those considered above into a single Mapping. */ if ( astOK ) { ngone = imap2 - imap1; /* Determine if the replacement Mapping can be a UnitMap (a null Mapping). This will only be the case if all the transformation steps were eliminated above. */ unit = ( nstep == 0 ); /* Determine if simplification is possible. This will be the case if (a) Mappings were eliminated ("ngone" is non-zero), or (b) the number of transformation steps was reduced, or (c) the SpecMap(s) can be replaced by a UnitMap, or (d) if there was initially only one SpecMap present, its invert flag was set (this flag will always be cleared in the replacement Mapping). */ simpler = ngone || ( nstep < nstep0 ) || unit || ( *invert_list )[ where ]; /* Do nothing more unless simplification is possible. */ if ( simpler ) { /* If the replacement Mapping is a UnitMap, then create it. */ if ( unit ) { new = (AstMapping *) astUnitMap( astGetNin( ( *map_list )[ where ] ), "", status ); /* Otherwise, create a replacement SpecMap and add each of the remaining transformation steps to it. */ } else { new = (AstMapping *) astSpecMap( nin, 0, "", status ); for ( istep = 0; istep < nstep; istep++ ) { AddSpecCvt( (AstSpecMap *) new, cvttype[ istep ], cvtargs[ istep ], status ); } } /* Annul the pointers to the Mappings being eliminated. */ if ( astOK ) { for ( imap = imap1; imap <= imap2; imap++ ) { ( *map_list )[ imap ] = astAnnul( ( *map_list )[ imap ] ); } /* Insert the pointer and invert value for the new Mapping. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Move any subsequent Mapping information down to close the gap. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - ngone ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - ngone ] = ( *invert_list )[ imap ]; } /* Blank out any information remaining at the end of the arrays. */ for ( imap = ( *nmap - ngone ); imap < *nmap; imap++ ) { ( *map_list )[ imap ] = NULL; ( *invert_list )[ imap ] = 0; } /* Decrement the Mapping count and return the index of the first Mapping which was eliminated. */ ( *nmap ) -= ngone; result = imap1; /* If an error occurred, annul the new Mapping pointer. */ } else { new = astAnnul( new ); } } } /* Free the memory used for the transformation steps. */ cvttype = astFree( cvttype ); cvtargs = astFree( cvtargs ); szarg = astFree( szarg ); } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static double Rate( AstMapping *this, 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 "specmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * SpecMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. * Implementation Deficiencies: * The initial version of this implementation only deals with * frequency->wavelength conversions. This is because the slowness of * the numerical differentiation implemented by the astRate method in * the parent Mapping class is cripples conversion between SpecFluxFrames. * Such conversions only rely on rate of change of wavelength with * respect to frequency. This implementation should be extended when * needed. */ /* Local Variables: */ AstSpecMap *map; double result; int cvt; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the SpecMap structure. */ map = (AstSpecMap *) this; /* Return 1.0 if the SpecMap has no conversions. */ if( map->ncvt == 0 ) return 1.0; /* Store the type of the first conversion.*/ cvt = map->cvttype[ 0 ]; /* If this is a 3D SpecMap or if it has more than one component, or if that conversion is not between frequency and wavelength, use the astRate method inherited form the parent Mapping class. */ if( astGetNin( map ) != 1 || map->ncvt != 1 || ( cvt != AST__WVTOFR && cvt != AST__FRTOWV ) ) { result = (*parent_rate)( this, at, ax1, ax2, status ); /* Otherwise, evaluate the known analytical expressions for the rate of change of frequency with respect to wavelength or wavelength with respect to frequency. */ } else { result = ( *at != AST__BAD ) ? -AST__C/((*at)*(*at)) : AST__BAD; } /* Return the result. */ return result; } static double Refrac( double wavelen, int *status ){ /* * Name: * Refrac * Purpose: * Returns the refractive index of dry air at a given wavelength. * Type: * Private function. * Synopsis: * #include "specmap.h" * double Refrac( double wavelen, int *status ) * Class Membership: * SpecMap method. * Description: * This function returns the refractive index of dry air at standard * temperature and pressure, at a given wavelength. The formula is * taken from the paper "Representation of Spectral Coordinates in FITS" * (Greisen et al). * Parameters: * wavelen * The wavelength, in metres. This should be the air wavelength, * but supplying the vacuum wavelength will make no significant * difference. * status * Pointer to the inherited status variable. * Returned Value: * The refractive index. A value of 1.0 is returned if an error * occurs, or has already occurred. */ /* Local Variables: */ double w2; /* Wavenumber squared */ /* Check the global error status. */ if ( !astOK || wavelen == 0.0 ) return 1.0; /* Find the squared wave number in units of "(per um)**2". */ w2 = 1.0E-12/( wavelen * wavelen ); /* Apply the rest of the algorithm as described in the FITS WCS paper III. */ return 1.0 + 1.0E-6*( 287.6155 + 1.62887*w2 + 0.01360*w2*w2 ); } static double Rverot( double phi, double h, double ra, double da, double st, int *status ) { /* * Name: * Rverot * Purpose: * Find the velocity component in a given direction due to Earth rotation. * Type: * Private function. * Synopsis: * #include "specmap.h" * double Rverot( double phi, double h, double ra, double da, * double st, int *status ) * Class Membership: * SpecMap method. * Description: * This function is like slaRverot, except that it takes account of the * observers height (h), and does all calculations in double precision. * Parameters: * phi * The geodetic latitude of the observer (radians, IAU 1976). * h * The geodetic height above the reference spheroid of the observer * (metres, IAU 1976). * ra * The geocentric apparent RA (rads) of the source. * da * The geocentric apparent Dec (rads) of the source. * st * The local apparent sidereal time (radians). * status * Pointer to the inherited status variable. * Returns: * The component of the Earth rotation in direction [RA,DA] (km/s). * The result is positive when the observer is receding from the * given point on the sky. Zero is returned if an error has already * occurred. */ /* Local Variables: */ double pv[ 6 ]; /* Observer position and velocity */ double v[ 3 ]; /* Source direction vector */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Get the Cartesian coordinates of the unit vector pointing towards the given sky position. */ palDcs2c( ra, da, v ); /* Get velocity and position of the observer. */ palPvobs( phi, h, st, pv ); /* Return the component of the observer's velocity away from the sky position, and convert from AU/s to km/s. */ return -palDvdv( v, pv + 3 )*149.597870E6; } static void SpecAdd( AstSpecMap *this, const char *cvt, const double args[], int *status ) { /* *++ * Name: c astSpecAdd f AST_SPECADD * Purpose: * Add a spectral coordinate conversion to a SpecMap. * Type: * Public virtual function. * Synopsis: c #include "specmap.h" c void astSpecAdd( AstSpecMap *this, const char *cvt, const double args[] ) f CALL AST_SPECADD( THIS, CVT, ARGS, STATUS ) * Class Membership: * SpecMap method. * Description: c This function adds one of the standard spectral coordinate f This routine adds one of the standard spectral coordinate * system conversions listed below to an existing SpecMap. * c When a SpecMap is first created (using astSpecMap), it simply f When a SpecMap is first created (using AST_SPECMAP), it simply c performs a unit (null) Mapping. By using astSpecAdd (repeatedly f performs a unit (null) Mapping. By using AST_SPECADD (repeatedly * if necessary), one or more coordinate conversion steps may then * be added, which the SpecMap will perform in sequence. This allows * multi-step conversions between a variety of spectral coordinate * systems to be assembled out of the building blocks provided by * this class. * * Normally, if a SpecMap's Invert attribute is zero (the default), * then its forward transformation is performed by carrying out * each of the individual coordinate conversions specified by c astSpecAdd in the order given (i.e. with the most recently added f AST_SPECADD in the order given (i.e. with the most recently added * conversion applied last). * * This order is reversed if the SpecMap's Invert attribute is * non-zero (or if the inverse transformation is requested by any * other means) and each individual coordinate conversion is also * replaced by its own inverse. This process inverts the overall * effect of the SpecMap. In this case, the first conversion to be * applied would be the inverse of the one most recently added. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the SpecMap. c cvt f CVT = CHARACTER * ( * ) (Given) c Pointer to a null-terminated string which identifies the f A character string which identifies the * spectral coordinate conversion to be added to the * SpecMap. See the "Available Conversions" section for details of * those available. c args f ARGS( * ) = DOUBLE PRECISION (Given) * An array containing argument values for the spectral * coordinate conversion. The number of arguments required, and * hence the number of array elements used, depends on the * conversion specified (see the "Available Conversions" * section). This array is ignored c and a NULL pointer may be supplied * if no arguments are needed. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - When assembling a multi-stage conversion, it can sometimes be * difficult to determine the most economical conversion path. For * example, when converting between reference frames, converting first * to the heliographic reference frame as an intermediate stage is often * sensible in formulating the problem, but may introduce unnecessary * extra conversion steps. A solution to this is to include all the steps * which are (logically) necessary, but then to use c astSimplify to simplify the resulting f AST_SIMPLIFY to simplify the resulting * SpecMap. The simplification process will eliminate any steps * which turn out not to be needed. c - This function does not check to ensure that the sequence of f - This routine does not check to ensure that the sequence of * coordinate conversions added to a SpecMap is physically * meaningful. * Available Conversions: * The following strings (which are case-insensitive) may be supplied c via the "cvt" parameter to indicate which spectral coordinate f via the CVT argument to indicate which spectral coordinate * conversion is to be added to the SpecMap. Where arguments are needed by * the conversion, they are listed in parentheses. Values for c these arguments should be given, via the "args" array, in the f these arguments should be given, via the ARGS array, in the * order indicated. Units and argument names are described at the end of * the list of conversions. * - "FRTOVL" (RF): Convert frequency to relativistic velocity. * - "VLTOFR" (RF): Convert relativistic velocity to Frequency. * - "ENTOFR": Convert energy to frequency. * - "FRTOEN": Convert frequency to energy. * - "WNTOFR": Convert wave number to frequency. * - "FRTOWN": Convert frequency to wave number. * - "WVTOFR": Convert wavelength (vacuum) to frequency. * - "FRTOWV": Convert frequency to wavelength (vacuum). * - "AWTOFR": Convert wavelength (air) to frequency. * - "FRTOAW": Convert frequency to wavelength (air). * - "VRTOVL": Convert radio to relativistic velocity. * - "VLTOVR": Convert relativistic to radio velocity. * - "VOTOVL": Convert optical to relativistic velocity. * - "VLTOVO": Convert relativistic to optical velocity. * - "ZOTOVL": Convert redshift to relativistic velocity. * - "VLTOZO": Convert relativistic velocity to redshift. * - "BTTOVL": Convert beta factor to relativistic velocity. * - "VLTOBT": Convert relativistic velocity to beta factor. * - "USF2HL" (VOFF,RA,DEC): Convert frequency from a user-defined * reference frame to heliocentric. * - "HLF2US" (VOFF,RA,DEC): Convert frequency from heliocentric * reference frame to user-defined. * - "TPF2HL" (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from * topocentric reference frame to heliocentric. * - "HLF2TP" (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from * heliocentric reference frame to topocentric. * - "GEF2HL" (EPOCH,RA,DEC): Convert frequency from geocentric * reference frame to heliocentric. * - "HLF2GE" (EPOCH,RA,DEC): Convert frequency from * heliocentric reference frame to geocentric. * - "BYF2HL" (EPOCH,RA,DEC): Convert frequency from * barycentric reference frame to heliocentric. * - "HLF2BY" (EPOCH,RA,DEC): Convert frequency from * heliocentric reference frame to barycentric. * - "LKF2HL" (RA,DEC): Convert frequency from kinematic LSR * reference frame to heliocentric. * - "HLF2LK" (RA,DEC): Convert frequency from heliocentric * reference frame to kinematic LSR. * - "LDF2HL" (RA,DEC): Convert frequency from dynamical LSR * reference frame to heliocentric. * - "HLF2LD" (RA,DEC): Convert frequency from heliocentric * reference frame to dynamical LSR. * - "LGF2HL" (RA,DEC): Convert frequency from local group * reference frame to heliocentric. * - "HLF2LG" (RA,DEC): Convert frequency from heliocentric * reference frame to local group. * - "GLF2HL" (RA,DEC): Convert frequency from galactic * reference frame to heliocentric. * - "HLF2GL" (RA,DEC): Convert frequency from heliocentric * reference frame to galactic. * The units for the values processed by the above conversions are as * follows: * * - all velocities: metres per second (positive if the source receeds from * the observer). * - frequency: Hertz. * - all wavelengths: metres. * - energy: Joules. * - wave number: cycles per metre. * * The arguments used in the above conversions are as follows: * * - RF: Rest frequency (Hz). * - OBSALT: Geodetic altitude of observer (IAU 1975, metres). * - OBSLAT: Geodetic latitude of observer (IAU 1975, radians). * - OBSLON: Longitude of observer (radians - positive eastwards). * - EPOCH: Epoch of observation (UT1 expressed as a Modified Julian Date). * - RA: Right Ascension of source (radians, FK5 J2000). * - DEC: Declination of source (radians, FK5 J2000). * - VOFF: Velocity of the user-defined reference frame, towards the * position given by RA and DEC, measured in the heliocentric * reference frame. * * If the SpecMap is 3-dimensional, source positions are provided by the * values supplied to inputs 2 and 3 of the SpecMap (which are simply * copied to outputs 2 and 3). Note, usable values are still required * for the RA and DEC arguments in order to define the "user-defined" * reference frame used by USF2HL and HLF2US. However, AST__BAD can be * supplied for RA and DEC if the user-defined reference frame is not * required. * *-- */ /* Local Variables: */ int cvttype; /* Conversion type code */ /* Check the inherited status. */ if ( !astOK ) return; /* Validate the type string supplied and obtain the equivalent conversion type code. */ cvttype = CvtCode( cvt, status ); /* If the string was not recognised, then report an error. */ if ( astOK && ( cvttype == AST__SPEC_NULL ) ) { astError( AST__SPCIN, "%s(%s): Invalid SpecMap spectral coordinate " "conversion type \"%s\".", status, "astAddSpec", astGetClass( this ), cvt ); } /* Add the new conversion to the SpecMap. */ AddSpecCvt( this, cvttype, args, status ); } static int SystemChange( int cvt_code, int np, double *values, double *args, int forward, int *status ){ /* * Name: * SystemChange * Purpose: * Change values between two spectral systems. * Type: * Private function. * Synopsis: * #include "specmap.h" * int SystemChange( int cvt_code, int np, double *values, double *args, * int forward, int *status ) * Class Membership: * SpecMap method. * Description: * This function modifies the supplied values in order to change the * spectral co-ordinate system (frequency, wavelength, etc) to which * they refer. * Parameters: * cvt_code * A code indicating the conversion to be applied. If the code does * not correspond to a change of system, then the supplied values * are left unchanged and zero is returned as the function value. * np * The number of frequency values to transform. * values * Pointer to an array of "np" spectral values. These are modified on * return to hold the corresponding values measured in the output * system. * args * Pointer to an array holding the conversion arguments. The number * of arguments expected depends on the particular conversion being * used. * forward * Should the conversion be applied in the forward or inverse * direction? Non-zero for forward, zero for inverse. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the supplied conversion code corresponds to a change of * system. Zero otherwise (in which case the upplied values will not * have been changed). */ /* Local Variables: */ double *pv; /* Pointer to next value */ double d; /* Intermediate value */ double f2; /* Squared frequency */ double temp; /* Intermediate value */ int i; /* Loop index */ int iter; /* Iteration count */ int result; /* Returned value */ /* Check inherited status. */ if( !astOK ) return 0; /* Set the return value to indicate that the supplied conversion code represents a change of system. */ result = 1; /* Test for each code value in turn and assign the appropriate values. */ switch ( cvt_code ) { /* Frequency to relativistic velocity. */ case AST__FRTOVL: if( forward ) { if( args[ 0 ] != AST__BAD ) { temp = args[ 0 ] * args[ 0 ]; pv = values - 1; for( i = 0; i < np; i++ ){ pv++; if( *pv != AST__BAD ) { f2 = ( *pv ) * ( *pv ); d = temp + f2; if( d > 0.0 ) { *pv = AST__C*( ( temp - f2 )/d ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } } } else { pv = values; for( i = 0; i < np; i++ ) *( pv++ ) = AST__BAD; } } else { SystemChange( AST__VLTOFR, np, values, args, 1, status ); } break; /* Relativistic velocity to frequency. */ case AST__VLTOFR: if( forward ) { if( args[ 0 ] != AST__BAD ) { temp = args[ 0 ]; pv = values - 1; for( i = 0; i < np; i++ ){ pv++; if( *pv != AST__BAD ) { d = AST__C + ( *pv ); if( d != 0.0 ) { d = ( AST__C - ( *pv ) )/d; if( d >= 0.0 ) { *pv = temp*sqrt( d ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } else { *pv = AST__BAD; } } } } else { pv = values; for( i = 0; i < np; i++ ) *( pv++ ) = AST__BAD; } } else { SystemChange( AST__FRTOVL, np, values, args, 1, status ); } break; /* Energy to frequency */ case AST__ENTOFR: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv /= AST__H; } } } else { SystemChange( AST__FRTOEN, np, values, args, 1, status ); } break; /* Frequency to energy */ case AST__FRTOEN: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv *= AST__H; } } } else { SystemChange( AST__ENTOFR, np, values, args, 1, status ); } break; /* Wave number to frequency */ case AST__WNTOFR: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv *= AST__C; } } } else { SystemChange( AST__FRTOWN, np, values, args, 1, status ); } break; /* Wave number to frequency */ case AST__FRTOWN: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv /= AST__C; } } } else { SystemChange( AST__WNTOFR, np, values, args, 1, status ); } break; /* Wavelength to frequency */ case AST__WVTOFR: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD && *pv != 0.0 ) { *pv = AST__C/( *pv ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } } else { SystemChange( AST__FRTOWV, np, values, args, 1, status ); } break; /* Frequency to wavelength. */ case AST__FRTOWV: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD && *pv != 0.0 ) { *pv = AST__C/( *pv ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } } else { SystemChange( AST__WVTOFR, np, values, args, 1, status ); } break; /* Wavelength in air to frequency. */ case AST__AWTOFR: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD && *pv != 0.0 ) { *pv = AST__C/( ( *pv )*Refrac( *pv, status ) ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } } else { SystemChange( AST__FRTOAW, np, values, args, 1, status ); } break; /* Frequency to wavelength in air. */ case AST__FRTOAW: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD && *pv != 0.0 ) { /* Form the vacuum wavelength. */ temp = AST__C/( *pv ); /* The refractive index function "Refrac" requires the wavelength in air as its parameter. Initially assume that the wavelength in air is equal to the vacuum wavelength to get he first estimate of the wavelength in air. Then use this estimate to get a better refractive index in order to form a better estimate of the air wavelength, etc. Iterate in this way a few times. */ *pv = temp; for( iter = 0; iter < 3; iter++ ) { *pv = temp/Refrac( *pv, status ); if( !astISFINITE( *pv ) ) { *pv = AST__BAD; break; } } } else { *pv = AST__BAD; } } } else { SystemChange( AST__AWTOFR, np, values, args, 1, status ); } break; /* Radio velocity to relativistic velocity */ case AST__VRTOVL: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = 1.0 - ( *pv )/AST__C; temp *= temp; *pv = AST__C*( 1.0 - temp )/( 1.0 + temp ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } } } else { SystemChange( AST__VLTOVR, np, values, args, 1, status ); } break; /* Relativistic velocity to radio velocity. */ case AST__VLTOVR: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = AST__C + ( *pv ); if( temp != 0.0 ) { temp = (AST__C - *pv )/temp; if( temp >= 0.0 ) { *pv = AST__C*( 1.0 - sqrt( temp ) ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } else { *pv = AST__BAD; } } } } else { SystemChange( AST__VRTOVL, np, values, args, 1, status ); } break; /* Optical velocity to relativistic velocity */ case AST__VOTOVL: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = 1.0 + ( *pv )/AST__C; temp *= temp; *pv = AST__C*( temp - 1.0 )/( temp + 1.0 ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } } } else { SystemChange( AST__VLTOVO, np, values, args, 1, status ); } break; /* Relativistic velocity to optical velocity. */ case AST__VLTOVO: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = AST__C - *pv; if( temp != 0.0 ) { temp = (AST__C + *pv )/temp; if( temp >= 0.0 ) { *pv = AST__C*( sqrt( temp ) - 1.0 ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } else { *pv = AST__BAD; } } } } else { SystemChange( AST__VOTOVL, np, values, args, 1, status ); } break; /* Redshift to relativistic velocity */ case AST__ZOTOVL: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = 1.0 + ( *pv ); temp *= temp; *pv = AST__C*( temp - 1.0 )/( temp + 1.0 ); if( !astISFINITE( *pv ) ) *pv = AST__BAD; } } } else { SystemChange( AST__VLTOZO, np, values, args, 1, status ); } break; /* Relativistic velocity to redshift. */ case AST__VLTOZO: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { temp = AST__C - *pv; if( temp != 0.0 ) { temp = (AST__C + *pv )/temp; if( temp >= 0.0 ) { *pv = sqrt( temp ) - 1.0; if( !astISFINITE( *pv ) ) *pv = AST__BAD; } else { *pv = AST__BAD; } } else { *pv = AST__BAD; } } } } else { SystemChange( AST__ZOTOVL, np, values, args, 1, status ); } break; /* Beta factor to relativistic velocity */ case AST__BTTOVL: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv *= AST__C; } } } else { SystemChange( AST__VLTOBT, np, values, args, 1, status ); } break; /* Relativistic velocity to beta factor. */ case AST__VLTOBT: if( forward ) { pv = values - 1; for( i = 0; i < np; i++ ) { pv++; if( *pv != AST__BAD ) { *pv /= AST__C; } } } else { SystemChange( AST__BTTOVL, np, values, args, 1, status ); } break; /* If the supplied code does not represent a change of system, clear the returned flag. */ default: result = 0; } /* Return the result. */ return result; } static double TopoVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * TopoVel * Purpose: * Find the velocity of the observer away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double TopoVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the observer away * from a specified source position, at a given epoch, in the frame of * rest of the Sun. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. */ /* Local Variables: */ double deca; /* Apparent DEC */ double raa; /* Apparent RA */ double vobs; /* Velocity of observer relative to earth */ double vearth; /* Velocity of earth realtive to sun */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* If not already done so, get the parameters defining the transformation of mean ra and dec to apparent ra and dec, and store in the supplied frame definition structure. */ if( def->amprms[ 0 ] == AST__BAD ) palMappa( 2000.0, def->epoch, def->amprms ); /* Convert the source position from mean ra and dec to apparent ra and dec. */ palMapqkz( ra, dec, def->amprms, &raa, &deca ); /* If not already done so, get the local apparent siderial time (in radians) and store in the supplied frame definition structure. */ if( def->last == AST__BAD ) def->last = palGmst( def->epoch ) + palEqeqx( def->epoch ) + def->obslon; /* Get the component away from the source, of the velocity of the observer relative to the centre of the earth (in m/s). */ vobs = 1000.0*Rverot( def->obslat, def->obsalt, raa, deca, def->last, status ); /* Get the component away from the source, of the velocity of the earth's centre relative to the Sun, in m/s. */ vearth = GeoVel( ra, dec, def, status ); /* Return the total velocity of the observer away from the source in the frame of the sun. */ return vobs + vearth; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a SpecMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "specmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * SpecMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a SpecMap and a set of points encapsulated * in a PointSet and transforms the points so as to perform the * sequence of spectral coordinate conversions specified by * previous invocations of astSpecAdd. * Parameters: * this * Pointer to the SpecMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the SpecMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstSpecMap *map; /* Pointer to SpecMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *spec; /* Pointer to output spectral axis value array */ double *alpha; /* Pointer to output RA axis value array */ double *beta; /* Pointer to output DEC axis value array */ int cvt; /* Loop counter for conversions */ int end; /* Termination index for conversion loop */ int inc; /* Increment for conversion loop */ int map3d; /* Is the SpecMap 3-dimensional? */ int ncoord_in; /* Number of coordinates per input point */ int npoint; /* Number of points */ int start; /* Starting index for conversion loop */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SpecMap. */ map = (AstSpecMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the coordinate conversions needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse transformation, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( this ) ) forward = !forward; /* Transform the coordinate values. */ /* -------------------------------- */ /* Use "spec" as a synonym for the array of spectral axis values stored in the output PointSet. */ if ( astOK ) { spec = ptr_out[ 0 ]; /* If this is a 3D SpecMap use "alpha" as a synonym for the array of RA axis values and "beta" as a synonym for the array of DEC axis values stored in the output PointSet. */ map3d = ( ncoord_in == 3 ); if( map3d ) { alpha = ptr_out[ 1 ]; beta = ptr_out[ 2 ]; } else { alpha = NULL; beta = NULL; } /* Initialise the output coordinate values by copying the input ones. */ (void) memcpy( spec, ptr_in[ 0 ], sizeof( double ) * (size_t) npoint ); if( map3d ) { (void) memcpy( alpha, ptr_in[ 1 ], sizeof( double ) * (size_t) npoint ); (void) memcpy( beta, ptr_in[ 2 ], sizeof( double ) * (size_t) npoint ); } /* We will loop to apply each spectral coordinate conversion in turn to the (spec) array. However, if the inverse transformation was requested, we must loop through these transformations in reverse order, so set up appropriate limits and an increment to control this loop. */ start = forward ? 0 : map->ncvt - 1; end = forward ? map->ncvt : -1; inc = forward ? 1 : -1; /* Loop through the coordinate conversions in the required order. */ for ( cvt = start; cvt != end; cvt += inc ) { /* Process conversions which correspond to changes of reference frames. */ if( !FrameChange( map->cvttype[ cvt ], npoint, alpha, beta, spec, map->cvtargs[ cvt ], forward, status ) ) { /* If this conversion was not a change of reference frame, it must be a change of system. */ SystemChange( map->cvttype[ cvt ], npoint, spec, map->cvtargs[ cvt ], forward, status ); } } } /* 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 double UserVel( double ra, double dec, FrameDef *def, int *status ) { /* * Name: * UserVel * Purpose: * Find the component of the velocity of the user-defined rest-frame * away from the source. * Type: * Private function. * Synopsis: * #include "specmap.h" * double UserVel( double ra, double dec, FrameDef *def, int *status ) * Class Membership: * SpecMap method. * Description: * This function finds the component of the velocity of the user-defined * rest-frame away from a specified position. The magnitude and direction * of the rest-frames velocity are defined within the supplied "def" * structure. The user-defined rest-frame is typically used to represent * the velocity of the source within the heliocentric rest-frame. * Parameters: * ra * The RA (rads, FK5 J2000) of the source. * dec * The Dec (rads, FK5 J2000) of the source. * def * Pointer to a FrameDef structure which holds the parameters which * define the frame, together with cached intermediate results. * status * Pointer to the inherited status variable. * Returns: * The component of the frame's velocity away from the position given by * "ra" and "dec", in m/s, measured within the Heliographic frame of * rest. Zero is returned if an error has already occurred. * Notes: * - The direction of the user velocity is given by def->refra and * def->refdec (an FK5 J2000 position). The maginitude of the velocity * is given by def->veluser, in m/s, positive when the source is moving * away from the observer towards def->refra, def->refdec, and given * with respect to the heliocentric rest-frame. */ /* Local Variables: */ double vb[ 3 ]; /* Source position vector */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* If not already done so, express the user velocity in the form of a J2000.0 x,y,z vector. */ if( def->vuser[ 0 ] == AST__BAD ) { def->vuser[ 0 ] = def->veluser*cos( def->refra )*cos( def->refdec ); def->vuser[ 1 ] = def->veluser*sin( def->refra )*cos( def->refdec ); def->vuser[ 2 ] = def->veluser*sin( def->refdec ); } /* Convert given J2000 RA,Dec to x,y,z. */ palDcs2c( ra, dec, vb ); /* Return the dot product with the user velocity. Invert it to get the velocity towards the observer (the def->veluser value is supposed to be positive if the source is moving away from the observer). */ return -palDvdv( def->vuser, vb ); } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SpecMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SpecMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstSpecMap *in; /* Pointer to input SpecMap */ AstSpecMap *out; /* Pointer to output SpecMap */ int cvt; /* Loop counter for coordinate conversions */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SpecMap structures. */ in = (AstSpecMap *) objin; out = (AstSpecMap *) objout; /* For safety, first clear any references to the input memory from the output SpecMap. */ out->cvtargs = NULL; out->cvttype = NULL; /* Allocate memory for the output array of argument list pointers. */ out->cvtargs = astMalloc( sizeof( double * ) * (size_t) in->ncvt ); /* If necessary, allocate memory and make a copy of the input array of coordinate conversion codes. */ if ( in->cvttype ) out->cvttype = astStore( NULL, in->cvttype, sizeof( int ) * (size_t) in->ncvt ); /* If OK, loop through each conversion in the input SpecMap and make a copy of its argument list, storing the new pointer in the output argument list array. */ if ( astOK ) { for ( cvt = 0; cvt < in->ncvt; cvt++ ) { out->cvtargs[ cvt ] = astStore( NULL, in->cvtargs[ cvt ], astSizeOf( in->cvtargs[ cvt ] ) ); } /* If an error occurred while copying the argument lists, loop through the conversions again and clean up by ensuring that the new memory allocated for each argument list is freed. */ if ( !astOK ) { for ( cvt = 0; cvt < in->ncvt; cvt++ ) { out->cvtargs[ cvt ] = astFree( out->cvtargs[ cvt ] ); } } } /* If an error occurred, free all other memory allocated above. */ if ( !astOK ) { out->cvtargs = astFree( out->cvtargs ); out->cvttype = astFree( out->cvttype ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SpecMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SpecMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstSpecMap *this; /* Pointer to SpecMap */ int cvt; /* Loop counter for coordinate conversions */ /* Obtain a pointer to the SpecMap structure. */ this = (AstSpecMap *) obj; /* Loop to free the memory containing the argument list for each coordinate conversion. */ for ( cvt = 0; cvt < this->ncvt; cvt++ ) { this->cvtargs[ cvt ] = astFree( this->cvtargs[ cvt ] ); } /* Free the memory holding the array of conversion types and the array of argument list pointers. */ this->cvtargs = astFree( this->cvtargs ); this->cvttype = astFree( this->cvttype ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SpecMap objects. * Type: * Private function. * Synopsis: * #include "specmap.h" * void Dump( AstObject *this, AstChannel *channel, int *status ) * Description: * This function implements the Dump function which writes out data * for the SpecMap class to an output Channel. * Parameters: * this * Pointer to the SpecMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Local Constants: */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstSpecMap *this; /* Pointer to the SpecMap structure */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ const char *sval; /* Pointer to string value */ int argdec; /* Index of DEC argument */ int argra; /* Index of RA argument */ int iarg; /* Loop counter for arguments */ int icvt; /* Loop counter for conversion steps */ int ival; /* Integer value */ int nargs; /* Number of user-supplied arguments */ int szargs; /* Number of stored arguments */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecMap structure. */ this = (AstSpecMap *) this_object; /* Write out values representing the instance variables for the SpecMap 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. */ /* Number of conversion steps. */ /* --------------------------- */ /* Regard this as "set" if it is non-zero. */ ival = this->ncvt; set = ( ival != 0 ); astWriteInt( channel, "Nspec", set, 0, ival, "Number of conversion steps" ); /* Write out data for each conversion step... */ for ( icvt = 0; icvt < this->ncvt; icvt++ ) { /* Conversion type. */ /* ---------------- */ /* Change each conversion type code into an equivalent string and obtain associated descriptive information. If the conversion code was not recognised, report an error and give up. */ if ( astOK ) { sval = CvtString( this->cvttype[ icvt ], &comment, &argra, &argdec, &nargs, &szargs, argdesc, status ); if ( astOK && !sval ) { astError( AST__SPCIN, "astWrite(%s): Corrupt %s contains invalid SpecMap " "spectral coordinate conversion code (%d).", status, astGetClass( channel ), astGetClass( this ), (int) this->cvttype[ icvt ] ); break; } /* Create an appropriate keyword and write out the conversion code information. */ (void) sprintf( key, "Spec%d", icvt + 1 ); astWriteString( channel, key, 1, 1, sval, comment ); /* Write out data for each conversion argument... */ for ( iarg = 0; iarg < szargs; iarg++ ) { /* Arguments. */ /* ---------- */ /* Create an appropriate keyword and write out the argument value, accompanied by the descriptive comment obtained above. */ if( this->cvtargs[ icvt ][ iarg ] != AST__BAD ) { (void) sprintf( key, "Spec%d%c", icvt + 1, ALPHABET[ iarg ] ); astWriteDouble( channel, key, 1, 1, this->cvtargs[ icvt ][ iarg ], argdesc[ iarg ] ); } } /* Quit looping if an error occurs. */ if ( !astOK ) break; } } /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASpecMap and astCheckSpecMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SpecMap,Mapping) astMAKE_CHECK(SpecMap) AstSpecMap *astSpecMap_( int nin, int flags, const char *options, int *status, ...) { /* *++ * Name: c astSpecMap f AST_SPECMAP * Purpose: * Create a SpecMap. * Type: * Public function. * Synopsis: c #include "specmap.h" c AstSpecMap *astSpecMap( int nin, int flags, const char *options, ... ) f RESULT = AST_SPECMAP( NIN, FLAGS, OPTIONS, STATUS ) * Class Membership: * SpecMap constructor. * Description: * This function creates a new SpecMap and optionally initialises * its attributes. * * An SpecMap is a specialised form of Mapping which can be used to * represent a sequence of conversions between standard spectral * coordinate systems. This includes conversions between frequency, * wavelength, and various forms of velocity, as well as conversions * between different standards of rest. * * When a SpecMap is first created, it simply performs a unit c (null) Mapping. Using the astSpecAdd function, f (null) Mapping. Using the AST_SPECADD routine, * a series of coordinate conversion steps may then be added, selected * from the list of supported conversions. This allows multi-step * conversions between a variety of spectral coordinate systems to * be assembled out of the building blocks provided by this class. * * For details of the individual coordinate conversions available, c see the description of the astSpecAdd function. f see the description of the AST_SPECADD routine. * * Conversions are available to transform between standards of rest. * Such conversions need to know the source position as an RA and DEC. * This information can be supplied in the form of parameters for * the relevant conversions, in which case the SpecMap is 1-dimensional, * simply transforming the spectral axis values. This means that the * same source position will always be used by the SpecMap. However, this * may not be appropriate for an accurate description of a 3-D spectral * cube, where changes of spatial position can produce significant * changes in the Doppler shift introduced when transforming between * standards of rest. For this situation, a 3-dimensional SpecMap can * be created in which axes 2 and 3 correspond to the source RA and DEC * The SpecMap simply copies values for axes 2 and 3 from input to * output). * Parameters: c nin f NIN = INTEGER (Given) * The number of inputs to the Mapping (this will also equal the * number of outputs). This value must be either 1 or 3. In either * case, the first input and output correspoindis the spectral axis. * For a 3-axis SpecMap, the second and third axes give the RA and * DEC (J2000 FK5) of the source. This positional information is * used by conversions which transform between standards of rest, * and replaces the "RA" and "DEC" arguments for the individual * conversions listed in description of the "SpecAdd" c function. f routine. c flags f FLAGS = INTEGER (Given) c This parameter is reserved for future use and should currently f This argument is reserved for future use and should currently * always be set to zero. 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 SpecMap. 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 SpecMap. 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 astSpecMap() f AST_SPECMAP = INTEGER * A pointer to the new SpecMap. * Notes: * - The nature and units of the coordinate values supplied for the * first input (i.e. the spectral input) of a SpecMap must be appropriate * to the first conversion step applied by the SpecMap. For instance, if * the first conversion step is "FRTOVL" (frequency to relativistic * velocity), then the coordinate values for the first input should * be frequency in units of Hz. Similarly, the nature and units of the * coordinate values returned by a SpecMap will be determined by the * last conversion step applied by the SpecMap. For instance, if the * last conversion step is "VLTOVO" (relativistic velocity to optical * velocity), then the coordinate values for the first output will be optical * velocity in units of metres per second. See the description of the c astSpecAdd function for the units expected and returned by each f AST_SPECADD routine for the units expected and returned by each * conversion. * - 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSpecMap *new; /* Pointer to the new SpecMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SpecMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecMap( NULL, sizeof( AstSpecMap ), !class_init, &class_vtab, "SpecMap", nin, flags ); /* 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 SpecMap'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 SpecMap. */ return new; } AstSpecMap *astSpecMapId_( int nin, int flags, const char *options, ... ) { /* * Name: * astSpecMapId_ * Purpose: * Create a SpecMap. * Type: * Private function. * Synopsis: * #include "specmap.h" * AstSpecMap *astSpecMapId_( int nin, int flags, const char *options, ... ) * Class Membership: * SpecMap constructor. * Description: * This function implements the external (public) interface to the * astSpecMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astSpecMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astSpecMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astSpecMap_. * Returned Value: * The ID value associated with the new SpecMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSpecMap *new; /* Pointer to the new SpecMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SpecMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecMap( NULL, sizeof( AstSpecMap ), !class_init, &class_vtab, "SpecMap", nin, flags ); /* 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 SpecMap'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 SpecMap. */ return astMakeId( new ); } AstSpecMap *astInitSpecMap_( void *mem, size_t size, int init, AstSpecMapVtab *vtab, const char *name, int nin, int flags, int *status ) { /* *+ * Name: * astInitSpecMap * Purpose: * Initialise a SpecMap. * Type: * Protected function. * Synopsis: * #include "specmap.h" * AstSpecMap *astInitSpecMap( void *mem, size_t size, int init, * AstSpecMapVtab *vtab, const char *name, * int nin, int flags ) * Class Membership: * SpecMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new SpecMap object. It allocates memory (if necessary) to accommodate * the SpecMap plus any additional data associated with the derived class. * It then initialises a SpecMap 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 SpecMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SpecMap is to be initialised. * This must be of sufficient size to accommodate the SpecMap data * (sizeof(SpecMap)) 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 SpecMap (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 SpecMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the SpecMap'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 SpecMap. * 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 astClass * method). * nin * The number of inputs and outputs for the SpecMap (either 1 or 3). * flags * This parameter is reserved for future use. It is currently ignored. * Returned Value: * A pointer to the new SpecMap. * 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: */ AstSpecMap *new; /* Pointer to the new SpecMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* Check nin is OK (1 or 3). */ if( nin != 1 && nin != 3 ) { astError( AST__BADNI, "astInitSpecMap(SpecMap): Supplied number of " "SpecMap axes (%d) is illegal; it should be 1 or 2. ", status, nin ); } /* If necessary, initialise the virtual function table. */ if ( init ) astInitSpecMapVtab( vtab, name ); /* Initialise a 1D Mapping structure (the parent class) as the first component within the SpecMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstSpecMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nin, 1, 1 ); if ( astOK ) { /* Initialise the SpecMap data. */ /* --------------------------- */ /* The initial state is with no conversions set, in which condition the SpecMap simply implements a unit mapping. */ new->ncvt = 0; new->cvtargs = NULL; new->cvttype = NULL; /* 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; } AstSpecMap *astLoadSpecMap_( void *mem, size_t size, AstSpecMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSpecMap * Purpose: * Load a SpecMap. * Type: * Protected function. * Synopsis: * #include "specmap.h" * AstSpecMap *astLoadSpecMap( void *mem, size_t size, * AstSpecMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SpecMap loader. * Description: * This function is provided to load a new SpecMap 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 * SpecMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a SpecMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the SpecMap is to be * loaded. This must be of sufficient size to accommodate the * SpecMap data (sizeof(SpecMap)) 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 SpecMap (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 SpecMap 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(AstSpecMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SpecMap. If this is NULL, a pointer to * the (static) virtual function table for the SpecMap 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 "SpecMap" is used instead. * Returned Value: * A pointer to the new SpecMap. * 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: */ AstSpecMap *new; /* Pointer to the new SpecMap */ char *sval; /* Pointer to string value */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ const char *argdesc[ MAX_ARGS ]; /* Pointers to argument descriptions */ const char *comment; /* Pointer to comment string */ int argdec; /* Index of DEC argument */ int argra; /* Index of RA argument */ int iarg; /* Loop counter for arguments */ int icvt; /* Loop counter for conversion steps */ int nargs; /* Number of user-supplied arguments */ int szargs; /* Number of stored arguments */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this SpecMap. In this case the SpecMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSpecMap ); vtab = &class_vtab; name = "SpecMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSpecMapVtab( 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 SpecMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "SpecMap" ); /* 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. */ /* Number of conversion steps. */ /* --------------------------- */ /* Read the number of conversion steps and allocate memory to hold data for each step. */ new->ncvt = astReadInt( channel, "nspec", 0 ); if ( new->ncvt < 0 ) new->ncvt = 0; new->cvttype = astMalloc( sizeof( int ) * (size_t) new->ncvt ); new->cvtargs = astMalloc( sizeof( double * ) * (size_t) new->ncvt ); /* If an error occurred, ensure that all allocated memory is freed. */ if ( !astOK ) { new->cvttype = astFree( new->cvttype ); new->cvtargs = astFree( new->cvtargs ); /* Otherwise, initialise the argument pointer array. */ } else { for ( icvt = 0; icvt < new->ncvt; icvt++ ) { new->cvtargs[ icvt ] = NULL; } /* Read in data for each conversion step... */ for ( icvt = 0; icvt < new->ncvt; icvt++ ) { /* Conversion type. */ /* ---------------- */ /* Create an appropriate keyword and read the string representation of the conversion type. */ (void) sprintf( key, "spec%d", icvt + 1 ); sval = astReadString( channel, key, NULL ); /* If no value was read, report an error. */ if ( astOK ) { if ( !sval ) { astError( AST__BADIN, "astRead(%s): A spectral coordinate conversion " "type is missing from the input SpecMap data.", status, astGetClass( channel ) ); /* Otherwise, convert the string representation into the required conversion type code. */ } else { new->cvttype[ icvt ] = CvtCode( sval, status ); /* If the string was not recognised, report an error. */ if ( new->cvttype[ icvt ] == AST__SPEC_NULL ) { astError( AST__BADIN, "astRead(%s): Invalid spectral conversion " "type \"%s\" in SpecMap data.", status, astGetClass( channel ), sval ); } } /* Free the memory holding the string value. */ sval = astFree( sval ); } /* Obtain the number of arguments associated with the conversion and allocate memory to hold them. */ (void) CvtString( new->cvttype[ icvt ], &comment, &argra, &argdec, &nargs, &szargs, argdesc, status ); new->cvtargs[ icvt ] = astMalloc( sizeof( double ) * (size_t) szargs ); /* Read in data for each argument... */ if ( astOK ) { for ( iarg = 0; iarg < szargs; iarg++ ) { /* Arguments. */ /* ---------- */ /* Create an appropriate keyword and read each argument value. */ (void) sprintf( key, "spec%d%c", icvt + 1, ALPHABET[ iarg ] ); new->cvtargs[ icvt ][ iarg ] = astReadDouble( channel, key, AST__BAD ); } } /* Quit looping if an error occurs. */ if ( !astOK ) break; } } /* If an error occurred, clean up by deleting the new SpecMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SpecMap 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 astSpecAdd_( AstSpecMap *this, const char *cvt, const double args[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,SpecMap,SpecAdd))( this, cvt, args, status ); } ast-8.3.0/dssmap.c0000664000175000017500000023736013004147321010675 00000000000000/* *class++ * Name: * DssMap * Purpose: * Map points using a Digitised Sky Survey plate solution. * Constructor Function: * The DssMap class does not have a constructor function. A DssMap * is created only as a by-product of reading a FrameSet (using c astRead) from a FitsChan which contains FITS header cards f AST_READ) from a FitsChan which contains FITS header cards * describing a DSS plate solution, and whose Encoding attribute is * set to "DSS". The result of such a read, if successful, is a * FrameSet whose base and current Frames are related by a DssMap. * Description: * The DssMap class implements a Mapping which transforms between * 2-dimensional pixel coordinates and an equatorial sky coordinate * system (right ascension and declination) using a Digitised Sky * Survey (DSS) astrometric plate solution. * * The input coordinates are pixel numbers along the first and * second dimensions of an image, where the centre of the first * pixel is located at (1,1) and the spacing between pixel centres * is unity. * * The output coordinates are right ascension and declination in * radians. The celestial coordinate system used (FK4, FK5, etc.) * is unspecified, and will usually be indicated by appropriate * keywords in a FITS header. * Inheritance: * The DssMap class inherits from the Mapping class. * Attributes: * The DssMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The DssMap class does not define any new functions beyond those f The DssMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * (except for code supplied by Doug Mink, as noted in this file) * Authors: * DSB: D.S. Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink, RAL) * History: * 18-FEB-1997 (DSB): * Original version. * 30-JUN-1997 (DSB): * astDssFits and astDssMap made protected instead of public. * 15-JUL-1997 (RFWS): * Tidied public prologues. * 5-SEP-197 (RFWS): * Added prototypes for platepos and platepix. * 4-NOV-1997 (DSB): * o A copy of the supplied FitsChan is no longer stored inside * the DssMap. The FitsChan returned by DssFits is now derived from * the wcs information stored in the SAOimage "WorldCoor" structure * (stored within the DssMap), and only contains the keywords * necessary to reconstruct the DssMap. * o The external representation of a DssMap is now stored in a set * of scalar values, rather than a FitsChan. * 22-DEC-1997 (DSB): * Bug fixed in MapMerge which caused a core dump when a * DssMap/WinMap combination is succesfully simplified. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitDssMapVtab * method. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 10-MAY-2006 (DSB): * Override astEqual. *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 DssMap /* Macro which returns the nearest integer to a given floating point value. */ #define NINT(x) (int)((x)+(((x)>0.0)?0.5:-0.5)) /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "memory.h" /* Memory allocation facilities */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "fitschan.h" /* Manipulation of FITS header cards */ #include "wcsmap.h" /* Degrees/radians conversion factors */ #include "winmap.h" /* Shift and scale mappings */ #include "dssmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(DssMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(DssMap,Class_Init) #define class_vtab astGLOBAL(DssMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstDssMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstFitsChan *DssFits( AstDssMap *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int platepix( double, double, struct WorldCoor *, double *, double * ); static int platepos( double, double, struct WorldCoor *, double *, double * ); static struct WorldCoor *BuildWcs( AstFitsChan *, const char *, const char *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *obj, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetObjSize( AstObject *, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two DssMaps are equivalent. * Type: * Private function. * Synopsis: * #include "dssmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * DssMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two DssMaps are equivalent. * Parameters: * this * Pointer to the first Object (a DssMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the DssMaps are equivalent, zero otherwise. * 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: */ AstDssMap *that; AstDssMap *this; int i; int nin; int nout; int result; struct WorldCoor *this_wcs; struct WorldCoor *that_wcs; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two DssMap structures. */ this = (AstDssMap *) this_object; that = (AstDssMap *) that_object; /* Check the second object is a DssMap. We know the first is a DssMap since we have arrived at this implementation of the virtual function. */ if( astIsADssMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two DssMaps differ, it may still be possible for them to be equivalent. First compare the DssMaps if their Invert flags are the same. In this case all the attributes of the two DssMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { this_wcs = ( struct WorldCoor *) this->wcs; that_wcs = ( struct WorldCoor *) that->wcs; if( this_wcs->x_pixel_offset == that_wcs->x_pixel_offset && this_wcs->y_pixel_offset == that_wcs->y_pixel_offset && this_wcs->ppo_coeff[2] == that_wcs->ppo_coeff[2] && this_wcs->ppo_coeff[5] == that_wcs->ppo_coeff[5] && this_wcs->x_pixel_size == that_wcs->x_pixel_size && this_wcs->y_pixel_size == that_wcs->y_pixel_size && this_wcs->plate_dec == that_wcs->plate_dec && this_wcs->plate_ra == that_wcs->plate_ra ) { result = 1; for( i = 0; i < 13; i++ ) { if( this_wcs->amd_x_coeff[i] != that_wcs->amd_x_coeff[i] || this_wcs->amd_y_coeff[i] != that_wcs->amd_y_coeff[i] ) { result = 0; break; } } } /* If the Invert flags for the two DssMaps differ, the attributes of the two DssMaps must be inversely related to each other. */ } else { /* In the specific case of a DssMap, Invert flags must be equal. */ result = 0; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "dssmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * DssMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied DssMap, * in bytes. * Parameters: * this * Pointer to the DssMap. * 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: */ AstDssMap *this; /* Pointer to DssMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the DssMap structure. */ this = (AstDssMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->wcs ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static struct WorldCoor *BuildWcs( AstFitsChan *fits, const char *method, const char *class, int *status ) { /* * Name: * BuildWcs * Purpose: * Copy DSS plate fit information from a FitsChan to a SAOimage * WorldCoor structure. * Type: * Private function. * Synopsis: * #include "dssmap.h" * struct WorldCoor *BuildWcs( AstFitsChan *fits, const char *method, * const char *class ) * Class Membership: * DssMap member function. * Description: * This creates a WorldCoor structure and copies the required data * from the supplied FitsChan into the new WorldCoor structure. Note, * only those components of the WorldCoor structure which are needed to * transform between pixel and sky coordinates are initialised in the * returned structure. * Parameters: * fits * Pointer to the FitsChan containing the FITS header describing * the DSS plate fit. * method * The calling method (for error messages). * class * The object class (for error messages). * Returned Value: * A pointer to the new WorldCoor structure. This should be freed * using astFree when no longer needed. * Notes: * - A NULL pointer is returned if an error has already occurred, or * if this function should fail for any reason. */ /* Local Variables: */ char name_buff[ 10 ]; /* Buffer for keyword name */ char *name; /* Pointer to jeyword name string */ char *ckeyval; /* Pointer to string keyword value */ struct WorldCoor *ret; /* Pointer to the returned structure */ double rah,ram,ras; /* Centre RA hours, minutes and seconds */ double dsign; /* Sign of centre dec */ double decd,decm,decs; /* Centre Dec degrees, minutes, seconds */ double dec_deg; /* Centre Dec in degrees */ double ra_hours; /* Centre RA in hours */ int i; /* Coefficient index */ /* Check the local error status. */ if ( !astOK ) return NULL; /* Get memory to hold the returned structure. */ ret = (struct WorldCoor *) astMalloc( sizeof( struct WorldCoor ) ); /* Check the memory can be used. */ if( astOK ){ /* The following code is based on the "wcsinit" function in SAOimage file wcs.c. Note, only the values needed in the platepos and platepix functions are set up. The FITS keywords are accessed in the order in which they are usually stored in a FITS file. This will cut down the time spent searching for keywords. Report an error if any required keyword is not found. */ /* Plate center RA */ rah = 0.0; ram = 0.0; ras = 0.0; name = "PLTRAH"; if( !astGetFitsF( fits, name, &rah ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "PLTRAM"; if( !astGetFitsF( fits, name, &ram ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "PLTRAS"; if( !astGetFitsF( fits, name, &ras ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } ra_hours = rah + (ram / (double)60.0) + (ras / (double)3600.0); ret->plate_ra = AST__DD2R*15.0*ra_hours; /* Plate center Dec */ name = "PLTDECSN"; if( !astGetFitsS( fits, name, &ckeyval ) && astOK ){ dsign = 1.0; } else { if( *ckeyval == '-' ){ dsign = -1.0; } else { dsign = 1.0; } } decd = 0.0; decm = 0.0; decs = 0.0; name = "PLTDECD"; if( !astGetFitsF( fits, name, &decd ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "PLTDECM"; if( !astGetFitsF( fits, name, &decm ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "PLTDECS"; if( !astGetFitsF( fits, name, &decs ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } dec_deg = dsign * (decd+(decm/(double)60.0)+(decs/(double)3600.0)); ret->plate_dec = AST__DD2R*dec_deg; /* Plate Scale arcsec per mm */ name = "PLTSCALE"; if( !astGetFitsF( fits, name, &ret->plate_scale ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } /* X and Y corners (in pixels) */ name = "CNPIX1"; if( !astGetFitsF( fits, name, &ret->x_pixel_offset ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "CNPIX2"; if( !astGetFitsF( fits, name, &ret->y_pixel_offset ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } /* X and Y pixel sizes (microns). */ name = "XPIXELSZ"; if( !astGetFitsF( fits, name, &ret->x_pixel_size ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } name = "YPIXELSZ"; if( !astGetFitsF( fits, name, &ret->y_pixel_size ) && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied for the " "FITS keyword '%s'.", status, method, class, name ); } /* Orientation Coefficients. Only report an error if PPO3 or PPO6 are missing (these are the only two which are actually used). Assume a value of zero for any of the others which are missing. */ name = name_buff; for ( i = 0; i < 6; i++ ) { sprintf( name_buff, "PPO%d", i + 1 ); if( !astGetFitsF( fits, name, &ret->ppo_coeff[i] ) ) { ret->ppo_coeff[i] = 0.0; if( ( i == 2 || i == 5 ) && astOK ) { astError( AST__BDFTS, "%s(%s): No value has been supplied " "for the FITS keyword '%s'.", status, method, class, name ); break; } } } /* Plate solution x and y coefficients. Report an error if any of coefficients 1 to 14 are missing. Assume a value of zero for any others which are missing. */ name = name_buff; for( i = 0; i < 19; i++ ){ sprintf( name_buff, "AMDX%d", i + 1 ); if( !astGetFitsF( fits, name, &ret->amd_x_coeff[i] ) ) { ret->amd_x_coeff[i] = 0.0; if( i < 13 && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied " "for the FITS keyword '%s'.", status, method, class, name ); break; } } } for( i = 0; i < 19; i++ ){ sprintf( name_buff, "AMDY%d", i + 1 ); if( !astGetFitsF( fits, name, &ret->amd_y_coeff[i] ) ){ ret->amd_y_coeff[i] = 0.0; if( i < 13 && astOK ){ astError( AST__BDFTS, "%s(%s): No value has been supplied " "for the FITS keyword '%s'.", status, method, class, name ); break; } } } /* If anything went wrong, free the returned structure. */ if( !astOK ) ret = (struct WorldCoor *) astFree( (void *) ret ); } /* Return the pointer. */ return ret; } static AstFitsChan *DssFits( AstDssMap *this, int *status ) { /* *+ * Name: * astDssFits * Purpose: * Return a pointer to a FitsChan describing a DssMap. * Type: * Protected virtual function. * Synopsis: * #include "dssmap.h" * AstFitsChan *DssFits( AstDssMap *this ) * Class Membership: * DssMap method. * Description: * This function returns a pointer to a DSS-encoded FitsChan containing * cards generated from the information stored with the DssMap. The * keywords contained in the FitsChan are those which would ne needed to * re-create the DssMap (see astDSSMap). * Parameters: * this * Pointer to the DssMap. * Returned Value: * astDssFits() * A pointer to the FitsChan. * Notes: * - The returned pointer should be annuled using astAnnul when no longer * needed. * - A value of NULL will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstFitsChan *ret; /* Pointer to the returned FitsChan */ char *comm; /* Pointer to keyword comment string */ char *name; /* Pointer to keyword name string */ char name_buff[ 10 ]; /* Buffer for keyword name */ double dec; /* Centre Dec in degrees */ double decd,decm,decs; /* Centre Dec degrees, minutes, seconds */ double ra; /* Centre RA in hours */ double rah,ram,ras; /* Centre RA hours, minutes and seconds */ int i; /* Coefficient index */ struct WorldCoor *wcs; /* WCS information from the DssMap */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Store a pointer to the WCS information stored in the DSSMap. */ wcs = (struct WorldCoor *) this->wcs, /* Create a new empty FitsChan, using DSS encoding. */ ret = astFitsChan( NULL, NULL, "Encoding=DSS", status ); /* Create the keyword values and stored them in the returned FitsChan... */ /* Plate centre RA. */ ra = wcs->plate_ra/( AST__DD2R*15.0 ); ra = modf( ra, &rah ); ra = modf( 60.0*ra, &ram ); ras = 60.0*ra; astSetFitsI( ret, "PLTRAH", NINT( rah ), "Plate centre RA", 0 ); astSetFitsI( ret, "PLTRAM", NINT( ram ), " ", 0 ); astSetFitsF( ret, "PLTRAS", ras, " ", 0 ); /* Plate centre DEC. */ dec = wcs->plate_dec/AST__DD2R; if( dec < 0.0 ) { dec = -dec; astSetFitsS( ret, "PLTDECSN", "-", "Plate centre DEC", 0 ); } else { astSetFitsS( ret, "PLTDECSN", "+", "Plate centre DEC", 0 ); } dec = modf( dec, &decd ); dec = modf( 60.0*dec, &decm ); decs = 60.0*dec; astSetFitsI( ret, "PLTDECD", NINT( decd ), " ", 0 ); astSetFitsI( ret, "PLTDECM", NINT( decm ), " ", 0 ); astSetFitsF( ret, "PLTDECS", decs, " ", 0 ); /* Plate Scale arcsec per mm */ astSetFitsF( ret, "PLTSCALE", wcs->plate_scale, "Plate Scale arcsec per mm", 0 ); /* X and Y corners (in pixels) */ astSetFitsI( ret, "CNPIX1", NINT( wcs->x_pixel_offset ), "X corner (pixels)", 0 ); astSetFitsI( ret, "CNPIX2", NINT( wcs->y_pixel_offset ), "Y corner", 0 ); /* X and Y pixel sizes (microns). */ astSetFitsF( ret, "XPIXELSZ", wcs->x_pixel_size, "X pixel size (microns)", 0 ); astSetFitsF( ret, "YPIXELSZ", wcs->y_pixel_size, "Y pixel size (microns)", 0 ); /* Orientation Coefficients. */ name = name_buff; comm = "Orientation Coefficients"; for ( i = 0; i < 6; i++ ) { sprintf( name_buff, "PPO%d", i + 1 ); astSetFitsF( ret, name, wcs->ppo_coeff[i], comm, 0 ); comm = " "; } /* Plate solution x and y coefficients. */ comm = "Plate solution x coefficients"; for( i = 0; i < 19; i++ ){ sprintf( name_buff, "AMDX%d", i + 1 ); astSetFitsF( ret, name, wcs->amd_x_coeff[i], comm, 0 ); comm = " "; } comm = "Plate solution y coefficients"; for( i = 0; i < 19; i++ ){ sprintf( name_buff, "AMDY%d", i + 1 ); astSetFitsF( ret, name, wcs->amd_y_coeff[i], comm, 0 ); comm = " "; } /* Return a pointer to the FitsChan. */ return ret; } void astInitDssMapVtab_( AstDssMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitDssMapVtab * Purpose: * Initialise a virtual function table for a DssMap. * Type: * Protected function. * Synopsis: * #include "dssmap.h" * void astInitDssMapVtab( AstDssMapVtab *vtab, const char *name ) * Class Membership: * DssMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the DssMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsADssMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->DssFits = DssFits; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; object = (AstObjectVtab *) vtab; parent_transform = mapping->Transform; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the class dump, copy and delete function. */ astSetDump( object, Dump, "DssMap", "DSS plate fit mapping" ); astSetCopy( object, Copy ); astSetDelete( object, Delete ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a DssMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * DssMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated DssMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated DssMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated DssMap which is to be merged with * its neighbours. This should be a cloned copy of the DssMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * DssMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated DssMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstDssMap *dm; /* Pointer to supplied DssMap */ AstDssMap *dmnew; /* Pointer to replacement DssMap */ AstFitsChan *fits; /* FITS headers for replacement DssMap */ AstFitsChan *fits_dss;/* FITS headers for supplied DssMap */ AstWinMap *wm; /* Pointer to the adjacent WinMap */ double *a; /* Pointer to shift terms */ double *b; /* Pointer to scale terms */ double cnpix1; /* X pixel origin */ double cnpix2; /* Y pixel origin */ double xpixelsz; /* X pixel size */ double ypixelsz; /* Y pixel size */ int i; /* Loop counter */ int ok; /* All FITS keywords found? */ int old_winv; /* original Invert value for supplied WinMap */ int result; /* Result value to return */ int wmi; /* Index of adjacent WinMap in map list */ struct WorldCoor *wcs;/* Pointer to SAOimage wcs structure */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* The only simplification easily possible is if a WinMap maps the pixel coordinates prior to a DssMap. If the DssMap has not been inverted, the WinMap must be applied before the DssMap, otherwise the WinMap must be applied after the DssMap. */ if( series ){ if( !( *invert_list )[ where ] ){ wmi = where - 1; } else { wmi = where + 1; } if( wmi >= 0 && wmi < *nmap ){ if( !strcmp( astGetClass( ( *map_list )[ wmi ] ), "WinMap" ) ){ /* Temporarily set the Invert attribute of the WinMap to the supplied value. */ wm = (AstWinMap *) ( *map_list )[ wmi ]; old_winv = astGetInvert( wm ); astSetInvert( wm, ( *invert_list )[ wmi ] ); /* Get a copy of the scale and shift terms from the WinMap. */ astWinTerms( wm, &a, &b ); /* Check that the scale and shift terms are usable. */ if( astOK && a[ 0 ] != AST__BAD && b[ 0 ] != AST__BAD && b[ 0 ] != 0.0 && a[ 1 ] != AST__BAD && b[ 1 ] != AST__BAD && b[ 1 ] != 0.0 ){ /* Get the values of the keywords which define the origin and scales of the DssMap pixel coordinate system. */ dm = (AstDssMap *) ( *map_list )[ where ]; wcs = (struct WorldCoor *) ( dm->wcs ); cnpix1 = wcs->x_pixel_offset; cnpix2 = wcs->y_pixel_offset; xpixelsz = wcs->x_pixel_size; ypixelsz = wcs->y_pixel_size; /* Calculate new values which take into account the WinMap. */ if( wmi == where - 1 ){ xpixelsz *= b[ 0 ]; ypixelsz *= b[ 1 ]; cnpix1 = 0.5 + ( cnpix1 + a[ 0 ] - 0.5 )/b[ 0 ]; cnpix2 = 0.5 + ( cnpix2 + a[ 1 ] - 0.5 )/b[ 1 ]; } else { xpixelsz /= b[ 0 ]; ypixelsz /= b[ 1 ]; cnpix1 = b[ 0 ]*( cnpix1 - 0.5 ) - a[ 0 ] + 0.5; cnpix2 = b[ 1 ]*( cnpix2 - 0.5 ) - a[ 1 ] + 0.5; } /* The CNPIX1 and CNPIX2 keywords are integer keywords. Therefore, we can only do the simplification if the new values are integer to a good approximation. We use one hundredth of a pixel. */ if( fabs( cnpix1 - NINT( cnpix1 ) ) < 0.01 && fabs( cnpix2 - NINT( cnpix2 ) ) < 0.01 ){ /* Get a copy of the FitsChan holding the header cards which define the DssMap. */ fits_dss = astDssFits( dm ); fits = astCopy( fits_dss ); fits_dss = astAnnul( fits_dss ); /* Update the value of each of the changed keywords. */ ok = 1; astClearCard( fits ); if( astFindFits( fits, "CNPIX1", NULL, 0 ) ){ astSetFitsI( fits, "CNPIX1", NINT( cnpix1 ), NULL, 1 ); } else { ok = 0; } astClearCard( fits ); if( astFindFits( fits, "CNPIX2", NULL, 0 ) ){ astSetFitsI( fits, "CNPIX2", NINT( cnpix2 ), NULL, 1 ); } else { ok = 0; } astClearCard( fits ); if( astFindFits( fits, "XPIXELSZ", NULL, 0 ) ){ astSetFitsF( fits, "XPIXELSZ", xpixelsz, NULL, 1 ); } else { ok = 0; } astClearCard( fits ); if( astFindFits( fits, "YPIXELSZ", NULL, 0 ) ){ astSetFitsF( fits, "YPIXELSZ", ypixelsz, NULL, 1 ); } else { ok = 0; } /* If all the keywords were updated succesfully, create the new DssMap based on the modified FITS header cards. */ if( ok ){ dmnew = astDssMap( fits, "", status ); /* Anull the DssMap pointer in the list and replace it with the new one. The invert flag is left unchanged. */ dm = astAnnul( dm ); ( *map_list )[ where ] = (AstMapping *) dmnew; /* Annul the WinMap pointer in the list, and shuffle any remaining Mappings down to fill the gap. */ wm = astAnnul( wm ); for ( i = wmi + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = astMIN( wmi, where ); } /* Annul the FitsChan holding the modified header cards. */ fits = astAnnul( fits ); } } /* Free the arrays holding scale and shift terms from the WinMap. */ a = (double *) astFree( (void *) a ); b = (double *) astFree( (void *) b ); /* Reinstate the original setting of the Invert attribute of the WinMap (if it still exists). */ if( wm ) astSetInvert( wm, old_winv ); } } } /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a DssMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "dssmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * DssMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a DssMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required DSS * plate fit. * Parameters: * this * Pointer to the DssMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * be 2. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstDssMap *map; /* Pointer to DssMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *aa; /* Pointer to next longitude value */ double *bb; /* Pointer to next latitude value */ double *xx; /* Pointer to next pixel X value */ double *yy; /* Pointer to next pixel Y value */ int npoint; /* Number of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the DssMap. */ map = (AstDssMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* First deal with forward transformations. */ if( forward ){ /* Store pointers to the next value on each axis. */ xx = ptr_in[ 0 ]; yy = ptr_in[ 1 ]; aa = ptr_out[ 0 ]; bb = ptr_out[ 1 ]; /* Loop to apply the plate fit to all the points, checking for (and propagating) bad values in the process. */ for ( point = 0; point < npoint; point++ ) { if( *xx != AST__BAD && *yy != AST__BAD ){ /* If the pixel position is transformed succesfully, convert the returned RA/DEC from degrees to radians. Otherwise, store bad values. NB, platepos returns zero for success. */ if( !platepos( *xx, *yy, (struct WorldCoor *) map->wcs, aa, bb ) ){ (*aa) *= AST__DD2R; (*bb) *= AST__DD2R; } else { *aa = AST__BAD; *bb = AST__BAD; } } else { *aa = AST__BAD; *bb = AST__BAD; } /* Move on to the next point. */ xx++; yy++; aa++; bb++; } /* Now deal with inverse transformations in the same way. */ } else { aa = ptr_in[ 0 ]; bb = ptr_in[ 1 ]; xx = ptr_out[ 0 ]; yy = ptr_out[ 1 ]; for ( point = 0; point < npoint; point++ ) { if( *aa != AST__BAD && *bb != AST__BAD ){ if( platepix( AST__DR2D*(*aa), AST__DR2D*(*bb), (struct WorldCoor *) map->wcs, xx, yy ) ){ *xx = AST__BAD; *yy = AST__BAD; } } else { *xx = AST__BAD; *yy = AST__BAD; } xx++; yy++; aa++; bb++; } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for DssMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for DssMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstDssMap *in; /* Pointer to input DssMap */ AstDssMap *out; /* Pointer to output DssMap */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output DssMaps. */ in = (AstDssMap *) objin; out = (AstDssMap *) objout; /* Store a copy of the input SAOIMAGE WorldCoor structure in the output. */ out->wcs = astStore( NULL, in->wcs, sizeof( struct WorldCoor ) ); return; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for DssMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for DssMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstDssMap *this; /* Pointer to DssMap */ /* Obtain a pointer to the DssMap structure. */ this = (AstDssMap *) obj; /* Free the SAOIMAGE WorldCoor structure. */ this->wcs = astFree( this->wcs ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for DssMap 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 DssMap class to an output Channel. * Parameters: * this * Pointer to the DssMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ AstDssMap *this; /* Pointer to the DssMap structure */ struct WorldCoor *wcs; /* Pointer to SAOimage wcs structure */ char name_buff[ 11 ]; /* Buffer for keyword string */ int i; /* Coefficient index */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the DssMap structure. */ this = (AstDssMap *) this_object; /* Get a pointer to the WorldCoor structure holding the description of the DssMap. */ wcs = (struct WorldCoor *) ( this->wcs ); /* Write out values representing the contents of the WorldCoor structure. Only the components which are required to re-create the DssMap are written out. */ astWriteDouble( channel, "PltRA", 1, 1, wcs->plate_ra, "Plate centre RA (radians)" ); astWriteDouble( channel, "PltDec", 1, 1, wcs->plate_dec, "Plate centre Dec (radians)" ); astWriteDouble( channel, "PltScl", 1, 1, wcs->plate_scale, "Plate scale (arcsec/mm)" ); astWriteDouble( channel, "CNPix1", 1, 1, wcs->x_pixel_offset, "X Pixel offset (pixels)" ); astWriteDouble( channel, "CNPix2", 1, 1, wcs->y_pixel_offset, "Y Pixel offset (pixels)" ); astWriteDouble( channel, "XPixSz", 1, 1, wcs->x_pixel_size, "X Pixel size (microns)" ); astWriteDouble( channel, "YPixSz", 1, 1, wcs->y_pixel_size, "Y Pixel size (microns)" ); for( i = 0; i < 6; i++ ) { sprintf( name_buff, "PPO%d", i + 1 ); astWriteDouble( channel, name_buff, 1, 1, wcs->ppo_coeff[i], "Orientation coefficients" ); } for( i = 0; i < 19; i++ ) { sprintf( name_buff, "AMDX%d", i + 1 ); astWriteDouble( channel, name_buff, 1, 1, wcs->amd_x_coeff[i], "Plate solution X coefficients" ); } for( i = 0; i < 19; i++ ) { sprintf( name_buff, "AMDY%d", i + 1 ); astWriteDouble( channel, name_buff, 1, 1, wcs->amd_y_coeff[i], "Plate solution Y coefficients" ); } } /* Standard class functions. */ /* ========================= */ /* Implement the astIsADssMap and astCheckDssMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(DssMap,Mapping) astMAKE_CHECK(DssMap) AstDssMap *astDssMap_( void *fits_void, const char *options, int *status, ...) { /* *+ * Name: * astDssMap * Purpose: * Create a DssMap. * Type: * Protected function. * Synopsis: * #include "dssmap.h" * AstDssMap *astDssMap( AstFitsChan *fits, const char *options, int *status, ... ) * Class Membership: * DssMap constructor. * Description: * This function creates a new DssMap and optionally initialises its * attributes. * * A DssMap is a Mapping which uses a Digitised Sky Survey plate fit to * transform a set of points from pixel coordinates to equatorial * coordinates (i.e. Right Ascension and Declination). * Parameters: * fits * A pointer to a FitsChan holding a set of FITS header cards * describing the plate fit to be used. The FitsChan may contain * other header cards which will be ignored, and it is unchanged on * exit. The required information is copied from the FitsChan, and * so the supplied FitsChan may subsequently be changed or deleted * without changing the DssMap. * options * Pointer to a null-terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new DssMap. The syntax used is identical to * that for the astSet function 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 additional 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 function (and for the C "printf" * function). * Returned Value: * astDssMap() * A pointer to the new DssMap. * Attributes: * The DssMap class has no additional attributes over and above those * common to all Mappings. * Notes: * - The supplied FitsChan must contain values for the following FITS * keywords: CNPIX1, CNPIX2, PPO3, PPO6, XPIXELSZ, YPIXELSZ, PLTRAH, * PLTRAM, PLTRAS, PLTDECD, PLTDECM, PLTDECS, PLTDECSN, PLTSCALE, * AMDX1, AMDX2, ..., AMDX13, AMDY1, AMDY2, ..., AMDY13. * - 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFitsChan *fits; /* Pointer to supplied FitsChan */ AstDssMap *new; /* Pointer to new DssMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ new = NULL; if ( !astOK ) return new; /* Obtain and validate a pointer to the FitsChan structure provided. */ fits = astCheckFitsChan( fits_void ); if ( astOK ) { /* Initialise the DssMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitDssMap( NULL, sizeof( AstDssMap ), !class_init, &class_vtab, "DssMap", fits ); /* 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 DssMap'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 DssMap. */ return new; } AstDssMap *astInitDssMap_( void *mem, size_t size, int init, AstDssMapVtab *vtab, const char *name, AstFitsChan *fits, int *status ) { /* *+ * Name: * astInitDssMap * Purpose: * Initialise a DssMap. * Type: * Protected function. * Synopsis: * #include "dssmap.h" * AstDssMap *astInitDssMap( void *mem, size_t size, int init, * AstDssMapVtab *vtab, const char *name, * AstFitsChan *fits ) * Class Membership: * DssMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new DssMap object. It allocates memory (if necessary) to accommodate * the DssMap plus any additional data associated with the derived class. * It then initialises a DssMap 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 DssMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the DssMap is to be initialised. * This must be of sufficient size to accommodate the DssMap data * (sizeof(DssMap)) 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 DssMap (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 DssMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the DssMap'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 DssMap. * 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). * fits * Pointer to a FitsChan containing the DSS FITS Header. * Returned Value: * A pointer to the new DssMap. * 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: */ AstDssMap *new; /* Pointer to new DssMap */ struct WorldCoor *wcs; /* Pointer to SAOIMAGE wcs structure */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitDssMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Create a structure holding the information required by the SAOIMAGE "platepos" function. The required values are extracted from the supplied FitsChan. An error is reported and NULL returned if any required keywords are missing or unusable. */ if ( ( wcs = BuildWcs( fits, "astInitDssMap", name, status ) ) ) { /* Initialise a 2-D Mapping structure (the parent class) as the first component within the DssMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstDssMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 2, 2, 1, 1 ); if ( astOK ) { /* Initialise the DssMap data. */ /* --------------------------- */ /* Store a copy of the SAOIMAGE wcs structure. */ new->wcs = astStore( NULL, (void *) wcs, sizeof( struct WorldCoor ) ); /* If an error occurred, clean up by deleting the new DssMap. */ if ( !astOK ) new = astDelete( new ); } /* Free the SAOIMAGE wcs structure. */ wcs = (struct WorldCoor *) astFree( (void *) wcs ); } /* Return a pointer to the new DssMap. */ return new; } AstDssMap *astLoadDssMap_( void *mem, size_t size, AstDssMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadDssMap * Purpose: * Load a DssMap. * Type: * Protected function. * Synopsis: * #include "dssmap.h" * AstDssMap *astLoadDssMap( void *mem, size_t size, * AstDssMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * DssMap loader. * Description: * This function is provided to load a new DssMap 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 * DssMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a DssMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the DssMap is to be * loaded. This must be of sufficient size to accommodate the * DssMap data (sizeof(DssMap)) 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 DssMap (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 DssMap 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(AstDssMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new DssMap. If this is NULL, a pointer * to the (static) virtual function table for the DssMap 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 "DssMap" is used instead. * Returned Value: * A pointer to the new DssMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstDssMap *new; /* Pointer to the new DssMap */ char name_buff[ 11 ]; /* Buffer for item name */ int i; /* Coefficient index */ struct WorldCoor *wcs; /* Pointer to Wcs information */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this DssMap. In this case the DssMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstDssMap ); vtab = &class_vtab; name = "DssMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitDssMapVtab( 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 DssMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "DssMap" ); /* Allocate memory to hold the WorldCoor structure which holds the wcs information in a form usable by the SAOimage projection functions. */ new->wcs = astMalloc( sizeof(struct WorldCoor) ); if( astOK ) { /* Get a pointer to the WorldCoor structure holding the description of the DssMap. */ wcs = (struct WorldCoor *) ( new->wcs ); /* Read the values representing the contents of the WorldCoor structure. Only the components which are required to re-create the DssMap are read. */ wcs->plate_ra = astReadDouble( channel, "pltra", AST__BAD ); if( wcs->plate_ra == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'PltRA' object (Plate " "centre RA) missing from input." , status); } wcs->plate_dec = astReadDouble( channel, "pltdec", AST__BAD ); if( wcs->plate_dec == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'PltDec' object (Plate " "centre Dec) missing from input." , status); } wcs->plate_scale = astReadDouble( channel, "pltscl", AST__BAD ); if( wcs->plate_scale == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'PltScl' object (Plate " "scale) missing from input." , status); } wcs->x_pixel_offset = astReadDouble( channel, "cnpix1", AST__BAD ); if( wcs->x_pixel_offset == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'CNPix1' object (X pixel " "offset) missing from input." , status); } wcs->y_pixel_offset = astReadDouble( channel, "cnpix2", AST__BAD ); if( wcs->y_pixel_offset == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'CNPix2' object (Y pixel " "offset) missing from input." , status); } wcs->x_pixel_size = astReadDouble( channel, "xpixsz", AST__BAD ); if( wcs->x_pixel_size == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'XPixSz' object (X pixel " "size) missing from input." , status); } wcs->y_pixel_size = astReadDouble( channel, "ypixsz", AST__BAD ); if( wcs->y_pixel_size == AST__BAD && astOK ){ astError( AST__RDERR, "astRead(DssMap): 'YPixSz' object (Y pixel " "size) missing from input." , status); } for( i = 0; i < 6 && astOK; i++ ) { sprintf( name_buff, "ppo%d", i + 1 ); wcs->ppo_coeff[i] = astReadDouble( channel, name_buff, AST__BAD ); if( wcs->ppo_coeff[i] == AST__BAD ){ if( i == 2 || i == 5 ) { if( astOK ) astError( AST__RDERR, "astRead(DssMap): 'PPO%d' " "object (orientation coefficient %d) " "missing from input.", status, i + 1, i + 1 ); } else { wcs->ppo_coeff[i] = 0.0; } } } for( i = 0; i < 19 && astOK; i++ ) { sprintf( name_buff, "amdx%d", i + 1 ); wcs->amd_x_coeff[i] = astReadDouble( channel, name_buff, AST__BAD ); if( wcs->amd_x_coeff[i] == AST__BAD ){ if( i < 13 ){ if( astOK ) astError( AST__RDERR, "astRead(DssMap): 'AMDX%d' " "object (plate solution X coefficient " "%d) missing from input.", status, i + 1, i + 1 ); } else { wcs->amd_x_coeff[i] = 0.0; } } } for( i = 0; i < 19 && astOK; i++ ) { sprintf( name_buff, "amdy%d", i + 1 ); wcs->amd_y_coeff[i] = astReadDouble( channel, name_buff, AST__BAD ); if( wcs->amd_y_coeff[i] == AST__BAD ){ if( i < 13 ){ if( astOK ) astError( AST__RDERR, "astRead(DssMap): 'AMDY%d' " "object (plate solution Y coefficient " "%d) missing from input.", status, i + 1, i + 1 ); } else { wcs->amd_y_coeff[i] = 0.0; } } } } /* If an error occurred, clean up by deleting the new DssMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new DssMap pointer. */ return new; } /* 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. */ AstFitsChan *astDssFits_( AstDssMap *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,DssMap,DssFits))( this, status ); } /* The code which follows in this file is covered by the following statement of terms and conditions, which differ from the terms and conditions which apply above. *************************************************************************** * * Copyright: 1988 Smithsonian Astrophysical Observatory * You may do anything you like with these files except remove * this copyright. The Smithsonian Astrophysical Observatory * makes no representations about the suitability of this * software for any purpose. It is provided "as is" without * express or implied warranty. * ***************************************************************************** */ /* >>>>>>>>>>>>>>>>>>>>>> platepos.c <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< */ /* File saoimage/wcslib/platepos.c * February 25, 1996 * By Doug Mink, Harvard-Smithsonian Center for Astrophysics * Module: platepos.c (Plate solution WCS conversion * Purpose: Compute WCS from Digital Sky Survey plate fit * Subroutine: platepos() converts from pixel location to RA,Dec * Subroutine: platepix() converts from RA,Dec to pixel location These functions are based on the astrmcal.c portion of GETIMAGE by J. Doggett and the documentation distributed with the Digital Sky Survey. >>>>>>> STARLINK VERSION <<<<<<<< */ /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Changed by R.F. Warren-Smith (Starlink) to make the function static. */ static int platepos (xpix, ypix, wcs, xpos, ypos) /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> */ /* Routine to determine accurate position for pixel coordinates */ /* returns 0 if successful otherwise 1 = angle too large for projection; */ /* based on amdpos() from getimage */ /* Input: */ double xpix; /* x pixel number (RA or long without rotation) */ double ypix; /* y pixel number (dec or lat without rotation) */ struct WorldCoor *wcs; /* WCS parameter structure */ /* Output: */ double *xpos; /* Right ascension or longitude in degrees */ double *ypos; /* Declination or latitude in degrees */ { double x, y, xmm, ymm, xmm2, ymm2, xmm3, ymm3, x2y2; double xi, xir, eta, etar, raoff, ra, dec; double cond2r = 1.745329252e-2; double cons2r = 206264.8062470964; double twopi = 6.28318530717959; double ctan, ccos; /* Ignore magnitude and color terms double mag = 0.0; double color = 0.0; */ /* Convert from image pixels to plate pixels */ x = xpix + wcs->x_pixel_offset - 1.0 + 0.5; y = ypix + wcs->y_pixel_offset - 1.0 + 0.5; /* Convert from pixels to millimeters */ xmm = (wcs->ppo_coeff[2] - x * wcs->x_pixel_size) / 1000.0; ymm = (y * wcs->y_pixel_size - wcs->ppo_coeff[5]) / 1000.0; xmm2 = xmm * xmm; ymm2 = ymm * ymm; xmm3 = xmm * xmm2; ymm3 = ymm * ymm2; x2y2 = xmm2 + ymm2; /* Compute coordinates from x,y and plate model */ xi = wcs->amd_x_coeff[ 0]*xmm + wcs->amd_x_coeff[ 1]*ymm + wcs->amd_x_coeff[ 2] + wcs->amd_x_coeff[ 3]*xmm2 + wcs->amd_x_coeff[ 4]*xmm*ymm + wcs->amd_x_coeff[ 5]*ymm2 + wcs->amd_x_coeff[ 6]*(x2y2) + wcs->amd_x_coeff[ 7]*xmm3 + wcs->amd_x_coeff[ 8]*xmm2*ymm + wcs->amd_x_coeff[ 9]*xmm*ymm2 + wcs->amd_x_coeff[10]*ymm3 + wcs->amd_x_coeff[11]*xmm*(x2y2) + wcs->amd_x_coeff[12]*xmm*x2y2*x2y2; /* Ignore magnitude and color terms + wcs->amd_x_coeff[13]*mag + wcs->amd_x_coeff[14]*mag*mag + wcs->amd_x_coeff[15]*mag*mag*mag + wcs->amd_x_coeff[16]*mag*xmm + wcs->amd_x_coeff[17]*mag*x2y2 + wcs->amd_x_coeff[18]*mag*xmm*x2y2 + wcs->amd_x_coeff[19]*color; */ eta = wcs->amd_y_coeff[ 0]*ymm + wcs->amd_y_coeff[ 1]*xmm + wcs->amd_y_coeff[ 2] + wcs->amd_y_coeff[ 3]*ymm2 + wcs->amd_y_coeff[ 4]*xmm*ymm + wcs->amd_y_coeff[ 5]*xmm2 + wcs->amd_y_coeff[ 6]*(x2y2) + wcs->amd_y_coeff[ 7]*ymm3 + wcs->amd_y_coeff[ 8]*ymm2*xmm + wcs->amd_y_coeff[ 9]*ymm*xmm2 + wcs->amd_y_coeff[10]*xmm3 + wcs->amd_y_coeff[11]*ymm*(x2y2) + wcs->amd_y_coeff[12]*ymm*x2y2*x2y2; /* Ignore magnitude and color terms + wcs->amd_y_coeff[13]*mag + wcs->amd_y_coeff[14]*mag*mag + wcs->amd_y_coeff[15]*mag*mag*mag + wcs->amd_y_coeff[16]*mag*ymm + wcs->amd_y_coeff[17]*mag*x2y2) + wcs->amd_y_coeff[18]*mag*ymm*x2y2 + wcs->amd_y_coeff[19]*color; */ /* Convert to radians */ xir = xi / cons2r; etar = eta / cons2r; /* Convert to RA and Dec */ ctan = tan (wcs->plate_dec); ccos = cos (wcs->plate_dec); raoff = atan2 (xir / ccos, 1.0 - etar * ctan); ra = raoff + wcs->plate_ra; if (ra < 0.0) ra = ra + twopi; *xpos = ra / cond2r; dec = atan (cos (raoff) / ((1.0 - (etar * ctan)) / (etar + ctan))); *ypos = dec / cond2r; return 0; } /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Changed by R.F. Warren-Smith (Starlink) to make the function static. */ static int platepix (xpos, ypos, wcs, xpix, ypix) /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> */ /* Routine to determine pixel coordinates for sky position */ /* returns 0 if successful otherwise 1 = angle too large for projection; */ /* based on amdinv() from getimage */ /* Input: */ double xpos; /* Right ascension or longitude in degrees */ double ypos; /* Declination or latitude in degrees */ struct WorldCoor *wcs; /* WCS parameter structure */ /* Output: */ double *xpix; /* x pixel number (RA or long without rotation) */ double *ypix; /* y pixel number (dec or lat without rotation) */ { double div,xi,eta,x,y,xy,x2,y2,x2y,y2x,x3,y3,x4,y4,x2y2,cjunk,dx,dy; double sypos,cypos,syplate,cyplate,sxdiff,cxdiff; double f,fx,fy,g,gx,gy, xmm, ymm; double conr2s = 206264.8062470964; double tolerance = 0.0000005; int max_iterations = 50; int i; double xr, yr; /* position in radians */ double cond2r = 1.745329252e-2; /* Convert RA and Dec in radians to standard coordinates on a plate */ xr = xpos * cond2r; yr = ypos * cond2r; sypos = sin (yr); cypos = cos (yr); syplate = sin (wcs->plate_dec); cyplate = cos (wcs->plate_dec); sxdiff = sin (xr - wcs->plate_ra); cxdiff = cos (xr - wcs->plate_ra); div = (sypos * syplate) + (cypos * cyplate * cxdiff); xi = cypos * sxdiff * conr2s / div; eta = ((sypos * cyplate) - (cypos * syplate * cxdiff)) * conr2s / div; /* Set initial value for x,y */ xmm = xi / wcs->plate_scale; ymm = eta / wcs->plate_scale; /* Iterate by Newton's method */ for (i = 0; i < max_iterations; i++) { /* X plate model */ xy = xmm * ymm; x2 = xmm * xmm; y2 = ymm * ymm; x2y = x2 * ymm; y2x = y2 * xmm; x2y2 = x2 + y2; cjunk = x2y2 * x2y2; x3 = x2 * xmm; y3 = y2 * ymm; x4 = x2 * x2; y4 = y2 * y2; f = wcs->amd_x_coeff[0]*xmm + wcs->amd_x_coeff[1]*ymm + wcs->amd_x_coeff[2] + wcs->amd_x_coeff[3]*x2 + wcs->amd_x_coeff[4]*xy + wcs->amd_x_coeff[5]*y2 + wcs->amd_x_coeff[6]*x2y2 + wcs->amd_x_coeff[7]*x3 + wcs->amd_x_coeff[8]*x2y + wcs->amd_x_coeff[9]*y2x + wcs->amd_x_coeff[10]*y3 + wcs->amd_x_coeff[11]*xmm*x2y2 + wcs->amd_x_coeff[12]*xmm*cjunk; /* magnitude and color terms ignored + wcs->amd_x_coeff[13]*mag + wcs->amd_x_coeff[14]*mag*mag + wcs->amd_x_coeff[15]*mag*mag*mag + wcs->amd_x_coeff[16]*mag*xmm + wcs->amd_x_coeff[17]*mag*(x2+y2) + wcs->amd_x_coeff[18]*mag*xmm*(x2+y2) + wcs->amd_x_coeff[19]*color; */ /* Derivative of X model wrt x */ fx = wcs->amd_x_coeff[0] + wcs->amd_x_coeff[3]*2.0*xmm + wcs->amd_x_coeff[4]*ymm + wcs->amd_x_coeff[6]*2.0*xmm + wcs->amd_x_coeff[7]*3.0*x2 + wcs->amd_x_coeff[8]*2.0*xy + wcs->amd_x_coeff[9]*y2 + wcs->amd_x_coeff[11]*(3.0*x2+y2) + wcs->amd_x_coeff[12]*(5.0*x4 +6.0*x2*y2+y4); /* magnitude and color terms ignored wcs->amd_x_coeff[16]*mag + wcs->amd_x_coeff[17]*mag*2.0*xmm + wcs->amd_x_coeff[18]*mag*(3.0*x2+y2); */ /* Derivative of X model wrt y */ fy = wcs->amd_x_coeff[1] + wcs->amd_x_coeff[4]*xmm + wcs->amd_x_coeff[5]*2.0*ymm + wcs->amd_x_coeff[6]*2.0*ymm + wcs->amd_x_coeff[8]*x2 + wcs->amd_x_coeff[9]*2.0*xy + wcs->amd_x_coeff[10]*3.0*y2 + wcs->amd_x_coeff[11]*2.0*xy + wcs->amd_x_coeff[12]*4.0*xy*x2y2; /* magnitude and color terms ignored wcs->amd_x_coeff[17]*mag*2.0*ymm + wcs->amd_x_coeff[18]*mag*2.0*xy; */ /* Y plate model */ g = wcs->amd_y_coeff[0]*ymm + wcs->amd_y_coeff[1]*xmm + wcs->amd_y_coeff[2] + wcs->amd_y_coeff[3]*y2 + wcs->amd_y_coeff[4]*xy + wcs->amd_y_coeff[5]*x2 + wcs->amd_y_coeff[6]*x2y2 + wcs->amd_y_coeff[7]*y3 + wcs->amd_y_coeff[8]*y2x + wcs->amd_y_coeff[9]*x2y + wcs->amd_y_coeff[10]*x3 + wcs->amd_y_coeff[11]*ymm*x2y2 + wcs->amd_y_coeff[12]*ymm*cjunk; /* magnitude and color terms ignored wcs->amd_y_coeff[13]*mag + wcs->amd_y_coeff[14]*mag*mag + wcs->amd_y_coeff[15]*mag*mag*mag + wcs->amd_y_coeff[16]*mag*ymm + wcs->amd_y_coeff[17]*mag*x2y2 + wcs->amd_y_coeff[18]*mag*ymm*x2y2 + wcs->amd_y_coeff[19]*color; */ /* Derivative of Y model wrt x */ gx = wcs->amd_y_coeff[1] + wcs->amd_y_coeff[4]*ymm + wcs->amd_y_coeff[5]*2.0*xmm + wcs->amd_y_coeff[6]*2.0*xmm + wcs->amd_y_coeff[8]*y2 + wcs->amd_y_coeff[9]*2.0*xy + wcs->amd_y_coeff[10]*3.0*x2 + wcs->amd_y_coeff[11]*2.0*xy + wcs->amd_y_coeff[12]*4.0*xy*x2y2; /* magnitude and color terms ignored wcs->amd_y_coeff[17]*mag*2.0*xmm + wcs->amd_y_coeff[18]*mag*ymm*2.0*xmm; */ /* Derivative of Y model wrt y */ gy = wcs->amd_y_coeff[0] + wcs->amd_y_coeff[3]*2.0*ymm + wcs->amd_y_coeff[4]*xmm + wcs->amd_y_coeff[6]*2.0*ymm + wcs->amd_y_coeff[7]*3.0*y2 + wcs->amd_y_coeff[8]*2.0*xy + wcs->amd_y_coeff[9]*x2 + wcs->amd_y_coeff[11]*(x2+3.0*y2) + wcs->amd_y_coeff[12]*(5.0*y4 + 6.0*x2*y2 + x4); /* magnitude and color terms ignored wcs->amd_y_coeff[16]*mag + wcs->amd_y_coeff[17]*mag*2.0*ymm + wcs->amd_y_coeff[18]*mag*(x2+3.0*y2); */ f = f - xi; g = g - eta; dx = ((-f * gy) + (g * fy)) / ((fx * gy) - (fy * gx)); dy = ((-g * fx) + (f * gx)) / ((fx * gy) - (fy * gx)); xmm = xmm + dx; ymm = ymm + dy; if ((fabs(dx) < tolerance) && (fabs(dy) < tolerance)) break; } /* Convert mm from plate center to plate pixels */ x = (wcs->ppo_coeff[2] - xmm*1000.0) / wcs->x_pixel_size; y = (wcs->ppo_coeff[5] + ymm*1000.0) / wcs->y_pixel_size; /* Convert from plate pixels to image pixels */ *xpix = x - wcs->x_pixel_offset + 1.0 - 0.5; *ypix = y - wcs->y_pixel_offset + 1.0 - 0.5; /* If position is off of the image, return offscale code */ /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Commented out by D.Berry (Starlink) in order to remove dependancy on NAXIS1/NAXIS2 keywords >>>>>>>> if (*xpix < 0.5 || *xpix > wcs->nxpix+0.5) return -1; if (*ypix < 0.5 || *ypix > wcs->nypix+0.5) return -1; >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> */ return 0; } /* Mar 6 1995 Original version of this code May 4 1995 Fix eta cross terms which were all in y Jun 21 1995 Add inverse routine Oct 17 1995 Fix inverse routine (degrees -> radians) Nov 7 1995 Add half pixel to image coordinates to get astrometric plate coordinates Feb 26 1996 Fix plate to image pixel conversion error Feb 18 1997 Modified by D.S. Berry (Starlink) to avoid use of the image dimensions stored in wcs->nxpix and wcs->nypix. Sep 5 1997 Modified by R.F. Warren-Smith (Starlink) to make the platepos and platepix functions static. */ ast-8.3.0/skyaxis.h0000664000175000017500000003613313004147321011101 00000000000000#if !defined( SKYAXIS_INCLUDED ) /* Include this file only once */ #define SKYAXIS_INCLUDED /* *+ * Name: * skyaxis.h * Type: * C include file. * Purpose: * Define the interface to the SkyAxis class. * Invocation: * #include "skyaxis.h" * Description: * This include file defines the interface to the SkyAxis class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The SkyAxis class extends the Axis class to represent angles on * the sky measured in radians. It provides alternative formatting * facilities for representing these coordinate values either as * angles (in degrees) or as time (in hours) using sexagesimal * notation. It also provides alternative defaults for certain * attributes and adds new attributes and methods of its own which * are needed to manipulate angular coordinates on the sky. * Inheritance: * The SkyAxis class inherits from the Axis class. * Attributes Over-Ridden: * Format (string) * The SkyAxis class defines a new syntax for this string. * Label (string) * The SkyAxis class defines new default values. These may * depend on other attribute settings. * Symbol (string) * The SkyAxis class defines new default values. These may * depend on other attribute settings. * Unit (string) * The SkyAxis class defines new default values. These may * depend on other attribute settings. * New Attributes Defined: * AsTime (integer) * A boolean value which indicates whether SkyAxis coordinate * values should be formatted for display as times (instead of * angles). It is used to determine the default format to use if * no explicit value has been set for the Format attribute. * CentreZero (integer) * A boolean value which indicates whether a SkyAxis value should * be normalised into the range [-PI,+PI] or [0,2.PI] when astNorm * is used. * IsLatitude (integer) * A boolean value which indicates whether a SkyAxis is a * latitude axis (as opposed to a longitude axis). It is used to * determine default axis labels and symbols. It also determines the * default value for the "AsTime" attribute (since longitudes on * the sky are usually expressed as times). * Methods Over-Ridden: * Public: * astAxisFormat * Format a coordinate value for a SkyAxis. * astAxisNorm * Normalise a SkyAxis coordinate value. * astAxisUnformat * Read a formatted coordinate value for a SkyAxis. * Protected: * astAxisAbbrev * Abbreviate a formatted SkyAxis value by skipping leading fields. * astAxisDistance * Find the distance between two SkyAxis values. * astAxisGap * Find a "nice" gap for tabulating SkyAxis values. * astClearAxisFormat * Clear the Format attribute for a SkyAxis. * astGetAxisDirection * Obtain the value of the Direction attribute for a SkyAxis. * astGetAxisFormat * Obtain a pointer to the Format attribute for a SkyAxis. * astGetAxisLabel * Obtain a pointer to the Label attribute for a SkyAxis. * astGetAxisSymbol * Obtain a pointer to the Symbol attribute for a SkyAxis. * astGetAxisUnit * Obtain a pointer to the Unit attribute for a SkyAxis. * astSetAxisFormat * Set a value for the Format attribute of a SkyAxis. * astTestAxisFormat * Test if a value has been set for the Format attribute of a SkyAxis. * astAxisOffset * Add an increment onto a supplied SkyAxis value. * astAxisOverlay * Overlay the attributes of a template SkyAxis on to another Axis. * astSetAttrib * Set an attribute value for a SkyAxis. * New Methods Defined: * Public: * None. * Protected: * astClearAxisAsTime * Clear the AsTime attribute for a SkyAxis. * astClearAxisCentreZero * Clear the CentreZero attribute for a SkyAxis. * astClearAxisIsLatitude * Clear the IsLatitude attribute for a SkyAxis. * astGetAxisAsTime * Obtain the value of the AsTime attribute for a SkyAxis. * astGetAxisIsLatitude * Obtain the value of the IsLatitude attribute for a SkyAxis. * astGetAxisCentreZero * Obtain the value of the CentreZero attribute for a SkyAxis. * astSetAxisAsTime * Set a value for the AsTime attribute of a SkyAxis. * astSetAxisIsLatitude * Set a value for the IsLatitude attribute of a SkyAxis. * astSetAxisCentreZero * Set a value for the CentreZero attribute of a SkyAxis. * astTestAxisAsTime * Test if a value has been set for the AsTime attribute of a SkyAxis. * astTestAxisIsLatitude * Test if a value has been set for the IsLatitude attribute of a * SkyAxis. * astTestAxisCentreZero * Test if a value has been set for the CentreZero attribute of a * SkyAxis. * Other Class Functions: * Public: * astIsASkyAxis * Test class membership. * astSkyAxis * Create an SkyAxis. * Protected: * astCheckSkyAxis * Validate class membership. * astInitSkyAxis * Initialise an SkyAxis. * Macros: * None. * Type Definitions: * Public: * AstSkyAxis * SkyAxis object type. * Protected: * AstSkyAxisVtab * SkyAxis virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 29-MAR-1996 (RFWS): * Original version. * 25-APR-1996 (RFWS): * Made all attribute access functions protected. * 13-MAY-1996 (RFWS): * Documented over-riding of the astGetAxisDirection method. * 26-FEB-1998 (RFWS): * Over-ride the astAxisUnformat method. * 8-JAN-2003 (DSB): * Added protected astInitSkyAxisVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "axis.h" /* Coordinate axes (parent class) */ /* Macros */ /* ====== */ /* Define constants used to size global arrays in this module. */ /* Define numerical constants for use in thie module. */ #define AST__SKYAXIS_GETAXISFORMAT_BUFF_LEN 50 #define AST__SKYAXIS_DHMSFORMAT_BUFF_LEN 70 #define AST__SKYAXIS_DHMSUNIT_BUFF_LEN 17 #define AST__SKYAXIS_GETATTRIB_BUFF_LEN 50 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* SkyAxis structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSkyAxis { /* Attributes inherited from the parent class. */ AstAxis axis; /* Parent class structure */ /* Attributes specific to objects in this class. */ char *skyformat; /* Pointer to sky format string */ int as_time; /* Format angles as time (hours)? */ int is_latitude; /* SkyAxis is a latitude axis? */ int centrezero; /* Normalised range is zero-centred? */ } AstSkyAxis; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSkyAxisVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstAxisVtab axis_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetAxisAsTime)( AstSkyAxis *, int * ); int (* GetAxisIsLatitude)( AstSkyAxis *, int * ); int (* GetAxisCentreZero)( AstSkyAxis *, int * ); int (* TestAxisAsTime)( AstSkyAxis *, int * ); int (* TestAxisIsLatitude)( AstSkyAxis *, int * ); int (* TestAxisCentreZero)( AstSkyAxis *, int * ); void (* ClearAxisAsTime)( AstSkyAxis *, int * ); void (* ClearAxisIsLatitude)( AstSkyAxis *, int * ); void (* ClearAxisCentreZero)( AstSkyAxis *, int * ); void (* SetAxisAsTime)( AstSkyAxis *, int, int * ); void (* SetAxisIsLatitude)( AstSkyAxis *, int, int * ); void (* SetAxisCentreZero)( AstSkyAxis *, int, int * ); } AstSkyAxisVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstSkyAxisGlobals { AstSkyAxisVtab Class_Vtab; int Class_Init; char DHmsFormat_Buff[ AST__SKYAXIS_DHMSFORMAT_BUFF_LEN + 1 ]; char DHmsUnit_Buff[ AST__SKYAXIS_DHMSUNIT_BUFF_LEN + 1 ]; char GetAttrib_Buff[ AST__SKYAXIS_GETATTRIB_BUFF_LEN + 1 ]; char GetAxisFormat_Buff[ AST__SKYAXIS_GETAXISFORMAT_BUFF_LEN + 1 ]; char *GhDelim; char *GmDelim; char *GsDelim; char *GdDelim; char *GamDelim; char *GasDelim; } AstSkyAxisGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SkyAxis) /* Check class membership */ astPROTO_ISA(SkyAxis) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSkyAxis *astSkyAxis_( const char *, int *, ...); #else AstSkyAxis *astSkyAxisId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSkyAxis *astInitSkyAxis_( void *, size_t, int, AstSkyAxisVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitSkyAxisVtab_( AstSkyAxisVtab *, const char *, int * ); /* Loader. */ AstSkyAxis *astLoadSkyAxis_( void *, size_t, AstSkyAxisVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitSkyAxisGlobals_( AstSkyAxisGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ int astGetAxisAsTime_( AstSkyAxis *, int * ); int astGetAxisIsLatitude_( AstSkyAxis *, int * ); int astGetAxisCentreZero_( AstSkyAxis *, int * ); int astTestAxisAsTime_( AstSkyAxis *, int * ); int astTestAxisIsLatitude_( AstSkyAxis *, int * ); int astTestAxisCentreZero_( AstSkyAxis *, int * ); void astClearAxisAsTime_( AstSkyAxis *, int * ); void astClearAxisIsLatitude_( AstSkyAxis *, int * ); void astClearAxisCentreZero_( AstSkyAxis *, int * ); void astSetAxisAsTime_( AstSkyAxis *, int, int * ); void astSetAxisIsLatitude_( AstSkyAxis *, int, int * ); void astSetAxisCentreZero_( AstSkyAxis *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSkyAxis(this) astINVOKE_CHECK(SkyAxis,this,0) #define astVerifySkyAxis(this) astINVOKE_CHECK(SkyAxis,this,1) /* Test class membership. */ #define astIsASkyAxis(this) astINVOKE_ISA(SkyAxis,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSkyAxis astINVOKE(F,astSkyAxis_) #else #define astSkyAxis astINVOKE(F,astSkyAxisId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSkyAxis(mem,size,init,vtab,name) \ astINVOKE(O,astInitSkyAxis_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSkyAxisVtab(vtab,name) astINVOKE(V,astInitSkyAxisVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSkyAxis(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSkyAxis_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSkyAxis to validate SkyAxis pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearAxisAsTime(this) \ astINVOKE(V,astClearAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) #define astClearAxisIsLatitude(this) \ astINVOKE(V,astClearAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) #define astGetAxisAsTime(this) \ astINVOKE(V,astGetAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) #define astGetAxisIsLatitude(this) \ astINVOKE(V,astGetAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) #define astSetAxisAsTime(this,value) \ astINVOKE(V,astSetAxisAsTime_(astCheckSkyAxis(this),value,STATUS_PTR)) #define astSetAxisIsLatitude(this,value) \ astINVOKE(V,astSetAxisIsLatitude_(astCheckSkyAxis(this),value,STATUS_PTR)) #define astTestAxisAsTime(this) \ astINVOKE(V,astTestAxisAsTime_(astCheckSkyAxis(this),STATUS_PTR)) #define astTestAxisIsLatitude(this) \ astINVOKE(V,astTestAxisIsLatitude_(astCheckSkyAxis(this),STATUS_PTR)) #define astClearAxisCentreZero(this) \ astINVOKE(V,astClearAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) #define astGetAxisCentreZero(this) \ astINVOKE(V,astGetAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) #define astSetAxisCentreZero(this,value) \ astINVOKE(V,astSetAxisCentreZero_(astCheckSkyAxis(this),value,STATUS_PTR)) #define astTestAxisCentreZero(this) \ astINVOKE(V,astTestAxisCentreZero_(astCheckSkyAxis(this),STATUS_PTR)) #endif #endif ast-8.3.0/object.h.in0000664000175000017500000020365113004147321011262 00000000000000#if !defined( OBJECT_INCLUDED ) /* Include this file only once */ #define OBJECT_INCLUDED /* *++ * Name: * object.h * Type: * C include file. * Purpose: * Define the interface to the Object class. * Invocation: * #include "object.h" * Description: * This include file defines the interface to the Object class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * The Object class is the base class from which all other classes * in the AST library are derived. This class provides all the * basic Object behaviour and Object manipulation facilities * required throughout the library. There is no Object constructor, * however, as Objects on their own are not of much use. * Inheritance: * The Object base class does not inherit from any other class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Class (string) * This is a read-only attribute containing the name of the * class to which an Object belongs. * ID (string) * An identification string which may be used to identify the * Object (e.g.) in debugging output, or when stored in an * external medium such as a data file. There is no restriction * on the string's contents. The default is an empty string. * Ident (string) * Like ID, this is an identification string which may be used * to identify the Object. Unlike ID, Ident is transferred when an * Object is copied. * UseDefs (int) * Should default values be used for unset attributes? * Nobject (integer) * This is a read-only attribute which gives the total number of * Objects currently in existence in the same class as the * Object given. It does not include Objects which belong to * derived (more specialised) classes. This value is mainly * intended for debugging, as it can be used to show whether * Objects which should have been deleted have, in fact, been * deleted. * ObjSize (int) * The in-memory size of the Object in bytes. * RefCount (integer) * This is a read-only Attribute which gives the "reference * count" (the number of active pointers) associated with an * Object. It is modified whenever pointers are created or * annulled (by astClone or astAnnul/astEnd for example) and * includes the initial pointer issued when the Object was * created. If the reference count for an Object falls to zero * as the result of annulling a pointer to it, then the Object * will be deleted. * Methods Over-Ridden: * None. * New Methods Defined: * Public: * astAnnul * Annul a pointer to an Object. * astClear * Clear attribute values for an Object. * astClone * Clone a pointer to an Object. * astCopy * Copy an Object. * astDelete * Delete an Object. * astExempt * Exempt an Object pointer from AST context handling * astExport * Export an Object pointer to an outer context. * astGet, where = C, D, F, I, L * Get an attribute value for an Object. * astImport * Import an Object pointer into the current context. * astSame * Return true if two pointers refer to the same object. * astSet * Set attribute values for an Object. * astSet, where = C, D, F, I, L * Set an attribute value for an Object. * astShow * Display a textual representation of an Object on standard output. * astTest * Test if an attribute value is set for an Object. * astTune * Get or set the value of a global AST tuning parameter. * * Protected: * astAnnulId * Annul an external ID for an Object (for use from protected code * which must handle external IDs). * astClearAttrib * Clear the value of a specified attribute for an Object. * astClearID * Clear the value of the ID attribute for an Object. * astClearIdent * Clear the value of the Ident attribute for an Object. * astCast * Return a deep copy of an object, cast into an instance of a * parent class. * astDump * Write an Object to a Channel. * astEqual * Are two Objects equivalent? * astGetAttrib * Get the value of a specified attribute for an Object. * astGetClass (deprecated synonym astClass) * Obtain the value of the Class attribute for an Object. * astGetID * Obtain the value of the ID attribute for an Object. * astGetIdent * Obtain the value of the Ident attribute for an Object. * astGetNobject * Obtain the value of the Nobject attribute for an Object. * astGetRefCount * Obtain the value of the RefCount attribute for an Object. * astSetAttrib * Set the value of a specified attribute for an Object. * astSetCopy * Declare a copy constructor for an Object. * astSetDelete * Declare a destructor for an Object. * astSetDump * Declare a dump function for an Object. * astSetVtab * Chaneg the virtual function table associated with an Object. * astSetID * Set the value of the ID attribute for an Object. * astSetIdent * Set the value of the Ident attribute for an Object. * astTestAttrib * Test if a specified attribute value is set for an Object. * astTestID * Test whether the ID attribute for an Object is set. * astTestIdent * Test whether the Ident attribute for an Object is set. * astVSet * Set values for an Object's attributes. * Other Class Functions: * Public: * astBegin * Begin a new AST context. * astEnd * End an AST context. * astIsAObject * Test class membership. * astVersion * Returns the AST library version number. * astEscapes * Remove escape sequences from returned text strings? * astP2I * Retrieve an int from a pointer. * astI2P * Pack an int into a pointer. * * Protected: * astCheckObject * Validate class membership. * astInitObject * Initialise an Object. * astInitObjectVtab * Initialise the virtual function table for the Object class. * astLoadObject * Load an Object. * astMakeId * Issue an identifier for an Object. * astMakePointer * Obtain a true C pointer from an Object identifier. * Macros: * Public: * AST__NULL * Null Object pointer value. * AST__VMAJOR * The AST library major version number. * AST__VMINOR * The AST library minor version number. * AST__RELEASE * The AST library release number. * * Protected: * astEQUAL * Compare two doubles for equality. * astMAX * Return maximum of two values. * astMIN * Return minimum of two values. * astMAKE_CHECK * Implement the astCheck_ function for a class. * astMAKE_CLEAR * Implement a method to clear an attribute value for a class. * astMAKE_GET * Implement a method to get an attribute value for a class. * astMAKE_ISA * Implement the astIsA_ function for a class. * astMAKE_SET * Implement a method to set an attribute value for a class. * astMAKE_TEST * Implement a method to test if an attribute has been set for a * class. * astMEMBER * Locate a member function. * Type Definitions: * Public: * AstObject * Object type. * * Protected: * AstObjectVtab * Object virtual function table type. * Feature Test Macros: * AST_CHECK_CLASS * If the AST_CHECK_CLASS macro is defined, then Object class * checking is enabled for all internal function invocations * within the AST library. Otherwise, this checking is * omitted. This macro should normally be defined as a compiler * option during library development and debugging, but left * undefined for software releases, so as to improve * peformance. Class checking by the AST public interface is not * affected by this macro. * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * astFORTRAN77 * If the astFORTRAN77 macro is defined, reporting of error * context information is suppressed. This is necessary when * implementing foreign language interfaces to the AST library, as * otherwise the file names and line numbers given would refer * to the interface implementation rather than the user's own * code. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 30-JAN-1996 (RFWS): * Original version. * 19-APR-1996 (RFWS): * Added macros for implementing attribute access methods. * 3-JUL-1996 (RFWS): * Added new definitions to support the external interface. * 10-SEP-1996 (RFWS): * Added loader and related facilities. * 30-MAY-1997 (RFWS): * Add the ID attribute. * 14-JUL-1997 (RFWS): * Add astExempt function. * 20-JAN-1998 (RFWS): * Make the astClear and astVSet methods virtual. * 15-SEP-1999 (RFWS): * Made the astAnnulId function accessible to protected code. * 3-APR-2001 (DSB): * Added Ident attribute. * 8-JAN-2003 (DSB): * Added protected astInitObjectVtab method. * 30-APR-2003 (DSB): * Added macros AST__VMAJOR, AST__VMINOR and AST__RELEASE. * Added astVersion function. * 7-FEB-2004 (DSB): * Added astEscapes function. * 11-MAR-2005 (DSB): * Added UseDefs attribute. * 7-FEB-2006 (DSB): * Added astTune function. * 14-FEB-2006 (DSB): * Added ObjSize attribute. * 23-FEB-2006 (DSB): * Moved AST__TUNULL from this file to memory.h. * 10-MAY-2006 (DSB): * Added astEQUAL, astMAX and astMIN. * 26-MAY-2006 (DSB): * Make all system includes unconditional, so that makeh is not * confused when creating ast.h. * 22-JUN-2007 (DSB): * - Make astVSet return a pointer to dynamic memory holding the * expanded setting string. * - Add ast astSetVtab and astCast. * 22-APR-2008 (DSB): * Added astSame. * 7-APR-2010 (DSB): * Added astHasAttribute. *-- */ /* Include files. */ /* ============== */ /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* Interface definitions. */ /* ---------------------- */ #include "error.h" /* Error reporting facilities */ #include "version.h" /* Version number macros */ /* C header files. */ /* --------------- */ #include #include #include #include #if defined(THREAD_SAFE) #include #endif /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Set to "1" (yes) or "0" (no) to indicate if AST was build with threads support. */ #define AST__THREADSAFE @THREADS@ #if defined(astCLASS ) #define AST__GETATTRIB_BUFF_LEN 50 /* Length of string returned by GetAttrib. */ #define AST__ASTGETC_MAX_STRINGS 50 /* Number of string values to buffer within astGetC */ /* Values supplied to astManageLock */ #define AST__LOCK 1 /* Lock the object */ #define AST__UNLOCK 2 /* Unlock the object */ #define AST__CHECKLOCK 3 /* Check if the object is locked */ /* Values returned by astThread */ #define AST__UNLOCKED 1 /* Object is unlocked */ #define AST__RUNNING 2 /* Object is locked by the running thread */ #define AST__OTHER 3 /* Object is locked by another thread */ #endif /* Value that indicates that two classes are not in direct line from each other. */ #if defined(astCLASS ) #define AST__COUSIN -1000000 #endif /* *+ * Name: * astINVOKE * Type: * Protected macro. * Purpose: * Invoke an AST function. * Synopsis: * #include "object.h" * astINVOKE(rettype,function) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an invocation of an AST function, together * with any additional actions required to support it. The actual * expansion depends on whether the macro is expanded in internal * code (astCLASS defined) or external code (astCLASS undefined) * and it therefore hides the differences between these two * interfaces. * Parameters: * rettype * A character to indicate the type of result returned by the function: * * V * The function returns a value (including void or a pointer * value, but excluding an Object pointer). astINVOKE will * return the value unchanged. * O * The function returns an Object pointer. astINVOKE will * convert it to an Object identifier if necessary. * F * The function returns a function pointer. astINVOKE will * return it unchanged. This is typically used when the * function has a variable argument list. In this case the * function name is passed to astINVOKE without its argument * list and a pointer to the function is returned which can * then be supplied with an argument list. This avoids the * need to define a macro with a variable number of arguments * (which isn't allowed). * function * A normal invocation of the function returning the required * result. In the case of a variable argument list, the * argument list should be omitted so that the function is not * invoked but a function pointer is returned that may then be * used to invoke it. * Examples: * #define astGetNobject(this) \ * astINVOKE(V,astGetNobject_(astCheckObject(this))) * Defines a macro to invoke the astGetNobject_ function which * returns an int. * #define astClone(this) \ * astINVOKE(O,astClone_(astCheckObject(this))) * Defines a macro to invoke the astClone_ function which * returns an Object pointer. * #define astSet astINVOKE(F,astSet_) * Defines a macro to invoke the astSet_ function which has a * variable argument list and returns void. The macro result is * a pointer to the astSet_ function. This function must perform * its own argument validation, as (e.g) astCheckObject cannot * be invoked on its arguments via a macro. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define astINVOKE, which records the current file and line number (in case of error) using astAt, and then invokes the function supplied as an argument of the astRetV_, astRetO_ or astRetF_ macro. Suppress reporting of the file and line number from internal code and from foreign language interfaces by not using astAt in these cases. */ #if defined(astCLASS) || defined(astFORTRAN77) #define astINVOKE(rettype,function) astRet##rettype##_(function) #else #define astINVOKE(rettype,function) \ astERROR_INVOKE(astRet##rettype##_(function)) #endif /* astRetF_ and astRetV_ currently do nothing. */ #define astRetF_(x) (x) #define astRetV_(x) (x) /* However, astRetO_ converts a pointer to an ID if necessary. */ #if defined(astCLASS) #define astRetO_(x) ((void *)(x)) #else #define astRetO_(x) ((void *)astMakeId_((AstObject *)(x),STATUS_PTR)) #endif /* *+ * Name: * astINVOKE_CHECK * astINVOKE_ISA * Type: * Protected macros. * Purpose: * Invoke the astCheck_ and astIsA_ functions. * Synopsis: * #include "object.h" * astINVOKE_CHECK(class,this,force) * astINVOKE_ISA(class,this) * Class Membership: * Defined by the Object class. * Description: * These macros expand to invocations of the standard * astCheck_ and astIsA_ functions for a class. * Parameters: * class * The name (not the type) of the class for which the function * is to be invoked. * this * The "this" argument (the Object pointer) to be passed to the * function. * force * Type checking takes time, and so can be disabled within the * protected context in order to save time. Setting "force" to * zero causes the astINVOKE_CHECK macro to skip the class check * in a protected context (it assumes that AST "knows what it is * doing"). Setting "force" to a non-zero value forces the class * check even in a protected context. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* For the public interface (and also internally if AST_CHECK_CLASS is defined), define astINVOKE_CHECK to invoke the astCheck function. */ #if !defined(astCLASS) || defined(AST_CHECK_CLASS) #define astINVOKE_CHECK(class,this,force) \ astCheck##class##_((Ast##class *)astEnsurePointer_(this),astGetStatusPtr) /* For the internal interface, astINVOKE_CHECK omits the astCheck function (unless AST_CHECK_CLASS is defined). */ #else #define astINVOKE_CHECK(class,this,force) ( (force) ? \ ( astCheck##class##_((Ast##class *)astEnsurePointer_(this),astGetStatusPtr) ) : \ ( (Ast##class *) astEnsurePointer_(this) ) ) #endif /* Define astINVOKE_ISA to invoke the astIsA function. */ #if defined(astCLASS) /* Protected */ #define astINVOKE_ISA(class,this) \ astIsA##class##_((const Ast##class *)(this),status) #else /* Public */ #define astINVOKE_ISA(class,this) \ astINVOKE(V,astIsA##class##_((const Ast##class *)astEnsurePointer_(this),astGetStatusPtr)) #endif /* The astEnsurePointer_ macro ensures a true C pointer, converting from an ID if necessary. */ #if defined(astCLASS) /* Protected */ #define astEnsurePointer_(x) ((void *)(x)) #else /* Public */ #define astEnsurePointer_(x) ((void *)astCheckLock_(astMakePointer_((AstObject *)(x),STATUS_PTR),STATUS_PTR)) #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CHECK * Type: * Protected macro. * Purpose: * Implement the astCheck_ function for a class. * Synopsis: * #include "object.h" * astMAKE_CHECK(class) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of the public astCheck_ * function (q.v.) which validates membership of a specified class. * Parameters: * class * The name (not the type) of the class whose membership is to be * validated. * Notes: * - This macro is provided so that class definitions can easiy * implement the astCheck_ function, which is essentially the same * for each class apart for a change of name. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ #ifndef MEM_DEBUG /* Define the macro. */ #define astMAKE_CHECK(class) \ \ /* Declare the function (see the object.c file for a prologue). */ \ Ast##class *astCheck##class##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return this; \ \ /* Check if the object is a class member. */ \ if ( !astIsA##class( this ) ) { \ \ /* If not, but the pointer was valid (which means it identifies an Object \ of some sort), then report more information about why this Object is \ unsuitable. */ \ if ( astOK ) { \ astError( AST__OBJIN, "Pointer to " #class " required, but pointer " \ "to %s given.", status, astGetClass( this ) ); \ } \ } \ \ /* Return the pointer value supplied. */ \ return this; \ } /* Define the macro with memory debugging facilities. */ #else #define astMAKE_CHECK(class) \ \ /* Declare the function (see the object.c file for a prologue). */ \ Ast##class *astCheck##class##_( Ast##class *this, int *status ) { \ \ char buf[100]; \ \ /* Check the inherited error status. */ \ if ( !astOK ) return this; \ \ /* Check if the object is a class member. */ \ if ( !astIsA##class( this ) ) { \ \ /* If not, but the pointer was valid (which means it identifies an Object \ of some sort), then report more information about why this Object is \ unsuitable. */ \ if ( astOK ) { \ astError( AST__OBJIN, "Pointer to " #class " required, but pointer " \ "to %s given.", status, astGetClass( this ) ); \ }\ \ } else { \ \ /* Call the astMemoryUse function to report it if the memory block is \ being watched. */ \ sprintf( buf, "checked (refcnt: %d)", astGetRefCount_( (AstObject *) this, status ) ); \ astMemoryUse( this, buf ); \ } \ \ /* Return the pointer value supplied. */ \ return this; \ } #endif #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CLEAR * Purpose: * Implement a method to clear an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_CLEAR(class,attribute,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( Ast *this ) * * and an external interface function of the form: * * void astClear_( Ast *this ) * * which implement a method for clearing a specified attribute value for * a class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabel"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * Examples: * astMAKE_CLEAR(MyStuff,Flag,flag,-1) * Implements the astClearFlag method for the MyStuff class which * operates by setting the "flag" structure component to -1 to indicate * that it has no value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_CLEAR(class,attribute,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Assign the "clear" value. */ \ this->component = (assign); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Clear##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CLEAR1 * Purpose: * Implement a method to clear an attribute value for a class, reporting * an error if the object has more than one reference. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_CLEAR1(class,attribute,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( Ast *this ) * * and an external interface function of the form: * * void astClear_( Ast *this ) * * which implement a method for clearing a specified attribute value for * a class. An error is reported if the object has a reference count that * is greater than one. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabel"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_CLEAR1(class,attribute,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astClear(%s): The " #attribute "attribute of " \ "the supplied %s cannot be cleared because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, assign the "clear" value in the structure component. */ \ } else { \ this->component = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Clear##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_GET * Purpose: * Implement a method to get an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_GET(class,attribute,type,bad_value,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( Ast *this ) * * and an external interface function of the form: * * astGet_( Ast *this ) * * which implement a method for getting a specified attribute value for a * class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the inherited error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. * Examples: * astMAKE_GET(MyStuff,Flag,int,0,( this->flag == 1 )) * Implements the astGetFlag method for the MyStuff class which operates * by examining the integer "flag" structure component and comparing it * with the value 1 to see if it is set. A value of 0 is returned if the * method fails to complete successfully. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_GET(class,attribute,type,bad_value,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attribute( Ast##class *this, int *status ) { \ type result; /* Result to be returned */ \ \ /* Check the inherited error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Assign the result value. */ \ result = (assign); \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,class,Get##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_ISA * Type: * Protected macro. * Purpose: * Implement the astIsA_ function for a class. * Synopsis: * #include "object.h" * astMAKE_ISA(class,parent) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of the public * astIsA_ function (q.v.) which checks membership of a * specified class. * Parameters: * class * The name (not the type) of the class whose membership is to be * tested. * parent * The name of the parent class. * Notes: * - This macro is provided so that class definitions can easiy * implement the astIsA_ function, which is essentially the * same for each class apart for a change of name. * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_ISA(class,parent) \ \ /* Declare the function (see the object.c file for a prologue). */ \ int astIsA##class##_( const Ast##class *this, int *status ) { \ \ /* Local Variables: */ \ int isa = 0; /* Is object a member? */ \ \ /* To test if the object is correctly constructed, we first test if it is a \ member of the parent class. This improves the security of the test by \ checking the object structure from the base Object class downwards \ (without this, the "magic numbers" that identify classes might be \ encountered by accident or we might address parts of the Object which \ don't exist). */ \ if ( astIsA##parent( this ) ) { \ \ /* Obtain the Object's size and check it is adequate for an object of the \ proposed type (this avoids any attempt to access derived class data that \ doesn't exist and therefore lies outside the memory allocated for the \ object). */ \ if ( ( (AstObject *) this )->size >= sizeof( Ast##class ) ) { \ \ /* If OK, see whether the check component in the object's virtual function \ table matches the expected "magic" value. */ \ isa = ( *astMEMBER(this,class,id.check) == &class_check ); \ } \ } \ \ /* Return the result. */ \ return isa; \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_SET * Purpose: * Implement a method to set an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_SET(class,attribute,type,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( Ast *this, value ) * * and an external interface function of the form: * * void astSet_( Ast *this, value ) * * which implement a method for setting a specified attribute value for a * class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * Examples: * astMAKE_SET(MyStuff,Flag,int,flag,( value != 0 )) * Implements the astSetFlag method for the MyStuff class which operates * by setting the "flag" structure component to 0 or 1 depending on * whether the "value" parameter is non-zero or not. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_SET(class,attribute,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Store the new value in the structure component. */ \ this->component = (assign); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Set##attribute))( this, value, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_SET1 * Purpose: * Implement a method to set an attribute value for a class, reporting * an error if the object has more than one reference. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_SET1(class,attribute,type,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( Ast *this, value ) * * and an external interface function of the form: * * void astSet_( Ast *this, value ) * * which implement a method for setting a specified attribute value for a * class. An error is reported if the object has a reference count that * is greater than one. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. *- */ /* Define the macro. */ #define astMAKE_SET1(class,attribute,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astSet(%s): The " #attribute "attribute of " \ "the supplied %s cannot be changed because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, store the new value in the structure component. */ \ } else { \ this->component = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Set##attribute))( this, value, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_TEST * Purpose: * Implement a method to test if an attribute has been set for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_TEST(class,attribute,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( Ast *this ) * * and an external interface function of the form: * * int astTest_( Ast *this ) * * which implement a method for testing if a specified attribute has been * set for a class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be tested, as it appears in the function * name (e.g. Label in "astTestLabel"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. * Examples: * astMAKE_TEST(MyStuff,Flag,( this->flag != -1 )) * Implements the astTestFlag method for the MyStuff class which operates * by testing the "flag" structure component to see if it is set to a * value other than -1. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_TEST(class,attribute,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attribute( Ast##class *this, int *status ) { \ int result; /* Value to return */ \ \ /* Check the inherited error status. */ \ if ( !astOK ) return 0; \ \ /* Assign the result value. */ \ result = (assign); \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,class,Test##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMEMBER * Purpose: * Locate a member function. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMEMBER(this,class,method) * Class Membership: * Defined by the Object class. * Description: * This macro evaluates to the address where the pointer to a * specified Object member function is stored. Typically, this will * be used to obtain a pointer to the member function so that it * can be invoked. It may also be used to assign a new function * pointer so that a derived class can re-define a virtual function * and hence over-ride an inherited method. * Parameters: * this * Pointer to an Object belonging to the class for which the * virtual function is required. This must either be the class * that originally defined the method, or one derived from it. * class * Name of the class that originally defined the method. This * may differ from (i.e. be an ancestor of) the class to which * "this" belongs. * method * Name of the method whose member function is to be located. * Returned Value: * The address where the member function pointer is stored (the * type of the result is determined by the type of the member * function itself). * Examples: * astMEMBER(this,Gnome,astFish) * Returns the address where the pointer to the function that * implements the astFish method for the "this" object is * stored. The Gnome class should be where the astFish method * was first defined (i.e. from where it was inherited by * "this"). * (**astMEMBER(this,Gnome,astFish))( this, arg1, arg2 ); * Invokes the virtual function that implements the astFish * method for object "this" and passes it additional arguments * "arg2" and "arg2". Again, Gnome should be the class that * originally defined the astFish method. * *astMEMBER(this,Gnome,astFish) = myFish; * Stores a pointer to the myFish function so that it replaces * the virtual function that previously implemented the astFish * method for the "this" object. Note that all objects in the * same class as "this" are affected, but objects in class * "class" are not affected (unless it happens to be the class * to which "this" belongs). * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* A subsiduary macro that returns a pointer to the vtab of an object, cast to an AstObjectVtab. */ #define astVTAB(this) (((AstObject*)(this))->vtab) /* Define the macro. This functions by (a) casting the Object pointer to type (AstObject *) and locating the Object's virtual function table (b) casting the table pointer to the correct type (AstClassVtab *) for the class in which the method pointer resides, (c) locating the component holding the member function pointer, and (d) taking its address. */ #define astMEMBER(this,class,method) \ (&((Ast##class##Vtab*)astVTAB(this))->method) #endif /* *+ * Name: * astPROTO_CHECK * astPROTO_ISA * Type: * Protected macros. * Purpose: * Prototype the astCheck_ and astIsA_ functions. * Synopsis: * #include "object.h" * astPROTO_CHECK(class) * astPROTO_ISA(class) * Class Membership: * Defined by the Object class. * Description: * These macros expands to function prototypes for the * astCheck_ and astIsA_ functions (q.v.) which * validate and test for membership of a specified class. * Parameters: * class * The name (not the type) of the class whose membership is to * be validated. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macros. */ #define astPROTO_CHECK(class) Ast##class *astCheck##class##_( Ast##class *, int * ); #define astPROTO_ISA(class) int astIsA##class##_( const Ast##class *, int * ); /* Macros which return the maximum and minimum of two values. */ #define astMAX(aa,bb) ((aa)>(bb)?(aa):(bb)) #define astMIN(aa,bb) ((aa)<(bb)?(aa):(bb)) /* Check for equality of floating point values. We cannot compare bad values directly because of the danger of floating point exceptions, so bad values are dealt with explicitly. */ #define astEQUALS(aa,bb,tol) (((aa)==AST__BAD)?(((bb)==AST__BAD)?1:0):(((bb)==AST__BAD)?0:(fabs((aa)-(bb))<=(tol)*astMAX((fabs(aa)+fabs(bb))*DBL_EPSILON,DBL_MIN)))) #define astEQUAL(aa,bb) astEQUALS(aa,bb,1.0E5) /* AST__NULL. */ /* ---------- */ /* Define the AST__NULL macro, which evaluates to a null Object pointer. */ #define AST__NULL (astI2P(0)) #if defined(astCLASS) /* Protected */ /* Test the validy of an attribute value */ /* ------------------------------------- */ /* If the set attribute value is invalid, clear it. These macros should be used in a context in which error reporting has been deferred by calling astReporting( 0 ). */ #define astCLEAN_ATTRIB(attr) \ if( astTest##attr(this) ) { \ astSet##attr( this, astGet##attr( this ) ); \ if( !astOK ) { \ astClearStatus; \ astClear##attr( this ); \ } \ } #define astCLEAN_INDEXED_ATTRIB(attr,index) \ if( astTest##attr(this,index) ) { \ astSet##attr( this, index, astGet##attr( this, index ) ); \ if( !astOK ) { \ astClearStatus; \ astClear##attr( this, index ); \ } \ } #endif #if defined(astCLASS) /* Protected */ #define astSetVtabClassIdentifier(vtab,id_ptr) \ ((AstObjectVtab *)(vtab))->top_id = (id_ptr) #endif /* Type Definitions. */ /* ================= */ /* Object structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstObject { /* Attributes specific to objects in this class. */ unsigned long check; /* Check value to identify Objects */ size_t size; /* Amount of memory used by Object */ struct AstObjectVtab *vtab; /* Pointer to virtual function table */ char dynamic; /* Memory allocated dynamically? */ int ref_count; /* Number of active pointers to the Object */ char *id; /* Pointer to ID string */ char *ident; /* Pointer to Ident string */ char usedefs; /* Use default attribute values? */ int iref; /* Object index (unique within class) */ void *proxy; /* A pointer to an external object that acts as a foreign language proxy for the AST object */ #if defined(THREAD_SAFE) int locker; /* Thread that has locked this Object */ pthread_mutex_t mutex1; /* Guards access to all elements of the Object except for the "locker" and "ref_count" components */ pthread_mutex_t mutex2; /* Guards access to the "locker" and "ref_count" components */ struct AstGlobals *globals; /* Pointer to thread-specific global data */ #endif } AstObject; /* Class identifier structure */ typedef struct AstClassIdentifier { int *check; struct AstClassIdentifier *parent; } AstClassIdentifier; /* Virtual function table. */ /* ----------------------- */ /* The virtual function table makes a forward reference to the AstChannel structure which is not defined until "channel.h" is included (below). Hence make a preliminary definition available now. */ struct AstChannel; /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstObjectVtab { /* A unique identifier for this class. */ AstClassIdentifier id; /* Pointer to the structure that identifies the top-level class described by the whole vtab (of which the AstObjectVtab is just the first, lowest-level, component). */ AstClassIdentifier *top_id; /* Pointer to a dynamically allocated string holding the default attribute values to use when creating new objects. These are read from environment variables of the form "_OPTIONS". */ const char *defaults; /* Properties specific to this class. */ void ( *CleanAttribs )( AstObject *, int * ); AstObject *( *Cast )( AstObject *, AstObject *, int * ); const char *( *GetID )( AstObject *, int * ); const char *( *GetIdent )( AstObject *, int * ); const char *(* GetAttrib)( AstObject *, const char *, int * ); int (* TestAttrib)( AstObject *, const char *, int * ); int (* TestID)( AstObject *, int * ); int (* Same)( AstObject *, AstObject *, int * ); int (* HasAttribute)( AstObject *, const char *, int * ); int (* TestIdent)( AstObject *, int * ); void (* Clear)( AstObject *, const char *, int * ); void (* ClearAttrib)( AstObject *, const char *, int * ); void (* ClearID)( AstObject *, int * ); void (* ClearIdent)( AstObject *, int * ); void (* Dump)( AstObject *, struct AstChannel *, int * ); int (* Equal)( AstObject *, AstObject *, int * ); void (* SetAttrib)( AstObject *, const char *, int * ); void (* SetID)( AstObject *, const char *, int * ); void (* SetIdent)( AstObject *, const char *, int * ); void (* Show)( AstObject *, int * ); void (* VSet)( AstObject *, const char *, char **, va_list, int * ); void (* EnvSet)( AstObject *, int * ); void *(* GetProxy)( AstObject *, int * ); void (* SetProxy)( AstObject *, void *, int * ); int (* GetObjSize)( AstObject *, int * ); int (* TestUseDefs)( AstObject *, int * ); int (* GetUseDefs)( AstObject *, int * ); void (* SetUseDefs)( AstObject *, int, int * ); void (* ClearUseDefs)( AstObject *, int * ); const char *class; /* Pointer to class name string */ void (** delete)( AstObject *, int * ); /* Pointer to array of destructors */ void (** copy)( const AstObject *, AstObject *, int * ); /* Copy constructors */ void (** dump)( AstObject *, struct AstChannel *, int * ); /* Dump functions */ const char **dump_class; /* Dump function class string pointers */ const char **dump_comment; /* Dump function comment string pointers */ int ndelete; /* Number of destructors */ int ncopy; /* Number of copy constructors */ int ndump; /* Number of dump functions */ int nobject; /* Number of active objects in the class */ int nfree; /* No. of entries in "free_list" */ AstObject **free_list; /* List of pointers for freed Objects */ #if defined(THREAD_SAFE) int (* ManageLock)( AstObject *, int, int, AstObject **, int * ); #endif } AstObjectVtab; #endif #if defined(THREAD_SAFE) && defined(astCLASS) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstObjectGlobals { AstObjectVtab Class_Vtab; int Class_Init; int Retain_Esc; int Context_Level; int *Active_Handles; char GetAttrib_Buff[ AST__GETATTRIB_BUFF_LEN + 1 ]; char *AstGetC_Strings[ AST__ASTGETC_MAX_STRINGS ]; int AstGetC_Istr; int AstGetC_Init; int Nvtab; AstObjectVtab **Known_Vtabs; } AstObjectGlobals; #endif /* More include files. */ /* =================== */ /* The interface to the Channel class must be included here (after the type definitions for the Object class) because "channel.h" itself includes this file ("object.h"), although "object.h" refers to the AstChannel structure above. This seems a little strange at first, but is simply analogous to making a forward reference to a structure type when recursively defining a normal C structure (except that here the definitions happen to be in separate include files). */ #include "channel.h" /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Object) /* Validate class membership */ astPROTO_ISA(Object) /* Test class membership */ /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstObject *astInitObject_( void *, size_t, int, AstObjectVtab *, const char *, int * ); /* Vtab Initialiser. */ void astInitObjectVtab_( AstObjectVtab *, const char *, int * ); /* Loader. */ AstObject *astLoadObject_( void *, size_t, AstObjectVtab *, const char *, AstChannel *channel, int * ); #if defined(THREAD_SAFE) void astInitObjectGlobals_( AstObjectGlobals * ); #endif #endif /* Prototypes for other class functions. */ /* ------------------------------------- */ #if !defined(astCLASS) /* Public */ void astBegin_( void ); void astEnd_( int * ); #endif AstObject *astI2P_( int, int * ); AstObject *astMakeId_( AstObject *, int * ); AstObject *astMakePointer_( AstObject *, int * ); AstObject *astMakePointer_NoLockCheck_( AstObject *, int * ); int astP2I_( AstObject *, int * ); int astVersion_( int * ); int astEscapes_( int, int * ); int astTune_( const char *, int, int * ); void astTuneC_( const char *, const char *, char *, int, int * ); /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ AstObject *astAnnul_( AstObject *, int * ); AstObject *astDelete_( AstObject *, int * ); void astSet_( void *, const char *, int *, ... ); #else /* Public */ AstObject *astDeleteId_( AstObject *, int * ); int astThreadId_( AstObject *, int, int * ); void astExportId_( AstObject *, int * ); void astImportId_( AstObject *, int * ); void astSetId_( void *, const char *, ... )__attribute__((format(printf,2,3))); #endif AstObject *astAnnulId_( AstObject *, int * ); AstObject *astCheckLock_( AstObject *, int * ); AstObject *astClone_( AstObject *, int * ); AstObject *astCopy_( const AstObject *, int * ); AstObject *astFromString_( const char *, int * ); char *astToString_( AstObject *, int * ); const char *astGetC_( AstObject *, const char *, int * ); double astGetD_( AstObject *, const char *, int * ); float astGetF_( AstObject *, const char *, int * ); int astEqual_( AstObject *, AstObject *, int * ); int astGetI_( AstObject *, const char *, int * ); int astHasAttribute_( AstObject *, const char *, int * ); int astSame_( AstObject *, AstObject *, int * ); int astTest_( AstObject *, const char *, int * ); long astGetL_( AstObject *, const char *, int * ); void *astGetProxy_( AstObject *, int * ); void astClear_( AstObject *, const char *, int * ); void astExemptId_( AstObject *, int * ); void astLockId_( AstObject *, int, int * ); void astSetC_( AstObject *, const char *, const char *, int * ); void astSetD_( AstObject *, const char *, double, int * ); void astSetF_( AstObject *, const char *, float, int * ); void astSetI_( AstObject *, const char *, int, int * ); void astSetL_( AstObject *, const char *, long, int * ); void astSetProxy_( AstObject *, void *, int * ); void astShow_( AstObject *, int * ); void astUnlockId_( AstObject *, int, int * ); #if defined(astCLASS) /* Protected */ void astCleanAttribs_( AstObject *, int * ); AstObject *astCast_( AstObject *, AstObject *, int * ); AstObject *astCastCopy_( AstObject *, AstObject *, int * ); #if defined(THREAD_SAFE) int astManageLock_( AstObject *, int, int, AstObject **, int * ); #endif int astGetObjSize_( AstObject *, int * ); int astTestUseDefs_( AstObject *, int * ); int astGetUseDefs_( AstObject *, int * ); void astSetUseDefs_( AstObject *, int, int * ); void astClearUseDefs_( AstObject *, int * ); const char *astGetAttrib_( AstObject *, const char *, int * ); const char *astGetClass_( const AstObject *, int * ); const char *astGetID_( AstObject *, int * ); const char *astGetIdent_( AstObject *, int * ); int astClassCompare_( AstObjectVtab *, AstObjectVtab *, int * ); int astGetNobject_( const AstObject *, int * ); int astGetRefCount_( AstObject *, int * ); int astTestAttrib_( AstObject *, const char *, int * ); int astTestID_( AstObject *, int * ); int astTestIdent_( AstObject *, int * ); void astClearAttrib_( AstObject *, const char *, int * ); void astClearID_( AstObject *, int * ); void astClearIdent_( AstObject *, int * ); void astDump_( AstObject *, AstChannel *, int * ); void astSetAttrib_( AstObject *, const char *, int * ); void astSetCopy_( AstObjectVtab *, void (*)( const AstObject *, AstObject *, int * ), int * ); void astSetDelete_( AstObjectVtab *, void (*)( AstObject *, int * ), int * ); void astSetDump_( AstObjectVtab *, void (*)( AstObject *, AstChannel *, int * ), const char *, const char *, int * ); void astSetVtab_( AstObject *, AstObjectVtab *, int * ); void astSetID_( AstObject *, const char *, int * ); void astSetIdent_( AstObject *, const char *, int * ); void astEnvSet_( AstObject *, int * ); void astVSet_( AstObject *, const char *, char **, va_list, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Check class membership. */ #define astCheckObject(this) astINVOKE_CHECK(Object,this,0) #define astVerifyObject(this) astINVOKE_CHECK(Object,this,1) /* Test class membership. */ #define astIsAObject(this) astINVOKE_ISA(Object,this) /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitObject(mem,size,init,vtab,name) \ astINVOKE(O,astInitObject_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitObjectVtab(vtab,name) astINVOKE(V,astInitObjectVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadObject(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadObject_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to other class functions. */ /* ------------------------------------ */ #if !defined(astCLASS) /* Public */ #define astBegin astBegin_() #define astEnd astINVOKE(V,astEnd_(STATUS_PTR)) #else /* Protected */ #define astMakePointer_NoLockCheck(id) ((void *)astMakePointer_NoLockCheck_((AstObject *)(id),STATUS_PTR)) #endif #define astVersion astVersion_(STATUS_PTR) #define astEscapes(int) astEscapes_(int,STATUS_PTR) #define astTune(name,val) astTune_(name,val,STATUS_PTR) #define astTuneC(name,value,buff,bufflen) astTuneC_(name,value,buff,bufflen,STATUS_PTR) #define astI2P(integer) ((void *)astI2P_(integer,STATUS_PTR)) #define astMakeId(pointer) ((void *)astMakeId_((AstObject *)(pointer),STATUS_PTR)) #define astP2I(pointer) astP2I_((AstObject *)(pointer),STATUS_PTR) #define astMakePointer(id) ((void *)astCheckLock_(astMakePointer_((AstObject *)(id),STATUS_PTR),STATUS_PTR)) #define astToString(this) astINVOKE(V,astToString_(astCheckObject(this),STATUS_PTR)) #define astFromString(string) astINVOKE(O,astFromString_(string,STATUS_PTR)) /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckObject (et al.) to validate Object pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. In the case of an external caller, it also performs the required conversion from an Object identifier to a true C pointer. */ /* These functions require special treatment for external use because they handle Object identifiers and their resources explicitly, and must therefore be passed identifier values without conversion to C pointers. */ #if defined(astCLASS) || defined(astFORTRAN77) /* Protected or Fotran interface */ #define astAnnulId(this) astINVOKE(O,astAnnulId_((AstObject *)(this),STATUS_PTR)) #endif #if defined(astCLASS) /* Protected only */ #define astAnnul(this) astINVOKE(O,astAnnul_(astCheckObject(this),STATUS_PTR)) #define astDelete(this) astINVOKE(O,astDelete_(astCheckObject(this),STATUS_PTR)) #define astSet astINVOKE(F,astSet_) #else /* Public only */ #define astAnnul(this) astINVOKE(O,astAnnulId_((AstObject *)(this),STATUS_PTR)) #define astDelete(this) astINVOKE(O,astDeleteId_((AstObject *)(this),STATUS_PTR)) #define astExport(this) astINVOKE(V,astExportId_((AstObject *)(this),STATUS_PTR)) #define astImport(this) astINVOKE(V,astImportId_((AstObject *)(this),STATUS_PTR)) #define astSet astINVOKE(F,astSetId_) #define astThread(this,ptr) astINVOKE(V,astThreadId_((AstObject *)(this),ptr,STATUS_PTR)) #endif /* Both.... */ #define astLock(this,wait) astINVOKE(V,astLockId_((AstObject *)(this),wait,STATUS_PTR)) #define astUnlock(this,report) astINVOKE(V,astUnlockId_((AstObject *)(this),report,STATUS_PTR)) #define astEqual(this,that) astINVOKE(V,(((AstObject*)this==(AstObject*)that)||astEqual_(astCheckObject(this),astCheckObject(that),STATUS_PTR))) #define astExempt(this) astINVOKE(V,astExemptId_((AstObject *)(this),STATUS_PTR)) #define astClear(this,attrib) astINVOKE(V,astClear_(astCheckObject(this),attrib,STATUS_PTR)) #define astClone(this) astINVOKE(O,astClone_(astCheckObject(this),STATUS_PTR)) #define astCopy(this) astINVOKE(O,astCopy_(astCheckObject(this),STATUS_PTR)) #define astGetC(this,attrib) astINVOKE(V,astGetC_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetD(this,attrib) astINVOKE(V,astGetD_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetF(this,attrib) astINVOKE(V,astGetF_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetI(this,attrib) \ astINVOKE(V,astGetI_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetL(this,attrib) \ astINVOKE(V,astGetL_(astCheckObject(this),attrib,STATUS_PTR)) #define astSetC(this,attrib,value) \ astINVOKE(V,astSetC_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetD(this,attrib,value) \ astINVOKE(V,astSetD_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetF(this,attrib,value) \ astINVOKE(V,astSetF_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetI(this,attrib,value) \ astINVOKE(V,astSetI_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetL(this,attrib,value) \ astINVOKE(V,astSetL_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astShow(this) \ astINVOKE(V,astShow_(astCheckObject(this),STATUS_PTR)) #define astTest(this,attrib) \ astINVOKE(V,astTest_(astCheckObject(this),attrib,STATUS_PTR)) #define astSame(this,that) \ astINVOKE(V,astSame_(astCheckObject(this),astCheckObject(that),STATUS_PTR)) #define astHasAttribute(this,attrib) \ astINVOKE(V,astHasAttribute_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetProxy(this) \ astINVOKE(V,astGetProxy_(astCheckObject(this),STATUS_PTR)) #define astSetProxy(this,proxy) \ astINVOKE(V,astSetProxy_(astCheckObject(this),proxy,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #if defined(THREAD_SAFE) #define astManageLock(this,mode,extra,fail) \ astINVOKE(V,astManageLock_(astCheckObject(this),mode, extra,fail,STATUS_PTR)) #else #define astManageLock(this,mode,extra,fail) #endif #define astCleanAttribs(this) astINVOKE(V,astCleanAttribs_(astCheckObject(this),STATUS_PTR)) #define astGetObjSize(this) astINVOKE(V,astGetObjSize_(astCheckObject(this),STATUS_PTR)) #define astCast(this,obj) astINVOKE(O,astCast_(astCheckObject(this),astCheckObject(obj),STATUS_PTR)) #define astCastCopy(this,obj) astCastCopy_((AstObject*)this,(AstObject*)obj,STATUS_PTR) #define astClearUseDefs(this) astINVOKE(V,astClearUseDefs_(astCheckObject(this),STATUS_PTR)) #define astTestUseDefs(this) astINVOKE(V,astTestUseDefs_(astCheckObject(this),STATUS_PTR)) #define astGetUseDefs(this) astINVOKE(V,astGetUseDefs_(astCheckObject(this),STATUS_PTR)) #define astSetUseDefs(this,val) astINVOKE(V,astSetUseDefs_(astCheckObject(this),val,STATUS_PTR)) #define astClearAttrib(this,attrib) \ astINVOKE(V,astClearAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astClearID(this) astINVOKE(V,astClearID_(astCheckObject(this),STATUS_PTR)) #define astClearIdent(this) astINVOKE(V,astClearIdent_(astCheckObject(this),STATUS_PTR)) #define astDump(this,channel) \ astINVOKE(V,astDump_(astCheckObject(this),astCheckChannel(channel),STATUS_PTR)) #define astGetAttrib(this,attrib) \ astINVOKE(V,astGetAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetClass(this) astINVOKE(V,astGetClass_((const AstObject *)(this),STATUS_PTR)) #define astGetID(this) astINVOKE(V,astGetID_(astCheckObject(this),STATUS_PTR)) #define astGetIdent(this) astINVOKE(V,astGetIdent_(astCheckObject(this),STATUS_PTR)) #define astGetNobject(this) astINVOKE(V,astGetNobject_(astCheckObject(this),STATUS_PTR)) #define astClassCompare(class1,class2) astClassCompare_(class1,class2,STATUS_PTR) #define astGetRefCount(this) astINVOKE(V,astGetRefCount_(astCheckObject(this),STATUS_PTR)) #define astSetAttrib(this,setting) \ astINVOKE(V,astSetAttrib_(astCheckObject(this),setting,STATUS_PTR)) #define astSetCopy(vtab,copy) \ astINVOKE(V,astSetCopy_((AstObjectVtab *)(vtab),copy,STATUS_PTR)) #define astSetDelete(vtab,delete) \ astINVOKE(V,astSetDelete_((AstObjectVtab *)(vtab),delete,STATUS_PTR)) #define astSetDump(vtab,dump,class,comment) \ astINVOKE(V,astSetDump_((AstObjectVtab *)(vtab),dump,class,comment,STATUS_PTR)) #define astSetVtab(object,vtab) \ astINVOKE(V,astSetVtab_((AstObject *)object,(AstObjectVtab *)(vtab),STATUS_PTR)) #define astSetID(this,id) astINVOKE(V,astSetID_(astCheckObject(this),id,STATUS_PTR)) #define astSetIdent(this,id) astINVOKE(V,astSetIdent_(astCheckObject(this),id,STATUS_PTR)) #define astVSet(this,settings,text,args) \ astINVOKE(V,astVSet_(astCheckObject(this),settings,text,args,STATUS_PTR)) #define astEnvSet(this) \ astINVOKE(V,astEnvSet_(astCheckObject(this),STATUS_PTR)) #define astTestAttrib(this,attrib) \ astINVOKE(V,astTestAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astTestID(this) astINVOKE(V,astTestID_(astCheckObject(this),STATUS_PTR)) #define astTestIdent(this) astINVOKE(V,astTestIdent_(astCheckObject(this),STATUS_PTR)) /* Deprecated synonym. */ #define astClass(this) astGetClass(this) #endif /* Extra stuff for debuging probnlems with object handles and memory usage */ #ifdef MEM_DEBUG void astWatchHandle_( int ); void astHandleUse_( int, const char *, ... ); void astHandleAlarm_( const char *, va_list ); #define astWatchHandle astWatchHandle_ #define astHandleUse astHandleUse_ #define astHandleAlarm astHandleAlarm_ #else #define astWatchHandle #define astHandleUse #define astHandleAlarm #endif #endif ast-8.3.0/fpolymap.c0000664000175000017500000001060713004147321011226 00000000000000/* *+ * Name: * fpolymap.c * Purpose: * Define a FORTRAN 77 interface to the AST PolyMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the PolyMap class. * Routines Defined: * AST_ISAPOLYMAP * AST_POLYMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 27-SEP-2003 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "polymap.h" /* C interface to the PolyMap class */ F77_LOGICAL_FUNCTION(ast_isapolymap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPOLYMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPolyMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_polymap)( INTEGER(NIN), INTEGER(NOUT), INTEGER(NCOEFF_F), DOUBLE_ARRAY(COEFF_F), INTEGER(NCOEFF_I), DOUBLE_ARRAY(COEFF_I), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NIN) GENPTR_INTEGER(NOUT) GENPTR_INTEGER(NCOEFF_F) GENPTR_DOUBLE_ARRAY(COEFF_F) GENPTR_INTEGER(NCOEFF_I) GENPTR_DOUBLE_ARRAY(COEFF_I) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_POLYMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPolyMap( *NIN, *NOUT, *NCOEFF_F, COEFF_F, *NCOEFF_I, COEFF_I, "%s", options ) ); astFree( options ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_polytran)( INTEGER(THIS), LOGICAL(FORWARD), DOUBLE(ACC), DOUBLE(MAXACC), INTEGER(MAXORDER), DOUBLE_ARRAY(LBND), DOUBLE_ARRAY(UBND), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_LOGICAL(FORWARD) GENPTR_DOUBLE(ACC) GENPTR_DOUBLE(MAXACC) GENPTR_INTEGER(MAXORDER) GENPTR_DOUBLE_ARRAY(LBND) GENPTR_DOUBLE_ARRAY(UBND) F77_INTEGER_TYPE(RESULT); astAt( "AST_POLYTRAN", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astPolyTran( astI2P( *THIS ), F77_ISTRUE( *FORWARD ), *ACC, *MAXACC, *MAXORDER, LBND, UBND ) ); ) return RESULT; } ast-8.3.0/fratemap.c0000664000175000017500000000635313004147321011201 00000000000000/* *+ * Name: * fratemap.c * Purpose: * Define a FORTRAN 77 interface to the AST RateMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the RateMap class. * Routines Defined: * AST_ISARATEMAP * AST_RATEMAP * 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 * . * Authors: * DSB: David S.Berry (Starlink) * History: * 10-FEB-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "ratemap.h" /* C interface to the RateMap class */ F77_LOGICAL_FUNCTION(ast_isaratemap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astWatchSTATUS( astAt( "AST_ISARATEMAP", NULL, 0 ); RESULT = astIsARateMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_ratemap)( INTEGER(MAP), INTEGER(AX1), INTEGER(AX2), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(MAP) GENPTR_INTEGER(AX1) GENPTR_INTEGER(AX2) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_RATEMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astRateMap( astI2P( *MAP ), *AX1, *AX2, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/ast.news0000664000175000017500000013406213004147320010721 00000000000000AST Library ----------- A new release (V8.3.0) of the Starlink AST (astrometry) library is now available. AST provides a comprehensive range of facilities for attaching world coordinate systems (such as RA/Dec, frequency, etc) to astronomical data, for retrieving and interpreting that information and for generating graphical output based on it. The library should be of interest to anyone writing astronomical software which needs to manipulate coordinate system data, especially celestial coordinate systems. AST is portable and environment-independent. Main Changes in this Version ---------------------------- - A new method called astAxNorm has been added to the Frame class that normalises an array of axis values. When used with SkyFrames, it allows longitude values to be normalised into the shortest range. - A bug has been fixed in the Fortran include file AST_PAR that caused constants related to PI to be defined as single rather than double precision. - A bug has been fixed in the astGetRegionBounds method that could cause the wrong bounds to be returned for regions spanning a longitude = zero singularity. Main Changes in V8.2.0 ---------------------- - A new class of Mapping called UnitNormMap has been added that converts a vector to a unit vector relative to a specified centre, plus length. A UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates represent a unit vector parallel to the supplied input vector, and the (N+1)'th output coordinate is the length of the input vector. - The restriction that Mappings are immutable has been extended to all Mapping classes. This means that attributes representing parameters of a Mapping's forward or inverse transformation cannot be changed after the Mapping has been created. In order to minimise the risk to existing software, this rule does not apply to Mappings that have not yet been included in other objects such as CmpMaps or FrameSets, or which have not yet been cloned. In other words, an error is reported if an attempt is made to change the nature of a Mapping's transformation, but only if the reference count of the Mapping is greater than one. The Mapping classes affected include: GrismMap, LutMap, PcdMap, SphMap, WcsMap and ZoomMap. Main Changes in V8.1.0 ---------------------- - The configure script has a new option "--without-fortran" that allows AST to be built in situations where no Fortran compiler is available. The resulting library has no Fortran interface and so cannot be used within Fortran applications. Also, the link scripts do not attempt to include the fortran runtime libraries. Main Changes in V8.0.7 ---------------------- - A bug in FitsChan has been fixed which could cause a small shift in spectral axis value when writing out a spectral cube to FITS-WCS headers, This shift occurred only if the celestial axes in the cube were not FK5 (RA,Dec). - Avoid some more compiler warnings. - A "BadKeyValue" warning is now issued by the FitsChan class if an illegal FITS keyword value is encountered. See attribute "Warnings" and function "astWarnings". Main Changes in V8.0.6 ---------------------- - Fix bug in FitsChan that caused SIP headers to be treated as linear when creating a FrameSet from the headers. - Fix bug in LutMap that incorrectly allowed an inverse lutmap to be used even if the original LutMap was not monotonic. - Allow attributes to be set for each plane of a Plot3D. - Avoid some compiler warnings. Main Changes in V8.0.5 ---------------------- - The SkyFrame class has a new attribute called SkyTol, which specifies the smallest significant distance within the SkyFrame. It is used to decide if the Mapping between two SkyFrames can be considered a unit transformation. The default value is 0.001 arc-seconds. - A bug has been fixed in the FitsChan class that prevented illegal characters within FITS keyword names (i.e. characters not allowed by the FITS standard) being detected. This bug could under some circumstances cause a subsequent segmentation violation to occur. - A "BadKeyName" warning is now issued by the FitsChan class if a FITS keyword name is encountered that contains any illegal characters. See attribute "Warnings" and function "astWarnings". Main Changes in V8.0.4 ---------------------- - The behaviour of the astAddFrame method has been changed slightly. Previously, astAddFrame modified the FrameSet by storing references to the supplied Mapping and Frame objects within the FrameSet. This meant that any subsequent changes to the current Frame of the modified FrameSet also affected the supplied Frame object. Now, astAddFrame stores deep copies of the Mapping and Frame objects (rather than references) within the modified FrameSet. This means that subsequent changes to the modified FrameSet will now have no effect on the supplied Frame. - The choice of default tick-mark for time axes has been improved, to avoid previous issues which could result in no suitable gap being found, or inappropriate tick marks when using formatted dates. - A new method called astRegionOutline has been added to the Plot class. It draws the outline of a supplied AST Region. - A bug has been fixed that could cause astSimplfy to enter an infinite loop. - Some improvements have been made to the Mapping simplification process that allow more Mappings to be simplified. - The Frame class has a new read-only attribute called "InternalUnit", which gives the units used for the unformatted (i.e. floating-point) axis values used internally by application code. For most Frames, the InternalUnit value is just the same as the Unit value (i.e. formatted and unformatted axis values use the same units). However, the SkyFrame class always returns "rad" for InternalUnit, regardless of the value of Unit, indicating that floating-point SkyFrame axis values are always in units of radians. - The LutMap class has a new attribute called LutEpsilon, which specifies the relative error of the values in the table. It is used to decide if the LutMap can be simplified to a straight line. Main Changes in V8.0.3 ---------------------- - Methods astRebin, astRebinSeq, astResample and astTranGrid now report an error if an array is specified that has more pixels than can be counted by a 32 bit integer. - The hypertext documentation is now generated using Tex4HT rather than latex2html. The format of the hypertext docs has changed significantly. - Another bug fix associated with reading CAR projections from FITS-WCS headers. - Constructor options strings of the form "..., "%s", text );" can now be supplied. This avoids a security issue associated with the alternative form "..., text );". Main Changes in V8.0.2 ---------------------- - For security reasons, the change introduced to astAppendString in V8.0.1 has been moved to a new function called astAppendStringf, and astAppendString itself has been reverted to its V8.0.0 version. Main Changes in V8.0.1 ---------------------- - The macro used to invoke the astAppendString utility function has changed to allow printf-style converstions to be included in the supplied text. Any code that uses this macro must be re-compiled. - The astRebin and astRebinSeq family of functions now include support for arrays with char (byte) and unsigned char (unsigned byte) data types. - The Base and Current attributes of a FrameSet may now be set using the Domain name or the index of the required Frame. - The FITS XPH projection is now supported. - The order of WCS axes within new FITS-WCS headers created by astWrite can now be controlled using a new attribute called FitsAxisOrder. Main Changes in V8.0.0 ---------------------- - AST is now distributed under the Lesser GPL licence. - Least squares fitting of N-dimensional polynomials is now done using files copied from the C/C++ Minpack package (see http://devernay.free.fr/hacks/cminpack/index.html). - Use of the IAU SOFA library has been replaced by ERFA library, which is a re-badged copy of SOFA distributed under a less restrictive license. A copy of ERFA is included within AST. Main Changes in V7.3.4 ---------------------- - By default, the simplification of Polygons no longer checks that the edges are not bent by the simplification. A new attribute, SimpVertices, can be set to zero in order to re-instate this check. - The Polygon class has a new mathod, astConvex, that returns a Polygon representing the shortest polygon (i.e. convex hull) enclosing a specified set of pixel values within a supplied array. Main Changes in V7.3.3 ---------------------- - The FitsChan class has new attributes CardName and CardComm, which hold the keyword name and comment of the current card. - When reading FITS-WCS headers that include polynomial distortion in the SIP format, any inverse transformation specified in the header is now ignored and a new inverse is created to replace it based on the supplied forward transformation. Previously, an inverse was created only if the header did not include an inverse. The accuracy of the inverse transformation has also been improved, although it may now be slower to evaluate in some circumstances. - A bug has been fixed that could over-write the FitsChan CarLin attribute with a non-zero value if the header contains a spectral axis. - The default options for each newly created FitsChan can now be specified via the environment variable FITSCHAN_OPTIONS. Main Changes in V7.3.2 ---------------------- - Fix support for reading GLS projections from FITS headers. - The KeyMap class has new sorting options "KeyAgeUp" and "KeyAgeDown" that retain the position of an existing entry if its value is changed. See the SortBy attribute. - A bug has been fixed in FitsChan that caused CDELT keywords for sky axes to be treated as radians rather than degrees when reading a FITS header, if the corresponding CTYPE values included no projection code. Main Changes in V7.3.1 ---------------------- - Fix bug that could cause a segmenatation fault when reading a FITS TNX header. Main Changes in V7.3.0 ---------------------- - IMPORTANT! The interface for the astRebinSeq (AST_REBINSEQ) family of functions has been changed in order to allow a greater number of pixels to be pasted into the output array. In C, the "nused" parameter is now a pointer to a "int64_t" variable, instead of a simple "int". In Fortran, the NUSED argument for AST_REBINSEQ is now an INTEGER*8. APPLICATION CODE SHOULD BE CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC BEHAVIOUR. - Added a new facility to the FrameSet class to allow each Frame to be associated with multiple Mappings, any one of which can be used to connect the Frame to the other Frames in the FrameSet. The choice of which Mapping to use is controlled by the new "Variant" attribute of the FrameSet class. - Mappings (but not Frames) that have a value set for their Ident attribute are now left unchanged by the astSimplify (AST_SIMPLIFY) function. Main Changes in V7.2.0 ---------------------- - A new method call astMapDefined has been added to the KeyMap class. It checks if a gtiven key name has a defined value in a given KeyMap. Main Changes in V7.1.1 ---------------------- - A bug has been fixed in FitsChan that caused inappropriate CTYPE values to be generated when writing a FrameSet to FITS-WCS headers if the current Frame describes generalised spherical coordinates (i.e. a SkyFrame with System=Unknown). - When a FitsChan is used to write an "offset" SkyFrame (see attribute SkyRefIs) to a FITS-WCS encoded header, two alternate axis descriptions are now created - one for the offset coordinates and one for the absolute coordinates. If such a header is subsequently read back into AST, the original offset SkyFrame is recreated. Main Changes in V7.1.0 ---------------------- - IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve flux. To conserve flux, the AST__CONSERVEFLUX flag should be supplied when calling astRebinSeq. Without this flag, each output value is a weighted mean of the neighbouring input values. - A new flag AST__NONORM can be used with astRebinSeq to indicate that normalisation of the output arrays is not required. In this case no weights array need be supplied. - A bug has been fixed in astAddFrame (AST_ADDFRAME) method that could result in the incorrect inversion of Mappings within the FrameSet when the AST__ALLFRAMES flag is supplied for the "iframe" parameter. - The astRate method has been re-written to make it faster and more reliable. Main Changes in V7.0.6 ---------------------- - A bug has been fixed in astRebinSeq which could result in incorrect normalisation of the final binned data and variance values. - When reading a FrameSet from a FITS-DSS header, the keywords CNPIX1 and CNPIX2 now default to zero if absent. Previously an error was reported. Main Changes in V7.0.5 ---------------------- - The FitsChan class can now read FITS headers that use the SAO convention for representing distorted TAN projections, based on the use of "COi_j" keywords to hold the coefficients of the distortion polynomial. Main Changes in V7.0.4 ---------------------- - The previously private grf3d.h header file is now installed into prefix/include. Main Changes in V7.0.3 ---------------------- - A bug has been fixed which could cause an incorrect axis to be used when accessing axis attributes within CmpFrames. This could happen if axes within the CmpFrame have been permuted. - A bug has been fixed in the SkyFrame class that could cause the two values of the SkyRef and/or SkyRefP attributes to be reversed. - Bugs have been fixed in the CmpRegion class that should allow the border around a compound Region to be plotted more quickly, and more accurately. Previously, component Regions nested deeply inside a CmpRegion may have been completely or partially ignored. - A bug has been fixed in the Plot3D class that caused a segmentation violation if the MinTick attribute was set to zero. - The astResampleX set of methods now includes astResampleK and astResampleUK that handles 64 bit integer data. Main Changes in V7.0.2 ---------------------- - The libast_pal library is no longer built if the "--with-external_pal" option is used when AST is configured. Main Changes in V7.0.1 ---------------------- - The levmar and wcslib code distributed within AST is now stored in the main AST library (libast.so) rather than in separate libraries. Main Changes in V7.0.0 ---------------------- - Fundamental positional astronomy calculations are now performed using the IAU SOFA library where possible, and the Starlink PAL library otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB library re-written in C). Copies of these libraries are bundled with AST and so do not need to be obtained or built separately, although external copies of SOFA and PAL can be used if necessary by including the "--with-external_pal" option when configuring AST. Main Changes in V6.0-1 ----------------------- - The Spitzer "-SIP" distortion code is now recognised within FITS headers that describe non-celestial axes, as well as celestial axes. - A bug has been fixed that could cause inappropriate equinox values to be used when aligning SkyFrames if the AlignSystem attribute is set. - The format of the version string for AST has changed from ".-" to "..". Main Changes in V6.0 ----------------------- - This version of AST is the first that can be used with the Python AST wrapper module, starlink.Ast, available at http://github.com/timj/starlink-pyast. - When reading a FITS-WCS header, the FitsChan class now recognises the non-standard "TPV" projection code within a CTYPE keyword value. This code is used by SCAMP (see www.astromatic.net/software/scamp) to represent a distorted TAN projection. - The Plot class has been changed to remove visual anomalies (such as incorrectly rotated numerical axis labels) if the graphics coordinates have unequal scales on the X and Y axes. - The graphics escape sequences used to produce graphical sky axis labels can now be changed using the new function astTuneC (AST_TUNEC). Main Changes in V5.7-2 ----------------------- - The PolyMap class can now use an iterative Newton-Raphson method to evaluate the inverse the inverse transformation if no inverse transformation is defined when the PolyMap is created. - The FitsChan class has a new method astWriteFits (AST_WRITEFITS) which writes out all cards currently in the FitsChan to the associated external data sink (specified either by the SinkFile attribute or the sink function supplied when the FitsChan was created), and then empties the FitsChan. - The FitsChan class has a new method astReadFits (AST_READFITS) which forces the FitsChan to reads cards from the associated external source and appends them to the end of the FitsChan. - The FitsChan class has a new read-only attribute called "Nkey", which holds the number of keywords for which values are held in a FitsChan. - The FitsChan class has a new read-only attribute called "CardType", which holds the data type of the keyword value for the current card. - The FitsChan astGetFits (AST_GETFITS) methods can now be used to returned the value of the current card. - If the FitsChan astRead method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, and for which the PolyTran method of the PolyMap class fails to create an accurate estimate of the inverse polynomial correction, then an iterative method will be used to evaluate the inverse correction for each point transformed. - The Object class has a new function astToString (C only), which creates an in-memory textual serialisation of a given AST Object. A corresponding new function called astFromString re-creates the Object from its serialisation. Main Changes in V5.7-1 ----------------------- - All classes of Channel can now read to and write from specified text files, without the need to provide source and sink functions when the Channel is created. The files to use are specified by the new attributes SourceFile and SinkFile. - The FitsChan class now ignores trailing spaces in character-valued WCS keywords when reading a FrameSet from a FITS header. - If the FitsChan astRead method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, the FitsChan class will now use the PolyTran method of the PolyMap class to create an estimate of the inverse polynomial correction. Main Changes in V5.7-0 ----------------------- - The FitsChan class support for the IRAF-specific "TNX" projection has been extended to include reading TNX headers that use a Chebyshev representation for the distortion polynomial. - The FitsChan class support for the IRAF-specific "ZPX" projection has been extended to include reading ZPX headers that use simple or Chebyshev representation for the distortion polynomial. - A bug has been fixed in the FitsChan class that caused headers including the Spitzer "-SIP" distortion code to be read incorrectly if no inverse polynomial was specified in the header. - A new attribute called PolyTan has been added to the FitsChan class. It can be used to indicate that FITS headers that specify a TAN projection should be interpreted according to the "distorted TAN" convention included in an early draft of FITS-WCS paper II. Such headers are created by (for instance) the SCAMP tool (http://www.astromatic.net/software/scamp). - The PolyMap class now provides a method called astPolyTran (AST_POLYTRAN) that adds an inverse transformation to a PolyMap by sampling the forward transformation on a regular grid, and then fitting a polynomial function from the resulting output values to the grid of input values. Main Changes in V5.6-1 ----------------------- - Tables can now have any number of parameters describing the global properties of the Table. - Frames now interpret the unit string "A" as meaning "Ampere" rather than "Angstrom", as specified by FITS-WCS paper I. - A bug has been fixed in the astFindFrame (AST_FINDFRAME) method that allowed a template Frame of a more specialised class to match a target frame of a less specialised class. For example, this bug would allow a template SkyFrame to match a target Frame. This no longer happens. Main Changes in V5.6-0 ----------------------- - New functions astBBuf (AST_BBUF) and astEBuf (AST_EBUF) have been added to the Plot class. These control the buffering of graphical output produced by other Plot methods. - New functions astGBBuf and astGEBuf have been added to the interface defined by file grf.h. The ast_link command has been modified so that the -grf_v3.2 switch loads dummy versions of the new grf functions. This means that applications that use the -grf_v3.2 switch should continue to build without any change. However, the new public functions astBBuf and astEBuf described in the previous item will report an error unless the new grf functions are implemented. If you choose to implement them, you should modify your linking procedure to use the -grf (or -grf_v5.6) switch in place of the older -grf_v3.2 switch. See the description of the ast_link command for details of these switches. - New method astGetRegionMesh (AST_GETREGIONMESH) returns a set of positions covering the boundary, or volume, of a supplied Region. Main Changes in V5.5-0 ----------------------- - The FitsChan "TabOK" attribute is now an integer value rather than a boolean value. As in previous versions, it is used to indicate whether the "-TAB" algorithm should be supported by the astRead (AST_READ) and astWrite (AST_WRITE) methods, but in addition it is now also used to give the version number to assign to any table gebnerated as a consequence of calling astWrite (AST_WRITE). A negative or zero value (the default) indicates that support for the -TAB algorithm is not available, where as a positive non-zero value indicates that support is available and also gives the table version number to use when creating subsequent -TAB headers. Main Changes in V5.4-0 ----------------------- - The FitsChan class now has an option to support reading and writing of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper III. This option is controlled by a new FitsChan attribute called TabOK. See the documentation for TabOK for more information. - A new class called "Table" has been added. A Table is a KeyMap in which each entry represents a cell in a two-dimensional table. - A new class called "FitsTable" has been added. A FitsTable is a Table that has an associated FitsChan holding headers appropriate to a FITS binary table. - KeyMaps can now hold byte (i.e. "unsigned char" or BYTE) values. - A new method called astMapRename (AST_MAPRENAME) has been added to rename an existing entry in a KeyMap. - KeyMaps have a new attribute called KeyCase that can be set to zero to make the handling of keys case insensitive. Main Changes in V5.3-2 ----------------------- - A bug has been fixed in the FitsChan class that could cause wavelength axes to be assigned the units "m/s" when reading WCS information from a FITS header. - The astSet function (AST_SET) now allows literal commas to be included in string attribute values. String attribute values that include a literal comma should be enclosed in quotation marks. - A bug in FitsChan has been fixed that caused "-SIN" projection codes within FITS-WCS headers to be mis-interpreted, resulting in no FrameSet being read by astRead. - The KeyMap class has a new attribute called "SortBy". It controls the order in which keys are returned by the astMapKey (AST_MAPKEY) function. Keys can be sorted alphabetically or by age, or left unsorted. - Access to KeyMaps holding thousands of entries is now significantly faster. - KeyMaps can now hold word (i.e. "short int" or INTEGER*2) values. Main Changes in V5.3-1 ----------------------- - The KeyMap class has a new method called astMapCopy/AST_MAPCOPY that copies entries from one KeyMap to another KeyMap. - The KeyMap class now supports entries that have undefined values. A new method called astMapPutU/AST_MAPPUTU will store an entry with undefined value in a keymap. - The KeyMap class has a new boolean attribute called MapLocked. If true (non-zero), an error is reported if an attempt is made to add any new entries to a KeyMap (the value associated with any old entry may still be changed # without error). The default is false (zero). - The Object class has a new method called astHasAttribute/AST_HASATTRIBUTE that returns a boolean value indicating if a specified Object has a named attribute. - The SkyFrame class has two new read-only boolean attributes called IsLatAxis and IsLonAxis that can be used to determine the nature of a specified SkyFrame axis. - A bug has been fixed in the astRebin(Seq)/AST_REBIN(SEQ) methods that could cause flux to be lost from the edges of the supplied array. - A bug has been fixed in the astRebin(Seq)/AST_REBIN(SEQ) methods that caused the first user supplied parameter to be interpreted as the full width of the spreading kernel, rather than the half-width. - The StcsChan class now ignores case when reading STC-S phrases (except that units strings are still case sensitive). - The Channel class now has an Indent attribute that controls indentation in the text created by astWrite/AST_WRITE. The StcsIndent and XmlIndent attributes have been removed. - All classes of Channel now use the string "" to represent the floating point value AST__BAD, rather than the literal formatted value (typically "-1.79769313486232e+308" ). - The KeyMap class now uses the string "" to represent the floating point value AST__BAD, rather than the literal formatted value (typically "-1.79769313486232e+308" ). - The KeyMap class has a new method called astMapPutElem/AST_MAPPUTELEM that allows a value to be put into a single element of a vector entry in a KeyMap. The vector entry is extended automatically to hold the new element if required. - The DSBSpecFrame class now reports an error if the local oscillator frequency is less than the absoliute value of the intermediate frequency. - A new method astQuadApprox produces a quadratic fit to a 2D Mapping. - A new method astSkyOffsetMap produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame coordinates. Main Changes in Version 5.3 --------------------------- - The details of how a Frame is aligned with another Frame by the astFindFrame and astConvert (AST_FINDFRAME and AST_CONVERT) functions have been changed. The changes mean that a Frame can now be aligned with an instance of a sub-class of Frame, so long as the number of axes and the Domain values are consistent. For instance, a basic 2-dimensional Frame with Domain "SKY" will now align succesfully with a SkyFrame, conversion between the two Frames being achieved using a UnitMap. - The arrays that supply input values to astMapPut1 are now declared "const". - Added method astMatchAxes (AST_MATCHAXES) to the Frame class. This allows corresponding axes in two Frames to be identified. - The astAddFrame (AST_ADDFRAME) method can now be used to append one or more axes to all Frames in a FrameSet. Main Changes in Version 5.1 --------------------------- - A new method called astSetFitsCM (AST_SETFITSCM) has been added to the FitsChan class. It stores a pure comment card in a FitsChan (that is, a card with no keyword name or equals sign). - A new attribute called ObsAlt has been added to the Frame class. It records the geodetic altitude of the observer, in metres. It defaults to zero. It is used when converting times to or from the TDB timescale, or converting spectral positions to or from the topocentric rest frame, or converting sky positions to or from horizon coordinates. The FitsChan class will include its effect when creating a set of values for the OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a set of OBSGEO-X/Y/Z keyword values from a FITS header. - The TimeMap conversions "TTTOTDB" and "TDBTOTT", and the SpecMap conversions "TPF2HL" and "HLF2TP", now have an additional argument - the observer's geodetic altitude. - The Polygon class has been modified to make it consistent with the IVOA STC definition of a Polygon. Specifically, the inside of a polygon is now the area to the left of each edge as the vertices are traversed in an anti-clockwise manner, as seen from the inside of the celestial sphere. Previously, AST used the anti-clockwise convention, but viewed from the outside of the celestial sphere instead of the inside. Any Polygon saved using previous versions of AST will be identified and negated automatically when read by AST V5.2. - A new class of Channel, called StcsChan, has been added that allows conversion of suitable AST Objects to and from IVOA STC-S format. - A new method called astDownsize (AST_DOWNSIZE) has been added to the Polygon class. It produces a new Polygon that contains a subset of the vertices in the supplied Polygon. The subset is chosen to retain the main features of the supplied Polygion, in so far as that is possible, within specified constraints. - A new constructor called astOutline (AST_OUTLINE) has been added to the Polygon class. Given a 2D data array, it identifies the boundary of a region within the array that holds pixels with specified values. It then creates a new Polygon to describe this boundary to a specified accuracy. - A new method called astRemoveRegions (AST_REMOVEREGIONS) has been added to the Mapping class. It removes the masking effects of any Regions found within a (possibly compound) Mapping or Frame. In effect, it replaces each Region found within the Mapping or Frame with a UnitMap or equivalent Frame. - A new set of methods, called astMapGetElem (AST_MAPGETELEM) has been added to the KeyMap class. They allow a single element of a vector valued entry to be returned. - A new attribute called KeyError has been added to the KeyMap Class. It controls whether the astMapGet... (AST_MAPGET...) family of functions report an error if an entry with the requested key does not exist in the KeyMap. Main Changes in Version 5.1 --------------------------- - The astUnlock function now has an extra parameter that controls whether or not an error is reported if the Object is currently locked by another thread. - The values of the AST__THREADSAFE macro (defined in ast.h) have been changed from "yes" and "no" to "1" and "0". - The PointList class has a new method, astPoints, that copies the axis values from the PointList into a supplied array. - The PointList class has a new (read-only) attribute, ListSize, that gives the number of points stored in the PointList. - A new method (astIntersect) has been added to the Frame class. It determines the position at which two geodesic curves intersect. - The XmlStrict attribute and astXmlWarnings function have been removed. The same functionality is now available via the existing Strict attribute, a new attribute called ReportLevel, and a new function called astWarnings. - A bug in the type-checking of Objects passed as arguments to constructor functions has been fixed. This bug could lead to applications crashing or showing strange behaviour if an inappropriate class of Object was supplied as an argument to a constructor. - The astPickAxes function will now return a Region, if possible, when applied to a Region. If this is not possible, a Frame will be returned as before. - The default gap size between the ISO date/time labels used by the Plot class when displaying an annotated axis described by a TimeFrame has been changed. The changes are meant to improve the labelling of calendar time axes that span intervals from a day to a few years. Main Changes in Version 5.0 --------------------------- - AST is now thread-safe. Many of the macro definitions in the "ast.h" header file have changed, and so all source code that include "ast.h" should be re-compiled. - The TimeFrame class now support Local Time as a time scale. The offset from UTC to Local Time is specified by a new TimeFrame attribute called LTOffset. - Addition of a new class called Plot3D that provides facilities for producing 3-dimensional annotated coordinate grids. - A correction for diurnal aberration is now included when converting between AZEL and other celestial coordinate systems. The correction is based on the value of the ObsLat Frame attribute (the geodetic latitude of the observer). - A bug has been fixed which caused the DUT1 attribute to be ignored by the SkyFrame class when finding conversions between AZEL and other celestial coordinate systems. - The Channel class has a new attribute called Strict which controls whether or not to report an error if unexpected data items are found within an AST Object description read from an external data source. Note, the default behaviour is now not to report such errors. This differs from previous versions of AST which always reported an error is unexpected input items were encountered. Main Changes in Version 4.5 --------------------------- - All FITS-CLASS headers are now created with a frequency axis. If the FrameSet supplied to astWrite contains a velocity axis (or any other form of spectral axis) it will be converted to an equivalent frequency axis before being used to create the FITS-CLASS header. - The value stored in the FITS-CLASS keyword "VELO-LSR" has been changed from the velocity of the source to the velocity of the reference channel. - Addition of a new method call astPurgeWCS (AST_PURGEWCS) to the FitsChan class. This method removes all WCS-related header cards from a FitsChan. - The astRebinSeq functions now have an extra parameter that is used to record the total number of input data val;ues added into the output array. This is necessary to correct a flaw in the calculation of output variances based on the spread of input values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE THAT USES ASTREBINSEQ TO BE MODIFIED TO INCLUDE THE NEW PARAMETER (CALLED "NUSED"). - The Plot class now honours the value of the LabelUp attribute even if numerical labels are placed around the edge of the Plot. Previously LabelUp was only used if the labels were drawn within the interior of the plot. The LabelUp attribute controls whether numerical labels are drawn horizontally or parallel to the axis they describe. - The Plot class has a new attribute called GrfContext that can be used to comminicate context information between an application and any graphics functions registered with the Plot class via the astGrfSet (AST_GRFSET) function. - Functions registered with the Plot class using astGrfSet (AST_GRFSET) now take a new additional integer parameter, "grfcon". The Plot class sets this parameter to value of the Plot's GrfContext attribute before calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE THAT USES astGrfSet (AST_GRFSET) TO BE MODIFIED TO INCLUDE THE NEW PARAMETER. - Support has been added for the FITS-WCS "HPX" projection (HEALPix). - A new flag "AST__VARWGT" can be supplied to astRebinSeq. This causes the input data values to be weighted using the reciprocals of the input variances (if supplied). - The Frame class has a new read-only attribute called NormUnit that returns the normalised value of the Unit attribute for an axis. Here, "normalisation" means cancelling redundant units, etc. So for instance, a Unit value of "s*(m/s)" would result in a NormUnit value of "m". - A new method astShowMesh has been added to the Region class. It displays a mesh of points covering the surface of a Region by writing out a table of axis values to standard output. - A bug has been fixed that could segmentation violations when setting attribute values. Main Changes in Version 4.4 --------------------------- - The astFindFrame (AST_FINDFRAME) method can now be used to search a CmpFrame for an instance of a more specialised class of Frame (SkyFrame, TimeFrame, SpecFrame, DSBSpecFrame or FluxFrame). That is, if an instance of one of these classes is used as the "template" when calling astFindFrame, and the "target" being searched is a CmpFrame (or a FrameSet in which the current Frame is a CmpFrame), then the component Frames within the CmpFrame will be searched for an instance of the supplied template Frame, and, if found, a suitable Mapping (which will include a PermMap to select the required axes from the CmpFrame) will be returned by astFindFrame. Note, for this to work, the MaxAxes and MinAxes attributes of the template Frame must be set so that they cover a range that includes the number of axes in the target CmpFrame. - The DSBSpecFrame class has a new attribute called AlignSB that specifies whether or not to take account of the SideBand attributes when aligning two DSBSpecFrames using astConvert (AST_CONVERT). - The Frame class has a new attribute called Dut1 that can be used to store a value for the difference between the UT1 and UTC timescales at the epoch referred to by the Frame. - The number of digits used to format the Frame attributes ObsLat and ObsLon has been increased. - The use of the SkyFrame attribute AlignOffset has been changed. This attribute is used to control how two SkyFrames are aligned by astConvert. If the template and target SkyFrames both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a UnitMap will always be used to align the two SkyFrames). - The Plot class has a new attribute called ForceExterior that can be used to force exterior (rather than interior) tick marks to be produced, even if this would result in less than 3 tick marks being produced. - The TimeFrame class now supports conversion between angle based timescales such as UT1 and atomic based timescales such as UTC. Main Changes in Version 4.3 --------------------------- - The SpecFrame class has a new attribute called SourceSys that specified whether the SourceVel attribute (which specifies the rest frame of the source) should be accessed as an apparent radial velocity or a redshift. Note, any existing software that assumes that SourceVel always represents a velocity in km/s should be changed to allow for the possibility of SourceVel representing a redshift value. - The astGetFitsS (AST_GETFITSS) function now strips trailing white space from the returned string, if the original string contains 8 or fewer characters. Main Changes in Version 4.2 --------------------------- - The SideBand attribute of the DSBSpecFrame class can now take the option "LO" in addition to "USB" and "LSB". The new option causes the DSBSpecFrame to represent the offset from the local oscillator frequency, rather than either of the two sidebands. - The FitsChan class has been changed so that it writes out a VELOSYS keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric apparent velocity of the standard of rest). FitsChan also strips out VELOSYS keywords when reading a FrameSet from a FITS-WCS encoding. - The FitsChan class has a new method called astRetainFits (AST_RETAINFITS) that indicates that the current card in the FitsChan should not be stripped out of the FitsChan when an AST Object is read from the FitsChan. Unless this method is used, all cards that were involved in the creation of the AST Object will be stripped from the FitsChan afte a read operation. - The ast_link_adam and ast_link scripts now ignore the -fsla and -csla options, and always link against the minimal cut-down version of SLALIB distributed as part of AST. - A problem with unaligned memory access that could cause bus errors on Solaris has been fixed. - A new function called astTune (or AST_TUNE) has been added which can be used to get and set global AST tuning parameters. At the moment there are only two such parameter, both of which are concerned with memory management within AST. - A new method called astTranGrid (AST_TRANGRID in Fortran) has been added to the Mapping class. This method creates a regular grid of points covering a rectangular region within the input space of a Mapping, and then transforms this set of points into the output space of the Mapping, using a piecewise-continuous linear approximation to the Mapping if appropriate in order to achive higher speed. - A new subclass of Mapping has been added called SwitchMap. A SwitchMap represents several alternate Mappings, each of which is used to transforms input positions within a different region of the input coordinate space. - A new subclass of Mapping has been added called SelectorMap. A SelectorMap tests each input position to see if it falls within one of several Regions. If it does, the index of the Region containing the input position is returned as the Mapping output. - The behaviour of the astConvert (AST_CONVERT) method when trying to align a CmpFrame with another Frame has been modified. If no conversion between positions in the Frame and CmpFrame can be found, an attempt is now made to find a conversion between the Frame and one of two component Frames contained within the CmpFrame. Thus is should now be possible to align a SkyFrame with a CmpFrame containing a SkyFrame and a SpecFrame (for instance). The returned Mapping produces bad values for the extra axes (i.e. for the SpecFrame axis in the above example). Main Changes in Version 4.1 --------------------------- - A new control flag has been added to the AST_RESAMPLE/astResample functions which produces approximate flux conservation. - The SkyFrame class now supports a System value of "AZEL" corresponding to horizon (azimuth/elevation) coordinates. - The FitsChan class allows the non-standard strings "AZ--" and "EL--" to be used as axis types in FITS-WCS CTYPE keyword values. - The Frame class now has attributes ObsLon and ObsLat to specify the geodetic longitude and latitude of the observer. - The ClockLon and ClockLat attributes have been removed from the TimeFrame class. Likewise, the GeoLon and GeoLat attributes have been removed from the SpecFrame class. Both classes now use the ObsLon and ObsLat attributes of the parent Frame class instead. However, the old attribute names can be used as synonyms for ObsLat and ObsLon. Also, dumps created using the old scheme can be read succesfully by AST V4.1 and converted to the new form. - A new function astMapSplit has been added to the Mapping class. This splits a Mapping into two component Mappings which, when combined in parallel, are equivalent to the original Mapping. - The default value for the SkyRefIs attribute has been changed from "Origin" to "Ignored". This means that if you want to use a SkyFrame to represent offsets from some origin position, you must now set the SkyRefIs attribute explicitly to either "Pole" or "Origin", in addition to assigning the required origin position to the SkyRef attribute. Main Changes in Version 4.0 --------------------------- - Experimental support for reading IVOA Space-Time-Coordinates (STC) descriptions using the XmlChan class has been added. Support is included for a subset of V1.20 of the draft STC specification. - A new set of methods (AST_REBIN/astRebin) has been added to the Mapping class. These are accurately flux-conserving alternatives to the existing AST_RESAMPLE/astResample methods. Main Changes in Version 3.7 --------------------------- - Support for time coordinate systems has been introduced throught the addition of two new classes, TimeFrame and TimeMap. The TimeFrame is a 1-dimensional Frame which can be used to describe moments in time (either absolute or relative) in various systems (MJD, Julian Epoch, etc.) and referred to various time scales (TAI, UTC, UT1, GMST, etc). The TimeMap is a Mapping which can transform time values between these various systems and time scales. Main Changes in Version 3.6 --------------------------- - If the Format attribute associated with an axis of a SkyFrame starts with a percent character (%), then axis values are now formatted and unformatted as a decimal radians value, using the Format syntax of a simple Frame. - The Plot class has a new attribute called Clip which controls the clipping performed by AST at the plot boundary. - The PolyMap class has been modified to allow a PolyMap to be written succesfully to a FitsChan using Native encoding. - A mimimal cut down subset of the C version of SLALIB is now included with the AST distribution and built as part of building AST. This means that it is no longer necessary to have SLALIB installed separately at your site. The SLALIB code included with AST is distrubuted under the GPL. The default behaviour of the ast_link script is now to link with this internal slalib subset. However, the ``-csla'' option can still be used to force linking with an external full C SLALIB library. A new option ``-fsla'' has been introduced which forces linking with the external full Fortran SLALIB library. Main Changes in Version 3.5 --------------------------- - AST now provides facilities for representing regions of various shapes within a coordinate system. The Region class provides general facilities which are independent of the specific shape of region being used. Various sub-classes of Region are also now available which provide means of creating Regions of specific shape. Facilities provided by the Region class include testing points to see if they are inside the Region, testing two Regions for overlap, transforming Regions from one coordinate system to another, etc. - A new class of 1-dimensional Frame called FluxFrame has been added which can be used to describe various systems for describing ovserved value at a single fixed spectral position. - A new class of 2-dimensional Frame called SpecFluxFrame has been added which can be used to describe a 2-d frame spanned by a spectral position axis and and an observed value axis. - A new class of Mapping called RateMap has been added. A RateMap encapsulates a previously created Mapping. The inputs of the RateMap correspond to the inputs of the encapsulated Mapping. All RateMaps have just a single output which correspond to the rate of change of a specified output of the encapsulated Mapping with respect to a specified input. - The SkyFrame class now supports a value of "J2000" for System. This system is an equatorial system based on the mean dynamical equator and equinox at J2000, and differs slightly from an FK5(J2000) system. - Methods have been added to the FitsChan class to allow values for named keywords to be changed or added. - The parameter list for the astRate method of the Mapping class has been modified. It no longer returns a second derivative estimate. Existing code which uses the astRate (AST_RATE) method will need to be changed. ast-8.3.0/grf_3.2.c0000664000175000017500000000445213004147321010540 00000000000000/* * Name: * grf_3.2.c * Purpose: * Implement the grf module required by AST V3.2 if no graphics system * is available. * Description: * This file implements the low level graphics functions required * by the rest of AST V3.2, except for those already defined in * grf_2.0.c (i.e. those needed by AST V2.0). These implementations * simply report an error when called. * Inheritance: * This module is not a class and does not inherit. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-NOV-2004 (DSB): * Original version. */ /* Header files */ /* ============ */ #include "grf.h" /* Declare the functions in this module */ #include "error.h" /* AST error reporting facilities */ #include "ast_err.h" /* AST error codes */ /* Function Prototypes */ /* =================== */ static void Report( const char * ); /* Function definitions */ /* ==================== */ int astGScales( float *alpha, float *beta ){ Report( "astGScales" ); return 0; } int astGCap( int cap, int value ){ return 0; } static void Report( const char *name ){ astError( AST__GRFER, "%s: The graphics facilities implement by %s " "(introduced at AST V3.2) are needed but are unavailable.", name, name ); astError( AST__GRFER, "Re-link using a suitable option such as '-pgplot' " "with the ast_link script, or add an implementation of this " "function to your 'grf' module." ); } ast-8.3.0/matrixmap.h0000664000175000017500000002364013004147321011407 00000000000000#if !defined( MATRIXMAP_INCLUDED ) /* Include this file only once */ #define MATRIXMAP_INCLUDED /* *+ * Name: * matrixmap.h * Type: * C include file. * Purpose: * Define the interface to the MatrixMap class. * Invocation: * #include "matrixmap.h" * Description: * This include file defines the interface to the MatrixMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The MatrixMap class implements Mappings that transform a set of * coordinates by multiplying them by a matrix. The inverse transformation * can only be applied if the associated matrix is square and non-singular. * Inheritance: * The MatrixMap class inherits from the Mapping class. * Attributes Over-Ridden: * TranForward (integer) * A read-only boolean value (0 or 1) which indicates whether a * MatrixMap is able to transform coordinates in the "forward" * direction (i.e. converting input coordinates into output * coordinates). * TranInverse (integer) * A read-only boolean value (0 or 1) which indicates whether a * MatrixMap is able to transform coordinates in the "inverse" * direction (i.e. converting output coordinates back into input * coordinates). * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astTransform * Apply a MatrixMap to transform a set of points. * astGetTranForward * Determine if a MatrixMap can perform a "forward" coordinate * transformation. * astGetTranInverse * Determine if a MatrixMap can perform an "inverse" coordinate * transformation. * New Methods Defined: * Public: * None. * * Protected: * astMtrMult * Multiply a MatrixMap by another MatrixMap. * astMtrRot * Rotate a MatrixMap. * Other Class Functions: * Public: * astIsAMatrixMap * Test class membership. * astMatrixMap * Create a MatrixMap. * * Protected: * astCheckMatrixMap * Validate class membership. * astInitMatrixMap * Initialise a MatrixMap. * astInitMatrixMapVtab * Initialise the virtual function table for the MatrixMap class. * astLoadMatrixMap * Load a MatrixMap. * Macros: * None. * Type Definitions: * Public: * AstMatrixMap * MatrixMap object type. * * Protected: * AstMatrixMapVtab * MatrixMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 12-Feb-1996 (DSB): * Original version. * 22-Feb-1996 (DSB): * Method "astMatrixRotate" added. * 5-Mar-1996 (DSB): * Method "astMatrixMult" added. * 14-NOV-1996 (DSB): * External interface and I/O added. Public method names shortened. * 3-JUN-1997 (DSB): * astMtrMult and astMtrRot made protected instead of public. * 8-JAN-2003 (DSB): * Added protected astInitMatrixMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* MatrixMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstMatrixMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *f_matrix; /* Pointer to forward matrix */ double *i_matrix; /* Pointer to inverse matrix */ int form; /* Matrix storage form */ } AstMatrixMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstMatrixMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstMatrixMap *(* MtrRot)( AstMatrixMap *, double, const double[], int * ); AstMatrixMap *(* MtrMult)( AstMatrixMap *, AstMatrixMap *, int * ); } AstMatrixMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstMatrixMapGlobals { AstMatrixMapVtab Class_Vtab; int Class_Init; } AstMatrixMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitMatrixMapGlobals_( AstMatrixMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(MatrixMap) /* Check class membership */ astPROTO_ISA(MatrixMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstMatrixMap *astMatrixMap_( int, int, int, const double[], const char *, int *, ...); #else AstMatrixMap *astMatrixMapId_( int, int, int, const double[], const char *, ... )__attribute__((format(printf,5,6))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstMatrixMap *astInitMatrixMap_( void *, size_t, int, AstMatrixMapVtab *, const char *, int, int, int, const double[], int * ); /* Vtab initialiser. */ void astInitMatrixMapVtab_( AstMatrixMapVtab *, const char *, int * ); /* Loader. */ AstMatrixMap *astLoadMatrixMap_( void *, size_t, AstMatrixMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ AstMatrixMap *astMtrRot_( AstMatrixMap *, double, const double[], int * ); AstMatrixMap *astMtrMult_( AstMatrixMap *, AstMatrixMap *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckMatrixMap(this) astINVOKE_CHECK(MatrixMap,this,0) #define astVerifyMatrixMap(this) astINVOKE_CHECK(MatrixMap,this,1) /* Test class membership. */ #define astIsAMatrixMap(this) astINVOKE_ISA(MatrixMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astMatrixMap astINVOKE(F,astMatrixMap_) #else #define astMatrixMap astINVOKE(F,astMatrixMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitMatrixMap(mem,size,init,vtab,name,nin,nout,form,matrix) \ astINVOKE(O,astInitMatrixMap_(mem,size,init,vtab,name,nin,nout,form,matrix,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitMatrixMapVtab(vtab,name) astINVOKE(V,astInitMatrixMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadMatrixMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadMatrixMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckMatrixMap to validate MatrixMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astMtrRot(this,theta,axis) \ astINVOKE(O,astMtrRot_(astCheckMatrixMap(this),theta,axis,STATUS_PTR)) #define astMtrMult(this,a) \ astINVOKE(O,astMtrMult_(astCheckMatrixMap(this),astCheckMatrixMap(a),STATUS_PTR)) #endif #endif ast-8.3.0/unit.c0000664000175000017500000061132413004147321010361 00000000000000/* * Name: * unit.c * Purpose: * Implement unit conversion functions. * Description: * This file implements the Unit module which is used for identifying * units and transforming between them. It follows the recommendations * for unit handling contained within FITS WCS paper I (Greisen & * Calabretta). All methods have protected access. * Methods: * astUnitMapper: Create a Mapping between two systems of units. * astUnitLabel: Returns a label for a given unit symbol. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 10-DEC-2002 (DSB): * Original version. * 10-FEB-2004 (DSB): * Added debug conditional code to keep track of memory leaks. * 15-JUL-2004 (DSB): * In astUnitMapper: if no Mapping can be found from input to * output units (e.g. because fo the less than perfect simplication * algorithm in SimplifyTree), try finding a Mapping from output to * input units and inverting the result. * 14-DEC-2004 (DSB): * In CreateTree, move the invocation of FixConstants from after * InvertConstants to before InvertConstants. This is because * InvertConstants ignores nodes which contain all constant * arguments. This results in constants not being inverted in * expressions such as "1/60 deg" (because all arguments are * constant in the the "1/60" node). * 18-JAN-2005 (DSB): * Fix memory leaks. * 2-FEB-2005 (DSB): * - Avoid using astStore to allocate more storage than is supplied * in the "data" pointer. This can cause access violations since * astStore will then read beyond the end of the "data" area. * 15-FEB-2005 (DSB): * - Modified CleanExp to fix up some common units mistakes. * 21-FEB-2005 (DSB): * - Modified CleanExp to accept as equivalent to * ^. * - Modified MakeTree to do case insensitive checking if case * sensitive checking failsto produce a match to a multiplier/unit * symbol combination. If this still produces no match, do a case * insensitive match for multiplier/unit label. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 6-APR-2006 (DSB): * Modify CleanExp to convert "MJY/STER" to standard form ("MJy/sr"). * 7-JUL-2006 (DSB): * Correct initialisation of "word" flag in CleanExp. * 17-MAY-2007 (DSB): * Simplify the units string returned by astUnitNormaliser. * - Fix indexing bug in CombineFactors. * 26-MAY-2007 (DSB): * - Correct error reporting in astUNitNormaliser. * - Fix bug in CleanExp that caused (for example) "-2" to be * converted to "^-2". * 2-DEC-2008 (DSB): * Correct memory allocation bug in CleanExp. * 6-MAY-2011 (DSB): * Include "adu" as basic unit. * 9-MAY-2011 (DSB): * Change "A" to be Ampere (as defined by FITS-WCS paper 1) rather * than "Angstrom". */ /* Module Macros. */ /* ============== */ /* Define the astCLASS macro (even although this is not a class implementation) to obtain access to the protected error and memory handling functions. */ #define astCLASS #define PI 3.141592653589793 #define E 2.718281828459045 /* Macro which returns the nearest integer to a given floating point value. */ #define NINT(x) (int)((x)+(((x)>0.0)?0.5:-0.5)) /* Macro identifying a character as lower or upper case letter, digit or + or -. */ #define ISWORD(c) (isalnum(c)||((c)=='+')||((c)=='-')) /* The number of basic dimension quantities used for dimensional analysis. In addition to the usual M, L and T, this includes pseudo-dimensions describing strictly dimensionless quantities such as plane angle, magnitude, etc. */ #define NQUANT 10 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "error.h" #include "memory.h" #include "pointset.h" #include "mapping.h" #include "unitmap.h" #include "zoommap.h" #include "mathmap.h" #include "unit.h" /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #ifdef THREAD_SAFE #include #endif /* Module Type Definitions. */ /* ======================== */ /* This declaration enumerates the codes for the operations which may legally be included in a units expression. */ typedef enum { OP_LDCON, /* Load constant */ OP_LDVAR, /* Load variable */ OP_LOG, /* Common logarithm */ OP_LN, /* Natural logarithm */ OP_EXP, /* Natural exponential */ OP_SQRT, /* Square root */ OP_POW, /* Exponentiate */ OP_DIV, /* Division */ OP_MULT, /* Multiplication */ OP_LDPI, /* Load constant PI */ OP_LDE, /* Load constant E */ OP_NULL /* Null operation */ } Oper; /* A structure describing a standard multiplier prefix. */ typedef struct Multiplier { const char *label; /* Multipler label string (null terminated) */ const char *sym; /* Multipler symbol string (null terminated) */ int symlen; /* Length of symbol (without trailing null ) */ int lablen; /* Length of label (without trailing null ) */ double scale; /* The scale factor associated with the prefix */ struct Multiplier *next; /* Next Multiplier in linked list */ } Multiplier; /* A structure describing a single node in a tree representation of a single units expression. */ typedef struct UnitNode { Oper opcode; /* Code for operation performed by this node */ int narg; /* No. of arguments used by the operation */ struct UnitNode **arg; /* Array of pointers to argument nodes */ double con; /* Constant to be loaded by OP_LDCON operations */ struct KnownUnit *unit; /* Known unit referred to by OP_LDVAR nodes */ Multiplier *mult; /* Multiplier used by OP_LDVAR nodes */ const char *name; /* User-defined unit referred to by OP_LDVAR nodes (no multiplier prefix included) */ } UnitNode; /* A structure describing a known unit. */ typedef struct KnownUnit { const char *sym; /* Unit symbol string (null terminated) */ const char *label; /* Unit label string (null terminated) */ int symlen; /* Length of symbol (without trailing null ) */ int lablen; /* Length of label (without trailing null ) */ struct UnitNode *head; /* Head of definition tree (NULL for basic units) */ struct KnownUnit *next; /* Next KnownUnit in linked list */ struct KnownUnit *use; /* KnownUnit to be used in place of this one */ } KnownUnit; /* Module Variables. */ /* ================= */ /* A pointer to the KnownUnit structure at the head of a linked list of such structures containing definitions of all known units. */ static KnownUnit *known_units = NULL; /* An array of pointers to KnownUnits which list the basic quantities used in dimensional analysis. */ static KnownUnit *quant_units[ NQUANT ]; /* A pointer to the Multiplier structure at the head of a linked list of such structures containing definitions of all known multipliers. */ static Multiplier *multipliers = NULL; /* Set up mutexes */ #ifdef THREAD_SAFE static pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX1 pthread_mutex_lock( &mutex1 ); #define UNLOCK_MUTEX1 pthread_mutex_unlock( &mutex1 ); static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); #else #define LOCK_MUTEX1 #define UNLOCK_MUTEX1 #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #endif /* Prototypes for Private Functions. */ /* ================================= */ static AstMapping *MakeMapping( UnitNode *, int * ); static KnownUnit *GetKnownUnits( int, int * ); static Multiplier *GetMultipliers( int * ); static UnitNode *ConcatTree( UnitNode *, UnitNode *, int * ); static UnitNode *CopyTree( UnitNode *, int * ); static UnitNode *CreateTree( const char *, int, int, int * ); static UnitNode *FixUnits( UnitNode *, UnitNode *, int * ); static UnitNode *FreeTree( UnitNode *, int * ); static UnitNode *MakeTree( const char *, int, int, int * ); static UnitNode *MakeLabelTree( const char *, int, int * ); static UnitNode *NewNode( UnitNode *, Oper, int * ); static UnitNode *CombineFactors( UnitNode **, double *, int, double, int * ); static const char *CleanExp( const char *, int * ); static int EndsWith( const char *, int, const char *, int * ); static int CmpTree( UnitNode *, UnitNode *, int, int * ); static void FixConstants( UnitNode **, int, int * ); static void InvertConstants( UnitNode **, int * ); static UnitNode *InvertTree( UnitNode *, UnitNode *, int * ); static void LocateUnits( UnitNode *, UnitNode ***, int *, int * ); static void MakeKnownUnit( const char *, const char *, const char *, int * ); static void MakeUnitAlias( const char *, const char *, int * ); static void RemakeTree( UnitNode **, int * ); static int SimplifyTree( UnitNode **, int, int * ); static int ComplicateTree( UnitNode **, int * ); static int ReplaceNode( UnitNode *, UnitNode *, UnitNode *, int * ); static void FindFactors( UnitNode *, UnitNode ***, double **, int *, double *, int * ); static const char *MakeExp( UnitNode *, int, int, int * ); static int DimAnal( UnitNode *, double[NQUANT], double *, int * ); static int Ustrcmp( const char *, const char *, int * ); static int Ustrncmp( const char *, const char *, size_t, int * ); static int SplitUnit( const char *, int, const char *, int, Multiplier **, int *, int * ); static UnitNode *ModifyPrefix( UnitNode *, int * ); static int ConStart( const char *, double *, int *, int * ); /* Debug functions... static const char *DisplayTree( UnitNode *, int ); static void OpSym( UnitNode *, char * ); static const char *OpName( Oper ); static const char *TreeExp( UnitNode * ); */ /* Function implementations. */ /* ========================= */ static const char *CleanExp( const char *exp, int *status ) { /* * Name: * CleanExp * Purpose: * Produce a clean copy of a units expression. * Type: * Private function. * Synopsis: * #include "unit.h" * const char *CleanExp( const char *exp ) * Class Membership: * Unit member function. * Description: * This function returns a pointer to dynamic memory containing a * cleaned copy of the supplied units expression. Cleaning consists of * the following operations: * - removal of leading and trailing white space. * - replacement of multiple adjacent spaces by a single space * - removal of spaces adjacent to a parenthesis * - removal of spaces adjacent to a binary operator * - translates various common non-standard units into equivalent * standard units. * * Such carefull handling of spaces is necessary since a space is * recognised by the MakeTree function as a multiplication operator. * Parameters: * exp * A pointer to the expression to be cleaned. * Returned Value: * A pointer to the cleaned expression, which should be freed using * astFree when no longer needed. * Notes: * - This function returns NULL if it is invoked with the global error * status set, or if it should fail for any reason. */ /* Local Variables: */ char **tok; char *p; char *r; char *result; char *s; char *t; char *w; const char *start; int i; int l; int len; char *tt; int ntok; int po; int ps; int word; /* Initialise */ result = NULL; /* Check inherited status */ if( !astOK ) return result; /* Split the supplied string up into tokens. Each block of contiguous alphanumeric characters is a token. Each contiguous block of non-alphanumerical characters is also a token. The + and - signs are counted as alphanumeric. */ start = exp; p = (char *) exp - 1; word = ISWORD( *( p + 1 ) ); ntok = 0; tok = NULL; while( *(++p) ){ if( word ) { if( !ISWORD( *p ) ) { l = p - start; t = astStore( NULL, start, l + 1 ); if( t ) t[ l ] = 0; tok = astGrow( tok, ntok + 1, sizeof( char * ) ); if( tok ) tok[ ntok++ ] = t; start = p; word = 0; } } else { if( ISWORD( *p ) ) { l = p - start; t = astStore( NULL, start, l + 1 ); if( t ) t[ l ] = 0; tok = astGrow( tok, ntok + 1, sizeof( char * ) ); if( tok ) tok[ ntok++ ] = t; start = p; word = 1; } } } l = p - start; t = astStore( NULL, start, l + 1 ); if( t ) t[ l ] = 0; tok = astGrow( tok, ntok + 1, sizeof( char * ) ); if( tok ) tok[ ntok++ ] = t; /* Check the tokens for known non-standard unit syntax, and replace with the equivalent standard syntax. Starlink SPLAT has a class called UnitUtilities which has more of these common units mistakes. AST has to be a bit more conservative than SPLAT though because of its wider remit. */ len = 0; tt = NULL; for( i = 0; i < ntok; i++ ) { t = tok[ i ]; l = strlen( t ); tt = astStore( tt, t, l + 1 ); /* Any alphabetical word followed by a digit is taken as ^. Any alphabetical word followed by a sign and a digit is taken as ^. */ if( l > 1 && *t != '-' && *t != '+' && strcspn( t, "0123456789" ) == l - 1 ) { tok[ i ] = astMalloc( l + 2 ); if( tok[ i ] ) { strcpy( tok[ i ], t ); w = t + l - 2; if( *w != '+' && *w != '-' ) { tok[ i ][ l - 1 ] = '^'; strcpy( tok[ i ] + l, t + l - 1 ); } else { tok[ i ][ l - 2 ] = '^'; strcpy( tok[ i ] + l - 1, t + l - 2 ); } t = astFree( t ); } l++; /* If the word ends with "micron" change to "(m*1.0E-6)". Should be OK for things like "Kmicron". */ } else if( ( s = strstr( t, "micron" ) ) ) { tok[ i ] = astMalloc( s - t + 11 ); if( tok[ i ] ) { w = tok[ i ]; *(w++) = '('; if( s > t ) { strncpy( w, t, s - t ); w += s - t; } strcpy( w, "m*1.0E-6)" ); l = s - t + 11; t = astFree( t ); } /* Convert "STER" to "sr". */ } else if( !Ustrcmp( t, "STER", status ) ) { tok[ i ] = astStore( NULL, "sr", 3 ); l = 2; t = astFree( t ); /* If the word ends with "JY" and is preceded by a single character, change to "Jy". Should be OK for things like "MJY". */ } else if( l == 3 && !strcmp( t + 1, "JY" ) ) { tok[ i ][ 2 ] = 'y'; /* If the word begins with "nano" (case-insensitive) change "nano" to "n". Such changes are usually handled by SplitUnit, but we need to handle this as a special case here since scanf seems to read "nan" as a string representation of NaN. */ } else if( !Ustrncmp( t, "nano", 4, status ) ) { tok[ i ] = astStore( NULL, t + 3, l - 2 ); if( tok[ i ] ) { *(tok[ i ]) = 'n'; t = astFree( t ); } l -= 3; } /* Update the total length of the string. */ len += l; } tt = astFree( tt ); /* Concatentate the tokens into a single string, freeing the individual strings. */ result = astMalloc( len + 1 ); if( result ) { p = result; for( i = 0; i < ntok; i++ ) { len = strlen( tok[ i ] ); memcpy( p, tok[ i ], len ); p += len; tok[ i ] = astFree( tok[ i ] ); } *p = 0; tok = astFree( tok ); /* Now do other cleaning. ---------------------- */ /* Initialise a pointer to the previous character read from the string. */ r = result - 1; /* Initialise a pointer to the next character to be written to the string. */ w = result; /* Pretend the previous character written to the string was a space. */ ps = 1; /* Read all the supplied string, copying it to earlier parts of the string discarding leading spaces and multiple adjacent embedded spaces in the process. */ while( *(++r) ) { /* If the character read is a space, only write it to the string if the previous character written was not a space (in which case set a flag to indicate that the previous character written to the string is now a space). */ if( isspace( *r ) ) { if( !ps ) { *(w++) = *r; ps = 1; } /* Write all non-space characters to the string, and clear the flag which indicates if the previous character written to the string was a space. */ } else { *(w++) = *r; ps = 0; } } /* If the last character written to the string was a space, reduce the length of the string by one since we do not want any trailing spaces. */ if( ps ) w--; /* Terminate the string. */ *w = 0; /* We now need to pass through the string again, this time removing any spaces which are adjacent to a binary operator or a parenthesis. */ r = result - 1; w = result; ps = 0; po = 0; while( *(++r) ) { /* If the current character is a space, only write it if the previous written character was not an operator or parenthesis. */ if( isspace( *r ) ) { if( !po ) { *(w++) = *r; po = 1; ps = 1; } /* If the current character is an operator or parenthesis, back up one character before writing it out if the previous written character was a space. */ } else if( *r == '*' || *r == '/' || *r == '^' || *r == '.' || *r == ')' || *r == '(' ) { if( ps ) w--; *(w++) = *r; po = 1; ps = 0; /* If the current character is not a space and not an operator symbol, just write it out. */ } else { *(w++) = *r; po = 0; ps = 0; } } /* Terminate the string. */ if( ps ) w--; *w = 0; } /* Return the result. */ return (const char *) result; } static int CmpTree( UnitNode *tree1, UnitNode *tree2, int exact, int *status ) { /* * Name: * CmpTree * Purpose: * Compares two trees of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * int CmpTree( UnitNode *tree1, UnitNode *tree2, int exact, int *status ) * Class Membership: * Unit member function. * Description: * This function returns a zero value if the two trees are * equivalent. This requires the trees to have identical structure * except that, if "exact" is zero, arguments for OP_MULT nodes can * be swapped. * * If the trees are not equivalent then a value of +1 or -1 is returned * depending on whether tree1 should be placed before or after tree2 * in a sorted list of trees. * Parameters: * tree1 * A pointer to the UnitNode at the head of the first tree. * tree2 * A pointer to the UnitNode at the head of the second tree. * exact * If non-zero, then OP_MULT nodes must have their arguments the * same way round in order for the OP_MULT nodes to match. Otherwise, * OP_MULT nodes with equivalent arguments match even if the * arguments are swapped. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the two trees are equal. +1 if tree1 should be placed before * tree2 in a sorted list of trees. -1 if tree1 should be placed after * tree2 in a sorted list of trees. * Notes: * - Zero is returned if an error has already occurred, or * if this function fails for any reason. */ /* Local Variables: */ int result; int i; Oper op; /* Initialise. */ result = 0; /* Check inherited status. */ if( !astOK ) return result; /* If the op codes differ, compare them as integers. */ op = tree1->opcode; if( op != tree2->opcode ) { result = ( op > tree2->opcode ) ? 1: -1; /* If both supplied nodes are OP_LDVAR nodes, compare the associated names. */ } else if( op == OP_LDVAR ){ result = strcmp( tree1->name, tree2->name ); /* If both supplied nodes are constant nodes, compare the constant values. */ } else if( tree1->con != AST__BAD ){ result = astEQUAL( tree1->con, tree2->con ) ? 0 : ( ( tree1->con > tree2->con ) ? 1 : -1 ); /* Otherwise, compare the arguments for the node. */ } else { for( i = 0; i < tree1->narg; i++ ) { result = CmpTree( tree1->arg[ i ], tree2->arg[ i ], exact, status ); if( result ) break; } /* If the head nodes of the two trees are OP_MULT nodes, and the above check determined they are different, this may be just because they have their operands swapped. If "exact" si zero, this is considered an insignificant difference between the two trees which we should ignore. To check for this try comparing the arguments again, this time swapping the arguments of tree2. */ if( result && op == OP_MULT && !exact ) { for( i = 0; i < tree1->narg; i++ ) { result = CmpTree( tree1->arg[ i ], tree2->arg[ 1 - i ], 0, status ); if( result ) break; } } } /* If an error has occurred, return zero. */ if( !astOK ) result = 0; /* Return the answer. */ return result; } static UnitNode *CombineFactors( UnitNode **factors, double *powers, int nfactor, double coeff, int *status ) { /* * Name: * CombineFactors * Purpose: * Create a tree which represents the product of the supplied factors. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *CombineFactors( UnitNode **factors, double *powers, * int nfactor, double coeff, int *status ) * Class Membership: * Unit member function. * Description: * This function createa a tree of UnitNodes which represents the * product of the supplied factors, and the supplied coefficient. * The factors are sorted before being combined, using the sort order * implemented by the CmpTree function. * Parameters: * factors * A pointer to an array with "nfactor" elements, each element being * a pointer to a UnitNode which is a factor of the required tree. * On exit, the array is sorted. * powers * A pointer to an array with "nfactor" elements, each element being a * double holding the power of the associated factor in "factors". * On exit, the array reflects the sorting applied to "factors". * nfactor * The number of elements in the "factors" and "powers" arrays. * coeff * The overall coefficient to be applied to the product of the factors. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which is at the head of the new tree. * Notes: * - A NULL pointer is returned if an error has already occurred, or * if this function fails for any reason. */ /* Local Variables: */ UnitNode *result; int i; int j; int jp; int done; UnitNode *ftmp; UnitNode *node1; UnitNode *node2; UnitNode *pnode; double ptmp; /* Initialise. */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Sort the supplied list of factors, modifying the powers array correspondingly. A simple bubblesort algorithm is used since there will only be a handfull of factors. */ for( i = nfactor - 1; i > 0; i-- ) { done = 1; for( j = 0, jp = 1; j < i; j++, jp++ ) { if( CmpTree( factors[ j ], factors[ jp ], 0, status ) > 0 ) { ftmp = factors[ j ]; factors[ j ] = factors[ jp ]; factors[ jp ] = ftmp; ptmp = powers[ j ]; powers[ j ] = powers[ jp ]; powers[ jp ] = ptmp; done = 0; } } if( done ) break; } /* The first root term of the returned tree is the coefficient, unless the coefficient is 1.0, in which case it will be the first factor. */ if( coeff != 1.0 ) { node1 = NewNode( NULL, OP_LDCON, status ); if( astOK ) node1->con = coeff; } else { node1 = NULL; } /* Loop through the factors. */ for( i = 0; i < nfactor; i++ ) { /* If the power of this factor is zero, we ignore the factor. */ if( powers[ i ] != 0.0 ) { /* If the power of this factor is one, we use the factor directly. */ if( astEQUAL( powers[ i ], 1.0 ) ) { node2 = CopyTree( factors[ i ], status ); /* Otherwise, for non-zero, non-unity powers, we create a POW node for the factor. */ } else { node2 = NewNode( NULL, OP_POW, status ); pnode = NewNode( NULL, OP_LDCON, status ); if( astOK ) { pnode->con = powers[ i ]; node2->arg[ 0 ] = CopyTree( factors[ i ], status ); node2->arg[ 1 ] = pnode; } } /* We now combine node1 and node2 using an OP_MULT node, which becomes the "node1" for the next pass. On the first pass we may have no node1 (if the supplied coefficient was 1.0), in which case we reserve the current node2 as the node1 for the next pass. */ if( node1 ) { result = NewNode( NULL, OP_MULT, status ); if( astOK ) { result->arg[ 0 ] = node1; result->arg[ 1 ] = node2; node1 = result; } } else { node1 = node2; } } } /* Ensure we have a node to return. */ if( astOK ) { if( !result ) result = node1; if( !result ) { result = NewNode( NULL, OP_LDCON, status ); if( astOK ) result->con = 1.0; } } /* If an error has occurred, free any new tree. */ if( !astOK ) result = FreeTree( result, status ); /* Return the answer. */ return result; } static int ComplicateTree( UnitNode **node, int *status ) { /* * Name: * ComplicateTree * Purpose: * Removes standardisations introduced by SimplifyTree. * Type: * Private function. * Synopsis: * #include "unit.h" * int ComplicateTree( UnitNode **node ) * Class Membership: * Unit member function. * Description: * This function modifies a tree of UnitNodes by removing standardisations * introduced by SimplifyTree. The standardisations removed are ones * which would make the corresponding algebraic expression (as produced * by MakeExp) unnatural to a human reader. * Parameters: * node * The address of a pointer to the UnitNode at the head of the tree * which is to be complicated. On exit the supplied tree is freed and * a pointer to a new tree is placed at the given address. * Returned Value: * Non-zero if any change was introduced into the tree. */ /* Local Variables: */ int i; UnitNode *newnode; UnitNode *node1; UnitNode *node2; UnitNode *node3; Oper op; double con; double fk; int k; int result; double kcon; /* Initialise */ result = 0; /* Check inherited status. */ if( !astOK ) return result; /* Initiallially, we have no replacement node. */ newnode = NULL; node1 = NULL; node3 = NULL; /* Complicate the sub-trees corresponding to the arguments of the node at the head of the supplied tree. */ for( i = 0; i < (*node)->narg; i++ ) { if( ComplicateTree( &( (*node)->arg[ i ] ), status ) ) result = 1; } /* Now undo specific simplifications appropriate to the nature of the node at the head of the tree. */ op = (*node)->opcode; /* If the head is an OP_MULT node with a constant first argument and a "LN" second argument, rearrange the nodes to represent ln(x**k) instead of k*ln(x). If k is an integer multiple of "0.1/ln(10)" convert the "ln" function into a "log" (base 10) function. Check for "k==1" in which case we do not need a POW node. */ if( (*node)->opcode == OP_MULT ) { con = (*node)->arg[ 0 ]->con; if( con != AST__BAD && (*node)->arg[ 1 ]->opcode == OP_LN ) { fk = 10.0*con*log( 10.0 ); k = NINT(fk); if( astEQUAL(fk,((double)k)) ) { newnode = NewNode( NULL, OP_LOG, status ); con = k/10.0; } else { newnode = NewNode( NULL, OP_LN, status ); } node2 = CopyTree( (*node)->arg[ 1 ]->arg[ 0 ], status ); if( !astEQUAL( con, 1.0 ) ){ node1 = CopyTree( (*node)->arg[ 0 ], status ); node3 = NewNode( NULL, OP_POW, status ); } if( astOK ) { if( !astEQUAL( con, 1.0 ) ){ node1->con = con; node3->arg[ 0 ] = node2; node3->arg[ 1 ] = node1; newnode->arg[ 0 ] = node3; } else { newnode->arg[ 0 ] = node2; } } /* Replace "(A**-1)*B" with "B/A" */ } else if( (*node)->arg[ 0 ]->opcode == OP_POW && astEQUAL( (*node)->arg[ 0 ]->arg[ 1 ]->con, -1.0 )) { newnode = NewNode( NULL, OP_DIV, status ); if( astOK ) { newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 1 ], status ); newnode->arg[ 1 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); } /* Replace "B*(A**-1)" with "B/A" */ } else if( (*node)->arg[ 1 ]->opcode == OP_POW && astEQUAL( (*node)->arg[ 1 ]->arg[ 1 ]->con, -1.0 )) { newnode = NewNode( NULL, OP_DIV, status ); if( astOK ) { newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ], status ); newnode->arg[ 1 ] = CopyTree( (*node)->arg[ 1 ]->arg[ 0 ], status ); } /* Convert (x**k)*(y**k) to (x*y)**k. */ } else if( (*node)->arg[ 0 ]->opcode == OP_POW && (*node)->arg[ 1 ]->opcode == OP_POW && astEQUAL( (*node)->arg[ 0 ]->arg[ 1 ]->con, (*node)->arg[ 1 ]->arg[ 1 ]->con )) { newnode = NewNode( NULL, OP_POW, status ); node1 = NewNode( NULL, OP_MULT, status ); if( astOK ) { node1->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); node1->arg[ 1 ] = CopyTree( (*node)->arg[ 1 ]->arg[ 0 ], status ); newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 1 ], status ); } /* Convert c*sqrt(x) to sqrt((c**2)*x) (if c > 0). */ } else if( (kcon=(*node)->arg[ 0 ]->con) != AST__BAD && kcon > 0.0 && (*node)->arg[ 1 ]->opcode == OP_SQRT ) { newnode = NewNode( NULL, OP_SQRT, status ); node1 = NewNode( NULL, OP_MULT, status ); node2 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node2->con = kcon*kcon; node1->arg[ 0 ] = node2; node1->arg[ 1 ] = CopyTree( (*node)->arg[ 1 ]->arg[ 0 ], status ); newnode->arg[ 0 ] = node1; } } /* If the head node is a POW node, replace "x**0.5" by sqrt(x) */ } else if( (*node)->opcode == OP_POW ) { if( astEQUAL( (*node)->arg[ 1 ]->con, 0.5 ) ) { newnode = NewNode( NULL, OP_SQRT, status ); if( astOK ) { newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ], status ); } } } /* If we have produced a new node which is identical to the old node, free it. Otherwise, indicate we have made some changes. */ if( newnode ) { if( !CmpTree( newnode, *node, 1, status ) ) { newnode = FreeTree( newnode, status ); } else { result = 1; } } /* If an error has occurred, free any new node. */ if( !astOK ) { newnode = FreeTree( newnode, status ); result = 0; } /* If we have a replacement node, free the supplied tree and return a pointer to the new tree. */ if( newnode ) { FreeTree( *node, status ); *node = newnode; } /* If the above produced some change, try simplifying (without re-introducing the standardisation we have just got rid of!) and then re-complicating the tree. */ if( result ) { SimplifyTree( node, 0, status ); ComplicateTree( node, status ); } /* Return the result. */ return result; } static UnitNode *ConcatTree( UnitNode *tree1, UnitNode *tree2, int *status ) { /* * Name: * ConcatTree * Purpose: * Concatenate two trees together. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *ConcatTree( UnitNode *tree1, UnitNode *tree2, int *status ) * Class Membership: * Unit member function. * Description: * This function a pointer to the head of a new tree of UnitNodes which * is formed by feeding the output of "tree1" (i.e. the quantity * represented by the node at the head of tree1) into the (single) * input of "tree2" (i.e. the single OP_LDVAR Node containined within * tree2). * Parameters: * tree1 * A pointer to the first tree. * tree2 * A pointer to the second tree. This should have no more than one * OP_LDVAR node. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which is at the head of the new tree. * Notes: * - If "tree2" contains zero units, a NULL pointer is returned but no * error is reported. * - If "tree2" contains more than one unit, an error is reported * error is reported. * - A NULL pointer is returned if an error has already occurred, or * if this function fails for any reason. */ /* Local Variables: */ UnitNode *result; UnitNode **units; int nunits; /* Initialise. */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Produce a copy of tree2. */ result = CopyTree( tree2, status ); /* Locate the OP_LDVAR node in the copy of tree2. */ units = NULL; nunits = 0; LocateUnits( result, &units, &nunits, status ); /* If no OP_LDVAR nodes were found in tree2, we cannot concatenate the trees. */ if( nunits > 0 ) { /* Report an error if the number of pointers returned is larger than 1. */ if( nunits > 1 && astOK ) { astError( AST__INTER, "ConcatTree(unit): tree2 uses %d units - " "should be 1 (internal AST programming error).", status, nunits ); } /* Replace the OP_LDVAR node in the copy of tree2 with a copy of tree1. */ if( astOK ) { /* If the node at the head of the supplied tree2 is the node to be replaced, just free the tree created earlier and return a copy of tree1. */ if( units[ 0 ] == result ) { FreeTree( result, status ); result = CopyTree( tree1, status ); /* Otherwise, search for the node to be replaced and do the substitution within the tree created earlier. */ } else { ReplaceNode( result, units[ 0 ], CopyTree( tree1, status ), status ); } } } /* Free resources. */ units = astFree( units ); /* If an error has occurred, free any new tree. */ if( !astOK ) result = FreeTree( result, status ); /* Return the answer. */ return result; } static int ConStart( const char *text, double *val, int *nc, int *status ) { /* * Name: * ConStart * Purpose: * See if the supplied string starts with a literal numeric constant. * Type: * Private function. * Synopsis: * #include "unit.h" * int ConStart( const char *text, double *val, int *nc, int *status ) * Class Membership: * Unit member function. * Description: * This function checks if the supplied string starts with a literal * numeric constant and returns it if it does. It is a wrap-up for scanf * since scanf has non-standard behaviour on some platforms (e.g. Cygwin * scanf interprets the character "n" as a floating point number!). * Parameters: * text * The text to check. * val * Address of a double to receive any numerical constant read * from the start of the string. Unity is returned if the string * does not start with a numerical constant. * nc * Address of an int to receive the number of characters used to * create the value returned in "val". Zero is returned if the * string does not start with a numerical constant. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the text started with a numerical constant. */ /* Local Variables: */ int result; const char *c; /* Initialise */ *nc = 0; *val = 1.0; /* Return zero if no text was supplied */ if( !text ) return 0; /* Use sscanf to see if the string begin with a numerical constant */ result = astSscanf( text, "%lf%n", val, nc ); /* If so, check that the first non-blank character in the string is not "N" (interpreted by Cygwin as numerical zero!). */ if( result ) { c = text; while( isspace( *c ) ) c++; if( *c == 'n' || *c == 'N' ) { result = 0; *nc = 0; *val = 1.0; } } /* Return the result. */ return result; } static UnitNode *CopyTree( UnitNode *tree, int *status ) { /* * Name: * CopyTree * Purpose: * Create a new tree of UnitNodes containing a copy of a given tree. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *CopyTree( UnitNode *tree, int *status ) * Class Membership: * Unit member function. * Description: * This function creates a copy of the supplied tree of UnitNodes. * Parameters: * tree * The UnitNode at the head of the tree to be copied. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the UnitNode at the head of the new tree. * Notes: * - A value of NULL will be returned if this function is invoked with * the global error status set, or if it should fail for any reason. */ /* Local Variables: */ UnitNode **args; UnitNode *result; int i; int narg; /* Initialise. */ result = NULL; /* Check the inherited status. */ if( !astOK || !tree ) return result; /* Create a new node to represent the head of the supplied tree. */ result = astMalloc( sizeof( UnitNode ) ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the fields of the supplied node. */ narg = tree->narg; result->arg = NULL; result->unit = tree->unit; result->mult = tree->mult; result->opcode = tree->opcode; result->narg = narg; result->con = tree->con; result->name = tree->name ? astStore( NULL, tree->name, strlen( tree->name ) + 1 ) : NULL; /* Create an array of UnitNode pointers for the arguments. */ args = astMalloc( narg*sizeof( UnitNode * ) ); if( astOK ) { result->arg = args; /* Copy the sub-trees headed by the argument nodes. */ for( i = 0; i < narg; i++ ) { args[ i ] = CopyTree( tree->arg[ i ], status ); } } } /* Free any result if an error occurred. */ if( !astOK ) result = FreeTree( result, status ); /* Return the answer. */ return result; } static UnitNode *CreateTree( const char *exp, int basic, int lock, int *status ){ /* * Name: * CreateTree * Purpose: * Convert an algebraic units expression into a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *CreateTree( const char *exp, int basic, int lock, int *status ) * Class Membership: * Unit member function. * Description: * This function converts the supplied algebraic units expression into * a tree of UnitNodes. The result tree can optionally be expanded to * create a tree in which the "roots" (LDVAR nodes) all refer to * basic units. * Parameters: * exp * The units expression. This should not include any leading or * trailing spaces. * basic * Should the tree created from parsing "exp" be expanded so that * the leaf nodes of the tree are all basic units? * lock * Use a mutex to guard access to the KnownUnits list? * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which forms the head of a tree of UnitNodes * representing the supplied unit expression. * Notes: * - A NULL value is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ UnitNode *result; const char *cleanex; /* Initialise */ result = NULL; /* Check the global error status, and that we have a string. */ if ( !astOK ) return result; /* Produce a clean copy of the supplied string. This has no leading or trailing white space, and any spaces adjacent to operators within the string are removed (this is needed because spaces are treated as multiplication symbols). */ cleanex = CleanExp( exp, status ); /* If the string is blank, return the NULL pointer. Otherwise, create a tree of UnitNodes describing the units. The returned tree has LDVAR nodes which refer to the unit symbols contained in the supplied string. */ if( cleanex && (*cleanex) ) { result = MakeTree( cleanex, strlen( cleanex ), lock, status ); /* Replace each subtree which simply combines constants (i.e. which has no OP_LDVAR nodes) with a single OP_LDCON node. */ FixConstants( &result, 0, status ); /* Invert literal constant unit multipliers. */ InvertConstants( &result, status ); /* Now replace each LDVAR node which refers to a known derived unit with a sub-tree which defines the derived unit in terms of known basic units. The LDVAR nodes in the resulting tree all refer to basic units. */ if( basic ) RemakeTree( &result, status ); } /* Free resources. */ cleanex = astFree( (void *) cleanex ); /* Free any returned tree if an error has occurred. */ if( !astOK ) result = FreeTree( result, status ); /* Return the result. */ return result; } static int DimAnal( UnitNode *node, double powers[NQUANT], double *scale, int *status ) { /* * Name: * DimAnal * Purpose: * Perform a dimensional analysis of a unit tree. * Type: * Protected function. * Synopsis: * #include "unit.h" * int DimAnal( UnitNode *node, double powers[NQUANT], double *scale, int *status ) * Class Membership: * Unit member function. * Description: * This function returns a set of powers and a scaling factor which * represent the units tree. * Parameters: * node * Pointer to the UnitNode at the head of the unit tree. * powers * An array in which are returned the powers for each of the following * basic units (in the order shown): kilogramme, metre, second, radian, * Kelvin, count, adu, photon, magnitude, pixel. If the supplied unit * does not depend on a given basic unit a value of 0.0 will be returned * in the array. The returns values represent a system of units which is * a scaled form of the supplied units, expressed in the basic units of * m, kg, s, rad, K, count, adu, photon, mag and pixel. For instance, a * returned array of [1,0,-2,0,0,0,0,0,0,0] would represent "m/s**2". * scale * Pointer to a location at which to return a scaling factor for the * supplied units. The is the value, in the units represented by the * returned powers, which corresponds to a value of 1.0 in the supplied * units. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the tree was analysed succesfully. Zero otherwise. * Notes: * - Zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables; */ Oper oper; int result; int i; double p0[ NQUANT ]; double p1[ NQUANT ]; double s0; double s1; /* Check inherited status */ if( !astOK ) return 0; /* Initialise the powers of all dimensions to zero, and set the scaling factor to unity. */ result = 1; *scale = 1.0; for( i = 0; i < NQUANT; i++ ) powers[ i ] = 0.0; /* Load constant: constant is dimensionaless so leave powers unchanged, and set the scaling factor. */ oper = node->opcode; if( oper == OP_LDCON ) { *scale = 1.0/node->con; /* Load variable: check it is one of the basic known dimensional quantities. If so, set the power of the quantity to unity and store the scale factor. If the unit is "g" modify the scale factor so that the analysis quantity is "kg". */ } else if( oper == OP_LDVAR ) { result = 0; for( i = 0; i < NQUANT; i++ ) { if( node->unit == quant_units[ i ] ) { powers[ i ] = 1.0; *scale = node->mult ? 1.0/node->mult->scale : 1.0; if( !strcmp( node->unit->sym, "g" ) ) *scale *= 0.001; result = 1; break; } } /* How does dimensional analysis handle log or exp units?*/ } else if( oper == OP_LOG ) { result= 0; } else if( oper == OP_LN ) { result= 0; } else if( oper == OP_EXP ) { result= 0; /* Get the powers for the child unit and then multiply each by 0.5 and take the square root of the scale factor. */ } else if( oper == OP_SQRT ) { result = DimAnal( node->arg[0], powers, scale, status ); if( result ) { for( i = 0; i < NQUANT; i++ ) powers[ i ]*= 0.5; *scale = sqrt( *scale ); } /* Similarly for pow nodes. */ } else if( oper == OP_POW ) { result = DimAnal( node->arg[0], powers, scale, status ); if( result ) { double power = node->arg[1]->con; for( i = 0; i < NQUANT; i++ ) powers[ i ]*= power; *scale = pow( *scale, power ); } /* Binary operators. Analyses the operands dimensions and combine. */ } else if( oper == OP_DIV ) { if( DimAnal( node->arg[0], p0, &s0, status ) && DimAnal( node->arg[1], p1, &s1, status ) ) { for( i = 0; i < NQUANT; i++ ) powers[ i ] = p0[ i ] - p1[ i ]; *scale = s0/s1; } else { result = 0; } } else if( oper == OP_MULT ) { if( DimAnal( node->arg[0], p0, &s0, status ) && DimAnal( node->arg[1], p1, &s1, status ) ) { for( i = 0; i < NQUANT; i++ ) powers[ i ] = p0[ i ] + p1[ i ]; *scale = s0*s1; } else { result = 0; } /* Named constants are dimensionless */ } else if( oper == OP_LDPI ) { *scale = 1.0/PI; } else if( oper == OP_LDE ) { *scale = 1.0/E; } return result; } static int EndsWith( const char *c, int nc, const char *test, int *status ){ /* * Name: * EndsWith * Purpose: * See if a string ends with another string * Type: * Private function. * Synopsis: * #include "unit.h" * int EndsWith( const char *c, int nc, const char *test, int *status ) * Class Membership: * Unit member function. * Description: * This function sees if the string given by "c" ends with the string * given by "test". The comparison is case-insensitive. * Parameters: * c * A pointer to the last character in the string to be tested. * nc * The number of characters in the string to be tested. * test * A pointer to the string to be tested for. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the string "c" ends with the string "test". */ /* Local Variables: */ const char *start; int i; int result; int tlen; /* initialise. */ result = 0; /* Check inherited status. */ if( !astOK ) return result; /* Check the string being tested for is not longer than the string being tested. */ tlen = strlen( test ); if( tlen <= nc ){ /* Get a pointer to where the matching string would start if the string "c" ends with the required string "test". */ start = c - tlen + 1; /* Do the comparison. */ result = 1; for( i = 0; i < tlen; i++ ) { if( tolower( start[ i ] ) != tolower( test[ i ] ) ) { result = 0; break; } } } /* Return the result. */ return result; } static void FindFactors( UnitNode *node, UnitNode ***factors, double **powers, int *nfactor, double *coeff, int *status ){ /* * Name: * FindFactors * Purpose: * Find the factors within an expression given by a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * void FindFactors( UnitNode *node, UnitNode ***factors, double **powers, * int *nfactor, double *coeff, int *status ) * Class Membership: * Unit member function. * Description: * This function analyses the supplied tree of UnitNoes and returns * an array of pointers to nodes within the supplied tree which form * factors of the tree. The power associated with each factor is also * returned, together with an overall coefficient for the tree. The * expression represented by the tree is thus the product of the * coefficient with each of the factors, each raised to the associated * power. * Parameters: * node * A pointer to the UnitNode at the head of the tree which is to be * analysed. * factors * The address at which to return a pointer to an array with "*nfactor" * elements, each element being a pointer to a UnitNode within the * supplied tree which is a factor of the supplied tree. * powers * The address at which to return a pointer to an array with "*nfactor" * elements, each element being a double holding the power of the * associated factor in "*factors". * nfactor * The address of an int containing the number of elements in the * returned "*factors" and "*powers" arrays. * coeff * The address of a double containing the overall coefficient to be * applied to the product of the factors. * status * Pointer to the inherited status variable. * Notes: * - If the supplied node is a constant node, then "*coeff" is * returned holding the value of the constant and "*nfactor" is returned * equal to zero ("*factors" and "*powers" are returned holding NULL). * - If an error has already occurred, or if this function fails, then * "*factors" and "*powers" are returned holding NULL, "*nfactor" is * returned holding zero and "*coeff" is returned holding 1.0. */ /* Local Variables: */ int i; int j; int found; UnitNode **fact1; double *pow1; double coeff1; int nfac1; double con; /* Initialise */ *factors = NULL; *powers = NULL; *nfactor = 0; *coeff = 1.0; /* Check inherited status. */ if( !astOK ) return; /* If the node at the head of the supplied tree is an OP_MULT node... */ if( node->opcode == OP_MULT ) { /* Find the factors of the two arguments of the OP_MULT node. */ FindFactors( node->arg[ 0 ], factors, powers, nfactor, coeff, status ); FindFactors( node->arg[ 1 ], &fact1, &pow1, &nfac1, &coeff1, status ); /* Combine the two lists. Loop round the factors of the seocnd argument. */ for( i = 0; i < nfac1; i++ ) { /* See if there is already an equivalent factor in the returned list of factors. */ found = 0; for( j = 0; j < *nfactor; j++ ) { if( !CmpTree( (*factors)[ j ], fact1[ i ], 0, status ) ){ found = 1; break; } } /* If so, increment the power of the factor. */ if( found ) { (*powers)[ j ] += pow1[ i ]; /* Otherwise, add the factor to the end of the returned list. */ } else { *factors = astGrow( *factors, *nfactor + 1, sizeof( UnitNode *) ); *powers = astGrow( *powers, *nfactor + 1, sizeof( double ) ); if( astOK ) { (*factors)[ *nfactor ] = fact1[ i ]; (*powers)[ (*nfactor)++ ] = pow1[ i ]; } } } /* Modify the overall coefficient. */ *coeff *= coeff1; /* Free resources */ fact1 = astFree( fact1 ); pow1 = astFree( pow1 ); /* If the node at the head of the supplied tree is an OP_POW node, */ } else if( node->opcode == OP_POW ) { /* Find the factors of the first argument. */ FindFactors( node->arg[ 0 ], factors, powers, nfactor, coeff, status ); /* Multiply all the factor powers by the constant exponent of the POW node. */ con = node->arg[ 1 ]->con; for( j = 0; j < *nfactor; j++ ) { (*powers)[ j ] *= con; } /* Exponentiate the coefficient. */ if( *coeff >= 0.0 || (int) con == con ) { *coeff = pow( *coeff, con ); } else { astError( AST__BADUN, "Simplifying a units expression requires a " "negative value to be raised to a non-intergal power." , status); } /* If the node at the head of the supplied tree is an OP_DIV node, */ } else if( node->opcode == OP_DIV ) { /* Find the factors of the two arguments of the OP_DIV node. */ FindFactors( node->arg[ 0 ], factors, powers, nfactor, coeff, status ); FindFactors( node->arg[ 1 ], &fact1, &pow1, &nfac1, &coeff1, status ); /* Combine the two lists. Loop round the factors of the second argument (the denominator). */ for( i = 0; i < nfac1; i++ ) { /* See if there is already an equivalent factor in the returned list of factors. */ found = 0; for( j = 0; j < *nfactor; j++ ) { if( !CmpTree( (*factors)[ j ], fact1[ i ], 0, status ) ){ found = 1; break; } } /* If so, decrement the power of the factor. */ if( found ) { (*powers)[ j ] -= pow1[ i ]; /* Otherwise, add the factor to the end of the returned list, with a negated power. */ } else { *factors = astGrow( *factors, *nfactor + 1, sizeof( UnitNode *) ); *powers = astGrow( *powers, *nfactor + 1, sizeof( double ) ); if( astOK ) { (*factors)[ *nfactor ] = fact1[ i ]; (*powers)[ (*nfactor)++ ] = -pow1[ i ]; } } } /* Modify the overall coefficient. */ if( coeff1 != 0.0 ) { *coeff /= coeff1; } else { astError( AST__BADUN, "Simplifying a units expression" "requires a division by zero." , status); } /* Free resources */ fact1 = astFree( fact1 ); pow1 = astFree( pow1 ); /* If the node at the head of the supplied tree is an OP_SQRT node, */ } else if( node->opcode == OP_SQRT ) { /* Find the factors of the argument. */ FindFactors( node->arg[ 0 ], factors, powers, nfactor, coeff, status ); /* Multiply all the factor powers by 0.5. */ for( j = 0; j < *nfactor; j++ ) { (*powers)[ j ] *= 0.5; } /* Square root the coefficient. */ if( *coeff >= 0.0 ) { *coeff = sqrt( *coeff ); } else { astError( AST__BADUN, "Simplifying a units expression requires " "the square root of a negative value to be taken." , status); } /* If the node at the head of the supplied tree is constant we have no factors but we have a coeffcient. */ } else if( node->con != AST__BAD ) { *coeff = node->con; /* Other nodes have no factors other than themselves, so just return a pointer to the supplied node. */ } else { *factors = astMalloc( sizeof( UnitNode *) ); *powers = astMalloc( sizeof( double ) ); if( astOK ) { *nfactor = 1; (*factors)[ 0 ] = node; (*powers)[ 0 ] = 1.0; *coeff = 1.0; } } /* If an error has occurred, free any returned resources. */ if( !astOK ) { *factors = astFree( *factors ); *powers = astFree( *powers ); *nfactor = 0; *coeff = 1.0; } } static void FixConstants( UnitNode **node, int unity, int *status ) { /* * Name: * FixConstants * Purpose: * Take the reciprocal of all constants in a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * void FixConstants( UnitNode **node, int unity, int *status ) * Class Membership: * Unit member function. * Description: * This function replaces sub-trees which have a constant value by * a single OP_LDCON node which loads the appropriate constant. * Parameters: * node * The address of a pointer to the UnitNode at the head of the tree * which is to be fixed. On exit the supplied tree is freed and a * pointer to a new tree is palced at he given address. * unity * If non-zero, then all multiplicative constants are set to 1.0, and * their original values are forgotten, but only if the other * argument of the OP_MULT node is an OP_LDVAR, OP_POW or OP_SQRT Node. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; UnitNode *newnode; int allcon; Oper op; double newcon; /* Check inherited status and pointer. */ if( !astOK || !node || !(*node) ) return; /* Initiallially, we have no replacement node */ newnode = NULL; newcon = AST__BAD; /* There is nothing to fix if the node has no arguments. */ if( (*node)->narg > 0 ) { /* Note the op code for the node. */ op = (*node)->opcode; /* Fix up the argument nodes. Also note if all the arguments are constants. */ allcon = 1; for( i = 0; i < (*node)->narg; i++ ) { FixConstants( &( (*node)->arg[ i ] ), unity, status ); if( (*node)->arg[ i ]->con == AST__BAD ) allcon = 0; } /* If an OP_MULT nodes within a simplified tree has a constant argument, it will always be argument zero. If this is an OP_MULT node and arg[0] is constant and "unity" is non-zero and arg[1] is an OP_LDVAR, OP_POW or OP_SQRT node, replace the constant value by 1.0. */ if( unity && op == OP_MULT && (*node)->arg[ 0 ]->con != AST__BAD && ( (*node)->arg[ 1 ]->opcode == OP_LDVAR || (*node)->arg[ 1 ]->opcode == OP_SQRT || (*node)->arg[ 1 ]->opcode == OP_POW ) ) { (*node)->arg[ 0 ]->con = 1.0; } /* If the arguments of this node are all constants, replace the node by an OP_LDCON node which loads the resulting constant value. */ if( allcon ) { if( (*node)->narg > 0 ) { newnode = NewNode( NULL, OP_LDCON, status ); if( astOK ) { if( op == OP_LOG ) { if( (*node)->arg[ 0 ]->con > 0.0 ) { newcon = log10( (*node)->arg[ 0 ]->con ); } else { astError( AST__BADUN, "Illegal negative or zero constant " "value '%g' encountered.", status, (*node)->arg[ 0 ]->con ); } } else if( op == OP_LN ){ if( (*node)->arg[ 0 ]->con > 0.0 ) { newcon = log( (*node)->arg[ 0 ]->con ); } else { astError( AST__BADUN, "Illegal negative or zero constant value " "'%g' encountered.", status, (*node)->arg[ 0 ]->con ); } } else if( op == OP_EXP ){ newcon = exp( (*node)->arg[ 0 ]->con ); } else if( op == OP_SQRT ){ if( (*node)->arg[ 0 ]->con >= 0.0 ) { newcon = sqrt( (*node)->arg[ 0 ]->con ); } else { astError( AST__BADUN, "Illegal negative constant value " "'%g' encountered.", status, (*node)->arg[ 0 ]->con ); } } else if( op == OP_POW ){ if( (*node)->arg[ 0 ]->con >= 0.0 || (int) (*node)->arg[ 1 ]->con == (*node)->arg[ 1 ]->con ) { newcon = pow( (*node)->arg[ 0 ]->con, (*node)->arg[ 1 ]->con ); } else { astError( AST__BADUN, "Illegal negative constant value " "'%g' encountered.", status, (*node)->arg[ 0 ]->con ); } } else if( op == OP_DIV ){ if( (*node)->arg[ 1 ]->con != 0.0 ) { newcon = (*node)->arg[ 0 ]->con / (*node)->arg[ 1 ]->con; } else { astError( AST__BADUN, "Illegal zero constant value encountered." , status); } } else if( op == OP_MULT ){ newcon = (*node)->arg[ 0 ]->con * (*node)->arg[ 1 ]->con; } if( astOK ) newnode->con = newcon; } } } } /* If an error has occurred, free any new node. */ if( !astOK ) newnode = FreeTree( newnode, status ); /* If we have a replacement node, free the supplied tree and return a pointer to the new tree. */ if( newnode ) { FreeTree( *node, status ); *node = newnode; } } static UnitNode *FixUnits( UnitNode *node, UnitNode *test, int *status ) { /* * Name: * FixUnits * Purpose: * Assign a constant value to all units except for one. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *FixUnits( UnitNode *node, UnitNode *test, int *status ) * Class Membership: * Unit member function. * Description: * This function returns a copy of the supplied tree of UnitNodes. All * OP_LDVAR nodes within the copy which refer to units which differ * from those referred to by the supplied test node are replaced by * OP_LDCON nodes which load the constant value 1.0. * Parameters: * node * A pointer to the UnitNode at the head of the tree to be used. * test * A pointer to an OP_LDVAR node which defines the units which are * *not* to be replaced by a constant value of 1.0. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which is at the head of a tree of UnitNodes * which forms the required copy of th einput tree. * Notes: * - A NULL pointer is returned if an error has already occurred, or * if this function fails for any reason. */ /* Local Variables: */ int i; UnitNode *result; /* Initialise. */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Create a complete copy of the supplied tree. */ result = CopyTree( node, status ); /* Is the node at the head of the supplied tree an OP_LDVAR node? */ if( node->opcode == OP_LDVAR ) { /* Does it refer to a unit which differs from that of the test node? If so annul the copy created above and return a new OP_LDCON node which loads the constant value 1.0. */ if( strcmp( test->name, node->name ) ) { FreeTree( result, status ); result = NewNode( NULL, OP_LDCON, status ); if( astOK ) result->con = 1.0; } /* If the supplied node is not an OP_LDVAR node, check each argument of the head node. */ } else { for( i = 0; i < node->narg; i++ ) { /* Free the resources used to hold this argument in the tree copy created above. */ FreeTree( result->arg[ i ], status ); /* Create a new argument tree by calling this function recursively to fix units in the argument sub-trees. */ result->arg[ i ] = FixUnits( node->arg[ i ], test, status ); } } /* If an error has occurred, free any new tree. */ if( !astOK ) result = FreeTree( result, status ); /* Return the answer. */ return result; } static UnitNode *FreeTree( UnitNode *node, int *status ) { /* * Name: * FreeTree * Purpose: * Free resources used by a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *FreeTree( UnitNode *node, int *status ) * Class Membership: * Unit member function. * Description: * This function frees the memory used to store a tree of UnitNodes. * Parameters: * node * A pointer to the UnitNode at the head of the tree which is to be * freed. * status * Pointer to the inherited status variable. * Returned Value: * A NULL pointer is returned. * Notes: * - This function attempts to execute even if it is invoked with * the global error status set. */ /* Local Variables: */ int i; /* Check a node was supplied. */ if( node ) { /* Recursively free any argument nodes. */ if( node->arg ) { for( i = 0; i < node->narg; i++ ) { (node->arg)[ i ] = FreeTree( (node->arg)[ i ], status ); } node->arg = astFree( node->arg ); } /* Nullify other pointers for safety. */ node->unit = NULL; node->mult = NULL; /* Free the copy of the symbol string (if any). */ node->name = astFree( (char *) node->name ); /* Free the memory holding the node. */ node = astFree( node ); } /* Return a null pointer. */ return NULL; } static KnownUnit *GetKnownUnits( int lock, int *status ) { /* * Name: * GetKnownUnits * Purpose: * Get a pointer to the head of a linked list of known unit definitions. * Type: * Private function. * Synopsis: * #include "unit.h" * KnownUnit *GetKnownUnits( int lock, int *status ) * Class Membership: * Unit member function. * Description: * This function returns a pointer to the head of a linked list of known * unit definitions. The unit definitions are created as static module * variables if they have not previously been created. * Parameters: * lock * If non-zero, then lock a mutex prior to accessing the list of * known units. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the first known unit definition. * Notes: * - A NULL pointer is returned if it is invoked with the global error * status set, or if an error occurs. */ /* Local Variables: */ int iq; KnownUnit *result; /* Initialise. */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Ensure the known units list is only initialised once. */ if( lock ) { LOCK_MUTEX1 } /* If the linked list of KnownUnit structures describing the known units has not yet been created, create it now. A pointer to the head of the linked list is put into the static variable "known_units". */ if( !known_units ) { /* At the same time we store pointers to the units describing the basic quantities used in dimensional analysis. Initialise th index of the next such unit. */ iq = 0; /* Create definitions for the known units. First do all IAU basic units. We include "g" instead of "kg" because otherwise we would have to refer to a gramme as a milli-kilogramme. */ MakeKnownUnit( "g", "gram", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "m", "metre", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "s", "second", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "rad", "radian", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "K", "Kelvin", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "A", "Ampere", NULL, status ); MakeKnownUnit( "mol", "mole", NULL, status ); MakeKnownUnit( "cd", "candela", NULL, status ); /* Now do all IAU derived units. Unit definitions may only refer to units which have already been defined. */ MakeKnownUnit( "sr", "steradian", "rad rad", status ); MakeKnownUnit( "Hz", "Hertz", "1/s", status ); MakeKnownUnit( "N", "Newton", "kg m/s**2", status ); MakeKnownUnit( "J", "Joule", "N m", status ); MakeKnownUnit( "W", "Watt", "J/s", status ); MakeKnownUnit( "C", "Coulomb", "A s", status ); MakeKnownUnit( "V", "Volt", "J/C", status ); MakeKnownUnit( "Pa", "Pascal", "N/m**2", status ); MakeKnownUnit( "Ohm", "Ohm", "V/A", status ); MakeKnownUnit( "S", "Siemens", "A/V", status ); MakeKnownUnit( "F", "Farad", "C/V", status ); MakeKnownUnit( "Wb", "Weber", "V s", status ); MakeKnownUnit( "T", "Tesla", "Wb/m**2", status ); MakeKnownUnit( "H", "Henry", "Wb/A", status ); MakeKnownUnit( "lm", "lumen", "cd sr", status ); MakeKnownUnit( "lx", "lux", "lm/m**2", status ); /* Now do additional derived and basic units listed in the FITS-WCS paper. */ MakeKnownUnit( "deg", "degree", "pi/180 rad", status ); MakeKnownUnit( "arcmin", "arc-minute", "1/60 deg", status ); MakeKnownUnit( "arcsec", "arc-second", "1/3600 deg", status ); MakeKnownUnit( "mas", "milli-arcsecond", "1/3600000 deg", status ); MakeKnownUnit( "min", "minute", "60 s", status ); MakeKnownUnit( "h", "hour", "3600 s", status ); MakeKnownUnit( "d", "day", "86400 s", status ); MakeKnownUnit( "yr", "year", "31557600 s", status ); MakeKnownUnit( "a", "year", "31557600 s", status ); MakeKnownUnit( "eV", "electron-Volt", "1.60217733E-19 J", status ); MakeKnownUnit( "erg", "erg", "1.0E-7 J", status ); MakeKnownUnit( "Ry", "Rydberg", "13.605692 eV", status ); MakeKnownUnit( "solMass", "solar mass", "1.9891E30 kg", status ); MakeKnownUnit( "u", "unified atomic mass unit", "1.6605387E-27 kg", status ); MakeKnownUnit( "solLum", "solar luminosity", "3.8268E26 W", status ); MakeKnownUnit( "Angstrom", "Angstrom", "1.0E-10 m", status ); MakeKnownUnit( "micron", "micron", "1.0E-6 m", status ); MakeKnownUnit( "solRad", "solar radius", "6.9599E8 m", status ); MakeKnownUnit( "AU", "astronomical unit", "1.49598E11 m", status ); MakeKnownUnit( "lyr", "light year", "9.460730E15 m", status ); MakeKnownUnit( "pc", "parsec", "3.0867E16 m", status ); MakeKnownUnit( "count", "count", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "adu", "analogue-to-digital unit", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "photon", "photon", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "Jy", "Jansky", "1.0E-26 W /m**2 /Hz", status ); MakeKnownUnit( "mag", "magnitude", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "G", "Gauss", "1.0E-4 T", status ); MakeKnownUnit( "pixel", "pixel", NULL, status ); quant_units[ iq++ ] = known_units; MakeKnownUnit( "barn", "barn", "1.0E-28 m**2", status ); MakeKnownUnit( "D", "Debye", "(1.0E-29/3) C.m", status ); if( iq != NQUANT && astOK ) { astError( AST__INTER, "unit(GetKnownUnits): %d basic quantities " "noted but this should be %d (internal AST programming " "error).", status, iq, NQUANT ); } /* Unit aliases... */ MakeUnitAlias( "Angstrom", "Ang", status ); MakeUnitAlias( "count", "ct", status ); MakeUnitAlias( "photon", "ph", status ); MakeUnitAlias( "Jy", "Jan", status ); MakeUnitAlias( "pixel", "pix", status ); MakeUnitAlias( "s", "sec", status ); MakeUnitAlias( "m", "meter", status ); } /* If succesful, return the pointer to the head of the list. */ if( astOK ) result = known_units; /* Allow the next thread to proceed. */ if( lock ) { UNLOCK_MUTEX1 } /* Return the result. */ return result; } static Multiplier *GetMultipliers( int *status ) { /* * Name: * GetMultiplier * Purpose: * Get a pointer to the head of a linked list of multiplier definitions. * Type: * Private function. * Synopsis: * #include "unit.h" * Multiplier *Multipliers( void ) * Class Membership: * Unit member function. * Description: * This function returns a pointer to the head of a linked list of known * multiplier definitions. The multiplier definitions are created as * static module variables if they have not previously been created. * Returned Value: * A pointer to the first known multiplier definition. * Notes: * - A NULL pointer is returned if it is invoked with the global error * status set, or if an error occurs. */ /* Local Variables: */ Multiplier *result; Multiplier *mult; /* Initialise. */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Ensure the list is only initialised by one thread. */ LOCK_MUTEX2 /* If the linked list of Multiplier structures describing the known multipliers has not yet been created, create it now. A pointer to the head of the linked list is put into the static variable "multipliers". */ if( !multipliers ) { /* Define a macro to create a multiplier struncture and add it to the linked list of multiplier structures. */ #define MAKEMULT(s,sl,sc,lab,ll) \ mult = astMalloc( sizeof( Multiplier ) ); \ if( astOK ) { \ mult->sym = s; \ mult->symlen = sl; \ mult->lablen = ll; \ mult->scale = sc; \ mult->label = lab; \ mult->next = multipliers; \ multipliers = mult; \ } /* Use the above macro to create all the standard multipliers listed in the FITS WCS paper I. */ MAKEMULT("d",1,1.0E-1,"deci",4) MAKEMULT("c",1,1.0E-2,"centi",5) MAKEMULT("m",1,1.0E-3,"milli",5) MAKEMULT("u",1,1.0E-6,"micro",5) MAKEMULT("n",1,1.0E-9,"nano",4) MAKEMULT("p",1,1.0E-12,"pico",4) MAKEMULT("f",1,1.0E-15,"femto",5) MAKEMULT("a",1,1.0E-18,"atto",4) MAKEMULT("z",1,1.0E-21,"zepto",5) MAKEMULT("y",1,1.0E-24,"yocto",5) MAKEMULT("da",2,1.0E1,"deca",4) MAKEMULT("h",1,1.0E2,"hecto",5) MAKEMULT("k",1,1.0E3,"kilo",4) MAKEMULT("M",1,1.0E6,"mega",4) MAKEMULT("G",1,1.0E9,"giga",4) MAKEMULT("T",1,1.0E12,"tera",4) MAKEMULT("P",1,1.0E15,"peta",4) MAKEMULT("E",1,1.0E18,"exa",3) MAKEMULT("Z",1,1.0E21,"zetta",5) MAKEMULT("Y",1,1.0E24,"yotta",5) /* Undefine the macro. */ #undef MAKEMULT } /* If succesful, return the pointer to the head of the list. */ if( astOK ) result = multipliers; /* Allow the next thread to proceed. */ UNLOCK_MUTEX2 /* Return the result. */ return result; } static void InvertConstants( UnitNode **node, int *status ) { /* * Name: * InvertConstants * Purpose: * Take the reciprocal of all constants in a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * void InvertConstants( UnitNode **node, int *status ) * Class Membership: * Unit member function. * Description: * This function replaces constant unit coefficients by their reciprocal. * This is because a string such as "0.01 m" will be interpreted as * meaning "multiply a value in metres by 0.01 to get the value in the * required units", whereas what is actually meant is "use units of * 0.01 of a metre" which requires us to divide the value in metres by * 0.01, not multiply it. * Parameters: * node * The address of a pointer to the UnitNode at the head of the tree. * On exit the supplied tree is freed and a pointer to a new tree is * placed at the given address. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; UnitNode *newnode; int allcon; Oper op; /* Check inherited status and pointer. */ if( !astOK || !node || !(*node) ) return; /* Initiallially, we have no replacement node */ newnode = NULL; /* There is nothing to fix if the node has no arguments. */ if( (*node)->narg > 0 ) { /* Note the op code for the node. */ op = (*node)->opcode; /* Fix up the argument nodes. Also note if all the arguments are constants. */ allcon = 1; for( i = 0; i < (*node)->narg; i++ ) { InvertConstants( &( (*node)->arg[ i ] ), status ); if( (*node)->arg[ i ]->con == AST__BAD ) allcon = 0; } /* If all nodes are constant, there are no co-efficients to invert. */ if( !allcon ) { /* Iif this is a multiplication node, see if either of its arguments is a constant. If so, invert the constant. This is because a string like "0.01 m" means "each unit is 0.01 of a metre". Therefore, to transform a value in metres into required units means multiplying the metres value by 100.0 (i.e the reciprocal of 0.01), not 0.01. */ if( op == OP_MULT ) { for( i = 0; i < 2; i++ ) { if( (*node)->arg[ i ]->con != AST__BAD ) { if( (*node)->arg[ i ]->con != 0.0 ) { (*node)->arg[ i ]->con = 1.0/(*node)->arg[ i ]->con; } else { astError( AST__BADUN, "Illegal zero constant encountered." , status); } } } /* Likewise, check for division nodes in which the denominator is constant. */ } else if( op == OP_DIV ) { if( (*node)->arg[ 1 ]->con != AST__BAD ) { if( (*node)->arg[ 1 ]->con != 0.0 ) { (*node)->arg[ 1 ]->con = 1.0/(*node)->arg[ 1 ]->con; } else { astError( AST__BADUN, "Illegal zero constant encountered." , status); } } /* If this is a "pow" node check that the second argument is constant (required by FITS WCS paper I). */ } else if( op == OP_POW ) { if( (*node)->arg[ 1 ]->con == AST__BAD ) { astError( AST__BADUN, "Illegal variable exponent." , status); } } } } /* If an error has occurred, free any new node. */ if( !astOK ) newnode = FreeTree( newnode, status ); /* If we have a replacement node, free the supplied tree and return a pointer to the new tree. */ if( newnode ) { FreeTree( *node, status ); *node = newnode; } } static UnitNode *InvertTree( UnitNode *fwdnode, UnitNode *src, int *status ) { /* * Name: * InvertTree * Purpose: * Invert a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *InvertTree( UnitNode *fwdnode, UnitNode *src ) * Class Membership: * Unit member function. * Description: * This function inverts a tree of UnitNodes. The supplied tree should * have exactly one OP_LDVAR node. This will be the quantity represented * by the node at the head of the returned tree. * Parameters: * fwdnode * A pointer to the UnitNode at the head of the tree which is to be * inverted. * src * A pointer to a UnitNode which is to be used as the root of the * inverted tree. That is, the output from this node should form * the (one and only) varying input to the inverted tree. If the * supplied tree is succesfulyl inverted, the tree of which "src" * is the head will be contained within the returned inverted tree. * Therefore "src" only needs to be freed explicitly if this * function fails to invert the supplied tree for any reason. If * this function succeeds, then "src" will be freed as part of * freeing the returned inverted tree. * Returned Value: * A pointer to a UnitNode which forms the head of the inverted tree. * Algorithm: * The algorithm works through the supplied forward tree, from the head * to the roots. First, the supplied node at the head of the forward * tree is inverted. To be invertable, the supplied head node must have * exactly one varying argument (any other arguments must be fixed, * i.e. not vary). This varying argument becomes the output of the * inverted node. The other (fixed) arguments to the forward node are * also used as arguments to the inverted node. The supplied "src" node * is used as the single varying input to the inverted node. Having * inverted the supplied forward head node, this function is called * recursively to invert the lower parts of the forward tree (i.e. the * part of the forward tree which provided the varying input to node * which has just been inverted). * Notes: * - It is assumed that he supplied forward tree has been simplified * using SimplifyTree. This means that the tree contains no nodes with * the following op codes: OP_LOG, OP_SQRT. OP_DIV (SimplifyTree * converts these nodes into OP_LN, OP_POW and OP_MULT nodes). * - A value of NULL will be returned if this function is invoked with * the global error status set, or if it should fail for any reason. */ /* Local Variables: */ UnitNode *newnode; UnitNode *nextnode; UnitNode *result; UnitNode *node1; Oper fop; int varg; /* Initialise */ result = NULL; /* Check inherited status. */ if( !astOK ) return result; /* Initiallially, we have no replacement node */ newnode = NULL; nextnode = NULL; /* Save the op code at the head of the forward tree. */ fop = fwdnode->opcode; /* If the head of the forward tree is a OP_EXP node. Inverse of "exp(x)" is "ln(x)". */ if( fop == OP_EXP ) { newnode = NewNode( NULL, OP_LN, status ); if( astOK ) { newnode->arg[ 0 ] = src; nextnode = fwdnode->arg[ 0 ]; } /* If the head of the forward tree is a OP_LN node. Inverse of "ln(x)" is "exp(x)". */ } else if( fop == OP_LN ) { newnode = NewNode( NULL, OP_EXP, status ); if( astOK ) { newnode->arg[ 0 ] = src; nextnode = fwdnode->arg[ 0 ]; } /* If the head of the forward tree is a OP_POW node. Inverse of "x**k" is "x**(1/k)" */ } else if( fop == OP_POW ) { newnode = NewNode( NULL, OP_POW, status ); node1 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node1->con = 1.0/fwdnode->arg[ 1 ]->con; newnode->arg[ 0 ] = src; newnode->arg[ 1 ] = node1; nextnode = fwdnode->arg[ 0 ]; } /* If the head of the forward tree is a OP_MULT node... */ } else if( fop == OP_MULT ) { /* The node is only invertable if it has one constant node and one non-constant node. Get the index of the varying argument. */ if( fwdnode->arg[ 0 ]->con != AST__BAD && fwdnode->arg[ 1 ]->con == AST__BAD ) { varg = 1; } else if( fwdnode->arg[ 0 ]->con == AST__BAD && fwdnode->arg[ 1 ]->con != AST__BAD ) { varg = 0; } else { varg = -1; } if( varg != -1 ) { /* The inverse of "k*x" is "(1/k)*x" (we use MULT nodes instead of DIV nodes to maintain the standardisation implemented by SimplifyTree). */ newnode = NewNode( NULL, OP_MULT, status ); node1 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node1->con = 1.0/fwdnode->arg[ 1 - varg ]->con; newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = src; nextnode = fwdnode->arg[ varg ]; } } /* If the head of the forward tree is a OP_LDVAR node, there is nothing left to invert. SO return a pointer to the suppleid source node. */ } else if( fop == OP_LDVAR ) { result = src; nextnode = NULL; /* If the head of the forward tree is any other node (e.g. a OP_LDCON node), the tree cannot be inverted. */ } else { nextnode = NULL; } /* If we managed to invert the node at the head of the supplied tree, continue to invert its varying argument node (if any). */ if( nextnode && newnode ) result = InvertTree( nextnode, newnode, status ); /* If the tree could not be inverted, free the newnode. */ if( !result ) newnode = FreeTree( newnode, status ); /* If an error has occurred, free any new node. */ if( !astOK ) result = FreeTree( result, status ); /* Return the result. */ return result; } static void LocateUnits( UnitNode *node, UnitNode ***units, int *nunits, int *status ){ /* * Name: * LocateUnits * Purpose: * Locate the units used by a supplied tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * void LocateUnits( UnitNode *node, UnitNode ***units, int *nunits, int *status ) * Class Membership: * Unit member function. * Description: * This function locates the units used by a supplied tree of * UnitNodes. * Parameters: * node * A pointer to the UnitNode at the head of the tree to be searched. * units * The address at which is stored a pointer to an array of "*nunits" * elements. Each element of the array holds a pointer to a UnitNode. * The array is extended on exit to hold pointers to the OP_LDVAR nodes * within the supplied tree (i.e. nodes which represent named units, * either known or unknown). A node is only included in the returned * array if no other node for the same unit is already included in the * array. A NULL pointer should be supplied on the first invocation of * this function. * nunits * The address of an integer which holds the number of elements in * the array given by "*units". Updated on exit to included any * elements added to the array. Zero should be supplied on the first * invocation of this function. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; int found; /* Check the global error status. */ if( !astOK ) return; /* Is the node at the head of the supplied tree an OP_LDVAR node? */ if( node->opcode == OP_LDVAR ) { /* If an array was supplied, see if it already contains a pointer to a node which refers to the same units. */ found = 0; if( *units ) { for( i = 0; i < *nunits; i++ ) { if( !strcmp( (*units)[ i ]->name, node->name ) ) { found = 1; break; } } } /* If not, ensure the array is big enough and add a pointer to the supplied node to the array. */ if( !found ) { *units = astGrow( *units, *nunits + 1, sizeof( UnitNode * ) ); if( astOK ) (*units)[ (*nunits)++ ] = node; } /* If the supplied node is not an OP_LDVAR node, call this function recursively to search the argument sub-trees. */ } else { for( i = 0; i < node->narg; i++ ) { LocateUnits( node->arg[ i ], units, nunits, status ); } } } static const char *MakeExp( UnitNode *tree, int mathmap, int top, int *status ) { /* * Name: * MakeExp * Purpose: * Make an algebraic expression from a supplied tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * const char *MakeExp( UnitNode *tree, int mathmap, int top, int *status ) * Class Membership: * Unit member function. * Description: * This function produces a string holding an algebraic expression * corresponding to a supplied tree of UnitNodes. * Parameters: * tree * A pointer to the UnitNode at the head of the tree to be converted * into an algebraic expression. * mathmap * If zero, format as an axis label expression. If 1, format as a * MathMap expression. If 2, format as a FITS unit string. * top * Should be non-zero for a top-level entry to this function, and * zero for a recursive entry. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the cleaned expression, which should be freed using * astFree when no longer needed. * Notes: * - This function returns NULL if it is invoked with the global error * status set, or if it should fail for any reason. */ /* Local Variables: */ UnitNode *newtree; UnitNode *sunit; char *a; char *result; char buff[200]; const char *arg0; const char *arg1; const char *mtxt; int larg0; int larg1; int lbuff; int mlen; int par; int tlen; /* Check inherited status. */ result = NULL; if( !astOK ) return result; /* Modify the tree to make the resulting transformation functions more natural to human readers. */ newtree = CopyTree( tree, status ); ComplicateTree( &newtree, status ); /* If we are producing an axis label... */ if( !mathmap ) { /* Fix all multiplicative constants to 1.0 if they multiply an OP_LDVAR OP_SQRT or OP_POW node. This is on the assumption that the returned label should not include any simple unit scaling (e.g. if the output label would be "2.345*wavelength", we prefer simply to use "wavelength" since a scaled wavelength is still a wavelength - i.e. simple scaling does not change the dimensions of a quantity). */ FixConstants( &newtree, 1, status ); /* Simplify the tree again to get rid of the 1.0 terms which may have been introduced by the previous line (but do not re-introduce any standardisations - removing them was the reason for calling ComplicateTree). If this simplication introduces any changes, try fixing multiplicative constants again, and so on, until no more changes occur. */ while( SimplifyTree( &newtree, 0, status ) ) { FixConstants( &newtree, 1, status ); } } /* Produce a string describing the action performed by the UnitNode at the head of the supplied tree, and then invoke this function recursively to format any arguments of the head node. */ /* Constant valued nodes... just format the constant in a local buffer and then copy the buffer. */ if( newtree->con != AST__BAD ) { lbuff = sprintf( buff, "%.*g", DBL_DIG, newtree->con ); result = astStore( NULL, buff, lbuff + 1 ); /* "Load Variable Value" nodes - return the variable name. If this is a recursive call to this function, and we are producing a label, append a single space before and after the name. */ } else if( newtree->opcode == OP_LDVAR ) { tlen = strlen( newtree->name ); if( !mathmap && !top ){ result = astMalloc( tlen + 3 ); if( result ) { result[ 0 ] = ' '; memcpy( result + 1, newtree->name, tlen ); memcpy( result + tlen + 1, " ", 2 ); } } else if( mathmap == 2 ) { if( newtree->mult ) { mlen = newtree->mult->symlen; mtxt = newtree->mult->sym; } else { mlen = 0; mtxt = NULL; } result = astMalloc( tlen + 1 + mlen ); if( result ) { if( mtxt ) memcpy( result, mtxt, mlen ); memcpy( result + mlen, newtree->name, tlen + 1 ); } } else { result = astStore( NULL, newtree->name, tlen + 1 ); } /* Single argument functions... place the argument in parentheses after the function name. */ } else if( newtree->opcode == OP_LOG ) { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); if( mathmap == 1 ) { result = astMalloc( larg0 + 8 ); if( result ) memcpy( result, "log10(", 7 ); a = result + 6; } else { result = astMalloc( larg0 + 6 ); if( result ) memcpy( result, "log(", 5 ); a = result + 4; } if( result ){ memcpy( a, arg0, larg0 + 1 ); memcpy( a + larg0, ")", 2 ); } arg0 = astFree( (void *) arg0 ); } else if( newtree->opcode == OP_LN ) { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); if( mathmap == 1 ) { result = astMalloc( larg0 + 6 ); if( result ) memcpy( result, "log(", 5 ); a = result + 4; } else { result = astMalloc( larg0 + 5 ); if( result ) memcpy( result, "ln(", 4 ); a = result + 3; } if( astOK ){ memcpy( a, arg0, larg0 ); memcpy( a + larg0, ")", 2 ); } arg0 = astFree( (void *) arg0 ); } else if( newtree->opcode == OP_EXP ) { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); result = astMalloc( larg0 + 6 ); if( result ){ memcpy( result, "exp(", 5 ); memcpy( result + 4, arg0, larg0 ); memcpy( result + 4 + larg0, ")", 2 ); } arg0 = astFree( (void *) arg0 ); } else if( newtree->opcode == OP_SQRT ) { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); result = astMalloc( larg0 + 7 ); if( result ){ memcpy( result, "sqrt(", 6 ); memcpy( result + 5, arg0, larg0 ); memcpy( result + 5 + larg0, ")", 2 ); } arg0 = astFree( (void *) arg0 ); /* POW... the exponent (arg[1]) is always a constant and so does not need to be placed in parentheses. The first argument only needs to be placed in parentheses if it is a two arg node (except we also put it in parentheses if it is an OP_LDVAR node and "mathmap" is zero - this is because such OP_LDVAR nodes will correspond to axis labels which will have spaces before and after them which would look odd if not encloses in parentheses). */ } else if( newtree->opcode == OP_POW ) { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); arg1 = MakeExp( newtree->arg[ 1 ], mathmap, 0, status ); larg1 = strlen( arg1 ); if( newtree->arg[ 0 ]->narg == 2 || (newtree->arg[ 0 ]->opcode == OP_LDVAR && !mathmap) ) { par = 1; result = astMalloc( larg0 + larg1 + 7 ); if( result ) memcpy( result, "(", 2 ); a = result + 1; } else { par = 0; result = astMalloc( larg0 + larg1 + 5 ); a = result; } if( result ) { memcpy( a, arg0, larg0 ); a += larg0; if( par ) *(a++) = ')'; memcpy( a, "**", 3 ); a += 2; memcpy( a, arg1, larg1 ); a += larg1; *a = 0; } arg0 = astFree( (void *) arg0 ); arg1 = astFree( (void *) arg1 ); /* DIV... the first argument (numerator) never needs to be in parentheses. The second argument (denominator) only needs to be placed in parentheses if it is a MULT node. */ } else if( newtree->opcode == OP_DIV ) { if( mathmap == 2 && ( sunit = ModifyPrefix( newtree, status ) ) ) { result = (char *) MakeExp( sunit, mathmap, 0, status ); sunit = FreeTree( sunit, status ); } else { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); arg1 = MakeExp( newtree->arg[ 1 ], mathmap, 0, status ); larg1 = strlen( arg1 ); if( newtree->arg[ 1 ]->opcode == OP_MULT && strchr( arg1, '*' ) ) { par = 1; result = astMalloc( larg0 + larg1 + 4 ); } else { par = 0; result = astMalloc( larg0 + larg1 + 2 ); } if( result ) { memcpy( result, arg0, larg0 ); a = result + larg0; *(a++) = '/'; if( par ) *(a++) = '('; memcpy( a, arg1, larg1 ); a += larg1; if( par ) *(a++) = ')'; *a = 0; } arg0 = astFree( (void *) arg0 ); arg1 = astFree( (void *) arg1 ); } /* MULT... the second argument never needs to be in parentheses. The first argument only needs to be placed in parentheses if it is a DIV or POW node. */ } else if( newtree->opcode == OP_MULT ) { if( mathmap == 2 && ( sunit = ModifyPrefix( newtree, status ) ) ) { result = (char *) MakeExp( sunit, mathmap, 0, status ); sunit = FreeTree( sunit, status ); } else { arg0 = MakeExp( newtree->arg[ 0 ], mathmap, 0, status ); larg0 = strlen( arg0 ); arg1 = MakeExp( newtree->arg[ 1 ], mathmap, 0, status ); larg1 = strlen( arg1 ); /* If this is a top-level entry and we are producing an axis label, do not include any constant multiplicative terms. */ if( top && !mathmap ) { if( newtree->arg[ 0 ]->con != AST__BAD ) arg0 = astFree( (void *) arg0 ); if( newtree->arg[ 1 ]->con != AST__BAD ) arg1 = astFree( (void *) arg1 ); } /* If we have two arguments, concatentate them, placing the operands in parentheses if necessary. */ if( arg0 && arg1 ) { if( ( newtree->arg[ 0 ]->opcode == OP_DIV && strchr( arg0, '/' ) ) || ( newtree->arg[ 0 ]->opcode == OP_POW && strstr( arg0, "**" ) ) ) { par = 1; result = astMalloc( larg0 + larg1 + 4 ); if( result ) result[ 0 ] = '('; a = result + 1; } else { par = 0; result = astMalloc( larg0 + larg1 + 2 ); a = result; } if( result ) { memcpy( a, arg0, larg0 ); a += larg0; if( par ) *(a++) = ')'; *(a++) = '*'; memcpy( a, arg1, larg1 ); a += larg1; *a = 0; } arg0 = astFree( (void *) arg0 ); arg1 = astFree( (void *) arg1 ); /* If we do not have two arguments, just return the one we do have. */ } else if( arg0 ){ result = (char *) arg0; } else { result = (char *) arg1; } } } /* Free the complicated tree. */ newtree = FreeTree( newtree, status ); /* Free the returned string if an error has occurred. */ if( !astOK ) result = astFree( result ); /* Return the result. */ return (const char *) result; } static void MakeKnownUnit( const char *sym, const char *label, const char *exp, int *status ){ /* * Name: * MakeKnownUnit * Purpose: * Create a KnownUnit structure describing a known unit. * Type: * Private function. * Synopsis: * #include "unit.h" * void MakeKnownUnit( const char *sym, const char *label, const char *exp, int *status ) * Class Membership: * Unit member function. * Description: * This function creates a KnownUnit structure decribing a known unit, * and adds it to the head of the linked list of known units stored in * a module variable. * Parameters: * sym * A pointer to a string which can be used as a symbol to represent * the new named unit. Once defined, this symbol can be included within * the definition of other derived units. The string should contain * only alphabetical characters (no digits, spaces, punctuation, * etc). Symbols are case sensitive (e.g. "s" is second, but "S" is * Siemens). The string should not include any multiplier prefix. * label * Pointer to a null terminated string containing the label for * the required units. No restriction on content. * exp * This should be a pointer to a null terminated string containing * a definition of the required unit. See the description of the * "in" and "out" parameters for the astUnitMapper function. * * A NULL pointer or a blank string may supplied for "exp", which * is interpreted as a request for a new basic unit to be created with * the symbol and label given by the other parameters. * status * Pointer to the inherited status variable. * Notes: * - The supplied symbol and label strings are not copied. The * supplied pointers are simply stored in the returned structure. * Therefore the strings to which the pointers point should not be * modified after this function returned (in fact this function is * always called with literal strings for these arguments). */ /* Local Variables: */ KnownUnit *result; /* Check the global error status. */ if( !astOK ) return; /* Indicate that subsequent memory allocations may never be freed (other than by any AST exit handler). */ astBeginPM; /* Allocate memory for the structure, and check the returned pointer can be used safely. */ result = astMalloc( sizeof( KnownUnit ) ); if( astOK ) { /* In case of errors, first nullify the pointer to the next KnownUnit. */ result->next = NULL; /* Store the supplied label and symbol pointers. */ result->sym = sym; result->label = label; /* Store the length of the symbol (without the trailing null character). */ result->symlen = strlen( sym ); /* Store the length of the label (without the trailing null character). */ result->lablen = strlen( label ); /* Create a tree of UnitNodes describing the unit if an expression was supplied. */ result->head = exp ? CreateTree( exp, 1, 0, status ) : NULL; /* Unit aliases are replaced in use by the KnownUnit pointed to by the "use" component of the structure. Indicate this KnownUnitis not an alias by setting its "use" component NULL. */ result->use = NULL; } /* Mark the end of the section in which memory allocations may never be freed (other than by any AST exit handler). */ astEndPM; /* If an error has occurred, free any returned structure. */ if( !astOK ) { result->head = FreeTree( result->head, status ); result = astFree( result ) ; /* Otherwise, add the new KnownUnit to the head of the linked list of known units. */ } else { result->next = known_units; known_units = result; } } static AstMapping *MakeMapping( UnitNode *tree, int *status ) { /* * Name: * MakeMapping * Purpose: * Create a new Mapping from a given tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * AstMapping *MakeMapping( UnitNode *tree ) * Class Membership: * Unit member function. * Description: * This function creates a Mapping with a forward transformation equal * to the transformation described by the tree of UnitNodes. The head * node of the tree corresponds to the output of the Mapping. * Parameters: * tree * The UnitNode at the head of the tree to be used. It should have * exactly one OP_LDVAR node, and should have been simplified using * the SimplifyTree function. * Returned Value: * A pointer to the Mapping. Its Nin and Nout attributes will both be 1. * Notes: * - A value of NULL will be returned if this function is invoked with * the global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstMapping *result; UnitNode *inv; UnitNode *src; const char *fwdexp; char *fwdfun; const char *invexp; char *invfun; int lfwd; int linv; /* Initialise. */ result = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* First see if a UnitMap can be used to represent the Mapping from input units to output units. This will be the case if the supplied tree consists of a aingle OP_LDVAR node (corresponding to the input units). */ if( tree->opcode == OP_LDVAR ) { result = (AstMapping *) astUnitMap( 1, "", status ); /* Now see if a UnitMap or ZoomMap can be used to represent the Mapping from input units to output units. This will be the case if the supplied tree consists of a OP_MULT node with one constant argument and on OP_LDVAR argument (corresponding to the input units). The standardisation done by SimplifyTree will have ensured that the constant will be argument 0 (and will also have converted "x/k" trees into "(1/k)*x" trees). */ } else if( tree->opcode == OP_MULT && tree->arg[ 0 ]->con != AST__BAD && tree->arg[ 1 ]->opcode == OP_LDVAR ) { if( tree->arg[ 0 ]->con == 1.0 ) { result = (AstMapping *) astUnitMap( 1, "", status ); } else { result = (AstMapping *) astZoomMap( 1, tree->arg[ 0 ]->con, "", status ); } /* For other trees we need to create a MathMap. */ } else { /* Format the supplied tree as an algebraic expression, and get its length. */ fwdexp = MakeExp( tree, 1, 1, status ); lfwd = strlen( fwdexp ); /* The MathMap constructor requires the forward and inverse transformation functions to be specified as equations (i.e. including an equals sign). We use the output variable name "output_units" (the astUnitMapper function creates the supplied tree usign the variable name "input_units" ). */ lfwd += 13; /* Invert the supplied tree and create an algebraic expression from it. */ src = NewNode( NULL, OP_LDVAR, status ); if( astOK ) src->name = astStore( NULL, "output_units", 13 ); inv = InvertTree( tree, src, status ); if( !inv ) { src = FreeTree( src, status ); astError( AST__BADUN, "MakeMapping(Unit): Failed to invert " "supplied tree '%s' (internal AST programming error).", status, fwdexp ); /* If inverted succesfully (which it should be since astUnitMapper should have checked this)... */ } else { /* Format the inverted tree as an algebraic expression, and get its length, adding on extra characters for the variable name ("input_units") and equals sign. */ invexp = MakeExp( inv, 1, 1, status ); linv = strlen( invexp ); linv += 12; /* Allocate memory for the transformation functions, plus an extra character for the trailing null. */ fwdfun = astMalloc( lfwd + 1 ); invfun = astMalloc( linv + 1 ); if( invfun ) { memcpy( fwdfun, "output_units=", 14 ); memcpy( invfun, "input_units=", 13 ); /* Append the expressions following the equals signs. */ strcpy( fwdfun + 13, fwdexp ); strcpy( invfun + 12, invexp ); /* Create the MathMap. */ result = (AstMapping *) astMathMap( 1, 1, 1, (const char **) &fwdfun, 1, (const char **) &invfun, "SimpFI=1,SimpIF=1", status ); } /* Free resources. */ inv = FreeTree( inv, status ); fwdfun = astFree( fwdfun ); invfun = astFree( invfun ); invexp = astFree( (void *) invexp ); } fwdexp = astFree( (void *) fwdexp ); } /* Free any result if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the answer. */ return result; } static UnitNode *MakeLabelTree( const char *lab, int nc, int *status ){ /* * Name: * MakeLabelTree * Purpose: * Convert an axis label into a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *MakeLabelTree( const char *lab, int nc, int *status ) * Class Membership: * Unit member function. * Description: * This function converts an axis label into a tree of UnitNodes. * It is assumed the supplied label represents some "basic" label * modified by the application of one or more single function arguments * and/or exponentiation operators. The (single) OP_LDVAR node in the * returned tree refers to the basic label (it is stored as the "name" * component of UnitNode structure). * Parameters: * lab * The label expression. * nc * The number of characters from "lab" to use. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which forms the head of a tree of UnitNodes * representing the supplied label expression. * Notes: * - A NULL value is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ Oper op; UnitNode *result; char buff[ 10 ]; const char *c; const char *exp; int depth; int i; int oplen; int n; double con; /* Initialise */ result = NULL; oplen = 0; /* Check the global error status, and that we have a string. */ if ( !astOK || !lab || !nc ) return result; /* Get a pointer to the first non-blank character, and store the number of characters to examine (this excludes any trailing white space). */ exp = lab; while( isspace( *exp ) ) exp++; c = lab + nc - 1; while( c >= exp && isspace( *c ) ) c--; nc = c - exp + 1; /* Scan through the supplied string looking for the first pow operator at zero depth of nesting within parentheses. */ depth = 0; c = exp; i = 0; op = OP_NULL; while( i < nc && *c ){ /* If this character is an opening parenthesis, increment the depth of nesting. */ if( *c == '(' ) { depth++; /* If this character is an closing parenthesis, decrement the depth of nesting. Report an error if it ever goes negative. */ } else if( *c == ')' ) { depth--; if( depth < 0 && astOK ) { astError( AST__BADUN, "Missing opening parenthesis." , status); break; } /* Ignore all other characters unless they are at zero depth of nesting. Also ignore spaces. */ } else if( depth == 0 && !isspace( *c ) ) { /* Compare the next part of the string with each of the "pow" operators. */ if( !strncmp( c, "**", 2 ) ) { op = OP_POW; oplen = 2; } else if( *c == '^' ) { op = OP_POW; oplen = 1; } /* If an operator was found, break out of the loop. */ if( op != OP_NULL ) break; } /* Pass on to check the next character. */ i++; c++; } /* If a "pow" operator was found, the strings on either side of it should be valid unit expressions, in which case we use this routine recursively to create corresponding trees of UnitNodes. */ if( op != OP_NULL ) { /* Create a UnitNode for the operator. */ result = NewNode( NULL, op, status ); if( astOK ) { /* Create a tree of unit nodes from the string which precedes the binary operator. Report an error if it cannot be done. */ result->arg[ 0 ] = MakeLabelTree( exp, i, status ); if( !result->arg[ 0 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand before '%s'.", status, buff ); } /* Create a tree of unit nodes from the string which follows the binary operator. Report an error if it cannot be done. */ result->arg[ 1 ] = MakeLabelTree( c + oplen, nc - i - oplen, status ); if( !result->arg[ 1 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand after '%s'.", status, buff ); } } /* If no binary operator was found at depth zero, see if the supplied string starts with a function name (the only legal place for a function name given that the string has no binary operators at depth zero). */ } else { if( !strncmp( exp, "sqrt(", 5 ) || !strncmp( exp, "SQRT(", 5 ) ) { op = OP_SQRT; oplen = 4; } else if( !strncmp( exp, "exp(", 4 ) || !strncmp( exp, "EXP(", 4 ) ) { op = OP_EXP; oplen = 3; } else if( !strncmp( exp, "ln(", 3 ) || !strncmp( exp, "LN(", 3 ) ) { op = OP_LN; oplen = 2; } else if( !strncmp( exp, "log(", 4 ) || !strncmp( exp, "LOG(", 4 ) ) { op = OP_LOG; oplen = 3; } /* If a function was found, the string following the function name (including the opening parenthesis) should form a legal units expresssion (all the supported functions take a single argument and so we do not need to worry about comma-separated lists of function arguments). Use this routine recursively to create a tree of UnitNodes from the string which forms the function argument. */ if( op != OP_NULL ) { /* Create a UnitNode for the function. */ result = NewNode( NULL, op, status ); if( astOK ) { /* Create a tree of unit nodes from the string which follows the function name. Report an error if it cannot be done. */ result->arg[ 0 ] = MakeLabelTree( exp + oplen, nc - oplen, status ); if( !result->arg[ 0 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing argument for '%s'.", status, buff ); } } /* Arrive here if the supplied string does not contain a POW operator or function at depth zero. Check to see if the whole string is contained within parentheses, In which we interpret the contents of the parentheses as a units expression. It is safe simply to check the first and last characters (a string like "(fred)(Harry)" is not a legal possibility since there should be an operator in the middle).*/ } else if( nc > 0 && ( exp[ 0 ] == '(' && exp[ nc - 1 ] == ')' ) ) { result = MakeLabelTree( exp + 1, nc - 2, status ); /* Does the string begin with a numerical constant? */ } else if( ConStart( exp, &con, &n, status ) == 1 ) { /* If the entire string was a numerical constant, represent it by a LDCON node. */ if( n == nc ) { result = NewNode( NULL, OP_LDCON, status ); if( astOK ) result->con = con; /* If there was anything following the numerical constant, report an error. */ } else if( astOK ){ astError( AST__BADUN, "Missing operator after " "numerical string '%.*s'.", status, n, exp ); } /* The only legal possibility left is that the string represents the basic label. Create an OP_LDVAR node for it and store the basic label as the node name, omitting any enclosing white space. */ } else { result = NewNode( NULL, OP_LDVAR, status ); if( astOK ) { result->name = astStore( NULL, exp, nc + 1 ); if( astOK ) ( (char *) result->name)[ nc ] = 0; } } } /* Free any returned tree if an error has occurred. */ if( !astOK ) result = FreeTree( result, status ); /* Return the result. */ return result; } static UnitNode *MakeTree( const char *exp, int nc, int lock, int *status ){ /* * Name: * MakeTree * Purpose: * Convert an algebraic units expression into a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *MakeTree( const char *exp, int nc, int lock, int *status ) * Class Membership: * Unit member function. * Description: * This function converts an algebraic units expression into a tree of * UnitNodes. It is a service routine for CreateTree. The roots of the * returned tree (i.e. the LDVAR nodes) refer to the unit symbols * contained within the supplied expression (i.e. definitions of these * units are not grafted onto the tree in place of the original nodes, * as is done by CreateTree). * Parameters: * exp * The units expression. This should not include any leading or * trailing spaces. * nc * The number of characters from "exp" to use. * lock * Use a mutex to guard access to the KnownUnits list? * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a UnitNode which forms the head of a tree of UnitNodes * representing the supplied unit expression. * Notes: * - A NULL value is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ KnownUnit *munit; KnownUnit *unit; Multiplier *mmult; Multiplier *mult; Oper op; UnitNode *result; char buff[ 10 ]; char d; const char *c; double con; int depth; int i; int l; int maxlen; int n; int oplen; int plural; /* Initialise */ result = NULL; /* Check the global error status, and that we have a string. */ if ( !astOK || !exp || nc <= 0 ) return result; /* Scan through the supplied string from the end to the start looking for the last multiplication or division operator at zero depth of nesting within parentheses. We go backwards through the string in order to give the correct priority to multiple division operators (i.e. "a/b/c" needs to be interpreted as "(a/b)/c", not "a/(b/c)"). */ op = OP_NULL; oplen = 1; depth = 0; c = exp + nc - 1; i = nc - 1; while( i >= 0 ){ /* If this character is an opening parenthesis, decrement the depth of nesting. Report an error if it ever goes negative. */ if( *c == '(' ) { depth--; if( depth < 0 && astOK ) { astError( AST__BADUN, "Missing closing parenthesis." , status); break; } /* An opening parenthesis at level zero must always be either the first character in the string, or be preceded by the name of a function, or be preceded by an operator. If none of these are true, assume there is an implicit multiplication operator before the parenthesis. */ if( depth == 0 && i > 0 ) { d = *( c - 1 ); if( d != '*' && d != '/' && d != '^' && d != '.' && d != ' ' && !EndsWith( c, i + 1, "sqrt(", status ) && !EndsWith( c, i + 1, "exp(", status ) && !EndsWith( c, i + 1, "ln(", status ) && !EndsWith( c, i + 1, "log(", status ) ) { op = OP_MULT; oplen = 0; break; } } /* If this character is an closing parenthesis, increment the depth of nesting. */ } else if( *c == ')' ) { depth++; /* A closing parenthesis at level zero must always be either the last character in the string, or be followed by an operator. If neither of these are true, assume there is an implicit multiplication operator. */ if( depth == 1 && i < nc - 1 ) { d = *(c+1); if( d != '*' && d != '/' && d != '^' && d != '.' && d != ' ') { op = OP_MULT; oplen = 0; /* Correct "i" so that it gives the length of the left hand operand of the implicit MULT operator, correct "c" so that it points to the first character in the right hand operand, and leave the loop. */ i++; c++; break; } } /* Ignore all other characters unless they are at zero depth of nesting. */ } else if( depth == 0 ) { /* Compare the next part of the string with each of the multiplication and division operators. */ if( *c == '/' ) { op = OP_DIV; } else if( *c == ' ' ) { op = OP_MULT; /* An asterisk is only treated as a multiplication symbol if it does not occur before or after another asterisk. */ } else if( *c == '*' ) { if( c == exp ) { if( *(c+1) != '*' ) op = OP_MULT; } else if( i == nc - 1 ) { if( *(c-1) != '*' ) op = OP_MULT; } else { if( *(c+1) != '*' && *(c-1) != '*' ) op = OP_MULT; } /* A dot is only treated as a multiplication symbol if it does not occur between two digits. */ } else if( *c == '.' ) { if( ( c == exp || !isdigit( *(c-1) ) ) && ( i == nc - 1 || !isdigit( *(c+1) ) ) ) { op = OP_MULT; } } } /* If an operator was found, break out of the loop. */ if( op != OP_NULL ) break; /* Pass on to check the next character. */ i--; c--; } /* If a multiplication or division operator was found, the strings on either side of it should be valid unit expressions, in which case we use this routine recursively to create corresponding trees of UnitNodes. */ if( op != OP_NULL ) { /* Create a UnitNode for the binary operator. */ result = NewNode( NULL, op, status ); if( astOK ) { /* Create a tree of unit nodes from the string which precedes the binary operator. Report an error if it cannot be done. */ result->arg[ 0 ] = MakeTree( exp, i, lock, status ); if( !result->arg[ 0 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand before '%s'.", status, buff ); } /* Create a tree of unit nodes from the string which follows the binary operator. Report an error if it cannot be done. */ result->arg[ 1 ] = MakeTree( c + oplen, nc - i - oplen, lock, status ); if( !result->arg[ 1 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand after '%s'.", status, buff ); } } /* If no multiplication or division operator was found at depth zero, check that the final depth of nesting was zero. Report an error if not. */ } else if( depth > 0 && astOK ) { astError( AST__BADUN, "Missing opening parenthesis." , status); /* Otherwise check for a "Pow" operator at depth zero. */ } else { /* Scan through the supplied string looking for the first pow operator at zero depth of nesting within parentheses. */ depth = 0; c = exp; i = 0; while( i < nc && *c ){ /* If this character is an opening parenthesis, increment the depth of nesting. */ if( *c == '(' ) { depth++; /* If this character is an closing parenthesis, decrement the depth of nesting. Report an error if it ever goes negative. */ } else if( *c == ')' ) { depth--; if( depth < 0 && astOK ) { astError( AST__BADUN, "Missing opening parenthesis." , status); break; } /* Ignore all other characters unless they are at zero depth of nesting. */ } else if( depth == 0 ) { /* Compare the next part of the string with each of the "pow" operators. */ if( !strncmp( c, "**", 2 ) ) { op = OP_POW; oplen = 2; } else if( *c == '^' ) { op = OP_POW; oplen = 1; } /* If an operator was found, break out of the loop. */ if( op != OP_NULL ) break; } /* Pass on to check the next character. */ i++; c++; } /* If a "pow" operator was found, the strings on either side of it should be valid unit expressions, in which case we use this routine recursively to create corresponding trees of UnitNodes. */ if( op != OP_NULL ) { /* Create a UnitNode for the operator. */ result = NewNode( NULL, op, status ); if( astOK ) { /* Create a tree of unit nodes from the string which precedes the binary operator. Report an error if it cannot be done. */ result->arg[ 0 ] = MakeTree( exp, i, lock, status ); if( !result->arg[ 0 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand before '%s'.", status, buff ); } /* Create a tree of unit nodes from the string which follows the binary operator. Report an error if it cannot be done. */ result->arg[ 1 ] = MakeTree( c + oplen, nc - i - oplen, lock, status ); if( !result->arg[ 1 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing operand after '%s'.", status, buff ); } } /* If no binary operator was found at depth zero, see if the supplied string starts with a function name (the only legal place for a function name given that the string has no binary operators at depth zero). */ } else { if( !strncmp( exp, "sqrt(", 5 ) || !strncmp( exp, "SQRT(", 5 ) ) { op = OP_SQRT; oplen = 4; } else if( !strncmp( exp, "exp(", 4 ) || !strncmp( exp, "EXP(", 4 ) ) { op = OP_EXP; oplen = 3; } else if( !strncmp( exp, "ln(", 3 ) || !strncmp( exp, "LN(", 3 ) ) { op = OP_LN; oplen = 2; } else if( !strncmp( exp, "log(", 4 ) || !strncmp( exp, "LOG(", 4 ) ) { op = OP_LOG; oplen = 3; } /* If a function was found, the string following the function name (including the opening parenthesis) should form a legal units expresssion (all the supported functions take a single argument and so we do not need to worry about comma-separated lists of function arguments). Use this routine recursively to create a tree of UnitNodes from the string which forms the function argument. */ if( op != OP_NULL ) { /* Create a UnitNode for the function. */ result = NewNode( NULL, op, status ); if( astOK ) { /* Create a tree of unit nodes from the string which follows the function name. Report an error if it cannot be done. */ result->arg[ 0 ] = MakeTree( exp + oplen, nc - oplen, lock, status ); if( !result->arg[ 0 ] && astOK ) { for( i = 0; i < oplen; i++ ) buff[ i ] = c[ i ]; buff[ oplen ] = 0; astError( AST__BADUN, "Missing argument for '%s'.", status, buff ); } } /* Arrive here if the supplied string does not contain a binary operator or function at depth zero. Check to see if the whole string is contained within parentheses, In which we interpret the contents of the parentheses as a units expression. It is safe simply to check the first and last characters (a string like "(fred)(Harry)" is not a legal possibility since there should be an operator in the middle).*/ } else if( exp[ 0 ] == '(' && exp[ nc - 1 ] == ')' ) { result = MakeTree( exp + 1, nc - 2, lock, status ); /* Does the string begin with a numerical constant? */ } else if( ConStart( exp, &con, &n, status ) == 1 ) { /* If the entire string was a numerical constant, represent it by a LDCON node. */ if( n == nc ) { result = NewNode( NULL, OP_LDCON, status ); if( astOK ) result->con = con; /* If there was anything following the numerical constant, report an error. */ } else if( astOK ){ astError( AST__BADUN, "Missing operator after " "numerical string '%.*s'.", status, n, exp ); } /* Does the string represent one of the named constants? If so represent it by a an appropriate operator. */ } else if( nc == 2 && ( !strncmp( exp, "pi", 2 ) || !strncmp( exp, "PI", 2 ) ) ) { result = NewNode( NULL, OP_LDPI, status ); } else if( nc == 1 && ( !strncmp( exp, "e", 1 ) || !strncmp( exp, "E", 1 ) ) ) { result = NewNode( NULL, OP_LDE, status ); /* The only legal possibility left is that the string represents the name of a basic unit, possibly prefixed by a multiplier character. */ } else { /* See if the string ends with the symbol for any of the known basic units. If it matches more than one basic unit, choose the longest. First ensure descriptions of the known units are available. */ mmult = NULL; plural = 0; while( 1 ) { unit = GetKnownUnits( lock, status ); maxlen = -1; munit = NULL; while( unit ) { if( SplitUnit( exp, nc, unit->sym, 1, &mult, &l, status ) ) { if( l > maxlen ) { maxlen = l; munit = unit; mmult = mult; } } unit = unit->next; } /* If the above did not produce a match, try matching the unit symbol case insensitive. */ if( !munit ) { unit = GetKnownUnits( lock, status ); while( unit ) { if( SplitUnit( exp, nc, unit->sym, 0, &mult, &l, status ) ) { if( l > maxlen ) { maxlen = l; munit = unit; mmult = mult; } } unit = unit->next; } } /* If the above did not produce a match, try matching the unit label case insensitive. */ if( !munit ) { unit = GetKnownUnits( lock, status ); while( unit ) { if( SplitUnit( exp, nc, unit->label, 0, &mult, &l, status ) ) { if( l > maxlen ) { maxlen = l; munit = unit; mmult = mult; } } unit = unit->next; } } /* If we still do not have a match, and if the string ends with "s", try removing the "s" (which could be a plural as in "Angstroms") and trying again. */ if( !munit && nc > 1 && !plural && ( exp[ nc - 1 ] == 's' || exp[ nc - 1 ] == 'S' ) ) { plural = 1; nc--; } else { break; } } if( plural ) nc++; /* If a known unit and multiplier combination was found, create an OP_LDVAR node from it. */ unit = munit; mult = mmult; if( unit ) { /* If the unit is an alias for another unit, it will have a non-NULL value for its "use" component.In this case, use the unit for which the identified unit is an alias. */ result = NewNode( NULL, OP_LDVAR, status ); if( astOK ) { result->unit = unit->use ? unit->use : unit; result->mult = mult; result->name = astStore( NULL, result->unit->sym, result->unit->symlen + 1 ); } /* If no known unit and multiplier combination was found, we assume the string represents a new user-defined basic unit, possibly preceded by a standard multiplier prefix. */ } else { /* Check the string to see if starts with a known multiplier prefix (but do not allow the multiplier to account for the entire string). */ mult = GetMultipliers( status ); c = exp; while( mult ) { n = nc - mult->symlen; if( n > 0 && !strncmp( exp, mult->sym, mult->symlen ) ) { c += mult->symlen; break; } mult = mult->next; } if( !mult ) n = nc; /* Check there are no illegal characters in the following string. */ for( i = 0; i < n && astOK; i++ ) { if( !isalpha( c[ i ] ) ) { astError( AST__BADUN, "Illegal character '%c' found.", status, c[ i ] ); break; } } /* If succesfull, create an OP_LDVAR node for th user-defined basic unit. */ if( astOK ) { result = NewNode( NULL, OP_LDVAR, status ); if( astOK ) { result->mult = mult; result->name = astStore( NULL, c, n + 1 ); if( astOK ) ( (char *) result->name)[ n ] = 0; } } } } } } /* Free any returned tree if an error has occurred. */ if( !astOK ) result = FreeTree( result, status ); /* Return the result. */ return result; } static void MakeUnitAlias( const char *sym, const char *alias, int *status ){ /* * Name: * MakeUnitAlias * Purpose: * Create a KnownUnit structure describing an alias for a known unit. * Type: * Private function. * Synopsis: * #include "unit.h" * void MakeUnitAlias( const char *sym, const char *alias, int *status ) * Class Membership: * Unit member function. * Description: * This function creates a KnownUnit structure decribing an alias for a * known unit, and adds it to the head of the linked list of known units * stored in a module variable. An alias is a KnownUnit which is * identical to an existing known but which has a different symbol. * Parameters: * sym * A pointer to the symbol string of an existing KnwonUnit. The string * should not include any multiplier prefix. * alias * A pointer to the symbol string to use as the alasi for the existing * KnownUnit. The string should not include any multiplier prefix. * status * Pointer to the inherited status variable. * Notes: * - The supplied symbol and label strings are not copied. The * supplied pointers are simply stored in the returned structure. * Therefore the strings to which the pointers point should not be * modified after this function returned (in fact this function is * always called with literal strings for these arguments). */ /* Local Variables: */ KnownUnit *unit; /* Check the global error status. */ if( !astOK ) return; /* Search the existing list of KnownUnits for the specified symbol. */ unit = known_units; while( unit ) { if( !strcmp( sym, unit->sym ) ) { /* Create a new KnownUnit for the alias. It will becomes the head of the known units chain. */ MakeKnownUnit( alias, unit->label, NULL, status ); /* Store a pointer to the KnownUnit which is to be used in place of the alias. */ known_units->use = unit; /* Leave the loop. */ break; } /* Move on to check the next existing KnownUnit. */ unit = unit->next; } /* Report an error if the supplied unit was not found. */ if( !unit ) { astError( AST__INTER, "MakeUnitAlias(Unit): Cannot find existing " "units \"%s\" to associate with the alias \"%s\" (AST " "internal programming error).", status, sym, alias ); } } static UnitNode *ModifyPrefix( UnitNode *old, int *status ) { /* * Name: * ModifyPrefix * Purpose: * Replace a MULT or DIV node with a LDVAR and suitable multiplier. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *ModifyPrefix( UnitNode *old, int *status ) * Class Membership: * Unit member function. * Description: * This function checks the supplied node. If it is a DIV or MULT node * in which one argument is an LDVAR and the other is a constant, then * its checks to see if the constant can be absorbed into the LDVAR by * changing the multiplier in the LDVAR node. If so, it returns a new * node which is an LDVAR with the modified multiplier. Otherwise it * returns NULL. * Parameters: * old * Pointer to an existing UnitNode to be checked. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new UnitNode. * Notes: * - A value of NULL will be returned if this function is invoked with * the global error status set, or if it should fail for any reason. */ /* Local Variables: */ Multiplier *mult; Multiplier *mmult; UnitNode *ldcon; UnitNode *ldvar; UnitNode *newtree; UnitNode *result; double con; double cmult; double r; double rmin; int recip; int changed; /* Initialise. */ result = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Indicate that we have not yet found any reason to return a changed node. */ changed = 0; /* Check the supplied node is a DIV or MULT node. */ if( old->opcode == OP_DIV || old->opcode == OP_MULT ) { /* Get a copy of the supplied tree which we can modify safely. */ newtree = CopyTree( old, status ); /* Identify the LDVAR argument (if any). */ if( newtree->arg[ 0 ]->opcode == OP_LDVAR ) { ldvar = newtree->arg[ 0 ]; } else if( newtree->arg[ 1 ]->opcode == OP_LDVAR ) { ldvar = newtree->arg[ 1 ]; } else { ldvar = NULL; } /* Identify the LDCON argument (if any). */ if( newtree->arg[ 0 ]->opcode == OP_LDCON ) { ldcon = newtree->arg[ 0 ]; } else if( newtree->arg[ 1 ]->opcode == OP_LDCON ) { ldcon = newtree->arg[ 1 ]; } else { ldcon = NULL; } /* If either was not found, return NULL. */ if( !ldvar || !ldcon ) { newtree = FreeTree( newtree, status ); /* Otherwise, extract the multiplier constant. If there is no multiplier, the constant is 1.0. */ } else { cmult = ldvar->mult ? ldvar->mult->scale: 1.0; /* Extract the constant. */ con = ldcon->con; /* Combine the multiplier and the constant. The resulting constant is a factor which is used to multiply the LDVAR quantity. If the original node is a DIV node in which the LDVAR is in the denominator, then flag that we need to reciprocate the new MULT node which represents "constant*LDVAR" before returning. */ if( newtree->opcode == OP_MULT ) { con = con*cmult; recip = 0; } else { con = cmult/con; recip = ( ldvar == newtree->arg[ 1 ] ); } /* Find the closest known multiplier to the new constant. */ rmin = ( con > 1 ) ? con : 1.0/con; mmult = NULL; mult = GetMultipliers( status ); while( mult ) { r = ( con > mult->scale) ? con/mult->scale : mult->scale/con; if( r < rmin ) { mmult = mult; rmin = r; } mult = mult->next; } /* Modify the constant to take account of the new multiplier chosen above. "mmult" will be NULL if the best multiplier is unity. */ if( mmult ) con = con/mmult->scale; /* If they have changed, associate the chosen multiplier with the LDVAR node, and the constant with the LDCON node. */ if( ldvar->mult != mmult ) { ldvar->mult = mmult; changed = 1; } if( ldcon->con != con ) { ldcon->con = con; changed = 1; } /* Unless the node is proportional to the reciprocal of the variable, the new node should be a MULT node (it may originally have been a DIV). */ if( !recip ) { if( newtree->opcode != OP_MULT ){ newtree->opcode = OP_MULT; changed = 1; } /* If the constant is 1.0 we can just return the LDVAR node by itself. */ if( fabs( con - 1.0 ) < 1.0E-6 ) { result = CopyTree( ldvar, status ); newtree = FreeTree( newtree, status ); changed = 1; /* Otherwise return the modified tree containing both LDVAR and LDCON nodes. */ } else { result = newtree; } /* If the node is proportional to the reciprocal of the variable, the new node will already be a DIV node and will have an LDCON as the first argument (numerator) and an LDVAR as the second argument (denominator). */ } else { /* The first argument (the numerator) should be the reciprocal of the constant found above. */ ldcon->con = 1.0/ldcon->con; if( !astEQUAL( ldcon->con, old->arg[0]->con ) ) changed = 1; /* Return the modified tree containing both LDVAR and LDCON nodes. */ result = newtree; } } } /* If the new and old trees are equivalent, then we do not need to return it. */ if( !changed && result ) result = FreeTree( result, status ); /* Return the answer. */ return result; } static UnitNode *NewNode( UnitNode *old, Oper code, int *status ) { /* * Name: * NewNode * Purpose: * Create and initialise a new UnitNode. * Type: * Private function. * Synopsis: * #include "unit.h" * UnitNode *NewNode( UnitNode *old, Oper code, int *status ) * Class Membership: * Unit member function. * Description: * This function creates and initialises a new UnitNode, or * re-initialises an existing UnitNode to use a different op code. * Parameters: * old * Pointer to an existing UnitNode to be modified, or NULL to create * a new UnitNode. * code * The op code for the new UnitNode. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new UnitNode. * Notes: * - A value of NULL will be returned if this function is invoked with * the global error status set, or if it should fail for any reason. */ /* Local Variables: */ UnitNode **args; UnitNode *result; int i; /* Initialise. */ result = NULL; args = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* If an existig UnitNode was supplied, free any memory used to hold pointers to its arguments. */ if( old ) { old->arg = astFree( old->arg ); result = old; /* Otherwise, allocate memory for a new structure. */ } else { result = astMalloc( sizeof( UnitNode ) ); } /* Check the pointer can be used safely. */ if( astOK ) { /* Initialise the members of the UnitNode structure. */ result->opcode = code; result->arg = NULL; result->con = AST__BAD; result->name = NULL; result->unit = NULL; result->mult = NULL; result->narg = 0; switch( code ){ case OP_LDPI: result->con = PI; break; case OP_LDE: result->con = E; break; case OP_LOG: case OP_LN: case OP_EXP: case OP_SQRT: result->narg = 1; break; case OP_POW: case OP_DIV: case OP_MULT: result->narg = 2; break; default: ; } /* Allocate memory for the UnitNode pointers which will locate the nodes forming the arguments to the new node. */ args = astMalloc( (result->narg)*sizeof( UnitNode * ) ); if( astOK ) { result->arg = args; /* Initialise the argument pointers to NULL. */ for( i = 0; i < result->narg; i++ ) args[ i ] = NULL; } } /* Free any result if an error occurred. */ if( !astOK ) { args = astFree( args ); result = astFree( result ); } /* Return the answer. */ return result; } static void RemakeTree( UnitNode **node, int *status ) { /* * Name: * RemakeTree * Purpose: * Replace derived units within a tree of UnitNodes by basic units. * Type: * Private function. * Synopsis: * #include "unit.h" * void RemakeTree( UnitNode **node, int *status ) * Class Membership: * Unit member function. * Description: * This function searches for LDVAR nodes (i.e. references to unit * symbols) within the given tree, and replaces each such node which * refers to known derived unit with a sub-tree of nodes which * define the derived unit in terms of known basic units. * Parameters: * node * The address of a pointer to the UnitNode at the head of the tree * which is to be simplified. On exit the supplied tree is freed and a * pointer to a new tree is placed at the given address. * status * Pointer to the inherited status variable. */ /* Local Variables: */ KnownUnit *unit; int i; UnitNode *newnode; /* Check inherited status. */ if( !astOK ) return; /* Initially, we have no replacement node */ newnode = NULL; /* If this is an LDVAR node... */ if( (*node)->opcode == OP_LDVAR ) { /* If the LDVAR node has a multiplier associated with it, we need to introduce a OP_MULT node to perform the scaling. */ if( (*node)->mult ) { newnode = NewNode( NULL, OP_MULT, status ); if( astOK ) { newnode->arg[0] = NewNode( NULL, OP_LDCON, status ); if( astOK ) { newnode->arg[0]->con = 1.0/(*node)->mult->scale; /* See if the node refers to a known unit. If not, or if the known unit is a basic unit (i.e. not a derived unit) use the supplied node for the second argument of the OP_MULT node (without the multiplier). Otherwise, use a copy of the tree which defines the derived unit. */ unit = (*node)->unit; if( unit && unit->head ) { newnode->arg[1] = CopyTree( unit->head, status ); } else { newnode->arg[1] = CopyTree( *node, status ); if( astOK ) newnode->arg[1]->mult = NULL; } } } /* If no multiplier is supplied, the replacement node is simply the tree which defines the unscaled unit (if known), or the original node (if unknown). */ } else { unit = (*node)->unit; if( unit && unit->head ) newnode = CopyTree( unit->head, status ); } /* If this is not an LDVAR Node, remake the sub-trees which form the arguments of this node. */ } else { for( i = 0; i < (*node)->narg; i++ ) { RemakeTree( &((*node)->arg[ i ]), status ); } } /* If an error has occurred, free any new node. */ if( !astOK ) newnode = FreeTree( newnode, status ); /* If we have a replacement node, free the supplied tree and return a pointer to the new tree. */ if( newnode ) { FreeTree( *node, status ); *node = newnode; } } static int ReplaceNode( UnitNode *target, UnitNode *old, UnitNode *new, int *status ) { /* * Name: * ReplaceNode * Purpose: * Replace a node within a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * int ReplaceNode( UnitNode *target, UnitNode *old, UnitNode *new, int *status ) * Class Membership: * Unit member function. * Description: * This function replaces a specified node within a tree of UnitNodes * with another given node. The original node is freed if found. * Parameters: * target * A pointer to the UnitNode at the head of the tree containing the * node to be replaced. * old * A pointer to the UnitNode to be replaced. * new * A pointer to the UnitNode to replace "old". * status * Pointer to the inherited status variable. * Return Value: * Non-zero if the "old" node was found and replaced (in which case * the "old" node will have been freed). * Notes: * - It is assumed that the "old" node occurs at most once within the * target tree. * - The node at the head of the target tree is not compared with the * "old" node. It is assumed the called will already have done this. * - A value of zero is returned if an error has already occurred, or * if this function fails for any reason. */ /* Local Variables: */ int i; int result; /* Initialise */ result = 0; /* Check inherited status. */ if( !astOK ) return result; /* Loop round the arguments of the node at the head of the target tree. Break out of the loop as soone as the old node is found. */ for( i = 0; i < target->narg; i++ ) { /* If this argument is the node to be replaced, free the old one and store the new one, and then leave the loop. */ if( target->arg[ i ] == old ) { FreeTree( old, status ); target->arg[ i ] = new; result = 1; break; /* Otherwise use this function recursively to search for the old node within the current argument. */ } else { if( ReplaceNode( target->arg[ i ], old, new, status ) ) break; } } /* If an error has occurred, return zero. */ if( !astOK ) result = 0; /* Return the answer. */ return result; } static int SimplifyTree( UnitNode **node, int std, int *status ) { /* * Name: * SimplifyTree * Purpose: * Simplify a tree of UnitNodes. * Type: * Private function. * Synopsis: * #include "unit.h" * int SimplifyTree( UnitNode **node, int std, int *status ) * Class Membership: * Unit member function. * Description: * This function simplifies a tree of UnitNodes. It is assumed that * all the OP_LDVAR nodes in the tree refer to the same basic unit. * A primary purpose of this function is to standardise the tree so * that trees which implement equivalent transformations but which * have different structures can be compared (for instance, so that * "2*x" and "x*2" are treated as equal trees). If "std" is non-zero, * reducing the complexity of the tree is only of secondary importance. * This explains why some "simplifications" actually produced trees which * are more complicated. * Parameters: * node * The address of a pointer to the UnitNode at the head of the tree * which is to be simplified. On exit the supplied tree is freed and a * pointer to a new tree is placed at the given address. * std * If non-zero, perform standardisations. Otherwise only perform * genuine simplifications. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if some change was made to the tree. */ /* Local Variables: */ int i; UnitNode *newnode; UnitNode *node1; UnitNode *node2; Oper op; UnitNode **factors; double *powers; int nfactor; double coeff; int result; /* Initialise */ result = 0; /* Check inherited status. */ if( !astOK ) return result; /* Initiallially, we have no replacement node. */ newnode = NULL; /* First replace any complex constant expressions any corresponding OP_LDCON nodes. */ FixConstants( node, 0, status ); /* Simplify the sub-trees corresponding to the arguments of the node at the head of the supplied tree. */ for( i = 0; i < (*node)->narg; i++ ) { if( SimplifyTree( &( (*node)->arg[ i ] ), std, status ) ) result = 1; } /* Now do specific simplifications appropriate to the nature of the node at the head of the tree. */ op = (*node)->opcode; /* Natural log */ /* =========== */ /* We standardise argument powers into coefficients of the LN value. */ if( op == OP_LN ) { /* If the argument is a OP_EXP node, they cancel out. Return a copy of the argument of OP_EXP node. */ if( (*node)->arg[ 0 ]->opcode == OP_EXP ) { newnode = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); /* If the argument is an OP_POW node, rearrange the nodes to represent k*ln(x) instead of ln(x**k) (note pow nodes always have a constant exponent - this is checked in InvertConstants). SQRT arguments will not occur because they will have been changed into POW nodes when the arguments of the supplied head node were simplified above. */ } else if( std && (*node)->arg[ 0 ]->opcode == OP_POW ) { newnode = NewNode( NULL, OP_MULT, status ); node1 = CopyTree( (*node)->arg[ 0 ]->arg[ 1 ], status ); node2 = NewNode( NULL, OP_LN, status ); if( astOK ) { node2->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = node2; } } /* Common log */ /* ========== */ /* We standardise natural logs into common logs. */ } else if( op == OP_LOG ) { if( std ) { newnode = NewNode( NULL, OP_DIV, status ); node1 = NewNode( NULL, OP_LN, status ); node2 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node1->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ], status ); node2->con = log( 10.0 ); newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = node2; } } /* Exponential */ /* =========== */ /* We prefer to minimise the number of EXP nodes, so, for instance, we do not change "exp(x*y)" to "exp(x)+exp(y)" (and the code for ADD nodes does the inverse conversion). */ } else if( op == OP_EXP ) { /* If the argument is an OP_LN node, they cancel out. Return a copy of the argument of the OP_LN node. Common log arguments will not occur because they will have been changed into natural logs when the arguments of the supplied head node were simplified above. */ if( (*node)->arg[ 0 ]->opcode == OP_LN ) { newnode = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); } /* Square root */ /* =========== */ /* We standardise sqrt nodes into pow nodes. */ } else if( op == OP_SQRT ) { if( std ) { newnode = NewNode( NULL, OP_POW, status ); node1 = CopyTree( (*node)->arg[ 0 ], status ); node2 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node2->con = 0.5; newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = node2; } } /* Exponentiation */ /* ============== */ /* We want to simplfy factors. So, for instance, (x*y)**k is converted to (x**k)*(y**k). */ } else if( op == OP_POW ) { /* If the first argument is an OP_EXP node, then change "(e**x)**k" into "e**(k*x)" */ if( (*node)->arg[ 0 ]->opcode == OP_EXP ) { newnode = NewNode( NULL, OP_EXP, status ); node1 = NewNode( NULL, OP_MULT, status ); if( astOK ) { node1->arg[ 0 ] = CopyTree( (*node)->arg[ 1 ], status ); node1->arg[ 1 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); newnode->arg[ 0 ] = node1; } /* "x**0" can be replaced by 1.0 */ } else if( (*node)->arg[ 1 ]->con == 0.0 ) { newnode = NewNode( NULL, OP_LDCON, status ); if( astOK ) newnode->con = 1.0; /* "x**1" can be replaced by x */ } else if( astEQUAL( (*node)->arg[ 1 ]->con, 1.0 ) ) { newnode = CopyTree( (*node)->arg[ 0 ], status ); /* If the first argument is an OP_POW node, then change "(x**k1)**k2" into "x**(k1*k2)" */ } else if( (*node)->arg[ 0 ]->opcode == OP_POW ) { newnode = NewNode( NULL, OP_POW, status ); node1 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node1->con = ( (*node)->arg[ 0 ]->arg[ 1 ]->con )* ( (*node)->arg[ 1 ]->con ); newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); newnode->arg[ 1 ] = node1; } /* If the first argument is an OP_MULT node, then change "(x*y)**k" into "(x**(k))*(y**(k))" */ } else if( std && (*node)->arg[ 0 ]->opcode == OP_MULT ) { newnode = NewNode( NULL, OP_MULT, status ); node1 = NewNode( NULL, OP_POW, status ); if( astOK ) { node1->arg[ 1 ] = CopyTree( (*node)->arg[ 1 ], status ); node2 = CopyTree( node1, status ); node1->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 0 ], status ); node2->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ]->arg[ 1 ], status ); newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = node2; } } /* Division. */ /* ========= */ /* We standardise divisions into corresponding multiplications. */ } else if( op == OP_DIV ) { /* Division by 1 is removed. */ if( astEQUAL( (*node)->arg[ 1 ]->con, 1.0 ) ){ newnode = CopyTree( (*node)->arg[ 0 ], status ); /* Division by any other constant (except zero) is turned into a multiplication by the reciprocal constant. */ } else if( (*node)->arg[ 1 ]->con != AST__BAD ) { if( (*node)->arg[ 1 ]->con != 0.0 ) { newnode = NewNode( NULL, OP_MULT, status ); node1 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node1->con = 1.0/(*node)->arg[ 1 ]->con; newnode->arg[ 0 ] = node1; newnode->arg[ 1 ] = CopyTree( (*node)->arg[ 0 ], status ); } } else { astError( AST__BADUN, "Simplifying a units expression" "requires a division by zero." , status); } /* Other divisions "x/y" are turned into "x*(y**(-1))" */ } else if( std ) { newnode = NewNode( NULL, OP_MULT, status ); node1 = NewNode( NULL, OP_POW, status ); node2 = NewNode( NULL, OP_LDCON, status ); if( astOK ) { node2->con = -1.0; node1->arg[ 0 ] = CopyTree( (*node)->arg[ 1 ], status ); node1->arg[ 1 ] = node2; newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 0 ], status ); newnode->arg[ 1 ] = node1; } } /* Multiplication */ /* ============== */ } else if( op == OP_MULT ) { /* If the right hand argument is constant, swap the arguments. */ if( (*node)->arg[ 1 ]->con != AST__BAD ) { newnode = NewNode( NULL, OP_MULT, status ); if( astOK ) { newnode->arg[ 0 ] = CopyTree( (*node)->arg[ 1 ], status ); newnode->arg[ 1 ] = CopyTree( (*node)->arg[ 0 ], status ); } /* Multiplication by zero produces a constant zero. */ } else if( (*node)->arg[ 0 ]->con == 0.0 ){ newnode = NewNode( NULL, OP_LDCON, status ); if( astOK ) newnode->con = 0.0; /* Multiplication by 1 is removed. */ } else if( astEQUAL( (*node)->arg[ 0 ]->con, 1.0 ) ){ newnode = CopyTree( (*node)->arg[ 1 ], status ); /* For other MULT nodes, analyse the tree to find a list of all its factors with an associated power for each one, and an overall constant coefficient. */ } else if( std ) { FindFactors( (*node), &factors, &powers, &nfactor, &coeff, status ); /* Produce a new tree from these factors. The factors are standardised by ordering them alphabetically (after conversion to a character string). */ newnode = CombineFactors( factors, powers, nfactor, coeff, status ); /* Free resources */ factors = astFree( factors ); powers = astFree( powers ); } } /* If we have produced a new node which is identical to the old node, free it. Otherwise, indicate we have made some changes. */ if( newnode ) { if( !CmpTree( newnode, *node, 1, status ) ) { newnode = FreeTree( newnode, status ); } else { result = 1; } } /* If an error has occurred, free any new node. */ if( !astOK ) newnode = FreeTree( newnode, status ); /* If we have a replacement node, free the supplied tree and return a pointer to the new tree. */ if( newnode ) { FreeTree( *node, status ); *node = newnode; } /* If the above produced some change, try re-simplifying the tree. */ if( result ) SimplifyTree( node, std, status ); /* Return the result. */ return result; } static int SplitUnit( const char *str, int ls, const char *u, int cs, Multiplier **mult, int *l, int *status ) { /* * Name: * SplitUnit * Purpose: * Split a given string into unit name and multiplier. * Type: * Private function. * Synopsis: * #include "unit.h" * int SplitUnit( const char *str, int ls, const char *u, int cs, * Multiplier **mult, int *l, int *status ) * Class Membership: * Unit member function. * Description: * Returns non-zer0 if the supplied string ends with the supplied unit * name or label, and any leading string is a known multiplier. * Parameters: * str * The string to test, typically containing a multiplier and a unit * symbol or label. * ls * Number of characters to use from "str" (not including trailing null) * u * Pointer to the unit label or symbol string to be searched for. * cs * If non-zero, the test for "u" is case insensitive. * mult * Address of a location at which to return the multiplier at the * start of the supplied string. NULL is returned if the supplied * string does not match the supplied unit, or if the string * includes no multiplier. * l * Address of an int in which to return the length of "u". * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if "str" ends with "u" and starts with a null string or a * known multiplier string. */ /* Local Variables: */ int ret; int lm; int lu; /* Initialise */ ret = 0; *mult = NULL; *l = 0; /* Check inherited status. */ if( !astOK ) return ret; /* Find the number of characters in the supplied unit label or symbol. The difference between lu and ls must be the length of the multiplier. */ lu = strlen( u ); lm = ls - lu; /* Make sure "str" is not shorter than "u" */ if( lm >= 0 ) { /* Compare the end of "str" against "u" */ if( cs ? !strncmp( str + lm, u, lu ) : !Ustrncmp( str + lm, u, lu, status ) ) { ret = 1; /* If "str" ends with "u", see if it starts with a known multiplier */ if( lm > 0 ) { ret = 0; *mult = GetMultipliers( status ); while( *mult ) { if( (*mult)->symlen == lm && !strncmp( str, (*mult)->sym, lm ) ) { ret = 1; break; } *mult = (*mult)->next; } /* If not, try again using case-insensitive matching. */ if( !ret ) { *mult = GetMultipliers( status ); while( *mult ) { if( (*mult)->symlen == lm && !Ustrncmp( str, (*mult)->sym, lm, status ) ) { ret = 1; break; } *mult = (*mult)->next; } } /* If not, try again using case-insensitive matching against the multiplier label. */ if( !ret ) { *mult = GetMultipliers( status ); while( *mult ) { if( (*mult)->lablen == lm && !Ustrncmp( str, (*mult)->label, lm, status ) ) { ret = 1; break; } *mult = (*mult)->next; } } } } } *l = lu; return ret; } double astUnitAnalyser_( const char *in, double powers[9], int *status ){ /* *+ * Name: * astUnitAnalyser * Purpose: * Perform a dimensional analysis of a unti string. * Type: * Protected function. * Synopsis: * #include "unit.h" * double astUnitAnalyser_( const char *in, double powers[9] ) * Class Membership: * Unit member function. * Description: * This function parses the supplied units string if possible, and * returns a set of pwoers and a scaling factor which represent the * units string. * Parameters: * in * A string representation of the units, for instance "km/h". * powers * An array in which are returned the powers for each of the following * basic units (in the order shown): kilogramme, metre, second, radian, * Kelvin, count, adu, photon, magnitude, pixel. If the supplied unit * does not depend on a given basic unit a value of 0.0 will be returned * in the array. The returns values represent a system of units which is * a scaled form of the supplied units, expressed in the basic units of * m, kg, s, rad, K, count, adu, photon, mag and pixel. For instance, a * returned array of [1,0,-2,0,0,0,0,0,0] would represent "m/s**2". * Returned Value: * A scaling factor for the supplied units. The is the value, in the * units represented by the returned powers, which corresponds to a * value of 1.0 in the supplied units. * Notes: * - An error will be reported if the units string cannot be parsed * or refers to units or functions which cannot be analysed in this way. * - AST__BAD is returned if this function is invoked with the * global error status set or if it should fail for any reason. *- */ /* Local Variables: */ UnitNode *in_tree; double result; /* Initialise */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Parse the input units string, producing a tree of UnitNodes which represents the input units. A pointer to the UnitNode at the head of the tree is returned if succesfull. Report a context message if this fails. */ in_tree = CreateTree( in, 1, 1, status ); if( in_tree ) { /* Analyse the tree */ if( !DimAnal( in_tree, powers, &result, status ) && astOK ) { result = AST__BAD; astError( AST__BADUN, "astUnitAnalyser: Error analysing input " "units string '%s' (it may contain unsupported " "functions or dimensionless units).", status, in ); } /* Free the tree. */ in_tree = FreeTree( in_tree, status ); } else if( astOK ) { astError( AST__BADUN, "astUnitAnalyser: Error parsing input " "units string '%s'.", status, in ); } /* Return the result */ return result; } const char *astUnitLabel_( const char *sym, int *status ){ /* *+ * Name: * astUnitLabel * Purpose: * Return a string label for a given unit symbol. * Type: * Protected function. * Synopsis: * #include "unit.h" * const char *astUnitLabel( const char *sym ) * Class Membership: * Unit member function. * Description: * This function returns a pointer to a constant string containing a * descriptive label for the unit specified by the given unit symbol. * Parameters: * sym * A string holing a known unit symbol. * Returned Value: * A pointer to constant string holding a descriptive label for the * supplied unit. A NULL pointer is returned (without error) if the * supplied unit is unknown. * Notes: * - A NULL pointer is returned if this function is invoked with the * global error status set or if it should fail for any reason. *- */ /* Local Variables: */ const char *result; KnownUnit *unit; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Ensure descriptions of the known units are available. */ unit = GetKnownUnits( 1, status ); /* Loop through the chain of known units looking for a unit with a symbol equal to the supplied string. If found, store a pointer to its label and break out of the loop. */ while( unit ) { if( !strcmp( sym, unit->sym ) ) { result = unit->label; break; } unit = unit->next; } /* Return the answer. */ return result; } AstMapping *astUnitMapper_( const char *in, const char *out, const char *in_lab, char **out_lab, int *status ){ /* *+ * Name: * astUnitMapper * Purpose: * Create a Mapping between two system of units. * Type: * Protected function. * Synopsis: * #include "unit.h" * AstMapping *astUnitMapper( const char *in, const char *out, * const char *in_lab, char **out_lab ) * Class Membership: * Unit member function. * Description: * This function creates a Mapping between two specified system of * units. It also modifes a supplied label (which is typically * the axis label associated with the input units) so that it includes * any functional change implied by the supplied "in" and "out" units. * Parameters: * in * A string representation of the input units, for instance "km/h". * See "Unit Representations:" below. * out * A string representation of the output units, for instance "m/s". * See "Unit Representations:" below. * in_lab * A label describing the quantity associated with the input units. * If the "in" string is the Units attribute of an Axis, then * "in_lab" should be the Label of the same Axis. May be supplied * NULL in which case "out_lab" is ignored. * out_lab * The address at which to return a pointer to a label describing the * quantity associated with the output units. For instance, if the * input and output units are "Hz" and "sqrt(Hz)", and the input * label is "Frequency", then the returned output label will be * "sqrt( Frequency )". The returned label is stored in dynamically * allocated memory which should be freed (using astFree) when no longer * needed. * Returned Value: * A pointer to a Mapping which can be used to transform values in the * "in" system of units into the "out" system of units. The Mapping * will have 1 input and 1 output. * Unit Representations: * The string supplied for "in" and "out" should represent a system of * units following the recommendations of the FITS WCS paper I * "Representation of World Coordinates in FITS" (Greisen & Calabretta). * Various commonly used variants are also allowed. * * To summarise, a string describing a system of units should be an * algebraic expression which combines one or more named units. The * following functions and operators may be used within these algebraic * expressions: * * - "*": multiplication. A period "." or space " " may also be used * to represent multiplication (a period is only interpreted as a * multiplication operator if it is not positioned between two digits, * and a space is only interpreted as a multiplication operator if it * occurs between two operands). * - "/": division. * - "**": exponentiation. The exponent (i.e. the operand following the * exponentiation operator) must be a constant. The symbol "^" is also * interpreted as an exponentiation operator. Exponentiation is also * implied by an integer following a unit name without any separator * (e.g. "cm2" is "cm^2"). * - log(): Common logarithm. * - ln(): Natural logarithm. * - sqrt(): Square root. * - exp(): Exponential. * * Function names are case insensitive. White space may be included * within an expression (note that white space between two operands * will be interpreted as a muiltiplication operator as described * above). Parentheses may be used to indicate the order in which * expressions are to be evaluated (normal mathematical precedence is * used otherwise). The following symbols may be used to represent * constants: * * - "pi" * - "e" * * These symbols are also case in-sensitive. * * The above operators and functions are used to combine together one * or more "unit symbols". The following base unit symbols are recognised: * * - "m": metre. * - "g": gram. * - "s": second. * - "rad": radian. * - "sr": steradian. * - "K": Kelvin. * - "mol": mole. * - "cd": candela. * * The following symbols for units derived fro the above basic units are * recognised: * * - "sec": second (1 s) * - "Hz": Hertz (1/s). * - "N": Newton (kg m/s**2). * - "J": Joule (N m). * - "W": Watt (J/s). * - "C": Coulomb (A s). * - "V": Volt (J/C). * - "Pa": Pascal (N/m**2). * - "Ohm": Ohm (V/A). * - "S": Siemens (A/V). * - "F": Farad (C/V). * - "Wb": Weber (V s). * - "T": Tesla (Wb/m**2). * - "H": Henry (Wb/A). * - "lm": lumen (cd sr). * - "lx": lux (lm/m**2). * - "deg": degree (pi/180 rad). * - "arcmin": arc-minute (1/60 deg). * - "arcsec": arc-second (1/3600 deg). * - "mas": milli-arcsecond (1/3600000 deg). * - "min": minute (60 s). * - "h": hour (3600 s). * - "d": day (86400 s). * - "yr": year (31557600 s). * - "a": year (31557600 s). * - "eV": electron-Volt (1.60217733E-19 J). * - "erg": erg (1.0E-7 J). * - "Ry": Rydberg (13.605692 eV). * - "solMass": solar mass (1.9891E30 kg). * - "u": unified atomic mass unit (1.6605387E-27 kg). * - "solLum": solar luminosity (3.8268E26 W). * - "Angstrom": Angstrom (1.0E-10 m). * - "Ang": Angstrom * - "A": Ampere * - "micron": micron (1.0E-6 m). * - "solRad": solar radius (6.9599E8 m). * - "AU": astronomical unit (1.49598E11 m). * - "lyr": light year (9.460730E15 m). * - "pc": parsec (3.0867E16 m). * - "count": count. * - "ct": count. * - "adu": analogue-to-digital converter unit. * - "photon": photon. * - "ph": photon. * - "Jy": Jansky (1.0E-26 W /m**2 /Hz). * - "Jan": Jansky * - "mag": magnitude. * - "G": Gauss (1.0E-4 T). * - "pixel": pixel. * - "pix": pixel. * - "barn": barn (1.0E-28 m**2). * - "D": Debye (1.0E-29/3 C.m). * * In addition, any other unknown unit symbol may be used (but of course * no mapping will be possible between unknown units). * * Unit symbols may be preceded with a numerical constant (for * instance "1000 m") or a standard multiplier symbol (for instance "km") * to represent some multiple of the unit. The following standard * multipliers are recognised: * * - "d": deci (1.0E-1) * - "c": centi (1.0E-2) * - "m": milli (1.0E-3) * - "u": micro (1.0E-6) * - "n": nano (1.0E-9) * - "p": pico (1.0E-12) * - "f": femto (1.0E-15) * - "a": atto (1.0E-18) * - "z": zepto (1.0E-21) * - "y": yocto (1.0E-24) * - "da": deca (1.0E1) * - "h": hecto (1.0E2) * - "k": kilo (1.0E3) * - "M": mega (1.0E6) * - "G": giga (1.0E9) * - "T": tera (1.0E12) * - "P": peta (1.0E15) * - "E": exa (1.0E18) * - "Z": zetta (1.0E21) * - "Y": yotta (1.0E24) * Notes: * - NULL values are returned without error if the supplied units are * incompatible (for instance, if the input and output units are "kg" * and "m" ). * - NULL values are returned if this function is invoked with the * global error status set or if it should fail for any reason. *- */ /* Local Variables: */ AstMapping *result; UnitNode **units; UnitNode *in_tree; UnitNode *intemp; UnitNode *inv; UnitNode *labtree; UnitNode *newtest; UnitNode *out_tree; UnitNode *outtemp; UnitNode *src; UnitNode *testtree; UnitNode *tmp; UnitNode *totaltree; UnitNode *totlabtree; const char *c; const char *exp; int i; int nc; int nunits; int ipass; /* Initialise */ result = NULL; if( in_lab ) *out_lab = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* A quick check for a common simple case: if the two strings are identical, return a UnitMap.*/ if( !strcmp( in, out ) ) { if( in_lab ) *out_lab = astStore( NULL, in_lab, strlen( in_lab ) + 1 ); return (AstMapping *) astUnitMap( 1, "", status ); } /* More initialisation. */ in_tree = NULL; out_tree = NULL; units = NULL; /* Parse the input units string, producing a tree of UnitNodes which represents the input units. A pointer to the UnitNode at the head of the tree is returned if succesfull. Report a context message if this fails. The returned tree contains branch nodes which correspond to operators or functions, and leaf nodes which represent constant values or named basic units (m, s, g, K, etc). Each branch node has one or more "arguments" (i.e. child nodes) which are operated on or combined by the branch node in some way to produce the nodes "value". This value is then used as an argument for the node's parent node (if any). If the string supplied by the user refers to any known derived units (e.g. "N", Newton) then each such unit is represented in the returned tree by a complete sub-tree in which the head node corresponds to the derived unit (e.g. "N") and the leaf nodes correspond to the basic units needed to define the derived unit ( for instance, "m", "s" and "g" - metres, seconds and grammes), or numerical constants. Thus every leaf node in the returned tree will be a basic unit (i.e. a unit which is not defined in terms of other units), or a numerical constant. */ in_tree = CreateTree( in, 1, 1, status ); if( !astOK ) astError( AST__BADUN, "astUnitMapper: Error parsing input " "units string '%s'.", status, in ); /* Do the same for the output units. */ if( astOK ) { out_tree = CreateTree( out, 1, 1, status ); if( !astOK ) astError( AST__BADUN, "astUnitMapper: Error parsing output " "units string '%s'.", status, out ); } /* If a blank string is supplied for both input and output units, then assume a UnitMap is the appropriate Mapping. */ if( !in_tree && !out_tree && astOK ) { result = (AstMapping *) astUnitMap( 1, "", status ); if( in_lab ) *out_lab = astStore( NULL, in_lab, strlen( in_lab ) + 1 ); /* Otherwise, if we have both input and output trees... */ } else if( in_tree && out_tree && astOK ) { /* Locate all the basic units used within either of these two trees. An array is formed in which each element is a pointer to a UnitNode contained within one of the trees created above. Each basic unit referred to in either tree will have a single entry in this array (even if the unit is referred to more than once). */ units = NULL; nunits = 0; LocateUnits( in_tree, &units, &nunits, status ); LocateUnits( out_tree, &units, &nunits, status ); /* Due to the simple nature of the simplification process in SimplifyTree, the following alogorithm sometimes fails to find a Mapping form input to output units, but can find a Mapping from output to input units. In this latter case, we can get the required Mapping from input to output simply by inverting the Mapign from output to input. So try first with the units in the original order. If this fails to find a Mapping, try again with the units swapped, and note that the final Mapping should be inverted before being used. */ for( ipass = 0; ipass < 2; ipass++ ){ if( ipass == 1 ) { tmp = in_tree; in_tree = out_tree; out_tree = tmp; } /* We are going to create a new tree of UnitNodes in which the head node corresponds to the requested output units, and which has a single non-constant leaf node corresponding to the input units. Initialise a pointer to this new tree to indicate that it has not yet been created. */ testtree = NULL; /* Loop round each basic unit used in the definition of either the input or the output units (i.e. the elements of the array created above by "LocateUnits"). The unit selected by this loop is referred to as the "current" unit. On each pass through this loop, we create a tree which is a candidate for the final required tree (the "test tree" pointed to by the testtree pointer initialised above). In order for a mapping to be possible between input and output units, the test tree created on each pass through this loop must be equivalent to the test tree for the previous pass (in other words, all the test trees must be equivalent). We break out of the loop (and return a NULL Mapping) as soon as we find a test tree which differs from the previous test tree. */ for( i = 0; i < nunits; i++ ) { /* Create copies of the trees describing the input and output units, in which all units other than the current unit are set to a constant value of 1. This is done by replacing OP_LDVAR nodes (i.e. nodes which "load" the value of a named basic unit) by OP_LDCON nodes (i.e. nodes which load a specified constant value) in the tree copy. */ intemp = FixUnits( in_tree, units[ i ], status ); outtemp = FixUnits( out_tree, units[ i ], status ); /* Simplify these trees. An important side-effect of this simplification is that trees are "standardised" which allows them to be compared for equivalence. A single mathematical expression can often be represented in many different ways (for instance "A/B" is equivalent to "(B**(-1))*A"). Standardisation is a process of forcing all equivalent representations into a single "standard" form. Without standardisation, trees representing the above two expressions would not be considered to be equivalent since thy would contain different nodes and have different structures. As a consequence of this standardisation, the "simplification" performed by SimplifyTree can sometimes actually make the tree more complicated (in terms of the number of nodes in the tree). */ SimplifyTree( &intemp, 1, status ); SimplifyTree( &outtemp, 1, status ); /* If either of the simplified trees does not depend on the current unit, then the node at the head of the simplified tree will have a constant value (because all the units other than the current unit have been fixed to a constant value of 1.0 above by FixUnits, leaving only the current unit to vary in value). If both simplified trees are constants, then neither tree depends on the current basic unit (i.e. references to the current basic unit cancel out within each string expression - for instance if converting from "m.s.Hz" to "km" and the current unit is "s", then the "s.Hz" term will cause the "s" units to cancel out). In this case ignore this basic unit and pass on to the next. */ if( outtemp->con != AST__BAD && intemp->con != AST__BAD ) { /* If just one simplified tree is constant, then the two units cannot match since one depends on the current basic unit and the other does not. Free any test tree from previous passes and break out of the loop. */ } else if( outtemp->con != AST__BAD || intemp->con != AST__BAD ) { intemp = FreeTree( intemp, status ); outtemp = FreeTree( outtemp, status ); testtree = FreeTree( testtree, status ); break; /* If neither simplified tree is constant, both depend on the current basic unit and so we can continue to see if their dependencies are equivalent. */ } else { /* We are going to create a new tree which is the inverse of the above simplified "intemp" tree. That is, the new tree will have a head node corresponding to the current unit, and a single non-constant leaf node corresponding to the input units. Create an OP_LDVAR node which can be used as the leaf node for this inverted tree. If the input tree is inverted successfully, this root node becomes part of the inverted tree, and so does not need to be freed explicitly (it will be freed when the inverted tree is freed). */ src = NewNode( NULL, OP_LDVAR, status ); if( astOK ) src->name = astStore( NULL, "input_units", 12 ); /* Now produce the inverted input tree. If the tree cannot be inverted, a null pointer is returned. Check for this. Otherwise a pointer to the UnitNode at the head of the inverted tree is returned. */ inv = InvertTree( intemp, src, status ); if( inv ) { /* Concatenate this tree (which goes from "input units" to "current unit") with the simplified output tree (which goes from "current unit" to "output units"), to get a new tree which goes from input units to output units. */ totaltree = ConcatTree( inv, outtemp, status ); /* Simplify this tree. */ SimplifyTree( &totaltree, 1, status ); /* Compare this simplified tree with the tree produced for the previous unit (if any). If they differ, we cannot map between the supplied units so annul the test tree and break out of the loop. If this is the first unit to be tested, use the total tree as the test tree for the next unit. */ if( testtree ) { if( CmpTree( totaltree, testtree, 0, status ) ) testtree = FreeTree( testtree, status ); totaltree = FreeTree( totaltree, status ); if( !testtree ) break; } else { testtree = totaltree; } } /* If the input tree was inverted, free the inverted tree. */ if( inv ) { inv = FreeTree( inv, status ); /* If the input tree could not be inverted, we cannot convert between input and output units. Free the node which was created to be the root of the inverted tree (and which has consequently not been incorporated into the inverted tree), free any testtree and break out of the loop. */ } else { src = FreeTree( src, status ); testtree = FreeTree( testtree, status ); break; } } /* Free the other trees. */ intemp = FreeTree( intemp, status ); outtemp = FreeTree( outtemp, status ); } /* If all the basic units used by either of the supplied system of units produced the same test tree, leave the "swap in and out units" loop. */ if( testtree ) break; } /* If the input and output units have been swapped, swap them back to their original order, and invert the test tree (if there is one). */ if( ipass > 0 ) { tmp = in_tree; in_tree = out_tree; out_tree = tmp; if( testtree ) { src = NewNode( NULL, OP_LDVAR, status ); if( astOK ) src->name = astStore( NULL, "input_units", 12 ); newtest = InvertTree( testtree, src, status ); FreeTree( testtree, status ); testtree = newtest; if( !newtest ) src = FreeTree( src, status ); } } /* If all the basic units used by either of the supplied system of units produced the same test tree, create a Mapping which is equivalent to the test tree and return it. */ if( testtree ) { result = MakeMapping( testtree, status ); /* We now go on to produce the output axis label from the supplied input axis label. Get a tree of UnitNodes which describes the supplied label associated with the input axis. The tree will have single OP_LDVAR node corresponding to the basic label (i.e. the label without any single argument functions or exponentiation operators applied). */ if( in_lab && astOK ) { /* Get a pointer to the first non-blank character, and store the number of characters to examine (this excludes any trailing white space). */ exp = in_lab; while( isspace( *exp ) ) exp++; c = exp + strlen( exp ) - 1; while( c >= exp && isspace( *c ) ) c--; nc = c - exp + 1; /* Create the tree. */ labtree = MakeLabelTree( exp, nc, status ); if( astOK ) { /* Concatenate this tree (which goes from "basic label" to "input label") with the test tree found above (which goes from "input units" to "output units"), to get a tree which goes from basic label to output label. */ totlabtree = ConcatTree( labtree, testtree, status ); /* Simplify this tree. */ SimplifyTree( &totlabtree, 1, status ); /* Create the output label from this tree. */ *out_lab = (char *) MakeExp( totlabtree, 0, 1, status ); /* Free the trees. */ totlabtree = FreeTree( totlabtree, status ); labtree = FreeTree( labtree, status ); /* Report a context error if the input label could not be parsed. */ } else { astError( AST__BADUN, "astUnitMapper: Error parsing axis " "label '%s'.", status, in_lab ); } } /* Free the units tree. */ testtree = FreeTree( testtree, status ); } } /* Free resources. */ in_tree = FreeTree( in_tree, status ); out_tree = FreeTree( out_tree, status ); units = astFree( units ); /* If an error has occurred, annul the returned Mapping. */ if( !astOK ) { result = astAnnul( result ); if( in_lab ) *out_lab = astFree( *out_lab ); } /* Return the result. */ return result; } const char *astUnitNormaliser_( const char *in, int *status ){ /* *+ * Name: * astUnitNormalizer * Purpose: * Normalise a unit string into FITS-WCS format. * Type: * Protected function. * Synopsis: * #include "unit.h" * const char *astUnitNormaliser( const char *in ) * Class Membership: * Unit member function. * Description: * This function returns a standard FITS-WCS form of the supplied unit * string. * Parameters: * in * A string representation of the units, for instance "km/h". * Returned Value: * A pointer to a dynamically allocated string holding the normalized * unit string. It should be freed using astFree when no longer needed. * Notes: * - An error will be reported if the units string cannot be parsed. * - NULL is returned if this function is invoked with the * global error status set or if it should fail for any reason. *- */ /* Local Variables: */ UnitNode *in_tree; double dval; const char *result; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Parse the input units string, producing a tree of UnitNodes which represents the input units. A pointer to the UnitNode at the head of the tree is returned if succesfull. Report a context message if this fails. */ in_tree = CreateTree( in, 0, 1, status ); if( in_tree ) { /* Simplify the units expression, only doing genuine simplifications. */ SimplifyTree( &in_tree, 1, status ); /* Invert literal constant unit multipliers. This is because a constant of say 1000 for a unit of "m" means "multiply the value in metres by 1000", but a unit string of "1000 m" means "value in units of 1000 m" (i.e. *divide* the value in metres by 1000). */ InvertConstants( &in_tree, status ); /* Convert the tree into string form. */ result = MakeExp( in_tree, 2, 1, status ); /* If the result is a constant value, return a blank string. */ if( 1 == astSscanf( result, "%lg", &dval ) ) { *((char *) result) = 0; } /* Free the tree. */ in_tree = FreeTree( in_tree, status ); } else { astError( AST__BADUN, "astUnitNormaliser: Error parsing input " "units string '%s'.", status, in ); } /* Return the result */ return result; } static int Ustrcmp( const char *a, const char *b, int *status ){ /* * Name: * Ustrcmp * Purpose: * A case blind version of strcmp. * Type: * Private function. * Synopsis: * #include "unit.h" * int Ustrcmp( const char *a, const char *b, int *status ) * Class Membership: * Unit member function. * Description: * Returns 0 if there are no differences between the two strings, and 1 * otherwise. Comparisons are case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strcmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Loop round each character. */ while( 1 ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } static int Ustrncmp( const char *a, const char *b, size_t n, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strncmp. * Type: * Private function. * Synopsis: * #include "unit.h" * int Ustrncmp( const char *a, const char *b, size_t n, int *status ) * Class Membership: * Unit member function. * Description: * Returns 0 if there are no differences between the first "n" * characters of the two strings, and 1 otherwise. Comparisons are * case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * n * The maximum number of characters to compare. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strncmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int i; /* Character index */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Check pointer have been supplied. */ if( !a || !b ) return ret; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Compare up to "n" characters. */ for( i = 0; i < (int) n; i++ ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } /* The rest of this file contains functions which are of use for debugging this module. They are usually commented out. static const char *DisplayTree( UnitNode *node, int ind ) { int i; char buf[200]; const char *result; char *a; const char *arg[ 2 ]; int rl; int slen; const opsym[ 100 ]; result = ""; for( i = 0; i < ind; i++ ) buf[ i ] = ' '; buf[ ind ] = 0; if( !node ) { printf( "%s \n", buf ); } else { printf( "%s Code: '%s' (%d)\n", buf, OpName( node->opcode ), node->opcode ); printf( "%s Narg: %d\n", buf, node->narg ); printf( "%s Constant: %g\n", buf, node->con ); printf( "%s Name: %s\n", buf, node->name?node->name:"" ); printf( "%s Unit: %s\n", buf, node->unit?node->unit->sym:"" ); printf( "%s Mult: %s\n", buf, node->mult?node->mult->sym:"" ); OpSym( node, opsym ); slen = strlen( opsym ); rl = slen; if( node->narg == 0 ) { result = astMalloc( rl + 1 ); if( astOK ) strcpy( (char *) result, opsym ); } else if( node->narg == 1 ) { rl += 2; printf( "%s Arg 0:\n", buf ); arg[ 0 ] = DisplayTree( (node->arg)[ 0 ], ind + 2 ); rl += strlen( arg[ 0 ] ); result = astMalloc( rl + 1 ); if( astOK ) { a = (char *) result; strcpy( a, opsym ); a += slen; *(a++) = '('; strcpy( a, arg[0] ); a += strlen( arg[ 0 ] ); *(a++) = ')'; } } else { rl += 4; for( i = 0; i < node->narg; i++ ) { printf( "%s Arg %d:\n", buf, i ); arg[ i ] = DisplayTree( (node->arg)[ i ], ind + 2 ); rl += strlen( arg[ i ] ); } result = astMalloc( rl + 1 ); if( astOK ) { a = (char *) result; *(a++) = '('; strcpy( a, arg[0] ); a += strlen( arg[ 0 ] ); *(a++) = ')'; strcpy( a, opsym ); a += slen; *(a++) = '('; strcpy( a, arg[1] ); a += strlen( arg[ 1 ] ); *(a++) = ')'; } } } if( !astOK ) { astFree( (void *) result ); result = ""; } return result; } static const char *OpName( Oper op ) { const char *name; if( op == OP_LDCON ) { name = "LDCON"; } else if( op == OP_LDVAR ) { name = "LDVAR"; } else if( op == OP_LOG ) { name = "LOG"; } else if( op == OP_LN ) { name = "LN"; } else if( op == OP_EXP ) { name = "EXP"; } else if( op == OP_SQRT ) { name = "SQRT"; } else if( op == OP_POW ) { name = "POW"; } else if( op == OP_DIV ) { name = "DIV"; } else if( op == OP_MULT ) { name = "MULT"; } else if( op == OP_LDPI ) { name = "LDPI"; } else if( op == OP_LDE ) { name = "LDE"; } else if( op == OP_NULL ) { name = "NULL"; } else { name = ""; } return name; } static void OpSym( UnitNode *node, char *buff ) { const char *sym = NULL; if( node->con != AST__BAD ) { sprintf( buff, "%g", node->con ); } else if( node->opcode == OP_LDVAR ) { sym = node->name; } else if( node->opcode == OP_LOG ) { sym = "log"; } else if( node->opcode == OP_LN ) { sym = "ln"; } else if( node->opcode == OP_EXP ) { sym = "exp"; } else if( node->opcode == OP_SQRT ) { sym = "sqrt"; } else if( node->opcode == OP_POW ) { sym = "**"; } else if( node->opcode == OP_DIV ) { sym = "/"; } else if( node->opcode == OP_MULT ) { sym = "*"; } else if( node->opcode == OP_NULL ) { sym = "NULL"; } else { sym = ""; } if( sym ) strcpy( buff, sym ); } static const char *TreeExp( UnitNode *node ) { char buff[ 100 ]; char buff2[ 100 ]; if( node->narg == 0 ) { OpSym( node, buff ); } else if( node->narg == 1 ) { OpSym( node, buff2 ); sprintf( buff, "%s(%s)", buff2, TreeExp( node->arg[ 0 ] ) ); } else if( node->narg == 2 ) { OpSym( node, buff2 ); sprintf( buff, "(%s)%s(%s)", TreeExp( node->arg[ 0 ] ), buff2, TreeExp( node->arg[ 1 ] ) ); } return astStore( NULL, buff, strlen( buff ) + 1 ); } */ ast-8.3.0/pcdmap.c0000664000175000017500000032675413004147321010660 00000000000000/* *class++ * Name: * PcdMap * Purpose: * Apply 2-dimensional pincushion/barrel distortion. * Constructor Function: c astPcdMap f AST_PCDMAP * Description: * A PcdMap is a non-linear Mapping which transforms 2-dimensional * positions to correct for the radial distortion introduced by some * cameras and telescopes. This can take the form either of pincushion * or barrel distortion, and is characterized by a single distortion * coefficient. * * A PcdMap is specified by giving this distortion coefficient and the * coordinates of the centre of the radial distortion. The forward * transformation of a PcdMap applies the distortion: * * RD = R * ( 1 + C * R * R ) * * where R is the undistorted radial distance from the distortion * centre (specified by attribute PcdCen), RD is the radial distance * from the same centre in the presence of distortion, and C is the * distortion coefficient (given by attribute Disco). * * The inverse transformation of a PcdMap removes the distortion * produced by the forward transformation. The expression used to derive * R from RD is an approximate inverse of the expression above. * Inheritance: * The PcdMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * PcdMap also has the following attributes: * * - Disco: PcdMap pincushion/barrel distortion coefficient * - PcdCen(axis): Centre coordinates of pincushion/barrel distortion * Functions: c The PcdMap class does not define any new functions beyond those f The PcdMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David Berry (Starlink) * History: * 18-MAY-1999 (DSB): * Original version. * 25-OCT-1999 (DSB): * Fixed memory leak in MapMerge. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitPcdMapVtab * method. * 23-AUG-2006 (DSB): * Override astEqual. * 23-APR-2015 (DSB): * Improve MapMerge. If a PcdMap can merge with its next-but-one * neighbour, then swap the PcdMap with its neighbour, so that * it is then next its next-but-one neighbour, and then merge the * two Mappings into a single Mapping. Previously, only the swap * was performed - not the merger. And the swap was only performed * if the intervening neighbour could not itself merge. This could * result in an infinite simplification loop, which was detected by * CmpMap and and aborted, resulting in no useful simplification. *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 PcdMap /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "unitmap.h" /* Unit mappings */ #include "zoommap.h" /* Zoom mappings */ #include "permmap.h" /* Axis permutations */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "pcdmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(PcdMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(PcdMap,Class_Init) #define class_vtab astGLOBAL(PcdMap,Class_Vtab) #define getattrib_buff astGLOBAL(PcdMap,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPcdMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstPcdMap *astPcdMapId_( double, const double [2], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static double GetDisco( AstPcdMap *, int * ); static double GetPcdCen( AstPcdMap *, int, int * ); static int CanMerge( AstMapping *, AstMapping *, int, int, int * ); static int CanSwap( AstMapping *, AstMapping *, int, int, int * ); static int Equal( AstObject *, AstObject *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestDisco( AstPcdMap *, int * ); static int TestPcdCen( AstPcdMap *, int, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearDisco( AstPcdMap *, int * ); static void ClearPcdCen( AstPcdMap *, int, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void PcdPerm( AstMapping **, int *, int, int * ); static void PcdZoom( AstMapping **, int *, int, int * ); static void PermGet( AstPermMap *, int **, int **, double **, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetDisco( AstPcdMap *, double, int * ); static void SetPcdCen( AstPcdMap *, int, double, int * ); /* Function Macros */ /* =============== */ /* Macros which return the maximum and minimum of two values. */ #define MAX(aa,bb) ((aa)>(bb)?(aa):(bb)) #define MIN(aa,bb) ((aa)<(bb)?(aa):(bb)) /* Macro to check for equality of floating point values. We cannot compare bad values directory because of the danger of floating point exceptions, so bad values are dealt with explicitly. */ #define EQUAL(aa,bb) (((aa)==AST__BAD)?(((bb)==AST__BAD)?1:0):(((bb)==AST__BAD)?0:(fabs((aa)-(bb))<=1.0E5*MAX((fabs(aa)+fabs(bb))*DBL_EPSILON,DBL_MIN)))) /* * * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "pcdmap.h" * MAKE_CLEAR(attr,component,assign,nval) * Class Membership: * Defined by the PcdMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPcdMap *this, int axis ) * * and an external interface function of the form: * * void astClear_( AstPcdMap *this, int axis ) * * which implement a method for clearing a single value in a specified * multi-valued attribute for an axis of a PcdMap. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. PcdCen in "astClearPcdCen"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR(attr,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPcdMap *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astClear" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ } else if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astClear(%s): The " #attr "attribute of " \ "the supplied %s cannot be cleared because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Assign the "clear" value. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attr##_( AstPcdMap *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,PcdMap,Clear##attr))( this, axis, status ); \ } /* * * Name: * MAKE_GET * Purpose: * Implement a method to get a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "pcdmap.h" * MAKE_GET(attr,type,bad_value,assign,nval) * Class Membership: * Defined by the PcdMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstPcdMap *this, int axis ) * * and an external interface function of the form: * * astGet_( AstPcdMap *this, int axis ) * * which implement a method for getting a single value from a specified * multi-valued attribute for an axis of a PcdMap. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. PcdCen in "astGetPcdCen"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. This can * use the string "axis" to represent the zero-based value index. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET(attr,type,bad_value,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attr( AstPcdMap *this, int axis, int *status ) { \ type result; /* Result to be returned */ \ \ /* Initialise */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astGet" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attr##_( AstPcdMap *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,PcdMap,Get##attr))( this, axis, status ); \ } /* * * Name: * MAKE_SET * Purpose: * Implement a method to set a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "pcdmap.h" * MAKE_SET(attr,type,component,assign,nval) * Class Membership: * Defined by the PcdMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPcdMap *this, int axis, value ) * * and an external interface function of the form: * * void astSet_( AstPcdMap *this, int axis, value ) * * which implement a method for setting a single value in a specified * multi-valued attribute for a PcdMap. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. PcdCen in "astSetPcdCen"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET(attr,type,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPcdMap *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astSet" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ } else if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astSet(%s): The " #attr "attribute of " \ "the supplied %s cannot be changed because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Store the new value in the structure component. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attr##_( AstPcdMap *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,PcdMap,Set##attr))( this, axis, value, status ); \ } /* * * Name: * MAKE_TEST * Purpose: * Implement a method to test if a single value has been set in a * multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "pcdmap.h" * MAKE_TEST(attr,assign,nval) * Class Membership: * Defined by the PcdMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( AstPcdMap *this, int axis ) * * and an external interface function of the form: * * int astTest_( AstPcdMap *this, int axis ) * * which implement a method for testing if a single value in a specified * multi-valued attribute has been set for a class. * Parameters: * attr * The name of the attribute to be tested, as it appears in the function * name (e.g. PcdCen in "astTestPcdCen"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. This can use the string "axis" to represent the zero-based * index of the value within the attribute. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_TEST(attr,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attr( AstPcdMap *this, int axis, int *status ) { \ int result; /* Value to return */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= nval ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astTest" #attr, astGetClass( this ), \ axis + 1, nval ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attr##_( AstPcdMap *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,PcdMap,Test##attr))( this, axis, status ); \ } /* Member functions. */ /* ================= */ static int CanMerge( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ){ /* * * Name: * CanMerge * Purpose: * Checks if two Mappings can be merged. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * int CanMerge( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ) * Class Membership: * PcdMap internal utility function. * Description: * This function checks the two supplied Mappings to see if they * can be merged into a single Mapping. One of the pair must be a PcdMap. * Parameters: * map1 * A pointer to the first mapping. * map2 * A pointer to the second mapping. * inv1 * The invert flag to use with the first mapping. * inv2 * The invert flag to use with the second mapping. * status * Pointer to the inherited status variable. * Returned Value: * 1 if the Mappings can be merged, zero otherwise. */ AstPcdMap *pcd; /* Pointer to PcdMap Mapping */ AstPcdMap *pcd2; /* Pointer to second PcdMap Mapping */ AstMapping *nopcd; /* Pointer to non-PcdMap Mapping */ const char *class1; /* Pointer to map1 class string */ const char *class2; /* Pointer to map2 class string */ const char *nopcd_class; /* Pointer to non-PcdMap class string */ int invert[ 2 ]; /* Original invert flags */ int ret; /* Returned flag */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise */ ret = 0; pcd = NULL; nopcd = NULL; /* Temporarily set the Invert attributes of both Mappings to the supplied values. */ invert[ 0 ] = astGetInvert( map1 ); astSetInvert( map1, inv1 ); invert[ 1 ] = astGetInvert( map2 ); astSetInvert( map2, inv2 ); /* Get the classes of the two mappings. */ class1 = astGetClass( map1 ); class2 = astGetClass( map2 ); if( astOK ){ /* Get pointers to the PcdMap and the non-PcdMap Mapping. */ if( !strcmp( class1, "PcdMap" ) ){ pcd = (AstPcdMap * ) map1; nopcd = map2; nopcd_class = class2; } else if( !strcmp( class2, "PcdMap" ) ){ nopcd = map1; pcd = (AstPcdMap * ) map2; nopcd_class = class1; } else { nopcd_class = "unusable"; } /* The Mappings can merge if the other Mapping is a UnitMap. */ if( !strcmp( nopcd_class, "UnitMap" ) ){ ret = 1; /* They can also merge if the other Mapping is also a PcdMap, and is the invert of the other. */ } else if( !strcmp( nopcd_class, "PcdMap" ) ){ pcd2 = (AstPcdMap *) nopcd; /* Check the distortion coefficients are equal. */ if( EQUAL( astGetDisco( pcd ), astGetDisco( pcd2 ) ) ){ /* Check the axis 0 centres are equal. */ if( EQUAL( astGetPcdCen( pcd, 0 ), astGetPcdCen( pcd2, 0 ) ) ){ /* Check the axis 1 centres are equal. */ if( EQUAL( astGetPcdCen( pcd, 1 ), astGetPcdCen( pcd2, 1 ) ) ){ /* Check the Invert flags are different. */ if( astGetInvert( pcd ) != astGetInvert( pcd2 ) ){ /* If the Mappings have passed all these tests, they can be merged. */ ret = 1; } } } } } } /* Re-instate the original settings of the Invert attributes for the supplied Mappings. */ astSetInvert( map1, invert[ 0 ] ); astSetInvert( map2, invert[ 1 ] ); /* Return the answer. */ return astOK ? ret : 0; } static int CanSwap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ){ /* * Name: * CanSwap * Purpose: * Determine if two Mappings could be swapped. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * int CanSwap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ) * Class Membership: * PcdMap member function * Description: * This function returns a flag indicating if the pair of supplied * Mappings could be replaced by an equivalent pair of Mappings from the * same classes as the supplied pair, but in reversed order. Each pair * of Mappings is considered to be compounded in series. The supplied * Mappings are not changed in any way. * Parameters: * map1 * The Mapping to be applied first. * map2 * The Mapping to be applied second. * inv1 * The invert flag to use with map1. A value of zero causes the forward * mapping to be used, and a non-zero value causes the inverse * mapping to be used. * inv2 * The invert flag to use with map2. * status * Pointer to the inherited status variable. * Returned Value: * 1 if the Mappings could be swapped, 0 otherwise. * Notes: * - One of the supplied pair of Mappings must be a PcdMap. * - A value of 0 is returned if the two Mappings could be merged into * a single Mapping. * - A value of 0 is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstMapping *nopcd; /* Pointer to non-PcdMap Mapping */ const char *class1; /* Pointer to map1 class string */ const char *class2; /* Pointer to map2 class string */ const char *nopcd_class; /* Pointer to non-PcdMap class string */ double *consts; /* Pointer to constants array */ int *inperm; /* Pointer to input axis permutation array */ int *outperm; /* Pointer to output axis permutation array */ int invert[ 2 ]; /* Original invert flags */ int nin; /* No. of input coordinates for the PermMap */ int nout; /* No. of output coordinates for the PermMap */ int ret; /* Returned flag */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise */ ret = 0; /* Temporarily set the Invert attributes of both Mappings to the supplied values. */ invert[ 0 ] = astGetInvert( map1 ); astSetInvert( map1, inv1 ); invert[ 1 ] = astGetInvert( map2 ); astSetInvert( map2, inv2 ); /* Get the classes of the two mappings. */ class1 = astGetClass( map1 ); class2 = astGetClass( map2 ); if( astOK ){ /* Get a pointer to the non-PcdMap Mapping. */ if( !strcmp( class1, "PcdMap" ) ){ nopcd = map2; nopcd_class = class2; } else { nopcd = map1; nopcd_class = class1; } /* If the other Mapping is a ZoomMap, the Mappings can be swapped. */ if( !strcmp( nopcd_class, "ZoomMap" ) ){ ret = 1; /* If it is a PermMap, the Mappings can be swapped so long as the PermMap simply swaps the two axes. */ } else if( !strcmp( nopcd_class, "PermMap" ) ){ /* Get the number of input and output coordinates for the PermMap. */ nin = astGetNin( nopcd ); nout = astGetNout( nopcd ); /* Must be 2-dimensional to swap. */ if( nin == 2 && nout == 2 ) { /* Get the axis permutation arrays and constants array for the PermMap. */ PermGet( (AstPermMap *) nopcd, &outperm, &inperm, &consts, status ); if( astOK ) { /* If the PermMap simply swaps the 2 axes (in both direction) we can swap the two mappings. */ ret = ( outperm[0] == 1 && outperm[1] == 0 && inperm[0] == 1 && inperm[1] == 0 ); /* Free the axis permutation and constants arrays. */ outperm = (int *) astFree( (void *) outperm ); inperm = (int *) astFree( (void *) inperm ); consts = (double *) astFree( (void *) consts ); } } } } /* Re-instate the original settings of the Invert attributes for the supplied Mappings. */ astSetInvert( map1, invert[ 0 ] ); astSetInvert( map2, invert[ 1 ] ); /* Return the answer. */ return astOK ? ret : 0; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a PcdMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PcdMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * PcdMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the PcdMap. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPcdMap *this; /* Pointer to the PcdMap structure */ int axis; /* Axis number */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PcdMap structure. */ this = (AstPcdMap *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* PcdCen(axis). */ /* ------------- */ if ( nc = 0, ( 1 == astSscanf( attrib, "pcdcen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearPcdCen( this, axis - 1 ); /* PcdCen. */ /* ------- */ } else if ( !strcmp( attrib, "pcdcen" ) ) { astClearPcdCen( this, 0 ); astClearPcdCen( this, 1 ); /* Disco. */ /* ------ */ } else if ( !strcmp( attrib, "disco" ) ) { astClearDisco( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two PcdMaps are equivalent. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * PcdMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two PcdMaps are equivalent. * Parameters: * this * Pointer to the first Object (a PcdMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the PcdMaps are equivalent, zero otherwise. * 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: */ AstPcdMap *that; AstPcdMap *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two PcdMap structures. */ this = (AstPcdMap *) this_object; that = (AstPcdMap *) that_object; /* Check the second object is a PcdMap. We know the first is a PcdMap since we have arrived at this implementation of the virtual function. */ if( astIsAPcdMap( that ) ) { /* Check the Invert flags for the two PcdMaps are equal. */ if( astGetInvert( this ) == astGetInvert( that ) ) { /* Check all the attributes are equal. */ if( astEQUAL( this->pcdcen[0], that->pcdcen[0] ) && astEQUAL( this->pcdcen[1], that->pcdcen[1] ) && astEQUAL( this->disco, that->disco ) ) { result = 1; } } } /* 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 PcdMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PcdMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a PcdMap, formatted as a character string. * Parameters: * this * Pointer to the PcdMap. * 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 PcdMap, 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 PcdMap. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPcdMap *this; /* Pointer to the PcdMap structure */ const char *result; /* Pointer value to return */ double dval; /* Double attribute value */ int axis; /* Axis number */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the PcdMap structure. */ this = (AstPcdMap *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* Disco. */ /* ------ */ if ( !strcmp( attrib, "disco" ) ) { dval = astGetDisco( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* PcdCen(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "pcdcen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetPcdCen( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* PcdCen. */ /* ------- */ } else if ( !strcmp( attrib, "pcdcen" ) ) { dval = astGetPcdCen( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } void astInitPcdMapVtab_( AstPcdMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPcdMapVtab * Purpose: * Initialise a virtual function table for a PcdMap. * Type: * Protected function. * Synopsis: * #include "pcdmap.h" * void astInitPcdMapVtab( AstPcdMapVtab *vtab, const char *name ) * Class Membership: * PcdMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the PcdMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPcdMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearDisco = ClearDisco; vtab->SetDisco = SetDisco; vtab->GetDisco = GetDisco; vtab->TestDisco = TestDisco; vtab->ClearPcdCen = ClearPcdCen; vtab->SetPcdCen = SetPcdCen; vtab->GetPcdCen = GetPcdCen; vtab->TestPcdCen = TestPcdCen; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; object->Equal = Equal; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->MapMerge = MapMerge; /* Declare the class dump function.*/ astSetDump( vtab, Dump, "PcdMap", "Apply pincushion distortion" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a PcdMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * PcdMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated PcdMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated PcdMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated PcdMap which is to be merged with * its neighbours. This should be a cloned copy of the PcdMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * PcdMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated PcdMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping **maplt; /* New mappings list pointer */ AstMapping *map2; /* First mapping to check */ AstMapping *newmap; /* Pointer to replacement Mapping */ AstMapping *mc[2]; /* Copies of supplied Mappings to swap */ AstMapping *smc0; /* Simplied Mapping */ AstMapping *smc1; /* Simplied Mapping */ const char *class1; /* Pointer to first Mapping class string */ const char *class2; /* Pointer to second Mapping class string */ const char *nclass; /* Pointer to neighbouring Mapping class */ int i1; /* Index of first PcdMap to merge */ int i2; /* Index of last PcdMap to merge */ int i; /* Loop counter */ int ic[2]; /* Copies of supplied invert flags to swap */ int invert; /* Should the inverted Mapping be used? */ int *invlt; /* New invert flags list pointer */ int nmapt; /* No. of Mappings in list */ int nstep1; /* No. of Mappings backwards to next mergable Mapping */ int nstep2; /* No. of Mappings forward to next mergable Mapping */ int result; /* Result value to return */ int swaphi; /* Can PcdMap be swapped with higher neighbour? */ int swaplo; /* Can PcdMap be swapped with lower neighbour? */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ i1 = 0; i2 = 0; /* First of all, see if the PcdMap can be replaced by a simpler Mapping, without reference to the neighbouring Mappings in the list. */ /* ======================================================================*/ /* If the distortion coefficient in the PcdMap is zero, the PcdMap can be replaced by a UnitMap. */ if( EQUAL( astGetDisco( (AstPcdMap *) ( *map_list )[ where ] ), 0.0 ) ){ /* Annul the PcdMap pointer in the list and replace it with a UnitMap pointer, and indicate that the forward transformation of the returned UnitMap should be used. */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) astUnitMap( 2, "", status ); ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the PcdMap itself could not be simplified, see if it can be merged with the Mappings on either side of it in the list. */ } else { /* Store the classes of the neighbouring Mappings in the list. */ class1 = ( where > 0 ) ? astGetClass( ( *map_list )[ where - 1 ] ) : NULL; class2 = ( where < *nmap - 1 ) ? astGetClass( ( *map_list )[ where + 1 ] ) : NULL; /* In series. */ /* ========== */ if ( series ) { /* We first look to see if the PcdMap can be merged with one of its neighbours, resulting in a reduction of one in the number of Mappings in the list. A PcdMap can only merge directly with its own inverse, or a UnitMap. */ if( class1 && CanMerge( ( *map_list )[ where - 1 ], ( *map_list )[ where ], ( *invert_list )[ where - 1 ], ( *invert_list )[ where ], status ) ){ nclass = class1; i1 = where - 1; i2 = where; } else if( class2 && CanMerge( ( *map_list )[ where ], ( *map_list )[ where + 1 ], ( *invert_list )[ where ], ( *invert_list )[ where + 1 ], status ) ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* If the PcdMap can merge with one of its neighbours, create the merged Mapping. */ if( nclass ){ /* If the neighbour is a PcdMap, it must be the inverse of the nominated Mapping, and so they merge to form a UnitMap. */ if( !strcmp( nclass, "PcdMap" ) ){ newmap = (AstMapping *) astUnitMap( 2, "", status ); invert = 0; /* If the neighbour is a UnitMap, they merge to form a clone of the nominated PcdMap. */ } else { newmap = (AstMapping *) astClone( ( *map_list )[ where ] ); invert = ( *invert_list )[ where ]; } /* If succesfull... */ if( astOK ){ /* Annul the first of the two Mappings, and replace it with the merged Mapping. Also set the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = newmap; ( *invert_list )[ i1 ] = invert; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i2 ] ); for ( i = i2 + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } /* If the PcdMap could not merge directly with either of its neighbours, we consider whether it would be worthwhile to swap the PcdMap with either of its neighbours. This can only be done for certain classes of Mapping (ZoomMaps & some PermMaps), and will usually require both Mappings to be modified (unless they are commutative). The advantage of swapping the order of the Mappings is that it may result in the PcdMap being adjacent to a Mapping with which it can merge directly on the next invocation of this function, thus reducing the number of Mappings in the list. */ } else { /* Set a flag if we could swap the PcdMap with its higher neighbour. */ if( where + 1 < *nmap ){ swaphi = CanSwap( ( *map_list )[ where ], ( *map_list )[ where + 1 ], ( *invert_list )[ where ], ( *invert_list )[ where + 1 ], status ); } else { swaphi = 0; } /* If so, step through each of the Mappings which follow the PcdMap, looking for a Mapping with which the PcdMap could merge directly. Stop when such a Mapping is found, or if a Mapping is found with which the PcdMap could definitely not swap. Note the number of Mappings which separate the PcdMap from the Mapping with which it could merge (if any). */ nstep2 = -1; if( swaphi ){ for( i2 = where + 1; i2 < *nmap; i2++ ){ /* See if we may be able to merge with this Mapping. If so, note the number of steps between the two Mappings and leave the loop. */ nclass = astGetClass( ( *map_list )[ i2 ] ); if( !strcmp( nclass, "UnitMap" ) || !strcmp( nclass, "PcdMap" ) ){ nstep2 = i2 - where - 1; break; } /* If there is no chance that we can swap with this Mapping, leave the loop with -1 for the number of steps to indicate that no merging is possible. PcdMaps can swap with ZoomMaps and some PermMaps. */ if( strcmp( nclass, "ZoomMap" ) && strcmp( nclass, "PermMap" ) ) { break; } } } /* Do the same working forward from the PcdMap towards the start of the map list. */ if( where > 0 ){ swaplo = CanSwap( ( *map_list )[ where - 1 ], ( *map_list )[ where ], ( *invert_list )[ where - 1 ], ( *invert_list )[ where ], status ); } else { swaplo = 0; } nstep1 = -1; if( swaplo ){ for( i1 = where - 1; i1 >= 0; i1-- ){ nclass = astGetClass( ( *map_list )[ i1 ] ); if( !strcmp( nclass, "UnitMap" ) || !strcmp( nclass, "PcdMap" ) ){ nstep1 = where - 1 - i1; break; } if( strcmp( nclass, "ZoomMap" ) && strcmp( nclass, "PermMap" ) ) { break; } } } /* Choose which neighbour to swap with so that the PcdMap moves towards the nearest Mapping with which it can merge. */ if( nstep1 != -1 && ( nstep2 == -1 || nstep2 > nstep1 ) ){ nclass = class1; i1 = where - 1; i2 = where; } else if( nstep2 != -1 ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* If there is a target Mapping in the list with which the PcdMap could merge, replace the supplied Mappings with swapped Mappings to bring a PcdMap closer to the target Mapping. */ if( nclass ){ /* Swap the Mappings. */ if( !strcmp( nclass, "ZoomMap" ) ){ PcdZoom( (*map_list) + i1, (*invert_list) + i1, where - i1, status ); } else if( !strcmp( nclass, "PermMap" ) ){ PcdPerm( (*map_list) + i1, (*invert_list) + i1, where - i1, status ); } /* And then merge them. */ if( where == i1 && where + 1 < *nmap ) { /* Merging upwards */ map2 = astClone( (*map_list)[ where + 1 ] ); nmapt = *nmap - where - 1; maplt = *map_list + where + 1; invlt = *invert_list + where + 1; (void) astMapMerge( map2, 0, series, &nmapt, &maplt, &invlt ); map2 = astAnnul( map2 ); *nmap = where + 1 + nmapt; } else if( where - 2 >= 0 ) { /* Merging downwards */ map2 = astClone( (*map_list)[ where - 2 ] ); nmapt = *nmap - where + 2; maplt = *map_list + where - 2 ; invlt = *invert_list + where - 2; (void) astMapMerge( map2, 0, series, &nmapt, &maplt, &invlt ); map2 = astAnnul( map2 ); *nmap = where - 2 + nmapt; } result = i1; /* If there is no Mapping available for merging, it may still be advantageous to swap with a neighbour because the swapped Mapping may be simpler than the original Mappings. */ } else if( swaphi || swaplo ) { /* Try swapping with each possible neighbour in turn. */ for( i = 0; i < 2; i++ ) { /* Set up the class and pointers for the mappings to be swapped, first the lower neighbour, then the upper neighbour. */ if( i == 0 && swaplo ){ nclass = class1; i1 = where - 1; i2 = where; } else if( i == 1 && swaphi ){ nclass = class2; i1 = where; i2 = where + 1; } else { nclass = NULL; } /* If we have a Mapping to swap with... */ if( nclass ) { /* Take copies of the Mapping and Invert flag arrays so we do not change the supplied values. */ mc[ 0 ] = (AstMapping *) astCopy( ( (*map_list) + i1 )[0] ); mc[ 1 ] = (AstMapping *) astCopy( ( (*map_list) + i1 )[1] ); ic[ 0 ] = ( (*invert_list) + i1 )[0]; ic[ 1 ] = ( (*invert_list) + i1 )[1]; /* Swap these Mappings. */ if( !strcmp( nclass, "ZoomMap" ) ){ PcdZoom( mc, ic, where - i1, status ); } else if( !strcmp( nclass, "PermMap" ) ){ PcdPerm( mc, ic, where - i1, status ); } /* If neither of the swapped Mappings can be simplified further, then there is no point in swapping the Mappings, so just annul the map copies. */ smc0 = astSimplify( mc[0] ); smc1 = astSimplify( mc[1] ); if( astGetClass( smc0 ) == astGetClass( mc[0] ) && astGetClass( smc1 ) == astGetClass( mc[1] ) ) { mc[ 0 ] = (AstMapping *) astAnnul( mc[ 0 ] ); mc[ 1 ] = (AstMapping *) astAnnul( mc[ 1 ] ); /* If one or both of the swapped Mappings could be simplified, then annul the supplied Mappings and return the swapped mappings, storing the index of the first modified Mapping. */ } else { (void ) astAnnul( ( (*map_list) + i1 )[0] ); (void ) astAnnul( ( (*map_list) + i1 )[1] ); ( (*map_list) + i1 )[0] = mc[ 0 ]; ( (*map_list) + i1 )[1] = mc[ 1 ]; ( (*invert_list) + i1 )[0] = ic[ 0 ]; ( (*invert_list) + i1 )[1] = ic[ 1 ]; result = i1; break; } /* Annul the simplied Mappings */ smc0 = astAnnul( smc0 ); smc1 = astAnnul( smc1 ); } } } } /* In parallel. */ /* ============ */ /* PcdMaps cannot combine in parallel with any other Mappings. */ } } /* Return the result. */ return result; } static void PermGet( AstPermMap *map, int **outperm, int **inperm, double **consts, int *status ){ /* * Name: * PermGet * Purpose: * Get the axis permutation and constants array for a PermMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * void PermGet( AstPermMap *map, int **outperm, int **inperm, * double **const, int *status ) * Class Membership: * PcdMap member function * Description: * This function returns axis permutation and constants arrays which can * be used to create a PermMap which is equivalent to the supplied PermMap. * Parameters: * map * The PermMap. * outperm * An address at which to return a popinter to an array of ints * holding the output axis permutation array. The array should be * released using astFree when no longer needed. * inperm * An address at which to return a popinter to an array of ints * holding the input axis permutation array. The array should be * released using astFree when no longer needed. * consts * An address at which to return a popinter to an array of doubles * holding the constants array. The array should be released using * astFree when no longer needed. * status * Pointer to the inherited status variable. * Notes: * - NULL pointers are returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding input positions for PermMap */ AstPointSet *pset2; /* PointSet holding output positions for PermMap */ double **ptr1; /* Pointer to pset1 data */ double **ptr2; /* Pointer to pset2 data */ double *cnst; /* Pointer to constants array */ double cn; /* Potential new constant value */ double ip; /* Potential output axis index */ double op; /* Potential input axis index */ int *inprm; /* Pointer to input axis permutation array */ int *outprm; /* Pointer to output axis permutation array */ int i; /* Axis count */ int nc; /* Number of constants stored so far */ int nin; /* No. of input coordinates for the PermMap */ int nout; /* No. of output coordinates for the PermMap */ /* Initialise. */ if( outperm ) *outperm = NULL; if( inperm ) *inperm = NULL; if( consts ) *consts = NULL; /* Check the global error status and the supplied pointers. */ if ( !astOK || !outperm || !inperm || !consts ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ nc = 0; /* Get the number of input and output axes for the supplied PermMap. */ nin = astGetNin( map ); nout = astGetNout( map ); /* Allocate the memory for the returned arrays. */ outprm = (int *) astMalloc( sizeof( int )* (size_t) nout ); inprm = (int *) astMalloc( sizeof( int )* (size_t) nin ); cnst = (double *) astMalloc( sizeof( double )* (size_t) ( nout + nin ) ); /* Returned the pointers to these arrays.*/ *outperm = outprm; *inperm = inprm; *consts = cnst; /* Create two PointSets, each holding two points, which can be used for input and output positions with the PermMap. */ pset1 = astPointSet( 2, nin, "", status ); pset2 = astPointSet( 2, nout, "", status ); /* Set up the two input positions to be [0,1,2...] and [-1,-1,-1,...]. The first position is used to enumerate the axes, and the second is used to check for constant axis values. */ ptr1 = astGetPoints( pset1 ); if( astOK ){ for( i = 0; i < nin; i++ ){ ptr1[ i ][ 0 ] = ( double ) i; ptr1[ i ][ 1 ] = -1.0; } } /* Use the PermMap to transform these positions in the forward direction. */ (void) astTransform( map, pset1, 1, pset2 ); /* Look at the mapped positions to determine the output axis permutation array. */ ptr2 = astGetPoints( pset2 ); if( astOK ){ /* No constant axis valeus found yet. */ nc = 0; /* Do each output axis. */ for( i = 0; i < nout; i++ ){ /* If the output axis value is copied from an input axis value, the index of the appropriate input axis will be in the mapped first position. */ op = ptr2[ i ][ 0 ]; /* If the output axis value is assigned a constant value, the result of mapping the two different input axis values will be the same. */ cn = ptr2[ i ][ 1 ]; if( op == cn ) { /* We have found another constant. Store it in the constants array, and store the index of the constant in the output axis permutation array. */ cnst[ nc ] = cn; outprm[ i ] = -( nc + 1 ); nc++; /* If the output axis values are different, then the output axis value must be copied from the input axis value. */ } else { outprm[ i ] = (int) ( op + 0.5 ); } } } /* Now do the same thing to determine the input permutation array. */ if( astOK ){ for( i = 0; i < nout; i++ ){ ptr2[ i ][ 0 ] = ( double ) i; ptr2[ i ][ 1 ] = -1.0; } } (void) astTransform( map, pset2, 0, pset1 ); if( astOK ){ for( i = 0; i < nin; i++ ){ ip = ptr1[ i ][ 0 ]; cn = ptr1[ i ][ 1 ]; if( ip == cn ) { cnst[ nc ] = cn; inprm[ i ] = -( nc + 1 ); nc++; } else { inprm[ i ] = (int) ( ip + 0.5 ); } } } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* If an error has occurred, attempt to free the returned arrays. */ if( !astOK ) { *outperm = (int *) astFree( (void *) *outperm ); *inperm = (int *) astFree( (void *) *inperm ); *consts = (double *) astFree( (void *) *consts ); } /* Return. */ return; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a PcdMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * PcdMap member function (over-rides the astSetAttrib protected * method inherited from the Mapping class). * Description: * This function assigns an attribute value for a PcdMap, 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 PcdMap. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPcdMap *this; /* Pointer to the PcdMap structure */ double dval; /* Double attribute value */ int axis; /* Index for the axis */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PcdMap structure. */ this = (AstPcdMap *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Disco. */ /* ------ */ if ( nc = 0, ( 1 == astSscanf( setting, "disco= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetDisco( this, dval ); /* PcdCen(axis). */ /* ------------ */ } else if ( nc = 0, ( 2 == astSscanf( setting, "pcdcen(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetPcdCen( this, axis - 1, dval ); /* PcdCen. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "pcdcen= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetPcdCen( this, 0, dval ); astSetPcdCen( this, 1, dval ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a PcdMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PcdMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a PcdMap's attributes. * Parameters: * this * Pointer to the PcdMap. * 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: */ AstPcdMap *this; /* Pointer to the PcdMap structure */ int axis; /* Axis number */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the PcdMap structure. */ this = (AstPcdMap *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* Disco. */ /* ------ */ if ( !strcmp( attrib, "disco" ) ) { result = astTestDisco( this ); /* PcdCen. */ /* ------- */ } else if ( !strcmp( attrib, "pcdcen" ) ) { result = astTestPcdCen( this, 0 ); /* PcdCen(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "pcdcen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestPcdCen( this, axis - 1 ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a PcdMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * PcdMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a PcdMap and a set of points encapsulated in a * PointSet and transforms the points so as to map them into the * required window. * Parameters: * this * Pointer to the PcdMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the PcdMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstPcdMap *map; /* Pointer to PcdMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *axin_0; /* Pointer to next input axis 0 value */ double *axin_1; /* Pointer to next input axis 1 value */ double *axout_0; /* Pointer to next output axis 0 value */ double *axout_1; /* Pointer to next output axis 1 value */ int npoint; /* Number of points */ int point; /* Loop counter for points */ double dx; /* Undistorted X increment from centre */ double dy; /* Undistorted Y increment from centre */ double dxp; /* Distorted X increment from centre */ double dyp; /* Distorted Y increment from centre */ double disco; /* Distortion coefficient */ double cen0; /* Centre of distortion on axis 0 */ double cen1; /* Centre of distortion on axis 1 */ double cr2; /* Constant */ double a; /* Constant */ double cr2a2; /* Constant */ double f; /* Expansion factor */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the PcdMap. */ map = (AstPcdMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Get the distortion coefficient and centre. */ disco = astGetDisco( map ); cen0 = astGetPcdCen( map, 0 ); cen1 = astGetPcdCen( map, 1 ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if( astOK ){ /* Store pointers to the first input and output values on both axes. */ axin_0 = ptr_in[ 0 ]; axin_1 = ptr_in[ 1 ]; axout_0 = ptr_out[ 0 ]; axout_1 = ptr_out[ 1 ]; /* First deal with forward transformations. */ if( forward ){ for( point = 0; point < npoint; point++ ){ if( *axin_0 != AST__BAD && *axin_1 != AST__BAD ){ dx = ( *axin_0 - cen0 ); dy = ( *axin_1 - cen1 ); f = 1.0 + disco*( dx*dx + dy*dy ); dxp = dx*f; dyp = dy*f; *(axout_0++) = dxp + cen0; *(axout_1++) = dyp + cen1; } else { *(axout_0++) = AST__BAD; *(axout_1++) = AST__BAD; } axin_0++; axin_1++; } /* Now deal with inverse transformations. */ } else { for( point = 0; point < npoint; point++ ){ if( *axin_0 != AST__BAD && *axin_1 != AST__BAD ){ dxp = ( *axin_0 - cen0 ); dyp = ( *axin_1 - cen1 ); cr2 = disco*( dxp*dxp + dyp*dyp ); a = ( 2.0*cr2 + 1.0 )/( 3.0*cr2 + 1.0 ); cr2a2 = cr2*a*a; f = ( 2.0*cr2a2*a + 1.0 )/( 3.0*cr2a2 + 1.0 ); dx = dxp*f; dy = dyp*f; /* The above approximate inverse is taken from SLA_UNPCD. If more accuracy c is needed, the following code can be uncommented to iterate to a better c solution. c c fl = 1.0 + disco*( dx*dx + dy*dy ); c dx = dxp/fl; c dy = dyp/fl; c c df = fabs( fl ); c while( df > fabs( fl*1.0E-6 ) ){ c f = 1.0 + disco*( dx*dx + dy*dy ); c df = fabs( f - fl ); c fl = f; c c dx = dxp/f; c dy = dyp/f; c } */ *(axout_0++) = dx + cen0; *(axout_1++) = dy + cen1; } else { *(axout_0++) = AST__BAD; *(axout_1++) = AST__BAD; } axin_0++; axin_1++; } } } /* Return a pointer to the output PointSet. */ return result; } static void PcdZoom( AstMapping **maps, int *inverts, int ipc, int *status ){ /* * Name: * PcdZoom * Purpose: * Swap a PcdMap and a ZoomMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * void PcdZoom( AstMapping **maps, int *inverts, int ipc, int *status ) * Class Membership: * PcdMap member function * Description: * A list of two Mappings is supplied containing a PcdMap and a * ZoomMap. These Mappings are annulled, and replaced with * another pair of Mappings consisting of a PcdMap and a ZoomMap * in the opposite order. These Mappings are chosen so that their * combined effect is the same as the original pair of Mappings. * Parameters: * maps * A pointer to an array of two Mapping pointers. * inverts * A pointer to an array of two invert flags. * ipc * The index within "maps" of the PcdMap. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPcdMap *pm2; /* Pointer to the returned PcdMap */ AstPcdMap *pm; /* Pointer to the supplied PcdMap */ AstZoomMap *zm2; /* Pointer to the returned ZoomMap */ AstZoomMap *zm; /* Pointer to the supplied ZoomMap */ double cen[2]; /* New distortion centre */ double disc; /* Distortion coeff. for returned PcdMap */ double disco; /* Distortion coeff. for supplied PcdMap */ double xcen; /* Axis 0 centre for supplied PcdMap */ double ycen; /* Axis 1 centre for supplied PcdMap */ double zoom; /* Zoom factor for supplied ZoomMap */ int old_pinv; /* Invert value for the supplied PcdMap */ int old_zinv; /* Invert value for the supplied ZoomMap */ /* Check the global error status. */ if ( !astOK ) return; /* Store pointers to the supplied PcdMap and the ZoomMap. */ pm = (AstPcdMap *) maps[ ipc ]; zm = (AstZoomMap *) maps[ 1 - ipc ]; /* Temporarily set the Invert attribute of the supplied Mappings to the supplied values. */ old_pinv = astGetInvert( pm ); astSetInvert( pm, inverts[ ipc ] ); old_zinv = astGetInvert( zm ); astSetInvert( zm, inverts[ 1 - ipc ] ); /* Get the zoom factor from the ZoomMap. */ zoom = astGetZoom( zm ); /* Get the distortion coefficient from the PcdMap. */ disco = astGetDisco( pm ); /* Get the distortion centre from the PcdMap. */ xcen = astGetPcdCen( pm, 0 ); ycen = astGetPcdCen( pm, 1 ); /* Re-instate the original value of the Invert attributes of the supplied Mappings. */ astSetInvert( pm, old_pinv ); astSetInvert( zm, old_zinv ); /* Create the returned ZoomMap. */ zm2 = astZoomMap( 2, zoom, "", status ); /* Find the attributes of the returned PcdMap. If the PCD map is applied first... */ if( ipc == 0 ) { cen[ 0 ] = xcen*zoom; cen[ 1 ] = ycen*zoom; disc = disco/(zoom*zoom); /* If the PCD map is applied second... */ } else { cen[ 0 ] = xcen/zoom; cen[ 1 ] = ycen/zoom; disc = disco*zoom*zoom; } /* Create the returned PcdMap. */ pm2 = astPcdMap( disc, cen, "", status ); if( inverts[ ipc ] ) astInvert( pm2 ); /* Replace the supplied Mappings with the ones created above, swapping the order. */ if( astOK ){ (void) astAnnul( pm ); (void) astAnnul( zm ); maps[ 1 - ipc ] = (AstMapping *) pm2; inverts[ 1 - ipc ] = inverts[ ipc ]; maps[ ipc ] = (AstMapping *) zm2; inverts[ ipc ] = 0; } /* Return. */ return; } static void PcdPerm( AstMapping **maps, int *inverts, int ipc, int *status ){ /* * Name: * PcdPerm * Purpose: * Swap a PcdMap and a PermMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * void PcdPerm( AstMapping **maps, int *inverts, int ipc, int *status ) * Class Membership: * PcdMap member function * Description: * A list of two Mappings is supplied containing a PcdMap and a * PermMap. These Mappings are annulled, and replaced with * another pair of Mappings consisting of a PcdMap and a PermMap * in the opposite order. These Mappings are chosen so that their * combined effect is the same as the original pair of Mappings. * Parameters: * maps * A pointer to an array of two Mapping pointers. * inverts * A pointer to an array of two invert flags. * ipc * The index within "maps" of the PcdMap. * status * Pointer to the inherited status variable. * Notes: * - It should have been checked previously that the PermMap simply * swaps axes 0 and 1. This is the only sort of PermMap which can be * used here. */ AstPermMap *rm; /* Pointer to the supplied PermMap */ AstPermMap *rm2; /* Pointer to the returned PermMap */ AstPcdMap *pm; /* Pointer to the supplied PcdMap */ AstPcdMap *pm2; /* Pointer to the returned PcdMap */ double cen[2]; /* Centre for new PcdMap */ double disco; /* Distortion coeff. for supplied PcdMap */ double xcen; /* Axis 0 centre for supplied PcdMap */ double ycen; /* Axis 1 centre for supplied PcdMap */ int old_rinv; /* Invert value for the supplied PermMap */ int old_pinv; /* Invert value for the supplied PcdMap */ /* Check the global error status. */ if ( !astOK ) return; /* Store pointers to the supplied PcdMap and the PermMap. */ pm = (AstPcdMap *) maps[ ipc ]; rm = (AstPermMap *) maps[ 1 - ipc ]; /* Temporarily set the Invert attribute of the supplied Mappings to the supplied values. */ old_pinv = astGetInvert( pm ); astSetInvert( pm, inverts[ ipc ] ); old_rinv = astGetInvert( rm ); astSetInvert( rm, inverts[ 1 - ipc ] ); /* Get the distortion coefficient from the PcdMap. */ disco = astGetDisco( pm ); /* Get the distortion centre from the PcdMap. */ xcen = astGetPcdCen( pm, 0 ); ycen = astGetPcdCen( pm, 1 ); /* Re-instate the original value of the Invert attributes of the supplied Mappings. */ astSetInvert( pm, old_pinv ); astSetInvert( rm, old_rinv ); /* Create the returned PermMap (unchanged). */ rm2 = astClone( rm ); /* Create the returned PcdMap. */ cen[ 0 ] = ycen; cen[ 1 ] = xcen; pm2 = astPcdMap( disco, cen, "", status ); if( inverts[ ipc ] ) astInvert( pm2 ); /* Replace the supplied Mappings with the ones created above, swapping the order. */ if( astOK ){ (void) astAnnul( pm ); (void) astAnnul( rm ); old_pinv = inverts[ ipc ]; maps[ ipc ] = (AstMapping *) rm2; inverts[ ipc ] = inverts[ 1 - ipc ]; maps[ 1 - ipc ] = (AstMapping *) pm2; inverts[ 1 - ipc ] = old_pinv; } /* Return. */ return; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * Disco * Purpose: * PcdMap pincushion/barrel distortion coefficient. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute specifies the pincushion/barrel distortion coefficient * used by a PcdMap. This coefficient is set when the PcdMap is created, * but may later be modified. If the attribute is cleared, its default * value is zero, which gives no distortion. For pincushion distortion, * the value should be positive. For barrel distortion, it should be * negative. * * Note that the forward transformation of a PcdMap applies the * distortion specified by this attribute and the inverse * transformation removes this distortion. If the PcdMap is inverted c (e.g. using astInvert), then the forward transformation will f (e.g. using AST_INVERT), then the forward transformation will * remove the distortion and the inverse transformation will apply * it. The distortion itself will still be given by the same value of * Disco. * * Note, the value of this attribute may changed only if the PcdMap * has no more than one reference. That is, an error is reported if the * PcdMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * PcdMap * All PcdMaps have this attribute. *att-- */ /* This ia a double value with a value of AST__BAD when undefined but yielding a default of 0.0. */ astMAKE_CLEAR1(PcdMap,Disco,disco,AST__BAD) astMAKE_GET(PcdMap,Disco,double,0.0,( ( this->disco == AST__BAD ) ? 0.0 : this->disco )) astMAKE_SET1(PcdMap,Disco,double,disco,value) astMAKE_TEST(PcdMap,Disco,( this->disco != AST__BAD )) /* *att++ * Name: * PcdCen(axis) * Purpose: * Centre coordinates of pincushion/barrel distortion. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute specifies the centre of the pincushion/barrel * distortion implemented by a PcdMap. It takes a separate value for * each axis of the PcdMap so that, for instance, the settings * "PcdCen(1)=345.0,PcdCen(2)=-104.4" specify that the pincushion * distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2 * respectively. This attribute is set when a PcdMap is created, but may * later be modified. If the attribute is cleared, the default value for * both axes is zero. * * Note, the value of this attribute may changed only if the PcdMap * has no more than one reference. That is, an error is reported if the * PcdMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * PcdMap * All PcdMaps have this attribute. * Notes: * - If no axis is specified, (e.g. "PcdCen" instead of * "PcdCen(2)"), then a "set" or "clear" operation will affect * the attribute value of both axes, while a "get" or "test" * operation will use just the PcdCen(1) value. *att-- */ /* The centre of the distortion. AST__BAD is stored if no value has been supplied, resulting in default values of zero being used. */ MAKE_CLEAR(PcdCen,pcdcen,AST__BAD,2) MAKE_SET(PcdCen,double,pcdcen,value,2) MAKE_TEST(PcdCen,( this->pcdcen[axis] != AST__BAD ),2) MAKE_GET(PcdCen,double,0.0,(( this->pcdcen[axis] == AST__BAD ) ? 0.0 : this->pcdcen[axis] ),2) /* Copy constructor. */ /* ----------------- */ /* No copy constructor is needed, as a byte-by-byte copy suffices. */ /* Destructor. */ /* ----------- */ /* No destructor is needed as no memory, etc. needs freeing. */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for PcdMap 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 PcdMap class to an output Channel. * Parameters: * this * Pointer to the PcdMap 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 Variables: */ AstPcdMap *this; /* Pointer to the PcdMap structure */ double dval; /* Attribute value */ int set; /* Is a value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PcdMap structure. */ this = (AstPcdMap *) this_object; /* Write out values representing the instance variables for the PcdMap 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. */ /* PcdCen(0). */ /* ---------- */ set = TestPcdCen( this, 0, status ); dval = set ? GetPcdCen( this, 0, status ) : astGetPcdCen( this, 0 ); astWriteDouble( channel, "PcdCn0", set, 1, dval, "Distortion centre on first axis" ); /* PcdCen(1). */ /* ---------- */ set = TestPcdCen( this, 1, status ); dval = set ? GetPcdCen( this, 1, status ) : astGetPcdCen( this, 1 ); astWriteDouble( channel, "PcdCn1", set, 1, dval, "Distortion centre on second axis" ); /* Disco. */ /* ------ */ set = TestDisco( this, status ); dval = set ? GetDisco( this, status ) : astGetDisco( this ); astWriteDouble( channel, "Disco", set, 1, dval, "Distortion coefficient" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPcdMap and astCheckPcdMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(PcdMap,Mapping) astMAKE_CHECK(PcdMap) AstPcdMap *astPcdMap_( double disco, const double pcdcen[2], const char *options, int *status, ...) { /* *++ * Name: c astPcdMap f AST_PCDMAP * Purpose: * Create a PcdMap. * Type: * Public function. * Synopsis: c #include "pcdmap.h" c AstPcdMap *astPcdMap( double disco, const double pcdcen[2], c const char *options, ... ) f RESULT = AST_PCDMAP( DISCO, PCDCEN, OPTIONS, STATUS ) * Class Membership: * PcdMap constructor. * Description: * This function creates a new PcdMap and optionally initialises its * attributes. * * A PcdMap is a non-linear Mapping which transforms 2-dimensional * positions to correct for the radial distortion introduced by some * cameras and telescopes. This can take the form either of pincushion * or barrel distortion, and is characterized by a single distortion * coefficient. * * A PcdMap is specified by giving this distortion coefficient and the * coordinates of the centre of the radial distortion. The forward * transformation of a PcdMap applies the distortion: * * RD = R * ( 1 + C * R * R ) * * where R is the undistorted radial distance from the distortion * centre (specified by attribute PcdCen), RD is the radial distance * from the same centre in the presence of distortion, and C is the * distortion coefficient (given by attribute Disco). * * The inverse transformation of a PcdMap removes the distortion * produced by the forward transformation. The expression used to derive * R from RD is an approximate inverse of the expression above, obtained * from two iterations of the Newton-Raphson method. The mismatch between * the forward and inverse expressions is negligible for astrometric * applications (to reach 1 milliarcsec at the edge of the Anglo-Australian * Telescope triplet or a Schmidt field would require field diameters of * 2.4 and 42 degrees respectively). * c If a PcdMap is inverted (e.g. using astInvert) then the roles of the f If a PcdMap is inverted (e.g. using AST_INVERT) then the roles of the * forward and inverse transformations are reversed; the forward * transformation will remove the distortion, and the inverse * transformation will apply it. * Parameters: c disco f DISCO = DOUBLE PRECISION (Given) * The distortion coefficient. Negative values give barrel * distortion, positive values give pincushion distortion, and * zero gives no distortion. c pcdcen f PCDCEN( 2 ) = DOUBLE PRECISION (Given) c A 2-element array containing the coordinates of the centre of the f An array containing the coordinates of the centre of the * distortion. 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 PcdMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new PcdMap. The syntax used is identical to that for the f AST_SET routine. 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 astPcdMap() f AST_PCDMAP = INTEGER * A pointer to the new PcdMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPcdMap *new; /* Pointer to new PcdMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the PcdMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPcdMap( NULL, sizeof( AstPcdMap ), !class_init, &class_vtab, "PcdMap", disco, pcdcen ); /* 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 PcdMap'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 PcdMap. */ return new; } AstPcdMap *astPcdMapId_( double disco, const double pcdcen[2], const char *options, ... ) { /* * Name: * astPcdMapId_ * Purpose: * Create a PcdMap. * Type: * Private function. * Synopsis: * #include "pcdmap.h" * AstPcdMap *astPcdMapId_( double disco, const double pcdcen[2], * const char *options, ... ) * Class Membership: * PcdMap constructor. * Description: * This function implements the external (public) interface to the * astPcdMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astPcdMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astPcdMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astPcdMap_. * Returned Value: * The ID value associated with the new PcdMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPcdMap *new; /* Pointer to new PcdMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the PcdMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPcdMap( NULL, sizeof( AstPcdMap ), !class_init, &class_vtab, "PcdMap", disco, pcdcen ); /* 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 PcdMap'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 PcdMap. */ return astMakeId( new ); } AstPcdMap *astInitPcdMap_( void *mem, size_t size, int init, AstPcdMapVtab *vtab, const char *name, double disco, const double pcdcen[2], int *status ){ /* *+ * Name: * astInitPcdMap * Purpose: * Initialise a PcdMap. * Type: * Protected function. * Synopsis: * #include "pcdmap.h" * AstPcdMap *astInitPcdMap( void *mem, size_t size, int init, * AstPcdMapVtab *vtab, const char *name, * double disco, const double pcdcen[2] ) * Class Membership: * PcdMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new PcdMap object. It allocates memory (if necessary) to accommodate * the PcdMap plus any additional data associated with the derived class. * It then initialises a PcdMap 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 PcdMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the PcdMap is to be initialised. * This must be of sufficient size to accommodate the PcdMap data * (sizeof(PcdMap)) 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 PcdMap (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 PcdMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the PcdMap'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 PcdMap. * 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). * disco * Distortion coefficient. * pcdcen * Distortion centre. * Returned Value: * A pointer to the new PcdMap. * 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: */ AstPcdMap *new; /* Pointer to new PcdMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPcdMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a Mapping structure (the parent class) as the first component within the PcdMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstPcdMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 2, 2, 1, 1 ); if ( astOK ) { /* Initialise the PcdMap data. */ /* ---------------------------- */ /* Store the shift and scale for each axis. */ new->pcdcen[0] = pcdcen[0]; new->pcdcen[1] = pcdcen[1]; new->disco = disco; /* If an error occurred, clean up by deleting the new PcdMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new PcdMap. */ return new; } AstPcdMap *astLoadPcdMap_( void *mem, size_t size, AstPcdMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPcdMap * Purpose: * Load a PcdMap. * Type: * Protected function. * Synopsis: * #include "pcdmap.h" * AstPcdMap *astLoadPcdMap( void *mem, size_t size, * AstPcdMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * PcdMap loader. * Description: * This function is provided to load a new PcdMap 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 * PcdMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a PcdMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the PcdMap is to be * loaded. This must be of sufficient size to accommodate the * PcdMap data (sizeof(PcdMap)) 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 PcdMap (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 PcdMap 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(AstPcdMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new PcdMap. If this is NULL, a pointer * to the (static) virtual function table for the PcdMap 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 "PcdMap" is used instead. * Returned Value: * A pointer to the new PcdMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPcdMap *new; /* Pointer to the new PcdMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this PcdMap. In this case the PcdMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPcdMap ); vtab = &class_vtab; name = "PcdMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPcdMapVtab( 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 PcdMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "PcdMap" ); /* 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. */ /* PcdCen(0). */ /* ---------- */ new->pcdcen[0] = astReadDouble( channel, "pcdcn0", AST__BAD ); if ( TestPcdCen( new, 0, status ) ) SetPcdCen( new, 0, new->pcdcen[0], status ); /* PcdCen(1). */ /* ---------- */ new->pcdcen[1] = astReadDouble( channel, "pcdcn1", AST__BAD ); if ( TestPcdCen( new, 1, status ) ) SetPcdCen( new, 1, new->pcdcen[1], status ); /* Disco. */ /* ------ */ new->disco = astReadDouble( channel, "disco", AST__BAD ); if ( TestDisco( new, status ) ) SetDisco( new, new->disco, status ); /* If an error occurred, clean up by deleting the new PcdMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new PcdMap pointer. */ return new; } /* 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. */ ast-8.3.0/specmap.h0000664000175000017500000002061013004147321011027 00000000000000#if !defined( SPECMAP_INCLUDED ) /* Include this file only once */ #define SPECMAP_INCLUDED /* *+ * Name: * specmap.h * Type: * C include file. * Purpose: * Define the interface to the SpecMap class. * Invocation: * #include "specmap.h" * Description: * This include file defines the interface to the SpecMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The SpecMap class encapsulates various ecptral coordinate * conversions. Since, typically, a sequence of these conversions is * required, a SpecMap can be used to accumulate a series of conversions * which it then applies in sequence. * Inheritance: * The SpecMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * astTransform * Use an SpecMap to transform a set of points. * Protected: * astMapMerge * Simplify a sequence of Mappings containing an SpecMap. * New Methods Defined: * Public: * astSpecAdd * Add a coordinate conversion step to an SpecMap. * Private: * None. * Other Class Functions: * Public: * astIsASpecMap * Test class membership. * astSpecMap * Create an SpecMap. * Protected: * astCheckSpecMap * Validate class membership. * astInitSpecMap * Initialise an SpecMap. * astLoadSpecMap * Load an SpecMap. * Macros: * None. * Type Definitions: * Public: * AstSpecMap * SpecMap object type. * Protected: * AstSpecMapVtab * SpecMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 8-NOV-2002 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ------ */ /* Physical constants taken from Chapter 15 of the "Explanatory Supplement to the Astronomical Ephemeris". */ #define AST__C 2.99792458E8 /* Speed of light (metres per second) */ #define AST__H 6.6260755E-34 /* Plank constant (Joule.seconds) */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* SpecMap structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSpecMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ int *cvttype; /* Pointer to array of conversion types */ double **cvtargs; /* Pointer to argument list pointer array */ int ncvt; /* Number of conversions to perform */ } AstSpecMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSpecMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ void (* SpecAdd)( AstSpecMap *, const char *, const double[], int * ); } AstSpecMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstSpecMapGlobals { AstSpecMapVtab Class_Vtab; int Class_Init; } AstSpecMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitSpecMapGlobals_( AstSpecMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SpecMap) /* Check class membership */ astPROTO_ISA(SpecMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSpecMap *astSpecMap_( int, int, const char *, int *, ...); #else AstSpecMap *astSpecMapId_( int, int, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSpecMap *astInitSpecMap_( void *, size_t, int, AstSpecMapVtab *, const char *, int, int, int * ); /* Vtab initialiser. */ void astInitSpecMapVtab_( AstSpecMapVtab *, const char *, int * ); /* Loader. */ AstSpecMap *astLoadSpecMap_( void *, size_t, AstSpecMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ void astSpecAdd_( AstSpecMap *, const char *, const double[], int * ); /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSpecMap(this) astINVOKE_CHECK(SpecMap,this,0) #define astVerifySpecMap(this) astINVOKE_CHECK(SpecMap,this,1) /* Test class membership. */ #define astIsASpecMap(this) astINVOKE_ISA(SpecMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSpecMap astINVOKE(F,astSpecMap_) #else #define astSpecMap astINVOKE(F,astSpecMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSpecMap(mem,size,init,vtab,name,nin,flags) \ astINVOKE(O,astInitSpecMap_(mem,size,init,vtab,name,nin,flags,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSpecMapVtab(vtab,name) astINVOKE(V,astInitSpecMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSpecMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSpecMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSpecMap to validate SpecMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astSpecAdd(this,cvt,args) \ astINVOKE(V,astSpecAdd_(astCheckSpecMap(this),cvt,args,STATUS_PTR)) #endif ast-8.3.0/shiftmap.c0000664000175000017500000015277013004147321011222 00000000000000/* *class++ * Name: * ShiftMap * Purpose: * Add a constant value to each coordinate. * Constructor Function: c astShiftMap f AST_SHIFTMAP * Description: * A ShiftMap is a linear Mapping which shifts each axis by a * specified constant value. * Inheritance: * The ShiftMap class inherits from the Mapping class. * Attributes: * The ShiftMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The ShiftMap class does not define any new functions beyond those f The ShiftMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David Berry (Starlink) * History: * 15-AUG-2003 (DSB): * Original version. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 10-MAY-2006 (DSB): * Override astEqual. *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 ShiftMap /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "matrixmap.h" /* Linear mappings */ #include "unitmap.h" /* Unit mappings */ #include "zoommap.h" /* Zoom mappings */ #include "permmap.h" /* Axis permutations */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "winmap.h" /* Window mappings */ #include "shiftmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(ShiftMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(ShiftMap,Class_Init) #define class_vtab astGLOBAL(ShiftMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstShiftMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstShiftMap *astShiftMapId_( int, const double [], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int GetObjSize( AstObject *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetIsLinear( AstMapping *, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two ShiftMaps are equivalent. * Type: * Private function. * Synopsis: * #include "shiftmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * ShiftMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two ShiftMaps are equivalent. * Parameters: * this * Pointer to the first Object (a ShiftMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the ShiftMaps are equivalent, zero otherwise. * 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: */ AstShiftMap *that; AstShiftMap *this; int i; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two ShiftMap structures. */ this = (AstShiftMap *) this_object; that = (AstShiftMap *) that_object; /* Check the second object is a ShiftMap. We know the first is a ShiftMap since we have arrived at this implementation of the virtual function. */ if( astIsAShiftMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two ShiftMaps differ, it may still be possible for them to be equivalent. First compare the ShiftMaps if their Invert flags are the same. In this case all the attributes of the two ShiftMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { result = 1; for( i = 0; i < nin; i++ ) { if( !astEQUAL( this->shift[ i ], that->shift[ i ] ) ) { result = 0; break; } } /* If the Invert flags for the two ShiftMaps differ, the attributes of the two ShiftMaps must be inversely related to each other. */ } else { result = 1; for( i = 0; i < nin; i++ ) { if( !astEQUAL( this->shift[ i ], -(that->shift[ i ] ) ) ) { result = 0; break; } } } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* 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 ShiftMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * ShiftMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one. * Parameters: * this * Pointer to the ShiftMap. * status * Pointer to the inherited status variable. */ return 1; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "shiftmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * ShiftMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied ShiftMap, * in bytes. * Parameters: * this * Pointer to the ShiftMap. * 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: */ AstShiftMap *this; /* Pointer to ShiftMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the ShiftMap structure. */ this = (AstShiftMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->shift ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitShiftMapVtab_( AstShiftMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitShiftMapVtab * Purpose: * Initialise a virtual function table for a ShiftMap. * Type: * Protected function. * Synopsis: * #include "shiftmap.h" * void astInitShiftMapVtab( AstShiftMapVtab *vtab, const char *name ) * Class Membership: * ShiftMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the ShiftMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAShiftMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->Rate = Rate; mapping->MapSplit = MapSplit; mapping->GetIsLinear = GetIsLinear; /* Declare the class dump, copy and delete functions.*/ astSetDump( vtab, Dump, "ShiftMap", "Shift each coordinate axis" ); astSetCopy( (AstObjectVtab *) vtab, Copy ); astSetDelete( (AstObjectVtab *) vtab, Delete ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a ShiftMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * ShiftMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated ShiftMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated ShiftMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated ShiftMap which is to be merged with * its neighbours. This should be a cloned copy of the ShiftMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * ShiftMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated ShiftMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstWinMap *w1; /* Pointer to replacement Mapping */ AstShiftMap *sm; /* Pointer to this ShiftMap */ double *aa; /* Pointer to shift terms for new WinMap */ double *bb; /* Pointer to scale terms for new WinMap */ int i; /* Axis count */ int nin; /* Number of axes */ int result; /* Returned value */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* A ShiftMap is equivalent to a WinMap with unit scaling. The policy on simplifying a ShiftMap is to convert it to the equivalent WinMap and let the WinMap class do the simplifying. Create the returned WinMap, initially with undefined corners. */ nin = astGetNin( this ); w1 = astWinMap( nin, NULL, NULL, NULL, NULL, "", status ); /* If succesful, store the scale and shift terms in the WinMap. The scale terms are unity. */ if( astOK ){ sm = (AstShiftMap *) this; bb = w1->b; aa = w1->a; for( i = 0; i < nin; i++ ) { *(bb++) = 1.0; *(aa++) = ( *invert_list )[ where ] ? -(sm->shift)[ i ] : (sm->shift)[ i ]; } /* Replace the supplied ShiftMap with the new WinMap and reset the invert flag. */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) w1; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; } /* Return the result. */ return result; } 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 * ShiftMap. * Type: * Private function. * Synopsis: * #include "shiftmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * ShiftMap 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 ShiftMap. This is only possible if the specified inputs * correspond to some subset of the ShiftMap outputs. That is, there * must exist a subset of the ShiftMap outputs for which each output * depends only on the selected ShiftMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied ShiftMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the ShiftMap to be split (the ShiftMap 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 ShiftMap, 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 ShiftMap 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 ShiftMap. 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: */ AstShiftMap *newsm; /* Pointer to returned ShiftMap */ AstShiftMap *this; /* Pointer to ShiftMap structure */ int *result; /* Pointer to returned array */ int i; /* Loop count */ int iin; /* Mapping input index */ int mnin; /* No. of Mapping inputs */ int ok; /* Are input indices OK? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the ShiftMap structure. */ this = (AstShiftMap *) this_map; /* Allocate memory for the returned array and create a ShiftMap with the required number of axes and initially unsorted shifts. */ result = astMalloc( sizeof( int )*(size_t) nin ); newsm = astShiftMap( nin, this->shift, "", status ); *map = (AstMapping *) newsm; /* Check pointers can be used safely. */ if( astOK ) { /* Store the required shifts in the new ShiftMap. At the same time check that each axis is valid. */ mnin = astGetNin( this ); ok = 1; for( i = 0; i < nin; i++ ) { iin = in[ i ]; if( iin >= 0 && iin < mnin ) { (newsm->shift)[ i ] = (this->shift)[ iin ]; result[ i ] = iin; } else { ok = 0; break; } } /* If the "in" array contained any invalid values, free the returned resources. */ if( !ok ) { result = astFree( result ); *map = astAnnul( *map ); /* If the indices are good, invert the returned ShiftMap if the supplied ShiftMap is inverted. */ } else { if( astGetInvert( this ) ) astInvert( *map ); } } /* 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 double Rate( AstMapping *this, 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 "shiftmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * ShiftMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ return ( ax1 == ax2 ) ? 1.0 : 0.0; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a ShiftMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "shiftmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * ShiftMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a ShiftMap and a set of points encapsulated in a * PointSet and transforms the points so as to map them into the * required window. * Parameters: * this * Pointer to the ShiftMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the ShiftMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstShiftMap *map; /* Pointer to ShiftMap to be applied */ const char *class; /* Object class */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *axin; /* Pointer to next input axis value */ double *axout; /* Pointer to next output axis value */ double a; /* Shift for current axis */ int coord; /* Loop counter for coordinates */ int ncoord; /* Number of coordinates per point */ int npoint; /* Number of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the ShiftMap. */ map = (AstShiftMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Report an error if the ShiftMap does not contain any shifts. */ if( !map->shift && astOK ){ class = astGetClass( this ); astError( AST__BADSM, "astTransform(%s): The supplied %s does not " "contain any shift information.", status, class, class ); } /* Perform coordinate arithmetic. */ /* ------------------------------ */ if( astOK ){ /* Apply the mapping to each axis. */ for( coord = 0; coord < ncoord; coord++ ){ /* Store pointers to the first input and output values on this axis. */ axin = ptr_in[ coord ]; axout = ptr_out[ coord ]; /* Get the value to add to each axis value. */ a = (map->shift)[ coord ]; /* If the shift is bad store bad output values. */ if( a == AST__BAD ){ for( point = 0; point < npoint; point++ ) *(axout++) = AST__BAD; /* Otherwise, shift this axis, taking account of whether the mapping is inverted or not. */ } else { if( !forward ) a = -a; for( point = 0; point < npoint; point++ ){ if( *axin != AST__BAD ){ *(axout++) = (*axin) + a; } else { *(axout++) = AST__BAD; } axin++; } } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for ShiftMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for ShiftMap objects. * Parameters: * objin * Pointer to the ShiftMap to be copied. * objout * Pointer to the ShiftMap being constructed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstShiftMap *out; /* Pointer to output ShiftMap */ AstShiftMap *in; /* Pointer to input ShiftMap */ int ncoord; /* No. of axes for the mapping */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the input and output ShiftMaps. */ in= (AstShiftMap *) objin; out = (AstShiftMap *) objout; /* Get the number of coordinates mapped by the ShiftMap. */ ncoord = astGetNin( in ); /* Allocate memory holding copies of the shifts defining the mapping. */ out->shift = (double *) astStore( NULL, (void *) in->shift, sizeof(double)*(size_t)ncoord ); /* If an error occurred, free any allocated memory. */ if ( !astOK ) { out->shift = (double *) astFree( (void *) out->shift ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for ShiftMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for ShiftMap objects. * Parameters: * obj * Pointer to the ShiftMap to be deleted. * status * Pointer to the inherited status variable. * Notes: * - This destructor does nothing and exists only to maintain a * one-to-one correspondence between destructors and copy * constructors. */ /* Local Variables: */ AstShiftMap *this; /* Pointer to ShiftMap */ /* Obtain a pointer to the ShiftMap structure. */ this = (AstShiftMap *) obj; /* Free the memory holding the shifts. */ this->shift = (double *) astFree( (void *) this->shift ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for ShiftMap 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 ShiftMap class to an output Channel. * Parameters: * this * Pointer to the ShiftMap 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 50 /* Maximum length of a comment string */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstShiftMap *this; /* Pointer to the ShiftMap structure */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment string */ int axis; /* Axis index */ int ncoord; /* No. of axes for mapping */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the ShiftMap structure. */ this = (AstShiftMap *) this_object; /* Get the number of coordinates to be mapped. */ ncoord = astGetNin( this ); /* Write out values representing the instance variables for the ShiftMap class. Accompany these with appropriate comment strings, possibly depending on the values being written.*/ /* The shifts. */ for( axis = 0; axis < ncoord; axis++ ){ (void) sprintf( buff, "Sft%d", axis + 1 ); (void) sprintf( comment, "Shift for axis %d", axis + 1 ); astWriteDouble( channel, buff, (this->shift)[ axis ] != 0.0, 0, (this->shift)[ axis ], comment ); } /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAShiftMap and astCheckShiftMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(ShiftMap,Mapping) astMAKE_CHECK(ShiftMap) AstShiftMap *astShiftMap_( int ncoord, const double shift[], const char *options, int *status, ...) { /* *++ * Name: c astShiftMap f AST_SHIFTMAP * Purpose: * Create a ShiftMap. * Type: * Public function. * Synopsis: c #include "shiftmap.h" c AstShiftMap *astShiftMap( int ncoord, const double shift[], c const char *options, ... ) f RESULT = AST_SHIFTMAP( NCOORD, SHIFT, OPTIONS, STATUS ) * Class Membership: * ShiftMap constructor. * Description: * This function creates a new ShiftMap and optionally initialises its * attributes. * * A ShiftMap is a linear Mapping which shifts each axis by a * specified constant value. * Parameters: c ncoord f NCOORD = INTEGER (Given) * The number of coordinate values for each point to be * transformed (i.e. the number of dimensions of the space in * which the points will reside). The same number is applicable * to both input and output points. c shift f SHIFT( NCOORD ) = DOUBLE PRECISION (Given) * An array containing the values to be added on to the input * coordinates in order to create the output coordinates. A separate * value should be supplied for each coordinate. 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 ShiftMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new ShiftMap. The syntax used is identical to that for the f AST_SET routine. 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 astShiftMap() f AST_SHIFTMAP = INTEGER * A pointer to the new ShiftMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstShiftMap *new; /* Pointer to new ShiftMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the ShiftMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitShiftMap( NULL, sizeof( AstShiftMap ), !class_init, &class_vtab, "ShiftMap", ncoord, shift ); /* 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 ShiftMap'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 ShiftMap. */ return new; } AstShiftMap *astShiftMapId_( int ncoord, const double shift[], const char *options, ... ) { /* * Name: * astShiftMapId_ * Purpose: * Create a ShiftMap. * Type: * Private function. * Synopsis: * #include "shiftmap.h" * AstShiftMap *astShiftMapId_( int ncoord, const double shift[], * const char *options, ... ) * Class Membership: * ShiftMap constructor. * Description: * This function implements the external (public) interface to the * astShiftMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astShiftMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astShiftMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astShiftMap_. * Returned Value: * The ID value associated with the new ShiftMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstShiftMap *new; /* Pointer to new ShiftMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the ShiftMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitShiftMap( NULL, sizeof( AstShiftMap ), !class_init, &class_vtab, "ShiftMap", ncoord, shift ); /* 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 ShiftMap'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 ShiftMap. */ return astMakeId( new ); } AstShiftMap *astInitShiftMap_( void *mem, size_t size, int init, AstShiftMapVtab *vtab, const char *name, int ncoord, const double *shift, int *status ) { /* *+ * Name: * astInitShiftMap * Purpose: * Initialise a ShiftMap. * Type: * Protected function. * Synopsis: * #include "shiftmap.h" * AstShiftMap *astInitShiftMap( void *mem, size_t size, int init, * AstShiftMapVtab *vtab, const char *name, * int ncoord, const double *shift ) * Class Membership: * ShiftMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new ShiftMap object. It allocates memory (if necessary) to accommodate * the ShiftMap plus any additional data associated with the derived class. * It then initialises a ShiftMap 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 ShiftMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the ShiftMap is to be initialised. * This must be of sufficient size to accommodate the ShiftMap data * (sizeof(ShiftMap)) 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 ShiftMap (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 ShiftMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the ShiftMap'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 ShiftMap. * 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). * ncoord * The number of coordinate values per point. * shift * Pointer to an array of shifts, one for each coordinate. * Returned Value: * A pointer to the new ShiftMap. * 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: */ AstShiftMap *new; /* Pointer to new ShiftMap */ int axis; /* Axis index */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitShiftMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a Mapping structure (the parent class) as the first component within the ShiftMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstShiftMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, ncoord, ncoord, 1, 1 ); if ( astOK ) { /* Initialise the ShiftMap data. */ /* ---------------------------- */ /* Allocate memory to hold the shift for each axis. */ new->shift = (double *) astMalloc( sizeof(double)*(size_t)ncoord ); /* Check the pointers can be used */ if( astOK ){ /* Store the shift and scale for each axis. */ for( axis = 0; axis < ncoord; axis++ ){ (new->shift)[ axis ] = shift ? shift[ axis ] : AST__BAD; } } /* If an error occurred, clean up by deleting the new ShiftMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new ShiftMap. */ return new; } AstShiftMap *astLoadShiftMap_( void *mem, size_t size, AstShiftMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadShiftMap * Purpose: * Load a ShiftMap. * Type: * Protected function. * Synopsis: * #include "shiftmap.h" * AstShiftMap *astLoadShiftMap( void *mem, size_t size, * AstShiftMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * ShiftMap loader. * Description: * This function is provided to load a new ShiftMap 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 * ShiftMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a ShiftMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the ShiftMap is to be * loaded. This must be of sufficient size to accommodate the * ShiftMap data (sizeof(ShiftMap)) 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 ShiftMap (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 ShiftMap 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(AstShiftMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new ShiftMap. If this is NULL, a pointer * to the (static) virtual function table for the ShiftMap 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 "ShiftMap" is used instead. * Returned Value: * A pointer to the new ShiftMap. * 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: */ AstShiftMap *new; /* Pointer to the new ShiftMap */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int axis; /* Axis index */ int ncoord; /* The number of coordinate axes */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this ShiftMap. In this case the ShiftMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstShiftMap ); vtab = &class_vtab; name = "ShiftMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitShiftMapVtab( 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 ShiftMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) vtab, name, channel ); if ( astOK ) { /* Get the number of axis for the mapping. */ ncoord = astGetNin( (AstMapping *) new ); /* Allocate memory to hold the shifts. */ new->shift = (double *) astMalloc( sizeof(double)*(size_t)ncoord ); /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "ShiftMap" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* The shifts. */ for( axis = 0; axis < ncoord; axis++ ){ (void) sprintf( buff, "sft%d", axis + 1 ); (new->shift)[ axis ] = astReadDouble( channel, buff, 0.0 ); } } /* If an error occurred, clean up by deleting the new ShiftMap. */ if ( !astOK ) new = astDelete( new ); /* Return the new ShiftMap 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. */ ast-8.3.0/cmpframe.h0000664000175000017500000003511113004147321011173 00000000000000#if !defined( CMPFRAME_INCLUDED ) /* Include this file only once */ #define CMPFRAME_INCLUDED /* *+ * Name: * cmpframe.h * Type: * C include file. * Purpose: * Define the interface to the CmpFrame class. * Invocation: * #include "cmpframe.h" * Description: * This include file defines the interface to the CmpFrame class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * * A CmpFrame is a compound Frame which allows two component Frames * (of any class) to be merged together to form a more complex * Frame. The axes of the two component Frames then appear together * in the resulting CmpFrame (those of the first Frame, followed by * those of the second Frame). * * Since a CmpFrame is itself a Frame, it can be used as a * component in forming further CmpFrames. Frames of arbitrary * complexity may be built from simple individual Frames in this * way. * Inheritance: * The CmpFrame class inherits from the Frame class. * Attributes Over-Ridden: * Domain (string) * A string which may be used to identify a CmpFrame and used as * an additional key when matching a target CmpFrame with a * template. The CmpFrame class re-defines the default value to * "CMP". * MaxAxes (integer) * Specifies the maximum number of axes in a target Frame that * can be matched when using the CmpFrame as a template. The * CmpFrame class sets this to be the sum of the MaxAxes * attribute values for the two component Frames contained by * the CmpFrame. Any attempt to alter this value (other than * through the component Frames) is simply ignored. * MinAxes (integer) * Specifies the minimum number of axes in a target Frame that * can be matched when using the CmpFrame as a template. The * CmpFrame class sets this to be the sum of the MinAxes * attribute values for the two component Frames contained by * the CmpFrame. Any attempt to alter this value (other than * through the component Frames) is simply ignored. * Naxes (integer) * A read-only attribute that gives the number of axes in a * CmpFrame (i.e. the number of dimensions of the space which * the CmpFrame describes). This value is determined when the * CmpFrame is created and is equal to the sum of the Naxes * attributes of the two component Frames. * Title (string) * Specifies a string to be used as a title on (e.g.) graphs to * describe the coordinate system which the CmpFrame * represents. The CmpFrame class re-defines the default value * to "-D Compound Coordinate System", where is the * number of CmpFrame axes. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * astDistance * Calculate the distance between two points. * astFormat * Format a coordinate value for a CmpFrame axis. * astNorm * Normalise a set of CmpFrame coordinates. * astOffset * Calculate an offset along a geodesic curve. * astPermAxes * Permute the order of a CmpFrame's axes. * astUnformat * Read a formatted coordinate value for a CmpFrame axis. * * Protected: * astAbbrev * Abbreviate a formatted CmpFrame axis value by skipping leading * fields. * astClearDirection * Clear the value of the Direction attribute for a CmpFrame axis. * astClearFormat * Clear the value of the Format attribute for a CmpFrame axis. * astClearLabel * Clear the value of the Label attribute for a CmpFrame axis. * astClearMaxAxes * Clear the value of the MaxAxes attribute for a CmpFrame. * astClearMinAxes * Clear the value of the MinAxes attribute for a CmpFrame. * astClearSymbol * Clear the value of the Symbol attribute for a CmpFrame axis. * astClearUnit * Clear the value of the Unit attribute for a CmpFrame axis. * astGap * Find a "nice" gap for tabulating CmpFrame axis values. * astGetAxis * Obtain a pointer to a specified Axis from a CmpFrame. * astGetDirection * Obtain the value of the Direction attribute for a CmpFrame axis. * astGetDomain * Obtain a pointer to the Domain attribute string for a CmpFrame. * astGetFormat * Obtain the value of the Format attribute for a CmpFrame axis. * astGetLabel * Obtain the value of the Label attribute for a CmpFrame axis. * astGetMaxAxes * Obtain the value of the MaxAxes attribute for a CmpFrame. * astGetMinAxes * Obtain the value of the MinAxes attribute for a CmpFrame. * astGetNaxes * Obtain the value of the Naxes attribute for a CmpFrame. * astGetPerm * Access the axis permutation array for a CmpFrame. * astGetSymbol * Obtain the value of the Symbol attribute for a CmpFrame axis. * astGetTitle * Obtain a pointer to the Title attribute string for a CmpFrame. * astGetUnit * Obtain the value of the Unit attribute for a CmpFrame axis. * astMatch * Determine if conversion is possible between two coordinate * systems. * astPrimaryFrame * Uniquely identify a primary Frame and one of its axes. * astSetAxis * Set a new Axis for a CmpFrame. * astSetDirection * Set the value of the Direction attribute for a CmpFrame axis. * astSetFormat * Set the value of the Format attribute for a CmpFrame axis. * astSetLabel * Set the value of the Label attribute for a CmpFrame axis. * astSetMaxAxes * Set a value for the MaxAxes attribute of a CmpFrame. * astSetMinAxes * Set a value for the MinAxes attribute of a CmpFrame. * astSetSymbol * Set the value of the Symbol attribute for a CmpFrame axis. * astSetUnit * Set the value of the Unit attribute for a CmpFrame axis. * astSubFrame * Select axes from a CmpFrame and convert to the new coordinate * system. * astTestDirection * Test if a Direction attribute value has been set for a CmpFrame * axis. * astTestFormat * Test if a Format attribute value has been set for a CmpFrame axis. * astTestLabel * Test if a Label attribute value has been set for a CmpFrame axis. * astTestMaxAxes * Test if a value has been set for the MaxAxes attribute of a * CmpFrame. * astTestMinAxes * Test if a value has been set for the MinAxes attribute of a * CmpFrame. * astTestSymbol * Test if a Symbol attribute value has been set for a CmpFrame axis. * astTestUnit * Test if a Unit attribute value has been set for a CmpFrame axis. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsACmpFrame * Test class membership. * astCmpFrame * Create a CmpFrame. * * Protected: * astCheckCmpFrame * Validate class membership. * astInitCmpFrame * Initialise a CmpFrame. * astInitCmpFrameVtab * Initialise the virtual function table for the CmpFrame class. * astLoadCmpFrame * Load a CmpFrame. * Macros: * None. * Type Definitions: * Public: * AstCmpFrame * CmpFrame object type. * * Protected: * AstCmpFrameVtab * CmpFrame virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 6-MAR-1996 (RFWS): * Original version. * 27-FEB-1997 (RFWS): * Improved the prologue. * 25-FEB-1998 (RFWS): * Over-ride the astUnformat method. * 8-JAN-2003 (DSB): * Added protected astInitCmpFrameVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "frame.h" /* Parent Frame class */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* The legal System values recognized by this class of Frame. */ #define AST__COMP 0 #endif /* Type Definitions. */ /* ================= */ /* CmpFrame structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstCmpFrame { /* Attributes inherited from the parent class. */ AstFrame frame; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstFrame *frame1; /* First component frame */ AstFrame *frame2; /* Second component Frame */ int *perm; /* Pointer to axis permutation array */ } AstCmpFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstCmpFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstCmpFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstCmpFrameGlobals { AstCmpFrameVtab Class_Vtab; int Class_Init; int *qsort_axes; char Label_Buff[ 101 ]; char Symbol_Buff[ 51 ]; char GetDomain_Buff[ 101 ]; char GetTitle_Buff[ 101 ]; } AstCmpFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(CmpFrame) /* Check class membership */ astPROTO_ISA(CmpFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstCmpFrame *astCmpFrame_( void *, void *, const char *, int *, ...); #else AstCmpFrame *astCmpFrameId_( void *, void *, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstCmpFrame *astInitCmpFrame_( void *, size_t, int, AstCmpFrameVtab *, const char *, AstFrame *, AstFrame *, int * ); /* Vtab initialiser. */ void astInitCmpFrameVtab_( AstCmpFrameVtab *, const char *, int * ); /* Loader. */ AstCmpFrame *astLoadCmpFrame_( void *, size_t, AstCmpFrameVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitCmpFrameGlobals_( AstCmpFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckCmpFrame(this) astINVOKE_CHECK(CmpFrame,this,0) #define astVerifyCmpFrame(this) astINVOKE_CHECK(CmpFrame,this,1) /* Test class membership. */ #define astIsACmpFrame(this) astINVOKE_ISA(CmpFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astCmpFrame astINVOKE(F,astCmpFrame_) #else #define astCmpFrame astINVOKE(F,astCmpFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitCmpFrame(mem,size,init,vtab,name,frame1,frame2) \ astINVOKE(O,astInitCmpFrame_(mem,size,init,vtab,name,astCheckFrame(frame1),astCheckFrame(frame2),STATUS_PTR)) /* Vtab Initialiser. */ #define astInitCmpFrameVtab(vtab,name) astINVOKE(V,astInitCmpFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadCmpFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadCmpFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckCmpFrame to validate CmpFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #endif ast-8.3.0/grismmap.h0000664000175000017500000003166613004147321011233 00000000000000#if !defined( GRISMMAP_INCLUDED ) /* Include this file only once */ #define GRISMMAP_INCLUDED /* *+ * Name: * grismmap.h * Type: * C include file. * Purpose: * Define the interface to the GrismMap class. * Invocation: * #include "grismmap.h" * Description: * This include file defines the interface to the GrismMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The GrismMap class implements Mappings which perform a "zoom" * transformation by multiplying all coordinate values by the same * scale factor (the inverse transformation is performed by * dividing by this scale factor). * Inheritance: * The GrismMap class inherits from the Mapping class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 8-JUL-2003 (DSB): * Initial version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* GrismMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstGrismMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double nr; double nrp; double waver; double alpha; double g; int m; double eps; double theta; double k1; double k2; double k3; } AstGrismMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstGrismMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (* GetGrismNR)( AstGrismMap *, int * ); int (* TestGrismNR)( AstGrismMap *, int * ); void (* ClearGrismNR)( AstGrismMap *, int * ); void (* SetGrismNR)( AstGrismMap *, double, int * ); double (* GetGrismNRP)( AstGrismMap *, int * ); int (* TestGrismNRP)( AstGrismMap *, int * ); void (* ClearGrismNRP)( AstGrismMap *, int * ); void (* SetGrismNRP)( AstGrismMap *, double, int * ); double (* GetGrismWaveR)( AstGrismMap *, int * ); int (* TestGrismWaveR)( AstGrismMap *, int * ); void (* ClearGrismWaveR)( AstGrismMap *, int * ); void (* SetGrismWaveR)( AstGrismMap *, double, int * ); double (* GetGrismAlpha)( AstGrismMap *, int * ); int (* TestGrismAlpha)( AstGrismMap *, int * ); void (* ClearGrismAlpha)( AstGrismMap *, int * ); void (* SetGrismAlpha)( AstGrismMap *, double, int * ); double (* GetGrismG)( AstGrismMap *, int * ); int (* TestGrismG)( AstGrismMap *, int * ); void (* ClearGrismG)( AstGrismMap *, int * ); void (* SetGrismG)( AstGrismMap *, double, int * ); int (* GetGrismM)( AstGrismMap *, int * ); int (* TestGrismM)( AstGrismMap *, int * ); void (* ClearGrismM)( AstGrismMap *, int * ); void (* SetGrismM)( AstGrismMap *, int, int * ); double (* GetGrismEps)( AstGrismMap *, int * ); int (* TestGrismEps)( AstGrismMap *, int * ); void (* ClearGrismEps)( AstGrismMap *, int * ); void (* SetGrismEps)( AstGrismMap *, double, int * ); double (* GetGrismTheta)( AstGrismMap *, int * ); int (* TestGrismTheta)( AstGrismMap *, int * ); void (* ClearGrismTheta)( AstGrismMap *, int * ); void (* SetGrismTheta)( AstGrismMap *, double, int * ); } AstGrismMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstGrismMapGlobals { AstGrismMapVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstGrismMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(GrismMap) /* Check class membership */ astPROTO_ISA(GrismMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstGrismMap *astGrismMap_( const char *, int *, ...); #else AstGrismMap *astGrismMapId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstGrismMap *astInitGrismMap_( void *, size_t, int, AstGrismMapVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitGrismMapVtab_( AstGrismMapVtab *, const char *, int * ); /* Loader. */ AstGrismMap *astLoadGrismMap_( void *, size_t, AstGrismMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitGrismMapGlobals_( AstGrismMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ double astGetGrismNR_( AstGrismMap *, int * ); int astTestGrismNR_( AstGrismMap *, int * ); void astClearGrismNR_( AstGrismMap *, int * ); void astSetGrismNR_( AstGrismMap *, double, int * ); double astGetGrismNRP_( AstGrismMap *, int * ); int astTestGrismNRP_( AstGrismMap *, int * ); void astClearGrismNRP_( AstGrismMap *, int * ); void astSetGrismNRP_( AstGrismMap *, double, int * ); double astGetGrismWaveR_( AstGrismMap *, int * ); int astTestGrismWaveR_( AstGrismMap *, int * ); void astClearGrismWaveR_( AstGrismMap *, int * ); void astSetGrismWaveR_( AstGrismMap *, double, int * ); double astGetGrismAlpha_( AstGrismMap *, int * ); int astTestGrismAlpha_( AstGrismMap *, int * ); void astClearGrismAlpha_( AstGrismMap *, int * ); void astSetGrismAlpha_( AstGrismMap *, double, int * ); double astGetGrismG_( AstGrismMap *, int * ); int astTestGrismG_( AstGrismMap *, int * ); void astClearGrismG_( AstGrismMap *, int * ); void astSetGrismG_( AstGrismMap *, double, int * ); int astGetGrismM_( AstGrismMap *, int * ); int astTestGrismM_( AstGrismMap *, int * ); void astClearGrismM_( AstGrismMap *, int * ); void astSetGrismM_( AstGrismMap *, int, int * ); double astGetGrismEps_( AstGrismMap *, int * ); int astTestGrismEps_( AstGrismMap *, int * ); void astClearGrismEps_( AstGrismMap *, int * ); void astSetGrismEps_( AstGrismMap *, double, int * ); double astGetGrismTheta_( AstGrismMap *, int * ); int astTestGrismTheta_( AstGrismMap *, int * ); void astClearGrismTheta_( AstGrismMap *, int * ); void astSetGrismTheta_( AstGrismMap *, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckGrismMap(this) astINVOKE_CHECK(GrismMap,this,0) #define astVerifyGrismMap(this) astINVOKE_CHECK(GrismMap,this,1) /* Test class membership. */ #define astIsAGrismMap(this) astINVOKE_ISA(GrismMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astGrismMap astINVOKE(F,astGrismMap_) #else #define astGrismMap astINVOKE(F,astGrismMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitGrismMap(mem,size,init,vtab,name) \ astINVOKE(O,astInitGrismMap_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitGrismMapVtab(vtab,name) astINVOKE(V,astInitGrismMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadGrismMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadGrismMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckGrismMap to validate GrismMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetGrismNR(this) astINVOKE(V,astGetGrismNR_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismNR(this) astINVOKE(V,astTestGrismNR_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismNR(this) astINVOKE(V,astClearGrismNR_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismNR(this,value) astINVOKE(V,astSetGrismNR_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismNRP(this) astINVOKE(V,astGetGrismNRP_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismNRP(this) astINVOKE(V,astTestGrismNRP_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismNRP(this) astINVOKE(V,astClearGrismNRP_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismNRP(this,value) astINVOKE(V,astSetGrismNRP_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismWaveR(this) astINVOKE(V,astGetGrismWaveR_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismWaveR(this) astINVOKE(V,astTestGrismWaveR_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismWaveR(this) astINVOKE(V,astClearGrismWaveR_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismWaveR(this,value) astINVOKE(V,astSetGrismWaveR_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismAlpha(this) astINVOKE(V,astGetGrismAlpha_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismAlpha(this) astINVOKE(V,astTestGrismAlpha_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismAlpha(this) astINVOKE(V,astClearGrismAlpha_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismAlpha(this,value) astINVOKE(V,astSetGrismAlpha_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismG(this) astINVOKE(V,astGetGrismG_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismG(this) astINVOKE(V,astTestGrismG_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismG(this) astINVOKE(V,astClearGrismG_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismG(this,value) astINVOKE(V,astSetGrismG_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismM(this) astINVOKE(V,astGetGrismM_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismM(this) astINVOKE(V,astTestGrismM_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismM(this) astINVOKE(V,astClearGrismM_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismM(this,value) astINVOKE(V,astSetGrismM_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismEps(this) astINVOKE(V,astGetGrismEps_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismEps(this) astINVOKE(V,astTestGrismEps_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismEps(this) astINVOKE(V,astClearGrismEps_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismEps(this,value) astINVOKE(V,astSetGrismEps_(astCheckGrismMap(this),value,STATUS_PTR)) #define astGetGrismTheta(this) astINVOKE(V,astGetGrismTheta_(astCheckGrismMap(this),STATUS_PTR)) #define astTestGrismTheta(this) astINVOKE(V,astTestGrismTheta_(astCheckGrismMap(this),STATUS_PTR)) #define astClearGrismTheta(this) astINVOKE(V,astClearGrismTheta_(astCheckGrismMap(this),STATUS_PTR)) #define astSetGrismTheta(this,value) astINVOKE(V,astSetGrismTheta_(astCheckGrismMap(this),value,STATUS_PTR)) #endif #endif ast-8.3.0/err_drama.c0000664000175000017500000000710513004147321011332 00000000000000/* * Name: * err_ems.c * Purpose: * Implement the "err" module for the DRAMA ERS error system. * Description: * This file implements an alternative "err" module for the AST * library. It is used to deliver error messages through the * DRAMA ERS error message system rather than by the default mechanism. * Copyright: * Copyright (C) 2008 Science and Technology Facilities Council. * 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 * . * Authors: * DSB: David S. Berry (UCLan) * TIMJ: Tim Jenness (JAC, Hawaii) * RFWS: R.F. Warren-Smith (STARLINK) * {enter_new_authors_here} * History: * 6-NOV-1996 (DSB): * Original version. * 16-SEP-2008 (TIMJ): * Use modern EMS interface * 13-NOV-2008 (TIMJ): * Modify for DRAMA * {enter_changes_here} */ #if HAVE_CONFIG_H #include #endif /* Module Macros. */ /* ============== */ /* Define the astCLASS macro (even although this is not a class implementation). This indicates to header files that they should make "protected" symbols available. */ #define astCLASS /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "err.h" /* Interface to this module */ /* Need to define these for DRAMA. Otherwise we have to include drama.h in the distribution as well */ #if HAVE_STDARG_H # define DSTDARG_OK #endif #define ERS_STANDALONE #include "Ers.h" /* Interface to the Ers system */ /* Function implementations. */ /* ========================= */ void astPutErr_( int status, const char *message ) { /* *+ * Name: * astPutErr * Purpose: * Deliver an error message. * Type: * Protected function. * Synopsis: * #include "err.h" * void astPutErr( int status, const char *message ) * Description: * This function delivers an error message and (optionally) an * accompanying status value to the user. It may be re-implemented * in order to deliver error messages in different ways, according * to the environment in which the AST library is being used. * Parameters: * status * The error status value. * message * A pointer to a null-terminated character string containing * the error message to be delivered. This should not contain * newline characters. * Notes: * - This function is documented as "protected" but, in fact, is * publicly accessible so that it may be re-implemented as * required. *- */ /* Local Variables: */ StatusType local_status; /* Local status value */ /* Make a copy of the status value supplied. Then invoke ems_rep_c to report the error message through EMS and to associate the error status with it. Ignore any returned status value. */ local_status = status; ErsRep( 0, &local_status, "%s", message ); } ast-8.3.0/fellipse.c0000664000175000017500000001023513004147321011177 00000000000000/* *+ * Name: * fellipse.c * Purpose: * Define a FORTRAN 77 interface to the AST Ellipse class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Ellipse class. * Routines Defined: * AST_ISAELLIPSE * AST_ELLIPSE * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 31-AUG-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "ellipse.h" /* C interface to the Ellipse class */ F77_LOGICAL_FUNCTION(ast_isaellipse)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAELLIPSE", NULL, 0 ); astWatchSTATUS( RESULT = astIsAEllipse( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_ellipse)( INTEGER(FRAME), INTEGER(FORM), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), DOUBLE_ARRAY(POINT3), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_INTEGER(FORM) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) GENPTR_DOUBLE_ARRAY(POINT3) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_ELLIPSE", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astEllipse( astI2P( *FRAME ), *FORM, POINT1, POINT2, POINT3, astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } F77_SUBROUTINE(ast_ellipsepars)( INTEGER(THIS), DOUBLE_ARRAY(CENTRE), DOUBLE(A), DOUBLE(B), DOUBLE(ANGLE), DOUBLE_ARRAY(P1), DOUBLE_ARRAY(P2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(CENTRE) GENPTR_DOUBLE(A) GENPTR_DOUBLE(B) GENPTR_DOUBLE(ANGLE) GENPTR_DOUBLE_ARRAY(P1) GENPTR_DOUBLE_ARRAY(P2) astAt( "AST_ELLIPSEPARS", NULL, 0 ); astWatchSTATUS( astEllipsePars( astI2P( *THIS ), CENTRE, A, B, ANGLE, P1, P2 ); ) } ast-8.3.0/unitmap.h0000664000175000017500000002041413004147321011056 00000000000000#if !defined( UNITMAP_INCLUDED ) /* Include this file only once */ #define UNITMAP_INCLUDED /* *+ * Name: * unitmap.h * Type: * C include file. * Purpose: * Define the interface to the UnitMap class. * Invocation: * #include "unitmap.h" * Description: * This include file defines the interface to the UnitMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The UnitMap class implements Mappings that perform an identity * (unit) coordinate transformation, simply by copying each * coordinate value from input to output (and similarly for the * inverse transformation). UnitMaps are therefore of little use * for converting coordinates, but they serve a useful role as * "null" Mappings in cases where a Mapping is needed (e.g. to * pass to a function), but no coordinate transformation is wanted. * Inheritance: * The UnitMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astMapMerge * Simplify a sequence of Mappings containing a UnitMap. * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsAUnitMap * Test class membership. * astUnitMap * Create a UnitMap. * * Protected: * astCheckUnitMap * Validate class membership. * astInitUnitMap * Initialise a UnitMap. * astInitUnitMapVtab * Initialise the virtual function table for the UnitMap class. * astLoadUnitMap * Load a UnitMap. * Macros: * None. * Type Definitions: * Public: * AstUnitMap * UnitMap object type. * * Protected: * AstUnitMapVtab * UnitMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 7-FEB-1996 (RFWS): * Original version. * 13-DEC-1996 (RFWS): * Over-ride the astMapMerge method. * 8-JAN-2003 (DSB): * Added protected astInitUnitMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* UnitMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstUnitMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ /* None. */ } AstUnitMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstUnitMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ /* None. */ } AstUnitMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstUnitMapGlobals { AstUnitMapVtab Class_Vtab; int Class_Init; } AstUnitMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitUnitMapGlobals_( AstUnitMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(UnitMap) /* Check class membership */ astPROTO_ISA(UnitMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstUnitMap *astUnitMap_( int, const char *, int *, ...); #else AstUnitMap *astUnitMapId_( int, const char *, ... )__attribute__((format(printf,2,3))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstUnitMap *astInitUnitMap_( void *, size_t, int, AstUnitMapVtab *, const char *, int, int * ); /* Vtab initialiser. */ void astInitUnitMapVtab_( AstUnitMapVtab *, const char *, int * ); /* Loader. */ AstUnitMap *astLoadUnitMap_( void *, size_t, AstUnitMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* None. */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckUnitMap(this) astINVOKE_CHECK(UnitMap,this,0) #define astVerifyUnitMap(this) astINVOKE_CHECK(UnitMap,this,1) /* Test class membership. */ #define astIsAUnitMap(this) astINVOKE_ISA(UnitMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astUnitMap astINVOKE(F,astUnitMap_) #else #define astUnitMap astINVOKE(F,astUnitMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitUnitMap(mem,size,init,vtab,name,ncoord) \ astINVOKE(O,astInitUnitMap_(mem,size,init,vtab,name,ncoord,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitUnitMapVtab(vtab,name) astINVOKE(V,astInitUnitMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadUnitMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadUnitMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckUnitMap to validate UnitMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ /* None. */ #endif ast-8.3.0/ratemap.h0000664000175000017500000001754213004147321011042 00000000000000#if !defined( RATEMAP_INCLUDED ) /* Include this file only once */ #define RATEMAP_INCLUDED /* *+ * Name: * ratemap.h * Type: * C include file. * Purpose: * Define the interface to the RateMap class. * Invocation: * #include "ratemap.h" * Description: * This include file defines the interface to the RateMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The RateMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astMapMerge * Merge a RateMap within a sequence of Mappings. * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsARateMap * Test class membership. * astRateMap * Create a RateMap. * * Protected: * astCheckRateMap * Validate class membership. * astInitRateMap * Initialise a RateMap. * astInitRateMapVtab * Initialise the virtual function table for the RateMap class. * astLoadRateMap * Load a RateMap. * Macros: * None. * Type Definitions: * Public: * AstRateMap * RateMap object type. * * Protected: * AstRateMapVtab * RateMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 7-DEC-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* RateMap structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstRateMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstMapping *map; /* Pointer to the Mapping */ int invert; /* Inversion flag for Mapping */ int iin; /* Index of Mapping input to vary */ int iout; /* Index of Mapping output to measure */ } AstRateMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstRateMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ /* None. */ } AstRateMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstRateMapGlobals { AstRateMapVtab Class_Vtab; int Class_Init; } AstRateMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitRateMapGlobals_( AstRateMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(RateMap) /* Check class membership */ astPROTO_ISA(RateMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstRateMap *astRateMap_( void *, int, int, const char *, int *, ...); #else AstRateMap *astRateMapId_( void *, int, int, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstRateMap *astInitRateMap_( void *, size_t, int, AstRateMapVtab *, const char *, AstMapping *, int, int, int * ); /* Vtab initialiser. */ void astInitRateMapVtab_( AstRateMapVtab *, const char *, int * ); /* Loader. */ AstRateMap *astLoadRateMap_( void *, size_t, AstRateMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* None. */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckRateMap(this) astINVOKE_CHECK(RateMap,this,0) #define astVerifyRateMap(this) astINVOKE_CHECK(RateMap,this,1) /* Test class membership. */ #define astIsARateMap(this) astINVOKE_ISA(RateMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astRateMap astINVOKE(F,astRateMap_) #else #define astRateMap astINVOKE(F,astRateMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitRateMap(mem,size,init,vtab,name,map,iin,iout) \ astINVOKE(O,astInitRateMap_(mem,size,init,vtab,name,astCheckMapping(map),iin,iout,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitRateMapVtab(vtab,name) astINVOKE(V,astInitRateMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadRateMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadRateMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckRateMap to validate RateMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ /* None. */ #endif ast-8.3.0/sun210_figures/0000775000175000017500000000000013004147321012063 500000000000000ast-8.3.0/sun210_figures/frameset.pdf0000664000175000017500000006743313004147321014321 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí½]Ìÿ[vT‘ôåM¹âí¢}. 1†>³ß_Ú ­hQI± 5Ö—6^ <‡1¡X´-/¼5\€ $&BcZhazl¸öÊ85= C.$d2ãLÓãÌq>ŸµöÞ¿çj\psf2óÿ­ýìï~Y{­µ×^{­µÿèSxŽOÿµß¾÷æSÿzúüMx®­”šŸþÀ›F~îõ)Ôñï{»¤ÄPž'þRÇs\pÎë»×PîðÛ7µÕç\Ó.yy“Æú¤Œ]ÒÒúÿ0v›{¯oßxI‰_¾ì’”×'e>y›sõk{ò^~ûÆGæ%/o|ì^âsó6ö^ß¾ùýÿü›H´Ä¡É‚ÞÛ%%¶€’ÜgÁÔJEhY¿à…–0Ô‰•,´äôP‚B»M‡½×·o¼¤v|W^’æ`‰·¹*¬”'ïÕa E#ó’…»—øܼM‡½W¢e<ýÉ…šß¹þ÷‡Þ„§é½BѾùž›±bœ‰è™tºÐã%‹è*ˆ.ÆÅh½‘lgÓüöM™YŒe% è‡OÒ 65é°wúöÍ.¹£äå”ôÔ´~l2·Ì&¼O‡ß¾ñqyÉ˹—ì¹Z“¶N7[Ř$KBf…÷NI, ÿÆÁ¬O%eñ²„ƒ '¹‰@¬dáduJ$XIÊ[“¶NR¬$®&ÉÎJú`÷9I¸ä‚HV½:¼°¢yÁBŠÜK|fÞ䆭S!å„\! -2 Ï)Ä´Hî¾)mÕM‹)BO ;¹Öç§À— làªÁöŒ±füÌÏqØïšž×w‹ß”çú8³B¥<ö9®: NÏ­³ŸªÏ%ê7H³?Ç4íOe<À¿E`¶¬¶ÖHÐhA£«zÏk½WI™Ï}ÕDE,=ðÕ¸D-FŸëDõM*yYô³XªÆ…ò‰~VÏkSZ:åwBeñJY´XI £(3I‹’ý^ªAèÆÀî¢ ¶C` [MÌ,Š)«u±Àõ/f@êR=r¾JÖ@‚\ËO5£˜j¿k{îhWТ‡Î†´V«‚²êZHM*æçõo]’º#x}KzšWÊapº¥/¸?óÏkùwê5.lÈ ‘ºT²v­i] ÖÚWõÚ­ÂÒæ2ð:Ö~ƒqwR…´‚Ä]·.Ú°¥.h½¥Æð½†tj,IRYcñÍZ¹Ck:©S´,ÒhUÅ Ÿ³~o•tJ‡¹º!ma·v¤öÔÖ@f›‚à¥8¶¸á¥¸Öän5øWHû]#Ö5 -±£(B[k‰m´í餧-pø‚ׄ]¡¶’ÚÓ’V$Õˆ^¼(€Tç%‹BÖ õh ‰sŸ‰(^d”Ã답óÏ1N¹5ÅÓ‚Á«EÕ)é(u òŒl=ÔÙ´¢¹Eª¶(KÔÎ'ôWûpés«; Ö—N…Þˆ¤E#@RÀ x!8IñÔXL>DäëËqÁ.N*ᔩ¡bi¡cZ[ÑÀß—’´Ð_ÇÂL¤”mÏ…HëyÉ,j\”HbY‚1wû½(¦Y"£E Q}€,— àæTg´MGðØbÉ 4œO+tl·íR]ôÝ°?÷©5æ’¶ó´°d~{ìbñ@> ìZµ­=—§Ö°Å-äÀA«W‰Ÿ˜Á:k™´%-æ_8jK’TÒ’ mí mlPSj%î’E,&O£ý^þl\x@‹~—øÃ*7ÎR”k¨ÅÉѹº¯*«È~k ôéÿMä·îêD~ëSœ¸°¡ß.òj"_€°&z[æ{'G蟊ùÛãO—öÝÎ"RÊS}÷¢ß«{4`.$!?뛌ûb¶!ÙÀuÄ2.Æ[=‚Èh}M•|„½:-pI$ŠÁ«>öÓó÷\µM,âÐoJxü´Á½°F½T…¾”ŠfÏÚ"z*&‡5§DøèÑ0ð Ü(jÖâÚõÛ¿û;žâ›O}ç÷Å7áß~ó©ßñ©ïøŽß±Àïþ­¿õSÿÊÓ·®¿|ǧ_þÄ{ä¯O¾ýÛß|×w>ýæÿáÿý/Ïwü¿ðc?ñïÿ?ïôÿÿŸ¯¾ÿ_}Ë×þÍ?õ ¿øCßþ-ßô#¿ð‹¿ôCßòMÿéßú;¿ô~ÍŸùú7ÿâw=ýî³Ó:3gè¤0¿Ä^dTØ%i4Yâš 8¹ëÐ^ª,vÃnT3ïV›nyø&õ*{°µ¹aëuµá%!ó ÿ²KÒLúÆÚL#Ó^å½:¼NÛ62/Á™¿=|ãsó6÷\­×m|ÊuhJ)GYävI6KE‘Ñ/3å¡. ^SsÞ%˜Òê¬$õï67l½-VÝRâ%É4oo3M™Ë½W‡Zld^²Ðbc÷Ÿ›·¹çÝ`´´§?ù ^^áåc¬P‹¶VGK¬¥1–έIà˶ApU†êœ–š‘@§øpíK\°¨œv(±6¢ ,*Â`Š íi÷+-Q§$w]ºðÔùXÔ6ŒcUŸ¯íÁM}-l€Æ†&lGQ-5Í/ا8™¡©%F×.–°Má(±D¯¬QiúRªä唤¥àÐø´¿ºK`Z%ëhníQ P,mTö a ÑÇfÜ5Ú¤Œáu¥T;N0úÛ\ú÷ÀoZûÒ\]cYÍVÙ¤VÉÄie•ؤ%Ð(µF]¡$,V©Œ;Z¥©¨Ä6•4;l(  êyEàË&#Û„S4º´ÔóŽ‘q:«ó¥°4 SÆET“_ZÃk ò"㈨ ë(â¸A"Ú%¢û» ê£dÈ>:Z*ö‚ƒÑQu`)J]mÄfÛôiqÏO8Äq‚°à²fiÜ¢ãkY»kTŽ/@ý¤‘Š$A#U†µ”+½x”K452´e³K8Œ/@jñª‘hˆZð ùwÃKa¡¥ê”¤ªÍ-V'€Â.š(H0§#…¬yhëû®µtˆù2UåUqº†©j•ÈV—–J[Õ*‘± % ¼†2 „a­Úð[|‘Lx`HP¨Iæ*À$íU.„z TÛœ€çƒÕ†¥"Ûþ®‘Íë ÖÍvÁ ]¤Ã]ç€n·`œ KØ„ƒÕ†ñ(þ®QaŽºZ08…*{ÕU2¸Hai©8 $œÜ´$À Ë´–¦rzè°—O8ž³ˆk’5k!‰Tˆ„F£¢Ãø¢ÃduÕX›Ñ`‹Õ5`|a%‘÷tXô“UM£  Ô&ÉÞ`³‚(î2Y-ÌÂf…qK`õ&Fû«Hp T¤Q%Ênf««¨J0ª·dÂÄj,ù¾ñaÔt´¥ ÑzÆÅ%Ö 5Ècb‹9 ÀÄøÐE ²[y 9–m ¬gôœx…âì„n%•h¸ZƒêÚ¾ª¨6tY®0*ˆúÐdº2ئÕÊU«LXJ)W®&ašÀŠ7® \6’µPÇ|µ>…ÁÍ6†5þ%<}_Øo k–Rrm[XðW %óÚú¶`°Âfø¹¶ïgï » KÐôöê·okôò Z–¤rX7 Ó³M@ û²NŒ F,Œ>’¡8Äq3#®¼Ëæ½8‚X+òعàÌ FýŸëUÁ÷–:V¯ú_ZÃEÉ!q‰Cw„š¼D¸.;?ÜØâBÚÞI¶ÏYY„² ² - …¬Ò´•LÓh¡Ø¥¶%l¥¬Á‘‘ò´Ó±•°…”«F B˜S€ÐÅß]‚ìêmŒzÐÅîV5vag@l¾†¨¬.(@X©)èÙCÝà_O,­T䇥&Q/ùlB©ÒªumS^ÃV %†íZÄ„a¶Û¾³Iær ²“î. ‡çµB4L²Ilû{ ¸Ê¦TN²j­‚(–Zû3d2®¡›mÞ`”\šíõÃ%Zw,³V\Xèëßœd׊uÈ®•qÉO:o•*JN²l!b2åKî2mEi#¹'éÜk1€L$(jÈ-ÛædÜZShÒïA¾ø J Sëjš—KøSØË5a¾²>”KhììÌOü¾æ³w¬!P=»KræUÃÑÒŘºì[qmºfßZháÂ.ÓÚ~¤QØœµÝ½Áï9m Ú¸NRMÂ'2°›4P¹VÉà.ŠYC†®G´¦¸ÏÞý •”cåZbVV®5œB%zÇÌÕÍ\óÂÌÕš™¹þâÏþ3õŸýµ¿ùë¿ù×~Û×ýè7ÿÈßýúOÿ _û-_ßÿÒçÿÕoÿóïgþÇ?øKßûê{?ó¾öÍÿõáW?úðç>úé_þåŸûÜOüåû¹oøÃ?ö³¿åù¾ÿÏý×_øþÏ}ãü•ð“¿î7|ß÷ýз}ög>üà‹~ôÅð»ÿÞõó?ÿ…ÿðÏá/ÿäß 㟫ÿÓ>ýgò'?ó¹ßðoüÀ÷ÿìï-?ó5O¿êc­cÑìWcÈê½]G'X £Y´–¦!³h9Ì‹!^xÉË›ÚØ„»cò&öNß¾ñ’õŒnk^Ò²n”­ÉZÔ„÷éðÛ7>./yyã#÷Ÿ™7é°wz³–fBGIsëyo—ÄPè"±3ÐkGöšuBŽÛoš¹yÉB .SЭ•À9FhS›{¯oßxÉŦä%mêÜÛÄ9±e½: ´hd^´hì^âsó6ö^…–OPò€’1‹5:/§¹¤Ì{tÏ — †‡øƒàŽ$.ƒ›æÙ¸/ñ',‘Ž -ÈFç_=îW[®t QûƒÎ!t Ù%˜ ®£ë?Bô•Y›4&‰oqI^gb?pÁOõ‹èµ¡ó"m$Í(諶0Hž¦rÁØv‰Aw_8¼ì^”fÞ)ë“«`%á‘+.üÛÒð†nUÖa‹£óß6¼xýbР‹\-ÐQO &ÈŸòw€Cÿ°v8øcMQVF7¬Åd‹ð¨ôÇ‚ C¨Ñ¡¢À¤”àܲ(‡tZåÝb´ ‚¿›—ÏÇÌ…Wóg/HÃȺ-i†Ë&:®´EGs‘r„Ã~¯-Õ®åûÓXƒ{¿Að?@ fÒ.­‹ƒj⌼ ò"~Òçé5¤Ê¼cÇV "i g}H$U?[”‘‹À"N3   {T~ê¸lÆ|ÖšŽ¥Sà3uóƒ>»œÖ0S W¢üs‘} îµXKØ,qq?ukØyßØ×z¶¶ÁUÞžà9¯õj!<ÊÃÁ$Ô·‚i“¯/*g#ŠÔÿÿþ=r½öºÇ~µFQéXÚæûÞ*á1o,­ . /op!T; p:°‘-LK§Åå­Ã¸Áìâå]£­ßIÜÎßMö¬ÁûÖA‡¥A:Fáò¼ùTî¾+½¯ÆåwVèרº½ÇúÜ0ü¶’®¿­÷¼XY0ó)§™ÞuQë0úô¾Ú5FáPw ž”B𰸫dÔȼ\¹À dýFj}Ú‚LNÝÁ¹ÊÍ 4 •4Þ £;` T—ä!Ú‚C¦û•— )ÈwyᎿa/¾P æ ÁøÂ9MÁFUIœ¸€Xø‡ßܯp-\¸)õuvû/ª×y?ÈDü½díXŠ|6zã9hdn?½Û¾’íÜD׌²ÿŒË‚B”?†ÌêÕ G \T— «!6ôýX“owócÂò†AÏÚå"½8Ftc÷çaPÚDº7 ÕmÔ¢…œ¼éÀx(2&Mj:`÷]aÅ!<ñ)~¶J†BÅÁI²n-.H‰70˜†°Ö$‡¹yyjÄ’ìä¸9M´ohËvŒŸú°ÉöÑ Ù˜ÀOíŽh'd˜¼[¶{G¸Ÿ0ø ñá—KuÜ]aLÜûWó¶õ³ ü^‹þ÷ÚHåâÅ îX»ë ˜®`4Þ'‹×xÕ5oÍPÅ9™|A!ib0|DD­ÿ=îduUÖ/Û‹ 2© ß&]†»Ô¥ƒ–SÂ/k³é?BŽ9ó©9ͤš$üð÷Æ ƒAÉ4zµ=àM:Ða^èú²šäøiò­hò?=‘swÖ`tïS¿…"êŠÁÍ—zP2Gˆã7Žv uc:r½µ”¥²!Ô_pf/¶6~bï…4x1ÐÔÜ=c ¶ŸÀ›t‘ÿÙpþw[&ì®@l¡4„OØ&°VýÁ‡_þÒW¿òþ¿ÿéÏ° ñóÓ_üeëÏ_üü_úèKßöå¯|ùó_þüþOô§¿üK¿’ãU‚¿”Ò†B"w <¾á…ÒtÌOmQ5þ­Y!Y¿}“‚nx¼dóÔí—D¨ý´¹aëu¡ÚK~KóÔ.Á±mx›ˆÁBoÞ«Ák>2+yy³ÇîßøÜ¬Í [¯Û¸”Z—ÛâRc¼Kš£gÈÑÎÈœJWäšÁkJðÿŽ§Sj6 •D¨¸ý´¹aëuµá%yš5f—$³ôy›v»º{5x¡¥ØÂíû×=v+Ùs³67l½î`ÚOÐòˆ–󻂃vÎk°±‘ا–t"ørƒ|熸@ì,kK^%š†¥ÊïJ`QÄ‹ƒ™×W»K°-¸â’n÷Rè+KöòFD„~´þ.H]8BýÁ<ñ9´Ʋ£¯% Ð80,‚³Êï*Nx£ŸiŸv1i¼(‰pÉø{+29­…)D¶•¼œ°sЀ쫻„:©"Zq5Ûh_X`Â5¨Fe€²BéÑÇæµMÀçºâÓ œ7úpRÍþ·µê¿ q<'o6W³Ýü®à! 'ŸºÎUð»‚+OÙ…Ï~Rq1¿«M**q¿+l¬ð« ñ£ Þ;£|¹Àèn‹ôœFýH°óÏ™¾: Îw‰ê‚Õ«ò»”¹O³™µŸ’ˆàwå!S~W»$éëŽö]PõQ‚%¢#ø]­=Üè¨:P¦ù] \T"¿+ Z~×5A˜1B±³SÖÆ׋j»ktŽÇ’Å$’ö¬‘¹ÒEþê ¦¢ERX¼É[}‡ñŤä®ÄBn #Þ‡ü®N ãŽÐæ&t†Q`NcÀ‹pWXlYùýÔZ:a„z™¨Ò¢##|–~WK€Mºn–<åw•à`T»J–¹à͆p Ì»X‡1øYLx `§HPPd§2p6ù] ¬Š"Hpâi6§5\¹a|œ}O±‘w󫢎 5ˆOIÀ}c‚ãYèlÝža³ ¿«Sq9éjaÃ]~W»«‹EÂmj‹¢ ÐEÄgX ¼S´4ÓC‡u¸|: L/> èÔì.$‘ ‘w£¶a|låªÃ0k$ø]Xæ*)ÃüÐÙË ‹ÎbæÅüaÆÞ ü®¸3áb”ˆ[" ŠÑ,ñW5@‚k^ è‚–²›ÙêÊv(ÁDp1ab5ๆ¶ž” Z_%Œéd ò_gœùi`DÛÓv3h³ñ‹B!% Ž k[GPhÜì„n%•èw•pgÎí«ˆjÍËŒ£‚\?D¼Á6­V®%˜ÀÀ½I,FpM´e­xãÚÐ}ÈF²êø]¥g®½1,yòÜ÷¾àÐÞ’„ìm!a®àJ DÀÞîm!]Xa3½œmÁú9»‚hH ê‡ß{;€?òtµ-¹ZÁn¤VT±‡ DÏêKIqb¢åp&'¦*?õÃŒ© Mâ=8J‹µ`´`ùŒúð¦»*ô®;BgûÍ1¾8„ØU ¿k¯ÇÜ°¬“DÔA“—79j{ nlå5ß;×dr¨YY‚6²:²r W‘FÎ '3 Y4”¬žMÛ¶rÔÆàÈÈ)jçÜØ¢N¹jP3C¬Û0ÀХߎ.AYH@£tÁåAÕðÃN‡Ø| QYMy-oñ¦($¨dÓ°ñDW%Q†£&囩½ Áó(ô{›Úˆð¶bØœá aB˜M³“cP1HcSN æ’twP€yí„péŸÜ$Ň³¿÷ ¡@y±Rdåâ„%ÆŠÄ;©£DR4ʽ^0ŽBëà•ïº[p~&•ÃÑ-2X_á«À4„…¾gz=E,oð À¨ ù×|yÄbÔ¢1JÊ÷{J²­÷‚õû8MM‰üÐ1U`¨zÐ*ò,Ôör-I²õq@l}»ÎLOü¾æ³w”Èà†kw@ìóªáh—§×šÔÐœ—¼2ƒWB’µŠZ¦ÐL£°9évoð{N[@¶“ùPcš„/¶32 ”hÞaéšµxIj ¤aªK¥Éë*i—Í«o›Ô<`µ}œÑ«ÿýº½~êw~êÃ/|ñÃ/þµŸáÿ¾ü?ÿ/ÿÛ_÷Á7ýä‡ï}áÃOþ3Ÿÿ#_øìgþƒ?øàƒ/~úÓŸýìÏ|éCüúðƒ/~é£÷?øè‹}ø•?ö'?úù/~éoüðþé/ý¹¿õïüÜüØßÍß÷Í?÷…OîsŸûð×|ã{?ðcö×ý†ßò#ßûÛ~õ×ü¶·„!”GÙ‹UõÞ)îÇØ­Àcr ˜e2XŠ°Ül²9Y%wȲ’H÷ªÓ憃§¦ó’1ÝËÊKúK”·ÙÌSË{uxÃFæ%ˆ5ÒØ÷76·Ý¦ÁÞ뱄 º€ÀœëB/‰¼…MF=xr-J’ä0µ]}a%<Å* —•D:67l½-*A¸¥ÙUû2S¦Y“ã¦YG}œ(ªÏ ª§qû6­ÝžÁÖ!ò 2gù‚C|ÎH’Õi·¨Œa!ørƒ2c4ž¦q¸ŽôpFãÍ¡[Ä!AäAPÄ!À9uCÈ#2LúSWÆÞ ˜äbuJ¸éG&»z¢Í!†â[\€-¸±#eüö1ðd°v‹6Œ‰Ñ†«¤ñH™«H÷=™‡EÆ FŇ}¼$!%ó´:%ðÿ¥f³¿ºJmÈ«t£ìW‘v–êƒàƒ„¢ <§FeÀZè8È1Ú€hÌþ7\Hâ»&#Ge´a®dõ©à.$Z½¢R`ñv :Dd¬ûŠ¬^N&VâV¯¤è±U\xòR *‚/؇oâà†¬['ŒlòF§RÐìŠÞ@Ü Ê<‘¸®g^¥ÂšSwôÞ÷†­µ—p©³_½©6ÏNº§šrÁZ`UýŽˆó—ÉK ,`M_lRèZÙ5¦}Jæåï0¾Î 5¼j0Ô³ÆÁ3)éA&¯¤„X!dP¦’2b‘ŽÕK†:̃C O 弊\tàÌäuJ¤š$¦ÅâZvÁPC‡9 „€ ‰¡†¼™ÅBnªh·WÖšëPqÈfòÊf5gö9 „Ô®h“¹ò2p Ìs¸ÃPVïX‘@—uÌ5Ë@ã%uD}< àÌfsJ:s鶹¹¢,õÔH0eîLÈuàüôè%•.ö n0y-ò‘i1 ª»óô‘`ò:5&ÇzZØð4“×.iImÕ( âA[Øg¶¥áôØa[80Ù™~ð™Ý…$Rš*ÖÉaMá(wÕ€ý¹éž–ivÖ€íØÈ’â©CÑËÄ$p´ž&(•wÙ`ÿ´è ¾Ä´¡ o^GÌUIaF× ‚¹h„äHZ’(‚eãÐi/nÇt¦Kò¿ç4Á­ÞSyì"7Ù»r¢VGÔÅpóï3C`¯ö1çtþ^)¦yF$„…Ðã¸i¡S $Y»r´ ‚Àlg fxLô‹ „€dÖ®Ì\*§FƒuW À·ÙqXí´va±I[™FÉZ£ËÚ…RÙBFlÁÞÚÛAî6vÛÌ€þZìí@ otÉñíÍôr¶õsí^@ñ_b{ü¹·d˜œ¦Kèx|úÀî³NÒ]¾²Þ(,Ì“õD?^FDsDÙLX¢p$ž+Ê“E×bè0wñ¹^²í)u:À¼Ôö›c|„áZ‡•- Sãa¹±ní!¦Gaâ:˜‚ÑCû%ïcZ¾0Õò)BS SJ—ELÉ`ÍøBbJÖ˜Â|YU½j7pLè†èFÕ`|á©1ƒpÅ£6Ão\Mløòâb£\!FðUV@Ü %d~ 4Œ-D3Ù Bì>\’ÁQÍȯIZQUƬ½í¥Ìº6¦¯ÑMíQ¶ %ÍŠoLËͬ‘톺\ dÞ_ß]¤dMZ %ÍZpÐÝ„q}»=¹‚>0®h®\‰¹ùªvdèYu6 ”d ÝvwsæJHµžï9Zé G‹ogN†ˆ[Y¹j3ç+„MÀ–ÔŠôí¤{À{ U™¦DRá{¢ì‚\ `†q+˜˜hQÉ63¹êìj~00;!ƒf¾ôäà zÄ:ši×÷ j­ Ì~OºKì*º2M¥oµ3^ïl)ÙMvã 6àqµfdL·K× 1@lýÖšt›P“ ïç{B{ÇG¶Êy×ð°¶.ó2“ŠiÁ,\umèÜ7‚U\p=•0ù¼šS×))çÕ……ªâ‘_Ù­«ý#EþÔ_þâþgþ×ÿäë~ô›ÿãÿóÛ¾íëþöö|þWã/þÈýæ_þôþíÿýÿÂúÒ¯ÿÌŸÿÙÿæÿ£þÑç¿úÙ¯¾ÿã?ý÷ü§á[ÿ½¿þü ßÿSÿô¯ú©_õæ¤ßõ×þþ_ýå¿ÿWü¯ß¿õüëÍ÷ÿÔwãoü]¿é¿ý;¿÷ý/¿ÿÑŸúè ÿàßüw?ûÑg?zÿóïåý¯|æŸúš_+[ \ͳ¦w³oîU¿"h†)/¨b`„S0}s–×L÷,ìiØßóîUL¸iA~ïÁe[¹‚Ȇg“„úBSÄè–¼=scÖq&„i°¥¸­åCÖúTÝж/kÞ:ßó&"Ç(½’²Ùob«òù)ÃòDËOg•t%öO w´uË_Ÿå¦¶šBÄX®Ò1±Ód!r eÆÁMK¤çƒ9›­%K£-JÌ6Dú°ûl®KaxšrœèW-:1$•#"J[sC(6K†Ù¤”O*f¥#£M²s–˜ý{ä†*{Õ´iEó¿[’Ûð-r4m®àV°Ò΀ººYª/²ó-½„yûBåT[Ó;¿]3­í¡F¬öE¬ÚÍ[³÷ÊžB›* r6\ýöRT"Ÿ,i³w²»,!iõttÀ¶u›šaQ—M™YHÀY4‘å–y ªiú{ì{‘×öm©¥¶eù¡•xÎm€Uí1ÆÞ|5|f6é> 7=ÇÞ|@^2”pìW„÷û ÛmdF47Î(²è­)ÈQ3v9k` JRiäîs"¯‘’'CS‚ýh9ô4øÎË8–4…m@aZ¦¥Ô#‡6:.‡q˜“(Ú‹Ì·Ž¢òàLÁÄF:Ïû)a‹yN§×=€O3·aiy%É7’µºVsª¤û3k³‰žì€ê«™$òȾâI¶ÔŒàL3iY_£9ƒƒÉ3ÙWqjYOh¿N;QVÛ«¯Å¢Ê=žˆX¹‡1GÛkϼb³¾öÜc;~®:­ºß®·S§Kï«Žòj<&®1×ì-û¼Js¹ãs7n¼ðSJy…ÃSÇñ¼ÛÙk±ûÚëµÇ³×ty¯ûž×¦=w¿3©Áž(NFL¯ë×æ>cxÍq=mŠwçÝÎ^‹Ý×^¯=ž½¦GnøºïyÚؚλôóQ£JÈZ3,#`GRÆßÁ %‰†e¢…î£\‚1–¦8銺`–Â-Ç †N"«åÃo¦½ˆaîI­À\T­êþôÀfG½J¦"(p‘€" ù‚2³¼ö¥6«Ÿ™¿ %cxŸš½³¨ÒØWŠìc ÍWë@G³pDf%Ì×>"Ô3ŒڼиJŠ:á° ‚êÍ7£h¨ä©F‰ýïðÔ{bäI‡#øP×°RAGcGpŸ7\`ß{ûæ*IÏöV—±“³­˜#>HQk ÏQb¤G"–é-¹à¢E©¶:ƒí¥vPË‹æËxÔ‚÷4˜ m%4œèÞÈŽÒ"¬ÔÆæ%ôÚ‹ÌSA¸ ÿ§ ³i[I¯1²†éšÍÁpð©9Oቜ"^§tÀ+šJ–Þ$8ÄŸŠø9[ƒ I ¶UŠwXMºÅ§èd#ÿÁ7lüÚaŠöh1®žœÀÙ…*Ä hæÿyJp?Ï™TÍ,‹'õVúÏI 1ŠÆÌç7VµìÃèŠØë>âºñ-­F31Ù«i¯ÁÌÔ«qèÞdQÚ ½‹ÃßT1”ìte¸×ð;Yìz<¨š%K¡Šª'ƒù$#y,|§Œ<`Û.òòE›•$^\óÄ:2‘x».G6 Ó€…¼yI‹£¸´êpVÅ¢$ïQ+ß»,CNâÛê„sB”eyŶq@AØÚ±yXÀw@ò)ú€ ãæÜoÊM¸¿`&hûæ*©¢¸¢Tˆl#Ì\Hk¯rÛ±ƒnv,×ýjû``VÄ‚7Ç"}S8<¾Æ_ó¸ Š7#õæqµ^Žª-¥Í½"Ü:ÛFè”mg× Ë7§½¬Ià 4î†SoÑZ%~hd³g*Sôóxæ;ÇæË/[ËxëS´ WMª:Áà㶭ËEË°%;\;ý(QËd¢‡mr£Kj¾ÝÓ•<˜í¥‹oGqB!Ÿt™Éø˜äPœo¹É¿™þºÉ?ì^#G Ä p_åE< {++ÙÛp°æÑŸ¿ˆ²Î¾ŒH6|FO§)–oþÛsŸ9˜…‚õݘ’¿ ´ävºàtœÒAZOŠ=¦«1â››ôWI!½M #ć£­Ѷ)ŽíóKoe¸w7íØœ®Åú‹iZæpëaCO\Œ©Õµ™6³ôÄ]»æm÷ÓžÌâ ¶cLn©‹ú­€xýÖž—Š±[NêOHðVqíufå–ÎAhø®¶5䨕G::.5¨´ÚñYÑKVOþ§žD™q¡©›\Í͵ҧ˜múù >&0·3v6&-æª?ÅÄ\ÅiÇÌfNÞÉÕÚ47ijÓ?‡Jà0ˆh¸ˆT­‚+˜…çYh©ãѤ&»±6û©sÌäx`XÇ…ªð3‚xC4­¿‘ø¶ýž~H3°Êõ_iMI\ä […eˆd«š•åL(¦3ÊûG,PaŒ¿6™@HÐ5—Z%c°´æÄ*И¥'iI•‡Ô4_$<6ÖjGgj$cENCt!jÓKö· =‰’€@9YV'bz~’DÂM£{÷KÕ%£Ð,¼>ÓT˜°}ý®A“^ò˜ƒ]PÚ°énPÏ›³Dö- ­œ;ùW‘3Pûj/{dzøUZ–³ß3/:õ•Ã¾ªŽ ÖtG-8¶U]òî:3+@ö´3£99ù€íáà>‡Q¶{È­êå„3­^“•øÔ›eßvô\uFµ›áÝNŸæ.¸ûêÃ\Ûl8‰‡¨{Ä©gkØgµVm<Î<ñzæÆNjůf ƒWÃòÕŽ­ÄéËWëŒg¯èò^õ=­M{êþD•£$ß Ëú7Ç&"¹ùåPœˆ²|ø ˜ Ë{;™'ëyÝsYˆºQ,V⯈ÒsíLûjN'¯3º—x;šU¼úêæh¸‡IN¿Ø=ä:›SžM«M'"ŸzµD¬Žž»Ž;;y; ·†mï+âDŒˆ†-š8õi û¬R÷ü‹>óÔýþÚ±“ ÓåƒWÃòiÇWâôå«uÆã+z†ì«~¦u(#" ŸÑ'DôED¯©çúê” § ñG¢Y_Í),Û¼®¾äººÆlþò1u{o::Í™ôÒœ.-–<õí¦¹1æŽZsê•”SgXÍÝÌðW«½'=´µøh ½h‹ò·ì‹î³‚:.âñ™oRÙØ¡…îÞä½™rñMU]:õáäèþ½6b>Éد9ñÁ°xO›‘ÆGVëc³£ùkï:†âÓŽ/ÃéÊ—êŒÆ—ó¶ägV‡,¶zó.é¼C^ÛÇ7¦x¨ ‡äcƒè ”HHD ¯`Ò”uoÈRÂwƒ™º¾X}zV_ Ñ—W?‰U\„Ç©6”…Þš¤hƒÉîNºñŒKBnq€™/‘ðâ ú™é×Y2†õ¨aå &üðUÆ= ç9–‘¥q¶öRIr%>0è)ìW‰úа„¶?)ó¢ÜkmׇA…wAVÆ£#ª{$rÁ;c*¹ûÊU‚ó}€´´z~d…|Asš.e\Ø<å__ndO–½¢E™z—yÅm/o„a+ø‘͘…Ó–7 >6Ò†:IJæq xTóÛÊQà0ÒÉv}À×'`AŸî&5pÁ…ŒmSv`Þ‰ÚKxœ€6Í(]¦‘Ç5!BÔ˜Ìjs8e2ËòÈŠ°#ÿPÜé®Á¡˜„í·]Í‹©ÐŽu,ÚB2QÂ¥ÑZ1#×áÉý;_àcÔt«™vÐ4y€zá“BÍ WÒ"ÀA³ìlôªqIô“Ý*ðãʨFýV¦6¼Ö0ÅÿäƒÊW)øŽ82a 5&qÌà;‹­ UXGP\^[Sf²¢øˆ9+Œ¿‘å‰ÕÀüœDn³ „ùâ½q}B|°ÉÖÒÄv*ŒjbLˆ&A†;ÓðR4¬É Øܸh‚oÒëŸê {’`—èŽ4«Bþ›ÕùÏ ?“™€£h±0¢(š.ðV|ÀÓñçTÁq†ñè·¯!¹õ¡{F[bW]óÎæd@sR! å6pÙÂ_!f¿uÍ–‘ ²ýÃ` eÜi,"Æ¢ YÒÄpO†]ÒõÌDLzñîXŒÔ•- 0cŒ7lf°«$(N6ÒPœDO̶ƒ«Ý íEÇfÀëÁI;UÂ÷^H“EÍCFFc}¦Ð8`§³’ÃøõdöEÎ@¥ ˆ2æ ]^\p7GS"ÏÅ6V)$x}4=KeÄ;îÕ¤C¤–ó'sNp¡£û¹¡ò‹j)*.FA†ÜÃÉŒ…º+è’Çèp3ú)‘÷£jË–0LpÆ%ƒbÐ#®§FÖ­´DíóšQ·mugv½#ŸÍ‘§‘4T˜{nÓ4Ï0À¨{£Â<Ñ+8•Â4Ã3!¯DñbÚë£ h0ŸÒ}“1æšhQð[Ñø+M*N½`¾Eöäoeˆ¡ñgïÞWªi-KqêOS3”çLÈÊwÿ‚Y´Ð²9Òàš^%F-% ïýÌÿ©sy”[ãÅåQöÍÃå³.í5—{‰qùÌ\nvÿÍåÞ\¾KŒË•Ìêp¹²ªo.g²‚q19È`­Ää &¿¸<Ýy‹É7$¦æExy4Ÿõ‘Çg~äñ oÚ%ÆãäáñÙ_ñ¸tšÃã;Û%Êáñ(×ÑÍã1´úòâq<ËyW¨åÇ7¼y|—ˆÇ#Ÿ§<Œô_<õÚñ©¡ë”ÍãÑ®Éo§±ðÇ£Ý8G»ÌtüÈãŒå»x<òr}óx´tô‡Ç£90Ç£œý7 #¡Ü#ƒÆ]!>ðø†7Ÿ&¨K<Žöy<ÊÙy<*©ó8|Wy<ÆñÀãð_¸yüN7[Zë™7ª§m­Ù=NaGâàä#ã0µ< ^c0CpWàyŒïp;ÍÑß@&½Âg:ÌQk‹¸þå˜sôYÎnB¦èR.â—ÎZ»2Ÿ›HŠºw¾DÒ.‘HÂ]x¹À®mx²ó®«¨Úðv>ðÌ.ÁšYÄn‹@x÷mh³BcúØ} ]6?¹—~ò“¯q:y TÞ6Œ;]|îo˜×Ì[ŒaÄM>‰)؆£Ã¸nÊË›Q!% ÝF««(sä8à¡&ÉüŒ‹0éùŽ 5¢œ ×P/Øß®ùiÛ€OC  QdËÃX˜“å‘–MZÆ;ÑèQq36.ÂÄ›(Û)7YF¼]£™1©I pÒM×Ù•Î"Ú“ éåœ$"ªw£ÝêA 0*’ÞtQ¶`c`J=™¼(Ÿ6Õ˜=óØbáïéÌv«ÊyÚRõä# qñ+Î)•J“+OD¶B6P³wQtË^ÿì:Cñ#)Å­°hz×ÏêÓ ¸o¿è™f1$ó!³m7r÷>°ë§„L˜ì¹ z;FkÅ=¢“²p:Fd^0ä€C}v«ÛÃ*Nˆi“¶~›}=Am1™¹·Êdú³y+#›a7ì+­³o„¶`Ø°dùî´—5I1œ@ÛýpZ‹Ö*ñCÓ w°ü81]ú¾ht²­P{ˆL“ÚFì‡÷sÐÇm[—‰Üå–sl~”°XÌ'¾#\d†ÙâŽ#ÍRÌÖ2ó˜T'-Æ›!Á:wÿµ `.Ng"îœMÝ䟣 v¯Á×?¸¯¢*!é1©åhQÕs(L»R´äÉ*k$Y)Em,T-üwr”O³›ÌßgfZ¦A›Ññ~¹hñÑòÇóËÞpìçÜJ’Ç¿[ª+FôÙu¬e=?ub´’ÝNÐÅìékr`ñßß1ójE0Û¼fÖc½gî#({Tó[ÝS%úí§7Sëx¼!]%î7ãÃ);9¹L¿ôiánùqêÅ3%mô”0_¡ðÔq4Ÿv|)N_¾\g<¾¤{Ì{Ù÷¼iIJOOøÿ¡¹6éò<ö—¾’¢§¢ªãØY š¯þØnͨh;h!OdenûMEÖ×}_l«æ,Æn4³ë0»âC;!mï«éTäã™Ù–v¹[þ=¯Ñ»Ó•ÍÝ.Æ=W•Ö “»™Š¼«æi9öpêöˆò!×ê+ëÓ‚¯ÔãÔkίÐSö³«ŽÂSÇÑ|Úñ¥8}ùrñø’î1ïeßóÚ¤±çî®4ŸPÑ'TôNE¯Éçúê”4¡7¶í²Ñì•–v!›×éËw­¿¸ßU‘;Gj%ö CÝ„™•z-Ö.hcl»lD¹™\uB3©»Û –zn÷}Çö÷É©¶Mùq7®e÷iMyAž™oZÙØ¡ŽÊØân¦{Š!ïiÓéÌhãÕ€ÇÞJ|Rs£Ô'><3æᶼ½` §Ž#ù´ã qúòÅ:ãñ=2Ã}OkÆÑqÞ%žwìd¬ÁÝt.‹òåÅ”JÚ0oùÅ’[í­H n]‡pa¬{õÊ;r«<þj»ŽŒMöH¦1W«Í^ü0xxþ)Éê·Ód ÇÞÉÀwxÈ.꺌@m˜O ûäЦ3q=¯,"öEo&5øî‡NrÝì0ýcÜæ23â.±N8,‡ˆ¨7—¥Vnþw˜¡`"|,¦Á¥†ãbI#ÿL—š·áWÆ»9€–'‰+}ø!A1â"¢|dDjÓ\jpª€K ŽÎS‹‚ûûE%¸Ï·¥¾@úKÍl+ø‘Û֚ኞ-%øÈ”ÕxC¿¡a.5§€KNË8×- Ìš¤ Óžô‚‰ˆî3ªÅUĪÒ̆yù¹øíö¨áþSÚV®$2ì\tÛ°™Lø•‘Åa³‘ƒ"O ƒ>5¸aÁÀfMWë܈«ÑBpAu 1sª¡õ§*ð»rÕð™TT–WM„Ëé±D™Ññöcö¡—¬~«›+¦žò°71‘P7,”춮Jl^ÀðÍÜe¿pØ®ê¸^#Ó`ÄݯÙ`0xp¤qS‘í\Nziœ nÎ52&%ÿ7»†©²Pl«ï=š\ÃÕ—“‚çªA‹äÔ,÷^#RXî‹Æfê ˜{Í)IʸèÉÄÅ•½§NÎ=ùm[ ó°Û›Lsg,ìùˆ=û.*s»j8ê8'{-NåøG`pD¿›l¢¢ð+ÊAº2ÜkøÙRz@ϾÍ”kIVR,†*ùVt×e9WÖcw]^â·xB5²RAÅ{K×ïvãÂ)Ñõ{Ô«åÑâÜÌ«IÄ[JIÓª_¿GÛZÑÍmPMÇk,‚YD%(ë& È"û,Y“™òú=ÚZ0Ça»á}½»KdÃd¸ÜµØMÑØš_¿§`{µ]¨nX6xƯº_¿§`û¦›å-‹”sl’óèÅÓˆÛ¼+T“-•Ã–nv|+É´÷ \ð7ÈtM¶Ú‰—íª!#,S¸iLuç0óë÷$ prá™UÕÓ3%»± G¨_¿ÃnÑ)8^ÉÅf$”ˆÊ]ÉnfìÚ‰JÖ¨Œnz¶QrGqø­èa\‚íH]×ï~ý~Jp™¼{_)ÓT¶u4í,s\! ˆ(‰S ×2ÀqøÉJŒZäö-%Ékœî{ðGOýðxê¯y|—ˆßRäñÔyüÀûÚ¡?ò8CoOý§úŠÇáÞ~ñ8®¹nǵØáq‡Œ©Ç#g„îÅã|#éâñoê<žú+¯y|¼âññŠÇÇ;<>^ñø|Åãó5çøÀã9?òxίy|—d³é>òxN¯y¯AÝ<žÃ+ŸïòxŽ¯y<ÇGÏñ‘Ç?ò8¯.G›çðšÇs¸y|¾âñùG¯x|¼ÃããæññŠÇç;<>y|>òø|Íã9<ò8ž´ºyüN7Úþ©™ªGÐTwR7f oRWx— ÛÎÈïaÏÕ¨¤ç»B³\l p?…ìÕãý3:Î÷åqÇݯÁe2ûº®ëõÍŽ÷lrÓÓ3&’rM¦D»HÚ%6³š¥‡;8Lõiºâ"af)iÞƒÙ%ºíÁÙg®DÊÈJ(viZ¹Ò=äœJs±ù »B¡EdØ•î.6Úu##ï7Ÿ£«|øÞ`^’ ë5hê㜜òÆùiH\ׇäó0ä]&vX€ÕÀ‰T.6¸6/.ŠüŒ‹PéB“»Ž¹†U”hÇ#Sü´m`Oƒ )fÏúXÆêÄ Û]6M›´\”€Ç2¬^ëaâ'Q¶Sn1¼S#kIàæ`€“®Ú‹øX¹éá˜^çiº‹MQ枸tvÅÛ^¤7å*Zpcidw±XtøASýˆÙ=#v‹å¦Ü5Š¥ƒ-r±ÁÓéÑ´z¹Ø­Ýžb-¢ê.×ýX,§¨å/Å&iÀ‹r±ÙuŠdQ‘‹'‡ÍíešL.æb³ ²¹ØeæŽPÕ‚¶ívá”p¸E”‡1ŠAžB‚»Ød9í:F<†žÎ9=ëxJÓÛ&…šU«D_Qí=%ùzrg)R"ÏVY¤?w…zñ-šnÙW„[gÞ-Õ°á5LÜö\ÒˆáÚî‡gåkÑZ%~¨ÝÅ2òp,¦9w±)ÙT!åX°(sr »‹6*œŠË-x¡¢”[ø”êj†Õh2Ñt3Æ“¿æƒ‹M­–¸Ðņ‘‚"HsÑî_äbƒ+ÊEþH9L°N—›ü‡M¨Ds±d'¸‚M&T á"7@eÒPeŽÃÊ0–oû·»Ø´<ÂøNFQ¹Ø”©'ZÛ¾,Ç3MŽ4L½Ø»ÀM&¿X°wB9ÔòwGºtÀ‚×ÊðWO€»Ø܈(Úïó” ¿¤%cþ ê"<#À³ ØåbSõ&¬Ï´Æn"u×c[ý´gW³µ‚íÀ»5„Eýf–ÿ­Ê,›™Z‚J Õt›¤Éî¿:³ÊšAmT¶5ÈW~[V›ÆKæhªµœLðJaò?1¥¤ÄúÔUI1¸‹MUšC³í-ÐD>'*®u›êŠ/Pô¬1˜8óÃfòB¸pÉæbã¤ÙÝŦÓQÅ0 r¸e(­‘ä &ÞnÒŸEꕳ—½Ø›½c&—·éÄDœjVMºÕ¦i’+^÷ÄQ'úïa Xo4]lðpc²SPÚ­ª‚\lÊÔþÚäRùˆê1•L=û{¢kA‚‰‹I.6¸‹ÀärEöOq"E[Mt °Â€n:»P#+r¢ Q›¸C£Ý5ÈÅÆw±ˆû3OØæ‚í4zv?<ë£s‘F»Ç|¦7*>ÞÅf©Ôz^­y®åªv&ƒY?[fØýf07]ûòù‡¬Ý¡ž‹å\í:lxþ˜¥~g» ³›Á\¬¯áyhr–_Hœž«&ë3>Ôñ‡µN;ÑÞMÛ})hãaíøZœ¾|½Îx|M÷˜÷ºŸy9m´WÙj˜ w–žh$Ã6"¢Ùd侞7`¸ªÝÅn2òå÷ÌÙÞ9TRx•4##O’³õ5=‰HNÍÚñD#9N#š]Xñ¡ §O_ ¯Õ{äyå0:qŸ×H0f+‹žÆÆ@å±ýó IÓkŽÊƒë0›6ê×0‹›=?ÆÁÄvÙ 3mËÔL¬–(àTx.1ï Ï%Y3†­]øy2®R¼k˜-µ3õ˜!úd³a‹æ÷,°˜Ò®ûav¡ õÌÝæ”(›MFÔ´,ÝâÉh6ÿƘïL7»6FÈ0_ñø|ÅãÈ`ðÀãÈ+pñ8€nG(øáq‡ÄÔð_¸x|ƒÆãóÏW<>ßáñùŠÇç+Ÿ¯y|¾âñùŠÇçkGxèÍã9<òx¯y<çÏõ‘Ç7¼y|—ˆÇsyäq„P>ò8bnÏñ‘Çבá_ëôŠÇs~äñœyð##¸óæq´yñxN¯yÔ¾yNB7Ã;ç‘ÇAã®ðÈãÞ<~J2þüÈãhÿ‘DZVc@çøšÇs|äqDÃÞ<þ §›Ç§Ýäj»‘îžÑf•˜Î Œ69¹Uobfs$êž$g%:ò“.ÀûÌgÁA\Ùñ³fWü°Ý»‡ËŠ¹YùÕ]Æ 9ÝmS®ôôHÊ­›í"i—H$e»ËtÐò%uvÞí0¢›Í ÞƒÙ%P¼3ènCÏÜœÍÓühZ™—¥×Ù47÷ ЃUYJaÔ‚ùIÃÈS t4Œ;]|nN4Ý“J“ó––FËîýr æw2Ú,LÊÓdXF›ŒHY¾\ʬN¦t·qÀµyÌhÃÏ’Añ™ùøuËh³úšµþ^pÁ4”ÑÆŸ†@³\UùXÆêÄ\”цš6i¹(£ e±¥Ûd„Yº…0lÊ-m<Öhf¡hyNºå:ÍòÃi.`’¢Œ6¥Zþ¢Œ6îd·ÊÖyõС͵ÍÕ «Ñe¢Áù» 3àxðñ†²šËë’ýMÄã«ó*@Bªõc‰/v¶ïÕÿ õþª[äÜÏŒêÏöàÓù¦ïÜJ›sj0#÷Ç–èPt4àûˆÙ;%ç«wû~gx'b>É0°N0ÜHHéémò÷ÿ„]†ÏBá+à^pzèÕSâCËJÓp)L‰t€©>Áð7áQià 8:Þm˜hÁ³/ÈàdÐd¤ $ÝyBìÿÔCÜŒaŠ`Åyãäß‘ÒKFÄátÜù¬ÒR ^ûÉ-8)X53,¯ëitD N%c ÁŒ×σmѪ¥v0hXÞ62Fc¦w†¹€€àËŽ<€ú©¸>¾ÔÓ˜Á¯ ¾ö’¥ËÄQÈJþ„û3uJV‘Df“ÄAqM™#Ô)~¾UÞA<}É?àÕ¸ð+´†Eös‡Ñ[Ôà"\«Í$i0I"ß#·ð5™½4 ¿ç£xG`Ú `ÃdUæw£hy±y0ûŸ¹ˆ0>S¥Ð†lÉ#h€¨Õ3Ó`..›eºãïÈ2sÛ XBad\üS¤­óÅ~½µ”‚åü¹ϸküÚÞ¤Gº[°Å§’ËÖñNí|¯ÈŒ«}È¥´ÿ^e Rùð‚Áy•XZšÞ{Â-ªCŸ †àCÜ9<Üɬ†È½g°M¦¶«2—6Ë”!À÷ÀZZ¸ëÄ},¶rHƒÉq€u›ƒÞ0ïÀ"(ĤK~\%M"<‘NØ=(m›BˆzÙ0…ǵ»†ž)NÍR¼)Z,Ea.z’™™àR½>žå†ébiÆý”ó÷ÈvIN0.‰ŽBæc ¢ °eî"ŠHJ$ÇÙlÊ*jï•DˆÜj…¬SPÝ&yÍ´)E±É0 $‡¾‚$ þW{¡Jþ2Œ‡K™HSoõrUÝ/»¢GqN)=@Ø6HñðGÝ&jïbL vn<§ÆÏt`ˆ‘WC,d;DÉÊ Žƒ8.çi,ºxB+vx¦Øëþw¤cÆ5‡×ÅöÃI03*¿0«id„ƒ)Š;% ÃŽ–xæ “Ì NY qàMÓ;G.å°B¤Z—‚EFÿóâB(ë™$Ù¨Ûô±IG^Ý+ §Á¥"ýÂ$ïlvŒ´íÁõŠ1¸ Üâ ,ágGU@Ú¢:(W<†¦¦~þ3›6Glæ4žÓRá„„–ºåÌá äÕ¤ÂG»0Çè“EupHgxP#'3U¼?¾ªƒä#O¾I{W®ŠÁ×êˆïi;WV¿h¦À@ràœ^ç‚5iCo‰ñ·û|`ìóÁ†y"°T;¯ Ê::„&¶„Ð*FöpÓìöÛF€F+ßõ£&Ív²0%™®4ñ(Þ¸Ú¥o¶-"¦kî‚—]À4ØMüä*€Ñ<U“ Y¶0$ûíãCLDP뇨´U-Z”ÇkáOJ×ÆüÃ4«fç{l0ÑwPZùpŠk^°ŽDže!ìÎH\' ›V̤¸ÑÃ8ÇžzÛ†²m ¸•œô<ÂÕ³Td&Ò"³ó%@WH^ 4í‡VR¼‡Æ IéÉ;â“â\›]@&¾¦­‡‰bœ Ý¬Žrw`©¦—ÄŦvK€™áw¼H.¨ÍõȈoñþ÷8wè6FçNgÁˆ¤#ªêÒÜŠÙƆQ}=á5&=1y-O<«oo^âgÙ¯Ðì—=z‘¨¸*¨õü^Y¸±›Çª„ÄK<ˆ2ìMžsxcÖ͇ÃÛ`Ž*?¼òÃ^ý<‡7äôÃÛèíÞØámðá‡7B~xzðÎg0àtÏp`û>õáðæð9¼YÉ>záÂò>¼!’êñð†ôÎ÷á ~æ÷áÍàsxÛvxi<Þ”­‡ÃÛHõÞÐß}xÛð>¼y‰oèî:¼\o:ßõgÖíðFàÞŸ…݇7Îã:¼!ôuxƒ3ôÃá È÷ám„¼oú½oýð†'n¯ÃÛàÎtöí·£(Â1þ>¼!kåãám`s:‡7Ľ]‡·Ñêãámô|Þø‚¥ÞõÿõáXÒá ¸½o>™×ámäþêð†É܇·…ãsxà‡7B~xp®¼oÄ«Ã_tm.Б£–¼®µtÈú€ÛD=}šÅ„ó p:ÀK tŽvf=Ý::}P†Ã’:ß…\¤ó5)‘â—NW¦ó%@׎^4–Ã[$ô(Rdœf¼YI}Óµ¡#)yÍÔßÁ&xŽ®)Q¿0Îuÿ­ûag T£Nc|q0IRÏ¥jNN–j ŸÈ¨¦vpþ´1×~6¿ÙoLõGLõGLõS}é“™˜Â³¯é.s'¦ü뱎%ùÂÔè Å xÜÅSxbªzA !°5ˆPþÞÈ"xe ÷â?ÿxá FÙ›ªvà _‘û;Ð$¤œ÷ü¯Kš³5[Qit¦Ž,Дœ„œ{£Yc¥Ì:û£Á6"[/œ|î¦ðþN#ɘÔÁÓ3)r+†y/ÍëóJ[ÍÕ| ×ɉ¯ êcjïÎùÞ:åA h×y2áÍ´sžLx/ïœ'ÞҾϓ« Ÿ?ö~'X®ódBøÐužL¡sžLxä{Ÿ'Ãoü<™øPÜ>ObÌû<™ðß}žLH‘{'"™ÒY“Γ ¸Ûõw¤|ÙçIÏyÒ ì<ɯÏy2!,ì>O&óäÆ®'STœÃužLÁÇy’X¹Î“ wJû<¹'ãûø*¨×yrã>OçI–œódÂ[×y’ðÃyò”œó¤n™!—,Îа­â™è5?öûÞü~»JÌÓºf„Gb2çhYm2‡ålË|ã¸A‚d|p–ôÊÅ<\§F;lžf°À©k´ £~“Ñf×(Ó: Ï"R‘=fŽ/2ü{2ŸÀÆ ì,¿ƒŠ­f*AYWÒŒ¤¼à%Np²€uÊ!ÔÕÃyûσ¿ ZJ8Í­±¼1KǪ„ ö‚ÏulH8½-’[ñ1×0ÆIï|¥ÄYÉË.)x¬”GT~UÛCÉòHƒŒO8”[‡m`ã”$<+@Ú"Ì©Ôà’ø_0¾î:@îžF{7 Ds{eà˜l‹,(0íùlpχJl> ÀuLÑ|ød-=!2¾8P—pÀ&òxAã=Å,Õç”n C&†Wj£ Éùt*tuÁMA2 HÌÌ…– 6Š‘»ŽWx(ˆ|й'ìq7_Ãot\5FФùfo”˜Vn)Ôfªü 5¨ÙCiQüÏQÎ$.Œú“îm»†½Ã•í­¿ ¶¹S2k:Ø¿íÙˆÀ¦™¾½Â„KÉ®PÊŒ¯W¿8x9=àŸ¹ôHÙ!¾évÈdƒ›LøúüE&S¶·& l2¸ÉD ‘ ¹÷"“ÝÓ&“]"Â@‚üø´Éd*Íã&“uÜ9d"`“‰ÀM&L¦ô÷Mxùë‘LðïM&¸Xs2¡ü@&S&R'ü{‘ ÿ‘Lì¥ÚSC‘͇L6¼ÉÄKD&‡<'>kö@&œöE&x˜î&“Md’ƒÒNSŠ1aÞ†çLÍ =î[ܯ v#Î9ÇëÏ qæ×8´Q 3“2$ZºáԣΊwäŠǵ‰Ê §7’!¡ÿá™ ¼V÷hl ¦rü–Y§›¬àóÒ´Ù)ëå v%ôä`®ï9HÕ9ÄEžuXƒ/¨(V‘Ÿ§#ÍsÐ5å‘÷Z|¼k8¦íú&(Å%ÑeŠ9_È…ÓÕb .ÎÂÕÒ!¿¼“‘E!“Ã'•‰S#7 B. +ä (õú@.ô˜6—?O#›¨4ÙÔØ–¤_%ái°«Mød»úÞsèÂ'ã×%{ÐGß;®ývÉc KúÇFȲQn4»—<§„²†é´  ËžŒWÖ«L¼R)êmn@Wyoß($½lP‘‡1hGé"=¼N°šk-^ˆ Z˜2[‘†ñíX†­²ÿÙP¤Ðø)‰?÷(_ô R>nÉŠnè{{ðµK Ap†øðà«ú˜c ¶xø«Øª& ‹!P{ £À/ц1?ÉGt™BãpVé’t– '¾>.£ãVç&I¾?môˆßëä,U¼}¯hq0´ ž†a<ÖÒÌ?Çi÷K|0_ýNÔº7èÈMâZ©µ³=¥í0èã> ›Î&>èö’³íÕS”<’4yQv3Ù¬Pïbü1­Á¸‹z'šýÏ"ø¥£ç ¸'°@ÍÒñLÈ÷@ê<]Eâ^a~_.0) y-ídÇÈÛ µ@`‰&W`Ð)ø"q_{qЈ;Ù ç. ¬R'=Åwˆ9[ ÌkP¹O²r¤²µÆKã# ƹ‡ÁàÆ)ÚNŠùËrÇàÛñ0Óá•j ‘"»™Šg`Ôª¬#Vò²KJЫKÌécgì«$Kí|…Á­’ã…€F%ÀY°›p%ÅRÁp“à‰1·E¿ñU¡\±?Unp ˆŒ¤SÖŒ‚Kóh t¡)X¢‚ä‡ê ï2ßmÕ¶hÄ œrŠBRk³ÎdθÜIVM×bÜŽd°÷{/(-–€—{zÚ²q—ˆ`à&߶d„›Ó¥Å"ìɵX\‹5еX»E¥¥vk±ŠóºµØŒLÔ—»àúdZl†'Ôƒ›áZt´Ø ·²£Å2LìA‹e(Þ¥Å2 êÒb/سìj±î:’»<ŠzŽ¾ÞZlÆ3§—{èáQ‹…ËL4ã/†vEÅ'Ù¥VÉ6DÆKdÉÇhÁÙE‘˜Žk±&Ro‹Pn­žpÇëaeêÈÈ›¯] xçã\ݶöT-x À@¿áMÓÚ%ÊA¨šâËqn©  b)Áì¡k'ôÓ¬”Ö€ƒ=è‚ø*¡[_FFY1MQ\àZ†fGÁn“ZmÏ šÕ¶:p”¹ð*©Ð¬Ð_> kF~Úñté¯HŒW® •« %¿; ¡2ËA‘Í©`=ªüaÌGsF™^«°¹Î7ÑBåy lgd"¥üv¼d;Æ^FîâÊÅû2èu4ÄÇõcûÉÈý{™î'Ä…sÇVn¢º‚—Æur@´T{8[0@*]5LEr•aäLáöÖ"²¤*¼'$k?ש‚…]á÷U[HÍ'TO þ\”àÁÚ–¨@]˜m»V!_BxJ^F$wÛ"¿V3wX8žƒ[ä#ö ·z.òk3e’S!°E¾À-òšÈG;³‘¿{Ú"—HÈWÄï| ¸…~…7v~Úç‡:æÕÝ8š9Ú–eÔÏŠ +®¹ T‰8aÅ› +žÀºvÿ†bIG„†dýé:DàõU©¦VC¼4ü×>AÜ'‘á‚Ȧ8Ÿ¶ÂßUz#l—C Žý]p#¬áiƒ~vÉ–/„ ظf Öð‚IÂ0°"y|ÙÇpξª! HÄð…4üõªÁ…풯ʔ‰´q#ax¼p†øú"Û%†¤Ù5öW`Ì™q_Ÿ¯â&W³–-}ãkØF®#—@SŒøŠåÙ‰æœòloU^×w{kcGo?r­]cã&ŠFün²ó±oM]"Æio±ðxªëÊãtìWˆ‡¼íWx´õ¶_u…„_ö«^Úõg¾®±íWÈÞö+Æ÷^ö+æ¿ìWLþqìWp¹»ìWHpÙ¯:e‰ìWpí{´_!)Àm¿bR´ƒ„d>Ú¯¢Ý5B½ìWtûÕ.0û“¿\{ Ÿ!yØcYzÛ¯6¦Í~Õ•3âÁ~e¡ón¿~nû^&¹ìW{R{ÿïx‡ó²_!œõ¶_1ÃÃm¿BÁm¿bÊÀË~øÑ~uJ¶ý ·Ë ˆ¸ÉÑ•c•yq»¼„m×í2¢S“eZ]<ÂÛè÷d§Œ§äå”ð•åiM•ùNÉù*‡‡–a2P¨e†C[¼?ÿ“ÄëÞ™mSéþð2A|ø éã•Á,ù¡NRŠÚ)©q§¡×ƒäSr¾z§÷wG¸÷»ßü4¿¯Ûendstream endobj 6 0 obj 26045 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:56-07:00 2013-08-20T08:41:56-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000026349 00000 n 0000027919 00000 n 0000026290 00000 n 0000026151 00000 n 0000000015 00000 n 0000026130 00000 n 0000026413 00000 n 0000026454 00000 n 0000026483 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 28089 %%EOF ast-8.3.0/sun210_figures/fronta.pdf0000664000175000017500000005357213004147321014003 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P05°Ô3Q056TÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!ê1s endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 531 509.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 531 510 ] /Resources 7 0 R >> stream xœ+ä T(ä2P05bcC]SK=cK …¢T…p…<®B.¨‚$L@,=3…ä\.ýD…ôbý K—|®@ Q¿é endstream endobj 8 0 obj 72 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 590 /Height 566 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœí ˜Å™þÉ_…ᦑâøtD$1®ëÍ"*^/‰QcÖE£Á¸ 7Þ×DW!nÈê1jЬWtט\ F“uQ5*Ψ€¢8ÞõÿÎôÐSÓ·ÓçT_¾úêý=óÌsºO_ªê­ª÷«î:ÝJ;xì±Ç¦L™òþûï—P>Ÿ~úé7¿ùͻì„äÎo~óÊéºuëÊNàÂ_ÿúWªÿe§¢4-Z4qâÄÞ½{÷êÕ‹þå+_yöÙgËNT*Ff³Y³fm¹å–O<ñDÞ鱑”eÈL’ºbÅŠþýûOŸ>½È“†žÚo|ã”ÓW^y%ƒ;BVYŽ<ÎÓO?=jÔ¨Èí©¦~¸w'ÍÍÍ?øÁ6lØ o@Õøþáh÷>}úŒ;ö¤“Núøãýoi—^Ql±ÅÏ=÷\ä?ùä“ÆÆÆÀöcÆŒ1È4/–,Y2|øðûî»rJ‹T\7ÝtÓÈ‘#_{íµ²“VÒ"ÍfTIžþù¼c))ËY%•:ÿô‘­Eå£z¦–FsÚœ²­(2!«,‡ó»ßýnÇwŒ<>õ½ÔS?L½ñúõë—-[vØa‡~úéþï¾ûî¾ð…ù—!}i›^xï|prn¹å:NÜ·+W®ljjª%O–ñw÷w·Þzk`å%—\r '”’žšp°éeŽEeXJR-*•sjí*ŠLÈÉé–/_¾Ûn»ýæ7¿‰<þi§vÁèk^~ùe}THC¼ï}ï{úÌ''uãÆãÆK¸®õÒK/ÑØ09ö2oÞ¼‰'R!ÖôÑGwÜqGúãttt<üðÙ&-6½Ì±¨ ã’ºbÅŠ%K–|Ò:¨ÚLž~úiÃQ˜-N·iÓ¦|0ÜóäĪU«}ôÑ:vÌoL—°¾oß¾4ÂÒ׬^½º¡¡Á_Ù§OŸ¶¶¶ð¡*ÏwÞ¹Ç{$¤êÞž{î™°Õôïߟ¢‹ª›ýáØi§¶ÜrKïFÞ1Ç£ßæ¦oiØK‡ò¾>}ºw!Ôƒ*ó?ýÓ?‘4ÞUbtÿçþ§þí¹çž»ýöÛoÑÉ;ìpà 7øßRCùI“&ù÷iê«_‹Ö¯'Ó)Ž:ê(o½%')ðŽC‡Õ7 ŒP¨æz«­¶:è ƒÞ{ï==;^x¡žÙ9sæè»Sf÷Úk/?³t(ÚXß 2kÏ>û¬~Òƒ>XŸ{C'¥øP?éÂ… “ 0ÊŸÎâ§P¿,þ6þðÝ } Uª<^F¨²Q•>|¸ÿm\j© ‡ 2hÐ ÊŽJ8pü{ʾ¬ *T½) ´½ÿmú¾.|½!Tm&ßýîw?÷¹ÏÅÕI½òø!ë<âˆ#ô ¤VÏ)}þýﯧpæÌ™)Ë!®ðÃ5Ö¯ÔEPkL˜0Áo¿üå/i—+¯¼2MÁÎBŸ_ýuÿÛÏþózñå/™F@úîwß}÷¶ÛnKNAPã=ãŒ3t‡ ×:*ÿ[Z™\h)©Éé(‘z½DÒ–x‹T‹þú׿†õ³Ÿý,ò,”ß]vÙ…Ì.!…<òÈÖ[o=lØ0ª`~%¤¶“°‹E¤iÅK—.¥þœ yýúõªóFÞ‘G9kÖ,ý[ª Þ"}{ÒI'Qëów'#ûêW¿JM’>Ó/^L­ÕDÓ·ÔHµ¿uòÜsÏQ]Ò“GÍóÚk¯ýì³Ïh‘þ™~Z¸?Ø29I „w¤Ãú;R+¦ÅÛo¿Ý+(jé´ýW¾ò= ÔØ)îò3K¹ó/øá‡Ô‡üë¿þ«—Y:ŠvÑ£»pÖÞ|óM*ý¤§vš~IŸviiiñOú‹_üâðïZ†‘ÐÁ'NœH™òâ:#I3uêÔ¸o#Ó8¦¾†LÜÏíNU.¦†wÿÕ¯~EeèÅ·”;Ú˜Jøßþíßô]H\RÊ+ŸðqÂÕ›Ò o²|"C-Eÿ¶j3ñ¼Ï¯“=ö˜ž ¿òxk¨œ©ÏÿÞ÷¾—²Äè3ÙÍ<॒´ë®»¦/‡pQ„k¬^ÈË;ì0Lmè„>Ð/¹äïÛwÞyçä“Onoo¯Z°³Ðrüo}ë[zªôo)T¦ŒøG&Û¢’¤Üy‹Ôx©œu· ×:ÚÝ/ÃäBKOMN÷ÏÿüÏT7ô)(Ï<ó mé/~úÓŸî½÷Þz?°bÅ ÚàÝwß<Ëý÷ßOA£RHÞJç}ë­·¼óú•P÷}{IÓŠ¿ýío_~ùåú*Š:â¾¥žmäÈ‘þâøñãÿïÿþO߀ú%ª½qßÚf J©êtžâá™Õú–ÉIJ 2µþŽ8%÷äôùƒ>п¥¸Ý¿LÁÃñÇÞÝ?#³væ™gžwÞyúš·ß~ÛW‡j~ þSKïÛ·o\ “¹âŠ+ôÎYu^åöþ6þÈsék¨Ú.ÚзúÔ‘ðîTz±Ï“O>¹ï¾ûê»ÜtÓM ' WàÀ-”åyœ^x!î۪̈́œÂ7Jê£(ùË_ô â <®Ä¼á‰¿HŽéד¸ô'7·pÕëßÿüg’ÿéOò¿¥–òÆo¨ Ÿåý÷ß×ëpX þð‡Ô.¼ÏT†T’ú·TÎTÚþb¸Öé–’ -=59µq È‚©-Sü‘ÇIþ6¹™¬]»Ö߀ºâp2j-𪅟\áÅpã Ô½o¼qÇw¤^zÊ”)?þñW¯^­j§êYÂù"ƒð‹Ž>PIêßÜ*\ëtª6Ÿ”Äí·žF÷4Â"‰)©ä5÷ÜsžeÕiv4 8ôÐCiý´iÓhƒ¸CQ¿AãÐÀR¢WB«™3gÎy_Ø/·†††„*ù­^8ýúõK°•äoë륫®L>iá3t:*Éd§‹<íõÖ[o%¤9C§£¸(ܵ&[SùPñÖºû€ª:]8©úÊÈ \‡ÓeÞLL8µxráW-‡ðbd óúë¯ÓÐãôÓOÓßs)‘ú·)T†zÿF%L嘑¨u) …åÔ›C'¥cêuÒí¥—^>|8u^ÑQ“ÙsÏ=ÿã?þÃß`Íš5Ûm·Ý /¼@ßR@òöÛozè¡—]vYøP'N¼îºë"OM%CA²ˆRœóµ¯}ÎåéëWB3R<È÷©»ð¦Ñzól¿= L?>úè£Ó§¾ÕgæÓ6t¢»ï¾[ÿ–Ìn‡vØb‹-èÛÏþósçÎõ¿ÕØÈ5Ô öÞ{ï­¶ÚJŸùÞ+°29I „wÔÃrÕYoþõ_ÐÊ‹.º(.³ªs65õ]ú,}}º{\Ö¼Õ?é!‡¢Ÿ´jR ò’”æ‡td:¾žB}$þ6Ð;î8ý[ê ôÄPµ¡Ê£Ï÷¦"Òw§fØÒÒBèI¥2¤Íh{ï7TÂUK,°2\wÞyçä#D’_3‰KÕ ¹JLß«jMH.â'?ù Å*zU ×X¿>é32Äû•}  ÄÿÙ£÷+ƒþýû'èfô³Ðú¬_Ϥ•ú·Ô!~e ÷oTÂTÎ_jÞ·W-´8Èp½jéK`VõhÑ‘Ùy¿ ¢4âlpá…zZ]L™2En{—7.îÁ§d¾T\/¾ø¢·H›QóôNêWÂ{ï½7Mfk$Ç{éÁÁ,ƒ4lÚ´‰b’ä{d)A‹ƒ×Kâ:k×®]¼xq‘éb€Óp0Ë Ô755ù?…6u €‚Óp0Ë ­­­÷ß&‡B `’¯á§¿ã#³ u žôî­zõÂþð‡?ü1ý£^BÅù¹ ÍõŸó–jtig¿í65mZƧ†@n™Kv,)ör”šÓi©@y¨àu:]]Çç¼e‰›lŽÌ.ÛS§À EÊØÒRàtæèeØœZÜôµ:ý1ËÝ2}GšùÙ[ZTGGƧN*þ€52ÜÒRàtæÔY†òJ>‡&P&©Ck€@Ì&'àtæÀéd˜˜Ã)Ó™SgÊ‹ß8Uì '0Ðw1‡@ÍÍÝÓ/!(Ã.PÌA(”è¥ÍAvr`bÊ ôÒæø£ã1cjÙMXü¦x…p@Á 7Î 89˜‘"Ä„"Ìá$œÎÌH‘ šs s8 §3eا.„…"JíZv²E˜@J\ âÔ1¢—6eØÊ3·)•îÑ  4„µ N¡zisê,Cañ›âU±3@˜@Ó:Íp½qnÀéÌÁŒ™¨¥ó¦$„…" ±bŽÀéÌÓÉ11‡“@p:s0÷²§ø- sÐw1‡“@p:sP†PÌ‘'°P¤M©]ÊNC¶p½´9˜‘R‰9ˆ93:ÿ@>ÀéÌÁ}º œâ·lŠ@ æ´(Õ^vä§3N'ÄÄN¡ˆ§ÓßCxزþUÜC˜[[ÕÀ]ÛÐZL^¯ƒ)8Õêl&<¤ô]ba à÷ÓmÚ¤öß_Í›v½¹Ø¢E]Ÿé-F®ojRmmÁ}å•a= ˜ƒP„9(OäõÒs樨øZÊõrðëg̨ü%ïë((æ@ æ@ <‘×KSÉTccõõ4°õ/f¦tºövÕ§OðÈ•mš;+*ý¥E°ŽSü– ‰¸®˜òœÎ#._ƒ§º×çt)×Thîi|+¬ÃAÁmr@(ÂN¹æt‹©††êÛÇ9][[̘®šC‹pFVmr€@Ìá$kNG:§ctŸŽ›3rŠß²AXŒ ˜#O Næ"ÆéFkõD·³Ñ=ë>—RG¿ªéý² r}SSåV];Ê0og´¢\1Gž@œB;zé46vÿnbРn;Ó×'ÌHñ~Yàÿn.ð‹ƒðz™O«Õ9Õêl`.P­Hiéb@y"ÆéJÏH©Àíjª9ò†°På œÎ8]ÍD Œ²\È s8 §3O«küVŠ3B æ ïb'àtæ  +°*+ÆŒÃJ L@(ÂN¡—6G挔Z±º"¹àŒV ä(Oàtæà>]Nñ[6$„"6:£SÙˆ<8§3N'“ ²ÑùƒÄN¡œÎÌH©À©VgC‰ÁÓ€¾‹3­J ¬¾UÞ´´¨©SÕüùpº @V@!”ˆ›ÎˆX‘3•ŠzÎFÁtt¨ Ôôéè¥3eX…À] 7‘9hAy‚^ÚÿQccÒw Ââ7…›=&Á ]qžÀéÌ©§ QìÌ@&ÔêŒ-JMUj¾R©OP„9Ì‚Ó™SO «Õò@»(2¸JMWj×Íkª:c¯ ³§3eXYgŠ¼PD’@dp#ktÆZÇŒÅ#I §Ê° 9. 3Æ]\-×… Ä,VD/mN=e(,~Sì*¶)òBKOO­WS3™òNgf¤Dž@EŠ¤g„@y§3N'ÄaáEÆ9§3s/+0 áL@Ìq¼ãŠtFÜvŒNgÊ° 9ÂB(’ž:~ÄaîŒÌB/mf¤T@EbbJqƜәƒût˜…p¦È E s쨔©ª5§3N'ÄÄœšB‘üNgf¤TcËH踘“«@µ:ãD8]  + ˜ƒP„9(?¡—Δas s Pž —6‡ÊÐ{{Þ9" ]qžÀéÌ¡2ô^à¾ë®Õ7Þ¼OŽé˜ƒP„9Ì‚Ó™ƒ)A»`b3àtæ  +0 áL‘Š@ æˆY¯ˆ^Ú”as s„ Ä,A/mžVYÅ6Ež@héÌ@y§3ÏHˆ<Š0å œÎ8@ s s˜ §3s/¹Åo˜ƒŽ‹9Ì‚Ó™ƒ2äV«Ay E”¸h„™@è¥ÍÁŒ©0  QžÀéÌÁ}:nñ[ E äiÄ 89p:@ æ@ æ0 Eàtæ`F ·ZÂ’:.æ𨥥ëñûp:sP†Lj5ˆ¡s P>ttt=~½´9(C8w s PΠ—6ï§c¿e E‚~8gàtæàýt@ÌA(ÂfÁéÌÁŒ ]01‡™@p:sP†Üâ· Š@ æȈY¯ˆ^Ú”!·Z ‚@ æȈY(‚^Ú< Œ[­Îa¡™3å œÎ<#E ÂB(”3p:sàt@Ì@Ìa&œÎ̽ä¿eb:.æ0NgÊ[­Aä „P„9ÌB/mNÍeØ¡Túߘ[js s PÎÀéÌ©¹ oSjZ.)) fñ[‹±!sä Ä 895—á´N³œA»`b³PDŒÓ57WòâÿÓýUcc÷zúI[›4¨{ZL^¯Ss¶t^À”³Zˆ±™#¥ã 3Ä8ϦMjÿýÕܹ]‹­­jàÀîoãò;cFå/ýgyeX3(æ aÊ}$Œ9sÔTüÎcâDµhQ÷·qùíÓGµ·w}¦´¹žL3<¬“W†5ƒ`bÊy½ô˜1•ë4” CVÕ·o÷bc£5ªës üÅÀúÈa]e›¨ÓÅ‚ø9Œ¸~˜òœŽ A\CCÄú³ÎRgœÑ½8n\÷p/¥ÓéýïÞù©¹³ÆÒŸ—°¹çb‹RS;×»O' ‰BE˜ÃO ‘N§¢òõë_«Ï^½ùfªí㜮­-ÆéRB·@©›O—ÒçËEh£b?qº… ÕСjùò´Û×|õ2'5—¡½ež•32‡O(’ÂBÄ~‰qºqÈéjÅRgtG K@Ìá'œÎœšËPXü¦² á˜8#bz-æðNgÊ°´ŠÍÄù#¬Š"a?ÐK›cñŒ”¬°¥9댶ä,(gàtæà>ÃÎ?ãŒRƒ¼>p:sàtÒ¨[ 1ÎÈy-¡HÎÀéÌÁŒ†ÛˆÂœ±>Ðk1‡Ÿ@p:sP† +¶lC‘ºQX(ÂV º@ù øýtŃ2”ætbðѨª3 -(gÐK›ƒ¹—|B¸l€@þ^pÆb@?œ3p:sÂÏ«¶C¾é¦@ ú(ÌŠ0‡Ÿ@p:s0#EhÅÐåƒ Fé˜ÃO 89(C†!œòBùÎج-¦qFP0üºDôÒæ  VlÐ7ªuÌXÖ‹Œ•”Pć_¬ˆ^ÚÌHaX±AÐÌÓPë‹Œ3tF”3p:sðŒi a’±¦þC œÓ™§“bŽ¥¹óH~ÁéÌq}î%¿øÍÄGz­Z‘ÏÏù §3Çõ2t<ûü‘'°PDå”èŒür½—Î×g¤  1ñ‡ƒFµ:c‰SUkNgŽë÷éøÅo¦ E lìJœªZ;p:s\w:y@ æÈHX4Š”êŒp:s0#EhÌ@ÌÉD Z1ñ!9p:s\/CyÙG(ÂaulîÌÅÀA žÆçz/®—¡ãÙçbÎmJM+; Òq½—Î×ç^rˆß²"™Öiv OàtæàýtÒ€@ÌŠ´Ø1Q¿ø §3Çõ)ò@£`b?àtæ¸^†üâ7S„…" ¿.Ñõ^: \/CdzÏÄ„"ùãz/˜‘Xƒ6Δ?p:sðŒi ab?àtæÀ餘˜ÃO 89®Ï½ä¿™˜ƒ^‹9ü‚Ó™ãz:ž}þÈ¡sø äz/®ÏHAbbÊ89µ•a›R}òJI9ð‹ßLŠ@ æ Î89µ•áŒÎ?À4 æ¡HþÀéÌ©­ [”jÏ+%åÀ¯V›‚FÁÄ~ÁéÌq½ åe_XŒ-/@Ìa#Pss÷ø!®—¡ãÙçbÊ×{é,¨­ ¿1‚A'œ?p:sj{? œ9ˆ9mJíRv²E^(Â/\„Ó™S[Ê«ÕÂ@‹`f/ó‡_#‚Ó™ãzò‹ßŒŠHÞìeyðë]拾Àõ2t<ûü@ÌŠ(Žá¢ë½t`F ` Ú8s PþÀéÌ©­ QàÌA(ÂÄ–ÁéÌÓ‰11‡¥@p:s\Ÿ{É2„«ÄtYÌa)œÎ×ËÐñìóG˜@E˜ÃR ×{é,p}F ªs s PþÀéÌqý>Ë®~ä…"ˆ9òú~ÀéÌqÝ鄘#O „"ù#Æéô·3Ðßðá=¾mkS£FU9Bk«8°òGÒ¬÷ÁŒQHib@Ìa)§Ó™1£òX“œSr12ÇE‹*ôÁ7µ¸õ:"Ë°„e¡s s8 $øýt4|£ñW»öd<Êlcc•œÒ.äeô#×75UŽ@^Ö†ãÙçbÊy½tx@çÎé¨QÝc´À·þb`}äÁ]Ÿ{É)„Ë F\'ÌyN·ãŽ•LÑ .@8§C‡vß¼Két4TìÓ'êÈÞŸ÷~ºæž‹Ä¥ÎVj¥·u-™Å˜ƒP„9,’çtá|%ç4¥ÓµµÅ8]2«”š­ÔøÎÏÍ!+ ;#(¡-Bˆ9,‚ÓE~›ãÕË44÷4¾ÈE>ÎÈ2„«a¶‚@ XXzŠ§ݳ9×êt ÝSMô[`}`®Kš#çNØø vF)UH,ˆ9EòGŒÓéim­8TÂúŒ}°–æsò‘“(½VgîŒ,+6èFJ Ê1NçýŽÀû4¨û§>Í¡YŸ‘B#5ÚËÛåÜâÖëFJécÆ‚)=Éa¡bKÄ8]‰wºZ±ÝÅ d;ˆ9,‚Ó™ãôÓÀÌã7nÎ(L ¥v-; Ù‚.‹9,‚Ó™ãtŸwnÎȜ۔šVv²EX(¢˜^î«–9ÝKg„e3R²…ýqܧušà ÿFd?p:sœ¾OÇ2~3¢·,glé¼€) a±¢×'°NgŽÓN'Zr|ÌX<òZ°p‘e(§33RD‘w‹¨ÕiP6U©ùâ†fuƒ.‹9,‚Ó™ãtÊË;·P„ nRÓµ)”59£¼P„›@æÓˆ“@‚ßOWùä“Ï?ÿüìËÌH|Ó1BN×ÖÖ¶ÓN;Í;7ûC³¤†2D­fBæ@ æp}´oNWÞÈìÆ7oÞ¼\ŽÎ 8 s s¸>Ú7§knnÿŒ¿§« ,~SâblÄ8s¸>Ú×éÙátºœw+&Bæp}´¯Ó½tF8=#õ‡9ˆ9¨àtæ8}ŸNXŒ-/@Ì‘×'°$?§{çwÎ?ÿüþýûo½õÖÇwÜ¢E‹ò:SÙ8ít€@Ì‘'B‘BÈÉé–,Y2dÈÓO?ýí·ß~÷Ýw¯½öÚqãÆvØaëÖ­Ëå|¥‚)rב 1‡«@y8Ýòåˇ ¶páB}å† Ž9æ˜c=6ûó•ÓW€…å¡s s˜ ÔÜÜýþÌ9þø㯸âŠðúÏ>ûlâĉò~d§|@Ì@…Pð» h¸×ÐÐý)KÅé¹—ÌB8S (8]!ÿ.yo:Àûé䘃P„9\ÊÃvz÷î÷.ƒ?ýéO Èþ”¥âôŒaÀ阘ÃU <œî;ßùÎi§^ÿöÛoo¿ýöwÞygö§,qƒÔZàÂÕ‰¼P"áÚæÑK¯]»v÷Ýw¿à‚ ^zé¥õë×ÿíokooòÉ'wÛm·Ë.»,ûó•ÓNçrÞ­1¡H!äÔKÓðmÊ”)cÆŒÙrË-·Øb‹#FLš4éÒK/Íådeƒ)€/p:æ@ Bpz<’xFŠŠ01‡«@p:sàtr€@Ì@Ìá*œÎwç^rßêG˜@\_]?诘ÃU LœîÁÜ°aC²w£g3n \_]?ÂB%.\ä*y/}ã7öêÕkæÌ™þ¼s<aµNÇ®/€Ý ‚¹Ó-]º”¬­µµ5‹äX‰»÷é¸Æoõ#,áúèú&×'pÅÝ+oÙá®ÓÉ1Gž@ÂÂE®¡C§Û°AÍŸ_v"j3RäÀ¯9€@ æpˆ¡Ó]y¥ê×/¸²µU}á I{éï!Ò¶L;ؽ¾±1zw}3úà_‹[¯Ã° B^ÆŠ0G˜@JœFÌÊõýt£G'‰—üíÿ¨FŒ¦ŠRëÙM6mRûï¯æÎíZ¤-êþ¶OÕÖ±—¾} ÅÈõMM»ÃéS  Q!üÖžäw¼û®;VÝtªR&uÎuÀ¿‹ÜkÆŒÊ_Õƒû‹ivwwî%³ø- (8]!ætkÖ¬ùÅ/~1räÈ„wy¤úîwcS^Ic½ðOh~•2°W{{eXÞ=¥Óé»7nÉ?¡@­fbŽ°PD‰‹F¸ ”‰Ó%ÿ€Îcë­·>òÈ#y䑸ƒÌ›§öÜS}üqlªjJjœU¥ßû‹*3‚‚Ó11‡«@Å¿s<ŽÑ£{L) ¿Â;§kk‹”…7«i÷lÊÐFgä¿ÕlæH.9 ñ ߘ®äûtÂÁ¹ÖjÐbN›R»”†láŠðœ7X‡Óé3:[[UCC×çÁƒ{ü4€Fdíí»ë›y¿,ˆ\ßÔ±»3RòpF®µtÁ²uƒnftþüáét‘ƒÂðJ}JIcc÷eÏAƒ‚?ˆü=¾»¾Yøáõ:2Ÿ‘ÂaÌX<Â.÷É E„ Ô¢TTàm1\âétv!ÓéjE†3 Hˆ9\Êé>Þe°Û$~ã錈9\;RÐWòpºöööQ£FÝ|óÍúÊO?ýô€˜9ÄrÜ™qžÎÈy5¡s¸ ”G/}òÉ'Ïš5+¼þƒ> áÞ|»ßœ‚´eˆ@ œQñ(Ty8]ß¾}W¯^ùÕÒ¥Kžf)iË/€æŒHg”$‡°Aœ®(Šÿåx}¿+çLÚ áÐü©é–«˜`”‘È Eø” (gr}? ÜFŽy÷Ýwë+?þøãÉ“'Ÿzê©ÙŸ¯làt |2qFP0hAE‘S/½téR2»éÓ§¿þúë«W¯¾ôÒK‡ vÆglܸ1—ó•JÚ2DüÆy“c‚3rNWùG>üðÃýèGýúõÛf›mN9å”_|1¯3•MÜËBÛ”P'ò&Çfg. ‹_ܽò–iËP^­&ÇfH­Î8A©³•ZYí°è¯˜ÃU 89î–!×ø­N09¶DV)5[©ñ›㜱÷æ R:#(®¡»½tv¸[†ÎfÜ ”Òk3ŒE¡HJ¸^¹Ê©—noo?ûì³·Ùf<á¹ÔjP0‚®Vx:#*Š<œîÁ2dȬY³V­Z•ýÑù‘¶ Q«™ƒP„9E T«3Ö÷Ãa)¾(§;üðÃï¸ãŽìË8 s,ÈÙGâpÕ(§'Âbly©0 sê(gÌu6…È7„ÁŒ! abNaÕêŒÃÝ2t6㶘Ša‘ýtv¸;÷RXŒ @Á û-ŠLœnÆ ÅZ¨ §NUóç«*?—G­fbBæ0ÈÜé-ZÔÐÐp÷Ýwg‘+¡2\°@MŸ®vM~cµ°Z-8s s dît¿üå/{õêuÁøk0÷Ò‡põ /@ H÷„™ôÒÿõ_ÿåòLwÎÙŒÛbB‘¢p·—ÎÌHLAëf* 89xFŠŠ01‡±@p:sàtB€@Ì@Ìa,P&N—<3Rº@üÆa)q1îHAÆaLgŽ£eèf®íB˜FE˜ÃX G{éLqtF j s PQÀéÌqô>ãø­N„…"JœFòÖ'0NgŽ£N'Äy!)ŠœœnÉ’%ûí·Ÿ¾æ±Ç›2eʺuër9_©`FŠäu¤Â€@Ìa,PN·|ùòaÆ-\¸P_¹aÆcŽ9æØcÍþ|eãè¸X^®Š0G˜@JœFüjiézü~½ôñÇÅW„×öÙg'Nœ7o^ö§,8àâ4Ê™ŽŽ®ÇïçÑK÷íÛwÍš5‘_Ñp¯¡¡!ûS–Š£s/ùÅo¦@ P0pº¢ÈÃéz%4ù[Áû鄘#,Qâ¢Æåa;4j[½zuäWK—.0`@ö§,¼ŸNp:æ@ æ0(§;ùä“õ×Õù¼÷Þ{;ï¼ó|üÈBÜ 5Œã·:Š@ P0Œ{Â÷²:¨Õü‘V1ŘÃX 1N×Úª ªd‡þè-&¯ÐÖÖ½Ycce1y½Ž8ëN‡¼\ ‹Fä…"ˆ9ŒÊ£—ÞvÛmã®^>ðÀÌþ”•ÇJ«E‹º>ÓÿiÜú3fTþÒÖÓŽ@ æ@ üinî§äÑKßpà “&MZ»v­êétwÝu׈#žzê©ìOÙ™#ÿ´ Æå·OÕÞÞõ™>Ðbäzréð°Îѹ—Œã·zèP*ùUÖ!L yÀé $§ñȬY³ÆÓM7‘Ó}ôÑG=ôÐgœ±Ã;,[¶,—óõdéRÕ¯_×ç§klT£FUÙ,°>rXWÙ&梨¶Qµ @¹Ü¦Ô´²Ó’.Ê E ”ß•·ûî»ïè£Þf›múôé³ÿþû_}õÕþ%Í\¡¡ä.»¨ÛoïZlhèqÏNÏï¸qÝ6S:>Üë±ñ;MmLÏEúëݹآÔT¥æwŽ +¦ušà ÂEæ0HØ=¦ ÔäÉêÜs»×—é3Râò›ÒéÚÚbœ.%dp ”š®](‹sFo ggd¿ÕC ËB6A˜@Jâ HŒÝD˜Óu–š:UmÜ»¡ÓÅ^½Ì ÎÎ(«æ1¡HHrº«®R;í¤>ü°Çʉ{\½Œ›{9xpÍüù¡õMMÝT|ÍH)Ò×jPAPÓ– *l®££ãÖ[o=òÈ#ûöíÛ«“>}úLŸ>ý·¿ýí¦M›²?#…ó˜±``3“cùøeèt?ùÉO† òõ¯}þüùdyÞÊ5kÖÜxã»ï¾û®»îúàƒfv²cÇvÿn‚þÆŒéþÊ»UGŸÒg¤x›ÑPŽþ›Å­÷±ØéjE°3ÊH0˜ËÆ(+§›5kÖ{ìñâ‹/ÆmððÃ6láÂ…ÙœxX,9£›Y&ÇòGºÓ=ðÀ4d£á[òfK–,ill\¹re§ä„¤{5G®-rFþ«–˜ËÆáb&½ôôéÓo¾ùæ4[žvÚißÿþ÷38%'ÍH))œ1 Pdât}ûöõžýU•7Þx£Oøi–ãÐ}:Æñ[, Î8Z[”áŒ6 ”bE`@&NWÓë }k´L‹#R €3|P…†V;#säµ a¡H›R»”†xàtæ`FŠ2©•pÆüÖmˆcFçWàtæˆËP:„应P$WgŠ VdUÎÐS5ø§3G\†Òáf®Ë¥&gì…1#oЂò'Û÷ÓmµÕV½RÓ»wï NÉ Gç^ ‹±E Të˜1¼È8]8:ÉÌH‘ ÃÊE†"’à-œÎœÈGV«å†`N®Î˜Ã[ 89.–!ïÅõ /ácW¨Éå $ ÞÝ ‹½tÖ¸X†¼gƒ òª%««©æðEj‚w(âb/5.ÎHá=£T@Ó®Õ žª Ngf¤H@X(¢¸ÇØ5S€@µ>F•û+u¶Rõ=´œÎ8 sx ´J©ÙJß¼ÈjÌX0<Ú œÎŸÆ;~«a)q è©d¿zƒ·@p:s\,C³lÂ4r0©ãjj‰rx äb/5.ÎHAµá4bNqvÆbÓ™ãâ}:Þñ[= E”8ä Ä°O¨Õ'LÈ)89.:< sä $ Ñ'äŒf}ÛNgf¤H 9ˆ9U*uBœÎËP^–Š0G˜@JœF™ ”é„{é¬q± ̲]@ þ@£¼ÑœÑÅ^:k\œ{‰›9ò’úÞÓ™ƒ)€@ÌŠ(qÑoàtæàýt@C`boàtæ¸X†¼ã·zŠ@ P0¼»A{é¬q± ̲]@ þ‹Fx‡".öÒYƒ)€h×üF§33R$€P„9ÂRâ4â-œÎ8 s sx §3O“bz*æðNgŽ‹eè`–íBž@ÂB‘í!W2à-‹½tÖT/CØ ` snSjZÙip 89ÕËP^!óŽßêAX4˜3­Óì@QÀéÌqÑéä˜#L –r^Ó–#¼C89ÕË6И˜Ã[ 89.–¡¼, ‹Fä…"ˆ9¼r±—ÎËÐÁ,Ûb*„ææî'ðC\œ{É;~«LùƒŽ·Xàtæ`FŠõ`Ê7„…‹òBÞÁéÌ©þ~:2s0å›?hDÌá-œÎ̽´Lùæ¼F$ ÞV§3ÇÅ2t0Ëv˜ƒP¤X\쥳3R;Ю™ŠNgf¤XBþÓ œÎ8õ@ þ@#æðNgf¤Xâz*æðNgŽ‹eè`–íBž@¢y¡o\쥳ÆÅ2t0Ëv˜ŠÅÅ^:k0÷Òz sä „Ž·Xàtæ`FŠõ@ æÈHX(¢¸G#p:s0#ÅzÐ ˜øÃ[#IN×Úª ªüчÀú+9¥ÿ¯Â›…·‰[ï#© Ó",ËE˜øÃ[#1½tccÅŒ-ªüÑZôד÷ÑJÂû*r±áûv§¾©Å­×S†5à`–í1‚¼÷Ó5÷Œ(ü| ÜÞâò빤‡nˆõMMª­-¸/f¤X#¥ãµ1NÀÏ—>ó®CúŒÕm‚rðëg̨üÅ+>5)S J1¡sØ¿ËX¤Óýüç•+–äe ÝX=1thÅì—RŸ‘¢ÖÒ|Ö±oF ó1cñ °•¸Ë}˜!ÆéÆŒéžvBc6÷Òäkƒu¯÷g§zÎH¡‘š¿mãÜâÖëØçtµ"ÞmH<ˆ9ìC1NW"Î= ¬j­¶Î… ¤,èyjÝsØ §3ǹ2tmŽ«“E˜Ã^ çzép® KÏos”&¥ƒ”®H‹s½t”?÷²`ØÇoAtFë4JFX Rpº¢Ó™#FŠx9èŒÌ‘ׂŠ œÎÌH±ÃVgÌtSÌa/œÎçÊP^~ EjuÆ J­ÔÊÔÇÇãÚø#,\dß'8×Kç€seèZ~Kg•R³•¿y±ª36àqmìÖˆ¸†"òÞOW"˜‘b=ÂÚ"ç1#0o±ÀéÌÁŒëq\ ZÇŒÅ;£°PD‰ Ù §3'ü²Ð…¦Ô ª‰â1‡½@p:s0÷Òz P®˜;£0äÁÞGàtæ8W†®å×:l¨Vg´ñaqÜ¢C؇"ÎõÒ9€)€Ž7j+œÑq Ngf¤XBæä*P)Î(O#ÞÀéÌÓYb+¬3 ûXNgf¤X0äau7U«3¶(5U©ùJu”Ø:a/œÎçÊеüZBþ$hD·@©éJíÚ¹h…3²ȹ^:œ+C×òkˆ?jd£3Žs½tT)CØü¦âO‰o­Î(â¶#œÎœ*eˆæ4bŽ<ìF윧3§JÚ[¥ã@€ 1'A ràtæ8W†òò+,‘Š@ æ°¿íè\/Ε¡kùµÄy•Š¤sFçzéÀŒ»‘÷†n4jæ@ ÂÓ™ƒ)v3Cܺ……"J\¸ NgN•÷Ó¡„™ÓG©ö²Ó’A#b{àtæ`î¥Ý@ þÈÓHì}NgŽseèZ~­1¡Há8×Kçf¤^ Q3œÎÌH±„"ü¦‘<ا3Ng7ˆ?Ј9ìC89˜‘b7ò’º)æ°NgŽseèZ~­CX(¢ÄE#¨pœë¥sÀ¹2t-¿Ö˜ ǹ^:0÷Òn sä „^·pàtæ`FŠÝ@ æÈHX(¢,ˆFàtæ`FŠÝ  0ñ‡½Fp:sœ+CaùE(ÂÄö}‚s½t8W†®å×: sä Ä5inî~?03RìFž@hÔÌ@…§33RìFž@E˜#L eFp:sð~:»@Ì@üa¯œÎ·æ^¶)µKÙiÈa) ìÚ'<ØûœÎ·ÊpFçàŒSÒF„…"Ê‚hÄ­^:Üš‘Ò¢T{ÙiÉ Q3œÎÌH±a¡ˆ² À® ŒÓ™§³ÄÄB89nÍH±¡V׆0ä>Š96§3Ç­2t*³–",‘Š@ Âq«—ηÊЩÌZ 4b*·zé|pkî¥ ñ[mH‰ÓHž@èu Ngf¤Ø bŽ<ŠœÎÌH±4æ@ æØ kN·~½š??ãcºU†ò2+,éPjײÓ-ÂRâÂEú1½tcc÷“–é=ô÷y[o±{k«8°kú@‹ÉëuÄ”a*œÊ¬Ü¦Ô´²Ó’Öˆ‡"òÞOÈH\¾vÞY=ôPÄzr±E‹º>ÓZŒ\ßÔ¤ÚÚªœ:ˆ°øq­®aMë4;À)½®Eˆqºæž=pd¾yDM˜Ð½8jT÷-Î(ëg̨üÀŒ»&PKçLI E”¸pÑÄ8Î3Ϩ††ˆõ{ï­~ó›îÅ¡C+fç‘ÒéÚÛUŸ>ÁÃvmÓÜÙgÒ_à-uKXˆ9ˆ96$ÏéÈæFŽì¾äèCkÈ×6nŒÞ+¥Ó¥\Ó…ç}½{.úVçŒÌ±!~« ØÌ&,®€1£Êg´A 89n•¡S™µa¡ˆÄ d¯3Ú [½t>¸U†NeÖF s2¨ÖqLTª5‹óZ‹[½t>`î¥Å@ æˆy\›O)]î"¥eôóF;Ó™ƒ)˜ãìãÚÊ¥¦ 9£-pF89˜‘b1¨ÿÌÁãÚøÓË‚©ªp:sÜ*Ca™E(Â<®?ÞyÌÍÝê¥óÁ­2t*³6˜#O RÂÅÑ­^:0#Åbä „ÍTp:s0#Åbä „P„9ÂRvh§3‡ÊpêT5¾êßP@ñ21ñÇàtæP.X ¦OW»†ø#,~kSj—²Ó-ÂRvØ5 O yØ`"p:s*À3îÔFKŠ(;¢‡zéÜphFJ‹Ríe§$ƒÍTp:s0#Åb„…"ÊŽ» È89p:‹@Ì@̱äÞ=œÎ‡ž† :(æXrïNgŽCeèNNíEX4"/&%÷îê¥sá2t'§ö˜ÊÀ¡^:7š{‰›?Â4’'ºÜ2€Ó™ƒ)˜#O „"e§33R,õŸ9ˆ9–§3Ç¡2”—Sa¡H‡ö*LH‰ -éê¥sá2t'§–r[çKºg„5"Þ¡HKK×ã÷ê¥s3R,F˜@Ó:Íp]nttt=~Ngf¤XŒ0Z:/`JBX(¢Ä…‹–§3麟ÄÄK‚Ó™ãÐûé,‰ßj1G˜@ò°ÄAàtæ8T†îäÔR „E#–„"õÒ¹[†˜ò Í™?Ш àtæÄ–!¦|ó6s„ ¤$jdp:sbËS¾ùƒúÏÄKB89±eˆ)ßüA€ÍtP̱D 89•¡;9µ„"ü¦‘%9ÔKç†CeèNN-ñ•C½tnÄ–¡°àMY¿Õ€0 Ð喜ΜØ2DÙò1Gž@¢KB89±e(¬J+kju  þ31Çàtæ8T†òr*,‘ŠH‰ÓÈ’>AL/ÝÚª ªd‡þè-ú´µuÕؽ{`ZL^¯#¦ «ãNN-ñG˜F¼Cyï§khP‹u}¦´è3cFåÏ£9F}›4Ÿu0#ÅVä=®MJs– 4*yï§ X˜Ÿ/… ¨ÚÛ«ìÞ§O÷6ô#×Ó¡ÂÃ:ÌH±ykŠ(„‹ì±D 1N§³t©êׯë³7kmU#F¨³ÏV+WvoÖبFêú(1°>rXWÙæl¥V×Ã鸃ǵñˆ9–$ÏéÖ®U»ì¢n¿½k‘ewÜ¡†W÷Þ«fÏ®Ütó7®û‚gJ§Ó‡{=6ž­ÔøÎ…æNééoÌæà­yó¢G‹RS•šoçƒÂ,‰ß҂ǵñGØH–8ˆ0§Û°AMž¬Î=·{ elÎw´††“UôÍ"ëÛÚbœ.=Ôµ.Pjúæ;Dº3*m Og”U[˜ƒP¤$„9ÝYgUfÚlÜؽfð`uíµÝ‹ôy‡"v4½zI&µš•3ZR«ÝEVs* INwÕUj§Ô‡öXI£9Óùã8}Š¦¢¿ }80z}SSÄäó)£S{bõ-7;ãè­:Î6Ê jôÀ¨›Œfd™£·ìèP»¦œQY^"sÚ2}(bMŽÊ«é·tZ Ô”›N1Nw×]•9'Ë—G|å™Ý=÷¨Y³zܧÓg¤ø†HúÕθõ:æN—^…ì·\Õ¹åøÍ‹)œ1zúMÞéL½åm·©i)gTZ!P>Ôš•W=Òoé´@9x-¨ÆŽíú}·÷7fLoÉ¡FŽT眣V­ê^©ÏHñ¶¡¡ýì,n½ùÓÀ¬©£+ÎØ=ýFÅ:c÷1«9cæé¤Þ鶔3*å ”krT^õH¿%*ëì:]‰lµU“Åþð‡?ü±úûÜçÊö eóöÛêÿþ¯ìD@±47÷˜U»ãŽ]ëã#÷îZï1þqâÞ]‡¾;}П2J‡òø ÔĦMjï½+ðñI(vP0~=Ï°YçÒ+æ'“qï® üF¾OŸè7­Ç¡ïNššºv<Ûû=>¨ë®SS¦ôP6®ØAÁ…ù.–a³è„ŸZçtqï® l÷¦õ8âv'.a ™§žª<ønõêh¨ÈŠœš@g§‚—M¼Åðå'žè~wm Iê¯ä£–bTÿòË­·ªþýƒWcâv×ßÞØR¿ª‰«:ɼ÷^åÁw÷ÝWùœàt~±ãŠq‰¤iV¸ª @Ýè—M¨ùüô§ë}þüg5t¨Z¸°{ûÞêc郾٨Q•}{Åí·>ðU3^ ”ÈôéêÄ»>'8Š*vR÷ÝsMè&e³3¦ÇkÅPÿ¨ ÝGôöZܳÏVîé,X»èZß?út‘»“ÃnLø[R‡@¡ïÙg«•Y¿}hË%K–èÛ477ûSbÆøoÌM~|/%?þx %äÝ—^zé~ûí·ÕV[y›M™2åöÛoO“©ðŸzê©£>zë­·öæðœuÖYtüÀ6”€7ß|ó”SNñ6££x≯½öš¾ÍgŸ}võÕWxàT,^áLž<ùÆo Ü• —j{{û 'œ°Å[Ð^t|:òòåËà  ÿ/¼ð}Kg÷¶¤ô¬Zµ*±8@‘N·fÍš9sæ >ü駟Nؘá›ßüæßÿýß¿þúëªógóæÍ9rdø˜´æC™>}úÛo¿ímù£ýˆ'ezª²nÝ:rýø”’¡C‡Žöƒü€¬í¡‡úè£hñÃ?¼óÎ;›ššž}öÙª™úõ¯­jñâÅ´ãܹsiZ$ã +9è ƒöD ?÷ÜsßyçZ|÷ÝwO=õÔÓO?]ßæšk®ÙgŸ}î¿ÿ~?U÷ÜsÏÎ;ï|ï½÷&” %â‹/¾¸££Ã;òW\Aé|å•W{-]ºtØ°aW^y%mCk(%Çw\}shÀFÂ?1ð†ÇsÌ3Ï<ÞX_¼üòËÉ­h0¥¯¤~•6óÇãÓO?¥5dúu¶7Þxcìر‘é©#?üá¿ño®ã-Z´ˆŽ¶~ýzMCCòeËû’Ìž=»j¦È÷ýLQ$@‹ä˜ú6tv—Q„௡!%ࢋ.Ò7ûãÿ¸×^{ékÈ ÃcÆ; W_£— 9;íuýõ×ö¢³Oš4)°Ùº¾ò±ÇÛÿý¸AÀY,X@]( +Òl¼ï¾û>üðÃU7[±b­ Ø}"oÖçt_þò—ÿüç?W=Úgœqì±Ç~ðÁÍ6nÜèŽË”¾ÍÌ™3O;í´ð6¯¾úêÀýE ÂÙ!ç düÒK/¥¯7àŠ;c /äÎGuT8ííídÁ½h„ØŒb¬îÀÂ]ñ×¾öµ³Î:+ÍÆÔ[F>2%òêešÍâVV…R¢ÝâŽFƒ¬“N:ièСäw4vûïÿþoïÒ_àPUŸãÝP‹¤±±±jv+?ûì³sÎ9§©©iÚ´i_|ñý÷ßOcÆä½ ÐÖÖÞ†R°°¸òÄÌ€;„{<‚‘<õÔSU7Nß‹æít5õç/¿üò­·ÞJã²ý÷ß»í¶ûñ\k §’F®¤á ¨Ï?ÿüC=”Rõýïÿoû[Ü^ ¨[#JdwË-·´´´„§¯6¦‘ExLy̼ŽR²nݺ:Žöꫯî¹çžóæÍÓ™)m·Ý–vL“°úò¸råÊýöÛï§?ýiÜ^4r ßpôÀ˜Döx›6m:è ƒ®¼òÊäiôùØaÚ,à;é;ü~ýúÆ2i ÑÙ£>y }2äï~÷»ð6Ë—/ohhðã2õÈ#ø™š3gθ¦:¯Ž~:‘&ã‘©zíµ×ô[~½~þóŸñ‹_ L›QÃí·ß¾jÖ€<âz¼—_~™o¾ùfÂÆ>ø`SSS`Šæõ×_O›î4¥wºÝwß]ŸóŸò¦1cÆx¿ ð¹è¢‹s/¿ð…/,^¼8°ïã?®;]\¦h_?Säž|ð™gž©oóÞ{ïíµ×^—_~¹¾2MÆ÷ÙgŸ»ï¾;°ÍO y®ºê*ï×m+W®<ï¼ó¶Ûn»Àx02SôAßfíÚµ&L òñ’úâ‹/Ž?þ‚ .¨#ã¿ÿýïétd‘^ªV¯^}ñÅ2„<7a¯ 6PÂÈ%)&Q—ai4:eÊ”ÀÌ8Ä}E}橧žª÷œ‘/\¸ÆD½:ŸB]}GGG¸Ü1rå'Ÿ|rÉ%—СêxL 9Ô€ô”„OñÔSO}ë[ßòlrÎ9ç¼õÖ[i2•TÚŒ6¾ùæ›Sæ1¼òÿ÷ýç¨l³Í6gœqFàà‘{ÑÐrîܹ^–û÷ïÍ5ׄo­Æé› ;€dÖ­[‡ßjLkkëÞ{ï]v*€Ìðî.ylܸñÄOœ9sf‰é²eûí·÷žEüÊ+¯ì»ï¾‡zhøq[+øÿ©yÆ\ endstream endobj 10 0 obj 20713 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000021801 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000749 00000 n 0000000728 00000 n 0000000849 00000 n 0000021776 00000 n 0000021866 00000 n 0000021994 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 22047 %%EOF ast-8.3.0/sun210_figures/overgrid_bw.pdf0000664000175000017500000006241113004147321015013 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ¥½ØwWU'*mŒŸ„&ÚÀ Ãȗ³ë9G: ý#P„H`¾7„¦8 ‘Ž€”LèƒÒ¥Ë…iÒ/¡©!  p÷¯ì}þ$á:÷ÎãƒYßÿ=çì¶öÚ«üÖÚÝ›†½ ÿçÿÞÿÀ±w™÷øð=Öt0ä°—Öù`^–½ýyNõ`ã—Ãã—<çéà:·_ú[Û/'8~ïäÝË)§ƒye;7èÿàãÓŒÇZ¿ém{³CÇÞêÀ±Çï•pàØ[óÿßôN7Û[{ËcoyøÀ±7¿Óo|ìvâtÿG<äa{¡´7rø‘û'?¼={“›¸ÍÍ÷õ‚ïvôó¯ýæË¿úRWøòÏ_á¤Ë—SžyïûþÜ3××ÞìÙŸýãK^ã-—xô1ûÀ¹GÝô©ÇsÌÅ~æ6ý¸c¾ø{—ùÚ3Ž|îÅ·~÷AûW¾ó%žð¬SoþíÏ|÷úÚyçΧ}ý+Ÿ:î_>ÿªW<ö¡Çÿàó~ÙÓ®x÷‡½þOûÞoø‘o¿å+zËŸ<å+GžwÏsÎyÇ/Ÿüœ/ÜçmÏ|ð­ýÇ—ø‹›\ã±_;ó ŸûÁ÷žü[o¸Þï<æf?¸ïÛŸwÃ3ÞüÛwz÷UϽÿ)O8áK·;ûNß9áQqÎs~ùο˟|þ2ßzÈ;x—sîö ›sðW:÷—Þ{¥Oýý5ï~ÌçÏÓ§Ÿúðöü¯›üà¾þìoßþ¸þË]wâoŸyþ¯¼ç§qîù¿zäÑ×ÃÞ]oñÂ~Ú7Ž}ÈC¾õ¾û_ãêOzö;Öûÿð¿=÷÷Åëüð¥'çÑÏüÊ¥~ð;öïõ¹ßyÝk>‹O>éä;^çá>óü¯„/Ýô®ÿxêùõ–Þø×÷~äo~áE7|믞xÝûœðó—»Åû_þ×wOØé'þá}N}Ðýnô¹Co=ãRgÿò;ÿîùç<ñ¨‡ý÷g|üugý—þË#^üÕ¯~õO¾× ôöóü×üöý^uò«Ž¯ÇÝñ^gÜîƒ?|òyGœþÉéKüoüàO¾ÎúÍûýÑ¿}ò]o}ßy/øÒ‰Ïøðôo?xÅÿöG¾óG¾Æoœ|Öãyü½îýð;½æõ¯=ð÷ßþÑW=çßýâ‡Üóoø‘»Ÿxü¿žõø{ßäÏO?k~Ïð—]ñI§>øvGýóá‡\ñëwxÚþÓW>öò¿þùïåw¾áiïþî}O¾îQ|Ý/þÔ/½ñ¨k½íª8ù=ÿ¦Oø¹ý\ÿ¸ÿ·=zÿ Où‡ß8ø‚uýò¿æm?xúýËý¿s¯—|åÌòòŽùlºÊ}_qãõÊ·ës~ö½ç}òŒ}ÿ>Ç=ãI¿ôÔ/œú¡ÝôzÏù‰+}æYg|ûšñÝWÍŸûÈŸºö¾ÿo_úÚµùúo¼ô®—xöÍϸá_õè³ÂÅþéáwûŸ—>ꃗ½Âëÿé{qû#ßÿÕOÜâkÏù»\óN¸þÿýÊ[?õůøï·yÂ;ïûÃ[<úÉ9ëM§ùÕ‡¾ìu/{õß^ïo/ñêGÝûÓïyò™—ºòSsÆù÷øµ§\ýäw]ì·¸WýÚ]>÷¢}æõ/þâc®óìOü~~óÝŸuïóOøÐmïq×O]繟¾ÊÛ?¿òÆO_ïœ{.o¼Ú·^qÒ#nöÖ^übgþþû_û²ÿëä+ÜãðŸ?üЕ>üñýé*78ê£ï¸ínu·>ñÓ?ë™o¼ÚUO}ìsÃÃÎyÅ[¾ð‡G¾ëc÷ºê~î¿r£]þÜwqÞunõ ·Ù?êJó'·ûÈu.ûëç\ûIÇýÍQYÏùä•Î½ÌÁ¼ôÀ¯¼çkÿõçøÆ­—/öï÷ÑkýÂû.÷w¾ã×¾ñ¨7ßôÌS/ýŒïuü%þìöŸxìþœŸÿ7/}þ›O¿û›ßtËc_|ëÓ^»œt‡?úÞ¯>õÓÏû…ß;ýŠŸxoü÷¼ÅC§‡~ÿ~ëÒ/?­_x…ß¾ô_Þó‰Ÿøþ¿žþìSþå¸>õ„÷ÝòU_¼æ_^+Üôò»ò³ït“Ÿþä/}÷Io|îžÿÂwÝðæ'}ƒç½öåw|äáûÝþ›¯âÁϼäÈüýŸ>òæǿ±÷ g¿4ΧM?úê+¾qëzÇ?ëù¿ø´§øÂ)åü#t÷~óy¼Æï¼&½ègÏüöÝÏ~ß_qÜמX»Å«ó×þó+.ùþKúýW¾ÿc¿zÝÓ?þ´›<*]óv—ýOOÛånø™ï>ã³»þ þáC~îKμÆ/¾ý*åãwýÔ©¯ýÏÿÅÛ~öÀëXî˜oü #¯òÑ|ÿ-_~Üý¿ôç/;ã„çÞìox™w]óÖ÷¾êŸ~çÊÇ=à)W½þMO½å‰ÿñ ·|ñ3Ï97ñWï~óÿñÿÖ]1ýkáöO»Ì%ÿë¸ÔôÊýèq¯}Ó=.yòiŸ<úOÿõÏŸ^Ÿ®þÙ‹}êE7¸Ê¡ß¿ÝËN:xð&ûGÞä¤ß;áÖ/»áýžpÂþê5wù¹+ßç”g?àø‡¿õ«79ïÜ]ý]_½ô•þǯ}ÿÁq¿{ÌüÔÉw8ýÅï;ûß»ãÑ_~õzäÕNºòCO¹íëß{¿3Ï:â¶gxï·~¹Û|xºÅ}_~Ï¿ùÈ%Nþ×Ýõ§ÿê¼ÇqíË<ÿ¼¯ýó/÷‰_yÕ=^ò”—¾.ýìO¿Ö9/xßQwÿ©;ýðÒçžt¥ßàõîú¯vèþÌßýú™ç=ñ”wßü¬wŸýÊŸ~ͽÞpµå‹sÝküÛ³ÞuÅ—>äÏN¿ñ®ü3ów®ñÌ“¾uÌç¯÷ݳïwÂѧ¼ç”?¼ÃIÓ_>ï5—½Ô‡§O^òpñw|ñ£?õÊ‹ýÙÑןö´o^öwO»ÿS¿ùÚw?üˆã®tÒ•n<ÝíöôÀÃ/ó{þòµ¿þÁSoùôû]þ·úÒiýOÿÝ{| ^ác_¿Í#nüÉ[]÷ùçðŒ/Þýâ¯úé³_~ð½W»õgòì—üÓQW9ësw¾YzÓ‹~æ2W¯G^î’_yãÝïy«s¿yÎQÏýÑ%®õ‹;xà·Ù»órpÊ{¿y ìݶýïÁ¦½[ˆ!%síÐkdmgWl'Y yÚËë$2í•<‹¬{u*"×½Zõl {sÔ³%îÍó"2í-íƒ\s`-ãµ0…©-LU/¶¶Bˆz3çF/zµ›!f½›Ú3iÒ»­Ç!½Ûï9èÝØžo§-éPÚñÙF zZ½ÑÓ^¨­ñFOkûγÔö|]ôL›·8'~g‰ W¶µL^8ö0·!Åuâ»sY]Ù¼–¦PH·ÿ¤iæ7kë ‘¿×Ö| œ“FWÐYt½ìЫèÆpa.@j-Ô`VldÚËîO[B}^Ê^™Ô›µ‘¥j ¥q¥Æò^-šŽ˜öæ‰-.©1hÕd¤uo ã³¥jºÚç×PûÌ­U¯µÁ„)ê½Ì:ëŶ`fÐ6¼ö{ëŒèÆd1éù6î5K›¬¶ËÔÁ¶ BÒà—6„Æà~Œ»ú0h ƒî#Â3sˆ}áÍ úæÔ0ñâ~¶ùkœGßÖ%ö>7.UÿçÆ “û37æ îO{ll:˜)}³ý'¦Iý!ƒV}³íƒ˜ƒ™¬1P£,M.Äâ¹j<‹e™À ÉK Z}€ðˆ³ú0£³ú0·Š‹úº1+û0·áÅU}˜Ûº¦I}¨mÞ³¶a'¯—ÔÌWþ˜;ÖÌÚ:°—#ŸO=ôÔäR«¥¶ËJá`Së@YÙNjýªÚ멲Jäö…YÍm×ÏâÅœKçÛÜ–cçCº­”‚Vʪy+mc¯JÜ›(÷šäÁÂœžÒšm,Ìi+M‡Põ{z“›ú};ý¾TÈ[ýÖKYS5–<©mµ.kÚ"X{‘|H²WKÑÎ’öa½ ùoyo]}‰ÚZjgÈdmÒÚvyˆKÚ¾¿µÕV¤­Š–[j5›€Å¦)ˆnì3YÖMdùY,Àò¥³Ocy½ “³Þ… f϶ËbJf½öý´ÌƒöxùLIbá°€å·oÖdVÍϦ#ä³ûÙÞÓ¥±|R»”Õf[Èü5M]ÇÕ¿/Ïþ½ÍUÛ¥SŸÃ<ÿbù°Ãæå¢YþBìè@Y¢9¾÷1 µmÃÌocd¹b¤µñLæYˆ¨D<‡ÁŠà¹ý»P˜ãUŠ§¹±ZÕ_ÛW+ÿŠ£jæ»Kc‰ï¥u‚¿QmÞn¹µMÙÂv×Ö…½‚†±r¦×& WòöÚV¶÷œò©MÛ\º ì9Íú½@ÝÐQ2Í ³~Ç»AlÛ¶ ¶—³ÚTNUÛvøœNœòM-á4nIðÆ‚Ø.dHõDËÒبÑÚ‚±@UÑÑÁþElq¢xë$|§êXN*ŒX>5,Iú£ lB§ìQœRê´ß}?ñäÐ3Ô"³XFßV(ó³ªÿª™ÔŠ¡vŠÉ¡ÆÂU­¶ë¡æXTµµ¢öG©Uh•á–ÒVĨ­_pŠ$mñ’Aë,£š*¤çq*ä4DTÌZ;ðd´¼…v×æQÒpÅv\KWm JT`»W‰ÃŠ-‹½jÑg©?5aÛI„àµV¤ãvÔ7›ôˆ>e¡IFkX’vEÑíÔ™ŠE¶¦Äx¾mÍÝm/´í ^©÷îÈø­à÷ iÞú \Â9Ïd<|°L |‡0Åų޼ԠÙ4t¡ ®8 ådmóÙ&>r+Cšó€ž›.úf&Cr‡£ësK TÇw¡+4Í’[»M€s¡Êͽ±N¥kܘØ&£ðÚ aáXgŠ|mkhÞbÃ)@#×iÁm½®c[G+rXfâÛ¶-å MnkСPk'Ë4Í,¬-Þ†Ö4xÒ80©- –±âÉÐþM–i¬Í^t㜘¤¤5‰ÝXxJ}+7ÖöV†BUE°¹N¦4ƒµ£èele¹4¢ñ‹,p¬Y[¶-h뇷/”+‰º¼ÐBÐÇé‚%ä6ÝØ¿DžFÚjc£UghqÑœ”ºmpW\uBs;®V¢Z?¯ŠÍ·…¶Q„¦Ӵ¶ï7)àm45ºÄm»t… §šŸÿI'¶N„æ׶OzŽ1cj%ZF%Øó í—û²@D2~Ž¹IÊŒ׆‚LÑæ«püS‘8í£OÔ¨z$mXqiÖÙGãË8·ýÑT d¤S3ǽ”¥K9l’˜ÉÕ`›8ê¢4¬’R¶ÃŠU-ZÉ ‚¯hhŸÖ0Q¥3L´}˜Aߨd0óš®"BÙVU'ú€iÆ*Ôvrî³lÒÆÙÐgD·•iÜ´Œ°ˆS²dÑèÛ¢ƒ²?.Zal–¨ ßÄåÆe0õãªw¹¬k5§C/¢Û™–&é‡e-íº4ÐRÑðþOzjJãDÑ 8κå63ｋà YBÔ:ípeØ1)þß8tiÛÂ&Û™2 9t‰âPnAÊnîF®슸ð¼*œU®8v¿FP ýãm©hA»\É>3Z[)¡jÇ5Ëî6µØ$eæ—s€f¤»5À} Ñœ8ó$+d•”žÇ`ú»Oü×ÖƒÒ >—& £¤1×F TÆš™/ák˜Šy®Ž5kº:Ì=IÝÖŶ~Q|†w­MèƒM¯Tƺ&®‡ µ맓Öl£­øàùMÙI![Á¤Òi+·ÑµKÅÆRF ‹‡ÙÒÏHCanK[‘Fòôžð]îþ&ѳò~“ž,Â#qŠx£³äÒ z|ŸÌ ´NWÌq”¢ÑÙh¾˜ñMÉ4(Ж WÔI•*ž— e+EÉ4lÈ­(Ã…Í ˜ï(Ó¿$ôÇ65Ö-ŠÇaì´“]2<5FØ¼É ±×<ì¬ù.ý¿±þs”‚ØÆ"E67é”$ª¡’§ºJp´VnÏ‚6+ç ‰T)v¡æ6sA‡Xûn¥Ovr’í:#–YÉ+ó‚g9²Pftº$7¬±¦‚R€Û gv_©Së`*r@7«eÂÀ*O[ÑFÏVÇÚ3Y¾<¨`)ËxǤ}Ðà™àM^‡JÕ[VÏ^”†•ºÇ.ž§ZԘ͎”©¸¹£„PYÀ<É‹ËE×æ.ë¦ñÛ±ðã‹›.Ho š§ÆP[r#¹¹ýÿl¦øâUÌR,æÆÒ9­b{Mn<¸Æ› ¯U¬g JeY>ОÚñÀ½˜Á(Ô-qR§Uζ *ø"çЄ#cɺmö 0øÊ’Íhâ´r”+ölP°H­”,Ú ¢¥èðƒB×d€öd@¶W2 ëÝ S¶E¸wí HÛŠ¢ÿ>jLCH{—áZþÿ¯b]´×FÒ× Ã,WZ¥ÍN.œ×ÒØ7ie­‰fnq6ÆÏò ÃÝ廀ÎriÀÙå週•åAØ&ë¸ÂšäHjZ–Ón%Kp¸k“ímµÿÚ>h«/Uk¦œ°JÕVK®°€Ð[k[¿cIWسi±O `^¼Š8K’U'®´\Ü´:!´‹WÇeñÑ •-«oÔ>²Õ%ijK¸%»¯m%û\"æÝãrWEª?aEw}(^Q¸&ÂÙ§2ÏR‚1±•Ú$ä[[\`V”úï\¸ —‘»u X\ZlØPMqiÚ>Ì>Q¦6§mkkmðå˜í|hkãþµc K)ºb#û÷kiÿ_š­^¬¥¾Û3-ú~Â|-^'Ì—¤6i–Kšj­]ÏFM&¯Cf‡ ÚÉ»²¾Z3ì*GyàkHI*nÅN’ÿ•ª’zÈÏ®îк¨5K¤µN0N¼Nk[Œ»y7Ù§ý²îÐÿÎ*ú*e5dFŽÀ˜« Y( ]zcetŒq†šÀ–QÓ&$ûl†‘³gßt¸p_ÁP_,9*hK”+fIƒ=ìV\±—|–ƒ#&íxê›ä³›«—×1‹-`‹¤„&¸Hs$¯;†Z¡öÌ=àH;È3 Í4YbAëì§N´¼¹ûJJõjì7ëuè(¤cwUBÓÌ;A·®—¤½äÇ€s«#àS<˜F®«é6[UáÙ™JŠöæÙRažìøWøÝá_h’:ÜÛ|Önʼ–Ÿ¹Â’–ðΦ¢s^Í”µJ´š²ÑЃlq‚©’ãz„ÉØöÛDÏ`ÙRôjCÂG}þøîBPx¶ïí¼c{ä_Sm6¸F´tð×wÖ)3%3ù8RrêÄo4ö9¥£Y˜FCÐ*Ad®<]×Yš\؃!øv¶É" (*Už·«hp™ es´ Õ»ü²± ­)éJT%rÜ¢gO=9%]„"™ƒÀi:¹"o‘§Ï¤±Dôm(-ò¤Hz¾ð<ç÷aV$9”£41îžföPé]hA«pàÊ…;"l ;Òòz£i´¶ n[!³PÉ0 ›FÜÝF 㻃ÕðLø ÜÝk<•ÔO:W«Alà\iêiªÑ5ü.©›Šì?Z÷ Ø3¢–J¥Ñ*'·®Ü:•Vžn³qJÐAŒY¢ÇØ'ùeDc¼Iœƒ£ÉÍ:v¿ý23-c„楻ÃL¥ïHø\$æ¸é5ÜyQ¯v›Ïƒºã—Ñn‹Þaùßwºeº‰† ™É9qïäAò‹^(‰^‘QÚÆ›Å)ÕÏN{r‡ˆä’c›S±IV… `]Kì‹äžÊppW$’»:ƳñJ’šWÆ4ÖÞD#{yoîM¤½9l$Õ팭${Pd6öæâ>tè’ÈYdÓÛæÕáëeouNS¿mùБÜò!úñÆrŒü€nSØö ; ­“è$ÐUMA¤³‡R¦‰?`â(ÿòDàÏë ¨˜1qM„ʈGÄ ï@ä&Gîÿ\±'¶Q ­‡ír, .O‡vöG”¯2Ç3ûœÚ”Oõ%.Q‚=å™´Yi•·C/"0ÇoÎÊç’¸‘nÓD ”g H²¨Ùo"bA€‰m!žgpQǺqŒ©2èFYE³#J†51ÍŸ/ Àeѯ*” ï9 ”"R¤¤ÂP¶%z$_›ˆGÀGsBûgÒ|Ò+Ùœ2ƒE´nÛÛ(Ñ¢•¦Ÿè´dÌ”.fŒ¬‰Ø3ä~Æ#RÐ÷Á±Ínãw û ˆ¢è°  è°]D?~òºC]K ·O€ÖÚÑ/-DK¢üŽêC ß˜ÂD™µ.O}ñÉÄwyž¤‰ïrã0FæàE¤lŽ\Ç6Å¥;âJ+Agà 8êÜHØ22j?vŽÕÞ•XEJÔŸ#°T)é Yˆa[tñ‹·ãL/Î(@4S¢L=8"ébV (Öy„’"ýqÞOñõAÇ4ž);ßÉójE˜>¢#\ì}ˆ :5¤ö¨SdpÏcIŒ\MÒSBc'??aú§¨s;‚£@Ý‘bcØׄŠ<¿t¿Û\=ƒ±Dÿ×nÖÙ[F@*2(* f1EY¢«øD@q>/Kqƒ¯ýó¶/~ßØ^¬oÇ#³?qÓ˜£‚œ°4z  ó9–½³r_ØZvÎÉúï™ðŸÆꦟ9kïÃ]&‰´6Â)´M÷*•F¹>M.Î{Â$à¯KÂƱ 'Ô›äkij@®A²o!f{êòјí&‘` =?·¯é– 褠µl"˜*ía‚P“dP%~J]„| –ã¨@%$ø~ƒ,°&È5Á¤æR&¥3dŸU”‰AG†¹‚¢1 MrqAÔ»Jž&Ÿ,ã€:Tè=5! È¿IXÑ$ vnKœ%û‰¡ÙØè<ËÇH$L–¼›{¢B"àC€`b¢ç*+™HHU²¼«k‡»$$HDy<šô!‚o’\cb÷Ø €H¶\l©H÷Â3:y!«Xd,8k =™DHD§¦[.Ýü«ìž‹Ò"A½:;‰m‰³älþ¨¨±ºí pÆ,YLÔ¡jî¸Hî Fá3µ ç+Õ¢H¤äR%¿ˆ(\lÅ~¾¶i®Br ~Dƒ0ˆ‹k– Ây¿rˆ6‹ëlÙ”;¼ŠË–&ɵÀ3Uò”Y>SrÒ Ï]ÉÈ/E ˜Ä’œ„ƒ-ÔÄ¥IzòÊóUrÑœXx;ù„±éÞ AÆóã ÖÏ)/lm§qè¼áówAó]vdÍO’;ŒÞJ<‹„µ(<æœß–;pà[Á‚³¬r¬ ª›Õ(À¼ ¥ƒgÑ T×j½£ñ«œ<ÁÚ é äõíÆT‘¬í†­µ"óšÈf ædÐ1LŸÃ)«i¤g_DCi›$˜‡A)1ÒjÇm¦DºÅÜ«a–™ î ³Õ¨ãKò6$æRÛ“èJ™·€e9Q‰=Šf9X³Q*¡LQî ­‘ŠÑ¶ÿ¤­‡-¼õ¦Ò–YñÌ:ÛôÎ]¥\¥‘šTŽmជÃòø°œˆAä¬"º2¼ˆz~±kug»-Ûvë[/_€¾¨­ô ·œ€²‡)MJë5!#„áŸòAóŒð‘P´`Á 0‡Eœƒ0ç"†Â^³X\™¦%Ñ¿*P*3òï*M‹`Õ ).Ìqà8q^ —+dó4’ÌO3v«À! ÜB 6ž.Ý gaŽ:Bf˜¤ÚKT#„äIe\s$[`ÏtÁÓ, ~b°}DÆXô3ŽÛ u¡¥­2Ól­VsOߢ»­ï%¸Ò¢2:"U„l—ÁöÝí…#Yn»ô`™uœÀü­v]e·¯WçD2­+IÎuìšÔ‹ÂHcá"vî£RF•ï¨lŽ6MÀ~¡™8ÙmDŒ Žî‡ÙÎ['as ‡Äë;.¡Î÷ÿy=ÂÉáôYœiž·¹ÌNT$k­ ÜÇòÆáé£E$aÐe žF%7Dz—ÎN»ò<ÀVE °qr 9,•ÉzhëRëè­§l<,-»‹]xè£=0Ä¢Pˆqb’‡,¨cµÌ[i{Q7PÔÅiàh«ÚÅ—øÃóÎY"û9úI/¢áô Ũbé€õÄuv¬kø™INÏ$´¹Ç¥Öî%»+^0kö"E$j 8.…ÉÏòGDÙ²¹ "Ëûg! $€©ŠÍ0j)5=2ÚXå×Á(sYlÂÿ.[‹à·".#„ªˆq®ô˜öiVÜ‚øÜmQ ²b3Læ,³2^%¡¿oNֵǩÄOˆ™¥(}–¿- $ÿ(QZVú‘Ôöž¯ŒoI5jLbÌ_;²G|+ÁŸdàWB6bVª ͯ<ÉçÊRÊWO`ά”§¦ëMÚ‰˜.bù”H*ç*;?5˜dÀ„¥£%–LJΠ“”D÷&×4r¥•_nLc]’?ÓJB–É_@€þ‡eÈ2¨©Ê÷A^µQF$²ü H#<ô+Ž•í˜ŠÆBp¿}4H¸6Ö8 ¸Ø·²v|qÊÄ'‹À‹Ø Gø#퓦_³Ú_ŸbÖ»óÌ'¯¥dÒÜý»ˆ%Î ‰<öÉÉ_.ýD)h õ•“ ä{.ô[‹ÇЄj\Å èË_ ^»¨r©Ry“Š®€°FQÉÜ ÆGá”°„dDÛßÐ{¢ýeñÅ/ÉQÊvb‹p+‰ÉÜEs¥ÄkÍÂ"=Æ_´ãqf|FsÅšÙ>Ä<üS ö?ƒã¤aˆ.ò-â°q'&û1Ç‚XË@¾yÅjìãÇt8¹<Á pª}—ÝïÆ8O°W†tÈŠA©–Ÿ¥ÑLYÔ3PX¼îL×Q¶i‚'{L±^“œ 4pV­#Žð ;-,db,r:å“J “/µ. ñ0BÙaqßÊPúš8ˆýtM ³%÷ø(çâØ”GíGdŠt(ëk(G!AáBn®l+‚ Û&]{*¡x eÏ2Q¥â$€Âæ&ÕÝp[P³ÚB’”µŒFÇ® n„o ’>$ùyáÏîÎl‚ACqV¼‚¢ÓÆ&.Lï&_9hV›Bƒ¤•Ê»öâ‡Ág”“ÜO8›‚ûIZóß\=öCA|   ;´æg_˜ÄK ¥ ñix"ÃÚ?¨º"=6û4È<õΪ8Ç0{êYÝ£P—æཾ˜“Ú‡]tˆ3¨`/'VÆw‚X`c…z„¡î•0JI“ ¡_ÁA¹¬B³œiA&ÈæB ÀC#'™®3׳›º#º—Å2gªoÎ,|%êwµ«2 DÒ pô7±ÑßÊ)Z£…ýM…±† €ˆ$;-Æ,w$ÆήPij²¢Õîì¢ÊÄÕ9b‹ï8J[‰f’F‹þHúGx’òd×,ú#3“n¯¬ôÊÈ]àÈaÖv)¬dm»‰®œí†v(^Z‰„²Û¸ŒÜ¢ˆ?'E¥èBN*ÅA3#9â3ÉaŽhZ´Öðj¶cHš.±}Ñ‘¢©gž0Áãò°4é$WZ‚I攤D”“µI ;©¬ K/¤YRxb^ƒ$ÑRú[uäÈ„ÚÝ–Ð,u"2‚/äƒ ©n®÷$r£çŽ£§FnUÆ?•líÏHNÁ N%E0uDU£µ× {3åêPž‘¦‚LÒ®¡fËhÞQàÒZ¨Í'£˜ý)Mšš}’˜D]I»"¢-9*HÔ¸´^€œ;•Àî)5A4¹N£Èü*Y0nŒÀb¸#EIUl!G–SœG?“ë*ó¯TÚÌÝÕ Àw­¡•&‡Yà ”æ”˜:,mƒQ~ŸvIéÞ²ˆ*o%2IBWŒx#Á•i )eV™²¥ß5ÿªµÍ¡oÂݤ,ê”ä’UƒpÜü¹ÅEÇO’»Sýgâv¶e2õ„oBJ»& ‹…Bå°"S.DTŒ]R)³”柩ñÊùH,¡Óåâ¬ù‡…ã°c`ŽŽ’¥úHt%×<9QiO Ž"— ;Fe&ÐÑÑoF>u^á}Lgú4¤e´°¥„°‰€rv”Tf‰„Y}À\e÷á)¬ßÝ7„’²û†y6—W´Æ·‘]…©0¬¤¾±èEr$_®Eÿí_ó ­kö…>[h,Ql¹­=œ•0Ô¨®„ÊPQ%¶hÑÅnéÁW#w_‚ë'*§–^T ‚Ñ]˜$1$ ×b ‰õt.ÐðíVAërÒZ@$ÑßI:w¿VbmÉãÅM/ë­,F4ÀBC*òA$X;âdU"\©UÌîVŒò°ÚR]XJQ1–óï!•Ž!dÒd£*P·Hûý W‚³’åäËš ÊYc*Z³:ÐÖ¡íƒ&6P-@ç—G° óQ1‰¶p&€ðØࣲò’Z€Rê¢e‰…Ðj·ça§à€ÂeÒ¦vÕ¦„”›*=—ÆG"nBL%Ûפ³±&yØ2tð;ª&Z>c[ý}Ø8Æô‘®þ>œýeÚhÛï°l”­ NK‰®þ=ôJC¢£±21öE¦Å¹zFÊ=éP¶ïÛÎÃèC°ÿA¶ÌÖÿÉóOº,cŒSŸ«Ú à™îßæÔãj´¡Š˜ZË|̸’©¹(ær’îb[6…2¸š«'¬}Ó>2¬}‡O6–°· œb I¯E㥥øµf#Ø3Ò8oÙr±¤±¢ x‘}íUCƒ0¸ýkÀj*y‰›cÎsß3¹Pk1n;l¶`P·ïS"¼•^úŽ­Pm5|VV4,}Û×d)±îYi‚^TÝÄŒZ²¡‹‘â&ÚŒï@§ŠÑRõÕZk´x(¥(–…³‡0«S…`Ü¥_ö!€òtâ Ú9Ý…½"iÁHàÂP ]öª\Er¶¯ŽØ&©Hw²›‹JðP¡H§Ú0ÙÉE}q*ìW—ŸÀ8®fÞ%œG!7y€Ž6»úAcÙY! T/+@ó“‰É¤½ÕU“ÑC& VeP‰`xƒÒPÖ4Š@²´¨’ñÐ@HœC  ˜GŠ¼ÙÚƒãŒk+=5*†ê3L%»ºŠØe˜Ì®;G œŽœL,›på+sÉÀOý\<¤¨J· §ÊU5¾ ñ†8‚ÐyVx•y¡¶¦‰QF'ÆdýXmòC±†o®Æs.ŽÈŒª8"‹×€úß]X¢, Šy¹:Šî“6Õû8,q¹é± ׳¶I Œa(6¥9EÄPZ¢çñfURÓ# Ž\œã+ØqÀ—³6óZ²Ê5Fˆê¬< ?Ë•¡ágåÁ±V·è™Ûu‹©DZë ›³ñk Þu`w%<Ë‘;l¸dÐ ­~åaþå—!Ô°{fÉÂF¤eU€ ;6'yE˜?¤ü’˜¸‹eÂ)eEüÇÙnîü,?>#’YÚ`Lóæ1Hô<¯ÇloãŠaekÍÜ)…ʯ2˜¹Yªx™›é(!4óîU€û9;péȬä^LÃ+2Ûc¶v/ ¡°i.¦ñ»A-qÔûˆˆ£°æèDa‰Y—΀‡d5=ªÂЫ–z|^ËOxØìuiô<òÕÐEççFeoFljñ{0]zvœç³ƒb"c~šsfö81€rNÒض—†Øh¢–§.²¨òeâJoR4=w¯QTîÃd:÷lxyƒÛef¼Û%HÆí½àv „t»à¥àv—©£ˆ-tùIÆõíe"H6˜„ü/ç%E·“Ò:±À ½ˆÄYÓs/b'¯¦Âk–GÓ,¶/š9S“i 7VÓð,-¦£u»)u`sˆ\z“ÍÄÕíÒ£åvUµÖ4ò¶ÜnamuÓ¹ãÓíü ¨Nø÷‚èv÷‚%Ý âPÜ ø÷‚þ0÷ÐÁŽ Ö½ o̽€ïÇö=´¶(IFDDœ "…ÏÌTÆÂÐ_ÛýaÐìzÄ™å-gû_éK‹¦ñ¼ÔyèÉÑ6´¿¨š7¼ûjfwE{pÆj_/ °ÓŒ\Ë/ËRšÎCd¶Ú_«’œ¦¡œLÃg&û.~¹˜^G¤®Ñîc#ÉO£´¼£Ú%ÉÉüQ58˜‡ïïN¦YpÖô–­ˆMDÕ4áuÕ4àuÎ LOA‚ +vÿt%D{ø°£$]¾1ÛÎLJû¿á+5Ê"ê­5š™U"%(“ç|I½^4Ñ,1yÎ"Hžó>¼ÍGî⼄*Åd$ #ò=û¾=y{áé³iøù•‘Q m=öŒCÕʶÏÕjíkgôß>r´Õº³±2+Rd{ûòá¿”MÇ$/Cð™ÀH3æ°P=.|LaU"“q€èÌKS¢²A”d¯K$Ò@V3³PŒ6U§O(½N8ã L?' ߤ<˜šŽL€ð«û6¿£iõ×Õ}Ì{u±zHËY Z®býœµ!:¸-ø/½¢ÝÖ<¢ÇCÛv[@>Ô²ÑNóÀ5 –u¦õM¤|8Æ%Z¼wq°_ôìwa81EÚs‹ëqf ´êïT˽ûŒÇºì|әǢ{?áìý=ÕÑçì5"½Ä1Æìøé:9qÊŠé0æ0çm>s_#x)½_DOc]rGžÊXÇ´Î;ô4Ö݈ÑóÆ©÷×­;t<Öcbà=Õó2×Á«–'‘EÖÃàížÆczêü¢y .Ëì`d öTˆÛþbÝdï»`9û¤=)eÈqfÉǾßq×Ñè9„4z…0©]ViU”!!¸ŸðH÷3Œì|Ê"Ö€¦Œ‚‡Ö@8„B‘ókû×¾¤ZŽÂ_¼òð£;ªÁìàažˆ©KSð"–{>ö†s$ÿÈ«Vá+üÑþµ½–†òo?0z!&c ¶TífFÞs$ …wFÆ>3Ò 6‰£ˆäá‰Í§â\,î˜l¥'ìHc/ rXEêÅ‘lÓRGŽY)ê*c7Ö(¶š”uÈ V™ðø´ÒŠ¡*muŒ'Î[®SšwÖ¯¡Ò¯&.À‘ü‚]hdÌE{ ìXE0*ov¦ñˆÚ¾’õ%{"\{Vþ4®:”…-…^>i6`Žk½F¿²^ƒ‹ÜØÔØ“f%x^¯1¯I¤›×`¬l„Ã1ªN§-pëaÊc²á¾é•(åÌwõA>ec‡€æ·ÁM¡¾›èïÛën{Rq^NÈŠ„¸ÉùP¾w]™æqTÀóNÄ€Ò㜩‰›Š‚ÁEÐ/ûkÂÐLæ_†è‚e|ÆIP’¢ ¨œï¥Ä¥Œ 0as/-˜Û•} •¤~Çò³\öqæ•,L :$̨o(.êÉûW\ϸHafèZ9u°Ÿ‚ ‚2¡fvYlÞ¼¢M¼|È%õ¨Ì©lNà1îbm˜¾~ËJ`˜F¹KŒ± °´ðæ >3´ ôî‰ ÝáûKúÏÊôî¤U×eðSºb·Ô)E õ‰ #AhÔןÌ0ìjRD*ö›åö–#S—lù‚ªÜ•WFpˆ•"pÖ*}5ªÑ Wòí s]„òÌ#yJ¨VBQɲX]ß&éÆ0ä ¦ì"M¹—:g…‹–‘\ä| ˆ†õ‚€–d'þ„Y]H»Å·¾T¦ÝVóB<âatéB¦Ê¸%°J99áˆáßq‰°‹óH'–@-ѯ°@ª“ÃC,&©@ØÒK²Mà º»‹YªÅ®]–ú±–å€ì2U)¹s}gÂ’)ÌG7~°»>²|\útgÉMçË/ä6‡ïü[Þ˦Àxœ ‚’›t¦ÓÄns™¶¼ßh÷,óÚUb•.èèò;äÁè|`Ü~c`'i'Áñƒ0Qf'(O>­àëRgÞ=j×7‚µRJ"ª…ƒÁÔA:¯c .í62âÔagøñ=$ðWBŒ—«(xÇìp äXvxF”C-%ôò\ ñôÄ=¬Wˆ:$pêAŸ˜ éÐ\ÁVë¹Ù‹Aw¤Òg‚sôi h~`Ï'O»se„˜?ÁV(mœ ÜIð£Fhõû gÑ=ûØék8ðì~Q&²‹÷3ãÓ…pVÞù¤lN,Vô  osuú*¸ÐSñ\bž½äðf)Ëû-¬¹ãÝž†•r¢‹œc…£KÄR¥¾ã!,ûí¡a º”Èþàîä4>¸†WEp9Ÿ0L~Í‹‡\.G‰Ý@ø›‹¡Rç >3¯`sáØÊ qHÚIz†Ã~ÃJwSꨠz@ 5VßÔ¤!aa¦x%@œ}«*H"FB&U0' qÒ‡ûíCZ_»ñõv‘Žsft…©¨ 3R$ÿ:½ ¹uYaÂr'ßLRx;ÛEoòµwPTæ4° —˱OÛ"“ÂTµÐc—?çÍ'^ÓI%ÒÙg s™Ö‰åI]ÀŸåI5Ÿ„E»ð5‹Ky½X(þfàú!Ì>±Qð_îhÞ˜˜¤ác븞$Ûrˆ¯+Å9Á",¿šõ+jRúYËÚeÆ×$Ù„þ¦µ²l¦V•e°µG8Ê+Æž®¾>$ŒTEX’’uu•A¿ý-0­÷<ùºÀ|†Qav•eŨ<Õ¡»d'ÄN,ê{°¦< î2nŽc8œ+}(»$ìê,·/¿È¾K(°”¸ú@¸†ï‚ã'û^Rè^ë€vÿÚ¼KëðZ_V Ðs½X?i~½^ —Pßs”˜ñ¢ÕÎ Û €Ä¹êåÉK?ï™-•U&ˆ7Ä9T_èóÉÒϾשpµ“X{õýX!ûB^–¸Zb/¥yó%Q’/Þ`8¹_Œð°ïc‰!‹Â„_…Ì"Þýjã‘ @ü©o(ª¾c;2µÔú/6ÐÉ€¶„DãÞ¾º†zRò™ ÓWXðÊÙdsgbz¨m Ï7ßuùw`[ö·G¶ßËø]hAüfÛ¨û"åÌN¨L‘ž&3Žol/æñ¢d‡ËÔ¿ûI34ÝÞ®§Uœ¶c¼ˆ\Ìýíú½qÀKø½RÙZzºÔAÆ‹z®ò)ô?ÀiýÐIkÀk’ÓÎë|g¼¯ /øÞ_v¾•{+q¼{ß´êTe(;AÉ ~CåÇ—ü6¼55êíÔ«ªeè„A'¥[Èy£c›A’Éo³øˆÚà—¼az ;oèÞñ¶ÿûfñ_rOã͉ÊÄþö¼C·'…öM+í0'&Ë# ¯ºŒtoͨáSªI¨Y»JãPú±f„-¤ºÑq¼ koòÛðH-jƒ×«³¾jÎì­ñmt” Â~§9»¬MdI¸ßEØ[óÛH¨^ü6èê·G¥­‹lƒçîŸâµØ‘÷3‘‹U§Cîå¬Y0:nôÒ{[¸T¿z4#-—²&-âuŽö–—:÷¯fUßÛ7Ý+wÏLTחزÖuôÂo×ý6èä§bO%q *#>ZÓÛH¶÷}U¢="”¾©U=× ÍËFçþ6ÒùŠØ´Þ(,Wª7xg³K‚ƒV´!GÖ”wkôÂ_E(»ú« µ"½¹ü¤¶sºˆ§2Ó}ô¼¼‹Šycƒ¹à€èÙEÄY•J<¬¶im}ÒWÌÏú*iI=ç½ÞyÔlÛz¡·Yíjá5æÕH­Å¥Ï!UXÛ´¹ al]à–Ul|ôÈ-´à@O‚Ë«+µÇ­´ùè‘ÞFÈeòö;턱¼N™adiƒ¦“ŒÂ³Á–=½Gj:ÌF´¯„›™À”I•ïH^]k’lí’ìÂýóœýøSð” ´ßiïèT“÷ûóFOî!o(F˜l¿Ó:f åœ%SûS@Ø´K磠¬À{[/ôÕ… }•´öF²3F*“*Z::QÙQö•{´†^¬Y•sÐz©¼cÌ&ïZ‹Îþ=;¯Õ»T7:ö¨ÏNjA´Z`K®ÌÒ¿Š‰˜¦“u#z—¦îë2]ÄSôŠe=%ÚíM½,JÆÑk™é¨öè‹~~îÞµm j–Dòþ õFáÝìz£¤^aÔtU ÒèýüÒýq[¯Ý‚£ûƒÖ€X&÷ <Ù¦µO ÆKžcÞï9î½V ´\ªZ -yÁJv©ô~ôñ©aÓ˜ö\&–§q?è%œ7:öö¢axû¦ã#ÚŒ dÑ—0ˆæÞ̈·;Pã¾JÎ1¨…@mÕeì %a Ÿé|¥­¤ø¡éà–§^ËÏ=õ~Š<ˆ°Oó¢&†‰ô6Š7+•Þ´÷;¯[÷~ŸÖg4]Ü#r<¶Fû Á˜ýA³ –®gñ)øDu¢Š&ÇfBS•¨¦1ø®1}‰¥¯«ÚSlö¾ƒ>y{–¯7­kI඲=í¾J*Œ1¨ìx$íûBŒêþ¡¨‘ó¢Uê€÷çDŨè$‹ È›žÝ£©W ÝFàÖ&•æÞï´ø•öouÿè+ðµò(N¦:½~~íu·¨øîáç ¬€ç.z r@^Ó²3^d¦…ÞîÿÂÛÄ*.dº§£Dù>ž¼C÷/!ÍXýN»ç™Þ} ’CžÓ¾¤$çCîãYwèÞ“úÝWÒâdÂÅm–ÂD‹Jñ0]4jìR¤3aä¾ÍE´öèÄèiòósO£eúÞ-9Usí»qü‹õEϾ^@T!qx/Xœ%½¸ß±;èã\wèÞS/êisþD–Fˆ­ÊŒ˜–ö>ñb”èÞ±üBÞèÐ]"ð¡¦Ô~§]‰ˆ³áµ0‹ ‘×wDYó‰Q'ƒäE» ü8òin£QËŒ\&µLZ°>U‡v•$VÆQ´ ~@‚D㸠|up¿ieR.¬¶»ˆæ(ËÝ{ÁJ¡g„Ìé+‹]¸i—Áè_¾fXECÓD»dËÞÛ¾ˆqº†Ô?ß/ð6xªliÀ›$ƒˆWéðˆ°_ß Å7®J‰ÊŽu]]¿]ãÐxŒÙN1xR‹Zf©âLÔu”-Ø7/ºŸ\,³Þh¾àôN“‹‹qd.ÈÕG¹]¢¿ZŽŒ:©e]³l´kq©§˜#×¼"- 2Á3“-ú Œ­ŒËx.ð|äð7ï«W깸¼^Gø'ѽRš¤·¨³é^ÔkíW hœ.e8ÆÌ––~™Ù2“–zq<–)õí ëHôa·$*‹~¥ÐK}1H3£ŠÐj™#³'´R-óøØ2iåyµ™Á³LµŠ¾®d)ýZǤk|KÉ:õ¢¨¦“\Ö‘¶t¡q’ž/â)bŠúDZp<`,ULLÓeæŸf=Å^v¯ö+bLG¿»Ž‚=ÿ¼C›tÁ̪^”Ø/:´ó/þ%÷Ô°N«¯¼öH²ráEÁÚs¢%+y ½Ëe¢RB/4$Z«»ðzM­î˜õ‚W«&õ×Ã{¤Ø—†p›VËy\@”X]<õ⇥_ŽÄ|L_”|R´|v‡T‚1l¾ßií9\Œ™’¯øŠ,:m´Ë"ò*&%R,¼âH`yÑ^ÛÄø‘ÞÕ(—º÷bâå¤êÅÄ«›õ6 žJjšÖ—°s­;´ó/¼ÍQ’¡¦Õ'^£äµåí‚dŠvÉÇ8®÷Ûæ…- šWÞpÐì“6BÄK]ˆQ´ä)/1R^üRvqGÒ:™äé’@š ÉÙ1/êÅLü•zÁ‚ZaóÊAÅôLûÊ …×-¯¢e¯;´Þ… Ⱦzh)Ÿ¦]6”EºŠGã™P*côêi_\„G]ËÍØzR™=Ó."Š hï½MÅ—!‘–”eÄ´ØãñçQ€ìO°†ìêýAktØ×­ç¤ÚN«ˆ‚j;—A5-”:Mú¦ëW%—E'¿»ô„ÜmŽÔ;Ć}Cï°—t˽&£‹E÷Ò¯ŒéZšŽámà&|ñži} ;ËEJ˜ä\\ØU´æ;O£ð°çhÝ¡‹[ÃND,­M,g¬CvÒ hÏRD ·†Û59™P´gƒå’]‚•˜0íkqM›=_ëíÞ!_;!c|¿Ó¾à eƒÉÍñò¦]D{Ï…šgâF\Œ—´¤8“Î]ÐU3ᢸ}VÔ ¤¸cÊ÷Íyá•r³Ë)aê>JÓ.ƒÄëP]fiXCÓ.ùƒ¸¿0”¼ 1RozÒÈ°]þø¼üØ_ÂÁ±?hõ:»DR%fÞh—*"Á¥“€˜Å ¢³ße ¾ÞŽ¡ÓêëÌ‹õÍ>wê]fõN´zžtŠ­ è|3­^@7uê- ÌÒ¨E÷ ÑÐ {+·í«ôsr1.Óú/Q×Ù0æNoƒC¡ìZ¤Bk4QPÝ]Š‰e0RÜhTƒžºº€Ò:õ²¦%'x±½“ƒ KÄ÷l¤'Ñ(›!ý5­½Ì8iõÒ`ÔÅòœª×•Wêª×µv4—äZ\¢]ÆÚ® vÚùÞÆ~…éH»Uée=X‹Šä %o!´]àÔóèP}NÕʲÂ}±?h½Áâ%ž ¤=Lž Ñ®@ÅÂûú*aš Ó3vÆÚËø¡G.EÚeó »\™æÎõ¿ú<ª§‘×[«§,Å"]¡ËÜËÓvA@`Øz„cû×¾Êf§õŠÖ¹\ˆ°sYBæl¸¶˜hõ;¡x‹¹•²¤Ó˜vµ­Ü¯‡ßæW½˜ª®îÞ´ú"ÇŠ›$–¢qÊŸiõ4Œ’3TŒ²™E›ÃÂ(EÃÛ­³œEë´bI›É#9§.Öç—=%R?"ÃR•Fú%¢æ„Ä3-™”‰Œýíþ¯}´4~°Ó“èÜKî°ÚHö5¸¦ƒèµ—â¡ —ƒÎ:Óê7Š»|ü˜_õh¿0k ¢ÕovrʧŠ ét3­^ ›HÈ ÂO³bT¦]¶“ŇÄyP¤]öØ´d»ŠùÒ>Ω´ž1¿ê) ªõTUÙÔ‚J#åöULDšú8û¿ð6³•$­L«ß,¹¬s—ç—`­~Ýé !€$uI[ÓêweŸ·ùU/x-HÑD«ß(Píë‚]jÝ¡ÕSìBÅÏh eÛû¢uº|”¾ÉkG\x•´NC—•Ò79§’ÿc~ÕSpL”žlZ_XôJ_ÐkÉ*ѾXcbVIê_ò¿öU´ÖE¶MËž‚–uý1‹Ùf—ËWÉ,_܈=©Ü«N«ß‘…öôÍ>¿lU$Ú"^.ß‹½š4K¦'Ñ,úµˆF¡/—ÍKKnÇžu[a§£èQbœFuVN«×ؾ,f̵z ¤õñcÑIŒ´›dÑ.=P¶×€”èI q4Q¶†á¨qwà×pB‚û‹X™Ä¬Ë•3Ì\•¹“ÑHæ%:“D*ƒòEá”kŸ€À+ßô H“ÌvBSàV‘ãc$•Ä&'8!ˆ«Ö{¢ Çx®÷Æ0Wµ;Ù¤>@'©:Ï q i%Ý”õ)þ•2Î M~Yú\Ýb !bý•‰*L 'tDgk˜iÎDFg½öÁóÞ]¯T¯RV¨„d 㸪ôŒ¤.(äª= Âùȼ`B¬ÄjÊž3Þ~fÖ-;í¡C¾ HëŠ\;‹ñÎgd£% ‘T~ Py ”—3ë*WT½X§AòVõ˜à"fÐð6ã>…t k IjÔðßz.°½=C¬XšœÍ]™óx‘u¿V¶•Ø§hÌ3Ë'ò*–žÝ¶„*ºoKŸ[§ÑÈ:šæ°.(ºuSÁ?=Àœ¯UäøIõø^j.‚ZÈC}cž±ûF¼ú&RæÊ”ú°$¤ïº˜̤Y9¥Ît¸ï!Ò‹$ â#‡JÌG[;9;©v‘›u£ò‰fbéY·œÿU»pÍiœ›ìY'cÄí5àòü1AôÆn˜µgWG'Ë:ºŽIñ€æm˜ó6ø:))ÛÆœétBá2èÔPÈ…ƒú¾ºTûm²òãJeH{0…d·É§™+–a˜Âì‘òÖí¯ª[Á d³¿²¸vDíTkméy¿{¾é»é‹Ñ¬É=ÜGYd×Xó¯ý2¸Þë½™ü×ÅŠ{ˉ­HïŒBÙ2ûú˜¡q¥”¿Œ¿ ØÞèUÞ¢ç-<Ä1ÇÀP~äåB.“džZ;HVÕ@RÊûË:§*µ!2®ãákS“ÞÀúý–ðñ@ùTí|½Èu< ä|­l+[]°;®i3:©¥âè´V}tÌ•p1ô1:‘.ÅzÍT½æ“nŒ.iÌ“W ?Æk‰·=¥eö¤†õš+О£¿\;l•Êt·ÈRå]gx^¿÷Gú`ûïŒZÇÎ{¾»#LÂm‹œûl$yøšî¶äÇŒ¿Ø§èòi¼Æ«ÔŠ¯:›{|À—æÅÒ»Ãõ"q;gÙÕ@L"ÉzáŸhTÝÕçRÉ,®Œ€ì}[ ©:| ,ã5ÕkáÇh(ª‰`«°Züc_ßèÝ`q0w5{Ü6*@ºGøUÅ·ú³z¿ÇÔ_ô÷xʼn~&©JHÓ©E!Ú'ÆÆ4“bùyRÐÖ NŒÙϳ~Yê¯u’cÓ¬ª­ƒ[Œ–N©~þ¬ÊxGyúøPÍýë¦0EúkY÷…d¢“&‹ä³jp’YTB‡‰®$ui{õÑTJdÿZ+BÒõ©–Þ„h|UË:o/ÕܧA£¼r¼BÄ¿ƒìógM.|·îPbµUvi>&áHõð zrY—Nirñçyîï¸Rûº‹¯›jMöòHeLnSïSfaU=±ŽYDro'ë:¨cÁù«¯QAR`Ù[‡]ê‹LÂäy¥.ã¯u4éŽ.¡S(9Ú]FÅ+wyÓ«Ïý„¾ÞÉ<¦1ç¾Eiéú¢•Ô§vŸrŸF|È—›Ô¾þhÒ]ê蜾Ä;Fõ¾8®â4Ø÷’êv¿õ$Y†#º“L סô.»S¾$xùŽ:…©£øzMÖÑ¥Ñ嵋’Iù³¶oZROxÑ\¿¯dƒš¶ŒªÁ‚ì_›Yöw’ù=ÖªnìÈU'7ö‚GЯ{ÁǸú«Ù _]lȳ(Í þZG“šºÄN öB{}^à[´$˜s—Íô¸J•ˆíÏêÅ<&䘂mžQöÄ#\Ò#D"ʺtʃ™»ÄÄ;®*×W‰W˜ ]B„ä‹BböW@­ã¯nn C®ã;žüÞKv™×´«Ë ûHø³XwÎôÌc1yºÉuH\^Ž.Öé¯©Ì O2V9éÈãñ3)ã$zùüœzF¦ò11^ä“(‚¬*z,5÷¿ò^†è"Z¹GMª¼×në ó.aw‘¢>&Q°ÜUÇmêÖœ,S§¨¢ñ¯Tç‘ÓÙ¿ŒÚ”bßì» ãv(¹æÒ¿®\p«öb ™õ%ЪPÍ艰ˤBïq¦ZÉ>ÑþbŸ4_©SúøZ{“zÇ •iòõ†Ñ$_Ë=Ï&(OÒK›{ =M t”í¾PdÖúã¿Ib1¦ìy7Êö3‘2úÙ ºù3oŒeØŠ20XG:!ÿÊßXÆ‹ë0¯æ¬NbÁÔég&–>Å òÒ0Ý°z²u7&[ÐbL¶(Κþ̹Ô;j2NÕ¼=PÊx­nFÁæ­*ÞÀ‡çi°ú¼-ÝìôRö–¦L7üúk,œ¡¢§³×Ãw:Õû-§ñ¥™IÙjÀ™ÎüY—ݳâSßÂrò:F4yéŠ/¬ýÏÀ2öƒ¯()ä)XÂØÊÁ£‹,õï‹B›úk¯ÔqILïeï1nPò@–: ®ÒÏüZ|téü¥ZæLlãô3¹nk¹:¦‹ªe"ÿ°šêjdÉÎïp(”ž3¥ß™>„› ÊäìØïýyÄØúwÖzßS‚+tËD¨K/÷çYS×/Õ“fËÀ–~Ï#V9¶‰ßQ8VÃît.Û3¥ôŽÞ¬¨T:Ó.<ÃDåèùn(“ßtçØÖ XGײ®Ó^9DC¡Bd8W¼® ÷w ô~†uë?ªôgàÐè}f0Ï}½,ý™Þg¼ÛûÌ`¦û‰¶GŸÙ7¿‹ž¶C’½@Oçºõ´n½ˆ;3wfÏô^àÝѱn( A# ìgpÐôwQî¨S´Kf¢n¹û€w{ßðÍ>s£ÿ ”õ>¸èÆuçKe§…²ÓrÝéѼÓÓegë62Þ„ègëò»„où›¢Õžé}À»£oëÁÖŽ  azc«ä>üeglygÌyûVÈëî,®³6Z™w¿«¿ˆoy+m/}X¶>ÂC2è´µWvV«„mŽEk>ÊΪãÝ>Ïz^Ë6Röa<3×¾­ä¡rfõF¡ ÿ®ãy¿½Íl »3Pwæ¼– ÿeÒ_væ¹îÌ3ÊwÚ~·—î½}u™æÑè þEk1¯;ßZvÚÀ-îq{†7ñºT6 e^ ÑZ <Ó×ïöyÆ7ûü£­AágÔÓ¾ [ÓZ,ú*߀·w¼Q·/¡zÐÎ8ÓÎ lã{ Ps9 ö{kÝfÉÏýtXË6ˆ|ô™A–ù Ã6“kŸáÃ;m zYú3}–ðn¾ÙÇâÿ.ÛLªÏž%–@ôzÆ)žÆië]äí ½§;küüè)wè`kQß·,¿ï°]¯H§wž©£û0F³³æèÃÎh–±j˜ô1še¬GœÖ þî•å_øÝ}ýe´½ìô‰¿×ñ¥ñ;é²óŒÝŠ|׺w`©÷à¥Îoþˤ¿àê ÷…ªú:¤6蚶gêÒ9O·o_íÁW—7ÖíK# :l-£æNÿ*ï_%„S;@7ìz­sØú‘9{•¦¯®;­-;½˜·Þ%ŽÍ%ìËö}ÑâÂqÍ3x·¯AÇ^7‚M£ýõ¹óLéãß½SÑÞÈë6`7{¿ó¼!ï¬I.Ûà,s”·1ðVaöÞ¿y“:½ncPOÇòº!¯»cà_&»Ýòè/…w¿ö4õi;›¦<ÖôöU @: ^HèþÆÌìÉ©ÛWQ»³·Ñ ÓÖ;$MöÙm Z³‡gúìáÝ>3øfŸ±¹¬ Øe†}î³·Ômö>ì/Á^žm KÞÆ°¤m KÜÆ€Dî>ØQ} ¢}‡lØÆ°Äm KÚÆ°lëÉ>ŒgêîPw¤ae ¾ª&l_]ãöUÞÓé2mÏH{ö:¯µl_­eã€4L¡}_¾3ùJ£0L$ÿî›6ÓéPÿ ¿Kzç»yç/ùÂ:bªÃzá]žÞÎ4èuX/)°uß‚9í˜w¼«·ÊöU”ïòê%DFr¿FŒ´"‡!›EðK'Î…Í€À±Ó›M$€§ßÓ°^L»­µl}XvF3o£ýP6m£‰ËîìÅe›×˜vg 硳*QÅ…Z˜Ø¢“Ž˜ŸÞsYQ;ô´=#‹Äpôuû¦è^ÆA¶@OæíTZON`ZÃà­2 m9•¸C§gÒö®l‚¼C¬“† Á”½Îy³:” 7æ¨NÃ6Ie·G;½¶•²l´€,ЮÅwûÕikmGÛgJíx&oï"]¸StO£ÝúPwfÂvÆhkÛ}óÎhêÎhêÎhêÎhêÎhêÎhêÎhæÑÌ;£™wF3ïŒfÞͼ3šyg4óÎhæÑÌ?6Y$ÍLÝ®€ˆÛ—æykaž·–—¸õhÓæÒŽÍ“–°C§gòöî’·oŠîeN¶>àÝÞ·%Ìc4£ÿM×/Yg§µe§ëwÀ$»Cs![ÃÅ¢ÒÖÙêŸhJÛxÖM ç7{ËkÝ¡wzg-\¿¯;ß\wÚZwú°ìô­ns1ú/8øÿr¤F endstream endobj 6 0 obj 23467 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:59-07:00 2013-08-20T08:41:59-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000023771 00000 n 0000025341 00000 n 0000023712 00000 n 0000023573 00000 n 0000000015 00000 n 0000023552 00000 n 0000023835 00000 n 0000023876 00000 n 0000023905 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<10531989216D992184CF129D91289DFD><10531989216D992184CF129D91289DFD>] >> startxref 25511 %%EOF ast-8.3.0/sun210_figures/overgrid.pdf0000664000175000017500000006452313004147321014331 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ¥}Ë®%¹rݼ¾âü€¯“Á÷܀ͤø<°aô±!x ß7×#˜»ªûZ²-ᢣöÉdò ÆcEð_¾ž¿•¯ÿïÿþ—ïÿñŸç×ý_?þåGõo¥•¯:æßÚZ_ß?Ú,ão#î/Ü_Ο¿íy~É·Þ_þÛÿüõ?~üËW«­þ­m~ç?ä?øø3ñxÑ×××úŸ?þéÇó·:¾þõGùúÇó¿ÿþCÝûçø¥Ttàtçã«=q¾%ž¯6‘õ«—)r|õÙEî¯Qõl-_cëÙóËlKdýZϸähùÀŽûÚ^O6Vžª÷bzëÅh_¥t½åëüO¯žîœçôîùé´ªwÏÈK]z÷9Ï·ÆwŸÝ¿J*é3Ñ¥"úù*£lÒó´3&ÇùŒúUfå@Ÿzó»O;ôêüîsUöÃï>gDe~÷)Ï×ùß*û,ØùH!½Ú×ó"=Ë¡9ƲûøŠèz¾ÅWÔò>sXÐh³ÆRÖ®‡V›kžgºÚ\}zë™vž]Ïœy;SÅvÖzð[ó4‹c/ó¬t¬ÉwgÝ_±+û0Ï<Ç^˜‡2ÎÖ§±Íqú_1© Ïr×Â99ôÝD7ÐëƒÞ¢¿•ñüFÿ<_Óæ8œxÈó÷ç4ç¡ÏÑcó«óü§ÇÐ@Éu;ËÔ¾Fh:ÎjÉ/®³fÕdœñÎU5/ókUM×ùÏ"×pævÕkg0{ëµ3•‹Oz$–uب”¦ÇOçήÑóãðXhÖ™«R=ÿgH¥jìëŒàll?sø¶ ?þŒréž+rÝÍŸjs.õ<¼ÜÏqöÔÚóöm÷È>Çó¨ÿüéþœ?ŸÍÔrèqVüòRˆŸ×áùˆ©þ?«Ú,‡÷ê2þiâ“õ€o5WóLetñÉ\àÏÇ+ Z}˜àá©>Lôaªó,P,õa‚Ÿ—ú¶>¼âÏ ^âÏõò*¬×ËüiÞëÿ¼#¥æ‘C§ÑÍçãðŸ‡^Xjâ´z¤[¶žôÁïÔÓ¯¡­^ŸI€ VgÛùã+¶ó¶Ù¶åXbüv:¿(אָ­yƒhØJƒØ{(öΠ!V§§á~X˜ÓÖÏì#@¿7ˆ[±Xï`çÐïG²aêw°^-l¿/Ð'ýtº´GÓö€µ»ÄÃéÕù¸–â¬àùˆ¦ùlÈbq5*ØÜËufè°¹–ñ°$מôþ¢Ìâ’žöWè[g¸HƒÍÅ&¢r–ôaŸG¢M–Wû`És¾\ö)  ÎDŸçÃ,pV9êcÖ;l[û¼tŽÏôG}ÞÉýms7]üiÓU0”Þïuß¿7ÈòhJƒø–hnŒ‡1‡ïð¦¸T6Ý¡±VêDÏ6NFdz޺Õ‡»J1ÖƽêJ!·(ãÈÕ‹ÏRTn<+õ ]ÈpØXÕΕÜ{] @Ó´¯'7Ƈ¢Ñe™ÁÖj ‰±‚…š\LZØ ‚ >^Žž•]4Dû”9 ISzèaf0Óº`ŠQãXt-X½‡±DWŠXјzm÷#»^&«Ð§¶ÞåªîjF‡î¢aÖné† &Ç–fùª6&¬>z·ƒÉ½ Á±ÚD¯òšx·è]Õb´çƒ)ˇ9ñbPIˆvÌ!¿…7&ù :·”;’››‘kÕ!O+œq±¸àÒLg¹Ž'º: Äcq?K³$÷ÀÔ:J²as>Å’;6MXÑg+“‹Ë/@RGÝÚ˜V æ™'Ù° C2zÞ5€Õ™îòß–0ƒ»å@ ì͵‘út>\­·c§ažwÍŽ‡©'¡[aêé…Ê^mÚ‚Ï-u¨ô»®ÃÕêJx^EÝx~[íÎüª:µ«7ÂI‚íY)£ B± ï=¼4 ?<# eùôCêT‚Ëχ¹ezþ™‡ŽzI!“7–x(@Š‡&Hò˜X$óC’‡VMr”•Ðh0¹z66!›õ‰ÙùZ·àª:épV’"êˆêC’[ÚåîßØ0AÎæ<ü¶(âãjá‡Ö™Î¯h ÈÑ}.£#šÊ‚)kÉì«Ù¢£M‰4hχֹYЦΩ ß©½•3%‘†ýXåuä¹Yì€é.²ú{Á²ù\㲉Åû„Y%Ñ5È"#ÌÝjmØK^>–ü“þw,? Hˆ ›Œ }±JRC¯cHnÀ|ãîÄÁPç©cƒRŠB¡# íÒ¹Êlg¦j'«ÌcTùÜöŸ,:(tUøgj—åfëœYx jçA¼O;gε¶èpÓÑBQ`}çÈ‹C7ëbxFN<è_µÉl?GüW­ÛÇÌy¦.oùó)»& OU˜AîCÙÌÍúï]ÄÃÎ>×Ïx¬ç&Ï~;R I4ḃóHžynr'`¶Î°–±I«€ë÷Hv-"ødkÁ]‹8’eľ¬èŠu³òUÁ—Y^ò²=P¿—¼BpžÙµÈ=³?%¾ðÝjÓs@+G©b§ÅŠTúàþ×–¨,]'´¹Úe„WŠ;(ô.tÜZíDØܺvÔwEÑã©WD{ׇhíÿï«8º¶â>$Ìí<Ò:-¿vwø†ÂaßÖµtÇ’hk;ã79ƒÇy¬Ém­¹É›élrr`¿5ù>®i:¬ fµBuŠY“·n“%8Ü}¶Þ1âµÿ \qÚsPa«ÝÏÙ&U>°‚ˆÛ™õÐ*bÕ%\q¦Õew÷÷*‚ëM\iéG´:´»W‡e÷Á }­©oT=šu%„« Kø#Ó̓o…Ý-æÏÃòS?gE?Ý'^Ñqö<£¢ßrLiÀ˜ØAU᧳¸×+Jíªvk\„ÅeÔù¶±¸´Öàm<"šKsºÙ| À;vZkƒ–£ØñpøÆý;'–RtÃFöï“nU» ä¼×k©v E]+åóµ¼N˜/ m: Îúi ÓÚç aT»vefÀmTí`€ç±6ë®ØUïà¨?2VÏ`‡äÿ ¢dƒžòÓÊm¡¿Z³ú;­u‚9âu‚›» m¬žÓ8h¯ìÓ~Ùô¿±Jà³\%hÅÍhËÍÁhÑGÅ5ÿçSzcetŒq†ZSOÛ‚ÔΆѪgm:ܱ¯dàZXr4¬’%Jm§;öp±KqbõìuG<ÚpÒÉg!VÏ<Ì¢Á FÍH 4Á)Í‘¼îà)âçud¤‘Vg«úXbA_ÉS«Z^÷¢WrHõjàä20‚fǽ¬‘nJ¬jùˆ¶¥^R?ô’_=îêÁÂ>«§Ðù€¦^S\ŽšÖµÀ¶ÍR“Ð:šØ'^I¸ÕÏžPx]RÑ¡yœ[ݸ‰­D€ê©á<Ï´Ÿ©iƳ.m_ Ÿñ»ÐÚhï¸nC¸’²à¬öáºqö¤û =¥ÝAÉé±`U%iáNLóPï\aµ¥GL†,å'‘hC¶ JQ†'Ò¤KZN™:±õþ"ˆ¬Ÿ&NŸÐƒlpâh­écÛC>=3¨×xµ!áÃpôÇÅeso·Û£ýÛšj@€škDK¸½›Nù¨”Ìäã äÔ‰•Z,¥ýÐM`€ÝšV•² ©Mpœ4¹€va LB“VG³DÆPè»ç­úCHH2„8Zt½KÉ/0W¥&üèJeépœ¼«4•Ô‚«É;Ç8âáJöѱ¦ [ðôy4xÚ#,<ÔMÑóˆÊó\í8—²)¤‰q÷DH Œ-hÿ®\”ص†´|Ûb×cPŒiî0¢ïê0­<5¹;0Œ:¤.Þ) /ÀO%õ‡_¯s¥©3^[û60 ;@RaC“ì²ÿhÜ+R_v£6o0­rr+†šýâéÖ P‚=g°Ý8=É-#ã­âtlêZ½Ë÷ë–Á¯Õà ¾ÒÏX0¹“&ÖÅÒh>z wžÑ˜ÿâó }¸e´ÛâÏ;¬ýÛ.·F"a$y€BRÎ ‘l±Á %Ñ+’{…vžœ`"«Ÿ}¾äÙÕØ™SůE*FëºÛ×rÛÃ0 (j÷¼bã•$5/n½‘Ÿ8d~¢}üDýë%©n7l¥é®ƒ,&Ë× ÷!1K"›ÈÃ,s¨ggA—û `‚<úGÁ+ ²8ê1Gzò¨}ì€ID€AtGL]ÖÔ<:µˆø!h"Š‡A9öˆ¡Íóú¨ w”Æ’È £‚ "Èvê&2ˆ:OŒ$‚+VáÁ6`ሄu9– ‡§Ãºû#䪬b1Òˆ¸I?b .Q…=:û@ƒ<­ò#"Q9¶ Ó!äs©ŒÚH·9z%âE”g< C³O¯pLÊZú‚*¢tØ’ïFÜ(«*tª «h…d]‡…*¦ÞÁ  }Ï! Êð°@"µ#-í»Ò ùJïn}4'´Í']°’ÍЄ*·EG}¸*-Ziú•.ûG éÊPñ£ç!W ¹ÿŒƈž É'Œ Eg e@…Õb»¨"Â_½î2Raa‚¦ªÂÿ þUY¬¡>ÃØ©Aý™1Å:C¦Â0üüâíódÏO`kÕ L ¸ z˜%ŠÑo)èKú:bë—¦üÖ3í£ÖoD+à÷9o±ô!*âU}–n™í±T†‚¦Îp®‹ÆN~t&àᯡs;h Ìôº>o*v2(~¥ÎÎm®‹ÎmŽEçÿõk ×Ž¢èIoôfØI–èŸ Îçe)îçòU¡{ÞöÅbûõr}Ÿ«…WͧBVÒŒû¦|Ç|N$c-¶w¾J°Òú8'Ç¿ufþýa넽J,Dk(îi~´ "8g.5miÕ^  å†4|WâúH1hÔÚhò›X´Ƽ+xD„­üž8®n1$ÆiÁ‡Pêœã–4„€v½¼õ -kË \»Ùòn©Q­2%i\ Ûân×ßW[ÉÜæöB r¬ R¯–Ì« nm|l·õn·Üzí7ú¯¶B#ÞzÏ,6‡ ÁRnc…“Bð#oŽÑI&äá‘h‚‡Øç ʹÄPÀ;X,B nIþ­ìA)ÌÈTh\¬«ì¬`¶•$‚·™ÀãÓÄé,‡A‹-áðv;+ ÃÓ 0ÐǶ\„EC%O µÇÖiÒaj+Q‹ô1SeJ-¤F ¢|ŒS>N-‚,2£Ä(û€$ ±á´-R&X ®ñ®«‘Î9gmÑÙ–[ Ž´P"GPC3ƒèVª<‘å´ƒ¾½ÉAã·Ûq´·1QV¿CŠúÔBðmA9TâHAڶ݂‰ˆbÅMß‹ü¯€Â{\ð­†â2T~B‰5—AH I+i6à~Šž ¡"Š[Ê¡í/H{%[n$7fé„âç¼Rl'%BŒ™$ eÏYhŒ:<Žv"R©Öz,u©üÄ‹öý‹Å¿Ç¢­ŽdQ’Úþþ(¨ˆgtñ%ä\÷qyúí­ 7ÿ°ù}†ä´n¬ò2ƒœc|9Fp¤”uT„òg¡_+`)aãZOØY6kQì’ ãª]™¿"ÌJew×\)ÛZs…È|ÆW& h®faÒ(ÇËBÍþøΩŠÄd½I#u¯Ë±ˆÀ–9ÃPŒ²N&‡i°€üòŠÓØ¿T‚3Êëd¶™ødÒÑæXt…bÇ%¬èRô TêÇ1¥*êè+^wæé(ÉôÐ0ì-…^¸åY y³µŽ@5Øu±x‰Ý¯Hå”CŠ°š²´.±Åþø´Š°lŒ]Yç« ºÝ´s—IÇ’{°rèdþCî]lI·ë eQ e'ÔX„Ú¨‹'¹ ÅŘŸöËBbµ²On/Ýó-£{€* §ªØ†d¬Šmø[Л¿³-cuˆ5J?>4·=.d§V9y¡0¤§g áê éPöBC±ð–€BÒÈë•wfÁÔ¤WJø犟ð7•â~ÂÓTÜOz<ÿˆ•>w-¾Šòh)—–ú-N)UˆH½#)»„ÍÍñ’ž€ sý¹dy²«ªÄ OÈ9Æáp'ª]xuÏŒôH¸Êç¯÷;­2¼+\ÂszÆÎù·î25s.Q--U8¶ŠØ‰ÅÖ´jkëY뵧s$¸½Ìx"Z¨M¨ÎÁ`L³9Þ7k½X¤ ìoØÕƒµPz½šF¿ÑxÅmÙíø)¡!6õ7ô;è:{A±ÍšâÔŒ´b÷TQçX-ô;Í'äk“CžùM²?€%h½²èlLº¼š²*» :(€=UíOÀ¾­Û`8íe!P®*ü›({ŒëM*:4uCýûtÙà ¯£ƒ0õ«¬‘PΉÖz+×Ð&ªo;HôdÎÉ¡ðÓ.&vIn4z|œ‹T‰o².ùÕ®J*U(ÉàGe¥¤_ '¥ß¡¯)Ó™¦x鱄¾©ó±{a¦ó¨ýõº×î¾Åèó‡ñ_!z*ÐýµëæxFr ±£?ð$–ªÌ\›ÎçBÜiuÏHOÇ*õÓÂ<™-ìñßÒY¨ËWá 3¥¤GS¯¯Ž o%ÝŠX¶p@ñeé¼Á8»tÒ`n¨ñÄ‘ë, fVÉΈz±WŒtÔ"©´u.E¿©û„/\<æ_´ ÃÛSÍP}ê¼Ø®gAa.ì 3†¥k0¾ï³®*Ë[vñ$Žõ@‡ÝÆ°À™x£Âiý¨ KÙÎÀïšÿZY}GmÂפäiÂØBUˆ*²‡ÿÐø]ÇO•«Söóµ‹í’'ó¼ke6½ôhØ+bü¡ ”+c—ŸÆ6ièך–P´¢Â¤¡ù‡}ãˆÃ_ŒzfÔ£Ò<ÊÅä„ž}võ€Šê¡¬Ï Q|3è©ó‚Øžð1ÝèÑ.ÖXÆÂv‹¸Lÿ¾.> ‡·‹ˆ„ë`qUdGŠ«6T÷h÷ óVÝ7èÔÖ×°åì'¬%÷ 6D•NÚäWôïˆ@iÞˆe²^s2ÂöK@Ø~ÂÜ*’U;ñc²¹áŽUÕ¢=içÁS#_ß¡ñ|õï,œãßg–#©Øí_YzCçBe L¹M›þgV) ^}4^œïöj1-¯è\¨@aŽÝ f€} †>PTÚƒ°²¥‡²žŒªRU¨iCR_–íÔÁâ‰N°‚—xŽ.Vã#°H1 ¾eí $y¸*`̬÷‡lÙ¢lµÊÊd“<óóã_ß?˜©\¦¿z•Ö-“DK¸ a±¤¾íß'²\§ŒÉe¤å<¯•ÒY^ÒV7P‡Ý3Aoºg‚~KíBAHÌM° ºQu¤‹a&íZ2ôî; &ZÕ_nŽ¹€´¹Ö‚ÐÛ¦·¿¯µ#ZR\©¶´IWÿ^²¼è0L扬KdZœËg¤%™Ž·}[¹¤{Cdɬ—îoÿÏ?éXwŒOÎÕÈšw¤w6Ù¿öÜ—wb-ñ1ßÛ ¹Q£t_²Ì\4E1¸–ËÓ…úc«äÊ'lò0„=eà#xHz%S¬ðkÇ.0ªòðÝ|ÙQ!2réô"OØaÞÇâ²ç°·}k0›¦'å¼2Ýõ³c¦»~„¦ñ¢Ø_Ãbét{ä.Âxá•ûuX<ïû¤è,aØsÓÇ2âXgž3ÝŸè([RˆtÆÓ‹™ê†I5LÔ×wµÍ°0Qì ƒVì-F”GKÙ'Óƒ"±™`åx«U&&ˆD°Úâ–))yU¡MŽ7³t/7ÄžKÚXTb‡*C2 É%gää*‹HNŒ=£s‰´394˜Äå²MÈŸ‹¼À%:]ôàŒl*<(‚Jdè}20™¬'ïNAø_¾Ùå}d)QåàÁßÇž 1RƒëmÜQq¿µŒoñ«=>@*nÅz¹¨$š+ͧó¸Pj%yQÒ+—‡âOTÒ|b¸Ií x<šÊg2ú܆âªLµ)Ml‚Ô!ýj­†É&T@µa'ЋŽì#ØÓ†CHÞ5P„®w×Fp¨I}bzG ÑÄVp Zošá@½gX£ÐÜV€ Ëæ¨4†Ö +Lú2à„I_®›ÌT[P\¡u—Y† ì M{ˆÞȦòŒ‡†¾ …ÃDsõ¾)ý-‚æ¹LZ¦Å&B ½á¸ü[SÜHÙÖŒ[x×!]¦È»?ès” *° 濺?{^óZZ3žV}SᇨLE”K„iCJ+‰Ê0ŽÌϪ/Ü]Ý™äƸ\“ ŸÁÈ&Uµ=Ó]€Ï4Ù„j81 R5C¬™2¥ƒPiU†3%K5ƒ)™B-O—4Úæ}£kBsUÜ‚$ŠaÒ‹] ˜î&Èz4‚¤¤ûHê%µê¦B4V7º/î_©°!˜Mjg ‡ü hû€x™c,@Ö䖎΄Àaw\ꤸÃSÑYÀ¢^øA“ë::݆.`\JÍ \¡&æð¶ &¼Sµ˜Œ»‡i¸2úuU9ÌÂUÀª€LªŽYw†¼´_”vZLÃ="~`™ úDïÐ/ ®’e0BUËî)˜ùª¨ é„Æ`‚¯q¡L”_† ˜*·z©²ì Ã¥°LrM¬CjÓ¸ü>Lãw¹ò†*¸˜F8®Ù]¶Ó…ÂìÆBHãw£Yž[æ#Ba¡!Ð…®¹Â =£N € e˜¾Å`èR«Ú…‹Ãòî5»\ Ê45NË ¢z,3Y®FÊt ˜]÷ËŸÝwptƒçβ#DlT‡ˆ `’áe»hX“®vñ<ëá4H,«ÌÕ€žVíÞ豪f7ë±9"óÐ욃KÊ EœGX0ã‹HYíö„§ÀÉ¥°I­vÙÁmbôÊjÔBܵ: Ž9©Í4ÜA:©®O¯v¢Ýèòwß„Uâ®3Cé$þîž7„à~˺͔§¨`_d ÝGaši ¢Y½ë1]3 –QH»ŒwvJ‚R]”/—cñw™ïïãï¸àï2ÍÇße­¿Ëâpþ.Ó‘üÝ1ÓÅD¯P5$ V±Ó‘Ñ4#Íö?Ç…ibªMÏ,\'—æãïÕæïnÖÖ—û‘©RÓ4ž¦ánꦞ•® ¨qÄ€ºÚ&?J“ö~;IujM#lëï2íËßeu~÷çÇ¿€æ„Sa¹Dµ»ˆ:(øÐæ^ÀÙ³Ü :ÃÜ `§{щ ·ó0÷Ž÷KEÓÀ bkDˬÿ,O`~{¾ôò·bp0A´¿5/èA´Ó;”‰åoQûK;½×*XÖ™V›HõP€Ë´x9¡Å~ÑÍïÂÁi°iÏ-²»¦ÇZewXu©8%úã™î±“þhÓ Ç¢³ŸÀ¹g?AÏqûܼF¤{Ü1ª0„é:ïœ8UÅt¹sØÊ;Ÿ-×@  D?w]j£@Ï~×±ŽùA?wÝ ÖÝ^Þ¨Ù7Þ´?è¸<–1ðžÊx‰VÑ ñªå yØ òv$?ß›‰Äÿa^‚‹Ä²{§ˆ=UâÝ_%jÍ}W,gx[€´'§ YÖí7‹±bÁ"ÛIÌ#o, L(ÅAB‚N,{™'1"e‹ä”9Nʧ,*¥YFí¯" ’òŠUµ¨5Ü}Kª•b"œå*ÍA)XÒàvð0½ÿÙ5¥)ë’†c8Ó°_ˆ $qIè#ü–^Üé0ÆØ/J÷"]R¿84!\Kt@‰6‰PÄã>‘wF°rOq*;N§[bþ¶eìÀÅV>šž¯„[žSÍ‚Ðíù>S½=Ýç8´~‡SrûÀïÅWXðLuÎ=VÅ’å¶ãmÞ8o[âqhè2;®q¸/÷÷4o6 F+µ‚–îl\Úåœ[èölCµX>©ŽN¹<Í÷ t# Ue9©-6²ÂsZxäªòCÕÇù¯8ج0BQšî:îs²:ñ wâjXÓ9tçmÑ 9±妬M‚å¦üþPä,wq\NÍ: UÎ=FÄmVGú‹“6h08K'kBoÏb…>wÿz^³ú‰›~t""z—Š(Jp(ôæV…çM…†bd,rü\üúñè¿0< Ã}Ã:ÐY3ã*^·â_«ïË¢¢žˆóö°úÞàŠö¯çµç*þvöC5p´ 9¤Fp¡´AO£}9ÕÁñcàŸ ñ‚=âÀv¡P-ºUðL³~z¥Ô_ö º€ÃÈê1êv8ˆ€*b½Þ¼²×¢êÆ`Ö趎„µÖ™`ø´ÐìÀ&w.2áÝFÀÀ&!¶~S* MwØ„v¥!n` ¼kÓ˜p_SJ8F|ùKJfòk5‰„ŸÕ(ôb| E'w ƒÐ+AÖõÜãõ°¬ž^c]&½Fÿ¡:©Ê‡"áõ³ÎZm"»$¼Ëž[„öÅÐWOI$’õö¾Ò`cøgó¡L„SÆYst½¤Ž^CÈ pg!žâëÿ „˜æ5BL2•6ACáq.Ã桦:`»ßƒ’9Fd¡9•µC”ªa̹,B0ç²øê£KV/‚²tk‚Í,'ÀÔ”R}å ¤¼O ñ\Wzì¼€…ù p:\¯ÿqO&#ºh5žq]Âʘµé`G•¬Z˜Œ¨ïYQU&^5ä*zR\•êÍ#ÜõÙ0ey©JaˆFK,ozð¢ >ƒNé¦{CóÉÌé>›Ëq'mÝŽp…®SãtJLC™ãGêÛN&³´E£"o‘#Æ[NL]¨å˨Z:% *‡†Ù[{0¹Ve™é¢ìè,P#xgÜ„u^ ¡úªX¢:GƒõÄÑ.¶aÕí`-VAVàòwqsµqxŸ•#»/΀@”4çû}9\;®t_òŸEëÕü†ø¦x˜õ]­2®;I”luž\ìát„\œ<úpï‡Ã_tá+$T—4U=“{)ˆüZY…í¹îg”£HW1«³Ø­Ëê>vÁ²Ý¥œKá Âw(À[ ⣠¿1ú°bÜÛµ¤«,|Ù…\æt 9é–)É·Iô“\¤“õvW|$û†]³ÌeWUUºŸÃwȃÅIÀ¼ÖS®tÒÎ}Ã3FÙ‹²éÛ*¾Y.ûÁœRƒLž(FCá(:ÐygOéG+âðóà'Žî¼Ï‰~+c?諲aÂu4‡J€b/­ÀHq˜¥–¬ÈÅðNæëa½Jèh¼2ÍÈe–Zqˆ FŠCR—gBve-Í?Ø‘w¨‘@k~8,žOžvåÊÑXX#ÁÙ¢÷\àN‚?5à?úþAoC8g’)ÇÎZÃg׋Ò]®Ÿyž®}³ènQ'â<á+p„ëËñž×Öaž«Ê³†—œÝ¬^‘®¶¬#Fl<AJáºæ“—£¹*ìÚy¿IQ󦿒…WXÛÔø6‚‘BØh&E† ¥ 'ç†9/¢Y%ÁUpánl~—×Ré4 –ΗyBJEÖŠmL ׉¤¤gæì°âÓ€9T@½@DÆðÍ,¼´VÅDX EA)¦UÄôµûÉ ¼PÅ ı$yÛÐòÍ/è/³ :Í}ší•…Tx1Ÿs£J¡Ó_§7±¶®$L<®ð¦ª¢þ¸ž4`¾ä®°è‰o@`í0W`_ï"sÁT©˜cW<çU'^ÓGUÑÙgÖseÖ‡9h®ÙÏŠ¤šO⡳Ö5ƒUZ/œºÆ³¤˜êç¨ò£Ê•£À¿üШT¥ÝcÛ¸|$QÚr„È­JØb0DV’Vëô³ û¾¨]¼&©&È7­§Í*™R…’™ ½¹j­ØI¥$±ëÊP#h¥*7W·ä%oå†ËCÌ/²G¡Õ`WµÏò=_¯ÎÒœÿú°R¨k¶3ìíÚú,`•Ä1.Î †ÆÍÃk ãðAà¨ækþÑðýApö4ß= Ë¡wÕÊÎß¡Å»ŒN0»@\”s+Y—Ÿ4Û:9kñ¾÷ñžqcS¨^;šaø¬DÞ󜧯¯¹$бÏÄr>!1ªïoRèÝu°±ŠÛ÷`!l컫ªZRag-WdÖÝ$!‰×’/T7¯üEHØw†±œD‡ÖéëŽ ÇÊë‹/ú¿,UUͪêËfUõm=ˆwèDÀ·>ãõ±yI ô£ê³ôaØ/XÑTçÿÃlP…üÖÉwÕVUµDIʾSJVp£SG^X?_aÅ¢û[]éʨô#¢üÃ}XÏó^Bß¡ۻ»aæfÖ¯Y·UÄÕ‹ÅçbJçb©©Ù7Ï`šž¡”–^TºTo ò{÷û»Ãó|Þp%¶£ê² :i~‚)÷ŸÁ+ç÷ãDh~þ½nZãrFƒγ‡v~PÑ°TßEώ½¬á €E™›†dÍ<‘yÿc„çsÎûçe.n²W¢½UiÂaì‡ú ag8é²N@‹¼^;"¼Õ\ùפ²\Zj)©É@¯y¾ŽõõÏÿàÛŸX‰¶Ö´Ž?ÈŸrÑÙ˜PJ¸S³&ùóýÇ÷m‘…nY–ùYj¾ÿö{»¿K=Îß×û{ûø½Çûûº¿?<~›TWt_a ½Xç%ããEH–ï·÷÷v×i–¿¯÷÷öñ;ÊÖ~¿è÷£BÀ|›$¿6 (T›H/’+o÷E D¾ß6ü;|¦þ½ØQÊ 5]Õ®U6Ûx_Üï‹=?J d~?»RyZ|D¦ì}ñÏOr–üNðâ?€~´¼ùù|{¾oë>ÂߟÁÛý£¥’ßx–PÝßI«–/nB*ÊYðª÷{[òÛðÃÔÐÛ5ë¨5lå¢óR­êŒ|¿¦JÍ´<¦ßfÅ}ƒ-y·äÞ7tÛîû¶ÿk¨û/-swÀ‰ÍäÛóƒ¾o? }'­,Ñ`F0Ï_·êºÑù5Wœ†G©V•œf¹*Ž#”s¼ôÆ“ùÇï×ü6l½é·Aw}ƒW»â²²šÇKÓÎý©’Ñ Ù}›šÅ¨‹ì·êZÑù5¿ b÷Û ]ëzÞâZõ A ~ áœÅßI?…ÀcÖ¯f…èxéž=%Ü«ß.þl˜üÒ]»š´Ü7¨Wá°h~y}Ð-[mª·÷´ûÑ™®–øe¯köÂo#û¤ømПŠÌ q«®ž_ÓÛÈ°×U¦="Ô»U=×mÌë¥K¾~"¾/­7* ”êÆŒ˜ñÒ‰ÏæÅΚýì…[E»ºUÐÞ ða»þWßV5Âߟbà{ê)øx§ªw+|ÏòÒæaV¢2óÛ´ˆÞ>©U†ñ‹Z%-™Gï‚k…ëË.xž½ÐÛÃìÿ¾´ú©µ\ë’Q•´M›»2xÖ—].>{ä/®à/€ž¯Âviöç­e~{Ä·ìÅ=¸ßIk'18,ŸScY:¡éÇ¿@áÙxzfs½=Òèžú¼0 n6†·JÝ‹îþPŒ”dîŸæì·§à'ªí[t`®1p,°û±ÛKÏì!¼P¶¾“ÖK€,: BÁ¦%ÍjÁöÞ^¨ÕA8Z%­=BˆÑã[Wá TaTÓ’ò…žÀá^´¬"õöT_ 7©ê ¢õôRùÆZ¡ç*ÖKÿ^ß ®s&Æ¥U!_hS¾«ïKë ,!¨Åb¿Šˆ˜¦5ÓtýyJÓ?÷µ?ñT]‚G}_Úß{²Jƒ;Ýþ1Ѫ«Þ+Ó½Aîë./=sD¼d½S·4­7*/b×µfMQÓU_^ïçWzãÞ^û ŽQ|_Zo\î w²(Lû&ç¸ù£îç8{­/Ð~©úiÉ V¯«‘ýÈñ©kÙ˜ö\Ò*ò\}„óÒŠ³ ¥Ç¼ï¤‡Þ í¤3•`żuá¹pèÆp˜Æ}•œ»cà™<{_- ó°Ú™ÎWZLŠŠ–5GŠë÷¹wÞOÏ… â ا­ë ôJê4‚Ï&”AoÚ·<ð¾tíwî d4G¾†ý‹˜ß—Öxl©gÝñ)ŒT'ªè©þAÖ(CÍcļãQK,v]õ=¾Voá3Ü“%¿|×»iÝC‡•­jõÕÜ1è ØñH9úö ÝýC%#…åMK—Bx/¡j,êÙ=ߤ›{ôdqÐwþÚ£bÜßI‹_i÷÷Xøy´*ªÌëçwÖj|G /Àsà¾À{껞‚ïÇ´ŒL b4[/÷_xPXE…Lk7=¼Oû ³%dwéñmz¸çAŸ‰Zb±Tq»hßJ-È9žýAçž&èówÒædúÈe“Â3Jî05v©àÑr_ß"Ú{”±ÓÇÏÏ„M£ž?=ï«èBT^]¿ò/þÿr+ ›L`wãpXgÓY¬¢½c±Ç•$˜ãÜtöƒåÓCý -ÀnEçѱª."ÚIµ›7¡l÷ŽUÚK/ûCÒbfÅwÒ‚C3tí:h¼f¹¾iáOà ™ò•1'ÃãE wBoŽ<›ïhôeì3äV|›6p•õ —ûŠ8¤îp5-pp a×f¬Û7ÖˆÖ¼ ØÕ\h”ýƒÎ^꽕9Ïø˜ . CÑDû¾Àýåx`žU˜&Z\(w±mÿyœ¾Uæ·§°“1Axª¾ ›õ8„ôía¿:±{³Â¥`R¢…±c-WWl×81¾cÖ—OÀæÄ—Y©U0!dVdEÑ|óZ{¥ªñòϪۺI‡ÐŒ.Ê_ WŽò½5â_~sÒ—uÎzi!¼¶ªwêËðJ«D´iA” ylÑÿ6¶~oßùõ)zÊqè~«ðV5Hsñ‚í&ÑY Œ0‰)zfùeÓYËkç%§P_wÌú2oi¾Ó±~ß2é_/ía^ P«•¬ðÅÔŸ!šE …»àÈä½£Ô—kÖT~™´ë°±6d“¬Šï'!­Ä‹J";ž¬„jZ É5oÂÒŸÆIzþÅSD>„úDZ`<¸Sämî5\|´À“U5²ÖÞÈ;aD—íw÷­ÓãñÏ:¹7Ê õ¢FÞ6ôóã_üKˤ°¤ÕWÞsäÚoˆlqbZ²’·Î»Fæjo}!Ñ^]ÞCäÕÍyQ/x—ê£þ±j§GŠ}ið¶i}9îCuÅÅ™˜vµD ×"o¢yò¦ w.ôeìQÀÌ¿“ÖžCȳV¹{X/ôyi×BDJuÊêâ­’®HÚk[EÒ»åú Ý „l*@_pá³Ê“¯ÂY¬ µ?håÒcç X÷óã_x›u¡$CM+`°Ç­ʨ›°M¦]çñ¹÷ù½ó¢/€§6ü¾´ú¾wòoýsõEÑ’§¼µHUy+®x©ºG]´@‡¼@±ºæBrö΋zщ¾R/XGKlÞ1¨Èži_4x¿²ÆÌû 56Óz2 ¹fç¸Éž¦]+tð^DÆ3¡5FèÕ#¦úª"¤66\¯êz¦]9;@1³ÊrôÍkNZR–qÓ6Ë_¿Ýºc¿=¸ò­¿/­ÑaoZ;y¸v¨iõÕy%—g½qTÓ¨CI}o H.‹~üîÊTÜwŽÔ;ÖW[êö’® `×jl±è¬÷ÊÈ®¥éýÞjÂ7í™VKØY®NÂôæîj®¢5ßñÜjÞ£ýAË—Wkûʄ롽£ :]P´f(®šõn±ßœF(Ú•tXŠÒugïPq Ñ_ó^6§z¾ö½c¬o¨w¤¥å2}ÜPr\Gà;ãMû†@ì=WgDŽ¸/i×â=™âÍ„«ç¬¨Ln{!ZóÒyg³ZÂ>Ô”¦%¹ï?•äºÓHCÓ®`Äè¿ÎîÁº~’è¦ kÒð×yùå/H^‡‡ùûÒê+8tzÔ€˜ùÒ’Lîw \ÞŸ6Í ¤‹ßeò½ÞíÍ´úÚyÓ±Ú̹Sï¦^êhõ<éäZ–$pŽ„iõ7À9é–¥ ¦4jÑyzaoåû¯oÕ{®®ÁeZ-UÖlTK9wz _ø÷¥ÅcÄx6xËwÖ†Y¡ªô‚«N—{“®hçŠðVðiŽ!œ\gƒiõŽˆssRÎ*‡sùNú­ä䂬õä—¦]Äè½¹úçÇ¿¾U_ª:Ðô#ºg…LÖ±2Ž6é"še"<þÈ›„ª¾ZE=B|õÜ]ƒ‰0\1Œ÷»¬kpºrÒ|² …iÉ ÞdïÔ 8ƒ\è"iõš¹ëƒwÐÍÚâ¤ÕkHƒ[Ësª^c7 íà[UŒébºšE¸H»ZK~TŸP÷_xûáÖ£#íT= z°UÝ®zFڕ ûnWmã<ºòSΩ¾†½ìŽïKë à“¶gƒIž Ñ.=żµŠÝà´~Ó3vÆÎê}è‘+c‘vµ<â®]§ŒsçÂ_9êéÃû¬ÕSa‘® `Ëšð¤]H¶’k’ÿÂÛ,Û"é#Zç20ÙÍip*çâ¢b¢ÕoØÅÛÜ[›¤]f«å}ðïü²È›á]Ýß—f¿YÛXq“ª"4®Å/º‰¾ÅfÚjNaí{e÷-BËޛS›Eë´R1VšS× ËùUOÇ/ÄÇ°B¥ñ~•Ø¹âj’ÄÑI&áò‰–±˜÷_ߪciaÒê7î¬x\‹åÃ|ï­iõ›È>I÷Æ;ÏuÖ™Ö\ É5ãïüªÀü•¦1ˆV¿QÒÉÉž*#äÛ D«¼]O3Óˆw”…#ÚÕ:YvHœ÷¶«›–lW9"_ÓÇ9•ÖsçW=ªâGߪIêL…ê¢Hí¥=¸_#ãDï¿ð6ª¯ ‡•´ú]Y:I³ ¥*¢%­~ãiΞԕlM«ßíV{~çW½à] ¡1ˆV¿Y—Z²Ê… ö­žb*~VQ;«ÙÞ­ÓÐ…£Ô&ïq½UÖ–Öiè‚Rj“s*ùç—=­¼Í\z²i¶ŠÀL‹¼&½v•[Ò¾Mc1§¤fKþ×·jÕº¶¶iÙSHká¹@¶ºF¾ŠeùªFìIe^%­~cOFÞÝáùÕ—Q~¬>«†»j/öjÕ,™ÖË}-ÑèµfÉ´z=™?·E£×âBÓêõ¼•ÅY±§©|NÒUsTî 1w®Õk kS¯‘v§[Å}ÆÍuœMë ,^æ:ÅÅÎÆ­/´…Ï~~üë[•Š[õM)¢5¥ ê ùBëƒÖP^Ï7ŸÜ¹ÖÀ‡ué à=Åö*lÕu—Eë ¸È%AÖl®cmZ_`!7ß ,ü6?hõºÞ{zxGg«¾;¸ê$ÕüJo»sÍ^#°Ë|©oU‘n.p–h¾5À´zÄêöž—‡%íÆ­#›o%Ç.wq–®STôçÇ¿¾U›º5ßWÚe0éM¥$=¿¾ä7çZc˜E·a €u6I@™:x1­‚àIß„–uI¿¤U¸`EVî'„¹¹®¬é*csìxW.g?ÑüúÆ œkõÙ‹z .TÌ’WûŽ¤õÜ‘Ô\’\h¯‰iõšÅ]Fb`.û!Z½V­ÚÄî÷Ý@ØŒ­OòÛœ’nñïRèzŠtsé Œ­Õ|ÊÿÂSàÖî9#íºÍJß`ÉHê·º60„b6iˆe%]lƒ·8¸h„hµÙÐ;ñçyõÝ·Æð°@¥¾€B…=K·ðþ—zA<¤]|Û³TF3ã¥³Ô ï›P›Ìft-wÞëeî„\è.#Ú¥FП,AâyçpÄ·!Ë€¥1ÛŽD—êLZ%XòSsÄÜŒ‘Å|H«ØoÕÈ9ºÿúVyŒæ{pŒ6—]ÁñÚFÞŸÅ¢ŸútÏ,Ç¢¹ît~Ü=¦Æ@Ú%.ÏáĨ md Þ⛫IðFµ~ËW4±‚ŠÓ\Õ×´‹=Y攥2ÚÈRèƒ Ph~ûm›ì‚ËÑkh[SRˆ›æ2¦õ…Ê¢­*Æ€œrWáf $Ý…R_Úe”À;; Å/šK'˜¾õ1ÚHýïþ‹sŠqºÄ¤Š+ãßyÇÿôãùÛ[ÿú£|ýãùßÿñ|ýª¿2€õõí,Õ`å0ÝÖÁâbª‚I²Ïû€Ñ7/8I,SyÕ±3 ö} Þ׈ŒÊÔ„ÈOð]ò5w‡7M(-!û‹178Ä.¨È(톀I=B2Œd`RЙ$RyDÌßPZ|´œ€Â{ÞÔd’*'²Ý×ÖÛHå$…®YW ]èd ¨´1ÐÌÙ7Ã\Víä×:«Æ1_‹ç„¸î¼.¬&E}Š¥Œí3'Ÿ×¥©FqÏN°„¾þZy55©ê5ú©Â°š3‘Û9¯9xâ—²¸ìÊy'"*Iø°ô@ã%¢[ämŒ¤¯/9P–\s62ï•+±Ž²çŒ)³nÿø‹ä© B Lîd1^uà|l°«—T– p=ÛÝ“u™)ê^0ß_dŸ÷]™F’…â<…ƒpN!I{Ýs1vr•j•>Îåî—„kALEÙIÖÛIM!ðuϘXMá`‚ò¹ë»%”ô­¾é.M§y?÷#óý4\_îÐÛMÿôÀâ$[ämŒ¤úÆ|»ºJ ²±Q²oÎ2–€ƒ¯F})s…WfÑÇð§™3f[Õ]’ìã>0žûÚx#Ž$î.LÃ[ÑýµìŠ5fß kXêd`ß$zã~Z8I? ½Ö#!iÃkß‘ ü——u””6´ý“¬w$¼Ä¯µÛÉ÷¾Ù| ï-ɾ!@›ˆ~”üÈ\·å™"G¤½39_K«gËŒt%YRÑÁè×xÛ‡Ð5å¿pYú’òŸåL¸¿FÔ\ Ö½ k¤ì&y‡JD!]øݨ`}»@Õâ@˜“Lÿ6>fÝ× /µ¹¤æž$6&7s‡v«—|¹“ÝÙ/li¾h&˜Õ ßþŒ„þÅSû% ãm·;7(’g™• ï1µÂ˜Úh/ÏÒ:_´ÊŠJêzr–E.§+u÷™9Tb>¦‘…³“ZŠ\Þm¦AµÊ{rö%ëû€“¿Z ×Vï¹Éž%ùôûÀs_Cþ’#éO<ï‡ya“Êâv’Wb·ûa¨¿ÃìïàÛ¼SR“ÛîœQ´Ê–A§†B.,ÔwW¡9¿-U\8ÚÓr6eÞºÄ ýÆ•¢ X2aöH¹4ýù«+” þØÌV”aŒ–ã~MÙ¿è+4ô¯e4k¸‡8Š+¬ "tÐ/ê5)WÞ¨~oøËü Ÿ;š±€O÷_aì¯Ô¾Ý )kªù5¼áðš’Ç-o[+LŸ- åïêV,¿¢øžƒ–¤jŠv§O…¼¿¬pªB$}74x²Tʉ¶lÌ5àÁ4&Q¯ÖÄÍà¦òÕõ"w>P|Uwɳ1U;U¿·gì¯2ãßNj©8:­UŸ¹*ƒÞïèDºàzÍj©|Í_ïè4æÇ+à°,·ÈêÌÆDº àý0_sw4ï+?Qœ„I0Ý­°HùÕã{þ~ÉÁæïPÂeOòZµîúø¼!y^²µû€ï5$H£¸'Y ýý8e[w¾ûZåÍviCæ'ô€ïÊë·;ll·û w¾è²‘  BæO?oÖáTf4«s™iQhFü€5*¹RÅð÷µò%•jAKK|sš_6x+]A,à°(˜;€Z=þêh·/ƒÙœ$ý¬^DÝÇšï¹9¦ñWRª¦*èˆé”ðúå|ðÇÄéÝ~Û`Gù¼ï—?/¨Þ0…©»g–5`„Ü\í 7¨îü«ª<Œ,g+ʺg5–½ó_a£[rΩ "yŠ ‡¨*#fåNâ®%™¨Gf™*ùWTöQÁ ÂZúj§Üù'é*T#{Â[%ÓΗZó,ñ«÷Óù”~•Ï‚Ölâ0ru„£6©{8ÌLVö_ÇÖlrDÇJJ•§èœù†+@WlÙ²(|-kõ;›P<Ý\¥¿Ïœ6@ñLµm^[þæ‹QPêÑﮯqíM_M‚ktKRê+­Ñû5÷p”¤€K¹_˾¶1ÜWØuëÚrê!”pS‘3Пú ÛÕwÙ–œ9üÕUÀ"gŽª|Ë–Mõœ9ôàöæ(kD02Å—€J,ƒ]Õ% >«7ˆA«‡i¦pY¯ÚÞ=ûº³=PîëöšÉ˜^ÙŠzÈèöýZ½}ɾk!N$ꢽ¿jË7á>îì`^¦Jþ°1T¶D™ÖH+?yyNCS—‡äòíº—‡€¿~w›‡Ðžë«a&JRš âºî×4~"´Z¶\ï×r&€µóöž‘â•&¼ ¼ñW_ÕQ^ñÊß5…„âyèóN,nu¹µž¨¤±’Ò@ðWuo¸\.Šn µSä GØw{eD­€÷¯þÚNáŒV4åëZÝWP9Ðb †òî\<àgLÍ”›k¦Ü$(Þç½h]FfýíWR*–u«ÜGÍôI%ORK‡!A7³ Þ±üâÌ¿Ò–å¼4³©¤T¶üùe¾½t6é²›IÁÄVÁ|O7•À.¯NUB"ãÊÞP·ë7ù2[>ýªI±_üë¾o0ÅPõ¤V¶¼ï×ð†úò“m7•€@áÓ²Nú»)‰,ªÖÜA¦9:ÍRMŠmërµû†kRly߯áæ$¬Tc*& Â_’*=oqÐoëøõ§ÌÓ¯n(3Úeê×n´EŸù+3ñœej'¥ÎçYÔÖ/úç#鯩¼'«<+Ëk³cƒB}éèùHòï^Þi¨T6Ó.ûÇgTäLïÖú¶éš~ý’ìÀG·xlmŽÎ@¤|“ÓT|toÊ~{É°_Òãí1Ãdî1Ciî±è¾ÞgÔc½««ÍXï·D«zF}sÀœurØ ô´Û 6Ù‹ø˜·ø˜7=Ó¢ïئ¿ NÒPeü `ù.ªêd›¢]®’ϸ|×}c›š¹ÛŽ*uŽ†p¿R¨ÙÁ*ù…úñåöÑ£þÑÓñŽ€Ð£¤×;b‚ªü.ÁSnS´¿Åg܇õδÚtIÁQ>FC`œG#:~ùËÐ_>ÆÖ>ÆÜÞ¶xÍÈÛ./ŠÕ#ý¶«‰o¯È¶z}ûˆÓêÒåý^ÿX­¶ß9­ùè«®w5jSóÚß‘º~¦ß9FO¡ ç6Æ£7PáÇBÿ«Èâ}Þo¿3+:g`|Ìù¨þËÔ_>æy|Ì3"à—f½z?Êö*o):[kÞï‰þõ/Z‹9߶p0ä7P=ðÒ-Þgjܵ@úP®…h—Tç3.ŠËw5kjS³©o™fü û–kÅ\‹¥Vù0÷ùÒ ³% ýßq"!g`½ãÁ_$1—³X¾G!Z³Érù¾}w×wwÈ™ÒæubÙC”‰rYµæÒ­¾ÏæâÛPEg«÷/hu|¼1?ZZ_Øï—yç®[­@© ›m½Ö¢ýÇcgÕúhu¾_«ãí°™÷ŽÍƒúÑ>iñžÏèÝZß6µnúV|ôÁÏ°ŸÉ3-ÇÿtŽSÿÒÞhóáýîwëïÚÇšð¦^Ž­ƒhAÏøvÞöŽAm&1Þ1¨~f}Ž÷—{ ¢s ú×´‹¬ÝþÁVË~#3òÒT¥ý `ryË.élŒä˜9:ÑÓt»€äÔlsù5¸|.]ÞÞ!e1gï~ëÒš==ã¢ø|×EúãöÔߊ>øö3goµwöH¯ýË_–ý5ïV¼cXåÃz>Æ°ß1 ûÎÑúÃ~Ç wÕ?µé»[ßõtüLûe ëc ¤}#ì~[ÝÏÛ*ò¢.]Ÿ÷iÏ^gýK­ŠN¸fз.¾±¦Ã«q¬ÑøwÉʳ駯ÊÉv×G»ÕV¢ý‹° ²“dQo'=£¿ôìï3´Ž–Z–«Lä÷`ô%ž\½ŠhEË+¼H :­g|]×;‡nÓÔÞ_úµ‰¯Ìw×󶹞÷[³¿}xm1·iàd»£ÿ©[ër41>g/Æ;¯Q>g¸v¯¤ÒD\&…i%:鈸ɞËzЈêþ ×ûŒ¬§'Ì·MÑYD¶@2• ´]5gѳ$o1¹É<Äd­K—÷d˜ç»=Þ6E*S® ¡„9sF{­¦§½stÎQÿèQÿèµ­”õÒ ÛwjâÞöùÎQ__{µ}&´æ3#ÞwG¼mŠÎ$Ö·ãs&öxghw÷±œŽf|Œf|Œf|Œf|Œf|Œf|Œf|Œf|Œf~Œf~Œf~Œf~Œf~Œf~Œf|Œfü2hý9”YÈ7àÙ¿-õù~¡Ï÷Ë#Þ½Ú\ý°y˜Oœô*ï3+ÞwW¼mŠÎ"#oðîíÛžw4·ÿ‚k¥~Éb4_½˜¿ÿî|,y”s±ãýÞ.o?d#¨¢]š§¼ãÙ¯^eËdɧú£wÖÂõûühs~|k~ôa|ô­½sqû/0öÿØ[endstream endobj 6 0 obj 20943 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 9 0 obj <> endobj 10 0 obj <> endobj 8 0 obj <>/Length 3336>>stream xœ•ÙÇ‹U[ðnsÎ9çœsFQ"Š8q uæÿàD"8pà@ˆˆˆ¢¢‚Ì9眳Ïøýú.èϾ¶ïµgp8÷œÚU«VÕ®]{ßÒ#GŽüøñ£C‡gÎœiß¾ý³gϾÿÞ¹sç§OŸ–””Ü¿¿Aƒïß¿÷îÝëׯ›4iòñãÇ­[·=zÔ׎;Þ»w¯¤â5f̘.]ºPâÓرc?|øпÿæÍ›wëÖªjÕªµiÓ†Ø?…«S§N'NœpôèÑСCÕSºgÏžOŸ>}ýúµqãƆU¯^½fÍšŸ?þùó'¥>ݺu«aÆ@:tèöíÛ;vìð|íÚµåË—SzðàÁ"d ,åÛ·o«W¯ž?>…äûöíK?ÏÝï޽땺uëò¶uëÖ.\¨]»v=* Û¹s'bZ¶lI¨^½z^½zU¿~}wàtóæM@ëÔ©sìرÇïÛ·¯V­Z_¾|™1cÆîÝ»©`€yéç’%KºwïþòåËõë×Ïš5kÚ´i†>|xÍÂÕ¬Y³ÒÒRʽlÚ´é›7ox_ŒlåÊ•T?þ\Â0ü¸xñ"òs"+F‹-òçW®\ñ¦U«V‰xѵtéR$ñsÓ¦Mž‡ ó#FŒÜÔ¨QƒZ2yC?Þ 8°²U«V%jàs¥mÛ¶H‚‡º£sÛ¶mêÙ³'Â0á%Iž”«`Œ?쉠Ÿ\½sçŽx­]»vÙ²e“&Mò•wh$tœoÔ¨Ǥ£O¬KM«€lÆ ׯ_{8˜è•õÌ‹“#GŽDçÞ½{aå_ÇûJ»u'3wî\ÚµkÇöùóçñ4xð`j½iÑ¢…±$MÓˆ9Óƒ¯lÉA¨€lÍš5™Gø$ÄcŸ —Ä$%íP>yò„£çÎsÇܯ'NœÈ¶ »páBò8£Ç¼Æ' å–Ùã^“Ó ‚(×(\„F¾²aÆk® 6c<ðÖ`å#3gÎôÞT.ÃOR8d$Ü"‚ Éô®]»/^lBŒ=Úð'IŒ%@žW0½}û–_¼x‘àsÖ¯_?uC¿çr®Ù³g㟯—/_)’4ʘ+VPg†JAHŠŽ¸@,—k„ ‚`bä(Ɔð+…–ÞHÁ ÈþÈEi¯^½¦©Œõ*\"+ô°ÊH nÞ‰¸œÄ%aE‹aw%”W7nÜ  %æ–;É3°wïÞ"'ñZ%dS§N•‚b˜Ÿj4wÅ‘1‘åâþýû§OŸ.GUQ%+Ìœ={VxSDn· yÞchìz)šòµ“”ÅÈÆO©|WKóvÞ¼yÖæ¹E»p£ É$—•Di‹0XM‹‚Çûi> *e’Š&’|>}ß*²yh` ìJ5þÈø ÈTN©Š–NÉ'z±M Ú<ôéÓÇWÍíú…Ë<¼§ÅÂÀá5eOŒ5Êd$fé”IƲ! 9 «P€(+Ì L‹²Q™çqÅHô"C9½zõê¸qãL"< “¯™ù´ vïá)ÔŠ>Àr—ÐfÞ{@Ð@9^é ÜÀRÁ{Î HñÜܼy3(F2À6LJ3ò3}@/e1<øD/|>'”8fRºÄˆd1³’NqŸ¼Ç:Ú|•‚0`·2« r´#Ãx¹É6W¸%"r¯€«Äü”ÈpÀDž=pK ­bðM’·±7XA’ôò&žgi7£­ES°tûöí&s¬Òˆ•ãdz$p ã£ÜK™YÌÈ_abXÔ²ìŠ ²ùf~CƒiŠ-®r£`Ñ“÷èÀ"ÒtH12Ñ4Rh8mn80eÊ°ÐÆuââNµØ™Œ%é«@£ÄÜcP.á\Ï¢q–0Ð3ç9†0ÈRuÁùbd[¶l1@cƒdá`ÏT0`¿ÕÚy³R víÚ5~ëÀ† ¤>ɪ®fÍ?‰¥•2Ç’ &ÎcÐt¬˜–¯Ee¶ ÙºuëÒÁÄ!˜è2,½] Ÿø*¬§wšS§NeÕ‚€“ÊO„‰¼ÌRF•<ƒÏƒQ≮iMbdú»Nij•·x¯´\$Yºø†?Ë]’,°êAh0V§%šò£(áIª— €ŽHÚhNgÁ+©BmÉoWéÆÂø´Šj/é?}R/ðWÎ1™íLÊíÞÙ±Ò@ÑÆàË*„oC`â ò¨•Öò’«R·peÏRŒLWmÒrÃ~³ÄƒZ… ²žá c^8²?JÆ'Û»téÚ`rOÝ. ¬»gã¥pÓýB¬8ãò÷ô/Cf½#ÊpI¡I”õˆ¡4å Ÿ.µ>UÛRÁòt?YªV¸àV,ÄK ÃéÅ™€‰Zd{V <ЩXz Y 2Kž  w¯€†mñÊ>‡ÆôpÝC2‰0&ÐÉXÂj ÛxÂ4žèÌ*î%Üõ“3àšÂˆP>çÌ™S 2uφ%3äׇŒ˜àP5Ì\Ïdt&(d {PâI”³¤ú}¶!^~à“æŒoŠNl)¼F!ÉÚeªÒV±™2&(éRèå(uaZ(Å ½RÍ]A–[ŒÉžÀ‘=³Q¡3mÄq Ø°úi(+*í+AÆéÌD¨‹1ø”&;.2É^ê‹Z#µ=s E$»ÀT윇 =@¦×p7 VR%dÒ“íòŽ>?)¢½xö[r.­ïE™?Á«y†ƒà˜ç ¾³×M îSa•!3¸¼}KíÈù>K‚›ŠŸâ™R4¸—‚›#ôˆ> ÒðågΡr‘c˜ª"{f8ÿ$dý,\8HÃÓ”læHŠ‹X9Ò=§¯bÇ0XR¢üT¶œ¢á/}”-LU‘e³ KÜ­ =-TÓ+ Ù¡ä/Vӵ柇l@Lغˆ¡';rîVrƒÎŒ3¦Š°Ê匬ä2“m9vSÄMC´I¸~ýú‰™TcéÑ,‰éÑsL.îÙf£­è°ó¿‘åo¶œK#È,ØåBÙÚ§¦Dž³ŸK-…Æiçž•ìLýÌ¿G”ÿ²¬èê‚°r+û³hÉR“æB…”%æiŠ7Ò‰è—4&$¹„­ì+ùž,GëIÖ¿‚U†L³š5„®’Âát ºEEK2e[–¦Ò&@œÈµhæÄ*§é|ÒB¢–Ï–Ý!C†ü52rP“í!“9$ËuÖM±Ô,%¬J1èY¤Ét¹‘ÿI¡É44g?ª²Ì¬Œ§=Nó^¥P™®JebáÇ¥\LÑÊ!·Qé¼³ÿæIÈ6ß‹`«xýǯ@ endstream endobj 11 0 obj <>stream 2013-08-20T08:41:59-07:00 2013-08-20T08:41:59-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 12 0000000000 65535 f 0000021263 00000 n 0000026399 00000 n 0000021204 00000 n 0000021049 00000 n 0000000015 00000 n 0000021028 00000 n 0000021328 00000 n 0000021428 00000 n 0000021369 00000 n 0000021398 00000 n 0000024962 00000 n trailer << /Size 12 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 26569 %%EOF ast-8.3.0/sun210_figures/fsalign.pdf0000664000175000017500000014432513004147321014132 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœì½ËÏ÷[VHL‹G Œ Ýêb:òž}¿$@l iñ’@“ˆ ±y½”Ís¬€Ò˜€ÁÑ‘êÀv"#b:U¦ªšø'tR•Pƒ’Ä ƒJ¡p„êýù|ÖÚ{ÿž÷hb3prN¥ò>ŸýÛß}Y{­}Y{íµ~ä9¼‰Ïÿ³ß¾ÿôÞÿÒŸÿÂ_~ oj+¥æç¿ðTÓ,ob}Nc¦7µ>¿¿SrŒ ÿÖ뛼pšáͬÏeÌú¦üö)öÈ¿<åå)–ïobŽ,ÝËtìµ®2,¥ñ&–2,¥´±þ‰Ï^æúÕ{¥ß>y»,áåÉn Þ//ϱ×øöéÏÿO‘$I“ßÍÒñáû;%ÇÖño 5’¹‘$³[ŽWwZ­w$·;OLuˆ$*ӱ׺ʰ”®Ê^vBEm«Å»ÈZD!¯Ô0hb ³”Eoº¥x×¼LÇV)‰2ž|æ­ÿÿoOáùþˆ@úäÓ÷ÝUR[…Iî{ÿ¤äHŒتVºÄfL¶ÚñÛ§>ÙCOXZb„Ê=¥$5féØ*]³”< S^NJË,ÝËÌ¥Q>¬R‡oŸ¼]ž²Š°–{Š÷Ì‹ÜØ*Ý"UR ÑZÕÞ?)y ¤2ÉMEDÑÐ9^D)ÿ´SUòú£ÌóMF•¹qô±ò”ÍEKyY‚õðI__@ƽȭÒEaO ¥KŒ<¥Î¬2Td˯½NÇk–²vyÊš¦¬åžâ=ó"wO­Ò-F±fŽbK…Þ?)«N.¬¥ˆ‡J±…7ÛTRln¥‰C,eõhÕÊ>ZJ+†­Ì­Ö·O;%†¡ñö”:§fÇ\E†A®g¯Õ1|Ÿ†”‚@m÷ï›—¹ûjµŠ,‘ä$£Å*áM 1-)þ‹O£¯¼iÉ|iѧ·ú&Å)ørÁÞWæÛ›ôÜGÆŸùMöwKoz‚d­uψ֒9VGÇâ÷•gáô¦•ç]æœñíN)m}[‹ø··oµ¶óK"v®|køðÙý‘Æ›õ7x³¿‰iÚOk¿EPv¬²BÆ­ Ð•}-Ìkq^)u­Ð«=Ȉ¡½ú‚k6Fëã›:‘}³†R^ÿ,¡šk‹'êY…¿ÿ4ÖNa¡— e ËX¼X Y[¤ÕŠГ¼˜ Ùßkç:'dPwqÊXíj«c«ˆ™Å1eõ˪ˆuý †Ù d¹6ˆ¹Çw¡²¯”Õ` ×òóÌÁ8¦Úß­½é(—üÐYÑ:4$|S­S)¿YÿÎE Ά׷ä§yå¨jº[ú3¶©üy âr´ZÃ<2WƒJî1kÀZÛpe_Û^I¢eèéMÝcÇØo˜V{1–;A+î\¼aC]Pz3NFó¿rt,ÇšI*s`-_ÍÛ<°º“:§Ì·¡!ôèõûHé˜VJ{30‡¬”5õu¥¤ö¼p}3 âµ£h¿ÅšWOŽ'&-bL™×ˆØ’*‹b·5¢1¬AhÖ§´`Z17^½ž¶ÿ±”9Òš²È¯¼Ø€¬wRÖN%¯a«Q¤Kàg®­Ã,£k0çNYx¾i§„ƒãbɤ/<¥cZYx¼Q/É 7 9oÁÂ1Hk“·ºÇ ëð9è‚«>oV'kV$¤EdŠ'Çø"NWŽ%ìƒmX_Ž «ÁøÂSV§¹Qb- T\b«uÁEùEGœü#gÛö¦P>F^sw_Ù‘{M¹Ûß‹m*G‘hÍiÉÁ:¾'ðVá"µª‰kõÙ-[ò£ÉÃrà رP°áü`qù|¥TŒsæ˜X@NkòoU,aàZâ9ÐÒÆ ê †³sMòÙ¢„j5ÅL!ZcU)SCº&®E«U2°Vˆ66¶nµråÃ&×è‡E‰áâä–5Ú$3&U¥)Ç-å1¢á6ÿ¯ö¯}‰ÏÿÙü¿öm·ùá)‰Ìɯ‚¾UXL/{ðzö"°8ëǘګ¿}ú_­:;`Ç°JŠ_U#°ZÀ2‰RÄì¨/û‘¸¤o¯YRÁ8ãÄU/É$¹‹«ËZï…fíçP£cäÇ2{e(UËÇZ' Ĩ|ÕÛøâh5? ùkÃÑl7´–U 7]™vŠÑfífæ‡ÀC­µ)ðŽîù"Á&VÏÄ4bõú†x«€Xk°¦-þMÄœ6µ†…MŒ1µ^jÍ ß9R"&Q‘‹or Õ "°ŒQ/r-¦/Ô²Q'­U0¿ƒ¸àèâE­¤¡júpàt"²=ô!¡6Dôâ²oKÔÚ¦C4Îua9|Ä°0c‹()a”]ëk)Ê‘Aû5•«3ÓCÙŽÒžc5ÙÈÊéÃÅßkФ—gï¶Öï5‰¥ÎÍRƒÎor]Yû^Ò \ZAöÎÝ7ékŠ%œÍ8ÓåÕdòìäæÅ}ZÎ)ƒ.Å yí"’-k‘”É¡iŸÙôÕ…ŽÏp­I*Ü;Š54õäXÛÑ­Ž±ìiÒØ)‹] Ö\ß×|ÖŽ´ä¢Ì{uÉ‹EúI9d_ëjÌk 9ØryIðÀµeý­ÝD²>áh—Ïâ¾û´—ÿ´;ïkuÐ %|‹*<¾$¶•_ ®¢è5ölÀõL­Ä”öÅ"½ûJÉ~îø‘ç5¸ªø–õCÌâÙŒ‹‹ïøî§÷¾ûO>ÿ•ý±?÷ôÞ÷¯lOïýѵ)xzï;¾çÏñé½ïüøþÌÓ{ßõÞ'>ñ] ~Ï·~ë{üù[Ö/ŸøÔ˽ÿ—þòúäÛ¿ý黿óù›ÿÉú;êû—æÓŸþÜüÜWÿËÿýöçþîÇ¿öçâ—õ'¿ýã_ÿÓ¿ü«¿ñ“ÿú¿õoþíoüÕ¯ùë{ú#ßýü½*«uÖ.ØÈB•“G‘:b§”ÉU2Ï.åOÒ·Ž&õá·O9·ÌC¿¥¼<åT¿¸Ô«LÇVë*ÃSR¡‚àå¤Ä¬o¼Ì ]í®5¸îv·,¸ y·ÝRv̭֭߬¸ÊsªðBÝá"ËN©Å<¶Ô&XîÒd;Y¤2ôÅ4kþÍš·Êtlµ‚,–’]òSl³¾Ë\³&ËôZ ¯2¼e–²XÛýï›—é8»¦diÏ?þ]^ÑåC´W9¯Ý÷Ú¡Ö20™ežw“àËû \™×ž`ÁµuX.ø—ÃÁârê¯skR`¬»… ÂÎØíZ þ£뤔ί'ªïÀª²¡T«ú|m nªkÍÂÔ X°.E•ÔÔ?í&Ù³$Í£k]ÊX¯2Ú±6WÔbåìC©”—“RÖ¦‡J«ýÕ=ÖJYç´pRµ`À®ÓZ%°Ùš4Y;¥ P—µðj^TfU;Î;ú-¯]úÀß<Çä5!¡-«Ø*]ÖJ™8Ù¬”]Öâ*³V«+6 C›µ¸8I›uXE)¶ªä<¨²XÉ”+•I„/ÌζyÁ ˜-kÿÞѲ†î¬Ê×ÁÀÚeð<#ˆ©sòK¢Õ¼ ©Tj‘‰ Š±Š2N%d¢"®)PLöw¡ò£øI½ùhäÆGÕÁÚ7u• .¡jË`ä¿@U¡?À `ˆZ¢„ߢîŒÝÕ•£²-èøjÝÂTn‘%¨ÜÊ%Fô’õÅ9ÿRà"÷g S•á_€Õâ•#Sµð Cl¼¶-Ôp”\u1™ª3@aM$Ìn਱3dlJø}×X:c¤|©¸u•Œ¤Šk¥p»ºRºT\+…*.¦¬äÂ<Íbª¸¿ÅÉ&Ï& -IÅ% RÅep1àÚÅ3Pq©O ó ŠË1:­«¾“£@ƒ…+Þx‘K|¸SÂÀöna踀³è\¡ãÚ_4ª¸NŽFÖ)Áq¬Rq])ƒ”a†Ñ¢8¨¡UdW®.Xlh*ºÇ ëØóÓãMö1auríÆX]Hb¡SÅå_ÐîãÊ1©ÀZ8@Åu°Œ/<…w|ÑFWͳ©UTqUÈ)oÖ+t\˜Š»T\‹²Ðq!%Še3²w ºèmÕ@Â5y$«PÍUaIà¨JÙ{²ÉÄr ¨¹XJØx-iC¼¾R¨æbÊߤškPô5Í«¨qh±ñ‰j.LX먓a"!¦®®æBµš•¨æZUumT[аª¹Ø*Î+j.ÇÖ­V®üì¬M)W‘˜1âc5…±%k Žšk‰"ι¾0T\¿íuÁÑ^*/ôβPµFDÄÀ^÷² dËŠéå, VÏYRë šëÆ:D&É G(Z‰ÇÏ…©ær “‚ßœ„mmY+†hùª·ñÅÑj>6¸#$,#«*µn2yŠhÓŠÖ°×pS«a mí,0YɇXN,¢C,ƒ"VËTs‘XKiù2mG@Uɪ9i·%jµ¢…a£L[97µ*Õ\'G "&R#W 7¹ˆtåÊ2F=äjZ­‹Zž`Ô™˜6_#mVÛ¤šKEÁ`d¨š>l:aõ¦šË m“ZïZþmjj®k™Ú„ð6bXœ±ÎµL5)a”MTs1ö¾-Ž7å* PÍuUQ§½-GTsU˜…aúpñ÷4)à œ³r’šk%PßÂõyMï××ÍoLƒ½6[ë‡M”½PÍur”¬Ù{Qa‰^î™j® Sª¹2¬xé[”…©æâ.~M±Ä³ç—>¨æ"|LÚs¯Áeв ¸¡÷l‹_šku¡iöÅ•$Ý”ê…*¡‹–=íkG/ÚƒžÕ¥7ª¹N';X5Ž¢>¯E×Ô\‹,ÜtSN¶£°>eîv÷¿û´·°á›wŽZm†O>P%6í@©æZ)Ts±×Ø·×3µSÚ×ƳwÿB)娹Ö4+5×â¦AÙ_|ý®š«5ª¹æ…š«5Ssý£_ü½õ|Ã7웾áÛ~÷ßø¦ŸþwûÔÿôµÿXÿÇ_úßþ~å³ÿü/þÆ÷ú'¾ÿçþá×>ýû~û«|á«ÿê7ó ŸÿôÏþ̾î‡æÿЛ¯ûÁ¿÷÷¿üƒŸÿ}?ôOÃg~ÿ7þÀüä·ýÂg?øâW>øêWþÃ÷þÊ?ûí/ýÒ—?øá_úòÏ~æçÿþƒõ_|ùSó3Ÿù¹ÏãŸþ¡üÅ?[>û5Ï¿ëCµcW4ÁíÜ¢¾Rú­aAMeŒyg–½˜á·O ƒÕOÊËS‚þ3^ß$i·½Ì­ÖU†§Ô¤Û)˜„Q†—™³ÊðZ ¯2¼e–²¤ÐÛn)»oVæÆVëÑŽ…*+Ù.cÔ÷OÊÈ2až4Z~.3Êòv4*â¯æd]Ây º$rìo¢´-»LÇVë*ÃSZ°=ÏN©!Š´V&ød²Z ¯2¼e–²Êð¶[Ê¹±ÕJ²,±þñèòŠ.¢K˜ˆÖþ¤tš¦¼Î_ë¼Eørà AI8q¯ñZ~Àã 7̶j•vL°éZûÅaá&#áŽeM‚[›µ•Úµ4]l¼=õ6Þ/jÌ–ïÀReûÁÏ×N"­e[u­ÉÛ€Ú‚{¨ÒŽ¥Œë"ô/اFö¦[›„~F;Ö +¨€µkäP*åå¤ô%½A ²¯îêQJ‡-Ú*vM$`™S­‘v#W›»>&™çʺؠâÓšwž ض€c’~ƒNfàïBã`½ÚR°$Q;– \û·•’ KTà‹B;†¶"iÇ«(Å£Tp7Éîà ¬}£¾\0™r9Ai\?QO—°t-±³0°ý< Âè~êË¢m˜P ×^2QA1VQ[[%nYOŠ¸¦¬±Íý]¨üHÁNñÑ:.œŒªÅ©lBX¼7}J&d9èŽÙAèG0#kÆ׋j»st¶/ ½npÉI‹Öš/8Òº^L¸¸)Y¬¼¶u 2ßÚÆë œ¾)«žc o&qâà!íØI‘)É*a3@Lã avc­‡W†%–•ßO¥3F¬—v,µ¨äV£´c©¡©´žÒŽ­n‹˜²fŽ…;6AĘ;fÇoñ…í vðFåDá H;&JR;fP÷¾ 7dÍú´úP×Ü2æÆ ’ß“#ñµ (¬xãÕñáI Ø&¨ KÑ„óú,³Ž íØÉÓŠt•°q—vì¤D*äØË’ƒZU†B ‚†¦£{¬°Ž=?m¸öÜÙ¤„‚M8« I¬B"@)Ô6ƯC®ë\2˜#A;v°Ì/”Ҧݲ–uÌ*|a…Vñø´`ÁÁ.ñi~^“xÝpÀCÒ’ ÷,­QÐ ¬é¯ª„«_ äZ›Ä¹A‹Y-¶B “ÀÅ&Ëý" XJØx~Pƒx}¥ÐX9(ƒVħ€mMó*ZZl,˜³Äš°Ö iÉMy£6w׎¡ZÍJÔŽ­FM-_5iX¥ d«0¯Ô8Ŷnµrå¨Á&ÜèJ¨¦¼€«£-kÄdžJkɨ£Kf$¾0´Å[}¯ Žö²Ð’v3¾,¬ã»¤rå7°—½,Ù²€bz9Ë‚ÕsVOÐ*ÐHŽûï½´¦§RÜV $ßV°m+ªÄ£iW1¥ð1h’ÅÅàÜž)‰­ñtz 㪗d’쵞L´h’Hðº1òCçyePé +† ÿV_Á"ÍZëÑ·µŒ¬J§¨‹Lž"Ú` æ‡ÀM-4À×ÎÕ뮹XÄpbb ±0õ,b-AN ÉL"–ö8˜¸Ûµ0½Ì~ˆÑsÔʹ©EUI¹r”$ra"¹ø÷&—P!Xƨ‡\ØÙ?l5<Á¨30m¾FÚ¬ö5¼Å‹Z%õ júp°é„Õ›Ú1ƒ¶Mê¸aÌg‚~(ô{™Ú„ð6bXœ±Î‘ÂC”0ʮŤØò½/›r h0IwØÏk%l°Òæ"18}¸ø{ š•Ú…bíXÒ¡r}^Ó{°Žš’0 Ž´Ö ã(”ó›|çH]³7Œé:pƶ©4YVá‹(zµÖ±EY¸sŽ.¬)–8p6›:k‰ _›öܺ3gȂ↡+<.mÔŽ­” ýý"åÄ°“¸vWD»Š3ÚEm¨¸-‰bƒ[M;*§g~_óY;Fâôµºð­Ø¼r8Ù¥[êóš¯L;–ðÄd­Ç&YýRðØ'ÜÜæ³Àï>í-ÎÃó!Ç´žªiR%6í@‹è¾Ú»z}pí{¶ æ6pmE©»RÚ¥ëÛ,Í@º·ÓŽõÿj#°ÖM;öý±÷>øòW>øÊ¿ü,ÿÿëÿçÿýÿ|ñwñë?óÁû_þàS_ú¹/ý¥/ÿÂÏýï|ñ‹_üʧ>õ ¿ðÙ_û}ðůüÚW?÷ů~å«üÖþøWé+¿ö¯ê‡ÿÕ¯ý½ó¿~á‡~æßåø¦/|ùSŸÿüç?ø=¿ïýú™¿ùû¿ñýô÷ÿáÿîkþ°Ta´÷,mÕ1‚^Ü_)¼Ðù/`)æ)ÝÞJÃô˜?‘Ûèõ®~íÀÌJèû`¬lFd©Y½°¡dJ± ͘ô}­³I1ãè:ízøèn¸ ¥Ù£;ŸLFàî/]–‘YðJ?TÓÁMÓŸ}ßS zMÌù“¥¤õä¿û k QïG»”T½;ãGå±ê)Ê8­%e@qz¦Ü²^ú/¢=´–é[ìÝ^÷ùc؈ÍæÛDâ¤náR_ä^œ® ¢iL+uãª7JsÓ²5h´®êZ.®´Lö¸7yW1¹Vm§*DJEµXmˆØ®F¼Ü¦íú=Ó)~ßÖL®ýµ1XÂóÙÚ°¦©òxbÚËaoç›=S] ºô·«&™Œi– /êø\1Û³ÉU³\-à‘ŒÆ¯«Æ:§•šð¾ïã›Õ¼–&¶s½uØ´bàbôíeU] O)ô ød(ûWYLåIúë*'Õòª®ªJÞíqøC›ã4q;ý &`»ï4ž‡>W³£¼Ê!5¼®>Ëc{jOÅ{¡6»°Ÿ~Ul6çÝwçœCŸÚjy¤á•Çè|•ccqÕeãuµÇÇô´ÙÇýôËyc÷ÝtÝiF{ÁZx—Er;™"ÿ<ºN8giª³Q÷áO›’ØÈœH3 6ê[y5,%o6 VÎÜl”ivžd¾IN96 ]u½å¾Úfxlsœ¶«_6á¾Ç1ÅFsÛΓ6ec£æ䶺ê¨å±=·fõns[‹mýª=o6²ºzô©Ýç§á•Çè|•ccqÕeãuµÇÆôj³ûÕ¯Íé°Qøˆ>b£ß!½æŸë«“ÂKq~uf5«Ë³¤nýºê*²Ê1*Ô•ÈÌyD纺·o>‚ŶY}ø5Õ¦ØV±d™"]y’vW9)˜k‰]ÖµøÐÛ°œ6ÇÙë~áEã¼û¾¹åâ¨ÚW{/gq¦ÓÙ7G¯ª=kMÎmna¯'Ö¯7U­ïK.Âk‰isT”G•Çè|•ccqÕeãuµÇÆôj³ûÕ¯Í{Gð.ÿ¼ÃcÜQ%\Û%6l;Ïg)2¥âí: qž Ó_„ì°Þ©Ã f&>Ô£ a]RŒTÁ'XÊ<ü­+3<ééI¥@ ‹‹o•Jð w;ªž”ÉzÙP¼oJx óo<˜–?Ó$ )cxêU ÜÒ𫆇ÎÖÛµ}“"¼N…ºŽ®œˆùâ8%X›§…“+œOJQ%h–£ˆ‡e«ÆBÛ*îÀõ$ׇZé]ÄkR¼«Â“=T½Ç=+‚Áú¼qÆåíÓ•’ÞØ]^$®ßÁ…µµ‹ÔÅÆ5¶Ps’"q0"Ç…ª½…‹e¢€HÍÅj‡^_Æ»Póxãe%œ©‹cEé‚xAomóª˜6Ø,/wÃC¤¶¿Õyg°¿ÅF/Ù@2Éoìí)Ò&Á¤ŸÌ “.ª™³,ÎWóȼ³Vox›²TŠŽqm*{ñ+³7ÜF8vk (cQª\,†{mb¼,gn¼¤…ŒSe‚YH]+]îFêÁêÄ%†’¨KW4 L2â:­²b†xîêÐÒº¾ªgE2Éç‡ìû€X€Z³¨Íxç‹h û0¾"õ†·¸núFKËÑmš”IÈÝ#ƒ…ÖÜ Ï^ ŠªSû.6sÅÔûð•Ñ^ÍE¼û@WÎæÞ”Š} ¨Öü»!‹ˆZÄ›´bìó^ ÿN‘iDM’ÅÕÏ6ù±˜wИó`¨Ì>ÃSššYãzШC³ŠAI^£<îÎ$bxæРëZÔgŠÿÄq: œ²R1´ I0€ï@Y誌G”$ÿuˆö曯·OWJÇÕ¬á&>•æ£3ÚËÞ”«­Ø‘f4¦|%šƒR†w¿Ù꫆¹=J,lÑq3¹2˜Å'9‹¦Ž;ŸGÓNÄRÀs0$iÓ ,â)V{B¢s´våè6ãqyî8œ©.­£kõ»‚ñÖ×i(,žgVϺõtzCƒÓbÚÌ©g7,“=+"ÞˆǼǧ7[*ªliDÉi”Ó7ÃoÅãÎ`+6>õÆÍ&„“b†;ªÞGªi,kpÞÇ 2w|cÆ=$ÉRB½t˜mÚª™»qG7nÁFÖDÞûÑÔe¼ÔþJÆaJsËxñ)†;µW2~RÌÀ'?È8 oßxËøI‘Œã…Ä-ã0q<zq˜.]2Χc—Œã}Í‘ñ(Ôx@sÉø2 ÊõAÆѹ[Æv:)’qtæ–qH?ÈxÉãAÆ–Œ¼@}ñRʃŒ—ÒdÜa^2Ë›;Ã,2îøȸ§˜Œþ ã°hz”ñÒúƒŒãåÒ-ãп–q*dosn‡Ö-ãÀ2^z~q¾;2^Zz%ãàö-ãxOuË8Þ©=Ê8øaÜ⃌ì2~RÀû%=È8Ê”qŒÕ%ãhÐ%㥖W2Ž·x·ŒYclES—ñšmÏNjË°«rñ³m¶=ƒŒúywP¬oÕ ™ÂÁ4™Ñ¸3p3Óyçj`ÚùDp•¬||¹‡½L'Îj³ÎÈ }cOIh\¢a&¶Î0U£u‘OI54ÛDû”tRô±n²7ŒÉ¦7ô2Võrh“¶qßÙ)p`H«¸/ŒðèË‹Bűúù:›ÖàýK²ÅÂ+;;¨Æž‚Q{4´;9¯¾ð ÛÌk&¨issf¤mZ°“V6©Ã£:ž­èjœHKÀhào¾F2}7/8Éâ³dgPZLqcfcH«¿ý;«À§ÍÁ醪fÅ5O[ں͈’í’3dwZ¶·M|ì·°m31[4ÎÞœ {‡Á40e2à¬+¨Ó,?œE¼ !ñ"ç¹’mø[4Þ…{ŒäJGò[²J&À˜( ›oGSe°~9ÓìéÇžva嘮‰y}jÜ< b oÚ¢íê³h=ìô¾ª¤ð­ š-ÐÒP»é„êtv¦ß™ÁŒ[wž¡umqo XFõë’Šy&9”Pí <ø"‡%h¹ *ÁñÞ#œ a6OÒfkÏ<‰™Õ°'·Fó=™íœëÅ`Ú,–-•¶£vQéM`·ÇÞÁÀÍíA¯¥²Úþ¹k½¯³jIés—Î>÷˜QÃr4Š|wÞËꤙl VcÒÄ×æ«ÄmÙÍ#Vª~/t¹ø¢ÖI×24½)ÞƑՀ룷ۖ.ŸZ¦ Ù–ZXé†+n–M¥´ØØ”.¹ùrÉ…õ©8Gr;‹3 ådL­þ°v2J+7ûwÛ¿ö¯6±{ŽÅ4´i#ຊ¬Dr¿‘šÜÍP›‡AÕfÑ'ˬ–déa¹E‘oþ·fšš…$X߉¦”ý…M'a»éDë4d¬Fæ"óDm?¢æЖŒè“Œªl ¢-S„à ¡u~ ;m»íŽ«Ì%ú Í\·Õ¼éd¶5(íêi7MÏÖ„áê×õ~Z³›4®;¬FM÷Û¢¢þ–õ¦þÖš‡Æ²˜"í"_¥x+#̇_]X¹¤³ÞÍ–†"7ì1¤µ—6;>Ë|–•ÉI‘aÄ”`ÈJV,Í'jÙú›n/u j f)G0ÍNVPÏΠ+ qæ‡vÌ”ýÒ–:OþäÓfM­ÁšêçPM8´bb7—ÐF€n»¸`¬Ž‘SzcÖû©sÌä<0¬cM[9õP6ÄÓú J§Aœú{?¤äÞ)Á2’Æ“@…M‰RÕ+3ð­¶gŠœï©À} RµÈ½AC­L‰Ïdzsf4aI»¤ÆÃÌǹÔT߶~öì"æX±Ó_ˆÛ’8^¿­Iœ ê1ñlÎĉïTÁ"áæѽúµæ3£µÐ4¼ÞÓRØdûê©d r¡Uƒ<}¿ÿAk\0ż¯†ƒ®œâô£ê²/3ŽŠâÀ¿Ú‹½šk°ê^Æñ¸˜FDÉ®ªc³º’_UoÏãfTßäM—¼'O–MÓUN–ÑÈUW4ƒ¥Óž¤KÙ«ÍfŠsõ+Z]»ï1˜©”ÑçÊZñeTÿÊhxå1:_åØX\uÙx]í±1=mÞã~úå¼±ûî°é£Û®êl4ª±ÑtRÎbrv•>Úf#þmï?ìí¬Ï6d‹æÃ_­®ì®Éb1+²6cš' KÙå$uëª+š]ÜiO4ou§Í¸\­ýŠV×îûlæ„?îaÛyÒf#+'4'·×êf£hl4}ؼÍ!xÉÖ¯2óxì{™~‡íô9ÏU†W£óUŽÅ©ËÆëjéi³ûé×ætØ(|ÄF±Ñï^óg,¼œ”,ÞXÞ«™`#ªûßûæ1«=šAGÄòÊæä)ª£ÌæåT3» Áª6Åv”–Ú«<&æ*'™9î©+š©íiO”AèÕæ`~úe¼tõ=Èóæ(Ï3œÎ^NrØ]WÚÝÞž|zamN².?ýª¹z9Þ÷¼{á—»§8 O£óUŽÅ©ËÇë´ÇÇô´ÙÇýôkóÆ8+Þkþy‡Ç¶¹MÄí)¶Œ0²¡¹ ‰€”¨/ˆ`×1Qš¾˜Lm¥ì£ áç·O¤ç WbkëtfF)ˆH†+w•JÑÁÙÝŸ~‰ ¡—‹ðÿˆím̦Ÿ` ÎTHÃëdÓJJS^‘úoÆE+E×WØÁEzN:ü%DL£h7B ÈÁÿI±JØ,C°çAj”¹ «<ý.+ˆ×HY£vËI.ï¹GSE|y°ß¨\)8mjty‰Èˆ“E ¦¤“mŽm™2·‰ JÀq¡f‚£A™I®Éq¤°¡>Pî¼ã°!|%KA »¨+†‡Çm¨¢tÁl†W Ï/ ë_ñÂ2·±¶³ûÒÖ$7žŠðÛJDò{{ŠôÂǫ̃®Z)áè‹kaöÞWpÊW„sPsJÞ}3Vº±‹%?Jl1uï‘é"æÎ0¬MÒDÜMÍ~RxÙÉc÷t§É«=!ó·s›q5óF„ #3÷­›¸çê%vã5©Ài÷ŠzM½»õ´yC‹Ó¢ÙÌÙ²ºRySëQO±S¸,Ùø)ÏŽ,âÞœ”LÙ('5§á·â‡qg° ŸzaHŒ±S2~öê}¤´_á&ØÊ—¹MäÝ;D’´)(sÄÒª‰Ë|¥·Ô´EÞûÑÔe¼Êøñ’ñ*-è–ñê‘ñÙ^˸§HÆq¹|ËxÕíÀ–ñƒ]ÆOŠd÷Õ·ŒW: ºe|ÔW2>ÒƒŒø ã…7ã.ãŽ$Ô¼./ïBÉ8]_2ŽÎÝ2~°óÐI‘ŒW5rË8¯þo¯ÚãlßØd¼jwÉxåAÆkl2^õå%ãµÄ[Æq¿xËøÆ[ÆwŠd¼Öþ ãµôW2^åfñäХ˖ñªËô§BñAÆ«ÖÎ-ãUWž[Æeœ/þ.¯¼‚ß2^åaé’ñªÃd¼êIÀáUð+?Œ;C|ñ·ŒŸ”ŒŸÓƒŒ£üG¯2Tv¯z¡ï2N÷Ã2^ÓxqX9Ü2þŠ¦.ãæ©…;S‘õìj1›µˆk`6N–OKŠõ·ç†Ñ˜i7ÏÀC€:Èv>1ˆ«6~Ö’ö2”ï©«;à‘rè6É]ÝEÜö&nsAÖ!s›’ªn§¯)i§Ø”Ôu+ëp$Ûú ò!cš8´I;ØsRpÖŽ4?ˆÎ!¾ mQè¼:gÓÚ­2B~öã°4=µG«ŒñpäÜÞ8¯˜÷L0‡17å$6{rc§!J.íy¶‚Ý1…nŠ:JÀhàdJ?E|7/H‘àgÉΠ}µ1äÊ"‡ʀŸ¶ ¼‚¦?hð`jmylëfæi»d #/ÛÛfÚDÜŸ‹1q'ÎvÎ…£Ì‡Ý4gÀY× Ö"|ȃ´äl­ûÞ¨Ù‡ñn³§"T:’ßt¶° 0&J‘l¾”e ‹êgš=ýØÓ.œ¤kbö»×(‹æÄ„»ú¬ÞT;½kÉdÀx6GK½¾ ͧVE5ýδ ¢'ÏÔ‰ºYÔŠ(ã¸Ø’ŸXÃÕé \·Q‚™pPU‚–›¢6ö=ÂI¡6ypãa¬ÛILR'ŸÜÈQgf;§Ã0$˜6‹eK`¥í —æ¤%„ßOp[l¶‰ÜK¥DÙ;Fø˜é6!ûˆpé› =5,E~8ïeuR'h«nYkÑX%~h;H›ŸÇu5ü¢Öé ¨ƒðüDÞÆ‘UÀíÊz»m鲩7¾å`¶Í–cHEƒóws¥K —¹M„gqÜÑG¸~4F¡š´JMõH]MèÕùLÌÝ‹í_7û÷d»ç@´ 0 â p]EV"íc"¼5IµªI/ÿ‹†Œa……‘*ƒ‚[›ìÒ*'ÝÂx™½\9¸„ÀTg:èTI1'#œG¸ˆÍ¸ çÄC/”œ5°¸WîV5š…+Ïj,§çÆ„ä›Ü\¾¢àÆyªEUd†Wܹ ç£ý»®8§6ô9S Ðp ÏÖîÎD /'AžÕ‘Ó#T,tÆ@/êk`•}Õ%ƒ$bךä¿O›eØK#-¹4 däú˜Àó ·Kpt::9¸ÙHŠM+§í"5Ëf¼™§¤F×þŒñL¡k]5† çÈÖ6Mæmƒ=‹œñ "Ù”—«M{R¤÷…+Ö}~@Œº¤c ç^œ78mÓ_÷ÂAM­”¾ÅÍ¥°4[1 /ˆ»Ô¡Å¯1c´ý‚¶I|\6fÅ~ý U-ˆ ÈçbãÆvC< [bgHF#M’£Åë>*²y&ãYmPOµyqX`+ŽtÑgU|é´å´èâ’d<¡oWxu0ßX9Xí=ÆN°->¿X.ãž¼>Ì݈?ïNiÄÅkÎÓÈ55B1ò*WvnÁ@Ÿ` -n“ÌáïÔa!Üðærå€þк¬À¦Å8¦½Q¸×R´DÙ.¬`ó1C©9Vƒ†íVNÊö?œñ^•› (ª4 „/7ThV<–:Œ vÄ6(ü€QÅ©~À”§Œ{ªRž÷ Ã+Ù'Œ“ óü¿¿“"WêQ9KkhT«¶®vÙ¬p v®],)¿¹æý G¿3>û¶7*šè=\5®ÁæIy9)8SĦ}u¥(ðîÞƒUiø¹…ä©V x#±—ê^Á¹µq Çxù.`*6¸—ÊM*ž£[<Ö HEˆi†í±3 ›xq<60asŽT‹A¹%h r|¹a¶¥Ïþ¸g™dl„Ž|æÖ[z‘Mb³i® j¯”£‚äL¼95E3»Rt ÇUÉ»hÚB›í Ä —­«2E¤À¡vj«õâ°“²ÅBà”ŽÈ¢x:ËÆø·Æ•cDuš‘'“¦×K­”æ‡^ežlw/jå¢+'Ün&«™.ðËÉu2û¥Û¥ƒ‡yt:):·9ÏœJëø‡Ã®·x>ö½èÐ>èð¤jëù×Z–_ûŒ¯‚}†û ¸‚ôÿx‚pÇ»‚}ØŽ·`A¡}´ƒ`—iâî ´|Aè9ï ±>7ÞÁ¢s\Oáá HMöÃAÊèû Ȩ ç ¸á>ž”a13ÇÃAšÂǃ`§{H;ÒWÿu<Ø‚;EAÔw¡8"è}ìÒè (°‚‚~dW®ƒ 4÷÷A°+Òòu„’ø>öƳƒ ? ÚA4îƒ`× v–zèOïƒ`W° }ì-¼:‚ÿ[ôÚ*ô^_ûÈÁ>ìkÆ.õƒ ˆ¥ƒ`¯íá ýô}Ä=ØãAº‚º?ðƒ  ¡9¾‚jÆÃAAÄ"œòG0µ¦ü}Êë ÌÅͦüáêtE`Où‚{Ê´)å¸?T4u×´§ü“ÂI¹ç‡AŸôG¦K–˜Ðß °:i¢*¨]Õˆ’B<ªìG$cB¯[ã-…£0RȼË<Ô,›å Í´6ÿà !:ú¼rH°Šÿ¥Ó 2J'Èv¾lˆ[•UÆ“rÒX0"&ÌM°" Á ½Üƒ)C?«ä7ÁÆ#ÁÆ#Áîi n¯JÁаŠäç‘ýcxwʽ։¿údøªÒºéôÂëqm¡,G *Ú_M2ÁM2ƒ\¸3ÞÇC3x/¨LvRH$xdÈýC @tkã$_3┳^öÚþvz v³©0h#zß9+a>;K•ÓÃs졃«»‚—7Æ@6!ÁwoŠZ¸A¢eÒ]B“FèÔ½Î[ˆcâà°§¯‚³E rô³¬c¯k ¡?Xñæ÷ñÀ:¥*·ŸéÝdX'³î+ܳÜVx0¹¬x°~¬«qù:°.˜®+šþlÖBÇ·÷µà%òu`]ø<|>øp`…'˜ûÀ ¿ ×Õá>°z‚Xñù}`5$g)¼;9¥u`]ý)ïX§ž€ù•žI®+Üß\VïÔYÿ0â>°N;9VRå>°2á:°.ï+ñÃõJÙVEVŽû‚÷}ðO²ÚûŒa5åGÿÜÓŸwßÓ|ìÂ%ƒcÅx%R%a饻â®ýÓä>ŠÞ‘qÆïÃöv ÛÿÁ &Žð KñT€îJ×ʼnӅa:,¦ºhçÀ¸* ƒa®åÓ®€S€s´‘ºÌ;"eÓw‡þ. ¥Èœ€"X‚­FÊš";ü&C÷jíHC]·Ÿ3ÿV8#˜Xhæîæ{)Ê ^:€$nÆ8;0¨S”3“Œ šKì“òrRfÈ:úò«ÚRÖÂÄI1A®ƒ5 .V|t [ÃF¹ràš°ÊÃsÑNjL³ºKfuÂé-Çã?5Dâ°$EÉcþ{€¶ytîÊ d{fd0ÐÂßáb>òA´}y¯ÎzZur…ûˆâ4¸Ðl*qwx)O‹ßÞ4yKWÈ5º‡ —¤=jîzÖ™.ŒUn–çäÎX† ©~ä"]ΔÉãš´àåIweòÍËÑPðQèÞE0¤R-𼇳t¬ 0Jwwæ€|]ýìÞÌMáú%%#<Û$<–<ŸGqÚÎÀ +½Ç¢ý¡ÜÛª½f–÷ÜíÇÔGD`Xšÿ½Û/(Vx1ˆùaÐU=ã”rÕ¸$ùF«RÒ‘ÉsÈ:ê p>ýχ3xAjx_™¹wµápxÆcðˆÈþ€ÓŒê¼0LJdŒF8x—MßÐѦ°ÉÁÛ±«§ˆM 7ÙÆxåøÈ&¸Ï¸ÙÏØÄùá‘Mð¸(ÛòØB5ؾe&yž¦šrG»£lü–1H®Ÿ¡ùÐ×Õ’/0´=§ïWªôŠ>y97¯Q/pV뻉¤ÎÑÎÓ‰N+\<óÔ>ác5°; Û±’>ÄÛ[Ñ{6­«æñ¬ðë!0GÓ®¦s,Ù«4¸S.+{Ô|¤Ùõµ®íÿ¤Ov›ÙU`Ü@>/Iæý³>!~´?ºŠ‚ÖK£3‘PF°ž®"ÃÖ)ºáËCgp…Áã,ÕJ©— ±À©D€weðD Ôµ®½84æî¹Û}&¯¤3ùÛS«136ÙíCàØ!°}‚ˆ½™Á¸Àt÷ê„àm^/'œ®8®A, ÜtãúÐV¼Lè†$žòr¥ôhççýÕ•’¹íÂDN'ž¢'\¬‘v#‡¼„¦¢aáý AÇ´Ø«Eã«iËõdüf-ppèŠÐÈz‘² ­òP‹Õœ¦h’ËxÖ趪GŠ{µeÙÎ#JØœÓý‹¹Ý»Ø ÷BBÿµ‹¥™E`¯%„g-´],çêkë5¹q§ˆa `ï =3½øÜâ>z<»X½‹%<»XAÛÅÝî=êñÕ.ÒqïbáC×w±ðÇ],4ï×.jãkKÑÃ.v†ò°‹zÓ¹w±û.v§h;C>3÷xœêÙúú°‹…ÛÈ{»ùáq‹ ³Ñ”k¼^N0¿ÏE‡gé¥æÜêäü8’.â4MMyö›Nõ<äÀæÖò‰v¼^6hª¸ÄŽ×*mî|è+œß¢í¼:¯_Xæ¯oŸN ÌõV†Ä7ñyè !1vAÚ˜5t­„ž£HKé8,A×ËW m |Sœ _ï1èm³£`·N 6v` ÐÎ$tp4uáIa xԗφuáAååÞ¿ÂÉ{¹3p§‰M~w ¦"o3bpÊfW0O^ x;ò¥@²_Q#¥ãb\/…¦FÃnF»§­6GÙ›V.ô³±G,|ïüé`¯\jyPÝÁ­/¯À‡{`Gt)Uªé2jß}±Ú5 S…yŽ™Ž" :ùQöäƃÅ4ýžBeOÙŠHgŸà˜×÷Øû“uÃÞ ¤æªíÊQŽB@çÉì<*óQ[¢³á®QÀÄÆ,_×Ë! §ü‚©;8åèS~‘ú}Ê_Ø6“¨WÀ§|Á=åUXά{Êß5í)ÿ¤p’ψ§=?ú¤Ÿ:³å}~X=›WuùìÌQ¶4£v~pHÖ^åD\'óÄ€é8àed¼¤0#lg:«xè”÷aáLK¸}ˆÈúúyå, ÿËO‚ûapÐ<;à6`oøW%—É7Á<Å(3¹þ.<Ãûð¾WÉÆM°ñH°ñH°q ŒœE04lr¾Ð¥»>^ [·^1øBÔˆpYozá:G\f9bV˜_6ÉÉuÊxuÍà¦>0ÙN‘p1•û»pdÁÕ½>ǃ%Øký½éE¸\µ1⓱³eXic>ÛKÕ¡‡åð¡ƒr×Ëaèè½\+…·Ã\¸A¢€Hw Øæ=ÔèOñd€!«ÖÞÓÂé.'yÌÚú«œ`‘sôWzvôW|6ö ¿ÊÑç6ü,®¿ÊqôK•Í@ÁõWÙž;¹þ*»í¶ôWÊŽþ*áÅÑ_¡éϦ¿Z­ìú« ;ÌKµÚý@ž()÷õpë¯räëú« ]å ¦¿Ò›°³Æd·ÖÙkL6[ÖcSZú«œôPûÖ_e3d4ýésé¯ø^îè¯N§|ý_)ãÖ_éyÞÑ_‘*·þŠ —þJ/þŠøAu¥lý•y£ç³ÍÜ rFÚ5àv™‘x»ŒµtüiZõuuè]¸D÷ ¿N£ò¢ûnJê½*ô‡¤œ¯Š®êNŠÇ†ÿoڈ׵ß);fy5×ð˜-"¸îí?$%5w÷o‘Î?$å|E}ÆCÊ»µ¿ÓÂÇð ¯m'ÐÕèç)UÎò ÿÂÀuZìÄxðÛ§ˆØâù¤ÐÅÃ7ô½QO™[­æ;)x±c.õ-—“~T&ìaP†×jøíÓn™¥¼<í¶[Ê¹±ÕúÖ_‹§¢‡ÓŠâE²xJ“÷g]š@Q‚ŠTÈuÇ ‹Â¡{ Ýßp0=E¾¨N™[­oŸv \|šßnKIõ¯2«È Þ»VüÛTË,ååi·ÝRvַ̭߬ŠEùIn’|òéû8­Å#Ä55Àõ4Nĸ2©ÜÁÛ‡ÔçÍœ€¬0»ÖVn3` nJÒáQÏW² "ÌÜb.°˜ž±;“¼jX-xßèåo§$ú,‚¾¥õwa¦Ï8–pÊWŠòY`ic XPhƒ“ûóÏz¦>Å ’¤T€3CæÝMÔ©;ùõö”—“‚˜‚Ný«;Eú:DD eÇ·ªrv£Vx#k1ݳÁšå £[”4p )¢Yu-úÙ~Ú‚‹«Êµ4Be8OçÊÈÓwg„<\-Ä!GP ågÃ#C¹—àûx‡U”âëï­.lxe _n˜M|¨šºBëh#Ë)Â\ÿvMÓIa/UV³p®ð:…bfÁ÷ŽW„»ÛA&Ú)â¨Ãr*?Š_l¦øÞœ’ˆ|T*þQ6áp§Z‚Ђó»ªÊ—f„Ugná·¨;[DFÏÁC¼nF;p…ÉòñÍ^)¼/‰ ð•ÅÊkS¡imc|±Ö‡¯°£5äìrc8ÉLßµ‰‚!«1@aŠ k˜Ý7ï  Sù}ÓX:cÀùCßú¿”ŒÈ´ƒ¡–B¢éR‚U™;!zNíJÎ"@ál8Ó1cXz%›ÐwŽ¨è¸˜(Ju*¯QRšiBÞW/‚"šB³>Îx«17F§«¯)–º+àÈíòÆàñáNÁ^ £ Ÿd €ÂD¨pfÙ_4µžª¼S‚ãY¤Y½R¨>‰Ù¢8¨¡U­i Œ[±¡áVXÇžŸìo²7ˆ ‘öÔ¬.XôR¡kœ ¿µhåÊ1uÓ‡¨ðzãØŒ/<6¶Š˜Ðøºv lUà-vHpKD›Ûh†¢[ÉŒ3 ¯ÈdÙŒìÒ@pmºÁÌû¸]fê2‰$pÔ %Œì=Ùdb9pšìXJØx-i]¼il;”ƒò‡ ¸¸ `¤vW±Öä¡ÅÆsèQM’cé„bjN€t£49Â_Vf®Å\¾ô\'"À—B`wÍ+ÒE:¶nÑTÀsðçBórÕ,ó 6ÞîqÄÉ`=h cKÖ@åx$½ËD€ Ãj?Zµ.dËB ÅvMZž’JDÀ—A_ ‰*,¦—½,x={UØ \RíÕß¾¬Ö3äêyá~UC8Ë$‚ù¾}Ù7c'X<. !”-q\ˆz=îp„‰phÉE‚BŒAM…aÉHõÉÎ`\I°b¬ÝŒòUoã‹#ÄBÇ–1˜ÁP¦òÎœ¢™P«v™*xŽD.U·pÈÅ¿7¹ˆ`G^eò<ê!ÉÝ[`Ô"äÄÍ*7ëÅ‹‚‘êP5¸ÄØtR,õôfèC†ƒÕ6)ñcÞ‹­¶C¿–©CÏa#†ÅÆë;6e§¬^e2n"èÃâ* (Ä詺çY Ó3#\cÚvñ·SžN8+ó6F±]Q{±>cz‡©s³Å‚’ä€Þ1ŽBðñvçXÓ>gï‡Y4Æe<öB³A/Wm—*/1ÎÚ€ËÚ8p6“ òàå!­rè·èæ‘] Š`ªliS€Eh@ \M§3›³« yx¸w)éeýÉèÔIuˆ¥O“ÆNý™ßÓ†ÏÖø5â´¸W¸êóÊádOzÂFQŸËVó“´òÆzœ9L8¬E û„­YÞ üé“ohô>ïµÚ )|  m‚ÛÊ/WQôk#p=S+1·rÁe_(%ûäGž×4Öÿ¾?ädAÈß¾ÿôßýôÞwÿÉç¿ò£?öçžÞûþ•íé½?ú<ûÓ{ßñ=ŸxŽOï}çħðgžÞû®÷>ñ‰ïZð{¾õ[ßûãÏß²~ùħ^~ìý¿ô—×'ßþíOßýÏßüüÓïü=_õÿþßÿá§øï·þ÷ÿøÿË~í·>÷[ŸûÔW?õÅ~ý×~û·>÷SŸûÔ—¾¸ñ秾òE¤­Ÿ¿ò¥/þÚWíÛ~ý·~ýK¿þ¥ŸúÒ_ûê_ûõßøš¿þ±§?òÝÏßû:Öf™¦ò‰Š¹õþIIŠžU†)r¡’ tS+~ûT’©ž,åå©ÄúøMpå••éØjÅãKÙq=%©D¼Ìu¥:Ãku¼Ê°–yÊ*ÃÚ¾¿±¾í2½¯VëVx@ð-D0=êNÉÒŒ¨þ©w™Ô¦ײYL‡b) K0ÒÙ7ÁŽ÷^¦c«d±”ÐM3ã)qZN+3âeÊ´Z¯2¬ež²¨íûëÛ.ÓûjµŠ,íùÇ?¢Ë+º|ˆÖ«$Se¬•ô‰¦n|¹`„¦õJØÛ¯FsÎÏt|` ei½c2_#á35­WTŠ] žÆQëuRBçצæz £Ê6­>_;„…›êZsd^P b™Š*É^Ët}šLë…çþx™L…½µ^%ÙPZÊËIÁ•u\û«;EZ/¼ÒA MëEÙÕ)àä-\Qÿš‘y"«´^ Í‹¦õJ|hS’i½ø[’Ö+I³X’i½x›Ç— É´^t`‰¾›Ö dkQ’´^Iqµß^¬¢[dŠ½°Yɸ,+ÉtM€/Z¼C¦Hë…k³Ž–á´Ž‡—k4 àa}×\ Ï‘ü’(Ò×:‹™YLTPŒWO0d¢"®É¦æz •ś֋Æë$¨²ÈGÕ ¾U6¡|¤¿8ìÜ”dZ/úÇZ’‘Mëeø-ê–ÖëäÖ‹þT:°´^ôO–ȦõÂKëÅ9%›Ö ¬¼¶k Këe_˜Ökç0 ±1¬"8¾;erw²J¨Î…UHëe˜ÝàÉÃ3$ÓzA<9–Ætª²µ^¥˜ÖË?¿í^ñ¾‘Z¯RLë…”µ¡,Å´^ÀXZ/ÃoñE²IÀsDmÜ×Da %i½ ö"­—AD°^ƒW¤õJz™Q²i½ £Ó¦õÚ9L§…›gT¼1 žÉ+;E¦Ï%›Ö‹>RAgÓzƦõÚ9L§µKpÜ«´^W -K6­㾡UdŽ‘MëÅHó™ò™§æ§Ç›ì b‚ X]HbÁ´^†ñ…i½vÓi™s烻iž”fÑEY ŽOx\ÎVIëŸyx(žMëë’"º™Ö‹XÈóÈž)èR•ÖË`¤1âúPZ/˜±DXZ/ÃÈnZ¯CZ¯ˆ ’QÝÑ’6Äë%›Ö 9(¦õòŠi½NÅ´^;‡i½"C-•bZ/›!N¨V³µ^%›Ö Ž.8¬¦õâ$0­—a뵞ƒ?'{ÈQZ/ƒ‹Ä˜³i½,ô€µd ÔÑz•¢c¯- Eê&[ e¡˜ÖË—…¢5‚öxö² èË‚- Å´^¾,x={Uð­e´Wïå ˜Ö+*øÑÂýª†V<,“¨w)rJ‹i½è4“i½Ž0i½LöŠi½à²‚SLëexå¯Òzy†lmY+†nùª·ñÅ"†TdKÆ ËH)¦ãºÈä)¢M5¥Ék¸©U¥õŠz/¼`>Äpb mb±ªi½h‘Ô€¥õŠÃ4'¥šÖ˨UM뵉aÊž‹Z¦õÚ9 Î¢Ïp`äâß›\D‘D`£rU)¹µ<Á¨#=×+¤Íj5­‹Z%ñ1}¤ñµM'¢ž¥õ2hÛ¤jZ/_„ªi½Î2å„Ø9|Ä&·0‹²ÒzEy$ĦõBl «´^»Óz*Ši½Lüw šš´^plH­Wi¦~¡÷ŸÅÂÍ´^˜’0 6ÓzÆQÈ´^;‡i½à¡f‰^i¦õŠò"Ž/Lë­êÚ¢,,­W”Ã)âÀÙŒóK3­Wäei¦õÂ`€2MZ/˜Ñši½¢ÜŒà{ÓzE…¡(Í´^N©f¢CËfZ¯Ã”Z¬ã‚ÕTå'1¶žù}Ígíh¦õ:«K3­×ÎádA5šÖ‹ql¥õZdᦣp˜LëÁcŸLëå ¼÷élši½vÓz1ãU"·%MZ¯ÒLëE/+HÓzÙlALioMZ¯+e¿Ûú‘ç5®õ*=K‡ø!Z¯Zþ«µ^µ˜ÖëŸü§¿ó§>ñ·ùg>ýéÏýÇÏ}õ¿üßoîï~ükþ'~ùWòÛ?þõ?ýË¿ú?ùñ¯ÿ[ÿæßþÆ_ýÏ©¹hš0z“{Í÷OJ-C÷ZUÁtÁêR]™Å0î嵞zÊ‹Å9)bÓO™[­°Ö±”,íÄËI¡wa†žQ™pçB]„Õj˜ŽÔ2KµŽµÝRv̭߬ÖË®«Éx¬Ètîý“R]mãFDfø_ãõà·²˜¹rXX³+# ÆSæÆVëÛ§ÂXÄfĤª–iĤ2Á¸$“Õj˜nNÒƒþæg÷ÍÊÜØj}+Câçÿˆ.¯èò¡Æ]‰îªb¥0öÀ‡Ž„/7T/œ%#ÂVNíAApŠQDó,„¼ÕÆýÅaè2îJ<Ä,f“ÕR4u¿=õ®³¿|HðYNÁwcô˜à‘‘¬T»ÔÆlÕ»úTÍÍ>’Ò¢u)ÒO)Cÿ3îÂk“\wÊËIáݳd_Ý)UѬ»")u>6^Ð"™±UÞHì2̸‹0Yœ£C—…ºÌjªÅÎÂ:›í7: R„Qw ˜»wEYñ6¶9ñ°¥qW„‡·ˆý®w«XÊ6î£ÕIv§qW¶˜¼Š¶áp+Z>€CþQeÜUŠ¢PÓ ˆ W7î*u\Æ]Dr Èb+LDã.¯S2ÀÊ\_ãyfZ~¤ÀÇîѸ‹1–AêT¶â/w7î"lCÆ]؃NΆÝžprÑÆ×òßzåèjK§×]šE9Kȸ *kŒtÑ*š§-²2MGQŽiyE•ôÉù‚2ƒÆ]7îò–eb¦ávÛ-†Õf7àKçdtbáA‚céŒÑëƒqW´d,ƒÙG g¤ˆ“¿wîo˜Bã.xw1LÓ-Ý0:ÆM³Oº;¨ƒŒ»Šw¶æÆ]„ÚÙFù#TŸ’® ÆܘDÁfwË‘d± K?w9†CYFí” Ó,ø!F™ÚöE<¢œecÖQ¡æ:9*_WŸ6înÜå)]A¥ñƯEq»` …0ã®Òlhº¬€ ½Âøü´áfܵŠŒ»ä¬Œ¬B"Tz¥sL«¡À€Ú;êfŽ$ã.ÇÝCaî”Zݸ ûdt¢ µŠç Xž4â h yoÆ]ÕÖ4î‚ÝT¦4î"ˆÝ»C•qÂ;snÐb+±x0 \l2±P¢€ ã.ØŸuqœwuâ!åoÈ~x0£­iÍ»-™<…LŽY 2X -þU›û1îâî/eÜÕ¦–¯˜ÌfJ=¶J¦[ —jغÕÊ•튬3 $s(¸Š4îªC VÌ>•-aÀeÜ…¨¾0¬ö#†­ ù²°ÎwÚ(Û²BŽ’Jwø²`ЖC¢ ‹ée/ »_ëjOÐÜ~ÚLßXý¡_A;…Ó÷dëÚEË“BʾNš¤lËa¯ËeöÐêé¡Í²%¸ûuÞÌ{ßù<¦?J\ð£á•Çè|•ccqÕeãuµÇÆôj³ûÕ/ãÓ÷áŸwxìŠ./»2½zS ñLÇÛ{¡Q+Æ7œp¢‰øÅÞ8ÒŸœ ?¿}:Vð¸òêïÆ(‡0aêI¥¸ •šä¢fcÝ~R䃘 Å º“Á% tmÁòÓ;ŒT‡ÃëTßš¼ø¯-:‡2¬·˜q½*=¯"`<¡*¦ Œyžuß:'EaáÙ¬`d!ÅqR‚*íwD Iï"ƹŒî˜Yu¥;© ŠPcÞ¸XŒÙ“ÂP€]^9eÕMö¶º¦© £9|§Û\§ú0ÑÙSäX2Äi¡×{+˜ëÃÔÄZp‘:ZrÝ©G;/²iÜ9`éÊ8G]€‚”Ì_•½ù–DèªÚbyÏU”fÑ6’ž£f{d䷩Ѫ‰ri2Õ‚1‹9òZÁ©@] ¢²Ç6„ÎK±ì9 Ôbc`÷YÂ6JñÎ1ªÍnñÙ½Úa-ÿ¤BØWó ÆhCBe>…QE5‡DSk”Ððv© kàÌhìû°µÉ´î¸_…Êk_‘zÅ[\7}£‰¥åð7þkE0Ð÷XyÅÃG=®Wܨ¦ÄE›+ªLÆÁWF{Úòmyz~Ež>>ËK;÷¤ZNþBäXÄ›«VØñ3¾Nj+{§PŠsL’køžüXÌ«P+Ê Ø)TÎ-œ%0Qá×äD‰ Éjô‘W(±Íä¤ÄK ˆ¼ž“{MLº­ã׎(zK"4€¯áTgŠC…$iß21´õÆ|æóöéJáBÆÎp¸‹Ä'3:/Ä´Ræh+v¥ÁÅ…)_™ÑXš®iŒàÉVÏ*_ŸxÄpKl–'šK¦!ýÎЭM²ÏuLNRÎ’ý6·ö0ÝäÚ$V{BBy²žçÈò˜O_¨2sH`­¢Yõ“ø†(œ]Áx5jbñ\³X+ZO«748-jÒº"ç,“=“ŸÊ\¢Ä±ïñÉÍ–ŠŠVßÔi”ã«&ÇoÅãÎ`+6>õÆædüJï'¯ÞGªi,ÝŒ’cÅÒƃ "IB”q;®ÕµjæÜ•[ 55‘÷þ_4ÝÁéc%ã%ÄGŸõÈøh¯e|§HÆg~”ñYeÜñ‘ñb2>Ë£ŒËWù‘ñŒà-ã0ã¿d<»_“q<ß82¾…·;—Œ(ŸõQÆg~”ñ7í“ñYe|öW2>Ç£Œol2>ç+g˜KÆq±tËx‰á•ŒÓsÅ•¡–7|ÉøN‘Œãýü-ãxDð(ã¸r¹eœ—2—ŒÃ 䵌S¡ø ãEáÞ·ŒÓoÄ%ãÀ2N —Œ:EÝ2ŽgQ2nß2Žô[Æq•ù(ã¼ü»3Ä?Øeü¤Lüœd¼Èç%ã´]92Ž]2ŽË²G‡Û-ãvo¿eüM·ŒO`gj¤žE]íÍ„¨(‚›l:Pô°mzkjü(»¯Æ%¶Zî I{;8-60í|"Ø馟µ¤½L'–U˜{vQES7h‡­óú sÅ)‰ñuÊ=%}ܺ¬ ödÓz©8ã O±IÛ8îÆìúOÆ­Uǽg¤gz^ø{§+Ãò|MKóþ%1%-+tvP=eu¡= .9÷¥¹Ökæ=ŒaÌ-÷³ðžÆ> Iê¦íÁà,‰œ0Œ:LÀh<Óœ¡4;¸©`á$[qgP|6mcFÈ1œâDý^õ£\¢ ìnT· À ¡à>ÏÛòÐVgæ:l—ŒszP{š<¬×žŒ bLzCm7ç"ÍCŽf xþ6à¬[¯Ó,?œE¼ !©=êŒ4² ?Þ¦H¢ƒ]¡t$¿É8sa`L”,ÁÔTYg$‡=©Z?®i·6ÉØ9ê0n¦óã…í4™Š¢fX»ó‹8TGa(U˜a‚ÃÅ…~N¯¢?s0/Ô–G¶<ø&Ž%`ÑO¬KXÄNÀ$‡â4”x” åF1S6Þ{„“B!Dš'i®°°Ä$Eæ-Êe0Ã!‹ ê×f±l ¬´x¤•Þo°È“î¶+7‘×RY«N Që=ÂFu›}DZÙ˜cfºÏ9˜nÄ{Y”À¬Æ¤Šï@1~hþ¨¢ùDÊÕÏ㣙³|¾Ì’LoµLñ6Ž¬\‡$X½Ý¶tÙÔR«é6ŽÔ6?JXŽ. ÎßÕ•.½ùrÉm=çPnáß×…*Ðbj2¾XØø̘»eÛ¿nöoѦ.Ï¢˜&T\W‘5˜s6h›<ŒP›‡AkQ0töEf´„ÍDzÎ)‘oþ·fPaº×¼Æ*Í"O´[0@Ý|<Ñȸ³™¢¥Já5‡ÖaD/œŒr%MåÃÔA´eJÐç9µÞ'"vÛWv®˜pð7æÊÅu[‚•ê N»zšMÓ³5a¸úõ™Rkv“Æ•b‡Õ¨Qw-*Úß]£X÷΄mæVõ¦°kÑiuÿêÂÊ%0­U¶4X¨à¶æ$im"€Ÿµ x%—ü§’Äæ. š TšH#*u{ëœ5å³£S•-’lkI&|Rld¾Kã|!Z¸„ÄNæfM­ÁšèçPM8èD1ka¢~ô &Þ©ó5ÉìÙ cÛÀz?uŽ™üAÄ\Eh4.· P6Œ§ùlqÔ‰þwñCšAÅo!«Ñ…ñáô8Ù)(/U Ï"K´= ¿¢÷1è˜-:a0² óLÏò:ÄæÌ*h³FI:Ívð>Œý¾lùìÙEͱb§!¾·%q¼~ Z“8L3%äVLœø4,^«_K>3Z MÃë=} …M¶¯Õí‹é¡÷DØ6M]®Í¸ gìêjöè^º~Ns_V]Bñj×.^-ÖmÈ~™Uä6>û _·)%\†3*õí"¸$•³ó9«¿Ê rúsêJ*Ðïö$39mNÝ®w¿ÒP]§ï©›£íá/ÀvžQÜ!½—c&,W]½O/YíI=†}å­Kùžöe¨ú•Ú6œ±¾¯V¤Gú$²ãMÃ+Ñù*ÇÆâªËÆëjénó÷ݯÍ»ïnnÓì–tæÍFÙبo6JÒXcY¶›TÙT1(Ž5ˇ?:ånl´ïVs56jÇþÊR.‹+gœbcÏ“Ì#Ô)'ÍRëJ]Ö§=ièö÷´95½;ýJ}yßÞÏCŸ;OØq TNBT”xו†¿Võö¬AÚ¶^ÅØhxÉ֯ԷŃõ=õ–é“Ú¾Ñ7^yŒÎW96§.¯ÓÓÓf÷Ó¯Ãá°Qøˆ>b£ß!½æÎX2h=)´Ôæ¿W3ëéhÇhÈRjßÐèê]ÞÄNÒvQE'#Š¹Œ£äcjô¢AaX{RbC}`T{‡ á+(yRØ¡,œ𪘡0C³nÍ0âJáù…ñcY^Š†‡:›¦Ç¡ (t çÝH7pCZ@’_$Ù)öqDEXMÑÌmð\ˆeé¢'‡îü9 ±éò×0ø ICvrðó ð„픥¼[ÄX”*7ëY®Y˜{ÐÜ—?2· Mæ6æß)ǵå7– ]%Ž ä·Js³F£ ~>•ØalçS² s›ÿ¯½¯iÙ­ÉÎr GÄ™8’gäÈœ®ï!$1ØŠAA!;øœ4i:øüAQIü Bö §MÏÚÁ‹´u]×ZUµïçuâ$“ðòžg¯ºkï]»j­Uk­Ztš…¾Í„G8Å° Ÿ££2‡ùh­äîQ²Õï5—.«%?wy8(AD–h®V5ˆèS‚fÙë<¤FªULžÃÖ@µ` ¶UŠw^¸È{5ÑnÆþžªH²º,Âå‰uXÙT"˜1˜ê ³«í–m⫾,Ë@G?ÒdrӜŸQ¦´U_ÌÙË>â¹ç7Zdl’ûIº¿ÈÀDï¿ucVÍÕ"÷Ô U¹àEî6n/Û c^hÏéqû(µ²U^>_å˜ c³JO 7Ëö´Kæ_t<íÒT‘ըʬK‹ãHä>"ò6†Ø^°›ËN‹ ˜(!É7š“¢ñÀâ'm¶òCe’ÞňIÇcaÈ·cˆâȲԢCÍJnŠ’^Á®ª™sÊ¢ÜE6ÖïV9qÃÝNN‹ÎFñ1Xîa–}èÇÝ*ƒØÈšÄä:¿¾ï $¹]r™·'B4·Ó!{kfÊ·‹bÙÊMÓHþ{wh0K>¹o3ûni<ìDäÑÍnàéO²:î²Yî6»G2Ž+ÎKƒ‹êoÛ|ŽfZ7tâ¹Û …ÕF‹Î9ýl°º}V‹qÎbîÅ™'%pÂàäYõ lK¶>2žü0*«5l¥ £Ìœ>Œ»ƒmÒ|êÇ` á´d•pÕë}¥ä Û·á¾×˜.<{Ç€Ty 4a¢fwRM†Õ°%§MòþýלîÚ§¡¿ÒøŒOuÓxÔ ÖEã»Åh\>‡ÆG}Òø†7ï£q«n¿i|Ä'#ÏïƒÆ£\»Æc‹5_4îµN`>€Fã£>i\î‡Æ7¼qh·k‡Æq¸ý qÉ8‡Æ Þ4.ï¦ñYž4>ۃƓî¼h<ñœót(åAãÞ4¾[DãÈ/~Ó8"ŸŸ4ŽHæ›Æ‘jû¦qä^¥ñ$sòEãI{ç¦ñ”ʃÆS*/4n Î7ã™'å ½h<¹ò÷4à›„g¥ñ™4>ã“Æ>4¾[²Ü4>û c­.Ç€.gxõƒÆSG˜ÁMã/sºi|Ø>žöTÛXÓöK&3Dy$/ƒ&¿—ý­†%Ý7ï$ÛÁÝÆ€lG¹ò¨ ·µ$YF®ÔÊ.`úznL¦ØÑ]RÆ,ˆÎot”f½x±¤¤C˜‹%í±$DÊ— lÉDŸ&¯i~e“và=˜Ý][ŽàñÚ4½®}Ú¤P;tS8¥óûtŠøÍÕa‚; (þ‡Î“m¼ÛÌ‹À]È­ÂÒÉ‚pLÕ$q.kÄ„Þ%ž²«ñÆ ¸Ò6°RÂÕÐÞx[2´(´€SNk(ÿ&¥”v`Æ,öJÆ(Ì3–ÇX·x7)îÏôÄm&ÛÊï`Á&fb²”m»1IÃ=ªY(àò`€£®Ú‹p#/:ËHLM>'ŽHoNÃÝ*£#ñ­ê8-w#`úwÛ Í…Wªžù™6¹Û8SÝß±ÙnVéõÓ£˜ª.[°k“ÃÜmr6íÝ¢¡2ϘNÕå3l6¡âîC9›}§[IÉÓǼW ßE>#¸Æän³¸oã ÁåÆd|‚¶óùް˧…D˜ƒ!—1ç`š˜ù¼*¥‘ÓàB0é̦§£ @0kÖùÍoÛÝ µ¢òÝÊÉ×ØFŸæÇV™%?c=åÓ,waÁŠpël{B«Ùv¼I¾9îe}d0ñ|v?FÀ­Uâ&AV É®ç`î6l-”2³¬·sr ¸_™>nm]ÎZrÑ’æ“««Ö£ÑDCý;»Ñ%…ÛÝ%ú„9¬ã^Š££ÒP+™y¤9×– ýY–àaê(Á»£?ò¿i8ÜW1ZB’cäàMCª˜°eÅÁ’›¸éI¶ÃL+E ¿v'¡å>Å«¹NO“Ý Ç™4"î¨6Ír‡Ê#I84¿rŸô,ïîN±WÎRxˆš@ŸˆÁ5YÛþ”“o7à‹NdiDäo…bóï.é¶-‚Ó|°8í|)Ë;˵Þ1o»Ÿ¹ÈÊâJ²Ët6®{u¢V±nÉ„ƒåcRÓ{cØÀ¹'?~ubmòÏŽ²Ò¦¶Ý™mkHä3r€ý%z[›ú,?$µHþ3+‰­cš²ñUùÿrr4©²íåBB•Ôl@µf6  ÊÝDœy£©™ |ÜÂÐÆï}Ú¨©=˜±ÍlÀæ`54 °ù£ ˜,ÑÉŸ Õ‘ëhH§pÀ¾~J™üA CLjƒ3nñÂiþ–idN,»; C ¢ìò6\Ó9 É€’iAi?Uº¦%˜ÌÈ`Îúí³m:r·^K  î6GV‚ÕøJ–» <’袯ï=žl%™]S#+t a[Æë· =©¦ LSúGb¹Ûx€ÅÆѽû!Õ^2S¥´r}éc*ŒÙF¯ÑV쌱TK^]šyÞ4?‹+ÕüH>¶ìÓÔ’ýòC˹+Í—'Ûñú_ì ^ß~·xu8—Z°ƒÎ’uHü--8–TI”šíÀôC˹˒._-ßþa„ûh¯˜#ï’a:æ퀬_À(@,Q¹È†"÷@²7ºrA$@ÖˆH‡Õ1)A?R©.év¿c0±þ—OWG‹ƒ îZa MMàBæ¢#¿Æ¹ÐàFU#‚ÕêD¢"ZXtá‡@Ì=Ï oÐ 7¸ƒ™©> ·Œ­g°s4ã|ažÚÛùæ¾ö`Á¦ðJwTÍíú*ÖñÀ5³í‡Åß;îÅÀz ¦aéÐ¥í–Å(³¶Œä×Á¥ 7\¼¾‰Ä¡Ý~ë Ëçz‰ ûè' €i|§ˆ-÷ðp–Ú4¼¨•çBUœB’\ÿ˜Ê0££¸2˜Û%¨eÇ)¦ØÙ1“¤äc¯Câ´­˜±ÄY,Újbñ1lýEÖ¯nÕÙ¶íUXÜLæ1ÛVöf¥ÝFÙ¿E“v0„œ„ OÞ„ ´q‹‹T§‚*S³lø€ è«C1ü÷ú£ µnðbjA_“(°r%!ZÚ0ß0Y}b÷@Öïvà êë(Þna¯‹;w¶ÂŠÖöÍfF¯®1µ YÅ3˜¥Ñˆåü6ܽ ·ÔH2mf RpFA¦Ž±Aô·$–»G‡ÜÝ •}MÜR­¼V>»ð |Ãiê¦MK¦Œ­.kEIÐ f;å-°Pá!ÅG5Ö\:à-(œ7ÈIê:ßô¾`žX{§`ÝÚ’ª±P¡Ú¹ßmwç É*9ïQLRµ ¥L¬Ç§MÃœ¬%ݳÔãšdªÊ[X_?w 'qUÌØ#Ø>¨¶«‡NHƒø«€î…u¢M¡u=*²ŽV!_B„°ZFèA’ÓXn·IhÃíÞÐÍT]i )0G3ú¢þ\×ù²@L\ïÛõ»Ÿí©¼jêa?®ˆ#4‰U¥ƒ˜2à¢]˜ýbº‰¹{¹zp ÁIít Ó$Åú‹f)›úb'ÙέQ{±ÚùêBJß‚Up˜H ¢Kì¹±æœÊbmÎð`³&Bç"Š˜O zò£ý{6q-&Æã{Óg«2‰cŸÝð¾†rp£!§'¨º@À{rÓõ­¡Iøïz£Ðºks…õ¿Žë÷idÓ1E‰R‡‘‘6\¶S’ÂuQõÐM¶náôfç,ÖƒÂÆP9Rsš‘Ü›ƒÓ±ˆ†.Q‰IàYÖ7šâ¦í™'¦Ö9r´íÍíl.jàÔŠN’³<¬S/7S„¹]ÉèàUu”áØ å_ÿ”C§YÊÖEÉ42^=.«Ú ò=PÍ\äÂíÊ&+xðnêâÝÃgL¬YG›®©*°ÊëŠ"æ'ØFË‹©R67 ÙµQˆî„åêGÁ¡}Yµ,‹aLû¬ Ÿ¥Hö0) ÖFq1!4àf–,I+§egª-ˆ]”žE‘_Á÷T5NT!= F¡j ì˸‚Qr» ƒ–íÂÔøåhþ’­aœéC:.ý+l:åÂÓÕªí«Ýi^8¡¼'}Žø°óýÂ\Éq‹íð£÷ ňTŸ§åýji”-ß?»N‹ÕZu¬h(ÂijTö YÂò}C<+ˆ¹¦pv•pÃ5‡fô‰Ÿû”¸ƒB€¶/©tÑ,*dZP2ŸÝ)cÔgqòâzlaÃÆ¥€õ ˜S‘A§R}̶ÕÔ¬¬Í`ŠÑj1ÑE>«{,‰b šôòî d¥N'¼³a²ŜǮiá8ÌüM[B„Š:±Îaëz™Šv™\%ÐœJvõî`& ”ª¬ùdé(&‰iΚ`ÜwŽ«ÇˆúhLÚcŠÙ¥VKs¥W™mØËQ"fl˜Uç‚yªâH¹È™§K.–Ñé´H9F´è橨…XÊ"Û©{®¢t0¡<éÆøm;i†˜Gl3¾(‚(=u)‚·"Ø,¼)‚ˆ+ØŠ`í(‚˜"ؤ‰¸"(ÐAÄ1ÞŠ ÂGŸŠ ¼üï±>Á oEp·Hk–ˆÊÕ¼–ú‹"Øry(‚ˆ¤ºÁ nEð´ +“8Š â잊`㱆)‚xß­ØÁÝ"E¡]—ž×xzrmXHß}+‚MV)‚¶"(ÐA~Ê¥"jñV›×=Š âJoE°¡”º+‚¸"(ÐÁ¦Ä>{'oÚÁÎVøÊ[l*+³ÁÖ‹"ˆ Ù£6¥Þ;÷÷ú¢¢`å­¶1"Øfý 6Yw¨6ó^pEÙ:oE°•þ¢6•Í<=`ûqEÐW[¶«ÞT$òVµfEy×…"dù=˜ÙN,ÿ€ÎòQCû—±üîæ|Š€Íò –/ÐX>ž3ëaùþ¦ÃòO ™õÁƒ/‰¬"rMØnÑ !iÿpOÜpúÙ%û¸'l<'l<'ìf[ˆâ,Y†A1îš/»¹ò5_PwÎü”/ßxÏ×°/»‡TXEÖ€=eϔȻ >]_#›XJŸ M0©Þ;шâgg«Úóa=|éx‚1áå³!1$VŒÚ¸1EÌ@}?¡™Eh¿8zé[½¤ýè›-ø+Ä-Ìì(¬PÔo…•È—Âjzý¥°™ÊígÖEÛ ëÐY¹+¬Æñ·ÂÊ“ÈKa¥å(¬8c¾VøD\ ëLD!*¬tÙ(¬ £¹VLž5»×¨õ‡Â:À߶ÂêàVX­ÁVÜ~+¬†9×'ƒ[aÝ3m ë4çÉ[a…ÍæRX­ëVXª—º?jïÿ8°½V¸-Ü +ho… ·Â:C|(¬, øPXOËVX£ŽÁ,0Ra™¬ˆ²?‹TÂÊ~ëÓoÛ‰Yd¢ö†´¹NT(CšõPHlùQª’O4x : ô”5 þ$<ˆˆð\ÈÆÄ,µ.a ÆQ^í¬o™À0Æ ‘£Ýé¦øJlRc—ØAò ¼rÝÁbo;KRQ»7lä $Íò® D2cœ,øØ¡²ñcðÈ b(‰þ‘§CPø°õéü»#³œ lÖʃî®üP ƒ⢪†&X.n ûpÔ R ·¼ïVXmj hv5ÀãÃPITpUeQ-Ã6ªQ®8)X XBa ßl2m#¾Ž7œ@8›%ÊísR‰i»GYèe²™®QF ²Jñ¶Å ‘(G¨¹Ë9Ì‘0¾êôÐ3—yÆ8ø±ÂrˆÈKô­pçyFHg “KMN…Ò‡oŽLÝÂÇ’GŦZo8gn*»[:¡F|ãÒ'Ü`å àl–Ÿ@hèLj÷àîÎee6—/u¨ á²AG À-sº "ÈÁ†–““ RÞ€ "æHÉc7gC¸9 åüçˆÁ&»@’.Q-A´Êÿگʇ‘3çôRµ9rf‰!pFNP«ÿnPšÔÉB–Õˆ7EˆñÈMjÿžèu4ïÎ"É9t`ð-í0è¬À Nˆ!²-M›ÂtÌ®%H÷n–!&Ovv•Åª1—'fÖ^¤D9_ö›«CÆz=ë XÞ±…•Q=86¾ˆ ˆR¼jL¡~V= õ/VzÂ7æ Ý@V{0®ìßsà×’ü{æINkÅ*oRbY¯šÖ‚H\#„J86Œîrx<=*­· ^›˜ç OŽ•õ“Õ‚ü&“ÏÄr£\¯›`r4ÌD°O¬‹ÚÞ¥q’„â…³]˜'˜ƒmÌèm>0cÉ|3Ì x0ƒ cS#\˜á/Ú˜a † ý.ÌPƃKl=˜à €fÌ~0c„tcÔfŒ0oÌX"ôÁŒ!Aé`Æ`škÇŒAõw¯ûÐxaÆÈá#×flxc†·8fŒÅp}å‡N®f@Ü¿0c„òÄ CÌ€|šµ§°¢:/°WÊ]‚[äöÅ*?â k*Çó#óæáΊr‡ƒ¨ôª¾Ü(ò5ÄœªÃ®ËI!,N]TÁ7RG„ʺ†Þ©l2IUÀw4 XS±ci7Ú!eèEˆ;?ÓÒÅbδ™Øâ¿C)×ÓY–\àú×Q —>UZNœQSN#ÇyÂÅÈ}v…›ùcšLÔŽCEp[ ,OÞx2ܱBüEÆC!Äõ1}øÇ ÎÂþvTì^ÕîFFôÜM­&6„´¦ÌËÌ?€É‡2QÂ’dòín [ʆ g$g.°õ½:´™ â¼…4…ôÔ{û$px ÁÃ[²&FÒH~@Âß³y‹5;Ï<—á†w¡ç¦: +fÓeÿH¼^²´ ú”KÃh§¹%`q‘ÞêOÄtGéIU ¢î–ÀMõš¨#8ùP³¦êÃ.²z²êÁ ‰â±o­ûK€‰ÌBbpõúÅ4=¡vª›6-IVâJ·k 3ÑžC/ ±Ÿ¥œ"Å ìÌ ±´Ø…#Á ¹4`XÃûi˜ñ³ÍŽÝr5dÊK¬ƒÑ)G'ø l'‘®m|Èô'­H “ÀcÂ:Ãö:Ëy!o/qÓäžÛUŒ[U‡³$Ì&®õ S«Óãú=ô\V%Ž®é&ÄÛ¾ÉgZÞ¸ÒÑ;YpËò­!¡öË%w&¸Õ8ß°÷{ohrg‚'Ô%wî9ÓóCø§Å'pXžÅ˜nzN=n¹SÀ–;n¹S É)ÉgÐäÊ÷£[îLƒ=ŠÌ„û · ÞÓˆ} 5`@;p›jÂC¨IS“)jµ .1°“ï#u«Ùp4[Ýia½n¼.oA3Áçi±3e9VîŸ! B‡#&º6M„íÀüŽIû%é¾Nk@0p4ÎÝ'ÐXeÁs¤23ëqé°n‰QîºFŠñª7ÅcgMpQ Ýåð„èÕ|ÄôÄèËr~®å6˜%TZÁ‚.Ä ¶`ëhÑú4žíû»íAûùŠØ¿Ï´9 !L£löÅJæYF5Ò…Â%”­¼¶ñÜ9–ÔßÖ“­´ŽñOrttÖ-ˆõØoRØ‚q©øÊ-ž,UAdË€¶æ ÑV u1t‡6CG”]«‡¡—(AßAà0t‚‡¡t†Îh½zº¿h3tk0^rò:,Å0[ÞÒþú¤y½*Ï[’%¸¥}ä‹Áñ-£@E”m­ñ&9Äú¥kC/k©jv™~’Ç–ù×&p˜»'å »Ø¿À-ð „$N]`t?B:Êß`+93¥ŸH¾ýºfjí3­ŸÍ¯Œ{¦Æs¦Æs¦Æ=S¨e˜9SÐóüÏ€ÂpC·»áfÏL¡ÞGÝS“à£CÞ)š³ì÷˜ù4ˆí¼>“EðLAÓZ*\FÎ\UðŠ«¬ÁfG?¹¿@«³ Øt+x^¥ o_KàLÁ£t!§²èo45’g}ȧÁ~÷õÂ);ŽÛPÈ¿+G ΃)r+ÆÌ þ˼n‡JômÚæ£Äí}›Év›R5Î…áEvÌG©âèj›˜oóQ‚Üe>JU¡&2%ámóÑ‚êe>˜·ù(±òÂe>bôße>JXÔ3+p¥»ÍG ¥LÚõ;âû·ùÈÁm>ò3ñîc>ZOOóQjª³ä¿ûìšù(5å¸ÌG‰…¡Ý|ÄY¹ÌG å,¶ùhÌÞÇ+¢i·ù(á„è2q*æ#¶óQ"O=æ#ÂóÑi9æ#œ¼ÙúbK@ÉÅC#²á˜äsEižÑ".•…e—òOXuŠH׉Y¼ÒrT准¼Ø° C}[˾‰†Îû±ú7€×7Ÿ–®SÍÚƳî‰^eš5ˆƒùЄ¨Ô¸H_¿­åÜ•¢ª:_-Þþq„ŠE]¼iA¿ƒ¨«&ß™_³°N"ô~ DWr$Å8ƒÕ®¶`·Âá“×Ðtå›daɲŒŠÐCÔì:Ö,‹Œ¦.šÈŠšŒ¦Ò—&ÀVÐ_ Æ쌅Œ:3Q•ÚS¶ëhÅ_á`#êÆÁPN„nœÌüŒŠ1`/ ¦ƒ„0 âC¬‡0¡ŸHýOÀPT‡(æ´B.]–˜ž\³Ô%‚Bà|7Ðå T”-ùl9°IÁÈp6%Ÿ†ÝÃlPL)EY—[Ï>­JSŽß)Ñ2¹Ú¹výžîä!Ùe÷èò«4O8Å÷G@sÕ1dâY"›Ðṋ”ZÅJ÷þRêb ƒ¸~ÏCéd‹p´õ‰©ò,GEä œ@1Mˆ.r¡´æ˜ó2áÖeÁzB½¢H?c˜æÀ±Wéà¡or2†4“ô®*ã?Žy€¸¨lš/¹…;ÃCn€åj^s\˜0óBƒKt.á-< áý´le›áòl"¨™Ùçù]“ ‹µ„SéL³C¶8¤ ›JeR…_l”o'?²ùlÞþ9g{¯°þß=”¾ )­*XƒvˆaË9¹M®¦HVÍtm¬0½À˜0Çn`CÞÊù@s•ãën€¿ŸN} xÉ’¡ïù'ÀqB3M˜KåMÆ μa‹Ã!êî¼¼Ÿm ˆ„W-WŒ¬¢Z,«$ãß–ˆƒ! à ~Q’¨ÚöïÓ§ä¨A-HtйR%¬C;$_‚í-t\Ñw7]Seø§ Ç‘(…»|¥B>±Š1UÕä'ùÆ/X[?fR@ŠvV#ÐåkÔ¨LB·hax³8È€Ë(£™ýƒø-ØMR&6ÉV-˜¹8ŠßŠ³šÎ8cJpwÑ ‚i¡—XËûny.*bY7Ý ¬¯ 1 {¦¶b-ÊdR 9¢i–e-jˆ:}r5¿o™Ïbƒ–«¡/{½³ƒéöïCgWpm€rôbtÍŽÁÚ›©ð1Y6•^êcSÁ„<7•ŽmæÚTß› àǦ²Φ‚(#ªÜQF ®­àÑ ŒD…»%lÿ¾¨wS„0‚öŒáèóy Kœ¶,‚.\\ûa‡¯ P+1Fuÿž›À¾Á¸Eœ@Åæx6´?Ù²)"Q.k>V fâ! Ÿ×ûè ߘ\ÔïÁ+ví‘tšÌ wØ,‡3ñnJn\vHæd˜ÅosòÄ<' º>æäi>2'Bõ:-Nî2'Û;.s²µ˜øÎ<Í3—h_ÃùF]c³§6 °h/ búô1[/¬®1ÛrƒÞAgUf~*p®Ò¨»Níç°Üèü¥²j™¬3PÖ;ò6Ï ð|I„zâ9,¼8f·À'FaK _&´éÈ‘›°õÝ‚O‡§ÌnXƒºÌßr2¾OHÜ„ž«<ÝoÄ5:Uù¹ó—2ŽY€áýÇtR# %bf$7D<ÖÉ <¼3]¡šGàz#ИlYñ‰Í¤Å›R>ŒƒéQÆ¢'¹r¶¢Á×OÕœ¡¾_ #…ph‘‰ia ^2Ý…®kVB£Z~Aȼ°¸*NG‘ÕwÆÇí7 0§ñ´dÐnxà Xðhn‘ȲŒÛIÿC¯JÙ®«¥½!„\à´†"ïDB•C8é߀i™ñ  q‹’nЪN“¼åý´ w½8ý¦«A&óÌ¡8!È®Ÿ]ûøªeâÔdÀTÊñŒêfóãõº‡N»Ó~Z¸É<Íèeæ‡ çofeàžÜØH¯Òd3²k$¹¾cFr<¨¡chÐp“‘øë'ìÊÈ(èý@ÉÎᣉ],3TQš×Qþ›¸†/7БЀM˜·e­c«tóœYS$àÛ=f7A°›ÂúT÷Õ’UpÓ °DØj×H\€ç šUí„X!÷4û¨È¬ðˆµ‚©ÏáuoQçéÑ4 –[f¡)ƒËÏCŽ“h¾Œ^ÉBص¦½ÑÈæàêŽ|Qø ï /Ì îr@#b-wC¢¬ÑÛ^j0Ìê˜"Ãï´DíYŠ[žÊXp æëÌctk…Á‰_?!¶F$Ùa,|ÿ4èZ£†ÅÊE_E°$x‡¿¬2ÙäéAâ種kÒ!îK|Q¢­µÈ°?'½ Ä© … ¯†ÊVÆnéCF²<•íÀ8¼!vx öÖµå#%Dã·CBÁa³"H^ホ8°ÆZI†ÍÑŸ°a䇡¨xµ°úbÀZ0´Yø0P~ K@œtæ¢Tç s14îsƒiOj¥g¾Ÿ“e`MRìܽ^7$ùßíÈþC,VéÊk¸ëoÁ'3›4^ÂYÂáÙÛRhòPU¤}€š”®THÌHŒ:ßúÚÞ2ŠðBKãu­:ì¤r¨†Œâ¬¿»|ÓŒ™ÍÆ3Ô!É™pÁØø%¶K á7äMÈ6ì±ÑVƒlÄžPƒoSþŠªªÞ¡Éÿ|éóZJìÌ1n&  P°Ÿˆ­˜/·¤ÊÓ¹‘T‚CZd¨–šƒú¤F„³]e4€®[TªOA`þ™«L”B¦„Á5Ôâä0è=Ë>B» 9Ç? ³|8ˆpàÆòÇ ¢Ä5ºv–OÈY¾Í“çùû%›éŸ²ù©Õ>—ÎímEÖäSsZ4Ã6§WpOQ¯¸‘é•ÊåúAÈe(»åýjÉYG箫¥H烫8¼xáÕ«QryŠjÅÌ ¢KïQ™#.þGªƒ”Ö·4ˆ;¨n‹Nrº å ‚s•ó†/<ô‰?W¥Ыê¿8i4‹(Šô„˜á¤¾$êQŒ/5•e(0KÚ-˜Ú-j0K8?ÄlZ¿)zkó‰êmúLÁßožI \3bÈŤòW塨‘"1·4—E ¿ ç!ràŽ¤‚›Û!ö_7 ü²å— (}Ø€ÒË”^6 ôaJ/PzÙ€ÒsÊÏ (¿l@ù¹åP~Ù€ÒË”>l@éeJÏ (}Ø€ÒsJ/Pú°å— (¿l@ù[6 tm@éeJ/Pú°¥— (½l@éÔ_6 ü²åPþ– þGyë9Qö*9vÝ8å«r·(\fMgÌòÅñþ®YÊÙ”ëf|ù´)ç’Ÿ×Pl™XØ@ çÑj$n>“[»ùŒ äñê1Tá †Ì ¨8ÌÐehgš-!^‰M£‰2ŸÁäѤ>³ÏMIþÖ¼õQõˆon›1 Yrp›MûVŸô÷B ¤™Q7d¦»ë6fµÄ*¿0õ#A¨}w”-cj4¤E®Èqé^xµ yuÒæ.Q*3úfš‹R¦uJC%"¢æ®A ‹š·Hc(chÜ/ ú£zÒQFcQ˜˜«v®V}ùjA¾Þf™Ï*¿àᛥå ²žð›“öRƒ”>”ËÀzQÀÖJ¸L{õi±9–»§# qõonGå¬OÉû{w‹&d¯+ÁïaÀÅvs¦ø©5Ð2T”¢/`n{þþî•Ÿßþ€¡9ÕT£ÚyJ¤ "µÐÁG(™Ä‘Q#fÍ[Z—¬Åëgâ¥Î*3A*‚˺á×>Á‚/7'_‹Ì€ÐmkßÅØüܪ«¼Úû§åä\yVgq;>¯Èx€"3€‚¸¬š6ìQáÎRª¬¶p_5äP3À…’-eÿoø nFY•é¬¥È†^V¶ªæ©” ¨ƒ¿|ÒŽuZÞ?-‚Ü“™\ñ(Í,˜[þ~ ÄWî;§e°~5LÊ”œ_@ª{™éߪnçf›Þ)Œ€«I°&’æ¡|$:¢X?—ÎêÂbr’`ô€Å9“E‰ ~ÿtîºZX»›Â ·SnÒ‘ªR€²„ª£R#SÔ,`0çk¦Á„Îü²ÑP•¦uû é[qÍ”©”°©¡.«ÊÂ"¡˜ŒÂÆvLdp¦ÒБO&Âg˜ÐFkñý ª}”È ‚‡­?Sn¼ÀläÂì/•vΈŠë´Yh.` ¸î$„…¥x>,F$*åm¿)Zhü<-š©Ìß@õGK–0”<~Ýß´–Ží7†0Ç8¥¾ò Q¦Ð6¢®Ʊ!¬äip \Ll:E-04Š x(ŪurðÀ1È_¬ÐU‚]‘cJº}Â9ϦÆGOßSØ’aÁ†ôˆøÐ.¸VÃÃÝG@¬öèÒ9JÒ/“*m(:&ÌUÈQº)‘7X¨sˆÚ¡†ûP"™¹˜‰õ€h+sü¿0xmi>r•2?:3üã´eÄëeÚž¶_¡ã§G+²Á°ÄP »–3@U”%?†ôO_ͺä fÇÁ ÁQ¡øNgÚØ°}V+W0ŒáFb°Šµ!®8,«°F‚o>…H"³´ÚÆP‹Ú¾p Û8Í­WÛkÙ’*srÀ·m[d³ÂÇô²·ÏÞvÃPÐpj/×¾ ì0Ùv’ûÍ‚ûy Œ@áÄj“Vè (12¹ß5P"±ifÚĈŽ²iñØÚ‡ŠŠfš£þ¢z«õêPlo©Ó¹fëšc|7þ’ûóÛàųTà3M»ÅæF‘CÀ3[t5ÔÞ‰¯îùš¬žïÉ"t&K M–â[8Y¥©¢ê4‰ Y×$iËfkhcØ“¢ ó1[ Èrz¤4]y8`Ẽöé"CݨŠàõš.¦»gˆ•ë„Ê+¤ØŒ7”*šò5 ¦Mãš'A5é˜Õ@‰I /ùlSˆ(ýÚ¦ÎDX_±¬“l”¥¯y4LèŶïÌ¢Äãs¹Ph®»_‘M÷‰UJcV¶›MþíY çY`+îûŸ•«Šû3bS!¬ûæ­@Ûf{½{ÿ#7ß=Ï„hó„ÿ?*s&>±ËÌÍBž²HíYxŠV –^f‹ÖT‚Q¹½ ¾«JdMZ –¾D˜>Ì¢0cÖæ§u nz<æñ ]öq_®Ñd6Üs‰«óšmdR¤a· MÌјÆn tÚÅý5Ÿ½#)kÁµ»`zûiÙÓŽÉTéË¢o' qÁKVprÃoöM®‚{ƒßß´E ø¼{Ìj>ŠøT雨~OÆð«!·®‡µ&µ8-;à÷ÞÖ­aý÷3(—iS•~ýô ßýôïþã·ùƒßÿ­OßùõÕíÓwþÁÛ\ÿþ¯üâ[üô_úø)ü“Oßùåïüâ/þòågö;ÿèígÖ/¿øý÷ßÿú»ÿbÝòs?÷黿ôöwÿÓ?üÎ7?úñ7?þÂÿÿ÷¿ÿoÿã‡í‡ó?|óõGß|ÿÏÿèÏ÷GüGÿê›þð‡?þþ÷ÿøÿä'ßàê›þø'?ý¯?üéúÍÿùÁüôþø'ÿå_ÿóÿü“÷ßÿéŸýæþ¯üçÏ~ôý?ýÓ?ýæ¯ÿ¯¿ù‡ÿöoýí¿÷o~ýçÿê_ùùOÿ»o¿z[À`ÌÌÎí?NYÁ2l§²4³2 leVZ-ÐÜi#HÑlV¥šÕ`º};>mÝ, ™ Š–„d-Ñޅĺ+˜\œšß©Þ}Xñ¸ÞÏa1ÁÇ»R·œ={<‰æ‚{ÌL2UïïJÝÞµ¿=!rlžù9}¦/Ïs&eÕq½‹9¬ïáÀ`m]lÈÌ®ô;öY}{°ú(ž´Ç§ÝåSxõ±i¾žcKqÞåËuÆãKº‡ì«~¾Ê1ã|¹Ù s-†D}#Q´…‰‚!Qw$9rA†#QöůŽDIF©˜òF¢¬'ç°‘ÈÞ…*à†Dn°KŽ8¨­wŸ4„<ç9‰žƒ÷»b‹ú=ž„xŠÇ˜*àÔû»R³wíoOf öù¹ú:@_Ï áH¤wY¾§3xµ:iÈP‘ ‰ì³FõÅ÷Ov9iz„cH¤)¼úØ4ŸçøRœwùrñø’î!ûªŸ¯Ú˜±¿Ü2sý%ý%ýÿ#Ñ+ö[É zZ²wBÝû˜­ ¶kwŸ}#˜%`+þrdŸÆøPïÝZ´9€¥Û—ǨiOv$³§«YC‚GâÝ#ñ û~H¢wÐý¢Ô… g0 µgæ5ÞÔ µ÷'%$õz|6“ø=QÉûÄ`jû9Q«q^µ02ï»ì@â|„†SN"ÕпûsìˉXººMjÐôb½æïêcs|žãëpÞåkuÆãËyƼ—|×F‹ýíß‚:ÐK©ñ–•pPè“Æz¥_5 h¡!‚Ê,¿·ðµ«Øy¦×S V¤$/qôI|£—×kMmcf>Ù%áó£§Ò+áÀÕÄý«%ë½°DÆŽ„/„:Uþ–-PœÑ2†¿“CƒÂÝ=ξvÐ×.Zš5q$ÌؼD÷ú“Y9ë«Å^Âa9ÅS¡£A)üwDR§»²üåЫQÿ‚™^ĴՆLJrZp8EP«Ë¬²ëô–ZRä´œ›¬ ‰ñ5ÏMŽ¨$z1ÚÉ@8ZDìª_çK}À¨ñ[ÂPôÖx²“v á‹Ò2Ææ-‚€&>¯Eƒ‡0¨yBWx  DOLÃV³3 ݼƒÖ#z{‹2É¢: <›A¼,9øö¤â“Õñ“¥.Yd“Ø%x½U][¹{ LŽ$K¢o`Ó£•a`½\(†KÂP/Ù&j¹ÓÕ¥/qe‘e‹j–À•Ø’P!F•¨ÎB­XõŽÌœêã%fõ&EdåLÝÊ @y‚)‚§tŒU3CÕÌæ£m%½G’w vÀfƒÁàA—¢©™ƒ¥*»:—À ô)A³¬LÉæÏeצ固ÕoeöJñî¡Ø"b©O4¬ÐSÆ|"é5Mpò…C¯P‡zAŸÝÇxM|Õ—uÑ$Túlã„Hw¤¢1W¦6beëaxÅÙ‹>â¹ç7Z`lN%ìµìªú³9ˆg«¯º†an¬H:e^ÙÜsø˜âîczÌÀ•Chj¬n‰Y›v_¤ý(M:¥"”d]«yľ)>¶[‚Ð]ž˜bœáf!/¢ãû 'YŸ®– aøY´ê‹3Ò¿ùmå½ßňIˆRA\Ò¬(Žì€ 3>;$3u¦ÿŒYSTÙß‘„QIœÜå|µLaÜ«i°Z¹“‡#§-Ú)qºF §9¿ÞwpÒW¢0J|IþùÓvObó…bçÔü9Mgž î† ú㘩âÀ³ÊË|·DfèʨMt±›õ¼&²r†”q¼BÔóA7êoÁ–d6qÕïáú;:º~Å8£6Ñ@Ï8jáÏ·| EsAÃE7¢à§`!ðe ƒZ`9V[bûÐÖ€QÞ”l3'Gƒ¿ÆÝÁv¤ÒD¯»àÕ‚2ÇÓ_ï+%y1 †ûsê Ç ˆ:r7Ôy"@Šæ9vLbKŠ;Éû÷_sºi\.§‡Æ³ 9Nã9´ê4žƒ²æ?-¤ñäà4Ž›o¿`£ñ«E±ó8+¼h4~@Ò8‡vÑ8?î¢ñ Þ8´[¦&½•›Æ3èê¦ñ t¼hüÀ¢ñLƒ›Æ30ä¢ñ ñ¢Ý$< Ço©ÇƒÆgz¥ñÑ/é¦ñŒóÔÆÝ!Þ4~`§ñ«%ãçtÓ8Ÿÿ q®ÕMã#=h|”WãIã3?iü9§Nã±ivÚT7m¬ÕDD±™Ì B²º©K¾œüZö·–Øn¹;$Év1 K?q°|V?úwÖ¯œõÑÒлuc2dIDVŠ¹kZ”ÚfIP’$D;KÚ-bIVúmƒ%™èƒ—KmQå­.xf·@×ÎÐ{|c¤H¡ø6䤀ÓæòvtÓ ­ß'§#Ào®P¦¡§Yšûçtè<úV,Ø`^œÇœBn¹üá$"˜¦e‰vrl&ƒUóªÍ°Š¹*m&ÍHþÉÛ’é ¸­I0È5œÂDû½»µm`AM3î;cyŒÕ‘ɳIÚÄeœr*OÖsRLÙFÌT³sqŽýè‘ÍB_9u Ô^„gî‚HR‰Ò‘Z·åO¥Eé®47rKXÌ럜€Á( €ï‰ßŒA/+,¶™ªÇa»°L¥‹1§$U=²@"`×&™ wÄaÈŸôÄ5½)7³ 쯈ÅôOwô>x öë¨D¾6·—ákø¬õõÄÀ‘"Æ4‚dà:Ÿ í¦è vá´ˆ‡ ÊX'lš˜Q‘ò5; f$}7ä€{5µ5êÙ"Ø"ãpðB¦àëÉèÈdBäÞ*“ÉÏSû=­~Æ}E¸u†=¡Ùl;Þ#g±áž…àŠàúî—”k•x£I³IG]/3íH®ïl-ò,eeZà6²](Ó] Û¶.c-)™mcSmÊ®JXyBÿÎÉ.-øvÊ…;œ0A[™ÇôBš@£™É"ô2Ê…þpˆéþÃX—£?sd]´¯¢+¡.Q¸PÈ´*&œ†±lé¾èÌ‘`ø S›"ù¶¯“Oy3 §Ï›â¿@´dv:ÈnÂãÔΤqS«6ÍCëѵâÉ |ÒÉŒ2òž#GVO@µmJ OD›Ú﬇Yê|Ñ9,‰¿åD±™8²Ù¶ ,ɸ8í|)Κ¢±\õƯÛý´g'³¸‚ì°¡åžE^3›œ_kÏÃ`ù˜Ö„ä3l€oµí_X™b›ƒ0Ðæ{ÚÖ A>Ó —K ™¦>Ó1ÃY'ÙOÙr4fΨÅH2êÁ5j rRiÛË™„:´í d†®©&ç¬@YqæÑøçbSHP„ÝFMíÁØì†é¡Ùδ¡åªE üÑL¸ïèg¡:²Ù…bÛ€}=®÷™³) Ðyè¡Ô6 §ùeoVtµëäJš4éæ$#‘‹ta« š=Uº{˜ÌTÈ@9†~IÚd 7‘s§·€}PÆc¨ÁQ;–-²q­)% *;([Êï.æpdvMx¬Ði/„mžê"8æ*‹·Ó”>јy²‰"áÂѳûÁ6­Žåà^ûÒÇTx v³Ø»œåkÒ³Bß0UƒGTMqüÞP@$YÞ—ÚÇ Q°L¿zÐJ ïŽdÙƒŠî…he»%*|lÃÙŽ§ EëåÌb–È É§b …'µ¬2¤c2µvŽw ÕƒÌn´hLYáwt'¶ð½jñkò…a@†˜è×a|³Â˜v¦ ö©¨=WF³.k·/¨ÙÚÔ¶¾ ê¤›¥Uõ (‚çäì'}5°wŠ~òˆ½²4íQCqx—OT—3o®v€Ú4¹V‹ú“STÌ' Kª§Te­ˆ-øÑ£b"WKóóçfG˜Å½X¤/›Z‡ù(ÜÙûÝŠ´ø;TŒ¥žñûЩ)´$Í*Zô”T¬—îF9WaQBZ6¹˜Âb#}WR+I¸ŠŽg±ÈÌ\¤r|ÊÌ1t›!z—ÏDb€®ÍÐH6 áólÈž/BçúÈ*Œûz÷èHLF¦QþqÛçœE‹‹¾“å‚ü*¨°t¤.›ÎlàeÈàÐ*–ŠùG‘âRö~À@·Š®¢¼ÀÎ9kV]‡¤X ½føµ,,É‹Šz~&L(©î´MÔlrƒßo`ºuZÜ-Œ£äÕe꘩JJ{ÿ+…ì¿C–[Ò÷€|:ª}®­5N½QlÚ%7dXE1•ÓÎÆô‘(Bø¹hªx²cM{&/Py/?³ÌÊGñ:Ø/ƒ­JC%/•NåßQȲ„ÑR¦Òs/î•“|B-ørÊf–Mdì@RéKBï”ì¼b(3h‚çÏ­3®5Ó¼®U©u í/ï5j˜HX«SÈ`ï(µiô§ArwU…ð`SND «âª+½i¿J×^F=+Á ¦¤£ $!ŒÜñd$Ã.YúÃBSGi`¬ÉÍ?$¯¡$ž+Ù•ÿŒó.Þ9íÚŸ)(+ÕAd™RÆË(·;wWuãZ(þ½Zpï…¹Df»!YýåªzÅEµ4S¥Xˆb2ên'À%%ïÎßu"H¨³Öœÿ:$• ŠK|ÓÕN¦ÜdáR%᱘Ï>@uXkºÐ‡ù¹u]¢éo„’´=‹ŠgE\¦Éä:”i%= 3•’x$^XÚU,E×4“Òñ~ó"Å™;n`R+.\]}ë¯Ô£%£#Ø¥1öÆÙ)Óå27ônPif¾¬íM§E¡&2‹>#Ê {9ËȨf«~nB"8Ã÷”õ4ˆ4´bÙM’ðà·Ú2Ì’Uª&o-¥\é ë1„µ„ªNe ÷Iô‰Šh¡‘’¥“¯ç²>pQ*TÈFÝš}]›©!„µ•³ 9RAðÌfÄ—•VK‰Ø²•šâv»£ÃÔd$U+?¤$ֱͪ›´ôFXFo(Ðò¤·ÓbäU­æíi@ÊEo(:sè i3ôV)óîTF¾è­î2ÀNo5Ö½anzCÒ‹½Aºé­ðq¢7];½ ½„‚z+Ò½ÕØôVSÝô¦k£7¢·ÛMo•a‘7½a÷ºé f7½Ù"½-~Ñ› §°Õù½PÌ¡7lz+J@³®z[¢Ò ½•Ñnz«< =Ô´—iÓJ3ÝôVkÚô¦k§7BFoX¬›Þ*Ü*ôV`+¼è­Œ¾éM×No‚Ho…±c‡š*ŽBô†Œ77½UžzƒÛí“Þ€Ù7½Uª*¢7ˆøßBoÈSnBs„™ú¸…ts!D×.„ÚBˆ I ÐKñwl!ä4PËñB.Єîê—±Wéú!uŽ§Re31¸öîBˆ.]`$!·\BkZßB+Sl!d‰ú[ѵ?S„Ö1ßBÈË(}‘¦r€ÚBµ¢}¶RhK…:"ZkT¬CMx­T³K_(B{¡É3†•HâÜÂó~Ç^ª«‹ƒ-œ‹ ­Uá¬Óì[áѵ¯!#w‡h1díŸ@4£Õ¿[¹º[ÁôW±ZŠ—ð&ƒ©:nïé\a|’Ÿý(Ri02ëºØÁ!!à»A:Œ'â'•;?âoÄ|’®ÎÊèÎÓ^@Ÿ$©4§.ýo¢mQ×>I„XÙŒyí 5ú v¬V{çA&Ûºloê¦~{‡%KNéu*½1­ŽËn¤tvœ>˜`Èß1£M¼À¾Ar=>·da§j¤fl=?É2_ã:wëI(qº”J²(D}¿Í—uR†„ÚÓh óÈ 6™d½Y |ý:w³òY9Å«ír©B>v18S\ 8Œ¶;ƒÂ’!7:Êv$Ç`&eó[fŠv¾SåoÈP¡/ìëhó.HvE¤»G*ú´dÊ7e}3àË'æ)ÆÜœð½…~к]#w5z%㛋RÐÐ)iÎ7¤¤”Ñ”€¿º6&ô.[X=³‰aS]^ð79-ƒˆ°žʤÝþöT®€¤ë ãê‘ÔŽ¯Ÿ–BÙµiAgˆ”7tÍÀN]–­£äÐ.¸æ€™ù‡!2S¶ÃG\K;ÏP…1B3`°™QíºNQ,AP _Â(õH*ß².0¶9°=ñ¦|Óu2£µA °^ó–%’"ïz¶Á–lùåQh8‰¹Ü³K«l¡âB´ëM9„sV¹ë‘„0oŠ – aÐQ?%»yíl[„(š[-h0/Ãõ¿j‚,‚ßåxRXÞ Æ­Í"V;¼åóA~KÌc;Wˆ #È ¦£ºqé»_˜aŽÄßjÁ3±è:Û‰8!Õ–…ÐŒÚ/à*Ô ›Q* ²> ô M°–¬zrV}’\½ƒ­O¤Þ\ˆaèÂòº7Ù·¿?X¤!ØçÞxꎎ–ï ZŠL³THýɸIH Îò³'ô~ ìº3T-̧T¼ײ?ð:Zq'BQQ%ï%a`b† v¼ù;b –RË8Àâ[×+¨î°²¨&Hb –8߯Òun.üAu%&⸘§3Úªtê¾\úîðrXÚ^A:§Â-þR£~²×®™ú"?xÿJïœvíÏ4»ìˆ•È§a¼ŒÒ5â`J m‡­•:`ÞjW1'úQ'ÃJ5»ô…"´JüŠÛ\°PPÜü{©N §²”Õ·€¾VŽÜ¶N5Jd¿öu"„\Èþ ¢¢ åhDÌ}¬R–†°ž+¦«^O‚w žLÏ` l"MWl€v E‰Ÿ½,¼þtÌ— ðÝ :ç3’{tM*x&é´hV¦™î_Á=I¢šêà“xj®ë=Iü¨`y¡eòeê•™4ÜôUÆ ƈä…ìr2Hæ<Ô8˜–Ò%üõ¢²tÀ8«²º¡¤mN‹<¿Ñ2%ŽápGúÅlÞBŽŽzpoNªãìp2iéjiÒü ‰Ì¸M§ÁhARÔa"½rL¡ßµ"³/x6÷›fÖc0uŒ„_2ƒª½âZ¾CÐðæE4‚ȉùØú+66쮾 Æ #C«¦F+bÈ“®®5ÿä6Me‚Ôܸ¹’ÝcÚƒ(»›–fšÇ3(4† 2B8:]p“”rµh4>ñÀoŽäî½?Õøm(ÎÉýðd†Â^L•Øy^«ßXš¸ï[äb¬k¢5•šfw¤Òòª³¾ƒ¸BJÃg:ÞýJQO¥k…™3 „ßî 4Md¹[èÒ[àÁÌŒ”ˆ È,> ,ös×pY{Óî‘©N—¨2_ªŽ7~±Äuä;ɼa{DÍN †ÄÐô8‚¬Çžïß r¿À •õØ ´f U T6+ØØ`—% @3ÀþS£å*ƒã„ Œµ¥kÏKJcDãrdiŸ*U†&4ÓvSmÞÄKT曆] G ÎY’˜%t%Wx ž6Ì¢æîPTõˆù—Ø_ $w«&a¦óF/jmÃz^Ìémʧ¨À$‘™@ÎñJeJkx÷&1$ù=úf#‹!Ú䂈QbYšU“ È1uex³ß=9dÕ! lŸEOÓˆ†•Ñ(‰¸¼T„|è8?3‚¸ávÆPº'ÝϺ2Õ& ##çèHþ¯¬¸-q¿Šéu†x¯ÅmÅCâR»1©(Aã£Ö“;k’XÅЂ2“eƒ¬Œ-_öÝÙWu—ÝÒÅÜC–áéx>!ŠÓE,9í×çž1µTïVúj³n9SÊqtÎ.òAmËÙ¯õÎ ;(€£ÆPbz~ª6çn´£uupë­ ¥F}(QÀþ Aï¶$_ج«×­Ú^ìMªáª# Ý‚Ó3h£|¬hiÎúe".Cez©ÃÐ+ 2b•r|w0S*ƒ•ÒðÚb†|ûÆ!Vðãdõ˜«yVŒãº5©LRËŽÉRzoLŠÊ2Å2o9ŒþÉÞç=2ÅafÅ|o¸;gÜ-•¢Í$1Vˆ(iò g…-2Êîˆ[]ÛTåT>³p¹nmô.iù+Êdq5!¦(iBäSJö½ ›á\™¬+5˜e›€RǪ/A ©±Y|Äcýíq8Þ‚«m»üŽja©dTXÃ;XÞUªÈÿ/8Á³%§Í§kˆÚ:p¶¤a@WôSîš¼œ­Éi©iÏ¡¯LEdïµk׶;‹‰5;  Vž³–MxâLn‡1Ìù€Uf\µŒÕRí;Éíuäæ^<¶dP‚DÙl ¡"T‰é¤•á¢BRy$•¿FÀ‹Š‘Y É’…óùþÄC,w :Ë» Ù0B…¯a겫7߀ô/rÒ¯–•„ ¬,PoDQ#A™Ÿ; o…fÇ;‹¥l¬4ºaèçÅqß«¢’ýê§ 6>$y†³¬h˜RÚÎQe-yxÎ3Kð·Äí¹pM¹^È ª‚ù ‡*oÖ8T^«VQ|E•|ú„íŠVè1Yt†-µ;øCó’Æ5Âu˜É 6„øL8ùj¢«öÙ*«X RÏbxët~­8ýŒØƒ·4d‹ ~*²HE²ÕœuhÅV3ÓÚN•Š¦çø|SÉC…) /£˜jvo³3YKß` œl ©èᨤËk0ÔÈŽÖN­CRª$òJ~¹¼–ï+ç->³à¦U?ŠÐ¼ï;¾‡äIB²Ódx݇“#¤:®õñ!2a§À[pbA!ø˜eíƒ=¾£7eúDKPaàh³.v ™Ü…J识ÃKK’C­”™êž·4Yº™~š^ôWC´šK¢ˆÈ$m\*8-âuŒãKª2Š¦ˆ6÷ó¦•&ÐyKlbY‘—¾Æ<6ºqÇ\ùàHf0+t¬ ÇaĸjY0á;{Å1± ªMWÅ tr?lÉKD¥õë:`>(….¨q꙳ßEˆ3åqæ°Üq±~»»-ÆÌƨGYeu¢a;ôNÊyS¸7„$Èx{”?pÉS²öEîÈÆÔÉþzèŒú<ôâ.^ ¡V>¹k¢Ey1c6©h±-•Ÿñ†’áIö¹FÖN‘¼Þ„|ÓLB)!«ƒQ¦z™BÊbÆóLT(’h³Ï(UihË-n”À´%ÖF¶ l ±"¶8 „×é “Q¸ê¼¡tÇSØ2H€"ÝÂúâhpÔu¦‡)?²°¡6•h”ªþ¼®|ÿR±4šÙOKÜšøèÄJÌû³GˆµÙ윪Àȇ½¯|ÿ8Ò„šŒ°:h50‚x@ª6üoAžNœÑ= ž” Ç ”Úè†ç¼玃Šê‚Xv:fÂ…o½#v(4a_SM%ÃòL v40A\cKÅçÑôñÃö´žXÚ|–«ÅXs¢¨bðpuÎƘuÞVYÛK3ÍëlDM‰EœÑB¯ç3Ö‡ ñ{ M±ó˜P ëG Û€u…s§üèà ×Íó\sO7¾ZœCÔñ\»ÍqÌZྒྷè%3y²Úh a îjuìâÐ8¦!KîÎÃ+müñô@œ7îÆsq}ž /Û»pWkg0/Ãu_LD›AôÒjM9{Ør9´× í$:iÉë.*š§©\•­ ³^€ZÿnÜ`ÖzuñI˵`ÞB7Y;›{ÅÈqmµ`©f6óÑt½W ±¨wè™ÛpÀ´ý¢‘b{m ˜ÐVx²‹ŽãÜ®p{Q”X#êÆÃZSêÿ±³Ô×gÄ»ó:ùç|lï‚|Ô­[1Gq)‚¿Ÿ¹Ù-rK|{nzè[3YZÚ[5y¿KS±¹D•þ AHOV9{úÎŽC]qOßú[U‰;ï€]¦K®&‡qÔ²sKø¡u`è'+òŽ,OwB+Â$ÁZ’,=4¼DŠþv©Ú}p…|ã‘ön\Ó•‹eDäÎö.ÈkáèXóù”nÎùçÓz‘cÕî‘M܃á²¹Ã9¦ì–$Ò ¯*>Qc/–ªUàêÏuº:XÆX¿Ý@ îXý½A2u— Šê Rræï{oGˆv¡ôô†7±«ŒÑ”{›†ÂüJ‡é³3÷¢óê=ŠM…õÀF£¶–r©Ÿ²qÅ4å±âý89ç[ƒü*»é`Ó(L©zL“ïúÚ#á ×ò2à,ˆ)~F#~‹ì2Oã›·PD›ûŠñ:ßx¦‚˜‡#)D"S‹R)$fü/ç‰ð‚åö¼ß0’K ÖƒöHQâ°€;ßW@ë•Ø¾¿®É•ËS¬„ú59 &Bwêݶçì:-¾³¶{´¸ù.¯§s@s?'H')vEê›f#釨4¶¨4¢Òø *KT/¢Òø *‡¨4¶¨4¢Ò¸D¥ÑXHÇ¡ñ*)ÍIi>%¥yIJóURš/’Ò|‘”æCR/’Ò¸$¥ñ”Æ–”æGIibÂÌ =Iɽó"wé-)M(ò&)ñz３~ð¾órLÓ3â–”ì%gsñŽuÄ#)m`ï-<û$%|Ç~®/I ”OIin«”Z&ÂLRÂõ‘h™¤„»P4ÑÄ º<¥)’==zÚ‚¯ÏcáXk‚mÛGPz­çš Õòh¾_?1M:ªñdå+°']oóyFÔ~§ü5e³<÷âÌßS®Ÿ—RvîÀRäÛ³eA,ÒÞëpi´³jçÜøž°zóÂDž®Güt‹ K~ Ñ­œo Q¹œÏP4Ùé‘úÏÖ™ëÕŸ,¾ }YʯÛnTÚÏ¢¢¹n`·’*ÇÄ/3D Ñœ9ÎG<¿Ò×lÝHlÌ«œÚ6´ÉÅkÚ–s#ü«]аéà!8‚.ëò1˜(“uýE‡äv‹ÂêÛ½ÿ6Í­–° n}Oßr£€Mr·¼k%šBBÂ#ñ®GâÐè¼1Zær“xÁÛ8›&Ô.x\"oŒ–‚~ÿLK­„^.õ:b¯À=~Uÿq6·{ïy²N 3l¼gžÄ·' ¦I¾®y¸e_A~±y09“’³Ýb„Câ%üF”cC}H~7º=…_ ¨2E´ú*8£|9:é:ˆ€A [íÈÅ[Þw “Sñ,¥ïjRÖpœìN+ë^òKg›D+Píe0Ð/Z!d‡$¬hö¸3Öjõ+Æ96ùÕOÿ׿)Ýendstream endobj 6 0 obj 49015 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:58-07:00 2013-08-20T08:41:58-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000049319 00000 n 0000050889 00000 n 0000049260 00000 n 0000049121 00000 n 0000000015 00000 n 0000049100 00000 n 0000049383 00000 n 0000049424 00000 n 0000049453 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<058719BA77BAE4505E955268EFF57EE0><058719BA77BAE4505E955268EFF57EE0>] >> startxref 51059 %%EOF ast-8.3.0/sun210_figures/fsconvert.pdf0000664000175000017500000004440513004147321014516 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}Ë«·KvV¢²E2Gö9fŸº_ 4!£fÂ&I·î/M:ÆBtäÀþNÅKÒBþ!Ï œ6‰mà¨ízžgÕå·¿AdÒçð±ßU¿÷Rµjպת_x/ñ9àÿûúáé“¿ÑŸîŸÂKm¥ÔüüsO%§üÒës¬£¾äúüá´ôhOÖç’Rz™ƒío s }Á¯OiXC»åí)¶l/K»¥¥—ZÃØïÜ°õõiµ¤\ùäÛn‰öH­ñy½s¢së“^ŸVŸ¾=­.Üãñ÷,x}éõég¿ï)©´•ˆ>œ–ÞØÍëÄß8Z*r±wnØP‘íÃeîCEXÈQËÀ¨úØïÜ°õõiµ¤Ù5œóHÑ«ü•½,œé£ >Ô±Õb(ñ®¯–34½sÁþQ"e<ÿ²!æGíßßy Ïå»z@ÐWž~â^H1G-“Ø|!í–Ô+ 0% æÖt§­WE$¹ZÞžrÎ÷#©$­å†ý£†ßÕRGËÛn™± þÊ‘ø†õI_ŸV¯¼ÁæÇ»í kTëu{”þÁ½œb*™´àÏ8-9 RE¬¢Žbï";³áק<}4Þb£IS¼ž™ÎiÖ;ì_µ­–0œ=¬–9Dëc ë« ¶w„Rˆ”¹¸ÓêûjYc[ïÜcõ¯ - +ê»xyÀ בÑKxIÁ~Ï_}Êö›á*¦_ê4 ­†l4˜ð™<ì-=>´Ä—ÙÐçË°Î9Ž—bp7zÍ4ÚŠé¾!½´9õ‚Ÿs³æ8…—’ñ„qˆÙ’_F{¶ñ½ôáöC?!ЈÝú0Ï 7‡ùR‹®Ó(/ö×î$Ôà ü"vaœÇþæ_B^:»úK@e /Áºaý'¶jx1ÈÄZÂí¶ì¹szý0#0e¼¤SÉVl±':¯ð¨ëhhoDX‹1¼Ö ñ%61ÖI#ÉYâ†íf㨩¥sG*/-6²²îf0 ~Ö”9hûg ËáHÇ‹ax³~…ò2:Æ™ãËÀ'ÒÄÌœ–·ÓA«hÙO]-í%°Á†Ÿ>Î3ú‰IŠ’Ò†Ñ/£ó¯;l"24‘!J1‰=éš¾„nð‰ ŠÍÙPŸØ—lvŠ-Ãá(]B[‹+cqÊäHÅ_òGPÄ„Pá(\¨X¶,Jäµfúu¨àö@)$­^BѸ«­|¼Âx&àˆ—¯oÄ@¯û£¦[áÑZ]?‚ºod5Ñ}*Ï Vo©ºöN¬1SÄx±Ùž@Q˜vÎÁËÀšÃZï춡_]¸XmdÓæ¸Ý°u¡Ó¢Î8Þ1TãÎÅž8ã=ÖÝÂÑU[Äi|H,V[ôœ`5Ž¼€—Ú îbu`\ì‹ 'N ¯îdg+ˆ+dc¯(v+9=ÈÌfí"Ý"‘MŠn¶¾ÈS‡X«FîÆl¾Ý`–úW ½6óµÓGÏÄ|ÁÍ”/ûÊÕPÀt«H<Ô¨×8R5lQ˜˜2›Ð­j 3ócj¨1ÂœÍÚÀ%¬¥v{‰ÅÐõG‚¾‚N‹­1c[Õä”÷š«²BY >ª¯öhÍ#?-DMï.×}&·j?¯†dN{µWÈ]á/_ö¥Ôz[Mje<`²|x ¥'µ“ Î6†8{ÄÆÐ"¾‘ØRû~ìæÖ #¦0P¢˜­ÆûI[”¨Õø3UýÄ{:û¡ë)¦¿!ÿ®B^‹1~'Ç1k•7ô®žŒvÓíj0%ÄFÛ]ˆwŠ C¸ä‰Ã@Wö¡ù@~4Ô¥¹®ƒw™P¥ü’#ß[ôIÏB„š,©ÝÁƒ)[X ç ©ç/Ê“´´°mÔhò ó1&?\À« Äõå K`RX%܉ ka©¾bù-@5uò‹åùZ”Yv×j7£‘Küûƒ-ݱ”?z'6hüØ@»9†)nžž[nÎ̇_ÒÊë¡„ð-€ÀòlêZvI†×Ð-ÿ‚s¼×óM±´fk¹I yÉáZwƒŵ6õ)“ó¼öNØk ýS,µáJnªzδLN›8뮩NZ0fGPè¦pmË"`T§úSaßü¡Ó`ÆdK²ö($\…àÄÞ?]{ÿ ;Ÿ$$9ÙlBiãÀ¥dÌSHe§ÌˆMS`· T½1ÓÅà!5 º"ùO7.B]ú¤Q[‡ö5¤ž˜Œî¦DÕK;Ù¤á-oN1Q‰»w[k£,¶u ç\ÝðKÎ⼪×"%ߺ®€©a‚ìåceKI¼bfQL±7ø'¶HÜ $>›3wàÿ*¢\ËÏ]â¶@Pð:™P£"Èè¡óEš¹ Êêб9(ã8ö·›\”Ù'Øžµ™—¤\wtuÃ5Õ±Û TŸ~J¨aË·P‘µë ¬ÍéÀ”¶ ÚíPÎÃ<7ØT’£Ÿµ¹ß É „¹Ü ]vkÜSmÁ)Åat¸Ê­–nÈ«¼Ã)fnÓ€ ‡*9Ic¦¸Ô•Qxš‘V 2*ÉÉ¥MëÈÔšm`ts™O¿Úe­p¿#ok×fOc>qgþZâ‡ò¶&nßÃ1ìöäÂ_°áÇX4¿²îÈàVÎMí«6 ÕcêÆøG^ê!=QÏ£¸Ôqߨ2'Ö&Ì CÆM>$öê´tp”1œlŒF[àýmM µ"|2HÜç¥E0˜Ìï·1€È¿v`{` ¼uǨ®·™x ã‚Õ]<±Zd§¿qHR¢+û”ÜÈÏ`†4#ÏH.Û^(H‡Ýçf| ­R[Šð‹øµq7 ñ‘=J ÕuÆÈoÔ%t³Åy†n€þÜÖ5„£ß.¥ºè{Œ. Ò­áy#{›o˜F…íáÓ”ï|@ÙäÆ—^Êó´I-x›_¶Ä~Œt?<™Bë^Oã˜N³ØªwÉ8Èè´B¨!¹)¡ZضŒ®áh¼ ƒ–9Ë")³jçpÛykUÛìæ9ß0h&ã_ ³ü™çrß’åÏ’´ º^,_³|ŽIOÀØ<d3ýÓB6?û»ËÅí§Ñ6Y3{Sç+Ý1Ä€ú¥ÇÂ&ã n!Þ°ê&¼÷³/:‚¸Ð¦M¸Üô£L›oj{Ûýöùz~Ÿ.HŒ8t]#o«soÐkS¦‰–6¶5<‡èb¡f·A:^Þ Eôi/XàânEŽZHZ ±dÀ¯%–Šµ‡ “ÐÔŸÎrð MšQÙ7b[œžb¨´Î5 U Ä•_;²¹YËwŒºÑe_1A{ak78vì¶üD]3†A'^ßnÔgúpàà‰Œ­·J鉡‰vIë`‘±ºdÑAĺÃg ÂÆ;ŠcÎÝ¢; l‡Èú &œ_q^Ÿ˜£ºÂâwÀmÌNïéYñë d´iDG¸b?<Ñù„ÑñeŠµBض®ˆ×&˜îÔÜx»# õÎ514Cà¹x¦_‹ŽšF5„,ù´G“PÉ®ýäv&#k 7.£5¡«gºlh!û7.pùwOK`_ð<)V‚Â@ð‘,¯Š6ôyÝáh‡ç–}ê]c´ë1]† ³dNSªœúúˆ²ùB¯¨äøÓ’ô6Mò…î;Šâ+4.‡°Bo¼)˜eªF]£n]¶-]ℹÚKÅDûjÉ˶ø³åÅÿ~û¡£K†+„ôèËOŸ|ù¯?ÿ½¯ÿÒÏ<}ò“v×Ó'Õ¨öé“ú±/=ǧO~ø§âSø[OŸüÈ'_úÒøc?ðŸüµçï·_¾ôµ·_úðó¿h|ñ‹O_þáç¿ø¯þç?ÿ›_úg¿ÿk¿ñßøïßøÎÿý¿ÿýñ…?ùÿáïÿÁ¯|ñ ßû«¿ÿø+_øÞúÛÿõÿÁ÷üã?ýô—¿üüã±Ñç¯>ð†á+CõN ˜˜¡0OÆ—Ì,«tghUóÀŒ§´ûúöË}Ošýáö¯"†à-!yË ú¬¿r@‡«Ú?º`ë†wlµX7¼ë«e Í_¹Gêß<)!Ò=¨%,¤xK¶Eœ”䱿Àðsßs˜Ñ ½Ü[€”˜ïgTªzÞ¹aÿ*â-apo»e*м^9<ïb}tÁ@JÚ¼HQ×WËš¿rÔ¿I¤|!7B>/4 1@þ{•±ÑÕ‚XŒB¡`ü¹?¶ò7„¶Eo‰€ÑŠÓ#<λíbP(Ÿ;¬“z‚£Í±PpÔˆ£ ÁÑÏ" ¦|=‘B ”SûjxÊ•Ô^6£¤¥ø"ïš [@({ˆúєыihQX3•`’­ÙÓ&2ôåh ’ƒ¥¶Fó QÖˆD†›€Õ„,WœË2-Å#¥ í›îY6Ìn§lÝw4Ä;iÿ PêÒ šJ¡ Ñø Y®Ô¾`·0NÚ_h=Û$}Àt hžÞòvZ¢Tt¶è©»ez 4(PjHìê%§A¿´av«º|^wt˜5‹f‚)¸ WÙ }{’ÌOÅPÍ@(§ÄUξèpÝ—ñ“Àh1C¥m9 V QN`œ¤XêÖt!0à ÝÕ­ÅJ¡€¦´ÉÎúïê ‚¥@&¢Ý&ÿ!{mkQë-¾#õ¸0eS©Ü‚è1çú"j§EjÍɦÁ¦X‘ÔÝY‚JI:ŽÇgÈT|ÀÑœ–a€Ð üLú"Õµ¼]-ˆß?¦è®XÆL30*=N׌ØPàz+˜ ŽŠøœîóy©8˜'ðUy ‹ì[[òS‹-k± ÷ÕâºF”¾ƒ<Ô²œ‘ÓÀ•1–áãqAí*’Ò½R‘1oÂÞ|a ÊäO[-4è3ü õs@ÝÏ…×¢Y6 ÝuêÊÆ€Q÷Ð0mžéNY1TLÊËp‡c¨ÖÒ<ˆqOvʧ¶küä‚»<'W‹:´&CO†Â8ï!ïÑgð#pˆP*ƒ0³óZ¾ÛôÛŒ‚ø`S•#¢_0,J„#Ý ‚Éä„N‰Â«|å2sûEÍH? D`&#'É©ÂŒ¹^9t‰-x+3U†¾ó ©§LfÌe1ØÊ´“GQ£|Ô"L¼()Šš‘¶Ã.óÅ‘oU×g0Ö? Ükj·24HÆ4ö:ÍàÙÊ(FÆ‘#`}µ7‰þ­ûz߉¯Ð*ñ·9Êsp`SšzE)òŸgšØIvÌl\Ÿžõì©…üRÁĦXj¿ŒGÖï|tTØ+\J'·³ÀWŒ°é)¤ee T ÿ­Èúb_$ $ ÈZC¬ðX÷Ê_–#LûþívÃM1ÕÓ‚”eàaJÞ7Ê—Ì0㉸ª!®0হ¸zC°HÎãÔ4òÐgº섽l¬ß6Ò)< ¡YŒÞÔT8â!óã3§†n Îr†œš®.LÏîR¬‰n~Í]YN+I… g½/³úôUº²[µv‘^“»cñbØi3û‚úž3gˆ¢›™Œ~8fU\U ¢+Y\`y¤1…È>ŠÎ–zæ_q.øz¾ël®Ø‚§©þÔB.¦ƪÇAè%.ÿx^€ú|¬è+B¢«d)ÉžñQz„±Fˆ»\àJ2D¤9”Ò…eµ¼]-#)˜zž:-y 8GyÌÏD—¿ bÚ{%`w¾0_:ò9FŒ±ä±Á¿°oäå¿a½H'Ž b&Xý³;wB‚L'ÖhÖ;¤Ñ˜8ÏÈð©—B³IÅ[Ü’«u"ÎÍþ ")e³µ nÎV¦¸Îâdeº©ÓŒ¦¥–¤ŒÖ“} S¾†ÁÖAÕmèˆÎÝ"ª©6·¹ nm¡¦îúvAÀÁàêtT0§4A% ¹:XI®æ "agV~¹ÃL×’«ëã Ùõ³.¿jM.Ъ™TŠÑѧhð”¯ÑHü‚™mÃxÊ~¼î@0Wfˆ\ðPäõ´4f fä 9~Â)H0;_âuCfRÔrQ¨õ ½æÖÔÌ8UâÖ’¼…c*öj-òÉ-MªYW¦Ãà‡m™d‚­/­vgëŽvL@ŠÂ¯IÆ_”­š[ /nÎÃdjÆ[ÆípÌÕÃXϵ“©‘íâÃ6jž–1›ëHR-sž­—³l˜ß4OÖ ‹87¸+þzZlvm’2’lš»ö!¶Ï’üÀô©‘F…2D+þ´Á¥†ý…ŸSä¨;š¢{§»£©%&óœ;̶җ=°:Ì'¼EN€7 Š!Xû…½ªr"(ª`xì/ŒÞ™±S„·>ä#ˆYÙé ÷E¼ù’ú]¯Æ†ífuº„Lwg&º£ÅN-bÐ bç• Üœm9È-cÛà"óa½ —iû& ‡]wØdpa”c 0â{¬‰¯gâJ Ä(-ìqL+2”VÄiÀ1{D.(ËaµrÝAo€Œ"ðqL-1‚¶ À™¥e Íç6 ×JïÜ‘`@TßraA[, aˆ¢×ÅB“Ô JØb¡)­ÆÅ‚  xÍšYˆÿΑ «AR £÷õ=fF2op:Ÿ€MÏÌËO²,‚?y­Ä¼9+žt£}—hÒÚëÚ›   ·A E®Úrv“'õº¡x<… Š×êãÛ‚€îgÉúej÷4{ÜhÚ-Ž›î{¤Þ[HüsÙ‰QëíŽ,ÑÜB•Œƒ,‚ YJƒ!²¸q;Ý'Ñ÷Ôb{‚”¾ã=•\ þžV(z…Ó xGWBòøž±žB4¯>Ü¢·¬÷D¦IÝß²qûã½ÌðØçH1~Ëĉ޼Ç‘í=~î{Bñ{ü=³¬¸æúsÓîî Ïoñ.1}£èÖ ¢¯¡–|:zìO9 ¯{Í×{|*®oùtþ¬)Ý]^³~Fu(c܃ö¦0:ÍMD«Ä@ÞDˆæ"¢ÒDDäw"¢5ù}Qn""¨'zO.¾ô™68zF=D$^÷8š¯÷øTœo­é:ýYSº»¼g}jSÆ9Òw‰è»DôÿEDï©ç~j·”)Ë%´ýžáõ⢰â³~¾…(ïPÒê üø©-®AdÍÒØd™”GÔ¾ÃWO§”ÞçÃ;»¼_c 9¯Î—"v{Ä»7&Zœ.öœ{M™3ªˆMóù¡”CMªãqIÃõÆ/ëý­C§ÞŸèÅ@NŸµE»^ÂWÜqêCWdäqµ©:ÃAáucùzÏÄùÖš­ÓŸ=£‡g¬YßãÚ”q4œ©ç# £&• N[ÚÁS;³]gU  ­©B¿WDj B§³(374†`¸ ƒàçק dZð„‡åñZ¨EI„¤·àmH@×[Ãî+£ô´d})ëi?3óYÁÛ4x¿’\Ð2Æú&»6|s³é2z E-ÜwhѶ̈¼bzÒÌ|Fý™€SÜÆYä|¼Zü#ìÖ‚Â~fŽu*lÙ¸~§ýù1Ä[¡õÐI×T º™>DÝ+£_Ÿ®l]$¨Ù•wÙj4‡ kpàßv‡¾(IOZpM¥|4)@%vÓ0õZS}À¨þŸÂw Öµü],í6ô¡t{ÑØ·ÕÒùžÑåv#:È„aÄÅE•Èù ÝPo ÈquZ.Æ‘TlrM&niÊMz"õþŒ)1í„#&öÒêñÜø¾ýŽèliÔì¹ ˆÈ$_•\²à¬Œwdˆ†Ý™étå¸g÷ÒîzÜQ— ÇV9ˆ–$rŸIët4ù°ˆ7Ñ«ÁîE»Z‚º9Eq1Í:vÆ`Üm}Ñg^;£ßÄHIHe-­8²‚™O;”¨e!}V{ŒÁœ5˜²@D¹88Dæ ¾`Ï…¼Z¦(Î]‚è,—Ïl܃±¢)L—ØP_8ú%Á¹¾Kì‘^’ÐQbš‘Ôx¯XdІ³ÆñD&÷ Õû4´* JbbíiA©"»1ÔÃnÌ.«ÍIÒ[wDq\dƒò“QSBbóÕŠ—3¼"ráQˆ&‘8˜(I+úHóêhY¸ÈÎ9CÖPSz‘Ï äŵûšt`H4 WN7-;æ”Jåð«èaÜ7¸D‚âS/¬BÄnÉøy}~Í”ôUô÷«bæp¨CD‰5”2¿E¯Ý[D-XEkɯñ_8Ýk|ö÷k|ć5—R¬µönï­qT¥¸×8Ò•î5~àµÆO‹Ö8ÊûÝkÓãǾéÇ5>òÃñq/ø¬ñÝ‚5>Òã·÷¿[ã3<¬ñ™Öø,ï×økÜ#ó{¿ÃéZãðÕ&ÍÔQÝ%X¡ªiqËg“ºñjblD~+{¬N%.-÷ Iº]ïȲOhÓÉŸ^Jsó€æ²pw÷дX:g“m]&¦+µÍ’Å#%z±¤Ý"–„™r5¹êƒW™­Ø%íÀ»3»¶vB\Š%:l áu‰¡½`V_¶iÂí¥m"Jîì•9ì@ó"C ”ŽÆÔž³ÎÓÍ‚}æÅ ˜þ;¤ƒq#„ƶ†´êºë`P„H ͱÃÌÆ3sKÛÀÒæV2Y<–ÜÅcÝ3‚œÃ)JôßW†ïhØà (ÿž;}yèë"f$†f×´I˹J·…YÖX¯8¹É'ÂÌuQö¢\`|¸cy(l€ X¤ë dœE´‹E’±-4‰•júsuÚU©÷8’Þ"SA öÌ2¸Íe¡øÀô±Ú•KíLuã°]TLcÎY¦:$wC÷ò²&ÇKÖhÒpâOúŠu¢; ,8ÄOý©¸ýéµeÎ=Y5Šc.•€âe.‹it˜ßÕ€êt\sú‚¬ˆ?ó 7E½ØðÒN‹átâ‚’FØ-1_E3læ‚@£tìtä¨÷fñÝZ°Mþá¸ftˆ˜âšOP[ÊR"¨ÌÒŸ1Ÿƒ3PåˆJyÏEgÚõ$Š}·¤E{YƒÔ‚èÒ/—¤=åØBÈ¥AB¦ÊFÍ˟ܽÿ¦ÞÉ×BíÁº?EÛ0Y´¹]àê·‹.g-9»oc¯Ú\–)áwT¹h8¡Ëé2Â÷X¹¥&§œ€u[ò"­@hr7rH )/:q—èúë!ÿé¬k‘?“ës¨ \Å­€`?5`A%ÎéÍã¤MgÙ²}q3{‚îCdæ:–|Û×i¡¼»…(À¾´)þË•á~ºÐ6÷ƒ4.²é‡ëjœ: qÄ ÒÉŒ ¦Ú;5{ª‹) R8Œfç3±ÔxU(–‹¿2ÒLœuù¶6ªdœœvFZ¢{z¶' 1ßå÷“ÌÎîq ªóX6ua‘×CëO×’yè,_3š¾ÂøY«û×µXFtÂÁè½rÑ m7©ç•ºƒ›ÏCeºcÕÃ,âDL7Ð] 38£.Ù‘JßžÉü,– ˆž3¹À¦xZ7qæƒÑùq±W÷&|åi“¦d0„Ýt;´Šá`ìZ­šDªu)˜¨=­ŸEê)¿A~ãøè§ì˜Éd0d䜷Y4¹hš¿!à ¦N\×eiÒ¥›X:‰¸¸.|j•#’oÕ ]Ä=]gjä÷X ƒ¹Ð ƒÜ$7A‚Ø…ëxHr^@XÄ*yì|%%Y3ÆŽ!B¢&, °\:»PãùD$§!ºµ%Q¼~ ’IàL7ú 'eeE釋Fô+Á9cò.¯ô«þ‰y`eÏÊú‡Œ×}xjEeâWËÛn)c= 裆ó̪&~ZzVªP_ÅË=®þÇ؃÷ŸVùV¶¯¥¿Ÿé+?i¥¤ì[F(ŸßPüA6½hca*’hOp ˆr–µ…’×ØÆÑX›×Ð=)WÁe€íc°Ôj,ç ¿Â²…;iŸ ݤ³á«~ƒÝ×Æ7ñ‚DBd ŠËH²@]V¼~µÉ-õîï,JÎkÒoYð& ©†‘·$«–FA `B ^«˜ýú=«f|¦×s˜5#X!{·ˆþ ÊògYRAR%] ~em»Ø7pûé!à{ùŒÝU² <·Ã'g©*‘˜£J­â‰ð¼Ž$À×Hrq°6Þ5qê[àÝáçsÒ*~§ÄATëŽZþ{çntöäµ÷76+ñMc˜À‚°U´ëŒ5€³É¾¦Uî ÛÑ%¸l8ih’“—ME¸íF@Ð-ÈÌTõ¤nžARTžxýÞЛ¯K,?ÉÍ:a  s>XVó5ôçåc;¯ŸbÞP)s;‰5ÈI®e¯Ib§±ì ªkfPöäóØ, l¢# þBoÌ5bkÝQÁ2“x#¯=öIÙŽ| ÷½áX„š^ë³òž¬à·ÓUU×ÖQwqZdçñXÃÒ/É’ê¨Cõ|`”Ù.Úí½nȽÒc"+ˆûûJQ‰ñ"fžEw($AûúD2ƽ×oM*›¸~çnê@¾Èë jœ*c’s°x8´yô Õð0“½ó¯¬û dŽ: >3Xp\׉¤†Ñ‰ CÞTyø0z@Ýë9h·f1šõ{¢4sÄZfµsPEßCQ¯vÁo .D'Ë£ßÇÚ&_ôâè‰åû'¿EÒ.±?•’dß0µ6&K­gäÇÛÄ÷±í”$[t¾Hå®ç½2Öí¥QË){)JfU6ñºG/qÛ|€Ôqú¦Qa¬â(ú͉ØÚ:¦¦¿ÔÌZDzmn;$W'7°²ØfEôéì­bWcØì î©;pÃ)È3j Tè³éÀ—Èú•[D>XRLêµK¥Ud¬ËîJë ØjУ‹tJ.T 'ãèBdK}ÿ”TËœòÎ$s9Ïœ¡U{‹¯a{±‡mŒP‘±Ëà %Ô*G$³í~cÙ4lkAˆÄ(¼×€’oåh%­åÌïÀ3ˆgµúÐv¯Î\TùêD)½Üh_Ž, ª/Ø• õ³£µêôä¸5!hj*°Ë&Ô¤åj•2ƒáaon>RocQIKÓKgðgx,Éô4ñ@Ib8{m 8¤¥µ,±ˆp£Æ\§X-iî¤Á: ѵ÷æÖåß.º ÄO›Ø4§‘¥á¦â×ðap ZºÅ› ×b˜€=5µ@ÅúH„“²H4Czéfk¨s ¾< «€Uv¿F–zhJ_|#ES‡­"ΊQ¼©ø¸ƒ(ù<_d±è÷.s†äå)³Pu´{Û$oš ¹7†ÎöX°=0%öS§>± ¼áîÒk·¸µ9Ææš(:‰±n®É4̺¹æð2A<Ô èñ™ÕmG•¬v ÜæÖñÑÜš#ÜæÀen±œó6·P×Í­ ½ÑÍ-^»¹…ëmnpsk¶t™[Ø…ó`na?äen!!ó6·6¼Í­Ó"k ›·¹…júæÊ9^æÖLóÁÜ:°›[»ÁM™‰B—¹…-gæÖD7·ðµÛÜ:ð2·v Í-|í˜[3×GskBÅ:æÖ¸¹Åëmn:æÇp™[8•à˜[L2¾Í­Úƒ¹5C^æ/·¹EÈÍ­ãenM—:[OVçÛÙó—¹…<òGs {3nsk¢‚É1·f«æÒ·/skJ‘h§ª³Üæ±Cs ½Í­éí,cjæþÎÜš9=˜[g‰ºvs‹€›[)ýÇÜÒì<˜[‰šØ‰N†=gðÒ_˜=»F’9ʧ/vƒû3x¢Í° Ž-Ð1÷ð¸GgÙþͱLÍì¤ù´6+¦7QO‘ ®>tÖ¦f}\ÚŽ×L_”Ëšé¤d?/ I¦õ^]L‹Js¯(†*KÚ)ÎRX6ÛAÖç~äý;߶.ÜX`Áô¸ûøæ`•ú‘Å+QÆ£Bá™KQ»Áqcëhö÷ÐÁTg!Ç%Ú¹º0Õ1Õ1ÕoLõ¡ê…Y'y0ɦSëé¡]S¨cÒ&ÖoLM•QðßXø6Ö ÄõAÀ Y«*µ0]ôÂÕäI®¼AØAÀ?÷÷Û DdG3“aèNöÑ8ˆiÛ›:Ð5†`¶ÈaÄÅøÔ9 y¥•s¾`„¸ò‰¤7hßbÙ”Ô˜Aìr^«È÷õzä@ŸŸsZó”µê×ÛÅ °›1>7 u Ķ U[f[…ªft™…(q~µm³ÐÀrÙ…Ìy©Ç.äñ`p­»]ȿʲ Yí†Ç/szG×·Yˆ>o»EÊeêø¿cª|Í™“ÁT‚ƒ4”£k×ï%]†¡ƒÇ2\ nòé´m?–µ©—¬`ˆcnìºq=!ð² ý˜‡Ä ëˆN?Ä %à—LÞƒY2›bŽyÈ*¤õ˜‡DŃ}È–¹íCîèB1UçëTŠc®–Ë>ŒŒðh^Šë hùÎÀ ¦±È¯ÿÌÓÏî`¥4”˜¡”U]:&ºàü:ª¦r‘ÀGSoªþ»”âtØd-›úC4XÉI ¦[0hAd½î(SŸ d†‰{Ç…¨¢. cbäGî ð;¥:˜ÅÚòº•¥˜ÜpöŠi]GÀ&ç06ÈâðÌö;7 âc—Á‘¸ï‹%~ÜùfÈ¡6ÄmžP>áÓa±4·”ÞÃ$…o°G±œ–·Ó2²,P>Ä!»!°NŠ‚χ ]ÚÚš {¯ÆiIØZZ.JtçLUéKDzQ2%èw‚fÙÇ’Î v˜Héí;Pãǽ¡¼ŽÃÅ4A”Pnô«â€Kzù4ÑezÌžp·ÐjYÆ’¦+#Dï”Üé¾j¼9œT’óƒê-Óa&ƒ%“ÛË-Xÿ<.N‘U&8±X³EƒWL÷†"Yý¼ÊyvŒr¨7j d•}¬Fq@¾ƒ›ÐÞ¹K{cùiÖ¢ô¸(-½â$ƒ­ÝùAž/¦®!¿Ê—`lª¡M7s32®6¤JÕ\=ëg®¬ä¨fÔT™»ž&¦¼ƒNÇ3Ù*z®À@VÏi°ÉkzZ³ÿæP«*§M…þy•Ô…øle^)Ìyýޙ߳'tÍx¾EHìLê:+㳪§dA{ Q»¨¸Ï–DA´P[p"7iqýY ëîâÖÌâv¬ÓÛóC^Kìu9U•îLayt+ T+×ùÏ™^‰Æ¹‹¢‘Ъ÷©±,½û<&;BÑa-y‹"<³,'i°`ñþ}Ž–l iåÓí õŸÕ¦²Ö^†à’%«"árløUu±K9w°ôR¢¤ãâÛðòÙï–¬ð½aðÐéÈÏé¼tì 7Õïß» )"g°I"?øzF/í¢ &ÿoÊXЦ Tø»)#ñW§ ‡2=Œ›2.ÊÀÙ7eø‡e¬Í JA?›2v¹)ºò¦ ‡2’jÊ/Ê ¸(ƒÇ¡ (ˆ”Á%v(#µx(ƒ9à7e0oS q^óÞó;Ê¿y ŒQ)cÁ‡2¼eQ2¶×̃>P C´¦.ÊX$ðŽ2¿‘%ST’¸JQÚ%ËCmlÓkwi7¾ÕÅÏ°ÍÌ´ä|ö¼ »*–EçP¤ÄTFMvUà”$öTµŽ®e9 !©sUtŠ}¤ ã¹œ]šåB9-CÊÈ5]ha5]hË®¶,´¡ªÞN”@l'óId'—º9ó16£vë¸y.Œ|a·yl%ë4 ÉµìLÓ•‡$p:bó’ÔîªGÊœâŒ@NGVutÿKŸõ§³ÎÉÁµl¶Lééœî<ýÈE_C4"4&I¹[ÂÒ²3RAGZÌ™´}ËÏmæÅ«“·(‚Ý/ñ©Å¼y ÕÎÃ[6–È×0ʼRUôÃ[Vƒx@‰Jë}„6wA G^Xõ9È>$Ç €óŸ‡*R‡²Ñó¶@ŽPR$QŸ§ÃÊ• ä3æ¶×7+i·•7„…cüÔ.kÐ@¡†¥¢©vuwC\|spw>ñô„Í6‘¹Ùo¼1G¾ƒšªFO°²*˜/¢ë Gµl%øÍÁ%?KtØzû2¯ÕX¢´’õ3ü<]ª@ ‹ÔÒ¸<Æ_¢ü²°U9^ª§I˜ËŸºZ`…2‘KØ4aË9CÃ}ÖÑ°¼AeÂE¸ë¢§³ÜMîDF Ø…˜ˆtµ—îŽß«NRàñ¹,wœ¸Ç!©ü^M¬ûëÜŒ\V¬HÇÔ5ìã·ÖÛâºÆÓpR´ócPòc[–…)ÄipŽ[^QYA0”9§M¨Y© ò:Ý0¤ÝôbÙã@äÓl Êš^"9PÉ÷J‚‹ˆQyûk­ûGè糋jónAÊèlÊóÅ›Sü¢ÖJï~í=@áÚ(廒¯öž®3wº¨¿•L‡¦o–¡í0,/¬-:jxÛ ˆ4˲õGîžë îÜ&mâÍ<£Y=Òõê_ÛVÁ.vFDfŠä3 #^â¡B™«*EUîJ[²w‘)æV=ËÈQ9¯Ì}hRpdéf?îrSïv² ¼h¥§pé Éè[ï\Ð mæ½³p¾AàÈ€—l ¸ôÎ6˃Þé:Lo5ˆD:ò3Þ›å!èë¨Z¼õNGïìÜt½“àÒ;{j·ÞÙs|Ô;{ηÞÙs=z'J>è({ôβ9Ze/ýÞÙkyÐ;{z熷޹Z–ÞÙZp–Ü8»^o½³ë¼×­w.x§w¢ºT”›‹‘ØŒ3žŠmc9‡FY¶ŒÛ÷›T&–ù˜NqéH«%f%cuíT‡ï’„2Ê-m˜_ ýÜ1é&²LΧƼ5Yf m_ /9XŽTðÅEü¬º³äP:]}žGµtúT@{ëüÈÛèóüΕ3üâ(ü3–[á'Ø”1“‘€0’>q:˜Z  ÿ Ë>@S³ð@-üf¾0Eà`jæL tL!Ï¡xìBp–Ì mêûi¤)ä S5\DóÄýÐIêù½åŠÔõ…,Lõ…,μd1*-Æ W•§m\¸òÇIú{¨eAAÚæ*<ät»JÐ!dÛ}dÖs;?ò,˜å>2K¯_î£|«²» bÈ—ûÈàxÜGa·û¨ Þáq¡ÏÛ}T‚—K_ÃR/÷QÁŽà•J~pjÜ®ßC½ÜG Üî#oXî#>}ÜG…'¼_r£`“f¼~wìºû¨Uï¸ÜG…©"Ë}D¬\´‘í>ÚƒYr¼ Å㸠ÃøÇ}DT<¸ŠŸŠêͰ—ûˆðƒûè´l÷‚´ Ć*/É+¤ë¼†‡-vYæªZëØÝ£²èf”°†h «Ôª™‹|×Ç-½®ýt{ÄÏk¹žÞì›,ÿx;ñþëWK+û©Æ œuUA¥›åóziû½…R?n9!±ý¡áã/Ô;mµÜ8sGýxŽÚ ˆÃ‡˜(%×É3âŽôù‚Üù`'Åá×)éø;B-U‰-AÑåœ!ý›6òî/ Õ¬â´?×D^úŒ,Y¸²%ð8¢É8A ŸJÙ¯Õ {-¡žüä;ÏâŽ0š‡»HçMåcàåENG+ëÈÜ$ü­–·ÓÒ¥2äŇ®Ùÿö­'Šê<Ö{4uê!~ÃCïeºQÂïðhðÁsÐzöè]LðÄîÑð¬l;{iYrÊŒižpæ1“Gô¤îŽë}\Þ-ÒPËr!Lå¤G¸ °ÔTcÐÛåu®d &q9zÿp­\^ä§BJ­luÍ#Ï4ÒaàÜ¢- üö«éH#o à€@æe½u;„êà Nù™ÛÑI1Õ¯SÓ!w‚š—~Ïž©>¨AGWa®ûÜ0v+õÜQ½HñÇbŠéç wE¹¯Ö@*ëd,„b¢gaØzص× …» d• ŽªÃívƒÎ=(4"9± ©9¥F÷åÇÚw„¡ì>È@ÍfÑ*~î³íj^Íqèl»šuÚSÃÎ#°ª”S6˜œ­¹Òf':çŒmQi­p¿ƒ¿2YQ׆9žk'…•?Eh6—5JóÓpwE"ñxÁ6àæg‡¬; q¹OÊë£h ©c· b;]˜±é\ /9˱UûÝƹÛ¼SœìÐç>K ǽZ´áÉŒºÎÆpÓ3ùNß›yƒ¯O8žë}C×®U¾Àº:Xㆆnm`çå6}Y©ÇÉq¯:aüœ§Áå bë¨ëøë.èÄô@]#h6E¨Mú„°O5¥rœ6[±?/Mõ•¥ž¤¡€©uCÉ+†b8ㆭ.éSØhZôºÊUŒM«i)LŒÞ%ì±÷”×:L6ûóÒ¤±•k00uÔèÊ«`»¹_;~ÔrŒˆqc­V½a…ºÃ q¥wðD4߅Ƚõ+*cÿ¬ÄQh†xËÛÕ(rQk=uZÜœCrOä~®P›±¹(Œ~µu~ä ¥ öØ]ÔôÑ’öUkŽ`§–dZÈ¢ìðE|Þ2ƒ«qi]—¢r‚*ÛÄAŸ-êø罡—‹J(Ž”QRuˆÎVÍŠÔá+]ïMZr p꺯.%ŸmÂξ·Ûœi¨¬š*tDÄâM³\‡šàTZ6X}D)B˶*‡ºîâBl°_žmýád™Ô`dAÞÿ-Yøÿ(Yu¸% —dAÐâA²p£ê‘,ØÉqI€—d™‹ÕVmoÌ·d™Ì:\’;% v™\’ezbø³öGÉ2s|,3Ö[²p­–ÓBÉ‚çoÉ2é ¾% 6ºÜ’å`[’û0ÞI–I\Q² BtKć.ɲƳ% vT_’e¶ö Y€É‚­/·d|I–É“doÉrµlÉÂ"‰y[*ØùìfŠ®{f¹Aî%\-Îh{TÍk섉œFŠ#6¶_|d½WKà b~w­òÁ”zƒ¾àÜ„]¡Õ%˜›ó&OvßwTS€™bõðÆS‘e+jû"òqÇž<îÕTX mªŽj-Z)Õë`.WÊújÞ¥ï'}^Þ•Lß8ç˜ÕX7Ò?7„á¼Ò‘‚à4°dJáß„¼Áôk§ŽB†y”»…¥GQ½6ëµ”§wÆÍEÏ8©5 óä‘ønWÍ[ï Ü«]Ï•áÇrkß<üÀ3Æ?ýÃðqendstream endobj 6 0 obj 16295 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:58-07:00 2013-08-20T08:41:58-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000016599 00000 n 0000018169 00000 n 0000016540 00000 n 0000016401 00000 n 0000000015 00000 n 0000016380 00000 n 0000016663 00000 n 0000016704 00000 n 0000016733 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 18339 %%EOF ast-8.3.0/sun210_figures/complex.pdf0000664000175000017500000003573313004147321014160 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}K®e¹®\ÿŒâ´ÝH/ý¥pïù5<€ü®S.Üðô­ˆ )­à¢PÈZúRE‘¢Î?¿Ÿ_éûÁöï￾þóßÿñ¾ž_­×ÚÊ÷|ÕÕʯѾójϯվÿŠ”’fþÕÚw½ý*—Á»œ¾þýµ 2¦HùùÏþQW¤´d9¬NÇÞêï/O©y¡òŸHHkþJu~{•üì-üþò.YQï1¡Çëql ýþúÿé+sNt¥0«Ñ¡7I’Ìïÿ»Éò_÷ÿÿëëùþ/ÿ"ÏEž|ýûk ÷å&Îúë¤ õ»ÖG5΢%”[Ç2püû+·Ivô”Ÿ¯\ º)¹pAD­Õ]‡¥´Ü¹R~"¥ph›F^gUcÞhõuäýª¾’¼ãJˆ¥oõ9öÏbªÝH¨ò”±©º»PKmÞÔÔ§•E¢Y$¥ŠHÓ¸%—-=ÒIÉ™su¶Vw–ÒÖÃÿDJ-^gIF"kÕñ&ŠõÌS6U¬ïžâcó:{«$Ë¿Hò&Éç"JIbúI¬è¯+¥‘i7+rá¦gi=¨ûà=´ù¼RöÐFïwJÜ8¢ÎƒÕê®ÃR·Ì:,%ký{ÕW¬5¸‰cý²„Më¸%ø¸¼¾ÀÖâYDO%ÍÒ3’ÉOIZ×õI\¯)UÎ~Y\˜1œ–U¢:ÇŒôÜ)¹©2&O[«»Kéyh@žÐ¦–½WÙš1Œ5êø÷—wÌS@uÝS|h^§ckTKè_¹‚ôϯÚÅEivöö¯¯1Mq²”Ÿ+e3®Ržò¯ÿþý¿wº”¬nÚàÍsÚšú÷¯ÛÁ|µ'{Þ,à¤,©XIÀ+i'õV c3~LɳÙ{j5VØ¢<¥=œq¯aj•ž‘ ïÞ K9½T Ÿã «âÕäl„hÑWrK g*eN*'Ë®é’qùÑJÏO1)[@II5m<©ŸÇ¿¿ÒÓ_)?_k½Š¸jìU¶Fºž’Ô䟓bbÒªLtdoÓñî…õËS~¾¼çžâ# ÉëØ )—–ø:?Ëu¤¤^E„Eù™s6œHfÇ ŠØÇS0"Ó -eÃVg`kÊ©RRöU)‰KòÛëÜCª¶i$b«yÏòžÒóÙ:|ý;X5„ôËJB9o-5ê;µØGçSéè¿rLá?(î28UoŽßü°™çÿ†„çWÙ2¶.Z˜Þ n ¸ÛËy2»}ÞTÜE÷2›Ö¯¥Œ@bH¿·–˜­‹cWÁ:6µÑëYÐ}~=ht=ld/1vï”(þ$2Ž øcRï[÷`÷ÚÇĦ-FIÙ9 ù7•Vö6ÆöþC™Ì§´Ã]·f.Àää-ÃœªAþ·,08€ EÅê¿÷Zè^7`#«'ˆALÀ>¡^–éä~ƯÀ 6~ï±ПÙÁ- ›$ÌÎ5ÐЖbìƒ6¤AÕE0d+ûI‚ö 4Uµ†wÕ\ô}ŸzëótyÊ,h;mڠƇÜzŒ9÷~ö«ÎøV!!6- â Ì_l@E4Çdè"•ß»w¹ëÏ[¤Ýõïng-b­_\*ÜLb¥˜„Ü›-²å],ƒ±³$/æ­ï¡u°e†è‘Ä{æzŽÅ‡ÑÎ{mîíß7C²·»~*Ž Vˆq¬*VâÏ•RUuÚ+œÓ´æÔý¶ V~‡DÉêf_ƒÜ…)wv b}W ÄF»º¿sVu¿Ï«2RxI?YnYÒ´“Â>ùU{ý?¼ÂMÀ={ì,—w³“¢HëmÇ’"‰¢^ŸKz$?³ÿÞêj=%'XŠ iï—$ó ]Eü5\ùÑwökjè`wgéR>Yº”7K—òbéR>YºÔ7K—z±´@°4áaiAcéRß,]ÊÍÒTp¼Xú@²téo–.ýbi`iÂÃÒ¥_, 7Óaé2>Xz½Xº¦‹¥‚¥¥¡_,]æKc0K—þbiõ7XZ0Xº´–.õbiPøfé3ù‡¥­~giƒbéÒ_, ‚¼YzÝ,]ŸÃÒú,-è,½^,]ÆK³ÕÃÒꑱ´KãäÝC€Èt x/ÞÍ w©`;¡L¥Ì_gMèœc sÖM¶Ôc<¥k/‰КV€dŠ øäÇáæ?6´•žôíªôîG±‘ï­›e#ZoÝÌÚêß@dGÂ>úvS®Á”­œ¦ø[½@ÅÍ´Nž+6ÔÊ}r+ )¸AÃÁaÏJ @툣Ü›rcF©_ÔB 32Öžµo­ª×Á©Q  AF«Wcî‡hR—GÏ!ª¦#¨›—Ç¥×=K£FƒûטWŽiò¬Ø“I†3¸•q‘d «yÖ5™ÃäjLf$pöà™þdSÙ¶~¤C®jk‰­- lÞx8A)ö,:©Ø7£æÕ4<”ÝTºC”Þ£™ó|çd »²Àf³ÊÑ f~nõK¡Á`wõwŸs¤ŸÚèO‚Æ»Wùùè«„Ÿ1r«Cƒ ÷©û„»‹S‡F‚UÙ e‘ÉUx±Í„Üm°œÃUÛ*벓¥À÷õœå0žâ†ŒM#pDd­_¬59q‡]©"&†³Yâ ˆö’Œ]ó4î6å·V«]2’:óîƒv_Ú,8ä-ŒX|øa3» ŸS ôÇ4ä ÛŒB»÷”^{mÌzá^mß‹”­õBàV©'VøíØà>Mè”Ý€“°Õ 9Û¦ŒÎMlµv=ç ¶a²wóíbûX©Ç|LV{‚³Ïè±L(ÜqÐIõx4©8b¡FȶQR`:KnéSÿ2™o ÊŸ¦^ôôpâø­›Y}áNX$«Ð—Ì>t;n¡¥GçLTYµÿrÒ·V‘,¯ î¢ÐÞŠÆQîã`kØör¦j€%3—Nz2›l\µ6AÛ ¦–Sf)¸Q`“J.ÛS¨Inf¶š>Kf+¤hDï•#©2(Ÿh&ãˆvÌ%ÓÈ& × ö âj¢+… ¦=°¯u½Yiÿ(bÔnš# {¶©Qw¥Øzlƒi{14Ó ÕcSM„u©X„l«œ…‹®k €2Uƒ%ôéÞ+»ùEÊñ)ZÂìmŸ6ÃI» lÚ'[ŠV=ë¡áTÿþ‘rŠNÚèþºR°þÈÿå—‰š©¥Ñ§Cô~!÷óÝe)䜩z²ƒ=F˜8 íóí¦%ý†V«™Ê¦GvÛ ©ŽÒ¹É¸ô›fd6“:F¸U¯ Ö9¶°kÌ°â^]2#fFO*š|h%ÈyŸ¸KÒñÓmÄÈJ´+^¬ˆÿ–´G€»Bg§€ìù‚”Œ  ˆ vVÓ®0I“Ø){ú‘PA›Q« R²:klª€-î]¬õÀh.†~åè<Àø—ú1˜¾ë£M%¶ª6»Ú"Ï2ð“ƒ`~¸¦YÕ!s·”EÓ†9þBn± eï—…‘ P3Ìk ¥Äômì¸h6žì<ì¬` (Æ¿aˉýì´S–F¨³S.{ºwbL?-6ÑjìÆÉÀϦŒ  ¸ù¥prˆ’ñq¥½¡à ÓÞçâ.8XÔ1Ñmæ>`%ìƒkdC^Í*½ª¡<øÁÉà(œ«Æ¾WÂÞV Íò è>bt43¸  ô þS .®xxû;’Ad_ň«ï,Šs–ÿîM®ƒÀ?yŒß¿7VòM)Ç$M÷ü I©ºY&‹pqM¬X²D§ T+$÷KÒ³è#‡•b¥Í%ó9ü굞ïdDèÊÍÁ^iTE f’úÇ¡†Žã¿õžë«–B‘áC¬±žŸÿ„:aæ*[0k{ÔV/ZFÚÚ“ÈÑ»’4"B\ìµ¢ý^—µ)xbÊ0£pÙ‰*ãº8™À¾cÓCQî›®–Ó˜Þtƒ÷Ç`Ž 3Liíª¾`žæaZk‰‹«ópѼmâK‚EŠiwJV‹v¤Í¥Ñ»K©^¸X‡Äâî82¤Èu¤Í°uô,¡™9Wyl™²0Ö1Øõ€Ú “›™s+ßælIÜÌ,ø¸™Ù ÌÌY×€yþ'+,@ÊÍ@,“XîÈëy°É,A.˜9óÈÌlÀÍÌ‚ÉÍÌ6R5á",m=%ÑŽœa™ŽP²ÚÛgN  wÜÌlPfæ]®ÂÌìs³N«oÐÜqx£=jVff믛™ S´ç¹*…ÅäÚçAa®L™™¯É3³×off‡û–MnfÏ6A$W³õ÷FÎgè©‹8üíffƒ23³T6Q‰¬ù±¨Fg´:ÏwöHff·™9÷YµßÒÝ)˜LË5d–7ÕÌû#¹wÓU\£¿R’®ŽîxA»’Çcb]ŽÇ$5ÔF¿"˜ýBŠA]HQ5KZ:ê e¿rRx£$ãô×ò[sOó )AiÌ€ËÇWþ€¼’q ÍSÍ‘ÊÓú6ø…ÁäR êB ë©Eä@øAoPAÞ“’ÔI-ã? x{•_VšU#gëBŠ¿"˜“hQhMˆJË”´:Rò|Š4¿²S =u¶úíMn{sï1&Þýó#Åj7  )†ºî!ó·i18K%Ûn3êØdzy4:…Ùºj1#ÃàÀ„Äè4ª!‚£Pªç;7í/™Ð´L¿²UjSÛMA®.¤8° )y\Ø¿mŽh`Åì¶]HaÃ쇷}ÖJ;ô )WŠÑ‘(lRˆ›iw:N %KºBÛRfq!Å~û…‡RÔG«¸B¹:?±¦CdÞJã<Ÿ Ç )üBŠA¿²[:ðBʆUÑuvÚ¾ û…”·kíÖs8äU}Çv!åJ° )'E&Ì]cáVR¬û¯ ){ПjlR·–4Ÿ—Z5ŸOµ i_Ò¥V „ZExÔ*AS«h,»Ô*ÌÇQ«©`}©UR`ÍòV«f¹Ô*P«Z5Ë¥VÍz«U³¾Õª9^jÕœ—Z%j• ©Us¼ÔªÙ>Ô* æR«fy©Uêo¨U³¼ÔªY>Ôª™/µ ¾Õª3ùG­²ú]­2(µjÖ—Z‚¼ÔªÙoµjŽ£Véw¨U‚¦V¡Ô¥V!úá¥V±Õ£V©G¦V¸Õª~U\ †w BOJÿ =9)z¥Þ¡'éû~UÞÉÎWøIi~‚¼3G^»”}R¾Ð«a.ñ–#ü·vñé)èëK¤Õp°‡†œD ~£óð“è…¥œ^ª†ÏqðRvIŸá'¥!‘'ÂOjÿÿ†Ÿx Ù>¦wˆ]Æ…qD¨=M±¥U5”µ9öÂä½|§Hm¹S<\Îë l­ž»ÔœK"¥.QÕêäF@ªULjŸRÏ<ñS껧Dø ÕØZý#ÌnŸÉ»Ø8Rjg”`YËBm³E•åçÆ¿%Í×Iù‘•NŠ‡ˆy­ÕUFÙºÃʶ€k­hC\ÃBÙªcE=ó”Í%k‘ìžsVgàîc¹íþEÅP|mGJH·@9)íSÞ} ¸¬‹”u „Œˆ”“2Þ²ÎÃK¢Õõ)ë,%$™Õppû”u>rjHoY(§é-묆Ïq¼e] „¬ Bœ<ëCÖÝ(ÿ„¤-Ÿ¢Üµé)?'%é©€ŸS*R4E§6Ÿ¢}@µœ |²)¢‘ŸñZ>='ň›-<Ûb«NÍ1=¼§}çÈZ`Qƒã˜žH±é‰,n5Úðé9½°ÑK«ácœžŒË8¬fúàšÅ©§$MÕ‚³x¯j}›†ÛËw;n/²—¡܃9öô£ê¯NÞ+…¶¬5tÇæÈCËjpƱ4ìe«Uk©9Xn/DYÌ®Êùœ=tIü‡$xWÌËšf/“ù lÝ'Z¶™½ö€{6úy}Ƙ'íed/#ÊOÖžÀߥÊXÒ²æ§,qŠÄŒT³—í^; 0Gœ@ä|‚Ÿ<;Dî$S—çÍ’¼./ÎíÚÍ^VžÍ)«G{cñõ‹f/3˜åÕ~Õó†*f·s³?Ký°ï0ÒäSÚa1{Ù•btI´ü2úû1ÜH'³—1…†ù鳨Xýw5{™C÷EØË6Ö¹9ó ŽAd¦W/>þ¦½Ì@1{™Álö²]ñCŸüãΖañä]bæ $çì Óªf/3Xh/“!ã/]ô꼿¶ŠFëˆá¡Äý„X‹6u@­Mìå«Ð^f š½Ìà0{Ya€©IÝ ÚůYa‚ÁNYvÊøÜÉOð@Æ[7Z‚…ö2¾¹Õ[H<Ä»¶€¿5˜žÎ÷'ûú®6ŠÝgNÚËh';•‘Â&‰3Õs÷¬´—]“ö2¯ßìeuû—sæŠ?E‰¢l=çÝ•øLe6‹8üý˜½ŒÐåKq!ÁZKè*¢óãÊ¿kÂ&íen{Ù&ö'KçöféÜ_,û'K#îU`\,-,ͲÃÒ‚ÆÒ¹¿Y·šKbÁò¼Xú@²tžo–Îóbi`iÁÃÒëféu³tyÞ,bK—z±4ÀÅÒ‚ÆÒ¸kv±tI,ÁÜ,½^,þ^,-,çKçq±4(|³ô™üÃÒV¿³´Acéõbi*þ7KãVÝaib:Këw°4c4¥yQñ°ôÖÎ?Xz½XZf,màÅÒ…WAŒ8·oÊ™´È,ŽÀU n%ÿ2€«àŽÊY&f`».›l©Æx¶&ɽÄsô"=k®ÀEè|òã@¿Y ¸L•Þ=6r]Jº¨õò¾Ný¨[IwȺ)× ô˜§)þžÀEHŠYWAÔ\æQ‚B¡t9: ¢æöÁ\,ÜÊà`Æ&§5’Ì–c¬þm,•âú 85 Raã+ºqºs¿H ² /!î•gšY•ÿWžÆ¥קH •¯ ’ž#=¡o(v ‘J9IH²„Õ 2$&s-;¢ødFg¯ þ ²©dLa>µÕlb ¼¦ÝC$tÅžUñΦs3jæ>U)^W×¢tËFB}ovdÈÍA¶.B.ã©á7;…W–ÃýÙÓ_Ým=£? /ÎÈ"ýÐkÆÈU'?^Ý50-€‹]œ*h§-¬ÊÚéC2¹ZuùÈÝ*ž‰ï…óHáIºe;]‹Ö9)!~quqD䈊 ¨£õÀu±ëuÛ­ bHâ…öWG¬°µnìj°wïÚÚn¥V«}ÃJ±ÈC»o«6µM\[ÎMúaZÛ’ wœR ´¬ËÒA!Üq…pßdjm@ƒœ-€ë¤$ÆÅ\y{ÀB¸v…M >ÀUp™­Û©W4ZR øZ àÚ5PwðsJ<ÉTp„Õñ^Ý5 h\‘`ìƒâ¾L fÀƒN_¬&SC×­\VÛª¸ Ô` ®]•m\èG˼ÆJ€^Å•ê[Õ)Ð|à Eü"óV à*¼úÔÕ®×´Ž.7žn t à28¸‹nðü’­âá ×AKÖ´®Ò²Ä,Ž ÀjšÙ¤àfÕ2\Ë»¡p”¥;˜T{ Mr~Ìle\®ˆ–p\/Täçå%éi6(˜^«L#Òü B<¹ò àâJaÂÒ0¸o$†“ÈÍûCˆ›®¤ÉKíaצöÂQ>@ˆ1<2)s•ô-³¥ÔáS§ò¸°2 l¥æ©÷XK7K¶ îªI¤ƒë¦LïI{*´s¼@e.6¸7µ6Qn-³AŒë›rA›&KáWÁx‹9øºÚCKÀ0•mŠMzk¨Äxk³½mh]r¸se‘í„YR-…cM•ôO¤ÜHáã^[Ú=ÌSÃß\•IÇþ;)[Š¨Ü†æ¨aë{šŸÆ™pÓhËóùeðàfkCO§—fÐI#÷‘¶»i^E0~ IrÜdK2[MbŸæJ¬¿ ÊƒÑÀ5b  >ôÐ sÐLºcEOŠŠn¡ŸHþ+ij(Äö^jWT ¬èφsˆ½WØéš—g†‡»Zhût3 í;a/œ¶—ÆiÝBw-Eöƒi÷ƒ6reØÃ¥o&9Ø{Ã2aùžrÎð§ù `ì@§]èáž4y@m<ôÍàJÁ£b»<”ß'é"ÝæÇfÜ"ïOºg)À&Ý3*ÐèŸñ67Þ«†î™äB×ònh–Î9ÚƒâY1ºnø·ìÒèIätÀxyCôÏXÏ-Åü3ƒþ™ ÷Ì0Ü@«pÏ ¸g&½3‰ßIH‹BÃ=CdÞ™Aï ïR>áµK8þýeWO~Õ–øg´Á6MëwÐA3ä¿Ì\;6ñé I¢(BMrÇì4Mj•cU«À0­TV@)tÐXÄÖfÊn¶ˆ“cÒI3ÜG³(_ÇqÑ,ªvøÎágØ¢<ŒÝåÕBVpéÉ‘é¦ðÒh!i¥1Yâ"ÜàñI¢n2à¢ò8覱k¨ü^(º9¦%²$c ]•˜ôšÇµTíúÉÑ©ãºjòÁáªq\¹0"eº§G·=³æ¨ÀOSÎîƒã¾K”Ø04¶LÚ¨R‚¥y •Ç´ºÏwú«9óǨ½Ñ M[Fm@¬9…Fm\#¹0!kÃæ.·…Sð~ É­Fl¸={¡Ï€c΢"Dá›{ì–ÁØ»fúo^’k,2àá8ˆQ2À¤=;ÉÒûpõKÞ.´Cìá)¿VoÁˆÑì‚'G϶̫ Ò£¤IEChå®–P¦I»Ð¤=Ý¢í_m›ÿ‡ÕGók’£QÑ ÝiÐÆUoõK+Óño¹Ê•ORg§ mÚf§n!-X *¨]\QqrwÓ{<fÎÍÚüý¶j§O–.éÍÒx Ýð“¥K~³t)KK],Mè,m±òÁÒŒ¥w–v býfé@MVøKã)¿`i‚`i¢ÃÒ0×;KÃ2±té,]曥ñp\°4ÀÅÒ„ÎÒe¾YºŒO–Æhn–.ífiôùbiÂÃÒxòðÍÒ¥–}/–Ž‰¿XZÕK Š¥÷ùÅÒ É›¥á~±t™K– –.ãÍÒ°î¿Yšm_,Í™3–ÖïKW¾§ìT ­žhCPZ~NBb}´§ÒWƒø˜_/‹‚(ô¦ Z]MôÕ8¦Õ–ö“#ê\T²’«5—à—ƒ Þ¢ÑÎW«iÛåà÷V)rDŠlÚŠðùDÊM3½6V˜¸ÁxÙï4`AÍNzk²Ü5Ï8TÈç‘©ÆMº!òfkúj²xVÌ€½!NœEt £Ð¦žiwšòÀÔBW¾ì¬“Žšd઎ÐT7Úµ>Dïbîi3is×䛂æ~…ÇjŒxúQoõ1÷c^9Æãz§~/Íx¨â8š@a-›?Ï4Êý}O£§hâpäùg'Ý4§¶)Ù9 /õkÍô{ÖgÇaäE7 è còÓ›©|Î+GÒáŽþ¦ŸÆ²®ãi^¾iO‡Áãô–Aj¨1úH‘ÃÄþ1züI¦: ãE?†éuÐù†[ÙC€„ðÓ`IÂ>|Vt;<ó¾ø›ý:hÕEÓ$¨ˆ7uÒ²³‰­”#„«žõ»„0¼Lë[0ëûð×´és–mF³"ÎóF»ŒJ/>1T*âoØL=5SŽ¼=5+÷í¾xÎ -ÁM#ƒ ÞY{ÐÙ¬ó¢ŒS¿H4骹I4è«99]1Ó|5éªIf˜f ]5(Ðé«aD ;_Ãí<.™«fp†{j=5Ã5Ž?hТ¤÷©›È¿¶ü4?£Çå´%ûôä딲§uê#Ü40ÕÃê`^\ÕGx1 5˜Ð4¦†±“&Éa.šE ¿àŵ]ë0 Þ’BFúg’̶tР‘Ò´çÝWóÏðw¸gˆÌ;ƒWªZá¨9­|÷Œ[¦/Üiç¯ðÎ zgÜtg•1sÎ8Üå bŠûf}3Œ~%õ7!9îdŸ4V1–\»_xC²Ó5£ß{¿æ˜Y0n€Ó9é–IÀ´äÎpË`Q/õ¿ïV'¼2ͼ2ê !¼2$w¦9"qõÐ.7Ã'3²LVï%x(²I,¤Ò’b¸Çô°StÊ8fS÷gH{ze„W†(æÇñ ³:šO†¯€èVˆ{dðû8dº*f“ôïµoqú{86Dº,æñÇXÝ1\ðÇ@ ˜< CÆ1爙“ÃD¦{d–Y¿ž ÉC—Ì$Ÿ>íØ’Â#CD‡L²Z 3X#2Óü1â3}°®»7æ M-K¬ÒZ ‡ÑûÎåË€¯¶½p'‡LZT vÙ,‹-^6,°=`t†aѨ'l¥JƒO[£>Ó6F§eŠMÃk¡µm=(|@ ;Dö‚Ç&ã3žÏš¬žŒŽ7úÿ¶‘ _¾»ÛëfZê³Çy€¿³ž=#ihÓÂË8Cu ÿ݉f\.fŸÏ“Ñ!Qa`¡h°'Ï ~ Ú]°ßýˆHT<“xJŸa}-ɶԽ½J\|/ÔÕAû¾è±*n÷Y’nŒLnêö7Ø„ GÔMKAM[™ÓÜIðýv‡8.ÓÇg9fçä[geèÒ œ¤¨™ß&v{ά¼.LÆ6_tþ!'çÞæË›IäÛÐ-'˜›¹7øøÅIÀ=|Ä?âO\‡»›+î<‹oó9¦Ó#)jÛsðQ^Æã+Šžoó±BÝZzä†U,3,eÜ*p°¥ø·‚KÊ•¡$ ¼×à O¦Sû€ÝOø6_VÀXÖZz÷à Pím>¡¤7ùà_[|ÆFlH¯R@ö\Á‘ÁŽp¬ñ‰Šgè…äŒ —^¸Hö6©…{&ø›¹¨a0.°Âηù£ÉÆ·ùN=.¾1ßæ+dç 7KÑ™j0Û"½XšóªàÔÅ'T5𜀜D»3|›Ï1ÇÏÛ†‘aòm¾Å¯¸úÖøD‹1ì³ø6_æC–d&¾ÍǧW†Å wæ¡'Rº_‹Ã;a·g=2ßæ#.öÈÌ HwÙP7"??öLź øèm>!Pšo‘e½&À7 §nÝwA^ ,÷^ë6sP÷·+ßæ´¿òZÕPà«},ÎÆžÄÐÈ y;*ßæãk4|X®v½gÔÌ¥©gQìº –=êAh’ÇÏ -Þň«ï|a§M=ÃçašG™>ö6Ÿ ™ò›oɬ¢Ñé*<ÚtQʱl¢âž?¡ÝtçÛ|¬KwüY±d ¼þâ^ÖÔ[<9Þ\)FFÚ¼FŽèÂZÏ÷L2òm>ÕÞæ3øØÛ|‚6tü5!ë=×n¹ÏkèÃ@œóß@»<˜+ßæcmÚªº5ç¤Í¸¿rÀt@0žêuÂjoóì|ÔÔH1tM;-- á‘ _âßqnBQ{Ae=ZN-b+æвîS!23é%•Ç«íª±lå4àµÆWìÍ$ öñ%Á"eDüCÍjqxüƒÝÿƒT×S§C’¥ëéž"÷mÅÜè"‡xv7¾V”uͼÝP›¡ašÂÛ»@’-)@ g `ïA@Ø<‚€MÆ;ÝŠ €¾¡ERA…þ ›ß£_‚AŽjAÀWØNAçZþ¦Ù‘—÷¹µ)°c-m}A )¶Ï¥`¤E”ˆ lAÀGd|îËÃGd.Ö[|D&XÏò‚,¾h§û‡)Ìys˜"û<)¬¿6í>ùwAÖ„yA–(U‘áF4EÉÕˆ (Z%A`/EeÿOA–ÐR¯äp=3‚ై^ñïêÑãYbè6Lã0ö[E² &‹5&ra+¥jÖ}“Z¥«˜dá)RÌÊw¸ã=Ö˜ïT^N“Ô¼` €ÛVfo%\kLˆ—’TŽoóQ«`G­!蓺ö)|€nDo4;ÌŠÐÄ_UÉ T˜É4ÈG>Œvçø ÷õä©æ@ß" ÂúýûË`²XcA¼Q¾HÁ·ùHŽF'ûpÈ{RäG™¶Œ?!)T`ªTihVe$k©°^ÐIBåW´H´,Åœé±yƒve{½ öx¬1ÉG‚bÛð‰&7ÃÓš¹®]Ÿq(o$ X¬±Pm2=G‹¥'ÙvKóZçÛ|— G‹ž=V–u·µ„ð µ!Dì†r|‡â¦ýE—zMËìkÜô¤v(ˆ…›b ø BAŠ½ŠJ¥h©bv»Z¬1Vvûnû¬•vØ<Öø¤]t_–ÚÝc¸™vg†Ìo²AÛhRfkÜ\Ëí^·¶¿Fƒ6ßæ£\ºé»¦CZŸ_ó|æ B]±ÆÍc«Çã2ôà#|Y}àÛ|qÚh¾ g5núË;EWYpi¾Ûa¥^ðñ³œ§PÌq›×ö!§PìS¸x]çù^ù6_æŸ}±KÒz:Ô/²x”B§Ý¦Üu•ïzþýÔoú²ôUÅûâÂRµ=FKk,ø(Ö«žê¼oœNÌc±ÆÍõûG±ÆvG;_ÑK¨gm–d ¤‘çk8Ù–“à±Æ‘’uƒ¥)$Ù¾9½¯Xã6?Õ*Øôn- vÙvÃOµ ìWu©U¡VµJÐÔª¶ÞjÒ¡VÒeçüR«lî¹Õªž.µJ Ô*ÁP«zºÔ*<Ërøµç·Z…¿Áy©U½_j•@¨U‚¦Vá|\jþÍK­Â`.µª§—ZÅþµJ0Ôªž>Ôªþ\j(|«UgòZeõ»ZePjÿüÆQ«ø—…oµª×[­êí¨Uúj• ©U(u©Uðm½Ô*¶zÔ*õÈÔ*oó=ö,Í3ì¡Zæ+åç¤à–—¿¡ö‘r¿Íçßôb jÔc;îúõ6_…•MïÙÃ<'EOÛT¾/ƒGpô´M}š=Š#ü{—У>'‡þÚ©Á±¿MwRêÒ;^VÿÔÄÕ†a”°^Dï¥×ð‡G+YϘÁ”¥Á=¸Ãçf†HÛ’=‘4ôQ­úæoIý¼ç‰¸Í*[þô?uå)ñVO”ŠSìÎY·‡æ8"ù¸Î;‹'å=?i½çÇñ™Ÿ“Ãþ\Ý|Ï·qæ'Í÷ü¤ùžÇg~Nïå{~NšŸ%’ê}%¡óéµÝÖægð‰¹DoÂ=?þ–TþX<¼£ÄºjÑdxÊO¤¤Tº‰=_$‘ò^<Ö׎ÞÑŠŒ÷ÚÏ·óÏÚ™CÏÖ9×N><™‚¯Ÿµsrˆö§ÃÖÆY;ðNa`QCJ†­ ÃgíœÖ˨á=[;¢|²Âòúê0SÛƒ†ÙÈrÖÎø`xMc‹ïÇøª½Hvã;)ñ^b”úx/±j—9ñU\€(·Håü´üñßIQ7+.ø\ñý1¾ŠRíÎQ_ñìå=¥wj°·£ ŒïôÂrD/­†qh~pøÒ›%Ù‰0¼+F„“'ÞJ\Ïßî=Ö§óŸÏÆyŒï¤”ù9)ïù9ñùü‘zÏÏyŒï¤´×üøS{§Åñ1?'G}=Æwpù˜J/j°§ö¢xŒ/zá9¢—éyãòçüð¯_¾æç!òœ Þæçcï‰>åçs~òó9?ˆÛyÏO¤|ÌOì*1?–ò1?9}Îìð÷üàŒÝócøšŸÈaÔ÷§ÏùIë=?i¼çÇð5?žÃ{é5|Œã=?©ÎO!òìmèc~"ç'-×±ý=åÌЗ“òs¥¸4;¥ÞòíªÍµƒÔÒ{ÙR¿^¦“†<)6”eZí#JìšMD,ÓÒ2Í8r$—ù›íÜ'…ÛÇ÷©!é-Ýh#™vpzá9¼—^Ã{ÒRúoþÈè!ÂÉãòüîOùæåŸL|ͧü\)åc~>åÛUÛÇü¼å›ëÈÁ“Ò^ó“¢zhçøÌÏÉá ºå7.ó£?nzæ'µõšÇg~Nïå³Þ¸ü9?G¾ùü"Džo>?ò-(ÊÇÍ^óc)×ü„4;¥ÒßÏÏÑ®}~^ò-Ærð¤”÷ü˜î´ í:¨9ÞÚõÁés~L7ŽLwŽ6B»Ž^DŽ·vý9Ž÷ü„|‹ù "Džo1?où¶ÅÞ‡þÖâÉa×ßNJèoQêC[χþÖrú;ýmÕOý-RLûZù­¿E‹¡¿ÍùÖßìïD C‹Ó¾¢Ó΢Ðߢž£¾õ·qp~î+¼ä[3sÆ!ÂÉãò­á/”þþf}:ú[‹'‡óÇü\ú[”*;?Gnùü|èo6®K‹”öšŸÐ΢Åñ1?‘è5.óÚ—×àÚ™·qô7ïEä¨oýíc¯ù9òÍçç!ò„|óùùÔß¼O¡¿Ål„þvRÒçü|êo>?!·b~Þú›ëèo‘RÞóãÚY´Ø>çÇs8õ½†Àés~\ûò\;ó6Žþ潈õ­¿}Œã=?!ßb~‚‘'ä[ÌÏ-ßþíëÿì]&endstream endobj 6 0 obj 12933 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:56-07:00 2013-08-20T08:41:56-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000013229 00000 n 0000014799 00000 n 0000013170 00000 n 0000013039 00000 n 0000000015 00000 n 0000013018 00000 n 0000013293 00000 n 0000013334 00000 n 0000013363 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 14969 %%EOF ast-8.3.0/sun210_figures/gridplot.pdf0000664000175000017500000014255013004147321014331 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœœ½K®î8“-ÖÏQì¶eñ-Ž ÷\»áðŒ_ nxúæz)ÌÂõ5 åÚ:ü$Šâ3"ÖŠÿü¹þ-ý\ø?ÿ÷þúŸÿcüü·ÿû¯ëßJÿùþJ?ÿËúßÿùþ9ýüÇ¿ÿ•¯T~RJãç®ÂÿnÀ·pžÂã…ï…óE¼þspNÄ÷É*ßP¦èžϪzÖ˜ ·NmÕÿ.SeÔÇZC×}æv}ÐæSíßú*?³î¹>[šz¯Ö×o§úL[Ý%Í¡òhŸ©ï¼:x‹2ùºKÜgujÕ¿…5¾ÐÜ«S÷¨ÏêÂ5ê¹:rŽúçäz®÷ZyÄû®Îëw_÷Y_Vx=7w=«àúP ®O·yýYTÏZUY3Å7ZSå/”éCßtÕß}=·ê]êêÊ«ÓÝê«þUï‚þ³:TQ¿ÖøªøV™²p»Tf}¶ýuhºOY}i½´ÆÔklH‹ÜTŸ²^5÷ëÒ˜ZïÒ5”5lr×{•5m­1¬{â½zטŻôáq½êÓoÍ m=k¨ní9<Þó*3tOL=yÔªyåÕǾõèSsÔºÿÐxOhÿ¡ù$­!”ï‹¿½P‡[u¾ðÛ[ßôZc3ߧ׺”ï*¼ª•oö“4Ñþw/Ä ¿åIï~›˜Ïâü¹¦Ã՗ÑßîÉ2÷_yò}Ó½æ…y} üL,?V“-Ìû Ü&•YEóä·[¯ž€Y‡ÞP†ãqMcã†oê2 }Æ¿m•÷Ä åÙ?ûÛ䜳¦<ÜŸóFbÿ™—®ã[܃© ´ÛÍû +¯v˜ÄècnŸ<Ñ>]ãñnƸçÃ…Ë £9.¸l,| ã·\Sæ7êÂåŸðn9+'W`¯œÂê\‹Wf¬ÆÍe°Bv—Áj<¼bcEåÖÊœ5ËreίU:kU¹0ûf­*ÄE3Ë”q~[æYí«f\>«¾v^©„ëÙATöP½Kzbs=Ñíò;f¬T¾ŽUK3ÁµzÙZ©T7ì0M·½RadÄJuaµ×Jµ&g¬HU ¯ßv® cuòHÂî£w_Çoo0¬xS××hH#i´­‰}MÐaëñiT]Ç 9š®c'28‹/ÌU‹=eb%¹/]Çjs§.ÌUK#˜+•zÐä Öõ.\Ù†Þ…+Þ­ºa%œ—êŒr&]/XÁJ‰Yaý£ê€ÁìªVÝ9ô¬5ñ8s¬‘}]zÖú^üà1£\¾çê^œªˆ¹úivÁŠq鞘pÖöîÒ Ä•° ¬„ü-&«5E&a\¯š±¸rrÕM˜è¼*®×oÝ_«¢î ëÝ«²v‚šá0•ãzS™õÏ«ˆÊä+VË„ y­–zÖµF¼v ¬œšù¸*ªÎcrå,š5×o WƒõùñÛ®òx/íþÖlŠßβgV©Õu*VT¶ÉÀ P¹ƒ^+mM{öÕêºZe8,Œ2jóïUÕßÆ…2êÃc5ÓZæ5[O®ºš­Qgl¹€ñ-šÞ¥cGÓô¬ŽöozVÇ®¤ a´yÓ Ó±Zj ®a–±2 cÇ¡•y Ëõ[ÇŽÕ£Ýuë\Q×Çoõ\,ôëiõX]?wÍâÜIõ[«úCç®0qgÔ§V®ÞªC[Ÿ*{übŠÉëPª®væ®gp¾]ÓS>a·»Vx–¯ƒ˜ÏªX1w| ;èìñ^+±Ê`64ŸT´ÃÐX¨‰X«WuîªÖT‹•J«\á Ÿt;JÏ…«½V΂ڳàY·æ¥‚ÝÊ­oZ°«Ònb­~ømÑ Æúw@·¾{FŸÔŽ#V6ãú?¼Êå×Ù2³å5_ø>gËëuμz¬š¡“gñ›çÉ´gPí¡5;¦ªY­¢ŒÖ陹rz&ã9S¿½PF£[†UMÍL8w%TlRRÏÂ첪æçLŠjTa¶XØ3D³hBðªË£ÌZuµ¯j8£jŸ10‹gõ¬±&XnN<²×çÑ ¶ÊêM÷×,‚kí1=‚±’«×`«»ºÂ#uá©Ñ‰s¬VBŒÎTÔVß«¨‘Ig€5 q¾Âç^Í.8ì.+¬s¬G!Î¥jŒ¼õY„¹ƒ(mØAh_U'v Zå0q¥:<Ú°ƒ¸5ªð­«ÞWçU­$mkkb•kjsŒ¶Ô<š±ãh~w z&anD9Úxî-m5v‰gò~iO‰wìZ ž«3GÞj`ýý­«¿ÁT°>‚~‹o×µÂÐ^е¬},ÎÃU#;rŒÈä™ {ÓÕAT;‚¡ 6o\Nˆq͈™çgßí sòêš;~´¿wkk‡ï ËZVyOÚPnžß8$¸l£}n…õN?É{t -n#€ñ¦Æ&í5SýXl`|&_»ÍfbÏÏóê'°me4*1w¬ÿ…3CV?¼pfÈZI.̬Y«Ç…™Õ»«á·Ó¿ÅÎâòo×s‹V­ «\ÑŒN\ÕXÆ㎿­ZxϪٚÏòX»°’×áßÞØ5è·8ó4Í'W~õÉ«cå/×n‡VÝ>8“7·vnÿ;ïÝÁÅ3¼ÛŸ+¼Vã +‰üv8‡«ýù}½COÜ5¨ýwjô™µÚ7aœ·5ÿÀĘeW¢‰q%•Aý‡æ„ï;´³Àfr­Ø*ƒlL«ëÝ{eÆj­Àw8ÞÙ㫨æ´ÌÕXõÇØÜ«+Ï¢1~¯³Ò6ž-uO|£½Òþ?C¦svJIç"­´ÆXålaЪkÌUWg6­º:§qÕõ9g¡ä3fâkú skeÆ,xÝ>K¬û_cŸÒåÕ³{œ 0Ã]ÚߘÑ/Í 8l'æ³ø¥= &«äóŽMéʶNà¹Ù{hë5™`Hªÿ•OwTWæ æé=qn›t#°6“Þžx<–‰„'ßÄ5fÒ@ÂÖwp¨ìÀkeÄîÁ=^á¦[Ú;¿LK¤6~<2jßÇyHÛ>.‡Üõi÷5°¡(œ$¸çÓ qàp_x¨Ü‘±f8u$ ^¹ê4šp €cLªW«ÏXˆ¯Ÿ[»Cœ~ïÛáüsÛ‚¹¾–·ï¸ý¶#®Ÿ›ÛÏ­•s®¯pkŒ‘vk™ë͆M‹k2²%¦z5à ~ÄjºáG¬){[ýÆÏÐ*r¯ñ7’=ëg6¥­{zß³|·‹bMØÝvÃuûnÓÜúþ]OC¯éÕn‹òc[.Ì]m†®×µG¾W÷ös¬ H×ïÕæ6Ï5uaì šs«77urÌÏ25'ÌÏM–H¼—ÜR4´µê“yúi>PãÅ´UVÛDL%ÍÜW¶¯r-íÍ… á 3›¼cœ¥›> œUU‡1¼jµÄ“äõ¥-«Þ>P×ïå1·ØXñ3Ã5IDõIª÷7î«}ÆškªOÀ«l‹½ÅzMŸ%ׄèªÃšÑ¼X£«eo°× i˜cºmÞʯWlê©ešÂ8ÿhÂ`ñ ¶º¬ÎÑðHÉ&"–ŽÁ=ÌÁÚëß«´&±{} Á†Gïì ƒ{L8:`ß.‹¦ÙQ5á®~¬ùvýnðûb¯?Øñ0rd „Nçð{ÕH@œû ìv:]Üë½´(Âë7¸'Æ™B>môÍÁØX­=´À˜ZÖ¿rw ïà0ÁßšzQfðÛãì2Ø!`ƒôì¡Sëì‚åFGÔèf;£–wÒº´þ5ioR~î¤]Ó¿(·f ´ÉÍs2Úéf›¢ínöu˜¬î¢½Ìúתupý«v=3ï¼F§ØSn¶F ö˜Xäçïë_ä%„ æžZÓ×Ìê{‚í«SNžâ1ýLm/°k×æ»om V})€3êdÅKþ ñÉ~…½ÖÔîhýÿÉÞÔ×Ùfriæá¢i/²‰¦ ÖíZV ´•Y_`rQêë«Lö—¾j497cc6omÑÒOìŽpVÑ® ¶†>¸ ÷Qû7e×¥­¶íÞª]±®aŒ¦‹# g¹»÷"ØƧØè×2©«x_˜ñ:é5út7ãhi0]üÜGÎ &¤kè*nÆïÌ`­Ö 1,Ç6¹éâÂø{þxþ DÃ*˜ð,.¨«%Ž°lØ,Ý2£œx53˜IW±(ººÃšÑ¢e£Ë¶êjŽÓMrdµkûn±YOÚ}ÂÔbû3Ch_[AG?UxØ‘o£jåÉ…˜VSù{œ““®ÂŽÌž[a6ÏüˆŒäÉ|!X3_ëÄ‚ºJ5«ƒ/—ÙW+ }™_ž¤8“ÊsWI•¸,,HÃ6 ÆGÄÌÏUa>Íü\UV|Žþ…½²òDÄqˆã±R_SQWgâ·¨´mófø°…»›Êƒg¸^h¥ÄQŒ³v…™±p a \çiÖ Ÿ»ð[Tœ¿Š¾Mã4©Vh ç”*—8ë€NPع*ßP•~o¨Ê·?QÅv)T‹£=†3,Hƒ8÷0£Ó° ˆ›©ê<ªêW ׺bÀTuìKëÐÏ`iç–4IË~¡ƒVû$Ç`™-¢Å\Ö’~{xÒÏè˜×ÏpŠÌúÙÁdåæ13ÈŸÝôÛóg7ƒÍø3X\tˆ)è©22­±á­ŸÑ&¯Ÿå0ÉöK?Kq|ÅwJÚðògcûÿ9aƲq~äà…•%éÈ$ØU¶‡ _p¨,þw (Ã#ýƒÖ'AÿŒ±eCNƼ™ŽM‚i?øv}GèYÉûÔW!(|!­ †3^þvûŽÝP7wl>-”†#šZ ~E*´€K+#?¡Â¹Sà7ž¹Ç—Ÿe÷-…ì0:çÞÑ£´²ŸÍvG'Ù'gß=U«_Áª596Ù•eJc—ÑŒÝ~Î <´iˆð\HûAòb¸ŠF£^4Þò•uu„ãc3k±ÃˆÍ²„Uy#bHç«eù¬$¾2‚VÚ%úðTagEeÄ¿âjòÅÁ[éýð¼“ÃœÙ(_³{Žrx!f®,{-&—¬“.f¹,«/BA³\ª˜³âŒL¥`]øÏròDŠ›i9@ü„Ö7LOYëæßœôš•á‹š é)Ñ´Më + y1Åg…÷bâÏ^êp®O·–Ü‹Äïùãáâ‘ÝT©Õ1z}:Zôiá¿O–áˆ9i-ƒ—…Ë;ÌgvÐTD™dMÆ®Þ ±™“Æ,K ½ÿŠµÄÊ™<…õ4Ë>ˆU6ç¦e#úY* FìÌŒ%ÈÜÍbJÎZ.…P8êqˆ´íˆ15k»F§ 7·Œ—Ô® ¨ ©>!)S!œ1:Ð?"“¬:2éÑäÔ‡Î&0Mv`êáp INØZ;‚!>²MÆBò{N„î)Ìq2‚”v&;N.èÙ1†ÞjûNVÐîÚï]ÛVD’C.Ø×4ñ¥D{’CùÞö¡Të¶ %….¨üh;X[§¸wÕЗ^}têÓ©ó?ÐΘúrÀôÇ“^Îî%íŒávôR¶·É¡¢rºè:-çv»i9W˜)íR ±Å­í˜áàöæ™ãØNš,ë½B1:í°á@LeNrÞ(û–Ëá³ô8(Ô;Ë?c«ècÆŽQ3aÎ<.4‡Ë·ðäBÛ›CÛé5P˜>ãJ›œÊp÷åßr‡w)0°òT g1„Ýu¨cl^¥7ÄaÜØLi>ÎÎ!‡n—Ç…˜_2Nυþé¹PØ4Û_m®ó•èöEZÖýi{· gÈè3ˆkŠÀOšõåÞÈ8é®®Ág )ô½Ë(3BY2`šTó`xŒÂša+ðY!#2 )P.ßt„(ì˜Î626vzÐøêp”|k;¯ë<L•Ç÷uX9¶©¨þt´È,ž'ÚD»ìÌÀâP~*jÜ鹩 ³f ¤CÉ8YÕþôùh Ì Ò”-ã”NÚkeÓ+´õvm] *Ãaÿ0uNc~Ť°ïr1|‚ój!•E¦š…±#»úÁÚE±ŒÌåbƒvŽØ;8Œ¡\\Ó9K•‹›}سŽ”'÷ì`Þ9vÁj.*‡BѼÁÀLíÂÊ‘M#Ý$Bðo: ü¸2ˆÒ0Ü'j ^Õ.øŒxW»Ú36ÀödØ"ä½qQj-þ¦䘕I/É÷0Me‡›g½ž˜6«ç „›{žÁ³¦Cç±ÎÊ|ÁÑryn\ß½\j^ͺ°ÃÆÊ [ûØS‰G.,‹òšßÊe;òºTìÁÄ"6¹âàVػʆެðªçjuꬃƒ(ë#SíòrNãTì…Ù¡ØKÛF/ckE8J8ƒv?òŽ2ÝáLhC9ѱÎSïUØV up;ËQ\æåg(üt°!Üf"Î\!‡=ÅX9ì©`ÀæÐ…yÂå„èy…Â;D¾¿BäÛ+D¾¾ðµ¢n’ÔóaŠ§vÍ:_Œ¸<7…ÇyC>g{õô/q¤ÿ÷pãž,f©/¦e@+gµi‚ NÕ&ð°6Ù$UI0{Õlrٌผ9Û)Œž]²0v(Õê‘Ñwx}¦m¡™{@óŠ ëBóJ3€f,ŽÏ•¿z…¯5üÉa©zÀÍ:—~kB_Ûeè«÷o1㞟ÐÙ*ì-KQ7…ËWfv¾‹F*V0‹iCˆBÕÍð’êQŽU×N7Û9;¬|„Á…çáTÓ÷w¡CÉV›uêž;˜VðT¦I=úR‚>!Ô©ÕŒ§û…M–¡±Iåñ.E=}Ðv¥Ù‚žÆ4-e‡©Ô¼I—u~‚=ï0¨¥N«Þ°³‰–8­Ð@×®òén)ì}œ±’ƒÔ:ÉvD!`B;…[ôêÆ ŒUø w¬z÷.jŠHK<ÉÀH©8Ô{Äî&Á16P¿# YW„×”&Ôåyõ}“âûÜ;¨Ó›Ž4”wý_;y{a±ÔMW~µÅtÝWLÇÁ"6GHˆCŸ:˜`94µ‚¡BŽ¤_ÝØó)¾ŒVtP¸ÏÀ“‘ùÓ®Œ„£™YHt¬Dé?ž<é¾q˜ð¾ò´‰E×1hpËØ¥‹Ÿ86Ž±;(õDZkØ(ÜðZ_%Ü¿pШ߽¼ƒI,-î€hìû„—ÝŽ×^d æE³ ôâúfWÞfôà-´Á±GK'“5abДa,÷>ïö¶`†c'ÃÔ-.%Ó3n O $S»Qì2bñú‚ÖÐŒ(©ivá…-­9ðªL/-ìRšâK‰p© ʯ£Ó2ÌËûð"†ÊôíÄX3yE¦yO]?Óçà ÍhæNÓL&Ë‹DæKÓø%{J.ò¸ÌŒuáìÖäƾíò9Yms¡i|ËâÙÒhçM>-|Ù\eÔÓ\hÖßQ¾WÑGÈøšæŒS˜àÅs^4¶Eß·ÐŽ?¼œï%ÿW¬Ua°V§ð¿þÄضkADàwf°b±:v *Ég›aÅ>˜,c³ñ,m™ym3d‡•œ…Ý…yÕ'•á¬Oò÷Š==t|¡Ÿd˜ KF³Z—>Y„Ј™ým–({Ó½¯…­X›ùdIWJ·7ü­8„d²Ë€B#VòD'qô·˜òf›2:;06.s1^K¿…õ )˜'ã$žn3ý3£ËkJC¶ã[`ê6wŽõÉJ)açI*Å\?†ÚA#Áƒ»Ø†ô„Iűfl¦4ÊzÊ·®z8˜£åøFœ†ÝŒ_i8ˆGßóh><ñãÇ嵃¬öÃœèŽ%ŸP3>M]‹2Ùè]›²Ú¿ÂþÖ}\ÀfÆa+8 ¤n–+FU󱀑|æáèéÈk˜“¹[b9˜ Ä#r2³›ré¶b_Òæ'÷Ø€nÍ#âæÖA£ÜMóˆjŒZ±äS#‹Ö£Ÿ{C2Ð+µ!7·y:øt†ÿW2O/§í¤¤_3eGa3Vy:X5‡jĺ47ã'q¦tô7¨Éx›ÐŒGÝå/‡ªÌ{Ìq!Ï8…'Úótâ¹*^#ˆ L o%‡-ZôM툣LøXU²Éz&¡ýdŠàžRS×jmĵÔøÒ¦ÀÇhî*öÉ]ûElÉÍG1,Hvk>‰¾¸Þ ºâúIWKc‹ç*ôßàø­§9~‡AQÁn¬?rä%ØÌÄÔá°*Df4G‰¯Ú^Æ` V37SŽ×i6z"ˆKk;Ìa]¦2,|Ýç¤u¥{Aßd\ÐÅäj=ŽòžŠ2΃\-—c[÷!;mcQjšñ9cÊÅKzFj2Á¾–äŽÈ Gîª[¯œeð$J«2Â÷ìoÍ<6tíC4«Z«i²~5D´rÃ`«È®³{Ð^"T5°— 86Þ˜^*Ý ¦ EdHycãî«Üä¿–[«G-æ}´7 o,pÚ¦>òT—;|bìmY.î+(5Á}ÊkgJGVÒ¡ï-_îÕt†iÿ0é÷Ò ¬«å`±?ŒÄ¢lD²;:gúÁ´‹¤SÄ&ɬò2&¨üv#Äo•ItO²¸ü¬KõÑÞ€Þ·äcC ]%9G(m c^³Y˜“í|uxCébF~yãl[•&º,Í%A;7Ï^)|´ÛʽA6œ‘,—Ï„9‰¯ Ve6G¦Ó |o`ðá©ô"WÎzEMÁtë¸Çï+s&m+Á~ã÷½ÌzÄè4W_þoM£ ;ß|­zy³îh3ë¸U82ý÷&ˆp?6w`¶ã´[ƒàÃdô€öTaò’.&íiyæ÷¾—]Rt$Ù`Áh„·Å#˜œä ašÕ½§¢»Ì 0j=8´·q¸èÈaäDZ5i™¤:(ö“žH ˆ“÷î" ¸©¬Äožcµþ掉5EgJrÈÞÜÏpV»©4"œ”Í.wª-<7‹—âHi„Ζ¦hLå MÅùA*?7½=wÞЦ8* •Áf—"Pgx§nžU›"Y¯ÜCßmæ…)ËúŠÌÀùZ²/ÐhP8%7Ú˜ ÌQ[sHh£=×¼`_ðš|j»>ØÚGL3× ¬nŽ3n÷l} ‹ÀHÔÍðD ¯†7âå´V$Ä´ ˜®½ûSGq z÷6Ga‡rcþö>S°„‚h¶j·) (`JkíÄ-¶%¶*ˆ10•\!Ç-cŠm&Ý2šY;ÐÕù›7¾ëÃ4+Ì ª[]èéÔ‘C®Ÿ!¸Úû\ƒ{‰xsï ×,×l7¯;Þâ$ÂqÖ0¾; §z³Ÿ±o¦ÿ¯j7Íh˜Ù-ú{¿Y؃úØ£¹ÔØZˆPDF™ãØqpØ7Â÷šHÐXrt;˜hff—„hqAÖÌÙ¬jN®m.šDç<Å›kªZu5Ï»ÄÇkÇ‹xókëXÞ¢0(Þ'›¼¾úŽCåqvŽèvÆÒ_1c:j»BÇÇç b7ÕUÝ6ÓÑ1éúì÷Vå˜ù=<€«Ã›U7;r®zÇUmÌ3®êvëKH3‹§;YÚÂmªwîW}ÄUݬáªwù¸ª›áM¬_÷¬êŠ¨Š yþ«2´bê³=‡«ŒÀŠaË<š_ΘUK ]}ZÄw×ö‘á‚f£?Ù†¾W­ò±ú©¼$¨i†%mÒ6~ ZM}XÕñeµA•iGàª.ŽQlwU½‘ƒr¨0r°Úî½zΆëÝÂg‡›m£q-6—×ÍB>aÝÌ6áUWû°¡ ¸š®jè`ËßÂ[ˆ‘ÄÏt¶BÕâgÚ†\é@”5÷dnˆ¾c?ÇÚFDçÊÞøÔ Ñl)f%Ñaô`r‚9bÏ}Øã…àçgËœ±¢ºu>ï6ƒáÜ-‰A75¢å7œñ-p˜òB` ?!¢üa±~…÷•T'@4 { ÌLî;0áV¨ðåm·BKÚœ…JÖˆ£N›ä:V촎ȹ<œ£q‘a/¨Ía:Écˆ[Ûjòæ˜f¿uò€¤ ÛBŽ°DTÛ»ñ¹í»îŸíŒkž2(°ÕqŒ,L`ã°$Ø°–ÚB°HÕ ‘êx ž=£‘ý¨)'M„»KI"|Ä'?l»E@ÊØ:¨vÇbÀbU?.v2˜s…»ìÊlžú39CÉÎÎé#ÃcÜäOÈ›0Åx¹¦Ã8—*ûKo,`º,6x®ºjÝË$+U›D‡—Kšõ›åóåU–Nßä2¬RÁâ¬RÅš®Xp»Ú ˆ©íû¥Í­äÚbä‡mêà›ÙˉÎo¨ï´ù76?´OX⇺ª‰Í„©ŒñÓÕ¨2Ùð0Ø­ÎZ]3t;{2Ñ*c]éòb c)0š&뮃ÎÒ5D°jv‡_­ªw›Ì¯dŽ^ÆWï– „ ÊaU«*ÝQUkÎ ]ÐõüßõŸôW«÷{ŸC7»DKmâ-tæÅÊ`±F0K¬‚=›Bì6‰e¨lÿÁqؼ3aÒÍ@[T; ”Ëb¤hfT~Ïl=ëv²•À¤1ŽùÂ~4ôÐP‡©X°ŒS¢%"¡t!ûtFëŽÖ‹YÂ@-’pM'áek•—é›: ³d@§b“2–”Û!f7œyz0¸Pz}4éíX3XõúôYyÖÍôújuLÙYÕ–¨u3:5›mF°kê*¸_}[¤î0<5ûB3Z×μA˨®‚n¦Nš‚ေ‹v{1µ2Îê HÏ0:J32Ãá"/-õ¸Cq¹q¸$–V•nú5WëL¿&Hº6‚ºëלÍ­ÁÐRÜj(¦I7õšpX(n‡ú]v(Þ¤i9ÒnØ/±N+ö'ߌ¼|¹A+32Á¦Dž+/ÇÙ1þ1ùúö†“\m¡ †c…‹’'ÕËñ}Œ—Ôbx¿\—<Ø:Ž’Nyá3‹Ô…Ôu™3UgÆ{jâcl॥ç–ÛSuVì¤ê,Q_ŸÁÓR,¡ˆZ™'ñä¸6ÆEÊX„ƒjÄNRÁÁš7ͨšâx ×Y9ßÇÀP4ÊUüë¯,0íI¢èö<¯-&AÕQG8P•Ö`F8¨&èúü’ŽÑk5A…Ó¤(÷l- ÇBâ>2èMRÌÔè»´¸·-èÉH1¼2EWlL£°cNŽ„¥ARN,;ÖrÛ2ìAIÒDyÒ£éžQ7Yó=¥Ô²ã7kŽ¨’L‡ÍÏSñ¡º'eÌ4ð1ˆÂ¥<)¢á6©tô¨ž`)š%3ò';&Q:aÌ“¼1Íxˆ…4[Œ!p:‰•)‚$º>ýŸÁð§2Þ¢Ó÷ÀNA¹#…—`¿lEeœ\’M:c„¤’Ä°)þ\5"~0ˆ“d Èj—6,…þ•¨€äCp I]œôzE¶Š\ŠEʨ"Ó30HG³F7ƒ{tšÞ›Ë­!KÖ¶£•ô±ðI¸¼JU§K”5ø!Ì£&-Bìê±µŒ‘q”j­¤TWQáH©žºš#$f»ˆÅ®‘íE´®›ä¡Ÿ™µMZwG(•„Å–‰ì->9>w.bæåå ËÜœö±÷B¤¡Ë¿'x«urˆx±u$]¥ÚªŸµp%½Ý C†Û‰^9¨™Î²“1‘›N±2¹ç»úÞ4RìµrÔ¹õe+ÃòØ•«¶•ìW ­²ÆM¢¤È]’(V[û@ì©=JÑ'Lu!n“Ô $*@¹=i*Pû@J ÜËK‹€: ì;dµ@‰^ê“ÜÇKØ€¢ ì\’bà·hÜÄsrHϨ}4i£«,«ƒ1crJÇb§£<6Š²…GGç% :‰1R‚Ó Æ¤aT¹Ùê!Ê1@­ ¶ì«Ò…¥Aa<ÿòóýnüü…¨h’òt+-DqHÇ$o5Ñ°Ï`JÐQ*,Ò†Áñ]N±U÷Î- NžR©ÆDfÅš~98ûE9²ðÞòcÁ>©qMPcÇFKÙ= 'JLËrV͹ciÐàvP]Œ¥Ñ$m‰"|²fi½õ!í•ËÒZÝp#·XêOhtÒ®¥›Á§$ó>œ†Më,büíiBk Gív/!îÏ{ìA¬w„ýYȃÂÄe· ýDòÃÁÄ%—…€BÖµÚHµWï%pˆ³Gƒª…ßð²¹1aƒTÃYXÂá“èð±‡p„k'ÑË£÷vâи©@7íï^Mm· "ª½~° {å†ÙÕ®¾Õö¯`‚ó–.¹j‰^„µ€­Õž<ø+,ivðxàˆcßÜÅ6vc¾¼¼íé°RÚ w˜ ù8|x6‚¥`q¬pÜýZfÁ0îÜkºwŒëCƒU‡Ëa†ý§8šl½YXlŠiK«Jƒ¥b•óõˆb•ÌõBÅñë«›O ¨< }¬„ {ý)êöèÑ!<½þQnvFXï×ÂZL€X#@«åç½¥C,¿YPï z—ÉDD5„G¸DdxÀvhäžK†UçÙA_¿÷‰©*„ͨil8£öàÔe¯öì>õ">rYÁ÷nÞá1äcTIè;ÃÃécR1§2U‹˜*LØ;„»G~*ØÓàµfy[ŒW÷ì2ƒå¼: 0äʪf»7¢œdÖx)†06Pòw™³œ ‹Ö^ÇÁ–mBæ–(£p£cÝ‘Ëa8ø¢Ý1Pî“gRa^5ówµŒÉš°žÞû[_è‹(Ä»d2…‘X/ƒçVÎ\l´%’aL6Á7 ›@  É"ƒxV ±°0YõŠÉ‹ÂÊ}Å6ì)êVö»Ëv1ò¸më! (cc;NÞŠµ²—Ù¾@[Øv+ò»m«êÁïþ}ýõÀZ’6Ûž–“tk’YûJJ`+w³¶,“ÎǪµ¶ðÔW–UÇ©}&-™r”ÙœÌ6¦Å’uËYá…aö ùã9³/ªˆá-ö³B©‹RI´ç¢¥QÒ7­‹\ÈÊE‹¢Äd¨L ½= ¶Žc*—çé·´JßæâCÚ1T2EŽ[Æ•·M)Cª\7Zö\7Zó¤C‘HÊE«]×=ûæâ•«ïx¬BÞbq»ÑòæzÒÂ&5¡‹^—Ë´HbP®±ÃÝËE®¢޲ȩ}î-ßT.ÆŒ™Y®„}úí½yš…aoÕm{o>f¹î͵,ÔH®®?ù’R¹¹Èë¼ÕV Us ðÔ=É€÷»ÌÙV`,3 ÀÈž¬S.žE¥ì„®ì ¸B% mê â·äk\}gÓêëu3ï}‰³0…ŸÆÁÃ×i½ìÂ÷fí7á}Ù¯ÓD©ÿË=ZHWéÍ×™pPÏ%§¾®ß¾~˜°Mw”É‘rI÷·,ë<]þ¢PñiÙ8Ôž"¨ýg|;”÷˜ÊñݳNfìYǸ‚(R':`¿rÈh¡6ïåþ3éÁ}5+}8ËóÂqdÁáX°ààè´I$°g˜sȯùÁ‰ 8odYþ9Ÿä˜ e”]‡Ä„znÊaÿâ¼”³Ç#lRYß—ZIJüs³í¬Ðv)Þk¡ŽLö˜…WÊ$ÑgY" úý‰SØã·˜?TAê á5@"‚"K²±æy¦zJ{Žä‰Æš·©|Ïi¢k-˜%8pnÏÅ+•°ïŸBO:ÓP'Q À^/Pg¯)ÂÛ#ÔXÏBß0 ªR¿£§#‡ÂÝ‹½TuÛIéÊ5jŽT“i-œä>ÑÜàþ_`h:8á•”þ CÓÁÊÔÔþ õnŸx^1çÙ‰íp)›…ÿ„Å-½ ]§:““¸1Ý¥µ)Õª ¼=&¼"}©ïô0ô’4{O8RÅÍ‘êtAL9Ów¨¸½]4ÅFÒ:XÂÕäÕ’u ³²fÊbåfòÁ;Õ G­UË”®Vå±â9 ˜+¢ç8k£†}¾ý'³ûqªà¬*K¼¤–çÁ"Ë&ÄA¦©ó¦WLFÈûŠ<€·äàð3ËœççfZ]e¯€Ú[5w€IX–y $Ç•L^•›“<-žô‹ñ-貓i1Lö1a‘5æSÙc†Üftçœ|” X¢,ú™ïÐéU“Ló`fa–UzDÀ W%9–”<¡SÒHy*˜`˜=ù­ª«_fÙzî Sðà·à#¸I0™í«\LP$çѤۓí ï)ÄLÊÀKo´hCy‡Ù¾ÀS*læ‹íï{üšÂz,ÀáÊÍÒä Æõ–K²"³¸CA›ý˜‹™–Êéz™K*RÁ›æ`NÍ­L1ää1Ø<…Q©G¯ qò„†N­zVä€1·8» Âry^ƒ¡ì ³ôls_‡†Y¹¬šÂ2&e¼ï sC¹<×g”i&‘¾´šø\ÏõwÛuƺ:LÐ+Îfƒsè0ÁóXLæ…ù¡HÚÆÅYtH4s[Á‘âgRcÉëæ·-Ó1[T„^v§8v²–i¯ßZÙ†÷t¸2¿©#ž;Ó+ë½Ð¿ZžûH ‚µ¨Åh2×TZg=‹j‰&Í1Uævzèß¿®Ÿ÷~GOÐ ‹­ …ITÓ͈ }i_þ¾¨€-…ù ;#µ7;õ1(¦èW/H[ÄÎDJgº[+—ÊTrÖÏý&n‘¨·Òˆ*âë÷Ež{þ¢,\Vÿ"Ñ'7ƒžåØúc%Mj7šÇ ã÷/& a›ç/ ø9‘Þ¯œ)”Üyäy±wø÷Ξ¿#%›áï_wè-?1¦M§î_¦'`Våuq65Ê“ëËG&ߺE_U0`… ê¦NW‚·õ0ÍÁt¢«`k³*Sn' øU5X0å¿ë%Z–ØÌÆëŒø¿üõàa(ŸÑ$ògüžðÜÇæÏé~€Íɳ}#‡x±S)¼jÿKw¡ÇAO#:Íw7[Âx6?&ŠðHˆ*½Õï_Ô&¥àÌÜÔYµKhf¹­—žt!·]Ôá‚¿ÊÙN3Þ¿¥;¿P`}}·G†pK)þZª+³ƒPúÕþoü ºÆÍcÉKé``ÑäTX7Iu'¿OëšïS)„5\kúÖ±(á_ð{kð/’¾ÖבE¡ãølâR³nXÚR÷Àâ…ÂøÜM Я¢«©–‡‰êû_Ì¡ßиQ£{0€+óû0«ïïƒÝ30ú7Ž7a ª&‡Gâš9»srgƃõc¶Œˆ¿Š>Ï…ÒÀ<íy'ñ+}• ßÔc®t¯Mἦ~@!bñÛ~-E<¾B%v­ÉzFæ`|Sæ Œ÷m–›ì%¶ú¿žìný&å-sû«œå<º<’zõñæ×™¦5˜)œbñ>Pƈ>Îù<‹§78÷Hö*OÇ©Óf˜qæ{”]5+4ïWrYß”ÚöYé¶þäÈ¿ùæoŽù›Wþæ’¿ùãoÎø›'þ憿ùàoø›÷ýæz¿ù݇ÓýûúëùƒÕýfr¿ÙÛoÆö›¥ýff¿ÙØoö›uýfZ¿ØÕFõ›E}˜Ó¿¯¿ž?¸Ó/¾ô‡#ýæE.ô›ÿü"=¿˜Î/zó‹Óü"2ãáu§Ôq|£½åÆÁ;ùTÑF¨åQVþÆ7A»Ú»{‰S‰Ló¨Êt0nz†Ž3‡LM™ÉTÓ•Ðã¼C&§ÒøØÀˆw%.¾ëv|èØt"pç­*@7ƒ àiÊ÷WèˆP ü&tS>CiUÖ¡ŒR‚IQ$;Ù<ðûÀ3I2YÞŒñVKÒ!3Û*P"@ÚLòz`òVÁ¬=2G‹NÀz oG9‘>—>¢~mhŽúAC€HQ‚*ÐvîÄ7µ½Fº¡êÀ%÷†‡û®Û<–aõí”®]Àäxj¨Ô¸YðäŒUâÁòͦ¨¤B´>œúíß»%æÜãå¥ñ,xÏh(%6ÜíkV¾`‰ *¿æÃßSÒÚb„(ÉÔ‹×Oímµº`ŽŽ¤S»—Üì—Ú®O®xeFÝÑÅÆŽ¯œ6sWñâÏ‚(°ûç#-EÎ@ôüJI¡fG†aOòæFîÊkô’%¨Á®ÁÄ!qFÌ&ŠÃl#—±üÈÝó’V¾—¤A\L˜ì¦-(Í9›pz”ÆMºÌOÜɽäˆG|.sEñ¹Ì%•ˆd½GÌ­r…ã8¥ãù‘R ä¢æ4ä¨ÒûBÀPï 1D¾/îKTü+YˆŽ t$9máÜ&Í5ÔWšŠ8ë*6%©r€K"ÿKÂ2œ™°Jˆ%†ã¦¨ch;›ÀM£©L¡¸µ#ÿ@ŽšâàŠCpÈUe˜½¤S…õQFOœe•í%¬ezKd2³¢GqÎ5¬mÊȆWrÜ“Ñy¼óKv‰mÁ» €%#ßš ”Š%Á35"AŠ„0 Ø0ú®(àjÍåAG€p….`SFªnÈLé Wùv¤/0Ê»£ïF‹,†#Eôˆ»EBC¸z»Ói¯ªXë-ž,x‘û¼†J6RÝ™®×¢(o9äð,ÊG~ã­¹ñÚ8êoI—ŽÆÏx+f¼d2Ž6Æ[㥂q¤/^zo‘‹—²Å‘³xiX¼…+^j/‰Š—.Å£x)P¼e'^Z/‰—ªDHIüž?ž¯˜ÄKAâ%q´"Ž@ÄGâ¥þð’|xé<¼Ä^Š/‡—vÃlx«4¼¤^z /†·òÂKnᥱðVØj o …—nÂK,á­ð’E8Z/„—êÁlÿ©ƒ²ãaVýïHŒÒ7x‹¼” Ž|ÁK³à-TpÔ ^’/‚—øÀ[qàÈ ¼´Þ‚GEà%ðÖ Ø"oe€·ÀÑxÿßlÿCññúßdþÃàÑöß\ýCбòßTüÍ¿“îßLû½þpê_Dú7{þE™ß<ù79þňÓà_Ü÷Cx±Ü_Ôö7ŸýEb1×_tõGýÓ_lôýÅ;‘ÍÃüM+ÑÇ_œñQüÅSÂ_<ðùûÅø~Ѽ7·ûMè~³¸_Ôí_û´_Ìì7ûÅÁ>Äë7ÛúE±>¼ê7™úÅ >´é7WúE~³¢ßLèûùÃx~±œ?Ìæ›ùÃ`~±–?Lå;ùÃH~±?Ìã7ÛøÍ0~³Š_Lâ{øÍ~±„?Ìà7øÅþ°~ßLß7»÷Íè}³xßÌÝ7[÷ÍÐ}³rßLÜ7ûöŸý°lßÌÚ7›öÍ }³fßLÙ7;öň”›U›ŒV&Ê0§)OÆî™-ÍØ=Çì(÷ÂŽ‹9ÌÚù2N+‘oaÒfbö3cúü툻c6aÀ ö훡Û#Ù¢ºŽ½w,^°x¯¶qqÿõŽ§½¹¾®ûiŽ!¶PˆøÀŽLýpƒaŽ–¨!@¬7e¢Årì/Ƭ‹uîVÜãYÕ꽟/ÐƒÛ ‹UäñA=__²»—½¹Êƒ²Ÿs÷‚á'vÞܽf¤Ó›†GFöŽ÷‹óŒžh™P:$F=½uD¯L[Lœr‹€³§KÄðËûÎbßä®GîÒpçœ>Âßy0k{päyRÿp°+EÀÓµ÷åLnãÜ#ûö»S°;Ño=þ—g|+òsæ°H÷”`÷ܳ‹5?¨; ¼-Š£Vþ—/'<íì“á¸Ño)n-€T"¥â´oÏv× zç‡[θn/=ˆ'JV™(÷¬ wÉm>9—gb¦ªÔŒþæ¨3ëäK?¾·òYj%aÆËì292ZJŸ""Øß\÷ÑÂô›))ã|Æ)?yáƒ!Y!gþ¤äÏ™fX¯ˆÎ|£seG˧X*MΪscž)¯x3H¶L±ã™_î=úÏ´úÌt¤]Ù‘©™†Ïimô“ˆ·Ï;•æ—Ã(½½2çÈu•}ât XÈs¬Ø4«§½ÖçÐ1yiÀ‘cUW.NoèV2á–‹‰˜ddM[¼Ãxi (šVå˜qi¼3ìŠ|X;?WŒšµÌ +@›¨·6Yš6㲿dç˜Cˆ—éÓÜ3eçÑ“s²{[õÒ8¨3¢x)„“›oPøUß”±iבÐÉÎë‡éÌ9C¿Z ™¹Dõ^ÌGf™h¦un8&Õ*Jv¾§”}ÎÎ3øÖ\ü^ÓËùG3UÞ% ’#çœ}É$—É|¥Ú¿µð¼«Â6;"ã…œf—¼óåõ ±+jÓ»°"¦"§‚‚¬ #é5t{wΣš;™ôÎÁ÷Ö’  sÙÜlF#D“·öVëŒa°ô·ùÚÇ¿5)2˨ny³ö32¼gçû£{/i'B·•"¹3²àdëÔ¼µ-`ܱ››É@Ÿ•AKv‘ñ`’eDgÀ©•˜.[ã棑Áö· Û_}˜J ¢NÓ1œ-]ÞúNûJ½ôl}ºÚþŽ_=:WRo|ÉîƒÿÌÇÉœˆÅ'ëY‰ès6·›],´y“ë'1ÓùžÛÙÿ¯¿è÷´$ç²3/1àÅÙ™² XØNyuN%1¾^Of ¥¾à>`;¦Ƥ|‰µJ``sŒb·Ýî½Í½‚­N„óŽÝþ*Ð <¢§M–Ì]sú‡3öÐÒ#.˜¾ôÈÛ¸€±Žxÿ™”¡WãC1Ñ2C•OíDÅ¢aͺeºüÄ}"Îï~¢Î¸SÐŽ, Èʇèmý¹ùÏ–%‡íÃY"Oƒí•ùV™ùPnsf›œŠÒ†+:+“9=¾Y»KúXwVÃwÖÁëguåŸÿø÷MiBD‡©KŽG:í1)Hä%“šfd=0¾÷¯ý×c¬C˜èE=™‚ÄCØõÂÓ¿Ž¿žÀýó/ýõ/¢ÙΤ€nQž¤¬húÓµí¿ž1ê÷õ×þ—ûó/÷ù©­êÞµ¿E–vLÕù+êÚ ç¯ó//VÂf„gº^í‹¿žçþ:NÌ*šV®·ýë¢ ôÏŸÿbŠ!ÿ墘©NĦ7QLô5*ÙSˆÀwþzOSDL¦u.&OŽ»½TM;ÆŒ %Æâ¯'(ŠE¿-1ü¦%šV)ZâupwÏÝ=AR4Á‹ÄÄ ·›L&b¢¯÷ÈdĸküõN¦)Þ!wtÄtpõ·óý‡owÅòä»sW¥þÓÓæ}ê§hžß×_®“3-ð|˜á›æËôPbSWÁ}™6Çl%öã_O`“ly Rhy‘ú¨¸d‚衬Aê‹»Æ_O`SüÆÞà³yƒ/œ®Ýã,úÄž˜“)¢Ä)žÀ£ÙÛ½ý56™XÛë|~­Ùë;1 …Á¹A3ÖˆýÖ¢ë®44½0ï•ß×_¸ÓS»mDLN/¬¯B¨Gc¹™y°~KyC“ ëÞÆ ·˜òU©v Uº¢Fñ×Ø”kQœõdF?¹e„õdÆJSœaºt ‹úlô¡J¦>×=Ÿø¯'pwÛ{ÆÚ¥¼ú.w”ÊÊ5ôg)‘DwM|„0öìÇ|8»½±ð&·we›r°79ç¯G­œ“g ¬‚Fž#"_+g÷WÑVßÖ;¾º£ Ù}Ø¿ET¢çG³—¨ÚZÞšsÛ½ÕáëAŒ-ç×A’}ÝIÓ¤HÏ/Å¿îÄí4Ô†˜(f× þ ›BšŽ°(#”C€Ø”Ó:W¤®:^*°c\÷_Ï_Âm~ 0ðÊdÚípqúÂþí GDˆ”Vk3®Ë#€ñ`ž3„£Æ_O`dFkiWCÏ1ûN9w¢~¸ï´ÉÊŒ?íåà6ãNüþÿÅÆ~£œ½¢ˆÒœ^¸GËüAi¾^¸F /<¢åž—háëOZò«‡1‰“{X‡ qÙ=ÌÂ…& ÛÜ+|EÛ„b‘”û §èa‡È|¿ÈΟQ´LG-¯m´2Ö¯¸†Dam¨2¶¡yØö7NÑ“r Y`PíÎÑ“r9=)—èaŸafDø>jDŽ%ˆíúdzj;c˜žÚÂÃJUmçǵ…ºé‘Qû÷õ×c׉MÜ–²¹^XO`L©–Œ ÷MÝÙ§˜Cå…Õ u¯bhHâÛUTB£0¤rÒ G­ã/Ôšª†^·(kèþóÂþ©šþE®áŽšÁu=ßÿ~A¼k˜kÝo‘ÝøǛfGÛ rmé…[´X×nÎAÔÍ¢ç†Ø7jêq!l‡é¾)¾§©¿î1ÙüÒãz#l×Y¿÷î1Æ5;P D¾O`«lp”R ·RÿÙ^¥Ûq³†ò!Òµ[˜úõÛ“Î%H~ÚP¿¥Þ¢¥CIœ”ò>Ûk+àse©$ù«S‹ÎŸ=;:ß=w+ýâþû¯‘O[\¥Œ(4GÀ“zÛ1ŠPwM«RÛñ^[@nÁn'mÝ9BVç þÛþã ¹9»ƒ“3%S„ãŽüˆPÓ *>ôèf¯ú'Ä­©W?”.‰¡î›†“1Ó[}[jƃcW(÷²k”COtwœ<žÝ]VŠ-jE·ž«eõ ÖËbò†;®qŽªeg:¦'Ýþšý ÷7 Â">JîöKSx ]ñY˜g×ß%;æ_ÚÆÚ8àÓX¿ã¼½ž¶z%Ä´9£¤qúRÒ¥’³Ï0PÐiY(7hÿ÷jûd÷wœ4¤¹€z„×ñhÿñÈ·.é–ŒÉm\=Å-ÈãB†H‡)êŽ}ÝzÀtø;‰}ôïý¼Œ¨~?0;pIâvÎÃòÕí´ÇTnµÇAq;ùass0%6ºƒ0};Oõþˆ»‘™RÙ­œ·ÍlÙ¶s? {$Ë¡„ËM­4I‡X¡±™è_û-ç G-¨,©J€X᡺ú#™m'œ#ÒTgs>6àè'ÈYŠ’áE±Q2•~v}DãŽZøG‘©Ã1¨ë‹¿äŒÃ! «—G, ¹’À}TïÝw¦PŽoÍšûÞÙ9¥@!Þ=[¡“ëËà‹áÀ‡ør»×?ï&Ì#D§¶Œ‘q+f‡¦¡2–÷QøÅpOté•hÉpïQzÅán éMñ–濯oª1„ž:"$b5lDD€M£àÄ0«2è‘ i´õ€Üé!Hºî«¹£“·£0‡ÕõF §ø&¡GÏ»g(™"d´¯<Ê0‘QKÏ[KÒp²ûæ¾3Ci|ë?¥œJÜ1…¢’"OâùTorôL®úþt»Ù˜9Êí–Ý•WâN¹çïÔlêw´]øZ«âуÖãˆsóåÑvûe¿æ~3Õ ñÜÔîß‘íÞqàˆP7D.8 Ë–øSºC(ÍéNËøò+üÇóU¤EV2Çê€ûåPµè{Ð Jf88D0Çæ4ä\sHÍzž#sÜ ÷ó˜RËÌÀ ¯±n-™=ÜñÌìY€¡9š)øÔì µôŸ›=Ýìϸ›“ÑgnO®ÕnÐ Ô0¦ÜLdì_9•û·ª…ÁΛ)ø€\/EI€tà œõ"^°u Ò`6Ýï?žv$Oûñºƒš—#° 6%Í‘AÃì´Œø_ÇÜ"vÈó>b^àö*!™â‹ÔíÃf…sïe/´íˆ«)Ðèöï`4HIXL fï1<É)óâ-B^6œ[?z$S©1å-\#mPOC>ÆH\týlŠFµºQ¢öÙ›dÆJxïL ÂÀq=Þ GT§„7쌱º1ÖÒâ5ž¡È§hŸð&Ù‡¼Šc.ø.Ù:ÓûÓYÖC™¨_RDAÔM[pûôÅîP#r‚ôiÓ8p5¯ãƒ0ujÒMÐL¡FʤªÄ4š†È©Jƒªù +ÚÒÿÑc>×qL»‡»Òa2~1f›ó›e²)ÜwÇkîÉCê0"5ŸQðzSÔqÆ fŸn˜I¢Ž|E 3ò.!ÀÈ·ÌwœFˆ1¢ÖH#.ƒ>¨T>°V²µ†Ü¬†/eu¤‡ÐÔ‚Ä+‚Îíá?EPÍkU:$ÙïÈïN— Ëæç©m1ä#_êŒÔ~Hž’Ãaœ–âŽøÇñ9Ù6 ÊÅl\BMKñ^"‚óY4ýëõQwc1xÞ­•m×@s9š‰íµñ¸$ìâs$›ì`¿l&3Öâ«ËÙâôÖ¼Ï`Úªž%Ò­š™åÄ}ü€eKå×nÚ.#ØlÒ@pˆ-°™n8¶¬¾;Ê®&®gž§¢Ù©5QS  ±ª·Ð±ae-ŒÆÚL‘´;ê›m bÈóQãl»ª|0î™w¥ó ÊMJYò8W¯Ó I€ŠÒy„ïlX7ùÝÐU_1 ¸ËªìÕ‚‰àž ³)Ï¿çGP6ÂÍa›bô]š<϶öRéHRsçkì·¤3ǯ™MÀ{ZÀŽ/šmÆ›Œ'˜±ÉaàŽr¥Æ=Ý—(>è.–®v­{3»‹¥—lœE„m¶ˆsøÊ Ñvið²7WUÁ•˜°4Š·µá0;\yšu¦B0׆=²MGØÕ¤"`HDÙb]Øï]ÓÙ5—*/:ãsë/Œ¡Wጡ õ=÷4!–3†¦[Tù`ÜS“óþÀ’¯ZSa•*›Rn¨>H/ãj‚¢l%ᔬ?æ®!¦%Òs€h°Dp(áØr.:½ ¦Ÿ{b¤!Ò¢ýGŠSö(cñÅÓìûu¨(î÷)ö¼JO^ûŠ½s…r“![éGSÒ™FrzaÜS; &xœñŽó਩j„\) Á$9Ú^!„ÔˆÌæù;Ša|íW²«J–HÝ‘tû…8°a·ÖÀþÈ»BLÜà»Q¥b—"êdeLVê`4Q.Q­b§%êu0›ýŽš;9QµƒñÛˆ‚¿ã3¡vë‡U‡vãDæ˜Õ¼ö¿!ìÃî·L-Ãlüïù÷¨Í d©lÉ" Œß‰oâ/µïÁX!ߤةŠ»lܶ–(ï³[2Zx¿•HýJV%å;»añRÅîY¼ÕÁ®ï”(¶À½/B§ìØ$i_ë!‚t6,¡,€ÄyÒÎL]ð¤è¹¦!¨ó¿a·dÄþ(»®^WÃJ¬¬‡`Y‘ƒ·B+«RìJF]F»èHƒÚGó£:SѵE…ÜŽ”b”ox¶.·°Ô´0#xmÃbÍi 8‹Q¯vgÖ’2‚s¹é÷ó3éó°¿–eØ7SÇöŽ‡9ÇùÔƒ{èÛò¹ÅÎôÝÚb°¬EµÊ6‰ 4(_“Bõ¡¢Õ+QC0g«^üÑZ¹Z÷â"™/2¢LqœÎ~ñ]¤º6Å‘:¨NqêSÙƒ mOÐÖž«*Mæ ÈaErªuÞpÄ/ ‘pJö‹ÉÊÄJpí;33Šo])„{GáæÅ‘EøÏÆHñejÜÅN|—x€ñ¯ ±×!§¨9õÙ„R¦&ÓÈ‘$èí6çQÛon‡P¥¸ŸÃ–.6½ÌI¸cq˜ny0^dî›úe¥ ,-Ì—úN–4ÌùÃôzXV'pÛ¯yn—O¯û)RJ7T•îhRo¹1¯—}S½ îÊŒiÒü-·ó¾ýž?+3;A/îÜq`¼ÆÛùÏ=DýÒMDÔ]6Fs[*¹ßç­âmO-Ñ•Ÿ×]ù/8˜—ál -rÑá„è u88*úi¿ëßo‰2É:Ôø©x‹ºc²\ ”lRH`î×)ˆû‰æ08{‚«x~ˆØ´ø¥âÔôÓdáüöŸ›Îc]ƒs=îOà¿({^ç?¬A ¸±ÓéN¤7võÓë–ü!¸zñKñöôÓäìÓj«{ÿø<¶ìÇF Îußu?ÿ yü¢¼~Áëñ‹òùEkÑ ’F–AÌéN"ˆþ¤Ž»ŸºµøK¿êWãoýÊ» úuªû±­ãõ¸kk¯Æ€Æ}ö2w ØË"IâÕwõS=·äS.û—îü©; /êû±¥ÆÐUÓƒf„HÞØ÷€‰*žzhð—ü©‡Fëghìjú×9fŽ¨¯ƒtâéÙÿ!åuRP2 £a>³ïá97ñlÁ»xám<»ð>ç×¼ñyÇÏ¿@S[k ssD.M¦Õäëâ„°á“9Ž~§xÓs;­-ºŸ¦aÝÐ’·¼ãÆ÷žÎyO¿â~uÝ[F.Þ ö[ÆHš,^2TL=¿æ¾WlÞÏ oè…Žw<¸Ä¨{¦HfR_k z·6Nä_íl§±`8'…G3ox{ ’Píêvñï;{Ä[{gÀ{{÷À›{WÁ»|Ç.„÷÷‚}Ú@O¨3ØK‹í fïÿsãåFÙû §ƒ•¨3ÒâJì,xWË2Þè±ÐÞª¿\oèXƒslY¡Ý$£œÓ§Jè!Î/¹2§°…"ša¡´Ù\kËlÖúvR§Y'víüÃç–ñ®š?Ì…ÛXg´Ií…GìàY­ÈVÚnÌNÉ“ÀiK=™é~Ùù˜÷T:|ÐÍÝ™_I€CûmÁ~ò·ÇN FDÎ'PÊÛàÏÚá·Óò¹Ñ TëvÛ§“@¶”Û‡¤‰ ÇO$'[RŽ#²§6ìv2%~#yÜTÃMżÍÒÈŸ¶kÉÎC*[o³¸œL»š»´}x,‰‹È•—‰?Ø~œó—_ÓÞ¾çÁ#¼C|ÓH“D†òÆ=¼L|Y{Ÿø¶ooß×Ó?T#H+5({ÍåSbPÿ6 1Rrp¬\Œ‰©¹º9„K™nÃn×*5'›¦æ›³¢”çn‹]MûYO»'YQ»-YÓƒs¸9YW»?YY»EYÛÈ)EêëÆ=Ü«¬pä "ÍvãnZÖÙÎÃÓ%Pk°å¿OP~Ì\BìT0ãµSÒ†Óáû3ñ¶Pwfüˆhò郞&G?F²¼ÿ»Îv£áๅc£šqo‡`(Í–”ÎÇöíOö¶køþŽ Ÿ2àˆ¸2(N@eøè÷jûñÉ“´Ð rû³mBè„ÌÐg„œîÁÛ#6…Çô¹CS&¥oY?„¥°" ÊêwÁ§S Ʋc@„S´ F¨Q¸õl:Ÿ"p@òS€E|+Õ+9 &jW›D®VÄ•ì?ôŽ=!L!)“±3Üþò°G\ˤ²‹>6š¬K¿e˜$Í°ïP²aC‚¢o”ì‰ÝGþx©µñëÕïç t9& Ì0…„Ö-Í_†ž£x0𻆞(; ¤#Å‚Š¤P°{F$ÞD` 6EINŠ€#ÇIÑU¤5)芬&Åb‘Ô¤-ågmQt)+¬ ãò¤×Ï0$å°L;XŒd8Å)¹œò]2‰.™vïˆOÛ]ƒ•ÓÑŽøЊ‡¼/Éê2\rüùÂ-âbQ}…,¢ÊŠcgGÁw Á~0|‰ê*6µUÀ$øYŠ¢D­E¼%X ÂŒºFLz·±‰ä)d‘Ô!E2’Qt;éNŠ¸G2ÇI☢$¥¤\) ¡3Ü¡–$„)“|°eܨ%îx+"òr[:Ún÷þ°D0E ¾™ -‡†öp’a ¦’ÂŽÑ¿ÝPŽ¯Ã{§?ÿe8ïKsŒ0ZGÃ`» gÍI1[IqÇh™áì9·#”£ÖñGk“f3œx¥EP0‰5Ùdf„“V£Èb2£†ÓëôˆC&j8ç+¶wÿñ8¯§Û§EX0)[·³¥Ì"&ÁK±ÅÊclxG$òîSxÈØáó¨—¢ÔQ-Ũƒ¼£P|PwŸj(hµP$?(K ï¿™+ƒO\ÏU8v|>oû\Å£ƒÉ¢ht4©¢ìÑ¢Š±‡Eöƒ€þó¯]븣Ù¤ÇøÏ"TÛôïÆŒp}Rcâ %‚ûÇ;2~™N®íÜAõä6)ÖžÔ&…à3 ®"óIëRÀ>Y]Šã¿O.7ª‘*t|w/>º=e0' ¾1*«Ž2Žz¨8ú ˆ8º'ê&¦ ª¦§¦ld•zmÆΘ…O.—™XbÀð)$Àð)ä¿ð)ešƒW§©H==êw4íȼ—ä{šêbÖK÷]MŒ!çE#“d% Wr•‚w²ÿP3™›BÚ’†>YKšHZÁ…œ%uRR–ÔsÉRRw&-Kä²²Üñ1gz4DŸc-®i™ï~ jN ë Šæol4Q7qÙP5 UPk4”©™Ïñ_ÏÿDlỈš_©ÄÏùÌ‘ÑÀ;Ñ´×\Ž×²n  iUˆ7‰§˜ÿ×IáS’c2øØUHqÑJJ†‹–¬Aòbo~–Ild&iÅ#1I "yIÁ Û<§ÛÑ”2²•´ö’¬$¹JZHUÒâ@¦’V •Dn#«»G_‡P…§Š "6 Ñh'BÄtídP moú&©‚"$æj| Þ»NÓ¡Á*Ñv­ªí$U{L!>ym…´G¯DW´­H¨hZmj@ÒN¡Û‰§³‰­ñNQ“sImÑ&œb´Ú£“Ø¢»awEÌ%%ÃEg¦:Õö›”%RÉXO•„%m[;éŠ%»>›î¹ÿP‹›Jæ’ö±‚µ¸ÑÍ+%…©»‰7 •Ô,m\wŸÕ[góÉ…X„RîÈqmÓã ýù›  ƒ{£Ãª©³Y/‘•ìÌÀéÑŒˆ›/´ˆYh&±À Òù ¸ÑÊâ£éuÚ&Ò^“†Hçà°·ÜQÎÿ¼jÑ^Z´Füñðvf›3ͱ ‚½¸6¦š“#¹L²pàeÌ3ÇšfNR“ß‚êÄ%Ǽ‹VÞÜ”f˜“Û$‚9©M:~“³ñýÇðöÇ4·œL.#wgÿ£®aù p…¤^‘ MB¼éÒxˆ F0È\^’ DDl0}d$ÄKÈ,ˆ7“Q\!IV©^¢•Ö uhem™Å"à²ÈL+ÄÛÛ"hY)[@=YVÃ?ooa’ed¡&W¦î›ZŒÂ0`é rfd¥@³¬±$>…ÒÃþã xûÍ-A:”´#Ȇ’¹•Ô.™ 9ÐÄÖ¥ ÇKVI¦÷•Ù’l/3 ›¿¥¥0HûjþÂó-PX¢7°³Y‡ Ár"rC(×ò:” –ñZPÍßíÏ;·­¦Ó(!ÅéÏ·£à_ u´’µŒåÉiT°â 7dkR׆ÓÞÝ":†|q¸·£ ÓÞ:)mh¤lßá2ܨ½ÃÅùo¥­‹D2ü§äòÈÚB*‡¥nN;²9døȃHŠ’üŠ†Ý¯eÉ’Èäº4lnëå ¹,—Cb™œnä•ÉgÈ›µ-•ƒ³ulöêÖº!×L.Á;»X0‡4ùfgrØ"-Šà ^0d‘´¥ÃšÒyŽù¦èÔ¦°70†ì”XÒ¼AU%î† Y·øª«E 2½,AfÈ·f† nM1ê­?&È­_£Z÷ƒ`Y|LŸü$KÕ¹•ÇÙ—+•¹ª´TXEJ )ê:;öߊXr®R5®Þ.B‰1‰?>ÈrcÌncÞ\Uk‘I¥°)A  á±›3§¸!Ãéæ²Ê˜ô¹Õ3ÙÊXX7C]yõ þñî–#ÏNa-†Ý=Ãzb$Ü)ŽÄ°¹gX”ŒÌ;…pFÏØÊV•2q”d4Äó˜Ò]rŽ•q Â,ßË Rï5äó°TH»£ÞÒ½‚Ü#€àfá^ðÞ¶n/f Šëz¿þ©ˆ•—I™“d¯ ÷Lû‡²^/o¹^Aumæម<@iõ ªEq,—R/©šêt„ÚþãaCZ¥—N‰ôJ£—™$ÑKV§z oLëó’Þ)y^Cýl†8/9Ÿ¡¨»ÿx µ˜Õb¼d‚J£W°E¯ÛŠ® *Z†]PMqI¸c–·²» 1>Û?ÞCjçsn!w,ÀÖq´Œ;•Ñ¥â>óq' ÷øãù ‰!BÁSµÜ ¥Bü’o?IêC¼=þX·c~;I·3ž”Û %KË„yzJÏëM·j;'GG}™v¤g³z;(ùß¿ÝÃrí㨵#ÖŽ{X«}Ô-ÕNJíñÇC:íÌÙ$™v¦r’z.¡DÚï´5Ú)²íñÇc(ö—>;³GI¨œPÊ×óˆ³Ãþ¶µÙãÇPÊì‘—0;ö<ÖeW^¤è>Ve'™V¢ì‚vì?CÍJ̹¤%”©˜rÛP³RÌ'jÿ“Æ">çß®ŸìÌ£ï‚Uݹ-#µEüñ:±E›;¯äÌÖBPF½ýÇcØß×û¹.=qd>sB $•q> æÖ‹tñÇcXß×ë¹~¿¯ßûºYàAÎcÑúNcAY,â×pç°ˆ?öõMáh ç¯`¶·H_<g4¾sWô“º¢¿óS¼FÓûúþ¥´zEde%çmȘ”—!fâÓ"=žOáþ*#\ºðó-c<^e¾øù–!®!ÙÿŽY~žžÄåÔaã!ü|Ë‹dª2àÐ…%XbË2²Là[øù–Ž6¹ÿŽY>íëÄÍBå~á)ü|Ë—qÊüëWûº°ˆ–*c ›ðó-#lÑD–ù³|Ù×…ïW™À{ø”!î¯$½âGJÑq]Ø)Y&p~¾e„E¥T™?ðó-cœ_e¾ø±~²¯—W™/~$¼º¯ ×Wàÿíçÿú+ýü7jJÿSÖ–“é{ŒÔ²ûªóÿñ?ýõ¿®#KÑüû_Jielø="õì­½A?Ø"¥“»]çvÄšÌ×<½8Ý—ë”a/vËÕc0ŽëYÃjUý%‘8tó4™Æ²¹Ö3N€Ë”™í•ª3’ä^Ìã;1y®žÀ>gmo8ÚÑ'¹†}ÑÉŽqp"4¦ éV˜Cs‡âyãí•0:Äx£þ~›©¤º|Œ AÜcD0¯M$3½ÎÌ5v;6Ï´õ¤fcBØHÔË^)‘¦Í#‡‹Kñ»vÙ¶ÚI{™`4¤Jµ&ß{áüÏ¿˜¥ØÁè0É8ôYÐ4£ràEøüQ`Dð´ 2p}ªì} ,hRÌý‚ðù L§€¡¢¶ŸoÂ| ^„,;÷UÂr lŽ•ìòŸ„õ0l„¤‡]qU°†™ðù지¡®>Ÿ‚ã„´„øcíJqUð> áó) 8OÃLȲ9®:Ú6¼ŸOÁt ˜³5ŸOÁ| ÖˆøÇØ÷UÁr fÂçS@°ž‚u>Ÿ‚í0O1²Ëß °Ÿ†ºú| ŽSÀ0>¢úªà} ’]pŸ²÷);OÍkן‚ó0L„ϧ¡Â„YÀ5ËúnÒUÁt vÂçS@0Ÿ†…ðù,§€¡8,»é‚õ½1ᢾ ¶SÀ°²lŽ«‚ý0,?ÚP¼ ŽSÀð²²×»€à} BäKÔjôG_œ§€¡Hϧ¡HL,PWY¶ÆUÁt ^„ϧ€`>¡¯Wò)›OÙr 6B–mqU°ž†™ðùl§€áEȲ=® öS@°K#íù§€aûÑ!ç]@ð> 3!Ën6à<!Væ);wY±$X  ®>Ÿ‚é0¬„,{ÇUÁ| fÂçS@°œ‚X’ª¿ÛŒ«‚õ0„ϧ€`; %0÷| öSÀ0ýÈú—0çøªà8±$ÕqÊŽSö> û,O4#úªà< k0˜^Ûµ ÔÕçS@0‚¤ö軤«‚ù0”Øâó) XNÃJȲ%® ÖSÀ0ý(è]@°¦+߄ϧ€`? EPbÙWÇ)`XŸOÁû0”zäó) 8OA,IÍß­ÅUBq«X `'|>Ó)`XYv_̧€áEø| –S@tY,I½œ²å”­§€a#dÙWÛ)`XŸOÁ~ lZuëþnw\§€à­«Ï§€à} 6ÂçS@pž†™eg\%'ž^„ϧ€`:±$‰Ä‰uÐWó)°éèæð½ –SÀ0>Ÿ‚õ0ÔU– e[Ãv bI’ªÊ«€`? ¥û| ŽSÀ0ZÄWïS@«÷){Ÿ²ó0„,[â*¡(¯,°>Ÿ‚é0”¬ïó) ˜OA,IG›ÅWË)`8Ì%|¬§À²l‹«‚ã0¼ Y¶ÇUÁy | ËŽ¸J(S œ„ϧ€àyyC(–N·C° Û)`˜YvÆUÁq ŒÝÔ>û×+®R—úº¢À†…ðùL§Àº¾¾*˜O]£ûŒ®Ïè„åø@÷_¬§Àzûª`; ÛO÷$=ŸÑ û)ð^[|UpœèuÞWïSÀ°z¿ã«‚óø@ï'}•0]»@ÚôûŒ:¡Ïè„éø@Ÿq|U0Ÿ賞¯ –SÀð&ô¹»Ÿ3ºH¥.ð¶ô8£¶S ÅtÕ㌞ãª`?>Ðv9_§ÀÚ>é«‚÷)àéõ"|¤yä«‚óø@–Íq•PGp˜Qù|r'L§À²ìˆ«‚ùø@–­qU°œ%–…”Ï}U°žˆ²`7úOØN|¤%å«‚ý0,?rÚлૂãø@–MqUð>îXB»Îèˆ,õUÁy | Ëö¸Jh¡‘^ÿ„,[âª`: !˦¸*˜ODYŒ€b '`9 ;!Ëö¸*XOdÙÈEaØNdÙWû)°·3]gôÊ̶pŽSàY¶ÅUÁû0¼ Y¶ÄUÁy | Ë^q•ÐâG(ð…([öUÁt NB–mqU0ŸȲ%® –SàYöŠ«‚õØ{Ï®3:Â}|U°Ȳ-® öSÀ0²lŽ«‚ãø@–½âªà} | Êb¡ª¶pÎSÀ0²l‹«„ÖšB/dÙ}U0†…e¯¸*˜ODY,TÍNÀr | ËÖ¸*XOC]eÙWÛ)ð¬‹3® öSÀ°²ìˆ«‚ãø@–ŒB†÷)ð,›ãªà< •“e±PùäÎôD×.ð…,»¯ ¦SàY¶ÆUÁ| ìcŸœð áZ¾*XNDÙÍÈ7¬§€áMȲ=® ¶SàY¶ÆUÁ~ | ˦¸*8NÃIˆ²}_¼OdÙWç)à3úõ£x)F(ú*á9˜ÿY6ÅUÁt | Êb¡¶pÞ–KpÃDȲ¡§`XNdÙWë)`˜º Û¾*ØNDY,TÃNÀ~ | ˶¸*8NÃBȲ%® Þ§À²ìWç)ð(‹…ÊÒŠ€>˜£@ÀJȲ-® ¦SàY6|æSÀ°²ìWË)ð(‹…Ê’„õø@–ÝWÛ)`Ø Y6ÇUÁ~ | Ë^qUpœ†ƒeÓˆ«‚÷)ð,Ûâªà<>es\%´qJe‘‚mÚ ˜NdÙWó)`¨Œ,y Ë)ð,›ãª`=>p•%!®ÎüpÛ2/B–ç*`?>eë¹Z-*â€)«Ç¿Í°ZTæºx™w\±ä_)FŠ£¼%§gÎGˆã…ùÏ·^¶§¶ÞÛo †wòeë°a#i‡r&•ý³~b lH…ãÍ1&=ÎÓ¿š¼m†§S[ÍÅé?Ý+ŸhaO|W[èÐ}m¡£KÂJ,יÒ¯ÎØ5ƒ¸á ' ¯«y/zH«w3c·¯wãXùÌ×aæ‚vŸç×WÁE„K‰_…ÁŒ‰ÍkˆŸº€ ¯>jŠ«‚å ¬]ðù¬§€à%ø| ¶S€°4ÁçS@°Ÿ‚—àó) 8NÂl.Þó) xŸ‚— Ê–}Upž„© >Ÿ„<©€ bþJï‚鬂ϧ€`>(oCöaͧl>eË) X*pùªa=ÉR«õ”­§l;‹àó.`ØOÂq >ï†ã,‚Ï»€á} ’2WõÝZ\5œ§€`|Þ%øÅ‚ˆDLíÚeÛuʦS@0 >ï†ù ¬Cðy0,§€`v(äÒ|Õ°žø¼ ÎSàQvÄUAή*`XŸwÃz | ÊÞqÕ°‚Uðy0œ§À¢ìŒ«ÿ/[÷r%;$ízÞR¤µˆ; Á Ôhè?=næCô?©z–ïÎ[dIÁqû Èn Èvƒ‡çæ„ŸOÉ~°ƒ[p~¼Üvo;NÉtƒ·í ^ž6ù”¬7¨þ´±_rrÞàái³OÁ ç·d¹ÁÃÓŸ’íà·ä¼ÁÃm7PåäFmÏ+2¶o7 ë ž¶ù”ì7¸5 × ž¶ûÄý(- 3¸5 ë n»{,§d¿XÀ­ˆ Š/O;}Jæ€Üí·Ýâ–SrÜlàÖÄÆÇ‚—羸ŸOÉ|°ƒ[²Ýàá¶[ïrJŽ€Ü€+Eðò´Ù§d¹Èo È~ƒ‡¸?0§ä¼¸À­±`ãs‚ž¶ú”,70ž=…ò•Û–ÛŽ<¼Üv3gNÉv°‚[rÞàái—OAܼÓ²[²ÜàáƧ9v·›€ÜOáž7yhuò1mŠHÈî§p×›<ܸ;6Çî~“8’à i´p¯›<´ºø˜Æá“%ä÷S¸ëMZ]}ì71ž}‡‚Ó8R¸×MZÝ|LÛj2û)Üí&­Ž[¸ÇMÀ ±a²äåÆÝÍ9v—›€ÜOán7yhõô±{Þ¬à~ ?–¼ÜOáÎ7y¿'3ßßÜ Ø@n˜%žpCbùü)ÙnðÛxLÉ~ƒ‡ÜÔ7xÈcLÉyƒ‡<ÎÔ\7;ÈcyLAZð’kg˜’éÿµmø”Ì7xxÚìS²ÜàáÆÊ"¦d½8þøê{{1*¦d»ÁÃs+üîÓ寯àá¶Û§sJŽ<ÜvvNÉyƒ‡§M>%× À n» <§F¼ó^|üò´ŸOÉtƒ‡ÿÚ¯ù”Ì7xxÚϧd¹ÁÃm7Ã÷)Xo /Ó^ýûOÇÕÒìŽú²¶uönù&xòÜ`g °lh'nmû—F쀦û«•xiÛà(žayÜ4ï¡Ù²#:üâ6Jç§v!èái{,/g¾B‹Ý`»'ß%!v™Ž âï»ø¶ßÙcµwv”†ãR;ÐÆ.Gµcc|¶Sûøž+>¹Y¦Òù°Xuî‰Ç/Ǿ7ü¡/Û÷ÍþsÎ|ªÈþ½ÅÏ oy`ûöã¶}6,ÕÛƒ‚#»ßãl±ßØcÇÒ–^p{';:Æ=ðDˆut›b©ÓöG{œ†(|ƒå*ûFIÛŒc‹i_GýëåË®Ï2MâuKg&ùåL0N ¢ym}¹s8KCóeáÖ×;‡‹4t‡­ïwWiè[?înÒж~Þ9Ü¥ymýºsxHCøôçÉËçð”†Î°õùÎá% `ëË›yI“5Þ9œ¤ym}¿s8Kc>o©–xÓY¾Š.Òж~Æœ®Òж~ÅœnÒÐ>}I1§»4¯­Ï1§‡4tƒ­/1§§4t…­¯1§—4t­ï1‡qª;ÃÖ˜ÓIš×ÖϘÓY:ùMIì}NièÏoJb› ŸÓUx.Øú¸Y‰»ICOØúsºKóÚúszHCØúszJCs¾qY€Ïé% Ýþxo)ÛØúÆ¡ w…­_1§“4¯O6~)œ¥¡ l}Ž9]¤¡9·þÎé* `ëkÌé& ýÁÖ÷˜Ó]š×Ö˜ÓCx,ØúszJCsnýÓKzÀ§·»‘ñR+3ßìÏw‡­Ï1§“4¯­/1§³4tƒ­¯1§‹44çÖ÷˜ÓUºÀÖ˜ÓMš×ÖϘÓ]:ÃÖ¯˜ÓC:Á§wÿoxJC°õ9æô’ÆçÅ㋯“WCãâ*4?¶¾ÆœNÒж¾ÇœÎÒж~Äœ.Òж~Æœ®ÒÐ ¶~ÅœnÒ¼>½ý]ûU[æ. ]aësÌé! ]`ëKÌé) aëkÌé% `ë{Ì̓ïózš_[?bN'iè¶~ÆœÎÒÀçyfàõmçHÄçt‘†ž°]ç–bNWiè[ŸcN7i^[_bNwièóº;ŸÓCºÁÖß9=¥¡+Ìk}N/ièâ·h´S>‡ñâ64?æõˆ>§“4t†íZÇs:KCsÎk#}NièÞxe¹Ïé* \Ìë4}N7i^o¼ÊÝçt—†ž0¯õ9=¤¡9ßxŽÏé) Ýa^¿êszIC7xãÕÿ>‡ùv¿Öü˜×ÒúœNÒÐÞ¸Ïé, ÍùÆŽ>§‹4t†­ï1§«4t‚ye¦Ïé&ÍkëgÌé. ýÁÖ¯˜ÓC¸pn×G§˜ÓSz¼öÚçô’†°õ%æ0^,‡æÇÖטÓIºÃÖ÷˜ÓYºÁ¢ûœ.ÒÐÞ¸øÕçt•æõÆå¶>§›4¯OŽy9§»4]¾6<¾ç˜—szH3ä{Çã[JÌé)Í”Ÿ-_|^ÞrÅ,©{ÁÖ÷˜Ãõ» m¿{•¯K1§“4éþnW¾6aÆœÎÒäû·Vùú„sZþfÝÞ¸&Úçt•¦Þç¬_|ÞBÇܤi÷¹®ò5&%æt—¦ßçÒÊ×™Ô˜Óòœì^ðÆ%Û>§§4ónk*_o2bN/iÖÝ–aýªØv·Õ1·ï6î o\MîsZ¶¹î Ÿ‡/2giè[ŸcNiè[_bNWidÿªñõC5æ´ìS¹l}9Ý¥áþó[?bNiè[?cNOiîþóàë÷ðyñøÂKºÂ§ÇÇá‹ÁŽ¹fe»ÁÖç˜ÓIºÃÖ—˜ÓYš{¬4øz>|^<¾p‘†^ðÆ‹!|NWixüûÁÖ˜ÓM:Á¯¼ð9Ý¥¹Çƒ¯ïÃçå-ÌÌCºÂ§ÇÇÁã Oiè[ŸcN/iè[_b»¦ž°õ5æt’†^°õ=æt–†ëWlýˆ9]¤¡lýŒ9]¥¡ lýŠ9ݤ¡+|z|<¾p—†n°õ9æô†î°õ%æô”†ž°õ5æô’†^°õ=æ0׬¬¡ÏZîà+ƒì˜—/ ‚“4t‚­Ÿ1§³4t­_1§‹4t…OƒÇ®ÒÐ ¶>ÇœnÒÜó ƒ¯Äç勪Í]zÂÖטÓCzÁÖ÷˜ÓSž?ú`ëGÌé%Í=—4øÚA|^<¾f®MYã.°õ+æt’†®ðÆ8}Ngièo¼ˆÝçt‘æž+¼?2>/_,o®ÒÐÞxA½Ïé& ½à;“úœîÒð<ào¼¸ßçô†ÎðÆ]R}NOiè[¿bN/iè ï·1O®M&Üàý6t’†°ýœÓYšsÿùpNièûÏŸsºJÃó€l}‹9ݤ¡3¼ß†îÒÐößÎé! ͹ÿ~rNOièûï?çô’†°ÿ}qsmÊ÷„÷ÛÐIzÁÖ1§³4<ȹ??pNiè ûóçt•†.°?¿qN7iè ï·¡»4t‡ýù–szHCØúszJCOØŸÿ9§—4ô‚}ûÂ9Ì[;YCŸãÊÉõ+iè$ aßÞqNgièûö”sºHCWØú/æt•†î°oß9§›4ô€}ÿsºKCs¾ß†ÒÐ öýÎé) Ï&Ø÷—¦ßÂÙ¼¤¡3l}‹9Ì[@Yã.þN?Øg›~+gs’†æ|¿ ¥¡;ìû“Óïîl.ÒÐöýUÎé* =aßæœnÒÐ ¶þ‹9Ý¥áyÀï·¡‡4t†}žszJwü2ûñçô’&nõeöãÎa¿UTwØw8§“4ô€÷ÛÐYzÂÖ·˜ÓEžü`?^㜮ÒÐ öãAÎé& a?ÞäœîÒÐöãYÎé!Mܚȼ߆žÒжþ‹9½¤¡ìÇãœÃ~K©!ž°ïsN'iâ–7f_OàœÎÒÄmoÌûmè" a_ßàœ®Òж¾ÅœnÒÄ]U̾ÞÂ9Ý¥‰Û7˜}=‡szH·T1ï·¡§4ô„}}‰szIÃó€ìëWSÖ¯&¯­²Æ͹õwN'iè ûzçt–†.ð~ºHC7Ø×÷8§«4t‡}ýsºI7W1ûú$çt—†ž°õ-æô†ç?x¿ =¥¡ìë«>‡—4t†}ýÖçf®MYã®|G=¬ ûNÒÐ öõgŸÃYºÃÖwièÒÐ öõsŸÃMžü`_Ÿ÷9Ü¥¡ìëÿ>‡‡4t†­ïwOiè ïŸ^ÒÐ ¶¾Ý¹™kSIÝaëëÃIzÀÖ—;‡³4ô‚­Ïwixðƒ÷OWiè[ŸînÒжþ»s¸KCWøôvÜÁ9<¤¡lý¼sxJCwxÿ4ð’†°õãÎÍ\›Êê[ßïNÒð<à[ßdnÎÒÐ ¶¾ÊÜ\¤9Ž[Kåoýç\qUÎÿí÷®K¾®k8¸ÁNà óå^TÈ“u¸xÙ~ñÿËÃcžr°Cq.ñÛa?—ížK¥èý&â¶ìÂC…»¼‚]j.ÙtYZ²Tg_/´åu¿q ]–ñÅŸÊàÛNó‰ºÞ‹…ü À6@<°ýîb.ºàܾr¨wa¿ÝÅpœ$â””YÜ™±ï`Ý +âìIÛOXÛNK¾€ÜQ±…/οØAµWœcw¾M°§òýƒÝöoؼ¶^æp‘æõéÏcîs¸JóÚú~çp“†žðéÏ„Ïá.ÍkëëÃCš×Ö;‡§4¯OŸÃKzÀÖ·;oç•ñ{šÿcë×ÃIš×§ïåÎá, ÝaëûÃEš×§ßÃUš×Ö×;‡›4¯­ŸwwièŸÞÞËšsxHóÚz™ÃSš×Ö¯;‡—4¯O¿Ê›Óww…­ïw'i^ÿëÏ+û|Ngi^[çt‘æµõ3æt•†.ðéSŽ9ݤym}‹9Ý¥ymýŠ9=¤¡3|ú|çô”æµõ#æô’æõéËs8·ù±õ5æt’†N°õ3æt–æõékŽ9]¤ym}‹9]¥ymýŠ9ݤ¡?øô­ÄœîÒ¼¶~ĜҼ>}O1§§4¯­¯1§—4ð·`ëgÌaì× ùñéGŽ9¤ym}9¥¡'lýÓEš×§Ÿ%æt•æµõ#æt“æõéWŠ9Ý¥¡l}9=¤y½ß®ßmÜÞoC'i^[_bNWièï·¡›4¯­Ï1§‡4t…÷ÛÐKš×ñóÇné6îï·¡‹4¯­ÿbN7iè ï·¡»4¯í÷mÅœ^ÒÐ Þo÷ï6?¶~ÆœÎÒм߆®Ò¼Ž¿—./½Kc>ÇIæý6ô”æµõ=æ0zи'¼ß†NÒ¼¶¾Åœ®ÒÐÞoC7i^[_cNièï·¡—4¯ãùm¬ûü6ÓmÜ ÞoCi^[ŸcN7iè ï·¡‡4¯­O1§—4t÷ÛÀë»Í­ÿbNgiè ï·¡«4¯c{„9Ý¥¡¼ß†žÒ¼¶~ÆÜœ¾/šðï·¡³4¯­1§«4ðyžI_•¾JߤyíÛwÎé!Íëý6ô”æõ~zI³â±H89·uð9œ¾Û¸;¼ß†NÒ¤x®K<‘†ÎÒäØ6%HCiJlëGÆÓUš»¿šx<" ݤ¡¼ß†îÒÐ ÞoCiàsÜ‘x<2JÌé) Ýáý6ô’.¼ßæ1ˆ5î ï·¡“4ô„}ÿ–s:K×ï·¡‹4tƒ÷ÛÐUzÁÖ§˜ÓM¸x¿ Ý¥¡¼ß†ÒÀýƒ÷ÛÐSºÂÖß9½¤¡'¼ßæ1ˆ5´ýÜüxä6t’†îð~:KC/ØŽVÌé" |¶³‰Ç#ÒÐUzÀûmè& lÛHCwiè ûñçô†æ|¿ =¥Áãøex¿ ½¤¡;lý¸s3e¬¡Ï±jâñŽ6p’†.ðþià, Íùþià" œl}¿s¸JC7xÿ4p“†žðþià. \2¼xHCsn}»sxJ×Þ? ¼¤¡+¼3.¼@ãðþià$ Üìë>‡³4tƒ÷OièÒÇɤ™¿ÿØŠÿ÷ûÞuæÜh+þí=ÆÇÉ$,<û‚úݱ:ç0þ¹ß ’m¡Ž‹úÙvºslT¿Î“ë.”»Ètõc¡®ßżÙïBÝ9Ù‹O¶ÓÍ'ÛÁǃƒy“…mÚÇÁÙósB lŸwðëé÷àÒùqî×üßÿÁò¨oö>ÙÕXöâ’îwoì'·ìÏ›_éʲDb? >ÝØòŸš-ð¡²Ce>äöñùߟ:~¹Ûd*ÜÄæ»Y¯§¡rk\îÝDZ¬ëpDzîOcžÒÀ•óÓã‘Åü>ÊÞÐý˺oÓcY—»üqY÷mà$ ͹õéÎ{,åzã·4KŸ¥/ÒÐõ˺oÓc)×:ÿqY7Ÿ÷|9ܤ3—{÷OwièþÇeÝ·‡4tùã²nn½Ü9<¥¡cY÷mà% l§¼ò’~ݾ|·q×?.ëæÖëÃI:ýqY÷mà, ìK¼û§‹4tÿã²î¿¦Ý9\¥¡¹Ü»¸IC\Öý×ô;‡»4æºbY÷mà! ͧùý6ô”†N°õ#æô’¶åº²¤_··ç;6îX6~:ICs©Øús:KCð~ºHï·¡«4týã²ô¿fÅœnÒÐéËÒOCwi`|Þ.}—~HCsIûôv*szJCx¿ ½¤y½ßnßm~l}Š9¥¡+¼ß†.Ò¼¶>ÇœnÒ´û½7üüG,Ÿ»åçãî°õ5æpO·qØúsºJSïc×ñû3bÄ-¯{ÁÖ˜ÓKØ—¾¤_·ßm~lýŒ9¥É÷wudé³ôEš×Ö¯˜Óò7âÎ\ÆÎÍþN1§§4t­O1‡gº»þqYú_“cNË߸»ÁÖ—˜ÓCºÿq™9·ËÏî%ͺÏ-sI¿n¿¾ÛüØús:KCÏ?.3? ]¤ym}9ݤ¡lýˆ9=¥™÷¹wññŠef8})šp‚­_1o¾<|:ÿqÙ8·»œìîÒôØv¤¯KߥÒ¼¶>Åœ^ÒÐõËÀO§ï6?¶>–‡ÝYšK¹Ö—˜ÓMšÛV,»þkbÙÕ=¥¡Ç—Eóy“HŸÃ9ÝÆË–ÿšsºJCDzâ¿fÄœîÒpÿçûã2áÓÐCš×ÖϘÓKš»o“¸¿* Œ}Q4?¶~ÅœNÒ¼ŽŸO‘ŸöEÙÐùË~|L‹<¾Øeó:~Ÿ¹¿ Wi^ûß/çí.õyC—?.ûá9ŠsºKóÚŸŸ9§‡4¯}{Á9=¥¹û®‰û«X.±=M¾¿Zÿ¯}€s˜û¨ÖüØ÷8§“4tûã²öi“ï¯Æ’ž7¯ýx$Õ{<’¸Šæµo¦z7÷QWs©ÏŽßgÌé&Íkëc9ÐÝ¥¹Ç#‰û«¶œÏýUxHóÚú/æô”æõéëÓKzþqÙï_ScÞîR›[ŸbN'i^Ÿ¾Ü9¥¡×—ýþ5-æt‘æµõ9æt•æõéóÓMš{¼™¸?œÇÃ]š×Ö×;‡‡4¯­OwOihÎOŸæÃKš×Ö·;7÷ï6?¶>ß9œ¤¡9?ýYˆ¹9KóÚú.ss‘F¯ùíÉRüer%N¾l¥ÿÒi¹´Â?ŸRîá¡-#ò¡±eÄÁÃR[:ä!äÝi83Æ%2Û¼®ûkÏMŒ­îûŠm¾ùíØÙì?:ßu\r8€+‰Fü¨ýò¯ß¯Š?¯àU1ö6J¾8 óÌWû¿Þ8Ûuçæ" ]a^¥s¸JCxãìXÌá&Ík^Õs¸KCgØú~çðæµõóÎá) `»ªù»sxIóÚú|çæùÝÆýÁgëb'i^[ßîÎÒðê÷[?î.ÒÐÞX’9\¥ymËù)æt“†ðÆÒ¾Ïé.Íkž.ð9=¤¡;¼q¶Ñçô”æ5¯÷9½¤¡¼qvÒçðúnócësÌé$ ]áÓ>§³4¯7NMøœ.ÒÐÞ8ûésºJCgØúsºIózãl©Ïé. ͹õwNi^oœò9=¥‰+’_…u^êæWaÁKš×gc}næYÖ¤ûê•äWm•;§“4¯7ÎÞúœÎÒж¾Äœ.Òж¾Åœ®Ò¼Þ8æsºICwØúsºKóúôçe“œÓCºÁÖç˜ÓSš×gŸ}N/ihέï1‡ùŠk~lýŒ9¤¡ |z{—i^Egiè oœÝö9]¤ym}‰9]¥¡¼q6Üçt“æõÆ©QŸÓ]úƒ7ΞûœÒ¼Þ8 ëszJÛ›vó*²žcN/i^ó,¿Ïaž·Æ=a^eás:IC˜WÅøœÎÒ¼æU=>§‹4t‡yVŠ«ÈÌUš×¼ .ÅUdæ& Ý`^µ˜â*2s—æ5¯Mq™yHCW˜Wɦ¸ŠÌ<¥yÍ«v}N/ièó*eŸÃ¼rÌ7ç¼*Ûçt’æµõ=æt–&®L~ÙÙ‡ô«Èà"ÍkëWÌé* ýÁ§_wN7i^[_bNwixÊ‚­o1§‡4¯­1§§4ô„­Ÿ1§—4¯ÿÙ{Ór9 æ+e¬qØúìsw’&.RI\N²÷bår¥ym}ÌÝEºÁÖŸ»«4¯­_>w7iè ŸþÜúËIt—æµõÅçî! ͹õÍçî)Íkë»ÏÝK:ÃÖOŸÓ¼Éw‚O^Îå$:IóÚúìsw–†þ`ë«ÏÝEš×Ö7Ÿ»«4qñSârÒ¹„sw“æµõ1wwiè Ÿß_xHóÚúâs÷”†°õÍçî%M\Ѹœô•îsš¯lÊÿ[?}îNÒÜW÷s9é³ç1,'ÑYš×ÖgŸ»‹4t…­¯>wWi^[ß|înÒж~øÜÝ¥ymýò¹{HCgøô¶Ÿ†ÓÛô”†æÜúâs÷’æµõÕçôønãþ`ë»ÏÝIš×ÖOŸ»³4÷® §Ï¿sw‘æµõÙçî* =aë‹ÏÝMš×Ö7Ÿ»»4ô€­>wi^[¿|îžÒ¼>½íCât>½¤YòµáñÙç4צ¬™òøN<¾gÝs·<¦î [ß}îÎÒäû·3ñøÚ»ïN<¾°üͺ;|zÛ‡œx|á*M\tk¶>ûÜݤ‘çç‰Ç÷¬abî–çgÚž‡'ß³†‰¹{H#Û_\îp–®8wË6×Ý`ë—ÏÝKºÃ§·}H\sÍÊš%ûZ¸<â,-qîNÒpÿùƒ­¯>wgid_—Sœ¥ÎÝEºÂÖOŸ»«4r|dëWö‚:ÎÝr|ä°õÉçî. ½`ë‹ÏÝCÿ&Øúæs÷”†.°õÃçî%¬uØú•]Á9œ}ͪ‰;|ú³†‰¹;ICOØúìsw–†ë“l}õ¹»HCgØúîsw•†®°õÓçî& Ý`ë—ÏÝ]š»þœq9Ë9ÔçÜ=¤¡l}ñ¹{JsÏ/䯽½ö‡Ç^Òж~øœæš•5î[?}îNÒÄ«¨ÌÖ/Ÿ»³4ô„ïÇÏòñ‹4ûÜ]¤¡'¼ŸÆ]¥áy¢Ž¿¯\ïßצÐÐÞOãîÒÜóD9óñý|îÒÐ ÞOãžÒÐŽç\¾O/ihÎãù ç‰a®MYCŸãú\¾Û—Oú$Í=O” ŸŸ‡ÏÝYºÂûiÜEºÃñü\äù™kS'¼ŸÆݤáy¢¶¾ùÜÝ¥¹ç‰2.‡’Æ=¤‰»'™c{„Ë¡è) Ý`ëcî^ÒÐÞOCóåJÖ¸ÛÓúÝí)_Æ„†ç‰¼ŸÆ¥¹ç‰råãsw‘†®ð~w•†îpì?T>¾æ& =áý4î. Ïqîû3˜»‡4÷wOièï§q/iâåefßÃœöW>61çûiÜIzÁÖwŸ»³4÷és¸IsÏåÕ¤oÒwixžèƒ­Owiè ÒÐöõXŸÃKš{ž(¯%ýŠ¾|_4á Ûúðºs8ICsîëÉ>‡³4IŸ¥¡l}¾s¸HÃóD Þ? \¥¹ç‰Jâã+s¸IsÏ•Ô¤oÒwiîy¢’øø~wiŽï]MFû]áþƒk­ï9#œK*¾®ë„~W»Ð‰· ¶€çþ——€d^Š´bé›s^i§1ÖݵâiŒs“&?e‚KÇxY-–Îy¨fË<²å3ì²T[F῵ÃoÞ(Ç–Eøñí•ŸW–ükŽÍê'—GÈ&ÐOCÚ²~¿ßO«ã{á!“]Je‡ÿõ'Oî Ù†ƒ;À¶Ññ‹l1$Ý'O,â×"ø‚¶ýòdNÆÉ#ɱSÁ_È VÜxñÂŒa›ø·½Þ¶öÝ2îŽý¼ß‰½ß#7Øö^ŽÜ`Ó þ®m! l{/ÇhJlŒÑ¸Gl°í½}žïƘ ÝcƒóݨÓYºÅ;g™ÃEºÆ;cC‹¹o˜oC—Ø`?l¤ÙÐ)6Øö¦>‡»4ôÝ`gÙÓCø[±Áβ!§§4ôŒ v.w£N/iè»ÁÎØðc^rlŒ­ ·Ø`? œ¤¡kl°íÍ3|gièl{/JŸÃE:Çû¬5Ƽ´Ø³¡¿Ø`gìˆ`^îƘ >ÖŠ ¶½w¥7ån¤ÙÐ36ØÚÐCzÄ;—;§§4t vÆŽßc6ôÝ`Ÿ'PŸÃ<™´ª¸ÄÛÞ“s:ICçØ`Û{crNgièlmè" ÇœnÒÐ ¶¾ÄœîÒж¾ÆœÒж¾ÅœžÒÐ ¶¾Çœ^ÒмßæÉ$khÛùà '{¯QÎé$ =aëgÌé, ÝaëWÌé" ÝàÓ÷/æt•†®°õ)æt“†.ð~ºKCgØúszHC°õ%æô”ÆÏ/¾N<¾ð’†ž°õ-æ0O&Yã°õ=æt’†nð~:KCWØúsºHCØúsºJCgØúsºIC'øôö{Ž9Ý¥íy 'œ´¡‡4ô„­O1§§4ô€­Ï1§—4t‡­/1‡y2Éwƒ­¯1§“4t­¿s:KCgx¿ ]¤¡l}9]¥¡?ØúsºIÛ~Nãã;cNwiè[¿bNièŸÞ¶S˜ÓSºÁûmè% ]aëSÌažL²ÆaësÌé$ `ëKÌé, ýÁÖטÓE^ر`ë[Ìé* =áý6t“æµõ=æt—æµõ#æôfÈ×ÆÇ÷Îé)Í”ïïÓKš%?[<¾ëÎáñÝfÈã‹NÚÐòøþØús:KCØú;§‹4åþîá„“½.çt•¦Þßmœp²·äœnÒ´û·ƒNöÞ¹œÓ]ùûÅzŠ6´üýþØúszJ3ïsN8Ù{írN/iè[çðünCÛs×äã{çt’&ÝçÆ™¤OÒgi^ÿëí½|9§å9yÊs5N8Ù[,rNWiêÝà„“½—/çt“†®°õwNwiúÝ6á„“½÷/çôfÜmN8iCOi^[ßbNË6wʶëWö^ÁœÃë»{ÂÖß9¤¡lýÓYî_}°õwNWièŸ>Ý9-ûHKö°eï-Ì9Ý¥¡ lýÓCºÂÖß9=¥¡lý›+/V>M¸ÃÖß9¤¹ûºëKö^ÄœÓYzÂÖß9]¤¡lýÓU¿|°õwNwièŸ>ß9=¤¹Ç&ëEöÞÅœÓSºÀÖß9½¤¡+lýÃ\#²æÇÖß9¤¡¼ß†ÎÒÜãÍŠõ"{odÎé" =`ëÒжþÎé& ½`ëïœÒp}àƒ­¿szJs×*Öì½”9§—4t†­¿s˜k>Ö¸ lýÓIš×Öß9¥¡+¼ß†.ÒÐ ¶þÎé*Í]ÿ©Xÿ±·æœnÒжþÎé. =aëïœÒ¼¶þÎé) ½àý6ô’†ë{lýÃ\ó±ÆàÓ×;§“4t†­¿s:KóÚú;§‹4t­/1§«4t…÷ÛÐMºÁÖß9Ý¥¹ë·ë?ö¾÷œÓCzÀÖß9=¥ymýÓKzÂÖϘÃ\ó™êï·¡“4\Ÿÿ`ëïœÎÒÜõùŠõŸ³ôàsºHCgØú;§«4¯­¿sºICx¿ Ý¥¡+lýÓCºÁÖß9=¥¹ç_*ÖJ»szIóÚú;‡¹æ³Ô¶~ÄœNÒÐÞoCgiè[çt‘†ç×>Øú;§«4t‚OßïœnÒ¼¶þÎé. aësÌé! ]àý6ô”†®°õwN/iè[çp¿çLmýÓIºÃÖ÷˜ÓYzÀÖ˜ÓEzÂûmè* ½`ëïœnÒðüø[çt—æõéÇÓC:ÁÖ§˜ÓS:ÃÖç˜ÓKºÀûm`®íXã®°õwN'i^[çt–æ^ÿP±þSF‹9]¤¡;l}9]¥¡lýˆ9ݤ¡'¼ß†îÒÐ ¶þÎé!ÍkëÒð:–>ýübN/iè[Ÿbsm'«3¼ß†NÒжþÎé, ]aëïœ.Ò¼¶þÎé* Ý`ë[Ìé& Ýaë{Ìé. =àý6ô†ž°õwNOi^[çô’†^°õ+æ°_›$¶ã,®ÿ¬/æt’†N°õ)æt–†Îð~ºHCØú;§«4¯­¿sºICWØúsºKC7ØúszHCwØúszJCx¿ ½¤ymý››_›¤ž°õ3æt’†^°õ+æt–†×±|ð¿þ,]ùœ.ÒÐ ¶>Åœ®ÒÐÞoC7i^[çt—†.°õ%æô†®°õ5æô”†n°õ-æô’†îð~دMêÿ×ûmè$ =àøú1§³4ô„ãçÃ÷€‹4ô‚ãçŸÊýùûµIëúgµ$o’Ç—×&¡¡9ßO®GÁ]š×ñûŸúýýçµIhè ûßçô”†.°ÿýrN/iè ûó ç0¯M²Æ͹?¿qN'ièûó'çt–æµ??sNièûö‚sºJCOØ·GœÓMšsß>rNwixËûö—szHóÚ÷8§§4t‚}ƒszICgØ÷g8‡ym’5nÎ}ÿŠs:ICWØ÷÷8§³4tƒ}’sºHóÚ÷W9§«4t‡}˜sºICsîûóœÓ]zÂ~¼À9=¤¡ìÇ#œÓSš×~¼Ã9½¤áu,ìÇ_œÃ¼6É7ç~<È9¤¡3ìÇ›œÓYºÀ~<Ë9]¤¡+ìÇלÓUš×~üÎ9ݤ¡9÷õÎé. Ýa_¯àœÒÐöõÎé) =a_Ÿáœ^Ò¼öõ¢æëWÇ~m’zÁ¾ÕdýªùµIëÚþN}ýªÇœÎÒÐ öõ·æëWæ" a_ßk¾~e®ÒÐöõFÎé&Ík_ÿäœîÒÐöõUÎé! Ý`_¿åœžÒÐöõaÎé% =`_ßæök“†x¾~Î9¤yíëóœÓYzÁ¾þÏ9]¤áu,l}Ž9]¥¡lýÓM:ç·ý|®_Á]š×ÖϘÓCºÀÖ˜ÓSºÂÖ÷˜ÓKºÁÖß9ì×&5q‡­/1§“4ô€­Ï1§³4¯­O1§‹4ô„­ÿbNWièŸ>ß9ݤáu,lý¸s¸KC'Øú~çðæµõíÎá) aëëÃKºÀÖËÜ̵)kܶ>Ý9œ¤¡lýwçp–†îðéϺœÏá"ÍkëçÃUzÀÖËnÒж¾Ý9Ü¥¡l}½sxHÃë^>Øú"só”æ8Þï(çô{5ÝüϽù¯´kuøoåïx„ßð‚q»ÌTþËÝP.ÕÙ!Š/±Ù©P._Úicþ©Ø²N¿K<õe‡sÕw¯ïe ¶Yâåöà—nØéæÙÒ?±OåúÃOÝÙé nÆ>9­bKl|š¶åÝ~/%÷Ó?ö=¶û‚ê—¿Ûåëçkþ¯?ùó8¨‘/†±¯‚ q¶øÏ_*[¸ãˆðå“•\ãšâ/IwÁªßÅlÜyàcšr/Úñ6û%¯ò¤ÍZÿúùÎsþ'u`Ÿ–ùÃXAŸ¯µãûœ{¹Í1žÑ¸+¼8IC'xÿ4p–®¶¾ß9\¤¡+¼¸JC'xÿ4p“.¶~Ü9Ü¥¡+¼xHC'xÿ4ð”ÎœïŸ^Òж~Þ¹™oÊi;Áû§“4ð9ÙÓK’>IŸ¥¡+lýºs¸HC'xÿ4p•† aÞ? ܤ¡+|ús ês¸KC'xÿ4ðæ.„u`? <¥¡+¼ß†^ÒÐ ¶>ÅæÁóŸõŽlmè$ ]áý6t–†æÜúsºHÃ…’ï·¡«4t…÷ÛÐM:Áûmè.Í}Žî•o‰9=¤¡+¼ß†žÒÐ ÞoC/iVlKzåã[cËÁs˜óý6t’†Nð~:Kí [ßbNi^ï·¡»4¯­ï1§‡4÷@··!ý~IóÚúsØV×õÙ6÷þݾÒgi^[?cNWiêýÙö*}•¾KóÚúszHCgx¿ ½¤y}úùÅæÁž5îï·¡³4¯­O1§«4õþ®â€MºKóÚúszHC7x¿ ½¤ym}‰9̃%kÜÞoCgi^[_cNWiêýÛŸUú*}—æµõ-æô†žð~zIóÚús˜'¿­q/x¿ ¥ymýˆ9]¥¹–õU¥¯Òwi^[?cNiîBj_Cú!½<ŸÿØúsóàÉãÓ„3¼ß†ÎÒ¼>ý96àœ®ÒÐÞoCwi^[ŸbNiîöqð°4ô’æµõ9æ0(­q7x¿ ]¤ym}‰9]¥¡;¼ß†îÒ¼¶¾ÆœÒÜ}‰‘†ôCú%Íkë[ÌaY[ãžð~ºHóÚúsºJC/x¿ Ý¥ymýˆ9=¥á‰¥ÞoC/i^[?cóäŸ5îï·¡‹4¯­_1§«4t†÷ÛÐ]š×oüíszJCx¿ ½¤y½ñnÔ>‡¹Ïo»Âûmè"Íëwµö9]¥¡¼ß†îÒ¼Þx»oŸÓSºÃûmè%ÍkëkÌaî3[ãð~ºHózãÁ}NWiè ï·¡»4¯7ÞTÝçô”†^ð~zIóÚús˜'o¬é÷Dûð7ˆ¿ ]¤ymýŒ9ݤ¡¼ß†îÒ¼Þx“zŸÓS:Ãûm`î[óãÓŸ…]Îé$ ]àý6t‘æµõ)æt“†®ð~ºKózãè}NOièï·ýâ×öm}‰9¤¡;¼ß†.Ò¼¶¾ÆœnÒÜ eÆlÒ7é»4¯­o1§§4÷ÂÓ1§ôóö¼xÔš[ßcN'ièï·¡‹4¯­1§›4¼Pìƒ÷ÛÐ]š×ÖϘÓS:ÁûmÌó»ëW¿¶~ÅœÎÒÐÞoCi^ŸþœÄâœnÒÐÞoCwi^[ŸbNOiîzàÄ‘ÚÀ|1­5?¶>ÇœÎÒÐ ÞoCi^[_bN7ièï·¡»4¯­¯1§§4wít¦)ý¼½_ü7þ¯­o1§³4ô„÷ÛÐEš×Ö÷˜ÓMš{!æÌMú&}—æµõ#æô’†Â~ð~˜kûÖüØús:KC'x¿ ]¤ymýŠ9ݤ¹"ÏÒ¤oÒi^Ÿ¾|1§—4t÷ÛÀ\·æÇÖ§˜ÓYºÂûmè"ÍkësÌé& Ýàý6ôæµõ%æô’†îð~˜kËÖüØús:KCx¿ ]¤ym}‹9ݤ¡'¼ß†Ò¼¶¾Çœ^ÒÐ Þos­Øš[?bNgix¾ìƒ÷ÛÐEš×ÖϘÓ]:Áûmè!ÍkëWÌé% áý60׊­ùñéϹpÎé, ]àý6t‘æµõ)æt—†®ð~zHóÚúszIC7x¿ ̵bk~l}‰9¥¡;¼ß†.Ò¼¶¾ÆœîÒÐÞoCi^[ßbN/iè ï·×w›[ßcNgièï·¡‹4¯­1§«4¯ïǯòñ›4¯ãñâþ6Ü¥m?“ûÛõ‹9=¤yÏ'kÜç“5¥yÏÿÜ?‡—4t‚c{ºîöt}÷ƒ_ûþ çt’æµïOrNgi^ûþ9çt‘†Î°ïpNWi^ûñ)çt“æµïsNwièûú çô浯wqNOi^ûú!çô’æ^O²|}~ܹ9ÝëI~íëç>‡“4¯­ÿîÎÒ¼>ýwiè[/s¸JóÚúïÎá&ÍëÓqçp—†î°õõÎá!Íkë¿;‡§4¯OßÇÃKš{íÐòëÁê›y­—5?¶þ»s8IóúôMæp–æµõõÎá" =aë¿;‡«4¯O_ÇÃMš×Ö×;‡»4ô‚­ÿîÒ¼>}wOi^[_ï^ÒǦµ—ÿØ•¼ÀT¯Ù¨ö\ÍãĻͦ¶ñìX>7£á œÿþ«¸tˆ]þ*œoupó~Lƒ›Šv—KÎm=|iÃ.›|Z9Kí\"±?iÿ·vú×À®»Ü‰Ó–ܶeV¿Åæ«ô¬qgØús:IóÚús:KC'ØúsºH¯èÊ~Ç©ÚcNWiøŠ½[?bN7iè s£èsºKCøôí‹9=¤ym}Š9=¥‰Wìe¿ãTË1§—4tƒ­/1‡ýUzM\aëkÌé$ ]`ë{Ìé, aëGÌé"ÍkëgÌé* `ëWÌé& ýÁ§ï_Ìé. _q»`ësÌé! =aëKÌé)M¼ú6û§z9½¤ym}‹9ÌWéYãî°õ=æt’†n°õ3æt–†®°õ+æt‘&^]ãŽS_Ìé* aëSÌé& ͹õwNwi^[_cNi趾ŜžÒÄ+æ³ßq ?ç¸0%û]¦ÐÄË“²ßq #/¼8æË´¬qsnýÓIºÃ§·ßs?ÑnÎÒ¼¶>Åœ.ÒÄrÜq*Çœ®Òж¾ÄœnÒÐœ[çt—†Î°õ=æô†N°õ#æô”æµõ3æô’†þ`ëWÌaÞeʺq~úuçt’†ž°õ9æt–†°õ%æt‘&în’ãŽS5æt•æµõ-æt“†æÜú;§»4t…­Ÿ1§‡4t­_1§§4q÷šÌ;NUÛ/åÂ(¼¤¡l}Š¹Ùï2ÕþÞ8‚ö9¤¡?Øús:KÃ;-ØúsºHCOØúsºJCx¿ ݤ¡9ßoCwi^߯¿Ë×?¤¡9¿?Ÿ!?Ÿ)MÜ}*ǧJÌé% Íù}¼Ö}¼ü.SEÌù~:IC'ØâŽSæ,ÍkÿýŒ;N™‹44çþûßüÂs•†/æÜÿ¾8§›44çÖ˜Ó]šóý6ô&î—ãŽS=æô”æµ?ÿħÌKšs~‹;Nó.SÖ¸9÷çO¹ãTö»L¡¡9÷çg¹ãTö»L¡¡9ßoCiè[ŸbNWièöí‹ßq nÒ¼öíWÜqÊÜ¥3ç¾}Œ;N™‡44çûmè) =`ß^ǧÌKºÃ¾?wœ:æ]¦²ºÁÖ·˜ÓIš×¾wœ2gihÎ}ÿÇï8ihÎ÷ÛÐU:þ?æwœ‚›4t‚}Ïï8wièöýI¿ã<¤ymû«+æô”NœûþmÜqʼ¤¡9ßoóvI=`ßßö;NÁIºÃ¾?ïwœ‚³4tƒýxÁï8i^ûñH»Ög¿Ëšóý6t“†.°õ%æt—†Î°Où§à! `?^óÀSúƒýxÐï8/i^ûñ¦ßqÊÌ5+kèóý6t’†ž°ÿú§à, =`ëGÌé" Ýa?÷;NÁUºÁ~¼ïwœ‚›4¯}=Áï8wihÎ÷ÛÐCºÀ¾¾áwœ‚§4t†}ýÄï8/iè[Ÿbû]ÒÕìë9~Ç)8KcN¶ŸãëQ+æt‘†ž°¯G5YâÝ¡ØÐöõ.¿ƒܤ¡;ìëi~)¸KC7ØúszHóz¿ =¥yíë~)xI³äk»ë~)3ßõÎ÷€}=³ÝgÞŠMº?[®GÙqЈ®gÞŠ<¾#Þ¡Âç´<¾\²ß%®GICWiêý]åz”7ù `ÌMšvÿÆ]Oö;HÁ]ù{äz”7q= –¿Gwƒ}=Üï Oiæ}.âz”4ô’fÝç:®GÙq×£Ì\ƒ²fÊó-ף츉ëQ°<ßÒö\Íõ(;nâzœ¥ÉwÛ1ãf|NiÊÝ–q=ªÞ9]¥‘í)×£¤¡e{ên°õ_Ìé. ÝáÓÛq×£à! =`ëgÌé)ì/q=ªÜ9-ûK~ô¶¾Çö; âï·¡“4t†­o1§³4t­¯1§eØÝ`ëÒж>ÇœnÒÐÞoCwiè [ŸbNË1Î’c®GÙq×£à) g|z™ÓK:ÃÖϘ›»ßõ<‹ lýˆ9¤¹Ç¶w@—†ÎÒÐ ¶¾Çœ.ÒжþÎé* =aëkÌé&Í]»èÏ×—˜Ó]®G}°õ9æô†æ|¿ =¥¡ l}Š9½¤¹kSÝß‘ï‹9ìkPUÜàÓŸçÎé$ ÝaëgÌé, Íù~ºHs×;×£Îóçt•†ëÉl}9ݤ¡l}‹9Ý¥¡3l}9=¤¹kË=Åþ|NOièï·¡—4t‡­Ï1‡ý®ç]<`ëSÌé$Í=_À´Ùu;ÝoÏgÎÒð|ç§?ÛqÎé" `ëgÌé* áý6t“æžâ ÚìºÎé. ]aë{Ìé! ͹õ-æô”†°õ5æô’æžïã Ú´ý®çS¼`ëKÌé$ Ïç~°õ9æt–†æÜúsºHsÏçòmvÝN÷ë¬ÌUºÂÿz»nÇçp“†nðþià. ÝaëçÃCš{¾ž7h³ëv|Oiè[ßï^ÒðzŒ¶¾Ý¹™kPÖ¸l}½s8ICgxÿ4p–†æÜúrçp‘†n°õùÎá* ÝaëÓÃMzÀÖwwiŽï¬_ûÎBñÖóüéïº)dzvmþ-.`ÅÅ}X0À…þÈ÷ =YòÄ‘=±ùI ;ážítûѶàÊ绘‡ƒ6‹D[ŒäbŒ-HOC/ièï·Ûww‚­¯1§“4ð9Ç}“ž†ÎÒМ﷡‹4t‚­o1§«4ðY®À}–ž†nÒÐÞoCwièÞoCià4`ë{Ìé) ]àý6ô’†þàý6pÿnCœ[?bN'ièï·¡³4æóºó~ºHCwx¿ ]¥¡3lýŒ9ݤç‚÷ÛÐ]ºÁûmè! aëWÌé)Íëý6°aóãÓŸÃ;Îé, ]àý6t•æµõ)æt—†®ð~zJóÚúszI³îÏv,é×ígºÍ­/1§‹4t‡÷ÛÐMš×ÖטÓ]zÀûmè)Íkë[Ìa[’gãžð~:KóÚúsºHSîßÂ*ÒéåoêÇÖ˜ÓCØömÖ~H¿¤ymýŒ¹÷ŒBNð~:KóÚúsºJsŸæW¥¯Òwi^Ÿ~~1§‡4t÷ÛÐKš×Ö§˜Ã)ÝÆ]áý6t‘æµõ9æt“†nð~ºKóÚúszJ3c[€ûD= œ¿ÛüØús:KCx¿ ]¤ym}‹9ݤ¡'¼ß†îÒ¼¶¾Çœ^ҬضN¯I—ï6?¶~ÄœÎÒp[ÿÁûmè"ÍkëgÌé&Íëý6t—†Nðýzº|=Cš×ñûÃã)xJó:þy</iè ûó'ç0¡¬ù±o8§“4¯}ÿaúñ”9KóÚ÷§O™‹4týxgÊñÔä1š×~üË9ݤyíë9œÓ]ºÂÖç˜ÓCš×§?ÇAœÓSš×Ö·˜ÓKš×Ö§˜Ã<†²ÆÝàÓŸã Îé$ÍkëkÌé,ÍkëSÌé"ÍëÓŸã Îé* ÝaëkÌé&Ík뿘Ó]š×§O#æô†æÜúszJóÚú/æô’æõéñyñøšýjü_[_bN'iè ïÿ±[êÄÎÒ¼¶¾ß9\¤ym}¾s¸JC/øôsÝ9ܤym}»s¸KóÚú|çðæõémŸsxJÃã嶾Ý9¼¤ym}ºsó¸ÇË¿>ý9ô9œ¤¡l}½s8KóÚz™ÃEš×§?k¶>‡«4¯­¯w7iè [ÿÝ9Ü¥y}ú:îÒ¼¶¾Ü9<¥¹ë!ÇgÓsxIóúôgÝÞçæùÝæÇÖËNÒ¼>ýY·÷9œ¥¡+l}¿s¸HóÚú|çp•æõéÓ’¹¹Isì§ÝÎþÑÎ_Hiÿṃs|šx ~×+Îî;ÿ­vãb6ÿ@—,P}¶ˆ%'¸!ÍóÚN¼°¯¶à1bã#¸qd?©rwBW±/®|m¿È<baLØ“qÊa?ˆÝØaLºOmå.…û®ír5ùså&»ð¹ºÌ{ÛÄæ»ìÈC/{Ǻ¿Ãÿ$îòP|ý<­gW¶áí•®ÃfÆ&Í­ow'iè[/s8KóúôvUçp‘†î°õåÎá*ÍkëÛÃMš×ÖÏ;‡»4tƒOoW5qi^[_îžÒж^æð’æµõóÎÍã»ÍOoWq'iè[_îÎÒ¼¶¾Ý9\¤¡3lý¼s¸Jóúôv• çp“æµõåÎá. `ëÛÃCš×ÖÏ;‡§4ôŸ~~w/i^[_îÜ<¿ÛüØúvçp’¶« ±´Ë|gi^ŸÞ®á.Òж¾Ü9\¥ym}»s¸IóÚz™Ã]zÀÿz\…9=¤ym}‰9=¥¡;l}‹9½¤ymýŒ9Œ%a4?>½]ˆ9¤¡l}‰9¥ymýÓEºÂÖϘÓUš×§·ßCÌé&ÍkëKÌé. ͹õ-æôæµõ3æô”†ÎðéËszIóÚúsóø¾h~m}‹9¤¡lýŒ9¥y}ú³Íåœ.ÒÐœ[_bNWi^[ßbN7i^[?cNwi`ÛÓÃ2¼½"ˆszHóÚúszJCOØúszIóÚú;‡Ów›ŸÞ.åÀœNÒж¾ÄœÎÒ¼¶¾Åœ.Òж~Æœ®Ò¼>½ŠÄœnÒ¼¶¾ÄœîÒÐ ¶¾ÅœÒ¼¶~ÆœžÒÐ>½]ƒ9½¤ym}‰9œ¿ÛüØú{Y¤¡ïeqöŠzÎé,ÍëÓÛ)5Ìé" ÿü²8»çt•æµõ-æt“æµõ3æt—†N~YœÝƒszHóz¿ =¥¡9ßo—ï6?¶¯ÅœNÒ˜“Ï÷ÛÐYš×ñó)ùþ|p´Ë†æ|¿ ݤymý½œîÒМ﷡‡4¯­ï1§§44çûm`œIÿ/Çï[ýîï[MÒМ﷡³4¯­¯1§‹44çûmè&Íëøûªíþ}Õ. Íù~zHóÚúszJCs¾ßnßm~l}Š9¤¡9ßoCgi^ÇóU“ç«V¤¡9ßoC7i^ÛóçŠ9Ý¥}¾ß†Ò¼ŽçgÌé) Íù~zIóÚúsk)hܜ﷡³4¯­ï1§‹4ô½ŒKºJó:¶w˜¿üê6ô½,K›"—b¥ÿ—­¯1§§44çûmè%ÍëؾwÙ¾t›ï·)~¹ÖmòýÞþ÷ò.Z~æî ï·¡«4õþí þüïe_t“¦ÝçŠÑ¤oÒËs”»ÿùebÚÐCšq·5cÜý«ÁÇË<¥‘m÷ý±!ûc\ë@C—?¿¬ÌîPÃ9̵Ž¯ˆ;¼ß†NÒȾ7ÖC´¡³4r<…õìsbNËñ”›—ªí·¡«4t‡­1§›4w=„—¹iCwi¸ÞõýùenvÇÎé! ]àý6ô”æ®mò²8mè% =áØÿçzˆ\"‡†¶µo®‡HC'iè[_cNgih^Ž·ß†.Òмo¿ ]¥áºôÇñ×Cà& Íù~ºKC7ØúszHCÏ?¿¬OzJÃuéÞoC/ihέO17ó?kÂíÏ/Ô†NÒÐöãSÎé, ×¥9ßoCiè ï·¡«4tûóË íGœÓMzÀûmè. ×¥y)¢¿sNih^¢¸ß†žÒÐ ÞoC/ièñç—1–>bs dˆíò+_¹s:ICç?¿ìÑ^´7}=¤Ç™A6tƒ÷ÛÐEzüùe’¶f2}=äžÍdC/x¿ ݤáº4/¥ÜoCwihžý´þž ¥‡4ô€÷ÛÐSzýùe˜¶¦Ä9½¤áºt†÷ÛÀ\ë°ÆÍK5÷O'iè[ŸïÎÒÐëÏ/ó|¸HÃuiέOwWiè ïŸnÒмDtÿ4p—†^~Y¨­ú¼ßsÀl¸.Í3ãû§§4t…m}rÝyã奷¡y©éþiÚ½Ôû^vú4p’†ëÒ öõRŸ·{îœ ]ÿü2Õ§i÷T6tÿóËTí_>‡«4ô‚÷O7i¸.þü²Ö§i÷’U6týóËZíb>‡‡44çû§§4ôúóËZmÚçð’†#/qÝ? .ÛüncŽËLìŽ7½ÍÿØgÒ#"»ÿ¥¬Ðá"»Q;Ÿm³ÂåÛ„q),ã«x:m²ÔYïòf–WÖbw´pWÖ^±ÇS'v(}O1óP»s<­lð”±í–ðt°½*‘§Âýk6ÛÒ܈͊/SÛœ»vs‡uwüT]½§ó솿8uõßÿÁÉ:ß)ødçnÝKTìö|M—Ý Ãrì5fü#+²,¯¶pøÉ}M¬møºAœp_<øþyk½;eö‡È ~’…;;ç"“úÇ«&ÿxÅä_Á=ª«#~æúÏy¿ÂÓW«#‘f¿:ßßÿ÷?vÇ%ü¦þeüì|ôïÿ.r™œüûÿî?ßvÿÝ­’õž·e³îßÿ¤æ°ß óŸì{bÛL÷ÍÆöù eÿ§MþlÇaâ ”"ûã~ùÜyi&ÚŠ îtüofߥ½d_'¶Røßÿé˜ù%ÅG5ggo¥øÑØð߬Ø/뿬$‡ý‚œÿdKÿâbŸáß7]°¨÷…²ÿÇóm ã‡0q7Ì?Ñùþeœ!¾¶?Á²"\þëJñ=[tègoSt:ûbÎ7ÕIŸHå:«ÿWû‰àV±ÿ¾mÜø_†>|ü‰à–õÿb¼7Á¿ŸÞ”áüDª/ð?žo¥Æ·Òâ[i¾CÃOtþE«ñÀàÝ¿Ï…°ÿ>;δØ’É¿ÿ„k…ì{àËèX=ýBÙÿãùD¼¶¨ø‡0ñxÕ?Ñù8'h?",­/£ñsaùßçâJùÊþí£5ÿ #>«¯}üû¯Ëÿ§þ}§ýWÛ]±aû‘gƒ±ý]æøïöSË5¾”Ü.{üXó¸ÿlÞkÁnëy¯Âr?Zñº?»(ÂÙîÏ°Øᛩÿí³ém®ÍÐ8*þ#ÄÛíÙF0‡>ÿ¯Å«ó(ö•úGæ€Ìñßñ%¯ø:ëw™ã{Âç´†/ î?L•_ ÞÍÁ¾([³/ÙÖ|§éÌVÌìÛÅ.×y¿\¼5‚}¥øˆöÃÅ æí³“%>%6à~ ‡R|Ñ#þ>-~ú¸Õ®}Ѷ¿ùÿwu-Ér„0lŸÓ€ù#õ®‘Ü›±dËSÙ© 62=¯žLÓpÂFª<ŒvËöƒÅŠ½ì´†`ýÏJ¹: ®¦k¥ÙäÖª€ù÷D³:šOîd9³?Hr·P¹üœú[ðç—Wû¢ÚW@¨E'{aôĨ7РnôR²q¢Ôs圷ÐQëuÜtù ¨ºáÓSâw4¼R„c#&˜·±þi‰PH¶©‡ƒÞŠÿrò>ÕéH·â±:ÔÛY‰VËV´#3Gœd™Œ;$$zbm Þ{dDè3ŒCV6“ÐIa8ú½‚/5Ô°blblblblblbÜS‚Gp261616161¶blÅØŠ±c+Æ£1b<ÄxˆñcãTÄþC#vr`ÑAã]ƒÆºž¬L•÷+{_ªNvöL•¢Ôé…> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:59-07:00 2013-08-20T08:41:59-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000048442 00000 n 0000050012 00000 n 0000048383 00000 n 0000048252 00000 n 0000000015 00000 n 0000048231 00000 n 0000048506 00000 n 0000048547 00000 n 0000048576 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 50182 %%EOF ast-8.3.0/sun210_figures/frontc_bw.pdf0000664000175000017500000012426213004147321014470 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœŒ½K®$»–ØQx»€sËø§@€z©hä•!\À«jhúâúlÒì¾Ì,!ñò®Ø¾ÜŽ9Fî?ÿñ¹þJŸ ÿçÿþ×ï¯ÿû¿ŒÏÿÿ~ýãWI寜 ¯¥–¿fú”û¾>ÿïûüëçþºþ*ýó¿~¥Ï^ÿû¿®ÏúU{Ÿt•òùþªµæOJi~þüª©´OÊõZ¸Ì“6×ó̼î'µÆç–Ö§™c9êËa9žÏxŒë˜g\‡ÇÏj¦3ÆScÓñÜf9ã=ÛïkêwwüÝ9öØ_óÞcÝ×û˜Gmœ¹Óú™#í1GZ=ó¢•óü[>ϼ=ž³žO~<Ýsçþ{ÏjÍøý¬¾Î…oÞ.~9¯o¬4Öö34iHòµþlª)¯—F¹Ï-÷vð¸öí_#?ð½Ê5¯îûgÅ0{ëË{ÌŽ¸g†Fü~Œø<#î§Î×;=滟t} ?E> ?9-¿ó?|*kñÜ%õµ†—¡s¬m´T½ùc­MÅ¿~â/L½Õs­q¹zãâÖqî´öNç®ý”„ëùåñk<ºü5]áÇÆâ‘~l,)ÿÓ¯Ìc ¹eî7ì.áKOÅôãv‘ëR(Já¯ÉeýÑruê óop â’«×=è‚Pˆù+­;r$ò[ÁÁs-óõ+©«{^RW÷¨Ý1æ%uxÏKa_ó1Z¾Îc.RÏ÷( -æõK¯@í9ÿî³¢¥lϹñX!Æ¿5çÞO¦Ö5qcY(ë‹å¦bS¯õ—Ëà PžX£•VÚR:~YY+øš—|2åÂ:{S[ OL^]{inU:.Þ²âQ÷ÝñxëGZ¿f½Àµ°ßü˜£éÀéüzŽèõx¯®cŒüJ]ëe]¨rö-˜—YÕ ×TΫ—±Åé°àZ¤’k9¨—/ˆkÊ•[„5›ÊaM”2EXÃU†‰+ắÒuß$Àvc¿3v^‰EP„¥!¾ê^É"¬'[8+Ï$BÇzY×0Þ"`vP'^p ôófyÅ{™‡Øõ¨n-¸¼‰€½–ËíZt1¥tgë•ÉE·N%@w ,‹•4ëÎ.®Ò€\ øì„.Ë?\aÅQ¯p%êùµ®LÔºV™¤A­k@Žë2@ø‡×ø}RÓu×\IM×¥¬ë®g¬…M…%-º.}Xºîú™Zj…Æíû¥¤¯­=ù~׈ûv×Ƥ)P—ºDÛf]~ìCèúhhËR·4²e­­\.kY±éë7U}cý¤ªo,RÑ70ùõ L}}?GßÀ¯Ñ7Ö3ÐÖù#Ñbÿˆ– Ów×;û“tÁõ(~¸@.¸¤šj˜:?š€˜:?ÜGk^VÙô—”+W™ŸægÙðú‘kY—·ÃñGñö€eäëbëB?zÌPên]lí ?2cÆ]^ºÜzD?ZRNÀºàz$?ZȾ€uÉõüHµ¬ Î)< ¯?å ±¬Õ…Û%Œ¿¥wÓìGËÝÂø[TAÖ¢€¿EÿIÅ~·°Ü øQIO>áW%Íh?I¿ ZÆOÖïÂ÷“õ»°Oýdý®D§–L¾Ÿœ%_³oaÝžQÖÔ…±ú“¹‘Ö‹N$­0¤²žœ?Ys ŽŽYñZÕOæÎ}aɾ;$¯tRI¨]ž© ­mu¡Ruõ‹·^Å…õ†tÈk—·^e¿Ó ëå[£¾VU½}ëiÔK“ ÃÂ%Ö‹õfi)»° _W¬.åÖèbÑY*‹«³f¦X¢Ê=Z¬\åîâd¨8=Ç:Wn¯ÆëËíåx f¹½C ¿½ ¯…°Ü^‘îÁKrÇ=xMîø[^”±>ß^•×À®ýÂëö ¬ûœØG¼0cíŸ^™±%L/ÍPÿ§^.n S‹3|ë 'a\S³›»ÐÔ˜ks*Þ¾pÍ,ì)g>v¸…Å)¸¦fh/0Gnq0&ãö>9`¦ˆƒ1ºgìµ ë~8œYØ×H§k½ßÅ*åo¸xÏÍáŽÜãN7^Or½wüš…ý+qoãükoÓ k^3åöF¾~÷ùZÙ§÷éñ¹½‘¯xÇFž>·öøhbê¬ ÝZKÚZcbâ¬×òÖÚÖüŽi³žtÌš5QcÒ¬ñÛsfÝYL™ü‰³þ~L˜µÓÇ|Y·Óei©1[ÖÈ{²´µx¦´õ’Noäë)Loäkà§7ò5¦7òõ¦^̶VÚé÷rM§é×rÿˆ·òþŒóR¿“k¨‡_ÉõL4;ø6¿k‰Tè±£zIXW¨%V‡¡A­ë™b b´‘aYi¯6#YƒXÍ麩KGÆ2%Ï•‰>½-‚V¾õ>] "ôŠ®dÝ傺îzz³ŠQ>Ý÷»´û~×Tí¾ß5|Ý÷»†¯û~×ðußïš«Ý÷»¦E¿4ë]î_(Mã»VàO³¢´Æ¬i_]kâ§i|¡†È`[0}š&íZP>MëõZ>MKÇz­?Móºk+VPÖu‹5”ùiy«(M{SYS®%+)ëkzËÊšcí²š²–{Í_h,Uó·@ÉÖÚ=·}mNúÚªm·¬Aªê‚¦FYïvÕûV`¼V«0k³ÐŠQÖ߯Zòm©ÙÚÌÚ¹tëPlªnŠýÌ-‰÷õ¸èÖ±#­{Ø(ËÔÅ:—IÁµzj–À€*š%Pš­óc?.õ¼îµhÔ¡?©Óknµâ³.Vt1¬ÐZÞ2n­yM ¬oÝÙÒdÉQý)Ö6ÖÏRU¡`gë&ka²%Ö±%`Äé Η­÷Àж: ÑZLe+O°‚­SASµªEUUî¡léúÃú‰n8G’i¿ÒŸ¯?ÌP€u£Ž± ¢ÅÖŒŒÔ^o@²®‚™Þøü“5XVx`aX‚…qÔ£d­©#¦$éú™É:VÛVÂ"r=PK² mÇzéE< b«ã­_Ü­$ÍØPˆÖ2©Ÿï‰fv+ÿ˜õ$å¹±^BU¦h]²õ0›dx“%[²JFeL¨È¨(ð]Éà›’Œá’­Ñï€ßÖ(èÃ5?úB¢/õYÒ«ÛæX0Ùæ(p7ÿpf,¸TØ")4Ø")‚UÒõsd~¬÷o©¦|l .­¶IºþóÓ%]þpú.}hݵö³-‘µòu[" ®Ûá¸lx?|ÞÏ-)ŒKy×FÉÂPü¹nPCú‘ÉX ýÖA#ƒžN](KCÂpp6Q[úÑ$[k/þ•¡2hdpyX¸†±R =mì‰?ö¾ OòÊaWüI]‹ÆÓÐ=àg%ÁH4\ô·ø»4 ãÂ5R[v)®Éõca4ü[¶`æBY°SþdÚÈ[å^åÒû6h†ñ¡¹µpa]³a.htE׬W7ÊâO®ö]ÁÒ˜@•ýÑTzÂwåÓê˜uò]¨Ç˸áw£î½ ã~ô>A5ûÉzË -,/',Ûmô FÏE#¦ë åŽ!à¢Ó¼ A^[,IÕj-V*. ÄØxd²&ú`½4bw»¼6fÈcqlÛ‚{táKi±. Kwa-Øjn¯õøu±äqyðê]¬ÛbQ/Vnaõr‘ðàXÍãrËY‘˜=$Õ=1ž$µ“'Œ$XÀåÎÞp2ò0yÊ-]’[×-/ &ÏÂ6éŒ$íi9mƒ‰ÛâÔïÊëÏp™ †Ñã}¸p£Þ†…·ãa­öGäm{ `AÚ[°6ÇÐM.äùÙ[°î÷²¶6Â}‡øÈoÁõö¬¡á-Xöhx áx Fx jxò¤á-X„fÂ"Ø[°”5„â5¨ÖK`ðX-d§^&;õàN¡/‚½kŠwkÃëB]"< ݺðIû÷ð¦Ù¿‡@¾¬?ÖK~éVƒ/Þ–.Buìe|zuH¦„«»úÍhå+S×ÞŽÐL×ÖŽ5ªk—Á‹©tyÆhìõ»àq»­¹>ÖP.xÜôXØ4¹°€5=XM“ þu;¯ ¤Úý‘áÔ­¯{mþA@I×à7»?R _à¤ÝðGÚýdRâÁÚqçýí²t/²®o8ßds#¡ Ê½aaÉ4¥cXº¾6$]ï{•-‡HNUb;ìy ^ýH~XÓ¨ÊfDŽ@­N‰HN CÉÖIcÒd òÍä,¤ý¢¬€‚,·êßF3mf'ÐŽ‘ßqù —åÓA¾hö=ÜTì ¡;ÈHŸ0!d»Ãµ_ìÓ€²mÿG ÿGsÁ‚Ъä+1c ö\ûU¨:ÉÍU&8|ÿE–ùäž/§̪dWH³cqÁõ'ô3'‚þú™XR²&rO§nr-6²žé‘± 8 cÁꢸ#IJ¼'Y?`Ë»õ÷v~ëï]È‚Ößþ6å@žô´?%9.”¤É 3IQæe% §4,ˆº ¹1Ö‡ÉÞév¤Ø?DHóšj='Ð ìP),è,Ÿd÷ 6}{e°ÏÛYƒ­Ý>d$ÛµsM',©œ'ˆm—Š&¢šê°Ÿ4 >‡[¥Ø¥‰µI€¥I¿+“~>&9¶¬’» QY͘ šX”ª¾ÁÔ!¼AD0ûtW˜¥ü%È•ÒL`b Ge.»Ðzª˜YOh $z> Ö¡$o%îá›e)“!þîÍËó RЃ[ý<Ÿ'΋ÉKsº`ÓÿQômrè-˜#þžÉ!ââ89BÜ$§ˆiüÜçäðÐøa¤Cn…ÉÁáÖ©bA>‡É[ç«2™uÄ7h*éÌ9â*:T·†‹ Þ:gÄà p¢ æñýL7âk=˜mÄ·¶ã£]‘5¸Hr“Å>í€Ã(ŒIàgŽÌÿSÁ¸¡á'q×LãÖ;®âè÷NÙê\Mø:_:nBk çEW  |ã8ê G½34ÃQïŠÌ U„&qw®!œÛQuç ¾sá²ß¹~¨$†Ë_­Î€ Ç·qñàø6®ܳÁŸ€ %Ù6þ ¾ð¿‚ëÜ•?SxÆâBŽÈ÷î†ÝŠ ¶Z-óØj+ÃVûÃÕ [íG[­¶¤þpü ûÿpÒ“øCݼ­éG6-æ¿ sL…K0…ä$Å ’Ž ä\ ì‹vÒ,$‡ß-¢9Œ\îœ_çú¡Óåä=®_ù¡a¿nŠ“ñCKó£ÿ.«íCƒê#kj©v\•Ö='kïíC³:jŠ$v«˜+[pËTÇ]×|ÑN³^ÏjâÓ¬ |¤ã®aîÞK?έ_’3Lâ7†Ïð ®ñoh„5"S Ã$‘ÚÔGŠÈTÁŒvjµMfôý‘Z/ÇÖ`”)ájaDš¬D_û'^ûw'Ê¥G'܃¨±G¬¨<;bµ0¢fÚŒð>Ó6ü#uÜ©|k³êщGD¯¨Ó;­¯ ¦ÝiÓî460 Ê-5r0íN›2ÌG² Ö§¢ …‚eËé~´EÊ]wü¶Üzn°\Ê]ïeêŸ>¼²wv|÷àI‘z¤2„LÃðm(•ó•ÉôC-®©q@¶ÞÂ’c¦, šmJ÷b°ªÈ$#O%—e2b¥l"š ì/YŠSÓj2b¥ù0LjȗÌÍ©ù0±’!ˆ<åÂfõo§)›máî(ž£`üÙN'¤™\¦ídŒÉ´¡œ³|Fj!MpGÄh™/¬W°¦H3,¨8*ò>ñ®‡/9¢£û•£  =w¸Š*SèQ(J,££“ñüœ¤ä–àäý#o…#eœ¦Ž”qú–áß‹9c¯ëš•S‡}žÎ‰€wZ±G­ätN ÚœÓ,ÆéœÖžÞ;ç"çD4ú¡î½®3œ?²‹° çᜎΪc]‹Î¯=’_O`v ±‰<|ÿ×ñý£ rDNòm}ÿȲ¾˜#r:àœ¤ßzüQùÜ}ÿt™ûþ‘ÃÛ=þ¨ÐìzØ}ÿ7«ö÷kzüo\Óãç|÷ýcÞFN æmäÔÜl#äb>\?Šsè·WŽܪív–?²KÓq±¨Ðy%pîS*Ø¢€9ÆÊÅX«]önÏ®ÞíYeØªË ð·\džê³0þVvÞ þVr-þ–v 8‡s»Ì™»r¥ ¹Þ®s¸Ð¹- xW:¸î¾B‘ÈÎWoxŽ2næ t²Ú`EC»,é\‹‹”pZ ¨d¥ 'Wcà~œ“‚wÐéê°Í³wocs #ίAz¶sR„wŽûl,ŒbΨü$v¡,Î"vê¹ÍAÎwTëõ]\7Bì9ƒuÀ»4±wiDsžã`3c8}>°«Y**—ÛÁ[&ž;߇Øcˆµ%{ Y5ìüVG…,ð©–q—á+îŬqÀ~v¸¦wà¥q¸‡tÇߎÜúaûÆmÿÆtÇ=Ç= >jv€=æÈÿ¸óuðs7“ |Å3J3r¯€=æMç^!ÿ{Žvpßs#Í(¢öø£¢v:÷ Y4ÓÏ‚ØϨYvIQrª‚pÚ9bìèä9Ÿ¦s¯Dï‚4ãïNrAÞ©ä4¼k çxÓèýàvÇ{šdþ~üë«7;¨xÎÀW¬É ìwç•+GòJ%y¥ÇJ“¼ÒcJ^é±2¥î•2¡šyÞ±’%ÛX¬R÷J™R´\⊘úY)“³'±‚&¯ôXY“³'±Ð%gOb%NÎžÄ lïaåN¶÷«O=Ê0q}—#¡5QÔ#¡Ø" ’à#k® ºQƒ=½Û –`x·Aô²ïiaïxwô˜ã–šë¨$muïx©Eå®Y¼ãášQû…k¦½£¦Õ_¸f”­kz¥Çž¼ÒWU€xWOÀÞÕÑÏКKCúÖ’Wzh ©º _Õ÷h­{@ãH¶Ù ‰$Ûl•a\ß?ÚhÕ´5š¤Tj:©úþœ’¾d…•{kL©xü±ºØN«Œûþ±*ØNS¼Ço¶³'Y_¢Ž ßB¶Œh²³`q§”-)™€šc*¡i¢âÞãwǶKêKÔ³1,mMv}7ϭɦlMó?[ÓÄœÏÖt0ϳËÿ1·³Ë/Æ·uo˜ÃΤÄ%W'a£LîY@ß® ¬1”É…×Ø@Svuû!º¼ s2_ÛNHÉnˆâ{']‘ÂÃÜ {l°FHöâûaaŽ…=†yöXdªAjìsßå]á/xa× ÔÎ{$.þ²r £\¨uñ—eËñÝlï FQ³òb3¸äš)Œ¢=]מ.¼I•‹¿Ìž.¼=É5N˜eÉÎu<™Ëi9ë…ºã³&Š,ú+e°yØË‹l4çc¬_ -–î³&7!òZrÚÁÎjtV+¶Þ˜y £­è¯Áé ŽÌÔU`ªà9æ ÷‘rWixFppªuCFÓ;\>+‡{ÍŒ¹¹ "7œYî ™q²r ø²ÿ¦ƒÊ™M”K’ñp fÛ#‡ÊòÅZ÷jcðÕ½RÇž¬g¨Qî!!»Äµ„ä §Sc MØP¯ú£9¹–†5M|-oJˆKÿ¨ ãÈœÍébl~W†/ÑŒAÆ5J|Ýan© [¡Ê™:›ÿ1îÔv"<®—K\[‰ü)çf­quzØšbZ°Õ|® 6…Qiƒø­™ ºÝÃbM wËƲN[Äݾ@áž|åYvoVIÐ85y”eᲘÂò•­¦çÛ¡ŽzÜ"u…7eœ*—GPä’=šó»˜’A¦ØS~ã´p3®8úØJ¤„#Ó¯¸ ÁNÿÅò. $cäÛ+h¶çíÈ Ó‰ Ù¥™fŠ0—¼1# »N+R.îÒ¨êCý¾f{G+&:ö²»Àÿª22ÂÒ´ê«UÄLõÏߥò@  D— ‹éÐMÕ‰±P]"°—^5ÛvÇh¶ eÓ­…~›Ü °'ìð¶Åæ°¶E5r[T(MRQ(!¥TÎNÅ“P‹ë(ñË"‰ª`IYá~œÆ‡-2òø°Ez±Ø’\j7ØÞÙéykX51Bj5Y&;Ñ IÚº3¶Т U =“£TâÏ,&Kðt­àhªö^Vyÿ <ÎJ0-p¤WžÐÝ´:G¤2„©U—QB8;ùnÒ锵2ãžÍ&•éñ"+#A½¨¹äe ¼ßÌÞB^€ïî4ºŒÊ*ÍÄŒ™¨Õ.cÒßBë3uµ»Øaëî˜7@½!Ö§†§\i½íH¥ãêÌ´<-Ô¨(rG2êËjKGuŠN‚çTí¨;i§M|ÝÔ¤ )K²‡t9¶Ù4C™œˆ˜úP£[x)„•ÙŠÊEI©úrvv`ÎòƒGdt¥(0£š/À]!W>#²>?ª Ã”žŠì­™¬8©—hÌÌï/V·%)u†’ÚQ \”{ÀžZúûXA5‘8áZ0ö%QÐl°šŽ×Ŧ\”˜Î­lIÄZ‹Ö6ÆKMŒßMµØ½´”kƒc,›ŠAJŒ»{)ãòêVX­©þ‚…Õ Í{i:›HÆo‰‰Fqõ:1Úét3ÖÖžæèeaF¾ÄšEõ©`@gÎIDÔ.ògD· ÷jù¬ ü ®Ó*®£òÎ9YÏ Qˆé\ ö½tÖ<ôÝiÀ%üí çˆÒÃ_§6(,çÌóÚ‘ð<¢ª~˱ӵs÷F ]s}<üZ‘aÎ^ŽTce)Ž~÷óŠz :j=v¿À¢èÎ>Gãjg.`°m/¯™Ã7Â(w²~‹¨8—FÑi¥ëþii{ËÞ]ogÀJÌÞfvGþß¿X˜˜`°~•b›êI·Mª,MéÄÆ°‘¥ìbiOΪo´IµàEKòh–ÆFkNqMZ÷›ÔYöôlU'ãÂ&­NÇÅ/®NÈ…MªêA¦ø&gÝÓâM–>y mg'â‡ÛaAaJVì1ÒÉrU6)Y~†KOá»ÛùœñHuDŸ%@%uþ¬-Ì7”â“ñŽ¤ŒAØ"Òѱ”¨N„q |dôÂiêâ¿Q³Y0¢ÙyÆ–¨Ès†ƒD`†3GχŽdeÒÏ+Ÿ1Ý°*·Ì™=·xgìÂm!ê”/˜=°å ΨF/nƒÎ.k7•eÂɬ  7“3±îi‹ëlÂ+tW„­EÕDb/5ô„ÛAíËF¯ýò½$$AªÐ5a‡VÇÍ‹ìEXº'ý!]¬Îa®%õpõ€²:’ò$‡‹‘ +©EtçÉ·Še!9JT,´·Ì8Å.åÔuÎZ´¥)â}tû88"p[¢m:t»B0xk&kVó%pæ3|LRyàÚÊrF²]6 !˜ܼ•3^#^_Nž.XAô̱y.ˆvOBç½!i@º3|EíÔ¹_*´ËæcJ;f‰¨2x±k:6f‘ž9T{Ë4L–s EQZ‘’Æ‚¹ÐneUàhs¨é«]bp/N.I‰É+jä‹ÞÅ=æø—³” ©‹ôz® .q§ï¬È­›àès }bŸ7%%䤸,?±$uj’R1ÐX&n§ò8¤ÉÞhjÌŠéVÊü.·¬|1áIºåE+’#Êî¶î½–“ì<½ŸLäÒr€ cªäÀÌ” YYƯfÈ,íÖÎpù¯÷U˜ÉFºjÓXaBÕ`†¾“™$'Ç/#§NÜÉ“¶£´)µ¢0AÊõ[LN’ó“™ÙN:a¸“E “`¼¥3éD¡žÂ$Wø(©";ûŸeÆ2˜ m ËA¹lÖuÒ!CÁ •°#Kµ) -z«gˆÌÉgìs:ìëaèU*@£%  «3l¨UêvnÑx$EX¯`<³zDÑþÎ%’)ÑÄHö7ta‡˜†ª„¼®†¸Æ(Šï„€ŒÆñõ÷ù Ìáò!+QÚ¤çÎnI dëþGزllbgûz®p†Ç¦oßG¦»}ÐùaìmSó»Îb†«¾dºá#)õ(H}IÍJ¡Ž‰1'»×Ô¨gö[’r™é’¯æеo®YÌÁ5]ÓAåF…'ðQ&×ñeÚµzðŒ%WÆ!+l_Zòž‰rºNEÛJ³Ä^ždTñTœ¤:”Œ,Òtù-aA5²†é]a ê’ý‚-¨I¨·ŒE¤NÙ˜¨AU~DF–¸Rè&ñr€é«æ Üñ•åHàz‡¸ò´•‰•Q¸§C¤JÈðÚö)Ûf·n2m-_4ƻְÛ]íØ«¹k·½)•Ð7a¦øZ=.–FŠ?Á •’*^5m9φZ@c’ªcjŸ^MFÓÚÁðñ(îÕÂV zÏ ­µ³²Y·ƒÖ­²wXF¯ÄÜt±œx”JœÐL4©Ó¨3šZ%_‚îúIšüdÁ~SõêïïØû’öI$$ †Sø8Y(מ|ª |`@“8¶ PÓÞ<õ_KJ•Àÿ·æÏ“o”ôY’B†tµOP)‘UÇ°ätf>bÇY†2ÖÛÌpm[šãl XÒîÎõ5YŠeNR¶xöu‘ )RŠ¤ÈZÃ`¹<’lI- <YÉÙ'Iµ ‰+ä5ŒK倬2iY²x9Õ* ÀS–½ 6n—¯㜫 ?sˆT¡ Ÿ„ËÊa²Å?0æÔ£HÚòk‚åwŽs$¿‚?‡¯…îŽëß‘‡R`N¦i~g®ðïÇ¿¾ò(¥áUºòí6†ã¼»`•9. ņWBÖ|‚Æõ ,Å…*cí~~pµw©B•*—Âín/õÅ,(ä]xÀ'ãrCfi¸ ‘—'*3C|޵˱++?#%(©ÄÒsKüš|³“½Þ+TE0 Ç9 UhØÀíCÆÆd‚8X“¬z*ý©ÈPAaE’‚ÎU’úÑ7žZ˨ø±ŠÄ÷*)R˜YD®ˆ §žmÞÜÉÖûÆ!½'™™%:„‹éqé²1þ3Íï?;íð·ž4™mQ½âº€%V¯3»Ôê;cÏ·Ò…¹yk<;kòVÐ ýöÁyµ¹LÆVpkýÆa¥Û†!|6&à }éGºç¦<Ü€­NвèKðø¨yMRÕ¼æ‚Ü-p# ê}žè>Pø;11Dyù}¨b¡³Jç–!xdí4± ®¡f®Ž<(,©ò1açJ9³Wè+t©œsÝâ—&1:¤cMp ^RÚ_º˜x"{O))DÀî=vøa’šøb°’œXì!ª–"Ї“ >î“_„!OrÞ@ÇLR'CY;7´>ÖÉÄ°K>{öXˆÒÕ¤Â(´µIÊvÆf—´SQÓ$¢»XíǽBDŽ°¡4ùkè á¯aE,ºn‰H%ôý¬ŒDíœ:‰@ =Æ“ŽdZˆØom\bt*ÂfY»*rñÖGG Ôνœ‡]ÉõΓbÔm‡Þ(í ©æ6xÙõ<Ë¿Å9•Õì=¡Ä:OiÖ¨ºÉÊõKIùàzððs+¯œ¯yöÔFì=+‡‘¾iTv‹|ÛŒ,uØJì-èƒø˜yïÓ`Ø›/ó‹l \®LHO\6ØW÷Q&™U '¤(‡>#ºdéNtàè %ú§´¿§ÁJ Yˆ•ÁªŸl“ˆåmÌïvéBün·“g_‡‡Ú%Œä¤¿Ë5,±œÖfV¨t:«òD–!Yz9³*(dú±Ák-Zj1Àtâ¢Êâ «Ág‚1Õ¹D& ôFœ˜éìºúÑ—TíÉùTÔ›‹F×+d˜pYU”yp>È@Eª|¾µÃwæ:€Gª #»³V÷\]Ò¯p§Í{¾…öÚ3—Y×·;ÓÔæLA?»u ¢ÍÙm]ϯÑž®}vŸä—+s‘ÿ~¹åÁM'qŽÞÂü*W„2JÁ…ßAkÁ6¡–^t¹%Y¾l€® ¸NÖcˆH\MØä¿¿˜“‘TIXz05,Ç ±¨«9¿±OFDGõ<Æ+ÉϨÊMöI 16ÉUý~`·†6—QhéU<­èú.teÓæ¡ìX}—Ù¨Ón“:KlÓé™zè'pS™]Χ7f©Z?¡ÛIóXQ.ŸB‡üdUæq]v'íäøŠ²<“m•+2/é#L¦0kP‘ªÌž€ªrã‘gÉÙ …>$…fîÌÈÌ„ukÏL\Éz^Ì<³Ý‚Éù ¨PL^3#­âÀ ¦¶™›¶×#êÀθ©øT¼¾óy²âÆ×á`­ŒïR·Ì¶!õwµþòïú¼BÌ1¯­xÝ}Ï©3ÃRê¢L%”>;9U¥4­õth*ä}”]—˜ã]Gb¦²2Yú¤&G¨œ)ëH;žµÎdC`,©áW¢}b{›}¥W'¤D¤ê=,ñD)Ùð÷vO&¹*Cáêá°IL@R¶4“I“:Á%º*}r&1E©|ÆI ½&’œû‰ÉHêõ›’’š¤¸eŒ%_*åÛ'ÎeáH‰»­ !E½™Ö»¤n‰IëÑmŒ»l ­ÈºÂ몬ÓÀ¦Ší„ðÿZ¨ø· ORsfU²æ,èdRÞÑ{8Ë¥›Tûf}ˆ:YvvÏ®‰Kô«©j?±žÅ+7úùDàÇõz ûzÖ¾Â%2ëxÐp´n”Õ«›E YœÔ®1Lƒ5‰öõfbÊ‘2’e_%æNÜ>F<íFÊXº£Œ°kó©sgõ§ßÙ:ž[í¿Ëã³óXx²„w2µ"«+Ëx²²o2}%ròr æYÙ:L×ÈS^p¦&·hF‚¼ë3\JÙÁ<Õ6féXÔi¤W±.o8Uì*ƒÍt~:@'ëéÞø¼äîÎõwÒ‡:OÐÕoÇ6–»u2økºu2Ú_LR(†e¹Ù–g\’ÍÎú2íeC¹+âà¹Tï­ùoâãÞ¼gaËÏÊø§Àu[JËú½“ïl?úŸª™94YÕÉœÖYÝtòäùËոƉ’˹žÙ8ð²îˆyreãuR<æ6yn ­c¡éÄ¿ éLæðÙÑB³ÊPThÅó×—«-IyW0?3øn¬yÀ³_X{?öl‡s„§çGŠªÀ=æMRÀÒ¨õI6Ö5yð¡uÿ1bM¬kÂNŽ¹‹ýÛÁgîyêÈ!EnªÄÉú8«.”dÌ鬛³úaØ3YÕÄ{fE°ï–ú–tzç|r/ûëx¤,‰Æ©ûìW8ºß[øžº}ÃДFa|jvö\¬.’~3w3c­wø’jyR0‡I'õ`§‹2©¹)s]’º›fÖ)øýAL6ük¬Gоžéûk>—öîQiÄÔ­ÔâÔ_b®Å7¿kœÚæ(O«Xjûš“ßÕž1©³Ú7ŸvµSÔY•e?¨³j_d~¼~cBÌÌ¿Egö²¸,t‘έô¶‘TåÝö9&–(ëô{'JÜQ=Æj€¤î"Œ Û+L•jüIǤú:ís¬ZáìÂܳ³‹-0¥±KvEbÖY&›%uIˆ¤é˜!k¥²ÒÈû%uqë@¬RWæÄJ ;yo®xO…+‡||¬æѾÅâ©$›˜>/û¶éRÍꌤý^9š‰>õËß%öwû9žòß…þÔŒ©?·°;©Ææìïb/·ãÎÀœýwo&ÍKO¥‡Êã†5ZÙ³Œ)å’íTĺ/ýkBÖ9Ω²ŽWϱê´àƒÊ5ù]±—$¬o9âTwÝz#…ÕþÖN{> Ùq*ÍNIiþ7zÂÚNÒÉJ9à4u­¸tgaYÉZ+è†ÏZCèæϪbätÌ]¿Ř4ÿ({-{nÃVqm¼ô¡8Ýž{¶ü@ÜŸ´¾I7RÌ ¡ë^Vu&Kcs—x²âä}»n_'Úwg†ó»ÊgþhÈçæçKßUü-ïë3¿Ü—åÈÎgÍ—êÿå—ºˆå—Êô¯h¬Œ#i]íu뉽´fÖóçD@ƒÑ]ÕüçÌ“£naŒ›\—™z³c…½ºíÞ5ü¹p>È7V4œE¿Žö¼wÊmÍŒ/Uï‰ð UûÃðL'¬Ô´¿TF¡“³%{xc¥Ï•±íùl[=T~Á==«¢‘*Uœ]é²_ ¿Ëv8ʪLVx<ÛÐö)Úì)ìkÈŒ§SO2®qÖ9_ŸŠ-ù5ÿŠïBªçúWü]¬WñwarMøýø3ÌQ.0¶6›ôàiíÖ²2›áʲ8Z¯D[ ¯pŠ ö]uv ì9T"ñ)°áxž›ô\céLTn”ywÞï±(úÂe2Ým×`$'Þ`»>žfiüê ²2Ü©Þ2ìȤžþôß&ÙU9q¿Ñ}&ÖµëÙ£ã¬ëã1pâU\&Éð݃¾Øþa] ö1j©‹à:š7¬´¦ŠøOès<`N¹áù¢>'?ÖÅšxÅÙé×QYfìÑI† ÌLŸsË×MÝÔçÜ3&çÜ?pKQ‹Ÿ˜“¸<8ùÓãš×ù[ó>÷0ùwµîÃó=³€KšÊ…÷ÚZâ·Ó!ê1áÏóXQ¡ÿÇÔ€ÖŸfŒy¢u0±›û%YÃu8-ž)UëôŒ#x$ú/msÃE³°®“ã¶Æ~ âóØBíÙê®ûg›pÙµ©³úHzU§^¢jV?Úžfâê<¨nÛ·ÌL |Ù€õërÈ`ŸrévsÆxg«1Ö‘fÌ8¾ñëKB›SGÇRgლð»\÷ÁÉz$8)?°ÿ. øêù[)þnŽ8}^©§fWžö¾×MÆzrTª2ñÒñ دj5K—ZVKâԙà =¯SOÒœA2Zv×ÑÛ&_ìUc=‰û½lfØxYÅ LUɪp£ªž‹çÏÌxPq\:Pq\ïš¡7ÓšÕ±.ËOY¼Gl=›Ó}aï#œÞkÀ÷^ÓwÿúõsÖ>ˆ ̾øœä/Ï<«5{aÜʾê%Í{%䶷™µW¼Ïâ:Ùûo^8ÒídR²>G]dó}4Æû(½‡>T%Ð4ÉΕÊeŠÍž`…Á Å¢õá»uMnvWõüÖ*SØrœŒb¿•X‹‚Ëï/¦NW÷µaD QõcР»»´;ø²¿¿°µ+¯ø÷/,g°¨¿ìØ-zãLµÄø²csÊe×—}èåF=t‰xÙo¶\fÓº/¿ê½ßl8͆ôß_8¶Æõ}¿™×ÉÑý²$§dk›L*è(öýÅëJó±ò‰;‡ŸÜ%õ7¬U–Òó;ðºùDÄßò[³ˆCÊŽ´>oŒ ž}ò•öW¦çÌ)ÌøÊF)£ûft8þ.Íÿý‹uó¥IGfÚ:\@žtZçKDJŒ$ûçAÆ ¼X|Ÿ=Æ°ÐáôD ÞfÉ„ÐÉ}ÕðÉla{ývéÂ'è Ý®ð>üÖé¬\ÐñI¡þâ;`õ1,ѯK TR‚§Ï®~óqÂ_yù—ª?ÐÅç£~EñDÕ5ùÄ_w¥‘­ó[½/úúê„K÷Tù­N¡¬äûª ¨sÑ~ëô¨„,Š¯N"uÆÚo®ŒD1ôF©Œ©ê;ìýËh"Î+ft°øm§{ðWÝ‹CÄQ0ð¨"gÁ°=@òw¿¬ÊTDŠrª~y%Ã;1¢Õs” è$Áˆ¢L9ºø„ÞÎœ´Þì¾GXošýXoäïôÜÉô´^n5o]ž1«ø/>SƉ{4,¸ØK£ñó®<«”c88˜ö‘†ßQ&1*O®+¢õø„¯¸:0}Õ~åß*np'“V“ò󫤑ú;>¡ á”Ì:ÒÉÚT:|’:ObED /è×þë;ö‚B+­Žx­)ÿv<ýf&CŒÖùnCƒåèhçU‹‹ß¿²ãüs£®È¦@¶'Ãéø$s§±â¹¸Ï”¹:&‡ ö>‘‰þz É"&÷Ùá1.Σ,ðqø쿳ÇüQurwu¬q­[™üÊòt7øgujýèqœÂ7ªï7þ‡‰" ypXÜáDÒeté ðu©•#£ZMX'ª×Ù[<…›v5TïZ›Ž2ÏúÔ5øÚ¦²ŠãåýGÆx8(â_YÜ¡Ðq)—®Æ&2iÙ\ÚîØR(ÇNRŒÒfµØÎþôr2>+T×ËTC&~d¬1Ž„€õ|kìGñl:èä/fŠSë‘å¦7–œN`…%1Úü<ö_䢚˜èQ£Š”pu“ŠÁ R•Û˜ê…`ÿãË Œ¤š:záµþ3I"¹UûBQÊ.">è<ïæ%±·ÿù?ªR-L]÷²ÿàNò(ÅßbÕ¤6ó>FùñH[‘ýªSµÎ€ª‘ç—b&ºm@gf‚Öò*À`!§ìx'¸â*Ë´Ècýûüc©@è¹®¬2ª]Æ\<XÆ ’ÇÜüào•ª¨NurA(%”¡[\èÄvÃÃÎwÀNsVU+ÐÂöô6®Ñ¥c:°ÏªUøù×Wî 7秧ŵ§4ãþíZÕqjUçn~t”› eFXUãÉnÛMû!(Nƒ7Ö÷é®tSýÜX·*ñþ6$€:ˆsZŠƒ‡ïjUŒ£–*çóyø<ä<ÞJ–“‹Û°ý|õùEHÜ,.ºûà_]¸xQkp-ÐLfM¡^íqz³¶ËžõªH§ô‰^'ȱZèJvù]Ã>€a+stúYn’ ¶¾ªýDG ÒÔ/³+*;ÃûZãµÈnž@wJ±Zzþõý7+Vu%ª‡*FWŪzÑ¡rEUk‹Š±£43ùÚU³w$²?PrzgÑ…û1(©£=šZ6jyyV¬²VÔ픨§ÑbðTµœIWº¨-?ÏäN*Š¢uM1¨´j‡â‰I-úÙ³$ùŒÉÆ6ÃO×ÑïmlÙøº·¶Õ»w•­)Fx£üAUøï…÷¿¾:¼9]nlÌJ·ñ„bàçlÍq¹‰iÙ+ºÚ^n™*ø·ÁÔy?û 6ŒY½ºÞM©©å%ìn%y1‘R›’$ÕH–õ¡2ByúLìŽÛ¤f{Í8 Ÿ>„=|dÊl§ŸWï‘Ê£]RQ¡Ð»aË«ÃÓ!ã¤Ì;j0xÈM’û‹MŒ’ÏlÔéÖ8Leõ¦ ßjÌ~)’;¼VD¾½Õ§¥Eª…)´ÑøeÌGs˜gùK)®|_ômŒiõI¬±R<ó~gôwB7:É8áò˜HÀ×N®à¡†©i*:Skw»ö¾V'K°“Tj*èz—Œ½*㱊(uBçÍ%yL-Qí=ÃW=šB¢rÅéàX¥ºOÉ SŒ»kõÅg‰™SØÙHW' 2Ü하ôåf5ò´g¢÷ùRÆ•(íBÅIq2z¸ëNÈ`…¤Æ(ùf½Ûä£=°5òäú®@ãd"‘¤LþU‚j<ÚTAhüg'’¿R­^éé¥Dr;;â'µïÏP Üú™n‡ž•wø(w¶¢V(l›–ÜÌÍ!5î,Úo3Wu‡ãØ2{Fê^ÞéU ‚î”­g°ó• †UÐBu e&+”+ƒ—Nžb`²8!üÞÉmÂR«º" %Ó¢ ”<å„IÛ¤ÛNXv>”ƒ*‹Bo7ç+DK±Û†%†Â=£U9=¶1¬V•6T»Êm*Ógk·Ë=oîÅu˜k4 íÞÇý8”€ÔW‡^.Øß9û/¿þátC«Á»'}'°´q¬áœuôÍ©áî Žqþê´-.Žqþþ#\ã$üõ¹À!nŽ{„Láïß8ÂýÁÙÚñ÷oáñàaòÇ‘ ÏÇØ ¤¿ãߎp÷ÞEþÙÇ„¥M‰¸ ÿÆNŽqþþ#œã$Lþ}äÂåÁnSøû7Žp}pŒ»ðWç…ܸ=8ÆEøûæ÷Ç8 ßãñà³Aøâ¹ñ|pŒ»ð÷Í1¾ã"L~ÞrazMNà$ü}sŒÓƒ³mâï›cœã.L~Ùrãòà[þ}sŒëƒcœ„ɯGÿnŽ- )ü}sŒûƒcÜ…¿oŽñxpŒ‹ðק[n<ãôÙŽíÇø~p„Ù‰vÞÛÝ]âxs`Ysâ¶üûæ§Ǹßãüà[Ï%l¹qyp„/7Èÿ¾9ÆõÁ1îÂß7Ǹ=8ÆE˜ü¹åÆýÁ1NÂß7Çx<8²poË¿îÈk¹ñ|pŒ»ð÷Í1¾ã"ü}sˆkœñ^8 }ð½åÆéÁÆÞZ¬xrŒóƒcÜ…ÉO[n\ã"ü}sŒëƒclù÷Í1nη-¥çû°«ÌycòË–ÏÇ8 ßát¼%Ç_ºrãôà¤óÛSzðÓƒŸœ7&¿m¹ñcÌWáï›cÜœ7þªyÈûƒ³ýaÄß7Çx<8oLþØrãùàÌ3—Ò|ðçáÛEÎß0ùsËÓƒc<„¿oŽq~pÞø«ƒtCn\œrÞ\üòà·çÁ§UîÃ|…ûƒc| ßãñà¼1ùiËçƒãõêþ¾9Âå:œ¿aòó–§ç±•ôà§??8oL~Ùrãòàgáï›cÜœ7&¿n¹qpúY{Kðûƒ?œ7&¿m¹ñ|pŒ«ð÷͎ëë?còû–~ŽqûDPüÉ1ÎΓ?¶Ü¸<8eïeÀß7Ǹ=8oLþÜrãþàáï›c<œ7&ÿÞrãùàœ½»ÖùàÏÃo×áü ƒÏpœäÆéÁ1¾…¿oŽq~pÞøûæ—Çú•åß7Ǹ>8o¼ÇSrãöà¼ñž?­ù㾘âý x¿­Ÿ÷±ç÷úÓë•üqæg὞û`qáûÁyã½µûì_ö]ó7¼õîý…8=8Æ–o}ÆíÑ…óƒóÆ¡Zn\ã*¼Ó]|¨ºp}pÞ8ì)ËÛƒóÆaoZnÜã&ö~ÈïÓÔÜœ7HÈ…çƒcl9ùåÈ…ïçÉOGNlßÅÕÿƒÏ}Öráôàaòráüà¼1ùåȅ˃sì£jÿõRË…ëƒóÆŒ*>äÂíÁycòû‘ ÷Çø&¿¹ðxpÞ˜ütäÂóÁ¦Ý!ÿýN!¾œ7&¿¹"‰×áü “_Ž\8=8ÆI˜ütäÂùÁycðÙ¼ßráòàgaòû‘ ×çÉ/G.Üœ7&?¹ppŒ‹0ø<(Àráñà¼1ùýÈ…çƒc\…ÉÈ…ïçÉOGN>úÏ|P`¹pzpŒÝF„ü~äÂùÁycòË‘ —Ǹ “ŸŽ\¸>8o >÷\Ë…ÛƒóÆä?äÂýÁ1Âä—#ΓŸŽ<Ÿh¾9ÀÿúùŸ¿Òç¿s=þ À~ýå´×c³Óåï>t’ÿçÿúõ/¿®¿ÖÀÿ¯uÿ¼þ÷?~]ŸÿóG:§æj>¾2Û›Jè¼ü.¿‡|ÝþóøUèÿ¯×ñuÛ¥ß8b­´S|äÉ žà<Þ³ç!°÷bêä–+6{ŸùïÜ‚ ó¥}š^1ä¨(Óp¶+áW9¢[zû„^Üuë!%¼Á°~Õa+¤€÷µ ³Ó ²/CJ˜Á0’[·”0‚áEøUÓï–CxÁ¯ºw…”°‚àÚš^!„pCJØÁPÒ¯:Š…”°‚á üª›˜¥‚ã ;áW]È,œ‡ð‚_u/³Tð>ÃFHn )`wŠ³ %%wKÓ!–s–‘Bk©`>ÃLHî ©`9„$÷©`=ÃDnJ!l‡`x’›C*ØA Ð/=·TB*8Áp~Õ!ØRÁy/Hn©à}†ƒð«K å $!`'$w†T0‚a#7_!̇`X ÉM!,‡ð‚_%/[*XÁ°’[B*ØÁ0~ÕôßRÁ~†‰ÜRÁq/Hî©à<„¿ÑåRDá“¥‚÷!®åð«$EK åX$!à$$7…T0‚á üª¾ÄRÁ|/Hn ©`9ÃþQ­ O ³T°‚¡¤än©`;ÃJøUºŒ¥‚ý !¹wHÇ!¼ ¸õ ©à<ÃLHn ©à}†’~ÕÝÛRÂrmBÀ‹ÜRÁt‚kKïrW¢Kƒ¥‚ù^ÜRÁr†“ÜRÁz†ƒÜ;¤‚í ;áWÇÀD–a?ÃFHn ©à8„üªVÊRÁy†•ÜRÁû !¹-¤„rd’0’;B*˜Á0’;C*˜áɽC*XÁð"·_!¬‡ ˆ7@§Û¢‹ ¥‚í '!¹%¤‚ý !¹5¤‚ã^ÜRÁy†ðû"Þ‡`(é÷E t]y@÷+©`:„ŒqT0‚¡¤1¾nKXÁPÒï‹ XÁ0}¢6«§ ¶C0¼c>´¶çCt†ý'óÌ'4ŽCÌ’ÆümcÏ_'%’`(é÷E¼ÁpÆ;䦟°’ÛC*˜áã=îi¿ÇîÍO‚¡¤±>ô¼×‡^ÁPÒï‹ XÁ°Æ%©`;ÃLHn©`?„Œu²ŸuÒç`(i¬¿}ìõ×ýI0”ôû"Þ‡ Èó}î½ô{ïq>ÂNÂØ[Ƶ÷9+ExArGHó!Jú}Ë!vÂØ }j#a=ÃF{ìðþY&VÂØ»]CBØáC'pmá8CI¿/‚à<ÃLHn©à}†‰0t˜áç–|"¥oºÑôsL‡ð‚¡sMë“€ùò¾™7n9„²æ´>9C*X¡îá›uëˆÓú$àyX;aèžq¸m÷iX&ô=fß:í´>Ù|€• cOOùKÁys¿"ò—P™ž®Ev€Ý!$œuòÎÛ¾¸ýÜÏ:°†ÝâFé„õê^âoÛowHÛ!´½uÜmÛN·í·8ÐÌ„³¿Ù_r¤‚g ¨3ÈÂ~»ýf' †™0ìBûKïC0,Ÿn GGÏmÁ%iå@IÉ­!L‡`Ø ¿/‚`>ÃAhûØRÁr†7¡ínKë!lÕrØ_²fŸ¥‚ív°¿$o©`?ÃLø}Ç!ÖÏÉRÁyÛ$á/™!¼Á°Ú_2Ž¿dØIB@I¿/‚`:„m¿ ûKp Ÿý%„ùlw_„ä¶ –C0LîÒAg‘¥‚õ ¡ýQ– ¶CØv÷°¿äû!6BûÄ,‡`Ø ík³Tp‚á$$÷ ©à}Û_2ì/¹îI@™hÉ!¦C0L„ö9Z*˜Á°Ú—i©`9„íçö—à0GûKë!6BûS-l‡`8¿/‚`?ÃIhŸ®¥‚㶫rØ_r• ÎC°_ù"$7‡Tð>CI¿/¡$ã !¹)¤‚éN»ûKÖzj©`>ÃF¸¸pÀ‡”°‚á $wn)a=CI¿oa;„Åñ€±¥„ý±I„äö-%‡`˜ Ém[J8Á°’[·”ð>„Òå>Ü{sí$™Ø É-[J˜Áp’›·”0‚á$$7m)a9À\ꯌÐ×_E»èS—] ÓGJø”—Qæ}ãøçæñåÍã‘´†ƒ—í:óÂûÜÌâf½[ß}+;÷Ü»ïý×î¼}çt¨#Ì?~±EpVõ|š‚² K„dí×µ¥„ù^ð«£FBJXá¿jËi©`=„üFû±G'²v†™ÜñÙÊû!¼à×mÊÜ¥–p ~Ý@LRÁy/Hî©à}/øõ’º‚„7üêÜï§c¦C0””ÜRÁ|/øU?KË!¼ ¸G*XáÉ!l‡ð‚äÎ öCxÁ}Ý~®;Áð"ü¾„µlÂ~Õb>ºß¶CD?ÉÚ·mn4D¾ÿÉm!̇`ÈƇ›w ~Õ[ÃRÁy†ƒðû"º ®,y¯ªE-l‡`È~ЇÛ6W•±$¼á×Gl ·̇`Ø¿/‚à<„Œ9én€„÷!VÂï‹@èF‰ ,„_·¥v¡,O:É›0òºC*x‚a"$w†Ð ¢AØð"üú¸7wXLy {àmnʇ[áÉí!¼Áp~_Bo ¼!¹-¤‚ý á÷E‡ð‚^£,%ôÂB@¶fÙ\¯Q„õ^ÜRB7æá ¿/‚`:„»TÍuÃ?ó!ì׿Ô|¸ùpË!xê„ßA°‚ šUÕz¸õpÛ!¢û ×³Cì‡`8¿/‚à8=!´ä©ãpÇáÎCĹ‹nÌÙÓ–Þ‡`8 ¿oBgߥM0Ä™†^Ât‚hýÓÒá¦Ã͇`x~ßÂr‚hŠÔÊá–í‡ ˆ®Ž­n=Üv€¡¨Bú ’ï¿äFzÎ[´woîÍ—Š*[µmýI§èúh éV  ¬º)×?~±£I)j™‰'®ÓÕ¤™„€—ß7aøÕ0Açž«­&š;nÂô«a‚aó»ó"–C0,~w^Âz†—ßÄ#Ç-%l‡ 8¦ß°‚aó»Ã&0%N=½üj˜`Xüî< ‚ó /¿;O‚à}‚=Þ«ÆRBµ«#!`¼;O‚`:ÃxwŽk°T0‚áåwçI,‡ ˆ¥ïΓ XÁ°ùÝIå*!l‡`˜ ¿/‚`?ËÜRÁq‚èØÆáŽÃ‡`Ø¿/‚à}†™Ü-%TÓu^õ·xÓ!¢[÷së!̇`X?êkñ$–C0Ìõ´xë!¢E]÷s!l‡`(é÷Eì‡`È–pâÎ ŽC0Ìõ°xç!¢ `Ÿ‡;÷>ÃñQï v“-q šø]›°~Ô·âIL‡`˜££3ŽµT0‚ ¯7n9ÃñQ¯Š'A° ’›B*ØáÉÝÝ5Ç!ÎúM< ‚÷!¼ ¹%¤„óÚ„€÷G}#žÁt/øÕÑ– žA5T£ÃÃ͇[áÉm!l‡`˜>êûð$öCxAr{HÇ!Œ=5æ8Üq¸÷!¼ ¹#¤„÷µ ‹¯> ‚é^ðëî–qJ*`>„¼§ý7n=„$÷©`;ÃöQß…'A° ‚‹vß’ ŽC0ìõ[xïCxArSH}xŽú&< ‚é^ÜRÁ|†ó£~ O‚`=„$·„T°B‹eP}žÁ~/Hn ©à8¯Õ×GýžÁû^ÜRB8BBÀôQ_„'A0 ’ÛC*˜!ÇÖ¡~O‚`=„$w„T°‚aù¨“ ØáÉ!‡°·Eõ?xïCxArïæk¶ú< ‚é^\ôR–T0‚aÿ¨ßÁ“ XáÉM!l‡°u õ9xû!¼ ¹9¤‚ã çGý žÁû^ÜRÂrmBÀû£¾O‚`:„$·†T0‚õ¾ë£~O‚`=„$·…T°‚aú¨Á“ ØáÉí!‡`˜?ê_ð$Þ‡ð‚äŽÚL!`ù¨oÁ“ ˜áÉ!̇°õjÕŽ= ‚õ^Ü;¤‚í ÛG} žÁ~/îú]– ŽC0ìŸjÛôïCxArSH md‚p|ªíÍCL‡ð‚ßA0‚áüTÛ›øñ¶7 Ë!¼`ÌÛ›„õ^0Þ Û›„í ïOmg-ig-±‘I Æ:i{“p‚íÍëSmobå²½I8ácß´½Ix †®ÑŽ^rŒÌ %µe©`:„´Žh©`>Ãü©}ëÕ– –CxAÛ – ÖCxAÛY5ìMÀv†åS½Y½éÃJExAÛó5ìÍ8ÒÀCIíרaoÎCxAû˜BJx Ú×R@™ lõH8,¤„é^ܼ¥„ù ûGýRž÷––CxArÇ–ÖCxArÛ–¶C0õ H8Î#¤„ý^ÜkK Ç!Îzð\§ÎCxArÛ–Þ‡ð‚äæ-´ñ BÀû£þôì…”0 ‚»æXH ó!¶ë£¾ôì…”° ’›·”° ’{¤„í ÓG½èÙÛRÀ~/Hn;RÀq€á+Ç.õ×Þ9ÐÎ><×·FËþýä\‘l~ÒÉÏŽ‡^Y¿G<¨à¸Åïí å‹HÙþÌØàñJy/šg«Á¤ñN‚cO¼aâ§Z7iu«J88%û&ç6Bú±áƱñòØb¼û6»öMÂ×nÛ“¹¬8xh2•Uè&J]>Ĭ-K/dísÓNŧBè2ÓŒE«îø(íO…&xÓ2¡¼?}"ðnË„ÊþTh-^º,ªûS¡Nôåq'’ µý©P#¯X&Ô÷§B•¼j™ÐØŸ>xÍ2¡¹?*Dà Ë„îý©P&oZF¤FþøÔ(w[&”ö§BÑâåË2¡¼?}"ð²eBeJ4o"ðŠeBu*4‰À«– µý©Ð ¯[&Ô÷§B’2¡±?}"ð¦eBs*ÔˆÀ»-º÷§B•hñJ²Œˆv0?5*XÕ–í!™PÚŸ I^È„òþô‰À‹“Ÿ„ÊþT(×-ªûS¡‹¼a™PÛŸ­Åï¦ùŒó&$êûS!ÉpÒÐe™ÐØŸ>xÉ2¡¹?DàeË„îý©P'¯XFD»™Ÿ5"ðšeBi*T‰Àë– åýé7,*ûS¡BÞm™PÝŸ e¢Å[Û‚dBm*”ˆÀK– õýé—-ûS¡‹èËs•$šûS¢~×,º÷§B“¼n‘ŽçÀ§Fƒ¼ ¥ýéw[&”÷§Bhñ–J"™PÙŸ 5"ð’eBu*T‰À+– µý©dà…L¨ïOŸ¼f™ÐØŸ åγk¼g>¢¹?JDàMË„îý©ÐEÞm‘šÁ§qäÌGtâ”7É„Òþô‰ÀË– åý©Ð$¯X&Tö§Bƒ¼j™PÝŸ u"ðšeBm*$xÃ2¡¾?}"ð¦eBc*T‰t@©dBs*Tˆk,eB÷þT(—-#êW|j”ˆÀ+– ¥ýéW-ÊûS¡‹¼n™PÙŸam¢ Ž@’ Õý©Ð$oZ&Ôö§Bƒ¼Û2¡¾?}¢Åƒ®B™ÐØŸ u"ð²eBs*ÔˆÀ+– ÝûS¡J^Ȉt >5*DàuË„Òþô‰À– åý©P&oZ&Tö§Bé£S,u•²¯W÷§BÑ÷ñ©PÛŸ>QüŽ¶Gߟ>‘Çeô=.c:öèyTË„æþtî_´ŸÇØÏCÇBñÓ{нywðæ~ FÈó@¥ýiŠ1SÌ«™b^ͼ?Í1æžÇe™PÙŸ–˜Ù³Ä|ž%æóÜo…Þ¨Y7¯n^ÛŸ¶xCg‹÷h¶xtD?í±2ÐLæÛH™ÐØŸŽXiæÛM™Ð^¥ŒxÍ2¡{zÇÊ:ïÍ»ƒw_ñ©Ñ ò:t_±Ýiº÷;źv§X×î½agºs¬“wŽuò.ûS¡Dô}|*T÷§B’y}¾k¬Ï:(ŸîýÖó¸,êûS¡Fä}áî±/Üc*Ô‰¼ÏÜ#ö™{îO…ÆG§=ŸO…îýéÖ´dŸñ„<öƒâT0ú£#äd£ ¦CL‚Ú^-5̇ ˜µe[jX!ô`Âï“`XA° Je°Ô°‚`”b©a?„°LÁM!5‡ x J ²Ôp‚,FK¿O‚á}‚IPj˜¥‚2ßIHa9Jµ³Ô0‚`w„Ô0‚`”ji©a9AK¿O‚a=„°ì ¥ÚZjØAð”ºl©a?y\.A©à–ŽCL‚àæÎCÏ á÷I0¼A° Ê\°TPf> †MP&ˆ¥†é‡ ÌK ó!„gŒðû$–C´Tf•¥†õø„®Kܱ¥‚í³ Ìº öC,‚2C*8A° ~_Áy‚mfÜŽTð>Á!nÙRÃym‚ᔩRÁt‚· Ìï æC DwßK.‚A°‚`þø´Pý!¬‡ èÓDåR©`;Á*øõÐ’ öCì‚ri„Tp‚ ¥ßAp‚à”K%¤‚÷!Þ‚rÓ„”°^› ˆ®¬—\µn©`:Á,(7QHó!Zú}Ë!VA¹©B*XA° ÊõRÁv‚CPî´ öCœ‚pÑÝ[*8AÐÒï‹ 8°$A¹þ¶”ð>Á,(wâ–¶k ‹ \”[J˜0">Ë’aýþâ ¬åF1Œc±´Òâk ùÐ÷¬GŽ¨Å~åì3Ká“¢÷»n¿º,÷v kÛ×ÖËÒÖ34o´ãq8´Iñ‡§ó®I5€ÓC %Ü=2 xÊh§2Si<_~0vÀµ-Yêaö^aH1¬0c“·et„Þd#›Ž‹í˜çK€à“-:üc°âCÍ âÏ› 8Á­[JÈñÁp‚Û¶T0‚`÷Hó!¼ ¸sKË!6Apï-¬‡ X¿¿& /(5l‡ XÁÍ!5ì‡ h)¸[j8áÁ­!5œ‡ ˜Ám!5¼Aðw„T°]› 8nApgH Ó!Z î–æCxÁÅMWH Ë!ApsH ë!vApKH Û!6ApkH û!Z î–ŽCxApGH ç!ApgH ïCÌ‚àÞ!ì×&&ÁÅÍWH Ó!Z n©a>„·„Ô°!KéAœ¨ÌÔ°‚à·…Ô°‚àw„Ô°‚`w†Ôp ‚{‡Ôp‚`\Ür…Ôð>Á*n© ½‡"ApKH Ó!fApkH ó!¼ ¸-¤†å“ ¸#¤†õ/ApgH Û!"¯BI<³Ü!5ì‡ 8·¦ŽCxApsH ç!ApKH ïCì‚àÖ rcÁ° ‚»¥†é« ¸#¤†ù^ÜRÃr‚EÜ;¤†õ³àâ¶RÃv‚–‚»¥†ý/ApKH Ç!¼ ¸5¤†óõ+øÜ4ê|n‚÷!NApGHéÁÐRp·Ô0‚`÷©a>„\\Õ4ó¹ –Cl‚àæÖC¬‚à–¶C´Ü-5ì‡ ˜Áí!5‡ð‚àŽÎCL‚àÎÞ‡ x ‚{‡”°]W ‹¥‹;RH Ó!NApsH ó!¼ ¸%¤†å‡ ¸5¤†õ» ¸=¤†í› ¸#¤†ý« ¸3¤†ã^Ü;¤†ó‹àâÎRÃû³ ¸9¤‚éÚÃ$n ©a:ÁKÜRÃ|/n©a9Bìè.Í «CRÃz‚SÜRÃv‚Cpqï+¤†ý» ¸)¤†ã^ÜRÃy‚MÜRÃû« ¸[*H¥†EÜRÃt‚YÜRÃ|/î ©a9Á$øý…,CK ë!Z î–¶ÿÝÖ½\¹’I˜Þ·W‚:7 G«ÑXŒþ›I¸™æœYÕw¼þ¼ù “ "ÉÓO›}Jö€ÛÒ\ølv»ïÆ*ï&´-Í…Ïf·8^0îÝȶ4>›Ýnà|Á¼wOÛ/Yølv»ëëþŠØ~ɲ{ŸMÁú~ÉêûÕ³ý’eŸÍ¦dzAº¿þ¶_²ì³Ù”Ì/È÷!ÈöK>›Ýn`yA¹m¶_²ìQæä{p¬ï!ÓöK>›Ýn`{A»ñ¶_²ðÙìvû ú}ê°ý’…Ïf·8^0îS’í—H@¾'µúžêl¿Dr½ìàýz×ýz±IbÉ©ÿÚwØ$AðŽKZº?ß–îÏ·½ƒr§­>%Ë p<™À­Y_fÐï­Þû6IÜãÉÖÚ½Ÿµvïg­¿¬ ß[¿÷_l’ ;è¿mÜß l’ ¸5 × î: Ù~ɲßn›‚ý®œœúï±MÉô¬ßè=ÝÇl’ 3è;=ßÇl’ ¸ë·ÖËkËkë À úc_¯÷±›$ÀžöNÉþp€þøÛû}üÅ& ‚»în}ÜÇõ>îãzŸ/¸5 × °_’@néë>·p“D˜AÎß}Îz›$ím4Û/9WÏsJæ€ôçM›’å`·d}8@î8.1¶Ü-¯6Ú=&8.1ö€ ôcããxö'xÚêSr¾ÌàÖ€\/¸[•m¬{l4p\rˆM’!¬ sM—Ó Àú±ÜÄífÌ/èLj·›±¼àn1·ùŽ'ç;žÄ& pç8uù”l/Àù€ú1-öKÀþ‚{>ï̈dì—€ã`ýû%à|XÁ­¹^6Ð×ó­°I2…}Oo7i¢­owi¢O?ê›ÃCšèÓÏôæð”&Úúñæ𒆞ðéW}s3^oÍÿúóÖR>§“4ÑÖ;§³4ѧ·—RÄœ.ÒDŸÞîØÓUšhëÇÓMšóÓÛ}sºK}z»cNi¢­szJ}z»cN/i¢Oo÷aÌáþ½æÇÖ¿9¤‰>½Ý‡1§³4t‡O{9§‹4Ñ;6ô’†nðŽ <¾×üؾþuçt—†®ðŽ =¤‰¶~Þ9<ókÜÞ±¡‹4ÑÖ;§—4t†wlàõ½æÇÖ÷;§»4t‚wlè!M´õíÎÍx±4×ì÷7Îé%ù,v ^#40^êÍ­/wNwiè ïØÐCšhëóÃxù4î[Ÿî.ßkܶþ»sºKC7xdžÒDÛãús¸–׸+¼cCWi¢­Ÿw·ï5îûãçô&Úú~çô”f¾Ûš·ÒÐrkï±hùãík`ŒÛëèúãí›ÓIzÁ;6t–Î Þ±¡‹4pÉðŽ ]¥¡'l}»sºIWÎwlè. |ΑàϼCCiè ïØÐSø,ñgß¡¡—4°ýÞñùE˜Ï)Ö¸l}½s:IOÎwlè, ¼>xdž.ÒÐÞ±¡«4¸ÏsþL<4t“N¼¸KCwxÿ4ðζ¾¼9<¥¡¼xI—ïŸÆŒ—\CCŸu3þ¬<6p’†^ðþià, |–±‹ÇÚÀEšãû‚gk¦ÿlµ†…hx ´s]þ±ï˜ /{ÖñRÛXpd{¢àÃ1ç Äáÿú·Ç‡à"‘v3ðá ¯¹½ÞÝ¥ÉÝ‘KJ{ZJøµ<©~(`‡_ü1Ù« ó.˜íp ?Žb¯mŽo©Ú!>×yh˜“‡Èö:åIŒ»æ9Ôö§ábO·ü÷Ï]¯èk—¹?û ½eäk¶÷Ü;ï:^ð“ù¼£wÁ[Lº3œŸû‚÷oc.Òж~¼9\¥¡+¼¸ICgxÿ4p—¶×ÃÛ´w¿sxHCxÿ4𔆮°õëÍá% áýÓ˜ñ>9hèÊùþià$ =àÓÏïÍá, ]áýÓÀE:ÁÖ§7‡«4pYðþià& ÝáýÓÀ]ºÂÖç7‡‡4t‚÷OOià¼`ëË›ÃKºÃû§1ãŸÐ¸+¼8IC'Øz™ÃYøv–¥ÏÒièÒÐœ[ßÞnÒÐ Þ? Ü¥í=5oßþæð†æ|ÿ4ð”†.ðþià% `ëÇ››û÷Ø–M£¯g'iè[ÿæt–†.ðŽ ]¤¡¼cCWi`Ÿ[¿îœnÒÐÞ±¡»4tO 9§‡4t‚wlè) lÛ}J?¥_ÒÐ ¶>Ý9<¾×¸ ¼cC'ièÞ±¡³4ðYb¼e?§û9§‹4tƒwlè* ]`ëËÓMúƒwlè. Ü&¼cCiè[_ÒÐÞ±¡—4ô[ßîžßkèsšfÌïõó“>ICs¾cCgiè [ßïœ.ÒмcCWiàsì8&oßqçt“†nðŽ Ý¥¡3¼cCiè¶~Þ9=¥ó€wlè% Ýàx}¯qgØúuçt’†þà:KÛ[já YÇ÷æt‘†nðŽ ]¥‰Þ±¡›4ÑÖ§;§‡4t‡­Ïwnžßw›ë[_îœÎÒж¾Þ9ݤ¡l}»szH3îm1?~ýýÎáô½Æ`ëÇÓYš|ï3eé³ôEšhëçÓMºÀÖ¯;§‡4t…wlè)Môéí”&æpþ^“ßïÎÄë{/Ìé, ÝáºHm}¾sºIÓîïþÄ­{÷4Ìé! =ázJm}½s¸|¯q/xdžNÒD[ßîœÎÒäûØ8K–>K_¤‰¶¾ß9ݤ¡¼cCwi¢­wNiÞsÁ,Cú!ý”&Úúyç0ÖÂhÜåOõ‡†NÒD[¿îœÎÒÐõOõ‡†.ÒDïØÐUšèºIóž¯qªŸ?ÃÚÞϳvi¢ïý³öwÿ¬Cºÿã©~þÖñ~ë”&ú>þ`>Þé}o¢ïã'æ<ÿ½ÆÍù}¾hß{¾hIšhþâœÎÒÐ÷T?žÓ9§‹4Ñ~üÃ9]¥‰öãUÎé& ½þñT?Žá9§»4Ѿþš¾^6iàs¬8e½¹^ÎåÎé"M´õéÎé*Môéí˜ëe¸IC'Øú~çt—&Úúrçô†Î°õoNOi¢Ook ®—á%M´õýÎa®‘[—¼ôû¢œÓIšhëÓÓYºÂ½í‹ú.ÒD[ßß®ÒD[_ÞnÒÐ ¶>½ùâ%E¯‰>ýœoih^‚d}sxJm}ysxIm}zói—/}·¹ðéϾ¨Ïá$M´õýÍá, =aëË›ÃEšhëÓ›ÃUšèÓw™ÃMzÁÖ÷7‡»4ÑÖ—7‡‡4Ç~êûûÿÇ3g‡…+@ÝÍ韤øæ©Rº|ÛÔݶõÐ¥âjjüà¹aÖlÓ$¶AèwvÛ y'f¢mãámœû"¸ÛÂë}£¾8èrŠk1ù±ï‰±½ëùïwbÇŸüíÁ•n¶ÃV{æ =,ùàj›ë}/¹¾_n ØW~7ÈÌý=˜ey²JòÄÂ;W—Í6ÿyâz9ï¶]’-0Ëy‡lóÿ]'¸‹üןwÉö9¥¡+l}ºsºHCØúrçt•†Î°õõÎé&M´õíÎé. `ëûÓCúƒ­ŸwNOià¹`ë×ÓKz§OßÃí{Í­OwN'iè[_îœÎÒж¾Þ9]¤¡l}»sºJCWØú~çt“&Úúyçt—†.°õëÎé! áÓçïÎé) `ëÓÓKúƒ­/w÷ï5?¶¾Þ9¤ÏãWê¸}ÏÆ&çt–†ž°õãÎé" ͹õoNWiè[¿îœnÒDŸ¾|wNwiè[ŸïœÒж¾Ü9=¥¡9·þÍé% aëÛÃã{Í­wN'iè[?ïœÎÒÐlýºsºHwÎO_ßœ®Òж>ß9ݤ‰¶¾Ü9Ý¥¡l}½szHCwØúvçô”†æÜúqçô’†®°õóÎáù½æÇÖ¯;§“4tOžã9§³4t†­ÏwNiè[_ÒÐl}½sºIm}¿sºK·[?îœÒж~Þ9=¥¡lýºszICwøôø9àö5¯ï5î[ŸïœNÒD[_îœÎÒж¾Þ9]¤¡ l}¿sºJCgØúqçt“†N°õóÎé.M´õëÎé! ýÁ§oNOi`û=Z¸}íqszICOØúrçæü}·¹°õõÎé$M´õýÎé, ͹õoNiè[?Òж~Ý9ݤ¡ |úsÜÂ9Ý¥‰¶>ß9=¤¡9·þÍé) `ëÛÓKúƒ­ïw§ï5ôyÌ ·ï9îåœNÒD[?ïœÎÒÐœŸ~}wNiè[Ÿîœ®Òж>ß9ݤ¡¼cCwi¢ß×ÓåëÒÐÞ±¡§4tßÏgÊÏgICgØ~þëÎáü½Æà{{åïÝ^9I}ï9½ûCÎÒмcCià¼à{ÿÄœ®Òо÷Ìé& =`ëëÓ]šèûû˜ûû}ÌCºÃ;6ô”†nð}|Èó=>ä% ]áûø“×{ü)ßkܶþ»s:I}Kz‡%KCgxdž.ÒÐ ¾ÏEŸK•†þàûø_ê{ü/M8-ø>¿`Nwiè [ßÒоÏwe¾ç»²¤¡;ìϧœÃÜk²ÆÝ`¾æœNÒÐöãÎé" ]`ë¿;§«4t†ýø„sºIC'Ø8§»4ôûñçô”þìÇoœÓKzÂÖ·;‡¹Gd{À~<É9¤¡;ìÇ«œÓEºÁ~<Ì9]¥¡+ìÇÛœÓMºÀÖwNwiè ûñ?çô”†N°¯/8§—4ôûú…s˜{8ÖÀùì»fîçœuçt’†ž°õíÎé" =`_¯qNWièûzsºIC7Ø×›œÓ]ºÂ;6ô&Úútçô”†.°¯—9§—4t†}=Î9<¾×¸ìë}Îé$ ýÁ;6t–&Ú÷8§‹4°çøþL¿sºJCOØ÷C²ïϘ›4ô€}¿%ûþŒ¹KCwxdžÒDûþOöýó”†n°ï/eߟ1/iè [ŸîÆÞ w}¿+ûþŒ9ICgxdžÎÒDûþçt‘&Ú÷÷8§«4U¾¶z÷9§›4M¾wî¯ö;§»4ýýl¹?# =¤ï¾Áý™òæô”f¾ûÞ|û«œÓKšõîÛÜŸ±u÷gÌë{ m¿;ÜŸ±u÷g`ùus¾cCgiò{láþŒ­ ¸?iÊ{ìâþŒ­ ¸?Wiê{,]oÿœsZ“ÝöýyÎé.MÏÜŸ‘†ÒŒ÷ÜÄý[pžÒÌ÷ÜÇý[p–çPw†­own.Ü“9Íu­¯wN'ihÎwlè, Ý`ëËÓEzÀÖç;§«4ô„­OwN7iè[ÿÝ9Ý¥yÇŸ…û3ÒÐC:çOëÎé) ]`ëçÓKºÂÖ;‡¹'cMzë…Âý™³ŽàœNÒÐÞ±¡³4ô„­owNiè[_Ҽõ]áþŒý¸?7iè ïØÐ]šsëßœÒж>Ý9=¥yë÷Âý»Ÿp^ÒÐ>½Ý¹?c枌5î ïØÐIšsëßœÎÒ¼ý™Âýû½ãþ \¤¡l}¿sºJCØúvçt“†®ðŽ Ý¥yûo…û3ß›ÓCºÃÖ—;§§4ô„­ÏwN/iè[Ÿî.oOÕ}Ž‹ ÷g¤¡“44çÖ¿9¥¡ ü×Û5->‡‹4t…­ŸoWiÞ^zÁþL9Ï›>‡›4t‡÷Owiè [/sxHC/Øúöæð”æ+)Øϱëp|/iè[_ÞÜÌ=kÜœïŸNÒж>¿9œ¥yçÂJåí›Þ.Òжþ{s¸JCOøôç¸Ñçp“†æ|ÿ4p—æë,Øÿ±ëp|iè[?ÞžÒж¾¿9¼¤yç¯ ö‹ì:Ÿ›Û;g}Íùþià$ Ýaëë›ÃYzÂÖ—7‡‹4ïú„‚ý%»Ççp•†×Ÿ|°õéÍá& Íùþià. ]`ë¿7‡‡4ïú“‚ë‹ì:œ;7Oiè[?en^Òûœç|Ë<ëãD¼òOW›v¥>Ò.àäec\~~ã]Æ°æ»dÂ.Ÿãåv©•ÿcåöµí\²šyxfÛÔ Ù6&ŸâmÉÓñÚ@}+o'i¢Oß¿7‡³4ô€­oi¢Oÿw?¸s¸J}ú¿/åÎá&M´õ2‡»4ѧ_õÍá!Mô_®}ö9=¥¡;lý¼szI}ú¿G ŸÃë{ÍOŸÓÓIšhëçÓYšèÓ—vçt‘&Úúuçt•&zdžnÒÐ Þ±¡‡4ÑÖÏ;7óqÁšë ïØÐUšhëÇÓSºÀ;6pJ¯ù±õýÎé* ázHí·/çpN¯q'xdž®ÒD[_ïœÒмc—ï5?¶¾Ü9]¥ÿž2ÚÐCšhëóÃxêFãžðŽ ]¥‰¶>Ý9=¤¡¼c·ï5?¶þ»sºHCwxdžÒDÛãɺs¸¯q7xdž.ÒDûãçt—†®ðŽ <¾×üØúqçt–†.ðŽ =¤‰¶¾ß9½¤¡3¼có¹Òš[ßîœnÒÐ Þ±ùœbÍ­¯wNgièÞ±¡»4ÑÖ—;§§4æóôæsŦ®5¿¶>ß9ݤ¡'¼cc“Íýù—s:ICxdžîÒD[ÿÝ9=¥¡;¼cçòšÛñƺsºJC7xdž^ÒD[?ï.é5î ïØÐ]šhëÇÓCºÀ;6p-¯ù±õýÎé* ázIíÇ{œÃí{;Á;6t—&Úúzçô&zdžžÒÈ} amè%ͺ¥µ-é×ëû{LvŸcƒÊç iè$ =à:Kgέ/wNià’àºJCxdžnÒÀµÂ;6t—n Þ±¡‡4ô€wlè) Ü+¼cC/ià‘`ëóÃ|εÆ=à:IÏ ïØÐYØî«|¾–†.ÒÐÞ±¡«4¸í¾:ªôUú&ÍñÝú[Oü‡ÔX{žÇOî-èïã´û¶},¶‚Î+¯fž9<¯"›y¦ñ¼ð]dØÁrâü̱µ3ì ¥ô7¯üØò«HòÎht¼£Íw8äÀ3­û¹¦hóš°…Q°”¶üà’ؾ .GÏÓjYo©_?þŠÖûÔ…9—ö4YøÍûðmÿ~-Ü i÷i༮ê}ʱÃP~.{J¶=M{Aëïï^‘øôßß­øôô„óóß½:ñècc^Òж~¼ù1ÿ8Þšë ïŸNÒÐÞ? œ¥ÿ~.‰@ÿùæp‘†ðþià* ]aë×›ÃM:Ãû§»4på|ÿ4ð†ðéç÷æ𔆮ðþià% aëÓ››ñâhè²àýÓÀIºÃû§³4t…­ÏoièÒÀyÁÖ—7‡›4t‡÷Owiè ïŸÒÐ ¶^æð”N Þ? ¼¤¡;l}{s3^»Âû§“4t‚÷OgiàoÁÖ÷7‡‹44çû§«4t…­o7ièïŸîÒ§µ&¼xHCwØú;wOièïи—4t‚whh¼ÏÚçÖ/Ÿ»“4t‡whÜYºÀ§_ŸÏÝE:Á;4î* lÛxÃiÜMºÃÖ'Ÿ»»4twhÜCšsë³ÏÝS¸Ox‡Æ½¤¡;¼CCã}Ѹ l}ñ¹;ICð;K· [_}î.ÒÐ Þ¡qWièïи›4ô[ß|îîÒÀuÂ;4î! ͹õÝçî) ]à÷’†þàï›…†.¶~øܤ¡¼CãÎÒж~úÜ]¤¡?x‡Æ]¥ó€whÜMºÁÖ/Ÿ»»4t†whÜCúƒÿúô}>wOià4à÷’†nð 7âAãΰõÉçî$ ýÁ;4î, ü x‡Æ]¤¡l}ö¹»JCs¾CãnÒÐl}ñ¹»Kcžv¿Å @JãÒÐ Þ¡qOiè [_}î^ÒÀö<Ø—ôëõx_14î[ß|îNÒÐÞ¡qgiè ïи‹4°­;oßîsw•†ð»ICWØú;wwiè ïи‡4p_ð{JCsnýô¹{ICWx‡†ÆûŠ¡qgØúåsw’nœïи³4ô€whÜEºÂ§·Ç¼$]¥¡¼CãnÒÀ¶VÅ @¦tçî. Ýá÷†®ð{JCsn}ö¹{IÛZ/) ÷UEãî°õÅçî$ ]áw–†Nð»HÛZuñö­>wWièïи›44ç;4î. `ë›ÏÝC8Mx‡Æ=¥¡;l}÷¹{ICx‡Æü·°û¼yNð;IŸSÜßÇÛwøÜ¥¡;¼Cã.Òж~úÜ]¥¡¼CãnÒ˜m?ñûšôMú. Ýaë—ÏÝCºÀ;4î) àÓŸS˜»—4ðœð Í÷ ¶ÆÝáûý¦ï}¿¶7å ]`Þ?9wgièæï/çî" <&ÌÇ[ÎÝUºÁ|>âÜݤ¡ ÌãÎÝ]úƒy¼Ä¹{H÷ óø–s÷”†n0ÿ9w/iès½Æ9Í7|´ÆýÁ\/sîNÒÀçìÀÇý«uçî, Ý`îÿpî.ÒÐæþçî* ýÁÜÏäÜݤ넹ß˹»KC7˜û휻‡4t†­¿s÷”†þ`ëïܽ¤Ë€­¿sšï“m»Á§ïwîNÒжþÎÝYúƒ­¿sw‘ζþÎÝUºÁ§owînÒжþÎÝ]úƒ­¿s÷¶çî_µ;wOi蟾޹{ICgØú;§±g…ÆýÁÖß¹;I}ús&ñ«÷„}Ðk¢­>wi¢­¯>wWiè[Ÿ}înÒDŸ>/Ÿ»»4ÑÖŸ»‡4C~¶¸}sõ¹{Jmý»å6uøôöœ^ï9»ÝæÇÖŸ»“4ÑÖWŸ»³44çÖgŸ»‹4ѧÿ–ÏÝUšúîÛÜ¿ú†ÏÝMšhë«ÏÝ]šhë³ÏÝCºÃûìÐÖçô”&Úúqçô’f½ß}Û¿²¥‚Ïa#éñÿµõùÎé$Môéçºs:KCOØú7§‹4ÑÖ×;§«4Ñç|N7ièŸ~¬;§»4Ñç|Ni䱺ãöõÎé)MôÆyŸÓKšèÓ÷uç0ö¬Ð¸¼qÞÁçt’&Úúzçt–&¿ç²Û·¿9]¤‰>}[wNWi¢­ïwNËs®»ÀÖ×;§»4ÑÖ§;§‡4t…O_×ÓSšhëûÓKšhëßžßkÜ ¶>Ý9¤‰>½=çNžw0gi¢­ïwNihέ¯wNWi¢­OwN7ièŸÞžs'Ï;˜»4ÑÖ÷;§‡4ÑÖ—;§§4ô„­OwN/i¢OŸÞ^ßkÜ ¶¾ß9¤‰¶¾Ü9¥‰¶>Ý9]¤‘cé…Û×Ö°‹çÌUšhëûÓM:ÁÖ—;§»4ÑÖ¿9=¤‰Þÿc—RùœžÒж¾ß9½¤‰¶¾Ü¹9}ßm~m}ºs:ICøôgŸ„s:Km}¿sºHCWØú7§«4ÑÖ§;§›4ѧóÎé. Ý`ëûÓCšhëËÓSºÃÖ§;§—4ѧïóÎaîYYócëÛÓIzÀÖ—;§³4ÑÖwNiè Ÿ¾Í;§«4ÑÖ·;§›4ÑÖ—;§»4ô‚­ÿîœÒDŸ¾Î;§§4ÑÖ·;§—4o¯#%ܾµÜ9Ì=+k~lý›ÓI:Á§·ŸCæys–&Úúvçt‘&Úúrçt•†Î°õßÓMšèÓçyçt—†.°õíÎé!M´õoNOi¢­ÿîœ^ÒÐÞ8Oás˜{VÖüØúvçt’†æ|ó<çt–&ÚúïÎé"MôéÏ–sºJCwØú7§›4ÑÖç;§»4ÑÖwNièÿõvy»Ïá)M´õíÍá% =aëó››¹geÍ­ÿÞNÒDŸþ¬a}giè[ßÞ.ÒD[Ÿß®Ò¼ýg¼?ÎSønÒDŸ~Œ7‡»4ÑÖ·7‡‡4t‚­ÏoOi¢­ÿÞ^ÒÐ>}onæž•5?¶¾½9œ¤‰¶^æp–†.°õß›ÃEšèÓ·!ss•æø¾!ÛßÓÐçÈò;ÿáÞ>ÿv u.>oÉöÙÅS¸ æ³ »/TO÷b\ ¾v/”°½¿€å³‹(;ÿ8À.f䉅óïp“Õ.”à†º]tÀ“ E.tµ“çÜÔ·ÑE.‚ææ¢ÍÜXõ‹¾Ê“¥öïßt¶'ã'î>Ûhñ‹âÍróÂëmðIn{Ùå,Ü&³KcûÝb»ŸÙ.âŸjØÒ…§ÁlYÂKcípŸ—iÚé"^"9ÞV2¶9ʽlÑO› Ÿ‚]å]~±ìR~nÁØe”Üë÷r´óÝØægâ"î|Ï8H[¶‰ÊÏ`ž8Xº=>:s[qãRÁ»¥g˲~/Ù»[kÞÛGOÛ˜àºá½mH¥·à p³~bÓ°¾9/â±Í5^ b'#yq†D¡í'6ﾑ7ñÕñb‹ò>o¾·š]ðá'¤ï×oßÍ°{ŸžlKOsë݆8}ßåR^je?m^†ñÙ!%ŸJäÐtñðÏâäËr…}ykÛJó=­û6©Ýwü!Ô̇µî÷/ûs£v.‹8ýÙÎå§?éççsYÒÀéÏؘ«4ô€­o7iè ïŸîÒÐÞ? <¤1×µ`ëçkà) =àzICWØúuç0Nm¢qgxdžNÒÀ“ó:KCøôç²WÎé" ]áºJCgØútçt“ Þ±¡»4ô€wlè! ]aëóÓSšózI÷[_îÆ©M4îïØÐIºÂ;6t–†Î°õoNià¶àºJCØúvçt“†®ðŽ Ý¥¡3¼cCiàº`ëûÓSzÀ;6ô’†®°õoãè;Ã;6t’>ÏÝ£%é“ôYšsëçÓEºÂ;6t•†Î°õëÎé& ìóºKCwxdžÒÐ>ý9圞ÒÐ Þ±¡—4°=Nâò}m`½¢qwØútçt’†®ðŽ ¥¡9·>ß9]¤í¹—ïkCWièïØÐMºÂÖ—;§»4t‚wlè!¹Øskçí[ÒÐÞ±¡—44ç;60.ÍGãN°õíÎé$ lÏ­#IŸ¤ÏÒж¾ß9]¤¡+¼cCWièïØÐMØž[oßqçt—†îðŽ =¤¡+lý¼szJC'xdž^ÒÀöÜ:–ôëõX•¢qwØú7§“4t…wlè, àÓŸ?ëâœ.ÒÀöÜŠË÷µ¡«4t‡wlè& ]aëÓÓ]šózHÛs+.ßoö¼Æ·c‡§4t‡wlè% ]á—æ£ù±õåÎé,M´õoNièïØÐMšö¾—ÅŸÿ›Óò3qØú77Ïï»Íõ„­sºHSîm1?~ýoN7ixÿù`ëßœžÒÌ{ߘ¸¼»ÉÆ¥ØhܶþÍé" ]`ëßœnÒ¼ûÿÄåÑMæô”†n°õoçï5î[ÿæt‘†°õoN7iè [ÿæô”fÞÇŠÉõ©Ìáò½†>ûB“ëM™ÓEš÷Ø5¹”9]¥‰Þ±¡›4t†ß×ÓäëéÒDߟ׃ð&úÞ¾\ÂSºÀ÷þÆõ ¼¤‰¾¿/\šë÷w…ïïo•ßßš¤‰öÇÎé,M´?~rNièûóçt•&Ú8§›4í>·N®K½sºKíÇ«œÓCšh__L_š§4ô€}ý5}=h^ÒDûzyúzð¸}¯qOØ÷+¦¯ÍIšhßÏáœÎÒDûþçt‘†^°õõÎé*M´õéÎé& '?øôß›Ó]šhëûÓCšhëëÓSšw<9¹üÒÓKšèÍ}?Îa¬õи3l}¿s:I½¹ïÇ9¥‰¶>Ý9]¤¡ |úó2œÓUšhëûÓMºÂÖ¿9Ý¥‰¶>Ý9=¤‰>ý˜wNOiè[ßïœ^ÒD[_îæÐw‡­OwN'i¢Oo¿wƒûxæ,M´õoNiè[_ÒD[ŸîœnÒÐ>}›wNwi¢­owNi¢­/wNOiè[ÿÝ9½¤‰>½Óîãs h }^6kb=xÞâÐçt’&Úúrçt–&Úú7§‹4t‚O_æÓUšhëÛÓM:ÃÖ—;§»4ÑÖwNi¢OŸçÓSºÀÖ·;§—4ÑÖç;‡¹´Æ]aë¿;§“4ѧOãÎé,M´õíÎé" ͹õùÎé*M´õßÓMºÃ§ÿÆÓ]šhëÛÓCšhëóÓSzüó—#ËÄ–yûÎ7‡³4ô€÷Oiè Òж~½9ܤ?Î÷OwièŸþl)ùÒÐÞ? <¥¡3¼xIc}ç¯2Í֧ט±µ†Æ=àw’†®°õÙçî, Íù»HÏïи«4ô€­/>w7iè ïи»4t†­¿s÷ Þ¡qOièïи—44çÖ7ŸÓx†EãÎð;IŸ­”VyûvŸ»³4ô€whÜEºÂ;4î* aë‡ÏÝMØ~Ok“¾Iߥ¡9·~úÜ=¤¡+¼CãžÒÐÞ¡q/i`{n­¼}—ÏilÝ¡qx‡Æ¤¡+|ús´†¹;KCgx‡Æ]¤í¹o’#»JCØúäsw“†®ð»KCgØúìs÷¶çV¼Éƒ4î) =à÷’†®°õÅç4¶îи3¼CãNÒÀöÜÚyûVŸ»³4ô€whÜEšów•†Î°õÍçî& lÏ­½IߤïÒж¾ûÜ=¤¡+¼CãžÒÐÞ¡q/iÌÓž[;oßásk4nÎwhÜIºÂÖOŸ»³4t†whÜEØž[G‘¾H_¥¡lý»›4t…whÜ]:ç?ÛT˜»‡4Ñ;4î%M´õÉç4VÁhÜÞ¡q'i¢­Ï>wiÊûÞñ¦UÒ¸«4ÑÖŸ»ågînð»Km}õ¹{JCwx‡Æ½¤‰¶¾ùœ^ßkÜÞ¡q'i¢­ï>wiè ïи«4ÑÖŸ»›4íýî¬&}“¾Kmýô¹{JŸ–¶¦ôSú%M´õËçpÿÒm®|ú7wiÞcKÇ›ŒIã®ÒD[Ÿ|îîÒжþÎÝSšy;ÞdR÷’&Úúâs:½Çäë[çî" Ýáw•&Úúæsw—¦ßçŽÎý‡7w/iè [çtN¯q/x‡Æ¥‰Þ¡qi¢ï÷Ëõ>\¥ÁñÆÙÖí\ïÛmÊõ>ܤ‰¾÷O®÷á. `ÿýí\ïÃCšh¼ê\ïÃSšhüï\ïÃKšwìѹޟŸÏi®ñ­ù±oôòŽ7:×øhèûñXçzÎÒDûñpçz.ÒDûz¡—·^è\㣡+ìë»^Þz°s&Ú׿Ý×ûæ.M´ï?t_4tƒ}¦—·ŸÓ¹ÆGíûië}xICwØ÷;×ûf®ñ­ù±õÙçî$M´õŸÏÝYzÀ§¯Ãçî"M´õÍçî* =aë³ÏÝMšèÓŸueçzîÒD[?|îÒÐ ¶¾úÜ=¥‰¶>ûܽ¤ÓŸ>ß9Í5¾5?¶~øܤ‰¶¾úÜ¥¡l}ö¹»H}ú´|î®ÒD[?|înÒ¼µaçz?UŸ»»4ÑÖß¹{HCøôv»p½Oi¢­>w/i¢­¯>§¹Æ·Æ͹õÙçî$MôþìëúÎÒÐ ¶~¼9\¤‰¶¾¾9\¥‰¶>¿9ܤ¡;|z;æäîÒD[?ÞÒÐœ[_ßžÒD[Ÿß^ÒDŸ~¬77ï5î [/s8Im}}s8Km}~s¸HC/øô}½9\¥‰¶~¼9ܤÏe—óؾ®Ïá.M´õùÍá!MôéÛzsxJC'Øúñæð’&Úúúææù½f¾ýºŽËyl_×çp’&úôg_×çp–&Úúñæp‘†.°õõÍá*M´õùÍá& ]áÓÛs.çp—&Úúñæð&Úz™ÃSºÁÖç7‡—4ѧ·ç\Ÿ¯ï5æû&¥¾ÖùoÝ#­ö鎿ú1ìÕ|û½Ø)6<=Õõ¶ k}Û’ç*'·mÛrûζ@¹õdÛ•ÜÖ°Cǧ2m)ÇÓ¬ç áR+ߥJ9„—0vÍïôœ/E;—Ì÷´‘mü/h±™Aû<ÞÀ6ãù a'"üæ|g¼ó[Üï‹Q{[6?0r€f6|Âï|·_2;™ïè'%ì «¼–×yþ» »b zÜy«-ôÇûÅúÚýš¹QÁ¯yý|Íç"Šz^‘*á%"ëyu§„×Cp7¸Š¼s—>÷¼Dd=¯õó†îðþià) ]áÓŸŸÏá% àýÓ˜íîφ>÷^¼Ddlà$ ÝaëÓ›ÃYºÂû§‹44çÖç7‡«4f{«/¼Ddlà& ÝáºKCWØúrçô†NðŽ =¥Ïf ^"²žW×ò9½¤¡;¼ccÆË?¢¹.ðŽ ¤¡l}»s:KŸ“x‰ÈÐÐEºÃÖ÷;§«4twlè& àºK÷ [?îœÒÐÞ±¡§4t­ŸwN/ièïØÀé{ Ý8ß±¡“4tƒ­_wNgièïØÐEúƒO_¿;§«4pðŽ ݤ¡¼cCwiè[ŸîœÒмcCOi`üœqûž3Îé% Ýà8¯qxdžNÒÐlý›ÓYø<¯á%"CCiè[_ÒÐÞ±¡›4ôïØÐ]ø,èð‘5Ùížyûš‡44ç;6ô”†Î°õýÎé% ýÁ;6pù^CŸÍ ¼Ddhè$ Ý`ëßœÎÒÐÞ±¡‹4ô[?ÒØf‘mVà%"CC7ièïи»4t†­_>wiàÉù{JCøôö¸TpûÂKºÂ;446xѸ3¼CãNÒÀçø/YÏ«rîÎÒÐÞ¡qiè [Ÿ}î®ÒÐœïи›4p_ð»KCØúâs÷†®ð{JCgØú;w/ià¶à¼hÜÞ¡q'i¢­o>wi¢­ï>wWiè ïи»4ÑÖŸ»‡4C¾÷!ý~Jmýô¹[~æôY×¥¶¤_¯ÇTh~lýò¹;KC'x‡Æ]¤‰>=þüüá*M}÷¥^¥¯Òwi¢­O>wièïи§4ÑÖgŸ»—4ëýîô%ýzýH¯ù±õÅçî, Ýàw‘&Úúêsw“†îð»Km}ó¹{H#EcH?¤ŸÒD[ß}Nc×{Â;4î$M´õÃçî,M~½3KŸ¥/ÒD[?}î–Ç|úœ,NÜ?y»Kmýò¹{HC'x‡Æ=¥‰>=þüü͸` ;Ã;4î$M´õÉçî" ]`ëïÜݤi﹘û¯qwi¢whÜCšè÷ýù~§4tƒïíËý xI}_¸_qœ¿ï6×öLJÌý 8Ií·™ûp–&ÚŸ_2÷+à"Í;vÊܯhÍçî*M´ŸdîWÀMzÂ~|˜¹_wi¢ýø9s¿ÒDûz'o½“¿) ½`_fîWÀKšh_gîW˜Ó÷šûþIöý s’†ÇÆìûKÙ÷+ÌYšhßß˾_a.ÒÐ öýÏÌý ¸Jmû·Ãçî&M´õÍçî. aë³ÏÝCšhë?Ÿ»§4tOŸ†ÏÝKšhë›Ïéü½æÇÖgŸ»“4t…­ÿ|îÎÒDŸþ¬‹3÷+à" Ý`ë›ÏÝUšhë³ÏÝMšhë?Ÿ»»4t‡÷Ù>wi¢­o>wOi¢­Ï>w/iÞÚ6c¿Â.´ËÜÇ0—ï5?>ý›»“4ô„­o>wgi¢­Ï>wi¢­ÿ|î®ÒÐ >½=sOnÒD[ß|îîÒp¿âƒ­Ï>wi¢Oß—ÏÝSšhë‡ÏÝK:ÁÖWŸÓÜ£°æÇÖgŸ»“44ç§?k(ÌÝYšhë‡ÏÝEšhë«ÏÝUºÀÖß¹»I}úº|îîÒD[?|îÒж¾úÜ=¥‰¶>ûܽ¤¡|ú²|Nsš[?|îNÒD[_}îÎÒж>ûÜ]¤‰>}^>wWiÞ~cÆþ†=ÇÜݤ‰¶¾úÜÝ¥‰ÞÜ—ÆÜ=¤¡'|ú´|îžÒDoîKcî^ÒÐ ¶¾úœîßk~¼¹/¹;I}úïÎÝYî'ðæ¾ô›‹4ÑÖW™›«4Ç~QÇ]»ü—î‘ÎÜënZ=oÏÁ´‹:xªÎŸŽÏ’™‡—™ÛžvhÁ-V? à–©Æåö£ýLâ]Ŷ[{¿O+iðTl¹ËO;¥ëK';Tà2Ä“èóMørÌNréZÖ[†Û©%Ûâø_?ÑÄ;‹UüŠ 75íŽÙßWm':øv~4I~‰}CnÙfÏ{àôk&¬ù}gv2„'ÃíI)É°âµ@þŸÿ©çº¼U=—}à¥¨È ŽÇú¯CƒÃö2ÿÃkPÅà°¿ü{ìÃëOÅàp¼€ÿðÚS!0Îõ^w*Æõ2ÿÃkN…à;9·)^o*Æô²ÿÃkM…À˜_@Öx©Ë Èô¯1c}˜×?¼¾TŒídÿ‡×– ±¿€¬ÿðºR!0Žé^S*Æù0­x=©× Èþ¯%‚CìYà,ÿð:R!0¦é^C*ÆüðÃtÇÀX^@öxí¨ë Èò¯c{™þá5£B`ì/0ž?hÃëE…À8^@öx­( Àù²üÃëDi®ß?¼F”‡xõ' œÓ0½€lÿðÚP€ùd1î€åägÜ!ë ÀéØ^@6ãØ_@ã8^@~Æp¾ì˜î€ëd3îñ”m3wÀôò3î€ùàßSÒJïvKïvÃ.²wÀú2wÀöò3î€ý`Æp¼€lÆp¾€ÌÆp½ü{JZéÝnéÝnØé±À9Œ;`zY;`~™;`y˜—q‡¬/ ‡q‡l/ «q‡ì/ ³q‡/Ó2î€ód7î€ëd5c3wÀôðïw•w»•w»açÙ;`yY;`}™Œ;`{ñ¼xï*ïv+ïvÃN ²wÀñ²wÀù‚Àp½ p‡Àˆ%ŒÎfÜ!ë êýÒëû™Õ÷3«ï›wã¸^@bºC`léÎeÜ!ë xÆ°¿ ß›»½¯·½¯«gd6î{º³wÀú‚w÷ìïëíïëíýd3î€ëëþŠô÷õö÷õŽtç0î€õ$¦;`A¿¿ÒoµÞ:kõ>î|ÆãL7˜ïaå­qÖ[ã,,Kî€õd6î€í;`YŒ;àxAà8_¸C®¼Çõ·nYoݲÖ{\Ü!Ó ÈfÜ!ó wÀò‚À°¾ Þ§¯·nYoݲV{AàØ_@ã8^¸CÎî€ë$¦;‡éãj%ýÿxdžNÒÐ Þ±¡³4Ñ;6t‘&zdž®ÒðÈêƒwlè&M´õíÎé. `ëËÓCšhë¿;§§4ѧ¯óÎé% aëÛÃ\ÕXócëËÓIšsë¿;§³4ѧ?—£sNi¢­owNWiè [ÿæt“&ÚúïÎé. ÝàÓÛŸbqíi¢­szJm}¾szICwØúïÎa®~¬ùñéÏ.-çt’†æÜúvçt–&Úú|çt‘&ÚúïÎé* =áÓoN7i¢­owNwiè[ŸïœÒD[ÿÝ9=¥‰þëÛo/i¸Êý`ëÛ››¹J²æÇÖç7‡“4t‚­—9œ¥‰>ý9½îs¸Hm}{s¸JCgØúüæp“&ÚúïÍá. ]àÓñæð&Úúöæð”&Úúüæ𒆮°õß››ë÷šŸþœj÷9œ¤¡l}{s8Km}~s¸Hmý÷æp•†îðéÛxs¸Im}{s¸KCØúüæð&ÚúïÍá)Môé«Ìá% =aëÛ››Û÷š[ŸßNÒßÓ”ã;oð·øø×8ž×ÌÀÛ¼è‚ßÞ1 Šó”çqÐwϹ#UžmLßléw?çï¦õíš’îNÈߪ|ÿk[ñç_>æï®âÎ=õ{뉻à8¯ â+¨³MÌ“lcÜõåÙh¶3Éÿ{n¤»Ýr^BÔ7lF÷/ȶÑû}ôÕèÙPà‚aÉaÙ”C„!OÉ]žzÛ;Ä97ƒ¯%J¹KÇ¿›Ê3åÝõüèøÈÁ/ú|·c±KÎ…¥•8üCµ/íÿç|Z M¶¾³²ÚSÉùðj7†¶<><ÄUí^héûx¼,ìþñÕëíõ{q)Ýù¿¸(ê¨Þÿk4{1‚óïÙ«eÛ+—Øëîšì$íÿ®û«û¿b²yÝÏf¯Ih_½ú'ßãá|f¼Â‹]¯ˆxÁc{) ¼ÌèôÀ0-ÿr‡- ÎG ;ä<_î°ƒ7{ Ó,þ×ý{Q¼å_.þåu?Û,﫱wwÅ ç£Ûý|öÍÚç³_û|&û|øQÜÀûg—}û¿öka±î¿²î¿l²Ï†òý¼ÿ¬ÿdð/ÛM?í(ÊÞÃ"×û à4Ï™â,~È<ù“ý­[ðÆ?Ã5ü‡Œ7Ò²÷°h“_Þœ oaæ?2üßu?¾Šá?düËë~¶óþÕØ×hÏÇö5ü~œÏƒ©}µÕ«ù=xÙg4{ŸÊç/’í_2ñ_âôïCó‡‹DòŸðg&çcðj°G+ßÁŸJ›lçîï[¥þ~§2ÿø)ñ+Êüù#<¨žÿkG×ç3ãÏ•ý_¶Ÿ5‹ÿßu?â|øWL5ûÿmŸD[÷»Æe‡çØ3®:<Ýf\@yþ½ŒkGϯZÆe¼à×<Àuvßà¿v¾z^Š:ý£L_óïmuÿÞæôïmVÿÞfõ¯tNÿêïüWL‰÷ ~¶óù>œf\á“Îÿ¶¿G:#<ê뤗÷³è¼/ñcZ°bûûgŠýÌÏW]lçâ|Õyñaƒ:_þïºqþÅ’†Ë~¶öí‰Ø>ÂŽ4οRšÿË}6‡Ü°¯ªø}ÿ2¿V»pÃ>ËÄã¹ïaj¿ø0`ïqN%¿_W[Ÿ¨ÙÚÐÿþü¿ Ý Õendstream endobj 6 0 obj 40796 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:58-07:00 2013-08-20T08:41:58-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000041092 00000 n 0000042662 00000 n 0000041033 00000 n 0000040902 00000 n 0000000015 00000 n 0000040881 00000 n 0000041156 00000 n 0000041197 00000 n 0000041226 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 42832 %%EOF ast-8.3.0/sun210_figures/gridplot_bw.pdf0000664000175000017500000004770513004147321015027 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P064Ô3Q065TÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!æxa endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 351 311.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 351 312 ] /Resources 7 0 R >> stream xœ+ä T(ä2P064R065TÐ564Ô3¶´P(JUWÈã*ä‰(€TꙀXzf ɹ\ú‰ éÅ ú– .ù\@N¢× endstream endobj 8 0 obj 75 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 390 /Height 346 /ColorSpace /DeviceGray /Interpolate true /BitsPerComponent 8 >> stream xœí]|EßkÉ¥çÒ.•’ Ò«€Ti‚€€ M”"E„”"J/VzQ" MAjIDAªÒk(zéÉÍ·3»{·evw6¹ òÿý²ÙÛÝ·3¯Ì{o(A J ‚é1o÷¹îœÚ/vN=ÎǾò [Ejº}7ûž}7ï–|1…#8 À¯j@| €•ÔÌÂ6‘©),,GéôcD{·³Ú.@í=ÙÖL™_¹w“;¸Sî/†»ùC<ÜïFÅƇº»5Øภ3·½Äü pÃÿܶ…þP˜šÎžS<ýñà/ öVžý¤Mh w»¼ }óˆÞÕìH_o…`}Å‹ }Wèyûe°ØÃ) óu`+&8V0¨Ôô˜© ¨½î¹ô&ÓLoöWÌ‚ºM§Çïà«p÷ý¡äDü wç½Æ]ų5ÿÎQ¶b‚cX¤^²ïžÉ$­ätÞ)Ò&8yÿ2ÿóÏ 'ÅçQ{ãà&Raâ$ttý¾—õD»¿7`k´{äyî*¶Ø’wu0¸ÚÜòè™ÎDÃ]©Ý(3<ÇòttS “©²½:ýâÍî¥wÑQnÍÑçý®;¼ÞÁ½½öèÍðªï×G;nôOå1”î¯IôŽ±ÜúÐãü[FOó LµN,¬l2Õˆ‡WæÚ`¯ D'Ô¢ëY!ÓÖ„Ú&S¥Ñ\{ØVÁ¿ãô]ݧÁŸÿ”§ßÊ»yÜ‹ø“þ¹²– û๦ûÐþéª4‹aØÀõrt]Šv“£¸²l±c Y¼ùNÙ©@Z¯—ØŠá_…µpÜ n·‡ïÉÊ>³š×Ç¡íáÿfÏÖ²Wx4µìxÙKw¹;<Aå°µQðªÅ-×Sö]Žø&ÜmNËÃÞIÙg*üF?d»û‚§¯• 2ÆÔ)óWvÖçéß«cdgÿYjµ 6*äÇ °¯·•;¶%#ûŸ:ÜÓr­‚Ö¥éàHÔºàÝ—Þ¢ww”¾ Ž†\”¥BV(VšÑ€rÝé݇h×w0eÌ\a¶XŽYXøß`¸Íû…G…lt6Ïñrжõ¸wã_^K‡˜½½t'œÿbÜü?ú Òw°Q6îyÓ›GfÇõŽ øn¯ù0µ|€’ÅŽ‚Bà9]"½}ëhº>æ#¨‚Ÿ\¶™!s–ë¶î=ÀQaû"Ù†$EÂíì†ÿEKåwû|«ÿ'%·+Ü¡„‡»C°·KÔ8fË’˜Ç!f/‹~nŸËèÀuúY¶Qü;`jg¯w53´…¦R/¿Æ#wØ$·´Ÿ\«MüÂr÷qå„?Í ùm]£F˵€™uÑm}™›CÊûÞF»š¾ÿ¡Ý|û÷ÀË÷ßAÅòTðqh‡˜=ØÑ|*¤˜í³wÀÔÎ^ï8ê{×QùÝŸ§Uï ÷ô¼:ì¯6 mõMÕþd¼¬I^ߚͫ|:zè°ýÛOø½?C»g*0ˆ!ß•òÜ¥l±_›‹8˜áÚ·ž >Ün³Ÿà^Î^s‡˜½ƒ/ÐÌ´ÓòÁözØ;`jg¯GLpóú,®1÷ถí$Sá…ƒÂ6äÈPÁÑÖWÖ½|ô²áð–G]b*0 I ‡Ûí¥÷[ñ«2ÓÒC:C …¥/0ÇV0ÌÄwø3&î.ëÀE ¢æö¹KÙbæ‹x)h½U×;:„˜7££ókÐ=9£%_‹vb÷&ð0>Àž Kö»0wXëàÎ@T%:à¿©ƒ4“`tkú.€ï RáÊ—ü7 ¡Âä–Â6ÈPÁÑÖ­å¯Ñ¯¾<Ûfy½©, ˜†|ßÞ™°¿ÁæÒi¼ªJŸ ER(΀աœšYa3lkÐizûÚxøál5J­ ÿ>1Ï^ìpÄ-q÷†ìëË^æ7„²3«ŸãŽŽ­pü\­Þ-Úqȱw¹ì:°/d/ï.ðÛ­¸žÆ\…vë­‚ÛÁûÁ×5èèHÐ~p嵆ô¡Ô.%*ä÷®uNÐ*ðZ¸0òÐŦHrþ-œÞk‘ IJ›£_ãÕD_uí­Gìãé¯0îÞŽzëÚ¹šÿƒ»é{\¹Øäu¸ÛJwš-v(rsÏŽïGùž€;qì âý)tØûÄ°GÁJoŸÅ"~é8äØ;áKù!Iž½ ÝÁg¿½ö8Þ9tUsjÌO¾”å»ã9Žå)Âa)N¼¥[(hCœ¨¦­||æ ‰Ù³·Š× 4~å®à×´ÁÇ?þ¡x¯‘¾À{%sþÞûžÜ­Ò'xÑw€{×7sõúl$ Ô‹vUpM½Åê!q(V œû»kê-V‰Cœz‘'ÏÄC– %(A JP‚” %(A JP‚” %(A JP‚” %(A JPŒ`A‘x&öO¼cyÜÍ{Ê¡g_µò{¶²ä0Q«žXЋå½ýxJ ÿxþ5VH á¡þ(cá^¸_¦h‚Ÿ„ô!UBŠBÁb'ûí“Žù =¸·IQB‰ÁNDì·¯D öõ—PB;L” QÀRP8Ia§]oá÷lÀÂŒ<°8Iê„”`«²:­Ò§¦X ÝÄ°ÚÙŠµD§Pêɽt¥.‰«uìÁZ"7ÉÀĉ™î[Hë…ö½M îý'¸Sî%„áž—^À±hj8›4f ág*™xH1Sn«Nýæ¯a·ðxeÅ]Ì©‚‚æÖÜÈTB4p¿Awvœ¶º³¥ýOyN¼)72YKú„¥CR©ÚËx´¤NÔTqƳ€ë%ýá´7EÑ=ÀB&•0ð¼z1r¿GYŸiûëµN:Ï’~`ÇIÖvNT#nýÂ:˜;ãÙí÷»èÜ·Ð4Ц¥/)×êz1RäÿØ<âÓTð¬Ò!}¨Îð“f@ä,Šêx̉-9ÝÃúÌ+àöÌÑ!¥¯Î´¼@4€ÈšÜÇ™:ÄÙÎá aêAë3fëÓV˜÷þ4Ï Eí8ܪ<ÊÝ÷,É­:(œZÜ ÅfO6­wÂYíø¥RK”ÊöYáóuHA(ìÃÚV†‘f,+8²? œ‚RYŸ2X(jA¡#n÷*óSákqàj‡*(©ðÓϦ}à*iêø5z6inA±.üm”Íð馃…Ò%8a0ràA·ÊGÔK‘ãîÀ&”õé•–|tÎì Ö…Lw¦°öUìA>­\Ú×ÙÁõ†UÚ™1.b,Ìí¿MS¯„‡¬ÁQ¿¡§’K¨ŸœÝ’¿íL¿ ?Ë—I[ßŃ¢Ü_üü,&+.;Ã?D6t«®ðM,^¸çf8íÌŽ{`N÷²¯2ßùŽÐ)*¯øá–¥ƒ:|qŒŒ)/7D93Ÿ¶Qɇ2g9¯#Ü_ÚÑRc𷎯ûZ‹vÒ”ÓbÜX7¸|hïå7 n`›ÌÈÀOÓ¨dóÐÿì´ŽpoÉ‹þ=¿KÌ^󾸗¾êTõÃÃê]â×Ð)èÿÓC†T“.‘fÎÎè·—¼äßmó#Ì™¹‘ûɪÈÿcl\ôûªFÙkuz Íüi±,ùQú\çô„í]}{~#ÄŽàUÄû°L¥/ï(—É|­&³Î‚ÛÓ@Oý"§ÈF™ «Öœw_¡À©²‹A ï–.Û…îÈ-Ùá-f›²í<£’A·“&B¡ŸãÔà WäQ„äzæj¨òÁ’zQÿ³ÿdm[Ð¥ÕsØ5tèçàeèÿ“®Hç¹®;a4:Ü1tÒõb™¯¿¤MC;6( gçñ­”÷^Gëÿœ‹ž€<Ù"kšÞ”VøÑèô«s2ˆJÚz×¹­­îû3";E{‚$Ïæ”k “Iߨ5˜åž`ælpÏ-ôht½¿õ32а ­üŸz)²¾Šxù˜tÐÌ]^®åß´|×ø f”{b™ÃfG¡YBÚø qÔ‹9016Ië=2•êp@šï<çë¨7n‚ŒfÝ™¥¤žPæ°Ò0¦ÐDXÖGëK“¨ù6Ys")ÌÒéÍÎKoþ2#J=‘½ásýôÂádó*p=šW6QûETàÛä³MjKoßý‰%ÃTÝ…$Bæ˜àY²«Þ*á«R’%Õá»å=ë\© k[4=£yoæÄÇ¢§ë’ ±Ý ês´.â‚öÛùÓm+a³½Ú¼Ñ™ÆÝIé ã 3ôË G„ƒ#,øÕ_—½¦ùÈž7D •Šc¶¹¡ß4Êì?QƒÒ$}!{¡˜~JÆ UÌ‹¹ªõ$$Ýëû§ôԿϽ;Ù}‚Èð…nQáˆ0Ïú}!›0¯ìuõBø2¤­‘c²%çÒߊ ÛÂì>1ƒÒ§ú%…"ÂÃn5/ºŸÇiŒ8¡­n5þ•žý:ЗQ±Ÿ”Þ°H7W#– ûRµÎp2ú¨–úô›v½mYð\©qö€¿…Gz"zÃ2ýí„VÕ-Öo$çïùUaåØb®¾å˜ÜáJJE²~ö@o¼á*É\ÀnDóf7 ¤ÕýHKq_~.€s•†H´ÓæZ¬e1¨X§ p×çƒø0ùù„[#Œôkžw5;d§½ÔéÁÙMÐÑÎü'L¾ø°p͹»DCé„þÐø°kc‰ê·& &S$Á³“ÁÃðHÆÙ"›þˆ2Æ)·Éò1ü÷êöeòüƒ4%Üw&u|¾°ë¥ß4”È_¯Ø>Œº$.ñf*ŒY%Á·p s!¦é’d˜Bn›É¸S¦ JÂã£ÃyÃøUzt2ü]è&íÑ }!Lèà±"LìžZ¶,£[yu±¼ñh`)å!ë·eƒú‚í¯m"^z̃2´%˜nVļX ¦ž …¿Wî•HˆœË JÅTPº£ŸH¿9Ì™l7Ê8[þ‹MÂdÎä-24ÁL¿hÁàVäjC|Œ(ÕÆ®-¢"ã:XÑŠ%òõfîF'=1AoRã|ÚµB;nYt>~® Ca„&0)L΋£É ׯ<þo¸ˆ¿çÔ^Ñïe†®æbÈ¡ Æ\ÿÒû’ã‹ †ù*—Ž ·ñ¾ —ŒáàsºF‰¿Wè›UÀ†Ý‰ÏòØX[|ätôRá“¡×ÛõG{ nl‘ëà­§‡ý[‰“ç\rÓOUU^úncfÁ-Tâý(Ÿù¼«ÅêÌk Þ´ãáÄ“>ùå$½özô,á_M¯7 í»1éµ€ʉF\ʃ 6±àë Fã;ö¸Xw2¿ÄÒÓoÜê*rέ,j-9t­ÌW‚ß™1ûn—_Žv‹Üh¦p=è ðà7#ɜו`æÿ6yêèOéÝ……&ºl/pëÞëNZ2Óz\rìb¤Ðyýó¶‹á»Ñnñ"ƒ—!ØZ~,8fóÐ$²ãüÐn¿¸ë‹@èÚMw‰„2Úë4k[Nã/I‹Né'=v*t3ÿ§­î÷à`8£‡Hݘü(z0™_—'f^ºe"ê4ÆŽ‡[ŸµôØuŠVIãƒÑd—ôùŽEºM/`“£v–LñÃúpˆÀSù—Jù`Me¤£Ø7E!ç‚Ïñ¨¯7“¦¹k‰æù™·NoY·VÜWö‘1öÛ^ÕÞÄ¡¤Æc&XÿàÿlBËã#º¢Ž^|Æ$Oc>°5âë¿êôÄc(…úŒ ÌN²Wô¿ †Q¯–'ŒÚàÃæ„Å+NÙÞdMäýÚS9ä6e:fq!ƒþ"KêðžòŠÎ aÖ—™Q° •&%þüø-|áÏuAZýòš“ YoŠ;º$ŽJW›–­“ƒ™aª˜°˜09˜)¶Vo"uªËm³‰ÛMðg2aÑ’îêY!rþu‰eÌbãn—ÞJVðt8vÚ{pcÞÌÝƪt·2£\ñ°ëÁD; ç(Ç•ú©ÄOj+£rk,`¦ÂØßKºUq0œÐ9¦ Öæ•ÛaŒãG~hêֺذH„]ezÑL9K8ž"=xÆBQJ®ÚM5ˆÕ0&5'›‡>ŠíÉ+ðld?@SGVõÏÐb0&Áñ(ï¹möߣ ‹ˆ¯Ík°¢@÷¼nõ-@¢°Üf3Õ A´û{øŒÕ¡•æGAíî¬éxGK_´ÿm”ZUeñIsMÓóä66®Ö~ÕÕ0²Ü“GËàÙÚOŽ)’ Ãàvadc|ÜÁ6 #Êî7â©_K~qRÐÅßø}èqóK+m®õ*‘Í5´\Ž?>©…}L»‚tKcD~Ü ŽG`f7^Ë{}c\!î¼ÉЬ]ŒViéõÕËÐØ‹ç y >±ï7G†à›Áûà¿ÇË Ñxt7„³×k ø-R[\¬ûŒ} xATkþø¥ûLôræÓÛóøÇ$tó÷ßeÍ1¬×pmvùBD(@$Y"ˆƒ?9üPUê‘Áö*2šö7U¸É¦{æè„Ò–<ÎÎó¢‚ëÁ¬‰f±þ+ÅÒ"|Ѿ°·P&Ds¸Ïkãù¿¤ Qz1+Ÿ4þVæúŽöQôuF¸˜ÿ=>΀X3èÏŽµkô„‚ ƒ´ BNëÓÈ+ç­5ZäV3[̼i@|ÊXoH‹W*Èè·"ö²{‰ì È”Žpûø4bÍgB™Ñ}§a¢¦‹gϼ( ¿žç?/Yáë)»¨)cõön!ÂæhÎÀÁò‚¬ò;à¿Ç5&!­ôž€~ØLÚÞjZ¨sÖ³hfÒ’>yŒ—w%Ì<Ž߶ƒÝGˆœ‡ƒ/kÙ‹äåÇÄ QW¸èfE¾w7j[5gâëNjE7Óïdáä="Ü ÅDrJ]*Ê)c-µÆ‹„ïÔpÖ²þ.'•´Aþ§3Ä3\ŒÓuzmŽÖœæ!ßÖx ØÖªÈ[4 ìcЪê$̲æè_Æ#CÛü(PöÖ°×'qSãg‚‘»Þcá :è†wÍ™ã¦Rg^¦½æ¼†´uŸS£ž‚±¾sù°5™GPkniÎT•µ²aä<žLlkÂ:XÙÇ aCàöqt¦+Œcz¥Î]±¬¹‘GØ”Êú¥²çl l¹â”@K8A4QôoÌ<Ü)ä#‡Šy"„™›¶SánÈiÁï¢ê YÖ3p‰N£ãÜÚœÙ[-ÿ{ø3ÉGÇM•N+Œé†)+ÆÃ`¾Ýöü‘ßÚÇ¥w˜oÏñÖ'¡ ‹¾30]a <3MV.,†­ÊNmL~épœJ|´oà»Ø>—G²dÀÔ7?÷¿Xa»{7äüçk§o*C±"ç rÎ~½Ms=ÿ\Ù©Êéï6°²øPÖ75£¦Ëå‰ü#øY{>ž-A<ߧë]Ê}f«áê‘}ÕË$”Å‹»»B~\ô’èé[" "ÓÜ15Õ’M.¥þ3(ðåEL<ÃTŒcÎÃý“Ÿ÷íµM“u<bͯœ’ë!¿>-â z¡ç…Séñþ”[ƒ•ôÎÁàU!'…TØ„¤×"ë ÌÍ7u •RsVT/5Ónù®)wÍí…/„OÖ'»{ .LÅBùÇg¡+ß0kÈD¼¼…z™ ¨Oß¾ å“û'¼k!raµˆ:Û-$ã ¹‹K·ÞíøÈý<³ŽõìGUqz™˜½ÜîÅiìø—Üž2‰Æã h®¥ˆòÅ° æb< WØÛZ ¶ U¿ýIdË‚<—ä–ÛPò‹6ÔR·g-´»ŠøÍc©ÀF¸$èDÏŸžŠ,Q sïÄÒ,PÄùÖ•1«Ùö³—D·$°ñ­¢ùƒž\—·5æ¢#=èï^p6iìæ€%R|Z çç"’Øé›~êRÞ§ÖÙâñ‡ ÿä,)ÕY’‹”£œE;Þþ¾æC>Ùñw¸z8öxÎ[f±Úy"gLiÖzO ’a2ô f¤Þ«U¤«^„y^'š•Ëø,x<É»ÜH¹×¸øàµ1ÞþöÚ”ä z©ûP¥ø±z!â=+¼( g/÷-çÝVà®üÈÙNŠ@sã˜ATCŽëнÊûsŒŒ¹Ùú¥ô(Ï&¯ˆ«¯UP[‡‡†mÐ+.è_+`_;gXr©3^ˆ‹Vu™ª/gÓC1_>‹ìß?õ‹¾uAÑ~ˆ¨E@fz\*Ï Hèµ&¶«q@T.od4ntw'^OaK©*ÞÀºÎήï`öñ³f;Åí˘6çä®b 4ŠGðf ø¶Þ®-˜òN¨·Eà§ÇzekvÇ̼ÖM¥…0©m›b#õ5|'i}Ë+& ‹/óN¸Q–ñžÿ÷íZß5Ìœ õ$ë 4.ÉMYóðR*}4t¡ôÛ‡rv¼|5’/YÛ¢‘IÝåÞã$îŽÛšñ‹Ý¬:à¡©?†Ë/Þœ7)y&E9Ùþ ™¹?Üfeõ«Frcõ9ó}å­Xý6òöøä@ .Ywq})þ×öªÍåTà^~cîN–3Ìÿt~˜ø…˜ÏÚø_ë†2#Ø&MX¦ù ý¥ž c˜È÷!̱ÏMÄñÖ—BÔ;Cu{´ÊÂ86'= ̦ÿ…÷ý:óJþUn].%±o1ÏÌ H‹*]œ8*ÜF&"9`›‰Ï5¼;lóçW`Ó'Ùy\Eâ[¼3FµÈRû‹öæ}s# é7òZŽ¤Xwn@ÚIÙûüçH7æå²=µNîzRÉ=aOºYaûeª1ÿq='Éðé nú«¬èI Ρ\½Üëý‰¡ç¢î.8ÉëMCÐ}]ÌžY 4çQ{‡Ðýt¸\†ÉŽK•Þi~iÝ« ½>÷DÿR¢ŸC݉ åýÔ]þíÞìcÿ`—Eè‹G÷v”ü)+.N©Ç½|Ê[¶HRi…ìj骩­Û4ÜË•ŠÞð¨î-ÅKèl³¶#­ÿb¨j|œÝ±ÿË/×´ áªYq‡½d–Šµ.¶%QÂÿßEÉÖÖóãaÕÏ ®×„Ü¡õxÌ6>Tš!av…ã‰=£è0k»àÑG=cç[etÔÌÓ.=-ì*ïPô["9Á¥Œc Üÿσ^Ú˜•Æû˜lßTª €­›Y– µÍ Æ…×®ôö+ÊÊÐ*”´öDu1étŒHdÎõeÇVCé†@§iŽ¦"fïRÆÀÉ©v›î+#W6nÙÃQbâóJã±r:z,Œdâ²{Õ!u|`¥^ˆÁ;ê¹énþŽ¯Åî<×}yp9ÈÞYÿ®·.•Uí·s#ì(8k za%kÛÜ)›Ç¢àËίEdHmÑž|vzšñÎÕÁ¯”¼¢y½òEáïŽ{·Ã‡q'ò| ¬ ‡¤ëlÝóíTªÛöÄånnÇÌ߉܅½C!Ú¶1òp¥òH-«¼” M6ƒÚCNÉ´#§Œ`®êl0g[º¤ƒ{·ƒíÓ&õÐÔ· ©ð.[·nã&twX‡;ª¨…iÛ†ðߢ²ucð§n›z!„ÃQª~ {ð š`ß5¡U͆ä~wµƒb™Å»ÉÍÐû˜¸¶¢J0~¡Ú6Ú0Cã/„“–l"“rÁ‡¼¹’ÁãQ™>p{…‹½ëÛ­ ]%9…O°Àî,};Lm¦²0TØ2(–À‹ãbÂ’?¾¨ZdÏ×é%ž>ÿ*²fƒ÷9ŸkhÂu­ÙíU&¶¿¿PE|M5ÇK!š¶*ô0˜X‡ _4ü ÃUòË©®¸q.Ä®l¯ÀcO_2Úm{gˆ@S.£Çœ©$xKÖ„„ þ@ýkYUù¥àM[j…Ke è¨-(ß›4ÅÞ‚NªEZs^Þ™åvðÇëùp$7%×Y÷\Fw=óŸIz:`<-â•‚1-ihÄÌ%V+pÓæ—Fž¹­HbpxXb$Ì ý(X5ÁOܨõ‘@ü½fd‚%ÎG³_ÈX¤}¸Ì”D1ê"t–§_§öÀuõèApÊG2G}h-0æT`5ÕÔ*ÚÄ$Õ’°à8Uúæ—e2¡¶ â#2ŒË™lÈâZÔ­\fJ²Ë©ŽÀye¶‚+üŒ2B œˆ H…*Øå“«a„iQYìÒæÛ¸¢Êsf ièQ¬HžŠe»ÆfIp2ýsÕD9þ5à™û²øsg¿D^ƒF|T'ý¤-It}‚½ð™#y¸íuÀbWï× Œã[v(ãqcFf5Qá: Ëè.‡¦VRƒÛÂå ²ÂIr0¨eÅ ¦aÕÔâþ‹žÌÁ 쫪Z¤Ï'ô'Ò= ‹ø §°³vuPjtQá]†9ÿ«w¤á™Ð5ªj_¿iÙˆXQ¢“®ÃðeP«Hz$ LÜ>µ‡cm‰Òe2r¨KM‘Õât£Fó.2«RŒAÔ &_v¼ÎdLÅ‘óþ"QÚï:¶º8ÛÌý˜ÍØ’28©ë<ž$OâÜ.ªEª¯{“³×žŠåy&zb)òcuQ_ph ‚[L…2äZ‚PP–ͪ$>®‰5DxY@¤ZTcC§áSû÷gŒñ1óàb*ànQŸ,†FsËæFãÞÌu´d³=¦“Ë_/»jÓ ùÜq‹3Ôà\±.!:9=U žÕڲͥ¯àÛÚhZ28¶Y¹³‘*vó¡ÍzâBo§ûs{l˜zL×,ÃÎr2΢×ù†Ò\3©p Xƺs+Bì«„ºD²‚­”µÿ5Óö㢠ïÚkc0¡x['é• pv ÷Õ]zhkØÉ°r§~ª Å®Wº™zˆ••ÎÎ*sƒfÀßcÎØë¾Âæ*°‹;2u ½»“d}r\LˆÓ .5ýµ¬„±™0«ßCÝbM8:®Â9Ø8+†gOu øÿ’žŽõe¿Y|DH)«îô ´–L}!ÕË@¼9AöÔüHÄãÓqës8ëäÞ탌Ë.Q(Ü?„sá¤qʨÓH9 qG%¢ŒÙ >#\øto9Ëù—±¬;î{˜´õŽÇÚú2Ü6ý]xÔ‰§ÂLbs3yÃl}:«L%ô _ýØ—.¤Â*Ôÿ][$ßHý^ÂJ±x¼AVn¸£é]:¦)êHëS í”imû}Ó%ÏÌtcòuÜâ¿`âÄ Z6˜̺Ú;#Õ¦vT-bÇ=‰% €KÞŸÕ[u{ó¼æ·• †¶âÈð1ôÀÈBj›KfXÆÏöÌ„`»úºìMÒ*âé÷î/p KðÇÒáTªe~Ö˜_Õ q¨ÞàÞÌX‚4ªM–Kx+Ýõ”ø P¶aÜp°Y5™wå ö,¿êÙsdö^…)Á™®Á¯Jý•ü)ïI¢@Ë´ K$å0ØT•<{É/:Ë[§Ô‹å•aE h(‰Îå ´×\ÀâE5µó»(¢ÕèÒ††ÌJK†ò\}=xßàfë:¬MM—‘•ƒð“¨˜XeÈ#6eŸÿº­— ©à'ªy÷Ñ\*Grùroݲ »0Ð:ËaÙY—p¥—ƒ¥È—„yŸp”~sÿWò‹m¤Ù[DøOÕv#p!X¿<{Í9¬ˆ²¼?¶¼ŸDn^.ƙֵ¹µIʯ—Ú•<©ñ#ÂÔI?×àÿÿ3è­¯eêq ùå+ºáÖÿfzF¼!ÕXWnùÏö8pê·ËM!œÀYšñ¨E–Û;×!g ÂòÿGâ|°ü§Zß ¸²/ Ù&ÚQóQÖš]MÕzŸ×»97Wë®ÀC®´j˜­ÖZ–÷é6I½ ‹M2e{'©ÞEfz¨Ÿ¨‰ü×}ºp%˜-¯f& øQ€ª»ÜÛ/Ùçëc©——¨‘ §ƒˆWÜžD¦2Üö Ý Æ›ú ø3xÆñ£éïÀÌðÁ¢¡ø¦FpWž1Ÿ/šlôU24ž <@bY"ó…íæ“–ÌÔX§2> y^}­Ý¿‘·ÔÚŠ§z8ÂØlM©ÜêVˆ¨«$(ÄÚæÖC ^ ß®¥a{ ý?hTo~bx%e'š­åºßø³ŽzU5x!s÷)ð³£ ûšrï¤hø'ÃS”©ðŽdH¡üÔ—™gùÛJœ²¢ñ*Ï+t¡ã9tB£Xú È·*† #,kåØÿR0Òe™‹¸/0¡›â­Rü$Ï#¯· ã,[#´,’º´ qQ“¢ž²kÔ*d°è‡qƒ!3Ä‘îùº‚ST‘S!3VñVI×Ì”ÕÛòj8$ÏiˆkÎPÃáм¦ü¹[o…Lgý–VòÅ8ŒtL‹G Î=ÀQ%÷ÃŒ`é:‘²zÛ¼&Ž±ÕÖNKäÔb'r<$ùƒà÷ìöŠ ‹ºwñ?¥íü™Z!8C¥±iÓŠŽ ¿ÇV—·.cÇ ™¶%ñ×ÒIÒ«áJqDƒ ï}wmHà0¾‡Ë+8ß/ZØ=Ç)ál*µ†Š-*î å²7{ÊÊ(­Å†x3~FY¦»­,™£5‹ċðUÃù–Ÿé8^è\¸¤zU«›°;y”P}§:²ŠlÑõ…¦û2”fpÝçGÑGºðuUDÏ–^©&Ëb†Tq;Ö-dªØ>ž¬Ñ›SnÏŠ^ åËŽg® ‚[1­&Þ¯"£íâñA\bÁTI@VZù‚©RËjªN(¢Ùv·,õ9† T&Hq•Ï  ÄTà’/¸l®MR1<_hŸ$ÏyVzp„tØ\Ž‘Þµe6¶¢c>ª‰ºÈ$÷¤+>,$÷Aq£I”pÍô±ù.¥^y>^WZòÞA£þSnÅäÜ^c%.¨aÙŒ|?Iä{ò/ï¹ÀŸ‹r`çÈë¾LTá'2iº)VyNEs9ï[ʌ͖嘼òœkÆÿ èû«R+nùs2êß1ŠF;—JZðÇ6šåÍ,ãæh³÷>Y2ú_dLIA¿ñYdlÏÞüœû#²qúƒK¨ÀÔªO¨xâ²îÎl@)ñËAö¶ÿ¬<$?‹ƒ1 >àÕ¹RÇ1L戎(ë7^êŠæW¼¹¿¿|Ãþë¼Õiò›ÌKYáÊ¢'m¹& §yU¿%kG£ð‘ƒ Î…òfVâý)Ê_¦,1cØÙš«Ë[°”!Z™L¿Ï”q}؈z2qªò¿øã·Þs§f&6ƒ¹†×Ð]uW¸},œÒ"¼Íúy¸¦+0Õ&‰+¯~D¾|‚¿l(-xÛ‘02;Ù¸TbÆp) C~’ ëãõƒõåõŽ=`-DnrPˆËåÎÜáMyO‚ªL=è@6²ûE ¤?ɺ¬yÃETÐûà*o)›ë•„k_b)q!€±Näs«2È´šŒ1 x ËÃݨHݪîÐ÷µDü“ ×Ǧ¼÷EpGý.2üØÌETHÀ²ç~² Åí%ü½G&KNw¢5·ÓôÚ¬ù¢ö4vFLÜkFôö]}"ó‹ÙŒl’HYhÂN7Üã¬G®ZKù$¼’)£¼(1%þ O»FËŒæûÀ;˹%»å©Ù åàÄâÔÝ’P•l/ÕҘܞ… §¿ÆqQ_À I›e³ÙŠš)AñiÑoô°™R a³JËeÚÁxy£Ï_ÊHŸ;[G¶j\mµä?WtÒ)ôKÑ[£X!éL4®¨l3Z NqŦ권LÎ:øÕB60Ÿïå;~o< ~nÿ DŪ%’i$=öoœÖÖhêb!)Ç]®ßúÊ˘h½jÿë4YÜj¼¥ävM1¯^áõsΠФQ1Uß07L¤Ü:Ö7Ê%³ ¯àVü¬Õäú­·Ì6ëw$”áԆ̔Ïz0’‚Pô!§ÂTQ±c*ìùSEivÅYåÑe+¶ámäú­·ü³v—@N^LnZõë{à°·œñË%Vð6“U™£òÑm>{Kr°»’¬«$Î@$Ì,é©X\£Gf¸³³Se'"«36Ò‡ø勪'_‘r±¿tHW;(w‚äÚ€ÑÃDõ//WÜW9scÜAð…IL…²É}îâlƒÄ/—XTͤÈRú(¿Éê¸À«Tl’k Sn€Ü°=T1ÿàuh-+ƒ¦{"¹ K³p.ÂäfUâ'§È"Ÿ{áIÝQÌÑ=¬EÕ井ÂðS ݤ‰ä$ú+y¼ Oü_ýZàøÚÁ®gBþrI êq.ýR(öºØåÔ?yWcS´# «·-„+ QS)¹+¥øzäs_{ê˜CؒΧBi)WÅA©ž×íÅ~u¥Æ¦X½í|¹âSß“;ÃÖu.v¢ } Š·§‡¿)“fÇùTè§^F¥ÂÆxmµôiM)tP†‘·#å†Ï‹aòCR<´d×™Vë¡Å«=ûKùàà|*,1lëÝ°P^§°ãð &üÄe:ÄX4D‰ÞzßråÊ/(…Œ@°É-ÕçSa=Õp‰*(Ïž›x¯ÀÞÀ:§¹t•í‡0„«º»(kõÖ&rå×Ê/¯lcÙ~d ‰Šª¸à5Â’²ìù¨n 6ŠkÐl-)ôÓ’Ÿè™~rî¦Ùaró¡ñŽ©µ}úï”oê|åÙFX¥,{Ž­ŸjÁÍP° '](§Büvµu”Ð!¼&›d¤\ö$¾UºAqù¹8)ˆõ;bÂÊ”[§¿pNÇ—ÙÄi®í ™‚_€›È£gìê—ä2ªñÚ¹-8+zs ·Î×ïðåò}zá‹/b³W¹”-Р~§7›D{è-ëˆÑGÆÑÔQÃÎÐ)îJ/Z6B©V'Ä—ëë-3_Ú±´ofý%ÑÜCvòsÁ؈ Þ(óÇI¶è“¿¥†G**ÑˤÈñc"ê]*§¢ v™ERҶʲôÄ.“ eÞ4ËðÅŽ aró¿?¯±…‚ñŒâ!)'XV庄Ì%£L•YÏ%T Œ¥ÆUØO'§jŒž¢±†%”Hª.ï·> 7o(ig¦—œ$žØy^ Ž©—‘©ð„ÞKêÖà š™[°¸š9p’‚˜ûPáÑK‘²Wj&c³äévÞ±ÿ˜ÈÏœç«!; 9Äa20K³3„7j÷#¾ðÁç4¶¢  ásxæ¶Í:Ù Ö>' …Ž»Cî Þ¿Ag+8]®Ÿãlò<È5 £J@‡n’<¥ƒ=Ò?‹+J+GLºiÉù^Œ”$úB·(ÇÚJ†+‰3éÜ=|l°[î¶k¨¾"ŒäšEwëáI"¯ŠíñúÍàá5lY[ã$õ”uÎRz‹ÌÛy¥p3O ®[Å‹âàûl£Ýó8ÿed<¦•@®Y,¥ÊÆ$E‘BDª{^Ýñåhì«Îüw=W€pƒ¡UÉ”(naºÂêÈ›Å)§dFÎÖŽ™È•A¬RÆ!õ\EÊÕbðiQ‘Sq¹ù¢o0)Y\®,0`ÄT7‘…(5ð®0ƒÁå“´óQÖäp ýÓ 9hÆ ÿre¿4¢XÔÆà/Ey‹–œéá&ŸÀäÿm(²(˜Mäs1ž¤°˜gÖ Â|l2-][*:ÜÁ–/oàFí^·À¯¡2B‰ä/àc£j‘ö´°ðOì`þç3‡RXkcCŠ'– O8×c£DŒàA€ÂP)eù“"2RÄžÐS™¥øK>¨„L#ó#ÉFN…Ï«1Ã!÷a}žmf›^é5~FÿÜ‹‚7C\¡à›ò¯î:¹«Â5gÃxn2RÄöƒÜ(í÷ÏmAQ0ÿYmÂ'#§‚ŸzJu¦²ä`;Ç¿`|Cá‡Ê‰Q›wOz³K'šÛÉ,%³&6Âá½ö}¥–Þ ˆ´;|Ù$E%?ºäo€R_ÏÇ7ýÅé§ÿù¶ NlRÆ"âÍ{‘þì!6²/SÌ0ñ{èïÜ®âÛºîÁe±òIœ×dò˜°Ÿd/a‘†úÅB±¶¯JÑÛ±ÌãÝd+Í V\í–_‘òfæ^0˜m‹N4ƒ“WI1ïøž NÖQnêŽ ŽP«ÕA#v†Éæc±†|aO¥ÜhSž~Xn9üuŸ¡BnL¨bâ†i}Ñ¿"Ñ›9ø!_ ³8mÊ–jŠî³žŠTØh½ÚÄÄÈ"(É´æM(M‹IUæ§;ª,‹ÂƒB ¾ žœƒNŸ-×ñ ­Õ#Ñ/·‚E1oYn$£po†È¦`Æ‘5z±¨‰l¨!±0F±Q¤BÄ>zh‘*ýn‚ud2 Ã]X Ù3–©ˆJÓ›ä[p§5ÍÝ(9#dÓÐ(h}µ™}”-*ë˜DEÚh IÅnâÀáãVå¼Ìª¾ ûµ"¨1E?ŒRFyÓòÔí ¤+¥«|häcr†JÑ !Œîˆ £àpo«nóÅeQƒñ-’Ih‚a™^<5ó¶Š=-£_Ù]D¯kƒÑháŒf#GØ­*ë,< gÎÉÔ•¯{\P.ãƒÏ©ì9t¢bÙ]•Ð·SÄ]=â nâ¼wBÔŒpÛ¢†¥Páa#*Œ‰ÝrôSY€g™’¾"ÄyÊÚë[éÊñB VÒZûÃhï«Ìêå²h¶ýÓmWàÊEzñ£,¨«–òþeÕ©p¥Vÿ[1^ì4jò5ئâÓØv³òyQê¡ÿWР«)A!) K~bÆ$•yW µÔÿÝ‹ç7’uÇ°cÕJÞ ŽðcØ°½d˜†~ÍhñH쥲ÈjÁÒ~!è=ÆÀ-uÄ«šZ§˜¹Á"æ WgøN2~AɜĂZÕªÀTýz£…flß@öèÐYÁcÕò¬®­R€‡ïU©ðßëQžÊÐVµ¶¿Ê Yñ1t>GuL¢Gܬù¥-ÂZÒ}Ó2† ¡>àŽòÿ'”Rÿ̦“ezaÚ¨jGyF=à]J6vÒ¦Œ/Øcè P΀v®5:± ßTfZÖø%foíâ7TêeØ`&Ï¿ãýý0ÂåتZ8h+— Rˆ¬&‚¡kgF@**“¶ž(†Gkññ$«|ÔöÑ’Gy ²S%ôå¶Xuo£[)¢eÃR|ˆóªddÇQ¿ÐKêTȯÎ<îcé 4‹ÓÁٵ݆¯Ä'v…Ê9ì°à?Z‚Ÿ=Æß{”˜ÉDÑüáVeÖ½‡´QÛ2~JÁR#`Š¡u>j³ú±¨Íx£ûÏH«`v åðb%—1ÙÏt Ý£X,ûÓÆ>í)çìæ#R͹Òê`DˆjSÓ£˜ ©+°‡BiÝ$“6Ö Õü›ì©ë$zo{¬ä8º·ÄM6ÔT‚Ä™ó¥øN‰T›:qÊ0çþ(mÔIBhR¢×îÒJ…·ßÜéo^.¼ÃÒNþõ§µsîkÕû“/ãóžU¥À½ºÜä¦ZS¯±« 异òQðç•à`’Ö ±É¿DÞ¶ú8Qfôì_GĆ bXÉ¡ˆOèmæ‡Ò”d8ľ‡Ì‰¦2'©Ðócô¯§Ø¤ÐÉž Ã'’3KãDT8†4¼ËµuU%øÒ|† å½ ¨µ¢ÞU2Ê_­¾ cßÎþòës›io£JS¢[ÖccÍ ÌÈ‚6_/åvï´‘Wނȧ’ùø¤o'7_Œ, ýY•Æ)ºŽ«eçÝn¡o_Ø)fåʲžc?6ÖÌ`‡e®p—š3ó^‘Ïr —;U™1Û·†ºÉ¬æBÁ¬¿Ù=eü¥—UsL)V¹² Lö”"p•W†¿Ž°Û s$gÒëM–½ª@¼l žþÖjè(I£¹*Ù/Rµò÷åV`Èkö}K8y­XÙÉð[dwt5lz¤†.ÐK'Ùn•—]{¥@ÍÞɤ[ú>‚ª/ˆB®2g|I‡rª6ÇÎaö˜hM^+U–_Ÿ™Gwqt3 Ö0ëÒxHå$p9j¶ÌE…úxú¼VUÃ[CÎNŽ\ÎÕú\bV;Üb¦õ4y§ûuu¡}\©¥³ÙÌÞ—53ðÕAA=Ó8Nzêl”ŒWDa¨°?<\hçæÙÃ.0¥ŒòòÙÈÕz¿Ü*É%Éc¼yi¦O`#9ÐPoÄö\…–^¶&¢ÿEêw!››ü÷­.Qzî¬ï¼R@! a8Zb/jUj2ãLù-›Ç<„V.Ô—Î|Ç[G¤€„ྫྷ—ÓPqÔ£¬úZc±ÎL Žf¹ r?VUÁKÔ9øÏۈфN•Âõþ IBÌmÒÅÛPc~6ýXãzÊ(oÊgTþa¸öíáLîšXA悼qú€Áweœ™Í&0§Š ð1B«[¾.Ž$±<6.­ðRÅ}+Ív·ðÔ—¦Ô,ßÜÍ®"_Ë,ƒc½Êìµ º¶h-ÔêØùRyG³ŸÃŠÞ%RùnÈ!c·—â¿j#0±8…’,fóòÿá«ÓtøM)Þ'€K‚ÞØ6Ö—-ûeôžÍ¦6Pº‹¬£ÙHF_+ò‡²r£I'fD=âþ$þ= ìW´ÃhT ùû6ú†Kò©A» ½;ã4ðgä8f`=QÜmGr°yssÐùÞz¥„=3«$Ï?)æë—¨áD råøŠK&¡Û¹¸Ã¨ãÜÁæéÝ&(GÕRË»SpœÒ}¦ý¢ApA‹Ì¾UXÅ-Þó &ÍÑt¬S/Èô0ȧ¶ oS`û .ê5‹G´Ä`¡ÇÈ35{°B¶ÉÿIŽXl0½ÌY2ýõÝd§~l_/´b†Å½Vbà@VsjÛ) ±ßdäBŸ¶¹éÄŽ’vd¶éíg= þ-N†=¸ß­"ëCï÷äòhÊî+ìMåtá¬vµN6¨c‰®Ã]gþ\jËÆâ=ŸðшCeÿ èt#d :9Ýš©'‚׆OõrA¦Šø9ª—ÜRìg7‰qÆèÆåF½2Òhœ‹/•7ì9ùõV [oCûF ¹úåÕ›õÖ±POÃhÄ!ËKo•òÇéM2¦µ9ÁŠIëµá¡›.vÜnípj-3—˜õ)`ËBX(½]ÊöÒuÇçãÞc)¯P$Bizç´EYPˆB¼Iò°ÊàV v¿>̃3¨èŸ6"pÕdtŒ7?¸éq!pô€e—Ñí€IçAf•e¬OÄOÖ‚ä;ù:L¼:Ž·¨Çdk~ÊF#ù>”§ãCÿT§Ã¦ÍÎè[QØ€ˆVÀå$¿ëàL0ÔýÜUâ±Æóhâ¾Aó†u`öŸºÑˆÃ“ŽÇ~è(lÆŠUAó-°åQ²&óÝÞÏî( Ûƒò,€˜ù‘eÔÝu1HŽ°}0ÁÀB§R"=~æ+:JO=óú™6$xQ²zµvкeôsVmÏtΠD¼Sjy¶(Q@Á>y º¸„Ε•@ɉ‘Ü eÜVuâ+Vpj¡óGkÿŪÍië^µR[dºXáÿµº¦ˆ endstream endobj 10 0 obj 18736 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000019828 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000752 00000 n 0000000731 00000 n 0000000852 00000 n 0000019803 00000 n 0000019893 00000 n 0000020021 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 20074 %%EOF ast-8.3.0/sun210_figures/frontb.pdf0000664000175000017500000015767113004147321014011 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P011Ó3Q014QÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!ê1s endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 414 446.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 414 447 ] /Resources 7 0 R >> stream xœ+ä T(ä2P011W014QÐ511Ó3¶´P(JUWÈã*ä‰(€T˜éYzf ɹ\ú‰ éÅ ú– .ù\@Tò endstream endobj 8 0 obj 74 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 460 /Height 496 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœì|ÅÛÇ“K¥%9RIBï]¤wR”¢4iJ‘¦R¥+ Hï ‚4©ÒKB/ Ò¤Jï„$üÞßeÿïy\Ùìíµ½d¿æƒw·»3³»3Ï<ÏÌ3ÏÎÆÇÇÇÄܹsK¼]°`App°¥LS+|Dv¹üÒ¥KµjÕ:uê”ì¬ùÒ?üðÃ/^ØRå ¿»4hÐ`×®]vOYÅù$%%uïÞ}Ê”)®.ÈV‰{÷îQGš?¾ð•¢,K–,‡6<¿K—.ì&fÍšuíÚµü122rÓ¦M†'Œ3¦H‘"“&Mb»ž>}zÎœ9çÍ›gx¿fÏž§ÝºuëÂ… åÊ•ãgñBÖ­[·F .¼sçŽÙLS+ö’±ÎÏZá8îîR÷sS‘a•è۷履~jxtÚ´iÔõ_)Ù(ŸX>áçÏŸK)*á…B©x¡Ñ”ÑQÚ¦wjéÓBòi󩲄LoÁH7ã«ùòË/™é«Yºtéøñã Oæ㥅.ñõˆ·bÞ,³Ö-Y²¤ÑЙ?~Æ …ÏUªT‰5:aÍš5‰Âg~àW£x /´TÖ[Ó©ÃLS1âoçÞ½{ì;tèÀŠqçÎaÆEGGŸ8qÂìåFŸõÒ²èÝ»7«¢Q÷jšµá/Û·o DÜ¥K—ªU«Ö¦M›¤¤¤ïHüB¥™3}úô„„Ó£”üZ±bŃ"Y0)^bXÂ~ýú±–V6|ÖºÆ_¾|Yÿ”,=ákTT”PY†2eÊüðÃ"åçù†7núÜ _Ÿv¯^½ø´?.­_¿~§NCÿòs³fÍô×æNÆЈ³ó0aOR濼MæÅçÉ.CʽT¯^Bƪ;e+V¬àg>Û5jP‚¥XNÂ*jx!rÓ¦M-å‹cF†Ò[¼fš¾Í9rð9ðÙòù3µ.]ºè ¯†ªãµk×LÂÝ»w)Þ—/_.|ý믿ø@Ξ=+å-ψøøxÊ·%K–è¡NkúºÙ/èu]~0yöì™á üjt/1Ô–ðóó3Õ‘ 3Mň»ôíÛ—MÒð—U«V±ß7¼ÜÒg#íhĈ†ƒBH©&,Xа¯dUiݺõéÓ§S¼#ñ ytݺu†GË•+§¯üÀ¯üQ“ÊŸ?¿a ù”âââ s¤Ta6|J–ž E¿nݺUÿË… ¨ª‰”ŸçÞ¸és3}MT‡¨8 Ÿ©_;wNˆm2GßÊnݺ¥g‡ùæÉ“Ç°£¤Íèééi8.'~/FF«øR^ñë²eËô'P³©J)jíÚµgÍše˜²á…FGùâ˜ÑÎ; ïÔôÞÍ~~üø1¿ꢴ ó2}5F JfDDÄÉ“')p(~MõC)ˆÈØ=z°ó•r²þwÛO~(- |‰ßcùòåM?,].Ò×#Yy(Z´¨xÖ†¿Ðü¤‘%’µ%Ä/4=ºpáÂ&MšŸù_ ²¥SO3,¡éüi­Zµþøã£-= 4koÜTq2ºÜìkÒŸF½:_¾|ì¨1ÎtX ¼~ýºá/Tæm¹ñ£‚øI\ÞïÅ‹-](~Ôl.–Þ&­!ñ“M_iCX´hûñ *ÀVaé±L:µP¡BF*AÆŒ_½zet&+†¾ûã{1UtÙOž`¨‡ð¥4C† ¦F¨a¦©ñJkÖj°t¹¸Œåk5RB¬²È¤#~¡éQ¶eC#ˆ_ V-árS­'˜V9qëRúÉR.g)ˆ_hzÔÐåýò«áQžlØ"Ì>.^e8‘az¦U­Ò´„)^žâkÒÃöþùçŸ7nÜXÊÉ"…ùQúK”q§e,U5‘fÓ£Ž“±¦¯Æ´!lØ°![¶l¥K—þöÛo-•Ù^nØÑß¿ßT\¼xqTT”ÙÎô£>2ÍoÕª•Þm oß¾?þø£Ñ _|ñÅwß}'|æ~5:—ðBKe¦­g*– 3MňWÚvíÚ1Âð—ØØØï¿ÿÞìåFŸgÎœixáôéÓæÅ›XÎœ9÷íÛ§ÿš˜˜È×j8®h ñ M6iÒdÀ€Â×þýûó«áàùäÃ4'L˜@±ixÂÚµk£££M•U¹sçò 6½þù‡Z4 |ݾ}{ M³[·n±,ªa™ù£þafÍpvøádžÙèÑ£ §M3MňWÚ+W®äÎ{ðàÁwïÞewÉN‡ÏÖЯCDÆê/¼wïÞ˜1c"##f¬²gÏ~èÐ!K…¡Á*'8™Ü¼y³Y³f4+¤¬¿Pü¨à!Àï&žÆ“y‰øãbu¢BQÆZ§J²[¥i yÔðÆù0i¬ú_¾&ýÓÖ¯¹«T©¥Gò4w=Þ{ï=ýµ%K–dU—èW åGé/1Å;•-cYEõ•/…¯†/H?ökz”ÉŽ ³Â4¨p”HöÛ5Ôi‹)¢Ÿ€Ûµkˆ©MdÄ… BBB„I:¡Š n0;vì`–,yýúµààÁ"=~üxõêÕ¼A#}²C‡­[·æí?yòdݺu•+W8p á üJÕT¨„<'ά1YÞuýúõõ¿$$$*ThÈ!|–2M­øúúšš:°£éÔ©SúôéÓ¥K÷Á^:zØy™ýÌD„ y ™¶mÛ²Û2Êú—_~¡%e˜—a HVÆÇKw”¦cž–¿Pü(¿ Ž¦É ±y²¥û5„-´W¯^ÔÌõOÉÒ“1›ˆø:6 ¹º %4ûšˆÑÓ¦âÊ_„1[á]°‘ê²iðw¶;³÷•â½[{/âïÂèNSL\„˜˜Á±–/…¯ÆhrÍ訑œÜ³gѵ¶¼M‘WC[ãóÏ?7<ù›dR¼; XÁ¿Ú´ŠæÍ›W¼E#¹GŠÄúÀþzÆŒF@_ŸýüüªU«6nÜ8#õ†_õÍÄô ³Š6jÔhРA†—œ={–·/’©ŠUHÔ7T\Οþiè ž6Q««ŠÛ¡VZw–¦‘"”Q««ŠÛ¡VZwáîÝ»®.‚ëQ««ŠÛ!}ÜLEÅå¨ÕUEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEœ˜ÁÇÿû3ülôU«uuqUTTT\ %aŠÒRÿ90±±RSöõM9AýWU «¨¨¸/‚þ©dán^üúùé ¯¢¢¢¢ôbJøÀ­Ò?‹Í ·£Ñ¨£***ÎF0öÓÔ@(•^#u7Õß²ŠŠŠÓ0AUÅ ÞûUˆŠŠŠµ*«ª Çh®M}\***fѦª‚ E.¦ŠŠJZ†²T?Ò¨ÊU»£)¨¨¤MôC¬ oøZh=Þ0Ä-þñLW6ôg æ***òÐËU×Ú°1ˆ B¡xôí’3á¥1sgz)5\“QQI=èg¯œÜœMe©ðˆÀX¸Òw–¹³ ‘½ú¥ª°UQq/Øfzç4^S‰êrYj-¦²×™R××Wש«ÌTT~«£E«ÑH©ÛIT)˜J]Gú «ÌTa«¢¢4ôñ©·ˆÕH¨*ŽÉŽú:TËÕ/éU…­ŠŠk†[ÙWÇÞ€‘QâÔá¯êÞ·pË8q¹š6…ªFZ®ƒž…­ŸŸ:`«¢âlþ[>ïóRødèƒ>·q[Fj¼j 2!)OxªrÕZô*®ƒô[avL£QÕZ‡8/Ÿ$¶5OíƒÒ(=îã¾]RÖ«¬ÔÍÖ`^äúÀ§$J~†Ï–aÙ=ܳK^©ê·!)‹²_à >Iû>4ý‚ªÖª¨Ø‹gx¶Û;ÄÌóz¢óÂÒ>ù?_ÇuÛS6t°¤²Æ#~7vøh@ñ[•Gbä!z׶ µÂW¶;ù j¡VŠ¡Xwt_‚%¦£1²ÔZ5Ú­ŠŠíPeõôyåøüûØýl¼¶'h¨²Zå €„MØÔý)4¢Õ}Žâ¨íåIݼ«8ÀNªñÉW@Z—qÙ.‰«j­ŠŠl¦Äó z( Ø%A½hµË(ë?øg†åFnþ}‰/á˜íi¦zØIý?>ÆÇ!)òã1Þ^ÂVX¨«JZ)P¨êf²ü^LµƒàÒ8hë8ŽÅÐlÈVeb¡]4íTÏK¼4¶“0IÞd¥jHq2i_ÙKqÕ‹Vç¬HDâl¨‡z_à‹ó8ïèS‚°mÖ|YïãýÍØœ„$Û“UÕZC.à‚ŸöuWJWåá+¼Zƒ5l­ÁvÉÂ+¿”±acáó à¦<ÄÃɘüÞʉœ£1ú®Ùž¦0/¦JZ•´L€6Qpsõ×ÆÛh-R }†Ï"AÛs*¦Æ!Î^…”Á3<›‚)9£*¬Æj»èfi„ƒ8صÐ6EÓMØdû£SuZ•´É¿øWã“HÝu Æ<ÁÙéP2Sí)‚"¹‘{†Á;ÒF¨T/Á’â(^`A"]]"·Ub:¦—DɼÈ; “¨åÚ˜ *iUÒwq—Z« »>Â#ÙéÇñèˆÀ®èº{ë°Ê‚mÁ–š¨™ùçaž*i­b7v·B«ÌÈÜ=Nã´©éCת¨¤J¨×yùêViùiŸÝÁÙéЄ¬ÚaŽávtkw4[±õ¼CÅl>æ«£Vq7G`DVd­‹º±ÑÆÔÔqZ•T‰à3à£}rçä¥ð/faMï"(2sŸã¹}Kè¶c{5Tã]¬ÁÅêÞÊ„}4»'¾ý²(»ëm|zªN«’jø-æ¦Oà3öá2,“—Åé$LŠFtC4܌ͩ@4­ÆêB(TUÎ⬫ËâfÐø ¿±“zoÛÞOQÒªáUÜV]ÝZ-MRûØ9OñTF ¼ê;|…¨fhö7þ¶{ ]ÈK¼œ‚)áï…^®õ‚pG(ZWaUi”.”´¶Œ½áUI«âvè–k>Ì[WÞå÷po8†SµFëT&] ¹ƒ;=Ñ3 a“1™R×ÕÅq?ÖaÚb(¶lIG´ê ­Š[ [ kÃr-ꮃ1832·Gûð}˦L؉TCµ"(r]]÷CÐi £p%TÚ‰¶$¥¨(] —ÀG²¥k"gaV¢>ÆÇöŠâ.PPüŠ_³ ËçøÜM§ó\ +Ï|ÌÏ…\õQÿNÈNGˆå¥JZ¢[ ôPv }Tä¨ÎÆaû̸ûâÂ(x\]·ä%^NÆäDØØMSÒj4êЊR úêá÷B¶úºûk FQµqH-Õ°+#Ù½ãï겸%ñx… d†É›lP‡T\ÎĘ#Ô]=ÉS_©¶uFçìÈ>sÕP†ÜÅÝvh—ùSß–âN㮵FëhD/ÀÙ.^ÂЪЪ8Ÿ$¤Ó>§t+g/JTÁ¦û_¨1W-±«£Õm_°ŸfÙ‡}eP¦<ÊÛ2üâë«. Sq*¿Æ\óôKðÑ>ùÿʸ|ö¼…·j¢¦º}@ŠÄ!®+ºfC¶-Øâ겸+Tbç`NdaoeË"nuè@Å PÿL¯}áéŸÐ;v¹ û‹5¼:Ð|[‚%Ž(^je-ÖR¡ý _½Â+W—Å]y€½Ð+á³1[öšÁV]«â Å\ñ |â­},/æÀr,§.Ñ}ã±ÝË–êa÷T µ*£òE\”~ÕS<ÝŠ­μоŽfFü¦ô@ ܈¶Ì¹ãoÞl”±Å¿‹ ­:n b_ôêkßØ•2.§|hˆ†P -ûeÙµ¯¯ñu ‰ò³*  MØdiÜ›¿oö¡ZU,¥“šD1ãLÌ E(‹lÏ uÜ@ÅŽ\Áê®òÔ××xMÓŒêë(ŒR]ëåq ×(!Ça\[´}oG"Ò ^>ðñƒ_ŠòÓŽŠbø ²C1~mõ ±}¨»ˆß[¸õ>Þ/ˆ‚²×Ö©.*vaxÌ6ª¯é´Ïe aѪ­åPîŽ8¢l©•{¸·ë(ͨü³{¢âÊÇؽçb.Ÿêiœn„F°ìþ\RBV†‡xx —ŽâèNì\€C0„"«(Šf@†B(Ôí&còPxǺ «ØgÄHÙÁ"|}u#´ªB«"ƒx¡ñIô z<7VÎ.ÔjÂ>ãUÇW)Prά–h™¹ƒô.ÞŒÁ˱œrÌìù4Æb,%0¥„“‹*…ïÌùŸ”@‰ŒÈXû£ÿ¬±eNßq°T Ѐ‚ìÈƪB«"ƒ¥GÎQºújŸÊ˜Ÿº‹»MÑ´0 §‘ˆ.²y„G+°¢:åB.jSmÑ– !uTé&C br"'Õ0ÅvdOñt;¶Â¨:¨Ã¾£ tDÇy˜'[ 9v ´h)ÈNAS‘ΘMš¨b×ɸv#6fEVZŽ 7]õÏÃ8<£+£rê¢î$L:²"ÝÇýr(WµmÙzÒ9°ï8†cÓ0íC|H œõ¤+ºRWHÉOáTQ¥zp÷ä¥@1«Ž¨ˆ“€?í3Màã[­V3âß=iêîÆnG”ͭქ±LÙŽðB(Ô}7a“½Â°;£°*‚"pÁ. :ö)ãïïðÝ;x'#2ÒZÿ¿Ø²‡¦]àé…^þԽ奠Ž¨ˆ°áÈ-¯ ÇžIT¬½–úI>ä뀪ï«!4á×a]´ FpT™Žé–ÆWmg<ÆS€»ãr°‡xHK1ˆÀh±+]뜰"ù-¾•½TÁ×W³*ÆLŒ9âu³[ìbFë\Ì CØb,vDÁÜ”}Ø×½#Q&cò5\sB¦´Áç`Žòrqˆ›‰™5PƒÂö|° Ë\yìnUB¥:¨s7䥠Ž¨è¡PM§}® |<~«ÕÑ^àu×Â(|§Q6·ãîLÀ>jõÃ0Ìù³~p!7rwC7Å΂IáîÍÆìwñnfdn‹¶›°Éù·Ã`@¢d‡>‹E@€} ¥â~<Â#o¢·öñu\·öÚ38S%ÙÜÅíÜq°ŸÚŽíïã}A&ìÂ.æ>îÓz© Z×MÜœ„IeQVØ!Âù;»mÆff=Så].ì0®Ž¤Y.⢧Ï+?í3Ø4KC:SQ07âŒÅXj­ÅPlf)d8: I=ѳ ZÜ@ɜùAhšð‹°( ²“¢ B¥%áúÝÂ-ýù—p‰ºDk´–í*£ϦMhi´Ók_ȸvFІJã«·ŽâhWtövTæÖ0£1šB‰æ†« b7^áÕ ¬¨‰šˆŒÁ2zšY‘•RÚÒ ·q› sBò6Þf.‡q8ñããÒ(-{ÿ*´j´®4ÅZ¬õÔ>ȨµZ}¥þÐ l©l©JÔ†hHñ5#i̺º8b,ÆâHD¦>oºS8Õ=(› ‰ô½hy&¯Ø˜â™‰H¤°Ý‡}TžiäAž1CÕ‚/}/öÊ+³ºH!í Û¿À÷U€ÖêI„ë¸^UY«Óì>Sl¤ïàlÈ6S_@Ž à|VcµDÁâv<óé˜NH…“ªiŠÁu©Ê*§\퀴Yê û/øEVyU1›úy×þÚxoíc±DþÄŸìÄÙ­ËvtkØÊj¡V!b[–?ÄUPñ¶E2(ÖêõXÏÞ?'rŠ÷}üÏâ÷5¾f‡•>Á'ò–橳`©vú¾Ú§ßDqðv`«ÖoøÍS8”®ïâ]Z‹ °À}ûv‘Yå[|ëê‚8ýØß ¢5L+y bh{.ÏñœÑ¾4gŽBÎfvDÝX<õ±.æ‘Wà?í3›•LôDìÁGLÉìÆî¨!H×T°ÉË\ Y=CeÇFp áÐ{xÊDL4Ôi`ÇM~ïáJÚöh/Ãïê¸Aêbå‘Kžéâ»ÅZ½‹jÛ ɇ|im‰Á5\k‡vY‘u!¦éªç>î—B)Ùv®A½½QÕ¤† 8zÙ8P` +FWt¥0×B;ƒdD¶6SØâ~«ŸUÞ`JÌ1¯¨›2‚hÑ&jŽæl’²Ã¹#l8ßá»`ŽÏSåÚŠ‡xXÕ?ÆÇn½L"û±¿.êæ@Žù˜ow+0ƒs!W34‹F´ŒïØXDE©KnݘyGŽz¦·õOk/d§L3¹%Z¦J9c‰ØXEÙ*Ï⬫Ëâ@â_ ÕørÝÅ5ÂFvc7ï—2öüáˆô§`Jä¡€-Òl5ÖF?;r^^ª6ë–Œ‰Ù­‰º1#Öêý7ãWå» ‹ûNñXËMÜlŠ¦TH–c¹«Ëâ žá¥A=ÔK#bÉc¹‘›:¼#ÖÎ̬HDÆáðC(B'a’UmGÐfU1ë^Œ9²‰¬Œ0/·p«8Š÷AŸT?d'@“y"&†!l8†§©¸âÔf¡QÚ³؆m?âGÊÀOñé]ܵoú«°*áqðÎUEÕʨlÕ^ÔfU1ëFŒŠÙI v^¬Õïe\·|C0Ä¥R Çp¬ŠÕEÝ´6©'€ŠYÞ~Z³±ˆ|·h¦uG÷DÌÁû*B™}ØG%v ¦PäÎÄLé— bV›U>Þ¾¯5Aælý×Ú ¯àJNäƒ1(”â Tˆ!ù ?¥Ý,iJÌN{Á‘Š¨HmÓ¾cï{°‡¢Up£[å a„qÔ±Yå“^ûB£}xVÁ^Çõ<Èó=¾wD©”ÆQ-ŒÂïãý«¸ê겸ž´#f\ ¨mRϤB;Cí8·»[Ã&ø“¿Â«‘‰Héãüêج’ñòI¢€•aöÞÄÍ(ð ¾qD©›ÕWø*¡¿âWW—EAPÌ6FcŠY·[&lˆ±)~ ×ê¡^ä ¥o¯ŒVc5µÙýØ/|=ˆƒ¹‘»;ºKìÅÔ±Ye’A›@+#ÁÜ¡R7ÃQ*EÁ‡S Õj£¶ã6Õr_1ÛÍS±˜ÕÉšB=3ÑÑùØ%¯µXKmV¿ÆC<ä³}oKœSŬÒìyœ·öÂ8ÄGñèˆR)ŠŸñ3ëüXŒMË£¯âPÌÖB­h‘Š‘ÈJŠÁöhŸÙ7`ƒ]òZ‚%Ùí_ü«ÿe ¦Ð†Zƒ5R.W§À”Ã×GþðôOžâ)žV@…¾èëˆR)Þft¡®®ÌHÚŠ‚Ϫ&j~†Ï\]GáqM•ú'cOô´‹#ßdL·|†;fÆaŠñ‘)¥#S§À”À˜˜ÝžQ×gÆž´öÂD$Òjþ§b¥…œÄÉB(DÝLF´±´ Åì[x+µŽ±&LÇtñs(„[¢e‘V˯ð“2Ü[í6nWA•¦h*%Ä:æZ¦Ùç™>~ÚV«7¡€¥tå[NÝ‹ÖwaM³y˜çꂸù‘?UnÖF5µ*I9“Õ†•ç;|g{ùŸWEUÃ=È^âewt§ì5I°„:6ë*&ÇÕDݘkõJ.*®Ñ¹2*§n_ñŸ6C2Ú…K¸D“Ydß+7…u>A}ö.àBuT§x”îàj¶¸VhEÝØh>q6fG#ZÊ–:6ë|æ9./Ø ’w<,…R®Ý:))ióf»¹ÊÁvÔ]K£´µÑ9T 9…SYe–¹º v¦úQ;•xr’Æ`L¢¶b«-™R‰­‚*]ÐÅè÷ØŽð•X™b êج3Yzä5ر±rön[ŒÅ¬0®õ½OHHhݺu“&M‘øu\/‡rïá½4»é˜¡ŠE1›Ê¶\ügEV«ÂÇ"–­f†Ø2n „õ6ÝŠâ(Ž²ìcÛ##oLïf*;¨lŸ•}b¯Ømç&ò¾+‰’©&`û#<ʌ̷q[Ƶ+°‚Æ {Ù¹ÏÀŒ(a:!øhÐRtÍUŬ#`*ì*+Ã5‰uQ·+º:¢`HÞ•ÆÈÞçgÚb×qÝ9ηc16+²®¹¹fÔºQ5‡×ÌÒ0‹W/M¸&²qäû“ßßp~Cêöv¬?µQ;ÕŒrwDGÙ!æþÂ_y§7zË’ê†nõPÏ´ZR ‚]UÙ ˆ§àë y™«˜‡ê+•XyÞV_âË*¨b÷uè×pí³˜Ï¼½õr•vóýÁb`!2 Ô°çÚžO}’·]^¯p/ïÞ…ú²cÈíWrT$7ÊØháê‚؇?ñg.ä’-$ïã~ Ô¨úqˆ“q9ã»x׬§àí…^eP&EÏŸÕÍÀn Ù¢ x"ÏÛj!æ@Ž;¸c¯ÂœÇùOc>õ ô¢\õ òý6ö[W¹±6À€²(Ë /rZRRÒšCkh¤-£õ õŒnÝ{]ï/RÏè¢Óà‹.‰’NqrQÑ–¾ØétB§‚((#N’¥tNä´4õÖýY±Å[–ºÌ^Ì9ë™>~Qìeס`Ó´±½Ïñ|hÌPAk¥h;Þùš ýf(`W`E?ô³jÏå³×Ïv˜Ú!¤ZˆgfϨ6Q½×ö¾ýBÕl­€ÆK8Âùä]];ð+~mŒÆ6&2“#±ûd\K]: Q–"qI³êÚÛYóÐ3]ü˜X938ð€åoøMƵ÷ïßOLüŸH;Š£Âä¾w÷¨ØQ.‰}wèd·_‚n] ° ®LÍ6o÷¼ÓNWÇl%‹ØP„ʈ¯4@§?(›Ø˜Y¬u˜‡y%PÂR›¢™–â Ŭ¯¯ŒœUtÐñ|Ú.v¶Œk)1š I/ô’qíõë×#""Nœ:‘Q›Qï eaµƒ(djeø©«§näWÀϯ_Ãïþs˸Å:tèÖ-›–R¦>¨ÇæFn»o;è|FbdGt´=“8Iõþü ãÚÏð™Hì;ŠÙR(%+Lu3¿6ÞGûDÞ°üDL,Ò†a($òäÉ“ReJù¤óÑ)®Zï…X¨ Í?Âd!" ÕEÕýeÔ­‘´iUùô=ÓóvÉëì™ë£\ Ž,à/ÏŸ?ÇóB($â¸Þý*£²¸GUYUÌZ‹v[|6Çq0 aqÑÚ ™—oòd–ÖWiÑV;ÓÞü%/ôÿŸoë¢ý÷U º¨÷¿ $çr>î|ƒïxg÷ÎX>cHÖFÝ¿/ç¤zh(5Gsy†’¢hö£0Ê.I]Çõ·ðÖ0 ³ö¿ñw0‚-ZðQ·A›Æh,¾’×Ãbôq3L‰9æðX^øÊGx” ¹¤D™0ä®ýoÐ5½÷ßOÿ–‘¯£yÆ!´bÝU¨7uM>çh²4N!f蛼xõ¢ã¤Žéò§ó+ì×eA—' VL«¥žàIQý?»º 6ÁV{ù ®}ÐÇZósFT@K“´%ë¢n't™5GP:ÿ% >%¯DA Z£uô~>maµ”¿ÖŸ±¼LÍK]{3½’i—;,øoøp %þ.\T—•ï÷Û¿×ÖÔzeój5½Õ£ç)¸…§A.àBdYõ®.ˆMÔD͹˜k¯Ô¨äдÿZ5“«¢ªÈò±§xZec°H"±±êü—$<eŠ­+ïZ*ÅPLâ6|­ýcúk5¾Z_Ãí0û›äßÇAÿJOíþÉ»–õœïè$$í;3>f¼W —w÷lY~ Nfðþ›¿°õHПPóÿ?Ç$u3¶V-þsqxãp¯¬^ævHH´z21³‹Ùöå­xR”®”±öÚ*Q ‰Ð~Š«b ùß×Fm‘q†S8ŠPq?1ŠYu™­%b#{àšJi)”š)žù{Ìï>>š ͸Øq23s:ý€Ñoþbôœâ°déŠäQYSb{MÌÛ?O[CëWÌoð¦ÁªK­žèQõÝ÷Ìü*¨bß4ù4>ćLVzJ× ¨`cÖØ™™ã°È9!!êÀ¬tÖçe&­Lg¾—¨!~NÒiÓyy¶mï^ÍÔÐíÄô¦2smáÐ=ÛÆ Lºz¨aÿ :A«N¯²kÂî ⊨8#]]™°üÙÍîÑÈ©ù´C»:¨#}Ðà ÎÐ5¿a ‡,Èb Q:0k[ìYœe×fiQžÀ‚# 4­í [œÏd;±i“õUþZ¯¾šÊXêëVG M‰¯^´œÒR¦)ЩÀé;§í¼ûq×Ùð7b£« "“‰˜øÞ³{²‰Hl†f-ÑRú 31³6j‹c0¦ ‰ŒÏ¨³FØ2 ËwQUÇÁ¢áO¤SL'¯(¯Ñ±£-£@æ`Î ©™±É±ú9/}… ySö¾NöÝ’³1Îß?_¼gqJÚ¦}ô2Q‹5\ÈìGø)œ’~É-Ü€ÁCçà™òÏìÞ6nbh–'xBEÅ“w´«£z't’èÐÅ]¦ûƒÓ]hºŠx/¨bVà +ûò˜Q ¥,=ê¥1K½½½ƒ¼Wlu§8‹°( Q"s¬"Ä&ûqéÅì”d7‡²êøª€ªKd\t(µmäj-c1¶ êG¢ãñ,¡"ç³23#2öAéá²yæ@ äUfSc. Ñp0_…ïþ¦ÛÚ ðr('=†óqE¨øca“¯…ZâË@T1+àøH¶7, ´„XZ­^›^¤ù<ös÷šŒÂ…íÇ~Ù)Ä&èõ['lO›ø:±Ý‚všMù~åï=¹çø Ê#<¢Î–9¡šé¡Ñ/øEžÐ³æ²K›£9ó•¡÷ÞÄÍ@:ÈKœv=ŬôU`ìzÚ£}ŠiæE^ñe ª§ö‡|“M-Óßãï«õõÖzŸÁJ焸šòÂ…¹œ3qg²}”Í7—ï¤]“\]g@EkV|‰/+¡R|á›é Ad‘¾¿¶Cô^–- aÅP¬êñëJ¬¼ùŸßß|ŠO)“TŠÄüÈ/1t {«HDî1^ÝhÌiœG¸ÈÊ÷4Ê “ö•ìaX²«s#·©gȪ#«¼½ü´~îå<€ä‘(¶P³½†1tóPïìÞ%ú”xðâ—{÷®ÛªJDâ>웈‰-Ñ2²ÑÜ m> £¶aÛÔÉ[ Å^û­|Žç¥Pêü"~ÚÜ¡F-eü–&!Õ•~º(JæIõ³Â(l_ò~*‡rÂgO­§gç°­ÃìS8WÀ.£JÌÄLWÄI¼~ýºùÍ5áš/V~áª2\ÄůðUd¡ªFIâ/Ž»¸›9l©ö.¡"*ÎÁÃ_ãñ8ŒËŽìÕPm%VÚåÑ]Ávs)šƒ0¨5ZKIð:®‡!L$TcêVe=4I¶Œ°W¥M'(±:«õ´_Ñ\Ã7ø&Õ˜òëÁ_}rù”PúÙ+9sIòàCÞ‚-õQŸÊU2‘Q;GƒJ÷˜ÝŠ­TeM)ƒ…XXås"çtL—7!hÈ:¬cRâ>qˆ£¹GuZJ‚뱞Oû̯7LÅ«l ü"À^•}+R‹€e…aµ9ó®.ˆ ¸òàJhРZAâ.ë¨}MôüÈ_…çb®ôp¦ö¥z½‹wÝ«?esYr¸{ A4¢)rmœ ŽáÚâ3k#0âC|(1Ánèö>°t4UŽØ[  4¸Öǯ÷mîëdFÀ&Â"Ñ áˆ ½#Ò ‰ åú—óÍï»þŒ£öú…[ƒ1˜Y4Ù…]®•o”íoã퉘èÂ2X -î’()þÜàÅ#O³ÅKÍá}¼ÿ>9çIôªEò~7ìUc±¥R߈5XÙáaf`FÅøŠÞ5¼}Ûú>{flž¼Ö¹|ãS[2p.S1µÊ¥‚%]6Òñ玚ÍÈ­vŽnM«¼;º#¸zˆ|v&'q2!îµùW”Y…"±S¯ÅZÖgž¬Ÿ¶–'x’y~ů"çŒÁ˜vh'1ÁC8D™li«¾T¦ÊN‰9æágSè*±ÙžeózÇË·½ob¢±\z¼Cku¸È´ž8Ä…#üo(q“qç39v²W¤WÛ¹mí’Úyœg3¤(‚! \473E6¹V ”™EQT¢ì ¬È‰œõPOÞØŸø3¡">Oñ4ÒWÛÂ(‘pßMêÙ’ÆÆe³dÒóIž5=}Ûø&%™öé¼mnklÅB›èSwRºNÌÅŸÜ>e¿,û2Iþz[ê-MÑ”ª µÅî`Èö^ÕS @­(*¢¢Èú)#âÏ矙¿ÀO¬o”?à‡Â(,²7Í „ASc×På-me‹€k ¨Dltˆ%wÞñ,íéÓÖÇTƒ%ó“÷±ô•{ЭXNøe¡ÐuSì¦)¨b¹–nÿP) òƒÈÇ/¬µz§›¡Y4¢§`ŠŒvíd.ã2+€øÖHŠB°ê’+¸Òm¢µ ˬº}P#4¢|¶tmÿ,È"}â’5Ï·4b:vWôð€žÞ­¼)cÍ X$ËÕ¼º=uA‹ëæu¿ÄëV£ `[2vÂÎ8St»¨÷<.{óìAU‚®=2ß"Ì\‚8áÿß»Êa@Ô¬(µÜeé7+m!’±ô 1TJ¢áÜ‘~ÕöA";£}ˆ­r)ÿßÒÀ1{(¨²Tbm ÁýìÙ3O­§‡Öc퓵"§Q!Èš¼ykË7¿œ¼€¢X„E%PBê²DbRbñÞÅÓOwàºÅ¨Ë”¨c1–Òµz)vdÀ”ZµQ[ú¦.gfÉÛQñ^ ÅPj’+±RúUë±^DùÜýÅPLzj/ñ²ŠXr{pëÉ/#Ä’t£Òy7ð.ˆ‚)βÃÌfÀŠrÐxŽçÙ-ÅÐî*µÇÔöÎá½ò¨ùVÉÊ°K³"+•÷š£7ä*®† Ä]"­±G EèIœ”wùAÌü-ÑRz ¯¾èûÞ±ÔðßÂ[;±Sz(…Øô,íøãïï®#6Nu¥Ÿž^“GSÿz}SËúHò–¬AonÀjÊU>=ÙÙ;€ïð]34su)܃îó»kÂ4SbŒ_ý!ªŠª´@SAWµ  €bãx1ãßÇû²/†g´8¢½’v/M@B%Tš¬Û÷Þ 30ÃÚÂtB'Kþ·n:b`ãn³ãVŒóŒðÜqf‡Z£Þ‡r5*y[@ag@Kjþ3à@9Û!ÜÇ}jî«w9ŸqÛÇi"4ý–ÿ/¾Çœ&¶¦cºÈ¼³{Á;êþ®.…$ØÐv°´?©DþÀ¹‘»:H‰ó|WÂö'þ4=D™@É`UÈt6ÀDP£6{ÔUY[”Ø™fjB4óþšÇêgÚõèVRÿ‡éh@.]{DIÝظ‚Æ=û OOôtu)Dÿß97‡ås[ìåÕeA—ÁjƹÑÄ–îàN$"-5|¥1S[ …‰<ÅÓŽè˜y¤X"³0«J˜1芮R¶¡1d>æ35³Ë~ÝN•õöy-Û_ëÆšlš¡Ë† C@¦ŠŸ‡èW$k¶™tÖ„‚ü¼/àïEõ×2â$%ÙD„Ùf{x„ w¯€*ÒY‰•ÅPÌ-4sÚûT,íNg–Q«œ‚)âS-<úÞ3ëàzG è:j+`j•Pi.æš=ê^¼mñ×òiè“î›tHŽSuÍ$.úU™Ð8ú߸ºÊâ/ ›.N©EØ¢©ü³%~sùŸ¼>õÆÔs^áœKS4Ñ®.…$`€½–Ï\Á•·ñ6E¨xä®ë¸Î:`¶‡-…RÖËÂ!–&¿Ü%ˆìEÏŸ?÷ÌìÉ?!AY”5Ò¨ë2|*‰»XÚ‘\ÆeVåûÆ;“3@$ÄÜÓ—cyähö®m»¯îö-ìûÁ7#)¹5×pfŽÄh'®å&nj¡½…[vIí9ž‚OŠ£¸øÚÛq×MŸ€ ƒÊÒíZ˜¨q?.Ÿ—ò”ØÁ3{×ð>ŸÀ 61)Óô26^§(qÚ¾zŒÀW—BA\Jög¶2¯“.^–n{ˆÝØmøû¡Û‡¼‹xwšbqïQ·f"&VA·pœî…^Ôfí˜àtL_tð/ò!ß|ÝšÎ7 r€k‡è©‡ ä".š=ª|UV¶;sûL¯¯Eÿ,¾öE_aÁ«ÉΖ=µ„GrO·ªZzKi+g¨¢°þ¸“¼ã ¾’û_ý8sd¸:PõÍŽì1üë•<ó%Û_Ë·‹oëAÿ«,ÅRaçe>‚0ü· .f¾=’Ýe”S^‡s7¨ÄÞÇ}WD)¬ÓyãHbRr¿iv-冓(fûþÖמ%S"+ë…à¹j¯QY=÷p¯:ª·Fk³‘¨9S>F—!HÆ:Ž%XRV8Ê ŠUee/:¶>¼wï¿Íwô[Ûç|SçÑë´†äõ¦‚³ø_¸‹‡¹BøI§ù£f²O—ÖrHŸU'Vi²h¾Úø•3Ëæh»åA·ØC³:Yš9²Ú°á£Ú¨mV3™ŒÉ5tIÞ 2*¯…X<³P[.…R«±ÚìQeª²ò”Øéû¦{F¼±qÌC<Ô;àžÔ…ZŸMet*ìvƒl)®…Š@®7¿„Î]o³ ÖÙûgkB5sÿ´8‚ç¦lÇö„HYåZÎàLfd~„GvO™Ò¯=ÚAÁ¥Äê·EQÔhö;|÷1>–‘ÑFldjf'Ö¨ÊÆÄ@ÆN7oÞÔdÓ|»æqþ¹˜kè!⩵ZW!•ËXŒmƒ6®.…Ò1šÅ=d09'æw‹ùvý·šHÍÒcKR2×AÛ§ º¸º)ÓÍÀŽH™bvFäC¾Ëº!ü7`”9 } hö†!LÞ¦UQu!š=¤4U6]`B†ØÚÖ^åû¯ÿã¨-õPOdzQß$ÿ"`yS P …}i¶ ý€›Þh/MÂø,L7ˆ‚ùå¦=çöôŠöÚwÅ=¢WIäžeA£.;}ØGqç8³É˜œ¹MÅ,e»‘3$‹q‡ed±»ó ÙEvŠReYOßWÖîN5%fŠg¨ç“'oxæÓôÈ„L"“D‚ŒÝÉ's¡"Ãìy[·ŽŠ1—p©j  aú8ÞX¨³ÿ=µ À»@ ÝÚ]èÏH Î{MúÈ·ï黧]rg²Kh,+my”_ ÚS15r]z3j)¿9¸vEWÙ åê£þ ÝÊ{3(ÇW–% E¨UÛÀ]ºtÉ3ÌsjìT£ßYµ¨ÇŠå•u}Ò}ÎôwŠ¦ŸtsË–óJ"Pò0,ùÿ†!L|vZƒ]ðp D¤é–%g’w½Ld„ñÎ|‡“7kÓï/¸Wçsn.ñׯ v.Þ,üe¢Ò?éœÇù`_2x^A°¯Ì‡|"K´ìÂDL̆l†ƒqˆc]Ò ÞÇxœée·¸ha)œˆFee,ìÒ„xÆÇw|_Mâ[ÿP·ÙfuMoô6u–NË°E4GówðŽ /‹+ÉëÂÌOKð"ñEh­Ðb‹QÞÊ+¤-7PRs1·šù®ÏžÌüÜÈmf&f~€ÿâWTB¥Íb†Ä8†c”<ÊTeï⮵!¶®_¿îjf”É»«¿…·ìW:×ð/ù¾¨Êºº Já.äAö;'Gr™üò·9gSn=¾å_Ô¿þ°úÖ–P±P1£«ðýhXáiËïÇ~GgDm¶ ÝÃ=}¾|8Gt›¢è`$}OpSꢮ¥ Ù];*ë¯÷Õ¯ ǯ‹Ÿ_ó;ÀŒÃ¸Ïñ¹=ÊåJÖ`MUTuu)”Âlˆ@•é—ø› V ±šï½´×+»Wÿ©gÝÇ,(òVMv8ª”òvT´JѲ(«aÇ|õáO÷`OE]Ì™lÇvêÉfÕ__Wª²”ðâAÉŒ˜ûç\O­çÍ›7Í­Úèæ@Ü›h1û¿y›4ÍÌ¡€Ýúƶ)ÓÆã,Ví/¼øØbMͪ«¬ÊT±$!©JYòáT H JéOEö5]Ñ•‚‚9âÿUhÁŽ~™É–m2J£´% W©²Öîëý×_i²j†.jöès<×BëîóDð(AÒ7ßL­P2tFçüÈo)‚œדýf%ïÈö,ÙO¯ŒåEµf½a´wnï“wen¢ª4¨¡E"Ò+ªìÈxŒo€NȈª&ufý®¹˜«÷((‡rVmVkÄ2,cwfö«TYkGb=<3,±8®¶[LW"»4ŠÕgŸâ)B}Ô—þîhr¤J_ÀGª=å8]¦ÔQ+ ZÀƒøTÒÙµGû>èãêRˆAû=ÑFV‚¬,ÊN…nNç^ÑÆz£÷(Œ’,ƒ<ȳͤºóUYJu­-há? )cENø_(ß0EÞÁ;«J¬TyÜÁÖª® 7ýúõëìïgÏÙ*§ð5>>~ÆŒF ^܈۸ŠÐãŠ^ר›“’7@7q3+² ¢õ'ü$86,Â"‡…§cº%ÿ|ç;xû¾Î¤Û™P*¾í|»‹ùɆyH· Ç9ƒ3„AQѾº®OêŸ?ük£ö4Ls‹ð¡–8óùoƹº :î?½Ÿ©l¦w½3iÒ¤èèèV­Z¹¯Œ…n´dkˆ’'¿ãq‚L—¾:ˆý؆0ö;/ñ2;²óë?ø'«n‡ ùû´*a‹„ßñ»‡ÏKéCÜ™´™<ƒ<<°h¸ñÖ(±•¿rP€õüŽýˆ; Ã[xË>‚œô‚W"(c·`‹µË4µ¨Ó$ä+f"µP«/úÎÇ|_JnV†°>„#|1»º ÿqôúQOÏe üù§’^K‚­£ üfq‹E@kõÖiÙQqÍÔi§bj4¡±€Óh]V!Ô™ë<µ2i¥nêãà)>rË£–âå*‡xð3~nÖ”$Qð|23©{¿ÀÿŽ•DI»Äñ *K#h,ƶB+vÐ!aý¡ã4 A»°‹JÅﺸÊbúîéš0MÌYóïÝ‹µX›yõõM\ÅUVWgNÏ f£°ì‹zl Ô°V"TbÙÀÍ>d§ ð1Z¥3{zdŠMaTò¤‡™ðÛŠ€½$Í´j¨ˆÀ¦hú~2» ñ\¡þ)/Àš87pc!¶A›`Fá~è·;ÌŠwìxï¶Lé:”6SÚ¤/šþÎC±õƒîÂûx_áÓÑ‘ÍÙiÙ±ÅÕC=¶Ž‘ɬG`„íK,¢¡%g9ç øiŸñOâÉTb=R.VK´‰gèîãþø±*ª!ˆ&üz¬7ÿ'crgtvh‘‘¸{‡cxi”E(i%ÄN\‰•Yå ùЃJ!k›¬¹šš. s?Îà µ,%ûqQ™d‡ëL'L6ÕB(DEˆMu+¶VB%¤ÎPÌrŽ*KI.}Õ¹g gŠJ,tÑï ê×Ĺœ8Ñ]3#3;Ç5X#q« Ú¨½N·]•“¸ŒËÔgò#?ÝhŒ6«Z;9˜CíälâæLn>»é_Ö¿áĆ®.ˆèþ ßÀ¨š9(v·%Nã4»ž’(¹Kü#[Ík¼Î‡|Gu.„fp´*ƒéët±_DýµØåñ± 7\ì6l£¨¤Ð ÝaÕÈ9oÁU (öa_wtAHÔYŽåÎCñY‘õŒ.n–°ùòfMÍo'=g$ªm|ÝJˆq‡ØˆìÞ¢c€ äUÕÉŒFØ'`B.ä¢x÷ºðZŒ‰˜HEËì!Ï”EšMX5ÛE%Ölì#(·] †Òu!C1ª…?ãguc=ÖSÄ9¢l¡²ý~ªˆŠÑˆþ_Û}ÃPSX Y¥•ÜÒMºn¨o!ßËO”;u(Z.26¼v&ÕPm>æÛ1Á˜ä8ÃúåØä]ª IBÛ`&d²‹Œ}ˆ‡TŒõ qôpt=Y¢‹ä€9ýÐO~™lc/öV@J§MØ${ƪ'zR©³oÁäñ'þ숎™‘ù|â8 “7KcÊU¶P¬g±È&‘IIöŸšt&ñˆÏ†l¦‘x•Ã¬)Žâ¶§³ ø9ùC´ÉöÓ¦¢èn#Ø.2–´E[K“DŽ.°*T¬D%É]å› å’É9œk„F9‘óWüjcR8é¢ø+š“Ã1< aíÑÞî‹Fbd!rÓµqñq銦k:¬©« b+¿à—r(§Xßi!v÷.ì²1 øß6]=`ìxdVÎÅ"Ö^2v'vò ›=ä8UVú~Ý üáoK´<Æã/ñ%Eõ1Û½ i/Sot„×–<Àƒ¯ð{vÞ¬½F`@ ”£®p6œÞ  ÕüëÞ³”®¥QÚ¾ö¸}™„I†ÛÁÈC/D®!c°7Íÿ>…So¬š,àá¡5³”21æw„3Ÿpä±´~Ùë¬r‹•èN `¯~G"ë±> QTðì%vfc¶a?+:``ŠP>Ð(“èÂí|®àJ0‚Í®˜0ª‚¬3;y-Y®z$Ì~©þ”º4=<žâ“a¦,as4·4%Tõ³æKç+-Ažéè+uÙþc<¶ÝgXœ§xÚ Ýò #VEÅÑ‚(h÷dÊ/ø…óS|ú¥œ¿ r#·U^¸³OÏÖD¸}(ƒZ¨5]] ‹´A}6a@¯@Ú%¸‡Y[5¥¬CÜ,Ì*Š¢eQÖt¹â ¬`:æs±«Œõðy)Ñ-6CL† R6¸û¶‡|çoüMØ Í(Ì‘þlÌŽHÙ¡Pµè‘ˆäó?s;¶Sÿÿÿ8§`N¦ê÷Uƒ*¹µ+Å‚“×®Z`4¢¿Ä—­†ƒò õ•éÿ—!èÿ“wÕ4„2ÖGëã¯õÏ׿ÆëŸð«z_ô5œög¹ 3C÷öÝÁAJ,¡€M±™Ë†)‡!Ì¡s¯]ÐŪ Åì)µQûŠn‡m3Póç´j6Ö½ˆOŠªÔô[÷våjŠ¦ ‰Ù+pçz¢gz¤×Çü¬‹º6†„Α0aò­!ÌtÖQ•íŽîŸàéYÜý†hH…Ö°E´DËYº½Ì`GUVbRÖ*±HvÜr„†ù/?ÃgùÏÑ¡ã‹£¸¥uÍnÁ+¼Žá!1¶£Žpgap {.íÑ?¼äÆýÈ)œ¢*k߉k‰Gü^쥨¯„Jì—‡`ˆÞÁovC1]yÙ`q/Rã¯IH¢ŒÝ‡}Y‘•¶˜ôŒXÎoðM(B·`‹ðËoø­j™Ï×N2Vº×–G ‡UJ,3áÅ×ÍgB ÙÑ቞â);kw -.Â!*Š¢­ÑZ?BK­#rYÚ¦3•Ñv~[í;ÚW‰ i-mÑ–’ÁU¹ÓÒÉŒÌoãm*6ë±ÞÔ¬$J®ÅZ[²ˆÖy¶˜ç*Œgt©â¯õçßj¬Î‹¼Ö6RÞ»-!":;¯LÈdÖeÑ^ßD)Á ¥/ž5Äî2ö>îWA•®èê„ý¤bËÊãè\œÃs<çCËÛ°Ÿ+¢¢ Û¬“¡êT5¨É·M\]ùœÇygÆ<¤ùÃzÒ}Ù5ÓÒB+>µ‹«¢ª-9š®óx­‹Xkì&H•ƒ8HU–/·>êO°~ãÍ“8‰È_ð ?7FãÙ”h»,Fèµ%}ñì‰ÛUÆ^ÇõÂ(Ü=œ³Æp ¦¸ã„—¿ãwÖ«‚(Øm\]§²ãÂM¤fû)+ŒJ¥Áª8#šeø",jª¥Pj8†Áš<)ê3T#£u§eg-8q9g_Þ….žÔý7×KM€fzÌôS8†°ûÆg¥Ì1c±'cò|̯Úfϱ}¸@â@<%v•±ìò Ï÷øÞ^ ¦Hgtž„INËÎ9|ŒƒL[À½bjÙN»ßÚ– |•ä®#|_”$²÷[ZëflþR´6DÃy˜'#ZÅ(Œ²qûr#Uv Ý2ÓQ½TiÛÚ/к£{oô–‘)Ÿ*Åì¯ø5=Ò›•Ò¶/F¸ë<%ö“±çpŽv&fÚ%5‰TGuýÀxê€]•Xª+_ãkÚž.‰Õã*¨Œe~/s“ n€öJÊç*¬¢"ÁšP¥iµÙ²Œún± è’m–kñc=’cZáÕK•8 ¬9½‹»¡½€ 2ò=ŒÃ|åPÎRð(UY)ßÿ½U‹gßHß2ö$NfEÖé˜n{RVAqt'œœ©ã De+8‹³ÂWÖÏ,È’vFeIì­XM¸f÷™Ý®.ˆL®àJfd¾¶$ò¯÷c7tcexïŒÇx{­ï£‰äœê¤—*¼Š¦S8ÅÏc0¦%ZÊKp)–R‡o…Væ³³A†é $ìzê™QfppÛeìiœ¦(pɞȔ1È£LøÙÑo{s!ø%\*ƒ2ÑQ±GìÎG3?Ê\9sB¢î~?>zôhW—È:z¢'Å£¼k)‹¨çDμÈKCFžÖ'Âq§Bè„ {†RÅOë—N›ÉîFÔÄá¼4Ù üáov¢Çï)qqqž“wN–—…2–B ²-ÐEâq6ì€ütaRqˆc³2k<ÇóðAuT·Ý‡Ü-x•ø*}©ô•{T~ï½÷ÂÂÂf̘áêYÇu\g×oiQ‰Yžâé",¢ÊJ]¥?ú;4rÔq€ž¡TÙŒÍz+{æñ6å¥ù/|á;#Ìç(WŒI(è9¡§‡—|9i‹Œe«Ï‡|®šuêŠÝ¯Ü*„Ý“Eî…}÷ Ê…\©/dY¦mŸÆ*Ýï«~Ož¸Ò«_6Ÿá³îèžâiÔëVb%íß ±,Çr'xzoÁ–üÈïè`ˆR…7E+Œ'"± mK!j—E¨ldB¦›ºàµ&9Êc= <3yv-ÏkÙ2öž•Fé¯ð•ì¬m„J¬ôýy• ŸaeTN±}QÕ‰@„lS˽¨:¬j¶Ù\] ™°ZR•™ú¿€ ýÐ/!µQ{.æš]Œï8Š£¸£IïïÑ1ÿóù ¿YÚ×;EXìÜÈm6¾JHb¬_)HÅFJÀXÙ³]ÿ»\–Œe?ØMZ¢¥ ÷Úprhq±K£e¶k6e Ö„!L¶àFÜ‹¿çßûÇ­?ºº 2é†n¦®Jqˆ£±\U(]¿Àvn•Ëàè FÚf‡å4¾šcÇt;ÔSb¼…·6`ƒŒd©×Qç/ˆ‚K°ÄèPl¬nTÖêrjãµ)¨ô²ÝbÿËE–¤ê‹¾UQÕömbl!ÈØÃ8Œ`«TÓÄ„#œ6¦ãJ¥†ìâ—×ïéó§®.ˆ.ã²ZaB–Rev|„(¨™ðݹ¶á<ÇóP„:tËx£¶yøùaª‚Ù³goÚ´éñãÇ©*Ж—ò»xwÆQ›5–¡lJ(ëû_.ÖK*Z7…QؾÖÒqBØ[GØ9M{ä9Š£T}]2ÏèL(šBÞ ©7¼ž« "“èÐýGaT^ä-†bS0ÅßTû2>ŧŽKßHª\'^ž˜6mÚ÷ßëÖ(•@ y¾ßßá»Ïñy#4š ãY~ke¬Ä Ü6Àzûþ‰Dä%\²1_qtØ[GÃZ×e;ùœÅÙÈ1 Óì[*¥±ùòfM°f×q[7Wu2IHÚˆµPK _ñqu‰Œ¹†kTª·1œ©TñÕú¦×¦×ý¿VA)ÄAÊç8A)d³×Ú!Ù@¦(>m(€•2öEÑßñ»™ÚŽCÃÞ: ˜À'i‹§"­Ñ|È7ÃíX*Rel•°Êa®.…T.ââ0 ËŽì”30ƒµÔù s$ÒmFÃ!¾ÇfmÌù˜o¨&"1rÉŒÌ Ù;ÜÅÝÖh=c ÅÆ" ÀŠ¤<´q)Æ“±} ÖÈXª^ÍÐL!±JöÖ9ü‰?ƒlûÖ7pãm¼=ƒíR*eòàå¿2~èꂤÀ.ìbëAˆ¡âÊ47”{ó/üèW°t³6&ë*e¬¡Ï­°º¨+#ý†h¸KiÊeA–§xc¸^£±t‘RTbcbb<ì0é#]ƲG.Ò ÙSÃ}'¼X+ò#ÿb,¶Kjð€úðøÂ.©)“ÉG&{E{Ý|,ÉõÂÉÜÆmjƒEP¤ MÁSÃDðÎrIÙR¤2*;by¦%“2Ö0œþs<G¸ Mc<ÆwA$«â?à‡7³°"OΘ!C¬u[˜ÏHš°º„Ka;‡s¶çhÜWÆ~ŒùgÇïáÅìçº]CS-¹Úå*ý¹Ì™hA•m<]Ñu/öZ:m'væFnG¨‹¶CmÐÆ ²f±dcúiý ‡dÉp —1%A œÿ?7d¨ÊJÁ%e‹‚]¶•”btÓØa—§¨îØMe,û÷(`dàØÎ-Ü*†b©8z̉Û'4¡šMÇ]…ì žÌÆìâ(ž9¿Å·R›Ë£¼½Ìûb{PY³Xj›Ô™æèïàNBh‹Y•~’2#³0íNÙh»@©[ÆHØ…Öv)“GýÑßÒ~:®Âe,+s0‚´FkäI}ÑtõÔüºfDÍàõ@¾Á&h² »¤¯¾YŽåePÆ¡e“íAeqª¼‚+¦R‹V¿Œ-ꣾ0ʱëj †á!‰Û"8Ç£@ E'(*ÕTÈeÄv(n'c_àU͉˜è¸,سgGö9·]roîÆßõÎí=¿÷86Ës<Ÿ‡yåP.r ÅP«‚½$"‘Jïn(1`#- Dðí• ¸<¡Œ5 mô7þ.„BÖæ2 þėH~¶Ùí²nC})_.%L]< ÄùiMFa~òŽÆíd,«D4pôÒã38CëoV84WÑcM ÊANËî&n²-‡#¼ê­Æj[â¨PUkŽæv,›¡ZnÇõ,âv±O€Ï˜˜1F?²ÿ²¶Zƒ5úø]C0„úCR¼diHŒµªH)¤fY^Á˜wu;ö(÷’±±ˆ¥èÓïÅìPŽá5“}Ø焼œ •ÿþCWutFû±ÿ#|”™?ŧvYsú´Ð*só µX+;H‹)âó;Å~$l=c-¯öhoU.7p#‚Ærhhëä¤xɦ¦ yFÌ2–U‚ÕL9¾†¸‘Œe•Ë…\à§å¸[Xë”ùâldÔÖQ~ùýž=wˆaæc~)”ʇ|?âGû.}íƒ>}·oUì¹²"«½£‰7ÌeXf*»žà µkQiÑïRÕ m·”uÔ”6>È“!C€¼¶þËÑÂc¡uc)"®Ëq#Ûíë¬%…Y˜•y·XÒ…hkk?øöû¦ywGb$;¦Ú¨½1¤s©Ê*sáÌ7ø¦:Ø%)ñ†É‡`V?|ïÇx«2jŒÆzoŸðSÐJqÚ+e!èk¯­ÿ4÷X¨-ç@;†Ûw‘±»±;ÑÖz§ØjM•QÙµ!žÁü#ó½Â½®?²Ï$ìiœö{í‚.ÇqÜ.iZ¢š9tÒS6wp'A¶o´!%ReìUã-Äuã«4¬ÊkFéí¶/–_ïi»kߘBIBRI”TàT—·±ì¡  ëKrçKü(dí³}ÉÙ%gÅþmIšêvlo€a‡qÎÙ.±¹‹¶¹ò²šZÃtûxÛÄB,l‚¶¦ø2m/ñ’/ª5_«±šF‡þ+_¥^^‰¯DHqõÁŠ«+<üì,^L§©{WDEÆßN·±¬´õQß… [¬µÂ”϶+Û4!šü+ãÚ$,À‚‚(X…çbî8u;jkÊôú O)gãvŠ°)*fú-èÞCaÅl朡¡­ÿ:ó 7½‘¢žÚÞ>b’Í·‡o³ͤ—D F.ml˜Qˆ:ˆƒöÍž(_ÆÅÑP„ššENæ:®G#Z ¡ÒìK¹þåÊ*oÕ%´ˆ¿Å·|µPk'vºD…`[«ŒÊÎÏW T Æϲ/§~Œà' §cºYKüŽäG~éÙQõõƒŸ~0“/—ÍMo#ˆ ɦ<’àçqíš7±zŒÇлÿñ!(Ó_Kòt³Ÿ*‰’NØT 4QÃ~]]{ræÞÏ@ÏcWI9ùÎ}‚O(:¢ã1HºÄAËWQ–¬ÂªJ¨$ûò8 e9Ûê{«)c4£ÂåE^à1)B™lø6™»ÞeQD:Ù3VïNX+Á:@ \™kRô(?@÷ ª‚*Êlù¿Gq…ÄL³¥;–.Ö¥˜È ÔjÖc= Xj8|#NÞšÐ_ãk |W— lûˆ¾€÷5)‡ ¼…[baaacÇŽMJzÃI•ïˆÒslŒÆË°Lÿu(†þ{×EÕµw7„$›BÐ{ïEªt¤ƒ"M@‘&UDiz•"]ADHD)"EB/i@B õýÏìâ²ìÎÎÎìN[ÿï5O˜¹s2;÷½çœ{ŠÉ¥ì0ÇŠ˜Bkh`ìÄGÆB#4’â"BåºOã4©L’öKr=У3:«‡öÇÙkgI•=vû˜õGÈX‚%…P¨ªÑ/¢áqD2!Q•H&Åqô çF=ÔÛý|ÎdôØ[¿7lØpÒ¤IæÇI‰Cÿ;~ˆÍËŒÆáê¨nüÝV¶—Ý,ZSh-0ƒgbfrHý¥œ—¤Psn"1zÙæažÒ‚X"éQÑ…ö¿î0m§àËøÞ™Ÿ@°ͯ5ªVñ÷‹›IEêlÌŽFts4?•6©é‚.˱\i)X@„ Çx,ôBº$Ö} YAû-¾¥_,ôXÌÿ8Áó¦K±Ôð1÷lœÁ‰9À±Ò9c ÌUr‚Ô¹çuçiUu>!Qjd!‹,¬é˜®´ ìð‹¾,z&.ñʱÇÌWìÅX\ ¥ÈòZ‡uW(Ú½¨²:çxžùŒÅüÕÒ;A@Eˆïñ½Ð _ŽŽáüæ–Fi ÿm0‚¶ ;ÇrfÑJç(€aK. aü=*ÊB±[-Тƒ›jq—ƒ¤Îú‡¦·œÖª1@8ãvc"ã#ðR\âØwñî^ì5þódÒImˆö¯{É/­3 ƒâ| ´,HAJ ùë¥=ÑSh6K@ÿZ‹á[„×ñú&l‚¡G­EhÝ I9¶ºMÁZÔ¹Ycæ ì®"(Âs_U XÕqˆSa‘ÿ¿ñÏ™Z¸LÁ2A§å.×RmBµjãTº‹d dØÒŒSggð¾èËS™$Bö‡ÿmÜ4>›‘e^à…Ã0l¦™ñ£0 l¡vKsKDZƪ;ñ°*ªÅQ‰î".Tµíõ ψ¯~ÀJ " ÑQ…Áð †0-úv=RÀ›øW[åÄ_wÿ҅ꮈƒÍÑ<±¦æ’?3: {¤>ë׿úðj·‚nOs\)Pö8ŽAu†+¿÷9lvRÉ¢åX ™Ñ £=<9Nh†f|<Õ¤ —C9‹ƒ0Á¸í%ÈW Ç>Ã3‹ úÆ ¢ :¿qs¨„cIƒí‡~JKá,È–)Š¢JÅðÓTÝŠ­ÕQ½0 ¯Íc3º0•6Y›a%¡-Cl …œÒ41>žOùAüÉá ØŽígÿ‰?¹9m:¦›2¶8p— ¡ÅÁmØft ¨c7cs=Ô³8XeÔ ÕpC {WÃÆ?ŒPÍèƒ>C˜YA&á7ø†è½*mÄƬÉ/á öFh3˜ÌtvLÿiºOM>âêÁ",r`k^ÔAZY?"êX…UŽ Kß57§ý†ßJ1q%vp÷ƒlqð:®slÍ›Î0Á±¶ý±ÒeÑvDGë QÓ0mÔ® ¨c{¡×§øTi)ÄÑc [½±á ÙȵP‹cA·þŽŸ0E™¹gË@ÍÍÍõŒõœþ«J³ØX‘Œd_øªsÛ”X”µ_ÒQ͇|΄ss,‘p^äµë…KGz¬£ú‰x-HL.YîàX‰²hS‘J߬õ_A«@Bœìì#5çØD$’¥òyAXõ2T {†g ±° 4Fc»µM‘ZO ¾Ù|@Øqj¼9ëÍÐv¡œ§¨ÐÉù–…Rà)ž!ȺeR34s²N¦]Û¼ñé‘Tå/à‚ÅAR¿%L7᎕ÈQ°[leÓ\Š¥RÜT,(αÝÐís|®¬ â"¹õQ_ºÊ·Ä®³0‹”Ÿ×ñ:Ïnqw ‘Z~†|„ZLü6ø¤Ë>xò@¤ûîÌwöOU va—j+2‘U; ¯Ó6*±Î¨a< Z;xk‘Ñã1ÞîP]Ñ•¨ÌâàÛxÛèÇxɱJ8cû£¿­Â »±Ûz·NUP¶ôÖiœŽB”kzâƒ38#EYzPÄ®ôÄZ£µ<­¬j­×]@E}ÅAæCaV¶×˜-œÀ‰hD›8ô=:PcÖDkÁÁÁ‡ÛtO}‡ïø¸©?Ãgôcqð|2aαJTƒ‰AÌiYà¤ÒEQAõÍd†ué­xÄ @Ãê¯ÅZçÇ4ÒÚÅ‹Ÿ={fëVW°.àBy”·8HT`XA_ÁWøŠ;;‰,q=ô×_ÔKV²µ››¢©ZøOŠbÛÒ £0Š¾Óh±[9(”ÖôÕXíüU Z¿è¥u8ü) iS0…è¢#:*hü®=¾Ö½ˆ{fŽ+-…5Pcv)- Œ÷Äfû±?q¢,|h­ìÆnîsH/XÖHBYâàDZ›on–¢ÌëxÝî·9ƒé*A.r7aS1«‰šd ò)ú¢Oü°kh¥CØHŒ´.¡ø(àB5 =ç:¨ãÀ:Bëò§ø”ì;²ÝÔÐQË·‚ïøìoš¨ ±PµÆãTL%›±ª­a©áøpì šÁDCÛÊjœÞa#ñòáXÏAží‰üØII @@*R¹O£e+Á4©”û°¯ ªTB%SFŒ¤¡Wqu4F‡"””1óBëÍÐì¿ê‰5Ça.ˆ‚ü—cÌé®ÝÑÝ–“_~ôþºwhW âzˆ‡y‘W­4H*²ò*¢¢XI |8vñÙ`¥ãA>{^RTƒI@‚E?G[è„NŸàqï.—q¹1“æÿ-¾5ÿ~eߢehæD#ºZÇqcj!ñ‰Ô÷UÚ¢-ŸâöÉHž„IôXÚ zØÕˆ©LW|’uÏpõ‚Ötu–ˆyŽç~ð‡qb ȇc‰©*£²ý¡ls¬§ç‹T/Ž»Iገ‰dó9ó,ÎÒâ¥`µü¥XJf;u¢¥l!²ôv‘‘ˆ,"¾c*Ç9œ£'ÏQvï>îÇxRõû¢¯c…Ad@…j|«JžJ°;ùäÊɘ\5M;_΃³‘bï _»š3+øÃ?ÞÐRÃx™9¶êñw­“õÇ¿…™ˆHAJt(òÄó¬'Èœ†ˆDø¥,ÄBunþŠŽ÷ñ>kÙÃGxDËt0‚û¡ŸÝm_eñýŸßëòëžf»L$3é!ù‹W²…|¸Š«ôu_ÁãΗ(còd6Òmìv–d¥Ò=™ä8ö)žæAþ^Vz¼D,¤´ˆ+7Nâdâ†b(‡KPæ4„á>CþÄŸµQ»*Éí©H‹G¸¹€^›©˜JïÃÛx[=U­á_ÝÿÃí*-…¼‹wÕf.µAcª—qçK”1y2ÛkxmÓ”˜s(ê–É%Ë]FtŽ%ýÙT”›'>ÀreÚ†md¥Z´›´†œÀ‘lFV!ËeVE!j:¦ÿçÚ¹˜ûÞ€á ÐßKìÚ]ŒEæ]ï®x7¤eˆÒRÀ/ø¥0 +-ÅKlÆf’Ǹ AdE6¸(Ž<™­?úÏÁ;Cqr¬‡‡‚0¢sìl̶è2f÷pì²Ä•„‹°(1|2.åì¾ Û¡ù‘Û¸ÝI§å.ïêxŽçù Rh‰]UëwåÀçuAºƒ—íÔŸQrCÏ\%†°ˆ Ú7!ÅrÖ9?2Of³Éz¬¼ääØžè¹ „^5Sd 4¢ÍhDó4Båì^e­«(Ó\˜†iô~ÏtDù" Y‹±8¤´»–îj2}ÊÔUKi)€,ÇL9åA «…O~5V7ƒ }x2ÛøÁîF›]ŽÕÄ×±èî€$üQåŽàˆÐ«HŸ)‚"’ö0ÝÄW¶v¸X!϶×!âè’€„(03ÔßCӞǭ<¼<ò&åå) ,Çrë:`üqWƒ$Èœ· Òýˆöù¤YC†m¯É˜LäÉóäÏðYQUyÈ(+öa_C4,‚"k°†ÕD‰™¢xá”ÂÅä‹Úí?.Ó|lºXÄ*u÷¹˜[e9ŒÖh°ë¹Žý _qÄ5ÄI[­_걜^â¶/Öõla6f“iuå0: ³ñ³?ü¥s[ÑŸ…(úù_B/gâTX¯ÌŽâh}Ô/†b´þr|­4ÝHu!FNÙÄEÈk!ƒv RZ (ˆ‚Š.;‡sÁæV¥6bãkxÍá[\¿~È-7—×Ì=‚#5`3Yo)–Ú <àɱ|dàRE¬û2Brê ÎTLEš×•P‰ m‡G B“.zj36×DM¡WÍB!õ‡9ÑÚÑm¢½ ËøúNÂ$»Q4jÆ€%ºÚÙ=Q†a˜E“‚”â(N¯÷iÈE¨Ãy(ž="r›2e Ÿ“é^D0À–´|ü±¢sl bœO…»ˆ‹A:ƒ3NŽsWI5r’‹H“®_Cc4v¬’Ñl$"ÕÙi†o°ÚÑË°‹ø{Õîã~Â’‘,©lÒáŸä´zíµ§®‘žC@ i rÞ‘4(RÃú3})íc9¼;Cs–È­@;wòڅሠ"³ÚV!M>þXq9ÖP*JjÒÌ)òÎ8½éÛ¬‹ºv38ì‚Þ" 'a­Ñd19¬cÓÚ‹Ø$ˆ\3ÍICŽÀZ"'c²!"4­ø´±S-ò·ÌÿÎúw”–‚/hŽ"§{ŸÞŠz¨Ç³ÇÙAQˆr¬!È'ø„Èíøñã½{óòrp,qš-—ü¾‚£8jÝ”Á1ä"·Z8SÁ{!6@ç]©+°¢z89+è5è‡~ÎŒ0óŠ ˆJòúá±+­ïã}‡ƒŒëÎC<W6Ù0lí°ÐÖ®TQö¼ã@Æcø¿@ `[°êlÀîå®wÏ«°›ÏÁ±v?’“c×a]'tk4²ó#ÿA8’¢˜‚”DˆâÏÿ ›Jˆ "ÒBûëÌ13‹¡˜²¤DúêL!3 ::N+ÚÇøXÁäÇýÔûÚ@핇rd…‹‚ØÑMd¸ÑyœD¤Ðöoñ-é½ÜŽ˜M…è*û%¾«fŽ{±· :@ ã0ÎIÑ2üà'zY°_ñk!%ba4DC#1øƒnºKH9é‚.b5.¤qh}tÝ–‘:豬‡ÒRðE:ÒH6ˆ¤w¹Û…QØNˆÄ“Ar ÚD(³9˱ríy ÁÙ˜-â€0TükŒÆ‚|¼ÉHE¨ˆ±ú´Ð;¿À RùÄÚÒ%¢k„F2·u¦Õa36GqºõaØlaïꣾݪhªÅ¸-ã›*-…¼7$íÑIËemÔv¸ÝÉ` þ ½JNŽ•sÏ«3:[äï8b×æh.H=&%ö}¼/¢ D†âZ¯ôG…#\D?ê<ˆEì×øZ¬¹AöEUT­€ v o:†uXG «#Ë€Ôg©º Ý÷TQÕŠV`E´‘hpZ‹ßÆÛÐÁa“í".æG~¡fšXËÚ”Öc+9}´ZIQ0í ž”@‰MØÄçdÑ•Xâ@ ˆþ„Ÿxö;ã38‚ÖìoqïBìGê«Eï3qA"}‰—pI¢ñ¥F‰·K´XÐBi)øâ>îûÂ×n‡SÇ0ƒê Ž“õ`É®á9ýM‹c‘Xem]•€„Èɱ¤JÝÁ4áN…!ŒOË<Ò9ÅUbaðYé¡ÑCؽgb¦X£™ð#~Œ@„DaÿàŸHÔ7ód¨> Ãœ¯ ¢fÿ0Û·®¯ÒRÑ è(a&TDŤ89ÎZ¬mŠ¦üÏ'¥W,Ž%nÜÊé•´Ú*)NQð6nsœCÏ–Ì )ªäÕB-±Š¥!Ö>‰J»ÌÀŒš¨).>ÄCÒFHIƒ1vk׈…ó8Oë…“UA”BFf†.Tw4é¨Ò‚ðÅ4L=Ãn.æEQQúŒ?ó`óÏ'kK,Žˆ‰ÞàxÄÓ\–Ó+uµU"ʨÌÑÄö;|Gf…·&õ˜F”¡VbeC4e(kýþ:^§)#Êh¤º…¯Â>C$²P8Põ\wç«xßâf‹Ç(5þÂ_qˆqÀÕX諸*Ö€ƒ1˜´bž'ƒoÄâXRb9*ïùÃ? rú d¨hÝý[£µ-=M¬.Ö8¥QZ”¡Z ÅRHXÃ9 I¤:™‰œƒœUXEó®ZÙJ$”ôn‹Ø ZfŒß=>¸~°ÒR@+5›æ ½bÅòAvM bèµäs²·ÞÛGï#h|[ÜUe9JnÊ+Çf!‹ô4ֆщHt¾æ$¢弫3©~ð“Úâ^ƒ5•PÉaò¯øµªÕDÍŸñ³¸‚ ‚Kï|=Èx  ÒÞ¸ï2½ØÞÅ»Î'ž`ѵ¸åIh‚&±‘Ï™DkÛ°MÐà¬ÜE”î/ŽÂø/9Ö3C¯·)Œ I¸!Og¢©Ê¨<“-Ž‚OÄÍ€°@ôXˆ…NB/‰<ºY[´u "ñ4Nw@RlUy•Ã0Ì™|jeÑ5bÐr—)u¸ »œOø2ÖÐh×uöU@>g­ ­LÅÊ]¤ØçG~»W‰úÃßÃÓ¦0‚$á†< Cï2c-¶æK „¤…ô‰vÈpvrnè&Q… ÜÁHDò¥»Š«ÝÑL¼˜!Q»ð7þ&ó§…¨6ôÞØ;+®ª*З®‡Þ™fFD°¤ÁJÚ]º Êüˆ¹ÏICÑšàxZ6îÚÝÜ['|z‹È±F½Z¬Ñìâ&nÍÎÅ\ã?‘X…$½#±–“a„d¼#X”V>X…UÕQÝ®:ú>À!!½W¢ IgPUHQZ Gp6õ¬6P›’ælä’lhƒ6BÃPM˜ƒ9dþHíØùŸ¿·¹Ïù#ûh•c§aw ¨IMB’ K‚3¼À Ü(ˆ‚Æò¹¤ÓŠk ZԾŷ_¾{k£¶ˆòpƒV½Ê¨LLkë„ dÌÇ|Rwû£¿lÌ/³0«'z*-…ƒÈÛ2ï„M”–‚/ÈÂr¬cÈL)Š¢2T3þÿ²Íp;ãïDkééé‚FfåØöhÏ1}`Ʊ¦ÿ³œ#Ç’²!]Fž-úJAÏ¡9šïÂ.©oG|îLa±èd#¡ø ¿…#œµ Íz¬E,=7Eºð™ARûBš-jV¦O¥¥à "ÉDòÃÓ:>CälåÙÝ¿Ä—'xë½Ý<ÝÆŒiÉʱ¤™sGG¼Â±6ÒDäXZG`„X£ñÇiœÎü~ð{ŒÇRßë!Ò2šaK¤ PàNˆ+’] Æà`~„^›FhTåÄmå&š ‰YH2`ëå­îQîJK!qˆã¿©‘†4Òôꢮœ-éi¾“nÀán%N[ykeHHÈ™3­9–,»¼È˽`òÇB=v8†Ë³›c R¡=á9Óe¸Íw¡a!Fü¿I¥”³žÖ…0„e7p£ú31S‘ZˆŽa)–:ÓìXAÐ×íç¾ë”ä–X SëS|ÊçLz—*£rgtv¦YžchŒÆyÄi$Ûºuë¶m0O­9vvØmÚÈËW௹ySœNmÐF©½‰y˜GD”!EZê=èÅXü&ÞtàÂ9˜ãØ…Îc¦uB§‰˜HF÷XŒu>\f$#ÙóAY”XªítiÛÇ‹ˆ-ØÂ'S’, HDNÆdEB>‘øÞbýè&n:¦7Zs쌇qv¯ÒÓ«iˆŒµÉ±ƒ4ƒ‰ÂW%•jzò:^§E‡f"™-ÐAÒÉHD¨#Ô­Wb¥"Ù=7¸‘.gç&qAÂoÆf¥¥p£¶ ©¢´|A“(òpÏ MØD¦è•…‚Õ£5B,Ž%2±û7jÌ<¶n”äáåá€HÖ·2• xÃÛHzd¶®H ±¤¾Y=Ö º$ÙÄÌòSÜœi´ü}ˆé™ï."`‹º ®>¾ªõÑ&?q™f»QÑ–Aš‹\²‰b˧žˆX¦´¨Ãi`*±ØÄ›ñoz8AjÁ±¤ŸÓ„µ›ù ÇÚØó24Ç%[åïúíÌŸ½àƒÊ¨Ì¿JPÌÇüæh.è’ßð›MÁ8pwº¡és1—Ö>ú‰Cœ«lrY# IþðwÑèßZ¾Óv1UzŽ?¾n$õ4DÄŒ`µ‘áQ´©‰š²…AÏ«8…ÒX ŠÞà`0Å—Ç0{–p÷wŸš0Õ»XpìQ-‡r|®òøWE•¡d©¤¨‹2”PXëù“0)òIQ0ÿÚS‚Þ´)˜b±¹/Ȇú_† ä#|d¾á»k\·Ä É;°Ci)AÕÑU 5)T±bÅØØØÅ‹+-ŽìÂ."R‹ƒ¿ã÷B(DÚ‹ü¶j^X*ÍO™²ù „‡ÌŽ“òIl&¨ï­ 2øDIññ@<Žý ŸÉüià¬ùe?à‡`;Ц: ƒ 0††h(O™¾MØT%[¡•uÔ+qo bDï½%迃w”– _;Ü#ÌcÏž=99.œŠTox›gü‘)D‘r”Mìfª ¾½ó³™Ç’!l7iVk+†M,Ž¥¯@Ù ¢ÖNâdA‰‘¢×í߉ü“ÚÒ‘Nz¯Ôµ¶NàD4)ƒ2=¶fb&­’Š!.ãrÂ\±vÁ­´[?Í£gÒö~¤Ç3zÒF“º"*ÊÃe Á°°opÏš0sDáØ+¸ÂÓ1eα^áÜ<Ø_N±8ö.”GyQ†Rb“dëÓû¸OÌSõÄu"‘Nˆ£àUèžD²sE¼»îâî` æõúõÐ+þáÁV*½{÷®ˆ©^²Õ6tà¦ôЈ‹ŒdDÁœ!Ïÿ^“"…––ŒÒ(ÝÙq·q;¡à2v«9öc5TSZ G0þÇñÁÍ\£-ÂYœ-np;óJËò îb ü Ôjü1VÅ&•û:®“ØÎP™‰FÈÊ D Ÿymj4ór¶ûÏ™ã¸ÃjæXòôK¡Tôp²± ´ÞÙ-ÌNZ´èæí%\j‰–±ˆul‚¬¿ù˜/®Hò€Þ|_øÊÖ·QD\K½¦ÕkÓ³Uª–‹Ü)˜Œà5XÓM„+…‰˜HFå,…cÉ0ì…^ûïDËõPÏÖ§³`3¦“´ßɘL:ÆøBæâœ{°ÇnW8u‚žÕp WZ Gàçµñ/9VÒèæc~¢Z£õqwlXГqˆª]w‰hfGDDö ŸÀuÒ]ë ŽVú¨=ØäX{^íµ÷ä)ô.Ö C;±Î#’ŒÅYb!²#6c3· ‹è‘,몭Fd€iôÂúô‰cßÅ»òïÂP¹Î¾2ôLû°cES3b;Äv_Ó]Ò[o±L3±9šóoäÍŠÃ8\ÄL Ô¸šeëÖøŒí˜9@¶j ÔàÓ&Ò¬^møÝ=‹ÏP¬Yâ/xÉÜ X† \Ò÷èM«ŠªÜIv´èóô·ëÿ-jÈÙœHР⊩©wp'ò7Rw­>mUzxi‰§BÊ@”!ÝL”lqc½î FGP#~Oú]뫽óäë§+±’Ôžƒ8Èúé3<ë…^uQwf9cK%ãWj—lQµ¥ËIøÛ*?."èíýß’BKKÞ¡W\¼-1…PÈÔ3ËVT€yaá„W ¹Ë¥XÚ.Ó™Úd ÚÕRTˆßÏÈÛ0¯ýó‚›ù˜_%I+ûÞrSÈ)ИN*ÃÒ¡Õ—­¢;Fsœ@öN$"û£¿ELæyœ'­©ºÑ$‰‘B¸Ø *€1DVbŽmƒ62oFEȦ‰‘¶+ ¢`K´dÝœZŽå&–51®‰Ä+ H3C RHQQTÑ-\qÛë|ÒymVDÇ;±ë̉Ftk´ºqÃ=Ñs‰>¬(ÈS)Ϩ­£¸ÏIFòhŒöƒ±âLÌd¸RÌ–`‰ñ„è ´Â]žWŸeT`„Í4ÍÍ›"t¦¦Ea2&;?Áʬ‰‘éDo­ï¤ÓZtI¦È<134w¤oþ2üËT5yÊr,Ê€vã0N¢ÊçRÃ-ÔíÇë"d{ÝÅÝñˆVh%]…ŸX Î6j;wjµŸóÝM “´#ëÖ̤Р}z¶œ±/>µ1Ÿ¼y·ÔNÐX± Ëd.‹ôOÑÄrC:m©Úæ¥ZæbnC4ÌE®9w‘qxÕðK«ˆ Žõ‚k! •ã;|ׂÙHt=„7²Ý©VdêöC¿  À©]sÇpLñ\¬¨óYRï”rr,dùÀG趯-g¬Úð»z–‚-I[DÙö:„C•QÙùqAAM,Ù¤HWB¥Š¨¸ ÓFÜK¬ËT 6HeÜ—1—Ïÿß}®gLyaKÊ•M'ÕŒK¸…(¥¥puFÖ©ù‰esmž »©5Z‡#|"&Ê“¨’‰Ì¼È«lK/kмs/ê¾õÌV'Ç9ƒ3…íW¨µ7ǶG{I]²ÉHÎ ñ]úÜPƒµKªl[´%Õb ÆüŽßnŸ©˜:Cñ*Ç& LÍ2®*$° IHR¤›“ Å+‘ŠÄ¼ÙÂ%ðj)ôáºCß4ò]ÜŽé%Q² ÊÌÃSažñÊ6€Š¬ªa‘rýÑ_þÜm|Ev¢¡»wáÅþüÁ½¸;ŸI[ÛŽí-ÑÒþ=ÑÓÚ—(è•VÕs&DtŒðÕû:ßÀe$FN„°ñˆ×xdÚÚð‚¡ò ÀÂ*Ö¶W´YË´ê•Јg{@úÕ\ÌÕÓh h|û Á'`2ýF ¹û0¥ùpòß“s õ;Ó;£h ¬‹rììx¯+-ÅKlËNLÅŒ6ý¤iÏÒ4^šÔL®ò×7qóc|誨ºK•íqIÓ¹3ó’ª 7tºÊU*oÝ꬯ 1o¥ÀŒ}ÐzgW¥X5±¶½¦`ŠÌU ÈŒúÊyG[¸€ ¯áµº¨K¬åÙѳó¨ÎïâÝ ýõ"¬àl7Tw/ÌvªevR¡KD¸(ǒ ªÀ³sLýpÏ€Ï ëf7°÷ vuÿ1‘%´€þ¢uXG¯P(Biu–¢± ·7îÅ_¦ Tÿ¨z¥~•æÍ›×¢…³›žaênâv‘'üI=‹+Ö¶×~ì§Å×ùqøãTGu9ïh,dÑâ‚™˜™ƒú"¾¸ô…[°ÛÕ{WoáÖl0¯Ê•Ë4©aÞZóBɆY)8qZ ¸(ÇBe’?7ÔçÏd’”SeÐÐpÄ:á?øõà·}lú'½<»±»úè¡o€ô¶Èœ,ÉLdÒZ&V7g'‘œ‘¬‹ÒÅŸOMM]¿Þ©Î¹IH±R9¾Á7’n{ƒ©ä܈LAJ䑹 Š9H}­†jMÑÔ´&ç~Å K¼WÂúü>Lö]aE(CUL%*‘|Ÿ!ìy€ÁD e ŒÁ]0†)FÇb4–R¦íô¶´ìî®wði­uP‡Vgšõ HÏeQV%ý}º.ëZ ]Q†Ú ™ePnâ¦G|{É™çq^ë)í¶W”9,ï–NqWÄ°ÊFöWøÊXžË<}Þ8÷ï¤ÝÑ…é¾þí•ŽÏ˘7–}‹îšU£"yà¢!²P Çvã›Ë”äÅr{2‰ZëϪØ*0ѵP‹¨•,™uÝÐm)–*-3Ý<Šy,?¼\”Ñ>Á'B}Œƒ0ÈÍ++ÁÞÞ#cÉjðÓyÌb9¤¥y¦e>“´è…^Ë^éG!ŽãxT!ã΢§'Ìæ~ï…½}Êûdå¾\Ôb™j,ÈZ£¥– ."K ‹I†jü1Ð*ϲ³HkíÞáÞìYÌóãÁu LÅÔ!p*oBLL˜è_G´ ­Ñz6º„´žz¨gøC?=‹e-V‘ÃXá@Ô™3øßÊÙãé9žÆèHD®ÄJÖêO&ŽÍÎÉÖ7Òwûº›é#Ö:0)ß]'(ã†sÑYÈ[­‚NÀf©ÖY˜õ^›‡y×píÀåѶ³1Õ‡Ø)Ô¬–yå½C45$?òó©1k>ÎX#ˆ؋ƈTäð.‘ùìü8üñƒ,K–Ô²(Û 8mÌmØ]véÂtçî½TZBþÔJgzØ1­ò|w¹/¦O¤j¨F¶Ì‘§¡’JŒn¡¿Z…Ã09Ÿg>×xj23ÛAŠë¸.óŒ¶ÆÔ½S=b=²sÅé@wwüá/¨<æMÜä¯ÇÒª$u&B>ä“Ùª‹ºRGÉÒ72óCj*Úc ”UqHÅý_n~«h 7+ƒaÙ3‰xõuV%É´ì†n«°ê2{8pQŽUªZ+>ÆË×¢ø¿©|Æl>kóDS@sé’+Õfô…¯²aºúú.³ºˆ5Úfln„F‚.„A:lŽìs<Æc¢RÖ` ]ˆn^¼9]ÐEæ’h_âKI›Y_Á²õê N"ížlAY·ŸÜv‹t¼`°÷½Š«Ë°¬#:F"2ÑÝÑ}%V:Уœ.ʱPTrZsOã4ýÀ@¤z¼²qh«[‚‰¦žfß¾}V‡Õ‹r(§`‡Í…ñ Ý¢Ü=äßÇûS0EÐ%ü•X#<“Y]²óækýµ‚nÍŠX s.Ró¢%…eMSiæûqóßbâoÚ´)oP^zIî>w*Éà<Î/ÆâNè„ Â(ܽI¿¥ƒÎwøÇòér{°ç|ÒMõÐA‘•†=Lk!L!Òo­Ë}jzh–.U~§ž?Ú£½Ð:«""¸~pÇ…E°4JÅQA—p—4´ÆŒ4Jö ÎäG~çÇ„²(+J‹ s\Çõú¨_µù»Ç- ØI“&EGGŸ?¾äà’•ÆUE*¢ú¿ð×\Ì튮±ˆ EhK´œŠ©ßã{¢\šƒücmá9žÇqZÚú¡ér~ð#[fFmÃ6óN¯ÖBl2ô#&ü–N¢îÜÇ~ìJõoéOþŸ*rëUGV¹rKÉLkÀ{¸G룠fß²áeÄNì””cI³ AˆÌÝ@Æcü`8bÛÂl!õõs|.H=¶ØˆéÓ§Ï7è—ë)×I•]uBXów>¸…[$êp o†f¤Y `†Ü{Ÿ#Vüc-@ ål åÍþ´v÷DO²eÈX¶µ¯êg•6;/âáÒ n‹ý"s‹¼ñÞRH.¾Æ×oãmEnÑ$¢ãj1•ØMØ$t«4ñZý#žÎX#R‘ªñÈ|ˆ‡Ö‰µíÕ]dnÎNúF"ø´ê¶ šb}Ч 9PÕ# häÆ‘Þe¼¦±­Ñz ÖðŒ¿ý LùÕC1_¿/³¶~†¥7§ýºö¥;KÕ÷|NóOK<¿Ã„As˜2!@K­»‡`œWø#_=‹Q)ֶ׷øVþ˜º’(é|Ï8âê(Ñ ½‹oçŒéS±_E'¤ Êe%ÞÿWKõhŒfJPš=¡¤jlC_ƒÓÀÛÐê{Cë«Ÿ¾Ò7P¤:…ƒ¸ÛÁ–ù¦¹¹¹þUüó•Ê·mÛ6‡¥Ù}g]"ÔQ`Ä,a½J¬m/zWi^Ëï13:Âq³"“19 aÎôããžõ‰É‰îqîbå: Vâ¥Õ¡Z­ÆjU%Oqƒãi[¨¦¦ú«‡bè]eŠœ½ÀÑ“GµeE˜er"¢´pcôw£}*ûÌ[0¯W¯^b™„$¡4âïÿºÝ2Ö ÇE/«§Q,wAs4—y/ò>îC¦À÷øßø»*¼†×nà†32ØÕ¬>MøÔ³¨gÒC1ÊL¤d̘#¥ÎU¸÷Ei TSIqóæMM”‹Ù4·`‹l·ËÊÉòˆó˜¾ú­[·J•r¶u— +°¢zºÄþ¾öË°Bë‘u‡XŽ‹T¸àk|Ý¢… óÙøTKX…Uá'Ý^ž8¨¸¾q;tòF"‚[f[ÜËúã$!³²¥Ý5¨¦‚žž® ÐääÈ‘Ä'¦`ʦؼLè·ª_x«pãï">¨7ñ&-»‚.µe7Ïlo=K (± Ð;„ ™«Á‘8ÄñHCZô)‰’¤ÇŠ"Ž½•v˳¼g¿ÅýD¹£óÑ+ˆgKö$—Ô\»vMi)àWüZ µä¹×ÕGWuùt?œûÁþ©B@T"X+bqÀ1g¬¿ãw›… ü5Ožˆ`aÕFí=¯Ô¢–UQu3xéáÇq¼Š‘ê›Æ„؈ž³~ü7ã5šßn¨¢ 3•ËJ®k£ûaŸÈ")2![ærÅc:ƈ>ì)œ*Ã÷þ¡ ¨-s랧ÿ¬àÙÖóão>¶>.s0§'K%xi±[í.¸ô·†Ï"I'‹{w>³~ëÖ­¡¡¡õÆ× ªôZ÷‘’ð)±ªírbj+ÓÍ_íû*¤MˆÒRƒ ûþÆ÷}kø>Ë_+»‚+ùOhIþ¡Ã^FÐûI,ÎÖüD£Ñp¨‚ü±+Ú3Ýd=É(a-ÿB, Gø&&›\*}WŸ\­ Óí¹(·×Ú×U¡¾2ÝüqáÚmI ‘•úUa¶º"ußœ–ä ýŸ¿‡÷]òþ%ŽÕV[„¼ú¼~‰~ÎO†y ã±óC Âz¬¯‹º¦Ò:ÒÝ+ ‚ÔUx{¯îíUÖëú£ëRÈc.ͱ.T¦Û999¢”Ä—R¿*%ú•(3XðžOTGõýØÏÿ|bŒüÈ/ ÇÎÅ\Öq–,Y¢©¬ÉÊÁ n‡v+ÙÛXIReË Ì`Ù_ÄÅò(O˪±‹ ÇÞÃRÝK…5ËÊ‘Ä}Á —æXc %¥¥pb%ûÈI_•Ï¶|æë–”*‰Ûên+¨ÖÖVl­?Üô.k\Ã5G&ëÝ5Õ5¢d oÆæzL­b¹±Û+¢â.ì¢Ç+[ÍpÇÞôgiúúúê£ä.»áÒA0Ô*©úJKá \Žc½á-Ñþõýg÷µy´m•jcâ+|ÕÂÂÑI%ÓêrKï²}Õ?1u.-á·Â¯Vk¢Ž3‘±‚ü¡ !èŽÉvGø;ÖJ;ñ^¢{ŒûÔ]SE‰.TCgúQZ árKË-jRŒ\~Tyï0ïŸþYŠÁ UPeŸ:=¯€–’@Šøýø†¤·ˆŸf}|oê^m 655Õù[ŒÆh¡‘iN"é½Ñ»J‘+çÖ³3¬µ`Ï­—ö‡“ò…¦»tP ³þ *-…ƒp9Ž•hEûâ×/ÜcÝûê;aÂÑ'\À…0„ r \2¾¿(Ž‚&$kýŸ°vøòl-N2Â%\ Eès¹º[_õ²(ûÞ"¦íƒ>c˜¾¯2ÁáVÚ‰‰‰… ®Ö­šgaÏË÷$ìh—vÆÂ`½ÊöR‰—ãXZÎD÷Ì\xpÁ=Î}ÚþiÛ¶mkЀ=ÞÒIL¤ è’žèé!–£Àú¶WÓV»b¬{K’ÑXž0›S8…(S…ðû¸ˆã?mÄ ®K—.EEE-^¼˜~¯2¡JPÝ ŒÁ-c„" iêéëê\zp9Ž¥åLô&ºSté~L¹ò´´´õë%)ÓW%~Á/üÏÏBVBDÿr<¼³+ǵ>žššª‰Ð`íïòÞÉO“EÓ'q’APêÁnìv×?q2õÀûžk<3X]sÞ½ûOëïü-Œ;_çpÎù¡la&f@ë®\ä¶@ q»}qÀù÷ðnê]ïbÞ­¿n-Š<¶Ð=>gê÷»0þDZ2CÄ~ðúA]˜nËikÒ~„†‚E{ä@t‘蛡aY+¯Î;8OW\'Ê-èï}ïˆ2”Œ)UPÅV©ö»¸K OZ®w·€(ïáï—~wrï¿^„ÕÙÈE¨Ì}-E‡«sì©S§ÆŽ[´hÑ3gÎ(-/ˆõÀÓ²Òüjúu]ÔU”Ñl^ò‚(xù_òÄ(0GPx&iÈÖÇsssÝŠ¸-<²Ðù[ÜÁ­ßh)H©‹ºÑ™;Å€–hVPÃVÇ Ö{¸ýÄv·|nŸ”DÕ<„CeQVŠ‘å„«slFŽùçŸ*- _ˆõÀ«M¨–¯u>Q†âÀNì´U·Äa‘§>Íáb†v¡õÈ:…SÖÇLàÑK÷D?ôw—? IåPn0óiað>hŽæÎ7;à†ˆùÑåºpÝŠ?Wˆ5  Ã1ücˆ1¢,\cIQZ aåÙ4Æ=ÆýJòç‡âF+´Z‡u‚.©îž~)~áiÄáÖÇïÞ½« Ô¤¤8Ò'ˉH Fp*Dˆ¹…¡ W˜ˆ‰<φg•Qy)–Šrw[wâÝ4–hvÕþU"ŽIÏ?A‚l(uÂÕ9ViÃùþÓ¥Ÿtaºe¿.EÜÀP„ Úé&>ÑéS¤Sb —q™¾vVôêä5tž0×±-¼7h¹e R¹#¹K]u×ó#ÿiœv^[wâgffÆ–Õúj·žâ*'žÈ$³€§Soз ŠxÊâ+3œ,&ù íWI¯Ös¤ÝÌ5‚Ì4²[]2£eøNè«À¢2ÍÚ7Ë­¬›(·8„C1ˆq²|ëoøÍá*…;°£ŠÜÇ}gà€ˆ?;;»cÇŽ­[·îñM·|n?_äJ6œ„€-)Ú UQÕX-ÇÕñ?Ž•Î“ÌÊÍòð÷ˆë'µ³†×(D R¥2‘™ùÜ=$—-0ü¹‡žEev¾âÄÙù"ÔB­Xáð屑¬g‚Æc|MÔ”(bÖþbeïŽ3¦qãÆÏŸ3©LýÖõsq?p+a<ˆæsŽ™ƒœ!(µP ‡ìÒ9®È±Î“¬1¡†›¿Ûî}»Å‰¤}ÕAA—«¸ëŸHê(0‚ø_ë™Å(Ëì|õgçk/öB!ÇZÖnÀZnÎð5‹ÙA+iGtìŒÎBë¢óˆ…£/_¾œžþ2X¢í¬¶1¿_þã’«`Ú½iÚ<¨ ®[<ÖWäX‡×µn‹º¹çwøáÀO>‘£†O4 ÎtI]Ô•t·Ë¾á©¬=Áïß¿¯ Ònº!Nú‹Ø{¢å)‘B„X—§xJ2ôGÑ-Iç~³yÍCÄÐ4¬¤6liu|Êû\LæŠ í|P 0OSÜø1s„ùÑ3Û® ×mæe„‹r¬Ð¤í—·ë"t ~Z@¿?þ¼téÒÒÈõƒ1x2& ºdÈümè<³—%¸âÖ­[š(MF†8åJš  ÿ¨âdÒ`ã°(·6á•C9Ñ+¶I½SeTŸ2>\ûƒû´Ÿñb¥$Ê Ä0éÛ/ð)ÐWJ e€KoxÁe9V'ÿäí“îqî£6Œ’N ¤!- awq—ÿ%)H F°Ì߆>¦þ%' ÿäÙ&959oå¼åK^>ΙȤ‰|‚‘”/ˆëŠ¢¨"_…x:kASS³}ûvQîr§I±ç¨!@ìhI»uqWéÛù _‰2š »fÍš˜˜˜A˹ås[˜ÀSׇ—ŽKµOl~8‡så ëüêçØ(XÆGÞcú7Án™×ÔŒÔÐú¡EÉΕ5Dp–5C3A—üŒŸÝôeVbx†gô °ÖeÊ»:o™Z¢µè}ïÙÒíá-1ó0O¬{qãnU@…Qå|¤ˆ!²¬8|øpDDÄÙ³gé÷;fèÂtvM°u²÷«þ°4 èŸù€±p¥ ¤oñmgtVZ Ça˜_jçØA`i›tcæ¦M<Ë|Õ6*üÍðç9²¶¨ Ó&qB=Š]ÑUÁïÁV×/™¿è ëVî§÷<ˆD¤u¼+]+´ˆ¢Ü…'ˆ£±Ý^v!uXÑÉ“'ÿýe”ìòß—»E¹ ß0œõd‹7h&ýïïDªc€P¦‚:Þ 2Q%®±Ë¿N… qTȱôJÅâe¬O#³ð¡Ò3Òc:Ä„4y”ÅAÃ’` ÖÔE]A—\ÇuGf ^±Ê<ÿàà!Z°" ´q¨X7Z…UÄliÕG}Çòœݱ/úVAgš Ê¿÷â^·h·f³šY+á3Ù/Vú߀fǵ?í:Á]Ðå;fepULÈ™àî%N'±p7üœ4;Ø×àh²À5°»ÂŸg=/о€[·”g"Ô„ä”@‰Ý–Dö>pó? Iò„?aUeïeÞÓÔž8!À·Ìz>¥Pj¶™ŽlÆæÄHWRÀ.faV¢îtLúpdnç÷ëµ_}JùêYèÑó*Ä_ø‹(—fM °Õ@¡¾ÿîy=0ì_XT™¹ã:Á…PèÚËÅÁõPýjõ˜1JKñ7"`v#Èn4O ºlXˆ-Úf³rlVvVN‚_VD?_õQQÐ%ÉHÖêèæظAŒuOÊo®_Í–5źÑ^ì-ŒÂFæ1 G¸ ÍA)ð ~!šŽéŽ¹gk †¤±¬¸“r'ªM”ÿ«)WwaW"n2³‡Q\£ !²¦¨Áa†|[ \wŽ½‹»¡ÍŒRž{<›·l®´/@KriCÒ ˜m#Ë®‡ E0L^Îl £a½6GzFzᎅƒš%§'ËϱÙÈ&%v«¥Ê`“0I%ÞƒµªöOOÒFhûí7±nÔíú¡_ÒŠ¡ØHÛå‡'ˆ j¢f ´xÁ]#‡`ȧL¤¿ÜÈÎÉ®2¬Š{awÿcþ‡pÈÖi^ÕÅ=‘’ 'v`Gs¨… ƒfžæƒ„%LI‡ãÀgÿþþ§Á]O†ÁEÖp0ÞàCSi¥ ^©šú45_Ó|A­ƒR2AñârG®ÁšJ¨$HzŠ§¤ÄúëUQ)$<[£Í}Ì–ûî;Û·jÓªbÝ( Iaë„Nõür ™Èü’B+”öÉxiÁ„M)€ïñ½Ç»Úí'[mæ¯Y/àæ‘Ü~4‡0ã&`‚ÒR8Íûš9sæ(- ² Û^ oÒxÆ{²€Fü[ÕÍœËnÞ½R+$_÷|òor‘…¬"(²;]5 ³tžª X#H•eÍÿýùÙϺüºcÇ,ûÀ:Œ±ë ïõMôÃ8LÆñÿMí×p-„©ç*7fbf"Žáج_g¹r«?ª~F6K&]^f)‰{Lz&©Ç%Ð …Î)µAÓT³k×.¥¥°ƒLC˜–…ÃË\]Ù!BM•8ÃÏàL0‚ù«‹2ã.ÔEÝâ(Î'J„ôÞõösbÄÁ!"Mûm¼mÙ›‘›QgB÷îó¼’ÊqÄ`÷53¥6Å œ(q–u¡ñÖ<}úÔþyJã´¡L9Œ9ŒëŽ®s wë¾±» M 8@Jl-Ôt )±‘ˆT!dž„g“*Ëê•ýxÛÇÞå½³rª mLª5Æâ~„Z¡•3£I]ØU%ë£þQå8m6f‹^8Ѥ`ÄHÒ™73ùåì÷Ã8]¤®Ë]̦3›Ì^¬Sé²c&ÉðT%Ž{÷4Aê›äV S¡˜•‰8vü·ãuºá?²ç¼ÈbË(ð+~t)±Z,E’gíBç‘ͺћ›ë_ÅÀw¬?â Z ë¡ž)göž‘¢"u÷X'AöÑ2,‹FtS4ýÉF­S8%iN==·-ØBJ5™o¬©"æ8pó€wmï¸nq·“oK'’ ¨‚*BCÍÕ†“'Ojʨ—c+ƒqv/2l~M²úÔ§Ÿ[”ÛÒãÊOO¢£.èbÿ<3–¨Ó§ÈдË1½²¬syñþÅî…Ý“Ÿ'[Äßà› ¨`îÕ9†cAº¢úÌÎ d¬ÄÊ2(S ¥fbæ£WÓ¸ ñÿá÷^©)(öa_5T£çÆ¿ûáýÌûEúñÈç1÷[5z¼ù€f^䕨›lغc«®…Ni)l"ÁwЖu÷f>,Ô·¶ v÷ å׸븂¸!èªOñ© ½æ ñlÅÌx£@ƒÉ “ˆˆ8Êz›˜LÂ:¨ã­ýèOØýoãí@¶FëõXorŠvFgq]²©Hƒ9¥QšT}Yh?²‡Fêôºö“Úçä(œáâÖa]´QZ g1jþ¨°þaJK! ¿ýó›oßüMókRUAR4³„–Ö'%–´Ä¼zUwºcbeÝ3“Á¢¯¹vD =sWp+ÃíØ^Õ­¹" Y¤§MÇteU¤Ç®Âª×ñºúîèþ¾›…Y½ÐËÉaéQÜÂ-ÒWßÅ»a£·‹”Xö²³³_ýõ1cÆü’ôKÞ†yƹtÄIÙd-d_ãk¥¥pMF5©òi¥¥€9¿Îq‹vk0®½Bj(ž€„(ðÂ6 Õ¯Äáæ•ÍZÁ€P¶oÙ²ÃË °Z¹ÍúÑ\ ²:…SBÇTwpgæÑŸF†­¼–`‰]©­qFc´?ü#Yug`†3•jæ̙ӠAc}õôœô:ëè‚uï~ýnn®JÝS µ&¡ÿà¥qQÍ£ê¬ß¯_¿âÅ‹/]ª¼c“Ù¹Ù-¾lAïÉØ cGçX²m+ ‚Pó0)¤ÄzxJ$”˜¸‡{´\gk¸wöÆY]ˆîÇk|݃04‘¡Yî`ÄB,¤ç)sq‘Œ(D5ESøh_ óã ßánáIGè8}j:Ó~C1TPs"ܸqãñãWõ–³[|*û„6 =}W´N”Òá'üT›é™ãòp r«Þ¤úܹsO:¥æîüÃó¡mBýªû¹üÒÞQœcçbn=ÔjÇÇx—Pbð OóÔ§±~Ôzrëà6Áü‡ @€Ýšº=Ѓldò© 0`˜!ÎÄŸ&.51*‹Qy"-+­Þ'õt‘º÷7¼/ç}½b5ªPL#'_MÒ#Çíy0ûàl··Ãk<Í|Å$W–c倄6§ND¢JlñGÒˆN¾Rfòßž¥yÅyÜÉ·²Ÿï+éåPŽ5Â%°[”*\ÀëþXçSÖ'âõˆ?.Ûéu«È"AˆK×34âØ­cdî)-že=«2¢Š.B÷Ù÷ŸYª,ÇöDÏaLÑ8ah€.¤Äážî®gïLòåî/ÝcÜï§Ú/ýz7y¶½»ˆ‹dqg’>]OñT½ ‹0X =3½ÖGµ4îš®óºæäªnÅߎí5^V(qa~˜·F^¥¥°‰­nõ­ä›¯c¾“·Y”((ʱ‡pˆx€ÃµÈŠ½Ø«Ú¤d!‹Ä¶UŠ*ú­èêCªÛd béÄŽŸñs,bYCÔè° «”–Ârss›6mÚíƒnþµüý«ù/_®´D¯€žálÌVZ ðÖ’·Š¾]Ti)X™•Ù|bs›¦çšž§)űÙÈ.òB[8å"—–fwOõ:½9 ÏÐéSXw£þ¼û§.T·õ/;%sI‰TÙc$F6ESù»Ï8ØH’+-…|ùå—µk×ÎÎÎÎÊÉ꺬«[”[©·K]¹«Š4²Âæ@_¢Ä€]¾–$6žÜèWÙ/°Q Ý ÛJqìçø¼>ê Ýê"NVªí¬(ð y< ~ëGÝt#](+›+Ü×<.ÞÐú„»m)ϯáµ>è〨Êâž!HåAGo½õÖõë/ÃEn<¹QvDYZ+»Íêöì¹ÂyU¢„«yªçY¾_E6BjFjýIõµ¡ÚŽ‹:fçf«“coáÍ  ¸ èª'xBz Ê“¸±>á¦Ö+“u<+7Ë·Žo諒m]kN8Å í/gý[kCµMF2Ù Ûô.žèù%¾TZ ÁØpfC@£ïXïO7}ªT”©.%Pâ\,]‚)Ù)Ú<ÚÔ¢OŸêYÒ3_ó|Ço½Øì°ÛÅ@~Ž¥ -Ú:°ëíZñZ¶àæ™m+ŽkÃßt‘º“IìžsVk­sëõIHŠ@Ä^Ë\jµã'üT ¥”–ÂÐ>úçÑže<ƒko;¶Íþb`!ÐXþï‚+t›CµXyv%-XJKÁàÄÝQoG¹çs·Åºñ,äçØ%XBs‡gÑfÎâ,)± %R‘ª Iþ*ž=à§ÆÄÑm¢…Ži÷+L@B8ÂÏÁJ›ìHDþ•FFÙEzvzãOktšb=Š¸î`;Ëlðý}d(©×ÙPÛ¶ª¡úÓƒd»®í×.NYg>n4³‘6X[wDÝ{)‚ É̱·p+!B­˜äïëãïz{7¬˜žpH矚ÎV…ô᳇žqž£¾Å´x«ºë¬X‹µqˆS°9¸Žá#=Ý%‘™™YµjÕ‰ŸO¬9¾¦.TWmDµëXrý¸qÉл¤jÒ8$;÷­æ‚sÆÛs±!z–ÛŠÔÒ(ý¾.²xïÅX¥¥?þøctLtóÍÝ »7 þhçG™Ù‚wu ±4Í/X¾[®¥ÇúÕñ›/y:ð¾n¬ ×µ˜Þâö‘{·yÛôqÇ´ÆÏø9?òÛbÞë¡Ouݬ.>ð Oµ.›•X7°Ý¬–ò*¬"Ó%¿=5•Ð°™Éð/’TE&c²@yÀyœC˜ ùùàÁƒQQQûö1[Õ©Ù©ï®yׯŠŸ{÷æSš_ºs‰ÿ8þ°l?yÎLµVO¼àDÉry‘ô4I«×>|îH©v>ÈÈÎúÝPßʾž±ž=ôLI—¤‘ ^)H!‚ÝÁa§pJ§OùOz ÌA–»ÖûùÄøý¬Ÿî¿¶Ÿ–×=çöÀPBçŽ=´ç.€Á1[°'M«^”ù —Zn4Góÿ@Ãs,_¾|ÄKwÍê“«ãúıĽ7sßÌìûÛ G½É{(m°eŒ°žÞ.dŽÝ56¨q#ŸùçL“IMÜcÜu>º1›ÇdfI*5Çæ"·:|„„^˜‰ÌŠ¨è桺zqR`aÂi­?™(ìFÊ[+Þò­ä›š‘J¿ ÿØeØ8^dÐ`Ën T¯"÷q¿*9à'—p 4J»Ê>“øûÑß-?oé]ÖÛ#Æ£Ü[åŽ\·L~Ü°±e 2É|hö‘EÊÎUC—« Ìà2M§‹Y(+7kêS£ßˆÖiK ,±á¯ NîgñÔ; ³*£²RÇc¼‡>õ?ÕÅ~áiô÷²~DÄ’¯}¾rƒËáÕïë&Ór”ÙѨe˜8¥ þ…†'hU~„GD_£™LU£*ªîÁ¥¥C¾âà© Ô7 îýuï ®c>½i}j W*áQÜcÕqqê[ž¸¢á´†îEÜ}ÊûtYÔåæã[¨®Î±¤{„"ô2{Œ Žàˆkµ9p´ ¹‡<ÏÞØëÚ£k…<†nêÓ{?¦@(Óƒö§³&ïá^Y”Š¡jV×c}C4TZ ùðìٳ… ïÚµëáӇþÙ>’ȶ@»c·}”nža€ßð›­(‘8C‚ó ùbÊTŠ"˜­vf£{è—k¿è‚uY9NÉ›–™6jרÐv¡ôèŠ÷,¾ê%c;3ÀÒqì]ÜÍüßá;¡f £Jý‡c laYB¢F—ckgpõï«uaºVWZñ¬Ñ½ÈkPc€ƒ<οûQ±ú¨¶Ø, …¨£8ª´ 2á³Ï>kÓ¦ù‘Äljo.}3°^ 6@[°kÁQ›FÝOcrº£û\Ìeä¤aÿË”«ò7ëIr!Þ»û£Áþzð1Ø_“mÐ~ÇÅc;Æ:v£ä§Éã6‹j¥õÕêëéû,ìsë¡à wQ ]©C¤rŒ³¿ë‚ɘ¬óÌþoÇØ‚oxª‡>Õ–2Ùk~/¯ª^^™vzÍ<hfVƋ‘ûP¡0äÓÕC½Vh¥ÚüåXÞM”–B&ìÞ½ûömvý©;§º-èÔ0Hë¯ÕUÐy.õÜ{ËRᬓ¾/’˃¥’xp³àÁË ÿüÝó½–õ oNkP`“À¢M‹öÞׇt Ó0­ ­¬fÙ=©Ó§ü¿ò˜ƒT5÷GƒÚaë„"Ý‹¸ uã(nŸDƒ©a®Œ.ß„éHï„N¯áµ§xjÿlÙAoTQwÉ´{I0ðþÀ°Ãb;Ç’YíUÞ«ÒèJSL½—.¸0”<°e›öeK¿ë)×I½•ÌKùüþ¯ï[Loá_Ë_«×æï˜ÿ½oÞ»ÌèÍš5Û¼y³s"; ‰v`G~äw ÉÍk7ýc_}†ýSÿ»XŸpSu{U<{¿’i´Ú¦«Ø7[S Ùó­Ž?7ø xK9Èé‡~uPG- ×a]=&_ÿÀnìŽ@„±r{VvÖêëMhP#@›W«¯£¯7¾Þû¾HNWQ77ÆóÏ‚›°ìúîÚw#šEp uàì7?³È›EÜ£þ¯½ólª\ÿøÉÉêN´¤ƒ²K)Ã Ü *K *C”eY²D”+Êeh™ ÈF„ *”a÷Ç°"Ó–!—] Ý¥+-ßß“KiÓ4Ínú~èm89y“œó}ŸçyŸ÷y$’ú’fcšÍÛ7/#ï‰o:u._®@¦±-°Å}ºø13ã¹c1Ö%ëT”Oãv—Uùèw¶Ÿ¨¦hýE•ˆFQ†žrFW¯ÉôOö!ŽÃ¸&hrçL~’ ) )šî/™w_åHD¢ÊŸa`‘4éAÒìý³ÛÎhëÝÞ[ä%’ב7îßøÃ-ž¸eN+2eîx)aâö¹zdñG²ó²7ßØÿßýëª/­+¥÷åÝØ»oLß½Wö–[Û°aCAƒõÄê ^wq·­Â*3žû#~$#Öåw˜/ÓÈÃÞú%\òZë%i(IHN(þx–.ÞUz O®®LS…{NèòîüàgÆæ[³Û#QÑ}Ù®©JwtŸüD&¬aâ¯Ç{x{´ÿ°}ž5øj<_‹ìØkj¯UV={6?ß®ë›gusým½ý'bYª'K(deeq îhâÑ5qkÇ ~jäSÞ­t“E y؈°A+í¼°³{î;wÚ©Á„%XWc5Ð<‡çÞÕ¦U˜ÿáÚ2+§r“Žt‘[îÔý†õíE¼Ø`L¡“ð@óX‡É!©Ž’}¾I`ûo™VÛ¹4j¨É+)kÍÚQÂ<…§¶•S`Ì•Y‚%­Ð*åGÕ¦M›6bÄýï>üï_ÿ·k\ã9ÅýÅ\cŽsçDa"eOeóÍ—­^{üøñ .ܼy3==½°Ðú³X&´» ëéDu¢Nu§êêvªÉC),\¹neï½EbGÿR"À Îù)œ"ý?šñÜ|äwFg†-?eHH-ÝÉ7ÑúMO㶓„HÎÜ®p3HEjoô~Ï™Q Øê¤!Lë?ð‡£bshR£½/ú:¤ Ä˜1cöí+gÙ¼yóÆŽ-g[ÖŠ+æÎ5Ø…ìj¨íP¤Å>\ÅÕÚÚFj–ž„L©Í0³M™C._ÛZHd…¼V"šƒ½)K¿wø¨ƒ×3^÷³+¼ïà è6Ÿƒ9ÁÞ‚-vx9ã¬ÀŠöhïÚy\(èþ4ŸV´Ù¨=9{ö¬… ýiii2Aæ!xXkHŽå.4Жä1ŸÛ¸]õÍ ÑíÉ°ÂK™EŸX‰J ±ð%¼D¿>,¬ùFÍšjæ?´SÆã1k†fïà;ôÑ0 þ x>ŽÁ¦Ðô1ƒº¢«Ó‘°ÿ^õoùòtKkÈ9 ë°®z™ýtò› É,0ïéäÜ‘Uæ#TÅijÑ6X,µ1áÐ\¹ÚEáäìd¡½>1Ünîd.rßÇûõPϱ.âbuT¿„KƒÐ@3«‚ÀõŸ¯ßmg7GÂj¼‡÷>×V5‡$$…#| ¦˜÷ôD$’ÀJdÌ‚­04ÅsVÒ¿bìÅ^’Yý=˜˜šèáÑ~N{{ŽjöÕB­qç@ƒv>æw@g.~k4…õFïWðJ®v+‰‹ó׿x?þtÞiGÄjD ⎘ñÄ4¤5GsóŠBBl‹¶b™+GÏlJu¥F$¤þúdEØWñjQO®„; òúò_õ°ç¨R2 ÃHiÍ(lÈ¡þþQ:û¢òr÷hÖèþN[Î׺ôû¼_ÈÈGÂjä!Ï nf¯#}ÏL(Y‡ÌTÈÌxo²íâ«Ìå$ùñxœ¬x×ýàwò N\=!©-´vv‡iî~ /ÝtDãÓ˸¬„Ò”ÝOÎÏyœ¯úâÃ*²‘¦Hycùü#ó=«ñ;~C…w¢év8̯yû>’L`-G¡ÌI5‰x¼Œ»«[£uÑ-y áÄOÙif<Çl4ÐÌÁø/Â"û{¸_ãkò’*».mÁš,¾×ö ¨*LÛ5ͳ½gáC×qoWaÕÛx»BO!Ï¥ ÚÀšòZ‰•"™†%X /eMXÅ—Bº£ûlÌ.úsÓï›x%?sŸ•SÖMlìNèTõþƒÿØóuõÕ¨Ìd9š•Fct4ø]Ûd¸ª—Ÿ'•Ï;bFe8çe†T(犖|@Kö Š„T–H`Eè»+SeBVÑ—rw‚T|«ÂzõzÞŸ¼µü x¶à„#üy<ÿ›vƒ¯Ðw‘3XUÕɹ€ -Т/úºLò’‰Œþf´O'[¯¬úWµÖM" IÑx&˜ý!\ÄEX–H`u²%U&» óÒwc7}¹Å×÷µÖl?7ÖØæÛ¡†üwRþa^9 38ŒÃøÓÁí+Ær,÷ƒß×Úr>U‹{É÷$’è“ÑŽˆ5!u ©ëw7p£ÍÂ,³_.ɼæ!¸~ò‰C Wä–;\õ]Ñ#£0j?fÅÑ$³_þú¥ÝG÷Òü)˜R Õ†a˜}Ö¤¾ÀtÝ–®Wæ„Ð-Ö ½È‚½`R[KW£ÛÄnþoø;zVf1Ó¥nÊ‘—p©.êšF ]†|3Õ(¹X²S}_äž=yÿ/ú?sˆQôáhÞŸ_pÀÌ=#Váî}„ª£úP 5Ý2›(DõC?[¿Š% `Õ@OðIUÈ€- ]«"¹hk‚còýlGtÙ„Måv'‚ƒ³_(y‘qãÄî¹juù3,a£ú†8øμýž Hð‡‰J)K.á«ñ˜èˆ>&©31“”¶?ú—®rcEèòsæ³'q’¦Â—ñòmûë*Š»à.\­è^6²=áYnÇØ}ا„Ò’Šñ°“êS·àû‡ÔNQÏåYw†¾½|ÿ£ý¤ßãûP„–h,»þøz>ˆ·yœ#ø¤´dÂ5Dçñôl°Q¥Ä$$ÕDÍû5Îu\ˆµQÛ¼ju.C R8ŽK€±Z²•‘ýØß팳›I`Õ°Èú·€wÏÙ[= GñeÜ!²f·¨îèÿ|ï÷Fï+•?œýA¬X9ÀÐ ì m7vwB'R˜ñ ·;·ºŒè$¥ nâæhŒ&þS|Z)bÅ6ÅMp“ òò«lLÁ”ÏÊ쾫ås|N¼…k²ÃTk¤ÁwR›Ów†a Óâ¶r¢ÂÛ¸ ]yÞöhÿ¾(qÌÁó%µ%=æÚu³­qNãôXŒõƒ_7tÛÖ5kcCs¹¾›M¡j$FúæÝÃ=ŽÄI ù”ŒØ;¸ãèXŸp„ŸÂ)ƒÿEöŒi‚&ölú0n“È={Klrù‡2l€¾¢^RHlCr‡Jsìæ1ycyÛImí?<#d#{-Ö’ŸEc&càÎYëÌt6:­ý‹¯’¡‹Ø—ñr Ô˜…YŽÕy§B*HÝwGÂú$ ¡.êü¯ä ÑS‘jÉKLQý‡ÜÕ­jœž*žÊL’Y}Ñr–PZ¯.Ý¿äÑÒ£éMs œ®h™µS1•ü©fh6ón Ì¶ª&BZ7ƒû Ý¶ÙÒ‡O.a(BŸÂS˱ܙkkÛŸOUŸŠb—¬u3óÇÁÀz®­ÑzFX˜@²xEÆÚXKï†åx+ðBš¾ Á&lªƒ:¥[Ã\O¹î×Ù¯z·ê·2ß5¦4…(TAE—¥üZ ÅLÌ<‰“f÷; ;º º Ã0›î'Ê@Æz¬ïŒÎ„wðÎ œ°ÝkURÒÆûð+Ô+ Œ7j¬ŒD"ò'üTâÁ#8„ hXºÏb+¶ÒMͺ:ú A R ËÉ@DéMšyy†5ò|Ú3îJœ#Æhhè*†iјœî¡ºëÌ0n³ÕíÆ¢œžSfŒd’Ö¾èë ßîè¾›™áZO‰X&nÞ¼¹‡‡ÇÊ•+ËBåá>î{³x=CšÐIZx-<ù,a} œÿ°HfI[^Ä‹]•ŽŸu×o>bf_6{r ×èb{¯“ØÖE]²×`ÍïøÝDÇ3©-ÑÒ*Ec’ô3~žÙÑ‘¤µú¬ÅZq5Ž§àÉ{ò1kcNœ8‘•åj™˱œfØ¢?sÓý›£¹å 3+±’Y°N‹‡2ƒdöî‘—M†Ö+xÅàªý¤}“x?~ÜwŽO5²â¿ ËÞÄ›MÑÔ-Ðb†|ŽÏ7b£jRcƒïTßÅc*\å‰>Ã}Ø7sHák£¶æ,²®÷boÕÜ¥UQ®ã:ÇqÇqÜѱ‘ˆÜ†múß/â"©ë»x׌2Ý%Ð ¬BpÂ.i‘~ Œ®ð<佄—ÞÂ[£š›Ïm×÷üWÏÊ%#ßüN¬ÂªI˜ÔýôÉ îp@D¢ÈÀ [»H oáV=Ô3¥Íb&2÷`ÏDL$W@Ñèü°á.¹X([S€‰ qÜ=[qWüáO·t[ ÈÏZ–ŸvfÜ"·<"p~¼”Y4^ÅUšUŸÃs£0ÊàaÇo—·–‡¾š™ë ¹Í$ªqˆû_ÇðVh%ƒŒW¡zJGtœÙÇp¬²—þv,î‚;i¬6ô930ã|@s=Ý\Öªü¾j³8øÎzµ Ö1,Ä[ù€ã ×ïOLGúÓxúC|hð°ÄìÄÀ^ŠŽŠßïºx™èk¸F÷‚%%&²TµT¤ÙbŸ“@sG‚va×Sxê ¼Qb»y¼·Zäž½:öšå§bØÔÛhZ\±ÿj2’ŸÁ3euÎ×ä¿8íEq°ø«_¿²óíÌMÜlŠ¦dx0Õvd"“÷á?QâèØ-ØŠP?øYRD«ˆB¾®Š–'²•‘qøàÛ_ìÿCßÍH÷9{æð~üÐeCí9<û“‚”HD’íÁ²­lxRAêÂaXè&R×`ŸÇyËÏFÓ}׸i¼GÎöX+à ‡°".Ždv®êH¹2»ûÂny¸¼Á·3oÛs„v&ùC1´5Zëë<0¬ˆ\“Æš½sÄùQC] µ¤Z%>ŒŽqÜ‚ïïS³¿r³!îO‘GöDÕÎre6)3)lX˜´ôÛß*Ю22sBbÓ’¶UIq“x¯OÏv=ò7SÐ?"!éHo¨z‡öçX—]¬RlRßÉóÜ„lºHfÇ$'ošÌ×à£VEÙs„ög6‘Ó·{=Wà+ÕW|0¿Q½Ñѱ §pªšõC¿+¸"@Ð×±„‹¸(ÒÅr;X—µù« ÉH–)S¤B&]!4¿‚WŒäKï:·K.¯?°~BŠ«U.NâÈ2™Ù,ýÕècùˆÅ.rô@¬O6²§c:]$ún2‹±ø5¼fá9UPqÒ|ÖôÐ%ÉE®T™Lh"aгx6 Ieœø ±éˆ¦|ÿÓO%«^¸Wqµ Ú À¶ fº6©¼‡àáèXÃ0„½7ôÕ– QØ ã°%çÜŠ­"!ÕKpÁ*d =ú`"yÞÕõ˜ŠÐ˸läxá µ›Ñ.#7ÃÈa•šäôEß–hy§=–J ¬D¸^mØ4¤Àˆ„ïDòØ-,9íPÕj^‘Á¶qU¦ªÿ#òÈ^²?þk|ˆ@#›ÊI“OÝ:ðJ€{3÷]gvÙsvf–ùà Ö8z •†Ld’Àº^™õX_5Ç`LÛt#Àî‚™·yIÝUó´9Zê»V&ÃÙY¢þC|g†êçÝØí ïr¼z0¯äÇ/_Pಳð%\j‚&¯ãõâ7à $zu¥L­ó8ß Z¡Ui«c;¶·Fkóâö7q³‘j¸Ø#7VÍb°U‹qÿ#ÏE.Êl‘ MÏ®ÌB¬À=ÍIÚIÿßbÛ ÏÐ]L¾dc4¦ùØiÀ—¥ ,‚¶‚ÉDÀð–˜eÐÎRÍ‹?Uj…Ú’Óoð ùøOãé-Øb^ßÆØiJ”à ®ˆ¤Ú•b`X‚Ÿ²€®"2h½ámJZW………SWM×·|¡åÙ³gm7BR€‚µX†°®èjç­aó(Qzr(IÀ]hËý´fWä´YÈ’ 2^Á¯Œ]iÍáÚžÛ¸=ÓÉè…^¿âW³ÏswŒñ€n†]…Ud~x¹N2bT:è*òRfq|¡—ê%\…”ödÁI÷eî\ NúªôäÉ“¶¤!¥]Žåä–’M»{m‘>úž0ª®@K28Ÿ<ìPWŒ-â².Bk¢²LµL°J/»q_ÇëtYŽÅØ ¸`É©èRï‚.ÿÄ?s ×Z©Æ‹äylú,SŸá2!Ëþ&æ‘ííÍsÒW¤ËŽ.³Ý )íVlm‰–MÑÔ¼`iÎ3P€Ã…'K¡MØmlÂIHr}Ê;&Ù$­"…è3õgæ×¾¤ eѧM~ý,1=aÀ¤®С¬: Eæ«›oÎA5 À2¬݉ڷ¾é#T[Ó“››;qÙD¾./é Y¢Zb£A:œXÄöDÏ ÍÆl³óiÉ×jê"«Û€`CaÕ|5«6ðì'¸(Œ íãËËÙ]T‚Ê{yÈÛ}Ї&úx‡¬å8Æaºªoá–Áÿý µPûfHeVy5£L–«Ï’£$2|àSQƒ–(((˜¹~&ß—t–l¼ìš ˆs87#«£:¹±¤-QuYçàë#}d²¾[ÆaS€±¥,ñJ}tÁ[ƒ\Çu}ôõKué4ç‚„”>ÆáNnÔ xa5V[7 ‘„¤Z¨epùò±ùªÈ=¤f-ö€ ZOe&´QªoÍ0h F3vÑX‘·Hä%Šúg”«fye!+1ÍÑ<ÁÓ0-¡ä"•I¼„båøŸäPëÉGèB´;:ña ²ÝwŽãÜ7¤£²¤oÇq|&¶@‹X@ó‚Õ_%™mÐæ_ÚÝ%¹ƒ;­UÈ|eÑW†ýY¡þSoÐzÃÛ ƒVÏ”•S8žã$œç&O«Ðy8óS0%A-Ñ’„¢,‡Ô µuñXúñ5´z†’E£¶@[u]ÿ(‘ÒAª5K5K0ÞiÈÐ áØ$LªÚa›…Yç­–ù[2:¡Ó»x·DÌ!ù ±ÌWÿE_Ž"¹Úanyo¨›gÐùùù£GæDçÎÉ?'&&Z}œNB ÈBT5T£û:Ѫ7bpõjLÞQ¯ ½J|%b…x‰ÚãáhâàŒ AH34›ÙgpƦ¯HºÚý^Ãk%‚9d<‹…tŽ3_ÎÀFõ ‰"‹÷MwWuñ‚×:¬3cU=99ùöíÛžÓ<9/Nä+ráE1è5îÄÎwðN Ô Ëöc||'MY»áJ=rMgè–ûÌùªù¤®¼‚ÿDý‰S'¤ÁœÃ¹ÅXܽiêyÏÌüxÄÛçÕ§bj{´/¾Ýà>î÷R- ³ÁSȳÏ S ;å#õÏ"EºTÈlŽæÕQÝ’êÖKÕKE ²kµb«R¹r•l2Ÿá9Å ÑQEÚkd‡Qi…®LY®,ÿcÕÇb_1Ù®³Ô³œ¤; ]-äû/Çò¾è€€h0ÿÇ÷ú.Ûvã |ÑIT‹Yõ¼&÷ÍÞ«f=ÝÎH*RŲ²ºª># ®a oêjêjœ‚ã|9oUù+;d¼ÍÇünèŽpƒ»‡þ4!Óµˆ¤¼§z÷å% É|õ|‡Û®™ÈTCý%¾ìƒ>tmÐœ…(Ò´kZKÜÞЧA,iû mj›Ò|ýÆX`8?ÛÕw¥Š"ß´:ª·?À–ŸP­V™µ®CГ‡¼{¸G¿|üð÷ƒ¿éRÖ˜ðôßñ»\ÓÇ%SÈbÔ16f9Ð[8€4k À€0„yÀ£ ÚŒÁ˜MØT¡%?«“üØíô2MF¯«¢É0ðrÄÎg0L!F}A¬Èä¤ù2Èè.«hG$ƒÅªBº°Š¿3¼‹ep‘8Á‘XÄžÆé¢Nåd(Æ F"HèÃqÜïàŽ=‡J.ÌQ]…U0¡ º  ªuDGšd×bíœ)·é€}ÈFvôx¯æ ‡æ²÷Tß“1 Wäü¤vÙ–I †<2…2G_RF å` ¶âÿ(ŒÀq^¾^./¶Eh I@Â:¬#W·'z6AOx 8©~æѪ«­Kˆ“4Å#þGü¸ †cx$"éËõÏ3xf†Ðƒ?á'çlqwŸÅ³ƒ0ˆÞÂFlä…4r¸6ªo8z\ †Ed!ËS™IJ+2üà· ­X’T µ§ÚS/¶UÁ²-‚ÌB’2}L€ _>ÇçQˆj‰–ä8pà þÐE b†-ÅÒã8nä‹ oì䙘IZâ„H ÁËx™lT:Ï ßßáñÞr¹„K4ì˜AŸ›>/K"uö13¦s—y™†“ä‡#¼&j~¯­û*²l]Xo¯áÚTÕT©¯´Èj½‚+¦?D5q1ˆ­Ðʸ·C»é˜þ ~qæÞ:&Bo¹jLÁšèE2—ïü“ƒaúj´"!5 aô³[mt©—ÐÛJ½RFV"9¶E&«T!¦žfçpkåå>î÷Fïú¨OsŠ¶#Œ´Ð¼ÂÝ F%¢ºRÃË è‚¯ƒ:äÛÚº­vñ•²Jaâf"SÕ(Õ¨"{Uo²žÆif}UˆØéò›X?nFDPæémÚ„ÒîÀû””/nâ:ƒêf!ë$N~‡ïÞR½U\Tå ùÇ궤€““ˆÄHDºÃ]$Ó0ueTeȦՆÿDk¡V(B¿Å·y°÷ÆÒª«Åè­% ìöѪÑr_y‰tS¸ÍQÏù2gÖr‘;ƒ$pÒ|¦® †žGJË|ºÌÇ|‡·;)Úø` ÈF¯¿û®áke-ò‘?c9!…©+ƒa¸¡Íò’æ“ÒúÂ÷C|èØ A¦™™¹jÕªaÆ…††vëÖÍÑé¢Ä#¾+ºjÕ•ƒ»Ã¦-ÃwqWŸO«o†ÛýŽâ¨£el'¦½¹‚+}ÐGo¸²JY †éd ÃG™­KyÏ÷ƒ_[´Ý€ öÕ2œ“|äï®àzÛÕKpŠº Fe¤š2Ÿ—è·‰"pféKy0ª&äæÌÄÌGAWi>SWÃ*|‹oEÊ»úP­<ú¡Ÿ’2*Gp¤3:ë W‘êèá0.H&2õEfô Ð`.æ:gù†µ ïw<Æ“¨êƒ®Ìpe0ì€j½Y+ÒP¼ˆ×a]6²=.†ÕHCÚ", E¨Þp• ’äèA1U‹¢ í4ß>C0dö¹@ “* }w4]¶B+½Õ*’²ú- †S •=|$¶BŠ¼>ÀvnÅ° 4[±5‘z«UŸˆÅà ©¦ÔÚ?œ<×CÕ5áQˆÚƒ=V¬XË°"÷qÿ3|ˆ"iË YÞƒáü,UŸ)´u˜9ßT±ª#Y¶0`#6ufa8ú¶`Ëóx^¤zNä›ÆË ÈjeUŒÊˆZ ™Ûã0‚ 2Ox²H‚CˆGüb,~Ïêc­Ú€€BC_ƒÁp ´a]âºHHu‡;ÝåLomÍ\YÕ]Ñ•WuàiúÕI–Å`¸6b¶ºûŒ[)¤Lo­HÒv`Çûx?!EV©¼™¬ FÄ_Yø¸‹™¸iƒ¸ðUÁ©{%8×q}¶õE_1ÄtUðX”•Á`4V¸•Á`”‹jœ2ñ‘tü-¹U3ž æÎmÄÆ©˜*’jŠäTÜŽBÔ]Üuô F%¦¤äþ¨àÚQÜÛ¸í&dë[bý¨Ã0W}Ë Ãx,¹Ez[lMy%Þ dl¦×ðšÜŠ–¨ŠÞ)êP ½„KŽ&ƒÁ¨ê> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000056680 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000751 00000 n 0000000730 00000 n 0000000851 00000 n 0000056655 00000 n 0000056745 00000 n 0000056873 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 56926 %%EOF ast-8.3.0/sun210_figures/simpexamp.pdf0000664000175000017500000001724213004147321014507 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\}tUÕ•GŠ^ˆÄª€ ø´J;UȽçžû¥ò@GÌbкր"Bfy!¶¥â I( 0ËÚ)]¸l««õ Ð>’å"aÔ&¯„Î º¦3 X‚dÊ3]:Ë4al>Xy¾Ü9÷ž½÷¹÷òÒiþ$±yîs÷Ù{ÿÎÞgï}S¿™ÔféIÍÿ†ÏÕ‰’oØÉG¿Ðf™禑|4Á͘e›IÝѵY®™¬q¸1Ë0“̶­YºOÛÁ fsø½¤W'˜ÆØ,SqR Ýuµð3ºkÁ )SÑ:È ç®/=âè¶|dN°‚vZèš'• Ýñ´ d*šƒŒ¿ùzB÷ÝbN ¸c*B×ñ·e¶.·wÜb9R= “@qÉñM2¸tƒOÍ‘n2-wõeÇÔÇ¥‡;àZÉM.eÀ®@ · fÀñݺ‡l™Dî[œä&áš{ÅÿKhÉ?¿ä¢˜‹Ö&ˆ³‚£e‹Sër×wpæ?Á’ŒŽ)W0&#ÒÂ4‡J G˜æŒ®8ºíÈ iÜUÈŽŽ1A Ó–€H¹öò× £ Ô†p è 4 åíÄBJw9\Çß!ȱ}¸ô$ÓíàIWãÒ!:4C:0&Ø9¾5f€-rt›Ø£L¢aW_†ä0Sº,¥8 jÂÙã ÃS*iáÐ 9Â)Bˆ<[l‘¶¡L¢a×À-—\uI,„ ÇB9xÜ M†ëÄBˆY,BÌt#!ÄL+BH«B…1ðȃHŒØS…¨E!„zÍByDÇCȵãç9x^\3z^\;/B÷Øyþœfj‘óB4ä¨óBÄÖ4"çw Ð,t^\3z^À6’‰t$„.¹ä…n@2vÅu\ÒÈaš¦ÉòI^`L3åeÉä'Ò«¦mÊSœTÂwc°=px:ÉDw] c`r,Í÷ O¢ÌàÄã–püQ'¼Á@ey_=(‡,†(xD¬ÉÛuƒ§+ˆ#Ìu“U Ó5‰”îH®ÐH]Ô+\„lè®Á‘Hã¦ÂÈqäÑI) ‰¶ÿ¼æ$qK¤…7@-䇀âÈ!S¦¬Ôà´ú.¹är‡4ßL@ε˜.ýá/óœTˆcX`/<ƒôÚÄÒä†÷×ë–ÿd ˆ/ îQ ¯€÷‹2úÑ„(Æä¹µ hÀG¿Å‘¶et10 h¿ó…3â‘ÄIP´-q4WF?H0ÝÀVÚèÕ Ò8JK)!n‡ÌΦ.kLÓÑÁ–+9äZcÙ¶äp ‘€%BÁ£9qx€‚Gs£ðƒGsâðhN2IsãÐèz݈BtàãAÑ°GÍŠB£™Qh€A¥·…†öC£ñ84š‡F7bÐÐ’4&—«4ÈQИ¦W,|lׇZÜ 1RÄPÑF('†e4¡·ìŒ4÷jÊhÄ|D~|Ež£ŒF¾Åè{”€4eű¢è@¾¢=(£‘´õ¶¢è„3šèž“m×€<t¿Ômìk-CîºEà$a`ùÀáÃ,YÁ8’¡2>ÏiÄç„”Å\χJjÄ”„^Á”…~SI =K+Àó$i5bB¤$’)‹ö ¤FZÐ Ð%Äìl,¿¢OŽ(â;Aƒë ;Á ¶â6£I†ÄÆ°"· œu8ø…«ªä¤‡Jˆ j ¸o.ÈjL³äyçŽ hÎ~7Š#sgh(Ò4ð8e5ÃÁPr ‹-%(3ŽâÈœD°HÃ=(«‘¸‚´”âvHl|S÷1 ’”Ôº¨ÛÀ¡º,¡„{À-¦¢8T¦T¦Ç?•zbDÁQI Á¡…p(©R¹Ë4t%5r-pÈõ hJ8ŠcEÁÁ2 ÷ ¤FZà ÒÛŠ‚IjèxßÏ8¦…EM—ÅÀ‰•ÐZ¬PÒƒ­U¡FU¨åÏj\ÓÃUI KÆ}¸R'(P’Š]·`G¼Òp3±t¨šh/Å&È¡éƒaG&ÜÐc Ã2ÌðŠTÂðOTh°L–ç i5Ñ å/äà$eÊl  Ô ³¨hÊ!‹ã n˜±9ÔoZ¤…G0Ö %åÔ‹ú;ÒÃÜ’Ï€L¤UOêá‰ùDbCŽ›ª&SM<ªŽ2ÆH†g—ráTƒ^ŠÒÕe¦.ŸS!6Êê©hë¬ø˜“ C**¤¹2ádƒù/š‚jó2qàå³-YæÙÐÛðîɦöÙf²T¤š,%IеÏÄö%X2ÏÐæeÒ‚V Þ(!jGpÔ C“e¾ért+ƒ^Šk2 †í^‘âäËËø~Àf˜˜ ÃvÃœqtxíRoˆ‘4‚È–U4-ô!24Ù øžÅ·+À1e¢14-pŒìqüé3¼\´©‰v­À%jœˆ6¨‰FŽM4H°\h¹Ò"˜@ ä– !nÀcË!¿¥¥8Qx ¨Ušù7¼jÐ,ß(<†…‡ëQxVð¨Òù(h;Á£ð_EàAZÁƒÒ’GáQ{ðÈ7•Gåût(|‡J¹&×TÍ3æà…TœÜ²ccÅQs[|*6¹•ˆ†ñ,DxrËýò.2æPh '2æà†spƒGÆÜ`‘1‡¢±XW(çQ–û¸‡jP jPKl¢vÈkÔ2¤hjË-î†Ý’RkÔÔÖvòm­XG@hPG 8nŸøèñ¡ž€ð‰ŒnÉ®PO Eäì ÐwÔwi‹ :ˆ¦z]q¬(>Xñãª'@-¨'@½­(>ក|O£[‡œ@kÔèñ‰Ïn­XS€h¨¦€8¡é­•¿+|¨+@x"]Z¥FÄAú…æ·à95ê@ߪ,2ê šÆÄAIÀù-îA£ÒW –(!fGjyr­pcÐD3ÝF4èà¢x‰:ˆCAwa‰!‘‰ó}iVžQ‡aÆ3›âÀ ‚G3›Áã™ÍàÑÌfðhfS4:x4³‘È[´e6ÒW˜ÑÌ·Cbã/"£¬³Õ¨ƒ336ꥰ¼ø¨Ì†h¨Ì†šXÐS±aG¼öá™v]”Ùˆƒ³ Ílä;5íàÑÌFÞ' ñ̦8VÈ[´e6ÒW˜ÑÌ·ð1cÓ‡¦„!M;B%@>|B™™ñ̆ÊcôT,³ ~,³13Ofcz,ø‹?® à7ò•5øWwª%`†œPÕÇ@Ué)#ª¼à›RK •…{¸¨aŒÇ:â`=ÏX´#`Z¼#ÐhG [ÑŽiÕ ;@ì¡:ÔB­à‘Ž n‡|­fÈshÑ›hCDr®°±¢a¦n¤bȨnqPÝqì82ŠE†ºD†fÞadT3@7Š •úàµP3~¥àw’€´G†š@Íì¡šÔB­à‘f nGƒÅ!à ®Ç‰¼H:nðwî3EŠè&uW·ü¿zŸ¿(Q²hqrã·¾ó׉’¥bY¢ä?%Jæß· ©'J.×ÚŠDÉÝ% Ü-Èûî¼³¤LÈI”,¨L}§b÷Å3sæ$-LÎØ]¶`åÐüñ]÷³©§—÷y^üëãÉ¿ýFÁ_Î?Ò2qÇÑV9O_Y´åóiç2ÛséÊöþÜÿíy™¹º«ËËU7W7W•¬,;ÑÛ8þÉ[öŽ›ulã ×l½ü‡æ½õЄýÿP»lÔ–q‰»%ï6ÚòoùgÚÂD×IêŽÃó˜h뾉öH,´u°ð•ÝON]c\õáw;ÆÖM¯=Ùºybóì«·÷Î/¸3YYZÐ{UÕØÎæƒUË»:›Wîõ:[ÚÔ÷y¹aLÏç{2¼]µKk¼鶚·3}íÚÞn/«l/KÝÒp⃢ýúò ·MY¦=X”Ú2nÔ4Ê´Á(žÃpF™v`Q¦ FíÿÞö¹7•¾ºpimáúõ] æe‡¼t²eí•÷׬߷îã¿ß¯ý<¥¥'_qnSmcmËõçžhè^Õ±ÿ½ø²QŨ¹Î”ê6ãé.–Xwñ (¿÷®»ïºËÛ>ï»ÇŠ“^ñpíãkø—Ž–ÖMí*ÚÐÖ¶üÀ÷òW[}³·©ÿ§ëÎüáÕ¢ëȽ]¾g_Áƒ÷$Ëë~\^²æ™kd¯þç5É_œ\vÇŽ#G¯ê¨›²ìŽÒý×M™×úË­ß»±þñ°õ\Wçp{¸ˆëFrâ!²ÿomy/;øYrRéËK“Û~_ûà³ÚsZÓm‡ê+6g3'½Î¬·ÈójêůÓzf£—é­Ïyûr+½Ü Ï;‘ÈÝêÕø%CÞë¹Êœw¯\q¯øeM6÷U/Xá-J{½/ i=þÇÊÁJù¸XQ’KŸðÚý¶!ñ«2¯²7Ý?tk.]ïõÏIW§+Ë~××ûã'—ým¢|çWgÜrSiºjÕèQIt—eQ캮=ÜY±¬Ç®e§^~«áWÖøŒ¹ïæäÚÙµ­E³ï8¾n`óŸ=²ö×k¯ûØã^*}ööÒƒµY爐ޗÍe³ÕC™ÃÝç+OWO;w¾ËÏ—Ÿ×ª§œ;?熚cÍs—ôøÔx¿)8ض±©+5kÊÚ™?zôšÚ‚Âr9/7¶cì';3¯ÍëøŸqvke]fqofq¶¯:3”ɤ3^¶&çyâSdãà©•2×ô¦û»Ÿ*kìžYм§ný¼Ö÷­ÙÞüÌoö_|_gî(_Õ±­¶¶°¨øƒ!£Ã×aZýýcXæEx¢jüÿz¶ó…¾‚Dé|éú“ï ®™_˜Kˆëì‹q 麅V;IÑsrÿÕiÞxÐ-i¶3’xÐ äÝ GÚúÆôÒCËÇM/~²´³ãšË¶ô–mÝñò¼³[‹: zk«ì݃‹{ÏîÊõnÛ—ëQàµy-‡G’)¼®o0÷úÐ Õ?+^×Q0núÂÉ7î5w]>f¢7ªø2ºxuÊ€LþÏjZ>œ}Ä ÐÁðß½ð_s{ß¼îÚÑ£SÉÖ3ë7umþ¿•ïûôlvÅí¿¿èà+Û¿üî×Öôü~i˧Jo]?¶hU·ßöISNû¯QóÆ -ÜP‡–1ÿ*² 71Üù¡åX³§ÿÍq¯M˜y ¾«f8Ýs57ßþ‡Ì&Ö~(Boì‘sO+ÙÏÏž=§Wüëúþ¦¦«ÃŠC´ù:ÁlÿØ1#ŸÞA°¹æHÔÆX{å¹Ô¸¦×¶N,xýõc¿:7ïìÎê;[N½öGîŸÞ›[u.ûgGïÈT‰<ñ=øݨäè¼W3˜6lÈ\ºBbWã–3\¸]lW3 6œ­Õâ:*tW¾8È®3òhpÉèÉ=Ùžc[–>µóæúÔ ©¹-íÝéŠO³•‡³ÝÙÊ¡ö'²5OU¥›žè÷*+ûûåÏžZ=íéë?{ØÊNÎÔ„/ [S§X³DÌëù‘ÕFÞÈhxŠß|êGlß‘kF½:îÎdï ç¾_zvë„Ùc¦µ.î´wgw>²««Ê®?¹ÙÛ¼d þ×Þ¾¾œ÷ùRÿšìûü…ú®6o 7+ç•åºϾ³¢«¢d…èe66M]^>óPÃÑ1“þý@ùß-+/߶ó½%;û$ܤ…lÓùÅe[¸ßaLgÃ÷Eèw˜!s˜è¼tY]xY9öp§å⻬‚?^¿ø/+kÿ?»`øæ+;MYû¤ì4uUvZ‹Ç|¹þ¦7~{Ã-§Ÿ~ÿŠó¥-Å•{[^ôö zÙ¶¶•4ol¾mia]c벇oÙS×ðüóÅ=TXZ>óòÖÇ*ܶ§µcÝÆ_¿}ð‘tn³3·)»Â[Ñؾbûäòm§Ï½;wûøs«¶‡ŠR‡I»¬ E7’¦èÕó´4Ì7˲GÒÒ0Dr×莵¼o‰wèÔÉ'Õ]»¤éyq´5h/«Œ¯ØÓâÝfm=}@|ÕŸ_ÿ¹·÷Å•‹~~óÑE"ëŸÝµy|óŒ€ú8öʸ¯­k(Ð^«½ŽM¬ŸÅ]q|-MË›fp^u6’à4¼{ÿ‡»Z¿Rþ“ÒŽ/u|²ïÊ_&Ë[‹ZËo¸ê[ízúÖÓ‹?ü·‚ô¤l{.ÝSÓ3Ð#§HØâ\¶õ¦WÔ”­xüù·¢u ÿT6æÍ¢ùlLbMñk3 Oµ-/<8©õæ­üÅÔ·&XûÏßšËfÒBJ{®åÞ•ÙL³W)ª–äƒOuŸ OC¸2K»8qµq®kÂHW ÞTæÉCr®k#ÉC8åNßôð„Ò±uÓ¯L~åxéŽÝþÜAèzX¨[ÓièÌ .öôz]5½gÓÞæÜ\o³Põlz‰ø9°2”¹šk¼\½×#XÙ¶õC^[î`ßP_¦«¹¦éGÙu•+»÷øŸ{Þ^¾.Å›Ž/+ߺ¼¸áÔ„IÂí/ã`³ãÿÓܤ©å»”LÉÈ…q´ø?®NööözK„²gÎœ9še ›Š±½£;Ãy\ùȇÆò5gñ™ªæþL壵•MÓÚ'6e7µwnÊVw·­T_ÍþWË@{»(Ñ›Ó⣺ߟC"¸šEtõü÷‘¥ïþc}.›«¯îÜ4Ø]¿®¢~}ÓÊŸ˜R¶êÈ̬?°ßllh8Õz´°`Ò„OŠ’t²îOü/Øendstream endobj 6 0 obj 5446 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005749 00000 n 0000007319 00000 n 0000005690 00000 n 0000005551 00000 n 0000000015 00000 n 0000005531 00000 n 0000005813 00000 n 0000005854 00000 n 0000005883 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<1F8947F1323EC9DF87FCF8C661F494EB><1F8947F1323EC9DF87FCF8C661F494EB>] >> startxref 7489 %%EOF ast-8.3.0/sun210_figures/parallel.pdf0000664000175000017500000002431113004147321014273 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí|KŽe;ŒÜ”’)\¿¢Î”$¥Ñj`“_ïY¤˜üzß#%Æunì­Í—«&q’ýû¤ä<8“hžóÔ´Nù¹1Èòt•˜>­WéN¥ÌáÓØëÜØ[ýý)©D'%qjF6¤Á¡x«Aõ,RŒ,i‘ì‘c‹:Ž±Yþ“$o’@ÓýÃDCsòL¤™|åÏó0N“=Ln›óÆ$Ï+ÅÈÓ5”H‰IuŽVÏD*Y)g"å)5u溜:lÔ¡Çûå ˜Eê¸'láõŽÿ˜D³$7£"axr’‘òHšz¨7¶Ñ4)ÂH±Ñ¤ç•Ì:7.®Ï#¡LgõN¨2w¢Æ’´ F›!.êW¤€$êy¤ÄȢΧKÜ5þ“˜ e†™0]ÏXÐ<¡ d½Í„òa&”f‚ω“ó3ÏÛL¨ém&Ôò6jù4"GQC`oã2Êx› VñËLp|™ žrú=ÞfÂnfBo¢X˜@£ §CßV‚ôb[[ƒŠÊýe$ä_ÿþ•r…}Q`VX]‚úÓ-—#Û…ônšÓì“9î–n‹¯õ¸~W¨…+%±ôèßåŸ ó#Å(’¯ {Rk³0µØUu§…fd©* X‹—³j`L™¹ÄŽzCÓ¤sT–Ž”öhXVO>ðyÏZ[ß™ã6Ê}§¾3ØÐïüÖAhê4O5÷X7LBÔ·¹úm!êÚ!´ò˪C=µˆ0i¬ôá÷¤žÉ¡þ¬BúöÒ£ Ë[jÔ vŠö³Æ¶LRò©tõï¼Yø5éX-ÍÌT“šbU5$<ߥCš›3z}»¸÷ ­½bÊ¢ÏFE+j“ln°¾—2M¬ÿ6NÌÖE‰eU°£6·#=`Ñçû©ÚT ƒ­‘ÈòÁLAäÆ\ªç»Uƒ½LJdl¶m(;Ÿ\'£Òê»=ÃÜLVâ `ÐÌ h›wÖòhÚDQÅè¶ úaõ¡ ÿ^`×ä]zC«[œ;)N—§K’Wû~“U‹òï%X`pEÅ꿧ͅu6Šz1RŒ¼H d‚4"³Ysó|&qmÅÏÐAÍAÓú3 X®ÑµQb´k¦WÁHn¥°M€êšÃyJ;VQÁ†u:vŠ)–„FÔ˜%}A¡ÂiKlËøn¢2Y:sÄ$¨'¿SÛƪÌЙ1ÊÛ¿¼ê7•v×oÝΚĚ;1¹ T¸:ÅZq -X³+–¡3ª4/øÀÖmBˆ‹¦3D$‰0Îõ|&Ÿv¾æ¦‹íš»&ì­ÕÏ¥,pà q‰UBÅLü¹Rºª.61u‡æœº?ÔÊï­Q2;5Á} Ò Cï ^:uââ¥côÃV¸W9#f#¶pÉ&´É¬Uˆ°ÛT„À—‘IÈn3†ôê 3±k{³ ÖG÷(…eí-AÍÍõXÇ—ƒa´îš>„œª¢gá´jŸK^ëɶũfiÀø\›ô'dI`4Ÿ‚Ö(ÚjÒÚÛÖxÕvA­^ƒáëqíù]c,Pít9«º?çU)¼¤‰Ÿ, Ëu40ú‹ùUký_A#`Ê”Á.UdÍÎ!OÓA¤Š²÷Êý|.ôgŽß}bÂ!#¡ôKq"ÙzI2Ïm«H¾V?ü®aNmfÚ’4H×ö)Òµ½Eº¶—H×ö)Ò°_ú%ÒG¤·H†H×þéÚn‘ÞH×[¤×K¤ë|‹t—H‘Ü"]ç-Òë%Òë-Ò-½Dº•K¤¶H ºH·üéö|Šôz‰t/‘V·H‘®ãC¤k¿D¾Eú0ÿˆ´×"íP"]ç[¤×‡H·t‹tËG¤õ{‹´ ‹4JÝ"½>Dš­‘V\¤¼Dºaâ lÍ–6·°S=Øšî2ÁàœJÁ¢s"µöˆ¨ÀŒ‘-õ1žÖÉœ“cÊ΂ií ¹a (9ù hòdžÌèIÛ”¶~¹-Ý,»hõ6ÖVÿ";lÜݸîÜž¦ø[½@ÅíNî+L Zç:i[ *…†Æ4òZÙY6 uÄÑÚ¢¬Œn~qJX$³·ØdÖ¿ªRœ§FAl(ÔVtãêâæý ‚]=‡¨b?FÐL–Çe7ãÒ¨·IÞíט'GÚ¶7ÀL œC3r(IBÒ%¬æY3Wõ-J0s'{½Ð²üDÎÊnö•×Ö³«-ˆ€ÉƣʰgÑù=Ž4£æÕ4<”5ª?= JÛhæ<ß00"åÀĬjô„•›ƒŸ€f¾b*t8é®þÚ>Gö©þ$h¼¦¸ÊŸ(Fߥü\{üØvŸºOh]œ*84ÌÊÞ¨‹\¯öªefë]D1ûÙ\u3Y—ïÌH7S÷õìåPÀSŽúífµŽÝ%[DÖÑú¯K´&wĵ‘*bxN¤^ À±ÂÑ’‹«`.ÝnüÖêµKGΪ•C«/}SFÒ~²Â;U“”Ô7F–…¼)4|Û²Þ—©¹1ëÁcV_÷vŠY½°¸Ôƒ?½sÇ:Œ.ÜÛnB»ØÜ„›™Á-§Q&q_Ñ$6±ëÙg°î¦ÿ ùѱ¬´ã7|\WGBˆÏê{š6P¸6b£“$ë‘«[,ÔH±5C¤x¶HLV¹XEw[¬së›õO—Ñ4ÊCÆ電Ю„Mº }É¢|l·¬¥GûLTYµ‰"0«"y^W\Ea½£´í`–hh ß!ã½ôÌq›®r–AÛ XK–y bÎT4ŠÉÍÝVÓY0’ÜVHÑ*ˆÞ+ FRå,P>ьΥ#™%9œ•X/ˆ««fÌ&¸õÀ•þµ`¶è!ýM‚:Ür¤cÏç"Í#Ú®T[/0Ã&Cs»²žÝLtÖµ%d[å|lœt]®‚DEÇ|ëb7¬~‘‡ä|Ôw¨ðO&p¿ØC‘€Ñ>ùTôêY¢Nƒ+Ê{D>Ê):i¡ûû¤`aenè<©š©©Ñg@ôʈûùºzÎM=ùÁ§ ÜdGûü ×’~êÕh«Û‘Ý×ÂImRDƥߔ0—9~ŠÑ˜9ToŒPÛÖº ëçÜ+–yŸ_øÛËöiéªcY“Ó…„ÒœY‹©,DlD5ê;¦+³øžcæ%?£@Çzši^+)Z‰êp3nïõÕ—e¸›ÇEsDíÕÚSÄbÁʻ簺S´º…kéœ-ZõQ I-ŽAÇ,ÎBh‚ë‰ç®úõ—Û3´Y}n¾\øq{l§Yj¨áZÿ×3Ü3E3žÚw:}=e[Á$ÀÎÆCØ)$á‘9“IS2z ÈÅ46ŒQìÝ5+Æ8îg[è:ã\Ʊqè{Ÿ :Ãá[´ê[„8ªÁïíKdJ’‡9ßH¹‘’±{‰ÚŠÑ¦y¬‚¿ªHò¹uë¡©‚²TΠ‡*XÇ2¨H…7“iHéGŠ" EîWG¹sò5†)@1eÒïßÓœWî@ Rd-yÝcùQŸ&”3÷Ty0(/…m¢ áÜ+$â“vÍEÑ¢¢…‹È'R'™gQ(®œªA(‚À;€þìŠNd-uQaOPníŠMÔLwnÃ;7ÚÖX‚I=4?½C(c+åb HK`º,ižØ°D€‚–ag€BLHVßm"Dó«1@‘`ãy zˆA˾ ŠcdÅÖõÀt.ôää€Ã4ïòŽ¡ðž{ŠG( B† o hµ–Tc|‚±ÔLBoËF´DŸñ l œ‚\bÓÛúdàWPMäg}"BÑ4Çu÷‡zÑ]m Q$Ñ aˆÂ Ú1Øæ!ŠÒ¨(VVà˜~/ †(’¼ÎVcv "å-¤e2ŠprÀ™… ÛÒvå°1RÄ8S€ÃDÛYAáìÚ¦tW›°»öþº}ÿ#oñ¸¶uÓd=ág|úÆôòd‘0r$mªàoF*<ëà<–K„Èð¢ŽÓ_8œi¡îÑï¹Ì±Cþ{ôtÒÌ#£dŽ~ô T¸ 8³‡®HKN¾³±²>òTÌ¥|‡\;\ÇKTÄ“>öv$¶ö^G ÷ɸȥ„»ª‹•4IœË×tö…È6§$Ç©`èq@í5S—È:*’煮H­ª~@ªÅ¾# !On“&A=èlÖ~ñ­Ô/™ÜÕ7‰C%'¼Í“dÖ É¢žÂ`E’‡n+x†ÎÔv‚ƒLh«<óÐ"TÑyÌ!6ôÌ'ÙýCæršþôHE 'ô´'lñé)æ)uÝ T®áøoth7SŒf…¦ËÁ³…°z˜bÈ «:ÁÇ(Bõ …b§üBOn¦Í“‹œ’Ø:Ò]ÃÁÍܸтËÚtfë«G(ø{(ˆ<>1a²Žzê,b©ñ ÑlúþkÇ'O¢…ë„~8Ç<<hpy$Ñ•щÁÀMcp‚róÈY57Ù'UHñUoL*9zùÍN€›ÀcúüAJ (z²S¶^Rø \Ù L à¥þOk•I €¸„ºB¸’“;ÓÁ0|¢_®ï¨ÄÈrY=±–Ðe.K§šÆ’ahcz’‚Áس:–Sùú mϸD€— Ú<ÆvÇ¿EÐÑ£‡-ô3Äcü½CBKM"Ì ›Ÿóâ="£ñíD$”ÐH H¡¸>èîÀäQ†àœ®2#&±Üûõl’<<ØÔ¥ óäWnEg2®¹X@ʃ£öWBÆdBJŸºÒ¡Ë ?4z†îÌ3 ÃÞÉ YØ°A»²Bm p±ƒ`$ å>îN¥¬{Q€ß“¡Ðd <ÈŸ!èk”Ÿ7 ª¢Éªã™0ô3è³Á³ä]$¢Ÿ‡ño®•æ#sCöœ~ô“auh ¿•‡¾«0í£û0¨-¡‚6?¢VA¥1FÖèO°B[[ßM›G¿rTž3l“ q—Âô wÞÒÝ…Lm‘·ýl>NÏ Xu, U ²K!ؤdÓŽ9þBi‰ 6U ‘š<‰™±ño ^*ÉØlŒª»167¼8P]:·À&Þ×È<ªcåZn-E[Ábì^Y˜§ïÁµ ë^C›w~Ö~MB¼öPõ[þlsÒ…’áqDÀ³0øEÈC[+ôغsîV¿Ã9‚óÄ…?’Ð17ð›ÀDf@ÈQõ+^¨äË-]écÑÑR¤Î oÙW¶’ðÓÌG‰àòuªç; 7­/ÙÏcÒÊÌqx$™ía N:=î n >:”˜Ä#EëWœvˆ¼:½z¾û:륦¸ |Rœ.yÉ:Kº Üܺs'+¯WQ».]PküÎqÐÆ¡ užþÒ«Sç× Hèó=Ïg>š–uX ÅM`Á'nãh+w'KG–q·ÝÆðeo&$?íL#>Swó$8;ÌÍJ½`½ÜNñ«v8£}–© Ð^§üÆÅþn¢Â½PÓÒ¬~§hëÒ ØÒͼ®òÚb^õ»½ßÇpkU7÷äjû&0)†x¿4´`×yO^À-{ó§Æ¹ÐèݾçàœëùL>e¼æfIn@:yÎæo_~¸æ$ÄMà2ã’qáv%÷Ë“½¯›Àc~šUð7ÞV|Æ톟fœë¯ë2«¶YExÌ*A7«peý6«è0ßfÕF: œ_fÕ-â3·Y5ÓeV l³Jp›UðOo³jæÛ¬šùmVá¼ðeVÍ~™UÛ¬šý2«p÷2«fù0«0˜Ë¬šéeV±¿Ç¬ÜfïçÜfÜM۬⣗Yu˜Ì*¯?Ì*‡2«f~™U Èˬâû çs;f³JÐÍ*”ºÌ*ÄÝ^f[=f•æf•ƒÛ¬úxþý©W*^¤ÒëIã'ú£À!@xœIÿû¤,½ò„eŽÐ=I¯=5ýÉñï/åyöÈ‘üq¯¨!ðˆ÷ávJÕKQÃâ¡Û¼Ûl%¼;Gô2jø‡^Ê>äQü);¬³¯áoÊ!ê¯ÇCƒ*þ„¸=þ˜2<5¥GñšsÅS~v îrÄkb*uRÞSÆÛàŒÑ#;ã=cz Þì”x Ïeµû³¥!Í}?cò~rh>œ§ [¤ ¥×þTƒpÄþ†×ÞD/NõòÔð‡ÏRþ—^äšRídÎô÷]AQ½ˆ;@žÒÇ[ÖÅ>¥¬ö+­åy\íÆ3­'%Í=û¼T¤8wútï´æµ|ÑI×¢“qçPùü²“âïiëxõ´o´fÙjwŽê½ô6Ž÷SwŠ¿°ºkðXwûÖ݋ȽŒ>Æ!ö TÆjz"ŒèŠaç™ÍW’ž\p¢Oûy¼Íý>ÞIYŸüÙ)üÙämþl=úâÏ~o§øÓv›2þôÝnq?Ž·©»s8õ£†Àûẓ2Þüñ§ïΨÚ'"Çî÷xóç~oÓ^Þ76vž½ªoþ¼œèÓêR ‡?‘rø³ÆÜsÑKí”7Î’ü‰”7Ðoב²ÞìyÒ›=Ž/öì"~TÐ[8ÜY¡½‚ý´hŒÉñáÎÎ}Œ>FñâäA‚á] lî<éƒ;'ÌdKýÖn=^nÞÚm§„.;¥ÞÚ­²î|i7¾bw½K-î̼óùì9)ÒMôÆûûһŭÝ@"ÖsíÈ­˜k··v‹”ÐMQC¼@mlí¶{á)»—^Ãç8È<ôª‡¬C»•² ø7öƒÚΟÚÿI¹í.åÌ8Êm§¬Oö|(·Íž­Ü6{^Êmk+·âªi&ÞõŒr â†r â‡r |”ÛNoöÄËŸ{Tí“=žrú=Þ칕Û&ýVn›=›;ÏVnÁžcÚ»té6ÿué¶HÙšl—úÐmÁž£Û‚=oÝÃ:ºm§¬7w\smÊÝ´ Ýæ´Ýðè¶H Íä„æÚcÚº-:±cŽ>z Ÿ£x1çè¶`Î!ÁfÎÖmÎœ—jû—¯ÿŸ7 ’endstream endobj 6 0 obj 8052 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000008347 00000 n 0000009917 00000 n 0000008288 00000 n 0000008157 00000 n 0000000015 00000 n 0000008137 00000 n 0000008411 00000 n 0000008452 00000 n 0000008481 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<8C31516C78DCA5ACBB8033C0649E1F12><8C31516C78DCA5ACBB8033C0649E1F12>] >> startxref 10087 %%EOF ast-8.3.0/sun210_figures/mapping.pdf0000664000175000017500000001751513004147321014142 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\}p]Åu7ØØæǦ¬!Pn;Ó¦CñÓݽw¿‚嘦q]0”´fld! Ç;6 ¶‚-LÒISR7Î4I‹hdb@&#Z°U™¦IÚ™AÁbp°¬h¯TšV²@²t{ÎÙÝ{ï{’ÒªIi-{üÎyûq>~çìÙ½{u_YâûKc¡úTp÷ç aQÈ8Qpw«8**0.dш 1ãD+F"àR;Úð¢@:ÔE–Ñ[ Œ™2NpxYJû¿3¥Ý¬0†ãÄ10bƒc8N¤ð?ø1#†CðÀÏêé-/™ç4¼ìžãuóczÚϺ¥ðé« Í"•FÁXÄ"¸1ÇÑÒšYû"-bA*;Íó| RI“ÚŽÃÂÐÒnÌŒ¶³¢Y,G„Æ©ä9q$‹,Ö3RŽf1³*ZÌâ$ó4‹•Ýs¼n~LOûYÉ,:ئù=ø÷™Büîÿ›¨ÂD÷n)Ü—"ŽñÛxŠÂå9 9ÓV묗çÜSØÜ‹|/œŒ66&¶‘c9 0ëÍàŒdÎ) ³¶)'Šñ®ÂØÒ‚ø0ºB¢1‚dHþH[8ÿøRÚÎ=‡iƒ¤#0Å,íæp4ôðRø^J?B…>n„5“lFy#:C¤m¸ 4†Ïç‡jÀ¡2tD=Yݘr29„å|”qÊ}d\Ž¡ÑH“æ!ô‘×+×Îsиˆ)gƒÆ'ŒYÛy:óOÖÂZ?ÁÓ¹œh9ºÜ=ºÜ;ºÒ9ºÜ7ºÜ5ÙðÖ5¤¿&ÏXý¥É[¤!mcÐ3_àgMߦÌ52u™º&åLrœÆ52ï 9¥kä$×È ×È ×ÈI®‘®‘®‘“\#Ê]#Ê]#*]#Ê]#Ê]#+\Cv9×(g»œk¬íò®‘ù¡œkDeb3•yÍT¦51uVÚ­ài¦ÒäV‘Õ$·¦ÌÚe›d;Z8c¸Z!Íh °I[ÄÜÑv„ŒöÙ&å¸|”ŽàòU:GšÑR)'•ÒP©‡]N+š®Ìgº2Áº6U:•!c*#ÆTŒ˜:^¼c²8ðŽ)¯PÖ.å8´{“øhðFËâÅ›5máÌîGHéО#Êý"ÊÝ"*½"Ê"Ê}R/º2\te´èÊ`ñ>)((©ä^i¢€ƒHŒõ÷Çת×Þìøìλ Õ U¡ú“¼ Õ¿iMÀ Õ×ob…°¶Pý‰ê5k>äM×^[½.X ߬ÙÞ°³ñÞÏA—ë®+¬½>øÍŽ÷oY¸®åèÑžžäð§âÑÝëýÁ½úܼš…ßYÜ bJmÅéxŒÅ¢s’˜R£˜2ž˜R;1Ÿ=ÿªÁ®…K.®ZÙròÝ›±”ãí;{_[¼—þ¨ê¶·^k_öð¶Eø³ôö¾§®o:oÞòTté,Cu?½è’,<#Ñ¥ý;_Þ¿¾kðÎç·Ýºò™ŽR&ã{¯æ\0¾¨ïò˾ô^xü[ýô79562–œJ’Îñ h6AëÀòÍI{²ùø±žm¯×>óÍ ^ù§b×¾±K_¸õ£ð£·-ª¿½ï¡‡^’÷‹JýiRn*øH5s¿(§ÜcGùÀíU-W\œºâW¿ýÎŽ3C}ÝÿyÓWw^üleðÆŽªñ§?œ<ùß`ª®§îOì{kEp&ùâây_ôÒGÆJ¯ySÉŽñ5IúÈ ôšÏ@úÈ8é[»j6.[ü±ë†Æ~òòöÖÞŽ'oþXóÔ2þüƒãƒcbþŠÞ=#½{’=#ã#½gΟxYµ‹£h£§Tüš ÚÃÿ±çv.üòÒ»î_úk×,ß]3¸ÿÄÕóþëàC/>ܺúØ‚ªÝŸT­ßzei¿zyûÚ¿[¿vl㚶Ѻ¶Úë’Ña§Dçü{dcçØHÝÙ¤¶³´sàTmÏöwwÕ=E_Ûv §þ¡—.`õ}íÁÝw|æù;o»ñ¢?™?xWÍÝo^ç5ö# WP¶©iãFŠÿMÜ°l±Þ}ã²—]ØÕßõöW,¨ê_xËW.yò•§?\*õ”’ºöd¨l'©€qßÜ9ž@æíxãóÉÙžÆ]g{êŸy­öÀÅßìûÒæž+ö/ùa¦rÏmžm>wàÕû/¸}ð«uåcÖ«#lü…ž&D‚tœ ª"átìüñtýئº“S'«ö‰†%?|¸ äZ¶ÿÌ{Èy“½ÞÔÔ ‰øèñ“'Ê [º#sš˜•+7OC7©§‘œÏÿB϶cm÷z£±íȉM[ÛT­Æø¨¿à{ß®9ò×TÝZ§8qç¥óËÒV®²Í\.m#!gym›ß"Ánø—x$U<—‘¤âhv#)·KŠ¸ÿÏm”¢(Žçê#¯FÌæì†/Î/z:o̾½RD5á/ýfÉLwz2ûvKRïÜÜ.E*œVô9¹_Š”bseÃéi?7vL‘žö lvo™Â"u°µÀDÄŠ!ì\E\Ôø„† ΋xŒ)D«(ÁÃb˜ªÇ hÆ‹…AõbÄñ¹‹%/j-‹1§ë"±ÐE•q˜¤^ZÁ,ô˜'ã"úšÆø00YwÐnZ¼çr/Ì’2õ©µšDAãÐr@ ÎR̯‹L[-@¢”–Q1T¤„gÀôPœ­žº…(3D«°h8 sS $iz’kVT:¥LH6TÂ?ÕŠA|*yL,㙨¨ñ\Ä™)ÉŠ±d4¼ãS”¶‡™bì›dQrC=´†dAŒÁÖaÞ 4)<‡L–Á>¾£‚Ä*00I#ºTA0¼o ºMã}Ißc{¼ç¥À‚FJvA*g"½·ƒáÉŠx`* ‹Q”swÊ Ùj©'QÔ1+âz™ŽY`‘áˆPø¤“”FÒbñȵÁ‘J…¦0ØØ€]è!£›ÈhÅÖSNlU*ò”Tîj8*$¹$'-Ý÷B£x“¨Z†N43tRT¤Nâ-"5H„78@¢õ"Œ0Xa’8E)ƒ )ÁŸ^TPaÉ” aá#¢×ÂN HЕÆ Ž²a¥*2žâ q¢cCwf × ±¢ñrZäð–×ql;AC G ža) SêH":³ta†SpZ½aCû«3Š"’£§61J m’¬ÈAL(ÖãšS™ÈØK C°±ÎJ O#FŒõ¬o¡ 2ìÁ¬S¾Ç‹oV@QQág¾æS“ûl»RS v(;v3 ,däH;°á)­µ°w‚Òh®lGBŠ×6—§g¤Ò<£Ò ›`¾†=@œA-ÈšäFKÀbàÅ1t³*B«JôhWgÇú¤4Z/$æ[0ì [;‚V*ëb$CLg6!à:p2Š¢h˜ jÑK†ñ4$ÌÔ¬àwI•SócB·e$y Û:dbjŽík Dg!O4jš¶@ÄPúŠ À¢ ‘âZ$µS†Kh`çQL› €8‰óSèHÓi ¼ÙAhãÕœ0Îm÷X“azV‚)¿8iˆ}ŠOfÂhOPt \²q¾VGŠ7 p]();X€Â:Ni2³«©o!¡Ý,£E !%e@b±.µð™Íñ&ƘÑFæ5…‰H=J3 ¾ÆÐ QlT,*91˜ÜÂ(OKÜÓ¨(:ÅäZHA€Æ´e ¦]jEJC\`œ48’AShP,‘€d¤ †K3 íÍš”RJ‡Í-%ârŠ²¡¸K“ã4\¸Ï˜6ld õ0yLyÆŒ¨`òx1vùÉ! ÓÏ·Àâ‚D`CÂÀ­MD$.u-h)–K†…”P²ôèôÉ(ÔJZØ0N#L .(“FdFR"D !G(b@X2N½éYZSrUQA ¢2··qfAAó9 ‚]@k+¡•ì"¢”F]V¹ØÒ©pŸ5–iÒZPù¤A½¸ u8µ·‰Rš¬Ùõ̵ ç.v5$B;{[p–ƒ¯°æÁm`¨<¸ ®äeàÆ¢"nƒµ7)¸‘Ê›Hn\ùsàFÁÊÀíÎÆè¸=eÁmtTn£Y núœ›È Ü`³ÜxY8nŽ·[ËÀÍC+Ï·ÀôìÀMDnKZpC?“7Œl*ÀíôÉà¯M¸Qì ÜDeàÆê¯ Üxí7n²tî9pÓ¸í|΂†çÁMv)7l eÜ ¯ôà¦Ï)¸-eÁM½rà¦qËÁ3çÁMÎóà¶D¸yu çÞÀ@0[Éa%å€KpÃFAÕ;pl! Ü­øá!,?XŽC,i9¾ë”Fµ`AŠX¾…¡B e³„3-µ5)h €Ä‚ÇñE7¡.ÚÊ‹=ƒú±Š¶JŠã°PÉH»q0-s³ á$ÀqqŽ ¿4TióëCܘÓüPÑŽ )Oà>ÀÅ›9 9Ò In_ï­jF¢_±Xô™fè·_àÄØäD6 DÖÐw”$A&›w:ƒ¢Õ én5ƒøÂýUĨj‰á&Ú×É@C¾¹j8°È™\ ÎÒÔÌ87 …LB–çYBat1Ý`’`2ïÁ”a}k 7“(ïA|7&;Éà,²Ç<ÒŽ°G8l¤ÓRŸ:*[[ô2Èï¡«€18a/G®q4öÇ·rò-ðk@¯¤îHàÙJEéYFƒ#a<+ðã ¿°©ÄDžÓÞ3HJ¼¬.Ù$*ÕB_Å)~aåK0,gƒIƒ5¿ ^"!Þñ[åå.ŸyaWIû4ó‚9í Ó‚Ù}$)44Ìéwydj¢ÓÜ Giî<@½iwx):C–«ë Ck\to+!†97èN!穈Fä:¶tTˆû;¤8‡-å)E;j #›í´{‰ŽsçZÔ†Ž_€Ùµˆ£Àœ Ehðêãí|‘·T(k€úJuxŽ—Ò¸l“‰ˆàÇaA´BµFÎã ,n˜"Ÿ;ñþ?ÖøÚÖø@3{P¨iã hû¢Œp¯_À:&€DÚmÔ)†åh<ܳS8ŽŽÀŒ?ñ‚CÜšc͇Ç7¤ƒ°¥@h†û-Üñc~±·‡,Ô‹ ãJ:} Ѳ± í^h­‚±ûTÁ¢ƒ1›_8î¶aÈ0µ9u¨2Œ†§^@ƒ1:ýg<Õˆ­jÆî%fd®íÖ';ODH,×”ئÜą̀ dz¢BÆW¸C“v2OW)¤:Š±Æt^Dª@àÂÎÕL8%®jÀqt‰N3Êõ@Ǹ¦ÙÁ!‘ýLØåäúr w¨Ái`‡Ô´aĶð íêb*€ÆF•ykC+QÊ LÏì9… –vÀíêBØÄM9LÒ.-LO›rã¥W¶HTxheà]C·Xw1ã¾àvãH®ÆÏ€[¡;Rùø°ƒÅ!eV*å”'ì*ט1 4hAD½yD©Åå‰j GÂažkñçÞˆ#u!<™¢EÕÅ ÕHÌE$¿î´ÉøÒ·Ê`¡’‡`TœH3¢íµ´@sÐÃo¬ô¸e´0vÚi:ÅwI÷¾@ù{9ø¼Ëlŧz¦äŒßQþ‘üßþÖÒUï_ò}ã‚uµ{ó/ˆ<òÓ?oN’ñæá¤çÄ{ÕW%ÉGÖuß$éM’‘Ÿþž[1Žê놿;üÄe±ð/ïùì¦þ³ÍŸ»úLšéïÍkŒ¦Öc–Ü+0*³ºÑAÚ©cÔŒ­n¼´­?½íò>p×ö£'Çꎭê¹qü ÇöölJj岉·–t·5õŽ;>¾qCûÄéÑÞ8Ùqxgrü`[óÆžî¯]Õ9|eiý@ÿ-{“‘Ç»“þÆѺ‘¶õ¥RÇ«{;Ú&–z'ï=ÞÑTþÕƒ-ŸZ¸«¥juKÙÕ¨ÜoYÁZ¬~ÁõÌqz=ó‰Û.ÿíÓÇ&-õöO+õ–~|aÿÞÞÍmãý«&`x<kª;}0yz(iZ?ÑÑ´íí]ßþê;IS]GûHûw›¶ö-\¾»¦kÑ`NîÜ|œ6µÅgó•\²ÑP˜M)ÿ,I5¹ë)Ì@Õ=µ¬³úvJ9` Tçs 0EöMsÑïX¡:<¤7ͧ!Ç‘ôJtC®—çØ—Èa—¿(fk!ýe?"6ö±ì ì;îŽcß&Ƕ°{·¿D„Ê·…OQ¾mÖƸ iÇZ6½ÏâP8Éè!8 …‘Lú_á9Ú«ã;éÉÚÀ<öÅ{éƶ·ÌëGÄÄ·ó]+æº5¤-W6”™ü7þ £ËÉendstream endobj 6 0 obj 5617 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:59-07:00 2013-08-20T08:41:59-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005920 00000 n 0000007490 00000 n 0000005861 00000 n 0000005722 00000 n 0000000015 00000 n 0000005702 00000 n 0000005984 00000 n 0000006025 00000 n 0000006054 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<744275B68F836A47CBD68BB0FAFCAAF0><744275B68F836A47CBD68BB0FAFCAAF0>] >> startxref 7660 %%EOF ast-8.3.0/sun210_figures/frontb_bw.pdf0000664000175000017500000020130713004147321014463 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœœ½YŽ-¹²%öŸ£ˆ<‘46ÎЧâC('”ô¡é‹«1úŽÌ¬*àáâ"-öñ†ÎÖšeËþÛWùúUð?ÿ÷¿üüõ¿üïëëÿüÿúoµˆÿh¿÷ó?Öþêµ—¯ÿç¿~ý_ÿ÷_å?b~ýÕ¯ÿíüÿÿú«|ý¯µ§ì¯ZÛüúùÿù<åÈKrƒüHî·äyä(’ä*y¿r+åŽçôAyâ9CÏ|ðœÅëwÁs^³ž³ù®=ÎsZ Ê ²Ú¶÷igëx~´¹E9 ¯ < ?›òyÍiò ¼Ïs¢á½Qñíåó©5¯©ý´'Ÿ_ç8ò.”Ÿø:]ËwµržÙ¯oõÜÛ{§|º»öÉ6´ë¾«Íó®Q$ãÛGã3£œþ]2úsLÉqîä~ž?‹äóè:ÕþXçú©~ôÉÔ{ûùÔ:¶§c\V™”ÏÔÅ1~†¤®ÁgöÓ}ué{;Ú¹¶î=M¯dÈûÜû¨£œ6Ÿ§ûÎçj,ö!ÇÎql{jìð]X”÷úu¥žæ^”®{Ï+O×nÍ¥~äœcåë,>ÍÃ9̽âÌÉóœ3q5oñûÖïçÒh¾þ|K4­»8Û×Èy×ih®³°ø-ç·#{­È^§®Ñ÷6´¡ö3}^ÎëÛ†Ó(í û<¿kŸ©ç?ü îç9ß³W9¼çœgºàtªö¨3üg¼ë'çRÛgŸ9ƒ©½îÜv&H×ވߧöØë—öí3l1·÷ÞÓ†Å5ÕÖé²X•{é:·ÅÒž¼ÎvKÏœxÎâ¾×æÀï“ÏÄ\:û hÏâœ?S×°Ím¼K{u?CÞ‹}&}Kœa e~WTʼ[v<ÓvÖÜ•ën÷šŠùà{kÅ»t.”³l‡äÓeGÆïg‹Á·ïI¹³ýå‚ï]¸¾²ß×]ÅkN?àùg+\Ù?gxñ½œuª?‡d<‡m8[-î­M2®¯Ur‡¬{ô?ÛYçâ=’ñL®ÇOùûtJ—“¹|œÌõã4nï ,9$äñ!ë™ × Ëx×’8™·dœ8ê co¡÷Žs}›ÒÎä9MSÎÎQq¼QÆIÛÔ†'ªf߃S+4ãž3X5ÍzœŠ]£Jí@«ðlDø«ðÈø}yeàwŽö‘qºªûÜæÓõȧ«î=»ì9]¥q@C™EïÅ7Nõçæ©ëwA›˜~×Y‘gø½:qrj¶nôÃêºþ¬¶º¦ž[³fõÊØè«Gã²Ï$< ÚøYj´ž­>”ÜôLh4»?)·÷ú³$Z>§ãÄiY܆sšyž  gié»&NQ;Ú|6Ù’ßrNÎÈolçh“|îmóÉ>9‡k;:Ë»gž}ûöl;ûüœ¢w,Z/=Çè(v+ÇîìÀ;Çôl1-ǺiÇå8'ê̹q4®;gÚ˜5ç·0αóûÔ.…¹×¼Ëâ°óézä‚ÓUóùìLÜ"9·Ï½ZñÜqÏ®¥çàÛ—×Î隶ríàÔÝz&Noïd´iRÔ¦Ïô^ N`¯ÓõÍãŽÍ– ù|;ò™Žgp$ŸyuŽ Ég3â{±[ß‹¬PãÐ P´fW…üH.¸W;:w»ª—;™÷Š‰ÝÚsfž×óäé“\sZÌQ‘õ¼«iïšgZøÄ>ÃÐpbóú´Qk;º<®ß:yÎ<<§·N›Ž[ûÞÀ·x8iCßÂ)t*vœ<¡öt츽è÷‰S½éwœØÒÚΩ…“œñQêpÂkýö‚“_m£–Ñ5'ÏÐ\:ª/N~]sæ0Õ ÈxΠt–N~´Ø":žmøÆ¡çSãNEôÛÐXœ5ýE5îÈgo€¦ šŽ÷+X-T!ãÞ©uZ1¦SãU0ŽSsÛÄ‘urörµ‰r>ã|O³90}r.\¿uº¢ß´ž- §5гU•Ô>N3Ç=åÌ Ÿ„¯× ‰å‘'çêã•Ño÷äÜïiùŒ9þíäüŸŸ¢+WÛ=9iÚ¦-ó=E%kõæÊS´ÀŽ¥ÞÜ`*U('^µjTׂ,iMœ–ÚMON­ªÕa£ú9´]ýØÏÞYÑ çD•~¶÷=QÑ+§iE+¶«vÙ9¯{V$íX­NÚ´[×ÓFÕi€ÕyìX¯Î‘v,7É*†æˆíØ{윴[+6ª¾+µ­$ÚxÒwiâTé» ‹¢ëŽøFë»ßèYŒGWïÄ0›ŽM»´‚!?^ÁlZ­Î¹u­fœÆZmšËš’ñK»c‡ÿâ)Zý_ëš±GÚ·\åõÑIutÂ{üvô´u%wÚº+W¿mÝ´‡µªp žå$6XÑ©3åœÞÞ {‡ÀÉS¤c‡h²—| Gî¹[4ÏCL#ÛÀgçàI.¹BÞ’a'ÛŸsêÜÔ´£@–¦Sd´ÚOu(‡ç#jî4çC%ãôíšPJO‡I®´“µ3Á&·6Wq²uuÁ Ü5Öå¡ÍÌ~+‹6³dh%C;7ºæ4S2Ú0äW*´™§v8ØÆ>íKà _$C;˜: úaöš;ÜY4Üiöí@¶Á>kê,8ï|8í«v;ØÀ:ùëÖÉßµ#òä×îˆö¬­çC‹‘ÆWa¿Ñ@ƒ ûüéz&Oþ9r=ZŸó`nH ¨Ðš mÛ¡ÚߦöQá_;* î=SÐ6¹vß"ÛãÁ Sš®Øä²sžÀ5³ÞºØFÂiPdGÁÂ8S@ÏÇ©¢=³Â¤ÓŒ2´®;*½Q]ó@Sض¯pÂë9ë´?ä—©0=CÚe¥½Ú¦Nh4ÒŽŒß·l3h7¡¾Å^z´öá’v ¶h¨àú:Û¤~Ç7ÊÚ ´Ÿ<°ÿ5Ö8ŒŽv ëá/èn¾½OÿŽk–mB\óÈÆ£Í/[‡¦µƒ 3ÝÚAÅÁšÃ²Çн8¥Ç²= Í‚ûÞ‘KjÓôhºÚÍÔ·Ïuµ€ŠýœüzNEùÿ‡'äóÚ™<ýtZb„_ù¹ö'yZòdËS‘6¤t‘ÅçtŸZ8¥—`ÑåÉ9igŽ«#žST§ ¼Ž>Qá!¬ÞÕà…8²N!ì²öÃÁZ«Nžö$ÓÃÙ¬ÿíX°'›vŽç4Ö €¦…wwØ´Ý;:îw?]uõ¹Ó=Ú‰'OlïÊxŽwnØ«!;§ÒÖ¥';î9É¥«áTñIe£†vÇŠvÚv*èÍâ&϶w;ب±½#ÖôT7zÈ»vzÎ{h—½žÑ{ЮÖÎ/q÷NVéÁ^Úzz°©ÛUyºh¶Ö¡üЮöŽϳg4Ü£hÕ>ôl{ÅÃÞ–¾¸pzOµ—:cæ*´NL•ÎÊYO…24¬¥<éÙ®ºópé9ß²xB%„o¾k`ìì´ÉÕžþ|š®‡ÆôhG ¿ëÄ€W“Ûñ‘aoÔG;çÞæ _aFÔÍuA× Èè+ïÖ$œÁaû{¥v §Aá)}†ùùâ C¦‡\;DÀö+ºZ ' dxž«ï…ý)íàüYcӪɳJÅòLR¶™ZIã<äT>Ú¿±Q;ÐŽOéYlþ¹É¿C%ö,>³¡ 1õœ˜©p™Å§{q*zNbœÅª{Ñ6Ù]géâ´÷»hÏë]8P¸PŽ/n”áQWŸTžêš«PÈ›wÇ3AqòWÉ°ù5—ê[D‹š´Å#Ï´áÕ¶­Óò¨ _tàPÆ©®±€¦vºV}U®ýô ìsy,±m…ÇýyNflïÚ5F° «4 l[ç4Þ9vy7œw¬Ÿ{êbhªâ<‰{Ò¼¬¡ùlCîGĺÓNÃ¥¿Øm ½¶ØSð2×ÅãbQkẄ©t424ÖÑÙîÑ3 굎Ø@UKj¡½š) ^Íœ|GÍàè§`?`_lr—aël:S&Õ.v8É›4f˜8­­‘¿ÊËkÕÙ|‚l/>W0 ¾­ëÛ°Ürnsœ|AQ$b1Îîƒáw´p¶1iy%é—™¾xžóL¦+]CyÛ¹ÐägG=ŒdsvÀ+Ïø†1mŽÇr¢#B&Ð*§Ì–w¼pîÐüå*¸Xaë3í¶–·Gxšbʆ\z´—"†šª:¬y€V/˜­V S)‡ú0Åzユ¤ÀBÎíå 'õ¶‹C³IÑ ˆ]뺎ãJ'þ|jî;÷ÅsîZ>ÐxP(Ëf±V¦í?w˜ú}>ÊõqP®{8êuF²B3tìʇxq•³£Á"8»…d¨óEN½3´„el’ÕîÙvem.œ¨`3–- “$C7§½»9þ~6y¦p<Šâ³9ÒÐ{š§ ¦ü££0GÃáÁ}ä\†‰ã8=àBˆóYiKv6±ÚI,3c `iL袕¿Ÿaµ¹è?¿ûdϯv±ž¦×öÌf©Ø fÍôùæÑÐÃß“ýÇ…ï0ì™-_C¾8 éB/MÙyØÙy†Eþ”³·Ì/a€üêòìB…uˆVŒ¶g7]j ÖQ—Çðq_=Ílçì›|Ž(áY¶Úöœbù4 »#•±æú†Ò,½ª@¤ã`ûú€]± ×Î#­ËÅŽ>Stzc³÷¯@dùZ„•ÓY…]b¿˜¹Â|óÒ;óѪ7üFÝšñÙtº×õuÅÓÏÁu>Sf-"_©™Ÿ—+öœˆÛý{¶’ÓgZéÀÒÉïãMé6ðâ ÙŽÇtûRt½Âu8¥^ÀÅ;e—”3µiïó-‹ÚLd3öi‹àJð9*ÑÔ!j£}ª<©šÔºØH˜>“\`\K ÿ`sà=”§€ª°BRpSTmX7ô¼BÄs9B ŽW\ª@4T’}8Ž¥Ðw¸ä膆WW-Âru5ý G§¦X]œrXÆ~õóYGä‹ #÷?ú›ýqŽñÅÐÏå £ctiXÅRÄ ž™#®+rž Jºõ øÊ^Q¾ªÀXØRëÃE&‘§pÇ’¦ŠåS}…D¾¢ÑÑÆW4Fäž+ê+°Þä}ë0ÔqEM.¬ÂG_AQ_A§ÆkSÛ‡E¶Ëtë+êuÞuX³›ðýþñ“"[ŒE- «E¾aÆ­EBQ+«^ê€Ä¥kÔ”¡ÎÃ\nÀ2S”O€(ì"±/?ŒgZŠsûÅô.§¨µ›\ä—?ô¨§qÅš=ѤµZîµsÚÖWœîá&P¶Åå!`ÌRctÄ}Å™ãI+þŠÃÞ„#ÃŒhrCIÜ9eŽ¸<§èŒ¿âãIgfå·çjS”H¢z’¸_}EÐJ©^G\^MÚx§s<^EMR‹—ÙQEº_‹µ½$›t,Ô¦¼µ‡5¡&ZêM`lM'¶…¦“›EÓI„-¤u,ØXìGÅvCEL›PSL»”UЈšÔ"lcÇì*ÞÜšP/Øò¨ài#lŠpá²& 6M*ƒÚJ[ßÕlϱ ‡Í¸ âØ¢f©_µÕ!À*—6ù6ôA‹€.~°NC´hêWzõ+¦y“R[?ÙYÁeM»Ìž&Ç>$í¡Ž…hC“?Š&]&L>—QÅZd{#*ãYåFˆm+ç0d¡ù ˆš­:by…Í@ &ì /K:@Sà„ìvgx$Õ)6zíA…Áƒ`—CNÔaç0C…é¼…½&›‹ph‘²g8è@[Oö Dv÷0Ì8å6‚+ïD…Ë/tÌÕ!`TÒÒ^çj´°¾öÝ2­º^UËÿIX¬¡­õu¢J6üµ½¶!᯶ r´m(Y¶!Îj+NÇò\˜ßQau¯œcNplX,œ±Åm *)"DÛèÅóMö„b–ìi,ë1 { x,R…Éh€å“&#Ï6<ôˆ~Ø9çƒOÏÌTl"ÊÙ%»Àd}”»‚É÷TAÐÏ? Íå¼m W¼' <,¥5Àﱺ®=o[~îy›t”€-µª`ñçÛd^BÈ‚SÆ1-¾äD t@€Ë³¨Ž¨, O¦^qt•¯©¼bRæATÅ ¡]‰ŠýtžÍùDÃëÏ–ý%TH`™Èóq‚#NåóœþR°2Ç•›$ûNì9c&5Äá”#6e´4ŠŽ Q9:x›R\€B™Å V¿žÞ•_ O[jÄéIÙ]àŒÂ`D-j'f.OwÊÎi`w¦Äù ®DüG¦s,úT:G™W„¨ °ÉvåN`/‘)龚ðÄžI8çsmNœÚ+z;ûeçÃÓù.°550-œñ„y3†~wX b= ³Ô0d Ì€Š X"Ni‚ %dɳÔÈ}úVêkоTš ¼âržv+4í;||Šðu®ipk‰t8Íi†ˆÎ=RÍË™Vjy¤T”óyk:L\aË:Ù£ã6ê£ã¸œ Åúm9¿{ÖqîX¿…óI¡Ä£ã§Åóø×s›ŽcØÖŽc,S…¤;<Û߆x„¿íôΖ–€™Fà­Bº•‚&G\Ž]ôŠà†,&¸ÎöJËTÚ†pŽ.8«U!Îßê¼ØÚ¤1c…´/;Ñ:Ž×³gZ½e°ÉÚ4UÒ*÷[™vȲ_®RQÜ>2†5[üný­öðŽ Q-n Eö°ööƳFBÓ!•“‰M2¡(¶i±>$Ú‘5axK€ÏIGÆïVy±ŽÞ˜^!= *³"; ›ŒìXµi®Á›Q¢êؾªB÷G:ö²šê5+6êàSP\‡ù¨¶ðð»4~¨2ö“tÂabØ6,@éØÿª\WùV5l)žµ:‹P€}(`Ên­ßÛewp©]®ÃWh(J:Š5o8¬Ý?ð]¨‚n õ9“#‡Õsz=¬‰ºl3÷„Ÿt`c«`½ ~b{d|¦ÓJL“æ§RºÀ¦ay'ä¤Ëb^–GÒßý@†¬™N‹Þ;mþÇ­è#A'~ƒ-ƒ‘ž…­™H߃W¨@'úzz* ì4´¬ÅM‹ Ìxåç¹×T#”íx $uÞ÷CÓ×—kHÒNi½dû[›+¿«yöÉFòÐÌ’ñ%ól¹§™,Ò²× %í4Z{Žá£aÚá›rÙá65X¤#ó¯ ÏÐEãA³o1²d/ , ÙèHck+g1d}üÖ pe@ÖÎKχ ¼ÓžŒÀ»'¬ùaœaÇGÉ(T‡ƒ»m;. XZ͉›w²(¶ù¡»K{ížh›¬8:°{†höÊä ¹£à4 Ûø…ÆŒV$¦E49°7hëL½SXµ¦VŸ³K*8Žb££ ½ê°fâ…Raq…Sg$XÕ`2VüQ‘3,s(²ÀÌ¿_17l2§sô¶¼Aاµ B7§Óq ¡tº/ïÝÖw˜æ§ßqïrêò¾©•ÁD–¥´áÁÔJëUˆ (Lƒ‰êxi6É|“xšô»è€R©±FâqŠlcXA©Ý°»)vÁÃ’& [ë‘úƒåDÕ)Sa·õRØuR˜5ÚC‚1EýC$äiÆ•|œ‡rnQ ¡ˆ3Š=­½ãš%³ý _1J!Ÿ}ÀX Ÿh:tAHˆoêÒδFôŶÊÄïG(O])8iåàzµùPG–ÑôàùJ„B¸¶KS`rÕ/š[x¦àôè‚^œœÇàŠ’Ð}]û$Óq{q"#b&iBÑ/‚¸<Áz,a—ÆADøYdNÜÄõÏM3é¶8Ÿ¯X2¹©¸9Ùk˜jÝi‹íw$3ÐN¥-öÜà…éÛ«Bu°ÏºRë™ïÖ¥é4À{Uª|ÝTÿ(ñ«j„ÐJ¯NöB¨V§™PÀ·áùJ䂳¾K{jHÝïNg eQEŒ¿)‡uteX5NJƒ¹Öm©#qeµÁààñʘ¶ø'IÁn8 ¨”;¯˜¸ÍW†áäk»rÜgB£¹rnàe|å·ÍP´^9î7žIÿ!×Ûgò½òóö¶æ+¯qûŠß+÷ÛÿM}(Mäýëç/ò#äˆA7}å~Gºì+;ò_æ„Ž˜fÖ‹J g®f}á X†(·\aGi)¹"«V¡ ›ð~ô"¼wÞ ÈIÑ rb¢ÃvâN§í,ã§òb1ýLfJ]H-34wqÇr8Cº‚B•óîXŸï$œNÔ`’|2 Ý„R:+€,ñ8ù€ ìúF Bfà‘ñ»Áû8I 1J„wÀÎD{'›;¬$}!+˜l¾ üÊBïRâywrNC£yReÁxÛÿûž7QÂÌܳ®ç-Ë´nìm›H „½0÷üÞ„Š9™—²jÕ~e†qEçP˜|à3€0H®Ÿ¨jƒœHo¢ª òI± :'šáåða¤ÐòRÃÑlHc#G!š:ÿ†­¦AÔ‘yž=¦ $´8då1³¤šž„±9e˜MB40Ý5=->úkj“+ià]¦¾jÂÉ  jm¦fAô¶Y©„Ãñ9“I¢€SQ‰I(Ý–®P¼R¼Î@¡\„pÒëÏúÓ ¥31íPŽ'ÂPM¡AZ éèÔϪõ<èmŽÇC0ô†‡;눌€«à­BÎc[vÁ„z{¶¢ÊÒ#Ú–ëjBUJ 7Š:ÓÑ™Èß Se;KŸáU¹iµá¨¬¢Náèäý^†´3}û8ä†vÚ£×"}'ðT¤Cdì/]ioÅ×l&ï˃AƒZ°[èîбœ¤O½ß€ýŽ)ÒšlÌç¦jÉaÏ@¥õÞ«qÑ3¥së]òÞÑ–h‚çô*I6Â.3EpÚÃt8 “ßúªJ{³; ï뺡ڶ ì²Qá‹’^6ÒÆhl‚Üe'LF`ä÷ø]vK<´[ì%¸[1ÂÀë#D•o`Ò½ éÄàôPZ—Ö)áŠSÑ\0n’ ÚĨ;íŠl0aÇuo7Q:°LÉÓ15áAÒq©ËŒÿúEק³úΩâN­â(ôé7r†5#ºrÜ)ÙgNBCË`³iM[E~¼3pÊ ƒ¼âþNêéýÔuB.@²'…üÔ&Bv,³N#×Hœw,£²FW!¥h|#5Žü™Œ‡Ç£dŽ»ð­tuÄc5ÆÔ§å#ª¥JÖKWChu,'!áš•iå= Eå¢S÷Y/Ý ÏëÇI›t/õ¥{áI›/ëNñòý@†_ªÝ°CU<4Ñ4i‘ÕäètRjD ÖnðM4‡éäÁaá´+ZgÕ!J˜<áSÛ:®ň‹;™Ò*˜çi´2a®FÖèÔu4ªœ±5\°öŸEaZ—¬ûÂçÈ:Ö-?óÞ¡ Å*Kœ‘®KÁBÿœdRÈøj¾÷!e‹žI›Ùßxà4ö'äôjXl§#çq*c0MÖS}’p­-ú «Ñší&°OâŠl1Á;'ÀÙEêpÒ=ü©ÂÄ)­ÑpÈAØÓôÊÉ7œT1RúAf¦6!ld²|Mßg|JâôF1öo¿)eU¤F_¦A’ôƒv¯`ÌIÁÜiÑ$9Aý]V< ÌMûã„wÓö µ,  HdÊ"¼^5¼+¸@;}Õa+þ{¥“5°‚XCa^zmÚùè/oNǵ~í û™ü~´'ï:ÏM•–'<¯|ù²âñ¿JvÒ•©­I6²yß?挠£› 4²mˆN )~ïë½ÞßXJÆ.ø|üdô0a børñÑ[êk×±_0ì¤Ç:ÈÖF¨õ/á“\Gà=ú8MærXß9˜ÌDƒÍZçÝ®2$8 &K€^Ø°GÒòhž‡Éˆh€œ*öKhÊò´<Í6)Tºˆ£­\áùVØp¼­ùªB:-ÙLÞâ¦Úi:–£¾óÒbÒ—2‚•y N¼&ÂaL¦ÅEÔ–=_q+«žâf‚·‡mu‚<’&ï­h4mªàR/é/›ó ±Çµe<$/yа­·eR·ò3ºØ„v¦£Ô„ad8hB ¹M“ÀmR‹ê˜}ª×dKq skÏKK {·É7CçnS¢T#µˆ)Mqb$ù¢Íþ¤«]OZë¦*DósŸÞ$W3ÕO'Ūv_zE»Áþ4!ÖÃt…LNDBƒy ž&É©]MÝSI+Ï©cL»1"I׫Øóhì©ÆÑmÕDšXU®¤ÙZ&P±M^àjt’~oT•ÖX.©^>¬=_¤}ŠÇ¯æxuYI¤»±TÛ¼iE¬7Pÿ$&xLŸ‚c^hR¾8ÛŠÁ2Xd¬á&êgðªµ8ÕªbFòcLM¬ÈìãÞÈÕQû%Ô±v_7úBD5ýN!VOï*$˜±<ìU4¬µP•Q›)W(0j%¥¡0ºVýâàu=‰!œÝy¦…C¯ØÉOÌÖoú0M“ëåqœÕ°”G€PÛ2GÎYXÖ<`#š±nÎéÔÓ fKC„Ë@˜vÖ<  õ8âxJM$©¦|mä‰PòÏ*e4Òªj“^R ²Š¤#A šæÄ9“Õo@~)—…Êbæ០Æü6P*L ²HëDÐ/†Iœ ?I‡ƒ_f$©Æã\h2ðÜ\ÿn 6Ó<ºÉ8F5¾œÓßd^Ð’º&m ¿Ù$ÐÀ´M ™©›$ ¸S ¬TÑ”¬Ð9ìnÓáAÁêæDA#´ò^+ð_VºÇ3ÿò••.KÖo¹‰õ¬†z`Ž(dÊdú2Ð,Z¶vÍ\BãµuÂ-tA&A ‘Øm&-󦡀x Á•ÄDê_löaº.’×먉ÏÝ¥œÆM#õ/ÆA8ê5ÂÅ‘MÕÌ#T¥‘‰îHý;X@ÆcQ|ÃOêßAª`]@Ÿú—ü êßAªeëjIÛ*•eX05I/Â6Þ›A•lk_¬ùK.ÍßAˆ¡Þö„•hZ,¡ÝqRoÃg:"Bz+YO/ÊÚÀÉ‘9ìáÀ/h?÷š×°cš“Žžg 'šæ5ñ-Y* +èÉÈqK"(RyJ¤òD‘”ßÖ€Ô1‡]£(M<˜í"1pjS‰§0Er˜=‰P¥ØÈrN‘Dh:8 y•-Å3WƹVu-OPEÈîãÌL˘ž‰p^èZ4]ƒÍ5y7`æµOKi QŠÐµÇ@Ño&þ#}Œ® ú(Ò¥Ð%â];x’RœäÌ“ˆd_] åÝšIøtíCµœ"ÌuYš[$8·§H@¶£™¶I¯ÅvWk“˜Àäæºœçº ;뛬™K…Ç\}a3Ô q“XC0`®\{èFØ»ñÀŒð2ܽ‘°|†YkÉædNX6X±eÈÛ€Ku ²’ÊnÍ{`P™~Œü€hð[õ†J¦æº¯Ý®x õG)é‚›:+ž¥¾nŸÌ %}ÎÛÕÑpòdì ¢Àudý*Ö¦*^‘AÜÁ©Ý}ÎùÆåÏ I09ðVº`[EÒxÉÿ5Šãï÷!õœU:y¡uâÍh¹È /dTFºP@Ì„.Ži!ÂPSë×^íó#š/ÿ¬NAØ}>¹pB(T¼¬Ã†[ ÌÉMVyR*`%PLÖp¶&ÜŠË@Vô+2\Çm¦šHˆr¤Š™ ½ôë=›Ø2íëSô¬Æ ù‡Gê„…u[Þ¡Ó†n!àãòàA3tÝ+äVtç3½;æ°2ý”¨mMf(~N`$OD5ÿ¸Ñ}ð¯8ZÝȲkõ+aW±Ó ŠJ2žXÈBÖ+a9#~gË:ìû<¤q‚pØ85gÙˆ$˜ӚŒEÄ>ÚÓº˜A|½|Î+†ÿPä3ÏÇ”£ ìsNU…z6í@<êY昜q›Î{E@¹ÛÃx.°ƒñlüÆa#Í ]®.ö†¨ð|ì°Dú´±mÇV§ô"?U@=³;꙽Ø)WæÓ"f­ À¦F"ßÔ^AøkíÄþiŸ <±Kkšš#ÙÀpÚyÊ[áL[š´D¨W`ƒ}´ j_L`¯Ä™81ñ3¶]Ãá6Ý×ÊBº¬ë@K(œAøšÃâ›(]€YúÀ㯼9Àíª€ ¯Ø­ÅØ˼ûw±qoÍIÄ[¶P“È(qŽlab¬0dýÔHŒUfab¬.8s}‹mqQž2Ke• %(¬ÎÔñQîcâáÍ°Ú‹’d›üH’¥îXZÙ3fÔ©H'%S‹S:\Q¬®Ù®¡N h(a±ÅM%Ï:U *„ÒØ 1Jÿ£"*Ð 3Kj¦¢•ËRËC»¯Õáߥ®:] µYÐnµ¹’œÁio‚a;¥­Ü[2‚VCj í^¾f'ú WV(U7 .®;ªÁ-¡¼%ù㕘ì$\±jB@¨fÈ©ÔÝú‰bèt 6'&C=iÎœfuÓáäe<j tƒ“” Õ±Õî¦>¯Ï­tÚé€4ô—ÉÎTuêæádj°Ü~2£&ÁO$}§ K^Y%UÉÑNþeTUþè0«ª,tª"áÄл4g`bV§q6&«ÿi„ ~  …Ÿ™t,˜4ì×Ú3ùF–S%I®ft«ÉÏÖ©Ø4šÚœ69ÜÖQL¶Š°7r»9A› 9e &/¾¿%.d]ÉÝ]PçFTˆàЪ«T[Ö0/ÀMŒ©ÃAß¿~ _2ÙN׳SœÉk¦6ÂáDDÑ•R½ –×*±¬7 &ê7_¨¡Rχ¿’¦±¿rÜÚ=)« ¬ï£ônÖ¸ Úòöï=ÝÙ½ËòoÙ£'ÜñÊNh~Ù! &›’ìßwû,û»øówQöw‘äm®W6žW'áR6©«öeÚ}\6¦à;Q@²G•¡‚R?äqÛðø½L¾6‡V¿¡Φ³‚éfg³ÚÔo¤6¸h"U ð L«²½Ó4YÜNPjÖ¶{Ä.GÏ t܃úÌ ­dÖFWb ÅÈS…;é8ûÂÝȪê$5fRˆ…Þ¥w’óDªkÉk?Ÿ<Þy\Ì›4BžS•K!ÏéKÙWÍôÇ_Í~Yˆ•jäN •ª4ÂvtÁ³ºmÝúƒp\±ö0ýÐTµ-‰ù%r#U­°AH-ªªJ.[1ç)ᑳ˜}ÖÜ}OVJ$1®¶=ÒåÊ/5TÈid¯k/$Ë®J“{פ¿âÿÕ`]½žã¦(Ç e±õ+3x-åâÞ ftòaôyN‰#Îy¡WÙ¬aª‡èˆYRQ0êA›I†y4½8' w#¬{g@÷™Ø³ÂæQ‡¢>b–‰T‰)wû¦ˆ³w&ëspܦœð“"ÝÀ5—ˆr¨g»–& ¨ˆžú×f‡LÒœwJÉë„MTdOÐÇ1ÇRT xl¶V*êkˆ£ùœ<2ž'Þ|ÇyªXá·×ð÷ÊØîÜ&*ÐïÁ­¡})¡~-Uf+錇ӥ´d±ZÛÀ$`ŽÅÞnQ€~œÓÛÚøš|”¥!½SþXò*Nð}埿È`5´¡#¶ãF¤¸Pàf¯waøÃÇ„qlv®cãä*÷=cã0f½wcß—ÙCËX…˜Ÿlîo©ÝçÀ‡.¨¡}Š$Äð¤o®wô\¶óú²“lÆE–ÜX¤•KqNvJ×ò@ú»â®0ÔÂx $æ›±’%zt4<ƒ4XW·Á!;|ÂߪÛ&Éc$îŒl“ºÄ¬äO³ÇÖÕtÂïÍx–1lhwFõâ?J%`Á,ÙÎL(p´:È*¤N[…?¶ÎÇÜ'ne…s‡¢ƒP54pÀ»†×.t†Å+-°v’N¨ÌÅ¥¨ú×£fL™äIúxþ ›À9*µŠ$¬ÆJ°Š—Ð §ë»gpxðtUÜŸ4ÄR„.7´ sàáS³S8TÁÓIdf„ (ÂÁãKšfå®ç0{Y£åî¤/ææ£uÁÜ@í¶’FÔe®˜ÅFuo‡‚’¯’ëL Ø¦Oĺœ%‹ gÃj*VWÆ&ÉÏå`wq4Žà÷çÆ“ÕMJá^mU_€¶ÃÕ`J 8TXú|§IØ.3MƒÒÈ/hË ¿>Ý€Y¡Ë@ÿ ³¢Â°Kf ñ/Æ„¡yR…²¾P¼(aØt¡l_œç<4Œ%œzŠä2ºG‰D{_”)Ü»_Ž° yN gò ‡]R8Qøå(¾l±(È BÓ¯?®¬8)4.Ù>¬™H Q>¶§§¬'¹ùr$TÑŠbÝ)Œ ËÍo€i(1™N†”ž¾W Ølý†]¿‘¨ô‹Åò¥ÚÚ(ô¡Ü<”xrÍû•Ñ`8uå/<™ Ãd*Š3÷A§«ì[׃¤H—“2nF.™¨ÌN(·ä¢‹&úuŠãUjX±9¢Bø° ¸à¾$fc#ƒÏÎÈêÆÁ°²z3ÁE»á8¢Š·aê°étí®W#¡°¾é= ;9@FfaE)Pä¨Õç’hGÞ‚îÜ ¤Æq&÷rùMc°Çä©Ð̹Š=Àl¥0:†!ïXujÙº€@æè;³á‰áH Àxf+eÐwbô¡«È¦cvûtˆÅ0ñòTuäØ‘\4*Ðòýþñƒ€øvº¨‰óGÂŒþØLY9eéH«~E$Eö)FER‰8 ËÏØëeK¿|ðúð•6$þO{Š?èvE¯$º§r(—ô뎩æ¥\V-ö¢¯'X’N8¥Ö¦Í$&ÁDñÜLìO˜ª}v¤â´g˜š{³‡öyi9éí·×z07Ñ~L<'}‚ˆ ˜Lƒ”›¦—‡.ß²¨ë¸Ëg÷ÌëáoDå˜~“@®³@{ÈÕhïÈg§”é¤ßœ/ý&)7Õ~QnšÄGdÒÒ³Z¬Éèã&Wt\šÞuÒo†I I¿©oaîf÷»XÚÌï"§¼åA3QÞ~ætÚ-§¿k½¶&ë¦Ûû-ŠNÙ•ÌËÕrd$IÓ—ÅFDÝ™µ,Hüb×˯û­'ÂTöKïÙ®?ZôžIõI¿s•ü¼´ŸozÓ~fe~ „°šƒâµd>ö/‹TýÀ²Ó„¥©ÿIz)C±+›ïŸ”¡*›Á Ë4ÿ¤•¯Ÿ¥5²èGÔLb1­¨ªv¸m$ÕzQ€²ô‡)LYäñ3It£g²~ˆË„Ô„›’}M»õ=DNêz˜>½‹D¥I`:2s°³ÂÉcrOÄ$S¤JöóŸ[ÜCòò½ÈR”ïžUU”Æ”²îNF÷’„Çã2žL °lâQy›Ôocd–+‰S›H–øÞ&€Š L÷í‡æµ©ÒãŽ3å=^­{îQëò˜ê÷·Õ=^¬‚ëùS‰¡Ñ½LõКżmÃ¥a'p¦> ÏU¸ä†©tY)7× ®_–áÇ÷þ ª¹Ú7oðz!Aª× OýùÒí^²TVÐÕÈ”‹éõ»˜þ¢gÂö™¦ä%ÌÖÔÁëÆ:sœFÓa6‘(¼æ˜ ³•³Éؼ¾DÒê=§3ÕI×1¿ÞK‘B¤3ˆ•E€Ðúi.Rô›îú²‰ž‚äE®‚~6‘+¢ÍóÓ¢eQôù“”Ë㱺²çpcI¤b.Y"Éau qMÛg Ú`XoãOôR;ZŠqÙ‹ÚYÑçZSiÆ“p Ž5{Ö»ª ›xª–¬BÌ(pÍ1zŠ‰¡¨Ù9Z=nEÄNrOQýQ/ˆjR)šØÕXÞŽQÁb÷¹\ÆKPK»F¸^Â(ÂäWpKE5¯;Hxªqˆ`èŒ&_iØ^¤dúû㯟¤Œ’Bõ(Ö¢èôÐ&ä6´°²û0î"¨Ú"5®´8RË6§Æ­,Z©&bRŒS6"ùg*FNí¬µ,8œÈWH$–kfQ‘褳JªXÆƤ~·7|fBØö™E\ùQ ÏÈD@ÞãBIäè+ƒüÈ5ƒis:JWU„™”S혠”Ã&BܬŒTˆ—°3–í:>G0ÔÁ Ί¦ñ+§ñµáé|mMAÃÙé"•­+}‚÷ïU:1t—˜.4ˆ¨œ+8M؉¹5mÕ²ŠÌ*”) 8à˜R¦}ºOV5¤Lçƒi¦óa´Ñt>•Å7'Qq¦ï‘tLrgÁÉè“îÌ|…‘¿T#!äA¼(ÄAÁœêÈ?xãìT$A˜ý‡]h¦Ð¤ñU€{åí‚{4œñ‚à–IÓDwÎgÑÒL’Àì³Ïf2¡ÄþÜö𬌺*9$³CÁ´w ¤l.ŠÊù ˆ#^y•Éν L2ý`p#:wúŠél{nÅsœ%ál|ΕsÀ ò :õï¹QQfÊ…SH„\3%²ýŒˆºÚÝTy¯Þ[y¯SÙHrg?*¾ÑÙþ°¬BôB4kï…¬}Ö©Øõíà4ö^L*ŠÍŸŠð˜õ)EÁê´  ° €éÔWré‰cøPÑN"±0ƒa&Wãt’ ‡CΧÆÃçê×þÜkcß'`o,õ‡ \no$jS)Õ‡Ç71 3Û¾¨Ö#Ï¢®ðaÏ€2<Þ&׫lÊ¢NŠP" -W%[&g'ÂÀžEü Å´¡sby`XX>h–¤Å­Åà¶T>–™™KUËÝ5 ò ÚÍ_nm^‚ĪÆP—·ÀÚÈê*—&ÌÀX™u×.÷¹ûÌÇÃÃ쳈#dzoÜüb«M\xзI´7“î&›¯–Ñ&YnBplvM²F²™óÌ 1ƒ/+´'7|à]Ó–ÛpþU°»šK’º =9šM„§uw•%B™³$=’‹”]²"upMz¸•ý-æBÔ®²ªíO2»ò/9 MNÞB;ÉþqôËmHŽÁí$r*:¥[écžîI ¹ ñ60„¿+›\× 4±X4vø™¬«çÛ]É‹ñvkÇ]÷b›yܲ ÀBe9qËEf 5lsT6Õj61Nª ‚ã°¼ö$BŸŠ¼”ëo¤8ÓÿK¨¶E÷Ý›PˆŸ¿ˆ"ÿ%ª÷4ªÞ:¶¿„Ìà!Õ üÆ1bR ƒ5¶üþ‹cžn?1 ì ßØf—Ø ¢°T‚ïÌo&¯2µKŽ#ß‹ÿp4`¶ß™ß ¥ECDujñgâžÜ+ O-¬"Ùg2'œ,ÂÿÎÓÁ7â"HÆœwOæìKIm€ßýÛmÓ lÍdD^|ÿ&„v¸÷·hµ8.…‘÷ª !„Œâ_ž•¥q¿Í£ ÍñG) UÎZ$hðª7fhÀq &f+r”C[hªÿEý‚Ú YÙq‚A8É‹øF‹¦ÿ…h8~ä-6+þ…5PæSîQ5M>I¢5¹Ø¶I¨á/*Úȧ1P $\ü K4žÎÿ`¦ Ê{`Œïvï¹_ŠÏ'q6[@Ù½…‡Vø—B9ÿ¥=:ÿð=ï)ÞYSU<~Ä mþ…À³à*ì’yÖF£bȪ¥D …œßæš…;áGeÕÌwû-Šº@ÖÙ*½YéýVqº@)pÌ*Ö{÷%*Š =ØÁÛ­ˆñ-– ’ªü¨¾¸™Ì¿Å#Wû"÷¹ŸV™?M‡7Ë’Æã¯ÂÛç(Ó)ãi¹Ct›&?VoEhôý ô 1ÇGÂ¥ ËQ.WÖøä@!œË„qŒs˜÷„‰I=Â?|¹NÄBS«ñ›™$nÑÌÖÕ´Éw‰ÀfäEkiÎ :4œ³ ÌȽýþ…ñ!¨4 æ? Ê÷É5‚ÕçšéP÷š#ÿøð&“µ"ÅÀÖŠ™–ù×äQ)=’Uxšù*~ñ… %‘8'3ï|üõó±ëu›2nÚm¨Á³“󇓢‘0£>Ò¿¢7óþ/Ø 9f¾C2½˜<1¬î³êµ'¡®g4ÐP讲õýñ×Ï߸>$ËXP@ohOÂôS–±ÐVîèâô0¢Â²´Rñ‡ÌÙ÷âdp«%ûÞH€˜eõ³Í ¹¸m ~ŒYšñ'W åç;Õø ˺žÉ¢î9Ê.3ÿ‹ç„ܱ~ΠؘóÄ}È`’ûð“ÿ„g© 9’¥‘³ Ê<µìk%ñ_–³>yTj¦Ä¨Ol$Z~ûУåzûÜÆ£åvÇHθß<-íÖ.Õ¸÷æCqÿ´—rŽó§xž`^ÏæýzžˆûeÈž­h§Ððòå”G’‹Ò€­2üÄ]S<7œ(ž±3XXaÖâ>ùà™é Öµ-N›"Tn»?Îmwª ._Ÿd΃A)ÀZE¢­P¢¿øk½ÔŒÞìð/”kõúÝFµUX§bc&Õöò˜Ý™d¿xqÎÜ:3­„|ãhm¯†Õ\бªÌ£^Ìl6½øÌ|…DHRüø‹?øv åì_è®/ɶ6 áuxüÅ»¸z,‘Ãg=ÒÛ»ÎÉûÅãS2¾\hP*_…ø1ôŒš´1o™ÈÅðØ;R»krr¹,ûI>ø@v÷\ïÉ2ú¼TÇ-µö܇‹†Êä6#êÒ‡¯z è^Þ¡óµK,`éDsÌ*Ž¦D„2¹ ¶ËpAªö Ûs÷X‰°;óg~ð­0¶Æ}2D‘mXŸ ”Œ?…oÿz á¹2_&ËáNÿúò$ÛØ:Ð'Ûs…DR&àÊ£¡‰4ãbô”uCWÃtµi0?j+ûä_B%_mdÀðN9±¥Îâ_÷—Ñ+´Q•äeºÛÐ2Eâ’o+Ü{ MýæuÊB½&s2ž…z}608¶É(¿å´`úóäreœ¨4-Wò%àï²2_í5<Óh˜Gì|ñå_”Äöfþ%Å£’©9ÿù7íªë )ˆdêäZê®ÄKôµR¬+H$íÏ…¦ÔÍZöI¥t¦½øÒpnweåà$MZ …³ô2%¡”“¡„#Ñ ¿8‘§šÿ"BZôqH|^ö#z(Â_¨%ÉúvÉsD÷ÅOr£í,ùߌF‘`Oä´]£Çä›,|ÜEôÊɉL‡²~¥¯Øþ®™Ïj¢É*ïS"•l$5mi@hÚ"™Û¾i€zš+.Ñ0D‘dŠ?i…¦ù Ì%¤Wì0sÍ’@ˆj³üp }÷Ktž¿ø’¥F;¾•U!d#ÁžrÛ3íâUºMÿCÎáaLh¸ý £Æ¨·_vŸ‘¸OmhäI´¡ã'–o·!(²²‚ðŽŒ=½˜Gƒv|5 :¹¦ý¦+Á©BÝT•Å’g½,ØpVrà<%9p€%4óͺ|7—冥(Aé‘4Û¿pÛÄå¶Y—Ûæ±4î¿"£ÂR´Ëh3/M½<6ã²×”Ë^3’½¦eë?9kvrÖ°ï”îF,®œ¸Ä‚Ùw¹_NšþrÒlã'Ûb)eû]_ö™çŽÙ^M9Ãt%ï±¢[Ã9or™Y’³‰ Öf”Ù䯅øI#Ó´¬Âf掹SšU]Ñl›?lÙÞ¹>T!%p~ úɳ̵ŸG5Ž”ùPJkÄžbvdue5—jÌ7‹¼4WDcb(_ñIìH‚ˆ5˜šl.Û¼g µ¹Æ¶¬fçÉVuxBÍ Új.à_¤,ÛdpÁèE2±,ïÙÁ¤DÇ«‰ë×µ´ªe,~ªúLu\ÿ`Wa€YHTX’—‡$~zÊ\*ßwž~ô¹vB3Š–Î#W1ûE“ò˜íž½äFnX>"V·L·`þñ#e¾Ûa@À‰!$)N×úE~2LCù›ñä1½% Õš$¡uƒUqžŒD¾BW“Ø‘Å"ñƒÅä ¢t@zþͬ (´ å"ÌæÔ]–ÐÈŠýtÕކ܉PÂ]¿÷ƒŽä4ÛÜÄâ  WóG£šFÒAÚ”(ÈØ‘‹ 1•eì,²wÄ~ô‹Wä1Éy` ÖÃÐÖã’Ãç‹]e …®¹úàO~ Ï]ÝùF[RÀ²ß!ÓéJ1Ðmh-ʺ„ų›]üc‚0âD’íÉÊ´—ô£%Fö7ÓÇÈ -æpÛ|fÍÙêrÜŠ’ q´æÎÒ3wHæ>*¬äo¶쎉×ÙG[ߢ¬aZužª^5ð·ÝPÃßØ7XøPò/Æ ŸÂ¤šeÃ2KÝ[&³†dŠ‡eºn$ÿbÐ`áCµá“5ã)YV(™2,¯t=±Ÿ™ý“CØ&èaü“X0œ£O$þÍ×™/ˆÁ•,¶ á±Äp!,—.„Ç"«…°•dÇ3×L‰ÉÂ8­Oö 2V75Ë:%K…Ú@–ŠäÀ)õ¼xènÜØËF‘üz×?9'ÌKñÉ3An }—¸%Œ9+§k µYæ– o„ÚùOÞ?gfé­ä‡P{Ä Ñ^Ù…Å¡{Å 1_YkÁ<í•ÍH"Nˆõʉÿ&'D¼²ÇHœã•ÝŸ¿x ›Ãc2‡x¾²ÛL–̾^ÙóJåC^÷S8.9}ÊëöUâÇ[œÒò¼ý¼Í5BŠl·ó“¯b´[ÌR¹#oúºÍƒýjÌí>W€î3ÞõÈYâÔ€_|L)sû;ñqç¤ g"E¸9€´óÅœ"¬˜’¸䀷;ÿ[ñ:úäÛàôZ@ÀßB:qKc†¹×žé<ÚH йÏ%æ©ßùÉç ÉG®BâÍ®ÜP¥&™nºðžPYÝG¿#ü]{À‚ £¾ø}šY“> ˆ~üõ£¬Uó!v-'·ËÿÞ“ˆ½³¾Ow§lΘøÅNò°D©ïIè®R§5yŠp¯y–DU+ÔèbÿÞ³~9‘\è7û iÍœQ´y}:Í~‘ÛTl›wnòæºl+Íeíâ•!`sI‰¨^ïúdWaí¡ÌiÁ»ÜÌ+Ëò¯¸^+’%P›Ñ°AÓ\ÏD :O!ÖErFÌ'{ ÃÓîøÂy7˜eÎ!¼"\Ž3K8Qrg5gŽT–Õ `¡€äwú`‡aIÖ<Ù ËŪÏKM‚Vo*§Ò¡$´p9]ø/œBÆI£ß1ÉÈûÍ>ƒÐb˜ó s@þ ^XLÀZ ²SE€H&Qô(ÞÂÚ óæÃX›3ê» ÆÚ§+¯ 0婉)±ÃÑß|ê X¡9†¸A3¯²,•[˜ekÍë“='Èèl]îriâåð(£ qµÀÖv–‹G×ùoM‘Èÿá<®ËÎÓA÷ÖÌOUh“¹Ÿ1v>ùaú$µS×X?ô$ %à\. ÔXäD÷6^£{ ùÒ¸#ŠÞ2ƒòƒ=ê!/Žæ›M¡"Ø y"¤Mçob΋;'€5´ÉœÎXaè6]ùè“J™,º—¥®“¾“×è^ìɦêD$ÆÙ(,óÓlü²~œ‚71ß,Ò–6Swþb¹"Çúœîäi¯@'”CÏÄœ7×'JSýfî!˜ÑtIwf»$ËêúçG¾L[¿Y·ˆa¢í÷ã2»¦H¦—·º”%Êm7–+ð"c_sŸÛwˆÿŒ[|ˆÿª ]¼—t½FÂç‹…ˆ}‡GT(–ÏcìÈÎâï†s£ Ž60sÈñf)%‡~MÈㆾ³v¨^]t¸Î1)„,8*ºhceuâçCæïjCáïjùnŠáè[àÄ?‚¦_ùáïÊLz‡ Éå°¡Š½2Ü}ò÷)ðIEäÉN™¿;#j~Èü]ú ØRídùDË¿«­½r].Nþò” WûK»2ðØ<´)Ç+?ü}HŽWf¼¸:+ëSæ5ÊÐre,ëSAE!×cdè{›Ÿ2!ñJ=à3S~¡òßåXß^÷™–úGÁ¼l3{Ræ¸Tg}}ÊúJÃü•ËífJ^¹Ü>¬„ë§\nŸWÎ=É…sÏÅßö õ/œ{Ó¢À¼äµï(,bd™}åÌ3ö•æÐM¯wî‚xˬæ¼-œo)·;· ç›æ?€o¹. ÓRR®wí€Î"×³ß Ú¬ ´ý-¹NYþÖkY\’FÁÑäµO”÷–}É4¼‡°6œ÷– Ä{ëÈx/¢Ì{TÝL½‚0iã“XÔâ€÷öH>Kï“ŒŠGÖÌå^êZ8ÜK3ˆÎ½WqøgæþÌÒ9Þ·~÷~N¬¼÷|Fè}Бè3‚A|Ÿd.ò Ã8¿³<+S·P®Ì…«@}xv3öðì0+TϬo:3 ]Æ\-ÂB\/‰Ù¢Ýh…{ú)I!!ŒeL b\Ji®Ì:­LŸ‘¾FXD¸î0Sfe"iB¬¬²„¾2Œ‚§qhAª2C1nö*É€ÃÐÞUù»îåùèBˆL«1ò¢”›¢59o];˜óVø¢Éy+LÆä¼uí^ÎÛ䈟Áƒ,”͇e˜ÿHnÅÉï_?)_ÿ2>þeÿú—ýþËõâD4¼ÿ²ï;ß«ÄŒ¡–Ú1²Íù×ýóO´—‡YÜòš'#ïο~,›•Ù ]2¢æòéHþdÍFLÉÔвõ÷Ç_?)Ëói> õ¯84Ê+¯'ïž™²bYžk³kè}¬‰­lx±hÔ¼;ÿú¹<zù2’Sƒøš{‡ÿúIÆ ·Š óƒ cçù×å-¯j§5R}7ýþí•ãÎ ÿõ“òúõ/ëã_’‹cfr_Åúê?){U«NÕùçU­•iíó_F¶¾9*ˆ¯jÍcKy–÷Ûù×OÊæÕ`u›çöukn;ÉmK}ûº)!ÊrõÝ‘¼·Á&Ni˽¾cË¿~R%gFzM;«¾%gËLoç÷Ç_?—M$r²Y|z”äí5ˈGSŒ#ùÔüë'eó¡Àzëq×b3ïä±r½ºt,×±ùJ¼ö@?ù/ë_® ò³m$舨»ÄßûWþ‹(¹È*’I±ýb2; k½ûzD!ÛzåÈ7ä_?)›C‰\CŠÀ‰\Í"Yߊš>U¶pòÅ+/ï"÷¯ŸËH¤> á0 åd$bÔS=‹Èñ0£LJM¤¼.C>ÜÔU~¯ï¿~Rö8þƒ·ÈãHÙ+/wj}³»žþÞwLÿ媖\¾Û\ËÞy ½°3¿È^XË=Ÿšý\æšžýÔ\µ@²Ù¦Äwݲ÷›Y%kec´šà.ÉnÓr„ü×OÊŠÿ‡*:>9kì½´\ï,kŽ?½…æË¢Üò b»Y9_æ2âÔœÓÍ,S¾{ýË“bfÂe– T¤ÄòÈ«ü×½Êß݉8P?í¨1•¬¸›ÙÀôE, æè, ¬6‰%Lm„¹Õ9×Vþõ“²ytX¢Xg˜yÅÆ++âDtb0ªŽH6׹ǤsY?Í!$9[‘ý¤œ eë""ÄV¦¸™Ëô6¤Û^æ2"%â•[º»—߶•H÷sù‹JÞѦ9Ê(»Ý93þy÷¼U’åèɯkF$XÞÙö ³—ì–,tÂ÷Ç_?êcfy»ïÛòèRöœf²arÀÕd­·l^6–‰–³Ä%Ô-÷|3Ù–VË9Ù–Ùá({…wqyw…×q™¥Š²Gç½~~½\JÄ÷ QšÍc´oêWÂ:µÿæÛkd —þÌàÍÜQ’så_?–ûv]ÇeÍÜ×?d=•h¯1úÅ+{e£¬]ÓLó•½g0QÎìZJ¾ËÖå_?)w?‰)}~ñJû•=?™>èy+þÀö!«sòÛ0Í*x‚Í3‰;\ !åžw7ùÿ~7eÏbF&<‹éE6G!äÇ|ˆâêz²gÚcM@rÏžlò¶°‡›ñ6’[ÎÏüëçÊw¬Ú㙎xÓíC^9æ/€­½¾²Ùá¥ÆmMÉT)ïœí1ŠgšŠ•}_ž°‘sûå ûuë²J×[eVæYÉQ/¤P}^”Q5ò„rV¹a½+£’fà§ì{?Y/kRç§ìyxÿ"yA\ìžx2'g¦0,‹˜>½¸sSqÜÂÈhË3ÇÙŒRÓh¤œ« žõ"4f[”¸ø¼ø¨Ée*ó#šK˜¼]‰Íý|j].¸ñc²¯’¬'©tv2*2iz¾²Ö s‰è6òø/öŽËŒ^.&9yÿú1–ÙF—ç~^YÚ1ãë%Ñ}L¬Y¯ll£¸—CD뤹J6~“¥I²†Ùs1æ–gdÙh㣙Î~׿ÿú¹²GÄû‚QŒ$þÒŽ^. ßþ6¼/·)¹æ»“¿osL[nù6Óýãm˜oÏ8&mÙH2”­ÛÛ—SÄd%Ç*ÜK–WŽg”ÄIâkÔK–g΋p¿0&U]§RòÇ,$U¼gaKŠ™5«Aþºƒ´ÝºuHÍë; •b‡Û/ÖQ›Â÷ûÇOò}2™9÷DOzkÁèG¢AþíË»ИÞ$$êaÕá ÑÜÉ@xgõ¡T;ù%ëL’¨†‰>É1ðýñ×Ï• D-Y&Gé†ß…­»IKµÌIZšpRt°Ë”RöÒ& —<ÂN5K„ÎK„ŠVDÍdÊ‘-Š,Šp]Í–FB!Þ¿ƒb€âhšÚŽÃ ÖUÁëöÊÓÃ…Ö%À­óAyìÒÈT²+‚,5´#‹È½½%N+$+QZÕb•J¢0• 6jMA2¡> 6.^JúqEVA!#^‹éX\vgæJ7ƒÄÈ©à?Ð[È×qÅÙºÍéÀâ³Öƒ0&Vƒ$‘ *=µ}½'Ç-þ‹áÞFUC4¨Ú‹Îƒ†ÎS|ÇrÍ‹¢¦çý÷UèúçÉ×F5ž˜õûöm$+³¿òÎO2^†_‰½®Ì¾»ýeF]ËÆa#~Ùs|™vÅð›5q±'>[ò|‡ŸEß=þaTvyÙx9"«è’û3Ë$¸zþå©(ôÔéÀ¾ÿI‹´.ÍA„•Uñýþ«Ïô¶†m>ë @tõã³.ƒ˜QFڌĠãpIdd‰I#Çr88Æ+ê#AÇáŠÉ`’{ Ž‹ÇÅO?†7CÜÙbÿñ#¸µí rsÈ ËU¥«Éf,?Ia¥Éüô«ôJ4ÅÌÆlKØ2Bc¢eè'™-»_7Sìg¶!Œ¦¿c{Ç$ì?)äH–·Q cß‹R<çŽäNæDs÷Pvbc´§‡Ì¨-û¸%³¿>G¤'sì·Õ‹lm,Òm¦{ÕÊÐ#ÏŒ]FŽŸÕâ²®Øö…[°h(7¸Lô–ØðBÎ?ðäGk£‚¾gÔ=;(ò¸Z7EÏA£¢—ôptBÓG=/”r²!ò½˜ Ê”+Cmd#Š×É-eÊëMI-¹¹?rÿy7€vvT}KŒ„]¤ðŽü~Ê7éÑÄÕìW³»L\Í^4X=vˆ²«F|È+‡Ë¬Åƒìä²kŒ@“è“T…?ûæ}Âçø#¼»¹á Ï,#¾QB΀ï³t–“HÏÊYYH79f˜.*‡§Dg™îæª-„æ •Á|R9MYp>ýg÷´ôLIûØ€û_IŠŽ¼XuîQï²ÌQ‚„9éH)_^ZÌ–UGy=üK`$Æ}ŠÉùð#WΖ]k٬ȴ–éÍtŒD¦#Hºæ÷›/—Ýb‚iöVD¦&@~ZömD¦åâ½ÏzÇ-‚án\ľ#NøVß]sìµ…þö$ÜÐaî°ÁÖPŒ¯†:`¸´Dg) ×ÙI gDªsΈ¼) ΀†’ üGÁŸ@âœðL‘µP@_XNlµøÜ÷™?Ëi GI_‘³Åü¤¨—€}H`dXñË9Оêº`'ĆÔ<3F²}Ñd!úð’-4}8›ÝßÃÒ|5²‘¡à[݉’{6-œ…¶…èfÞñ¼c½¯”è^—’KŽPô¸CÝxZwÚv®žÙàh…Àç÷ëù6¶“4s7¦SÑOcã Öùš7éÃØq¸é¦×õ™"É Ö|óÌ?]á|y‚RœŽsýkdŸLÏúÓÍÓù8H¨œ¶2L åúQzš<•‘ß¿Û×?gòçï•´ñêMì~Ý­Æ~©Â÷|t#ÜÝŸŽ}Wá76!²|8€a Ññe¦ŸGîö,k¸kI÷ê¾îolª?·w#S”HjïŽ*$ÁïÙÁѽŸÀÈÏ´§üJ½ùlbS”¬Pù”nòýþÁß—õdºŒâ¾UPa_&Ô8ת SMTôKŸqZ¡À.tï –Õœ3›3KÙãÄh…¢øvÙ0§Vö2…TQ”8Ú¿ÌÙÏßa)Ž¢‡¥èºg^ÍÍ€}q8y®'p¡1Ñ샷; ˆ,N@QiåïèÞ'i¯»<œ†E®øá^š,ï9²£Cðöt˜ÿâaA…Ey`°[ ¿²¶W.ÙŠ3 }„äŽeŽ °Œ9©} DÀ¥¬ïv4AHª=tä ³)“¥µàôÙG:U  s_ôr+ÄÌÃ]z´‘L“:*GfIµ2=.#ÉÔî”ÕwÀ–Úñèp2ÚÃtOÖMÕ控»ÜÃs {ûð̺=ÅüvÆËéh0 ~a¿…DÐqf¬gÏÅð>ÙÞ¤–P.§‚]!‹êÁ°½²¿Œ­P>Ž ®Yo-¹$ë=D…*!ÔV0¢q…"!`whRE¿Ë`â4=X΂à$=X™£¹d;9¯à “™ W@¾â<6Tò¬_ÿœw¿ì:Ä‚·»œ_NÐÃû#÷Hsã„>ì€9mag ŒïL Äh ˜;¢·gcŠù]žq„ÖŠù—*9ÏÞ Á“ؽ!Øû×ÜÐìàpš z8’f&¿Ro0äqb†ëf‘OO·²£žˆr¨ÊÜש¡€íšj¸Èùj¸3—(•’gVtdqG½âLÔá|À3ˆW<ÏufàQÃU’…˜i1îü}B~þÎ4Ê!BC"3 kÊD6%’X‡ÄÙÒôXcÔÙŒG„´,„c{® k7¹zro×2ÍëGB~±G]ñ†]Ó [Dæ923Éùù5Êê:#Ú•Šý¡ËB×ç,x†º+ Ù’6Q&5ÅçKLÆ$"20  \F,´3ª‘v"4a±&4áž\Þù¾Å"´Åãë¼cÀµ»ç§g›¿ý 2øÅ ?®áÄ*C)³‚PÏÆÆtíP’ŽÍ ñD{cz×€ÿL‡-É$Î?j¥³¾ØLW"b;ç:ô÷H‚¥ÇÛÿL1õ„k†b\÷èý2ÝÎÆÐ £'U4WA:ùMWo¤ÆqSHþªŸ .+µêª @~¿ ¿»€9Ë[¥øÔäÂÂ*iÌKdIª*+˜@Á›0+§Ûý?%\UÙo&Êš¹2zzïüœÈŒX®ÍŽÉõãlZx‹2ãF†‹°NnƒÎÖå6¨Ù‰ye<_3ë »ÎÇÅtžeŽ¾3¾ˆó‹ÕLôü£Á8ͪ¥ð»ßï¸3¾:»s¼â2aç¯*¸˜ñÚY \:YÊ¥8L,‘pî]q$½4J1…rÛZÊIåqav‚Ê*äÝo !éù‘εàWº ¿Œäcôiί෽òÊ\ ~s-øyεå1æ·Î̯U%Ë,ÖøGæZ„ò$ͯ–_Ã/PÉa×’`2 ®!ƒ¨x0eO¼Ìfsï0ùi æ[IdÑbe²bíjªA_+ûØ;ARÏW¸N<ËzE–·Q6W@þöã°iÿøy¦Nã—W4ómœ!Ì\£”Y©­äC#s"ܳ¿aF;ö„Ë33Ke–Ûöu±3\>:2Âìeú¨?®ì/Л©ræ–âÖóã1!l é¼›c©;g|PÉuÂ5T‰<ï$rË—ø$K ÉcSdÎä?~”³-R¯Pzªû¤y¢|»¡KYØÒå¹@§߶*-VM™)¬2;Ø\§™³½Ë…°Ç“)^jñ•G¦{¹™REÕNlêÛÑk×ÛÓJPy¿€W©^7·-ØJt Y2֠Ùžq°üUv›ÿ`­zwuɾ"Ë«C*…鱓HÇEú,Ž$~ò:HÜ·€¸'Ð??²Ý¬¿pÆï¸O\ÎÖg¬ÔR¾ÿÊ7;Q­U6£>B™ú6Ó:+xßnQÖ¥zK›êÏ+Gf„ªË3Cˆž”ÆÔˆèÜ(Óµ6•è>Ë+› B”Z5ÔDr^J{ì+^q$ï&YœXOh€E†ƒ%"’ì,|Dpêm²–zÒü<‘Á‡²ÛûðÇU+ñÈ+ï̼ý—~ˆ‡ÁöP93íaì s °þå#ëÝ¢’XêŒ+£×#nw˜’ýqeÞÌ-Ü áÎ4±©ŠÄèU¬te(O=$':à[L1X,V"±~׉…òôÍ?~Db*jSi Dcx'Êm3)`ÜèÑ?[Ši²Ù¯Ì‚c%°fRfñ™ö¬³¨LÑ™ÍlVfýÊÐ&íê•ñ̾²ÍÉ?£ÊV³ú︣Ú0{ÃHºYÂ)>ÌæH:‰Ï±tážÍjÃ×+yÏf”–ܵPÌ®ȺúÇs@ËÅ­jXéÉ~Jvúý:Èü5ñ˜€‚“KS ˜„m™KB³$˜¨ýÜOº2—„¦š’ì5ƒIê)ã™:š” ¿LˆáV«u¢cã˜QÆk‚”!êu2†HdòšÞ™‰&ñ¹" ”©…¤×ÒGŒõŠ ÒgNòNIì¦þÛØrªÃþ÷%P·<˜hi(‘‘Á¿ØÉ!¼³ÒûʬÀW²åazQ ¤Œ‘Ñj VÚÓ"#ñ•Ñ‹:)YLVEÇßÑfKYÊY¾äFþ<^Ï‚ÐÚQY'Z;*KI§8“šAÕfdä[¥ˆTEõ ¸’t³j^Š`¯S¯€ØGnŒlõ" Ï]<ô%{Ñ­¦ûžÍFED=©QyÕ Ðð”Y(wK# yŠ*²Á¯<²ª$›ÛŸÚꇌ{Õ1hµ«&¾-U똺JMD,•|¯ˆ,§DæCSœñŠÃLö<Õ}-uŠÛEû¢‘yGߌ„¯Y+þŸ#ûëw˜[^Y4/T†íc°É $o™[øʬ¶Y³!ÄQ`ïyeÉWžc©±ð¨TþÛ·©Œº­”ÝØ£([KR967>dt€Ì2øìd,Ÿ2D§Lc9Pí:hô+»ul/ëPÍ<Öëb‘Ø_§úP´îAŽá‡ °h¹H‘ƒ¤Â)â6Pþ¯FƨöoÒ §ˆw~ñºuŒg³y˜å•#+Ãò9¡Äö·{六]ñG_AÙŸA8ƒ¿ƒpÈ+»|I¹U¾( ×Ò¦yJä¼äqAü_q¸¨¡½¢~%íÿW,`eVñ6Üñ¹í „oaݦ–DVÓå+_™€Ÿ|iö–o}eÖ‰|o/&|kãC¦—cgƒÜ“¬DIšq6ˆ9 |ÉÐåÕÔ[Ոɾâv©ÖÏV-n¯¯Ø\ê! ³‰Ôã‡ûjxúÝ”ýò^|‹âèÄë_™÷Öl@3G€Ûô•Ÿ,WÌ–uÂ~A­(*‚F ¯ºuB‚µéd‹ª´›Å¬‹!Æ=¢ªf±¹@I”ÞoǺ»ÝMu–tÍí€ì˜Û@½Øš›ÙZr¤ºa¯¼³’3›ÖE^϶½rË Ïߪ–ùê »#I)ó×p© ÊSÊR(ûÜjJBŠõÞÓuZ«¥ôÛ§% ®ø„Æýè©]TÐ|nW<>¹:ÛȈ^¡G¾Óõ¬ßžÒÀ\|>*‘-^(pF‰Ø?Jgº¥´¾D™¦:”Ô7÷‰dÃå3›d>m›ê—@Û†Þ÷î•1Z.L >Ôg³Èø^Õž¾ýÃ7ª:5gA‹~Ž…ôÎ3]÷Ü$a©§¢|›Þ«Ñ·  UYêÄ’ŠŸÊºá–á/.›Òúû½Ù·mÄ…ºu]‰,ïtB‰P3˜Å©~@§z¶sJçKy?°¾zL¶”P‚MÒóå€Ì¯<œ3úrÜ×EΧ]™}»î›»ÒjØFË$ä<#):NDÕò]’ù+Ê•ñ¾6®„Ø9%ÔùT§Iê™…g#ï¢ìûºˆËyg/š}+½§Ì–ö¶ÄL¤xh`ÄRa&pä¸r9¶;=A_ôÞ#2"æwÑ1{˜ñ?~šJV´‡£™2ûÌâs¶-"HùLbOù:–)Ñ[K‰>VJÔ $E¶]ßsŸHÄ;ŸY%ó©ý«ga"D_²^Ñè2oùÆûùí|Ãd2)Ÿ² =T˜’v~‡¾M­Â]=â]·UÙÚûä®Ã•ü¯=ë$åݺ &î)“DϸB”·’·ÉíüÇ“qW>U³»nV”ï:®ùËß"–TåçIò]#:¯uk^Ùq¢³ÆzHþ£RRÌgø#êËj$3a™ô•nÎ]«VÜ+»ÉoééRËø¸b ÷ýÙ.ÝÍc™÷B…á¸i"z>Tֻݞ{O‡fÇšÙ[ò‘YvW)Èå¶$[ø·7v& êWÈ÷™ù|ý j5òò³ñyˆÒ?ïmù°êæþ3«2ÞL†ò.u“œAÝUÖòÍ/¸­ÐÝ%ßÌ&ÜßîóéüÐ`èêr¯Æo÷êòëêæ«uÛý-ûÙªàÚUk#Þ¯¸O×ÝG+S±r5ùïí>šYéEÿšý¤î?¿o}ðÞÈD`VËÑåïóŽ:œaÙêûÌ{G>§¸,ïÒ$ Ï3¦jú‹ ¿oésˆùs\…LHåZb:ê’4ÿåi¸'×# ý\Uk¦KwÖÞ·ënø˹ӰŒ‚®¾ëž…‚Ô µìÞûF¹+ö`î0oK²…¼›å8 ØîÔ¿HkRëXHA­PËî=¹ãÎå±ûÿå¹»žóÊëî€hÞmo~‡žÄ°5ŸÃð:®`Æä^ž’à*’âîÃxO›Ý•'Oáz4eç|O­ûmºgªê¸c]éÎ⳯!ë"¥õõÖXtkõïs €ô$Ÿß¥ÜsŽw¾r»çb‰÷¼¼_ƒ§’kŽš™æ¤A¸Åú÷s^S'߶jwûžûïÔ]p…´¬‡×Ì«1ðÎWŽÔ*ôFkåÕ<~¿uéZøxQ`‹né¬KW¶<ÚJ»[mšFÊÔñ$jbË׬Ԭø´WŽÔ¾ê–&6õ5WCûUhû"±ÏkjP`‹õ倲[jÒcYîÞu9H—±‹“÷Ûbå%ÛL$Iµ=Á§\y]ûƒU˜l—¼=¡7¨L&ž¢tºú,Ú”†lºúÿ³õ.¹²#K°]ÿŽb·Õ(0þŒPïá64 ¼–¦¯ãfæá»^£€µ­ÖÉdf2™d0ÂÝîZú+ª?*YVìŽ3¾9Åî7sï{±îõGýZ–_ãßàZTÿJ׫øwºföW¿®C!W]ïa+ƒ‡_bKÏûäïžÙæ…ðpSl&‚ºØ/®Ÿ&]c´àtœ¼GÍWVëÕ ?‹¡{\\ª‚ë<à xäàåÃŦ±ê¢~Ã[ì%¼0¼Åê²çÍã3[…Rüº›¢ÇtY¨ÂM` àFAiY®›ÖÂ!¢=èÃ3ç=;Ï×Y·%L5†„¦[ÂS/‹B{ ËàYã2_ƒ)÷{‰Ü›gËf®q´åj‹žáiSãgŦN/»}|d;‡ÄÙZ±ét<å*6ÙŽç1(‰{°žPüCŒ)ê_jÜÿTã‘ØÖ`{kØ–sT9¤†Í=\0ìÆsªT®·ž!;{æÎh{b»™ÁòÄ6£“ƒÕhþÌ!ì2Gô6Äh ÍAÖbs×£Y4¡ãYæyƒÎScÈXÏ­ác<¹†˜ñì0ÅžÅUÑÒBƒ­Ø‚Ãv`'sLéä m¼ÙÜŠuz±¶ ðð7Q§’›c÷ «î„›Èa÷b“  Ñ›dÌ{tð;èƒüe¢Q¡Þn¿   Âí m‘na`“tkÏ<ýVH±y×ÃÇfódžé^¶!xǨýýá\ÿǦ¾óþ ڪɵ¿TÐÇ{ó@k@¼{´â>h{‹€Û4ÞíAWsGÛgøãfóðÔ_Û¦Þ9jƒÎS㘞[7Éðäºy†g?ŒI,Ž ¼¹Ã¶êθ ©Žî¼ÁÄMç$ñ¹‘T8R]ÒýÓäÖ¡aÞÔžzü·¶×°Ö»Íâr´¡mVz·u,¼¡Xlþš£]ñr ¸2_(ª& ýžeAo~þþᜠÂMXm‘nÔb“tÛtØfÉð†/¶Jw3±Y‡q‹høîâ}ÜLÝyÄw¿SY0w0ãÃä#Y]¹‡;Þéý\lŽÚÁ®{ÝhîÉ;àç=ÇcØ,-–[.-ûLéè?‰ûà.šÐP:ÕâëètÓ>>ž¦Ìÿâ4<¸¦à!ƒ§OGÀãëv6^fððÛß(¬ÛâxýÁç6:ÞÝ^O™[jÓ®ø‘÷3áåH9 ÕH99MˆM¤)63.ŠMÊ;Ø5;£ØrĪ׶J`ÓüŽÒÙ ‘oÊóãõ°±mÕ¼ fXqR 6T“]°y‡qÛ‘Ÿ9æÍqº¶ð0ö¢ó9ù_7^Ó1°ÉÁö úèיʭ¶gðýçñÏÛž¡rV=Úâq+Z lš/Tlvg¡6,§Oˆ‡Ö_ÜeŸ V0‘‹?:¬LÌ*-phŠY±éóœq„‚µcòžÓ°ô,š’U8Œ?"ý9Ó¹ gÝ9ŸþUØW…‡κs>‹ð¦hÂQá¬;çæ” gÝí×ßæõÞÑ:«b@Áô)n&Uñ7Ðf9s¾bÁ4;Ç¡¹Åf3s¶ªìšWl‚;'ÉθÃK㌻AKóðÎu6S±Õ§ΰâÇVü<Ù$†§œOç<|z#6\3ð çÓ9§¹oñ×ÇW¢rE³ëÄÍgÑáÅhv]ÑL»×_Žv¼ž¦¹šÅ&’q:gÁ$8îþ¹Ð.œ‰k¶M…â±UŸµ[0ùIØMëEXNöEÕWÎ.6ŽS? Jè:ú4QT‚åäÑ‚¹zŽíL5å½ äqŽ,7‰sg¹MÎè[ÓÞ³Uœƒ‹m Þ>O¦™žØ2ÍŦi–(¶-¸ù¬Ò‰yüªžÝ[m…b8Ë•|9½`¨˜ÇÆß–ÊÚBDŸºŒtœÐ\lúÝÁW3ž‹}Jœ]0±@Ìk㥆”Ü Å îØ ¦¹îg3CyyŒé[œ?NŸsÆù8gœ/ŒóÄùrŸ.B|mœ+ÍÇ9Ô|uœ[Í—wøõ¹Ø|œ£Í—uxÅ,è{ÿ¸þO~Éöýã!&¬qWÁ<6^[ANä/l±&lšÓ_¬.çô£0+çô£^+çô;6|´(%`¹(¤`ò‡*ÐÓ‰g·˜êåøcq(©²ŸO=ÿT½zðˆêçƒ'ò%ñק­QÇ läáè0„—¤.Dx¥êZ„7€ë ø¾Æ„zÞE®5ˆý†[¾BÜóëÐÊ•R±’PXµÊ¥Øù ×¾Lã‰ýõ– |!^û ãÁq–h{ƒ-À€åÑʨR‹/ƒ)˜ŸçèëdJåj/b; løÔ ýeøÜ\/Ä'W÷ <»º áéÕyˆOêÜ}m’¶€WªÜ½Øþrám;|:äñ=T%¼‰ê´TÛY’÷Q›ÎÞÄWƒ›x# .©áÛ <.ù+vÑÆÕ[¥pWP›81)ˆIœƒˆ“^¢¯+;Ÿ ·Ân(säª`„Ÿÿp6­,v%zpŸ…‡ø‡Xn÷Q÷6G˜§öG…Ë ^ÿÇZ·׫e~xÁÞj ­ÒÔ‚ ¯ópóåg|Ñjå„W­OxÙjý„×í ŮݦÄr²ß–Í?ãL?Ó#ÙÒa= ¯ó0dóи2¶ØÔA_E[¬Žc×k²QP½Tˆgè‚5•|c°¦’ÏÖ÷A[H©wtøÍR0€Ï¦îl¾&ïFUúH¼|%^–w²BÑGu¸ÂäÆå/'ºc]K¯mj ñùŒc^ªVL‹ãaÄ&ìqAy±:©}ñyÁ|E~1]‘Ç@›6ÉõÄ(#ËUÆÅƹö¸`:#!0›‘G¦u,¾…¥¹¼ùlüÙb,Dþ¸Z5Ž²·ZMŽÖ*slõY¯}|ZÕW¡ÕÞxZIŒ×¡Æx!ZyŒÍ^¾:¯E«–ñb´²¯F+žñr´:ö9n&6_Úôùsù0Ö:«÷Q ˜kúχÈÇ°›]˜iºÆ,ÙPl’ 9”ç”w(V\ŽEPߘ¥ PÞ˜"ŠMÅdÙˆ‚™˜Üñ­úïÁªRÅnÔ°@ÀygƒP¤A[tÊÄ_7PE°…*–€MTlXpóB Ø4-âG¥e-îÇvjÑ?6TÅ°¥*€MUñ¼ç**€7]Åð®«Þv'ˆ]‘¯æïG9xÆfµlYÓ¢X?݃^ô¢Ø¼L–Â@jÖÊ(V›4ŠÝta]óÚ“lKásüýXXcy‡^ÚãõXŠµrd•TæeíæeETâz7Ëøa‡öó2üéPZDϧ’#xB•"Á3ªD žR¥Kðœ*i‚'U©Zm:Ö‘±™§,ÚbóNYqÆf² J³6KfÁš‚64TÚÆ?!<‹•AÁ×Ù}YµÈjϲ”‘Íöd}#›ëÉ¢G6Ó“•¬&Ë#ÙŒ[Ÿ± ñ,¤äÛïÏ‚š>|•ýÙ¨ê4ºžHE‚6j:­§RI!Ôc¥¡"N¸¼G O½!v¡Áâ6¨åÇš7…jV×;¦ 9ejÖÖ{¦z:ö¦©ÌÎfÛN¹š´³Ý¹USà ›[ËÂL6³–Õšl/÷ «7ǺNû{²ZÁ¬µmæ%®Ômì—µ¢l. Hù'…çû»OMä³ù¯¬0fci,;fs_Y‹Ì*³@™Íeղݕ2ó­öGÄze>¤ fÙcªŽÖF'>B=U·ÐהŸìqU£ …ÝXºk£šS]zCTèkãB£U½%*:µQ£ Wˆ;JTm^Ƚ-*hµQŸ —…Ä´BèÚÓRnåp'Zö`ÂÜdü”çãƒý=<ðpl¥¦YnÍ:"²›u²0›Õ™fµ6Žžþ©àùlâ¦øZ‰_ù³Æ¬¬ü‡Â؃9C¸^´î ¬&hMÁYbÐ*û²Ëº¿¬YæÓ¨ÔÀ²ž=‘ ã¡E,ëåÙS©Œž=—ªë¡9‹îÙ³©Z:βˆ›½sªífoJ¾±öw[;¶²@ÜFÝ©Çß>•“C‹[V™Û(#¦…†×Þ—r+»x›oneV&—u8­‹sÚœfVì´±*–ñ´ù̬íi³ÃÙcËf‡³ô§KƒÚ¨»qù+ñçÚj>á).yþøðô*@iϯº”/KT6mªX¢O/‹[Ú3«æå‹âœømµçVUÌ#(}é}T%F"÷. ¼p—Ãp ÷ÃùzÅÇã5ø½±÷Uõ!Q>Ð *^{eÎëPR^µUc S›Gκ¦Ög‰ÅN­½0¯ü3²Ç±^Î k­+ç‚ð£aÅ™9.`sÀYx×f€³¯¬±D¯ÍŒçE¡ÍŒg1_ëŲ§6ŠÆZ¨oñ©V‘™US­[{ùkòíjl¾‡2m,Rû¢Ö-¿l(ûÖ@½1þLJ-UíÙ…twѶªR틼۷VuP_”ê|m¯ª¦Ú«˜ªmqc¿õ2ž­w_UXííWqVá«Be]Ñê™Õ^ÏÌWý¨±• f™âujûgõË´:ÈøÚœ}+¶™ü¬UlóûYª˜d︲°Ç¶u¼fb{–)¶GåxšÞ°h·ÍšgÍn{~–ì¶}…»Ix<+úŽï·Í¹÷rÝ6ÿÅ%Êï ’«5Ê´±µ=¬ÊPÛ³6¶eC'j¤&âki›ªÔh[íu¦Ï^ac£¶…ÂÅ8k[¨[ŒS9{ƒTxyapy,½©*Á,ä[½¼è2êñ±æòbiå¢OM—Ï®üû½ðjåömb±rëÎÍZå$<>fãá½Aurl J–ãÁû£2å¶Ö‚UÊí{Å"å ¾+ÍK”Ûpk÷[¿f–î·ã‡Wî·#Ë+fëXÈZü ³ëð8V²G,ß"+ØÎ÷í×ã \<HUäí‘T\µÛXsÞ¡ñþ–Z°*½Ð7UõìÑ6œeîíE©t:Öœ°¢:Tî­ýñšëBíþLJ·REÖê­—¢7]%Öí“P…ut8oú̺×Z'â|öi<É󨟈¯ãﶰ ýä±7ý ²a-8ab£2û e“Þ}Dö,öc¼ñ-²hvä°Æ–lÓ1mÑ9 ¼ û™g—ûégë;`?ù÷ É&!$<Êi|`?Åì†`EºÙ"Á_§o “ssÔ¶×ÙµÂ6CM+„|³Î¶O(lÕ˜b¾§_Åd=œ¡-kì\7Y@iÄoÏD-%îø¨¥Ôýchlf‡Nò¼%-\úLÔ¹«€ØÐèÙça•Ôôàüñ ϧ¤~ öÆ45@álÄ?ºßÿ¿¨?ŠérÖ„é²;Šx±9 Ôßï#[£Ø9/;£Ø9/£Ø9/û¢€p$³^ÅìŠ2GQ'"åïc± ™Ñ{"ˆÙ¸/cçïl,dçô;±­&bß!~­çiVôûqZA-{ 5°v=¨ZßØc©#ç'3úç ÖÛêØV76k³—¢Æ;©­./(rÈæ/öF5vu´w¯ùÔ¤óÇ'ÜÞjõ}™è1„RáÖ'¥¦/öñ©ç‹}¦jùb´:¾ñsx¾7xj[AξIvªæJ³žžKKp2±§ÏB¾›Eíœlå{<‘ðHú$ÿõ\·h²ë\uhš\ ]ñ´X.ͽ rð‹më꺆^lºFäÞûœ–kXÆŽkB<Øóx¿µ†iº=ØIÍ.E•¿ÿ+k½©¨û—pé±Õûk¢Í?FâÔÖ©ñ×ÄÍj¾—n@7½ÔÓÏëüñ9n½1ê5qŸ©ÐßZµš²7\¨ìsnì•hŸ³zTyÌCÃ!¾µõ4½"ö¢\-²ì“>½ ®¯[Êf‹£jý@ã<¼6¥.r¬Þsn¼§_­el8 蘷êA\°Ø`‹ºß 4Ë›üpô©þkƒ†w¦³ñ/5¦³0õ«â‘mÎ/— aß{!¶ mXñã3Ðï½dˆù†c½ {… µo¡&Üÿ+Ç2wæê HÄ—Ö»±!Ú@ù8mRõŽ‰•äªoóérxþø·^¬š%Ú[ ŠB»ÔYÏÞD5ÜbÛìz’ß5T˜Ôw8õY«ÇßxOë?¡¶ÍÿøðÁ«_ß@k=ü€Ø§Ò ü´Õ¸OøêƒW«¾_onó¦Ÿ}8±k› Î][ˆÇ`3Ol]ôû$Nþ3ûˆ¹£µÓà“ˆŸ‰¶¢ÜU±Ô@ÓdÏŸ#6 ¸çc¹¿DlzŸâgkDù3!Ä;TOC`æS?`!ÞûrºÌöçnMÔ{_Ûÿ~ÿαPŸ¹zй¿”ÓÖžQ h‰Ü_êi?kÛ|zÆž?>Ç­«v³ö¨ ­péíª<Û˜K5kàÔ»_yÂaŸ‰úž ‡>¿Ê3‰Á6§O ¶-Z¡öZ]ÚIÔ•ˆ“Ó ~›ßøæQ Õõ|™ÿõ>7ï²LÄ9ö(÷X\¤ñÄùèÀ*îËè…Î}ù9핇MYW·¯Í•wî­ì|ÿ±pÞY«FØVŒ Hø¶ ƒ-¹6ú³·@ü³÷=]Ûíx­¦í@6„´éíj f“ÞOS*;7 ÉÛ cï¿NìÀèÖŽìùû1ê‹ó{û‡ÞÈîR+º[¡05ÿ&Nm]UÓ9› ©¦sÄ­×ç}¿÷“zûŸ£¿]U=åØ ºäc3+Õ=nGoé}ZNÛç§NÔã9 ª…[{€ÚYÛ~þÒØ·üÏñÕUy5f»™:Pùûà_q¼(ûÙSkz [zaÕ ;}aÕ €Ù/Ì?Ê=†­âa+&Ô勈‡³N jy?¢ãýˆ†÷ö»¨VU¶NGª€ìhlK8"b7÷‹ˆœ?>!ßòŽ‚JØ [Äa<"÷P[rÐؽԖ¯pìÈ¡9›`R84gL ‡æ„¼èꨔ…%ÕÌÙåò·R.hQF”ã¦D¶¶¶Ç_íÉ+»E ·6´røÓ6¿z+¨óÇ'd@;`q ÕÞ Ô±pdÇÐaS†¹ Û¶õn}UÝÉlNìÒ¤ØóÇ'd÷J+¹Ø¼rÚ†nߪ:óaf3;óÙÌæ—+ìOi¥%Õvo¡>ë>¨¢µ×—?ç¶r©c±L·5(6·)>¥«›°!;„Ú-é»­gêìô Ô¡ó_l¨æÞ¶wxwáŸÒ½¹ðOéê¤kk¢ÔÔN„ UüõüaÝAQGÿÐʤ©×§¡šÚ,vô´]¼ûGäc+¾†zÃÈçkÛVlaþ‹ííE`€jÎeØÔÒþ!wµßQ.ìÖ¡étçÏÕ³ÍæóoÀÊÛ¨@Þµ­®S½m&ºZúûï|ŽKïGjk“Õ[9è½_P˜„ozêÈm8üªS­]­ÀìÔžä|B5Q·mV?mÛfµÓ6T×lÛ6eì„fª¶áö½®òN”íju©0üùãòCöƒß\[uÇj÷@u/ÓÇù/ÅöõŸ±¢%jKc¨nP¶×°°–ýN«c ª jFÛùÍp~ŠwAAÍÄrPJ¬:¢7.ù)ÞÏÄpèáütù)Þ¢ÃV»©s‡¡Z3XÝE°´evÞÈÁðôÑq©Gƒ-©ó ¶¤®d}M«A§ŽV–Pˆzäu{Ø‘«jþ/¥¶µ¥Ô¦úIçåœ:jÏYO Ã÷ VÙœ?>¡º: >¯¿ µ«Cƒ¡štXÕÞóFÖî{‚ÿñ ÕÈåï®å\lµŒ¹`áÌÒ§X»÷úûUÕ:³óÇ'T75û6«›š-Ôa> ÷„kvíyu¨ÓùãzO>C<œL©iP­ätØá;më,;)ªå>ºÿ¥ÂÑ­"Tay[[¸TÛ–žòåúãª$º­÷äN„õ‰*?nè+ýOè« ׳4[îø²>'Ð;%úÑëñZ•ìµ%“ªä‹Õ“[ÿP|•óåy}¸÷Ù±E5 ­Ê¹JCõýO8r>"ß9ß'W…K{"U¸´§WYK °ô?´…åÍù{r¯¶l ìT™ØVëÕç¼q•+ ‰3ç3å[ŸDõ"ᨽܹNç¿ñÇç¸õÙ×Suÿ§z©}ÃîÿP|ŽC{[m¬“jgZÞ!ÃPíJt$±ÇøÿùŸÖOž¬o#vU¿ËbEè舲Èßo¼’#Vþ±ËÉÉorÄ…üýrÈ;9dûUX0x;`¾~:ÎÊáÏÈÉ%9âFþ~9äšñCþ~9ä–¬íBm 6ÿ©+rOŽ¸“¿Ûäˆ ù»ñLù}Éðß“‹WrăüÝŽøMŽ¸‘¿Ûïäˆ2ü}r²w˜y‚—ñßíˆKrÄüÝŽ¸&G\Èûy.nÉÑOýKþnGÜ“#ždøåäâ‘q#·#žÉ?äïvÄ+9ä±È{,y.~“#îäïvÄ;9âBþn‡ÌÒtÄv‰9ØsÇn x..ÉOòw;âš±òïvÄ-9â‡ü±ï”çâž²]|Õ“ß“?’#VþÝŽx&G\ÈðÇÉÅ+9ú™ØäïvÄornþnG¼“sóÇ^\ž“Õ- Žß‹WŸ×:¹¸'§Çkyõ~¾'§×ë\ÉûyNV.8Îl>>Gu…#·ä´ø,Ø‹Àfö{.NŸ—ó ï'¿ÉOòw;✛ᷓƒÕÄÎáE†ßO.îÉ¿døãäâ•ñ&ß''—'±½ÏSíîìLG¹¸%G\Èðß“‹grÄ• Ÿ\ü&ç=ßýYÔáî99¹–pœ;~9¹¸'G<ÈðëÉÅ+9ë»8¼ÙÏÉí Çy‘á÷“‹[rÚ9–N¶6µ&ž‹Grn†?O.žÉoòw;â79ú}yÈð×ÉÉêǹá¿'÷äˆ+þ>¹x%GÜÈæÏçädÃqîdøåäâ–ñ ï'äˆ'~;¹øMNüvOÍ3T弓sów;dƒÁùÅçõÎôz½ÿÞJü’Ïç5Óç¥s°ÿŸýSçcä–œ›Ï÷Kçcäžñ&ŸãƒÎÇÈ#97Ÿã›ÎÇÈ397Ÿã­ÎÇÈ+9qn6u>†ã˜ÎÇÈornößÇéçcàœ›ý÷}úù˜±ÎÁà8²Ÿ¿yçYrIÎÍ~¾­\\“s³_¿(·äˆ+Ù¯O½+.¹'çføgÄÕy$'η½ënyO.žÉ¹þ8¹x%çføõäâ79âN6ÿÙ'ïäÜ œ¬“p~1üÈÅ%9âA†_N.®É¹Ù†Íö9¹%çfø)'÷äÄõÔäù¡-<9y$çf󭜕ç䙜›á¯ÈÉ+9båð{ää797Ã/‘“wrn6½‘ƒuN ÇY9ü9¹$çfø5rrMŽñÿùóÿþ§üüßøýù¿pº’G ?¾³ùêbnÿ—ÿ×ÿöŸÿñŸçŸ¿gÿßßGø?þþ÷ÿüçùùßÿ£Ñ~£îöø7gù#¾½¾ù8³Tg!ò_ß’~ùÐåO¿Fè(Æ;®F³ g!i«5¾™:“ž¸báÞ€‡•FCÔ—é²YîoU[º Agçòóç87[+†§ž\\“s3ü}rqKÎÍh1O.îɹ­!ÚÉÅ#97lá¹x&çføç=u^Éw¿Â«¶|Àsñ›œ›ÕâÃsñNÎÍð×ÉÉl‹Aç›?#—äÜl>F’˜‹krn†ÿž\Ü’s3šŽŒ“‹{rÄl>î0äÜ Ÿ\<“s³ºx.^ɹÙü¹øMÎÍæc$›¹x'çføëä`®Ô¥ó›Ñ\§Ÿ\\’#®?ºÂF3ÏÅ597ÃO.nɹùcÃÏÅ=97›?#äÜü±Ùç♜›áï“‹WrnŽÇ_éñßäˆ ù»réáübøëäâ‘ñCþn‡\K8¿øcc$ÏwüN¸C¶¹cœmp9â797Ã'ïäˆ5oỲܬ÷ßü±É“çâ™ñúÑüåÕÎ/†ßN.nÉOòw;✛ÏþÜwìÏlwDÇYçßíˆgrn†_N.^Éwòw;äÙÂùÅ📋{rÄíGW¨—³ã*MÎ/þØ.ÌsqIŽXWrßíˆWrn†ÿž\ü&G\~ts9dcÀùÅŸy.É??:£¿²~sáübøóäâš²Ÿ³~·#~“só9>ë÷Èxé7ÅœßüÝŽ¸$§œ}{é÷%9âšœz~›–~_’#nÉ!ïÇg]Ž¸'G¼ÈßíˆGrxž`W–K¿/£Ÿ\<“CFÿmý¾$G¼’#~Éßíˆßäë ·#ÞÉ!svÕNþŸÍwè8oòw;â’²$­R’_’_“C¶ÑGãÍü<·äí¸±JK~K~OŽxù$ÓËäW'·#žÉ!Ûo1«2\Žx%Gü’¿Û¿É!ÛuÖ*oòßäïäðs|*~\Ÿpœ7ùûåKrÈvµtþrMÙ®³–βCnÉ!cV`mÉoÉïÉ/ò÷Ë!ä{'¿òLŽ±ü=ÆÌp_rÿævéhk5οóLŒT[Kîàe„yBôâÜ{ ]oC•u—3”X7”ãäê Á­¾ÉýÜj@OOÍ"EWÎsâWq©‹ 8‰ÅN8µ“o¼N@Þsˆ…“|¸CÛZ(ðŸÃ›ÜÿÍæÛÛs0ŸƒŽs#ï‘“Krn†ß#'×äˆ+þŒœÜ’s3ü7rrOŽ¸Í_Oää‘œ›á×ÈÉ39⇠¿GN^ɹþŒœü&‡ŒY^¼°i''ïäÜŒîcOä`õƒãü’á×ÈÉ%97Ãï‘“krÄ‹¬>i''·äܬîi''÷äˆ'ÙüýDNɹ~œ<“#dø=ròJÎÍðgää79âN†ÿFNÞɹٺÕ=ÏÉÉý ǹ‘áד‹Krn†ßO.®ÉW2üyrqKÎÍðß“‹{rÄ…ìÝù”‹GrnþÔÃO¹x&Güá÷“‹Wrn†?O.~“Cn› ÿ=¹x'çfóësr2/Vé8¿døg¨sIÎÍŸú*×äˆþ<¹¸%çføïÉÅ=9âI6¿='äÜ ¿ž\<“#døýäâ•œ›áÏ“‹ßäˆ;þ{rñNÎÍæc?aNžO8Î ¿ž\\’s󧮙ÊÅ59âJþØ[ÓsqKÎÍðß“‹{rÄ…ü±3§çâ‘œ›áד‹grÄ~?¹x%çføóäâ79d»aÕØÕ¼àœŠ¹x'çfóqNÅœÌÁ:Î/~=¹¸$çæ]L=×äˆþ<¹¸%çføïÉÅ=9âI6çTÌÅ#97ï'Ïäˆ~?¹x%çføóäâ79âN†ÿž\¼“s³ù8§bN~Ÿpœùc]ÏÅ%97ì³ë¹¸&G\É»ñz.nɹþ{rqOŽ¸ÍÇ9sñHÎÍðëÉÅ39⇠¿Ÿ\¼’s3üyrñ›²­±k¼áWpNÅ\¼“sóg}‰Ÿ““y3ŽóK†_O..ɹùcßcÏÅ59âE†?O.nɹþ{rqOŽx’ÍÇ9sñHÎÍðëÉÅ39âA†ßO.^ɹþ<¹øMŽ¸“á¿'ïäÜl>öæ`–R¤s¸‘¿Û×äˆ+Û³O.îɲo¿rñLŽø!Ã_'¿É!?›ìï§r2é8¿døãäâšñ"ûç«\Ü“#ždøíäâ™ñ ûþ¦\ü&GÜÉðËÉÉ»€ãÜȾÿ+×äˆ+߯}rqOŽ¸ýû¨\<“sów;â•œ•¶ß¼ÏÌÅorÒ{ÅñC”‹wrv|vu'‡¯±8-íKMÇÃqrqIN‰}»•ä—ä×ä¤ïZ«çø©\Ü’Óα¢·–ü–üžœ86ö¦Ï«\<’3ÎoAçxBvÄ39ñÛ×Û<¿ÊÅ+9ëüÖ÷¶’¿’ÿ&'ÎmzÓç[N.ÞÉ/òw;d!ÀéqîÚûs~•‹Krt=RÈßíˆkrâÚ¤kþà9¹$‡Œs'OH¹&GÜÈÙ‘“[răüýrÈ=9âEöñÏÉ#9âMþ~9ä™2Î4ž€ã€ròJŽ¸‘¿_ùMŽx}|ÉsòNŽx‘¿_ë¡<á8o2ü9¹$‡Œs'Ž'\¹&GÜÈ>žæ9¹%G<Èß/‡Ü“#^dø-ròHŽx“¿_y&‡Œs§=Ïø¡çä•q#¿ò›ñ Ã/‘“wrÄ‹üýr0ûyŽsx“}¼ÔsrIË្ü’üšqûQ=j=ONnÉò÷Ë!÷äˆÙLJ='äˆ7ùûågrȳᯔƒWrÄüývÀorŒÏ”¿çŒÿØ(ªfN¤+pŒŒë_¦N?áO§¦Oì4,ó®"Ãб†C1L­¡×YbØv¤áSÜŽÜq¹áC[øš”rœîS l£t9<Òe,Nót™‰Ã£ßj×6ã§ðõ¤[ºþ³·Zðóí·Û^ÜêÒ©]Ü^Ä)hSíOðt’‚ƒ½N*ñCÑÓœƒô‹0ïÄŽ¬WÞÐðƒY9“üa|ÒIAÙqÀnñåó TÈÒI¾¸+núÉH='\6©ýÕËËvÒö†ö²p.ä–¸’ᯔƒkrÄ…ü±™}äà–ñC†¿SîÉ!Wå{Ÿœ<’#~ÉðKää™ñ"ï‘“WrÄ“üýrÈoră ¿ENÞÉ+‡ß#³½ çJ†?"'—äˆ þŒœ\“#~ÈðWää–²Õu|;?_+'ê9¹'G¬~ÊÉ#9âE6<‘“grÄ“ ¿DN^É2ü9ùMŽ¸“á·ÈÉ;9båðSf‹L:Ε DN.É2ü9¹&Güá¯ÈÉ-9dë6ð~¾V%ÐsrOŽX9ü”“GrÄ‹lþ|"'Ïäˆ'~‰œ¼’#dø5rò›q÷bu•y='ï䈕ÃO9˜]½é8W2ü9¹$G\ÈðgääšñC†¿"'·ä€QØôü|­T±;äžñ"Ã\<’#ždó×srñLŽxá—“‹WrÄ ¿ž\ü&GÜÈðÛÉÅ;9âJ†ßONfŸc:Î… œ\\’#~ÈðçÉÅ59äw“¿Û·äˆ_2üurqOŽX9üÈÅ#9âI†¿O.žÉ²ùïsrñJŽ¸“á—“‹ßäˆ~=¹x'G¬~ää÷ ǹá÷“‹KrÄþ8¹¸&‡Œ÷íåç‹÷¹¸%Gü’ᯓ‹{rÄÊáG.ÉO2ü}rñLŽxÍÇ~Ë\¼’#îdøåäâ79âF†_O.ÞÉ2üÈÉìNÇù!Ãï'—äqÜc{qô P.®É¿døóäâ–ñ"Ã_'÷äˆ'þ{rñHŽxáï“‹grÄü×øa.^É72ürrñ›qýQÍ×2žzrñNŽ¸á·“ƒÙNÎᇠ¿Ÿ\\’C¶ó–AŒb×ÿž‹krÄ/þ<¹¸%G¼Èð×ÉÅ=9âI†ÿž\<’#døûäâ™q'›_ž“‹WrÄüÝŽøMŽ¸’á—“‹wrÄÊáGNf7s:Î~;¹¸$‡l×»ðóµóvåâšñK†?N.nÉ/2üyrqOÎÍð#äÜ ÿ=¹x&g¦mÓç»O.^ÉYéµóó­ÏÉÅorÞôÞòó­åäâœôù~¾µžœ\Óçë¬~;¹¸$§Ä¾WùùÖ~rqMN}»òóµëtåâ–œßÊÏ·žÊÔÎ=9éû[ùùÚ8ƒrqúþ:+‡ÿž\<“3ãØRùùÚ8‰rñJΊcWåçkã0ÊÅorÞ86V~¾­œ\¼“Çç]ùù¶zrrKÇggåðÛÉÅ%9åüvlŽ_ –ýæçK®É©ç·isü }§”‹[rÚùícÏHtzð\Ü“¿¿›ãWh}¥\<’3Îo÷æøÕ@‘sæâ™±røûä╱róm M¹øMŽÎ¯”Ã/'ïäÄùK­ôSNîq~uX9üvrqIŽX9ü~rqMŽXùw;â–ñ Ã'÷äˆ'þ<¹x$'Î¥7ǯF_'Ïäˆ_2ü÷äâ•ñ&Ãß'¿ÉÑõÑC6<'ïäˆ ~99yÄ5ÑáJ†_O..ɹ~;¹¸&G¬~?¹¸%G¬þ8¹¸'G¬þ<¹x$'®7ǯеP¹x&G¬þ{rñJŽX9ü}rñ›±róqf.ÞÉÑø†røåääù„3c|csü í•‹KrÄÊá·“‹krÄÊá÷“‹[rÄÊá“‹{rÄÊáÏ“‹Grbüjsüjà8Ì\<“#Vÿ=¹x%G¬þ>¹øMŽX¹ù83ïäh|R9ürr²Æ¦à8+‡_O..ɉ±ÊÍñ+´U.®É+‡ßO.nÉ+‡?N.îÉ+‡?O.É+‡¿N.žÉ‰±èÍñ«ã0sñJŽXùw;â79âM†¿O.ÞÉÑý…çG-M šÉ*'klªd.døåäâ’œ¸×°9~…µÊÅ59âF†ßN.nÉw2ü~rqOŽxá“‹GrÄ“ ž\<“÷’6ǯƻN.^É¿døïÉÅorn†¿O.ÞÉ+7ÇaædMÁWåðËÉÅ%9qpsüjà8Ì\\“#V¿\Ü’#V¿Ÿ\Ü“#Vœ\<’#Vž\<“#V\¼’÷‚·Æ¯pÖøùMŽX9ü}rñNŽXù_}¹•£÷ ûŒÃ9Ü”Ã/'—䈕ï'×äœ{ý`øíäâ–±røýäâž±røãä⑱røóäâ™±røëä╱røïÉÅorÄÊáï“‹wrÄÊÍ/ÏÉÉå GÜ•Ã/'—䈕ï'×䈕Ão'·äˆ•Çã·ôø=9âNŽíïiûGră|Þæâ™ñ$Ÿ÷¿ÌxÿËJŽx‘Ïç[Òç[Þ䈕Ÿý§¼±ÿ”ñöÎ`Ú'ËŽý³>áˆmÔSŸØÿëû-Éòù~Õ߯Z“#®äóý­éû[[rÄÊÏñ¡¶8>Ôžœ›Ïñ§ö8þÔ‘q'~L«#Žou&G<È:~z.^ÉO²ŽÏž‹ßäˆYÇÏÅ;9â—¬ßÏÉš[Çy“õû幸$G÷ñ²~=×äˆ Y¿¿ž‹[rÄ•¬ßwÏÅ=9âFÖùƒçâ‘q'ëüÄsñLŽxuþã¹x%G<É:¿ò\ü&G¼È:ó\¼“#~É:?ôœ¬¹Upœ7Y矞‹Krtÿ!ë|ØsqMŽ¸u¾í¹¸%G¬\çóž‹{rĬëÏÅ#9âNÖõˆçâ™ñ ëzÇsñJŽx’uýå¹øMŽX¹®ï<ïäˆ_²®='knçMÖõ©çâ’ÝÇȺþõ\\“#.d]_{.nÉ+×õ»çâžq#k|ÀsñHŽ¸“5þà¹x&G<Èßð\¼’#ždŸx.~“#V®ñÏÅ;9â÷G81æã9Ys«à8o²Æ—<—äܬñ+ÏÅ59ºÿ5>湸%G\Èó\Ü“#®dïy.É7²Æ=Ïäˆ;Yã“ž‹Wră¬ñOÏÅorÄ“¬ñUÏÅ;9âEÖx¯çdYÁq~ÉOö\\’#ÞdW{.®ÉÑ}ü‡¬ñð““[rÄÊ5Þ~rrOŽ¸’5žròHŽ¸‘á¿‘“grÄ EN^É2ü9ùMŽX9ü”“wrÄ‹ ¿GÖØç— ¿EN.Éo2ü9¹&G÷ñ2ü9¹%G¬~ÊÉ=9âJ6×}ÊÉ#9âF†ÿFNžÉw2ü9y%G<Èðgää79båðSNÞÉ/2ü9XcSpœ_2ü9¹$G¼ÉðkääšÝÇÈðKää–±rø)'÷äˆ+Ù|vVÉ72ü7åà™q'Ã_)¯äû¢!Sù‡+CþÁ{•çœØÜÿ·éˆtóŠ*¼q¤‰'àÔE&×ã@øßÿhHKSBñ3¦¡“t;¤çáx Ýj8Ô~hˆÛœ®4Ï.{n³•¸5KG—C¸E¡KÜ7¦¶`Z§3n9¨Ã·vZMTæň/¯O‚ŠAî´1Ùã\ˆµtуv;7ÔÎÅN~t¡ŠEMÚY1PÆFÚ9q³Ï,qs7åuÇ„ŠuÙ*²R9p`‹ŠÀãqåˆ+ùûå[rÈvC´rààrÈ=9båß/‡<’Cî“ ¿FNžÉò÷Ë!¯ämÂGåÀÁåßäˆò÷Ë!ïäë ¿0èˆm¿rààrÈ%9âN†ß"'×äŸMþ~9ä–±òï—CîÉÛò<ð÷Ë!䈕·#žÉ!¿/~?¹x%G\Éßíˆßäí†_moòßäïäˆ+ù»2èˆísíOøýI~IŽ¸á“‹krÈø®õšüšü–q!·#îɹù»ñJÎÍðçÉɼ¨¦ã\Éßíˆkrn†¿N.É7òw;â•œ›á¿''Ï'çNþnGÜ’s3ü}rñLŽx¿Û¿É¹Ù|»¬œÌ‹:ΓüÝŽ8í?¿~9¹x&G¼Èßíˆwrn†_ON~k8Î/ù»qOÎÍðÛÉÅ+9âMþn‡¼Ÿp~1ü~rqMŽ¾Ëù»ñHÎÍðÇÉÅorÞ8Vì7ùïñÛóç7ß'·äˆ+ù»ñLÎÍð×ÉÅorÄüݹ”p~1ü÷äâžq'·#žÉ¹þ>¹x'G<Èßík ç›o7û•‹{rúùíh:¿JŽx%çføåää¿Y‡ù»qMÎÍðëÉÅ#9â—üÝŽøMÎÍðÛÉÉþ›û&ÞäïvÄ-97Ãï'Ïäm«±_ŽøMÎÍðÇÉÉD¦ã\Èßíˆ{rn†?O.žÉWòw;✛ᯓ“9èIǹ‘¿Û÷äÜ ÿ=¹x%GÜÉßí×Î/†¿O.®Éòw;â‘œ›ÿúV1ÐsñJŽx’¿Û!¿%œ_ ¿œ\Ü’#^äïvÄ397ï'¿É¿äïvÈ»„ó‹á·“‹[rÄ›üÝŽx%çføýäâ²ç°ºîå€Y —Îo†?N.îÉòw;â•œ›áÏ“‹wrÄ•üÝ™“6èübøëäâ‘q#·#~“s3ü÷ädNz ãÜÉßíˆ[rn†¿O.Éòw;✛ͷ ”Êɼ֦ã<Éßíˆ{rn†_N.žÉ/òw;✛áד“u Çù%·#ɹ~;¹x%G¼Éßíu çÃï'×äí<‡Õ9/G<’s3üqrñJŽ¸¿Û!ó¦ _ ž\Ü’#®äïvÄ397Ã_'¿É7òw;dýÆÁùÅðß“‹[rÄ|öŸÕbÿY=97ŸãÉêq<Ño(›ý÷«ûï)x&çf?ŸQ.^ɹÙÏŸ•‹ßäÜì×SÊÅ;9bå~}ÝýzÖ˜7±èüb/R..ɹÙ|;/U.®É¹~;¹¸%çfóíºX¹¸'G<ÉðÛÉÅ#97›ocÜÊÅ397ï'¯äÜl~‹\ü&çføåäâñ"›_#'kLÎ/†ÿœ\\’s³ù8ælƒkrn6¿q;ƻΩèÜ ¿Ÿ\Ü“c|n,•õüƒÑíò>»kÌÐνõoÓq†7–8XË™ø!­3NŠ}ð7p`û¯÷lèÄCsÓONñ}Ø—¬ñÖ4 CÛö¦!T›Ý4œ×pÙÀª÷sšŽÝ´é+=ã´ÃÓ~©€Óë©üå¶G\¾âT—ânÐm˜¡÷ì²lNÈ[M·.°æ¶Ýˆ µxÛ iø¯¶Ø6¼^}휚×xü°‚K²÷ü|r›ÿkÿ'3ÜáqÖ |p ±U¬]5¶ÂP'±¸‰ãŒ`‰ÁîöÅOƒ]Ô8Ý`zÎ¥µe*]}uó„á=Ÿv×…¶o¿WÂûûunûûùvŸOhx¦ ?zé6ÏSàáTvÒy•MÄóÔЧöÀöÓU¬íï®ï)°„ dúqž§À™ÚU¤mõ“[Â秫@ÛßýÄS`áTéê*Îöwçö8B¾?:ÿ³ŸJO3!Ó“í<®ÎŒ^'ÚO¤§À7áøé*Æö>'îNŵ®Blo9©¡—XëíGçžö³è)°„ dúñÀ™©­sTû9ôØB>?]…×þ~¥<ö4ë~ÿt]ûû3è)p„ |tÞk?žgB¦'Ñy \!œY÷:?¶Ÿ>OoÂñÓUdm?'îN%Ä®k»œÔPSúLpl?]ÅÕþè<–„L?N€óXC8+(ºŠªí~R` A+böÎãm⛧À‚ðýé*¦ö÷\ÂSàA¸~ºæ'$8C8«`tm`“ã<®„㧫€Ú~O |Cö]Cؤ8O;aû隸÷<ž5UÏÇúÓ5iïïù¼Rb á¬hêš°÷œ”XC>?º†±Ù$Ýçð¶´RmÿèúÅ&ÀuŸxbØC¾?ºv±ÉoÝçëG×-6ñ­û¼=ÃÂY¦k›ôÖ}Ξá A8~t½bÞºÏ×3|Cö]«Ø,™îsõ wÂö£ë›è¦¨%¤&8Ö]£ØÜ¥ÄÂYi¨ë›à¦”XC>?º6±ÉmÝç涴‚tÿèºÄ&¶uŸ—gØC¾?º&±™CÝç䎄ëG×#67¨û|<ÃÂYAªk‘)q… ?ºx6Mj2|Cö]ƒ ¼ ÍÁ3Ü!ë®?ÞÕÑù‹¾L´–]{Øä5¥Ä‚ðùÑu‡M\SJ¬!hu÷þÑ5‡MZë>çΰ… |t½‘bA¸~ºOªëžGgEw÷ uÃSâ AÈôã®îsé WÂþÓµÔ¾±>×Îð AØ~ºÚ‘@k@;aýé*`fGÕ/û‹CK>ÿ ËÏPñ²¿G.¥Ä‚éÇÉJ‰5U]Ø?CEËZõ”ØB¾?CËþÁ•{Âõ3T¬ìï/ƒRâáTZ*Tö÷G)q† d ÷¤Ä‚°ÿ (kËSâ‚°ᾞw „»=ª™ Žhîßk¥Ä‚éÇù}J‰5UCÙ@¸ÕSb Aøá6O‰=áÂížG§ÊP²¿gmJ‰3aÂ=)q… lÀs•ß„÷õ”¸C8m† Žõí)°žr6 ¹ãñ”XBP¥¢ ü.XC¾@¸ÅSb A¸€p«§Ä©N4T\ìïõ‚RâA8€çqG<î AØg{glï AØ€ç}Xñ>¼!+Ð?‹úÆg±C8•¦†bÚ«u˜†í”™:ø}ßÑL` AÄ6Ð÷I­¿Ö„/Ð÷uMù¶„ èß!MýöNÕ°¡E—ö…ÔšKàA8€þ×4eà AØ~,ÑZKà AØ€~ŒŠ:aÃË„µÀ ôcŸ¦;w§ÜÐK;j:´a?åß>@?Vkm%°„ Ê~è¿ZW ¬!Ð[´¦ØBN ÿfi=%°‡ @ÿ-ÔDtàAØþ«u”À‚°ý·[k(+aú9ÖOß„¨s ¥Ä‚ðê|G)P¥¾LÚ7V‹&ÿ”K¨ó3¥Ä‚puÞ§”ØBN Î'•{ÂÔ9­RâAØ:WVJœ!PçàJ‰+aêÜ^)ñ AX€ºfPJÜ! ®E”UÂË¡}cµòïo±Rb Aøuí¤”XC. ®É”[ ԵžRbA8€º†TJ!;PצJ‰3aêšW)q… ¬@]K+%¾! P×èJ‰;¢} }¼dy Tiy_ Æ†—–„ ¨±Šáã%†5áj døx‰a A8€[>^bØCv ÆlF¬u*#AØ€ >^b8CV Æ£”WÂÔ8—Râ‚ðjüL)q‡@´o¬ ÈÛŠ/dú‹*o‚ã ÔØ Rb A¸€sTJ¬!'Pc™J‰-ájŒT)±‡ ì@½*%Ž„ ¨1]¥Ä‚°͵+¢W„ûzJ|C>@¸ËSâhßX†·+¢ª¼ Ž/îð”XB. Üî)±† œ@¸ÍSb A8€p«§Ä‚°áO‰#aÂ}<%΄h®]Íh¸B>@¸¯§Ä7NB±oìÖý·å)q‡ |p§§†“Ã!&\@¸ÃSb A8p»§Ä‚pá6O‰-aÂ-ž{„ûxJ!+ÐÜ¿¿J‰3aÂ}=%®„îò”ø†@|7îô”¸C¾@¸ÃS ‡C 8. Üî)±„ œ@¸ÍSb A8€p«§Ä‚°áO‰=aÂ}<%Ž„hîßs3¥Ä‚°á¾žWÂwyJ|C ® „;=%î„/îð¨š&8. Üî)±„ œ@¸ÍSb áB¸ÕSb áB¸ÅSb¡Çæ¨YÕã)q„0âeªÑÜö”8C˜çí«j2wRâ !>·ªsËSb|nŽwzJÜ!ì³U5–žÛsÇ„Û<%–ÊÙíÕ0°WO‰5„ø¾©Yàß+¥Äø¾9N ÜÇSb¡Ÿ¯¿šþ½B™ÞGÐp„0ÎaE Ûë)q†0ÏáJÍÛò”¸Bˆã¤æ—´é)1Ž“ŽwxJÜ!ìsØÖü’Ö=öçŽ ·yJ,!”ó3£ù%­zJ¬!Äï›æ—üý|•ã÷Íqá>ž{Â4÷ïþ¨”8B¸îë)q† d ÷¤Ä‚páNO‰oçej~Ižw„Û=jÄÇ „Û<%–„Láž”XCv Üâ)±…pÎ'§æ—ü=N+%ö„hîßã¿RâA¸€p_O‰3!S¸'%®„wxJ|C8×SóKJ÷”¸C Üæ)Pƒ$&8V Üê)±„ l@¸ÅSb AØpO‰-„sý65¿Ä^±÷ô3ì!'îë)q„ \@¸ËSâ AøáNO‰+„ áO‰o „Û=%îÎ%øTc>ûx½ó¿èƒ$O`­žKB¦pOJ¬!îã)±… ìÀ¿®ÝMõØC8C'“ã%v7ÕSàA8p×I3!S¸‘WÂwœø† Ü@¸ý¤À‚†¼ ÜvRC ’˜àX€pëI%!S¸‘k„ûœØBv ¹öëÿž«Sƒ$Îøääx‰Ý!õ8BN ÜyRà A¸€pÇI+á „ÛO |Cn ÜvRàáB¸õ¤†û &;ÚYÇKìnª§À‚)ÜH5aškgÐûÜX$ l@¸ïI=aÂ]'ŽέÉñ»›ê)p† d 7Rà A¸€pûIo·¸Cn ÜzÒ¿¸žsóÆñï‰Èâx‰ÝMõXB2…)°† ¬@sç>)°… l@¸ïI=aÂ]'Žέ¸Åñ»›ê)p† d 7Rà A¸€pûIo·¸Cn ÜzRCou·…g1Æõ»ßÿ>Ö£yïébÚî¡òßq!¦w¿1™|ÅŒ÷“¾Ÿ3§Ð¦¦j ÔfˆîsM3¼ÔûòY&³L4pP}¾ƒ)ùT»¯ +_)ÅI‚Õ³qëvNÎtÛNü.» :>ç¾·2zó£¸;·Î­(Ì™Ðｶú[=cò6ðªán»Ÿ®Ñlû9Ç…ÿßmù)}pëKp ”ÏÊqœ¡ Îjür´s·J—"86ú½¼8=³œuf,8Ú!Õ;Ï<çTW\gV•.!ñsŒ«u[Ñ°bã$ ;ÆI„X Ü©áh+,0NÒ°ÀÃÂ…pß“WB¦p#¾!Ð\›à¯¸Cήóm˜à¯Ôà n„ÛN ,!Ç×7LÚW ¬!;î<)°… l@¸ë¤ÀÂ…p÷I#aškñ•gÂòÃµÈ ñ•WÂGëp&â+¾!\·Ÿtw-³‘@´£Rãç¶ÇI ûsÇWëp&Ì+–„Këp&Á+Ö„Sëp&Á+¶.üëbïƒILp,Z‡Ã7•)±„ ¬Z‡“b AØ´§M,|Ñçöh™¡¯ÃáNÀ”ØCN­ÃáεûÙÏ4HA¸´' Ä‚pkwð=Ͼ®A’íKrp‡‰ëpÚÄz}ߦ–ÙH­Ãá—lÇ÷MÃ!„Mëp²0Ï2»Öáà‹®tže6„CëppQ:Ï2 ©u880)%¶„¯ÖádØCn­Ãió,ÔŽtÇæÑ:H•gªu88@+%®„Mëp²@|Cv­ÃÁ„RâA8µ§Í3W¨á}~¨”KÂWëpð¨”XCn­Ãɱ… ;6Eëpð#¬”ØCVMÉhs6O‰#aÓ:œ(%΄Cëp²@\!§ÖáàdD)ñ A¸´'9J‰;áÖ:œ<)ÖçB›B©ñ’ˆ%aÑ:œfó¤•kªu88ÙSJl!»Öáà$R)±‡ Z‡“âA8µ'²J‰3á«u8mb?7à A¸µ'ÓJ‰oºcóhNˆ;¡¯ÃÁ ½R`{Žàèëpp¡ ”XBú:œfë”kB_‡“b A¸´6J‰=á«u8¸`RJ!·ÖáàBL)q† ;6Eëpp§”¸BV­ÃÉñ AØ´§Íîëp„;áÐ:\*r8‚ãÔ:\è*%–„Këp²@¬!_­ÃÁŶRb Awl­Ãiö˜J‰=aÑ:\ð+%Ž„Uëp²@œ!»Öá`ÐaúxÉÖÜ6 ¡u8̘>^òj™áÔ:œfŸïôñ’¥e6„¯Öád¨é#&8n­ÃÁàËôñ’©e6tÇæÑ: ê(%Ö„Eëp0X¤”ØB6­Ãɱ‡ ìZ‡ƒ+¥Ä‚phN³ï»Râ A¸´ƒfJ‰+á«u8Y ¾!·Öá`àN)q‡ ;6¾‚Jš>ò–@_‡ÓìØ«”XBú: J*%Ö„¾' Ä‚pjF•{Â¥u8pUJ!_­Ãiö;¨”8CЛGëp²@\!‹Öá`€X)ñ AXµÏJ‰;a×: h+Zqã‚ãÐ:œ,̳øF‚pjÕ•kÂ¥u8Í΋”[­u8ØWJì!èŽÍ£u8Y Ž„EëppsÁÓâëp$›Öáঅ§Å×áHv­ÃivŽêiñu8„Cëp.¸C.­ÃÁMO 5b‚ã«u8¸yã)°„ ÜZ‡ƒ›Bž_|#ÁÐç­·¾ê?í§×úÏË«ÏtŸÐ.$ü_ž1 Ì\ç¨3/Ó0°ýœÉQ~³½çö ¤iuœ›³Ÿû 6ôÕcDGwXÞ¸éd·Ÿë™™ë·µQ˜\gè>Áå¿:³ÔmtàÄ¥Ó5êàÓ±^].þWGMžá‡D'Ƹä<ÇG xà&´2ã “¯ÕÄ;J›WÂyŽIÙ¸ú>w(ü‚Æt:G¶w]'7gM.îÀ{ºüÌÎf“wTßß8lõÂfÝöÿœ'yü›Í·1ž“WrÄ ?åä797Ã#'ïäÜl¾õŠðŒã”çF†ŸrrIÎÍðWääšœ›áïÈÉ-9âJ6¿ÕÈÉ=97Ñ“Grn†ÿFNžÉ«5¹ùѦÜy%çfø=rò›œ›á¯ÈÉ;9⇠G~Ÿp~±ùÖFØsrIøÙ› „C®É¹þ{rqKÎÍæ[ÛUåâžñK†ßO.ɹþ:¹x&çføûäâ•ñ"›¿êÉÅorn†?N.Þɹþ{r2›rœ'Ù|k£§\\’s3ü~rqMÎÍð×ÉÅ-9âA†¿O.îɹÙ|ëé¢\<’s3üÈÅ39âN†ÿž\¼’só_-¹”‹ßäˆ~ä✛ᯓ×çyÜùÃß'—äˆ+ÙüRO.®É¹þ8¹¸%çføïÉÅ=9âB6¿–“‹GrnþnG¼’#~È📋wrnÆöï““ËŽøUþÝŽ¸&çæóþ”ïOiÉ+ÿnG<’#^døëäâ79âI†?ON®%çA>ûC-±?Ôžq'Ãï'¯äˆ~;¹x'çæ³?×ûs{ÂqVþÝŽ¸&G\ÈðËÉÅ#9⇠ÿ9¹øMymòùþ¶7¾¿½„ãü’á¿'÷äˆùócsñJŽx’áÏ“‹wră œœü¿Û!ëšN±âªë#;W..ɉ±ñªë£äˆkrÄÊ¿Û·äè~J!Ã_'÷äˆ;ù»ñHŽXùw;â™Ýï~Èðgää•q#¿ò›±òï—CÞÉo2ü9x<áˆmܾŽ'|åä’q'¿rMŽx‘᧜ܒCÆoýhÉoÉïÉ7ò÷Ë!äˆ'~ÊÉ39âMþ~9ä•cŸÙd÷Óþ±X =vÇwæ_t}êÕÿ%f6i Oÿ°›=þõYçVžúñ¯!n q ·Ò儱ŸÚÚ^-é0QÏó3_ð“–v¾àA§’¸üÖmo°.±xüž]„—¾6 ªÚ,ÅÂaûj³ ‡í+¹$~ÈðgÊÁ-97ÃSîÉ!Ût óW›µwròHÎÍðkää™ñK†ß#'¯äÜ DN~“#^dø+ròNŽx’áïÈÁ˜âñÿ·õvY®ƒJåû7Š3‚»Ä? £×Æeþ¯]d™»ßvEmÛX¶%HD燿Räà$¹Í/‘ƒ³8/›_#qÈÌÍ«8/›?#7qÈü矫;ßœÜÅyÙüì9yˆCfn~ää)9Íož“—8/›?<7ÆŽó6yNNâ¼|ü”<'gqÀmÍ/ž“‹8/›_='WqÈl~÷œÜÄyÙüÈÉ]ò?ž“‡8ä6?{Nžâ¼l~ñœ¼Ä!7°ùÍspúÂùaó‡çä$¹‚Í_ž“³8/¿$ÏÉEr›Ÿ='Wq^6¿zNnâ3Øüî9¹‹CN`ó§çä!ÎËǯŸçä)™¹ùÙsòçeó‹çàü…C>Ë31M÷ç4ÏÉIœ—Íž“³8ä 6?rrçåãÛv@N®âØüì9¹‰Cî`ó«çä.ÎËæGNâØüé9yŠóòñm¿‡œ¼Ä!W°ùÉspùÂùaó‹çä$™¹ùÍsrçeó‡çä"9ƒÍ_ž“«8ä>þHž“›8/›Ÿ='wqÈØüê9yˆó²ùÝsò\Øüé9y‰óòñçç9¸~á\ž`ó“çä$ÎËæÏÉYò›ß<'qÈl~ää*ÎËæ/ÏÉMr}ž“»8/›Ÿ='qÈl~õœ<ÅyÙüî9y‰C.`ó§çàö…óÃæ/ÏÉIrÿùó, fNÎâ™›_<'q^6¿yN®â?°ùÃsrçeó—çä.83?~Šœ<ÄyÙüì9yŠCž`ó«çä%ÎËæwÏÁý çò›99‰Cî`ó—çä,ÎËÇ?§Ú0'qÈ l~ñœ\ÅyÙüÈÉMr›?<'wq^6zNâ øøö=ANžâ¼l~öœ¼Ä!37¿z_8—Øüî99‰ó²ùÓsr‡üÍ_ž“‹8/ߎƒÈÉU°}¯>_;Ž#'7q^6¿yNîâ'Øüá9yˆó²ù‘“§8ä>¾õ{‘“—8ä6?{ž_8?l~õœœÄ!7°ù‘“³8/›?<'qÈlþòœ\ÅyùøÖ‡DNnâ Øüâ9¹‹ó²ùÍsòçeó‡çä)Δ¶áó=u-æä%Ž|¾¨_ÍSÇc^ò™^ž`ó³çä$NŠßêWÓúÈÉò›½œÁæwÏÉEœû"ԯ枓«8²FýjŽå9YöÏ—øøÖ‡DNîâÈñõ«i}Häd9æ’­o€úÕ´>$rò‡\ÀæwÏÉÒ§ZÒ×BýjÎé¹qfÍê8Î|üÓ‡dNNâDÿ9£~5O’99‹ÃñÑ6¿zN.âÄøË@þœî9¹ŠC.`ó‡çä&¹Í_ž“»8äþó×éC2'qÈ l~ñœ<ʼnZ–™ü9Ísò‡\ÀæwÏÁ·fU„+Øüé99‰CîàãŸ>$sr‡<ÁægÏÉEÖŸ?°ùÕsr‡œÁæ7ÏÉMœ¨?cËŸ3<'wqÈ lþòœ<Ä!ðñO?„9yŠC^`ó‹çä%x$°ùÕs0kVæ\.àý:ä$NÌaÙËã³81O„e/l3rr'扰ìåqÈUœ˜'²—?'{NnâÄ<–½<¹‹C.`ÿ¼“‡81O„e/CžâÄ<–½ü9Ÿçä%NÌaÙËã€Y³2§Ä<–½ð;‰œœÄ‰y",{ùs¦çä,NÌaÙËã‹81O„e/üM•¿/Ö¬àÄ<–½<¹‰óDXöòçtÏÉ]œ˜'²—Ç!qÈìûää)NÌaÙËã—81O„e/ܧ!³6eÎåÞ¯CNâÄ<–½ü9Åsr'扰ì…ûä*ûgÖ¦àÄ<–½<¹ŠóDXöòç$ÏÉMœ˜'²—Ç!wqbžË^x ª=ŽG¬Meå Þ¯Cžâ+ØŽËsò'扰ìåqÀ¬M™sy€ýøÛäøÛ’81O„e/CÎâÄ<–½ü9Ãsr‡\ÀÞ@N®âÄ<–½<¹‰óDXöÂ> rr'扰ìåqÈCœ˜'Êý«ê9yŠóD¹Mñ§øK2sï¿5~¾‡ûÎåÞ¯CNâľ`ý œÄ‰y¢Ìú•8ä,NÌeÖ¯ì¸Éú¸ˆóD™õ«Õ<'Wqbž(³~%¹‰C.`¯±~îâÄþrÝÜÄ!gðþqÀ]r›Ÿ"qÀuÍÏ‘ƒ§8ä 6¿D^âØü¹1îVçrïœÄ!7°ù-rp‡\Àæ÷ÈÁEr›?"WqÈ lþŒÜÄ!`óWäà.¸LðþqÀCòÿùç@{sò‡ÜÁæ'ÏÉKr›Ÿ=ã®p.W°ùÅsr‡œÁæGNÎâx¿¹ˆCþÀæ7ÏÉUðÊTÜá~oNnâ'Øüá9¹‹Cî`ó#'qÈ ¼_‡<Å!W°ùËsò‡\ÀÇOŸç`ÜýÎå 6?yNNâ?°ù‘“³8à3-Yq£„Ó͹9¹ˆCžàý:ä*y€Í¯ž“›8ä6¿yNîâ+ØüÈÉCr›?<'OqÈlþôœ¼Ä!'ð~0®Ð‡lß“ÉÏwyNNâ'øøö9"'gqÈl~òœ\Ä!w°ùÙsr‡ÜÀûuÈMr›_<'wqÈl~õœ<Ä!'°ùÍsò‡üÍïž“—8ÆvEõŠ›Sž•7ãf p.3߯CNâ;Øüé99‹Cn`ó—çä"¹‚oûaää*¹€ÍOž“›8dæægÏÉ]òÞ¯C‭ˆ›Wž• 7'OqÈl~õœ¼Ä!°ùÍsㆻTšãÌÜüî99‰C®`ó‡çä,¹€÷ë‹8ä 6zN®âØüå9¹‰óòñO?Š9¹‹ó²ù‘“‡8CÚ6ÄâOq¦¼w|¾5rògɶÅç[#§/œ$Ÿ/nxyVJÜœ,Ÿï›99‹Cî`ó»çä"N‰ïn~©¹ŠSý»ÝpÌS¬¹9¹‰Óü·Ó?ßÈÉ]œøý¶ÄÏ7ròçåã·ÈÉSœéûŠ†bž•7'/qȼ_œ¿p.°ù‘““8É÷ 7Ç<+1nNÎâÄþ¹á™g%ÆÍÉEœ—Íœ\Å©~,h¸Q¦:ä&NócMÃÍ2ÏÊ›“»8ä 6?rògø±¯e~¾‘“§8qüm™Ÿoää%ÎËÇY›ú”x¿9‰CÎ`ó#'gqÈl~ää"¹‚Íœ\ʼnþUCýê¬ô¸9¹‰ó²ù‘“»8äÞ¯CâØüÈÉSò›9y‰C^`ó#×è3_>ã¦VùùFNÎâøø#rr‡œÁæGN®â ØüÈÉMr›9¹‹ó²ù‘“‡8äÞ¯Cžâ;ØüÈÉKò›9˜µ&s.O°ù‘““8ä6?rrçeó#'qÀgÜÔZ¿ˆ_Å!'ðñgää&9ƒÍœÜÅ!°ù‘“‡8ä 6?rò‡ÜÀæGfMÉœËl~ää$y€ÍœœÅ!O°ù‘“‹8ä6?rr|Æ5õ¢9¹‹CNàã¯ÈÉCr›9yŠC.`ó#'/qÈl~äàõ=ç6?rr‡ÜÁæGN.âØüÈÉUò›9¹‰C^`ó#'qXoÿÀæGNžâøÏ/_ää%9ƒÍÌŽ9— ØüÈÉYr›9¹ˆCn`ó#'WqÈl~ää&y€ÍœÜÅ!O°ù‘“§81÷Ñ&·ää%ç³>°ù‘ƒ×Îå>~ŠœœÄ!g°ù‘“³8ä6?rr'æªê'%ENnâØüÈÉ]r›9yˆC`ó#'Oqȼ_‡¼ÄyÙüá¹qÿbÎÑyÍœœÄáüò6?rr‡œÀÇÏ‘“‹8ä 6?rr‡\ÀûuÈMœ—ÍÏž“»81×ÜQ?9+[nNâØüÈÉSr›9y‰C`ó#£6çòï×!'q^6xNÎâÄZ‚žøùFN.â€O?¿'~¾‘“«8ä>~‰œÜÄ!gð~r‡\Àæ'ÏÉCœ—ÍÏž“§8ä 6?rò‡ÜÀæGÎ_8—;ØüÈÉIòï×!gq^6¿{N.â'ØüÈÉUò›9¹‰Ãu ØüÈÉ]r¿FNâ3x¿yŠó²ùÉsò‡\ÀæGfÍÄœËl~ää$¹ÍœœÅ!wð~r‡<Àæ7ÏÉUœ—Íïž“›8ä 6?rr‡¼ÀæGNâpÈ6?rò‡œÀûuÈKr¿}žƒY31ç‡ÍOž““8ä6?rr‡\ÁæGN.âØüÈÉUrï×!7qÈl~óœÜÅyÙüî9yˆCž`ó#'OqÈ l~ää%×|àý:`ÖR̹œÀæ/ÏÉIr{û[Šö³–çeß>-Çöa-¹€}û·ÛŸµ8ä öÏ·ÉçËZʧÜÀþýl-¾Ÿ¬¥À!w°ÿ[ïÿ]ÛÓÿ¿ì¿¯6â÷u×ötáößo“ßï]Û3„'Ø÷'mÅþä®íQ^`ß¿õ/öowmÏ >ã ÞSì?{Šý'k/pÈ ìûç.ûgÖ^à¼ìÇ‹^âxÁµ=pÈìÇ£^ãxÄZMR.`?>öÇGÖjà+Ø×½Çñšµ8äöþ@gÿÊxŠCî`ïotö¯Œ—8/{¦³uø®íQ`ï ö¯Œ“8ä öþÞ`ÿÊ8‹C^`ïOö¯Œ‹8\ò½¿:Ø¿2®â™{xHÿ™µ8/{~p|dÜÅ!g°ÇGÆCrûxdp|d<Å!W°†Œ¸¶™¹×X/2æÚs.w°Y/'q^öñæäøÈ8‹C`ÿNÿÞµ=Cx‚}|Íú¸ŠCf~ÇûÌÉM®ùÀ·žÀœÜÅ!'ð­o0'q^¾õæä)9ƒo}†9y‰Cf~ëEÌÁ\ÛcÎå ¾õ¨.õ¨Îµ=pÈ |ë]ÌÉYœ—o=9¹ˆCîà[¯cN®â™ßú!sr‡<Á·>ÉœÜÅ!/ð­2'q¸äßú*sòçå[¿eN^â™ßzòÍ®í9ŽsßzõÍÁIrßzøÍÁYrßzûÍÁErßúÿÍÁUœ—Í/‘ƒ›8ä6?GîâØü9xˆCž`ó¿ÈÁSòJ^âpÈ6Dn̵=æü°ù=rp‡œÀæ·ÈÁYr›_#qÈl¾äà*¹‚ÍO‘ƒ›8ä6ÿ‹ÜÅyùø§Nrsð‡ÜÁæÏÈÁSò›/9x‰Cž`ó[äÆwmÏ^`ókäà$×|`óKäà,ÎËæçÈÁEr›/9¸ŠCÎàã÷%¹q‡\ÀæOÉ»8ä 6Hn<Ä9|O<5ÅÿàìµÿØkéB[[ÂÇʸÕN€äÉ(ƒ'ÄØ"—ó‚ÿý?v[Ùt;frg)g°Ô;e Á¦Wg ÿ»×9¦Õ±¤²Æ.ã.M°¥Btl™‡R}Äôg©2,]âá­Å”‰í¦û]ŽiåþXŠÍi{œR²aL»ËÁ[LG›ÿ˃;Ø8°ràf¨?¨~2EáÔv2ÜZ8رxn~­cÆ"§u2KLÝÁ¾¬ïDv‰Î¹–¹Õ­à0c~;´·ý<ò¬ÇL ¯³öÐøÎÖ&:ä6¿GnŒbœË¼pÇø¬ÿ5Þ?8‹Cf¾_‡\Ä!°ùÃsr<x¿¹‰Cîàý:ä.9ƒÍŸž“‡8à±ÀûuÈSrï×!/qÈlþòŒ_(rg¾_‡œÄ!7ð~r‡œÁûuÈEpc~ü3èbN®âx¿¹‰CÎàý:ä.øüö ^gíêÍÉCrï×!Oqȼ_‡¼Ä— 6?r0ŠYp.7ð~r‡œÀûuÈYpžàý:ä"¹Í/ž“«8äÞ¯Cnâ€íwÑ›øMü.¹‚ͯž“‡8äÞ¯Cžâ€¿ Þ¯C^â™›ß<ã( çrï×!'q00>Gÿ5’øIü,ÎËûuÈEœ—Íïž“»8ä6xN^âpû|`ó§ç`_à\N`ó—çä.9ƒ_>ÏÉKr›Ÿ<¯Îå 6?{NîâØüâ9y‰Cî`ó«çÍîoù•ë°ùÍsr§ß缾ùÝsò‡¼ÀæÏÁ©„Cþ/›?='wqúý­›¿<'/qÈ|üúyÎ%œËl~òœÜÅñý‰±ùÙsò‡ÜÀûuÀ˜<†óÃæÏÉEr›_='wqÈl~óœ¼ÄYw_j¼_\¿p~Øüî9¹ˆC^`ó‡çä.øÜÒöc¬NÏÉKœuÆûuÀì#™óÃæ/ÏÉEr¿}ž“»8ä6?yN^â+x¿˜}s~Øüì9¹ˆãÇkcó‹çä.¹ƒÍ¯ž“—8äÞ¯æ1Îœ6¿yN.âxßÃØüî9¹‹C^`ó‡çä%ûcx¿x~áü°ùÓsr‡œÀæ/ÏÉ]r¾w.gíùÍÉKrïׯ/œ6?yN.â+Ø|¿£ñå.¹Í/ž“—8äÞ¯cŒ{•Âùeó«çä"y€Íož“»8ä 6¿{N^âx¿8}áü°ùÃsr|Žk‰ÇÓsÏjæä.9Í_ž“—8>6ɉÇSqÀ¨2ÁùáãÏsr‡\Àæ'ÏÉ]rï×!q^6?{N^âx¿˜Çhs~Øüâ9¹ˆCî`ó«çä.y€÷ë‡8/›ß<'/qȼ_Ìcº9?l~÷œ\Ä!/°ùÃsr‡có¼_‡<ÄyÙüé9y‰CNàý:`öÌùaó—çä"9ƒo÷bgÜÅ!ð~òçeó“çä%¹‚÷ë€Ùg0ç‡ÍÏž“‹8ä6¿xNîâ;x¿yˆó²ùÕsò‡<ÀûuÀìc˜óÃæ7ÏÉEò›ß='wqÈ ¼_‡<ÄyÙüá9y‰>ÇñÄþ‰8`öIÌùaó§çä"9Í_ž“»8ä Þ¯Câ¼|üõyN^â x¿˜}s~Øüä9¹ˆC®`ó³çä.¹÷ë‡8/›_<'/qȼ_Ç8³Ïsœ_6¿zN.âØüæ9¹‹Cžàý:ä!ÎËæwÏÉKòïק/œ6xN.â€O?$³¿$¹Šóò~rçeßþÈÉ]rßï'sòçåûûeNžâ¼|÷‡ÌÉKŸ_È9Åñ‚98áüð=žæÛß3Nâ¼|û3ÌÉYœ—o9¹ˆC.àÛfN®â¼|Ç ÌÉMœ—ïøˆ9¹‹C®à;dNâ¼|ÇËÌÉSœ—o}€9y‰Cnà[É·u˜}Zs~øÖ—ò­G'q^¾õ4æä,ÎË·Èœ\Ä!wð­g2'Wq^fýöæä&Îˬ?ßœÜÅ!0ëç7'q^6?yNžâ¼|ü4='/qÈÌÍožƒÙ‡7ç‡ÍOž““8/ÿ‹œœÅyÙüæ9¹ˆC^`ó“çä*ÎËþ¹–•çà&ÎËæ·ÈÁ]Îÿ~`óSäà!ÎËÇ·}òͧ8/›ß$7^âö%-ÕÿœêÿÁâ?™Ó©¶¯æ¸&ŽYXPr¶wç\|-W[Æ°¥t;ø±®ÿç0–xùlÈŸÇ™rHÜõ¤|Juwˆne>Ö†ôßô]ɇ(Ó³‹ie¦;5¢thåãÎöfqV›ˆ÷Ž±µšƒ…ƒ©3qéƒ2k'¸­ÓÎÁ—uÀøX+¤ îä­S=ÿ“/ì´Ü–ÞNÅg–_¬~«3:fÞ~.ø8+×JºWthàÿ9sµZNàUx‘7q|åZI÷ Crã.Ž¯\+°U„áq|åZIÝW,zžâ¼l~Š¼Ä!°ù9rc.c2çro,ÆñœÄ!7°ù5rp‡ÌÜü9¸ˆC.`óGäà*ÎËæÏÈÁMro,bòÜÅ!'ðÙ‰|Ÿçä!™ùÆ*㛓§8¼²Ño,Œº9y‰CžàUÒ7sù—9?¼± ûæä$Ž/S+‰g |Ãsr‡ÜÁ«ÈoN.âxc•úÍÉU¿rUI÷ŒÏsrÇW,–tÏHž“»8/o¬â¿9yˆCÎà³nNžâxã,„›“—8ä¼±hîæàõ…³|EjI÷Œá99‰Cžà³4nNÎâ¼¼qÈÍÉEòo,¼9¹ŠCîà³XnNnâøŠã’xÆ@®ž“»8dægáÜœ<Ä!ðÆY>7'Oq^Þ8‹èæä%9ƒ7ÎRº¹1yæ8'ðÆYP7''q|uyɼâE‰œœÅáÂÏÞ8‹ëæä"y‚7λ9¹ŠóòÆYh7'7qÈl~÷œÜÅñ³ .ç,º›“‡8ä6zNžâø2Ü’yÅ‹²<'/q^>~Mžƒãj Ál~öœœÄñ³CJæ/$'gqÈ l~õœ\Ä!`ó›çä*Ž_ùµ°Tìsá/ÀMœ—ÍŸž“»8dææGNâø²ìÂP±ïyò3n ‹;tÈl~òœ¼Ä!7°ùÅs0Ï0çr›_=''q^6¿yNÎâ Øüî9¹ˆãKÉ @g5ýÍÉU¿rsaèœ~srÇÏØ+,•þyNîâ€ó›Ÿ<'q^6?{Nžâ'Øüê9y‰C`ó›ç`^ ÔœËl~÷œœÄ!7°ùÃsr‡\ÁæOÏÉEœ—ú™ÌÉUr›Ÿ<'7qÈl~öœÜÅ!'°ùÅsò‡üÍož“§8<£zÍïž“—8/›?<ój æ\žàý:ä$ŽŸ]]XBxÅ p‡Ì|¿¹ˆCn`ß>¼â¸ŠãwN(,•Q='7q^öÏ‹W¼wqÈÌýûÀ+^€‡8dæþ}ã/ÀS2óý:ä%ùû÷ŸW¼0æ):IøŒ;2¯xÑ—çä$ÎËþ{ä/ÀY2sÿ½ó$p‡ÌÜ÷'¼â¸Šãw>)™W¼‡ÜÄñ+^”Ì+^ôæ9¹‹ó²ï?yÅ ð‡ÌÜüâ9yŠCfîûs^ñ¼Ä!3÷ã¯xa|¯r‘…™ï×!'qÈØ_¼â8‹ó²yÅ pÇøt÷Kîrüírüå]nà™›?<'7qüŠ5%óŠÖà/À]2óý:ä!¹½Â+^€§8/{ÿ‡W¼/qÈ̽Õ¥Żܘs™¹ùÙsrÇOí+™W¼°>O gqÈÌ÷ë‹8äìýOž®â¼ìý[^ñÜÄ᧘{ÿyHÿ™w¹CfîýsÖ¯ÀC2óý:ä)¹ƒÍïž“—8äöñëWƼ*êüÿa¿°~NâøÕÅJž2>š2>âUTá™ûø‹õ+p‡Ì|¿¹ŠCN`²~nâøãJž~Åš›“»8/ûø”õ+ð<˜ûøwÊø—W]…CfîãëéW¬)™W]…Cf¾_Ì«®åöñ>ëWà$¹Íož“³8/{ýõ+p‡ÌÜëKê¼J+2s¯Ÿ°~nâøKfýJr‡œÀ^Ïaý <Ä!`¯±~žâ¼lõ¨å9y‰îÌoý*Kýªð*­Çqf~ëcÌÉI2óý:ä,¹ƒo½®Ü+¶q^¾õÀr¯Øj\ÅyùÖ˽b«q§IÛXŸ,ž“»8]Þ{÷úg¹Wl5â Ù¶Cü!þ'>ßr¯Øš<'/q–—ʽbkä`^¥ÕœË|ëÉÌÉIœä¿ÂúÕ71'gqâ÷[X¿‡\Ä)¾¯(¬_qsr§ú¾¨°~•"'7qüꞥ°~•šçä.NìŸ ëW©zNâ ?Ö¯Rñœ<Åñ+z–’¦øSü%ÎòcYaý*EæeÌÉqü-¬_qsr'ù±¾°~uÆYÌÉYòÿŒ›˜“‹8ä 6zN®âx¿¹‰Ã¾V›?<'wqÈl~÷œ<Ä!°ùÍsò‡\ÁæWÏÉKœèKÖ¯¾â9˜Wi5çrï×!'qÈl~öœœÅ!/°ùÉsr'ÆJ…õ«Ëÿs®âøÏÏxÎÿ7qÈlþŒÜÅ!WðþqÀCœ Þñ挳nžâøÕÍ—8ä6¿EnÌš•9—'Øü98‰ãW|46¿DÎâø÷.â3Øü9¸ŠC.`óSäà&NÔ¯ ï³¾ÈÁ]rßöÌÁCòï<Å!O°ù3rð'ê“¥ú§<7¾õ«lÇåæWœòœÄ!g°ù-rp‡\Àæ×ÈÁEœ¨?Þ!Gp‡ÜÀæ—ÈÁMr›Ÿ#wqÈl~Š<ĉù…rïóEžâpþˆùñ‡äà%9÷cÌš•9—3Øü98‰C.`óGäà,Ž_ÐØü9¸ˆCfn¾äà*Ž_ÐØü9¸‰ãW4Þ?¸‹s……믬Ÿy×eq8ÿ›ÀæçÈÁS2só%/qÈlþ¹ñˆ9_ç >¾õÛ™ƒ“8äÞ?8‹C`ógäà"NÌ﮿ꒃ«8ä6¿GnâpýÆ6¿EîâØü9xˆë7 ïð£xŠCfn¾äà%¹ÍÏ‘sÍ•9—;Øü98‰C`ó¿ÈÁYœÃ¾àõo³üÇf‰¾ÿ$ß—rm¤Žgm-‹¯X<È[êZ‘•+&mçz' ¬˜tÆÓPù.6¬Q˜ü¢øgƒ¶[ ´ýܰ=V oUMp‚Ë T…‹q1ů©M—ògoe2þD­?Îé¥1*¸üÅ“\:`‡NÛî/nnèÝ”Æî‘ï¦ï´®=6¦s8ŒÇTÇ’© {…¶zKÃgYk>×1-¸±M>×ø,¸±Íåó×!gð~r|º'¸±Íã‹8ä6?{N®â™ï×!7qÀç[‡Û<¹‹Cnàý:ä!9Í/ž“§8à>ÁûuÈKrï×[ „Îå6?rr|~⸱Íã³8dæûuÈEòÞ¯C®â€ë›ß<'7qȼ_‡ÜÅŸC4nló8ä!¹ƒÍïž“§8ä Þ¯C^â€óï×ç/œË ¼_‡œÄ!g°ùÃsr|öœ¸±Íã‹8äÞ¯C®âØüé9¹‰¾ù~r‡\ÁûuÈCrï×!OqŒÏy7¶Éç½7'/qȼ_l%:—?ð~r|Ž†¸±M>×¾99‹C.àý:ä"x,ð~r‡ÜÁûuÈMr›Ÿ<'wqÀ}÷ë‡8äÞ¯Cžâ3Øüì9y‰>Ó鸱Íã€ëÎåÞ¯CNâx¿9‹®l~ñœ\Ä!Wð~r‡œÀûuÈMðéqáÆ6ù\ãùæä.™ù~ò‡ü÷ë§8à<ÀûuÈKœ—ÍožƒÛÎï×!gq^6¿{N.â'x¿¹‹ó²ùÃsò‡¼ÀûuÈKœ—ÍŸžƒûÙ>‹þ…ß?ñ‹8/›¿<'WqÈ ¼_‡ÜÅyùøùóœ<Ä!gð~ðøÂùaó“çä$¹€÷ë‹8/›Ÿ='WqjüvF¿Š/¿¯6¿xNžâx¿x~áü°ùÕsr‡ÜÁûuÈUœ—Íož“›8²¿šMü&þçeó»çä)y‚÷ë€W ç‡Íž“³8äÞ¯C®â¼lþôœÜÄá¾ýï×!Oq^6yN^â¬8v¬%þr7¥€óËÇ?ûæä,9ƒ÷ë›8/›Ÿ<'wqȼ_‡<ÅyÙüì9y‰³üX<8œr8?l~ñœ\Ä!7ð~rçeó«çä.¹ƒ÷ë‡8/ûçÅñxŠóòýþ3'/q^¾û+æ`Œ­à\à»ÿgNNâ¼|×ÌÉYœ—oÿŠ9¹ˆ}¹qÇ_Ësrçå;~wüeÜÄyùÖCFŽú nºp—÷© -ÏÉC2só›çä)ÎËæ'ÏÉKœ—?§ç`Ž¹Ì!ŸZÄÀøë*nNNâ¼l~òœœÅyùøgª„9¹ˆó²ùÕsr‡œÀæGNnâ¼|ü><'wq^6¿xNâ3ØüÏsòçåãŸr5sòçeó‹çà;æÊÿ_>¾}îÈÉIr›ß<'gq^6?{N.â¼|üsgN®â+Øüæ9¹‰ó²ùÉsrçåãçé9yˆó²ù‘“§8ä6?yN^â¼|ü3an1¦þeó«çä$¹ƒÍÿ<'gq^>þ7<'q^6¿xN®â¼üç7Ûg27qÈl¾äà.ÎËæçÈÁCœ—?Wäà)y‚Ío‘ƒ—8/›Ÿ#7îQ?ùåãÉÁIœ—Ío‘ƒ³8ä6?E.â¼|ü>#Wq^6¿Fnâ¾Ón§ÿõŸÓ‚ÔÿÃZîé3RsàïÅö«öX›v˽F¤×(z:Ã-ÚÎø;Ï|v¿I+Œ-? ã.±|qì¬8ŠAÚw&:•gLW üv`¹“‡9‘R­³Ï‚} hîÔO:'FŒÙþ(0t+^2_%èÑæÿž¯×.b7r-öŸ<“•$øÊ6<^,©G·øTë½ËòY—ïò‹C•_ïáÓ¾vì*ÙR¾{”9IJOƒÃu¼K~Å£<äíÇ´žÝªÊî­²ÿÏn-lü?çþ‚ÏVmÖ-µ[‡cœÅyùøý‹\Ä!O°ù9rpçeó[äà&ÎËæÈÁ]2óã/rðçeósäà)¹ƒÍo‘ƒ—8/›?"7._8?|üókº98‰Cn`ósäà,ÎËæK.â+Øü9¸Šóòñ×9¸‰ó²ù9rp‡\Àæ·ÈÁCœ—Í‘ƒ§8ä þómOÂœ¼ÄyÙüÈÁõ ç‡Í¯ž““8ä6xNÎâ¼lþòœ\Ä!àã§ì9¹Šó²ùÕsrçeó‡çä.¸,°ùËsòçåãçì9yŠó²ùÕsò‡<ÁæÏÁí ç‡Í_ž““8ä>þ)í0'gq^6¿zN.â¼l~ää*¹ƒÍ_ž“›8/ß¾·ÈÉ]r›_='q^6xNžâ¼lþòœ¼Ä!Wðñ[öÜ¿p~ØüÈÉIr›?<'gq^6yN.â¼||;æ"'WqÈÌͯž“›8/›?<'wqÈ lþòœ<ÄyùøvÌENžâ¼l~õœ¼Ä!`ó‡çàñ…óÃæ/ÏÉIpf~|;æ"'gq^6¿zN.â¼lþðœ\Å!O°ù‘“›8/ߎ¹ÈÉ]ò›_='q^6?ròçeó—çä%¹ƒÿüiÇ\äàù…óÃæWÏÉIr›?<'gq^6yN.â¼||;æ"'WqÈl~õœÜÄyÙüá9¹‹C.`ó—çä!ÎËÇ·c.ròçeó“çä%9ƒ÷ë€W ç2só?ÏÉEœ—ýý®ïwUqÈx¿¹‹¾¹ùÓsòçeÿ¼“—8ä Þ¯cŒ%œpœ™›ïË?/q^6¿yN®âû?.Û|r‡ìË0ñfNžâ¼l¾/«¼¼Ä!û²ÊǧÎeæ÷÷Èœ\ÄyÙüä9¹ŠCÎÿ¸ìñqÈ]2só?ÏÉSœ—ïþ‡9y‰CþþqYâã€Y+0‡|só§çä"ÎËwÿÉ|ƲÁë¹Tp¿¹‹Cfn~÷œ<ÅyÙüæ9y‰Cîÿ¸¬ïqÀk›óÃ÷øÂœœÅyy¿¹ˆSâ½nO_¾wY¶!ËߪøUü&N‹ï*Æãê»8ò[.Ý¿ÌÉCœû"ŒÇÕ!Oq¦ï{±LïÏñªæå%N;°LïqÀƒ›S£?€ezCNâç?.Óûs>ÏÉYöç¹do¿¹ˆýùÎñøéó0'Wqb¼Ö9‡ÜÄ!Ï\¦÷8ä.Çæé—éý9‘“‡8Qoé‹CžâD=­s<¾†çä%yþã2½Çs nÙ–Lr<.ΈZðuÈl~÷œœÅ!3߯C.â}YߟÓ<'WqXMàý:ä&¹€÷ë»8d.'¼ýyæä!™K÷ë§8¬‹&°ùÅsò‡Ì|¿˜cð¡Üÿq™áã“8ä ¾ãæä,ë¢ ¼_‡\Ä!—\ÆøçDN®âû?.c|r‡<ÁûuÈ]ÖE}ÙãŸãË/qÈœIÙ¯Cžâ;øŽ7™“—8ä Þ¯æÜŽ»?.¥Ü¯CNâ}YåŸ3#gqȼp‡ÌüŽÇ»ŒÇ;ÇÚpXMÿ¸ óuÀMrïÜÅ!w°ù=rð‡<ÿq™ç뀧8¬‹¦\æùç´ÈÁKrïgúRÐ$KD—F~á3Ÿ¾ô:äùËBQ3¹98‹Ãºhï\Ä!°ù%rp‡ìËN_ÜÄ!Ï\vú:à.ë¢ |ëK7qÈå—©¾xŠCæÒTóSäà%y‚÷c¼¾pÈùþqÀIrùÇe°Î98‹Cîÿ¸ öuÀEòßúÞ͇/•½ë¢é—;Îð¥²×!—\6û:Ãg½¯Cî`ógäà!™ùþq†/˽ë¢é—å¢æé¹ñ‡\þqYîc3øŸ;à»láÌ9ÿçTÒúæædŒ3F÷ÇJÍÇ–-ð`’8Agt£Ó­øÊ‚Ö♹Yxk)ŠR6ù°¤sÊâGõó1©Ø9™lË Št¾8Šó‘0¡zy·Í¶³ÿ¼HƒI<îP?+Bg?ÀÞ –óC¿“?6)ÍŽj·ü¼ÖÿÓ?÷0oKZLƒqÈÝhænÔJ0ø¨lªæþœb [åõ»+9¯Ì¯©Ò» ¼c|j<ÏífÙO‘‡ð]oÿy7ÅâÔ5j²ñ¯Zå¿ÿ×nt`r;ðx¬˜Õ~C‹jŸø_Ãê¸`ÛüüË6ò‘m{ý½ãjå¼°î¿Òwm{|hé>§ý×^fá…Ñ~N¢ÿi˜B· §¿ÈzN¢ˆ¿y¥Šˆù†8áöÜR§ÛÚ›Ex2[‹q´rÁFWç_Ö ?²½Âß3¢#3/¬û¯óvØiO÷ ŒðcýîˬhÃø‡…å»V¬*?ÖgŸGbYŒQñ·‡}T=™? ºÑÚøoXËäïîb`KºlbvnˆÙøþg½¹!f↘7Äü¸!ëþ뼉éobú›ÀsÚÛ}@÷#}V|©‡¬”õg§/‘–íþþ¹l÷ç/ë/ý5cYGq^X÷_ç…`ŸÇâ“žó•_›(}vض– ¾Zú:_îøz¤åÿÅSŽx!õ„›±›€ûšŸGááç™p“±áÔü¿ÕQýiª?7Ú‹›ô˜i›Àmm³g´átZþ_4ýìÄ繸ü á6çQ¸áÂy&ÜŠ`85ÿoõGTšêÏöâ"Òö:¸$ÅñTÛSõûÖqá{õÿŒìÈy¾ø —÷°gÂÕ=ðUB|kºœGáê=FVɱÿÚ¡ÉaÕÐÓ \eo:-ÿ¯m <¯X1˜þü׈ýaEa:Zö“L§ hbPl¢šüáÿŒ[Ä q÷ø¼£:îVª¾½ªm¯óßf²óˆ–¼íM^–ýD¼Û±=ú[óEFãnOÌyŸGà |¶'ÖuL§åÿµÍÅiòäÏœ¾=ñŠkD‹ZáfeMV4¬ñ=pÄæCýÒhTÿÞáä$#;°v§fôñÝaaðy4–€ÿ¯uÎ{v˜¿ÏŒ÷Zþ_k0b­ÄóQ8üüíQ<äŸçŸVu;¯9½í8d§Ù?o‘uBºgÃ<£“•ÛJ<ßÙ¬Ó:Ok\²æàßÖÈíÅ Bøî£ðŠØêsy{çݪsÝí6—¿‡…Õ˜x*tõ“çHÑWý~Rô±R`.”|f­É_ºOlÈŸãznÎx7eþªSãFÍßýŠäoÜM@ü¯Ç|¢ÙîÃï{Ì)ñ}çdó;vCp̬$GûZædÅ´¸ãpwjvgãÎ'Âm…ΓãR5ß{•ÛËXÙ÷’ïøèí™í'-ÿïÙœ|Ú3ñä&àí~œ9ù†Å¥bÍ-Ñ¡d|šR¼y¸´Ñð·ÑoCqß{ãí6´ü¿hGÖE›ñä&à׈YC[4´%ÿà[CíyMNhòßëw?úù‹ñÁaU°‘ ºÓùàÐs=O„îéyr gŒªÿ·°¿•±rö>3¶hùíír fòçöìÂí±²=جÒíÃûcŒ-õæõæTnCq½{Dº Ew:-ÿ¯µ£{ŸÏlÞP¼â’×ôÎrŽÞrŽîrŽþr5t6Oƒ„ý`ÿÜù±'ÙËýœî©ÉMšŸ? þϸF\‡ÅŸ6}“NÿÌy7é´ÁÐyÄúˆç_=¾¼û_yUöÉò²m:–ÿ×6‚çìÞiÎè5Û£{|åûøì¤æÿ­þˆêOSý¹­½}{uJǵ £˜ýïñ÷Ì™ã^P,ÙMBÊm/ufBïè½zÞèΆ¨ÝÖJÃé\šìÞÀîÅü½n¾='ó—÷ÂavÕÓrý œø¥Çœªÿ×®9—§7Ö ¼Ê(îè}çŸ ÀUì8xù:\ÜoáÍÿÚ›ÆC0°ÿ–cº©¿U>ªZÇõóÿïÿù¿ÿö&ŽSendstream endobj 6 0 obj 63857 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:57-07:00 2013-08-20T08:41:57-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000064153 00000 n 0000065723 00000 n 0000064094 00000 n 0000063963 00000 n 0000000015 00000 n 0000063942 00000 n 0000064217 00000 n 0000064258 00000 n 0000064287 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<0A870FDC00AC23A2E3061A918990C4F1><0A870FDC00AC23A2E3061A918990C4F1>] >> startxref 65893 %%EOF ast-8.3.0/sun210_figures/fsexample.pdf0000664000175000017500000004246413004147321014474 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}_¬·ÛQ!¦”m D#!\´ûÂb`Ÿwý_oB¤ˆ1€$Ö¤ÑÐ|ò§v4€ˆQˆÄZLL¼ðB¼àBH.­jÚ Üxi iM{QI¸°ǃ¦ÂŽó<ÏÌz×o'&„ SHÏ÷›µ×»þÌš5kfÖÌšï½?Òýÿ÷Ÿ=¿{é/ûïúþ»ã¡õZ[¹ÿ®»2g}Hí>÷žJ»~•Ìqàß2R}8íߣÚwöo;nàgwµâÓ¼JïrÉö#­’žRuµ¹`ïõÙ]”Xïüòq•¤¡’hó´Rë÷ÑkÀÏîbdQòxc’˜[´pôúìî;ÿÌ]"Z¾¹Ï#‡!´xÉ™þ-½ =ÇY‰–Z3ÿu؆3;f°JïÒŽ(•Lΰ®6ì½>»‹’jõ´6VZØV´9j P½lã¦V‰¡ÅÇ~}ãsó6Ž^‰–yÿƒ†šo´ÿýÍ»ãþÏEOPôÝw߶o¬”réåC~•¤Ò0ôt”„sÎDš+`ÛXYE‰ +Ý|’ó¡½áM.Ø;}v%iN {3JÆ`Þdê“MDŸ?»‹qE‰-’¥(™U‹äm¦Ñœ–O§¥æ˜‘EÉã]Œ=JbnÑ悽W¡¥c_}/7xá^2z9ò‘²u÷ž»rZGÙ&c´eøÉFy970 €V9û˜IÁÏò¦ÿ>òÃÈ@ ã°a¡@é4Æ3Á¤l¢¨8óCÇÑ¥ NVïÙÝU2yÖ´ñÐùÁðÄiVÊ)¼áói'Oéê*þŽAصlm³™®‰Mßõâ;¼Ö«YzÇg¶ámTü|-ªJ·’y>bnþÑU`øè(±¿X'¶NP³¿7Ÿ~ûølÉ¿$ÔžVÏÈ äž_çCMú Ú)Ÿþ';|çÁ¿%`¶‚?Úñ=ÈŽm\µcÒ¶ŽÃÆc8ë ákhô$ªm་4¼äÑèÇvV5jJ'P5N£˜šŽˆ€7¨ˆ³Vãçu¢‘‘1Ššˆ+ÙŽŽA® È(ˆíä¬uìÆ:­‰³ˆbp © í_Ì* TÛ¶4/‚ªn%F‡\/8iœbxê`ýa°]BFƒ ²Ìø¦ù¤ŒlìßjâN«€í[ÒÓ¹Õh§[‡Áã¶åÏ<“Œš°°Ø³F#ÕÈZD°¶¦uœ½/ÐªÛ À 7xÇö¨hÝf¬å*<þ«Ñ†/uEë]”â0†oôzä«F3d °<Þ¢›Nd-FmªØð91ëçV2À¬ ?L°fBB*Èý¾Ù@Î~ >›`ÙÓ‚ŸÙ9v¸×à_ÁøÛÖ+a=QÓñ×3;J"4[Ëfhèk:ù¾™ø<9|ÁömšâéQÃèprsÛº ×cƒ:®’j‡ñ´6$¶)iÌc£‰ ¶/L8I5^#Û¢ætµ°àfÔÈQ]%¥åióp²1zh¹k Hs-×Xcµç=úkc÷Ù@ëÎÇ£›£ WèHí Vè‚íƒ $¥«hUDn_Î Öpí‹UbSæ¡…N8F“¬0&;Š&þn’¡¿%ÃL"—í•H;Šñ,Š^)ñDmcŒeøoãn-“ÄOñˆlˆ:&ÈÒx§f<[‡Ž`kÖ´ñ U°áÞ 8 0n?¥†è»áŒ§j¨q·=¯ ý¶ ãÇå*eƒ#€/=Ø1Д“Ã²^Å~RÁÖ1ªàñ~ÆršˆÜ|HÆAš }.PSê5]ȺÁO“ÿ6>yrK2YÒØVY$U‘Æ`‹SRìênUÊ9ƒá7ì=bžåw›ÎR±|5o;Ñ°¡ßÁò9ËïbÊÄF'ž‹çG'Ó¿JÈæ{í·?ƒÛwCX³LW/ö›Ý£A œŸEÆÝdŒ)Þ}`×uËÜ6žõèâFƒŠÃ}Ô'vIG"klõí¸h×ß{Ó1aÄ¡ßÔ˜õ“ƒ{$ÀQ›¨Ð­Ûî½Uò¡ 5W ñ1Žäx.A2;½E;<úY.eC…"ABÑÙÀg‰!C·Å9ãpï@Ñ@mIBãÛŒãÔq(‚šË…´‘!ÉÊô›HÒOG78Î=¾w¬KÃh¿hŽŽ¥«Dh±®éEbæ°%­AEմשžÆäï…!v$O~EH²Î(CºÎ—)rlЀÿý‰bPé'ù#Q@„BE¬âÅk·9¯Ì(ÆD¼së¡Û°Ô¤×¨8ŽÐ@‹¸vytÁÍ?Aü,6©Ò”ªçV’œžmŒ&\ÌÜ|ïò¬Ÿ¦ø>Ä O2·ÆÓ3·žÎã~œ” 4ªÁ©1Œšˆ«d,Ó°}‰Í†³Ö <# ˜Ù´iô Ö ªŽé ¬`ôÜ]$‚YŠŸhƬp2í˜aÓP°­z‚^}¡h:vŽyø¡îËd'­]ÞÃŽÈ®£#Kû¾•´…yH¼Ni“ó:WÛŸäQîÉ «4NJ!83”*±XNh@Ê*ëÀ^ó‰}Ú¢žÛßMfqΰӀÔ%FÒ3!&¬ùš¸]| ¶umXY}à%%ˆïµ£Œ–Ó¯>­;òùÝ×½ãî¥wü¥û¿õ}?ðw/½ÓjݽôîÏq÷Ò×}ËÛïÓÝK_ÿ®twüµ»—¾á¥·¿ý ü–¯ùš—þâýWÛ_Þþ¾Çxþ=ßoŸ¼ímwïøúû¯øWÿçŸþ•·ÿ“ßøÀÏÿüGÿ÷G_ûÿßïôŸ½å ¿ô÷~ã·~èmoùâ÷ÿÆoýνå‹ÿѯþ·ßù;Ÿ÷#o¼ûsï¸ÿÖûtfȤP°s¦ôùUbz›Lr§,95Óœf*Í^CËRνĔë1n¾É}ÒÈm.Ø{µ6¢ä˜3L*9‡ÁÞæœnÖð^†Ú©‘E‰©ž>ö(‰¹E›k®ÞëeÜmISÊ3lÞQÍVš©~¤ê6²’d¹phÉç^´dGJr/iosÁÞ+Ðâ%©…ÝQ•æ(ƒ1¼ƒö($ÕåÅÿf¢÷Äo7ôÙŒl,Öl“9ÊJN(* 6AÈ׳Ñe£n”fƒAʨ8Ë µHÅKü<±IÂì€âƒ&Ì!{ÀÇ Õ·Ï'Ž3+)‰1E`Â8eʘ D ÅA#ª“_ά…í¼È“] DTý%h²dF‰¨æÌ°E½ª>J’LS ##Wƒ§£æ€Ì2N9ˆs¶ëS€MÇý™š&CÀÄ%OÒy%_ƒÌú^£q,˜¸-‰Á´O‘$hŸÊg¡%Èú¨™ÎB IVdzÐ$0¾06¥­F£ ÊàI‚X°É*4R]%£‘'µTvÑIAsÐ&® GøýàZ.Âèe³R•£ª8A±†•ªÀ3U2•‹c%²S¡$wܸš”ìðA†ªÃä µ°í5€ F!À$XYª4LvÙÇ â¨.Vò´Ï 6ö¶ªcÒƒçn”äz(`S·­ã 6j®’:!Ö åpž¡Ôã “νƄ%jk!àÖdªÚJ&É`›yÁt ½Š á8«/MÃôØa›‹?]à|(1 Ø$a¢@wG© ²' °V­’£Ç`›ò˜¬ã‹(áe$wÕ¤µ*åÒ5ª”špg èÄ`ðgÛ-UxÃþAYæÜ“›(q£;`ì¯ cíóÈ@W—Å*MfçL:¡£ú™™T]¸5 Ï9i::Ò¦hÝJÖŠ5Ö8qÄ\ Àº¸wag§LV«†9¸„1,ÓnŠßžÄvB·âJ´Yèp<¾DµËh…Q‘¯œ²Z9ìÓêu«uˆ 7%¥‹ë"s´'I×ò‘@‹M×N?akóƒ¡ÀX1â\XP :Ç®cÁàS»²äâXpÐAŽ63ê:¢Ÿu*¬1štô'¿ã8°ÑO]ûjå [70µIÆÿr,Â.¸í™äí ;±à–.Ím3¢_¢‰{¯¤thkujœ×P½-õ¡‰o²Ÿ-FÐ4¯×bŒaø¸ûÂU¶!ã±Nx=¸¡i•8nºÎ°§àÂV‚êg§Í:µr!‹ÀB– …,…¬ÔhÉ"²*Õ`ʲºÕ³¤-ÇV×Á°ÑO?9¶ì4Êu«1¡Ë6§Ž.þ^èš<üukŠ6fÛÐeL¬Þ`Ë „œÀ6ŸBV :À¬ÔÔ}1å[ÝŒéÀ“ ˜ðye*PbRÁ)WËuL¥IƒÖuL]ˆˆ¾b8œqÎ¥F“1ᘭ°i©î`MŸy¨[v0¾u‘\MZ ó'8žoÿèAL·ØäÊY-+H"pÛÆÞ n »Þ`ƒYÖ¡€\Ïï5$`X v’u­gð”I«à $¾`bÚuÏG)T.$#¡Sâ6ø Y‹‹Ì` $AQCÆ!âGíZ6…®æ •'>J¦ s»TQr=$D Ë•÷±ÅÞW Xü=¿ç–ó³#Ëf´.ÐFǹÕp´'SRÐc9ªæ s¡L[%sÖFÏùÛ% Ÿ“¤ÝuÀ¯9-Äzî5$WRˆ(SXI]¨tÜ ÙjhÖÛ·‹µæn7ñ®­¤^.c³2páöž$ ¨,\½ÓÂuþ,\½»…ë'~ùMíOÉW¼ñÍ_òÖ/ø‡o~ÿo¾ñ}ö oyãø—Ÿú¦·ýø§?òoßó;ïüù¿÷Îþ‹7ÜýÏWÿµW?þÚ/üîï~üc?ÿSøø¾÷¿üU_øí?öÏ_þö}Ñ»ÿõñ¡/ý²w½ë‡Þúá¼úÉW^}í•ÿõ­Ÿþ7¿ÿ©O¼üê{?ñòO}è—Ž_üÊöï^~ß~èCüØ—ýÕwû/ÿú‘Ï»ÿü×5Œy˜ÆmêóUÒ³{6®°ÏÓ%ÅÐH¡ÙÁgwéÔ!ìw J๠’©ñø7Ú 8z„¯Jhת“¾6*Á¦EÞb8+F—›œá£Š}ØËiÒ§åM}.“˜ ¿´ª´Ñä}º™¥%yÈ©}ÛDg+øHò—S&sÒÉhÄ€Ž Ú Ø;:Tn«¤¿X÷—[Ÿw°áž ã*>4ì(‰iE›G¯ËÓñs „¼Ž)ÌNá ûFOtU›Fã¦[õ¤}ÐAÊfÂuªiQ'\¾:/M!×áw;uýóìŽ`=§Ì`‚¦_Žáîĸ¼Axsì}Ô©K‹g«×Ê«^cԸ∎¦dpÏà[Þ‹O«„ŽÀ¡ù[C@›—Ù×ßø×?ðÉðO^ß·¢»˜%Þ>l&ÒfËQj/x¼ f¦ ‡¦oöZJpmÏ‹þ ¸0X úqbPÄ­ .¡½']>ãqhžÔóð;h³è/°¹LûYýR>S¾Äµ5ÚDåBO 8 :J)ð˜¡ë‚Íd[eû Úð?ixiËÜœ÷ì'¶€/WAUH€P{ÒF·ë6ÈÉ“R¨àª°–žS_V®¦®¢:ÕêWÑQ5}j‰£„„B—†2žB^ãbû$éô,'‘NóßØm…íž™„1ºº™¤1z=` áhD·º#ü쎮€­ï5‚9Ë+NW° ™¼ RÛüZõKÂÔ!mtuÿ˜©OŒ2­ÓW [Ò¬$‚ žôzÁ^ÒG8Ǫ³~Ñä&¼fâ϶[¥ë‰VЉ¡µÍÚ•Sa)nu&8Lð=Á(ê”_Ã#J(æ „¤&!A¨|4zƒRø¾¨ÚÄyÐÆ*c!à°gï«èF¤4º Ø~…§‹Ã˜p÷ã"jTêC תò+lD Ò»Júëdûlu[‰«ÍÆ[æ€ÙGƒ­ëªaRcÏ[ ºŒâ /£Gqç–žH9ôÒÃ6†Ÿ˜Ó\°,Ãά¿6+Z°MµkD,©¼-–Z&•¸ÿä¤óœÃøâ„ä±ÕÀÖE ãhsƒ}ÄüB%%îýØ‹|…b\T‡àV&·† cWƒCgUÐ׬ m“ +fãæv Ú–l¾(‰ìB.6ˆ<èu˜Üß -Ø­bþw¨ öõÁƒãFõó‘[½çP›.ôèÏé »7oúΆõw#m„½ŒSîÉvdN‹Ùa¡O2!øÚÚþ/œ(a–‘!Mz’‰ ÅH `ŸjÔ¹«Üh{x¹Ág‚Uú‚r¡»\÷IJÀÑò¤7ÅÚßZ²N½±J?Xü?›$£Õù¿é¢‰[NËüìŸÐÅþ:FØ Xæ Ë6Ÿk—Ûþƒý³^Ûw|ØLI[ÅmD3¶íª`«ÀCü†¿kU­±†øè |Mpð,ÇÔàÈ’àýÚnPä%B ¤Æó謚~>á2)¦n˜"˜Ê…–`Š.•&ƶTÑû*~½úÉW>ûÚG?ùÚ+¯½ú{ß÷ƒ¯}â•Ïþâßï/|öÇ~õ¯üÝøÍò®7üå÷}ìc{õÑówàG¿ô˾êýïüÚ?öy_+“ìTÝcóFžòßê©Jõ×¥S-­5ÑÃfdäHè”ómw="´JbØó»‘Ü Tä:Po¦„µbç…[,–Ð"XµvzdÚ™Õ^Âf†l˜î=ºÊ4溿Ç›~„ËűÕH JOÕ•1o­çXôÅ·Ý%îxôËp2öÛ5œb2> °ƒíÎOZô…[ŸÇn ¯‚;Q–¬ÕZ8ãp#C«ùÜ6­¤xDÝ¡¸Q+©I#Ç¥¯éhä¦ÓÛé®L´Š3\²g/IÅK’»L¥Ã1¦uNÅ=_uf’hΖ,Y}ÑÑyΨ¾ kÈŒpáG1­î]]S‡:ÂôluŽu¼Y§2£/xµŽm4c„©3z»€#§ŸñU p«ãH¾Ú‰…¸úŠÅºÆ ºFk~MjÑÅšxµ"ˆ$t.òmd˜í¾ÐÕmºÇ¹HHÛ1A  •Xú±H(‰„–7/k‡;U©äð¾RxÝáêZ[7ÂñÏuæá%«1„V_ÝÔ×pº[¯!·$ÓêÑÕš:D’ÐZ´¨q¡W;çØŽ¾æ$¤ÑÌK†s–“Oj,sxLNe"@üóœW@òÕN,ÄÕW,Ö5žXÐ5âXókRA×ÄÁŒ>GBŸ#¡? =¥í««¤èd†óÎâfìêLë”˧ÚÙú*<ÇiÃW ¯Ü­¤¯;‰4u¶ˆ’.ù˜U}Š¯‘Nõ·«ÎÔÍÆjÅ\ýô¦7®±ôÓ‰b·ylú5'SÅ âSâÕzjÛ¬íØvQäÚf¼%Ü°wÕ _íÄ"\]ÅB]£‰Åܘ…/ø5« ŠM¬y‘p^ .ÊÛvKàÇý„·oa^¸­$îqü$nûÆEîŸ|Ç|Ï7}þo½ÿo}Ãûý›_ùè+}í·øS¿÷Óü/ï}Óý¯üç/ùÉð_ßóîŸûЯñ¿_þ.ý÷Oýè‡>h"õ—â¿ú®Oú¿¿õ­_ð3?óŸùÌ›ÿñ‡?}|æÇí‹ì¿ïÿ»ßô5âMoþ“_û™W~îÕo~×+¯ýàÿxù‡öSïùÙŸþ௼é+·XŠŒ«.8£Az>h çË ™6,ÇÍ!Ã\b„<Ê᮶Àgx-£ÞV(rÓ€…^l\üƒ('`¸žá ù]=åo–àAg)·‰!ÁÉ.ß÷k‰Q8€±”á÷'=ã.(IÀÊ·?ý¹j¬A¾1lØg]ö“ìFÛ«¤èVÉgpâ9•L–SöGÔ‡íSˆ³eŸx@}ÁK­ë 8'ò‘áº7ÝîtÏ„ â U¾º ¨JÄðÎ9Ü #¹ç–s›s ݵÝœb*8†Â*pÈC ÖÖTîO¶WBs‡ŸÝ±kÓz¯ih•Üû: D3‚ ŽUp§ãô8€m«v5þFêJÆ!áæ·æ{‹ e@@ •,zS‰Á]ˆ…£”€Vå°àAÒdz3ðf¤}›ˆÌ-QNõ•p©ã{„ÏD6]"§Ô>›*#i­Ip¦k µ“di£éÔòpX“”‡á™T?“ãZ,€Sj6T³èˆT‘D€•kÁ‘pq‚.| 9·@҆à¾p/9]ìRÇžÃ{T§Am•´âJxIîßñbÉúªÀ¯9Ý”T“pG^/.¤ƒxÚ;Jä­œFˆ~×WÅÅCúj¥›:ôs|Ý’¦šÐΡÀ£KÖW/öþâiÈt2~š¨ÍèLzðb$ôœ›Þ KÂâWðܪŸÝå¦ÛÞA¸Møòa«·)ï¢ÙŒúàcs«Á»Xõ€ØØ A¯p—å ÷~ ž–cySú|ðß¼.ª©Û,…Á²¦PKÛ2‰|@¨;pµzýy‰ç,ù@‹â›9Ë~d¿sãÉ“á{ÀÀUÄ!¿GEÀz°SOƒ£õ’Ç­Ä:N]%t5ÜKl9gW >,¯6Ю¡¦¯NÀ>°Y÷l±|œ ƒ‘9ËC8‚éšÃ€ ¹¡îý°€àî 1š½Cýƒi Üw U&mÕ_°Áw¼‡e0|Oë‚QýÛŽŽaƒ)­g†)°Å¹Î½Üe§CCŃƒ% ÐBd;_Ž@,¢ÐlÙl—¦ßVÐ×/yϲâ6z=7ñ"¸Æ_¦6 –[ úzü¾Æ_E vQ T†S·ìƒ+Úÿ‚ñ5°Û·F{­_ ¼H WíNQÆèó…R%çÚ®¤JÖ„†8yì|L#Óè,o€þÔ“ ÷ŒÃU¢`Q¬ß‹Ð¹â" Ïö·3‚ÎÊ ÀÔ4®>ä6Ó4%‚0Ÿ"sd½z!ê6˜~ãk\±Ï­_èÉíwÖc0Xk|&%CWå“ŒN_¨¯ÇF¬Ýq0 /j ´ž>8‰ÚÁg2$~á%¸ñG“ô¡äd]kæxMé«Æð@|“Õ·²èÁ&”ó"“‰{´‹Lf*;™\`ÉÌÇ ™Lž)N&™Lú=-2èd‚wv2ñž62¹J‰+¤¡ “ÙŽ2™r™Xd2õ:D‰@'“ ?÷Lf›OÈdöã†LfÏ‹Lf/OÈdö±“ B݈`Ô§d‚‡v2™ý–L¾È$JD&sL¼œtC&²·o5Z»!“E·dBDûñ#™²…Ü€)“³:ãßp00ô ÁµuÁ ÐÌÛŸM1èúšÑr¢Æ2vôTcÆ Àâ(²Ušˆ¡¦ÎÑO…e‚¦¦@xFÜø d_B?­HèÈîÂÏ PúDI¸ñÈzÎ| ¹ gˆ:ÀSådº?:¨ÇÀ´ ^ <Ü~—mîüëÎï¦ÛôðIÙ!€®Ó€húâót”€J#Y2žò,¢›I æÚT=¿5àÜI®Ô@ñ§·ÏÊN‰M “²A"éË„)(Óã«d]à¼5ób>`ã:s/0˜"K‡x#8¯W¿ç¸q]âå)Ÿ%r ìlïfãìW^ö«U û?ßìW¯ôÞدls·_]˜–ýªà&è‰ýªà±ÇË~Eülö«¾Ë~uMjÿ½ž»ýªà-áÍ~E¬ìö+lö+ƒÛn¿"|c¿ÚJ–ýŠwþ @žþâ»l©ñæ°äû¾ãî;Ã¥È]òyÐÓ3ÀyB½EÀ‚ ìâÑ~Ú;ù›í2Ææÿ!mV:½çKp¸Ÿ›z,-Ú§·ãý³»­€ïV]@9½d0ó¾äÄ=!Â?eW”³?DÈ–ïp²XϬӹO—1 e™U†ºø`‚•÷â4]áÍÅ¡Û Eåà‰Eˆ¢“¦išbùsø«.‚NY%Á´pÀ¡Y/)Ÿ‡¤ý ÎJ #ZôÞ·—à=„¬3/Éü‹)ÿ™²¿×ù^&ù!]Ìq•‚A¨¿Á»X<ñÅLüK>µ$ÀK¬»†5)©?wè”À72Ï$r€VÎPT¼KæRñOà†QÍÅ+Ö—WøÀ3Ü ìSæü>ïC'X"³aqrÉ•¡)#0®²¤ b@“¼Ü²]2K‰ñ%Ø·Ú)ùgN''û©ìä}—ÿ.Ò„HG‡š¤h7 Lý[!ƒ›áU°Q|Õ@¤ —´ñ}« Æ¡.`”" ®“ˆÓ"qê9-˜¶ÑžWÀKBmQôÖH¹s•©AIñR êI«‚÷PÝÅŒÙjpSÅ•†S`S:œ Ž$EWIÐSÜhí”äét¦x§è«¨ÑªÞ(å‘_×8)ØhšR'`Ò©·*Ö@þ[sãc5#s“3¨!×N²LDCKUGC®EÑ™? ‚£Zy\_oöHáHeS<ÄQ3æ¨m‡€·‡Œþ<|{ðMÚzȆ3¦0ˆf%b$ø#¡8õ¯…Zû¦.ÆoGÖ…*¼ Ð|SQÉS-UzÐJWñœGõÓôÔH¦ö)6!AV›îë·óGAPŸïñ¿/ÃÚˆh‚ÛU\ü·«P(_˜l÷D`P×ÅIµêjÊÎQ!YÍÚIµu„ô2· eh'<ã‚Ü2¹iÅNÞÁ"=–ä<"=¹ˆ@dê×0OCDò:uøržì\:oMGØøO¿S¤Åz<¯d¬ñó­¢ó!Ä#N…*¡é]né¢ç1Hö¾ñÖÓ;ã¨ô=ÝEåh¿,('i »ÌÄw162CZ*¡,È®y‡¨(¶-‡ÄVE åÚB™+ $0@äå“èHÞ «GÙÎÅk:A9M©)V…äÂŽYdJN&-‘ñvÉ‚CA¹ ²$aÀ]ïN [I ] R(ÑHúo|ÛÆ•Ç ”2ç¿]èQݦÌ.Ðf®7ªP³«nH4r«ºMì^ªÛäÔÅ1ù{©n‚¤ºM0]ª›–iWÝÎH)–>»›ÏÈÑ ÇŸOr†>ÃV‚)ˆÛ9C× ÝOtbmðÉRgèÑÉâçWø÷鹶žBÎÌñ@eÏÞš-Åy\8×ï³j3žÇ%ß?DòåÓ™´âyâÉ^‡}›!ßò­…L!|bRÒÑõeYâ ¢2÷Ó7ñÜ—qü\Èð ±b8FÛ<'Óý»|I1é‚`Þ¹N4¸Ï¶›àž¼iPxfu}Ÿª[?zÐõN)ê¸v™ð0ߦ^&¤>l—z™èCµë—ˆÖÜþ Ê[ú%#y/“‘µíR0Ó!sp(˜é*ì ¦"Èç½+˜|af܇~‰¡ß»‚™Ïó²Ì„t…›†™à3v­žsÉnïú^#›†¹ÀP1£ÀuL~ž/’Öm??Ò!m᪘––iÓËOÕLF·^z&ñCÝKz&ðË:±¯IÅ™ÎàæMÏdäq»ôLbeW4Yp^ŠfBHZŒÅ"3SU(š[ÉR4¯šçüU)Ñìpªð$± !ª˜·RˆZíÅŸƒ¦“DJîWõÊT=yð:%½6:Á·x’õ2Šß4ìñª”CxÚ÷^Ò<¢öu>ý½“x(âuJzñçFä~±d}c\%/öþâ­º²Ó`iìiÌN×u8|ÜÀªÈ³“ïÿ*Èèƒl´zv:±Ø•Ž ¸¬ìt³g§;˜Î`…–F/#GvºU’˜Il4¦£{Ìj»0;?§ÔIÕ0{v:ee§“ ÙéFëêgú§]é ÆðàÇÞe°m‘nè¡(y¼J ¹)]|µ—d³ …9Cžm1Èse§“6»²ÓIõìteŠ©ÀIº«”Y…pu¦)ò¿ d§‹½„5Ùé •3b§(;Òn‡ÍÃOOɧzy‘JºÉN7•m *"Àü²1);]€ÇÊN—øÖ`F–\Erñ:óÓe7pzv:‚%²Ó‰H<;]:%`fÏNç!ó°g§‹QÍìrÏy æÈNÆŒs|(s8´5§£@‰ìtGd§8•Žb¶‹‹ÓoFζ`^B3;ÝV£i,§²Ó!èkiÊ‘9”o‹¢ÍAzK’ç(`œFÙéh£J[3»Š¯ìt >#;]”ð „V®@"]”";Ýd®ë«B£5†·ÉM.Éoo·÷º‘sŒÅÙ³Óexí‘…dÏN‡dj‘P’žCMŸ0c˜¦ü¯fÄNv&50÷ÌìtÏNçàôìtA€Ðe˜ìsÊŠC¢vVv:…ÿ_5枣ÆŽ5xvº(ž[î`vºŒŒÌ=—ha ø™²ž{ Þo-œÉ<‡Ú‘âÊ(1@ì!îA•!íô“se§KCOD|]ÌNG`z2¿cC— ìÙéÒpôD2?>Sra+ ;¡eO ÅiáÃMÁ©eª›1<¥p-Pv:Ý‘ž® ÙwR¤ŽKaLôi;"V _±©»êyuK0{LÅܸóA9ôâF4€'‹FÞ»`¤bÛjT¯ÓJ.N×·Ùéù ¶²²Ó¹<óY½5q–ì¹çR÷³~e§;˜îªqqï¢ìtÈ{KOÆÙéð>Å%E<³8]®‡/`Z¤»ržù5 @½e±ÑéÙéÜwÏsÂ;0ûÑæÙé²2ª•Ìä–† 5Ž)dË>Î›åš &^ËÕ™|N}l`ìt«¤0;Ÿý-ëì(x(™2hœ.¾£'þªhÏ aÀÛøœs¹²Ó%=|ÁìtÌ;™´ñN¢Ì¥Ý£ÝÎéXÙéܼj$—+ÏN÷çÊN—¦NÑÓ³Ó¥)1pzvº4µÛÇÊN·JVv:†{¥¾ô”ç[‰Ô=FÎ ¶΋w4ð$1Úܲ‡À•3ˆ,-9—52£Ë'ÓÜ3Â<„îh$˜O xåÃÃ0&<ÔE‹@)„/¶~Õf=<Å"w|“ÀïàAûš*¦Ìf¥î’4¥t<Åjº*tŸ@J^È=5ü%m¥/l:äÏ$Ç¿ìâœ5(!çjŽH¦ìÒÖ•Ùíö@‹Ì©.˜A“‡,r^#OF;“!ƒG Œ D!jö]JÄNêÝ=5d̦ëùkÿ _¥žƒaÉãV’øJâ«­ÄUÄDÅ›Håá¹esXz bÕÀÓìä\%hÎXF(꾓q¢3íÃ5⪔ot¸jP(.|PÁùžÓ­÷nÏxÉn˜EQI»O–™†3;GWàëÔƒ.Nv6þSª¸‚myi¥·®’´Ã0Vî·zÞ’º`’×IgÕŠy£!™Mæ‰2¥%qG6ôFÃ’æQ_ÀÞ?6 Fq·\÷!•ûTÓxr!’m?€àj·@pì»=€ɶ@å¬7àíªÁŒuÕãýªõØ Zꓨ†+²@5Í›ˆÎ7¢:÷ÕÛ´ÀµV‰ |¿@î»=€ªq‹ýZh÷¡´O BáP"-÷¨œãæZsZÜ/÷¨¦~sñ9÷›¨%ïàý|{]%×Ô’^ø‘âƒø¼P{ü7Ä ª.x¡Z÷t«ÄÙ0ÜVéÄ Ý—ß{Ф¿/„-)¾|•)Wš®¶ßPy=4¹—KB¯#-…¶1ð©ï|‡îà§ôk¯Ñ+ÎëY±U2¬ '»&¯€XBÄÝ_ñJ|ÑÞtÍõMöz^¢\ôZ–Žª—íÆÏ ›šëBú±®2“×ñÎö¡—”ñt©ÌáÝsG¥Â4aÌÉÂ7Äùî"’4 f" DŸ!%Ü)Ÿ&’8Tk¬wõ*tä6°ä0@Ë9JnId¤JàÓ•âk¦(×#²³Æ˜M7iªud˜Ñø“\qX2õõYü-眕¦#ɯrö$žÇá^æcêùé³F;È+8šïó_æTýÑ5¯ÔÏ\sOUoS~¶:ýŒ–£¾^¤Ž¾zÎOÆÓâiú5æÖWÒâžÉÒnæBH;~b\¯:Žç«µ«¯µ^kà•ÃKø>‹\u|>+À¹Õððr¾ÎO³@&+Æj o0‡Þ·wp=F}*”ôÃߣN0`Ojå[ ÖI¸|fm mÐ! õÞõ§(×õä úzÖý1†~ÁLû­¹®°ÿUŽpúÕê*i§¿­”£ùK:Hå¸Àg’¯¿ó¥íõœÃßÌ$8•ÈOŠ ûL)ÍŸNâ š©GË•%çÃôÇl°H”ÀE«ZÄR­öÝWæ=øùàA4½~ÏÍçY²)È&¨YÛ;¿ˆƒÙƒ‰hZœ€L“É2—xàOƒäŒº(ÓSB–G1‡~ˆ®ŒO6²o½û¿J /_endstream endobj 6 0 obj 15318 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:58-07:00 2013-08-20T08:41:58-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000015622 00000 n 0000017192 00000 n 0000015563 00000 n 0000015424 00000 n 0000000015 00000 n 0000015403 00000 n 0000015686 00000 n 0000015727 00000 n 0000015756 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<086F2B0061CF655B7C837D707F849218><086F2B0061CF655B7C837D707F849218>] >> startxref 17362 %%EOF ast-8.3.0/sun210_figures/frames.pdf0000664000175000017500000001603413004147321013757 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\tTU~ÇL’B"Yõ±§Úm%™÷û¾çQBµ‹SV·‚`"þ f¨ Â’(!àÚžÓØžE·î)Ù]"mù1q$€;™&©gÙž¶âD3œ¤0DiKÇd=3œaæõ¾wï÷¾™qrΦý‡P'8É÷3÷}ï÷×ýñ>ïŽÏs|™Àñæý½¥Þá|qÏüÐÁ—)ª,+÷ŒCSÔ2E8Qäå2]áê3•!…Ó©LRDN”x±LP8¤èYò‡€DrEÜAÐÍKíKð‚ÊTÚ2ét‹AQ4¢ÂFxó/Žªd•7/>A6U»q;Àr@À3PiˤÓ-Ž§ÿÄ!à  ]°Ìñu‚$A4!™º‡àÏU]Éq@DCD·C•qO¼ÆQ  ™L»ÜâDPE«o·(ªf^:E´ú‡^AÞâ †€ƒ*kÔc‚P¿@#ˆ´K+·Çä!üß³žûÓ¯c±ÙêxÄñ¼CåiÕ)‚iŽ‡*âš–u†¸"JP™p•lu¬ç¶9TŽ=I•¨6jT0ÍÃ-q|ßìp]7‚9ny=Ycˆ›!"ÏÓAÅô3ú•¡%Of¤kÄfŠ~y<8TE†ODR6"JflTI¥²lÅJâ-•·8ÎQLe¢Á–aŽDÐ5Þô4ºjy }€ŒL­`-¨• !×RíR®s6BLÓ„lçžëBÙÎ!%Û9[†ŽÓ@˜}Ø΀€• !×˹ŒªAJnÕPĨ9Uc#ÙUƒñœª„T ‹@“öSl¶ ¤7 :"·Þn(Cuj*ei¯ oq€e€¸`; àèd2핱ޢ¢j]U)•É$X*EE"\<²øUN”‘Åçƒlº„¤LÄtIPI "(ˆ„‡êd2íë„—!PÑy@Uê’ Q²:G…ˆb: àUÉ<¥}ZAù: ™!|·(é©P«‰l²€ p3û§ká!ü¡(ódÔ!$€2‚è¢JGa»YKøi\媥S~ÚF,ºÒ²®„õk±ëøZåÕb6±ÙnϤ-ÕõˆdieYˆ ½*4¢¤Y2X I•‰L50f†H©3Ð !Ë[Ö•ÍS+X j%hÈñƒ¸*æ:ÇjšÊg;§h¹Î)j¶sŠœí“™s€€i L‡>lçÀ hV‚†?(ÛÍ¢$¨¹U#¨¹Uƒ‹3§j’S5‚š[5‚šQ5,ÒÊ­AÏ®QÈ®*gT ´€z LF¹ƒÇrVÅRvÅP9£bX °RήÖGfÅØÎ1DÏ®0²i;ùf-äl瘌r+L `:ôa;V@ f¥œ]1™Î=Ï!Êv cí¬fÍÉr*󹌆ïí&IÓt|0#èH2“”oà]Ofxs™ÄÜáÑŒ(ð“:xC<›EQ˜4ƒ×ûØL6ß©›gòqXd˜ Ñ£³yàÛEï'ÎþÃÍe—z¹MóJÇ}¥‡{|NW0ˆúœÕ^W€ÌÝæ$îsz]Ön}üñ™Ë¯¼0·xמ+ îhÛìoi**/N6•L¤ÒøÇ0†!‘.#åL5ae®u¯×̾t°eYïˆã·ËŸyìÒiGqgƸË`ìD³F±»ù8ÕiIÙÁ”ŽdND"2wÐù˜2¥£©¬SlJo¼}éû…ËÚ7W\jY;WŽ.¹íÁs®Ü5ðêwlKüè—£+bÛq Ž¦’µñßUVÔüéeyi"nx/–û Ÿç÷*ã´R}2ùå<ñÏý›BÍÞzOüÂÝcñÕÉMœžÆΟD'kœ›ûÖ¿½v¿·xWÍŠ%ëÛøç³xe¶Û“ ’°Ç¢”—!§»­)Íú.‹—墾ùsÍõùö›¿‡Ú_öÍ* xÞŠ¾ð¤îŠzCcxáMøS§ o¯bÊŸÆ6ßN#²óxп½Ëpy†]õ/úkë“ÅËù@ÁÁ%Ç–öoPÜ0ÙµŠÚ­Ë¹wL®-v¹Ž—½òtº­"=äůºÑúÖHiçÁÞ}]ËêÝËù ›嘙5~ÕŒñËã‚E%_A«S¿°Ý:ýðìÇô<ÜÿÐýõÏÙÿà̯ çeqÿöâÏ—4•Œ÷O¤üxT†üÝñ±Þ¸4§ðöňþ¹Š‡èáå>‘jAoúuó§#m¨êy½cÄé:Wµp|ï‡wžçNÎZܽ]ödݧ7ïiÝÛ9㥹à¬b¤dQô|s®2u†TÑÛþŸ_zydNûxËÀÀ¹††/¸›¯pž}%çÖDø_÷@4Ôó“ø@UyÐÜ¿àã_ï ÙþôNã⻩áà6<ÐëKO»jöu¾‡ÖÙ×Ûš±j(Z†æ^e´©{ë~{û•{°/zûß-[{ÿ©í+Có¢-èp ­ã_#ÛïÁ;0¼pàå?O¶=ûþ¼È‘ø™øî¡îêȉ õƒ%®šŽÎÚšWû ‹–/ù6KB *ˆäÈÞåö…:= )’{FM¦‡‰ðlk1‹TÞâè‰)@ðÝ3Ò,: Q¬ß “ɤSóÆ•üÞT5PM%Ëô ²y¤”؈ۖžNi§ŒPÖ WZÏM!4ž [§£4²¼f‘x c¬xC°C¢H‚× rTRú4¹e‡·(YǤ*Uƈv 2ÖA Ä<“ML<L¦½’ |Œ€ ßö[ÜBÏã˜ð¢Å2âfˆÎß WÙ¡•^°JQç…PéÑf€*ñÄ13ºÅüâfˆÉ–@§ä*Éîp+­V¯e0¯&Š'jêÑõ6¢’‘)ð’EÇ(}jÁbä-]#£›A“ÙÌÂrf–) ,ôÀÓÓÜÌøœZH®Îu”¶hg×ÛˆDŽz‹„ð“ȉv!™Î‚ X\û\¶:«A¤ê­iŠpQÔ®B¹(: h"{¸°Ô@¦!ÇÊ{BvErÄÝ*‹?£€›ŠŒ(À ‚Ùu"ñu¢f54Ëâ+ñ¹%"‰Ù%"ÉÙ%²]"€@€&ó¹%"jY%"ªY%BE»DØç ÍFV‰ØêI‰d†©Þh×8A*©| ¦ 25PÙL:9 m·­iˆi™taU D)PÀÓHBT¶ª„-ÀHÐíEªÓ<\ªá{àÿ¯D§$›§´óÝlMOšÓ|n´¼í§+É)c·ò§h:Rœ ÒÌ/M‚S•…ÉŒ½èM$LæÞ Anj⤥6}¨MUTñ-~^bäÆ#6‘Ècgó×›–´f&Ë'Høf\åóE¼I¾ fW$ ß"Lþ¬îF v3HM•×9)ÿ#‰Ò4óÛÓ•ÐDHžÌþë–ÎÌÚ¨Hœ¨ÜXaeºŽ›_½D¦{yO£ÈÖBŽÛLåH1¬äÇNÕzô÷ïžï)Ž|vŸÏçKyð[zÂð5þž’FosÓtÔà­I“?ˆ7ÆuAcc,UÛ¼±zðõÑÚx¶\xnãWEís§*3¿ m'2ÿg ¼ùõ|_úA’5%Le @ä©ðå^ú—þY´4î34ÿ‚Æ_¼°G^À'ç¡÷Ð@sS¨º;ŽÝ)œ(ìF–èQ¼E©N±p,4ú¢/Xûâ-ûç½°Ì1áóÖìª;_µÄÉ¥>a›²DúÔãÿUžž$EøVÝ<¾w£rý')cÓ( ìŒÀ罃ü¿ìßXWò‡…Ù;³oþ¼+÷ÝûGíÑ?s˜»ÆmžÕ=o®yö>l(ξû Z¾œž}ÛÈÌh|­ d4{ð¿‹ïÆ¡HGg ¿èηñimûW/ÏØIe&DÄ‹­ ä}Œz½çãûŽÿ@Дwendstream endobj 6 0 obj 4800 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:56-07:00 2013-08-20T08:41:56-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005103 00000 n 0000006673 00000 n 0000005044 00000 n 0000004905 00000 n 0000000015 00000 n 0000004885 00000 n 0000005167 00000 n 0000005208 00000 n 0000005237 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<7C2E795CF5CCB77DF399AA12D4A649AF><7C2E795CF5CCB77DF399AA12D4A649AF>] >> startxref 6843 %%EOF ast-8.3.0/sun210_figures/fsmerge.pdf0000664000175000017500000013401313004147321014130 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœì½Ï¯ïKVLŒf+aDï!æ ì[¿$ÐAym$ðvb›t4tŽh#ûpŠ˜@¢ 6Ž8t #¶1ÝF »%ü &Ý wÐ’0apsÑÄ–p”ûÖóôz_û¨ø÷åNi1ðßRi¹gâ8â‰_ܵºª(c§<ÞåÔnRZ,»LÇ^ë*ÃSæà—;%õÂ/3®ÊjÊ÷^«ãwÞ2Oy¼ó¶{Š÷ÍËܽ·Z_Üýÿç.’,¡<ÌõÃ(ÿ¾Ü)-6þ[JY \¸¤.²Äqâwu®Œeî”Ç»ÔÃM +-e—éØk}q·s´¨"÷Õk ª²˜xcåÜ&>WPµªj¶~ô¦=´ë*öÕ˜m‡¶#Ò±gZ®½ÓBÈá(ùfÛÕ¢'i/Ÿýìõ“âA막ÏÕÅiø° Ò +Í,*%ä%Ù^Ñœá\HJÍ9Â)?GÝHWžøòÙ_OQOžu›ø\Q.P¦:vŠ¶àÔšøòÙ-åöÃÛlí~>ÔÙ[³&†^Îß}‘z’+EÊæžË¼'¹2嫳,.žOr•ù&5JÿÃjìýMj„ñ‡Ö˜B}ƒSœoP㒞ߤÆÒߤÆߤFȶxc¾A9ä7¨qMÚ7¨1ç7áœ\Þ„sr}ÎÉýM8'7áœÞ„sJ¬:7w;g¬5¡ù–Q¢U·'þJá ëfÅxšøòù_OIªÿ¶¨›Äg‹²S^¾á¬žº£ì¬,éW ~²µu¥`Á^«´ 2ÎÅ{Ý^),ûfÁšøòù_Oa£žu“ølQ¹*Oñí«ðÏ•R(êIâËg?|¦(‘eïº*ê&ñ«Å‘ÉÅ»óUZ5xÖÜDÉš¼yÌý~Û’ÀJÀþy+A÷ÕëÅPÆ/eÄ~’ø|AÔa}1ê—Ì´´“DE3¸ÆÝ¢–%›nZ—ÎÎ×½»®<,»öCÊzšøòÙ¿jQí¦{·‰_¥(jêؼTL<ÆÙ*Mýf,÷üñÆsõÑÏ3ÐíéÆ3MS‰<ºñ\1P¶þC*Œ)¼A³d~µÜÎUÆ›ÔØÒ›ÔØÛ›Ô8ÃÔ˜ByƒSoPcÊéMj,íMjláMjìåMjƒ’Šcí€ctŸ‰âÝ4]#éüf¹tvO_>ûá×(ªËÌmâW)J-Ÿi¥-r›ô¢ŠV¾§Uµò-ZI÷åkO=éC_Ÿrhgo_>ûá×(ª­ºM|¾(©]ÛΔ`Ûä¥à,Yú˜söÝfØV·½úŽ›Œz¾ÛÅÖŽ¢n_>ûá3E©å±åkŸ$>_T²vNSB‰8×^*ÀÂSÔÊ{‰7q-§ä¦ly²3C’$¼òŒ‹ìO_>ÿáë)®kï[Yú4ñÙ¢âTw’óv‰’ƒ³å5y/ßdƒ¼—ír¦ZÅ..¯Û‹ë§†£¨ÛÄ—Ïè)LJ¡Žó¾díï-D9×?u‹Þ3ú s]úM®Þoq è7¹Z¾©ñÐor•ù&5æú&5¦ø&5†þ5¦™ß ÆÔçÔ˜Z}“k|“s“Á~xa¾AqÖ7¨1Ž7áœØÞ„sb}ΉùM8'¦7áœß„sŽFÉ©ÏÖxØ>Ħ•}HíÖÖSZ]B\_Ò^!vmõe²hÇ/îæ4M°¥l%›'ô)qÖ‹t앾¸Û)#Ûj³Sx{¶ú«"«ÝâxŽ_Üy»<åñÎ[î)»¯VäÆVé¶|Xò.êC¶Ÿu1¥¾¾ovâv(q¼ˆbêlOSºAOéÙ°•¹±Õº¨b)uLÛ@vJç1îÞu ëÀÀSš×êdQË<åñÎÛî)Þ7/sc«Udù:InH‹\ò‡‡bZ§©¿›8i¥±Û©Œ®õ!Å)øxÀÖWæµ ¶Ü eü™â°¿×)¿Ã˜¨Nh„X Ñ’kÆêè:$.A8=´rï5,Œ®”Ü f^Ýnüà ,TB¯-™wø|ÄûšªÂ"ÿՈ5Ž µÒ*›Å4ëXÐwKÔä^rƪôϨe LŸÝF{ÊãNYÃ<BAŠ>:=Rpq°Îõa­F‡zo-âßÞ>\7òK"v®|køðY[߬õ´Dý Þì1MûiÉë#ð·Ê¢ç«%(´ Ð•}I2먼RpU¾ÚƒŒzЫßSúGëãCȾYC)‹¤—Çú¼’ô!s­é0z`aÀ%ÿÀç"· a| ®jgŽŠ¶°Ï¥w–LdJ´ÚÄñ ¬14%‹qn_×ȵ¶1¾X’nŒGŽ–2F`Ð\8®VO~á)Éô‹QlÜ «hà^Çì¸÷Ê€3¿oÅ‹V¯Rç2í¿2¹’/y}ÑTÎÕö0°žð‚ºv¥¤† ëú0 â%õ·_à ®±GLÚ‚EÁÁÁÃT^£dKª,ŠõÖÐƸ†¢YŸpS¾ˆcnŒNß:”Ç˼ŽN¨xãÅ C¼¢”Å.kcÆh÷Õ*`&ÑyɳlŒ/–<0Ïs¢­W «ŽÅœjÕNé¤I³EqPC«fÓ@Ât†CSÐ=VX‡¯G\õyƒ˜°:Y³’X…d 'Ç/LÀ+GŽ5ñÛ°¾Vƒñ…RØi M¬ebäتN]pQTÀ5(å®öPD·ž×B†” Ž$™×j™»¨•E1µt$k‰É‰k7­UU\»ÑÆhÝšFZL”#â °cã`ãùÁâ8òúJ©+æÌ1±¡\¬Í ÝV±&÷϶6.X«kÛFU¾úa:¡Z­J1s"­ñªœ“ú*yàÞ´Z…u‡Ù66¶nµråX|c‹mtSÅ&&\ÌŒÅ#Þ86K˜ZMWÜ3=4ÜöƒÕþ%§ø~p!ÛbäuõÞžš•99ðpo †DÓËÞ¬žkSØ ÚRlOþÞÛAÒáCD¡böªF`µ€e-NnT7ÔL„¥ÞàÚ8gœ“qÕK2iî¥ÕeN-ìè°èYjucäǶ{dȶ·¬Àvümm|t´šÐü%€4“ŽÖ6aôÈ%j“i§mz1žÀ‹ZPÚÞ‰^·|‹`«åb ±`“E¬b­Ára ‰X«Ã¦VçÆp£O휵FÇ¿rÌ ra!0rÍp’‹¨deŒz çÕjY‚¨³„£‡ü¢\ºPÀb¥¢îcÖ¾—úpàtÊä,;úPRÌ‹^ÜþmJk½"ÓímjÂstBE˜EY.¢¤„Qví±Å¶ï Ú¯å¨àØ™nªHv´ö«¨ÉFV.>ý½- eÍ®Êk…mXÊ’´[Õþ¼Ö†ˆ«½f›7–ÁŒk€¶1(ƒ‹ž3ÇZö¹z×µ‡¯E,7ŠM wl¬øbñUÁ @”ÙÅ( ík‰%\͸Ò˜gfÁGÀ$A{ (ƒ.Å eIɶ¶HÊäÙ$Ð'6}u¡ãÃM)h˜ÃTA]îAmM„lulÈ­O‹ÆNYì‚û õ}Í×Þ‘;eÐcwá½ä•r‘}íC¨±,Q@§³)ÛK–ÐÁ½eý-‰"ZŸpÔË׿û´E€¼;Ïkw¨&)å!ªÄ& ´L}1°‹²×ۀ뵴S „M^÷/”’ýòS÷k„ñ<æ{Ö±P*Êe~à#wo}ä/ÝÿŸþ™»{ëc+ÛÝ[î~ö»·~à‡?|ïÞúÁÇ»ðWïÞú¡·>üáZð‡¿÷{ßú ÷ß³~ùðÛ?óò'ÿöúäCºûÈÞ׿þ_ÿä/øÿÖ§>ó™/ü/¼ÿµÿ÷_ø§üÆ_û¹ßúÝŸÿпõ~ëwïç?ø­ÿè7þëïý½oø¸û³¹ÿ‘Ö:{³X^ͬäå•’t«T‚ì¹kîvélZfÃ/`F»Oy¼[sû ´jõ*sc«u•á)Á•ëžR¦]·X™eÈÐÄku¼Ê°–yÊã·ÝS¼o^æî«Õz=á º†©ØuCà)Y_eb·mú4€‰¸ñg˜5°ƒÐ!¬™Q¦Î†ñõ¤šëÈA5;^@úI5Y‚j®%ÅDôšëVÜj.²ò’Ïr•:Ã1¾ˆ]sÕs$*±*No`ˆ—ØB5ו’(Ž¬ª3@aM$Ìn਱3”A5WÅ=5ÇÒ#æCÍ•›´_‹²Sj®•"5W\b+Õ\+Ej.¤, ra©¹€±Ô\†_à‹d‹€çˆ …š¤æ%©æ2¸p mÆ«†f};Õ\ŽA%Yy\9²”XúQñÆ‹\âCO‰s@¼[Xj®¨Åf•(5—a|Q¥æÚ9ªÔ\»Ã)T©¹Ž”AZ˜j.rVƒ*v3=ë‚ņ¦¢{¬°Ž½>]pÔ#ƒï-kÇ0,_õ6>:Z͇À+q1BÂ6’ñʉKÔE&Omº®j^ƒ›Z=QÍuI¹`¾ˆ%àÄ"ºˆePÄê‰j.kMä…©æ"±¨*Y5'I[¢ìøg¿ˆÑó´Ó©£ÄTŽ5ˆ\XHD.þ½É%¤+X–1êE®^¨Õº¨å FAÅÖ$aµ©¹XÔ= ˜TM6€°{SÍeÐÄ$¼Ý*ùÚ„z¥šëئ6!<‡6gìs=QÍEJe#Õ\ÌÙ·‡ñP®øx5U´aGoÏÑ©æZ4.>ý½- ¸窜¤æZ Ò·`^krÆuv³ÍËà(Íöúa åÈRsíYj.¾á^‹ØHRsEX;qoµè[…ˆ²°Ô\â×K¸šq}]j®(iÞ)—®Áeв ¸a´l›_šku¡I¾ûâƒB’nJá¥p¸‘*F¤šë®)-ë¸ ¶>-;;ó=¿¯ùÚ; B€ zí.£J͵s8ÙÁºhS—š ·¦æZd¡ÐQ8L)™Da}J”v÷¿û´E€Q¨æºr”j+|âäUb“J5×J¡š‹½†Ü\¯¥•˜bà<{÷/”R.5×Zf¥æâûGRµ<£æjj®ùGPsµfj®ùë²þ©oû®|ç·}ß7ýÃïü…ßþÀÛæ?øþ¯¾ü?ôÏçóÿîÇïcŸù¹}ú_|ãÝ{õï¿úÒû¿òû¿ÿ¥/~æ—?õ¥oþ‰Oýúw?|óþÒ?{÷G¿ø-Ÿø7á³ßþÿøÏßç>ÿê÷^½ÿÞÿ‘ßù·ðåß|÷ÕOü滿üÙ_ ¿ú§ë¿÷í_üìg?ýÅïø+ŸøÑ_ÿëåóßpÿÇžÕŽÑC”¥™‚RÍÚ-ÊÀ¦4Ùÿç ³VÇ/îRÕËOOy¼KE/ë=eq¨Ê°27¶ZWž’³™}î”$Óè]fLæƒÃj5¼Ö[ݨv·ÝRv̭֭߬Ëäh4ص-¡¥¼ë)ëÕ¨\?8^]*M_X ºTÍIŠ}“$.x™[­« OÉn„¼Sðn&ç^¦‰À»VëŒ)Îr ÉÞö详¬oVæÆVëvróu²Ü’ååXªkÊy5¶> vžkE$|§Z# x#qïú˜dž+ëÚã*>­ yã!€m 8%ÙokÔþ.¤1L¿W[V±]ʱ„úÖy¨àŒÙW£ oiø"ÓŒaáuÒ)Ç.VQŠíE©â6-L0LP±Œ"øxÀhºåTqÍ…ü‘jº…ùs†`a`ùy Ä+¶©/‹¶a=ÍÜzÉDÅXEkq”Äz¥ˆkàj#÷סò#C:ÅGëü·p2>ª`#§² ñ¨§éS2Ñ ËUH®ÐI&áˆÊõ@_/v¨íÌÑÙt¼€ôºÀ%K$íY누‘.º]\¸A0#+ ÞäÑË1¾˜Tdïm ¯ˆÈRŽ])²$Y%l(¨b ³k;<2`=â÷ScéŒê¡K=(¹”(åXjhê­§”c+…RS–ܹp‡ Dˆ)0;F㧠;¨S¸P8(RŽ\EP9&Xuí› ´¬Oðg³Ö–17ÆÇönrçˆ<@­Š*6 n^)Ba‚vNŠîDŽë³lÌ:*”cWXV¤£„»”c;£0ºèy5´* „* MG÷Xa{}Úp‰ÜÙ¤„œÕ…$V! jã ¾+=r¬cÉ`ŽåØ…Õ`~¡{2÷¨NM°0ù,Á?KU–OçX‡ðóZÄ‹è†óŠhœ-©qTNtkù«j áêW¹Ö¹&qmÐf—0ñÂ$p±ÅÄr@½xÏW´)ª;ü ñúJ¡½spþu_Œh{Ú®bm6žþ|¬xN„Á_Ü ¦ªÕªDåØjÔÔöU’†Uª@¶ ë ¼,b‰7lÝjåÈQ‚-¸ÑtPšb„«£-kÄdž:kɨK9–:­H|cèx)µ÷G{[èÑ^(Û¶ÐÑWÌÊœìmpo ý  ‹éåÚ¬žkWðí\}ó÷ÞºžØI¬ çÊyT#±¢jzÁ.R_jõ×L„ÞbpmÏœ‰pPo&㪗dÒÜë-ÙÔ¢5ÈÂÔ09F~¨< ½k'Y;†@¡FÀþfÁ ÍïÚëÑ·µ$<ðåu‘ÉSDxÍ™ÏÀM­ç³¶wxR¨±œXB›X„N,øâéYÄZyá å‰E˪٤-QkDm NŒ‘¢vÎM-jJÊ‘ƒ’Ùj-R#—þvr eeŒz‘ Š‚QÃŒ:ËæS$au¬á-^Ô*©UÓ‡ƒM'¢µ{S9&èbÒÀc¾6!¨‡B?·©MÏa#†ÍûÜ…‡(!Êöµ™Û¾!ûâÝR¹ è°IgÝœƒî0Ôæ&1¸|øô÷´(Lê´åiʱ4¥Båþ¼(–`”Ä•e-IXé±±mŒ£žºž9b×ê [ºœ!6­:‚”c OB(.­cÖQžª“ë×K¸šMµÄ†€€M˨®ÌÙ² ¸aê[•c‰ÆI¤œøf‡T1qCt#U ú2=†k­¤![ÄÖ§Ec§@ãtÏïk¾öŽy}ì.t5Nv©ãx¾dŸ×zeʱ„'k?Ö0Éè—}ÂÅm¾6øݧ-ài˼É1m…§fšTá¡ZXÑþM»z ¹ ˜b V bŠK¥rìHi‡r¬o°4'éÞžSŽõ?² Xë¦ûOþ­Wï¾÷ê½ÿøyþ÷?ÿÃþ/ï|Ó;ßúÙW/ß}õö—?ýåŸ|÷sŸþ»¯Þyç÷Þ~ûsŸûüW^á¯Wï¼÷•÷¿ðÎûï½ÿêÿôϾÿ›ï}åWÿþOüÊW~é7þÚ—>ñ©ßÎÿÎ/½ûö¿øÅWâ[^~âS¿øíßñÝ¿ð±ïÿãßðýÒ„Aý£¿ÔÑÿå™BõÀ×ÀþfÌSªVÑÞ}W˜ìá…˜ù¦©°kå…q9ÍÅ^ÂêUŽAàû† °˜Íf:ûû옻¬ˆ’»ïÔ«T­éPÔ^GÌçÃ, LÑôe˜ã£w õÜkzÀÍ8æîÛRÔcIÕ²ÖM•Ô/ï)É$­…a J±šÏlóäyjÉ›òH=̃¯áEÓ.‡–;G«ö…¼>Å*· îûX]›žº=ŸOIÏüÛvnêj¢¶¤œ“Ìü] $×X,ªÖàEu¹Ê®Ù\X=¦5Ÿƒ±›&ñ£[¹öc®J3«@ókà.±xb:K5Ÿ×Îî°àÐÚÒ¿ƒ|µ˜=cšò­PéÀO¥&s[ÞíÍlªÑ]ŠcŽöp±ZÍkG’…¢9%¥È¦’gp©²Y]£™#ˆTõºÂâP_•!’^yr3"ïràᶮ(ßG{` uÛæ érô+Z]»ï)È›‹ÓçÈÓÜ¥À.§N×Az]Õ½´îöÔX¼Öæš½dï|?Λ¾çô)¥<¡á•Çé|•ãcqÕåãuµÇÇt·yûÕ/çÝw×pã98‰ë>~ÓèÆFÃI9ÝåOÞl$²u¸#¤4|øãf£hläN”¡µ­³²ºfr)ÓÊ›’1Í΃µ±Þ”c ÐQ—-RG{âOÚ4ÙŽ~E«k÷=N-žNŸ3OÜldå4w½ë¢SÔ›öÔîÃæm6¯sG¿l9ú^ÛxBŸê¶œ›†W§óUŽÅU—×ÕÓ«Í>îW¿6o¾Ã×ÙèëlôÈFOùçøêJòµ¾ºV5«Ëƒ¸/“³.y©Õ=E­=\‚X >‚Í÷=‚«æ©Ý\«_Ûš•"¤#O¶îîrÒ41q×e~¢ö˜Àr´9´ð¤_Q¾;·en’¯]ÑËû6Õë:xÕÚ3C~Òæí©|÷kîzßg Og\O›£DÃ+Óù*ÇÇâªËÇëjéÕf÷«_›7vß_ãŸ×yŒUÂm]–iáɆ›\ØKI4à Y¨âä@3·Nz4ƒï|¨f0ƒ0ï&jÞ3ÌcoþŽT?äEÈžT ”¯¸îV©4û>p·ê•2uˇë4¯šÜUÁ æPÁògB!e ¯S}£"}5‡õ–.#W ôOÐÒeØSó­qÊ°1_¥ÂzDzæ+¥¨6ËPÂs²U~¦E¤!Ø¿C›ô:âí("J¤¡ªé™~Éh¬fêóÄŠ–wGJz°4º¼?”c!ö¶¢ø E-´›¤N‘ãBÞÂEƒ2Q@ ÂbµC /Š/ãu¨‡W¯de%œ¨‚cEé€x;omój–Ž,/uÃC¤¶¿Ðyg°¿Åy·Ò4§— î5#‰§H‰C~r¡ìLír‰VV$gðªZ½áÍk*Ò$:Æm©¬ÄÌÞp á`ØeA9¦‹Råb1\gãA9sãý,æ85%Xsôĵ—×Ðn ú«"d‘%$Qö­˜O“¬Õ×™—lŒ‡ñw™µîô Syý` ñry a[ÊA{eè›Õ¼$e„Y´¤çXg}6?òú€aãSó9…çùEs«^Ðb)PW‚¨¬+xÁÀ;,/¬IcÔ)a¥xæˆÕV7Ü£¡“µü“w,óîä =»¨@ÊÐ\ ºSj7ÂWõ,kNòÑ!û>0-ПQÔf¼îEŸÖ°ã+R¯{‹ë¦o´ii9š-“´=jg fÚp'lÖæÒ§—lý*Ýß {ßK÷;l§OéÞixä1:åØXuÙxí±1½Úìã~ôkóF¼Ø(|¾ÎFÿ‡lô”Ž¯.ŠM…¹*fpÈUÍêò aqX¿Žºd­\ ¨)¥ws_}»ï{[‘‘qwcÍ‹biï]Ó œwÜö›r²»ÁÜu¥d«õnOj¶Sí6G{zxõ+)ÐÕ÷Í-}àÍâv··rªó^u¼jí©1 ï…¹ {´~Ñ I<û^c4ôkÆõ±g¥™ïòC°µ"€“Ëí— kŽÃ)Í͇ÿ×cŽÃLþœã•7ã>ÇiR󺼼mŽÏz;Çg¾ãoÚ)6ÇÕÈkŽãêÿfŽKƹæ¸cŸã’ñŽ9ÞB¹™ã-´›9Þôå1Ç[ŽçÇýâ9Ç7Þs|§hŽ# ý9Ç[îOæx“sÅ+‡.]öoºL¿™ãT(ÞÌñ¦½sÏñ¦+Ï=Çoç8_üs¼ñ ~ÏñfŽ•®9ÞtøÑoz°§p ýÉ?Œ3C¼™ãï9~¥düœnæ8Ê¿ãM†Ê>Ç›æû§Óá›9Þ⸙ã°r8çøšî9nZfÞ¤ž¶±f³Y‹¸fãdIñ´¤XßØøQv_K†Ü<itûé ÛùÄ ®ÚøYK’e:qV›sô^În‹LÑÕ]Ämo¢˜ ²vùð±%©évúX’vŠ–$ܘ—öd¢*ïU½ìÒ.¼³SpÖæ«ð1CÔ}ÚSÌyœM[³þÉøÞÃâtö”ŒÖÙášç¾ñ†y À¸6‹ekÂJÛAßÌI[¿Í>žà¶ØMˆÜ[e7ùYöŽ†’Ýdn}´£†åà”ïÎ{YÔ„´Ý¦ªEc•ø¡Iþ$$v?ëjøQ­“®Eéð‰^i’·+sèí¶­Ë–Z|^˜mó£„åèRÑàüÝ]é’Ãaná»Yœ'ôwyÆ(T“–©Ý0¾ÁÂÎgbî‘M~Ýì?¢-ìžžqÀ4ˆ(À}Y‰$ÇDXúQÙ*Ç~®šŠ†ÓWK„›îä?Ñ#¼–u©ØºZ‚-Ô£Š¨ÒíÅÁ‰*©Ù@3ot›ÐhnÃIœù¡3»há3¤Gê47kjƤ‰v ZpÐ ~!®8ô£ ˜p¢ŸÕó Ŷõ~ê3ùCÔ‰ -–—-Î ñ´~ƒÿ7u¢ÿ=ýf*Ý8¤¸&sq^Ø({÷ÇR•¡‹,Ñd¦Èõþ– ”cÐ1ÛthnC¾Ö$h10‘æ6‚3+a³U£$II•‡:´G9Õ%À‘/™]¤Ñ+vâ q[Çë· =‰+À´CŸ`u&¦¹ Y$œ<ºw?z†3UeÑäkåèé )|±uGäͬXŠÛÙäaOšÛ¬änñ>^Oéîá'WþýZÊõUOJvoÿWñ´ö#¥{7Ÿ©ŒÃWÙ}ý˜‚gRú(ÞByÎ~&åúª»Ç‚òzí¯µp_íå$UÁ:Kvz‘ß!,ˆÑ*¯!%Ê[ äDôÕ‘>NÓleŒŠT¼ŽÊ­ßî¶6A…R.£ï&˜3žuã.hÿùè‰ä,†3¢fðŠ++Ö5¢Êdh5‘UNF¼À$E|¡4õg­› t=DÄfäloa1Ý ï£<쿧=ö'dxPDAàµYm3ÜkÙß ¸¶»1„ _õúØRÐoœÛNÉid…sMþw6¯·u¡”qÝÖÑ×½Ö*Y4'‹í¤ŸØ€ÈðSpº.Wór¸45/jä9€P†N1INRõ ŠNÉÎ~ë_#¯ÊÛ03Ê™bN’VY{xs°B탣Üiô)g#þ¼W2…’ôñ©ø¬5.è5ÕŒŠ‰dØh¿‘Uá冘S¨™Ÿƒ8B!¢¢·®^ñè”qç­(öARo†ï©3CÖ;1fú¡CОBN]PÏ®!iVÔXô˜È0k˜ ãë9Ç3„¼àË¿â"îÆp[XoªÀîƒDUѳ.ÃV â@ËW7ë+6Ñqãîñ =wŠjCºK«¹ˆD›fƒÈßé‘ôÊÐYÜd(/5•y›ºªp‰è #nó|™á£0(2ï%2Âtrâ.I\¡QrŽjüò g}¢áÀž:„m;‹j »3e±œáÝ/oH"u]÷ "8}§! Zî6Á£/2bÐN®k(D×jÇ÷zAyÖ0‡èd9`'Á¯¨¦È¡B¢ö9,b%EûÄ{TþN'”湫9‰£¢·U†­Cµ9ðc굜ƒî±6 3…Ö ™Ú5 ˜\jž°\sÏîÉ÷ë_)Ðls¢u=#ºš^†ÎAeH¶VºŒBÂ&w‚˜¸xMÙŽßõXÄŒÎ2®(½¸¢AcPaa|Ê ÅÃæ.ž«ÃFûšÜpHÝË‘ƒ±Ëápr:hTI1' ì÷Ñt<ænµ¦J–;0¥â¯á;G3sçYåòÜvЀ\’‚§W\õxoʨ"ã}Ú¹³Ö#ÿ]×N\SúœôæúlíîÜ@”ðx%È¡:Rº… ¾çj Ç6¬²³¯z£dDìÚ“ü÷iÓ¦ƒDnÇM#mð,Îçþ˜qÑÎiáã¶'NÑéèÊчHÆh©ÝVI‚Ze3ÞÌÓGR¥GFvæT»j <:5ÎÜG¸Á´®’ ö*jpjăˆdK^)¶xìE‘ÞŽ Ø÷ù ü1êš}8÷â¼Áe›nºÆÔÒʹÓ÷tóYX«íˆÄ]êÐæ×v1š¼ 1‰ÏƒËÆ ­ØŸ¡ª³­qÉò©Ø¸ÑâOcÅ¢gòZ£<‰ûkΈÂk#ÿáâ×z0Å’_LyÏ0ü°[8+†‹ô©ÏªøÒiÏÓª;ˆc&ã };rÀ«ƒùÆÊù‚ÅÞcì¹ðùÁr÷äõfíFÔÉxæpJ#^³ žF®©ÊðÔ]¹³ScÄÛhfžd.ÙÚ,„Þ\Ž0ÃÚ—δÇ´Å‘ÍE[”IaÂǸºJÍQá"YÒÊ•²Ýg¼WeŸ(š4 „'T@V<–ºmQ‘b&âN ø£‘Àû€!(ÿN÷T¥Üï†Ur0®‡äöý5¯Ò•£´†FÑöÕî ™ŽÁƽ‹%e£×ý G kjb;nT´Ð{j\ƒÍ+åñH™”-ﮯ® ·ë2X“†Ÿ"MµJÀIY>ª{U4ç¶Ê-àQüø7›Æùi?Mrôú÷RÙ^è-µÙâ±FäyÓ4CŽƒdìÌGÂ6½8Æ#–°9G*‹Å  `J,‘`èèë0ÛVƒGt”Y;÷l¢5â¼ ôl3V0™æÚ d¥‚Èy3rÕÌxìHÑ™W%¯£iCm¶3C]RŠÉâP`P»%j=:ldl!¸¤#ž(^„’jÂø·Æ‘£Gušñ&“–×Kå®è£8Ì(ód»[Q+áÉzlÌÀƒAÓÊsLùX³Û¥ wóèt¥èpÜ)œÛšJëø›Ã®·È©ž£).!îˆP»ù³jëù³™KÁ1ⓃàÐ3e?îƒàèó<Âï>Žno¹€…öAPЂÃÞ‡zO å»=BÏyfõæ ¸ñ>îㆽª÷c5Ù7A(£Ïƒ ƒ5\Á ÷AðJ)sÜ¡)¼=ªqì ˆú΃à…ý ¸StD}çAñ›ƒ žÁ!-€‚û (èAvå8Bs‡ÅW¾‚PŸÁ›~4àAA;â©ÂyÜÁŽ­úÓó 8#h‡ùŠ¹‚cÉz×AEQa´úä 8ÌýÙÎÑíkF,õµƒ ˆ¥ƒà(íæ ýôyÄ=ØíA:‚oÀý hÀ‚‚v„æø<ª7Ašå·½äij;-ùô%¬30B™ú’?]ƒ®ì%_p/ù‚¶ä£÷‡Ê¦zM{É¿R¸Èãi>}ѧñ t_ÓTg`ÚT”Tõ¸¡f!®°Ä÷‘ŒÉ#`èµNüµÔX#=â ½f—™xAÂ~BÀIfÐIæwÆ ƒxÐ úà&»R*?ÎEm 'a’Ï\~ÞWC¤TG¯ýo£—Áf6ÍP¦0×NT £q=Û[Õ¦‡íU{èàê.‚à…á§Và ¼ˆÚ¸¡ ‡-Ê°*žrðؼۄAínsîúÇîþ†ûžÆË»Á3Pø™BçÈ{J §ÆÆàªäêÅà¢]ˆèÀòZ±ŠîÔ~áTÈ]9+Û?'€M¦Âž š$,xv…ð—p7?²`HÆf™"<³\]xÒIº @ë ãuqì‡2{l`¼ §‰Ê vÞ}±˜B &ÚIèH}ï•Ðèr’—Ãíu(ßuˆß‹ ëðãÝT¸G`˜)Š üU9Ì–S¦è¡‡‚ÙÌXþÊÃñER‹q,J'Y çJsY8RÆ[å!Vá*r¥ÐÒ,eY›ð>A[³..‰³6>«rüBÎëÉ[–#qQò(j`í ~êRèègÂ[ᣟˆP%>P?ŒJÛÑÏ#Åy'I…ଓ´ ¸Jï6Ìò7%“ÇwRÖxÚ€Ýæ, ˺¡:·bïI=’H8ÉŽÌYz»~Å­GÓ¥žž¢è‡}h‰À$D@*±Y§×öµ  b½~ÇÕTË8 [l8½ÈÉ‹úOz‚be¿Ü‹¨¿¹t„Ñ(#›lÍ3"#_’OÞJŠ ‡Cä‡ æñ{Aá8¨t.)2eêE×g‘QÞ[iNRA3šÚ‘ÞçrQdÀ—6ó“w‹\ºéª¸ m.Ó]òõâm @å&]Ôêú‚<È Ý•qÓ0ÕGŽ¬åñeé[¸YrFÄ0ÊH0É9¢£ìØŽ -õÝòl¶*¸a¦›'î]’]SscôVN4ÓÅR:+/—É‚x Þ[8.ÈnöxxÖŽÇâL[èèôRBÙ;Ï …k79@«½5[@äX¼ÚJɧöK—¦S1õïÎh8šéùÞšåR8#ÜöÜžíq†A]äÑþ<7ð;4ƒMñQT׆†û>jž}CK…†±W†Â€Á\=¡ײ\Zºíö¸¹å*Ød7»® Á­=˜`±¶6ÞbžÉñn±ZKk³ÞÓ¥¬Íõ¹Á6ñ Q®ûJN¯ÃB·ŠU¡L9£ ]áN­y Ù€«š)fÅ[r_ˆ[£ÀaðñURËÞõªlˆ}àÑ ­'\Æw“9Ý–9Ü!µã÷Ð5Æuƒé+:¡uNÓ¾n(—aLѶîNº NênÚÀï¶19䯞Èä¶*Ç2¾ W½T¹Vi>N×ïÉ7Ò /Ì0Þ’ˆHû0µÞšoZK𵛉½Š¬,Å'K0pæøv±R=Ž¦ úN Ð÷&x "ËPÇSM®•%=8¦jŠšWŽÁ¼Ë‰.Á>EÔcWytص.¡œ%Ú6X}v̱.mO‘{¶9™—á wX5ÝÎë,”k-ŒÙžyìÊt(Ì¥2˜“ÝðpAºÙÕbse`#šŒwÌœ ³´Š/ä—òJ®jÞΙk<ýèJ.(îëªì3Ã|0â¦tAø6´ì–@÷}èV½ÔVͧxl?]Þ`rŒrï´ðxµ‚•~$åºyú·I {_©Cºø¦ð¶›ËdT¼ý]ç'̇§Ž'óµ|Ã|-?e>²?˜¯•ƒù6ó^Ì'ḣrNæÃW'ó96vë7Ì×o˜¯Ý2_«ó 8ómærækO˜¯?e¾þ„ùú-óõט¯?a¾þ„ùÆkÌ7n™oÜ2ßxÊ|ã†ùÆ-óõ'Ì×o™¯Ý2ŸÑ™Op3_«·Ì‡¯NæMæÛ\vË|¸¥äá[O‹_Ê7ªíR ßLhò†©ó° Ä™ØïrÂÏq4ÉÃÏ+]ѳ½†Mð“Ié1(Àr&Dº©B¢¢Û· ñz+Ë¡h³ñÉâÒ³—QWMtìÚ²À5f›æ]/ç¯1Aó®Ÿys.Qü@¡›ðc ¶Eí¦ÛOæ7çz-×ïz'ÂýœoU‚Íìâ&xuê$9TµÖev›®‹}³rÐ;ÑQi3ÐÏ8F]Ë Ü–R$J‡»òîLCŸ*ôT*ÝJÓå[êvÈiòG’ð´«—ém6˜ôd9Ø~o±:ãÂ&¡–‚GG¦Š@1aj Qèöhò‚­F;A Р­ÉSÄÌÄ&|xi¸·eÅá`+‹›œðòS¬M›l(YÇ1rÞÜ„æ^qS1êwZÆà Ru õªÏÚ”ÉϬ[Å^\õj¡ÊAþø_ƒÝh} 좞êaÑcèºÏÈ,ëÂ=6e)Cx jRž=ìb ·lµÞÈä9È Õw…ç!“ç  —LžáúÉA~Ëä\&Ü2¹AÉä,çÉWÅå”É76òÎú)’UoE.™<‡}îìL&r™ÜdòdVæ"÷ÂõF&ÏA.üŽ ãÉs”߉K&ϼœ¼dòŒ ÖC&ϸD¹‘Ésäµù•÷}{cÙÐeò+šª¨x¶Ç°¶C&gó/™<ãÊñÉ&“ôý+ãvèÉ3®™| f=dò‹Ëndò§iN´”¾DJJ®2.?rqEЂÕDp-Õ9š¦ÚÏÁ¿Pj*#g tWöwÖÅ"®Ÿb;hj綔·RLogT=ý9ÚýMÕhFDþ;Ž°÷¼4H„â-ÛÁ?5ñ„ê[¸HŠB!¢<:¤övýÝUÞ1¨à‘"¯±Ÿ¶èk‡jó{ŠÑŦ“Gâj¬(sÝÈÃ5f€¢bÙ3ÿÔ#àE ¢¡tPoM‘™ï®öÏ­Šk`h)“ÙÖ Êü Ãjæ\¦¸‰ˆÇv)I0$؃âŒ{`^[èD˜áºÙ^[8šÓÈSlÅŠxuîr¦Ë9Jï¸׃6×Ø‘‘tãÐÑžPê:gÁi×ìú¾ëØ{•o7fþ»|Ñð-09É'— Ÿ4ŠAwÊ»Xƒ&FX‡ç{×¥s¤;Óýo†›ýfçã`#×Ò5ùlݸæ¦N¦û÷ܶ®¾ÆO]ì ÉÌÔ=ÅdÒTh£—;%‡D’Ó/+ºŒ£&Š*ƒÁ+¿¸ƒ# X{Êê¶ÇÒ§a+Ó±×úân§tJ±SÀ0«~è4sµ{È•ÃkuL§Ö]D;°•Úî)»·VæÆV«Èòu’Üä“wåú³6ð°N§Q8 …Ê*1ì‘|ƒXo“&V¤ ^2Å@¡qò»Âc™þÎI´ˆð‹2„ º_ëH*í%píð¸*À÷À•Âg©xWÑøÁ˜ Žœ´žú|ÄûIµäfý­F¬b‰_ ˜f• }‡Ó'·‚¼‚þÐæµ¹G¼hÈu§<^)0\ü£#;45Èbí!C‚ó±%UZ‹ø·µïÆø%H;ïù$Å–õM§,ÿoBh›‚1ð.aÍ×6hqÏŽ‡=|²©Éí+&âÊ!'˜ Öö´ ¼TºÝÛ¼¡7mz(œð‚dM)„‘ì”0[,™ÙoJ5ßÑ2éåi¨/0`{Þµ*óBO×%8±˜™Å9ð;èÑ¿Ýdï²JÄkƒÜ_‡Ê”ÅÁxž,Â1’{ªX\©lÂîE!vð»ÊùTÎÕñµN÷GŽª¶LêJ"Ÿ˜L±Cât y½³˜&R˜ÅÂ!Ïgé@?|´OGŽÄƒdŽ¾/è¹rÔ©Ë8/Áñ(ºö;R¨ºïÔ¢8¨¡Ub·d u–††ÎX!ïï8¢ìÙ„t²f5 $± ‰Ð8NŽñE§Aú•cÈX‡—iãÀj0¾ðéIÕ©‰NÀ•»ITÔ¾[¡Æ·R¤4‡$^dYfGx“î s (˜èH;"’gâÚÀí+B=/Œì-Ùbb9 £Ð…wŠê?€¹`Ww*í ‘ƒóÏÄâQÀ"D»©"ɦçHzPœª=òd÷H’«Z­Jïn#ßgè_ÃÚev‰Va]‰MÑÜ [·Z9rpØ3uä”’LŸ1Y#Nk< C5ÕLNZÛBki‰ºÈä)¢ |šÍgà¦VÆ=Û;-å‹XN,¡M,ƒ"‚dÁÄ‚÷v(ŦIòV ½/Q ¾ë¸11èmžÔ‚µTŽ5ˆ\XHD.ýíä‚=:Pº‘Gäʸ4<©å F\|½†’B‘á¹µJêf£Ò‡ƒM'"X%èÃ>.1 žÕJ¾6!øÓ ýܦœ;‡6gìs9EðÌ씕G æ€`M» H2z9ª –õØ ñ°d²‘•Ë‡Mÿ]ƒÅ7£î&ÁcAlŠbÅà™þy"ü‹5Û¼± ßqŒ³üÛž9Ö²ÏÕ;Ón!â-í˜\«ÈÀ`— í#ßG˜@ÏXR°âjf‘¹²Ø°YŒ³¤eԢɠ dAqÞ$ÛÚäíO%F)ጸÈèqSŠîÅn¤Š"¯B×pM:´TlWBKÁÚ=¿¯ùÚ;ùŒ2èÞ]ÊêjŸG'» :¶}ÎC7Zˆ8F£Î½nÛ8,ÓúÑ,_üîÓðZfž9pl’R¢J$ÝØV~1´‹â-U×ÒJÌÙ.÷£ö…R²H~ê~pXÿÿž‰`=‰<»fÔË»øÈÝ[ùK÷ç§æÇîÞúØÊv÷ÖŸ[g¨»·~à‡?|ïÞúÁÇ»ðWïÞú¡·>üáZð‡¿÷{ßú ÷ß³~ùðÛ?óò'ÿöúäCºûÈÞ׿þ_ÿä/øÿÖ§>ó™/ü/¼ÿµÿ÷_ø§üÆ_û¹ßúÝŸÿпõ~ëwïç?ø­ÿè7þëïý½oø¸û³¹ÿ‘§ÅK’ª Ñj‚Ð=%*i‰Ij¡Tp4(h¶ãÛ°§È­èù ý×Ö«Ì­VèU•wÈÓ×&ôp¨2cÔ‚y­ŽñZ-ó¼ZO7ßx߼̭֭Ò*.z[ìò—W d£IM£t x-Iíd‘–Ä0}ÞQoæ)èR‘àáß$i+½Ì­V^‡5‘¥»3fO’V™UdPL^¯Õ±»Ë¸Rà@Am÷ï›—¹±ÕúBÞ ¾N’“$Ϩ´2Rg¼O7'¥|[Cøx@]mfx‚€ºÙÀú£\ (\/\ Û§š ^¸W]&a! »kNj­+%òök!¤Æ§PwéØÐ0¦ø†vÛ êÂ}°Àöö&¸„FÊô(Êz†}Š“ŠêæÓµJKj²{«"-»§<^)0¡ &ku¦èÍTQ3ŸšœÖ*odÌî†Z°¹LRpñu>Þí•(@Ví8êØo®¨h¡KF“†+Jk†Ü].Ä`†qZÒpá)?.ßXÕ¹XwpÎ*JqÃL¼èÂiþ5à$1H¯åÊoÃPÜÉz†+âÖ×`t~dÂO2áé‡_%Æ”a1b*]ø{EPÔQì¼RÄ5ôµÙ_‡Êÿ(Ÿ•Ø£ÁG^-ƒñQu;•M(‡G“™I‘tmgõö×1¾®Òp]9¤áBÇa Ï›uŠ%’ö«& Wt1–ñ~"X9ÈX.Ãø¢Kõs 鯠‡âM­ã%±$ùû´”ªÞöê @w _àø…<‚Æ#C‘† ¶~Kc ôêÒp¹ëÄî*»4\p¯3䣲KÃ…Þwd€i©ˆPŽá+±'[<úŽ`$ÝANÒpE.A0`§ñ5\1Úø, —a|®=…vÍSú+X@†vapƒñ¡§tÝÈãb.8-©¼H–†Ë0êOø+G”þÊKØxTó?¥ ÝöGi¸‚ÎÕ 7 „ç44Ýc…uìõé‚C.Ž=¬Y I¬B2Ié_di¸vŽ"ýÕ65l Æž¢ˆëê4\¼±•õÔR¡¥m; Ìz‹fÉ”† †ÔäH ](œèrµK{Á”õüdJÃÌ[!^Æ ¿›T-&–ƒ/]¼xÒ;gɶ¥ ñ:í ¡áBŽeÔ1âQ@¶§í*2æÊÑ¥á‚ÇOÚ€KÃe í׀ܥᢡ·/q- èÒÖ|橦­[­98±àF%šKlA„e•kX1˜Î\Ö˜¿\®åzâ×6x¿è{_p´·†0¬×¶€8qœ•´AóÜ}[²mÅôrm Vϵ+x‚vžÛ“¿÷vГ4\A#¿p¿ªÈYÓCZû²_3.R×ö(ŸŸ2X;&#^x•=÷ð¶-pÔS¼ðjucä¯Ôpí Õö–µc–¯zÁ8š_“1BÂ6’ñ¨KÔ&ÓN1ÚØ-ÍSxQkPÃÄOpez‹`‹è"– kHÃbAˆéC®àZ’U³4\N­iƒcNÛ9ZC¾^vŽƒÈ……T@äÒßN.!ÝòŒQ/rá!Ú¨á ¢¢IåׄU(Œ‹CÕÐf„ ö§¨JèbÒùÚ„Ì%æ±M9!<‡6gìs²(·KÅ)Û¥áBȾ…XŽª4\GÅNÝž#KÃ…«0,6ýw îo’.¸C£†+3,cÕþLÏsQ.,IXMM䘎!¥áòCÆ*±I³] .<Ìn×M\  dÙuQH)žžT%$­Œë |K’ GWõ\Ft² dAq\ 'ÛÚd~ ¿¸Ã\GÁöqŠ¤×pMiƒ.ZŽ. ×ÎQ¥À 2ØÞ°™ZüJÉ|½Šïk¾öÓ» tgýJ¹ÈžÌug–† o–²{-%ê=IêÓ´»7øݧ-ð¥Ø‘cJ®¤‘‡¨"±¤IÕaØÅ] í~O\¯¥•˜³¬º¡”ri¸Ö2+ פ«DPµ<£áj®ùGÐpµf®ùë²þ©oû®|ç·}ß7ýÃïü…ßþÀÛæ?øþ¯¾ü?ôÏçóÿîÇïcŸù¹}ú_|ãÝ{õï¿úÒû¿òû¿ÿ¥/~æ—?õ¥oþ‰Oýúw?|óþÒ?{÷G¿ø-Ÿø7á³ßþÿøÏßç>ÿê÷^½ÿÞÿ‘ßù·ðåß|÷ÕOü滿üÙ_ ¿ú§ë¿÷í_üìg?ýÅïø+ŸøÑ_ÿëåóßpÿÇžUŒ1NÓ¤Bž"êË+¥TÙµ%YªE¸Ø ùÖ4Ëár‡P¯zQ–’§° +sc«•žj”’¢©*v a”áeYòíZ ó Zf)4A·2ÌúÏûfenlµnÅMÁ¡')º¹y¥À¿? š²uZ>i³ùùt ²”tæYr>ó$ĪW™[­ ‹¥¤îÆ…že5·Ë„œOC7«Õ0Èb-³{IpäÙ}³27N~N[¯ûŸý:]žÐåí]ÈdªÖix –OÒÕ³«Ê)Ž ñž0ð¢„ð»ÐûCÚHUÚ1Áœ†´c£„ \¯¬E7Nͽ–¬(^/®z3/‹é÷O¡ÉU™~ðsœ?*â]¢.,Þj=ö*íXBø ÖÓíS#)#É¥ïŸ1\ò QqÖª;åñJ)1I¶¿:S¨G‰T/©РO ôj­ðFB fþƒ3Ã@& ر0]1Éòà… Åì¿Ñ°;2\ÄTÅ“§k,9.j26ÂÅôP¸ \0‚ï@Ö€ñ¶s1}\lVQÊ£;†Y@€Êä“hð0AøxA¸>ÓôÁ›¡‚þNs85ù³\„ ¬üM»Ö¸Å.W“{ﾶÜ­ƒLô|ÀµA›<æÄ “ÀÅå€O¨²BãùA âuºÕ¡‰ \ÏG¹ðñ( DÛÓvUÆN;GmZ%è$&!rIŠ{”ßTµ*Q;–TžÛW"×&Ü°Ö¤Va]ATy,ñ†­[²×±!Ø‚d‹mÑ.²Fœ V©ä±–¬º´cô­RöÆÐéPÒ÷C׶`fé{[è$Ö”‡½-ú¶ dÛŠéåÚ¼ž½+x‚vÁuçü{oÃÞP¬G«X(SOkõ¥¶sÍD(.×v9¬:“q„Ëž{0\ÓÔ2.R19F~ˆ¯ Ú9šìž´Áëo¶ñÑŒ«Ì ÉÑ̈ay[O2í£M·=ì ¼¨¯`¶wÒ»K=ˆ%#0'ÑE,B'Vë²NfÈÙøÞ—ÄjÛ] å/£V·Á‰1¢v΋ZrÖzåPyr)`äâß›\D±™-ï4ò\V×7¢†'ˆ:tæÿ’°Š°^Å‹‚±}P5´îJá “ÐZѨ3hbÂ3”|mBCŠãc›rBì>bsšiߟ“FÙJ/à݈̑ö( ÓiøYE²£·ç€‘67‰!³Ý`|ÝNíXÀÍ–•bÚ1xSƒ0äHš0ŒZ’° Nù¸u Ê@Kuæè]«7ìè`oH(1sÒ‰‡!—r—‰zëÀ‹. €W3jipA6¬rP¢ P hÇв ¹au ÛæçÎ B*~2x=ÄäCª˜rvÐ1¤çAm„œÙê8`u7{;%ÉH¿rcÞ{,"(ƒîÝeb]½R.²›>ŽÑÚH¢èÚ±4)R6:œž2øåÄcŸà&2_¼÷éðÀeÞä°ÝIªiR%RÒŽ%¼á.Š›K $œ÷½Zs¶·!íØ‘²c-üÔýúÔí¿ð|TmÏiÇúÙþ«uÓŽý§?ÿÖ«wß{õÞü<ÿûŸÿá?ÿ—w¾éoýì«—ï¾zûËŸþòO¾û¹OÿÝWï¼óÎ{o¿ý¹Ï}þ+¯ð׫wÞûÊû_xçý÷Þõ¿úgßÿÍ÷¾ò«ÿ'~å+¿ôíKŸøÔoçç—Þ}û‹_üâ«?ñ-/?ñ©_üöïøî_øØ÷ÿñoø~©ÂÆýÏR“¿"äëBZVï”!ýÐWÅþzÌSð¬˜9†TI–ÜÕiñÑì‹Â€¸œæb/ï(f¡”¨7œ0R5›iY3±UykíF=PÎÀ=#nÃô2q¯%M¶HÉH•›Ù˜¦ì`eéóQ°<Ñ”)Ek~³;7:äïv8Ÿ7š—ìR!©d3§C8›jE™þ°µ_¯Q³¯!æÓ¼ð¢)ÌôÏk•ë!¾¿KM*¦bæu…¯uuwJÓÏÿº.LˆJcšÅdª©èúJ,44ó÷{dûYq /ª›n)©!܈4êZÔ⪩?*×@¼|ŠÆ\9Ê*/á¬ôNÁ!4W\æa·²ölõö.}­P«ÕÌž1M©KéþW·£Ö*ž:ÍCYnö€ÑJMÓ´c=ïÅâ‹%Ùú“gØ·¢úäÓÃd««×¾5qL‚Å¡¾2}Û‘‡aŠoÊ1}ÞQWª¢àÕDY¸ms4[º«_ÉêÚ}×}ÒEŸ#OÍ®`örh›|SWiåI{òô§ÓÞæ½dïW.>#¼ïÆ9}r*Ohxåq:_åøX\uùx]íñ1ÝmÞã~õËyc÷ÝÕÜöCâ¦ÍFÙبm6J*n?¦Ç@2MÚldÝÓ³[>Œº-üË¢ø¤4X]#ì·ôÕØh¿·/Ãfæ΃˜çõ¦[€Žºl‘:Ú“JxÒæ âG¿¢Õµûž‚êpúyêt6òrjvr{] î{ÓzÅ¿i3ŒÄçM¿l9úN£íúäQžÐðÊãt¾Êñ±¸êòñºÚãcºÛ¼Çýê—óÆ[ø:}þOØè)ÿ_]ã}8¿ºV5««8‡õëªË"F®Õ±»3Œ&A¬ ÁîûÀA¸Abžj¶×ŶvÅ®#<¹Ùº»ËÁ#¢~SWŠ¾Z{{\`¹Ú àÛ~áã¼é»sËE]ºÙ½œ¾¯T½®‹W½=#|Ûæ¾÷@ï×Ø-ô¾#Ôð“WÓæ(ÑðÊãt¾Êñ±¸êòñºÚãczµÙÇýê—óÆîûëüó:Q¢bl8êJ¨Fn¸}€ÌØ,%$‹…“kW¼ ™`%W™V…¦ãD Â~?I(í{žåÉß“*LÀžT Jƒp®R=^‹ãn§Ô+eª^\É ¡xÕ” åé½!Xþ¬ÐrÊku y ø%ØW}xäˆqôzo‘‚ü0ÃË=¾-Я Ôéºæ+¥¨5Ëž“Ý'sNG \Z‚v¿J¯#Þ®á¦å¦XZŠºEûƒÙ »wí+!P ƒ]04ÒTø¨¶£E†’+ã-L4C+ÙåmÞ’®ÕèBV±­Úê 5¼Iö^ƒp8KVVbÐ&ªáXQº`Sh1¶ÍSò. …¢Ï+â¡Îz¬LžwxÖ‹ó.c‡&¸6 bd¡W<ÅD zcÙ™f,õƒÍÓ \W«7UAŽšE=~¡°R¼Ý9†L5Ɔ‡j×cQªÜX¬+ Â0÷ 3{ÆFTšf.*CÂ=ZÀ* -î/”D…jçb (Wc O,ò…QINv—g9`žÄ ÝA¨ò°(ˆõ@3Âî^x.áÞ^ñ`Š¹ùÆBößs”¬ 1“Wl šÏ©ŒY¦â=á-–u%ˆÊº†¼×ÀvÜ›jÒè‚Ò°R5Ðrž?-fO°{ÈõÂz“RƒÏaÝÇSËn %ÂÎ[åwè˜ÓÑÎ Mmg±Ž‹¥¿Rjfkk»YnjišV{A‚ý YÏs$ õSm}I8Þô¯ÿ{_ŽlIÏ[é×*î *8Ëèè%TH!E¼räôö›ç€dæýätr~ë=ð239Ä@ 5w+ëCtâ•(&Z„âµd¡V±™hðµ(vr*â†ïäÌŠ– G•ª {R3VQåF£•4þÝfðáø;G‚àSo¸ÙpZÌgGŸ÷2y%Ç}Q£j~=\d{¨ ¸…ˆkV]csEˆ-9m’÷ù_kºk8…þ¦ñŸ4>ê¦qä~Òøiñ’`OõIãß-Fã£ÛƒÆÁož4§›»C)ßð¦ñÝ"Ï»iÎLO·Êh§G oªëø q4nõÓ6Cѹið“Æ‘Žø¦q€o1½hؾi‚ÛƒÆgÓøÌŸñIãÞ4¾[¦º=h|öc¯.·TæNãàöO‡tqÓ8Cæ.­é¦ña|<ì¥ÆX•ØÚî0™AþüT%‹Í­šS80½et½o`z)²nˆ©~ ÚÃ줳éþÚôôF:²±$ ®O-ƒ?"ÆRÛGRS¡ÄëH:-zX—ØlÉŽ7ÊͪY„jàìãpÙƒÙ-M‚w¡g$ãö:Ú¤Py;{tS‘æ—lTùãê°ÕÑ“à°pUÕ&Λ1^ƒmæu@ûrÑÉt@—Œ ª&ƒ!ü€˜ÐmuØ€ÝÀÿÑ‹Ò}ˆ<’æªâ'K¦ƒÒYÊ3‚TMNh¤ßg±G›gÍ~Ðäz¦±<Æz }IJ-4ÝiI¶…ZÆZf ÙˆÙý´Þ˜ WÂGj +Ìv£.AÓfù GTX™%ÞŒµý½îf¯A £#ñ-¹áu#`º¼uã…:oÖ¦5nÙ‡ªÏã»ppL×ÁŒŠqÂf—aÕ¶hR½U8ËÒÞ›jË-¸þ6–0é‘gntiú'²ì; Eùµî>Ugêä¹HÀw×XÛoóó/LQ® ÆÁÄnÄ56¼e„ÓB"Ä tNÒÿkjb¢¢® aNƒ ¤3›žÇÅ`Ö,¾»ü>¶­ž|GÅ{à²Çw$r–nBäf•]ò3ö“.oEFÀ¾#de/h5ÛŽ÷`‘É⸗5IsX IY'ƒ{•ø IÅò`±,žV¢YL+HZ¡ç[žÂm:Ð p’Àáãëò£¥—iÕuÓ«Ö£ÉDC'A3º`êQ'‡B˜,pVŠ# ͤÙÌdu*Ñ`6<3äff§‡©ŠåFÿé.ÉÕìµ )ókµÑØu #;+v8MײvžIÐ÷ì;ièuh.ÁzN°J{w³ÓAv3<gш¸£Ú2íÏHµýÝ]%màÇ@â²ÑØ”@_ã UFݤcUË"ŽjWGÞ03_.î¶-ÃJÀ­Íig¦pHŒväZÝO<{¸Å5$ùŽ…ºWÑþW9@ý¯c°|M”(È€TþÈÿòñ««X:a`´Q™Ù#ÊÆ  Ym˜uQê3€?Êžü'(v¬Oå¿"*ÆæïŠU¶½4H¨9˜“i.²‹åT¬Ì"" ;)٘Π­…S“)ÿÇ/GMÓ@4ÁõP8tBKšüaºg[€dR\7T‡7]•ÝØ›ý”£´jRZ W«ÄŽD†Óø­Ëd€Lœöw%Í@ÉNÝ\v\I—‘É´ Tü­š•:Ž`¡Cåó«@9†¾¨&ü1`xÍ­V ŽÊxÊiJ 4GVv®dyŸ³† E¬&¹8Ò‘Ù=ócbj  “ÄnítLV9ºmÌ•É_@:Þ½³#qbˆ*KiÝ8º¹Ò±éd´š…×gúX ;l_Q’ Us˜rK™¿×‚…¦ÈÂá.; ¹UÙÒ<ï~3LÝëO¯äW{qK–<ë8âŠé5íª:vûÖô«êyÜœŠÐ¢ÄQWŸ2­e¿§ÈãêúVÖ5ö5D<ƬÌÁ÷¼èàXï¹ÇØ-õT³ËÐ݇uƒïin·¿eu®ñ´`W{{Ì´?æUýªzÏ4÷úDXËòc O_çóß‹ý­½_{<{O÷˜÷¾ïymÜØs7w›„¤¸\Ü´ÑÈTGs4²ÐÔ8“/7¶”H“}K¦o¿û;E¤àÖîäõLY-\]K¬%l42/²ÐwÊ{õ¾úàF¤>ÞSby}+™_ÜO¶ugÌÑó™íy¥jhÔ6E¡ÑØÛæ}ºû;í÷ô¼ÑÈóá%G£´‹Tl4²1·¾ÑHóŠÍƒ…}î±Õô\Ÿ¹.ßkxõ±u¾Þã{q¾eûuÇ÷tyïûž×Æ=w¯nò/4úý Ñ®§ÎŠ!€‰ç9Õì[Å×yÚ¼ÎNy+Gˬ…YX6,zóp>°w°«ÐClW¬¹»V¬J¡yõÁ`¼§˜ŸðùnËãc<9§ÚcŽ~xæµ4õ™»§^<Õû“Ûï÷Ìè8æߺpÕƃœ1ÏÍm^ÌDs7Ç—›âêØT©5<}l¯÷ø^œoù~ñøžî1ï}?órܸ$7þ|ãØv·‰¸=EÂzTÎîJXœ­E/—…×1k (y/˜êlì2ö‘ƒàÏŸ_ÈÌÎ]žÿki+u5¾o+ª×!R3ØÞà<)ðiÉú.«hE”†'Ä Ã8‚Ù'Ø‚8'´Ð݆ßäÜ)øc¹ñÔH>ÛÎ뫈$ÝŒôîTþâsA,ƒÎ5Å”Úÿ´ØG4,ƒ¹a›î6 2mû÷L/ˆ/H]¥e~ºZ€¬>¤°Ý ûÊÕmƒ v7+ö²QåY¥Ù™Z¯fžd ¡Ð݆Ç ºR´) Ëô¯ñ­> ’x«zõ7( ¬4Øñ]‰ÙÉy£Ë¥Ž`ŽWKW0WmÚÿ šl´K%:@wžRhR¬N9×0è—Øé-ÊÛ]U僚MDâ¾K¶¶ˆKX͆ecUUZ‡QÞ*ÓBvõàã,Iï€]9¨È+¼JŠá˜pRyT:è/¥§jXÇ¡º l)B[jVlHZUŦøM°ê‰î6ã#ÊØîQOÓ‚Ï„)-W ÎQÝmÖ’Òø‹œ>æ«m«­.÷Cl6>š [ÄU:eÈÕ °ŽM%h•s²¾1ï_×Þô%íAО¶]ŠwRítƒT` †»Ûð¤W /# UÕqˆO¨C½`‰çw‹”ôõxÕÌ’h²F£I7 ­E-ÓV€9ºÛpÆ\½à#ž{}£Ñá´°c|Àß òþ‹pÜ@òrp#Â1h#ÊÆ ÙˆW¶ö¾læ¯åñ4øv±p©è*>“ c1ÔÚ‹p_mFèÍnCOKº÷$Zĉ0ù°·2fú‚Í\vµ S•²#-µü|àFçæ_ÔÎw•Äúщ@Lj¸cí:’¿(ŽÇAV3p¨òŒa!Éò ¶¬É™C“ã¹(‡¹ Z¦0®gmw7òa‰Ø=æ:ÂFF Aô gïœôa½" ÌäÓ—³j4{k¬ãE±2÷^4ÝhÀÜ`sÊM˜…1n¸˜™ý´ð²“c÷q‹$ÉjHÍê ì#Ë°{T£ƒ©-eÛæcSîZGWÁ‹QL´ ś̻ë)Í°j>«4at# N%0iì“XxŒ"¶dû3i<ùaT†73ÛÊÑÌéðáø;G‚àS ÎaÂnÉøÙ?ï;eòJ*Žûcj†¼{瀸$ðÚ(a…ƒÄ5éŘ´"˜7}'yŸÿµ¦Nã¸7}Ò8n/nonªÂªÉÿð¢ñÝ"7ïÅMãp¸¸iüÀNã§E4Ž»Á›ÆuKwѸœ.‡áò¢qV\¾h·,‡ÆQ79Ê|¢qf!¾h¼ò9Øqè´ˆÆí¢sÓ¸\.·KËMã6g†œóÂÿ¢ñÖÚƒÆ[oŸñ¦qÜ/Þ4¾áMã»ÅF+94nÃEã£?h¾77] =i\—P7˃ûиÉ›ÆgyÓøÌOGVí‹Æ-¹Ò¡ñÖû¡q¨°7·Ö_4Þ„Q§C|иÇÆOKÆÏéAãxÿ“Æ›¼°œÆ©S7wó‹Æ-œàÐøÈO®©Ó¸'idª¥ÆE=‰.šÏZÄ50'OêîÅæ†g{){®†%Å7ï$Û¡ºÙôËoõc È2\ý’5æhW‡‰”tÈ]ÝEÜö&Š¹Yv†Ôö‘„ü¦¢ýHÚ-:’pc^.0'}ðñ,µy<©!mxf·@צIypßLÈΆœèð¹tÓžl~rBüquX@Ÿæ(à d4Œ;:ïÆx ¶ ˜×I€»}!·:ÍŽ´!R.íÑg2U.0¡huÔ€ÝXL¥(2À¥yC$Q”O:(ÏOÌr§fm¿óüPñ<ö4šý #ˆå1VGfHàÙ$mâ2”AHFL&fbâ"N˜í˜kUOd  —ŽºêÌŃ³wE¨Qç\ì¶ýÈ@¢AX¨ŽÄ7]§á¯˜[SŒê¼(ϾªŸcöÌc»¬ûyÌv÷JÎM‹®M¹ÛpàBþdf–Ju²k˜² á<µO„bú§—Ý}Z2ηHÀwt×XÃoí¯7 ú<ßÐMQ®Êî7ˆÝÓ8vá´ˆ»!W‰2>uÓÄŒŠz؇9c“Îlz:C‚Y³øn¬Y;˜ 9i)eÖè©šq’›UÊ€ûIŒŠÊ¡ˆØw„è]÷‚&³íxÕq/k’"8ÆýpËZ‹öŠ8i%ÿ†‡„ÈðÀ•r·áèdkQ¡A&}nçd@w¿2}Üb]~´Ð8SîÃVÈp÷È2Ñð–À.1\î6 œ…9ÈDOë§! M ÁÌdE"+rÝè?M~=èßí`÷Hý¤ ÕòUt%”ŽCc«’ûE¤k*Ú«d5’(Ûá¨S$ßöÿ^é`Ÿ.BÓÝFשlÝsîPòEÛ$a²š("I8Ôö_ôlêüîç´ Q3ТCà`{ŸUd¯V©ƒ–¢e“NÀpÛÖt±3q3¦v×f:ÍÒ³-a¬Tk'¥xöp‹«•êºÛ×*òº¹øÿây,_e]#l€_µí_X›Nµ!+­ÜÍØßXƒ’¸Ê Ê­Æ7Ç0s•R£L…4̇$ŒèL„ôÖDÅì ž±C …v’P³Ø®€b锚ŒÌZÜ”BÿÝ ­¸›Bj¤MÓQÓ´0»nzè°g˜uV\qèuéÀõ³¡:äÞ.»±6û)=†Ëe C3Žži“6 §EHI§kôÿ»+iN#álƒN2^j0æ´ßª’À‡\°9ïôy­åL̘Ýmˆ×RA$ôL“™BÒ€à¨->\­c2öJeg(³Y»‘Ö<2»–Fg¬Ði/„mÉNêà˜›LK0M阉énC 7ŽnîÇìpÄ ¡[xM¼{,…¶ž¼GKœÒ<ùðôÍ~•-Ã?´Ð£›-Íÿ¿ZÎSµ¼ÞìÙ,þGñþúÝ2ì24W¥)ò<ÍxsžÿMKk^§+ Á?´œ§†’¾^-ß_ÿá¾ÚË)°v1ËtÖÄdG¸C?-9ªæzdºüùóËÀ ²úÔ¤S'+÷ ºóF…¼ÌÒ£»GbºF{\²c¨/ÁFª[@fÁTˆZ¼·‡Jb2M_¬‚”Ü2ª©_SxM’U0:8›âMùænȨ·Îü‹“ù"s‚§4@M ~T¾ÊÓˆP–¿d8€<¡M]é·Æì¸ È*ÍÊÜ€ë½îM»;G¹ù² ÞÌvL­Z7Œm˜QÞØÖ#‶7 *jbÓ±wz!­¨´ÍpFÅ.˜¾~ùŠÝ°á£á·Æ-agP^Þ…¨^¬Þ#¨œ)qG‚È^Ó×¢{>D”™V ÇŽqc/¼¼,^«{­^á…vé` ‘ â b‡ÊÂùï,Í=‰7 ÃKhý^0±9ƒUÔS§å‡í\h”úóëj ¡¡X$s5¿AVDb¥u]¡”ÁЇˆ=Dè][$©ˆpÿ]íIΣej=,fh*wÀž/Š‰£ò–/)øV8+ŒÏ 9 (óQ³Ò)O2—Ÿ»Å@ùOãEÚGs*,©à5ƒYRaf§GêµiÀ^Ÿ‹à™'î]5jŸg†Ÿï5Ïl.¶>Ïl.¼{ž»åà²)—ƒ:¹µ*!…ùLfaÊ"—|ïAR1œ0XøŒ}›Î©Ðô­ÉèP8ùf‰A‘msÈwâžÎþáökíÀbÒÀ¡ÃŽ)èˆ2;Gó]ÌÈT7hKà9b8QD·a°íô  §W±)Xûïqèaõ7–.)@Ý—™o Öä1Ïu×·’†¡T¥Ñ"Òõ;kšVö2YµLtÞçá‘‘rq2WTò%%¥äìáë¿sü2HàG›h (Ä£ç€*Ú†²‰æöÌ¥ó|¸n0`pº,¶ä¼­’ƒ¡ñ£B)\;Hfûì¯P5SÍÑÝ"‰A5ª7ˆÚ“øe#EN¬KÈÒÐ,ÇR€/6¸ ZÆ®ëN”Ä­ŒNdf(HÑŒY22Z’^,ox~ÎvXõaN&ø$”Uÿ—aU-Þ=IUUé¾ËNI±^¹¶ ?’â9•Y2ï#›Å@#Yžý‡ôª>ÝòtGc ¸º%áè{ Ʊ}«8pHJ Ë{UÏø §!½˜Ã&h%F9ûÝÒ¦øÓäxØß[´.ÕÒÊ›u˜0éI÷‹?aQ:“UN«V±ìÿ‹I´Š¬.Š£‡÷YWÁg²¦$#6üç…S*V5@ s7Y„éÓHMcÊk–ŠÆ7²$ZèHfèƒLŠdkh[Ö>`ò5²–>­4±’MçôڜՓ:Ùïtohâ¬SS3AÛLIækš{5È°[1Îçý }ß¿gôÕhlj+™­XpÁÙ@º@eñ¤¬ód²^lÓק ëpbhF`ÁvŽ´F|k¶ã¦M:ÚB*Þi¢ ņu`ƪµŒ~®–Èd™é~Ó²ýÏ2ÜXÑ@­%Á/M­‡&¥C{÷ÿÙ“ïã/[XL€´uªË3Ãi¿«Ø¢(xÂãl˜Š È5*‚‹…šO‰éÿ3.I³ /žO˜%`§½ÂzPÕU ³Å ¯â’pýÔT¡ ¼Š‚å-Åx©jCQ~F'ªìñÔ–ÓiŽÓ¥ˆR¡€Øÿ®s4Y wáB<Ö€GðztÈê0·q~nÍT¯Êžrf~;p«ÓeÒ…ðn11QøÇåv6èí;-ù`V}mÕâUÍ,˜›rÚ_=¼¿_Ð-Œ}¨³Ç™*ã^nVžÂ‰o˜îÄé¨b¿÷˜E ,…³„W"®ª¬’»®¢)Ì“?É•†¾ÍêZ‹Í㢰\µb›y­ÇJ×äM8H F¯Â,Lù¨q·¼±ï€D‘bìÊ:L%)³‚‚&b©m œÊìf§ê_‚5…•Us{7Q¨reZµc¢þö"µ;™ÕnmºÁWým#)«å‰èæ3#}˜‰BUHé2:ëÅŠN>V·–?Â*Î*¨*›ŽƒN†Ó4Ú”Åv`I–W4 ·6ˆãÃÕ'ÞA§ÅþÞb«$Û,ëדÚ8Cw,ªã©¼y…Vÿ}Xæ‚™5ø©€XÆþJ‰9«SXƒÙG'f£O1 Žy Â÷š…ÊÚÏÝ"|)+dxÑÞSÂFÄö¤$®\)âí–ƳÕT-gÎÝRLÈdF,MÊaFU Mü±’¤º¥°ÿ!0_éŒÕJ)wÌ®R¥²Ï©fhôZ'VÝUÇì:³Éd!•ŒBTº+cŒ÷´àEŒ|²š]†”Û?€Azt¦¿ˆ™$± ð-Ù[oˆì z2KÑcQv=>f_9Jãi‘1ØR ~Ck—uÀJÕáRR=M˜êº7 hã|o LQÄZ¸‰¶©JWv¶]¨±1¦ÓDA"L±74›,´B'ñTÅ^‡±!Õ„€Ýc •Bq`[¥»¥èòÞÓmIaJ™ ŽË ·a.àT…7ÄÕœ½™ì7PvD5hù™nÄ0 ¨Û™*T$+Ï´ ž¸JÜ~Ï¥ =Lç¦dš§%` lÁÓì_È@ƦËkÁ–â@ðŸ_%à¾y7TEÉמ8tÞìÊG R*V; ñµ­*Ùðiò³ŸG²³ˆ’¥­…k6ò]®”Žu> ØRù1=k³£ µÒ/,×UU £<5Ò‚ G#-¡ÏK#-¨;|k¤«!tAqk¤\#5ˆ©ý/Í« ÎòÒHK09ek¤56ŽÔYPibk¤­o´˜.Êù=õK#-¬:~k¤%X¾2ûÞ‚-óóúÙ×H„NYPçh¤|ñ­‘òÃG#]à —Fz¦‘^-¶.9Ü)á‡FÊ–£‘ü˜Fêÿ›Fê 5ÒÂ*[#-¨C~k¤k}ãÑH±Ú×H pÔ@×H ª‘tõÖH¹`´X%n—/ô“¯‘µØ‰UPód‹{…\\(Áruøï¥Þ)é¡‘®–~i¤ ñÂ¥‘$ÝÎ÷÷òx·Fz—k¤¶b®‘:HtõÖH¹·FºÆßo”;w4RÎv»N¿QP4!»öϹÅèS×Í•ß=”(åíLÝaÎ5Áë3ýØ)¾T…ªv‹É;¯‚âJ±œ¥M1mÖK %p¨ôƒu-[ å b³çÍò¢e2öß»™léɳÖ59™ë\‰ÕÍ0‰'M¤ó|1#®¿ÞU×çÓüÍËYyÛ·¬rz§Å¥•Õ’·áGh”ŽÎ,O¤ù`CÂA³O‘ù{—.L?ëÚÙõ®½ÀtéÚ%õðеK²Üáþ»A]×. D{ëÚî—®]PwéÒµ ]»à.zëÚ j·®]P!íÒµžºö¹uí5voljý¡ksx×Ïi]{C®k{ƒáÛº1¯Ôž¥…×û‡¹&37›®]rˆo]û¬uí=:‰!kµÃ¥kÔ’»tí’¢¸îýÒµ8ߺvBÌõiÄ›£#«£ÑâT† î6I÷HØ>W è²ð£À›«©ÞÁ °îexñÙ%­!:t0ªm˜(œeê“KZË„y©ø$ž€½frø ²”E㶂\BF³w] ¥M ¥°^8ê¬7ö¥ÁÎAô–¼q: …/Kܯò©,"ÂîY‰w«|ñX!=°<=NV5DÛö¨³*§åç´tâ (»\ ×ðµ±þøÉ+ëæ±¾7ÈaÕ8-¬Q?•â:aR–ƒm€R#ÝÇ ‰­ù‰Ã\TÞ¢a½_„þ§ ’Ùµ–.Û KKL‚¿97ºQìuø•ö8-¾Àä-@­q þzáàd m ™¥ðvX;Yßµ”É­JEÕ³™YïEqÂÊ×f%¶O´Å"MBSµäݼ•V½¡pë ®}P+¢!¯Ö­ê' ÜcbçàÒýd„e”Ff¤÷¹ùa øpçcÖ†.e£†–•¸µXÂÒ¬K(T\`‰˜N%CnD°ý3)+Ù?o*HÓÎHåÚù‚ÎÀ3ƒe0ò„ìo9käX8×È×Ûýƒä$žraô¢À,V¥Â€âÉN§ìý»ü¯÷†úŽƒí^ˆP¤“V«N";¡MÄ¡=‘’) ° ‘bí&B÷9g"Y=$±L A$’eW˜ÑuÂéýCð°È»ò )ÇV|êúc…7ß…//¸ñC<€ÀÝÄÆ´@DÙ[:u‚Ì Ž1t"<ùÁq /AÂ@Öbà¥Îþ}Ζ䢿¯ÃB~„ü«/jÃÄ5ÂI·‡Y—‚’øîQ„Ç Ì£éðäX­Z[fòØC‰3eMÈÑ0ïÑþÙRÖ™¾Ð´4.’PNñ`*'Ì€¯ÄÁ ‡6fphfTþj˜Aà`À 3:fÀäÆ ûÐÁ o20ñý ؘQË|`F…õÀ1ƒÀÁ €ftÌ@ú© 3À͘lüfÔf À3È”6fT:ÏŸ}ïù…UÐé1ê3>˜a-ŽuÍÖw¾J=˜­f }ÂŽ/Ì°B  æJcžd¯é¤Ç<í™;4wI7;i|ŽçGTŽç“tùiD \´òˆEúx¼‰õÔ§ä‚upQ¦òŸâ¤ž,FÎûÉAˆiÕ—Äð©tuÌýaÍ XHBþ´,0@>)CBŒé^æ†Jײ5[|Ù ìëíªÞ>¾‰j@C%š§kŸÔHìYÇu#ñæuûê2°‰éæ¹ÌX¦)#*KU-ôª!p;ƒ´%ì1ù¢⚌À?*T˜Ëù=ófÎSz:Óê@ *-ˆù*³ø’D‰Œ€Ái0Ó6zKøxa,¸Œä‡ S?nþéÐ>\µÝy¶¦Z¿Ø's¶¼Î‚Ì4†…CpQäy@¾sÎoÐqÒcÖ6< }ºÀÇ¡òeä鸖-Ì8ž @›d4€¾—· ™a\Gì\+6%ƒëçˆ3ò8œÜ Ø0Ñ5j!Ä5Iû¥è.Á‹ª”0k­oÍ ‚G-ê 6?¹uö0ú ëxÃUÍ ;kÆÍjè.‡¯ÏÀ­b‹ék²pÙϸL¸ f· 8Ìò¯ ‹ëháþÄH—ý|2äïÇ…WIçwþ/cÎtjÇ—&eT#]ºÏ—& `ÁkècIpp¶žl§åH½{„yttÝ’ÈbKöã= Ö>Û¹¥€™ª`d;褠=Ç*ëƒÎJ‡ü@ϸ(Z¬Æt­’l4û@'xt¶"|Ϭû@÷í}7è “·/hé¸íÂí‰Iûˆ›¼>5æ%É<Ò¾Fr­‘¾ND•Ä›äâ\gÞaè &ÅI*™~’Ç–ùsZäM±Ò~'å ûg üÀ/Áñ×…Ñ} é}¸¿Ü+å Z›É·¿¡½Riñ™ÖóKùZ)g¥R~¬”@[©´Dœ’¹RÐóŒ³+åO/¦•óµRÕä~[ Ì'Þ+…{·z~o™oƒÏ&ÿ¿ [}-wž¼8ãÂ(^k…³âÆ*o°Õ;aC5 ¼Å¯væ%Š§>[Z«ÏBq)GMÈɸ€9Œ&5žY‡ù2øïÚ/:±3uâ­)h:’seq=yâñz&FÞ\WšzÒû¦ü‡êŸÄË|Ä0Äc>bâ1å\ÓÃ|”siçG`Û6åŒåÝæ#†a^棦Û|´àxÌG ½Ýæ#ƱóƼÍG `¼ÍG«!Þæ#|žUÉÊpv ÅÂÛõ;¢m·ùÈÀc>ò3ñéc>ZoOóã-ãõ»­®™rVŠ•Ë|´Ö!óWå2-¸óÑžÌæ㹌Ë|”™Šú˜¸ó[Žùhå6~˜NË6Yºv©€@üĨDNk­æ:!ÿëß~ý»J„0']ý Hçb›Ô)s¼ãYÉÖ‡²6|5LFZÊ°‘˜‹þ»å<»ØýZ/.ñ?6€÷—¯œ:^~’½‘òa¿wþsËÂÚ{:SØ·\OA7Í–ï¯P™/ÖÙ´ ÿü¡¶¬C¾ÈÓ.Ð=¾7”qáˆz;0÷À| ®¶ÖéËæâ…üa^”RUùŽý€ü»F3¡T÷ôQ]íøñ÷3—î…G½…n5ðÓEÑÁËPóaUå5*`$¾“²þMVdžúõÔ”¾ƒke¦ã xŸ^ Ó=ê?i)š½ág7 |Y Ÿ«?óh¡Sή§Pßö±%‡EG’þ×a£—Šu¢=9Ûú\ž×‚5úŸ¬×¯“ ŠðŸ–EÛ1(3#êæJlp—,륫_è‘ÉXú®ÄчøNe¯rtPƒŸP\°lþKÖ¥ Ÿ ʆ„ŠjAïÄAÄ€£^0)žÎÏ5YS-¯?A¦õÆc•Aû•©Õð¤}‡ÊVå-Äý̲Þx9r˜<”°×0vaªýŸhÄ{i+& ìtÛŒã178” ©ÐÚHÁÿÁ‡Ï}õ j€9Cõ^pÇÒ·3BG•oÃÂ’·*Èe=Q€ˆQþãøÇ«ÇÚR0ˆ.—’ ™øð„µL?É“ï:ûG!@NÎþ35ñp³4d@®©íµáwDZœö_´ÐÿlhйZ…¸G"}eÁàœ1ɇØá?x‚9}®’åqXL4XWóIö­H¤[;n“4$9…#ÝZ‡1áÊ´@§\œÖgZ€Ï:Ü«£ž· £-w¹0x Ö>­p•áÍ`<¬w&cÀ~ƒÁ½˜Iæ´H[ð (Ù‰ lÜÇ»V´-ë°|?e3?„Ü)cوЕ)Ûˆ IÌb«Ðéäé0žÃÞé1™p”YÏ‘IÓáîäny_é:ñ¼0ij\ú˜ÂFx)BaƒpUôŠÂ ðZ‚°JL–LÝb¤´cÑôˆí|ê´ÖD€Î©¢³Bü÷ï#Ñ`×É*8îØýv‡©´ÂÕ‰D‡¨Á¸GŠ¢v¿>E&Ù¿+ÿ ºb‹®ØaÇ”k§o˜H?qíxNxnè †¤ƒ¤Óžá°MÉxõ°‹,¡Ã ø¬k/Efn4«;²0úÊÍCß,ël ÁAÙ€ûüOE¶G?ÿ!i°Bu²ÿ÷ñOèÿýøÇ[z9Ç¿}æœþÖ ã>¯ϱO_¿*AaI¯©·ëPáCAp­„‘ø ãô/^áÑEI)NntB«"•„tuÃëx©í2®w°ÅÓþg™NýkCü1•ƒp„À­IBæ`8^sǘ¬E “U1ñ•‚6wì ¼˜1³RÏJ ´•‚:eJ`ã{tc2<§g.¬û´—*Câî×J ôd>–ª2Üñô¨bÁ<8 ØbÕùX,€1Søä;FÝ‹•á›¯•5ØâÀ’ð¢Þ QL¯!!g Ó­D®U>!jþèr”á’ËR¾ˆâbJ¶ §‡mؤ˜¡S’˜²/kÒ”£lÌLŠsW¢áëiRvÙ=àW+I‹„S¼¿_ÇT{œ¿¼C¬.´f:•õQ\Ö™{Ž=x'ÚQ´bS^æû÷B1Ê+²š䧩4VN‰"%s™xä*H‹#eÂGS–!ÔS"òbf—'Ç´Àh‘Ä»bÒ·“†Ä)‹¼pöú”Âl¥× eÄ;=– 2?AäpØ|Eñ„µ “̇ÏÃöhL‚…y1Ø]ú<¿Ûb‡iŸƒ+ËA¶´»–U¡,s+†O·¥ù0o›ÎÅÞa˜w•ƒ€@J+ŠÔ†`Y¼ÖØ$›DŠêÎ'h­ö£0H»1Í`CÞÊ…Uæ0•ãïi(Õ.zYÙcÉÐw‹²ïÁñB3+·,TÎv@@œyÃT&¦«\Qø<ŠBM‚¡R5•×‘È?ÂÄðu["†€3 ˆü£@µíßá.ˆ;BZ¸½ˆ»´êhCÖß^¹ä,jx ˜àŠ×®Ç ¡´ ‡u+†ºG¦îòž(4l€+ã6jðɱóò 6×JÇŽn3QÆþ›V&õoù9-ˆ-RÍ {èj`oˆiàaX¾Îê]W€Ó7 …#òù}ê]w²Âä9î[æÃЯE°ÜÌK.û™Ø{RÆfßòU†:X­úµ0Ë~ý KœXA®{ ®}2Ã}ª×¹‚¢ °4Çó»òÞлÒ#ÊËðî­9žõb>–m$"éI7oœÇH1S¥òëF3þÅäê¤~n\±ÿ§ðÁS3ôU>V,{ò†hAf…¬¥Y‘Ü+ÏR{øÛ n#² µ!dx ­F²"û7Žy·H|‡'ZØry‰öKÍ=säÿ`öÒÖ¬ŸìÐg2ˆ<þÌè–f«×õ”™ŸXZaHC¢î:ÄÏa¹Ñ• k3Yg ,0‰ý6ÏhÁ\e^½òÅYöù5/DZ±Ê3¶dΑK{Pß-?–¬7 ÿ1|(ÉÎ}B:M†|%7ß_ÄÿVÅö –ÔǬGÀð~ uìt9#œ•U}@rcjy^/|¬ÜAּР<&3Óûg+:Êé±h&-•'Èçàà@¶™© ¼]GMe:•%E…ª™ÿF‡‘Û¯V%°"ÉÅK^~²5îšSÙeœuwTìíG¦0\§åêO…È’ªõ™A7nÙ+"#AVíti,‘¯×P¥dм*³¨y¼†S²Ž«3äÄ¢ÝñšV®zÏ5u°ÜãŽ~Ýûô÷{2Âêý-æî{Œ'¯ÙìcÎ5Û›}^¼¼î÷ÜséÖÇ–‡×Ìó^ÁÓÅWù¼Æwâ|Êwë Çwô ÙwýLkcÆžºW¨ª¹gÚH´ùVÇüÇD6 CÚH…Dq×ðΪQ­ [MFŸ<»—ÚO )ÑžBî~ŽÖgH(t?áBÚâéR«!Ñ~ „ò'¢¡¶¼͇ƒ{"Ñr1$ÚÓJŽŒ{êÌ#΄EÉÖßûäñ~OÆk½¿•»¿ÇÇÃúó3“dæ{^¹dG"›ûÙ}[&éž÷ ^b«|^ã;q>å»u†ã;z†ì»~¦å˜q¦nwØÿB¢!Ñÿ;½±‡ª²ñ±T3ô_f¶õ)jA8}=U§çƒaIç`ˆ>‹ÅŠ{UÞb›i°™:ۚŖ·Qó^0µ¦:iO:|Ùý-~Uv¾£©Z|4ˆcí÷€S)†u—0±–=qÖ §óÅÙ}æ Ï÷”àñO•7z5g³ÝPÇF\À³*Ù‡c/p$‹7©—ê½z§‹¯ðy‹ïÂù’ïÔïæ±ïø™ÔÆŠ=ñÀœ/ìzútêg–æﯩ)ú9²»’–(C.yyX+aîûsÁ—÷©Ì–ø,Ø“˜Œ¹vzç£?­w)Ì ––âŒûÌ®4F’ênH“ÈÐøÞ:¯˜d¹ï™Uì:þ™S,3ÛË lán¡ùÑR¸OU ³þéIR”Ï`=Q¯Ä™r§tÊ:,[ÅlZ¼ CþŽ”¯¤J Lô²þa<Î`†x®³«°›à « rîpZú?¿Nw¡G0ã|¶SˆcÒIÍ­BœVÑ¿æ`1¯‰ÓÀ GÖÈkšâZ6¼Œ‹`Ã_ýaº£HŠzºÀ*JèñúÂ,]Ì­‰\—•ûìök^S¡/kG¨}"fÐŽ^¯†ÒéÑø4kŸèÿj¦ƒ׫I;[ûC&”¨w ¬¿YÚ)8aÊ,ðwoõ3ƒü™˜!l)+йgÃÜ¡("u<&}L&¾›Ì¬Ïÿá£R:ýž’2쬕œQî?̵Ô)ÕÝšÆô"Þ2ˆÀC“àÿ•~ØñlÃÖ|å€óIÌUŒEÊL&xõ^¯©Y©À«Ìs¦ v%*Ì RøÆ£žY –)4Þš8ÚÈÜšHÉ)Lˆ–ksª¦­7ÌE‡ë^eë¨{ô,T̃Ãa_!÷ã$A°WÛ~P;lÜ.–Î~ÝTDxÜéHB˜Té)¢7ÀNtÏpÀÉ' øÏo"(üh€ÅRò Zºs£Ma@ç¥d-Dp^¡Ÿ†¤Ð˜»a5T’`€Ùrþ1 ôù„v/¨v¬í$[I›ªà{¦l,NyÊT©| a8¡õ.ôfù „tåùx'œ"Ò¸ZãbnRÑ€¢RƒŽ;X6ùµŠ AZ¤1`89ó› "ûzõÈJ¨¥8(WãÕ ªrAå,H†î ǯjg>Ùeâ'¦2Ùµýÿvœ#8hÛä›G¦Á€¢§Ò«V >|cìÁ›Ó`©WËtÑ«µ–bâXáâ"o!üåp¼–¶é€Bô_)gX³ã¦HkÛ?—\v²Ð5yš'sÄaÝ?Š†ä2/øE ÍÁ‹BhQnÌYŒ¸†¿¿`q¦ß6 oôòAé0­!.D{Jý€q›•p²åK_<Úh„UÞóù ²$,Êüžn°€Ñû‰¡izÈ"¢Ø›Óû Fc1Aãzºª¬ÍÐåÏꎸƒ-Él.ÈÍ 'u¤ÁR Ý!A"MHdËÐ aÙƒ ·5ˆ@™º†ŸÑÌ(f|Å»G%b£¾˜X÷jµàÐJ§.KL„}€´5»!“_Ct;ê°L7•8ÿ´æFÆÍÓÓ%»(“2N]ºÒy]4± ÷} ðcê1EÁp[à1x½s¶|7 9Yjò4M,ƒùyêíL¤NgÍ8õµÐÌj¨‘#Ü-Ó# :¦™} zŸ´‚dR™ÜŸ¢&Åy‹k É‡ã‚óÚW ))ÃQ7nèxÉÀˆá·y¢÷F#dÂrÔ_‡èãð’qÛœÇÕ™¯c™ìÿ,héŒuÜFFK#I;QŽÉ:ÁÐP.´238¯Â–XYÉɳE.’iâëâ=,rNbîÔ0€ñ3¨€¸õÚáIì0`¹•yKã ¯—ôŒÊHø€#aXØ#–rMb<î Æ{-Ô{$ ybÉÌ‘ð ê 4—"’úZœu ,RàÿL6ÐÕñÃœùŠÄg°ö¥ÙQÔ|sŒ6¼C“‹¥cç^e“NIª£™‹˜J«ZòÖ²ÝK³Íb¡¿ ,FN .Р¡_FE°µz=;ýEe‘U"¡¨Áp ‹-èÒàõÄ•zõM/ö«ÿ}>‚ÖÑŠ2š<@%óŒAAnCÞ`d ¬ìAû†È!ã½.ÆQPσqÉCyž–t[Ë:¦‹\‡rô`AƒDØ8ÓÕMBð ¤ø…d,D¯µ^‹µ¡ªt¬¦¯*kÌM.|#ÂÃé ËÚÂJÆAõØÿÆ"h?¤r‚¾Ö)ŽéÂeÄV-„ ¢÷^qðºßpòyƒ ccÒKb'BžÖ¶"Ù!>D8ð4rÜ-EÉôägnÁì39rW9]Ì_µ‚X‹uÀ°*n ÉT¥º!¢GõXGìx*ʱ„)cíï=ºEâ2o=y`iT¶vKç…;jËHÆÐ!3ötN!Vì¨WÜgN"³oA!ü€ôDå¥ÈxdÈú—ÃÄZ£aáÒ¨ÿ³Bòm2rpÈ1ôƒ²Ðm È-ŒsµCÁДŠ<ÄaXÞ *µÈ ç— ¡UÄ:;ËÔï¡+Ê“'h:0“ÞRß;-ä?ür1Qf‘ ¾‰Ú9(ǶŠ«RX²}¤hTTƒ´|ùfhtjäù3´,Ð*³ Ì¢Ê>ø\QW©¾È{¾È{>É{|‘÷x’÷x’÷|÷|‘÷|÷x‘÷x“÷ø"ïñ"ïñ$ïñ$ïñ$ïù$ïù$ïù"ïñ"ïñEÞãEÞãEÞó‹¼ç“¼ç“¼çyÏyÏyÏ/òž/òž/òž_ä=_ä=_ä=ßä=_ä=_ä=¿É{¾É{>É{^ä=¿È{¾È{¾È{~‘÷|‘÷|’÷|“÷|’÷|‘÷ü"ïù"ïù"ïùEÞóIÞóEÞó‹¼ç“¼ç“¼ç?’wDv‘B¨ã­CÖ¹*…I¶è@YAF•F,%,²€<Âêzß0#ï´:§G0‡ÒìÐ7’}ƒ$F¸ÁµÆı̾ªg‚?º+¨G¼G¦+åbT˜G…tÎ#˜>¸Œ~…2¶`CF #ªƒt-àlX=Î褹@Õ“bñœµ£0vé°2 kŽ!ÂpU”õR(öѹqŽöqÕ—ÿ±G³;bÄÄ'ñ}ˆ¶õÏm·Dvøž ‡Kø«<ôó@^*‰ƒ°Œ@¼@€În@D¾}MÊfgǦ‚2ÊؽÞ[TåÆKÓ”†²{H‡fâ@L²(ôÓƒåÓsÈŽÑ1zÊô¯Ý·`cÍe ¡£îaè ›ÊaS †Gé¢ ”â€ão¼4W>)ÙÓoÁÌj•Á›¹”2Š•,ŽÌÝN2FXü›(8Ô 4ñB; DÔ˜çLÝ“ðC—Áˆ©^è kl;+ü±‰ó;Y ð‹m0²ò7~¤´á÷f'RÔ©ÉxBûh1z—n4Ó˜OÔ‡W†`ðäŸ Ý-QÖ’æ”|@«c Vv á²h"ÂÕbtXYñvÁÇ`•„p®Ù*K“&$2ŒA~ß®™Ãø»›‹¯g³nDäjâ$ð^Gê¡Qµ&’‚…1ßÜ2âÖ › ϵ(¿Àl¹/)n˜1œ3?=¢Í·– XNw“ £H FüÁ­yv²^tX&^Œ0B¶ñÒòå쌒zWûŸ:ˆÎ^f²Ué½}ÆD9î]§ˆ!Í«Gb0ª«Þ ?ŸÀ>Ôºé—YÕ‰!ŠDeI‚¸Ód :Û/8I,0$g ˜[ö`¨Ý<„£Ö¾ZÄâÜ –±¤qyÈ<£ŸÄ­ëET¯¹óòÛäm[р챚æ #xtÓÅ÷Õ&‹*B–£B-Tš0+:4KŠ³(ÞZÍ¢F±oÁ‘åí 7ŨD%ù§ÐÀ®äQ _§Ü‹N%IÄ–#Ä@Tä²XWÈ·x+ K]BŒ‚|ø[¢”Ù˜!פ|&N%—@Á°Ab56ÕÙÍ€kF°‡ÈJçFõJ4bÜåH¿ÖQ€ÝZ9Ha…#¦]ÄAç†ù±|·0F»Á&Úü±(Y †›ˆÜF[L é¨~'øÅDû ©†x<'’ cHyÚ&3ð3Êšâ™,|ˆà’¨Õ†m ¹öªlT¬»°ÀÂb׃¥S6¹4%”Ühj*Â_.…(´T›Æ¨R2à£É¬JÄ®`t‚j€£2fev6AFІ¾Š—37P7)^ïC€ÂV‰äµÝÁ²ZŠˆŠ™›Y¹1*ÂG!F2³ˆR6Ühal<íQÓ3ƒ;+Š“å>—ƒ² žÑ—–8eè ¹[p¬ˆ¥â€4PF«c‡)Z†`5xƱ¦XòµÌG®çjâlzQd´Ã|TɃüD’5úo#!Ó &—¹þ6ll·1vóG‹ãvumÁÃö²ÏÌk9<Qúü9ÚB(Œ—§©º˜’–TD¹PåçIQI~ læÖä0ôç×ÿþ®——¦®]Ü «tëbþAÃ=rH8ÍwUԛѿâMLkZ˜P©ÈmW%\‚Ö îrØb 'sÖl!Õs)‘G¯~ÓŸ±}úR˜Öm„;¶Ì á%ÜÝá}¨D¡–œ§õ©'ïÍq¿É ¥È,ž„ôB¥ÓÀàÏ*×VA‘&ܲòÊ«Š0AâÐÈýþüˆËE%¦BW¯ÄZO¡ªú¯% ³=íš=2âç¶ì VņH[õ8NþÊ{N•J3@ã@IíÄ[d |ÓÐü¢=ªø’¼(‘^‡î^‡y·ç*ofoù9-pxV9Sên¡úH:*9$Åüjƒ4`²5«…*°3CC®Ê…šZxùC©v%B¬bößzP¥'*½™Öt¬ªº©Ì ;bÅ-z"d Ö¥Ðb™ÞgVꉙ®6ª¨Å3Â2;½®˜ ª©Z ÁŸ ÌÅ=ê5Ó…#SY0Þ™U`TŒ$¬'J0 ù…ž4ÿXðš™…D,VmbmB"ÑnÖ v(÷oPýéÆÇ â Ë/¬ò^߀֥©–t•ã&¨Êm¹)wMC¬Â‡YÏ›zïÕƒÎ^œ8l! ZšB‰¤bÛ°×E¹¹Œ¤âÝ% •Áå[çáî°Å&­z9±NbÃH›ÄýÝ-JÿºÞ° ÐGß0H0§l> +[¬ç»öÒ#å+Ù ¹<}mêTAQJr,û‡«Mnù~WK"ëW"à:¶¬òÌ‚‘ÕJê­–l‡€÷HrÎjÝ–”íE 9 ý8Í,±´ÙœX);2›©Á,c>uÈ[6­ \¶RãÇæxè-Á ÏÃþLÇŠ,ÚÐTc-˜’qß6ïJI·ß°a”H·*ÙÞÂ"iž“- ƒXÅ:z ‘¨^[C~°Ž}>pÐ)é4 ^dÖè §!,Sâ>9l5¾c¹zÀ'€=‚J’;¬ã o /BçG÷¢Å¨"½xàÒB—U¥‰mE%ªÎÎ µÄH$‡ƒ´ ­ZÊe•y|YÆÎvEÌ w•ñÀ\àl‡‰õÀå$ÀAùƒKÂõŒ+X–­+’ÃqYN)A ÆÓö'Ú³ñ]Y_‘ÿ™$¹–€*]Ž,ê8•bVéòaÑFAÛš­jªŠ³æ. Àa›V+WRf“ÑH@7ÏÀ‘U>©\$Ž¡ýÔFÑB”ŵlÆÀÂÙ›/8´Ùô5²^c #QeNl¶@p³AÆðš^[°ï®à â#¿ÿßì—UÓÅ ŠÈã|F8?Ç#©¢ËÝÄAQ"èÑÍ5«IûbÕËMŒªË¦½QÌÑ,MÙ¼ ïrFÿÊb_»ƒsÚDë×|Œ?ÁT_eë"ø<%³k™v‹­b¾À³Zƒé“É;Y½\‹E`/Ö(ÅåZ,+®€ÅB¹n¸aΤÅjZ¬iÒ–­–ô½½¼®›÷jÁ')•«™b’ÍS€Õ=ñZ.A•¹uùŽQÏrÁwí!jxƒV÷Aù ’°Š[â¯ZoÊæ +‚_'BàÞtØ6ÐÄ$^ŠæÄ`°ýfS{!¬‡ï˜3=™FR±\Üâhepª2ûÎßåzÒ§û0Ì‹§|ZZÙœ ¯Ë•¦0Q¾üf°_`EoUü™Ç{´“¥šT†ñú¡ƒ’EÓóéÁªé<½}YÕ=YÐ%]‡TÞ|*¡ÏAó¥xּ‚ƒ5?™… jÛ1Ê¥,£E€É‚ª1¿°«VÉ÷¹kèaªL±o—à{»ºÕYõ•aÃúÆ™\]µÞ½yØ>|¾æÃ;pTæÅ]Ö˜òï~ZβW^n0‚snÓÝ5ײP,A`þ7‰‚sʸK¢¬1ø='€5O‚\—Õ$%rÆ0Í´É2W¨èwÍš¼QÅbü´ LjM~KWË.g"ù³m=åïÕ¢2(. ÆÒ-iZyß`º™xidUN¡1gÓídá¡Ä ŠÝ#¥Á2œ%R¿RzV¢våÚ%ÀœÆ½©gÒ'³®½D€Ýƒz…ê„PìòÕ@˜}<œ¤jí»Ô< $æ²yÝ>Ñò±nZ#˜ðÅçY¹ZÒkn7½j6%‡¡-qkX™_Ì XT^­äõÜò8½ª“ážê}g«g[‘ ²]= ÆÚlÑ0$¬V$p+pAqEnŸ¿P‰_ (½Pz1 ôÍ€pR:â©y1 Ÿ èÌi3 ôb@éÅ€ÒJ/”^ (}1 ô (Ë'֟¸©=öçJT"¿»¥©2A|IµÉŒSº•Ϧy7;—O åTóóðž( ŵ]¡Å9“z»Ï?ªœ^ãÕcªt 6¬±¾w•F«ªR4ñ>öZóÞDmªFx5}“ïsS’5oU=âÇm7 ¸ÎŠ¡Ç=×½èµEåÔÝ°¼öYï¦Ä–R”4Ó%ý‚,y4 /W¯u“ëZ˜{õjɺ£i“Kä6Å¥*ëVV$0{7–5®A`á¼…*CÉŠ‚øÕ-ГLÝ⇊Rš~w`q|a·ÀófY¶¦Ágò¹®ð’õAé Ö8^äÍm æ³R°Â×iŸ>-¶ÆÊÇåûAÎcv媫$ЙïnÑ‚ì}%øp1nÎ ™MÙAä‰fÉ Ãܱ¢ÿë×ÿËí4uendstream endobj 6 0 obj 44717 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:58-07:00 2013-08-20T08:41:58-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000045021 00000 n 0000046591 00000 n 0000044962 00000 n 0000044823 00000 n 0000000015 00000 n 0000044802 00000 n 0000045085 00000 n 0000045126 00000 n 0000045155 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<7C43FFDD45F1805E3C013FF92C304C2D><7C43FFDD45F1805E3C013FF92C304C2D>] >> startxref 46761 %%EOF ast-8.3.0/sun210_figures/series.pdf0000664000175000017500000002364513004147321014002 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\KŽe9n¿UÄ؃ðÕ_ZÏÚ=èЕmD(xàí›çð#ée.¡P(ä; }IŠ¢H]ýùñ|¦ÿÙ¿_?_ÿþ_ããÿ}=Ÿ­×ÚÊǯÚVùí#µÙ>Kûø¹)#IÍöQëÊŸKð,ÿÖÒ'莿^£¡Î |¿z*ÒXJKù³µm¶^¿^NÉ¥±æwP’TÁ¿ÞæÂà¼K‚¯—‰ðûåC&ŒùX;Ž½§¯×?ÿí•ÈŠ<9Ñ^ üÜ”Ñ9ÌZó¿iöª¬xª´øëÕ§t\WPdÍ™cu++¬MÇÖ«LÆ(y ›NT©lÊ›èü™Þ©cðCæ°D‡î”=5mÓ±uJ¦ÌÿÆü§üÿ߯çã?þbÐÅ ¯¿¿þ|Õnšþd¨«ðdLÓ[£|”B-ý>j9åÇëÿ#ôG¹ó®im4/ikëﯿ‰4þxµ'{ÙŒ6~”F ¯³äÜîu8'ëc#³ÙGj-Ö>¤FP¸œ>¼…µ”î}8–6 §ìQj ïó êb͘ä„-†bŒð22ø©”)Ö+=ŠHK‡­“_¨I4‰¶.(9±ïœ—¶[È9—½Ò3©¥NùJÊ'e5“˜µØzýz9¥tÒwPòryh›¹8o´WÇ_/™S¾_>v§øܼMÇÞkؽœçä"M«« %÷Á&²Š&•¬ÃHý91Ø’il‚)MºQÖ“Œ-Úf`ëUØb”š«MÉ)ÅØãmÚôNcIú¸Â0ÈÀŸcÑú¼¼=ÇÞ#Yò;6;`ãNg!M5ç© Ûœ’Í9HÙ°.†ú´¤ ÌP^iKJF5k?ëä1ûÙf`ëUÚ0J)Ãœ§ä®ÖÚÛÌaëÕ±˜%™SÄ(ÛØâsó6{¯ÛqH6¥¤nÇÏMɽӇz:§âÒ/kŽS?dJØýÚ©1y,ekÙ(Ù´m¶^Á¥Ôçq›`”’UàÖdî¦8֩㯗Ì)ºS|jÖ¤Cï“Lù‹!'CnG¡?j~·£à”í(ô4]'½VPnG¡§Ç÷Gsœò«£Ð±IÛQèåòz»ÜƒÛKð¿› àµZóÛGh¶óxý6nÁñöœâôÞ§pù­¿û›^¦7Ÿù»ˆ´ô'L¼nëÏ47.÷lÎÄ47nS–9m»ÖºÜ8¡«&>Ëܸ •Žì#ê~<Ë\¸ ˆ±ÓÍüiŠK2“m‡™bÂÉ2,n>Q¢VÅÖ‚cë5œ2è€E Ù·û0,5|^"Æm-¼ÍC÷Ñ6l[ªfr[Î@7ý^&•é‹¼<6ÜíÃmùÔé«GÍ¥ê”ïMY¾V¢ÖºW˧._="nÃN¹åƒã¤®§´[<í–N{N»eÓnÑxó[4u˜Ïfõ«)¶wàx‹&Jø½…·)¸hº:ï¾rD4õäÈw”ie†íÔÐ.s‰fØÞKÇ){éÌçqaY­M¹E3–.ܽtœr‹fpÜéÍL]·|ãÌ,æïoéìÊýhÁ°÷±å3†ùØÖÂhÕ°öáxË'Jø¸½…·y\KgЉIÇÒÙLð2³¦ðtéì2”lHfzrW##b·åª”gìSlãI©ëú,U e­7EåSSëjKsWÑ)M—š­y1"ªÁI— c¸hn/¬ÄãÅZ¬} †S’®#ka­n.œöáXjØ(v ¥µð6õoŠ® ó dnE—ÏæÙÛG¢Ì%žnÎýS¶xºpÚœ¯”[<ýY6²ználï!(ŶhcKo¶…ãoáD c}´à8¹ä”6—l¬…6ì c}8ÞÂÙ%t”ÑÂÛ<.á´žná ¼Do?RÑD Æ òÇ¿^©<ùc2„eH8Ä”ŠÏ†£?¡ÌªwñB×úœóƒ~Îuâg¬*°~Š?„3aP«–þY~EZyŽÖJNìhVû-6¸gÈpÂÚ—¥õŠÒZÒÆú€ËƒZ'SŽJ£LÖ5Êzt6ÒJv”ÅÅ2$™–X9RijMÝÿž¤“]ÚÑD²áæÉž9óæGÇ4W2`ãWÌf|ÖNF"ž“yžŸµ ð¤éþàhP´ªì1õWTuèéS«Ž‚!,í¤.6Žgax¬„ XŽEײ ìÏ~5ãpü·},#Ñ’ñ‰ïý”¶EAU¬Â¸E,ª³±tWŸ‰ QàR[w&¢UkjÑñ13CNü‰]k¢T§TŠÈ)± a´H¢ŽŸÏG¤,+•Qà"PÊ ·e%h‹c¨Å€³p”‡]vqÿ3ÆUÄ™ÖÎ:¸,PAJ®} 3DŸ™¸•˜$ZdSDC"*Ì‘ cè†QXzÆH¢„õVŽú†¤q“^P”7€¢Sl÷3 7ðŠjoåQ|Èð9Qed±¾dF–Ž–Ô ä‘H .ãtiFiÙæQcª˜ì2€=@¡,ÔÖtýÊ tHW¢)6 š1&R8ÄVÉ)Ì@®S=) ®ÒÁ¡Ð ÏL2ŠØ4‘ÿ¥ì¦ƒÆ$ÇÔúÌT}Äe`\E†¥òï6ýŽ‚Q¿ÊàËÕC•é=TÙ}3ײ-$[iÂh­ñC_ÇM3 °½Qå\ŸÅrÐäRÇG ¦›*Ê–dª!M÷¼W"æ<¯¥ŠS;3tc–>ZÊ/,Ó]âÊ…ùÈŽ†\¬ hQJj¬¡ba3M³˜ŒAÁǃņ‘3ŽX!Ph"k†m< dœ•ÅqU€K,ZMÉÈÙDU¼2ý1|"”EüPŒ* îÊ®š¥=œ©­ÖÕð¾!µ[bB‘š®öÈo1ö‚*BPc4:¥ÇŠ±[&Ä>u­KíÔ%1™2ƒ(ОF3JE˜©ùR DX‘ö{Ûf¯bß©§aÄl¤â.Ñ|™W›¬G1”¬6…:ÏÖÈàE£üdå/öO,M²×_m›ÿa퉰 ¹Ÿ;×|mbh`lÁ'4H9F#]FT9 û¶yèÖ‚õ°à)·§;*Îîf~—€ä°ªâw‡¶»J#­{«tK·J·t©tKï*Ýò­Ò-*M* t¨4¡«tË·J·t¨´­ÖN•D•nõRéV•&•&Ú*ÝêVéÖ.•níM¥ÛxSéuªôºUz*Ýæ­Ò­¿«4fsªt«§JċJn•FlàVé–·Jƒ¿‡J‡à•ÖæC¥ªJ·z«4xr«4OGy¨4ÁViÀPiÔ;UÙâ[¥Ù÷¡Ò”œ©´þ¾TšGžà‚Ì£‹WoNË÷&$¶GB§K†Ãû0ÊüÜË"áHÓ´À€WÇÈg,ƒÄÑ›É.1ésÑÉVÜEt}ù6(šHÿíðt¡nµ ¤èäeTv…"îJÔ_–E\›®¾6¶ZÁåè À‚–‹ú¡zÀ…@/ãPQÉG8&‘üÃÆ^©ŽRÖé ”% “£¢ˆÅæÀæAcÐE;jµ¿àØ#U¸JŽæÍuC%¬Ža.dßÈhaW?¤Ë‚‚ƒ&Ò‡Aè²sÃ5F$zÔÓ=ïâŒy”èÍýNý-r¤¶ÁÅq%4ƒÂVx¬q1¶ªÇ•-F§¨àd³ûl!Šwƒ­Mµ]° ¤ÀcãÇZ3ÿžU'¼šPdMÆp1Ÿrž|z`©?ž¡,´Ö^97û; Š¦Ìup—mBÍpS}2ýš&>WÙf¼QMÆ‹Jì€Ö *UVÑ3U¿qeçi\QhˆŠŠ½Cw_«Ñ“x}I&pŽQiYÏsfꋦzÈ›EÃŽpQ·&|h‡¹úþç”TÔ!²àp\æóô:ÄëF—¢zZBà`³^;‚b­¦ŠÕeiìƒ;èê÷u?ÚM v—=n§êÓº¯SÚž!Òé4®0,ÿ0ê ç>®†˜ÔPBÑ l¯ÃÜ0Ž';ýM)<ÿ258ŸG¶ÀD&ážT!o¾ x=hI'¬é„Å@ìzÚo¼§–T‹!LLp?Zá¬)Öùd¯dËô…«'d&8UúâÏB'‚+1¤Ø4¸=RHJAîaª1[‘™ µi°jÛƒU Ø®‡¾XjV?yzäo–RN!0¢T1SŠˆ–ÐiÀ™ «Ln_º(€—ŽbIÈNJ >-daC!,ÉØŽHv]²ë’£7EdÈêñ½ümê riªc(sâZs5ά†ÙUÙ–Óä–£0våÖ!c¤(fe øXUsâ¶?´EGZÃßØåt‘7mXGÔ™TM¿§cSœ8ùÛ–ösdÿ$Ÿ1c5(f´Û1ºä~”0“)Ö ¡=œ¶ýzœ%Ðœ¨§Ï³cI£s®DϤoª­Àfꬩü¤VQÏô6t9¾ÔÊÔ´gšÕüÈŠ{fìL2嵸œ@aDg-]„n!¼ËIUtYÂ왋> ¨ò*Û1½°«Ò™/àÀ´NO¬¤ºûœØ4ÎPªXwÉ”vl:Pµ}w‰¾ Ç‚ò§§è¸ADˆ”ÿN(6ÛGC “FT`¡ÿ¨›:Š'Ú=Y쪩3gH”q£€_ò‹¸ÏêpéÂ;ÙøqoË)˜/¶X´pìî« 3$ì `d xˆüg¢à^•(H^Í£ìŒe DBad .‰áÀ83äÙ•†ö#!°œˆÀ‘Še ¤ÉtÄ¿œI;&ó»òÔ˜ >!¬3QpOcõeù—»‡ÑïdˆXiG‚ŒÛ…¶ g‚ò¸22‡uf (Ã#Á9Ï{©Bfçb¶sªe [bcÏ@8ÅÜXi°ï „êÁi;\+”uF_ ï—Ÿ0ßáZ¡Ì«B§eáZ®%ÚáZ…®-¸´|„k)×ÐjåÙáÚh· .LD¸V`‹p­×*ŠpmõÝR~Ÿ 3é!_áÚ‚Ý®-e<õ"ØáZ…®•Šã ×–RŸ;\ËÙáZé:ïp-Ǽõ #R °ÜáZi¬z¸–üÝáÚ-ø®µæ=\káÚ‚;¹G¸–<¹Âµ2—~„keª-µ "\KèÖ‚õŽp­´\îp­ö=œ†kí÷®Ž¿«t·J—y©t™ï*]æ›J¯S¥×¥ÒëVéu¨4³’‡Jã^J¨´V«ùTé@Ti\8Tº>‡J„Jm•®i«4n**]ó›J×z«tí‡J*Mè*]ë­Òµ¼«4fsª4.Il•®Ï¥Ò„[¥ëó‹J¯­Òàï¡Ò!øC¥µùPi…ªÒÈAŸ* žÜ*]Ë¥Òµ*M°U0Tº–[¥y½ëRéšn•¦äL¥õ÷¥Òk÷È@ˆÖ•‚g J•íÊ@¥ˆâÙOË/w¢ 7xd —È@ð áÎ@(´¤Û929Æ+±)1rs‘ØÈ÷Âuf Ï£³µS!hyÍ+Q,{¬ˆ‚‹é–ßOd xÊ@¡e 09Ï@°¹È@HoÕ3ed Íšë†J–8Gç²oiÞˆÒÌAÓ „Àtf Ò§W¢àúÛ‘(­<îwêoÏ@í „B3(låÈ@ÈÀÖØœlv¿€b«ud ·È@(ˆ áÎ@H[åÈ@°é#Qš“¯ DÁgGBðð „þŽ ad iB~×#¤Ri½2›ÂA"©VÞÁžýªgBpŽ…‚È@î „BË@”&:µV©Ï+QðñÄ‘fõ3!¬­w"(Û·Zî „èE=2[¿¦‰ÏUöÊ@”Ž‚e ÐzõÑwBPñ „ü~v¢ôÞ¯ „ò(È¿ˆ‚lÈ‘(]Zº2¥—tf Œ;02A± Dé²àŽ „4Ø® DAyg >GBª;!”tf ó¤žä'¸ú ö‘<¯ „”oGB`Š „‚È@(Ô Déæ†q 5ï D±”¨þ¥Ï#Q½º2¥C³wBðò „þö „"Í@ÈïçÌ@H7ãÊ@Ȉʕ(ÈSˆ‚Dod 6ò DP4A!iÿ¹3B©wB(Ã2òsyBØ“,Qp%¹µ×3QÕ;3\;!pEBAd –dìŽ „Àvf ¨ˆWB(óÌ@Èó‘A¥;Ž?ãüjžP2Æqœ‰2&2ߘ-ûvÍ@èoÏ@ZÖ%.Äiâ}:6Åre ‚`Îxg .8\²àÈ@”n&S3×(HÀZ¢0¡ï±$Ï@(² „¶¢èGd \Ïô6tÍ@œS;2eTÝïääñs# “‚mi‡IüpYb­ô÷Ž’zÌ÷Û ì|ä9R¬#EvÁû8â¤Aae†ŽÂƒbò 2«ÆG¸N†) 6i€Ðâpàgp®`§¶;´T†/¿† »'€1z*SƒGHûgÑuÁ dÚgÄʪºÆM=ïÓÂq³êŽ‚5¥¿W”„›‡í˜’oEAT¦ªX¨˜Ãî/uI‘ÚƒR)ÃÊ”3H #Ê°í€1áæ¬;ÎÄ-„Tu 'NšÉÔQË£bè‹lyúECȯì`8áí| þaИìFºjø/Š,~¢@̹fR|Žbù-VM‹¤[3!G040݉A{üf¸¿ÑÝJÌš‚öÈi1+Â|˜*)и g]xðãŠÅÎÜZŒ„Ìž=s—ÜÀí.¾ðpÿH}Ø"|#rÄ)†qMÜâêGƧü׆p¡zgæŒ ãýÅ´Ý.1y‘›W€ Ö• –Î #•>™ ÈIïyúrjLz;F…ŠÜî.Pè²i1'ôRRÕÄIA¾[•Ì%?¸ÿ‡ä ð,FÁu^lˆÿ¦¦î“Œd~΀9ãè»ÀêZAïG 7 Ñ[}YÆwø„ Þ|+·²Ã—=hað#€¦×12²_­F—8ô£Dåm0Á²¨˜¡9H8懲÷+›âƒÛev2XiØÔà-¬¦|'eôÀœ¡¶x,2 §à…Yò’–¾Ý°øéH‚?:¨L“ƒ‡3À®‰Q;CaqS–×ÔèNBi“^ã„šðA£ˆ{eņÔòU‘¡Ãˆü3ƒï‚„ )Y®¢¦zœ³]âÔ«F ‚®p°ªcý´u“ܬ„¢‰¼N*œ)úѬv”‡\}ÓáWÞ,zŠ1WÿλUi²*?  °äTNÙWÉ„PJ”Ý+:;(zÉ'§“5ø˜´ý*§De²2Ng¬ «-Q€g²Øì*ʨڵ&¿×ò™غ3+)ëUFŸ9‚εî¿g²qak3€û®U‹vzgG uêÛÚè¹¾žžÇÔë\o$þ Q½^ÏÖí«µ8ÆÚRíqïÄdt¯P> ”|;mɈ6“¥(+–. B~Þk+ÌþŽ3^…õdnÄÔB;Êz#áе ľ¢AQ‡Ä À›Ïx*awÔ¶¤É¢æ ›|¿ ˆN¯‚ æuJªÂâg¬éH+2­þÈ· /¥èX0eú÷ËAvÁ)TWŸUyi<é7ö¼>Ëk㘠>u$5ñuLÎñçZ0œ§ºƒÕl÷%ÄSb!2>õé¡ ¹ÊÙê©z¸¼Ô…4û__Í¡ÑT†¨]Í:òŠ§üâÏvë\™CF!»¢ü ìtNX+›©DQ Ÿ$? ¹ÿ]ÖëppÍe›©ºß&ê3!ÜZEf,èp°eÞ…ÉøFbmË"}o ­S[[;.XM¡ñîa>œf©á6*À™U›äWÖUk½Ò«õÚgÖ+ã:Pë¨ë¥Ù¯Ýuç…’Œp%k0óv‚~_ÂyWu»½@µ/ßa§ÍÅ—X46ÇGÁ6¶@Ç QvÎjØŽ£°ñÅvjQvÈ‚^R?Ù»)IiËø’CÈcXmxVU?°ÑÇûè(Ð.µ¾)/4ê2KLñ%œƒ[ñôL4ªˆ·)˜)¯d„WŠy˜°}ö€Ò_Wó~TC±Ú àæ6 >t 0ým^ ¢@ɶی6 ÓÛ£CUxCU3 4=¨‘€¿ZÎý‹±ÈºÿÇM÷—Lh^f枀òzt±³2_' PlïWÈãßWaKâ²,m˜Ã&DYkµªÇÂòN1¾ä¥Þ™Hñ1ÜÌ»Óã(Y­+¼®Îì–×ÝËíÞ¶n°eŽ¡v• LfË–1P4|î?·¦f²©Ú PøP…ø$ÊÐÓ 7>^ÃwXí´ÑmF?©òèem|̤#ÓëÃ<¬Ôv?Ë¥éYbÚÛ”s(ö©^†}ó¥Çi™µ™ö¤"ͪÊom]­c‚!«uÔ×#æѾùËþ÷1Ì[MªI¾¸Úü´=†kíÿéPšm(+_âðF9°wÜÏdwæßs 0Éõ¼_Ñ×öÚ,ÉHcÏ>b<ôrÍA`füû L†h3È‚D¶²á/¦À¾Â¢¼»U}ÞnUŸ—[Õç»[Õ×íVõu¸U ­"Ün•Bs«úºÝ*Èc»Uô¥™|¹UêNév«ðN¸U ­RnÕH‡[5òéV|»U£]nÕè‡[¥ ܪÑ· ¹„íÂU‰Ë­Âd· ßðnÇ»Ý*…áVôæVçp«ÀáÓ­ÚÂßn•µïn•Au«F¾Ü*0är«DÙnÕhÛ­âïíV)4·Š©—íVá¡Ë­b¯Û­R™[eàt«þ|1‹Œ=*žÄõ'G÷“¸›OâF­ûIÜôñ¯Wåó.û\ä¸÷,.ÊꃱùxwSôQ[Ö~w÷ìÏââ¼ìŒ•Ÿ[ û“µ›¢Úz ñ,®õ±ŸÅõQ8eR[xŸÇ—^·”÷gq½Ì~_­¿?‹»Å´$t¡ì ƒ²$ôZö“B.¢ûABŸÖ~Œ0(å’Ž?6èýµ7ÙÁoµÆCNñ§½~[ý}ÔrŠIfÓmAÔ©¼»OmÝ3䛉|ÝÛ)Í^æ®öÖÈŠ³= 8ìÁÍÚ{øÐJT{Ö[¬}àmI§$•·µ°–?t×ôÁ®âoëâï>D¯~OB_„šdü±jê´§Bƒ^æX5ë÷Ë&ÞŠŠ÷ºf»(ß›²—×z_6÷ËSlìч½ÎUS›¾|<Øån Ûàñ@Wmzkûx°«=õzÒ«ÎûÉ/ÇûÁ.£Äs[ÖB<Çe}vÙ(v ånážÇ%ž½t\<› ^æX:ë7kço¯ÿZÞÀ©endstream endobj 6 0 obj 7761 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000008056 00000 n 0000009626 00000 n 0000007997 00000 n 0000007866 00000 n 0000000015 00000 n 0000007846 00000 n 0000008120 00000 n 0000008161 00000 n 0000008190 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<22219C6C87A4667B9ACF7BB5F925C80F><22219C6C87A4667B9ACF7BB5F925C80F>] >> startxref 9796 %%EOF ast-8.3.0/sun210_figures/fsremap.pdf0000664000175000017500000006061213004147321014140 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí½ÏëÿÏvDÒô­%]•®’÷BŠHû¾óû´¡6µšªÐ0BP>¶MÌûÛKSk„bêÊ… ëÂ….ìJш$bÛ$†þ B¹‹4ÐM—[cèWsÇãqÎÌ<ߟ«P»èæÞ˽Ÿ÷™×<çÇ™sÎœ9s朿øÞâkÀíßO_¼|å_ë¯þ/½„·ÚJ©ùõÏ¿”’Û[­¯©Îôë매Ïò6ëkI=àß4[@y m ¦ÃŸ^J^ÊÜ%ï/)­*eì’–Öÿ‡±ÛÜ°õúéÅKr×—ï»$öú–kzõ6ç[_ƒ°. ¬ؘ¾¿øUÕæãí8ì=}zùsÿÜK*rø µÒWM ÂKF h¾¤À_rˆE¨ü×áO/yuÒOÁûKì‰õ’Iõ±›Ü°uúéÅKJ‰šÍ®’›ò&{q”±O ËK€ ÜKöĬI‡­O¢d¼þôBËŸ^ÿûw^Âë¿ømô\èùñ—º™(ÆEÆ`‘ªP³Kzdï1CUh¤ÌÄ ¯QÍ,2·’÷—<Ÿ¤ VŠ»É [§Ÿ^vIiœÎû)É•mx“©±‰Ý§ÁŸ^ö¸¬d­ÜJöÌ¬É [§›bL’­±Â§¤wr} yâ“4šØ5uMX K“`±’…“Ô4!+IÙ`krÃÖéBŠ—Ô4L8yI‰ì>'09KÀy¯/¬ØÀ¬`!ÅGn%{fÖ䆭S!åÛ¹BZdÞRˆi‘ÜO¼”¶ê&ì!-ìäZßRœßØf¸*Ç@°½¥Ååæ·8ìï‘Þz¢ÌYPkJl…Ðbô`ûª³àôÖÊëî¡.vßî’Ö´¯¼5~ðì`˜â|>"6Ju•²ý­Ap»ZÌiµÍfšM,뻜mÉRyËè_Ÿ->_£âçK q}¬äý*YX %þÑ)Xøh()m)e­ñ´Ö-ÔWÿöñ­Ñv~I¨]’0¬åÃgP âx+Qƒ4û[LÓ~*ãmþÙ²ð¸(4ºª×ù¶Ö{•ôµK¯ñ´Urøê \¢£ou¢º“†•¼/úY,Uuʼn~VÙÚFxEÐûeñJ«ÏFjÂ(ÊÄL°Ñ$û»¤·Ð)Œ±ª‹‚Ø5®¶&¶š˜YSV ÖE]”4@0»€RóZÀ?U}•¤Õ¡\˯5£˜jöÖÑ.!ÐCgC„reÕµšTÉoëߺˆˆÌjðú–ô4¯UÃÀtK_pãÏkù–².jâ®ÔRÞJÁ®5­e¾µ¶ÁU½vãD«°$MÞW»kí7XÖx±–» r®‹6l© ZoF)‚1üE¯! ¬±6 µr‡ÖtR§hY¤±h@ÅuéykÖ_¬’é° ÚÛ€Aµ« µ×¶2Û/]µÅ /%uÑq¸Õà¯ö÷Ú_ÃdMÃ_Kì(ŠÐÖZbÙÚžNzmqч/xMx˜òl% µA¦«½x5Eª;%K"åµÂÛL‰(^¬<Ë׋'©Æj̵¨)ž6¼h6qT§¤C¢Ô9Ö<Œl=ÔÙ´¢¹¥çÛ¢,Q;_Ñ_•és«; Ö—N…Þˆ¤µ@RÀ x!8IñÔH‹VEäëËqÁ.N^²¦LípŒK¡Â˜ÖV4ð{\h_(Xì_#¥l{+DZÏKfQã ¤D t¨n/éV‰,‘ѢDž¨E TÖ¸9Õ%µé^ Éd ZL¢÷ºª…pŒÛv©.únØŸûT€sIÛyZÀŠ<»Xò8Ÿqž¶µ·ò Õ Å¸…8hõ*ñ3X'vÓ–´^8j1sÀ–ikWhcƒšR+q—,b1yíï…ìÙ¸ðXtTÏ\e‘x‚k¨ÅÉѹº¯*™ŸPà·BŸ.ñ/ÐD~ë®þHä·>ʼn úÛE>!ù„ 4ÑóØ2w²…þ)¡˜ï±=ÿti߃ŽRÊk}÷¢¿W÷h@Ë„ü¬o2îKÇ’Ý\×A,ãb¼Õ£!ˆŒÖS-X\Ò-5ŠÁ«þÚ.êù=Wm ú›¨çŸÜ»kÔKUèKâ7ÓxÖÑS‘Ú¨9%ÂG·Íé#¸QÔ .¬Åµyô–Šø·£¨åE‚„"œS²0T†ÖâÌd›{#Šz2eI(ê&ö‹Äë¼Q4ß僴>ƒ´Êô·4Ã…$çßV„¥¥#dÍѱ´Kˆ–±v¸âç Õ̱–´8•×¡--¿-é©¿ C°%~EHºÎX§]nèÚ_ú’H$1߀6ìw_%ì— ³½Q>BèÚ8‹dqƒÂÚ!mæÙÀÅ,oÞ=¤dMZˆí TˆˆÃåÞ™‚ø%=– m‹ÿgˆ¢gl¼K¹³J‚@î¬%Àl ï’„cÍ-ß5æ(×ôþ:u .ªÁ®15WØÐêÂvËR›Wǵ Ü#"„Ù\Ó éE¬Û\¼©m:+=¹‹D0C¶míW8ëæq®^M§ŠTŽ‡°hS· k§9Z¸¶3Š†]ÂíßW‚ÚF7ErïK-YTuö•ƒí…¥ÕãŒåM‡«…«48¥„=cýiÒ¼hBk¯¡@׆½çã;úXK8¯ß—Îb’;‚ӀؤF–ÉúCû"æ»0ÀõÈM€bëµ[önXIöÄ_\ '£d*'¿Dɧ/^þļ|åþÕ×÷§þòŸ}ùʯZ/_ù—^gùÊŸø3ßÿ_¾ò'$¾„óå+ê+ßÿýjæþѯü˯dýòý_}ÿË_ü…¿´>ù¾ï{ù?ùú‡þ›ÿë?ý׿ÿ?ù­Ÿû…_ø•ÿãW¾ùÿýŸßý•ÿì{¿óoý•ßúû?ó}ßûÝ?û[ÿw~æ{¿û?þÛçwþýïø¿ëå_ø×|˜Ö™y± ÏõKaÌ2=íh&0¶qŒ³×¤Ý“¦5‡×)7é[/Y§äØŸß„¡c½·é°õºÚð’\ª´«]’²Úð6cQÞ«Á8©ÛȬ&°ùüÆçæm:l½nãS+¢ñuRÀ‡_œ#Œ’#™…WSh‰lÂa %Í»hI ³ØéѦÃÖ+Ðb%%t›’—ä„k3i|»Wƒ™•-6vÿÆçæm:l½ -íõ§¿—xùV¨¼dý[Îk°#?çÖ$ðý5êˆcfX`…Š .B‡J@ f‡"X–(•!J`M´DÅSà@K”÷Rpš¡%ꔚý"OŸƒ“m¯“ p‡Ï×ö¿à¦¾–ä3@ã@ÃëÒ¸iŒZ-5Í/èÓ”²8?p[0 K±ô)kTN¾”*y?%µtŸöWw ìQ«d-º‰´G­t(–>ª.ƒ”kÌ´H4OT¥MjÁkr)Ð(E€¤Úq‚±ßòxhfÇiat%ÂA›Ô*™8­DX4:Ui”Z0- †UŠTL«Ô!•Ø¦’3,Å„Û¨Q¾ß`tîÂ\aý€‘,ɈéÀbš6tLX`ìå—„Öð8¤Ó8E"*hÆ:¢5NèØ%Dc†± pHÏ‹ ±I“Ž¹.8UZ‘…J ¨„&*¿%~W5ÁD]dõµE%ÓMVI†BuÕ¨ &¾–dÁ4R‘$h¤Ê«Q­4ô›…§œi¦")/myÁ´K8Œ/ñ‘W½F¥!jÁ•±á5ZªNI¦•$c›1(좉‚s8Rœ q@kŒ°üa-7a¬YSUzQ\–êGSÕ*¡vºJŠlU«„Æ*–¤Å‡Kx›°Vmø¾Ð¥Â©T ¦ÌUIÚ« \¶©¸ÙœÖJ€ÁjØt§m×ÈBm50Ùñ†5ˆw ®®°Ú“ Õ(‹÷Ñ76ª¨éhK«¢õUµbÀÜbNiÚ&æ]”<´ÙxEäøw‘’(nvB·’J4\eìôTT—HDz–@ËGE¹2iºrئÕÊUc ¸qCÆ+×"P8®oD> Î6˜ãáô ƒ›o Tßû†|[(MŽ ¾-²H"JðmàÞÙ¶€fz9Û‚õsv…]À] †öñoßÊBÖtµ-IY7ÖÔ& ‹ì3ŠË„ ð 'bÓˆãfÆ„&ñå57ÁFÆiuèŸâ[½*$Û[A 1Ç¿5Æw‡Öð¡p€ïIÐ2:áá…¦S"Ü´hÈø:¶*îlïäåb>ÈàÈ"te …ë‘ž…¬dUس„¬&dµ$mË°Õ´1ld´©ó` †ärÕAè‚ `èáF¡¥AaE£^èZšÅCÕØÄÌõùsh Vjê5·0ÔM8žhÒ2ÐÔ¤:»¶Û„xÓïmj#ÂkØŠasÆ>W+íZÄ„a¶Û¾¡ûÖ%ŽÊÕ, éÑE´£·×´kE\ÁA|8û{ ÷˜æ”U+óÖ´j^â=ã*¶Ùæ 1“´öúj‚×¼ù®Ñ²¤w0~d܆‰ö«ìZ¦6à«`ËÚ+-[Ôâ—ˆ%¸Ó°z4mÄ-zHÒ¹×b3˜wxQn‹“mm4n­)4é÷™jÊšBLJS­ÑtáöÛya·Ÿ![ÄÖ'¡±KàsöÊïÉe¶w´&ôì. Þ0óªáh_Êzì¡hÎklfßZh¡Ò¹L`æ(Æãœ*-\{ƒ?sr uÚ¸N^%áq¶ÂJlÒ@iäZ%ƒ»(f ½ p=¢•0¹ëÓý •ÄcåZbVV®EM$ }õ33Wk4sÍ3Wkfæú¯~õŸ®ÿÌïÿCßõ=¿ÿýžÿè{~öï~×WÿùïüÞïêÿõoþ+ß÷_ü½_þïâw~øþÊÿüù/ÿÛ—¿ûÍ/ý›ãüƒ_ÿµ_øë?÷ë¿÷'îWÿðÛïýÑ¿öŸýGí÷ýØ~ñüÁù‘Ÿùc¿ôË_~í_~óÿûþ½ÿîwó7¾þåOþÆ×ÿú/þ­ð7ÿÙú?|ý«õñçíþ?ö£¿úo—_þŽ×â[ZÇR—(†9äݸKpP¬vÛ Sš4M$,M<ð§—ÌÐJÞ_âLÖ†JâÈÖ†ÚÜ°õúéÅKà)ïF/EMX“½Y=­S‡×0l`^òþâCßßØÔ¬I½ÏmKàÞtÿÅ)IwÞo˘7nß.‡×„`x»j`B=ßubf‹Q›¶^W^tý¾K¦9ÍY“Ãd3°I³˜v~§óÝKhE&±SBÓKœKãÀñá#Ø Áj.v¸a\££«(ú‚Ä q`Xcª2‰Å‰K!Ì/Ù§F k"ÜÃ&î”0ŽYd[ëR„T•¼Ÿ’¸”µ ÙWwI¥I,®ݬc¶Ì˜©¡Ú¨ìA®1w}Lh^ÿNxQàSœO¦üfpl&1ý¶¶¼¿ q<FaЈk¢I,…@¡¯ZÜ;ÃwjrltFXpsžüÀIE%¶¥Ðh¬[ÅpíK 6œ¾_`1ß×k0gTè…¶à¢[ܶ ÈUg&}Y´°k+g3ØpADÍXG¡™)â”T}½Ö6÷ÏAÕG ÈoŠŽpëZ2:ªÀ£Mm•Ð$fàâÃÄïº&˜ióY=e¹Ó Æ×PÚ]£s,˜xêuMK’HÚ©FÖJ']%†EÐñ@ʸ@PpÚ†ñÅ”ùÚkĵ¼B.íÐôá‹ot Øƨ]yiUà ;bó#De5á~¤xSxÃÔ Ÿ9µpã vošÄ 45)Ë6·7¡¼ðú½MmDx [1lÎØçòâÛ2„ a6ÁÌfÛw¡ÎðVN Šcº»X§T5é5àâÅMbP|8û{ œ+E&±„;‰±ñž n÷¢DÄ ¶ ã$”hy?5b—ôî´”$ÜOÀ$7Ú¸p_at¨( wÃôú%b J3*4›gï›tnÜ¡vêZ2Á¨”lk£Il•é÷ •pž.¸5¿´ŠãþC«Èx=yao![¸ö /¡*ùÊïk>{.`(¢öîRàª7¯Žö–4¦Ê;Á…¢è&±„÷!kŸÔ2…f…Í ~ùlð{N[Àíâ|Ô˜&á ™XᡶWᆮYCo\û–„ÉíqÈ$v•´Ë$Ö·ã×ÅÄ{ûV&±þíùÕº™Äþç?ý•/¿þ/¿ñ?ý2ÿ÷þÿËÿúµßóµïþÅ/¿øú—_ýÍŸÿÍ¿ðõ_úùï˯}íkßøêWé—~ù·¿Ä__~í¿ýÍ_ùÚ7¿ñÍ/ÿïŸúéoþÆ7~ûoþ?ù7~û¯ýíë×ìçþnþ‘ïùõ¯õ×~í×¾ü§~ß?ösõüÁ?ü³?üÇÿÉïøã²éÑæO¼4{è—u]úÅU@cÄÿ+h÷­^Íf©dï‹B¤í¢ÛÃÁuH·~èæ&˜¡pŠWŸ}È 6e¹zæ½uóú]Æ©8¤0¿ë¡\—ÌÈÙì1Ñ¥¼SüŠ~aY÷ÖíٙƇñD¸ÅÓ ×ÌöéJÈZæçñ„¢Û±|Þ—ÅDM6 .¯4©E ê|šu¢¨ú% srËöÏàuîNµ=j˜Ù'b˜¦gžöDZS˜V&Ãâê·—¢’d¾Wkl2IõææÉ!oø9JGÆ%CeL=·¦^&s(Îk‘k¤ñ&ÕˆÝ^uV÷þšþ|°53gY»lS-èYxJm14ái:£Ëë,M½*³úSÕ‘´8³›mm>j1æ´—â2ð¦*ï2n¼t}¤¸Ñ#H[¼TíñlIö\8åJ¬HܪdÚø\Ít3ßØÚ ?pRI´¾j86 k§û«ÈiT²ë¬µ±o'ìôñ.ÞãY§‚þ³|¡îymŠÜs—¯ÂÁÏU'MííÀ7*>úJÉéÉÇ›ñèsìÞ²Ï+†ñaî&B.ü„1ýìf8* ÖWmN"f^Lm?®~7±ëÀE¿ßílµûŠ-ùxb«ý9f]ÝóŠÕúÚsça>ø¹êäºÉÈÚIÓÉÈûJc“‘'¥°E—=-ÏÞ²Ï+¶ñaî)¦ø¡ úÀ᮳ñ¼ÛÙk±ûÚëµÇ³×ty¯ûž×¦=w¥o“Ñ·Éè‘Œ>ÒÏõÕ)Éòo^_©¦¾²«+ëfã9}Å&Œ¹¶fT§:ÕEÛâ¦ÌP†Í«|ÄXsj™!ÙZx>4æÝÎZ í⻯ˆw±ùOl]´qÖ’óZj{î›ZE5ãÚ½ÒƼ¯C«>žº¯î|Ìuï>¯ºGès¯µy‰s\tjqî:Ï»½»¯½^{<{MÜðußóÚ´q4Ïéç3£F•Öaí®ôBä©´7ªš]%T(’ÐÂ÷­k :˜/Ã`cE˜ØÁˆA0¯37Èk´ãÇ¿ÅšP“ZÁQ Ïi­6^‡m¸™³ðU’Õ/ÊV˜Fà "D0à Kðˆ%cxŸZ§­“*¾‚׬f;ðð–y9MTe€gÌ°[~ž‰‹ŒÓW ›´a9ÇJ >ÂÒ„‚­=ýŽ7ΟCª §üa6…uì‚Ž¦Žtñ°aS8”S‚vjui*x:!›}Ž>ᨡȹ·`‹™dFªr‘ä‹rF}IxÄç¾ÔŒoµ%üŠ—‚ìéh+aÁƒ^‘¢£tá0™]ÒE!2K¥,úcƒýŒ_È<ÁÔhw²‰a8y{ íÜ(JQÛ9鶛oki”òL^î$}âPCê :XlFûæ®Ar ¼¹0Àœn”íM©s#±µÃXÅO:˜V¢¹D:è&¸JxÉ’$²] ‚H!‘Þâ€ûß+ /ì£óBÁa IPN \ôÂvó™€Fs)ê¬ýp† Á…é,j#f³é¬•ôEÛ`³Á`ðàKã)ø!ñ: ÍD§Òltoo`¦èIR`õÄ5XÇÊV6l«ï3›tÃ)Tˆ†4Gþã/l‘üA¦ ¹qráa{føG¿-ˆ´‚Í´ù@‹ã¢Ní+3k*RfgGpv.Ú–l}a'ñ%ÅÌF75Û(uMið'Ñø*$Û‘ øÔ Æõ±-§—Ài)y÷¾RÒWø’EíëRe¿‚r1 nèÔKÖ`É©h7åð‹•µøÍD<ó¿pê—5!•'§ÆÍãð":<>óG÷’(7™n§ ÒÅãì7)§D3 !>y|Ž<>Ò“ÇáŒuñ8l7×ìð¸Cdêb¸xü€IîB!Ý<ÎÉ]<~ÁFCW‰D&sñ8=°n_õæñ‹ÇÜžy|•Ô›ÇSÐÅ©óøGœ:ãN±6i¦Bu4¦ã͵wJg€ºB×®Yì˜4ø™ö\J¦³+év¸Ÿ5 ë|â 0>kIºLoòkã¤u —Z5!C‘ÄÁÑ ª³ãRs‘”èôU.‘tJL$uù‰88‚©>è|è0Rb‘‹á†}0§„'À0äJÉëe€N¢›hèõœMœà8¿¦½7às;P§“§@i]wºø|Û ¶˜·$˜Íˆ›’‘fø`'­l\]>7\ýƒé¦a‡X œLéd倻o Ä.ùÊÏ’AéjhB› ×°‹íwþ]ø"ÒŸ†@ÙðÝËs¬›˜°Ä4mÑ2bر k»†qfÔ»Œ‹ráÃü¬Qµ$t{à¤k ÷"~8‹h£†/ÏH²¶ ú(ÆÑEg×Ub*sHòÛƒÛ˜>r`²”ÇA3f ©~ÄìžÇ»p8K—`†‹iÏáè‘í4I”á‹ZøuÀÂÝ å‰æAš!yj]ÔhçO _¸ë È"xAºJÀ6â´/h}­QØBjÆôO` ÚnŠZذ맄LˆH4f|Š8…à$&.¢kwÚ<¸`šcìœz³c+]\c¦‘µ^”¶¢š½çˆZ ¢”ȳUFéÏXOùÈ ¯À¾"Ü:ãFh3ÛŽ×èAâF´4Ió—$h»_Ä.R´ViȬ=ŠöÔfM›‹Õ`¤¨wN¶j)V;Qæä@NèÕ¶BŽªÚÖU¼s-Ù>±ûQÂj ™hhcž’nX€º“)ÉÂÊ ·`sÒ 4“V3“%¾Í¦É¹\ä¿$†}“? ×å"ÿ¤ó|’ÿ[Øû*] ª¼"Ðe††™´‘`É“UæH².,ØŽÞmÿÜ£ŠàÂråoƒ>™¼€·”Ùé »Ekù SO=0Ëô7i)‡ZþéH×Ù Òœ§VO@õ=“àFDÓ~¸]IœK€ŽŒÆü­ÑÕmh0ŠÙ¶ ¬4gpqî™Êòx,a¼úu»ŸöìdW°ÍR:XLÚðµŠik&,›é"†D •ÖÕiuÿêÌÚ(Õ0 ßÙ¶†.6\“z®';>ë¥X*IWú~Š":Ã\%ÛœÀXs;Æ©´í­a‰|NT\ë>µʨ˜ôŒ•LL¯WS‚–PÝéêmš›4µƒi’C‹NÊ6´"+jʤ W0×þk?©Óld«g€Í¾é3›îÝyb¢“®–/›Ç©Ót’çí+:ÑÿÎvHsPÓI1Ø ‰âdú=Æ|ZU…nÎÀÁ¬×\Ð'¨Ç$©!tIã еŽ A< ˜Øt‚w 8± .W´çÉÃÎB„æ;]Lô•Î.ÔHÆŠœ†èBÔ)Q¨ßH¹C6>¦»Ë&ëD<áµG žÝ!¾ÓØÇ10_+×L¨0aûá-elÙÂ|D»àö ¸Xëv9±‘:§‹³b®?-ùõ_1—£6ýB9ë²Ù½¸P’Ôr/~Õ˜¬/s‰zßÁÓ×.²ƒË©æÔ™ôŠW;3š—Úî«[\û=œÍ'm™‚ù‘O«WkxO½EIwô\uÊ°;ºÝNIvû·ûÂ1·ßÃÉÕ®“÷ˆqÌYáºô9s°Ç;i»è8OÇòiÇWb÷µWkg¯èò^õ=­M{êž z¬˜îDTìn‹›ˆ²Qw"‚ŒTȺMD¾øÕ‰(Y¸¹¾ý’Û½ƒ‘…‘[_9™s ¯ÿD ÓIÆëа’ÝΨ¶$»/Þ@ÝÃÁ""rND>­æ]í©ƒšDD¾j»¢p×G;¶2W_¥;Ùp ¯âcÄÅ}Áö¬rfŽcÆ;y{V8OÇòng¯Äîk¯ÖÏ^Ñ=ä½ê{Z›2öÔÍÕæÛDôm"úÿOD©çúê”9AÆZŽD³¾¦SX¶y]}‹“ܱ%Ùp%h`Iµ—ä›.c±øyÛ+ycÌD'ÿçUghʧ™!'¨ÓSÇ — ê£éÍc¾aªã³êÑ\´÷Ì7©lìtóøÝ»án¦µâ›ªuµét§gójñwßG|N݇·§Ý‹ûØlVÛ~¦Ž¾SÇQ¼ÛÙË°»ÚKµG³—ó _ò=«MG½ùœt>#¯ícÇd*Š-› ®»YR«ùØŒÖX¥Ð²>ZQLšÂÓ8Põù”ñ¡ìÏP>üI¬.$vF6+ÔóáΠ&é^³Áêa‚w!ô~Ôtp¦Ä%ygXµjÞ5(™ÉJè]ƒ5¬fLFÆWˆ…Ìyâ‘î8¥e)Ó.S —BëÁ\ÔÂA#ö«D}Ø° Äù–ñẹ׌\¼ET€/+|²rÀµAT÷k|Pˬ3:Ø8›ƒÍU‚ã@[Z®øÒaðÆDÙæÂ6ó¯é†ö(N[XêŒ ©›ÍNµéë|Œå†­à"›!&B¶åMP^ÂooT͵æÐÊÓa.àÂEÃH§™c ž; <jÉkàÕ‚EA¢ žrhùóíY3éËÕ8=kÑ>½âVN3ᥠîäDXÅk&}8âUƒC§_ýmÆ„y1Ú±ŽE[0Ç+F¨¼j fDKÑÜjðvYH"céV3»îä[WÍd<„)Q°Nlˆ!‚Š<ÎÆÛW'E)vâuЩFWó©Tºø 2ù@¬2*N¼ù&N²]ÍÍb+h`}ËSû]Ó8Q¨ÙÁ·Ü"ÊsýÄ‹A0?'„[šú Â|'mÖ-l!ò8KÃ~¬Â¨&Æ문ÙÎ4³9w9Ó Ø…(PðMÏX¡Þ€9Óì„‚'º«Íª“ÿp×OþCp4~xwÏ!Wšü¦bØqºÀ[ñOÇktžSÇÙ’öö·¯¡F=Š¢ó>kZ¦“%•!! åxSf¥ˆq7>ùEw£ ‰wP¤P¸Ñ„XDŒxaªÛ¯ÈÈj¼ðÞ%×ÝÒ1ÊÆ®- ÃæÀîFsJäFƒ+cî1SWìºæŒÈÂÏ¢'»cÿ‹†pÓÈ xdvqoäY?âŽý€rÖC”ŽV>cÖtŠƒt¤ÁôàN·¥ìŽ§DŽ4˜N¶hÄ|ò-N£;Òàšµš”뜿ïÓr¤Áõ4º¸#MÀáÚ"œñ~z0jÄͲ‚Ǻ# üÏï ÝÆÔäH³áéŽ4^ž)zAÖÊ–0|ÄÆ%ƒbP(þS#˦٠j\sQæq¤ …×pN° ½%-ÒPIâƒæ¬™M›iõº# Ìݸ‚S)ŒŸQ›ip+O^¬{}ó̇QEaRî„ sLÚiÄå®@;–TœzÁÕiN ³&ïÞWJº bzõÃq‹äMG (r:S ¼r_Ž4!uL£–’„÷pæáÔ¹·NO.Ç¥èƒËg=\>ÚG.÷ãrs[Ú\>ë“Ë7¼¹|——Ïòär… Ú\·Åãbr•àZ‘ɾåâr=†w&ߘA".ß ñø¬O7GÅÍãÞ4´KŒÇe\?lŸ%ÄVM¥Z~#G›# ŠÜ&ý7¢r+LS`/”¼ƒ:Ãcö#f÷<ŽØÅunº3ãõ íÜ`1FôiÒë³fS†¿DòQp8Úâ†L?²w±h©'ñ"iv¦TS1)°0‡Í6b²/äHs ‚iVÁ4†T ´ í¦¨… »ŽpJÈ„I‡<ˆuÂÀo7Gšh÷¶Îƒ•Œ9à`98+.ÒãÕ ‘WïI[¿Í¾ž ¶˜L‰Ü[e2ýyj¿Ç•{7ì+­3l„*7Ë©šƒ¸íeMR GÐw?„_b^‡I7†ôäî2Í‘fufç£nŽ4l+Ô"ã?¶Åcè㶭ËD ’Ž”sl~”°]B("þj·#M¤;(| #ÚBËÔî•äÞå"ÿœMÝäKå"ÿL{JPäJÚWQ•P—“•¼œv; ‘›Š–$½,Gšˆ·¼B:…Ñ‚©ö*„§æHc Ë#„T'–ºŸtÛJæào¬éHc@öGb‹T2,N»fšÍÂSwí”·•O{6ó4±x7Ó@-,ê﵊uk&,›iz¦—SØ{·í_YéHÃAmT¶5X[9f­ûÆ„… ¤Í{¡/NÔ*«Dòã*‘¾SÑ âú3ü÷‘çÞàOÊêØÚ]ƒ'S^àW¤4KÁ[,–Ä*^#!&æy„´pž…ÆÓÍÒزËaùŽáIN°5X¾ÌRÇOë<!…ÜFnÖÉq6Od•Nf9dКï3£s–’×ØW•n”/ÀxgF1!ƒü×4¸ò4ÄU<ÛCÉÌ>j„¸÷‚÷]PˆXËÂyCœ`僌¨‰ôÔD“ni&;7žScŠg&0”cwˆ…l‡HÒOaû†œÌ8E§Ã¶b‡g ×´Ã“9"«)‰¥Ø^*!<@Kü)B­‚µŒ’1ëî»ì´$‹ˆ¬Ã™Cn†i‚BôÍ)If‹ ÙRŽË%‘x´Ÿºµ‘¢1*}(Ø‚Ï5mù+0H$¦[+ô Û…èÞñÎf;_Ô¶‡Ç[ ¯f¦ÊxFU@Ú™ø¯Ÿñ€S›#6ó ÇM¬–*#fÒ SDá™ %Å~Èc&¶+Ö¦’:Qem6ò©„‚…{fòÄ0´OX ^¦_4>WGØr¸V×ò­âõ;biªuhƒ‘Ø=h¯±סðõ¡0O†yœžûïŽ]¼¾ÀØðš° MÓÄ4+ð Q¸°´‰j ïzÓƒMæË §ìßA°ƒ®¾VlÑÀ,ZaZyÀœt³.qJ5=ÄJêÜþLLÝF'‚¢ØR€Þ/¨èP“îóA¶BKœóÀë|@f¤|¤ãÒ9X'û|à°NU7v …`fŠ‰-!ªÓ‚«6ÍnÛ˜Òn‘ŒR$aÿJG¦gØ>V [ñæÝh"yk[4¶êI~¼ é øÉU™wkT0Up±˜ŒW#Òß>>Øփͬ·¤ÒªWœ Ù9i៙P?TÒ.B£bÍUÏ‘ÿÎvЪ[£ùË9"Ã+\!k`˜2Fâ*8YvZi àµÎ² °¹Ñ3£¸CðÑüÃn@ÜQ᪦"'ægœRE/ºBòn i?šàÂ#VYèPG [+‰ð ýPU&iœN1èyÁåîÀBŠé¥¡mVËïØ©m“†1ÔHýÙ”ÕÄ@&ñc&¼ý{Žœ-¸#¥SçN%¬…漏¨ª ãhU#„ã÷Ø0SòVòÔ¨ u€»KêRî¾½y‰Ÿe[™[b2¿à}´Â„ìÿž˜=3D:ÖM±Ú©T”ÑEŠçð†°pÏÃ[‡ì>¼òÃ[—Ìo=·}xë¹Ã?¼8‡7B~xë)݇7æ¥|Ì°Ïëð†Ìa÷áÍásxÛ%vô›«ûð†t‡ÏÃ[ÃmÅuxk¸}¿oöÛøá­ñ8¼!ïäóðÖF=‡7ôwÞ6¼o^¢Ãº»oƒÏ>„¨}×á­ã°î‡7çðð:¼q×á />®ÃB0?oÈ-yÞ ÊüðÆ¿Ïá ÞàÝ~Þ·ïÚ·ñRä:¼õ‡·®{ÅëðÖxàÞ¨ð:¼uù¼ö{Î÷ámÑï9¼õR?;¼K:¼u=n܇7¼omö‡7>{¹o öÛ?¼òÞއ7-Õóðïm…:Ï€×%ÐÚ×$¶@ïf1ÑÛQˆR,{Ó€º’3xí ƒDökr4øïZ/œ|RAã陪™Ô¸´‰ÜŠ‰ìX×瑶š«yz6øÏÈs`S{wÎ÷Ö%¦¢ íó$üî¯ó$bä]çIs>?çÉ µÿj;çÉ eàœ'Ÿï>O"†Ü}žDT¸sžDl½sžä£…sž\c>çI8ž?Γp¡¿Ï“³ÞXAð¸Çyq¯ó$âg^çI×yÒ ü<‰¯¯óä„#ýoLyÏìß »~žœÊTuŸ'*ïœ'•û<9‘HaïÓ>™½ã5ÀužD ¿û< T<Ï“(¹Î“SÒû< øyž´’ë<uËÄ5ê%Þ~g&[ºBý©?ûòçvÀfÝø0¸BÊ ¢@Š«6]·á–e‚žÙô¤¬‡Pþtßßu‡/zeàe¢šiŸŠØÜGÛ0#ñÒn³k@mQžH=S¡¶ÄÐ"vß¡3"|¿@gJöV¼½êáoÈg2ƒy2é„ÀÉÀ¬¿AF8¦ëá©@@'’؉v%ñm¤cžÍP6ßh‚{¥ûĤøñén9%ï»$+.4 ølæ*@DH Cy7;ñhT|Óa ä°j”«÷bzŽÖ3sIåèúVì h ˜Æwta k»a"•„¶k´R_ÝÕ…Óõ“mt2¼£C2Ÿj¤€ç)eÉR¦íÔ +—!É”õ×â+'¥ñœ<à!Šnf^3\Oð½ÍPÖH9L&D¢…¤@³Ù+EÌ]Ê­»K:¡jcu‡»`Æ$£µEÀÂf´@Ç jC1@ïÒßÖ˜áF» ¦ð GGh;Z7¹&kbCKÉY^#ròÉžì¨@hü†ŽûgÆúJöLêâZ‚i—Éç´Žî]öäEàÈù`À9A­þ»AAdE¾Tö8p(¤¥O”’ÿnÎF{AÓžt¾aÚÜ0tÆRŽ Ïg `ÐYÎcãà“(FäDøtŠÀµƒY)Mƒ=ƒU;MK)Ø{6ïHN1ŸvÏOn8>« 8(‚[(zq7)[›œ25&‚¼ìVS›Žz«]|ã~ËôY'A3¡ùï)p¶d„†(#ÅÂ<5R½)ãÀN»Ä(¡H}åõ¦ Fµ½)c–'e <)ƒF³öe/›RG,HxL@Ìûö¡„Ù£8è±1ýÇÆ8¯P´rTænd…•–½$ßP9Ýù-¸3|o–WO ¦%>FÁAè]ñ1±¦Z6ÆüJ‡ eàVE¼P@ÌÁ}Z†:b¹6 yÐfj‹ÿŽÃ€ZÏiƒpͳET½¾ç×i j¦ ¯ãrF&×ï†]zñb[³4 !-{áAÑd+ÃññÁ!xQ7Ç 9‰³⚌@.±°' ¿ÂyY_wùèjDa+³)¬5ý¥€ÜH•‘0”QÄ9n–{ÜJ‚kÙ ±GF2Ღ4¹rC± ráÂ0²…<ãÙ>lÙ"pËÌ]ƒb訑ò`2ã´õã²Å LœD=xxB[º¤È«8%zfŸ…= ÐÉ~—žwupL‘1!°PåÁV¨ƒkXÍø›a?ô®ì±ÿ›a#Msÿ(Ô Fÿ®ÝÌm€ïîÁ#ÃmÜb“Á({ºÑdþúB ÊÃGèBÓÒ';…$.Ü|âh–­¿hû㧱Åø™óâÆX¥•øÏð'ìbÈ »I­ËR(ÝþRqUŽâÚ[a†h£'Î)ÇÆ+®þ‰-¾ÃXÓåŽ «Yɤ±0Ÿpáî?c5/:Žpœ%‘Ýu6­ÌzÚ!PAï\wçïUŠIÕ†I¨â–•uElÒ‚Ñ9»²Ì's\wIkµýoFÌS@ÿ‘t½ti†öSœK;a ´É ·,‘pd¸]¸‡|¡ŒÔtKQ²dƒÔ>ÙŽ^ <ˆ|€²¦Òê.0ñ:Gít"FDr¤ñzÞqµyýâ°Q­Åˆ}Bx„eI M‹°Ô;â•ÞíoˆôÑÚ¡¿NêÇõ —ÞYFÿ w=(>5ôxqëÞz§—¸ÞYfÞ"¹<8‡^/½sÍtÜzç&z'ÞD™¹xI›ø¾„ÁÞÍ8”ø왑óÉ~[ ʾ<(ö Ùò»åD  Z¤ AfpHô>8›¼'æ=ÚEÙ¶°Ü|—9Œ¾Úè½d©¸ÂKÕB«"(3^“‚íÌhG?5²Ì„»ƒ[Ð%í)YªS·)þSßÙIM¦¨U2¸ÄTŸ*¯Ð¨Ùp4[Ý)ašst—·¢™ªBÑnµnuåúô‚†êAÀ†‰ªUˆ°˜ó`xuñ " PöÑ>U9‹2(°ÖZŽ¿ ÏÊ¥ ŒŒKåšî[ÕS8vÖ„˜Ìf$=œy|/5ï‹Êù¹”Û`–ª§š˜f4Ltd§AFëSyg¾¿·ç•§ýNY¿ç±ZÆœþ([|ñPeT#_”©õv@̱Ìd¼‚eZQÛÖ“­t®–yÀjäsFìJPÖAâ[GÆÀ•6¡¥Ê÷%mÂÝð/ÇSðººC[ óÝg=½)‚œ#Ð NÐ:Ú™õtïh t+0–ù:"~8LbÚ>Õ‘ÝUš·&Kðhûå蜩à“ñþ»Æ›åZîoéÚÐéß’·NOwš~éüð¦¡\²ßÉ9Ãþ8 ?Á£ð r§Ið{›GIG¬·Q/LYã)8ûèÂÔÚgZ?›_ë7¦úSý‰©~c ž™˜jÚ3I¸õý5n9ó…©iz¿a΢ñÂ.MHYú½‡ÌÖF²¿²d´S \1â…+$‡¸©Ê ;¸úÉý´* Œ]LæuÈÚ`³%pEðŽº’ƒ ˜³Ñô@™uö!GƒýîëµV)pÿî:ûáhðž[1ÙGÑësÄ}4_òe(ix¾¨©½;ç?^CQž¶ùhð&t›pï{™pñû0õÑΠ¶c>ê`c>ê=?ÌGK™˜8u›Fl—ùhàpvÌGkÌÇ|Lj‡ùn ·ùN+]á<Òz ·ù—`—ùÈÀc>²7áëË|ÔGzšàÖq™»n>–©è2uew0ó°r›nö˜|2{‡ßÉe>b€ÅË|T<ÍGô€9æ#z¥\æ#ÀOóÑ.Ùæ# „nÃ-.¬åyGËÄòxɲêá,…ȧ8S(ji-ÙSý&6õYA³È§ï/žåþó’óìbw³ž’üÛ>ö|JppË–ÕF1ÂéÝëíÎo]‚kekÇ’#^r}ÅŒš’Ï{ÿl„zê–c-r¢£®ðy Ñå´iŽ­åæ“Ì=xHi7"|ãBCÉús$¿Q^PÕïб½A¹ZcèiÁ"ÒÚǹ ï?í‹=᎔>B{ÝA¿L<Ñز^áOõOó ñ“¢Ž¤º äÓô@ ¤]]€U½‘‘; ¤o$­àý EÖHŸ\:ðÃÿ;2 ý”$š¤¿mxãX©šPŠ AG«[ÓGrÚ‘i‰‡©S&ÈiO¬-÷:œÚ¤µú>ÈE­$\x㓺™è«D9h´`îÓM/uøMéE°½<£Ç®Ùs×Ð:=VÕ{$=ÄN6O¼´[ ‰XNò {3æi&ɧW]5Èr³…"Wæ†á[.ÿÓS£r tö‡·0¢&WœA`ÂZfšL™ð6“@éÑÕhþs—OŒ‰°Ÿ@¬±h`œÕ%¥ ÷âDÍ}à€…T\MŒ"£(KœƒšØ}Wˆê…4°þœî1¨Ùò±¸$%óŠÃ°&9lsž eºrTCfírÙ^,>¾ËöÂ_iHçŸ.ÚÑNÈ0ø¥Évïã÷]By^×æúkKõš»¿è5g%Xü{økY@5+øÀ»A"\XâÅtp‰ Üm^ÃWDñÃÀè@áK¢¬î ^ðqÚþÝ”D0þ¤rƒ¿|lï‚}ÓPڤ˽R¤GË.2¦6¡ÐAÞ–L5×ø¶"üà‘oü2üP'á´É›CO…€ >.ÅSYêAŽŸ)!¿0™¼ëà/qÀ¹^‚ÀøŽEøë ˆPÏœ:Ãe)Ä»ïtVgŽ‘íf]wßóJHŸ–ï¹Ë[àà窃¤ÈýÑNö,»¯47ÙxâØddcÆÕë|Ì ~÷ϹÇîKëøA>’'OÇóiÇ×âôåëuÆãkºÇ¼×}ÏkÓÆž»Gcý6}›ŒþÈè#ý02{]%ÃãçÖ¨:Á×´kG`ªuë=hÌðV;Mß3•¸fZ©=Á-Q½C‹D.­«Í4m‰n‹ù`uJÊî:öèùj'”üì+ “Ä{úªž{§µôaÌ-ïY4ß·=²ÏÎ/ù×…ÃSÇñ|Úñµ8}µ2Mkðñøšî1ïußóÊ œuÏý[ÐÏg4vb"ƒAèÇ)»ðþ¡ø~ƒŒºÉe·G@ŒÏn9óÓË.$E"Ïæ]¸_(p:Èt9‚… 2’o—‡"=Tp“:Ì3é.ÕÀ ›Fûdz8¦+ ^àAö”w(Þ\`Š ª~• ÌôeåX*SŒøàùXÏñ™BˆøH¼j‡ë¡èž¡^­ŸÞÇU%…¾½ŒxÅP©™v>'™Ëጕê%"¶È'ÛŸƒ¾@É0æ ”r²5±7ß,Z­Ír{ ¯w¼­gTÃ’¦À0©6)Ü0ìw9)‹R‚q¨+ˆñ”Û4 ì®âI+Âð kíð'ñR¼kУ7Y˜OSÙ TyôÁ§µX’N«Ò\0B'ŸåU%lðø›©Z ¸D»84Z\L{x&/DÎß‘²P DþÝ= &.Yå10æYE1‚9l-è®±N:rïM0Ž«?œ¢\vH\šb6fØس'—»†r¾‘!4¸¢õHX×ÇR8­/ÞU¾ûÍbó2åGB*MǼwŸŽr]5øsU”j†QA:1ðÓ`h§¡©\ùjSQ¿¸ðEíVÑäsÜ;o²Eï$Ý/Tô*aUR\g˜`ÆÞe¯WôÔh.Õ’iY9Ñàœ¬•Ç ·Üš?él#‘3ß,þ.a%`°Éd[ei°VÓ^F61ÌÉn—(‰œ³7¹om zA{ÆݪÍ#Ú¥3\2Ê£ÍnSÝ%E¾©ä¢Äð¥\1ÍC@g[ö·×Jtxv /¡»ºM OÈsl"ªé†“0Ú%|4‚Ó–‰„íuŒM·ìÃDIJïTFÛs +󭃢‰/ü&b# “i¼YäX“=1׸©‚–íe¾ábèŸCeEŽ!ZŹ(Q}‰y Øg;¶«ö‘è_ ? ,@r¶¶KÔVè’%âœ×ñlL_ž‘í% {Qph¤å”ø"#')P(ÓCb9IÓiÉAEþŒ@ÝãïĈj†£¤Vä U¬U¦l¹à¦´WÉP¿ÈGˇ|o„ôRV¿ê\.JbÎ>5·jL£¾Ij¶QY_ùœlX¼ÿJ˜Q¹©`Üt0)®“°„Ö@–CÌ–°^I‰%”öwÿŽdHŸA   X¶(-aÊô•Q˜I)6œm8%h‡ V—^:!q¶î=LsÇWìaÒÜ “eZpÓ¢ðí`§øµ¥> –Í—ñ9h ¨€°-Ìj* aRV¡ ´Ìà§$ójcÁCíIýbƒýŒÓ'­ð)¡ÑnBà­„`ž<>?ðøüÀãó3Ÿx|~àñùÇñ0ôÁã|€}xè›Ç•aÉy|Cdjœë/? x|~àñùÇçg<>?ðøüÀãó[ÔÃÍã#[æ“ÇsxòxOGø†'çüàñ\Ÿ<¾áÍã»D<žË“ÇqFyò8ö¸›Ç¡SÜ<žãç<…ÿÉãTL.‡wóxÎy<ç'£Í‹ÇsúÈã9^<žã“Çazò8Í>w…'Øyü” ÙenGûOÏñÁã9>xϧž<žÓ“ÇÑñÍãpºy|çjg:…±éOÓÒ”IeLS”«?úž«Q‰vËSÁLþHUaÀØY@ªZV=¾t¤¦éÎ1os,Nê)ÓMS!ßò°¬.©m‘”•b÷I§D‰™ºâ¥m°šxSJ#L)iöÁœš›!·:ƒªÐM Á¸5­Ü®éœMsóùEek¯~v 8y6#G"1ù/>÷W°-À¼%Á”±Ä’‘ÒÌ줕ëL>F#$%;*ÀjàïÀX¥¢kóƒL“/NyÅg&´š)³¶ß  óÓæÀž†@³¾?³±<ƺó =Î ÆŒü.ˆkB4ÊÎÇ{a{Ý}(—>ØAK‚¬#8騽¨ÐW´ &o"å\Ù&0jxâòl›IôŸ? ‚"¡Ùи½Hà¨Ö™b‘¹PÝóØb·(£ï©Ñì¨>ñ9—Úô…P†/ªÞ» R¥tÒ˜æ±ä¦Ù„êð.ŠÙwÆTfóSgèD]ÌÂ@jLÌ…d_TÝDœ‚ÀÌæë‹h É×÷lAŒ€vá” Ý _yëì’RuÁPéÂA3Ê>§ÃH¤ RÃSY³v”ì+šõmöõµå Ï×VYpªÓz2Tµƒk{E¸uöÐ&ÛΩQ%nH{œá w—¦€9X+šc›"DcOÕoÊ81™Óß5:ÙZºŒ¥ÕN”9m 8¡4óX©¶uEïÜ–ìpm†E«Ñe¢ÁùŽfà t'³9½D9¼”äÓ oN™›æ”b µ‹ü«bž]ä#y¹È¿"(ˆ&T¸¯¢*¡J5 × ›fXó°h°Ø-y²ÊI–í°;z7ÿ[’†U 2›¿c€2Ýäjv:ènÑZ>H#áÎnhÎZŸiÊ¡–Òåè¸`ˆ¢P´z½x CÒ2*C1gÑAw¦ø ÓP¥#ϧ—ÂûX:­0vV¿£ªßj@…1gQRÜ1À¼£w–|ùDpwÑendstream endobj 6 0 obj 22572 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:59-07:00 2013-08-20T08:41:59-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000022876 00000 n 0000024446 00000 n 0000022817 00000 n 0000022678 00000 n 0000000015 00000 n 0000022657 00000 n 0000022940 00000 n 0000022981 00000 n 0000023010 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<946799EDBD944D64147240A63650A762><946799EDBD944D64147240A63650A762>] >> startxref 24616 %%EOF ast-8.3.0/sun210_figures/cmpframe.pdf0000664000175000017500000001641013004147321014272 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí[}pTU–G‰IètŠ(#D˜Ñf·Ä™%I¿÷ú}Z ‰(+vaü‚„¤‰øALBV‡’Vò¡ãnÕıftF2!îè¸ vz’ŒU™VL$Í&›4q˜•Ð¶©n»é¾{ß{÷ÞׯíìÚl¦ìÆ~œÃ}çœß9ç~{}ÁDÐ&Jþ¢çÖƒù1ÁôÜÏ Tdz,g1=g 9J(°p&š!—3Õhrhød¾@‚O‘WZÐFýwDo50,_@³"áThÈá8špx¥KdiÝj ‰RdUŽ$·  t,“RùD+¢·ˆeˆ#ÛlGŒÈÄX‘Ö­†gÿÁ@ËnaYF+X¸Aq æˆVq‹…·¨¯Ò¬Âg -h44 •X‰pª  ß ù¸wYX&¦‘V(qN^M4Ç*c‘+ëbLX)¦eªa˜e ÓÉ;’‰i¤TqŠhÚ óüïyeúÇï¤sÐ6ÃãºNE³jZq4ƒ:á´ò¤)µ3ñ´¨£XZq¢a§²èÐ(Q½…_aPþc‘„V•*ÀŽ(2JÏ©Ö8Œ $Rxå‰tbJ@fa”€ Ç KÄ$R©u(JD.äE¹GÖhžá•'eQû*­‚ø$A‚’BCkNÇ‘­T'© lj$4RºÕ€9Ë"@˜#Š‚*\)¢x •ˆÜjÀV!4™_@¨ˆ8Dc…ªC¾wr†Üq^0H…ÒRmW¥cF5f@pŠ‚jòŽÆÙf(1m‡|ûE6N–…8ò¢vƒÇ *Z±UÐ!j/¥$U âTk Mô¢·'A/â+1EÓ¶PÖKÁÎ ±X¨Ò“k4KÉ-%F¤…S"%Q¨g#z«AU(˜#òhnD4'„ÃH¼$¨D¢ap‘¸2½ŸAMkšAî.‘G IyªBiZTçe‘WÆ2DË#¯Žü¤«v,ÓH‡2F!‡žHeÕ'Òè­bnAìFp(àþßòeG\¾–r¾`GŸbrò‰#ñ(‰4âL@MÐjNŸ+È_Dñ(67`uþL€ ÏÒ4«Ï”ã$Ž¤H“(°BÓ‰¹‚²˜H@INt^@¬À-°•XB5Wà`«,¹ó¡åÅ t%V^€ß·Î`^·Þ´ãźg æØÌ`~j¥ æûYc¢ æûKiUf0¯5¯Y³’ÜsÙ åÌkj«ëj¶ÿ ¾³j•aÝý¦‡ª³~ÓTlúÓªþù—M[š>{¼mO—1£?ýjQߢa¤A8ðØÖƒ³Áh¸Cn[xº>èmw>uËÀÔ?°f5w—åÜ20]‘ŸŸwgGGû‰MYEÛ ïÚV°$«¥ýÄæ‚×+=YÓõáp¹«,¶”[¨Ü]/sÏê˜ê>žõÁÝ}·Ý²¨uÁÌ–[·ÿv^ašáu¦Geðª$y™$É`’9€— q©àçþ™Á6ªû™=oÅz­À:úœ f«×=À¿8ʇþ‚U§¼ofùv—ÇÜÇ}»#‘FO¯Oþ É¿žîXìŽök¦k¯Íàš͵\‹Ä k²Xd@|2@¼ bSÄ Ðï×ßPžs)?‘OŠë³#ÑHdwÌYïÛU±«7ê‡_狼t†ía»ÃÞ…Cï-o 7Øk­`C88­íEƒ}®†•!÷¥ Ýiö<®\Açã_Îüº8í´ &‘!Ab•íPÒ ‰LÊAq’ž|Âèo>0ó´qYMµy 9÷rö_Mv2ŸhCCÃsËå5"_gšû¯­vÉŸ~»°Ä@t÷µF°á¯»å_,þužièî—|ÊuþÆy&"u£›CÅJr§ã“u:ž–áÈúö!¢œÃÿœþ‹ÈF¦9œ8@âÇ?dŽ5ùV‹î._kù*ä/ vMÙnª›q½Êäh»a^±VDÖJ&ŽãgµVT¬•R±VÄ ÕTX°mqæ§ióÒ›ÎTN·~4Ý9q¦êçæ‚'–6¤ý°¾±) ÙÑ!¿ß§t)—qµquúM o_Ø6¼®éü×iÝ{rV…„ s6lðO•+5šzŒ¿ÙCgeWìíß;ôìcóL7bxp+@¢Á3Âlø`³”ÃßÁéuËmËÌ z¨ð·oR9uË4FwŒø¿˜Ù>QÏ„£Ò½3T5ÔüÉͧ®>?X¶±bE®õܹ`åá•ë·á|œ/ýCvàÏTQKۆϲæåÜ@âG‘ø ,3kü¨ÔãGáøí{$ûÂŒýÍ·7 ÔËŸŸ¤_5Õ¥Þ¹¸ê­¡«¾å¯`Ô•Ç­ËÝ.p™²8€€#îXÔ+k½W¼;z†Ç­[6>ճؘG=iô¼’9ïŒBÂC€ÅıòŠ¦å7QHê`I…D†€?ýëÍçûM¥ ò½ùûœf«Û;pšmë°:hË£·Óì°*c·òÏŸºð>÷bfö®=sîhÛâjj4®ÎŽ4.»Á/ã8ŒV5G¡0ë#û+n:¿¯iyÿ”á/yÏ=yþ¤!»;®ÏIðxe©%PÉÐJ)x’„ÑRÙöØ:é¦gr+Ò{º^êéòÚ‡Çc½«Ý½Ý5nû'»CVW}püèê±èÑ]K£ ²öÊi·£Î5V;]稽²txdjŸgz§_¦zÃew•ë£F·¯1J~>ŸŸÈ’CPjœ˜ Ö)8–í›Û™ ¬q`a¦•epû±=y¦—M#3ïŽÙwW†C»Ó¡åûw, …º&în€“t´œò7ùËàípybõ>8Æ–F‚Æ '6zm_Ø]¥10 \¾Fà*AئŸ¶‚ s¾]vìt¹»iAµ}4ZSS×Ú³8÷‘ø,æµ>ËÈkP‹%Yó©÷Y¼¶:ùØM›§÷=6øÐýOf´®ÿZ÷ë‚ùÓº#ûËÜÆe3ƒW¢.Ø=®Þß—)vˆ3BÀå‘'mê–A8»‡£v/p;bûåo‡78]_Þ·¿cÊl=S~ËÌÞOïýôÒ¡ñåi3Ÿ¯ü¬{ßkQ]ûÉ•C9Ïü§‘ÿ÷ £oßäääà¹gþþ©º›~'§»³/š2…ƒž’®z[IW°åI)àp\Šy=ÎzŸû½ÃBOÏèØx–ñáW>dÚÙ5YÆ‹·Æ­Ý,(áŠT Øãéd½EÉAy=úí{ ÉÁþÂM 3ï]ˆ|r¦¶ÝÓÛÙU~¯=yü>_‰pó—xBžÐŠ†<ºe¦H‚&°Â,[M·Ô‚†ÓíýWq•zµ¥é'ƒ…ù‡zÞõÓÿ{¾•{]­ÎkmoÛ²Z—œsØ•õæTËù¯´6îÍï¾…M¤™=·k“Ü7¨çÙœ¤^—ƒû†VîaN5áÐ’²ÿTJ&èœpÔ #ÍPè®C£ÛˆÃ£Ý¸ºMÕ®c°éX‡ŽÑß2Òìæô£¿¶…cW CùW ÃRø"o%”ÂpÆÄ•ÂPÆèKasº^„=ŽÑWùp¬ˆé(šqàP¼I ”š{øDp˜CLõà° £¯ó+±&I¥ï9¢‰³Ë%ÎJ„Cf%òV¬ÄP‰³Ë&›•æòÀ ½›Žpi,¯Dz‰àXFŽ¥ôàMÀa6 KÀ¦c8li!êÁ%àHȘ¸1†åÔÔÒÆÄá,äÀ ½¥qHƨҴ1†eZÆgÌœì†ØÓœ…€Ã™†bÅ ÈtMLk£µPóA“€h ‡942 I`%d:Òi-c´ÈJ"A#!cD11c0GËm-BÆJé=‘¯eŒ(%˘99ÕcO‹RbÆHŒ>c$‹>c0­eŒÖBÍM‚JcZƈ‚>cDNŸ1˜Ö2Fkìô£éÐÑòÿÒA‰òAÚ¬g4B*Õ 1îrÏÒ³–·o):ßTœÉ–NýhíÈ™¢×.®®®©Û~ùÓ›Š‚ÛtZG§£‘ŽÊ†ÐWe¶³öKØ¥ápL®v'pÅ@98ÉÙŽG¾þ˜¨ }é*õØ5µ¡‰•þкH鄹¶¡ûW¾ƒ‘ ó–’Š[Ù»*Vå–´Q/è.¦ñqW¨åX‹l2Àê-—Ô®P“k.ín[ú¢á÷Lö6šf gÞÍÙuÆ{í¹» _u¦ï•/6-H,ª/rÕ®s®Ö®ë}«|´-æ¬ ÃÀ Ü1—º«ŽrÅbEOE_¶íŠ;ê®±O¼äŽ‡?uãeÇÇ˺OWµ|A¨h®[•K0Þ·‡*Ͻk¨æýËƷÈd¼|Þœ øw÷ÌD° º §Ëlø‹R8I鎖×é–¤;®ý¼õ`nwü8pc£ÛŠ/¯èS±îèüó×W‹úrj…£}}ï¿Ç/_Œò9úAL>VqW=ceÑŽ¡f÷TG—ñή[[ßê¨:Wž»±uqÑãíq¡øcT^’S6YIè;yŽÊÍšˆ×áAªrýqkçÄIª|‘l® qG©"ÅÍ¿ëú,õQÃÿß÷­endstream endobj 6 0 obj 5036 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:56-07:00 2013-08-20T08:41:56-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005339 00000 n 0000006909 00000 n 0000005280 00000 n 0000005141 00000 n 0000000015 00000 n 0000005121 00000 n 0000005403 00000 n 0000005444 00000 n 0000005473 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 7079 %%EOF ast-8.3.0/sun210_figures/frontc.pdf0000664000175000017500000016043513004147321014002 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P01³P0¶´PÐ1ŠRÂò¸ ¹ô Ò‹ô+L\ò¹ž × endstream endobj 4 0 obj 52 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 398.7 468 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 399 468 ] /Resources 7 0 R >> stream xœ+ä T(ä2P01³P0¶´Ð3³´TÐqŠRÂò¸ ¹@¢æ  5@ZϘšY˜+$çré'(¤+èWX*¸äs!y^ endstream endobj 8 0 obj 78 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 443 /Height 520 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœì]xTEÛ¥7é ˆ€¨TEQÔDAEª ¨(lØEEDl€‚…¢€¨té%!„PC'ôPBÐÂûŸ“7›Í–»»wæîúïyòð„ìîÌÝ{gÞ9o‰ Œ‘;·dË–é§bÅô—n¼ÑõÍß|#{öð—‹¥xq÷Ÿ²Y¯Áv„à%EAzYgò¥þý¥V-9uŠ¿¯Y#µk«½0·× Pt4DA¡“sÀ¹é&INNÿïÈ‘Ò¥‹Ú Ëz DAöÂŒÀ4HªV•¤¤Œ—^yEFR{a.×AD`;| L0ÉÊ•eß¾L/A7Ï™3ÀY´¨DEù˜¨|y¾Ííûñ{‘"é/áç—œ/¯X±Œñ;4pãüˆ1¸w})\8“ÑÕyjŒéö’ ”«¯ÎxÉÙ†9mZÆ€.W~íµR¨PÆK{÷ú¸?DAèËã>œâ¢}{×OÝr‹DGgü¿—,éC&`´#Ü¿òÄ1~)U*ã%‡ÀÄ_òæÍ C9^Â/Íùz¼\ÃÇgücB:>ÑçxΗ´v-?8gŽë%mØÀy—.͸r|ÊÀöí|ÛÔ©éÿ}í5þDAáï ³BYµJ®»N† ñ1ŽO™à2‘óûͼ”u|giF;Çw9âñš%žË%9ÿ×ñû /È—_ºÛîÝ™>~î,í#ˆ ‚0…'yô(_Ú¶¿ÇÄPáMHð6ΊÒÆÌDÎï7óh'þîv@üâb1p C`:cº„T9´r3³tiÙ¸Ñ÷ÛÜþ7‚"G˜ô’C¾ã†_È‹h†a¦¤¸ C9 L“ð2‘‡Ì*îŒx*ç—^]ºuó8~D`FÁæã0Û¶•=Òw6÷Iš‹¤dI4£9>îò~üî ¿€ø9^r\ƒ‹VÛ½»c^}uÆÔ'Òø` Η´l?¸d‰ë û÷Ë5×Ðïã¸rgŽ˜DðßCµjf_:yRÊ•“M›ø{tt†ËÛðzûô¹àm‡²Ëû ã¡Ã¡ìü’ó5@vÖ.*/_Áû7r™—·r¥û¿;‹;çA E]ឮܯ‹Œ ‚þHN–Ë—ülXS¬°¾ø"ˆ ìÖ2'¬/>‚";„NŠ Îê= ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ@-=žÿÿ\ÀС²l™ÇWSSå‹/dòd¤ ë†IT5Yÿ£ÖIÇŽ•¥KµÎúXr£,ì(ɉ™þøòËrá‚M°a´û"2cÓ&IJÒ1Q±b6wÚ[°@ŠÑ=é´iR¾¼ìÞíæ¥}û䡇¤~}Ù¿_÷UYˆ}1²ðAÙ™G¶å•EÍå´–µä@·nòÙgZg },ÿP–—“ãÙeÁuÝG.ž§Ø©QÃîË _-¥KˤIv_‡Æ—2e$>^í,«VÙ ¬œ1¾\sÄÄØ0u¯^rç®ç;X%VBÏžrù² —<Ο‘è×%¾ˆË!‹o“Mc칌”Ží™:Äqz·Äµ—meON™RR†¼a÷ h7Þ(ï½'/Ú})ÿâ—_(3ׯW5>¤eÙ²­j|Ÿ˜=›Òiùr{f¿r…›úÅ3þÛ£i§7$$.“ù÷IRY[Lbß“ó'í¼˜Å‹åî»í¼€ÐǦß$*gÚ¹VJæ()çì¾ ÿ‘œ,Í›Ë=÷„.öÛo”™»vY?rT¥å¼yÖlý%¥JI\œm¤¤dþþ»œ>-­[K½z!g™ñ‰+©÷™,)C]/º†ìžf÷¥áÀ)Q‚¦à‘’B@Õª²5 ØÝo½%÷ßÏ« öš.Aݯ½V¶o·gvg\¸ íÚñ~îÛÇÿ¦¦Ò†ép… vÇÊ›åx‰ýŸX’ùµ‘êö\•à åûi#°ö a;æãmW.˲÷d]AÙžWb^•Ëçµ\\Ð0"ŽfÌ°û:Òd&Ní-äÒ¥À±Ñt¹re¨Ø-!ŸìÜ9¥àÇm4]îÜIn9-|¸7J¥JLäÉŠ„Òïuë´_“l] Ó+RTÆ5Óáæ@‰‹£³2‚¬xôQY¸ÐïO­ùB6–„¼ý^(é»w3&œä¼ÝÄøÌ>}þy ŸµËtyð T©"#FØ0µ p¸Cn{Éyœ:•—šœ¬ñšÜáðV™[ƒÆÿ %%ô:fpü¸äÍ”6ôŸÄÞ½Œõ Ø›³¦·$ù%®¿¥—¥§OKÓ¦´za%Ø‹cÇóý÷~Ðe·ëÎ;™Vc/°D?þ˜ÜríZïùă¶+†ðô1™Õ(ÍOz‡œò¤€‡ À07l°û"B X]݃ôÐ]‘åïÐ%´¬˜¬þÕš«R—o¼!·Ü"{öØ|%Û¶ÑJðÛo¾ßi/@ÈëÕ“W_µù2._–§ž¢Ü>zÔ÷›!Z7zUû‹)2ë)Ù•SVV¤ùºgWèž ô8€uX¡‚5y(—Ïɲ§åPNÙ^BöÚ”+gýú‘Tû$*ªåºxqÛò Mâ™gh߶7œ5%EZµ’FèÖ1 ƒÃÿõ—ÊËÊŒµŸÉÖ¼²©ˆlýYߤªCÇ­­øÿ-æεØvñS9Z\Žæ… $Ån;’€Ú•*Eg½ÀŽ.[–¹*¡‰#hnµ×ê{ò$)îcù]DkÍúô7mRsYNH\ +JËÖÜûµ­ÿ°"‘EÎhÓÆRÊ YZd³ì“(h%¹dÅ«L• M,XÀ e»ÛwÈz£Ì´k¦y³gËu×Ùœ>³gԬɒƒ}÷qã…«.sáø~Ù|$g—%Å4û #€PÕ­k÷E„ öíc–„•É=DºdüoùP‰Ï/k KB¨šAÖ­£ËõG½¥Y³¢Kyøa~7h£ÐIµaëVž&öš @!±ƒ¬Ê¥ìÔú µ+²ä5Ù›S’ŠJÊÃV2رÃæR«! Ü=.ÀþÊÌ”.ž—…måp™‡œ>`é\a˺´ó.]¢W÷£<¾aóf¹é&º«ô¬²Z5Æ-Ûˆøx+‚¿ÜÛo¾AŠ¢ÝÚÌþÙXB¶ç“ÍÃDΈT™cŸ¡ܽüùAj*3‚õT#9¶Ub*Ëþœ²èíPÌFÓ¾ùfùôS;¯²J÷æè•%JÈ?hº’”Ú-õ»˜±v-k§L™bÉ`ÐæfHÂ!R´hpŒéâ™ß’!C³“KŽש"·Xp¡¡‰;ï ‰Ü.Ûa¹»Ç'Ö“]ùdÑÕ²m¡ÖyÍàÈ. mÎ- BJ8——4*âV¨ 5Xý駙ˆdc!DÜ܇ٳ­ïóÏY ×A ²e t uSeiAÙPXvg­á£Þµd,vs„-l¹—ÏJ\cÐsZËåË 0¼±¯½f'ž4)ÃÏrú4ŸÑÈáÃú.Ú«½nñ˜rÁ™3-²`ÁŒ¨Ûõë¥P!ÿ‡¸tAf5ãº]óŒ\ ±u«Ð5Ìç,œOkscøÖÁ@òäáùäå'wnZ¶¤=ê÷ßùxB³¡Øþý¬¹j×µí_ ë‹ÊjœÔöÕ¿u‹sç¤Ayþy;ÓÁ¾øBî»éÒÕ«³„”Î+Y½šN@£ø-˜>>¸²t½¢dÉtÓ%þ…JîجEŠ˜+ê¼}±Ä’MEåh¬µ>\y„)føúÎsϱÂí·ó\Ë™ÓUBBâ%ì ï¿§ÇÐçÉ{ñ"«?þÞ½¥m[ZÆ0ÂUWÑáX¹2$êק8}óMùê+ùóOÖR0“¹`9°+í ¯ºrY–´å‘½èqI ¥†))´T<ù¤m:)ø-Èüù姟´Î‹uxã µ² &PZ*hxMÙhlègžÉø;” üxÖÀ¬r(‡Ä´ÿÿB,ñ•¨{~ðÓ|ªVe:9„Øý÷Ë /Hß¾2j ál=p@IœÖÿ™3|ëVβhÅ)¤e×®òøãrÇÌõÀÍ ÁÁ{T+D†»'Êe5ÅdCrÎÐÁÙ³lÒÚ©“ 23öìI­ü†¸N´+¿Q#;=`•`,Š« åË—)#TÂÀ#v­–ù%egÙ3]éUÙÄDæqàð¨U‹ ¬½æÍIùþú‹R"))ä"‹pI³fIÿþÌ–½å2RpÑÎÉ!?-/"=w.Í !‚ÔK²¸ë_žl÷¥82óÁy¤ê”™ÉÉ .¼GŽ0Øéê«õj•?l©†îi©¾™š‹»ú¸ÇRyqŸÉ¾œ²êI=«úªlÎG趃Q .WŽ7¿uk²¸%KÜù,h//€Vˆ%ôý÷4Üz+¯ö¾ûäÃeÎ?ri½ M›¨ÓåŒíS$!Ÿ,¯ gí3 ¹2³A}†‹µkY‡çý÷3Ôœ_e ‘ϪÎÁcôhrZ ¹Å† ô‰ÿó†©À'FËsçhŠë×/Ë›.‘e5$)§$ ÓpIú€uµt){K=òcõê,¨2fŒ©ÀBð«0ªY~þ|¶ªWÂóž{h^˜7<€Í–,Iij8Bbj0›róh»/å_œ>Msb·nÊ'‚B„S>kÐĵ’,'@PƒÊÚÕ* GW´†a´ÄS<™Ù¨Ðç\yÓž’PPæ—•cÛô\’r@[T|â †òBoíÚ•Š¶¿Íøž~Zk  áÙ³'72„gãÆ$Ò~µ£²ÝÝã«ß‘KÙ$®I¨18~œFuƽK—¸†Á$Ýžà8q>ª+sñ"ý’veôlßÎ\ž‘#µM¸oupðÌFþýÒÎ¥9–¿K/äÜV¡˜[á/vîdøiíÚ´I6kFãÞî݆Ø?ä«Ýúö2Ä>¤ßõ׳’Õ;ï0l» ¯Þx#“ÎBíäL‰/(ËËÊ©ÐPÏÁÉ«VU’;‰ƒþþûÉ!½T‡HLdU%(S*Ы—tì¨ddŸ8x‹Ö^Ó®Ä~Ù2I=-ËïݹeÓ8;¯'x@NB²Ýuµ†.]üdÇ=P^xÁ‚qBPmúôáºæz‹fÎt¿Rî7øI¤’È)9Z¢n–ydWt.“4©uÝuÇù`ŸbL<5Ÿ®–)S˜ìc¹‹ÃZb÷gÏ2>$Ȫ–`Ú4iSR ÈÂR’³8p¿ÿž[rò¥—h¯³6|wåJÚÿ“ñ2DêÔáÑ ]Ï…L† »'^ijÉøßÒ.T‘bß±ïzœ°y3#«,9x Í|#K£äŽ…8|˜¥(/¶rL“¸|™~¶—p7ÿœÊ._±†‰iîäœ9Œ.Z”‡-—“$'s¹þ·±};#© €ßz« ÀÔžhø=}Úî+ó›ÇKbnùûv9^ª+,ðœ?O F ÿZ{c#Üs-Q–œ"Ë–¨KL¯ÙmÌUw`Γ J_ÚŸ¾€P6ìgÅÞ½4§”+ÇÝ=t(=;ª‘?¿©’­áŽ+W˜çЩEeµj4v[Õ©É;d] YVTl¶ûRþ­9p|uRcƒA ¨—•˜Hqm úõãeزÞz‹SÛ¤‘z‰õwå•ý ùßcÇH-þþÛæ«ò œ2 ”Í›3.èå—YR^pÄÿ¿ªY„Zª­ø·[7MUݬBêyYr—lÏ% !°¤ÇŒ¡o7!Áï.YB-xðàÀ§þùçÀ?ë2d¾_üÖ* HF¤³–ˆ[œÞ/Ë®‘Å䤓Ñ2>žçÑæ8”Ýû÷«¯˜ƒÁ5b„ –çV­Xãÿîž-[èOÇÚhÙÒþŽ6~aÅkl´ä}»¯C˜Q[©’zV;(«ËJø °J(¶P©©Sα¿ S;#q ÿλI.da¹?þÈ›c{CsìÛ'ï½Ç Û¾=…v¡G› ÆjÆÓOÓät¢ï¿goèGãÆ…hI¥¬Øø#»RÎmf÷u+gÖ­kê¾;ÇŠ¸Ï¦*ã(F¯^¬6£Û¶‘ÖÚ϶êW9Cf·õø†_dþ½-2X½š^Ú%ÈpvÚÝß|Ô(éÐÁækКŊ¹9:¯\á¹_¿>UEÈÏÀR‡4ã@\C¸Ù©ÞµÀžjÛ6Sí·Øµ‹ñ3;‡D*.øɵ×Ú`º?vŒG³íÂè¾r0‡¬êãí=xL>hsµyI•-Z0èëë¯vpó ÑÑ<ôÿŸ`ÄU^ËÚ eÊȷ߆A|Åɽ²¶„Ä––s¶jO¸Q ™x|Ãœ9¼¥ÚZKxNêU­júàBD-~‡¥Ld9BÓÁ¤Iê¯É —y„ºÃ†…–ÞwèIW(Ä6¨¸Põê´aúĪU¬–S¶,Bœm^<Å&A«ŠH²­ªÊÑ£¤“'»þÔ½O-—,±ã²Ü"ëé§m˜$¼U+›7ZTkÙ—KM÷SÆF(UJw¹‰•+™ö…CmäÈЕ)fÎâÀ0c"óX±‚ɧÐÝ ¤‡r Ò•T‰ºS¶ä“ý¶ö4Úu9:ÅbYuêØïàp`út:Xõ»V¿ü’á£6a‘,ºS6ä•}~æ–¥¢ô¨Ã[·RQùé§P1ŸºÅ]wÑ‚÷ŸG‹ToÀyפ ³}ÇŒ é‡ÛD¶æ‘m‹ì¼†±cYNÿøqþ¾e ËYtíB$4\W)õY³¨Ûý‰lAê%YPE6’#þÇ€IšÌA)7Æ‘úÜsô€c‡Ú›êO>©°LˆO¤X±À»`,ZD3Ým·™ÒèíÂÒ6’˜K¶›V¸T ï£Ò¯Qº´5Ñ’ñûÚc±öî%ñ†¶b.§HLÙ\LÎöyþ;Í>ú”ùßÿì<8.$ËÊ2²ìjþ öí£ØU¶Ó¦ÑVÙ°!•ñ0¸qºsëÇ7ZsÊC €—(Á,¡‰spAlw9‘CözöY«Âóœ 6×"[.0Ê]Z×àÛpÂvìÈâ¼váÔÙXT¢Ê³æUðˆŽ¦Ö`Uض2§bEÊÌ°Ãòå”'ÿa¬\ÉË >6µ×ÊøñVk ÆHJ1¦mÖÆÏõß³'-½Ø\™¡ãë2„†ÍèÝ›«Î®(‹c{eÓU2ófv· #FÐ*@ú¿3RS™{õÕì¤ A¹àøq_ý°Ã€eü»ï¬ vDÓ¦öä#»Ç/"׊씘On¯«Ëر¤Îíûôa"@(x|öîåöÔœ!2e LÁ÷gŽÉ²Â²¤†¤Zí¦|î9º<ÆêÕŒšÀÂص˲K²`˜ÿÕ'OÒ¤¬H}›úê+ƪ}úiHé ²6ý׸!¬¢¹VqEýK—äõ×i‰ré"ñÐCLœ´­[ÓJ¯‡ñøˆÕ:©ç˪²ªžõƒVÙ|ÄX'ï¿ÏÛ2rä¡ó] ˜tÃgvOð‡iÔˆÚÊÚµ¾ß¬높g® ¢.wÏÄضmýn:²èÞý?YT·®ŽX l“Q£x€ZiSë¾a¯ó•ßX?2ÔuױÔÂ`”¶+¨ÊEÙ²Öûv½tíÚö¬Kç%®‹¦^š/RJDYVãÂ…\êf 8ª>þ˜õF~S&Àmžò2²zb¹rúT€}ûȸ4°¿¦Š3V÷M³gúçºë.¯Eï† ã.˜9Ó÷@C†p,E-¼£[7yöY­3nØ`[MˆèÅe¥#ÞrHi‘ª¦¿iôîÒZ½šÁ Íš±ÇÁ à``bÿ=€9k.w€u Ò…ówÌ­ózÇŠiÏÜìG>Wt4£)³e#‹Ì„”yþy?ZKà´jÝšÞsÍÀáU²¤Ö­zú4o‹]Ï}j]Y_DN;ë¼*Y®ñX½då÷•‹ÿj­](MÅŠÙ}V[,1ц©Á4°w°¢léEèËß’½9åÐr“o‡.õÒK´Af*ÿ¿?mþíÛû—¿vây¾ùNg–{¹_?­3‚ͪ¶–{¢ֲ+/uDõꙪËHNf2øgÈæwhLùòaj˜8Ñ΀|Hœ®])qÀÕBKZÈŽ|rÒ÷2/«U‹í¼ð ¬XÁÂwàŸhNÔ–û¶|9§Óéëùûo–vq½_Zý²ìÍ%G5öµq`ëV×x€9sX·êwB#hD%î¼Ówd$ê¼yòÑGrß}’'6·?xéž{E0k–BÒÒv×ÿÌ™ŒoÿøãP)Ü1ënÙXXR¼%ÊÅÄzwæ‚îÝ50Üê:u´¶Q>y’·Ì–„ñ˜®4PïÒëØrÆôé,»m˜>úö¥ 7“wüÄZ£FdD½{³p_“&rûí<;ræt•„XŠ|À,3/J^š?ŸR¢^=W¹š;7cö\>üŽ³øxU4 !Ã_ƒ  Æ>ôKüièêWReÉ SZ.¸¹íƒñ±›qæø”.* &¾áÃi7Ðé§~ñE¶zÑUýÙ7a´ S;ã‹/(Ú¶%é²Å¦#k×2…$ðÑGiÖ/P€æ>è†?ýDjÍž–ó¢‹eÓ&–qþä¶\¿åN}óÍòÄä4`¤r~w`óöêÅû öf;.œ–¸â2ý –Ô¢EšBÿúõ òWŒ¥$Gç}ŽŠbÞ‡þD¹ýqtäÅ­{ެزEŠe¡Ñ¯¶í¶n•Ñ£É!ëÖ•‚i­…Œúì3æpíÚÅ­!ÀÛ- B×­#ñx÷]yàÞùJ•xmƒÓXåÞ ¸kB*¶GÒ*ƒ½Am±=Óáø^3g6qþÛ„ òöÛê—ü! tW‡wÞÑ ù\¥ õ)Í8sH6¨öºçÍ «’%)IªU#× kìÙÂÉÏ>ËŠ[åÊQ À ÓÓDG§÷Ÿµ&›7S¶wéÂܙ…٠tœÁ¼~=ujˆÖ_‚ ‡¶Øª•ýe.g!¸e¯òуA´ÔÆÑ|×]\–*°{7%é$Ï=gCóåK²´¬,«¨{Þ¬€„31v±mK” É /@ª@¶ôìIå ‹§ukD™iËntT 5@Qœ9SÞz‹Ê;.2²Ô§1TÙvw'€Ã=ù$+²&%Ù|%ÛGKrv‰÷Ø Lß­O/W®àZcmÜHGØ10;jí rUµª ‘cÓï“u…ä‚ö®—θ|™d_ßYûýwÚÂ"ÿ×?w®¼ð M@TB`Blúk÷†ªn;óñ‚½{i7€BÚÙ ·Äöí£»'¤»ð\a¤8ÿ;BAœ±üIÊ)‰qn_„T,S&Óa bBáW±{ôîm}½µ-[øܵEe`Ýx£ ÍÝ¿"I¹åˆÞÆd.iÒ„n⬫»w§3DbBÜ".N^y…ëºÞÀ*ù¦MÖ]™2€¤M™Bo~É’”œÐ œ _|Bî/˜0%i°¸Ä”si4iÖ,e{Ð F’âo/¿L3Õ¶mVLzá—«µŠ9ÔŠaºÊÙIÚ2þӌ-äPNÙckgsèw dï¾ëÞDQÙ°a(nÀÝ»™ÈpÓM,¼_,©ñŽ%—µSj(|øï¿¥eKjëO=ÅýŽ]¡B(¨ôŠ¨(’"{«_I•UåeV5f^ßpñ2£W/ʶ{ïe,ØI µÀøxÆï¹5§€ ¨ j‹"ÃvEÑ\rÿÌÙ[–¬uR`gA ÷ž¼‰Š…4ݾ>)΀@øóOÒª«¯æk¥Ë{ãË/-M'ŽåC¬]›·jd•'cÃNÏš_¦I r"» ¾ÆmL×Ò¥ŒüªUKoëÍ’‚™¸2Ètm‘ê Q< 50ž¸"ËÊË[ >à|/WN~ùÅ÷;W¯¦ö´Þ־Ϡ”~HiP¯9‰ŠÌ£‰¥sgë‡Õ‰ÆiZÁÿ`Ë¡lKq 1‘‘¨ï¿oO¸Ñš5´Åõ{‚]-v¸Öà:”LjÊZk¬?KÏcüÆR?;egÅ„ t¢i{Ö8Ýê××ý°âZÊê‚,àfÀÓJ—ö£VÞwßÑk˜ÕÈ©›6Ñ^W¼8Å[¶(œhåJlÃabâ47Ž§P À<­ÒûÔáØ1Òcïå¯Ëþ\r(ÃǾùÈ#éæ¤$ÆZ(n•+õ€ '1ÂâÅÖ]“WåsÍ„XˆøO™Ñ“¸Lë¤Îøë/ÚOü­Ý½;›âéL¹Z¸Þ(œñŸ}¦#¯ÇAÙ²ÊgQ‡/¾p Šƒjо=¥(´?[;ó€ÐhÚ”öX=2óâEFºV«–ÉÍ7ãV‰+i}#ïxì± |cÇò¬Ñ†ÇgS82‹=qz+/9ã?–ŸíXÉ èpíϘA;ûM7±©±Î¬«¼yÀ¹nZÅŠîAÐògŸeT-ÎP›bíÚQfª®ôrð ;-Z¸zqÎœ¸‚2»‘ÚÙ]°cM(—«^]ŸÁ诪µáÅE9’WNÑËi>œ^T—†Mæqø0?TØ®W`×CKºå&¹LœhC¡{,?°²p„ÏL%è–:Pl†2Û„‚ùÄLnR½t)Õ«þýÝ[á¶.‘CÙe»Þ·€ÛàêLOÃíºûnFeèIJ&²øjI,rµˆöÃdÌɪUTñ6(…Ž§b9ožméÆÐ8&L°gê eÜŒãOßÁ6C§º¯3pJB°ßwŸªÿí·´ðüó·÷Ì}—¡Ñg5†fZC™ò׉=òÀúá~ý•±:‘0œ¦Ë»ƒêt«Â–Y1~<ã7,IÈ=švf ŠP$6$Û··Åž¤Ùiûô±ù€Q£Æ|–‡Á6Ë–e¨sHõ,3pé@÷ßoe¾RJŠtêDÍÅŒò;µ’¬/gÙÔf0w.kÔûe¿1ƒ[Fµ8z”¾so–¹$ª›¾1}:í$º˜!Xš6µ`¯ä¼ómªÃ‡‡Dâ‘#v¬‰ÛêÕ¬Tyûí6T›ñ èæ­[óÇPb"K^àŒ0ÙZâøYŸGbÚZ0µy€.úUÎ]g•à.]¼õ¯±W$¾´,¨¬qF'@Z–,iñé€e|Ï=A9€ lú‰ ;‡I-:Z·Þ<À1@œ6½NœÈhÀ6m˜«R½„<Õ ò\Æq€ÙßÖ«Æȱì²KW¸Ž¤UË„š`²tÂ4õë‰(X·ŽÁWê˜ËÀš¬ÞvÖŽŠÓ Ò䨂BìßÏuø×_|6!Q‚µk[µk-fEÊ°ˆ÷v`Þ¼`-ÿçαtï¿- „ëäå—ü8Ž’þýiy,Lq^[YUXR5††‚<˜Ô6Ôב°qc. m8/ÇsH‚->-ÃÆÜ™ŠC÷_>wìÍ^½xUÐ&Bjo:P¬X˜µ{{â kT³íÛ©Þ}· %h¼àøq^Rß¾~ðôiv Àg®Çr%U6•EMüxHJ"½1Sà£R%MÛ'.ŽÙÓ: 6–“YM|¿ÍrìÚE/Ï”)jgÁV­RÅlþÌ™Œ|òI÷uÉBà½Sí8ÝÃÑ£Ôã,ôwEýëí·mh:à ÇŽqÙ îÇG¶n¥ÆÚ¥K°AƒG–’ílqM™T“!F5¯ 8Cuºb—½#›óÈEí){öБí× Ð#ðˆ½ŸwgÎP±*_žíÃB;2e&\0x°¼þºÅc9ÂòjÕBˆj‚ó—+gÖþ3meþH•ýÚgdK~9ïO#ò`páZ}V ÕS÷rî\¦ùk‹ñK^'‡sʪ4MçNä›nÒW“ ‡8/ÓÍšE†ðôÓºëA†Ï>³¡ê~ÀÀƒ^·NÉÈ“&QF½ûn¨P͘ÖX´ÈÛ{pjü1s+¬ì*ëJÉÌúÖ è '²vŠí¸|Yî¸Ckéþ5å$ªŽ¾é à80:Æê„áÊšpéûo‚Xæ²X!¡Ù'+V®äQ¥Ð÷Û·göSˆÔUÆ£ñ’Exü8‹e@… ¼ãŽXÊZF{uE!b ã´Ý.4j”ÚÕå‚-½ec>9¯½ñÔɇ²¡!5Ô·%2í¬„†5nlYëX=ˆgŒnXLXC£:PÍk®‘¯¿¶¿Û#ðô@‡rhvåÊòÞ{ªV~ìsWJÉÈnî]ØƶòP+®»N¡¿ØOÈ¡\²BcÅx¿üBåWCa·1‚5Cïþýw»Ì/œ;'ùóëë0NâÖs u·Þʲ¡Ðyù•W˜ä|%F­B¥9­ô˜eº7ìšš5µéuÎÇfÍôM·¤¡Ì¹NßtbcITdy›Ç /ÐÔ³'Ãü-:¸óNj»!Ž_ÕÚH’ù¹ç˜/c{|ûåË,úg$žÍûªTÑQÝzËXvæ=nE33˜2…ÆX[B‚/^dðª6—ßÆ¿YÀmŸ^qqèoïܹZ'ÍŠ¤$~—+çFi #@)êm!6´áq÷ëGcµí©”ÉÉ´¬~û-­O8 µ©T±Õei%Msd6hÀâ]úÅÿàƒšæº|Qâ Ë¢Ç5Mg÷JŠíýh6n¤A ];š¼Â«›˜ ºwžoÎÀ­®VÍsÇ?ÿP‘:Ô†©–3'­¸:ÓNî”ý9eý MÓEG“ù ôUþº#­ËÌI]†A浑Lðœzõ4íYÜÆC9äˆÆBÍ—.1˜öà%Οgõ­tÏ$ñ*Š0J3”´6>žë3Oºrç–lÙ<þäÏÏaÌV¾š?Ÿ9&Xlø ËÛðCœÎ™c8µÅÝã £FÑ£jef€”//¸nçýûédôžd9æÜ"KuQ£ X³TRSÉfçÍÓ1uÌxXÓ\zõâikNœ §©Y3o†¬½{éT åüq,HÈ!C¨`BÑ+P€‡O>É|^üÑ’°Ã³gÓÅé½÷²ÉZ®\”´%KòîuëÆB¿J‘lÜH›|Hñö)S˜€ƒ/¢_M+„§®Ð‹Sfê4fÞ*‡sÈ6-iƒ`Ñ8»5¨É“'“€éÁšäbv¹ «B¤­R,!»¢w -kÖ”7ßôŒEófHLÃ5ÇÆ’«€–(A9ùÒKlWºiS†±Èd‹œÀf‡ÆîáìÛ—'¤ NöçŸg3ñ¤$·×Ýã  øãÇ[?rJ ã?A±vîôö¶ž=u÷€ž÷¨¬*®i.¨<.éº]»Zq\SSª¬¹Jv€ìA>?(¢>†vÏš.µµ×tÁñãò¿ÿIïÞfßÉS£†ý¹3 rÆ1]¥X1út í'MòXGBI‡e,  ‹Xüß~K}¡xqÚ¬@GãâÜÐHÃÝ£ÙÏbø eÊ°Ñž…ؽ›Oêé§}S}а{îÑz”œ;![òÈ–:æ2|1ÎGÆûïSw«[—É}&ûnxǪUPOØÃÆwds!ö¡€äÐõ÷ð¡‡äƒ”Ïâ @àí½zù÷)„ví”\O€Ëa7h@YÔ±#™¤ÝÍ®Øøàä ‘7ßL5óÕWisHÎq÷xBB÷5ÔgK0o%°ùZß[·òý:u™Ø>²«@ÚÆW!C\Op¨*þɤ',ì×^ó]Î;žzJ>ÿ<¨LâÂ9˜[Ö[z°zv 4m‘γ…òøÙg~Ô¤T[ÕSIK ÿã*ÝE‹²ûÕßûWK|éÆ•]œ9lÞLϺ|y–Y[½:´Ü=n±k3΂,ÄŠ›·lY¿Ã§±5î½W«b¾ªkÞjÀ©S4z¸Ä®üè#Þ®»ï¦.€jÒP¾°MôÉYø¤,,­c"øjPÊâãõÍèVµjòÕW~|ï^>ñ9s,½&wHLdÕš%辇˜)Ò5o^«¯,P@zC¡€Æ”/w„Š†ÝbÛ6rãŸðãøv`ÑЯ+Ëߨ‘Ö”·•ÃdWnIÑýòË䙞Â9e E!ú^y…*¶y@Á¸q’_8“,I9eƒÆ›ÍšÙ“µwò$ &8È‚ÁŒ”öÞ­÷ÁÚk‹´îB`Bl 0LŸ.èÖMž}–%¡‚á †r›pcˆ÷Z@©¯^ fÀÆ4œËXÚê’ë iJ…^·ÎT{ÜÞ½ÉóﺋîŸÉ#à¸cöàö‚ÍY%XÆ£ý0È6% uýú4<Áš5­1S;pñbº_ {í§Ÿ,ó.á°Ö¹ï¼«ÚpQmÝJÛf‘"”ŸzÖyX»–Ñ~…G‚ á#ÁWø9’µ1µ“\ÑWöå”KZhÿ}÷™-žšJ§póæ$œ;{ ”ýí7úD4àÜ~9˜C¶ë¢—'NÐL¡¨\¹Âd–öí-[mÛÒ¨h ¿þšmµ±0æͳ8:LÞÆ‚„.Èê„:r$½ÿ&n¦_;µÒÐL•?ìî?äs\±Â‚y± \«Ç<¶¤Äµ×1Ñï¿ûí‹ç¡Ct⮂ÛR©Û^|Ñ}Ÿ©ß~SØZÓÕ¬éÍ­l-–|';òÈyõ-<ð”Ëí7ÁÞ™7ÚYŽL刊R»›Na¹u ÁÜ¢Kù5èo©”ÂᬬSǬ²î…HÔ§ŸêcÚyóÚïê ÃÝcÞé¿jãî¼3ØHf ÙõÈ#™šã/]»ò= ™;Ò¥ nî\+ƒÿS/Ê–\²m”ezh³ùì0KJS­C¾5àÔ)¶`þñGoÀžj׎&ÈLýÀùk{{hOîŸ8|˜[ lYÀC{÷òb°˜¯»Žj‚ž|œãÇI25´HR/ËÖ²æSåY•·iÅ#6»3°Ý¾ý–¦ P…¾}­á'+»ÉŽ‚ŒcÿX]:Ûƒœ<û,㢵aËr¡eËܼ4y2ão{ôp}¬Úðúë,jd#6oÖ‰¹x1Éù3Ï„D[:¬«9Òû˜h$@ƒš â­~[6Õ1QðøàÆgzÂòå|µX1ìMŸîb½í6Ó%–•ZêØ`›Ü|³îŽ8Vî¼Swù)Sx.8ºx‘%תVå~·ß}çmQi€%íØ@Hžžþ»ØX+®) àâNÞz+“Ån¿]ké*lvÌK÷©çe[.Y¯1õ/0€ÞcÇùLÕÇc9Rjצ›éã–&-Ë”aÛ.SX÷­ìÌÉÛ¢#FPÓY*vÎòu©‹^ЫË•–„† =ù¤õáLþ7äþûm›ýüyro«¢+gÎähŸ®µ6…¤$ú¡žx"]N⣫¸6@SÓÖ~qF;™ƒŽ‰‚Á¢ETºÍË–uëh Þ½”z¼!-ׯgð¬Ña P!ÁKËËÌ&V]µ7\¸@Ù¥ÓÑyò$Ï»’±˜zˆ ß羶ªDXؽ›§©]°¼ÄÜ޽̭kÒDkE͘’çš-'N° ”fãp›6šLg&KJv9²PÇ\£S§ÀêB@6:P¸0«Rg`|<°«ÌÜ»^Žg—£Z î^j>…ŸzÊæfÜû÷󠲫“[€ŒåËg[¹ø€Ý=^péKÓ@=×cë<Øý)¼aô¾}:®ÁÀ¦MüÖ–ôñˆ_DjˆT— åd‘ÅTM7¡H‘ÀÂ?J–ÌPÆ…§¤NlßL˜ÞH¢o èýÄ¡C,ö|½óøázÆõg9­í¶ÛÒ«¡êÏ—÷‚[oµ§åÊ•\Š¢@¡¢‚9VÙ»òÙgéoõ”øЯ5:ö'žP\ùí ‘y +Zÿ—$å’T›š¶ûÄøñw7 ˜Æ1^° ëòÌ$B/ž‘=9e§=¢KSщVg Ä”%u(åõק/æqã˜È“f^ ´liO ,¥„´¹bEÖ%VáàÛ½›eµ¼·–€¨¬WOkÖ9v»µ•²¦!eÁÿ$¦u¶mYÿìÓmfJðxá¿2 ì”Ûnc-À¢­ZÕ›c ·ÚöÒ¸²‡Nnô^ÔÌùß?(™¹e ‰â›oR7êa©Rú<}±± ØÓÐOvó<9žC.‡Œ5^Ò‚‹S^áÜiIÊ.¦ÿ÷èQ–øÃò¸õVÚN-tOíH´ù;~ý•š¯-èÖéá>í´à󪶗ÃÔYÔ½»|ò‰¾éèуI^Tñ<™zJÀ]Ï€Ÿ~¢ßVÛe?r¤Ž‰bŠÊZíuƼj˽÷*Ÿ%ê}ÙPÈÍß¡¬=õýËO?mMA¹wß ª4¨_س‡‹Ü–Ž0PÁlMs;S‡²×¤³¹-8€Fh7`æž ¨éõ×[ô{硇oHê/fÏæA¬aQ-|Q6W>‹y<ÿ¼Ž¡KÊÉâ'=¾zü8µË[ná#4(ð £ï°s>µR<þ¸k_x=€´¼ýv?: Ÿ?Oî¡ÍLá/¾¨¯íĉÌ"´XÃ+šjîUèá‡yšXÒZbçNZ`´5kê°Ÿ9"‡rHRh&Å¡á,>™('²Ë1ÙÒ¥l–Q¬ãcçÏ÷ûü–Ԗڃ¶R%2µÂ þö‹ß·F'\³]À£Ñ ùc{çµO?åòðîÜ\»–rõƒ¬LÐÆòÀÞуñãéYÓ€·Êì¦:&ò‰¸8š\Tcé3]Ö÷Ÿ8ÁŠwÜAÃW¿~fµ¬:¼_OèøÅ‹,A©¿¼$ä@åʲ‘¨(fÒÙ•¢}ÜÚœnOضm16žùÕW™uå)¦}Ü8r•ÚŽ{ÇÙ³ŒšðYBÇ`ÇAàkÈÝ8Z6äS>‹ôî­#amq‰ ( Ò´ë¿eKVpõ~C;¨S'° ô_}Ž ÏØbÁtñƒ¼½í6ÝÉ›ÒR “¾û¹ê*öb0iiéÕKk†—µP 1¹Xæ!BßxƒÖ'E­%~ÿdCÉú›o˜¯¢ûsÉ-}l½£vmBQŠ£$9»œ ÂK{ú4Ó´ÿ÷?Ðt×­K§¹`obYj(²°¶,Pï›öhvø²ª ÜE?!K®·f¨µk™.T¢ÓF¦LÉ´û ¾Ê”ÑÔlKg‹ÉÉÔÄ-©ó’Bc kMË;ƒÁAƒ!ß²zîn¼ÑN4o^zÄc‘"\  &&¿pô(K²UÑ–-cthß¾Ê ´._N“uFÞˆJ¼ýv`UÎüÆ_ekå³xÇر:ìÃñEe™¥ zçÎ1\ Ú7$ä‡2¯G4FíÚEzi‰OÓ$°¹~˜Z­Uؼ™_aþ|kFÛ¹“Zp…  kÖx”nÖVZ;~œMfÛ¶¥—°E ùûoiÕÊ~wOV`ÍÕ¶¯¹†%ˆõ੧4í(×^«<ˆ‹jo.Ùd«VÞ¡ƒòÞ ‡×Êièãj:¡lÚÄ´äFXæC;£cGšt¢_?iÚÔb“d x`0µï@æ±x6L¯`¦øC÷îl ¬ R8C¡üæÈ!/¿Ì…R8žÆÌ|ù4õ3°w/ž;œVºÀ,¼Cf×S>‹'`–*¥ª…®Qm%¶¼Ú) c¾þ:õtH€nÝÔvt'­Õ£éˆŽfH³ B Ùí5bpæ iqUã“&ùáB÷SêŽÁ7jßžC °Ùàí½–`ÏÆÞàÂÞxCw9klèËðÇt3©ÆÚa²!¯òY<{¿fMõ³•¥o*ŸÅh QiTýhЀššŠ&‰Ø†Ú¢¯%ÍÈ ¹´d‰’Á¡ã@õK‚%'ÓxqÔ¬Y u”F©Œ:ógÏÒ{{à Œd°±B)°`ÕUcÍ€“ß}·Ön†wRÉÄ¡ Æ¢ºÈê%9CvÚT¼±kWµSJsÙäLPUã|cËš°<”iüx–¡Æ¾~ë-+}ÙЧ°ü´µê3L—ŠtX§N±Œ©—†æ`³Ìèsgš@ÃŽ ›ûdu÷àš‡§ñð±Ç¿æ`0p =/Žú°@b"¯Gg÷m$üYCÖÛ¼jõ˜òYÜâñÇ™ï¯ ^‘u%ÕN!i© /»«±‰íÙ£ÍàŸ¿übAhèS½{;ˆyôíKWµ;´bÐ;]œ9“°Ê ÅÎ¥K´ã):qÚ´qïîÁIjˆúW^ÑW’åÜ9ºSk×v“C‡ÓÔWiyCg€db ìÞ­|"œ ™ªC|£zI|1µS¸¶!È’ê®ôó¯—¸Öj§À¹ñF&Tzçĉ¤jÅ‹Ó7±zu€-êwBbÀˆ‰á:×Ó—pÚ4׆æ9ÂF½•+[æÛ ²Ä„[ìßÏçëECT‚C;þûoëgwÁ®]4è½ø¢GéÑ¡MšÚð曚¢àðpÝ·‰µ§Ž²…âY]€vY£†Ú).^ƒ9ä°E±+žÁR¥Š©wâ¬7¢_îº+ ÆXrª-€ŸàKYž4çPü Í‚ݽ»•Ö`ð@Ë{8JÚõ›1ÆFE‘*ƒû©;‰æÌ¡XönåÀÚÃ)?nœªkpx±bÖTƒ÷Žo¾¡ÞªKKÉ í}ðÕT–ƒêM_}•õüÍ#5•î!Y¥8çK+hÀÃí×Êæ­·2HÆûÒíߟÁz€¯90ÞîhTª… é˜øà%a*:ÅÝ™ª %ݪpëS§rP·®qzД_xÁšÙ}_Ù²JZ[º Q#¨(Á‘{D>—ýã$)§š)<÷­xqåö±d§âÖrà‡AFFAäΟO3]Ñ¢+cOA€èq³^¾Ì”y3nkˆ'C(UJa¥ßèhëS=¹{¼"ŠF½zl„-[˜ ½À¯ÌÜ3gxBY•oåuêè°ßŽÅ:9ª±-ìTì°vö…I»_ÀHÚ.)ÙE»¡[Yå¶>z”¾ÔêÕ©‡˜‰'LœÈR zðÝw¬~¯Ú3îØ¿øšøú7Ü ÐÞ•œœÖwÙ:$%ñôL t(ÑÁXÆŽ¥ þ—_ùì´i”´z ŒM«‹jàù)¢<³cN ‰n¦v g€À¨6‘-ê)[ÕA«²¼sL ëù`S·mK¢•šÊÞ%³fY<‹[@)ÆÖ³¥ÒΑ#d¶X ÓÝ»³Ë¶ºâ`W]eeÞ±IwLJ‘;eŠßÄ-êÚ•‹pÕªÀgoÒDS*DJ #“5¤?ú¨reô‡²\£³sg2¥Xx›¬~HíЃÀ…ÁQÁÊ8v“žšÿ¯¿ÎÀ'ýÀ·Ïùè£tf{éÃþÕ54‡Jn•}" ZmðqJÑÑ&~µþÄéöðüQAÆvnÚDˆïÏÛo[YÂņg—v¥HNdÅÈ])$·ßÔ™hÇrIj^‘ûDzŠlW2Å€:â|žzŠáÇØMPW§OWX òG[œ§[·òÜ<8ÓA8ñGE&¯6m¡snàæ›­jýz8ÐÔ›Öo¼aÍzxí5MkÎeÊ(wý$&Òk©º|ñæ«dé÷j§0pö¬.¬ö¦L’SÙ%õpZ@/‘Jf¦L넧“ 4OOÊòðÔ¾}5åþ|û-3ëUã½÷X¤E)Võ”ê½$”¯wÞQ;ÅÂ{dñÃj§øë/Ͻqc÷Uþ.\`°Yƒ¬Û½{PMv Ô«'#G;ˆ_HH Àg,.´NËKL¯\É[<À-Ut“Bqà n"»Žåé ½FE<Þñãd­Á/$ŸÀùrÕU -PŠ ”'OÙu4o®<ß3¾ˆ¬UìTêÜY† S;UÑ¢>ø•QßZm£F$NQÄÅ‹iÓTìÀ¡Cô•|óïw‚ÃßsÅI"ÉÉ´l‰Ë—ÙÄVQ¼èöí|¦Î§ Ø8¤è»ï*|LŸ|¢)9¢eKS>€Q,¨¼ÖîŽ<²v’Ú)ôpò$M=jÅÿñëw©Æ#('fÑ•e¶â‚̧N±¾–R2³i´lʯp|IsöU«¦v ú×?ÿø÷‘={œrrß}Üef ÊAº^½¦Ðe;2³Ø¯Øøèh¦ ZxBAÖYò±Ç”'Gÿõm¼O?ͤ:ªÄ@¯^ÊzJZi¨NüiICó¡Cy+†%Ù=^0l–± k@r:·™PŠmÛxªË0€G©¡B&¸™êšŸë Éòá ÇðAVƒT‡ä ”ù©*wt´ò8RC&[ÞD )‰äZ^­ZŒZ9q‚Îqm a!™[µ v={èn  ý™ Àp4ð ¢òöÛƒ½O8ž%×p²@£t`ÎÊL š²úõ™Þ®X ªÝXÐúƒ9Í`Á­2ÏwO,·¿k©RAµ¢ö‰u_ÊŠÂ Ç—´&ݪÛÓƒNÜwŸªÁA8gÎda±‚¹ •2%°å!è,‰ñ^¸(ÈF„8&ªV ð³/¾H#¶ àDÃYÖ¬Ï2@7ôQ%“fů¿ê˜ ³Xaë‚U«”GcÎN¢*û|×îÝ´EùÍv± ®º*°ë2‹¥-e¾E¹½žÐ²¥ò²~|@+™jÔ­K$óŽ;¨ªëŠeyÝE£ŸE0É rùòÒ–îÜ9zaTô2‹‰á¦úä÷ß :ò]w)“1€ÛR¼¸ìÛ§v–£GivPªû_º$… ©m÷¶þGÙ\ÀËëXhÐþü“‡C¶l~R- i5™§ ùÂ`JJI²¤•ÓY¾\íÛ¶¥§v^¹"³g3‘ܯ–~áí·-ðÀ5·i,ÏŒ]Oœ¨Ä[1d¥Ç4¯¶÷5ke¤§>žWß¾ÊgV½Îq°ú›çN'IJ6¹˜¼±t)-o¼ÁÜeЄüùؼ9“5ü‘ùm~‹­E Ë/96’_)ÿÀÆ](N^ µV>ûÌ5ŸÚÑ2‡¹U$*>žÛÜróþéÓ4ô«P¿~ n5HKk{¨¥¤0¿›ÊŒ1ùµ×ø£qqÌcR=¸ä”¢[7«QŠ½¹ekÆ:|õUP|õí–[·rŽ›£6‹üŠœÉ.üÌsñ S§ÊCŠËlNšdsÄ' ££Ýüämî\Ö..Z”uŒ¡'Y}½iSUµOׯgÜH厣¢øí  ùüÁÛðf¶láŒùCU¢ aRm4S\†T¯®¼àVšêà¢ñã•w+ˆ+#1oòAŸý…XWDZ¯®Rà´R]õ•WÔÞ%IKU._Þ‡$„ê÷å—dq7ÝD…10 ¤ ˆŠº4¢ß皤¯9Y¤‹>}|×,ÂÛðf‡äìÞÝʲÆóæ1ö‹/ü;’ÖäýÁ…©93 ÂJK~mÞ¬°Ê·…÷ʺþ}z;NÞ‚}¼­AšËÔaíç²¢¨Âñ%­rÎ,¥¨ZÕOK‡ÿ4Èl¸öò‚é=ÚžzŠ¥ùÌ#5•~%Õ¡#Ø×^úY8“ICN:ðÛo~ÐCrfÏnÍ×Á]íߟ\qæL¿?‹Óg„3ïU„½{i}R3«ºpååË4#f:°Kß’¸küûNŠ={|”×]§¤¬1m”»ÈUW9p€JÕ¨WÏï2;P!f+W¦¦6p © c8Yn»M¹1Öhhž•ømÜHç"$±lòæ;†³ ºèéþâ̦Òרø^€¨àÀ/À<êÔñx÷¬ÂË/[VÌÙþ÷?ÖãR¬½}ûä¯ÏåP{ÌÊ0ïÍ´©R¥ü¨Œ‡ã£ti:PƒÇ?(8‘´æ ™JûµâæC†øø¡¶r%Í/Ÿ|BzP«õ¾bÅØ] ÿÅ¡=á ¯Í¾<².S)ìhiÆ[Þ}—Å'$-/‡ƒÙ;Üü{îñï²ý…êîê8§^P\ÖôRuYl4 ‡ØXÖÄÀZjÕŠ½€ôûñÇ•XvÁ˜1ÌúÄîƒ$7ihØЬiÂS/ÝM›È4À½7†€ýè#ÚùXÔ^ Zuèƒx²*¢ôCÄ[pv{)°Ÿ’Âp C<âçŸg†N^PCè “ ” óÞÃ_7^-ó3 ¤@í(R$ùj¹ƒXŠÕþøC확ÿ\6¹¨²[h—.®Í -GáÂÁ&ýy‡±,Ï}€¸€x¼ãš©ûô¡yǪêú$Î0$–i“&~|jß>³¨üž¬y]Øh7ßì17[l4ÕB€»¨nõ"ie?U{95RK Û–)Ã_°ø¡€Ì˜Á]Œ½Œã²B&|Ýt¿&îçˆL¼ÅªðW3Zq³ü“‘Qî-‹i…$tsS:Tm É„Er,§Âñ‡R[9O§­R€*U²pšBýÁ"¬\™y+ª‹ÞÀò~ë-4âh¿ûnëëúB³òÙKwÀ*øYƒÏ±C«W§XiS/½V݆t½cGµS¼÷žõå°$p~Í›Ç=¬œ9Þ†e‰gÔ¸1¾¢;¬Y¢±åŸZŽÿ•-ëZlÕ!$¡g*dnÌnÝÔ&[Å’-EŽ/i.r¥?ÿü£Üû a¢ÚF Æ…5ÙU®½J{y`Á?÷ã— ô“úÒ|£¢¨xAã7Ά2nFc,(ÝÎ…Üqd@qVT©CÒNðß~S5¸øRJ1vl°™‡“ÿÉé–-©(@±uÿý|vÆY6a‚ÂÃeù+²ð:Çÿ¦O§­ÚÈ»…z†^ä_É„SÝ,çzúi÷ ­Â¼Î’’²<í§¢õãƒ!€X+ K8Py5ªGáÁªX™ŽÖÀë×3«Bãá‡y誸{:‘38w[¼˜{ܳþ i  ·ÂæñÇÓþû 8A#†É î‰95X%Î'ŸP(+­cùÇÔgU›ßŒ-`lØà‡;øìYI¸Ï}úP¤Ô®Mã~‰iŸ}Æ—Ö¬q5)ã{™†ÊêLÄ2¬Ä2ãÁ3â—ý²kЀ5¾ÔaFcY¡RÙܼ™†,¥xþyå9>PùUWmmÓ†vrg@šÃàOð[ ]ƒÓç’•#ŽAÎéN 6¤¥³=29™Qä™ †ò«—.ÞË-Ä5kª•3òo^ÕNÐ?¥U’p¸@`:×ÿ4ÝaûvÆö’nr,_žÑ\¸½ ‘ï¿ÏbÔ11¦Î²îÝÕ6`:°Hvæ²xÌ›nò»›¡_˜RCâƒîéàP¯ür(°¥ôª±ê.'Þ·ð–-ôS€±MƒT‘ õn¸Á#“lÛÖ­_ÛS${b"ÃÒÝÐ;ïô¯šnBç¨\Ù²öCÞaŽÃH) ¯TWüÀ“!7Ôj·-h4ΗN™‡âì†Éq×®MŽß|CMG.o•V÷(7óf–‘m)ÿ»ï”§ÖÞ~{¦þ–\ð}‚¼ãŸ|ç‚øOEt÷½÷4 >Ì "/©šPÊ@EFrù3´7Oßë×g1ÈÚ¢ùM Ñ ª:h…¯êæ -q4(ÅâÅ D´gÎPkk5Ôj ~ÕU’;wºZÝ·/ëϬ[gå‰3e CÍb‡$æ¢)ÆB¨˜ ®’c*ã Kªn«ªºÒæ‡2®L)Þ~Û×ÞÎT¬ ã<Ä‹³Ò'žzŠsyð5׸T\üóO2\Oé­®!æ«m@¯ìÕ‹Ú¾a´Œ§ ;k<¿å0Êð*M Ãf=»Y€ ƒZmDò€oà”Ä"/P€~húxú?ÿLµzï^òIuXµŠ&…Ø%‡ò[\xUi[Òå9@Ž£Pu ,¤`2æ|¢yså%»ï¸Ãïìcì©¿þ¢W„³kW7¶¬¬Àƒ¸é&S ”j]æRK`fØÁÐæ%M±büÉÀùó¼$HuŸ8uŠÛ¿víL™’´ª{11‹U;îƒÏP#±zÁZqß}—‘xFƒP VãV@/ž=›jµ[χÙðÄ€pè/C!’ål^‹«¶NïÁ Wµ^¿¾Úì]ð+¥‡¬¨¯"iMÍÔåp GS`±c½õ€g¾X:ÆlÒÄ%ºN³f䃅 Óªjä ¸nY“ÅÕ·l¡Á­cGW“,…œÑPV¡„ÅMð£PD;tP8¾¤En[˜ýzà€|þ9Ï)¨ùß}—¡ž@ù«õŸ9öjÔÅ„ltPJoس‡bÁ‹Ö üÑG$©ÞK‡Aœª&™Û·³Ã…%0Zvöïϲ  ‹ø‚àóx ø"|nrTÑW(¼æ9I-$Õo²rHµö•áÃiÄIƒG`4ÙTŠð˜ÀÍR9eƒážðLýÀpæ7 Ri^0ÆWêQ2¦PWpãØ1níœ9éf0€‚ÏàҲʶի)$ÜÔJ{Ä ÎIŽÎز…î ˆS“ÏKùVõ5v3ÎaØX Q_µ*ïÈ 7¤G9J/˜ª‹M¸ 4åO¡¹íoªï?ج¿fO¿Ð¥‹Ý‘è¥ÚB ©rÞºGðÐCj»C`Λ§rüð8á>¾_ñê—.1iÜ|×oGÇ[¬¢ªUÓ™¤ÙûïSöZÒj÷œÌü,\±zuòF°GpH0IðÉ©S邬6»†°7¥µ=GR[ÜfëVš1ÕºG€E¨¶A6µe½%üN¸@¼zfxkBþÉ'éy> !F‰•ädò½€ñ=ÊÌÁ_eÁ“víhiÄý)UŠ¶Ç瞣yjÒ$Y»Ö[ú§¿P}ÿU'VÄÇ[\ÉE«úë†Kõ£–q`3„¹Àù?¾Çlc幑ø9xù˜P¡$š!{§Nñý¿ÿž)s°hQnÿ(dÆ£/;äï,^¬6uJA¸ÇÆ[(0ÃèRÝââÅ°š‘ñ3ãúëÿõÃüýwúøÆ™ RqΊsçXPʾKKÖÛn£ŸÈ‘9è¶üH¸ÝWD’}<¢Ú¿q"ó_¬YCæ áºZÂuüÒ¥ÿ­øY!iLG‰7pË„–ùê+ÚÖ6dáüù™ãÓ¼y -YÃíþØ0E¸˜ŒIM)Â}µ„ØøŽjÆ8ãÀî\ÍÛ·Köì’#‡Ü”MrfçïÆr墫ºI¶6øæöGع3¨T‘»?¡8E¸˜€cdiv`1Â}µ„Øø.qô»v1…ºfMY¶,óûºwçÈù²É¥lR.¦"„Øýñ§NETrŸX7Rø\ª[Ԫ屃U÷Õbã»­¶ñ×_Œ]w©„Þ"»Dÿ«’»©ŒiBìþø kk÷¹E¸ß¢ˆÀt xqµQ»þ«ÅÆñSS©/ϘA­û…è’öüöéÓÙð9†ÑòlòVÒKCTB™üqÖÙ°0Y/Üï¿ŠÚ}.÷[fÓñ£ {¸òÌýð_-ÚÆ?ž®ê‰<ùÄéÍ®¿ž©1o½Å¿§’Ïm;Ž³g4Ë Òp’ä?Î-ñ—Ù³™8vÏ=ém†,IÙ ÷û¯´vŸp¿Eá%0•®+ÏÜÿÕ¢hüãÇYSâçŸ9~³f ÌŸŸ92­[³à98ÏêÕnë|Æl ·]˜Ò¯ôÐ!êçË–É€|ò}ZœpÞ¼”§cÇÒ!nÔdÇ)ùÁLÆX<ØD¡vÏÓû¯m| SD¦ÓjS#•gî‡ÿj ~ü+WØeÏñ›oXüÒ»”ÕªÅZëfŸÎPÓm‰&L`vÏË/³Ù…–?ýÄV 'È‘"i­x!‡Þj½z1HÛá‡Ê?g£Ðq1Í›óè   Gèß{Ç×Ð0"0¸”S†{hDe ”gî‡ÿ‚÷wüÇ3êÜ‚.Ö¨AͺlYZ»t¡Ì„ätŽrŒŽ 9cé=Î2UÛÀ°F‚ÏÛwÊé éïnÑ"]£‡¨lÔÈMGò“'Ð~ï½,ÇñÆn´yA¨ÝÿP_u@ ¹'a$0—–O^V8¾†Ìýp_ð^ƇœY±‚åªz÷&O3êÜ/žQçvüxSun-ÿ à«ërË•–é šß}7=‘\ÒÚÈÞpƒkoYvî¤Aüõ–[X4Ùºx­êÎ>á¾~T窫Î=áù>óØ]Ò=k§ë !s?Ü<îÏÞ½éunÿüSúõ“N˜ !òÄ+ÉÃuôNt¾¢ Sùõ×™ßýe]Iª’é/X¢×\ÃöjÎÀ×Ä^sØ6Íã@»ìÔ‰â÷ÑGy÷,ðããÀÞþ a1>Ö¿éøŠ@0©‘Ä[×V¬jUß #³Ãüª®hív|°±¸8FöêEu×]¤pÐ+ëÔa$ÏgŸÑk¼v­« ñ Ó+É„Tƒ€w`ÇŽŒ÷nÛ–™å%'ËäÜr~ ë ºQ¨±t¯½6¡U½gOÖñÀ-}õUY¾ÜïL"$iûø“+Éæ®–ÅM©4$Ù¢þ„R Õ^BìÜ—_–?þ`@é³ÏÒXwõÕädwÞÉ|™?f±eË‚j;¨aÛzd°Z5=š¿C91üê«ô—\Õâ_¾’yE²øž@¡ÿÍÊ„… I>è`¸{ ÚpóÍÒ¿€UÜ=ACÀÌ HRõøó ÉAëRG±UUWû±°‘[Tª¤¶Ë†…­¡‚Bež:•¹Õ/½DUº\9jmW]ÅéîÝé1Ät>ƒaü…Û‚–ßÂmOÖ¯O¯Ÿw nR…´,S&³›úçR’äNIÙv ¼tï½~g—»ìÓ%K¤sg:¢š6¥W=°ö=.À1÷¿ÿY0Ž¨’¼r%ìV›²KêNËFéúÁ–ægÒÒÕ¡~}/ûÔVÑÚ¨;1{6Ý.o¼A&_±"Ç©\™[²kWùî;:kvïfÀØŽR3´N\ƒjL™BÙm´ˆPS98gÑ¢™¥åÊr<‡H!‘Î"3½ôҥǮ¹U«LqG>1m9¼Ûë7ŽñO¥Jщ¶aƒcfÅ!<•Bµú³w/W¬R¨˜çäD66Ž´ &0àC)öd—+ÖIø¬xúiömQ ŸÏªÎú~`ÄLóæÔïòçgâóƒ2júçôé ÆöÄ‚jÔðU<öì¡L>yRáÞ}×àÂw/]Ú”"óu+9\<-”èS‘2"s2^Z¹’6 O8uŠ×Ç7u‘Û·Óèçí=xX=zPþƒ»þúk€=ÑZ¶äg•Bu$V5Ö°R¨˜É’léøË—+×Öç“#®}¨­²_®Òe299ý÷£Gàm´lÛ–ßà*ØY:1,üÏ?"ÞhÇäf=F3©jœ8Á[¯o4bZ·¯(ML~t>Iv¤=ff¸ÿÞ‹anÞÌ©¡ù{èèÃg˜P½´êyãÆÌ~zýuÿŠ#a"ÐT¥Æ"\ÎA¥A’?ýÄfšêpæŒbl¢$Z*0¡@a1(E\ Ù8@áøÐmõM>}šÁ‚e‰­[3a÷ KGŒÑvð·ß˜Z)$zõr“m-À~ŸyFí¦N%ÁÆF8tˆyß ˜“GÉÉܤžÁë$CѨR%#ÜÓ-p¢5mêw(Ý®]<Ë–edˆÏ€y ŠƒR@+Q=λO>Q8þ† ž›†Z‚í²Ãj[ €ZemiE‰Q™N>m-„AÇôÆlSØ¿?#¢ë×çö¼ê*.HˆÊ¢Eù÷%K¼¦ó™P2²PUj)uàwøDÊ•£10ÿK5Ùî5‹¶aCßiŒ8wš5óØÙ¿áf£ܽɓ™€s³K¦^Å磜È$p”C7Q |YOiû–`Æ yè!…ãËJYiµÀ¬ZU­-ön™ÛTáøÐÅ*úSš[xûv™9“6ùW_åóºþzê¸ØkØìÇ3yïÞ ù9gŽ×Aƒ¤ˆ«Ú a '¾—jà[|ñ…äÎíŸ*·7Qvçó^5÷_dGHï€LÃÑãÖŸ¾?4N½àµ)*T ®êî¶8 h¶_E“À{ïyŒ° ×]§¶@÷°aä'ê#±V LH¥ûhE+™}«Âñ/\`äƒ[ŠQÈßÏåí·)!óççÆœ|í5:”’òÓ;õ‚\ Òª€mÜèûmÁ`à@Æy*DG«V#sç2<òÏ?Í~pÂ󲻤÷@›1\@ (_Þõ€ƒeað`³×cà±Ðn{ŒÆUó´éزåßVÁ*Q¯Ã0Ô!9™J–'ºn Þ_>ýTáøÆH”ÕaQ:¤‡+ÂÚeÉÕ Ç g%$ЖÇ0o¨BPUŒ ×^Ë¡sgùòKjÜJä9‚Øtì¨àº€ñ]S­xQá¦ìoaÝ:Ú£p¸nˆõë)3ͤE`K®É+§kfÊÏ /‘E.Äsßµ+ý¿çÎñ||þySŸ IIÜõÉßO#jÏžŒS ñxš&S½Ct4s ”¢}{5Õ2:ãœÏiñØÎÅU`÷_²%Åc‚UnÚ”nrÄFÀ_´hzvÌ“ORO7Ž(VÙf—-S^usüxrÕxäU¾ò±ci#u9y£¢øÇþññÙ¥³åVõ{"×àä-pÿ6ï‘E.ÀwÇ•8FëÖ¥}@)S’4±oÚ²%­+ÐbT7&¡Uß2j”ò8R<И…ãǶ”9Õ-zŠÒ¨æó‡å\¶ÀÝ P«÷ìa•ïï¾ã©ýðÃéàUª¤›±5š7§/O ç8f´$ûÃŒ°ÕNèȬ+D`”gVÕªîM àü {Ç{aܽ’`¬ê³"ƒ@UÝ¿ Ìͯ6»’­Z1 ÿ­·”Û‡1r$UžJ•äÖ[©5${öûƒÏ>£ S) —¹v>¶8bp²dâ±5d¶Õþ˜´Ü€ö—)CBågÏ’®@)ÈzèüÙS„"ajƆ )…|âÔ)éÖ®\¡ºbDY±n­ÎÁäGŽÐ~ŽïŽ3Úœ%‘iGÒãWr„¿Àéú§T«ÂÞ> Ð;öç–S-$‹* äÉCïî·ßúÊ6ˆ½Qf´ÊH¬nܘTÁÉóî»”E‹‘<v '&RØ*ÅW_ù—­–, øäòò^SûHÒì$ŸÎ@n3)<üþ;•HN箸“ÊÈ–fGðY-ï×_¹žŸ}–‘ó’éwýõÁ~_ó€²e9+pÇ.$(\˜‡/V{0„ßQmøbZkxÕ6RÕV…+)¬üsÊj“ÖdW@î6œ™?þH³b… ´g²ÀáøÀÝhÑ‚i“sȬ\‰ÕXÃÐ ý-/ãÐÜ•nŠÅ‹éDP ܾ%«6×_§7``©´iÃœ—Š¡á³à·Ø†¤Ý²JNäK;Ì~Ü{dT<è)uëÒªãò)¬QÕNI£—%KúЉ@±ªW'çá4¤º¿hÙ’îx¥øôSyóMµS´m+¿ü¢pü}se—šv·Üâ#mÁ{,=ä¨AÖ5‰H?9ñ@ûõãËXE ^’¸rV^pV@‘WênƒR©:%JÒ¢,~þYí’Â0ÉLHàf‡È FY‹Ž¦e/[6ù,—$ÜàÇ=EMÍ ¢g0+sÃ_pp«N>ÏôÒ-pÍxܸøFP¾ÌËó”ÒÕõú ,»-@j! /”6§XÓ[âÔä}?þ8­=Þa$VÏšåü7E<À™ÞþxÍ5Ìs-î²a¬ìT\Uï駕Ûï¿ŸÜX)ð°µ5 0’9e }F?ýdÍ5@änÏ&/¥µ$7©ÚoØ@…ÅCNBðºÖ‰Ëœt•*©MÐز… ‚¿Gê‰4iÕ¬I»H]b¢ï@wS ékm9eœ:EÅÖZ5ÓK›É\5¹öݺe:½$VãL¼rœñóÏK­6Œ‘M›Ò<9t¨;'Àé#4&\Ri£†vÓ¹³Âñ>}”³l7ì}¥°°»¡Ý>‹Mma¨@ô@Ù‘îáÄOîÜÞä'Îæª60,¯"s¬®]i$V¿ù& ¼&«Óìè?üÀ|Aœu¦ê+$æ’*é6Ži¥€Ê÷Ýj§Z·V^ߎHçF;^œüì]\Uå÷ÊÜ©9±eYijÎ\™šZj©åÈQi–#Ór¥ÙÒLÿfæʆå6Ór›DqâEY"¾ÿ÷¹‡ðr¹ûžï;çjÏ_?ÂËùç|ß»ßç…:|ñE•ã«k’Ÿ9ÿÚX~æÿ*XÐÄÍq¼™y¿ŠèuÚ¾Öƒëöß¿}ÞfìªMžŒ¨¬ ØÑc}!ˆ&l÷euS–máD>@~.¨0–x,÷Xúñ¶aIhÜXÍÒ’_ÕF`ÂÞû¡‡Èïc§ïÝ6b=¡ãù±”+'<ߺy3Lz `?‚ϸÍZ¾ÐP8³'ª<¨7î]ó TÇ+BÍNC³,Þ|Óù_7 ~’üˆø쨈ãÇaÆTª=µvíÝ2”•+qrEƒ5)/$ƒ#à,·)ÃΆ:ùÛJ8K7>Œìe³¯mÜXÍZE[ÔæÀ2ØÞ6ôƒMi`êæúõMÓ£ª£Gáìîl¥T®ŒÁŠpà껬H¬^ ¥ˆàÿÆ~VÅ™_d¿Õ•WÀ¾];•{ùj‚"Ï,'W­Â óñTFftîl;Ýà"øT³ J}̨Wçúèðýê+•Þ‘èj¥<3Îì[¼M›ªpK–€Ê¹éf¹;V8ï_.Øæ¯Q#GHÆÄ w¸V-4S(„r*‚÷žC \Nà“O°Á„"¸:3¹F;³B©'KÑáÅb—¨ZUl`„ µ§jõb[ÁªU22ò¹øôSH°„d1ÂJGh¹iRÒ=)_ÕçÃIä`£wF†jS¨†E™œÓ`3I™^$lZ³h …Pîõ×O<zÜu~Åìø‹önZ´P-$b …éŒHvevÊTQÜVpðIÚc_‹Ó`—|±`™ÌÛÒ¡‰ÎÍ OOtË^@]Ü3Ï LB(öõ¦@…£†O÷_DŽû•,®^UáNXö²Vr.tþ<Ìr›C*UDóæG‹ÆÇ#ûÄøš3Ç¥¢£ùó…N¼Ùx@lÓ\Z8%zˆm†MLD](m Ï Ú/8ï#!ŒÉoUp¨³å öƒ]­N„¯¢ :þiñâ»áGKR˜kîXãƘt¬ bc!÷íRB—ju<Ùƒ ¦mæ|Ùì0U¬o¼Î ‰ÁzSÝú¨üðóî=ž!ª)ÒÕª‰­f‰XK‘jS¯› <59¢i† Išh¤§ã8Õãï”sç¢2ŸŸžP]µ‘bŠÐ×<>Ö‰*Î5ðöF$‡-FûÁ6Ø[o©vö K»hô$'£ˆ5`:ÈÅY`°ÏÖ›¼D³XK 1ôoC{Äuìè|…=ÈJ£J>'p +bÑL¿¬Çy $Þß}SA(؃c+×÷ß°™…˜QË=K_võ"S§ºÄ¶”K– MÌNzÉ/¿DªEZè’ 9ýZµœi# „lgƒ³{wÚºÕvdòÿ„h4o.–'‡Z‚Ä›4¼ ¿ùFì>å)HmdŒícŒs`Qéé)ü¥“"‰6›E€åàA\›ˆÇ3@.b°BF2%{P‚… öcåJõçqbWµÒ?âÕ‹S(fÁ–Œ+Ä2ׯã×7†fdÓΊ-ݨ|¡à}U¡‚X#–õBf§.¡`Ëá]Wÿt¤‚;¾wî)¢h|ñ… ]̘5ËÞQ‰áÜ9˜IÆ™§~7yLKnò#xy@…ë°á¤:o@z:Êi¬'€Ö¬g²œ&¬\xyÁ³V…Õ'4›–åU×®fø=N‚DÎúóO{ œFØ_tNpèOÁ•+ÂËïüD‚Ë×Y<ø Ê•iùqáž• ¢y5 ™Æ3¯]Ç®]ZZ™oÅ&ôàÁèbVwBXYÊ`ùÑZ"l ¶RJ—VßJ‰ŽÆcÙ»×ü¿®['<Àk­[«L‘ÊïTá÷à}5eÊ]Æ*v0ÇWs!³`3Þþ`¬cøw?ìéMw*å¢n]Ðú‰CF*j𮞸:¾%d{_zI8A‚ï¿GÌ_°$üòKl¤Y‹#v{ùo´ÞQk?Îî¢Ëé+² D-ˆ\;5¬­Dôlîß1’Ÿ”rÙ2”§ fÛ¶®YPUä±cèŠeƒ³sg}׬)¼JŠmZ~q¢¨–&zšh$,OGˆY"úõKϨHþ‚¯–.IšhlØ Ã÷'ƒ·èé©ùmb"Šœ[¶´—Weæ;ï Ùª ¹·wcÚ¯^1Ióæ¢tâ’%å›Öß}‡îQA‘d+`9ÉÒRt‘ÿ¥¬ž~L¤“&™!”S»w£lIn¢;ÿIQ¬àªø\Ì›'|Ô×Þ—QÁ.첕)£šid ,O؃açäÇ_aK»bi°ãÀîÃG9 ›1i¾˜Ëo…Ç×.ºôÛ)”T.ì·õ9»1x°ÊŒCÆ`ÓZ©âÎ6Ø“O çÖ0‹ùó‘ƒáƒ°C‡ Dn9‰x¡8¹ŽNK `*IšP„-¥óEÄ.ÁxùeZ±Bø*S§bÈ{ÇNzoÜWÈißÅõCåLo2 5žœ"'½½!3ùÖJ—ÆÔ£O?5GJ6U OŸ.P³ß¸õ4g’#íÚ ‡›ÅåËxer:‰ââPz¤°C³œ\¹$•*¡ã[E»úÎT¬‰î#óêN»Ÿ»„123±é…îÛ™èZŠUÏØ0‹_N‡B†4AùòÂMY.@j9J°“ ?«jUWéØfuölåÿXuë–ó/11°3ÙÓŠŠÂ=²MdfŽÇñʴωœÓ`œ !qØ° B†BèÐ+`Z4eP.>ûÌ ù9‹Ê?Æ–kÛÌ®Ssûù¡ñV4ü+Ó±ÂW1FëÖÂÃ&>5ɯ¯á»+D› =Åj#1’_Â4jvßÄGaÞKûöÂWÉŤI8Å–ÀªœO\Íšä Ϥ³`—<7ñÅÒ²{wpQßÅѯèHnwÏq"—û"sÑ»·j•EçÎQÏžðò“ ñq`ƒS§úîÝPˆöÓe¸ÖÎõL=‹à ë—æÍQÅg³³~èP„8D#ª8yËŠã¹çTn-ÉÝ-è°x]0hð22¨i>k¢Iªs‘–«`½9S=JÖþì ˆÃj„ØXè%¥¸¨lYømy’`þÕé€bŸ T¨,â{22jút‹yðpDùÔ"”³‚„ø¼Ò˜öÉà¹2QŽÍª¿ÿΙ1j”Ef-~°åÊ ÷Ç/úQ¬‡Œæ»üøðC±ã*GRl1'§ºØö”E‹WÀ.°L#“]Q>Â&Å!!h:fóR¤wÀ«ÙYyÊ,ñr&S§.EcWš{iÉ—8ÖnÝB¡# ¨Áƒm'ŶlAH´áÇŽÃðáb—0ŸOOuÚˆØcƒ³V-H`¶ÆMêFV­ÂÏEcï´ÇSø*fÁÖ‹è(Êí[WˆâÕ‹h™Û~rh±%™d åhÝúîn_±Z^p—ÖéÓhyq€žá`Gò~BÔÝ°ŒvN²Á³x1þ’nÝ”–]`k¶U+UFJ·ëÕ;öã…T5ðÎ`Íòê«Pœï½w7ÂÜ¡XžDï"øPø*fqõªp &ÆÞ§)X\ŸÔ¿`‡ëC)Q²‘É›³cG¨u>Â#Fàø‹ït3>o¶' Èù*Så.vî4˜¡·éRa:-lˆvRR>‹Ö®]Cˆ†uhçηáÎpJ±Nç»rˆÄØE°yÉ{Fü¿t D|}Öh3f ÀOÐøÑ\$G×I–K»gŒ-„3ã™GñÅlÌEœ=‹•„Ȇ|#“…RÕª(f ž r§7o¢šHq^Yê~ Ê;9mút*UŠ&¥ÐbêWþƒW±³X‘oqäHXvœŽÏóZO<¶Au‘˜ˆùï›6©|YëPݼÌeFŠ¢E±]lò½¸ïä[Iàõm‚÷¼™† UÁ^ù™Bç2§„M° ]Àvæ#@¹/\(¤‘зí¤þeíGp0ÚiEcK#òsy`M(­  ™¢-sK– lÂÖ΂Ø“ªLQ´ ‰,žçÏÇ_™¿fܸ¸¸N×=èf<úƒø;uB½kWܶŠ|8½{›îÃw¶?Äc“&¸cv¢ýüT[‘ To|öùïRÇ#Ë,š¶×YY(”Ú¼YÆZ;wÞwÆÂs÷ntÆ•-Ko¿­fÕAò%i¤à.uëà¿îá‡Íª ¿Ÿ)¢¤Ø%ÈÐüÅG= g6{„î6 †…ÌíS›8ùñùu­[£À´—‡P¬ž‡.°‡iº‡í ï XW§ÌÎ+\½çiÓòøA,ÄøQ°ßÝ´)Hã½¼DÅáY7ðƒpÝBcõÃ>¾èøž -’G‚Ô¹3Ü.$$ eÉ6?›d?ü Â0”=ÐáÊ®^Äu¼û®ðß·oÓ¥B½Kì*d)£T%°V4-[ Œ]ºÙØ­[¿†eAôÚk¢˜fÀª`Þ<ÔÅãàAä}Œ?E‹Ò˃YÔó±åßÉÍñWéÒÈ*Ùi¹)²‘-]ã+”*…~g³eOê‚EeÇŽ®&€Øúª\Y,ÿd~°p–3$šqâŒ.Kj…7íÞ½Ô·/Ü A]êtñž*$·Ë,þúKøˆ†×säÝFø*ÑÑx/rØ F D„Ùàë‹ÈfU~ 63ÁrÆ í#TìcåÉ9Ÿ™C!%¾ ºI“ ôŒe ¥/E6îÚ%©Î6?®^…ìô´ßsç --Ç?4CL$¼ÐWv  ç'9gHGëÕCù·£„9ñ@¸‘®]~<7n@ÈÍr2Ž¯ ‹E„W°3zõ^Ÿ 6ÎUçæbç¥Bô²YBJ ¤Ç矫¼®x„v‹WµäTe‘Š8zoĉPTè5D6Èà`Hi9]`¬þX:dí³£òÖ[Ȳ»tà€½çæ¡Rݹ{T/¿ŒX¿hD¥ñ½ºü:yDRt÷I¥J òQéé’?þx…Žõuùcó竳®s¸q _ÂSì׋ÖéV°z56•CQ¸˜˜¦:vMÀ;_iу©S1ßÄ $'#èS¿>v2[ž6ÅûžòtT0»šýX²áÑØÓŽÅgä Êÿ ,€½ç:íÛ… ˜(ݽ»½ñþ|Íšf"íÒp²e"šA$%Ò²¥œ9"0aì ;q|<äÀ¿<ÌR±p!ž•BVal0¸Ø<îç‡añìAôëGûö™¿ó3;è†Ý6Õ˜¿þš —íÄÅáJˆÚC× R–xÞòµk!3¥qW¶háêXI//„ègÌpìžy£>ü° .P3¸CçJÓñÉDCˆ*-¾à°a2&„ZAV––ù|HLD!¢&1>Èê–Zû8¹Œü.âÚ5ˆz>¶=†ÜºIùœW3:fÚ{»q#>«Å°ÌduÜ8ļùKÝyÅæÁ§^Bhúx '|¥NRNØ0ªUs²B’%$Û!¬­œc¿ˆ@”L|.NΣcÅÿïˆD6w(˜9MÚ"!^¶Yþ¨\\¼HÏ>‹)9š o_yK³©àé©~5r` RåË£’s×.œåۙࣈ^jòÁW_½›‹cùÔSÈ…²i¯´Ÿ ×®,ÕG¼‘ÿäóðUÈ@œÒ¤‰Œ…°áÁï×Q¤¤€ž‘­W&Fñ }ôQ¤ÔeâhMÚ&‹üV€Áƒ¥®hJ>ÅRYa-ÑJ°³x©UË6e¥ZX³F 7œ?ý„#ÌÏsQ+:W,ÿ€›’%ïþ­,0ÙY†)l«ðÓÌŠ/HÑ;…/Äêíõ»mÏ‚‘™ »‚¥´ý¸t ¿2h ;œÕjƒpZÅ×g7"(Ń$2Há ´N²m+V`kå/'c)ʲTtI³%¤¥AoJóª'NB_ü±cäW‚~-ߟp£jÏÜù)Ë—C`š¤ó÷\¨6jÕ`ZPÀ³ÂW!Ck[Û¶2RÀo¶J{‰ß}}‘²QÑ•NNÍ[¹ ÿ> 0) 'D'`‡‚ϯqˆ%UÕª¦÷2Áêòµ×ä-·r%Ú¬$ !Š®xP|ÄbëÖ8bÿκʟR¦ :ŒCbQQø'áøüs´`ˆFœ%¤ ñ©U6·X ÊÌÌš…¼€M3oî\YöíSyuV¾"e/¶ï-AÇEM²†Ò¥Uh¯SYYà%ÉM}÷²o¬µÂúõØQâyrÀ;üñÇÑ0.ÛºÓžzwÿ7<ÜlûÒ€wKÎC¨€ß‰pœ9.š“áW|?ø÷DLnØ€Î9ér2ø)¬­„Ùob¼aCSuµÀé×_£bP\C}ü×t¹+~Q×·~nB©Ãk¥Zµ`R~ð\3>¥ZáÂØÞªë_+æ»e¦ÑéÂtÊ6ýøñã‡(:Û–,<åD§&’÷;2Ž—¦;±D_U%Öc΄-?ÿuýü8{oÎ,¿÷ùó¢ÄF 4cüþ;Ÿ pÖ‰G(®Q¢±D±¶?¯"úôqµ|K]ìÚÈV­$µâZïpÑó²ÁVAݺ’ÌéýQø¶?f€2)t½z¶?l'øÈ[!ýVÁUh»ø’ üü Ä5°Ë_·.ŠâŒm~ÞlÏ?Oß|#jQ'À÷ÉB€wËž=öþJÄä7ŽˆÿŠ‡ˆ¾ysVñÕW®Nرl©ôè´CŒ£Ê»'ÒÙ’©\™¶lu}KøòKys¥o¥Qla O¼œšŠreµ°~=b©púwºT2¤Ðé“ÁÞ”ýaÛ•-7³Eò11ð~ѢР¶n]CË–¶›D¢ÿ¤è”¥¤®n²÷#üÞ,aíZ¨r¡¸~õ«l~°”p¿æw-¨MòêU¼/v*%ãÜ9< ›SÔ‚ß»t¬B~n"õÁÛþ)õ’Îì¯ñ{—“ }˜u•±†;°Z9~\Íkò³9ÒÆh …šCfÿš=ÈÊB[§'&‰[´ô mo#ﮬàÈäVMŽ9s`±J={Öùë8€ £º9YÝ­ZA’ËNöÌ8SÙ0/C¤Ì×xí5•‡¼°k9uªš´„𕆠UñÑrË–©™ý‰ÇÕºw·=>20PÞäS‡Àÿ‡`³š_æg&QrAŠOceRR¨P!õ+HÙ°(æ'àâÀ|56ÝÕ*'ãÔ­ĸüHøæÍhe’Vwxù SˆÆàc[¾¼Ê‰³ `dÊyV;¢CCd,D†ìÏ /¨Óûãï–¶o¾±w'¯_S©C™I†øÛWl7mŠAE¹SPƒF_%Mï,/ž|RMBVs³g£Š’UžY§1h:áÖìlt¶¼úªÔö^W®@:$i¹ÔËW˜Â7ÊXkæLõç½’¡ëÇé‰ÌáÈJºX˜Òe‘œ9ÏËůE‹ ^M² Ì23"Â¥¥ÅOåŽè’Èå<^–|5¸`½{«@ÙÇ nï^¡”- ËM„ cÔ¸1‚®®€ïó½÷pQ—ÀNôï/)ŦàÀ‹t@Ê8†7üQлoJËäÀï!ÚÙ]ÒZdà0dSʹ†A޽＾tçžùêÕ°K]‰’I@¹r`~iU€’ Ða­ïÆ&¸”†¾|£oy¶-(Iµ죱rte$ÙäÉH»ó—mÛP .méĺZÂ¥(ƒ5á™g$¥*Nþéö1–»ŽÛ·Aö;ožÃ¿ÚÔ/Ú¦ˆåíºx1hË”AU̯¿ ÛaÙÙ`¬r(øñLjÙ¬»„ YÞèwÆ0Ñ~k5Ú݈öË¿ÅÊk©éÄ^•ÁºfÔ(±KäâÏÆù'¶ ‹Á.]l»x,QÙJiÖ ¼4ê‚]66YQù²ª ´ùµø¯áá0’Y(±øRsìÚ%É~+YÒ4¶Æï1, ƒY B{ sþfÍÍdŽ ø±<õýñ‡íOòÂÇ­E Íîœ]v»‚ƒ¥, ñ[å隥Jé EÞ_tåOL <9<¥qQhü ÿ[ÆZ Øö`{É ¯`Diß_óÀæͨϔLlhçw£Íÿ–1Þ~^^ CgÝÍ¢ŒåÿÀÈËlÙ‚sÇ¡êõ0Ï=‡‹ûø`®1»®;¢¥N–-R§Ru°~a÷ÄzˆmÑ÷Þƒ^Ö$ËC‚Ÿ­d¶mŸ*t¬±¤µØ4’1ÍPT&­Ë`kò—;P50ÇÜl”&K3Ñ]{÷biäöÀ·9íq<“˜š Ÿý·ßè“OÐ=Ô b%J )Ɇ+Wˆ›ØN[»ŒÛ… à jÞåO_}…|®Ðd·Z`ÍøØc“8¬wØ‹éÐAƒ(k.ØM`e'‡çѥ”.%±uâ ?9ʈõ#{^‚8M‘Fç‹RØx£‰çŒ:Is㸠«{Þ?µjQPðÕÉà,°lùwæ²Æ¸}n¤ó*ÍÔP¤ègŸÁs/ZÕJÎ}±à}õUpÈôÑÝ·î6¼»t1SÌÆv8Ûç,ÿ%°ÃY¦MpµdRÞ¹C!¥(x¸¤åØê=ZÒZŒ¾}å-wt:Å¡,Vµˆº½+|EvF^zéŒf´öí¥& Ø—¬[—FŒÐ’T\Áé”åAôÑïÄ,–-“7(A]°ˆèÔÉTÚ>Œ +{prž?{°Â' ^c(¼4ÝO#I†šX6/UÏAXAXV”æ/xU¡‹ž†q®3Ù]‘±bBê™wì@Ị́©”ߌvõ*üPÒZ¹6L¯cÔJ÷ K³?d Š,_eT.v´¹6/‡E]k(MpéÒ=iJX‰m‰C íDR’ÜáÓj#$­ü~§MCð\RJÚ2Þ{Ovè’±±Ö’´ÛBeʸ:ÓÊ (-ØÒ¢ÿ´£½KZ‹ ’jÜ8$_ê××2”¤`þ|ŒE<ŽAwúGJÏ…+xàmÚ«ÕÂÏ?S©R(M×jœh.V¯F“¯+mkN ôWôD$ʪg˜0‘.MЭ›¼ªƒ´DŠ/B;¦ÈX‹}áŽñ×%'£OüÍ7Õ™Kë üýQ3&§ "·Sér! ß!uQ'À.¹+=ÚÚ""éòƱߴ]âç AÂÄCcÜΤ%é°¬)®—/üÔJ1±ûÀ§XZUí©Ï(¤(Ý\uÀ.Rݺv£ÉÌL”ÁÈL¨YB\ŽUÏžN6#;° äû íiŽ·Þ’4BEuüñdÔªUˆ·k§Á@ó\\º„D¸®jKðéG¡ÒY 6/er.å[_2‹:ÂjÓÞç^ùrl`“9), <=Ñ÷§922PESµª¤±×a•h÷P ¹–3º“dXBŽ‹Äb.äB8¹s§7ÃûªIQ%#!Œ’ Ò9Y±¦ÈH˜—1²(},ÝCÅŠòlžk'Ábtb¹úW¾u‹†ÙÞöøøÏԉ߷oúD>ûLlW×ÙÍt«¥KŸ±åØ.zûm­oÂð©iÚ”úô1m½÷ñ6”Ìõwû6õ뇛‘|˜|Oe2Æ€›— $[¹SDqº©j¥ {»­ZÁÛµRÀ³f îä'×Ì‚­‘—^BïŒ8¾«z˜èQ¢ÖD*U­ ÂáàÍw dg#]¥ŠÅº%KðZe¦]F‚y)?k¶E¥Û²2ªJkõv9vW¯b8²œÆ5hCSÕ®æë WhölÛ–?óä“’úèm‚ïvñbؽ ªod\G5Ñé-†¾ªå#) ý#6Jþ²Î÷õÎ;0ùä`î\ç):]ÁåC >ý“¼_}¬uôè!åV A¤÷ß—´ãêIºRˆNýeû“61oÔ½ý£iÓPÖ+m”Mœ9ƒqçÎŽ1yÚ„Ï:êVÅ%Kê…ŒÈ,X£±éÈRϬ͊ ÑÍs±v-nI[cÜ¡JÜDÞ‚‡! aóØÖ¬)‰“öæMÔdÊd† K'KÒ-ÎoËÁƒáþ82âÿî»è Õ¼Ð(·oãòÎganaK<ˆ±‰2 ±…ùKOIwë:||ÌÙÊÒqæ 2­5j¨Æ8Ä›¶~}4›«…é}¹€2f‹"ú×À>¿Sº¢$V槥Aú9j±a?\-'{‚líË,1ʸAQÅÉœñVyòIt8ªëà\¾Œª UGŠ@bN’MvÃ+VÄLÑîÝï_•dPW§ýƒˆ6µ"6¯Yu\¹‚*; ¹CyÏÃ~Ö,•«(#"qòøqHKÉ#'À X•h#e%SD Ú7DêâÓ¦ÑÇW¼~]*[&[\ƒIZKAÔŸHR\ö²øM›°åQüñƒe1ôÕWB.®*NŸF¶ŠMJ–™,ZXZ²sæm\“~í4%yÐܪ<í¦+:ÞäJÜA2.\€¨¬PãÕènÙ«ÕéX(¤e•*Ò¥¥‚½Dµ)®2ùU—óŒ„Cåܼ~¡Ò3Ù fEæ-·7dgºP’2ò%v³²Ы][læ‹wr£F4E “’kà »`èÐXl§ÎsØ“¼êhsg®ãùçe3à±|6 §’E¥èÚo¶CZ·vrÜ­"-¥zâyqd,zÆoÈUg]º8ßÏJ‡´®ó5kô4WÑ,ØÉÜT›ÍóCvÓÚ·Çt ½9ÉÉ8°Ÿ~*|!G0{¶CѯlŠ-JóÅÝX  /žÌú·W/ˆÊI“$u~)ó,œHùûý҄LUÁ™íè;.—…[™1çŠ=Z^$“Ñ¡ƒlò“ÄKZ‚üßÌùßÐP–Ÿ./®uý:dæ;ïHÕ–Á:ÄÓ3‡Ý¿Ÿ;—J—†Ûj11ŸÂŠK¼AµñÕWÂ9 x/ñId\½:´‘ u†h$&âþíÈÜuëVÝ¡£iêeŠ(FH]”O"Ÿ}gU³ËP®œÊ tVÀ ñ›’Ì»rf¸ŒÎnA s~–6 ¸y#xÚ¶•}”ÌaçNœlŸ|‚(ö •‚eêwórl,)#‚êÒΞšÜª:X»jZ®]ƒÊayÕ¨Q}¥&8zïïÔ)»>¼h›]FeÑ +•;›=È!Cò&Y`–/@™è› šß¶óFKuAÁ<ø šæÕ¿¾£øé'¼ÎD[}XS§‚\Kšd¯QD)Ê”k¯Ï–¤ii:!ûgÚàY‚ŽÌÆ7¬Uç̓…üðÃôÁh#ÕÊýt¬ ],‡`!Þlûö°ºD\Có¹ðù‘™‰h‹Ù‘´4ð˜±ÐÙp—a[ÀÞvJz‘å[‹j/ñ£f#S&EÉÛo ªh:x2'…Á¶»c[·æü[üi:]„ô±®`ëºreúýw­Ö¿v §ªzuÓŸ‰¯»8ý+EEŸ¯1ÎC^ƒ·;8o½…ÖicèFïÞNN¥‰ŒDˆ²];ÈÉ~ýÐg­ù¨PëHH€ÇmÒOÄ?ä÷Å/KÛšq‘^„üeÍ5Ë{"8Óæχ’%c¥vUÃO ªÄFTÎ|6Lœ¦S[‘òýŸºë:Œ'ðçÏš¥ñmULÅŠyû?f-ÝÃeÅݵ+žx·n¨ã ÓëˆVö×f°:Ù²…ÆŒÅ+ös·mÓÓ©M(¹Ñ–Ó§!BÇ×øÕd¦‘w9:Ò@öºüW¿öšÊÞuëÒž=ê_ÙX¢ñ†´¦v ÞÞ–¹4GqéœË<.âÒ%°5²Þ·2ÿBXÑ”-›·^=#†R=èJ„í_¾yö;ùžž8ªo¼AÊV?ÑN¾ëiÍøxXŸ|‚Öú2e0æã›oàÅëSþÛÄÊ•èÌMN†/ÃŽ€v¾Ì]l­O§*Ðé•uK—"à,Hßñž‘\XΪ_X‚žÝqÞûæô:/A7%ö¶›ûw,g§ÞüùÕpø·.\À0“EðË/ƒ¸éï¿¥Òäk‚Fòü$%ÚtΈ÷ZµÐÀȦò×_ã‡ndLZŸ¬ÇƒþÚ·Oë[!:ÐczҤϽâ]Ç®¦Ðn>ÉCÓÓaÜxYn÷vÖ&*Áž¤ò”¦ƒù+V`cçZu‚èR<Ã¥+°Ù¶~=df‹øÙÔéеp ¹`Ñ*Í~»zqv´gÌ@(òÉ'Q¬ß¼9ZƒùáGD¸«%i 7n€éè½÷´¾¢“érAº(ÑuÍE§N¨dŠÐPäPe?ò÷GŒÅ©ÄÁk¯Aܲi0z4B°Û·cï+mµl)Øè\¿A>Õé@ ÊÖA¶÷èQØ9S¦8Ù¬:ÎÿAéDµˆ¾%R©^ŽÕ={ˆ³gã³^æ×ÃR«}{ð%±üT½d‚/ÈÆ{Öݺ!eãá涻XB;æN)~Gqü8¢¯|$bc'ׄ8‡—çį,½lF¾J(fàMõ–ÜL+úø=–µ¥JáL°k5|8"Oì.Œ‚vm‡cӯё ´_,âW®àD7m*¤Ô ŽÖ£-/²‘NÄï¥:‘1žœ »zÒ$lì¢EñÚTü*R©~ˆý‹á’K&~Ñ {.Ÿ{Y’‡j#Ú›b Ñáñ,}ö¬¼ŽBÞÆUªH-®NKƒ—ôý÷Nüê’%Õ8ßqx3žN— ý}œý}U‘ Œ-üµ¼Œ«”âA±¹³Ãt“»qlð^¹‡Ánø›oRƦñpž?®ÁèÌká¨IÛ«E _Fµléœ!-Zf ãÕ£s¾MM¦àò´ï)¤VåÃË OC~U?¶s$—vïŽ`µ=ˆˆ@›Þûï+EP hTr)Tsâ7äò&ºp UÁúñçŸauOœ(µA#nfnfÝ¥5Æ8|aŸ{ ¬OŸx‚ú÷·]Ì|ñ"jž8,%ªCI™7É÷!ò­EÙZ¤/¯]ß)¦êÆ6Ø~M$h|ü÷úùÙøØ–-ˆ²æm¥OJr9!vb9†1ùƵ«¨ V”=zàP¸8gÐ~}ž¶µ•´–Lðþ(VìÞ)bÃrüxÚîöõÅ©8­ã7äV¦à*tK‹R~¹½z¡èB+(=˜’½BÖlÙZÒ˜üL>ÿ8AABV]€*ˆS§¨ÛƒßGeõ„ ™²¯ÒmJËòEìBšÀÓS›á>ªcçND,ûöE}©CX²qeö¼êÈΠÓQ\IÊÔ¨síûïÁŤ-)ʲeÈ»I¾‡1crÊ¿hJ */ÛµËÍø­Af®1úÑy^[àŠö 6þ¬)vŠœFzj…”#êKT–_‘þy\A‡~w»`ƒÁ¢Ø´ÉÉ+ *„—,;“‚jSȃ”®‘ª=tHêÜpK`‹®}{© z2f¶lišÓ<}å¸cÇÊ(9öû9 Å†ÿ 'ªÂþŒðEíÁ–-YðžT%^|?6|w‰èÇ{M`&{'«>‰¿ýï£\232Ð/¯n7ßíL ¨CåP¤§ ®\ɽ}»6«› <¯ÉQãßE˜4)üý7ªerŒ‡yr QM¢ÕòÖµ‰ë×ÁŒ÷ðÃH ©kùGo£èÂtKƒ‡„€¥¥ä˜¼Z •eãƨ¾s|¸Xíªel³´ô­MAåè†F¼Ä¬J^~Y_5cÓ¦áJFPèÆØÆæGÁ>ˆ´¬G.ŽÌ¤[(¶‡ìuí; mÚ Zrà€j× z–þi£ÚÕtâ†ûBJ êFØÙüé'5 )}|0rݽF5)¸"ÝÂ9f¾üSW|Ω©˜ïï/{Ýï¾}or9KóãÄ,øæÇôÚ!²z5¢šo½¥Â¤’¬dJ)H礿b™ˆŠBÞÇ]ÀâqéR¸#G ™·d ®+-ü™×èHU ¨JÚñþóÞ©VòÁ ¶nEq‹L~{ö>êÖEW×È[4?Ž/A}¦¿Ž˜~ó€7üäÉ0ÅÙq…2åÈ ¹çº{L™™o‡^ÁŽÃóσOIP5ˆ‚wÞA §sH‰¡Ð ´¿&eiÇâH]h¨f7`ƒË ­\‰GñçŸ(Ÿ{ôQZ¼XÒºfqbâ™»¤SëÛ¸8”T¨€à‰sˆ)X7Í¡âÀÖHt´íiˆÈHt$±C·|¹ðªÑŒ ½8‘ºN'KҞǵlp`ÉÀ&Üo¿iv6qíú%ES²ßºĘSWeît…*ˆÚ@±…ig'-ïÁ&ΟéSµj˜Væ«•à ruªD4™ƒ°ûÓºuÓ¬ Ä&øõ gaÆ Q¥’ù ¯ï^~%ÎÎ%¯¶Zv°³ðÒKnÂóñqš»Ò.°SÙº5$MÊfvî¤òå5)® >˜ÂKÐÞçtÁŸi!!`Z¨ZÓ`íœØu¨hAC4ÚP NN˜0AcoÅ,ÎCR•wøÔ©wçÄKÃÁƒP²v†ÁÏ­§¸B´Çò¤'9`QÙ±£{šŠcËô÷G×ü7ߘ×\¿üJDôÛ~\¡ 2äW‹nIì ‚ƒaM±ñÀÏÍzñÎMJ.D1¹Žî 27KX²uŒúAx8Î>[•S¦h9.œK£F¶yoŽÏBlêà8)÷dsç¢$[¾fql´°c®b5‹‚E‹Ðèj½ô”e5ÛáÚª•‰äW+Йè4Á¡Cè;`Eóý÷vaÈçA¹·¥vï À^0{R¼ç¿üRgÈ®oŠ-H?Ⱥ! ص ÙÈHoÃ!øùá ªÕl’žŽlݳÏÚîóeK‰¿æÂÛ؀ΡpM᱄À@tÃUªDŸ~jÆŒ9Q…v ×ⶴÀÅ‹h Ñ·n¡ŒÍ¹§žBi¥~¦œó1lÒÉÖü¸“MÞMédQ:%ŽìÈ>?Žml“œG‡9gÐõ¨ot4^Sÿþö&)‘ûñGW×uAà åF® “‰sçPzT²$ÜäâÚaºZ†÷ŠÓfpR|<¦RÖ¨A/¾OJ‡¼I11fš4¥'ax¨oYJК·äÒ%T¯X¡ñm8ÖGO?íjg®—^Ðù|ð«W§5klR4Ž- ø‚ä­ãr#³`Y ¦(hj—Z¶ ²£5cüù7ÞeJl¬óKûù¡rÆÑ@"tžBËÓòw\ë[qgfQPéœC]»6NŠ+oÄ]0jýﯟ‘Ò˜W^ÁàR6,Y­ëÐû¶¾Û>}hn$ÄMÕún `‘Õ½»6”?ÿT™¨¿_?ǪŒòŽ–p ¼-ëÖ•:BÝn§“_SL=i29ŠHǖ籚´÷_N•€Œ ç3Þ¶--\¨‹§*óç )xæýÌþ,KÈråšüååÊBq+¶Ô§kh©>:¿fÎÙ£êcëíAL ˆÚÔ¥ýaßÓ“6o¶ëÃ[¶ $ ïh —0ctâìLA(øÝÿ?šè!L9Ñ'®…QrAº™7iž–†WÉ°|yä&øMiX(;w‚ƒZ-(rrð`<±V­¿xQµ‹ËÇÅ`:T–ªРÑ¡C&ÿ~æ F2Ž-kk7öa5©¾V&Ç-X þ•Ù8©TɆM’€­ˆÑ~šÉt–µ—Ž£#ÒÍ8¢6Dz¥ì`z•ö[ö5X°äd÷í¥&M0„ÏŽ{¹––pö,’†."1ñ¨Þ½sìI>VòǪŽ#ßÑ¥Bä÷rqô¶mÔ ‹Y½}Ê”ŽÖ¨ú>±œj+Và´êýŸ03-=Þ6–:XAt놈0Wø³/Ù¨‘ì—–O{êÒ•Ât£6cFíÂmŠ+B§ÖÚþà­[ˆÂ}ò "9Uª ƒoÕ*±#BDƒy±bÎÈ7ÞÞÞÞ˜±Õ¬j zõ‚ÌÔ!±˜¸}‹ö¼@— Ññ9y~ÎîpŸ>¹Š²mÛ»¬Ãl¡´iƒH­¨>’uëàJ®gÈÅÆàügÙò#íÞÝ|hèÔ),Í'N\‡›¯£FÁ!ÒOÔ(²+ê½^Cѯqf6=àðo±mÆ.'¿è²e©A¼Ó={¤2þ©…zõìågézäxYYã—)CÏ=Ãÿj×#ðúA :RŽŽ–§ËÁ¦ÿÄçÚÈs,^<ÏßÍ ¤kW EWJ;|^çÏ#¡ ¹½°4®_ß”m鯿°ôZ;,ÁovÈè<›ý°Ò·ŸBËRH%ºêTå•PÄ–‡Kî4X÷ùúÂOoÑ‚xbdäHXžš ²=z {ÚRSaI²ÓÔ¥ T›ÖÇÓè%ì£.'LcW'{ƈó«6iïc¯Ž›Ê¯ÝÇõŠü_Mpó&B|?ý$c-¶Ÿùñ;†ïY5³îyì1”kʯøÖ[Ô³§Ž8L²³È«Ê3üFk}+F¸Nét§ Ñ+D‡]½ûìl Ì™•ß~éÒ(™;ª“m3}Zbl€a#ùàAP: ˆŽÅ’%¶3†Ö¯wïàƒu\¿DÞRd ¶w ë™ü Û)SPó¢øET®¬>U…ý`"ˆ\È,ؤdüÂœöb$§·Xf¾ü2ª¶4)Ù²„ãËèl1òªAW4 Ș °y?a¨wúèq6…Õ¼8[[·‚rª_?ô‚•(ôúë .[½nŽ¶"”7ß!«òF´èÔ Ù ¶œš5±ÿÏ?ëWÈ«‹¹t®í­O)æ5BL ´ ÀÄ>ø/‘û­Z™~’]vvÕÕÁîÝ–‘sª‹ °$—0±kÌfûkš4¤§Ã“b]¨«mŸ‘DÏ Òïc­o%›.¥HZß{ëÖa?¼ñ*äÙ~kØÉ£… Q_!â5±‹Á>06l@ЕI–Þ-[B6+ A¾rå`oߎ€Õ½‘ý·×iÿs`ÃþÚʧFŽÄªVÍ‘™ü®š7GC¼1øù©3÷cçNx(Ú–¬+~;G&–/Ç_]·.âäZßkß¾0ÒuV4ö](B~žtí¬f÷pf…”Ôlu2h4e?þˆ!›yE‹ÂŽQ÷«P!ì|v«YoŽhäŠ8ó|¶•pÍÅ‹8ä÷•œT²ˆÎ#ŸG(ÙÚdeÂ_¹]_,3Ë”ÉùžX­º œ8ÑåcÕÆrCRq§9ð_R»¶Ônk>Ç£ÊôäI¤SùÏÿG;2(öÍû÷y¦®ìLÆÍË´¿ê7ü?ÑæŽxÒÎîÚ,­+xzÚ¦¼—Kûê£Ì2p’Íϲαòeüõ¸qô÷ß(Ë|÷]— %Ö¬Ael¾"yy`5Ú®ÔÉæqqàéÙón1äÞ½xšÒ2>ùÁ2sÀêÜYG”ƒ¹8< ¦æ~OÙ,Ä×ÎQ²%ÝO‚Â:t°·²Èýð‡!:mßÉt¾0ùÔðlOæÆ-ÉPµgât_¾Œ~¶âÙøtlü׬‰âC Á¢²[7y!D??D‡~øÁÔÇY´z\Ã<#ËÌ7Þ@¹­Z\Ç*"õ ù< dœ¼úvß7iomIkéÆY«,roœ'ª@tß^ ¦ƒÓù¢tÒ&FƒÏ>{÷Ùê)•o1 BZj[¶`Šy¤¥§y¹*UhÇóÿÊ¢»U+-sÖ,3F•µ3ž$ãØJ .N'*Ñ% ™Á;t³]}Žå¦øµt™3Ñ}Ïâ+ºó*íîNW=È· eºd0ðáîÑ#ç{¶‰–.U©Yáë¯QQsþ¼×rJ“œéŠöŒ–`yõÊ+OÃäw>E Ù¾êÞm)23‘5JÆZsæÀTs´ŸÅÿ–æãÞðâ×­Óø6¬àNí{Û>¡$E«W—å×›|jªvµ{laÊ ^‰Fö-ò}V¥_MŠq=om v[ë×·ð¨Øô|î9{ QØ(mÚ-Úê©;wPsس§ð´8?Ö4  ÌÒ ¬_™©ùP‰¸ß|£ëºå›±´·])HÞ (Éu;óE§ ù*Üؽ„t­:íDÈtŠ,A!e(TÔ(Õ+¬N¡yûm»š¯OžDeø—_ªw_ÎbÚ44,9Tmh\Ó¦Áâr(+äââ 3¿ýVøBö€í‘#цïFµyü²Ö,¡e)©8¥µ#Úh¢ô©E{itsî€Þ½õÈYtm,]ª‚Z\¿‡à¸—¾›> ¤Ù³µ¾bcq¢Õåæ5vÌSRèµ×P¤$­òçÒ%zäš7OÒr6±jê6oÖú>AZ}=…†%ÿSαOdo¦DÓ5-ÉŠõvp-Òú&þEVø†ö=Œ`ËÙêtN R&RS‘˜`£}þ|ªUKûú“«Wq3"|XEfž>ë¿ÿ¾ì°Ã¹s°™õP£¥ 4¯{Ê·ì› ^JË‹RRZÇ®\GòÿÌÍ*–,Aw´æˆ¤Í¯Ò±¢t®ù¿EéZ‹'À~Ksê´ÙoÓFËJ˜›7Dd›-ÙI”.M¨˜ÒJTvçNmVÏ+W0Ä߸»Ì5E2}Z‚¨(kV Gþ?˜ûã]ºh¶zf&íŸM[k«êH]ŠúU3ªºøñG¤<–-»û“;wЊ@¥eÛ¶ôé§B.ž 9\­šbz™8|Ï\?å=üX¦OG)‚%ªOãÔï]˜BçSjQHΛ…iï:Ú®°*yôQ Ö=³“v¶¤3…)º8éE©܃*HLDÈÓO›©o¼~˜ò›OÙÄm×K"”„¹´-Z`çØS™)ÂÎÜ´IË{0AP¡'Lp?QP¶·Éù>=v}F7 Óuú®'(¹4ïЊSàÚVÃ]lí~Cè®"ïFtþO•ÖÕ|`ùtŒi±/;4&‡Ì95,-Û·§¡C…dÊøÏaÀfs®4Ð\f¢Çjõj-ïÁ Ôµ+â!úäl7‹ŒK”èA1GM÷'¥•¤c¥inIú¾íÛúŸäD«—j„0-‰ÌM‰½z‚öõ¡Cå0PÉÿ1 ›MÙî¦MÀþ×—_¼ٺÕÆ'׬ /gKË_«¹ˆÚZJ*Я¿šþ\s™É¶=ËL­¢©fÁÚjÞ©“©j ÒóÏçIöŽ‰/Wwšö}DÇ«SDøìG¢}])ô{J½‡ ;Ïœ^¶Ù·Áå3ˆ|£è¢’¾åiç‹tdeh:¡F(XBN? ~ ±læ¨Ycow±±8ƒ'j/-èAfÆÅAƒôï¯åpsK`ƒ7k7­»ÀJ—FÜׇ©í"œ&Ÿ±t°!-áy¾8zœÞ Ó?Qºýü]úÔÈ~\±bæ½Þ¡Øý0†GÇ 2¦ùU£½/Ñ¡”äDÓjwU¯^˜Â£.SºÂë躔 @¯P:5§¡™Éæå AÚÏ2¶„cÇÀXÂ^qˆ9êWÁÈ/ùi±y)otRÆM:ñ'íF{QP9d‡=È¿4íö¤]mÉû}:¾„.¦Û·T˜®]êf,hEƒ?#¿>´§—¢K…)¥…–¤½uiWòÿšâó Ü`óï×_Qs8nœa¸¼/Ù/sEïÝ‹ÛÓUµ¶ ʔў‹ß#ÛrõëÛÈïk¶©Xß=ôúLåN,bó–pcb`–¸A?PÐòn‰Ù¯a¥)¡¥ [¨ßÞÿínM;úÒ?iÏÏäwÄ/üZc;±)0³(ëÅm¥“³(è]òy‰|êSÐC^O)tºùW&¯ú´ª:}ߘ¢¼(KaɆêoÕJýìŒ1”ž>ç†ÏnÙ¢òÄðö†RÐ\f2fÌÁsZèÍ7Qâ¾v­´@t~ ³G<'ÝáÖuŠÝMÇfSÀÛäÓ–=A§¢Ë%趇Aúåýº]€¢ ·ýUšVzÒÊv´þ}òú‰"ŽRZ(]ü™2ÊÒÑÖt²],iñ qèXò-G{ØÖmN{ûPÀd:µš®æu®YÓõî­ÑCÑ ØwûàÈ¢•+elÝ%K0°ÛÑ´sæ CÇêUÿ8rD/2sáBH$6Ëu Ö/Ï> wvÕŃ]œJ•î^²;Õ¨Ñ=ÐòÈÀ9ÊÚM—¿¥Èþt²)EV§ø”áAg=è@ Ú\“Ö·¢Ciߊ8áRNÐË ÉÖûìñ¦á3Ŝ̉ƒ#™k'Øû5 ,êÎ ýÈÌ­[áˆ._®õ}X¿ß¹s©bEº»2ÉÝ>(e³eË¢Á—Œ[h`!:šŠß¯ƒ<üý¡_Ù?šy@4ÒÓAÑ`OˆOP÷îÈüºÑú‘™§N¡züóÏu½ÏããÑQ« Äß'‹ÍêÕñßÿàøÕ°µã¯*âìY"jÔ õë5;D.@Á[÷Y5mŠÒ&7õšô#3•"ÿ7ßÔÅd:+`]‰&MÀ«&ÇÞ¡ ëE]ü>k¹‰±Çµmˆäd8>ìþLŸ.Áý±;²Äq#àë¯åÞ“ÚPd¦ö[õ€8Eç¶zv6Ò@O¶l9xz¢i­uk]Hx¡bMW2“Á›÷6h}Ž€­âQ£ð´8=Äa(@1â‰Æmy÷ ¦M£×^3óóeËPÍ­ój5Sܼ ÛŒeN›6ZêÜ7F|<¼Âöíá!òmwêDS¦h|KšÞdæéÓØ<ï¿oq¨>ÁbóÛoa!7o Áz$çtÚ)fþò}å/W ¤òåÁ¶è6ˆŽ†WU¹2¨&U/ZýûQiùùçwSüJjÔ@]—V`çTNy„ÞdfRšUë×K½"¼yþú sªUC»£Y‚¦˜ÝWnH`zÏáòe¨Óü£™xËÔªEßMŽ,X@ÌÍÎÕøhó¯PÆŒQ§âB&ؘüæ(­þ1ý'û+jSþ¤$²¥õËéMf’¥R%xY0¤ÑÉ5rq 9íh Å=¹=ø¤¾üržå¥K9-/,~Š_¬$jÇŽ˜Ï ;ÉútÃôk°pŸ359nö¤zô@ZÊm+Ûš5e÷«*ÒR\GžYèPf²ØyòIP»ãÖ"C±`Ù²(É}°Yit¹ …¹UV7øî;<È/¾@ùóϣʃÝY%!îå…^=¶-u8HNF ²n]jÙUÇî’Ó1, dzqš0„Òª5‘– t(3oÞÄñxôQ:áÎ4ÚJ Ÿðõ¯ÑÑ´¾wE¯^ ¿?¬f~~FV Ÿ_}æJø®öî‘ ë;}Ý/P™‹ìl4°³\Ú¶Íö‡Y´o/v y.4”– t(3k×½]´Hu Nƒ Îcô¿¢ôöÛ´oŸ{ÿ-ºëS½µ ž?„›” b„º>G´Ø‰³g‘ÁïØÑÚ9öÜk×ÞÁwð ÆÒR>e&»[ìδj…ùªnŠk§)Ƀ·oÉ爽›I“èøq­oËýÑ­­[§õMšJ¿ÿûŠõû‡j2+Jeüò X‰ØVqÔ†gÛ‚8¦–Ql·k.-èSf*ì¾üø%êÓ³ŽÀžä[ïîÿž8·¥F ÔþðƒÄág÷ø1j;¶•…Ý»QˆË§¦GdvܬÔââáÍé4±õòå0þ“„èP@éð–ðëkÚ‚‘ÞÙ[”ÂWäûq62|Ö*VD¯ÄÂ…¨þaÉ’<œ92ÁZoüxh½&M õî™wÇ{µjèp1‹Æº¬kW•£OºM|W>¨^#cdeÑW_!EêF=A‘ó(¬¸µdf¢Ñ£<ö—^‚-B5ß“à-Ú²¥ÔCCQgûôÓˆ«Lžì…öCX¿¾:aa>ªÍ›«–R0ô)-(\p:á52ÁÑ£T¯õëçÎlhMÚÚÇ®O¦§#ZÎÞP™2ô⋨Æv§ö-%ã±—½ctËÉÑ£q.î±ÌÝš50,'NT“tèâE\ó¯¿\½ŽäÒt§Á÷Y¶¬N¥:Ë…þ‚2=G5SŽP|AJ°Àço ׯÄ~ûmDÝY5ð_Ê»å;¡ª€Í˜%D7^ºšž=q ZµB“Ë=™§ã?“ÿÆgž¡C‡Ô¿¸Úš\iÜÓ¼|ÈQè6n@†úvöÈ^xA¿µšgšÐ¹²ì–;ùë,$hêTäÖ+WÆt_¥sçÔ¼CwG£Fj–O°}Ågó“O @X÷ïO+V¸ ÷ £`KcéR(å/¾ÈfÉ&Íã;9’Æí¤¥=ËL) @˜|þ9ÌN}á]*Jqí‰Ê½NäÚ0Ý °÷Þ|;ü±Ç@ÈÉVèý691?z÷6ÓaîXn;†ÄÍ+¯ä“_}ú©{Û¤Œõ+b C%Þy‡^}Õ™ò$w”– ô,3é_·‚™®Z*¤°b†}’Bô=‘Õá¤öƒ/Š’ή]qÀ›5“Ú5÷©å9aêÃEZâìew럑wÎðáP@÷Cº-5±J¶Ÿù¹Éi(ÍÈ@}Ë´iüŠ[KK:—™dZW­&ïèd¾^P]ÚþºØ%²²pðgÍÂP*Þ`liwïN3f /ïÆ ±Këluaûc¬e¢¢0OaìXdoK—Æ7)‰¸û‰Æ™k­Z5HN˜ÆÄàlîÜiׇ]oäa=¨è_f²…ðá‡Ðž³gk\BœE©tEnš;:yö?†_YªŠ‡ûôA/ð¶mzQ"ªÃÛ¥¹fqátèäÉø›‘5jÀ a«rÿ~í§{ËljðÁŸz ͹šàÀ„Û$µS¥‘‡]Þöz€Â&¡s±I]º`¦ =Œ‚àÓ—¼«i¶:ŒÏ°0Z¹ò³C(¶?;wFFã—_È×÷‰&%Ü-;‰íÛAžÆ.ë‹òåaÒ¼ú*2¼ î+3ÒüˆØg•ñÃÓ%±;ðì³àÕ1 ‹-Ù<¨]³:þMMÆ–-HŽtíê|‡—+8]’|ªÁºVÀnѦMpØÌaIc߶-Âw|”6oF«þ¥hf&â®]8}'„öð€9]½:ÊþGBû3Q:ùª-Xüú+Ç{ïéÅÅ<‰ËüP½Ø’(›LNÄ·Á-d&®™3a\M*•Zóüt¶0ÝÖ=ùal,šeæÏGÎý•W ýÙ0+Y Ÿ·ß¦Ï>CviéRÄúöîÅ Û³ga±Í ³ÄaHÊÅû Nô˜18el7²T,V \@l3³%ÉÂíZøÚþþïÇMáå…ÉæmÚ@êéé˜cg (Å ;óÇU¾¬Óp ™I†™M}ûæP¯ÈI FÕ¤Ì"D}‰Ü°uŽ=¦“'Ÿÿùgd6YX±UУlц áÿòK/ZßtìIË•y6ã-Õòñ3g1Ëò–/_pÐ œâZµ0¡µ@3_üs6}Yzwê„O˜€%V¯FìÂ3ü´Ýº¹S«¬ðëëÜZ ‚åXÕªw;¯…rµñÆã‹ÿñ‡‹;¥ë\Ÿ”&8v »ˆôõëÅ6eDQbAŠ šET•è;ki–ìoß_~ôh xôQ*\ؼäŸ×¬ ‚‘a²²“ÈÆOT”jñ´qã`…þ2D]Øðfq´`^9è Ø·:‘½f \maapLDStÚeƒ[˜šd˜y׬"x|f!¬7mªñïÿd9ÕãðìÇ’%4dˆÖ7¡5®]ƒ)^±"¨Vk«‘ŒQ£àJ°è€ÐP(‘5kd¬e'ÜÅ='CIÞÚµ³+gG—«È0ØPâÿúùÙ¾:Å• /}”4Ü'`s¥E ­oB;ܸtp¥JÈì¸ ý놷k‡n_98qA9½ÉL}’™;,óç£Ò¦O( HL„jRª“6mÂ÷ÑÑV/{~-E¦,{C÷.^DÍ̽ÝÉhiièY`9п¿6¥ Î!× gQ_¿¾< èÄ.”´œ=Ð3)œY¤¤äl9 bsÜ8Ä„r1{6x׌# Ë–åÍBzš6uv»ÿÁxÀýÆ|»•óæ!4׫—u¯G˜¸¢‘‘#ìU©kØ&ΞEãë¯%-gôL g 7oZ›ÅŠ!1› ¶bžyÕ. "" î ÌŒ8ºæAç‚¥Üô0B£FnãÚ¸ˆôtŒkám÷Ê+¨òr#°e¶.ý76ü.:Hè4bbÐîÄÏPWp/÷\±Øÿ\³á>Àœu3o»~ýÜ̪T`3#|çÚü?úHÖ âÞÏ='i„ºýpG÷\Ur†qãðõË/h7¹‹ [é|AÊL'ºEô;‘.k†ïU¬Y“÷eÜ+ˆˆ ÷ßÇ!>Ü-ç•XrÃó#%VߪUâïé_\»™¹d‰¼í„·Û‡3g í4È;;èúûyÍîé>«föUï%ð_ôæ›ØgãÇË‹ï© ënx~„„ $“Ò–u{‰£GëŽ{ܽŠÛ øãkŒ’]»¢·ïn/Ef<Ò=§H¹µÿüª BîØÝ‘•k¹E Ô /Z$•AE8Í;´r%˜dRK]¾ŒœE§NzÜ<îSÜž”„(¦ÉÊ0Ï4¼°wéŸòâïë?XÆ“Oº_*ÄW®`4‹‹—^¢­[ݸ¬T)JwšwhæLtÑÊìë¼}µƒMšè‘ÐMÜóyórh¼ããáÕ¯OEŠ Ù‡Íä<÷žû„/î"z/]-H7¬ ¡)S¨^=HÎqãP—ûŸä=Pp°œ\¶ ̼W^{ VŠ¥!‰n ¥ÆR¨ai ¶Ïùà¬_ïÀ¯lÙ¢ÎÒ±±`9–Cqìtij*hÜØÜñnJûÛ{ ÖYÓ¦!_½:4ûöÚÎ<½÷ðÖ[šuº]¼ˆ¨7û,'»w§+À•qïÁÅKçÀ"ºreLš°ìþ©Ûó¥ÿêq·}ÎÈN…yyæ‡1<ÞzÆ°ùû÷Gg‡üÈö=‰™3e»o§NaœP³fØ®ü*×­³ÖíàÖÈ5,…Îß±6Ú{ÌÆè ¶E¿øgÊ×WåÕùåÖ¨xœž¡o8ÛŸ’Š²À¢ÓÉ+\º¶8vßø/m׳#"T½Åû ,¯ºu¾Jf&oÙGxâ ĸÙkcbibæ½M K †—k¥Š…ùСyèkÕ/ºy3H;5øX‡Ž=tàl9:ñ2Q¢G‰\›I—–†ÀË{ïÁ[¯WFŽDm“[Œ²ÒØkóôuñ“'A¹Ùµ+´[óæ£s?”@(±{­ KcddÀ’·äAHpœÝ…¯RŸz‚ÅyPºâùm³ñy;Áððaô}t耜oË–{úøèzdª~žŠ|Á.ÀêÕôÎ;°$k׆F[¿}(÷rE¥¶†¥1bcŸü'oÌi¢'àF|•zóÐÚÐÆÇÅ.ÁÇ×.”$5h€¿½gOtÒùù鎊JW` Ó•‚pVX'N N2hø‚x×ñc_°àþ •H΃;¾%vsç7ñ­Êè? ¤@?zv&].L¾{]Y¬\‰²çF¨tijÚ]Elüœ=+ïÜl™³AîRS1¨wÆ ¸ÛåËÃ’ìßÔj¡¡nLä4ô®´Ž%KèÙgQ¬¥Üª&±7Á£=”ÝäÒš­ž–†ý<{6&V¯ŽŠ‹=Ü´ÉÖ àû£GÓ¯¿Úø ›è°‡ A—b©RŽ±Z·.ïÄ‘û ú WÚ¿¸¢E5¾Uw i*ÐÖC«J[úh³t~ðç“>iŠ«TAY[YìȯZ…<Åýf#±ù‘?/põ*¶ C‡¢š‹%$êï½×;8ø¿ø°ÕV D –7ÐÜÊèÄ絊‡._l^?B©”¤W_øÒ%ÔîNŸû³n]‡gžÏ”)´|9,«{»æ“½¤—_&//š?½ümÛÂç-ݲ%êR.Dê½Ô¢è"ÜKT’QÐ’©ªUua »‘{NZˆÍ—)¹˜a4äDº¯RNIÁ[³¥òýú¡a©LÈV­üå²»k °Ý®ƒïúu„7mBµÏG!.Ñ ¼l{´khvºYrêF['M¡:L‚–ûö!tþ¼¦÷d€âž»‹Ì$™b3›.%ÿŸ‰±W>JðrbÀV(o6vH§N×÷‹/¢‚mÑòåNïÖ îêĉ¨nb—ý}Þ ‡#5ÉÖ©4?3Ñ^wûvpÉòÍ|ü1 : Œ|«|ÃõëãnGŽ¤ÿý6l€jHH@e‘|~÷‚ŽÂ,—;{åÏ=§‹q<Šéë.!MÄæ™9äWêž-Wfi ›mñbdÇGÐ]ûôóôĦ-R„ªUùÝë¯#Q2{6­]‹Ä4+z'ZãùWØ·òõI ½1cpY¾8{[,÷ø¿,;vD“ø¸q™,9Y~òM^¹bñš5jÜ-;ù&pSQiéžù$òþäí¡(!M]U?Ú¡b3¼*ý5@ý˺XıáçïËó»ïhìX ÝkÞbªP!ll‡¾øWX/7k†mÏn5_/ËuÞJdƒyÇUÿæ{rÙÔ…=Eé7nÐSO!,£è§úÑ!ˆ¸í”Š+H ÿÅÄô÷ß×ÑñÑÜ.³£Àþ¢ôˆ3ýüÄß“Ýp¯LP.Ôu@Žv¤-©s©ÿ sç"?þÈmEåÿÛ;ÿ(ï8Žk£l„Ù ÊQ­"÷OíŸ ¤2AûÅ ˆÑB,ªE6‚¶þ]2úZPDŽXöÓÙn3¥ÂÊCf%¹œéºZbš¾÷ýöØwÏwÏÝ=Ï÷×}_ˆÜçÝçîž{?Ÿïçóù~>ÉïDåÌÞÍ£¢\&ˆál¢cêµ[4¸§ªŠ]“u¥ñÎê-)¡µRåûTÌ1,ÙŒ;¶yï;ô¦bh/ ZùM²qç4–œX:IŽsE¥2‘NCC´´LÈ<‹¨UÜJÜ)¡Æü¶XLöùcœÁ h†= ›ã)WWé ñmìÁ =WVTxg“GÈÖ;(Vb•Í`3ž¦¢Ë*‘mNøiœ!afÏVX7â@Åb!;ncoh Ó9>ôÂ,Oaš£bTÓÂz nŽ´ß?CmN”ûäaéRaÃ}xÂàêJ%|pŒËËé¦`9y©Õ²c4¢œ ‡Ð:õf®›7KËò¥s: ÿzÿ’Óev¶¤º¤zT“1ZVèÏ}hJÓvw–8@ûè‡ê9;~7Þ=ª'tpNå?~L[ü­\)ïXO=¢šŒátªVGl2@¤2;[íz$tìðœVf§·—&óó©xʉ6QM ¡= —~ ¬{7p¦ @É•ŽNQJ;bG‘%9Y˜“åyS“Ü ÁR¢åcG@ØRÝ(§ä*VYd}_ÒÒ´ÒIÈ4*¨¬Œ¦$ïd¥h׋«ï¢r”]Éîk8 B()Q£²H¿¥·Ù6‘w;;›¶g‘E£šÿ´áI*Ú£ÜÍ,Õ夢‚6c—]—Þ i˜wïÒFý«VIѧ}4TìE\ó9j²ÜÞ™9œF<%áömÚ"^6,ÑX'!.¹ã"•«Wcþ|ZM!3jõ"ŒÇ•oãùG³Z—¾>”dÊ°Þën;b“;1±g iÊïÛ°5¬ÌÍÀn ¦`pÀL:æNŸSÄÃ[Y” þ$CžäŽ{ȇB4sÇYN¬<°Y; u brÐqù™vLn]¨¬äý¤Ì™L’![rÇ=dUžŸO 5ƒAѦDCÚÀf_ºSÑÕüêÊcà²glB<),¤¹r>$•3ɰ•ªŸúûétÔ9shëiù‘0°ys%ªýÏñô›Ý»©fúIÕ#> WºáàAy…"Uƒ·Ð°“ë3ÚÅS’7A.]ò~¸Or®¸¨®tùffÒ“lW—hSÜ!CË£¶ Ü{ƒâÚ›$¹ßâ!­­ÞTÙE2©VÜ¡èч3Á Ö¬¡/Pâž¹ãõy8›/æ©C±‹§ÑÏXyñ‚VÅ]!HZh/•vÈmÖ,\¾,Ú׈’;cFÁlh  ‹FÐü&þ}8âK9gÎôÕHoÈ7±¨H´q䈴߾D)+£IwŽCNΈ[êêh óÔ)A ƒ"äæROÿüyÑv .üÓŸê endstream endobj 10 0 obj 55959 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000057036 00000 n 0000000165 00000 n 0000000015 00000 n 0000000144 00000 n 0000000481 00000 n 0000000265 00000 n 0000000738 00000 n 0000000717 00000 n 0000000838 00000 n 0000057011 00000 n 0000057101 00000 n 0000057229 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 57282 %%EOF ast-8.3.0/sun210_figures/fronta_bw.pdf0000664000175000017500000005415313004147321014467 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ]½KÎ-¹ÎÚ¯Qì'I=G`À=Û à6î…qꆞ¾3"H檅]SJ=2–RIQAêýyþeü—ÿŸ¿ÿúOÿmÿùÿ÷_ÿ믈ø—›ýÙ{ÿ+üÏßõJW¿;ašÛ¿,Þ”*ó¥üý?ÿÿ_Ï¿býù?ÙŸÿòþûŸ=þ3 ÿËTó Éÿþë¿¿W~qÌy¦dæÌc¸È™sKVNÄ—ó°üTÎ8SWoÎûòʜغBŽ±üVNœ««7'˟̦+äË_åø ]½9¾PÞŸÌSWÈq”ÿÇ»[WoŽíøͬè˜OÉÊyXÑyˆ¡':QtbðCOt¢èÀ .1t¡—(úb1ô•9DÑAbèB'QôÃbè'sˆ¢r61t¡›(úe1Œ'sˆbXÄ0„A,¢Æbž9D‘£2&1 a“(F0‡ÆÈ¢ƒ9Ä0ƒAƒèŒéƒñ> ¯óŒŸœ8®ˆNÌ%Y9ÁˆAïÅÒÔ£Ãò‰Áûm×r‚åƒ÷‹§+¨G‡åƒ÷; +äË'ïì¨+¨G÷ùÉyk ÏpÉÊ1ÖÀO6$e©GD‘ ‚W‰Z’•C¹ ðC s©ðªQ¨ ‚W‰z$+‡(rAð*Q.YêQä‚àU¢†dåE.^%jI–zD¹ ðE sAà‹(f1ÌÁ õÒ'b˜ ŸD‘K…W‰bùÄ`E.^%ŠåƒA¹ ðA sAðªQCWPˆa.Þxé 9Ä0îD‘ ‚W‰bùÄÀ‰"¯Åò‰E.܈a.^5jè 9Ä°sˆ"¯å’¥8E.ü!†¹ ð‡(rA`—æ‚àýJ³~²/1ÌÁ«F¡.^%ê‘,ʼn(rAð*Q.Y9D‘ ‚W‰’¥Eªý¯µ$+‡(Rí·E sA`‹(f1Ì-¢ÈÁ«D±|*4“(rAð*Q,Ÿ Í$Š\¼JË'ƒ(rA`ƒæ‚àU£†®C Sí_Ú¥+(NÄ0Õ~ ¢ÈÁ«D¡|ªý¯õè Š1LµÿU£\WÈ!†•cXŽ>\¼+¬+Y9XŽ>\¼J”I–z„åèÃÁ«D…då Ö@ ð‚QVÎÀÁÝ["5§Éò@àú•Èt,çªü«ù'׋ù‡ ÿúðäJà`)ÿPÝßgJ¤æ´XO¾cKdºE¥CzE=6ôz^¼éz>V¤)¾·ØÖÅ«!½Tø'áãJ`»T÷'Áã:`¹Tö¡[RDX´Ì,Sø £è.3ÂÖ>R(šj>µõ÷ÓÂX]RVÎ[UQ|u%“,-ÚVÇWW ÉÊqÔ@$ßOÜ”,-èXç¼@N-æUwtEýˆåS‹y•]ýúQÅæRÆ]±uE“ïJæýxèŠ&'Ö•zË;¥ê 9Æò‰+Æ4¯ -–O<0¦yE“Ê'¶cšW49¡|¡ûQ.¯øшÈEU^A "ž¹ˆŠKD¹ˆŠK¿Ù‡(Rïu%–Ï/ó!ŠÔû_]‰åóË|ˆ"õþWWbùü2o¢H½ß71LíþÕ–†®hrbùÔ[Q¤Þï°@òGRPÔû_]iüäL 8¨÷¿ºÒ’¬c Ä`œ#YúÑb Ä`ŒG²rŒ5ÀGYúÑb Ä Æ¬g ÄÀï’,-h³bàãHVŽ³£žG²´ ÍˆM—¬ 8LÆ(`8Rï‡j vïø$RVQ4£ˆaêý¯¶Äøe¾Ä0õþw[_1L½ßQ¤ÞÿêJ,_Æ(¢H½ÿÕ•X>¿Ì›(RïåËE©÷¿º˧޲ˆ"õ~ƒyá•-♚¾-"Ê5€-âée˜"¢\¼zêJMÿÕœ\WÈ!ž^†)"Ê5À«7±|â1ˆ¨Ë0E<½ SD”k ♚¾u¦ˆ§—aŠˆRÓÐó“ãDÔe˜Â*~äàý`Ì?´—Óüd’¥+a?\†)¬â‡—a «øAMÿÕ›¦diDXÅa «øe˜Â*~PÓÇŠ›"u¢Íò@àN“ÈtgiZ¥žHˆ¿uü3§D¦ Ó*õl‰Ô‰ Óú4¯D¦ Ëúd©¦õi…D¦5¥²Tì'1£Æ? Xªõ“ˆQߟ„+•úA¼¨í‚5JÝغÀ—ŸEëãzu¯!‹–ÉÉt!“Ó+þ˜œhˆ§ÉÉ$+g0Gûso”¥½¼WÚ…{[¡¬œÉ¨ÄLß’•óDçŒÍòµ?7§®hrbùTo0Gñ *ÑaùÚŸ›WW43±|ª7ïKWæ ü¨ý¹º"d(ŸØ j^ÑÌ„ò…>5¯hfbùăšW43±|ýˆâÐþ1Ì߀+v^A%"†£váˆâÐþ1Ì%U\¢È%U\b8jŽ(íÏÃ\RÅ!Š\RÅ!†³Ôg¢È%Ulb˜KªØD‘KªØÄpÖ.Qä’*1Ì…S,¢È%U`S–v ¶WGà”¥Ws}å‡/˜¼BÎ;¯~9ã²íÂíG²rk ˜)K%º¬A»p{HVÎd Ä |IV΃–váö‘,ei¢.^Å鑬œ5,í—,ei²b`1$+ÇX1xÎ’,ei±b+eåEªú~‰áª]8¢HUÿUœ\²rˆ"UýWq’¥Eªú¯â´$+‡(RÕ÷M wíÂEªú(”•C©ê¿Š“K–JD©êû"†¹ðE©ê¿ŠÓ’,•ˆ(RÕ÷I SÕU'Ö 1LUÿÕ[Vç b˜ª¾¢ÈE€b˜ª¾Qä"Àƒ¦ªÿªN®+äÃTõ_ÕièŠf&”OUÿÕ•–®hfBùTõ݈"43ù¦ªÿÊ£dšœ]á.â™jÿ«F¹® ©|âñQ.ü!ž§ŒQD” ‚·y–ÏÏô%¢Tû_%ŠåËED©ö¿JËçgúQªývˆç-c¥Úo›x¦Úo›ˆRí·M•%tÁý+Ç[Ñ﫪 :ÔdOéQ¨Êø pU^¹¶áP™=Ú ,_Ûp>uE3Ë×6ÜÞºb‡QÞjø›å6Ê[m½á0ÓÖ~+¦4>^!çaùÚz;SW4-±|m½ÅÖMK,_[oçꊦ%–¯­·aºBŽ±|m°ÝÐt"bX¿Ç®‰iűkõpðš~Ž^Ë_!8|͵õF sQÀæÚz#†¹¨ asm½Ã\T±¹¶Þˆa.ª‚ÃØ<•é§r‚cÚŠ[ÅAmb]qT[q«8¬M¬+Žk+n¶‰uÅ‘mÅ­o…W43±Í[üÒå;ÏXq«À[áÍL(_Ü*¬0QS«?>%2ýAaêô°÷R¤æ4Q˜ýö+‘é SŸë"5§ÉÂ4EEHdúÃÂxäy¦DjN‹…iŠŠ-‘éÆÂTΕ(½†…er2‰úŠ³°LN!Q_3Öê~JT=oEgJ3{+:ùÛÐoíðG `Y[poÁ3µ77P´6àÜxA¦ŠÖöÛ^ } hm¾ùäEҽϬ­·½yA+ŠÖÆ›_^ÐÆô-–Õ;ÙóêÐ[Ý)ŽÕ;òé/æ§VP‘VX”âWÁ:pD¯‚Áê»ê9—´,¡hm¶,Ñ©Àâ=«¶ÚÖÒN ZµÑ°–öÙUý. G¿ èYµÉ°ÄDÃ=ÅPÃ=[ûh€j×ÀQ ôìb~,Ѥ0@Oñ§0@HR §ØS G) ÐS ) Ð#‚è)~è= ô; ôˆ…zŠ…zDÂ=ÅŒÂ="Fa€žâEÀ-ÊU±¢`‰5ø' |“#Jè&§QXû¢`v8Ň‚-숪É)6˜&Gd(MNq¡À39"¢9aîÿ ;ÁG$'PKN±ŸÀ,9¢8LrŠû.ÉÁ T’SÌ'0IŽèM ’œâ=a?"7Aƒ8Åz‚ÂzDmÂêç ’#bH·ØK`\Ñš@ ¹Å]äŠÔúÈ-æØ#W”&Gnñ–À¹"4½u¾b™ƒlñ‚6-®õ:¼ ÅEËä/ ‚\-žõv^¤O›ÒÔâ[Ä%ð߯MpʸOÑ­÷â>o-VÖ ·KÚÐÃkEµ~q»&ö‹Ú-ÂÒnÔŸ ;'·èJؾ»b+aOùY ä†+®ÒjEU‚7ÓS w·ˆJp ½â)x‹¦BâK Ÿ[$%h&W%(«W%èÇ·JXš]”@J¼ÅO+ñŠžöÐ-vHmWä$oq“ÀH¼¢&Žx‹™>â1 dÄ[¼$°¯hI "Þb%‹xEJ‚­äóº+J Å·xGؽ¸"$„x‹uâ Ä[œ#p/eðoªÉà^*ÉàÞT‘ñü— 2^ª›ê1&èKåœÃ›ª18‡—Š1öÿnªÅØ“¾TŠÁ“¸©ï·¿— ñ~߇›ê0Xd—Ê0¼KoªÂð¾T„׳)Q¹8(‡_ êÏM*÷…蜷ø-ïDwÅay¿’·¸-o™›ü•II;”Ó7gSÒÔrœC’ ¨YÉÅÚv‚O5Û|§IÀ¶ò8¤[¥É_–Nš¶šU=giÏ‹† Yf)éIÔ^ã[@ÐQ5¬ttýÌ(pˆµ¡¯?\¬xVt¼5‘ýèÆkEH¥»¯%56w‹~R˜4Bü ‘›·c 9¾Å…ÂbÀG›¯ÞºÝsGðí§?EI‡Š,&½ÍZuƒÂ­œ’éJ‡="³§Lf0o<'Ñ·ÏåH@—x{’™#J9dÑõ¾üñz–²……°ùð5c‘×¥#´òëòÉÁôÎß>ê+h랊1"ãCHûCdˆj;HóQ0}Ìr!Ц\\€žål5À¿å÷‚Ûnpy»\z ºzÔ„E’üÐwpà{4NšÝàXWÊÓÀ^ý8SÚ(<{7ÉþmG{õƒÎgÅ ˜Ï†¸LÃáƹ£T[x#líùʧ»ÌN÷PiÉ®XÕzéjÿÜ’1ˤÈhZ© úÿÖbxБeæ^,œ3Ú$NÛåðÖܼAìæWi’ÑN•p¿Iš?4ò\"LÕ#ŠèðQ E¦/Š?^æ¼íøVoàùê³#`¼í¸«7ð@ö§zw$Yí'£ö‚½›µC9è¢ÓûæN‡““Ç¿˜áqÊqk0¦B9ÒÈZΰX ¿*~ítƒ.{“HgØÚÏv8'H£ØÇŒÓîºz·‡ÓQ@@òe€Å’bä_Oî«»âvÀ`ó*ÑêˆÉå;Nþa(¾ÁO$*ÇÀ>H¬G=ït–Ùk¦Ð|Ø_Ÿ®ZÈÀøÊà€Ö ëdÆæZìñõ:0i%9{(¤å&0Àk*ç#-¿fX:äFîöÃÝÄk†…~žÎ'ïP ¯ûáša±‡Ön»ïkÚsâ0j÷s`%´ ?°öT@Ž~¶z¢o¹ L»!‡ÄA{9Íò±®6°yå·ÂÜ{”0`BóÒ'é@ãZ›ˆÚ‹[lÚùw•;SÅh¡?ÙT\Ç6Ço@Åi¶)9F5ïa³ÓÓ¿/ˆ¯vÚIÑ9>#þEÁvÓÔ¼GvÙÜÕìüÉ|Di/s%]€\æñÛGÍãØ÷!«ÙEâæV„Ëé`À`äåþ2 §yÈR€mè%ûÛÓxr+ã­Ùkc¦jw­þñ!t/Î/Hîb¤Hæ‚`-g½ÂLÍ{Æ=¹fìŠC¢_{¤OÍ{HtùŽ‰R”2  `åþMKûlÐ/-†;{3æý¢KS`,X-Œ8™VÖskÓ Ö¯ïhV`,ž£ý˜ØƒtZ·â±i“kuл‚hw­ +Ýßš ƒ\« QbLqjÍyK项*·“¸aRóÞCSar›ÏøŒðœŽsh@5±Ñ.bš˜æ=ðmt¼"èr¥¡ ¾•S× Ñ94ïaY÷Ž‘vÕk Í{à ™×¼Ç­.×¼G“¤Go‚ h_É1zûY›³t41èDiÅ[¡ ¦%g ê•=µOO“s$ýA­œvé]jr,§jÇ>€—ÜÕ¬ÇåhÂÇÊ5ÙNµrçN,Bôá=5áa!s2¾ÓÛh ù%™I{Úï0ŸOí¾Á°0Ÿ4.”¬"‰cn™OR˜ JV׿ٛuð½EøÆuÜ ïÜZÓê4Ò„]ºQVÄ ßù­Q”ÂÀÚgˆØ  ¦[3œ‹ˆÿü.Ž];TôQV¬X Ó1æŸ ¡¤0Rå»ÚĘÚé„õ|–U¨†²ä*µ?x{FîM‚ºEchæ@±…ž^ôåOC#Ý—W0àHû‚M›(s Lu _zZE™eª¬dX(Q c”©¢a1,–kÏ4QÜÀBiˆ¼BOÆÑ4*À4Dç‹Eéòé[ËÊa—»¨íOŠ  ˜X4u\ŽXŒw±rçÊT9“`Ù2Po‰²:}oËœ ¯¨SN p'‰“d8ø 6@k‰~šÊT¹Ð7sgÐ0xÔìÚ_ÅŒ \ \‰»Â‘Àð'–õ~ñ[÷':(Sš÷&wWkÞ›Ü6Ô¼‡µWïÕFrÔƒ‡|êy2ÚšA¢r¬‹©¨¾P¦Šq;®¥:ô0‹r…•ÇB´]~,:JÔ>×¼Ç=J¯y6Cz)0ÊTÍ{¸&Y€4eEO ЮLDÙÀÆ‚•;àpaæ=<–uÔ2±1„„¬¢ÚÐC^—ªä­™Œý«‰ìæ²súÕ®Co`ezä®gÀ3è|ÔèW— ”r× ðy§©",tæS5T8 $°è™±&ð™U ‹žq»6Ä0¹rCâg”a˜Äæq‹Ÿ“ò¿ÅÕµ7X“Ndˆ vjîIJgœŒb„ åz ê&‡°¯c”kb@E|ÁLÿý߸cø©2L^“¬0¤šæK(ôñÌèUš/¡)bü†¸-$mæR1~Ž8}%}<3çEJ¿øGù¡žf¬L3Cñ"‚ë*šG`9DOlïA3Œâ;a9Dks c•#ezÅa@të=Ä·n˨Ð ‹PX Q»_:VÍ ªøhîTl š;iÑÜù@3¬8Lñ0bŽæ·1ÞjîTL2ÍXEílª m˜ý¤{Ç ¢Ð–=Æ¡¡°äê Ü‹åãPü¢\͹! áŠåŠX(Qýç¦êý|œ±XéÌ/ô]Š…R¬Œ¦-qÞæ™AßÕñÖŠAŒ'".W<ô¯y“D Í£X,Ũyô£üØ›«£+Ä3¾ X0EÔ< çÊÍ££ZÔ< …&\ó(,éá52NkEªðšGÆ*Dæ¥m)Š4àHEº/0>Š5£Z¢ÌßI/žvõDœ™¿,Íø‰5ö~Ceþf, /ó·ÜCeþ„Có2ËBæo²ø¼y}®´’Ax7/“wÐ}P&oÚÇÚi2:kD„/“w`»LÞŽyÛËäít×É ¦äR—É›ñÒ\&oFñ2y;–Î.“·Ü]Ëä-ŽâB3,“·c{ÃGºÈB3,“·ÓrdŒ6hƒOQü\&okÍ£ƒÛ‚ø.3·Ó »ÌÜN—#™¹*×ËÌ͈o.37÷Úû¾äNË¥”»íò 7ñóîJ‡°Ìy{*37‰ ^fn§gÆ'Cg/3·#¡ÉÌíäÝ•™Û1•˜ÌÜGr»ÍÓĆVì×N;cCKfn.;ÁZ2sÓéØÚû‹&37}+3·Ø¡2s;¶œLÑ0ɳ°2y;öH-CúboÕÊäíØ•5™¼]<ÂrËÅÔ˜Ô2Ç^ðÇd¼dˆiÇ»ÍÍíf >“É›/‹•ÉÛ/™ÑŠG‚Ís‹f„@”ɛˋv,‚6(“7É"V&oÇgÝdòvP ¬LÞ‚‚ÉäídB–ÉÛ1¹›LÞÆ„É¥%årþ÷Âdþf(f+ó7c šÌß|õ­ÌßÒˆe<>K¬Ìßtsºò_ÆX¸å^ƒM@ív“øR” ­FìÀ‹½å í…Áã§ÌÞŽ”¬ÞæP;hc5”„ Í<ËÕÑA¼›šÀjhV83ÆÓ™k+£Yñ Aᥔ.P¯V\ÎãضÒ6¸ce”„)ÿ뤑¤¬’F±ºh/zƒ-¬S\bÆÇÜI´ÁV;¹c4v:aa k/k¦±+"ÐýBÿ*–b…§f áâøNÆÅ!†áîg9Ÿ3H±(”\rŽfå‚ <Ä' h”Ÿ‚ƒˆ<†fX†F¯À%Ž5ÓPg¼ÏŠòä Ö¦xcŽ5Óˆša±f¡ômîÔf´/Í°Œ é5ÃbÍÄ=2æØî()ú£\†¸l?Îkо2%ôG+ÖVP´/3Ç¿X}ÜϨx’ Ô[1O+¨¸r͇¢·\Ç]Et‡ÃC%ˆÁCô2‡g@?ѱ‚Š£–±œÊ)Ù±š 9Ã;œF¢C4`:  !‹îð+lJ1œ>dwð+Ë8îØ•mÜA¶ê()pÙšŠÌÀ zó©8-÷@É’O1¾„³CÃ";¾ÚÚÿvm`7]ùcn·\V°PÉöÄ2i‰Øx¦ˆXèÆÀاœLðŽŒ#¦&6IGÇ5ÁBi(ÚŽA÷‰«š¡Ød ¢¼Ÿ©lu]ž*ОݳÏr¡}¹Ï2žV0ù‹¦Q®$t)¢i” ›aÑ4ä>i鯠Ûõk3voa„Ñ¢ 0,›âÖ‰ P¬Êáê2Ø¿¨Ê`>GÑÞÆQþ%£Œg§© ‡Åÿ{ѱ{°œ Åš2’­¨g¤nǧ&â؇K¨Ès6@}: †srè¼"Ê;d™%Kgf` å°ÄÓNBns\OG9cQ!§à PùÅX>û¿,G…T¥s\‡ý5…Æ•ÓÚapR~j! £¸ß°€‡+f^¼ðòï‡gH¸œÑ` /7CªšâÁ?%ÚW?L(jOr‰Še€ä!ƒ¹&e07Ø­#ÃgCKŽ2˜3JBÈ`np ò2˜‹\sRë½ æ$Ëx’ñvèT°¹u2þ¶¶ÊHngÜ ôÊû'>UF=Ó/­­2’ÓÞá2’˜®^Frõ7gèXš;±£#ëA3yr4ÃÑÇ<àP› CŒÏâPhjãY([çk)˜»Ž‰ˆšG`Ÿq;þVdFíP´D×<Š¥)ò™}Kó(ªñšGáú4›…¤ÅÑñ°8ŠDe<®b¥GŒÕÁœŸètR‡u„Žš©Œ>Úˆ–gFêP¶³®œÈy\Àç~…í¬“q Az*÷OÆâ ù ˆSó(J‘‘Z¾â_’†ŠÄjP:¢b[÷®yk±¨Ó¿ ¥Ðùtïâ :VÍ£AÞ»æQ,”bÖ<Ê#¡äkÍc<¢]ùšZ¡#,o¹âJb­DJÀߊ,Ô‘-ÇY¾lÁ#*¤‚å+žv™¼éÈäeò6x¤¸LÞÆh§eò6x¤TMg$äŠöäŒû©ÐpøôÝŽ}ä½W4LèU¹‰ÑžVÀ‚­­2yósã2y“Úëeò6FäUtcĹ2ys…ï2yÓËËämð=,”:MŽ*H§Öy]d+ê§A8E…¬Ú< „“àæ±»üÏ¡*M…Ä9ß!›gepÜ>¿Ã6ÏÓáô‡•PjIˆ»‘á&µó æíðSG‰A[â,/“ðr'­]¢Ád¯x†XV‡biò8 ê “Zf”û!û5¼K¢Ì×p. Y¯’¾Œ×Œ²*Û5¨(^¦k¼}.Ëõ"{=§:|v\vëÅÀÑ9Õ1§¬Ö8m3ÝûIì9+Á»$ƒÅçI éçÏàê¡ÀCО:1î{œ•àJâe¹†ï¼ËpÍxúe·æ2[ƒ=ãeµ†‰Ëh '/›5ñɚѪËbÍP¢2XÃïÞË^ —¹& /k5üG\ÆjÆ1.[5ãOÊT=$w®kSL”aÑsNPð!qÏ j‘ªÎ JÁns‚ZŒ­Ì j1´sNPö²SÓžÌÔô°—•šöe¤¦½lÔt¯/³4V“U^"VFi†™“Ms·•IjŠÉ"½ÈJO# ¼ëMöhF¼¬Èa8²:§jNNP‹A¹8A-û‰‘¥ ‡œ –"÷åOúœ N¹K±b^A+eêM…Y‡&4>7V&h(V& 4Âñ[áøa²93Fg™œaì2Yœ±álep†Ó‡ÉÞ +s3Ã4ÊÚŒmF+có$ùœ¶<µ•©ËÓqŒpÆ°:1”Áütt-BãÜœ”  ^ÎI æWTxv(¨ <9Š‚ͨYœàÅQ–eóÊðóï«QVe²xfFMÇý¢,î™)¬'rF¹ÌœŒkÅœlÅœ<å†9}Ê s2È(s:È(sòèBæô…ÌñøÊxGÑ@NFŽgNGŽç±Ó£KnZåßÌœô>]ú¼ýt¥×QåÔ¶±r2œ*sÚÿœ9Ïòýr2>s:>§¿{ºŒ×¯«œŒPÆœQÆœõ|9ëùÁÍ3p,s:p,sb6nó·ŒÇW¦=N%}É‘c÷üæd´5æt6ESñÆÍ:šsÖÓ¸Ùz~ˈ@¡œ˜?¸™lÊ©©V9ö|eìùÁíî§ì’„!¡¢˜påýkP¦3Æ[{ůt,–ÚáûcJlœ}Ž ï·$Ó¡Au:¸ž™Ž'îthš™CQ§c-”éˆXÝéXÂd:”Â&Ý`øæÑ0°íw:f¥LÇlõ‘tÞÙ¾Ž’Á*¦Ã›ŽoU§c§?ÓñíéÕ vÌvn:" X¥CÏtL\BQ¦ƒuÔéغÉthÜ}VÇ-8q”T¥bËL©q• ÝC©ðçý~Á,£w¬¦ä#²†ÄJ7}‡ÄN?^÷7a’é³ëó·žñÕ3~뉯žø­'}ÕèÞZÎ,`íýùœS‘þõ'ê즯®'Öo=_?éß×é_"~ëÉ×HÿGòhZ¤??õg%}¿ÓW×ã¿ýñÙõx‚dúøêéßdÁûþ°Ÿû¿þøóS}ý±ûS®§IàLÿú™tîLÏ“æ´7õ“v+ý·?–!Ãi¥ø­çY} ŒôÓÕô‰-8@¯" A™hŽ Rå§/¯kåà-þrà6Q9p›èœÀ+;ë$‘µ~rðÒVÔ/ ëÊÁÛüåàÅ­¼Ïãxy‹}ïovÂ+¯õ—ƒ—¸rðj9Pê+¯÷—kpåÀ«áËשràˆö±†`óÈîŠ9XGUÆÆ—juå€ZýåÀ2\9N¢wåÀ-­rÌ~¹(3°˜ët,Ÿ2}œÁ±Îô?X‚\Vðߟûù-Ì)PJÿCÅS‰úU{vüÒËdUòß_•Hþ¯=ÿz?9ÿç/ûó_Þÿó¯çÏƙ׳¶N%‹¡66ÃYpY™2—t´+ÑÚ ™¦Ã¼j²”‘ÁMñ”=ïÁÊœ¯àÀ©J´Ù–l÷»GÌÉíýÜÊ0FYù‘gO¥n©¦R¸ž9ê7_aî7šˆL)ŸŸç¼zN–½_Ÿ:ÌÔf˜6©6[ÙTë Ÿ«zHæ`¨òG|ò<ß=k}e&EunÝÏò”Ñ»º‡ŠUkõNœ”+h[Óy­jMgÞªmSê7ÔIÁc3pJÊôôÕ=ü²,[Љ°)SMÌ{†}e¹ÖÌ:§m¥Ì>ä=ì[–eŸUg÷_OCjÎcPËzeÿœá@”ä“•%înYqëuÏÌ1ÌXÍþôóTôö/§j9¢YSÜOžÏWkþ¶Šý!VQŸõLfÏ-ªŽð˜×'mF ¿’ïí{ˆw–e Zæ”|úmf©ìŠÝuŠ¢¶JFêô­ÊªÏçG~~Ÿ¦f nŒ¯¦µ¿V|-§Ì­ïMϲz‚ógù¿ëž³C™wûgF*yÚw=Á²,û|¿÷qUð'ÎaûgíŸ9B‡d¦<¿7RG²fÙø~³JÇ\¸ë]€m&ç ë_ý|š}{Ž,™O¬{ˆDöAòüAEm©lüÌ‹<‚àoµì+ç#Êí÷.§¸*$¡^Õ{ó@Õœéy ,7׈·ïœUçÂz¨{mõ¨žç¡¼)ûî™ñ•]ÏWg!?™}È{ê°×WŸ¿™ä;xsk9gmGóþ=ÓzšòcõÛæA“*+ÊJö(Óÿã4ªÚ€áoÛõß«vó÷iOœ÷‰ìƒäçµÅ²E›ÚP@6mäx†É¹ýÇ}‹Pظ”ó·ä=9¯¡¬èŽªóæhÖîÄ)Túú‹××ý9=EtÍÖøP­íõµPßc¤ç/{ì“ïí{€E•U çkYÖuÞ“ÞU,;ëYg<Ö³QËÓ¾{â~eÙgÕÙýïQ42ô)°` ±9ŒúÕòœ…×xFkH ¡Õ=ÊtúíO«Q4žüÆ_ÿêçӜ֢ZæïF¢ú yþ ¢¶T¶¼FyšÜVƒÑéðûI,§…ß[ª/&ÄÑj DÞ-s<ï.˼“™"Ké+ThœŒö]©|¤¾—I3RAhPU¿-1ª`ÝÛýNB…,]ÕŒ6%ŽQýVBdž¼Œ 1‘Ùb|7À»’;Qìd—èß 6ªoR èR´Yöm&ŒØ|¼êC¾®îÛQ߸õë]Çù¹ ‹N’h^7hCŽÅ¤Ä°2Â&RDÃyº“Å\+Î+@:~)%¢á¼ÝÉbó{§g¿éØæd|HÔDœ›1‘¢E¹ï¡½Dt6¬{áØÏ7‡ž‘%Îïr ŽÄ“æ ‰þÝ`jb•.J³t{Ã⮓œI1”¦Ãk„³º:þ—vû™GÒ[Cv_#.SÕ%ûÆ!›¯‚ktÁuºà]p} ö$b­F"{­ñ©Æ¯êˆÑ⌾᭹Šõb_¢wÓ‰,¶ò7y+Ó¨e%>£n`wTŒTeÕ߯ó—wë:vÿðµj/Å}úv,.Šs¼a¿«Æ'+Ó¨e%>£n@EY Ìʪ¿¹³þÔ¦¨1‡·9€) ¸fäFð¹ºS±F-ÜNJÜß Œ›$ÞÀý»AË9€ÁíœñoÙM¯Õ išy,­|ŽámÕ šÙÅ&põÂk`à—8ž¾a–5@=–3Ä>טQ5êYpY•£^© >í‰[Ïì‚çvÁ3»àñŸ‚ïcåë‚ÇÊqÏgÑÛÀÆõŽÎ’âî÷ 5W±Ë½›Îqbù6 ²|GÐD‰>ûë·ŒÌʲ¿_çoŸ%œãžuìfùŽ°½w¿OìÛi°òu±o„ã†ý¢|HÏË0úÍAÃuƒõ[†NVeÙ_ÑG,ß…×ÃNù—DðKéM™«¾ ˆR©—ƒ:¤Ö¶¨lñ%J w„’w.ßÒûþMbu½ì éÙ4Š*ñ”Ä1Ì ‹ØèWÞwjOeMÒ­\´¬×fYV¿`ì_@ö‹o%û•¤YìÂç‘È«ÖÃìG²ÒØÃù-†Q“Ê°m–ùÔ$¥l±ÏX~ûªý×ÀF8Fv¶ÈW€l,I·^Ô¨«‡éê±ËܨçÒ(G-ú¨9¥±*7êÍa¯XKõ¯ûÊñÏ;9ŽYz×Èшg+’n½ìÍ)D4*WUäîÔ¨E#5§ô¶–¹Q/ z¥ZªTÎ`ntqò&¶Æ¼Hy¿9’];g0¿¹“J8.tÒ^!X„îâ 1VmÉŒ›÷쟲ǿ:ÿ¶Ì:)¨O^mö#gd?B«¥‹_¾¦Ï„QwƒÞbª7êè?æˆY9Ÿ’_¤Æ&e":8CþA†³ÜgRæÛ¢{"}NôªU(Œì![F²öŽyJ«lµù(–žZãÓ¥?÷À±YeõlÕ#ÊÙS:?ç„×S®:Ô)KÜÊáSßïçMýž‰2eÖ•÷ˆ›£ÎÜaV­å¸¤öGÆË \=T`•Xñ=Ѫ£ÝØÞÒA’û9VÈ  ž£ˆgZÎ>žñõýpvOÙ¾çPì=•Ý‰-caÓA¿EÉñsžBe³6?Y_Ý3V—ýgO带^ȵ_½»?½NF€îy¾Qs³×<åùz­8¸“ÀåÈ«'PýúhB=*=­{ð7{M9+Þ“mE÷!Ÿ†óóiBdr>A(ÎuÊ㩧 ’e;„ix²ø>_k}£€²,{—u¦<ïwÏ÷”ìgm¶ ßÓ”e¸:¤p×ü:‚N=µÓoCè•”g|÷ä“ñàÂì]µUOSrüÜ3f•Õ¨Î”·÷œñ•-"{áôXV ¯ã€ù<ÊQÿüçWðŸgðÛ³R„ø‰,O¿“Q'Œèé’ÉÃz¤F$z”÷ùj]2‘ˆ!К҅Rä“>é±Zˆ©~ŽÚ?è•Ì“l}=½û“÷‡pµ݇œŸê˜ÌËVOx`I~gþ™¾~¾3¡øôj¯"`*gþ`/Çm!0­gû (§'-9~îAÏUvæ¹ öÉëùîÙñ•=ó«óÚ×Öµ¯§g¿,›}^Ï'÷HÂÕŠþjPþƘrT—ü³ÄúFÃúioÝþj„„ªu×Ùs ç›N$ 4ÿC2îk“Þ¾¹Å ?éÜ7„Vþ§ö{‡1÷LáΙ…á š{ÅôµÒN*+çîÈoó Š®è͈{±¯t´ëh0ïRêFáP>s;JZ«rßÁ¹µ±ªšS²ÜôÞ§:wÈS¾U‘zÄÚKtï‘>wfá£PÇð¶V³m¾¯¬|3þ,Λыdì*#…Kd·vŸ{ËißÉ à…“uÚú¬?Õ2J¬¬Dgïõ§+Þ*ð÷LS€Šwî¡Æ±J˜†º˜î7%JðÊ’}ËØ| èwJ@§v?ÆîÇØýª”¹£KÔ®½¹†'d5UˆIµ?%°à­¦ÎS œnôx5%Wr”ÐI˜8OcfµVeͺ{T£ê„¯?”e“ŒSeKxª=^áäÏr¨ žØ“Ó½K{aÕ@ÉëÉÔJ”“ ¼ë3K¼^-1v]JàðäÎ’ÎÊMéÉÜ+«|Ënêä·SÝÕÍ›Và®B¢¥ù±ã)ʆ›í팄ôE·:™<ݵ[’Y=‚fFXJKg‹°tþ1±¹KRöÅöwïùÄûuËÒ1\'ìUª+œ§¥˜pg2¢7yc«xQ,4[Z_¿\ñäèf¥~ýaغ÷aþ‘t¾>ùm¨<;µçj&T:µyðhœ–fõHGä°{ɹ˜OqZâÏ£l¥2lRI\ý«ªIû骎âͳ‚­X%Ó¿Gëdúµ¤õ/rͲ«²rnz2­ìª$¶Ù» UFMú'–)¼šT±:Pw(®œŽ~ºz««µ+ gŸ–¢ººFuU‡”2Ö쬮Jb›ÊfOT†ý[ñ‰Ö]Íç§OlU‘ÛØl¹YZ%ÓÇGv*AÞm@Ì•]Ý„]ÝìÕiI§œîÉNüº"‰ÖÏ¢&õ„í²‰x,^à¤IJJFg÷—·zKOwõvWOwõtWÏ×ÕóuõvÿÎó‰îuƒšd±ê[=_WO…§ªdvš>ìtòþ0ÆyJþ•¹Š…88´¯¬–0ñÞ[õÜ[¬pÛ”Vçί˜HU³^ŸâæîO—áC¨"‰§^MÃ÷®a%¯'ý”’øè£WKYF½¿-Χ4¯l’ŪOLÖQ5¸Wa—­eþ3iµÚÈÔzºÕŠo¬§“;à^'Ó°í©îÆŠ–Fj“!-œ%V÷ý4»{¹û[®d2Mܵ\Ƀ˜)Õr%v-Wò<€ºj¹’ÑÙ½\‰R¡»"‰½\É&Ul~ ú• Úùù*ûôÝ8ö‰þ!¸3Dâ.Õ<Š< OfK}5%œ (—ÞÉOª~Œ–Ò.xÏJe=N¸jÖãŸ^Wd¶z¼¾nîO¼¥¯f“,v­qo*¦Ñ:tܽK¢ ÉÜ‘:tú_ïNãÓR©¤õI½:ë»KmTÓww‡ZÁÍ%®¯Çã+ö-/F«Òã‰D6nbÚȧøs²LÖ€Ìt¥ææ?¤J›öO ëbU1þâyä$·TÝSš”¿wJL‡Ý–Nåjw“TW>ÕL$SâañÖðd>RžCb];oP“,æEM^}°;5{ d2Sk]2rstéù|›aH[ßK’ÕUI:×¾•ù,Ãþ©"‰»ŸEMª«óû©c¥";¤š¯Î|êaçSûJ E?ì퇽ý°·ööÃÞzجERæfkt:¬‡e¯²/õ°™kÖTô³~Øù|{¿‡íøžm–ö×qòY]†Õ× LÅ!F–Ç+ ½mêÓné§Óe^:UÕy–{¥‘¦þ)#ôì4> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:41:57-07:00 2013-08-20T08:41:57-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000020541 00000 n 0000022111 00000 n 0000020482 00000 n 0000020351 00000 n 0000000015 00000 n 0000020330 00000 n 0000020605 00000 n 0000020646 00000 n 0000020675 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<484D240D9C8BDF3191FD97E4A80D7A4D><484D240D9C8BDF3191FD97E4A80D7A4D>] >> startxref 22281 %%EOF ast-8.3.0/fcmpmap.c0000664000175000017500000000640613004147321011024 00000000000000/* *+ * Name: * fcmpmap.c * Purpose: * Define a FORTRAN 77 interface to the AST CmpMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the CmpMap class. * Routines Defined: * AST_ISACMPMAP * AST_CMPMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 25-SEP-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "cmpmap.h" /* C interface to the CmpMap class */ F77_LOGICAL_FUNCTION(ast_isacmpmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astWatchSTATUS( astAt( "AST_ISACMPMAP", NULL, 0 ); RESULT = astIsACmpMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_cmpmap)( INTEGER(MAP1), INTEGER(MAP2), LOGICAL(SERIES), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(MAP1) GENPTR_INTEGER(MAP2) GENPTR_LOGICAL(SERIES) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_CMPMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astCmpMap( astI2P( *MAP1 ), astI2P( *MAP2 ), F77_ISTRUE( *SERIES ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/err_ems.c0000664000175000017500000000640513004147321011034 00000000000000/* * Name: * err_ems.c * Purpose: * Implement the "err" module for the EMS error system. * Description: * This file implements an alternative "err" module for the AST * library. It is used to deliver error messages through the * Starlink EMS error message system (Starlink System Note 4) * rather than by the default mechanism. * Copyright: * Copyright (C) 2008 Science and Technology Facilities Council. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (STARLINK) * {enter_new_authors_here} * History: * 6-NOV-1996 (DSB): * Original version. * 16-SEP-2008 (TIMJ): * Use modern EMS interface * {enter_changes_here} */ /* Module Macros. */ /* ============== */ /* Define the astCLASS macro (even although this is not a class implementation). This indicates to header files that they should make "protected" symbols available. */ #define astCLASS /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "err.h" /* Interface to this module */ #include "ems.h" /* Interface to the EMS system */ /* Function implementations. */ /* ========================= */ void astPutErr_( int status, const char *message ) { /* *+ * Name: * astPutErr * Purpose: * Deliver an error message. * Type: * Protected function. * Synopsis: * #include "err.h" * void astPutErr( int status, const char *message ) * Description: * This function delivers an error message and (optionally) an * accompanying status value to the user. It may be re-implemented * in order to deliver error messages in different ways, according * to the environment in which the AST library is being used. * Parameters: * status * The error status value. * message * A pointer to a null-terminated character string containing * the error message to be delivered. This should not contain * newline characters. * Notes: * - This function is documented as "protected" but, in fact, is * publicly accessible so that it may be re-implemented as * required. *- */ /* Local Variables: */ int local_status; /* Local status value */ /* Make a copy of the status value supplied. Then invoke ems_rep_c to report the error message through EMS and to associate the error status with it. Ignore any returned status value. */ local_status = status; emsRep( "AST_ERROR", message, &local_status ); } ast-8.3.0/error.c0000664000175000017500000010036213004147321010526 00000000000000/* * Name: * error.c * Purpose: * Implement error handling functions. * Description: * This file implements the Error module which provides functions * for handling error conditions in the AST library. For a * description of the module and its interface, see the .h file of * the same name. * * Since its initial release, AST has used a global status variable * rather than adding an explicit status parameter to the argument * list of each AST function. This caused problems for the thread-safe * version of AST since each thread needs its own status value. Whilst * it would have been possible for each function to access a global * status value via the pthreads "thread speific data key" mechanism, * the huge number of status checks performed within AST caused this * option to be slow. Instead AST has been modified so that every * function has an explicit status pointer parameter. This though * causes problems in that we cannot change the public interface to * AST because doing so would break large amounts of external software. * To get round this, the macros that define the public interface to * AST have been modified so that they provide a status pointer * automatically to the function that is being invoked. This is how * the system works... * * All AST functions have an integer inherited status pointer parameter * called "status". This parameter is "hidden" in AST functions that * are invoked via macros (typically public and protected functions). * This means that whilst "int *status" appears explicitly at the end * of the function argument list (in both prototype and definition), it * is not included in the prologue documentation, and is not included * explicitly in the argument list when invoking the function. Instead, * the macro that is used to invoke the function adds in the required * status parameter to the function invocation. * * Macros which are invoked within AST (the protected interface) expand * to include ", status" at the end of the function parameter list. For * backward compatability with previous versions of AST, macros which * are invoked from outside AST (the public interface) expand to include * ", astGetStatusPtr" at the end of the function parameter list. The * astGetStatusPtr function returns a pointer to the interbal AST * status variable or to the external variable specified via astWatch. * * Parameter lists for functions that have variable argument lists * (such as astError) cannot be handled in this way, since macros cannot * have variable numbers of arguments. Instead, separate public and * protected implementations of such functions are provided within AST. * Protected implementations include an explicit, documented status * pointer parameter that must be given explicitly when invoking the * function. Public implementations do not have a status pointer * parameter. Instead they obtain the status pointer internally using * astGetStatusPtr. * * Private functions are called directly rather than via macros, and so * they have a documented status pointer parameter that should be * included explicitly in the parameter list when invoking the * function. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008-2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 2-JAN-1996 (RFWS): * Original version. * 8-JAN-1996 (RFWS): * Tidied up. * 26-JAN-1996 (RFWS): * Incorporated changes to prologue style. * 14-JUN-1996 (RFWS): * Added astAt. * 20-JUN-1996 (RFWS): * Added astSetStatus. * 15-JUL-1996 (RFWS): * Sorted out the public interface. * 16-JUL-1996 (RFWS): * Added astWatch. * 18-MAR-1998 (RFWS): * Added notes about functions being available for writing * foreign language and graphics interfaces, etc. * 27-NOV-2002 (DSB): * Added suppression of error reporting using astReporting. * 11-MAR-2004 (DSB): * Add facility to astAt to allow astAt to be called from public * interface without private interface settings over-riding the * public interface settings. * 30-MAR-2005 (DSB): * Added facility to report deferred messages when reporting is * switched back on. * 16-FEB-2006 (DSB): * Improve efficiency by replacing the astOK_ function with a macro * which tests the value of status variable. The pointer which points * to the AST status variable are now global rather than static. * 19-SEP-2008 (DSB): * Big changes for the thread-safe version of AST. * 3-FEB-2009 (DSB): * Added astBacktrace. */ /* Define the astCLASS macro (even although this is not a class implementation) to obtain access to protected interfaces. */ #define astCLASS /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "err.h" /* Interface to the err module */ #include "error.h" /* Interface to this module */ #include "globals.h" /* Thread-safe global data access */ /* C header files. */ /* --------------- */ #include #include #include #include /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* Select the appropriate memory management functions. These will be the system's malloc, free and realloc unless AST was configured with the "--with-starmem" option, in which case they will be the starmem malloc, free and realloc. */ #ifdef HAVE_STAR_MEM_H # include # define MALLOC starMalloc # define FREE starFree # define REALLOC starRealloc #else # define MALLOC malloc # define FREE free # define REALLOC realloc #endif /* Include execinfo.h if the backtrace function is available */ #if HAVE_EXECINFO_H #include #endif /* Module Variables. */ /* ================= */ /* Define macros for accessing all items of thread-safe global data used by this module. */ #ifdef THREAD_SAFE #define reporting astGLOBAL(Error,Reporting) #define current_file astGLOBAL(Error,Current_File) #define current_routine astGLOBAL(Error,Current_Routine) #define current_line astGLOBAL(Error,Current_Line) #define foreign_set astGLOBAL(Error,Foreign_Set) #define message_stack astGLOBAL(Error,Message_Stack) #define mstack_size astGLOBAL(Error,Mstack_Size) /* Since the external astPutErr function may not be thread safe, we need to ensure that it cannot be invoked simultaneously from two different threads. So we lock a mutex before each call to astPutErr. */ static pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER; #define INVOKE_ASTPUTERR( status, buff ) \ ( pthread_mutex_lock( &mutex1 ), \ astPutErr( (status), (buff) ), \ (void) pthread_mutex_unlock( &mutex1 ) ) /* Define the initial values for the global data for this module. */ #define GLOBAL_inits \ globals->Reporting = 1; \ globals->Current_File = NULL; \ globals->Current_Routine = NULL; \ globals->Current_Line = 0; \ globals->Foreign_Set = 0; \ globals->Mstack_Size = 0; \ /* Create the global initialisation function. */ astMAKE_INITGLOBALS(Error) /* If thread safety is not needed, declare globals at static variables. */ /* -------------------------------------------------------------------- */ #else /* Status variable. */ static int internal_status = 0; /* Internal error status */ int *starlink_ast_status_ptr = &internal_status; /* Pointer to status variable */ /* Reporting flag: delivery of message is supressed if zero. */ static int reporting = 1; /* Error context. */ static const char *current_file = NULL; /* Current file name pointer */ static const char *current_routine = NULL; /* Current routine name pointer */ static int current_line = 0; /* Current line number */ static int foreign_set = 0; /* Have foreign values been set? */ /* Un-reported message stack */ static char *message_stack[ AST__ERROR_MSTACK_SIZE ]; static int mstack_size = 0; /* If thread-safety is not needed, we can invoke the external astPutErr function directly. */ #define INVOKE_ASTPUTERR( status, buff ) \ astPutErr( (status), (buff) ); #endif /* Function prototypes. */ /* ==================== */ static void EmptyStack( int, int * ); /* Function implementations. */ /* ========================= */ void astAt_( const char *routine, const char *file, int line, int forn, int *status) { /* *+ * Name: * astAt * Purpose: * Store a routine, file and line number context in case of error. * Type: * Protected function. * Synopsis: * #include "error.h" * void astAt( const char *routine, const char *file, int line, int forn) * Description: * This function stores a pointer to two strings containing the * names of a routine and a file, together with an integer line * number. These values are retained for subsequent use in * reporting the context of any error that may arise. * Parameters: * routine * Pointer to a null terminated C string containing a routine * name (which should reside in static memory). * file * Pointer to a null terminated C string containing a file name * (which should reside in static memory). * line * The line number in the file. * for * Is this call being made from a foreign language interface? * If so any values supplied will take precedence of the values * set by the C interface. * Notes: * - This function returns without action (i.e. without changing * the stored values) if the global error status is set. It * performs no other error checking. * - Any (or all) of the arguments may be omitted by supplying a * NULL or zero value (as appropriate) and will then not be included * in any error report. * - This function is documented as protected because it should not * be invoked by external code. However, it is available via the * external C interface so that it may be used when writing (e.g.) * foreign language or graphics interfaces. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Check the global error status. */ if ( !astOK ) return; /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* If the values refer to a foreign interface, or if no foreign values have yet been set, store the supplied values. */ if( forn|| !foreign_set ) { current_routine = routine; current_file = file; current_line = line; } /* If the values relate to a foreign interface, set a flag which prevents local values set later replacing them. */ foreign_set = forn; } void astBacktrace_( int *status ) { /* c+ * Name: * astBacktrace * Purpose: * Display a backtrace on standard output. * Type: * Protected macro. * Synopsis: * #include "error.h" * astBacktrace; * Description: * This macro displays a set of messages on standard output that * give a backtrace of the caller. It can be useful for debugging AST * code in situations when it is not easy or possible to use a * debugger (for instance, when debugging JNIAST). * Notes: * - Only non-static function names are included in the backtrace. * - This function requires the GNU C library. When called, it will * just issue a warning if the GNU 'backtrace' function was not * available when AST was configured. c- */ #if HAVE_BACKTRACE #define MAX_ADDR 100 /* Local Variables: */ char **strings; /* Pointer to array of formated strings */ char buf[ 120 ]; /* Output line buffer */ int j; /* String index */ int np; /* Number of used return addresses */ void *buffer[ MAX_ADDR ]; /* Array of return addresses */ /* Get the array of return addresses. */ np = backtrace( buffer, MAX_ADDR ); /* Convert them into strings. */ strings = backtrace_symbols( buffer, np ); /* If succesful, display them and then free the array. Note we skip the first one since that will refer to this function. */ if( strings ) { INVOKE_ASTPUTERR( astStatus, " " ); for( j = 1; j < np; j++ ) { sprintf( buf, "%d: %s", j, strings[j] ); INVOKE_ASTPUTERR( astStatus, buf ); } free( strings ); INVOKE_ASTPUTERR( astStatus, " " ); /* If not succesful, issue a warning. */ } else { INVOKE_ASTPUTERR( astStatus, "Cannot convert backtrace addresses into formatted strings" ); } #else INVOKE_ASTPUTERR( astStatus, "Backtrace functionality is not available " "on the current operating system." ); #endif } void astClearStatus_( int *status ) { /* c++ * Name: * astClearStatus * Purpose: * Clear the AST error status. * Type: * Public macro. * Synopsis: * #include "error.h" * void astClearStatus * Description: * This macro resets the AST error status to an OK value, * indicating that an error condition (if any) has been cleared. * Notes: * - If the AST error status is set to an error value (after an * error), most AST functions will not execute and will simply * return without action. Using astClearStatus will restore normal * behaviour. c-- */ /* Empty the deferred error stack without displaying the messages on the stack. */ EmptyStack( 0, status ); /* Reset the error status value. */ *status = 0; } static void EmptyStack( int display, int *status ) { /* * Name: * EmptyStack * Purpose: * Empty the stack of deferred error messages, optionally displaying * them. * Type: * Private function. * Synopsis: * #include "error.h" * void EmptyStack( int display, int *status ) * Description: * This function removes all messages from the stack of deferred error * messages. If "display" is non-zero it reports them using astPutErr * before deleting them. * Parameters: * display * Report messages before deleting them? * status * Pointer to the integer holding the inherited status value. */ /* Local variables; */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int i; /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Loop round all messages on the stack. */ for( i = 0; i < mstack_size; i++ ) { /* Display the message if required. */ if( display ) INVOKE_ASTPUTERR( astStatus, message_stack[ i ] ); /* Free the memory used to hold the message. */ FREE( message_stack[ i ] ); message_stack[ i ] = NULL; } /* Reset the stack size to zero. */ mstack_size = 0; } void astErrorPublic_( int status_value, const char *fmt, ... ) { /* *+ * Name: * astError * Purpose: * Set the AST error status and report an error message. * Type: * Protected function. * Synopsis: * #include "error.h" * void astError( int status_value, const char *fmt, ... ) * Description: * This function sets the AST error status to a specified value and * reports an associated error message. * Parameters: * status_value * The new error status value to be set. * fmt * Pointer to a null-terminated character string containing the * format specification for the error message, in the same way * as for a call to the C "printf" family of functions. * ... * Additional optional arguments (as used by e.g. "printf") * which specify values which are to appear in the error * message. * Notes: * This function operates just like "printf", except that: * - The first argument is an error status. * - The return value is void. * - A newline is automatically appended to the error message * (there is no need to add one). * - This function is documented as protected because it should not * be invoked by external code. However, it is available via the * external C interface so that it may be used when writing (e.g.) * foreign language or graphics interfaces. *- * This is the public implementation of astError. It does not have an status pointer parameter, but instead obtains the status pointer explicitly using the astGetStatusPtr function. This is different to other public functions, which typically have a status pointer parameter that is supplied via a call to astGetStatusPtr within the associated interface macro. The benefit of doing it the usual way is that the public and protected implementations are the same, with the differences between public and protecte dinterfaces wrapped up in the associated interface macro. We cannot do this with this function because of the variale argument list. The prologue for the astError_ function defines the interface for use internally within AST. */ /* Local Constants: */ #define BUFF_LEN 1023 /* Max. length of an error message */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char buff[ BUFF_LEN + 1 ]; /* Message buffer */ int *status; /* Pointer to inherited status value */ int imess; /* Index into deferred message stack */ int nc; /* Number of characters written */ va_list args; /* Variable argument list pointer */ /* Initialise the variable argument list pointer. */ va_start( args, fmt ); /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the integer holding the inherited status value. */ status = astGetStatusPtr; /* If this is the first report of an error (the global status has not previously been set) and error context information is available, then construct an error context message. */ if ( astOK && ( current_routine || current_file || current_line ) ) { nc = sprintf( buff, "AST: Error" ); if ( current_routine ) { nc += sprintf( buff + nc, " in routine %s", current_routine ); } if ( current_line ) { nc += sprintf( buff + nc, " at line %d", current_line ); } if ( current_file ) { nc += sprintf( buff + nc, " in file %s", current_file ); } nc += sprintf( buff + nc, "." ); /* Deliver the error message unless reporting has been switched off using astReporting. In which case store them in a static array. */ if( reporting ) { INVOKE_ASTPUTERR( status_value, buff ); } else if( mstack_size < AST__ERROR_MSTACK_SIZE ){ imess = mstack_size++; message_stack[ imess ] = MALLOC( strlen( buff ) + 1 ); if( message_stack[ imess ] ) { strcpy( message_stack[ imess ], buff ); } } /* Set the global status. */ astSetStatus( status_value ); } /* Write the error message supplied to the formatting buffer. */ nc = vsprintf( buff, fmt, args ); /* Tidy up the argument pointer. */ va_end( args ); /* Deliver the error message unless reporting has been switched off using astReporting. */ if( reporting ) { INVOKE_ASTPUTERR( status_value, buff ); } else if( mstack_size < AST__ERROR_MSTACK_SIZE ){ imess = mstack_size++; message_stack[ imess ] = MALLOC( strlen( buff ) + 1 ); if( message_stack[ imess ] ) { strcpy( message_stack[ imess ], buff ); } } /* Set the error status value. */ astSetStatus( status_value ); /* Undefine macros local to this function. */ #undef BUFF_LEN } void astError_( int status_value, const char *fmt, int *status, ... ) { /* *+ * Name: * astError * Purpose: * Set the AST error status and report an error message. * Type: * Protected function. * Synopsis: * #include "error.h" * void astError( int status_value, const char *fmt, int *status, ... ) * Description: * This function sets the AST error status to a specified value and * reports an associated error message. * Parameters: * status_value * The error status value to be set. * fmt * Pointer to a null-terminated character string containing the * format specification for the error message, in the same way * as for a call to the C "printf" family of functions. * status * Pointer to the integer holding the inherited status value. * ... * Additional optional arguments (as used by e.g. "printf") * which specify values which are to appear in the error * message. * Notes: * This function operates just like "printf", except that: * - The first argument is an error status. * - The return value is void. * - A newline is automatically appended to the error message * (there is no need to add one). * - This function is documented as protected because it should not * be invoked by external code. However, it is available via the * external C interface so that it may be used when writing (e.g.) * foreign language or graphics interfaces. *- * This is the protected implementation of astError. It has a status pointer parameter that is not present in the public form. Different implementations for protected and public interfaces are required because of the variable argument list. */ /* Local Constants: */ #define BUFF_LEN 1023 /* Max. length of an error message */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char buff[ BUFF_LEN + 1 ]; /* Message buffer */ int imess; /* Index into deferred message stack */ int nc; /* Number of characters written */ va_list args; /* Variable argument list pointer */ /* Initialise the variable argument list pointer. */ va_start( args, status ); /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* If this is the first report of an error (the global status has not previously been set) and error context information is available, then construct an error context message. */ if ( astOK && ( current_routine || current_file || current_line ) ) { nc = sprintf( buff, "AST: Error" ); if ( current_routine ) { nc += sprintf( buff + nc, " in routine %s", current_routine ); } if ( current_line ) { nc += sprintf( buff + nc, " at line %d", current_line ); } if ( current_file ) { nc += sprintf( buff + nc, " in file %s", current_file ); } nc += sprintf( buff + nc, "." ); /* Deliver the error message unless reporting has been switched off using astReporting. In which case store them in a static array. */ if( reporting ) { INVOKE_ASTPUTERR( status_value, buff ); } else if( mstack_size < AST__ERROR_MSTACK_SIZE ){ imess = mstack_size++; message_stack[ imess ] = MALLOC( strlen( buff ) + 1 ); if( message_stack[ imess ] ) { strcpy( message_stack[ imess ], buff ); } } /* Set the global status. */ astSetStatus( status_value ); } /* Write the error message supplied to the formatting buffer. */ nc = vsprintf( buff, fmt, args ); /* Tidy up the argument pointer. */ va_end( args ); /* Deliver the error message unless reporting has been switched off using astReporting. */ if( reporting ) { INVOKE_ASTPUTERR( status_value, buff ); } else if( mstack_size < AST__ERROR_MSTACK_SIZE ){ imess = mstack_size++; message_stack[ imess ] = MALLOC( strlen( buff ) + 1 ); if( message_stack[ imess ] ) { strcpy( message_stack[ imess ], buff ); } } /* Set the error status value. */ astSetStatus( status_value ); /* Undefine macros local to this function. */ #undef BUFF_LEN } int *astGetStatusPtr_(){ /* *+ * Name: * astGetStatusPtr * Purpose: * Return a pointer to the integer holding the inherited status value. * Type: * Protected function. * Synopsis: * #include "error.h" * int *astGetStatusPtr; * Description: * This macro returns a pointer to the integer holding the inherited * status pointer. This will either be an internal global integer * (possibly stored as thread specific data), or an ineger specified * via the astWatch function. * Returned Value: * A pointer to the integer holding the inherited status value. *- */ /* The thread-safe version of AST stores the status pointer in thread specific data, using the key stored in the global variable "starlink_ast_status_key". */ #if defined(THREAD_SAFE) astDECLARE_GLOBALS AstStatusBlock *sb; astGET_GLOBALS(NULL); sb = (AstStatusBlock *) pthread_getspecific(starlink_ast_status_key); return sb->status_ptr; /* The non thread-safe version of AST stores the status pointer in the global variable "starlink_ast_status_ptr". */ #else return starlink_ast_status_ptr; #endif } /* c++ * Name: * astOK * Purpose: * Test whether AST functions have been successful. * Type: * Public macro. * Synopsis: * #include "error.h" * int astOK * Description: * This macro returns a boolean value (0 or 1) to indicate if * preceding AST functions have completed successfully * (i.e. without setting the AST error status). If the error status * is set to an error value, a value of zero is returned, otherwise * the result is one. * Returned Value: * astOK * One if the AST error status is OK, otherwise zero. * Notes: * - If the AST error status is set to an error value (after an * error), most AST functions will not execute and will simply * return without action. To clear the error status and restore * normal behaviour, use astClearStatus. c-- */ int astReporting_( int report, int *status ) { /* c+ * Name: * astReporting * Purpose: * Controls the reporting of error messages. * Type: * Protected function. * Synopsis: * #include "error.h" * int astReporting( int report ) * Description: * Error messages supplied to astError will only be delivered to the * underlying error system if the "Reporting" flag is set to a * non-zero value. Setting this flag to zero suppresses the reporting * of error messages (the value of the AST error status however is * unaffected). Instead, the reports are saved in an internal message * stack. When reporting is switched back on again, any messages on this * stack of deferred messages will be reported (and the stack emptied) * if the AST error status is not astOK. Also the stack is emptied each * time astClearStatus is called (the stacked messages are not displayed * in this case). * Parameters: * report * The new value for the Reporting flag. * Returned Value: * The original value of the Reporting flag. * Notes: * - The Reporting flag is initially set to 1. c- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int oldval; /* Original "reporting" value */ /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Save the original reporting value, and then store the new value. */ oldval = reporting; reporting = report; /* If we are now reporting errors, flush any messages on the error stack. This causes the messages to be displayed and the stack emptied. */ if( reporting ) EmptyStack( 1, status ); /* Return the original reporting value. */ return oldval; } /* c++ * Name: * astSetStatus * Purpose: * Set the AST error status to an explicit value. * Type: * Public function. * Synopsis: * #include "error.h" * void astSetStatus( int status_value ) * Description: * This function sets the AST error status to the value supplied. * It does not cause any error message to be produced and should * not be used as part of normal error reporting. Its purpose is * simply to communicate to AST that an error has occurred in some * other item of software. * * For example, a source or sink function supplied as an argument * to astChannel or astFitsChan might use this to signal that an * input/output error has occurred. AST could then respond by * terminating the current read or write operation. * Parameters: * status_value * The new error status value to be set. * Notes: * - If the AST error status is set to an error value, most AST * functions will not execute and will simply return without * action. To clear the error status and restore normal behaviour, * use astClearStatus. c-- */ /* c++ * Name: * astStatus * Purpose: * Obtain the current AST error status value. * Type: * Public function. * Synopsis: * #include "error.h" * int astStatus * Description: * This function returns the current value of the AST error status. * Returned Value: * astStatus * The AST error status value. * Notes: * - If the AST error status is set to an error value (after an * error), most AST functions will not execute and will simply * return without action. To clear the error status and restore * normal behaviour, use astClearStatus. c-- */ int *astWatch_( int *status_ptr ) { /* c++ * Name: * astWatch * Purpose: * Identify a new error status variable for the AST library. * Type: * Public function. * Synopsis: * #include "error.h" * int *astWatch( int *status_ptr ) * Description: * This function allows a new error status variable to be accessed * by the AST library when checking for and reporting error * conditions. * * By default, the library uses an internal integer error status * which is set to an error value if an error occurs. Use of * astWatch allows the internal error status to be replaced by an * integer variable of your choosing, so that the AST library can * share its error status directly with other code which uses the * same error detection convention. * * If an alternative error status variable is supplied, it is used * by all related AST functions and macros (e.g. astOK, astStatus * and astClearStatus). * Parameters: * status_ptr * Pointer to an int whose value is to be used subsequently as * the AST inherited status value. If a NULL pointer is supplied, * the AST library will revert to using its own internal error status. * Returned Value: * astWatch() * Address of the previous error status variable. This may later * be passed back to astWatch to restore the previous behaviour * of the library. (Note that on the first invocation of * astWatch the returned value will be the address of the * internal error status variable.) * Notes: * - This function is not available in the FORTRAN 77 interface to * the AST library. c-- */ /* Local Variables: */ int *result; /* Value to be returned */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ #if defined(THREAD_SAFE) AstStatusBlock *sb = NULL; #endif /* Ensure that the thread-specific status block has been created and ininitialised. */ astGET_GLOBALS(NULL); #if defined(THREAD_SAFE) sb = (AstStatusBlock *) pthread_getspecific( starlink_ast_status_key ); result = sb->status_ptr; sb->status_ptr = status_ptr ? status_ptr : &(sb->internal_status); #else result = starlink_ast_status_ptr; starlink_ast_status_ptr = status_ptr ? status_ptr : &internal_status; #endif /* Return the old address. */ return result; } ast-8.3.0/pointlist.h0000664000175000017500000001675213004147321011440 00000000000000#if !defined( POINTLIST_INCLUDED ) /* Include this file only once */ #define POINTLIST_INCLUDED /* *+ * Name: * pointlist.h * Type: * C include file. * Purpose: * Define the interface to the PointList class. * Invocation: * #include "pointlist.h" * Description: * This include file defines the interface to the PointList class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The PointList class implements a Region which represents a collection * of points in a Frame. * Inheritance: * The PointList class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-AUG-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "region.h" /* Coordinate regions (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* PointList structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPointList { /* Attributes inherited from the parent class. */ AstRegion region; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *lbnd; /* Lower axis limits of bounding box */ double *ubnd; /* Upper axis limits of bounding box */ } AstPointList; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPointListVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetListSize)( AstPointList *, int * ); void (* PointListPoints)( AstPointList *, AstPointSet **, int * ); } AstPointListVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstPointListGlobals { AstPointListVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstPointListGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitPointListGlobals_( AstPointListGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(PointList) /* Check class membership */ astPROTO_ISA(PointList) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPointList *astPointList_( void *, AstPointSet *, AstRegion *, const char *, int *, ...); #else AstPointList *astPointListId_( void *, int, int, int, const double *, AstRegion *, const char *, ... )__attribute__((format(printf,7,8))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPointList *astInitPointList_( void *, size_t, int, AstPointListVtab *, const char *, AstFrame *, AstPointSet *, AstRegion *, int * ); /* Vtab initialiser. */ void astInitPointListVtab_( AstPointListVtab *, const char *, int * ); /* Loader. */ AstPointList *astLoadPointList_( void *, size_t, AstPointListVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astGetListSize_( AstPointList *, int * ); void astPointListPoints_( AstPointList *, AstPointSet **, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPointList(this) astINVOKE_CHECK(PointList,this,0) #define astVerifyPointList(this) astINVOKE_CHECK(PointList,this,1) /* Test class membership. */ #define astIsAPointList(this) astINVOKE_ISA(PointList,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astPointList astINVOKE(F,astPointList_) #else #define astPointList astINVOKE(F,astPointListId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPointList(mem,size,init,vtab,name,frame,points,unc) \ astINVOKE(O,astInitPointList_(mem,size,init,vtab,name,frame,points,unc,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPointListVtab(vtab,name) astINVOKE(V,astInitPointListVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPointList(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPointList_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckPointList to validate PointList pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetListSize(this) \ astINVOKE(V,astGetListSize_(astCheckPointList(this),STATUS_PTR)) #define astPointListPoints(this,pset) \ astINVOKE(V,astPointListPoints_(astCheckPointList(this),pset,STATUS_PTR)) #endif #endif ast-8.3.0/channel.c0000664000175000017500000067536213004147321011026 00000000000000/* *class++ * Name: * Channel * Purpose: * Basic (textual) I/O channel. * Constructor Function: c astChannel f AST_CHANNEL * Description: * The Channel class implements low-level input/output for the AST * library. Writing an Object to a Channel will generate a textual * representation of that Object, and reading from a Channel will * create a new Object from its textual representation. * * Normally, when you use a Channel, you should provide "source" c and "sink" functions which connect it to an external data store f and "sink" routines which connect it to an external data store * by reading and writing the resulting text. By default, however, * a Channel will read from standard input and write to standard * output. Alternatively, a Channel can be told to read or write from * specific text files using the SinkFile and SourceFile attributes, * in which case no sink or source function need be supplied. * Inheritance: * The Channel class inherits from the Object class. * Attributes: * In addition to those attributes common to all Objects, every * Channel also has the following attributes: * * - Comment: Include textual comments in output? * - Full: Set level of output detail * - Indent: Indentation increment between objects * - ReportLevel: Selects the level of error reporting * - SinkFile: The path to a file to which the Channel should write * - Skip: Skip irrelevant data? * - SourceFile: The path to a file from which the Channel should read * - Strict: Generate errors instead of warnings? * Functions: c In addition to those functions applicable to all Objects, the c following functions may also be applied to all Channels: f In addition to those routines applicable to all Objects, the f following routines may also be applied to all Channels: * c - astWarnings: Return warnings from the previous read or write c - astPutChannelData: Store data to pass to source or sink functions c - astRead: Read an Object from a Channel c - astWrite: Write an Object to a Channel f - AST_WARNINGS: Return warnings from the previous read or write f - AST_READ: Read an Object from a Channel f - AST_WRITE: Write an Object to a Channel * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 12-AUG-1996 (RFWS): * Original version. * 6-SEP-1996: * Finished initial implementation. * 11-DEC-1996 (RFWS): * Added support for foreign language source and sink functions. * 28-APR-1997 (RFWS): * Prevent "-0" being written (use "0" instead). * 27-NOV-2002 (DSB): * Added astWriteInvocations. * 8-JAN-2003 (DSB): * - Changed private InitVtab method to protected astInitChannelVtab * method. * - Modified to use protected Vtab initialisation methods when * loading an Object. * 1-NOV-2003 (DSB): * Change the initialiser so that it accepts source and sink * wrapper functions as arguments (for use by derived classes). * 16-AUG-2006 (DSB): * - Document non-destructive nature of unsuccessful astRead calls * on a FitsChan. * 3-OCT-2008 (DSB): * Added "Strict" attribute. * 11-DEC-2008 (DSB): * Added astPutChannelData and astChannelData functions. * 16-JAN-2009 (DSB): * Added astAddWarning and astWarnings. * 11-JUN-2009 (DSB): * Enable astChannelData to be used from within astRead. * 7-DEC-2009 (DSB): * Added Indent attribute. * 12-FEB-2010 (DSB): * Represent AST__BAD externally using the string "". * 23-JUN-2011 (DSB): * Added attributes SinkFile and SourceFile. * 2-OCT-2012 (DSB): * Report an error if an Inf or NaN value is read from the external * source. *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 Channel /* Define a string containing the maximum length of keywords used to identify values in the external representation of data. This is deliberately kept small so as to simplify integration with standards such as FITS. */ #define MAX_NAME "8" /* Max length of string returned by GetAttrib */ #define GETATTRIB_BUFF_LEN 50 /* String used to represent AST__BAD externally. */ #define BAD_STRING "" /* Include 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 "channel.h" /* Interface definition for this class */ #include "loader.h" /* Interface to the global loader */ #include "keymap.h" /* Storing arbitrary data in an AST Object */ #include "pointset.h" /* For AST__BAD */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* 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->AstReadClassData_Msg = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->Items_Written = 0; \ globals->Current_Indent = 0; \ globals->Nest = -1; \ globals->Nwrite_Invoc = 0; \ globals->Object_Class = NULL; \ globals->Values_List = NULL; \ globals->Values_Class = NULL; \ globals->Values_OK = NULL; \ globals->End_Of_Object = NULL; \ globals->Channel_Data = NULL; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Channel) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Channel,Class_Init) #define class_vtab astGLOBAL(Channel,Class_Vtab) #define astreadclassdata_msg astGLOBAL(Channel,AstReadClassData_Msg) #define getattrib_buff astGLOBAL(Channel,GetAttrib_Buff) #define items_written astGLOBAL(Channel,Items_Written) #define current_indent astGLOBAL(Channel,Current_Indent) #define nest astGLOBAL(Channel,Nest) #define nwrite_invoc astGLOBAL(Channel,Nwrite_Invoc) #define object_class astGLOBAL(Channel,Object_Class) #define values_list astGLOBAL(Channel,Values_List) #define values_class astGLOBAL(Channel,Values_Class) #define values_ok astGLOBAL(Channel,Values_OK) #define end_of_object astGLOBAL(Channel,End_Of_Object) #define channel_data astGLOBAL(Channel,Channel_Data) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); static pthread_mutex_t mutex3 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX3 pthread_mutex_lock( &mutex3 ); #define UNLOCK_MUTEX3 pthread_mutex_unlock( &mutex3 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Contextual error message reported in astReadClassData? */ static int astreadclassdata_msg = 0; /* Buffer returned by GetAttrib. */ static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ]; /* Count of the number of output items written since the last "Begin" or "IsA" item. */ static int items_written = 0; /* Amount of indentation to be applied to the next output item. */ static int current_indent = 0; /* Nesting level, used to keep track of data associated with building Objects when they contain other Objects. */ static int nest = -1; /* The number of times astWrite has been invoked. */ static int nwrite_invoc = 0; /* Pointer to a user-supplied block of memory to be made available to source or sink functions via the astChannelData function. */ static void *channel_data = NULL; /*** The following items are all pointers to dynamically allocated arrays (stacks) that grow as necessary to accommodate one element for each level of nesting (one more than the value of "nest"). ***/ /* Stack of pointers to null-terminated character strings giving the names of the classes of the Objects being built at each nesting level. */ static char **object_class = NULL; /* Stack of pointers to the elements designated as the "heads" of circular, doubly linked lists of name-value associations. */ static AstChannelValue **values_list = NULL; /* Stack of pointers to null-terminated character strings giving the names of the classes for which the values held in the values lists are intended. */ static char **values_class = NULL; /* Stack of flags indicating whether the values held in the values lists are intended for the class loaders currently executing to build Objects at each nesting level. */ static int *values_ok = NULL; /* Stack of flags indicating whether "End" items have been read for the Objects being built at each nesting level. */ static int *end_of_object = NULL; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstChannelVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #define LOCK_MUTEX3 #define UNLOCK_MUTEX3 #endif /* External 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. */ AstChannel *astChannelForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); AstChannel *astChannelId_( const char *(*)( void ), void (*)( const char * ), const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstObject *Read( AstChannel *, int * ); static AstObject *ReadObject( AstChannel *, const char *, AstObject *, int * ); static AstChannelValue *FreeValue( AstChannelValue *, int * ); static AstChannelValue *LookupValue( const char *, int * ); static AstKeyMap *Warnings( AstChannel *, int * ); static char *GetNextText( AstChannel *, int * ); static char *InputTextItem( AstChannel *, int * ); static char *ReadString( AstChannel *, const char *, const char *, int * ); static char *SourceWrap( const char *(*)( void ), int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static double ReadDouble( AstChannel *, const char *, double, int * ); static int GetComment( AstChannel *, int * ); static int GetFull( AstChannel *, int * ); static int GetSkip( AstChannel *, int * ); static int GetStrict( AstChannel *, int * ); static int ReadInt( AstChannel *, const char *, int, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestComment( AstChannel *, int * ); static int TestFull( AstChannel *, int * ); static int TestSkip( AstChannel *, int * ); static int TestStrict( AstChannel *, int * ); static int Use( AstChannel *, int, int, int * ); static int Write( AstChannel *, AstObject *, int * ); static void AddWarning( AstChannel *, int, const char *, const char *, int * ); static void AppendValue( AstChannelValue *, AstChannelValue **, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearComment( AstChannel *, int * ); static void ClearFull( AstChannel *, int * ); static void ClearSkip( AstChannel *, int * ); static void ClearStrict( AstChannel *, int * ); static void ClearValues( AstChannel *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void GetNextData( AstChannel *, int, char **, char **, int * ); static void OutputTextItem( AstChannel *, const char *, int * ); static void PutChannelData( AstChannel *, void *, int * ); static void PutNextText( AstChannel *, const char *, int * ); static void ReadClassData( AstChannel *, const char *, int * ); static void RemoveValue( AstChannelValue *, AstChannelValue **, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetComment( AstChannel *, int, int * ); static void SetFull( AstChannel *, int, int * ); static void SetSkip( AstChannel *, int, int * ); static void SetStrict( AstChannel *, int, int * ); static void SinkWrap( void (*)( const char * ), const char *, int * ); static void Unquote( AstChannel *, char *, int * ); static void WriteBegin( AstChannel *, const char *, const char *, int * ); static void WriteDouble( AstChannel *, const char *, int, int, double, const char *, int * ); static void WriteEnd( AstChannel *, const char *, int * ); static void WriteInt( AstChannel *, const char *, int, int, int, const char *, int * ); static void WriteIsA( AstChannel *, const char *, const char *, int * ); static void WriteObject( AstChannel *, const char *, int, int, AstObject *, const char *, int * ); static void WriteString( AstChannel *, const char *, int, int, const char *, const char *, int * ); static int GetReportLevel( AstChannel *, int * ); static int TestReportLevel( AstChannel *, int * ); static void ClearReportLevel( AstChannel *, int * ); static void SetReportLevel( AstChannel *, int, int * ); static int GetIndent( AstChannel *, int * ); static int TestIndent( AstChannel *, int * ); static void ClearIndent( AstChannel *, int * ); static void SetIndent( AstChannel *, int, int * ); static const char *GetSourceFile( AstChannel *, int * ); static int TestSourceFile( AstChannel *, int * ); static void ClearSourceFile( AstChannel *, int * ); static void SetSourceFile( AstChannel *, const char *, int * ); static const char *GetSinkFile( AstChannel *, int * ); static int TestSinkFile( AstChannel *, int * ); static void ClearSinkFile( AstChannel *, int * ); static void SetSinkFile( AstChannel *, const char *, int * ); /* Member functions. */ /* ================= */ static void AddWarning( AstChannel *this, int level, const char *msg, const char *method, int *status ) { /* *+ * Name: * astAddWarning * Purpose: * Add a warning to a Channel. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astAddWarning( AstChannel *this, int level, const char *msg, * const char *method, int status, ... ) * Class Membership: * Channel method. * Description: * This function stores a warning message inside a Channel. These * messages can be retirieved using astWarnings. * Parameters: * this * Pointer to the Channel. * level * Ignore the warning if the ReportLevel attribute value is less * than "level". * msg * The wanting message to store. It may contain printf format * specifiers. If a NULL pointer is supplied, all warnings * currently stored in the Channel are removed. * method * The method name. * status * Inherited status value. * ... * Extra values to substitute into the message string as * replacements for the printf format specifiers. *- * Note: The expansion of the printf format specifiers is done in the * astAddWarning_ wrapper function. The AddWarning functions defined by * each class receives the fully expanded message and does not have a * variable argument list. The variable argument list is included in the * above prologue in order to document the wrapper function. */ /* Local Variables: */ int i; /* Message index */ char *a; /* Pointer to copy of message */ /* If a NULL pointer was supplied, free all warnings currently in the Channel. Do this before checking the inherited status so that it works even if an error has occurred. */ if( !msg ) { for( i = 0; i < this->nwarn; i++ ) { (this->warnings)[ i ] = astFree( (this->warnings)[ i ] ); } this->warnings = astFree( this->warnings ); this->nwarn = 0; return; } /* Check the global error status. */ if ( !astOK ) return; /* Only proceed if the message level is sufficiently important. */ if( astGetReportLevel( this ) >= level ) { /* If we are being strict, issue an error rather than a warning. */ if( astGetStrict( this ) ) { if( astOK ) { astError( AST__BADIN, "%s(%s): %s", status, method, astGetClass( this ), msg ); } /* Otherwise, we store a copy of the message in the Channel. */ } else { /* Allocate memory and store a copy of th supplied string in it. */ a = astStore( NULL, msg, strlen( msg ) + 1 ); /* Expand the array of warning pointers in ther Channel structure. */ this->warnings = astGrow( this->warnings, this->nwarn + 1, sizeof( char * ) ); /* If all is OK so far, store the new warning pointer, and increment the number of warnings in the Channel. */ if( astOK ) { (this->warnings)[ (this->nwarn)++ ] = a; /* Otherwise, attempt to free the memory holding the copy of the warning. */ } else { a = astFree( a ); } } } } static void AppendValue( AstChannelValue *value, AstChannelValue **head, int *status ) { /* * Name: * AppendValue * Purpose: * Append a Value structure to a list. * Type: * Private function. * Synopsis: * #include "channel.h" * void AppendValue( AstChannelValue *value, AstChannelValue **head, int *status ) * Class Membership: * Channel member function. * Description: * This function appends a Value structure to a doubly linked * circular list of such structures. The new list element is * inserted just in front of the element occupying the "head of * list" position (i.e. it becomes the new last element in the * list). * Parameters: * value * Pointer to the new element. This must not already be in the * list. * head * Address of a pointer to the element at the head of the list * (this pointer should be NULL if the list is initially * empty). This pointer will only be updated if a new element is * being added to an empty list. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error chacking and does not * generate errors. */ /* If the list is initially empty, the sole new element points at itself. */ if ( !*head ) { value->flink = value; value->blink = value; /* Update the list head to identify the new element. */ *head = value; /* Otherwise, insert the new element in front of the element at the head of the list. */ } else { value->flink = *head; value->blink = ( *head )->blink; ( *head )->blink = value; value->blink->flink = value; } } void *astChannelData_( void ) { /* c++ * Name: * astChannelData * Purpose: * Return a pointer to user-supplied data stored with a Channel. * Type: * Public macro. * Synopsis: * #include "channel.h" * void *astChannelData * Class Membership: * Channel macro. * Description: * This macro is intended to be used within the source or sink * functions associated with a Channel. It returns any pointer * previously stored in the Channel (that is, the Channel that has * invoked the source or sink function) using astPutChannelData. * * This mechanism is a thread-safe alternative to passing file * descriptors, etc, via static global variables. * Returned Value: * astChannelData * The pointer previously stored with the Channel using * astPutChannelData. A NULL pointer will be returned if no such * pointer has been stored with the Channel. * Applicability: * Channel * This macro applies to all Channels. * Notes: * - This routine is not available in the Fortran 77 interface to * the AST library. c-- */ astDECLARE_GLOBALS astGET_GLOBALS(NULL); return channel_data; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Channel. * Type: * Private function. * Synopsis: * #include "channel.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Channel member function (over-rides the astClearAttrib protected * method inherited from the Object class). * Description: * This function clears the value of a specified attribute for a * Channel, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Channel. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstChannel *this; /* Pointer to the Channel structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Channel structure. */ this = (AstChannel *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Comment. */ /* -------- */ if ( !strcmp( attrib, "comment" ) ) { astClearComment( this ); /* Full. */ /* ----- */ } else if ( !strcmp( attrib, "full" ) ) { astClearFull( this ); /* Indent. */ /* ------- */ } else if ( !strcmp( attrib, "indent" ) ) { astClearIndent( this ); /* ReportLevel. */ /* ------------ */ } else if ( !strcmp( attrib, "reportlevel" ) ) { astClearReportLevel( this ); /* Skip. */ /* ----- */ } else if ( !strcmp( attrib, "skip" ) ) { astClearSkip( this ); /* SourceFile. */ /* ----------- */ } else if ( !strcmp( attrib, "sourcefile" ) ) { astClearSourceFile( this ); /* SinkFile. */ /* --------- */ } else if ( !strcmp( attrib, "sinkfile" ) ) { astClearSinkFile( this ); /* Strict. */ /* ------- */ } else if ( !strcmp( attrib, "strict" ) ) { astClearStrict( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearValues( AstChannel *this, int *status ) { /* * Name: * ClearValues * Purpose: * Clear the current values list. * Type: * Private function. * Synopsis: * #include "channel.h" * void ClearValues( AstChannel *this, int *status ) * Class Membership: * Channel member function. * Description: * This function clears any (un-read) Value structures remaining in * the current values list (i.e. at the current nesting level). It * should be invoked after all required values have been read. * * If the values list has not been read, or if any remaining values * are found (i.e. the list is not empty) then this indicates an * unrecognised input class or an input value that has not been * read by a class loader. This implies an error in the loader, or * bad input data, so an error is reported. * * All resources used by any remaining Value structures are freed * and the values list is left in an empty state. * Parameters: * this * Pointer to the Channel being read. This is only used for * constructing error messages. It must not be NULL. * status * Pointer to the inherited status variable. * Notes: * - This function attempts to execute even if the global error * status is set on entry, although no further error report will be * made if it subsequently fails under these circumstances. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstChannelValue **head; /* Address of pointer to values list */ AstChannelValue *value; /* Pointer to value list element */ /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* If "values_class" is non-NULL, then the values list has previously been filled with Values for a class. */ if ( values_class[ nest ] ) { /* If "values_ok" is zero, however, then these Values have not yet been read by a class loader. This must be due to a bad class name associated with them or because the class data are not available in the correct order. If we are using strict error reporting, then report an error (unless the error status is already set). */ if ( astGetStrict( this ) && !values_ok[ nest ] && astOK ) { astError( AST__BADIN, "astRead(%s): Invalid class structure in input data.", status, astGetClass( this ) ); astError( AST__BADIN, "Class \"%s\" is invalid or out of order within a %s.", status, values_class[ nest ], object_class[ nest ] ); } /* Free the memory holding the class string. */ values_class[ nest ] = astFree( values_class[ nest ] ); } /* Reset the "values_ok" flag. */ values_ok[ nest ] = 0; /* Now clear any Values remaining in the values list. Obtain the address of the pointer to the head of this list (at the current nesting level) and loop to remove Values from the list while it is not empty. */ head = values_list + nest; while ( *head ) { /* Obtain a pointer to the first element. */ value = *head; /* Issue a warning. */ if ( value->is_object ) { astAddWarning( this, 1, "The Object \"%s = <%s>\" was " "not recognised as valid input.", "astRead", status, value->name, astGetClass( value->ptr.object ) ); } else { astAddWarning( this, 1, "The value \"%s = %s\" was not " "recognised as valid input.", "astRead", status, value->name, value->ptr.string ); } /* Remove the Value structure from the list (which updates the head of list pointer) and free its resources. */ RemoveValue( value, head, status ); value = FreeValue( value, status ); } } static AstChannelValue *FreeValue( AstChannelValue *value, int *status ) { /* * Name: * FreeValue * Purpose: * Free a dynamically allocated Value structure. * Type: * Private function. * Synopsis: * #include "channel.h" * AstChannelValue *FreeValue( AstChannelValue *value, int *status ) * Class Membership: * Channel member function. * Description: * This function frees a dynamically allocated Value structure, * releasing all resources used by it. The structure contents must * have been correctly initialised. * Parameters: * value * Pointer to the Value structure to be freed. * status * Pointer to the inherited status variable. * Returned Value: * A NULL pointer is always returned. * Notes: * - This function attempts to execute even if the global error * status is set on entry, although no further error report will be * made if it subsequently fails under these circumstances. */ /* Check that a non-NULL pointer has been supplied. */ if ( value ) { /* If the "name" component has been allocated, then free it. */ if ( value->name ) value->name = astFree( value->name ); /* If the "ptr" component identifies an Object, then annul the Object pointer. */ if ( value->is_object ) { if ( value->ptr.object ) { value->ptr.object = astAnnul( value->ptr.object ); } /* Otherwise, if it identifies a string, then free the string. */ } else { if ( value->ptr.string ) { value->ptr.string = astFree( value->ptr.string ); } } /* Free the Value structure itself. */ value = astFree( value ); } /* Return a NULL pointer. */ return NULL; } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Channel. * Type: * Private function. * Synopsis: * #include "channel.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Channel member function (over-rides the protected astGetAttrib * method inherited from the Object class). * Description: * This function returns a pointer to the value of a specified * attribute for a Channel, formatted as a character string. * Parameters: * this * Pointer to the Channel. * 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 Channel, 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 Channel. 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 */ AstChannel *this; /* Pointer to the Channel structure */ const char *result; /* Pointer value to return */ int comment; /* Comment attribute value */ int full; /* Full attribute value */ int indent; /* Indent attribute value */ int report_level; /* ReportLevel attribute value */ int skip; /* Skip attribute value */ int strict; /* Report errors insead of warnings? */ /* 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 Channel structure. */ this = (AstChannel *) 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. */ /* Comment. */ /* -------- */ if ( !strcmp( attrib, "comment" ) ) { comment = astGetComment( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", comment ); result = getattrib_buff; } /* Full. */ /* ----- */ } else if ( !strcmp( attrib, "full" ) ) { full = astGetFull( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", full ); result = getattrib_buff; } /* Indent. */ /* ------- */ } else if ( !strcmp( attrib, "indent" ) ) { indent = astGetIndent( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", indent ); result = getattrib_buff; } /* ReportLevel. */ /* ------------ */ } else if ( !strcmp( attrib, "reportlevel" ) ) { report_level = astGetReportLevel( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", report_level ); result = getattrib_buff; } /* Skip. */ /* ----- */ } else if ( !strcmp( attrib, "skip" ) ) { skip = astGetSkip( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", skip ); result = getattrib_buff; } /* SourceFile. */ /* ----------- */ } else if ( !strcmp( attrib, "sourcefile" ) ) { result = astGetSourceFile( this ); /* SinkFile. */ /* --------- */ } else if ( !strcmp( attrib, "sinkfile" ) ) { result = astGetSinkFile( this ); /* Strict. */ /* ------- */ } else if ( !strcmp( attrib, "strict" ) ) { strict = astGetStrict( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", strict ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static void GetNextData( AstChannel *this, int skip, char **name, char **val, int *status ) { /* *+ * Name: * astGetNextData * Purpose: * Read the next item of data from a data source. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astGetNextData( AstChannel *this, int skip, char **name, * char **val ) * Class Membership: * Channel method. * Description: * This function reads the next item of input data from a data * source associated with a Channel and returns the result. * * It is layered conceptually on the astGetNextText method, but * instead of returning the raw input text, it decodes it and * returns name/value pairs ready for use. Note that in some * derived classes, where the data are not stored as text, this * function may not actually use astGetNextText, but will access * the data directly. * Parameters: * this * Pointer to the Channel. * skip * A non-zero value indicates that a new Object is to be read, * and that all input data up to the next "Begin" item are to be * skipped in order to locate it. This is useful if the data * source contains AST objects interspersed with other data (but * note that these other data cannot appear inside AST Objects, * only between them). * * A zero value indicates that all input data are significant * and the next item will therefore be read and an attempt made * to interpret it whatever it contains. Any other data * inter-mixed with AST Objects will then result in an error. * name * An address at which to store a pointer to a null-terminated * dynamically allocated string containing the name of the next * item in the input data stream. This name will be in lower * case with no surrounding white space. It is the callers * responsibilty to free the memory holding this string (using * astFree) when it is no longer required. * * A NULL pointer value will be returned (without error) to * indicate when there are no further input data items to be * read. * val * An address at which to store a pointer to a null-terminated * dynamically allocated string containing the value associated * with the next item in the input data stream. No case * conversion is performed on this string and all white space is * potentially significant. It is the callers responsibilty to * free the memory holding this string (using astFree) when it * is no longer required. * * The returned pointer will be NULL if an Object data item is * read (see the "Data Representation" section). * Data Representation: * The returned data items fall into the following categories: * * - Begin: Identified by the name string "begin", this indicates * the start of an Object definition. The associated value string * gives the class name of the Object being defined. * * - IsA: Identified by the name string "isa", this indicates the * end of the data associated with a particular class structure * within the definiton of a larger Object. The associated value * string gives the name of the class whose data have just been * read. * * - End: Identified by the name string "end", this indicates the * end of the data associated with a complete Object * definition. The associated value string gives the class name of * the Object whose definition is being ended. * * - Non-Object: Identified by any other name string plus a * non-NULL "val" pointer, this gives the value of a non-Object * structure component (instance variable). The name identifies * which instance variable it is (within the context of the class * whose data are being read) and the value is encoded as a string. * * - Object: Identified by any other name string plus a NULL "val" * pointer, this identifies the value of an Object structure * component (instance variable). The name identifies which * instance variable it is (within the context of the class whose * data are being read) and the value is given by subsequent data * items (so the next item should be a "Begin" item). * Notes: * - NULL pointer values will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. * - This method is provided primarily so that derived classes may * over-ride it in order to read from alternative data sources. It * provides a higher-level interface than astGetNextText, so is * suitable for classes that either need to read textual data in a * different format, or to read from non-textual data sources. *- */ /* Local Variables: */ char *line; /* Pointer to input text line */ int done; /* Data item read? */ int i; /* Loop counter for string characters */ int len; /* Length of input text line */ int nc1; /* Offset to start of first field */ int nc2; /* Offset to end of first field */ int nc3; /* Offset to start of second field */ int nc; /* Number of charaters read by "astSscanf" */ /* Initialise the returned values. */ *name = NULL; *val = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Read the next input line as text (the loop is needed to allow initial lines to be skipped if the "skip" flag is set). */ done = 0; while ( !done && ( line = InputTextItem( this, status ) ) && astOK ) { /* If OK, determine the line length. */ len = strlen( line ); /* Non-Object value. */ /* ----------------- */ /* Test for lines of the form " name = value" (or similar), where the name is no more than MAX_NAME characters long (the presence of a value on the right hand side indicates that this is a non-Object value, encoded as a string). Ignore these lines if the "skip" flag is set. */ if ( nc = 0, ( !skip && ( 0 == astSscanf( line, " %n%*" MAX_NAME "[^ \t=]%n = %n%*[^\n]%n", &nc1, &nc2, &nc3, &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Extract the name and value fields. */ *name = astString( line + nc1, nc2 - nc1 ); *val = astString( line + nc3, len - nc3 ); /* If OK, truncate the value to remove any trailing white space. */ if ( astOK ) { i = len - nc3 - 1; while ( ( i >= 0 ) && isspace( ( *val )[ i ] ) ) i--; ( *val )[ i + 1 ] = '\0'; /* Also remove any quotes from the string. */ Unquote( this, *val, status ); } /* Object value. */ /* ------------- */ /* Test for lines of the form " name = " (or similar), where the name is no more than MAX_NAME characters long (the absence of a value on the right hand side indicates that this is an Object, whose definition follows on subsequent input lines). Ignore these lines if the "skip" flag is set. */ } else if ( nc = 0, ( !skip && ( 0 == astSscanf( line, " %n%*" MAX_NAME "[^ \t=]%n = %n", &nc1, &nc2, &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Extract the name field but leave the value pointer as NULL. */ *name = astString( line + nc1, nc2 - nc1 ); /* Begin. */ /* ------ */ /* Test for lines of the form " Begin Class " (or similar). */ } else if ( nc = 0, ( ( 0 == astSscanf( line, " %*1[Bb]%*1[Ee]%*1[Gg]%*1[Ii]%*1[Nn] %n%*s%n %n", &nc1, &nc2, &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name to "begin" and extract the associated class name for the value. Store both of these in dynamically allocated strings. */ *name = astString( "begin", 5 ); *val = astString( line + nc1, nc2 - nc1 ); /* IsA. */ /* ---- */ /* Test for lines of the form " IsA Class " (or similar). Ignore these lies if the "skip" flag is set. */ } else if ( nc = 0, ( !skip && ( 0 == astSscanf( line, " %*1[Ii]%*1[Ss]%*1[Aa] %n%*s%n %n", &nc1, &nc2, &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* Set the returned name to "isa" and extract the associated class name for the value. */ *name = astString( "isa", 3 ); *val = astString( line + nc1, nc2 - nc1 ); /* End. */ /* ---- */ /* Test for lines of the form " End Class " (or similar). Ignore these lines if the "skip" flag is set. */ } else if ( nc = 0, ( !skip && ( 0 == astSscanf( line, " %*1[Ee]%*1[Nn]%*1[Dd] %n%*s%n %n", &nc1, &nc2, &nc ) ) && ( nc >= len ) ) ) { /* Note we have found a data item. */ done = 1; /* If found, set the returned name to "end" and extract the associated class name for the value. */ *name = astString( "end", 3 ); *val = astString( line + nc1, nc2 - nc1 ); /* If the input line didn't match any of the above and the "skip" flag is not set, then report an error. */ } else if ( !skip ) { astError( AST__BADIN, "astRead(%s): Cannot interpret the input data: \"%s\".", status, astGetClass( this ), line ); } /* Free the memory holding the input data as text. */ line = astFree( line ); } /* If successful, convert the name to lower case. */ if ( astOK && *name ) { for ( i = 0; ( *name )[ i ]; i++ ) { ( *name )[ i ] = tolower( ( *name )[ i ] ); } } /* If an error occurred, ensure that any memory allocated is freed and that NULL pointer values are returned. */ if ( !astOK ) { *name = astFree( *name ); *val = astFree( *val ); } } static char *GetNextText( AstChannel *this, int *status ) { /* *+ * Name: * GetNextText * Purpose: * Read the next line of input text from a data source. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * char *astGetNextText( AstChannel *this ) * Class Membership: * Channel method. * Description: * This function reads the next "raw" input line of text from the * data source associated with a Channel. * * Each line is returned as a pointer to a null-terminated string * held in dynamic memory, and it is the caller's responsibility to * free this memory (using astFree) when it is no longer * required. A NULL pointer is returned if there are no more input * lines to be read. * Parameters: * this * Pointer to the Channel. * Returned Value: * Pointer to a null-terminated string containing the input line * (held in dynamically allocated memory, which must be freed by * the caller when no longer required). A NULL pointer is returned * if there are no more input lines to be read. * 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. * - This method is provided primarily so that derived classes may * over-ride it in order to read from alternative (textual) data * sources. *- */ /* Local Constants: */ #define MIN_CHARS 81 /* Initial size for allocating memory */ #define ERRBUF_LEN 80 /* Local Variables: */ FILE *fd; /* Input file descriptor */ char *errstat; /* Pointer for system error message */ char *line; /* Pointer to line data to be returned */ char errbuf[ ERRBUF_LEN ]; /* Buffer for system error message */ const char *sink_file; /* Path to output sink file */ const char *source_file; /* Path to source file */ int c; /* Input character */ int len; /* Length of input line */ int readstat; /* "errno" value set by "getchar" */ int size; /* Size of allocated memory */ /* Initialise. */ line = NULL; /* Check the global error status. */ if ( !astOK ) return line; /* If the SourceFile attribute of the Channel specifies an input file, but no input file has yet been opened, open it now. Report an error if it is the same as the sink file. */ if( astTestSourceFile( this ) && !this->fd_in ) { source_file = astGetSourceFile( this ); if( this->fd_out ) { sink_file = astGetSinkFile( this ); if( astOK && !strcmp( sink_file, source_file ) ) { astError( AST__RDERR, "astRead(%s): Failed to open input " "SourceFile '%s' - the file is currently being used " "as the output SinkFile.", status, astGetClass( this ), source_file ); } } if( astOK ) { this->fd_in = fopen( source_file, "r" ); if( !this->fd_in ) { if ( errno ) { #if HAVE_STRERROR_R strerror_r( errno, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( errno ); #endif astError( AST__RDERR, "astRead(%s): Failed to open input " "SourceFile '%s' - %s.", status, astGetClass( this ), source_file, errstat ); } else { astError( AST__RDERR, "astRead(%s): Failed to open input " "SourceFile '%s'.", status, astGetClass( this ), source_file ); } } } } /* Source function defined, but no input file. */ /* ------------------------------------------- */ /* If no active input file descriptor is stored in the Channel, but a source function (and its wrapper function) is defined for the Channel, use the wrapper function to invoke the source function to read a line of input text. This is returned in a dynamically allocated string. */ if ( !this->fd_in && this->source && this->source_wrap ) { /* About to call an externally supplied function which may not be thread-safe, so lock a mutex first. Also store the channel data pointer in a global variable so that it can be accessed in the source function using macro astChannelData. */ astStoreChannelData( this ); LOCK_MUTEX3; line = ( *this->source_wrap )( this->source, status ); UNLOCK_MUTEX3; /* Input file defined, or no source function. */ /* ------------------------------------------ */ /* Read the line from the input file or from standard input. */ } else if( astOK ) { c = '\0'; len = 0; size = 0; /* Choose the file descriptor to use. */ fd = this->fd_in ? this->fd_in : stdin; /* Loop to read input characters, saving any "errno" value that may be set by "getchar" if an error occurs. Quit if an end of file (or error) occurs or if a newline character is read. */ while ( errno = 0, c = getc( fd ), readstat = errno, ( c != EOF ) && ( c != '\n' ) ) { /* If no memory has yet been allocated to hold the line, allocate some now, using MIN_CHARS as the initial line length. */ if ( !line ) { line = astMalloc( sizeof( char ) * (size_t) MIN_CHARS ); size = MIN_CHARS; /* If memory has previously been allocated, extend it when necessary to hold the new input character (plus a terminating null) and note the new size. */ } else if ( ( len + 2 ) > size ) { line = astGrow( line, len + 2, sizeof( char ) ); if ( !astOK ) break; size = (int) astSizeOf( line ); } /* Store the character just read. */ line[ len++ ] = c; } /* If the above loop completed without setting the global error status, check the last character read and use "ferror" to see if a read error occurred. If so, report the error, using the saved "errno" value (but only if one was set). */ if ( astOK && ( c == EOF ) && ferror( fd ) ) { if ( readstat ) { #if HAVE_STRERROR_R strerror_r( readstat, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( readstat ); #endif astError( AST__RDERR, "astRead(%s): Read error on standard input - %s.", status, astGetClass( this ), errstat ); } else { astError( AST__RDERR, "astRead(%s): Read error on standard input.", status, astGetClass( this ) ); } } /* If an empty line has been read, allocate memory to hold an empty string. */ if ( !line && ( c == '\n' ) ) { line = astMalloc( sizeof( char ) ); } /* If memory has been allocated and there has been no error, null-terminate the string of input characters. */ if ( line ) { if ( astOK ) { line[ len ] = '\0'; /* If there has been an error, free the allocated memory. */ } else { line = astFree( line ); } } } /* Return the result pointer. */ return line; /* Undefine macros local to this function. */ #undef MIN_CHARS #undef ERRBUF_LEN } static AstKeyMap *Warnings( AstChannel *this, int *status ){ /* *++ * Name: c astWarnings f AST_WARNINGS * Purpose: * Returns any warnings issued by the previous read or write operation. * Type: * Public virtual function. * Synopsis: c #include "channel.h" c AstKeyMap *astWarnings( AstChannel *this ) f RESULT = AST_WARNINGS( THIS, STATUS ) * Class Membership: * Channel member function. * Description: * This function returns an AST KeyMap object holding the text of any * warnings issued as a result of the previous invocation of the c astRead or astWrite f AST_READ or AST_WRITE * function on the Channel. If no warnings were issued, a c a NULL value f AST__NULL * will be returned. * * Such warnings are non-fatal and will not prevent the * read or write operation succeeding. However, the converted object * may not be identical to the original object in all respects. * Differences which would usually be deemed as insignificant in most * usual cases will generate a warning, whereas more significant * differences will generate an error. * * The "Strict" attribute allows this warning facility to be switched * off, so that a fatal error is always reported for any conversion * error. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Channel. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astWarnings() f AST_WARNINGS = INTEGER * A pointer to the KeyMap holding the warning messages, or c NULL f AST__NULL * if no warnings were issued during the previous read operation. * Applicability: * Channel * The basic Channel class generates a warning when ever an * un-recognised item is encountered whilst reading an Object from * an external data source. If Strict is zero (the default), then * unexpected items in the Object description are simply ignored, * and any remaining items are used to construct the returned * Object. If Strict is non-zero, an error will be reported and a * NULL Object pointer returned if any unexpected items are * encountered. * * As AST continues to be developed, new attributes are added * occasionally to selected classes. If an older version of AST is * used to read external Object descriptions created by a more * recent version of AST, then the Channel class will, by default, * ignore the new attributes, using the remaining attributes to * construct the Object. This is usually a good thing. However, * since external Object descriptions are often stored in plain * text, it is possible to edit them using a text editor. This * gives rise to the possibility of genuine errors in the * description due to finger-slips, typos, or simple * mis-understanding. Such inappropriate attributes will be ignored * if Strict is left at its default zero value. This will cause the * mis-spelled attribute to revert to its default value, * potentially causing subtle changes in the behaviour of * application software. If such an effect is suspected, the Strict * attribute can be set non-zero, resulting in the erroneous * attribute being identified in an error message. * FitsChan * The returned KeyMap will contain warnings for all conditions * listed in the Warnings attribute. * XmlChan * Reports conversion errors that result in what are usally * insignificant changes. * Notes: * - The returned KeyMap uses keys of the form "Warning_1", * "Warning_2", etc. * - A value of c NULL will be returned if this function is invoked with the AST c error status set, f AST__NULL will be returned if this function is invoked with STATUS f set to an error value, * or if it should fail for any reason. *-- */ /* Local Variables: */ AstKeyMap *result; char key[ 20 ]; int i; /* Check the global status, and supplied keyword name. */ result = NULL; if( !astOK ) return result; /* Check there are some warnings to return. */ if( this->nwarn && this->warnings ) { /* Create the KeyMap. */ result = astKeyMap( "", status ); /* Loop round all warnings, adding them into the KeyMap. */ for( i = 0; i < this->nwarn; i++ ){ sprintf( key, "Warning_%d", i + 1 ); astMapPut0C( result, key, (this->warnings)[ i ], " " ); } } /* Return the KeyMap. */ return result; } AstChannel *astInitChannel_( void *mem, size_t size, int init, AstChannelVtab *vtab, const char *name, const char *(* source)( void ), char *(* source_wrap)( const char *(*)( void ), int * ), void (* sink)( const char * ), void (* sink_wrap)( void (*)( const char * ), const char *, int * ), int *status ) { /* *+ * Name: * astInitChannel * Purpose: * Initialise a Channel. * Type: * Protected function. * Synopsis: * #include "channel.h" * AstChannel *astInitChannel( void *mem, size_t size, int init, * AstChannelVtab *vtab, const char *name, * const char *(* source)( void ), * char *(* source_wrap)( const char *(*)( void ), int * ), * void (* sink)( const char * ), * void (* sink_wrap)( void (*)( const char * ), * const char *, int * ) ) * Class Membership: * Channel initialiser. * Description: * This function is provided for use by class implementations to * initialise a new Channel object. It allocates memory (if * necessary) to accommodate the Channel plus any additional data * associated with the derived class. It then initialises a * Channel 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 Channel at the start of the memory passed * via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Channel is to be * initialised. This must be of sufficient size to accommodate * the Channel data (sizeof(Channel)) 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 Channel (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 Channel structure, so a valid value must be * supplied even if not required for allocating memory. * init * A boolean flag indicating if the Channel'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 Channel. * 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). * source * Pointer to a "source" function which will be used to obtain * lines of input text. Generally, this will be obtained by * casting a pointer to a source function which is compatible * with the "source_wrap" wrapper function (below). The pointer * should later be cast back to its original type by the * "source_wrap" function before the function is invoked. * * If "source" is NULL, the Channel will read from standard * input instead. * source_wrap * Pointer to a function which can be used to invoke the * "source" function supplied (above). This wrapper function is * necessary in order to hide variations in the nature of the * source function, such as may arise when it is supplied by a * foreign (non-C) language interface. * * The single parameter of the "source_wrap" function is a * pointer to the "source" function, and it should cast this * function pointer (as necessary) and invoke the function with * appropriate arguments to obtain the next line of input * text. The "source_wrap" function should then return a pointer * to a dynamically allocated, null terminated string containing * the text that was read. The string will be freed (using * astFree) when no longer required and the "source_wrap" * function need not concern itself with this. A NULL pointer * should be returned if there is no more input to read. * * If "source_wrap" is NULL, the Channel will read from standard * input instead. * sink * Pointer to a "sink" function which will be used to deliver * lines of output text. Generally, this will be obtained by * casting a pointer to a sink function which is compatible with * the "sink_wrap" wrapper function (below). The pointer should * later be cast back to its original type by the "sink_wrap" * function before the function is invoked. * * If "sink" is NULL, the Channel will write to standard output * instead. * sink_wrap * Pointer to a function which can be used to invoke the "sink" * function supplied (above). This wrapper function is necessary * in order to hide variations in the nature of the sink * function, such as may arise when it is supplied by a foreign * (non-C) language interface. * * The first parameter of the "sink_wrap" function is a pointer * to the "sink" function, and the second parameter is a pointer * to a const, null-terminated character string containing the * text to be written. The "sink_wrap" function should cast the * "sink" function pointer (as necessary) and invoke the * function with appropriate arguments to deliver the line of * output text. The "sink_wrap" function then returns void. * * If "sink_wrap" is NULL, the Channel will write to standard * output instead. * Returned Value: * A pointer to the new Channel. * 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: */ AstChannel *new; /* Pointer to new Channel */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitChannelVtab( vtab, name ); /* Initialise an Object structure (the parent class) as the first component within the Channel structure, allocating memory if necessary. */ new = (AstChannel *) astInitObject( mem, size, 0, (AstObjectVtab *) vtab, name ); if ( astOK ) { /* Initialise the Channel data. */ /* ---------------------------- */ /* Save the pointers to the source and sink functions and the wrapper functions that invoke them. */ new->source = source; new->source_wrap = source_wrap; new->sink = sink; new->sink_wrap = sink_wrap; /* Indicate no input or output files have been associated with the Channel. */ new->fd_in = NULL; new->fn_in = NULL; new->fd_out = NULL; new->fn_out = NULL; /* Set all attributes to their undefined values. */ new->comment = -INT_MAX; new->full = -INT_MAX; new->indent = -INT_MAX; new->report_level = -INT_MAX; new->skip = -INT_MAX; new->strict = -INT_MAX; new->data = NULL; new->warnings = NULL; new->nwarn = 0; /* 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; } void astInitChannelVtab_( AstChannelVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitChannelVtab * Purpose: * Initialise a virtual function table for a Channel. * Type: * Protected function. * Synopsis: * #include "channel.h" * void astInitChannelVtab( AstChannelVtab *vtab, const char *name ) * Class Membership: * Channel vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Channel class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ /* 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. */ astInitObjectVtab( (AstObjectVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAChannel) 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 = &(((AstObjectVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->AddWarning = AddWarning; vtab->ClearComment = ClearComment; vtab->ClearFull = ClearFull; vtab->ClearSkip = ClearSkip; vtab->ClearStrict = ClearStrict; vtab->GetComment = GetComment; vtab->GetFull = GetFull; vtab->GetNextData = GetNextData; vtab->GetNextText = GetNextText; vtab->GetSkip = GetSkip; vtab->GetStrict = GetStrict; vtab->Warnings = Warnings; vtab->PutNextText = PutNextText; vtab->Read = Read; vtab->ReadClassData = ReadClassData; vtab->ReadDouble = ReadDouble; vtab->ReadInt = ReadInt; vtab->ReadObject = ReadObject; vtab->ReadString = ReadString; vtab->SetComment = SetComment; vtab->SetFull = SetFull; vtab->SetSkip = SetSkip; vtab->SetStrict = SetStrict; vtab->TestComment = TestComment; vtab->TestFull = TestFull; vtab->TestSkip = TestSkip; vtab->TestStrict = TestStrict; vtab->Write = Write; vtab->WriteBegin = WriteBegin; vtab->WriteDouble = WriteDouble; vtab->WriteEnd = WriteEnd; vtab->WriteInt = WriteInt; vtab->WriteIsA = WriteIsA; vtab->WriteObject = WriteObject; vtab->WriteString = WriteString; vtab->PutChannelData = PutChannelData; vtab->ClearReportLevel = ClearReportLevel; vtab->GetReportLevel = GetReportLevel; vtab->SetReportLevel = SetReportLevel; vtab->TestReportLevel = TestReportLevel; vtab->ClearIndent = ClearIndent; vtab->GetIndent = GetIndent; vtab->SetIndent = SetIndent; vtab->TestIndent = TestIndent; vtab->ClearSourceFile = ClearSourceFile; vtab->GetSourceFile = GetSourceFile; vtab->SetSourceFile = SetSourceFile; vtab->TestSourceFile = TestSourceFile; vtab->ClearSinkFile = ClearSinkFile; vtab->GetSinkFile = GetSinkFile; vtab->SetSinkFile = SetSinkFile; vtab->TestSinkFile = TestSinkFile; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; /* Declare the destructor and copy constructor. */ astSetDelete( (AstObjectVtab *) vtab, Delete ); astSetCopy( (AstObjectVtab *) vtab, Copy ); /* Declare the Dump function for this class. There is no destructor or copy constructor. */ astSetDump( vtab, Dump, "Channel", "Basic I/O Channel" ); /* 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 char *InputTextItem( AstChannel *this, int *status ) { /* * Name: * InputTextItem * Purpose: * Read the next item from a data source as text. * Type: * Private function. * Synopsis: * #include "channel.h" * char *InputTextItem( AstChannel *this ) * Class Membership: * Channel member function. * Description: * This function reads the next input data item as text from the * data source associated with a Channel. It is similar to the * astGetNextText method (which it invokes), except that it strips * off any comments along with leading and trailing white * space. Input lines which are empty or do not contain significant * characters (e.g. all comment) are skipped, so that only * significant lines are returned. * * Each line is returned as a pointer to a null-terminated string * held in dynamic memory, and it is the caller's responsibility to * free this memory (using astFree) when it is no longer * required. A NULL pointer is returned if there are no more input * lines to be read. * Parameters: * this * Pointer to the Channel. * Returned Value: * Pointer to a null-terminated string containing the input line * (held in dynamically allocated memory, which must be freed by * the caller when no longer required). A NULL pointer is returned * if there are no more input lines to be read. * 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: */ char *line; /* Pointer to line data to be returned */ int i; /* Loop counter for line characters */ int j; /* Counter for characters */ int len; /* Length of result line */ int nonspace; /* Non-space character encountered? */ int quoted; /* Character is inside quotes? */ /* Initialise. */ line = NULL; /* Check the global error status. */ if ( !astOK ) return line; /* Loop to read input lines until one is found which contains useful characters or end of file is reached (or a read error occurs). */ while ( !line && ( line = astGetNextText( this ) ) && astOK ) { /* Loop to remove comments and leading and trailing white space. */ len = 0; nonspace = 0; quoted = 0; for ( i = j = 0; line[ i ]; i++ ) { /* Note quote characters and ignore all text after the first unquoted comment character. */ if ( line[ i ] == '"' ) quoted = !quoted; if ( ( line[ i ] == '#' ) && !quoted ) break; /* Note the first non-space character and ignore everything before it. */ if ( ( nonspace = nonspace || !isspace( line[ i ] ) ) ) { /* Move each character to its new position in the string. */ line[ j++ ] = line[ i ]; /* Note the final length of the string (ignoring trailing spaces). */ if ( !isspace( line[ i ] ) ) len = j; } } /* If the string is not empty, terminate it. */ if ( len ) { line[ len ] = '\0'; /* Otherwise, free the memory used for the string so that another input line will be read. */ } else { line = astFree( line ); } } /* Return the result pointer. */ return line; /* Undefine macros local to this function. */ #undef MIN_CHARS } static AstChannelValue *LookupValue( const char *name, int *status ) { /* * Name: * LookupValue * Purpose: * Look up a Value structure by name. * Type: * Private function. * Synopsis: * #include "channel.h" * AstChannelValue *LookupValue( const char *name ) * Class Membership: * Channel member function. * Description: * This function searches the current values list (i.e. at the * current nesting level) to identify a Value structure with a * specified name. If one is found, it is removed from the list and * a pointer to it is returned. If no suitable Value can be found, * a NULL pointer is returned instead. * Parameters: * name * Pointer to a constant null-terminated character string * containing the name of the required Value. This must be in * lower case with no surrounding white space. Note that names * longer than NAME_MAX characters will not match any Value. * Returned value: * Pointer to the required Value structure, or NULL if no suitable * Value exists. * Notes: * - The returned pointer refers to a dynamically allocated * structure and it is the callers responsibility to free this when * no longer required. The FreeValue function must be used for this * purpose. * - 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 */ AstChannelValue **head; /* Address of head of list pointer */ AstChannelValue *result; /* Pointer value to return */ AstChannelValue *value; /* Pointer to list element */ /* 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(NULL); /* Check that the "values_ok" flag is set. If not, the Values in the values list belong to a different class to that of the current class loader, so we cannot return any Value. */ if ( values_ok[ nest ] ) { /* Obtain the address of the current "head of list" pointer for the values list (at the current nesting level). */ head = values_list + nest; /* Obtain the head of list pointer itself and check the list is not empty. */ if ( ( value = *head ) ) { /* Loop to inspect each list element. */ while ( 1 ) { /* If a name match is found, remove the element from the list, return a pointer to it and quit searching. */ if ( !strcmp( name, value->name ) ) { RemoveValue( value, head, status ); result = value; break; } /* Follow the list until we return to the head. */ value = value->flink; if ( value == *head ) break; } } } /* Return the result. */ return result; } static void OutputTextItem( AstChannel *this, const char *line, int *status ) { /* * Name: * OutputTextItem * Purpose: * Output a data item formatted as text. * Type: * Private function. * Synopsis: * #include "channel.h" * void OutputTextItem( AstChannel *this, const char *line, int *status ) * Class Membership: * Channel member function. * Description: * This function outputs a data item formatted as a text string to * a data sink associated with a Channel. It keeps track of the * number of items written. * Parameters: * this * Pointer to the Channel. * line * Pointer to a constant null-terminated string containing the * data item to be output (no newline character should be * appended). * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Write out the line of text using the astPutNextText method (which may be over-ridden). */ astPutNextText( this, line ); /* If successful, increment the count of items written. */ if ( astOK ) items_written++; } static void PutChannelData( AstChannel *this, void *data, int *status ) { /* c++ * Name: * astPutChannelData * Purpose: * Store arbitrary data to be passed to a source or sink function. * Type: * Public function. * Synopsis: * #include "channel.h" * void astPutChannelData( AstChannel *this, void *data ) * Class Membership: * Channel method. * Description: * This function stores a supplied arbitrary pointer in the Channel. * When a source or sink function is invoked by the Channel, the * invoked function can use the astChannelData macro to retrieve the * pointer. This provides a thread-safe alternative to passing file * descriptors, etc, via global static variables. * Parameters: * this * Pointer to the Channel. * data * A pointer to be made available to the source and sink functions * via the astChannelData macro. May be NULL. * Applicability: * Channel * All Channels have this function. * Notes: * - This routine is not available in the Fortran 77 interface to * the AST library. c-- */ /* Check the global error status. */ if ( !astOK ) return; /* Store the pointer. */ this->data = data; } static void PutNextText( AstChannel *this, const char *line, int *status ) { /* *+ * Name: * astPutNextText * Purpose: * Write a line of output text to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astPutNextText( AstChannel *this, const char *line ) * Class Membership: * Channel method. * Description: * This function writes an output line of text to a data sink * associated with a Channel. * Parameters: * this * Pointer to the Channel. * line * Pointer to a constant null-terminated string containing the * line of output text to be written (no newline character * should be appended). * Notes: * - This method is provided primarily so that derived classes may * over-ride it in order to write to alternative (textual) data * sinks. *- */ /* Local Constants: */ #define ERRBUF_LEN 80 /* Local Variables: */ char *errstat; /* Pointer for system error message */ char errbuf[ ERRBUF_LEN ]; /* Buffer for system error message */ const char *sink_file; /* Path to output sink file */ const char *source_file; /* Path to output source file */ /* Check the global error status. */ if ( !astOK ) return; /* If the SinkFile attribute of the Channel specifies an output file, but no output file has yet been opened, open it now. Report an error if it is the same as the source file. */ if( astTestSinkFile( this ) && !this->fd_out ) { sink_file = astGetSinkFile( this ); if( this->fd_out ) { source_file = astGetSourceFile( this ); if( astOK && !strcmp( sink_file, source_file ) ) { astError( AST__WRERR, "astWrite(%s): Failed to open output " "SinkFile '%s' - the file is currently being used " "as the input SourceFile.", status, astGetClass( this ), sink_file ); } } if( astOK ) { this->fd_out = fopen( sink_file, "w" ); if( !this->fd_out ) { if ( errno ) { #if HAVE_STRERROR_R strerror_r( errno, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( errno ); #endif astError( AST__WRERR, "astWrite(%s): Failed to open output " "SinkFile '%s' - %s.", status, astGetClass( this ), sink_file, errstat ); } else { astError( AST__WRERR, "astWrite(%s): Failed to open output " "SinkFile '%s'.", status, astGetClass( this ), sink_file ); } } } } /* Check no error occurred above. */ if( astOK ) { /* If an active output file descriptor is stored in the channel, write the text to it, with a newline appended. */ if( this->fd_out ) { (void) fprintf( this->fd_out, "%s\n", line ); /* Otherwise, if a sink function (and its wrapper function) is defined for the Channel, use the wrapper function to invoke the sink function to output the text line. Since we are about to call an externally supplied function which may not be thread-safe, lock a mutex first. Also store the channel data pointer in a global variable so that it can be accessed in the source function using macro astChannelData. */ } else if ( this->sink && this->sink_wrap ) { astStoreChannelData( this ); LOCK_MUTEX2; ( *this->sink_wrap )( *this->sink, line, status ); UNLOCK_MUTEX2; /* Otherwise, simply write the text to standard output with a newline appended. */ } else { (void) printf( "%s\n", line ); } } } static AstObject *Read( AstChannel *this, int *status ) { /* *++ * Name: c astRead f AST_READ * Purpose: * Read an Object from a Channel. * Type: * Public function. * Synopsis: c #include "channel.h" c AstObject *astRead( AstChannel *this ) f RESULT = AST_READ( THIS, STATUS ) * Class Membership: * Channel method. * Description: * This function reads the next Object from a Channel and returns a * pointer to the new Object. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Channel. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astRead() f AST_READ = INTEGER * A pointer to the new Object. The class to which this will * belong is determined by the input data, so is not known in * advance. * Applicability: * FitsChan c All successful use of astRead on a FitsChan is destructive, so that f All successful use of AST_READ on a FitsChan is destructive, so that * FITS header cards are consumed in the process of reading an Object, * and are removed from the FitsChan (this deletion can be prevented * for specific cards by calling the FitsChan c astRetainFits function). f AST_RETAINFITS routine). * An unsuccessful call of c astRead f AST_READ * (for instance, caused by the FitsChan not containing the necessary * FITS headers cards needed to create an Object) results in the * contents of the FitsChan being left unchanged. * StcsChan * The AST Object returned by a successful use of c astRead f AST_READ * on an StcsChan, will be either a Region or a KeyMap, depending * on the values of the StcsArea, StcsCoords and StcsProps * attributes. See the documentation for these attributes for further * information. * Notes: * - A null Object pointer (AST__NULL) will be returned, without * error, if the Channel contains no further Objects to be read. * - A null Object pointer will also be returned if this function c is invoked with the AST error status set, or if it should fail f is invoked with STATUS set to an error value, or if it should fail * for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstLoaderType *loader; /* Pointer to loader for Object */ AstObject *new; /* Pointer to new Object */ char *class; /* Pointer to Object class name string */ char *name; /* Pointer to data item name */ int skip; /* Skip non-AST data? */ int top; /* Reading top-level Object definition? */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Determine if we are reading a top-level (i.e. user-level) Object definition, as opposed to the definition of an Object contained within another Object. This is indicated by the current nesting level. */ top = ( nest == -1 ); /* If reading a top-level object, determine if data lying in between Object definitions in the input data stream are to be skipped. */ skip = ( top && astGetSkip( this ) ); /* Read the next input data item. If we are reading a top-level Object definition, skip any unrelated data beforehand. Otherwise read the data strictly as it comes (there should be no unrelated data embedded within Object definitions themselves). */ astGetNextData( this, skip, &name, &class ); /* If no suitable data item was found (and no error occurred), we have reached the end of data. For a top-level Object a NULL Object pointer is simply returned, but for a nested Object this indicates that part of the Object definition is missing, so report an error. */ if ( astOK ) { if ( !name ) { if ( !top ) { astError( AST__EOCHN, "astRead(%s): End of input encountered while trying to " "read an AST Object.", status, astGetClass( this ) ); } /* If a data item was found, check it is a "Begin" item. If not, there is a data item missing, so report an error and free all memory. */ } else if ( strcmp( name, "begin" ) ) { astError( AST__BADIN, "astRead(%s): Missing \"Begin\" when expecting an Object.", status, astGetClass( this ) ); name = astFree( name ); if ( class ) class = astFree( class ); /* If the required "Begin" item was found, free the memory used for the name string. */ } else { name = astFree( name ); /* Use the associated class name to locate the loader for that class. This function will then be used to build the Object. */ loader = astGetLoader( class, status ); /* Extend all necessary stack arrays to accommodate entries for the next nesting level (this allocates space if none has yet been allocated). */ end_of_object = astGrow( end_of_object, nest + 2, sizeof( int ) ); object_class = astGrow( object_class, nest + 2, sizeof( char * ) ); values_class = astGrow( values_class, nest + 2, sizeof( char * ) ); values_list = astGrow( values_list, nest + 2, sizeof( AstChannelValue * ) ); values_ok = astGrow( values_ok, nest + 2, sizeof( int ) ); /* If an error occurred, free the memory used by the class string, which will not now be used. */ if ( !astOK ) { class = astFree( class ); /* Otherwise, increment the nesting level and initialise the new stack elements for this new level. This includes clearing the "end_of_object" flag so that ReadClassData can read more data, and storing the class name of the object we are about to read. */ } else { nest++; end_of_object[ nest ] = 0; object_class[ nest ] = class; values_class[ nest ] = NULL; values_list[ nest ] = NULL; values_ok[ nest ] = 0; /* Invoke the loader, which reads the Object definition from the input data stream and builds the Object. Supply NULL/zero values to the loader so that it will substitute values appropriate to its own class. */ new = (*loader)( NULL, (size_t) 0, NULL, NULL, this, status ); /* Clear the values list for the current nesting level. If the list has not been read or any Values remain in it, an error will result. */ ClearValues( this, status ); /* If no error has yet occurred, check that the "end_of_object" flag has been set. If not, the input data were not correctly terminated, so report an error. */ if ( astOK && !end_of_object[ nest ] ) { astError( AST__BADIN, "astRead(%s): Unexpected end of input (missing end " "of %s).", status, astGetClass( this ), object_class[ nest ] ); } /* If an error occurred, report contextual information. Only do this for top-level Objects to avoid multple messages. */ if ( !astOK && top ) { astError( astStatus, "Error while reading a %s from a %s.", status, class, astGetClass( this ) ); } /* Clear the Object's class string, freeing the associated memory (note this is the memory allocated for the "class" string earlier). */ object_class[ nest ] = astFree( object_class[ nest ] ); /* Restore the previous nesting level. */ nest--; } /* Once the top-level Object has been built, free the memory used by the stack arrays. */ if ( top ) { end_of_object = astFree( end_of_object ); object_class = astFree( object_class ); values_class = astFree( values_class ); values_list = astFree( values_list ); values_ok = astFree( values_ok ); } } } /* If an error occurred, clean up by deleting the new Object and return a NULL pointer. */ if ( !astOK ) new = astDelete( new ); /* Return the pointer to the new Object. */ return new; } static void ReadClassData( AstChannel *this, const char *class, int *status ) { /* *+ * Name: * astReadClassData * Purpose: * Read values from a data source for a class loader. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astReadClassData( AstChannel *this, const char *class ) * Class Membership: * Channel method. * Description: * This function reads the data for a class from the data source * associated with a Channel, so as to provide values for * initialising the instance variables of that class as part of * building a complete Object. This function should be invoked by * the loader for each class immediately before it attempts to read * these values. * * The values read are placed into the current values list by this * function. They may then be read from this list by the class * loader making calls to astReadDouble, astReadInt, astReadObject * and astReadString. The order in which values are read by the * loader is unimportant (although using the same order for reading * as for writing will usually be more efficient) and values are * removed from the list as they are read. * Parameters: * this * Pointer to the Channel. * class * A pointer to a constant null-terminated string containing the * name of the class whose loader is requesting the data (note * this is not usually the same as the class name of the Object * being built). This value allows the class structure of the * input data to be validated. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstObject *object; /* Pointer to new Object */ AstChannelValue *value; /* Pointer to Value structure */ char *name; /* Pointer to data item name string */ char *val; /* Pointer to data item value string */ int done; /* All class data read? */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* If the "values_ok" flag is set, this indicates that the values list (at the current nesting level) has been filled by a previous invocation of this function and has then been read by the appropriate class loader. In this case, clear any entries which may remain in the current values list. If any such entries are found, they represent input data that were not read, so an error will result. */ if ( values_ok[ nest ] ) ClearValues( this, status ); /* If "values_class" is non-NULL, this indicates that the values list (at the current nesting level) has been filled by a previous invocation of this function, but that the values belong to a class whose loader has not yet tried to read them. In this case, we must continue to keep the values until they are needed, so we do not read any more input data this time. */ if ( values_class[ nest ] ) { /* If the class to which the previously saved values belong matches the class we now want values for, set the "values_ok" flag. This then allows the values to be accessed (by LookupValue). */ values_ok[ nest ] = !strcmp( values_class[ nest ], class ); /* If the current values list is empty, we must read in values for the next class that appears in the input data. However, first check that the "end_of_object" flag has not been set. If it has, we have already reached the end of this Object's data, so there is some kind of problem with the order in which class loaders have been invoked. This will probably never happen, but report an error if necessary. */ } else if ( end_of_object[ nest ] ) { astError( AST__LDERR, "astRead(%s): Invalid attempt to read further %s data " "following an end of %s.", status, astGetClass( this ), class, object_class[ nest ] ); astError( AST__LDERR, "Perhaps the wrong class loader has been invoked?" , status); /* If we need new values, loop to read input data items until the end of the data for a class is reached. */ } else { done = 0; while ( astOK && !done ) { /* Read the next input data item. */ astGetNextData( this, 0, &name, &val ); if ( astOK ) { /* Unexpected end of input. */ /* ------------------------ */ /* If no "name" value is returned, we have reached the end of the input data stream without finding the required end of class terminator, so report an error. */ if ( !name ) { astError( AST__EOCHN, "astRead(%s): Unexpected end of input (missing end " "of %s).", status, astGetClass( this ), object_class[ nest ] ); /* "IsA" item. */ /* ----------- */ /* Otherwise, if an "IsA" item was read, it indicates the end of the data for a class. Store the pointer to the name of this class in "values_class" and note whether this is the class whose data we wanted in "values_ok". If the data we have read do not belong to the class we wanted, they will simply be kept until the right class comes looking for them. */ } else if ( !strcmp( name, "isa" ) ) { values_class[ nest ] = val; values_ok[ nest ] = !strcmp( val, class ); /* Free the memory holding the name string. */ name = astFree( name ); /* Note we have finished reading class data. */ done = 1; /* "End" item. */ /* ----------- */ /* If an "End" item was read, it indicates the end of the data both for a class and for the current Object definition as a whole. Set the "end_of_object" flag (for the current nesting level) which prevents any further data being read for this Object. This flag is also used (by Read) to check that an "End" item was actually read. */ } else if ( !strcmp( name, "end" ) ) { end_of_object[ nest ] = 1; /* Check that the class name in the "End" item matches that of the Object being built. If so, store the pointer to the name of this class in "values_class" and note whether this is the class whose data we wanted in "values_ok". If the data we have read do not belong to the class we wanted, they will simply be kept until the right class comes looking for them. */ if ( !strcmp( val, object_class[ nest ] ) ) { values_class[ nest ] = val; values_ok[ nest ] = !strcmp( class, val ); /* If the "End" item contains the wrong class name (i.e. not matching the corresponding "Begin" item), then report an error. */ } else { astError( AST__BADIN, "astRead(%s): Bad class structure in input data.", status, astGetClass( this ) ); astError( AST__BADIN, "End of %s read when expecting end of %s.", status, val, object_class[ nest ] ); /* Free the memory used by the class string, which will not now be used. */ val = astFree( val ); } /* Free the memory holding the name string. */ name = astFree( name ); /* Note we have finished reading class data. */ done = 1; /* String value. */ /* ------------- */ /* If any other name is obtained and "val" is not NULL, we have read a non-Object value, encoded as a string. Allocate memory for a Value structure to describe it. */ } else if ( val ) { value = astMalloc( sizeof( AstChannelValue ) ); if ( astOK ) { /* Store pointers to the name and value string in the Value structure and note this is not an Object value. */ value->name = name; value->ptr.string = val; value->is_object = 0; /* Append the Value structure to the values list for the current nesting level. */ AppendValue( value, values_list + nest, status ); /* If an error occurred, free the memory holding the "name" and "val" strings. */ } else { name = astFree( name ); val = astFree( val ); } /* Object value. */ /* ------------- */ /* If "val" is NULL, we have read an Object item, and the Object definition should follow. Allocate memory for a Value structure to describe it. */ } else { value = astMalloc( sizeof( AstChannelValue ) ); /* Invoke astRead to read the Object definition from subsequent data items and to build the Object, returning a pointer to it. This will result in recursive calls to the current function, but as these will use higher nesting levels they will not interfere with the current invocation. */ astreadclassdata_msg = 0; object = astRead( this ); if ( astOK ) { /* Store pointers to the name and Object in the Value structure and note this is an Object value. */ value->name = name; value->ptr.object = object; value->is_object = 1; /* Append the Value structure to the values list for the current nesting level. */ AppendValue( value, values_list + nest, status ); /* If an error occurred, report a contextual error maessage and set the "astreadclassdata_msg" flag (this prevents multiple messages if this function is invoked recursively to deal with nested Objects). */ } else { if ( !astreadclassdata_msg ) { astError( astStatus, "Failed to read the \"%s\" Object value.", status, name ); astreadclassdata_msg = 1; } /* Free the memory holding the "name" string and any Value structure that was allocated. */ name = astFree( name ); value = astFree( value ); } } } } } } static double ReadDouble( AstChannel *this, const char *name, double def, int *status ) { /* *+ * Name: * astReadDouble * Purpose: * Read a double value as part of loading a class. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * double astReadDouble( AstChannel *this, const char *name, double def ) * Class Membership: * Channel method. * Description: * This function searches the current values list of a Channel to * identify a double value with a specified name. If such a value * is found, it is returned, otherwise a default value is returned * instead. * * This function should only be invoked from within the loader * function associated with a class, in order to return a double * value to be assigned to an instance variable. It must be * preceded by a call to the astReadClassData function, which loads * the values associated with the class into the current values * list from the input data source. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated character string * containing the name of the required value. This must be in * lower case with no surrounding white space. Note that names * longer than 6 characters will not match any value. * def * If no suitable value can be found (e.g. it is absent from the * data stream being read), then this value will be returned * instead. * Returned Value: * The required value, or the default if the value was not found. * Notes: * - A value of 0.0 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstChannelValue *value; /* Pointer to required Value structure */ double result; /* Value to be returned */ int nc; /* Number of characters read by astSscanf */ /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Search for a Value structure with the required name in the current values list.*/ value = LookupValue( name, status ); if ( astOK ) { /* If a Value was found, check that it describes a string (as opposed to an Object). */ if ( value ) { if ( !value->is_object ) { /* If so, then attempt to decode the string to give a double value, checking that the entire string is read (and checking for the magic string used to represent bad values). If this fails, then the wrong name has probably been given, or the input data are corrupt, so report an error. */ nc = 0; if ( ( 0 == astSscanf( value->ptr.string, " " BAD_STRING " %n", &nc ) ) && ( nc >= (int) strlen( value->ptr.string ) ) ) { result = AST__BAD; } else if ( !( ( 1 == astSscanf( value->ptr.string, " %lf %n", &result, &nc ) ) && ( nc >= (int) strlen( value->ptr.string ) ) ) ) { astError( AST__BADIN, "astRead(%s): The value \"%s = %s\" cannot " "be read as a double precision floating point " "number.", status, astGetClass( this ), value->name, value->ptr.string ); } else if( !astISFINITE( result ) ) { astError( AST__BADIN, "astRead(%s): Illegal double precision floating " "point value \"%s\" read for \"%s\".", status, astGetClass( this ), value->ptr.string, value->name ); } /* Report a similar error if the Value does not describe a string. */ } else { astError( AST__BADIN, "astRead(%s): The Object \"%s = <%s>\" cannot " "be read as a double precision floating point number.", status, astGetClass( this ), value->name, astGetClass( value->ptr.object ) ); } /* Free the Value structure and the resources it points at. */ value = FreeValue( value, status ); /* If no suitable Value structure was found, then use the default value instead. */ } else { result = def; } } /* Return the result. */ return result; } static int ReadInt( AstChannel *this, const char *name, int def, int *status ) { /* *+ * Name: * astReadInt * Purpose: * Read an int value as part of loading a class. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * int astReadInt( AstChannel *this, const char *name, int def ) * Class Membership: * Channel method. * Description: * This function searches the current values list of a Channel to * identify an int value with a specified name. If such a value is * found, it is returned, otherwise a default value is returned * instead. * * This function should only be invoked from within the loader * function associated with a class, in order to return an int * value to be assigned to an instance variable. It must be * preceded by a call to the astReadClassData function, which loads * the values associated with the class into the current values * list from the input data source. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated character string * containing the name of the required value. This must be in * lower case with no surrounding white space. Note that names * longer than 6 characters will not match any value. * def * If no suitable value can be found (e.g. it is absent from the * data stream being read), then this value will be returned * instead. * Returned Value: * The required value, or the default if the value was not found. * 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: */ AstChannelValue *value; /* Pointer to required Value structure */ int nc; /* Number of characters read by astSscanf */ int result; /* Value to be returned */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Search for a Value structure with the required name in the current values list.*/ value = LookupValue( name, status ); if ( astOK ) { /* If a Value was found, check that it describes a string (as opposed to an Object). */ if ( value ) { if ( !value->is_object ) { /* If so, then attempt to decode the string to give an int value, checking that the entire string is read. If this fails, then the wrong name has probably been given, or the input data are corrupt, so report an error. */ nc = 0; if ( !( ( 1 == astSscanf( value->ptr.string, " %d %n", &result, &nc ) ) && ( nc >= (int) strlen( value->ptr.string ) ) ) ) { astError( AST__BADIN, "astRead(%s): The value \"%s = %s\" cannot " "be read as an integer.", status, astGetClass( this ), value->name, value->ptr.string ); } /* Report a similar error if the Value does not describe a string. */ } else { astError( AST__BADIN, "astRead(%s): The Object \"%s = <%s>\" cannot " "be read as an integer.", status, astGetClass( this ), value->name, astGetClass( value->ptr.object ) ); } /* Free the Value structure and the resources it points at. */ value = FreeValue( value, status ); /* If no suitable Value structure was found, then use the default value instead. */ } else { result = def; } } /* Return the result. */ return result; } static AstObject *ReadObject( AstChannel *this, const char *name, AstObject *def, int *status ) { /* *+ * Name: * astReadObject * Purpose: * Read a (sub)Object as part of loading a class. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * AstObject *astReadObject( AstChannel *this, const char *name, * AstObject *def ) * Class Membership: * Channel method. * Description: * This function searches the current values list of a Channel to * identify an Object with a specified name. If such an Object is * found, a pointer to it is returned, otherwise a default pointer * is returned instead. * * This function should only be invoked from within the loader * function associated with a class, in order to return an Object * pointer value to be assigned to an instance variable. It must be * preceded by a call to the astReadClassData function, which loads * the values associated with the class into the current values * list from the input data source. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated character string * containing the name of the required Object. This must be in * lower case with no surrounding white space. Note that names * longer than 6 characters will not match any Object. * def * If no suitable Object can be found (e.g. the Object is absent * from the data stream being read), then a clone of this * default Object pointer will be returned instead (or NULL if * this default pointer is NULL). * Returned Value: * A pointer to the Object, or a clone of the default pointer if * the Object was not found. * 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: */ AstObject *result; /* Pointer value to return */ AstChannelValue *value; /* Pointer to required Value structure */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Search for a Value structure with the required name in the current values list.*/ value = LookupValue( name, status ); if ( astOK ) { /* If a Value was found, check that it describes an Object (as opposed to a string). */ if ( value ) { if ( value->is_object ) { /* If so, then extract the Object pointer, replacing it with NULL. */ result = value->ptr.object; value->ptr.object = NULL; /* If the Value does not describe an Object, then the wrong name has probably been given, or the input data are corrupt, so report an error. */ } else { astError( AST__BADIN, "astRead(%s): The value \"%s = %s\" cannot be " "read as an Object.", status, astGetClass( this ), value->name, value->ptr.string ); } /* Free the Value structure and the resources it points at. */ value = FreeValue( value, status ); /* If no suitable Value structure was found, clone the default pointer, if given. */ } else if ( def ) { result = astClone( def ); } } /* Return the result. */ return result; } static char *ReadString( AstChannel *this, const char *name, const char *def, int *status ) { /* *+ * Name: * astReadString * Purpose: * Read a string value as part of loading a class. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * char *astReadString( AstChannel *this, const char *name, * const char *def ) * Class Membership: * Channel method. * Description: * This function searches the current values list of a Channel to * identify a string value with a specified name. If such a value * is found, a pointer to the string is returned, otherwise a * pointer to a copy of a default string is returned instead. * * This function should only be invoked from within the loader * function associated with a class, in order to return a string * pointer value to be assigned to an instance variable. It must be * preceded by a call to the astReadClassData function, which loads * the values associated with the class into the current values * list from the input data source. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated character string * containing the name of the required value. This must be in * lower case with no surrounding white space. Note that names * longer than 6 characters will not match any value. * def * If no suitable string can be found (e.g. the value is absent * from the data stream being read), then a dynamically * allocated copy of the null-terminated string pointed at by * "def" will be made, and a pointer to this copy will be * returned instead (or NULL if this default pointer is NULL). * Returned Value: * A pointer to a dynamically allocated null-terminated string * containing the value required, or to a copy of the default * string if the value was not found (or NULL if the "def" pointer * was NULL). * Notes: * - It is the caller's responsibility to arrange for the memory * holding the returned string to be freed (using astFree) when it * is no longer required. * - 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: */ AstChannelValue *value; /* Pointer to required Value structure */ char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Search for a Value structure with the required name in the current values list.*/ value = LookupValue( name, status ); if ( astOK ) { /* If a Value was found, check that it describes a string (as opposed to an Object). */ if ( value ) { if ( !value->is_object ) { /* If so, then extract the string pointer, replacing it with NULL. */ result = value->ptr.string; value->ptr.string = NULL; /* If the Value does not describe a string, then the wrong name has probably been given, or the input data are corrupt, so report an error. */ } else { astError( AST__BADIN, "astRead(%s): The Object \"%s = <%s>\" cannot " "be read as a string.", status, astGetClass( this ), value->name, astGetClass( value->ptr.object ) ); } /* Free the Value structure and the resources it points at. */ value = FreeValue( value, status ); /* If no suitable Value structure was found, then make a dynamic copy of the default string (if given) and return a pointer to this. */ } else if ( def ) { result = astStore( NULL, def, strlen( def ) + (size_t) 1 ); } } /* Return the result. */ return result; } static void RemoveValue( AstChannelValue *value, AstChannelValue **head, int *status ) { /* * Name: * RemoveValue * Purpose: * Remove a Value structure from a circular linked list. * Type: * Private function. * Synopsis: * #include "channel.h" * void RemoveValue( AstChannelValue *value, AstChannelValue **head, int *status ); * Class Membership: * Channel member function. * Description: * This function removes a Value structure from a doubly linked * circular list of such structures. The "head of list" pointer is * updated to point at the element following the one removed. * Parameters: * value * Pointer to the structure to be removed (note that this must * actually be in the list, although this function does not * check). * head * Address of a pointer to the element at the head of the * list. This pointer will be updated to point at the list * element that follows the one removed. If the list becomes * empty, the pointer will be set to NULL. * status * Pointer to the inherited status variable. * Notes: * - This function does not perform error chacking and does not * generate errors. */ /* Remove the Value structure from the list by re-establishing links between the elements on either side of it. */ value->blink->flink = value->flink; value->flink->blink = value->blink; /* Update the head of list pointer to identify the following element. */ *head = value->flink; /* If the head of list identifies the removed element, then note that the list is now empty. */ if ( *head == value ) *head = NULL; /* Make the removed element point at itself. */ value->flink = value; value->blink = value; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Channel. * Type: * Private function. * Synopsis: * #include "channel.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * Channel member function (over-rides the astSetAttrib protected * method inherited from the Object class). * Description: * This function assigns an attribute value for a Channel, 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 Channel. * setting * Pointer to a null terminated string specifying the new attribute * value. */ /* Local Variables: */ AstChannel *this; /* Pointer to the Channel structure */ int comment; /* Comment attribute value */ int full; /* Full attribute value */ int indent; /* Indent attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by "astSscanf" */ int report_level; /* Skip attribute value */ int skip; /* Skip attribute value */ int sourcefile; /* Offset of SourceFile string */ int sinkfile; /* Offset of SinkFile string */ int strict; /* Report errors instead of warnings? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Channel structure. */ this = (AstChannel *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Comment. */ /* ---------*/ if ( nc = 0, ( 1 == astSscanf( setting, "comment= %d %n", &comment, &nc ) ) && ( nc >= len ) ) { astSetComment( this, comment ); /* Full. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "full= %d %n", &full, &nc ) ) && ( nc >= len ) ) { astSetFull( this, full ); /* Indent. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "indent= %d %n", &indent, &nc ) ) && ( nc >= len ) ) { astSetIndent( this, indent ); /* ReportLavel. */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "reportlevel= %d %n", &report_level, &nc ) ) && ( nc >= len ) ) { astSetReportLevel( this, report_level ); /* Skip. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "skip= %d %n", &skip, &nc ) ) && ( nc >= len ) ) { astSetSkip( this, skip ); /* SinkFile. */ /* --------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "sinkfile=%n%*[^\n]%n", &sinkfile, &nc ) ) && ( nc >= len ) ) { astSetSinkFile( this, setting + sinkfile ); /* SourceFile. */ /* ----------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "sourcefile=%n%*[^\n]%n", &sourcefile, &nc ) ) && ( nc >= len ) ) { astSetSourceFile( this, setting + sourcefile ); /* Strict. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "strict= %d %n", &strict, &nc ) ) && ( nc >= len ) ) { astSetStrict( this, strict ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SinkWrap( void (* sink)( const char * ), const char *line, int *status ) { /* * Name: * SinkWrap * Purpose: * Wrapper function to invoke a C Channel sink function. * Type: * Private function. * Synopsis: * #include "channel.h" * void SinkWrap( void (* sink)( const char * ), const char *line, int *status ) * Class Membership: * Channel member function. * Description: * This function invokes the sink function whose pointer is * supplied in order to write an output line to an external data * store. * Parameters: * sink * Pointer to a sink function, whose single parameter is a * pointer to a const, null-terminated string containing the * text to be written, and which returns void. This is the form * of Channel sink function employed by the C language interface * to the AST library. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the sink function. */ ( *sink )( line ); } static char *SourceWrap( const char *(* source)( void ), int *status ) { /* * Name: * SourceWrap * Purpose: * Wrapper function to invoke a C Channel source function. * Type: * Private function. * Synopsis: * #include "channel.h" * char *SourceWrap( const char *, int *status(* source)( void ) ) * Class Membership: * Channel member function. * Description: * This function invokes the source function whose pointer is * supplied in order to read the next input line from an external * data store. It then returns a pointer to a dynamic string * containing a copy of the text that was read. * Parameters: * source * Pointer to a source function, with no parameters, that * returns a pointer to a const, null-terminated string * containing the text that it read. This is the form of Channel * source function employed by the C language interface to the * AST library. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated, null terminated string * containing a copy of the text that was read. This string must be * freed by the caller (using astFree) when no longer required. * * A NULL pointer will be returned if there is no more input text * to read. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ char *result; /* Pointer value to return */ const char *line; /* Pointer to input line */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the source function to read the next input line and return a pointer to the resulting string. */ line = ( *source )(); /* If a string was obtained, make a dynamic copy of it and save the resulting pointer. */ if ( line ) result = astString( line, (int) strlen( line ) ); /* Return the result. */ return result; } void astStoreChannelData_( AstChannel *this, int *status ) { /* *+ * Name: * astStoreChannelData * Purpose: * Store the Channel's channel-data pointer in a thread-specific * global variable. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * astStoreChannelData( AstChannel *this ) * Class Membership: * Channel method. * Description: * This function stores the Channel's channel-data pointer (if any) * established by the previous call to astPutChannelData, in a * thread-specific global variable from where the astChannelData macro * can access it. * Parameters: * this * Pointer to the Channel. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Store the pointer int he global variable. */ channel_data = this->data; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Channel. * Type: * Private function. * Synopsis: * #include "channel.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Channel member function (over-rides the astTestAttrib protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Channel's attributes. * Parameters: * this * Pointer to the Channel. * 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: */ AstChannel *this; /* Pointer to the Channel structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Channel structure. */ this = (AstChannel *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Comment. */ /* -------- */ if ( !strcmp( attrib, "comment" ) ) { result = astTestComment( this ); /* Full. */ /* ----- */ } else if ( !strcmp( attrib, "full" ) ) { result = astTestFull( this ); /* Indent. */ /* ------- */ } else if ( !strcmp( attrib, "indent" ) ) { result = astTestIndent( this ); /* ReportLevel. */ /* ------------ */ } else if ( !strcmp( attrib, "reportlevel" ) ) { result = astTestReportLevel( this ); /* Skip. */ /* ----- */ } else if ( !strcmp( attrib, "skip" ) ) { result = astTestSkip( this ); /* SourceFile. */ /* ----------- */ } else if ( !strcmp( attrib, "sourcefile" ) ) { result = astTestSourceFile( this ); /* SinkFile. */ /* ----------- */ } else if ( !strcmp( attrib, "sinkfile" ) ) { result = astTestSinkFile( this ); /* Strict. */ /* ------- */ } else if ( !strcmp( attrib, "strict" ) ) { result = astTestStrict( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static void Unquote( AstChannel *this, char *str, int *status ) { /* * Name: * Unquote * Purpose: * Remove quotes from a (possibly) quoted string. * Type: * Private function. * Synopsis: * #include "channel.h" * void Unquote( AstChannel *this, char *str, int *status ) * Class Membership: * Channel member function. * Description: * This function removes one layer of quote characters (") from a * string which is possibly quoted. Any quotes within quotes (which * should have been doubled when the string was originally quoted) * are also converted back to single quotes again. * * The quotes need not start or end at the ends of the string, and * there may be any number of quoted sections within the string. No * error results if the string does not contain any quotes at all * (it is simply returned unchanged), but an error results if any * unmatched quotes are found. * Parameters: * this * Pointer to a Channel. This is only used for constructing error * messages and has no influence on the string processing. * str * Pointer to the null-terminated string to be processed. This * is modified in place. The new string starts at the same * location as the original but has a new null character * appended if necessary (it will usually be shorter than the * original). * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; /* Loop counter for "input" characters */ int j; /* Counter for "output" characters */ int quoted; /* Inside a quoted string? */ /* Check the global error status. */ if ( !astOK ) return; /* Loop to inspect each character in the string. */ quoted = 0; for ( i = j = 0; str[ i ]; i++ ) { /* Non-quote characters are simply copied to their new location in the string. */ if ( str[ i ] != '"' ) { str[ j++ ] = str[ i ]; /* If a quote character '"' is encountered and we are not already in a quoted string, then note the start of a quoted string (and discard the quote). */ } else if ( !quoted ) { quoted = 1; /* If a quote character is encountered inside a quoted string, then check if the next character is also a quote. If so, convert this double quote to a single one. */ } else if ( str[ i + 1 ] == '"' ) { str[ j++ ] = '"'; i++; /* If a single quote character is encountered inside a quoted string, then note the end of the quoted string (and discard the quote). */ } else { quoted = 0; } } /* Append a null to terminate the processed string. */ str[ j ] = '\0'; /* If the "quoted" flag is still set, then there were unmatched quotes, so report an error. */ if ( quoted ) { astError( AST__UNMQT, "astRead(%s): Unmatched quotes in input data: %s.", status, astGetClass( this ), str ); } } static int Use( AstChannel *this, int set, int helpful, int *status ) { /* * Name: * Use * Purpose: * Decide whether to write a value to a data sink. * Type: * Private function. * Synopsis: * #include "channel.h" * int Use( AstChannel *this, int set, int helpful, int *status ) * Class Membership: * Channel member function. * Description: * This function decides whether a value supplied by a class "Dump" * function, via a call to one of the astWrite... protected * methods, should actually be written to the data sink associated * with a Channel. * * This decision is based on the settings of the "set" and * "helpful" flags supplied to the astWrite... method, plus the * attribute settings of the Channel. * Parameters: * this * A pointer to the Channel. * set * The "set" flag supplied. * helpful * The "helpful" value supplied. * status * Pointer to the inherited status variable. * Returned Value: * One if the value should be written out, otherwise zero. * 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: */ int full; /* Full attribute value */ int result; /* Result value to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* If "set" is non-zero, then so is the result ("set" values must always be written out). */ result = ( set != 0 ); /* Otherwise, obtain the value of the Channel's Full attribute. */ if ( !set ) { full = astGetFull( this ); /* If Full is positive, display all values, if zero, display only "helpful" values, if negative, display no (un-"set") values. */ if ( astOK ) result = ( ( helpful && ( full > -1 ) ) || ( full > 0 ) ); } /* Return the result. */ return result; } static int Write( AstChannel *this, AstObject *object, int *status ) { /* *++ * Name: c astWrite f AST_WRITE * Purpose: * Write an Object to a Channel. * Type: * Public function. * Synopsis: c #include "channel.h" c int astWrite( AstChannel *this, AstObject *object ) f RESULT = AST_WRITE( THIS, OBJECT, STATUS ) * Class Membership: * Channel method. * Description: * This function writes an Object to a Channel, appending it to any * previous Objects written to that Channel. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Channel. c object f OBJECT = INTEGER (Given) * Pointer to the Object which is to be written. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astWrite() f AST_WRITE = INTEGER * The number of Objects written to the Channel by this c invocation of astWrite (normally, this will be one). f invocation of AST_WRITE (normally, this will be one). * Applicability: * FitsChan * If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather * than the native AST encoding, then storing values in the * FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking c astWrite f AST_WRITE * can help to produce a successful write. * Notes: * - A value of zero will be returned if this function is invoked c with the AST error status set, or if it should fail for any f with STATUS set to an error value, or if it should fail for any * reason. * - Invoking this function will usually cause the sink function * associated with the channel to be called in order to transfer a * textual description of the supplied object to some external data * store. However, the FitsChan class behaves differently. Invoking * this function on a FitsChan causes new FITS header cards to be * added to an internal buffer (the sink function is not invoked). * This buffer is written out through the sink function only when the * FitsChan is deleted. *-- */ /* Check the global error status. */ if ( !astOK ) return 0; /* The work of this function is actually performed by the protected astDump method of the Object. The fact that this is further encapsulated within the astWrite method (which belongs to the Channel) is simply a trick to allow it to be over-ridden either by a derived Channel, or a derived Object (or both), and hence to adapt to the nature of either argument. */ astDump( object, this ); /* Return the number of Objects written. */ return astOK ? 1 : 0; } static void WriteBegin( AstChannel *this, const char *class, const char *comment, int *status ) { /* *+ * Name: * astWriteBegin * Purpose: * Write a "Begin" data item to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteBegin( AstChannel *this, const char *class, * const char *comment ) * Class Membership: * Channel method. * Description: * This function writes a "Begin" data item to the data sink * associated with a Channel, so as to begin the output of a new * Object definition. * Parameters: * this * Pointer to the Channel. * class * Pointer to a constant null-terminated string containing the * name of the class to which the Object belongs. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the "Begin" * item. Normally, this will describe the purpose of the Object. * Notes: * - The comment supplied may not actually be used, depending on * the nature of the Channel supplied. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ int i; /* Loop counter for indentation characters */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Start building a dynamic string with an initial space. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, " " ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the "Begin" keyword followed by the class name. */ line = astAppendString( line, &nc, "Begin " ); line = astAppendString( line, &nc, class ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); /* Increment the indentation level and clear the count of items written for this Object. */ current_indent += astGetIndent( this ); items_written = 0; } static void WriteDouble( AstChannel *this, const char *name, int set, int helpful, double value, const char *comment, int *status ) { /* *+ * Name: * astWriteDouble * Purpose: * Write a double value to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteDouble( AstChannel *this, const char *name, * int set, int helpful, * double value, const char *comment ) * Class Membership: * Channel method. * Description: * This function writes a named double value, representing the * value of a class instance variable, to the data sink associated * with a Channel. It is intended for use by class "Dump" functions * when writing out class information which will subsequently be * re-read. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * Channel's Full attribute is set - either to permit all values * to be shown, or to suppress non-essential information * entirely. * value * The value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the Channel supplied and the setting of its * Comment attribute. *- */ /* Local Constants: */ #define BUFF_LEN 100 /* Size of local formatting buffer */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ char buff[ BUFF_LEN + 1 ]; /* Local formatting buffer */ int i; /* Loop counter for indentation characters */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Use the "set" and "helpful" flags, along with the Channel's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Start building a dynamic string with an initial space, or a comment character if "set" is zero. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, set ? " " : "#" ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the name string followed by " = ". */ line = astAppendString( line, &nc, name ); line = astAppendString( line, &nc, " = " ); /* Format the value as a string and append this. Make sure "-0" isn't produced. Use a magic string to represent bad values. */ if( value != AST__BAD ) { (void) sprintf( buff, "%.*g", DBL_DIG, value ); if ( !strcmp( buff, "-0" ) ) { buff[ 0 ] = '0'; buff[ 1 ] = '\0'; } } else { strcpy( buff, BAD_STRING ); } line = astAppendString( line, &nc, buff ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); } /* Undefine macros local to this function. */ #undef BUFF_LEN } static void WriteEnd( AstChannel *this, const char *class, int *status ) { /* *+ * Name: * astWriteEnd * Purpose: * Write an "End" data item to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteEnd( AstChannel *this, const char *class ) * Class Membership: * Channel method. * Description: * This function writes an "End" data item to the data sink * associated with a Channel. This item delimits the end of an * Object definition. * Parameters: * this * Pointer to the Channel. * class * Pointer to a constant null-terminated string containing the * class name of the Object whose definition is being terminated * by the "End" item. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ int i; /* Loop counter for indentation characters */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Decrement the indentation level so that the "End" item matches the corresponding "Begin" item. */ current_indent -= astGetIndent( this ); /* Start building a dynamic string with an initial space. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, " " ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the "End" keyword followed by the class name. */ line = astAppendString( line, &nc, "End " ); line = astAppendString( line, &nc, class ); /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); } static void WriteInt( AstChannel *this, const char *name, int set, int helpful, int value, const char *comment, int *status ) { /* *+ * Name: * astWriteInt * Purpose: * Write an integer value to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteInt( AstChannel *this, const char *name, * int set, int helpful, * int value, const char *comment ) * Class Membership: * Channel method. * Description: * This function writes a named integer value, representing the * value of a class instance variable, to the data sink associated * with a Channel. It is intended for use by class "Dump" functions * when writing out class information which will subsequently be * re-read. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * Channel's Full attribute is set - either to permit all values * to be shown, or to suppress non-essential information * entirely. * value * The value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the Channel supplied and the setting of its * Comment attribute. *- */ /* Local Constants: */ #define BUFF_LEN 50 /* Size of local formatting buffer */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ char buff[ BUFF_LEN + 1 ]; /* Local formatting buffer */ int i; /* Loop counter for indentation characters */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Use the "set" and "helpful" flags, along with the Channel's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Start building a dynamic string with an initial space, or a comment character if "set" is zero. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, set ? " " : "#" ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the name string followed by " = ". */ line = astAppendString( line, &nc, name ); line = astAppendString( line, &nc, " = " ); /* Format the value as a decimal string and append this. */ (void) sprintf( buff, "%d", value ); line = astAppendString( line, &nc, buff ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); } /* Undefine macros local to this function. */ #undef BUFF_LEN } int astWriteInvocations_( int *status ){ /* *+ * Name: * astWriteInvocations * Purpose: * Returns the number of invocations of the astWrite method. * Type: * Protected function. * Synopsis: * #include "channel.h" * int astWriteInvocations * Class Membership: * Channel method. * Description: * This function returns the number of invocations of astWrite which * have been made so far, excluding those made from within the * astWriteObject method. An example of its use is to allow a Dump * function to determine if a sub-object has already been dumped * during the current invocation of astWrite. See the Dump method for * the AstUnit class as an example. *- */ astDECLARE_GLOBALS astGET_GLOBALS(NULL); return nwrite_invoc; } static void WriteIsA( AstChannel *this, const char *class, const char *comment, int *status ) { /* *+ * Name: * astWriteIsA * Purpose: * Write an "IsA" data item to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteIsA( AstChannel *this, const char *class, * const char *comment ) * Class Membership: * Channel method. * Description: * This function writes an "IsA" data item to the data sink * associated with a Channel. This item delimits the end of the * data associated with the instance variables of a class, as part * of an overall Object definition. * Parameters: * this * Pointer to the Channel. * class * Pointer to a constant null-terminated string containing the * name of the class whose data are terminated by the "IsA" * item. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the "IsA" * item. Normally, this will describe the purpose of the class * whose data are being terminated. * Notes: * - The comment supplied may not actually be used, depending on * the nature of the Channel supplied. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ int i; /* Loop counter for indentation characters */ int indent_inc; /* Indentation increment */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Output an "IsA" item only if there has been at least one item written since the last "Begin" or "IsA" item, or if the Full attribute for the Channel is greater than zero (requesting maximum information). */ if ( items_written || astGetFull( this ) > 0 ) { /* Start building a dynamic string with an initial space. Then add further spaces to suit the current indentation level, but reduced by one to allow the "IsA" item to match the "Begin" and "End" items which enclose it. */ indent_inc = astGetIndent( this ); line = astAppendString( NULL, &nc, " " ); for ( i = 0; i < ( current_indent - indent_inc ); i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the "IsA" keyword followed by the class name. */ line = astAppendString( line, &nc, "IsA " ); line = astAppendString( line, &nc, class ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); /* Clear the count of items written for this class. */ items_written = 0; } } static void WriteObject( AstChannel *this, const char *name, int set, int helpful, AstObject *value, const char *comment, int *status ) { /* *+ * Name: * astWriteObject * Purpose: * Write an Object as a value to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteObject( AstChannel *this, const char *name, * int set, int helpful, * AstObject *value, const char *comment ) * Class Membership: * Channel method. * Description: * This function writes an Object as a named value, representing * the value of a class instance variable, to the data sink * associated with a Channel. It is intended for use by class * "Dump" functions when writing out class information which will * subsequently be re-read. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * Channel's Full attribute is set - either to permit all values * to be shown, or to suppress non-essential information * entirely. * value * A Pointer to the Object to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the Channel supplied and the setting of its * Comment attribute. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ int i; /* Loop counter for indentation characters */ int indent_inc; /* Indentation increment */ int nc; /* Number of output characters */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Use the "set" and "helpful" flags, along with the Channel's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Start building a dynamic string with an initial space, or a comment character if "set" is zero. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, set ? " " : "#" ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the name string followed by " =". The absence of a value on the right hand side indicates an Object value, whose definition follows. */ line = astAppendString( line, &nc, name ); line = astAppendString( line, &nc, " =" ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); /* If the value is not a default, write the Object to the Channel as well, suitably indented (this is omitted if the value is commented out). */ if ( set ) { indent_inc = astGetIndent( this ); current_indent += indent_inc; (void) astWrite( this, value ); current_indent -= indent_inc; } } } static void WriteString( AstChannel *this, const char *name, int set, int helpful, const char *value, const char *comment, int *status ) { /* *+ * Name: * astWriteString * Purpose: * Write a string value to a data sink. * Type: * Protected virtual function. * Synopsis: * #include "channel.h" * void astWriteString( AstChannel *this, const char *name, * int set, int helpful, * const char *value, const char *comment ) * Class Membership: * Channel method. * Description: * This function writes a named string value, representing the * value of a class instance variable, to the data sink associated * with a Channel. It is intended for use by class "Dump" functions * when writing out class information which will subsequently be * re-read. * Parameters: * this * Pointer to the Channel. * name * Pointer to a constant null-terminated string containing the * name to be used to identify the value in the external * representation. This will form the key for identifying it * again when it is re-read. The name supplied should be unique * within its class. * * Mixed case may be used and will be preserved in the external * representation (where possible) for cosmetic effect. However, * case is not significant when re-reading values. * * It is recommended that a maximum of 6 alphanumeric characters * (starting with an alphabetic character) be used. This permits * maximum flexibility in adapting to standard external data * representations (e.g. FITS). * set * If this is zero, it indicates that the value being written is * a default value (or can be re-generated from other values) so * need not necessarily be written out. Such values will * typically be included in the external representation with * (e.g.) a comment character so that they are available to * human readers but will be ignored when re-read. They may also * be completely omitted in some circumstances. * * If "set" is non-zero, the value will always be explicitly * included in the external representation so that it can be * re-read. * helpful * This flag provides a hint about whether a value whose "set" * flag is zero (above) should actually appear at all in the * external representaton. * * If the external representation allows values to be "commented * out" then, by default, values will be included in this form * only if their "helpful" flag is non-zero. Otherwise, they * will be omitted entirely. When possible, omitting the more * obscure values associated with a class is recommended in * order to improve readability. * * This default behaviour may be further modified if the * Channel's Full attribute is set - either to permit all values * to be shown, or to suppress non-essential information * entirely. * value * Pointer to a constant null-terminated string containing the * value to be written. * comment * Pointer to a constant null-terminated string containing a * textual comment to be associated with the value. * * Note that this comment may not actually be used, depending on * the nature of the Channel supplied and the setting of its * Comment attribute. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *line; /* Pointer to dynamic output string */ int i; /* Loop counter for characters */ int nc; /* Number of output characters */ int quote; /* Quote character found? */ int size; /* Size of allocated memory */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Use the "set" and "helpful" flags, along with the Channel's attributes to decide whether this value should actually be written. */ if ( Use( this, set, helpful, status ) ) { /* Start building a dynamic string with an initial space, or a comment character if "set" is zero. Then add further spaces to suit the current indentation level. */ line = astAppendString( NULL, &nc, set ? " " : "#" ); for ( i = 0; i < current_indent; i++ ) { line = astAppendString( line, &nc, " " ); } /* Append the name string followed by " = " and an opening quote character (the string will be quoted to protect leading and trailing spaces). */ line = astAppendString( line, &nc, name ); line = astAppendString( line, &nc, " = \"" ); /* We now append the value string, but must inspect each character so that quotes (appearing inside quotes) can be doubled. Determine the current size of memory allocated for the dynamic string. */ size = (int) astSizeOf( line ); /* Loop to inspect each character and see if it is a quote. */ for ( i = 0; value[ i ]; i++ ) { quote = ( value[ i ] == '"' ); /* If more memory is required, extend the dynamic string (allowing for doubling of quotes and the final null) and save its new size. */ if ( nc + 2 + quote > size ) { line = astGrow( line, nc + 2 + quote, sizeof( char ) ); if ( astOK ) { size = (int) astSizeOf( line ); /* Quit if an error occurs. */ } else { break; } } /* Append the value character to the dynamic string, duplicating each quote character. */ line[ nc++ ] = value[ i ]; if ( quote ) line[ nc++ ] = '"'; } /* Append the closing quote. */ line = astAppendString( line, &nc, "\"" ); /* If required, also append the comment. */ if ( astGetComment( this ) && *comment ) { line = astAppendString( line, &nc, " \t# " ); line = astAppendString( line, &nc, comment ); } /* Write out the resulting line of text. */ OutputTextItem( this, line, status ); /* Free the dynamic string. */ line = astFree( line ); } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. */ /* *att++ * Name: * SourceFile * Purpose: * Input file from which to read data. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the name of a file from which the Channel * should read data. If specified it is used in preference to any source * function specified when the Channel was created. * * Assigning a new value to this attribute will cause any previously * opened SourceFile to be closed. The first subsequent call to c astRead f AST_READ * will attempt to open the new file (an error will be reported if the * file cannot be opened), and read data from it. All subsequent call to c astRead f AST_READ * will read data from the new file, until the SourceFile attribute is * cleared or changed. * * Clearing the attribute causes any open SourceFile to be closed. All * subsequent data reads will use the source function specified when the * Channel was created, or will read from standard input if no source * function was specified. * * If no value has been assigned to SourceFile, a null string will be * returned if an attempt is made to get the attribute value. * Notes: * - Any open SourceFile is closed when the Channel is deleted. * - If the Channel is copied or dumped c (using astCopy or astShow) f (using AST_COPY or AST_SHOW) * the SourceFile attribute is left in a cleared state in the output * Channel (i.e. the value of the SourceFile attribute is not copied). * Applicability: * FitsChan * In the case of a FitsChan, the specified SourceFile supplements * the source function specified when the FitsChan was created, * rather than replacing the source function. The source file * should be a text file (not a FITS file) containing one header per * line. When a value is assigned to SourceFile, the file is opened * and read immediately, and all headers read from the file are * appended to the end of any header already in the FitsChan. The file * is then closed. Clearing the SourceFile attribute has no further * effect, other than nullifying the string (i.e. the file name) * associated with the attribute. *att-- */ /* Clear the SourceFile value by closing any open file, freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Channel,SourceFile,fn_in,((this->fd_in=(this->fd_in?(fclose(this->fd_in),NULL):NULL)),astFree(this->fn_in))) /* If the SourceFile value is not set, supply a default in the form of a pointer to the constant string "". */ astMAKE_GET(Channel,SourceFile,const char *,NULL,( this->fn_in ? this->fn_in : "" )) /* Set a SourceFile value by closing any open file, freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Channel,SourceFile,const char *,fn_in,((this->fd_in=(this->fd_in?(fclose(this->fd_in),NULL):NULL)),astStore( this->fn_in, value, strlen( value ) + (size_t) 1 ))) /* The SourceFile value is set if the pointer to it is not NULL. */ astMAKE_TEST(Channel,SourceFile,( this->fn_in != NULL )) /* *att++ * Name: * SinkFile * Purpose: * Output file to which to data should be written. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the name of a file to which the Channel * should write data. If specified it is used in preference to any sink * function specified when the Channel was created. * * Assigning a new value to this attribute will cause any previously * opened SinkFile to be closed. The first subsequent call to c astWrite f AST_WRITE * will attempt to open the new file (an error will be reported if the * file cannot be opened), and write data to it. All subsequent call to c astWrite f AST_WRITE * will write data to the new file, until the SinkFile attribute is * cleared or changed. * * Clearing the attribute causes any open SinkFile to be closed. All * subsequent data writes will use the sink function specified when the * Channel was created, or will write to standard output if no sink * function was specified. * * If no value has been assigned to SinkFile, a null string will be * returned if an attempt is made to get the attribute value. * Notes: * - A new SinkFile will over-write any existing file with the same * name unless the existing file is write protected, in which case an * error will be reported. * - Any open SinkFile is closed when the Channel is deleted. * - If the Channel is copied or dumped c (using astCopy or astShow) f (using AST_COPY or AST_SHOW) * the SinkFile attribute is left in a cleared state in the output * Channel (i.e. the value of the SinkFile attribute is not copied). * Applicability: * FitsChan * When the FitsChan is destroyed, any headers in the FitsChan will be * written out to the sink file, if one is specified (if not, the * sink function used when the FitsChan was created is used). The * sink file is a text file (not a FITS file) containing one header * per line. *att-- */ /* Clear the SinkFile value by closing any open file, freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Channel,SinkFile,fn_out,((this->fd_out=(this->fd_out?(fclose(this->fd_out),NULL):NULL)),astFree(this->fn_out))) /* If the SinkFile value is not set, supply a default in the form of a pointer to the constant string "". */ astMAKE_GET(Channel,SinkFile,const char *,NULL,( this->fn_out ? this->fn_out : "" )) /* Set a SinkFile value by closing any open file, freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Channel,SinkFile,const char *,fn_out,((this->fd_out=(this->fd_out?(fclose(this->fd_out),NULL):NULL)),astStore( this->fn_out, value, strlen( value ) + (size_t) 1 ))) /* The SinkFile value is set if the pointer to it is not NULL. */ astMAKE_TEST(Channel,SinkFile,( this->fn_out != NULL )) /* *att++ * Name: * Comment * Purpose: * Include textual comments in output? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This is a boolean attribute which controls whether textual * comments are to be included in the output generated by a * Channel. If included, they will describe what each item of * output represents. * * If Comment is non-zero, then comments will be included. If * it is zero, comments will be omitted. * Applicability: * Channel * The default value is non-zero for a normal Channel. * FitsChan * The default value is non-zero for a FitsChan. * XmlChan * The default value is zero for an XmlChan. *att-- */ /* This is a boolean value (0 or 1) with a value of -INT_MAX when undefined but yielding a default of one. */ astMAKE_CLEAR(Channel,Comment,comment,-INT_MAX) astMAKE_GET(Channel,Comment,int,0,( this->comment != -INT_MAX ? this->comment : 1 )) astMAKE_SET(Channel,Comment,int,comment,( value != 0 )) astMAKE_TEST(Channel,Comment,( this->comment != -INT_MAX )) /* *att++ * Name: * Full * Purpose: * Set level of output detail. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute is a three-state flag and takes values of -1, 0 * or +1. It controls the amount of information included in the * output generated by a Channel. * * If Full is zero, then a modest amount of * non-essential but useful information will be included in the * output. If Full is negative, all non-essential information will * be suppressed to minimise the amount of output, while if it is * positive, the output will include the maximum amount of detailed * information about the Object being written. * Applicability: * Channel * The default value is zero for a normal Channel. * FitsChan * The default value is zero for a FitsChan. * XmlChan * The default value is -1 for an XmlChan. * StcsChan * The default value is zero for an StcsChan. Set a positive value * to cause default values to be included in STC-S descriptions. * Notes: * - All positive values supplied for this attribute are converted * to +1 and all negative values are converted to -1. *att-- */ /* This ia a 3-state value (-1, 0 or +1) with a value of -INT_MAX when undefined but yielding a default of zero. */ astMAKE_CLEAR(Channel,Full,full,-INT_MAX) astMAKE_GET(Channel,Full,int,0,( this->full != -INT_MAX ? this->full : 0 )) astMAKE_SET(Channel,Full,int,full,( value > 0 ? 1 : ( value < 0 ? -1 : 0 ) )) astMAKE_TEST(Channel,Full,( this->full != -INT_MAX )) /* *att++ * Name: * Indent * Purpose: * Specifies the indentation to use in text produced by a Channel. * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the indentation within the output text produced by f the AST_WRITE function. c the astWrite function. * It gives the increase in the indentation for each level in the object * heirarchy. If it is set to zero, no indentation will be used. [3] * Applicability: * Channel * The default value is zero for a basic Channel. * FitsChan * The FitsChan class ignores this attribute. * StcsChan * The default value for an StcsChan is zero, which causes the entire * STC-S description is written out by a single invocation of the sink * function. The text supplied to the sink function will not contain * any linefeed characters, and each pair of adjacent words will be * separated by a single space. The text may thus be arbitrarily large * and the StcsLength attribute is ignored. * * If Indent is non-zero, then the text is written out via multiple * calls to the sink function, each call corresponding to a single * "line" of text (although no line feed characters will be inserted * by AST). The complete STC-S description is broken into lines so that: * * - the line length specified by attribute StcsLength is not exceeded * - each sub-phrase (time, space, etc.) starts on a new line * - each argument in a compound spatial region starts on a new line * * If this causes a sub-phrase to extend to two or more lines, then the * second and subsequent lines will be indented by three spaces compared * to the first line. In addition, lines within a compound spatial region * will have extra indentation to highlight the nesting produced by the * parentheses. Each new level of nesting will be indented by a further * three spaces. f f Note, the default value of zero is unlikely to be appropriate when f an StcsChan is used within Fortran code. In this case, Indent f should usually be set non-zero, and the StcsLength attribute set to f the size of the CHARACTER variable used to f receive the text returned by AST_GETLINE within the sink function. f This avoids the possibility of long lines being truncated invisibly f within AST_GETLINE. * XmlChan * The default value for an XmlChan is zero, which results in no * linefeeds or indentation strings being added to output text. * If any non-zero value is assigned to Indent, then extra linefeed and * space characters will be inserted as necessary to ensure that each * XML tag starts on a new line, and each tag will be indented by * a further 3 spaces to show its depth in the containment hierarchy. *att-- */ /* This is an integer value with a value of -INT_MAX when undefined, yielding a default of 3. Sub-classes may over-ride theis default. */ astMAKE_CLEAR(Channel,Indent,indent,-INT_MAX) astMAKE_GET(Channel,Indent,int,3,( this->indent != -INT_MAX ? this->indent : 3 )) astMAKE_SET(Channel,Indent,int,indent,value) astMAKE_TEST(Channel,Indent,( this->indent != -INT_MAX )) /* *att++ * Name: * ReportLevel * Purpose: * Determines which read/write conditions are reported. * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute determines which, if any, of the conditions that occur * whilst reading or writing an Object should be reported. These * conditions will generate either a fatal error or a warning, as * determined by attribute Strict. ReportLevel can take any of the * following values: * * 0 - Do not report any conditions. * * 1 - Report only conditions where significant information content has been * changed. For instance, an unsupported time-scale has been replaced by a * supported near-equivalent time-scale. Another example is if a basic * Channel unexpected encounters data items that may have been introduced * by later versions of AST. * * 2 - Report the above, and in addition report significant default * values. For instance, if no time-scale was specified when reading an * Object from an external data source, report the default time-scale * that is being used. * * 3 - Report the above, and in addition report any other potentially * interesting conditions that have no significant effect on the * conversion. For instance, report if a time-scale of "TT" * (terrestrial time) is used in place of "ET" (ephemeris time). This * change has no signficiant effect because ET is the predecessor of, * and is continuous with, TT. Synonyms such as "IAT" and "TAI" are * another example. * * The default value is 1. Note, there are many other conditions that * can occur whilst reading or writing an Object that completely * prevent the conversion taking place. Such conditions will always * generate errors, irrespective of the ReportLevel and Strict attributes. * Applicability: * Channel * All Channels have this attribute. * FitsChan * All the conditions selected by the FitsChan Warnings attribute are * reported at level 1. *att-- */ /* This is an integer value with a value of -INT_MAX when undefined, yielding a default of one. */ astMAKE_CLEAR(Channel,ReportLevel,report_level,-INT_MAX) astMAKE_GET(Channel,ReportLevel,int,1,( this->report_level != -INT_MAX ? this->report_level : 1 )) astMAKE_SET(Channel,ReportLevel,int,report_level,value) astMAKE_TEST(Channel,ReportLevel,( this->report_level != -INT_MAX )) /* *att++ * Name: * Skip * Purpose: * Skip irrelevant data? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This is a boolean attribute which indicates whether the Object * data being read through a Channel are inter-mixed with other, * irrelevant, external data. * * If Skip is zero (the default), then the source of input data is * expected to contain descriptions of AST Objects and comments and * nothing else (if anything else is read, an error will * result). If Skip is non-zero, then any non-Object data * encountered between Objects will be ignored and simply skipped * over in order to reach the next Object. * Applicability: * Channel * All Channels have this attribute. * FitsChan * The FitsChan class sets the default value of this attribute * to 1, so that all irrelevant FITS headers will normally be * ignored. *att-- */ /* This ia a boolean value (0 or 1) with a value of -INT_MAX when undefined but yielding a default of zero. */ astMAKE_CLEAR(Channel,Skip,skip,-INT_MAX) astMAKE_GET(Channel,Skip,int,0,( this->skip != -INT_MAX ? this->skip : 0 )) astMAKE_SET(Channel,Skip,int,skip,( value != 0 )) astMAKE_TEST(Channel,Skip,( this->skip != -INT_MAX )) /* *att++ * Name: * Strict * Purpose: * Report an error if any unexpeted data items are found? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This is a boolean attribute which indicates whether a warning * rather than an error should be issed for insignificant conversion * problems. If it is set non-zero, then fatal errors are issued * instead of warnings, resulting in the c AST error status being set. f inherited STATUS variable being set to an error value. * If Strict is zero (the default), then execution continues after minor * conversion problems, and a warning message is added to the Channel * structure. Such messages can be retrieved using the c astWarnings f AST_WARNINGS * function. * Notes: * - This attribute was introduced in AST version 5.0. Prior to this * version of AST unexpected data items read by a basic Channel always * caused an error to be reported. So applications linked against * versions of AST prior to version 5.0 may not be able to read Object * descriptions created by later versions of AST, if the Object's class * description has changed. * Applicability: * Channel * All Channels have this attribute. *att-- */ /* This ia a boolean value (0 or 1) with a value of -INT_MAX when undefined but yielding a default of zero. */ astMAKE_CLEAR(Channel,Strict,strict,-INT_MAX) astMAKE_GET(Channel,Strict,int,0,( this->strict != -INT_MAX ? this->strict : 0 )) astMAKE_SET(Channel,Strict,int,strict,( value != 0 )) astMAKE_TEST(Channel,Strict,( this->strict != -INT_MAX )) /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Channel objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Channel 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: */ AstChannel *this; /* Pointer to Channel */ /* Obtain a pointer to the Channel structure. */ this = (AstChannel *) obj; /* Free memory used to store warnings. */ astAddWarning( this, 0, NULL, NULL, status ); /* Close any open input or output files. */ if( this->fd_in ) fclose( this->fd_in ); if( this->fd_out ) fclose( this->fd_out ); /* Free file name memory. */ this->fn_in = astFree( this->fn_in ); this->fn_out = astFree( this->fn_out ); } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Channel objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Channel 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: */ AstChannel *out; /* Pointer to output Channel */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Channels. */ out = (AstChannel *) objout; /* Just clear any references to the input memory from the output Channel. */ out->warnings = NULL; out->nwarn = 0; out->fd_in = NULL; out->fn_in = NULL; out->fd_out = NULL; out->fn_out = NULL; } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Channel 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 Channel class to an output Channel. * Parameters: * this * Pointer to the Object 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 Variables: */ AstChannel *this; /* Pointer to the Channel structure */ const char *comment; /* Pointer to comment string */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Channel structure. */ this = (AstChannel *) this_object; /* Write out values representing the instance variables for the Channel 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. */ /* Indent */ /* ------------ */ set = TestIndent( this, status ); ival = set ? GetIndent( this, status ) : astGetIndent( this ); astWriteInt( channel, "Indnt", set, 0, ival, "Indentation increment" ); /* ReportLevel. */ /* ------------ */ set = TestReportLevel( this, status ); ival = set ? GetReportLevel( this, status ) : astGetReportLevel( this ); astWriteInt( channel, "RpLev", set, 0, ival, "Error reporting level" ); /* Skip. */ /* ----- */ set = TestSkip( this, status ); ival = set ? GetSkip( this, status ) : astGetSkip( this ); astWriteInt( channel, "Skip", set, 0, ival, ival ? "Ignore data between Objects" : "No data allowed between Objects" ); /* Strict. */ /* ------- */ set = TestStrict( this, status ); ival = set ? GetStrict( this, status ) : astGetStrict( this ); astWriteInt( channel, "Strict", set, 0, ival, ival ? "Report errors insead of warnings" : "Report warnings instead of errors" ); /* Full. */ /* ----- */ set = TestFull( this, status ); ival = set ? GetFull( this, status ) : astGetFull( this ); if ( ival < 0 ) { comment = "Suppress non-essential output"; }else if ( ival == 0 ) { comment = "Output standard information"; } else { comment = "Output maximum information"; } astWriteInt( channel, "Full", set, 0, ival, comment ); /* Comment. */ /* -------- */ set = TestComment( this, status ); ival = set ? GetComment( this, status ) : astGetComment( this ); astWriteInt( channel, "Comm", set, 0, ival, ival ? "Display comments" : "Omit comments" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAChannel and astCheckChannel functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Channel,Object) astMAKE_CHECK(Channel) AstChannel *astChannel_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, int *status, ...) { /* *+ * Name: * astChannel * Purpose: * Create a Channel. * Type: * Protected function. * Synopsis: * #include "channel.h" * AstChannel *astChannel( const char *(* source)( void ), * void (* sink)( const char * ), * const char *options, ..., int *status ) * Class Membership: * Channel constructor. * Description: * This function creates a new Channel and optionally initialises * its attributes. * * A Channel implements low-level input/output for the AST library. * Writing an Object to a Channel (using astWrite) will generate a * textual representation of that Object, and reading from a * Channel (using astRead) will create a new Object from its * textual representation. * * Normally, when you use a Channel, you should provide "source" * and "sink" functions which connect it to an external data store * by reading and writing the resulting text. By default, however, * a Channel will read from standard input and write to standard * output. * Parameters: * source * Pointer to a "source" function that takes no arguments and * returns a pointer to a null-terminated string. * * This function will be used by the Channel to obtain lines of * input text. On each invocation, it should return a pointer to * the next input line read from some external data store, and a * NULL pointer when there are no more lines to read. * * If "source" is NULL, the Channel will read from standard * input instead. * sink * Pointer to a "sink" function that takes a pointer to a * null-terminated string as an argument and returns void. * * This function will be used by the Channel to deliver lines of * output text. On each invocation, it should deliver the * contents of the string supplied to some external data store. * * If "sink" is NULL, the Channel will write to standard output * instead. * options * Pointer to a null-terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Channel. The syntax used is identical to * that for the astSet function 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 additional 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 function (and for the C "printf" * function). * Returned Value: * astChannel() * A pointer to the new Channel. * Notes: * - A NULL pointer value 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 Channel constructor which * is available via the protected interface to the Channel class. * A public interface is provided by the astChannelId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstChannel *new; /* Pointer to new Channel */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the Channel, allocating memory and initialising the virtual function table as well if necessary. Supply pointers to (local) wrapper functions that can invoke the source and sink functions with appropriate arguments for the C language. */ new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab, "Channel", source, SourceWrap, sink, SinkWrap ); /* 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 Channel'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 Channel. */ return new; } AstChannel *astChannelId_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, ... ) { /* *++ * Name: c astChannel f AST_CHANNEL * Purpose: * Create a Channel. * Type: * Public function. * Synopsis: c #include "channel.h" c AstChannel *astChannel( const char *(* source)( void ), c void (* sink)( const char * ), c const char *options, ... ) f RESULT = AST_CHANNEL( SOURCE, SINK, OPTIONS, STATUS ) * Class Membership: * Channel constructor. * Description: * This function creates a new Channel and optionally initialises * its attributes. * * A Channel implements low-level input/output for the AST library. c Writing an Object to a Channel (using astWrite) will generate a f Writing an Object to a Channel (using AST_WRITE) will generate a * textual representation of that Object, and reading from a c Channel (using astRead) will create a new Object from its f Channel (using AST_READ) will create a new Object from its * textual representation. * * Normally, when you use a Channel, you should provide "source" c and "sink" functions which connect it to an external data store f and "sink" routines which connect it to an external data store * by reading and writing the resulting text. By default, however, * a Channel will read from standard input and write to standard * output. Alternatively, a Channel can be told to read or write from * specific text files using the SinkFile and SourceFile attributes, * in which case no sink or source function need be supplied. * Parameters: c source f SOURCE = SUBROUTINE (Given) c Pointer to a source function that takes no arguments and c returns a pointer to a null-terminated string. If no value c has been set for the SourceFile attribute, this function c will be used by the Channel to obtain lines of input text. On c each invocation, it should return a pointer to the next input c line read from some external data store, and a NULL pointer c when there are no more lines to read. c c If "source" is NULL and no value has been set for the SourceFile c attribute, the Channel will read from standard input instead. f A source routine, which is a subroutine which takes a single f integer error status argument. If no value has been set f for the SourceFile attribute, this routine will be used by f the Channel to obtain lines of input text. On each f invocation, it should read the next input line from some f external data store, and then return the resulting text to f the AST library by calling AST_PUTLINE. It should supply a f negative line length when there are no more lines to read. f If an error occurs, it should set its own error status f argument to an error value before returning. f f If the null routine AST_NULL is suppied as the SOURCE value, f and no value has been set for the SourceFile attribute, f the Channel will read from standard input instead. c sink f SINK = SUBROUTINE (Given) c Pointer to a sink function that takes a pointer to a c null-terminated string as an argument and returns void. c If no value has been set for the SinkFile attribute, this c function will be used by the Channel to deliver lines of c output text. On each invocation, it should deliver the c contents of the string supplied to some external data store. c c If "sink" is NULL, and no value has been set for the SinkFile c attribute, the Channel will write to standard output instead. f A sink routine, which is a subroutine which takes a single f integer error status argument. If no value has been set f for the SinkFile attribute, this routine will be used by f the Channel to deliver lines of output text. On each f invocation, it should obtain the next output line from the f AST library by calling AST_GETLINE, and then deliver the f resulting text to some external data store. If an error f occurs, it should set its own error status argument to an f error value before returning. f f If the null routine AST_NULL is suppied as the SINK value, f and no value has been set for the SinkFile attribute, f the Channel will write to standard output instead. 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 Channel. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Channel. The syntax used is identical to that for the f AST_SET routine. 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 astChannel() f AST_CHANNEL = INTEGER * A pointer to the new Channel. * Notes: c - Application code can pass arbitrary data (such as file c descriptors, etc) to source and sink functions using the c astPutChannelData function. The source or sink function should use c the astChannelData macro to retrieve this data. f - The names of the routines supplied for the SOURCE and SINK f arguments should appear in EXTERNAL statements in the Fortran f routine which invokes AST_CHANNEL. However, this is not generally f necessary for the null routine AST_NULL (so long as the AST_PAR f include file has been used). * - 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. f - Note that the null routine AST_NULL (one underscore) is f different to AST__NULL (two underscores), which is the null Object f pointer. *-- * Implementation Notes: * - This function implements the external (public) interface to * the astChannel constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astChannel_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astChanel_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstChannel *new; /* Pointer to new Channel */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the Channel, allocating memory and initialising the virtual function table as well if necessary. Supply pointers to (local) wrapper functions that can invoke the source and sink functions with appropriate arguments for the C language. */ new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab, "Channel", source, SourceWrap, sink, SinkWrap ); /* 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 Channel'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 Channel. */ return astMakeId( new ); } AstChannel *astChannelForId_( const char *(* source)( void ), char *(* source_wrap)( const char *(*)( void ), int * ), void (* sink)( const char * ), void (* sink_wrap)( void (*)( const char * ), const char *, int * ), const char *options, ... ) { /* *+ * Name: * astChannelFor * Purpose: * Initialise a Channel from a foreign language interface. * Type: * Public function. * Synopsis: * #include "channel.h" * AstChannel *astChannelFor( const char *(* source)( void ), * char *(* source_wrap)( const char *(*) * ( void ), int * ), * void (* sink)( const char * ), * void (* sink_wrap)( void (*)( const char * ), * const char *, int * ), * const char *options, ... ) * Class Membership: * Channel constructor. * Description: * This function creates a new Channel from a foreign language * interface and optionally initialises its attributes. * * A Channel implements low-level input/output for the AST library. * Writing an Object to a Channel (using astWrite) will generate a * textual representation of that Object, and reading from a * Channel (using astRead) will create a new Object from its * textual representation. * * Normally, when you use a Channel, you should provide "source" * and "sink" functions which connect it to an external data store * by reading and writing the resulting text. This function also * requires you to provide "wrapper" functions which will invoke * the source and sink functions. By default, however, a Channel * will read from standard input and write to standard output. * Parameters: * source * Pointer to a "source" function which will be used to obtain * lines of input text. Generally, this will be obtained by * casting a pointer to a source function which is compatible * with the "source_wrap" wrapper function (below). The pointer * should later be cast back to its original type by the * "source_wrap" function before the function is invoked. * * If "source" is NULL, the Channel will read from standard * input instead. * source_wrap * Pointer to a function which can be used to invoke the * "source" function supplied (above). This wrapper function is * necessary in order to hide variations in the nature of the * source function, such as may arise when it is supplied by a * foreign (non-C) language interface. * * The single parameter of the "source_wrap" function is a * pointer to the "source" function, and it should cast this * function pointer (as necessary) and invoke the function with * appropriate arguments to obtain the next line of input * text. The "source_wrap" function should then return a pointer * to a dynamically allocated, null terminated string containing * the text that was read. The string will be freed (using * astFree) when no longer required and the "source_wrap" * function need not concern itself with this. A NULL pointer * should be returned if there is no more input to read. * * If "source_wrap" is NULL, the Channel will read from standard * input instead. * sink * Pointer to a "sink" function which will be used to deliver * lines of output text. Generally, this will be obtained by * casting a pointer to a sink function which is compatible with * the "sink_wrap" wrapper function (below). The pointer should * later be cast back to its original type by the "sink_wrap" * function before the function is invoked. * * If "sink" is NULL, the Channel will write to standard output * instead. * sink_wrap * Pointer to a function which can be used to invoke the "sink" * function supplied (above). This wrapper function is necessary * in order to hide variations in the nature of the sink * function, such as may arise when it is supplied by a foreign * (non-C) language interface. * * The first parameter of the "sink_wrap" function is a pointer * to the "sink" function, and the second parameter is a pointer * to a const, null-terminated character string containing the * text to be written. The "sink_wrap" function should cast the * "sink" function pointer (as necessary) and invoke the * function with appropriate arguments to deliver the line of * output text. The "sink_wrap" function then returns void. * * If "sink_wrap" is NULL, the Channel will write to standard * output instead. * options * Pointer to a null-terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Channel. The syntax used is identical to * that for the astSet function and may include "printf" format * specifiers identified by "%" symbols in the normal way. * ... * If the "options" string contains "%" format specifiers, then * an optional list of additional 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 function (and for the C "printf" * function). * Returned Value: * astChannelFor() * A pointer to the new Channel. * Notes: * - A null Object pointer (AST__NULL) will be returned if this * function is invoked with the global error status set, or if it * should fail for any reason. * - This function is only available through the public interface * to the Channel class (not the protected interface) and is * intended solely for use in implementing foreign language * interfaces to this class. *- * Implememtation Notes: * - This function behaves exactly like astChannelId_, in that it * returns ID values and not true C pointers, but it has two * additional arguments. These are pointers to the "wrapper * functions" which are needed to accommodate foreign language * interfaces. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstChannel *new; /* Pointer to new Channel */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise the Channel, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab, "Channel", source, source_wrap, sink, sink_wrap ); /* 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 Channel'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 Channel. */ return astMakeId( new ); } AstChannel *astLoadChannel_( void *mem, size_t size, AstChannelVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadChannel * Purpose: * Load a Channel. * Type: * Protected function. * Synopsis: * #include "channel.h" * AstChannel *astLoadChannel( void *mem, size_t size, * AstChannelVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * Channel loader. * Description: * This function is provided to load a new Channel 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 * Channel structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Channel at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Channel is to be * loaded. This must be of sufficient size to accommodate the * Channel data (sizeof(Channel)) 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 Channel (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 Channel 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(AstChannel) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Channel. If this is NULL, a pointer * to the (static) virtual function table for the Channel 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 "Channel" is used instead. * Returned Value: * A pointer to the new Channel. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstChannel *new; /* Pointer to the new Channel */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Channel. In this case the Channel belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstChannel ); vtab = &class_vtab; name = "Channel"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitChannelVtab( 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 Channel. */ new = astLoadObject( mem, size, (AstObjectVtab *) 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, "Channel" ); /* Set the pointers to the source and sink functions, and their wrapper functions, to NULL (we cannot restore these since they refer to process-specific addresses). */ new->source = NULL; new->source_wrap = NULL; new->sink = NULL; new->sink_wrap = NULL; /* We do not have any data to pass to the source and sink functions. */ new->data = NULL; /* No warnings yet. */ new->warnings = NULL; new->nwarn = 0; /* Indicate no input or output files have been associated with the Channel. */ new->fd_in = NULL; new->fn_in = NULL; new->fd_out = NULL; new->fn_out = NULL; /* 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. */ /* Indent. */ /* ------- */ new->indent = astReadInt( channel, "indnt", -INT_MAX ); if ( TestIndent( new, status ) ) SetIndent( new, new->indent, status ); /* ReportLevel. */ /* ------------ */ new->report_level = astReadInt( channel, "rplev", -INT_MAX ); if ( TestReportLevel( new, status ) ) SetReportLevel( new, new->report_level, status ); /* Skip. */ /* ----- */ new->skip = astReadInt( channel, "skip", -INT_MAX ); if ( TestSkip( new, status ) ) SetSkip( new, new->skip, status ); /* Strict. */ /* ------- */ new->strict = astReadInt( channel, "strict", -INT_MAX ); if ( TestStrict( new, status ) ) SetStrict( new, new->strict, status ); /* Full. */ /* ----- */ new->full = astReadInt( channel, "full", -INT_MAX ); if ( TestFull( new, status ) ) SetFull( new, new->full, status ); /* Comment. */ /* -------- */ new->comment = astReadInt( channel, "comm", -INT_MAX ); if ( TestComment( new, status ) ) SetComment( new, new->comment, status ); /* If an error occurred, clean up by deleting the new Channel. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Channel pointer. */ return new; } /* 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 astGetNextData_( AstChannel *this, int begin, char **name, char **val, int *status ) { *name = NULL; *val = NULL; if ( !astOK ) return; (**astMEMBER(this,Channel,GetNextData))( this, begin, name, val, status ); } char *astGetNextText_( AstChannel *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Channel,GetNextText))( this, status ); } void astPutNextText_( AstChannel *this, const char *line, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,PutNextText))( this, line, status ); } AstObject *astRead_( AstChannel *this, int *status ) { if ( !astOK ) return NULL; astAddWarning( this, 0, NULL, NULL, status ); return (**astMEMBER(this,Channel,Read))( this, status ); } void astReadClassData_( AstChannel *this, const char *class, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,ReadClassData))( this, class, status ); } double astReadDouble_( AstChannel *this, const char *name, double def, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,Channel,ReadDouble))( this, name, def, status ); } int astReadInt_( AstChannel *this, const char *name, int def, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Channel,ReadInt))( this, name, def, status ); } AstObject *astReadObject_( AstChannel *this, const char *name, AstObject *def, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Channel,ReadObject))( this, name, def, status ); } char *astReadString_( AstChannel *this, const char *name, const char *def, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Channel,ReadString))( this, name, def, status ); } void astWriteBegin_( AstChannel *this, const char *class, const char *comment, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteBegin))( this, class, comment, status ); } void astWriteDouble_( AstChannel *this, const char *name, int set, int helpful, double value, const char *comment, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteDouble))( this, name, set, helpful, value, comment, status ); } void astWriteEnd_( AstChannel *this, const char *class, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteEnd))( this, class, status ); } void astWriteInt_( AstChannel *this, const char *name, int set, int helpful, int value, const char *comment, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteInt))( this, name, set, helpful, value, comment, status ); } void astWriteIsA_( AstChannel *this, const char *class, const char *comment, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteIsA))( this, class, comment, status ); } void astWriteString_( AstChannel *this, const char *name, int set, int helpful, const char *value, const char *comment, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,WriteString))( this, name, set, helpful, value, comment, status ); } void astPutChannelData_( AstChannel *this, void *data, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Channel,PutChannelData))( this, data, status ); } AstKeyMap *astWarnings_( AstChannel *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,Channel,Warnings))( this, status ); } /* Because of the variable argument list, we need to work a bit harder on astAddWarning. Functions that provide implementations of the astAddWarning method recieve the fully expanded message and so do not need a variable argument list. */ void astAddWarning_( void *this_void, int level, const char *fmt, const char *method, int *status, ... ) { AstChannel *this; char buff[ 201 ]; va_list args; int nc; this = astCheckChannel( this_void ); if( fmt ) { if( astOK ) { va_start( args, status ); nc = vsprintf( buff, fmt, args ); va_end( args ); if( nc > 200 ) { astError( AST__INTER, "astAddWarning(%s): Message buffer size " "exceeded (internal AST programming error).", status, astGetClass( this ) ); } else { (**astMEMBER(this,Channel,AddWarning))( this, level, buff, method, status ); } } } else { (**astMEMBER(this,Channel,AddWarning))( this, level, NULL, method, status ); } } /* Count the number of times astWrite is invoked (excluding invocations made from within the astWriteObject method - see below). The count is done here so that invocations of astWrite within a sub-class will be included. */ int astWrite_( AstChannel *this, AstObject *object, int *status ) { astDECLARE_GLOBALS if ( !astOK ) return 0; astGET_GLOBALS(this); nwrite_invoc++; astAddWarning( this, 0, NULL, NULL, status ); return (**astMEMBER(this,Channel,Write))( this, object, status ); } /* We do not want to count invocations of astWrite made from within the astWriteObject method. So decrement the number of invocations first (this assumes that each invocation of astWriteObject will only invoke astWrite once). */ void astWriteObject_( AstChannel *this, const char *name, int set, int helpful, AstObject *value, const char *comment, int *status ) { astDECLARE_GLOBALS if ( !astOK ) return; astGET_GLOBALS(this); nwrite_invoc--; (**astMEMBER(this,Channel,WriteObject))( this, name, set, helpful, value, comment, status ); } ast-8.3.0/fac_1521_err0000664000175000017500000001512613004147334011234 00000000000000FACILITY AST 300,ATGER,attribute getting error 301,ATSER,attribute setting error 302,ATTIN,attribute value invalid 303,AXIIN,axis index invalid 304,BADAT,bad attribute name 305,BADBX,zero-sized box given 306,BADIN,bad input data 307,BADNI,bad number of input coordinates 308,BADNO,bad number of output coordinates 309,BADPW,PolyMap contains illegal power value 310,BADSM,ShiftMap contains no shift information 311,BADWM,WinMap contains no bounds information 312,BDBRK,bad break index 313,BDFMT,bad field specifier 314,BDFTS,invalid FITS keyword value found 315,BDOBJ,inappropriate Object supplied 316,CLPAX,wrong number of clipping axes 317,CORNG,range of coordinates invalid 318,CVBRK,too many breaks in a curve 319,DIMIN,array dimensions invalid 320,DTERR,date/time error 321,ENDIN,invalid use of astEnd 322,EOCHN,end of input Channel encountered 323,EXPIN,attempt to export Object pointer from level zero 324,FCRPT,corrupted FitsChan supplied 325,FMTER,error while formatting coordinate value 326,FRMIN,Frame index invalid 327,FRSIN,FrameSet invalid 328,FTCNV,cannot convert FITS data value type 329,GRFER,low level graphics error 330,INHAN,invalid Handle 331,INNCO,incompatible numbers of coordinates 332,INTER,internal programming error 333,INTRD,incompatible transformation directions 334,KYCIR,circular dependency between KeyMaps 335,LDERR,class loader error 336,LUTII,invalid lookup table increment 337,LUTIN,invalid number of lookup table elements 338,MEMIN,requested memory size invalid 339,MTR23,not a 2d or 3d MatrixMap 340,MTRAX,null rotation axis supplied 341,MTRML,bad matrix shapes for multiplication 342,MTRMT,null matrix supplied 343,NAXIN,number of axes invalid 344,NCHIN,number of characters invalid 345,NCOIN,number of coordinates invalid 346,NCPIN,number of coordinates per point invalid 347,NELIN,number of array elements invalid 348,NOCTS,number of output coordinates too small 349,NODEF,transformation not defined 350,NOFTS,required FITS keywords missing 351,NOMEM,unable to allocate memory 352,NOPTS,number of output points too small 353,NOWRT,attribute is read-only 354,NPTIN,number of points invalid 355,OBJIN,Object invalid 356,OPT,invalid Plot option 357,PDSIN,points data structure invalid 358,PLFMT,no numerical labels can be produced 359,PRMIN,permutation invalid 360,PTRIN,pointer invalid 361,PTRNG,range of points invalid 362,RDERR,read error 363,REGIN,invalid or corrupted Region structure supplied 364,REMIN,invalid attempt to remove last Frame 365,SCSIN,sky coordinate system invalid 366,SELIN,axis selection invalid 367,SLAIN,bad SLALIB transformation type 368,TRNND,coordinate transformation not defined 369,UNMQT,unmatched quotes 370,VSMAL,valid area too small 371,WCSAX,non-existent longitude or latitude axis 372,WCSNC,too few mapping coordinates 373,WCSPA,invalid projection parameters 374,WCSTY,unknown projection type 375,XSOBJ,too many Objects in use at once 376,ZOOMI,zoom factor invalid 377,BADCI,bad coordinate index 378,ILOST,FrameSet integrity lost 379,ITFER,error in IntraMap transformation function 380,ITFNI,IntraMap transformation function name invalid 381,MBBNF,Mapping bounding box not found 382,MRITF,multiple registration of IntraMap transformation function 383,OCLUK,Object class unknown 384,UNFER,error while unformatting a coordinate value 385,URITF,unregistered IntraMap transformation function 386,GBDIN,grid bounds invalid 387,NGDIN,number of grid dimensions invalid 388,PATIN,positional accuracy tolerance invalid 389,SISIN,sub-pixel interpolation scheme invalid 390,SSPIN,scale size in pixels invalid 391,UINER,error in user-supplied sub-pixel interpolation function 392,UK1ER,error in user-supplied 1-d sub-pixel interpolation kernel 393,COMIN,invalid comma in expression 394,CONIN,invalid constant in expression 395,DUVAR,duplicate variable name 396,INNTF,invalid number of transformation functions 397,MIOPA,missing or invalid operand in expression 398,MIOPR,missing or invalid operator in expression 399,MISVN,missing variable name 400,MLPAR,missing left parenthesis in expression 401,MRPAR,missing right parenthesis in expression 402,NORHS,missing right hand side in function 403,UDVOF,undefined variable or function in expression 404,VARIN,variable name invalid 405,WRNFA,wrong number of function arguments in expression 406,BADUN,invalid units specification 407,NORSF,no rest frequency is defined 408,NOSOR,no standard of rest is defined 409,SPCIN,invalid SpecMap 410,XMLNM,invalid XML name or prefix 411,XMLCM,invalid XML comment text 412,XMLPT,invalid XML processing instruction target text 413,XMLIT,invalid XML content item index 414,XMLWF,supplied XML document is not well formed 415,ZERAX,Range of log axis scale includes zero 416,BADOC,Invalid parameters for offset sky coordinate system 417,MPGER,error getting a named value from a KeyMap 418,MPIND,invalid integer index supplied for a KeyMap entry 419,REGCN,region cannot be re-centred 420,NOVAL,attribute has no usable value 421,INCTS,incompatible time scales 422,TIMIN,invalid TimeMap 423,STCKEY,cannot use supplied AstroCoords info 424,STCIND,invalid AstroCoords index 425,CNFLX,cannot conserve flux whilst resampling an array of data 426,TUNAM,Unknown AST tuning parameter name supplied 427,BDPAR,Bad value supplied for a public function parameter 428,3DFSET,Supplied FrameSet does not contain any independent axes 429,PXFRRM,Attempt to delete original Plot3D base Frame 430,BADSUB,Illegal syntax for string substitution template 431,BADFLG,Incompatible flags for re-sampling or re-binning 432,LCKERR,Error locking or unlocking an AST Object 433,FUNDEF,FITS keyword had undefined value 434,MPVIN,invalid integer index supplied for a KeyMap vector element 435,OPRIN,operation specifier invalid 436,NONIN,no inside point found 437,MPKER,requested key not found in KeyMap 438,MPPER,error putting a named value into a KeyMap 439,BADKEY,Attempt made to add an entry to a locked KeyMap 440,BADTYP,Bad data type 441,OLDCOL,Column already exists with different properties 442,BADNULL,Bad null value for a FITS table column 443,BIGKEY,Key string is too long 444,BADCOL,No such column exists in the table 445,BIGTAB,Table is too large 446,BADSIZ,Invalid array size 447,BADTAB,Error reading WCS from FITS binary table 448,NOTAB,Cannot access FITS binary table 449,LEVMAR,Error in levmar Levenberg-Marquardt code 450,NOFIT,Fit failed 451,ISNAN,A transformation generated one or more NaN values 452,WRERR,write error 453,BDVNM,Bad variant Mapping name 454,MIRRO,Attempt to add a variant Mapping to a mirror Frame 455,MNPCK,Error in cminpack Levenberg-Marquardt code 456,EXSPIX,Supplied array has too many pixels 457,NOCNV,No mapping found between coordinate systems 458,IMMUT,Attempt to change an immutable attribute ast-8.3.0/ftable.c0000664000175000017500000002316513004147321010637 00000000000000/* *+ * Name: * ftable.c * Purpose: * Define a FORTRAN 77 interface to the AST Table class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Table class. * Routines Defined: * AST_ISATABLE * AST_TABLE * Copyright: * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S.Berry (Starlink) * History: * 22-NOV-2010 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "table.h" /* C interface to the Table class */ F77_LOGICAL_FUNCTION(ast_isatable)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astWatchSTATUS( astAt( "AST_ISATABLE", NULL, 0 ); RESULT = astIsATable( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_table)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_TABLE", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astTable( "%s", options ) ); astFree( options ); ) return RESULT; } F77_SUBROUTINE(ast_addcolumn)( INTEGER(THIS), CHARACTER(NAME), INTEGER(TYPE), INTEGER(NDIM), INTEGER_ARRAY(DIMS), CHARACTER(UNIT), INTEGER(STATUS) TRAIL(NAME) TRAIL(UNIT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(NAME) GENPTR_INTEGER(TYPE) GENPTR_INTEGER(NDIM) GENPTR_INTEGER_ARRAY(DIMS) GENPTR_CHARACTER(UNIT) char *name, *unit; astAt( "AST_ADDCOLUMN", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); unit = astString( UNIT, UNIT_length ); astAddColumn( astI2P( *THIS ), name, *TYPE, *NDIM, DIMS, unit ); astFree( name ); astFree( unit ); ) } F77_SUBROUTINE(ast_addparameter)( INTEGER(THIS), CHARACTER(NAME), INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(NAME) char *name; astAt( "AST_ADDPARAMETER", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); astAddParameter( astI2P( *THIS ), name ); astFree( name ); ) } F77_SUBROUTINE(ast_removecolumn)( INTEGER(THIS), CHARACTER(NAME), INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(NAME) char *name; astAt( "AST_REMOVECOLUMN", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); astRemoveColumn( astI2P( *THIS ), name ); astFree( name ); ) } F77_SUBROUTINE(ast_removeparameter)( INTEGER(THIS), CHARACTER(NAME), INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(NAME) char *name; astAt( "AST_REMOVEPARAMETER", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); astRemoveParameter( astI2P( *THIS ), name ); astFree( name ); ) } F77_SUBROUTINE(ast_removerow)( INTEGER(THIS), INTEGER(INDEX), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(INDEX) astAt( "AST_REMOVEROW", NULL, 0 ); astWatchSTATUS( astRemoveRow( astI2P( *THIS ), *INDEX ); ) } F77_SUBROUTINE(ast_purgerows)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_PURGEROWS", NULL, 0 ); astWatchSTATUS( astPurgeRows( astI2P( *THIS ) ); ) } /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file keymap.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_columnname_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_columnname)( CHARACTER_RETURN_VALUE(RESULT), #endif INTEGER(THIS), INTEGER(INDEX), #if NO_CHAR_FUNCTION INTEGER(STATUS) TRAIL(RESULT) ) { #else INTEGER(STATUS) ) { #endif GENPTR_CHARACTER(RESULT) GENPTR_INTEGER(THIS) GENPTR_INTEGER(INDEX) const char *result; int i; astAt( "AST_COLUMNNAME", NULL, 0 ); astWatchSTATUS( result = astColumnName( astI2P( *THIS ), *INDEX ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ ) } /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file keymap.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_parametername_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_parametername)( CHARACTER_RETURN_VALUE(RESULT), #endif INTEGER(THIS), INTEGER(INDEX), #if NO_CHAR_FUNCTION INTEGER(STATUS) TRAIL(RESULT) ) { #else INTEGER(STATUS) ) { #endif GENPTR_CHARACTER(RESULT) GENPTR_INTEGER(THIS) GENPTR_INTEGER(INDEX) const char *result; int i; astAt( "AST_PARAMETERNAME", NULL, 0 ); astWatchSTATUS( result = astParameterName( astI2P( *THIS ), *INDEX ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ ) } F77_SUBROUTINE(ast_columnshape)( INTEGER(THIS), CHARACTER(COLUMN), INTEGER(MXDIM), INTEGER(NDIM), INTEGER_ARRAY(DIMS), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) GENPTR_INTEGER(MXDIM) GENPTR_INTEGER(NDIM) GENPTR_INTEGER_ARRAY(DIMS) char *column; astAt( "AST_COLUMNSHAPE", NULL, 0 ); astWatchSTATUS( column = astString( COLUMN, COLUMN_length ); astColumnShape( astI2P( *THIS ), column, *MXDIM, NDIM, DIMS ); astFree( column ); ) } F77_LOGICAL_FUNCTION(ast_hascolumn)( INTEGER(THIS), CHARACTER(COLUMN), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) F77_LOGICAL_TYPE(RESULT); char *column; astWatchSTATUS( astAt( "AST_HASCOLUMN", NULL, 0 ); column = astString( COLUMN, COLUMN_length ); RESULT = astHasColumn( astI2P( *THIS ), column ) ? F77_TRUE : F77_FALSE; astFree( column ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_hasparameter)( INTEGER(THIS), CHARACTER(PARAM), INTEGER(STATUS) TRAIL(PARAM) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(PARAM) F77_LOGICAL_TYPE(RESULT); char *param; astWatchSTATUS( astAt( "AST_HASPARAMETER", NULL, 0 ); param = astString( PARAM, PARAM_length ); RESULT = astHasParameter( astI2P( *THIS ), param ) ? F77_TRUE : F77_FALSE; astFree( param ); ) return RESULT; } ast-8.3.0/intramap.h0000664000175000017500000002743613004147321011227 00000000000000#if !defined( INTRAMAP_INCLUDED ) /* Include this file only once */ #define INTRAMAP_INCLUDED /* *+ * Name: * intramap.h * Type: * C include file. * Purpose: * Define the interface to the IntraMap class. * Invocation: * #include "intramap.h" * Description: * This include file defines the interface to the IntraMap class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * * The IntraMap class implements Mappings which transform * coordinates using a privately-defined transformation function * (e.g. written in C). * Inheritance: * The IntraMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * IntraFlag * IntraMap identification string. * Methods Over-Ridden: * Public: * None. * * Protected: * astMapMerge * Simplify a sequence of Mappings containing an IntraMap. * astTransform * Transform a set of points using an IntraMap. * New Methods Defined: * Public: * None. * * Protected: * astClearIntraFlag * Clear the IntraFlag attribute for an IntraMap. * astGetIntraFlag * Get the value of the IntraFlag attribute for an IntraMap. * astSetIntraFlag * Set the value of the IntraFlag attribute for an IntraMap. * astTestIntraFlag * Test whether a value has been set for the IntraFlag attribute of * an IntraMap. * Other Class Functions: * Public: * astIntraMap * Create an IntraMap. * astIntraReg * Register a transformation function for use by an IntraMap. * astIsAIntraMap * Test class membership. * * Protected: * astCheckIntraMap * Validate class membership. * astInitIntraMap * Initialise an IntraMap. * astLoadIntraMap * Load an IntraMap. * Macros: * None. * Type Definitions: * Public: * AstIntraMap * IntraMap object type. * * Protected: * AstIntraMapVtab * IntraMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 24-MAR-1998 (RFWS): * Original version. * 16-SEP-1999 (RFWS): * Added the IntraFlag attribute and added a Mapping pointer as a new * first argument to transformation functions. * 8-JAN-2003 (DSB): * Added protected astInitIntraMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macro Definitions. */ /* ================== */ #define AST__NOFWD (1U) /* No forward transformation defined */ #define AST__NOINV (2U) /* No inverse transformation defined */ #define AST__SIMPFI (4U) /* Forward-inverse may be simplified */ #define AST__SIMPIF (8U) /* Inverse-forward may be simplified */ #define AST__ANY (-66) /* Allow any number of input/output coords */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* IntraMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstIntraMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ char *intraflag; /* Pointer to identification string */ int ifun; /* Transformation function index */ } AstIntraMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstIntraMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ const char *(* GetIntraFlag)( AstIntraMap *, int * ); int (* TestIntraFlag)( AstIntraMap *, int * ); void (* ClearIntraFlag)( AstIntraMap *, int * ); void (* SetIntraFlag)( AstIntraMap *, const char *, int * ); } AstIntraMapVtab; /* Structure to hold data for transformation functions. */ typedef struct AstIntraMapTranData { void (* tran)( AstMapping *, int, int, const double *[], int, int, double *[] ); /* Pointer to transformation function */ void (* tran_wrap)( void (*)( AstMapping *, int, int, const double *[], int, int, double *[] ), AstMapping *, int, int, const double *[], int, int, double *[], int * ); /* Pointer to wrapper function */ char *author; /* Author's name */ char *contact; /* Contact details (e.g. e-mail address) */ char *name; /* Function name (assigned by caller) */ char *purpose; /* Comment string describing purpose */ int nin; /* Number of input coordinates per point */ int nout; /* Number of output coordinates per point */ unsigned int flags; /* Flags to describe function behaviour */ } AstIntraMapTranData; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstIntraMapGlobals { AstIntraMapVtab Class_Vtab; int Class_Init; } AstIntraMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(IntraMap) /* Check class membership */ astPROTO_ISA(IntraMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstIntraMap *astIntraMap_( const char *, int, int, const char *, int *, ...); #else AstIntraMap *astIntraMapId_( const char *, int, int, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstIntraMap *astInitIntraMap_( void *, size_t, int, AstIntraMapVtab *, const char *, const char *, int, int, int * ); /* Vtab initialiser. */ void astInitIntraMapVtab_( AstIntraMapVtab *, const char *, int * ); /* Loader. */ AstIntraMap *astLoadIntraMap_( void *, size_t, AstIntraMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitIntraMapGlobals_( AstIntraMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ void astIntraReg_( const char *, int, int, void (*)( AstMapping *, int, int, const double *[], int, int, double *[] ), unsigned int, const char *, const char *, const char *, int * ); #if defined(astCLASS) /* Protected */ const char *astGetIntraFlag_( AstIntraMap *, int * ); int astTestIntraFlag_( AstIntraMap *, int * ); void astClearIntraFlag_( AstIntraMap *, int * ); void astSetIntraFlag_( AstIntraMap *, const char *, int * ); #else /* Public only */ void astIntraRegFor_( const char *, int, int, void (*)( AstMapping *, int, int, const double *[], int, int, double *[] ), void (*)( void (*)( AstMapping *, int, int, const double *[], int, int, double *[]), AstMapping *, int, int, const double *[], int, int, double *[], int * ), unsigned int, const char *, const char *, const char *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckIntraMap(this) astINVOKE_CHECK(IntraMap,this,0) #define astVerifyIntraMap(this) astINVOKE_CHECK(IntraMap,this,1) /* Test class membership. */ #define astIsAIntraMap(this) astINVOKE_ISA(IntraMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astIntraMap astINVOKE(F,astIntraMap_) #else #define astIntraMap astINVOKE(F,astIntraMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitIntraMap(mem,size,init,vtab,name,fname,nin,nout) \ astINVOKE(O,astInitIntraMap_(mem,size,init,vtab,name,fname,nin,nout,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitIntraMapVtab(vtab,name) astINVOKE(V,astInitIntraMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadIntraMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadIntraMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckIntraMap to validate IntraMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astIntraReg(name,nin,nout,tran,flags,purpose,author,contact) \ astIntraReg_(name,nin,nout,tran,flags,purpose,author,contact,STATUS_PTR) #if defined(astCLASS) /* Protected */ #define astClearIntraFlag(this) \ astINVOKE(V,astClearIntraFlag_(astCheckIntraMap(this),STATUS_PTR)) #define astGetIntraFlag(this) \ astINVOKE(V,astGetIntraFlag_(astCheckIntraMap(this),STATUS_PTR)) #define astSetIntraFlag(this,value) \ astINVOKE(V,astSetIntraFlag_(astCheckIntraMap(this),value,STATUS_PTR)) #define astTestIntraFlag(this) \ astINVOKE(V,astTestIntraFlag_(astCheckIntraMap(this),STATUS_PTR)) #else /* Public only */ #define astIntraRegFor(name,nin,nout,tran,tran_wrap,flags,purpose,author,contact) \ astIntraRegFor_(name,nin,nout,tran,tran_wrap,flags,purpose,author,contact,STATUS_PTR) #endif #endif ast-8.3.0/xmlchan.c0000664000175000017500000170325413004147321011041 00000000000000/* *class++ * Name: * XmlChan * Purpose: * I/O Channel using XML to represent Objects. * Constructor Function: c astXmlChan f AST_XMLCHAN * Description: * A XmlChan is a specialised form of Channel which supports XML I/O * operations. Writing an Object to an XmlChan (using c astWrite) will, if the Object is suitable, generate an f AST_WRITE) will, if the Object is suitable, generate an * XML description of that Object, and reading from an XmlChan will * create a new Object from its XML description. * * Normally, when you use an XmlChan, you should provide "source" c and "sink" functions which connect it to an external data store c by reading and writing the resulting XML text. These functions f and "sink" routines which connect it to an external data store f by reading and writing the resulting XML text. These routines * should perform any conversions needed between external character c encodings and the internal ASCII encoding. If no such functions f encodings and the internal ASCII encoding. If no such routines * are supplied, a Channel will read from standard input and write * to standard output. * * Alternatively, an XmlChan can be told to read or write from * specific text files using the SinkFile and SourceFile attributes, * in which case no sink or source function need be supplied. * Inheritance: * The XmlChan class inherits from the Channel class. * Attributes: * In addition to those attributes common to all Channels, every * XmlChan also has the following attributes: * * - XmlFormat: System for formatting Objects as XML * - XmlLength: Controls output buffer length * - XmlPrefix: The namespace prefix to use when writing * Functions: c The XmlChan class does not define any new functions beyond those f The XmlChan class does not define any new routines beyond those * which are applicable to all Mappings. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David Berry (Starlink) * History: * 10-OCT-2003 (DSB): * Original version. * 6-FEB-2004 (DSB): * Added XmlPrefix and XmlFormat attributes. * 10-FEB-2004 (DSB): * - Added debug conditional code to keep track of memory leaks. * - Fixed bug which prevented more than 1 object being read from * an XmlChan. * 7-DEC-2005 (DSB): * Free memory allocated by calls to astReadString. * 12-FEB-2010 (DSB): * Represent AST__BAD externally using the string "". *class-- * Further STC work: * - Speed up general STC processing (a lot of time seems to be spent * simplifying things) * - Document (including a complete description of what is and is not * supported in the reference docs for the XmlFormat attribute). * - Produce a schema describing the format which can in fact be read by * AST. * - Look at Jonathan McDowell's mini-STC schema (also STC stuff in * spectral data model) * - Web services. Read only: test STCs for overlap, test points for * inclusion/exclusion, plot a mask over an image, verification (can AST * read it & does it generate warnings?). Read/Write: convert FITS to STC, * transform STC into a new coord system. * - Add support for writing as well as reading * - Modify Stc... constructors to check that the supplied Frame is suitable. * - What about multiple AstroCoordFrames and AstroCoordAreas in a STC? * - Add support for generic CoordFrames * - What should be done with pixel coords info within STC? * - Extend coverage (e.g. to 3D space frames, etc) */ /* 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 XmlChan /* The XML element name used to store an AST attribute setting */ #define ATTR "_attribute" /* The XML element name used for an AST "isa" element */ #define ISA "_isa" /* The XML attribute name which holds the name of the AST class which defines the item contained in the element. */ #define DEFINEDBY "definedby" /* The XML attribute name which holds the name of the AST attribute */ #define NAME "name" /* The XML attribute name which holds the value of the AST attribute */ #define VALUE "value" /* The XML attribute name which indicates if the AST attribute value is a default value. */ #define DEFAULT "default" /* The XML attribute name which indicates if the AST attribute value was originally a string value. */ #define QUOTED "quoted" /* The XML attribute name which holds a description of the AST attribute. */ #define DESC "desc" /* The XML attribute name which holds the label associated with an AST Object (if any). */ #define LABEL "label" /* A string used to indicate atrue attribute value */ #define TRUE "true" /* Format identifiers and strings */ #define UNKNOWN_FORMAT -1 #define NATIVE_FORMAT 0 #define QUOTED_FORMAT 1 #define IVOA_FORMAT 2 #define MAX_FORMAT 2 #define UNKNOWN_STRING "UNKNOWN" #define NATIVE_STRING "NATIVE" #define QUOTED_STRING "QUOTED" #define IVOA_STRING "IVOA" /* Values representing message severities. */ #define WARNING 0 #define FAILURE 1 #define RESET 2 /* Known IVOA namespaces. When a new name is added, update the FindIVOAClass function. */ #define STC_URI "urn:nvo-stc" /* Known IVOA Classes and attributes. When a new name is added, it may be necessary to update the FindIVOAClass function. */ #define STC_RESOURCE_PROFILE "STCResourceProfile" #define SEARCH_LOCATION "SearchLocation" #define OBSERVATION_LOCATION "ObservationLocation" #define OBSERVATORY_LOCATION "ObservatoryLocation" #define CATALOG_ENTRY_LOCATION "CatalogEntryLocation" #define OBS_DATA_LOCATION "ObsDataLocation" #define ASTRO_COORD_SYSTEM "AstroCoordSystem" #define ASTRO_COORD_AREA "AstroCoordArea" #define ASTRO_COORDS "AstroCoords" #define TIME_FRAME "TimeFrame" #define SPACE_FRAME "SpaceFrame" #define SPECTRAL_FRAME "SpectralFrame" #define REDSHIFT_FRAME "RedshiftFrame" #define DOPPLER_DEFINITION "DopplerDefinition" /* Returns string "an" or "a" depending on whether the first character of the supplied string is a vowel or not. */ #define ANA(t) (t?(strchr("AaEeIiOoUu",t[0])?"an":"a"):"") /* String used to represent AST__BAD externally. */ #define BAD_STRING "" /* Include 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 "frame.h" /* Coordinate Frames */ #include "timeframe.h" /* Time coordinate Frames */ #include "cmpframe.h" /* Coordinate Frames */ #include "skyframe.h" /* Celestial coordinate Frames */ #include "specframe.h" /* Spectral coordinate Frames */ #include "region.h" /* Regions within coordinate Frames */ #include "ellipse.h" /* Ellipses within coordinate Frames */ #include "pointlist.h" /* Points within coordinate Frames */ #include "polygon.h" /* Polygons within coordinate Frames */ #include "circle.h" /* Circles within coordinate Frames */ #include "keymap.h" /* Mapping of keys to values */ #include "channel.h" /* Interface for parent class */ #include "xmlchan.h" /* Interface definition for this class */ #include "loader.h" /* Interface to the global loader */ #include "object.h" /* Base Object class */ #include "wcsmap.h" /* Angular conversion constants */ #include "xml.h" /* AST XML facilities */ #include "erfa.h" /* ERFA functions */ #include "stcresourceprofile.h" /* IVOA StcResourceProfile class */ #include "stcsearchlocation.h" /* IVOA SearchLocation class */ #include "stccatalogentrylocation.h"/* IVOA CatalogEntryLocation class */ #include "stcobsdatalocation.h" /* IVOA ObsDataLocation class */ #include "nullregion.h" /* Null regions */ #include "interval.h" /* Axis intervals */ #include "box.h" /* Box regions */ #include "cmpregion.h" /* Compound regions */ #include "prism.h" /* Prism regions */ #include "unitmap.h" /* Unit Mappings */ #include "unit.h" /* Unit handling utilities */ #include "pal.h" /* slalib functions */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* Type Definitions */ /* ================ */ /* A type for functions which read an IVOA element and return a corresponding AST Object. */ typedef AstObject *(*IVOAReader)( AstXmlChan *, AstXmlElement *, int * ); /* A structure to hold the result of scanning the content of an IVOA element.*/ typedef struct IVOAScan { int n; /* Number of element names described by this structure */ int *count; /* Array holding number of each element name found */ AstXmlElement ***el; /* Array holding pointers to each element found */ } IVOAScan; /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static int (* parent_getfull)( AstChannel *, int * ); static int (* parent_getcomment)( AstChannel *, int * ); static int (* parent_getindent)( AstChannel *, int * ); /* Text values used to represent XmlFormat values externally. These should be in the order defined by the associated constants above. */ static const char *xformat[3] = { NATIVE_STRING, QUOTED_STRING, IVOA_STRING }; /* 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->IsUsable_This = NULL; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->GetNextChar_C = NULL; \ globals->GetNextChar_Buf = NULL; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(XmlChan) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(XmlChan,Class_Init) #define class_vtab astGLOBAL(XmlChan,Class_Vtab) #define isusable_this astGLOBAL(XmlChan,IsUsable_This) #define getattrib_buff astGLOBAL(XmlChan,GetAttrib_Buff) #define getnextchar_c astGLOBAL(XmlChan,GetNextChar_C) #define getnextchar_buf astGLOBAL(XmlChan,GetNextChar_Buf) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* An XmlChan pointer use to communicate with the IsUsable function. */ static AstXmlChan *isusable_this = NULL; /* Buffer returned by GetAttrib. */ static char getattrib_buff[ 51 ]; /* Variables used in GetNextChar */ static char *getnextchar_c = NULL; /* Pointer to next character to read */ static char *getnextchar_buf = NULL; /* Pointer to previously read text */ /* Define the class virtual function table and its initialisation flag as static variables. */ static AstXmlChanVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstXmlChan *astXmlChanForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); AstXmlChan *astXmlChanId_( const char *(* source)( void ), void (* sink)( const char * ), const char *options, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstObject *AstroCoordSystemReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *MakeAstFromXml( AstXmlChan *, AstXmlElement *, int * ); static AstObject *ObsDataLocationReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *Read( AstChannel *, int * ); static AstObject *ReadObject( AstChannel *, const char *, AstObject *, int * ); static AstObject *RedshiftFrameReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *SpaceFrameReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *SpectralFrameReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *StcMetadataReader( AstXmlChan *, AstXmlElement *, int * ); static AstObject *TimeFrameReader( AstXmlChan *, AstXmlElement *, int * ); static AstPointList *ObservatoryLocationReader( AstXmlChan *, AstXmlElement *, AstStcObsDataLocation *, int * ); static AstRegion *AllSkyReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *AstroCoordAreaReader( AstXmlChan *, AstXmlElement *, AstFrame *, AstRegion *[4], int, AstKeyMap **, int * ); static AstRegion *BoxReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *CircleReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *ConstraintReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *ConvexReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *Coord2VecIntervalReader( AstXmlChan *, AstXmlElement *, const char *, AstFrame *, int * ); static AstRegion *Coord3VecIntervalReader( AstXmlChan *, AstXmlElement *, const char *, AstFrame *, int * ); static AstRegion *CoordScalarIntervalReader( AstXmlChan *, AstXmlElement *, const char *, AstFrame *, int * ); static AstRegion *EllipseReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *IntersectionReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *NegationReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *PolygonReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *Position2DReader( AstXmlChan *, AstXmlElement *, AstFrame *, double *, AstKeyMap **, int * ); static AstRegion *PositionIntervalReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *RedshiftIntervalReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *RedshiftReader( AstXmlChan *, AstXmlElement *, AstFrame *, AstKeyMap **, int * ); static AstRegion *StcRegionReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *RegionReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *SpectralIntervalReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *SpectralReader( AstXmlChan *, AstXmlElement *, AstFrame *, double *, AstKeyMap **, int * ); static AstRegion *SphereReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstRegion *TimeIntervalReader( AstXmlChan *, AstXmlElement *, AstTimeFrame *, int * ); static AstRegion *TimeReader( AstXmlChan *, AstXmlElement *, AstTimeFrame *, double *, AstKeyMap **, int * ); static AstRegion *UnionReader( AstXmlChan *, AstXmlElement *, AstFrame *, int * ); static AstSystemType RedshiftSys( AstXmlChan *, AstXmlElement *, char **, int, int * ); static AstSystemType SpecSys( AstXmlChan *, AstXmlElement *, const char *, int, int * ); static AstXmlElement *FindAttribute( AstXmlChan *, const char *, int * ); static AstXmlElement *FindElement( AstXmlChan *, AstXmlElement *, const char *, int * ); static AstXmlElement *FindObject( AstXmlChan *, const char *, int * ); static AstXmlElement *MakePos2D( AstXmlChan *, AstXmlElement *, int * ); static AstXmlElement *ReadXmlText( AstXmlChan *, int * ); static AstXmlElement *Remove( AstXmlChan *, AstXmlElement *, int * ); static IVOAReader FindIVOAClass( AstXmlElement *, int *, int * ); static IVOAScan *FreeIVOAScan( IVOAScan *, int * ); static IVOAScan *ScanIVOAElement( AstXmlChan *, AstXmlElement *, int, const char *[], int[], int[], int * ); static char *ReadString( AstChannel *, const char *, const char *, int * ); static char *SourceWrap( const char *(*)( void ), int * ); static char GetNextChar( void *, int * ); static const char *FindNextIsA( AstXmlElement *, int, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetTag( AstXmlObject *, int, int * ); static double AstronTimeReader( AstXmlChan *, AstXmlElement *, AstTimeFrame *, int * ); static double AttrValueD( AstXmlChan *, AstXmlElement *, const char *, double, int * ); static double ElemValueD( AstXmlChan *, AstXmlElement *, double, int * ); static double Error2PAReader( AstXmlChan *, AstXmlElement *, double *, int * ); static double MakeMJD( AstTimeFrame *, double, int * ); static double PosAngleReader( AstXmlChan *, AstXmlElement *, int * ); static double ReadDouble( AstChannel *, const char *, double, int * ); static int AstroCoordsReader( AstXmlChan *, AstXmlElement *, AstFrame *, AstRegion *[4], AstKeyMap **, int * ); static int AttrValueB( AstXmlChan *, AstXmlElement *, const char *, int, int * ); static int AttrValueI( AstXmlChan *, AstXmlElement *, const char *, int, int * ); static int ElemListD( AstXmlChan *, AstXmlElement *, int, double *, int * ); static int FindString( int, const char *[], const char *, const char *, const char *, const char *, int * ); static int GetComment( AstChannel *, int * ); static int GetFull( AstChannel *, int * ); static int GetIndent( AstChannel *, int * ); static int IsUsable( AstXmlElement *, int * ); static int ReadInt( AstChannel *, const char *, int, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int Use( AstXmlChan *, int, int, int * ); static int Ustrcmp( const char *, const char *, int * ); static int Ustrncmp( const char *, const char *, size_t, int * ); static int VertexReader( AstXmlChan *, AstXmlElement *, double *, double *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void FillAndLims( AstXmlChan *, AstXmlElement *, AstRegion *, int * ); static void OutputText( AstXmlChan *, const char *, int, int * ); static void ReCentreAnc( AstRegion *, int, AstKeyMap **, int * ); static void ReadClassData( AstChannel *, const char *, int * ); static void Report( AstXmlChan *, AstXmlElement *, int, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SinkWrap( void (*)( const char * ), const char *, int * ); static void WriteBegin( AstChannel *, const char *, const char *, int * ); static void WriteDouble( AstChannel *, const char *, int, int, double, const char *, int * ); static void WriteEnd( AstChannel *, const char *, int * ); static void WriteInt( AstChannel *, const char *, int, int, int, const char *, int * ); static void WriteIsA( AstChannel *, const char *, const char *, int * ); static void WriteObject( AstChannel *, const char *, int, int, AstObject *, const char *, int * ); static void WriteString( AstChannel *, const char *, int, int, const char *, const char *, int * ); static AstTimeScaleType TimeScaleReader( AstXmlChan *, AstXmlElement *, int * ); static int TestXmlLength( AstXmlChan *, int * ); static void ClearXmlLength( AstXmlChan *, int * ); static void SetXmlLength( AstXmlChan *, int, int * ); static int GetXmlLength( AstXmlChan *, int * ); static int TestXmlFormat( AstXmlChan *, int * ); static void ClearXmlFormat( AstXmlChan *, int * ); static void SetXmlFormat( AstXmlChan *, int, int * ); static int GetXmlFormat( AstXmlChan *, int * ); static int TestXmlPrefix( AstXmlChan *, int * ); static void ClearXmlPrefix( AstXmlChan *, int * ); static void SetXmlPrefix( AstXmlChan *, const char *, int * ); static const char * GetXmlPrefix( AstXmlChan *, int * ); /* Member functions. */ /* ================= */ static AstRegion *AllSkyReader( AstXmlChan *this, AstXmlElement *elem, AstFrame *frm, int *status ){ /* * Name: * AllSkyReader * Purpose: * Make an AST Region from an IVOA AllSky element. * Type: * Private function. * Synopsis: * #include "xmlchan.h" * AstRegion *AllSkyReader( AstXmlChan *this, AstXmlElement *elem, * AstFrame *frm, int *status ) * Class Membership: * XmlChan member function. * Description: * This function makes a new AST Region from the supplied IVOA * AllSky element. * Parameters: * this * Pointer to the XmlChan. * elem * Pointer to the IVOA AllSky element. * frm * Pointer to the 2D Frame in which the returned Region should be * defined. If the Unit attribute is not set, this function will * set it to the value supplied in "unit" before returning. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new Region. */ /* Local Variables: */ AstRegion *new; /* Pointer to returned Region */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Create a negated NullRegion (this is a boundless Region which includes all points in the Frame). */ new = (AstRegion *) astNullRegion( frm, NULL, "negated=1", status ); /* Get any fill factor from the element and assign to the returned Region. */ FillAndLims( this, elem, new, status ); /* Annul any returned Frame if an error has occurred. */ if( !astOK ) new = astAnnul( new ); /* Return the pointer to the new Region. */ return new; } static AstRegion *AstroCoordAreaReader( AstXmlChan *this, AstXmlElement *elem, AstFrame *frm, AstRegion *uncs[4], int nanc, AstKeyMap **ancs, int *status ) { /* * Name: * AstroCoordAreaReader * Purpose: * Make an AST Region from an IVOA AstroCoordArea element. * Type: * Private function. * Synopsis: * #include "xmlchan.h" * AstRegion *AstroCoordAreaReader( AstXmlChan *this, AstXmlElement *elem, * AstFrame *frm, AstRegion *uncs[4], * int nanc, AstKeyMap **ancs, int *status ) * Class Membership: * XmlChan member function. * Description: * This function makes a new AST Region from the supplied IVOA * AstroCoordArea element. * Parameters: * this * Pointer to the XmlChan. * elem * Pointer to the IVOA AstroCoordArea element. May be NULL, in * which case a NullRegion is returned. * frm * The Frame in which the returned Region is to be defined. If * Units or reference values (Epoch, RestFreq, RefRA, etc) are not set * for any axes, then they will be set by this function if possible. * uncs * Array holding pointers to the uncertainty Regions to be associated * with each of the four STC domains (space, time, spectral, redshift). * NULL should be suppied in any element for which no uncertainty is * available. * nanc * Number of KeyMap pointers stored in "ancs" * ancs * Pointer to an array of "nanc" elements, each being a pointer to * a KeyMap. Each one describes the ancilary information in an * AstroCoords element associated with the AstroCoordsArea decribed * by "region". Each KeyMap has elements with keys AST__STCERROR, * AST__STCRES, AST__STCSIZE, AST__STCPIXSZ, AST__STCVALUE each of * which holds a pointer to a Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new Region. */ /* Local Variables: */ AstRegion *r; AstFrame *cfrm; AstFrame *fr; AstFrame *pfrm; AstFrame *red_frame; AstFrame *space_frame; AstFrame *spec_frame; AstFrameSet *fs; AstMapping *map; AstObject *o; AstRegion **red_list; AstRegion **spec_list; AstRegion **space_list; AstRegion **time_list; AstRegion *new; AstRegion *reg; AstRegion *rred; AstRegion *rspec; AstRegion *rspace; AstRegion *rtime; AstRegion *sum; AstRegion *tmp; AstTimeFrame *time_frame; IVOAScan *scan; char *decset; char *raset; char buff[ DBL_DIG + 30 ]; char setting[ 100 ]; const char *dom; const char *id; const char *names[4]; const char *name; const char *old_units; const char *text; double decref; double lbnd[2]; double raref; double space_val[2]; double spec_val; double time_val; double ubnd[2]; int i; int ianc; int ired; int ispace; int ispec; int itime; int k; int l; int max[4]; int min[4]; int nax; int nred; int nspace; int nspec; int ntime; int paxis; static const char *key[ 5 ] = { AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ, AST__STCVALUE }; /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If null AstroCoordArea element has been supplied, return a NullRegion. */ if( !elem ) { new = (AstRegion *) astNullRegion( frm, NULL, "", status ); /* Otherwise, create a Region of suitable class. */ } else { /* First identify the individual Frames within the supplied Frame. Current implementation for spatial axes is limited to celestial longitude and latitude. */ space_frame = NULL; spec_frame = NULL; red_frame = NULL; time_frame = NULL; nax = astGetNaxes( frm ); for( i = 0; i < nax; i++ ) { astPrimaryFrame( frm, i, &pfrm, &paxis ); dom = astGetDomain( pfrm ); if( !strcmp( dom, "SKY" ) ) { if( !space_frame ) { space_frame = astClone( pfrm ); } else if( pfrm != space_frame) { Report( this, elem, FAILURE, "contains more than 2 spatial axes", status ); } } else if( !strcmp( dom, "TIME" ) ) { if( !time_frame ) { if( astIsATimeFrame( pfrm ) ) { time_frame = (AstTimeFrame *) astClone( pfrm ); } else if( astOK ) { astError( AST__INTER, "AstroCoordAreaReader(XmlChan): %s " "supplied where TimeFrame expected (internal " "AST programming error).", status, astGetClass( pfrm ) ); } } else { Report( this, elem, FAILURE, "contains more than 1 time axis", status ); } } else if( !strcmp( dom, "SPECTRUM" ) ) { if( !spec_frame ) { spec_frame = astClone( pfrm ); } else { Report( this, elem, FAILURE, "contains more than 1 spectral axis", status ); } } else if( !strcmp( dom, "REDSHIFT" ) ) { if( !red_frame ) { red_frame = astClone( pfrm ); } else { Report( this, elem, FAILURE, "contains more than 1 redshift axis", status ); } } else { Report( this, elem, FAILURE, "contains axes for an unsupported domain", status ); } pfrm = astAnnul( pfrm ); } /* Search the supplied element for the required sub-elements. */ names[ 0 ] = "Sphere|PositionInterval|Region"; names[ 1 ] = "TimeInterval"; names[ 2 ] = "SpectralInterval"; names[ 3 ] = "RedshiftInterval"; min[ 0 ] = 0; min[ 1 ] = 0; min[ 2 ] = 0; min[ 3 ] = 0; max[ 0 ] = INT_MAX; max[ 1 ] = INT_MAX; max[ 2 ] = INT_MAX; max[ 3 ] = INT_MAX; scan = ScanIVOAElement( this, elem, 4, names, min, max, status ); /* If succesfull.. */ if( scan ) { /* Create Regions for all the SpatialIntervals found in the supplied element. */ space_val[ 0 ] = AST__BAD; space_val[ 1 ] = AST__BAD; nspace = scan->count[ 0 ]; space_list = astMalloc( sizeof(AstRegion *)*(size_t)nspace ); if( space_list ) { for( ispace = 0; ispace < nspace; ispace++ ) { name = astXmlGetName( scan->el[ 0 ][ ispace ] ); if( !strcmp( name, "Sphere" ) ) { space_list[ ispace ] = SphereReader( this, scan->el[ 0 ][ ispace ], space_frame, status ); } else if( !strcmp( name, "PositionInterval" ) ) { space_list[ ispace ] = PositionIntervalReader( this, scan->el[ 0 ][ ispace ], space_frame, status ); } else if( !strcmp( name, "Region" ) ) { space_list[ ispace ] = StcRegionReader( this, scan->el[ 0 ][ ispace ], space_frame, status ); } else if( astOK ) { astError( AST__INTER, "AstroCoordAreaReader(XmlChan): " "SpatialInterval type %s not yet supported " "(AST internal programming error).", status, name ); break; } /* Store any uncertainty region.*/ if( uncs[ 0 ] ) astSetUnc( space_list[ ispace ], uncs[ 0 ] ); } /* If the spatial region is a single point we will use the point as the reference position for any SpecFrames which are created. If there is just one spatial interval, and if it is bounded. and if the bounds are equal on both axes, note the mean position. */ if( nspace == 1 ){ if( astGetBounded( space_list[ 0 ] ) ) { astGetRegionBounds( space_list[ 0 ], lbnd, ubnd ); if( astEQUAL( lbnd[ 0 ], ubnd[ 0 ] ) && astEQUAL( lbnd[ 1 ], ubnd[ 1 ] ) ) { space_val[ 0 ] = 0.5*( lbnd[ 0 ] + ubnd[ 0 ] ); space_val[ 1 ] = 0.5*( lbnd[ 1 ] + ubnd[ 1 ] ); } } } } /* Create Regions for all the TimeIntervals found in the supplied element. */ time_val = AST__BAD; ntime = scan->count[ 1 ]; time_list = astMalloc( sizeof(AstRegion *)*(size_t)ntime ); if( time_list ) { for( itime = 0; itime < ntime; itime++ ) { time_list[ itime ] = TimeIntervalReader( this, scan->el[ 1 ][ itime ], time_frame, status ); /* Store any uncertainty region. Transfer the System and TimeOrigin values from the time region to the time uncertainty, if set. */ if( uncs[ 1 ] ) { if( astTestSystem( time_frame ) && astTestTimeOrigin( time_frame ) ) { sprintf( setting, "System=%s", astGetC( time_frame, "System" ) ); astRegSetAttrib( uncs[ 1 ], setting, NULL ); if( astTestUnit( time_frame, 0 ) ) { old_units = astGetUnit( time_frame, 0 ); old_units = astStore( NULL, old_units, strlen( old_units ) + 1 ); } else { old_units = NULL; } astSetUnit( time_frame, 0, astGetUnit( uncs[ 1 ], 0 ) ); sprintf( setting, "TimeOrigin=%s", astGetC( time_frame, "TimeOrigin" ) ); astRegSetAttrib( uncs[ 1 ], setting, NULL ); if( old_units ) { astSetUnit( time_frame, 0, old_units ); old_units = astFree( (void *) old_units ); } else { astClearUnit( time_frame, 0 ); } } astSetUnc( time_list[ itime ], uncs[ 1 ] ); } } /* Use the mid point as the Epoch for all Frames which are created. If either limit is not specified, use the specified limit. */ if( ntime > 0 ){ astGetRegionBounds( time_list[ 0 ], lbnd, ubnd ); if( fabs( lbnd[ 0 ] ) != DBL_MAX && lbnd[ 0 ] != AST__BAD ){ if( fabs( ubnd[ 0 ] ) != DBL_MAX && ubnd[ 0 ] != AST__BAD ){ time_val = 0.5*( lbnd[ 0 ] + ubnd[ 0 ] ); } else { time_val = lbnd[ 0 ]; } } else if( fabs( ubnd[ 0 ] ) != DBL_MAX && ubnd[ 0 ] != AST__BAD ){ time_val = ubnd[ 0 ]; } } } /* Create Regions for all the SpectralIntervals found in the supplied element. */ spec_val = AST__BAD; nspec = scan->count[ 2 ]; spec_list = astMalloc( sizeof(AstRegion *)*(size_t)nspec ); if( spec_list ) { for( ispec = 0; ispec < nspec; ispec++ ) { spec_list[ ispec ] = SpectralIntervalReader( this, scan->el[ 2 ][ ispec ], spec_frame, status ); /* Store any uncertainty region.*/ if( uncs[ 2 ] ) astSetUnc( spec_list[ ispec ], uncs[ 2 ] ); } /* If the spectral region is a single point we will use the point as the rest frequency for all RedShift Frames which are created. If there is just one spectral interval, and if it is bounded. and if the bounds are equal, note the mean spectral value. */ if( nspec == 1 ){ if( astGetBounded( spec_list[ 0 ] ) ) { astGetRegionBounds( spec_list[ 0 ], lbnd, ubnd ); if( astEQUAL( lbnd[ 0 ], ubnd[ 0 ] ) ) { spec_val = 0.5*( lbnd[ 0 ] + ubnd[ 0 ] ); } } } } /* Create Regions for all the RedshiftIntervals found in the supplied element. */ nred = scan->count[ 3 ]; red_list = astMalloc( sizeof(AstRegion *)*(size_t)nred ); if( red_list ) { for( ired = 0; ired < nred; ired++ ) { red_list[ ired ] = RedshiftIntervalReader( this, scan->el[ 3 ][ ired ], red_frame, status ); /* Store any uncertainty region.*/ if( uncs[ 3 ] ) astSetUnc( red_list[ ired ], uncs[ 3 ] ); } } /* Free the can result structure.*/ scan = FreeIVOAScan( scan, status ); /* If the spatial regions cover only a single point, convert it to FK5 J2000 and use it as the reference position for any SpecFrames (spectral or redshift) unless values were inherited from the supplied Frame. If the supplied Frame did not contain set values for these attributes, set them now. Use astRegSetAttrib which applies the attribute setting to both base and current Frame of the Region's FrameSet, and avoids re-mapping the current Frame. */ if( astOK ) { if( space_val[ 0 ] != AST__BAD && space_val[ 1 ] != AST__BAD ) { /* First need to convert to FK5 J2000 and format into a string for use with astRegSetAttrib. Need to ensure that the Format and Digits attributes are set to values which will result in no loss of precision in the formatting and unformatting steps. */ fr = astCopy( space_frame ); astClear( fr, "Format(1),Format(2),Digits(1),Digits(2)" ); astSet( fr, "digits=%d,system=FK5,equinox=J2000", status, DBL_DIG); fs = astConvert( space_frame, fr, "" ); fr = astAnnul( fr ); if( fs ) { astTran2( fs, 1, space_val, space_val + 1, 1, &raref, &decref ); text = astFormat( fs, raref, 0 ); l = text ? strlen( text ) : 0; raset = astMalloc( l + 10 ); if( raset ) sprintf( raset, "refra=%s", text ); text = astFormat( fs, decref, 1 ); l = text ? strlen( text ) : 0; decset = astMalloc( l + 10 ); if( decset ) sprintf( decset, "refdec=%s", text ); fs = astAnnul( fs ); /* Now set the FK5 J2000 values in the required Frames and Regions. */ if( !spec_frame || !astTestRefRA( spec_frame ) || !astTestRefDec( spec_frame ) ) { for( ispec = 0; ispec < nspec; ispec++ ) { astRegSetAttrib( spec_list[ ispec ], raset, NULL ); astRegSetAttrib( spec_list[ ispec ], decset, NULL ); } if( spec_frame ) { astSetRefRA( (AstSpecFrame *) spec_frame, raref ); astSetRefDec( (AstSpecFrame *) spec_frame, decref ); } } if( !red_frame || !astTestRefRA( red_frame ) || !astTestRefDec( red_frame ) ) { for( ired = 0; ired < nred; ired++ ) { astRegSetAttrib( red_list[ ired ], raset, NULL ); astRegSetAttrib( red_list[ ired ], decset, NULL ); } if( red_frame ) { astSetRefRA( (AstSpecFrame *) red_frame, raref ); astSetRefDec( (AstSpecFrame *) red_frame, decref ); } } for( ianc = 0; ianc < nanc; ianc++ ) { for( k = 0; k < 5; k++ ) { if( astMapGet0A( ancs[ ianc ], key[ k ], &o ) ) { r = (AstRegion *) o; astRegSetAttrib( r, raset, NULL ); astRegSetAttrib( r, decset, NULL ); r = astAnnul( r ); } } } /* Free resources. */ if( raset ) raset = astFree( raset ); if( decset ) decset = astFree( decset ); } else if( astOK ) { astError( AST__INTER, "AstroCoordAreaReader(XmlChan):" " Cannot convert spatial position to FK5 J2000" , status); } } /* If a time region was specified, use a typical value as the epoch for all Frames. Call MakeMJD to convert "time_val" from the system of the TimeFrame to an MJD (as required by the Frame Epoch attribute). Set the value in both the returned Region and the supplied Frame. */ if( time_val != AST__BAD ) { fr = astRegFrame( time_list[ 0 ] ); if( astIsATimeFrame( fr ) ) { time_val = MakeMJD( (AstTimeFrame *) fr, time_val, status ); } else if( astOK ) { astError( AST__INTER, "AstroCoordAreaReader(XmlChan): %s " "supplied where TimeFrame expected (internal " "AST programming error).", status, astGetClass( fr ) ); } fr = astAnnul( fr ); sprintf( buff, "epoch= MJD %.*g", DBL_DIG, time_val ); if( !space_frame || !astTestEpoch( space_frame ) ) { for( ispace = 0; ispace < nspace; ispace++ ) { astRegSetAttrib( space_list[ ispace ], buff, NULL ); } if( space_frame ) astSetEpoch( space_frame, time_val ); } if( !spec_frame || !astTestEpoch( spec_frame ) ) { for( ispec = 0; ispec < nspec; ispec++ ) { astRegSetAttrib( spec_list[ ispec ], buff, NULL ); } if( spec_frame ) astSetEpoch( spec_frame, time_val ); } if( !red_frame || !astTestEpoch( red_frame ) ) { for( ired = 0; ired < nred; ired++ ) { astRegSetAttrib( red_list[ ired ], buff, NULL ); } if( red_frame ) astSetEpoch( red_frame, time_val ); } for( ianc = 0; ianc < nanc; ianc++ ) { for( k = 0; k < 5; k++ ) { if( astMapGet0A( ancs[ ianc ], key[ k ], &o ) ) { r = (AstRegion *) o; astRegSetAttrib( r, buff, NULL ); r = astAnnul( r ); } } } } /* If the spectral regions cover only a single point, format it with its units so that the astSetAttrib function can convert it to Hz and use it as the rest frequency for any redshift Frames. */ if( spec_val != AST__BAD && nred > 0 ) { text = astGetUnit( spec_frame, 0 ); if( text ) sprintf( buff, "restfreq= %.*g %s", DBL_DIG, spec_val, text ); if( !red_frame || !astTestRestFreq( red_frame ) ) { for( ired = 0; ired < nred; ired++ ) { astRegSetAttrib( red_list[ ired ], buff, NULL ); } if( red_frame ) astSetAttrib( red_frame, buff ); } for( ianc = 0; ianc < nanc; ianc++ ) { for( k = 0; k < 5; k++ ) { if( astMapGet0A( ancs[ ianc ], key[ k ], &o ) ) { r = (AstRegion *) o; astRegSetAttrib( r, buff, NULL ); r = astAnnul( r ); } } } } /* Create Regions corresponding to every possible combination of interval on each axis type, and assemble the union of these into a CmpRegion (if there is more than one). */ sum = NULL; /* Initialise indices of the sub-Frame intervals to use. */ ispace = 0; itime = 0; ispec = 0; ired = 0; /* Loop over all possible combinations of time+space+spec+red intervals. */ while( 1 ) { rspace = ( ispace < nspace ) ? space_list[ ispace ] : NULL; rtime = ( itime < ntime ) ? time_list[ itime ] : NULL; rspec = ( ispec < nspec ) ? spec_list[ ispec ] : NULL; rred = ( ired < nred ) ? red_list[ ired ] : NULL; /* Prism Regions extrude a Region into higher dimensions, and the extrusion is defined by an Interval. Spatial Regions are not restricted to Intervals and so any spatial Region must be the first Region to be included in the Prism (all the other axis types *are* restricted to Intervals and so can be used to extrude the spatial region). */ reg = rspace ? astClone( rspace ) : NULL; /* Now extrude this region (if any) into the time axis. */ if( rtime ) { if( reg ) { tmp = (AstRegion *) astPrism( reg, rtime, "", status ); (void) astAnnul( reg ); reg = tmp; } else { reg = astClone( rtime ); } } /* Now extrude this region (if any) into the spectral axis. */ if( rspec ) { if( reg ) { tmp = (AstRegion *) astPrism( reg, rspec, "", status ); (void) astAnnul( reg ); reg = tmp; } else { reg = astClone( rspec ); } } /* Now extrude this region (if any) into the redshift axis. */ if( rred ) { if( reg ) { tmp = (AstRegion *) astPrism( reg, rred, "", status ); (void) astAnnul( reg ); reg = tmp; } else { reg = astClone( rred ); } } /* If a Prism was created, add it into the CmpRegion which holds the running sum of the union of all Prisms created so far. */ if( reg ) { if( !sum ) { sum = astClone( reg ); } else { tmp = (AstRegion *) astCmpRegion( sum, reg, AST__OR, "", status ); (void) astAnnul( sum ); sum = tmp; } reg = astAnnul( reg ); } /* Increment the indices of the next set of sub-Frame Intervals to use. Leave the while loop when all combinations have been done. */ if( ++ired >= nred ) { ired = 0; if( ++ispec >= nspec ) { ispec = 0; if( ++itime >= ntime ) { itime = 0; if( ++ispace >= nspace ) break; } } } } /* Simplify the total sum Region. */ tmp = astSimplify( sum ); (void) astAnnul( sum ); sum = tmp; /* The axes in this sum Region may not be in the correct order or units (i.e in the order and units specified in the supplied Frame). So use astConvert to get a Mapping from the Frame represented by the sum Region to the supplied Frame. */ fs = astConvert( sum, frm, "" ); if( fs ) { /* Unless the Mapping is a UnitMap, remap the sum Region into the supplied Frame using this Mapping. */ map = astGetMapping( fs, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) ) { new = astMapRegion( sum, map, frm ); } else { new = astClone( sum ); } map = astAnnul( map ); fs = astAnnul( fs ); } else if( astOK ) { astError( AST__INTER, "AstroCoordAreaReader(%s): Cannot " "convert from supplied Frame to internal Frame (AST " "internal programming error).", status, astGetClass( this ) ); } /* Transfer selected properties from the supplied Frame to the current Frame of the returned Region. */ cfrm = astRegFrame( new ); if( astTestIdent( frm ) ) astSetIdent( cfrm, astGetIdent( frm ) ); if( astTestTitle( frm ) ) astSetTitle( cfrm, astGetTitle( frm ) ); /* Ensure the Epoch is set correctly in the Region */ if( time_val != AST__BAD ) { sprintf( buff, "epoch= MJD %.*g", DBL_DIG, time_val ); astRegSetAttrib( new, buff, NULL ); } /* Free resources. */ cfrm = astAnnul( cfrm ); sum = astAnnul( sum ); } if( space_list ) { for( i = 0; i < nspace; i++ ) space_list[ i ] = astAnnul( space_list[ i ] ); space_list = astFree( space_list ); } if( time_list ) { for( i = 0; i < ntime; i++ ) time_list[ i ] = astAnnul( time_list[ i ] ); time_list = astFree( time_list ); } if( spec_list ) { for( i = 0; i < nspec; i++ ) spec_list[ i ] = astAnnul( spec_list[ i ] ); spec_list = astFree( spec_list ); } if( red_list ) { for( i = 0; i < nred; i++ ) red_list[ i ] = astAnnul( red_list[ i ] ); red_list = astFree( red_list ); } } if( space_frame ) space_frame = astAnnul( space_frame ); if( time_frame ) time_frame = astAnnul( time_frame ); if( spec_frame ) spec_frame = astAnnul( spec_frame ); if( red_frame ) red_frame = astAnnul( red_frame ); /* Get the ID attribute from the AstroCoordArea element and store in the returned Region. */ id = astXmlGetAttributeValue( elem, "ID" ); if( id ) astSetIdent( new, id ); } /* If an error has occurred,annul the returned pointer. */ if( !astOK ) new = astAnnul( new ); /* Return the pointer to the new Region. */ return new; } static int AstroCoordsReader( AstXmlChan *this, AstXmlElement *elem, AstFrame *frm, AstRegion *uncs[4], AstKeyMap **anc, int *status ) { /* * Name: * AstroCoordsReader * Purpose: * Modify a Frame to take account of an IVOA AstroCoords element, and * return an coordinate uncertainties. * Type: * Private function. * Synopsis: * #include "xmlchan.h" * int AstroCoordsReader( AstXmlChan *this, AstXmlElement *elem, * AstFrame *frm, AstRegion *uncs[4], * AstKeyMap **anc, int *status ) * Class Membership: * XmlChan member function. * Description: * This function modifies the supplied Frame object to incorporate the * effects of the supplied AstroCoords element. It may also return * Regions representing the bounds of the uncertainties in the four * component coordinate Frames, depending on the contents of the * AstroCoords element. * Parameters: * this * Pointer to the XmlChan. * elem * Pointer to the IVOA AstroCoords element. * frm * The Frame object to modify. * uncs * Array in which to return pointers to the uncertainty Regions to * be associated with each of the four STC domains (space, time, * spectral, redshift). NULL is returned in any element for which * no uncertainty is specified within the supplied AstroCoords element. * anc * Address of a location at which to store the pointer to a newly * created KeyMap holding ancillary information describing the * AstroCoords element in the form required by constructors of AST * Stc objects. A NULL pointer is returned if no usable ancillary * information is found in the AstroCoords. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if any non-NULL values have been returned in the "uncs" * array. Zero otherwise. */ /* Local Variables: */ AstFrame *afrm; /* Pointer to axis Frame */ AstFrame *gfrm; /* Pointer to generic Frame */ AstFrame *pfrm; /* Pointer to position Frame */ AstFrame *rfrm; /* Pointer to redshift Frame */ AstFrame *sfrm; /* Pointer to spectral Frame */ AstTimeFrame *tfrm; /* Pointer to time Frame */ AstKeyMap *panc; /* KeyMap holding spatial ancillary data */ AstKeyMap *ranc; /* KeyMap holding redshift ancillary data */ AstKeyMap *sanc; /* KeyMap holding spectral ancillary data */ AstKeyMap *tanc; /* KeyMap holding temporal ancillary data */ AstObject *o; /* Pointer to object retrieved from KeyMap */ AstRegion *r; /* Individual ancillary Region */ AstRegion *t; /* Total extruded ancillary Region */ AstRegion *tt; /* Temporary Region pointer */ AstXmlElement *el; /* Pointer to Position2D element */ IVOAScan *scan; /* Structure holding scan results */ char **anames; /* Pointer to list of ancillary name pointers */ const char *dom; /* Pointer to Domain attribute value */ const char *nam; /* Pointer to ancillary Name string */ const char *names[4]; /* Names of the subelements to be searched for */ char buff[100]; /* Message buffer */ double epoch; /* Epoch */ double hi; /* High limit for zero-width interval */ double lo; /* Low limit for zero-width interval */ double pos[2]; /* Reference spatial position */ double rf; /* Rest frequency */ int axes[2]; /* Indices of position axes */ int axis; /* Index of next axis to use */ int empty; /* Is returned KeyMap empty? */ int i; /* Loop count */ int isearth; /* Does the SkyFrame represent terrestrial lon/lat? */ int junk; /* Unused integer value */ int max[4]; /* Max allowed occurrences of each name */ int min[4]; /* Min allowed occurrences of each name */ int nax; /* Number of axes in supplied Frame */ int unc; /* Any uncertainty Regions found? */ int use; /* Use ancillary information? */ static const char *key[ 5 ] = { AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ, AST__STCVALUE }; /* Initialise */ unc = 0; uncs[ 0 ] = NULL; uncs[ 1 ] = NULL; uncs[ 2 ] = NULL; uncs[ 3 ] = NULL; *anc = NULL; /* Check the global error status. */ if ( !astOK ) return unc; /* Search the supplied element for the required sub-elements. */ names[ 0 ] = "Position2D|Position3D"; names[ 1 ] = "Time"; names[ 2 ] = "Spectral"; names[ 3 ] = "Redshift"; min[ 0 ] = 0; min[ 1 ] = 0; min[ 2 ] = 0; min[ 3 ] = 0; max[ 0 ] = 1; max[ 1 ] = 1; max[ 2 ] = 1; max[ 3 ] = 1; scan = ScanIVOAElement( this, elem, 4, names, min, max, status ); /* If succesfull.. */ if( scan ) { /* Initialise pointers to component Frames */ pfrm = NULL; tfrm = NULL; sfrm = NULL; rfrm = NULL; /* Initialise pointers to KeyMaps holding ancillary data. */ panc = NULL; tanc = NULL; sanc = NULL; ranc = NULL; /* Allocate storage for an array of pointers to strings holding the Name value for each axis. Initialise them to a null string. */ nax = astGetNaxes( frm ); anames = astMalloc( sizeof( char * )*(size_t)nax ); for( i = 0; i < nax; i++ ) anames[ i ] = NULL; /* Initialise the index of the next Frame axis to use. */ axis = 0; /* Check to see if the next 2 axes describe positions on the sky or earth (see SpaceFrameReader). */ axes[ 0 ] = 0; axes[ 1 ] = 1; afrm = astPickAxes( frm, 2, axes, NULL ); dom = astGetDomain( afrm ); isearth = dom && ( !strcmp( dom, "GEO_D" ) || !strcmp( dom, "GEO_C" ) ); if( isearth || ( dom && !strcmp( dom, "SKY" ) ) ){ astPrimaryFrame( frm, axis, &pfrm, &junk ); if( scan->count[ 0 ] ) { /* We currently also use SkyFrames to represent geographical long/lat used to describe observatory positions. These may have 3D positions, in which case we convert the 3D position to a 2D position by ignoring the 3rd axis value (height). See SpaceFrameReader. */ el = MakePos2D( this, scan->el[ 0 ][ 0 ], status ); /* Use the Position2D to create a Region describing the uncertainty in the space axes of the Frame. Also create a KeyMap holding Regions describing any ancillary information stored in the Position2D. */ uncs[ 0 ] = Position2DReader( this, el, pfrm, pos, &panc, status ); if( uncs[ 0 ] ) unc = 1; el = astXmlDelete( el ); /* If ancillary information was returned, extract the Name element, and store it twice (once for each axis) in the "names" array. */ if( panc && astMapGet0C( panc, AST__STCNAME, &nam ) ) { anames[ axis ] = astStore( NULL, nam, strlen( nam ) + 1 ); anames[ axis + 1 ] = astStore( NULL, nam, strlen( nam ) + 1 ); } } /* Increment the axis index. */ axis += 2; /* If the supplied Frame has no sky frame, but we found a Position2D, then report a warning and ignore the Position2D. */ } else if( scan->count[ 0 ] ) { sprintf( buff, "contains a <%s> which is not being used.", astXmlGetName( scan->el[ 0 ][ 0 ] ) ); Report( this, elem, WARNING, buff, status ); } afrm = astAnnul( afrm ); /* Indicate we do not yet have an epoch to use. */ epoch = AST__BAD; /* Check to see if the Frame contains a time frame. It will be the next axis if it does. */ afrm = astPickAxes( frm, 1, &axis, NULL ); dom = astGetDomain( afrm ); if( dom && !strcmp( dom, "TIME" ) ){ astPrimaryFrame( frm, axis, &gfrm, &junk ); /* Report an error if it is not an AST TimeFrame. */ if( !astIsATimeFrame( gfrm ) && astOK ) { astError( AST__INTER, "AstroCoordAreaReader(XmlChan): %s " "supplied where TimeFrame expected (internal " "AST programming error).", status, astGetClass( pfrm ) ); } else { tfrm = (AstTimeFrame *) gfrm; } /* Use any Time element to create a Region describing the uncertainty in the time axis of the Frame. Also create a KeyMap holding Regions describing any ancillary information stored in the Time element. */ if( scan->count[ 1 ] ) { uncs[ 1 ] = TimeReader( this, scan->el[ 1 ][ 0 ], tfrm, &epoch, &tanc, status ); if( uncs[ 1 ] ) unc = 1; /* If ancillary information was returned, extract the Name element, and store it in the "names" array. */ if( tanc && astMapGet0C( tanc, AST__STCNAME, &nam ) ) { anames[ axis ] = astStore( NULL, nam, strlen( nam ) + 1 ); } } /* Increment the index of the next axis to use. */ axis++; /* If the supplied Frame has no time frame, but we found a Time element, then report a warning and ignore the Time element. */ } else if( scan->count[ 1 ] ) { Report( this, elem, WARNING, "contains a
* Alternatively, if your data system handles the propagation of FITS * header cards to the output dataset for you, then simply create an * empty FitsChan to contain the output WCS information alone. * FITSCHAN2 = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS ) * Rewind the new FitsChan (if necessary) and attempt to write the * output WCS information to it using the same encoding method as the * input dataset. CALL AST_SET( FITSCHAN2, 'Card=1, Encoding=' // ENCODE, STATUS ) IF ( AST_WRITE( FITSCHAN2, WCSINFO2, STATUS ) .EQ. 0 ) THEN * If this didn't work (the WCS FrameSet has become too complex), then * use the native AST encoding instead. CALL AST_SETC( FITSCHAN2, 'Encoding', 'NATIVE', STATUS ); JUNK = AST_WRITE( FITSCHAN2, WCSINFO2, STATUS ); END IF \end{terminalv} \normalsize For details of how to modify the contents of the output FitsChan in other ways, such as by adding, over-writing or deleting header cards, see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and \secref{ss:findingandchangingfits}. Once you have assembled the output FITS cards, you may retrieve them from the FitsChan that contains them as follows: \small \begin{terminalv} CHARACTER * ( 80 ) CARD ... CALL AST_CLEAR( FITSCHAN2, 'Card', STATUS ) 5 CONTINUE IF ( AST_FINDFITS( FITSCHAN2, '%f', CARD, .TRUE., STATUS ) ) THEN WRITE ( *, '(A)' ) CARD GO TO 5 END IF \end{terminalv} \normalsize Here, we have simply written each card to the standard output unit, but you would obviously replace this with a subroutine call to store the cards in your output dataset. For data systems that do not use FITS header cards, a different approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} (\secref{ss:channels}) rather than a FitsChan. In the case of the Starlink NDF data format, for example, all of the above may be replaced by a single call to the routine \xref{NDF\_PTWCS}{sun33}{NDF_PTWCS}---see \xref{SUN/33}{sun33}{}. The whole process can probably be encapsulated in a similar way for most other data systems, whether they use FITS header cards or not. For an overview of how to propagate WCS information through data processing steps, see \secref{ss:propagatingwcsinformation}. For more information about writing WCS information to FitsChans, see \secref{ss:writingnativefits} and \secref{ss:writingforeignfits}. For information about the options for encoding WCS information in FITS header cards, see \secref{ss:nativeencoding}, \secref{ss:foreignencodings}, and the description of the \htmlref{Encoding}{Encoding} attribute in \appref{ss:attributedescriptions}. For a complete understanding of FitsChans and their use with FITS header cards, you should read \secref{ss:nativefits} and \secref{ss:foreignfits}. \subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid} A common requirement when displaying image data is to plot an associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid}) over the displayed image. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/overgrid_bw} \caption[An example of a displayed image with a coordinate grid plotted over it.]{An example of a displayed image with a coordinate grid plotted over it.} \label{fig:overgrid} \end{center} \end{figure} The use of AST in such circumstances is independent of the underlying graphics system, so starting up the graphics system, setting up a coordinate system, displaying the image, and closing down afterwards can all be done using the graphics routines you would normally use. However, displaying an image at a precise location can be a little fiddly with some graphics systems, and obviously the grid drawn by AST will not be accurately registered with the image unless this is done correctly. In the following template, we therefore illustrate both steps, basing the image display on the PGPLOT graphics package.\footnote{An interface is provided with AST that allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics, although interfaces to other graphics systems may also be written.} Plotting a coordinate grid with AST then becomes a relatively minor part of what is almost a complete graphics program. Once again, we assume that a pointer, WCSINFO, to a suitable \htmlref{FrameSet}{FrameSet} associated with the image has already been obtained (\secref{ss:howtoreadwcs}). \small \begin{terminalv} DOUBLE PRECISION BBOX( 4 ) INTEGER NX, NY, PGBEG, PLOT REAL DATA( NX, NY ), GBOX( 4 ), HI, LO, SCALE, TR( 6 ) REAL X1, X2, XLEFT, XRIGHT, Y1, Y2, YBOTTOM, YTOP ... * Access the image data, which we assume will be stored in the real * 2-dimensional array DATA with dimension sizes NX and NY. Also * derive limits for scaling it, which we assign to the variables HI * and LO. * Open PGPLOT using the device given by environment variable * PGPLOT_DEV and check for success. IF ( PGBEG( 0, ' ', 1, 1 ) .EQ. 1 ) THEN * Clear the screen and ensure equal scales on both axes. CALL PGPAGE CALL PGWNAD( 0.0, 1.0, 0.0, 1.0 ) * Obtain the extent of the plotting area (not strictly necessary for * PGPLOT, but possibly for other graphics systems). From this, derive * the display scale in graphics units per pixel so that the image * will fit within the display area. CALL PGQWIN( X1, X2, Y1, Y2 ) SCALE = MIN( ( X2 - X1 ) / NX, ( Y2 - Y1 ) / NY ) * Calculate the extent of the area in graphics units that the image * will occupy, so as to centre it within the display area. XLEFT = 0.5 * ( X1 + X2 - NX * SCALE ) XRIGHT = 0.5 * ( X1 + X2 + NX * SCALE ) YBOTTOM = 0.5 * ( Y1 + Y2 - NY * SCALE ) YTOP = 0.5 * ( Y1 + Y2 + NY * SCALE ) * Set up a PGPLOT coordinate transformation matrix and display the * image data as a grey scale map (these details are specific to * PGPLOT). TR( 1 ) = XLEFT - 0.5 * SCALE TR( 2 ) = SCALE TR( 3 ) = 0.0 TR( 4 ) = YBOTTOM - 0.5 * SCALE TR( 5 ) = 0.0 TR( 6 ) = SCALE CALL PGGRAY( DATA, NX, NY, 1, NX, 1, NY, HI, LO, TR ) * BEGINNING OF AST BIT * ==================== * Store the locations of the bottom left and top right corners of the * region used to display the image, in graphics coordinates. GBOX( 1 ) = XLEFT GBOX( 2 ) = YBOTTOM GBOX( 3 ) = XRIGHT GBOX( 4 ) = YTOP * Similarly, store the locations of the image's bottom left and top * right corners, in pixel coordinates -- with the first pixel centred * at (1,1). BBOX( 1 ) = 0.5D0 BBOX( 2 ) = 0.5D0 BBOX( 3 ) = NX + 0.5D0 BBOX( 4 ) = NY + 0.5D0 * Create a Plot, based on the FrameSet associated with the * image. This attaches the Plot to the graphics surface so that it * matches the displayed image. Specify that a complete set of grid * lines should be drawn (rather than just coordinate axes). PLOT = AST_PLOT( WCSINFO, GBOX, BBOX, 'Grid=1', STATUS ) * Optionally, we can now set other Plot attributes to control the * appearance of the grid. The values assigned here use the * colour/font indices defined by the underlying graphics system. CALL AST_SET( PLOT, 'Colour(grid)=2, Font(textlab)=3', STATUS ) * Use the Plot to draw the coordinate grid. CALL AST_GRID( PLOT, STATUS ) * Annul the Plot when finished (or use the AST_BEGIN/AST_END * technique shown earlier). CALL AST_ANNUL( PLOT, STATUS ) * END OF AST BIT * ============== * Close down the graphics system. CALL PGEND END IF \end{terminalv} \normalsize Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a displayed image, you may also use it to generate further graphical output of your own, specified in the image's world coordinate system (such as markers to represent astronomical objects, annotation, \emph{etc.}). There is also a range of Plot attributes which gives control over most aspects of the output's appearance. For details of the facilities available, see \secref{ss:plots} and the description of the Plot class in \appref{ss:classdescriptions}. For details of how to build a graphics program which uses PGPLOT, see \secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in \appref{ss:commanddescriptions}. \subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid} Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid (\secref{ss:howtoplotgrid}), it is a simple matter to change things so that the grid represents a different celestial coordinate system. For example, after creating the Plot with \htmlref{AST\_PLOT}{AST\_PLOT}, you could use: \small \begin{terminalv} CALL AST_SET( PLOT, 'System=Galactic', STATUS ) \end{terminalv} \normalsize or: \small \begin{terminalv} CALL AST_SET( PLOT, 'System=FK5, Equinox=J2010', STATUS ) \end{terminalv} \normalsize and any axes and/or grid drawn subsequently would represent the new celestial coordinate system you specified. Note, however, that this will only work if the original grid represented celestial coordinates of some kind (see \secref{ss:howtotestforcelestial} for how to determine if this is the case\footnote{Note that the methods applied to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not, you will get an error message. For more information about the celestial coordinate systems available, see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in \appref{ss:attributedescriptions}. \subsection{\ldots Give a User Control Over the Appearance of a Plot} The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the graphical output it produces (\secref{ss:howtoplotgrid} and \secref{ss:howtoswitchgrid}) can easily be extended to allow the user of a program complete control over such matters. For instance, if the file ``plot.config'' contains a series of plotting options in the form of Plot attribute assignments (see below for an example), then we could create a Plot and implement these assignments before producing the graphical output as follows: \small \begin{terminalv} CHARACTER LINE( 120 ) INTEGER BASE ... * Create a Plot and define the default appearance of the graphical * output it will produce. PLOT = AST_PLOT( WCSINFO, GBOX, PBOX, : 'Grid=1, Colour(grid)=2, Font(textlab)=3', : STATUS ) * Obtain the value of any Plot attributes we want to preserve. BASE = AST_GETI( PLOT, 'Base', STATUS ) * Open the plot configuration file, if it exists. OPEN ( 1, FILE = 'plot.config', STATUS = 'OLD', ERR = 8 ) * Read each line of text and use it to set new Plot attribute * values. Close the file when done. 6 CONTINUE READ ( 1, '(A)', END = 7 ) LINE CALL AST_SET( PLOT, LINE, STATUS ) GO TO 6 7 CLOSE ( 1 ) 8 CONTINUE * Restore any attribute values we are preserving. CALL AST_SETI( PLOT, 'Base', BASE, STATUS ) * Produce the graphical output (e.g.). CALL AST_GRID( PLOT, STATUS ) \end{terminalv} \normalsize Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved so that the user cannot change it. This is because graphical output will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe the plotting surface to which we attached the Plot when we created it. The arrangement shown above allows the contents of the ``plot.config'' file to control most aspects of the graphical output produced (including the coordinate system used; the colour, line style, thickness and font used for each component; the positioning of axes and tick marks; the precision, format and positioning of labels; \emph{etc.}) \emph{via} assignments of the form: \small \begin{terminalv} System=Galactic, Equinox = 2001 Border = 1, Colour( border ) = 1 Colour( grid ) = 2 DrawAxes = 1 Colour( axes ) = 3 Digits = 8 Labelling = Interior \end{terminalv} \normalsize For a more sophisticated interface, you could obviously perform pre-processing on this input---for example, to translate words like ``red'', ``green'' and ``blue'' into colour indices, to permit comments and blank lines, \emph{etc.} For a full list of the attributes that may be used to control the appearance of graphical output, see the description of the Plot class in \appref{ss:classdescriptions}. For a complete description of each individual attribute (\emph{e.g.}\ those above), see the attribute's entry in \appref{ss:attributedescriptions}. \cleardoublepage \section{\label{ss:primer}An AST Object Primer} The AST library deals throughout with entities called Objects and a basic understanding of how to handle these is needed before you can use the library effectively. If you are already familiar with an object-oriented language, such as C$++$, few of the concepts should seem new to you. Be aware, however, that AST is designed to be used \emph{via} fairly conventional Fortran and C interfaces, so some things have to be done a little differently. If you are not already familiar with object-oriented programming, then don't worry---we will not emphasise this aspect more than is necessary and will not assume any background knowledge. Instead, this section concentrates on presenting all the fundamental information you will need, explaining how AST Objects behave and how to manipulate them from conventional Fortran programs. If you like to read documents from cover to cover, then you can consider this section as an introduction to the programming techniques used in the rest of the document. Otherwise, you may prefer to skim through it on a first reading and return to it later as reference material. \subsection{AST Objects} An AST \htmlref{Object}{Object} is an entity which is used to store information and Objects come in various kinds, called \emph{classes}, according to the sort of information they hold. Throughout this section, we will make use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to illustrate many of the basic concepts. A ZoomMap is an Object that contains a recipe for converting coordinates between two hypothetical coordinate systems. It does this by multiplying all the coordinate values by a constant called the \emph{\htmlref{Zoom}{Zoom} factor}. A ZoomMap is a very simple Object which exists mainly for use in examples. It allows us to illustrate the ways in which Objects are manipulated and to introduce the concept of a \htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental to the way the AST library works. \subsection{\label{ss:objectcreation}Object Creation and Pointers} Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very simply as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER STATUS, ZOOMMAP STATUS = 0 ... ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ) \end{terminalv} \normalsize The first step is to include the file AST\_PAR which defines the interface to the AST library and, amongst other things, declares \htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} to be an integer function. We then declare an integer variable ZOOMMAP to receive the result and an integer STATUS variable to hold the error status, which we initialise to zero. Next, we invoke AST\_ZOOMMAP to create the ZoomMap. The pattern is the same for all other classes of AST \htmlref{Object}{Object}---you simply prefix ``AST\_'' to the class name to obtain the function that creates the Object. These functions are called \emph{constructor functions}, or simply \emph{constructors} (you can find an individual description of all AST functions in \appref{ss:functiondescriptions}) and the arguments passed to the constructor are used to initialise the new Object. In this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we are going to work in a 2-dimensional space) and 5.0D0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a Fortran double precision value. We will return to the final two arguments, a blank string and the error status, shortly (\secref{ss:attributeinitialisation} and \secref{ss:errordetection}). The integer value returned by the constructor is termed an \emph{Object pointer} or, in this case, a \emph{ZoomMap pointer}. This pointer is not an Object itself, but is a value used to refer to the Object. You should be careful not to modify any Object pointer yourself, as this may render it invalid. Instead, you perform all subsequent operations on the Object by passing this pointer to other AST routines. \subsection{\label{ss:objecthierarchy}The Object Hierarchy} Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it relates to other kinds of \htmlref{Object}{Object} before investigating what we can do with it. We have so far indicated that a ZoomMap is a kind of Object and have also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements can be represented very simply using the following hierarchy: \small \begin{terminalv} Object Mapping ZoomMap \end{terminalv} \normalsize which is a way of stating that a ZoomMap is a special class of Mapping, while a Mapping, in turn, is a special class of Object. This is exactly like saying that an Oak is a special form of Tree, while a Tree, in turn, is a special form of Plant. This may seem almost trivial, but before you turn to read something less dull, be assured that it is a very important idea to keep in mind in what follows. If we look at some of the other Objects used by the AST library, we can see how these are all related in a similar way (don't worry about what they do at this stage): \label{ss:mappinghierarchy} \small \begin{terminalv} Object Mapping Frame FrameSet Plot UnitMap ZoomMap Channel FitsChan XmlChan \end{terminalv} \normalsize Notice that there are several different types of Mapping available (\emph{i.e.}\ there are classes of Object indented beneath the ``Mapping'' heading) and, in addition, other types of Object which are not Mappings---Channels for instance (which are at the same hierarchical level as Mappings). The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we will not discuss in detail until \secref{ss:plots}). As you can see, a Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and, like everything else, ultimately an Object. What this means is that you can use a Plot not only for its own specialised behaviour, but also whenever any of these other less-specialised classes of Object is called for. The general rule is that an Object of a particular class may substitute for any of the classes appearing above it in this hierarchy. The Object is then said to \emph{inherit} the behaviour of these higher classes. We can therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object is called for. Sometimes, this can lead to some spectacular short-cuts by avoiding the need to break large Objects down in order to access their components. With some practice and a little lateral thinking you should soon be able to spot opportunities for this. You can find the full \emph{class hierarchy}, as this is called, for the AST library in \appref{ss:classhierarchy} and you may need to refer to it occasionally until you are familiar with the classes you need to use. \subsection{\label{ss:displayingobjects}Displaying Objects} Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier (\secref{ss:objectcreation}) and examine what it's made of. There is a routine for doing this, called \htmlref{AST\_SHOW}{AST\_SHOW}, which is provided mainly for looking at Objects while you are debugging programs. If you consult the description of AST\_SHOW in \appref{ss:functiondescriptions}, you will find that it takes a pointer to an \htmlref{Object}{Object} as its argument (in addition to the usual STATUS argument). Although we have only a ZoomMap pointer available, fortunately this is not a problem. If you refer to the brief class hierarchy described above (\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an Object, albeit a specialised one, so it inherits the properties of all Objects and can be substituted wherever an Object is required. We can therefore pass our ZoomMap pointer directly to AST\_SHOW, as follows: \small \begin{terminalv} CALL AST_SHOW( ZOOMMAP, STATUS ) \end{terminalv} \normalsize The output from this will appear on the standard output stream and should look like the following: \small \begin{terminalv} Begin ZoomMap Nin = 2 IsA Mapping Zoom = 5 End ZoomMap \end{terminalv} \normalsize Here, the ``Begin'' and ``End'' lines mark the beginning and end of the ZoomMap, while the values 2 and 5 are simply the values we supplied to initialise it (\secref{ss:objectcreation}). These have been given simple names to make them easy to refer to. The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a property shared by all Mappings, so the ZoomMap has inherited this from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however, is specific to a ZoomMap and isn't shared by other kinds of Mappings. \subsection{\label{ss:gettingattributes}Getting Attribute Values} We saw above (\secref{ss:displayingobjects}) how to display the internal values of an \htmlref{Object}{Object}, but what about accessing these values from a program? Not all internal Object values are accessible in this way, but many are. Those that are, are called \emph{attributes}. A description of all the attributes used by the AST library can be found in \appref{ss:attributedescriptions}. Attributes come in several data types (character string, integer, boolean and floating point) and there is a standard way of obtaining their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin} attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as follows: \small \begin{terminalv} INTEGER NIN ... NIN = AST_GETI( ZOOMMAP, 'Nin', STATUS ) \end{terminalv} \normalsize Here, the integer function AST\_GETI is used to extract the attribute value by giving it the ZoomMap pointer and the attribute name (attribute names are not case sensitive, but we have used consistent capitalisation in this document in order to identify them). Remember to use the AST\_PAR include file to save having to declare AST\_GETI as integer yourself. If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably have used AST\_GETD instead, this being a double precision version of the same function, for example: \small \begin{terminalv} DOUBLE PRECISION ZOOM ... ZOOM = AST_GETD( ZOOMMAP, 'Zoom', STATUS ) \end{terminalv} \normalsize However, we could equally well have read the Nin value as double precision, or the Zoom value as an integer, or whatever we wanted. The data type you want returned is specified simply by replacing the final character of the AST\_GETx function name with C~(character), D~(double precision), I~(integer), L~(logical) or R~(real). If possible, the value is converted to the type you want. If not, an error message will result. In converting from integer to logical, zero is regarded as .FALSE.\ and non-zero as .TRUE.. Note that all floating point values are stored internally as double precision. Boolean values are stored as integers, but only take the values 1 and 0 (for true/false). \subsection{\label{ss:settingattributes}Setting Attribute Values} Some attribute values are read-only and cannot be altered after an \htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing the number of coordinates) is like this. It is defined when the ZoomMap is created, but cannot then be altered. Other attributes, however, can be modified whenever you want. A ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this could be done simply as follows: \small \begin{terminalv} CALL AST_SETD( ZOOMMAP, 'Zoom', 99.6D0, STATUS ) \end{terminalv} \normalsize which sets the value to 99.6 (double precision). As when getting an attribute value (\secref{ss:gettingattributes}), you have a choice of which data type you will use to supply the new value. For instance, you could use an integer value, as in: \small \begin{terminalv} CALL AST_SETI( ZOOMMAP, 'Zoom', 99, STATUS ) \end{terminalv} \normalsize and the necessary data conversion would occur. You specify the data type you want to supply simply by replacing the final character of the AST\_SETx routine name with C~(character), D~(double precision), I~(integer), L~(logical) or R~(real). Setting a boolean attribute to any non-zero integer causes it to take the value 1. An alternative way of setting attribute values for Objects is to use the \htmlref{AST\_SET}{AST\_SET} routine (\emph{i.e.}\ with no final character specifying a data type). In this case, you supply the attribute values in a character string. The big advantage of this method is that you can assign values to several attributes at once, separating them with commas. This also reads more naturally in programs. For example: \small \begin{terminalv} CALL AST_SET( ZOOMMAP, 'Zoom=99.6, Report=1', STATUS ) \end{terminalv} \normalsize would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute (about which more shortly---\secref{ss:transforming}). You don't really have to worry about data types with this method, as any character representation will do (although you must use 0/1 instead of .TRUE./.FALSE., which are not supported). Note, when using AST\_SET, a literal comma may be included in an attribute value by enclosed the value in quotation marks: \small \begin{terminalv} CALL AST_SET( SKYFRAME, 'SkyRef="12:13:32,-23:12:44"', STATUS ) \end{terminalv} \normalsize \label{ss:attributeinitialisation} Finally, a very convenient way of setting attribute values is to do so at the same time as you create an Object. Every Object constructor function has a penultimate character argument which allows you to do this. Although you can simply leave this blank, it is an ideal opportunity to initialise the Object to have just the attributes you want. For example, we might have created our original ZoomMap with: \small \begin{terminalv} ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, 'Report=1', STATUS ) \end{terminalv} \normalsize and it would then start life with its Report attribute set to 1. \subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes} You can use the AST\_GETx family of routines (\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute at any time, regardless of whether a value has previously been set for it. If no value has been set, the AST library will generate a suitable default value. Often, the default value of an attribute will not simply be trivial (zero or blank) but may involve considerable processing to calculate. Wherever possible, defaults are designed to be real-life, sensible values that convey information about the state of the Object. In particular, they may often be based on the values of other attributes, so their values may change in response to changes in these other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a little too simple to show this behaviour, but we will meet it later on. An attribute that returns a default value in this way is said to be \emph{un-set}. Conversely, once an explicit value has been assigned to an attribute, it becomes \emph{set} and will always return precisely that value, never a default. The distinction between set and un-set attributes is important and affects the behaviour of several key routines in the AST library. You can test if an attribute is set using the logical function \htmlref{AST\_TEST}{AST\_TEST}, as in: \small \begin{terminalv} IF ( AST_TEST( ZOOMMAP, 'Report', STATUS ) ) THEN END IF \end{terminalv} \normalsize (as usual, remember to include the AST\_PAR file to declare the function as LOGICAL, or make this declaration yourself). Once an attribute is set, you can return it to its un-set state using \htmlref{AST\_CLEAR}{AST\_CLEAR}. The effect is as if it had never been set in the first place. For example: \small \begin{terminalv} CALL AST_CLEAR( ZOOMMAP, 'Report', STATUS ) \end{terminalv} \normalsize would ensure that the default value of the \htmlref{Report}{Report} attribute is used subsequently. %\subsection{TBW--Handling Character Attributes} \subsection{\label{ss:transforming}Transforming Coordinates} We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show what it is really for. Here, we will also encounter a routine that is a little more fussy about the type of pointer it will accept. The purpose of a ZoomMap is to multiply coordinates by a constant zoom factor. To witness this in action, we will first set the \htmlref{Report}{Report} attribute for our ZoomMap to a non-zero value: \small \begin{terminalv} CALL AST_SET( ZOOMMAP, 'Report=1', STATUS ) \end{terminalv} \normalsize This boolean (integer) attribute, which is present in all Mappings (and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all coordinate values that the Mapping converts. It is not a good idea to leave this feature turned on in a finished program, but it can save a lot of work during debugging. Our next step is to set up some coordinates for the ZoomMap to work on, using two arrays XIN and YIN, and two arrays to receive the transformed coordinates, XOUT and YOUT. Note that these arrays are double precision, as are all coordinate data processed by the AST library: \small \begin{terminalv} DOUBLE PRECISION XIN( 10 ), YIN( 10 ), XOUT( 10 ), YOUT( 10 ) DATA XIN / 0D0, 1D0, 2D0, 3D0, 4D0, 5D0, 6D0, 7D0, 8D0, 9D0 / DATA YIN / 0D0, 2D0, 4D0, 6D0, 8D0, 10D0, 12D0, 14D0, 16D0, 18D0 / \end{terminalv} \normalsize We will now use the routine \htmlref{AST\_TRAN2}{AST\_TRAN2} to transform the input coordinates. This is the most commonly-used (2-dimensional) coordinate transformation routine. If you look at its description in \appref{ss:functiondescriptions}, you will see that it requires a pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer, as we could with the routines discussed previously. If we passed it a pointer to an inappropriate Object, an error message would result. Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we can use it with AST\_TRAN2 to transform our coordinates, as follows: \small \begin{terminalv} CALL AST_TRAN2( ZOOMMAP, 10, XIN, YIN, .TRUE., XOUT, YOUT, STATUS ) \end{terminalv} \normalsize Here, 10 is the number of points we want to transform and the fifth argument value of .TRUE.\ indicates that we want to transform in the \emph{forward} direction (from input to output). Because our ZoomMap's Report attribute is set to 1, this will cause the effects of the ZoomMap on the coordinates to be displayed on the standard output stream: \small \begin{terminalv} (0, 0) --> (0, 0) (1, 2) --> (5, 10) (2, 4) --> (10, 20) (3, 6) --> (15, 30) (4, 8) --> (20, 40) (5, 10) --> (25, 50) (6, 12) --> (30, 60) (7, 14) --> (35, 70) (8, 16) --> (40, 80) (9, 18) --> (45, 90) \end{terminalv} \normalsize This shows the coordinate values of each point both before and after the ZoomMap is applied. You can see that each coordinate value has been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute value. The transformed coordinates are now stored in the XOUT and YOUT arrays. If we wanted to transform in the opposite direction, we need simply change the fifth argument of AST\_TRAN2 from .TRUE. to .FALSE.. We can also feed the output coordinates from the above back into the routine: \small \begin{terminalv} CALL AST_TRAN2( ZOOMMAP, 10, XOUT, YOUT, .FALSE., XIN, YIN, STATUS ) \end{terminalv} \normalsize The output would then look like: \small \begin{terminalv} (0, 0) --> (0, 0) (5, 10) --> (1, 2) (10, 20) --> (2, 4) (15, 30) --> (3, 6) (20, 40) --> (4, 8) (25, 50) --> (5, 10) (30, 60) --> (6, 12) (35, 70) --> (7, 14) (40, 80) --> (8, 16) (45, 90) --> (9, 18) \end{terminalv} \normalsize This is termed the \emph{inverse} transformation (we have converted from output to input) and you can see that the original coordinates have been recovered by dividing by the Zoom factor. \subsection{\label{ss:annullingpointers}Managing Object Pointers} So far, we have looked at creating Objects and using them in various simple ways but have not yet considered how to get rid of them again. Every \htmlref{Object}{Object} consumes various computer resources (principally memory) and should be disposed of when it is no longer required, so as to free up these resources. One way of doing this (not necessarily the best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once you have finished with it, using \htmlref{AST\_ANNUL}{AST\_ANNUL}. For example: \small \begin{terminalv} CALL AST_ANNUL( ZOOMMAP, STATUS ) \end{terminalv} \normalsize This indicates that you have finished with the pointer and sets it to the null value AST\_\_NULL (as defined in the AST\_PAR include file), so that any attempt to use it again will generate an error message. In general, this process may not delete the Object, because there may still be other pointers associated with it. However, each Object maintains a count of the number of pointers associated with it and will be deleted if you annul the final pointer. Using AST\_ANNUL consistently will therefore ensure that all Objects are disposed of at the correct time. You can determine how many pointers are associated with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute. \subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End} The use of \htmlref{AST\_ANNUL}{AST\_ANNUL} (\secref{ss:annullingpointers}) is not completely foolproof, however. Consider the following: \small \begin{terminalv} CALL AST_SHOW( AST_ZOOMMAP( 2, 5.ODO, ' ', STATUS ), STATUS ) \end{terminalv} \normalsize This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output (\secref{ss:displayingobjects}). Using function invocations as arguments to other routines in this way is very convenient because it avoids the need for intermediate pointer variables. However, the pointer generated by \htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} is still active, and since we have not stored its value, we cannot use AST\_ANNUL to annul it. The ZoomMap will therefore stay around until the end of the program. A simple way to avoid this problem is to enclose all use of AST routines between calls to \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END}, for example: \small \begin{terminalv} CALL AST_BEGIN( STATUS ) CALL AST_SHOW( AST_ZOOMMAP( 2, 5.ODO, ' ', STATUS ), STATUS ) CALL AST_END( STATUS ) \end{terminalv} \normalsize When the AST\_END call executes, every \htmlref{Object}{Object} pointer created since the previous AST\_BEGIN call is automatically annulled and any Objects left without pointers are deleted. This provides a simple solution to managing Objects and their pointers, and allows you to create Objects very freely without needing to keep detailed track of each one. Because this is so convenient, we implicitly assume that AST\_BEGIN and AST\_END are used in most of the examples given in this document. Pointer management is not generally shown explicitly unless it is particularly relevant to the point being illustrated. If necessary, calls to AST\_BEGIN and AST\_END may be nested, like \htmlref{IF}{IF}\ldots ENDIF blocks in Fortran, to define a series of AST pointer contexts. Each call to AST\_END will then annul only those Object pointers created since the matching call to AST\_BEGIN. \subsection{Exporting, Importing and Exempting AST Pointers} The \htmlref{AST\_EXPORT}{AST\_EXPORT} routine allows you to export particular pointers from one AST context (\secref{ss:contexts}) to the next outer one, as follows: \small \begin{terminalv} CALL AST_EXPORT( ZOOMMAP, STATUS ) \end{terminalv} \normalsize This would identify the pointer stored in ZOOMMAP as being required after the end of the current AST context. It causes any pointers nominated in this way to survive the next call to \htmlref{AST\_END}{AST\_END} (but only one such call) unscathed, so that they are available to the next outer context. This facility is not needed often, but is invaluable when the purpose of your \htmlref{AST\_BEGIN}{AST\_BEGIN}\ldots AST\_END block is basically to generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting that pointer out. The \htmlref{AST\_IMPORT}{AST\_IMPORT} routine can be used in a similar manner to import a pointer into the current context, so that it is deleted when the current context is closed using AST\_END. Sometimes, you may also want to exempt a pointer from all the effects of AST contexts. You should not need to do this often, but it will prove essential if you ever need to write a library of routines that stores AST pointers as part of its own internal data. Without some form of exemption, the caller of your routines could cause the pointers you have stored to be annulled---thus corrupting your internal data---simply by using AST\_END. To avoid this, you should use \htmlref{AST\_EXEMPT}{AST\_EXEMPT} on each pointer that you store, for example: \small \begin{terminalv} CALL AST_EXEMPT( ZOOMMAP, STATUS ) \end{terminalv} \normalsize This will prevent the pointer being affected by any subsequent use of AST\_END. Of course, it then becomes your responsibility to annul this pointer (using \htmlref{AST\_ANNUL}{AST\_ANNUL}) when it is no longer required. \subsection{\label{ss:copyingobjects}Copying Objects} The AST library makes extensive use of pointers, not only for accessing Objects directly, but also as a means of storing Objects inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to hold collections of other Objects). Rather than copy an Object in its entirety, a pointer to the interior Object is simply stored in the enclosing Object. This means that Objects may frequently not be completely independent of each other because, for instance, they both contain pointers to the same sub-Object. In this situation, changing one Object (say assigning an attribute value) may affect the other one \emph{via} the common Object. It is difficult to describe all cases where this may happen, so you should always be alert to the possibility. Fortunately, there is a simple solution. If you require two Objects to be independent, then simply use \htmlref{AST\_COPY}{AST\_COPY} to make a copy of one, \emph{e.g.}: \small \begin{terminalv} INTEGER ZOOMMAP1, ZOOMMAP2 ... ZOOMMAP2 = AST_COPY( ZOOMMAP1, STATUS ) \end{terminalv} \normalsize This process will create a true copy of any Object and return a pointer to the copy. This copy will not contain any pointers to any component of the original Object (everything is duplicated), so you can then modify it safely, without fear of affecting either the original or any other Object. %\subsection{TBW - Inheritance} \subsection{\label{ss:errordetection}Error Detection} If an error occurs in an AST routine (for example, if you supply an invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an error message will be written to the standard error stream and the function will immediately return. To indicate that an error has occurred, each AST routine that can potentially fail has a final integer \emph{error status} argument called STATUS. This is both an input and an output argument. Normally, you should declare a single error status variable and pass it as the STATUS argument to every AST routine you invoke. This variable must initially be cleared (\emph{i.e.}\ set to zero\footnote{We will assume throughout that the ``OK'' value is zero, as it currently is. However, a different value could, in principle, be used if the environment in which AST is running requires it. To allow for this possibility, you might prefer to use a parameter constant to represent the value zero when testing for errors.} to indicate no error). If an error occurs, the STATUS argument is returned set to a different \emph{error value}, which allows you to detect the error, as follows: \small \begin{terminalv} STATUS = 0 ... ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, 'Title=My ZoomMap', STATUS ) IF ( STATUS .NE. 0 ) THEN END IF \end{terminalv} \normalsize In this example, an error would be detected because we have attempted to set a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not have such an attribute. A consequence of the error status variable STATUS being set to an error value is that almost all AST routines will subsequently cease to function and will instead simply return without action. This means that you do not need to check for errors very frequently. Instead, you can usually simply invoke a succession of AST routines. If an error occurs in any of them, the following ones will do nothing and you can check for the error at the end, for example: \small \begin{terminalv} STATUS = 0 ... CALL AST_ROUTINEA( ... , STATUS ) CALL AST_ROUTINEB( ... , STATUS ) CALL AST_ROUTINEC( ... , STATUS ) IF ( STATUS .NE. 0 ) THEN END IF \end{terminalv} \normalsize There are, however, a few routines which do not adhere to this general rule and which will attempt to execute if their STATUS argument is initially set. These routines, such as \htmlref{AST\_ANNUL}{AST\_ANNUL}, are concerned with cleaning up and recovering resources. For example, in the following: \small \begin{terminalv} STATUS = 0 ... ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ) CALL AST_ROUTINEX( ... , STATUS ) CALL AST_ROUTINEY( ... , STATUS ) CALL AST_ROUTINEZ( ... , STATUS ) CALL AST_ANNUL( ZOOMMAP, STATUS ) IF ( STATUS .NE. 0 ) THEN END IF \end{terminalv} \normalsize AST\_ANNUL will execute normally in order to recover the resources associated with the ZoomMap that was created earlier, regardless of whether an error has occurred in any of the intermediate routines. Routines which behave in this way are noted in the relevant descriptions in \appref{ss:functiondescriptions}. If a serious error occurs, you will probably want to abort your program, but sometimes you may want to recover and carry on. This is simply done by resetting your error status variable to zero, whereupon the AST routines you pass it to will execute normally again. \cleardoublepage \section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)} In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a \htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its input to its output and back again (\secref{ss:transforming}). We also saw how its behaviour could be controlled by setting various attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made it display coordinate values as it transformed them. In this section, we will look at Mappings a bit more thoroughly and explore the behaviour which is common to all the Mappings provided by AST. This is good background for what follows, because many of the Objects we discuss later will also turn out to be Mappings in various disguises. \subsection{\label{ss:mappingclass}The Mapping Class} Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class as a whole and some of the sub-classes it contains: \begin{terminalv} Mapping CmpMap DssMap GrismMap IntraMap LutMap MathMap MatrixMap PermMap PolyMap SlaMap SpecMap TimeMap UnitMap WcsMap ZoomMap Frame \end{terminalv} The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered in detail in \secref{ss:frames}. We start by looking at the parent class, Mapping. AST does not provide a function to create a basic Mapping (\emph{i.e.}\ the AST\_MAPPING constructor does not exist). This is because the Mapping class itself is ``virtual'' and basic Mappings are of no use in themselves. The Mapping class serves simply to contain the various specialised Mappings that exist. However, it provides more than just a convenient heading for them because it bestows all classes of Mapping with common properties (\emph{e.g.}\ attributes) and behaviour. By examining the Mapping class, we are therefore examining the things that all other Mappings have in common. \subsection{The Mapping Model} The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}. It is a black box which you can supply with a set of coordinate values in return for a set of transformed coordinates. The two sets are termed \emph{input} and \emph{output} coordinates. You can also go back the other way and transform output coordinates back into input coordinates, as we saw in \secref{ss:transforming}. \subsection{Changing Attributes of a Mapping} Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each coordinate is to be multiplied. These attribute values should be set when the Mapping is created and should not be changed afterwards. Indeed, the AST library will report an error if an attempt is made to change the value of a Mapping attribute. This is because, once created, Mappings are often later included within other objects such as FrameSets and CmpMaps. This means that in general there could be many active references to a single Mapping object within a program. Changing an attribute of the Mapping via one particular reference (i.e pointer) would cause all the other references to change too, with often undesirable or unpredictable consequences. To avoid this, Mappings are considered \emph{immutable} in most situations. The one exception is if the Mapping has not yet been cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference couint of one) - changing the attributes of such a Mapping is allowed, and will not generate an error. Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and can be changed at any time. \subsection{Input and Output Coordinate Numbers} In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to represent a single point need not be the same as the number that comes out. Often these numbers will be the same, and often they will both equal 2 (because 2-dimensional coordinate systems are common), but this needn't necessarily be the case. The number of coordinates required to specify an input point is represented by the integer attribute \htmlref{Nin}{Nin} and the number required to specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only attributes common to all Mappings. Generally, their values are fixed when a Mapping is created. In \secref{ss:objectcreation}, we saw how the Nin attribute for a \htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function \htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} which created it. In this case, the Nout attribute was not needed and it implicitly took the same value as Nout, but we could have enquired about its value had we wanted, as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER NOUT, STATUS, ZOOMMAP STATUS = 0 ... NOUT = AST_GETI( ZOOMMAP, 'Nout', STATUS ) \end{terminalv} \normalsize \subsection{Forward and Inverse Transformations} We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates either from input to output, or \emph{vice versa}. These are termed its \emph{forward} and \emph{inverse} transformations. This statement was not quite accurate, however, because in general Mappings are only \textbf{potentially} capable of working in both directions. In practice, coordinate transformation may only be feasible in one direction or the other because some functions are not easily inverted (they may be multi-valued, for instance). Allowance must be made for this, so each Mapping has two read-only boolean (integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate whether each transformation is available. A transformation is available if the corresponding attribute is non-zero, otherwise it is not.\footnote{Most of the Mappings provided by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can behave otherwise.} If you enquire about the value of these attributes, a value of 0 or 1 is returned. Attempting to use a Mapping to apply a transformation which is not available will result in an error. \subsection{\label{ss:invertingmappings}Inverting Mappings} An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert} flag. This is a boolean (integer) attribute that can be assigned a new value at any time. If it is non-zero, it has the effect of interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the Mapping is then said to be \emph{inverted}. By default, the Invert attribute is zero. There is no magic in this. There is no fancy arithmetic involved in inverting mathematical functions, for instance. The Invert flag is simply a switch that interchanges a Mapping's input and output ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and when you ask for what was once the forward transformation you get the inverse transformation instead (and \emph{vice versa}). When you return the Invert attribute to zero, or clear it, the Mapping returns to its original behaviour. Often, the actual value of the Invert attribute is unimportant and you simply wish to invert its boolean sense, so that what was the Mapping's input becomes its output and \emph{vice versa}. This is most easily accomplished using \htmlref{AST\_INVERT}{AST\_INVERT}, as follows: \small \begin{terminalv} INTEGER MAPPING ... CALL AST_INVERT( MAPPING, STATUS ) \end{terminalv} \normalsize If the Mapping you have happens to be the wrong way around, AST\_INVERT allows you to correct the problem. \subsection{Finding the Rate of Change of a Mapping Output} The \htmlref{AST\_RATE}{AST\_RATE} function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output with respect to any Mapping input, at a given input position. The method used produces good accuracy (typically a relative error of 10E-10 or less) but may require the Mapping to be evaluated 100 or more times. An estimate of the second derivative is also produced by this function. \subsection{Reporting Coordinate Transformations} We have already seen (\secref{ss:transforming}) how the boolean (integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the operation of transforming a set of coordinates will result in a report being written to standard output. This will display the coordinate values before and after transformation. It can save considerable time during program development by eliminating the need to add loops and output statements to your program. In a finished program, however, you should be careful that the Report attribute is not set to a non-zero value unless you want to see the output (there may often be rather a lot of this!). To help prevent unwanted output being produced by accident, the Report attribute is unusual in that its value is not preserved when a Mapping is copied using \htmlref{AST\_COPY}{AST\_COPY} (\secref{ss:copyingobjects}). Instead, it reverts to its default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to zero when a Mapping is written out, \emph{e.g.}\ to a file using a \htmlref{Channel}{Channel} (\secref{ss:channels}). %\subsection{TBW---More on Transforming Coordinates} \subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values} Even when coordinates can, in principle, be transformed in either direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific coordinate values cannot be handled. For example, the Mapping may be mathematically intractable (\emph{e.g.}\ singular) in certain places, or it may map a subset of one space on to another, so that some points in one space are not represented in the other. Sky projections often show this behaviour, since it is quite common to project only half of the celestial sphere on to two dimensions, omitting points on the opposite side of the sky. There are many other examples. To indicate when coordinates cannot be transformed, for whatever reason, AST substitutes a special output coordinate value given by the parameter constant AST\_\_BAD (as defined in the AST\_PAR include file). Before making use of coordinates generated by any of the AST transformation routines, therefore, you may need to check for the presence of this value. Because coordinates with the value AST\_\_BAD can be generated in this way, all other AST routines are also capable of recognising this value and handling it appropriately. The coordinate transformation routines do this by propagating any missing input coordinate information through to their output. This means that if you supply coordinates with the value AST\_\_BAD, the returned coordinates are also likely to contain this value. Here, for example, is what happens if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of coordinates: \small \begin{terminalv} (0, 0) --> (0, 0) (, 2) --> (, 10) (2, 4) --> (10, 20) (3, 6) --> (15, 30) (4, ) --> (20, ) (5, 10) --> (25, 50) (, ) --> (, ) (7, 14) --> (35, 70) (8, 16) --> (40, 80) (9, 18) --> (45, 90) \end{terminalv} \normalsize The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This is a case of ``garbage in, garbage out'' but at least it's consistent garbage that you can recognise! Note how the presence of the AST\_\_BAD value in one input dimension does not necessarily result in the loss of information for all output dimensions. Sometimes, such loss will be unavoidable, but in general an attempt is made to preserve information as far as possible. The exact behaviour will depend on the Mapping involved. \subsection{\label{ss:unitmapexample}Example---the UnitMap} The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its purpose is simply to copy coordinate values, unaltered, from its input to its output and \emph{vice versa}. A UnitMap has no additional attributes beyond those of a basic Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are specified by the first argument supplied to its constructor. For example: \small \begin{terminalv} INTEGER UNITMAP ... UNITMAP = AST_UNITMAP( 2, ' ', STATUS ) \end{terminalv} \normalsize will create a UnitMap that copies 2-dimensional coordinates. Inverting a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert} attribute. The main use of a UnitMap is to allow a Mapping to be supplied when one is required (as an argument to a routine, for example) but you wish it to leave coordinate values unchanged. \subsection{\label{ss:permmapexample}Example---the PermMap} The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met previously. Its purpose is to change the order, or number, of coordinates. It is also able to substitute fixed values for coordinates. To illustrate its action, suppose our input coordinates are denoted by ($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore, should rotate the coordinate values by one position. To create such a PermMap, we first set up two integer arrays. One of these, OUTPERM, controls the selection of input coordinates for use in the output and the other, INPERM, controls selection of output coordinates for use in the input: \small \begin{terminalv} INTEGER OUTPERM( 4 ), INPERM( 4 ) DATA OUTPERM / 4, 1, 2, 3 / DATA INPERM / 2, 3, 4, 1 / \end{terminalv} \normalsize Note that the numbers we store in these arrays are the indices of the coordinates that we want to select. We have chosen these so that the forward and inverse transformations will perform complementary permutations on the coordinates. The PermMap is then created by passing these arrays to its constructor, as follows: \small \begin{terminalv} INTEGER PERMMAP DOUBLE PRECISION DUMMY( 1 ) ... PERMMAP = AST_PERMMAP( 4, INPERM, 4, OUTPERM, DUMMY, ' ', STATUS ) \end{terminalv} \normalsize (the fifth argument is not being used, so a dummy array has been supplied). Note that we specify the number of input and output coordinates separately, but set both to 4 in this example. The resulting PermMap would have the following effect when used to transform coordinates: \begin{terminalv} Forward: (1, 2, 3, 4) --> (4, 1, 2, 3) (2, 4, 6, 8) --> (8, 2, 4, 6) (3, 6, 9, 12) --> (12, 3, 6, 9) (4, 8, 12, 16) --> (16, 4, 8, 12) (5, 10, 15, 20) --> (20, 5, 10, 15) Inverse: (4, 1, 2, 3) --> (1, 2, 3, 4) (8, 2, 4, 6) --> (2, 4, 6, 8) (12, 3, 6, 9) --> (3, 6, 9, 12) (16, 4, 8, 12) --> (4, 8, 12, 16) (20, 5, 10, 15) --> (5, 10, 15, 20) \end{terminalv} If the number of input and output coordinates are unequal so, also, will be the size of the OUTPERM and INPERM arrays. This means, however, that we cannot fill them with coordinate indices so that they perform complementary permutations, because one transformation will lose information (discard a coordinate) that the other cannot recover. To give an example, consider the following: \small \begin{terminalv} INTEGER OUTPERM( 3 ), INPERM( 4 ) DOUBLE PRECISION CONST( 1 ) DATA OUTPERM / 4, 3, 2 / DATA INPERM / -1, 3, 2, 1 / DATA CONST / 99.004D0 / \end{terminalv} \normalsize In this case, the forward transformation will change ($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The inverse transformation restores the original coordinate order, but has no value to assign to the first coordinate. In this case, the number entered in the INPERM array is $-$1. This negative value indicates that the coordinate value should be obtained by addressing the CONST array using an index of 1 (the absolute value). This array, ignored in the previous example, may then be used to supply a value for the missing coordinate. The constructor function: \small \begin{terminalv} PERMMAP = AST_PERMMAP( 4, INPERM, 3, OUTPERM, CONST, ' ', STATUS ) \end{terminalv} \normalsize will then create a PermMap with the following effect when used to transform coordinates: \begin{terminalv} Forward: (1, 2, 3, 4) --> (4, 3, 2) (2, 4, 6, 8) --> (8, 6, 4) (3, 6, 9, 12) --> (12, 9, 6) (4, 8, 12, 16) --> (16, 12, 8) (5, 10, 15, 20) --> (20, 15, 10) Inverse: (4, 3, 2) --> (99.004, 2, 3, 4) (8, 6, 4) --> (99.004, 4, 6, 8) (12, 9, 6) --> (99.004, 6, 9, 12) (16, 12, 8) --> (99.004, 8, 12, 16) (20, 15, 10) --> (99.004, 10, 15, 20) \end{terminalv} The CONST array may contain more than one value if necessary and may be addressed by both the INPERM and OUTPERM arrays using coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the first, second, third,~\emph{etc.}\ elements. If there is no suitable replacement value that can be supplied \emph{via} the CONST array, a value of zero may be entered into the OUTPERM and/or INPERM arrays. This causes the value AST\_\_BAD to be used for the affected coordinate (as defined in the AST\_PAR include file), thus indicating a missing coordinate value (\secref{ss:badcoordinates}). The principle use for a PermMap lies in matching a coordinate system to a data array where there is a choice of storage order for the data. PermMaps are also useful for discarding unwanted coordinates so as to reduce the number of dimensions, such as when selecting a ``slice'' from a multi-dimensional array. \cleardoublepage \section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)} We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The Mappings we have considered so far have been atomic, in the sense that they perform pre-defined elementary transformations. A CmpMap, however, is a compound Mapping. In essence, it is a framework for containing other Mappings and its purpose is to allow those Mappings to work together in various combinations while appearing as a single \htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is determined by the other Mappings it contains. \subsection{\label{ss:seriescmpmap}Combining Mappings in Series} Consider a simple example based on two 2-dimensional coordinate systems. Suppose that to convert from one to the other we must swap the coordinate order and multiply both coordinates by 5, so that the coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done in two stages: \begin{enumerate} \item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the coordinate order. \item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both coordinate values by the constant 5. \end{enumerate} The PermMap and ZoomMap are then said to operate \emph{in series}, because they are applied sequentially (\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}). We can create a \htmlref{CmpMap}{CmpMap} that applies these Mappings in series as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER CMPMAP, PERMMAP, STATUS, ZOOMMAP INTEGER INPERM( 2 ), OUTPERM( 2 ), CONST( 1 ) DATA INPERM / 1, 2 / DATA OUTPERM / 1, 2 / STATUS = 0 ... * Create the individual Mappings. PERMMAP = AST_PERMMAP( 2, INPERM, 2, OUTPERM, CONST, ' ', STATUS ) ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ) * Combine them in series. CMPMAP = AST_CMPMAP( PERMMAP, ZOOMMAP, .TRUE., ' ', STATUS ) * Annul the individual Mapping pointers. CALL AST_ANNUL( PERMMAP, STATUS ) CALL AST_ANNUL( ZOOMMAP, STATUS ) \end{terminalv} \normalsize Here, the third argument (.TRUE.) of the constructor function \htmlref{AST\_CMPMAP}{AST\_CMPMAP} indicates ``in series''. When used to transform coordinates in the forward direction, the resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap) and then the second one (the ZoomMap). When transforming in the inverse direction, it will apply the second one (in the inverse direction) and then the first one (also in the inverse direction). In general, although not in this particular example, the order in which the two component Mappings are supplied is significant. Clearly, also, the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for the second one. \subsection{Combining Mappings in Parallel} Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the only way of combining them. The alternative, \emph{in parallel}, involves applying the two Mappings at once but on different subsets of the coordinate values. Consider, for example, a set of 3-dimensional coordinates and suppose we wish to transform them by swapping the first two coordinate values and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms into ($x_2,x_1,5x_3$). Again, we can perform each of these steps individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is 1-dimensional and the individual Mappings are applied in parallel (\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}). Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple: \small \begin{terminalv} CMPMAP = AST_CMPMAP( PERMMAP, ZOOMMAP, .FALSE., ' ', STATUS ) \end{terminalv} \normalsize The only difference is that the third argument of \htmlref{AST\_CMPMAP}{AST\_CMPMAP} is now .FALSE., meaning ``in parallel''. As before, the order in which the two component Mappings are supplied is significant. The first one acts on the lower-numbered input coordinate values (however many it needs) and produces the lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on the higher-numbered input coordinates (however many remain) and generates the remaining higher-numbered output coordinates. When the CmpMap transforms coordinates in the inverse direction, both component Mappings are applied to the same coordinates, but in the inverse direction. Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings (\emph{i.e.}\ the numbers of input and output coordinates) will sum to give the Nin and Nout attributes of the overall CmpMap. \subsection{\label{ss:cmpmapcomponents}The Component Mappings} A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply holds pointers to them. In th example above (\secref{ss:seriescmpmap}), we were free to annul the individual \htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount} attribute) of each component Mapping by one. The individual components are therefore not deleted by \htmlref{AST\_ANNUL}{AST\_ANNUL}, but retained until the CmpMap itself is deleted and annuls the pointers it holds. Consistent use of AST\_ANNUL (\secref{ss:annullingpointers}) and/or pointer contexts (\secref{ss:contexts}) will therefore ensure that all Objects are deleted at the appropriate time. Note that access to a CmpMap's component Mappings is not generally available unless pointers to them are retained when the CmpMap is created. If such pointers are retained, then subsequent modifications to the individual components can be used to indirectly modify the behaviour of the overall CmpMap. There is an important exception to this, however, because a CmpMap retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its components and uses these in order to ignore any subsequent external changes. This means that you may invert either component Mapping before inserting it into a CmpMap and need not worry if you un-invert it again later. The CmpMap's behaviour will not be affected by the later action. \subsection{\label{ss:complexcmpmap}Creating More Complex Mappings} Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can substitute (\secref{ss:objecthierarchy}) as a component Mapping when constructing a new CmpMap using \htmlref{AST\_CMPMAP}{AST\_CMPMAP}. This has the effect of nesting one CmpMap inside another and opens up many new possibilities. For example, combining three Mappings in series can be accomplished as follows: \small \begin{terminalv} INTEGER MAP1, MAP2, MAP3 ... CMPMAP = AST_CMPMAP( MAP1, AST_CMPMAP( MAP2, MAP3, .TRUE., ' ', STATUS ), : .TRUE., ' ', STATUS ) \end{terminalv} \normalsize The way in which the individual component Mappings are grouped within the nested CmpMaps is not usually important. A similar technique can be used to combine multiple Mappings in parallel and, of course, mixed series and parallel combinations are also possible (Figure~\ref{fig:complexcmpmap}). There is no built-in limit to how many CmpMaps may be nested in this way, so this mechanism provides an indefinitely extensible method of building complex Mappings out of the elemental building blocks provided by AST. In practice, you might not need to construct such complex CmpMaps yourself very frequently, but they will often be returned by AST routines. Nested CmpMaps underlie the library's entire ability to represent a wide range of different coordinate transformations. \subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images} Consider, as a practical example of CmpMaps, two images of the sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from pixel coordinates to a standard celestial coordinate system, say FK5~(J2000.0). If we wish to inter-compare these images, we can do so by using this celestial coordinate system to align them. That is, we first convert from pixel coordinates in the first image into FK5 coordinates and we then convert from FK5 coordinates into pixel coordinates in the second image. If MAPA and MAPB are pointers to our two original Mappings, we could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel coordinates of the first and second images by combining these Mappings, as follows: \small \begin{terminalv} INTEGER ALIGNMAP, MAPA, MAPB ... CALL AST_INVERT( MAPB, STATUS ) ALIGNMAP = AST_CMPMAP( MAPA, MAPB, .TRUE., ' ', STATUS ) CALL AST_INVERT( MAPB, STATUS ) \end{terminalv} \normalsize Here, we have used \htmlref{AST\_INVERT}{AST\_INVERT} (\secref{ss:invertingmappings}) to invert MAPB before inserting it into the CmpMap because, as supplied, it converted in the wrong direction. Afterwards, we invert it again to return it to its original state. The CmpMap, however, will ignore this subsequent change (\secref{ss:cmpmapcomponents}). The forward transformation of the resulting CmpMap will now transform from pixel coordinates in the first image to pixel coordinates in the second image, while its inverse transformation will convert in the opposite direction. \subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings} While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it unfortunately also provides an opportunity for representing simple Mappings in complex ways. Sometimes, unnecessary complexity can be difficult to avoid but can obscure important simplifications. Consider the example above (\secref{ss:cmpmapexample}), in which we inter-related two images of the sky \emph{via} a CmpMap. If the two images turned out to be simply offset from each other by a shift along each pixel axis, then this approach would align them correctly, but it would be inefficient. This is because it would introduce unnecessary and expensive transformations to and from an intermediate celestial coordinate system, whereas a simple shift of pixel origin would suffice. Recognising that a simpler and more efficient solution exists obviously requires a little more than simply joining two Mappings end-to-end. We must also determine whether the resulting CmpMap is more complex than it needs to be, \emph{i.e.}\ contains redundant information. If it is, we then need a way to simplify it. The problem is not always just one of efficiency, however. Sometimes we may also need to know something about the actual form a \htmlref{Mapping}{Mapping} takes---\emph{i.e.}\ the nature of the operations it performs. Unnecessary complexity can obscure this, but such complexity can easily accumulate during normal data processing. For example, a Mapping that transforms pixel coordinates into positions on the sky might be repeatedly modified as changes are made to the shape and size of the image. Typically, on each occasion, another Mapping will be concatenated to reflect what has happened to the image. This could soon make it difficult to discern the overall nature of the transformation from the complex CmpMap that accumulates. If only shifts of origin were involved on each occasion, however, they could be combined into a single shift which could be represented much more simply. Suppose we now wanted to represent our image's celestial coordinate calibration using FITS conventions (\secref{ss:foreignfits}). This requires AST to determine whether the Mapping which relates pixel coordinate to sky positions conforms to the FITS model (for example, whether it is equivalent to applying a single set of shifts and scale factors followed by a map projection). Clearly, there is an important use here for some means of simplifying the internal structure of a CmpMap. \subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings} The ability to simplify compound Mappings is provided by the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} function. This function encapsulates a number of heuristics for converting Mappings, or combinations of Mappings within a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap, AST\_SIMPLIFY tries to reduce the number of individual Mappings within it by merging neighbouring component Mappings together. It will do this with both series and parallel combinations of Mappings, or both, and will handle CmpMaps nested to any depth (\secref{ss:complexcmpmap}). To illustrate how AST\_SIMPLIFY works, consider the combination of Mappings shown in Figure~\ref{fig:simplifyexample}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/simpexamp} \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps, ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single UnitMap. The enclosing nested CmpMaps have been omitted for clarity.} \label{fig:simplifyexample} \end{center} \end{figure} If this were contained in a CmpMap, it could be simplified as follows: \small \begin{terminalv} INTEGER SIMPLER ... SIMPLER = AST_SIMPLIFY( CMPMAP, STATUS ); \end{terminalv} \normalsize In this case, the result would be a simple 3-dimensional UnitMap (the identity \htmlref{Mapping}{Mapping}). To reach this conclusion, AST\_SIMPLIFY will have made a number of deductions, roughly as follows: \begin{enumerate} \item The two 2-dimensional ZoomMaps in series are equivalent to a single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is equivalent to a 2-dimensional UnitMap. \item This UnitMap in parallel with the other 1-dimensional UnitMap is equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched between any other pair of Mappings, can then be eliminated. \item The remaining two PermMaps in series are equivalent to a single 3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap is found to be equivalent to a 3-dimensional UnitMap. \end{enumerate} This example is a little contrived, but illustrates how AST\_SIMPLIFY can deal with even quite complicated compound Mappings through a series of incremental simplifications. Where possible, this will result in either a simpler compound Mapping or, if feasible, an atomic (non-compound) Mapping, as here. If no simplification is possible, AST\_SIMPLIFY will just return a pointer to the original Mapping. Although AST\_SIMPLIFY cannot identify every simplification that is theoretically possible, sufficient rules are included to deal with the most common and important cases. \cleardoublepage \section{\label{ss:frames}Representing Coordinate Systems (Frames)} An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is used to describe how to convert between coordinate systems. The two concepts are complementary and we will see how they work together in \secref{ss:framesets}. In this section we will discuss only basic Frames, which represent Cartesian coordinate systems. More specialised types of Frame (\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes}) and, naturally, inherit the properties and behaviour of the simple Frames discussed here. \subsection{The Frame Model} The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would plot around a graph. In two dimensions, you would have an ``$x$'' and a ``$y$'' axis, a title on the graph and labels on the axes, together with an indication of the physical units being plotted. The values marked along each axis would be formatted in a human-readable way. The frame around a graph therefore defines a coordinate space within which you can locate points, draw lines, calculate distances, \emph{etc.} An AST Frame works in much the same way, embodying all of these concepts and a few more. It also allows any number of axes, which means that a Frame can represent coordinate systems with any number of dimensions. You specify how many when you create it. Remember that the basic Frame we are considering here is completely general. It knows nothing of celestial coordinates, for example, and all its axes are equivalent. It can be adapted to describe any general purpose Cartesian coordinate system by setting its attributes, such as its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values. \subsection{\label{ss:creatingframes}Creating a Frame} Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER FRAME, STATUS STATUS = 0 ... FRAME = AST_FRAME( 2, ' ', STATUS ) \end{terminalv} \normalsize The first argument of the \htmlref{AST\_FRAME}{AST\_FRAME} constructor function specifies the number of axes which the Frame should have. \subsection{\label{ss:frameasmapping}Using a Frame as a Mapping} We should briefly point out that the \htmlref{Frame}{Frame} we created above (\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping} (\secref{ss:mappingclass}) and therefore inherits the properties and behaviour common to other Mappings. One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited from the Mapping class) to a non-zero value and pass the Frame pointer to a coordinate transformation routine, such as \htmlref{AST\_TRAN2}{AST\_TRAN2}. \small \begin{terminalv} DOUBLE PRECISION XIN( 5 ), YIN( 5 ), XOUT( 5 ), YOUT( 5 ) DATA XIN / 0D0, 1D0, 2D0, 3D0, 4D0, 5D0 / DATA YIN / 0D0, 2D0, 4D0, 6D0, 8D0, 10D0 / CALL AST_SET( FRAME, 'Report=1', STATUS ) CALL AST_TRAN2( FRAME, 5, XIN, YIN, .TRUE., XOUT, YOUT, STATUS ) \end{terminalv} \normalsize The resulting output might then look like this: \begin{terminalv} (1, 2) --> (1, 2) (2, 4) --> (2, 4) (3, 6) --> (3, 6) (4, 8) --> (4, 8) (5, 10) --> (5, 10) \end{terminalv} This is not very exciting because a Frame implements an identity transformation just like a \htmlref{UnitMap}{UnitMap} (\secref{ss:unitmapexample}). However, it illustrates that a Frame can be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both equal to the number of Frame axes. When we consider more specialised Frames (\emph{e.g.}~\secref{ss:framesets}), we will see that using them as Mappings can be very useful indeed. \subsection{\label{ss:frameaxisattributes}Frame Axis Attributes} Frames have a number of attributes which can take multiple values, one for each axis. These separate values are identified by appending the axis number in parentheses to the attribute name. For example, the Label(1) attribute is a character string containing the label which appears on the first axis. \htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes (\secref{ss:gettingattributes}, \secref{ss:settingattributes} and \secref{ss:defaultingattributes}). For example, the Label on the second axis might be obtained as follows: \small \begin{terminalv} CHARACTER * ( 70 ) LABEL ... LABEL = AST_GETC( FRAME, 'Label(2)', STATUS ) \end{terminalv} \normalsize Other attribute access routines (AST\_SETx, \htmlref{AST\_TEST}{AST\_TEST} and \htmlref{AST\_CLEAR}{AST\_CLEAR}) may also be applied to axis attributes in the same way. If the axis number is stored in a program variable, then its value must be formatted to generate a suitable attribute name before using this to access the attribute itself. For example, the following will print out the Label value for each axis of a \htmlref{Frame}{Frame}: \small \begin{terminalv} CHARACTER * ( 10 ) AXIS INTEGER IAXIS ... DO 1 IAXIS = 1, AST_GETI( FRAME, 'Naxes', STATUS ) WRITE ( AXIS, '( I10 )' ) IAXIS LABEL = AST_GETC( FRAME, 'Label(' // AXIS // ')', STATUS ) WRITE ( *, 199 ) IAXIS, LABEL 199 FORMAT ( 'Label ', I2, ': ', A ) 1 CONTINUE \end{terminalv} \normalsize Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame axes. The output from this might look like the following: \begin{terminalv} Label 1: Axis 1 Label 2: Axis 2 \end{terminalv} In this case, the Frame's default axis Labels have been revealed as rather un-exciting. Normally, you would set much more useful values, typically when you create the Frame---perhaps something like: \small \begin{terminalv} FRAME = AST_FRAME( 2, 'Label(1)=Offset from centre of field,' // 'Unit(1) =mm,' // 'Label(2)=Transmission coefficient,' // 'Unit(2) =%', STATUS ) \end{terminalv} \normalsize Here, we have also set the (character string) Unit attribute for each axis to describe the physical units represented on that axis. All the attribute assignments have been combined into a single string, separated by commas. \subsection{\label{ss:frameattributes}Frame Attributes} We will now briefly outline the various attributes associated with a \htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the \htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each attribute, for which you should consult the appropriate description in \appref{ss:attributedescriptions}. Instead, we aim simply to sketch the range of facilities available: \begin{quote} \begin{description} \item[\htmlref{Naxes}{Naxes}]\mbox{}\\ A read-only integer giving the number of Frame axes. \item[\htmlref{Title}{Title}]\mbox{}\\ A string describing the coordinate system which the Frame represents. \item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\ A label string for each axis. \item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\ A string describing the physical units on each axis. You can choose whether to make this attribute ``active'' or ``passive'' (using \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} ). If active, its value will be taken into account when finding the Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used to connect two axis with units of ``km'' and ``m''). If passive, its value is ignored. Its use is described in more detail in \secref{ss:frameunits}. \item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\ A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X'' or ``Y'') used to represent the quantity plotted on each axis. \item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\ The preferred number of digits of precision to be used when formatting values for display on each axis. \item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\ A string containing a \emph{format specifier} which determines exactly how values should be formatted for display on each axis (\secref{ss:formattingaxisvalues}). If this attribute is un-set, the formatting is based on the Digits value, otherwise the Format string over-rides the Digits value. \item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\ A boolean (integer) value which indicates in which direction each axis should be plotted. If it is non-zero (the default), the axis should be plotted in the conventional direction---\emph{i.e.}\ increasing to the right for the abscissa and increasing upwards for the ordinate. If it is zero, the axis should be plotted in reverse. This attribute is provided as a hint only and programs are free to ignore it if they wish. \item[\htmlref{Domain}{Domain}]\mbox{}\\ A character string which identifies the \emph{physical domain} to which the Frame's coordinate system applies. The primary purpose of this attribute is to prevent unwanted conversions from occurring between coordinate systems which are not related. Its use is described in more detail in \secref{ss:framedomains}. \item[\htmlref{System}{System}]\mbox{}\\ A character string which identifies the specific coordinate system used to describe positions within the physical domain represented by the Frame. For a simple Frame, this attribute currently has a fixed value of ``Cartesian'', but could in principle be extended to include options such as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame} and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be appropriate to the domain which they describe. For instance, the SkyFrame allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows values such as ``frequency'' and ``wavelength''. \item[\htmlref{Epoch}{Epoch}]\mbox{}\\ This value is used to qualify a coordinate system by giving the moment in time when the coordinates are correct. Usually, this will be the date of observation. The Epoch value is important in cases where coordinates systems move with respect to each other over time. An example of two such coordinate systems are the FK4 and FK5 celestial coordinate systems. \item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\ Specifies the longitude of the observer (assumed to be on the surface of the earth). The basic Frame class does not use this value, but specialised sub-classes may. For instance, the SpecFrame class uses it to calculate the relative velocity of the observer and the centre of the earth for use in converting between standards of rest. \item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\ Specifies the latitude of the observer. Use in conjunction with ObsLon. \end{description} \end{quote} There are also some further Frame attributes, not described above, which are important when Frames are used as templates to search for other Frames. Their use goes beyond the present discussion. %TBW---Add reference here. \subsection{\label{ss:formattingaxisvalues}Formatting Axis Values} The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored (\emph{e.g.}\ within your program) as double precision values. The Frame class therefore provides a function, \htmlref{AST\_FORMAT}{AST\_FORMAT}, to convert these values into formatted strings for display: \small \begin{terminalv} CHARACTER * ( 50 ) STRING DOUBLE PRECISION VALUE ... STRING = AST_FORMAT( FRAME, IAXIS, VALUE, STATUS ) \end{terminalv} \normalsize Here, the AST\_FORMAT character function is passed a Frame pointer, the number of an axis (IAXIS) and a double precision value to format (VALUE). It returns a character string containing the formatted value. \label{ss:formattingwithdigits} By default, the formatting applied will be determined by the Frame's Digits attribute and will normally display results with seven digits of precision (corresponding approximately to the Fortran REAL data type on many machines). Setting a different Digits value, however, allows you to adjust the precision as necessary to suit the accuracy of the coordinate data you are processing. If finer control is needed, it is also possible to set a Digits value for each individual axis by appending an axis number to the attribute name (\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the effect of the Frame's main Digits value for that axis. Even finer control is possible by setting the (character string) Format attribute for a Frame axis. The string given should contain a \emph{format specifier} which explicitly determines how the values on that axis should be formatted. This will over-ride the effects of any Digits value\footnote{The exception to this rule is that if the Format value includes a precision of ``$.*$'', then Digits will be used to determine the actual precision used.}. Unfortunately for Fortran programmers, this must be a C language format specifier,\footnote{This is a consequence of implementing the AST library in C.} so you might find the Digits approach preferable. The simplest type of format specifier takes the form ``\%m.nG'', where ``m'' and ``n'' are integers giving the minimum field width in characters and the number of significant digits to display (\emph{e.g.}\ ``\%10.5G''). The ''n'' value may be replaced by an asterisk, in which case the value of the Digits attribute is used to determine the number of significant digits to display. Other formatting options are also possible and if you need to use them you may wish to consult a book on C (see the ``printf'' function), remembering that you want to format a double precision (C double) value. It is recommended that you use AST\_FORMAT whenever you display formatted coordinate values, even although you could format them yourself using a WRITE statement. This is because it puts the Frame in control of formatting. When you start to handle more elaborate Frames (representing, say, celestial coordinates), you will need different formatting methods. This approach delivers them without any change to your software. You should also consider regularly using the \htmlref{AST\_NORM}{AST\_NORM} routine, described below (\secref{ss:normalising}), for any values that will be made visible to the user of your software. \subsection{\label{ss:normalising}Normalising Frame Coordinates} The routine \htmlref{AST\_NORM}{AST\_NORM} is provided to cope with the fact that some coordinate systems do not extend indefinitely in all directions. Some may have boundaries, outside which coordinates are meaningless, while others wrap around on themselves, so that after a certain distance you return to the beginning again (coordinate systems based on circles and spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but other more specialised Frames (such as SkyFrames, representing the celestial sphere---\secref{ss:skyframes}) do. The role played by AST\_NORM is to \emph{normalise} any arbitrary set of coordinates by converting them into a set which is ``within bounds'', interpreted according to the particular Frame in question. For example, on the celestial sphere, a right ascension value of 24~hours or more can have a suitable multiple of 24~hours subtracted without affecting its meaning and AST\_NORM would perform this task. Similarly, negative values of right ascension would have a multiple of 24~hours added, so that the result lies in the range zero to 24~hours. The coordinates in question are modified in place by AST\_NORM, as follows: \small \begin{terminalv} DOUBLE PRECISION POINT( 2 ) ... CALL AST_NORM( FRAME, POINT, STATUS ) \end{terminalv} \normalsize If the coordinates supplied are initially OK, as they would always be with a basic Frame, then they are returned unchanged. Because the main purpose of AST\_NORM is to convert coordinates into the preferred range for human consumption, its use is almost always appropriate immediately before formatting coordinate values for display using \htmlref{AST\_FORMAT}{AST\_FORMAT} (\secref{ss:formattingaxisvalues}). Even if the Frame in question does not restrict the range of coordinates, so that AST\_NORM does nothing, using it will allow you to process other more specialised Frames, where normalisation is important, without changing your software. \subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values} The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame} axis, such as might be produced by \htmlref{AST\_FORMAT}{AST\_FORMAT} (\secref{ss:formattingaxisvalues}), back into a numerical (double precision) value ready for processing is performed by \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}. However, although this process is essentially the inverse of that performed by AST\_FORMAT, there are a number of additional difficulties that must be addressed in practice. The main use for AST\_UNFORMAT is in reading formatted coordinate values which have been entered by the user of a program, or read from a file. As such, we can rarely assume that the values are neatly formatted in the way that AST\_FORMAT would produce. Instead, it is usually desirable to allow considerable flexibility in the form of input that can be accommodated, so as to permit ``free-format'' data input by the user. In addition, we may need to extract individual coordinate values embedded in other textual data. Underlying these requirements is the root difficulty that the textual format used to represent a coordinate value will depend on the class of Frame we are considering. For example, for a basic Frame, AST\_UNFORMAT may have to read a value like ``1.25E-6'', whereas a more specialised Frame representing celestial coordinates may have to handle a value like ``-07d~49m~13s''. Of course, the format might also depend on which axis is being considered. Ideally, we would like to write software that can handle any kind of Frame. However, this makes it a little more difficult to analyse textual input data to extract individual coordinate values, since we cannot make assumptions about how the values are formatted. It would not be safe, for example, simply to assume that the values being read are separated by white space. This is not just because they might be separated by some other character, but also because celestial coordinate values might themselves contain spaces. In fact, to be completely safe, we cannot make any assumptions about how a formatted coordinate value is separated from the surrounding text, except that it should be separated in some way which is not ambiguous. This is the very basic assumption upon which AST\_UNFORMAT works. It is invoked as follows: \small \begin{terminalv} INTEGER N ... N = AST_UNFORMAT( FRAME, IAXIS, STRING, VALUE, STATUS ) \end{terminalv} \normalsize It is supplied with a Frame pointer (FRAME), the number of an axis (IAXIS) and a character string to be read (STRING). If it succeeds in reading a value, AST\_UNFORMAT returns the resulting coordinate \emph{via} its penultimate argument (VALUE). The returned function value indicates how many characters were read from the string in order to obtain this result. The string is read as follows: \begin{enumerate} \item Any white space at the start is skipped over. \item Further characters are considered, one at a time, until the next character no longer matches any of the acceptable forms of input (given the characters that precede it). The longest sequence of characters which matches is then considered ``read''. \item If a suitable sequence of characters was read successfully, it is converted into a coordinate value which is returned. Any white space following this sequence is then skipped over and the total number of characters consumed is returned as the function value. \item If the sequence of characters read is empty, or insufficient to define a coordinate value, then the string does not contain a value to read. In this case, the read is aborted and AST\_UNFORMAT returns a function value of zero and no coordinate value. However, it returns without error. \end{enumerate} Note that failing to read a coordinate value does not constitute an error, at least so far as AST\_UNFORMAT is concerned. However, an error can occur if the sequence of characters read appears to have the correct form but cannot be converted into a valid coordinate value. Typically, this will be because it violates some constraint, such as a limit on the value of one of its fields. The resulting error message will give details. For any given Frame axis, AST\_UNFORMAT does not necessarily always use the same algorithm for converting the sequence of characters it reads into a coordinate value. This is because some forms of input (particularly free-format input) can be ambiguous and might be interpreted in several ways depending on the context. For example, the celestial longitude ``12:34:56.7'' could represent an angle in degrees or a right ascension in hours. To decide which to use, AST\_UNFORMAT may examine the Frame's attributes and, in particular, the appropriate \htmlref{Format(axis)}{Format(axis)} string which is used by AST\_FORMAT when formatting coordinate values (\secref{ss:formattingaxisvalues}). This is done in order that AST\_FORMAT and AST\_UNFORMAT should complement each other---so that formatting a value and then un-formatting it will yield the original value, subject to any rounding error. To give a simple (but crucially incomplete!) example, consider reading a value for the axis of a basic Frame, as follows: \small \begin{terminalv} N = AST_UNFORMAT( FRAME, IAXIS, ' 1.5E6 -99.0', VALUE, STATUS ) \end{terminalv} \normalsize AST\_UNFORMAT will skip over the initial space in the string supplied and then examine each successive character. It will accept the sequence ``1.5E6'' as input, but reject the space which follows because it does not form part of the format of a floating point number. It will then convert the characters ``1.5E6'' into a coordinate value and skip over the three spaces which follow them. The returned function value will therefore be 9, equal to the total number of characters consumed. This result may be used to address the string during a subsequent read, so as to commence reading at the start of ``-99.0''. Most importantly, however, note that if the user of a program mistakenly enters the string ``~1.5R6\ldots'' instead of ``~1.5E6\ldots'', a coordinate value of 1.5 and a function result of 4 will be returned, because the ``R'' would prematurely terminate the attempt to read the value. Because this sort of mistake does not automatically result in an error but can produce incorrect results, it is \textbf{vital} to check the returned function value to ensure that the expected number of characters have been read. For example, if the string is expected to contain exactly one value, and nothing else, then the following would suffice: \small \begin{terminalv} N = AST_UNFORMAT( FRAME, IAXIS, STRING, VALUE, STATUS ) IF ( STATUS .EQ. 0 ) THEN IF ( N .LT. LEN( STRING ) ) THEN ELSE END IF END IF \end{terminalv} \normalsize If AST\_UNFORMAT does not detect an error itself, we check that it has read to the end of the string. If this reveals an error, the value of N indicates where it occurred. Another common requirement is to obtain a position by reading a list of coordinates from a string which contains one value for each axis of a Frame. We assume that the values are separated in some unambiguous manner, perhaps using white space and/or some unspecified single-character separator. The choice of separator is up to the data supplier, who must choose it so as not to conflict with the format of the coordinate values, but our software does not need to know what it is. The following is a template algorithm for reading data in this form: \small \begin{terminalv} INTEGER I DOUBLE PRECISION VALUES( 10 ) ... * Initialise the string index. I = 1 * Obtain the number of Frame axes and loop through them. DO 1 IAXIS = 1, AST_GETI( FRAME, 'Naxes', STATUS ) * Attempt to read a value for this axis. N = AST_UNFORMAT( FRAME, IAXIS, STRING( I : ), : VALUES( IAXIS ), STATUS ) * If nothing was read and this is not the first axis and the end of * the string has not been reached, try stepping over a separator and * reading again. IF ( ( N .EQ. 0 ) .AND. ( IAXIS .GT. 1 ) .AND. : ( I .LT. LEN( STRING ) ) ) THEN I = I + 1 N = AST_UNFORMAT( FRAME, IAXIS, STRING( I : ), : VALUES( IAXIS ), STATUS ) END IF * Quit if nothing was read, otherwise move on to the next value. IF ( N .EQ. 0 ) GO TO 2 I = I + N 1 CONTINUE 2 CONTINUE * Check for possible errors. IF ( STATUS .EQ. 0 ) THEN IF ( ( I .LT. LEN( STRING ) ) .OR. ( N .EQ. 0 ) ) THEN ELSE END IF END IF \end{terminalv} \normalsize In this case, the value of I will indicate the location of any input error. Note that this algorithm is insensitive to the precise format of the data and will therefore work with any class of Frame and any reasonably unambiguous input data. For example, here is a range of suitable input data for a 3-dimensional basic Frame: \small \begin{terminalv} 1 2.5 3 3.1,3.2,3.3 1.5, 2.6, -9.9e2 -1.1+0.4-1.8 .1/.2/.3 44.0 ; 55.1 -14 \end{terminalv} \normalsize \subsection{\label{ss:permutingaxes}Permuting Frame Axes} Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number of axes it contains, but it is possible to change the order in which these axes occur. To do so, an integer \emph{permutation array} is filled with the numbers of the axes so as to specify the new order, \emph{e.g.:} \small \begin{terminalv} INTEGER PERM( 2 ) DATA PERM / 2, 1 / \end{terminalv} \normalsize In this case, the axes of a 2-dimensional Frame could be interchanged by passing this permutation array to the \htmlref{AST\_PERMAXES}{AST\_PERMAXES} function. That is, an ($x_1,x_2$) coordinate system would be changed into an ($x_2,x_1$) coordinate system by: \small \begin{terminalv} CALL AST_PERMAXES( FRAME, PERM, STATUS ) \end{terminalv} \normalsize If the axes are permuted more than once, the effects are cumulative. You are, of course, not restricted to Frames with only two axes. \subsection{Selecting Frame Axes} An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not allowed, is to create a new Frame by selecting axes from an existing one. The method of doing this is very similar to the way \htmlref{AST\_PERMAXES}{AST\_PERMAXES} is used (\secref{ss:permutingaxes}), in that we supply an integer array filled with the numbers of the axes we want, in their new order. In this case, however, the number of array elements need not equal the number of Frame axes. For example, we could select axes 3 and 2 (in that order) from a 3-dimensional Frame as follows: \small \begin{terminalv} INTEGER FRAME1, FRAME2, MAPPING, PICK( 2 ) DATA PICK / 3, 2 / ... FRAME2 = AST_PICKAXES( FRAME1, 2, PICK, MAPPING, STATUS ) \end{terminalv} \normalsize This would return a pointer to a 2-dimensional Frame (FRAME2) which contains the information associated with axes 3 and 2, in that order, from the original Frame (FRAME1). The original Frame is not altered by this process. Beware, however, that the axis information may still be shared by both Frames, so if you wish to alter either of them independently you may first need to use \htmlref{AST\_COPY}{AST\_COPY} (\secref{ss:copyingobjects}) to make an independent copy. In addition to the new Frame pointer, \htmlref{AST\_PICKAXES}{AST\_PICKAXES} will also return a pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument. This Mapping will inter-relate the two Frames. By this we mean that its forward transformation will convert coordinates originally in the coordinate system represented by FRAME1 into that represented by FRAME2, while its inverse transformation will convert in the opposite direction. In this particular case, the Mapping would be a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following transformations: \begin{terminalv} Forward: (1, 2, 3) --> (3, 2) (2, 4, 6) --> (6, 4) (3, 6, 9) --> (9, 6) (4, 8, 12) --> (12, 8) (5, 10, 15) --> (15, 10) Inverse: (3, 2) --> (, 2, 3) (6, 4) --> (, 4, 6) (9, 6) --> (, 6, 9) (12, 8) --> (, 8, 12) (15, 10) --> (, 10, 15) \end{terminalv} This is our first introduction to the idea of inter-relating pairs of Frames \emph{via} a Mapping, but this will assume a central role later on. Note that when using AST\_PICKAXES, it is also possible to request more axes than there were in the original Frame. This will involve selecting axes from the original Frame that do not exist. To do this, the corresponding axis number (in the PICK array) should be set to zero and the effect is to introduce an additional new axis which is not derived from the original Frame. This axis will have default values for all its attributes. You will need to do this because AST\_PICKAXES does not allow you to select any of the original axes more than once.\footnote{It will probably not be obvious why this restriction is necessary, but consider creating a Frame with one longitude axis and two latitude axes. Which latitude axis should be associated with the longitude axis?} \subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets} Some complementary routines are provided for use with Frames to allow you to perform geometric operations without needing to know the nature of the coordinate system represented by the \htmlref{Frame}{Frame}. Routines can be used to find the distance between two points, and to offset a specified distance along a line joining two points, \emph{etc.} In essence, these define the metric of the coordinate space which the Frame represents. In the case of a basic Frame, this is a Cartesian metric. The first of these routines, \htmlref{AST\_DISTANCE}{AST\_DISTANCE}, returns a double precision distance value when supplied with the Frame coordinates of two points. For example: \small \begin{terminalv} DOUBLE PRECISION DIST, POINT1( 2 ), POINT2( 2 ) DATA POINT1 / 0D0, 0D0 / DATA POINT2 / 1D0, 1D0 / ... DIST = AST_DISTANCE( FRAME, POINT1, POINT2, STATUS ) \end{terminalv} \normalsize This calculates the distance between the origin (0,0) and a point at position (1,1). In this case, the result, as you would expect, is $\surd{2}$. However, this is only true for the Cartesian coordinate system which a basic Frame represents. In general, AST\_DISTANCE will calculate the geodesic distance between the two points, so that with a more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial sphere) a great-circle distance might be returned. The \htmlref{AST\_OFFSET}{AST\_OFFSET} routine is really the inverse of AST\_DISTANCE. Given two points in a Frame, it calculates the coordinates of a third point which is offset a specified distance away from the first point along the geodesic joining it to the second one. For example: \small \begin{terminalv} DOUBLE PRECISION POINT1( 2 ), POINT2( 2 ), POINT3( 2 ) DATA POINT1 / 0D0, 0D0 / DATA POINT2 / 1D0, 1D0 / ... CALL AST_OFFSET( FRAME, POINT1, POINT2, 0.5D0, POINT3, STATUS ) \end{terminalv} \normalsize This would fill the POINT3 array with the coordinates of a point which is offset 0.5 units away from the origin (0,0) in the direction of the position (1,1). Again, this is a simple result in a Cartesian Frame, as varying the offset will trace out a straight line. On the celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would trace out a great circle. The routines \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE} and \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET} are similar to AST\_DISTANCE and AST\_OFFSET, except that the curves which they use as ``straight lines'' are not geodesics, but curves parallel to a specified axis\footnote {For instance, a line of constant Declination is not a geodesic}. One reason for using these routines is to deal with the cyclic ambiguity of longitude and latitude axes. The \htmlref{AST\_OFFSET2}{AST\_OFFSET2} routine is similar to AST\_OFFSET, but instead of using the geodesic which passes through two positions, it uses the geodesic which passes at a given position angle through the starting position. Position angles are always measured from the positive direction of the second Frame axis to the required line, with positive angles being in the same sense as rotation from the positive direction of the second axis to the positive direction of the first Frame axis. This definition applies to all classes of Frame, including SkyFrame. The default ordering of axes in a SkyFrame makes the second axis equivalent to north, and so the definition of position angle given above corresponds to the normal astronomical usage, ``from north, through east''. However, it should be remembered that it is possible to permute the axes of a SkyFrame (or indeed any Frame), so that north becomes axis 1. In this case, an AST ``position angle'' would be the angle ``from east, through north''. Always take the axis ordering into account when deriving an astronomical position angle from an AST position angle. Within a Cartesian coordinate system, the position angle of a geodesic (\emph{i.e.}\ a straight line) is constant along its entire length, but this is not necessarily true of other coordinate systems. Within a spherical coordinate system, for instance, the position angle of a geodesic will vary along its length (except for the special cases of a meridian and the equator). In addition to returning the required offset position, the AST\_OFFSET2 routine returns the position angle of the geodesic at the offset position. This is useful if you want to trace out a path which involves turning through specified angles. For instance, tracing out a rectangle in which each side is a geodesic involves turning through 90 degrees at the corners. To do this, use AST\_OFFSET2 to calculate the position of each corner, and then add (or subtract) 90 degrees from the position angle returned by AST\_OFFSET2. The \htmlref{AST\_ANGLE}{AST\_ANGLE} routine calculates the angle subtended by two points, at a third point. If used with a 2-dimensional Frame the returned angle is signed to indicate the sense of rotation (clockwise or anti-clockwise) in taking the ``shortest route'' from the first point to the second. If the Frame has more than 2 axes, the result is un-signed and is always in the range zero to $\pi$. The \htmlref{AST\_AXANGLE}{AST\_AXANGLE} routine is similar to AST\_AXANGLE, but the ``reference direction'', from which angles are measured, is a specified axis. The \htmlref{AST\_RESOLVE}{AST\_RESOLVE} routine resolves a given displacement within a Frame into two components, parallel and perpendicular to a given reference direction. The displacement is specified by two positions within the Frame; the starting and ending positions. The reference direction is defined by the geodesic curve passing through the starting position and a third specified position. The lengths of the two components are returned, together with the position on the reference geodesic which is closest to the third supplied point. \subsection{\label{ss:framedomains}The Domain Attribute} The \htmlref{Domain}{Domain} attribute is one of the most important properties of a \htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little subtle. We will introduce it here, but its true value will probably not become apparent until later (\secref{ss:framesetconverting}). To understand the need for the Domain attribute, consider using different Frames to represent the following different coordinate systems associated with a CCD image: \begin{enumerate} \item A coordinate system based on pixel numbers. \item Positions on the CCD chip, measured in $\mu$m. \item Positions in the focal plane of the telescope, measured in mm. \item A celestial coordinate system, measured in radians. \end{enumerate} If we had two such CCD images, we might legitimately want to align them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based on pixel numbers) in order to, say, divide by a flat-field exposure. We might similarly consider aligning them using any of the other coordinate systems so as to achieve different results. For example, we might consider merging separate images from a CCD mosaic by using focal plane positions. It would obviously not be legitimate, however, to directly compare positions in one image measured in pixels with positions in the other measured in mm, nor to equate chip positions in $\mu$m with sky coordinates in radians. If we wanted to inter-compare these coordinates, we would need to do it indirectly, using other information based on the experimental set-up. For instance, we might need to know the size of the pixels expressed in mm and the orientation of the CCD chip in the focal plane. Note that it is not simply the difference in physical units which prevents certain coordinates from being directly inter-compared (because the appropriate unit scaling factors could be included without any additional information). Neither is it the fact that different coordinate systems are in use (because we could legitimately inter-compare two different celestial coordinate systems without any extra information). Instead, it is the different nature of the coordinate spaces to which these coordinate systems have been applied. We normally express this by saying that the coordinate systems apply to different \emph{physical domains}. Although we may establish \emph{ad hoc} relationships between coordinates in different physical domains, they are not intrinsically related to each other and we need to supply extra information before we can convert coordinates between them. In AST, the role of the (character string) Domain attribute is to assign Frames to their respective physical domains. The way it operates is as follows: \begin{itemize} \item Coordinate systems which apply to the same physical domain (\emph{i.e.}\ whose Frames have the same Domain value) can be directly inter-compared. If the domain has several coordinate systems associated with it (\emph{e.g.}\ the celestial sphere), then a coordinate conversion may be involved. Otherwise, coordinate values may simply be equated. \item Coordinate systems which apply to different physical domains (\emph{i.e.}\ whose Frames have different Domain values) cannot be directly inter-compared. If any relationship does exist between such coordinate systems---and it need not---then additional information must be supplied in order to establish the relationship between them in any particular case. We will see later (\secref{ss:framesets}) how to establish such relationships between Frames in different domains. \end{itemize} With the basic Frames we are considering here, each physical domain only has a single (Cartesian) coordinate system associated with it, so that if two such Frames have the same Domain value, their coordinate systems will be identical and may simply be equated. With more specialised Frames, however, more than one coordinate system may apply to each domain. In such cases, a coordinate conversion may need to be performed. When a basic Frame is created, its Domain attribute defaults to a blank string. This means that all such Frames belong to the same (null) domain by default and therefore describe the same unspecified physical coordinate space. In order to assign a Frame to a different domain, you simply need to set its Domain value. This is normally most conveniently done when it is created, as follows: \small \begin{terminalv} FRAME1 = AST_FRAME( 2, 'Domain=CCD_CHIP,' // 'Unit(1)=micron,' // 'Unit(2)=micron', STATUS ) FRAME2 = AST_FRAME( 2, 'Domain=FOCAL_PLANE,' // 'Unit(1)=mm,' // 'Unit(2)=mm', STATUS ) \end{terminalv} \normalsize Here, we have created two Frames in different physical domains. Although their coordinate values all have units of length, they cannot be directly inter-compared (because their axes may be rotated with respect to each other, for instance). All Domain values are automatically converted to upper case and white space is removed, but there are no other restrictions on the names you may use to label different physical domains. From a practical point of view, however, it is worth following a few conventions (\secref{ss:domainconventions}). \subsection{\label{ss:domainconventions}Conventions for Domain Names} When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it obviously makes sense to avoid generic names which might clash with those used for similar (but subtly different!) purposes by other programmers. If you are developing software for an instrument, for example, and want to identify an instrumental coordinate system, then it is sensible to add a distinguishing prefix. For instance, you might use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an acronym) identifies your instrument. For some purposes, however, a standard choice of Domain name is desirable so that different items of software can communicate. For this purpose, the following Domain names are reserved by AST and the use recommended below should be carefully observed: \begin{quote} \begin{description} \item[GRAPHICS]\mbox{}\\ Identifies the coordinate space used by an underlying computer graphics system to specify plotting operations. Typically, when performing graphical operations, AST is used to define additional coordinate systems which are related to these ``native'' graphical coordinates. Plotting may be carried out in any of these coordinate systems, but the GRAPHICS domain identifies the native coordinates through which AST communicates with the underlying graphics system. \item[GRID]\mbox{}\\ Identifies the instantaneous \emph{data grid} used to store and handle data, together with an associated coordinate system. In this coordinate system, the first element stored in an array of data always has a coordinate value of unity at its centre and all elements have unit extent. This applies to all dimensions. If data are copied or transformed to a new data grid (by whatever means), or a subset of the original grid is extracted, then the same rules apply to the copy or subset. Its first element therefore has GRID coordinate values of unity at its centre. Note that this means that GRID coordinates remain attached to the first element of the data grid and not to its data content (\emph{e.g.}\ the features in an image). \item[PIXEL]\mbox{}\\ Identifies an array of pixels and an associated \emph{pixel-based} coordinate system which is related to the GRID coordinate system (above) simply by a shift of origin along each axis. This shift may be integral, fractional, positive, negative or zero. The data elements retain their unit extent along each axis. Because the amount of shift is unspecified, the PIXEL domain is distinct from the GRID domain. The relationship between them contains a degree of uncertainty, such as typically arises from the different conventions used by different software systems. For instance, in some software the first pixel is regarded as being centred at (1,1), while in other software it is at (0.5,0.5). In addition, some software packages implement a ``pixel origin'' which allows pixel coordinates to start at an arbitrary value. The GRID domain (which corresponds with the pixel-numbering convention used by FITS) is a special case of the PIXEL domain and avoids this uncertainty. In general, additional information is required in order to convert from one to the other. \item[SKY]\mbox{}\\ Identifies the domain which contains all equivalent celestial coordinate systems. Because these are represented in AST by SkyFrames (\secref{ss:skyframes}), it should be no surprise that the default Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you probably won't need to change this very often. \item[SPECTRUM]\mbox{}\\ Identifies the domain used to describe positions within an electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes}) class describes positions within this domain, allowing a wide range of different coordinate systems to be used (frequency, wavelength, \emph{etc}). The default Domain value for a SpecFrame is SPECTRUM. \item[TIME]\mbox{}\\ Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame} class describes positions within this domain, allowing a wide range of different coordinate systems and timescales to be used. The default Domain value for a TimeFrame is TIME. \end{description} \end{quote} Although we have drawn a necessary distinction here between the GRID and PIXEL domains, we will continue to refer in general terms to image ``pixels'' and ``pixel coordinates'' whenever this distinction is not important. This should not be taken to imply that the GRID convention for numbering pixels is excluded---in fact, it is usually to be preferred (at the level of data handling being discussed in this document) and we recommend it. \subsection{\label{ss:frameunits}The Unit Attribute} Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used to describe positions on the axis. The index of the axis to which the attribute refers should normally be placed in parentheses following the attribute name (``Unit(2)'' for instance). However, if the Frame has only a single axis, then the axis index can be omitted. In versions of AST prior to version 2.0, the Unit attribute was nothing more than a descriptive string intended purely for human readers---no part of the AST system used the Unit string for any purpose (other than inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between two Frames. Thus if the conversion between a pair of 1-dimensional Frames representing velocity was found (using \htmlref{AST\_CONVERT}{AST\_CONVERT} ) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is referred to below as a \emph{passive} Unit attribute. As of AST version 2.0, a facility exists which allows the Unit attribute to be \emph{active}; that is, differences in the Unit attribute may be taken into account when finding the Mapping between two Frames. In order to minimise the risk of breaking older software, the \emph{default} behaviour of simple Frames and SkyFrames is unchanged from previous versions (\emph{i.e.} they have passive Unit attributes). However, the new routines \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} and \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT} allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame} classes \emph{always} have an active Unit attribute (attempts to change this are ignored). For instance, consider the above example of two 1-dimensional Frames describing velocity. These Frames can be created as follows: \small \begin{terminalv} INTEGER FRAME1, FRAME2 FRAME1 = AST_FRAME( 1, 'Domain=VELOCITY,Unit=km/h' ) FRAME2 = AST_FRAME( 1, 'Domain=VELOCITY,Unit=m/s' ) \end{terminalv} \normalsize By default, these Frames have passive Unit attributes, and so an attempt to find a Mapping between them would ignore the difference in their Unit attributes and return a unit Mapping. To avoid this, we indicate that we want these Frames to have \emph{active} Unit attributes, as follows: \small \begin{terminalv} CALL AST_SETACTIVEUNIT( FRAME1, .TRUE., STATUS ) CALL AST_SETACTIVEUNIT( FRAME2, .TRUE., STATUS ) \end{terminalv} \normalsize If we then find the Mapping between them as follows: \small \begin{terminalv} INTEGER CVT ... CVT = AST_CONVERT( FRAME1, FRAME2, ' ', STATUS ) \end{terminalv} \normalsize the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by AST\_CONVERT will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a velocity in $km/h$) by a factor of 0.278 to create its output (a velocity in $m/s$). In fact we need not have set the Unit attribute active in FRAME1 since the behaviour of AST\_CONVERT is determined by its TO Frame (the second Frame argument). \subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings} Conversion between units systems relies on the use of a specific syntax for the Unit attribute. If the value of the Unit attribute does not conform to this syntax, then an error will be reported if an attempt is made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen if the Unit attribute is \emph{passive}). The adopted syntax is that described in FITS-WCS paper I "Representation of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish here between ``basic'' units and ``derived'' units: derived units are defined in terms of other units (either derived or basic), whereas basic units have no such definitions. Derived units may be represented by their own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a \emph{mathematical expression} which combines other symbols and constants to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per second). Unit symbols may be prefixed by a string representing a standard multiple or sub-multiple. In addition to the unit symbols listed in FITS-WCS Paper I, any other arbitrary unit symbol may be used, with the proviso that it will not be possible to convert between Frames using such units. The exception to this is if both Frames refer to the same unknown unit string. For instance, an axis with unknown unit symbol "flop" \emph{could} be converted to an axis with unit "Mflop" (Mega-flop). Unit symbols (optionally prefixed with a multiple or sub-multiple) can be combined together using a limited range of mathematical operators and functions, to produce new units. Such expressions may also contain parentheses and numerical constants (these may optionally use ``scientific'' notation including an ``E'' character to represent the power of 10). The following tables list the symbols for the basic and derived units which may be included in a units string, the standard prefixes for multiples and sub-multiples, and the strings which may be used to represent mathematical operators and functions. \begin{table}[htbp] \begin{center} \begin{tabular}{|l|l|l|} \hline \multicolumn{3}{|c|}{{\large Basic units}} \\ \hline \multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & \multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline length & m & metre \\ mass & g & gram \\ time & s & second \\ plane angle & rad & radian \\ solid angle & sr & steradian \\ temperature & K & Kelvin \\ electric current & A & Ampere \\ amount of substance & mol & mole \\ luminous intensity & cd & candela \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{small} \begin{tabular}{|l|l|l|l|} \hline \multicolumn{4}{|c|}{{\large Derived units}} \\ \hline \multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & \multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline area & barn & barn & 1.0E-28 m**2 \\ area & pix & pixel & \\ area & pixel & pixel & \\ electric capacitance & F & Farad & C/V \\ electric charge & C & Coulomb & A s \\ electric conductance & S & Siemens & A/V \\ electric potential & V & Volt & J/C \\ electric resistance & Ohm & Ohm & V/A \\ energy & J & Joule & N m \\ energy & Ry & Rydberg & 13.605692 eV \\ energy & eV & electron-Volt & 1.60217733E-19 J \\ energy & erg & erg & 1.0E-7 J \\ events & count & count & \\ events & ct & count & \\ events & ph & photon & \\ events & photon & photon & \\ flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\ flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\ flux density & mag & magnitude & \\ force & N & Newton & kg m/s**2 \\ frequency & Hz & Hertz & 1/s \\ illuminance & lx & lux & lm/m**2 \\ inductance & H & Henry & Wb/A \\ length & AU & astronomical unit & 1.49598E11 m \\ length & Angstrom & Angstrom & 1.0E-10 m \\ length & lyr & light year & 9.460730E15 m \\ length & pc & parsec & 3.0867E16 m \\ length & solRad & solar radius & 6.9599E8 m \\ luminosity & solLum & solar luminosity & 3.8268E26 W \\ luminous flux & lm & lumen & cd sr \\ magnetic field & G & Gauss & 1.0E-4 T \\ magnetic flux & Wb & Weber & V s \\ mass & solMass & solar mass & 1.9891E30 kg \\ mass & u & unified atomic mass unit & 1.6605387E-27 kg \\ magnetic flux density & T & Tesla & Wb/m**2 \\ plane angle & arcmin & arc-minute & 1/60 deg \\ plane angle & arcsec & arc-second & 1/3600 deg \\ plane angle & mas & milli-arcsecond & 1/3600000 deg \\ plane angle & deg & degree & pi/180 rad \\ power & W & Watt & J/s \\ pressure, stress & Pa & Pascal & N/m**2 \\ time & a & year & 31557600 s \\ time & d & day & 86400 s \\ time & h & hour & 3600 s \\ time & yr & year & 31557600 s \\ time & min & minute & 60 s \\ & D & Debye & 1.0E-29/3 C.m \\ \hline \end{tabular} \end{small} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{tabular}{|lll|lll|} \hline \multicolumn{6}{|c|}{{\large Prefixes for multiples \& sub-multiples}} \\ \hline \multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & \multicolumn{1}{c|}{Prefix} & \multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & \multicolumn{1}{c|}{Prefix} \\ \hline $10^{-1}$ & deci & d & $10$ & deca & da \\ $10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\ $10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\ $10^{-6}$ & micro & u & $10^{6}$ & mega & M \\ $10^{-9}$ & nano & n & $10^{9}$ & giga & G \\ $10^{-12}$ & pico & p & $10^{12}$ & tera & T \\ $10^{-15}$ & femto & f & $10^{15}$ & peta & P \\ $10^{-18}$ & atto & a & $10^{18}$ & exa & E \\ $10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\ $10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{tabular}{|l|l|} \hline \multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\ \hline \multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline sym1 sym2 & multiplication (a space) \\ sym1*sym2 & multiplication (an asterisk) \\ sym1.sym2 & multiplication (a dot) \\ sym1/sym2 & division \\ sym1**y & exponentiation ($y$ must be a numerical constant)\\ sym1\verb+^+y & exponentiation ($y$ must be a numerical constant)\\ log(sym1) & common logarithm \\ ln(sym1) & natural logarithm \\ exp(sym1) & exponential \\ sqrt(sym1) & square root \\ \hline \end{tabular} \end{center} \end{table} \subsubsection{Side-effects of Changing the Unit attribute} If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by setting a new value or by clearing it so that the default value is re-instated) may cause the Label and Symbol attributes to be changed accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'', ``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)'' will cause AST to change its Label and Symbol to ``log(Frequency)'' and ``Log(nu)''. These changes are only made if the Unit attribute is active, and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change to the Label or Symbol attributes. \cleardoublepage \section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)} A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on the celestial sphere is obviously of great importance in astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine the additional properties and behaviour of a SkyFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The SkyFrame Model} A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a SkyFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a SkyFrame represents a 2-dimensional \emph{spherical} coordinate system, in which the shortest distance between two points is a great circle. A SkyFrame therefore always has exactly two axes which represent the longitude and latitude of a coordinate system residing on the celestial sphere. Many such coordinate systems can be represented by a SkyFrame, as we will see shortly. A SkyFrame can represent any of the commonly used celestial coordinate systems. Optionally, the origin of the longitude/latitude system can be moved to any specified point in the standard celestial system, allowing a SkyFrame to represent offsets from a specified sky position. When it is first created, a SkyFrame's axes are always in the order (longitude,~latitude) but this can be changed, if required, by using the \htmlref{AST\_PERMAXES}{AST\_PERMAXES} routine (\secref{ss:permutingaxes}). The order of the axes can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A SkyFrame's coordinate values are always stored as angles in (double precision) radians, regardless of the setting of the Unit attribute \footnote{The units used for the internal floating-point representation of an axis value can be determined by examining the InternalUnit attribute of the Frame. For most Frames, the Unit and InternalUnit attributes will be equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}. \subsection{Creating a SkyFrame} The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a SkyFrame with default attributes is created as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER SKYFRAME, STATUS STATUS = 0 ... SKYFRAME = AST_SKYFRAME( ' ', STATUS ) \end{terminalv} \normalsize Such a SkyFrame would represent the default celestial coordinate system which, at present, is the ICRS system (the default was "FK5(J2000)" in versions of AST prior to 3.0). \subsection{Specifying a Particular Celestial Coordinate System} For many purposes, the ICRS coordinate system is perfectly adequate. In order to support conversion between a variety of celestial coordinate systems, however, you can create SkyFrames that represent any of these. Selection of a particular coordinate system is performed simply by setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System} attribute. This setting is most conveniently done when the SkyFrame is created. For example, a SkyFrame representing the old FK4~(B1950.0) coordinate system would be created by: \small \begin{terminalv} SKYFRAME = AST_SKYFRAME( 'System=FK4', STATUS ) \end{terminalv} \normalsize Note that specifying ``System$=$FK4'' also changes the associated equinox (from J2000.0 to B1950.0). This is because the default value of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions} and include a variety of equatorial coordinate systems, together with ecliptic and galactic coordinates. General spherical coordinates are supported by specifying ``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be created to convert between ``unknown'' coordinates and any of the other celestial coordinate systems (see \secref{ss:introducingconversion} ). \subsection{Attributes which Qualify Celestial Coordinate Systems} Many celestial coordinate systems have some additional free parameters which serve to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, the FK5~(J2010.0) system is distinguished from the FK5~(J2000.0) system by a different equinox---and the coordinates of a fixed astronomical source would have different values when expressed in these two systems. In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main SkyFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\ This attribute is inherited from the Frame class. It gives the moment in time when the coordinates are correct for the astronomical source under study (usually the date of observation). \item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\ This value is used to qualify celestial coordinate systems that are notionally based on the Earth's equator and/or the ecliptic (the plane of the Earth's orbit around the Sun). The position of either of these planes is difficult to specify precisely, so in practice a model \emph{mean} equator and/or ecliptic are used instead. These, together with the point on the sky that defines the coordinate origin (termed the \emph{mean equinox}) move with time according to some model which smoothes out the more rapid fluctuations. The SkyFrame class supports both the old FK4 model and the newer FK5 one. Coordinates expressed in any of these systems vary with time due to movement (by definition) of the coordinate system itself, and must therefore be qualified by a moment in time (the \emph{epoch of the mean equinox}, or ``equinox'' for short) which specifies the position of the model coordinate system on the sky. This is the role of the Equinox attribute. Note that it is quite valid and common to relate the position of a source to an equinox other than the date of observation. Usually a standard equinox such as J2000.0 is used, meaning that the coordinates are referred to axes defined by where the model mean equator and ecliptic would lie on the sky at the Julian epoch J2000.0. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). For the interested reader, an excellent overview of celestial coordinate systems can also be found in the documentation for the SLALIB library (\xref{SUN/67}{sun67}{}). The value of these qualifying attributes is most conveniently set at the same time as the System value, \emph{e.g.}\ when a SkyFrame is created. For instance: \small \begin{terminalv} SKYFRAME = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2005.5', STATUS ) \end{terminalv} \normalsize would create a SkyFrame representing an ecliptic coordinate system referred to the mean equinox and ecliptic of Julian epoch J2005.5. Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System value. Any such values are stored, but are not used unless the System value is later set so that they become relevant. \subsection{Using Default SkyFrame Attributes} The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this means that there is usually little need to specify many of these attributes explicitly unless you have some special requirement. This can be illustrated by using \htmlref{AST\_SHOW}{AST\_SHOW} to examine a SkyFrame, as follows: \small \begin{terminalv} CALL AST_SHOW( AST_SKYFRAME( 'System=FK4-NO-E, Epoch=1958', STATUS ), STATUS ) \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0; epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain Epoch = 1958 # Besselian epoch of observation # Lbl1 = "Right ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 System = "FK4-NO-E" # Coordinate system type # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction # Bot2 = -1.5707963267949 # Lowest legal axis value # Top2 = 1.5707963267949 # Highest legal axis value Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} Note that the defaults (indicated by the ``\verb?#?'' comment character at the start of the line) for attributes such as the \htmlref{Title}{Title}, axis Labels and Format specifiers are all set to values appropriate for the particular equatorial coordinate system that the SkyFrame represents. This means, for example, that if we were to use this SkyFrame to format a right ascension value stored in radians using \htmlref{AST\_FORMAT}{AST\_FORMAT} (\secref{ss:formattingaxisvalues}), it would automatically result in a string in sexagesimal notation (such as ``12:14:35.7'') suitable for display. If we changed the value of the SkyFrame's Digits attribute (which is inherited from the \htmlref{Frame}{Frame} class), the number of digits appearing would also change accordingly. These choices would be appropriate for a System value of ``FK4-NO-E'', but if a different System value were set, the defaults would be correspondingly different. For example, ecliptic longitude is traditionally expressed in degrees, so setting ``System=ecliptic'' would result in coordinate values being formatted as degrees by default. Of course, if you do not like any of these defaults, you may always over-ride them by setting explicit attribute values yourself. \subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates} SkyFrames use \htmlref{AST\_FORMAT}{AST\_FORMAT} for formatting coordinate values in the same way as other Frames (\secref{ss:formattingaxisvalues}). However, they offer a different set of formatting options more appropriate to celestial coordinates. The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the precision with which celestial coordinates are displayed can also be adjusted in this way. However, the range of format specifiers that can be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format resulting from any particular Digits value, is different. The syntax of SkyFrame format specifiers is detailed under the description of the Format(axis) attribute in \appref{ss:attributedescriptions}. Briefly, however, it allows celestial coordinates to be expressed either as angles or times and to include one or more of the fields: \begin{quote} \begin{itemize} \item degrees or hours \item arc-minutes or minutes \item arc-seconds or seconds \end{itemize} \end{quote} with a specified number of decimal places for the final field. A range of field separators is also available, as the following examples show: \begin{quote} \begin{center} \begin{tabular}{|l|l|} \hline \textbf{Format Specifier} & \textbf{Example Formatted Value}\\ \hline \hline {\tt{d}} & {\tt{219}}\\ {\tt{d.3}} & {\tt{219.123}}\\ {\tt{dm}} & {\tt{219:05}}\\ {\tt{dm.2}} & {\tt{219:05.44}}\\ {\tt{dms}} & {\tt{219:05:42}}\\ {\tt{hms.1}} & {\tt{15:44:13.8}}\\ {\tt{bdms.2}} & {\tt{219 05 42.81}}\\ {\tt{lhms.3}} & {\tt{15h44m13.88s}}\\ {\tt{+zlhms}} & {\tt{+06h10m44s}}\\ {\tt{ms.1}} & {\tt{13145:42.8}}\\ {\tt{lmst.3}} & {\tt{876m22.854s}}\\ {\tt{s.2}} & {\tt{788742.81}}\\ \hline \end{tabular} \end{center} \end{quote} Note the following key points: \begin{itemize} \item The required fields are specified using characters chosen from either ``dms'' or ``hms'' according to whether the value is to be formatted as an angle (in degrees) or a time (in hours). \item If no degrees or hours field is required, the distinction between angle and time may be made by including ``t'' to request time. \item The number of decimal places (for the final field) is indicated using ``\texttt{.}'' followed by an integer. An asterisk can be used in place of an integer, in which case the number of decimal places is chosen so that the total number of digits in the formatted value is equal to the value of the Digits attribute. \item ``b'' causes fields to be separated by blanks, while ``l'' causes them to be separated by the appropriate letters (the default being a colon). \item ``z'' causes padding with leading zeros. \item ``+'' cause a plus sign to be prefixed to positive values (negative values always have a minus sign). \end{itemize} The formatting performed by a SkyFrame is also influenced by the \htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each SkyFrame axis. It determines whether the default format specifier for an axis will present values as angles (\emph{e.g.}\ in degrees) if it is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero. The default AsTime value depends on the celestial coordinate system which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System} attribute value. For example, equatorial longitude values (right ascension) are normally expressed in hours, whereas ecliptic longitudes are normally expressed in degrees, so their default AsTime values will reflect this difference. The value of the AsTime attribute may be set explicitly to over-ride these defaults if required, with the formatting precision being determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the Format(axis) attribute may be set explicitly to specify both the format and precision required. Setting an explicit Format value always over-rides the effects of both the Digits and AsTime attributes (unless the Format value does not specify the required number of decimal places, in which case Digits is used to determine the default number of decimal places) \subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates} The process of converting formatted celestial coordinates, such as might be produced by the \htmlref{AST\_FORMAT}{AST\_FORMAT} function (\secref{ss:formattingskyaxisvalues}), into numerical (double precision) coordinate values is performed by using \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT} (\secref{ss:unformattingaxisvalues}) and passing it a pointer to a \htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats accepted is appropriate to positions on the sky expressed as angles and/or times, while the returned value is in radians. The following describes the forms of celestial coordinate which are supported: \begin{itemize} \item You may supply an optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03''). \item Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (\emph{e.g.}\ decimal degrees might be given as ``124.707'', while degrees and decimal arc-minutes might be given as ``$-$13~33.8''). \item The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (\emph{e.g.} ``720~45~31'' is valid, whereas ``11~45~61'' is not). \item Fields may be separated by white space or by ``:'' (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1''). \item The following field identification characters may be used as separators to replace those above (or may be appended to the final field), in order to identify the field to which they are appended: \begin{quote} \begin{tabular}{lll} d & -- & degrees \\ h & -- & hours \\ m & -- & minutes (of arc or time) \\ s & -- & seconds (of arc or time) \\ \texttt{'} & -- & arc-minutes \\ \texttt{"} & -- & arc-seconds \end{tabular} \end{quote} Either lower or upper case may be used. Fields must be given in order of decreasing significance (\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s''). \item The presence of certain field identification characters indicates whether the value is to be interpreted as an angle or a time (with 24 hours corresponding to 360 degrees), as follows: \begin{quote} \begin{tabular}{lll} d & -- & angle \\ \texttt{'} & -- & angle \\ \texttt{"} & -- & angle \\ h & -- & time \end{tabular} \end{quote} Incompatible angle/time identification characters may not be mixed (\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either. \item If no preference for an angle or a time is expressed anywhere within the value, then it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by AST\_FORMAT (\secref{ss:formattingskyaxisvalues}) are correctly interpreted by AST\_UNFORMAT. \item Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters. For example: \begin{quote} \begin{tabular}{lll} 10d & -- & degrees \\ 10d12 & -- & degrees and arc-minutes \\ 11:14\texttt{"} & -- & arc-minutes and arc-seconds \\ 9h13s & -- & hours and seconds of time \\ :45:33 & -- & minutes and seconds (of arc or time) \\ :55: & -- & minutes (of arc or time) \\ ::13 & -- & seconds (of arc or time) \\ $-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\ 07m14 & -- & minutes and seconds (of arc or time) \\ $-$8:14\texttt{'} & -- & degrees and arc-minutes \\ $-$h3:14 & -- & minutes and seconds of time \\ h:2.1 & -- & seconds of time \end{tabular} \end{quote} \item If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. ``01:02''), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that AST\_FORMAT would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that AST\_FORMAT would produce. \end{itemize} This final convention is intended to ensure that values formatted by AST\_FORMAT which contain less than three fields will be correctly interpreted if read back using AST\_UNFORMAT, even if they do not contain field identification characters. However, it also affects other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set to ``mst.1'' (producing two fields representing minutes and seconds of time), then formatted input would be interpreted by AST\_UNFORMAT as follows: \begin{quote} \begin{tabular}{lll} 12 13 & -- & minutes and seconds \\ 12 & -- & minutes \\ :13 & -- & seconds \\ $-$18: & -- & minutes \\ 12.8 & -- & minutes \\ 1 2 3 & -- & hours, minutes and seconds \\ & & \\ 4\texttt{'} & -- & arc-minutes \\ 60::\texttt{"} & -- & degrees \\ $-$23:\texttt{"} & -- & arc-minutes \\ $-$33h & -- & hours \end{tabular} \end{quote} (in the last four cases, explicit field identification has been given which overrides the implicit identification). Alternatively, if the Format(axis) string were set to ``s.3'' (producing only an arc-seconds field), then formatted input would be interpreted by AST\_UNFORMAT as follows: \begin{quote} \begin{tabular}{lll} 12.8 & -- & arc-seconds \\ 12 13 & -- & arc-minutes and arc-seconds \\ :12 & -- & arc-seconds \\ 13: & -- & arc-minutes \\ 1 2 3 & -- & degrees, arc-minutes and arc-seconds \end{tabular} \end{quote} In general, if you are preparing formatted input data containing celestial coordinates and wish to omit certain fields, then you are advised to identify clearly those that you do provide by using the appropriate field identification characters and/or extra colon separators. This prevents you depending on the implicit field identification described above which, in turn, depends on an appropriate Format(axis) string having been set. When writing software, it is also a good idea to set the Format(axis) string so that data input will be as simple as possible for the user. Unless some special effect is desired, this normally means that it should contain ``d'' or ``h'' to ensure that the first field entered by the user will be interpreted as degrees or hours, unless otherwise identified. This is the normal behaviour unless an explicit Format(axis) value has been set to override the default. \subsection{Representing Offsets from a Specified Sky Position} A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are referred to an origin at any specified sky position. Such a coordinate system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System} attribute should be set to represent the celestial coordinate system in which the origin is to be specified. Then the SkyRef attribute should be set to hold the coordinates of the origin within the selected celestial coordinate system. By default, ``north'' in the new offset coordinate system is parallel to north in the original celestial coordinate system. However, the direction of north in the offset system can be controlled by assigning a value to the SkyRefP attribute. This attribute should be assigned the celestial coordinates of a point which is on the zero longitude meridian and which has non-zero latitude. By default, the position given by the SkyRef attribute is used as the origin of the new longitude/latitude system, but an option exists to use it as the north pole of the system instead. This option is controlled by the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what sort of offset coordinate system you want. Setting SkyRefIs to ``Origin'' (the default) produces an offset coordinate system which is approximately Cartesian close to the specified position. Setting SkyRefIs to ``Pole'' produces an offset coordinate system which is approximately Polar close to the specified position. \cleardoublepage \section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)} The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate systems which describe a position within an electro-magnetic spectrum. In this section we examine the additional properties and behaviour of a SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The SpecFrame Model} As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a SpecFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a SpecFrame represents a wide range of different 1-dimensional coordinate system which can be used to describe positions within a spectrum. The options available largely mirror those described in the FITS-WCS paper III \emph{Representations of spectral coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen). \subsection{Creating a SpecFrame} The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a SpecFrame with default attributes is created as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER SPECFRAME, STATUS STATUS = 0 ... SPECFRAME = AST_SPECFRAME( ' ', STATUS ) \end{terminalv} \normalsize Such a SpecFrame would represent the default coordinate system which is heliocentric wavelength in metres (i.e. wavelength corrected to take into account the Doppler shift caused by the velocity of the observer around the sun). \subsection{Specifying a Particular Spectral Coordinate System} Selection of a particular coordinate system is performed simply by setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System} attribute. This setting is most conveniently done when the SpecFrame is created. For example, a SpecFrame representing Energy would be created by: \small \begin{terminalv} SPECFRAME = AST_SPECFRAME( 'System=Energy', STATUS ) \end{terminalv} \normalsize Note that specifying ``System$=$Energy'' also changes the associated Unit (from metres to Joules). This is because the default value of the SpecFrame's Unit attribute depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions} and include a variety of velocity systems, together with frequency, wavelength, energy, wave-number, \emph{etc}. \subsection{Attributes which Qualify Spectral Coordinate Systems} Many spectral coordinate systems have some additional free parameters which serve to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, the velocity systems are all parameterised by a rest frequency---the frequency which defines zero velocity, and all coordinate systems are qualified by a `standard of rest'' which indicates the rest frame to which the values refer. In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main SpecFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\htmlref{Epoch}{Epoch}]\mbox{}\\ This attribute is inherited from the Frame class. It gives the moment in time when the coordinates are correct for the astronomical source under study (usually the date of observation). It is needed in order to calculate the Doppler shift produced by the velocity of the observer relative to the centre of the earth, and of the earth relative to the sun. \item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\ This specifies the rest frame in which the coordinates are correct. Transforming between different standards of rest involves taking account of the Doppler shift introduced by the relative motion of the two standards of rest. \item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\ Specifies the frequency which correspond to zero velocity. When setting a value for this attribute, the value may be supplied as a wavelength (including an indication of the units being used, ``nm'' ``Angstrom'', \emph{etc.}), which will be automatically be converted to a frequency. \item[\htmlref{RefRA}{RefRA}]\mbox{}\\ Specifies the RA (FK5 J2000) of the source. This is used when converting between standards of rest. It specifies the direction along which the component of the relative velocity of the two standards of rest is taken. \item[\htmlref{RefDec}{RefDec}]\mbox{}\\ Specifies the Dec (FK5 J2000) of the source. Used in conjunction with REFRA. \item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\ This defines the ``source'' standard of rest. This is a rest frame which is moving towards the position given by RefRA and RefDec, at a velocity given by SourceVel. The velocity is stored internally as a heliocentric velocity, but can be given in any of the other supported standards of rest. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System value. Any such values are stored, but are not used unless the System value is later set so that they become relevant. \subsection{Using Default SpecFrame Attributes} The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this means that there is usually little need to specify many of these attributes explicitly unless you have some special requirement. This can be illustrated by using \htmlref{AST\_SHOW}{AST\_SHOW} to examine a SpecFrame, as follows: \small \begin{terminalv} CALL AST_SHOW( AST_SPECFRAME( 'System=Vopt, RestFreq=250 GHz', STATUS ), : STATUS ) \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} Begin SpecFrame # Description of spectral coordinate system # Title = "Optical velocity, rest frequency = 250 GHz" # Title of coordinate system Naxes = 1 # Number of coordinate axes # Domain = "SPECTRUM" # Coordinate system domain # Epoch = 2000 # Julian epoch of observation # Lbl1 = "Optical velocity" # Label for axis 1 System = "VOPT" # Coordinate system type # Uni1 = "km/s" # Units for axis 1 Ax1 = # Axis number 1 Begin Axis # Coordinate axis End Axis IsA Frame # Coordinate system description # SoR = "Heliocentric" # Standard of rest RstFrq = 250000000000 # Rest frequency (Hz) End SpecFrame \end{terminalv} Note that the defaults (indicated by the ``\verb?#?'' comment character at the start of the line) for attributes such as the \htmlref{Title}{Title}, axis Labels and Unit specifiers are all set to values appropriate for the particular velocity system that the SpecFrame represents. These choices would be appropriate for a System value of ``Vopt'', but if a different System value were set, the defaults would be correspondingly different. For example, by default frequency is measured in units of GHz, not $km/s$, so setting ``System=freq'' would change the appropriate line above from: \begin{terminalv} # Uni1 = "km/s" # Units for axis 1 \end{terminalv} to \begin{terminalv} # Uni1 = "GHz" # Units for axis 1 \end{terminalv} Of course, if you do not like any of these defaults, you may always over-ride them by setting explicit attribute values yourself. For instance, you may choose to have your frequency axis expressed in ``kHz'' rather than ``GHz''. To do this simply set the attribute value as follows: \small \begin{terminalv} CALL AST_SETC( SPECFRAME, 'Unit', 'kHz', STATUS ) \end{terminalv} \normalsize No error will be reported if you accidentally set an inappropriate Unit value (say "J" - Joules)---after all, AST cannot tell what you are about to do, and you \emph{may} be about to change the System value to ``Energy''. However, an error \emph{will} be reported if you attempt to find a conversion between two SpecFrames (for instance using \htmlref{AST\_CONVERT}{AST\_CONVERT} ) if either SpecFrame has a Unit value which is inappropriate for its System value. SpecFrame attributes, like all other attributes, all have default value. However, be aware that for some attributes these default values can never be more than ``a legal numerical value'' and have no astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes (which give the source position) both have a default value of zero. So unless your source happens to be at that point (highly unlikely!) you will need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute has an arbitrary default value of 1.0E5 GHz. Some operations are not affected by inappropriate values for these attributes (for instance, converting from frequency to wavelength, changing axis units, \emph{etc}), but some are. For instance, converting from frequency to velocity requires a correct rest frequency, moving between different standards of rest requires a correct source position. The moral is, always set explicit values for as many attributes as possible. \subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes} You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube containing two spatial axes and a spectral axis. To do this you would create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame} (often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}. \small \begin{terminalv} INTEGER SKYFRAME INTEGER SPECFRAME INTEGER CMPFRAME ... SKYFRAME = AST_SKYFRAME( 'Epoch=J2002', STATUS ) SPECFRAME = AST_SPECFRAME( 'System=Freq,StdOfRest=LSRK', : STATUS ) CMPFRAME = AST_CMPFRAME( SKYFRAME, SPECFRAME, ' ', STATUS ) \end{terminalv} \normalsize In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis 3 will be Frequency. If this is not the order you want, you can permute the axes using \htmlref{AST\_PERMAXES}{AST\_PERMAXES}. There is one potential problem with this approach if you are interested in unusually high accuracy. Conversion between different standards of rest involves taking account of the Doppler shift caused by the relative motion of the two standards of rest. At some point this involves finding the component of the relative velocity in the direction of interest. For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, even if the SpecFrame is embedded within a CmpFrame as above. It would be more appropriate if this ``direction of interest'' was specified by the values passed into the CmpFrame on the RA and DEC axes, allowing each pixel within a data cube to have a slightly different correction for Doppler shift. Unfortunately, the SpecFrame class cannot do this (since it is purely a 1-dimensional Frame), and so some small degree of error will be introduced when converting between standards of rest, the size of the error varying from pixel to pixel. It is hoped that at some point in the future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which allows for this spatial variation in Doppler shift. The maximum velocity error introduced by this problem is of the order of $V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of $V$ is about 20 $km/s$, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 $km/s$. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 $km/s$ over a 1 degree field of view. \subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra} Dual sideband super-heterodyne receivers produce spectra in which each channel contains contributions from two different frequencies, referred to as the ``upper sideband frequency'' and the ``lower sideband frequency''. In the rest frame of the observer (topocentric), these are related to each other as follows: \begin{quote} \begin{small} \begin{equation} \label{eqn:dsb} f_{lsb} = 2.f_{LO} - f_{usb} \end{equation} \end{small} \end{quote} where $f_{LO}$ is a fixed frequency known as the ``local oscillator frequency''. In other words, the local oscillator frequency is always mid-way between any pair of corresponding upper and lower sideband frequencies\footnote{Note, this simple relationship only applies if all frequencies are topocentric.}. If you want to describe the spectral axis of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot describe both sidebands simultaneously. However, there is a sub-class of SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty. A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the DSBSpecFrame is currently being used to describe the upper or lower sideband spectral axis. The value of this attribute can be changed at any time. If you use the \htmlref{AST\_CONVERT}{AST\_CONVERT} function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for the two SideBand attributes will be taken into account. Thus, if you take a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use AST\_CONVERT to find a Mapping from the original to the modified copy, the resulting Mapping will be of the form of equation \ref{eqn:dsb} (if the DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric''). In general, when finding a Mapping between two arbitrary DSBSpecFrames, the total Mapping is made of of three parts in series: \begin{enumerate} \item A Mapping which converts the first DSBSpecFrame into its upper sideband representation. If the DSBSpecFrame already represents its upper sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}. \item A Mapping which converts from the first to the second DSBSpecFrame, treating them as if they were both basic SpecFrames. This takes account of any difference in units, standard of rest, system, \emph{etc} between the two DSBSpecFrames. \item A Mapping which converts the second DSBSpecFrame from its upper sideband representation to its current sideband. If the DSBSpecFrame currently represents its upper sideband, this Mapping will be a UnitMap. \end{enumerate} If an attempt is made to find the Mapping between a DSBSpecFrame and a basic SpecFrame, then the DSBSpecFrame will be treated like a basic SpecFrame. In other words, the returned Mapping will not be affected by the setting of the SideBand attribute (or any of the other attributes specific to the DSBSpecFrame class). In practice, the local oscillator frequency for a dual sideband instrument may not be easily available to an observer. Instead, it is common practice to specify the spectral position of some central feature in the observation (commonly the centre of the instrument passband), together with an ``intermediate frequency''. Together, these two values allow the local oscillator frequency to be determined. The intermediate frequency is the difference between the topocentric frequency at the central spectral position and the topocentric frequency of the local oscillator. So: \begin{quote} \begin{small} \begin{equation} \label{eqn:dsb2} f_{LO} = f_{central} + f_{if} \end{equation} \end{small} \end{quote} The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the intermediate frequency ($f_{if}$). The DSBCentre value is given and returned in the spectral system described by the DSBSpecFrame (thus you do not need to calculate the corresponding topocentric frequency yourself - this will be done automatically by the DSBSpecFrame when you assign a new value to the DSBCentre attribute). The value assigned to the IF attribute should always be a topocentric frequency in units of Hz, however a negative value may be given to indicate that the DSBCentre value is in the upper sideband (that is, if $IF < 0$ then $f_{central} > f_{LO}$). A positive value for IF indicates that the DSBCentre value is in the lower sideband (that is, if $IF > 0$ then $f_{central} < f_{LO}$). \cleardoublepage \section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)} The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in time. In this section we examine the additional properties and behaviour of a TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The TimeFrame Model} As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a TimeFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a TimeFrame represents a wide range of different 1-dimensional coordinate system which can be used to describe moments in time. Absolute times and relative (i.e. elapsed) times are supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales (attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch}, \emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to allow them to be used with any unit of time (attribute Unit). The TimeFrame class also allows times to formatted as either a simple floating point value or as a Gregorian date and time of day (attribute Format). \subsection{Creating a TimeFrame} The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a TimeFrame with default attributes is created as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER TIMEFRAME, STATUS STATUS = 0 ... TIMEFRAME = AST_TIMEFRAME( ' ', STATUS ) \end{terminalv} \normalsize Such a TimeFrame would represent the default coordinate system which is Modified Julian Date (with the usual units of days) in the International Atomic Time (TAI) time scale. \subsection{Specifying a Particular Time System} By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}). Selection of a particular coordinate system is performed simply by setting a value for the TimeFrame's (character string) System attribute. This setting is most conveniently done when the TimeFrame is created. For example, a TimeFrame representing Julian Epoch would be created by: \small \begin{terminalv} TIMEFRAME = AST_TIMEFRAME( 'System=JEPOCH', STATUS ) \end{terminalv} \normalsize Note that specifying ``System$=$JEPOCH'' also changes the associated default Unit (from days to years). This is because the default value of the TimeFrame's Unit attribute depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions}. \subsection{Attributes which Qualify Time Coordinate Systems} Time coordinate systems require some additional free parameters to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, all TimeFrames are qualified by the time scale (that is, the physical process used to define the flow of time), and some require the position of the observer's clock. In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main TimeFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\ This specifies the time scale. \item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\ This specifies the offset from Local Time to UTC in hours (time zones east of Greenwich have positive values). Note, AST uses the value as supplied without making any correction for daylight saving. \item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\ This specifies the zero point from which time values are measured, within the system specified by the System attribute. Thus, a value of zero (the default) indicates that time values represent absolute times. Non-zero values may be used to indicate that the TimeFrame represents elapsed time since the specified origin. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System or TimeScale value. Any such values are stored, but are not used unless the System and/or TimeScale value is later set so that they become relevant. \cleardoublepage \section{\label{ss:cmpframes}Compound Frames (CmpFrames)} We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The Frames we have considered so far have been atomic, in the sense that they represent pre-defined elementary physical domains. A CmpFrame, however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for containing other Frames and its purpose is to allow those Frames to work together in various combinations while appearing as a single \htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is determined by the other Frames it contains (its ``component'' Frames). As with compound Mappings, compound Frames can be nested within each other, forming arbitrarily complex Frames. \subsection{Creating a CmpFrame} A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a ``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes represents position within a spectrum, and the other two axes represent position on the sky (or some other spatial domain such as the focal plane of a telescope). As an example, we create such a CmpFrame in which axes 1 and 2 represent Right Ascension and Declination (ICRS), and axis 3 represents wavelength (these are the default coordinate Systems represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively): \small \begin{terminalv} INTEGER SKYFRAME INTEGER SPECFRAME INTEGER CMPFRAME ... SKYFRAME = AST_SKYFRAME( ' ', STATUS ) SPECFRAME = AST_SPECFRAME( ' ', STATUS ) CMPFRAME = AST_CMPFRAME( SKYFRAME, SPECFRAME, ' ', STATUS ) \end{terminalv} \normalsize If it was desired to make RA and Dec correspond to axes 1 and 3, with axis 2 being the spectral axis, then the axes of the CmpFrame created above would need to be permuted as follows: \small \begin{terminalv} INTEGER PERM(3) ... PERM( 1 ) = 1 PERM( 2 ) = 3 PERM( 3 ) = 2 CALL AST_PERMAXES( CMPFRAME, PERM, STATUS ) \end{terminalv} \normalsize \subsection{The Attributes of a CmpFrame} A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame. The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by concatenating the Domains of the two component Frames, separated by a minus sign (``-'').\footnote{If both component Frames have blank Domains, then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed) value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to change the System value of a CmpFrame is ignored.} A CmpFrame has no further attributes over and above those common to all Frames. However, attributes of the two component Frames can be accessed as if they were attributes of the CmpFrame, as described below. Frame attributes which are specific to individual axes (such as Label(2), Format(1), \emph{etc}) simply mirror the corresponding axes of the relevant component Frame. That is, if the ``Label(2)'' attribute of a CmpFrame is accessed, the CmpFrame will forward the access request to the component Frame which contains axis 2. Thus, default values for axis attributes will be the same as those provided by the component Frames. An axis index can optionally be appended to the name of Frames attributes which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title}, \emph{etc}). If this is done, the access request is forwarded to the component Frame containing the indicated axis. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes have not been permuted, then getting the value of attribute ``System'' will return ``Compound'' as mentioned above (that is, the System value of the CmpFrame as a whole), whereas getting the value of attribute ``System(1)'' will return ``Spectral''(that is, the System value of the component Frame containing axis 1 --- the SpecFrame). This technique is not limited to attributes common to all Frames. For instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is not held by other classes of Frames. To set a value for the Equinox attribute of the SkyFrame contained within the above CmpFrame, assign the value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame defines both axes 2 and 3 of the CmpFrame, we could equivalently have set a value for ``Equinox(3)'' since this would also result in the attribute access being forwarded to the SkyFrame. Finally, if an attribute is not qualified by a axis index, attempts will be made to access it using each of the CmpFrame axes in turn. Using the above example of the spectral cube, if an attempt was made to get the value of attribute ``Equinox'' (with no axis index), each axis in turn would be used. Since axis 1 is contained within a SpecFrame, the first attempt would fail since the SpecFrame class does not have an Equinox attribute. However, the second attempt would succeed because axis 2 is contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus the returned attribute value would be that obtained from the SkyFrame containing axis 2. When getting or testing an attribute value, the returned value is determined by the \emph{first} axis which recognises the attribute. When setting an attribute value, \emph{all} axes which recognises the attribute have the attribute value set to the given value. Likewise, when clearing an attribute value, all axes which recognises the attribute have the attribute value cleared. \cleardoublepage \section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions} In this section, we start to look at techniques for converting between different coordinate systems. At this stage, the tools we have available are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}), SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and various Mappings (\secref{ss:mappings}). These are sufficient to allow us to begin examining the problem, but more sophisticated approaches will also emerge later (\secref{ss:framesetconverting}). \subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems} We begin by examining how to convert between two celestial coordinate systems represented by SkyFrames, as this is both an illuminating and practical example. Consider the problem of converting celestial coordinates between: \begin{enumerate} \item The old FK4 system, with no E terms, a Besselian epoch of 1958.0 and a Besselian equinox of 1960.0. \item An ecliptic coordinate system based on the mean equinox and ecliptic of Julian epoch 2010.5. \end{enumerate} This example is arbitrary but not completely unrealistic. Unless you already have expertise with such conversions, you are unlikely to find it straightforward. Using AST, we begin by creating two SkyFrames to represent these coordinate systems, as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER SKYFRAME1, SKYFRAME2, STATUS STATUS = 0 ... SKYFRAME1 = AST_SKYFRAME( 'System=FK4-NO-E, Epoch=B1958, Equinox=B1960', STATUS ) SKYFRAME2 = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2010.5', STATUS ) \end{terminalv} \normalsize Note how specifying the coordinate systems consists simply of initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately. The next step is to find a way of converting between these SkyFrames. This is done using \htmlref{AST\_CONVERT}{AST\_CONVERT}, as follows: \small \begin{terminalv} INTEGER CVT ... CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS ) IF ( CVT .EQ. AST__NULL ) THEN ELSE END IF \end{terminalv} \normalsize The third argument of AST\_CONVERT is not used here and should be a blank string. AST\_CONVERT will return a null result, AST\_\_NULL (as defined in the AST\_PAR include file), if conversion is not possible. In this example, conversion is possible, so it will return a pointer to a new \htmlref{Object}{Object} that describes the conversion. The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed FrameSets yet (\secref{ss:framesets}), but for the present purposes we can consider them simply as Objects that can behave both as Mappings and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we are mainly interested here, because the Mapping it implements is the one we require---\emph{i.e.}\ it converts between the two celestial coordinate systems (\secref{ss:framesetsfromconvert}). For example, if ALPHA1 and DELTA1 are two arrays containing the longitude and latitude, in radians, of N points on the sky in the original coordinate system (corresponding to SKYFRAME1), then they could be converted into the new coordinate system (represented by SKYFRAME2) as follows: \small \begin{terminalv} INTEGER N DOUBLE PRECISION ALPHA1( N ), DELTA1( N ) DOUBLE PRECISION ALPHA2( N ), DELTA2( N ) ... CALL AST_TRAN2( CVT, N, ALPHA1, DELTA1, .TRUE., ALPHA2, DELTA2, STATUS ) \end{terminalv} \normalsize The new coordinates are returned \emph{via} the ALPHA2 and DELTA2 arrays. To transform coordinates in the opposite direction, we simply invert the 5th (logical) argument to \htmlref{AST\_TRAN2}{AST\_TRAN2}, as follows: \small \begin{terminalv} CALL AST_TRAN2( CVT, N, ALPHA2, DELTA2, .FALSE., ALPHA1, DELTA1, STATUS ) \end{terminalv} \normalsize The FrameSet returned by AST\_CONVERT also contains information about the SkyFrames used in the conversion (\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the ``destination'' Frame used in the conversion (\emph{i.e.}\ like SKYFRAME2). We could therefore use the CVT FrameSet to calculate the distance between two points (with coordinates in radians) in the destination coordinate system, using \htmlref{AST\_DISTANCE}{AST\_DISTANCE}: \small \begin{terminalv} DOUBLE PRECISION DISTANCE, POINT1( 2 ), POINT2( 2 ) ... DISTANCE = AST_DISTANCE( CVT, POINT1, POINT2, STATUS ) \end{terminalv} \normalsize and the result would be the same as if the SKYFRAME2 SkyFrame had been used. Another way to see how the FrameSet produced by astConvert retains information about the coordinate systems involved is to set its \htmlref{Report}{Report} attribute (inherited from the Mapping class) so that it displays the coordinates before and after conversion (\secref{ss:transforming}): \small \begin{terminalv} CALL AST_SET( CVT, 'Report=1', STATUS ) CALL AST_TRAN2( CVT, N, ALPHA1, DELTA1, .TRUE., ALPHA2, DELTA2, STATUS ) \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} (2:06:03.0, 34:22:39) --> (42.1087, 20.2717) (2:08:20.6, 35:31:24) --> (43.0197, 21.1705) (2:10:38.1, 36:40:09) --> (43.9295, 22.0716) (2:12:55.6, 37:48:55) --> (44.8382, 22.9753) (2:15:13.1, 38:57:40) --> (45.7459, 23.8814) (2:17:30.6, 40:06:25) --> (46.6528, 24.7901) (2:19:48.1, 41:15:11) --> (47.5589, 25.7013) (2:22:05.6, 42:23:56) --> (48.4644, 26.6149) (2:24:23.1, 43:32:41) --> (49.3695, 27.5311) (2:26:40.6, 44:41:27) --> (50.2742, 28.4499) \end{terminalv} Here, we see that the input FK4 equatorial coordinate values (given in radians) have been formatted automatically in sexagesimal notation using the conventional hours for right ascension and degrees for declination. Conversely, the output ecliptic coordinates are shown in decimal degrees, as is conventional for ecliptic coordinates. Both are displayed using the default precision of 7 digits.\footnote{The leading digit is zero and is therefore not seen in this particular example.} In fact, the CVT FrameSet has access to all the information in the original SkyFrames which were passed to AST\_CONVERT. If you had set a new Digits attribute value for either of these, the formatting above would reflect the different precision you requested by displaying a greater or smaller number of digits. \subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems} The principles described in the previous section for converting between celestial coordinate systems also apply to the task of converting between spectral coordinate systems. As an example, let's look at how we might convert between frequency measured in $GHz$ as measured in the rest frame of the telescope, and radio velocity measured in $km/s$ measured with respect the kinematic Local Standard of Rest. First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to describe the required radio velocity system (this is slightly more convenient, given the relatively large number of attributes, than specifying the attribute values in a single string such as would be passed to the SpecFrame constructor). We then take a copy of this SpecFrame, and change the attribute values so that the copy describes the original frequency system (modifying a copy, rather than creating a new SpecFrame from scratch, avoids the need to specify the epoch, reference position, \emph{etc} a second time since they are all inherited by the copy): \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER SPECFRAME1, SPECFRAME2, STATUS STATUS = 0 ... SPECFRAME1 = AST_SPECFRAME( ' ', STATUS ) CALL AST_SETC( SPECFRAME1, 'System=vradio', STATUS ) CALL AST_SETC( SPECFRAME1, 'Unit=km/s', STATUS ) CALL AST_SETC( SPECFRAME1, 'Epoch=1996-Oct-2 12:13:56.985', : STATUS ) CALL AST_SETC( SPECFRAME1, 'ObsLon=W155:28:18', STATUS ) CALL AST_SETC( SPECFRAME1, 'ObsLat=N19:49:34', STATUS ) CALL AST_SETC( SPECFRAME1, 'RefRA=18:14:50.6', STATUS ) CALL AST_SETC( SPECFRAME1, 'RefDec=-4:40:49', STATUS ) CALL AST_SETC( SPECFRAME1, 'RestFreq=230.538 GHz', STATUS ) CALL AST_SETC( SPECFRAME1, 'StdOfRest=LSRK', STATUS ) SPECFRAME2 = AST_COPY( SPECFRAME1, STATUS ) CALL AST_SETC( SPECFRAME1, 'System=freq', STATUS ) CALL AST_SETC( SPECFRAME1, 'Unit=GHz', STATUS ) CALL AST_SETC( SPECFRAME1, 'StdOfRest=Topocentric', STATUS ) \end{terminalv} \normalsize Note, the fact that a SpecFrame has only a single axis means that we were able to refer to the Unit attribute without an axis index. The other attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the standard of rest (\htmlref{StdOfRest}{StdOfRest}). The next step is to find a way of converting between these SpecFrames. We use exactly the same code that we did in the previous section where we were converting between celestial coordinate systems: \small \begin{terminalv} INTEGER CVT ... CVT = AST_CONVERT( SPECFRAME1, SPECFRAME2, ' ', STATUS ) IF ( CVT .EQ. AST__NULL ) THEN ELSE END IF \end{terminalv} \normalsize A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible, which should always be the case for our example), and we can use the FrameSet to convert between the two spectral coordinate systems. We use \htmlref{AST\_TRAN1}{AST\_TRAN1} in place of \htmlref{AST\_TRAN2}{AST\_TRAN2} since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two). For example, if FRQ is an array containing the observed frequency, in GHz, of N spectral channels (describe by SPECFRAME1), then they could be converted into the new coordinate system (represented by SPECFRAME2) as follows: \small \begin{terminalv} INTEGER N DOUBLE PRECISION FRQ( N ) DOUBLE PRECISION VEL( N ) ... CALL AST_TRAN1( CVT, N, FRQ, .TRUE., VEL, STATUS ) \end{terminalv} \normalsize The radio velocity values are returned in the VEL array. \subsection{Converting between Time Coordinate Systems} All the principles outlined in the previous section about aligning spectral cocordinate systems (SpecFrames) can be applied directly to the problem of aligning time coordinate systems (TimeFrames). \subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations} We can illustrate an important point if we swap the axis order of either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes}) before identifying the conversion. Let's assume we use \htmlref{AST\_PERMAXES}{AST\_PERMAXES} (\secref{ss:permutingaxes}) to do this to the second SkyFrame, before applying \htmlref{AST\_CONVERT}{AST\_CONVERT}, as follows: \small \begin{terminalv} INTEGER PERM( 2 ) DATA PERM / 2, 1 / ... CALL AST_PERMAXES( SKYFRAME2, PERM, STATUS ) CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS ) \end{terminalv} \normalsize Now, the destination SkyFrame system no longer represents the coordinate system: \begin{quote} (ecliptic~longitude, ecliptic~latitude) \end{quote} but instead represents the transposed system: \begin{quote} (ecliptic~latitude, ecliptic~longitude) \end{quote} As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by AST\_CONVERT to apply a coordinate transformation, we obtain something like the following: \begin{terminalv} (2:06:03.0, 34:22:39) --> (20.2717, 42.1087) (2:08:20.6, 35:31:24) --> (21.1705, 43.0197) (2:10:38.1, 36:40:09) --> (22.0716, 43.9295) (2:12:55.6, 37:48:55) --> (22.9753, 44.8382) (2:15:13.1, 38:57:40) --> (23.8814, 45.7459) (2:17:30.6, 40:06:25) --> (24.7901, 46.6528) (2:19:48.1, 41:15:11) --> (25.7013, 47.5589) (2:22:05.6, 42:23:56) --> (26.6149, 48.4644) (2:24:23.1, 43:32:41) --> (27.5311, 49.3695) (2:26:40.6, 44:41:27) --> (28.4499, 50.2742) \end{terminalv} When compared to the original (\secref{ss:convertingskyframes}), the output coordinate order has been swapped to compensate for the different destination SkyFrame axis order. In all, there are four possible axis combinations, corresponding to two possible axis orders for each of the source and destination SkyFrames, and AST\_CONVERT will convert correctly between any of these. The point to note is that a SkyFrame contains knowledge about how to convert to and from other SkyFrames. Since its two axes (longitude and latitude) are distinguishable, the conversion is able to take account of the axis order. If you need to identify the axes of a SkyFrame explicitly, taking into account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be used. These are read-only attributes which give the indices of the latitude and longitude axes respectively. \subsection{\label{ss:convertingframes}Converting Between Frames} Having seen how clever SkyFrames are (\secref{ss:convertingskyframes} and \secref{ss:convertingpermutedaxes}), we will next examine how dumb a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two 2-dimensional Frames and use \htmlref{AST\_CONVERT}{AST\_CONVERT} to derive a conversion between them, as follows: \small \begin{terminalv} INTEGER FRAME1, FRAME2 ... FRAME1 = AST_FRAME( 2, ' ', STATUS ) FRAME2 = AST_FRAME( 2, ' ', STATUS ) CVT = AST_CONVERT( FRAME1, FRAME2, ' ', STATUS ) \end{terminalv} \normalsize then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs will be as follows: \begin{terminalv} (1, 2) --> (1, 2) (2, 4) --> (2, 4) (3, 6) --> (3, 6) (4, 8) --> (4, 8) (5, 10) --> (5, 10) \end{terminalv} This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap} (\secref{ss:unitmapexample}). Even if we permute the axis order of our Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will fare no better. The conversion between our two basic Frames will always be an identity transformation. The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start life the same and have axes that are indistinguishable. Therefore, permuting their axes doesn't make them look any different---they still represent the same coordinate system. %Actually, this behaviour isn't as dumb as it seems and can actually be %very useful, as the following example illustrates. % %\subsection{Distinguishable and Indistinguishable Axes} % %c+ %Imagine you have two Frames which represent the pixel coordinates of %two 2-dimensional images. Let's call their axes ``X'' and ``Y''. %Suppose you now transpose the second image and swap its Frame axes %(with astPermAxes) to take account of this. %c- %f+ %Imagine you have two Frames which represent the pixel coordinates of %two 2-dimensional images. Let's call their axes ``X'' and ``Y''. %Suppose you now transpose the second image and swap its Frame axes %(with astPermAxes) to take account of this. %f- % %Next, consider what happens if you want to subtract one image from the %other. If you have a ``subtract'' program that is intelligent and %tries to align the two images for you, one of two things could happen: % %\begin{enumerate} %c+ %\item If the axes are distinguishable, when your program invokes %astConvert it will derive a transformation between the two images %which swaps the X and Y coordinates (corresponding to the transposition %you applied to the second image). However, in aligning X-with-X and %Y-with-Y, this will completely undo the effects of your transposition! %c- %f+ %\item If the axes are distinguishable, when your program invokes %AST\_CONVERT it will derive a transformation between the two images %which swaps the X and Y coordinates (corresponding to the transposition %you applied to the second image). However, in aligning X-with-X and %Y-with-Y, this will completely undo the effects of your transposition! %f- % %\item If the axes are indistinguishable, the transformation between %the two images will always be an identity %(\secref{ss:convertingframes}). Therefore, your program will align %X-with-Y and Y-with-X, so that you see the effects of your earlier %transposition of the second image. %\end{enumerate} % %Clearly, if we are considering pixel coordinates, the latter behaviour %is preferable, since there would be no point in implementing an image %transposition program if we could never see the effects of it. This %indicates that a basic Frame, with is indistinguishable axes, is the %correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where %this behaviour is necessary. % %Conversely, the former behaviour would be more useful if the axes we %were considering were, say, wavelength (in nm) and slit position (in %mm). In this case, we would expect our ``subtract'' program to %subtract data at corresponding wavelengths and slit positions, not %just at corresponding pixels. This case requires distinguishable axes, %so that corresponding axes in the two images can be matched up, just %as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}). % %Of course, there may also be intermediate cases, where some axes are %distinguishable and others aren't. \subsection{\label{ss:alignmentsystem}The Choice of Alignment System} In practice, when AST is asked to find a conversion between two Frames describing two different coordinate systems on a given physical domain, it uses an intermediate ``alignment'' system. Thus, when finding a conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from system A to some alignment system, system C, and then finds the Mapping from this system C to the required system B. It finally concatenates these two Mappings to get the Mapping from system A to system B. One advantage of this is that it cuts down the number of conversion algorithms required. If there are $N$ different Systems which may be used to describe positions within the \htmlref{Domain}{Domain}, then this approach requires about $2*N$ conversion algorithms to be written. The alternative approach of going directly from system A to system B would require about $N*N$ conversion algorithms. In addition, the use of an intermediate alignment system highlights the nature of the conversion process. What do we mean by saying that a Mapping ``converts a position in one coordinate system into the corresponding position in another''? In practice, it means that the input and output coordinates correspond to the same coordinates \emph{in some third coordinate system}. The choice of this third coordinate system, the ``alignment'' system, can completely alter the nature of the Mapping. The \htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to specify the alignment system. As an example, consider the case of aligning two spectra calibrated in radio velocity, but each with a different rest frequency (each spectrum will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a given velocity will correspond to different frequencies in the two spectra. So when we come to ``align'' these two spectra (that is, find a Mapping which converts positions in one SpecFrame to the corresponding positions in the other), we have the choice of aligning the frequencies or aligning the velocities. Different Mappings will be required to describe these two forms of alignment. If we set AlignSystem to ``Freq'' then the returned Mapping will align the frequencies described by the two SpecFrames. On the other hand, if we set AlignSystem to ``Vradio'' then the returned Mapping will align the velocities. Some choices of alignment system are redundant. For instance, in the above example, changing the alignment system from frequency to wavelength has no effect on the returned Mapping: if two spectra are aligned in frequency they will also be aligned in wavelength (assuming the speed of light doesn't change). The default value for AlignSystem depends on the class of Frame. For a SpecFrame, the default is wavelength (or equivalently, frequency) since this is the system in which observations are usually made. The SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which allows the standard of rest of the alignment system to be specified. Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale} which allows the time scale of the alignment system to be specified. Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since this is a close approximation to an inertial frame of rest. \cleardoublepage \section{\label{ss:framesets}Coordinate System Networks (FrameSets)} We saw in \secref{ss:introducingconversion} how \htmlref{AST\_CONVERT}{AST\_CONVERT} could be used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems represented by Frames. There is a limitation to this, however, in that it can only be applied to coordinate systems that are inter-related by suitable conventions. In the case of celestial coordinates, the relevant conventions are standards set out by the International Astronomical Union, and others, that define what these coordinate systems mean. In practice, however, the relationships between many other coordinate systems are also of practical importance. Consider, for example, the focal plane of a telescope upon which an image of the sky is falling. We could measure positions in this focal plane in millimetres or, if there were a detector system such as a CCD present, we could count pixels. We could also use celestial coordinates of many different kinds. All of these systems are equivalent in their effectiveness at specifying positions in the focal plane, but some are more convenient than others for particular purposes. Although we could, in principle, convert between all of these focal plane coordinate systems, there is no pre-defined convention for doing so. This is because the conversions required depend on where the telescope is pointing and how the CCD is mounted in the focal plane. Clearly, knowledge about this cannot be built into the AST library and must be supplied in some other way. Note that this is exactly the same problem as we met in \secref{ss:framedomains} when discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that apply to different physical domains require that extra information be supplied before we can convert between them. What we need, therefore, is a general way to describe how coordinate systems are inter-related, so that when there is no convention already in place, we can define our own. We can then look forward to converting, say, from pixels into galactic coordinates and {\emph{vice versa.} In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability. \subsection{The FrameSet Model} Consider a coordinate system (call it number 1) which is represented by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to the coordinates in system 1 yields coordinates in another system, number 2. The Mapping therefore inter-relates coordinate systems 1 and 2. Now consider a second Mapping which inter-relates system 1 and a further coordinate system, number 3. If we wanted to convert coordinates between systems 2 and 3, we could do so by: \begin{enumerate} \item Applying our first Mapping in reverse, so as to convert between systems 2 and 1. \item Applying the second Mapping, as given, to convert between systems 1 and 3. \end{enumerate} We are not limited to three coordinate systems, of course. In fact, we could continue to introduce any number of further coordinate systems, so long as we have a suitable Mapping for each one which relates it to one of the Frames already present. Continuing in this way, we can build up a network in which Frames are inter-related by Mappings in such a way that there is always a way of converting between any pair of coordinate systems. The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas. It is a network composed of Frames and associated Mappings, in which there is always exactly one path, \emph{via} Mappings, between any pair of Frames. Since we assemble FrameSets ourselves, they can be used to represent any coordinate systems we choose and to set up the particular relationships between them that we want. \subsection{\label{ss:creatingaframeset}Creating a FrameSet} Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to put into it, so let's create a simple one: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER FRAME1, STATUS STATUS = 0 ... FRAME1 = AST_FRAME( 2, 'Domain=A', STATUS ) \end{terminalv} \normalsize We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to A so that it will be distinct from the others we will be using. We can now create a new FrameSet containing just this Frame, as follows: \small \begin{terminalv} INTEGER FRAMESET ... FRAMESET = AST_FRAMESET( FRAME1, ' ', STATUS ) \end{terminalv} \normalsize So far, however, this Frame isn't related to any others. \subsection{\label{ss:addingframes}Adding New Frames to a FrameSet} We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above (\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that are already present (there is only one present so far). To keep the example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates by 10. The required Objects are created as follows: \small \begin{terminalv} INTEGER FRAME2, MAPPING12 ... FRAME2 = AST_FRAME( 2, 'Domain=B', STATUS ) MAPPING12 = AST_ZOOMMAP( 2, 10.0D0, ' ', STATUS ) \end{terminalv} \normalsize To add the new Frame into our FrameSet, we use the \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} routine: \small \begin{terminalv} CALL AST_ADDFRAME( FRAMESET, 1, MAPPING12, FRAME2, STATUS ) \end{terminalv} \normalsize Whenever a Frame is added to a FrameSet, it is assigned an integer index. This index starts with 1 for the initial Frame used to create the FrameSet (\secref{ss:creatingaframeset}) and increments by one every time a new Frame is added. This index is the primary way of identifying the Frames within a FrameSet. When a Frame is added, we also have to specify which of the existing ones the new Frame is related to. Here, we chose number 1, the only one present so far, and the new one we added became number 2. Note that a FrameSet does not make copies of the Frames and Mappings that you insert into it. Instead, it holds pointers to them. This means that if you retain the original pointers to these Objects and alter them, you will indirectly be altering the FrameSet's contents. You can, of course, always use \htmlref{AST\_COPY}{AST\_COPY} (\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if you need to ensure its independence. We could also add a third Frame into our FrameSet, this time defining a coordinate system which is reached by multiplying the original coordinates (of FRAME1) by 5: \small \begin{terminalv} CALL AST_ADDFRAME( FRAMESET, 1, : AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ), : AST_FRAME( 2, 'Domain=C', STATUS ), : STATUS ) \end{terminalv} \normalsize Here, we have avoided storing unnecessary pointer values by using function invocations directly as arguments for AST\_ADDFRAME. This assumes that we are using \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END} (\secref{ss:contexts}) to ensure that Objects are correctly deleted when no longer required. Our example FrameSet now contains three Frames and two Mappings with the arrangement shown in Figure~\ref{fig:fsexample}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/fsexample} \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to Frame~1 by multiplying its coordinates by factors of 10 and 5 respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its \htmlref{Current}{Current} attribute has the value 3. The transformation performed when the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to its current Frame) is shown in bold.} \label{fig:fsexample} \end{center} \end{figure} The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute. \subsection{\label{ss:baseandcurrent}The Base and Current Frames} At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its \emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame (Figure~\ref{fig:fsexample}). These Frames are identified by two integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices of the nominated Frames within the FrameSet. The existence of the base and current Frames reflects an important application of FrameSets, which is to attach coordinate systems to entities such as data arrays, data files, plotting surfaces (for graphics), \emph{etc.} In this context, the base Frame represents the ``native'' coordinate system of the attached entity---for example, the pixel coordinates of an image or the intrinsic coordinates of a plotting surface. The other Frames within the FrameSet represent alternative coordinate systems which may also be used to refer to positions within that entity. The current Frame represents the particular coordinate system which is currently selected for use. For instance, if an image were being displayed, you would aim to label it with coordinates corresponding to the current Frame. In order to see a different coordinate system, a software user would arrange for a different Frame to be made current. The choice of base and current Frames may be changed at any time, simply by assigning new values to the FrameSet's Base and Current attributes. For example, to make the Frame with index 3 become the current Frame, you could use: \small \begin{terminalv} CALL AST_SETI( FRAMESET, 'Current', 3, STATUS ) \end{terminalv} \normalsize You can nominate the same Frame to be both the base and current Frame if you wish. \label{ss:baseandcurrentdefault} By default (\emph{i.e.}\ if the Base or Current attribute is un-set), the first Frame added to a FrameSet becomes its base Frame and the last one added becomes its current Frame.\footnote{Although this is reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a new Frame is added to a FrameSet, the Current attribute is modified so that the new Frame becomes the current one. This behaviour is reflected in the state of the example FrameSet in Figure~\ref{fig:fsexample}. \subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames} It is often necessary to refer to the base and current Frames (\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes on each occasion. To make this easier, two parameter constants, AST\_\_BASE and AST\_\_CURRENT, are defined in the AST\_PAR include file and may be used to represent the indices of the base and current Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is required. For example, when adding a new Frame to a FrameSet (\secref{ss:addingframes}), you could use the following to indicate that the new Frame is related to the existing current Frame, whatever its index happens to be: \small \begin{terminalv} INTEGER FRAME, MAPPING ... CALL AST_ADDFRAME( FRAMESET, AST__CURRENT, MAPPING, FRAME, STATUS ) \end{terminalv} \normalsize Of course, the Frame you added would then become the new current Frame. \subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping} The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame} class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class (\secref{ss:mappings}). Its behaviour when used as a Mapping is particularly important. Consider, for instance, passing a FrameSet pointer to a coordinate transformation routine such as \htmlref{AST\_TRAN2}{AST\_TRAN2}: \small \begin{terminalv} INTEGER N DOUBLE PRECISION XIN( N ), YIN( N ) DOUBLE PRECISION XOUT( N ), YOUT( N ) ... CALL AST_TRAN2( FRAMESET, N, XIN, YIN, .TRUE., XOUT, YOUT, STATUS ) \end{terminalv} \normalsize The coordinate transformation applied by this FrameSet would be the one which converts between its base and current Frames. Using the FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates would be multiplied by a factor of 5. If we instead requested the FrameSet's inverse transformation, we would be transforming from its current Frame to its base Frame, so our example FrameSet would then multiply by a factor of 0.2. Whenever the choice of base and current Frames changes, the transformations which a FrameSet performs when used as a Mapping also change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in consequence, because they are determined by the numbers of axes in the FrameSet's base and current Frames respectively. These numbers need not necessarily be equal, of course. Like any Mapping, a FrameSet may also be inverted by changing the boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{AST\_INVERT}{AST\_INVERT} (\secref{ss:invertingmappings}). If this is happens, the values of the FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with its Nin and Nout attributes, so that its base and current Frames swap places. When used as a Mapping, the FrameSet will therefore perform the inverse transformation to that which it performed previously. To summarise, a FrameSet may be used exactly like any other Mapping which inter-relates the coordinate systems described by its base and current Frames. \subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet} Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is required (\secref{ss:framesetasmapping}), a FrameSet necessarily contains additional information and sometimes this might cause inefficiency or confusion. For example, if you wanted to use a Mapping contained in one FrameSet and insert it into another, it would probably not be efficient to insert the whole of the first FrameSet into the second one, although it would work. In such a situation, the \htmlref{AST\_GETMAPPING}{AST\_GETMAPPING} function allows you to extract a Mapping from a FrameSet. You do this by specifying the two Frames which the Mapping should inter-relate using their indices within the FrameSet. For example: \small \begin{terminalv} MAP = AST_GETMAPPING( FRAMESET, 2, 3, STATUS ) \end{terminalv} \normalsize would return a pointer to a Mapping that converted between Frames~2 and 3 in the FrameSet. Its inverse transformation would then convert in the opposite direction, \emph{i.e.}\ between Frames~3 and 2. Note that this Mapping might not be independent of the Mappings contained within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so \htmlref{AST\_COPY}{AST\_COPY} should be used to make a copy if you need to guarantee independence (\secref{ss:copyingobjects}). Very often, the Mapping returned by AST\_GETMAPPING will be a compound Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that conversion between the two Frames may need to be done \emph{via} an intermediate coordinate system so that several stages may be involved. You can, however, easily simplify this Mapping (where this is possible) by using the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} function (\secref{ss:simplifyingcmpmaps}) and this is recommended if you plan to use it for transforming a large amount of data. \subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame} A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost always behaves as if its current Frame had been used instead. For example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using: \small \begin{terminalv} CHARACTER * ( 80 ) TITLE ... TITLE = AST_GETC( FRAMESET, 'Title', STATUS ) \end{terminalv} \normalsize the result will be the Title of the current Frame, or a suitable default if the current Frame's Title attribute is un-set. The same also applies to other attribute operations---\emph{i.e.}\ setting, clearing and testing attributes. Most attributes shared by both Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)}, \htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions: \begin{quote} \begin{description} \item[\htmlref{Class}{Class}]\mbox{}\\ Has the value ``FrameSet''. \item[\htmlref{ID}{ID}]\mbox{}\\ Identifies the particular FrameSet (not its current Frame). \item[\htmlref{Nin}{Nin}]\mbox{}\\ Equals the number of axes in the FrameSet's base Frame. \item[\htmlref{Invert}{Invert}]\mbox{}\\ Is independent of any of the Objects within the FrameSet. \item[\htmlref{Nobject}{Nobject}]\mbox{}\\ Counts the number of active FrameSets. \item[\htmlref{RefCount}{RefCount}]\mbox{}\\ Counts the number of active pointers to the FrameSet (not to its current Frame). \end{description} \end{quote} Note that the set of attributes possessed by a FrameSet can vary, depending on the nature of its current Frame. For example, if the current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired, \emph{etc.} However, if the current Frame is changed to be a basic Frame, which does not have an Equinox attribute, then this attribute will be absent from the FrameSet as well. Any attempt to reference it will then result in an error. \subsection{Extracting a Frame from a FrameSet} Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most situations, it is sometimes convenient to have direct access to a specified Frame within it. This may be obtained using the \htmlref{AST\_GETFRAME}{AST\_GETFRAME} function, as follows: \small \begin{terminalv} FRAME = AST_GETFRAME( FRAMESET, AST__BASE, STATUS ) \end{terminalv} \normalsize This would return a pointer (not a copy) to the base Frame within the FrameSet. Note the use of AST\_\_BASE (\secref{ss:astbaseandastcurrent}) as shorthand for the value of the FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index. \subsection{Removing a Frame from a FrameSet} Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed using the \htmlref{AST\_REMOVEFRAME}{AST\_REMOVEFRAME} routine. You identify the Frame you wish to remove in the usual way, by giving its index within the FrameSet. For example, the following would remove the Frame with index 1: \small \begin{terminalv} CALL AST_REMOVEFRAME( FRAMESET, 1, STATUS ); \end{terminalv} \normalsize The only restriction is that you cannot remove the last remaining Frame because a FrameSet must always contain at least one Frame. When a Frame is removed, the Frames which follow it are re-numbered (\emph{i.e.}\ their indices are reduced by one) so as to preserve the sequence of consecutive Frame indices. The FrameSet's \htmlref{Nframe}{Nframe} attribute is also decremented. If appropriate, AST\_REMOVEFRAME will modify the FrameSet's \htmlref{Base}{Base} and/or \htmlref{Current}{Current} attributes so that they continue to identify the same Frames as previously. If either the base or current Frame is removed, however, the corresponding attribute will become un-set, so that it reverts to its default value (\secref{ss:baseandcurrentdefault}) and therefore identifies an alternative Frame. Note that it is quite permissible to remove any Frame from a FrameSet, even although other Frames may appear to depend on it. For example, in Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct relationship between Frames~2 and 3 would still be preserved, although they would be re-numbered as Frames~1 and 2. \cleardoublepage \section{\label{ss:fshigher}Higher Level Operations on FrameSets} \subsection{\label{ss:framesetsfromconvert}Creating FrameSets with AST\_CONVERT} Before considering the important subject of using FrameSets to convert between coordinate systems (\secref{ss:framesetconverting}), let us return briefly to reconsider the output generated by \htmlref{AST\_CONVERT}{AST\_CONVERT}. We used this function earlier (\secref{ss:introducingconversion}), when converting between the coordinate systems represented by various kinds of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the coordinate conversion it identifies. We are now in a position to examine the structure of this FrameSet. Take our earlier example (\secref{ss:convertingskyframes}) of converting between the celestial coordinate systems represented by two SkyFrames: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER SKYFRAME1, SKYFRAME2, STATUS STATUS = 0 ... SKYFRAME1 = AST_SKYFRAME( 'System=FK4-NO-E, Epoch=B1958, Equinox=B1960', STATUS ) SKYFRAME2 = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2010.5', STATUS ) CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS ) \end{terminalv} \normalsize This will produce a pointer, CVT, to the FrameSet shown in Figure~\ref{fig:fsconvert}. \begin{figure}[bhtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/fsconvert} \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when AST\_CONVERT is used to convert between the coordinate systems represented by two SkyFrames. The source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the required conversion.} \label{fig:fsconvert} \end{center} \end{figure} As can be seen, this FrameSet contains just two Frames. The source Frame supplied to AST\_CONVERT becomes its base Frame, while the destination Frame becomes its current Frame. (The FrameSet, of course, simply holds pointers to these Frames, rather than making copies.) The Mapping which relates the base Frame to the current Frame is the one which implements the required conversion. As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet returned by AST\_CONVERT may be used both as a Mapping and as a Frame to perform most of the functions you are likely to need. However, the Mapping may be extracted for use on its own if necessary, using \htmlref{AST\_GETMAPPING}{AST\_GETMAPPING} (\secref{ss:extractingamapping}), for example: \small \begin{terminalv} INTEGER MAPPING ... MAPPING = AST_GETMAPPING( CVT, AST__BASE, AST__CURRENT, STATUS ) \end{terminalv} \normalsize \subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems} We now consider the process of converting between the coordinate systems represented by two FrameSets. This is a most important operation, as a subsequent example (\secref{ss:registeringimages}) will show, and is illustrated in Figure~\ref{fig:fsalign}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/fsalign} \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion between two FrameSets is performed by establishing a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion between these two Frames is possible, then a route for converting between the current Frames of both FrameSets can also be found. In practice, there may be many ways of pairing Frames to find the ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to narrow the choice.} \label{fig:fsalign} \end{center} \end{figure} Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave like its current \htmlref{Frame}{Frame} when necessary, conversion between two FrameSets is performed using \htmlref{AST\_CONVERT}{AST\_CONVERT} (\secref{ss:convertingskyframes}), but supplying pointers to FrameSets instead of Frames. The effect of this is to convert between the coordinate systems represented by the current Frames of each FrameSet: \small \begin{terminalv} INTEGER FRAMESETA, FRAMESETB ... CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY', STATUS ) \end{terminalv} \normalsize When using FrameSets, we are presented with considerably more conversion options than when using Frames alone. This is because each current Frame is related to all the other Frames in its respective FrameSet. Therefore, if we can establish a link between any pair of Frames, one from each FrameSet, we can form a complete conversion path between the two current Frames (Figure~\ref{fig:fsalign}). This expanded range of options is, of course, precisely the intention. By connecting Frames together within a FrameSet, we have extended the range of coordinate systems that can be reached from any one of them. We are therefore no longer restricted to converting between Frames with the same Domain value (\secref{ss:framedomains}), but can go \emph{via} a range of intermediate coordinate systems in order to make the connection we require. Transformation between different domains has therefore become possible because, in assembling the FrameSets, we provided the additional information needed to inter-relate them. It is important to appreciate, however, that the choice of ``missing link'' is crucial in determining the conversion that results. Although each FrameSet may be perfectly self-consistent internally, this does not mean that all conversion paths through the combined network of Mappings are equivalent. Quite the contrary in fact: everything depends on where the inter-connecting link between the two FrameSets is made. In practice, there may be a large number of possible pairings of Frames and hence of possible links. Other factors must therefore be used to restrict the choice. These are: \begin{enumerate} \item Not every possible pairing of Frames is legitimate. For example, you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which belong to different classes, so such pairings will be ignored. \item In a similar way, you cannot convert directly between Frames with different Domain values (\secref{ss:framedomains}). If the Domain attribute is used consistently (typically only one Frame in each FrameSet will have a particular Domain value), then this further restricts the choice. \item The third argument of AST\_CONVERT may then be used to specify explicitly which Domain value the paired Frames should have. You may also supply a comma-separated list of preferences here (see below). \item If the above steps fail to uniquely identify the link, then the first suitable pairing of Frames is used, so that any ambiguity is resolved by the order in which Frames are considered for pairing (see the description of the AST\_CONVERT function in \appref{ss:functiondescriptions} for details of the search order).\footnote{If you find that how this ambiguity is resolved actually makes a difference to the conversion that results, then you have probably constructed a FrameSet which lacks internal self-consistency. For example, you might have two Frames representing indistinguishable coordinate systems but inter-related by a non-null \htmlref{Mapping}{Mapping}.} \end{enumerate} In the example above we supplied the string ``SKY'' as the third argument of AST\_CONVERT. This constitutes a request that a pair of Frames with the Domain value SKY (\emph{i.e.}\ representing celestial coordinate systems) should be used to inter-relate the two FrameSets. Note that this does not specify which celestial coordinate system to use, but is a general request that the two FrameSets be inter-related using coordinates on the celestial sphere. Of course, it may be that this request cannot be met because there may not be a celestial coordinate system in both FrameSets. If this is likely to happen, we can supply a list of preferences, or a \emph{domain search path}, as the third argument to AST\_CONVERT, such as the following: \small \begin{terminalv} CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY,PIXEL,GRID,', STATUS ) \end{terminalv} \normalsize Now, if the two FrameSets cannot be inter-related using the SKY domain, AST\_CONVERT will attempt to use the PIXEL domain instead. If this also fails, it will try the GRID domain. A blank field in the domain search path (here indicated by the final comma) allows any Domain value to be used. This can be employed as a last resort when all else has failed. If astConvert succeeds in identifying a conversion, it will return a pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the source and destination Frames are inter-connected by the required Mapping. In this case, of course, these Frames will be the current Frames of the two FrameSets, but in all other respects the returned FrameSet is the same as when converting between Frames. Very importantly, however, AST\_CONVERT may modify the FrameSets you are converting between. It does this, in order to indicate which pairing of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base} attribute for each FrameSet so that the Frame used in the pairing becomes its base Frame (\secref{ss:baseandcurrent}). Finally, note that AST\_CONVERT may also be used to convert between a FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is supplied for either the first or second argument, it will behave like a FrameSet containing only a single Frame. \subsection{\label{ss:registeringimages}Example---Registering Two Images} Consider two images which have been calibrated by attaching FrameSets to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the raw data grid coordinates of each image (the GRID domain of \secref{ss:domainconventions}). Suppose, also, that these FrameSets contain an unknown number of other Frames, representing alternative world coordinate systems. What we wish to do is register these two images, such that we can transform from a position in the data grid of one into the corresponding position in the data grid of the other. This is a very practical example because images will typically be calibrated using FrameSets in precisely this way. The first step will probably involve making a copy of both FrameSets (using \htmlref{AST\_COPY}{AST\_COPY}---\secref{ss:copyingobjects}), since we will be modifying them. Let ``frameseta'' and ``framesetb'' be pointers to these copies. Since we want to convert between the base Frames of these FrameSets (\emph{i.e.}\ their data grid coordinates), the next step is to make these Frames current. This is simply done by inverting both FrameSets, which interchanges their base and current Frames. astInvert will perform this task: \small \begin{terminalv} CALL AST_INVERT( FRAMESETA, STATUS ) CALL AST_INVERT( FRAMESETB, STATUS ) \end{terminalv} \normalsize To identify the required conversion, we now use \htmlref{AST\_CONVERT}{AST\_CONVERT}, supplying a suitable domain search path with which we would like our two images to be registered: \small \begin{terminalv} CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY,PIXEL,GRID', STATUS ) IF ( CVT .EQ. AST__NULL ) THEN ELSE END IF \end{terminalv} \normalsize The effects of this are: \begin{enumerate} \item AST\_CONVERT first attempts to register the two images on the celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it searches for a celestial coordinate system, although not necessarily the same one, attached to each image. If it finds a suitable pair of coordinate systems, it then registers the images by matching corresponding positions on the sky. \item If this fails, AST\_CONVERT next tries to match positions in the PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two images will then be registered so that their corresponding pixel positions correspond. If the PIXEL domain is offset from the data grid (as typically happens in data reduction systems which implement a ``pixel origin''), then this will be correctly accounted for. \item If this also fails, the GRID domain is finally used. This will result in image registration by matching corresponding points in the data grids used by both images. This means they will be aligned so that the first element their data arrays correspond. \item If all of the above fail, AST\_CONVERT will return the value AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned. \end{enumerate} The resulting CVT FrameSet may then be used directly (\secref{ss:convertingskyframes}) to convert between positions in the data grid of the first image and corresponding positions in the data grid of the second image. To determine which domain was used to achieve registration, we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by AST\_CONVERT to indicate which intermediate Frames were used. We can therefore simply invert either FrameSet (to make its base Frame become the current one) and then enquire the \htmlref{Domain}{Domain} value: \small \begin{terminalv} CHARACTER * ( 20 ) DOMAIN ... CALL AST_INVERT( FRAMESETA, STATUS ) DOMAIN = AST_GETC( FRAMESETA, 'Domain', STATUS ) \end{terminalv} \normalsize If conversion was successful, the result will be one of the strings ``SKY'', ``PIXEL'' or ``GRID''. \subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System} As discussed earlier (\secref{ss:baseandcurrent}), an important application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to be attached to entities such as images in order to calibrate them. In addition, one of the main objectives of AST is to simplify the propagation of such information through successive stages of data processing, so that it remains consistent with the associated image data. In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with the image's data grid coordinates and its other Frames (if any) with the various alternative world coordinate systems associated with the image. If the data processing being performed does not change the relationship between the image's data grid coordinates and any of the associated world coordinate systems, then propagation of the WCS information is straightforward and simply involves copying the FrameSet associated with the image. If any of these relationships change, however, then corresponding changes must be made to the way Frames within the FrameSet are inter-related. By far the most common case occurs when the image undergoes some geometrical transformation resulting in ``re-gridding'' on to another data grid, but the same principles can be applied to any re-definition of a coordinate system. To pursue the re-gridding example, we would need to modify our FrameSet to account for the fact that the image's data grid coordinate system (corresponding to the FrameSet's base Frame) has changed. Looking at the steps needed in detail, we might proceed as follows: \begin{enumerate} \item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the original data grid coordinate system and the new one. \item Obtain a Frame to represent the new data grid coordinate system (we could re-use the original base Frame here, using \htmlref{AST\_GETFRAME}{AST\_GETFRAME} to obtain a pointer to it). \item Add the new Frame to the FrameSet, related to the original base Frame by the new Mapping. This Frame now represents the new data grid coordinate system and is correctly related to all the other Frames present.\footnote{This is because any transformation to or from this new Frame must go \emph{via} the base Frame representing the original data grid coordinate system, which we assume was correctly related to all the other Frames present.} \item Remove the original base Frame (representing the old data grid coordinate system). \item Make the new Frame the base Frame and restore the original current Frame. \end{enumerate} The effect of these steps is to change the relationship between the base Frame and all the other Frames present. It is as if a new Mapping has been interposed between the Frame we want to alter and all the other Frames within the FrameSet (Figure~\ref{fig:fsremap}). \begin{figure}[hbtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/fsremap} \caption[Interposing a Mapping into a FrameSet]{The effect of \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME} is to interpose a Mapping between a nominated Frame within a FrameSet and the remaining contents of the FrameSet. This effectively ``re-defines'' the coordinate system represented by the affected Frame. It may be used to compensate (say) for geometrical changes made to an associated image. The inter-relationships between all the other Frames within the FrameSet remain unchanged.} \label{fig:fsremap} \end{center} \end{figure} Performing the steps above is rather lengthy, however, so the AST\_REMAPFRAME function is provided to perform all of these operations in one go. A practical example of its use is given below (\secref{ss:wcsprocessingexample}). \subsection{\label{ss:wcsprocessingexample}Example---Binning an Image} As an example of using \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME}, consider a case where the pixels of a 2-dimensional image have been binned 2$\times$2, so as to reduce the image size by a factor of two in each dimension. We must now modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the image. Much the same process would be needed for any other geometrical change the image might undergo. We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the data grid coordinates in the original image to those in the new one: \small \begin{terminalv} INTEGER WINMAP DOUBLE PRECISION INA( 2 ), INB( 2 ), OUTA( 2 ), OUTB( 2 ) DATA INA / 0.5D0, 0.5D0 / DATA INB / 2.5D0, 2.5D0 / DATA OUTA / 0.5D0, 0.5D0 / DATA OUTB / 1.5DO, 1.5DO / ... WINMAP = AST_WINMAP( 2, INA, INB, OUTA, OUTB, ' ', STATUS ) \end{terminalv} \normalsize Here, we have simply set up arrays containing the data grid coordinates of the bottom left and top right corners of the first element in the output image (OUTA and OUTB) and the corresponding coordinates in the input image (INA and INB). \htmlref{AST\_WINMAP}{AST\_WINMAP} then creates a WinMap which performs the required transformation. We do not need to know the size of the image. We can then pass this WinMap to AST\_REMAPFRAME. This modifies the relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in the FrameSet, so that the base Frame represents the data grid coordinate system of the new image rather than the old one: \small \begin{terminalv} INTEGER FRAMESET ... CALL AST_REMAPFRAME( FRAMESET, AST__BASE, WINMAP, STATUS ) \end{terminalv} \normalsize Any other coordinate systems described by the FrameSet, no matter how many of these there might be, are now correctly associated with the new image. \subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets} When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into which you can place any combination of Frames and Mappings that you wish. There are relatively few constraints on this process and no checks are performed to see whether the FrameSet you construct makes physical sense. It is quite possible, for example, to construct a FrameSet containing two identical SkyFrames which are inter-related by a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes no sense, because applying a non-unit Mapping to any set of celestial coordinates cannot yield positions that are still in the original coordinate system. If you use such a FrameSet to perform coordinate conversions, you are likely to get unpredictable results because the information in the FrameSet is corrupt. It is, of course, your responsibility as a programmer to ensure the validity of any information which you insert into a FrameSet. Normally, this is straightforward and simply consists of formulating your problem correctly (a diagram can often help to clarify how coordinate systems are inter-related) and writing the appropriate bug-free code to construct the FrameSet. However, once you start to modify an existing FrameSet, there are new opportunities for corrupting it! Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute simply by using \htmlref{AST\_SET}{AST\_SET} on the FrameSet, as follows: \small \begin{terminalv} CALL AST_SET( FRAMESET, 'Equinox=J2010', STATUS ) \end{terminalv} \normalsize The effect of this will be to change the celestial coordinate system which the current Frame represents. You can see, however, that this has the potential to make the FrameSet corrupt unless corresponding changes are also made to the Mapping which relates this SkyFrame to the other Frames within the FrameSet. In fact, it is a general rule that any change to a FrameSet which affects its current Frame can potentially require corresponding changes to the FrameSet's Mappings in order to maintain its overall integrity. Fortunately, once you have stored valid information in a FrameSet, AST will look after these details for you automatically, so that the FrameSet's integrity is maintained. In the example above, it would do this by appropriately re-mapping the current Frame (as if \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME} had been used---\secref{ss:remapframe}) in response to the use of AST\_SET. One way of illustrating this process is as follows: \small \begin{terminalv} INTEGER SKYFRAME ... SKYFRAME = AST_SKYFRAME( ' ', STATUS ) FRAMESET = AST_FRAMESET( SKYFRAME, STATUS ) CALL AST_ADDFRAME( FRAMESET, 1, AST_UNITMAP( 2, ' ', STATUS ) : SKYFRAME, STATUS ) \end{terminalv} \normalsize This constructs a trivial FrameSet whose base and current Frames are both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this as a ``pipe'' connecting two coordinate systems. At present, these two systems represent identical ICRS coordinates, so the FrameSet implements a unit Mapping. We can change the coordinate system on the current end of this pipe as follows: \small \begin{terminalv} CALL AST_SET( FRAMESET, 'System=Ecliptic, Equinox=J2010', STATUS ) \end{terminalv} \normalsize and the Mapping which the FrameSet implements would change accordingly. To change the coordinate system on the base end of the pipe, we might use: \small \begin{terminalv} CALL AST_INVERT( FRAMESET ) CALL AST_SET( FRAMESET, 'System=Galactic', STATUS ) CALL AST_INVERT( FRAMESET ) \end{terminalv} \normalsize The FrameSet would then convert between galactic and ecliptic coordinates. Note that AST\_SET is not the only function which has this effect: \htmlref{AST\_CLEAR}{AST\_CLEAR} behaves similarly, as also does \htmlref{AST\_PERMAXES}{AST\_PERMAXES} (\secref{ss:permutingaxes}). If you need to circumvent this mechanism for any reason, this can be done by going behind the scenes and obtaining a pointer directly to the Frame you wish to modify. Consider the following, for example: \small \begin{terminalv} SKYFRAME = AST_GETFRAME( FRAMESET, AST__CURRENT, STATUS ) CALL AST_SET( SKYFRAME, 'Equinox=J2010', STATUS ) CALL AST_ANNUL( SKYFRAME, STATUS ) \end{terminalv} \normalsize Here, AST\_SET is applied to the SkyFrame pointer rather than the FrameSet pointer, so the usual checks on FrameSet integrity do not occur. The SkyFrame's Equinox attribute will therefore be modified without any corresponding change to the FrameSet's Mappings. In this case you must take responsibility yourself for maintaining the FrameSet's integrity, perhaps through appropriate use of AST\_REMAPFRAME. \subsection{Merging FrameSets} As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet} (\secref{ss:addingframes}), it is also possible to add complete sets of inter-related Frames which are contained within another FrameSet. This, of course, corresponds to the process of merging two FrameSets (Figure~\ref{fig:fsmerge}). \begin{figure}[hbtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun210_figures/fsmerge} \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}. FrameSet~B is being added to FrameSet~A by supplying a new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1) and the current Frame of B. In the merged FrameSet, the Frames contributed by B will be re-numbered to become Frames~4, 5 and 6. The base Frame will remain unchanged, but the current Frame of B becomes the new current Frame. Note that FrameSet~B itself is not altered by this process.} \label{fig:fsmerge} \end{center} \end{figure} This process is performed by adding one FrameSet to another using AST\_ADDFRAME, in much the same manner as when adding a new Frame to an existing FrameSet (\secref{ss:addingframes}). It is simply a matter of providing a FrameSet pointer, instead of a Frame pointer, for the 4th argument. In performing the merger you must, as usual, supply a Mapping, but in this case the Mapping should relate the current Frame of the FrameSet being added to one of the Frames already present. For example, you might perform the merger shown in Figure~\ref{fig:fsmerge} as follows: \small \begin{terminalv} INTEGER MAPPING ... CALL AST_ADDFRAME( FRAMESETA, 1, MAPPING, FRAMESETB, STATUS ) \end{terminalv} \normalsize The Frames acquired by FRAMESETA from the FrameSet being added (FRAMESETB) are re-numbered so that they retain their original order and follow on consecutively after the Frames that were already present, whose indices remain unchanged. The base Frame of FRAMESETA remains unchanged, but the current Frame of FRAMESETB becomes its new current Frame. All the inter-relationships between Frames in both FrameSets remain in place and are preserved in the merged FrameSet. Note that while this process modifies the first FrameSet (FRAMESETA), it leaves the original contents of the one being added (FRAMESETB) unchanged. %\cleardoublepage %\section{\label{ss:searching}TBW - Searching for Coordinate Systems} \cleardoublepage \section{\label{ss:channels}Saving and Restoring Objects (Channels)} Facilities are provided by the AST library for performing input and output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible to write any Object into various external representations for storage, and then to read these representations back in, so as to restore the original Object. Typically, an Object would be written by one program and read back in by another. We refer to ``external representations'' in the plural because AST is designed to function independently of any particular data storage system. This means that Objects may need converting into a number of different external representations in order to be compatible with (say) the astronomical data storage system in which they will reside. In this section, we discuss the basic I/O facilities which support external representations based on a textual format referred to as the AST ``native format''. These are implemented using a new kind of Object---a \htmlref{Channel}{Channel}. We will examine later how to use other representations, based on an XML format or on the use of FITS headers, for storing Objects. These are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan} (\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}). \subsection{The Channel Model} The best way to start thinking about a \htmlref{Channel}{Channel} is like a Fortran I/O unit (also represented by an integer, as it happens) and to think of the process of creating a Channel as the combined process of allocating a unit number and attaching it to a file by opening the file on that unit. Subsequently, you can read and write Objects \emph{via} the Channel. This analogy is not quite perfect, however, because a Channel has, in principle, two ``files'' attached to it. One is used when reading, and the other when writing. These are termed the Channel's \emph{source} and \emph{sink} respectively. In practice, the source and sink may both be the same, in which case the analogy with the Fortran I/O unit is correct, but this need not always be so. It is not necessarily so with the basic Channel, as we will now see (\secref{ss:creatingachannel}). \subsection{\label{ss:creatingachannel}Creating a Channel} The process of creating a \htmlref{Channel}{Channel} is straightforward. As you might expect, it uses the constructor function \htmlref{AST\_CHANNEL}{AST\_CHANNEL}: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER CHANNEL, STATUS STATUS = 0 ... CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, ' ', STATUS ) \end{terminalv} \normalsize The first two arguments to AST\_CHANNEL specify the external source and sink that the Channel is to use. There arguments are the names of Fortran subroutines and we will examine their use in more detail later (\secref{ss:channelsource} and \secref{ss:channelsink}). In this very simple example we have supplied the name of the null routine AST\_NULL\footnote{Note that AST\_NULL (one underscore) is a routine name and is distinct from AST\_\_NULL (two underscores) which is a null \htmlref{Object}{Object} pointer. Since we are passing the name of one routine to another routine, AST\_NULL would normally have to appear in a Fortran EXTERNAL statement. In this example, however, a suitable statement is already present in the AST\_PAR include file.} for both the source and sink routines. This requests the default behaviour, which means that textual input will be read from the program's standard input stream (typically, this means your keyboard) while textual output will go to the standard output stream (typically appearing on your screen). On UNIX systems, of course, either of these streams can easily be redirected to files. \subsection{\label{ss:writingtoachannel}Writing Objects to a Channel} The process of saving Objects is very straightforward. You can simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{AST\_WRITE}{AST\_WRITE} function, as follows: \small \begin{terminalv} INTEGER NOBJ, OBJECT ... NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS ) \end{terminalv} \normalsize The effect of this will be to produce a textual description of the Object which will appear, by default, on your program's standard output stream. Any class of Object may be converted into text in this way. AST\_WRITE returns a count of the number of Objects written. Usually, this will be one, unless the Object supplied cannot be represented. With a basic Channel all Objects can be represented, so a value of one will always be returned unless there has been an error. We will see later, however, that more specialised forms of Channel may impose restrictions on the kind of Object you can write (\secref{ss:foreignfitslimitations}). In such cases, AST\_WRITE may return zero to indicate that the Object was not acceptable. \subsection{\label{ss:readingfromachannel}Reading Objects from a Channel} Before discussing the format of the output produced above (\secref{ss:writingtoachannel}), let us consider how to read it back, so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first need to save the output in a file. We can do that either by using the \htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output to a file using a shell command like: \small \begin{terminalv} program1 >file \end{terminalv} \normalsize Within a subsequent program, we can read this Object back in by using the \htmlref{AST\_READ}{AST\_READ} function, having first created a suitable \htmlref{Channel}{Channel}: \small \begin{terminalv} OBJECT = AST_READ( CHANNEL, STATUS ) \end{terminalv} \normalsize By default, this function will read from the standard input stream (the default source for a basic Channel), so we would need to ensure that our second program reads its input from the file in which the Object description is stored. On UNIX systems, we could again use a shell redirection command such as: \small \begin{terminalv} program2 $}{AST\_ISA$<$CLASS$>$} family of functions: \small \begin{terminalv} LOGICAL OK ... OK = AST_ISAFRAME( OBJECT, STATUS ) \end{terminalv} \normalsize Note, however, that this will accept any Frame, so would be equally happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}. An alternative validation strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute and then test this character string, as follows: \small \begin{terminalv} OK = AST_GETC( OBJECT, 'Class', STATUS ) .EQ. 'Frame' \end{terminalv} \normalsize This would only accept a basic Frame and would reject a SkyFrame. \subsection{Storing an ID String with an Object} Occasionally, you may want to store a number of Objects and later retrieve them and use each for a different purpose. If the Objects are of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish them when you read them back (\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the order in which they are stored is a possible solution, this becomes complicated if some of the Objects are optional and may not always be present. It also makes extending your data format in future more difficult. To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident} attribute, both of which allows you, in effect, to attach a textual identification label to it. You simply set the ID or Ident attribute before writing the Object: \small \begin{terminalv} CALL AST_SET( OBJECT, 'ID=Calibration', STATUS ) NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS ) \end{terminalv} \normalsize You can then test its value after you read the Object back: \small \begin{terminalv} OBJECT = AST_READ( CHANNEL, STATUS ) IF ( AST_GETC( OBJECT, 'ID', STATUS ) .EQ. 'Calibration' ) THEN ELSE END IF \end{terminalv} \normalsize The only difference between the ID and Ident attributes is that the ID attribute is unique to a particular Object and is lost if, for example, you make a copy of the Object. The Ident attrubute, on the other hand, is transferred to the new Object when a copy is made. Consequently, it is safest to set the value of the ID attribute immediately before you perform the write. \subsection{\label{ss:textualoutputformat}The Textual Output Format} Let us now examine the format of the textual output produced by writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}). To give a concrete example, suppose the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows: \small \begin{terminalv} INTEGER SKYFRAME ... NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS ) \end{terminalv} \normalsize The output should then look like the following: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain # Lbl1 = "Right Ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction (hint) Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} \normalsize You will notice that this output is designed both for a human reader, in that it is formatted, and also to be read back by a computer in order to reconstruct the SkyFrame. In fact, this is precisely the way that \htmlref{AST\_SHOW}{AST\_SHOW} works (\secref{ss:displayingobjects}), this routine being roughly equivalent to the following use of a Channel: \small \begin{terminalv} CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, ' ', STATUS ) NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS ) CALL AST_ANNUL( CHANNEL, STATUS ) \end{terminalv} \normalsize Some lines of the output start with a ``\verb?#?'' comment character, which turns the rest of the line into a comment. These lines will be ignored when read back in by \htmlref{AST\_READ}{AST\_READ}. They typically contain default values, or values that can be derived in some way from the other data present, so that they do not actually need to be stored in order to reconstruct the original Object. They are provided purely for human information. The same comment character is also used to append explanatory comments to most output lines. It is not sensible to attempt a complete description of this output format because every class of Object is potentially different and each can define how its own data should be represented. However, there are some basic rules, which mean that the following common features will usually be present: \begin{enumerate} \item Each Object is delimited by matching ``Begin'' and ``End'' lines, which also identify the class of Object involved. \item Within each Object description, data values are represented by a simple ``keyword~$=$~value'' syntax, with one value to a line. \item Lines beginning ``IsA'' are used to mark the divisions between data belonging to different levels in the class hierarchy (\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data associated with the Frame class and the start of data associated with some derived class (a SkyFrame in the above example). ``IsA'' lines may be omitted if associated data values are absent and no confusion arises. \item Objects may contain other Objects as data. This is indicated by an absent value, with the description of the data Object following on subsequent lines. \item Indentation is used to clarify the overall structure. \end{enumerate} Beyond these general principles, the best guide to what a particular line of output represents will generally be the comment which accompanies it together with a general knowledge of the class of Object being described. \subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output} It is not always necessary for the output from \htmlref{AST\_WRITE}{AST\_WRITE} (\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has attributes that allow the amount of detail in the output to be controlled. The first of these is the integer attribute \htmlref{Full}{Full}, which controls the extent to which optional, commented out, output lines are produced. By default, Full is zero, and this results in the standard style of output (\secref{ss:textualoutputformat}) where default values that may be helpful to humans are included. To suppress these optional lines, Full should be set to $-$1. This is most conveniently done when the Channel is created, so that: \small \begin{terminalv} CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, 'Full=-1', STATUS ) NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS ) CALL AST_ANNUL( CHANNEL, STATUS ) \end{terminalv} \normalsize would result in output containing only the essential information, such as: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system Naxes = 2 # Number of coordinate axes Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation End SkyFrame \end{terminalv} \normalsize In contrast, setting Full to $+$1 will result in additional output lines which will reveal every last detail of the \htmlref{Object}{Object}'s construction. Often this will be rather more than you want, especially for more complex Objects, but it can sometimes help when debugging programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # RefCnt = 1 # Count of active Object pointers # Nobj = 1 # Count of active Objects in same class IsA Object # Astrometry Object # Nin = 2 # Number of input coordinates # Nout = 2 # Number of output coordinates # Invert = 0 # Mapping not inverted # Fwd = 1 # Forward transformation defined # Inv = 1 # Inverse transformation defined # Report = 0 # Don't report coordinate transformations IsA Mapping # Mapping between coordinate systems # Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain # Lbl1 = "Right Ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 # Sym1 = "RA" # Symbol for axis 1 # Sym2 = "Dec" # Symbol for axis 2 # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dig1 = 7 # Individual precision for axis 1 # Dig2 = 7 # Individual precision for axis 2 # Digits = 7 # Default formatting precision # Fmt1 = "hms.1" # Format specifier for axis 1 # Fmt2 = "dms" # Format specifier for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction (hint) # Dir2 = 1 # Plot axis 2 in conventional direction (hint) # Presrv = 0 # Don't preserve target axes # Permut = 1 # Axes may be permuted to match # MinAx = 2 # Minimum number of axes to match # MaxAx = 2 # Maximum number of axes to match # MchEnd = 0 # Match initial target axes # Prm1 = 1 # Axis 1 not permuted # Prm2 = 2 # Axis 2 not permuted Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis # RefCnt = 1 # Count of active Object pointers # Nobj = 2 # Count of active Objects in same class IsA Object # Astrometry Object # Label = "Angle on Sky" # Axis Label # Symbol = "delta" # Axis symbol # Unit = "ddd:mm:ss" # Axis units # Digits = 7 # Default formatting precision # Format = "dms" # Format specifier # Dirn = 1 # Plot in conventional direction IsA Axis # Coordinate axis # Format = "dms" # Format specifier # IsLat = 0 # Longitude axis (not latitude) # AsTime = 0 # Display values as angles (not times) End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis # RefCnt = 1 # Count of active Object pointers # Nobj = 2 # Count of active Objects in same class IsA Object # Astrometry Object # Label = "Angle on Sky" # Axis Label # Symbol = "delta" # Axis symbol # Unit = "ddd:mm:ss" # Axis units # Digits = 7 # Default formatting precision # Format = "dms" # Format specifier # Dirn = 1 # Plot in conventional direction IsA Axis # Coordinate axis # Format = "dms" # Format specifier # IsLat = 0 # Longitude axis (not latitude) # AsTime = 0 # Display values as angles (not times) End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} \normalsize \subsection{\label{ss:channelcommenting}Controlling Commenting} Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments are appended to describe the purpose of each value. Comment has the value 1 by default but, if set to zero, will suppress these comments. This is normally appropriate only if you wish to minimise the amount of output, for example: \small \begin{terminalv} CALL AST_SET( CHANNEL, 'Full=-1, Comment=0', STATUS ) NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS ) \end{terminalv} \normalsize might result in the following more compact output: \small \begin{terminalv} Begin SkyFrame Naxes = 2 Ax1 = Begin SkyAxis End SkyAxis Ax2 = Begin SkyAxis End SkyAxis IsA Frame System = "FK4-NO-E" Epoch = 1958 End SkyFrame \end{terminalv} \normalsize \subsection{Editing Textual Output} The safest advice about editing the textual output from \htmlref{AST\_WRITE}{AST\_WRITE} (or \htmlref{AST\_SHOW}{AST\_SHOW}) is ``don't!''---unless you know what you are doing. Having given that warning, however, it is sometimes possible to make changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from scratch, and to read the results back in to construct new Objects. Normally, simple changes to numerical values are safest, but be aware that this is a back door method of creating Objects, so you are on your own! There are a number of potential pitfalls. In particular: \begin{itemize} \item \htmlref{AST\_READ}{AST\_READ} is intended for retrieving data written by AST\_WRITE and not for reading data input by humans. As such, the data validation provided is very limited and is certainly not foolproof. This makes it quite easy to construct Objects that are internally inconsistent by this means. In contrast, the normal programming interface incorporates numerous checks designed to make it impossible to construct invalid Objects. You should not necessarily think you have found a bug if your changes to an Object's textual description fail to produce the results you expected! \item In many instances the names associated with values in textual output will correspond with Object attributes. Sometimes, however, these names may differ from the attribute name. This is mainly because of length restrictions imposed by other common external formats, such as FITS headers. Some of the names used do not correspond with attributes at all. \item It is safest to change single numerical or string values. Beware of changing the size or shape of Objects (\emph{e.g.}\ the number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others stored elsewhere within the Object and changing them in a haphazard fashion will not produce useful results. \item Be wary about un-commenting default values. Sometimes this will work, but often these values are derived from other Objects stored more deeply in the structure and the proper place to insert a new value is not where the default itself appears. \end{itemize} \subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text} By default, when you use \htmlref{AST\_READ}{AST\_READ} to read from a basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}), it is assumed that you are reading a stream of text containing only AST Objects, which follow each other end-to-end. If any extraneous input data are encountered which do not appear to form part of the textual description of an \htmlref{Object}{Object}, then an error will result. In particular, the first input line must identify the start of an Object description, so you cannot start reading half way through an Object. Sometimes, however, you may want to store AST Object descriptions intermixed with other textual data. You can do this by setting the Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every read to skip over extraneous data until the start of a new AST Object description, if any, is found. So long as your other data do not mimic the appearance of an AST Object description, the two sets of data can co-exist. For example, by setting Skip to 1, the following complete Fortran program will read all the AST Objects whose descriptions appear in the source of this document, ignoring the other text. \htmlref{AST\_SHOW}{AST\_SHOW} is used to display those found: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER CHANNEL, OBJECT, STATUS STATUS = 0 CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, 'Skip=1', STATUS ) 1 OBJECT = AST_READ( CHANNEL, STATUS ) IF ( OBJECT .NE. AST__NULL ) THEN CALL AST_SHOW( OBJECT, STATUS ) CALL AST_ANNUL( OBJECT, STATUS ) GO TO 1 END IF CALL AST_ANNUL( CHANNEL, STATUS ) END \end{terminalv} \normalsize \subsection{\label{ss:channelsource}Reading Objects from Files} Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel} in reading and writing Objects through a program's standard input and output streams. We will now consider how to access Objects stored in files more directly. The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of the Channel. For instance, the following will read a pair of Objects from a text file called ``fred.txt'': \small \begin{terminalv} CALL AST_SET( CHANNEL, 'SourceFile=fred.txt', STATUS ) OBJ1 = AST_READ( CHANNEL, STATUS ) OBJ2 = AST_READ( CHANNEL, STATUS ) CALL AST_CLEAR( CHANNEL, 'SourceFile', STATUS ) \end{terminalv} \normalsize Note, the act of clearing the attribute tells AST that no more Objects are to be read from the file and so the file is then closed. If the attribute is not cleared, the file will remain open and further Objects can be read from it. The file will always be closed when the Channel is deleted. This simple approach will normally be sufficient. However, because the AST library is designed to be used from more than one language, it has to be a little careful about reading and writing to files. This is due to incompatibilities that may exist between the file I/O facilities provided by different languages. If such incompatibilities prevent the above simple system being used, we need to adopt a system that off-loads all file I/O to external code. What this means in practice is that if the above simple approach cannot be used, you must instead provide some simple Fortran routines that perform the actual transfer of data to and from files and similar external data stores. The routines you provide are supplied as the source and/or sink routine arguments to \htmlref{AST\_CHANNEL}{AST\_CHANNEL} when you create a Channel (\secref{ss:creatingachannel}). An example is the best way to illustrate this. Consider the following simple subroutine called SOURCE. It reads a single line of text from a Fortran I/O unit and then calls \htmlref{AST\_PUTLINE}{AST\_PUTLINE} to pass it to the AST library, together with its length. It sets this length to be negative if there is no more input: \small \begin{terminalv} SUBROUTINE SOURCE( STATUS ) INTEGER STATUS CHARACTER * ( 200 ) BUFFER READ( 1, '(A)', END = 99 ) BUFFER CALL AST_PUTLINE( BUFFER, LEN( BUFFER ), STATUS ) RETURN 99 CALL AST_PUTLINE( BUFFER, -1, STATUS ) END \end{terminalv} \normalsize Our main program might then look something like this (omitting error checking for brevity): \small \begin{terminalv} EXTERNAL SOURCE ... * Open the input file. OPEN( UNIT = 1, FILE = 'infile.ast', STATUS = 'OLD' ) * Create the Channel and read an Object from it. CHANNEL = AST_CHANNEL( SOURCE, AST_NULL, ' ', STATUS ) OBJECT = AST_READ( CHANNEL, STATUS ) ... * Annul the Channel and close the file when done. CALL AST_ANNUL( CHANNEL, STATUS ) CLOSE( 1 ) \end{terminalv} \normalsize Here, we first open the required input file. We then pass the name of our SOURCE routine as the first argument to AST\_CHANNEL when creating a new Channel (ensuring that SOURCE also appears in an EXTERNAL statement). When we read an \htmlref{Object}{Object} from this Channel using \htmlref{AST\_READ}{AST\_READ}, the SOURCE routine will be called to obtain the textual data from the file, the end-of-file being detected when it yields a negative line length. Note, if a value is set for the SourceFile attribute, the AST\_READ function will ignore any source routine specified when the Channel was created. \subsection{\label{ss:channelsink}Writing Objects to Files} As for reading, writing Objects to files can be done in two different ways. Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}. For instance, the following will write a pair of Objects to a text file called ``fred.txt'': \small \begin{terminalv} CALL AST_SET( CHANNEL, 'SinkFile=fred.txt', STATUS ) NOBJ = AST_WRITE( CHANNEL, OBJECT1, STATUS ) NOBJ = AST_WRITE( CHANNEL, OBJECT2, STATUS ) CALL AST_CLEAR( CHANNEL, 'SinkFile', STATUS ) \end{terminalv} \normalsize Note, the act of clearing the attribute tells AST that no more output will be written to the file and so the file is then closed. If the attribute is not cleared, the file will remain open and further Objects can be written to it. The file will always be closed when the Channel is deleted. If the details of the language's I/O system on the computer you are using means that the above approach cannot be used, then we can write a SINK routine, that obtains a line of output text from the AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE} and then writes it to a file. We can use this in basically the same way as the SOURCE routine in the previous section (\secref{ss:channelsource}): \small \begin{terminalv} SUBROUTINE SINK( STATUS ) INTEGER L, STATUS CHARACTER * ( 200 ) BUFFER CALL AST_GETLINE( BUFFER, L, STATUS ) IF ( L .GT. 0 ) WRITE( 2, '(A)' ) BUFFER( : L ) END \end{terminalv} \normalsize In this case, our main program would supply the name of this SINK routine as the second argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL} (ensuring that it also appears in an EXTERNAL statement), as follows: \small \begin{terminalv} EXTERNAL SINK ... * Open the output file. OPEN( UNIT = 2, FILE = 'outfile.ast', STATUS = 'NEW' ) * Create a Channel and write an Object to it. CHANNEL = AST_CHANNEL( SOURCE, SINK, ' ', STATUS ) NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS ) ... * Annul the Channel and close the file when done. CALL AST_ANNUL( CHANNEL, STATUS ) CLOSE( 2 ) \end{terminalv} \normalsize Note that we can specify a source and/or a sink routine for the Channel, and that these may use either the same file, or different files according to whether we are reading or writing. AST has no knowledge of the underlying file system, nor of file positioning. It just reads and writes sequentially. If you wish, for example, to reposition a file at the beginning in between reads and writes, then this can be done directly (and completely independently of AST) using standard Fortran statements. If an error occurs in your source or sink routine, you can communicate this to the AST library by setting the STATUS argument to any error value. This will immediately terminate the read or write operation. Note, if a value is set for the SinkFile attribute, the \htmlref{AST\_WRITE}{AST\_WRITE} function will ignore any sink routine specified when the Channel was created. \subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places} It should be obvious from the above (\secref{ss:channelsource} and \secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink routines provide a flexible means of intercepting textual data that describes AST Objects as it flows in and out of your program. In fact, you might like to regard a Channel simply as a filter for converting AST Objects to and from a stream of text which is then handled by your source and sink routines, where the real I/O occurs. This gives you the ability to store AST Objects in virtually any data system, so long as you can convert a stream of text into something that can be stored (it need no longer be text) and retrieve it again. There is generally no need to retain comments. Other possibilities, such as inter-process and network communication, could also be implemented \emph{via} source and sink functions in basically the same way. \cleardoublepage \section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)} A FITS header is a sequence of 80-character strings, formatted according to particular rules defined by the Flexible Image Transport \htmlref{System}{System} (FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/} is a widely-used standard for data interchange in astronomy and has also been adopted as a data processing format in some astronomical data reduction systems. The individual 80-character strings in a FITS header are usually called \emph{cards} or \emph{header cards} (for entirely anachronistic reasons). A sequence of FITS cards appears as a header at the start of every FITS data file, and sometimes also at other points within it, and is used to provide ancillary information which qualifies or describes the main array of data stored in the file. As such, FITS headers are prime territory for storing information about the coordinate systems associated with data held in FITS files. In this section, we will examine how to store information in FITS headers directly in the form of AST Objects---a process which is supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our discussion here will turn out to be a transitional step that emphasises the similarities between a FitsChan and a Channel (\secref{ss:channels}). At the same time, it will prepare us for the next section (\secref{ss:foreignfits}), where we will examine how to use a FitsChan to tackle some of the more difficult problems that FITS headers can present. \subsection{\label{ss:nativeencoding}The Native FITS Encoding} As it turns out, we are not the first to have thought of storing WCS information in FITS headers. In fact, the original FITS standard (1981 vintage) defined a set of header keywords for this purpose which have been widely used, although they have proved too limited for many practical purposes. At the time of writing, a number of different ways of using FITS headers for storing WCS information are in use, most (although not all) based on the original standard. We will refer to these alternative ways of storing the information as FITS \emph{encodings} but will defer a discussion of their advantages and limitations until the next section (\secref{ss:foreignfits}). Here, we will examine how to store AST Objects directly in FITS headers. In effect, this defines a new encoding, which we will term the \emph{native encoding}. This is a special kind of encoding, because not only does it allow us to associate conventional WCS calibration information with FITS data, but it also allows any other information that can be expressed in terms of AST Objects to be stored as well. In fact, the native encoding provides us with facilities roughly analogous to those of the \htmlref{Channel}{Channel} (\secref{ss:channels})---\emph{i.e.}\ a lossless way of transferring AST Objects from program to program---but based on FITS headers instead of free-format text. \subsection{The FitsChan Model} I/O between AST Objects and FITS headers is supported by a specialised form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which may hold any number, including zero, of FITS header cards. This buffer forms a workspace in which you can assemble FITS cards and manipulate them before writing them out to a file. By default, when a FitsChan is first created, it contains no cards and there are five ways of inserting cards into it: \begin{enumerate} \item You may add cards yourself, one at a time, using \htmlref{AST\_PUTFITS}{AST\_PUTFITS} (\secref{ss:addingfitscards}). \item You may add cards yourself, supplying all cards concatenated into a single string, using \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}. (\secref{ss:addingmulticards}). \item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}), which will have the effect of creating new cards within the FitsChan which describe the Object (\secref{ss:writingnativefits}). \item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan. The value should be the path to a text file holding a set of FITS header cards, one per line. When the SourceFile value is set (using AST\_SETC or \htmlref{AST\_SET}{AST\_SET}). the file is opened and the headers copied from it into the FitsChan. The file is then immediately closed. \item You may specify a source routine which reads data from some external store of FITS cards, just like the source associated with a basic Channel (\secref{ss:channelsource}). If you supply a source routine, it will be called when the FitsChan is created in order to fill it with an initial set of cards (\secref{ss:fitssourceandsink}). \end{enumerate} There are also four ways of removing cards from a FitsChan: \begin{enumerate} \item You may delete cards yourself, one at a time, using \htmlref{AST\_DELFITS}{AST\_DELFITS} (\secref{ss:findingandchangingfits}). \item You may read an AST Object from the FitsChan (using \htmlref{AST\_READ}{AST\_READ}), which will have the effect of removing those cards from the FitsChan which describe the Object (\secref{ss:readingnativefits}). \item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When the FitsChan is deleted, any remaining headers are written out to a text file with path equal to the value of the SinkFile attribute. \item Alternatively, You may specify a sink routine which writes data to some external store of FITS cards, just like the sink associated with a basic Channel (\secref{ss:channelsink}). If you supply a sink routine, it will be called when the FitsChan is deleted in order to write out any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note, the sink routine is not called if the SinkFile attribute has been set. \end{enumerate} Note, in particular, that reading an AST Object from a FitsChan is \emph{destructive}. That is, it deletes the FITS cards that describe the Object. The reason for this is explained in \secref{ss:destructiveread}. In addition to the above, you may also read individual cards from a FitsChan using the function \htmlref{AST\_FINDFITS}{AST\_FINDFITS} (which is not destructive). This is the main means of writing out FITS cards if you have not supplied a sink routine. AST\_FINDFITS also provides a means of searching for particular FITS cards (by keyword, for example) and there are other facilities for overwriting cards when required (\secref{ss:findingandchangingfits}). \subsection{\label{ss:creatingafitschan}Creating a FitsChan} The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{AST\_FITSCHAN}{AST\_FITSCHAN}, is straightforward to use: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER FITSCHAN, STATUS STATUS = 0 ... FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, 'Encoding=NATIVE', STATUS ) \end{terminalv} \normalsize Here, we have omitted any source or sink functions by supplying the AST\_NULL routine for the first two arguments (remember to include the AST\_PAR include file which contains the required EXTERNAL statement for this routine). We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to NATIVE. This indicates that we will be using the native encoding (\secref{ss:nativeencoding}) to store and retrieve Objects. If this was left unspecified, the default would depend on the FitsChan's contents. An attempt is made to use whatever encoding appears to have been used previously. For an empty FitsChan, the default is NATIVE, but it does no harm to be sure. \subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan} Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a mechanism is needed for addressing them. This allows you to specify where new cards are to be added, for example, or which card is to be deleted. This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which gives the index of the \emph{current card} in the FitsChan. You can nominate any card you like to be current, simply by setting a new value for the Card attribute, for example: \small \begin{terminalv} INTEGER ICARD ... CALL AST_SETI( FITSCHAN, 'Card', ICARD, STATUS ) \end{terminalv} \normalsize where ICARD contains the index of the card on which you wish to operate next. Some functions will update the Card attribute as a means of advancing through the sequence of cards, when reading them for example, or to indicate which card matches a search criterion. The default value for Card is one, which is the index of the first card. This means that you can ``rewind'' a FitsChan to access its first card by clearing the Card attribute: \small \begin{terminalv} CALL AST_CLEAR( FITSCHAN, 'Card', STATUS ) \end{terminalv} \normalsize The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard} attribute. This is a read-only attribute whose value is automatically updated as you add or remove cards. It means you can address all the cards in sequence using a loop such as the following: \small \begin{terminalv} DO 1 ICARD = 1, AST_GETI( FITSCHAN, 'Ncard', STATUS ) CALL AST_SETI( FITSCHAN, 'Card', ICARD, STATUS ) 1 CONTINUE \end{terminalv} \normalsize However, it is usually possible to write slightly tidier loops based on the \htmlref{AST\_FINDFITS}{AST\_FINDFITS} function described later (\secref{ss:extractingfitscards} and \secref{ss:findingandchangingfits}). If you set the Card attribute to a value larger than Ncard, the FitsChan is regarded as being positioned at its \emph{end-of-file}. In this case there is no current card and an attempt to obtain a value for the Card attribute will always return the value Ncard~$+$~1. When a FitsChan is empty, it is always at the end-of-file. \subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan} Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you can write any AST \htmlref{Object}{Object} to it in the native encoding using the \htmlref{AST\_WRITE}{AST\_WRITE} function. Let us assume we are writing a \htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet}, but for purposes of illustration a SkyFrame contains a more manageable amount of data.} as follows: \small \begin{terminalv} INTEGER NOBJ, SKYFRAME ... NOBJ = AST_WRITE( FITSCHAN, SKYFRAME, STATUS ) \end{terminalv} \normalsize Since we have selected the native encoding (\secref{ss:nativeencoding}), there are no restrictions on the class of Object we may write, so AST\_WRITE should always return a value of one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), this write operation will not produce any output from our program. The FITS headers produced are simply stored inside the FitsChan. After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card} attribute will point at the card immediately after the last one written. Since our FitsChan was initially empty, the Card attribute will, in this example, point at the end-of-file (\secref{ss:addressingfitscards}). The FITS standard imposes a limit of 68 characters on the length of strings which may be stored in a single header card. Sometimes, a description of an AST Object involves the use of strings which exceed this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If this occurs, the long string will be split over two or more header cards. Each ``continuation'' card will have the keyword \texttt{CONTINUE} in columns 1 to 8, and will contain a space in column 9 (instead of the usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of each of the strings (except the last one) to indicate that the string is continued on the next card. Note, this splitting of long strings over several cards only occurs when writing AST Objects to a FitsChan using the AST\_WRITE routine and the \emph{native} encoding. If a long string is stored in a FitsChan using (for instance) the \htmlref{AST\_PUTFITS}{AST\_PUTFITS} or \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS} routine, it will simply be truncated. \subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan} To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame} above (\secref{ss:writingnativefits}), we must write a simple loop to extract each card in turn and print it out. We must also remember to rewind the FitsChan first, \emph{e.g.}\ using \htmlref{AST\_CLEAR}{AST\_CLEAR}. The following loop would do: \small \begin{terminalv} CHARACTER * ( 80 ) CARD ... CALL AST_CLEAR( FITSCHAN, 'Card', STATUS ) 2 CONTINUE IF ( AST_FINDFITS( FITSCHAN, '%f', CARD, .TRUE., STATUS ) ) THEN WRITE ( *, '(A)' ) CARD GO TO 2 END IF \end{terminalv} \normalsize Here, we have used the \htmlref{AST\_FINDFITS}{AST\_FINDFITS} function to find a FITS card by keyword. It is given a keyword template of ``\%f'', which matches any FITS keyword, so it always finds the current card, which it returns. Its fourth argument is set to .TRUE., to indicate that the \htmlref{Card}{Card} attribute should be incremented afterwards so that the following card will be found the next time around the loop. AST\_FINDFITS returns .FALSE.\ when it reaches the end-of-file and this terminates the loop. If we were storing the FITS headers in an output FITS file instead of printing them out, we might use a loop like this but replace the WRITE statement with a call to a suitable data access routine to store the header card. This would only be necessary if we had not provided a sink routine for the FitsChan (\secref{ss:fitssourceandsink}). \subsection{The Native FitsChan Output Format} If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote earlier (\secref{ss:writingnativefits}), we should obtain something like the following: \small \begin{terminalv} COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST COMMENT AST Beginning of AST data for SkyFrame object AST COMMENT AST ................................................................ AST BEGAST_A= 'SkyFrame' / Description of celestial coordinate system NAXES_A = 2 / Number of coordinate axes AX1_A = ' ' / Axis number 1 BEGAST_B= 'SkyAxis ' / Celestial coordinate axis ENDAST_A= 'SkyAxis ' / End of object definition AX2_A = ' ' / Axis number 2 BEGAST_C= 'SkyAxis ' / Celestial coordinate axis ENDAST_B= 'SkyAxis ' / End of object definition ISA_A = 'Frame ' / Coordinate system description SYSTEM_A= 'FK4-NO-E' / Celestial coordinate system type EPOCH_A = 1958.0 / Besselian epoch of observation ENDAST_C= 'SkyFrame' / End of object definition COMMENT AST ................................................................ AST COMMENT AST End of AST data for SkyFrame object AST COMMENT AST ---------------------------------------------------------------- AST \end{terminalv} \normalsize As you can see, this resembles the information that would be written to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame (\secref{ss:textualoutputformat}), except that it has been formatted into 80-character header cards according to FITS conventions. There are also a number of other differences worth noting: \begin{enumerate} \item There is no unnecessary information about default values provided for the benefit of the human reader. This is because the \htmlref{Full}{Full} attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You can restore the information if you wish by setting Full to 0 or $+$1, in which case additional COMMENT cards will be generated to hold it. \item The information is not indented, because FITS does not allow this. However, if you change the Full attribute to 0 or $+$1, comments will be included that are intended to help break up the sequence of headers and highlight its structure. This will probably only be of use if you are attempting to track down a problem by examining the FITS cards produced in detail. \item The FITS keywords which appear to the left of the ``$=$'' signs have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to them. This is done in order to make each keyword unique. \end{enumerate} This last point is worth further comment and is necessary because the FITS standard only allows for certain keywords (such as COMMENT and HISTORY) to appear more than once. \htmlref{AST\_WRITE}{AST\_WRITE} therefore appends an arbitrary sequence of two characters to each new keyword it generates in order to ensure that it does not duplicate any already present in the FitsChan. The main risk from not following this convention is that some software might ignore (say) all but the last occurrence of a keyword before passing the FITS headers on. Such an event is unlikely, but would obviously destroy the information present, so AST\_WRITE enforces the uniqueness of the keywords it uses. The extra characters added are ignored when the information is read back. As with a basic Channel, you can also suppress the comments produced in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to zero (\secref{ss:channelcommenting}). However, FITS headers are traditionally generously commented, so this is not recommended. \subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan} To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back as Objects for example, you should use the \htmlref{AST\_PUTFITS}{AST\_PUTFITS} routine. You can insert a card in front of the current one as follows: \small \begin{terminalv} CALL AST_PUTFITS( FITSCHAN, CARD, .FALSE., STATUS ) \end{terminalv} \normalsize where the third argument of .FALSE.\ indicates that the current card should not be overwritten. Note that facilities are not provided by AST for formatting the card contents. After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the original Card, or at the end-of-file if the FitsChan was originally empty. Entering a sequence of cards is therefore straightforward. If CARDS is an array of character strings containing FITS header cards and NCARDS is the number of cards, then a loop such as the following will insert the cards in sequence into a FitsChan: \small \begin{terminalv} INTEGER NCARD CHARACTER * ( 80 ) CARDS( NCARD ) ... DO 3 ICARD = 1, NCARD CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS ) 3 CONTINUE \end{terminalv} \normalsize Note that AST\_PUTFITS enforces the validity of a FitsChan by rejecting any cards which do not adhere to the FITS standard. If any such cards are detected, an error will result. \subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan} If you have all your cards concatenated together into a single long string, each occupying 80 characters (with no delimiters), you can insert them into a \htmlref{FitsChan}{FitsChan} in a single call using \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}. This call first empties the supplied FitsChan of any existing cards, then inserts the new cards, and finally rewinds the FitsChan so that a subsequent call to \htmlref{AST\_READ}{AST\_READ} will start reading from the first supplied card. The AST\_PUTCARDS routine uses \htmlref{AST\_PUTFITS}{AST\_PUTFITS} internally to interpret and store each individual card, and so the caveats in \secref{ss:addingfitscards} should be read. \subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan} Once you have stored a FITS header description of an \htmlref{Object}{Object} in a \htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}), you can read it back using \htmlref{AST\_READ}{AST\_READ} in much the same way as with a basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments about validating the Object you read also apply (\secref{ss:validatinginput}). If you have just written to the FitsChan, you must remember to rewind it first: \small \begin{terminalv} INTEGER OBJECT ... CALL AST_CLEAR( FITSCHAN, 'Card', STATUS ) OBJECT = AST_READ( FITSCHAN, STATUS ) \end{terminalv} \normalsize An important feature of a FitsChan is that read operations are destructive. This means that if an Object description is found, it will be consumed by AST\_READ which will remove all the cards involved, including associated COMMENT cards, from the FitsChan. Thus, if you write an Object to a FitsChan, rewind, and read the same Object back, you should end up with the original FitsChan contents. If you need to circumvent this behaviour for any reason, it is a simple matter to make a copy of a FitsChan using \htmlref{AST\_COPY}{AST\_COPY} (\secref{ss:copyingobjects}). If you then read from the copy, the original FitsChan will remain untouched. After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the card immediately following the last card read, or the end-of-file of there are no more cards. Since the \emph{native} encoding is being used, any long strings involved in the object description will have been split into two or more adjacent contuation cards when the Object was stored in the header using routine \htmlref{AST\_WRITE}{AST\_WRITE}. The AST\_READ routine reverses this process by concatenating any such adjacent continuation cards to re-create the original long string. \subsection{Saving and Restoring Multiple Objects in a FitsChan} When using the native FITS encoding, multiple Objects may be stored and all I/O operations are sequential. This means that you can simply write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation, the \htmlref{Card}{Card} attribute will be updated so that the next write appends the next \htmlref{Object}{Object} description to the previous one. If you then rewind the FitsChan, you can read the Objects back in the original order. Reading them back will, of course, remove their descriptions from the FitsChan (\secref{ss:readingnativefits}) but the behaviour of the Card attribute is such that successive reads will simply return each Object in sequence. The only thing that may require care, given that a FitsChan can always be addressed randomly by setting its Card attribute, is to avoid writing one Object on top of another. For obvious reasons, the Object descriptions in a FitsChan must remain separate if they are to make sense when read back. \subsection{Mixing Native Objects with Other FITS Cards} Of course, any real FITS header will contain other information besides AST Objects, if only the mandatory FITS cards that must accompany all FITS data. When FITS headers are read in from a real dataset, therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with many other cards. Because this is the normal state of affairs, the boolean (integer) \htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when you read an Object From a FitsChan, any irrelevant cards will simply be skipped over until the start of the next Object description, if any, is found. If you start reading part way through an Object description, no error will result. The remainder of the description will simply be skipped. Setting Skip to zero will change this behaviour to resemble that of a basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data are not permitted by default, but this will probably rarely be useful. \subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan} You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by keyword, using the function \htmlref{AST\_FINDFITS}{AST\_FINDFITS}. This performs a search, starting at the current card, until it finds a card whose keyword matches the template you supply, or the end-of-file is reached. If a suitable card is found, AST\_FINDFITS returns the card's contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to identify the card found, or the one following it. The way you want the Card attribute to be set is indicated by the fourth (logical) argument to AST\_FINDFITS. A value of .TRUE.\ is returned to indicate success. If a suitable card cannot be found, AST\_FINDFITS returns a value of .FALSE.\ to indicate failure and sets the FitsChan's Card attribute to the end-of-file. Requesting that the Card attribute be set to indicate the card that AST\_FINDFITS finds is useful if you want to replace that card with a new one, as in this example: \small \begin{terminalv} CHARACTER * ( 80 ) NEWCARD LOGICAL JUNK ... JUNK = AST_FINDFITS( FITSCHAN, 'AIRMASS', CARD, .FALSE., STATUS ) CALL AST_PUTFITS( FITSCHAN, NEWCARD, .TRUE., STATUS ) \end{terminalv} \normalsize Here, AST\_FINDFITS is used to search for a card with the keyword AIRMASS. If the card is found, \htmlref{AST\_PUTFITS}{AST\_PUTFITS} then overwrites it with a new card. Otherwise, the Card attribute ends up pointing at the end-of-file and the new card is simply appended to the end of the FitsChan. A similar approach can be used to delete selected cards from a FitsChan using \htmlref{AST\_DELFITS}{AST\_DELFITS}, which deletes the current card: \small \begin{terminalv} IF ( AST_FINDFITS( FITSCHAN, 'BSCALE', CARD, .FALSE., STATUS ) ) THEN CALL AST_DELFITS( FITSCHAN, STATUS ) END IF \end{terminalv} \normalsize This deletes the first card, if any, with the BSCALE keyword. Requesting that AST\_FINDFITS increments the Card attribute to identify the card following the one found is more useful when writing loops. For example, the following loop extracts each card whose keyword matches the template ``CD\%6d'' (that is, ``CD'' followed by six decimal digits): \small \begin{terminalv} 4 CONTINUE IF ( AST_FINDFITS( FITSCHAN, 'CD%6d', CARD, .TRUE., STATUS ) ) THEN GO TO 4 END IF \end{terminalv} \normalsize For further details of keyword templates, see the description of AST\_FINDFITS in \appref{ss:functiondescriptions}. \subsection{\label{ss:fitssourceandsink}Source and Sink Routines for FitsChans} The use of source and sink routines with a \htmlref{FitsChan}{FitsChan} is optional. This is because you can always arrange to explicitly fill a FitsChan with FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards}) and you can also extract any cards that remain and write them out yourself (\secref{ss:extractingfitscards}) before you delete the FitsChan. If you choose to use these routines, however, they behave in a very similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource} and \secref{ss:channelsink}). You supply these routines, as arguments to the constructor function \htmlref{AST\_FITSCHAN}{AST\_FITSCHAN} when you create the FitsChan (\secref{ss:creatingafitschan}). The source routine is invoked implicitly at this point to fill the FitsChan with FITS cards and the FitsChan is then rewound, so that the first card becomes current. The sink routine is automatically invoked later, when the FitsChan is deleted, in order to write out any cards that remain in it. The only real difference between the source and sink routines for a FitsChan and a basic Channel is that FITS cards are limited in length to 80~characters, so the choice of buffer size is simplified. This affects the way the card contents are passed, so the routines themselves are slightly different. The following is therefore the FitsChan equivalent of the Channel SOURCE routine given in \secref{ss:channelsource}: \small \begin{terminalv} INTEGER FUNCTION FITSSOURCE( CARD, STATUS ) CHARACTER * ( 80 ) CARD INTEGER STATUS READ( 1, '(A)', END = 99 ) CARD FITSSOURCE = 1 RETURN 99 FITSSOURCE = 0 END \end{terminalv} \normalsize Here, the FITS card contents are returned \emph{via} the CARD argument (the \htmlref{AST\_PUTLINE}{AST\_PUTLINE} routine should not be used) and the function returns 1 to indicate that a card has been read. A value of zero is returned if there are no more cards to read. The sink routine for a FitsChan is also a little different (\emph{c.f.}\ the SINK routine in~\secref{ss:channelsink}), as follows: \small \begin{terminalv} SUBROUTINE FITSSINK( CARD, STATUS ) CHARACTER * ( 80 ) CARD INTEGER STATUS WRITE( 2, '(A)' ) CARD END \end{terminalv} \normalsize The contents of the FITS card being written are passed \emph{via}\ the CARD argument (the \htmlref{AST\_GETLINE}{AST\_GETLINE} routine should not be used). Of course, both of these examples assume that you are accessing text files. If this is not the case, then appropriate changes to the I/O statements would be needed. The details obviously depend on the format of the file you are handling, which need not necessarily be a true FITS file. \cleardoublepage \section{\label{ss:foreignfits}Using Foreign FITS Encodings} We saw in the previous section (\secref{ss:nativefits}) how to store and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a \htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to NATIVE. However, the Objects we wrote could then only be read back by other programs that use AST. In practice, we will also encounter FITS headers containing WCS information written by other software systems. We will probably also need to write FITS headers in a format that can be understood by these systems. Indeed, this interchange of data is one of the main reasons for the existence of FITS, so in this section we will examine how to accommodate these requirements. \subsection{\label{ss:foreignencodings}The Foreign FITS Encodings} As mentioned previously (\secref{ss:nativeencoding}), there are a number of conventions currently in use for storing WCS information in FITS headers, which we call \emph{encodings}. Here, we are concerned with those encodings defined by software systems other than AST, which we term \emph{foreign encodings}. Currently, AST supports six foreign encodings, which may be selected by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the following (character string) values: \begin{quote} \begin{description} \item[DSS]\mbox{}\\ This encoding stores WCS information using the convention developed at the Space Telescope Science Institute for the Digitised Sky Survey (DSS) astrometric plate calibrations. DSS images which use this convention are widely available and it is understood by a number of important and well-established astronomy applications. However, the calibration model used (based on a polynomial fit) is not easily applicable to other types of data and creating the polynomial coefficients needed to calibrate your own images can prove difficult. For this reason, the DSS encoding is probably best viewed as a ``read-only'' format. It is possible, however, to read in WCS information using this encoding and then to write it back out again, so long as only minor changes have been made. \item[FITS-WCS]\mbox{}\\ This encoding is very important because it is based on a new FITS standard which should, for the first time, address the problem of celestial coordinate systems in a proper manner, by considerably extending the original FITS standard. The conventions used are described in a series of papers by E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the ``FITS-WCS papers''. They are described at \url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers in this series have been agreed, this encoding should be understood by any FITS-WCS compliant software and it is likely to be adopted widely for FITS data in future. For details of the coverage of these conventions provided by the FitsChan class, see \appref{ss:fitswcscoverage}. \item[FITS-IRAF]\mbox{}\\ This encoding is based on the conventions described in the document ``World Coordinate Systems Representations Within the FITS Format'' by R.J. Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. This encoding is in effect a sub-set of the current FITS-WCS encoding. \item[FITS-PC]\mbox{}\\ This encoding is based on a previous version of the proposed new FITS WCS standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe axis rotation and scaling. Versions of AST prior to V1.5 used this scheme for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j} keywords instead.\footnote{There are many other differences between the previous and the current FITS-WCS encodings. The keywords to describe axis rotation and scaling is used purely as a label to identify the scheme.} The FITS-PC encoding is included in AST V1.5 only to allow FITS-WCS data created with previous versions to be read. It should not, in general, be used to create new data sets. \item[FITS-AIPS]\mbox{}\\ This encoding is based on the conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS data analysis facility, so its use will facilitate data exchange with AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to describe axis rotation and scaling. \item[FITS-AIPS++]\mbox{}\\ Encodes coordinate system information in FITS header cards using the conventions used by the AIPS++ project. This is an extension of FITS-AIPS which includes some of the features of FITS-PC and FITS-IRAF. \end{description} \end{quote} For more detail about the above encodings, see the description of the Encoding attribute in \appref{ss:attributedescriptions}. \subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings} The foreign encodings available for storing WCS information in FITS headers have a number of limitations when compared with the native encoding of AST Objects (\secref{ss:nativefits}). The main ones are: \begin{enumerate} \item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented using a foreign FITS encoding. This should not come as a surprise, because the purpose of storing WCS information in FITS headers is to attach coordinate systems to an associated array of data. Since the FrameSet is the AST Object designed for the same purpose (\secref{ss:baseandcurrent}), there is a natural correspondence. The way in which a FrameSet is translated to and from the foreign encoding also follows from this correspondence. The FrameSet's base \htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS data. These are the same as FITS pixel coordinates, in which the first pixel (in 2 dimensions) has coordinates (1,1) at its centre. Similarly, the current Frame of the FrameSet identifies the FITS world coordinate system associated with the data. \item You may store a representation of only a single FrameSet in any individual set of FITS header cards (\emph{i.e.}\ in a single \htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may over-write the previous one or generate an invalid representation of your WCS information. This is mainly a consequence of the use of fixed FITS keywords by foreign encodings and the fact that you cannot, in general, have multiple FITS cards with the same keyword. \item In general, it will not be possible to store every possible FrameSet that you might construct. Depending on the encoding, only certain FrameSets that conform to particular restrictions can be represented and, even then, some of their information may be lost. See the description of the \htmlref{Encoding}{Encoding} attribute in \appref{ss:attributedescriptions} for more details of these limitations. \end{enumerate} It should be understood that using foreign encodings to read and write information held in AST Objects is essentially a process of converting the data format. As such, it potentially suffers from the same problems faced by all such processes, \emph{i.e.}\ differences between the AST data model and that of the foreign encoding may cause some information to be lost. Because the AST model is extremely flexible, however, any data loss can largely be eliminated when reading. Instead, this effect manifests itself in the form of the above encoding-dependent restrictions on the kind of AST Objects which may be written. One of the aims of the AST library, of course, is to insulate you from the details of these foreign encodings and the restrictions they impose. We will see shortly, therefore, how AST provides a mechanism for determining whether your WCS information satisfies the necessary conditions and allows you to make an automatic choice of which encoding to use. \subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input} Let us now examine the practicalities of extracting WCS information from a set of FITS header cards which have been written by some other software system. We will pretend that our program does not know which encoding has been used for the WCS information and must discover this for itself. In order to have a concrete example, however, we will use the following set of cards. These use the FITS-AIPS encoding and contain a typical mix of other FITS cards which are irrelevant to the WCS information in which we are interested: \small \begin{terminalv} SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 BITPIX = -32 / Bits per pixel. NAXIS = 2 / Number of dimensions NAXIS1 = 300 / Length of x axis. NAXIS2 = 300 / Length of y axis. CTYPE1 = 'GLON-ZEA' / X-axis type CTYPE2 = 'GLAT-ZEA' / Y-axis type CRVAL1 = -149.56866 / Reference pixel value CRVAL2 = -19.758201 / Reference pixel value CRPIX1 = 150.500 / Reference pixel CRPIX2 = 150.500 / Reference pixel CDELT1 = -1.20000 / Degrees/pixel CDELT2 = 1.20000 / Degrees/pixel CROTA1 = 0.00000 / Rotation in degrees. SURVEY = 'COBE DIRBE' BUNITS = 'MJy/sr ' / ORIGIN = 'CDAC ' / Cosmology Data Analysis Center TELESCOP= 'COBE ' / COsmic Background Explorer satellite INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] PIXRESOL= 9 / Quad tree pixel resolution [6, 9] DATE = '27/09/94' / FITS file creation date (dd/mm/yy) DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) COMMENT COBE specific keywords DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) \end{terminalv} \normalsize The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into it. If CARDS is an array of character strings holding the header cards and NCARDS is the number of cards, this could be done as follows: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER FITSCHAN, ICARD, NCARD, STATUS CHARACTER * ( 80 ) CARDS( NCARD ) STATUS = 0 ... FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS ) DO 1 ICARD = 1, NCARD CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS ) 1 CONTINUE \end{terminalv} \normalsize Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to use the native encoding. This is because we are pretending not to know which encoding to use and want AST to determine this for us. By leaving the Encoding attribute un-set, its default value will adjust to whichever encoding AST considers to be most appropriate, according to the FITS header cards present. For details of how this choice is made, see the description of the Encoding attribute in \appref{ss:attributedescriptions}. This approach has the obvious advantages of making our program simpler and more flexible and of freeing us from having to know about the different encodings available. As a bonus, it also means that the program will be able to read any new encodings that AST may support in future, without needing to be changed. At this point, we could enquire the default value of the Encoding attribute, which indicates which encoding AST intends to use, as follows: \small \begin{terminalv} CHARACTER * ( 20 ) ENCODE ... ENCODE = AST_GETC( FITSCHAN, 'Encoding', STATUS ) \end{terminalv} \normalsize The result of this enquiry would be the string ``FITS-AIPS''. Note that we could also have set the FitsChan's Encoding attribute explicitly, such as when creating it: \small \begin{terminalv} FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, 'Encoding=FITS-AIPS', STATUS ) \end{terminalv} \normalsize If we tried to read information using this encoding (\secref{ss:readingforeignfits}), but failed, we could then change the encoding and try again. This would allow our program to take control of how the optimum choice of encoding is arrived at. However, it would also involve using explicit knowledge of the encodings available and this is best avoided if possible. \subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header} Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined how the WCS information is encoded (\secref{ss:identifyingfitsencoding}), the next step is to read an AST \htmlref{Object}{Object} from the FitsChan using \htmlref{AST\_READ}{AST\_READ}. We must also remember to rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card} attribute, which defaults to 1: \small \begin{terminalv} INTEGER WCSINFO ... CALL AST_CLEAR( FITSCHAN, 'Card', STATUS ) WCSINFO = AST_READ( FITSCHAN, STATUS ) \end{terminalv} \normalsize If the pointer returned by AST\_READ is not equal to AST\_\_NULL, then an Object has been read successfully. Otherwise, there was either no information to read or the choice of FITS encoding (\secref{ss:identifyingfitsencoding}) was inappropriate. At this point you might like to indulge in a little data validation along the lines described in \secref{ss:validatinginput}, for example: \small \begin{terminalv} IF ( AST_GETC( WCSINFO, 'Class', STATUS ) .EQ. 'FrameSet' ) THEN ELSE END IF \end{terminalv} \normalsize If a foreign encoding has definitely been used, then the Object will automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so this stage can be omitted. However, if the native encoding (\secref{ss:nativeencoding}) might have been employed, which is a possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then any class of Object might have been read and a quick check would be worthwhile. If you used \htmlref{AST\_SHOW}{AST\_SHOW} (\secref{ss:displayingobjects}) to examine the FrameSet which results from reading our example FITS header (\secref{ss:identifyingfitsencoding}), you would find that its base \htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which incorporates the effects of various rotations, scalings and a ``zenithal equal area'' sky projection, so that each pixel of the FITS image is mapped on to a corresponding sky position in galactic coordinates. Because this FrameSet may be used both as a Mapping (\secref{ss:framesetasmapping}) and as a Frame (\secref{ss:framesetasframe}), it may be employed directly to perform many useful operations without any need to decompose it into its component parts. These include: \begin{itemize} \item Transforming data grid (FITS pixel) coordinates into galactic coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}). \item Formatting coordinate values (either pixel or galactic coordinates) ready for display to a user (\secref{ss:formattingaxisvalues} and \secref{ss:normalising}). \item Enquiring about axis labels (or other axis information---\secref{ss:frameattributes}) which might be used, for example, to label columns of coordinates in a table (\secref{ss:frameaxisattributes}). \item Aligning the image with another image from which a similar FrameSet has been obtained (\secref{ss:registeringimages}). \item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay a variety of graphical information (including a coordinate grid---Figure~\ref{fig:gridplot}) on the displayed image. \item Generating a new FrameSet which reflects any geometrical processing you perform on the associated image data (\secref{ss:wcsprocessingexample}). This new FrameSet could then be written out as FITS headers to describe the modified image (\secref{ss:writingforeignfits}). \end{itemize} If the FrameSet contains other Frames (apart from the base and current Frames), then you would also have access to information about other coordinate systems associated with the image. \subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read} It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan} after we have read a \htmlref{FrameSet}{FrameSet} from it (\secref{ss:readingforeignfits}). The following would rewind our FitsChan and display its contents: \small \begin{terminalv} CHARACTER CARD * ( 80 ) ... CALL AST_CLEAR( FITSCHAN, 'Card', STATUS ) 2 CONTINUE IF ( AST_FINDFITS( FITSCHAN, '%f', CARD, .TRUE., STATUS ) ) THEN WRITE ( *, '(A)' ) CARD GO TO 2 END IF \end{terminalv} \normalsize The output, if we started with the example FITS header in \secref{ss:identifyingfitsencoding}, might look like this: \small \begin{terminalv} SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 BITPIX = -32 / Bits per pixel. NAXIS = 2 / Number of dimensions NAXIS1 = 300 / Length of x axis. NAXIS2 = 300 / Length of y axis. SURVEY = 'COBE DIRBE' BUNITS = 'MJy/sr ' ORIGIN = 'CDAC ' / Cosmology Data Analysis Center TELESCOP= 'COBE ' / COsmic Background Explorer satellite INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] PIXRESOL= 9 / Quad tree pixel resolution [6, 9] DATE = '27/09/94' / FITS file creation date (dd/mm/yy) DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) COMMENT COBE specific keywords DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) \end{terminalv} \normalsize Comparing this with the original, you can see that all the FITS cards that represent WCS information have been removed. They have effectively been ``sucked out'' of the FitsChan by the destructive read that \htmlref{AST\_READ}{AST\_READ} performs and converted into an equivalent FrameSet. AST remembers where they were stored, however, so that if we later write WCS information back into the FitsChan (\secref{ss:writingforeignfits}) they will, as far as possible, go back into their original locations. This helps to preserve the overall layout of the FITS header. You can now see why AST\_READ performs destructive reads. It is a mechanism for removing WCS information from a FITS header while insulating you, as a programmer, from the details of the encoding being used. It means you can ensure that all relevant header cards have been removed, giving you a clean slate, without having to know which FITS keywords any particular encoding uses. Clearing this WCS information out of a FITS header is particularly important when considering how to write new WCS information back after processing (\secref{ss:writingforeignfits}). If any relevant FITS cards are left over from the input dataset and find their way into the new processed header, they could interfere with the new information being written.\footnote{This can happen if a particular keyword is present in the input header but is not used in the output header (whether particular keywords are used can depend on the WCS information being stored). In such a case, the original value would not be over-written by a new output value, so would remain erroneously present.} The destructive read mechanism ensures that this doesn't happen. \subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps} One of the purposes of AST is to make it feasible to propagate WCS information through successive stages of data processing, so that it remains consistent with the associated image data. As far as possible, this should happen regardless of the FITS encoding used to store the original WCS information. If the data processing being performed does not change the relationship between image pixel and world coordinates (whatever these may be), then propagation of the WCS information is straightforward. You can simply copy the FITS header from input to output. If this relationship changes, however, then the WCS information must be processed alongside the image data and a new FITS header generated to represent it. In this case, the sequence of operations within your program would probably be as follows: \begin{enumerate} \item Read the image data and associated FITS header from the input dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan} (\secref{ss:identifyingfitsencoding}). \item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically using a foreign FITS encoding---\secref{ss:readingforeignfits}). \item Process the image data and modify the FrameSet accordingly (\emph{e.g.}~\secref{ss:wcsprocessingexample}). \item Write the FrameSet back into the FitsChan (\secref{ss:writingforeignfits}). \item Perform any other modification of FITS header cards your program may require. \item Write the FitsChan contents (\emph{i.e.}\ processed header cards) and image data to the output dataset. \end{enumerate} In stage (2), the original WCS information will be removed from the FitsChan by a destructive read. Later, in stage (4), new WCS information is written to replace it. This is the process which we consider next (\secref{ss:writingforeignfits}). \subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header} Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS encoding to use. Unfortunately, we cannot simply depend on the default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the input information (\secref{ss:identifyingfitsencoding}), because the destructive action of reading the WCS data (\secref{ss:destructiveread}) will have altered the FitsChan's contents. This, in turn, will have changed the choice of default encoding, probably causing it to revert to NATIVE. We will return to the question of the optimum choice of encoding below. For now, let's assume we want to use the same encoding for output as we used for input. Since we enquired what that was before we read the input WCS data from the FitsChan (\secref{ss:identifyingfitsencoding}), we can now set that value explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at the same time (because the write will fail if the FitsChan is not rewound). \htmlref{AST\_WRITE}{AST\_WRITE} can then be used to write the output WCS information into the FitsChan: \small \begin{terminalv} INTEGER NOBJ ... CALL AST_SET( FITSCHAN, 'Card=1, Encoding=' // ENCODE, STATUS ) NOBJ = AST_WRITE( FITSCHAN, WCSINFO, STATUS ) \end{terminalv} \normalsize The value returned by AST\_WRITE (assigned to NOBJ) indicates how many Objects were written. This will either be 1 or zero. A value of zero is used to indicate that the information could not be encoded in the form you requested. If this happens, nothing will have been written. If your choice of encoding proves inadequate, the probable reason is that the changes you have made to the FrameSet have caused it to depart from the data model which the encoding assumes. AST knows about the data model used by each encoding and will attempt to simplify the FrameSet you provide so as to fit into that model, thus relieving you of the need to understand the details and limitations of each encoding yourself.\footnote{Storing values in the FitsChan for FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels), before invoking AST\_WRITE can sometimes help to produce a successful write.} When this attempt fails, however, you must consider what alternative encoding to use. Ideally, you would probably want to try a sequence of alternative encodings, using an approach such as the following: \small \begin{terminalv} * 1. CALL AST_SET( FITSCHAN, 'Card=1, Encoding=FITS-WCS', STATUS ) IF ( AST_WRITE( FITSCHAN, WCSINFO, STATUS ) .EQ. 0 ) THEN * 2. CALL AST_SETC( FITSCHAN, 'Encoding', ENCODE, STATUS ) IF ( AST_WRITE( FITSCHAN, WCSINFO, STATUS ) .EQ. 0 ) THEN * 3. CALL AST_SET( FITSCHAN, 'Encoding=NATIVE', STATUS ) NOBJ = AST_WRITE( FITSCHAN, WCSINFO, STATUS ) END IF END IF \end{terminalv} \normalsize That is: \begin{enumerate} \item Start by trying the FITS-WCS encoding, on the grounds that FITS should provide a universal interchange standard in which all WCS information should be expressed if possible. \item If that fails, then try the original encoding used for the input WCS information, on the grounds that you are at least not making the information any harder for others to read than it originally was. \item If that also fails, then you are probably trying to store fairly complex information for which you need the native encoding. Only other AST programs will then be able to read this information, but these are probably the only programs that will be able to do anything sensible with it anyway. \end{enumerate} An alternative approach might be to encode the WCS information in several ways, since this gives the maximum chance that other software will be able to read it. This approach is only possible if there is no significant conflict between the FITS keywords used by the different encodings\footnote{In practice, this means you should avoid mixing FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share many keywords.}. Adopting this approach would simply require multiple calls to AST\_WRITE, rewinding the FitsChan and changing its Encoding value before each one. Unfortunately, however, there is a drawback to duplicating WCS information in the FITS header in this way, because any program which modifies one version of this information and simply copies the remainder of the header will risk producing two inconsistent sets of information. This could obviously be confusing to subsequent software. Whether you consider this a worthwhile risk probably depends on the use to which you expect your data to be put. \cleardoublepage \section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)} \htmladdnormallinkfoot{XML}{http://www.w3.org/XML/} is fast becoming the standard format for passing structured data around the internet, and much general purpose software has been written for tasks such as the parsing, editing, display and transformation of XML data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides facilities for storing AST objects externally in the form of XML documents, thus allowing such software to be used. The primary XML format used by the XmlChan class is a fairly close transliteration of the AST native format produced by the basic Channel class. Currently, there is no DTD or schema defining the structure of data produced in this format by an XmlChan. The following is a native AST representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full} attribute set to zero so that some default attribute values are included as extra comments): \small \begin{terminalv} Begin Frame # Coordinate system description # Title = "1-d coordinate system" # Title of coordinate system Naxes = 1 # Number of coordinate axes Domain = "SCREEN" # Coordinate system domain # Lbl1 = "Axis 1" # Label for axis 1 # Uni1 = "cm" # Units for axis 1 Ax1 = # Axis number 1 Begin Axis # Coordinate axis Unit = "cm" # Axis units End Axis End Frame \end{terminalv} \normalsize The corresponding XmlChan output would look like: \small \begin{terminalv} <_attribute name="Title" quoted="true" value="1-d coordinate system" desc="Title of coordinate system" default="true"/> <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/> <_attribute name="Domain" quoted="true" value="SCREEN" desc="Coordinate system domain"/> <_attribute name="Lbl1" quoted="true" value="Axis 1" desc="Label for axis 1" default="true"/> <_attribute name="Uni1" quoted="true" value="cm" desc="Units for axis 1" default="true"/> <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/> \end{terminalv} \normalsize Notes: \begin{enumerate} \item The AST class name is used as the name for an XML element which contain a description of an AST object. \item AST attributes are described by XML elements with the name ``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML to refer to a ``name=value'' pair within an element start tag. So for instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described within an XML element with name ``\_attribute'' in which the XML attribute ``name'' has the value ``Title'', and the XML attribute ``value'' has the value ``1-d coordinate system''. The moral is always to be clear clear about the context (AST or XML) in which the word \emph{attribute} is being used! \item The XML includes comments both as XML attributes with the name ``desc'', and as separate comment tags. \item Elements which describe default values are identified by the fact that they have an XML attribute called ``default'' set to the value ``true''. These elements are ignored when being read back into an XmlChan. \item The outer-most XML element of an AST object will set the default namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be inherited by all nested elements. \end{enumerate} The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full attributes (inherited from the base Channel class) to zero and -1, resulting in terse output by default. With the default values for these attributes, the above XML is reduced to the following: \small \begin{terminalv} <_attribute name="Naxes" value="1"/> <_attribute name="Domain" quoted="true" value="SCREEN"/> <_attribute name="Unit" quoted="true" value="cm"/> \end{terminalv} \normalsize The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel class. If Skip is zero (the default) then an error will be reported if the text supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If Skip is non-zero, then initial text is skipped over without error until the start of an AST object is found. this allows an AST object to be located within a larger XML document. \subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions} The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML documents which use a restricted subset of an early draft (V1.20) of the IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, and so the STC-X support currently provided by AST is mainly of historical interest. Note, AST also supports the alternative ``STC-S'' linear string description of the STC model (see \secref{ss:stcschans}). STC-X V1.20 is documented at \url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current version is documented at \url{http://www.ivoa.net/Documents/latest/STC-X.html}. When an STC-X document is read using an XmlChan, the read operation produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of \htmlref{Region}{Region}. Specifically, each such Object will be an instance of \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or \htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the \htmlref{XmlFormat}{XmlFormat} attribute for further details. \cleardoublepage \section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)} The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing IVOA ``STC-S'' descriptions. STC-S (see \url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string syntax that allows simple specification of the STC metadata describing a region in an astronomical coordinate system. AST supports a subset of the STC-S specification, allowing an STC-S description of a region within an AST-supported astronomical coordinate system to be converted into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further details, see the full description of the StcsChan class in \appref{ss:classdescriptions}. \cleardoublepage \section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)} \subsection{The Need for Extensibility} However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you will want to transform coordinates in some way that has not been foreseen. You might want to plot a graph in some novel curvilinear coordinate system (perhaps you already have a WCS system in your software and just want to use AST for its graphical capabilities). Alternatively, you might need to calibrate a complex dataset (like an objective prism plate) where each position must be converted to world coordinates with reference to calibration data under the control of an elaborate algorithm. In such cases, it is clear that the basic pre-formed components provided by AST for building Mappings are just not enough. What you need is access to a programming language. However, if you write your own software to transform coordinate values, then it must be made available in the form of an AST class (from which you can create Objects) before it can be used in conjunction with other AST facilities. At this point you might consider writing your own AST class, but this is not recommended. Not only would the internal conventions used by AST take some time to master, but you might also find yourself having to change your software whenever a new version of AST was released. Fortunately, there is a much easier route provided by the \htmlref{IntraMap}{IntraMap} class. \subsection{The IntraMap Model} To allow you to write your own Mappings, AST provides a special kind of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper'' for a coordinate transformation routine written in Fortran. You write this routine yourself and then register it with AST. This, in effect, creates a new class from which you can create Mappings (\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever way your transformation routine specifies. Because IntraMaps are Mappings, they may be used in the same way as any other Mapping. For instance, they may be combined in series or parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}), they may be inverted (\secref{ss:invertingmappings}), you may enquire about their attributes (\secref{ss:gettingattributes}), they may be inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do, however, have some important limitations of which you should be aware before we go on to consider how to create them. \subsection{\label{ss:intramaplimitations}Limitations of IntraMaps} By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is required at all. After all, why not simply write your own coordinate transformation routines in Fortran, wrap them up in IntraMaps and do away with all the other Mapping classes in AST? The reason is not too hard to find. Any transformation routine you write is created solely by you, so it is a private extension which does not form a permanent part of AST. If you use it to calibrate some data and then pass that data to someone else, who has only the standard version of AST, then they will not be able to interpret it. Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators (who we assume have access to the same transformation routines), it does not address the need for universal data exchange like other AST Mappings do. This is where the ``Intra'' in the class name ``IntraMap'' comes from, implying private or internal usage. For this reason, it is unwise to store IntraMaps in datasets, unless they will be used solely for communication between collaborating items of software which share conventions about their use. A private database describing coordinate systems on a graphics device might be an example where IntraMaps would be suitable, because the data would probably never be accessed by anyone else's software. Restricting IntraMap usage to within a single program (\emph{i.e.} never writing it out) is, of course, completely safe. If, by accident, an IntraMap should happen to escape as part of a dataset, then the unsuspecting recipient is likely to receive an error message when they attempt to read the data. However, AST will associate details of the IntraMap's transformation routine and its author (if provided) with the data, so that the recipient can make an intelligent enquiry to obtain the necessary software if this proves essential. \subsection{\label{ss:transformationfunctions}Writing a Transformation Routine} The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate transformation routine. This should have a calling interface like the \htmlref{AST\_TRANN}{AST\_TRANN} function provided by AST (\emph{q.v.}). Here is a simple example of a suitable transformation routine which transforms coordinates by squaring them: \xlabel{SqrTran} \small \begin{terminalv} SUBROUTINE SQRTRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD, : NCOORD_OUT, OUTDIM, OUT, STATUS ) INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT ) LOGICAL FORWARD INCLUDE 'AST_PAR' DOUBLE PRECISION X INTEGER COORD, POINT * Forward transformation. IF ( FORWARD ) THEN DO 2 POINT = 1, NPOINT DO 1 COORD = 1, NCOORD_IN X = IN( POINT, COORD ) IF ( X .EQ. AST__BAD ) THEN OUT( POINT, COORD ) = AST__BAD ELSE OUT( POINT, COORD ) = X * X ENDIF 1 CONTINUE 2 CONTINUE * Inverse transformation. ELSE DO 4 POINT = 1, NPOINT DO 3 COORD = 1, NCOORD_IN X = IN( POINT, COORD ) IF ( X .LT. 0.0D0 .OR. X .EQ. AST__BAD ) THEN OUT( POINT, COORD ) = AST__BAD ELSE OUT( POINT, COORD ) = SQRT( X ) ENDIF 3 CONTINUE 4 CONTINUE ENDIF END \end{terminalv} \normalsize As you can see, the routine comes in two halves which implement the forward and inverse coordinate transformations. The number of points to be transformed (NPOINT) and the numbers of input and output coordinates per point (NCOORD\_IN and NCOORD\_OUT---in this case both are assumed equal) are passed to the routine. A pair of loops then accesses all the coordinate values. Note that it is legitimate to omit one or other of the forward/inverse transformations and simply not to implement it, if it will not be required. It is also permissible to require that the numbers of input and output coordinates be fixed (\emph{e.g.}\ at 2), or to write the routine so that it can handle arbitrary dimensionality, as here. Before using an incoming coordinate, the routine must first check that it is not set to the value AST\_\_BAD, which indicates missing data (\secref{ss:badcoordinates}). If it is, the same value is also assigned to any affected output coordinates. The value AST\_\_BAD is also generated if any coordinates cannot be transformed. In this example, this can happen with the inverse transformation if negative values are encountered, so that the square root cannot be taken. There are very few restrictions on what a coordinate transformation routine may do. For example, it may freely perform I/O to access any external data needed, it may invoke other AST facilities (but beware of unwanted recursion), \emph{etc.} Typically, you may also want to pass information to it \emph{via}\ global variables held in common blocks. Remember, however, that whatever facilities the transformation routine requires must be available in every program which uses it. Generally, it is not a good idea to retain context information within a transformation routine. That is, it should transform each set of coordinates as a single point and retain no memory of the points it has transformed before. This is in order to conform with the AST model of a \htmlref{Mapping}{Mapping}. If an error occurs within a transformation routine, it should set its STATUS argument to an error value before returning. This will alert AST to the error, causing it to abort the current operation. The error value AST\_\_ITFER is available for this purpose, but other values may also be used (\emph{e.g.}\ if you wish to distinguish different types of error). The AST\_\_ITFER error value is defined in the AST\_ERR include file. \subsection{\label{ss:registeringintramaps}Registering a Transformation Routine} Having written your coordinate transformation routine, the next step is to register it with AST. Registration is performed using \htmlref{AST\_INTRAREG}{AST\_INTRAREG}, as follows: \small \begin{terminalv} EXTERNAL SQRTRAN CHARACTER * ( 80 ) AUTHOR, CONTACT, PURPOSE ... PURPOSE = 'Square each coordinate value' AUTHOR = 'R.F. Warren-Smith & D.S. Berry' CONTACT = 'http://www.starlink.ac.uk/cgi-bin/htxserver/' // 'sun210.htx/?xref_SqrTran' CALL AST_INTRAREG( 'SqrTran', 2, 2, SQRTRAN, 0, : PURPOSE, AUTHOR, CONTACT, STATUS ) \end{terminalv} \normalsize Note that the transformation routine must also appear in a Fortran EXTERNAL statement. The first argument to AST\_INTRAREG is a name by which the transformation routine will be known. This will be used when we come to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you base this on the actual routine name and make this sufficiently unusual that it is unlikely to clash with any other routines in most people's software. The next two arguments specify the number of input and output coordinates which the transformation routine will handle. These correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will create. Here, we have set them both to 2, which means that we will only be able to create IntraMaps with 2 input and 2 output coordinates (despite the fact that the transformation routine can actually handle other dimensionalities). We will see later (\secref{ss:variableintramapcoordinates}) how to remove this restriction. The fourth argument should contain a set of flags which describe the transformation routine in a little more detail. We will return to this shortly (\secref{ss:restrictedintramaps} \& \secref{ss:simplifyingintramaps}). For now, we supply a value of zero. The remaining arguments are character strings which document the transformation routine, mainly for the benefit of anyone who is unfortunate enough to encounter a reference to it in their data which they cannot interpret. As explained above (\secref{ss:intramaplimitations}), you should try and avoid this, but accidents will happen, so you should always provide strings containing the following: \begin{enumerate} \item A short description of what the transformation routine is for. \item The name of the author. \item Contact details, such as an e-mail or WWW address. \end{enumerate} The idea is that anyone finding an IntraMap in their data, but lacking the necessary transformation routine, should be able to contact the author and make a sensible enquiry in order to obtain it. If you expect many enquiries, you may like to set up a World Wide Web page and use that instead (in the example above, we use the WWW address of the relevant part of this document). \subsection{Creating an IntraMap} Once a transformation routine been registered, creating an \htmlref{IntraMap}{IntraMap} from it is simple: \small \begin{terminalv} INTEGER INTRAMAP ... INTRAMAP = AST_INTRAMAP( 'SqrTran', 2, 2, ' ', STATUS ); \end{terminalv} \normalsize We simply use the \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} constructor function and pass it the name of the transformation routine to use. This name is the same (case sensitive) one that we associated with the routine when we registered it using \htmlref{AST\_INTRAREG}{AST\_INTRAREG} (\secref{ss:registeringintramaps}). You can, of course, register any number of transformation routines and select which one to use whenever you create an IntraMap. You can also create any number of independent IntraMaps using each transformation routine. In this sense, each transformation routine you register effectively creates a new ``sub-class'' of IntraMap, from which you can create Objects just like any other class. However, an error will occur if you attempt to use a transformation routine that has not yet been registered. The second and third arguments to AST\_INTRAMAP are the numbers of input and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for the IntraMap that is created and they must match the corresponding numbers given when the transformation routine was registered. The penultimate argument is the usual attribute initialisation string. You may set attribute values for an IntraMap in exactly the same way as for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see \secref{ss:intraflag}). \subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Routines} You may not always want to use both the forward and inverse transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit either from the underlying coordinate transformation routine. Consider the following, for example: \small \begin{terminalv} SUBROUTINE POLY3TRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD, : NCOORD_OUT, OUTDIM, OUT, STATUS ) INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT ) LOGICAL FORWARD INCLUDE 'AST_PAR' DOUBLE PRECISION X INTEGER POINT * Forward transformation. DO 1 POINT = 1, NPOINT X = IN( POINT, 1 ) IF ( X .EQ. AST__BAD ) THEN OUT( POINT, 1 ) = AST__BAD ELSE OUT( POINT, 1 ) = : 6.18D0 + X * ( 0.12D0 + X * ( -0.003D0 + X * 0.0000101D0 ) ) END IF 1 CONTINUE END \end{terminalv} \normalsize This implements a 1-dimensional cubic polynomial transformation. Since this is somewhat awkward to invert, however, we have only implemented the forward transformation. When registering the routine, this is indicated via the FLAGS argument to \htmlref{AST\_INTRAREG}{AST\_INTRAREG}, as follows: \small \begin{terminalv} EXTERNAL POLY3TRAN ... CALL AST_INTRAREG( 'Poly3Tran', 1, 1, POLY3TRAN, AST__NOINV, : PURPOSE, AUTHOR, CONTACT, STATUS ) \end{terminalv} \normalsize Here, the fifth argument has been set to the flag value AST\_\_NOINV to indicate the lack of an inverse. If the forward transformation were absent, we would use AST\_\_NOFOR instead. Flag values for this argument may be combined by summing them if necessary. \subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates} In our earlier examples, we have used a fixed number of input and output coordinates when registering a coordinate transformation routine. It is not necessary to impose this restriction, however, if the transformation routine can cope with a variable number of coordinates (as with the example in \secref{ss:transformationfunctions}). We indicate the acceptability of a variable number when registering the transformation routine by supplying the value AST\_\_ANY for the number of input and/or output coordinates, as follows: \small \begin{terminalv} CALL AST_INTRAREG( 'SqrTran', AST__ANY, AST__ANY, SQRTRAN, 0, : PURPOSE, AUTHOR, CONTACT, STATUS ) \end{terminalv} \normalsize The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of input and output coordinates. For example: \small \begin{terminalv} INTEGER INTRAMAP1, INTRAMAP2 ... INTRAMAP1 = AST_INTRAMAP( 'SqrTran', 1, 1, ' ', STATUS ) INTRAMAP2 = AST_INTRAMAP( 'SqrTran', 3, 3, 'Invert=1', STATUS ) \end{terminalv} \normalsize It is possible to fix either the number of input or output coordinates (by supplying an explicit number to \htmlref{AST\_INTRAREG}{AST\_INTRAREG}), but more subtle restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} be equal, are not supported. This means that: \small \begin{terminalv} INTRAMAP = AST_INTRAMAP( 'SqrTran', 1, 2, ' ', STATUS ) \end{terminalv} \normalsize will be accepted without error, although the transformation routine cannot actually handle such a combination sensibly. If this is important, it would be worth adding a check within the transformation routine itself, so that the error would be detected when it came to be used. \subsection{\label{ss:intraflag}Adapting a Transformation Routine to Individual IntraMaps} In the examples given so far, our coordinate transformation routines have not made use of the THIS pointer passed to them (which identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In practice, this will often be the case. However, the presence of the THIS pointer allows the transformation routine to invoke any other AST routine on the IntraMap, and this permits enquiries about its attributes. The transformation routine's behaviour can therefore be modified according to any attribute values which are set. This turns out to be a useful thing to do, so each IntraMap has a special \htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose. Consider, for instance, the case where the transformation routine has access to several alternative sets of internally-stored data which it may apply to perform its transformation. Rather than implement many different versions of the transformation routine, you may switch between them by setting a value for the IntraFlag attribute when you create an instance of an IntraMap, for example: \small \begin{terminalv} INTRAMAP1 = AST_INTRAMAP( 'MyTran', 2, 2, 'IntraFlag=A', STATUS ) INTRAMAP2 = AST_INTRAMAP( 'MyTran', 2, 2, 'IntraFlag=B', STATUS ) \end{terminalv} \normalsize The transformation routine may then enquire the value of the IntraFlag attribute (\emph{e.g.}\ using AST\_GETC and passing it the THIS pointer) and use whichever dataset is required for that particular IntraMap. This approach is particularly useful when the number of possible transformations is unbounded or not known in advance, in which case the IntraFlag attribute may be used to hold numerical values encoded as part of a character string (effectively using them as data for the IntraMap). It is also superior to the use of a global switch for communication (\emph{e.g.}\ setting an index to select the ``current'' data before using the IntraMap), because it continues to work when several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping}, when you may have no control over the order in which they are used. \subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps} A notable disadvantage of IntraMaps is that they are ``black boxes'' as far as AST is concerned. This means that they have limited ability to participate in the simplification of compound Mappings performed, \emph{e.g.}, by \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} (\secref{ss:simplifyingcmpmaps}), because AST cannot know how they interact with other Mappings. In reality, of course, they will often implement such specialised coordinate transformations that the simplification possibilities will be rather limited anyway. One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This is important because Mappings are frequently used to relate a dataset to some external standard (a celestial coordinate system, for example). When inter-relating two similar datasets calibrated using the same standard, part of the Mapping often cancels, because it is applied first in one direction and then the other, effectively eliminating the reference to the standard. This is often a useful simplification and can lead to greater efficiency. Many transformations have this property of cancelling with their own inverse, but not necessarily all. Consider the following transformation routine, for example: \small \begin{terminalv} SUBROUTINE MAXTRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD, : NCOORD_OUT, OUTDIM, OUT, STATUS ) INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT ) LOGICAL FORWARD INCLUDE 'AST_PAR' DOUBLE PRECISION HI, X INTEGER COORD, POINT * Forward transformation. IF ( FORWARD ) THEN DO 2 POINT = 1, NPOINT HI = AST__BAD DO 1 COORD = 1, NCOORD_IN X = IN( POINT, COORD ) IF ( X .NE. AST__BAD ) THEN IF ( X .GT. HI .OR. HI .EQ. AST__BAD ) HI = X END IF 1 CONTINUE 2 CONTINUE * Inverse transformation. ELSE DO 4 COORD = 1, NCOORD_OUT DO 3 POINT = 1, NPOINT OUT( POINT, COORD ) = IN( POINT, 1 ) 3 CONTINUE 4 CONTINUE END IF END \end{terminalv} \normalsize This routine takes any number of input coordinates and returns a single output coordinate which is the maximum value of the input coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the input coordinates to the value of the output coordinate.\footnote{Remember that IN holds the original ``output'' coordinates when applying the inverse transformation and OUT holds the original ``input'' coordinates.} If this routine is applied in the forward direction and then in the inverse direction, it does \textbf{not} in general restore the original coordinate values. However, if applied in the inverse direction and then the forward direction, it does. Hence, replacing the sequence of operations with an equivalent UnitMap is possible in the latter case, but not in the former. To distinguish these possibilities, two flag values are provided for use with \htmlref{AST\_INTRAREG}{AST\_INTRAREG} to indicate what simplification (if any) is possible. For example, to register the above transformation routine, we might use: \small \begin{terminalv} EXTERNAL MAXTRAN ... CALL AST_INTRAREG( 'MaxTran', AST__ANY, 1, MAXTRAN, AST__SIMPIF, : PURPOSE, AUTHOR, CONTACT, STATUS ) \end{terminalv} \normalsize Here, the flag value AST\_\_SIMPIF supplied for the fifth argument indicates that simplification is possible if the transformation is applied in the inverse direction followed by the forward direction. To indicate the complementary case, the flag AST\_\_SIMPFI would be used instead. If both simplifications are possible (as with the SQRTRAN function in \secref{ss:transformationfunctions}), then we would use the sum of both values. In practice, some judgement is usually necessary when deciding whether to allow simplification. For example, seen in one light our SQRTRAN routine (\secref{ss:transformationfunctions}) does not cancel with its own inverse, because squaring a coordinate value and then taking its square root can change the original value, if this was negative. Therefore, replacing this combination with a UnitMap will change the behaviour of a compound Mapping and should not be allowed. Seen in another light, however, where the coordinates being processed are intrinsically all positive, it is a permissible and probably useful simplification. If such distinctions are ever important in practice, it is simple to register the same transformation routine twice with different flag values (use a separate name for each) and then use whichever is appropriate when creating an \htmlref{IntraMap}{IntraMap}. \subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps} It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation routine which it uses is not stored with it. To do so is impossible, because the routine has been compiled and loaded into memory ready for execution before AST gets to see it. However, AST does store the name associated with the transformation routine and various details about the IntraMap itself. This means that any program attempting to read the IntraMap (\secref{ss:readingfromachannel}) cannot make use of it unless it also has independent access to the original transformation routine. If it does not have access to this routine, an error will occur at the point where the IntraMap is read and the associated error message will direct the user to the author of the transformation routine for more information. However, if the necessary transformation routine is available, and has been registered before the read operation takes place, then AST is able to re-create the original IntraMap and will do so. Registration of the transformation routine must, of course, use the same name (and, in fact, be identical in most particulars) as was used in the original program which wrote the data. This means that a set of co-operating programs which all have access to the same set of transformation routines and register them in identical fashion (see \secref{ss:intramaplibrary} for how this can best be achieved) can freely exchange data that contain IntraMaps. The need to avoid exporting such data to unsuspecting third parties (\secref{ss:intramaplimitations}) must, however, be re-iterated. \subsection{\label{ss:intramaplibrary}Managing Transformation Routines in Libraries} If you are developing a large suite of data reduction software, you may have a need to use IntraMaps at various points within it. Very probably this will occur in unrelated modules which are compiled separately and then stored in a library. Since the transformation routines required must be registered before they can be used, this makes it difficult to decide where to perform this registration, especially since any particular data reduction program may use an arbitrary subset of the modules in your library. To assist with this problem, AST allows you to perform the same registration of a transformation routine any number of times, so long as it is performed using an identical invocation of \htmlref{AST\_INTRAREG}{AST\_INTRAREG} on each occasion (\emph{i.e.}\ all of its arguments must be identical). This means you do not have to keep track of whether a particular routine has already been registered but could, in fact, register it on each occasion immediately before it is required (wherever that may be). In order that all registrations are identical, however, it is recommended that you group them all together into a single routine, perhaps as follows: \small \begin{terminalv} SUBROUTINE MYTRANS( STATUS ) INTEGER STATUS INCLUDE 'AST_PAR' EXTERNAL MAXTRAN, POLY3TRAN, SQRTRAN ... CALL AST_INTRAREG( 'MaxTran', AST__ANY, 1, MAXTRAN, AST__SIMPIF, : PURPOSE, AUTHOR, CONTACT, STATUS ) ... CALL AST_INTRAREG( 'Poly3Tran', 1, 1, POLY3TRAN, AST__NOINV, : PURPOSE, AUTHOR, CONTACT, STATUS ) ... CALL AST_INTRAREG( 'SqrTran, 2, 2, SQRTRAN, 0, : PURPOSE, AUTHOR, CONTACT, STATUS ) END \end{terminalv} \normalsize You can then simply invoke this routine wherever necessary. It is, in fact, particularly important to register all relevant transformation routines in this way before you attempt to read an \htmlref{Object}{Object} that might be (or contain) an \htmlref{IntraMap}{IntraMap} (\secref{ss:readingandwritingintramaps}). This is because you may not know in advance which of these transformation routines the IntraMap will use, so they must all be available in order to avoid an error. \cleardoublepage \section{\label{ss:plots}Producing Graphical Output (Plots)} Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot}, which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the graphical content itself, but is a route through which plotting operations, such as drawing lines and curves, are conveyed on to a plotting surface to appear as visible graphics. \subsection{The Plot Model} When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or logarithmically (as specified by the LogPlot attribues) on to a \emph{plotting area}. This is a rectangular region in the graphical coordinate space of the underlying graphics system and becomes the new base Frame of the Plot. In effect, the Plot becomes attached to the plotting surface, in rather the same way that a basic FrameSet might be attached to (say) an image. The current Frame of the Plot (derived from the current Frame of the FrameSet supplied) is used to represent a \emph{physical coordinate system}. This is the system in which plotting operations are performed by your program. Every plotting operation is then transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current and base Frames in order to appear on the plotting surface. An example may help here. Suppose we start with a FrameSet whose base Frame describes the pixel coordinates of an image and whose current Frame describes a celestial (equatorial) coordinate system. Let us assume that these two Frames are inter-related by a Mapping within the FrameSet which represents a particular sky projection. When a Plot is created from this FrameSet, we specify how the pixel coordinates (the base Frame) maps on to the plotting surface. This simply corresponds to telling the Plot where we have previously plotted the image data. If we now use the Plot to plot a line with latitude zero in our physical coordinate system, as given by the current Frame, this line would appear as a curve (the equator) on the plotting surface, correctly registered with the image. There are a number of plotting functions provided, which all work in a similar way. Plotting operations are transformed through the Mapping which the Plot represents before they appear on the plotting surface.\footnote{Like any FrameSet, a Plot can be used as a Mapping. In this case it is the inverse transformation which is used when plotting (\emph{i.e.}\ that which transforms between the current and base Frames).} It is possible to draw symbols, lines, axes, entire grids and more in this way. %\subsection{TBW---Creating a Plot} \subsection{Plotting Symbols} The simplest form of plotting is to draw symbols (termed \emph{markers}) at a set of points. This is performed by \htmlref{AST\_MARK}{AST\_MARK}, which is supplied with a set of physical coordinates at which to place the markers: \small \begin{terminalv} INCLUDE 'AST_PAR' INTEGER NCOORD, NMARK, TYPE, STATUS DOUBLE PRECISION IN( NMARK, NCOORD ) STATUS = 0 ... CALL AST_MARK( PLOT, NMARK, NCOORD, NMARK, IN, TYPE, STATUS ) \end{terminalv} \normalsize Here, NMARK specifies how many markers to plot and NCOORD specifies how many coordinates are being supplied for each point.\footnote{Remember, the physical coordinate space need not necessarily be 2-dimensional, even if the plotting surface is.} The array IN supplies the coordinates and the integer TYPE specifies which type of marker to plot. \subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves} There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight line in physical coordinates can potentially turn into a curve in graphical coordinates. We therefore start by considering how to draw geodesic curves. These are curves which trace the path of shortest distance between two points in physical coordinates and are the basic drawing element in a Plot. In many instances, the geodesic will, in fact, be a straight line, but this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a celestial coordinate system, for instance, it will be a great circle (corresponding with the behaviour of the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function which defines the metric of the physical coordinate space). The geodesic will, of course, be transformed into graphics coordinates before being plotted. A geodesic curve is plotted using \htmlref{AST\_CURVE}{AST\_CURVE} as follows: \small \begin{terminalv} DOUBLE PRECISION START( NCOORD ), FINISH( NCOORD ) ... CALL AST_CURVE( PLOT, START, FINISH, STATUS ) \end{terminalv} \normalsize Here, START and FINISH are arrays containing the starting and finishing coordinates of the curve. The \htmlref{AST\_OFFSET}{AST\_OFFSET} and AST\_DISTANCE routines can often be useful for computing these (\secref{ss:distanceandoffset}). If you need to draw a series of curves end-to-end (when drawing a contour line, for example), then a more efficient alternative is to use \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}. This has the same effect as a sequence of calls to AST\_CURVE, but allows you to supply a whole set of points at the same time. AST\_POLYLINE then joins them, in sequence, using geodesic curves: \small \begin{terminalv} INTEGER NPOINT DOUBLE PRECISION COORDS( NPOINT, NCOORD ) ... CALL AST_POLYCURVE( PLOT, NPOINT, NCOORD, NPOINT, COORDS, STATUS ) \end{terminalv} \normalsize Here, NPOINT specifies how many points are to be joined and NCOORD specifies how many coordinates are being supplied for each point. The array COORDS supplies the coordinates of the points in the Plot's physical coordinate system. \subsection{Plotting Curves Parallel to Axes} As there is no \htmlref{Plot}{Plot} routine to draw a ``straight line'', drawing axes and grid lines to represent coordinate systems requires a slightly different approach. The problem is that for some coordinate systems, these grid lines will not be geodesics, so \htmlref{AST\_CURVE}{AST\_CURVE} and \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} (\secref{ss:plottinggeodesics}) cannot easily be used (you would have to resort to approximating grid lines by many small elements). Lines of constant celestial latitude provide an example of this, with the exception of the equator which is a geodesic. The \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE} routine allows these curves to be drawn, as follows: \small \begin{terminalv} INTEGER AXIS DOUBLE PRECISION LENGTH ... CALL AST_GRIDLINE( PLOT, AXIS, START, LENGTH, STATUS ) \end{terminalv} \normalsize Here, AXIS specifies which physical coordinate axis we wish to draw parallel to. The START array contains the coordinates of the start of the curve and LENGTH specifies the distance to draw along the axis in physical coordinate space. \subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves} We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot} class includes another method, \htmlref{AST\_GENCURVE}{AST\_GENCURVE}, which allows curves of \emph{any} form to be drawn. The caller supplies a \htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the start of the curve is at offset 0.0 and the end of the curve is at offset 1.0 - offset need not be linearly related to distance.} into the corresponding position in the current \htmlref{Frame}{Frame} of the Plot. AST\_GENCURVE, then takes care of Mapping these positions into graphics coordinates. The choice of exactly which positions along the curve are to be used to define the curve is also made by AST\_GENCURVE, using an adaptive algorithm which concentrates points around areas where the curve is bending sharply or is discontinuous in graphics coordinates. The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows you to code your own Mappings to do any transformation you choose. \subsection{\label{ss:clipping}Clipping} Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics you produce. This means that plotting is restricted to certain regions of the plotting surface so that anything drawn outside these regions will not appear. All Plots automatically clip at the edges of the plotting area specified when the Plot is created. This means that graphics are ultimately restricted to the rectangular region of plotting space to which you have attached the Plot. In addition to this, you may also specify lower and upper limits on each axis at which clipping should occur. This permits you to further restrict the plotting region. Moreover, you may attach these clipping limits to \emph{any} of the Frames in the Plot. This allows you to place restrictions on where plotting will take place in either the physical coordinate system, the graphical coordinate system, or in any other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot. For example, you could plot using equatorial coordinates and set up clipping limits in galactic coordinates. In general, you could set up arbitrary clipping regions by adding a new Frame to a Plot (in which clipping will be performed) and inter-relating this to the other Frames in a suitable way. Clipping limits are defined using the \htmlref{AST\_CLIP}{AST\_CLIP} routine, as follows: \small \begin{terminalv} INTEGER IFRAME, NAXES DOUBLE PRECISION LBND( NAXES ), UBND( NAXES ) ... CALL AST_CLIP( PLOT, IFRAME, LBND, UBND, STATUS ) \end{terminalv} \normalsize Here, the IFRAME value gives the index of the Frame within the Plot to which clipping is to be applied, while LBND and UBND give the limits on each axis of the selected Frame (NAXES is the number of axes in this Frame). You can remove clipping by giving a value of AST\_\_NOFRAME for IFRAME. \subsection{Using a Plot as a Mapping} All Plots are also Mappings (just like the FrameSets from which they are derived), so can be used to transform coordinates. Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert coordinates between the base and current Frames (\emph{i.e.}\ between graphical and physical coordinates). This would be useful if you were (say) reading a cursor position in graphical coordinates and needed to convert this into physical coordinates for display. Conversely, a Plot's inverse transformation converts between its current and base Frames (\emph{i.e.}\ from physical coordinates to graphical coordinates). This transformation is applied automatically whenever plotting operations are carried out by AST routines. It may also be useful to apply it directly, however, if you wish to perform additional plotting operations (\emph{e.g.}\ those provided by the native graphics system) at positions specified in physical coordinates. There is, however. one important difference between using a \htmlref{FrameSet}{FrameSet} and a Plot to transform coordinates, and this is that clipping may be applied by a Plot (if it has been enabled using \htmlref{AST\_CLIP}{AST\_CLIP}---\secref{ss:clipping}). Any point which lies within the clipped region of a Plot will, when transformed, yield coordinates with the value AST\_\_BAD. If you wish to avoid this clipping, you should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using \htmlref{AST\_GETMAPPING}{AST\_GETMAPPING}) and use this, instead of the Plot, to transform the coordinates. \subsection{Using a Plot as a Frame} Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units, \emph{etc.}, which are typically used when displaying data and/or coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from the current Frame of the Plot (\secref{ss:framesetasframe}). They are also used automatically when using the Plot to plot coordinate axes and coordinate grids (\emph{e.g.}\ for labelling them---\secref{ss:plottingagrid}). Because the current Frame of a Plot represents physical coordinates, any Frame operation applied to the Plot will effectively be working in this coordinate system. For example, the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} and \htmlref{AST\_OFFSET}{AST\_OFFSET} routines will compute distances and offsets in physical coordinate space, and \htmlref{AST\_FORMAT}{AST\_FORMAT} will format physical coordinates in an appropriate way for display. \subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates} When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot} into graphics coordinates for plotting, they may not always yield valid coordinates, irrespective of any clipping being applied (\secref{ss:clipping}). To indicate this, the resulting coordinate values will be set to the value AST\_\_BAD (\secref{ss:badcoordinates}). There are a number of reasons why this may occur, but typically it will be because physical coordinates only map on to a subset of the graphics coordinate space. This situation is commonly encountered with all-sky projections where, typically, the celestial sphere appears, when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which does not entirely fill the graphics space. In some cases, there may even be multiple regions of valid and invalid physical coordinates. When plotting is performed \emph{via} a Plot, graphical output will only appear in the regions of valid physical coordinates. Nothing will appear where invalid coordinates occur. Such output is effectively clipped. If you wish to plot in these areas, you must change coordinate system and use, say, graphical coordinates to address the plotting surface directly. \subsection{Plotting Borders} The \htmlref{AST\_BORDER}{AST\_BORDER} routine is provided to draw a (line) border around your graphical output. With most graphics systems, this would simply be a rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this boundary follows the edge of each region containing valid, unclipped physical coordinates (\secref{ss:validphysicalcoordinates}). This means, for example, that if you were plotting an all-sky projection, this boundary would outline the perimeter of the celestial sphere when projected on to your plotting surface. Of course, if there is no clipping and all physical coordinates are valid, then you will get the traditional rectangular box. AST\_BORDER requires only a pointer to the Plot and the usual STATUS argument: \small \begin{terminalv} LOGICAL HOLES ... HOLES = AST_BORDER( PLOT, STATUS ) \end{terminalv} \normalsize It returns a logical value to indicate if any invalid or clipped physical coordinates were found within the plotting area. If they were, it will draw around the valid unclipped regions and return .TRUE.. Otherwise, it will draw a simple rectangular border and return .FALSE.. \subsection{Plotting Text} Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be displayed and a position in physical coordinates where the text is to appear. The position is transformed into graphical coordinates to determine where the text should appear on the plotting surface. You must also provide a 2-element UP vector which gives the upward direction of the text in graphical coordinates. This allows text to be drawn at any angle. Plotting is performed by \htmlref{AST\_TEXT}{AST\_TEXT}, for example: \small \begin{terminalv} CHARACTER * ( 20 ) TEXT DOUBLE PRECISION POS( NCOORD ) REAL UP( 2 ) DATA UP / 0.0, 1.0 / ... CALL AST_TEXT( PLOT, TEXT, POS, UP, 'TL', STATUS ) \end{terminalv} \normalsize Here, TEXT contains the string to be drawn, POS is an array of physical coordinates and UP specifies the upward vector. In this case, the text will be drawn horizontally. The penultimate argument specifies the text justification, here indicating that the top left corner of the text should appear at the position given. Further control over the appearance of the text is possible by setting values for various Plot attributes, for example Colour, Font and Size. Sub-strings within the displayed text can be given different appearances, or turned into super-scripts or sub-scripts, by the inclusion of escape sequences (see section~\secref{ss:escapes}) within the supplied text string. \subsection{\label{ss:plottingagrid}Plotting a Grid} The most comprehensive plotting routine available is \htmlref{AST\_GRID}{AST\_GRID}, which can be used to draw labelled coordinate axes and, optionally, to overlay coordinate grids on the plotting area (Figure~\ref{fig:gridplot}). The routine is straightforward to use, simply requiring a pointer to the \htmlref{Plot}{Plot} and a STATUS argument: \small \begin{terminalv} CALL AST_GRID( PLOT, STATUS ) \end{terminalv} \normalsize It will draw both linear and curvilinear axes and grids, as required by the particular Plot. The appearance of the output can be modified in a wide variety of ways by setting various Plot attributes. The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings within these strings can be given different appearances, or turned into super-scripts or sub-scripts, by the inclusion of escape sequences (see section~\secref{ss:escapes}) within the Label attributes. \subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings} Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be plotted so that all characters in the string have the same font size, colour, \emph{etc.}, specified by the appropriate attributes of the Plot. However, it is possible to include \emph{escape sequences} within the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be used to change, colour, font, size, width, to introduce extra horizontal space between characters, and to change the base line of characters (thus allowing super-scripts and sub-scripts to be created). See the entry for the Escape attribute in \appref{ss:attributedescriptions} for details. As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a super-scripted exponent. The exponent text will be 70\% of the size of normal text (as determined by the Size attribute), and its baseline will be raised by 50\% of the height of a normal character. Such escape sequences can be used in the strings assigned to textual attributes of the Plot (such as the axis Labels), and may also be included in strings plotted using \htmlref{AST\_TEXT}{AST\_TEXT}. The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option which will cause escape sequences to be included when formatting celestial positions so that super-script characters are used as delimiters for the various fields (a super-script ``h'' for hours, ``m'' for minutes, \emph{etc}). Note, the facility for interpreting escape sequences is only available if the graphics wrapper functions which provide the interface to the underlying graphics system support all the functions included in the \verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be extended by the addition of new functions before escape sequences can be interpretted. \subsection{\label{ss:logaxes}Producing Logarithmic Axes} In certain situations you may wish for one or both of the plotted axes to be displayed logarithmically rather than linearly. For instance, you may wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux against frequency. In this case, you can cause the frequency axis to be drawn logarithmically simply by setting the boolean LogPlot attribute for the frequency axis to a non-zero value. This causes several things to happen: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents the underlying graphics world coordinate system) and the base Frame of the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By default, this mapping is linear on both axes, but setting LogPlot non-zero for an axis causes the Mapping to be modified so that it is logarithmic on the specified axis. This is only possible if the displayed section of the axis does not include the value zero (otherwise the attempt to set a new value for LogPlot is ignored,and it retains its default value of zero). \item The major tick marks drawn as part of the annotated coordinate grid are spaced logarithmically rather than linearly. That is, major axis values are chosen so that there is a constant ratio between adjacent tick mark values. This ratio is constrained to be a power of ten. The minor tick marks are drawn at linearly distributed points between the adjoining major tick values. Thus if a pair of adjacent major tick values are drawn at axis values 10.0 and 100.0, minor ticks will be placed at 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick marks are drawn). \item If possible, numerical axis labels are shown as powers of ten. This depends on the facilities implemented by the graphics wrapper functions (see the next section). Extra functions were introduced to this set of wrapper functions at AST V3.2 which enable super-scripts and sub-scripts to be produced. Some older wrappers may not yet have implemented these functiosn and this will result in axis labels being drawn in usual scientific or decimal notation. \end{enumerate} Whilst the LogPlot attribute can be used to control all three of the above facilities, it is possible to control them individually as well. The LogTicks and LogLabel attributes control the behaviour specified in items 2 and 3 above, but the default values for these attributes depend on the setting of the LogPlot attribute. This means that setting LogPlot non-zero will swicth all three facilites on, so long as zero values have not been assigned explicitly to LogTicks or LogLabel. \subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package} The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a graphics device. Instead, it requires a set of functions to be provided which it uses to draw the required graphics. These include functions to draw a straight line, draw a text string, \emph{etc}. You may choose to provide functions from your favorite graphics package, or you can even write your own! To accomodate variations in the calling interfaces of different graphics packages, AST defines a standard interface for these routines. If this interface differs from the interface provided by your graphics package (which in general it will), then you must write a set of \emph{wrapper functions}, which provide the interface expected by AST but which then call functions from your graphics package to provide the required functionality. AST comes with wrapper functions suitable for the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}). There are two ways of indicating which wrapper functions are to be used by the Plot class: \begin{enumerate} \item A file containing C functions with pre-defined names can be written and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command. (see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT functions to implement the required functionality. This file can be used as a template for writing your own. Currently, it is not possible to write such ``grf modules'' in Fortran. If you want to use wrapper functions written in Fortran, then you must use the \htmlref{AST\_GRFSET}{AST\_GRFSET} method as described below. \item The AST\_GRFSET method of the Plot class can be used to ``register'' wrapper functions at run-time. This allows an application to switch between graphics systems if required. Graphics functions registered in this way do not need to have the pre-defined names used in the link-time method described above. \end{enumerate} For details of the interfaces of the wrapper routines, see the reference documentation for the AST\_GRFSET method. \cleardoublepage \section{Compiling and Linking Software that Uses AST} A small number of UNIX commands are provided by AST to assist with the process of building software. A description of these can be found in \appref{ss:commanddescriptions} and their use is discussed here. Note that in order to access these commands, the appropriate directory (normally ``/star/bin'') should be on your PATH.\footnote{If you have not installed AST in the usual location, then substitute the appropriate directory in place of ``/star'' wherever it occurs.} \subsection{\label{ss:accessingheaderfile}Accessing AST Include Files} The include files provided for use with Fortran are: \begin{quote} \begin{description} \item[AST\_PAR]\mbox{}\\ Declares the types of all AST functions and defines parameter constants, except those that identify error values. \item[AST\_ERR]\mbox{}\\ Defines parameter constants to represent the various error values to which the AST error status may be set when an error occurs (\secref{ss:errordetection}). \end{description} \end{quote} References to AST include files should be in upper case. Most modern Fortran compilers allow the directory to be specified as a command line option: \small \begin{terminalv} f77 prog.f -I/star/include -o prog \end{terminalv} \normalsize If you are using such a compiler then your Fortran source code should, for instance, include: \small \begin{terminalv} INCLUDE 'AST_PAR' \end{terminalv} \normalsize (that is, there is no need to include the directory within the INCLUDE statement). If your compiler does not provide such an option then your source code must contain an absolute file name identifying the directory where the include files reside, for instance: \small \begin{terminalv} INCLUDE '/star/include/AST_PAR' \end{terminalv} \normalsize \subsection{\label{ss:linking}Linking with AST Facilities} Fortran programs may be linked with AST by including execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command line. Thus, to compile and link a program called ``prog'', the following might be used: \small \begin{terminalv} f77 prog.f -L/star/lib `ast_link` -o prog \end{terminalv} \normalsize On Linux systems you should usually use \verb+g77 -fno-second-underscore+ in place of \verb+f77+ - see \xref{``Software development on Linux''}{sun212} {software_development_on_linux} in \xref{SUN/212}{sun212}{}. Note the use of backward quote characters, which cause the ``ast\_link'' command to be executed and its result substituted into the compiler command. An alternative is to save the output from ``ast\_link'' in (say) a shell variable and use this instead. You may find this a little faster if you are building software repeatedly during development. Programs which use AST can also be linked in a number of other ways, depending on the facilities they require. In the example above, we have used the default method which assumes that the program will not be generating graphical output, so that no graphics libraries need be linked. If you need other facilities, then various switches can be applied to the ``ast\_link'' command in order to control the linking process. For example, if you were producing graphical output using the PGPLOT graphics package, you could link with the AST/PGPLOT interface by using the ``$-$pgplot'' switch with ``ast\_link'', as follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use the Starlink version of PGPLOT which uses GKS to generate its output.} \begin{small} \begin{terminalv} f77 prog.f -L/star/lib `ast_link -pgplot` -o prog \end{terminalv} \end{small} again using \verb+g77 -fno-second-underscore+ in place of \verb+f77+ on Linux systems. See the ``ast\_link'' command description in \appref{ss:commanddescriptions} for details of the options available. \subsection{Building ADAM Applications that Use AST} Users of Starlink's \xref{ADAM}{sg4}{} programming environment \latex{(SG/4)} on UNIX should use the ``\xref{alink}{sun144}{ADAM_link_scripts}'' command (\xref{SUN/144}{sun144}{}) to compile and link applications and can access the AST library by including execution of the command ``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows: \begin{small} \begin{terminalv} alink adamprog.f `ast_link_adam` \end{terminalv} \end{small} Note the use of backward quote characters. By default, AST error messages produced by applications built in this way will be delivered \emph{via} the Starlink EMS Error Message Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is consistent with the \xref{\emph{inherited status}}{sun104}{inherited_status} error handling normally used in Starlink software. Switches may be given to the ``ast\_link\_adam'' command (in a similar way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with additional AST-related facilities, such as a graphics interface. See the ``ast\_link\_adam'' command description in \appref{ss:commanddescriptions} for details of the options available. \appendix \cleardoublepage \section{\label{ss:classhierarchy}The AST Class Hierarchy} The following table shows the hierarchy of classes in the AST library. For a description of each class, you should consult \appref{ss:classdescriptions}. \small \begin{terminalv} Object - Base class for all AST Objects Axis - Store axis information SkyAxis - Store celestial axis information Channel - Basic (textual) I/O channel FitsChan - I/O Channel using FITS header cards XmlChan - I/O Channel using XML StcsChan - I/O Channel using IVOA STC-S descriptions KeyMap - Store a set of key/value pairs Table - Store a 2-dimensional table of values Mapping - Inter-relate two coordinate systems CmpMap - Compound Mapping DssMap - Map points using Digitised Sky Survey plate solution Frame - Coordinate system description CmpFrame - Compound Frame SpecFluxFrame - Observed value versus spectral position FluxFrame - Observed value at a given fixed spectral position FrameSet - Set of inter-related coordinate systems Plot - Provide facilities for 2D graphical output Plot3D - Provide facilities for 3D graphical output Region - Specify areas within a coordinate system Box - A box region with sides parallel to the axes of a Frame Circle - A circular or spherical region within a Frame CmpRegion - A combination of two regions within a single Frame Ellipse - An elliptical region within a 2-dimensional Frame Interval - Intervals on one or more axes of a Frame. NullRegion - A boundless region within a Frame PointList - A collection of points in a Frame Polygon - A polygonal region within a 2-dimensional Frame Prism - An extrusion of a Region into orthogonal dimensions Stc - Represents an generic instance of an IVOA STC-X description StcResourceProfile - Represents an an IVOA STC-X ResourceProfile StcSearchLocation - Represents an an IVOA STC-X SearchLocation StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation SkyFrame - Celestial coordinate system description SpecFrame - Spectral coordinate system description DSBSpecFrame - Dual sideband spectral coordinate system description TimeFrame - Time coordinate system description GrismMap - Models the spectral dispersion produced by a grism IntraMap - Map points using a private transformation function LutMap - Transform 1-dimensional coordinates using a lookup table MathMap - Transform coordinates using mathematical expressions MatrixMap - Map positions by multiplying them by a matrix NormMap - Normalise coordinates using a supplied Frame PcdMap - Apply 2-dimensional pincushion/barrel distortion PermMap - Coordinate permutation Mapping PolyMap - General N-dimensional polynomial Mapping RateMap - Calculates an element of a Mapping's Jacobian matrix SelectorMap - Locates positions within a set of Regions ShiftMap - Shifts each axis by a constant amount SlaMap - Sequence of celestial coordinate conversions SpecMap - Sequence of spectral coordinate conversions SphMap - Map 3-d Cartesian to 2-d spherical coordinates SwitchMap - Encapuslates a set of alternate Mappings TimeMap - Sequence of time coordinate conversions TranMap - Combine fwd. and inv. transformations from two Mappings UnitMap - Unit (null) Mapping UnitNormMap - Converts a vector to a unit vector plus length WcsMap - Implement a FITS-WCS sky projection WinMap - Match windows by scaling and shifting each axis ZoomMap - Zoom coordinates about the origin \end{terminalv} \normalsize \cleardoublepage \section{\label{ss:functiondescriptions}AST Routine Descriptions} \small \sstroutine{ AST\_SET }{ Set attribute values for an Object }{ \sstdescription{ This routine assigns a set of attribute values to an \htmlref{Object}{Object}, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute\texttt{'} s data type. } \sstinvocation{ CALL AST\_SET( THIS, SETTINGS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ SETTINGS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a comma-separated list of attribute settings in the form described above. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstexamples{ \sstexamplesubsection{ CALL AST\_SET( MAP, \texttt{'} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{'} , STATUS ) }{ Sets the Report attribute for Object MAP to the value 1 and the Zoom attribute to 25.0. } \sstexamplesubsection{ CALL AST\_SET( FRAME, \texttt{'} Label( 1 ) =Offset from cluster axis\texttt{'} , STATUS ) }{ Sets the Label(1) attribute for Object FRAME to a suitable string. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned). \sstitem To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ AST\_ADDCOLUMN }{ Add a new column definition to a table }{ \sstdescription{ Adds the definition of a new column to the supplied table. Initially, the column is empty. Values may be added subsequently using the methods of the \htmlref{KeyMap}{KeyMap} class. } \sstinvocation{ CALL AST\_ADDCOLUMN( THIS, NAME, TYPE, NDIM, DIMS, UNIT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The column name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. } \sstsubsection{ TYPE = INTEGER (Given) }{ The data type associated with the column. See \texttt{"} Applicability:\texttt{"} below. } \sstsubsection{ NDIM = INTEGER (Given) }{ The number of dimensions spanned by the values stored in a single cell of the column. Zero if the column holds scalar values. } \sstsubsection{ DIMS( NDIM ) = INTEGER (Given) }{ An array holding the the lengths of each of the axes spanned by the values stored in a single cell of the column. Ignored if the column holds scalara values. } \sstsubsection{ UNIT = CHARACTER $*$ ( $*$ ) (Given) }{ A string specifying the units of the column. Supply a blank string if the column is unitless. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Table }{ Tables can hold columns with any of the following data types - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for INTEGER$*$2), AST\_\_BYTETYPE (for bytes), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}). } \sstsubsection{ \htmlref{FitsTable}{FitsTable} }{ FitsTables can hold columns with any of the following data types - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for INTEGER$*$2), AST\_\_BYTETYPE (for bytes), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string). } } \sstnotes{ \sstitemlist{ \sstitem This routine returns without action if a column already exists in the Table with the supplied name and properties. However an error is reported if any of the properties differ. } } } \sstroutine{ AST\_ADDFRAME }{ Add a Frame to a FrameSet to define a new coordinate system }{ \sstdescription{ This routine adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a \htmlref{FrameSet}{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\texttt{'} s current Frame. This routine may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet. } \sstinvocation{ CALL AST\_ADDFRAME( THIS, IFRAME, MAP, FRAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 \htmlref{Nframe}{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). } \sstsubsection{ MAP = INTEGER (Given) }{ Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index IFRAME) into coordinates in the new system. The Mapping\texttt{'} s forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction. The supplied Mapping is ignored if parameter IFRAME is equal to AST\_\_ALLFRAMES. } \sstsubsection{ FRAME = INTEGER (Given) }{ Pointer to a Frame that describes the new coordinate system. Any class of Frame may be supplied (including Regions and FrameSets). This routine may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this argument (see the Notes section for details). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Deep copies of the supplied 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. \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the IFRAME argument to specify the base Frame or the current Frame respectively. \sstitem This routine sets the value of the \htmlref{Current}{Current} attribute for the FrameSet so that the new Frame subsequently becomes the current Frame. \sstitem The number of input coordinate values accepted by the supplied Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the Frame identified by the IFRAME argument. Similarly, the number of output coordinate values generated by this Mapping (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new Frame. \sstitem As a special case, if a pointer to a FrameSet is given for the 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 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 the IFRAME argument (in the original FrameSet) and the current Frame of the FRAME FrameSet. This latter Frame becomes the current Frame in the merged FrameSet. \sstitem As another special case, if a value of AST\_\_ALLFRAMES is supplied for parameter 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 \htmlref{CmpFrame}{CmpFrame} containing the original Frame and the Frame specified by parameter FRAME. In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap} containing the original Mapping and a \htmlref{UnitMap}{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 \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} before being stored in the FrameSet. } } } \sstroutine{ AST\_ADDPARAMETER }{ Add a new global parameter definition to a table }{ \sstdescription{ Adds the definition of a new global parameter to the supplied table. Note, this does not store a value for the parameter. To get or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class should be used, using the name of the parameter as the key. } \sstinvocation{ CALL AST\_ADDPARAMETER( THIS, NAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The parameter name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Unlike columns, the definition of a parameter does not specify its type, size or dimensionality. } } } \sstroutine{ AST\_ADDVARIANT }{ Store a new variant Mapping for the current Frame in a FrameSet }{ \sstdescription{ This routine allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"} attribute for more details. It can also be used to rename the currently selected variant Mapping. } \sstinvocation{ CALL AST\_ADDVARIANT( THIS, MAP, NAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 AST\_\_NULL is supplied, then the name associated with the currently selected variant of the current Frame is set to the value supplied for NAME, but no new variant is added. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The name to associate with the new variant Mapping (or the currently selected variant Mapping if MAP is AST\_\_NULL). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The newly added Variant becomes the current variant on exit (this is equivalent to setting the Variant attribute to the value supplied for NAME). \sstitem An error is reported if a variant with the supplied name already exists in the current Frame. \sstitem 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 \htmlref{AST\_MIRRORVARIANTS}{AST\_MIRRORVARIANTS} routine has been called to make the current Frame act as a mirror. } } } \sstroutine{ AST\_ANGLE }{ Calculate the angle subtended by two points at a third point }{ \sstdescription{ This routine finds the angle at point B between the line joining points A and B, and the line joining points C and B. These lines will in fact be geodesic curves appropriate to the \htmlref{Frame}{Frame} in use. For instance, in \htmlref{SkyFrame}{SkyFrame}, they will be great circles. } \sstinvocation{ RESULT = AST\_ANGLE( THIS, A, B, C, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ A( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ B( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. } \sstsubsection{ C( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute) containing the coordinates of the third point. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_ANGLE = DOUBLE PRECISION }{ The angle in radians, from the line AB to the line CB. If the Frame is 2-dimensional, it will be in the range \$$\backslash$pm $\backslash$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 \$$\backslash$pi\$. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem A value of AST\_\_BAD will also be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_ANNUL }{ Annul a pointer to an Object }{ \sstdescription{ This routine annuls a pointer to an \htmlref{Object}{Object} so that it is no longer recognised as a valid pointer by the AST library. Any resources associated with the pointer are released and made available for re-use. This routine also decrements the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute by one. If this attribute reaches zero (which happens when the last pointer to the Object is annulled), then the Object is deleted. } \sstinvocation{ CALL AST\_ANNUL( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given and Returned) }{ The Object pointer to be annulled. A null pointer value (AST\_\_NULL) is always returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value on entry, although no further error report will be made if it subsequently fails under these circumstances. In particular, it will fail if the pointer suppled is not valid, but this will only be reported if the error status is clear on entry. } } } \sstroutine{ AST\_AXANGLE }{ Returns the angle from an axis, to a line through two points }{ \sstdescription{ This routine finds the angle, as seen from point A, between the positive direction of a specified axis, and the geodesic curve joining point A to point B. } \sstinvocation{ RESULT = AST\_AXANGLE( THIS, A, B, AXIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Frame}{Frame}. } \sstsubsection{ A( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ B( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. } \sstsubsection{ AXIS = INTEGER (Given) }{ The number of the Frame axis from which the angle is to be measured (axis numbering starts at 1 for the first axis). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_AXANGLE = DOUBLE PRECISION }{ The angle in radians, from the positive direction of the specified axis, to the line AB. If the Frame is 2-dimensional, it will be in the range [-PI/2,$+$PI/2], and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range zero to PI. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this routine is the path of shortest distance between two points, as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the require position angle is undefined. } } } \sstroutine{ AST\_AXDISTANCE }{ Find the distance between two axis values }{ \sstdescription{ This routine returns a signed value representing the axis increment from axis value v1 to axis value v2. For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the difference between the two axis values. But for other derived classes of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. } \sstinvocation{ RESULT = AST\_AXDISTANCE( THIS, AXIS, V1, V2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ AXIS = INTEGER (Given) }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ V1 = DOUBLE PRECISION (Given) }{ The first axis value. } \sstsubsection{ V2 = DOUBLE PRECISION (Given) }{ The second axis value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_AXDISTANCE = DOUBLE PRECISION }{ The distance from the first to the second axis value. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input values has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_AXNORM }{ Normalise an array of axis values }{ \sstdescription{ This routine modifies a supplied array of axis values so that they are normalised in the manner indicated by argument OPER. No normalisation is possible for a simple \htmlref{Frame}{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 \htmlref{SkyFrame}{SkyFrame} has a discontinuity at zero longitude and so a longitude value can be expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the \texttt{"} Applicability:\texttt{"} section below for details. } \sstinvocation{ CALL AST\_AXNORM( THIS, AXIS, OPER, NVAL, VALUES, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ AXIS = INTEGER (Given) }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ OPER = INTEGER (Given) }{ Indicates the type of normalisation to be applied. If zero is supplied, the normalisation will be the same as that performed by routine \htmlref{AST\_NORM}{AST\_NORM}. If 1 is supplied, the normalisation will be chosen automatically so that the resulting list has the smallest range. } \sstsubsection{ NVAL = INTEGER (Given) }{ The number of points in the values array. } \sstsubsection{ VALUES( NVAL ) = DOUBLE PRECISION (Given and Returned) }{ On entry, the axis values to be normalised. Modified on exit to hold the normalised values. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ SkyFrame }{ If OPER is 0, longitude values are returned in the range [0,2$*$PI]. If OPER is 1, longitude values are returned in either the range [0,2$*$PI] or [-PI,PI]. The choice is made so that that the resulting list has the smallest range. Latitude values are always returned in the range [-PI,PI]. } \sstsubsection{ All other classes of Frame }{ The supplied axis values are returned unchanged. } } } \sstroutine{ AST\_AXOFFSET }{ Add an increment onto a supplied axis value }{ \sstdescription{ This routine returns an axis value formed by adding a signed axis increment onto a supplied axis value. For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the sum of the two supplied values. But for other derived classes of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. } \sstinvocation{ RESULT = AST\_AXOFFSET( THIS, AXIS, V1, DIST, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ AXIS = INTEGER (Given) }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ V1 = DOUBLE PRECISION (Given) }{ The original axis value. } \sstsubsection{ DIST = DOUBLE PRECISION (Given) }{ The axis increment to add to the original axis value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_AXOFFSET = DOUBLE PRECISION }{ The incremented axis value. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input values has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_BBUF }{ Begin a new graphical buffering context }{ \sstdescription{ This routine starts a new graphics buffering context. A matching call to the routine \htmlref{AST\_EBUF}{AST\_EBUF} should be used to end the context. } \sstinvocation{ CALL AST\_BBUF( THIS STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this routine to this routine simply invokes the astGBBuf function in the grf module. } } } \sstroutine{ AST\_BEGIN }{ Begin a new AST context }{ \sstdescription{ This routine begins a new AST context. Any \htmlref{Object}{Object} pointers created within this context will be annulled when it is later ended using \htmlref{AST\_END}{AST\_END} (just as if \htmlref{AST\_ANNUL}{AST\_ANNUL} had been invoked), unless they have first been exported using \htmlref{AST\_EXPORT}{AST\_EXPORT} or rendered exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}. If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. } \sstinvocation{ CALL AST\_BEGIN( STATUS ) } \sstarguments{ \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value. \sstitem Contexts delimited by AST\_BEGIN and AST\_END may be nested to any depth. } } } \sstroutine{ AST\_BORDER }{ Draw a border around valid regions of a Plot }{ \sstdescription{ This function draws a (line) border around regions of the plotting area of a \htmlref{Plot}{Plot} which correspond to valid, unclipped physical coordinates. For example, when plotting using an all-sky map projection, this function could be used to draw the boundary of the celestial sphere when it is projected on to the plotting surface. If the entire plotting area contains valid, unclipped physical coordinates, then the boundary will just be a rectangular box around the edges of the plotting area. If the Plot is a \htmlref{Plot3D}{Plot3D}, this method is applied individually to each of the three 2D Plots encapsulated within the Plot3D (each of these Plots corresponds to a single 2D plane in the 3D graphics system). In addition, if the entire plotting volume has valid coordinates in the 3D current \htmlref{Frame}{Frame} of the Plot3D, then additional lines are drawn along the edges of the 3D plotting volume so that the entire plotting volume is enclosed within a cuboid grid. } \sstinvocation{ RESULT = AST\_BORDER( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_BORDER = LOGICAL }{ .FALSE. is returned if the plotting space is completely filled by valid, unclipped physical coordinates (so that only a rectangular box was drawn around the edge). Otherwise, .TRUE. is returned. } } \sstnotes{ \sstitemlist{ \sstitem A value of .FALSE. will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. \sstitem An error results if either the current Frame or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the base and current Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} attribute is zero). } } } \sstroutine{ AST\_BOUNDINGBOX }{ Return a bounding box for previously drawn graphics }{ \sstdescription{ This routine returns the bounds of a box which just encompasess the graphics produced by the previous call to any of the \htmlref{Plot}{Plot} methods which produce graphical output. If no such previous call has yet been made, or if the call failed for any reason, then the bounding box returned by this routine is undefined. } \sstinvocation{ CALL AST\_BOUNDINGBOX( THIS, LBND, UBND, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ LBND( 2 ) = REAL (Returned) }{ A two element array in which is returned the lower limits of the bounding box on each of the two axes of the graphics coordinate system (the base \htmlref{Frame}{Frame} of the Plot). } \sstsubsection{ UBND( 2 ) = REAL (Returned) }{ A two element array in which is returned the upper limits of the bounding box on each of the two axes of the graphics coordinate system (the base Frame of the Plot). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem An error results if the base Frame of the Plot is not 2-dimensional. } } } \sstroutine{ AST\_BOX }{ Create a Box }{ \sstdescription{ This function creates a new \htmlref{Box}{Box} and optionally initialises its attributes. The Box class implements a \htmlref{Region}{Region} which represents a box with sides parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a pole). } \sstinvocation{ RESULT = AST\_BOX( FRAME, FORM, POINT1, POINT2, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ FORM = INTEGER (Given) }{ Indicates how the box is described by the remaining parameters. A value of zero indicates that the box is specified by a centre position and a corner position. A value of one indicates that the box is specified by a two opposite corner positions. } \sstsubsection{ POINT1( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). If FORM is zero, this array should contain the coordinates at the centre of the box. If FORM is one, it should contain the coordinates at the corner of the box which is diagonally opposite the corner specified by POINT2. } \sstsubsection{ POINT2( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute) containing the coordinates at any corner of the box. } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Box. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_BOX = INTEGER }{ A pointer to the new Box. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_CHANNEL }{ Create a Channel }{ \sstdescription{ This function creates a new \htmlref{Channel}{Channel} and optionally initialises its attributes. A Channel implements low-level input/output for the AST library. Writing an \htmlref{Object}{Object} to a Channel (using \htmlref{AST\_WRITE}{AST\_WRITE}) will generate a textual representation of that Object, and reading from a Channel (using \htmlref{AST\_READ}{AST\_READ}) will create a new Object from its textual representation. Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output. Alternatively, a Channel can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstinvocation{ RESULT = AST\_CHANNEL( SOURCE, SINK, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ SOURCE = SUBROUTINE (Given) }{ A source routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SourceFile attribute, this routine will be used by the Channel to obtain lines of input text. On each invocation, it should read the next input line from some external data store, and then return the resulting text to the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a negative line length when there are no more lines to read. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SOURCE value, and no value has been set for the SourceFile attribute, the Channel will read from standard input instead. } \sstsubsection{ SINK = SUBROUTINE (Given) }{ A sink routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SinkFile attribute, this routine will be used by the Channel to deliver lines of output text. On each invocation, it should obtain the next output line from the AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the resulting text to some external data store. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SINK value, and no value has been set for the SinkFile attribute, the Channel will write to standard output instead. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Channel. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CHANNEL = INTEGER }{ A pointer to the new Channel. } } \sstnotes{ \sstitemlist{ \sstitem The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST\_CHANNEL. However, this is not generally necessary for the null routine AST\_NULL (so long as the AST\_PAR include file has been used). \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. \sstitem Note that the null routine AST\_NULL (one underscore) is different to AST\_\_NULL (two underscores), which is the null Object pointer. } } } \sstroutine{ AST\_CIRCLE }{ Create a Circle }{ \sstdescription{ This function creates a new \htmlref{Circle}{Circle} and optionally initialises its attributes. A Circle is a \htmlref{Region}{Region} which represents a circle or sphere within the supplied \htmlref{Frame}{Frame}. } \sstinvocation{ RESULT = AST\_CIRCLE( FRAME, FORM, CENTRE, POINT, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ FORM = INTEGER (Given) }{ Indicates how the circle is described by the remaining parameters. A value of zero indicates that the circle is specified by a centre position and a position on the circumference. A value of one indicates that the circle is specified by a centre position and a scalar radius. } \sstsubsection{ CENTRE( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of the circle or sphere. } \sstsubsection{ POINT( $*$ ) = DOUBLE PRECISION (Given) }{ If FORM is zero, then this array should have one element for each Frame axis (Naxes attribute), and should be supplied holding the coordinates at a point on the circumference of the circle or sphere. If FORM is one, then this array should have one element only which should be supplied holding the scalar radius of the circle or sphere, as a geodesic distance within the Frame. } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Circle being created. The uncertainty in any point on the boundary of the Circle is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, Circle, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Circle. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Circle being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Circle. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CIRCLE = INTEGER }{ A pointer to the new Circle. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_CIRCLEPARS }{ Returns the geometric parameters of an Circle }{ \sstdescription{ This routine returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}. } \sstinvocation{ CALL AST\_CIRCLEPARS( THIS, CENTRE, RADIUS, P1, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Region}{Region}. } \sstsubsection{ CENTRE( $*$ ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates of the Circle centre. The length of this array should be no less than the number of axes in the associated coordinate system. } \sstsubsection{ RADIUS = DOUBLE PRECISION (Returned) }{ Returned holding the radius of the Circle, as an geodesic distance in the associated coordinate system. } \sstsubsection{ P1( $*$ ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates of a point on the circumference of the Circle. The length of this array should be no less than the number of axes in the associated coordinate system. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Circle has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Circle object may not be an accurate circle. } } } \sstroutine{ AST\_CLEAR }{ Clear attribute values for an Object }{ \sstdescription{ This routine clears the values of a specified set of attributes for an \htmlref{Object}{Object}. 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 \htmlref{AST\_TEST}{AST\_TEST} function to return the value .FALSE. for the attribute, indicating that no value has been set. } \sstinvocation{ CALL AST\_CLEAR( THIS, ATTRIB, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ ATTRIB = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a comma-separated list of the names of the attributes to be cleared. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem It does no harm to clear an attribute whose value has not been set. \sstitem An error will result if an attempt is made to clear the value of a read-only attribute. } } } \sstroutine{ AST\_CLIP }{ Set up or remove clipping for a Plot }{ \sstdescription{ This routine defines regions of a \htmlref{Plot}{Plot} which are to be clipped. Any subsequent graphical output created using the Plot will then be visible only within the unclipped regions of the plotting area. See also the \htmlref{Clip}{Clip} attribute. } \sstinvocation{ CALL AST\_CLIP( THIS, IFRAME, LBND, UBND, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ IFRAME = INTEGER (Given) }{ The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping limits supplied in LBND and UBND (below) refer. Clipping may be applied to any of the coordinate systems associated with a Plot (as defined by the Frames it contains), so this index may take any value from 1 to the number of Frames in the Plot (\htmlref{Nframe}{Nframe} attribute). In addition, the values AST\_\_BASE and AST\_\_CURRENT may be used to specify the base and current Frames respectively. For example, a value of AST\_\_CURRENT causes clipping to be performed in physical coordinates, while a value of AST\_\_BASE would clip in graphical coordinates. Clipping may also be removed completely by giving a value of AST\_\_NOFRAME. In this case any clipping bounds supplied (below) are ignored. } \sstsubsection{ LBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each axis of the clipping Frame (identified by the index IFRAME). This should contain the lower bound, on each axis, of the region which is to remain visible (unclipped). } \sstsubsection{ UBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each axis of the clipping Frame (identified by the index IFRAME). This should contain the upper bound, on each axis, of the region which is to remain visible (unclipped). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Only one clipping Frame may be active at a time. This routine will deactivate any previously-established clipping Frame before setting up new clipping limits. \sstitem The clipping produced by this routine is in addition to that specified by the Clip attribute which occurs at the edges of the plotting area established when the Plot is created (see \htmlref{AST\_PLOT}{AST\_PLOT}). The underlying graphics system may also impose further clipping. \sstitem When testing a graphical position for clipping, it is first transformed into the clipping Frame. The resulting coordinate on each axis is then checked against the clipping limits (given by LBND and UBND). By default, a position is clipped if any coordinate lies outside these limits. However, if a non-zero value is assigned to the Plot\texttt{'} s \htmlref{ClipOp}{ClipOp} attribute, then a position is only clipped if the coordinates on all axes lie outside their clipping limits. \sstitem If the lower clipping limit exceeds the upper limit for any axis, then the sense of clipping for that axis is reversed (so that coordinate values lying between the limits are clipped instead of those lying outside the limits). To produce a \texttt{"} hole\texttt{"} in a coordinate space (that is, an internal region where nothing is plotted), you should supply all the bounds in reversed order, and set the ClipOp attribute for the Plot to a non-zero value. \sstitem Either clipping limit may be set to the value AST\_\_BAD, which is equivalent to setting it to infinity (or minus infinity for a lower bound) so that it is not used. \sstitem If a graphical position results in any bad coordinate values (AST\_\_BAD) when transformed into the clipping Frame, then it is treated (for the purposes of producing graphical output) as if it were clipped. \sstitem When a Plot is used as a \htmlref{Mapping}{Mapping} to transform points (e.g. using \htmlref{AST\_TRAN2}{AST\_TRAN2}), any clipped output points are assigned coordinate values of AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. } } } \sstroutine{ AST\_CLONE }{ Clone (duplicate) an Object pointer }{ \sstdescription{ This function returns a duplicate pointer to an existing \htmlref{Object}{Object}. It also increments the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to keep track of how many pointers have been issued. Note that this function is NOT equivalent to an assignment statement, as in general the two pointers will not have the same value. } \sstinvocation{ RESULT = AST\_CLONE( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Original pointer to the Object. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_CLONE = INTEGER }{ A duplicate pointer to the same Object. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_CMPFRAME }{ Create a CmpFrame }{ \sstdescription{ This function creates a new \htmlref{CmpFrame}{CmpFrame} and optionally initialises its attributes. A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame). Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way. Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values. } \sstinvocation{ RESULT = AST\_CMPFRAME( FRAME1, FRAME2, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME1 = INTEGER (Given) }{ Pointer to the first component Frame. } \sstsubsection{ FRAME2 = INTEGER (Given) }{ Pointer to the second component Frame. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CMPFRAME = INTEGER }{ A pointer to the new CmpFrame. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_CMPMAP }{ Create a CmpMap }{ \sstdescription{ This function creates a new \htmlref{CmpMap}{CmpMap} and optionally initialises its attributes. A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be \texttt{"} in series\texttt{"} (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the earlier coordinates for each point and the second Mapping simultaneously transforms the later coordinates). Since a CmpMap is itself a Mapping, it can be used as a component in forming further CmpMaps. Mappings of arbitrary complexity may be built from simple individual Mappings in this way. } \sstinvocation{ RESULT = AST\_CMPMAP( MAP1, MAP2, SERIES, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ MAP1 = INTEGER (Given) }{ Pointer to the first component Mapping. } \sstsubsection{ MAP2 = INTEGER (Given) }{ Pointer to the second component Mapping. } \sstsubsection{ SERIES = LOGICAL (Given) }{ If a .TRUE. value is given for this argument, the two component Mappings will be connected in series. A .FALSE. value requests that they are connected in parallel. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CMPMAP = INTEGER }{ A pointer to the new CmpMap. } } \sstnotes{ \sstitemlist{ \sstitem If the component Mappings are connected in series, then using the resulting CmpMap to transform coordinates will cause the first Mapping to be applied, followed by the second Mapping. If the inverse CmpMap transformation is requested, the two component Mappings will be applied in both the reverse order and the reverse direction. \sstitem When connecting two component Mappings in series, the number of output coordinates generated by the first Mapping (its \htmlref{Nout}{Nout} attribute) must equal the number of input coordinates accepted by the second Mapping (its \htmlref{Nin}{Nin} attribute). \sstitem If the component Mappings of a CmpMap are connected in parallel, then the first Mapping will be used to transform the earlier input coordinates for each point (and to produce the earlier output coordinates) and the second Mapping will be used simultaneously to transform the remaining input coordinates (to produce the remaining output coordinates for each point). If the inverse transformation is requested, each Mapping will still be applied to the same coordinates, but in the reverse direction. \sstitem When connecting two component Mappings in parallel, there is no restriction on the number of input and output coordinates for each Mapping. \sstitem Note that the component Mappings supplied are not copied by AST\_CMPMAP (the new CmpMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a CmpMap containing a copy of its component Mappings is required, then a copy of the CmpMap should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_CMPREGION }{ Create a CmpRegion }{ \sstdescription{ This function creates a new \htmlref{CmpRegion}{CmpRegion} and optionally initialises its attributes. A CmpRegion is a \htmlref{Region}{Region} which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion. The two component Region need not refer to the same coordinate \htmlref{Frame}{Frame}, but it must be possible for the \htmlref{AST\_CONVERT}{AST\_CONVERT} function to determine a \htmlref{Mapping}{Mapping} between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the AST\_CONVERT function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region. Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way. } \sstinvocation{ RESULT = AST\_CMPREGION( REGION1, REGION2, OPER, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION1 = INTEGER (Given) }{ Pointer to the first component Region. } \sstsubsection{ REGION2 = INTEGER (Given) }{ Pointer to the second component Region. This Region will be transformed into the coordinate Frame of the first region before use. An error will be reported if this is not possible. } \sstsubsection{ OPER = INTEGER (Given) }{ The boolean operator with which to combine the two Regions. This must be one of the symbolic constants AST\_\_AND, AST\_\_OR or AST\_\_XOR. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpRegion. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CMPREGION = INTEGER }{ A pointer to the new CmpRegion. } } \sstnotes{ \sstitemlist{ \sstitem If one of the supplied Regions has an associated uncertainty, that uncertainty will also be used for the returned CmpRegion. If both supplied Regions have associated uncertainties, the uncertainty associated with the first Region will be used for the returned CmpRegion. \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the CmpRegion. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_COLUMNNAME }{ Get the name of the column at a given index within the Table }{ \sstdescription{ This function returns a string holding the name of the column with the given index within the \htmlref{Table}{Table}. This function is intended primarily as a means of iterating round all the columns in a Table. For this purpose, the number of columns in the Table is given by the \htmlref{Ncolumn}{Ncolumn} attribute of the Table. This function could then be called in a loop, with the index value going from one to Ncolumn. Note, the index associated with a column decreases monotonically with the age of the column: the oldest Column in the Table will have index one, and the Column added most recently to the Table will have the largest index. } \sstinvocation{ RESULT = AST\_COLUMNNAME( THIS, INDEX, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ INDEX = INTEGER (Given) }{ The index into the list of columns. The first column has index one, and the last has index \texttt{"} Ncolumn\texttt{"} . } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_COLUMNNAME = CHARACTER $*$ ( AST\_\_SZCHR ) }{ The upper case column name. } } \sstnotes{ \sstitemlist{ \sstitem A blank string will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_COLUMNNULL }{ Get or set the null value for an integer column of a FITS table }{ \sstdescription{ This function allows a null value to be stored with a named integer-valued column in a \htmlref{FitsTable}{FitsTable}. The supplied null value is assigned to the TNULLn keyword in the FITS header associated with the FitsTable. A value in the named column is then considered to be null if 1) it equals the null value supplied to this function, or 2) no value has yet been stored in the cell. As well as setting a new null value, this function also returns the previous null value. If no null value has been set previously, a default value will be returned. This default will be an integer value that does not currently occur anywhere within the named column. If no such value can be found, what happens depends on whether the column contains any cells in which no values have yet been stored. If so, an error will be reported. Otherwise (i.e. if there are no null values in the column), an arbitrary value of zero will be returned as the function value, and no TNULLn keyword will be stored in the FITS header. A flag is returned indicating if the returned null value was set explicitly by a previous call to this function, or is a default value. A second flag is returned indicating if the named column contains any null values (i.e. values equal to the supplied null value, or cells to which no value has yet been assigned). } \sstinvocation{ RESULT = AST\_COLUMNNULL( THIS, COLUMN, SET, NEWVAL, WASSET, HASNULL, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ SET = LOGICAL (Given) }{ If .TRUE., the value supplied for argument NEWVAL will be stored as the current null value, replacing any value set by a previous call to this function. If .FALSE., the value supplied for argument NEWVAL is ignored and the current null value is left unchanged. } \sstsubsection{ NEWVAL = INTEGER (Given) }{ The new null value to use. Ignored if SET is .FALSE. An error will be reported if the supplied value is outside the range of values that can be stored in the integer data type associated with the column. } \sstsubsection{ WASSET = LOGICAL (Returned) }{ .TRUE. will be returned if the returned null value was set previously via an earlier invocation of this function. .FALSE. is returned otherwise. If the named column does not exist, or an error occurs, a value of .FALSE. is returned. } \sstsubsection{ HASNULL = LOGICAL (Returned) }{ .TRUE. will be returned if and only if the named column currently contains any values equal to the null value on exit (i.e. NEWVAL if SET is .TRUE. or the returned function value otherwise), or contains any empty cells. If the named column does not exist, or an error occurs, a value of .FALSE. is returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_COLUMNNULL = INTEGER }{ The null value that was in use on entry to this function. If a null value has been set by a previous invocation of this function, it will be returned. Otherwise, if SET is .TRUE., the supplied NEWVAL value is returned. Otherwise, a default value is chosen (if possible) that does not currently occur in the named column. If all available values are in use in the column, an error is reported if and only if the column contains any empty cells. Otherwise, a value of zero is returned. A value of zero is also returned if the named column does not exist, or an error occurs. } } \sstnotes{ \sstitemlist{ \sstitem The FITS binary table definition allows only integer-valued columns to have an associated null value. This routine will return without action if the column is not integer-valued. } } } \sstroutine{ AST\_COLUMNSHAPE }{ Returns the shape of the values in a named column }{ \sstdescription{ This routine returns the number of dimensions spaned by each value in a named column of a \htmlref{Table}{Table}, together with the length of each dimension. These are the values supplied when the column was created using \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}. } \sstinvocation{ CALL AST\_COLUMNSHAPE( THIS, COLUMN, MXDIM, NDIM, DIMS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the upper case name of the column. Trailing spaces are ignored. } \sstsubsection{ MXDIM = INTEGER (Given) }{ The length of the DIMS array. } \sstsubsection{ NDIM = INTEGER (Returned) }{ The number of dimensions spanned by values in the named column. This will be zero if the column contains scalar values. } \sstsubsection{ DIMS( MXDIM ) = INTEGER (Returned) }{ An array in which to return the length of each dimension. Any excess trailing elements will be filled with the value 1. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested column cannot be found in the given Table. A value of zero is returned for NDIM and the supplied values in DIMS are left unchanged. \sstitem A value of zero is returned for NDIM if an error occurs. } } } \sstroutine{ AST\_COLUMNSIZE }{ Get the number of bytes needed to hold a full column of data }{ \sstdescription{ This function returns the number of bytes of memory that must be allocated prior to retrieving the data from a column using \htmlref{AST\_GETCOLUMNDATA}{AST\_GETCOLUMNDATA}. } \sstinvocation{ RESULT = AST\_COLUMNSIZE( THIS, COLUMN, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL} = INTEGER }{ The number of bytes required to store the column data. } } \sstnotes{ \sstitemlist{ \sstitem An error will be reported if the named column does not exist in the \htmlref{FitsTable}{FitsTable}. \sstitem Zero will be returned as the function value in an error occurs. } } } \sstroutine{ AST\_CONVERT }{ Determine how to convert between two coordinate systems }{ \sstdescription{ This function compares two Frames and determines whether it is possible to convert between the coordinate systems which they represent. If conversion is possible, it returns a \htmlref{FrameSet}{FrameSet} which describes the conversion and which may be used (as a \htmlref{Mapping}{Mapping}) to transform coordinate values in either direction. The same function may also be used to determine how to convert between two FrameSets (or between a \htmlref{Frame}{Frame} and a FrameSet, or vice versa). This mode is intended for use when (for example) two images have been calibrated by attaching a FrameSet to each. AST\_CONVERT might then be used to search for a celestial coordinate system that both images have in common, and the result could then be used to convert between the pixel coordinates of both images -- having effectively used their celestial coordinate systems to align them. When using FrameSets, there may be more than one possible intermediate coordinate system in which to perform the conversion (for instance, two FrameSets might both have celestial coordinates, detector coordinates, pixel coordinates, etc.). A comma-separated list of coordinate system domains may therefore be given which defines a priority order to use when selecting the intermediate coordinate system. The path used for conversion must go via an intermediate coordinate system whose \htmlref{Domain}{Domain} attribute matches one of the domains given. If conversion cannot be achieved using the first domain, the next one is considered, and so on, until success is achieved. } \sstinvocation{ RESULT = AST\_CONVERT( FROM, TO, DOMAINLIST, STATUS ) } \sstarguments{ \sstsubsection{ FROM = INTEGER (Given) }{ Pointer to a Frame which represents the \texttt{"} source\texttt{"} coordinate system. This is the coordinate system in which you already have coordinates available. If a FrameSet is given, its current Frame (as determined by its \htmlref{Current}{Current} attribute) is taken to describe the source coordinate system. Note that the \htmlref{Base}{Base} attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). } \sstsubsection{ TO = INTEGER (Given) }{ Pointer to a Frame which represents the \texttt{"} destination\texttt{"} coordinate system. This is the coordinate system into which you wish to convert your coordinates. If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe the destination coordinate system. Note that the Base attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). } \sstsubsection{ DOMAINLIST = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a comma-separated list of Frame domains. This may be used to define a priority order for the different intermediate coordinate systems that might be used to perform the conversion. The function will first try to obtain a conversion by making use only of an intermediate coordinate system whose Domain attribute matches the first domain in this list. If this fails, the second domain in the list will be used, and so on, until conversion is achieved. A blank domain (e.g. two consecutive commas) indicates that all coordinate systems should be considered, regardless of their domains. This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply a blank string. This is normally appropriate if either of the source or destination coordinate systems are described by Frames (rather than FrameSets), since there is then usually only one possible choice of intermediate coordinate system. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ If the \htmlref{AlignSideBand}{AlignSideBand} attribute is non-zero, alignment occurs in the upper sideband expressed within the spectral system and standard of rest given by attributes \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}. If AlignSideBand is zero, the two DSBSpecFrames are aligned as if they were simple SpecFrames (i.e. the \htmlref{SideBand}{SideBand} is ignored). } \sstsubsection{ Frame }{ This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem. } \sstsubsection{ FrameSet }{ If either of the FROM or TO arguments is a pointer to a FrameSet, then AST\_CONVERT will attempt to convert from the coordinate system described by the current Frame of the FROM FrameSet to that described by the current Frame of the TO FrameSet. To achieve this, it will consider all of the Frames within each FrameSet as a possible way of reaching an intermediate coordinate system that can be used for the conversion. There is then the possibility that more than one conversion path may exist and, unless the choice is sufficiently restricted by the DOMAINLIST string, the sequence in which the Frames are considered can be important. In this case, the search for a conversion path proceeds as follows: \sstitemlist{ \sstitem Each field in the DOMAINLIST string is considered in turn. \sstitem The Frames within each FrameSet are considered in a specific order: (1) the base Frame is always considered first, (2) after this come all the other Frames in Frame-index order (but omitting the base and current Frames), (3) the current Frame is always considered last. However, if either FrameSet\texttt{'} s \htmlref{Invert}{Invert} attribute is set to a non-zero value (so that the FrameSet is inverted), then its Frames are considered in reverse order. (Note that this still means that the base Frame is considered first and the current Frame last, because the Invert value will also cause these Frames to swap places.) \sstitem All source Frames are first considered (in the appropriate order) for conversion to the first destination Frame. If no suitable intermediate coordinate system emerges, they are then considered again for conversion to the second destination Frame (in the appropriate order), and so on. \sstitem Generally, the first suitable intermediate coordinate system found is used. However, the overall Mapping between the source and destination coordinate systems is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one transformation is defined, the forward one is preferred. \sstitem If the domain of the intermediate coordinate system matches the current DOMAINLIST field, the conversion path is accepted. Otherwise, the next DOMAINLIST field is considered and the process repeated. } If conversion is possible, the Base attributes of the two FrameSets will be modified on exit to identify the Frames used to access the intermediate coordinate system which was finally accepted. Note that it is possible to force a particular Frame within a FrameSet to be used as the basis for the intermediate coordinate system, if it is suitable, by (a) focussing attention on it by specifying its domain in the DOMAINLIST string, or (b) making it the base Frame, since this is always considered first. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ Alignment occurs within the time system and time scale given by attributes AlignSystem and \htmlref{AlignTimeScale}{AlignTimeScale}. } } \sstreturnedvalue{ \sstsubsection{ AST\_CONVERT = INTEGER }{ If the requested coordinate conversion is possible, the function returns a pointer to a FrameSet which describes the conversion. Otherwise, a null \htmlref{Object}{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 argument. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the TO argument. The Mapping which inter-relates these two Frames will perform the required conversion between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with \htmlref{AST\_TRAN2}{AST\_TRAN2}), then it provides a means of converting coordinates from the source to the destination coordinate system (or vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the destination coordinate system. } } \sstexamples{ \sstexamplesubsection{ CVT = AST\_CONVERT( A, B, \texttt{'} \texttt{'} , STATUS ) }{ Attempts to convert between the coordinate systems represented by A and B (assumed to be Frames). If successful, a FrameSet is returned via the CVT pointer which may be used to apply the conversion to sets of coordinates (e.g. using AST\_TRAN2). } \sstexamplesubsection{ CVT = AST\_CONVERT( \htmlref{AST\_SKYFRAME}{AST\_SKYFRAME}( \texttt{'} \texttt{'} , STATUS ), AST\_SKYFRAME( \texttt{'} \htmlref{Equinox}{Equinox}=2005\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Creates a FrameSet which describes precession in the default FK5 celestial coordinate system between equinoxes J2000 (also the default) and J2005. The returned CVT pointer may then be passed to AST\_TRAN2 to apply this precession correction to any number of coordinate values given in radians. Note that the returned FrameSet also contains information about how to format coordinate values. This means that setting its \htmlref{Report}{Report} attribute to 1 is a simple way to obtain printed output (formatted in sexagesimal notation) to show the coordinate values before and after conversion. } \sstexamplesubsection{ CVT = AST\_CONVERT( A, B, \texttt{'} SKY,DETECTOR,\texttt{'} , STATUS ) }{ Attempts to convert between the coordinate systems represented by the current Frames of A and B (now assumed to be FrameSets), via the intermediate \texttt{"} SKY\texttt{"} coordinate system. This, by default, is the Domain associated with a celestial coordinate system represented by a \htmlref{SkyFrame}{SkyFrame}. If this fails (for example, because either FrameSet lacks celestial coordinate information), then the user-defined \texttt{"} DETECTOR\texttt{"} coordinate system is used instead. If this also fails, then all other possible ways of achieving conversion are considered before giving up. The returned pointer CVT indicates whether conversion was possible and will have the value AST\_\_NULL if it was not. If conversion was possible, CVT will point at a new FrameSet describing the conversion. The Base attributes of the two FrameSets will be set by AST\_CONVERT to indicate which of their Frames was used for the intermediate coordinate system. This means that you can subsequently determine which coordinate system was used by enquiring the Domain attribute of either base Frame. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the TO Frame. See the description of the AlignSystem attribute for further details. \sstitem When aligning (say) two images, which have been calibrated by attaching FrameSets to them, it is usually necessary to convert between the base Frames (representing \texttt{"} native\texttt{"} pixel coordinates) of both FrameSets. This may be achieved by inverting the FrameSets (e.g. using astInvert) so as to interchange their base and current Frames before using astConvert. \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_CONVEX$<$X$>$ }{ Create a new Polygon representing the convex hull of a 2D data grid }{ \sstdescription{ This is a set of functions that create the shortest \htmlref{Polygon}{Polygon} that encloses all pixels with a specified value within a gridded 2-dimensional data array (e.g. an image). A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter STARPIX. You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST\_CONVEX$<$X$>$ are procesing data with type REAL, you should use the function AST\_CONVEXR (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstinvocation{ RESULT = AST\_CONVEX$<$X$>$( VALUE, OPER, ARRAY, LBND, UBND, STARPIX, STATUS ) } \sstarguments{ \sstsubsection{ VALUE = $<$Xtype$>$ (Given) }{ A data value that specifies the pixels to be included within the convex hull. } \sstsubsection{ OPER = INTEGER (Given) }{ Indicates how the VALUE parameter is used to select the required pixels. It can have any of the following values: \sstitemlist{ \sstitem AST\_\_LT: include pixels with value less than VALUE. \sstitem AST\_\_LE: include pixels with value less than or equal to VALUE. \sstitem AST\_\_EQ: include pixels with value equal to VALUE. \sstitem AST\_\_NE: include pixels with value not equal to VALUE. \sstitem AST\_\_GE: include pixels with value greater than or equal to VALUE. \sstitem AST\_\_GT: include pixels with value greater than VALUE. } } \sstsubsection{ ARRAY( $*$ ) = $<$Xtype$>$ (Given) }{ A 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_CONVEXR, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ LBND( 2 ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND( 2) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND and UBND together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND(J)-LBND(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter STARPIX. } \sstsubsection{ STARPIX = LOGICAL (Given) }{ A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If .TRUE., the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If .FALSE., the definition of pixel coordinate used by other AST functions such as AST\_RESAMPLE, AST\_MASK, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CONVEX$<$X$>$ = INTEGER }{ A pointer to the required Polygon. AST\_\_NULL is returned without error if the array contains no pixels that satisfy the criterion specified by VALUE and OPER. } } \sstnotes{ \sstitemlist{ \sstitem AST\_\_NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name AST\_CONVEX$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem UI: INTEGER (treated as unsigned) \sstitem S: INTEGER$*$2 (short integer) \sstitem US: INTEGER$*$2 (short integer, treated as unsigned) \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_CONVEXD would be used to process DOUBLE PRECISION data, while AST\_CONVEXS would be used to process short integer data (stored in an INTEGER$*$2 array), etc. For compatibility with other Starlink facilities, the codes W and UW are provided as synonyms for S and US respectively (but only in the Fortran interface to AST). } } \sstroutine{ AST\_COPY }{ Copy an Object }{ \sstdescription{ This function creates a copy of an \htmlref{Object}{Object} and returns a pointer to the resulting new Object. It makes a \texttt{"} deep\texttt{"} copy, which contains no references to any other Object (i.e. if the original Object contains references to other Objects, then the actual data are copied, not simply the references). This means that modifications may safely be made to the copy without indirectly affecting any other Object. } \sstinvocation{ RESULT = AST\_COPY( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object to be copied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_COPY = INTEGER }{ Pointer to the new Object. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_CURRENTTIME }{ Return the current system time }{ \sstdescription{ This routine returns the current system time, represented in the form specified by the supplied \htmlref{TimeFrame}{TimeFrame}. That is, the returned floating point value should be interpreted using the attribute values of the TimeFrame. This includes \htmlref{System}{System}, \htmlref{TimeOrigin}{TimeOrigin}, \htmlref{LTOffset}{LTOffset}, \htmlref{TimeScale}{TimeScale}, and Unit. } \sstinvocation{ RESULT = AST\_CURRENTTIME( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the TimeFrame. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_CURRENTTIME = DOUBLE }{ } } \sstnotes{ \sstitemlist{ \sstitem Values of AST\_\_BAD will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. \sstitem It is assumes that the system time (returned by the C time() function) follows the POSIX standard, representing a continuous monotonic increasing count of SI seconds since the epoch 00:00:00 UTC 1 January 1970 AD (equivalent to TAI with a constant offset). Resolution is one second. \sstitem An error will be reported if the TimeFrame has a TimeScale value which cannot be converted to TAI (e.g. \texttt{"} angular\texttt{"} systems such as UT1, GMST, LMST and LAST). \sstitem Any inaccuracy in the system clock will be reflected in the value returned by this function. } } } \sstroutine{ AST\_CURVE }{ Draw a geodesic curve }{ \sstdescription{ This routine draws a geodesic curve between two points in the physical coordinate system of a \htmlref{Plot}{Plot}. The curve drawn is the path of shortest distance joining the two points (as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function for the current \htmlref{Frame}{Frame} of the Plot). For example, if the current Frame is a basic Frame, then the curve joining the two points will be a straight line in physical coordinate space. If the current Frame is more specialised and describes, for instance, a sky coordinate system, then the geodesic curve would be a great circle in physical coordinate space passing through the two sky positions given. Note that the geodesic curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{AST\_CLIP}{AST\_CLIP}. If you need to draw many geodesic curves end-to-end, then the \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} routine is equivalent to repeatedly calling AST\_CURVE, but will usually be more efficient. If you need to draw curves which are not geodesics, see \htmlref{AST\_GENCURVE}{AST\_GENCURVE} or \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}. } \sstinvocation{ CALL AST\_CURVE( THIS, START, FINISH, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ START( $*$ ) = DOUBLE PRECISION (Given) }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the first point on the geodesic curve. } \sstsubsection{ FINISH( $*$ ) = DOUBLE PRECISION (Given) }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the second point on the geodesic curve. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn if either of the START or FINISH arrays contains any coordinates with the value AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_DECOMPOSE }{ Decompose a Mapping into two component Mappings }{ \sstdescription{ This routine returns pointers to two Mappings which, when applied either in series or parallel, are equivalent to the supplied \htmlref{Mapping}{Mapping}. Since the \htmlref{Frame}{Frame} class inherits from the Mapping class, Frames can be considered as special types of Mappings and so this method can be used to decompose either CmpMaps or CmpFrames. } \sstinvocation{ CALL AST\_DECOMPOSE( THIS, MAP1, MAP2, SERIES, INVERT1, INVERT2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping. } \sstsubsection{ MAP1 = INTEGER (Returned) }{ A pointer to first component Mapping. } \sstsubsection{ MAP2 = INTEGER (Returned) }{ A pointer to second component Mapping. } \sstsubsection{ SERIES = LOGICAL (Returned) }{ Indicates if the component Mappings are applied in series or parallel. A .TRUE. value means that the supplied Mapping is equivalent to applying MAP1 followed by MAP2 in series. A zero value means that the supplied Mapping is equivalent to applying MAP1 to the lower numbered axes and MAP2 to the higher numbered axes, in parallel. } \sstsubsection{ INVERT1 = INTEGER (Returned) }{ The value of the \htmlref{Invert}{Invert} attribute to be used with MAP1. } \sstsubsection{ INVERT2 = INTEGER (Returned) }{ The value of the Invert attribute to be used with MAP2. } } \sstapplicability{ \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If the supplied Mapping is a CmpMap, then MAP1 and MAP2 will be returned holding pointers to the component Mappings used to create the CmpMap, either in series or parallel. Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied CmpMap. This is because the CmpMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the CmpMap was first created). These are the Invert values which are returned in INVERT1 and INVERT2. } \sstsubsection{ \htmlref{TranMap}{TranMap} }{ If the supplied Mapping is a TranMap, then MAP1 and MAP2 will be returned holding pointers to the forward and inverse Mappings represented by the TranMap (zero will be returned for SERIES). Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied TranMap. This is because the TranMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the TranMap was first created). These are the Invert values which are returned in INVERT1 and INVERT2. } \sstsubsection{ Mapping }{ For any class of Mapping other than a CmpMap, MAP1 will be returned holding a clone of the supplied Mapping pointer, and MAP2 will be returned holding AST\_\_NULL. INVERT1 will be returned holding the current value of the Invert attribute for the supplied Mapping, and INVERT2 will be returned holding zero. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ If the supplied Mapping is a CmpFrame, then MAP1 and MAP2 will be returned holding pointers to the component Frames used to create the CmpFrame. The component Frames are considered to be in applied in parallel. } \sstsubsection{ Frame }{ For any class of Frame other than a CmpFrame, MAP1 will be returned holding a clone of the supplied Frame pointer, and MAP2 will be returned holding AST\_\_NULL. } } \sstnotes{ \sstitemlist{ \sstitem The returned Invert values should be used in preference to the current values of the Invert attribute in map1 and map2. This is because the attributes may have changed value since the Mappings were combined. \sstitem Any changes made to the component Mappings using the returned pointers will be reflected in the supplied Mapping. } } } \sstroutine{ AST\_DELETE }{ Delete an Object }{ \sstdescription{ This routine deletes an \htmlref{Object}{Object}, freeing all resources associated with it and rendering any remaining pointers to the Object invalid. Note that deletion is unconditional, regardless of whether other pointers to the Object are still in use (possibly within other Objects). A safer approach is to defer deletion, until all references to an Object have expired, by using \htmlref{AST\_BEGIN}{AST\_BEGIN}/\htmlref{AST\_END}{AST\_END} (together with \htmlref{AST\_CLONE}{AST\_CLONE} and \htmlref{AST\_ANNUL}{AST\_ANNUL} if necessary). } \sstinvocation{ CALL AST\_DELETE( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given and Returned) }{ Pointer to the Object to be deleted. A null pointer value (AST\_\_NULL) is always returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value on entry, although no further error report will be made if it subsequently fails under these circumstances. } } } \sstroutine{ AST\_DELFITS }{ Delete the current FITS card in a FitsChan }{ \sstdescription{ This routine deletes the current FITS card from a \htmlref{FitsChan}{FitsChan}. The current card may be selected using the \htmlref{Card}{Card} attribute (if its index is known) or by using \htmlref{AST\_FINDFITS}{AST\_FINDFITS} (if only the FITS keyword is known). After deletion, the following card becomes the current card. } \sstinvocation{ CALL AST\_DELFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if the FitsChan is initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the Card attribute exceeds the number of cards in the FitsChan). \sstitem If there are no subsequent cards in the FitsChan, then the Card attribute is left pointing at the \texttt{"} end-of-file\texttt{"} after deletion (i.e. is set to one more than the number of cards in the FitsChan). } } } \sstroutine{ AST\_DISTANCE }{ Calculate the distance between two points in a Frame }{ \sstdescription{ This function finds the distance between two points whose \htmlref{Frame}{Frame} coordinates are given. The distance calculated is that along the geodesic curve that joins the two points. For example, in a basic Frame, the distance calculated will be the Cartesian distance along the straight line joining the two points. For a more specialised Frame describing a sky coordinate system, however, it would be the distance along the great circle passing through two sky positions. } \sstinvocation{ RESULT = AST\_DISTANCE( THIS, POINT1, POINT2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ POINT1( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ POINT2( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis containing the coordinates of the second point. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_DISTANCE = DOUBLE PRECISION }{ The distance between the two points. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input coordinates has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_DOWNSIZE }{ Reduce the number of vertices in a Polygon }{ \sstdescription{ This function returns a pointer to a new \htmlref{Polygon}{Polygon} that contains a subset of the vertices in the supplied Polygon. The subset is chosen so that the returned Polygon is a good approximation to the supplied Polygon, within the limits specified by the supplied parameter values. That is, the density of points in the returned Polygon is greater at points where the curvature of the boundary of the supplied Polygon is greater. } \sstinvocation{ RESULT = AST\_DOWNSIZE( THIS, MAXERR, MAXVERT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Polygon. } \sstsubsection{ MAXERR = DOUBLE PRECISION (Given) }{ The maximum allowed discrepancy between the supplied and returned Polygons, expressed as a geodesic distance within the Polygon\texttt{'} s coordinate frame. If this is zero or less, the returned Polygon will have the number of vertices specified by MAXVERT. } \sstsubsection{ MAXVERT = INTEGER (Given) }{ The maximum allowed number of vertices in the returned Polygon. If this is less than 3, the number of vertices in the returned Polygon will be the minimum needed to achieve the maximum discrepancy specified by MAXERR. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_DOWNSIZE = INTEGER }{ Pointer to the new Polygon. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_DSBSPECFRAME }{ Create a DSBSpecFrame }{ \sstdescription{ This function creates a new \htmlref{DSBSpecFrame}{DSBSpecFrame} and optionally initialises its attributes. A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents positions in a spectrum obtained using a dual sideband instrument. Such an instrument produces a spectrum in which each point contains contributions from two distinctly different frequencies, one from the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). Corresponding LSB and USB frequencies are connected by the fact that they are an equal distance on either side of a fixed central frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. When quoting a position within such a spectrum, it is necessary to indicate whether the quoted position is the USB position or the corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this indication. Another option that the SideBand attribute provides is to represent a spectral position by its topocentric offset from the LO frequency. In practice, the LO frequency is specified by giving the distance from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically this central position is that of some interesting spectral feature. The distance from this central position to the LO frequency is known as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can be a signed value in order to indicate whether the LO frequency is above or below the central position. } \sstinvocation{ RESULT = AST\_DSBSPECFRAME( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new DSBSpecFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_DSBSPECFRAME = INTEGER }{ A pointer to the new DSBSpecFrame. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_EBUF }{ End the current graphical buffering context }{ \sstdescription{ This routine ends the current graphics buffering context. It should match a corresponding call to the AST\_EBUF routine. } \sstinvocation{ CALL AST\_EBUF( THIS STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this routine simply invokes the astGEBuf function in the grf module. } } } \sstroutine{ AST\_ELLIPSE }{ Create a Ellipse }{ \sstdescription{ This function creates a new \htmlref{Ellipse}{Ellipse} and optionally initialises its attributes. A Ellipse is a \htmlref{Region}{Region} which represents a elliptical area within the supplied 2-dimensional \htmlref{Frame}{Frame}. } \sstinvocation{ RESULT = AST\_ELLIPSE( FRAME, FORM, CENTRE, POINT1, POINT2, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ FORM = INTEGER (Given) }{ Indicates how the ellipse is described by the remaining parameters. A value of zero indicates that the ellipse is specified by a centre position and two positions on the circumference. A value of one indicates that the ellipse is specified by its centre position, the half-lengths of its two axes, and the orientation of its first axis. } \sstsubsection{ CENTRE( 2 ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates at the centre of the ellipse. } \sstsubsection{ POINT1( 2 ) = DOUBLE PRECISION (Given) }{ If FORM is zero, this array should contain the coordinates of one of the four points where an axis of the ellipse crosses the circumference of the ellipse. If FORM is one, it should contain the lengths of semi-major and semi-minor axes of the ellipse, given as geodesic distances within the Frame. } \sstsubsection{ POINT2( 2 ) = DOUBLE PRECISION (Given) }{ If FORM is zero, this array should containing the coordinates at some other point on the circumference of the ellipse, distinct from POINT1. If FORM is one, the first element of this array should hold the angle between the second axis of the Frame and the first ellipse axis (i.e. the ellipse axis which is specified first in the POINT1 array), and the second element will be ignored. The angle should be given in radians, measured positive in the same sense as rotation from the positive direction of the second Frame axis to the positive direction of the first Frame axis. } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Ellipse being created. The uncertainty in any point on the boundary of the Ellipse is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, Ellipse, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Ellipse. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Ellipse being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Ellipse. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_ELLIPSE = INTEGER }{ A pointer to the new Ellipse. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_ELLIPSEPARS }{ Returns the geometric parameters of an Ellipse }{ \sstdescription{ This routine returns the geometric parameters describing the supplied ellipse. } \sstinvocation{ CALL AST\_ELLIPSEPARS( THIS, CENTRE, A, B, ANGLE, P1, P2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Region}{Region}. } \sstsubsection{ CENTRE( 2 ) = DOUBLE PRECISION (Returned) }{ The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays. } \sstsubsection{ A = DOUBLE PRECISION (Returned) }{ Returned holding the half-length of the first axis of the ellipse. } \sstsubsection{ B = DOUBLE PRECISION (Returned) }{ Returned holding the half-length of the second axis of the ellipse. } \sstsubsection{ ANGLE = DOUBLE PRECISION (Returned) }{ If the coordinate system in which the Ellipse is defined has axes (X,Y), then ANGLE is returned holding the angle from the positive direction of the Y axis to the first axis of the ellipse, in radians. Positive rotation is in the same sense as rotation from the positive direction of Y to the positive direction of X. } \sstsubsection{ P1( 2 ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates at one of the two ends of the first axis of the ellipse. } \sstsubsection{ P2( 2 ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates at one of the two ends of the second axis of the ellipse. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Ellipse has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Ellipse object may not be an accurate ellipse. \sstitem Values of AST\_\_BAD are returned for the parameters without error if the ellipse is degenerate or undefined. } } } \sstroutine{ AST\_EMPTYFITS }{ Delete all cards in a FitsChan }{ \sstdescription{ This routine deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}. } \sstinvocation{ CALL AST\_EMPTYFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This method simply deletes the cards currently in the FitsChan. Unlike \htmlref{AST\_WRITEFITS}{AST\_WRITEFITS}, they are not first written out to the sink function or sink file. \sstitem Any Tables or warnings stored in the FitsChan are also deleted. \sstitem This method attempt to execute even if an error has occurred previously. } } } \sstroutine{ AST\_END }{ End an AST context }{ \sstdescription{ This routine ends an AST context which was begun with a matching invocation of \htmlref{AST\_BEGIN}{AST\_BEGIN}. Any \htmlref{Object}{Object} pointers created within this context will be annulled (just as if \htmlref{AST\_ANNUL}{AST\_ANNUL} had been invoked) and will cease to be valid afterwards, unless they have previously been exported using \htmlref{AST\_EXPORT}{AST\_EXPORT} or rendered exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}. If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. } \sstinvocation{ CALL AST\_END( STATUS ) } \sstarguments{ \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value. \sstitem Contexts delimited by AST\_BEGIN and AST\_END may be nested to any depth. } } } \sstroutine{ AST\_ESCAPES }{ Control whether graphical escape sequences are included in strings }{ \sstdescription{ The \htmlref{Plot}{Plot} class defines a set of escape sequences which can be included within a text string in order to control the appearance of sub-strings within the text. See the \htmlref{Escape}{Escape} attribute for a description of these escape sequences. It is usually inappropriate for AST to return strings containing such escape sequences when called by application code. For instance, an application which displays the value of the \htmlref{Title}{Title} attribute of a \htmlref{Frame}{Frame} usually does not want the displayed string to include potentially long escape sequences which a human read would have difficuly interpreting. Therefore the default behaviour is for AST to strip out such escape sequences when called by application code. This default behaviour can be changed using this function. } \sstinvocation{ RESULT = AST\_ESCAPES( NEWVAL, STATUS ) } \sstarguments{ \sstsubsection{ NEWVAL = INTEGER (Given) }{ A flag which indicates if escapes sequences should be included in returned strings. If zero is supplied, escape sequences will be stripped out of all strings returned by any AST function. If a positive value is supplied, then any escape sequences will be retained in the value returned to the caller. If a negative value is supplied, the current value of the flag will be left unchanged. } } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ This routine applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_ESCAPES = INTEGER }{ The value of the flag on entry to this function. } } \sstnotes{ \sstitemlist{ \sstitem This function also controls whether the \htmlref{AST\_STRIPESCAPES}{AST\_STRIPESCAPES} function removes escape sequences from the supplied string, or returns the supplied string without change. \sstitem This function attempts to execute even if an error has already occurred. } } } \sstroutine{ AST\_EXEMPT }{ Exempt an Object pointer from AST context handling }{ \sstdescription{ This routine exempts an \htmlref{Object}{Object} pointer from AST context handling, as implemented by \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END}. This means that the pointer will not be affected when AST\_END is called and will remain active until the end of the program, or until explicitly annulled using \htmlref{AST\_ANNUL}{AST\_ANNUL}. If possible, you should avoid using this routine when writing applications. It is provided mainly for developers of other libraries, who may wish to retain references to AST Objects in internal data structures, and who therefore need to avoid the effects of AST\_BEGIN and AST\_END. } \sstinvocation{ CALL AST\_EXEMPT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Object pointer to be exempted from context handling. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } } \sstroutine{ AST\_EXPORT }{ Export an Object pointer to an outer context }{ \sstdescription{ This routine exports an \htmlref{Object}{Object} pointer from the current AST context into the context that encloses the current one. This means that the pointer will no longer be annulled when the current context is ended (with \htmlref{AST\_END}{AST\_END}), but only when the next outer context (if any) ends. } \sstinvocation{ CALL AST\_EXPORT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Object pointer to be exported. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem It is only sensible to apply this routine to pointers that have been created within (or exported to) the current context and have not been rendered exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}. Applying it to an unsuitable Object pointer has no effect. } } } \sstroutine{ AST\_FINDFITS }{ Find a FITS card in a FitsChan by keyword }{ \sstdescription{ This function searches for a card in a \htmlref{FitsChan}{FitsChan} by keyword. The search commences at the current card (identified by the \htmlref{Card}{Card} attribute) and ends when a card is found whose FITS keyword matches the template supplied, or when the last card in the FitsChan has been searched. If the search is successful (i.e. a card is found which matches the template), the contents of the card are returned and the Card attribute is adjusted to identify the card found or, if required, the one following it. If the search is not successful, the function returns .FALSE. and the Card attribute is set to the \texttt{"} end-of-file\texttt{"} . } \sstinvocation{ RESULT = AST\_FINDFITS( THIS, NAME, CARD, INC, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a template for the keyword to be found. In the simplest case, this should simply be the keyword name (the search is case insensitive and trailing spaces are ignored). However, this template may also contain \texttt{"} field specifiers\texttt{"} which are capable of matching a range of characters (see the \texttt{"} Keyword Templates\texttt{"} section for details). In this case, the first card with a keyword which matches the template will be found. To find the next FITS card regardless of its keyword, you should use the template \texttt{"} \%f\texttt{"} . } \sstsubsection{ CARD = CHARACTER $*$ ( 80 ) (Returned) }{ A character variable with at least 80 characters in which the FITS card which is found will be returned. If the search is not successful, a card will not be returned. } \sstsubsection{ INC = LOGICAL (Given) }{ If this value is .FALSE. (and the search is successful), the FitsChan\texttt{'} s Card attribute will be set to the index of the card that was found. If it is .TRUE., however, the Card attribute will be incremented to identify the card which follows the one found. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FINDFITS = LOGICAL }{ .TRUE. if the search was successful, otherwise .FALSE.. } } \sstexamples{ \sstexamplesubsection{ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} \%f\texttt{'} , CARD, .TRUE., STATUS ) }{ Returns the current card in a FitsChan and advances the Card attribute to identify the card that follows (the \texttt{"} \%f\texttt{"} template matches any keyword). } \sstexamplesubsection{ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} BITPIX\texttt{'} , CARD, .TRUE., STATUS ) }{ Searches a FitsChan for a FITS card with the \texttt{"} BITPIX\texttt{"} keyword and returns that card. The Card attribute is then incremented to identify the card that follows it. } \sstexamplesubsection{ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} COMMENT\texttt{'} , CARD, .FALSE., STATUS ) }{ Sets the Card attribute of a FitsChan to identify the next COMMENT card (if any) and returns that card. } \sstexamplesubsection{ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} CRVAL\%1d\texttt{'} , CARD, .TRUE., STATUS ) }{ Searches a FitsChan for the next card with a keyword of the form \texttt{"} CRVALi\texttt{"} (for example, any of the keywords \texttt{"} CRVAL1\texttt{"} , \texttt{"} CRVAL2\texttt{"} or \texttt{"} CRVAL3\texttt{"} would be matched). The card found (if any) is returned, and the Card attribute is then incremented to identify the following card (ready to search for another keyword with the same form, perhaps). } } \sstnotes{ \sstitemlist{ \sstitem The search always starts with the current card, as identified by the Card attribute. To ensure you search the entire contents of a FitsChan, you should first clear the Card attribute (using \htmlref{AST\_CLEAR}{AST\_CLEAR}). This effectively \texttt{"} rewinds\texttt{"} the FitsChan. \sstitem If a search is unsuccessful, the Card attribute is set to the \texttt{"} end-of-file\texttt{"} (i.e. to one more than the number of cards in the FitsChan). No error occurs. \sstitem A value of .FALSE. will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } \sstdiytopic{ Keyword Templates }{ The templates used to match FITS keywords are normally composed of literal characters, which must match the keyword exactly (apart from case). However, a template may also contain \texttt{"} field specifiers\texttt{"} which can match a range of possible characters. This allows you to search for keywords that contain (for example) numbers, where the digits comprising the number are not known in advance. A field specifier starts with a \texttt{"} \%\texttt{"} character. This is followed by an optional single digit (0 to 9) specifying a field width. Finally, there is a single character which specifies the type of character to be matched, as follows: \sstitemlist{ \sstitem \texttt{"} c\texttt{"} : matches all upper case letters, \sstitem \texttt{"} d\texttt{"} : matches all decimal digits, \sstitem \texttt{"} f\texttt{"} : matches all characters which are permitted within a FITS keyword (upper case letters, digits, underscores and hyphens). } If the field width is omitted, the field specifier matches one or more characters. If the field width is zero, it matches zero or more characters. Otherwise, it matches exactly the number of characters specified. In addition to this: \sstitemlist{ \sstitem The template \texttt{"} \%f\texttt{"} will match a blank FITS keyword consisting of 8 spaces (as well as matching all other keywords). \sstitem A template consisting of 8 spaces will match a blank keyword (only). } For example: \sstitemlist{ \sstitem The template \texttt{"} BitPix\texttt{"} will match the keyword \texttt{"} BITPIX\texttt{"} only. \sstitem The template \texttt{"} crpix\%1d\texttt{"} will match keywords consisting of \texttt{"} CRPIX\texttt{"} followed by one decimal digit. \sstitem The template \texttt{"} P\%c\texttt{"} will match any keyword starting with \texttt{"} P\texttt{"} and followed by one or more letters. \sstitem The template \texttt{"} E\%0f\texttt{"} will match any keyword beginning with \texttt{"} E\texttt{"} . \sstitem The template \texttt{"} \%f\texttt{"} will match any keyword at all (including a blank one). } } } \sstroutine{ AST\_FINDFRAME }{ Find a coordinate system with specified characteristics }{ \sstdescription{ This function uses a \texttt{"} template\texttt{"} \htmlref{Frame}{Frame} to search another Frame (or \htmlref{FrameSet}{FrameSet}) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it. This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example: \sstitemlist{ \sstitem Is there a wavelength scale? \sstitem Is there a 2-dimensional coordinate system? \sstitem Is there a celestial coordinate system? \sstitem Can I plot the data in ecliptic coordinates? } You can also use this function as a means of reconciling a user\texttt{'} s preference for a particular coordinate system (for example, what type of axes to draw) with what is actually possible given the coordinate information available. To perform a search, you supply a \texttt{"} target\texttt{"} Frame (or FrameSet) which represents the set of coordinate systems to be searched. If a basic Frame is given as the target, this set of coordinate systems consists of the one described by this Frame, plus all other \texttt{"} virtual\texttt{"} coordinate systems which can potentially be reached from it by applying built-in conversions (for example, any of the celestial coordinate conversions known to the AST library would constitute a \texttt{"} built-in\texttt{"} conversion). If a FrameSet is given as the target, the set of coordinate systems to be searched consists of the union of those represented by all the individual Frames within it. To select from this large set of possible coordinate systems, you supply a \texttt{"} template\texttt{"} Frame which is an instance of the type of Frame you are looking for. Effectively, you then ask the function to \texttt{"} find a coordinate system that looks like this\texttt{"} . You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its \htmlref{Current}{Current} attribute will be modified to indicate which of its Frames was used for this purpose. The result of this process is a coordinate system represented by a hybrid Frame which acquires some attributes from the template (but only if they were set) and the remainder from the target. This represents the \texttt{"} best compromise\texttt{"} between what you asked for and what was available. A \htmlref{Mapping}{Mapping} is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information. } \sstinvocation{ RESULT = AST\_FINDFRAME( TARGET, TEMPLATE, DOMAINLIST, STATUS ) } \sstarguments{ \sstsubsection{ TARGET = INTEGER (Given) }{ Pointer to the target Frame (or FrameSet). Note that if a FrameSet is supplied (and a suitable coordinate system is found), then its Current attribute will be modified to indicate which Frame was used to obtain attribute values which were not specified by the template. This Frame will, in some sense, represent the \texttt{"} closest\texttt{"} non-virtual coordinate system to the one you requested. } \sstsubsection{ TEMPLATE = INTEGER (Given) }{ Pointer to the template Frame, which should be an instance of the type of Frame you wish to find. If you wanted to find a Frame describing a celestial coordinate system, for example, then you might use a \htmlref{SkyFrame}{SkyFrame} here. See the \texttt{"} Examples\texttt{"} section for more ideas. } \sstsubsection{ DOMAINLIST = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a comma-separated list of Frame domains. This may be used to establish a priority order for the different types of coordinate system that might be found. The function will first try to find a suitable coordinate system whose \htmlref{Domain}{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 a blank string. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. } \sstsubsection{ FrameSet }{ If the target is a FrameSet, the possibility exists that several of the Frames within it might be matched by the template. Unless the choice is sufficiently restricted by the DOMAINLIST string, the sequence in which Frames are searched can then become important. In this case, the search proceeds as follows: \sstitemlist{ \sstitem Each field in the DOMAINLIST string is considered in turn. \sstitem An attempt is made to match the template to each of the target\texttt{'} s Frames in the order: (1) the current Frame, (2) the base Frame, (3) each remaining Frame in the order of being added to the target FrameSet. \sstitem Generally, the first match found is used. However, the Mapping between the target coordinate system and the resulting Frame is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one transformation is defined, the forward one is preferred. \sstitem If a match is found and the domain of the resulting Frame also matches the current DOMAINLIST field, it is accepted. Otherwise, the next DOMAINLIST field is considered and the process repeated. } If a suitable coordinate system is found, the Current attribute of the target FrameSet will be modified on exit to identify the Frame whose match with the target was eventually accepted. } } \sstreturnedvalue{ \sstsubsection{ AST\_FINDFRAME = INTEGER }{ If the search is successful, the function returns a pointer to a FrameSet which contains the Frame found and a description of how to convert to (and from) the coordinate system it represents. Otherwise, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is returned without error. If a FrameSet is returned, it will contain two Frames. Frame number 1 (its base Frame) represents the target coordinate system and will be the same as the (base Frame of the) target. Frame number 2 (its current Frame) will be a Frame representing the coordinate system which the function found. The Mapping which inter-relates these two Frames will describe how to convert between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with astTran2), then it provides a means of converting coordinates from the target coordinate system into the new coordinate system that was found (and vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the new coordinate system. } } \sstexamples{ \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, \htmlref{AST\_FRAME}{AST\_FRAME}( 3, \texttt{'} \texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Searches for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by AST\_FRAME), so no restriction has been placed on the required coordinate system, other than that it should have 3 dimensions. The first suitable Frame found will be returned as part of the RESULT FrameSet. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, \htmlref{AST\_SKYFRAME}{AST\_SKYFRAME}( \texttt{'} \texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Searches for a celestial coordinate system in the target Frame (or FrameSet). The type of celestial coordinate system is unspecified, so AST\_FINDFRAME will return the first one found as part of the RESULT FrameSet. If the target is a FrameSet, then its Current attribute will be updated to identify the Frame that was used. If no celestial coordinate system can be found, a value of AST\_\_NULL will be returned without error. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{MaxAxes}{MaxAxes}=100\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ This is like the last example, except that in the event of the target being a \htmlref{CmpFrame}{CmpFrame}, the component Frames encapsulated by the CmpFrame will be searched for a SkyFrame. If found, the returned Mapping will included a \htmlref{PermMap}{PermMap} which selects the required axes from the target CmpFrame. This is acomplished by setting the MaxAxes attribute of the template SkyFrame to a large number (larger than or equal to the number of axes in the target CmpFrame). This allows the SkyFrame to be used as a match for Frames containing from 2 to 100 axes. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{System}{System}=FK5\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Searches for an equatorial (FK5) coordinate system in the target. The \htmlref{Equinox}{Equinox} value for the coordinate system has not been specified, so will be obtained from the target. If the target is a FrameSet, its Current attribute will be updated to indicate which SkyFrame was used to obtain this value. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 2, \texttt{'} \texttt{'} , STATUS ), \texttt{'} SKY,PIXEL,\texttt{'} , STATUS ) }{ Searches for a 2-dimensional coordinate system in the target. Initially, a search is made for a suitable coordinate system whose Domain attribute has the value \texttt{"} SKY\texttt{"} . If this search fails, a search is then made for one with the domain \texttt{"} PIXEL\texttt{"} . If this also fails, then any 2-dimensional coordinate system is returned as part of the RESULT FrameSet. Only if no 2-dimensional coordinate systems can be reached by applying built-in conversions to any of the Frames in the target will a value of AST\_\_NULL be returned. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} Domain=WAVELENGTH\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Searches for any 1-dimensional coordinate system in the target which has the domain \texttt{"} WAVELENGTH\texttt{"} . } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} \texttt{'} , STATUS ), \texttt{'} WAVELENGTH\texttt{'} , STATUS ) }{ This example has exactly the same effect as that above. It illustrates the equivalence of the template\texttt{'} s Domain attribute and the fields in the DOMAINLIST string. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} MaxAxes=3\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ This is a more advanced example which will search for any coordinate system in the target having 1, 2 or 3 dimensions. The Frame returned (as part of the RESULT FrameSet) will always be 1-dimensional, but will be related to the coordinate system that was found by a suitable Mapping (e.g. a PermMap) which simply extracts the first axis. If we had wanted a Frame representing the actual (1, 2 or 3-dimensional) coordinate system found, we could set the \htmlref{PreserveAxes}{PreserveAxes} attribute to a non-zero value in the template. } \sstexamplesubsection{ RESULT = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{Permute}{Permute}=0\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS ) }{ Searches for any celestial coordinate system in the target, but only finds one if its axes are in the conventional (longitude,latitude) order and have not been permuted (e.g. with \htmlref{AST\_PERMAXES}{AST\_PERMAXES}). } } \sstnotes{ \sstitemlist{ \sstitem The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the \htmlref{AlignSystem}{AlignSystem} attribute of the TEMPLATE Frame. See the description of the AlignSystem attribute for further details. \sstitem Beware of setting the Domain attribute of the template and then using a DOMAINLIST string which does not include the template\texttt{'} s domain (or a blank field). If you do so, no coordinate system will be found. \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ More on Using Templates }{ A Frame (describing a coordinate system) will be found by this function if (a) it is \texttt{"} matched\texttt{"} by the template you supply, and (b) the value of its Domain attribute appears in the DOMAINLIST string (except that a blank field in this string permits any domain). A successful match by the template depends on a number of criteria, as outlined below: \sstitemlist{ \sstitem In general, a template will only match another Frame which belongs to the same class as the template, or to a derived (more specialised) class. For example, a SkyFrame template will match any other SkyFrame, but will not match a basic Frame. Conversely, a basic Frame template will match any class of Frame. \sstitem The exception to this is that a Frame of any class can be used to match a CmpFrame, if that CmpFrame contains a Frame of the same class as the template. Note however, the MaxAxes and \htmlref{MinAxes}{MinAxes} attributes of the template must be set to suitable values to allow it to match the CmpFrame. That is, the MinAxes attribute must be less than or equal to the number of axes in the target, and the MaxAxes attribute must be greater than or equal to the number of axes in the target. \sstitem If using a CmpFrame as a template frame, the MinAxes and MaxAxes for the template are determined by the MinAxes and MaxAxes values of the component Frames within the template. So if you want a template CmpFrame to be able to match Frames with different numbers of axes, then you must set the MaxAxes and/or MinAxes attributes in the component template Frames, before combining them together into the template CmpFrame. \sstitem If a template has a value set for any of its main attributes, then it will only match Frames which have an identical value for that attribute (or which can be transformed, using a built-in conversion, so that they have the required value for that attribute). If any attribute in the template is un-set, however, then Frames are matched regardless of the value they may have for that attribute. You may therefore make a template more or less specific by choosing the attributes for which you set values. This requirement does not apply to \texttt{'} descriptive\texttt{'} attributes such as titles, labels, symbols, etc. \sstitem An important application of this principle involves the Domain attribute. Setting the Domain attribute of the template has the effect of restricting the search to a particular type of Frame (with the domain you specify). Conversely, if the Domain attribute is not set in the template, then the domain of the Frame found is not relevant, so all Frames are searched. Note that the DOMAINLIST string provides an alternative way of restricting the search in the same manner, but is a more convenient interface if you wish to search automatically for another domain if the first search fails. \sstitem Normally, a template will only match a Frame which has the same number of axes as itself. However, for some classes of template, this default behaviour may be changed by means of the MinAxes, MaxAxes and \htmlref{MatchEnd}{MatchEnd} attributes. In addition, the behaviour of a template may be influenced by its Permute and PreserveAxes attributes, which control whether it matches Frames whose axes have been permuted, and whether this permutation is retained in the Frame which is returned (as opposed to returning the axes in the order specified in the template, which is the default behaviour). You should consult the descriptions of these attributes for details of this more advanced use of templates. } } } \sstroutine{ AST\_FITSCHAN }{ Create a FitsChan }{ \sstdescription{ This function creates a new \htmlref{FitsChan}{FitsChan} and optionally initialises its attributes. A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O operations involving the use of FITS (Flexible Image Transport \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description. While a FitsChan is active, it represents a buffer which may contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} card, to which subsequent operations apply. Searches based on keyword may be performed (using \htmlref{AST\_FINDFITS}{AST\_FINDFITS}), new cards may be inserted (\htmlref{AST\_PUTFITS}{AST\_PUTFITS}, \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}, \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}) and existing ones may be deleted (\htmlref{AST\_DELFITS}{AST\_DELFITS}) or changed (AST\_SETFITS$<$X$>$). When you create a FitsChan, you have the option of specifying \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using AST\_PUTFITS, AST\_PUTCARDS, AST\_WRITE or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from which headers should be read). When the FitsChan is deleted, any remaining header cards in the FitsChan can be saved in either of two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the name of a text file to which header cards should be written), or 2) by providing a sink function (used to to deliver header cards to an external data store). If you do not provide a sink function or a value for SinkFile, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using AST\_FINDFITS or \htmlref{AST\_READ}{AST\_READ}). Coordinate system information may be described using FITS header cards using several different conventions, termed \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers). The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings. The detailed behaviour of AST\_READ and AST\_WRITE, when used with a FitsChan, depends on the encoding in use. In general, however, all use of AST\_READ is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS} routine). If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using AST\_WRITE will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence. } \sstinvocation{ RESULT = AST\_FITSCHAN( SOURCE, SINK, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ SOURCE = FUNCTION (Given) }{ A source routine, which is a function taking two arguments: a character argument of length 80 to contain a FITS card, and an integer error status argument. It should return an integer value. This function will be used by the FitsChan to obtain input FITS header cards. On each invocation, it should read the next input card from some external source (such as a FITS file), and return the contents of the card via its character argument. It should return a function result of one unless there are no more cards to be read, in which case it should return zero. If an error occurs, it should set its error status argument to an error value before returning. If the null routine AST\_NULL is supplied as the SOURCE value, the FitsChan will remain empty until cards are explicitly stored in it (e.g. using AST\_PUTCARDS, AST\_PUTFITS or via the SourceFile attribute). } \sstsubsection{ SINK = SUBROUTINE (Given) }{ A sink routine, which is a subroutine which takes two arguments: a character argument of length 80 to contain a FITS card, and an integer error status argument. If no value has been set for the SinkFile attribute, this routine will be used by the FitsChan to deliver any FITS header cards it contains when it is finally deleted. On each invocation, it should deliver the contents of the character string passed to it as a FITS header card to some external data store (such as a FITS file). If an error occurs, it should set its error status argument to an error value before returning. If the null routine AST\_NULL is supplied as the SINK value, and no value has been set for the SinkFile attribute, the contents of the FitsChan will be lost when it is deleted. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsChan. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. Note, the FITSCHAN\_OPTIONS environment variable may be used to specify default options for all newly created FitsChans. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FITSCHAN = INTEGER }{ A pointer to the new FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST\_FITSCHAN. However, this is not generally necessary for the null routine AST\_NULL (so long as the AST\_PAR include file has been used). \sstitem No FITS \texttt{"} END\texttt{"} card will be written via the sink routine. You should add this card yourself after the FitsChan has been deleted. \sstitem 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. \sstitem Note that the null routine AST\_NULL (one underscore) is different to AST\_\_NULL (two underscores), which is the null Object pointer. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_FITSTABLE }{ Create a FitsTable }{ \sstdescription{ This function creates a new \htmlref{FitsTable}{FitsTable} and optionally initialises its attributes. The FitsTable class is a representation of a FITS binary table. It inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the binary data of the main table, and a \htmlref{FitsChan}{FitsChan} is used to hold the FITS header. Note, there is no provision for binary data following the main table (such data is referred to as a \texttt{"} heap\texttt{"} in the FITS standard). Note - it is not recommended to use the FitsTable class to store very large tables. } \sstinvocation{ RESULT = AST\_FITSTABLE( HEADER, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ HEADER = INTEGER (Given) }{ Pointer to an optional FitsChan containing headers to be stored in the FitsTable. AST\_\_NULL may be supplied if the new FitsTable is to be left empty. If supplied, and if the headers describe columns of a FITS binary table, then equivalent (empty) columns are added to the FitsTable. Each column has the same index in the FitsTable that it has in the supplied header. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsTable. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FITSTABLE = INTEGER }{ A pointer to the new FitsTable. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_FLUXFRAME }{ Create a FluxFrame }{ \sstdescription{ This function creates a new \htmlref{FluxFrame}{FluxFrame} and optionally initialises its attributes. A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various systems used to represent the signal level in an observation. The particular coordinate system to be used is specified by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by other attributes such as the units, etc (see the description of the System attribute for details). All flux values are assumed to be measured at the same frequency or wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is more appropriate for use with images rather than spectra. } \sstinvocation{ RESULT = AST\_FLUXFRAME( SPECVAL, SPECFRM, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ SPECVAL = DOUBLE PRECISION (Given) }{ The spectral value to which the flux values refer, given in the spectral coordinate system specified by SPECFRM. The value supplied for the SPECVAL parameter becomes the default value for the SpecVal attribute. A value of AST\_\_BAD may be supplied if the spectral position is unknown, but this may result in it not being possible for the \htmlref{AST\_CONVERT}{AST\_CONVERT} function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and some other FluxFrame. } \sstsubsection{ SPECFRM = INTEGER (Given) }{ A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system in which the SPECVAL parameter is given. A deep copy of this object is taken, so any subsequent changes to the SpecFrame using the supplied pointer will have no effect on the new FluxFrame. AST\_\_NULL can be supplied if AST\_\_BAD is supplied for SPECVAL. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FluxFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FLUXFRAME = INTEGER }{ A pointer to the new FluxFrame. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two FluxFrames is requested (as when supplying FluxFrames AST\_CONVERT), account will be taken of the nature of the flux coordinate systems they represent, together with any qualifying attribute values, including the \htmlref{AlignSystem}{AlignSystem} attribute. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_FORMAT }{ Format a coordinate value for a Frame axis }{ \sstdescription{ This function returns a character string containing the formatted (character) version of a coordinate value for a \htmlref{Frame}{Frame} axis. The formatting applied is determined by the Frame\texttt{'} s attributes and, in particular, by any Format attribute string that has been set for the axis. A suitable default format (based on the Digits attribute value) will be applied if necessary. } \sstinvocation{ RESULT = AST\_FORMAT( THIS, AXIS, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (given) }{ Pointer to the Frame. } \sstsubsection{ AXIS = INTEGER (Given) }{ The number of the Frame axis for which formatting is to be performed (axis numbering starts at 1 for the first axis). } \sstsubsection{ VALUE = DOUBLE PRECISION (Given) }{ The coordinate value to be formatted. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FORMAT = CHARACTER $*$ ( AST\_\_SZCHR ) }{ The formatted value. } } \sstnotes{ \sstitemlist{ \sstitem A formatted value may be converted back into a numerical (double precision) value using \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}. \sstitem A blank string will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_FRAME }{ Create a Frame }{ \sstdescription{ This function creates a new \htmlref{Frame}{Frame} and optionally initialises its attributes. A Frame is used to represent a coordinate system. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a \htmlref{Title}{Title} (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two. Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame. Frames may also contain knowledge of how to transform to and from related coordinate systems. } \sstinvocation{ RESULT = AST\_FRAME( NAXES, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NAXES = INTEGER (Given) }{ The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes). } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Frame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FRAME = INTEGER }{ A pointer to the new Frame. } } \sstexamples{ \sstexamplesubsection{ FRAME = AST\_FRAME( 2, \texttt{'} Title=Energy Spectrum\texttt{'} , STATUS ); }{ Creates a new 2-dimensional Frame and initialises its Title attribute to the string \texttt{"} Energy Spectrum\texttt{"} . } \sstexamplesubsection{ FRAME = AST\_FRAME( 2, \texttt{'} Label(1)=Energy, Label(2)=Response\texttt{'} , STATUS ); }{ Creates a new 2-dimensional Frame and initialises its axis Label attributes to suitable string values. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_FRAMESET }{ Create a FrameSet }{ \sstdescription{ This function creates a new \htmlref{FrameSet}{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 \htmlref{Mapping}{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 \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} 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\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{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 \texttt{"} native\texttt{"} coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the \texttt{"} apparent\texttt{"} 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 \htmlref{Title}{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 \texttt{"} native\texttt{"} coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see \htmlref{AST\_INVERT}{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 \htmlref{Region}{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. } \sstinvocation{ RESULT = AST\_FRAMESET( FRAME, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ 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 \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} routine.) } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FrameSet. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_FRAMESET }{ A pointer to the new FrameSet. } } \sstnotes{ \sstitemlist{ \sstitem If a pointer to an existing FrameSet is given for the FRAME 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 similar to making a copy of a FrameSet (see \htmlref{AST\_COPY}{AST\_COPY}), except that the Frames and Mappings contained in the original are not themselves copied, but are shared by both FrameSets. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GENCURVE }{ Draw a generalized curve }{ \sstdescription{ This routine draws a general user-defined curve defined by the supplied \htmlref{Mapping}{Mapping}. Note that the curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the Mapping involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{AST\_CLIP}{AST\_CLIP}. If you need to draw simple straight lines (geodesics), \htmlref{AST\_CURVE}{AST\_CURVE} or \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} will usually be easier to use and faster. } \sstinvocation{ CALL AST\_GENCURVE( THIS, MAP ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ MAP = INTEGER (Given) }{ Pointer to a Mapping. This Mapping should have 1 input coordinate representing offset along the required curve, normalized so that the start of the curve is at offset 0.0, and the end of the curve is at offset 1.0. Note, this offset does not need to be linearly related to distance along the curve. The number of output coordinates should equal the number of axes in the current \htmlref{Frame}{Frame} of the Plot. The Mapping should map a specified offset along the curve, into the corresponding coordinates in the current Frame of the Plot. The inverse transformation need not be defined. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_GET$<$X$>$ }{ Get an attribute value for an Object }{ \sstdescription{ This is a family of functions which return a specified attribute value for an \htmlref{Object}{Object} using one of several different data types. The type is selected by replacing $<$X$>$ in the function name by C, D, I, L or R, to obtain a result in Character, Double precision, Integer, Logical or Real format, respectively. If possible, the attribute value is converted to the type you request. If conversion is not possible, an error will result. } \sstinvocation{ RESULT = AST\_GET$<$X$>$( THIS, ATTRIB, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ ATTRIB = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the name of the attribute whose value is required. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ These functions apply to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_GET$<$X$>$ = $<$X$>$type }{ The attribute value, in the data type corresponding to $<$X$>$. } } \sstexamples{ \sstexamplesubsection{ WRITE( $*$, \texttt{'} (\texttt{'} \texttt{'} \htmlref{RefCount}{RefCount} = \texttt{'} \texttt{'} , A10 )\texttt{'} ) AST\_GETC( Z, \texttt{'} RefCount\texttt{'} , STATUS ) }{ Prints the RefCount attribute value for Object Z as a character string. } \sstexamplesubsection{ NAXES = AST\_GETI( FRAME, \texttt{'} \htmlref{Naxes}{Naxes}\texttt{'} , STATUS ) }{ Obtains the value of the Naxes attribute for Object FRAME as an integer. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem An appropriate \texttt{"} null\texttt{"} value will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. This null value is zero for numeric values, .FALSE. for logical values, and blank for character values. \sstitem Numerical attribute values of zero translate to logical value .FALSE. and all other numerical values translate to .TRUE.. } } } \sstroutine{ AST\_GETACTIVEUNIT }{ Determines how the Unit attribute will be used }{ \sstdescription{ This routine returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See the description of the \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine for a description of the ActiveUnit flag. } \sstinvocation{ RESULT = AST\_GETACTIVEUNIT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETACTIVEUNIT = LOGICAL }{ The current value of the ActiveUnit flag. } } \sstnotes{ \sstitemlist{ \sstitem A value of .FALSE. will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETCOLUMNDATA }{ Retrieve all the data values stored in a column }{ \sstdescription{ This routine copies all data values from a named column into a supplied buffer } \sstinvocation{ CALL AST\_GETCOLUMNDATA( THIS, COLUMN, RNULL, DNULL, MXSIZE, COLDATA, NELEM, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{FitsTable}{FitsTable}. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ RNULL = REAL (Given) }{ The value to return in COLDATA for any cells for which no value has been stored in the FitsTable. Ignored if the column\texttt{'} s data type is not AST\_\_FLOATTYPE. Supplying AST\_\_NANR will cause a single precision IEEE NaN value to be used. } \sstsubsection{ DNULL = REAL (Given) }{ The value to return in COLDATA for any cells for which no value has been stored in the FitsTable. Ignored if the column\texttt{'} s data type is not AST\_\_DOUBLETYPE. Supplying AST\_\_NAN will cause a double precision IEEE NaN value to be used. } \sstsubsection{ MXSIZE = INTEGER (Given) }{ The size of the COLDATA array, in bytes. The amount of memory needed to hold the data from a column may be determined using \htmlref{AST\_COLUMNSIZE}{AST\_COLUMNSIZE}. If the supplied array is too small to hold all the column data, trailing column values will be omitted from the returned array, but no error will be reported. } \sstsubsection{ COLDATA( $*$ ) = BYTE (Given) }{ An area of memory in which to return the data values currently stored in the column. The values are stored in row order. If the column holds non-scalar values, the elements of each value are stored in \texttt{"} Fortran\texttt{"} order. No data type conversion is performed - the data type of each returned value is the data type associated with the column when the column was added to the table. If the column holds strings, the returned strings will be null terminated. Any excess room at the end of the array will be left unchanged. } \sstsubsection{ NELEM = INTEGER (Return) }{ The number of elements returned in the COLDATA array. This is the product of the number of rows returned and the number of elements in each column value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The RNULL and DNULL arguments specify the value to be returned for any empty cells within columns holding floating point values. For columns holding integer values, the value returned for empty cells is the value returned by the \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL} functiom. For columns holding string values, the ASCII NULL character is returned for empty cells. } } } \sstroutine{ AST\_GETFITS$<$X$>$ }{ Get a named keyword value from a FitsChan }{ \sstdescription{ This is a family of functions which gets a value for a named keyword, or the value of the current card, from a \htmlref{FitsChan}{FitsChan} using one of several different data types. The data type of the returned value is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS data types: \sstitemlist{ \sstitem CF - Complex floating point values. \sstitem CI - Complex integer values. \sstitem F - Floating point values. \sstitem I - Integer values. \sstitem L - Logical (i.e. boolean) values. \sstitem S - String values. \sstitem CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but are encoded without an equals sign. } The data type of the \texttt{"} value\texttt{"} argument depends on $<$X$>$ as follows: \sstitemlist{ \sstitem CF - DOUBLE PRECISION(2) (a 2 element array to hold the real and imaginary parts of the complex value). \sstitem CI - INTEGER(2) (a 2 element array to hold the real and imaginary parts of the complex value). \sstitem F - DOUBLE PRECISION. \sstitem I - INTEGER \sstitem L - LOGICAL \sstitem S - CHARACTER \sstitem CN - CHARACTER } } \sstinvocation{ RESULT = AST\_GETFITS$<$X$>$( THIS, NAME, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. If a single dot \texttt{'} .\texttt{'} is supplied, the value of the current card is returned. } \sstsubsection{ VALUE = $<$X$>$type (Returned) }{ A buffer to receive the keyword value. The data type depends on $<$X$>$ as described above. The conents of the buffer on entry are left unchanged if the keyword is not found. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETFITS$<$X$>$ = LOGICAL }{ .FALSE. is returned if the keyword was not found in the FitsChan (no error is reported). Otherwise, a value of .TRUE. is returned. } } \sstnotes{ \sstitemlist{ \sstitem If a name is supplied, the card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards. \sstitem If the requested card is found, it becomes the current card, otherwise the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem If the stored keyword value is not of the requested type, it is converted into the requested type. \sstitem If the keyword is found in the FitsChan, but has no associated value, an error is reported. If necessary, the \htmlref{AST\_TESTFITS}{AST\_TESTFITS} function can be used to determine if the keyword has a defined value in the FitsChan prior to calling this function. \sstitem An error will be reported if the keyword name does not conform to FITS requirements. \sstitem .FALSE. is returned as the function value if an error has already occurred, or if this function should fail for any reason. \sstitem The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the string returned by AST\_GETFITSS if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings. } } } \sstroutine{ AST\_GETFRAME }{ Obtain a pointer to a specified Frame in a FrameSet }{ \sstdescription{ This function returns a pointer to a specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet}. } \sstinvocation{ RESULT = AST\_GETFRAME( THIS, IFRAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 \htmlref{Nframe}{Nframe} attribute). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETFRAME = INTEGER }{ A pointer to the requested Frame. } } \sstnotes{ \sstitemlist{ \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the IFRAME argument to specify the base Frame or the current Frame respectively. \sstitem This function increments the \htmlref{RefCount}{RefCount} attribute of the selected Frame by one. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETGRFCONTEXT }{ Return the KeyMap that describes a Plot\texttt{'} s graphics context }{ \sstdescription{ This routine returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing routines registered using \htmlref{AST\_GRFSET}{AST\_GRFSET}. This KeyMap can be used by an application to pass information to the drawing routines about the context in which they are being called. The contents of the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself. } \sstinvocation{ RESULT = AST\_GETGRFCONTEXT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETGRFCONTEXT = INTEGER }{ A pointer to the graphics context KeyMap. The returned pointer should be annulled when it is no longer needed. } } } \sstroutine{ AST\_GETLINE }{ Obtain text to be written by a Channel sink routine }{ \sstdescription{ This routine should only be used when implementing a routine which will be passed as the SINK argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL}. It should be used to obtain (from the AST library) each line of text which is to be written to the external data sink. One such line should be obtained in this way for each invocation of the sink routine. } \sstinvocation{ CALL AST\_GETLINE( LINE, L, STATUS ) } \sstarguments{ \sstsubsection{ LINE = CHARACTER $*$ ( $*$ ) (Returned) }{ The line of text to be written. Depending on the length of character variable supplied, the returned text may be truncated if necessary. Note, however, that it will not be padded with blanks in order to fill this variable. } \sstsubsection{ L = INTEGER (Returned) }{ The number of characters returned, which may be zero. Note that characters beyond the L\texttt{'} th character in the LINE variable are not modified and may therefore contain junk. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This routine is only available in the Fortran interface to the AST library. } } } \sstroutine{ AST\_GETMAPPING }{ Obtain a Mapping that converts between two Frames in a FrameSet }{ \sstdescription{ This function returns a pointer to a \htmlref{Mapping}{Mapping} that will convert coordinates between the coordinate systems represented by two Frames in a \htmlref{FrameSet}{FrameSet}. } \sstinvocation{ RESULT = AST\_GETMAPPING( THIS, IFRAME1, IFRAME2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ IFRAME1 = INTEGER (Given) }{ The index of the first \htmlref{Frame}{Frame} in the FrameSet. This Frame describes the coordinate system for the \texttt{"} input\texttt{"} end of the Mapping. } \sstsubsection{ IFRAME2 = INTEGER (Given) }{ The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the \texttt{"} output\texttt{"} end of the Mapping. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ 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. } } \sstnotes{ \sstitemlist{ \sstitem 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). \sstitem 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 \htmlref{Nframe}{Nframe} attribute). A value of AST\_\_BASE or AST\_\_CURRENT may also be given to identify the FrameSet\texttt{'} s base Frame or current Frame respectively. It is permissible for both these arguments to have the same value, in which case a unit Mapping (\htmlref{UnitMap}{UnitMap}) is returned. \sstitem 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 \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes of the returned Mapping should be inspected to determine if the required transformation is available. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETREFPOS }{ Return the reference position in a specified celestial coordinate system }{ \sstdescription{ This routine returns the reference position (specified by attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) converted to the celestial coordinate system represented by a supplied \htmlref{SkyFrame}{SkyFrame}. The celestial longitude and latitude values are returned in radians. } \sstinvocation{ CALL AST\_GETREFPOS( THIS, FRM, LON, LAT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{SpecFrame}{SpecFrame}. } \sstsubsection{ FRM = INTEGER (Given) }{ Pointer to the SkyFrame which defines the required celestial coordinate system. If AST\_\_NULL is supplied, then the longitude and latitude values are returned as FK5 J2000 RA and Dec values. } \sstsubsection{ LON = DOUBLE PRECISION (Returned) }{ The longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ LAT = DOUBLE PRECISION (Returned) }{ The latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Values of AST\_\_BAD will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETREGIONBOUNDS }{ Returns the bounding box of Region }{ \sstdescription{ This routine returns the upper and lower limits of a box which just encompasses the supplied \htmlref{Region}{Region}. The limits are returned as axis values within the \htmlref{Frame}{Frame} represented by the Region. The value of the \htmlref{Negated}{Negated} attribute is ignored (i.e. it is assumed that the Region has not been negated). } \sstinvocation{ CALL AST\_GETREGIONBOUNDS( THIS, LBND, UBND, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ LBND() = DOUBLE PRECISION (Returned) }{ An array in which to return the lower axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no lower limit, the returned value will be the largest possible negative value. } \sstsubsection{ UBND() = DOUBLE PRECISION (Returned) }{ An array in which to return the upper axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no upper limit, the returned value will be the largest possible positive value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The value of the Negated attribute is ignored (i.e. it is assumed that the Region has not been negated). \sstitem If an axis has no extent on an axis then the lower limit will be returned larger than the upper limit. Note, this is different to an axis which has a constant value (in which case both lower and upper limit will be returned set to the constant value). \sstitem If the bounds on an axis cannot be determined, AST\_\_BAD is returned for both upper and lower bounds } } } \sstroutine{ AST\_GETREGIONFRAME }{ Obtain a pointer to the encapsulated Frame within a Region }{ \sstdescription{ This function returns a pointer to the \htmlref{Frame}{Frame} represented by a \htmlref{Region}{Region}. } \sstinvocation{ RESULT = AST\_GETREGIONFRAME( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETREGIONFRAME = INTEGER }{ A pointer to a deep copy of the Frame represented by the Region. Using this pointer to modify the Frame will have no effect on the Region. To modify the Region, use the Region pointer directly. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETREGIONFRAMESET }{ Obtain a pointer to the encapsulated FrameSet within a Region }{ \sstdescription{ This function returns a pointer to the \htmlref{FrameSet}{FrameSet} encapsulated by a \htmlref{Region}{Region}. The base \htmlref{Frame}{Frame} is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by \htmlref{AST\_GETREGIONFRAME}{AST\_GETREGIONFRAME}). } \sstinvocation{ RESULT = AST\_GETREGIONFRAMESET( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETREGIONFRAMESET = INTEGER }{ A pointer to a deep copy of the FrameSet represented by the Region. Using this pointer to modify the FrameSet will have no effect on the Region. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETREGIONMESH }{ Return a mesh of points covering the surface or volume of a Region }{ \sstdescription{ This routine returns the axis values at a mesh of points either covering the surface (i.e. boundary) of the supplied \htmlref{Region}{Region}, or filling the interior (i.e. volume) of the Region. The number of points in the mesh is approximately equal to the \htmlref{MeshSize}{MeshSize} attribute. } \sstinvocation{ CALL AST\_GETREGIONMESH( THIS, SURFACE, MAXPOINT, MAXCOORD, NPOINT, POINTS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ SURFACE = LOGICAL (Given) }{ If .TRUE., the returned points will cover the surface or the Region. Otherwise, they will fill the interior of the Region. } \sstsubsection{ MAXPOINT = INTEGER (Given) }{ If zero, the number of points in the mesh is returned in NPOINT, but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the first dimension of the POINTS array. An error is reported if the number of points in the mesh exceeds this number. } \sstsubsection{ MAXCOORD = INTEGER (Given) }{ The length of the second dimension of the POINTS array. An error is reported if the number of axes in the supplied Region exceeds this number. } \sstsubsection{ NPOINT = INTEGER (Returned) }{ The number of points in the returned mesh. } \sstsubsection{ POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates values at the mesh positions. These are stored such that the value of coordinate number COORD for point number POINT is found in element POINTS(POINT,COORD). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem An error is reported if the Region is unbounded. \sstitem If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (\htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc). } } } \sstroutine{ AST\_GETREGIONPOINTS }{ Returns the positions that define the given Region }{ \sstdescription{ This routine returns the axis values at the points that define the supplied \htmlref{Region}{Region}. The particular meaning of these points will depend on the type of class supplied, as listed below under \texttt{"} Applicability:\texttt{"} . } \sstinvocation{ CALL AST\_GETREGIONPOINTS( THIS, MAXPOINT, MAXCOORD, NPOINT, POINTS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ MAXPOINT = INTEGER (Given) }{ If zero, the number of points needed to define the Region is returned in NPOINT, but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the first dimension of the POINTS array. An error is reported if the number of points needed to define the Region exceeds this number. } \sstsubsection{ MAXCOORD = INTEGER (Given) }{ The length of the second dimension of the POINTS array. An error is reported if the number of axes in the supplied Region exceeds this number. } \sstsubsection{ NPOINT = INTEGER (Returned) }{ The number of points defining the Region. } \sstsubsection{ POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned) }{ An array in which to return the coordinates values at the positions that define the Region. These are stored such that the value of coordinate number COORD for point number POINT is found in element POINTS(POINT,COORD). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{Box}{Box} }{ The first returned position is the Box centre, and the second is a Box corner. } \sstsubsection{ \htmlref{Circle}{Circle} }{ The first returned position is the Circle centre, and the second is a point on the circumference. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ Returns a value of zero for NPOINT and leaves the supplied array contents unchanged. To find the points defining a CmpRegion, use this method on the component Regions, which can be accessed by invoking \htmlref{AST\_DECOMPOSE}{AST\_DECOMPOSE} on the CmpRegion. } \sstsubsection{ \htmlref{Ellipse}{Ellipse} }{ The first returned position is the Ellipse centre. The second is the end of one of the axes of the ellipse. The third is some other point on the circumference of the ellipse, distinct from the second point. } \sstsubsection{ \htmlref{Interval}{Interval} }{ The first point corresponds to the lower bounds position, and the second point corresponds to the upper bounds position. These are reversed to indicate an extcluded interval rather than an included interval. See the Interval constructor for more information. } \sstsubsection{ \htmlref{NullRegion}{NullRegion} }{ Returns a value of zero for NPOINT and leaves the supplied array contents unchanged. } \sstsubsection{ \htmlref{PointList}{PointList} }{ The positions returned are those that were supplied when the PointList was constructed. } \sstsubsection{ \htmlref{Polygon}{Polygon} }{ The positions returned are the vertex positions that were supplied when the Polygon was constructed. } \sstsubsection{ \htmlref{Prism}{Prism} }{ Returns a value of zero for NPOINT and leaves the supplied array contents unchanged. To find the points defining a Prism, use this method on the component Regions, which can be accessed by invoking AST\_DECOMPOSE on the CmpRegion. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (Circle, Box, etc). } } } \sstroutine{ AST\_GETSTCCOORD }{ Return information about an AstroCoords element stored in an Stc }{ \sstdescription{ When any sub-class of \htmlref{Stc}{Stc} is created, the constructor function allows one or more AstroCoords elements to be stored within the Stc. This function allows any one of these AstroCoords elements to be retrieved. The format of the returned information is the same as that used to pass the original information to the Stc constructor. That is, the information is returned in a \htmlref{KeyMap}{KeyMap} structure containing elements with one or more of the keys given by symbolic constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE and AST\_\_STCPIXSZ. If the coordinate system represented by the Stc has been changed since it was created (for instance, by changing its \htmlref{System}{System} attribute), then the sizes and positions in the returned KeyMap will reflect the change in coordinate system. } \sstinvocation{ RESULT = AST\_GETSTCCOORD( THIS, ICOORD, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Stc. } \sstsubsection{ ICOORD = INTEGER (Given) }{ The index of the AstroCoords element required. The first has index one. The number of AstroCoords elements in the Stc can be found using function \htmlref{AST\_GETSTCNCOORD}{AST\_GETSTCNCOORD}. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETSTCCOORD = INTEGER }{ A pointer to a new KeyMap containing the required information. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETSTCNCOORD }{ Return the number of AstroCoords elements stored in an Stc }{ \sstdescription{ This function returns the number of AstroCoords elements stored in an \htmlref{Stc}{Stc}. } \sstinvocation{ RESULT = AST\_GETSTCNCOORD( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Stc. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETSTCNCOORD = INTEGER }{ The number of AstroCoords elements stored in the Stc. } } \sstnotes{ \sstitemlist{ \sstitem Zero will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETSTCREGION }{ Obtain a copy of the encapsulated Region within a Stc }{ \sstdescription{ This function returns a pointer to a deep copy of the \htmlref{Region}{Region} supplied when the \htmlref{Stc}{Stc} was created. } \sstinvocation{ RESULT = AST\_GETSTCREGION( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Stc. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETSTCREGION = INTEGER }{ A pointer to a deep copy of the Region encapsulated within the supplied Stc. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETTABLES }{ Retrieve any FitsTables currently in a FitsChan }{ \sstdescription{ If the supplied \htmlref{FitsChan}{FitsChan} currently contains any tables, then this function returns a pointer to a \htmlref{KeyMap}{KeyMap}. Each entry in the KeyMap is a pointer to a \htmlref{FitsTable}{FitsTable} holding the data for a FITS binary table. The key used to access each entry is the FITS extension name in which the table should be stored. Tables can be present in a FitsChan as a result either of using the \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE} (or \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES}) method to store existing tables in the FitsChan, or of using the \htmlref{AST\_WRITE}{AST\_WRITE} method to write a \htmlref{FrameSet}{FrameSet} to the FitsChan. For the later case, if the FitsChan \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute is positive and the FrameSet requires a look-up table to describe one or more axes, then the \texttt{"} -TAB\texttt{"} algorithm code described in FITS-WCS paper III is used and the table values are stored in the FitsChan in the form of a FitsTable object (see the documentation for the \texttt{"} TabOK\texttt{"} attribute). } \sstinvocation{ RESULT = AST\_GETTABLES( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETTABLES = INTEGER }{ A pointer to a deep copy of the KeyMap holding the tables currently in the FitsChan, or AST\_\_NULL if the FitsChan does not contain any tables. The returned pointer should be annulled using \htmlref{AST\_ANNUL}{AST\_ANNUL} when no longer needed. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GETUNC }{ Obtain uncertainty information from a Region }{ \sstdescription{ This function returns a \htmlref{Region}{Region} which represents the uncertainty associated with positions within the supplied Region. See \htmlref{AST\_SETUNC}{AST\_SETUNC} for more information about Region uncertainties and their use. } \sstinvocation{ RESULT = AST\_GETUNC( THIS, DEF, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ DEF = LOGICAL (Given) }{ Controls what is returned if no uncertainty information has been associated explicitly with the supplied Region. If .TRUE. is supplied, then the default uncertainty Region used internally within AST is returned (see \texttt{"} Applicability\texttt{"} below). If .FALSE. is supplied, then AST\_\_NULL will be returned (without error). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default uncertainty for a CmpRegion is taken from one of the two component Regions. If the first component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. Otherwise, if the second component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. If neither of the component Regions has non-default uncertainty, then the default uncertainty for the CmpRegion is 1.0E-6 of the bounding box of the CmpRegion. } \sstsubsection{ \htmlref{Prism}{Prism} }{ The default uncertainty for a Prism is formed by combining the uncertainties from the two component Regions. If a component Region does not have a non-default uncertainty, then its default uncertainty will be used to form the default uncertainty of the parent Prism. } \sstsubsection{ Region }{ For other classes of Region, the default uncertainty is 1.0E-6 of the bounding box of the Region. If the bounding box has zero width on any axis, then the uncertainty will be 1.0E-6 of the axis value. } } \sstreturnedvalue{ \sstsubsection{ AST\_GETUNC = INTEGER }{ A pointer to a Region describing the uncertainty in the supplied Region. } } \sstnotes{ \sstitemlist{ \sstitem If uncertainty information is associated with a Region, and the coordinate system described by the Region is subsequently changed (e.g. by changing the value of its \htmlref{System}{System} attribute, or using the \htmlref{AST\_MAPREGION}{AST\_MAPREGION} function), then the uncertainty information returned by this function will be modified so that it refers to the coordinate system currently described by the supplied Region. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GRFPOP }{ Restore previously saved graphics functions used by a Plot }{ \sstdescription{ The \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH} and AST\_GRFPOP functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the \htmlref{Plot}{Plot}. The current functions should first be saved by calling AST\_GRFPUSH. New functions should then be registered using \htmlref{AST\_GRFSET}{AST\_GRFSET}. The required graphics should then be produced. Finally, AST\_GRFPOP should be called to restore the original graphics functions. } \sstinvocation{ CALL AST\_GRFPOP( THIS STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This routine returns without action if there are no snapshots to restore. No error is reported in this case. } } } \sstroutine{ AST\_GRFPUSH }{ Save the current graphics functions used by a Plot }{ \sstdescription{ This routine takes a snapshot of the graphics functions which are currently registered with the supplied \htmlref{Plot}{Plot}, and saves the snapshot on a first-in-last-out stack within the Plot. The snapshot can be restored later using function \htmlref{AST\_GRFPOP}{AST\_GRFPOP}. The AST\_GRFPUSH and AST\_GRFPOP functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the Plot. The current functions should first be saved by calling AST\_GRFPUSH. New functions should then be registered using \htmlref{AST\_GRFSET}{AST\_GRFSET}. The required graphics should then be produced. Finally, AST\_GRFPOP should be called to restore the original graphics functions. } \sstinvocation{ CALL AST\_GRFPUSH( THIS STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_GRFSET }{ Register a graphics routine for use by a Plot }{ \sstdescription{ This routine can be used to select the underlying graphics routines to be used when the supplied \htmlref{Plot}{Plot} produces graphical output. If this routine is not called prior to producing graphical output, then the underlying graphics routines selected at link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use alternative graphics routines, call this routine before the graphical output is created, specifying the graphics routines to be used. This will register the routine for future use, but the routine will not actually be used until the \htmlref{Grf}{Grf} attribute is given a non-zero value. } \sstinvocation{ CALL AST\_GRFSET( THIS, NAME, FUN, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A name indicating the graphics routine to be replaced. Various graphics routines are used by the Plot class, and any combination of them may be supplied by calling this routine once for each routine to be replaced. If any of the graphics routines are not replaced in this way, the corresponding routines in the graphics interface selected at link-time (using the ast\_link command) are used. The allowed function names are: \sstitemlist{ \sstitem Attr - Enquire or set a graphics attribute value \sstitem BBuf - Start a new graphics buffering context \sstitem Cap - Inquire a capability \sstitem EBuf - End the current graphics buffering context \sstitem Flush - Flush all pending graphics to the output device \sstitem Line - Draw a polyline (i.e. a set of connected lines) \sstitem Mark - Draw a set of markers \sstitem Qch - Return the character height in world coordinates \sstitem Scales - Get the axis scales \sstitem Text - Draw a character string \sstitem TxExt - Get the extent of a character string } The string is case insensitive. For details of the interface required for each, see the sections below. } \sstsubsection{ FUN = INTEGER FUNCTION (Given) }{ The name of the routine to be used to provide the functionality indicated by parameter NAME (the name should also appear in a Fortran EXTERNAL statement in the routine which invokes AST\_GRFSET). Once a routine has been provided, the \texttt{"} null\texttt{"} routine AST\_NULL can be supplied in a subsequent call to astGrfSet to reset the routine to the corresponding routine in the graphics interface selected at link-time. AST\_NULL is defined in the AST\_PAR include file. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstdiytopic{ Function Interfaces }{ All the functions listed below (except for \texttt{"} Cap\texttt{"} ) should return an integer value of 0 if an error occurs, and 1 otherwise. All x and y values refer to \texttt{"} graphics cordinates\texttt{"} as defined by the GRAPHBOX parameter of the \htmlref{AST\_PLOT}{AST\_PLOT} call which created the Plot. The first argument (GRFCON) for each function is an AST \htmlref{KeyMap}{KeyMap} pointer that can be used by the called function to establish the context in which it is being called. The contents of the KeyMap are determined by the calling application, which should obtain a pointer to the KeyMap using the \htmlref{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT} routine, and then store any necessary information in the KeyMap using the methods of the KeyMap class. Note, the functions listed below should never annul or delete the supplied KeyMap pointer. } \sstdiytopic{ Attr }{ The \texttt{"} Attr\texttt{"} function returns the current value of a specified graphics attribute, and optionally establishes a new value. The supplied value is converted to an integer value if necessary before use. It requires the following interface: INTEGER FUNCTION ATTR( GRFCON, ATT, VAL, OLDVAL, PRIM ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem ATT = INTEGER (Given) - An integer identifying the required attribute. The following symbolic values are defined in GRF\_PAR: GRF\_\_STYLE (Line style), GRF\_\_WIDTH (Line width), GRF\_\_SIZE (Character and marker size scale factor), GRF\_\_FONT (Character font), GRF\_\_COLOUR (Colour index). \sstitem VAL = DOUBLE PRECISION (Given) - no value is stored. \sstitem OLDVAL = DOUBLE PRECISION (Returned) - Returned holding the attribute value. \sstitem PRIM = INTEGER (Given) - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in GRF\_PAR: GRF\_\_LINE, GRF\_\_MARK, GRF\_\_TEXT. } } \sstdiytopic{ BBuf }{ The \texttt{"} BBuf\texttt{"} function should start a new graphics buffering context. A matching call to the function \texttt{"} EBuf\texttt{"} should be used to end the context. The nature of the buffering is determined by the underlying graphics system. INTEGER FUNCTION BBUF( GRFCON ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Cap }{ The \texttt{"} Cap\texttt{"} function is called to determine if the grf module has a given capability, as indicated by the \texttt{"} cap\texttt{"} argument: INTEGER FUNCTION CAP( GRFCON, CAP, VALUE ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem CAP = INTEGER (Given) The capability being inquired about. This will be one of the following constants defined in GRF\_PAR: } GRF\_\_SCALES: This function should return a non-zero value if the \texttt{"} Scales\texttt{"} function is implemented, and zero otherwise. The supplied VALUE argument should be ignored. GRF\_\_MJUST: This function should return a non-zero value if the \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions recognise \texttt{"} M\texttt{"} as a character in the justification string. If the first character of a justification string is \texttt{"} M\texttt{"} , then the text should be justified with the given reference point at the bottom of the bounding box. This is different to \texttt{"} B\texttt{"} justification, which requests that the reference point be put on the baseline of the text, since some characters hang down below the baseline. If the \texttt{"} Text\texttt{"} or \texttt{"} TxExt\texttt{"} function cannot differentiate between \texttt{"} M\texttt{"} and \texttt{"} B\texttt{"} , then this function should return zero, in which case \texttt{"} M\texttt{"} justification will never be requested by Plot. The supplied VALUE argument should be ignored. GRF\_\_ESC: This function should return a non-zero value if the \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions can recognise and interpret graphics escape sequences within the supplied string (see attribute \htmlref{Escape}{Escape}). Zero should be returned if escape sequences cannot be interpreted (in which case the Plot class will interpret them itself if needed). The supplied VALUE argument should be ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} . Otherwise, VALUE indicates whether \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} should interpret escape sequences in subsequent calls. If VALUE is non-zero then escape sequences should be interpreted by \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} . Otherwise, they should be drawn as literal text. \sstitemlist{ \sstitem VALUE = INTEGER (Given) The use of this parameter depends on the value of CAP as described above. \sstitem Returned Function Value: The value returned by the function depends on the value of CAP as described above. Zero should be returned if the supplied capability is not recognised. } } \sstdiytopic{ EBuf }{ The \texttt{"} EBuf\texttt{"} function should end the current graphics buffering context. See the description of \texttt{"} BBuf\texttt{"} above for further details. It requires the following interface: INTEGER FUNCTION EBUF( GRFCON ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Flush }{ The \texttt{"} Flush\texttt{"} function ensures that the display device is up-to-date, by flushing any pending graphics to the output device. It requires the following interface: INTEGER FUNCTION FLUSH( GRFCON ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Line }{ The \texttt{"} Line\texttt{"} function displays lines joining the given positions and requires the following interface: INTEGER FUNCTION LINE( GRFCON, N, X, Y ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem N = INTEGER (Given) - The number of positions to be joined together. \sstitem X( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} x values. \sstitem Y( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} y values. } } \sstdiytopic{ Mark }{ The \texttt{"} Mark\texttt{"} function displays markers at the given positions. It requires the following interface: INTEGER FUNCTION MARK( GRFCON, N, X, Y, TYPE ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem N = INTEGER (Given) - The number of positions to be marked. \sstitem X( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} x values. \sstitem Y( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} y values. \sstitem TYPE = INTEGER (Given) - An integer which can be used to indicate the type of marker symbol required. } } \sstdiytopic{ Qch }{ The \texttt{"} Qch\texttt{"} function returns the heights of characters drawn vertically and horizontally in graphics coordinates. It requires the following interface: INTEGER FUNCTION QCH( GRFCON, CHV, CHH ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem CHV = REAL (Returned) The height of characters drawn with a vertical baseline. This will be an increment in the X axis. \sstitem CHH = REAL (Returned) The height of characters drawn with a horizontal baseline. This will be an increment in the Y axis. } } \sstdiytopic{ Scales }{ The \texttt{"} Scales\texttt{"} function returns two values (one for each axis) which scale increments on the corresponding axis into a \texttt{"} normal\texttt{"} coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, and 3) Y values increase from bottom to top. It requires the following interface: INTEGER FUNCTION SCALES( GRFCON, ALPHA, BETA ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem ALPHA = REAL (Returned) The scale for the X axis (i.e. Xnorm = alpha$*$Xworld). \sstitem BETA = REAL (Returned) The scale for the Y axis (i.e. Ynorm = beta$*$Yworld). } } \sstdiytopic{ Text }{ The \texttt{"} Text\texttt{"} function displays a character string at a given position using a specified justification and up-vector. It requires the following interface: INTEGER FUNCTION TEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem TEXT = CHARACTER $*$ ( $*$ ) (Given) - The string to be displayed. \sstitem X = REAL (Given) - The reference x coordinate. \sstitem Y = REAL (Given) - The reference y coordinate. \sstitem JUST = CHARACTER $*$ ( $*$ ) (Given ) - A string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be \texttt{'} T\texttt{'} for \texttt{"} top\texttt{"} , \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} B\texttt{'} for \texttt{"} bottom\texttt{"} , and specifies the vertical location of the reference position. Note, \texttt{"} bottom\texttt{"} corresponds to the base-line of normal text. Some characters (eg \texttt{"} y\texttt{"} , \texttt{"} g\texttt{"} , \texttt{"} p\texttt{"} , etc) descend below the base-line. The second character may be \texttt{'} L\texttt{'} for \texttt{"} left\texttt{"} , \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} R\texttt{'} for \texttt{"} right\texttt{"} , and specifies the horizontal location of the reference position. If the string has less than 2 characters then \texttt{'} C\texttt{'} is used for the missing characters. \sstitem UPX = REAL (Given) - The x component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen. \sstitem UPX = REAL (Given) - The y component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen. } } \sstdiytopic{ TxExt }{ The \texttt{"} TxExt\texttt{"} function returns the corners of a box which would enclose the supplied character string if it were displayed using the Text function described above. The returned box includes any leading or trailing spaces. It requires the following interface: INTEGER FUNCTION TXEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY, XB, YB ) \sstitemlist{ \sstitem GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application. \sstitem TEXT = CHARACTER $*$ ( $*$ ) (Given) - The string to be displayed. \sstitem X = REAL (Given) - The reference x coordinate. \sstitem Y = REAL (Given) - The reference y coordinate. \sstitem JUST = CHARACTER $*$ ( $*$ ) (Given ) - A string which specifies the location within the text string which is to be placed at the reference position given by x and y. See \texttt{"} Text\texttt{"} above. \sstitem UPX = REAL (Given) - The x component of the up-vector for the text. See \texttt{"} Text\texttt{"} above. \sstitem UPX = REAL (Given) - The y component of the up-vector for the text. See \texttt{"} Text\texttt{"} above. \sstitem XB( 4 ) = REAL (Returned) - Returned holding the x coordinate of each corner of the bounding box. \sstitem YB( 4 ) = REAL (Returned) - Returned holding the y coordinate of each corner of the bounding box. } } } \sstroutine{ AST\_GRID }{ Draw a set of labelled coordinate axes }{ \sstdescription{ This routine draws a complete annotated set of coordinate axes for a \htmlref{Plot}{Plot} with (optionally) a coordinate grid superimposed. Details of the axes and grid can be controlled by setting values for the various attributes defined by the Plot class (q.v.). } \sstinvocation{ CALL AST\_GRID( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied Plot is a \htmlref{Plot3D}{Plot3D}, the axes will be annotated using three 2-dimensional Plots, one for each 2D plane in the 3D current coordinate system. The plots will be \texttt{"} pasted\texttt{"} onto 3 faces of the cuboid graphics volume specified when the Plot3D was constructed. The faces to be used can be controlled by the \texttt{"} \htmlref{RootCorner}{RootCorner}\texttt{"} attribute. \sstitem An error results if either the current \htmlref{Frame}{Frame} or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the base and current Frames of the Plot is not defined in either direction (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} or \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_GRIDLINE }{ Draw a grid line (or axis) for a Plot }{ \sstdescription{ This routine draws a curve in the physical coordinate system of a \htmlref{Plot}{Plot} by varying only one of the coordinates along the length of the curve. It is intended for drawing coordinate axes, coordinate grids, and tick marks on axes (but note that these are also available via the more comprehensive \htmlref{AST\_GRID}{AST\_GRID} routine). The curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{AST\_CLIP}{AST\_CLIP}. } \sstinvocation{ CALL AST\_GRIDLINE( THIS, AXIS, START, LENGTH, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ AXIS = INTEGER (Given) }{ The index of the Plot axis whose physical coordinate value is to be varied along the length of the curve (all other coordinates will remain fixed). This value should lie in the range from 1 to the number of Plot axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ START( $*$ ) = DOUBLE PRECISION (Given) }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the start of the curve. } \sstsubsection{ LENGTH = DOUBLE PRECISION (Given) }{ The length of curve to be drawn, given as an increment along the selected physical axis. This may be positive or negative. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn if the START array contains any coordinates with the value AST\_\_BAD, nor if LENGTH has this value. \sstitem An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_GRISMMAP }{ Create a GrismMap }{ \sstdescription{ This function creates a new \htmlref{GrismMap}{GrismMap} and optionally initialises its attributes. A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III \texttt{"} Representation of spectral coordinates in FITS\texttt{"} . This describes the dispersion produced by gratings, prisms and grisms. When initially created, the forward transformation of a GrismMap transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as \texttt{"} the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length\texttt{"} . The units in which wavelength values are expected or returned is determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will also be used for the wavelength values. } \sstinvocation{ RESULT = AST\_GRISMMAP( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new GrismMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GRISMMAP = INTEGER }{ A pointer to the new GrismMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_GetTableHeader }{ Get the FITS headers from a FitsTable }{ \sstdescription{ This function returns a pointer to a \htmlref{FitsChan}{FitsChan} holding copies of the FITS headers associated with a \htmlref{FitsTable}{FitsTable}. } \sstinvocation{ RESULT = AST\_GETTABLEHEADER( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsTable. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_GetTableHeader = INTEGER }{ A pointer to a deep copy of the FitsChan stored within the FitsTable. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer should be annulled using \htmlref{AST\_ANNUL}{AST\_ANNUL} when it is no longer needed. \sstitem Changing the contents of the returned FitsChan will have no effect on the FitsTable. To modify the FitsTable, the modified FitsChan must be stored in the FitsTable using \htmlref{AST\_PUTTABLEHEADER}{AST\_PUTTABLEHEADER}. } } } \sstroutine{ AST\_HASATTRIBUTE }{ Test if an Object has a named attribute }{ \sstdescription{ This function returns a logical result to indicate whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name. } \sstinvocation{ RESULT = AST\_HASATTRIBUTE( THIS, ATTRIB, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the first Object. } \sstsubsection{ ATTRIB = INTEGER (Given) }{ The name of the attribute to be tested. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ \htmlref{AST\_SAME}{AST\_SAME} = LOGICAL }{ .TRUE. if the Object has the named attribute, otherwise .FALSE. } } \sstnotes{ \sstitemlist{ \sstitem A value of .FALSE. will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_HASCOLUMN }{ Returns a flag indicating if a column is present in a Table }{ \sstdescription{ This routine returns a flag indicating if a named column exists in a \htmlref{Table}{Table}, for instance, by having been added to to the Table using \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}. } \sstinvocation{ RESULT = AST\_HASCOLUMN( THIS, COLUMN, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the upper case name of the column. Trailing spaces are ignored. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem A value of .FALSE. is returned for if an error occurs. } } } \sstroutine{ AST\_HASPARAMETER }{ Returns a flag indicating if a named global parameter is present in a Table }{ \sstdescription{ This routine returns a flag indicating if a named parameter exists in a \htmlref{Table}{Table}, for instance, by having been added to to the Table using \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}. } \sstinvocation{ RESULT = AST\_HASPARAMETER( THIS, PARAMETER, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ PARAMETER = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the upper case name of the parameter. Trailing spaces are ignored. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem A value of .FALSE. is returned for if an error occurs. } } } \sstroutine{ AST\_IMPORT }{ Import an Object pointer to the current context }{ \sstdescription{ This routine imports an \htmlref{Object}{Object} pointer that was created in a higher or lower level context, into the current AST context. This means that the pointer will be annulled when the current context is ended (with \htmlref{AST\_END}{AST\_END}). } \sstinvocation{ CALL AST\_IMPORT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Object pointer to be imported. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } } \sstroutine{ AST\_INTERSECT }{ Find the point of intersection between two geodesic curves }{ \sstdescription{ This routine finds the coordinate values at the point of intersection between two geodesic curves. Each curve is specified by two points on the curve. It can only be used with 2-dimensional Frames. For example, in a basic \htmlref{Frame}{Frame}, it will find the point of intersection between two straight lines. But for a \htmlref{SkyFrame}{SkyFrame} it will find an intersection of two great circles. } \sstinvocation{ CALL AST\_INTERSECT( THIS, A1, A2, B1, B2, CROSS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ A1( 2 ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the first point on the first geodesic curve. } \sstsubsection{ A2( 2 ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the first geodesic curve. It should not be co-incident with the first point. } \sstsubsection{ B1( 2 ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute). This should contain the coordinates of the first point on the second geodesic curve. } \sstsubsection{ B2( 2 ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the second geodesic curve. It should not be co-incident with the first point. } \sstsubsection{ CROSS( 2 ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Frame axis in which the coordinates of the required intersection will be returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the two points defining either geodesic are co-incident, or if the two curves do not intersect. \sstitem The geodesic curve used by this routine is the path of shortest distance between two points, as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function. \sstitem An error will be reported if the Frame is not 2-dimensional. } } } \sstroutine{ AST\_INTERVAL }{ Create a Interval }{ \sstdescription{ This function creates a new \htmlref{Interval}{Interval} and optionally initialises its attributes. A Interval is a \htmlref{Region}{Region} which represents upper and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval. At least one axis limit must be supplied. Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} should usually be used in these cases since this requires the user to think about suitable upper and lower limits, } \sstinvocation{ RESULT = AST\_INTERVAL( FRAME, LBND, UBND, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ LBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the lower limits on each axis. Set a value to AST\_\_BAD to indicate that the axis has no lower limit. } \sstsubsection{ UBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute) containing the upper limits on each axis. Set a value to AST\_\_BAD to indicate that the axis has no upper limit. } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Interval being created. The uncertainty in any point on the boundary of the Interval is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Interval. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Interval being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Interval. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_INTERVAL = INTEGER }{ A pointer to the new Interval. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_INTRAMAP }{ Create an IntraMap }{ \sstdescription{ This function creates a new \htmlref{IntraMap}{IntraMap} and optionally initialises its attributes. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates a privately-defined coordinate transformation routine (e.g. written in Fortran) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. However, an IntraMap is intended for use within a single program or a private suite of software, where all programs have access to the same coordinate transformation functions (i.e. can be linked against them). IntraMaps should not normally be stored in datasets which may be exported for processing by other software, since that software will not have the necessary transformation functions available, resulting in an error. You must register any coordinate transformation functions to be used using \htmlref{AST\_INTRAREG}{AST\_INTRAREG} before creating an IntraMap. } \sstinvocation{ RESULT = AST\_INTRAMAP( NAME, NIN, NOUT, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the name of the transformation routine to use (which should previously have been registered using AST\_INTRAREG). This name is case sensitive. All white space will be removed before use. } \sstsubsection{ NIN = INTEGER (Given) }{ The number of input coordinates. This must be compatible with the number of input coordinates accepted by the transformation routine (as specified when this routine was registered using AST\_INTRAREG). } \sstsubsection{ NOUT = INTEGER (Given) }{ The number of output coordinates. This must be compatible with the number of output coordinates produced by the transformation routine (as specified when this routine was registered using AST\_INTRAREG). } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new IntraMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_INTRAMAP = INTEGER }{ A pointer to the new IntraMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_INTRAREG }{ Register a transformation routine for use by an IntraMap }{ \sstdescription{ This function registers a privately-defined coordinate transformation routine written in Fortran so that it may be used to create an \htmlref{IntraMap}{IntraMap}. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates the Fortran routine so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. Registration of relevant transformation routines is required before using the \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} constructor function to create an IntraMap or reading an external representation of an IntraMap from a \htmlref{Channel}{Channel}. } \sstinvocation{ CALL AST\_INTRAREG( NAME, NIN, NOUT, TRAN, FLAGS, PURPOSE, AUTHOR, CONTACT, STATUS ) } \sstarguments{ \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a unique name to be associated with the transformation routine in order to identify it. This name is case sensitive. All white space will be removed before use. } \sstsubsection{ NIN = INTEGER (Given) }{ The number of input coordinates accepted by the transformation routine (i.e. the number of dimensions of the space in which the input points reside). A value of AST\_\_ANY may be given if the routine is able to accommodate a variable number of input coordinates. } \sstsubsection{ NOUT = INTEGER (Given) }{ The number of output coordinates produced by the transformation routine (i.e. the number of dimensions of the space in which the output points reside). A value of AST\_\_ANY may be given if the routine is able to produce a variable number of output coordinates. } \sstsubsection{ TRAN = SUBROUTINE (Given) }{ The transformation routine to be registered. This routine should perform whatever coordinate transformations are required and should have an interface like \htmlref{AST\_TRANN}{AST\_TRANN} (q.v.). This transformation routine must also appear in an EXTERNAL statement in the routine which calls AST\_INTRAREG. } \sstsubsection{ FLAGS = INTEGER (Given) }{ This value may be used to supply a set of flags which describe the transformation routine and which may affect the behaviour of any IntraMap which uses it. Often, a value of zero will be given here, but you may also supply the sum of a set of flags as described in the \texttt{"} Transformation Flags\texttt{"} section (below). } \sstsubsection{ PURPOSE = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a short (one line) textual comment to describe the purpose of the transformation routine. } \sstsubsection{ AUTHOR = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the name of the author of the transformation routine. } \sstsubsection{ CONTACT = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing contact details for the author of the transformation routine (e.g. an e-mail or WWW address). If any IntraMap which uses this transformation routine is exported as part of a dataset to an external user who does not have access to the routine, then these contact details should allow them to obtain the necessary code. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation routine which it uses, so will only refer to the routine by its name (as assigned using AST\_INTRAREG). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation routine with the same name using an identical invocation of AST\_INTRAREG. If no such registration has been performed, then attempting to read the external representation will result in an error. \sstitem You may use AST\_INTRAREG to register a transformation routine with the same name more than once, but only if the arguments supplied are identical on each occasion (i.e there is no way of changing things once a routine has been successfully registered under a given name, and attempting to do so will result in an error). This feature simply allows registration to be performed independently, but consistently, at several places within your program, without having to check whether it has already been done. \sstitem If an error occurs in the transformation routine, this may be indicated by setting its STATUS argument to an error value before it returns. This will immediately terminate the current AST operation. The error value AST\_\_ITFER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). The AST\_\_ITFER error value is defined in the AST\_ERR include file. } } \sstdiytopic{ Transformation Flags }{ The following flags are defined in the AST\_PAR include file and allow you to provide further information about the nature of the transformation routine. Having selected the set of flags which apply, you should supply the sum of their values as the FLAGS argument to AST\_INTRAREG. \sstitemlist{ \sstitem AST\_\_NOFWD: If this flag is set, it indicates that the transformation routine does not implement a forward coordinate transformation. In this case, any IntraMap which uses it will have a \htmlref{TranForward}{TranForward} attribute value of zero and the transformation routine itself will not be called with its FORWARD argument set to .TRUE.. By default, it is assumed that a forward transformation is provided. \sstitem AST\_\_NOINV: If this flag is set, it indicates that the transformation routine does not implement an inverse coordinate transformation. In this case, any IntraMap which uses it will have a \htmlref{TranInverse}{TranInverse} attribute value of zero and the transformation routine itself will not be called with its FORWARD argument set to .FALSE.. By default, it is assumed that an inverse transformation is provided. \sstitem AST\_\_SIMPFI: You may set this flag if applying the transformation routine\texttt{'} s forward coordinate transformation, followed immediately by the matching inverse transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}). It is not necessary that both transformations have actually been implemented. \sstitem AST\_\_SIMPIF: You may set this flag if applying the transformation routine\texttt{'} s inverse coordinate transformation, followed immediately by the matching forward transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using AST\_SIMPLIFY). It is not necessary that both transformations have actually been implemented. } } } \sstroutine{ AST\_INVERT }{ Invert a Mapping }{ \sstdescription{ This routine inverts a \htmlref{Mapping}{Mapping} by reversing the boolean sense of its \htmlref{Invert}{Invert} attribute. If this attribute is zero (the default), the Mapping will transform coordinates in the way specified when it was created. If it is non-zero, the input and output coordinates will be inter-changed so that the direction of the Mapping is reversed. This will cause it to display the inverse of its original behaviour. } \sstinvocation{ CALL AST\_INVERT( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_ISA$<$CLASS$>$ }{ Test membership of a class by an Object }{ \sstdescription{ This is a family of functions which test whether an \htmlref{Object}{Object} is a member of the class called $<$CLASS$>$, or of any class derived from it. } \sstinvocation{ RESULT = AST\_ISA$<$CLASS$>$( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ These functions apply to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_ISA$<$CLASS$>$ = LOGICAL }{ .TRUE. if the Object belongs to the class called $<$CLASS$>$ (or to a class derived from it), otherwise .FALSE.. } } \sstexamples{ \sstexamplesubsection{ MEMBER = AST\_ISAFRAME( OBJ, STATUS ); }{ Tests whether Object OBJ is a member of the \htmlref{Frame}{Frame} class, or of any class derived from a Frame. } } \sstnotes{ \sstitemlist{ \sstitem Every AST class provides a function (AST\_ISA$<$CLASS$>$) of this form, where $<$CLASS$>$ should be replaced by the class name. \sstitem This function attempts to execute even if STATUS is set to an error value on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem A value of .FALSE. will be returned if this function should fail for any reason. In particular, it will fail if the pointer supplied does not identify an Object of any sort. } } } \sstroutine{ AST\_KEYMAP }{ Create a KeyMap }{ \sstdescription{ This function creates a new empty \htmlref{KeyMap}{KeyMap} and optionally initialises its attributes. Entries can then be added to the KeyMap using the \htmlref{AST\_MAPPUT0$<$X$>$}{AST\_MAPPUT0$<$X$>$} and \htmlref{AST\_MAPPUT1$<$X$>$}{AST\_MAPPUT1$<$X$>$} functions. The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), character string or AST \htmlref{Object}{Object} pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap. } \sstinvocation{ RESULT = AST\_KEYMAP( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new KeyMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAP = INTEGER }{ A pointer to the new KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_LINEARAPPROX }{ Obtain a linear approximation to a Mapping, if appropriate }{ \sstdescription{ This function tests the forward coordinate transformation implemented by a \htmlref{Mapping}{Mapping} over a given range of input coordinates. If the transformation is found to be linear to a specified level of accuracy, then an array of fit coefficients is returned. These may be used to implement a linear approximation to the Mapping\texttt{'} s forward transformation within the specified range of output coordinates. If the transformation is not sufficiently linear, no coefficients are returned. } \sstinvocation{ RESULT = AST\_LINEARAPPROX( THIS, LBND, UBND, TOL, FIT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping. } \sstsubsection{ LBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This box should specify the region over which linearity is required. } \sstsubsection{ UBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing the upper bounds of the box specifying the region over which linearity is required. } \sstsubsection{ TOL = DOUBLE PRECISION (Given) }{ The maximum permitted deviation from linearity, expressed as a positive Cartesian displacement in the output coordinate space of the Mapping. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then no fit coefficients will be returned. } \sstsubsection{ FIT( $*$ ) = DOUBLE PRECISION (Returned) }{ An array in which to return the co-efficients of the linear approximation to the specified transformation. This array should have at least \texttt{"} ( Nin $+$ 1 ) $*$ \htmlref{Nout}{Nout}\texttt{"} , elements. The first Nout elements hold the constant offsets for the transformation outputs. The remaining elements hold the gradients. So if the Mapping has 2 inputs and 3 outputs the linear approximation to the forward transformation is: X\_out = fit(1) $+$ fit(4)$*$X\_in $+$ fit(5)$*$Y\_in Y\_out = fit(2) $+$ fit(6)$*$X\_in $+$ fit(7)$*$Y\_in Z\_out = fit(3) $+$ fit(8)$*$X\_in $+$ fit(9)$*$Y\_in } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_LINEARAPPROX = LOGICAL }{ If the forward transformation is sufficiently linear, .TRUE is returned. Otherwise .FALSE. is returned and the fit co-efficients are set to AST\_\_BAD. } } \sstnotes{ \sstitemlist{ \sstitem This function fits the Mapping\texttt{'} s forward transformation. To fit the inverse transformation, the Mapping should be inverted using \htmlref{AST\_INVERT}{AST\_INVERT} before invoking this function. \sstitem A value of .FALSE. will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } } \sstroutine{ AST\_LUTMAP }{ Create a LutMap }{ \sstdescription{ This function creates a new \htmlref{LutMap}{LutMap} and optionally initialises its attributes. A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. Each input coordinate value is first scaled to give the index of an entry in the table by subtracting a starting value (the input coordinate corresponding to the first table entry) and dividing by an increment (the difference in input coordinate value between adjacent table entries). The resulting index will usually contain a fractional part, so the output coordinate value is then generated by interpolating linearly between the appropriate entries in the table. If the index lies outside the range of the table, linear extrapolation is used based on the two nearest entries (i.e. the two entries at the start or end of the table, as appropriate). If the lookup table entries increase or decrease monotonically, then the inverse transformation may also be performed. } \sstinvocation{ RESULT = AST\_LUTMAP( NLUT, LUT, START, INC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NLUT = INTEGER (Given) }{ The number of entries in the lookup table. This value must be at least 2. } \sstsubsection{ LUT( NLUT ) = DOUBLE PRECISION (Given) }{ An array containing the lookup table entries. } \sstsubsection{ START = DOUBLE PRECISION (Given) }{ The input coordinate value which corresponds to the first lookup table entry. } \sstsubsection{ INC = DOUBLE PRECISION (Given) }{ The lookup table spacing (the increment in input coordinate value between successive lookup table entries). This value may be positive or negative, but must not be zero. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new LutMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_LUTMAP = INTEGER }{ A pointer to the new LutMap. } } \sstnotes{ \sstitemlist{ \sstitem If the entries in the lookup table either increase or decrease monotonically, then the new LutMap\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute will have a value of one, indicating that the inverse transformation can be performed. Otherwise, it will have a value of zero, so that any attempt to use the inverse transformation will result in an error. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_MAPBOX }{ Find a bounding box for a Mapping }{ \sstdescription{ This routine allows you to find the \texttt{"} bounding box\texttt{"} which just encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping} (using either its forward or inverse transformation). A typical use might be to calculate the size of an image after being transformed by a Mapping. The routine works on one dimension at a time. When supplied with the lower and upper bounds of a rectangular region (box) of input coordinate space, it finds the lowest and highest values taken by a nominated output coordinate within that region. It also returns the input coordinates where these bounding values are attained. It should be used repeatedly to obtain the extent of the bounding box in more than one dimension. } \sstinvocation{ CALL AST\_MAPBOX( THIS, LBND\_IN, UBND\_IN, FORWARD, COORD\_OUT, LBND\_OUT, UBND\_OUT, XL, XU, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping. } \sstsubsection{ LBND\_IN( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Mapping input coordinate. This should contain the lower bound of the input box in each input dimension. } \sstsubsection{ UBND\_IN( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Mapping input coordinate. This should contain the upper bound of the input box in each input dimension. Note that it is permissible for the upper bound to be less than the corresponding lower bound, as the values will simply be swapped before use. } \sstsubsection{ FORWARD = LOGICAL (Given) }{ If this value is .TRUE., then the Mapping\texttt{'} s forward transformation will be used to transform the input box. Otherwise, its inverse transformation will be used. (If the inverse transformation is selected, then references to \texttt{"} input\texttt{"} and \texttt{"} output\texttt{"} coordinates in this description should be transposed. For example, the size of the LBND\_IN and UBND\_IN arrays should match the number of output coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout} attribute. Similarly, the COORD\_OUT argument, below, should nominate one of the Mapping\texttt{'} s input coordinates.) } \sstsubsection{ COORD\_OUT = INTEGER (Given) }{ The index of the output coordinate for which the lower and upper bounds are required. This value should be at least one, and no larger than the number of Mapping output coordinates. } \sstsubsection{ LBND\_OUT = DOUBLE PRECISION (Returned) }{ The lowest value taken by the nominated output coordinate within the specified region of input coordinate space. } \sstsubsection{ UBND\_OUT = DOUBLE PRECISION (Returned) }{ The highest value taken by the nominated output coordinate within the specified region of input coordinate space. } \sstsubsection{ XL( $*$ ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Mapping input coordinate. This will return the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the lower bound value returned in LBND\_OUT. } \sstsubsection{ XU( $*$ ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Mapping input coordinate. This will return the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the upper bound value returned in UBND\_OUT. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Any input points which are transformed by the Mapping to give output coordinates containing the value AST\_\_BAD are regarded as invalid and are ignored. They will make no contribution to determining the output bounds, even although the nominated output coordinate might still have a valid value at such points. \sstitem An error will occur if the required output bounds cannot be found. Typically, this might happen if all the input points which the routine considers turn out to be invalid (see above). The number of points considered before generating such an error is quite large, so this is unlikely to occur by accident unless valid points are restricted to a very small subset of the input coordinate space. \sstitem The values returned via LBND\_OUT, UBND\_OUT, XL and XU will be set to the value AST\_\_BAD if this routine should fail for any reason. Their initial values on entry will not be altered if the routine is invoked with STATUS set to an error value. } } } \sstroutine{ AST\_MAPCOPY }{ Copy entries from one KeyMap into another }{ \sstdescription{ This routine copies all entries from one \htmlref{KeyMap}{KeyMap} into another. } \sstinvocation{ CALL AST\_MAPCOPY( THIS, THAT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the destination KeyMap. } \sstsubsection{ THAT = INTEGER (Given) }{ Pointer to the source KeyMap. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Entries from the source KeyMap will replace any existing entries in the destination KeyMap that have the same key. \sstitem The one exception to the above rule is that if a source entry contains a scalar KeyMap entry, and the destination contains a scalar KeyMap entry with the same key, then the source KeyMap entry will be copied into the destination KeyMap entry using this function, rather than simply replacing the destination KeyMap entry. \sstitem If the destination entry has a non-zero value for its \htmlref{MapLocked}{MapLocked} attribute, then an error will be reported if the source KeyMap contains any keys that do not already exist within the destination KeyMap. } } } \sstroutine{ AST\_MAPDEFINED }{ Check if a KeyMap contains a defined value for a key }{ \sstdescription{ This function checks to see if a \htmlref{KeyMap}{KeyMap} contains a defined value for a given key. If the key is present in the KeyMap but has an undefined value it returns .FALSE. (unlike \htmlref{AST\_MAPHASKEY}{AST\_MAPHASKEY} which would return .TRUE.). } \sstinvocation{ RESULT = AST\_MAPDEFINED( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPDEFINED = LOGICAL }{ .TRUE. is returned if the requested key name is present in the KeyMap and has a defined value. } } } \sstroutine{ AST\_MAPGET0$<$X$>$ }{ Get a scalar value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a scalar value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name AST\_MAPGET0$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the version of this function which returns character strings, AST\_MAPGET0C, has an extra parameter in which is returned the number of characters written into the supplied CHARACTER variable. } \sstinvocation{ RESULT = AST\_MAPGET0$<$X$>$( THIS, KEY, VALUE, STATUS ) RESULT = AST\_MAPGET0C( THIS, KEY, VALUE, L, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ VALUE = $<$X$>$type (Returned) }{ The requested value. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}), then the contents of the buffer on entry to this function will be unchanged on exit. } \sstsubsection{ L = INTEGER (Returned) }{ This parameter is only present in the interface for the AST\_MAPGET0C function. It is returned holding the number of characters written into the CHARACTER variable supplied for parameter VALUE. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPGET0$<$X$>$ = LOGICAL }{ .TRUE. is returned if the requested key name was found, and does not have an undefined value (see AST\_MAPPUTU). .FALSE. is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, but a .FALSE. value will be returned as the function value. The supplied buffer will be returned unchanged. \sstitem If the stored value is a vector value, then the first value in the vector will be returned. \sstitem If the returned value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object. The returned pointer should be annulled using \htmlref{AST\_ANNUL}{AST\_ANNUL} when it is no longer needed. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPGET0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: Unsigned byte } For example, AST\_MAPGET0D would be used to get a DOUBLE PRECISION value, while AST\_MAPGET0I would be used to get an INTEGER, etc. } } \sstroutine{ AST\_MAPGET1$<$X$>$ }{ Get a vector value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a vector value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name AST\_MAPGET1$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). } \sstinvocation{ RESULT = AST\_MAPGET1$<$X$>$( THIS, KEY, MXVAL, NVAL, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ MXVAL = INTEGER (Given) }{ The number of elements in the VALUE array. } \sstsubsection{ NVAL = INTEGER (Returned) }{ The number of elements stored in the Any unused elements of the array are left unchanged. } \sstsubsection{ VALUE( MXVAL ) = $<$X$>$type (Returned) }{ The requested values. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}), then the contents of the buffer on entry to this function will be unchanged on exit. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPGET1$<$X$>$ = LOGICAL }{ .TRUE. is returned if the requested key name was found, and does not have an undefined value (see AST\_MAPPUTU). .FALSE. is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, but a .FALSE. value will be returned as the function value. The supplied array will be returned unchanged. \sstitem If the stored value is a scalar value, then the value will be returned in the first element of the supplied array, and NVAL will be returned set to 1. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPGET1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: Unsigned byte } For example, AST\_MAPGET1D would be used to get DOUBLE PRECISION values, while AST\_MAPGET1I would be used to get INTEGER values, etc. } } \sstroutine{ AST\_MAPGETELEM$<$X$>$ }{ Get a single element of a vector value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a single element of a vector value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name AST\_MAPGETELEM$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). } \sstinvocation{ RESULT = AST\_MAPGETELEM$<$X$>$( THIS, KEY, ELEM, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ ELEM = INTEGER (Given) }{ The index of the required vector element, starting at one. An error will be reported if the value is outside the range of the vector. } \sstsubsection{ VALUE = $<$X$>$type (Returned) }{ The requested value. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}), then the contents of the buffer on entry to this function will be unchanged on exit. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPGETELEM$<$X$>$ = LOGICAL }{ .TRUE. is returned if the requested key name was found, and does not have an undefined value (see AST\_MAPPUTU). .FALSE. is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, or if it has an undefined value, but a .FALSE. value will be returned as the function value. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPGETELEM$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: Unsigned byte } For example, AST\_MAPGETELEMD would be used to get a DOUBLE PRECISION value, while AST\_MAPGETELEMI would be used to get an INTEGER value, etc. } } \sstroutine{ AST\_MAPHASKEY }{ Check if an entry with a given key exists in a KeyMap }{ \sstdescription{ This function returns a flag indicating if the \htmlref{KeyMap}{KeyMap} contains an entry with the given key. } \sstinvocation{ RESULT = AST\_MAPHASKEY( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPHASKEY = LOGICAL }{ .TRUE. if the key was found, and .FALSE. otherwise. } } \sstnotes{ \sstitemlist{ \sstitem .TRUE. is returned if the key exists but has an undefined value (that is, the returned value does not depend on whether the entry has a defined value or not). See also \htmlref{AST\_MAPDEFINED}{AST\_MAPDEFINED}, which returns zero in such a case. \sstitem A function value of .FALSE. will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_MAPKEY }{ Get the key at a given index within the KeyMap }{ \sstdescription{ This function returns a string holding the key for the entry with the given index within the \htmlref{KeyMap}{KeyMap}. This function is intended primarily as a means of iterating round all the elements in a KeyMap. For this purpose, the number of entries in the KeyMap should first be found using \htmlref{AST\_MAPSIZE}{AST\_MAPSIZE} and this function should then be called in a loop, with the index value going from one to the size of the KeyMap. The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy} attribute. } \sstinvocation{ RESULT = AST\_MAPKEY( THIS, INDEX, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ INDEX = INTEGER (Given) }{ The index into the KeyMap. The first entry has index one, and the last has index SIZE, the value returned by the AST\_MAPSIZE function. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPKEY = CHARACTER $*$ ( AST\_\_SZCHR ) }{ The key value. } } \sstnotes{ \sstitemlist{ \sstitem A blank string will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_MAPLENC }{ Get the number of characters in a character entry in a KeyMap }{ \sstdescription{ This function returns the minimum length which a character variable which must have in order to be able to store a specified entry in the supplied \htmlref{KeyMap}{KeyMap}. If the named entry is a vector entry, then the returned value is the length of the longest element of the vector value. } \sstinvocation{ RESULT = AST\_MAPLENC( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPLENC = INTEGER }{ The length (i.e. number of characters) of the longest formatted value associated with the named entry. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned without error if the named entry cannot be formatted as a character string. \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_MAPLENGTH }{ Get the vector length of an entry in a KeyMap }{ \sstdescription{ This function returns the vector length of a named entry in a \htmlref{KeyMap}{KeyMap}, (that is, how many values are associated with the entry). } \sstinvocation{ RESULT = AST\_MAPLENGTH( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPLENGTH = INTEGER }{ The length of the entry. One for a scalar, greater than one for a vector. A value of zero is returned if the KeyMap does not contain the named entry. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_MAPPUT0$<$X$>$ }{ Add a scalar value to a KeyMap }{ \sstdescription{ This is a set of routine for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a routine which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic routine name AST\_MAPPUT0$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). } \sstinvocation{ CALL AST\_MAPPUT0$<$X$>$( THIS, KEY, VALUE, COMMENT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap in which to store the supplied value. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ VALUE = $<$X$>$type (Given) }{ The value to be stored. The data type of this value should match the 1-character type code appended to the routine name (e.g. if you are using AST\_MAPPUT0A, the type of this value should be \texttt{"} integer pointer for an AstObject\texttt{"} ). } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A comment string to be stored with the value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the new value will replace the old value. \sstitem If the stored value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object, including any obtained later using AST\_MAPGET0A. The reference count for the Object will be decremented when the KeyMap is destroyed, or the entry is removed or over-written with a different pointer. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPPUT0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: Unsigned byte } For example, AST\_MAPPUT0D would be used to store a DOUBLE PRECISION value, while AST\_MAPPUT0I would be used to store an INTEGER, etc. } } \sstroutine{ AST\_MAPPUT1$<$X$>$ }{ Add a vector value to a KeyMap }{ \sstdescription{ This is a set of routine for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a routine which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic routine name AST\_MAPPUT1$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). } \sstinvocation{ CALL AST\_MAPPUT1$<$X$>$( THIS, KEY, SIZE, VALUE, COMMENT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap in which to store the supplied values. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ SIZE = INTEGER (Given) }{ The number of elements in the supplied array of values. } \sstsubsection{ VALUE( $*$ ) = $<$X$>$type (Given) }{ The array of values to be stored. The data type of this value should match the 1-character type code appended to the routine name (e.g. if you are using AST\_MAPPUT1A, the type of this value should be \texttt{"} integer pointer for an AstObject)\texttt{"} . } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A comment string to be stored with the values. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the new values will replace the old values. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPPUT1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: Unsigned byte } For example, AST\_MAPPUT1D would be used to store DOUBLE PRECISION values, while AST\_MAPPUT1I would be used to store INTEGER, etc. } } \sstroutine{ AST\_MAPPUTELEM$<$X$>$ }{ Put a value into an element of a vector value in a KeyMap }{ \sstdescription{ This is a set of functions for storing a value in a single element of a vector value in a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name AST\_MAPPUTELEM$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The supplied value is converted from the data type indicated by $<$X$>$ to the data type of the KeyMap entry before being stored (an error is reported if it is not possible to convert the value to the required data type). } \sstinvocation{ CALL AST\_MAPPUTELEM$<$X$>$( THIS, KEY, ELEM, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ ELEM = INTEGER (Given) }{ The index of the vector element to modify, starting at one. } \sstsubsection{ VALUE = $<$X$>$type (Given) }{ The value to store. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ KeyMap }{ If the ELEM index is outside the range of the vector, the length of the vector will be increased by one element and the supplied value will be stored at the end of the vector in the new element. } \sstsubsection{ \htmlref{Table}{Table} }{ If the ELEM index is outside the range of the vector, an error will be reported. The number of elements in each cell of a column is specified when the column is created using \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}. } } \sstnotes{ \sstitemlist{ \sstitem If the entry originally holds a scalar value, it will be treated like a vector entry of length 1. \sstitem If the specified key cannot be found in the given KeyMap, or is found but has an undefined value, a new vector entry with the given name, and data type implied by $<$X$>$, is created and the supplied value is stored in its first entry. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST\_MAPPUTELEM$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem C: CHARACTER \sstitem A: INTEGER used to identify an AstObject \sstitem S: INTEGER$*$2 (short integer) \sstitem B: BYTE (unsigned) } For example, AST\_MAPPUTELEMD would be used to put a DOUBLE PRECISION value, while AST\_MAPPUTELEMI would be used to put an INTEGER value, etc. } } \sstroutine{ AST\_MAPPUTU }{ Add an entry to a KeyMap with an undefined value }{ \sstdescription{ This routine adds a new entry to a \htmlref{KeyMap}{KeyMap}, but no value is stored with the entry. The entry therefore has a special data type represented by symbolic constant AST\_\_UNDEFTYPE. An example use is to add entries with undefined values to a KeyMap prior to locking them with the \htmlref{MapLocked}{MapLocked} attribute. Such entries can act as placeholders for values that can be added to the KeyMap later. } \sstinvocation{ CALL AST\_MAPPUTU( THIS, KEY, COMMENT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap in which to store the supplied value. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A comment string to be stored with the value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the value associated with the key will be removed. } } } \sstroutine{ AST\_MAPREGION }{ Transform a Region into a new Frame using a given Mapping }{ \sstdescription{ This function returns a pointer to a new \htmlref{Region}{Region} which corresponds to supplied Region described by some other specified coordinate system. A \htmlref{Mapping}{Mapping} is supplied which transforms positions between the old and new coordinate systems. The new Region may not be of the same class as the original region. } \sstinvocation{ RESULT = AST\_MAPREGION( THIS, MAP, FRAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ MAP = INTEGER (Given) }{ Pointer to a Mapping which transforms positions from the coordinate system represented by the supplied Region to the coordinate system specified by FRAME. The supplied Mapping should define both forward and inverse transformations, and these transformations should form a genuine inverse pair. That is, transforming a position using the forward transformation and then using the inverse transformation should produce the original input position. Some Mapping classes (such as \htmlref{PermMap}{PermMap}, \htmlref{MathMap}{MathMap}, \htmlref{SphMap}{SphMap}) can result in Mappings for which this is not true. } \sstsubsection{ FRAME = INTEGER (Given) }{ Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which the new Region is required. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPREGION = INTEGER }{ A pointer to a new Region. This Region will represent the area within the coordinate system specified by FRAME which corresponds to the supplied Region. } } \sstnotes{ \sstitemlist{ \sstitem The uncertainty associated with the supplied Region is modified using the supplied Mapping. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_MAPREMOVE }{ Removed a named entry from a KeyMap }{ \sstdescription{ This routine removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the KeyMap does not contain the specified key. } \sstinvocation{ CALL AST\_MAPREMOVE( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_MAPRENAME }{ Rename an existing KeyMap entry }{ \sstdescription{ This routine associated a new key with an existing entry in a \htmlref{KeyMap}{KeyMap}. It returns without action if the oldkey does not exist in the KeyMap. } \sstinvocation{ CALL AST\_MAPRENAME( THIS, OLDKEY, NEWKEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ OLDKEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the entry to be renamed. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ NEKEY = CHARACTER $*$ ( $*$ ) (Given) }{ The new character string to associated with the renamed entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_MAPSIZE }{ Get the number of entries in a KeyMap }{ \sstdescription{ This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}. } \sstinvocation{ RESULT = AST\_MAPSIZE( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPSIZE = INTEGER }{ The number of entries in the KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_MAPSPLIT }{ Split a Mapping up into parallel component Mappings }{ \sstdescription{ This routine creates a new \htmlref{Mapping}{Mapping} which connects specified inputs within a supplied Mapping to the corresponding outputs of the supplied Mapping. This is only possible if the specified inputs correspond to some subset of the Mapping outputs. That is, there must exist a subset of the Mapping outputs for which each output depends only on the selected Mapping inputs, and not on any of the inputs which have not been selected. Also, any output which is not in this subset must not depend on any of the selected inputs. If these conditions are not met by the supplied Mapping, then an AST\_\_NULL Mapping pointer is returned. } \sstinvocation{ CALL AST\_MAPSPLIT( THIS, NIN, IN, OUT, MAP, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be split. } \sstsubsection{ NIN = INTEGER (Given) }{ The number of inputs to pick from THIS. } \sstsubsection{ IN( NIN ) = INTEGER (Given) }{ An array holding the indices within the supplied Mapping of the inputs which are to be picked from the Mapping. If \texttt{"} \htmlref{Nin}{Nin}\texttt{"} is the number of inputs of the supplied Mapping, then each element should have a value in the range 1 to Nin. } \sstsubsection{ OUT( $*$ ) = INTEGER (Returned) }{ An array in which to return the indices of the outputs of the supplied Mapping which are fed by the picked inputs. A value of one is used to refer to the first Mapping output. The supplied array should have a length at least equal to the number of outputs in the supplied Mapping. The number of values stored in the array on exit will equal the number of outputs in the returned Mapping. The i\texttt{'} th element in the returned array holds the index within the supplied Mapping which corresponds to the i\texttt{'} th output of the returned Mapping. } \sstsubsection{ MAP = INTEGER (Returned) }{ The returned Mapping. This Mapping will have NIN inputs (the number of outputs may be different to NIN). AST\_\_NULL is returned if the supplied Mapping has no subset of outputs which depend only on the selected inputs. The returned Mapping is a deep copy of the required parts of the supplied Mapping. } } \sstnotes{ \sstitemlist{ \sstitem If this routine is invoked with the global error status set, or if it should fail for any reason, then AST\_\_NULL will be returned for MAP. } } } \sstroutine{ AST\_MAPTYPE }{ Get the data type of an entry in a KeyMap }{ \sstdescription{ This function returns a value indicating the data type of a named entry in a \htmlref{KeyMap}{KeyMap}. This is the data type which was used when the entry was added to the KeyMap. } \sstinvocation{ RESULT = AST\_MAPTYPE( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the KeyMap. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MAPTYPE = INTEGER }{ One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for INTEGER$*$2), AST\_\_BYTETYPE (for unsigned bytes ) AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}). AST\_\_BADTYPE is returned if the supplied key is not found in the KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem A function value of AST\_\_BADTYPE will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_MARK }{ Draw a set of markers for a Plot }{ \sstdescription{ This routine draws a set of markers (symbols) at positions specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The positions are transformed into graphical coordinates to determine where the markers should appear within the plotting area. } \sstinvocation{ CALL AST\_MARK( THIS, NMARK, NCOORD, INDIM, IN, TYPE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ NMARK = INTEGER (Given) }{ The number of markers to draw. This may be zero, in which case nothing will be drawn. } \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinates being supplied for each mark (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given by its \htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ INDIM = INTEGER (Given) }{ The number of elements along the first dimension of the IN array (which contains the marker coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than NMARK. } \sstsubsection{ IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given) }{ A 2-dimensional array giving the physical coordinates of the points where markers are to be drawn. These should be stored such that the value of coordinate number COORD for input mark number MARK is found in element IN(MARK,COORD). } \sstsubsection{ TYPE = INTEGER (Given) }{ A value specifying the type (e.g. shape) of marker to be drawn. The set of values which may be used (and the shapes that will result) is determined by the underlying graphics system. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Markers are not drawn at positions which have any coordinate equal to the value AST\_\_BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST\_\_BAD). \sstitem If any marker position is clipped (see \htmlref{AST\_CLIP}{AST\_CLIP}), then the entire marker is not drawn. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_MASK$<$X$>$ }{ Mask a region of a data grid }{ \sstdescription{ This is a set of functions for masking out regions within gridded data (e.g. an image). The functions modifies a given data grid by assigning a specified value to all samples which are inside (or outside if INSIDE is .FALSE.) the specified \htmlref{Region}{Region}. You should use a masking function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST\_MASK$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are masking data with type REAL, you should use the function AST\_MASKR (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstinvocation{ RESULT = AST\_MASK$<$X$>$( THIS, MAP, INSIDE, NDIM, LBND, UBND, IN, VAL, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to a Region. } \sstsubsection{ MAP = INTEGER (Given) }{ Pointer to a \htmlref{Mapping}{Mapping}. The forward transformation should map positions in the coordinate system of the supplied Region into pixel coordinates as defined by the LBND and UBND arguments. A value of AST\_\_NULL can be supplied if the coordinate system of the supplied Region corresponds to pixel coordinates. This is equivalent to supplying a \htmlref{UnitMap}{UnitMap}. The number of inputs for this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of axes in the supplied Region (as given by the \htmlref{Naxes}{Naxes} attribute of the Region). The number of outputs for the Mapping (as given by its \htmlref{Nout}{Nout} attribute) should match the number of grid dimensions given by the value of NDIM below. } \sstsubsection{ INSIDE = INTEGER (Given) }{ A boolean value which indicates which pixel are to be masked. If .TRUE. is supplied, then all grid pixels with centres inside the supplied Region are assigned the value given by VAL, and all other pixels are left unchanged. If .FALSE. is supplied, then all grid pixels with centres not inside the supplied Region are assigned the value given by VAL, and all other pixels are left unchanged. Note, the \htmlref{Negated}{Negated} attribute of the Region is used to determine which pixel are inside the Region and which are outside. So the inside of a Region which has not been negated is the same as the outside of the corresponding negated Region. For types of Region such as \htmlref{PointList}{PointList} which have zero volume, pixel centres will rarely fall exactly within the Region. For this reason, the inclusion criterion is changed for zero-volume Regions so that pixels are included (or excluded) if any part of the Region passes through the pixel. For a PointList, this means that pixels are included (or excluded) if they contain at least one of the points listed in the PointList. } \sstsubsection{ NDIM = INTEGER (Given) }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ LBND( NDIM ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND( NDIM ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND and UBND together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND(J)-LBND(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ IN( $*$ ) = $<$Xtype$>$ (Given and Returned) }{ An array, with one element for each pixel in the input grid, containing the data to be masked. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_MASKR, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). On exit, the samples specified by INSIDE are set to the value of VAL. All other samples are left unchanged. } \sstsubsection{ VAL = $<$Xtype$>$ (Given) }{ This argument should have the same type as the elements of the IN array. It specifies the value used to flag the masked data (see INSIDE). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MASK$<$X$>$ = INTEGER }{ The number of pixels to which a value of BADVAL has been assigned. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem An error will be reported if the overlap of the Region and the array cannot be determined. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name AST\_MASK$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem UI: INTEGER (treated as unsigned) \sstitem S: INTEGER$*$2 (short integer) \sstitem US: INTEGER$*$2 (short integer, treated as unsigned) \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_MASKD would be used to process DOUBLE PRECISION data, while AST\_MASKS would be used to process short integer data (stored in an INTEGER$*$2 array), etc. For compatibility with other Starlink facilities, the codes W and UW are provided as synonyms for S and US respectively (but only in the Fortran interface to AST). } } \sstroutine{ AST\_MATCHAXES }{ Find any corresponding axes in two Frames }{ \sstdescription{ 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 \htmlref{Frame}{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. } \sstinvocation{ CALL AST\_MATCHAXES( FRM1, FRM2, AXES, STATUS ) } \sstarguments{ \sstsubsection{ FRM1 = INTEGER (Given) }{ Pointer to the first Frame. } \sstsubsection{ FRM2 = INTEGER (Given) }{ Pointer to the second Frame. } \sstsubsection{ AXES = INTEGER( $*$ ) (Returned) }{ 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. \htmlref{Axis}{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. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. } } \sstnotes{ \sstitemlist{ \sstitem Corresponding axes are identified by the fact that a \htmlref{Mapping}{Mapping} can be found between them using \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}. Thus, \texttt{"} corresponding axes\texttt{"} are not necessarily identical. For instance, \htmlref{SkyFrame}{SkyFrame} axes in two Frames will match even if they describe different celestial coordinate systems } } } \sstroutine{ AST\_MATHMAP }{ Create a MathMap }{ \sstdescription{ This function creates a new \htmlref{MathMap}{MathMap} and optionally initialises its attributes. A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in Fortran. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs. } \sstinvocation{ RESULT = AST\_MATHMAP( NIN, NOUT, NFWD, FWD, NINV, INV, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NIN = INTEGER }{ Number of input variables for the MathMap. This determines the value of its \htmlref{Nin}{Nin} attribute. } \sstsubsection{ NOUT = INTEGER }{ Number of output variables for the MathMap. This determines the value of its \htmlref{Nout}{Nout} attribute. } \sstsubsection{ NFWD = INTEGER }{ The number of forward transformation functions being supplied. This must be at least equal to NOUT, but may be increased to accommodate any additional expressions which define intermediate variables for the forward transformation (see the \texttt{"} Calculating Intermediate Values\texttt{"} section below). } \sstsubsection{ FWD = CHARACTER $*$ ( $*$ )( NFWD ) }{ An array which contains the expressions defining the forward transformation. The syntax of these expressions is described below. } \sstsubsection{ NINV = INTEGER }{ The number of inverse transformation functions being supplied. This must be at least equal to NIN, but may be increased to accommodate any additional expressions which define intermediate variables for the inverse transformation (see the \texttt{"} Calculating Intermediate Values\texttt{"} section below). } \sstsubsection{ INV = CHARACTER $*$ ( $*$ )( NINV ) }{ An array which contains the expressions defining the inverse transformation. The syntax of these expressions is described below. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new MathMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MATHMAP = INTEGER }{ A pointer to the new MathMap. } } \sstnotes{ \sstitemlist{ \sstitem The sequence of numbers produced by the random number functions available within a MathMap is normally unpredictable and different for each MathMap. However, this behaviour may be controlled by means of the MathMap\texttt{'} s \htmlref{Seed}{Seed} attribute. \sstitem Normally, compound Mappings (CmpMaps) which involve MathMaps will not be subject to simplification (e.g. using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}) because AST cannot know how different MathMaps will interact. However, in the special case where a MathMap occurs in series with its own inverse, then simplification may be possible. Whether simplification does, in fact, occur under these circumstances is controlled by the MathMap\texttt{'} s \htmlref{SimpFI}{SimpFI} and \htmlref{SimpIF}{SimpIF} attributes. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Defining Transformation Functions }{ A MathMap\texttt{'} s transformation functions are supplied as a set of expressions in an array of character strings. Normally you would supply the same number of expressions for the forward transformation, via the FWD argument, as there are output variables (given by the MathMap\texttt{'} s Nout attribute). For instance, if Nout is 2 you might use: \sstitemlist{ \sstitem \texttt{'} R = SQRT( X $*$ X $+$ Y $*$ Y )\texttt{'} \sstitem \texttt{'} THETA = ATAN2( Y, X )\texttt{'} } which defines a transformation from Cartesian to polar coordinates. Here, the variables that appear on the left of each expression (R and THETA) provide names for the output variables and those that appear on the right (X and Y) are references to input variables. To complement this, you must also supply expressions for the inverse transformation via the INV argument. In this case, the number of expressions given would normally match the number of MathMap input coordinates (given by the Nin attribute). If Nin is 2, you might use: \sstitemlist{ \sstitem \texttt{'} X = R $*$ COS( THETA )\texttt{'} \sstitem \texttt{'} Y = R $*$ SIN( THETA )\texttt{'} } which expresses the transformation from polar to Cartesian coordinates. Note that here the input variables (X and Y) are named on the left of each expression, and the output variables (R and THETA) are referenced on the right. Normally, you cannot refer to a variable on the right of an expression unless it is named on the left of an expression in the complementary set of functions. Therefore both sets of functions (forward and inverse) must be formulated using the same consistent set of variable names. This means that if you wish to leave one of the transformations undefined, you must supply dummy expressions which simply name each of the output (or input) variables. For example, you might use: \sstitemlist{ \sstitem \texttt{'} X\texttt{'} \sstitem \texttt{'} Y\texttt{'} } for the inverse transformation above, which serves to name the input variables but without defining an inverse transformation. } \sstdiytopic{ Calculating Intermediate Values }{ It is sometimes useful to calculate intermediate values and then to use these in the final expressions for the output (or input) variables. This may be done by supplying additional expressions for the forward (or inverse) transformation functions. For instance, the following array of five expressions describes 2-dimensional pin-cushion distortion: \sstitemlist{ \sstitem \texttt{'} R = SQRT( XIN $*$ XIN $+$ YIN $*$ YIN )\texttt{'} \sstitem \texttt{'} ROUT = R $*$ ( 1 $+$ 0.1 $*$ R $*$ R )\texttt{'} \sstitem \texttt{'} THETA = ATAN2( YIN, XIN )\texttt{'} , \sstitem \texttt{'} XOUT = ROUT $*$ COS( THETA )\texttt{'} \sstitem \texttt{'} YOUT = ROUT $*$ SIN( THETA )\texttt{'} } Here, we first calculate three intermediate results (R, ROUT and THETA) and then use these to calculate the final results (XOUT and YOUT). The MathMap knows that only the final two results constitute values for the output variables because its Nout attribute is set to 2. You may define as many intermediate variables in this way as you choose. Having defined a variable, you may then refer to it on the right of any subsequent expressions. Note that when defining the inverse transformation you may only refer to the output variables XOUT and YOUT. The intermediate variables R, ROUT and THETA (above) are private to the forward transformation and may not be referenced by the inverse transformation. The inverse transformation may, however, define its own private intermediate variables. } \sstdiytopic{ Expression Syntax }{ The expressions given for the forward and inverse transformations closely follow the syntax of Fortran (with some extensions for compatibility with the C language). They may contain references to variables and literal constants, together with arithmetic, logical, relational and bitwise operators, and function invocations. A set of symbolic constants is also available. Each of these is described in detail below. Parentheses may be used to over-ride the normal order of evaluation. There is no built-in limit to the length of expressions and they are insensitive to case or the presence of additional white space. } \sstdiytopic{ Variables }{ Variable names must begin with an alphabetic character and may contain only alphabetic characters, digits, and the underscore character \texttt{"} \_\texttt{"} . There is no built-in limit to the length of variable names. } \sstdiytopic{ Literal Constants }{ Literal constants, such as \texttt{"} 0\texttt{"} , \texttt{"} 1\texttt{"} , \texttt{"} 0.007\texttt{"} or \texttt{"} 2.505E-16\texttt{"} may appear in expressions, with the decimal point and exponent being optional (a \texttt{"} D\texttt{"} may also be used as an exponent character). A unary minus \texttt{"} -\texttt{"} may be used as a prefix. } \sstdiytopic{ Arithmetic Precision }{ All arithmetic is floating point, performed in double precision. } \sstdiytopic{ Propagation of Missing Data }{ Unless indicated otherwise, if any argument of a function or operator has the value AST\_\_BAD (indicating missing data), then the result of that function or operation is also AST\_\_BAD, so that such values are propagated automatically through all operations performed by MathMap transformations. The special value AST\_\_BAD can be represented in expressions by the symbolic constant \texttt{"} $<$bad$>$\texttt{"} . A $<$bad$>$ result (i.e. equal to AST\_\_BAD) is also produced in response to any numerical error (such as division by zero or numerical overflow), or if an invalid argument value is provided to a function or operator. } \sstdiytopic{ Arithmetic Operators }{ The following arithmetic operators are available: \sstitemlist{ \sstitem X1 $+$ X2: Sum of X1 and X2. \sstitem X1 - X2: Difference of X1 and X2. \sstitem X1 $*$ X2: Product of X1 and X2. \sstitem X1 / X2: Ratio of X1 and X2. \sstitem X1 $*$$*$ X2: X1 raised to the power of X2. \sstitem $+$ X: Unary plus, has no effect on its argument. \sstitem - X: Unary minus, negates its argument. } } \sstdiytopic{ Logical Operators }{ Logical values are represented using zero to indicate .FALSE. and non-zero to indicate .TRUE.. In addition, the value AST\_\_BAD is taken to mean \texttt{"} unknown\texttt{"} . The values returned by logical operators may therefore be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"} logic is implemented. For example, A.OR.B may evaluate to 1 if A is non-zero, even if B has the value AST\_\_BAD. This is because the result of the operation would not be affected by the value of B, so long as A is non-zero. The following logical operators are available: \sstitemlist{ \sstitem X1 .AND. X2: Logical AND between X1 and X2, returning 1 if both X1 and X2 are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym \texttt{"} \&\&\texttt{"} is also provided for compatibility with C.) \sstitem X1 .OR. X2: Logical OR between X1 and X2, returning 1 if either X1 or X2 are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym \texttt{"} $|$$|$\texttt{"} is also provided for compatibility with C.) \sstitem X1 .NEQV. X2: Logical exclusive OR (XOR) between X1 and X2, returning 1 if exactly one of X1 and X2 is non-zero, and 0 otherwise. Tri-state logic is not used with this operator. (The synonym \texttt{"} .XOR.\texttt{"} is also provided, although this is not standard Fortran. In addition, the C-like synonym \texttt{"} $\wedge$$\wedge$\texttt{"} may be used, although this is also not standard.) \sstitem X1 .EQV. X2: Tests whether the logical states of X1 and X2 (i.e. .TRUE./.FALSE.) are equal. It is the negative of the exclusive OR (XOR) function. Tri-state logic is not used with this operator. \sstitem .NOT. X: Logical unary NOT operation, returning 1 if X is zero, and 0 otherwise. (The synonym \texttt{"} !\texttt{"} is also provided for compatibility with C.) } } \sstdiytopic{ Relational Operators }{ Relational operators return the logical result (0 or 1) of comparing the values of two floating point values for equality or inequality. The value AST\_\_BAD may also be returned if either argument is $<$bad$>$. The following relational operators are available: \sstitemlist{ \sstitem X1 .EQ. X2: Tests whether X1 equals X2. (The synonym \texttt{"} ==\texttt{"} is also provided for compatibility with C.) \sstitem X1 .NE. X2: Tests whether X1 is unequal to X2. (The synonym \texttt{"} !=\texttt{"} is also provided for compatibility with C.) \sstitem X1 .GT. X2: Tests whether X1 is greater than X2. (The synonym \texttt{"} $>$\texttt{"} is also provided for compatibility with C.) \sstitem X1 .GE. X2: Tests whether X1 is greater than or equal to X2. (The synonym \texttt{"} $>$=\texttt{"} is also provided for compatibility with C.) \sstitem X1 .LT. X2: Tests whether X1 is less than X2. (The synonym \texttt{"} $<$\texttt{"} is also provided for compatibility with C.) \sstitem X1 .LE. X2: Tests whether X1 is less than or equal to X2. (The synonym \texttt{"} $<$=\texttt{"} is also provided for compatibility with C.) } Note that relational operators cannot usefully be used to compare values with the $<$bad$>$ value (representing missing data), because the result is always $<$bad$>$. The ISBAD() function should be used instead. Note, also, that because logical operators can operate on floating point values, care must be taken to use parentheses in some cases where they would not normally be required in Fortran. For example, the expresssion: \sstitemlist{ \sstitem .NOT. A .EQ. B } must be written: \sstitemlist{ \sstitem .NOT. ( A .EQ. B ) } to prevent the .NOT. operator from associating with the variable A. } \sstdiytopic{ Bitwise Operators }{ Bitwise operators are often useful when operating on raw data (e.g. from instruments), so they are provided for use in MathMap expressions. In this case, however, the values on which they operate are floating point values rather than the more usual pure integers. In order to produce results which match the pure integer case, the operands are regarded as fixed point binary numbers (i.e. with the binary equivalent of a decimal point) with negative numbers represented using twos-complement notation. For integer values, the resulting bit pattern corresponds to that of the equivalent signed integer (digits to the right of the point being zero). Operations on the bits representing the fractional part are also possible, however. The following bitwise operators are available: \sstitemlist{ \sstitem X1 $>$$>$ X2: Rightward bit shift. The integer value of X2 is taken (rounding towards zero) and the bits representing X1 are then shifted this number of places to the right (or to the left if the number of places is negative). This is equivalent to dividing X1 by the corresponding power of 2. \sstitem X1 $<$$<$ X2: Leftward bit shift. The integer value of X2 is taken (rounding towards zero), and the bits representing X1 are then shifted this number of places to the left (or to the right if the number of places is negative). This is equivalent to multiplying X1 by the corresponding power of 2. \sstitem X1 \& X2: Bitwise AND between the bits of X1 and those of X2 (equivalent to a logical AND applied at each bit position in turn). \sstitem X1 $|$ X2: Bitwise OR between the bits of X1 and those of X2 (equivalent to a logical OR applied at each bit position in turn). \sstitem X1 $\wedge$ X2: Bitwise exclusive OR (XOR) between the bits of X1 and those of X2 (equivalent to a logical XOR applied at each bit position in turn). } Note that no bit inversion operator is provided. This is because inverting the bits of a twos-complement fixed point binary number is equivalent to simply negating it. This differs from the pure integer case because bits to the right of the binary point are also inverted. To invert only those bits to the left of the binary point, use a bitwise exclusive OR with the value -1 (i.e. X$\wedge$-1). } \sstdiytopic{ Functions }{ The following functions are available: \sstitemlist{ \sstitem ABS(X): Absolute value of X (sign removal), same as FABS(X). \sstitem ACOS(X): Inverse cosine of X, in radians. \sstitem ACOSD(X): Inverse cosine of X, in degrees. \sstitem ACOSH(X): Inverse hyperbolic cosine of X. \sstitem ACOTH(X): Inverse hyperbolic cotangent of X. \sstitem ACSCH(X): Inverse hyperbolic cosecant of X. \sstitem AINT(X): Integer part of X (round towards zero), same as INT(X). \sstitem ASECH(X): Inverse hyperbolic secant of X. \sstitem ASIN(X): Inverse sine of X, in radians. \sstitem ASIND(X): Inverse sine of X, in degrees. \sstitem ASINH(X): Inverse hyperbolic sine of X. \sstitem ATAN(X): Inverse tangent of X, in radians. \sstitem ATAND(X): Inverse tangent of X, in degrees. \sstitem ATANH(X): Inverse hyperbolic tangent of X. \sstitem ATAN2(X1, X2): Inverse tangent of X1/X2, in radians. \sstitem ATAN2D(X1, X2): Inverse tangent of X1/X2, in degrees. \sstitem CEIL(X): Smallest integer value not less then X (round towards plus infinity). \sstitem COS(X): Cosine of X in radians. \sstitem COSD(X): Cosine of X in degrees. \sstitem COSH(X): Hyperbolic cosine of X. \sstitem COTH(X): Hyperbolic cotangent of X. \sstitem CSCH(X): Hyperbolic cosecant of X. \sstitem DIM(X1, X2): Returns X1-X2 if X1 is greater than X2, otherwise 0. \sstitem EXP(X): Exponential function of X. \sstitem FABS(X): Absolute value of X (sign removal), same as ABS(X). \sstitem FLOOR(X): Largest integer not greater than X (round towards minus infinity). \sstitem FMOD(X1, X2): Remainder when X1 is divided by X2, same as MOD(X1, X2). \sstitem GAUSS(X1, X2): Random sample from a Gaussian distribution with mean X1 and standard deviation X2. \sstitem INT(X): Integer part of X (round towards zero), same as AINT(X). \sstitem ISBAD(X): Returns 1 if X has the $<$bad$>$ value (AST\_\_BAD), otherwise 0. \sstitem LOG(X): Natural logarithm of X. \sstitem LOG10(X): Logarithm of X to base 10. \sstitem MAX(X1, X2, ...): Maximum of two or more values. \sstitem MIN(X1, X2, ...): Minimum of two or more values. \sstitem MOD(X1, X2): Remainder when X1 is divided by X2, same as FMOD(X1, X2). \sstitem NINT(X): Nearest integer to X (round to nearest). \sstitem POISSON(X): Random integer-valued sample from a Poisson distribution with mean X. \sstitem POW(X1, X2): X1 raised to the power of X2. \sstitem QIF(x1, x2, x3): Returns X2 if X1 is true, and X3 otherwise. \sstitem RAND(X1, X2): Random sample from a uniform distribution in the range X1 to X2 inclusive. \sstitem SECH(X): Hyperbolic secant of X. \sstitem SIGN(X1, X2): Absolute value of X1 with the sign of X2 (transfer of sign). \sstitem SIN(X): Sine of X in radians. \sstitem SINC(X): Sinc function of X [= SIN(X)/X]. \sstitem SIND(X): Sine of X in degrees. \sstitem SINH(X): Hyperbolic sine of X. \sstitem SQR(X): Square of X (= X$*$X). \sstitem SQRT(X): Square root of X. \sstitem TAN(X): Tangent of X in radians. \sstitem TAND(X): Tangent of X in degrees. \sstitem TANH(X): Hyperbolic tangent of X. } } \sstdiytopic{ Symbolic Constants }{ The following symbolic constants are available (the enclosing \texttt{"} $<$$>$\texttt{"} brackets must be included): \sstitemlist{ \sstitem $<$bad$>$: The \texttt{"} bad\texttt{"} value (AST\_\_BAD) used to flag missing data. Note that you cannot usefully compare values with this constant because the result is always $<$bad$>$. The ISBAD() function should be used instead. \sstitem $<$dig$>$: Number of decimal digits of precision available in a floating point (double precision) value. \sstitem $<$e$>$: \htmlref{Base}{Base} of natural logarithms. \sstitem $<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is distinguishable from unity. \sstitem $<$mant\_dig$>$: The number of base $<$radix$>$ digits stored in the mantissa of a floating point (double precision) value. \sstitem $<$max$>$: Maximum representable floating point (double precision) value. \sstitem $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power can be represented as a floating point (double precision) value. \sstitem $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that power minus 1 can be represented as a floating point (double precision) value. \sstitem $<$min$>$: Smallest positive number which can be represented as a normalised floating point (double precision) value. \sstitem $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double precision) value. \sstitem $<$min\_exp$>$: Minimum negative integer such that $<$radix$>$ raised to that power minus 1 can be represented as a normalised floating point (double precision) value. \sstitem $<$pi$>$: Ratio of the circumference of a circle to its diameter. \sstitem $<$radix$>$: The radix (number base) used to represent the mantissa of floating point (double precision) values. \sstitem $<$rounds$>$: The mode used for rounding floating point results after addition. Possible values include: -1 (indeterminate), 0 (toward zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus infinity). Other values indicate machine-dependent behaviour. } } \sstdiytopic{ Evaluation Precedence and Associativity }{ Items appearing in expressions are evaluated in the following order (highest precedence first): \sstitemlist{ \sstitem Constants and variables \sstitem Function arguments and parenthesised expressions \sstitem Function invocations \sstitem Unary $+$ - ! .not. \sstitem $*$$*$ \sstitem $*$ / \sstitem $+$ - \sstitem $<$$<$ $>$$>$ \sstitem $<$ .lt. $<$= .le. $>$ .gt. $>$= .ge. \sstitem == .eq. != .ne. \sstitem \& \sstitem $\wedge$ \sstitem $|$ \sstitem \&\& .and. \sstitem $\wedge$$\wedge$ \sstitem $|$$|$ .or \sstitem .eqv. .neqv. .xor. } All operators associate from left-to-right, except for unary $+$, unary -, !, .not. and $*$$*$ which associate from right-to-left. } } \sstroutine{ AST\_MATRIXMAP }{ Create a MatrixMap }{ \sstdescription{ This function creates a new \htmlref{MatrixMap}{MatrixMap} and optionally initialises its attributes. A MatrixMap is a form of \htmlref{Mapping}{Mapping} which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed. } \sstinvocation{ RESULT = AST\_MATRIXMAP( NIN, NOUT, FORM, MATRIX, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NIN = INTEGER (Given) }{ The number of input coordinates, which determines the number of columns in the matrix. } \sstsubsection{ NOUT = INTEGER (Given) }{ The number of output coordinates, which determines the number of rows in the matrix. } \sstsubsection{ FORM = INTEGER (Given) }{ An integer which indicates the form in which the matrix elements will be supplied. A value of zero indicates that a full NOUT x NIN matrix of values will be supplied via the MATRIX argument (below). In this case, the elements should be given in row order (the elements of the first row, followed by the elements of the second row, etc.). A value of 1 indicates that only the diagonal elements of the matrix will be supplied, and that all others should be zero. In this case, the elements of MATRIX should contain only the diagonal elements, stored consecutively. A value of 2 indicates that a \texttt{"} unit\texttt{"} matrix is required, whose diagonal elements are set to unity (with all other elements zero). In this case, the MATRIX argument is not used. } \sstsubsection{ MATRIX( $*$ ) = DOUBLE PRECISION (Given) }{ The array of matrix elements to be used, stored according to the value of FORM. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new MatrixMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_MATRIXMAP = INTEGER }{ A pointer to the new MatrixMap. } } \sstnotes{ \sstitemlist{ \sstitem In general, a MatrixMap\texttt{'} s forward transformation will always be available (as indicated by its \htmlref{TranForward}{TranForward} attribute), but its inverse transformation (\htmlref{TranInverse}{TranInverse} attribute) will only be available if the associated matrix is square and non-singular. \sstitem As an exception to this, the inverse transformation is always available if a unit or diagonal matrix is specified. In this case, if the matrix is not square, one or more of the input coordinate values may not be recoverable from a set of output coordinates. Any coordinates affected in this way will simply be set to the value zero. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_MIRRORVARIANTS }{ Make the current Frame mirror the variant Mappings in another Frame }{ \sstdescription{ This routine indicates that all access to the \htmlref{Variant}{Variant} attribute of the current \htmlref{Frame}{Frame} should should be forwarded to some other nominated Frame in the \htmlref{FrameSet}{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 \htmlref{Mapping}{Mapping} using either the pre-existing Frame or the new Frame. } \sstinvocation{ CALL AST\_MIRRORVARIANTS( THIS, IFRAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 \htmlref{Nframe}{Nframe} attribute). If AST\_\_NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this routine is disabled. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to the \htmlref{AST\_ADDVARIANT}{AST\_ADDVARIANT} routine will cause an error to be reported if the current Frame is mirroring another Frame. \sstitem A value of AST\_\_BASE may be given for the IFRAME argument to specify the base Frame. \sstitem Any variant Mappings explicitly added to the current Frame using AST\_ADDVARIANT will be ignored if the current Frame is mirroring another Frame. } } } \sstroutine{ AST\_NEGATE }{ Negate the area represented by a Region }{ \sstdescription{ This function negates the area represented by a \htmlref{Region}{Region}. That is, points which were previously inside the region will then be outside, and points which were outside will be inside. This is acomplished by toggling the state of the \htmlref{Negated}{Negated} attribute for the supplied region. } \sstinvocation{ CALL AST\_NEGATE( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_NORM }{ Normalise a set of Frame coordinates }{ \sstdescription{ This routine normalises a set of \htmlref{Frame}{Frame} coordinate values which might be unsuitable for display (e.g. may lie outside the expected range) into a set of acceptable values suitable for display. } \sstinvocation{ CALL AST\_NORM( THIS, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ VALUE( $*$ ) = DOUBLE PRECISION (Given and Returned) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). Initially, this should contain a set of coordinate values representing a point in the space which the Frame describes. If these values lie outside the expected range for the Frame, they will be replaced with more acceptable (normalised) values. Otherwise, they will be returned unchanged. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem For some classes of Frame, whose coordinate values are not constrained, this function will never modify the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as zero to 2$*$pi. \sstitem The \htmlref{NormMap}{NormMap} class is a \htmlref{Mapping}{Mapping} which can be used to normalise a set of points using the AST\_NORM routine of a specified Frame. \sstitem It is intended to be possible to put any set of coordinates into a form suitable for display by using this function to normalise them, followed by appropriate formatting (using \htmlref{AST\_FORMAT}{AST\_FORMAT}). } } } \sstroutine{ AST\_NORMMAP }{ Create a NormMap }{ \sstdescription{ This function creates a new \htmlref{NormMap}{NormMap} and optionally initialises its attributes. A NormMap is a \htmlref{Mapping}{Mapping} which normalises coordinate values using the \htmlref{AST\_NORM}{AST\_NORM} routine of the supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap are both equal to the number of axes in the supplied Frame. The forward and inverse transformation of a NormMap are both defined but are identical (that is, they do not form a real inverse pair in that the inverse transformation does not undo the normalisation, instead it reapplies it). However, the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} function will replace neighbouring pairs of forward and inverse NormMaps by a single \htmlref{UnitMap}{UnitMap}. } \sstinvocation{ RESULT = AST\_NORMMAP( FRAME, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame which is to be used to normalise the supplied axis values. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new NormMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_NORMMAP = INTEGER }{ A pointer to the new NormMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_NULLREGION }{ Create a NullRegion }{ \sstdescription{ This function creates a new \htmlref{NullRegion}{NullRegion} and optionally initialises its attributes. A NullRegion is a \htmlref{Region}{Region} with no bounds. If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion represents a Region containing no points. If the Negated attribute of a NullRegion is true, the NullRegion represents an infinite Region containing all points within the coordinate system. } \sstinvocation{ RESULT = AST\_NULLREGION( FRAME, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the \htmlref{Frame}{Frame} in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with positions in the supplied Frame. The uncertainty in any point in the Frame is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created NullRegion. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty of zero is used. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new NullRegion. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_NULLREGION = INTEGER }{ A pointer to the new NullRegion. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_OFFSET }{ Calculate an offset along a geodesic curve }{ \sstdescription{ This routine finds the \htmlref{Frame}{Frame} coordinate values of a point which is offset a specified distance along the geodesic curve between two other points. For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions. } \sstinvocation{ CALL AST\_OFFSET( THIS, POINT1, POINT2, OFFSET, POINT3, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ POINT1( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the point marking the start of the geodesic curve. } \sstsubsection{ POINT2( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis. This should contain the coordinates of the point marking the end of the geodesic curve. } \sstsubsection{ OFFSET = DOUBLE PRECISION }{ The required offset from the first point along the geodesic curve. If this is positive, it will be towards the second point. If it is negative, it will be in the opposite direction. This offset need not imply a position lying between the two points given, as the curve will be extrapolated if necessary. } \sstsubsection{ POINT3( $*$ ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Frame axis in which the coordinates of the required point will be returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this routine is the path of shortest distance between two points, as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value. \sstitem \texttt{"} Bad\texttt{"} 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. } } } \sstroutine{ AST\_OFFSET2 }{ Calculate an offset along a geodesic curve in a 2D Frame }{ \sstdescription{ This routine finds the \htmlref{Frame}{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. } \sstinvocation{ RESULT = AST\_OFFSET2( THIS, POINT1, ANGLE, OFFSET, POINT2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ POINT1( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the point marking the start of the geodesic curve. } \sstsubsection{ ANGLE = DOUBLE PRECISION (Given) }{ The angle (in radians) from the positive direction of the second axis, to the direction of the required position, as seen from the starting position. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1. } \sstsubsection{ OFFSET = DOUBLE PRECISION }{ The required offset from the first point along the geodesic curve. If this is positive, it will be in the direction of the given angle. If it is negative, it will be in the opposite direction. } \sstsubsection{ POINT2( $*$ ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Frame axis in which the coordinates of the required point will be returned. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_OFFSET2 = DOUBLE PRECISION }{ The direction of the geodesic curve at the end point. That is, the angle (in radians) between the positive direction of the second axis and the continuation of the geodesic curve at the requested end point. Positive rotation is in the sense of rotation from the positive direction of axis 2 to the positive direction of axis 1. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this routine is the path of shortest distance between two points, as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function. \sstitem An error will be reported if the Frame is not 2-dimensional. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value. } } } \sstroutine{ AST\_OUTLINE$<$X$>$ }{ Create a new Polygon outling values in a 2D data grid }{ \sstdescription{ This is a set of functions that create a \htmlref{Polygon}{Polygon} enclosing a single contiguous set of pixels that have a specified value within a gridded 2-dimensional data array (e.g. an image). A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter STARPIX. The MAXERR and MAXVERT parameters can be used to control how accurately the returned Polygon represents the required region in the data array. The number of vertices in the returned Polygon will be the minimum needed to achieve the required accuracy. You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST\_OUTLINE$<$X$>$ are procesing data with type REAL, you should use the function AST\_OUTLINER (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstinvocation{ RESULT = AST\_OUTLINE$<$X$>$( VALUE, OPER, ARRAY, LBND, UBND, MAXERR, MAXVERT, INSIDE, STARPIX, STATUS ) } \sstarguments{ \sstsubsection{ VALUE = $<$Xtype$>$ (Given) }{ A data value that specifies the pixels to be outlined. } \sstsubsection{ OPER = INTEGER (Given) }{ Indicates how the VALUE parameter is used to select the outlined pixels. It can have any of the following values: \sstitemlist{ \sstitem AST\_\_LT: outline pixels with value less than VALUE. \sstitem AST\_\_LE: outline pixels with value less than or equal to VALUE. \sstitem AST\_\_EQ: outline pixels with value equal to VALUE. \sstitem AST\_\_NE: outline pixels with value not equal to VALUE. \sstitem AST\_\_GE: outline pixels with value greater than or equal to VALUE. \sstitem AST\_\_GT: outline pixels with value greater than VALUE. } } \sstsubsection{ ARRAY( $*$ ) = $<$Xtype$>$ (Given) }{ A 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_OUTLINER, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ LBND( 2 ) = INTEGER (Given) }{ An array containing the pixel index of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND( 2) = INTEGER (Given) }{ An array containing the pixel index of the last pixel in the input grid along each dimension. Note that LBND and UBND together define the shape and size of the input pixel grid, its extent along a particular (J\texttt{'} th) dimension being UBND(J)-LBND(J)$+$1 pixels. For FITS images, the LBND values will be 1 and the UBND values will be equal to the NAXISi header values. Other data systems, such as the Starlink NDF system, allow an arbitrary pixel origin to be used (i.e. LBND is not necessarily 1). These bounds also define the input grid\texttt{'} s floating point coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter STARPIX. } \sstsubsection{ MAXERR = DOUBLE PRECISION (Given) }{ Together with MAXVERT, this determines how accurately the returned Polygon represents the required region of the data array. It gives the target discrepancy between the returned Polygon and the accurate outline in the data array, expressed as a number of pixels. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals MAXVERT, or the largest discrepancy between the accurate outline and the returned Polygon is greater than MAXERR. If MAXERR is zero or less, its value is ignored and the returned Polygon will have the number of vertices specified by MAXVERT. } \sstsubsection{ MAXVERT = INTEGER (Given) }{ Together with MAXERR, this determines how accurately the returned Polygon represents the required region of the data array. It gives the maximum allowed number of vertices in the returned Polygon. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals MAXVERT, or the largest discrepancy between the accurate outline and the returned Polygon is greater than MAXERR. If MAXVERT is less than 3, its value is ignored and the number of vertices in the returned Polygon will be the minimum needed to ensure that the discrepancy between the accurate outline and the returned Polygon is less than MAXERR. } \sstsubsection{ INSIDE( 2 ) = INTEGER (Given) }{ An array containing the pixel indices of a pixel known to be inside the required region. This is needed because the supplied data array may contain several disjoint areas of pixels that satisfy the criterion specified by VALUE and OPER. In such cases, the area described by the returned Polygon will be the one that contains the pixel specified by INSIDE. If the specified pixel is outside the bounds given by LBND and UBND, or has a value that does not meet the criterion specified by VALUE and OPER, then this function will search for a suitable pixel. The search starts at the central pixel and proceeds in a spiral manner until a pixel is found that meets the specified crierion. } \sstsubsection{ STARPIX = LOGICAL (Given) }{ A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If .TRUE., the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If .FALSE., the definition of pixel coordinate used by other AST functions such as AST\_RESAMPLE, AST\_MASK, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_OUTLINE$<$X$>$ = INTEGER }{ A pointer to the required Polygon. } } \sstnotes{ \sstitemlist{ \sstitem This function proceeds by first finding a very accurate polygon, and then removing insignificant vertices from this fine polygon using \htmlref{AST\_DOWNSIZE}{AST\_DOWNSIZE}. \sstitem The returned Polygon is the outer boundary of the contiguous set of pixels that includes ths specified \texttt{"} inside\texttt{"} point, and satisfy the specified value requirement. This set of pixels may potentially include \texttt{"} holes\texttt{"} where the pixel values fail to meet the specified value requirement. Such holes will be ignored by this function. \sstitem AST\_\_NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name AST\_OUTLINE$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem UI: INTEGER (treated as unsigned) \sstitem S: INTEGER$*$2 (short integer) \sstitem US: INTEGER$*$2 (short integer, treated as unsigned) \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_OUTLINED would be used to process DOUBLE PRECISION data, while AST\_OUTLINES would be used to process short integer data (stored in an INTEGER$*$2 array), etc. For compatibility with other Starlink facilities, the codes W and UW are provided as synonyms for S and US respectively (but only in the Fortran interface to AST). } } \sstroutine{ AST\_OVERLAP }{ Test if two regions overlap each other }{ \sstdescription{ This function returns an integer value indicating if the two supplied Regions overlap. The two Regions are converted to a commnon coordinate system before performing the check. If this conversion is not possible (for instance because the two Regions represent areas in different domains), then the check cannot be performed and a zero value is returned to indicate this. } \sstinvocation{ RESULT = AST\_OVERLAP( THIS, THAT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the first \htmlref{Region}{Region}. } \sstsubsection{ THAT = INTEGER (Given) }{ Pointer to the second Region. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_OVERLAP = INTEGER }{ A value indicating if there is any overlap between the two Regions. Possible values are: 0 - The check could not be performed because the second Region could not be mapped into the coordinate system of the first Region. 1 - There is no overlap between the two Regions. 2 - The first Region is completely inside the second Region. 3 - The second Region is completely inside the first Region. 4 - There is partial overlap between the two Regions. 5 - The Regions are identical to within their uncertainties. 6 - The second Region is the exact negation of the first Region to within their uncertainties. } } \sstnotes{ \sstitemlist{ \sstitem The returned values 5 and 6 do not check the value of the \htmlref{Closed}{Closed} attribute in the two Regions. \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ AST\_PARAMETERNAME }{ Get the name of the global parameter at a given index within the Table }{ \sstdescription{ This function returns a string holding the name of the global parameter with the given index within the \htmlref{Table}{Table}. This function is intended primarily as a means of iterating round all the parameters in a Table. For this purpose, the number of parameters in the Table is given by the \htmlref{Nparameter}{Nparameter} attribute of the Table. This function could then be called in a loop, with the index value going from one to Nparameter. Note, the index associated with a parameter decreases monotonically with the age of the parameter: the oldest Parameter in the Table will have index one, and the Parameter added most recently to the Table will have the largest index. } \sstinvocation{ RESULT = AST\_PARAMETERNAME( THIS, INDEX, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ INDEX = INTEGER (Given) }{ The index into the list of parameters. The first parameter has index one, and the last has index \texttt{"} Nparameter\texttt{"} . } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PARAMETERNAME = CHARACTER $*$ ( AST\_\_SZCHR ) }{ The upper case parameter name. } } \sstnotes{ \sstitemlist{ \sstitem A blank string will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PCDMAP }{ Create a PcdMap }{ \sstdescription{ This function creates a new \htmlref{PcdMap}{PcdMap} and optionally initialises its attributes. A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. This can take the form either of pincushion or barrel distortion, and is characterized by a single distortion coefficient. A PcdMap is specified by giving this distortion coefficient and the coordinates of the centre of the radial distortion. The forward transformation of a PcdMap applies the distortion: RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) where R is the undistorted radial distance from the distortion centre (specified by attribute PcdCen), RD is the radial distance from the same centre in the presence of distortion, and C is the distortion coefficient (given by attribute \htmlref{Disco}{Disco}). The inverse transformation of a PcdMap removes the distortion produced by the forward transformation. The expression used to derive R from RD is an approximate inverse of the expression above, obtained from two iterations of the Newton-Raphson method. The mismatch between the forward and inverse expressions is negligible for astrometric applications (to reach 1 milliarcsec at the edge of the Anglo-Australian Telescope triplet or a Schmidt field would require field diameters of 2.4 and 42 degrees respectively). If a PcdMap is inverted (e.g. using \htmlref{AST\_INVERT}{AST\_INVERT}) then the roles of the forward and inverse transformations are reversed; the forward transformation will remove the distortion, and the inverse transformation will apply it. } \sstinvocation{ RESULT = AST\_PCDMAP( DISCO, PCDCEN, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ DISCO = DOUBLE PRECISION (Given) }{ The distortion coefficient. Negative values give barrel distortion, positive values give pincushion distortion, and zero gives no distortion. } \sstsubsection{ PCDCEN( 2 ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of the centre of the distortion. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new PcdMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PCDMAP = INTEGER }{ A pointer to the new PcdMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_PERMAXES }{ Permute the axis order in a Frame }{ \sstdescription{ This routine permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur. } \sstinvocation{ CALL AST\_PERMAXES( THIS, PERM, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ PERM( $*$ ) = INTEGER (Given) }{ An array with one element for each axis of the Frame (\htmlref{Naxes}{Naxes} attribute). This should list the axes in their new order, using the original axis numbering (which starts at 1 for the first axis). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Only genuine permutations of the axis order are permitted, so each axis must be referenced exactly once in the PERM array. \sstitem If successive axis permutations are applied to a Frame, then the effects are cumulative. } } } \sstroutine{ AST\_PERMMAP }{ Create a PermMap }{ \sstdescription{ This function creates a new \htmlref{PermMap}{PermMap} and optionally initialises its attributes. A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output. In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones. } \sstinvocation{ RESULT = AST\_PERMMAP( NIN, INPERM, NOUT, OUTPERM, CONSTANT, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NIN = INTEGER (Given) }{ The number of input coordinates. } \sstsubsection{ INPERM = INTEGER( NIN ) (Given) }{ An array which, for each input coordinate, should contain the number of the output coordinate whose value is to be used (note that this array therefore defines the inverse coordinate transformation). Coordinates are numbered starting from 1. For details of additional special values that may be used in this array, see the description of the CONSTANT argument. } \sstsubsection{ NOUT = INTEGER (Given) }{ The number of output coordinates. } \sstsubsection{ OUTPERM = INTEGER( NOUT ) (Given) }{ An array which, for each output coordinate, should contain the number of the input coordinate whose value is to be used (note that this array therefore defines the forward coordinate transformation). Coordinates are numbered starting from 1. For details of additional special values that may be used in this array, see the description of the CONSTANT argument. } \sstsubsection{ CONSTANT = DOUBLE PRECISION( $*$ ) (Given) }{ An array containing values which may be assigned to input and/or output coordinates instead of deriving them from other coordinate values. If either of the INPERM or OUTPERM arrays contains a negative value, it is used to address this CONSTANT array (such that -1 addresses the first element, -2 addresses the second element, etc.) and the value obtained is used as the corresponding coordinate value. Care should be taken to ensure that locations lying outside the extent of this array are not accidentally addressed. The array is not used if the INPERM and OUTPERM arrays do not contain negative values. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new PermMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PERMMAP = INTEGER }{ A pointer to the new PermMap. } } \sstnotes{ \sstitemlist{ \sstitem If either of the INPERM or OUTPERM arrays contains a zero value (or a positive value which does not identify a valid output/input coordinate, as appropriate), then the value AST\_\_BAD is assigned as the new coordinate value. \sstitem This function does not attempt to ensure that the forward and inverse transformations performed by the PermMap are self-consistent in any way. You are therefore free to supply coordinate permutation arrays that achieve whatever effect is desired. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PICKAXES }{ Create a new Frame by picking axes from an existing one }{ \sstdescription{ This function creates a new \htmlref{Frame}{Frame} whose axes are copied from an existing Frame along with other Frame attributes, such as its \htmlref{Title}{Title}. Any number (zero or more) of the original Frame\texttt{'} s axes may be copied, in any order, and additional axes with default attributes may also be included in the new Frame. A \htmlref{Mapping}{Mapping} that converts between the coordinate systems described by the two Frames will also be returned. } \sstinvocation{ RESULT = AST\_PICKAXES( THIS, NAXES, AXES, MAP, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the original Frame. } \sstsubsection{ NAXES = INTEGER (Given) }{ The number of axes required in the new Frame. } \sstsubsection{ AXES( NAXES ) = INTEGER (Given) }{ An array which lists the axes to be copied. These should be given in the order required in the new Frame, using the axis numbering in the original Frame (which starts at 1 for the first axis). Axes may be selected in any order, but each may only be used once. If additional (default) axes are also to be included, the corresponding elements of this array should be set to zero. } \sstsubsection{ MAP = INTEGER (Returned) }{ A pointer to a new Mapping. This will be a \htmlref{PermMap}{PermMap} (or a \htmlref{UnitMap}{UnitMap} as a special case) that describes the axis permutation that has taken place between the original and new Frames. The Mapping\texttt{'} s forward transformation will convert coordinates from the original Frame into the new one, and vice versa. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. The class of Frame returned may differ from that of the original Frame, depending on which axes are selected. For example, if a single axis is picked from a \htmlref{SkyFrame}{SkyFrame} (which must always have two axes) then the resulting Frame cannot be a valid SkyFrame, so will revert to the parent class (Frame) instead. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ Using this function on a FrameSet is identical to using it on the current Frame in the FrameSet. The returned Frame will not be a FrameSet. } \sstsubsection{ \htmlref{Region}{Region} }{ If this function is used on a Region, an attempt is made to retain the bounds information on the selected axes. If succesful, the returned Frame will be a Region of some class. Otherwise, the returned Frame is obtained by calling this function on the Frame represented by the supplied Region (the returned Frame will then not be a Region). In order to be succesful, the selected axes in the Region must be independent of the others. For instance, a \htmlref{Box}{Box} can be split in this way but a \htmlref{Circle}{Circle} cannot. Another requirement for success is that no default axes are added (that is, the AXES array must not contain any zero values. } } \sstreturnedvalue{ \sstsubsection{ AST\_PICKAXES = INTEGER }{ A pointer to the new Frame. } } \sstnotes{ \sstitemlist{ \sstitem The new Frame will contain a \texttt{"} deep\texttt{"} copy (c.f. \htmlref{AST\_COPY}{AST\_COPY}) of all the data selected from the original Frame. Modifying any aspect of the new Frame will therefore not affect the original one. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PLOT }{ Create a Plot }{ \sstdescription{ This function creates a new \htmlref{Plot}{Plot} and optionally initialises its attributes. A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created. The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect). Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see \htmlref{AST\_CURVE}{AST\_CURVE}). A Plot also provides facilities for drawing markers or symbols (\htmlref{AST\_MARK}{AST\_MARK}), text (\htmlref{AST\_TEXT}{AST\_TEXT}) and grid lines (\htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}). It is also possible to draw curvilinear axes with optional coordinate grids (\htmlref{AST\_GRID}{AST\_GRID}). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these routines. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot, using its \htmlref{Current}{Current} attribute. You may also set up clipping (see \htmlref{AST\_CLIP}{AST\_CLIP}) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in. Like any FrameSet, a Plot may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a Mapping, a Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST\_\_BAD). } \sstinvocation{ RESULT = AST\_PLOT( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ Pointer to a Frame describing the physical coordinate system in which to plot. A pointer to a FrameSet may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below). If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default 2-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. } \sstsubsection{ GRAPHBOX( 4 ) = REAL (Given) }{ An array giving the position and extent of the plotting area (on the plotting surface of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system. The first pair of values should give the coordinates of the bottom left corner of the plotting area and the second pair should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. } \sstsubsection{ BASEBOX( 4 ) = DOUBLE PRECISION (Given) }{ An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting area, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PLOT }{ A pointer to the new Plot. } } \sstnotes{ \sstitemlist{ \sstitem The base Frame of the returned Plot will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot. The choice of base Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a Plot has been created (although you could use this as a way of moving the plotting area around on the plotting surface). \sstitem If a Frame is supplied (via the FRAME pointer), then it becomes the current Frame of the new Plot and is given a Frame index of 2. \sstitem If a FrameSet is supplied (via the FRAME pointer), then all the Frames within this FrameSet become part of the new Plot (where their Frame indices are increased by 1), with the FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot. \sstitem If a null Object pointer (AST\_\_NULL) is supplied (via the FRAME pointer), then the returned Plot will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot \htmlref{Title}{Title} and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates. \sstitem An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 2-dimensional. \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PLOT3D }{ Create a Plot3D }{ \sstdescription{ This function creates a new \htmlref{Plot3D}{Plot3D} and optionally initialises its attributes. A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities for producing 3D graphical output. } \sstinvocation{ RESULT = AST\_PLOT3D( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ Pointer to a \htmlref{Frame}{Frame} describing the physical coordinate system in which to plot. A pointer to a \htmlref{FrameSet}{FrameSet} may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below). If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default 3-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. } \sstsubsection{ GRAPHBOX( 6 ) = REAL (Given) }{ An array giving the position and extent of the plotting volume (within the plotting space of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system. The first triple of values should give the coordinates of the bottom left corner of the plotting volume and the second triple should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. } \sstsubsection{ BASEBOX( 6 ) = DOUBLE PRECISION (Given) }{ An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting volume, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot3D. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PLOT3D = INTEGER }{ A pointer to the new Plot3D. } } \sstnotes{ \sstitemlist{ \sstitem The base Frame of the returned Plot3D will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot3D. The choice of base Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a Plot3D has been created (although you could use this as a way of moving the plotting area around on the plotting surface). \sstitem If a Frame is supplied (via the FRAME pointer), then it becomes the current Frame of the new Plot3D and is given a Frame index of 2. \sstitem If a FrameSet is supplied (via the FRAME pointer), then all the Frames within this FrameSet become part of the new Plot3D (where their Frame indices are increased by 1), with the FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot3D. \sstitem At least one of the three axes of the current Frame must be independent of the other two current Frame axes. \sstitem If a null Object pointer (AST\_\_NULL) is supplied (via the FRAME pointer), then the returned Plot3D will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot3D \htmlref{Title}{Title} and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates. \sstitem An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 3-dimensional. \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_POINTLIST }{ Create a PointList }{ \sstdescription{ This function creates a new \htmlref{PointList}{PointList} object and optionally initialises its attributes. A PointList object is a specialised type of \htmlref{Region}{Region} which represents a collection of points in a coordinate \htmlref{Frame}{Frame}. } \sstinvocation{ RESULT = AST\_POINTLIST( FRAME, NPNT, COORD, DIM, POINTS, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ NPNT = INTEGER (Given) }{ The number of points in the Region. } \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinates being supplied for each point. This must equal the number of axes in the supplied Frame, given by its \htmlref{Naxes}{Naxes} attribute. } \sstsubsection{ DIM = INTEGER (Given) }{ The number of elements along the first dimension of the POINTS array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than NPNT. } \sstsubsection{ POINTS( DIM, NCOORD ) = DOUBLE PRECISION (Given) }{ A 2-dimensional array giving the physical coordinates of the points. These should be stored such that the value of coordinate number COORD for point number PNT is found in element IN(PNT,COORD). } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with each point in the PointList being created. The uncertainty at any point in the PointList is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the bounding box of the PointList being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new PointList. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_POINTLIST = INTEGER }{ A pointer to the new PointList. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_POLYCURVE }{ Draw a series of connected geodesic curves }{ \sstdescription{ This routine joins a series of points specified in the physical coordinate system of a \htmlref{Plot}{Plot} by drawing a sequence of geodesic curves. It is equivalent to making repeated calls to the \htmlref{AST\_CURVE}{AST\_CURVE} routine (q.v.), except that AST\_POLYCURVE will generally be more efficient when drawing many geodesic curves end-to-end. A typical application of this might be in drawing contour lines. As with AST\_CURVE, full account is taken of the \htmlref{Mapping}{Mapping} between physical and graphical coordinate systems. This includes any discontinuities and clipping established using \htmlref{AST\_CLIP}{AST\_CLIP}. } \sstinvocation{ CALL AST\_POLYCURVE( THIS, NPOINT, NCOORD, INDIM, IN, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ NPOINT = INTEGER (Given) }{ The number of points between which geodesic curves are to be drawn. } \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinates being supplied for each point (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given by its \htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ INDIM = INTEGER (Given) }{ The number of elements along the first dimension of the IN array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than NPOINT. } \sstsubsection{ IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given) }{ A 2-dimensional array giving the physical coordinates of the points which are to be joined in sequence by geodesic curves. These should be stored such that the value of coordinate number COORD for input point number POINT is found in element IN(POINT,COORD). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn on either side of any point which has any coordinate equal to the value AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_POLYGON }{ Create a Polygon }{ \sstdescription{ This function creates a new \htmlref{Polygon}{Polygon} object and optionally initialises its attributes. The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon. Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied). } \sstinvocation{ RESULT = AST\_POLYGON( FRAME, NPNT, DIM, POINTS, UNC, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME = INTEGER (Given) }{ A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the \htmlref{Region}{Region}. } \sstsubsection{ NPNT = INTEGER (Given) }{ The number of points in the Region. } \sstsubsection{ DIM = INTEGER (Given) }{ The number of elements along the first dimension of the POINTS array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than NPNT. } \sstsubsection{ POINTS( DIM, 2 ) = DOUBLE PRECISION (Given) }{ A 2-dimensional array giving the physical coordinates of the vertices. These should be stored such that the value of coordinate number COORD for point number PNT is found in element IN(PNT,COORD). } \sstsubsection{ UNC = INTEGER (Given) }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Polygon being created. The uncertainty in any point on the boundary of the Polygon is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Polygon. Alternatively, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Polygon being created. The uncertainty Region has two uses: 1) when the \htmlref{AST\_OVERLAP}{AST\_OVERLAP} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Polygon. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_POLYGON = INTEGER }{ A pointer to the new Polygon. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_POLYMAP }{ Create a PolyMap }{ \sstdescription{ This function creates a new \htmlref{PolyMap}{PolyMap} and optionally initialises its attributes. A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, an iterative method can be used to evaluate the inverse based only on the forward transformation. } \sstinvocation{ RESULT = AST\_POLYMAP( NIN, NOUT, NCOEFF\_F, COEFF\_F, NCOEFF\_I, COEFF\_I, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NIN = INTEGER (Given) }{ The number of input coordinates. } \sstsubsection{ NOUT = INTEGER (Given) }{ The number of output coordinates. } \sstsubsection{ NCOEFF\_F = INTEGER (Given) }{ The number of non-zero coefficients necessary to define the forward transformation of the PolyMap. If zero is supplied, the forward transformation will be undefined. } \sstsubsection{ COEFF\_F( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing \texttt{"} NCOEFF\_F$*$( 2 $+$ NIN )\texttt{"} elements. Each group of \texttt{"} 2 $+$ NIN\texttt{"} adjacent elements describe a single coefficient of the forward transformation. Within each such group, the first element is the coefficient value; the next element is the integer index of the PolyMap output which uses the coefficient within its defining polynomial (the first output has index 1); the remaining elements of the group give the integer powers to use with each input coordinate value (powers must not be negative, and floating point values are rounded to the nearest integer). For instance, if the PolyMap has 3 inputs and 2 outputs, each group consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"} describes a coefficient with value 1.2 which is used within the definition of output 2. The output value is incremented by the product of the coefficient value, the value of input coordinate 1 raised to the power 1, and the value of input coordinate 2 raised to the power 3. Input coordinate 3 is not used since its power is specified as zero. As another example, the group \texttt{"} (-1.0, 1.0, 0.0, 0.0, 0.0 )\texttt{"} describes adds a constant value -1.0 onto output 1 (it is a constant value since the power for every input axis is given as zero). Each final output coordinate value is the sum of the \texttt{"} NCOEFF\_F\texttt{"} terms described by the \texttt{"} NCOEFF\_F\texttt{"} groups within the supplied array. } \sstsubsection{ NCOEFF\_I = INTEGER (Given) }{ The number of non-zero coefficients necessary to define the inverse transformation of the PolyMap. If zero is supplied, the inverse transformation will be undefined. } \sstsubsection{ COEFF\_I( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing \texttt{"} NCOEFF\_I$*$( 2 $+$ NOUT )\texttt{"} elements. Each group of \texttt{"} 2 $+$ NOUT\texttt{"} adjacent elements describe a single coefficient of the inverse transformation, using the same schame as \texttt{"} COEFF\_F\texttt{"} , except that \texttt{"} inputs\texttt{"} and \texttt{"} outputs\texttt{"} are transposed. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new PolyMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_POLYMAP = INTEGER }{ A pointer to the new PolyMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_POLYTRAN }{ Fit a PolyMap inverse or forward transformation }{ \sstdescription{ This function creates a new \htmlref{PolyMap}{PolyMap} which is a copy of the supplied PolyMap, in which a specified transformation (forward or inverse) has been replaced by a new polynomial transformation. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values. This method can only be used on (1-input,1-output) or (2-input,2-output) PolyMaps. The transformation to create is specified by the FORWARD parameter. In what follows \texttt{"} X\texttt{"} refers to the inputs of the PolyMap, and \texttt{"} Y\texttt{"} to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials, P\_f or P\_i: Y=P\_f(X) for the forward transformation and X=P\_i(Y) for the inverse transformation. The FORWARD parameter specifies the transformation to be replaced. If it is is .TRUE., a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap\texttt{'} s output space. The coefficients of the required forward polynomial, Y=P\_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P\_f(X). If FORWARD is .FALSE. (probably the most likely case), a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap\texttt{'} s input space. The coefficients of the required inverse polynomial, X=P\_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P\_i(Y). This fitting process is performed repeatedly with increasing polynomial orders (starting with linear) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than MAXACC. If it is not, an error is reported. } \sstinvocation{ RESULT = AST\_POLYTRAN( THIS, FORWARD, ACC, MAXACC, MAXORDER, LBND, UBND, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the original \htmlref{Mapping}{Mapping}. } \sstsubsection{ FORWARD = LOGICAL (Given) }{ If .TRUE., the forward PolyMap transformation is replaced. Otherwise the inverse transformation is replaced. } \sstsubsection{ ACC = DOUBLE (Given) }{ The target accuracy, expressed as a geodesic distance within the PolyMap\texttt{'} s input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). } \sstsubsection{ MAXACC = DOUBLE (Given) }{ The maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap\texttt{'} s input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). } \sstsubsection{ MAXORDER = INTEGER (Given) }{ The maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial. Note, cross terms with total powers greater than or equal to MAXORDER are not inlcuded in the fit. So the maximum number of terms in each of the fitted polynomials is MAXORDER$*$(MAXORDER$+$1)/2. } \sstsubsection{ LBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array holding the lower bounds of a rectangular region within the PolyMap\texttt{'} s input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap\texttt{'} s \htmlref{Nin}{Nin} or \htmlref{Nout}{Nout} attribute, depending on FORWARD. } \sstsubsection{ UBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array holding the upper bounds of a rectangular region within the PolyMap\texttt{'} s input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap\texttt{'} s Nin or Nout attribute, depending on FORWARD. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_POLYTRAN = INTEGER }{ A pointer to the new PolyMap. AST\_\_NULL will be returned if the fit fails to achieve the accuracy specified by MAXACC, but no error will be reported. } } \sstnotes{ \sstitemlist{ \sstitem This function can only be used on 1D or 2D PolyMaps which have the same number of inputs and outputs. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PRISM }{ Create a Prism }{ \sstdescription{ This function creates a new \htmlref{Prism}{Prism} and optionally initialises its attributes. A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region into one or more orthogonal dimensions (specified by another Region). If the Region to be extruded has N axes, and the Region defining the extrusion has M axes, then the resulting Prism will have (M$+$N) axes. A point is inside the Prism if the first N axis values correspond to a point inside the Region being extruded, and the remaining M axis values correspond to a point inside the Region defining the extrusion. As an example, a cylinder can be represented by extruding an existing \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the Interval would have a single axis and would specify the upper and lower limits of the cylinder along its length. } \sstinvocation{ RESULT = AST\_PRISM( REGION1, REGION2, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION1 = INTEGER (Given) }{ Pointer to the Region to be extruded. } \sstsubsection{ REGION2 = INTEGER (Given) }{ Pointer to the Region defining the extent of the extrusion. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Prism. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_PRISM = INTEGER }{ A pointer to the new Prism. } } \sstnotes{ \sstitemlist{ \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the Prism. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_PURGEROWS }{ Remove all empty rows from a table }{ \sstdescription{ This function removes all empty rows from the \htmlref{Table}{Table}, renaming the key associated with each table cell accordingly. } \sstinvocation{ CALL AST\_PURGEROWS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_PURGEWCS }{ Delete all cards in the FitsChan describing WCS information }{ \sstdescription{ This routine deletes all cards in a \htmlref{FitsChan}{FitsChan} that relate to any of the recognised WCS encodings. On exit, the current card is the first remaining card in the FitsChan. } \sstinvocation{ CALL AST\_PURGEWCS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_PUTCARDS }{ Store a set of FITS header cards in a FitsChan }{ \sstdescription{ This routine stores a set of FITS header cards in a \htmlref{FitsChan}{FitsChan}. The cards are supplied concatenated together into a single character string. Any existing cards in the FitsChan are removed before the new cards are added. The FitsChan is \texttt{"} re-wound\texttt{"} on exit by clearing its \htmlref{Card}{Card} attribute. This means that a subsequent invocation of \htmlref{AST\_READ}{AST\_READ} can be made immediately without the need to re-wind the FitsChan first. } \sstinvocation{ CALL AST\_PUTCARDS( THIS, CARDS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ CARDS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the FITS cards to be stored. Each individual card should occupy 80 characters in this string, and there should be no delimiters, new lines, etc, between adjacent cards. The final card may be less than 80 characters long. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if the supplied string contains any cards which cannot be interpreted. } } } \sstroutine{ AST\_PUTCOLUMNDATA }{ Store new data values for all rows of a column }{ \sstdescription{ This routine copies data values from a supplied buffer into a named column. The first element in the buffer becomes the first element in the first row of the column. If the buffer does not completely fill the column, then any trailing rows are filled with null values. } \sstinvocation{ CALL AST\_PUTCOLUMNDATA( THIS, COLUMN, CLEN, SIZE, COLDATA, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{FitsTable}{FitsTable}. } \sstsubsection{ COLUMN = CHARACTER $*$ ( $*$ ) (Given) }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ CLEN = INTEGER (Given) }{ If the column holds character strings, then this must be set to the length of each fixed length string in the supplied array. This is often determined by the appropriate TFORMn keyword in the binary table header. The supplied value is ignored if the column does not hold character data. } \sstsubsection{ SIZE = INTEGER (Given) }{ The size of the COLDATA array, in bytes. This should be an integer multiple of the number of bytes needed to hold the full vector value stored in a single cell of the column. An error is reported if this is not the case. } \sstsubsection{ COLDATA( $*$ ) = BYTE (Given) }{ An area of memory holding the data to copy into the column. The values should be stored in row order. If the column holds non-scalar values, the elements of each value should be stored in \texttt{"} Fortran\texttt{"} order. No data type conversion is performed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_PUTFITS }{ Store a FITS header card in a FitsChan }{ \sstdescription{ This routine stores a FITS header card in a \htmlref{FitsChan}{FitsChan}. The card is either inserted before the current card (identified by the \htmlref{Card}{Card} attribute), or over-writes the current card, as required. } \sstinvocation{ CALL AST\_PUTFITS( THIS, CARD, OVERWRITE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ CARD = CHARACTER $*$ ( 80 ) (Given) }{ A character string string containing the FITS card to be stored. No more than 80 characters will be used from this string. } \sstsubsection{ OVERWRITE = LOGICAL (Given) }{ If this value is .FALSE., the new card is inserted in front of the current card in the FitsChan (as identified by the initial value of the Card attribute). If it is .TRUE., the new card replaces the current card. In either case, the Card attribute is then incremented by one so that it subsequently identifies the card following the one stored. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the Card attribute initially points at the \texttt{"} end-of-file\texttt{"} (i.e. exceeds the number of cards in the FitsChan), then the new card is appended as the last card in the FitsChan. \sstitem An error will result if the supplied string cannot be interpreted as a FITS header card. } } } \sstroutine{ AST\_PUTLINE }{ Store a text line read by a Channel source routine }{ \sstdescription{ This routine should only be used when implementing a routine which will be passed as the SOURCE argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL}. It should be used to pass back (to the AST library) each line of text read from the external data source. One such line should be passed back in this way for each invocation of the source routine. } \sstinvocation{ CALL AST\_PUTLINE( LINE, L, STATUS ) } \sstarguments{ \sstsubsection{ LINE = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the line of input text which has been read. } \sstsubsection{ L = INTEGER (Given) }{ The number of characters in the input line, which may be zero. If there is no more input available (e.g. an end of file has been reached), this value should be set negative and this will terminate the read operation on the \htmlref{Channel}{Channel}. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This routine is only available in the Fortran interface to the AST library. } } } \sstroutine{ AST\_PUTTABLE }{ Store a single FitsTable in a FitsChan }{ \sstdescription{ This routine allows a representation of a single FITS binary table to be stored in a \htmlref{FitsChan}{FitsChan}. For instance, this may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling \htmlref{AST\_READ}{AST\_READ}, the \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE} routine provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. } \sstinvocation{ CALL AST\_PUTTABLE( THIS, TABLE, EXTNAM, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ TABLE = INTEGER (Given) }{ Pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. If a FitsTable with the associated extension name already exists in the FitsChan, it is replaced with the new one. A deep copy of the FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTable will have no effect on the behaviour of the FitsChan. } \sstsubsection{ EXTNAM = CHARACTER $*$ ( $*$ ) (Given) }{ The name of the FITS extension associated with the table. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Tables stored in the FitsChan may be retrieved using \htmlref{AST\_GETTABLES}{AST\_GETTABLES}. \sstitem The \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES} method can add multiple FitsTables in a single call. } } } \sstroutine{ AST\_PUTTABLEHEADER }{ Store new FITS headers in a FitsTable }{ \sstdescription{ This routine stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing headers are first deleted. } \sstinvocation{ CALL AST\_PUTTABLEHEADER( THIS, HEADER, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsTable. } \sstsubsection{ HEADER = INTEGER (Given) }{ Pointer to a \htmlref{FitsChan}{FitsChan} holding the headers for the FitsTable. A deep copy of the supplied FitsChan is stored in the FitsTable, replacing the current FitsChan in the Fitstable. Keywords that are fixed either by the properties of the \htmlref{Table}{Table}, or by the FITS standard, are removed from the copy (see \texttt{"} Notes:\texttt{"} below). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The attributes of the supplied FitsChan, together with any source and sink functions associated with the FitsChan, are copied to the FitsTable. \sstitem Values for the following keywords are generated automatically by the FitsTable (any values for these keywords in the supplied FitsChan will be ignored): \texttt{"} XTENSION\texttt{"} , \texttt{"} BITPIX\texttt{"} , \texttt{"} NAXIS\texttt{"} , \texttt{"} NAXIS1\texttt{"} , \texttt{"} NAXIS2\texttt{"} , \texttt{"} PCOUNT\texttt{"} , \texttt{"} GCOUNT\texttt{"} , \texttt{"} TFIELDS\texttt{"} , \texttt{"} TFORM\%d\texttt{"} , \texttt{"} TTYPE\%d\texttt{"} , \texttt{"} TNULL\%d\texttt{"} , \texttt{"} THEAP\texttt{"} , \texttt{"} TDIM\%d\texttt{"} . } } } \sstroutine{ AST\_PUTTABLES }{ Store one or more FitsTables in a FitsChan }{ \sstdescription{ This routine allows representations of one or more FITS binary tables to be stored in a \htmlref{FitsChan}{FitsChan}. For instance, these may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling \htmlref{AST\_READ}{AST\_READ}, the \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE} routine provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. } \sstinvocation{ CALL AST\_PUTTABLES( THIS, TABLES, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ TABLES = INTEGER (Given) }{ Pointer to a \htmlref{KeyMap}{KeyMap} holding the tables that are to be added to the FitsChan. Each entry should hold a scalar value which is a pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. Any unusable entries are ignored. The key associated with each entry should be the name of the FITS binary extension from which the table was read. If a FitsTable with the associated key already exists in the FitsChan, it is replaced with the new one. A deep copy of each usable FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTables will have no effect on the behaviour of the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Tables stored in the FitsChan may be retrieved using \htmlref{AST\_GETTABLES}{AST\_GETTABLES}. \sstitem The tables in the supplied KeyMap are added to any tables already in the FitsChan. \sstitem The \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE} method provides a simpler means of adding a single table to a FitsChan. } } } \sstroutine{ AST\_QUADAPPROX }{ Obtain a quadratic approximation to a 2D Mapping }{ \sstdescription{ This function returns the co-efficients of a quadratic fit to the supplied \htmlref{Mapping}{Mapping} over the input area specified by LBND and UBND. The Mapping must have 2 inputs, but may have any number of outputs. The i\texttt{'} th Mapping output is modelled as a quadratic function of the 2 inputs (x,y): output\_i = a\_i\_0 $+$ a\_i\_1$*$x $+$ a\_i\_2$*$y $+$ a\_i\_3$*$x$*$y $+$ a\_i\_4$*$x$*$x $+$ a\_i\_5$*$y$*$y The FIT array is returned holding the values of the co-efficients a\_0\_0, a\_0\_1, etc. } \sstinvocation{ RESULT = AST\_QUADAPPROX( THIS, LBND, UBND, NX, NY, FIT, RMS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping. } \sstsubsection{ LBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This box should specify the region over which the fit is to be performed. } \sstsubsection{ UBND( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing the upper bounds of the box specifying the region over which the fit is to be performed. } \sstsubsection{ NX = INTEGER (Given) }{ The number of points to place along the first Mapping input. The first point is at LBND( 1 ) and the last is at UBND( 1 ). If a value less than three is supplied a value of three will be used. } \sstsubsection{ NY = INTEGER (Given) }{ The number of points to place along the second Mapping input. The first point is at LBND( 2 ) and the last is at UBND( 2 ). If a value less than three is supplied a value of three will be used. } \sstsubsection{ FIT( $*$ ) = DOUBLE PRECISION (Returned) }{ An array in which to return the co-efficients of the quadratic approximation to the specified transformation. This array should have at least \texttt{"} 6$*$\htmlref{Nout}{Nout}\texttt{"} , elements. The first 6 elements hold the fit to the first Mapping output. The next 6 elements hold the fit to the second Mapping output, etc. So if the Mapping has 2 inputs and 2 outputs the quadratic approximation to the forward transformation is: X\_out = fit(1) $+$ fit(2)$*$X\_in $+$ fit(3)$*$Y\_in $+$ fit(4)$*$X\_in$*$Y\_in $+$ fit(5)$*$X\_in$*$X\_in $+$ fit(6)$*$Y\_in$*$Y\_in Y\_out = fit(7) $+$ fit(8)$*$X\_in $+$ fit(9)$*$Y\_in $+$ fit(10)$*$X\_in$*$Y\_in $+$ fit(11)$*$X\_in$*$X\_in $+$ fit(12)$*$Y\_in$*$Y\_in } \sstsubsection{ RMS = DOUBLE PRECISION (Returned) }{ The RMS residual between the fit and the Mapping, summed over all Mapping outputs. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_QUADAPPROX = LOGICAL }{ If a quadratic approximation was created, .TRUE is returned. Otherwise .FALSE. is returned and the fit co-efficients are set to AST\_\_BAD. } } \sstnotes{ \sstitemlist{ \sstitem This function fits the Mapping\texttt{'} s forward transformation. To fit the inverse transformation, the Mapping should be inverted using \htmlref{AST\_INVERT}{AST\_INVERT} before invoking this function. \sstitem A value of .FALSE. will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } } \sstroutine{ AST\_RATE }{ Calculate the rate of change of a Mapping output }{ \sstdescription{ This routine evaluates the rate of change of a specified output of the supplied \htmlref{Mapping}{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. This method produces good accuracy but can involve evaluating the Mapping 100 or more times. } \sstinvocation{ RESULT = AST\_RATE( THIS, AT, AX1, AX2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be applied. } \sstsubsection{ AT( $*$ ) = DOUBLE PRECISION (Given) }{ 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. } \sstsubsection{ AX1 = INTEGER (Given) }{ The index of the Mapping output for which the rate of change is to be found (output numbering starts at 1 for the first output). } \sstsubsection{ AX2 = INTEGER (Given) }{ The index of the Mapping input which is to be varied in order to find the rate of change (input numbering starts at 1 for the first input). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_RATE = DOUBLE PRECISION }{ 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. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ AST\_RATEMAP }{ Create a RateMap }{ \sstdescription{ This function creates a new \htmlref{RateMap}{RateMap} and optionally initialises its attributes. A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created). A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation. } \sstinvocation{ RESULT = AST\_RATEMAP( MAP, AX1, AX2, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ MAP = INTEGER (Given) }{ Pointer to the encapsulated Mapping. } \sstsubsection{ AX1 = INTEGER (Given) }{ Index of the output from the encapsulated Mapping for which the rate of change is required. This corresponds to the delta quantity forming the numerator of the required element of the Jacobian matrix. The first axis has index 1. } \sstsubsection{ AX2 = INTEGER (Given) }{ Index of the input to the encapsulated Mapping which is to be varied. This corresponds to the delta quantity forming the denominator of the required element of the Jacobian matrix. The first axis has index 1. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new RateMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_RATEMAP = INTEGER }{ A pointer to the new RateMap. } } \sstnotes{ \sstitemlist{ \sstitem The forward transformation of the encapsulated Mapping must be defined. \sstitem Note that the component Mappings supplied are not copied by AST\_RATEMAP (the new RateMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a RateMap containing a copy of its component Mappings is required, then a copy of the RateMap should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_READ }{ Read an Object from a Channel }{ \sstdescription{ This function reads the next \htmlref{Object}{Object} from a \htmlref{Channel}{Channel} and returns a pointer to the new Object. } \sstinvocation{ RESULT = AST\_READ( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Channel. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All successful use of AST\_READ on a FitsChan is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the FitsChan \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS} routine). An unsuccessful call of AST\_READ (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The AST Object returned by a successful use of AST\_READ on an StcsChan, will be either a \htmlref{Region}{Region} or a \htmlref{KeyMap}{KeyMap}, depending on the values of the \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} attributes. See the documentation for these attributes for further information. } } \sstreturnedvalue{ \sstsubsection{ AST\_READ = INTEGER }{ A pointer to the new Object. The class to which this will belong is determined by the input data, so is not known in advance. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned, without error, if the Channel contains no further Objects to be read. \sstitem A null Object pointer will also be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_READFITS }{ Read cards into a FitsChan from the source function }{ \sstdescription{ This routine reads cards from the source function that was specified when the \htmlref{FitsChan}{FitsChan} was created, and stores them in the FitsChan. This normally happens once-only, when the FitsChan is accessed for the first time. This routine provides a means of forcing a re-read of the external source, and may be useful if (say) new cards have been deposited into the external source. Any newcards read from the source are appended to the end of the current contents of the FitsChan. } \sstinvocation{ CALL AST\_READFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if no source function was specified when the FitsChan was created. \sstitem The \htmlref{SourceFile}{SourceFile} attribute is ignored by this routine. New cards are read from the source file whenever a new value is assigned to the SourceFile attribute. } } } \sstroutine{ AST\_REBIN$<$X$>$ }{ Rebin a region of a data grid }{ \sstdescription{ This is a set of functions for rebinning gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Rebinning may be restricted to a specified region of the input grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the rebined output data. Propagation of missing data (bad pixels) is supported. Note, if you will be rebining a sequence of input arrays and then co-adding them into a single array, the alternative \htmlref{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$} routines will in general be more efficient. You should use a rebinning function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST\_REBIN$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are rebinning data with type REAL, you should use the function AST\_REBINR (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). Rebinning of the grid of input data is performed by transforming the coordinates of the centre of each input grid element (or pixel) into the coordinate system of the output grid. The input pixel value is then divided up and assigned to the output pixels in the neighbourhood of the central output coordinates. A choice of schemes are provided for determining how each input pixel value is divided up between the output pixels. In general, each output pixel may be assigned values from more than one input pixel. All contributions to a given output pixel are summed to produce the final output pixel value. Output pixels can be set to the supplied bad value if they receive contributions from an insufficient number of input pixels. This is controlled by the WLIM argument. Input pixel coordinates are transformed into the coordinate system of the output grid using the forward transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping\texttt{'} s forward transformation as they are transferred from the input to the output grid. In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel. This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstinvocation{ CALL AST\_REBIN$<$X$>$( THIS, WLIM, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR, SPREAD, PARAMS, FLAGS, TOL, MAXPIX, BADVAL, NDIM\_OUT, LBND\_OUT, UBND\_OUT, LBND, UBND, OUT, OUT\_VAR, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to a Mapping, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of NDIM\_IN below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by NDIM\_OUT. } \sstsubsection{ WLIM = DOUBLE PRECISION (Given) }{ Gives the required number of input pixel values which must contribute to an output pixel in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied WLIM value, then the output pixel value is returned set to the supplied bad value. } \sstsubsection{ NDIM\_IN = INTEGER (Given) }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ LBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND\_IN and UBND\_IN together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND\_IN(J)-LBND\_IN(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ IN( $*$ ) = $<$Xtype$>$ (Given) }{ An array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_REBINR, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given) }{ An optional second array with the same size and type as the IN array. If the AST\_\_USEVAR flag is set via the FLAGS argument (below), this array should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the IN array. Estimates of the variance of the rebined output data will then be calculated. If the AST\_\_USEVAR flag is not set, no input variance estimates are required and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ SPREAD = INTEGER (Given) }{ This argument specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} section below. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST\_\_LINEAR). } \sstsubsection{ PARAMS( $*$ ) = DOUBLE PRECISION (Given) }{ An optional array which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} section below. If no additional parameters are required, this array is not used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ FLAGS = INTEGER (Given) }{ The sum of a set of flag values which may be used to provide additional control over the rebinning operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ TOL = DOUBLE PRECISION (Given) }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. } \sstsubsection{ MAXPIX = INTEGER (Given) }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed MAXPIX pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting TOL to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ BADVAL = $<$Xtype$>$ (Given) }{ This argument should have the same type as the elements of the IN array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the FLAGS argument, then this value is used to test for bad pixels in the IN (and IN\_VAR) array(s). In all cases, this value is also used to flag any output elements in the OUT (and OUT\_VAR) array(s) for which rebined values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). } \sstsubsection{ NDIM\_OUT = INTEGER (Given) }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ LBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that LBND\_OUT and UBND\_OUT together define the shape, size and coordinate system of the output grid in the same way as LBND\_IN and UBND\_IN define the shape, size and coordinate system of the input grid. } \sstsubsection{ LBND( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. } \sstsubsection{ UBND( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array. Note that LBND and UBND together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the LBND\_IN and UBND\_IN arrays). Regions of the input grid lying outside this region will not be used. } \sstsubsection{ OUT( $*$ ) = $<$Xtype$>$ (Returned) }{ An array, with one element for each pixel in the output grid, in which the rebined data values will be returned. The numerical type of this array should match that of the IN array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned) }{ An optional array with the same type and size as the OUT array. If the AST\_\_USEVAR flag is set via the FLAGS argument, this array will be used to return variance estimates for the rebined data values. The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the pixel spreading schemes employed. If the AST\_\_USEVAR flag is not set, no output variance estimates will be calculated and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name AST\_REBIN$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_REBIND would be used to process DOUBLE PRECISION data, while AST\_REBINI would be used to process integer data (stored in an INTEGER array), etc. Note that, unlike \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}, the AST\_REBIN$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. } \sstdiytopic{ Pixel Spreading Schemes }{ The pixel spreading scheme specifies the Point Spread Function (PSF) applied to each input pixel value as it is copied into the output array. It can be thought of as the inverse of the sub-pixel interpolation schemes used by the AST\_RESAMPLE$<$X$>$ group of functions. That is, in a sub-pixel interpolation scheme the kernel specifies the weight to assign to each input pixel when forming the weighted mean of the input pixels, whereas the kernel in a pixel spreading scheme specifies the fraction of the input data value which is to be assigned to each output pixel. As for interpolation, the choice of suitable pixel spreading scheme involves stricking a balance between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features but which often tend to introduce unwanted artifacts. See the AST\_RESAMPLE$<$X$>$ documentation for further discussion. The binning algorithm used has the ability to introduce artifacts not seen when using a resampling algorithm. Particularly, when viewing the output image at high contrast, systems of curves lines covering the entire image may be visible. These are caused by a beating effect between the input pixel positions and the output pixels position, and their nature and strength depend critically upon the nature of the Mapping and the spreading function being used. In general, the nearest neighbour spreading function demonstrates this effect more clearly than the other functions, and for this reason should be used with caution. The following values (defined in the AST\_PAR include file) may be assigned to the SPREAD parameter. See the AST\_RESAMPLE$<$X$>$ documentation for details of these schemes including the use of the FSPREAD and PARAMS arguments: \sstitemlist{ \sstitem AST\_\_NEAREST \sstitem AST\_\_LINEAR \sstitem AST\_\_SINC \sstitem AST\_\_SINCSINC \sstitem AST\_\_SINCCOS \sstitem AST\_\_SINCGAUSS \sstitem AST\_\_SOMBCOS } In addition, the following schemes can be used with AST\_REBIN$<$X$>$ but not with AST\_RESAMPLE$<$X$>$: \sstitemlist{ \sstitem AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant determined by the full-width at half-maximum (FWHM). The FWHM should be supplied in units of output pixels by means of the PARAMS(2) value and should be at least 0.1. The PARAMS(1) value should be used to specify at what point the Gaussian is truncated to zero. This should be given as a number of output pixels on either side of the central output point in each dimension (the nearest integer value is used). } } \sstdiytopic{ Control Flags }{ The following flags are defined in the AST\_PAR include file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the sum of their values via the FLAGS argument: \sstitemlist{ \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for BADVAL and propagated to the output array(s). If this flag is not set, all input values are treated literally and the BADVAL value is only used for flagging output array values. \sstitem AST\_\_USEVAR: Indicates that variance information should be processed in order to provide estimates of the statistical error associated with the rebined values. If this flag is not set, no variance processing will occur and the IN\_VAR and OUT\_VAR arrays will not be used. (Note that this flag is only available in the Fortran interface to AST.) } } \sstdiytopic{ Propagation of Missing Data }{ Instances of missing data (bad pixels) in the output grid are identified by occurrences of the BADVAL value in the OUT array. These are produced if the sum of the weights of the contributing input pixels is less than WLIM. An input pixel is considered bad (and is consequently ignored) if its data value is equal to BADVAL and the AST\_\_USEBAD flag is set via the FLAGS argument. In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the BADVAL value in the OUT\_VAR array for similar reasons. } } \sstroutine{ AST\_REBINSEQ$<$X$>$ }{ Rebin a region of a sequence of data grids }{ \sstdescription{ This set of routines is identical to \htmlref{AST\_REBIN$<$X$>$}{AST\_REBIN$<$X$>$} except that the rebinned input data is added into the supplied output arrays, rather than simply over-writing the contents of the output arrays. Thus, by calling this routine repeatedly, a sequence of input arrays can be rebinned and accumulated into a single output array, effectively forming a mosaic of the input data arrays. In addition, the weights associated with each output pixel are returned. The weight of an output pixel indicates the number of input pixels which have been accumulated in that output pixel. If the entire value of an input pixel is assigned to a single output pixel, then the weight of that output pixel is incremented by one. If some fraction of the value of an input pixel is assigned to an output pixel, then the weight of that output pixel is incremented by the fraction used. The start of a new sequence is indicated by specifying the AST\_\_REBININIT flag via the FLAGS argument. This causes the supplied arrays to be filled with zeros before the rebinned input data is added into them. Subsequenct invocations within the same sequence should omit the AST\_\_REBININIT flag. The last call in a sequence is indicated by specifying the AST\_\_REBINEND flag. Depending on which flags are supplied, this may cause the output data and variance arrays to be normalised before being returned. This normalisation consists of dividing the data array by the weights array, and can eliminate artifacts which may be introduced into the rebinned data as a consequence of aliasing between the input and output grids. This results in each output pixel value being the weighted mean of the input pixel values that fall in the neighbourhood of the output pixel (rather like \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}). Optionally, these normalised values can then be multiplied by a scaling factor to ensure that the total data sum in any small area is unchanged. This scaling factor is equivalent to the number of input pixel values that fall into each output pixel. In addition to normalisation of the output data values, any output variances are also appropriately normalised, and any output data values with weight less than WLIM are set to BADVAL. Output variances can be generated in two ways; by rebinning the supplied input variances with appropriate weights, or by finding the spread of input data values contributing to each output pixel (see the AST\_\_GENVAR and AST\_\_USEVAR flags). } \sstinvocation{ CALL AST\_REBINSEQ$<$X$>$( THIS, WLIM, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR, SPREAD, PARAMS, FLAGS, TOL, MAXPIX, BADVAL, NDIM\_OUT, LBND\_OUT, UBND\_OUT, LBND, UBND, OUT, OUT\_VAR, WEIGHTS, NUSED, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to a \htmlref{Mapping}{Mapping}, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of NDIM\_IN below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by NDIM\_OUT. } \sstsubsection{ WLIM = DOUBLE PRECISION (Given) }{ This value is only used if the AST\_\_REBINEND flag is specified via the FLAGS argument. It gives the required number of input pixel values which must contribute to an output pixel (i.e. the output pixel weight) in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied WLIM value, then the output pixel value is returned set to the supplied bad value. If the supplied value is less than 1.0E-10 then 1.0E-10 is used instead. } \sstsubsection{ NDIM\_IN = INTEGER (Given) }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ LBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND\_IN and UBND\_IN together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND\_IN(J)-LBND\_IN(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ IN( $*$ ) = $<$Xtype$>$ (Given) }{ An array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_REBINSEQR, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given) }{ An optional second array with the same size and type as the IN array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the IN array. If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no input variance estimates are required and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ SPREAD = INTEGER (Given) }{ This argument specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the AST\_REBIN$<$X$>$ routines. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST\_\_LINEAR). } \sstsubsection{ PARAMS( $*$ ) = DOUBLE PRECISION (Given) }{ An optional array which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the AST\_REBIN$<$X$>$ routines. If no additional parameters are required, this array is not used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ FLAGS = INTEGER (Given) }{ The sum of a set of flag values which may be used to provide additional control over the rebinning operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ TOL = DOUBLE PRECISION (Given) }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. } \sstsubsection{ MAXPIX = INTEGER (Given) }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed MAXPIX pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting TOL to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ BADVAL = $<$Xtype$>$ (Given) }{ This argument should have the same type as the elements of the IN array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the FLAGS argument, then this value is used to test for bad pixels in the IN (and IN\_VAR) array(s). In all cases, this value is also used to flag any output elements in the OUT (and OUT\_VAR) array(s) for which rebined values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). } \sstsubsection{ NDIM\_OUT = INTEGER (Given) }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ LBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that LBND\_OUT and UBND\_OUT together define the shape, size and coordinate system of the output grid in the same way as LBND\_IN and UBND\_IN define the shape, size and coordinate system of the input grid. } \sstsubsection{ LBND( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. } \sstsubsection{ UBND( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array. Note that LBND and UBND together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the LBND\_IN and UBND\_IN arrays). Regions of the input grid lying outside this region will not be used. } \sstsubsection{ OUT( $*$ ) = $<$Xtype$>$ (Given and Returned) }{ An array, with one element for each pixel in the output grid. The rebined data values will be added into the original contents of this array. The numerical type of this array should match that of the IN array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Given and Returned) }{ A array with the same type and size as the OUT array. This array will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set via the FLAGS argument, via the \texttt{"} flags\texttt{"} parameter, in which case variance estimates for the rebined data values will be added into the array. If neither the AST\_\_USEVAR flag nor the AST\_\_GENVAR flag is set, no output variance estimates will be calculated and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ WEIGHTS( $*$ ) = DOUBLE PRECISION (Given and Returned) }{ An array with one or two elements for each pixel in the output grid, depending on whether or not the AST\_\_GENVAR flag has been supplied via the FLAGS parameter. If AST\_\_GENVAR has not been specified then the array should have one element for each output pixel, and it will be used to accumulate the weight associated with each output pixel. If AST\_\_GENVAR has been specified then the array should have two elements for each output pixel. The first half of the array is again used to accumulate the weight associated with each output pixel, and the second half is used to accumulate the square of the weights. In each half, the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ NUSED = INTEGER$*$8 (Given and Returned) }{ The number of input data values that have been added into the output array so far. The supplied value is incremented on exit by the number of input values used. The value is initially set to zero if the AST\_\_REBININIT flag is set in FLAGS. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name AST\_REBINSEQ$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_REBIND would be used to process DOUBLE PRECISION data, while AST\_REBINI would be used to process integer data (stored in an INTEGER array), etc. Note that, unlike AST\_RESAMPLE$<$X$>$, the AST\_REBINSEQ$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. } \sstdiytopic{ Control Flags }{ The following flags are defined in the AST\_PAR include file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the sum of their values via the FLAGS argument: \sstitemlist{ \sstitem AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates that the supplied OUT, OUT\_VAR and WEIGHTS arrays should be filled with zeros (thus over-writing any supplied values) before adding the rebinned input data into them. This flag should be used when rebinning the first input array in a sequence. \sstitem AST\_\_REBINEND: Used to mark the last call in a sequence. It causes each value in the OUT and OUT\_VAR arrays to be divided by a normalisation factor before being returned. The normalisation factor for each output data value is just the corresponding value from the weights array. The normalisation factor for each output variance value is the square of the data value normalisation factor (see also AST\_\_CONSERVEFLUX). It also causes output data values to be set bad if the corresponding weight is less than the value supplied for argument WLIM. It also causes any temporary values stored in the output variance array (see flag AST\_\_GENVAR below) to be converted into usable variance values. Note, this flag is ignored if the AST\_\_NONORM flag is set. \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for BADVAL and propagated to the output array(s). If this flag is not set, all input values are treated literally and the BADVAL value is only used for flagging output array values. \sstitem AST\_\_USEVAR: Indicates that output variance estimates should be created by rebinning the supplied input variance estimates. An error will be reported if both this flag and the AST\_\_GENVAR flag are supplied. \sstitem AST\_\_GENVAR: Indicates that output variance estimates should be created based on the spread of input data values contributing to each output pixel. An error will be reported if both this flag and the AST\_\_USEVAR flag are supplied. If the AST\_\_GENVAR flag is specified, the supplied output variance array is first used as a work array to accumulate the temporary values needed to generate the output variances. When the sequence ends (as indicated by the AST\_\_REBINEND flag), the contents of the output variance array are converted into the required variance estimates. If the generation of such output variances is required, this flag should be used on every invocation of this routine within a sequence, and any supplied input variances will have no effect on the output variances (although input variances will still be used to weight the input data if the AST\_\_VARWGT flag is also supplied). The statistical meaning of these output varianes is determined by the presence or absence of the AST\_\_DISVAR flag (see below). \sstitem AST\_\_DISVAR: This flag is ignored unless the AST\_\_GENVAR flag has also been specified. It determines the statistical meaning of the generated output variances. If AST\_\_DISVAR is not specified, generated variances represent variances on the output mean values. If AST\_\_DISVAR is specified, the generated variances represent the variance of the distribution from which the input values were taken. Each output variance created with AST\_\_DISVAR will be larger than that created without AST\_\_DISVAR by a factor equal to the number of input samples that contribute to the output sample. \sstitem AST\_\_VARWGT: Indicates that the input data should be weighted by the reciprocal of the input variances. Otherwise, all input data are given equal weight. If this flag is specified, the calculation of the output variances (if any) is modified to take account of the varying weights assigned to the input data values. \sstitem AST\_\_NONORM: If the simple unnormalised sum of all input data falling in each output pixel is required, then this flag should be set on each call in the sequence and the AST\_\_REBINEND should not be used on the last call. In this case WEIGHTS and NUSED are ignored. This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR or AST\_\_VARWGT flag. \sstitem AST\_\_CONSERVEFLUX: Indicates that the normalized output pixel values generated by the AST\_\_REBINEND flag should be scaled in such a way as to preserve the total data value in a feature on the sky. Without this flag, each normalised output pixel value represents a weighted mean of the input data values around the corresponding input position. (i.e. AST\_REBINSEQ$<$F$>$ behaves similarly to AST\_RESAMPLE$<$X$>$). This (i.e. AST\_REBINSEQ$<$F$>$ behaves similarly to AST\_RESAMPLE$<$X$>$). This is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST\_\_CONSERVEFLUX flag could be of use. It causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size. } This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the TOL argument is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the TOL argument until the difference between adjacent panels is sufficiently small to be insignificant. This flag should normally be supplied on each invocation of AST\_REBINSEQ$<$X$>$ within a given sequence. Note, this flag cannot be used in conjunction with the AST\_\_NOSCALE flag (an error will be reported if both flags are specified). } \sstdiytopic{ Propagation of Missing Data }{ Instances of missing data (bad pixels) in the output grid are identified by occurrences of the BADVAL value in the OUT array. These are only produced if the AST\_\_REBINEND flag is specified and a pixel has zero weight. An input pixel is considered bad (and is consequently ignored) if its data value is equal to BADVAL and the AST\_\_USEBAD flag is set via the FLAGS argument. In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the BADVAL value in the OUT\_VAR array for similar reasons. } } \sstroutine{ AST\_REMAPFRAME }{ Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet }{ \sstdescription{ This routine modifies the relationship (i.e. \htmlref{Mapping}{Mapping}) between a specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{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 FrameSet using this routine. } \sstinvocation{ CALL AST\_REMAPFRAME( THIS, IFRAME, MAP, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 \htmlref{Nframe}{Nframe} attribute). } \sstsubsection{ 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. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the IFRAME argument to specify the base Frame or the current Frame respectively. \sstitem The relationship between the selected Frame and any other Frame within the FrameSet will be modified by this routine, but the relationship between all other Frames in the FrameSet remains unchanged. \sstitem The number of input coordinate values accepted by the Mapping (its \htmlref{Nin}{Nin} attribute) and the number of output coordinate values generated (its \htmlref{Nout}{Nout} attribute) must be equal and must match the number of axes in the Frame being modified. \sstitem If a simple change of axis order is required, then the \htmlref{AST\_PERMAXES}{AST\_PERMAXES} routine may provide a more straightforward method of making the required changes to the FrameSet. \sstitem This routine cannot be used to change the number of Frame axes. To achieve this, a new Frame must be added to the FrameSet (\htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}) and the original one removed if necessary (\htmlref{AST\_REMOVEFRAME}{AST\_REMOVEFRAME}). \sstitem 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 \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). } } } \sstroutine{ AST\_REMOVECOLUMN }{ Remove a column from a table }{ \sstdescription{ This function removes a specified column from the supplied table. The routine returns without action if the named column does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstinvocation{ CALL AST\_REMOVECOLUMN( THIS, NAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The column name. Trailing spaces are ignored (all other spaces are significant). Case is significant. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_REMOVEFRAME }{ Remove a Frame from a FrameSet }{ \sstdescription{ This routine removes a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet}. All other Frames in the FrameSet have their indices re-numbered from one (if necessary), but are otherwise unchanged. } \sstinvocation{ CALL AST\_REMOVEFRAME( THIS, IFRAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FrameSet. } \sstsubsection{ 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 \htmlref{Nframe}{Nframe} attribute). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem 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. \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the IFRAME argument to specify the base Frame or the current Frame respectively. \sstitem If a FrameSet\texttt{'} s base or current Frame is removed, the \htmlref{Base}{Base} or \htmlref{Current}{Current} attribute (respectively) of the FrameSet will have its value cleared, so that another Frame will then assume its role by default. \sstitem 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. } } } \sstroutine{ AST\_REMOVEPARAMETER }{ Remove a global parameter from a table }{ \sstdescription{ This function removes a specified global parameter from the supplied table. The routine returns without action if the named parameter does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstinvocation{ CALL AST\_REMOVEPARAMETER( THIS, NAME, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The parameter name. Trailing spaces are ignored (all other spaces are significant). Case is significant. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_REMOVEREGIONS }{ Remove any Regions from a Mapping }{ \sstdescription{ This function searches the suppliedMapping (which may be a compound \htmlref{Mapping}{Mapping} such as a \htmlref{CmpMap}{CmpMap}) for any component Mappings that are instances of the AST \htmlref{Region}{Region} class. It then creates a new Mapping from which all Regions have been removed. If a Region cannot simply be removed (for instance, if it is a component of a parallel CmpMap), then it is replaced with an equivalent \htmlref{UnitMap}{UnitMap} in the returned Mapping. } \sstinvocation{ RESULT = AST\_REMOVEREGIONS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the original Mapping. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ If the supplied Mapping is a CmpFrame, any component Frames that are instances of the Region class are replaced by the equivalent \htmlref{Frame}{Frame}. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which Regions have been removed from all the inter-Frame Mappings, and any Frames which are instances of the Region class are repalced by the equivalent Frame. } \sstsubsection{ Mapping }{ This function applies to all Mappings. } \sstsubsection{ Region }{ If the supplied Mapping is a Region, the returned Mapping will be the equivalent Frame. } } \sstreturnedvalue{ \sstsubsection{ AST\_REMOVEREGIONS = INTEGER }{ A new pointer to the (possibly modified) Mapping. } } \sstnotes{ \sstitemlist{ \sstitem This function can safely be applied even to Mappings which contain no Regions. If no Regions are found, it behaves exactly like \htmlref{AST\_CLONE}{AST\_CLONE} and returns a pointer to the original Mapping. \sstitem The Mapping returned by this function may not be independent of the original (even if some Regions were removed), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_REMOVEROW }{ Remove a row from a table }{ \sstdescription{ This function removes a specified row from the supplied table. The routine returns without action if the row does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstinvocation{ CALL AST\_REMOVEROW( THIS, INDEX, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Table. } \sstsubsection{ INDEX = INTEGER (Given) }{ The index of the row to be removed. The first row has index 1. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_REMOVETABLES }{ Remove one or more tables from a FitsChan }{ \sstdescription{ This routine removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error is reported if any the tables do not exist). } \sstinvocation{ CALL AST\_REMOVETABLES( THIS, KEY, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ KEY = CHARACTER $*$ ( $*$ ) (Given) }{ The key indicating which tables to exist. A single key or a comma-separated list of keys can be supplied. If a blank string is supplied, all tables are removed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_RESAMPLE$<$X$>$ }{ Resample a region of a data grid }{ \sstdescription{ This is a set of functions for resampling gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Resampling may be restricted to a specified region of the output grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the resampled output data. Propagation of missing data (bad pixels) is supported. You should use a resampling function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST\_RESAMPLE$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are resampling data with type REAL, you should use the function AST\_RESAMPLER (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). Resampling of the grid of input data is performed by transforming the coordinates of the centre of each output grid element (or pixel) into the coordinate system of the input grid. Since the resulting coordinates will not, in general, coincide with the centre of an input pixel, sub-pixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of sub-pixel interpolation schemes is provided, but you may also implement your own. This algorithm samples the input data value, it does not integrate it. Thus total data value in the input image will not, in general, be conserved. However, an option is provided (see the \texttt{"} Control Flags\texttt{"} section below) which can produce approximate flux conservation by scaling the output values using the ratio of the output pixel size to the input pixel size. However, if accurate flux conservation is important to you, consder using the \htmlref{AST\_REBIN$<$X$>$}{AST\_REBIN$<$X$>$} or \htmlref{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$} family of routines instead. Output pixel coordinates are transformed into the coordinate system of the input grid using the inverse transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping\texttt{'} s forward transformation as they are transferred from the input to the output grid (although the Mapping\texttt{'} s forward transformation is not explicitly used). In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel. This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the output grid which is being used. If this proves to be insufficiently accurate, the output region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstinvocation{ RESULT = AST\_RESAMPLE$<$X$>$( THIS, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR, INTERP, FINTERP, PARAMS, FLAGS, TOL, MAXPIX, BADVAL, NDIM\_OUT, LBND\_OUT, UBND\_OUT, LBND, UBND, OUT, OUT\_VAR, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to a Mapping, whose inverse transformation will be used to transform the coordinates of pixels in the output grid into the coordinate system of the input grid. This yields the positions which are used to obtain resampled values by sub-pixel interpolation within the input grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of NDIM\_IN below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by NDIM\_OUT. } \sstsubsection{ NDIM\_IN = INTEGER (Given) }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ LBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND\_IN and UBND\_IN together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND\_IN(J)-LBND\_IN(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ IN( $*$ ) = $<$Xtype$>$ (Given) }{ An array, with one element for each pixel in the input grid, containing the input data to be resampled. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST\_RESAMPLER, the type of each array element should be REAL). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given) }{ An optional second array with the same size and type as the IN array. If the AST\_\_USEVAR flag is set via the FLAGS argument (below), this array should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the IN array. Estimates of the variance of the resampled output data will then be calculated. If the AST\_\_USEVAR flag is not set, no input variance estimates are required and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ INTERP = INTEGER (Given) }{ This argument specifies the scheme to be used for sub-pixel interpolation within the input grid. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below. If a value of zero is supplied, then the default linear interpolation scheme is used (equivalent to supplying the value AST\_\_LINEAR). Alternatively, you may supply a value which indicates that you will provide your own routine to perform sub-pixel interpolation by means of the FINTERP argument. Again, see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below for details. } \sstsubsection{ FINTERP = SUBROUTINE (Given) }{ If the value given for the INTERP argument indicates that you will provide your own routine for sub-pixel interpolation, then the name of that routine should be given here (the name should also appear in a Fortran EXTERNAL statement in the routine which invokes AST\_RESAMPLE$<$X$>$). For details of the interface which the routine should have (several are possible, depending on the value of INTERP), see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below. If the INTERP argument has any other value, corresponding to one of the pre-defined interpolation schemes, then this routine will not be used and you may supply the null routine AST\_NULL here (note only one underscore). No EXTERNAL statement is required for this routine, so long as the AST\_PAR include file has been used. } \sstsubsection{ PARAMS( $*$ ) = DOUBLE PRECISION (Given) }{ An optional array which should contain any additional parameter values required by the sub-pixel interpolation scheme. If such parameters are required, this will be noted in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below (you may also use this array to pass values to your own interpolation routine). If no additional parameters are required, this array is not used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ FLAGS = INTEGER (Given) }{ The sum of a set of flag values which may be used to provide additional control over the resampling operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ TOL = DOUBLE PRECISION (Given) }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the input grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. } \sstsubsection{ MAXPIX = INTEGER (Given) }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the output grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire output region. If a smaller value is used, the output region will first be divided into sub-regions whose size does not exceed MAXPIX pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting TOL to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ BADVAL = $<$Xtype$>$ (Given) }{ This argument should have the same type as the elements of the IN array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the FLAGS argument, then this value is used to test for bad pixels in the IN (and IN\_VAR) array(s). Unless the AST\_\_NOBAD flag is set via the FLAGS argument, this value is also used to flag any output elements in the OUT (and OUT\_VAR) array(s) for which resampled values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). The AST\_RESAMPLE$<$X$>$ function return value indicates whether any such values have been produced. If the AST\_\_NOBAD flag is set. then output array elements for which no resampled value could be obtained are left set to the value they had on entry to this function. } \sstsubsection{ NDIM\_OUT = INTEGER (Given) }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ LBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that LBND\_OUT and UBND\_OUT together define the shape, size and coordinate system of the output grid in the same way as LBND\_IN and UBND\_IN define the shape, size and coordinate system of the input grid. } \sstsubsection{ LBND( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the first pixel in the region of the output grid for which a resampled value is to be calculated. } \sstsubsection{ UBND( NDIM\_OUT ) = INTEGER (Given) }{ An array containing the coordinates of the last pixel in the region of the output grid for which a resampled value is to be calculated. Note that LBND and UBND together define the shape and position of a (hyper-)rectangular region of the output grid for which resampled values should be produced. This region should lie wholly within the extent of the output grid (as defined by the LBND\_OUT and UBND\_OUT arrays). Regions of the output grid lying outside this region will not be modified. } \sstsubsection{ OUT( $*$ ) = $<$Xtype$>$ (Returned) }{ An array, with one element for each pixel in the output grid, into which the resampled data values will be returned. The numerical type of this array should match that of the IN array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. normal Fortran array storage order). } \sstsubsection{ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned) }{ An optional array with the same type and size as the OUT array. If the AST\_\_USEVAR flag is set via the FLAGS argument, this array will be used to return variance estimates for the resampled data values. The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the sub-pixel interpolation schemes employed. If the AST\_\_USEVAR flag is not set, no output variance estimates will be calculated and this array will not be used. A dummy (e.g. one-element) array may then be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_RESAMPLE$<$X$>$ = INTEGER }{ The number of output pixels for which no valid resampled value could be obtained. Thus, in the absence of any error, a returned value of zero indicates that all the required output pixels received valid resampled data values (and variances). See the BADVAL and FLAGS arguments. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate resampling function, you should replace $<$X$>$ in the generic function name AST\_RESAMPLE$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: DOUBLE PRECISION \sstitem R: REAL \sstitem I: INTEGER \sstitem UI: INTEGER (treated as unsigned) \sstitem S: INTEGER$*$2 (short integer) \sstitem US: INTEGER$*$2 (short integer, treated as unsigned) \sstitem B: BYTE (treated as signed) \sstitem UB: BYTE (treated as unsigned) } For example, AST\_RESAMPLED would be used to process DOUBLE PRECISION data, while AST\_RESAMPLES would be used to process short integer data (stored in an INTEGER$*$2 array), etc. For compatibility with other Starlink facilities, the codes W and UW are provided as synonyms for S and US respectively (but only in the Fortran interface to AST). } \sstdiytopic{ Sub-Pixel Interpolation Schemes }{ There is no such thing as a perfect sub-pixel interpolation scheme and, in practice, all resampling will result in some degradation of gridded data. A range of schemes is therefore provided, from which you can choose the one which best suits your needs. In general, a balance must be struck between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features. The latter will often tend to introduce unwanted oscillations, typically visible as \texttt{"} ringing\texttt{"} around sharp features and edges, especially if the data are under-sampled (i.e. if the sharpest features are less than about two pixels across). In practice, a good interpolation scheme is likely to be a compromise and may exhibit some aspects of both these features. For under-sampled data, some interpolation schemes may appear to preserve data resolution because they transform single input pixels into single output pixels, rather than spreading their data between several output pixels. While this may look better cosmetically, it can result in a geometrical shift of sharp features in the data. You should beware of this if you plan to use such features (e.g.) for image alignment. The following are two easy-to-use sub-pixel interpolation schemes which are generally applicable. They are selected by supplying the appropriate value (defined in the AST\_PAR include file) via the INTERP argument. In these cases, the FINTERP and PARAMS arguments are not used: \sstitemlist{ \sstitem AST\_\_NEAREST: This is the simplest possible scheme, in which the value of the input pixel with the nearest centre to the interpolation point is used. This is very quick to execute and will preserve single-pixel features in the data, but may displace them by up to half their width along each dimension. It often gives a good cosmetic result, so is useful for quick-look processing, but is unsuitable if accurate geometrical transformation is required. \sstitem AST\_\_LINEAR: This is the default scheme, which uses linear interpolation between the nearest neighbouring pixels in the input grid (there are two neighbours in one dimension, four neighbours in two dimensions, eight in three dimensions, etc.). It is superior to the nearest-pixel scheme (above) in not displacing features in the data, yet it still executes fairly rapidly. It is generally a safe choice if you do not have any particular reason to favour another scheme, since it cannot introduce oscillations. However, it does introduce some spatial smoothing which varies according to the distance of the interpolation point from the neighbouring pixels. This can degrade the shape of sharp features in the data in a position-dependent way. It may also show in the output variance grid (if used) as a pattern of stripes or fringes. } An alternative set of interpolation schemes is based on forming the interpolated value from the weighted sum of a set of surrounding pixel values (not necessarily just the nearest neighbours). This approach has its origins in the theory of digital filtering, in which interpolated values are obtained by conceptually passing the sampled data (represented by a grid of delta functions) through a linear filter which implements a convolution. Because the convolution kernel is continuous, the convolution yields a continuous function which may then be evaluated at fractional pixel positions. The (possibly multi-dimensional) kernel is usually regarded as \texttt{"} separable\texttt{"} and formed from the product of a set of identical 1-dimensional kernel functions, evaluated along each dimension. Different interpolation schemes are then distinguished by the choice of this 1-dimensional interpolation kernel. The number of surrounding pixels which contribute to the result may also be varied. From a practical standpoint, it is useful to divide the weighted sum of pixel values by the sum of the weights when determining the interpolated value. Strictly, this means that a true convolution is no longer being performed. However, the distinction is rarely important in practice because (for slightly subtle reasons) the sum of weights is always approximately constant for good interpolation kernels. The advantage of this technique, which is used here, is that it can easily accommodate missing data and tends to minimise unwanted oscillations at the edges of the data grid. In the following schemes, which are based on a 1-dimensional interpolation kernel, the first element of the PARAMS array should be used to specify how many pixels are to contribute to the interpolated result on either side of the interpolation point in each dimension (the nearest integer value is used). Execution time increases rapidly with this number. Typically, a value of 2 is appropriate and the minimum value used will be 1 (i.e. two pixels altogether, one on either side of the interpolation point). A value of zero or less may be given for PARAMS(1) to indicate that a suitable number of pixels should be calculated automatically. In each of these cases, the FINTERP argument is not used: \sstitemlist{ \sstitem AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant. The full-width at half-maximum (FWHM) is given by PARAMS(2) value, which should be at least 0.1 (in addition, setting PARAMS(1) to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1\% of its maximum value). This kernel suppresses noise at the expense of smoothing the output array. \sstitem AST\_\_SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the pixel offset from the interpolation point and sinc(z)=sin(z)/z. This sometimes features as an \texttt{"} optimal\texttt{"} interpolation kernel in books on image processing. Its supposed optimality depends on the assumption that the data are band-limited (i.e. have no spatial frequencies above a certain value) and are adequately sampled. In practice, astronomical data rarely meet these requirements. In addition, high spatial frequencies are often present due (e.g.) to image defects and cosmic ray events. Consequently, substantial ringing can be experienced with this kernel. The kernel also decays slowly with distance, so that many surrounding pixels are required, leading to poor performance. Abruptly truncating it, by using only a few neighbouring pixels, improves performance and may reduce ringing (if PARAMS(1) is set to zero, then only two pixels will be used on either side). However, a more gradual truncation, as implemented by other kernels, is generally to be preferred. This kernel is provided mainly so that you can convince yourself not to use it! \sstitem AST\_\_SINCSINC: This scheme uses an improved kernel, of the form sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor provides an \texttt{"} envelope\texttt{"} which gradually rolls off the normal sinc(pi$*$x) kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the PARAMS(2) value, which should be at least 1.0 (in addition, setting PARAMS(1) to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). The case given by PARAMS(1)=2, PARAMS(2)=2 is typically a good choice and is sometimes known as the Lanczos kernel. This is a valuable general-purpose interpolation scheme, intermediate in its visual effect on images between the AST\_\_NEAREST and AST\_\_LINEAR schemes. Although the kernel is slightly oscillatory, ringing is adequately suppressed if the data are well sampled. \sstitem AST\_\_SINCCOS: This scheme uses a kernel of the form sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor provides an envelope which gradually rolls off the sinc() kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the PARAMS(2) value, which should be at least 1.0 (in addition, setting PARAMS(1) to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). This scheme gives similar results to the AST\_\_SINCSINC scheme, which it resembles. \sstitem AST\_\_SINCGAUSS: This scheme uses a kernel of the form sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc() kernel is rolled off using a Gaussian envelope which is specified by giving its full-width at half-maximum (FWHM) by means of the PARAMS(2) value, which should be at least 0.1 (in addition, setting PARAMS(1) to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1\% of its maximum value). On astronomical images and spectra, good results are often obtained by approximately matching the FWHM of the envelope function, given by PARAMS(2), to the point spread function of the input data. However, there does not seem to be any theoretical reason for this. \sstitem AST\_\_SOMB: This scheme uses a somb(pi$*$x) kernel (a \texttt{"} sombrero\texttt{"} function), where x is the pixel offset from the interpolation point and somb(z)=2$*$J1(z)/z (J1 is a Bessel function of the first kind of order 1). It is similar to the AST\_\_SINC kernel, and has the same parameter usage. \sstitem AST\_\_SOMBCOS: This scheme uses a kernel of the form somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the AST\_\_SINCCOS kernel, and has the same parameter usage. } In addition, the following schemes are provided which are not based on a 1-dimensional kernel: \sstitemlist{ \sstitem AST\_\_BLOCKAVE: This scheme simply takes an average of all the pixels on the input grid in a cube centred on the interpolation point. The number of pixels in the cube is determined by the value of the first element of the PARAMS array, which gives the number of pixels in each dimension on either side of the central point. Hence a block of (2 $*$ PARAMS(1))$*$$*$NDIM\_IN pixels in the input grid will be examined to determine the value of the output pixel. If the variance is not being used (USEVAR = .FALSE.) then all valid pixels in this cube will be averaged in to the result with equal weight. If variances are being used, then each input pixel will be weighted proportionally to the reciprocal of its variance; any pixel without a valid variance will be discarded. This scheme is suitable where the output grid is much coarser than the input grid; if the ratio of pixel sizes is R then a suitable value of PARAMS(1) may be R/2. } Finally, supplying the following values for INTERP allows you to implement your own sub-pixel interpolation scheme by means of your own routine. You should supply the name of this routine via the FINTERP argument: \sstitemlist{ \sstitem AST\_\_UKERN1: In this scheme, you supply a routine to evaluate your own 1-dimensional interpolation kernel, which is then used to perform sub-pixel interpolation (as described above). The routine you supply should have the same interface as the fictitious \htmlref{AST\_UKERN1}{AST\_UKERN1} routine (q.v.). In addition, a value should be given via PARAMS(1) to specify the number of neighbouring pixels which are to contribute to each interpolated value (in the same way as for the pre-defined interpolation schemes described above). Other elements of the PARAMS array are available to pass values to your interpolation routine. \sstitem AST\_\_UINTERP: This is a completely general scheme, in which your interpolation routine has access to all of the input data. This allows you to implement any interpolation algorithm you choose, which could (for example) be non-linear, or adaptive. In this case, the AST\_RESAMPLE$<$X$>$ functions play no role in the sub-pixel interpolation process and simply handle the geometrical transformation of coordinates and other housekeeping. The routine you supply should have the same interface as the fictitious \htmlref{AST\_UINTERP}{AST\_UINTERP} routine (q.v.). In this case, the PARAMS argument is not used by AST\_RESAMPLE$<$X$>$, but is available to pass values to your interpolation routine. } } \sstdiytopic{ Control Flags }{ The following flags are defined in the AST\_PAR include file and may be used to provide additional control over the resampling process. Having selected a set of flags, you should supply the sum of their values via the FLAGS argument: \sstitemlist{ \sstitem AST\_\_NOBAD: Indicates that any output array elements for which no resampled value could be obtained should be left set to the value they had on entry to this function. If this flag is not supplied, such output array elements are set to the value supplied for argument BADVAL. Note, this flag cannot be used in conjunction with the AST\_\_CONSERVEFLUX flag (an error will be reported if both flags are specified). \sstitem AST\_\_URESAMP1, 2, 3 \& 4: A set of four flags which are reserved for your own use. They may be used to pass private information to any sub-pixel interpolation routine which you implement yourself. They are ignored by all the pre-defined interpolation schemes. \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for BADVAL and propagated to the output array(s). If this flag is not set, all input values are treated literally and the BADVAL value is only used for flagging output array values. \sstitem AST\_\_USEVAR: Indicates that variance information should be processed in order to provide estimates of the statistical error associated with the resampled values. If this flag is not set, no variance processing will occur and the IN\_VAR and OUT\_VAR arrays will not be used. (Note that this flag is only available in the Fortran interface to AST.) \sstitem AST\_\_CONSERVEFLUX: Indicates that the output pixel values should be scaled in such a way as to preserve (approximately) the total data value in a feature on the sky. Without this flag, each output pixel value represents an instantaneous sample of the input data values at the corresponding input position. This is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST\_\_CONSERVEFLUX flag could be used. This causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size. } This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the TOL argument is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the TOL argument until the difference between adjacent panels is sufficiently small to be insignificant. Note, this flag cannot be used in conjunction with the AST\_\_NOBAD flag (an error will be reported if both flags are specified). } \sstdiytopic{ Propagation of Missing Data }{ Unless the AST\_\_NOBAD flag is specified, instances of missing data (bad pixels) in the output grid are identified by occurrences of the BADVAL value in the OUT array. These may be produced if any of the following happen: \sstitemlist{ \sstitem The input position (the transformed position of the output pixel\texttt{'} s centre) lies outside the boundary of the grid of input pixels. \sstitem The input position lies inside the boundary of a bad input pixel. In this context, an input pixel is considered bad if its data value is equal to BADVAL and the AST\_\_USEBAD flag is set via the FLAGS argument. (Positions which have half-integral coordinate values, and therefore lie on a pixel boundary, are regarded as lying within the pixel with the larger, i.e. more positive, index.) \sstitem The set of neighbouring input pixels (excluding those which are bad) is unsuitable for calculating an interpolated value. Whether this is true may depend on the sub-pixel interpolation scheme in use. \sstitem The interpolated value lies outside the range which can be represented using the data type of the OUT array. } In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the BADVAL value in the OUT\_VAR array under any of the following circumstances: \sstitemlist{ \sstitem The associated resampled data value (in the OUT array) is bad. \sstitem The set of neighbouring input pixels which contributed to the output data value do not all have valid variance estimates associated with them. In this context, an input variance estimate may be regarded as bad either because it has the value BADVAL (and the AST\_\_USEBAD flag is set), or because it is negative. \sstitem The set of neighbouring input pixels for which valid variance values are available is unsuitable for calculating an overall variance value. Whether this is true may depend on the sub-pixel interpolation scheme in use. \sstitem The variance value lies outside the range which can be represented using the data type of the OUT\_VAR array. } If the AST\_\_NOBAD flag is specified via argument FLAGS, then output array elements that would otherwise be set to BADVAL are instead left holding the value they had on entry to this function. The number of such array elements is returned as the function value. } } \sstroutine{ AST\_RESOLVE }{ Resolve a vector into two orthogonal components }{ \sstdescription{ This routine resolves a vector into two perpendicular components. The vector from point 1 to point 2 is used as the basis vector. The vector from point 1 to point 3 is resolved into components parallel and perpendicular to this basis vector. The lengths of the two components are returned, together with the position of closest aproach of the basis vector to point 3. } \sstinvocation{ CALL AST\_RESOLVE( THIS, POINT1, POINT2, POINT3, POINT4, D1, D2, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Frame}{Frame}. } \sstsubsection{ POINT1( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This marks the start of the basis vector, and of the vector to be resolved. } \sstsubsection{ POINT2( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute). This marks the end of the basis vector. } \sstsubsection{ POINT3( $*$ ) = DOUBLE PRECISION (Given) }{ An array with one element for each Frame axis (Naxes attribute). This marks the end of the vector to be resolved. } \sstsubsection{ POINT4( $*$ ) = DOUBLE PRECISION (Returned) }{ An array with one element for each Frame axis in which the coordinates of the point of closest approach of the basis vector to point 3 will be returned. } \sstsubsection{ D1 = DOUBLE PRECISION (Returned) }{ 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. } \sstsubsection{ D2 = DOUBLE PRECISION (Returned) }{ 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. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Each vector used in this routine is the path of shortest distance between two points, as defined by the \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the required output values are undefined. } } } \sstroutine{ AST\_RETAINFITS }{ Indicate that the current card in a FitsChan should be retained }{ \sstdescription{ This routine stores a flag with the current card in the \htmlref{FitsChan}{FitsChan} indicating that the card should not be removed from the FitsChan when an \htmlref{Object}{Object} is read from the FitsChan using \htmlref{AST\_READ}{AST\_READ}. Cards that have not been flagged in this way are removed when a read operation completes succesfully, but only if the card was used in the process of creating the returned AST Object. Any cards that are irrelevant to the creation of the AST Object are retained whether or not they are flagged. } \sstinvocation{ CALL AST\_RETAINFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if the FitsChan is initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the \htmlref{Card}{Card} attribute exceeds the number of cards in the FitsChan). \sstitem The current card is not changed by this function. } } } \sstroutine{ AST\_RegionOutline }{ Draw the outline of an AST Region }{ \sstdescription{ This function draws an outline around the supplied AST \htmlref{Region}{Region} object. } \sstinvocation{ CALL AST\_REGIONOUTLINE( THIS, REGION, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ REGION = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_SAME }{ Test if two AST pointers refer to the same Object }{ \sstdescription{ This function returns a logical result to indicate whether two pointers refer to the same \htmlref{Object}{Object}. } \sstinvocation{ RESULT = AST\_SAME( THIS, THAT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the first Object. } \sstsubsection{ THAT = INTEGER (Given) }{ Pointer to the second Object. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_SAME = LOGICAL }{ .TRUE. if the two pointers refer to the same Object, otherwise .FALSE. } } \sstnotes{ \sstitemlist{ \sstitem Two independent Objects that happen to be identical are not considered to be the same Object by this function. \sstitem A value of .FALSE. will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SELECTORMAP }{ Create a SelectorMap }{ \sstdescription{ This function creates a new \htmlref{SelectorMap}{SelectorMap} and optionally initialises its attributes. A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains a given input position. A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation. For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation. If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. In practice, SelectorMaps are often used in conjunction with SwitchMaps. } \sstinvocation{ RESULT = AST\_SELECTORMAP( NREG, REGS, BADVAL, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NREG = INTEGER (Given) }{ The number of supplied Regions. } \sstsubsection{ REGS( NREG ) = INTEGER (Given) }{ An array of pointers to the Regions. All the supplied Regions must relate to the same coordinate Frame. The number of axes in this coordinate Frame defines the number of inputs for the SelectorMap. } \sstsubsection{ BADVAL = DOUBLE PRECISION (Given) }{ The value to be returned by the forward transformation of the SelectorMap for any input positions that have a bad (AST\_\_BAD) value on any axis. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SelectorMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SELECTORMAP = INTEGER }{ A pointer to the new SelectorMap. } } \sstnotes{ \sstitemlist{ \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the SelectorMap. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SET }{ Set attribute values for an Object }{ \sstdescription{ This routine assigns a set of attribute values to an \htmlref{Object}{Object}, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute\texttt{'} s data type. } \sstinvocation{ CALL AST\_SET( THIS, SETTINGS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ SETTINGS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing a comma-separated list of attribute settings in the form described above. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstexamples{ \sstexamplesubsection{ CALL AST\_SET( MAP, \texttt{'} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{'} , STATUS ) }{ Sets the Report attribute for Object MAP to the value 1 and the Zoom attribute to 25.0. } \sstexamplesubsection{ CALL AST\_SET( FRAME, \texttt{'} Label( 1 ) =Offset from cluster axis\texttt{'} , STATUS ) }{ Sets the Label(1) attribute for Object FRAME to a suitable string. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned). \sstitem To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ AST\_SET$<$X$>$ }{ Set an attribute value for an Object }{ \sstdescription{ This is a family of routines which set a specified attribute value for an \htmlref{Object}{Object} using one of several different data types. The type is selected by replacing $<$X$>$ in the routine name by C, D, I, L or R, to supply a value in Character, Double precision, Integer, Logical or Real format, respectively. If possible, the value you supply is converted to the type of the attribute. If conversion is not possible, an error will result. } \sstinvocation{ CALL AST\_SET$<$X$>$( THIS, ATTRIB, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ ATTRIB = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the name of the attribute whose value is to be set. } \sstsubsection{ VALUE = $<$X$>$type (Given) }{ The value to be set for the attribute, in the data type corresponding to $<$X$>$. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ These routines apply to all Objects. } } \sstexamples{ \sstexamplesubsection{ CALL AST\_SETC( PLOT, \texttt{'} \htmlref{Title}{Title}\texttt{'} , CVALUE, STATUS ) }{ Sets the Title attribute value for Object PLOT to the contents of the character variable CVALUE. } \sstexamplesubsection{ CALL AST\_SETL( FRAME, \texttt{'} Preserve\texttt{'} , .TRUE., STATUS ); }{ Sets the Preserve attribute value for Object FRAME to 1 (true). } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem The logical value .FALSE. will translate to a numerical attribute value of zero and logical .TRUE. will translate to one. \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ AST\_SETACTIVEUNIT }{ Specify how the Unit attribute should be used }{ \sstdescription{ This routine sets the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}, which controls how the Frame behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) to match another Frame. If the ActiveUnit flag is set in both template and target Frames then the returned \htmlref{Mapping}{Mapping} takes into account any differences in axis units. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0. If the ActiveUnit flag of either Frame is .FALSE., then the Mapping will ignore any difference in the Unit attributes of corresponding template and target axes. In this mode, the Unit attributes are purely descriptive commentary for the benefit of human readers and do not influence the Mappings between Frames. This is the behaviour which all Frames had in older version of AST, prior to the introduction of this attribute. If the ActiveUnit flag of both Frames is .TRUE., then the Mapping from template to target will take account of any difference in the axis Unit attributes, where-ever possible. For instance, if corresponding target and template axes have Unit strings of \texttt{"} km\texttt{"} and \texttt{"} m\texttt{"} , then the \htmlref{FrameSet}{FrameSet} class will use a \htmlref{ZoomMap}{ZoomMap} to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I \texttt{"} Representations of world coordinates in FITS\texttt{"} (Greisen \& Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus \texttt{"} flops\texttt{"} can be transformed to \texttt{"} Mflops\texttt{"} even though \texttt{"} flops\texttt{"} is not a standard FITS unit symbol). A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an \texttt{"} s\texttt{"} to the end of Angstrom, using a lower case \texttt{"} a\texttt{"} at the start of \texttt{"} angstrom\texttt{"} , \texttt{"} micron\texttt{"} instead of \texttt{"} um\texttt{"} , \texttt{"} sec\texttt{"} instead of \texttt{"} s\texttt{"} , etc. If the ActiveUnit flag is .TRUE., setting a new Unit value for an axis may also change its Label and Symbol attributes. For instance, if an axis has Unit \texttt{"} Hz\texttt{"} and Label \texttt{"} frequency\texttt{"} , then changing its Unit to \texttt{"} log(Hz)\texttt{"} will change its Label to \texttt{"} log( frequency )\texttt{"} . In addition, the \htmlref{Axis}{Axis} Format attribute will be cleared when-ever a new value is assigned to the Unit attribute. Note, if a .TRUE. value is set for the ActiveUnit flag, then changing a Unit value for the current Frame within a FrameSet will result in the Frame being re-mapped (that is, the Mappings which define the relationships between Frames within the FrameSet will be modified to take into account the change in Units). } \sstinvocation{ CALL AST\_SETACTIVEUNIT( THIS, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ VALUE = LOGICAL (Given) }{ The new value to use. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The ActiveUnit flag for a SkyFrame is always .FALSE. (any value supplied using this routine is ignored). } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The ActiveUnit flag for a SpecFrame is always .TRUE. (any value supplied using this routine is ignored). } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The ActiveUnit flag for a FluxFrame is always .TRUE. (any value supplied using this routine is ignored). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default ActiveUnit flag for a CmpFrame is .TRUE. if both of the component Frames are using active units, and .FALSE. otherwise. When a new value is set for the ActiveUnit flag, the flag value is propagated to the component Frames. This change will be reflected through all references to the component Frames, not just those encapsulated within the CmpFrame. } \sstsubsection{ \htmlref{Region}{Region}: }{ Regions always use active units if possible. } } \sstnotes{ \sstitemlist{ \sstitem The ActiveUnit flag resembles a Frame attribute, except that it cannot be tested or cleared, and it cannot be accessed using the generic \htmlref{AST\_GET$<$X$>$}{AST\_GET$<$X$>$} and \htmlref{AST\_SET$<$X$>$}{AST\_SET$<$X$>$} routines. \sstitem The \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT} routine can be used to retrieve the current value of the ActiveUnit flag. } } } \sstroutine{ AST\_SETFITS$<$X$>$ }{ Store a keyword value in a FitsChan }{ \sstdescription{ This is a family of routines which store values for named keywords within a \htmlref{FitsChan}{FitsChan} at the current card position. The supplied keyword value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan. The keyword data type is selected by replacing $<$X$>$ in the routine name by one of the following strings representing the recognised FITS data types: \sstitemlist{ \sstitem CF - Complex floating point values. \sstitem CI - Complex integer values. \sstitem F - Floating point values. \sstitem I - Integer values. \sstitem L - Logical (i.e. boolean) values. \sstitem S - String values. \sstitem CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but are encoded without an equals sign. } The data type of the \texttt{"} value\texttt{"} parameter depends on $<$X$>$ as follows: \sstitemlist{ \sstitem CF - DOUBLE PRECISION(2) (a 2 element array holding the real and imaginary parts of the complex value). \sstitem CI - INTEGER(2) (a 2 element array holding the real and imaginary parts of the complex value). \sstitem F - DOUBLE PRECISION. \sstitem I - INTEGER \sstitem L - LOGICAL \sstitem S - CHARACTER \sstitem CN - CHARACTER } } \sstinvocation{ CALL AST\_SETFITS$<$X$>$( THIS, NAME, VALUE, COMMENT, OVERWRITE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ VALUE = $<$X$>$type (Given) }{ The keyword value to store with the named keyword. The data type of this parameter depends on $<$X$>$ as described above. } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A string holding a comment to associated with the keyword. If a blank string is supplied, then any comment included in the string supplied for the NAME parameter is used instead. If NAME contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. } \sstsubsection{ OVERWRITE = LOGICAL (Given) }{ If .TRUE., the new card formed from the supplied keyword name, value and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If .FALSE., the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The routine \htmlref{AST\_SETFITSU}{AST\_SETFITSU} can be used to indicate that no value is associated with a keyword. \sstitem The routine \htmlref{AST\_SETFITSCM}{AST\_SETFITSCM} can be used to store a pure comment card (i.e. a card with a blank keyword). \sstitem To assign a new value for an existing keyword within a FitsChan, first find the card describing the keyword using \htmlref{AST\_FINDFITS}{AST\_FINDFITS}, and then use one of the AST\_SETFITS$<$X$>$ family to over-write the old value. \sstitem If, on exit, there are no cards following the card written by this routine, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem An error will be reported if the keyword name does not conform to FITS requirements. } } } \sstroutine{ AST\_SETFITSCM }{ Store a comment card in a FitsChan }{ \sstdescription{ This routine stores a comment card ( i.e. a card with no keyword name or equals sign) within a \htmlref{FitsChan}{FitsChan} at the current card position. The new card can either over-write an existing card, or can be inserted as a new card into the FitsChan. } \sstinvocation{ CALL AST\_SETFITSCM( THIS, COMMENT, OVERWRITE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A string holding the text of the comment card. If a blank string is supplied, then a totally blank card is produced. } \sstsubsection{ OVERWRITE = LOGICAL (Given) }{ If .TRUE., the new card over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If .FALSE., the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . } } } \sstroutine{ AST\_SETFITSU }{ Store an undefined keyword value in a FitsChan }{ \sstdescription{ This routine stores an undefined value for a named keyword within a \htmlref{FitsChan}{FitsChan} at the current card position. The new undefined value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan. } \sstinvocation{ CALL AST\_SETFITSU( THIS, NAME, COMMENT, OVERWRITE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ COMMENT = CHARACTER $*$ ( $*$ ) (Given) }{ A string holding a comment to associated with the keyword. If a blank string is supplied, then any comment included in the string supplied for the NAME parameter is used instead. If NAME contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. } \sstsubsection{ OVERWRITE = LOGICAL (Given) }{ If .TRUE., the new card formed from the supplied keyword name and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If .FALSE., the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem An error will be reported if the keyword name does not conform to FITS requirements. } } } \sstroutine{ AST\_SETREFPOS }{ Set the reference position in a specified celestial coordinate system }{ \sstdescription{ This routine sets the reference position (see attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) using axis values (in radians) supplied within the celestial coordinate system represented by a supplied \htmlref{SkyFrame}{SkyFrame}. } \sstinvocation{ CALL AST\_SETREFPOS( THIS, FRM, LON, LAT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the \htmlref{SpecFrame}{SpecFrame}. } \sstsubsection{ FRM = INTEGER (Given) }{ Pointer to the SkyFrame which defines the celestial coordinate system in which the longitude and latitude values are supplied. If AST\_\_NULL is supplied, then the supplied longitude and latitude values are assumed to be FK5 J2000 RA and Dec values. } \sstsubsection{ LON = DOUBLE PRECISION (Given) }{ The longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ LAT = DOUBLE PRECISION (Given) }{ The latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_SETUNC }{ Store uncertainty information in a Region }{ \sstdescription{ Each \htmlref{Region}{Region} (of any class) can have an \texttt{"} uncertainty\texttt{"} which specifies the uncertainties associated with the boundary of the Region. This information is supplied in the form of a second Region. The uncertainty in any point on the boundary of a Region is found by shifting the associated \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. The uncertainty is usually specified when the Region is created, but this routine allows it to be changed at any time. } \sstinvocation{ CALL AST\_SETUNC( THIS, UNC, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region which is to be assigned a new uncertainty. } \sstsubsection{ UNC = INTEGER (Given) }{ Pointer to the new uncertainty Region. This must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the Region THIS. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_SHIFTMAP }{ Create a ShiftMap }{ \sstdescription{ This function creates a new \htmlref{ShiftMap}{ShiftMap} and optionally initialises its attributes. A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a specified constant value. } \sstinvocation{ RESULT = AST\_SHIFTMAP( NCOORD, SHIFT, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ SHIFT( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the values to be added on to the input coordinates in order to create the output coordinates. A separate value should be supplied for each coordinate. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new ShiftMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SHIFTMAP = INTEGER }{ A pointer to the new ShiftMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_SHOW }{ Display a textual representation of an Object on standard output }{ \sstdescription{ This routine displays a textual description of any AST \htmlref{Object}{Object} on standard output. It is provided primarily as an aid to debugging. } \sstinvocation{ CALL AST\_SHOW( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object to be displayed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } } \sstroutine{ AST\_SHOWFITS }{ Display the contents of a FitsChan on standard output }{ \sstdescription{ This routine formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output. } \sstinvocation{ CALL AST\_SHOWFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_SHOWMESH }{ Display a mesh of points covering the surface of a Region }{ \sstdescription{ This routine writes a table to standard output containing the axis values at a mesh of points covering the surface of the supplied \htmlref{Region}{Region}. Each row of output contains a tab-separated list of axis values, one for each axis in the \htmlref{Frame}{Frame} encapsulated by the Region. The number of points in the mesh is determined by the \htmlref{MeshSize}{MeshSize} attribute. The table is preceded by a given title string, and followed by a single line containing the word \texttt{"} ENDMESH\texttt{"} . } \sstinvocation{ CALL AST\_SHOWMESH( THIS, FORMAT, TTL, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Region. } \sstsubsection{ FORMAT = LOGICAL (Given) }{ A boolean value indicating if the displayed axis values should be formatted according to the Format attribute associated with the Frame\texttt{'} s axis. Otherwise, they are displayed as simple floating point values. } \sstsubsection{ TTL = CHARACTER $*$ ( $*$ ) (Given) }{ A title to display before displaying the first position. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } } \sstroutine{ AST\_SIMPLIFY }{ Simplify a Mapping }{ \sstdescription{ This function simplifies a \htmlref{Mapping}{Mapping} (which may be a compound Mapping such as a \htmlref{CmpMap}{CmpMap}) to eliminate redundant computational steps, or to merge separate steps which can be performed more efficiently in a single operation. As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation. This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates. } \sstinvocation{ RESULT = AST\_SIMPLIFY( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the original Mapping. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Mapping }{ This function applies to all Mappings. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which all the inter-\htmlref{Frame}{Frame} Mappings have been simplified. } } \sstreturnedvalue{ \sstsubsection{ AST\_SIMPLIFY = INTEGER }{ A new pointer to the (possibly simplified) Mapping. } } \sstnotes{ \sstitemlist{ \sstitem Mappings that have a set value for their \htmlref{Ident}{Ident} attribute are left unchanged after simplification. This is so that their individual identity is preserved. This restriction does not apply to the simplification of Frames. \sstitem This function can safely be applied even to Mappings which cannot be simplified. If no simplification is possible, it behaves exactly like \htmlref{AST\_CLONE}{AST\_CLONE} and returns a pointer to the original Mapping. \sstitem The Mapping returned by this function may not be independent of the original (even if simplification was possible), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SKYFRAME }{ Create a SkyFrame }{ \sstdescription{ This function creates a new \htmlref{SkyFrame}{SkyFrame} and optionally initialises its attributes. A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or an \htmlref{Epoch}{Epoch}. For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs} and SkyRefP All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using \htmlref{AST\_FORMAT}{AST\_FORMAT}. } \sstinvocation{ RESULT = AST\_SKYFRAME( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SkyFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SKYFRAME = INTEGER }{ A pointer to the new SkyFrame. } } \sstexamples{ \sstexamplesubsection{ FRAME = AST\_SKYFRAME( \texttt{'} \texttt{'} , STATUS ) }{ Creates a SkyFrame to describe the default ICRS celestial coordinate system. } \sstexamplesubsection{ FRAME = AST\_SKYFRAME( \texttt{'} System = FK5, Equinox = J2005, Digits = 10\texttt{'} , STATUS ) }{ Creates a SkyFrame to describe the FK5 celestial coordinate system, with a mean Equinox of J2005.0. Because especially accurate coordinates will be used, additional precision (10 digits) has been requested. This will be used when coordinate values are formatted for display. } \sstexamplesubsection{ FRAME = AST\_SKYFRAME( \texttt{'} System = FK4, Equinox = 1955-SEP-2\texttt{'} , STATUS ) }{ Creates a SkyFrame to describe the old FK4 celestial coordinate system. A default Epoch value (B1950.0) is used, but the mean Equinox value is given explicitly as \texttt{"} 1955-SEP-2\texttt{"} . } \sstexamplesubsection{ FRAME = AST\_SKYFRAME( \texttt{'} System = GAPPT, Epoch = \texttt{'} // DATE, STATUS ) }{ Creates a SkyFrame to describe the Geocentric Apparent celestial coordinate system. The Epoch value, which specifies the date of observation, is obtained from a date/time string contained in the character variable DATE. } } \sstnotes{ \sstitemlist{ \sstitem Currently, the default celestial coordinate system is ICRS. However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in behaviour with future versions of this function). If you intend to use the ICRS system indefinitely, then you should specify it explicitly using an OPTIONS value of \texttt{"} System=ICRS\texttt{"} . \sstitem Whichever celestial coordinate system is represented, it will have two axes. The first of these will be the longitude axis and the second will be the latitude axis. This order can be changed using \htmlref{AST\_PERMAXES}{AST\_PERMAXES} if required. \sstitem When conversion between two SkyFrames is requested (as when supplying SkyFrames \htmlref{AST\_CONVERT}{AST\_CONVERT}), account will be taken of the nature of the celestial coordinate systems they represent, together with any qualifying mean Equinox or Epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} attribute will also be taken into account. The results will therefore fully reflect the relationship between positions on the sky measured in the two systems. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SKYOFFSETMAP }{ Returns a Mapping which goes from absolute coordinates to offset coordinates }{ \sstdescription{ This function returns a \htmlref{Mapping}{Mapping} in which the forward transformation transforms a position in the coordinate system given by the \htmlref{System}{System} attribute of the supplied \htmlref{SkyFrame}{SkyFrame}, into the offset coordinate system specified by the SkyRef, SkyRefP and \htmlref{SkyRefIs}{SkyRefIs} attributes of the supplied SkyFrame. A \htmlref{UnitMap}{UnitMap} is returned if the SkyFrame does not define an offset coordinate system. } \sstinvocation{ RESULT = AST\_SKYOFFSETMAP( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the SkyFrame. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SKYOFFSETMAP = INTEGER }{ Pointer to the returned Mapping. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SLAADD }{ Add a celestial coordinate conversion to an SlaMap }{ \sstdescription{ This routine adds one of the standard celestial coordinate system conversions provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67) to an existing \htmlref{SlaMap}{SlaMap}. When an SlaMap is first created (using \htmlref{AST\_SLAMAP}{AST\_SLAMAP}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_SLAADD (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SlaMap will perform in sequence. This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. Normally, if an SlaMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by AST\_SLAADD in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the SlaMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SlaMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstinvocation{ CALL AST\_SLAADD( THIS, CVT, ARGS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the SlaMap. } \sstsubsection{ CVT = CHARACTER $*$ ( $*$ ) (Given) }{ A character string which identifies the celestial coordinate conversion to be added to the SlaMap. See the \texttt{"} SLALIB Conversions\texttt{"} section for details of those available. } \sstsubsection{ ARGS( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing argument values for the celestial coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} SLALIB Conversions\texttt{"} section). This array is ignored if no arguments are needed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem All coordinate values processed by an SlaMap are in radians. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude. \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, converting to the standard FK5 coordinate system as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting SlaMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This routine does not check to ensure that the sequence of coordinate conversions added to an SlaMap is physically meaningful. } } \sstdiytopic{ SLALIB Conversions }{ The following strings (which are case-insensitive) may be supplied via the CVT argument to indicate which celestial coordinate conversion is to be added to the SlaMap. Each string is derived from the name of the SLALIB routine that performs the conversion and the relevant documentation (SUN/67) should be consulted for details. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the ARGS array, in the order indicated. The argument names match the corresponding SLALIB routine arguments and their values should be given using exactly the same units, time scale, calendar, etc. as described in SUN/67: \sstitemlist{ \sstitem \texttt{"} ADDET\texttt{"} (EQ): Add E-terms of aberration. \sstitem \texttt{"} SUBET\texttt{"} (EQ): Subtract E-terms of aberration. \sstitem \texttt{"} PREBN\texttt{"} (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4) precession model. \sstitem \texttt{"} PREC\texttt{"} (EP0,EP1): Apply IAU 1975 (FK5) precession model. \sstitem \texttt{"} FK45Z\texttt{"} (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax). \sstitem \texttt{"} FK54Z\texttt{"} (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax). \sstitem \texttt{"} AMP\texttt{"} (DATE,EQ): Convert geocentric apparent to mean place. \sstitem \texttt{"} MAP\texttt{"} (EQ,DATE): Convert mean place to geocentric apparent. \sstitem \texttt{"} ECLEQ\texttt{"} (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} EQECL\texttt{"} (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates. \sstitem \texttt{"} GALEQ\texttt{"} : Convert galactic coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} EQGAL\texttt{"} : Convert FK5 J2000.0 equatorial to galactic coordinates. \sstitem \texttt{"} HFK5Z\texttt{"} (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} FK5HZ\texttt{"} (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS. \sstitem \texttt{"} GALSUP\texttt{"} : Convert galactic to supergalactic coordinates. \sstitem \texttt{"} SUPGAL\texttt{"} : Convert supergalactic coordinates to galactic. \sstitem \texttt{"} J2000H\texttt{"} : Convert dynamical J2000.0 to ICRS. \sstitem \texttt{"} HJ2000\texttt{"} : Convert ICRS to dynamical J2000.0. \sstitem \texttt{"} R2H\texttt{"} (LAST): Convert RA to Hour Angle. \sstitem \texttt{"} H2R\texttt{"} (LAST): Convert Hour Angle to RA. } For example, to use the \texttt{"} ADDET\texttt{"} conversion, which takes a single argument EQ, you should consult the documentation for the SLALIB routine SLA\_ADDET. This describes the conversion in detail and shows that EQ is the Besselian epoch of the mean equator and equinox. This value should then be supplied to AST\_SLAADD in ARGS(1). In addition the following strings may be supplied for more complex conversions which do not correspond to any one single SLALIB routine (DIURAB is the magnitude of the diurnal aberration vector in units of \texttt{"} day/(2.PI)\texttt{"} , DATE is the Modified Julian Date of the observation, and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian coordinates, in metres, of the observer): \sstitemlist{ \sstitem \texttt{"} HPCEQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHPC\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian. \sstitem \texttt{"} HPREQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHPR\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial. \sstitem \texttt{"} HEEQ\texttt{"} (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHE\texttt{"} (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic. \sstitem \texttt{"} H2E\texttt{"} (LAT,DIRUAB): Convert horizon coordinates to equatorial. \sstitem \texttt{"} E2H\texttt{"} (LAT,DIURAB): Convert equatorial coordinates to horizon. } Note, the \texttt{"} H2E\texttt{"} and \texttt{"} E2H\texttt{"} conversions convert between topocentric horizon coordinates (azimuth,elevation), and apparent local equatorial coordinates (hour angle,declination). Thus, the effects of diurnal aberration are taken into account in the conversions but the effects of atmospheric refraction are not. } } \sstroutine{ AST\_SLAMAP }{ Create an SlaMap }{ \sstdescription{ This function creates a new \htmlref{SlaMap}{SlaMap} and optionally initialises its attributes. An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems. When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the \htmlref{AST\_SLAADD}{AST\_SLAADD} routine, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. For details of the individual coordinate conversions available, see the description of the AST\_SLAADD routine. } \sstinvocation{ RESULT = AST\_SLAMAP( FLAGS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FLAGS = INTEGER (Given) }{ This argument is reserved for future use and should currently always be set to zero. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SlaMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SLAMAP = INTEGER }{ A pointer to the new SlaMap. } } \sstnotes{ \sstitemlist{ \sstitem The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes (number of input and output coordinates) for an SlaMap are both equal to 2. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude. All coordinate values are in radians. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SPECADD }{ Add a spectral coordinate conversion to a SpecMap }{ \sstdescription{ This routine adds one of the standard spectral coordinate system conversions listed below to an existing \htmlref{SpecMap}{SpecMap}. When a SpecMap is first created (using \htmlref{AST\_SPECMAP}{AST\_SPECMAP}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_SPECADD (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SpecMap will perform in sequence. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class. Normally, if a SpecMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by AST\_SPECADD in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the SpecMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SpecMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstinvocation{ CALL AST\_SPECADD( THIS, CVT, ARGS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the SpecMap. } \sstsubsection{ CVT = CHARACTER $*$ ( $*$ ) (Given) }{ A character string which identifies the spectral coordinate conversion to be added to the SpecMap. See the \texttt{"} Available Conversions\texttt{"} section for details of those available. } \sstsubsection{ ARGS( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing argument values for the spectral coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} Available Conversions\texttt{"} section). This array is ignored if no arguments are needed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, when converting between reference frames, converting first to the heliographic reference frame as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting SpecMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This routine does not check to ensure that the sequence of coordinate conversions added to a SpecMap is physically meaningful. } } \sstdiytopic{ Available Conversions }{ The following strings (which are case-insensitive) may be supplied via the CVT argument to indicate which spectral coordinate conversion is to be added to the SpecMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the ARGS array, in the order indicated. Units and argument names are described at the end of the list of conversions. \sstitemlist{ \sstitem \texttt{"} FRTOVL\texttt{"} (RF): Convert frequency to relativistic velocity. \sstitem \texttt{"} VLTOFR\texttt{"} (RF): Convert relativistic velocity to Frequency. \sstitem \texttt{"} ENTOFR\texttt{"} : Convert energy to frequency. \sstitem \texttt{"} FRTOEN\texttt{"} : Convert frequency to energy. \sstitem \texttt{"} WNTOFR\texttt{"} : Convert wave number to frequency. \sstitem \texttt{"} FRTOWN\texttt{"} : Convert frequency to wave number. \sstitem \texttt{"} WVTOFR\texttt{"} : Convert wavelength (vacuum) to frequency. \sstitem \texttt{"} FRTOWV\texttt{"} : Convert frequency to wavelength (vacuum). \sstitem \texttt{"} AWTOFR\texttt{"} : Convert wavelength (air) to frequency. \sstitem \texttt{"} FRTOAW\texttt{"} : Convert frequency to wavelength (air). \sstitem \texttt{"} VRTOVL\texttt{"} : Convert radio to relativistic velocity. \sstitem \texttt{"} VLTOVR\texttt{"} : Convert relativistic to radio velocity. \sstitem \texttt{"} VOTOVL\texttt{"} : Convert optical to relativistic velocity. \sstitem \texttt{"} VLTOVO\texttt{"} : Convert relativistic to optical velocity. \sstitem \texttt{"} ZOTOVL\texttt{"} : Convert redshift to relativistic velocity. \sstitem \texttt{"} VLTOZO\texttt{"} : Convert relativistic velocity to redshift. \sstitem \texttt{"} BTTOVL\texttt{"} : Convert beta factor to relativistic velocity. \sstitem \texttt{"} VLTOBT\texttt{"} : Convert relativistic velocity to beta factor. \sstitem \texttt{"} USF2HL\texttt{"} (VOFF,RA,DEC): Convert frequency from a user-defined reference frame to heliocentric. \sstitem \texttt{"} HLF2US\texttt{"} (VOFF,RA,DEC): Convert frequency from heliocentric reference frame to user-defined. \sstitem \texttt{"} TPF2HL\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from topocentric reference frame to heliocentric. \sstitem \texttt{"} HLF2TP\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to topocentric. \sstitem \texttt{"} GEF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from geocentric reference frame to heliocentric. \sstitem \texttt{"} HLF2GE\texttt{"} (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to geocentric. \sstitem \texttt{"} BYF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from barycentric reference frame to heliocentric. \sstitem \texttt{"} HLF2BY\texttt{"} (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to barycentric. \sstitem \texttt{"} LKF2HL\texttt{"} (RA,DEC): Convert frequency from kinematic LSR reference frame to heliocentric. \sstitem \texttt{"} HLF2LK\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to kinematic LSR. \sstitem \texttt{"} LDF2HL\texttt{"} (RA,DEC): Convert frequency from dynamical LSR reference frame to heliocentric. \sstitem \texttt{"} HLF2LD\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to dynamical LSR. \sstitem \texttt{"} LGF2HL\texttt{"} (RA,DEC): Convert frequency from local group reference frame to heliocentric. \sstitem \texttt{"} HLF2LG\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to local group. \sstitem \texttt{"} GLF2HL\texttt{"} (RA,DEC): Convert frequency from galactic reference frame to heliocentric. \sstitem \texttt{"} HLF2GL\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to galactic. } The units for the values processed by the above conversions are as follows: \sstitemlist{ \sstitem all velocities: metres per second (positive if the source receeds from the observer). \sstitem frequency: Hertz. \sstitem all wavelengths: metres. \sstitem energy: Joules. \sstitem wave number: cycles per metre. } The arguments used in the above conversions are as follows: \sstitemlist{ \sstitem RF: Rest frequency (Hz). \sstitem OBSALT: Geodetic altitude of observer (IAU 1975, metres). \sstitem OBSLAT: Geodetic latitude of observer (IAU 1975, radians). \sstitem OBSLON: Longitude of observer (radians - positive eastwards). \sstitem EPOCH: \htmlref{Epoch}{Epoch} of observation (UT1 expressed as a Modified Julian Date). \sstitem RA: Right Ascension of source (radians, FK5 J2000). \sstitem DEC: Declination of source (radians, FK5 J2000). \sstitem VOFF: Velocity of the user-defined reference frame, towards the position given by RA and DEC, measured in the heliocentric reference frame. } If the SpecMap is 3-dimensional, source positions are provided by the values supplied to inputs 2 and 3 of the SpecMap (which are simply copied to outputs 2 and 3). Note, usable values are still required for the RA and DEC arguments in order to define the \texttt{"} user-defined\texttt{"} reference frame used by USF2HL and HLF2US. However, AST\_\_BAD can be supplied for RA and DEC if the user-defined reference frame is not required. } } \sstroutine{ AST\_SPECFLUXFRAME }{ Create a SpecFluxFrame }{ \sstdescription{ This function creates a new \htmlref{SpecFluxFrame}{SpecFluxFrame} and optionally initialises its attributes. A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents spectral position and the second axis represents flux. } \sstinvocation{ RESULT = AST\_SPECFLUXFRAME( FRAME1, FRAME2, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FRAME1 = INTEGER (Given) }{ Pointer to the SpecFrame. This will form the first axis in the new SpecFluxFrame. } \sstsubsection{ FRAME2 = INTEGER (Given) }{ Pointer to the FluxFrame. This will form the second axis in the new SpecFluxFrame. The \texttt{"} \htmlref{SpecVal}{SpecVal}\texttt{"} attribute of this FluxFrame is not used by the SpecFluxFrame class and so may be set to AST\_\_BAD when the FluxFrame is created. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFluxFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SPECFLUXFRAME = INTEGER }{ A pointer to the new SpecFluxFrame. } } \sstnotes{ \sstitemlist{ \sstitem The supplied Frame pointers are stored directly, rather than being used to create deep copies of the supplied Frames. This means that any subsequent changes made to the Frames via the supplied pointers will result in equivalent changes being visible in the SpecFluxFrame. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_SPECFRAME }{ Create a SpecFrame }{ \sstdescription{ This function creates a new \htmlref{SpecFrame}{SpecFrame} and optionally initialises its attributes. A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, etc (see the description of the System attribute for details). By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute } \sstinvocation{ RESULT = AST\_SPECFRAME( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SPECFRAME = INTEGER }{ A pointer to the new SpecFrame. } } \sstexamples{ \sstexamplesubsection{ FRAME = AST\_SPECFRAME( \texttt{'} \texttt{'} , STATUS ) }{ Creates a SpecFrame to describe the default wavelength spectral coordinate system. The \htmlref{RestFreq}{RestFreq} attribute (rest frequency) is unspecified, so it will not be possible to align this SpecFrame with another SpecFrame on the basis of a velocity-based system. The standard of rest is also unspecified. This means that alignment will be possible with other SpecFrames, but no correction will be made for Doppler shift caused by change of rest frame during the alignment. } \sstexamplesubsection{ FRAME = AST\_SPECFRAME( \texttt{'} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{'} , STATUS ) }{ Creates a SpecFrame describing a apparent radial velocity (\texttt{"} VELO\texttt{"} ) axis with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured in the kinematic Local Standard of Rest (\texttt{"} LSRK\texttt{"} ). Since the source position has not been specified (using attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}), it will only be possible to align this SpecFrame with other SpecFrames which are also measured in the LSRK standard of rest. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two SpecFrames is requested (as when supplying SpecFrames \htmlref{AST\_CONVERT}{AST\_CONVERT}), account will be taken of the nature of the spectral coordinate systems they represent, together with any qualifying rest frequency, standard of rest, epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest} attributes will also be taken into account. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SPECMAP }{ Create a SpecMap }{ \sstdescription{ This function creates a new \htmlref{SpecMap}{SpecMap} and optionally initialises its attributes. An SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard spectral coordinate systems. This includes conversions between frequency, wavelength, and various forms of velocity, as well as conversions between different standards of rest. When a SpecMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{AST\_SPECADD}{AST\_SPECADD} routine, a series of coordinate conversion steps may then be added, selected from the list of supported conversions. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class. For details of the individual coordinate conversions available, see the description of the AST\_SPECADD routine. Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output). } \sstinvocation{ RESULT = AST\_SPECMAP( NIN, FLAGS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NIN = INTEGER (Given) }{ The number of inputs to the Mapping (this will also equal the number of outputs). This value must be either 1 or 3. In either case, the first input and output correspoindis the spectral axis. For a 3-axis SpecMap, the second and third axes give the RA and DEC (J2000 FK5) of the source. This positional information is used by conversions which transform between standards of rest, and replaces the \texttt{"} RA\texttt{"} and \texttt{"} DEC\texttt{"} arguments for the individual conversions listed in description of the \texttt{"} SpecAdd\texttt{"} routine. } \sstsubsection{ FLAGS = INTEGER (Given) }{ This argument is reserved for future use and should currently always be set to zero. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SPECMAP = INTEGER }{ A pointer to the new SpecMap. } } \sstnotes{ \sstitemlist{ \sstitem The nature and units of the coordinate values supplied for the first input (i.e. the spectral input) of a SpecMap must be appropriate to the first conversion step applied by the SpecMap. For instance, if the first conversion step is \texttt{"} FRTOVL\texttt{"} (frequency to relativistic velocity), then the coordinate values for the first input should be frequency in units of Hz. Similarly, the nature and units of the coordinate values returned by a SpecMap will be determined by the last conversion step applied by the SpecMap. For instance, if the last conversion step is \texttt{"} VLTOVO\texttt{"} (relativistic velocity to optical velocity), then the coordinate values for the first output will be optical velocity in units of metres per second. See the description of the AST\_SPECADD routine for the units expected and returned by each conversion. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_SPHMAP }{ Create a SphMap }{ \sstdescription{ This function creates a new \htmlref{SphMap}{SphMap} and optionally initialises its attributes. A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors). } \sstinvocation{ RESULT = AST\_SPHMAP( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SphMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SPHMAP = INTEGER }{ A pointer to the new SphMap. } } \sstnotes{ \sstitemlist{ \sstitem The spherical coordinates are longitude (positive anti-clockwise looking from the positive latitude pole) and latitude. The Cartesian coordinates are right-handed, with the x axis (axis 1) at zero longitude and latitude, and the z axis (axis 3) at the positive latitude pole. \sstitem At either pole, the longitude is set to the value of the \htmlref{PolarLong}{PolarLong} attribute. \sstitem If the Cartesian coordinates are all zero, then the longitude and latitude are set to the value AST\_\_BAD. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_STCCATALOGENTRYLOCATION }{ Create a StcCatalogEntryLocation }{ \sstdescription{ This function creates a new \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} and optionally initialises its attributes. The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstinvocation{ RESULT = AST\_STCCATALOGENTRYLOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION = INTEGER (Given) }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ NCOORDS = INTEGER (Given) }{ The length of the COORDS array. Supply zero if COORDS should be ignored. } \sstsubsection{ COORDS( NCOORDS ) = INTEGER (Given) }{ An array holding NCOORDS AstKeyMap pointers (if NCOORDS is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by REGION. Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by REGION. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcCatalogEntryLocation. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_STCCATALOGENTRYLOCATION = INTEGER }{ A pointer to the new StcCatalogEntryLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_STCOBSDATALOCATION }{ Create a StcObsDataLocation }{ \sstdescription{ This function creates a new \htmlref{StcObsDataLocation}{StcObsDataLocation} and optionally initialises its attributes. The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstinvocation{ RESULT = AST\_STCOBSDATALOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION = INTEGER (Given) }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ NCOORDS = INTEGER (Given) }{ The length of the COORDS array. Supply zero if COORDS should be ignored. } \sstsubsection{ COORDS( NCOORDS ) = INTEGER (Given) }{ An array holding NCOORDS AstKeyMap pointers (if NCOORDS is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by REGION. Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by REGION. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcObsDataLocation. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_STCOBSDATALOCATION = INTEGER }{ A pointer to the new StcObsDataLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_STCRESOURCEPROFILE }{ Create a StcResourceProfile }{ \sstdescription{ This function creates a new \htmlref{StcResourceProfile}{StcResourceProfile} and optionally initialises its attributes. The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstinvocation{ RESULT = AST\_STCRESOURCEPROFILE( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION = INTEGER (Given) }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ NCOORDS = INTEGER (Given) }{ The length of the COORDS array. Supply zero if COORDS should be ignored. } \sstsubsection{ COORDS( NCOORDS ) = INTEGER (Given) }{ An array holding NCOORDS AstKeyMap pointers (if NCOORDS is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by REGION. Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by REGION. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcResourceProfile. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_STCRESOURCEPROFILE = INTEGER }{ A pointer to the new StcResourceProfile. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_STCSCHAN }{ Create an StcsChan }{ \sstdescription{ This function creates a new \htmlref{StcsChan}{StcsChan} and optionally initialises its attributes. A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description. Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting text. These routines should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such routines are supplied, a Channel will read from standard input and write to standard output. Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstinvocation{ RESULT = AST\_STCSCHAN( SOURCE, SINK, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ SOURCE = SUBROUTINE (Given) }{ A source routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SourceFile attribute, this routine will be used by the StcsChan to obtain lines of input text. On each invocation, it should read the next input line from some external data store, and then return the resulting text to the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a negative line length when there are no more lines to read. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SOURCE value, and no value has been set for the SourceFile attribute, the StcsChan will read from standard input instead. } \sstsubsection{ SINK = SUBROUTINE (Given) }{ A sink routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SinkFile attribute, this routine will be used by the StcsChan to deliver lines of output text. On each invocation, it should obtain the next output line from the AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the resulting text to some external data store. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SINK value, and no value has been set for the SinkFile attribute, the StcsChan will write to standard output instead. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcsChan. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_STCSCHAN = INTEGER }{ A pointer to the new StcsChan. } } \sstnotes{ \sstitemlist{ \sstitem The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST\_STCSCHAN. However, this is not generally necessary for the null routine AST\_NULL (so long as the AST\_PAR include file has been used). \sstitem If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST. \sstitem 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. \sstitem Note that the null routine AST\_NULL (one underscore) is different to AST\_\_NULL (two underscores), which is the null Object pointer. } } } \sstroutine{ AST\_STCSEARCHLOCATION }{ Create a StcSearchLocation }{ \sstdescription{ This function creates a new \htmlref{StcSearchLocation}{StcSearchLocation} and optionally initialises its attributes. The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of a VO query. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstinvocation{ RESULT = AST\_STCSEARCHLOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ REGION = INTEGER (Given) }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ NCOORDS = INTEGER (Given) }{ The length of the COORDS array. Supply zero if COORDS should be ignored. } \sstsubsection{ COORDS( NCOORDS ) = INTEGER (Given) }{ An array holding NCOORDS AstKeyMap pointers (if NCOORDS is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by REGION. Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by REGION. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcSearchLocation. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_STCSEARCHLOCATION = INTEGER }{ A pointer to the new StcSearchLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_STRIPESCAPES }{ Remove AST escape sequences from a string }{ \sstdescription{ This function removes AST escape sequences from a supplied string, returning the resulting text as the function value. The behaviour of this function can be controlled by invoking the \htmlref{AST\_ESCAPES}{AST\_ESCAPES} routine, which can be used to supress or enable the removal of escape sequences by this function. AST escape sequences are used by the \htmlref{Plot}{Plot} class to modify the appearance and position of sub-strings within a plotted text string. See the \texttt{"} \htmlref{Escape}{Escape}\texttt{"} attribute for further information. } \sstinvocation{ RESULT = AST\_STRIPESCAPES( TEXT ) } \sstarguments{ \sstsubsection{ TEXT }{ The string to be checked. } } \sstreturnedvalue{ \sstsubsection{ AST\_STRIPESCAPES = CHARACTER }{ The modified string. If the AST\_ESCAPES routine has been called indicating that escape sequences should not be stripped, then the supplied string is returned without change. } } } \sstroutine{ AST\_SWITCHMAP }{ Create a SwitchMap }{ \sstdescription{ This function creates a new \htmlref{SwitchMap}{SwitchMap} and optionally initialises its attributes. A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap. A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input. When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST\_\_BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position. When the SwitchMap is used to transform a position in the inverse direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is set to a value of AST\_\_BAD on every axis. In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly appropriate for this purpose. If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. } \sstinvocation{ RESULT = AST\_SWITCHMAP( FSMAP, ISMAP, NROUTE, ROUTEMAPS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FSMAP = INTEGER (Given) }{ Pointer to the forward selector Mapping. This must have a defined forward transformation, but need not have a defined inverse transformation. It must have one output, and the number of inputs must match the number of inputs of each of the supplied route Mappings. AST\_\_NULL may be supplied, in which case the SwitchMap will have an undefined forward Mapping. } \sstsubsection{ ISMAP = INTEGER (Given) }{ Pointer to the inverse selector Mapping. This must have a defined inverse transformation, but need not have a defined forward transformation. It must have one input, and the number of outputs must match the number of outputs of each of the supplied route Mappings. AST\_\_NULL may be supplied, in which case the SwitchMap will have an undefined inverse Mapping. } \sstsubsection{ NROUTE = INTEGER (Given) }{ The number of supplied route Mappings. } \sstsubsection{ ROUTEMAPS( NROUTE ) = INTEGER (Given) }{ An array of pointers to the route Mappings. All the supplied route Mappings must have common values for the Nin and Nout attributes, and these values define the number of inputs and outputs of the SwitchMap. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SwitchMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_SWITCHMAP = INTEGER }{ A pointer to the new SwitchMap. } } \sstnotes{ \sstitemlist{ \sstitem Note that the component Mappings supplied are not copied by AST\_SWITCHMAP (the new SwitchMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a SwitchMap containing a copy of its component Mappings is required, then a copy of the SwitchMap should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_TABLE }{ Create a Table }{ \sstdescription{ This function creates a new empty \htmlref{Table}{Table} and optionally initialises its attributes. The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional table of values. The AST\_MAPGET... and AST\_MAPPUT... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the name of a table column and \texttt{"} i\texttt{"} is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table. Columns must be declared using the \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN} method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape (specified when the column is declared). Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER} method before being accessed. Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables. } \sstinvocation{ RESULT = AST\_TABLE( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new Table. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TABLE = INTEGER }{ A pointer to the new Table. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_TABLESOURCE }{ Register a source routine for accessing tables in FITS files }{ \sstdescription{ This routine can be used to register a call-back routine with a \htmlref{FitsChan}{FitsChan}. The registered routine is called when-ever the FitsChan needs to read information from a binary table contained within a FITS file. This occurs if the \htmlref{AST\_READ}{AST\_READ} function is invoked to read a \htmlref{FrameSet}{FrameSet} from a set of FITS headers that use the \texttt{"} -TAB\texttt{"} algorithm to describe one or more axes. Such axes use a FITS binary table to store a look-up table of axis values. The FitsChan will fail to read such axes unless the \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute is set to a non-zero positive integer value. The table containing the axis values must be made available to the FitsChan either by storing the table contents in the FitsChan (using \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES} or \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}) prior to invoking AST\_READ or by registering a call-back routine using AST\_TABLESOURCE. The first method is possibly simpler, but requires that the name of the extension containing the table be known in advance. Since the table name is embedded in the FITS headers, the name is often not known in advance. If a call-back is registered, the FitsChan will determine the name of the required table and invoke the call-back routine to supply the table at the point where it is needed (i.e. within the AST\_READ method). } \sstinvocation{ CALL AST\_TABLESOURCE( THIS, TABSOURCE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ TABSOURCE = SUBROUTINE (Given) }{ The table source routine to use. It takes five arguments - the first is a pointer to the FitsChan, the second is a string holding the name of the FITS extension containing the required binary table (\texttt{"} EXTNAME\texttt{"} ), the third is the integer FITS \texttt{"} EXTVER\texttt{"} header value for the required extension, the fourth is the integer FITS \texttt{"} EXTLEVEL\texttt{"} header value for the required extension, and the fifth is the inherited integer status value. The call-back should read the entire contents (header and data) of the binary table in the named extension of the external FITS file, storing the contents in a newly created \htmlref{FitsTable}{FitsTable} object. It should then store this FitsTable in the FitsChan using the AST\_PUTTABLES or AST\_PUTTABLE method, and finally annull its local copy of the FitsTable pointer. If the table cannot be read for any reason, or if any other error occurs, it should return a non-zero integer for the final (third) argument. If TABSOURCE is AST\_NULL, any registered call-back function will be removed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The name of the routine supplied for the TABSOURCE argument should appear in an EXTERNAL statement in the Fortran routine which invokes AST\_TABLESOURCE. However, this is not generally necessary for the null routine AST\_NULL (so long as the AST\_PAR include file has been used). \sstitem Note that the null routine AST\_NULL (one underscore) is different to AST\_\_NULL (two underscores), which is the null \htmlref{Object}{Object} pointer. } } } \sstroutine{ AST\_TEST }{ Test if an Object attribute value is set }{ \sstdescription{ This function returns a logical result to indicate whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s attributes. } \sstinvocation{ RESULT = AST\_TEST( THIS, ATTRIB, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Object. } \sstsubsection{ ATTRIB = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the name of the attribute to be tested. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Object }{ This routine applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_TEST = LOGICAL }{ .TRUE. if a value has previously been explicitly set for the attribute (and hasn\texttt{'} t been cleared), otherwise .FALSE.. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem A value of .FALSE. will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. \sstitem A value of .FALSE. will also be returned if this function is used to test a read-only attribute, although no error will result. } } } \sstroutine{ AST\_TESTFITS }{ See if a named keyword has a defined value in a FitsChan }{ \sstdescription{ This function serches for a named keyword in a \htmlref{FitsChan}{FitsChan}. If found, and if the keyword has a value associated with it, a .TRUE. value is returned. If the keyword is not found, or if it does not have an associated value, a .FALSE. value is returned. } \sstinvocation{ RESULT = AST\_TESTFITS( THIS, NAME, THERE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ THERE = LOGICAL (Returned) }{ A value of .TRUE. will be returned if the keyword was found in the header, and .FALSE. otherwise. This parameter allows a distinction to be made between the case where a keyword is not present, and the case where a keyword is present but has no associated value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TESTFITS = LOGICAL }{ A value of zero .FALSE. is returned if the keyword was not found in the FitsChan or has no associated value. Otherwise, a value of .TRUE. is returned. } } \sstnotes{ \sstitemlist{ \sstitem The current card is left unchanged by this function. \sstitem The card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards. \sstitem An error will be reported if the keyword name does not conform to FITS requirements. \sstitem .FALSE. is returned as the function value if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ AST\_TEXT }{ Draw a text string for a Plot }{ \sstdescription{ This function draws a string of text at a position specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The physical position is transformed into graphical coordinates to determine where the text should appear within the plotting area. } \sstinvocation{ CALL AST\_TEXT( THIS, TEXT, POS, UP, JUST, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Plot. } \sstsubsection{ TEXT = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the text to be drawn. Trailing white space is ignored. } \sstsubsection{ POS( $*$ ) = DOUBLE PRECISION (Given) }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the point where the reference position of the text string is to be placed. } \sstsubsection{ UP( $*$ ) = REAL (Given) }{ An array holding the components of a vector in the \texttt{"} up\texttt{"} direction of the text (in graphical coordinates). For example, to get horizontal text, the vector [0.0,1.0] should be supplied. For a basic Plot, 2 values should be supplied. For a \htmlref{Plot3D}{Plot3D}, 3 values should be supplied, and the actual up vector used is the projection of the supplied up vector onto the text plane specified by the current value of the Plot3D\texttt{'} s Norm attribute. } \sstsubsection{ JUST = CHARACTER $*$ ( $*$ ) (Given) }{ A character string identifying the reference point for the text being drawn. The first character in this string identifies the reference position in the \texttt{"} up\texttt{"} direction and may be \texttt{"} B\texttt{"} (baseline), \texttt{"} C\texttt{"} (centre), \texttt{"} T\texttt{"} (top) or \texttt{"} M\texttt{"} (bottom). The second character identifies the side-to-side reference position and may be \texttt{"} L\texttt{"} (left), \texttt{"} C\texttt{"} (centre) or \texttt{"} R\texttt{"} (right ). The string is case-insensitive, and only the first two characters are significant. For example, a value of \texttt{"} BL\texttt{"} means that the left end of the baseline of the original (un-rotated) text is to be drawn at the position given by POS. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The Plot3D class currently does not interpret graphical escape sequences contained within text displayed using this method. \sstitem Text is not drawn at positions which have any coordinate equal to the value AST\_\_BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST\_\_BAD). \sstitem If the plotting position is clipped (see \htmlref{AST\_CLIP}{AST\_CLIP}), then no text is drawn. \sstitem An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ AST\_TIMEADD }{ Add a time coordinate conversion to a TimeMap }{ \sstdescription{ This routine adds one of the standard time coordinate system conversions listed below to an existing \htmlref{TimeMap}{TimeMap}. When a TimeMap is first created (using \htmlref{AST\_TIMEMAP}{AST\_TIMEMAP}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_TIMEADD (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the TimeMap will perform in sequence. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of the building blocks provided by this class. Normally, if a TimeMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by AST\_TIMEADD in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the TimeMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the TimeMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstinvocation{ CALL AST\_TIMEADD( THIS, CVT, ARGS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the TimeMap. } \sstsubsection{ CVT = CHARACTER $*$ ( $*$ ) (Given) }{ A character string which identifies the time coordinate conversion to be added to the TimeMap. See the \texttt{"} Available Conversions\texttt{"} section for details of those available. } \sstsubsection{ ARGS( $*$ ) = DOUBLE PRECISION (Given) }{ An array containing argument values for the time coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} Available Conversions\texttt{"} section). This array is ignored if no arguments are needed. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting TimeMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This routine does not check to ensure that the sequence of coordinate conversions added to a TimeMap is physically meaningful. } } \sstdiytopic{ Available Conversions }{ The following strings (which are case-insensitive) may be supplied via the CVT argument to indicate which time coordinate conversion is to be added to the TimeMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the ARGS array, in the order indicated. Units and argument names are described at the end of the list of conversions, and \texttt{"} MJD\texttt{"} means Modified Julian Date. \sstitemlist{ \sstitem \texttt{"} MJDTOMJD\texttt{"} (MJDOFF1,MJDOFF2): Convert MJD from one offset to another. \sstitem \texttt{"} MJDTOJD\texttt{"} (MJDOFF,JDOFF): Convert MJD to Julian Date. \sstitem \texttt{"} JDTOMJD\texttt{"} (JDOFF,MJDOFF): Convert Julian Date to MJD. \sstitem \texttt{"} MJDTOBEP\texttt{"} (MJDOFF,BEPOFF): Convert MJD to Besselian epoch. \sstitem \texttt{"} BEPTOMJD\texttt{"} (BEPOFF,MJDOFF): Convert Besselian epoch to MJD. \sstitem \texttt{"} MJDTOJEP\texttt{"} (MJDOFF,JEPOFF): Convert MJD to Julian epoch. \sstitem \texttt{"} JEPTOMJD\texttt{"} (JEPOFF,MJDOFF): Convert Julian epoch to MJD. \sstitem \texttt{"} TAITOUTC\texttt{"} (MJDOFF): Convert a TAI MJD to a UTC MJD. \sstitem \texttt{"} UTCTOTAI\texttt{"} (MJDOFF): Convert a UTC MJD to a TAI MJD. \sstitem \texttt{"} TAITOTT\texttt{"} (MJDOFF): Convert a TAI MJD to a TT MJD. \sstitem \texttt{"} TTTOTAI\texttt{"} (MJDOFF): Convert a TT MJD to a TAI MJD. \sstitem \texttt{"} TTTOTDB\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD. \sstitem \texttt{"} TDBTOTT\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD. \sstitem \texttt{"} TTTOTCG\texttt{"} (MJDOFF): Convert a TT MJD to a TCG MJD. \sstitem \texttt{"} TCGTOTT\texttt{"} (MJDOFF): Convert a TCG MJD to a TT MJD. \sstitem \texttt{"} TDBTOTCB\texttt{"} (MJDOFF): Convert a TDB MJD to a TCB MJD. \sstitem \texttt{"} TCBTOTDB\texttt{"} (MJDOFF): Convert a TCB MJD to a TDB MJD. \sstitem \texttt{"} UTTOGMST\texttt{"} (MJDOFF): Convert a UT MJD to a GMST MJD. \sstitem \texttt{"} GMSTTOUT\texttt{"} (MJDOFF): Convert a GMST MJD to a UT MJD. \sstitem \texttt{"} GMSTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. \sstitem \texttt{"} LMSTTOGMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. \sstitem \texttt{"} LASTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. \sstitem \texttt{"} LMSTTOLAST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. \sstitem \texttt{"} UTTOUTC\texttt{"} (DUT1): Convert a UT1 MJD to a UTC MJD. \sstitem \texttt{"} UTCTOUT\texttt{"} (DUT1): Convert a UTC MJD to a UT1 MJD. \sstitem \texttt{"} LTTOUTC\texttt{"} (LTOFF): Convert a Local Time MJD to a UTC MJD. \sstitem \texttt{"} UTCTOLT\texttt{"} (LTOFF): Convert a UTC MJD to a Local Time MJD. } The units for the values processed by the above conversions are as follows: \sstitemlist{ \sstitem Julian epochs and offsets: Julian years \sstitem Besselian epochs and offsets: Tropical years \sstitem Modified Julian Dates and offsets: days \sstitem Julian Dates and offsets: days } The arguments used in the above conversions are the zero-points used by the AST\_TRANSFORM routine. The axis values supplied and returned by AST\_TRANSFORM are offsets away from these zero-points: \sstitemlist{ \sstitem MJDOFF: The zero-point being used with MJD values. \sstitem JDOFF: The zero-point being used with Julian Date values. \sstitem BEPOFF: The zero-point being used with Besselian epoch values. \sstitem JEPOFF: The zero-point being used with Julian epoch values. \sstitem OBSLON: Observer longitude in radians ($+$ve westwards). \sstitem OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards). \sstitem OBSALT: Observer geodetic altitude (IAU 1975) in metres. \sstitem DUT1: The UT1-UTC value to use. \sstitem LTOFF: The offset between Local Time and UTC (in hours, positive for time zones east of Greenwich). } } } \sstroutine{ AST\_TIMEFRAME }{ Create a TimeFrame }{ \sstdescription{ This function creates a new \htmlref{TimeFrame}{TimeFrame} and optionally initialises its attributes. A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions in time. A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame representing time offsets from the specified zero point. Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years. The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that is, the physical proces used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales. When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute). } \sstinvocation{ RESULT = AST\_TIMEFRAME( OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeFrame. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TIMEFRAME = INTEGER }{ A pointer to the new TimeFrame. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two TimeFrames is requested (as when supplying TimeFrames \htmlref{AST\_CONVERT}{AST\_CONVERT}), account will be taken of the nature of the time coordinate systems they represent, together with any qualifying time scale, offset, unit, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignTimeScale}{AlignTimeScale} attributes will also be taken into account. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_TIMEMAP }{ Create a TimeMap }{ \sstdescription{ This function creates a new \htmlref{TimeMap}{TimeMap} and optionally initialises its attributes. A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard time coordinate systems. When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{AST\_TIMEADD}{AST\_TIMEADD} routine, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks. For details of the individual coordinate conversions available, see the description of the AST\_TIMEADD routine. } \sstinvocation{ RESULT = AST\_TIMEMAP( FLAGS, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ FLAGS = INTEGER (Given) }{ This argument is reserved for future use and should currently always be set to zero. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank value may be supplied. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TIMEMAP = INTEGER }{ A pointer to the new TimeMap. } } \sstnotes{ \sstitemlist{ \sstitem The nature and units of the coordinate values supplied for the first input (i.e. the time input) of a TimeMap must be appropriate to the first conversion step applied by the TimeMap. For instance, if the first conversion step is \texttt{"} MJDTOBEP\texttt{"} (Modified Julian Date to Besselian epoch) then the coordinate values for the first input should be date in units of days. Similarly, the nature and units of the coordinate values returned by a TimeMap will be determined by the last conversion step applied by the TimeMap. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_TRAN1 }{ Transform 1-dimensional coordinates }{ \sstdescription{ This routine applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in one dimension. } \sstinvocation{ CALL AST\_TRAN1( THIS, NPOINT, XIN, FORWARD, XOUT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be applied. } \sstsubsection{ NPOINT = INTEGER (Given) }{ The number of points to be transformed. } \sstsubsection{ XIN( NPOINT ) = DOUBLE PRECISION (Given) }{ An array of coordinate values for the input (untransformed) points. } \sstsubsection{ FORWARD = LOGICAL (Given) }{ A .TRUE. value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a .FALSE. value indicates that the inverse transformation should be used. } \sstsubsection{ XOUT( NPOINT ) = DOUBLE PRECISION (Returned) }{ An array into which the coordinates of the output (transformed) points will be written. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. } } } \sstroutine{ AST\_TRAN2 }{ Transform 2-dimensional coordinates }{ \sstdescription{ This routine applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in two dimensions. } \sstinvocation{ CALL AST\_TRAN2( THIS, NPOINT, XIN, YIN, FORWARD, XOUT, YOUT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be applied. } \sstsubsection{ NPOINT = INTEGER (Given) }{ The number of points to be transformed. } \sstsubsection{ XIN( NPOINT ) = DOUBLE PRECISION (Given) }{ An array of X-coordinate values for the input (untransformed) points. } \sstsubsection{ YIN( NPOINT ) = DOUBLE PRECISION (Given) }{ An array of Y-coordinate values for the input (untransformed) points. } \sstsubsection{ FORWARD = LOGICAL (Given) }{ A .TRUE. value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a .FALSE. value indicates that the inverse transformation should be used. } \sstsubsection{ XOUT( NPOINT ) = DOUBLE PRECISION (Returned) }{ An array into which the X-coordinates of the output (transformed) points will be written. } \sstsubsection{ YOUT( NPOINT ) = DOUBLE PRECISION (Returned) }{ An array into which the Y-coordinates of the output (transformed) points will be written. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. } } } \sstroutine{ AST\_TRANGRID }{ Transform a grid of positions }{ \sstdescription{ This function uses the supplied \htmlref{Mapping}{Mapping} to transforms a regular square grid of points covering a specified box. It attempts to do this quickly by first approximating the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstinvocation{ CALL AST\_TRANGRID( THIS, NCOORD\_IN, LBND, UBND, TOL, MAXPIX, FORWARD, NCOORD\_OUT, OUTDIM, OUT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be applied. } \sstsubsection{ NCOORD\_IN = INTEGER (Given) }{ The number of coordinates being supplied for each box corner (i.e. the number of dimensions of the space in which the input points reside). } \sstsubsection{ LBND( NCOORD\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND( NCOORD\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND and UBND together define the shape and size of the input grid, its extent along a particular (J\texttt{'} th) dimension being UBND(J)-LBND(J)$+$1. They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ TOL = DOUBLE PRECISION (Given) }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement within the output coordinate system of the Mapping. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher. If this is a problem, reduce the tolerance value used. } \sstsubsection{ MAXPIX = INTEGER (Given) }{ A value which specifies an initial scale size (in input grid points) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed MAXPIX grid points in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 grid points can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting TOL to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ FORWARD = LOGICAL (Given) }{ A .TRUE. value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a .FALSE. value indicates that the inverse transformation should be used. } \sstsubsection{ NCOORD\_OUT = INTEGER (Given) }{ The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as NCOORD\_IN. } \sstsubsection{ OUTDIM = INTEGER (Given) }{ The number of elements along the first dimension of the OUT array (which will contain the output coordinates). The value given should not be less than the number of points in the grid. } \sstsubsection{ OUT( OUTDIM, NCOORD\_OUT ) = DOUBLE PRECISION (Returned) }{ An array into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number COORD for output point number POINT will be found in element OUT(POINT,COORD). The points are ordered such that the first axis of the input grid changes most rapidly. For example, if the input grid is 2-dimensional and extends from (2,-1) to (3,1), the output points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the forward coordinate transformation is being applied, the Mapping supplied must have the value of NCOORD\_IN for its \htmlref{Nin}{Nin} attribute and the value of NCOORD\_OUT for its \htmlref{Nout}{Nout} attribute. If the inverse transformation is being applied, these values should be reversed. } } } \sstroutine{ AST\_TRANMAP }{ Create a TranMap }{ \sstdescription{ This function creates a new \htmlref{TranMap}{TranMap} and optionally initialises its attributes. A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist). When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed. } \sstinvocation{ RESULT = AST\_TRANMAP( MAP1, MAP2, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ MAP1 = INTEGER (Given) }{ Pointer to the first component Mapping, which defines the forward transformation. } \sstsubsection{ MAP2 = INTEGER (Given) }{ Pointer to the second component Mapping, which defines the inverse transformation. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new TranMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TRANMAP = INTEGER }{ A pointer to the new TranMap. } } \sstnotes{ \sstitemlist{ \sstitem The number of output coordinates generated by the two Mappings (their \htmlref{Nout}{Nout} attribute) must be equal, as must the number of input coordinates accepted by each Mapping (their \htmlref{Nin}{Nin} attribute). \sstitem The forward transformation of the first Mapping must exist. \sstitem The inverse transformation of the second Mapping must exist. \sstitem Note that the component Mappings supplied are not copied by AST\_TRANMAP (the new TranMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a TranMap containing a copy of its component Mappings is required, then a copy of the TranMap should be made using \htmlref{AST\_COPY}{AST\_COPY}. \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_TRANN }{ Transform N-dimensional coordinates }{ \sstdescription{ This routine applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in a single array (which they need not fill completely). } \sstinvocation{ CALL AST\_TRANN( THIS, NPOINT, NCOORD\_IN, INDIM, IN, FORWARD, NCOORD\_OUT, OUTDIM, OUT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Mapping to be applied. } \sstsubsection{ NPOINT = INTEGER (Given) }{ The number of points to be transformed. } \sstsubsection{ NCOORD\_IN = INTEGER (Given) }{ The number of coordinates being supplied for each input point (i.e. the number of dimensions of the space in which the input points reside). } \sstsubsection{ INDIM = INTEGER (Given) }{ The number of elements along the first dimension of the IN array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than NPOINT. } \sstsubsection{ IN( INDIM, NCOORD\_IN ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of the input (untransformed) points. These should be stored such that the value of coordinate number COORD for input point number POINT is found in element IN(POINT,COORD). } \sstsubsection{ FORWARD = LOGICAL (Given) }{ A .TRUE. value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a .FALSE. value indicates that the inverse transformation should be used. } \sstsubsection{ NCOORD\_OUT = INTEGER (Given) }{ The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as NCOORD\_IN. } \sstsubsection{ OUTDIM = INTEGER (Given) }{ The number of elements along the first dimension of the OUT array (which will contain the output coordinates). This value is required so that the coordinate values can be correctly located if they will not entirely fill this array. The value given should not be less than NPOINT. } \sstsubsection{ OUT( OUTDIM, NCOORD\_OUT ) = DOUBLE PRECISION (Returned) }{ An array into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number COORD for output point number POINT will be found in element OUT(POINT,COORD). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the forward coordinate transformation is being applied, the Mapping supplied must have the value of NCOORD\_IN for its \htmlref{Nin}{Nin} attribute and the value of NCOORD\_OUT for its \htmlref{Nout}{Nout} attribute. If the inverse transformation is being applied, these values should be reversed. } } } \sstroutine{ AST\_TUNE }{ Set or get an integer-valued AST global tuning parameter }{ \sstdescription{ This function returns the current value of an integer-valued AST global tuning parameter, optionally storing a new value for the parameter. For character-valued tuning parameters, see \htmlref{AST\_TUNEC}{AST\_TUNEC}. } \sstinvocation{ RESULT = AST\_TUNE( NAME, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The name of the tuning parameter (case-insensitive). } \sstsubsection{ VALUE = INTEGER (Given) }{ The new value for the tuning parameter. If this is AST\_\_TUNULL, the existing current value will be retained. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_TUNE = INTEGER }{ be returned if no value has been set for the parameter. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem All threads in a process share the same AST tuning parameters values. } } \sstdiylist{ Tuning Parameters }{ \sstsubsection{ ObjectCaching }{ A boolean flag which indicates what should happen to the memory occupied by an AST \htmlref{Object}{Object} when the Object is deleted (i.e. when its reference count falls to zero or it is deleted using \htmlref{AST\_DELETE}{AST\_DELETE}). If this is zero, the memory is simply freed using the systems \texttt{"} free\texttt{"} function. If it is non-zero, the memory is not freed. Instead a pointer to it is stored in a pool of such pointers, all of which refer to allocated but currently unused blocks of memory. This allows AST to speed up subsequent Object creation by re-using previously allocated memory blocks rather than allocating new memory using the systems malloc function. The default value for this parameter is zero. Setting it to a non-zero value will result in Object memory being cached in future. Setting it back to zero causes any memory blocks currently in the pool to be freed. Note, this tuning parameter only controls the caching of memory used to store AST Objects. To cache other memory blocks allocated by AST, use MemoryCaching. } \sstsubsection{ MemoryCaching }{ A boolean flag similar to ObjectCaching except that it controls caching of all memory blocks of less than 300 bytes allocated by AST (whether for internal or external use), not just memory used to store AST Objects. } } } \sstroutine{ AST\_TUNEC }{ Set or get a character-valued AST global tuning parameter }{ \sstdescription{ This function returns the current value of a character-valued AST global tuning parameter, optionally storing a new value for the parameter. For integer-valued tuning parameters, see \htmlref{AST\_TUNE}{AST\_TUNE}. } \sstinvocation{ CALL AST\_TUNEC( NAME, VALUE, BUFF, STATUS ) } \sstarguments{ \sstsubsection{ NAME = CHARACTER $*$ ( $*$ ) (Given) }{ The name of the tuning parameter (case-insensitive). } \sstsubsection{ VALUE = CHARACTER $*$ ( ) (Given) }{ The new value for the tuning parameter. If this is AST\_\_TUNULLC, the existing current value will be retained. } \sstsubsection{ BUFF = CHARACTER $*$ ( ) (Given) }{ A character string in which to return the original value of the tuning parameter. An error will be reported if the buffer is too small to hold the value. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem This routine attempts to execute even if STATUS is set to an error value on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem All threads in a process share the same AST tuning parameters values. } } \sstdiylist{ Tuning Parameters }{ \sstsubsection{ HRDel }{ A string to be drawn following the hours field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use (see the Format attribute). This string may include escape sequences to produce super-scripts, etc. (see the Escapes attribute for details of the escape sequences allowed). The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$h\%$+$\texttt{"} which produces a super-script \texttt{"} h\texttt{"} . } \sstsubsection{ MNDel }{ A string to be drawn following the minutes field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$m\%$+$\texttt{"} which produces a super-script \texttt{"} m\texttt{"} . } \sstsubsection{ SCDel }{ A string to be drawn following the seconds field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$s\%$+$\texttt{"} which produces a super-script \texttt{"} s\texttt{"} . } \sstsubsection{ DGDel }{ A string to be drawn following the degrees field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$53$+$\%s60$+$o\%$+$\texttt{"} which produces a super-script \texttt{"} o\texttt{"} . } \sstsubsection{ AMDel }{ A string to be drawn following the arc-minutes field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$20$+$\%s85$+$\texttt{'} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{'} \texttt{"} (single quote). } \sstsubsection{ ASDel }{ A string to be drawn following the arc-seconds field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$20$+$\%s85$+$$\backslash$\texttt{"} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{"} \texttt{"} (double quote). } \sstsubsection{ EXDel }{ A string to be drawn to introduce the exponent in a value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} 10\%-\%$\wedge$50$+$\%s70$+$\texttt{"} which produces \texttt{"} 10\texttt{"} followed by the exponent as a super-script. } } } \sstroutine{ AST\_UINTERP }{ Perform sub-pixel interpolation on a grid of data }{ \sstdescription{ This is a fictitious routine which does not actually exist. Instead, this description constitutes a template so that you may implement a routine with this interface for yourself (and give it any name you wish). Such a routine may be passed via the FINTERP argument of the \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$} functions (q.v.) in order to perform sub-pixel interpolation during resampling of gridded data (you must also set the INTERP argument of AST\_RESAMPLE$<$X$>$ to the value AST\_\_UINTERP). This allows you to use your own interpolation algorithm in addition to those which are pre-defined. The routine interpolates an input grid of data (and, optionally, processes associated statistical variance estimates) at a specified set of points. } \sstinvocation{ CALL AST\_UINTERP( NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR, NPOINT, OFFSET, COORDS, PARAMS, FLAGS, BADVAL, OUT, OUT\_VAR, NBAD, STATUS ) } \sstarguments{ \sstsubsection{ NDIM\_IN = INTEGER (Given) }{ The number of dimensions in the input grid. This will be at least one. } \sstsubsection{ LBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ UBND\_IN( NDIM\_IN ) = INTEGER (Given) }{ An array containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that LBND\_IN and UBND\_IN together define the shape, size and coordinate system of the input grid in the same way as they do in AST\_RESAMPLE$<$X$>$. } \sstsubsection{ IN( $*$ ) = $<$Xtype$>$ (Given) }{ An array, with one element for each pixel in the input grid, containing the input data. This will be the same array as was passed to AST\_RESAMPLE$<$X$>$ via the IN argument. The numerical type of this array should match that of the data being processed. } \sstsubsection{ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given) }{ An optional second array with the same size and type as the IN array. This will only be given if the AST\_\_USEVAR flag is set via the FLAGS argument (below). If given, it will contain the set of variance values associated with the input data and will be the same array as was passed to AST\_RESAMPLE$<$X$>$ via the IN\_VAR argument. If the AST\_\_USEVAR flag is not set, then no variance values are being processed. In this case, this array of variance values may be a dummy (e.g. one-element) array and should not be used. } \sstsubsection{ NPOINT = INTEGER (Given) }{ The number of points at which the input grid is to be interpolated. This will be at least one. } \sstsubsection{ OFFSET( NPOINT ) = INTEGER (Given) }{ For each interpolation point, this array will contain the offset from the start of the OUT (and OUT\_VAR) array(s) at which the interpolated value (and its variance, if required) should be stored. For example, the interpolated value for point number POINT should be stored in OUT(1$+$OFFSET(POINT)). } \sstsubsection{ COORDS( NPOINT, NDIM\_IN ) = DOUBLE PRECISION (Given) }{ A 2-dimensional array containing the coordinates of the points at which interpolation should be performed. These will be stored so that coordinate number COORD for interpolation point number POINT is found in element COORDS(POINT,COORD). If any interpolation point has any of its coordinates equal to the value AST\_\_BAD (as defined in the AST\_PAR include file), then the corresponding output data (and variance) should either be set to the value given by BADVAL, or left unchanged, depending on whether the AST\_\_NOBAD flag is specified by FLAGS. } \sstsubsection{ PARAMS( $*$ ) = DOUBLE PRECISION (Given) }{ This will be the same array as was given via the PARAMS argument of AST\_RESAMPLE$<$X$>$. You may use this to pass any additional parameter values required by your interpolation algorithm. } \sstsubsection{ FLAGS = INTEGER (Given) }{ This will be the same value as was given via the FLAGS argument of AST\_RESAMPLE$<$X$>$. You may test this value to provide additional control over the operation of your resampling algorithm. Note that the special flag values AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see AST\_RESAMPLE$<$X$>$). } \sstsubsection{ BADVAL = $<$Xtype$>$ (Given) }{ This will be the same value as was given for the BADVAL argument of AST\_RESAMPLE$<$X$>$, and will have the same numerical type as the data being processed (i.e. as elements of the IN array). It should be used to test for bad pixels in the input grid (but only if the AST\_\_USEBAD flag is set via the FLAGS argument) and (unless the AST\_\_NOBAD flag is set in FLAGS) for identifying bad output values in the OUT (and OUT\_VAR) array(s). } \sstsubsection{ OUT( $*$ ) = $<$Xtype$>$ (Returned) }{ An array with the same numerical type as the IN array, into which the interpolated data values should be returned. Note that details of the storage order and number of dimensions of this array are not required, since the OFFSET array contains all necessary information about where each returned value should be stored. In general, not all elements of this array (or the OUT\_VAR array below) may be used in any particular invocation of the routine. Those which are not used should be returned unchanged. } \sstsubsection{ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned) }{ An optional array with the same type and size as the OUT array, into which variance estimates for the resampled values should be returned. This array will only be given if the AST\_\_USEVAR flag is set via the FLAGS argument. If given, it is addressed in exactly the same way (via the OFFSET array) as the OUT array. The values returned should be estimates of the statistical variance of the corresponding values in the OUT array, on the assumption that all errors in input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors). If the AST\_\_USEVAR flag is not set, then variance values are not being processed. In this case, this array may be a dummy (e.g. one-element) array and should not be used. } \sstsubsection{ NBAD = INTEGER (Returned) }{ This should return the number of interpolation points at which no valid interpolated value could be obtained. The maximum value that should be returned is NPOINT, and the minimum is zero (indicating that all output values were successfully obtained). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem The data type $<$Xtype$>$ indicates the numerical type of the data being processed, as for AST\_RESAMPLE$<$X$>$. \sstitem This routine will typically be invoked more than once for each invocation of AST\_RESAMPLE$<$X$>$. \sstitem If an error occurs within this routine, it should set the STATUS argument to an error value before returning. This will cause an immediate return from AST\_RESAMPLE$<$X$>$. The error value AST\_\_UINER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). The AST\_\_UINER error value is defined in the AST\_ERR include file. } } } \sstroutine{ AST\_UKERN1 }{ 1-dimensional sub-pixel interpolation kernel }{ \sstdescription{ This is a fictitious routine which does not actually exist. Instead, this description constitutes a template so that you may implement a routine with this interface for yourself (and give it any name you wish). Such a routine may be passed via the FINTERP argument of the \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$} functions (q.v.) in order to supply a 1-dimensional interpolation kernel to the algorithm which performs sub-pixel interpolation during resampling of gridded data (you must also set the INTERP argument of AST\_RESAMPLE$<$X$>$ to the value AST\_\_UKERN1). This allows you to use your own interpolation kernel in addition to those which are pre-defined. The routine calculates the value of a 1-dimensional sub-pixel interpolation kernel. This determines how the weight given to neighbouring pixels in calculating an interpolated value depends on the pixel\texttt{'} s offset from the interpolation point. In more than one dimension, the weight assigned to a pixel is formed by evaluating this 1-dimensional kernel using the offset along each dimension in turn. The product of the returned values is then used as the pixel weight. } \sstinvocation{ CALL AST\_UKERN1( OFFSET, PARAMS, FLAGS, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ OFFSET = DOUBLE PRECISION (Given) }{ This will be the offset of the pixel from the interpolation point, measured in pixels. This value may be positive or negative, but for most practical interpolation schemes its sign should be ignored. } \sstsubsection{ PARAMS( $*$ ) = DOUBLE PRECISION (Given) }{ This will be the same array as was given via the PARAMS argument of AST\_RESAMPLE$<$X$>$. You may use this to pass any additional parameter values required by your kernel, but note that PARAMS(1) will already have been used to specify the number of neighbouring pixels which contribute to the interpolated value. } \sstsubsection{ FLAGS = INTEGER (Given) }{ This will be the same value as was given via the FLAGS argument of AST\_RESAMPLE$<$X$>$. You may test this value to provide additional control over the operation of your routine. Note that the special flag values AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see AST\_RESAMPLE$<$X$>$). } \sstsubsection{ VALUE = DOUBLE PRECISION (Returned) }{ The calculated kernel value, which may be positive or negative. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem Not all functions make good interpolation kernels. In general, acceptable kernels tend to be symmetrical about zero, to have a positive peak (usually unity) at zero, and to evaluate to zero whenever the pixel offset has any other integral value (this ensures that the interpolated values pass through the original data). An interpolation kernel may or may not have regions with negative values. You should consult a good book on image processing for more details. \sstitem If an error occurs within this routine, it should set the STATUS argument to an error value before returning. This will cause an immediate return from AST\_RESAMPLE$<$X$>$. The error value AST\_\_UK1ER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). The AST\_\_UK1ER error value is defined in the AST\_ERR include file. } } } \sstroutine{ AST\_UNFORMAT }{ Read a formatted coordinate value for a Frame axis }{ \sstdescription{ This function reads a formatted coordinate value (given as a character string) for a \htmlref{Frame}{Frame} axis and returns the equivalent numerical (double precision) value. It also returns the number of characters read from the string. The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame\texttt{'} s attributes (in particular, the Format string associated with the Frame\texttt{'} s axis). This function is, in essence, the inverse of \htmlref{AST\_FORMAT}{AST\_FORMAT}. } \sstinvocation{ RESULT = AST\_UNFORMAT( THIS, AXIS, STRING, VALUE, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Frame. } \sstsubsection{ AXIS = INTEGER (Given) }{ The number of the Frame axis for which a coordinate value is to be read (axis numbering starts at 1 for the first axis). } \sstsubsection{ STRING = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing the formatted coordinate value. This string may contain additional information following the value to be read, in which case reading stops at the first character which cannot be interpreted as part of the value. Any white space before or after the value is discarded. } \sstsubsection{ VALUE = DOUBLE PRECISION (Returned) }{ The coordinate value read. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. See the \texttt{"} Frame Input Format\texttt{"} section below for details of the input formats accepted by a basic Frame. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the \texttt{"} SkyFrame Input Format\texttt{"} section below for details of the formats accepted. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The input formats accepted by a FrameSet are determined by its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstreturnedvalue{ \sstsubsection{ AST\_UNFORMAT = INTEGER }{ The number of characters read from the string in order to obtain the coordinate value. This will include any white space which occurs before or after the value. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem Beware that it is possible for a formatting error part-way through an input string to terminate input before it has been completely read, but to yield a coordinate value that appears valid. For example, if a user types \texttt{"} 1.5R6\texttt{"} instead of \texttt{"} 1.5E6\texttt{"} , the \texttt{"} R\texttt{"} will terminate input, giving an incorrect coordinate value of 1.5. It is therefore most important to check the return value of this function to ensure that the correct number of characters have been read. \sstitem An error will result if a value is read which appears to have the correct format, but which cannot be converted into a valid coordinate value (for instance, because the value of one or more of its fields is invalid). \sstitem The string \texttt{"} $<$bad$>$\texttt{"} is recognised as a special case and will yield the coordinate value AST\_\_BAD without error. The test for this string is case-insensitive and also permits embedded white space. \sstitem A function result of zero will be returned and no coordinate value will be returned via the VALUE argument if this function is invoked with the AST error status set, or if it should fail for any reason. } } \sstdiytopic{ Frame Input Format }{ The input format accepted for a basic Frame axis is as follows: \sstitemlist{ \sstitem An optional sign, followed by: \sstitem A sequence of one or more digits possibly containing a decimal point, followed by: \sstitem An optional exponent field. \sstitem The exponent field, if present, consists of \texttt{"} E\texttt{"} or \texttt{"} e\texttt{"} followed by a possibly signed integer. } Examples of acceptable Frame input formats include: \sstitemlist{ \sstitem 99 \sstitem 1.25 \sstitem -1.6 \sstitem 1E8 \sstitem -.99e-17 \sstitem $<$bad$>$ } } \sstdiytopic{ SkyFrame Input Format }{ The input format accepted for a SkyFrame axis is as follows: \sstitemlist{ \sstitem An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. \texttt{"} -12 42 03\texttt{"} ). \sstitem Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as \texttt{"} 124.707\texttt{"} , while degrees and decimal arc-minutes might be given as \texttt{"} -13 33.8\texttt{"} ). \sstitem The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. \texttt{"} 720 45 31\texttt{"} is valid, whereas \texttt{"} 11 45 61\texttt{"} is not). \sstitem Fields may be separated by white space or by \texttt{"} :\texttt{"} (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. \texttt{"} - 2: 04 : 7.1\texttt{"} ). \sstitem The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: \texttt{"} d\texttt{"} ---degrees; \texttt{"} h\texttt{"} ---hours; \texttt{"} m\texttt{"} ---minutes of arc or time; \texttt{"} s\texttt{"} ---seconds of arc or time; \texttt{"} \texttt{'} \texttt{"} (single quote)---minutes of arc; \texttt{"} \texttt{"} \texttt{"} (double quote)---seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. \texttt{"} -11D 3\texttt{'} 14.4\texttt{"} \texttt{"} or \texttt{"} 22h14m11.2s\texttt{"} ). \sstitem The presence of any of the field identification characters \texttt{"} d\texttt{"} , \texttt{"} \texttt{'} \texttt{"} (single quote) or \texttt{"} \texttt{"} \texttt{"} (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of \texttt{"} h\texttt{"} indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. \texttt{"} 10h14\texttt{'} 3\texttt{"} \texttt{"} is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either. \sstitem If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by AST\_FORMAT are correctly interpreted by AST\_UNFORMAT. \sstitem Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. \texttt{"} -05m13s\texttt{"} is equivalent to \texttt{"} -:05:13\texttt{"} ). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. \texttt{"} 14:25.4s\texttt{"} specifies minutes and seconds, while \texttt{"} 14::25.4s\texttt{"} specifies degrees and seconds). \sstitem If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. \texttt{"} 01:02\texttt{"} ), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that AST\_FORMAT would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that AST\_FORMAT would produce. } This final convention is intended to ensure that values formatted by AST\_FORMAT which contain less than three fields will be correctly interpreted if read back using AST\_UNFORMAT, even if they do not contain field identification characters. Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include: \sstitemlist{ \sstitem -14d 13m 22.2s (-14d 13\texttt{'} 22.2\texttt{"} ) \sstitem $+$ 12:34:56.7 (12d 34\texttt{'} 56.7\texttt{"} or 12h 34m 56.7s) \sstitem 001 : 02 : 03.4 (1d 02\texttt{'} 03.4\texttt{"} or 1h 02m 03.4s) \sstitem 22h 30 (22h 30m 00s) \sstitem 136::10\texttt{"} (136d 00\texttt{'} 10\texttt{"} or 136h 00m 10s) \sstitem -14M 27S (-0d 14\texttt{'} 27\texttt{"} or -0h 14m 27s) \sstitem -:14: (-0d 14\texttt{'} 00\texttt{"} or -0h 14m 00s) \sstitem -::4.1 (-0d 00\texttt{'} 04.1\texttt{"} or -0h 00m 04.1s) \sstitem .9\texttt{"} (0d 00\texttt{'} 00.9\texttt{"} ) \sstitem d12m (0d 12\texttt{'} 00\texttt{"} ) \sstitem H 12:22.3s (0h 12m 22.3s) \sstitem $<$bad$>$ (AST\_\_BAD) } Where alternative interpretations are shown, the choice of angle or time depends on the associated \htmlref{Format(axis)}{Format(axis)} attribute. } } \sstroutine{ AST\_UNITMAP }{ Create a UnitMap }{ \sstdescription{ This function creates a new \htmlref{UnitMap}{UnitMap} and optionally initialises its attributes. A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the coordinates supplied to it. They are simply copied. This can be useful if a Mapping is required (e.g. to pass to another routine) but you do not want it to have any effect. } \sstinvocation{ RESULT = AST\_UNITMAP( NCOORD, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of input and output coordinates (these numbers are necessarily the same). } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_UNITMAP = INTEGER }{ A pointer to the new UnitMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_UNITNORMMAP }{ Create a UnitNormMap }{ \sstdescription{ This function creates a new \htmlref{UnitNormMap}{UnitNormMap} and optionally initialises its attributes. The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm. The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. UnitNormMap enables radially symmetric transformations, as follows: \sstitemlist{ \sstitem apply a UnitNormMap to produce a unit vector and norm (radius) \sstitem apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged \sstitem apply the same UnitNormMap in the inverse direction to produce the result } } \sstinvocation{ RESULT = AST\_UNITNORMMAP( NCOORD, CENTRE, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). Output will include one additional coordinate. } \sstsubsection{ CENTRE( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the values to be subtracted from the input coordinates before computing unit vector and norm. A separate value must be supplied for each coordinate. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitNormMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_UNITNORMMAP = INTEGER }{ A pointer to the new UnitNormMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_VERSION }{ Return the version of the AST library being used }{ \sstdescription{ This function returns an integer representing the version of the AST library being used. The library version is formatted as a string such as \texttt{"} 2.0-7\texttt{"} which contains integers representing the \texttt{"} major version\texttt{"} (2), the \texttt{"} minor version\texttt{"} (0) and the \texttt{"} release\texttt{"} (7). The integer returned by this function combines all three integers together into a single integer using the expresion: (major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release) } \sstinvocation{ RESULT = AST\_VERSION() } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ This routine applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ AST\_VERSION = INTEGER }{ The major version, minor version and release numbers for the AST library, encoded as a single integer. } } } \sstroutine{ AST\_WARNINGS }{ Returns any warnings issued by the previous read or write operation }{ \sstdescription{ This function returns an AST \htmlref{KeyMap}{KeyMap} object holding the text of any warnings issued as a result of the previous invocation of the \htmlref{AST\_READ}{AST\_READ} or \htmlref{AST\_WRITE}{AST\_WRITE} function on the \htmlref{Channel}{Channel}. If no warnings were issued, a AST\_\_NULL will be returned. Such warnings are non-fatal and will not prevent the read or write operation succeeding. However, the converted object may not be identical to the original object in all respects. Differences which would usually be deemed as insignificant in most usual cases will generate a warning, whereas more significant differences will generate an error. The \texttt{"} \htmlref{Strict}{Strict}\texttt{"} attribute allows this warning facility to be switched off, so that a fatal error is always reported for any conversion error. } \sstinvocation{ RESULT = AST\_WARNINGS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Channel. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ Channel }{ The basic Channel class generates a warning when ever an un-recognised item is encountered whilst reading an \htmlref{Object}{Object} from an external data source. If Strict is zero (the default), then unexpected items in the Object description are simply ignored, and any remaining items are used to construct the returned Object. If Strict is non-zero, an error will be reported and a NULL Object pointer returned if any unexpected items are encountered. As AST continues to be developed, new attributes are added occasionally to selected classes. If an older version of AST is used to read external Object descriptions created by a more recent version of AST, then the Channel class will, by default, ignore the new attributes, using the remaining attributes to construct the Object. This is usually a good thing. However, since external Object descriptions are often stored in plain text, it is possible to edit them using a text editor. This gives rise to the possibility of genuine errors in the description due to finger-slips, typos, or simple mis-understanding. Such inappropriate attributes will be ignored if Strict is left at its default zero value. This will cause the mis-spelled attribute to revert to its default value, potentially causing subtle changes in the behaviour of application software. If such an effect is suspected, the Strict attribute can be set non-zero, resulting in the erroneous attribute being identified in an error message. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The returned KeyMap will contain warnings for all conditions listed in the \htmlref{Warnings}{Warnings} attribute. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ Reports conversion errors that result in what are usally insignificant changes. } } \sstreturnedvalue{ \sstsubsection{ AST\_WARNINGS = INTEGER }{ A pointer to the KeyMap holding the warning messages, or AST\_\_NULL if no warnings were issued during the previous read operation. } } \sstnotes{ \sstitemlist{ \sstitem The returned KeyMap uses keys of the form \texttt{"} Warning\_1\texttt{"} , \texttt{"} Warning\_2\texttt{"} , etc. \sstitem A value of AST\_\_NULL will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } } \sstroutine{ AST\_WCSMAP }{ Create a WcsMap }{ \sstdescription{ This function creates a new \htmlref{WcsMap}{WcsMap} and optionally initialises its attributes. A WcsMap is used to represent sky coordinate projections as described in the (draft) FITS world coordinate system (FITS-WCS) paper by E.W. Griesen and M. Calabretta (A \& A, in preparation). This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa). A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection plane\texttt{"} coordinates. These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS). The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be associated with each axis. These specify the precise form of the projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is the integer axis index (starting at 1), and m is an integer \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper. } \sstinvocation{ RESULT = AST\_WCSMAP( NCOORD, TYPE, LONAX, LATAX, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). This must be at least 2. The same number is applicable to both input and output points. } \sstsubsection{ TYPE = INTEGER (Given) }{ The type of FITS-WCS projection to apply. This should be given as a symbolic value such as AST\_\_TAN (for a tangent plane projection), where the characters following the double underscore give the projection type code (in upper case) as used in the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword. You should consult the FITS-WCS paper for a list of the available projections. The additional code of AST\_\_TPN can be supplied which represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper. } \sstsubsection{ LONAX = INTEGER (Given) }{ The index of the longitude axis. This should lie in the range 1 to NCOORD. } \sstsubsection{ LATAX = INTEGER (Given) }{ The index of the latitude axis. This should lie in the range 1 to NCOORD and be distinct from LONAX. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new WcsMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. If the sky projection to be implemented requires projection parameter values to be set, then this should normally be done here via the PVi\_m attribute (see the \texttt{"} Examples\texttt{"} section). Setting values for these parameters is mandatory if they do not have default values (as defined in the FITS-WCS paper). } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_WCSMAP = INTEGER }{ A pointer to the new WcsMap. } } \sstexamples{ \sstexamplesubsection{ WCSMAP = AST\_WCSMAP( 2, AST\_\_MER, 1, 2, \texttt{'} \texttt{'} , STATUS ) }{ Creates a WcsMap that implements a FITS-WCS Mercator projection on pairs of coordinates, with coordinates 1 and 2 representing the longitude and latitude respectively. Note that the FITS-WCS Mercator projection does not require any projection parameters. } \sstexamplesubsection{ WCSMAP = AST\_WCSMAP( 3, AST\_\_COE, 2, 3, \texttt{'} PV3\_1=40.0\texttt{'} , STATUS ) }{ Creates a WcsMap that implements a FITS-WCS conical equal area projection. The WcsMap acts on points in a 3-dimensional space; coordinates 2 and 3 represent longitude and latitude respectively, while the values of coordinate 1 are copied unchanged. \htmlref{Projection}{Projection} parameter 1 associatyed with the latitude axis (corresponding to FITS keyword \texttt{"} PV3\_1\texttt{"} ) is required and has no default, so is set explicitly to 40.0 degrees. Projection parameter 2 (corresponding to FITS keyword \texttt{"} PV3\_2\texttt{"} ) is required but has a default of zero, so need not be specified. } } \sstnotes{ \sstitemlist{ \sstitem The forward transformation of a WcsMap converts between FITS-WCS \texttt{"} native spherical\texttt{"} and \texttt{"} relative physical\texttt{"} coordinates, while the inverse transformation converts in the opposite direction. This arrangement may be reversed, if required, by using \htmlref{AST\_INVERT}{AST\_INVERT} or by setting the \htmlref{Invert}{Invert} attribute to a non-zero value. \sstitem If any set of coordinates cannot be transformed (for example, many projections do not cover the entire celestial sphere), then a WcsMap will yield coordinate values of AST\_\_BAD. \sstitem The validity of any projection parameters given via the PVi\_m parameter in the OPTIONS string is not checked by this function. However, their validity is checked when the resulting WcsMap is used to transform coordinates, and an error will result if the projection parameters do not satisfy all the required constraints (as defined in the FITS-WCS paper). \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_WINMAP }{ Create a WinMap }{ \sstdescription{ This function creates a new \htmlref{WinMap}{WinMap} and optionally initialises its attributes. A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes). A WinMap is specified by giving the coordinates of two opposite corners (A and B) of the window in both the input and output coordinate systems. } \sstinvocation{ RESULT = AST\_WINMAP( NCOORD, INA, INB, OUTA, OUTB, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ INA( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of corner A of the window in the input coordinate system. } \sstsubsection{ INB( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of corner B of the window in the input coordinate system. } \sstsubsection{ OUTA( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of corner A of the window in the output coordinate system. } \sstsubsection{ OUTB( NCOORD ) = DOUBLE PRECISION (Given) }{ An array containing the coordinates of corner B of the window in the output coordinate system. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new WinMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_WINMAP = INTEGER }{ A pointer to the new WinMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ AST\_WRITE }{ Write an Object to a Channel }{ \sstdescription{ This function writes an \htmlref{Object}{Object} to a \htmlref{Channel}{Channel}, appending it to any previous Objects written to that Channel. } \sstinvocation{ RESULT = AST\_WRITE( THIS, OBJECT, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the Channel. } \sstsubsection{ OBJECT = INTEGER (Given) }{ Pointer to the Object which is to be written. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather than the native AST encoding, then storing values in the FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking AST\_WRITE can help to produce a successful write. } } \sstreturnedvalue{ \sstsubsection{ AST\_WRITE = INTEGER }{ The number of Objects written to the Channel by this invocation of AST\_WRITE (normally, this will be one). } } \sstnotes{ \sstitemlist{ \sstitem A value of zero will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. \sstitem Invoking this function will usually cause the sink function associated with the channel to be called in order to transfer a textual description of the supplied object to some external data store. However, the FitsChan class behaves differently. Invoking this function on a FitsChan causes new FITS header cards to be added to an internal buffer (the sink function is not invoked). This buffer is written out through the sink function only when the FitsChan is deleted. } } } \sstroutine{ AST\_WRITEFITS }{ Write out all cards in a FitsChan to the sink function }{ \sstdescription{ This routine writes out all cards currently in the \htmlref{FitsChan}{FitsChan}. If the \htmlref{SinkFile}{SinkFile} attribute is set, they will be written out to the specified sink file. Otherwise, they will be written out using the sink function specified when the FitsChan was created. All cards are then deleted from the FitsChan. } \sstinvocation{ CALL AST\_WRITEFITS( THIS, STATUS ) } \sstarguments{ \sstsubsection{ THIS = INTEGER (Given) }{ Pointer to the FitsChan. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstnotes{ \sstitemlist{ \sstitem If the SinkFile is unset, and no sink function is available, this method simply empties the FitsChan, and is then equivalent to \htmlref{AST\_EMPTYFITS}{AST\_EMPTYFITS}. \sstitem This method attempt to execute even if an error has occurred previously. } } } \sstroutine{ AST\_XMLCHAN }{ Create an XmlChan }{ \sstdescription{ This function creates a new \htmlref{XmlChan}{XmlChan} and optionally initialises its attributes. A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O operations. Writing an \htmlref{Object}{Object} to an XmlChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description. Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting XML text. By default, however, an XmlChan will read from standard input and write to standard output. Alternatively, an XmlChan can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstinvocation{ RESULT = AST\_XMLCHAN( SOURCE, SINK, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ SOURCE = SUBROUTINE (Given) }{ A source routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SourceFile attribute, this routine will be used by the XmlChan to obtain lines of input text. On each invocation, it should read the next input line from some external data store, and then return the resulting text to the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a negative line length when there are no more lines to read. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SOURCE value, and no value has been set for the SourceFile attribute, the XmlChan will read from standard input instead. } \sstsubsection{ SINK = SUBROUTINE (Given) }{ A sink routine, which is a subroutine which takes a single integer error status argument. If no value has been set for the SinkFile attribute, this routine will be used by the XmlChan to deliver lines of output text. On each invocation, it should obtain the next output line from the AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the resulting text to some external data store. If an error occurs, it should set its own error status argument to an error value before returning. If the null routine AST\_NULL is suppied as the SINK value, and no value has been set for the SinkFile attribute, the XmlChan will write to standard output instead. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new XmlChan. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_XMLCHAN = INTEGER }{ A pointer to the new XmlChan. } } \sstnotes{ \sstitemlist{ \sstitem The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST\_XMLCHAN. However, this is not generally necessary for the null routine AST\_NULL (so long as the AST\_PAR include file has been used). \sstitem If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST. \sstitem 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. \sstitem Note that the null routine AST\_NULL (one underscore) is different to AST\_\_NULL (two underscores), which is the null Object pointer. } } } \sstroutine{ AST\_ZOOMMAP }{ Create a ZoomMap }{ \sstdescription{ This function creates a new \htmlref{ZoomMap}{ZoomMap} and optionally initialises its attributes. A ZoomMap is a \htmlref{Mapping}{Mapping} which \texttt{"} zooms\texttt{"} a set of points about the origin by multiplying all coordinate values by the same scale factor (the inverse transformation is performed by dividing by this scale factor). } \sstinvocation{ RESULT = AST\_ZOOMMAP( NCOORD, ZOOM, OPTIONS, STATUS ) } \sstarguments{ \sstsubsection{ NCOORD = INTEGER (Given) }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ ZOOM = DOUBLE PRECISION (Given) }{ Initial scale factor by which coordinate values should be multiplied (by the forward transformation) or divided (by the inverse transformation). This factor may subsequently be changed via the ZoomMap\texttt{'} s \htmlref{Zoom}{Zoom} attribute. It may be positive or negative, but should not be zero. } \sstsubsection{ OPTIONS = CHARACTER $*$ ( $*$ ) (Given) }{ A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new ZoomMap. The syntax used is identical to that for the \htmlref{AST\_SET}{AST\_SET} routine. } \sstsubsection{ STATUS = INTEGER (Given and Returned) }{ The global status. } } \sstreturnedvalue{ \sstsubsection{ AST\_ZOOMMAP = INTEGER }{ A pointer to the new ZoomMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \normalsize \cleardoublepage \section{\label{ss:attributedescriptions}AST Attribute Descriptions} \small \sstroutine{ Abbrev(axis) }{ Abbreviate leading fields within numerical axis labels? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether matching leading fields should be removed from adjacent numerical axis labels. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} Abbrev(2)=0\texttt{"} specifies that matching leading fields should not be removed on the second axis. If the Abbrev value of a Plot is non-zero (the default), then leading fields will be removed from adjacent axis labels if they are equal. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} Abbrev\texttt{"} instead of \texttt{"} Abbrev(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Abbrev(1) value. } } } \sstroutine{ Adaptive }{ Should the area adapt to changes in the coordinate system? }{ \sstdescription{ The coordinate system represented by a \htmlref{Region}{Region} may be changed by assigning new values to attributes such as \htmlref{System}{System}, Unit, etc. For instance, a Region representing an area on the sky in ICRS coordinates may have its System attribute changed so that it represents (say) Galactic coordinates instead of ICRS. This attribute controls what happens when the coordinate system represented by a Region is changed in this way. If Adaptive is non-zero (the default), then area represented by the Region adapts to the new coordinate system. That is, the numerical values which define the area represented by the Region are changed by mapping them from the old coordinate system into the new coordinate system. Thus the Region continues to represent the same physical area. If Adaptive is zero, then area represented by the Region does not adapt to the new coordinate system. That is, the numerical values which define the area represented by the Region are left unchanged. Thus the physical area represented by the Region will usually change. As an example, consider a Region describe a range of wavelength from 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region is changed from Angstrom to \texttt{"} nm\texttt{"} (nanometre), what happens depends on the setting of Adaptive. If Adaptive is non-zero, the \htmlref{Mapping}{Mapping} from the old to the new coordinate system is found. In this case it is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). This Mapping is then used to modify the numerical values within the Region, changing 2000 to 200 and 4000 to 400. Thus the modified region represents 200 nm to 400 nm, the same physical space as the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive had been zero, then the numerical values would not have been changed, resulting in the final Region representing 2000 nm to 4000 nm. Setting Adaptive to zero can be necessary if you want correct inaccurate attribute settings in an existing Region. For instance, when creating a Region you may not know what \htmlref{Epoch}{Epoch} value to use, so you would leave Epoch unset resulting in some default value being used. If at some later point in the application, the correct Epoch value is determined, you could assign the correct value to the Epoch attribute. However, you would first need to set Adaptive temporarily to zero, because otherwise the area represented by the Region would be Mapped from the spurious default Epoch to the new correct Epoch, which is not what is required. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ AlignOffset }{ Align SkyFrames using the offset coordinate system? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{SkyFrame}{SkyFrame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) as a template to match another (target) SkyFrame. It determines the coordinate system in which the two SkyFrames are aligned if a match occurs. If the template and target SkyFrames both have defined offset coordinate systems (i.e. the \htmlref{SkyRefIs}{SkyRefIs} attribute is set to either \texttt{"} Origin\texttt{"} or \texttt{"} Pole\texttt{"} ), and they both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). If either the template or target SkyFrame has zero (the default value) for AlignOffset, or if either SkyFrame has SkyRefIs set to \texttt{"} Ignored\texttt{"} , then alignment occurring within the coordinate system specified by the \htmlref{AlignSystem}{AlignSystem} attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ AlignSideBand }{ Should the SideBand attribute be taken into account when aligning this \htmlref{DSBSpecFrame}{DSBSpecFrame} with another DSBSpecFrame? }{ \sstdescription{ This attribute controls how a DSBSpecFrame behaves when an attempt is made to align it with another DSBSpecFrame using \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}. If both DSBSpecFrames have a non-zero value for AlignSideBand, the value of the \htmlref{SideBand}{SideBand} attribute in each DSBSpecFrame is used so that alignment occurs between sidebands. That is, if one DSBSpecFrame represents USB and the other represents LSB then AST\_FINDFRAME and AST\_CONVERT will recognise that the DSBSpecFrames represent different sidebands and will take this into account when constructing the \htmlref{Mapping}{Mapping} that maps positions in one DSBSpecFrame into the other. If AlignSideBand in either DSBSpecFrame is set to zero, then the values of the SideBand attributes are ignored. In the above example, this would result in a frequency in the first DSBSpecFrame being mapped onto the same frequency in the second DSBSpecFrame, even though those frequencies refer to different sidebands. In other words, if either AlignSideBand attribute is zero, then the two DSBSpecFrames aligns like basic SpecFrames. The default value for AlignSideBand is zero. When AST\_FINDFRAME or AST\_CONVERT is used on two DSBSpecFrames (potentially describing different spectral coordinate systems and/or sidebands), it returns a Mapping which can be used to transform a position in one DSBSpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the target\texttt{'} s current sideband (given by its SideBand attribute) to the observed sideband (whether USB or LSB). If the target already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted. \sstitem Map the values from the spectral system of the target to the spectral system of the template. This Mapping takes into account all the inherited \htmlref{SpecFrame}{SpecFrame} attributes such as \htmlref{System}{System}, \htmlref{StdOfRest}{StdOfRest}, Unit, etc. \sstitem If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the result\texttt{'} s observed sideband to the result\texttt{'} s current sideband (given by its SideBand attribute). If the result already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted. } } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ AlignSpecOffset }{ Align SpecFrames using the offset coordinate system? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) as a template to match another (target) SpecFrame. It determines whether alignment occurs between the offset values defined by the current value of the SpecOffset attribute, or between the corresponding absolute spectral values. The default value of zero results in the two SpecFrames being aligned so that a given absolute spectral value in one is mapped to the same absolute value in the other. A non-zero value results in the SpecFrames being aligned so that a given offset value in one is mapped to the same offset value in the other. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ AlignStdOfRest }{ Standard of rest to use when aligning SpecFrames }{ \sstdescription{ This attribute controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) as a template to match another (target) SpecFrame. It identifies the standard of rest in which alignment is to occur. See the \htmlref{StdOfRest}{StdOfRest} attribute for a desription of the values which may be assigned to this attribute. The default AlignStdOfRest value is \texttt{"} Helio\texttt{"} (heliographic). When AST\_FindFrame or AST\_CONVERT is used on two SpecFrames (potentially describing different spectral coordinate systems), it returns a \htmlref{Mapping}{Mapping} which can be used to transform a position in one SpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem Map values from the system used by the target (wavelength, apparent radial velocity, etc) to the system specified by the \htmlref{AlignSystem}{AlignSystem} attribute, using the target\texttt{'} s rest frequency if necessary. \sstitem Map these values from the target\texttt{'} s standard of rest to the standard of rest specified by the AlignStdOfRest attribute, using the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{RefDec}{RefDec} and \htmlref{RefRA}{RefRA} attributes of the target to define the two standards of rest. \sstitem Map these values from the standard of rest specified by the AlignStdOfRest attribute, to the template\texttt{'} s standard of rest, using the Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the template to define the two standards of rest. \sstitem Map these values from the system specified by the AlignSystem attribute, to the system used by the template, using the template\texttt{'} s rest frequency if necessary. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ AlignSystem }{ Coordinate system in which to align the Frame }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) as a template to match another (target) Frame. It identifies the coordinate system in which the two Frames will be aligned by the match. The values which may be assigned to this attribute, and its default value, depend on the class of Frame and are described in the \texttt{"} Applicability\texttt{"} section below. In general, the AlignSystem attribute will accept any of the values which may be assigned to the \htmlref{System}{System} attribute. The \htmlref{Mapping}{Mapping} returned by astFindFrame or astConvert will use the coordinate system specified by the AlignSystem attribute as an intermediate coordinate system. The total returned Mapping will first map positions from the first Frame into this intermediate coordinate system, using the attributes of the first Frame. It will then map these positions from the intermediate coordinate system into the second Frame, using the attributes of the second Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The AlignSystem attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The AlignSystem attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The AlignSystem attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The default AlignSystem attribute for a SkyFrame is \texttt{"} ICRS\texttt{"} . } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The default AlignSystem attribute for a SpecFrame is \texttt{"} Wave\texttt{"} (wavelength). } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The default AlignSystem attribute for a TimeFrame is \texttt{"} MJD\texttt{"} . } } } \sstroutine{ AlignTimeScale }{ Time scale to use when aligning TimeFrames }{ \sstdescription{ This attribute controls how a \htmlref{TimeFrame}{TimeFrame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) as a template to match another (target) TimeFrame. It identifies the time scale in which alignment is to occur. See the \htmlref{TimeScale}{TimeScale} attribute for a desription of the values which may be assigned to this attribute. The default AlignTimeScale value depends on the current value of TimeScale: if TimeScale is UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all other TimeScales the default is TAI. When AST\_FindFrame or AST\_CONVERT is used on two TimeFrames (potentially describing different time coordinate systems), it returns a \htmlref{Mapping}{Mapping} which can be used to transform a position in one TimeFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem Map values from the system used by the target (MJD, JD, etc) to the system specified by the \htmlref{AlignSystem}{AlignSystem} attribute. \sstitem Map these values from the target\texttt{'} s time scale to the time scale specified by the AlignTimeScale attribute. \sstitem Map these values from the time scale specified by the AlignTimeScale attribute, to the template\texttt{'} s time scale. \sstitem Map these values from the system specified by the AlignSystem attribute, to the system used by the template. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } } \sstroutine{ AllVariants }{ A list of the variant Mappings associated with the current Frame }{ \sstdescription{ This attrbute gives a space separated list of the names of all the variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the current Frame. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ All FrameSets have this attribute. } } } \sstroutine{ AllWarnings }{ A list of all currently available condition names }{ \sstdescription{ This read-only attribute is a space separated list of all the conditions names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed below. } \sstattributetype{ String, read-only } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } \sstdiytopic{ Conditions }{ The following conditions are currently recognised (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a non-Native encoded FitsChan if an unknown celestial co-ordinate system is specified by the CTYPE keywords. \sstitem \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if an illegal algorithm code is specified by a CTYPE keyword, and the illegal code can be converted to an equivalent legal code. \sstitem \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is encountered that contains an illegal character (i.e. one not allowed by the FITS standard). \sstitem \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword cannot be determined from the content of the header card. \sstitem \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if the latitude of the reference point has an absolute value greater than 90 degrees. The actual absolute value used is set to exactly 90 degrees in these cases. \sstitem \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the transformation from pixel offsets to intermediate world coordinates cannot be inverted. This matrix describes the scaling, rotation, shear, etc., applied to the pixel axes, and is specified by keywords such as PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable if any rows or columns consist entirely of zeros. The FITS-WCS Paper I \texttt{"} Representation of World Coordinates in FITS\texttt{"} by Greisen \& Calabretta requires that this matrix be invertable. Many operations (such as grid plotting) will not be possible if the matrix cannot be inverted. \sstitem \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found that refers to a projection parameter that is not used by the projection type specified by CTYPE, or the PV values are otherwise inappropriate for the projection type. \sstitem \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if it is not possible to convert the value of a FITS keywords to the expected type. For instance, this can occur if the FITS header contains a string value for a keyword which should have a floating point value, or if the keyword has no value at all (i.e. is a comment card). \sstitem \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if any of the CTYPE keywords specify an unsupported distortion code using the \texttt{"} 4-3-3\texttt{"} format specified in FITS-WCS paper IV. Such distortion codes are ignored. \sstitem \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used within \htmlref{AST\_READ}{AST\_READ}, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoEquinox\texttt{"} : This condition arises if a default equinox value is used within AST\_READ, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoRadesys\texttt{"} : This condition arises if a default reference frame is used for an equatorial co-ordinate system within AST\_READ, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoLonpole\texttt{"} : This condition arises if a default value is used for the LONPOLE keyword within AST\_READ, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoLatpole\texttt{"} : This condition arises if a default value is used for the LATPOLE keyword within AST\_READ, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoMjd-obs\texttt{"} : This condition arises if a default value is used for the date of observation within AST\_READ, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} Tnx\texttt{"} : This condition arises if a FrameSet is read from a FITS header containing an IRAF \texttt{"} TNX\texttt{"} projection which includes terms not supproted by AST. Such terms are ignored and so the resulting FrameSet may be inaccurate. \sstitem \texttt{"} Zpx\texttt{"} : This condition arises if a FrameSet is read from a FITS header containing an IRAF \texttt{"} ZPX\texttt{"} projection which includes \texttt{"} lngcor\texttt{"} or \texttt{"} latcor\texttt{"} correction terms. These terms are not supported by AST and are ignored. The resulting FrameSet may therefore be inaccurate. } } } \sstroutine{ AsTime(axis) }{ Format celestal coordinates as times? }{ \sstdescription{ This attribute specifies the default style of formatting to be used (e.g. by \htmlref{AST\_FORMAT}{AST\_FORMAT}) for the celestial coordinate values described by a \htmlref{SkyFrame}{SkyFrame}. It takes a separate boolean value for each SkyFrame axis so that, for instance, the setting \texttt{"} AsTime(2)=0\texttt{"} specifies the default formatting style for celestial latitude values. If the AsTime attribute for a SkyFrame axis is zero, then coordinates on that axis will be formatted as angles by default (using degrees, minutes and seconds), otherwise they will be formatted as times (using hours, minutes and seconds). The default value of AsTime is chosen according to the sky coordinate system being represented, as determined by the SkyFrame\texttt{'} s \htmlref{System}{System} attribute. This ensures, for example, that right ascension values will be formatted as times by default, following normal conventions. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The AsTime attribute operates by changing the default value of the corresponding \htmlref{Format(axis)}{Format(axis)} attribute. This, in turn, may also affect the value of the \htmlref{Unit(axis)}{Unit(axis)} attribute. \sstitem Only the default style of formatting is affected by the AsTime value. If an explicit Format(axis) value is set, it will over-ride any effect from the AsTime attribute. } } } \sstroutine{ Base }{ FrameSet base Frame index }{ \sstdescription{ This attribute gives the index of the \htmlref{Frame}{Frame} which is to be regarded as the \texttt{"} base\texttt{"} Frame within a \htmlref{FrameSet}{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 \htmlref{Domain}{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. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Inverting a FrameSet (inverting the boolean sense of its \htmlref{Invert}{Invert} attribute, with the \htmlref{AST\_INVERT}{AST\_INVERT} routine for example) will interchange the values of its Base and \htmlref{Current}{Current} attributes. } } } \sstroutine{ Border }{ Draw a border around valid regions of a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether a border is drawn around regions corresponding to the valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{AST\_BORDER}{AST\_BORDER}). If the Border value of a Plot is non-zero, then this border will be drawn as part of the grid. Otherwise, the border is not drawn (although axis labels and tick marks will still appear, unless other relevant Plot attributes indicate that they should not). The default behaviour is to draw the border if tick marks and numerical labels will be drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit it otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ Bottom(axis) }{ Lowest axis value to display }{ \sstdescription{ This attribute gives the lowest axis value to be displayed (for instance, by the \htmlref{AST\_GRID}{AST\_GRID} method). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ The default supplied by the Frame class is to display all axis values, without any limit. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Bottom value to -90 degrees for latitude axes, and 0 degrees for co-latitude axes. The default for longitude axes is to display all axis values. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ Bounded }{ Is the Region bounded? }{ \sstdescription{ This is a read-only attribute indicating if the \htmlref{Region}{Region} is bounded. A Region is bounded if it is contained entirely within some finite-size bounding box. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ CDMatrix }{ Use CDi\_j keywords to represent pixel scaling, rotation, etc? }{ \sstdescription{ This attribute is a boolean value which specifies how the linear transformation from pixel coordinates to intermediate world coordinates should be represented within a \htmlref{FitsChan}{FitsChan} when using FITS-WCS encoding. This transformation describes the scaling, rotation, shear, etc., of the pixel axes. If the attribute has a non-zero value then the transformation is represented by a set of CDi\_j keywords representing a square matrix (where \texttt{"} i\texttt{"} is the index of an intermediate world coordinate axis and \texttt{"} j\texttt{"} is the index of a pixel axis). If the attribute has a zero value the transformation is represented by a set of PCi\_j keywords (which also represent a square matrix) together with a corresponding set of CDELTi keywords representing the axis scalings. See FITS-WCS paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by M. Calabretta \& E.W. Greisen, for a complete description of these two schemes. The default value of the CDMatrix attribute is determined by the contents of the FitsChan at the time the attribute is accessed. If the FitsChan contains any CDi\_j keywords then the default value is non-zero. Otherwise it is zero. Note, reading a \htmlref{FrameSet}{FrameSet} from a FitsChan will in general consume any CDi\_j keywords present in the FitsChan. Thus the default value for CDMatrix following a read will usually be zero, even if the FitsChan originally contained some CDi\_j keywords. This behaviour is similar to that of the \htmlref{Encoding}{Encoding} attribute, the default value for which is determined by the contents of the FitsChan at the time the attribute is accessed. If you wish to retain the original value of the CDMatrix attribute (that is, the value before reading the FrameSet) then you should enquire the default value before doing the read, and then set that value explicitly. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CarLin }{ Ignore spherical rotations on CAR projections? }{ \sstdescription{ This attribute is a boolean value which specifies how FITS \texttt{"} CAR\texttt{"} (plate carree, or \texttt{"} Cartesian\texttt{"} ) projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero (the default), it is assumed that the CAR projection conforms to the conventions described in the FITS world coordinate system (FITS-WCS) paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by M. Calabretta \& E.W. Greisen. If CarLin is non-zero, then these conventions are ignored, and it is assumed that the mapping from pixel coordinates to celestial coordinates is a simple linear transformation (hence the attribute name \texttt{"} CarLin\texttt{"} ). This is appropriate for some older FITS data which claims to have a \texttt{"} CAR\texttt{"} projection, but which in fact do not conform to the conventions of the FITS-WCS paper. The FITS-WCS paper specifies that headers which include a CAR projection represent a linear mapping from pixel coordinates to \texttt{"} native spherical coordinates\texttt{"} , NOT celestial coordinates. An extra mapping is then required from native spherical to celestial. This mapping is a 3D rotation and so the overall \htmlref{Mapping}{Mapping} from pixel to celestial coordinates is NOT linear. See the FITS-WCS papers for further details. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } } \sstroutine{ Card }{ Index of current FITS card in a FitsChan }{ \sstdescription{ This attribute gives the index of the \texttt{"} current\texttt{"} FITS header card within a \htmlref{FitsChan}{FitsChan}, the first card having an index of 1. The choice of current card affects the behaviour of routines that access the contents of the FitsChan, such as \htmlref{AST\_DELFITS}{AST\_DELFITS}, \htmlref{AST\_FINDFITS}{AST\_FINDFITS} and \htmlref{AST\_PUTFITS}{AST\_PUTFITS}. A value assigned to Card will position the FitsChan at any desired point, so that a particular card within it can be accessed. Alternatively, the value of Card may be enquired in order to determine the current position of a FitsChan. The default value of Card is 1. This means that clearing this attribute (using \htmlref{AST\_CLEAR}{AST\_CLEAR}) effectively \texttt{"} rewinds\texttt{"} the FitsChan, so that the first card is accessed next. If Card is set to a value which exceeds the total number of cards in the FitsChan (as given by its \htmlref{Ncard}{Ncard} attribute), it is regarded as pointing at the \texttt{"} end-of-file\texttt{"} . In this case, the value returned in response to an enquiry is always one more than the number of cards in the FitsChan. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardComm }{ The comment for the current card in a FitsChan }{ \sstdescription{ This attribute gives the comment for the current card of the \htmlref{FitsChan}{FitsChan}. A zero-length string is returned if the card has no comment. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardName }{ The keyword name of the current card in a FitsChan }{ \sstdescription{ This attribute gives the name of the keyword for the current card of the \htmlref{FitsChan}{FitsChan}. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardType }{ The data type of the current card in a FitsChan }{ \sstdescription{ This attribute gives the data type of the keyword value for the current card of the \htmlref{FitsChan}{FitsChan}. It will be one of the following integer constants: AST\_\_NOTYPE, AST\_\_COMMENT, AST\_\_INT, AST\_\_FLOAT, AST\_\_STRING, AST\_\_COMPLEXF, AST\_\_COMPLEXI, AST\_\_LOGICAL, AST\_\_CONTINUE, AST\_\_UNDEF. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Class }{ Object class name }{ \sstdescription{ This attribute gives the name of the class to which an \htmlref{Object}{Object} belongs. } \sstattributetype{ Character string, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Clean }{ Remove cards used whilst reading even if an error occurs? }{ \sstdescription{ This attribute indicates whether or not cards should be removed from the \htmlref{FitsChan}{FitsChan} if an error occurs within \htmlref{AST\_READ}{AST\_READ}. A succesful read on a FitsChan always results in the removal of the cards which were involved in the description of the returned \htmlref{Object}{Object}. However, in the event of an error during the read (for instance if the cards in the FitsChan have illegal values, or if some required cards are missing) no cards will be removed from the FitsChan if the Clean attribute is zero (the default). If Clean is non-zero then any cards which were used in the aborted attempt to read an object will be removed. This provides a means of \texttt{"} cleaning\texttt{"} a FitsChan of WCS related cards which works even in the event of the cards not forming a legal WCS description. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Clip }{ Clip lines and/or markers at the Plot boundary? }{ \sstdescription{ This attribute controls whether curves and markers are clipped at the boundary of the graphics box specified when the \htmlref{Plot}{Plot} was created. A value of 3 implies both markers and curves are clipped at the Plot boundary. A value of 2 implies markers are clipped, but not curves. A value of 1 implies curves are clipped, but not markers. A value of zero implies neither curves nor markers are clipped. The default value is 1. Note, this attributes controls only the clipping performed internally within AST. The underlying graphics system may also apply clipping. In such cases, removing clipping using this attribute does not guarantee that no clipping will be visible in the final plot. The \htmlref{AST\_CLIP}{AST\_CLIP} routine can be used to establish generalised clipping within arbitrary regions of the Plot. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ ClipOp }{ Combine Plot clipping limits using a boolean OR? }{ \sstdescription{ This attribute controls how the clipping limits specified for each axis of a \htmlref{Plot}{Plot} (using the \htmlref{AST\_CLIP}{AST\_CLIP} routine) are combined. This, in turn, determines which parts of the graphical output will be visible. If the ClipOp attribute of a Plot is zero (the default), graphical output is visible only if it satisfies the clipping limits on all the axes of the clipping \htmlref{Frame}{Frame} (a boolean AND). Otherwise, if ClipOp is non-zero, output is visible if it satisfies the clipping limits on one or more axes (a boolean OR). An important use of this attribute is to allow areas of a Plot to be left clear (e.g. as a background for some text). To achieve this, the lower and upper clipping bounds supplied to AST\_CLIP should be reversed, and the ClipOp attribute of the Plot should be set to a non-zero value. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ Closed }{ Should the boundary be considered to be inside the region? }{ \sstdescription{ This attribute controls whether points on the boundary of a \htmlref{Region}{Region} are considered to be inside or outside the region. If the attribute value is non-zero (the default), points on the boundary are considered to be inside the region (that is, the Region is \texttt{"} closed\texttt{"} ). However, if the attribute value is zero, points on the bounary are considered to be outside the region. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{PointList}{PointList} }{ The value of the Closed attribute is ignored by PointList regions. If the PointList region has not been negated, then it is always assumed to be closed. If the PointList region has been negated, then it is always assumed to be open. This is required since points have zero volume and therefore consist entirely of boundary. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default Closed value for a CmpRegion is the Closed value of its first component Region. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default Closed value for an Stc is the Closed value of its encapsulated Region. } } } \sstroutine{ Colour(element) }{ Colour index for a Plot element }{ \sstdescription{ This attribute determines the colour index used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Colour(title)=2\texttt{"} causes the Plot title to be drawn using colour index 2. The synonym \texttt{"} Color\texttt{"} may also be used. The range of integer colour indices available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default colour index supplied by this graphics system (normally, this is likely to result in white plotting on a black background, or vice versa). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Colour\texttt{"} instead of \texttt{"} Colour(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Colour(TextLab) value. } } } \sstroutine{ ColumnLenC(column) }{ The largest string length of any value in a column }{ \sstdescription{ This attribute holds the minimum length which a character variable must have in order to be able to store the longest value currently present (at any row) in a specified column of the supplied \htmlref{Table}{Table}. The required column name should be placed inside the parentheses in the attribute name. If the named column holds vector values, then the attribute value is the length of the longest element of the vector value. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Table }{ All Tables have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the named column holds numerical values, the length returned is the length of the largest string that would be generated if the column values were accessed as strings. } } } \sstroutine{ ColumnLength(column) }{ The number of elements in each value in a column }{ \sstdescription{ This attribute holds the number of elements in each value stored in a named column. Each value can be a scalar (in which case the ColumnLength attribute has a value of 1), or a multi-dimensional array ( in which case the ColumnLength value is equal to the product of the array dimensions). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ ColumnNdim(column) }{ The number of axes spanned by each value in a column }{ \sstdescription{ This attribute holds the number of axes spanned by each value in a column. If each cell in the column is a scalar, ColumnNdim will be zero. If each cell in the column is a 1D spectrum, ColumnNdim will be one. If each cell in the column is a 2D image, ColumnNdim will be two, etc. The required column name should be placed inside the parentheses in the attribute name. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ ColumnType(column) }{ The data type of each value in a column }{ \sstdescription{ This attribute holds a integer value indicating the data type of a named column in a \htmlref{Table}{Table}. This is the data type which was used when the column was added to the Table using astAddColumn. The required column name should be placed inside the parentheses in the attribute name. The attribute value will be one of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for INTEGER$*$2), AST\_\_BYTETYPE (for bytes), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Table }{ All Tables have this attribute. } } } \sstroutine{ Comment }{ Include textual comments in output? }{ \sstdescription{ This is a boolean attribute which controls whether textual comments are to be included in the output generated by a \htmlref{Channel}{Channel}. If included, they will describe what each item of output represents. If Comment is non-zero, then comments will be included. If it is zero, comments will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ The default value is non-zero for a normal Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The default value is non-zero for a FitsChan. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value is zero for an XmlChan. } } } \sstroutine{ Current }{ FrameSet current Frame index }{ \sstdescription{ This attribute gives the index of the \htmlref{Frame}{Frame} which is to be regarded as the \texttt{"} current\texttt{"} Frame within a \htmlref{FrameSet}{FrameSet}. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet\texttt{'} s \htmlref{Nframe}{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 \htmlref{Domain}{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. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Inverting a FrameSet (inverting the boolean sense of its \htmlref{Invert}{Invert} attribute, with the \htmlref{AST\_INVERT}{AST\_INVERT} routine for example) will interchange the values of its \htmlref{Base}{Base} and Current attributes. } } } \sstroutine{ DSBCentre }{ The central position of interest in a dual sideband spectrum }{ \sstdescription{ This attribute specifies the central position of interest in a dual sideband spectrum. Its sole use is to determine the local oscillator frequency (the frequency which marks the boundary between the lower and upper sidebands). See the description of the \htmlref{IF}{IF} (intermediate frequency) attribute for details of how the local oscillator frequency is calculated. The sideband containing this central position is referred to as the \texttt{"} observed\texttt{"} sideband, and the other sideband as the \texttt{"} image\texttt{"} sideband. The value is accessed as a position in the spectral system represented by the \htmlref{SpecFrame}{SpecFrame} attributes inherited by this class, but is stored internally as topocentric frequency. Thus, if the \htmlref{System}{System} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} is set to \texttt{"} VRAD\texttt{"} , the Unit attribute set to \texttt{"} m/s\texttt{"} and the \htmlref{StdOfRest}{StdOfRest} attribute set to \texttt{"} LSRK\texttt{"} , then values for the DSBCentre attribute should be supplied as radio velocity in units of \texttt{"} m/s\texttt{"} relative to the kinematic LSR (alternative units may be used by appending a suitable units string to the end of the value). This value is then converted to topocentric frequency and stored. If (say) the Unit attribute is subsequently changed to \texttt{"} km/s\texttt{"} before retrieving the current value of the DSBCentre attribute, the stored topocentric frequency will be converted back to LSRK radio velocity, this time in units of \texttt{"} km/s\texttt{"} , before being returned. The default value for this attribute is 30 GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } \sstdiytopic{ Note }{ \sstitemlist{ \sstitem The attributes which define the transformation to or from topocentric frequency should be assigned their correct values before accessing this attribute. These potentially include System, Unit, StdOfRest, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec} and \htmlref{RestFreq}{RestFreq}. } } } \sstroutine{ DefB1950 }{ Use FK4 B1950 as defaults? }{ \sstdescription{ This attribute is a boolean value which specifies a default equinox and reference frame to use when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} with a foreign (i.e. non-native) encoding. It is only used if the FITS header contains RA and DEC axes but contains no information about the reference frame or equinox. If this is the case, then values of FK4 and B1950 are assumed if the DefB1950 attribute has a non-zero value and ICRS is assumed if DefB1950 is zero. The default value for DefB1950 depends on the value of the \htmlref{Encoding}{Encoding} attribute: for FITS-WCS encoding the default is zero, and for all other encodings it is one. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Digits/Digits(axis) }{ Number of digits of precision }{ \sstdescription{ This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a \htmlref{Frame}{Frame} axis (e.g. using \htmlref{AST\_FORMAT}{AST\_FORMAT}). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole. Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string \texttt{"} .$*$\texttt{"} , then the Digits attribute is used to determine the number of decimal places to produce. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{Plot}{Plot} }{ The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute). } } } \sstroutine{ Direction(axis) }{ Display axis in conventional direction? }{ \sstdescription{ This attribute is a boolean value which suggests how the axes of a \htmlref{Frame}{Frame} should be displayed (e.g.) in graphical output. By default, it has the value one, indicating that they should be shown in the conventional sense (increasing left to right for an abscissa, and bottom to top for an ordinate). If set to zero, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ The default Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{Plot}{Plot} }{ The Direction attribute of the base Frame in a Plot is set to indicate the sense of the two graphics axes, as implied by the graphics bounding box supplied when the Plot was created. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. \sstitem The Direction attribute does not directly affect the behaviour of the AST library. Instead, it serves as a hint to applications programs about the orientation in which they may wish to display any data associated with the Frame. Applications are free to ignore this hint if they wish. } } } \sstroutine{ Disco }{ PcdMap pincushion/barrel distortion coefficient }{ \sstdescription{ This attribute specifies the pincushion/barrel distortion coefficient used by a \htmlref{PcdMap}{PcdMap}. This coefficient is set when the PcdMap is created, but may later be modified. If the attribute is cleared, its default value is zero, which gives no distortion. For pincushion distortion, the value should be positive. For barrel distortion, it should be negative. Note that the forward transformation of a PcdMap applies the distortion specified by this attribute and the inverse transformation removes this distortion. If the PcdMap is inverted (e.g. using \htmlref{AST\_INVERT}{AST\_INVERT}), then the forward transformation will remove the distortion and the inverse transformation will apply it. The distortion itself will still be given by the same value of Disco. Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ PcdMap }{ All PcdMaps have this attribute. } } } \sstroutine{ Domain }{ Coordinate system domain }{ \sstdescription{ This attribute contains a string which identifies the physical domain of the coordinate system that a \htmlref{Frame}{Frame} describes. The Domain attribute also controls how a Frame behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It does this by specifying the Domain that the target Frame should have in order to match the template. If the Domain value in the template Frame is set, then only targets with the same Domain value will be matched. If the template\texttt{'} s Domain value is not set, however, then the target\texttt{'} s Domain will be ignored. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default Domain value supplied by the Frame class is an empty string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Domain value to be \texttt{"} SKY\texttt{"} . } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The CmpFrame class re-defines the default Domain value to be of the form \texttt{"} $<$dom1$>$-$<$dom2$>$\texttt{"} , where $<$dom1$>$ and $<$dom2$>$ are the Domains of the two component Frames. If both these Domains are blank, then the string \texttt{"} CMP\texttt{"} is used as the default Domain name. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The SpecFrame class re-defines the default Domain value to be \texttt{"} SPECTRUM\texttt{"} . } \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ The DSBSpecFrame class re-defines the default Domain value to be \texttt{"} DSBSPECTRUM\texttt{"} . } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The FluxFrame class re-defines the default Domain value to be \texttt{"} FLUX\texttt{"} . } \sstsubsection{ \htmlref{SpecFluxFrame}{SpecFluxFrame} }{ The FluxFrame class re-defines the default Domain value to be \texttt{"} SPECTRUM-FLUX\texttt{"} . } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Domain value to be \texttt{"} TIME\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem All Domain values are converted to upper case and white space is removed before use. } } } \sstroutine{ DrawAxes(axis) }{ Draw axes for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether curves representing coordinate axes should be drawn. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} DrawAxes(2)=0\texttt{"} specifies that no axis should be drawn for the second axis. If drawn, these axis lines will pass through any tick marks associated with numerical labels drawn to mark values on the axes. The location of these tick marks and labels (and hence the axis lines) is determined by the Plot\texttt{'} s \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute. If the DrawAxes value of a Plot is non-zero (the default), then axis lines will be drawn, otherwise they will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem \htmlref{Axis}{Axis} lines are drawn independently of any coordinate grid lines (see the \htmlref{Grid}{Grid} attribute) so grid lines may be used to substitute for axis lines if required. \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the DrawAxes attribute is ignored. \sstitem If no axis is specified, (e.g. \texttt{"} DrawAxes\texttt{"} instead of \texttt{"} DrawAxes(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the DrawAxes(1) value. } } } \sstroutine{ DrawTitle }{ Draw a title for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether a title is drawn. If the DrawTitle value of a \htmlref{Plot}{Plot} is non-zero (the default), then the title will be drawn, otherwise it will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes, assuming a value of zero. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the title is obtained from the Plot\texttt{'} s \htmlref{Title}{Title} attribute. \sstitem The vertical placement of the title can be controlled using the \htmlref{TitleGap}{TitleGap} attribute. } } } \sstroutine{ Dut1 }{ The UT1-UTC correction }{ \sstdescription{ This attribute is used when calculating the Local Apparent Sidereal Time corresponding to \htmlref{SkyFrame}{SkyFrame}\texttt{'} s \htmlref{Epoch}{Epoch} value (used when converting positions to or from the \texttt{"} AzEl\texttt{"} system). It should be set to the difference, in seconds, between the UT1 and UTC timescales at the moment in time represented by the SkyFrame\texttt{'} s Epoch attribute. The value to use is unpredictable and depends on changes in the earth\texttt{'} s rotation speed. Values for UT1-UTC can be obtained from the International Earth Rotation and Reference Systems Service (IERS) at http://www.iers.org/. Currently, the correction is always less than 1 second. This is ensured by the occasional introduction of leap seconds into the UTC timescale. Therefore no great error will usually result if no value is assigned to this attribute (in which case a default value of zero is used). However, it is possible that a decision may be taken at some time in the future to abandon the introduction of leap seconds, in which case the DUT correction could grow to significant sizes. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ All Frames have this attribute. } } } \sstroutine{ Edge(axis) }{ Which edges to label in a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining which edges of a \htmlref{Plot}{Plot} are used for displaying numerical and descriptive axis labels. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} Edge(2)=left\texttt{"} specifies which edge to use to display labels for the second axis. The values \texttt{"} left\texttt{"} , \texttt{"} top\texttt{"} , \texttt{"} right\texttt{"} and \texttt{"} bottom\texttt{"} (or any abbreviation) can be supplied for this attribute. The default is usually \texttt{"} bottom\texttt{"} for the first axis and \texttt{"} left\texttt{"} for the second axis. However, if exterior labelling was requested (see the \htmlref{Labelling}{Labelling} attribute) but cannot be produced using these default Edge values, then the default values will be swapped if this enables exterior labelling to be produced. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes. Instead it uses its own \htmlref{RootCorner}{RootCorner} attribute to determine which edges of the 3D plot to label. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels will be drawn along internal grid lines instead of at the edges of the plotting area (see the Labelling attribute). In this case, the Edge attribute only affects the placement of the descriptive labels (these are drawn at the edges of the plotting area, rather than along the axis lines). } } } \sstroutine{ Encoding }{ System for encoding Objects as FITS headers }{ \sstdescription{ This attribute specifies the encoding system to use when AST Objects are stored as FITS header cards in a \htmlref{FitsChan}{FitsChan}. It affects the behaviour of the \htmlref{AST\_WRITE}{AST\_WRITE} and \htmlref{AST\_READ}{AST\_READ} routines when they are used to transfer any AST \htmlref{Object}{Object} to or from an external representation consisting of FITS header cards (i.e. whenever a write or read operation is performed using a FitsChan as the I/O \htmlref{Channel}{Channel}). There are several ways (conventions) by which coordinate system information may be represented in the form of FITS headers and the Encoding attribute is used to specify which of these should be used. The encoding options available are outlined in the \texttt{"} Encodings Available\texttt{"} section below, and in more detail in the sections which follow. Encoding systems differ in the range of possible Objects (e.g. classes) they can represent, in the restrictions they place on these Objects (e.g. compatibility with some externally-defined coordinate system model) and in the number of Objects that can be stored together in any particular set of FITS header cards (e.g. multiple Objects, or only a single Object). The choice of encoding also affects the range of external applications which can potentially read and interpret the FITS header cards produced. The encoding options available are not necessarily mutually exclusive, and it may sometimes be possible to store multiple Objects (or the same Object several times) using different encodings within the same set of FITS header cards. This possibility increases the likelihood of other applications being able to read and interpret the information. By default, a FitsChan will attempt to determine which encoding system is already in use, and will set the default Encoding value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical FITS keywords which only occur in particular encodings. For details of how this works, see the \texttt{"} Choice of Default Encoding\texttt{"} section below. If you wish to ensure that a particular encoding system is used, independently of any FITS cards already present, you should set an explicit Encoding value yourself. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } \sstdiytopic{ Encodings Available }{ The Encoding attribute can take any of the following (case insensitive) string values to select the corresponding encoding system: \sstitemlist{ \sstitem \texttt{"} DSS\texttt{"} : Encodes coordinate system information in FITS header cards using the convention developed at the Space Telescope Science Institute (STScI) for the Digitised Sky Survey (DSS) astrometric plate calibrations. The main advantages of this encoding are that FITS images which use it are widely available and it is understood by a number of important and well-established astronomy applications. For further details, see the section \texttt{"} The DSS Encoding\texttt{"} below. \sstitem \texttt{"} FITS-WCS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in the FITS world coordinate system (FITS-WCS) papers by E.W. Greisen, M. Calabretta, et al. The main advantages of this encoding are that it should be understood by any FITS-WCS compliant application and is likely to be adopted widely for FITS data in future. For further details, see the section \texttt{"} The FITS-WCS Encoding\texttt{"} below. \sstitem \texttt{"} FITS-PC\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in an earlier draft of the FITS world coordinate system papers by E.W. Greisen and M. Calabretta. This encoding uses a combination of CDELTi and PCiiijjj keywords to describe the scale and rotation of the pixel axes. This encoding is included to support existing data and software which uses these now superceded conventions. In general, the \texttt{"} FITS-WCS\texttt{"} encoding (which uses CDi\_j or PCi\_j keywords to describe the scale and rotation) should be used in preference to \texttt{"} FITS-PC\texttt{"} . \sstitem \texttt{"} FITS-IRAF\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in the document \texttt{"} World Coordinate Systems Representations Within the FITS Format\texttt{"} by R.J. Hanisch and D.G. Wells, 1988. This encoding is currently employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. Its main advantages are that it is a stable convention which approximates to a subset of the propsed FITS-WCS encoding (above). This makes it suitable as an interim method for storing coordinate system information in FITS headers until the FITS-WCS encoding becomes stable. Since many datasets currently use the FITS-IRAF encoding, conversion of data from FITS-IRAF to the final form of FITS-WCS is likely to be well supported. \sstitem \texttt{"} FITS-AIPS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions originally introduced by the AIPS data analysis facility. This is base on the use of CDELTi and CROTAi keuwords to desribe the scale and rotation of each axis. These conventions have been superceded but are still widely used. \sstitem \texttt{"} FITS-AIPS$+$$+$\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions used by the AIPS$+$$+$ project. This is an extension of FITS-AIPS which includes some of the features of FITS-IRAF and FITS-PC. \sstitem \texttt{"} FITS-CLASS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions used by the CLASS project. CLASS is a software package for reducing single-dish radio and sub-mm spectroscopic data. See the section \texttt{"} CLASS FITS format\texttt{"} at http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/. \sstitem \texttt{"} NATIVE\texttt{"} : Encodes AST Objects in FITS header cards using a convention which is private to the AST library (but adheres to the general FITS standard) and which uses FITS keywords that will not clash with other encoding systems. The main advantages of this are that any class of AST Object may be encoded, and any (reasonable) number of Objects may be stored sequentially in the same FITS header. This makes FITS headers an almost loss-less communication path for passing AST Objects between applications (although all such applications must, of course, make use of the AST library to interpret the information). For further details, see the section \texttt{"} The NATIVE Encoding\texttt{"} below. } } \sstdiytopic{ Choice of Default Encoding }{ If the Encoding attribute of a FitsChan is not set, the default value it takes is determined by the presence of certain critical FITS keywords within the FitsChan. The sequence of decisions used to arrive at the default value is as follows: \sstitemlist{ \sstitem If the FitsChan contains any keywords beginning with the string \texttt{"} BEGAST\texttt{"} , then NATIVE encoding is used, \sstitem Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV keyword and a keyword of the form VELO-xxx, where xxx indicates one of the rest frames used by class (e.g. \texttt{"} VELO-LSR\texttt{"} ), or \texttt{"} VLSR\texttt{"} . \sstitem Otherwise, if the FitsChan contains a CTYPE keyword which represents a spectral axis using the conventions of the AIPS and AIPS$+$$+$ projects (e.g. \texttt{"} FELO-LSR\texttt{"} , etc), then one of FITS-AIPS or FITS-AIPS$+$$+$ encoding is used. FITS-AIPS$+$$+$ is used if any of the keywords CDi\_j, PROJP, LONPOLE or LATPOLE are found in the FitsChan. Otherwise FITS-AIPS is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} PCiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-PC encoding is used, \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} CDiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-IRAF encoding is used, \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} CDi\_j\texttt{"} , and at least one of RADECSYS, PROJPi, or CjVALi where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-IRAF encoding is used. \sstitem Otherwise, if the FitsChan contains any keywords of the form PROJPi, CjVALi or RADECSYS, where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-PC encoding is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form CROTAi, where \texttt{"} i\texttt{"} is a single digit, then FITS-AIPS encoding is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form CRVALi, where \texttt{"} i\texttt{"} is a single digit, then FITS-WCS encoding is used. \sstitem Otherwise, if the FitsChan contains the \texttt{"} PLTRAH\texttt{"} keyword, then DSS encoding is used, \sstitem Otherwise, if none of these conditions is met (as would be the case when using an empty FitsChan), then NATIVE encoding is used. } Except for the NATIVE and DSS encodings, all the above checks also require that the header contains at least one CTYPE, CRPIX and CRVAL keyword (otherwise the checking process continues to the next case). Setting an explicit value for the Encoding attribute always over-rides this default behaviour. Note that when writing information to a FitsChan, the choice of encoding will depend greatly on the type of application you expect to be reading the information in future. If you do not know this, there may sometimes be an advantage in writing the information several times, using a different encoding on each occasion. } \sstdiytopic{ The DSS Encoding }{ The DSS encoding uses FITS header cards to store a multi-term polynomial which relates pixel positions on a digitised photographic plate to celestial coordinates (right ascension and declination). This encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a \htmlref{FrameSet}{FrameSet} which conforms to the STScI/DSS coordinate system model (this means the \htmlref{Mapping}{Mapping} which relates its base and current Frames must include either a \htmlref{DssMap}{DssMap} or a \htmlref{WcsMap}{WcsMap} with type AST\_\_TAN or AST\_\_TPN). When reading a DSS encoded Object (using AST\_READ), the FitsChan concerned must initially be positioned at the first card (its \htmlref{Card}{Card} attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base \htmlref{Frame}{Frame} of this FrameSet represents DSS pixel coordinates, and the current Frame represents DSS celestial coordinates. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound. When AST\_WRITE is used to store a FrameSet using DSS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the DSS model. Specifically, the current Frame must be a FK5 \htmlref{SkyFrame}{SkyFrame}; the projection must be a tangent plane (gnomonic) projection with polynomial corrections conforming to DSS requirements, and north must be parallel to the second base Frame axis. If the simplification process succeeds, a description of the FrameSet is written to the FitsChan using appropriate DSS FITS header cards. The base Frame of the FrameSet is used to form the DSS pixel coordinate system and the current Frame gives the DSS celestial coordinate system. A successful write operation will over-write any existing DSS encoded data in the FitsChan, but will not affect other (non-DSS) header cards. If a destructive read of a DSS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. If an attempt to simplify a FrameSet to conform to the DSS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and AST\_WRITE will return zero. No error will result. } \sstdiytopic{ The FITS-WCS Encoding }{ The FITS-WCS convention uses FITS header cards to describe the relationship between pixels in an image (not necessarily 2-dimensional) and one or more related \texttt{"} world coordinate systems\texttt{"} . The FITS-WCS encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSet which conforms to the FITS-WCS model (the FrameSet may, however, contain multiple Frames which will be result in multiple FITS \texttt{"} alternate axis descriptions\texttt{"} ). Details of the use made by this Encoding of the conventions described in the FITS-WCS papers are given in the appendix \texttt{"} FITS-WCS Coverage\texttt{"} of this document. A few main points are described below. The rotation and scaling of the intermediate world coordinate system can be specified using either \texttt{"} CDi\_j\texttt{"} keywords, or \texttt{"} PCi\_j\texttt{"} together with \texttt{"} CDELTi\texttt{"} keywords. When writing a FrameSet to a FitsChan, the the value of the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan determines which system is used. In addition, this encoding supports the \texttt{"} TAN with polynomial correction terms\texttt{"} projection which was included in a draft of the FITS-WCS paper, but was not present in the final version. A \texttt{"} TAN with polynomial correction terms\texttt{"} projection is represented using a WcsMap with type AST\_\_TPN (rather than AST\_\_TAN which is used to represent simple TAN projections). When reading a FITS header, a CTYPE keyword value including a \texttt{"} -TAN\texttt{"} code results in an AST\_\_TPN projection if there are any projection parameters (given by the \htmlref{PVi\_m}{PVi\_m} keywords) associated with the latitude axis, or if there are projection parameters associated with the longitude axis for m greater than 4. When writing a FrameSet to a FITS header, an AST\_\_TPN projection gives rise to a CTYPE value including the normal \texttt{"} -TAN\texttt{"} code, but the projection parameters are stored in keywords with names \texttt{"} QVi\_m\texttt{"} , instead of the usual \texttt{"} PVi\_m\texttt{"} . Since these QV parameters are not part of the FITS-WCS standard they will be ignored by other non-AST software, resulting in the WCS being interpreted as a simple TAN projection without any corrections. This should be seen as an interim solution until such time as an agreed method for describing projection distortions within FITS-WCS has been published. AST extends the range of celestial coordinate systems which may be described using this encoding by allowing the inclusion of \texttt{"} AZ--\texttt{"} and \texttt{"} EL--\texttt{"} as the coordinate specification within CTYPE values. These form a longitude/latitude pair of axes which describe azimuth and elevation. The geographic position of the observer should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS paper III. Currently, a simple model is used which includes diurnal aberration, but ignores atmospheric refraction, polar motion, etc. These may be added in a later release. If an AST SkyFrame that represents offset rather than absolute coordinates (see attribute \htmlref{SkyRefIs}{SkyRefIs}) is written to a FitsChan using FITS-WCS encoding, two alternate axis descriptions will be created. One will describe the offset coordinates, and will use \texttt{"} OFLN\texttt{"} and \texttt{"} OFLT\texttt{"} as the axis codes in the CTYPE keywords. The other will describe absolute coordinates as specified by the \htmlref{System}{System} attribute of the SkyFrame, using the usual CTYPE codes (\texttt{"} RA--\texttt{"} /\texttt{"} DEC-\texttt{"} , etc). In addition, the absolute coordinates description will contain AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the header to be read back into AST in order to reconstruct the original SkyFrame. When reading a FITS-WCS encoded Object (using AST\_READ), the FitsChan concerned must initially be positioned at the first card (its Card attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base Frame of this FrameSet represents FITS-WCS pixel coordinates, and the current Frame represents the physical coordinate system described by the FITS-WCS primary axis descriptions. If secondary axis descriptions are also present, then the FrameSet may contain additional (non-current) Frames which represent these. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound. When AST\_WRITE is used to store a FrameSet using FITS-WCS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the FITS-WCS model. If this simplification process succeeds (as it often should, as the model is reasonably flexible), a description of the FrameSet is written to the FitsChan using appropriate FITS header cards. The base Frame of the FrameSet is used to form the FITS-WCS pixel coordinate system and the current Frame gives the physical coordinate system to be described by the FITS-WCS primary axis descriptions. Any additional Frames in the FrameSet may be used to construct secondary axis descriptions, where appropriate. A successful write operation will over-write any existing FITS-WCS encoded data in the FitsChan, but will not affect other (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. Otherwise, the new cards will be inserted following any other FITS-WCS related header cards present or, failing that, in front of the current card (as given by the Card attribute). If an attempt to simplify a FrameSet to conform to the FITS-WCS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and AST\_WRITE will return zero. No error will result. } \sstdiytopic{ The FITS-IRAF Encoding }{ The FITS-IRAF encoding can, for most purposes, be considered as a subset of the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following: \sstitemlist{ \sstitem The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic, \sstitem Sky projections can be represented only if any associated projection parameters are set to their default values. \sstitem Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored. } Note that this encoding is provided mainly as an interim measure to provide a more stable alternative to the FITS-WCS encoding until the FITS standard for encoding WCS information is finalised. The name \texttt{"} FITS-IRAF\texttt{"} indicates the general keyword conventions used and does not imply that this encoding will necessarily support all features of the WCS scheme used by IRAF software. Nevertheless, an attempt has been made to support a few such features where they are known to be used by important sources of data. When writing a FrameSet using the FITS-IRAF encoding, axis rotations are specified by a matrix of FITS keywords of the form \texttt{"} CDi\_j\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits. The alternative form \texttt{"} CDiiijjj\texttt{"} , which is also in use, is recognised when reading an Object, but is never written. In addition, the experimental IRAF \texttt{"} ZPX\texttt{"} and \texttt{"} TNX\texttt{"} sky projections will be accepted when reading, but will never be written (the corresponding FITS \texttt{"} ZPN\texttt{"} or \texttt{"} distorted TAN\texttt{"} projection being used instead). However, there are restrictions on the use of these experimental projections. For \texttt{"} ZPX\texttt{"} , longitude and latitude correction surfaces (appearing as \texttt{"} lngcor\texttt{"} or \texttt{"} latcor\texttt{"} terms in the IRAF-specific \texttt{"} WAT\texttt{"} keywords) are not supported. For \texttt{"} TNX\texttt{"} projections, only cubic surfaces encoded as simple polynomials with \texttt{"} half cross-terms\texttt{"} are supported. If an un-usable \texttt{"} TNX\texttt{"} or \texttt{"} ZPX\texttt{"} projection is encountered while reading from a FitsChan, a simpler form of TAN or ZPN projection is used which ignores the unsupported features and may therefore be inaccurate. If this happens, a warning message is added to the contents of the FitsChan as a set of cards using the keyword \texttt{"} ASTWARN\texttt{"} . You should not normally attempt to mix the foreign FITS encodings within the same FitsChan, since there is a risk that keyword clashes may occur. } \sstdiytopic{ The FITS-PC Encoding }{ The FITS-PC encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions. } \sstdiytopic{ The FITS-AIPS Encoding }{ The FITS-AIPS encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following: \sstitemlist{ \sstitem The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic, \sstitem Spectral axes can only be represented if they represent frequency, radio velocity or optical velocity, and are linearly sampled in frequency. In addition, the standard of rest must be LSRK, LSRD, barycentric or geocentric. \sstitem Sky projections can be represented only if any associated projection parameters are set to their default values. \sstitem The AIT, SFL and MER projections can only be written if the CRVAL keywords are zero for both longitude and latitude axes. \sstitem Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored. \sstitem If there are more than 2 axes in the base and current Frames, any rotation must be restricted to the celestial plane, and must involve no shear. } } \sstdiytopic{ The FITS-AIPS$+$$+$ Encoding }{ The FITS-AIPS$+$$+$ encoding is based on the FITS-AIPS encoding, but includes some features of the FITS-IRAF and FITS-PC encodings. Specifically, any celestial projections supported by FITS-PC may be used, including those which require parameterisation, and the axis rotation and scaling may be specified using CDi\_j keywords. When writing a FITS header, rotation will be specified using CROTA/CDELT keywords if possible, otherwise CDi\_j keywords will be used instead. } \sstdiytopic{ The FITS-CLASS Encoding }{ The FITS-CLASS encoding uses the conventions of the CLASS project. These are described in the section \texttt{"} Developer Manual\texttt{"} /\texttt{"} CLASS FITS Format\texttt{"} contained in the CLASS documentation at: http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html. This encoding is similar to FITS-AIPS with the following restrictions: \sstitemlist{ \sstitem When a \htmlref{SpecFrame}{SpecFrame} is created by reading a FITS-CLASS header, the attributes describing the observer\texttt{'} s position (\htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon} and \htmlref{ObsAlt}{ObsAlt}) are left unset because the CLASS encoding does not specify these values. Conversions to or from the topocentric standard of rest will therefore be inaccurate (typically by up to about 0.5 km/s) unless suitable values are assigned to these attributes after the FrameSet has been created. \sstitem When writing a FrameSet to a FITS-CLASS header, the current Frame in the FrameSet must have at least 3 WCS axes, of which one must be a linear spectral axis. The spectral axis in the created header will always describe frequency. If the spectral axis in the supplied FrameSet refers to some other system (e.g. radio velocity, etc), then it will be converted to frequency. \sstitem There must be a pair of celestial axes - either (RA,Dec) or (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000. \sstitem A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) can be used. For AIT and SFL, the reference point must be at the origin of longitude and latitude. For SIN, the associated projection parameters must both be zero. \sstitem No rotation of the celestial axes is allowed, unless the spatial axes are degenerate (i.e. cover only a single pixel). \sstitem The frequency axis in the created header will always describe frequency in the source rest frame. If the supplied FrameSet uses some other standard of rest then suitable conversion will be applied. \sstitem The source velocity must be defined. In other words, the SpecFrame attributes \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} must have been assigned values. \sstitem The frequency axis in a FITS-CLASS header does not represent absolute frequency, but instead represents offsets from the rest frequency in the standard of rest of the source. } When writing a FrameSet out using FITS-CLASS encoding, the current Frame may be temporarily modified if this will allow the header to be produced. If this is done, the associated pixel-$>$WCS Mapping will also be modified to take account of the changes to the Frame. The modifications performed include re-ordering axes (WCS axes, not pixel axes), changing spectral coordinate system and standard of rest, changing the celestial coordinate system and reference equinox, and changing axis units. } \sstdiytopic{ The NATIVE Encoding }{ The NATIVE encoding may be used to store a description of any class of AST Object in the form of FITS header cards, and (for most practical purposes) any number of these Object descriptions may be stored within a single set of FITS cards. If multiple Object descriptions are stored, they are written and read sequentially. The NATIVE encoding makes use of unique FITS keywords which are designed not to clash with keywords that have already been used for other purposes (if a potential clash is detected, an alternative keyword is constructed to avoid the clash). When reading a NATIVE encoded object from a FitsChan (using AST\_READ), FITS header cards are read, starting at the current card (as determined by the Card attribute), until the start of the next Object description is found. This description is then read and converted into an AST Object, for which a pointer is returned. Such a read is always destructive and causes all the FITS header cards involved in the Object description to be removed from the FitsChan, which is left positioned at the following card. The Object returned may be of any class, depending on the description that was read, and other AST routines may be used to validate it (for example, by examining its \htmlref{Class}{Class} or \htmlref{ID}{ID} attribute using AST\_GETC). If further NATIVE encoded Object descriptions exist in the FitsChan, subsequent calls to AST\_READ will return the Objects they describe in sequence (and destroy their descriptions) until no more remain between the current card and the \texttt{"} end-of-file\texttt{"} . When AST\_WRITE is used to write an Object using NATIVE encoding, a description of the Object is inserted immediately before the current card (as determined by the Card attribute). Multiple Object descriptions may be written in this way and are stored separately (and sequentially if the Card attribute is not modified between the writes). A write operation using the NATIVE encoding does not over-write previously written Object descriptions. Note, however, that subsequent behaviour is undefined if an Object description is written inside a previously-written description, so this should be avoided. When an Object is written to a FitsChan using NATIVE encoding, AST\_WRITE should (barring errors) always transfer data and return a value of 1. } } \sstroutine{ Epoch }{ Epoch of observation }{ \sstdescription{ This attribute is used to qualify the coordinate systems described by a \htmlref{Frame}{Frame}, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time. The Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the \texttt{"} Input Formats\texttt{"} section (below) for details. Strictly, the Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the \htmlref{System}{System} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer\texttt{'} s position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole). The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others. Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator). See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the Epoch attribute. However, user code can still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"} time spanned by the TimeFrame. The default Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0. } } \sstdiytopic{ Input Formats }{ The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters: \sstitemlist{ \sstitem Besselian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). \sstitem Julian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). \sstitem Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"} for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise. \sstitem Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for example). \sstitem Modified Julian Date: With or without decimal places (\texttt{"} MJD 54321.4\texttt{"} for example). \sstitem Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours). \sstitem Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). } } \sstdiytopic{ Output Format }{ When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"} format described under \texttt{"} Input Formats\texttt{"} . This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch value to be obtained as either a character string or a floating point value. } } \sstroutine{ Equinox }{ Epoch of the mean equinox }{ \sstdescription{ This attribute is used to qualify those celestial coordinate systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun) and/or the Earth\texttt{'} s equator. Both of these planes are in motion and their positions are difficult to specify precisely. In practice, therefore, a model ecliptic and/or equator are used instead. These, together with the point on the sky that defines the coordinate origin (the intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move with time according to some model which removes the more rapid fluctuations. The SkyFrame class supports both the FK4 and FK5 models. The position of a fixed source expressed in any of these coordinate systems will appear to change with time due to movement of the coordinate system itself (rather than motion of the source). Such coordinate systems must therefore be qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"} or \texttt{"} equinox\texttt{"} for short) which allows the position of the model coordinate system on the sky to be determined. This is the role of the Equinox attribute. The Equinox attribute is stored as a Modified Julian Date, but when setting or getting its value you may use the same formats as for the \htmlref{Epoch}{Epoch} attribute (q.v.). The default Equinox value is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and J2000.0 (Julian) for all others. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent coordinate system (based on solar system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify coordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer\texttt{'} s motion, etc. \sstitem See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system. } } } \sstroutine{ Escape }{ Allow changes of character attributes within strings? }{ \sstdescription{ This attribute controls the appearance of text strings and numerical labels drawn by the \htmlref{AST\_GRID}{AST\_GRID} and (for the \htmlref{Plot}{Plot} class) \htmlref{AST\_TEXT}{AST\_TEXT} routines, by determining if any escape sequences contained within the strings should be used to control the appearance of the text, or should be printed literally. Note, the \htmlref{Plot3D}{Plot3D} class only interprets escape sequences within the AST\_GRID routine. If the Escape value of a Plot is one (the default), then any escape sequences in text strings produce the effects described below when printed. Otherwise, they are printed literally. See also the \htmlref{AST\_ESCAPES}{AST\_ESCAPES} function. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstdiytopic{ Escape Sequences }{ Escape sequences are introduced into the text string by a percent \texttt{"} \%\texttt{"} character. Any unrecognised, illegal or incomplete escape sequences are printed literally. The following escape sequences are currently recognised (\texttt{"} ...\texttt{"} represents a string of one or more decimal digits): \%\% - Print a literal \texttt{"} \%\texttt{"} character. \%$\wedge$...$+$ - Draw subsequent characters as super-scripts. The digits \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} text to the base-line of the super-script text, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%$\wedge$$+$ - Draw subsequent characters with the normal base-line. \%v...$+$ - Draw subsequent characters as sub-scripts. The digits \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} text to the base-line of the sub-script text, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%v$+$ - Draw subsequent characters with the normal base-line (equivalent to \%$\wedge$$+$). \%$>$...$+$ - Leave a gap before drawing subsequent characters. The digits \texttt{"} ...\texttt{"} give the size of the gap, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%$<$...$+$ - Move backwards before drawing subsequent characters. The digits \texttt{"} ...\texttt{"} give the size of the movement, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%s...$+$ - Change the Size attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Size as a fraction of the \texttt{"} normal\texttt{"} Size, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to 1.0; \%s$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. \%w...$+$ - Change the Width attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new width as a fraction of the \texttt{"} normal\texttt{"} Width, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to 1.0; \%w$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. \%f...$+$ - Change the Font attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Font value. \%f$+$ - Reset the Font attribute to its \texttt{"} normal\texttt{"} value. \%c...$+$ - Change the Colour attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Colour value. \%c$+$ - Reset the Colour attribute to its \texttt{"} normal\texttt{"} value. \%t...$+$ - Change the Style attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Style value. \%t$+$ - Reset the Style attribute to its \texttt{"} normal\texttt{"} value. \%h$+$ - Remember the current horizontal position (see \texttt{"} \%g$+$\texttt{"} ) \%g$+$ - Go to the horizontal position of the previous \texttt{"} \%h$+$\texttt{"} (if any). \%- - Push the current graphics attribute values onto the top of the stack (see \texttt{"} \%$+$\texttt{"} ). \%$+$ - Pop attributes values of the top the stack (see \texttt{"} \%-\texttt{"} ). If the stack is empty, \texttt{"} normal\texttt{"} attribute values are restored. } } \sstroutine{ FillFactor }{ Fraction of the Region which is of interest }{ \sstdescription{ This attribute indicates the fraction of the \htmlref{Region}{Region} which is of interest. AST does not use this attribute internally for any purpose. Typically, it could be used to indicate the fraction of the Region for which data is available. The supplied value must be in the range 0.0 to 1.0, and the default value is 1.0 (except as noted below). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default FillFactor for a CmpRegion is the FillFactor of its first component Region. } \sstsubsection{ \htmlref{Prism}{Prism} }{ The default FillFactor for a Prism is the product of the FillFactors of its two component Regions. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default FillFactor for an Stc is the FillFactor of its encapsulated Region. } } } \sstroutine{ FitsAxisOrder }{ Frame title }{ \sstdescription{ This attribute specifies the order for the WCS axes in any new FITS-WCS headers created using the \htmlref{AST\_WRITE}{AST\_WRITE} method. The value of the FitsAxisOrder attribute can be either \texttt{"} $<$auto$>$\texttt{"} (the default value), \texttt{"} $<$copy$>$\texttt{"} or a space-separated list of axis symbols: \texttt{"} $<$auto$>$\texttt{"} : causes the WCS axis order to be chosen automatically so that the i\texttt{'} th WCS axis in the new FITS header is the WCS axis which is more nearly parallel to the i\texttt{'} th pixel axis. \texttt{"} $<$copy$>$\texttt{"} : causes the WCS axis order to be set so that the i\texttt{'} th WCS axis in the new FITS header is the i\texttt{'} th WCS axis in the current \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} being written out to the header. \texttt{"} Sym1 Sym2...\texttt{"} : the space-separated list is seached in turn for the Symbol attribute of each axis in the current Frame of the FrameSet. The order in which these Symbols occur within the space-separated list defines the order of the WCS axes in the new FITS header. An error is reported if Symbol for a current Frame axis is not present in the supplied list. However, no error is reported if the list contains extra words that do not correspond to the Symbol of any current Frame axis. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } } \sstroutine{ FitsDigits }{ Digits of precision for floating point FITS values }{ \sstdescription{ This attribute gives the number of significant decimal digits to use when formatting floating point values for inclusion in the FITS header cards within a \htmlref{FitsChan}{FitsChan}. By default, a positive value is used which results in no loss of information, assuming that the value is double precision. Usually, this causes no problems. However, to adhere strictly to the recommendations of the FITS standard, the width of the formatted value (including sign, decimal point and exponent) ought not to be more than 20 characters. If you are concerned about this, you should set FitsDigits to a negative value, such as -15. In this case, the absolute value ($+$15) indicates the maximum number of significant digits to use, but the actual number used may be fewer than this to ensure that the FITS recommendations are satisfied. When using this approach, the resulting number of significant digits may depend on the value being formatted and on the presence of any sign, decimal point or exponent. The value of this attribute is effective when FITS header cards are output, either using \htmlref{AST\_FINDFITS}{AST\_FINDFITS} or by the action of the FitsChan\texttt{'} s sink routine when it is finally deleted. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Font(element) }{ Character font for a Plot element }{ \sstdescription{ This attribute determines the character font index used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Font(title)=2\texttt{"} causes the Plot title to be drawn using font number 2. The range of integer font indices available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default font supplied by this graphics system. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Font\texttt{"} instead of \texttt{"} Font(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Font(TextLab) value. } } } \sstroutine{ Format(axis) }{ Format specification for axis values }{ \sstdescription{ This attribute specifies the format to be used when displaying coordinate values associated with a particular \htmlref{Frame}{Frame} axis (i.e. to convert values from binary to character form). It is interpreted by the \htmlref{AST\_FORMAT}{AST\_FORMAT} function and determines the formatting which it applies. If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The Frame class interprets this attribute as a format specification string to be passed to the C \texttt{"} printf\texttt{"} function (e.g. \texttt{"} \%1.7G\texttt{"} ) in order to format a single coordinate value (supplied as a double precision number). } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the \texttt{"} SkyFrame Formats\texttt{"} section. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). Note that the syntax of the Format string is also determined by the current Frame. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the \texttt{"} TimeFrame Formats\texttt{"} section. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } \sstdiytopic{ SkyFrame Formats }{ The Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity: \sstitemlist{ \sstitem \texttt{"} $+$\texttt{"} : Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used. \sstitem \texttt{"} z\texttt{"} : Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added. \sstitem \texttt{"} i\texttt{"} : Use the standard ISO field separator (a colon) between fields. This is the default behaviour. \sstitem \texttt{"} b\texttt{"} : Use a blank to separate fields. \sstitem \texttt{"} l\texttt{"} : Use a letter (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} as appropriate) to separate fields. \sstitem \texttt{"} g\texttt{"} : Use a letter and symbols to separate fields (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} , etc, as appropriate), but include escape sequences in the formatted value so that the \htmlref{Plot}{Plot} class will draw the separators as small super-scripts. \sstitem \texttt{"} d\texttt{"} : Include a degrees field. Expressing the angle purely in degrees is also the default if none of \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} , \texttt{"} s\texttt{"} or \texttt{"} t\texttt{"} are given. \sstitem \texttt{"} h\texttt{"} : Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if \texttt{"} t\texttt{"} is given without either \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} . \sstitem \texttt{"} m\texttt{"} : Include a minutes field. By default this is not included. \sstitem \texttt{"} s\texttt{"} : Include a seconds field. By default this is not included. This request is ignored if \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is given, unless a minutes field is also included. \sstitem \texttt{"} t\texttt{"} : Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If \texttt{"} t\texttt{"} is given without \texttt{"} d\texttt{"} , \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} being present, then it is equivalent to \texttt{"} h\texttt{"} . \sstitem \texttt{"} .\texttt{"} : Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The \texttt{"} .\texttt{"} should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits attribute. } All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both \texttt{"} i\texttt{"} and \texttt{"} b\texttt{"} appear), then the character occurring last takes precedence, except that \texttt{"} d\texttt{"} and \texttt{"} h\texttt{"} always override \texttt{"} t\texttt{"} . If the format string starts with a percentage sign (\%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value. } \sstdiytopic{ TimeFrame Formats }{ The Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C \texttt{"} printf\texttt{"} format string), or the extended \texttt{"} iso\texttt{"} syntax described below (the default value is inherited from the Frame class): \sstitemlist{ \sstitem C \texttt{"} printf\texttt{"} syntax: If the Format string is a C \texttt{"} printf\texttt{"} format description such as \texttt{"} \%1.7G\texttt{"} , the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute, measured in units given by the TimeFrame\texttt{'} s Unit attribute. \sstitem \texttt{"} iso\texttt{"} syntax: This is used to format a TimeFrame axis value as a Gregorian date followed by an optional time of day. If the Format value commences with the string \texttt{"} iso\texttt{"} then the TimeFrame axis value will be converted to an absolute MJD, including the addition of the current TimeOrigin value, and then formatted as a Gregorian date using the format \texttt{"} yyyy-mm-dd\texttt{"} . Optionally, the Format value may include an integer precision following the \texttt{"} iso\texttt{"} specification (e.g. \texttt{"} iso.2\texttt{"} ), in which case the time of day will be appended to the formatted date (if no time of day is included, the date field is rounded to the nearest day). The integer value in the Format string indicates the number of decimal places to use in the seconds field. For instance, a Format value of \texttt{"} iso.0\texttt{"} produces a time of day of the form \texttt{"} hh:mm:ss\texttt{"} , and a Format value of \texttt{"} iso.2\texttt{"} produces a time of day of the form \texttt{"} hh:mm:ss.ss\texttt{"} . The date and time fields will be separated by a space unless \texttt{'} T\texttt{'} is appended to the end of string, in which case the letter T (upper case) will be used as the separator. The value of the Digits attribute is ignored when using this \texttt{"} iso\texttt{"} format. } } } \sstroutine{ Full }{ Set level of output detail }{ \sstdescription{ This attribute is a three-state flag and takes values of -1, 0 or $+$1. It controls the amount of information included in the output generated by a \htmlref{Channel}{Channel}. If Full is zero, then a modest amount of non-essential but useful information will be included in the output. If Full is negative, all non-essential information will be suppressed to minimise the amount of output, while if it is positive, the output will include the maximum amount of detailed information about the \htmlref{Object}{Object} being written. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Channel }{ The default value is zero for a normal Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The default value is zero for a FitsChan. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value is -1 for an XmlChan. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The default value is zero for an StcsChan. Set a positive value to cause default values to be included in STC-S descriptions. } } \sstnotes{ \sstitemlist{ \sstitem All positive values supplied for this attribute are converted to $+$1 and all negative values are converted to -1. } } } \sstroutine{ Gap(axis) }{ Interval between linearly spaced major axis values of a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the linear interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} Gap(2)=3.0\texttt{"} specifies the difference between adjacent major values along the second axis. The Gap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be linear. If major axis values are logarithmically spaced then the gap is specified using attribute LogGap. The Gap value supplied will usually be rounded to the nearest \texttt{"} nice\texttt{"} value, suitable (e.g.) for generating axis labels, before use. To avoid this \texttt{"} nicing\texttt{"} you should set an explicit format for the axis using the \htmlref{Format(axis)}{Format(axis)} or \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} attribute. The default behaviour is for the Plot to generate its own Gap value when required, based on the range of axis values to be represented. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The Gap value should use the same units as are used internally for storing coordinate values on the corresponding axis. For example, with a celestial coordinate system, the Gap value should be in radians, not hours or degrees. \sstitem If no axis is specified, (e.g. \texttt{"} Gap\texttt{"} instead of \texttt{"} Gap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Gap(1) value. } } } \sstroutine{ Grf }{ Use Grf routines registered through AST\_GRFSET? }{ \sstdescription{ This attribute selects the routines which are used to draw graphics by the \htmlref{Plot}{Plot} class. If it is zero, then the routines in the graphics interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script). Otherwise, routines registered using \htmlref{AST\_GRFSET}{AST\_GRFSET} are used. In this case, if a routine is needed which has not been registered, then the routine in the graphics interface selected at link-time is used. The default is to use the graphics interface } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes, assuming a value of zero. } } \sstnotes{ \sstitemlist{ \sstitem The value of this attribute is not saved when the Plot is written out through a \htmlref{Channel}{Channel} to an external data store. On re-loading such a Plot using \htmlref{AST\_READ}{AST\_READ}, the attribute will be cleared, resulting in the graphics interface selected at link-time being used. } } } \sstroutine{ Grid }{ Draw grid lines for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether grid lines (a grid of curves marking the \texttt{"} major\texttt{"} values on each axis) are drawn across the plotting area. If the Grid value of a \htmlref{Plot}{Plot} is non-zero, then grid lines will be drawn. Otherwise, short tick marks on the axes are used to mark the major axis values. The default behaviour is to use tick marks if the entire plotting area is filled by valid physical coordinates, but to draw grid lines otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The spacing between major axis values, which determines the spacing of grid lines, may be set using the \htmlref{Gap(axis)}{Gap(axis)} attribute. } } } \sstroutine{ GrismAlpha }{ The angle of incidence of the incoming light on the grating surface }{ \sstdescription{ This attribute holds the angle between the incoming light and the normal to the grating surface, in radians. The default value is 0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismEps }{ The angle between the normal and the dispersion plane }{ \sstdescription{ This attribute holds the angle (in radians) between the normal to the grating or exit prism face, and the dispersion plane. The dispersion plane is the plane spanned by the incoming and outgoing ray. The default value is 0.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismG }{ The grating ruling density }{ \sstdescription{ This attribute holds the number of grating rulings per unit length. The unit of length used should be consistent with the units used for attributes \htmlref{GrismWaveR}{GrismWaveR} and \htmlref{GrismNRP}{GrismNRP}. The default value is 0.0. (the appropriate value for a pure prism disperser with no grating). Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismM }{ The interference order }{ \sstdescription{ This attribute holds the interference order being considered. The default value is 0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismNR }{ The refractive index at the reference wavelength }{ \sstdescription{ This attribute holds refractive index of the grism material at the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 1.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismNRP }{ The rate of change of refractive index with wavelength }{ \sstdescription{ This attribute holds the rate of change of the refractive index of the grism material with respect to wavelength at the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 0.0 (the appropriate value for a pure grating disperser with no prism). The units of this attribute should be consistent with those of attributes GrismWaveR and \htmlref{GrismG}{GrismG}. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismTheta }{ Angle between normal to detector plane and reference ray }{ \sstdescription{ This attribute gives the angle of incidence of light of the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}) onto the detector. Specifically, it holds the angle (in radians) between the normal to the detector plane and an incident ray at the reference wavelength. The default value is 0.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismWaveR }{ The reference wavelength }{ \sstdescription{ This attribute holds reference wavelength. The default value is 5000 (Angstrom). The units of this attribute should be consistent with those of attributes \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG}. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ ID }{ Object identification string }{ \sstdescription{ This attribute contains a string which may be used to identify the \htmlref{Object}{Object} to which it is attached. There is no restriction on the contents of this string, which is not used internally by the AST library, and is simply returned without change when required. The default value is an empty string. An identification string can be valuable when, for example, several Objects have been stored in a file (using \htmlref{AST\_WRITE}{AST\_WRITE}) and are later retrieved (using \htmlref{AST\_READ}{AST\_READ}). Consistent use of the ID attribute allows the retrieved Objects to be identified without depending simply on the order in which they were stored. This attribute may also be useful during debugging, to distinguish similar Objects when using \htmlref{AST\_SHOW}{AST\_SHOW} to display them. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the AST\_WRITE routine. } } } \sstroutine{ IF }{ The intermediate frequency in a dual sideband spectrum }{ \sstdescription{ This attribute specifies the (topocentric) intermediate frequency in a dual sideband spectrum. Its sole use is to determine the local oscillator (LO) frequency (the frequency which marks the boundary between the lower and upper sidebands). The LO frequency is equal to the sum of the centre frequency and the intermediate frequency. Here, the \texttt{"} centre frequency\texttt{"} is the topocentric frequency in Hz corresponding to the current value of the \htmlref{DSBCentre}{DSBCentre} attribute. The value of the IF attribute may be positive or negative: a positive value results in the LO frequency being above the central frequency, whilst a negative IF value results in the LO frequency being below the central frequency. The sign of the IF attribute value determines the default value for the \htmlref{SideBand}{SideBand} attribute. When setting a new value for this attribute, the units in which the frequency value is supplied may be indicated by appending a suitable string to the end of the formatted value. If the units are not specified, then the supplied value is assumed to be in units of GHz. For instance, the following strings all result in an IF of 4 GHz being used: \texttt{"} 4.0\texttt{"} , \texttt{"} 4.0 GHz\texttt{"} , \texttt{"} 4.0E9 Hz\texttt{"} , etc. When getting the value of this attribute, the returned value is always in units of GHz. The default value for this attribute is 4 GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ Ident }{ Permanent Object identification string }{ \sstdescription{ This attribute is like the \htmlref{ID}{ID} attribute, in that it contains a string which may be used to identify the \htmlref{Object}{Object} to which it is attached. The only difference between ID and Ident is that Ident is transferred when an Object is copied, but ID is not. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ ImagFreq }{ The image sideband equivalent of the rest frequency }{ \sstdescription{ This is a read-only attribute giving the frequency which corresponds to the rest frequency but is in the opposite sideband. The value is calculated by first transforming the rest frequency (given by the \htmlref{RestFreq}{RestFreq} attribute) from the standard of rest of the source (given by the \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} attributes) to the standard of rest of the observer (i.e. the topocentric standard of rest). The resulting topocentric frequency is assumed to be in the same sideband as the value given for the \htmlref{DSBCentre}{DSBCentre} attribute (the \texttt{"} observed\texttt{"} sideband), and is transformed to the other sideband (the \texttt{"} image\texttt{"} sideband). The new frequency is converted back to the standard of rest of the source, and the resulting value is returned as the attribute value, in units of GHz. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ Indent }{ Specifies the indentation to use in text produced by a Channel }{ \sstdescription{ This attribute controls the indentation within the output text produced by the \htmlref{AST\_WRITE}{AST\_WRITE} function. It gives the increase in the indentation for each level in the object heirarchy. If it is set to zero, no indentation will be used. [3] } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Channel}{Channel} }{ The default value is zero for a basic Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The FitsChan class ignores this attribute. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The default value for an StcsChan is zero, which causes the entire STC-S description is written out by a single invocation of the sink function. The text supplied to the sink function will not contain any linefeed characters, and each pair of adjacent words will be separated by a single space. The text may thus be arbitrarily large and the \htmlref{StcsLength}{StcsLength} attribute is ignored. If Indent is non-zero, then the text is written out via multiple calls to the sink function, each call corresponding to a single \texttt{"} line\texttt{"} of text (although no line feed characters will be inserted by AST). The complete STC-S description is broken into lines so that: \sstitemlist{ \sstitem the line length specified by attribute StcsLength is not exceeded \sstitem each sub-phrase (time, space, etc.) starts on a new line \sstitem each argument in a compound spatial region starts on a new line } If this causes a sub-phrase to extend to two or more lines, then the second and subsequent lines will be indented by three spaces compared to the first line. In addition, lines within a compound spatial region will have extra indentation to highlight the nesting produced by the parentheses. Each new level of nesting will be indented by a further three spaces. Note, the default value of zero is unlikely to be appropriate when an StcsChan is used within Fortran code. In this case, Indent should usually be set non-zero, and the StcsLength attribute set to the size of the CHARACTER variable used to receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function. This avoids the possibility of long lines being truncated invisibly within AST\_GETLINE. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value for an XmlChan is zero, which results in no linefeeds or indentation strings being added to output text. If any non-zero value is assigned to Indent, then extra linefeed and space characters will be inserted as necessary to ensure that each XML tag starts on a new line, and each tag will be indented by a further 3 spaces to show its depth in the containment hierarchy. } } } \sstroutine{ InternalUnit(axis) }{ Physical units for unformated axis values }{ \sstdescription{ This read-only attribute contains a textual representation of the physical units used to represent unformatted (i.e. floating point) values on a particular axis of a \htmlref{Frame}{Frame}, typically handled internally within application code. In most cases, the value of the InternalUnit attribute will be the same as Unit attribute (i.e. formatted and unformatted axis values will normally use the same system of units). The main exception to this is the \htmlref{SkyFrame}{SkyFrame} class, which represents unformatted axis values in radians, regardless of the current setting of the Unit attribute. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ IntraFlag }{ IntraMap identification string }{ \sstdescription{ This attribute allows an \htmlref{IntraMap}{IntraMap} to be flagged so that it is distinguishable from other IntraMaps. The transformation routine associated with the IntraMap may then enquire the value of this attribute and adapt the transformation it provides according to the particular IntraMap involved. Although this is a string attribute, it may often be useful to store numerical values here, encoded as a character string, and to use these as data within the transformation routine. Note, however, that this mechanism is not suitable for transferring large amounts of data (more than about 1000 characters) to an IntraMap. For that purpose, global variables are recommended, although the IntraFlag value can be used to supplement this approach. The default IntraFlag value is an empty string. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ IntraMap }{ All IntraMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem A pair of IntraMaps whose transformations may potentially cancel cannot be simplified to produce a \htmlref{UnitMap}{UnitMap} (e.g. using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}) unless they have the same IntraFlag values. The test for equality is case-sensitive. } } } \sstroutine{ Invert }{ Mapping inversion flag }{ \sstdescription{ This attribute controls which one of a \htmlref{Mapping}{Mapping}\texttt{'} s two possible coordinate transformations is considered the \texttt{"} forward\texttt{"} transformation (the other being the \texttt{"} inverse\texttt{"} transformation). If the attribute value is zero (the default), the Mapping\texttt{'} s behaviour will be the same as when it was first created. However, if it is non-zero, its two transformations will be inter-changed, so that the Mapping displays the inverse of its original behaviour. Inverting the boolean sense of the Invert attribute will cause the values of a Mapping\texttt{'} s \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes to be interchanged. The values of its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes will also be interchanged. This operation may be performed with the \htmlref{AST\_INVERT}{AST\_INVERT} routine. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{UnitMap}{UnitMap} }{ The value of the Invert attribute has no effect on the behaviour of a UnitMap. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ Inverting the boolean sense of the Invert attribute for a FrameSet will cause its base and current Frames (and its \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes) to be interchanged. This, in turn, may affect other properties and attributes of the FrameSet (such as Nin, Nout, \htmlref{Naxes}{Naxes}, TranForward, TranInverse, etc.). The Invert attribute of a FrameSet is not itself affected by selecting a new base or current \htmlref{Frame}{Frame}. } } } \sstroutine{ Invisible }{ Draw graphics using invisible ink? }{ \sstdescription{ This attribute controls the appearance of all graphics produced by \htmlref{Plot}{Plot} methods by determining whether graphics should be visible or invisible. If the Invisible value of a Plot is non-zero, then all the Plot methods which normally generate graphical output do not do so (you can think of them drawing with \texttt{"} invisible ink\texttt{"} ). Such methods do, however, continue to do all the calculations which would be needed to produce the graphics. In particular, the bounding box enclosing the graphics is still calculated and can be retrieved as normal using \htmlref{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}. The default value is zero, resulting in all methods drawing graphics as normal, using visible ink. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ IsLatAxis(axis) }{ Is the specified celestial axis a latitude axis? }{ \sstdescription{ This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial latitude axis (Declination, Galactic latitude, etc), and is zero otherwise. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. } } } \sstroutine{ IsLinear }{ Is the Mapping linear? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is an instance of a class that always represents a linear transformation. Note, some Mapping classes can represent linear or non-linear transformations (the \htmlref{MathMap}{MathMap} class for instance). Such classes have a zero value for the IsLinear attribute. Specific instances of such classes can be tested for linearity using the astLinearApprox function. \htmlref{AST\_LINEARAPPROX}{AST\_LINEARAPPROX} routine. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The IsLinear value for a CmpMap is determined by the classes of the encapsulated Mappings. For instance, a CmpMap that combines a \htmlref{ZoomMap}{ZoomMap} and a \htmlref{ShiftMap}{ShiftMap} will have a non-zero value for its IsLinear attribute, but a CmpMap that contains a MathMap will have a value of zero for its IsLinear attribute. } \sstsubsection{ \htmlref{Frame}{Frame} }{ The IsLinear value for a Frame is 1 (since a Frame is equivalent to a \htmlref{UnitMap}{UnitMap}). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The IsLinear value for a FrameSet is obtained from the Mapping from the base Frame to the current Frame. } } } \sstroutine{ IsLonAxis(axis) }{ Is the specified celestial axis a longitude axis? }{ \sstdescription{ This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial longitude axis (Right Ascension, Galactic longitude, etc), and is zero otherwise. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. } } } \sstroutine{ IsSimple }{ Has the Mapping been simplified? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} has been simplified by the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} method. If the IsSimple value is non-zero, then the Mapping has been simplified and so there is nothing to be gained by simplifying it again. Indeed, the AST\_SIMPLIFY method will immediately return the Mapping unchanged if the IsSimple attribute indicates that the Mapping has already been simplified. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{Frame}{Frame} }{ All classes of Frame return zero for the IsSimple attribute. This is because changes can be made to a Frame which affect the Mapping represented by the Frame, and so there can be no guarantee that the Mapping may not need re-simplifying. Most non-Frame Mappings, on the other hand, are immutable and so when they are simplified it is certain that they weill remain in a simple state. } } } \sstroutine{ IterInverse }{ Provide an iterative inverse transformation? }{ \sstdescription{ This attribute indicates whether the inverse transformation of the \htmlref{PolyMap}{PolyMap} should be implemented via an iterative Newton-Raphson approximation that uses the forward transformation to transform candidate input positions until an output position is found which is close to the required output position. By default, an iterative inverse is provided if, and only if, no inverse polynomial was supplied when the PolyMap was constructed. The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that control the behaviour of the inverse approcimation method. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ PolyMap }{ All PolyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem An iterative inverse can only be used if the PolyMap has equal numbers of inputs and outputs, as given by the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. An error will be reported if IterInverse is set non-zero for a PolyMap that does not meet this requirement. } } } \sstroutine{ Iwc }{ Include a Frame representing FITS-WCS intermediate world coordinates? }{ \sstdescription{ This attribute is a boolean value which is used when a \htmlref{FrameSet}{FrameSet} is read from a \htmlref{FitsChan}{FitsChan} with a foreign FITS encoding (e.g. FITS-WCS) using \htmlref{AST\_READ}{AST\_READ}. If it has a non-zero value then the returned FrameSet will include Frames representing \texttt{"} intermediate world coordinates\texttt{"} (IWC). These Frames will have \htmlref{Domain}{Domain} name \texttt{"} IWC\texttt{"} for primary axis descriptions, and \texttt{"} IWCa\texttt{"} for secondary axis descriptions, where \texttt{"} a\texttt{"} is replaced by the single alternate axis description character, as used in the FITS-WCS header. The default value for \texttt{"} Iwc\texttt{"} is zero. FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one axis for each WCS axis, and is the coordinate system produced by the rotation matrix (represented by FITS keyword PCi\_j, CDi\_j, etc). For instance, for a 2-D FITS-WCS header describing projected celestial longitude and latitude, the intermediate world coordinates represent offsets in degrees from the reference point within the plane of projection. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ KeyCase }{ Are keys case sensitive? }{ \sstdescription{ This attribute is a boolean value which controls how keys are used. If KeyCase is zero, then key strings supplied to any method are automatically converted to upper case before being used. If KeyCase is non-zero (the default), then supplied key strings are used without modification. The value of this attribute can only be changed if the \htmlref{KeyMap}{KeyMap} is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to change the attribute value when the KeyMap contains any entries. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } \sstsubsection{ \htmlref{Table}{Table} }{ The Table class over-rides this attribute by forcing it to zero. That is, keys within a Table are always case insensitive. } } } \sstroutine{ KeyError }{ Report an error when getting the value of a non-existant KeyMap entry? }{ \sstdescription{ This attribute is a boolean value which controls how the AST\_MAPGET... functions behave if the requested key is not found in the \htmlref{KeyMap}{KeyMap}. If KeyError is zero (the default), then these functions will return .FALSE. but no error will be reported. If KeyError is non-zero, then the same values are returned but an error is also reported. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When setting a new value for KeyError, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap. \sstitem When clearing the KeyError attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. } } } \sstroutine{ LTOffset }{ The offset from UTC to Local Time, in hours }{ \sstdescription{ This specifies the offset from UTC to Local Time, in hours (fractional hours can be supplied). It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ All TimeFrames have this attribute. } } } \sstroutine{ Label(axis) }{ Axis label }{ \sstdescription{ This attribute specifies a label to be attached to each axis of a \htmlref{Frame}{Frame} when it is represented (e.g.) in graphical output. If a Label value has not been set for a Frame axis, then a suitable default is supplied. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is the string \texttt{"} \htmlref{Axis}{Axis} $<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for each successive axis. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Label value (e.g. to \texttt{"} Right ascension\texttt{"} or \texttt{"} Galactic latitude\texttt{"} ) as appropriate for the particular celestial coordinate system being represented. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Label value as appropriate for the particular time system being represented. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem Axis labels are intended purely for interpretation by human readers and not by software. \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ LabelAt(axis) }{ Where to place numerical labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining where numerical axis labels and associated tick marks are placed. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LabelAt(2)=10.0\texttt{"} specifies where the numerical labels and tick marks for the second axis should be drawn. For each axis, the LabelAt value gives the value on the other axis at which numerical labels and tick marks should be placed (remember that Plots suitable for use with AST\_GRID may only have two axes). For example, in a celestial (RA,Dec) coordinate system, LabelAt(1) gives a Dec value which defines a line (of constant Dec) along which the numerical RA labels and their associated tick marks will be drawn. Similarly, LabelAt(2) gives the RA value at which the Dec labels and ticks will be drawn. The default bahaviour is for the Plot to generate its own position for numerical labels and tick marks. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The LabelAt value should use the same units as are used internally for storing coordinate values on the appropriate axis. For example, with a celestial coordinate system, the LabelAt value should be in radians, not hours or degrees. \sstitem Normally, the LabelAt value also determines where the lines representing coordinate axes will be drawn, so that the tick marks will lie on these lines (but also see the DrawAxes attribute). \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the LabelAt attribute is ignored. } } } \sstroutine{ LabelUnits(axis) }{ Use axis unit descriptions in a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether the descriptive labels drawn for each axis of a \htmlref{Plot}{Plot} should include a description of the units being used on the axis. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} LabelUnits(2)=1\texttt{"} specifies that a unit description should be included in the label for the second axis. If the LabelUnits value of a Plot axis is non-zero, a unit description will be included in the descriptive label for that axis, otherwise it will be omitted. The default behaviour is to include a unit description unless the current \htmlref{Frame}{Frame} of the Plot is a \htmlref{SkyFrame}{SkyFrame} representing equatorial, ecliptic, galactic or supergalactic coordinates, in which case it is omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the unit description is obtained from the Plot\texttt{'} s \htmlref{Unit(axis)}{Unit(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} LabelUnits\texttt{"} instead of \texttt{"} LabelUnits(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LabelUnits(1) value. \sstitem If the current Frame of the Plot is not a SkyFrame, but includes axes which were extracted from a SkyFrame, then the default behaviour is to include a unit description only for those axes which were not extracted from a SkyFrame. } } } \sstroutine{ LabelUp(axis) }{ Draw numerical Plot labels upright? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether the numerical labels for each axis of a \htmlref{Plot}{Plot} should be drawn upright or not. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} LabelUp(2)=1\texttt{"} specifies that numerical labels for the second axis should be drawn upright. If the LabelUp value of a Plot axis is non-zero, it causes numerical labels for that axis to be plotted upright (i.e. as normal, horizontal text), otherwise labels are drawn parallel to the axis to which they apply. The default is to produce upright labels if the labels are placed around the edge of the plot, and to produce labels that follow the axes if the labels are placed within the interior of the plot (see attribute \htmlref{Labelling}{Labelling}). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the Labelling attribute). In this case, the value of the LabelUp attribute is ignored. \sstitem If no axis is specified, (e.g. \texttt{"} LabelUp\texttt{"} instead of \texttt{"} LabelUp(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LabelUp(1) value. } } } \sstroutine{ Labelling }{ Label and tick placement option for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the strategy for placing numerical labels and tick marks for a \htmlref{Plot}{Plot}. If the Labelling value of a Plot is \texttt{"} exterior\texttt{"} (the default), then numerical labels and their associated tick marks are placed around the edges of the plotting area, if possible. If this is not possible, or if the Labelling value is \texttt{"} interior\texttt{"} , then they are placed along grid lines inside the plotting area. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute may be used to determine the exact placement of labels and tick marks that are drawn inside the plotting area. } } } \sstroutine{ LatAxis }{ Index of the latitude axis }{ \sstdescription{ This read-only attribute gives the index (1 or 2) of the latitude axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis permutations). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ ListSize }{ Number of points in a PointList }{ \sstdescription{ This is a read-only attribute giving the number of points in a \htmlref{PointList}{PointList}. This value is determined when the PointList is created. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ PointList }{ All PointLists have this attribute. } } } \sstroutine{ LogGap(axis) }{ Interval between major axis values of a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the logarithmic interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} LogGap(2)=100.0\texttt{"} specifies the ratio between adjacent major values along the second axis. The LogGap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be logarithmic. If major axis values are linearly spaced then the gap is specified using attribute Gap. The LogGap value supplied will be rounded to the nearest power of 10. The reciprocal of the supplied value may be used if this is necessary to produce usable major axis values. If a zero or negative value is supplied, an error will be reported when the grid is drawn. The default behaviour is for the Plot to generate its own LogGap value when required, based on the range of axis values to be represented. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The LogGap value is a ratio between axis values and is therefore dimensionless. \sstitem If no axis is specified, (e.g. \texttt{"} LogGap\texttt{"} instead of \texttt{"} LogGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogGap(1) value. } } } \sstroutine{ LogLabel(axis) }{ Use exponential format for numerical axis labels? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether the numerical axis labels should be in normal decimal form or should be represented as 10 raised to the appropriate power. That is, an axis value of 1000.0 will be drawn as \texttt{"} 1000.0\texttt{"} if LogLabel is zero, but as \texttt{"} 10$\wedge$3\texttt{"} if LogLabel is non-zero. If graphical escape sequences are supported (see attribute \htmlref{Escape}{Escape}), the power in such exponential labels will be drawn as a small superscript instead of using a \texttt{"} $\wedge$\texttt{"} character to represent exponentiation. The default is to produce exponential labels if the major tick marks are logarithmically spaced (see the LogTicks attribute). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Plot}{Plot} }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} LogLabel\texttt{"} instead of \texttt{"} LogLabel(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogLabel(1) value. } } } \sstroutine{ LogPlot(axis) }{ Map the plot logarithmically onto the screen? }{ \sstdescription{ This attribute controls the appearance of all graphics produced by the \htmlref{Plot}{Plot}, by determining whether the axes of the plotting surface are mapped logarithmically or linearly onto the base \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} supplied when the Plot was constructed. It takes a separate value for each axis of the graphics coordinate system (i.e. the base Frame in the Plot) so that, for instance, the setting \texttt{"} LogPlot(2)=1\texttt{"} specifies that the second axis of the graphics coordinate system (usually the vertical axis) should be mapped logarithmically onto the second axis of the base Frame of the FrameSet supplied when the Plot was constructed. If the LogPlot value of a Plot axis is non-zero, it causes that axis to be mapped logarithmically, otherwise (the default) the axis is mapped linearly. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The setting of the LogPlot attribute provides the default value for the related LogTicks attribute. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vice-versa). \sstitem An axis may only be mapped logarithmically if the visible part of the axis does not include the value zero. The visible part of the axis is that part which is mapped onto the plotting area, and is measured within the base Frame of the FrameSet which was supplied when the Plot was constructed. Any attempt to set LogPlot to a non-zero value will be ignored (without error) if the visible part of the axis includes the value zero \sstitem If no axis is specified, (e.g. \texttt{"} LogPlot\texttt{"} instead of \texttt{"} LogPlot(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogPlot(1) value. } } } \sstroutine{ LogTicks(axis) }{ Space the major tick marks logarithmically? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether the major tick marks should be spaced logarithmically or linearly in axis value. It takes a separate value for each physical axis of the \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LogTicks(2)=1\texttt{"} specifies that the major tick marks on the second axis should be spaced logarithmically. If the LogTicks value for a physical axis is non-zero, the major tick marks on that axis will be spaced logarithmically (that is, there will be a constant ratio between the axis values at adjacent major tick marks). An error will be reported if the dynamic range of the axis (the ratio of the largest to smallest displayed axis value) is less than 10.0. If the LogTicks value is zero, the major tick marks will be evenly spaced (that is, there will be a constant difference between the axis values at adjacent major tick marks). The default is to produce logarithmically spaced tick marks if the corresponding LogPlot attribute is non-zero and the ratio of maximum axis value to minimum axis value is 100 or more. If either of these conditions is not met, the default is to produce linearly spaced tick marks. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The setting of the LogTicks attribute does not affect the mapping of the plot onto the screen, which is controlled by attribute LogPlot. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vica-versa). \sstitem An error will be reported when drawing an annotated axis grid if the visible part of the physical axis includes the value zero. \sstitem If no axis is specified, (e.g. \texttt{"} LogTicks\texttt{"} instead of \texttt{"} LogTicks(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogTicks(1) value. } } } \sstroutine{ LonAxis }{ Index of the longitude axis }{ \sstdescription{ This read-only attribute gives the index (1 or 2) of the longitude axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis permutations). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ LutEpsilon }{ The relative error of the values held in the took-up table }{ \sstdescription{ This attribute holds the relative error of the values held in the took-up table. It is used when simplifying a \htmlref{LutMap}{LutMap}, to determine if the LutMap should be considered linear. Setting a larger value makes it more likely that a LutMap will be replaced by a \htmlref{WinMap}{WinMap} (i.e. a linear \htmlref{Mapping}{Mapping}) when simplified. The default value is the value of the system constant DBL\_EPSILON (typically around 1e-16 or 2E-16). If the values in the look-up table were derived from single precision data, it may be appropriate to set this attribute to a value around 1E-7. Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ LutMap }{ All LutMaps have this attribute. } } } \sstroutine{ LutInterp }{ Look-up table interpolation method }{ \sstdescription{ This attribute indicates the method to be used when finding the output value of a \htmlref{LutMap}{LutMap} for an input value part way between two table entries. If it is set to 0 (the default) then linear interpolation is used. Otherwise, nearest neighbour interpolation is used. Using nearest neighbour interpolation causes AST\_\_BAD to be returned for any point which falls outside the bounds of the table. Linear interpolation results in an extrapolated value being returned based on the two end entries in the table. Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ LutMap }{ All LutMaps have this attribute. } } } \sstroutine{ MajTickLen(axis) }{ Length of major tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the length of the major tick marks drawn on the axes of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} MajTickLen(2)=0\texttt{"} specifies the length of the major tick marks drawn on the second axis. The MajTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause major tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside. The default behaviour depends on whether a coordinate grid is drawn inside the plotting area (see the \htmlref{Grid}{Grid} attribute). If so, the default MajTickLen value is zero (so that major ticks are not drawn), otherwise the default is $+$0.015. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} MajTickLen\texttt{"} instead of \texttt{"} MajTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MajTickLen(1) value. } } } \sstroutine{ MapLocked }{ Prevent new entries being added to a KeyMap? }{ \sstdescription{ If this boolean attribute is set to .TRUE., an error will be reported if an attempt is made to add a new entry to the \htmlref{KeyMap}{KeyMap}. Note, the value associated with any existing entries can still be changed, but no new entries can be stored in the KeyMap. The default value (.FALSE.) allows new entries to be added to the KeyMap. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When setting a new value for MapLocked, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap. \sstitem When clearing the MapLocked attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. } } } \sstroutine{ MatchEnd }{ Match trailing axes? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It applies only in the case where a match occurs between template and target Frames with different numbers of axes. If the MatchEnd value of the template Frame is zero, then the axes which occur first in the target Frame will be matched and any trailing axes (in either the target or template) will be disregarded. If it is non-zero, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ The default MatchEnd value for a Frame is zero, so that trailing axes are disregarded. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ MaxAxes }{ Maximum number of Frame axes to match }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It specifies the maximum number of axes that the target Frame may have in order to match the template. Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default MaxAxes value for a Frame is equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The MaxAxes attribute of a CmpFrame defaults to a large number (1000000) which is much larger than any likely number of axes in a Frame. Combined with the \htmlref{MinAxes}{MinAxes} default of zero (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MaxAxes and MinAxes attributes to the number of axes in the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When setting a MaxAxes value, the value of the MinAxes attribute may also be silently changed so that it remains consistent with (i.e. does not exceed) the new value. The default MaxAxes value may also be reduced to remain consistent with the MinAxes value. \sstitem If a template Frame is used to match a target with a different number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used to determine how the individual axes of each Frame should match. } } } \sstroutine{ MeshSize }{ Number of points used to represent the boundary of a Region }{ \sstdescription{ This attribute controls how many points are used when creating a mesh of points covering the boundary or volume of a \htmlref{Region}{Region}. Such a mesh is returned by the \htmlref{AST\_GETREGIONMESH}{AST\_GETREGIONMESH} method. The boundary mesh is also used when testing for overlap between two Regions: each point in the bomdary mesh of the first Region is checked to see if it is inside or outside the second Region. Thus, the reliability of the overlap check depends on the value assigned to this attribute. If the value used is very low, it is possible for overlaps to go unnoticed. High values produce more reliable results, but can result in the overlap test being very slow. The default value is 200 for two dimensional Regions and 2000 for three or more dimensional Regions (this attribute is not used for 1-dimensional regions since the boundary of a simple 1-d Region can only ever have two points). A value of five is used if the supplied value is less than five. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default MeshSize for a CmpRegion is the MeshSize of its first component Region. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default MeshSize for an Stc is the MeshSize of its encapsulated Region. } } } \sstroutine{ MinAxes }{ Minimum number of Frame axes to match }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It specifies the minimum number of axes that the target Frame may have in order to match the template. Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default MinAxes value for a Frame is equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The MinAxes attribute of a CmpFrame defaults to zero. Combined with the \htmlref{MaxAxes}{MaxAxes} default of 1000000 (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MinAxes and MaxAxes attributes to the number of axes in the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When setting a MinAxes value, the value of the MaxAxes attribute may also be silently changed so that it remains consistent with (i.e. is not less than) the new value. The default MinAxes value may also be reduced to remain consistent with the MaxAxes value. \sstitem If a template Frame is used to match a target with a different number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used to determine how the individual axes of each Frame should match. } } } \sstroutine{ MinTick(axis) }{ Density of minor tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the density of minor tick marks which appear between the major axis values of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} MinTick(2)=2\texttt{"} specifies the density of minor tick marks along the second axis. The value supplied should be the number of minor divisions required between each pair of major axis values, this being one more than the number of minor tick marks to be drawn. By default, a value is chosen that depends on the gap between major axis values and the nature of the axis. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} MinTick\texttt{"} instead of \texttt{"} MinTick(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MinTick(1) value. } } } \sstroutine{ MinTickLen(axis) }{ Length of minor tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining the length of the minor tick marks drawn on the axes of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} MinTickLen(2)=0\texttt{"} specifies the length of the minor tick marks drawn on the second axis. The MinTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause minor tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside. The default value is $+$0.007. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The number of minor tick marks drawn is determined by the Plot\texttt{'} s \htmlref{MinTick(axis)}{MinTick(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} MinTickLen\texttt{"} instead of \texttt{"} MinTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MinTickLen(1) value. } } } \sstroutine{ NatLat }{ Native latitude of the reference point of a FITS-WCS projection }{ \sstdescription{ This attribute gives the latitude of the reference point of the FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in radians in the \texttt{"} native spherical\texttt{"} coordinate system. This value is fixed for most projections, for instance it is PI/2 (90 degrees) for all zenithal projections. For some projections (e.g. the conics) the value is not fixed, but is specified by parameter one on the latitude axis. FITS-WCS paper II introduces the concept of a \texttt{"} fiducial point\texttt{"} which is logical distinct from the projection reference point. It is easy to confuse the use of these two points. The fiducial point is the point which has celestial coordinates given by the CRVAL FITS keywords. The native spherical coordinates for this point default to the values of the NatLat and \htmlref{NatLon}{NatLon}, but these defaults mey be over-ridden by values stored in the PVi\_j keywords. Put another way, the CRVAL keywords will by default give the celestial coordinates of the projection reference point, but may refer to some other point if alternative native longitude and latitude values are provided through the PVi\_j keywords. The NatLat attribute is read-only. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem A default value of AST\_\_BAD is used if no latitude value is available. } } } \sstroutine{ NatLon }{ Native longitude of the reference point of a FITS-WCS projection }{ \sstdescription{ This attribute gives the longitude of the reference point of the FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in radians in the \texttt{"} native spherical\texttt{"} coordinate system, and will usually be zero. See the description of attribute \htmlref{NatLat}{NatLat} for further information. The NatLon attribute is read-only. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ Naxes }{ Number of Frame axes }{ \sstdescription{ This is a read-only attribute giving the number of axes in a \htmlref{Frame}{Frame} (i.e. the number of dimensions of the coordinate space which the Frame describes). This value is determined when the Frame is created. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Naxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The Naxes attribute of a CmpFrame is equal to the sum of the Naxes values of its two component Frames. } } } \sstroutine{ Ncard }{ Number of FITS header cards in a FitsChan }{ \sstdescription{ This attribute gives the total number of FITS header cards stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Ncolumn }{ The number of columns in the table }{ \sstdescription{ This attribute holds the number of columns currently in the table. Columns are added and removed using the \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN} and \htmlref{AST\_REMOVECOLUMN}{AST\_REMOVECOLUMN} functions. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ NegLon }{ Display negative longitude values? }{ \sstdescription{ This attribute is a boolean value which controls how longitude values are normalized for display by \htmlref{AST\_NORM}{AST\_NORM}. If the NegLon attribute is zero, then normalized longitude values will be in the range zero to 2.pi. If NegLon is non-zero, then normalized longitude values will be in the range -pi to pi. The default value depends on the current value of the \htmlref{SkyRefIs}{SkyRefIs} attribute, If SkyRefIs has a value of \texttt{"} Origin\texttt{"} , then the default for NegLon is one, otherwise the default is zero. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } } \sstroutine{ Negated }{ Region negation flag }{ \sstdescription{ This attribute controls whether a \htmlref{Region}{Region} represents the \texttt{"} inside\texttt{"} or the \texttt{"} outside\texttt{"} of the area which was supplied when the Region was created. If the attribute value is zero (the default), the Region represents the inside of the original area. However, if it is non-zero, it represents the outside of the original area. The value of this attribute may be toggled using the \htmlref{AST\_NEGATE}{AST\_NEGATE} routine. Note, whether the boundary is considered to be inside the Region or not is controlled by the \htmlref{Closed}{Closed} attribute. Changing the value of the Negated attribute does not change the value of the Closed attribute. Thus, if Region is closed, then the boundary of the Region will be inside the Region, whatever the setting of the Negated attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ Nframe }{ Number of Frames in a FrameSet }{ \sstdescription{ This attrbute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This value will change as Frames are added or removed, but will always be at least one. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } } \sstroutine{ Nin }{ Number of input coordinates for a Mapping }{ \sstdescription{ This attribute gives the number of coordinate values required to specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of dimensions of the space in which the Mapping\texttt{'} s input points reside). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If a CmpMap\texttt{'} s component Mappings are joined in series, then its Nin attribute is equal to the Nin attribute of the first component (or to the \htmlref{Nout}{Nout} attribute of the second component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). If a CmpMap\texttt{'} s component Mappings are joined in parallel, then its Nin attribute is given by the sum of the Nin attributes of each component (or to the sum of their Nout attributes if the CmpMap\texttt{'} s Invert attribute is non-zero). } \sstsubsection{ \htmlref{Frame}{Frame} }{ The Nin attribute for a Frame is always equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Nin attribute of a FrameSet is equal to the number of axes (Naxes attribute) of its base Frame (as specified by the FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may therefore change if a new base Frame is selected. } } } \sstroutine{ NiterInverse }{ Maximum number of iterations for the iterative inverse transformation }{ \sstdescription{ This attribute controls the iterative inverse transformation used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. Its value gives the maximum number of iterations of the Newton-Raphson algorithm to be used for each transformed position. The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ \htmlref{PolyMap}{PolyMap} }{ All PolyMaps have this attribute. } } } \sstroutine{ Nkey }{ Number of unique FITS keywords in a FitsChan }{ \sstdescription{ This attribute gives the total number of unique FITS keywords stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or deleted. If no keyword occurrs more than once in the FitsChan, the \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs more than once, the Nkey attribute value will be smaller than the Ncard attribute value. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Nobject }{ Number of Objects in class }{ \sstdescription{ This attribute gives the total number of Objects currently in existence in the same class as the \htmlref{Object}{Object} whose attribute value is requested. This count does not include Objects which belong to derived (more specialised) classes. This attribute is mainly intended for debugging. It can be used to detect whether Objects which should have been deleted have, in fact, been deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Norm(axis) }{ Specifies the plane upon which a Plot3D draws text and markers }{ \sstdescription{ This attribute controls the appearance of text and markers drawn by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which text and markers will be drawn by all subsequent invocations of the \htmlref{AST\_TEXT}{AST\_TEXT} and \htmlref{AST\_MARK}{AST\_MARK} functions. When setting or getting the Norm attribute, the attribute name must be qualified by an axis index in the range 1 to 3. The 3 elements of the Norm attribute are together interpreted as a vector in 3D graphics coordinates that is normal to the plane upon which text and marks should be drawn. When testing or clearing the attribute, the axis index is optional. If no index is supplied, then clearing the Norm attribute will clear all three elements, and testing the Norm attribute will return a non-zero value if any of the three elements are set. The default value is 1.0 for each of the 3 elements. The length of the vector is insignificant, but an error will be reported when attempting to draw text or markers if the vector has zero length. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Plot}{Plot} }{ All Plot3Ds have this attribute. } } } \sstroutine{ NormUnit(axis) }{ Normalised physical units for formatted axis values }{ \sstdescription{ The value of this read-only attribute is derived from the current value of the Unit attribute. It will represent an equivalent system of units to the Unit attribute, but will potentially be simplified. For instance, if Unit is set to \texttt{"} s$*$(m/s)\texttt{"} , the NormUnit value will be \texttt{"} m\texttt{"} . If no simplification can be performed, the value of the NormUnit attribute will equal that of the Unit attribute. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ All Frames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ Nout }{ Number of output coordinates for a Mapping }{ \sstdescription{ This attribute gives the number of coordinate values generated by a \htmlref{Mapping}{Mapping} to specify each output point (i.e. the number of dimensions of the space in which the Mapping\texttt{'} s output points reside). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If a CmpMap\texttt{'} s component Mappings are joined in series, then its Nout attribute is equal to the Nout attribute of the second component (or to the \htmlref{Nin}{Nin} attribute of the first component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). If a CmpMap\texttt{'} s component Mappings are joined in parallel, then its Nout attribute is given by the sum of the Nout attributes of each component (or to the sum of their Nin attributes if the CmpMap\texttt{'} s Invert attribute is non-zero). } \sstsubsection{ \htmlref{Frame}{Frame} }{ The Nout attribute for a Frame is always equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Nout attribute of a FrameSet is equal to the number of FrameSet axes (Naxes attribute) which, in turn, is equal to the Naxes attribute of the FrameSet\texttt{'} s current Frame (as specified by the \htmlref{Current}{Current} attribute). The Nout attribute value may therefore change if a new current Frame is selected. } } } \sstroutine{ Nparameter }{ The number of global parameters in the table }{ \sstdescription{ This attribute holds the number of global parameters currently in the table. Parameters are added and removed using the \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER} and \htmlref{AST\_REMOVEPARAMETER}{AST\_REMOVEPARAMETER} functions. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ Nrow }{ The number of rows in the table }{ \sstdescription{ This attribute holds the index of the last row to which any contents have been added using any of the astMapPut... AST\_MAPPUT... functions. The first row has index 1. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ NumLab(axis) }{ Draw numerical axis labels for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether labels should be drawn to represent the numerical values along each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} NumLab(2)=1\texttt{"} specifies that numerical labels should be drawn for the second axis. If the NumLab value of a Plot axis is non-zero (the default), then numerical labels will be drawn for that axis, otherwise they will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The drawing of associated descriptive axis labels for a Plot (describing the quantity being plotted along each axis) is controlled by the \htmlref{TextLab(axis)}{TextLab(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} NumLab\texttt{"} instead of \texttt{"} NumLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the NumLab(1) value. } } } \sstroutine{ NumLabGap(axis) }{ Spacing of numerical labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining where numerical axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} NumLabGap(2)=-0.01\texttt{"} specifies where the numerical label for the second axis should be drawn. For each axis, the NumLabGap value gives the spacing between the axis line (or edge of the plotting area, if appropriate) and the nearest edge of the corresponding numerical axis labels. Positive values cause the descriptive label to be placed on the opposite side of the line to the default tick marks, while negative values cause it to be placed on the same side. The NumLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.01. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} NumLabGap\texttt{"} instead of \texttt{"} NumLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the NumLabGap(1) value. } } } \sstroutine{ ObjSize }{ The in-memory size of the Object }{ \sstdescription{ This attribute gives the total number of bytes of memory used by the \htmlref{Object}{Object}. This includes any Objects which are encapsulated within the supplied Object. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ ObsAlt }{ The geodetic altitude of the observer }{ \sstdescription{ This attribute specifies the geodetic altitude of the observer, in metres, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ ObsLat }{ The geodetic latitude of the observer }{ \sstdescription{ This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} , \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can optionally be indicated using characters \texttt{"} N\texttt{"} and \texttt{"} S\texttt{"} in place of the usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the format \texttt{"} [s]dd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} N\texttt{"} or \texttt{"} S\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ ObsLon }{ The geodetic longitude of the observer }{ \sstdescription{ This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} , \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can optionally be indicated using characters \texttt{"} E\texttt{"} and \texttt{"} W\texttt{"} in place of the usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the format \texttt{"} [s]ddd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} E\texttt{"} or \texttt{"} W\texttt{"} and the numerical value is chosen to be less than 180 degrees. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ PVMax(i) }{ Maximum number of FITS-WCS projection parameters }{ \sstdescription{ This attribute specifies the largest legal index for a PV projection parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the largest legal value for \texttt{"} m\texttt{"} when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"} attribute). The axis index is specified by i, and should be in the range 1 to 99. The value for each axis is determined by the projection type specified when the WcsMap is first created using \htmlref{AST\_WCSMAP}{AST\_WCSMAP} and cannot subsequently be changed. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ PVi\_m }{ FITS-WCS projection parameters }{ \sstdescription{ This attribute specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection. Each PV attribute name should include two integers, i and m, separated by an underscore. The axis index is specified by i, and should be in the range 1 to 99. The parameter number is specified by m, and should be in the range 0 to 99. For example, \texttt{"} PV2\_1=45.0\texttt{"} would specify a value for projection parameter 1 of axis 2 in a WcsMap. These projection parameters correspond exactly to the values stored using the FITS-WCS keywords \texttt{"} PV1\_1\texttt{"} , \texttt{"} PV1\_2\texttt{"} , etc. This means that projection parameters which correspond to angles must be given in degrees (despite the fact that the angular coordinates and other attributes used by a WcsMap are in radians). The set of projection parameters used by a WcsMap depends on the type of projection, which is determined by its \htmlref{WcsType}{WcsType} parameter. Most projections either do not require projection parameters, or use parameters 1 and 2 associated with the latitude axis. You should consult the FITS-WCS paper for details. Some projection parameters have default values (as defined in the FITS-WCS paper) which apply if no explicit value is given. You may omit setting a value for these \texttt{"} optional\texttt{"} parameters and the default will apply. Some projection parameters, however, have no default and a value must be explicitly supplied. This is most conveniently done using the OPTIONS argument of \htmlref{AST\_WCSMAP}{AST\_WCSMAP} (q.v.) when a WcsMap is first created. An error will result when a WcsMap is used to transform coordinates if any of its required projection parameters has not been set and lacks a default value. A \texttt{"} get\texttt{"} operation for a parameter which has not been assigned a value will return the default value defined in the FITS-WCS paper, or AST\_\_BAD if the paper indicates that the parameter has no default. A default value of zero is returned for parameters which are not accessed by the projection. Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude axis to hold the native longitude and latitude of the fiducial point of the projection, in degrees. The default values for these parameters are determined by the projection type. The AST-specific TPN projection does not use this convention - all projection parameters for both axes are used to represent polynomical correction terms, and the native longitude and latitude at the fiducial point may not be changed from the default values of zero and 90 degrees. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. \sstitem If the projection parameter values given for a WcsMap do not satisfy all the required constraints (as defined in the FITS-WCS paper), then an error will result when the WcsMap is used to transform coordinates. } } } \sstroutine{ PcdCen(axis) }{ Centre coordinates of pincushion/barrel distortion }{ \sstdescription{ This attribute specifies the centre of the pincushion/barrel distortion implemented by a \htmlref{PcdMap}{PcdMap}. It takes a separate value for each axis of the PcdMap so that, for instance, the settings \texttt{"} PcdCen(1)=345.0,PcdCen(2)=-104.4\texttt{"} specify that the pincushion distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2 respectively. This attribute is set when a PcdMap is created, but may later be modified. If the attribute is cleared, the default value for both axes is zero. Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ PcdMap }{ All PcdMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} PcdCen\texttt{"} instead of \texttt{"} PcdCen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of both axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the PcdCen(1) value. } } } \sstroutine{ Permute }{ Permute axis order? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It specifies whether the axis order of the target Frame may be permuted in order to obtain a match. If the template\texttt{'} s Permute value is zero, it will match a target only if it can do so without changing the order of its axes. Otherwise, it will attempt to permute the target\texttt{'} s axes as necessary. The default value is 1, so that axis permutation will be attempted. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. However, the Frame class effectively ignores this attribute and behaves as if it has the value 1. This is because the axes of a basic Frame are not distinguishable and will always match any other Frame whatever their order. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ Unlike a basic Frame, the SkyFrame class makes use of this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ PolarLong }{ The longitude value to assign to either pole }{ \sstdescription{ This attribute holds the longitude value, in radians, to be returned when a Cartesian position corresponding to either the north or south pole is transformed into spherical coordinates. The default value is zero. Note, the value of this attribute may changed only if the \htmlref{SphMap}{SphMap} has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ SphMap }{ All SphMaps have this attribute. } } } \sstroutine{ PolyTan }{ Use PVi\_m keywords to define distorted TAN projection? }{ \sstdescription{ This attribute is a boolean value which specifies how FITS \texttt{"} TAN\texttt{"} projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero, the projection is assumed to conform to the published FITS-WCS standard. If positive, the convention for a distorted TAN projection included in an early draft version of FITS-WCS paper II are assumed. In this convention the coefficients of a polynomial distortion to be applied to intermediate world coordinates are specified by the \htmlref{PVi\_m}{PVi\_m} keywords. This convention was removed from the paper before publication and so does not form part of the standard. Indeed, it is incompatible with the published standard because it re-defines the meaning of the first five PVi\_m keywords on the longitude axis, which are reserved by the published standard for other purposes. However, headers that use this convention are still to be found, for instance the SCAMP utility (http://www.astromatic.net/software/scamp) creates them. The default value for the PolyTan attribute is -1. A negative values causes the used convention to depend on the contents of the \htmlref{FitsChan}{FitsChan}. If the FitsChan contains any PVi\_m keywords for the latitude axis, or if it contains PVi\_m keywords for the longitude axis with \texttt{"} m\texttt{"} greater than 4, then the distorted TAN convention is used. Otherwise, the standard convention is used. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ PreserveAxes }{ Preserve axes? }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}) as a template to match another (target) Frame. It determines which axes appear (and in what order) in the \texttt{"} result\texttt{"} Frame produced. If PreserveAxes is zero in the template Frame, then the result Frame will have the same number (and order) of axes as the template. If it is non-zero, however, the axes of the target Frame will be preserved, so that the result Frame will have the same number (and order) of axes as the target. The default value is zero, so that target axes are not preserved and the result Frame resembles the template. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The PreserveAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ ProjP(m) }{ FITS-WCS projection parameters }{ \sstdescription{ This attribute provides aliases for the PV attributes, which specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection. ProjP is retained for compatibility with previous versions of FITS-WCS and AST. New applications should use the PV attibute instead. Attributes ProjP(0) to ProjP(9) correspond to attributes PV$<$axlat$>$\_0 to PV$<$axlat$>$\_9, where $<$axlat$>$ is replaced by the index of the latitude axis (given by attribute WcsAxis(2)). See PV for further details. Note, the value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ Projection }{ Sky projection description }{ \sstdescription{ This attribute provides a place to store a description of the type of sky projection used when a \htmlref{SkyFrame}{SkyFrame} is attached to a 2-dimensional object, such as an image or plotting surface. For example, typical values might be \texttt{"} orthographic\texttt{"} , \texttt{"} Hammer-Aitoff\texttt{"} or \texttt{"} cylindrical equal area\texttt{"} . The Projection value is purely descriptive and does not affect the celestial coordinate system represented by the SkyFrame in any way. If it is set to a non-blank string, the description provided may be used when forming the default value for the SkyFrame\texttt{'} s \htmlref{Title}{Title} attribute (so that typically it will appear in graphical output, for instance). The default value is an empty string. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ RefCount }{ Count of active Object pointers }{ \sstdescription{ This attribute gives the number of active pointers associated with an \htmlref{Object}{Object}. It is modified whenever pointers are created or annulled (by \htmlref{AST\_CLONE}{AST\_CLONE}, \htmlref{AST\_ANNUL}{AST\_ANNUL} or \htmlref{AST\_END}{AST\_END} for example). The count includes the initial pointer issued when the Object was created. If the reference count for an Object falls to zero as the result of annulling a pointer to it, then the Object will be deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ RefDec }{ The declination of the reference point }{ \sstdescription{ This attribute specifies the FK5 J2000.0 declination of a reference point on the sky. See the description of attribute \htmlref{RefRA}{RefRA} for details. The default RefDec is \texttt{"} 0:0:0\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ RefRA }{ The right ascension of the reference point }{ \sstdescription{ This attribute, together with the \htmlref{RefDec}{RefDec} attribute, specifies the FK5 J2000.0 coordinates of a reference point on the sky. For 1-dimensional spectra, this should normally be the position of the source. For spectral data with spatial coverage (spectral cubes, etc), this should be close to centre of the spatial coverage. It is used to define the correction for Doppler shift to be applied when using the \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT} method to convert between different standards of rest. The \htmlref{SpecFrame}{SpecFrame} class assumes this velocity correction is spatially invariant. If a single SpecFrame is used (for instance, as a component of a \htmlref{CmpFrame}{CmpFrame}) to describe spectral values at different points on the sky, then it is assumes that the doppler shift at any spatial position is the same as at the reference position. The maximum velocity error introduced by this assumption is of the order of V$*$SIN(FOV), where FOV is the angular field of view, and V is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of V is about 20 km/s, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 km/s. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 km/s over a 1 degree field of view. The RefRA and RefDec attributes are stored internally in radians, but are converted to and from a string for access. The format \texttt{"} hh:mm:ss.ss\texttt{"} is used for RefRA, and \texttt{"} dd:mm:ss.s\texttt{"} is used for RefDec. The methods \htmlref{AST\_SETREFPOS}{AST\_SETREFPOS} and \htmlref{AST\_GETREFPOS}{AST\_GETREFPOS} may be used to access the value of these attributes directly as unformatted values in radians. The default for RefRA is \texttt{"} 0:0:0\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ RegionClass }{ The AST class name of the Region encapsulated within an Stc }{ \sstdescription{ This is a read-only attribute giving the AST class name of the \htmlref{Region}{Region} encapsulated within an \htmlref{Stc}{Stc} (that is, the class of the Region which was supplied when the Stc was created). } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ Stc }{ All Stc objects this attribute. } } } \sstroutine{ Report }{ Report transformed coordinates? }{ \sstdescription{ This attribute controls whether coordinate values are reported whenever a \htmlref{Mapping}{Mapping} is used to transform a set of points. If its value is zero (the default), no report is made. However, if it is non-zero, the coordinates of each point are reported (both before and after transformation) by writing them to standard output. This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ When applied to a compound Mapping (CmpMap), only the Report attribute of the CmpMap, and not those of its component Mappings, is used. Coordinate information is never reported for the component Mappings individually, only for the complete CmpMap. } \sstsubsection{ \htmlref{Frame}{Frame} }{ When applied to any Frame, the formatting capabilities of the Frame (as provided by the \htmlref{AST\_FORMAT}{AST\_FORMAT} function) will be used to format the reported coordinates. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ When applied to any FrameSet, the formatting capabilities of the base and current Frames will be used (as above) to individually format the input and output coordinates, as appropriate. The Report attribute of a FrameSet is not itself affected by selecting a new base or current Frame, but the resulting formatting capabilities may be. } } \sstnotes{ \sstitemlist{ \sstitem Unlike most other attributes, the value of the Report attribute is not transferred when a Mapping is copied. Instead, its value is undefined (and therefore defaults to zero) in any copy. Similarly, it becomes undefined in any external representation of a Mapping produced by the \htmlref{AST\_WRITE}{AST\_WRITE} routine. } } } \sstroutine{ ReportLevel }{ Determines which read/write conditions are reported }{ \sstdescription{ This attribute determines which, if any, of the conditions that occur whilst reading or writing an \htmlref{Object}{Object} should be reported. These conditions will generate either a fatal error or a warning, as determined by attribute \htmlref{Strict}{Strict}. ReportLevel can take any of the following values: 0 - Do not report any conditions. 1 - \htmlref{Report}{Report} only conditions where significant information content has been changed. For instance, an unsupported time-scale has been replaced by a supported near-equivalent time-scale. Another example is if a basic \htmlref{Channel}{Channel} unexpected encounters data items that may have been introduced by later versions of AST. 2 - Report the above, and in addition report significant default values. For instance, if no time-scale was specified when reading an Object from an external data source, report the default time-scale that is being used. 3 - Report the above, and in addition report any other potentially interesting conditions that have no significant effect on the conversion. For instance, report if a time-scale of \texttt{"} TT\texttt{"} (terrestrial time) is used in place of \texttt{"} ET\texttt{"} (ephemeris time). This change has no signficiant effect because ET is the predecessor of, and is continuous with, TT. Synonyms such as \texttt{"} IAT\texttt{"} and \texttt{"} TAI\texttt{"} are another example. The default value is 1. Note, there are many other conditions that can occur whilst reading or writing an Object that completely prevent the conversion taking place. Such conditions will always generate errors, irrespective of the ReportLevel and Strict attributes. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All the conditions selected by the FitsChan \htmlref{Warnings}{Warnings} attribute are reported at level 1. } } } \sstroutine{ RestFreq }{ The rest frequency }{ \sstdescription{ This attribute specifies the frequency corresponding to zero velocity. It is used when converting between between velocity-based coordinate systems and and other coordinate systems (such as frequency, wavelength, energy, etc). The default value is 1.0E5 GHz. When setting a new value for this attribute, the new value can be supplied either directly as a frequency, or indirectly as a wavelength or energy, in which case the supplied value is converted to a frequency before being stored. The nature of the supplied value is indicated by appending text to the end of the numerical value indicating the units in which the value is supplied. If the units are not specified, then the supplied value is assumed to be a frequency in units of GHz. If the supplied unit is a unit of frequency, the supplied value is assumed to be a frequency in the given units. If the supplied unit is a unit of length, the supplied value is assumed to be a (vacuum) wavelength. If the supplied unit is a unit of energy, the supplied value is assumed to be an energy. For instance, the following strings all result in a rest frequency of around 1.4E14 Hz being used: \texttt{"} 1.4E5\texttt{"} , \texttt{"} 1.4E14 Hz\texttt{"} , \texttt{"} 1.4E14 s$*$$*$-1\texttt{"} , \texttt{"} 1.4E5 GHz\texttt{"} , \texttt{"} 2.14E-6 m\texttt{"} , \texttt{"} 21400 Angstrom\texttt{"} , \texttt{"} 9.28E-20 J\texttt{"} , \texttt{"} 9.28E-13 erg\texttt{"} , \texttt{"} 0.58 eV\texttt{"} , etc. When getting the value of this attribute, the returned value is always a frequency in units of GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ RootCorner }{ Specifies which edges of the 3D box should be annotated }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining which edges of the cube enclosing the 3D graphics space are used for displaying numerical and descriptive axis labels. The attribute value identifies one of the eight corners of the cube within which graphics are being drawn (i.e. the cube specified by the GRAPHBOX argument when \htmlref{AST\_PLOT3D}{AST\_PLOT3D} was called tp create the \htmlref{Plot3D}{Plot3D}). \htmlref{Axis}{Axis} labels and tick marks will be placed on the three cube edges that meet at the given corner. The attribute value should consist of three character, each of which must be either \texttt{"} U\texttt{"} or \texttt{"} L\texttt{"} . The first character in the string specifies the position of the corner on the first graphics axis. If the character is \texttt{"} U\texttt{"} then the corner is at the upper bound on the first graphics axis. If it is \texttt{"} L\texttt{"} , then the corner is at the lower bound on the first axis. Likewise, the second and third characters in the string specify the location of the corner on the second and third graphics axes. For instance, corner \texttt{"} LLL\texttt{"} is the corner that is at the lower bound on all three graphics axes, and corner \texttt{"} ULU\texttt{"} is at the upper bound on axes 1 and 3 but at the lower bound on axis 2. The default value is \texttt{"} LLL\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot3D }{ All Plot3Ds have this attribute. } } } \sstroutine{ Seed }{ Random number seed for a MathMap }{ \sstdescription{ This attribute, which may take any integer value, determines the sequence of random numbers produced by the random number functions in \htmlref{MathMap}{MathMap} expressions. It is set to an unpredictable default value when a MathMap is created, so that by default each MathMap uses a different set of random numbers. If required, you may set this Seed attribute to a value of your choosing in order to produce repeatable behaviour from the random number functions. You may also enquire the Seed value (e.g. if an initially unpredictable value has been used) and then use it to reproduce the resulting sequence of random numbers, either from the same MathMap or from another one. Clearing the Seed attribute gives it a new unpredictable default value. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } } \sstroutine{ SideBand }{ Indicates which sideband a dual sideband spectrum represents }{ \sstdescription{ This attribute indicates whether the \htmlref{DSBSpecFrame}{DSBSpecFrame} currently represents its lower or upper sideband, or an offset from the local oscillator frequency. When querying the current value, the returned string is always one of \texttt{"} usb\texttt{"} (for upper sideband), \texttt{"} lsb\texttt{"} (for lower sideband), or \texttt{"} lo\texttt{"} (for offset from the local oscillator frequency). When setting a new value, any of the strings \texttt{"} lsb\texttt{"} , \texttt{"} usb\texttt{"} , \texttt{"} observed\texttt{"} , \texttt{"} image\texttt{"} or \texttt{"} lo\texttt{"} may be supplied (case insensitive). The \texttt{"} observed\texttt{"} sideband is which ever sideband (upper or lower) contains the central spectral position given by attribute \htmlref{DSBCentre}{DSBCentre}, and the \texttt{"} image\texttt{"} sideband is the other sideband. It is the sign of the \htmlref{IF}{IF} attribute which determines if the observed sideband is the upper or lower sideband. The default value for SideBand is the observed sideband. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ SimpFI }{ Forward-inverse MathMap pairs simplify? }{ \sstdescription{ This attribute should be set to a non-zero value if applying a \htmlref{MathMap}{MathMap}\texttt{'} s forward transformation, followed immediately by the matching inverse transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}). By default, the SimpFI attribute is zero, so that AST will not perform this simplification unless you have set SimpFI to indicate that it is safe to do so. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient. \sstitem The consent of both MathMaps is required before simplification can take place. If either has a SimpFI value of zero, then simplification will not occur. \sstitem The SimpFI attribute controls simplification only in the case where a MathMap\texttt{'} s forward transformation is followed by the matching inverse transformation. It does not apply if an inverse transformation is followed by a forward transformation. This latter case is controlled by the \htmlref{SimpIF}{SimpIF} attribute. \sstitem The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those defined when the MathMap is created (corresponding to the FWD and INV arguments of its constructor function). If the MathMap is inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. } } } \sstroutine{ SimpIF }{ Inverse-forward MathMap pairs simplify? }{ \sstdescription{ This attribute should be set to a non-zero value if applying a \htmlref{MathMap}{MathMap}\texttt{'} s inverse transformation, followed immediately by the matching forward transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}). By default, the SimpIF attribute is zero, so that AST will not perform this simplification unless you have set SimpIF to indicate that it is safe to do so. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient. \sstitem The consent of both MathMaps is required before simplification can take place. If either has a SimpIF value of zero, then simplification will not occur. \sstitem The SimpIF attribute controls simplification only in the case where a MathMap\texttt{'} s inverse transformation is followed by the matching forward transformation. It does not apply if a forward transformation is followed by an inverse transformation. This latter case is controlled by the \htmlref{SimpFI}{SimpFI} attribute. \sstitem The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those defined when the MathMap is created (corresponding to the FWD and INV arguments of its constructor function). If the MathMap is inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. } } } \sstroutine{ SimpVertices }{ Simplify a Polygon by transforming its vertices? }{ \sstdescription{ This attribute controls the behaviour of the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} method when applied to a \htmlref{Polygon}{Polygon}. The simplified Polygon is created by transforming the vertices from the \htmlref{Frame}{Frame} in which the Polygon was originally defined into the Frame currently represented by the Polygon. If SimpVertices is non-zero (the default) then this simplified Polygon is returned without further checks. If SimpVertices is zero, a check is made that the edges of the new Polygon do not depart significantly from the edges of the original Polygon (as determined by the uncertainty associated with the Polygon). This could occur, for instance, if the \htmlref{Mapping}{Mapping} frrm the original to the current Frame is highly non-linear. If this check fails, the original unsimplified Polygon is returned without change. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Polygon }{ All Polygons have this attribute. } } } \sstroutine{ SinkFile }{ Output file to which to data should be written }{ \sstdescription{ This attribute specifies the name of a file to which the \htmlref{Channel}{Channel} should write data. If specified it is used in preference to any sink function specified when the Channel was created. Assigning a new value to this attribute will cause any previously opened SinkFile to be closed. The first subsequent call to \htmlref{AST\_WRITE}{AST\_WRITE} will attempt to open the new file (an error will be reported if the file cannot be opened), and write data to it. All subsequent call to AST\_WRITE will write data to the new file, until the SinkFile attribute is cleared or changed. Clearing the attribute causes any open SinkFile to be closed. All subsequent data writes will use the sink function specified when the Channel was created, or will write to standard output if no sink function was specified. If no value has been assigned to SinkFile, a null string will be returned if an attempt is made to get the attribute value. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ When the FitsChan is destroyed, any headers in the FitsChan will be written out to the sink file, if one is specified (if not, the sink function used when the FitsChan was created is used). The sink file is a text file (not a FITS file) containing one header per line. } } \sstnotes{ \sstitemlist{ \sstitem A new SinkFile will over-write any existing file with the same name unless the existing file is write protected, in which case an error will be reported. \sstitem Any open SinkFile is closed when the Channel is deleted. \sstitem If the Channel is copied or dumped (using \htmlref{AST\_COPY}{AST\_COPY} or \htmlref{AST\_SHOW}{AST\_SHOW}) the SinkFile attribute is left in a cleared state in the output Channel (i.e. the value of the SinkFile attribute is not copied). } } } \sstroutine{ Size(element) }{ Character size for a Plot element }{ \sstdescription{ This attribute determines the character size used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Size(title)=2.0\texttt{"} causes the Plot title to be drawn using twice the default character size. The range of character sizes available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default character size supplied by this graphics system. } \sstattributetype{ Floating Point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Size\texttt{"} instead of \texttt{"} Size(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Size(TextLab) value. } } } \sstroutine{ SizeGuess }{ The expected size of the KeyMap }{ \sstdescription{ This is attribute gives an estimate of the number of entries that will be stored in the \htmlref{KeyMap}{KeyMap}. It is used to tune the internal properties of the KeyMap for speed and efficiency. A larger value will result in faster access at the expense of increased memory requirements. However if the SizeGuess value is much larger than the actual size of the KeyMap, then there will be little, if any, speed gained by making the SizeGuess even larger. The default value is 300. The value of this attribute can only be changed if the KeyMap is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to set or clear the attribute when the KeyMap contains any entries. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } } \sstroutine{ Skip }{ Skip irrelevant data? }{ \sstdescription{ This is a boolean attribute which indicates whether the \htmlref{Object}{Object} data being read through a \htmlref{Channel}{Channel} are inter-mixed with other, irrelevant, external data. If Skip is zero (the default), then the source of input data is expected to contain descriptions of AST Objects and comments and nothing else (if anything else is read, an error will result). If Skip is non-zero, then any non-Object data encountered between Objects will be ignored and simply skipped over in order to reach the next Object. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The FitsChan class sets the default value of this attribute to 1, so that all irrelevant FITS headers will normally be ignored. } } } \sstroutine{ SkyRef(axis) }{ Position defining the offset coordinate system }{ \sstdescription{ This attribute allows a \htmlref{SkyFrame}{SkyFrame} to represent offsets, rather than absolute axis values, within the coordinate system specified by the \htmlref{System}{System} attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the \htmlref{SkyRefIs}{SkyRefIs} attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute. If an integer axis index is included in the attribute name (e.g. \texttt{"} SkyRef(1)\texttt{"} ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). If no axis index is included in the attribute name (e.g. \texttt{"} SkyRef\texttt{"} ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute. The default values for SkyRef are zero longitude and zero latitude. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System. \sstitem If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending \texttt{"} offset\texttt{"} to the end, the default axis Symbols for the SkyFrame are modified by prepending the character \texttt{"} D\texttt{"} to the start, and the default title is modified by replacing the projection information by the origin information. } } \sstdiytopic{ Aligning SkyFrames with Offset Coordinate Systems }{ The offset coordinate system within a SkyFrame should normally be considered as a superficial \texttt{"} re-badging\texttt{"} of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical \texttt{"} label\texttt{"} for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may \texttt{"} drift\texttt{"} with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the \htmlref{AST\_CONVERT}{AST\_CONVERT} or \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the \htmlref{AlignSystem}{AlignSystem} attribute. However, by setting the \htmlref{AlignOffset}{AlignOffset} attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames. } } \sstroutine{ SkyRefIs }{ Selects the nature of the offset coordinate system }{ \sstdescription{ This attribute controls how the values supplied for the SkyRef and SkyRefP attributes are used. These three attributes together allow a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin or pole within the coordinate system specified by the \htmlref{System}{System} attribute, rather than absolute axis values. SkyRefIs can take one of the case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"} or \texttt{"} Ignored\texttt{"} . If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system represented by the SkyFrame is modified to put the origin of longitude and latitude at the position specified by the SkyRef attribute. If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented by the SkyFrame is modified to put the north pole at the position specified by the SkyRef attribute. If SkyRefIs is set to \texttt{"} Ignored\texttt{"} (the default), then any value set for the SkyRef attribute is ignored, and the SkyFrame represents the coordinate system specified by the System attribute directly without any rotation. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ SkyRefP(axis) }{ Position on primary meridian of offset coordinate system }{ \sstdescription{ This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the \htmlref{System}{System} attribute. The offset coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of $+$90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute). If an integer axis index is included in the attribute name (e.g. \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude). \sstitem An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation. \sstitem If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System. } } } \sstroutine{ SkyTol }{ The smallest significant shift in sky coordinates }{ \sstdescription{ This attribute indicates the accuracy of the axis values that will be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two positions within the SkyFrame is smaller than the value of SkyTol, then the two positions will (for the puposes indicated below) be considered to be co-incident. This value is used only when constructing the \htmlref{Mapping}{Mapping} between two different SkyFrames (for instance, when calling \htmlref{AST\_CONVERT}{AST\_CONVERT} or \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}). If the transformation between the two SkyFrames causes positions to shift by less than SkyTol arc-seconds, then the transformation is replaced by a \htmlref{UnitMap}{UnitMap}. This could in certain circumatances allow major simplifications to be made to the transformation between any pixel grids associated with the two SkyFrames (for instance, if each SkyFrame is part of the WCS \htmlref{FrameSet}{FrameSet} associated with an image). A common case is when two SkyFrames use the FK5 system, but have slightly different \htmlref{Epoch}{Epoch} values. If the \htmlref{AlignSystem}{AlignSystem} attribute has its default value of \texttt{"} ICRS\texttt{"} , then the transformation between the two SkyFrames will include a very small rotation (FK5 rotates with respect to ICRS as a rate of about 0.0005 arc-seconds per year). In most circumstances such a small rotation is insignificant. Setting SkyTol to some suitably small non-zero value will cause this rotation to be ignored, allowing much simpler transformations to be used. The test to determine the shift introduced by transforming between the two SkyFrames is performed by transforming a set of 14 position spread evenly over the whole sky. The largest shift produced at any of these 14 positions is compared to the value of SkyTol. The SkyTol value is in units of arc-seconds, and the default value is 0.001. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ SortBy }{ Determines how keys are sorted in a KeyMap }{ \sstdescription{ This attribute determines the order in which keys are returned by the \htmlref{AST\_MAPKEY}{AST\_MAPKEY} function. It may take the following values (the default is \texttt{"} None\texttt{"} ): \sstitemlist{ \sstitem \texttt{"} None\texttt{"} : The keys are returned in an arbitrary order. This is the fastest method as it avoids the need for a sorted list of keys to be maintained and used. \sstitem \texttt{"} AgeDown\texttt{"} : The keys are returned in the order in which values were stored in the \htmlref{KeyMap}{KeyMap}, with the key for the most recent value being returned last. If the value of an existing entry is changed, it goes to the end of the list. \sstitem \texttt{"} AgeUp\texttt{"} : The keys are returned in the order in which values were stored in the KeyMap, with the key for the most recent value being returned first. If the value of an existing entry is changed, it goes to the top of the list. \sstitem \texttt{"} KeyAgeDown\texttt{"} : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned last. If the value of an existing entry is changed, its position in the list does not change. \sstitem \texttt{"} KeyAgeUp\texttt{"} : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned first. If the value of an existing entry is changed, its position in the list does not change. \sstitem \texttt{"} KeyDown\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} being returned last. \sstitem \texttt{"} KeyUp\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} being returned first. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If a new value is assigned to SortBy (or if SortBy is cleared), all entries currently in the KeyMap are re-sorted according to the new SortBy value. } } } \sstroutine{ SourceFile }{ Input file from which to read data }{ \sstdescription{ This attribute specifies the name of a file from which the \htmlref{Channel}{Channel} should read data. If specified it is used in preference to any source function specified when the Channel was created. Assigning a new value to this attribute will cause any previously opened SourceFile to be closed. The first subsequent call to \htmlref{AST\_READ}{AST\_READ} will attempt to open the new file (an error will be reported if the file cannot be opened), and read data from it. All subsequent call to AST\_READ will read data from the new file, until the SourceFile attribute is cleared or changed. Clearing the attribute causes any open SourceFile to be closed. All subsequent data reads will use the source function specified when the Channel was created, or will read from standard input if no source function was specified. If no value has been assigned to SourceFile, a null string will be returned if an attempt is made to get the attribute value. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ In the case of a FitsChan, the specified SourceFile supplements the source function specified when the FitsChan was created, rather than replacing the source function. The source file should be a text file (not a FITS file) containing one header per line. When a value is assigned to SourceFile, the file is opened and read immediately, and all headers read from the file are appended to the end of any header already in the FitsChan. The file is then closed. Clearing the SourceFile attribute has no further effect, other than nullifying the string (i.e. the file name) associated with the attribute. } } \sstnotes{ \sstitemlist{ \sstitem Any open SourceFile is closed when the Channel is deleted. \sstitem If the Channel is copied or dumped (using \htmlref{AST\_COPY}{AST\_COPY} or \htmlref{AST\_SHOW}{AST\_SHOW}) the SourceFile attribute is left in a cleared state in the output Channel (i.e. the value of the SourceFile attribute is not copied). } } } \sstroutine{ SourceSys }{ Spectral system in which the source velocity is stored }{ \sstdescription{ This attribute identifies the spectral system in which the \htmlref{SourceVel}{SourceVel} attribute value (the source velocity) is supplied and returned. It can be one of the following: \sstitemlist{ \sstitem \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) \sstitem \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) \sstitem \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) \sstitem \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) \sstitem \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) } When setting a new value for the SourceVel attribute, the source velocity should be supplied in the spectral system indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity will be returned in this spectral system. If the value of SourceSys is changed, the value stored for SourceVel will be converted from the old to the new spectral systems. The default value is \texttt{"} VELO\texttt{"} (apparent radial velocity). } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ SourceVRF }{ Rest frame in which the source velocity is stored }{ \sstdescription{ This attribute identifies the rest frame in which the source velocity or redshift is stored (the source velocity or redshift is accessed using attribute \htmlref{SourceVel}{SourceVel}). When setting a new value for the SourceVel attribute, the source velocity or redshift should be supplied in the rest frame indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity or redshift will be returned in this rest frame. If the value of SourceVRF is changed, the value stored for SourceVel will be converted from the old to the new rest frame. The values which can be supplied are the same as for the \htmlref{StdOfRest}{StdOfRest} attribute (except that SourceVRF cannot be set to \texttt{"} Source\texttt{"} ). The default value is \texttt{"} Helio\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ SourceVel }{ The source velocity }{ \sstdescription{ This attribute (together with \htmlref{SourceSys}{SourceSys}, \htmlref{SourceVRF}{SourceVRF}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) defines the \texttt{"} Source\texttt{"} standard of rest (see attribute \htmlref{StdOfRest}{StdOfRest}). This is a rest frame which is moving towards the position given by RefRA and RefDec at a velocity given by SourceVel. A positive value means the source is moving away from the observer. When a new value is assigned to this attribute, the supplied value is assumed to refer to the spectral system specified by the SourceSys attribute. For instance, the SourceVel value may be supplied as a radio velocity, a redshift, a beta factor, etc. Similarly, when the current value of the SourceVel attribute is obtained, the returned value will refer to the spectral system specified by the SourceSys value. If the SourceSys value is changed, any value previously stored for the SourceVel attribute will be changed automatically from the old spectral system to the new spectral system. When setting a value for SourceVel, the value should be supplied in the rest frame specified by the SourceVRF attribute. Likewise, when getting the value of SourceVel, it will be returned in the rest frame specified by the SourceVRF attribute. The default SourceVel value is zero. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem It is important to set an appropriate value for SourceVRF and SourceSys before setting a value for SourceVel. If a new value is later set for SourceVRF or SourceSys, the value stored for SourceVel will simultaneously be changed to the new standard of rest or spectral system. } } } \sstroutine{ SpecOrigin }{ The zero point for SpecFrame axis values }{ \sstdescription{ This specifies the origin from which all spectral values are measured. The default value (zero) results in the \htmlref{SpecFrame}{SpecFrame} describing absolute spectral values in the system given by the \htmlref{System}{System} attribute (e.g. frequency, velocity, etc). If a SpecFrame is to be used to describe offset from some origin, the SpecOrigin attribute should be set to hold the required origin value. The SpecOrigin value stored inside the SpecFrame structure is modified whenever SpecFrame attribute values are changed so that it refers to the original spectral position. When setting a new value for this attribute, the supplied value is assumed to be in the system, units and standard of rest described by the SpecFrame. Likewise, when getting the value of this attribute, the value is returned in the system, units and standard of rest described by the SpecFrame. If any of these attributes are changed, then any previously stored SpecOrigin value will also be changed so that refers to the new system, units or standard of rest. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ SpecVal }{ The spectral position at which flux values are measured }{ \sstdescription{ This attribute specifies the spectral position (frequency, wavelength, etc.), at which the values described by the \htmlref{FluxFrame}{FluxFrame} are measured. It is used when determining the \htmlref{Mapping}{Mapping} between between FluxFrames. The default value and spectral system used for this attribute are both specified when the FluxFrame is created. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ FluxFrame }{ All FluxFrames have this attribute. } } } \sstroutine{ StcsArea }{ Return the CoordinateArea component when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{AST\_READ}{AST\_READ} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsArea is set non-zero (the default), then a \htmlref{Region}{Region} representing the STC CoordinateArea will be returned by AST\_READ. If StcsArea is set to zero, then the STC CoordinateArea will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} can be used to specify other Objects to be returned by AST\_READ. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by AST\_READ will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this case, the Region representing the STC CoordinateArea will be stored in the returned KeyMap using the key \texttt{"} AREA\texttt{"} . If StcsArea is the only attribute to be set non-zero, then the Object returned by AST\_READ will be the CoordinateArea Region itself. \sstitem The class of Region used to represent the CoordinateArea for each STC-S sub-phrase is determined by the first word in the sub-phrase (the \texttt{"} sub-phrase identifier\texttt{"} ). The individual sub-phrase Regions are combined into a single \htmlref{Prism}{Prism}, which is then simplified using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} to form the returned region. \sstitem Sub-phrases that represent a single value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} or \texttt{"} Redshift\texttt{"} ) are considered to be be part of the STC CoordinateArea component. \sstitem The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times. \sstitem The \htmlref{Epoch}{Epoch} attribute for the returned Region is set in the same way as the TimeOrigin attribute (see above). } } } \sstroutine{ StcsCoords }{ Return the Coordinates component when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{AST\_READ}{AST\_READ} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsCoords is set non-zero, then a \htmlref{PointList}{PointList} representing the STC Coordinates will be returned by AST\_READ. If StcsCoords is set to zero (the default), then the STC Coordinates will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsArea}{StcsArea} and \htmlref{StcsProps}{StcsProps} can be used to specify other Objects to be returned by AST\_READ. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by AST\_READ will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this case, the PointList representing the STC Coordinates will be stored in the returned KeyMap using the key \texttt{"} COORDS\texttt{"} . If StcsCoords is the only attribute to be set non-zero, then the Object returned by AST\_READ will be the Coordinates PointList itself. \sstitem The Coordinates component is specified by the additional axis values embedded within the body of each STC-S sub-phrase that represents an extended area. Sub-phrases that represent a single value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} or \texttt{"} Redshift\texttt{"} ) are not considered to be be part of the STC Coordinates component. \sstitem If the STC-S documents does not contain a Coordinates component, then a NULL object pointer (AST\_\_NULL) will be returned by AST\_READ if the Coordinates component is the only object being returned. If other objects are also being returned (see attributes StcsProps and StcsArea), then the returned KeyMap will contain a \texttt{"} COORDS\texttt{"} key only if the Coordinates component is read succesfully. \sstitem The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times. \sstitem The \htmlref{Epoch}{Epoch} attribute for the returned \htmlref{Region}{Region} is set in the same way as the TimeOrigin attribute (see above). } } } \sstroutine{ StcsLength }{ Controls output line length }{ \sstdescription{ This attribute specifies the maximum length to use when writing out text through the sink function supplied when the \htmlref{StcsChan}{StcsChan} was created. It is ignored if the \htmlref{Indent}{Indent} attribute is zero (in which case the text supplied to the sink function can be of any length). The default value is 70. The number of characters in each string written out through the sink function will not usually be greater than the value of this attribute (but may be less). However, if any single word in the STC-S description exceeds the specified length, then the word will be written out as a single line. Note, the default value of zero is unlikely to be appropriate when an StcsChan is used within Fortran code. In this case, StcsLength should usually be set to the size of the CHARACTER variable used to receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function. In addition, the Indent attribute should be set non-zero. This avoids the possibility of long lines being truncated invisibly within AST\_GETLINE. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } } \sstroutine{ StcsProps }{ Return all properties when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{AST\_READ}{AST\_READ} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsProps is set non-zero, then a \htmlref{KeyMap}{KeyMap} containing all the properties read from the STC-S document will be returned by AST\_READ. If StcsProps is set to zero (the default), then the properties will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsArea}{StcsArea} can be used to specify other Objects to be returned by AST\_READ. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by AST\_READ will be a KeyMap containing the requested Objects. In this case, the properties KeyMap will be stored in the returned KeyMap using the key \texttt{"} PROPS\texttt{"} . If StcsProps is the only attribute to be set non-zero, then the Object returned by AST\_READ will be the properties KeyMap itself. \sstitem The KeyMap containing the properties will have entries for one or more of the following keys: \texttt{"} TIME\_PROPS\texttt{"} , \texttt{"} SPACE\_PROPS\texttt{"} , \texttt{"} SPECTRAL\_PROPS\texttt{"} and \texttt{"} REDSHIFT\_PROPS\texttt{"} . Each of these entries will be another KeyMap containing the properties of the corresponding STC-S sub-phrase. } } } \sstroutine{ StdOfRest }{ Standard of rest }{ \sstdescription{ This attribute identifies the standard of rest to which the spectral axis values of a \htmlref{SpecFrame}{SpecFrame} refer, and may take any of the values listed in the \texttt{"} Standards of Rest\texttt{"} section (below). The default StdOfRest value is \texttt{"} Helio\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } \sstdiytopic{ Standards of Rest }{ The SpecFrame class supports the following StdOfRest values (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} Topocentric\texttt{"} , \texttt{"} Topocent\texttt{"} or \texttt{"} Topo\texttt{"} : The observers rest-frame (assumed to be on the surface of the earth). Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a day because of the rotation of the observer around the axis of the earth. This standard of rest must be qualified using the \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes. \sstitem \texttt{"} Geocentric\texttt{"} , \texttt{"} Geocentr\texttt{"} or \texttt{"} Geo\texttt{"} : The rest-frame of the earth centre. Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a year because of the rotation of the earth around the Sun. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes. \sstitem \texttt{"} Barycentric\texttt{"} , \texttt{"} Barycent\texttt{"} or \texttt{"} Bary\texttt{"} : The rest-frame of the solar-system barycentre. Spectra recorded in this standard of rest suffer a Doppler shift which depends both on the velocity of the Sun through the Local Standard of Rest, and on the movement of the planets through the solar system. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes. \sstitem \texttt{"} Heliocentric\texttt{"} , \texttt{"} Heliocen\texttt{"} or \texttt{"} Helio\texttt{"} : The rest-frame of the Sun. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the Sun through the Local Standard of Rest. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} LSRK\texttt{"} , \texttt{"} LSR\texttt{"} : The rest-frame of the kinematical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the kinematical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} LSRD\texttt{"} : The rest-frame of the dynamical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the dynamical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Galactic\texttt{"} , \texttt{"} Galactoc\texttt{"} or \texttt{"} Gal\texttt{"} : The rest-frame of the galactic centre. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the galactic centre through the local group. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Local\_group\texttt{"} , \texttt{"} Localgrp\texttt{"} or \texttt{"} LG\texttt{"} : The rest-frame of the local group. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Source\texttt{"} , or \texttt{"} src\texttt{"} : The rest-frame of the source. This standard of rest must be qualified using the RefRA, RefDec and \htmlref{SourceVel}{SourceVel} attributes. } Where more than one alternative \htmlref{System}{System} value is shown above, the first of these will be returned when an enquiry is made. } } \sstroutine{ Strict }{ Report an error if any unexpeted data items are found? }{ \sstdescription{ This is a boolean attribute which indicates whether a warning rather than an error should be issed for insignificant conversion problems. If it is set non-zero, then fatal errors are issued instead of warnings, resulting in the inherited STATUS variable being set to an error value. If Strict is zero (the default), then execution continues after minor conversion problems, and a warning message is added to the \htmlref{Channel}{Channel} structure. Such messages can be retrieved using the \htmlref{AST\_WARNINGS}{AST\_WARNINGS} function. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem This attribute was introduced in AST version 5.0. Prior to this version of AST unexpected data items read by a basic Channel always caused an error to be reported. So applications linked against versions of AST prior to version 5.0 may not be able to read \htmlref{Object}{Object} descriptions created by later versions of AST, if the Object\texttt{'} s class description has changed. } } } \sstroutine{ Style(element) }{ Line style for a Plot element }{ \sstdescription{ This attribute determines the line style used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Style(border)=2\texttt{"} causes the Plot border to be drawn using line style 2 (which might result in, say, a dashed line). The range of integer line styles available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line style supplied by this graphics system (normally, this is likely to give a solid line). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Style\texttt{"} instead of \texttt{"} Style(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Style(\htmlref{Border}{Border}) value. } } } \sstroutine{ Symbol(axis) }{ Axis symbol }{ \sstdescription{ This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a \htmlref{Frame}{Frame}. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include \texttt{"} RA\texttt{"} and \texttt{"} Dec\texttt{"} (for Right Ascension and Declination). If a Symbol value has not been set for a Frame axis, then a suitable default is supplied. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default Symbol value supplied by the Frame class is the string \texttt{"} $<$\htmlref{Domain}{Domain}$>$$<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for successive axes, and $<$Domain$>$ is the value of the Frame\texttt{'} s Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, \texttt{"} x\texttt{"} is used as the $<$Domain$>$ value in constructing this default string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Symbol value (e.g. to \texttt{"} RA\texttt{"} or \texttt{"} Dec\texttt{"} ) as appropriate for the particular celestial coordinate system being represented. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ System }{ Coordinate system used to describe positions within the domain }{ \sstdescription{ In general it is possible for positions within a given physical domain to be described using one of several different coordinate systems. For instance, the \htmlref{SkyFrame}{SkyFrame} class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the \htmlref{SpecFrame}{SpecFrame} class can use frequency, wavelength, velocity, etc, to describe a position within an electromagnetic spectrum. The System attribute identifies the particular coordinate system represented by a \htmlref{Frame}{Frame}. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System value is shown, the first of will be returned when an enquiry is made. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The System attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The System attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , and may not be altered. In addition, the CmpFrame class allows the System attribute to be referenced for a component Frame by including the index of an axis within the required component Frame. For instance, \texttt{"} System(3)\texttt{"} refers to the System attribute of the component Frame which includes axis 3 of the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The System attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ SkyFrame }{ The SkyFrame class supports the following System values and associated celestial coordinate systems: \sstitemlist{ \sstitem \texttt{"} AZEL\texttt{"} : Horizon coordinates. The longitude axis is azimuth such that geographic north has an azimuth of zero and geographic east has an azimuth of $+$PI/2 radians. The zenith has elevation $+$PI/2. When converting to and from other celestial coordinate systems, no corrections are applied for atmospheric refraction or polar motion (however, a correction for diurnal aberattion is applied). Note, unlike most other celestial coordinate systems, this system is right handed. Also, unlike other SkyFrame systems, the AzEl system is sensitive to the timescale in which the \htmlref{Epoch}{Epoch} value is supplied. This is because of the gross diurnal rotation which this system undergoes, causing a small change in time to translate to a large rotation. When converting to or from an AzEl system, the Epoch value for both source and destination SkyFrames should be supplied in the TDB timescale. The difference between TDB and TT is between 1 and 2 milliseconds, and so a TT value can usually be supplied in place of a TDB value. The TT timescale is related to TAI via TT = TAI $+$ 32.184 seconds. \sstitem \texttt{"} ECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying \htmlref{Equinox}{Equinox} value. \sstitem \texttt{"} FK4\texttt{"} : The old FK4 (barycentric) equatorial coordinate system, which should be qualified by an Equinox value. The underlying model on which this is based is non-inertial and rotates slowly with time, so for accurate work FK4 coordinate systems should also be qualified by an Epoch value. \sstitem \texttt{"} FK4-NO-E\texttt{"} or \texttt{"} FK4\_NO\_E\texttt{"} : The old FK4 (barycentric) equatorial system but without the \texttt{"} E-terms of aberration\texttt{"} (e.g. some radio catalogues). This coordinate system should also be qualified by both an Equinox and an Epoch value. \sstitem \texttt{"} FK5\texttt{"} or \texttt{"} EQUATORIAL\texttt{"} : The modern FK5 (barycentric) equatorial coordinate system. This should be qualified by an Equinox value. \sstitem \texttt{"} GALACTIC\texttt{"} : Galactic coordinates (IAU 1958). \sstitem \texttt{"} GAPPT\texttt{"} , \texttt{"} GEOCENTRIC\texttt{"} or \texttt{"} APPARENT\texttt{"} : The geocentric apparent equatorial coordinate system, which gives the apparent positions of sources relative to the true plane of the Earth\texttt{'} s equator and the equinox (the coordinate origin) at a time specified by the qualifying Epoch value. (Note that no Equinox is needed to qualify this coordinate system because no model \texttt{"} mean equinox\texttt{"} is involved.) These coordinates give the apparent right ascension and declination of a source for a specified date of observation, and therefore form an approximate basis for pointing a telescope. Note, however, that they are applicable to a fictitious observer at the Earth\texttt{'} s centre, and therefore ignore such effects as atmospheric refraction and the (normally much smaller) aberration of light due to the rotational velocity of the Earth\texttt{'} s surface. Geocentric apparent coordinates are derived from the standard FK5 (J2000.0) barycentric coordinates by taking account of the gravitational deflection of light by the Sun (usually small), the aberration of light caused by the motion of the Earth\texttt{'} s centre with respect to the barycentre (larger), and the precession and nutation of the Earth\texttt{'} s spin axis (normally larger still). \sstitem \texttt{"} HELIOECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox of J2000.0, in which an offset is added to the longitude value which results in the centre of the sun being at zero longitude at the date given by the Epoch attribute. Attempts to set a value for the Equinox attribute will be ignored, since this system is always referred to J2000.0. \sstitem \texttt{"} ICRS\texttt{"} : The Internation Celestial Reference System, realised through the Hipparcos catalogue. Whilst not an equatorial system by definition, the ICRS is very close to the FK5 (J2000) system and is usually treated as an equatorial system. The distinction between ICRS and FK5 (J2000) only becomes important when accuracies of 50 milli-arcseconds or better are required. ICRS need not be qualified by an Equinox value. \sstitem \texttt{"} J2000\texttt{"} : An equatorial coordinate system based on the mean dynamical equator and equinox of the J2000 epoch. The dynamical equator and equinox differ slightly from those used by the FK5 model, and so a \texttt{"} J2000\texttt{"} SkyFrame will differ slightly from an \texttt{"} FK5(Equinox=J2000)\texttt{"} SkyFrame. The J2000 System need not be qualified by an Equinox value \sstitem \texttt{"} SUPERGALACTIC\texttt{"} : De Vaucouleurs Supergalactic coordinates. \sstitem \texttt{"} UNKNOWN\texttt{"} : Any other general spherical coordinate system. No \htmlref{Mapping}{Mapping} can be created between a pair of SkyFrames if either of the SkyFrames has System set to \texttt{"} Unknown\texttt{"} . } Currently, the default System value is \texttt{"} ICRS\texttt{"} . However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in future). If you intend to use the ICRS system indefinitely, then you should specify it explicitly. } \sstsubsection{ SpecFrame }{ The SpecFrame class supports the following System values and associated spectral coordinate systems (the default is \texttt{"} WAVE\texttt{"} - wavelength). They are all defined in FITS-WCS paper III: \sstitemlist{ \sstitem \texttt{"} FREQ\texttt{"} : Frequency (GHz) \sstitem \texttt{"} ENER\texttt{"} or \texttt{"} ENERGY\texttt{"} : Energy (J) \sstitem \texttt{"} WAVN\texttt{"} or \texttt{"} WAVENUM\texttt{"} : Wave-number (1/m) \sstitem \texttt{"} WAVE\texttt{"} or \texttt{"} WAVELEN\texttt{"} : Vacuum wave-length (Angstrom) \sstitem \texttt{"} AWAV\texttt{"} or \texttt{"} AIRWAVE\texttt{"} : Wave-length in air (Angstrom) \sstitem \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) \sstitem \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) \sstitem \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) \sstitem \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) \sstitem \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) } The default value for the Unit attribute for each system is shown in parentheses. Note that the default value for the ActiveUnit flag is .TRUE. for a SpecFrame, meaning that changes to the Unit attribute for a SpecFrame will result in the SpecFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine for further information). } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class supports the following System values and associated coordinate systems (the default is \texttt{"} MJD\texttt{"} ): \sstitemlist{ \sstitem \texttt{"} MJD\texttt{"} : Modified Julian Date (d) \sstitem \texttt{"} JD\texttt{"} : Julian Date (d) \sstitem \texttt{"} JEPOCH\texttt{"} : Julian epoch (yr) \sstitem \texttt{"} BEPOCH\texttt{"} : Besselian (yr) } The default value for the Unit attribute for each system is shown in parentheses. Strictly, these systems should not allow changes to be made to the units. For instance, the usual definition of \texttt{"} MJD\texttt{"} and \texttt{"} JD\texttt{"} include the statement that the values will be in units of days. However, AST does allow the use of other units with all the above supported systems (except BEPOCH), on the understanding that conversion to the \texttt{"} correct\texttt{"} units involves nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined in terms of tropical years of 365.2422 days, rather than the usual Julian year of 365.25 days. Therefore, to avoid any confusion, the Unit attribute is automatically cleared to \texttt{"} yr\texttt{"} when a System value of BEPOCH System is selected, and an error is reported if any attempt is subsequently made to change the Unit attribute. Note that the default value for the ActiveUnit flag is .TRUE. for a TimeFrame, meaning that changes to the Unit attribute for a TimeFrame will result in the TimeFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see AST\_SETACTIVEUNIT routine for further information). } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The FluxFrame class supports the following System values and associated systems for measuring observed value: \sstitemlist{ \sstitem \texttt{"} FLXDN\texttt{"} : Flux per unit frequency (W/m$\wedge$2/Hz) \sstitem \texttt{"} FLXDNW\texttt{"} : Flux per unit wavelength (W/m$\wedge$2/Angstrom) \sstitem \texttt{"} SFCBR\texttt{"} : Surface brightness in frequency units (W/m$\wedge$2/Hz/arcmin$*$$*$2) \sstitem \texttt{"} SFCBRW\texttt{"} : Surface brightness in wavelength units (W/m$\wedge$2/Angstrom/arcmin$*$$*$2) } The above lists specified the default units for each System. If an explicit value is set for the Unit attribute but no value is set for System, then the default System value is determined by the Unit string (if the units are not appropriate for describing any of the supported Systems then an error will be reported when an attempt is made to access the System value). If no value has been specified for either Unit or System, then System=FLXDN and Unit=W/m$\wedge$2/Hz are used. } } } \sstroutine{ TabOK }{ Should the FITS-WCS -TAB algorithm be recognised? }{ \sstdescription{ This attribute is an integer value which indicates if the \texttt{"} -TAB\texttt{"} algorithm, defined in FITS-WCS paper III, should be supported by the \htmlref{FitsChan}{FitsChan}. The default value is zero. A zero or negative value results in no support for -TAB axes (i.e. axes that have \texttt{"} -TAB\texttt{"} in their CTYPE keyword value). In this case, the \htmlref{AST\_WRITE}{AST\_WRITE} method will return zero if the write operation would required the use of the -TAB algorithm, and the \htmlref{AST\_READ}{AST\_READ} method will return AST\_\_NULL if any axis in the supplied header uses the -TAB algorithm. If TabOK is set to a non-zero positive integer, these methods will recognise and convert axes described by the -TAB algorithm, as follows: The AST\_WRITE method will generate headers that use the -TAB algorithm (if possible) if no other known FITS-WCS algorithm can be used to describe the supplied \htmlref{FrameSet}{FrameSet}. This will result in a table of coordinate values and index vectors being stored in the FitsChan. After the write operation, the calling application should check to see if such a table has been stored in the FitsChan. If so, the table should be retrived from the FitsChan using the \htmlref{AST\_GETTABLES}{AST\_GETTABLES} method, and the data (and headers) within it copied into a new FITS binary table extension. See AST\_GETTABLES for more information. The FitsChan uses a \htmlref{FitsTable}{FitsTable} object to store the table data and headers. This FitsTable will contain the required columns and headers as described by FITS-WCS paper III - the coordinates array will be in a column named \texttt{"} COORDS\texttt{"} , and the index vector(s) will be in columns named \texttt{"} INDEX$<$i$>$\texttt{"} (where $<$i$>$ is the index of the corresponding FITS WCS axis). Note, index vectors are only created if required. The EXTNAME value will be set to the value of the AST\_\_TABEXTNAME constant (currently \texttt{"} WCS-TAB\texttt{"} ). The EXTVER header will be set to the positive integer value assigned to the TabOK attribute. No value will be stored for the EXTLEVEL header, and should therefore be considered to default to 1. The AST\_READ method will generate a FrameSet from headers that use the -TAB algorithm so long as the necessary FITS binary tables are made available. There are two ways to do this: firstly, if the application knows which FITS binary tables will be needed, then it can create a Fitstable describing each such table and store it in the FitsChan (using method \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES} or \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}) before invoking the AST\_READ method. Secondly, if the application does not know which FITS binary tables will be needed by AST\_READ, then it can register a call-back function with the FitsChan using method \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE}. This call-back function will be called from within AST\_READ if and when a -TAB header is encountered. When called, its arguments will give the name, version and level of the FITS extension containing a required table. The call-back function should read this table from an external FITS file, and create a corresponding FitsTable which it should then return to AST\_READ. Note, currently AST\_READ can only handle -TAB headers that describe 1-dimensional (i.e. separable) axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ TextLab(axis) }{ Draw descriptive axis labels for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether textual labels should be drawn to describe the quantity being represented on each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} TextLab(2)=1\texttt{"} specifies that descriptive labels should be drawn for the second axis. If the TextLab value of a Plot axis is non-zero, then descriptive labels will be drawn for that axis, otherwise they will be omitted. The default behaviour is to draw descriptive labels if tick marks and numerical labels are being drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit them otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the descriptive labels is derived from the Plot\texttt{'} s \htmlref{Label(axis)}{Label(axis)} attribute, together with its \htmlref{Unit(axis)}{Unit(axis)} attribute if appropriate (see the \htmlref{LabelUnits(axis)}{LabelUnits(axis)} attribute). \sstitem The drawing of numerical axis labels for a Plot (which indicate values on the axis) is controlled by the \htmlref{NumLab(axis)}{NumLab(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} TextLab\texttt{"} instead of \texttt{"} TextLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the TextLab(1) value. } } } \sstroutine{ TextLabGap(axis) }{ Spacing of descriptive axis labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining where descriptive axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} TextLabGap(2)=0.01\texttt{"} specifies where the descriptive label for the second axis should be drawn. For each axis, the TextLabGap value gives the spacing between the descriptive label and the edge of a box enclosing all other parts of the annotated grid (excluding other descriptive labels). The gap is measured to the nearest edge of the label (i.e. the top or the bottom). Positive values cause the descriptive label to be placed outside the bounding box, while negative values cause it to be placed inside. The TextLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.01. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If drawn, descriptive labels are always placed at the edges of the plotting area, even although the corresponding numerical labels may be drawn along axis lines in the interior of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). \sstitem If no axis is specified, (e.g. \texttt{"} TextLabGap\texttt{"} instead of \texttt{"} TextLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the TextLabGap(1) value. } } } \sstroutine{ TickAll }{ Draw tick marks on all edges of a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining whether tick marks should be drawn on all edges of a \htmlref{Plot}{Plot}. If the TickAll value of a Plot is non-zero (the default), then tick marks will be drawn on all edges of the Plot. Otherwise, they will be drawn only on those edges where the numerical and descriptive axis labels are drawn (see the \htmlref{Edge(axis)}{Edge(axis)} attribute). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels and tick marks are drawn along grid lines inside the plotting area, rather than around its edges (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the TickAll attribute is ignored. } } } \sstroutine{ TimeOrigin }{ The zero point for TimeFrame axis values }{ \sstdescription{ This specifies the origin from which all time values are measured. The default value (zero) results in the \htmlref{TimeFrame}{TimeFrame} describing absolute time values in the system given by the \htmlref{System}{System} attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } \sstdiytopic{ Input Formats }{ The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters: \sstitemlist{ \sstitem Besselian \htmlref{Epoch}{Epoch}: Expressed in decimal years, with or without decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). \sstitem Julian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). \sstitem Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame\texttt{'} s System attribute, in the units given by the TimeFrame\texttt{'} s Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value (\texttt{"} 123.4 d\texttt{"} for example), in which case the supplied value is scaled into the units specified by the Unit attribute. \sstitem Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for example). \sstitem Modified Julian Date: With or without decimal places (\texttt{"} MJD 54321.4\texttt{"} for example). \sstitem Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours). \sstitem Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). } } \sstdiytopic{ Output Format }{ When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame\texttt{'} s System, in the unit specified by the TimeFrame\texttt{'} s Unit attribute. } } \sstroutine{ TimeScale }{ Time scale }{ \sstdescription{ This attribute identifies the time scale to which the time axis values of a \htmlref{TimeFrame}{TimeFrame} refer, and may take any of the values listed in the \texttt{"} Time Scales\texttt{"} section (below). The default TimeScale value depends on the current \htmlref{System}{System} value; if the current TimeFrame system is \texttt{"} Besselian epoch\texttt{"} the default is \texttt{"} TT\texttt{"} , otherwise it is \texttt{"} TAI\texttt{"} . Note, if the System attribute is set so that the TimeFrame represents Besselian \htmlref{Epoch}{Epoch}, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT. Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the \htmlref{Dut1}{Dut1} attribute (defined by the parent \htmlref{Frame}{Frame} class). This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute for further details. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } \sstdiytopic{ Time Scales }{ The TimeFrame class supports the following TimeScale values (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} TAI\texttt{"} - International Atomic Time \sstitem \texttt{"} UTC\texttt{"} - Coordinated Universal Time \sstitem \texttt{"} UT1\texttt{"} - Universal Time \sstitem \texttt{"} GMST\texttt{"} - Greenwich Mean Sidereal Time \sstitem \texttt{"} LAST\texttt{"} - Local Apparent Sidereal Time \sstitem \texttt{"} LMST\texttt{"} - Local Mean Sidereal Time \sstitem \texttt{"} TT\texttt{"} - Terrestrial Time \sstitem \texttt{"} TDB\texttt{"} - Barycentric Dynamical Time \sstitem \texttt{"} TCB\texttt{"} - Barycentric Coordinate Time \sstitem \texttt{"} TCG\texttt{"} - Geocentric Coordinate Time \sstitem \texttt{"} LT\texttt{"} - Local Time (the offset from UTC is given by attribute \htmlref{LTOffset}{LTOffset}) } An very informative description of these and other time scales is available at http://www.ucolick.org/$\sim$sla/leapsecs/timescales.html. } \sstdiytopic{ UTC \htmlref{Warnings}{Warnings} }{ UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won\texttt{'} t matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times. } } \sstroutine{ Title }{ Frame title }{ \sstdescription{ This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a \htmlref{Frame}{Frame} represents. Examples might be \texttt{"} Detector Coordinates\texttt{"} or \texttt{"} Galactic Coordinates\texttt{"} . If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is \texttt{"} $<$n$>$-d coordinate system\texttt{"} , where $<$n$>$ is the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The CmpFrame class re-defines the default Title value to be \texttt{"} $<$n$>$-d compound coordinate system\texttt{"} , where $<$n$>$ is the number of CmpFrame axes (Naxes attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem A Frame\texttt{'} s Title is intended purely for interpretation by human readers and not by software. } } } \sstroutine{ TitleGap }{ Vertical spacing for a Plot title }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{AST\_GRID}{AST\_GRID} routine) by determining where the title of a \htmlref{Plot}{Plot} is drawn. Its value gives the spacing between the bottom edge of the title and the top edge of a bounding box containing all the other parts of the annotated grid. Positive values cause the title to be drawn outside the box, while negative values cause it to be drawn inside. The TitleGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.05. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes since it does not draw a \htmlref{Title}{Title}. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the title is obtained from the Plot\texttt{'} s Title attribute. } } } \sstroutine{ Tol }{ Plotting tolerance }{ \sstdescription{ This attribute specifies the plotting tolerance (or resolution) to be used for the graphical output produced by a \htmlref{Plot}{Plot}. Smaller values will result in smoother and more accurate curves being drawn, but may slow down the plotting process. Conversely, larger values may speed up the plotting process in cases where high resolution is not required. The Tol value should be given as a fraction of the minimum dimension of the plotting area, and should lie in the range from 1.0E-7 to 1.0. By default, a value of 0.01 is used. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ TolInverse }{ Target relative error for the iterative inverse transformation }{ \sstdescription{ This attribute controls the iterative inverse transformation used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. Its value gives the target relative error in teh axis values of each transformed position. Further iterations will be performed until the target relative error is reached, or the maximum number of iterations given by attribute \htmlref{NiterInverse}{NiterInverse} is reached. The default value is 1.0E-6. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{PolyMap}{PolyMap} }{ All PolyMaps have this attribute. } } } \sstroutine{ Top(axis) }{ Highest axis value to display }{ \sstdescription{ This attribute gives the highest axis value to be displayed (for instance, by the \htmlref{AST\_GRID}{AST\_GRID} method). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ The default supplied by the Frame class is to display all axis values, without any limit. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Top value to $+$90 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ TranForward }{ Forward transformation defined? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform coordinates in the \texttt{"} forward\texttt{"} direction (i.e. converting input coordinates into output coordinates). If this attribute is non-zero, the forward transformation is available. Otherwise, it is not. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The TranForward attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The TranForward attribute of a FrameSet applies to the transformation which converts between the FrameSet\texttt{'} s base \htmlref{Frame}{Frame} and its current Frame (as specified by the \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes). This value is given by the boolean AND of the TranForward values which apply to each of the individual sub-Mappings required to perform this conversion. The TranForward attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if a Mapping with a TranForward value of zero is used to transform coordinates in the forward direction. } } } \sstroutine{ TranInverse }{ Inverse transformation defined? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform coordinates in the \texttt{"} inverse\texttt{"} direction (i.e. converting output coordinates back into input coordinates). If this attribute is non-zero, the inverse transformation is available. Otherwise, it is not. } \sstattributetype{ Integer (boolean), readonly. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The TranInverse attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The TranInverse attribute of a FrameSet applies to the transformation which converts between the FrameSet\texttt{'} s current \htmlref{Frame}{Frame} and its base Frame (as specified by the \htmlref{Current}{Current} and \htmlref{Base}{Base} attributes). This value is given by the boolean AND of the TranInverse values which apply to each of the individual sub-Mappings required to perform this conversion. The TranInverse attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if a Mapping with a TranInverse value of zero is used to transform coordinates in the inverse direction. } } } \sstroutine{ Unit(axis) }{ Physical units for formatted axis values }{ \sstdescription{ This attribute contains a textual representation of the physical units used to represent formatted coordinate values on a particular axis of a \htmlref{Frame}{Frame}. The \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine controls how the Unit values are used. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is an empty string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Unit value (e.g. to \texttt{"} hh:mm:ss.sss\texttt{"} ) to describe the character string returned by the \htmlref{AST\_FORMAT}{AST\_FORMAT} function when formatting coordinate values. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The SpecFrame class re-defines the default Unit value so that it is appropriate for the current \htmlref{System}{System} value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit (e.g. \texttt{"} km\texttt{"} ). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem This attribute described the units used when an axis value is formatted into a string using AST\_FORMAT. In some cases these units may be different to those used to represent floating point axis values within application code (for instance a SkyFrame always uses radians to represent floating point axis values). The InternalUnit attribute described the units used for floating point values. \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ UnitRadius }{ SphMap input vectors lie on a unit sphere? }{ \sstdescription{ This is a boolean attribute which indicates whether the 3-dimensional vectors which are supplied as input to a \htmlref{SphMap}{SphMap} are known to always have unit length, so that they lie on a unit sphere centred on the origin. If this condition is true (indicated by setting UnitRadius non-zero), it implies that a \htmlref{CmpMap}{CmpMap} which is composed of a SphMap applied in the forward direction followed by a similar SphMap applied in the inverse direction may be simplified (e.g. by \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}) to become a \htmlref{UnitMap}{UnitMap}. This is because the input and output vectors will both have unit length and will therefore have the same coordinate values. If UnitRadius is zero (the default), then although the output vector produced by the CmpMap (above) will still have unit length, the input vector may not have. This will, in general, change the coordinate values, so it prevents the pair of SphMaps being simplified. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SphMap }{ All SphMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem This attribute is intended mainly for use when SphMaps are involved in a sequence of Mappings which project (e.g.) a dataset on to the celestial sphere. By regarding the celestial sphere as a unit sphere (and setting UnitRadius to be non-zero) it becomes possible to cancel the SphMaps present, along with associated sky projections, when two datasets are aligned using celestial coordinates. This often considerably improves performance. \sstitem Such a situations often arises when interpreting FITS data and is handled automatically by the \htmlref{FitsChan}{FitsChan} class. \sstitem The value of the UnitRadius attribute is used only to control the simplification of Mappings and has no effect on the value of the coordinates transformed by a SphMap. The lengths of the input 3-dimensional Cartesian vectors supplied are always ignored, even if UnitRadius is non-zero. \sstitem The value of this attribute may changed only if the SphMap has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a CmpMap or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{AST\_CLONE}{AST\_CLONE} function. } } } \sstroutine{ UseDefs }{ Use default values for unspecified attributes? }{ \sstdescription{ This attribute specifies whether default values should be used internally for object attributes which have not been assigned a value explicitly. If a non-zero value (the default) is supplied for UseDefs, then default values will be used for attributes which have not explicitly been assigned a value. If zero is supplied for UseDefs, then an error will be reported if an attribute for which no explicit value has been supplied is needed internally within AST. Many attributes (including the UseDefs attribute itself) are unaffected by the setting of the UseDefs attribute, and default values will always be used without error for such attributes. The \texttt{"} Applicability:\texttt{"} section below lists the attributes which are affected by the setting of UseDefs. Note, UseDefs only affects access to attributes internally within AST. The public accessor functions such as AST\_GETC is unaffected by the UseDefs attribute - default values will always be returned if no value has been set. Application code should use the \htmlref{AST\_TEST}{AST\_TEST} function if required to determine if a value has been set for an attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ All Objects have this attribute, but ignore its setting except as described below for individual classes. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The default value of UseDefs for a FrameSet is redefined to be the UseDefs value of its current \htmlref{Frame}{Frame}. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default value of UseDefs for a CmpFrame is redefined to be the UseDefs value of its first component Frame. } \sstsubsection{ \htmlref{Region}{Region} }{ The default value of UseDefs for a Region is redefined to be the UseDefs value of its encapsulated Frame. } \sstsubsection{ Frame }{ If UseDefs is zero, an error is reported when aligning Frames if the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat} or \htmlref{ObsLon}{ObsLon} attribute is required but has not been assigned a value explicitly. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ If UseDefs is zero, an error is reported when aligning SkyFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{Equinox}{Equinox}. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ If UseDefs is zero, an error is reported when aligning SpecFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec}, \htmlref{RestFreq}{RestFreq}, \htmlref{SourceVel}{SourceVel}, \htmlref{StdOfRest}{StdOfRest}. } \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ If UseDefs is zero, an error is reported when aligning DSBSpecFrames or when accessing the \htmlref{ImagFreq}{ImagFreq} attribute if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{DSBCentre}{DSBCentre}, \htmlref{IF}{IF}. } } } \sstroutine{ Variant }{ Indicates which variant of the current Frame is to be used }{ \sstdescription{ This attribute can be used to change the \htmlref{Mapping}{Mapping} that connects the current \htmlref{Frame}{Frame} to the other Frames in the \htmlref{FrameSet}{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 \htmlref{AST\_REMAPFRAME}{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 \texttt{"} Variant\texttt{"} 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 \htmlref{Domain}{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 \texttt{"} SKY\texttt{"} . That is, instead of searching for Frames that have a class of \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , such software searches for Frames that have a Domain of \texttt{"} SKY\texttt{"} . 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 \texttt{"} Variant\texttt{"} 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 \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} method. By default, the Mapping supplied to \htmlref{AST\_ADDVARIANT}{AST\_ADDVARIANT} is assigned a name equal to the Domain name of the Frame. To assign a different name to it, the AST\_ADDVARIANT method should then be called specifying the required name and a NULL Mapping. The 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 \htmlref{AST\_MIRRORVARIANTS}{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 \texttt{"} Variant\texttt{"} 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 \texttt{"} Variant\texttt{"} 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 \texttt{"} Variant\texttt{"} attribute will have the effect of removing all variant Mappings (except for the currently selected Mapping) from the current Frame. Testing the \texttt{"} Variant\texttt{"} attribute will return .TRUE. if the current Frame contains any variant Mappings, and .FALSE. otherwise. A complete list of the names associated with all the available variant Mappings in the current Frame can be obtained from the \htmlref{AllVariants}{AllVariants} attribute. If a Frame with variant Mappings is remapped using the AST\_REMAPFRAME method, the currently selected variant Mapping is used by AST\_REMAPFRAME and the other variant Mappings are removed from the Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } } \sstroutine{ Warnings }{ Controls the issuing of warnings about various conditions }{ \sstdescription{ This attribute controls the issuing of warnings about selected conditions when an \htmlref{Object}{Object} or keyword is read from or written to a \htmlref{FitsChan}{FitsChan}. The value supplied for the Warnings attribute should consist of a space separated list of condition names (see the \htmlref{AllWarnings}{AllWarnings} attribute for a list of the currently defined names). Each name indicates a condition which should be reported. The default value for Warnings is the string \texttt{"} BadKeyName BadKeyValue Tnx Zpx BadCel BadMat BadPV BadCTYPE\texttt{"} . The text of any warning will be stored within the FitsChan in the form of one or more new header cards with keyword ASTWARN. If required, applications can check the FitsChan for ASTWARN cards (using \htmlref{AST\_FINDFITS}{AST\_FINDFITS}) after the call to \htmlref{AST\_READ}{AST\_READ} or \htmlref{AST\_WRITE}{AST\_WRITE} has been performed, and report the text of any such cards to the user. ASTWARN cards will be propagated to any output header unless they are deleted from the FitsChan using astDelFits. } \sstattributetype{ String } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } \sstnotes{ This attribute only controls the warnings that are to be stored as a set of header cards in the FitsChan as described above. It has no effect on the storage of warnings in the parent \htmlref{Channel}{Channel} structure. All warnings are stored in the parent Channel structure, from where they can be retrieved using the \htmlref{AST\_WARNINGS}{AST\_WARNINGS} function. } } \sstroutine{ WcsAxis(lonlat) }{ FITS-WCS projection axes }{ \sstdescription{ This attribute gives the indices of the longitude and latitude coordinates of the FITS-WCS projection within the coordinate space used by a \htmlref{WcsMap}{WcsMap}. These indices are defined when the WcsMap is first created using \htmlref{AST\_WCSMAP}{AST\_WCSMAP} and cannot subsequently be altered. If \texttt{"} lonlat\texttt{"} is 1, the index of the longitude axis is returned. Otherwise, if it is 2, the index of the latitude axis is returned. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ WcsType }{ FITS-WCS projection type }{ \sstdescription{ This attribute specifies which type of FITS-WCS projection will be performed by a \htmlref{WcsMap}{WcsMap}. The value is specified when a WcsMap is first created using \htmlref{AST\_WCSMAP}{AST\_WCSMAP} and cannot subsequently be changed. The values used are represented by symbolic constants with names of the form \texttt{"} AST\_\_XXX\texttt{"} , where \texttt{"} XXX\texttt{"} is the (upper case) 3-character code used by the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword to identify the projection. For example, possible values are AST\_\_TAN (for the tangent plane or gnomonic projection) and AST\_\_AIT (for the Hammer-Aitoff projection). AST\_\_TPN is an exception in that it is not part of the FITS-WCS standard (it represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of available projections, see the FITS-WCS paper. } } } \sstroutine{ Width(element) }{ Line width for a Plot element }{ \sstdescription{ This attribute determines the line width used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Width(border)=2.0\texttt{"} causes the Plot border to be drawn using a line width of 2.0. A value of 1.0 results in a line thickness which is approximately 0.0005 times the length of the diagonal of the entire display surface. The actual appearance of lines drawn with any particular width, and the range of available widths, is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line width supplied by this graphics system. This will not necessarily correspond to a Width value of 1.0. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Width\texttt{"} instead of \texttt{"} Width(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Width(\htmlref{Border}{Border}) value. } } } \sstroutine{ XmlFormat }{ System for formatting Objects as XML }{ \sstdescription{ This attribute specifies the formatting system to use when AST Objects are written out as XML through an \htmlref{XmlChan}{XmlChan}. It affects the behaviour of the \htmlref{AST\_WRITE}{AST\_WRITE} routine when they are used to transfer any AST \htmlref{Object}{Object} to or from an external XML representation. The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the \texttt{"} Formats Available\texttt{"} section below. By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the \texttt{"} Choice of Default Format\texttt{"} section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ XmlChan }{ All XmlChans have this attribute. } } \sstdiytopic{ Formats Available }{ The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system: \sstitemlist{ \sstitem \texttt{"} NATIVE\texttt{"} : This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a \htmlref{FitsChan}{FitsChan}). \sstitem \texttt{"} QUOTED\texttt{"} : This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST \htmlref{Channel}{Channel}. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel. \sstitem \texttt{"} IVOA\texttt{"} : This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see \texttt{"} http://www.ivoa.net/\texttt{"} ) to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at \texttt{"} http://www.ivoa.net/Documents/WD/STC/STC-20050225.html\texttt{"} . Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative \texttt{"} STC-S\texttt{"} format (a simpler non-XML encoding of the STC metadata) is supported by the \htmlref{StcsChan}{StcsChan} class. } } \sstdiytopic{ Choice of Default Format; }{ If the XmlFormat attribute of an XmlChan is not set, the default value it takes is determined by the presence of certain critical items within the document most recently read using \htmlref{AST\_READ}{AST\_READ}. The sequence of decision used to arrive at the default value is as follows: \sstitemlist{ \sstitem If the previous document read contained any elements in any of the STC namespaces (\texttt{"} urn:nvo-stc\texttt{"} , \texttt{"} urn:nvo-coords\texttt{"} or \texttt{"} urn:nvo-region\texttt{"} ), then the default value is IVOA. \sstitem If the previous document read contained any elements in the AST namespace which had an associated XML attribute called \texttt{"} quoted\texttt{"} , then the default value is QUOTED. \sstitem Otherwise, if none of these conditions is met (as would be the case if no document had yet been read), then NATIVE format is used. } Setting an explicit value for the XmlFormat attribute always over-rides this default behaviour. } \sstdiytopic{ The IVOA Format }{ The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the \texttt{"} IVOA\texttt{"} XmlChan format is of historical interest only. The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete): \sstitemlist{ \sstitem Objects can currently only be read using this format, not written. \sstitem The AST object generated by reading an $<$STCMetadata$>$ element will be an instance of one of the AST \texttt{"} \htmlref{Stc}{Stc}\texttt{"} classes: \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcObsDataLocation}{StcObsDataLocation}. \sstitem When reading an $<$STCMetadata$>$ element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the $<$STCMetadata$>$ element. If the supplied $<$STCMetadata$>$ element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude). \sstitem Until such time as the AST \htmlref{TimeFrame}{TimeFrame} is complete, a simple 1-dimensional \htmlref{Frame}{Frame} (with \htmlref{Domain}{Domain} set to TIME) will be used to represent the STC $<$TimeFrame$>$ element. Consequently, most of the information within a $<$TimeFrame$>$ element is currently ignored. \sstitem $<$SpaceFrame$>$ elements can only be read if they describe a celestial longitude and latitude axes supported by the AST \htmlref{SkyFrame}{SkyFrame} class. The space axes will be returned in the order (longitude, latitude). \sstitem Velocities associated with SpaceFrames cannot be read. \sstitem Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element are currently ignored. \sstitem Any second or subsequent $<$AstroCoordSystem$>$ found within an STCMetaData element is ignored. \sstitem Any second or subsequent $<$AstroCoordArea$>$ found within an STCMetaData element is ignored. \sstitem Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored. \sstitem Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored. \sstitem $<$SpaceFrame$>$ elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC\_II, SUPER\_GALACTIC, HEE, FK4, FK5, ECLIPTIC. \sstitem $<$SpaceFrame$>$ elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored. \sstitem Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex. \sstitem The AST \htmlref{Region}{Region} read from a CoordInterval element is considered to be open if either the lo\_include or the hi\_include attribute is set to false. \sstitem $<$RegionFile$>$ elements are not supported. \sstitem Vertices within $<$\htmlref{Polygon}{Polygon}$>$ elements are always considered to be joined using great circles (that is, $<$SmallCircle$>$ elements are ignored). } } } \sstroutine{ XmlLength }{ Controls output buffer length }{ \sstdescription{ This attribute specifies the maximum length to use when writing out text through the sink function supplied when the \htmlref{XmlChan}{XmlChan} was created. The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). A value of zero (the default) means there is no limit - each string can be of any length. Note, the default value of zero is unlikely to be appropriate when an XmlChan is used within Fortran code. In this case, XmlLength should usually be set to the size of the CHARACTER variable used to receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function. This avoids the possibility of long lines being truncated invisibly within AST\_GETLINE. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ XmlChan }{ All XmlChans have this attribute. } } } \sstroutine{ XmlPrefix }{ The namespace prefix to use when writing }{ \sstdescription{ This attribute is a string which is to be used as the namespace prefix for all XML elements created as a result of writing an AST \htmlref{Object}{Object} out through an \htmlref{XmlChan}{XmlChan}. The URI associated with the namespace prefix is given by the symbolic constant AST\_\_XMLNS defined in AST\_PAR. A definition of the namespace prefix is included in each top-level element produced by the XmlChan. The default value is a blank string which causes no prefix to be used. In this case each top-level element will set the default namespace to be the value of AST\_\_XMLNS. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Zoom }{ ZoomMap scale factor }{ \sstdescription{ This attribute holds the \htmlref{ZoomMap}{ZoomMap} scale factor, by which coordinate values are multiplied (by the forward transformation) or divided (by the inverse transformation). The default value is unity. Note that if a ZoomMap is inverted (e.g. by using \htmlref{AST\_INVERT}{AST\_INVERT}), then the reciprocal of this zoom factor will, in effect, be used. In general, \htmlref{Mapping}{Mapping} attributes cannot be changed after the Mapping has been created (the exception to this is the \htmlref{Invert}{Invert} attribute, which can be changed at any time). However, several of the oldest Mapping classes - including the ZoomMap class - were introduced into the AST library before this restriction was enforced. To reduce the chances of breaking existing software, the attributes of such Mappings may still be changed, but only for Mapping instances that have exactly one active reference. In other words, an error will be reported if an attempt is made to set or clear an attribute of a Mapping (other than the Invert attribute) if that Mapping has been cloned. Mappings are cloned when they are incorporated into another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet}, or when the \htmlref{AST\_CLONE}{AST\_CLONE} function is used. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ ZoomMap }{ All ZoomMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The Zoom attribute may not be set to zero. } } } \normalsize \cleardoublepage \section{\label{ss:classdescriptions}AST Class Descriptions} \small \sstroutine{ Axis }{ Store axis information }{ \sstdescription{ The Axis class is used to store information associated with a particular axis of a \htmlref{Frame}{Frame}. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from \htmlref{AST\_WRITE}{AST\_WRITE}). } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Axis class inherits from the \htmlref{Object}{Object} class. } } \sstroutine{ Box }{ A box region with sides parallel to the axes of a Frame }{ \sstdescription{ The Box class implements a \htmlref{Region}{Region} which represents a box with sides parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a pole). } \sstconstructor{ \htmlref{AST\_BOX}{AST\_BOX} } \sstdiytopic{ Inheritance }{ The Box class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Box class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Box class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ Channel }{ Basic (textual) I/O channel }{ \sstdescription{ The Channel class implements low-level input/output for the AST library. Writing an \htmlref{Object}{Object} to a Channel will generate a textual representation of that Object, and reading from a Channel will create a new Object from its textual representation. Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output. Alternatively, a Channel can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstconstructor{ \htmlref{AST\_CHANNEL}{AST\_CHANNEL} } \sstdiytopic{ Inheritance }{ The Channel class inherits from the Object class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every Channel also has the following attributes: \sstitemlist{ \sstitem \htmlref{Comment}{Comment}: Include textual comments in output? \sstitem \htmlref{Full}{Full}: Set level of output detail \sstitem \htmlref{Indent}{Indent}: Indentation increment between objects \sstitem \htmlref{ReportLevel}{ReportLevel}: Selects the level of error reporting \sstitem \htmlref{SinkFile}{SinkFile}: The path to a file to which the Channel should write \sstitem \htmlref{Skip}{Skip}: Skip irrelevant data? \sstitem \htmlref{SourceFile}{SourceFile}: The path to a file from which the Channel should read \sstitem \htmlref{Strict}{Strict}: Generate errors instead of warnings? } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Objects, the following routines may also be applied to all Channels: \sstitemlist{ \sstitem \htmlref{AST\_WARNINGS}{AST\_WARNINGS}: Return warnings from the previous read or write \sstitem \htmlref{AST\_READ}{AST\_READ}: Read an Object from a Channel \sstitem \htmlref{AST\_WRITE}{AST\_WRITE}: Write an Object to a Channel } } } \sstroutine{ Circle }{ A circular or spherical region within a Frame }{ \sstdescription{ The Circle class implements a \htmlref{Region}{Region} which represents a circle or sphere within a \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{AST\_CIRCLE}{AST\_CIRCLE} } \sstdiytopic{ Inheritance }{ The Circle class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Circle class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Regions, the following routines may also be applied to all Circles: \sstitemlist{ \sstitem \htmlref{AST\_CIRCLEPARS}{AST\_CIRCLEPARS}: Get the geometric parameters of the Circle } } } \sstroutine{ CmpFrame }{ Compound Frame }{ \sstdescription{ A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame). Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way. Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values. } \sstconstructor{ \htmlref{AST\_CMPFRAME}{AST\_CMPFRAME} } \sstdiytopic{ Inheritance }{ The CmpFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ The CmpFrame class does not define any new attributes beyond those which are applicable to all Frames. However, the attributes of the component Frames can be accessed as if they were attributes of the CmpFrame. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame}, then the CmpFrame will recognise the \texttt{"} \htmlref{Equinox}{Equinox}\texttt{"} attribute and forward access requests to the component SkyFrame. Likewise, it will recognise the \texttt{"} \htmlref{RestFreq}{RestFreq}\texttt{"} attribute and forward access requests to the component SpecFrame. An axis index can optionally be appended to the end of any attribute name, in which case the request to access the attribute will be forwarded to the primary Frame defining the specified axis. } \sstdiytopic{ Functions }{ The CmpFrame class does not define any new routines beyond those which are applicable to all Frames. } } \sstroutine{ CmpMap }{ Compound Mapping }{ \sstdescription{ A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be \texttt{"} in series\texttt{"} (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the earlier coordinates for each point and the second Mapping simultaneously transforms the later coordinates). Since a CmpMap is itself a Mapping, it can be used as a component in forming further CmpMaps. Mappings of arbitrary complexity may be built from simple individual Mappings in this way. } \sstconstructor{ \htmlref{AST\_CMPMAP}{AST\_CMPMAP} } \sstdiytopic{ Inheritance }{ The CmpMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The CmpMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The CmpMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ CmpRegion }{ A combination of two regions within a single Frame }{ \sstdescription{ A CmpRegion is a \htmlref{Region}{Region} which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion. The two component Region need not refer to the same coordinate \htmlref{Frame}{Frame}, but it must be possible for the \htmlref{AST\_CONVERT}{AST\_CONVERT} function to determine a \htmlref{Mapping}{Mapping} between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the AST\_CONVERT function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region. Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way. } \sstconstructor{ \htmlref{AST\_CMPREGION}{AST\_CMPREGION} } \sstdiytopic{ Inheritance }{ The CmpRegion class inherits from the Region class. } \sstdiytopic{ Attributes }{ The CmpRegion class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The CmpRegion class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ DSBSpecFrame }{ Dual sideband spectral coordinate system description }{ \sstdescription{ A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents positions in a spectrum obtained using a dual sideband instrument. Such an instrument produces a spectrum in which each point contains contributions from two distinctly different frequencies, one from the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). Corresponding LSB and USB frequencies are connected by the fact that they are an equal distance on either side of a fixed central frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. When quoting a position within such a spectrum, it is necessary to indicate whether the quoted position is the USB position or the corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this indication. Another option that the SideBand attribute provides is to represent a spectral position by its topocentric offset from the LO frequency. In practice, the LO frequency is specified by giving the distance from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically this central position is that of some interesting spectral feature. The distance from this central position to the LO frequency is known as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can be a signed value in order to indicate whether the LO frequency is above or below the central position. } \sstconstructor{ \htmlref{AST\_DSBSPECFRAME}{AST\_DSBSPECFRAME} } \sstdiytopic{ Inheritance }{ The DSBSpecFrame class inherits from the SpecFrame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all SpecFrames, every DSBSpecFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignSideBand}{AlignSideBand}: Should alignment occur between sidebands? \sstitem \htmlref{DSBCentre}{DSBCentre}: The central position of interest. \sstitem \htmlref{IF}{IF}: The intermediate frequency used to define the LO frequency. \sstitem \htmlref{ImagFreq}{ImagFreq}: The image sideband equivalent of the rest frequency. \sstitem \htmlref{SideBand}{SideBand}: Indicates which sideband the DSBSpecFrame represents. } } \sstdiytopic{ Functions }{ The DSBSpecFrame class does not define any new routines beyond those which are applicable to all SpecFrames. } } \sstroutine{ DssMap }{ Map points using a Digitised Sky Survey plate solution }{ \sstdescription{ The DssMap class implements a \htmlref{Mapping}{Mapping} which transforms between 2-dimensional pixel coordinates and an equatorial sky coordinate system (right ascension and declination) using a Digitised Sky Survey (DSS) astrometric plate solution. The input coordinates are pixel numbers along the first and second dimensions of an image, where the centre of the first pixel is located at (1,1) and the spacing between pixel centres is unity. The output coordinates are right ascension and declination in radians. The celestial coordinate system used (FK4, FK5, etc.) is unspecified, and will usually be indicated by appropriate keywords in a FITS header. } \sstconstructor{ The DssMap class does not have a constructor function. A DssMap is created only as a by-product of reading a \htmlref{FrameSet}{FrameSet} (using \htmlref{AST\_READ}{AST\_READ}) from a \htmlref{FitsChan}{FitsChan} which contains FITS header cards describing a DSS plate solution, and whose \htmlref{Encoding}{Encoding} attribute is set to \texttt{"} DSS\texttt{"} . The result of such a read, if successful, is a FrameSet whose base and current Frames are related by a DssMap. } \sstdiytopic{ Inheritance }{ The DssMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The DssMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The DssMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Ellipse }{ An elliptical region within a 2-dimensional Frame }{ \sstdescription{ The Ellipse class implements a \htmlref{Region}{Region} which represents a ellipse within a 2-dimensional \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{AST\_ELLIPSE}{AST\_ELLIPSE} } \sstdiytopic{ Inheritance }{ The Ellipse class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Ellipse class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Regions, the following routines may also be applied to all Ellipses: \sstitemlist{ \sstitem \htmlref{AST\_ELLIPSEPARS}{AST\_ELLIPSEPARS}: Get the geometric parameters of the Ellipse } } } \sstroutine{ FitsChan }{ I/O Channel using FITS header cards to represent Objects }{ \sstdescription{ A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O operations involving the use of FITS (Flexible Image Transport \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description. While a FitsChan is active, it represents a buffer which may contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} card, to which subsequent operations apply. Searches based on keyword may be performed (using \htmlref{AST\_FINDFITS}{AST\_FINDFITS}), new cards may be inserted (\htmlref{AST\_PUTFITS}{AST\_PUTFITS}, \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}, \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}) and existing ones may be deleted (\htmlref{AST\_DELFITS}{AST\_DELFITS}), extracted (\htmlref{AST\_GETFITS$<$X$>$}{AST\_GETFITS$<$X$>$}) or changed (AST\_SETFITS$<$X$>$). When you create a FitsChan, you have the option of specifying \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using AST\_PUTFITS, AST\_PUTCARDS, AST\_WRITE or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from which headers should be read). When the FitsChan is deleted, any remaining header cards in the FitsChan can be saved in either of two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the name of a text file to which header cards should be written), or 2) by providing a sink function (used to to deliver header cards to an external data store). If you do not provide a sink function or a value for SinkFile, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using AST\_FINDFITS or \htmlref{AST\_READ}{AST\_READ}). Coordinate system information may be described using FITS header cards using several different conventions, termed \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers). The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings. The detailed behaviour of AST\_READ and AST\_WRITE, when used with a FitsChan, depends on the encoding in use. In general, however, all successful use of AST\_READ is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS} routine). An unsuccessful call of AST\_READ (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged. If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using AST\_WRITE will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence. } \sstconstructor{ \htmlref{AST\_FITSCHAN}{AST\_FITSCHAN} } \sstdiytopic{ Inheritance }{ The FitsChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every FitsChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{AllWarnings}{AllWarnings}: A list of the available conditions \sstitem \htmlref{Card}{Card}: Index of current FITS card in a FitsChan \sstitem \htmlref{CardComm}{CardComm}: The comment of the current FITS card in a FitsChan \sstitem \htmlref{CardName}{CardName}: The keyword name of the current FITS card in a FitsChan \sstitem \htmlref{CardType}{CardType}: The data type of the current FITS card in a FitsChan \sstitem \htmlref{CarLin}{CarLin}: Ignore spherical rotations on CAR projections? \sstitem \htmlref{CDMatrix}{CDMatrix}: Use a CD matrix instead of a PC matrix? \sstitem \htmlref{Clean}{Clean}: Remove cards used whilst reading even if an error occurs? \sstitem \htmlref{DefB1950}{DefB1950}: Use FK4 B1950 as default equatorial coordinates? \sstitem \htmlref{Encoding}{Encoding}: System for encoding Objects as FITS headers \sstitem \htmlref{FitsAxisOrder}{FitsAxisOrder}: Sets the order of WCS axes within new FITS-WCS headers \sstitem \htmlref{FitsDigits}{FitsDigits}: Digits of precision for floating-point FITS values \sstitem \htmlref{Iwc}{Iwc}: Add a \htmlref{Frame}{Frame} describing Intermediate World Coords? \sstitem \htmlref{Ncard}{Ncard}: Number of FITS header cards in a FitsChan \sstitem \htmlref{Nkey}{Nkey}: Number of unique keywords in a FitsChan \sstitem \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"} algorithm be recognised? \sstitem \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection? \sstitem \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Channels, the following routines may also be applied to all FitsChans: \sstitemlist{ \sstitem \htmlref{AST\_DELFITS}{AST\_DELFITS}: Delete the current FITS card in a FitsChan \sstitem \htmlref{AST\_EMPTYFITS}{AST\_EMPTYFITS}: Delete all cards in a FitsChan \sstitem \htmlref{AST\_FINDFITS}{AST\_FINDFITS}: Find a FITS card in a FitsChan by keyword \sstitem \htmlref{AST\_GETFITS$<$X$>$}{AST\_GETFITS$<$X$>$}: Get a keyword value from a FitsChan \sstitem \htmlref{AST\_GETTABLES}{AST\_GETTABLES}: Retrieve any FitsTables from a FitsChan \sstitem \htmlref{AST\_PURGEWCS}{AST\_PURGEWCS}: Delete all WCS-related cards in a FitsChan \sstitem \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}: Stores a set of FITS header card in a FitsChan \sstitem \htmlref{AST\_PUTFITS}{AST\_PUTFITS}: Store a FITS header card in a FitsChan \sstitem \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}: Store a single FitsTables in a FitsChan \sstitem \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES}: Store multiple FitsTables in a FitsChan \sstitem \htmlref{AST\_READFITS}{AST\_READFITS}: Read cards in through the source function \sstitem \htmlref{AST\_REMOVETABLES}{AST\_REMOVETABLES}: Remove one or more FitsTables from a FitsChan \sstitem \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS}: Ensure current card is retained in a FitsChan \sstitem \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}: Store a new keyword value in a FitsChan \sstitem \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE}: Register a source function for FITS table access \sstitem \htmlref{AST\_TESTFITS}{AST\_TESTFITS}: Test if a keyword has a defined value in a FitsChan \sstitem \htmlref{AST\_WRITEFITS}{AST\_WRITEFITS}: Write all cards out to the sink function } } } \sstroutine{ FitsTable }{ A representation of a FITS binary table }{ \sstdescription{ The FitsTable class is a representation of a FITS binary table. It inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the binary data of the main table, and a \htmlref{FitsChan}{FitsChan} (encapsulated within the FitsTable) is used to hold the FITS header. Note - it is not recommended to use the FitsTable class to store very large tables. FitsTables are primarily geared towards the needs of the \texttt{"} -TAB\texttt{"} algorithm defined in FITS-WCS paper 2, and so do not support all features of FITS binary tables. In particularly, they do not provide any equivalent to the following features of FITS binary tables: \texttt{"} heap\texttt{"} data (i.e. binary data following the main table), columns holding complex values, columns holding variable length arrays, scaled columns, column formats, columns holding bit values, 8-byte integer values or logical values. } \sstconstructor{ \htmlref{AST\_FITSTABLE}{AST\_FITSTABLE} } \sstdiytopic{ Inheritance }{ The FitsTable class inherits from the Table class. } \sstdiytopic{ Attributes }{ The FitsTable class does not define any new attributes beyond those which are applicable to all Tables. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Tables, the following routines may also be applied to all FitsTables: \sstitemlist{ \sstitem \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL}: Get/set the null value for a column of a FitsTable \sstitem \htmlref{AST\_COLUMNSIZE}{AST\_COLUMNSIZE}: Get number of bytes needed to hold a full column of data \sstitem \htmlref{AST\_GETCOLUMNDATA}{AST\_GETCOLUMNDATA}: Retrieve all the data values stored in a column \sstitem AST\_GETTABLEHEADER: Get the FITS headers from a FitsTable \sstitem \htmlref{AST\_PUTCOLUMNDATA}{AST\_PUTCOLUMNDATA}: Store data values in a column \sstitem \htmlref{AST\_PUTTABLEHEADER}{AST\_PUTTABLEHEADER}: Store FITS headers within a FitsTable } } } \sstroutine{ FluxFrame }{ Measured flux description }{ \sstdescription{ A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various systems used to represent the signal level in an observation. The particular coordinate system to be used is specified by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by other attributes such as the units, etc (see the description of the System attribute for details). All flux values are assumed to be measured at the same frequency or wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is more appropriate for use with images rather than spectra. } \sstconstructor{ \htmlref{AST\_FLUXFRAME}{AST\_FLUXFRAME} } \sstdiytopic{ Inheritance }{ The FluxFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every FluxFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{SpecVal}{SpecVal}: The spectral position at which the flux values are measured. } } \sstdiytopic{ Functions }{ The FluxFrame class does not define any new routines beyond those which are applicable to all Frames. } } \sstroutine{ Frame }{ Coordinate system description }{ \sstdescription{ This class is used to represent coordinate systems. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a \htmlref{Title}{Title} (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two. Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame. Frames may also contain knowledge of how to transform to and from related coordinate systems. } \sstconstructor{ \htmlref{AST\_FRAME}{AST\_FRAME} } \sstnotes{ \sstitemlist{ \sstitem When used as a \htmlref{Mapping}{Mapping}, a Frame implements a unit (null) transformation in both the forward and inverse directions (equivalent to a \htmlref{UnitMap}{UnitMap}). The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attribute values are both equal to the number of Frame axes. } } \sstdiytopic{ Inheritance }{ The Frame class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every Frame also has the following attributes (if the Frame has only one axis, the axis specifier can be omited from the following attribute names): \sstitemlist{ \sstitem \htmlref{AlignSystem}{AlignSystem}: Coordinate system used to align Frames \sstitem \htmlref{Bottom(axis)}{Bottom(axis)}: Lowest axis value to display \sstitem \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}: Number of digits of precision \sstitem \htmlref{Direction(axis)}{Direction(axis)}: Display axis in conventional direction? \sstitem \htmlref{Domain}{Domain}: Coordinate system domain \sstitem \htmlref{Dut1}{Dut1}: Difference between the UT1 and UTC timescale \sstitem \htmlref{Epoch}{Epoch}: Epoch of observation \sstitem \htmlref{Format(axis)}{Format(axis)}: Format specification for axis values \sstitem \htmlref{InternalUnit(axis)}{InternalUnit(axis)}: Physical units for unformated axis values \sstitem \htmlref{Label(axis)}{Label(axis)}: \htmlref{Axis}{Axis} label \sstitem \htmlref{MatchEnd}{MatchEnd}: Match trailing axes? \sstitem \htmlref{MaxAxes}{MaxAxes}: Maximum number of Frame axes to match \sstitem \htmlref{MinAxes}{MinAxes}: Minimum number of Frame axes to match \sstitem \htmlref{Naxes}{Naxes}: Number of Frame axes \sstitem \htmlref{NormUnit(axis)}{NormUnit(axis)}: Normalised physical units for formatted axis values \sstitem \htmlref{ObsAlt}{ObsAlt}: Geodetic altitude of observer \sstitem \htmlref{ObsLat}{ObsLat}: Geodetic latitude of observer \sstitem \htmlref{ObsLon}{ObsLon}: Geodetic longitude of observer \sstitem \htmlref{Permute}{Permute}: Permute axis order? \sstitem \htmlref{PreserveAxes}{PreserveAxes}: Preserve axes? \sstitem \htmlref{Symbol(axis)}{Symbol(axis)}: Axis symbol \sstitem \htmlref{System}{System}: Coordinate system used to describe the domain \sstitem \htmlref{Title}{Title}: Frame title \sstitem \htmlref{Top(axis)}{Top(axis)}: Highest axis value to display \sstitem \htmlref{Unit(axis)}{Unit(axis)}: Physical units for formatted axis values } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Mappings, the following routines may also be applied to all Frames: \sstitemlist{ \sstitem \htmlref{AST\_ANGLE}{AST\_ANGLE}: Find the angle subtended by two points at a third point \sstitem \htmlref{AST\_AXANGLE}{AST\_AXANGLE}: Find the angle from an axis, to a line through two points \sstitem \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE}: Calculate the distance between two axis values \sstitem \htmlref{AST\_AXNORM}{AST\_AXNORM}: Normalises an array of axis values \sstitem \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET}: Calculate an offset along an axis \sstitem \htmlref{AST\_CONVERT}{AST\_CONVERT}: Determine how to convert between two coordinate systems \sstitem \htmlref{AST\_DISTANCE}{AST\_DISTANCE}: Calculate the distance between two points in a Frame \sstitem \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}: Find a coordinate system with specified characteristics \sstitem \htmlref{AST\_FORMAT}{AST\_FORMAT}: Format a coordinate value for a Frame axis \sstitem \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT}: Determines how the Unit attribute will be used \sstitem \htmlref{AST\_INTERSECT}{AST\_INTERSECT}: Find the intersection between two geodesic curves \sstitem \htmlref{AST\_MATCHAXES}{AST\_MATCHAXES}: Find any corresponding axes in two Frames \sstitem \htmlref{AST\_NORM}{AST\_NORM}: Normalise a set of Frame coordinates \sstitem \htmlref{AST\_OFFSET}{AST\_OFFSET}: Calculate an offset along a geodesic curve \sstitem \htmlref{AST\_OFFSET2}{AST\_OFFSET2}: Calculate an offset along a geodesic curve in a 2D Frame \sstitem \htmlref{AST\_PERMAXES}{AST\_PERMAXES}: Permute the order of a Frame\texttt{'} s axes \sstitem \htmlref{AST\_PICKAXES}{AST\_PICKAXES}: Create a new Frame by picking axes from an existing one \sstitem \htmlref{AST\_RESOLVE}{AST\_RESOLVE}: Resolve a vector into two orthogonal components \sstitem \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT}: Specify how the Unit attribute should be used \sstitem \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}: Read a formatted coordinate value for a Frame axis } } } \sstroutine{ FrameSet }{ Set of inter-related coordinate systems }{ \sstdescription{ 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 \htmlref{Mapping}{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 \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} 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\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{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 \texttt{"} native\texttt{"} coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the \texttt{"} apparent\texttt{"} 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 \htmlref{Title}{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 \texttt{"} native\texttt{"} coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see \htmlref{AST\_INVERT}{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 \htmlref{Region}{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. } \sstconstructor{ \htmlref{AST\_FRAMESET}{AST\_FRAMESET} } \sstdiytopic{ Inheritance }{ The FrameSet class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every FrameSet also has the following attributes: \sstitemlist{ \sstitem \htmlref{AllVariants}{AllVariants}: List of all variant mappings store with current Frame \sstitem \htmlref{Base}{Base}: FrameSet base Frame index \sstitem \htmlref{Current}{Current}: FrameSet current Frame index \sstitem \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet \sstitem \htmlref{Variant}{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\texttt{'} s class. (For example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{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. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Frames, the following routines may also be applied to all FrameSets: \sstitemlist{ \sstitem \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}: Add a Frame to a FrameSet to define a new coordinate system \sstitem \htmlref{AST\_ADDVARIANT}{AST\_ADDVARIANT}: Add a variant Mapping to the current Frame \sstitem \htmlref{AST\_GETFRAME}{AST\_GETFRAME}: Obtain a pointer to a specified Frame in a FrameSet \sstitem \htmlref{AST\_GETMAPPING}{AST\_GETMAPPING}: Obtain a Mapping between two Frames in a FrameSet \sstitem \htmlref{AST\_MIRRORVARIANTS}{AST\_MIRRORVARIANTS}: Make the current Frame mirror variant Mappings in another Frame \sstitem \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME}: Modify a Frame\texttt{'} s relationship to the other Frames in a FrameSet \sstitem \htmlref{AST\_REMOVEFRAME}{AST\_REMOVEFRAME}: Remove a Frame from a FrameSet } } } \sstroutine{ GrismMap }{ Transform 1-dimensional coordinates using a grism dispersion equation }{ \sstdescription{ A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III \texttt{"} Representation of spectral coordinates in FITS\texttt{"} . This describes the dispersion produced by gratings, prisms and grisms. When initially created, the forward transformation of a GrismMap transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as \texttt{"} the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length\texttt{"} . The units in which wavelength values are expected or returned is determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will also be used for the wavelength values. } \sstconstructor{ \htmlref{AST\_GRISMMAP}{AST\_GRISMMAP} } \sstdiytopic{ Inheritance }{ The GrismMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every GrismMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{GrismNR}{GrismNR}: The refractive index at the reference wavelength \sstitem \htmlref{GrismNRP}{GrismNRP}: Rate of change of refractive index with wavelength \sstitem \htmlref{GrismWaveR}{GrismWaveR}: The reference wavelength \sstitem \htmlref{GrismAlpha}{GrismAlpha}: The angle of incidence of the incoming light \sstitem \htmlref{GrismG}{GrismG}: The grating ruling density \sstitem \htmlref{GrismM}{GrismM}: The interference order \sstitem \htmlref{GrismEps}{GrismEps}: The angle between the normal and the dispersion plane \sstitem \htmlref{GrismTheta}{GrismTheta}: Angle between normal to detector plane and reference ray } } \sstdiytopic{ Functions }{ The GrismMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Interval }{ A region representing an interval on one or more axes of a Frame }{ \sstdescription{ The Interval class implements a \htmlref{Region}{Region} which represents upper and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval. Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} should usually be used in these cases since this requires the user to think about suitable upper and lower limits, } \sstconstructor{ \htmlref{AST\_INTERVAL}{AST\_INTERVAL} } \sstdiytopic{ Inheritance }{ The Interval class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Interval class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Interval class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ IntraMap }{ Map points using a private transformation routine }{ \sstdescription{ The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which encapsulates a privately-defined coordinate transformation routine (e.g. written in Fortran) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. However, an IntraMap is intended for use within a single program or a private suite of software, where all programs have access to the same coordinate transformation functions (i.e. can be linked against them). IntraMaps should not normally be stored in datasets which may be exported for processing by other software, since that software will not have the necessary transformation functions available, resulting in an error. You must register any coordinate transformation functions to be used using \htmlref{AST\_INTRAREG}{AST\_INTRAREG} before creating an IntraMap. } \sstconstructor{ \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} (also see AST\_INTRAREG) } \sstdiytopic{ Inheritance }{ The IntraMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every IntraMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{IntraFlag}{IntraFlag}: IntraMap identification string } } \sstdiytopic{ Functions }{ The IntraMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ KeyMap }{ Store a set of key/value pairs }{ \sstdescription{ The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), character string or AST \htmlref{Object}{Object} pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap. } \sstconstructor{ \htmlref{AST\_KEYMAP}{AST\_KEYMAP} } \sstdiytopic{ Inheritance }{ The KeyMap class inherits from the Object class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every KeyMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{KeyCase}{KeyCase}: Sets the case in which keys are stored \sstitem \htmlref{KeyError}{KeyError}: \htmlref{Report}{Report} an error if the requested key does not exist? \sstitem \htmlref{SizeGuess}{SizeGuess}: The expected size of the KeyMap. \sstitem \htmlref{SortBy}{SortBy}: Determines how keys are sorted in a KeyMap. \sstitem \htmlref{MapLocked}{MapLocked}: Prevent new entries being added to the KeyMap? } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Objects, the following routines may also be applied to all KeyMaps: \sstitemlist{ \sstitem \htmlref{AST\_MAPDEFINED}{AST\_MAPDEFINED}: Does a KeyMap contain a defined value for a key? \sstitem \htmlref{AST\_MAPGET0$<$X$>$}{AST\_MAPGET0$<$X$>$}: Get a named scalar entry from a KeyMap \sstitem \htmlref{AST\_MAPGET1$<$X$>$}{AST\_MAPGET1$<$X$>$}: Get a named vector entry from a KeyMap \sstitem \htmlref{AST\_MAPGETELEM$<$X$>$}{AST\_MAPGETELEM$<$X$>$}: Get an element of a named vector entry from a KeyMap \sstitem \htmlref{AST\_MAPHASKEY}{AST\_MAPHASKEY}: Does the KeyMap contain a named entry? \sstitem \htmlref{AST\_MAPKEY}{AST\_MAPKEY}: Return the key name at a given index in the KeyMap \sstitem \htmlref{AST\_MAPLENC}{AST\_MAPLENC}: Get the length of a named character entry in a KeyMap \sstitem \htmlref{AST\_MAPLENGTH}{AST\_MAPLENGTH}: Get the length of a named entry in a KeyMap \sstitem \htmlref{AST\_MAPCOPY}{AST\_MAPCOPY}: Copy entries from one KeyMap into another \sstitem \htmlref{AST\_MAPPUT0$<$X$>$}{AST\_MAPPUT0$<$X$>$}: Add a new scalar entry to a KeyMap \sstitem \htmlref{AST\_MAPPUT1$<$X$>$}{AST\_MAPPUT1$<$X$>$}: Add a new vector entry to a KeyMap \sstitem \htmlref{AST\_MAPPUTELEM$<$X$>$}{AST\_MAPPUTELEM$<$X$>$}: Puts a value into a vector entry in a KeyMap \sstitem \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}: Add a new entry to a KeyMap with an undefined value \sstitem \htmlref{AST\_MAPREMOVE}{AST\_MAPREMOVE}: Removed a named entry from a KeyMap \sstitem \htmlref{AST\_MAPRENAME}{AST\_MAPRENAME}: Rename an existing entry in a KeyMap \sstitem \htmlref{AST\_MAPSIZE}{AST\_MAPSIZE}: Get the number of entries in a KeyMap \sstitem \htmlref{AST\_MAPTYPE}{AST\_MAPTYPE}: Return the data type of a named entry in a map } } } \sstroutine{ LutMap }{ Transform 1-dimensional coordinates using a lookup table }{ \sstdescription{ A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. Each input coordinate value is first scaled to give the index of an entry in the table by subtracting a starting value (the input coordinate corresponding to the first table entry) and dividing by an increment (the difference in input coordinate value between adjacent table entries). The resulting index will usually contain a fractional part, so the output coordinate value is then generated by interpolating linearly between the appropriate entries in the table. If the index lies outside the range of the table, linear extrapolation is used based on the two nearest entries (i.e. the two entries at the start or end of the table, as appropriate). If either of the entries used for the interplation has a value of AST\_\_BAD, then the interpolated value is returned as AST\_\_BAD. If the lookup table entries increase or decrease monotonically (ignoring any flat sections), then the inverse transformation may also be performed. } \sstconstructor{ \htmlref{AST\_LUTMAP}{AST\_LUTMAP} } \sstdiytopic{ Inheritance }{ The LutMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every LutMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{LutEpsilon}{LutEpsilon}: The relative error of the values in the table. \sstitem \htmlref{LutInterp}{LutInterp}: The interpolation method to use between table entries. } } \sstdiytopic{ Functions }{ The LutMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Mapping }{ Inter-relate two coordinate systems }{ \sstdescription{ This class provides the basic facilities for transforming a set of coordinates (representing \texttt{"} input\texttt{"} points) to give a new set of coordinates (representing \texttt{"} output\texttt{"} points). It is used to describe the relationship which exists between two different coordinate systems and to implement operations which make use of this (such as transforming coordinates and resampling grids of data). However, the Mapping class does not have a constructor function of its own, as it is simply a container class for a family of specialised Mappings which implement particular types of coordinate transformation. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Mapping class inherits from the \htmlref{Object}{Object} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every Mapping also has the following attributes: \sstitemlist{ \sstitem \htmlref{Invert}{Invert}: Mapping inversion flag \sstitem \htmlref{IsLinear}{IsLinear}: Is the Mapping linear? \sstitem \htmlref{IsSimple}{IsSimple}: Has the Mapping been simplified? \sstitem \htmlref{Nin}{Nin}: Number of input coordinates for a Mapping \sstitem \htmlref{Nout}{Nout}: Number of output coordinates for a Mapping \sstitem \htmlref{Report}{Report}: Report transformed coordinates? \sstitem \htmlref{TranForward}{TranForward}: Forward transformation defined? \sstitem \htmlref{TranInverse}{TranInverse}: Inverse transformation defined? } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Objects, the following routines may also be applied to all Mappings: \sstitemlist{ \sstitem \htmlref{AST\_DECOMPOSE}{AST\_DECOMPOSE}: Decompose a Mapping into two component Mappings \sstitem \htmlref{AST\_TRANGRID}{AST\_TRANGRID}: Transform a grid of positions \sstitem \htmlref{AST\_INVERT}{AST\_INVERT}: Invert a Mapping \sstitem \htmlref{AST\_LINEARAPPROX}{AST\_LINEARAPPROX}: Calculate a linear approximation to a Mapping \sstitem \htmlref{AST\_QUADAPPROX}{AST\_QUADAPPROX}: Calculate a quadratic approximation to a 2D Mapping \sstitem \htmlref{AST\_MAPBOX}{AST\_MAPBOX}: Find a bounding box for a Mapping \sstitem \htmlref{AST\_MAPSPLIT}{AST\_MAPSPLIT}: Split a Mapping up into parallel component Mappings \sstitem \htmlref{AST\_RATE}{AST\_RATE}: Calculate the rate of change of a Mapping output \sstitem \htmlref{AST\_REBIN$<$X$>$}{AST\_REBIN$<$X$>$}: Rebin a region of a data grid \sstitem \htmlref{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$}: Rebin a region of a sequence of data grids \sstitem \htmlref{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS}: Remove any Regions from a Mapping \sstitem \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}: Resample a region of a data grid \sstitem \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}: Simplify a Mapping \sstitem \htmlref{AST\_TRAN1}{AST\_TRAN1}: Transform 1-dimensional coordinates \sstitem \htmlref{AST\_TRAN2}{AST\_TRAN2}: Transform 2-dimensional coordinates \sstitem \htmlref{AST\_TRANN}{AST\_TRANN}: Transform N-dimensional coordinates } } } \sstroutine{ MathMap }{ Transform coordinates using mathematical expressions }{ \sstdescription{ A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in Fortran. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs. } \sstconstructor{ \htmlref{AST\_MATHMAP}{AST\_MATHMAP} } \sstdiytopic{ Inheritance }{ The MathMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every MathMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Seed}{Seed}: Random number seed \sstitem \htmlref{SimpFI}{SimpFI}: Forward-inverse MathMap pairs simplify? \sstitem \htmlref{SimpIF}{SimpIF}: Inverse-forward MathMap pairs simplify? } } \sstdiytopic{ Functions }{ The MathMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ MatrixMap }{ Map coordinates by multiplying by a matrix }{ \sstdescription{ A MatrixMap is form of \htmlref{Mapping}{Mapping} which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed. } \sstconstructor{ \htmlref{AST\_MATRIXMAP}{AST\_MATRIXMAP} } \sstdiytopic{ Inheritance }{ The MatrixMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The MatrixMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The MatrixMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ NormMap }{ Normalise coordinates using a supplied Frame }{ \sstdescription{ The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate values using the \htmlref{AST\_NORM}{AST\_NORM} routine of a supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap are both equal to the number of axes in the supplied Frame. The forward and inverse transformation of a NormMap are both defined but are identical (that is, they do not form a real inverse pair in that the inverse transformation does not undo the normalisation, instead it reapplies it). However, the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} function will replace neighbouring pairs of forward and inverse NormMaps by a single \htmlref{UnitMap}{UnitMap}. } \sstconstructor{ \htmlref{AST\_NORMMAP}{AST\_NORMMAP} } \sstdiytopic{ Inheritance }{ The NormMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The NormMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The NormMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ NullRegion }{ A boundless region within a Frame }{ \sstdescription{ The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}. If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion represents a Region containing no points. If the Negated attribute of a NullRegion is true, the NullRegion represents an infinite Region (that is, all points in the coordinate system are inside the NullRegion). } \sstconstructor{ \htmlref{AST\_NULLREGION}{AST\_NULLREGION} } \sstdiytopic{ Inheritance }{ The NullRegion class inherits from the Region class. } \sstdiytopic{ Attributes }{ The NullRegion class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The NullRegion class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ Object }{ Base class for all AST Objects }{ \sstdescription{ This class is the base class from which all other classes in the AST library are derived. It provides all the basic Object behaviour and Object manipulation facilities required throughout the library. There is no Object constructor, however, as Objects on their own are not useful. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Object base class does not inherit from any other class. } \sstdiytopic{ Attributes }{ All Objects have the following attributes: \sstitemlist{ \sstitem \htmlref{Class}{Class}: Object class name \sstitem \htmlref{ID}{ID}: Object identification string \sstitem \htmlref{Ident}{Ident}: Permanent Object identification string \sstitem \htmlref{Nobject}{Nobject}: Number of Objects in class \sstitem \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes \sstitem \htmlref{RefCount}{RefCount}: Count of active Object pointers \sstitem \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes? } } \sstdiytopic{ Functions }{ The following routines may be applied to all Objects: \sstitemlist{ \sstitem \htmlref{AST\_ANNUL}{AST\_ANNUL}: Annul a pointer to an Object \sstitem \htmlref{AST\_BEGIN}{AST\_BEGIN}: Begin a new AST context \sstitem \htmlref{AST\_CLEAR}{AST\_CLEAR}: Clear attribute values for an Object \sstitem \htmlref{AST\_CLONE}{AST\_CLONE}: Clone a pointer to an Object \sstitem \htmlref{AST\_COPY}{AST\_COPY}: Copy an Object \sstitem \htmlref{AST\_DELETE}{AST\_DELETE}: Delete an Object \sstitem \htmlref{AST\_END}{AST\_END}: End an AST context \sstitem \htmlref{AST\_ESCAPES}{AST\_ESCAPES}: Control whether graphical escape sequences are removed \sstitem \htmlref{AST\_EXEMPT}{AST\_EXEMPT}: Exempt an Object pointer from AST context handling \sstitem \htmlref{AST\_EXPORT}{AST\_EXPORT}: Export an Object pointer to an outer context \sstitem \htmlref{AST\_GET$<$X$>$}{AST\_GET$<$X$>$}: Get an attribute value for an Object \sstitem \htmlref{AST\_HASATTRIBUTE}{AST\_HASATTRIBUTE}: Test if an Object has a named attribute \sstitem \htmlref{AST\_IMPORT}{AST\_IMPORT}: Import an Object pointer to the current context \sstitem \htmlref{AST\_ISA$<$CLASS$>$}{AST\_ISA$<$CLASS$>$}: Test class membership \sstitem \htmlref{AST\_SAME}{AST\_SAME}: Do two AST pointers refer to the same Object? \sstitem \htmlref{AST\_SET}{AST\_SET}: Set attribute values for an Object \sstitem \htmlref{AST\_SET$<$X$>$}{AST\_SET$<$X$>$}: Set an attribute value for an Object \sstitem \htmlref{AST\_SHOW}{AST\_SHOW}: Display a textual representation of an Object on standard output \sstitem \htmlref{AST\_TEST}{AST\_TEST}: Test if an attribute value is set for an Object \sstitem \htmlref{AST\_TUNE}{AST\_TUNE}: Set or get an integer AST tuning parameter \sstitem \htmlref{AST\_TUNEC}{AST\_TUNEC}: Set or get a character AST tuning parameter \sstitem \htmlref{AST\_VERSION}{AST\_VERSION}: Return the verson of the AST library being used. } } } \sstroutine{ PcdMap }{ Apply 2-dimensional pincushion/barrel distortion }{ \sstdescription{ A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. This can take the form either of pincushion or barrel distortion, and is characterized by a single distortion coefficient. A PcdMap is specified by giving this distortion coefficient and the coordinates of the centre of the radial distortion. The forward transformation of a PcdMap applies the distortion: RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) where R is the undistorted radial distance from the distortion centre (specified by attribute PcdCen), RD is the radial distance from the same centre in the presence of distortion, and C is the distortion coefficient (given by attribute \htmlref{Disco}{Disco}). The inverse transformation of a PcdMap removes the distortion produced by the forward transformation. The expression used to derive R from RD is an approximate inverse of the expression above. } \sstconstructor{ \htmlref{AST\_PCDMAP}{AST\_PCDMAP} } \sstdiytopic{ Inheritance }{ The PcdMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every PcdMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient \sstitem \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion } } \sstdiytopic{ Functions }{ The PcdMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ PermMap }{ Coordinate permutation Mapping }{ \sstdescription{ A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output. In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones. } \sstconstructor{ \htmlref{AST\_PERMMAP}{AST\_PERMMAP} } \sstdiytopic{ Inheritance }{ The PermMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The PermMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The PermMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Plot }{ Provide facilities for 2D graphical output }{ \sstdescription{ This class provides facilities for producing 2D graphical output. A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created. The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect). Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see \htmlref{AST\_CURVE}{AST\_CURVE}, \htmlref{AST\_GENCURVE}{AST\_GENCURVE} and \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}). A Plot also provides facilities for drawing markers or symbols (\htmlref{AST\_MARK}{AST\_MARK}), text (\htmlref{AST\_TEXT}{AST\_TEXT}) and grid lines (\htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}). It is also possible to draw curvilinear axes with optional coordinate grids (\htmlref{AST\_GRID}{AST\_GRID}). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these routines. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot, using its \htmlref{Current}{Current} attribute. You may also set up clipping (see \htmlref{AST\_CLIP}{AST\_CLIP}) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in. Like any FrameSet, a Plot may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a Mapping, a Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST\_\_BAD). } \sstconstructor{ \htmlref{AST\_PLOT}{AST\_PLOT} } \sstdiytopic{ Inheritance }{ The Plot class inherits from the FrameSet class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all FrameSets, every Plot also has the following attributes: \sstitemlist{ \sstitem Abbrev: Abbreviate leading fields? \sstitem \htmlref{Border}{Border}: Draw a border around valid regions of a Plot? \sstitem \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary? \sstitem \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR? \sstitem \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element \sstitem \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot? \sstitem \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot? \sstitem \htmlref{Escape}{Escape}: Allow changes of character attributes within strings? \sstitem \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot \sstitem \htmlref{Font(element)}{Font(element)}: Character font for a Plot element \sstitem \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values \sstitem \htmlref{Grf}{Grf}: Select the graphics interface to use. \sstitem \htmlref{Grid}{Grid}: Draw grid lines for a Plot? \sstitem \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink? \sstitem \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot \sstitem \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot? \sstitem \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright? \sstitem \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot \sstitem \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values \sstitem \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically? \sstitem \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically? \sstitem \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot \sstitem \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot \sstitem \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot \sstitem \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot? \sstitem \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot \sstitem \htmlref{Size(element)}{Size(element)}: Character size for a Plot element \sstitem \htmlref{Style(element)}{Style(element)}: Line style for a Plot element \sstitem \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot? \sstitem \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot \sstitem \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot? \sstitem \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title \sstitem \htmlref{Tol}{Tol}: Plotting tolerance \sstitem \htmlref{Width(element)}{Width(element)}: Line width for a Plot element } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all FrameSets, the following routines may also be applied to all Plots: \sstitemlist{ \sstitem \htmlref{AST\_BBUF}{AST\_BBUF}: Begin a new graphical buffering context \sstitem \htmlref{AST\_BORDER}{AST\_BORDER}: Draw a border around valid regions of a Plot \sstitem \htmlref{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}: Returns a bounding box for previously drawn graphics \sstitem \htmlref{AST\_CLIP}{AST\_CLIP}: Set up or remove clipping for a Plot \sstitem \htmlref{AST\_CURVE}{AST\_CURVE}: Draw a geodesic curve \sstitem \htmlref{AST\_EBUF}{AST\_EBUF}: End the current graphical buffering context \sstitem \htmlref{AST\_GENCURVE}{AST\_GENCURVE}: Draw a generalized curve \sstitem \htmlref{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT}: Get the graphics context for a Plot \sstitem \htmlref{AST\_GRFPOP}{AST\_GRFPOP}: Retrieve previously saved graphics functions \sstitem \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH}: Save the current graphics functions \sstitem \htmlref{AST\_GRFSET}{AST\_GRFSET}: Register a graphics routine for use by the Plot class \sstitem \htmlref{AST\_GRID}{AST\_GRID}: Draw a set of labelled coordinate axes \sstitem \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}: Draw a grid line (or axis) for a Plot \sstitem \htmlref{AST\_MARK}{AST\_MARK}: Draw a set of markers for a Plot \sstitem \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}: Draw a series of connected geodesic curves \sstitem AST\_REGIONOUTLINE: Draw the outline of an AST \htmlref{Region}{Region} \sstitem \htmlref{AST\_TEXT}{AST\_TEXT}: Draw a text string for a Plot } } \sstdiytopic{ Graphical Elements }{ The colour index, character font, character size, line style and line width used for plotting can be set independently for various elements of the graphical output produced by a Plot. The different graphical elements are identified by appending the strings listed below as subscripts to the Plot attributes Colour(element), Font(element), Size(element), Style(element) and Width(element). These strings are case-insensitive and unambiguous abbreviations may be used. Elements of the graphical output which relate to individual axes can be referred to either independently (e.g. \texttt{"} (Grid1)\texttt{"} and \texttt{"} (Grid2)\texttt{"} ) or together (e.g. \texttt{"} (Grid)\texttt{"} ): \sstitemlist{ \sstitem Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using AST\_GRID \sstitem Axis1: Axis line drawn through tick marks on axis 1 using AST\_GRID \sstitem Axis2: Axis line drawn through tick marks on axis 2 using AST\_GRID \sstitem Border: The Plot border drawn using AST\_BORDER, AST\_GRID or AST\_REGIONOUTLINE \sstitem Curves: Geodesic curves drawn using AST\_CURVE, AST\_GENCURVE or AST\_POLYCURVE \sstitem Grid: Grid lines drawn using AST\_GRIDLINE or AST\_GRID \sstitem Grid1: Grid lines which cross axis 1, drawn using AST\_GRIDLINE or AST\_GRID \sstitem Grid2: Grid lines which cross axis 2, drawn using AST\_GRIDLINE or AST\_GRID \sstitem Markers: Graphical markers (symbols) drawn using AST\_MARK \sstitem NumLab: Numerical axis labels drawn using AST\_GRID \sstitem NumLab1: Numerical labels for axis 1 drawn using AST\_GRID \sstitem NumLab2: Numerical labels for axis 2 drawn using AST\_GRID \sstitem Strings: Text strings drawn using AST\_TEXT \sstitem TextLab: Descriptive axis labels drawn using AST\_GRID \sstitem TextLab1: Descriptive label for axis 1 drawn using AST\_GRID \sstitem TextLab2: Descriptive label for axis 2 drawn using AST\_GRID \sstitem Ticks: Tick marks (both major and minor) drawn using AST\_GRID \sstitem Ticks1: Tick marks (both major and minor) for axis 1 drawn using AST\_GRID \sstitem Ticks2: Tick marks (both major and minor) for axis 2 drawn using AST\_GRID \sstitem \htmlref{Title}{Title}: The Plot title drawn using AST\_GRID } } } \sstroutine{ Plot3D }{ Provide facilities for 3D graphical output }{ \sstdescription{ A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities for producing 3D graphical output, including fully annotated 3D coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional \texttt{"} graphical\texttt{"} coordinate system. The axes of this coordinate system are assumed to be right-handed (that is, if X appears horizontally to the right and Y vertically upwards, then Z is out of the screen towards the viewer), and are assumed to be equally scaled (that is, the same units are used to measure positions on each of the 3 axes). The upper and lower bounds of a volume within this graphical coordinate system is specified when the Plot3D is created, and all subsequent graphics are \texttt{"} drawn\texttt{"} in this volume. The Plot3D class does not itself include any ability to draw on a graphics device. Instead it calls upon function in an externally supplied module (the \texttt{"} grf3d\texttt{"} module) to do the required drawing. A module should be written that implements the functions of the grf3d interface using the facilities of a specific graphics system This module should then be linked into the application so that the Plot3D class can use its functions (see the description of the \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface defines a few simple functions for drawing primitives such as straight lines, markers and character strings. These functions all accept positions in the 3D graphics coordinate system (the base Frame of the Plot3D), and so the grf3d module must also manage the projection of these 3D coordinates onto the 2D viewing surface, including the choice of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"} position, direction of viewing, etc. The AST library includes a sample implementation of the grf3d interface based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This implementation also serves to document the grf3d interface itself and should be consulted for details before writing a new implementation. The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"} 3-dimensional coordinate system, which is the coordinate system in which plotting operations are specified when invoking the methods of the Plot3D class. The results of each plotting operation are automatically transformed into 3D graphical coordinates before being plotted using the facilities of the grf3d module linked into the application. Note, at least one of the three axes of the current Frame must be independent of the other two current Frame axes. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot3D, using its \htmlref{Current}{Current} attribute. Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation between 3D graphical coordinates (its base Frame) and 3D physical coordinates (its current Frame). Although the Plot3D class inherits from the Plot class, several of the facilities of the Plot class are not available in the Plot3D class, and an error will be reported if any attempt is made to use them. Specifically, the Plot3D class does not support clipping using the astClip function. \htmlref{AST\_CLIP}{AST\_CLIP} routine. Nor does it support the specification of graphics primitive functions at run-time using the \htmlref{AST\_GRFSET}{AST\_GRFSET}, \htmlref{AST\_GRFPOP}{AST\_GRFPOP}, \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH}, and \htmlref{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT} routines. } \sstconstructor{ \htmlref{AST\_PLOT3D}{AST\_PLOT3D} } \sstdiytopic{ Inheritance }{ The Plot3D class inherits from the Plot class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Plots, every Plot3D also has the following attributes: \sstitemlist{ \sstitem Norm: Normal vector defining the 2D plane used for text and markers \sstitem \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated. } Some attributes of the Plot class refer to specific physical coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic Plot, the axis index must be 1 or 2, but for a Plot3D the axis index can be 1, 2 or 3. Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation for details. All other Plot attributes can be set for a specific plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"} or \texttt{"} \_YZ\texttt{"} to the end of the Plot attribute name. For instance, \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"} refers to the \texttt{"} Grid\texttt{"} attribute for the plane spanning the second (Y) and third (Z) axes of the 3-d plot. } \sstdiytopic{ Functions }{ The Plot3D class does not define any new routines beyond those which are applicable to all Plots. Note, however, that the following methods inherited from the Plot class cannot be used with a Plot3D and will report an error if called: \sstitemlist{ \sstitem \htmlref{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}, AST\_CLIP, \htmlref{AST\_CURVE}{AST\_CURVE}, \htmlref{AST\_GENCURVE}{AST\_GENCURVE}, AST\_GETGRFCONTEXT, AST\_GRFPOP, AST\_GRFPUSH, AST\_GRFSET, \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}, \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}. } } } \sstroutine{ PointList }{ A collection of points in a Frame }{ \sstdescription{ The PointList class implements a \htmlref{Region}{Region} which represents a collection of points in a \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{AST\_POINTLIST}{AST\_POINTLIST} } \sstdiytopic{ Inheritance }{ The PointList class inherits from the Region class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every PointList also has the following attributes: \sstitemlist{ \sstitem \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList } } \sstdiytopic{ Functions }{ The PointList class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ PolyMap }{ Map coordinates using polynomial functions }{ \sstdescription{ A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, an iterative method can be used to evaluate the inverse based only on the forward transformation. } \sstconstructor{ \htmlref{AST\_POLYMAP}{AST\_POLYMAP} } \sstdiytopic{ Inheritance }{ The PolyMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every PolyMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation? \sstitem \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse \sstitem \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Objects, the following routines may also be applied to all Mappings: \sstitemlist{ \sstitem \htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}: Fit a PolyMap inverse or forward transformation } } } \sstroutine{ Polygon }{ A polygonal region within a 2-dimensional Frame }{ \sstdescription{ The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon. Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied). } \sstconstructor{ \htmlref{AST\_POLYGON}{AST\_POLYGON} } \sstdiytopic{ Inheritance }{ The Polygon class inherits from the \htmlref{Region}{Region} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every Polygon also has the following attributes: \sstitemlist{ \sstitem \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices? } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Regions, the following routines may also be applied to all Polygons: \sstitemlist{ \sstitem \htmlref{AST\_DOWNSIZE}{AST\_DOWNSIZE}: Reduce the number of vertices in a Polygon. \sstitem \htmlref{AST\_CONVEX$<$X$>$}{AST\_CONVEX$<$X$>$}: Create a Polygon giving the convex hull of a pixel array \sstitem \htmlref{AST\_OUTLINE$<$X$>$}{AST\_OUTLINE$<$X$>$}: Create a Polygon outlining values in a pixel array } } } \sstroutine{ Prism }{ An extrusion of a region into higher dimensions }{ \sstdescription{ A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region into one or more orthogonal dimensions (specified by another Region). If the Region to be extruded has N axes, and the Region defining the extrusion has M axes, then the resulting Prism will have (M$+$N) axes. A point is inside the Prism if the first N axis values correspond to a point inside the Region being extruded, and the remaining M axis values correspond to a point inside the Region defining the extrusion. As an example, a cylinder can be represented by extruding an existing \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the Interval would have a single axis and would specify the upper and lower limits of the cylinder along its length. } \sstconstructor{ \htmlref{AST\_PRISM}{AST\_PRISM} } \sstdiytopic{ Inheritance }{ The Prism class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Prism class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Prism class does not define any new routines beyond those which are applicable to all Regions. } } \sstroutine{ RateMap }{ Mapping which represents differentiation }{ \sstdescription{ A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created). A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation. } \sstconstructor{ \htmlref{AST\_RATEMAP}{AST\_RATEMAP} } \sstdiytopic{ Inheritance }{ The RateMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The RateMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The RateMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Region }{ Represents a region within a coordinate system }{ \sstdescription{ This class provides the basic facilities for describing a region within a specified coordinate system. However, the Region class does not have a constructor function of its own, as it is simply a container class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc, which implement Regions with particular shapes. All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region is created. This Frame describes the coordinate system in which the Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"} below. Constructors will also typically required one or more positions to be supplied which define the location and extent of the region. These positions must be supplied within the encapsulated Frame. The Region class inherits from the Frame class, and so a Region can be supplied where-ever a Frame is expected. In these cases, supplying a Region is equivalent to supplying a reference to its encapsulated Frame. Thus all the methods of the Frame class can be used on the Region class. For instance, the \htmlref{AST\_FORMAT}{AST\_FORMAT} routine may be used on a Region to format an axis value. In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort of Mapping. Transforming positions by supplying a Region to one of the AST\_TRAN$<$X$>$ routines is the way to determine if a given position is inside or outside the Region. When used as a Mapping, most classes of Frame are equivalent to a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a Region acts like a UnitMap only for input positions which are within the area represented by the Region. Input positions which are outside the area produce bad output values (i.e. the output values are equal to AST\_\_BAD). This behaviour is the same for both the forward and the inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"} is not a true inverse of the forward transformation, since applying the forward transformation to a point outside the Region, and then applying the inverse transformation results, in a set of AST\_\_BAD axis values rather than the original axis values. If required, the \htmlref{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS} function can be used to remove the \texttt{"} masking\texttt{"} effect of any Regions contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by replacing each Region with a UnitMap or equivalent Frame (depending on the context in which the Region is used). If the coordinate system represented by the Region is changed (by changing the values of one or more of the attribute which the Region inherits from its encapsulated Frame), the area represented by the Region is mapped into the new coordinate system. For instance, let\texttt{'} s say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being supplied to the constructor so that the Circle describes a circular area on the sky in FK4 equatorial coordinates. Since Region inherits from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then changed from FK4 to FK5, the circular area represented by the Region will automatically be mapped from the FK4 system into the FK5 system. In general, changing the coordinate system in this way may result in the region changing shape - for instance, a circle may change into an ellipse if the transformation from the old to the new coordinate system is linear but with different scales on each axis. Thus the specific class of a Region cannot be used as a guarantee of the shape in any particular coordinate system. If the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} routine is used on a Region, it will endeavour to return a new Region of a sub-class which accurately describes the shape in the current coordinate system of the Region (but this may not always be possible). It is possible to negate an existing Region so that it represents all areas of the encapsulated Frame except for the area specified when the Region was created. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Region class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every Region also has the following attributes: \sstitemlist{ \sstitem \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system? \sstitem \htmlref{Negated}{Negated}: Has the original region been negated? \sstitem \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region? \sstitem \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region \sstitem \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest \sstitem \htmlref{Bounded}{Bounded}: Is the Region bounded? } Every Region also inherits any further attributes that belong to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is inherited by any Region which represents a SkyFrame.) } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Frames, the following routines may also be applied to all Regions: \sstitemlist{ \sstitem \htmlref{AST\_GETREGIONBOUNDS}{AST\_GETREGIONBOUNDS}: Get the bounds of a Region \sstitem \htmlref{AST\_GETREGIONFRAME}{AST\_GETREGIONFRAME}: Get a copy of the Frame represent by a Region \sstitem \htmlref{AST\_GETREGIONFRAMESET}{AST\_GETREGIONFRAMESET}: Get a copy of the Frameset encapsulated by a Region \sstitem \htmlref{AST\_GETREGIONMESH}{AST\_GETREGIONMESH}: Get a mesh of points covering a Region \sstitem \htmlref{AST\_GETREGIONPOINTS}{AST\_GETREGIONPOINTS}: Get the positions that define a Region \sstitem \htmlref{AST\_GETUNC}{AST\_GETUNC}: Obtain uncertainty information from a Region \sstitem \htmlref{AST\_MAPREGION}{AST\_MAPREGION}: Transform a Region into a new coordinate system \sstitem \htmlref{AST\_NEGATE}{AST\_NEGATE}: Toggle the value of the Negated attribute \sstitem \htmlref{AST\_OVERLAP}{AST\_OVERLAP}: Determines the nature of the overlap between two Regions \sstitem \htmlref{AST\_MASK$<$X$>$}{AST\_MASK$<$X$>$}: Mask a region of a data grid \sstitem \htmlref{AST\_SETUNC}{AST\_SETUNC}: Associate a new uncertainty with a Region \sstitem \htmlref{AST\_SHOWMESH}{AST\_SHOWMESH}: Display a mesh of points on the surface of a Region } } } \sstroutine{ SelectorMap }{ A Mapping that locates positions within one of a set of alternate Regions }{ \sstdescription{ A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains a given input position. A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation. For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation. If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. In practice, SelectorMaps are often used in conjunction with SwitchMaps. } \sstconstructor{ \htmlref{AST\_SELECTORMAP}{AST\_SELECTORMAP} } \sstdiytopic{ Inheritance }{ The SelectorMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SelectorMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The SelectorMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ ShiftMap }{ Add a constant value to each coordinate }{ \sstdescription{ A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a specified constant value. } \sstconstructor{ \htmlref{AST\_SHIFTMAP}{AST\_SHIFTMAP} } \sstdiytopic{ Inheritance }{ The ShiftMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The ShiftMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The ShiftMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ SkyAxis }{ Store celestial axis information }{ \sstdescription{ The SkyAxis class is used to store information associated with a particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from \htmlref{AST\_WRITE}{AST\_WRITE}). } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The SkyAxis class inherits from the \htmlref{Axis}{Axis} class. } } \sstroutine{ SkyFrame }{ Celestial coordinate system description }{ \sstdescription{ A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or an \htmlref{Epoch}{Epoch}. For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified reference point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using \htmlref{AST\_FORMAT}{AST\_FORMAT}. For a SkyFrame, the Unit attribute describes the formatted value of a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a formatted axis value contains colon-separated fields for hours, minutes and seconds. On the other hand, the InternalUnit attribute for a SkyFrame is always set to \texttt{"} rad\texttt{"} (i.e. radians), indicating that the unformatted (i.e. floating point) axis values used by application code are always in units of radians } \sstconstructor{ \htmlref{AST\_SKYFRAME}{AST\_SKYFRAME} } \sstdiytopic{ Inheritance }{ The SkyFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every SkyFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system? \sstitem \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times? \sstitem \htmlref{Equinox}{Equinox}: Epoch of the mean equinox \sstitem IsLatAxis: Is the specified axis the latitude axis? \sstitem IsLonAxis: Is the specified axis the longitude axis? \sstitem \htmlref{LatAxis}{LatAxis}: Index of the latitude axis \sstitem \htmlref{LonAxis}{LonAxis}: Index of the longitude axis \sstitem \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]? \sstitem \htmlref{Projection}{Projection}: Sky projection description. \sstitem SkyRef: Position defining location of the offset coordinate system \sstitem \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system \sstitem SkyRefP: Position defining orientation of the offset coordinate system \sstitem \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Frames, the following routines may also be applied to all SkyFrames: \sstitemlist{ \sstitem \htmlref{AST\_SKYOFFSETMAP}{AST\_SKYOFFSETMAP}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates } } } \sstroutine{ SlaMap }{ Sequence of celestial coordinate conversions }{ \sstdescription{ An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems. When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the \htmlref{AST\_SLAADD}{AST\_SLAADD} routine, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. For details of the individual coordinate conversions available, see the description of the AST\_SLAADD routine. } \sstconstructor{ \htmlref{AST\_SLAMAP}{AST\_SLAMAP} (also see AST\_SLAADD) } \sstdiytopic{ Inheritance }{ The SlaMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SlaMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Mappings, the following routine may also be applied to all SlaMaps: \sstitemlist{ \sstitem \htmlref{AST\_SLAADD}{AST\_SLAADD}: Add a celestial coordinate conversion to an SlaMap } } } \sstroutine{ SpecFluxFrame }{ Compound spectrum/flux Frame }{ \sstdescription{ A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents spectral position and the second axis represents flux. } \sstconstructor{ \htmlref{AST\_SPECFLUXFRAME}{AST\_SPECFLUXFRAME} } \sstdiytopic{ Inheritance }{ The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class. } \sstdiytopic{ Attributes }{ The SpecFluxFrame class does not define any new attributes beyond those which are applicable to all CmpFrames. However, the attributes of the component Frames can be accessed as if they were attributes of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"} attribute and forward access requests to the component SpecFrame. An axis index can optionally be appended to the end of any attribute name, in which case the request to access the attribute will be forwarded to the primary Frame defining the specified axis. } \sstdiytopic{ Functions }{ The SpecFluxFrame class does not define any new routines beyond those which are applicable to all CmpFrames. } } \sstroutine{ SpecFrame }{ Spectral coordinate system description }{ \sstdescription{ A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, units, etc (see the description of the System attribute for details). By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute spectral values. } \sstconstructor{ \htmlref{AST\_SPECFRAME}{AST\_SPECFRAME} } \sstdiytopic{ Inheritance }{ The SpecFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every SpecFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system? \sstitem \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames \sstitem \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000) \sstitem \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000) \sstitem \htmlref{RestFreq}{RestFreq}: Rest frequency \sstitem \htmlref{SourceSys}{SourceSys}: Source velocity spectral system \sstitem \htmlref{SourceVel}{SourceVel}: Source velocity \sstitem \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame \sstitem \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values \sstitem \htmlref{StdOfRest}{StdOfRest}: Standard of rest } Several of the Frame attributes inherited by the SpecFrame class refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional, it allows these attributes to be specified without an axis index. So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Frames, the following routines may also be applied to all SpecFrames: \sstitemlist{ \sstitem \htmlref{AST\_SETREFPOS}{AST\_SETREFPOS}: Set reference position in any celestial system \sstitem \htmlref{AST\_GETREFPOS}{AST\_GETREFPOS}: Get reference position in any celestial system } } } \sstroutine{ SpecMap }{ Sequence of spectral coordinate conversions }{ \sstdescription{ A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard spectral coordinate systems. When an SpecMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{AST\_SPECADD}{AST\_SPECADD} routine, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of a set of building blocks. Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output), but modifies axis 1 values (the spectral axis) appropriately. For details of the individual coordinate conversions available, see the description of the AST\_SPECADD routine. } \sstconstructor{ \htmlref{AST\_SPECMAP}{AST\_SPECMAP} (also see AST\_SPECADD) } \sstdiytopic{ Inheritance }{ The SpecMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SpecMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Mappings, the following routine may also be applied to all SpecMaps: \sstitemlist{ \sstitem \htmlref{AST\_SPECADD}{AST\_SPECADD}: Add a spectral coordinate conversion to an SpecMap } } } \sstroutine{ SphMap }{ Map 3-d Cartesian to 2-d spherical coordinates }{ \sstdescription{ A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors). } \sstconstructor{ \htmlref{AST\_SPHMAP}{AST\_SPHMAP} } \sstdiytopic{ Inheritance }{ The SphMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every SphMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere? \sstitem \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole } } \sstdiytopic{ Functions }{ The SphMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Stc }{ Represents an instance of the IVOA STC class }{ \sstdescription{ The Stc class is an implementation of the IVOA STC class which forms part of the IVOA Space-Time Coordinate Metadata system. See: http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html The Stc class does not have a constructor function of its own, as it is simply a container class for a family of specialised sub-classes including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation} and \htmlref{StcObsDataLocation}{StcObsDataLocation}. } \sstconstructor{ AST\_STC } \sstdiytopic{ Inheritance }{ The Stc class inherits from the \htmlref{Region}{Region} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every Stc also has the following attributes: \sstitemlist{ \sstitem \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region. } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Regions, the following routines may also be applied to all Stc\texttt{'} s: \sstitemlist{ \sstitem \htmlref{AST\_GETSTCREGION}{AST\_GETSTCREGION}: Get a pointer to the encapsulated Region \sstitem \htmlref{AST\_GETSTCCOORD}{AST\_GETSTCCOORD}: Get information about an AstroCoords element \sstitem \htmlref{AST\_GETSTCNCOORD}{AST\_GETSTCNCOORD}: Returns the number of AstroCoords elements in an Stc } } } \sstroutine{ StcCatalogEntryLocation }{ Correspond to the IVOA STCCatalogEntryLocation class }{ \sstdescription{ The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{AST\_STCCATALOGENTRYLOCATION}{AST\_STCCATALOGENTRYLOCATION} } \sstdiytopic{ Inheritance }{ The StcCatalogEntryLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcCatalogEntryLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcCatalogEntryLocation class does not define any new routines beyond those which are applicable to all Stcs. } } \sstroutine{ StcObsDataLocation }{ Correspond to the IVOA ObsDataLocation class }{ \sstdescription{ The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coordinate space occupied by a particular observational dataset. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html An STC ObsDataLocation element specifies the extent of the observation within a specified coordinate system, and also specifies the observatory location within a second coordinate system. The AST StcObsDataLocation class inherits from Stc, and therefore an StcObsDataLocation can be used directly as an Stc. When used in this way, the StcObsDataLocation describes the location of the observation (not the observatory). Eventually, this class will have a method for returning an Stc describing the observatory location. However, AST currently does not include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar system positions. Therefore, the provision for returning observatory location as an Stc is not yet available. However, for terrestrial observations, the position of the observatory can still be recorded using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated within the Stc representing the observation location (this assumes the observatory is located at sea level). } \sstconstructor{ \htmlref{AST\_STCOBSDATALOCATION}{AST\_STCOBSDATALOCATION} } \sstdiytopic{ Inheritance }{ The StcObsDataLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcObsDataLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcObsDataLocation class does not define any new routines beyond those which are applicable to all Stcs. } } \sstroutine{ StcResourceProfile }{ Correspond to the IVOA STCResourceProfile class }{ \sstdescription{ The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{AST\_STCRESOURCEPROFILE}{AST\_STCRESOURCEPROFILE} } \sstdiytopic{ Inheritance }{ The StcResourceProfile class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcResourceProfile class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcResourceProfile class does not define any new routines beyond those which are applicable to all Stcs. } } \sstroutine{ StcSearchLocation }{ Correspond to the IVOA SearchLocation class }{ \sstdescription{ The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of a query. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{AST\_STCSEARCHLOCATION}{AST\_STCSEARCHLOCATION} } \sstdiytopic{ Inheritance }{ The StcSearchLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcSearchLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcSearchLocation class does not define any new routines beyond those which are applicable to all Stcs. } } \sstroutine{ StcsChan }{ I/O Channel using STC-S to represent Objects }{ \sstdescription{ A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description. When an STC-S description is read using \htmlref{AST\_READ}{AST\_READ}, the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC AstroCoords (i.e. a single point of interest within the coordinate frame described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC AstrCoordsArea (i.e. an area or volume of interest within the coordinate frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap} containing the uninterpreted property values read form the STC-S description, or 4) a KeyMap containing any combination of the first 3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} control which of the above is returned by AST\_READ. When an STC-S description is created from an AST Object using AST\_WRITE, the AST Object must be either a Region or a KeyMap. If it is a Region, it is assumed to define the AstroCoordsArea or (if the Region is a single point) the AstroCoords to write to the STC-S description. If the Object is a KeyMap, it may contain an entry with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} , holding a Region (a PointList) to be used to create the AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding a KeyMap that contains uninterpreted property values to be used as defaults for any STC-S properties that are not determined by the other supplied Regions. In addition, a KeyMap supplied to AST\_WRITE may itself hold the default STC-S properties (rather than defaults being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"} entry in the supplied KeyMap). The AST\_READ and AST\_WRITE functions work together so that any Object returned by AST\_READ can immediately be re-written using AST\_WRITE. Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting text. These routines should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such routines are supplied, a Channel will read from standard input and write to standard output. Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. Support for STC-S is currently based on the IVOA document \texttt{"} STC-S: Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} , version 1.30 (dated 5th December 2007), available at http://www.ivoa.net/Documents/latest/STC-S.html. Note, this document is a recommednation only and does not constitute an accepted IVOA standard. The full text of version 1.30 is supported by the StcsChan class, with the following exceptions and provisos: \sstitemlist{ \sstitem When reading an STC-S phrase, case is ignored except when reading units strings. \sstitem There is no support for multiple intervals specified within a TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval. \sstitem If the ET timescale is specified, TT is used instead. \sstitem If the TEB timescale is specified, TDB is used instead. \sstitem The LOCAL timescale is not supported. \sstitem The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a reference position to be specified. Consequently, any $<$refpos$>$ specified within the Time or Space sub-phrase of an STC-S document is ignored. \sstitem The Convex identifier for the space sub-phrase is not supported. \sstitem The GEO\_C and GEO\_D space frames are not supported. \sstitem The UNITSPHERE and SPHER3 space flavours are not supported. \sstitem If any Error values are supplied in a space sub-phrase, then the number of values supplied should equal the number of spatial axes, and the values are assumed to specify an error box (i.e. error circles, ellipses, etc, are not supported). \sstitem The spectral and redshift sub-phrases do not support the following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos, EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO. \sstitem Error values are supported but error ranges are not. \sstitem Resolution, PixSize and Size values are ignored. \sstitem Space velocity sub-phrases are ignored. } } \sstconstructor{ \htmlref{AST\_STCSCHAN}{AST\_STCSCHAN} } \sstdiytopic{ Inheritance }{ The StcsChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every StcsChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S? \sstitem \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S? \sstitem \htmlref{StcsLength}{StcsLength}: Controls output buffer length \sstitem \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S? } } \sstdiytopic{ Functions }{ The StcsChan class does not define any new routines beyond those which are applicable to all Channels. } } \sstroutine{ SwitchMap }{ A Mapping that encapsulates a set of alternate Mappings }{ \sstdescription{ A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap. A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input. When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST\_\_BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position. When the SwitchMap is used to transform a position in the inverse direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is set to a value of AST\_\_BAD on every axis. In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly appropriate for this purpose. If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. } \sstconstructor{ \htmlref{AST\_SWITCHMAP}{AST\_SWITCHMAP} } \sstdiytopic{ Inheritance }{ The SwitchMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SwitchMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The SwitchMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ Table }{ A 2-dimensional table of values }{ \sstdescription{ The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional table of values. The AST\_MAPGET... and AST\_MAPPUT... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the upper-case name of a table column and \texttt{"} i\texttt{"} is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table. Columns must be declared using the \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN} method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape, as specified when the column is added to the Table. Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER} method before being accessed. Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables. } \sstconstructor{ \htmlref{AST\_TABLE}{AST\_TABLE} } \sstdiytopic{ Inheritance }{ The Table class inherits from the KeyMap class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all KeyMaps, every Table also has the following attributes: \sstitemlist{ \sstitem \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column \sstitem \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column \sstitem \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column \sstitem \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column \sstitem ColumnUnit(column): The unit string describing each value in a column \sstitem \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table \sstitem \htmlref{Nrow}{Nrow}: The number of rows currently in the Table \sstitem \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table } } \sstdiytopic{ Functions }{ In addition to those routines applicable to all KeyMaps, the following routines may also be applied to all Tables: \sstitemlist{ \sstitem \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}: Add a new column definition to a Table \sstitem \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}: Add a new global parameter definition to a Table \sstitem \htmlref{AST\_COLUMNNAME}{AST\_COLUMNNAME}: Return the name of the column with a given index \sstitem \htmlref{AST\_COLUMNSHAPE}{AST\_COLUMNSHAPE}: Return the shape of the values in a named column \sstitem \htmlref{AST\_HASCOLUMN}{AST\_HASCOLUMN}: Checks if a column exists in a Table \sstitem \htmlref{AST\_HASPARAMETER}{AST\_HASPARAMETER}: Checks if a global parameter exists in a Table \sstitem \htmlref{AST\_PARAMETERNAME}{AST\_PARAMETERNAME}: Return the name of the parameter with a given index \sstitem \htmlref{AST\_PURGEROWS}{AST\_PURGEROWS}: Remove all empty rows from a Table \sstitem \htmlref{AST\_REMOVECOLUMN}{AST\_REMOVECOLUMN}: Remove a column from a Table \sstitem \htmlref{AST\_REMOVEPARAMETER}{AST\_REMOVEPARAMETER}: Remove a global parameter from a Table \sstitem \htmlref{AST\_REMOVEROW}{AST\_REMOVEROW}: Remove a row from a Table } } } \sstroutine{ TimeFrame }{ Time coordinate system description }{ \sstdescription{ A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions in time. A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame representing time offsets from the specified zero point. Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years. The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that is, the physical process used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales. When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute). } \sstconstructor{ \htmlref{AST\_TIMEFRAME}{AST\_TIMEFRAME} } \sstdiytopic{ Inheritance }{ The TimeFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every TimeFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames \sstitem \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours. \sstitem \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values \sstitem \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame } Several of the Frame attributes inherited by the TimeFrame class refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional, it allows these attributes to be specified without an axis index. So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Frames, the following routines may also be applied to all TimeFrames: \sstitemlist{ \sstitem \htmlref{AST\_CURRENTTIME}{AST\_CURRENTTIME}: Return the current system time } } } \sstroutine{ TimeMap }{ Sequence of time coordinate conversions }{ \sstdescription{ A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard time coordinate systems. When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{AST\_TIMEADD}{AST\_TIMEADD} routine, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks. For details of the individual coordinate conversions available, see the description of the AST\_TIMEADD routine. } \sstconstructor{ \htmlref{AST\_TIMEMAP}{AST\_TIMEMAP} (also see AST\_TIMEADD) } \sstdiytopic{ Inheritance }{ The TimeMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The TimeMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those routines applicable to all Mappings, the following routine may also be applied to all TimeMaps: \sstitemlist{ \sstitem \htmlref{AST\_TIMEADD}{AST\_TIMEADD}: Add a time coordinate conversion to an TimeMap } } } \sstroutine{ TranMap }{ Mapping with specified forward and inverse transformations }{ \sstdescription{ A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist). When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed. } \sstconstructor{ \htmlref{AST\_TRANMAP}{AST\_TRANMAP} } \sstdiytopic{ Inheritance }{ The TranMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The TranMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The TranMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ UnitMap }{ Unit (null) Mapping }{ \sstdescription{ A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the coordinates supplied to it. They are simply copied. This can be useful if a Mapping is required (e.g. to pass to another routine) but you do not want it to have any effect. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and are specified when it is created. } \sstconstructor{ \htmlref{AST\_UNITMAP}{AST\_UNITMAP} } \sstdiytopic{ Inheritance }{ The UnitMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The UnitMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The UnitMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ UnitNormMap }{ Convert a vector to a unit vector and its norm, relative to a specified centre }{ \sstdescription{ The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm. The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. UnitNormMap enables radially symmetric transformations, as follows: \sstitemlist{ \sstitem apply a UnitNormMap to produce a unit vector and norm (radius) \sstitem apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged \sstitem apply the same UnitNormMap in the inverse direction to produce the result } } \sstconstructor{ \htmlref{AST\_UNITNORMMAP}{AST\_UNITNORMMAP} } \sstdiytopic{ Inheritance }{ The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class. } \sstdiytopic{ Attributes }{ The UnitNormMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The UnitNormMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ WcsMap }{ Implement a FITS-WCS sky projection }{ \sstdescription{ This class is used to represent sky coordinate projections as described in the FITS world coordinate system (FITS-WCS) paper II \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"} by M. Calabretta and E.W. Griesen. This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa). A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection plane\texttt{"} coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} . These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS). The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be associated with each axis. These specify the precise form of the projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is the integer axis index (starting at 1), and m is an integer \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper. } \sstconstructor{ \htmlref{AST\_WCSMAP}{AST\_WCSMAP} } \sstdiytopic{ Inheritance }{ The WcsMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every WcsMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection \sstitem \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection \sstitem \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters \sstitem PVMax: Maximum number of FITS-WCS projection parameters \sstitem \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes \sstitem \htmlref{WcsType}{WcsType}: FITS-WCS projection type } } \sstdiytopic{ Functions }{ The WcsMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ WinMap }{ Map one window on to another by scaling and shifting each axis }{ \sstdescription{ A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes). A WinMap is specified by giving the coordinates of two opposite corners (A and B) of the window in both the input and output coordinate systems. } \sstconstructor{ \htmlref{AST\_WINMAP}{AST\_WINMAP} } \sstdiytopic{ Inheritance }{ The WinMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The WinMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The WinMap class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ XmlChan }{ I/O Channel using XML to represent Objects }{ \sstdescription{ A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O operations. Writing an \htmlref{Object}{Object} to an XmlChan (using \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description. Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} routines which connect it to an external data store by reading and writing the resulting XML text. These routines should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such routines are supplied, a Channel will read from standard input and write to standard output. Alternatively, an XmlChan can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstconstructor{ \htmlref{AST\_XMLCHAN}{AST\_XMLCHAN} } \sstdiytopic{ Inheritance }{ The XmlChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every XmlChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML \sstitem \htmlref{XmlLength}{XmlLength}: Controls output buffer length \sstitem \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing } } \sstdiytopic{ Functions }{ The XmlChan class does not define any new routines beyond those which are applicable to all Mappings. } } \sstroutine{ ZoomMap }{ Zoom coordinates about the origin }{ \sstdescription{ The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"} transformation by multiplying all coordinate values by the same scale factor (the inverse transformation is performed by dividing by this scale factor). The number of coordinate values representing each point is unchanged. } \sstconstructor{ \htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} } \sstdiytopic{ Inheritance }{ The ZoomMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every ZoomMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Zoom}{Zoom}: ZoomMap scale factor } } \sstdiytopic{ Functions }{ The ZoomMap class does not define any new routines beyond those which are applicable to all Mappings. } } \normalsize \cleardoublepage \section{\label{ss:commanddescriptions}UNIX Command Descriptions} The commands described here are provided for use from the UNIX shell to assist with developing software which uses AST. To use these commands, you should ensure that the directory ``/star/bin''\footnote{Or the equivalent directory if AST is installed in a non-standard location.} is on your PATH. \small \sstroutine{ ast\_link }{ Link a program with the AST library }{ \sstdescription{ This command should be used when building programs which use the AST library, in order to generate the correct arguments to allow the compiler to link your program. The arguments generated are written to standard output but may be substituted into the compiler command line in the standard UNIX way using backward quotes (see below). By default, it is assumed that you are building a stand-alone program which does not produce graphical output. However, switches are provided for linking other types of program. } \sstinvocation{ f77 program.f -L/star/lib `ast\_link [switches]` -o program } \sstexamples{ \sstexamplesubsection{ f77 display.f -L/star/lib `ast\_link -pgplot` -o display }{ Compiles and links a Fortran program called ``display\texttt{'} \texttt{'} which uses the standard version of PGPLOT for graphical output. } \sstexamplesubsection{ f77 plotit.f -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit }{ Compiles and links a Fortran program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } \sstexamplesubsection{ f77 plotit.f -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit }{ Compiles and links a Fortran program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } } \sstdiytopic{ Switches }{ The following switches may optionally be given to this command to modify its behaviour: \sstitemlist{ \sstitem ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages produced by the AST library are delivered via the Starlink EMS (Error Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default, error messages are simply written to standard error. \sstitem ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages produced by the AST library are delivered via the DRAMA Ers (Error Reporting Service) library. By default, error messages are simply written to standard error. \sstitem ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 2D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new graphics system yourself and wish to provide your own arguments for linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in that it assumes that your graphics module implements the complete interface required by the current version of AST. If future versions of AST introduce new functions to the graphics interface, this switch will cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you that you need to implement new functions in your graphics module. To avoid such errors, you can use one of the other, version-specific, switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time errors to be reported if any AST function is invoked which requires facilities not in the implemented interface. \sstitem ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. It indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V2.0 of AST. \sstitem ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V3.2 of AST. \sstitem ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V5.6 of AST. \sstitem ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how error messages produced by the AST library should be delivered. You should use this option only if you have implemented an interface to a new error delivery system yourself and wish to provide your own arguments for linking with it. \sstitem ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, but is retained in order to allow applications to be linked with a graphics module which implements the 2D interface used by AST V2.0. It is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. \sstitem ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 2D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 2D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 3D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new 3D graphics system yourself and wish to provide your own arguments for linking with it. \sstitem ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. } } \sstdiytopic{ ERFA \& PAL }{ The AST distribution includes bundled copies of the ERFA and PAL libraries. These will be used for fundamental positional astronomy calculations unless the \texttt{"} --with-external\_pal\texttt{"} option was used when AST was configured. If \texttt{"} --with-external\_pal\texttt{"} is used, this script will include \texttt{"} -lpal\texttt{"} in the returned list of linking options, and the user should then ensure that external copies of the PAL and ERFA libraries are available (ERFA functions are used within PAL). } } \sstroutine{ ast\_link\_adam }{ Link an ADAM program with the AST library }{ \sstdescription{ This command should only be used when building Starlink ADAM programs which use the AST library, in order to generate the correct arguments to allow the ADAM ``alink\texttt{'} \texttt{'} command to link the program. The arguments generated are written to standard output but may be substituted into the ``alink\texttt{'} \texttt{'} command line in the standard UNIX way using backward quotes (see below). By default, it is assumed that you are building an ADAM program which does not produce graphical output. However, switches are provided for linking other types of program. This command should not be used when building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'} command instead. } \sstinvocation{ alink program.f -L/star/lib `ast\_link\_adam [switches]` } \sstexamples{ \sstexamplesubsection{ alink display.f -L/star/lib `ast\_link\_adam -pgplot` }{ Compiles and links an ADAM Fortran program called ``display\texttt{'} \texttt{'} which uses the standard version of PGPLOT for graphical output. } \sstexamplesubsection{ alink plotit.f -L. -L/star/lib `ast\_link\_adam -grf` -lgrf }{ Compiles and links an ADAM Fortran program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } \sstexamplesubsection{ alink plotit.f -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf }{ Compiles and links an ADAM Fortran program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } } \sstdiytopic{ Switches }{ The following switches may optionally be given to this command to modify its behaviour: \sstitemlist{ \sstitem ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 2D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new graphics system yourself and wish to provide your own arguments for linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in that it assumes that your graphics module implements the complete interface required by the current version of AST. If future versions of AST introduce new functions to the graphics interface, this switch will cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you that you need to implement new functions in your graphics module. To avoid such errors, you can use one of the other, version-specific, switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time errors to be reported if any AST function is invoked which requires facilities not in the implemented interface. \sstitem ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. It indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V2.0 of AST. \sstitem ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V3.2 of AST. \sstitem ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V5.6 of AST. \sstitem ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how error messages produced by the AST library should be delivered. You should use this option only if you have implemented an interface to a new error delivery system yourself and wish to provide your own arguments for linking with it. By default, error messages are delivered in the standard ADAM way via the EMS Error Message Service (Starlink \htmlref{System}{System} Note SSN/4). \sstitem ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, but is retained in order to allow applications to be linked with a graphics module which implements the interface used by AST V2.0. It is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. \sstitem ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 3D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new 3D graphics system yourself and wish to provide your own arguments for linking with it. \sstitem ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. } } \sstdiytopic{ SLALIB }{ The AST distribution includes a cut down subset of the C version of the SLALIB library written by Pat Wallace. This subset contains only the functions needed by the AST library. It is built as part of the process of building AST and is distributed under GPL (and is thus compatible with the AST license). Previous version of this script allowed AST applications to be linked against external SLALIB libraries (either Fortran or C) rather than the internal version. The current version of this script does not provide this option, and always uses the internal SLALIB library. However, for backward compatibility, this script still allows the \texttt{"} -fsla\texttt{"} and \texttt{"} -csla\texttt{"} flags (previously used for selecting which version of SLALIB to use) to be specified, but they will be ignored. } } \normalsize \newpage \section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage} This appendix gives details of the \htmlref{FitsChan}{FitsChan} class implementation of the conventions described in the FITS-WCS papers available at \url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan has the value ``FITS-WCS'' (whether set explicitly or defaulted). It should always be possible for a \htmlref{FrameSet}{FrameSet} to be read (using the \htmlref{AST\_READ}{AST\_READ} function) from a FitsChan containing a header which conforms to these conventions. However, only those FrameSets which are compatible with the FITS-WCS model can be \emph{written} to a FitsChan using the \htmlref{AST\_WRITE}{AST\_WRITE} function. For instance, if the current \htmlref{Frame}{Frame} of a FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{MathMap} then the FrameSet will no longer be compatible with the FITS-WCS model, and so will not be written out successfully to a FitsChan. The following sub-sections describe the details of the implementation of each of the first four FITS-WCS papers. Here, the term ``pixel axes'' is used to refer to the FITS pixel coordinates (i.e. the centre of the first image pixel has a value 1.0 on each pixel axis); the term ``IWC axes'' is used to refer to the axes of the Intermediate World Coordinate system; and the term ``WCS axes'' is used to refer to the axes of the final physical coordinate system described by the CTYPE\emph{i} keywords. \subsection{Paper I - General Linear Coordinates} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} keyword values within the FitsChan do not conform to the conventions described in later papers, in which case the axes are assumed to be linear. When writing a FrameSet to a FitsChan, these conventions are used for axes which are described by a simple \htmlref{Frame}{Frame} (\emph{i.e.} not a \htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}). \htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword defined by FITS-WCS paper I. \begin{table}[htbp] \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS Frame - only written if different to NAXIS.} \fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference Point'' below).} \fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always written (see ``Choice of Reference Point'' below).} \fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is set to zero.} \fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only written in FITS-AIPS and FITS-AIPS++ encodings.} \fitskey{CTYPE\emph{ia}}{Used to choose the class and attributes of the WCS Frame, and to create the pixel to WCS Mapping (note, ``STOKES'' and ``COMPLEX'' axes are treated as unknown linear axes).}{Always written (see ``Use and Choice of CTYPE keywords'' below).} \fitskey{CUNIT\emph{ia}}{Used to set the Units attributes of the WCS Frame.}{Only written if the Units attribute of the WCS Frame has been set explicitly. If so, the Units value for each axis is used as the CUNIT value.} \fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to zero.} \fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to a non-zero value.} \fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes are linear.} \fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.} \fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{Domain} attribute of the WCS Frame.}{Only written if the Domain attribute of the WCS Frame has been set explicitly. If so, the Domain value is used as the WCSNAME value.} \fitskey{CRDER\emph{ia}}{Ignored.}{Not used.} \fitskey{CSYER\emph{ia}}{Ignored.}{Not used.} \hline \end{tabular} \vspace{3.mm} \caption{Use of FITS-WCS Paper I keywords} \label{tab:fitspaper1} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan}, success depends on the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the WCS Frame being linear. The write operation will fail if this is not the case. \subsubsection{Use and Choice of CTYPE\emph{i} keywords} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from the CNAME\emph{i} keywords, if present in the header. Otherwise they are set from the CTYPE\emph{i} comments strings in the header, so long as each axis has a unique non-blank comment. Otherwise, the Label attributes are set to the CTYPE\emph{i} values. The above procedure is over-ridden if the axis types conform to the conventions described in paper II or III, as described below. When writing a FrameSet to a FitsChan, each CTYPE\emph{i} value is set to the value of the Symbol attribute of the corresponding axis in the Frame being written. If a value has been set explicitly for the axis Label attribute, it is used as the axis comment (except that any existing comments in the FitsChan take precedence if the keyword value has not changed). The above procedure is over-ridden if the Frame is a \htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which case the CTYPE\emph{i} value is derived from the \htmlref{System}{System} attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping} according to the conventions of papers II and III, as described below. \subsubsection{Choice of Reference Point} When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, the pixel coordinates of the reference point for linear axes (i.e. the CRPIX\emph{j} values) are chosen as follows: \begin{itemize} \item If the FrameSet is being written to a FitsChan which previously contained a set of axis descriptions with the same identifying letter, then the previous CRVAL\emph{j}values are converted into the coordinate system of the \htmlref{Frame}{Frame} being written (if possible). These values are then transformed into the pixel Frame, and the closest integer pixel values are used as the CRPIX keywords. \item If the above step could not be performed for any reason, the central pixel is used as the reference point. This requires the image dimensions to be present in the FitsChan in the form of a set of NAXIS\emph{j} keyword values. \item If both the above two steps failed for any axis, then the pixel reference position is set to a value of 1.0 on the pixel axis. \end{itemize} The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding CRVAL\emph{j}values. Again, the above procedure is over-ridden if the Frame is a \htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which case the conventions of papers II and III are used as described below. \subsubsection{Choice of Axis Ordering} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current \htmlref{Frame}{Frame} of the resulting FrameSet corresponds to axis $i$ in the FITS header. When writing a FrameSet to a FitsChan, the axis ordering for the FITS header is chosen to make the CD\emph{i\_j} or PC\emph{i\_j} matrix predominately diagonal. This means that the axis numbering in the FITS header will not necessarily be the same as that in the AST Frame. \subsubsection{Alternate Axis Descriptions} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions, each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added to the final FrameSet, connected via an appropriate \htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{Ident} attribute of the Frame is set to hold the single alphabetical character which is used to identify the set of axis descriptions within the FITS header (a single space is used for the primary axis descriptions). When writing a FrameSet to a FitsChan, it is assumed that the base Frame represents pixel coordinates, and the current Frame represents the primary axis descriptions. If there are any other Frames present in the FrameSet, an attempt is made to create a complete set of ``alternate'' set of keywords describing each additional Frame. The first character in the Ident attribute of the Frame is used as the single character descriptor to be appended to the keyword, with the proviso that a given character can only be used once. If a second Frame is found with an Ident attribute which has already been used, its Ident attribute is ignored and the next free character is used instead. Note, failure to write a set of alternate axis descriptions does not result in failure of the entire write operation: the primary axis descriptions are still written, together with any other alternate axis descriptions which can be produced successfully. \subsection{Paper II - Celestial Coordinates} These conventions are used when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i} values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame}. \htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper II. \begin{table}[htbp] \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types listed in paper II are supported (note, ``CUBEFACE'' axes are treated as unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar HEALPix) are supported.}{Determined by the \htmlref{System}{System} attribute of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the \htmlref{WcsMap}{WcsMap} within the FrameSet.} \fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.} \fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values are stored as attributes of a WcsMap within this Mapping).}{Values are obtained from the WcsMap in the pixel to WCS Mapping.} \fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also stored as a \htmlref{PVi\_m}{PVi\_m} attribute for the longitude axis of the WcsMap.}{Only written if not equal to the default value defined in paper II (see ``Choice of LONPOLE/LATPOLE'' below).} \fitskey{LATPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also stored as a PV attribute for the longitude axis of the WcsMap.}{Only written if not equal to the default value defined in paper II (see ``Choice of LONPOLE/LATPOLE'' below).} \fitskey{RADESYS\emph{a}}{Used to set the attributes of the SkyFrame. All values supported except that ecliptic coordinates are currently always assumed to be FK5.}{Always written. Determined by the System attribute of the SkyFrame.} \fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of the SkyFrame.} \fitskey{EPOCH}{Used to set the Equinox attribute of the SkyFrame.}{Only written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute of the SkyFrame.} \fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{Epoch} attribute of the SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on RADESYS and EQUINOX is used if used if DATE-OBS is not present either.}{Determined by the Epoch attribute of the SkyFrame. Only written if this attribute has been set to an explicit value (in which case DATE-OBS is also written).} \hline \end{tabular} \vspace{3.mm} \caption{Use of FITS-WCS Paper II keywords} \label{tab:fitspaper2} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a \htmlref{FitsChan}{FitsChan}, success depends on the following conditions being met: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}. \item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear. \item The Mapping after the WcsMap (\emph{i.e.} from native spherical to celestial coordinates) is a spherical rotation for the celestial axes, and linear for any other axes. \item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan, and the longitude and latitude axes are separable. In this case the Mapping will be described by a pair of 1-dimensional look-up tables, using the ``-TAB'' algorithm described in FITS-WCS paper III. \end{enumerate} If none of the above conditions hold, the write operation will be unsuccessful. \subsubsection{Choice of LONPOLE/LATPOLE} When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, the choice of LONPOLE and LATPOLE values is determined as follows: \begin{enumerate} \item If the projection represented by the \htmlref{WcsMap}{WcsMap} is azimuthal, then any values set for attributes ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis) within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a FrameSet from a FITS-WCS header results in the original LONPOLE and LATPOLE values being stored within a WcsMap within the FrameSet. Consequently, if a FrameSet is read from a FITS-WCS header and it is subsequently written out to a new FITS-WCS header, the original LONPOLE and LATPOLE values will usually be used in the new header (the exception being if the WcsMap has been explicitly modified before being written out again). Any extra rotation of the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is possible only if the projection is azimuthal). \item If the projection represented by the WcsMap is azimuthal but no values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' attributes within the WcsMap, then the default LONPOLE and LATPOLE values are used. This results in no LONPOLE or LATPOLE keywords being stored in the header since default values are never stored. Any extra rotation of the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is possible only if the projection is azimuthal). \item If the projection represented by the WcsMap is not azimuthal, then the values of LONPOLE and LATPOLE are found by transforming the coordinates of the celestial north pole (\emph{i.e} longitude zero, latitude $+\pi/2$) into native spherical coordinates using the inverse of the \htmlref{Mapping}{Mapping} which follows the WcsMap. \end{enumerate} \subsubsection{User Defined Fiducial Points} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis ``\emph{i}'') are used to indicate a user-defined fiducial point as described in section 2.5 of paper II. This results in a shift of IWC origin being applied \emph{before} the \htmlref{WcsMap}{WcsMap} which converts IWC into native spherical coordinates. The values of these projection parameters, if supplied, are stored as the corresponding \htmlref{PVi\_m}{PVi\_m} attributes of the WcsMap. When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap determine the native coordinates of the fiducial point (the fixed defaults for each projection described in paper II are used if the PV attributes of the WcsMap have not been assigned a value). The corresponding celestial coordinates are used as the CRVAL\emph{i} keywords and the corresponding pixel coordinates as the CRPIX\emph{j} keywords. \subsubsection{Common Non-Standard Features} A collection of common non-standard features are supported when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, in addition to those embodied within the available encodings of the FitsChan class. These are translated into the equivalent standard features before being used to create a FrameSet. Note, the reverse operation is never performed: it is not possible to produce non-standard features when writing a FrameSet to a FitsChan (other than those embodied in the available encodings of the FitsChan class). The supported non-standard features include: \begin{itemize} \item EQUINOX keywords with string values equal to a date preceded by the letter B or J (\emph{e.g.} ``B1995.0''). \item EQUINOX or EPOCH keywords with value zero (these are converted to B1950). \item The IRAF ``ZPX'' projection is represented by a \htmlref{WcsMap}{WcsMap} with type of AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn} keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic ZPN projection by including ``lngcor'' or ``latcor'' terms. These are supported if they use half cross-terms, in either simple or Chebyshev representation. \item The IRAF ``TNX'' projection is represented by a WcsMap with type of AST\_\_TPN (a distorted TAN projection retained within the WcsMap class from an early draft of the FITS-WCS paper II). Projection parameter values are read from any WAT\emph{i\_nnn} keywords, and corresponding PV attributes are set in the WcsMap. If the TNX projection cannot be converted exactly into an AST\_\_TPN projection, ASTWARN keywords are added to the FitsChan containing a warning message (but only if the \htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently, TNX projections that use half cross-terms, in either simple or Chebyshev representation, are supported. \item ``QV'' parameters for TAN projections (as produced by \xref{AUTOASTROM}{sun242}{} \footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}} are renamed to the equivalent ``PV'' parameters. \item TAN projections that have associated ``PV'' parameters on the latitude axis are converted to the corresponding TPN (distorted TAN) projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute of the FitsChan class. \end{itemize} \subsection{Paper III - Spectral Coordinates} These conventions are used when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which includes appropriate CTYPE\emph{i} values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}. \htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper III. \begin{table}[htbp] \begin{footnotesize} \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types listed in paper III are supported algorithm (the ``-LOG'' algorithm may also be applied to non-spectral linear axes; the ``-TAB'' algorithm requires the \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the SpecFrame and the nature of the pixel to SpecFrame \htmlref{Mapping}{Mapping}.} \fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of the SpecFrame (note, SpecFrames always have an ``active'' Units attribute (see astSetActiveUnit).}{Always written.} \fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values are stored as attributes of a \htmlref{GrismMap}{GrismMap}).} {Set from the attributes of the GrismMap, if present, and if set explicitly.} \fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame (all systems are supported except CMBDIPOL).} {Set from the StdOfRest attribute of the SpecFrame, but only if it has been set explicitly.} \fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.} \fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame (the observers height above sea level is ignored).}{Set from the ObsLon and ObsLat attributes of the Frame, if they have been set explicitly (it is assumed that the observer is at sea level).} \fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has been set explicitly.} \fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the SpecFrame (all systems are supported except CMBDIPOL).} {Set from the SourceVRF attribute of the SpecFrame.} \fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{SourceVel} attribute of the SpecFrame (the SourceVRF attribute is first set to the system indicated by the SSYSSRC keyword, and the ZSOURCE value is then converted to an apparent radial velocity and stored as the SourceVel attribute).} {Set from the SourceVel attribute of the SpecFrame, if it has been set explicitly (the SourceVel value is first converted from apparent radial velocity to redshift).} \fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the SpecFrame that define the standard of rest and the observers position.} \fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{RestFreq} attribute of the SpecFrame.}{Set from the RestFreq attribute of the SpecFrame, but only if the System attribute is not set to ``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set explicitly.} \fitskey{RESTWAV\emph{a}}{Used to set the RestFreq attribute of the SpecFrame (after conversion from wavelength to frequency).} {Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the System attribute is set to ``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set explicitly.} \fitskey{CNAME\emph{ia}}{Used to set the Label attributes of the WCS Frame keywords.}{Set from the Label attributes of the WCS Frame, if they have been set explicitly.} \hline \end{tabular} \end{footnotesize} \vspace{3.mm} \caption{Use of FITS-WCS Paper III keywords} \label{tab:fitspaper3} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a \htmlref{FitsChan}{FitsChan}, the write operation is successful only if the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the SpecFrame satisfies one of the following conditions: \begin{enumerate} \item It is linear. \item It is logarithmic. \item It is linear if the SpecFrame were to be re-mapped into one of the other spectral systems supported by FITS-WCS paper III. \item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from pixel coordinates to grism parameter) is linear, and the Mapping after the GrismMap is either null or represents a change of spectral system from wavelength (air or vacuum) to one of the supported spectral systems. \item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan. \end{enumerate} If none of the above conditions hold, the write operation will be unsuccessful. Note, if the FitsChan's TabOK attribute is set to a positive non-zero value then any Mapping that does not meet any of the earlier conditions will be written out as a look-up table, using the ``-TAB'' algorithm described in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or negative in the FitsChan, then the write operation will be unsuccessful unless one of the eaerlier conditions is met.\footnote{If the -TAB algorithm is used, the positive value of the TabOK attribute is used as the table version number (the EXTVER header) in the associated FITS binary table.} \subsubsection{Common Non-Standard Features} The following non-standard features are supported when reading spectral axes from a \htmlref{FitsChan}{FitsChan}: \begin{itemize} \item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes (specified in early drafts of paper III) to the corresponding ``-X2P'' form. \item Conversion of ``RESTFREQ'' to ``RESTFRQ'' \end{itemize} \subsection{Paper IV - Coordinate Distortions} This paper proposes that an additional 4 character code be appended to the end of the CTYPE\emph{i} keyword to specify the nature of any distortion away from the basic algorithm described by the first 8 characters of the CTYPE\emph{i} value. Currently AST ignores all such codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} (except for the ``-SIP'' code defined by the Spitzer Space Telescope project - see below). This means that a FrameSet can still be read from such headers, but the \htmlref{Mapping}{Mapping} which gives the WCS position associated with a given pixel position will reflect only the basic algorithm and will not include the effects of the distortion. If such a FrameSet is then written out to a FitsChan, the resulting CTYPE\emph{i} keywords will include no distortion code. \subsubsection{The ``-SIP'' distortion code} The Spitzer Space Telescope project (\url{http://www.spitzer.caltech.edu/}) has developed its own system for encoding 2-dimensional image distortion within a FITS header, based on the proposals of paper IV. A description of this system is available in \url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}. In this system, the presence of distortion is indicated by appending the distortion code ``-SIP'' to the CTYPE\emph{i} keyword values for the celestial axes. The distortion takes the form of a polynomial function which is applied to the pixel coordinates, after subtraction of the CRPIX\emph{j} values. This system is a strictly 2 dimensional system. When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which includes the ``-SIP'' distortion code, AST assumes that it is only applied to the first 2 WCS axes in a FITS header (i.e. CTYPE1 and CTYPE2). If the ``-SIP'' distortion code is attached to other axes, it will be ignored. The distortion itself is represented by a \htmlref{PolyMap}{PolyMap} within the resulting FrameSet. If a FrameSet is read from a FitsChan which includes ``-SIP'' distortion, and an attempt is then made to write this FrameSet out to a FitsChan, the write operation will fail unless the distortion is insignificant (\emph{i.e.} is so small that the tests for linearity built into AST are passed). In this case, no distortion code will be appended to the resulting CTYPE\emph{i} keyword values. \newpage \section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes} \subsection{Changes Introduced in V1.1} The following describes the most significant changes which occurred in the AST library between versions V1.0 and V1.1 (not the most recent version): \begin{enumerate} \item A new ``How To\ldots'' section (\secref{ss:howto}) has been added to this document. It contains simple recipies for performing commonly-required operations using AST. \item A new \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT} function has been provided to read formatted coordinate values for the axes of a \htmlref{Frame}{Frame} (\secref{ss:unformattingaxisvalues}). In essence, this function is the inverse of \htmlref{AST\_FORMAT}{AST\_FORMAT}. It may be used to decode user-supplied formatted values representing coordinates, turning them into numerical values for processing. Celestial coordinates may also be read using this function (\secref{ss:unformattingskyaxisvalues}) and free-format input is supported. \item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting celestial coordinate values now allows the degrees/hours field to be omitted, so that celestial coordinates may be given in (\emph{e.g.}) arc-minutes and/or arc-seconds (\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours field is no longer included by default. A new ``t'' format specifier has been introduced (see the Format attribute) to allow minutes and/or seconds of time to be specified if required. \item A new routine \htmlref{AST\_MAPBOX}{AST\_MAPBOX} has been introduced. This allows you to find the extent of a ``bounding box'' which just encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to calculate the size which an image would have if it were transformed by the Mapping. \item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced (\secref{ss:intramaps}). This is a specialised form of Mapping which encapsulates a privately-defined coordinate transformation routine (\emph{e.g.}\ written in Fortran) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. \item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically preserved whenever changes are made to any attributes which affect the current Frame (either by setting or clearing their values). This is accomplished by appropriately re-mapping the current Frame to account for any change to the coordinate system which it represents (\secref{ss:framesetintegrity}). \item The internal structure of a FrameSet is now automatically tidied to eliminate redundant nodes whenever any of its Frames is removed or re-mapped. Automatic simplification of any compound Mappings which result may also occur. The effect of this change is to prevent the accumulation of unnecessary structure in FrameSets which are repeatedly modified. \item Some improvements have been made to the algorithms for simplifying compound Mappings, as used by \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. \item The textual representation used for some Objects (\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed slightly, but remains compatible with earlier versions of AST. \item A problem has been fixed which could result when using \htmlref{AST\_READ}{AST\_READ} to read FITS headers in which the CDELT value is zero. Previously, this could produce a Mapping whose inverse transformation was not defined and this could unnecessarily restrict the use to which it could be put. The problem has been overcome by supplying a suitable small CDELT value for FITS axes which have only a single pixel. \item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap} to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of a compound Mapping which is being simplified using AST\_SIMPLIFY. \item A bug has been fixed which could cause the AST\_\_BAD parameter to have an incorrect value on some platforms. \item A problem has been fixed which could prevent tick marks being drawn on a coordinate axis close to a singularity in the coordinate system. \end{enumerate} \subsection{Changes Introduced in V1.2} The following describes the most significant changes which occurred in the AST library between versions V1.1 and V1.2 (not the most recent version): \begin{enumerate} \item A new routine, \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}, has been introduced to allow more efficient plotting of multiple geodesic curves (\secref{ss:plottinggeodesics}). \item A new set of functions, \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}, has been introduced to perform resampling of gridded data such as images (\emph{i.e.}\ re-gridding) under the control of a geometrical transformation specified by a \htmlref{Mapping}{Mapping}. \item The command-line options ``$-$pgp'' and ``$-$pgplot'', which were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and ``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option ``$-$pgp'' now causes linking with the Starlink version of PGPLOT (which uses GKS to generate its output), while ``$-$pgplot'' links with the standard (or ``native'') version of PGPLOT. \item The routine \htmlref{AST\_MAPBOX}{AST\_MAPBOX} has been changed to execute more quickly, although this has been achieved at the cost of some loss of robustness when used with difficult Mappings. \item A new value of ``FITS-IRAF'' has been introduced for the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an interim solution to the problem of storing coordinate system information in FITS headers, until the proposed new FITS-WCS standard becomes stable. \item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame} of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to ``GRID''. This reflects the fact that this Frame represents FITS data grid coordinates (equivalent to FITS pixel coordinates---see \secref{ss:domainconventions}). Previously, this Domain value was not set. \item \htmlref{AST\_FINDFITS}{AST\_FINDFITS} now ignores trailing spaces in its keyword template. \item \htmlref{AST\_PUTFITS}{AST\_PUTFITS} now recognises ``D'' and ``d'' as valid exponent characters in floating point numbers. \item The FitsChan class is now more tolerant of common minor violations of the FITS standard. \item The FitsChan class now incorporates an improved test for the linearity of Mappings, allowing more reliable conversion of AST data into FITS (using ``foreign'' FITS encodings). \item Some further improvements have been made to the algorithms for simplifying compound Mappings, as used by \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}. \item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap} class. This allows improved simplification of compound Mappings (CmpMaps) involving SphMaps and typically improves performance when handling FITS world coordinate information. \item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of AST\_\_BAD automatically to all output coordinates. If certain output coordinates do not depend on the affected input coordinate(s) because the relevant matrix elements are zero, then they may now remain valid. \item A minor bug has been corrected which could cause certain projections which involve half the celestial sphere to produce valid coordinates for the other (unprojected) half of the sphere as well. \item A bug has been fixed which could occasionally cause \htmlref{AST\_CONVERT}{AST\_CONVERT} to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was possible when, in fact, it wasn't. \end{enumerate} \subsection{Changes Introduced in V1.3} The following describes the most significant changes which occurred in the AST library between versions V1.2 and V1.3 (not the most recent version): \begin{enumerate} \item A new set of functions, \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}, has been introduced to provide efficient resampling of gridded data, such as spectra and images, under the control of a geometrical transformation specified by a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported. \item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised form of Mapping which implements 2-dimensional pincushion or barrel distortion. \item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too many digits when formatting floating point values for inclusion in a FITS header if the numerical value was in the range -0.00099999\ldots to -0.0001. \item A bug has been fixed which could cause a FitsChan to lose the comment associated with a string value in a FITS header. \item A FitsChan now reports an error if it reads a FITS header which identifies a non-standard sky projection (previously, this was accepted without error and a Cartesian projection used instead). \item A bug has been fixed which could prevent conversion between the coordinate systems represented by two CmpFrames. This could only occur if the CmpFrames contained a relatively large number of nested Frames. %\item A bug has been fixed which could cause a program to crash if %FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet} %had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The %problem could only occur if the nested structure was loaded from a data %c+ %file (using astRead). %c- %f+ %file (using \htmlref{AST\_READ}{AST\_READ}). %f- % \item Further improvements have been made to the simplification of compound Mappings, including fixes for several bugs which could cause indefinite looping or unwanted error messages. \item Some memory leaks have been fixed. \item A small number of documentation errors have been corrected. \end{enumerate} \subsection{Changes Introduced in V1.4} The following describes the most significant changes which have occurred in the AST library between versions V1.3 and V1.4 (not the most recent version): \begin{enumerate} \item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of \htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a flexible and transportable way using arithmetic operations and mathematical functions similar to those available in Fortran. \item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation routines used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{AST\_INTRAREG}{AST\_INTRAREG}) now require a THIS pointer as their first argument. \textbf{Existing implementations will not continue to work correctly with this version of AST unless this argument is added.} There is no need for existing software to make use of this pointer, but it must be present. This change has been introduced so that transformation functions can gain access to IntraMap attributes. \item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap class. This allows the transformation routines used by IntraMaps to adapt to produce the required transformation on a per-IntraMap basis (\secref{ss:intraflag}). \item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the length of major and minor tick marks on coordinate axes, may now be subscripted using an axis number. This allows tick marks of different lengths to be used on each axis. It also allows tick marks to be suppressed on one axis only by setting the length to zero. \item The value of the Plot attribute NumLab, which controls the plotting of numerical labels on coordinate axes, no longer has any effect on whether labelling of a coordinate grid is interior or exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute). \item The \htmlref{FitsChan}{FitsChan} class now provides some support for the IRAF-specific ``ZPX'' sky projection, which is converted transparently into the equivalent FITS ``ZPN'' projection (see the description of the \htmlref{Encoding}{Encoding} attribute for details). \item The FitsChan class now recognises the coordinate system ``ICRS'' (International Celestial Reference \htmlref{System}{System}) as equivalent to ``FK5''. This is an interim measure and full support for the (exceedingly small) difference between ICRS and FK5 will be added at a future release. Note that ``ICRS'' is not yet recognised as a coordinate system by other classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the importation of foreign data. \item A bug in the FitsChan class has been fixed which could result in longitude values being incorrect by 180 degrees when using cylindrical sky projections, such as the FITS ``CAR'' projection. \item A bug in the FitsChan class has been fixed which could result in the FITS sky projection parameters ProjP(0) to ProjP(9) being incorrectly named PROJP1 to PROJP10 when written out as FITS cards. \item A bug in the FitsChan class has been fixed which could cause confusion between the FITS-IRAF and FITS-WCS encoding schemes if both a CD matrix and a PC matrix are erroneously present in a FITS header. \item Some minor memory leaks have been fixed. \item A small number of documentation errors have been corrected. \end{enumerate} \subsection{Changes Introduced in V1.5} The following describes the most significant changes which have occurred in the AST library between versions V1.4 and V1.5 (not the most recent version): \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft FITS WCS standard, described in the two papers ``Representation of world coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th November, 1999), and ``Representation of celestial coordinates in FITS'' (M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are available at \url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}. The FITS-WCS encoding now uses these updated conventions. The main changes are: \begin{itemize} \item Rotation and scaling of pixel axes is now represented by a matrix of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and \texttt{CDELTj} keywords. \item \htmlref{Projection}{Projection} parameters are now associated with particular axes and are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm} keywords. \item The tangent plane projection (``TAN'') can now include optional polynomial correction terms. \item An entire set of keywords must be supplied for each set of secondary axis descriptions, and each such keyword must finish with a single character indicating which set it belongs to. This means that keywords which previously occupied eight characters have been shorten to seven to leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}. \end{itemize} \item Two new encodings have been added to the FitsChan class: \begin{description} \item [FITS-PC] This encoding uses the conventions of the now superseded FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords \texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation. These are the conventions which were used by the FITS-WCS encoding prior to version 1.5 of AST. This encoding is provided to allow existing data which use these conventions to be read. It should not in general be used to create new data. \item [FITS-AIPS] This encoding is based on the conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to describe axis rotation and scaling. \end{description} \item The FitsChan class now provides some support for the IRAF-specific ``TNX'' sky projection, which is converted transparently into the equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding} attribute for details). \item FrameSets originally read from a DSS encoded FITS header can now be written out using the FITS-WCS encoding (a TAN projection with correction terms will be used) in addition to the DSS encoding. The reverse is also possible: FrameSets originally read from a FITS-WCS encoded FITS header and which use a TAN projection can now be written out using the DSS encoding. \item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet} conforms to the FITS-WCS model has been improved so that FrameSets including more complex mixtures of parallel and serial Mappings can be written out using the FITS-WCS encoding. \item The FitsChan class has been changed so that long strings included in the description of an \htmlref{Object}{Object} can be saved and restored without truncation when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles, mathematical expressions, \emph{etc.} were truncated if they exceeded the capacity of a single FITS header card. They are now split over several header cards so that they can be restored without truncation. Note, this facility is only available when using NATIVE encoding. \item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which can be used to select potentially dangerous conditions under which warnings should be issued. These conditions include (for instance) unsupported features within non-standard projections, missing keywords for which default values will be used, \emph{etc}. \item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the FITS-WCS encoding in the FitsChan class: \begin{itemize} \item Projection parameters are now associated with a particular axis and are specified using a new set of attributes called PVj\_m. Here, ``j'' is the index of an axis of WcsMap, and ``m'' is the index of the projection parameter. \item The old attributes ProjP(0) to ProjP(9) are still available but are now deprecated in favour of the new PVj\_m attributes. They are interpreted as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of the latitude axis. \item The GLS projection projection has been renamed as SFL, but the AST\_\_GLS type has been retained as an alias for AST\_\_SFL. \end{itemize} \end{enumerate} \subsection{Changes Introduced in V1.6} The following describes the most significant changes which have occurred in the AST library between versions V1.5 and V1.6: \begin{enumerate} \item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups of tick marks to be skipped when using very small gaps. \item A bug has been fixed in the Plot class which could cause axes to be labeled outside the visible window, resulting in no axes being visible. \item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding Frames in the returned FrameSet. When writing a FrameSet to a FITS header the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the header. \item The FITS-WCS encoding used by the FitsChan class now attempts to retain the identification letter associated with multiple axis descriptions. When reading a FrameSet from a FITS header, the identification letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a FrameSet to a FITS header, the identification letter is read from the Ident attribute of each Frame. The letter to associate with each Frame can be changed by assigning a new value to the Frame's Ident attribute. \item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to ``Unknown'' if the CTYPE keywords in the supplied header refers to an unknown celestial coordinate system. Previously, a Frame was used instead of a SkyFrame. \item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the FitsChan class no longer report an error if the FITS header contains no CTYPE keywords. It is assumed that a missing CTYPE keyword implies that the world coordinate system is linear and identically equal to ``intermediate world coordinates''. \item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute of the FitsChan class. This value causes warnings to be issued if CTYPE keywords are missing from foreign encodings. \item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan class. This is a read-only, space separated list of all the known condition names which can be specified in the Warnings attribute. \item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in a FrameSet read using a foreign encoding. The Title is based on the Domain name of the Frame. If the Frame has no Domain name, the default Title supplied by the Frame class is retained. \item The FitsChan class uses the comments associated with CTYPE keywords as axis labels when reading a foreign encoding. This behaviour has been modified so that the default labels provided by the Frame class are retained (instead of using the CTYPE comments) if any of the CTYPE comments are identical. \item A new ``interpolation'' scheme identified by the symbolic constant AST\_\_BLOCKAVE has been added to the \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$} set of functions. The new scheme calculates each output pixel value by finding the mean of the input pixels in a box centred on the output pixel. \item The SkyFrame class can now be used to represent an arbitrary spherical coordinate system by setting its System attribute to ``Unknown''. \item The indices of the latitude and longitude axes of a SkyFrame can now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The effects of any axis permutation is taken into account. \item A new attribute called Ident has been added to the \htmlref{Object}{Object} class. This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID) its value is transferred to the new Object when a copy is made. \item A bug has been fixed which could prevent complex CmpFrames behaving correctly (for instance, resulting in the failure of attempts to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself). \end{enumerate} \subsection{Changes Introduced in V1.7} The following describes the most significant changes which have occurred in the AST library between versions V1.6 and V1.7: \begin{enumerate} \item The \htmlref{Frame}{Frame} class has a new method called \htmlref{AST\_ANGLE}{AST\_ANGLE} which returns the angle subtended by two points at a third point within a 2 or 3 dimensional Frame. \item The Frame class has a new method called \htmlref{AST\_OFFSET2}{AST\_OFFSET2} which calculates a position which is offset away from a given starting point by a specified distance along a geodesic curve which passes through the starting point at a given position angle. It can only be used with 2-dimensional Frames. \item The Frame class has a new method called \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE} which returns the increment between two supplied axis values. For axes belonging to SkyFrames, the returned value is normalized into the range $\pm\pi$. \item The Frame class has a new method called \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET} which returns an axis value a given increment away from a specified axis value. For axes belonging to SkyFrames, the returned value is normalized into the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude axes). \item The \htmlref{Plot}{Plot} class has a new method called \htmlref{AST\_GENCURVE}{AST\_GENCURVE} which allows generalised user-defined curves to be drawn. The curve is defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve into the corresponding position in the current Frame of the Plot. The new method then maps these current Frame position into graphics coordinates, taking care of any non-linearities or discontinuities in the mapping. \item The Plot class has a new method called \htmlref{AST\_GRFSET}{AST\_GRFSET} which allows the underlying primitive graphics functions to be selected at run-time. Previously, the functions used by the Plot class to produce graphics could only be selected at link-time, using the options of the \htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride the functions established at link-time, by specifying alternative primitive graphics routines. In addition, the two new Plot methods \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH} and \htmlref{AST\_GRFPOP}{AST\_GRFPOP} allow the current graphics routines to be saved and restore on a first-in-last-out stack, allowing temporary changes to be made to the set of registered graphics routines. \item The DrawAxes attribute of the Plot class can now be specified independantly for each axis, by appending the axis index to the end of the attribute name. \item A bug has been fixed in the Plot class which could result in axis labels being drawn on inappropriate edges of the plotting box when using ``interior'' labelling. \item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps to be corrupted after transforming any points. \item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause inappropriate ordering of headers within a FitsChan when writing or reading objects using NATIVE encodings. \item A bug has been fixed in the FitsChan class which could cause the celestial longitude of a pixel to be estimated incorrectly by 180 degrees if the reference point is at either the north or the south pole. \end{enumerate} \subsection{Changes Introduced in V1.8-2} The following describes the most significant changes which have occurred in the AST library between versions V1.7 and V1.8-2: \begin{enumerate} \item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows longitude values to be displayed in the range $-\pi$ to $+\pi$, instead of the usual range zero to $2.\pi$. \item Some new routines (\htmlref{AST\_ANGLE}{AST\_ANGLE}, \htmlref{AST\_AXANGLE}{AST\_AXANGLE}, \htmlref{AST\_RESOLVE}{AST\_RESOLVE}, \htmlref{AST\_OFFSET2}{AST\_OFFSET2}, \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET}, \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE}) have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space to be performed without needing to know the underlying geometry of the co-ordinate system (for instance, whether it is Cartesian or spherical). Note, version 1.8-1 contained many of these facilities, but some have been changed in version 1.8-2. Particularly, positions angles are now referred to the second Frame axis for \emph{all} classes of Frames (including SkyFrames), and the AST\_BEAR routine has been replaced by AST\_AXANGLE. \end{enumerate} \subsection{Changes Introduced in V1.8-3} The following describes the most significant changes which occurred in the AST library between versions V1.8-2 and V1.8-3: \begin{enumerate} \item A new method called astDecompose has been added to the \htmlref{Mapping}{Mapping} class which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and \htmlref{CmpFrame}{CmpFrame} objects. \item Functions within proj.c and wcstrig.c have been renamed to avoid name clashes with functions in more recent versions of Mark Calabretta's wcslib library. \end{enumerate} \subsection{Changes Introduced in V1.8-4} The following describes the most significant changes which occurred in the AST library between versions V1.8-3 and V1.8-4: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be used to select the default reference frame and equinox to be used if a FitsChan with foreign encoding contains no indication of the reference frame or equinox. \item A bug has been fixed in the FitsChan class which could prevent astWrite from creating a set of FITS headers from an otherwise valid \htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding. \item A bug has been fixed in the FitsChan class which could cause astRead to mis-interpret the FITS CROTA keyword when using FITS-AIPS encoding. \end{enumerate} \subsection{Changes Introduced in V1.8-5} The following describes the most significant changes which occurred in the AST library between versions V1.8-4 and V1.8-5: \begin{enumerate} \item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2, Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2. These allow graphical attributes (colour, width, etc) to be set for each axis individually. Previously, graphical attributes could only be set for both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs, TextLabs and Ticks. \end{enumerate} \subsection{Changes Introduced in V1.8-7} The following describes the most significant changes which occurred in the AST library between versions V1.8-5 and V1.8-7: \begin{enumerate} \item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class which controls the way CAR projections are handled when reading a \htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR projection to represent a simple linear transformation between pixel coordinates and celestial sky coordinates. This is not consistent with the definition of the CAR projection in the draft FITS-WCS standard, which requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native spherical coordinates to celestial spherical coordinates, thus making the Mapping non-linear. Setting CarLin to 1 forces \htmlref{AST\_READ}{AST\_READ} to ignore the FITS-WCS standard and treat any CAR projections as simple linear Mappings from pixel coordinates to celestial coordinates. \item A bug has been fixed which could result in axis Format attributes set by the user being ignored under certain circumstances. \item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class has been fixed. This bug could result in extra ticks marks being displayed at inappropriate positions. This bug manifested itself, for instance, if the Mapping represented by the Plot was a simple Cartesian to Polar Mapping. In this example, the bug caused tick marks to be drawn at negative radius values. \item A bug has been fixed which could prevent attribute settings from being read correctly by \htmlref{AST\_SET}{AST\_SET}, etc., on certain platforms (MacOS, for instance). \end{enumerate} \subsection{Changes Introduced in V1.8-8} The following describes the most significant changes which occurred in the AST library between versions V1.8-7 and V1.8-8: \begin{enumerate} \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS information stored in the form of Digitised Digitised Sky Survey (DSS) keywords. These problems only occurred for DSS fields in the southern hemisphere, and resulted in pixel positions being mapped to sky positions close to the corresponding \emph{northern} hemispshere field. \item A new method called \htmlref{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX} has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of the previous graphical output produced by a Plot method. \item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class which suppresses the graphical output normally produced by Plot methods. All the calculations needed to produce the normal output are still performed however, and so the bounding box returned by the new AST\_BOUNDINGBOX method is still usable. \item Bugs have been fixed related to the appearance of graphical output produced by the Plot class. These bugs were to do with the way in which graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.) interacted with the corresponding generic element (e.g. \texttt{Colour(axes)}, etc.). \end{enumerate} \subsection{Changes Introduced in V1.8-13} The following describes the most significant changes which occurred in the AST library between versions V1.8-8 and V1.8-13: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords are only produced by \htmlref{AST\_WRITE}{AST\_WRITE} when necessary. For zenithal projections such as TAN, the LONPOLE keyword can always take its default value and so is not included in the FITS header produced by AST\_WRITE Previously, the unnecessary production of a LONPOLE keyword could prevent FrameSets being written out using encodings which do not support the LONPOLE keyword (such as FITS-IRAF). \item The FitsChan class has been modified to retain leading and trailing spaces within COMMENT cards. \item The FitsChan class has been modified to only use CTYPE comments as axis labels if all non-celestial axes have unique non-blank comments (otherwise the CTYPE keyword values are used as labels). \item The FitsChan class has been modified so that it does not append a trailing ``Z'' character to the end of DATE-OBS keyword values. \item The FitsChan class has been modified to use latest list of FITS-WCS projections, as described in the FITS-WCS paper II, ``Representations of celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23 April 2002). Support has been retained for the polynomial correction terms which previous drafts have allowed to be associated with TAN projections. \item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN (which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN projection type now represents a simple TAN projection and has no associated projection parameters. In addition, the usage of projection parameters has been brought into line with the the FITS-WCS paper II. \item The WcsMap class has been modified so that a ``get'' operation on a projection parameter attribute will return the default value defined in the FITS-WCS paper II if no value has been set for the attribute. Previously, a value of AST\_\_BAD was returned in such a situation. \item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which allow a ``plottable range'' to be specified for each Frame axis. The grid produced by the \htmlref{AST\_GRID}{AST\_GRID} routine will not extend beyond these limits. \end{enumerate} \subsection{Changes Introduced in V2.0} Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by applications linked with earlier versions of AST. This applies to Frame descriptions created using: \begin{itemize} \item the \htmlref{Channel}{Channel} class \item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used \item the \htmlref{AST\_SHOW}{AST\_SHOW} routine. \end{itemize} Applications must be re-linked with AST V2.0 in order to be able to read Frame descriptions created by AST v2.0. The following describes the most significant changes which have occurred in the AST library between versions V1.8-13 and V2.0 (the current version): \begin{enumerate} \item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame} class has been changed from ``CMP'' to a string formed by concatenating the Domain attributes of the two component Frames, separated by a minus sign. If both component Domains are blank, then the old default of ``CMP'' is retained for the CmpFrame Domain. \item The implementation of the \htmlref{AST\_WRITE}{AST\_WRITE} routine within the FitsChan class has been modified. It will now attempt to produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the \htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This has always been possible with NATIVE encoding, but has not previously been possible for foreign encodings. The WCSAXES keyword is used to store the number of WCS axes in the FITS header. \item Another change to the AST\_WRITE routine within the FitsChan class is that the ordering of ``foreign'' axes (\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix as diagonal as possible - any element of axis transposition is removed by this re-ordering as recommended in FITS-WCS paper I. Previously the ordering was determined by the order of the axes in the Current Frame of the supplied FrameSet. This change does not affect NATIVE encoding. \item Support for spectral coordinate systems has been introduced throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}. The SpecFrame is a 1-dimensional Frame which can be used to describe positions within an electromagnetic spectrum in various systems (wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred to various standards of rest (topocentric, geocentric, heliocentric LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral axis values between these various systems and standards of rest. Note, FitsChans which have a foreign encoding (\emph{i.e.} any encoding other than NATIVE) are not yet able to read or write these new classes. \item Facilities have been added to the Frame class which allow differences in axis units to be taken into account when finding a Mapping between two Frames. In previous versions of AST, the Unit attribute was a purely descriptive item intended only for human readers - changing the value of Unit made no difference to the behaviour of the Frame. As of version 2.0, the Unit attribute can influence the nature of the Mappings between Frames. For instance, if the AST\_FINDRAME or \htmlref{AST\_CONVERT}{AST\_CONVERT} method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m'' and another Axis with Unit set to ``km'', then the method will return a \htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes. These facilities assume that units are specified following the rules included in FITS-WCS paper I (\emph{Representation of World Coordinates in FITS}, Greisen \& Calabretta). In order to minimise the risk of breaking existing software, the default behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.} to retain the previous behaviour). However, the new Frame method \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} may be used to ``activate'' (or deactivate) the new facilities within a specific Frame. Note, the new SpecFrame class is different to the simple Frame class in that the new facilities for handling units are always active within a SpecFrame. \item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been moved to the parent Frame class. This enables all sub-classes of Frame (such as the new SpecFrame class) to share these attributes, and to provide suitable options for each class. \item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows control over the alignment process performed by the methods \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} and AST\_CONVERT. \item The CmpFrame class has been modified so that attributes of a component Frame can be accessed without needing to extract the Frame first. To do this, append an axis index to the end of the attribute name. For instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order), then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the ``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently ``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the CmpFrame will refer to the System attribute of the SpecFrame, whereas the ``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the System attribute of the SkyFrame (the ``System'' attribute without an axis specifier will refer to the System attribute of the CmpFrame as a whole, since System is an attribute of all Frames, and a CmpFrame is a Frame and so has its own System value which is independant of the System attributes of its component Frames). \item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit overlapping axis labels, and the abbreviation of redundant leading fields within sexagesimal axis labels, have been improved to avoid some anomolous behaviour in previous versions. \item The curve drawing algorithm used by the Plot class has been modified to reduce the chance of it ``missing'' small curve sections, such as may be produced if a grid line cuts across the plot very close to a corner. Previously, these missed sections could sometimes result in axis labels being omitted. \item A new function (\htmlref{AST\_VERSION}{AST\_VERSION}) has been added to return the version of the AST library in use. \item Bugs have been fixed in the Plot class which caused serious problems when plotting high precision data. These problems could range from the omission of some tick marks to complete failure to produce a plot. \end{enumerate} Programs which are statically linked will need to be re-linked in order to take advantage of these new facilities. \subsection{Changes Introduced in V3.0} The following describes the most significant changes which occurred in the AST library between versions V2.0 and V3.0: \begin{enumerate} \item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring the FITS-WCS encoding into line with the current versions of the FITS-WCS papers (see \url{http://www.atnf.csiro.au/people/mcalabre/WCS/}): \begin{itemize} \item The rotation and scaling of the pixel axes may now be specified using either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS header. \item The FITS-WCS encoding now supports most of the conventions described in FITS-WCS paper III for the description of spectral coordinates. The exceptions are that the SSYSOBS keyword is not supported, and WCS stored in tabular form (as indicated by the ``-TAB'' algorithm code) is not supported. \item User-specified fiducial points for WCS projections are now supported by FitsChans which use FITS-WCS encoding. This use keywords PVi\_0, PVi\_1 and PVi\_2 for the longitude axis. \item When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3 and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE and LATPOLE keywords which may be present. When writing a FITS-WCS header, both forms are written out. \item The number of WCS axes is stored in the WCSAXES keyword if its value would be different to that of the NAXIS keyword. \item Helio-ecliptic coordinates are now supported by FitsChans which use FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all the usual facilities, such as conversion to other celestial systems, are available. \item The FITS-WCS encoding now supports most of the conventions described in FITS-WCS paper III for the description of spectral coordinates. The exceptions are that the SSYSOBS keyword is not supported, and WCS stored in tabular form (as indicated by the ``-TAB'' algorithm code) is not supported. \item When reading a FITS-WCS header, a FitsChan will now ignore any distortion codes which are present in CTYPE keywords. Here, a ``distortion code'' is the final group of four characters in a CTYPE value of the form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception to this is that the ``-SIP'' distortion code (as used by the Spitzer Space Telescope project - see \url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes can only be read, not written. A FrameSet which uses a PolyMap will not in general be able to be written out to a FitsChan using any foreign encoding (although NATIVE encoding can of course be used). \item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values ``BadVal'' (which gives warnings about conversion errors when reading FITS keyword values), ``Distortion'' (which gives warnings about unsupported distortion codes within CTYPE values), and ``BadMat'' (which gives a warning if the rotation/scaling matrix cannot be inverted). \item When writing a FrameSet to a FitsChan which uses a non-Native encoding, the comment associated with any card already in the FitsChan will be retained if the keyword value being written is the same as the keyword value already in the FitsChan. \item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN projection with polynomial distortion terms) can now be written to a FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard ``-TAN'' code is used within the CTYPE values, and the distortion coefficients are encoded in keywords of the form `` QVi\_ma'', which are directly analogous to the standard ``PVi\_ma'' projection parameter keywords. Thus a FITS reader which does not recognise the QV keywords will still be able to read the header, but the distortion will be ignored. \item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value of the Encoding attribute. \item A new appendix has been added to SUN/210 and SUN/211 giving details of the implementation provided by the FitsChan class of the conventions contained in the first four FITS-WCS papers. \end{itemize} \item The SkyFrame class now supports two new coordinate systems ``ICRS'' and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames has been changed from ``FK5'' to ``ICRS''. \item The \htmlref{AST\_RATE}{AST\_RATE} function has been added which allows an estimate to be made of the rate of change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs. \item All attribute names for Frames of any class may now include an optional axis specifier. This includes those attributes which describe a property of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases such as this, where the attribute describes a property of the whole Frame, axis specifiers will usually be ignored. The exception is that a \htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the attribute name relates to the primary Frame containing the specified axis, rather than to the CmpFrame as a whole. \item A new subclass of Mapping, the PolyMap, has been added which performs a general N-dimensional polynomial mapping. \item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which models the spectral dispersion produced by a grating, prism or grism. \item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap} with unit scaling on all axes). \item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice and placement of numerical axis labels. \item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the longitude value to be returned when a Cartesian position corresponding to either the north or south pole is transformed into spherical coordinates. \item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output celestial coordinates which have a latitude of plus or minus 90 degrees. \item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been changed so that they now return the fixed native coordinates of the projection reference point, rather than the native coordinates of the user-defined fiducial point. \item Notation has been changed in both the WcsMap and FitsChan classes to reflect the convention used in the FITS-WCS papers that index ``i'' refers to a world coordinate axis, and index ``j'' refers to a pixel axis. \item Changes have been made to several Mapping classes in order to allow the \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not possible. \item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates. \item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the refractive index of air as given in the current version of FITS-WCS paper III. Also, the forward and inverse transformations between frequency and air-wavelength have been made more compatible by using an iterative procedure to calculate the inverse. \end{enumerate} \subsection{Changes Introduced in V3.1} The following describes the most significant changes which have occurred in the AST library between versions V3.0 and V3.1 (the current version): \begin{enumerate} \item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which reads and writes AST objects in the form of XML. \item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect graphical attributes to be used for various parts of the plot if either axis has no tick marks (i.e. if both major and minor tick marks have zero length). \end{enumerate} Programs which are statically linked will need to be re-linked in order to take advantage of these new facilities. \subsection{Changes Introduced in V3.2} The following describes the most significant changes which have occurred in the AST library between versions V3.1 and V3.2: \begin{enumerate} \item A new routine \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS} has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header cards to be stored in a FitsChan in a single call, providing an alternative to the existing AST\_PUTCARDS routine. \item Some signficant changes have been made to the simplification of Mappings which should resultin a greater degree of simplication taking place.Some bugs have also been fixed which could result in an infinite loop being entered when attempting to simplify certain Mappings. \item The FitsChan class now translates the spectral algorithm codes ``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to the corresponding ``-X2P'' form when reading a spectral axis description from a set of FITS header cards. \item A bug has been fixed in the FitsChan class which could cause keywords associated with alternate axis descriptions to be mis-interpreted. \item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance of sub-strings within text strings such as axis labels, titles, \emph{etc}, by producing super-scripts, sub-scripts, changing the font colour, size, \emph{etc}. See attribute \htmlref{Escape}{Escape}. \item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been changed from 0.001 to 0.01. This should not usually cause any significant visible change to the plot, but should make the plotting faster. You may need to set a lower value for Tol if you are producing a particularly large plot. \item The algorithm for finding the default value for the Gap attribute has been changed. This attribute specifies the gap between major axis values in an annotated grid drawn by the Plot class. The change in algorithm may cause the default value to be different to previous versions in cirtain circumstances. \item Some bugs have been fixed in the Plot class which could cause the system to hang for a long time while drawing certain all-sky grids (notable some of the FITS Quad-cube projections). \item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition of the ``g'' option. this option is similar to the older ``l'' option in that it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as delimiters between the sexagesimal fields of the celestial position. The difference is that the ``g'' option includes graphics escape sequences in the returned formatted string which result in the field delimiter characters being drawn as super-scripts when plotted as numerical axis values by a Plot. \item The Plot class has been extended to include facilities for producing logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel. \item New functions astGCap and astGScales have been added to the interface defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so that the \verb+-mygrf+ switch loads dummy versions of the new grf functions. This means that applications should continue to build without any change. However, the facilities for interpreting escape sequences within strings drawn by the Plot class will not be available unless the new grf functions are implemented. If you choose to implement them, you should modify your linking procedure to use the \verb+-grf+ switch in place of the older \verb+-mygrf+ switch. See the description of the ast\_link command for details of the new switches. Also note that the astGQch function, whilst included in verb+grf.h+ in pervious versions of AST, was not actually called. As of this version of AST, calls are made to the astGQch function, and so any bugs in the implementation of astGQch may cause spurious behaviour when plotting text strings. \item A new 'static' method called astEscapes has been added which is used to control and enquire whether astGetC and astFormat will strip any graphical escape sequences which may be present out of the returned value. \item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It allows XML written by the XmlChan class to include an explicit namespace prefix on each element. \item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It specifies the format in which AST objects should be written. \item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap takes its forward transformation from an existing Mapping, and its inverse transformation from another existing Mapping. \item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to include erroneous axis numbers when referring to missing parameter values. \end{enumerate} \subsection{Changes Introduced in V3.3} The following describes the most significant changes which have occurred in the AST library between versions V3.2 and V3.3: \begin{enumerate} \item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the origin of celestial coordinates to be moved to any specified point. See the new attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. \item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra Frames representing cartesian projection plane coordinates (``intermediate world coordinates'' in the parlance of FITS-WCS) to be created when reading WCS information from a foreign FITS header. This option is controlled by a new attribute called \htmlref{Iwc}{Iwc}. \item The FitsChan class which been modified to interpret FITS-WCS CAR projection headers correctly if the longitude reference pixel (CRPIX) is very large. \item The FITS-AIPS++ encoding in the FitsChan class now recognised spectral axes if they conform to the AIPS convention in which the spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB" where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD, HEL or OBS. Such spectral axes can be both read and written. \item The FitsChan class now has a FITS-AIPS++ encoding which represents WCS information using FITS header cards recognised by the AIPS++ project. Support for spectral axes is identical to the FITS-AIPS encoding. \item The organisation of the AST distribution and the commands for building it have been changed. Whereas AST used to be built and installed with \verb+./mk build; ./mk install+, it now builds using the more standard idiom \verb+./configure; make; make install+. The installation location is controlled by the \verb+--prefix+ argument to ./configure (as is usual for other packages which use this scheme). Note that the INSTALL environment variable now has a \emph{different} meaning to that which it had before, and it should generally be \emph{unset}. Also, there is no need to set the SYSTEM variable. \item Shared libraries are now installed in the same directory as the static libraries. In addition, links to sharable libraries are installed with names which include version information, and ``libtool libraries'' are also installed (see \url{http://www.gnu.org/software/libtool/manual.html}). \item The \verb+ast_dev+ script has been removed. Instead, the location of the AST include files should be specified using the -I option when compiling. \item The names of the installed AST include files have been changed to upper case. \end{enumerate} \subsection{Changes Introduced in V3.4} The following describes the most significant changes which have occurred in the AST library between versions V3.3 and V3.4: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} class has a new method (\htmlref{AST\_LINEARAPPROX}{AST\_LINEARAPPROX}) which calculates the co-efficients of a linear approximation to a Mapping. \item The Format attribute for simple Frames and SkyFrames has been extended. It has always been possible, in both classes, to specify a precision by including a dot in the Format value followed by an integer (\emph{e.g.} ``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}). The precision can now also be specified using an asterisk in place of the integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the precision to be derived on the basis of the Digits attribute value. \item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the Digits attribute is chosen to be the smallest value which results in no pair of adjacent labels being identical. For instance, if an annotated grid is being drawn describing a SkyFrame, and the Format(1) value is set to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as superscripts), and the Digits(1) value is unset, then the seconds field will have a number of decimal places which results in no pair of labels being identical. \item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes associated with dual sideband spectral data. \item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS'' projection code, converting them to the corresponding modern ``-SFL'' code, provided that the celestial axes are not rotated. \item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows the reading and writing of FITS headers using the conventions of the CLASS package - see \url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}). \end{enumerate} \subsection{Changes Introduced in V3.5} The following describes the most significant changes which have occurred in the AST library between versions V3.4 and V3.5: \begin{enumerate} \item AST now provides facilities for representing regions of various shapes within a coordinate system. The \htmlref{Region}{Region} class provides general facilities which are independent of the specific shape of region being used. Various sub-classes of Region are also now available which provide means of creating Regions of specific shape. Facilities provided by the Region class include testing points to see if they are inside the Region, testing two Regions for overlap, transforming Regions from one coordinate system to another \emph{etc}. \item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which can be used to describe various systems for describing ovserved value at a single fixed spectral position. \item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which can be used to describe a 2-d frame spanned by a spectral position axis and and an observed value axis. \item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates a previously created Mapping. The inputs of the RateMap correspond to the inputs of the encapsulated Mapping. All RateMaps have just a single output which correspond to the rate of change of a specified output of the encapsulated Mapping with respect to a specified input. \item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}. This system is an equatorial system based on the mean dynamical equator and equinox at J2000, and differs slightly from an FK5(J2000) system. \item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to store a collection of vector or scalar values or Objects, indexed by a character string rather than an integer. \item The parameter list for the \htmlref{AST\_RATE}{AST\_RATE} method of the Mapping class has been modified. It no longer returns a second derivative estimate. Existing code which uses this method will need to be changed. \item Methods (AST\_SETFITS) have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named keywords to be changed or added. \end{enumerate} \subsection{Changes Introduced in V3.6} The following describes the most significant changes which occurred in the AST library between versions V3.5 and V3.6: \begin{enumerate} \item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame} starts with a percent character (``\verb+%+''), then axis values are now formatted and unformatted as a decimal radians value, using the Format syntax of a simple \htmlref{Frame}{Frame}. \item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the clipping performed by AST at the plot boundary. \item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}. The new PolyMap class always writes new styles keys but can read either old or new style keys. Consequently, PolyMap dumps written by this version of AST cannot be read by older versions of AST. \item A mimimal cut down subset of the C version of SLALIB is now included with the AST distribution and built as part of building AST. This means that it is no longer necessary to have SLALIB installed separately at your site. The SLALIB code included with AST is distrubuted under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to link with this internal slalib subset. However, the ``-csla'' option can still be used to force linking with an external full C SLALIB library. A new option ``-fsla'' has been introduced which forces linking with the external full Fortran SLALIB library. \end{enumerate} \subsection{Changes Introduced in V3.7} The following describes the most significant changes which occurred in the AST library between versions V3.6 and V3.7: \begin{enumerate} \item Support for time coordinate systems has been introduced throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}. The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe moments in time (either absolute or relative) in various systems (MJD, Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC, UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time values between these various systems and time scales. Note, FitsChans which have a foreign encoding (\emph{i.e.} any encoding other than NATIVE) are not able to read or write these new classes. \end{enumerate} \subsection{Changes Introduced in V4.0} The following describes the most significant changes which occurred in the AST library between versions V3.7 and V4.0: \begin{enumerate} \item Experimental support for reading IVOA Space-Time-Coordinates (STC-X) descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included for a subset of V1.20 of the draft STC specification. \item A new set of methods (AST\_REBIN/astRebin) has been added to the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing AST\_RESAMPLE/astResample methods. \end{enumerate} \subsection{Changes Introduced in V4.1} The following describes the most significant changes which occurred in the AST library between versions V4.0 and V4.1: \begin{enumerate} \item A new control flag has been added to the AST\_RESAMPLE/astResample functions which produces approximate flux conservation. \item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to AST\_PAR. These specify kernels for AST\_RESAMPLE and AST\_REBIN based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the first order Bessel function of the first kind). \item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding to horizon (azimuth/elevation) coordinates. \item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and ``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values. \item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify the geodetic longitude and latitude of the observer. \item The ClockLon and ClockLat attributes have been removed from the \htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and ObsLat attributes of the parent Frame class instead. However, the old attribute names can be used as synonyms for ObsLat and ObsLon. Also, dumps created using the old scheme can be read succesfully by AST V4.1 and converted to the new form. \item A new routine \htmlref{AST\_MAPSPLIT}{AST\_MAPSPLIT} has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component Mappings which, when combined in parallel, are equivalent to the original Mapping. \item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from ``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame to represent offsets from some origin position, you must now set the SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in addition to assigning the required origin position to the SkyRef attribute. \end{enumerate} \subsection{Changes Introduced in V4.2} The following describes the most significant changes which occurred in the AST library between versions V4.1 and V4.2: \begin{enumerate} \item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the DSBSpecFrame to represent the offset from the local oscillator frequency, rather than either of the two sidebands. \item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric apparent velocity of the standard of rest). FitsChan also strips out VELOSYS keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding. \item The FitsChan class has a new method called \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS} that indicates that the current card in the FitsChan should not be stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan. Unless this method is used, all cards that were involved in the creation of the AST Object will be stripped from the FitsChan afte a read operation. \item A problem with unaligned memory access that could cause bus errors on Solaris has been fixed. \item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the Object. Note, this is the size of the internal in-memory representation of the Object, not the size of the textual representation produced by writing the Object out through a \htmlref{Channel}{Channel}. \item A new function \htmlref{AST\_TUNE}{AST\_TUNE} has been added which can be used to get and set global AST tuning parameters. At the moment there are only two such parameter, both of which are concerned with memory management within AST. \item A new method called \htmlref{AST\_TRANGRID}{AST\_TRANGRID} has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular grid of points covering a rectangular region within the input space of a Mapping, and then transforms this set of points into the output space of the Mapping, using a piecewise-continuous linear approximation to the Mapping if appropriate in order to achive higher speed. \item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A SwitchMap represents several alternate Mappings, each of which is used to transforms input positions within a different region of the input coordinate space. \item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A SelectorMap tests each input position to see if it falls within one of several Regions. If it does, the index of the \htmlref{Region}{Region} containing the input position is returned as the Mapping output. \item The behaviour of the \htmlref{AST\_CONVERT}{AST\_CONVERT} method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been modified. If no conversion between positions in the Frame and CmpFrame can be found, an attempt is now made to find a conversion between the Frame and one of two component Frames contained within the CmpFrame. Thus is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad values for the extra axes (i.e. for the SpecFrame axis in the above example). \item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the \verb+-fsla+ and \verb+-csla+ options, and always link against the minimal cut-down version of SLALIB distributed as part of AST. \end{enumerate} \subsection{Changes Introduced in V4.3} The following describes the most significant changes which occurred in the AST library between versions V4.2 and V4.3: \begin{enumerate} \item The AST\_GETFITSS function now strips trailing white space from the returned string, if the original string contains 8 or fewer characters \item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the source) should be accessed as an apparent radial velocity or a redshift. Note, any existing software that assumes that SourceVel always represents a velocity in km/s should be changed to allow for the possibility of SourceVel representing a redshift value. \end{enumerate} \subsection{Changes Introduced in V4.4} The following describes the most significant changes which occurred in the AST library between versions V4.3 and V4.4: \begin{enumerate} \item The \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame} or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as the ``template'' when calling AST\_FINDFRAME, and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the current Frame is a CmpFrame), then the component Frames within the CmpFrame will be searched for an instance of the supplied template Frame, and, if found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the required axes from the CmpFrame) will be returned by AST\_FINDFRAME. Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template Frame must be set so that they cover a range that includes the number of axes in the target CmpFrame. \item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes now allow the MaxAxes and MinAxes attributes to be set freely to any value. In previous versions of AST, any attempt to change the value of MinAxes or MaxAxes was ignored, resulting in them always taking the default values. \item The DSBSpecFrame class has a new attribute called AlignSB that specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when aligning two DSBSpecFrames using \htmlref{AST\_CONVERT}{AST\_CONVERT}. \item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to store a value for the difference between the UT1 and UTC timescales at the epoch referred to by the Frame. \item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and \htmlref{ObsLon}{ObsLon} has been increased. \item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This attribute is used to control how two SkyFrames are aligned by AST\_CONVERT. If the template and target SkyFrames both have a non-zero value for AlignOffset, then alignment occurs between the offset coordinate systems (that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). \item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be used to force exterior (rather than interior) tick marks to be produced. By default, exterior ticks are only produced if this would result in more than 3 tick marks being drawn. \item The TimeFrame class now supports conversion between angle based timescales such as UT1 and atomic based timescales such as UTC. \end{enumerate} \subsection{Changes Introduced in V4.5} The following describes the most significant changes that occurred in the AST library between versions V4.4 and V4.5: \begin{enumerate} \item All FITS-CLASS headers are now created with a frequency axis. If the \htmlref{FrameSet}{FrameSet} supplied to \htmlref{AST\_WRITE}{AST\_WRITE} contains a velocity axis (or any other form of spectral axis) it will be converted to an equivalent frequency axis before being used to create the FITS-CLASS header. \item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed from the velocity of the source to the velocity of the reference channel. \item Addition of a new method call \htmlref{AST\_PURGEWCS}{AST\_PURGEWCS} to the \htmlref{FitsChan}{FitsChan} class. This method removes all WCS-related header cards from a FitsChan. \item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used to comminicate context information between an application and any graphics functions registered with the Plot class via the \htmlref{AST\_GRFSET}{AST\_GRFSET} routine. \item Functions registered with the Plot class using AST\_GRFSET now take a new additional integer parameter, ``grfcon''. The Plot class sets this parameter to the value of the Plot's GrfContext attribute before calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE THAT USES AST\_GRFSET TO BE MODIFIED TO INCLUDE THE NEW PARAMETER. \item The AST\_REBINSEQ routines now have an extra parameter that is used to record the total number of input data values added into the output array. This is necessary to correct a flaw in the calculation of output variances based on the spread of input values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO INCLUDE THE NEW PARAMETER (CALLED "NUSED"). \item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection. \item A new flag ``AST\_\_VARWGT'' can be supplied to AST\_REBINSEQ. This causes the input data values to be weighted using the reciprocals of the input variances (if supplied). \item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that returns the normalised value of the Unit attribute for an axis. Here, ``normalisation'' means cancelling redundant units, etc. So for instance, a Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''. \item A new routine \htmlref{AST\_SHOWMESH}{AST\_SHOWMESH} has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering the surface of a Region by writing out a table of axis values to standard output. \item The Plot class now honours the value of the LabelUp attribute even if numerical labels are placed around the edge of the Plot. Previously LabelUp was only used if the labels were drawn within the interior of the plot. The LabelUp attribute controls whether numerical labels are drawn horizontally or parallel to the axis they describe. \item A bug has been fixed that could segmentation violations when setting attribute values. \end{enumerate} \subsection{Changes Introduced in V4.6} The following describes the most significant changes which have occurred in the AST library between versions V4.5 and V4.6: \begin{enumerate} \item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset from UTC to Local Time is specified by a new TimeFrame attribute called \htmlref{LTOffset}{LTOffset}. \item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows the creation of 3-dimensional annotated coordinate grids. \item A correction for diurnal aberration is now included when converting between AZEL and other celestial coordinate systems. The correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the geodetic latitude of the observer). \item A bug has been fixed which caused the DUT1 attribute to be ignored by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other celestial coordinate systems. \end{enumerate} \subsection{Changes Introduced in V5.0} The following describes the most significant changes which occurred in the AST library between versions V4.6 and V5.0: \begin{enumerate} \item The AST library is now thread-safe (assuming that the POSIX pthreads library is available when AST is built). Many of the macros defined in the ast.h header file have changed. It is therefore necessary to re-compile all source code that includes ast.h. \item New methods astLock and astUnlock allow an AST \htmlref{Object}{Object} to be locked for exclusive use by a thread. \item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset from UTC to Local Time is specified by a new TimeFrame attribute called \htmlref{LTOffset}{LTOffset}. \item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls whether or not to report an error if unexpected data items are found within an AST Object description read from an external data source. Note, the default behaviour is now not to report such errors. This differs from previous versions of AST which always reported an error is unexpected input items were encountered. \end{enumerate} \subsection{Changes Introduced in V5.1} The following describes the most significant changes which occurred in the AST library between versions V5.0 and V5.1: \begin{enumerate} \item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval} could be used for this purpose. \item Improvements have been made to the way that Prisms are simplified when \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} is called. The changes mean that more types of Prism will now simplify into a simpler class of Region. \item The \htmlref{PointList}{PointList} class has a new method, AST\_POINTS, that copies the axis values from the PointList into a supplied array. \item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that gives the number of points stored in the PointList. \item The handling of warnings within different classes of \htmlref{Channel}{Channel} has been rationalised. The XmlStrict attribute and AST\_XMLWARNINGS function have been removed. The same functionality is now available via the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new attribute called \htmlref{ReportLevel}{ReportLevel}, and the new \htmlref{AST\_WARNINGS}{AST\_WARNINGS} function. This new function can be used on any class of Channel. Teh \htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as header cards within the FitsChan, but it also now stores warnings in the parent Channel structure, from where they can be retrieved using the AST\_WARNINGS function. \item A new function called AST\_INTERCEPT has been added to the \htmlref{Frame}{Frame} class. This function finds the point of intersection beteeen two geodesic curves. \item A bug in the type-checking of Objects passed as arguments to constructor functions has been fixed. This bug could lead to applications crashing or showing strange behaviour if an inappropriate class of \htmlref{Object}{Object} was supplied as an argument to a constructor. \item The \htmlref{AST\_PICKAXES}{AST\_PICKAXES} function will now return a Region, if possible, when applied to a Region. If this is not possible, a Frame will be returned as before. \item The choice of default tick-mark for time axes has been improved, to avoid previous issues which could result in no suitable gap being found, or inappropriate tick marks when using formatted dates. \item A new function called \htmlref{AST\_TESTFITS}{AST\_TESTFITS} has been added to the FitsChan class. This function tests a FitsChan to see if it contains a defined value for specified FITS keyword. \item The AST\_\_UNDEF parameters used to flag undefined FITS keyword values have been removed. Use the new AST\_TESTFITS function instead. \end{enumerate} \subsection{Changes Introduced in V5.2} The following describes the most significant changes which occurred in the AST library between versions V5.1 and V5.2: \begin{enumerate} \item A new method called \htmlref{AST\_SETFITSCM}{AST\_SETFITSCM} has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a FitsChan (that is, a card with no keyword name or equals sign). \item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It records the geodetic altitude of the observer, in metres. It defaults to zero. It is used when converting times to or from the TDB timescale, or converting spectral positions to or from the topocentric rest frame, or converting sky positions to or from horizon coordinates. The FitsChan class will include its effect when creating a set of values for the OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a set of OBSGEO-X/Y/Z keyword values from a FITS header. \item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap} conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument - the observer's geodetic altitude. \item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the IVOA STC definition of a Polygon. Specifically, the inside of a polygon is now the area to the left of each edge as the vertices are traversed in an anti-clockwise manner, as seen from the inside of the celestial sphere. Previously, AST used the anti-clockwise convention, but viewed from the outside of the celestial sphere instead of the inside. Any Polygon saved using previous versions of AST will be identified and negated automatically when read by AST V5.2. \item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows conversion of suitable AST Objects to and from IVOA STC-S format. \item A new method called \htmlref{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS} has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound) Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either removes them, or replaces them with UnitMaps (or equivalent Frames). It can be used to remove the masking effects of Regions from a compound Mapping or Frame. \item A new method called \htmlref{AST\_DOWNSIZE}{AST\_DOWNSIZE} has been added to the Polygon class. It produces a new Polygon that contains a subset of the vertices in the supplied Polygon. The subset is chosen to retain the main features of the supplied Polygion, in so far as that is possible, within specified constraints. \item A new constructor called AST\_OUTLINE has been added to the Polygon class. Given a 2D data array, it identifies the boundary of a region within the array that holds pixels with specified values. It then creates a new Polygon to describe this boundary to a specified accuracy. \item A new set of methods, called AST\_MAPGETELEM has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector valued entry to be returned. \item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It controls whether the AST\_MAPGET... family of functions report an error if an entry with the requested key does not exist in the KeyMap. \end{enumerate} \subsection{Changes Introduced in V5.3} The following describes the most significant changes which occurred in the AST library between versions V5.2 and V5.3: \begin{enumerate} \item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} and \htmlref{AST\_CONVERT}{AST\_CONVERT} functions have been changed. The changes mean that a Frame can now be aligned with an instance of a sub-class of Frame, so long as the number of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic 2-dimensional Frame with Domain ``SKY'' will now align succesfully with a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a \htmlref{UnitMap}{UnitMap}. \item Added method \htmlref{AST\_MATCHAXES}{AST\_MATCHAXES} to the Frame class. This method allows corresponding axes within two Frames to be identified. \item The \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}. \end{enumerate} \subsection{Changes Introduced in V5.3-1} The following describes the most significant changes which have occurred in the AST library between versions V5.3 and V5.3-1: \begin{enumerate} \item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A new method called \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU} will store an entry with undefined value in a keymap. Methods that retrieve values from a KeyMap (AST\_MAPGET0, etc.) ignore entries with undefined values when searching for an entry with a given key. \item The KeyMap class has a new method called \htmlref{AST\_MAPCOPY}{AST\_MAPCOPY} that copies entries from one KeyMap to another KeyMap. \item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If .TRUE., an error is reported if an attempt is made to add any new entries to a KeyMap (the value associated with any old entry may still be changed without error). The default is .FALSE. \item The \htmlref{Object}{Object} class has a new method called astHasAttribute/\htmlref{AST\_HASATTRIBUTE}{AST\_HASATTRIBUTE} that returns a boolean value indicating if a specified Object has a named attribute. \item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called IsLatAxis and IsLonAxis that can be used to determine the nature of a specified SkyFrame axis. \item A bug has been fixed in the AST\_REBIN(SEQ) methods that could cause flux to be lost from the edges of the supplied array. \item A bug has been fixed in the AST\_REBIN(SEQ) methods that caused the first user supplied parameter to be interpreted as the full width of the spreading kernel, rather than the half-width. \item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except that units strings are still case sensitive). \item A new \htmlref{Mapping}{Mapping} method, \htmlref{AST\_QUADAPPROX}{AST\_QUADAPPROX}, produces a quadratic least-squares fit to a 2D Mapping. \item A new Mapping method, \htmlref{AST\_SKYOFFSETMAP}{AST\_SKYOFFSETMAP}, produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame coordinates. \item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation in the text created by \htmlref{AST\_WRITE}{AST\_WRITE}. The StcsIndent and XmlIndent attributes have been removed. \item All classes of Channel now use the string ``'' to represent the floating point value AST\_\_BAD, rather than the literal formatted value (typically ``-1.79769313486232e+308'' ). \item The KeyMap class now uses the string ``'' to represent the floating point value AST\_\_BAD, rather than the literal formatted value (typically ``-1.79769313486232e+308'' ). \item The KeyMap class has a new method called AST\_MAPPUTELEM that allows a value to be put into a single element of a vector entry in a KeyMap. The vector entry is extended automatically to hold the new element if required. \item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator frequency is less than the absoliute value of the intermediate frequency. \end{enumerate} \subsection{Changes Introduced in V5.3-2} The following describes the most significant changes which occurred in the AST library between versions V5.3-1 and V5.3-2: \begin{enumerate} \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength axes to be assigned the units ``m/s'' when reading WCS information from a FITS header. \item The \htmlref{AST\_SET}{AST\_SET} routine now allows literal commas to be included in string attribute values. String attribute values that include a literal comma should be enclosed in quotation marks. \item A bug in FitsChan has been fixed that caused ``-SIN'' projection codes within FITS-WCS headers to be mis-interpreted, resulting in no \htmlref{FrameSet}{FrameSet} being read by astRead. \item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls the order in which keys are returned by the \htmlref{AST\_MAPKEY}{AST\_MAPKEY} function. Keys can be sorted alphabetically or by age, or left unsorted. \item Access to KeyMaps holding thousands of entries is now significantly faster. \item KeyMaps can now hold word (i.e. INTEGER*2) values. \end{enumerate} \subsection{Changes Introduced in V5.4-0} The following describes the most significant changes which occurred in the AST library between versions V5.3-2 and V5.4-0: \begin{enumerate} \item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}. See the documentation for TabOK for more information. \item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in which each entry represents a cell in a two-dimensional table. \item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a Table that has an associated FitsChan holding headers appropriate to a FITS binary table. \item KeyMaps can now hold byte values. These are held in variables of type BYTE. \item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to make the handling of keys case insensitive. \item a memory leak associated with the use of the AST\_MAPPUTELEM functions has been fixed. \item A new method called \htmlref{AST\_MAPRENAME}{AST\_MAPRENAME} has been added to rename existing entry in a KeyMap. \end{enumerate} \subsection{Changes Introduced in V5.5-0} The following describes the most significant changes which occurred in the AST library between versions V5.4-0 and V5.5-0: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather than a boolean value. If TabOK is set to a non-zero positive integer before invoking the \htmlref{AST\_WRITE}{AST\_WRITE} method, its value is used as the version number for any table that is created as a consequence of the write operation. This is the value stored in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the binary table header. In previous versions of AST, the value used for these headers could not be controlled and was fixed at 1. If TabOK is set to a negative or zero value, the -TAB algorithm will not be supported by either the AST\_WRITE or \htmlref{AST\_READ}{AST\_READ} methods. \end{enumerate} \subsection{Changes Introduced in V5.6-0} The following describes the most significant changes which occurred in the AST library between versions V5.5-0 and V5.6-0: \begin{enumerate} \item New routines \htmlref{AST\_BBUF}{AST\_BBUF} and \htmlref{AST\_EBUF}{AST\_EBUF} have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical output produced by other Plot methods. \item New functions astGBBuf and astGEBuf have been added to the interface defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf functions. This means that applications that use the \verb+-grf_v3.2+ switch should continue to build without any change. However, the new public routines AST\_BBUF and AST\_EBUF will report an error unless the new grf functions are implemented. If you choose to implement them, you should modify your linking procedure to use the \verb+-grf+ (or \verb+-grf_v5.6+ ) switch in place of the older \verb+-grf_v3.2+ switch. See the description of the ast\_link command for details of these switches. \item New method \htmlref{AST\_GETREGIONMESH}{AST\_GETREGIONMESH} returns a set of positions covering the boundary, or volume, of a supplied \htmlref{Region}{Region}. \end{enumerate} \subsection{ChangesIntroduced in V5.6-1} The following describes the most significant changes which occurred in the AST library between versions V5.6-0 and V5.6-1: \begin{enumerate} \item Tables can now have any number of parameters describing the global properties of the \htmlref{Table}{Table}. \item Frames now interpret the unit string ``A'' as meaning ``Ampere'' rather than ``Angstrom'', as specified by FITS-WCS paper I. \item A bug has been fixed in the \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match a target frame of a less specialised class. For example, this bug would allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer happens. \end{enumerate} \subsection{Changes Introduced in V5.7-0} The following describes the most significant changes which occurred in the AST library between versions V5.6-1 and V5.7-0: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has been extended to include reading TNX headers that use a Chebyshev representation for the distortion polynomial. \item The FitsChan class support for the IRAF-specific ``ZPX'' projection has been extended to include reading ZPX headers that use simple or Chebyshev representation for the distortion polynomial. \item A bug has been fixed in the FitsChan class that caused headers including the Spitzer ``-SIP'' distortion code to be read incorrectly if no inverse polynomial was specified in the header. \item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It can be used to indicate that FITS headers that specify a TAN projection should be interpreted according to the ``distorted TAN'' convention included in an early draft of FITS-WCS paper II. Such headers are created by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}). \item The \htmlref{PolyMap}{PolyMap} class now provides a method called \htmlref{AST\_POLYTRAN}{AST\_POLYTRAN} that adds an inverse transformation to a PolyMap by sampling the forward transformation on a regular grid, and then fitting a polynomial function from the resulting output values to the grid of input values. \end{enumerate} \subsection{Changes Introduced in V5.7-1} The following describes the most significant changes which occurred in the AST library between versions V5.7-0 and V5.7-1: \begin{enumerate} \item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified text files, without the need to provide source and sink functions when the Channel is created. The files to use are specified by the new attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}. \item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header. \item - If the FitsChan astRead method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, the FitsChan class will now use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the inverse polynomial correction. \end{enumerate} \subsection{Changes Introduced in V5.7-2} The following describes the most significant changes which occurred in the AST library between versions V5.7-1 and V5.7-2: \begin{enumerate} \item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to evaluate the inverse the inverse transformation if no inverse transformation is defined when the PolyMap is created. \item The \htmlref{FitsChan}{FitsChan} class has a new method \htmlref{AST\_WRITEFITS}{AST\_WRITEFITS} which writes out all cards currently in the FitsChan to the associated external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the sink function supplied when the FitsChan was created), and then empties the FitsChan. \item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which holds the number of keywords for which values are held in a FitsChan. \item The FitsChan AST\_GETFITS methods can now be used to returned the value of the current card. \item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which holds the data type of the keyword value for the current card. \item The FitsChan class has a new method \htmlref{AST\_READFITS}{AST\_READFITS} which forces the FitsChan to reads cards from the associated external source and appends them to the end of the FitsChan. \item - If the FitsChan astRead method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, and for which the PolyTran method of the PolyMap class fails to create an accurate estimate of the inverse polynomial correction, then an iterative method will be used to evaluate the inverse correction for each point transformed. \end{enumerate} \subsection{Changes Introduced in V6.0} The following describes the most significant changes which occurred in the AST library between versions V5.7-2 and V6.0: \begin{enumerate} \item This version of AST is the first that can be used with the Python AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}. \item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the non-standard ``TPV'' projection code within a CTYPE keyword value. This code is used by SCAMP (see www.astromatic.net/software/scamp) to represent a distorted TAN projection. \item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as incorrectly rotated numerical axis labels) if the graphics coordinates have unequal scales on the X and Y axes. - The graphics escape sequences used to produce graphical sky axis labels can now be changed using the new routine \htmlref{AST\_TUNEC}{AST\_TUNEC}. \end{enumerate} \subsection{Changes Introduced in V6.0-1} The following describes the most significant changes which occurred in the AST library between versions V6.0 and V6.0-1: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion code within FITS headers that describe non-celestial axes, as well as celestial axes. \item A bug has been fixed that could cause inappropriate equinox values to be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set. \item The versioning string for AST has changed from ``$.-$'' to ``$..$''. \end{enumerate} \subsection{Changes Introduced in V7.0.0} The following describes the most significant changes which occurred in the AST library between versions V6.0-1 and V7.0.0: \begin{enumerate} \item Fundamental positional astronomy calculations are now performed using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{} otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB library re-written in C). Copies of these libraries are bundled with AST and so do not need to be obtained or built separately, although external copies of SOFA and PAL can be used if necessary by including the ``\texttt{--with-external\_pal}'' option when configuring AST. \end{enumerate} \subsection{Changes Introduced in V7.0.1} The following describes the most significant changes which occurred in the AST library between versions V7.0.0 and V7.0.1: \begin{enumerate} \item The levmar and wcslib code distributed within AST is now stored in the main AST library (libast.so) rather than in separate libraries. \end{enumerate} \subsection{Changes Introduced in V7.0.2} The following describes the most significant changes which occurred in the AST library between versions V7.0.1 and V7.0.2: \begin{enumerate} \item The libast\_pal library is no longer built if the ``--with-external\_pal'' option is used when AST is configured. \end{enumerate} \subsection{Changes Introduced in V7.0.3} The following describes the most significant changes which occurred in the AST library between versions V7.0.2 and V7.0.3: \begin{enumerate} \item A bug has been fixed which could cause an incorrect axis to be used when accessing axis attributes within CmpFrames. This could happen if axes within the \htmlref{CmpFrame}{CmpFrame} have been permuted. \item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two values of the SkyRef and/or SkyRefP attributes to be reversed. \item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately. Previously, component Regions nested deeply inside a CmpRegion may have been completely or partially ignored. \item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation violation if the MinTick attribute was set to zero. \item The astResampleX set of methods now includes astResampleK and astResampleUK that handles 64 bit integer data. \end{enumerate} \subsection{Changes Introduced in V7.0.4} The following describes the most significant changes which occurred in the AST library between versions V7.0.3 and V7.0.4: \begin{enumerate} \item The previously private grf3d.h header file is now installed into prefix/include. \end{enumerate} \subsection{Changes Introduced in V7.0.5} The following describes the most significant changes which occurred in the AST library between versions V7.0.4 and V7.0.5: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO convention for representing distorted TAN projections, based on the use of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial. \end{enumerate} \subsection{Changes Introduced in V7.0.6} The following describes the most significant changes which occurred in the AST library between versions V7.0.5 and V7.0.6: \begin{enumerate} \item A bug has been fixed in astRebinSeq which could result in incorrect normalisation of the final binned data and variance values. \item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1 and CNPIX2 now default to zero if absent. Previously an error was reported. \end{enumerate} \subsection{Changes Introduced in V7.1.0} The following describes the most significant changes which occurred in the AST library between versions V7.0.6 and V7.1.0: \begin{enumerate} \item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied when calling AST\_REBINSEQ. Without this flag, each output value is a weighted mean of the neighbouring input values. \item A new flag AST\_\_NONORM can be used with astRebinSeq to indicate that normalisation of the output arrays is not required. In this case no weights array need be supplied. \item A bug has been fixed in \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} routine that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet} when the AST\_\_ALLFRAMES flag is supplied for the IFRAME argument. \item The \htmlref{AST\_RATE}{AST\_RATE} function has been re-written to make it faster and more reliable. \end{enumerate} \subsection{Changes Introduced in V7.1.1} The following describes the most significant changes which occurred in the AST library between versions V7.1.0 and V7.1.1: \begin{enumerate} \item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute \htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions are now created - one for the offset coordinates and one for the absolute coordinates. If such a header is subsequently read back into AST, the original offset SkyFrame is recreated. \item A bug has been fixed in FitsChan that caused inappropriate CTYPE values to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a SkyFrame with \htmlref{System}{System}=Unknown). \end{enumerate} \subsection{Changes Introduced in V7.2.0} The following describes the most significant changes which occurred in the AST library between versions V7.1.1 and V7.2.0: \begin{enumerate} \item A new method call \htmlref{AST\_MAPDEFINED}{AST\_MAPDEFINED} has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has a defined value in a given KeyMap. \end{enumerate} \subsection{Changes Introduced in V7.3.0} The following describes the most significant changes which occurred in the AST library between versions V7.2.0 and V7.3.0: \begin{enumerate} \item The interface for the AST\_REBINSEQ family of routines has been changed in order to allow a greater number of pixels to be pasted into the output array. The NUSED parameter is now an INTEGER*8 variable, instead of an INTEGER. APPLICATION CODE SHOULD BE CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC BEHAVIOUR. \item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be associated with multiple Mappings, any one of which can be used to connect the Frame to the other Frames in the FrameSet. The choice of which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the FrameSet class. \item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident} attribute are now left unchanged by the c astSimplify function. f \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY} routine. \end{enumerate} \subsection{Changes Introduced in V7.3.1} The following describes the most significant changes which occurred in the AST library between versions V7.3.0 and V7.3.1: \begin{enumerate} \item Fix a bug that could cauise a segmentation violation when reading certain FITS headers that use a TNX projection. \end{enumerate} \subsection{Changes Introduced in V7.3.2} The following describes the most significant changes which occurred in the AST library between versions V7.3.1 and V7.3.2: \begin{enumerate} \item Fix support for reading FITS header that use a GLS projection. Previously, an incorrect transformation was used for such projections if any CRVAL or CROTA value was non-zero. \item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and ``KeyAgeDown'' that retain the position of an existing entry if its value is changed. See the \htmlref{SortBy}{SortBy} attribute. \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords for sky axes to be treated as radians rather than degrees when reading a FITS header, if the corresponding CTYPE values included no projection code. \end{enumerate} \subsection{Changes Introduced in V7.3.3} The following describes the most significant changes which occurred in the AST library between versions V7.3.2 and V7.3.3: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold the keyword name and comment of the current card. \item When using the FitsChan class to read FITS-WCS headers that include polynomial distortion in the SIP format, any inverse transformation specified in the header is now ignored and a new inverse is created to replace it based on the supplied forward transformation. Previously, an inverse was created only if the header did not include an inverse. The accuracy of the inverse transformation has also been improved, although it may now be slower to evaluate in some circumstances. \end{enumerate} \subsection{Changes Introduced in V7.3.4} The following describes the most significant changes which occurred in the AST library between versions V7.3.3 and V7.3.4: \begin{enumerate} \item By default, the simplification of Polygons no longer checks that the edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices}, can be set to zero in order to re-instate this check. \item The \htmlref{Polygon}{Polygon} class has a new mathod, AST\_CONVEX, that returns a Polygon representing the shortest polygon (i.e. convex hull) enclosing a specified set of pixel values within a supplied array. \end{enumerate} \subsection{Changes Introduced in V8.0.0} The following describes the most significant changes which occurred in the AST library between versions V7.3.4 and V8.0.0: \begin{enumerate} \item AST is now distributed under the Lesser GPL licence. \item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform least squares fitting of N-dimensional polynomials. \item Use of the IAU SOFA library has been replaced by ERFA library, which is a re-badged copy of SOFA distributed under a less restrictive license. A copy of ERFA is included within AST. \end{enumerate} \subsection{Changes Introduced in V8.0.1} The following describes the most significant changes which occurred in the AST library between versions V8.0.0 and V8.0.1: \begin{enumerate} \item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}. \item The order of WCS axes within new FITS-WCS headers created by astWrite can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}. \item Supported added for FITS XPH (polar HEALPIX) projection. \item The AST\_REBIN and AST\_REBINSEQ family of functions now include support for arrays with \_BYTE (byte) and and \_UBYTE (unsigned byte) data types. \end{enumerate} \subsection{Changes Introduced in V8.0.2} The changes that occurred in the AST library between versions V8.0.1 and V8.0.2 only affect the C interface. The Fortran interface remains the same as V8.0.1. \subsection{Changes Introduced in V8.0.3} The following describes the most significant changes which occurred in the AST library between versions V8.0.2 and V8.0.3: \begin{enumerate} \item Methods AST\_REBIN, AST\_REBINSEQ, AST\_RESAMPLE and \htmlref{AST\_TRANGRID}{AST\_TRANGRID}. now report an error if an array is specified that has more pixels than can be counted by a 32 bit integer. \item The hypertext documentation is now generated using Tex4HT rather than latex2html. The format of the hypertext docs has changed significantly. \item Another bug fix associated with reading CAR projections from FITS-WCS headers. \item Trailing spaces supplied within attribute setting strings are now ignored. \end{enumerate} \subsection{Changes Introduced in V8.0.4} The following describes the most significant changes which occurred in the AST library between versions V8.0.3 and V8.0.4: \begin{enumerate} \item The behaviour of the \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME} method has been changed slightly. Previously, AST\_ADDFRAME modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and \htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes to the current Frame of the modified FrameSet also affected the supplied Frame object. Now, deep copies of the Mapping and Frame objects (rather than references) are stored within the modified FrameSet. This means that subsequent changes to the modified FrameSet will now have no effect on the supplied Frame. \item The choice of default tick-mark gaps for time axes has been improved, to avoid a previous issue which could result in no suitable gap being found. - A new method called AST\_REGIONOUTLINE has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST \htmlref{Region}{Region}. \item A bug has been fixed that could cause astSimplfy to enter an infinite loop. \item Some improvements have been made to the Mapping simplification process that allow more Mappings to be simplified. \item The Frame class has a new read-only attribute called InternalUnit, which gives the units used for the unformatted (i.e. floating-point) axis values used internally by application code. For most Frames, the InternalUnit value is just the same as the Unit value (i.e. formatted and unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of Unit, indicating that floating-point SkyFrame axis values are always in units of radians. \item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies the relative error of the values in the table. It is used to decide if the LutMap can be simplified to a straight line. \end{enumerate} \subsection{Changes Introduced in V8.0.5} The following describes the most significant changes which occurred in the AST library between versions V8.0.4 and V8.0.5: \begin{enumerate} \item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies the smallest significant distance within the SkyFrame. It is used to decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit transformation. The default value is 0.001 arc-seconds. \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal characters within FITS keyword names (i.e. characters not allowed by the FITS standard) being detected. This bug could under some circumstances cause a subsequent segmentation violation to occur. \item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS keyword name is encountered that contains any illegal characters. See attribute ``\htmlref{Warnings}{Warnings}'' and routine ``\htmlref{AST\_WARNINGS}{AST\_WARNINGS}''. \end{enumerate} \subsection{Changes Introduced in V8.1.0} The following describes the most significant changes which occurred in the AST library between versions V8.0.5 and V8.1.0: \begin{enumerate} \item The configure script has a new option ``--without-fortran'' that allows AST to be built in situations where no Fortran compiler is available. The resulting library has no Fortran interface and so cannot be used within Fortran applications. Also, the link scripts do not attempt to include the fortran runtime libraries. \end{enumerate} \subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes Introduced in V8.2} The following describes the most significant changes which occurred in the AST library between versions V8.1.0 and V8.2.0: \begin{enumerate} \item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts a vector to a unit vector relative to a specified centre, plus length. A UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates represent a unit vector parallel to the supplied input vector, and the (N+1)'th output coordinate is the length of the input vector. \item The restriction that Mappings are immutable has been extended to all Mapping classes. This means that attributes representing parameters of a Mapping's forward or inverse transformation cannot be changed after the Mapping has been created. In order to minimise the risk to existing software, this rule does not apply to Mappings that have not yet been included in other objects such as CmpMaps or FrameSets, or which have not yet been cloned. In other words, an error is reported if an attempt is made to change the nature of a Mapping's transformation, but only if the reference count of the Mapping is greater than one. The Mapping classes affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}. \end{enumerate} \subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes Introduced in V8.3} The following describes the most significant changes which have occurred in the AST library between versions V8.2.0 and V8.3.0 (the current version): \begin{enumerate} \item A new method called \htmlref{AST\_AXNORM}{AST\_AXNORM} has been added to the \htmlref{Frame}{Frame} class that normalises an array of axis values. When used with SkyFrames, it allows longitude values to be normalised into the shortest range. \item A bug has been fixed in the Fortran include file AST\_PAR that caused constants related to $\pi$ to be defined as single rather than double precision. \item A bug has been fixed in the astGetRegionBounds method that could cause the wrong bounds to be returned for regions spanning a longitude = zero singularity. \end{enumerate} % Programs which are statically linked will need to be re-linked in % order to take advantage of these new facilities. \end{document} ast-8.3.0/ems.h0000664000175000017500000001071613004147321010171 00000000000000/*+ * Name: * ems.h * Purpose: * EMS_ C interface header file. * Language: * Starlink ANSI C * Description: * This include file contains the function prototypes for all * EMS C interface routines and defines EMS__VERSN to be the major * version number * Authors: * PCTR: P.C.T. Rees (STARLINK) * AJC: A.J.Chipperfield (STARLINK) * TIMJ: Tim Jenness (JAC, Hawaii) * {enter_new_authors_here} * History: * 19-SEP-1990 (PCTR): * Original version. * 21-JUN-1991 (PCTR): * Made all given character strings type "const". * 5-OCT-1993 (PCTR): * Updated for Vn. 1.2-3 * 28-SEP-1994 (AJC): * V1.4 Added ems_facer_c and ems_errno_c * 21-JUN-1995 (AJC): * V1.5 Added ems1_starf_c * 13-MAY-1999 (AJC): * Added the emsXxx form of name * and #define old_names = new_names * Removed ems_tune/gtune/show/_c * Added ems1_get_facility_error * 27-JUL-2001 (AJC): * Removed emsFmtx * Add emsExpnd, emsTune * 13-AUG-2001 (AJC): * Removed emsFioer * #define EMS__VERSN * 20-SEP-2001 (AJC): * Added emsSetnc and point ems_setc_c at it * 3-MAR-2006 (TIMJ): * Add emsSetu / emsSetp / emsSeti64 * 30-JUL-2008 (PWD): * Added emsGtune. * 31-JUL-2008 (PWD): * Added emsStune and changed emsGtune to return the value as a result. * Marked emsTune as deprecated. * 10-SEP-2008 (TIMJ): * Remove fortran prototypes. Should not be in a public include file. * 16-SEP-2008 (TIMJ): * Remove 3 arg version of emsSetc * {enter_changes_here} * Bugs: * {note_any_bugs_here} *- */ #ifndef EMS_DEFINED #define EMS_DEFINED /* ANSI types */ #include #include #include /* EMS Major Version */ #define EMS__VERSN 2 /* Function Prototypes: */ void emsAnnul( int *status ); void emsBegin( int *status ); void emsEload( char *param, int *parlen, char *opstr, int *oplen, int *status ); void emsEnd( int * status ); void emsErrno( const char *token, int errval ); void emsExpnd( const char *text, char *opstr, const int maxlen, int *oplen, int *status ); void emsFacer( const char *token, int status ); int emsGtune( const char *key, int *status ); void emsLevel( int *level ); void emsMark( void ); void emsMload( const char *msg, const char *text, char *opstr, int *oplen, int *status ); void emsRenew( void ); void emsRep( const char *err, const char *text, int *status ); void emsRlse( void ); void emsSetc( const char *token, const char *cvalue ); void emsSetnc( const char *token, const char *cvalue, int mxchar ); void emsSetd( const char *token, double dvalue ); void emsSeti( const char *token, int ivalue ); void emsSeti64( const char *token, int64_t ivalue ); void emsSetl( const char *token, int lvalue ); void emsSetr( const char *token, float rvalue ); void emsSetp( const char *token, void * pvalue ); void emsSetu( const char *token, unsigned int ivalue ); void emsStat( int *status ); void emsSyser( const char *token, int systat ); int emsStune( const char *key, const int value, int *status ); /* Deprecated function. */ void emsTune( const char *key, const int value, int *status ); /* Internal Functions */ /* Not for general use */ int ems1Starf( const char *envar, const char *relpath, const char *acmode, char **filename, int *pathlen ); void ems1_get_facility_error( unsigned int errcode, char **facility_name, char **error_ident, char **error_text ); /* Required by MERS. Not to be used by anyone else */ void ems1Rform( const char *text, const int maxlen, int *iposn, char *string, int *strlength ); void ems1Gesc( const char *escchr, const char *string, int *iposn ); void ems1Gnam( const char *string, int *iposn, char *name, int *namlen, int *status); #endif /* EMS_DEFINED */ ast-8.3.0/axis.c0000664000175000017500000033702413004147321010350 00000000000000/* *class++ * Name: * Axis * Purpose: * Store axis information. * Constructor Function: * None. * Description: * The Axis class is used to store information associated with a * particular axis of a Frame. It is used internally by the AST * library and has no constructor function. You should encounter it c only within textual output (e.g. from astWrite). f only within textual output (e.g. from AST_WRITE). * Inheritance: * The Axis class inherits from the Object class. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: B.S. Berry (Starlink) * History: * 1-MAR-1996 (RFWS): * Original version. * 10-SEP-1996 (RFWS): * Added I/O facilities. * 11-SEP-1996 (RFWS): * Added astAxisGap (written by DSB). * 25-FEB-1998 (RFWS): * Added astAxisUnformat. * 29-AUG-2001 (DSB): * Added AxisDistance and AxisOffset. * 20-OCT-2002 (DSB): * Added Top and Bottom attributes. * 8-JAN-2003 (DSB): * - Changed private InitVtab method to protected astInitAxisVtab * method. * - Include descriptive label for units string within a Dump. * 24-JAN-2004 (DSB): * - Added astAxisFields. * - Added argument "fmt" to definition of AxisAbbrev. * 3-FEB-2004 (DSB): * - Added "log" formatting using the "&" flag character in the * Format string. * 15-SEP-2004 (DSB): * - If a format string is set which includes a wildcard precision * value (".*"), then use the Digits value to determine the precision * to be used. * - If the conversion code is of integer type (e.g. "%d") cast value * to integer before printing. * 2-FEB-2005 (DSB): * - Avoid using astStore to allocate more storage than is supplied * in the "data" pointer. This can cause access violations since * astStore will then read beyond the end of the "data" area. * 15-MAR-2005 (DSB): * - Avoid exponents in log format labels which are close to zero but * not quite zero. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 30-JUN-2006 (DSB): * Guard against a null "str1" value in AxisAbbrev. * 17-APR-2015 (DSB): * Added astAxisCentre. * 26-OCT-2016 (DSB): * Added astAxisNormValues. *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 Axis /* Header files. */ /* ============= */ #include "ast_err.h" /* Error code definitions */ /* 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" /* Object interface (parent class) */ #include "pointset.h" /* Sets of coordinates (for AST__BAD) */ #include "channel.h" /* I/O channels */ #include "axis.h" /* Interface definition for this class */ #include "unit.h" /* Definitions of physical units */ #include "globals.h" /* Thread-safe global data access */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include #include #include /* 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 const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* Plain text equivalents. */ static const char *log_txt = "10^"; /* 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->GetDefaultFormat_Buff[ 0 ] = 0; \ globals->AxisFormat_Buff[ 0 ] = 0; \ globals->GetAxisNormUnit_Buff[ 0 ] = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Axis) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Axis,Class_Init) #define class_vtab astGLOBAL(Axis,Class_Vtab) #define getdefaultformat_buff astGLOBAL(Axis,GetDefaultFormat_Buff) #define axisformat_buff astGLOBAL(Axis,AxisFormat_Buff) #define getaxisnormunit_buff astGLOBAL(Axis,GetAxisNormUnit_Buff) #define getattrib_buff astGLOBAL(Axis,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getdefaultformat_buff[ AST__AXIS_GETDEFAULTFORMAT_BUFF_LEN + 1 ]; static char axisformat_buff[ AST__AXIS_GETDEFAULTFORMAT_BUFF_LEN + 1 ]; static char getaxisnormunit_buff[ AST__AXIS_GETAXISNORMUNIT_BUFF_LEN + 1 ]; static char getattrib_buff[ AST__AXIS_GETATTRIB_BUFF_LEN + 1 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstAxisVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstAxis *astAxisId_( const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static const char *AxisAbbrev( AstAxis *, const char *, const char *, const char *, int * ); static const char *AxisFormat( AstAxis *, double, int * ); static int GetObjSize( AstObject *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetAxisFormat( AstAxis *, int * ); static const char *GetAxisLabel( AstAxis *, int * ); static const char *GetAxisSymbol( AstAxis *, int * ); static const char *GetAxisUnit( AstAxis *, int * ); static const char *GetAxisInternalUnit( AstAxis *, int * ); static const char *GetAxisNormUnit( AstAxis *, int * ); static const char *GetDefaultFormat( AstAxis *, int * ); static char *ParseAxisFormat( const char *, int, int *, int *, int *, int *, int * ); static double AxisDistance( AstAxis *, double, double, int * ); static double AxisCentre( AstAxis *, double, double, int * ); static double AxisGap( AstAxis *, double, int *, int * ); static double AxisOffset( AstAxis *, double, double, int * ); static int AxisFields( AstAxis *, const char *, const char *, int, char **, int *, double *, int * ); static int AxisIn( AstAxis *, double, double, double, int, int * ); static int AxisUnformat( AstAxis *, const char *, double *, int * ); static int GetAxisDigits( AstAxis *, int * ); static int GetAxisDirection( AstAxis *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestAxisDigits( AstAxis *, int * ); static int TestAxisDirection( AstAxis *, int * ); static int TestAxisFormat( AstAxis *, int * ); static int TestAxisLabel( AstAxis *, int * ); static int TestAxisSymbol( AstAxis *, int * ); static int TestAxisUnit( AstAxis *, int * ); static int TestAxisInternalUnit( AstAxis *, int * ); static int TestAxisNormUnit( AstAxis *, int * ); static void AxisNorm( AstAxis *, double *, int * ); static void AxisNormValues( AstAxis *, int, int, double *, int * ); static void AxisOverlay( AstAxis *, AstAxis *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearAxisDigits( AstAxis *, int * ); static void ClearAxisDirection( AstAxis *, int * ); static void ClearAxisFormat( AstAxis *, int * ); static void ClearAxisLabel( AstAxis *, int * ); static void ClearAxisSymbol( AstAxis *, int * ); static void ClearAxisUnit( AstAxis *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetAxisDigits( AstAxis *, int, int * ); static void SetAxisDirection( AstAxis *, int, int * ); static void SetAxisFormat( AstAxis *, const char *, int * ); static void SetAxisLabel( AstAxis *, const char *, int * ); static void SetAxisSymbol( AstAxis *, const char *, int * ); static void SetAxisUnit( AstAxis *, const char *, int * ); static double GetAxisTop( AstAxis *, int * ); static int TestAxisTop( AstAxis *, int * ); static void ClearAxisTop( AstAxis *, int * ); static void SetAxisTop( AstAxis *, double, int * ); static double GetAxisBottom( AstAxis *, int * ); static int TestAxisBottom( AstAxis *, int * ); static void ClearAxisBottom( AstAxis *, int * ); static void SetAxisBottom( AstAxis *, double, int * ); /* Member functions. */ /* ================= */ static const char *AxisAbbrev( AstAxis *this, const char *fmt, const char *str1, const char *str2, int *status ) { /* *+ * Name: * astAxisAbbrev * Purpose: * Abbreviate a formatted Axis value by skipping leading fields. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * const char *astAxisAbbrev( AstAxis *this, const char *fmt, * const char *str1, const char *str2 ) * Class Membership: * Axis method. * Description: * This function compares two Axis values that have been formatted * (using astAxisFormat) 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 Axis. * fmt * Pointer to a constant null-terminated string containing the * format specifier used to format the two values. * str1 * Pointer to a constant null-terminated string containing the * first formatted value. If this is null, the returned pointer * points to the start of the final field in str2. * str2 * Pointer to a constant null-terminated string containing the * second formatted value. * Returned Value: * A pointer into the "str2" string which locates the first * character in the first field that differs between the two * formatted values. * * If the two values have no leading fields in common, the returned * value will point at the start of string "str2". If the two * values are equal, it will point at the terminating null at the * end of this string. * Notes: * - This function assumes that the format specification used was * the same when both values were formatted. * - 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: */ const char *result; /* Result pointer to return */ /* Initialise. */ result = str2; /* Check the global error status. */ if ( !astOK ) return result; /* In the Axis class, there is only one field in a formatted value. We return the value of "str2", unless the two strings are identical, in which case we return a pointer to the final null in "str2". */ if( str1 && !strcmp( str1, str2 ) ) result += strlen( str2 ); /* Return the result. */ return result; } static double AxisDistance( AstAxis *this, double v1, double v2, int *status ) { /* *+ * Name: * astAxisDistance * Purpose: * Find the distance between two axis values. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * AxisDistance( AstAxis *this, double v1, double v2 ) * Class Membership: * Axis method. * Description: * This function returns a signed value representing the axis increment * from axis value v1 to axis value v2. * * For a simple Axis, this is a trivial operation. But for other * derived classes of Axis (such as a SkyAxis) this is not the case. * Parameters: * this * Pointer to the Axis. * v1 * The first axis value * v2 * The second axis value * Returned Value: * The axis increment from v1 to v2. * Notes: * - A value of AST__BAD is returned if either axis value is AST__BAD. * - 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: */ double result; /* Returned gap size */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Check both axis values are OK, and form the returned increment. */ if( v1 != AST__BAD && v2 != AST__BAD ) result = v2 - v1; /* Return the result. */ return result; } static int AxisFields( AstAxis *this, const char *fmt0, const char *str, int maxfld, char **fields, int *nc, double *val, int *status ) { /* *+ * Name: * astAxisFields * Purpose: * Identify numerical fields within a formatted Axis value. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * int astAxisFields( AstAxis *this, const char *fmt0, const char *str, * int maxfld, char **fields, int *nc, double *val ) * Class Membership: * Axis member function. * Description: * This function identifies the numerical fields within an Axis value * that have 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 Axis. * fmt0 * 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: */ char log_esc[ 50 ]; /* Buffer for graphical delimiter string */ const char *fmt; /* Pointer to parsed Format string */ const char *log_del; /* Pointer to delimiter string */ const char *p; /* Pointer to next character */ double value; /* Equivalent radians value */ int ifld; /* Field index */ int integ; /* Cast axis value to integer before printing? */ int len; /* Length of formatted string */ int log; /* Format as "10**x"? */ int n; /* Number of characters read */ int neg; /* Negate final value? */ int result; /* Result fields count to return */ int sign; /* Include leading sign in front of "10**x"? */ int space; /* Include leading space in front of "10**x"? */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 0; for( ifld = 0; ifld < maxfld; ifld++ ) { fields[ ifld ] = NULL; nc[ ifld ] = 0; } if( val ) *val = AST__BAD; /* Parse the Format string. This returns a collection of flags indicating if any AST specific formatting features are specified in the Format string. It also returns a pointer to a new Format string which is a standard C printf format specifier. Currently the only flags are "log" which indicates if the value should be formatted as "10**x" using the graphical escape sequences defined within the Plot class to produce "x" as a superscript of "10", "sign" which is used with log to indicate if a sign should always be included infront of the "10", and "space" which indicates if a leading space should be included infronyt of "10" if no sign is included. */ fmt = ParseAxisFormat( fmt0, astGetAxisDigits( this ), &log, &sign, &space, &integ, status ); fmt = astFree( (void *) fmt ); if( astOK ) { /* Obtain the length of the formatted string. */ len = (int) strlen( str ); /* First deal with "log" format. */ if( log ) { /* We need room for at least 2 fields. */ if( maxfld > 1 ) { /* Return a pointer to the first non-blank character. */ p = str; while( *p == ' ' ) p++; fields[ 0 ] = (char *) p; /* If the first non-blank character is a minus sign, note it and skip it. */ neg = 0; if( *p == '-' ) { neg = 1; p++; /* If the first non-blank character is a plus sign, and skip it. */ } else if( *p == '+' ) { p++; } /* Select the delimter.*/ if( astEscapes( -1 ) ) { astTuneC( "exdel", NULL, log_esc, sizeof( log_esc ) ); log_del = log_esc; } else { log_del = log_txt; } /* Check the remaining string starts with the correct delimiter. If so, store the number of characters in the first field and skip over the delimiter. */ n = 0; if( strstr( p, log_del ) == p ) { nc[ 0 ] = p + 2 - fields[ 0 ]; p += strlen( log_del ); /* Attempt to read a floating point value from the start of the remaining string. */ if( 1 == sscanf( p, "%lg%n", &value, &n ) ) { /* If succesfull, store the returned values. */ result = 2; fields[ 1 ] = (char *) p; nc[ 1 ] = n; if( val ) { *val = pow( 10.0, value ); if( neg ) *val = -(*val); } /* Otherwise, see if the string starts with */ } else if( strstr( p, "" ) == p ) { /* If succesfull, store the returned values. */ result = 2; fields[ 1 ] = (char *) p; nc[ 1 ] = 5; if( val ) *val = 0.0; } /* Zero is never formatted as an exponent. If the string starts with zero, return a single zero field. */ } else if( 1 == sscanf( p, "%lg%n", &value, &n ) ) { if( value == 0.0 ) { result = 1; nc[ 0 ] = p + n - fields[ 0 ]; if( val ) *val = 0.0; } } } /* Now deal with normal decimal format */ } else { /* Attempt to read a floating point value from the formatted string. */ if ( n = 0, ( 1 == sscanf( str, "%lg %n", &value, &n ) ) && ( n >= len ) && maxfld > 0 ) { /* If succesful, return a pointer to the first non-blank character. */ p = str; while( *p == ' ' ) p++; fields[ 0 ] = (char *) p; /* Find the last non-blank character. */ p += len; while( p[ -1 ] == ' ' ) p--; /* Return the number of characters in the field. */ nc[ 0 ] = p - fields[ 0 ]; /* Return the field value. */ if( val ) *val = value; /* Indicate that we are returning one field. */ result = 1; } } } /* Return the result. */ return result; } static const char *AxisFormat( AstAxis *this, double value, int *status ) { /* *+ * Name: * astAxisFormat * Purpose: * Format a coordinate value for an Axis. * Type: * Public virtual function. * Synopsis: * #include "axis.h" * const char *astAxisFormat( AstAxis *this, double value ) * Class Membership: * Axis method. * Description: * This function returns a pointer to a string containing the formatted * (character) version of a coordinate value for an Axis. The formatting * applied is that specified by a previous invocation of the * astSetAxisFormat method. A suitable default format is applied if * necessary. * Parameters: * this * Pointer to the Axis. * value * The coordinate value to be formatted. * Returned Value: * A pointer to a null-terminated string containing the formatted value. * Notes: * - The returned string pointer may point at memory allocated within * the Axis 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 Axis. 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 Constants: */ #define ERRBUF_LEN 80 /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char *errstat; /* Pointer for system error message */ char errbuf[ ERRBUF_LEN ]; /* Buffer for system error message */ char log_esc[ 50 ]; /* Buffer for graphical delimiter string */ const char *fmt0; /* Pointer to original Format string */ const char *fmt; /* Pointer to parsed Format string */ const char *log_del; /* Pointer to delimiter string */ const char *result; /* Pointer to formatted value */ double x; /* The value to be formatted by sprintf */ int integ; /* Cast axis value to integer before printing? */ int log; /* Format as "10**x"? */ int nc; /* Total number of characters written */ int ncc; /* Number of characters written */ int sign; /* Include leading sign in front of "10**x"? */ int space; /* Include leading space in front of "10**x"? */ int stat; /* Value of errno after error */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; nc = 0; x = value; /* Check if a bad coordinate value was supplied and return a pointer to an appropriate string if necessary. */ if ( value == AST__BAD ) { result = ""; /* Otherwise, obtain a pointer to the Format string. Note a private member function is used here in preference to an object method. This is because the syntax of the Format string may be extended by derived classes and we do not want to obtain a string that we cannot interpret here (where we are restricted to C format specifiers capable of formatting double values). Classes that extend the syntax should provide their own astAxisFormat method and may need to store the string in a separate location. The original location should not be re-used as the string it contains may be needed by the Axis astOverlay method when overlaying attributes on to another Axis object. */ } else { fmt0 = GetAxisFormat( this, status ); /* Parse the Format string. This returns a collection of flags indicating if any AST specific formatting features are specified in the Format string. It also returns a pointer to a new Format string which is a standard C printf format specifier. Currently the only flags are "log" which indicates if the value should be formatted as "10**x" using the graphical escape sequences defined within the Plot class to produce "x" as a superscript of "10", "sign" which is used with log to indicate if a sign should always be included infront of the "10", and "space" which indicates if a leading space should be included infronyt of "10" if no sign is included. It also modifies ".*" precision fields by replacing the "*" by the current vale of the Digits attribute. */ fmt = ParseAxisFormat( fmt0, astGetAxisDigits( this ), &log, &sign, &space, &integ, status ); if( astOK ) { /* Format zero normally. */ if( value == 0.0 ) log = 0; /* If log format is required, find the value of the exponent "x", and initialise the returned string to hold the exponent and the graphical escape sequence which produces a superscript. Otherwise just format the supplied value. */ if( log ) { if( sign ) { axisformat_buff[ 0 ] ='+'; nc = 1; } else if( space ) { axisformat_buff[ 0 ] =' '; nc = 1; } if( value > 0 ) { x = log10( integ ? (int) value : value ); } else { x = log10( integ ? (int) -value : -value ); axisformat_buff[ 0 ] ='-'; nc = 1; } if( astEscapes( -1 ) ) { astTuneC( "exdel", NULL, log_esc, sizeof( log_esc ) ); log_del = log_esc; } else { log_del = log_txt; } nc += sprintf( axisformat_buff + nc, "%s", log_del ); /* Round small exponents to zero. */ if( fabs( x ) < 1.0E-10 ) x = 0.0; } } /* Clear errno and attempt to format the value as if the Format string were a standard "sprintf" format. */ if ( astOK ) { errno = 0; if( integ ) { ncc = sprintf( axisformat_buff + nc, fmt, (int) x ); } else { ncc = sprintf( axisformat_buff + nc, fmt, x ); } nc += ncc; /* If log format is being used, terminate the string with an escape sequence which resets the graphical attributes to what they were at the start of the string. */ if( log ) nc += sprintf( axisformat_buff + nc, "%%+" ); /* The possibilities for error detection are limited here, but check if an error value was returned and report an error. Include information from errno if it was set. */ if ( ncc < 0 ) { stat = errno; if( stat ) { #if HAVE_STRERROR_R strerror_r( stat, errbuf, ERRBUF_LEN ); errstat = errbuf; #else errstat = strerror( stat ); #endif } else { *errbuf = 0; errstat = errbuf; } astError( AST__FMTER, "astAxisFormat(%s): Error formatting a " "coordinate value of %1.*G%s%s.", status, astGetClass( this ), DBL_DIG, value, stat? " - " : "", errstat ); astError( AST__FMTER, "The format string was \"%s\".", status, fmt ); /* Also check that the result buffer did not overflow. If it did, memory will probably have been corrupted but this cannot be prevented with "sprintf". Report the error and abort. */ } else if ( nc > AST__AXIS_AXISFORMAT_BUFF_LEN ) { astError( AST__FMTER, "astAxisFormat(%s): Internal buffer " "overflow while formatting a coordinate value of %1.*G " "- result exceeds %d characters.", status, astGetClass( this ), DBL_DIG, value, AST__AXIS_AXISFORMAT_BUFF_LEN ); astError( AST__FMTER, "The format string was \"%s\".", status, fmt ); /* If succesfull, return a pointer to the buffer. */ } else { result = axisformat_buff; } } /* Free resources. */ fmt = astFree( (void *) fmt ); } /* Return the result. */ return result; } #undef ERRBUF_LEN static double AxisCentre( AstAxis *this, double value, double gap, int *status ) { /* *+ * Name: * astAxisCentre * Purpose: * Find a "nice" central value for tabulating Axis values. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * double astAxisCentre( AstAxis *this, double value, double gap ) * Class Membership: * Axis method. * Description: * This function returns an axis value which produces a nice formatted * value suitable for a major tick mark on a plot axis. * Parameters: * this * Pointer to the Axis. * 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: */ double result; /* Returned central axis value */ /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* The returned central value is an integral number of gaps away from the origin and is close to the supplied axis value. This would result in the origin being at a major tick mark. */ if( gap != 0.0 && gap != AST__BAD && value != AST__BAD ) { result = gap*floor( 0.5 + value/gap ); } /* Return the result. */ return result; } static double AxisGap( AstAxis *this, double gap, int *ntick, int *status ) { /* *+ * Name: * astAxisGap * Purpose: * Find a "nice" gap for tabulating Axis values. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * double astAxisGap( AstAxis *this, double gap, int *ntick ) * Class Membership: * Axis method. * Description: * This function returns a gap size which produces a nicely spaced * series of formatted Axis values, 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 Axis. * gap * The target gap size. * ntick * Address of an int in which to return a convenient number of * divisions into which the gap can be divided. * Returned Value: * The nice gap size. * Notes: * - A value of zero is returned if the supplied 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: */ double absgap; /* Absolute supplied gap size */ double b; /* Decimal step size */ double result; /* Returned gap size */ int index; /* Index into tables */ int positive; /* Value is positive (or zero)? */ /* Local Data: */ static double table1[ 10 ] = /* Table of nice decimal gaps */ { 1.0, 2.0, 2.0, 5.0, 5.0, 5.0, 5.0, 10.0, 10.0, 10.0 }; static int table2[ 10 ] = /* Table giving number of divisions */ { 5, 4, 4, 5, 5, 5, 5, 5, 5, 5 }; /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Check that the supplied gap size is not zero. */ if ( gap != 0.0 ) { /* Determine if the supplied gap size is positive and obtain its absolute value. */ positive = ( gap >= 0.0 ); absgap = positive ? gap : -gap; /* Obtain a value which has a 1 at the position of the most significant decimal digit in the target gap size and zeros at all other positions. */ b = pow( 10.0, floor( log10( absgap ) ) ); /* This value is the basic "step size". Find the nearest whole number of steps in the supplied gap, and then use the look-up-table in "table1" to find the closest acceptable gap size. Convert this gap size back to an absolute value by multiplying by the step size. */ index = (int) ( absgap / b + 0.5 ) - 1; result = b * table1[ index ]; /* If the target gap was negative, negate the result. */ if( !positive ) result = -result; /* Store the number of divisions in the gap. */ if ( ntick ) *ntick = table2[ index ]; } /* Return the result. */ return result; } static int AxisIn( AstAxis *this, double lo, double hi, double val, int closed, int *status ){ /* *+ * Name: * astAxisIn * Purpose: * Test if an axis value lies within a given interval. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * int AxisIn( AstAxis *this, double lo, double hi, double val, int closed ) * Class Membership: * Axis member function. * Description: * This function returns non-zero if a given axis values lies within a * given axis interval. * Parameters: * this * Pointer to the Axis. * lo * The lower axis limit of the interval. * hi * The upper axis limit of the interval. * val * The axis value to be tested. * closed * If non-zero, then the lo and hi axis values are themselves * considered to be within the interval. Otherwise they are outside. * Returned Value: * Non-zero if the test value is inside the interval. * Class Applicability: * Axis * Uses simple Euclidean test * SkyAxis * All angles which are numerically between "lo" and "hi" are within * the interval. Angle outside this range are also within the interval * if they can be brought into the range by addition or subtraction * of a multiple of 2.PI. *- */ /* For speed, omit the astOK check since no pointers are being used. */ if( closed ) { return ( lo <= val && val <= hi ); } else { return ( lo < val && val < hi ); } } static void AxisNorm( AstAxis *this, double *value, int *status ) { /* *+ * Name: * astAxisNorm * Purpose: * Normalise an Axis coordinate value. * Type: * Public virtual function. * Synopsis: * #include "axis.h" * void astAxisNorm( AstAxis *this, double *value ) * Class Membership: * Axis method. * Description: * This function converts an Axis coordinate value which might * potentially be unsuitable for display to a user (for instance, * may lie outside the expected range of values) into an acceptable * alternative value suitable for display. * * Typically, for axes that represent cyclic values such as angles, * this function wraps an arbitrary coordinate value so that it * lies within the first cycle (say zero to 2*pi). For an ordinary * linear Axis, without constraints, this function will typically * return the original value unchanged. * Parameters: * this * Pointer to the Axis. * value * Pointer to the coordinate value to be normalised, which will * be modified in place. *- */ /* In the Axis class there are no constraints, so simply return without action. */ return; } static void AxisNormValues( AstAxis *this, int oper, int nval, double *values, int *status ){ /* *+ * Name: * astAxisNormValues * Purpose: * Normalise an array of axis coordinate values. * Type: * Public virtual function. * Synopsis: * #include "axis.h" * void astAxisNormValues( AstAxis *this, int oper, int nval, * double *values ) * Class Membership: * Axis method. * Description: * This function modifies a supplied array of axis values so that * they are normalised in the manner indicated by parameter "oper". * * For a simple axis, the supplied values are always returned * unchanged regardless of the value of "oper". * Parameters: * this * Pointer to the Axis. * oper * Indicates the type of normalisation to be applied. If zero is * supplied, the normalisation will be the same as that performed by * function astAxisNorm. 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. *- */ /* In the Axis class there are no constraints, so simply return without action. */ return; } static double AxisOffset( AstAxis *this, double v1, double dist, int *status ) { /* *+ * Name: * astAxisOffset * Purpose: * Add an increment onto a supplied axis value. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * AxisOffset( AstAxis *this, double v1, double dist ) * Class Membership: * Axis method. * Description: * This function returns an axis value formed by adding a signed axis * increment onto a supplied axis value. * * For a simple Axis, this is a trivial operation. But for other * derived classes of Axis (such as a SkyAxis) this is not the case. * Parameters: * this * Pointer to the Axis. * v1 * The supplied axis value * dist * The axis increment * Returned Value: * The axis value which is the specified increment away from v1. * Notes: * - A value of AST__BAD is returned if either axis value is AST__BAD. * - 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: */ double result; /* Returned gap size */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Check both axis values are OK, and form the returned axis value. */ if( v1 != AST__BAD && dist != AST__BAD ) result = v1 + dist; /* Return the result. */ return result; } static void AxisOverlay( AstAxis *template, AstAxis *result, int *status ) { /* *+ * Name: * astAxisOverlay * Purpose: * Overlay the attributes of a template Axis on to another Axis. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * void astAxisOverlay( AstAxis *template, AstAxis *result ) * Class Membership: * Axis method. * Description: * This function overlays attributes of one Axis (the "template") on to * another Axis, so as to over-ride selected attributes of that second * Axis. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which an Axis 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 Axis, for which values should have been * explicitly set for any attribute which is to be transferred. * result * Pointer to the Axis which is to receive the new attribute values. * Returned Value: * void *- */ /* Check the global error status. */ if ( !astOK ) return; /* Define a macro to overlay a single attribute. This tests if the attribute is set in the template Axis. If it is, its value is obtained and set in the result Axis also. */ #define OVERLAY(par) \ if ( astTestAxis##par( template ) ) { \ astSetAxis##par( result, astGetAxis##par( template ) ); \ } /* Overlay each Axis attribute in turn. */ OVERLAY(Digits); OVERLAY(Direction); OVERLAY(Label); OVERLAY(Symbol); OVERLAY(Unit); /* Handle the Format string slightly differently by using a private member function to obtain it. This is necessary in case derived classes have extended the string syntax (see the AxisFormat function for more details). */ if ( TestAxisFormat( template, status ) ) { SetAxisFormat( result, GetAxisFormat( template, status ), status ); } /* Undefine macros local to this function. */ #undef OVERLAY } static int AxisUnformat( AstAxis *this, const char *string, double *value, int *status ) { /* *+ * Name: * astAxisUnformat * Purpose: * Read a formatted coordinate value for an Axis. * Type: * Public virtual function. * Synopsis: * #include "axis.h" * int astAxisUnformat( AstAxis *this, const char *string, double *value ) * Class Membership: * Axis method. * Description: * This function reads a formatted coordinate value for an 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 Axis. * string * Pointer to a constant null-terminated string containing the * formatted coordinate value. * value * Pointer to a double in which the coordinate value read will be * returned. * Returned Value: * The number of characters read from the string to obtain the * coordinate value. * Notes: * - Any white space at the beginning of the string will be * skipped, as also will any trailing white space following the * coordinate value read. The function's return value will reflect * this. * - A function value of zero (and no coordinate value) will be * returned, without error, if the string supplied does not contain * a suitably formatted value. * - The string "" 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: */ double coord; /* Coordinate value read */ int nc; /* Number of characters read */ /* Initialise. */ nc = 0; /* Check the global error status. */ if ( !astOK ) return nc; /* See if the string can be read as a floating point number. If so, return its value. Also obtain the number of characters read, including any leading and trailing white space. */ if ( 1 == astSscanf( string, "%lf %n", &coord, &nc ) ) { *value = coord; /* Otherwise, see if the string starts with "", allowing mixed case and leading, embedded and trailing white space. If so, return the value AST__BAD. */ } else if ( nc = 0, ( 0 == astSscanf( string, " < %*1[Bb] %*1[Aa] %*1[Dd] > %n", &nc ) && ( nc > 0 ) ) ) { *value = AST__BAD; /* If the string cannot be read, return a function result of zero. */ } else { nc = 0; } /* Return the number of characters read. */ return nc; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Axis member function (over-rides the astClearAttrib protected * method inherited from the Object class). * Description: * This function clears the value of a specified attribute for an * Axis, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Axis. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstAxis *this; /* Pointer to the Axis structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { astClearAxisDigits( this ); /* Direction. */ /* ---------- */ } else if ( !strcmp( attrib, "direction" ) ) { astClearAxisDirection( this ); /* Format. */ /* ------- */ } else if ( !strcmp( attrib, "format" ) ) { astClearAxisFormat( this ); /* Label. */ /* ------ */ } else if ( !strcmp( attrib, "label" ) ) { astClearAxisLabel( this ); /* Top. */ /* ---- */ } else if ( !strcmp( attrib, "top" ) ) { astClearAxisTop( this ); /* Bottom. */ /* ------- */ } else if ( !strcmp( attrib, "bottom" ) ) { astClearAxisBottom( this ); /* Symbol. */ /* ------- */ } else if ( !strcmp( attrib, "symbol" ) ) { astClearAxisSymbol( this ); /* Unit. */ /* ----- */ } else if ( !strcmp( attrib, "unit" ) ) { astClearAxisUnit( this ); /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then report an error. */ } else if ( !strcmp( attrib, "normunit" ) || !strcmp( attrib, "internalunit" ) ) { 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static const char *GetAxisInternalUnit( AstAxis *this, int *status ){ /* *+ * Name: * astGetAxisInternalUnit * Purpose: * Return the unit string for unformatted Axis values * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * const char *astGetAxisInternalUnit( AstAxis *this ){ * Class Membership: * Axis method. * Description: * This function returns the axis InternalUnit attribute. For basic * axes, the InternalUnit and Unit attributes are the same. * Parameters: * this * Pointer to the Axis. * Returned Value: * - Pointer to a null-terminated string containing the internal * unit string. * Notes: * - The returned pointer points to a static memory buffer. The * contents of this buffer will be over-written on each invocation of * this function. A copy of the returned string should therefore be * taken if it will be needed later. * - 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. *- */ return astGetAxisUnit( this ); } static const char *GetAxisNormUnit( AstAxis *this, int *status ){ /* *+ * Name: * astGetAxisNormUnit * Purpose: * Return the normalised Unit attribute for an Axis. * Type: * Protected virtual function. * Synopsis: * #include "axis.h" * const char *astGetAxisNormUnit( AstAxis *this ){ * Class Membership: * Axis method. * Description: * This function normalised and returns the axis Unit attribute. * Normalisation refers to transformations such as "s*(m/s)" -> "m". * Parameters: * this * Pointer to the Axis. * Returned Value: * - Pointer to a null-terminated string containing the normalised * unit string. * Notes: * - The returned pointer points to a static memory buffer. The * contents of this buffer will be over-written on each invocation of * this function. A copy of the returned string should therefore be * taken if it will be needed later. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *result; /* Pointer to dynamic memory holding returned text */ int nc; /* Length of normalised Unit string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Get the Axis Unit attrribute and normalise it. */ result = astUnitNormaliser( astGetAxisUnit( this ) ); /* If successful, check that the resulting string will fit in the buffer. If not, report an error. */ if( result ) { nc = strlen( result ); if( nc > AST__AXIS_GETAXISNORMUNIT_BUFF_LEN ) { astError( AST__FMTER, "astGetAxisNormUnit(%s): Internal buffer " "overflow while normalising the units string '%s' " "- result exceeds %d characters.", status, astGetClass( this ), result, AST__AXIS_GETAXISNORMUNIT_BUFF_LEN ); result = astFree( (void *) result ); /* If so, copy it into the static buffer and free the dynamic memory returned by astUnitNormaliser. */ } else { strcpy( getaxisnormunit_buff, result ); } astFree( (void *) result ); result = getaxisnormunit_buff; } /* Return the answer. */ 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 "axis.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Axis member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Axis, * in bytes. * Parameters: * this * Pointer to the Axis. * 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: */ AstAxis *this; /* Pointer to Axis structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Axis structure. */ this = (AstAxis *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->label ); result += astTSizeOf( this->format ); result += astTSizeOf( this->symbol ); result += astTSizeOf( this->unit ); /* 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 an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Axis member function (over-rides the protected astGetAttrib * method inherited from the Object class). * Description: * This function returns a pointer to the value of a specified * attribute for an Axis, formatted as a character string. * Parameters: * this * Pointer to the Axis. * 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 Axis, 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 Axis. A copy of the string should therefore be made if * necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstAxis*this; /* Pointer to the Axis structure */ const char *result; /* Pointer value to return */ double dval; /* Double attribute value */ int digits; /* Digits attribute value */ int direction; /* Direction attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) 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. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { digits = astGetAxisDigits( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", digits ); result = getattrib_buff; } /* Direction. */ /* ---------- */ } else if ( !strcmp( attrib, "direction" ) ) { direction = astGetAxisDirection( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", direction ); result = getattrib_buff; } /* Top. */ /* ---- */ } else if ( !strcmp( attrib, "top" ) ) { dval = astGetAxisTop( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Bottom. */ /* ------- */ } else if ( !strcmp( attrib, "bottom" ) ) { dval = astGetAxisBottom( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Format. */ /* ------- */ } else if ( !strcmp( attrib, "format" ) ) { result = astGetAxisFormat( this ); /* Label. */ /* ------ */ } else if ( !strcmp( attrib, "label" ) ) { result = astGetAxisLabel( this ); /* Symbol. */ /* ------- */ } else if ( !strcmp( attrib, "symbol" ) ) { result = astGetAxisSymbol( this ); /* Unit. */ /* ----- */ } else if ( !strcmp( attrib, "unit" ) ) { result = astGetAxisUnit( this ); /* NormUnit. */ /* --------- */ } else if ( !strcmp( attrib, "normunit" ) ) { result = astGetAxisNormUnit( this ); /* InternalUnit. */ /* ------------- */ } else if ( !strcmp( attrib, "internalunit" ) ) { result = astGetAxisInternalUnit( this ); /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static const char *GetDefaultFormat( AstAxis *this, int *status ){ /* * Name: * GetDefaultFormat * Purpose: * Return a pointer to a string holding the default Format value. * Type: * Private function. * Synopsis: * #include "axis.h" * const char *GetDefaultFormat( AstAxis *this, int *status ) * Class Membership: * Axis member function * Description: * This function returns a pointer to a string holding the default * Format value, which is based on the current Digits value. * Parameters: * this * A pointer to the Axis structure. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a static null-terminated character string containing * the default Format string. * Notes: * - A null string will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Check the global error status. */ if ( !astOK ) return ""; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Create the default format value and store it in the "format_buff" static variable. */ (void) sprintf( getdefaultformat_buff, "%%1.%dG", astGetAxisDigits( this ) ); /* Return a pointer to the "format_buff" static variable. */ return getdefaultformat_buff; } void astInitAxisVtab_( AstAxisVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitAxisVtab * Purpose: * Initialise a virtual function table for an Axis. * Type: * Protected function. * Synopsis: * #include "axis.h" * void astInitAxisVtab( AstAxisVtab *vtab, const char *name ) * Class Membership: * Axis vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Axis class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ /* 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. */ astInitObjectVtab( (AstObjectVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAAxis) 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 = &(((AstObjectVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->AxisAbbrev = AxisAbbrev; vtab->AxisFields = AxisFields; vtab->AxisFormat = AxisFormat; vtab->AxisDistance = AxisDistance; vtab->AxisOffset = AxisOffset; vtab->AxisCentre = AxisCentre; vtab->AxisGap = AxisGap; vtab->AxisIn = AxisIn; vtab->AxisNorm = AxisNorm; vtab->AxisNormValues = AxisNormValues; vtab->AxisOverlay = AxisOverlay; vtab->AxisUnformat = AxisUnformat; vtab->ClearAxisDigits = ClearAxisDigits; vtab->ClearAxisDirection = ClearAxisDirection; vtab->ClearAxisFormat = ClearAxisFormat; vtab->ClearAxisLabel = ClearAxisLabel; vtab->ClearAxisSymbol = ClearAxisSymbol; vtab->ClearAxisUnit = ClearAxisUnit; vtab->GetAxisDigits = GetAxisDigits; vtab->GetAxisDirection = GetAxisDirection; vtab->GetAxisFormat = GetAxisFormat; vtab->GetAxisLabel = GetAxisLabel; vtab->GetAxisSymbol = GetAxisSymbol; vtab->GetAxisUnit = GetAxisUnit; vtab->GetAxisInternalUnit = GetAxisInternalUnit; vtab->GetAxisNormUnit = GetAxisNormUnit; vtab->SetAxisDigits = SetAxisDigits; vtab->SetAxisDirection = SetAxisDirection; vtab->SetAxisFormat = SetAxisFormat; vtab->SetAxisLabel = SetAxisLabel; vtab->SetAxisSymbol = SetAxisSymbol; vtab->SetAxisUnit = SetAxisUnit; vtab->TestAxisDigits = TestAxisDigits; vtab->TestAxisDirection = TestAxisDirection; vtab->TestAxisFormat = TestAxisFormat; vtab->TestAxisLabel = TestAxisLabel; vtab->TestAxisSymbol = TestAxisSymbol; vtab->TestAxisUnit = TestAxisUnit; vtab->TestAxisInternalUnit = TestAxisInternalUnit; vtab->TestAxisNormUnit = TestAxisNormUnit; vtab->ClearAxisTop = ClearAxisTop; vtab->GetAxisTop = GetAxisTop; vtab->SetAxisTop = SetAxisTop; vtab->TestAxisTop = TestAxisTop; vtab->ClearAxisBottom = ClearAxisBottom; vtab->GetAxisBottom = GetAxisBottom; vtab->SetAxisBottom = SetAxisBottom; vtab->TestAxisBottom = TestAxisBottom; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; parent_clearattrib = object->ClearAttrib; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; /* Declare the destructor, copy constructor and dump function. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Axis", "Coordinate axis" ); /* 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 char *ParseAxisFormat( const char *fmt0, int digs, int *log, int *sign, int *lspace, int *integ, int *status ){ /* * Name: * ParseAxisFormat * Purpose: * Parse the Format string for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * char *ParseAxisFormat( const char *fmt0, int digs, int *log, int *sign, * int *lspace, int *integ, int *status ) * Class Membership: * Axis member function * Description: * This function returns a collection of flags indicating if any AST * specific formatting features are specified in the supplied Format * string. It also returns a pointer to a new Format string which is a * standard C printf format specifier. * Parameters: * fmt0 * The value of the Format attribute. * digs * The default number of digits of precision to use. This is used * if the given format specifier includes a wildcard precision (".*"). * In this case, the returned format specifier will be modified to * include an explicit precision value equal to the supplied value * of "digs". * log * Pointer to an integer in which to store a flag indicating if the * if the axis value should be formatted as "10**x" using the graphical * escape sequences defined within the Plot class to produce "x" as a * superscript of "10". A non-zero value will be returned if the * supplied Format string has a '&' character in its printf * field (that is, between the leading '%' sign and the optional * printf field width). * sign * Pointer to an integer in which to store a flag indicating if a * sign character ('+' or '-') should always be included in front * of the "10" if "log" is returned non-zero. If "log" is returned * zero, then "sign" will also be zero. If "log" is non-zero, then * a non-zero value for "sign" will be returned if the supplied Format * string has a '+' character in its printf field (that is, * between the leading '%' sign and the optional printf field width). * lspace * Pointer to an integer in which to store a flag indicating if a * leading space should be included in front of the "10" if "log" is * returned non-zero and "sign" is returned zero. Otherwise, "lspace" * will also be zero. If "log" is non-zero, then a non-zero value for * "lspace" will be returned if the supplied Format string has a ' ' * character in its printf field (that is, between the leading * '%' sign and the optional printf field width). * integ * Pointer to an integer in which to store a flag indicating if the * returned format specifier includes an integer conversion code * (e.g. %d) or floating point conversion code (e.g. "%.7G"). * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a dynamically allocated null-terminated string containing * the modified Format string. This will be a copy of the supplied * Format string, but with any '&' flag removed. Any '+' or ' ' flag will * also be removed if "log" is returned as non-zero. An explicit * precision field will be included if the supplied format includes a * ".*" precision field. * 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: */ char *a; /* Pointer to next char read from original format */ char *b; /* Pointer to next char to write to new format */ char *c; /* Pointer to next char read from original format */ char *new; /* Pointer to new returned string */ char *perc; /* Pointer to percent sign */ char *result; /* Pointer to the returned string */ int hash; /* Was a '#' flag found? */ int len; /* Used length of format string */ int minus; /* Was a '-' flag found? */ int plus; /* Was a '+' flag found? */ int rlen; /* Length of result */ int space; /* Was a ' ' flag found? */ /* Initialise. */ result = NULL; *log = 0; *sign = 0; *lspace = 0; *integ = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Take a copy of the supplied string. Check the pointer can be used safely. */ len = astChrLen( fmt0 ); result = astStore( NULL, fmt0, len + 1 ); if( astOK ) { result[ len ] = 0; /* Find the first percent sign. Do nothing if none is found. */ perc = strchr( result, '%' ); if( perc ) { /* Check each character following the percent sign until one is found which is not a legal printf flag, or a legal AST extension flag. Note which ones are present. */ minus = 0; plus = 0; space = 0; hash = 0; a = perc; while( ++a ){ if( *a == '-' ){ minus = 1; } else if( *a == '+' ){ plus = 1; } else if( *a == ' ' ){ space = 1; } else if( *a == '#' ){ hash = 1; } else if( *a == '&' ){ *log = 1; } else { break; } } /* If no '&' flag was found just return the unaltered copy of the supplied Format string. Otherwise, remove any '+' or ' ' flag. */ if( *log ) { if( plus ) *sign = 1; if( space ) *lspace = 1; /* Append any remaining flag characters to the output string. */ perc++; if( minus ) *(perc++) = '-'; if( hash ) *(perc++) = '#'; /* Copy the remaining characters down to fill up the gap left by the removed flags. */ while( *a ) *(perc++) = *(a++); /* Terminate the returned string. */ *perc = 0; } } } /* If the format specifier being returned does include a ".*" precision, replace the "*" with the value of the Digits attribute. */ if( result ) { /* Find the first percent sign. Do nothing if none is found. */ a = strchr( result, '%' ); if( a ) { /* Check each character following the percent sign until one is found which is not a legal printf flag. */ while( ++a ){ if( *a != '-' && *a != '+' && *a != ' ' && *a != '#' ) break; } /* Skip any field width (a decimal integer) following the flags. */ a--; while( ++a ) { if( !isdigit( *a ) ) break; } /* Get a pointer to the next alphabetic character. This will be the conversion code. If it an integer code, return *integ non-zero. */ c = a - 1; while( ++c ) { if( isalpha( *c ) ) { if( *c == 'd' || *c == 'i' || *c == 'u' || *c == 'o' || *c == 'x' || *c == 'X' || *c == 'c' ) *integ = 1; break; } } /* Go back to the end of the field width. If the next two characters are "." and "*", change the asterisk to the supplied "digs" value. */ if( a[ 0 ] == '.' && a[ 1 ] == '*' ) { /* Allocate memory to hold the extended format string (allowing 20 characters for formatting the digs value - just in case something like INT_MAX is supplied by mistake), and store the existing string in it. */ rlen = strlen( result ); new = astMalloc( rlen + 22 ); if( new ) memcpy( new, result, rlen + 1 ); /* Put the precision into the new string, following the field width. */ b = new + ( a - result ); b += sprintf( b, ".%d", digs ); /* Copy the remainder of the original format string to the new format string. */ if( a[ 2 ] != 0 ) strcpy( b, a + 2 ); /* Use the new format string in place of the old.*/ astFree( result ); result = new; } } } /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Axis member function (over-rides the protected astSetAttrib * method inherited from the Object class). * Description: * This function assigns an attribute value for an Axis, 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 Axis. * setting * Pointer to a null terminated string specifying the new * attribute value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstAxis *this; /* Pointer to Axis structure */ double dval; /* Double attribute value */ int digits; /* Number of digits of precision */ int direction; /* Plot axis in normal direction? */ int format; /* Offset of Format string */ int label; /* Offset of Label string */ int len; /* Length of setting string */ int nc; /* Number of characters read from setting */ int symbol; /* Offset of Symbol string */ int unit; /* Offset of Unit string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) this_object; /* Obtain the length of the setting string. */ len = (int) strlen( setting ); /* Test for each recognised attribute in turn, using "astSscanf" to parse the setting string and extract the attribute value (or an offset to it in the case of string values). In each case, use the value set in "nc" to check that the entire string was matched. Once a value has been obtained, use the appropriate method to set it. */ /* Digits. */ /* ------- */ if ( nc = 0, ( 1 == astSscanf( setting, "digits= %d %n", &digits, &nc ) ) && ( nc >= len ) ) { astSetAxisDigits( this, digits ); /* Direction. */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "direction= %d %n", &direction, &nc ) ) && ( nc >= len ) ) { astSetAxisDirection( this, direction ); /* Top. */ /* ---- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "top= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetAxisTop( this, dval ); /* Bottom. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "bottom= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetAxisBottom( this, dval ); /* Format. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "format=%n%*[^\n]%n", &format, &nc ) ) && ( nc >= len ) ) { astSetAxisFormat( this, setting + format ); /* Label. */ /* ------ */ } else if ( nc = 0, ( 0 == astSscanf( setting, "label=%n%*[^\n]%n", &label, &nc ) ) && ( nc >= len ) ) { astSetAxisLabel( this, setting + label ); /* Symbol. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "symbol=%n%*[^\n]%n", &symbol, &nc ) ) && ( nc >= len ) ) { astSetAxisSymbol( this, setting + symbol ); /* Unit. */ /* ----- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "unit=%n%*[^\n]%n", &unit, &nc ) ) && ( nc >= len ) ) { astSetAxisUnit( this, setting + unit ); /* Read-only attributes. */ /* --------------------- */ /* Define a macro to see if the setting string matches any of the read-only attributes of this class. */ #define MATCH(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ ( nc >= len ) ) /* Use this macro to report an error if a read-only attribute has been specified. */ } else if ( MATCH( "normunit" ) || MATCH( "internalunit" ) ) { 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 any unrecognised attribute setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Axis member function (over-rides the astTestAttrib protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for one of an Axis' attributes. * Parameters: * this * Pointer to the Axis. * 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: */ AstAxis *this; /* Pointer to the Axis structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { result = astTestAxisDigits( this ); /* Direction. */ /* ---------- */ } else if ( !strcmp( attrib, "direction" ) ) { result = astTestAxisDirection( this ); /* Top. */ /* ---- */ } else if ( !strcmp( attrib, "top" ) ) { result = astTestAxisTop( this ); /* Bottom. */ /* ------- */ } else if ( !strcmp( attrib, "bottom" ) ) { result = astTestAxisBottom( this ); /* Format. */ /* ------- */ } else if ( !strcmp( attrib, "format" ) ) { result = astTestAxisFormat( this ); /* Label. */ /* ------ */ } else if ( !strcmp( attrib, "label" ) ) { result = astTestAxisLabel( this ); /* Symbol. */ /* ------- */ } else if ( !strcmp( attrib, "symbol" ) ) { result = astTestAxisSymbol( this ); /* Unit. */ /* ----- */ } else if ( !strcmp( attrib, "unit" ) ) { result = astTestAxisUnit( this ); /* InternalUnit. */ /* --------- */ } else if ( !strcmp( attrib, "internalunit" ) ) { result = astTestAxisInternalUnit( this ); /* NormUnit. */ /* --------- */ } else if ( !strcmp( attrib, "normunit" ) ) { result = astTestAxisNormUnit( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static int TestAxisInternalUnit( AstAxis *this, int *status ){ /* * Name: * TestAxisInternalUnit * Purpose: * Test if a InternalUnit attribute value is set for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * int TestAxisInternalUnit( AstAxis *this, int *status ) * Class Membership: * Axis member function * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for the InternalUnit string. * Parameters: * this * Pointer to the Axis. * 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. */ /* Tell the world that we know what value to use for InternalUnit if and only if a value has been set for Unit. */ return astTestAxisUnit( this ); } static int TestAxisNormUnit( AstAxis *this, int *status ){ /* * Name: * TestAxisNormUnit * Purpose: * Test if a NormUnit attribute value is set for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * int TestAxisNormUnit( AstAxis *this, int *status ) * Class Membership: * Axis member function * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for the NormUnit string. * Parameters: * this * Pointer to the Axis. * 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. */ return astTestAxisUnit( this ); } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Digits. */ /* ------- */ /* Clear the Digits value by setting it to -INT_MAX. */ astMAKE_CLEAR(Axis,AxisDigits,digits,-INT_MAX) /* Supply a default of 7 digits if no value has been set. */ astMAKE_GET(Axis,AxisDigits,int,0,( this->digits != -INT_MAX ? this->digits : 7 )) /* Constrain the Digits value being set to be at least 1. */ astMAKE_SET(Axis,AxisDigits,int,digits,( value > 1 ? value : 1 )) /* The Digits value is set if it is not -INT_MAX. */ astMAKE_TEST(Axis,AxisDigits,( this->digits != -INT_MAX )) /* Direction. */ /* ---------- */ /* Clear the Direction value by setting it to -INT_MAX. */ astMAKE_CLEAR(Axis,AxisDirection,direction,-INT_MAX) /* Supply a default value of 1 if the Direction value is not set. */ astMAKE_GET(Axis,AxisDirection,int,0,( this->direction != -INT_MAX ? this->direction : 1 )) /* Set a Direction value of 1 if any non-zero value is supplied. */ astMAKE_SET(Axis,AxisDirection,int,direction,( value != 0 )) /* The Direction value is set if it is not -INT_MAX. */ astMAKE_TEST(Axis,AxisDirection,( this->direction != -INT_MAX )) /* Top. */ /* -----*/ /* Clear the Top Direction value by setting it to AST__BAD. */ astMAKE_CLEAR(Axis,AxisTop,top,AST__BAD) /* Supply a default value of DBL_MAX if the Top value is not set.*/ astMAKE_GET(Axis,AxisTop,double,0,( this->top != AST__BAD ? this->top : DBL_MAX)) /* Set the Top value. */ astMAKE_SET(Axis,AxisTop,double,top,(value)) /* The Top value is set if it is not AST__BAD. */ astMAKE_TEST(Axis,AxisTop,( this->top != AST__BAD )) /* Bottom. */ /* --------*/ /* Clear the Bottom Direction value by setting it to AST__BAD. */ astMAKE_CLEAR(Axis,AxisBottom,bottom,AST__BAD) /* Supply a default value of -DBL_MAX if the Bottom value is not set.*/ astMAKE_GET(Axis,AxisBottom,double,0.0,( this->bottom != AST__BAD ? this->bottom : -DBL_MAX)) /* Set the Bottom value. */ astMAKE_SET(Axis,AxisBottom,double,bottom,(value)) /* The Bottom value is set if it is not AST__BAD. */ astMAKE_TEST(Axis,AxisBottom,( this->bottom != AST__BAD )) /* Format. */ /* ------- */ /* Clear the Format value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Axis,AxisFormat,format,astFree( this->format )) /* If the Format value is not set, return a pointer to a default Format string. */ astMAKE_GET(Axis,AxisFormat,const char *,NULL,( this->format ? this->format : GetDefaultFormat( this, status ) ) ) /* Set a Format value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Axis,AxisFormat,const char *,format,astStore( this->format, value, strlen( value ) + (size_t) 1 )) /* The Format value is set if the pointer to it is not NULL. */ astMAKE_TEST(Axis,AxisFormat,( this->format != NULL )) /* Label. */ /* ------ */ /* Clear the Label value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Axis,AxisLabel,label,astFree( this->label )) /* If the Label value is not set, supply a default value by way of a pointer to the constant string "Coordinate Axis". */ astMAKE_GET(Axis,AxisLabel,const char *,NULL,( this->label ? this->label : "Coordinate axis" )) /* Set a Label value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Axis,AxisLabel,const char *,label,astStore( this->label, value, strlen( value ) + (size_t) 1 )) /* The Label value is set if the pointer to it is not NULL. */ astMAKE_TEST(Axis,AxisLabel,( this->label != NULL )) /* Symbol. */ /* ------- */ /* Clear the Symbol value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Axis,AxisSymbol,symbol,astFree( this->symbol )) /* If the Symbol value is not set, supply a default value by way of a pointer to the constant string "x". */ astMAKE_GET(Axis,AxisSymbol,const char *,NULL,( this->symbol ? this->symbol : "x" )) /* Set a Symbol value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Axis,AxisSymbol,const char *,symbol,astStore( this->symbol, value, strlen( value ) + (size_t) 1 )) /* The Symbol value is set if the pointer to it is not NULL. */ astMAKE_TEST(Axis,AxisSymbol,( this->symbol != NULL )) /* Unit. */ /* ----- */ /* Clear the Unit value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Axis,AxisUnit,unit,astFree( this->unit )) /* If the Unit value is not set, supply a default value by way of a pointer to the constant string "". */ astMAKE_GET(Axis,AxisUnit,const char *,NULL,( this->unit ? this->unit : "" )) /* Set a Unit value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Axis,AxisUnit,const char *,unit,astStore( this->unit, value, strlen( value ) + (size_t) 1 )) /* The Unit value is set if the pointer to it is not NULL. */ astMAKE_TEST(Axis,AxisUnit,( this->unit != NULL )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Axis objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Axis objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstAxis *in; /* Pointer to input Axis */ AstAxis *out; /* Pointer to output Axis */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Axis structures. */ in = (AstAxis *) objin; out = (AstAxis *) objout; /* For safety, first clear any references to the input memory from the output Axis. */ out->format = NULL; out->label = NULL; out->symbol = NULL; out->unit = NULL; /* Make copies of the allocated strings and Objects. */ if ( in->label ) out->label = astStore( NULL, in->label, strlen( in->label ) + (size_t) 1 ); if ( in->format ) out->format = astStore( NULL, in->format, strlen( in->format ) + (size_t) 1 ); if ( in->symbol ) out->symbol = astStore( NULL, in->symbol, strlen( in->symbol ) + (size_t) 1 ); if ( in->unit ) out->unit = astStore( NULL, in->unit, strlen( in->unit ) + (size_t) 1 ); /* If an error occurred, clean up by freeing all memory allocated above. */ if ( !astOK ) { out->format = astFree( out->format ); out->label = astFree( out->label ); out->symbol = astFree( out->symbol ); out->unit = astFree( out->unit ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Axis objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Axis objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstAxis *this; /* Pointer to Axis */ /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) obj; /* Free all allocated memory. */ this->format = astFree( this->format ); this->label = astFree( this->label ); this->symbol = astFree( this->symbol ); this->unit = astFree( this->unit ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Axis 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 Axis class to an output Channel. * Parameters: * this * Pointer to the Axis 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 Variables: */ AstAxis *this; /* Pointer to the Axis structure */ char comment[ 80 ]; /* Buffer for comment string */ const char *sval; /* Pointer to string value */ const char *lab; /* Pointer to unit label */ double dval; /* Double value */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Axis structure. */ this = (AstAxis *) this_object; /* Write out values representing the instance variables for the Axis 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. */ /* Label. */ /* ------ */ set = TestAxisLabel( this, status ); sval = set ? GetAxisLabel( this, status ) : astGetAxisLabel( this ); astWriteString( channel, "Label", set, 1, sval, "Axis Label" ); /* Symbol. */ /* ------- */ set = TestAxisSymbol( this, status ); sval = set ? GetAxisSymbol( this, status ) : astGetAxisSymbol( this ); astWriteString( channel, "Symbol", set, 1, sval, "Axis symbol" ); /* Unit. */ /* ----- */ set = TestAxisUnit( this, status ); sval = set ? GetAxisUnit( this, status ) : astGetAxisUnit( this ); /* Get any label associated with the unit string. */ lab = astUnitLabel( sval ); /* Construct a comment including the above label (but only if it is not the same as the unit string) . */ if( lab && strcmp( lab, sval ) ) { (void) sprintf( comment, "Axis units (%s)", lab ); } else { (void) sprintf( comment, "Axis units" ); } /* Write out the Unit value. */ astWriteString( channel, "Unit", set, 0, sval, comment ); /* Digits. */ /* ------- */ set = TestAxisDigits( this, status ); ival = set ? GetAxisDigits( this, status ) : astGetAxisDigits( this ); astWriteInt( channel, "Digits", set, 0, ival, "Default formatting precision" ); /* Format. */ /* ------- */ set = TestAxisFormat( this, status ); sval = set ? GetAxisFormat( this, status ) : astGetAxisFormat( this ); astWriteString( channel, "Format", set, 0, sval, "Format specifier" ); /* Direction. */ /* ---------- */ set = TestAxisDirection( this, status ); ival = set ? GetAxisDirection( this, status ) : astGetAxisDirection( this ); astWriteInt( channel, "Dirn", set, 0, ival, ival ? "Plot in conventional direction (hint)" : "Plot in reverse direction (hint)" ); /* Top. */ /* ---- */ set = TestAxisTop( this, status ); dval = set ? GetAxisTop( this, status ) : astGetAxisTop( this ); astWriteDouble( channel, "Top", set, 0, dval, "Maximum legal axis value" ); /* Bottom. */ /* ------- */ set = TestAxisBottom( this, status ); dval = set ? GetAxisBottom( this, status ) : astGetAxisBottom( this ); astWriteDouble( channel, "Bottom", set, 0, dval, "Minimum legal axis value" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAAxis and astCheckAxis functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Axis,Object) astMAKE_CHECK(Axis) AstAxis *astAxis_( const char *options, int *status, ...) { /* *+ * Name: * astAxis * Purpose: * Create an Axis. * Type: * Public function. * Synopsis: * #include "axis.h" * AstAxis *astAxis( const char *options, int *status, ... ) * Class Membership: * Axis constructor. * Description: * This function creates a new Axis and optionally initialises its * attributes. * Parameters: * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Axis. 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 Axis. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstAxis *new; /* Pointer to new Axis */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the Axis, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitAxis( NULL, sizeof( AstAxis ), !class_init, &class_vtab, "Axis" ); /* 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 Axis' 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 Axis. */ return new; } AstAxis *astAxisId_( const char *options, ... ) { /* * Name: * astAxisId_ * Purpose: * Create an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * AstAxis *astAxisId_( const char *options, ... ); * Class Membership: * Axis constructor. * Description: * This function implements the external (public) interface to the * astAxis constructor function. It returns an ID value (instead of * a true C pointer) to external users, and must be provided * because astAxis_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astAxis_ directly, so it must be a re-implementation of * it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astAxis_. * Returned Value: * The ID value associated with the new Axis. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstAxis *new; /* Pointer to new Axis */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the Axis, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitAxis( NULL, sizeof( AstAxis ), !class_init, &class_vtab, "Axis" ); /* 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 Axis' 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 Axis. */ return astMakeId( new ); } AstAxis *astInitAxis_( void *mem, size_t size, int init, AstAxisVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitAxis * Purpose: * Initialise an Axis. * Type: * Protected function. * Synopsis: * #include "axis.h" * AstAxis *astInitAxis( void *mem, size_t size, int init, * AstAxisVtab *vtab, const char *name ) * Class Membership: * Axis initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Axis object. It allocates memory (if necessary) to accommodate * the Axis plus any additional data associated with the derived class. * It then initialises an Axis structure at the start of this memory. If * the "init" flag is set, it also initialises the contents of a virtual * function table for an Axis at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Axis is to be created. This * must be of sufficient size to accommodate the Axis data * (sizeof(Axis)) 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 Axis (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 Axis * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Axis'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 Axis. * 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 astClass * method). * Returned Value: * A pointer to the new Axis. * 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: */ AstAxis *new; /* Pointer to new Axis */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitAxisVtab( vtab, name ); /* Initialise an Object structure (the parent class) as the first component within the Axis structure, allocating memory if necessary. */ new = (AstAxis *) astInitObject( mem, size, 0, (AstObjectVtab *) vtab, name ); if ( astOK ) { /* Initialise the Axis data. */ /* ------------------------- */ /* Initialise all attributes to their "undefined" values. */ new->digits = -INT_MAX; new->direction = -INT_MAX; new->format = NULL; new->label = NULL; new->symbol = NULL; new->unit = NULL; new->top = AST__BAD; new->bottom = AST__BAD; /* If an error occurred, clean up by deleting the new Axis. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new Axis. */ return new; } AstAxis *astLoadAxis_( void *mem, size_t size, AstAxisVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadAxis * Purpose: * Load an Axis. * Type: * Protected function. * Synopsis: * #include "axis.h" * AstAxis *astLoadAxis( void *mem, size_t size, * AstAxisVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * Axis loader. * Description: * This function is provided to load a new Axis 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 * Axis structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Axis at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Axis is to be * loaded. This must be of sufficient size to accommodate the * Axis data (sizeof(Axis)) 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 Axis (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 Axis 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(AstAxis) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Axis. If this is NULL, a pointer * to the (static) virtual function table for the Axis 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 "Axis" is used instead. * Returned Value: * A pointer to the new Axis. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstAxis *new; /* Pointer to the new Axis */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Axis. In this case the Axis belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstAxis ); vtab = &class_vtab; name = "Axis"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitAxisVtab( 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 Axis. */ new = astLoadObject( mem, size, (AstObjectVtab *) 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, "Axis" ); /* 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. */ /* Label. */ /* ------ */ /* Note that string values do not require any additional processing. */ new->label = astReadString( channel, "label", NULL ); /* Symbol. */ /* ------- */ new->symbol = astReadString( channel, "symbol", NULL ); /* Unit. */ /* ----- */ new->unit = astReadString( channel, "unit", NULL ); /* Digits. */ /* ------- */ new->digits = astReadInt( channel, "digits", -INT_MAX ); if ( TestAxisDigits( new, status ) ) SetAxisDigits( new, new->digits, status ); /* Format. */ /* ------- */ new->format = astReadString( channel, "format", NULL ); /* Direction. */ /* ---------- */ new->direction = astReadInt( channel, "dirn", -INT_MAX ); if ( TestAxisDirection( new, status ) ) SetAxisDirection( new, new->direction, status ); /* Top. */ /* ---- */ new->top = astReadDouble( channel, "top", AST__BAD ); if ( TestAxisTop( new, status ) ) SetAxisTop( new, new->top, status ); /* Bottom. */ /* ---- */ new->bottom = astReadDouble( channel, "bottom", AST__BAD ); if ( TestAxisBottom( new, status ) ) SetAxisBottom( new, new->bottom, status ); /* If an error occurred, clean up by deleting the new Axis. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Axis pointer. */ return new; } /* 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. */ /* External interfaces for the attribute access functions are generated automatically by the macros that implement the access functions themselves. Hence, we need only provide external interfaces for a few additional functions here. */ const char *astAxisAbbrev_( AstAxis *this, const char *fmt, const char *str1, const char *str2, int *status ) { if ( !astOK ) return str2; return (**astMEMBER(this,Axis,AxisAbbrev))( this, fmt, str1, str2, status ); } const char *astAxisFormat_( AstAxis *this, double value, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Axis,AxisFormat))( this, value, status ); } double astAxisDistance_( AstAxis *this, double v1, double v2, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Axis,AxisDistance))( this, v1, v2, status ); } double astAxisOffset_( AstAxis *this, double v1, double dist, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Axis,AxisOffset))( this, v1, dist, status ); } double astAxisCentre_( AstAxis *this, double value, double gap, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,Axis,AxisCentre))( this, value, gap, status ); } double astAxisGap_( AstAxis *this, double gap, int *ntick, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,Axis,AxisGap))( this, gap, ntick, status ); } void astAxisNorm_( AstAxis *this, double *value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Axis,AxisNorm))( this, value, status ); } void astAxisOverlay_( AstAxis *template, AstAxis *result, int *status ) { if ( !astOK ) return; (**astMEMBER(template,Axis,AxisOverlay))( template, result, status ); } int astAxisUnformat_( AstAxis *this, const char *string, double *value, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Axis,AxisUnformat))( this, string, value, status ); } int astAxisFields_( AstAxis *this, const char *fmt, const char *str, int maxfld, char **fields, int *nc, double *val, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Axis,AxisFields))( this, fmt, str, maxfld, fields, nc, val, status ); } int astAxisIn_( AstAxis *this, double lo, double hi, double val, int closed, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Axis,AxisIn))( this, lo, hi, val, closed, status ); } const char *astGetAxisNormUnit_( AstAxis *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Axis,GetAxisNormUnit))( this, status ); } int astTestAxisNormUnit_( AstAxis *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Axis,TestAxisNormUnit))( this, status ); } const char *astGetAxisInternalUnit_( AstAxis *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Axis,GetAxisInternalUnit))( this, status ); } int astTestAxisInternalUnit_( AstAxis *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Axis,TestAxisInternalUnit))( this, status ); } void astAxisNormValues_( AstAxis *this, int oper, int nval, double *values, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Axis,AxisNormValues))( this, oper, nval, values, status ); } ast-8.3.0/GRF_PAR0000664000175000017500000000576213004147320010303 00000000000000*+ * Name: * GRF_PAR * Purpose: * Define the constants needed to implement Fortran GRF routines. * Language: * Fortran 77 * Type of Module: * Include file. * Description: * This file contains definitions which are required by Fortran 77 * programs which implement their own grf routines (routines for * drawing graphics primitive used by the AST Plot class). * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 13-JUN-2001 (DSB): * Original version. *- * Values identifying different graphics attributes. INTEGER GRF__STYLE PARAMETER ( GRF__STYLE = 0 ) INTEGER GRF__WIDTH PARAMETER ( GRF__WIDTH = 1 ) INTEGER GRF__SIZE PARAMETER ( GRF__SIZE = 2 ) INTEGER GRF__FONT PARAMETER ( GRF__FONT = 3 ) INTEGER GRF__COLOUR PARAMETER ( GRF__COLOUR = 4 ) * Values identifying different graphics primatives. INTEGER GRF__TEXT PARAMETER ( GRF__TEXT = 0 ) INTEGER GRF__LINE PARAMETER ( GRF__LINE = 1 ) INTEGER GRF__MARK PARAMETER ( GRF__MARK = 2 ) * The number of different graphics attributes. INTEGER GRF__NATTR PARAMETER ( GRF__NATTR = 5 ) * Values identifying capabilities. INTEGER GRF__ESC PARAMETER ( GRF__ESC = 0 ) INTEGER GRF__MJUST PARAMETER ( GRF__MJUST = 1 ) INTEGER GRF__SCALES PARAMETER ( GRF__SCALES = 2 ) * Values identifying types of graphics escape sequence INTEGER GRF__ESPER PARAMETER ( GRF__ESPER = 1 ) INTEGER GRF__ESSUP PARAMETER ( GRF__ESSUP = 2 ) INTEGER GRF__ESSUB PARAMETER ( GRF__ESSUB = 3 ) INTEGER GRF__ESGAP PARAMETER ( GRF__ESGAP = 4 ) INTEGER GRF__ESBAC PARAMETER ( GRF__ESBAC = 5 ) INTEGER GRF__ESSIZ PARAMETER ( GRF__ESSIZ = 6 ) INTEGER GRF__ESWID PARAMETER ( GRF__ESWID = 7 ) INTEGER GRF__ESFON PARAMETER ( GRF__ESFON = 8 ) INTEGER GRF__ESCOL PARAMETER ( GRF__ESCOL = 9 ) INTEGER GRF__ESSTY PARAMETER ( GRF__ESSTY = 10 ) INTEGER GRF__ESPOP PARAMETER ( GRF__ESPOP = 11 ) INTEGER GRF__ESPSH PARAMETER ( GRF__ESPSH = 12 ) ast-8.3.0/fpermmap.c0000664000175000017500000000671213004147321011210 00000000000000/* *+ * Name: * fpermmap.c * Purpose: * Define a FORTRAN 77 interface to the AST PermMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the PermMap class. * Routines Defined: * AST_ISAPERMMAP * AST_PERMMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 26-SEP-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "permmap.h" /* C interface to the PermMap class */ F77_LOGICAL_FUNCTION(ast_isapermmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPERMMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPermMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_permmap)( INTEGER(NIN), INTEGER_ARRAY(INPERM), INTEGER(NOUT), INTEGER_ARRAY(OUTPERM), DOUBLE_ARRAY(CONSTANT), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NIN) GENPTR_INTEGER_ARRAY(INPERM) GENPTR_INTEGER(NOUT) GENPTR_INTEGER_ARRAY(OUTPERM) GENPTR_DOUBLE_ARRAY(CONSTANT) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_PERMMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPermMap( *NIN, INPERM, *NOUT, OUTPERM, CONSTANT, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/ast_link_adam.in0000664000175000017500000004046713004147320012357 00000000000000 # N.B. the previous line should be blank. #++ # Name: # ast_link_adam # Purpose: # Link an ADAM program with the AST library. # Type of Module: # Shell script. # Description: # This command should only be used when building Starlink ADAM programs # which use the AST library, in order to generate the correct arguments # to allow the ADAM ``alink'' command to link the program. The arguments # generated are written to standard output but may be substituted into # the ``alink'' command line in the standard UNIX way using backward # quotes (see below). # # By default, it is assumed that you are building an ADAM program which # does not produce graphical output. However, switches are provided for # linking other types of program. This command should not be used when # building stand-alone (non-ADAM) programs. Use the ``ast_link'' command # instead. # Invocation: #c alink program.o -L/star/lib `ast_link_adam [switches]` #f alink program.f -L/star/lib `ast_link_adam [switches]` # Switches: # The following switches may optionally be given to this command to # modify its behaviour: # # - ``-csla'': Ignored. Provided for backward compatibility only. # # - ``-fsla'': Ignored. Provided for backward compatibility only. # # - ``-grf'': Requests that no arguments be generated to specify which # 2D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new graphics system yourself and wish to provide your own arguments for # linking with it. This switch differs from the other ``grf'' switches in # that it assumes that your graphics module implements the complete # interface required by the current version of AST. If future versions of # AST introduce new functions to the graphics interface, this switch will # cause ``unresolved symbol'' errors to occur during linking, warning you # that you need to implement new functions in your graphics module. To # avoid such errors, you can use one of the other, version-specific, # switches in place of the ``-grf'' switch, but these will cause run-time # errors to be reported if any AST function is invoked which requires # facilities not in the implemented interface. # # - ``-grf_v2.0'': This switch is equivalent to the ``-mygrf'' switch. # It indicates that you want to link with your own graphics module which # implements the 2D graphics interface required by V2.0 of AST. # # - ``-grf_v3.2'': Indicates that you want to link with your own graphics # module which implements the 2D graphics interface required by V3.2 of AST. # # - ``-grf_v5.6'': Indicates that you want to link with your own graphics # module which implements the 2D graphics interface required by V5.6 of AST. # # - ``-myerr'': Requests that no arguments be generated to specify how # error messages produced by the AST library should be delivered. You # should use this option only if you have implemented an interface to a # new error delivery system yourself and wish to provide your own # arguments for linking with it. By default, error messages are delivered # in the standard ADAM way via the EMS Error Message Service (Starlink # System Note SSN/4). # # - ``-mygrf'': This switch has been superceeded by the ``-grf'' switch, # but is retained in order to allow applications to be linked with a # graphics module which implements the interface used by AST V2.0. It is # equivalent to the ``-grf_v2.0'' switch. # # - ``-pgp'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via the # standard (or ``native'') version of the PGPLOT graphics # package. By default, no graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # # - ``-grf3d'': Requests that no arguments be generated to specify which # 3D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new 3D graphics system yourself and wish to provide your own arguments # for linking with it. # # - ``-pgp3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no 3D graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via # the standard (or ``native'') version of the PGPLOT graphics # package. By default, no 3D graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # SLALIB: # The AST distribution includes a cut down subset of the C version of # the SLALIB library written by Pat Wallace. This subset contains only # the functions needed by the AST library. It is built as part of the # process of building AST and is distributed under GPL (and is thus # compatible with the AST license). Previous version of this script # allowed AST applications to be linked against external SLALIB # libraries (either Fortran or C) rather than the internal version. # The current version of this script does not provide this option, # and always uses the internal SLALIB library. However, for backward # compatibility, this script still allows the "-fsla" and "-csla" flags # (previously used for selecting which version of SLALIB to use) to be # specified, but they will be ignored. # Examples: #c alink display.o -L/star/lib `ast_link_adam -pgplot` #c Links an ADAM program ``display'' which uses the standard #c version of PGPLOT for graphical output. #c alink plotit.o -L. -L/star/lib `ast_link_adam -grf` -lgrf #c Links an ADAM program ``plotit'', written in C. The ``-grf'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by the current version of AST. #c Here, this interface is supplied by means of the ``-lgrf'' library #c reference. #c alink plotit.o -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf #c Links an ADAM program ``plotit'', written in C. The ``-grf_v2.0'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by version 2.0 of AST. Here, #c this interface is supplied by means of the ``-lgrf'' library #c reference. #f alink display.f -L/star/lib `ast_link_adam -pgplot` #f Compiles and links an ADAM Fortran program called ``display'' which #f uses the standard version of PGPLOT for graphical output. #f alink plotit.f -L. -L/star/lib `ast_link_adam -grf` -lgrf #f Compiles and links an ADAM Fortran program ``plotit''. The ``-grf'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by the current version of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. #f alink plotit.f -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf #f Compiles and links an ADAM Fortran program ``plotit''. The ``-grf_v2.0'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by version 2.0 of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. # Copyright: # Copyright (C) 1997-2006 Council for the Central Laboratory of the Research Councils # Authors: # RFWS: R.F. Warren-Smith (STARLINK) # {enter_new_authors_here} # History: # 11-NOV-1996 (RFWS): # Original version. # 18-NOV-1997 (RFWS): # Adapted prologue for document extraction. # 28-SEP-1998 (RFWS): # Distinguish between -pgp and -pgplot options. # 23-JAN-2004 (DSB): # Added switches to support older grf implementations. # 21-APR-2005 (DSB): # Added "-fsla" option. # 16-JUN-2006 (DSB): # Ignore "-fsla" and "-clsa" options, and always use PAL. # 22-AUG-2007 (DSB): # Added "-grf3d", "-pgplot3d" and "-pgp3d" flags. # 4-MAR-2011 (DSB): # Added v5.6 grf options. # {enter_changes_here} # Bugs: # {note_any_bugs_here} #-- # This function searches the directory path specified in PATH, looking for # an executable file which is not a directory. If found, it echos the full # file name to standard output. Otherwise, it outputs nothing. find() { IFS=':'; for d in $PATH; do f="${d:=.}/${1}" test -x "${f}" -a ! -d "${f}" && echo "${f}" && break done; } # Initialise linking options. err='' grf='' grf3d='' sla='' # Interpret command line switches. # -------------------------------- while :; do case "${1}" in # -csla - Previously used to request C version of SLALIB. Now ignored. -csla) # sla='c' shift;; # -fsla - Previously used to request Fortran version of SLALIB. Now ignored. -fsla) # sla='f' shift;; # -myerr - Requests no error reporting. -myerr) err='my' shift;; # -grf - Requests no 2D graphics. -grf) grf='current' shift;; # -mygrf - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -mygrf) grf='v2.0' shift;; # -grf_v2.0 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -grf_v2.0) grf='v2.0' shift;; # -grf_v3.2 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V3.2. -grf_v3.2) grf='v3.2' shift;; # -grf_v5.6 - Requests no 2D graphics, except for null implementations of # functions added to the grf interface after AST V5.6. -grf_v5.6) grf='v5.6' shift;; # -pgp - Requests 2D graphical output through Starlink PGPLOT. -pgp) grf='pgp' shift;; # -pgplot - Requests 2D graphical output through native PGPLOT. -pgplot) grf='pgplot' shift;; # -grf3d - Requests no 3D graphics. -grf3d) grf3d='current' shift;; # -pgp3d - Requests 3D graphical output through Starlink PGPLOT. -pgp3d) grf3d='pgp' shift;; # -pgplot3d - Requests 3D graphical output through native PGPLOT. -pgplot3d) grf3d='pgplot' shift;; # Once all switches have been read, continue with the rest of the script. '') break;; # Catch unrecognised switches and report an error. *) echo >&2 "ast_link_adam: unknown argument \""${1}"\" given" exit 1;; esac done # Link with the main AST library. # ------------------------------- # Start forming the list of arguments with the main AST library itself. args='-last' # Generate arguments for linking PAL. # ----------------------------------- case "@EXTERNAL_PAL@" in # If we configured --with-external_pal include a link option to pick up # an external PAL library. 1) args="${args} -lpal";; # Otherwise, use the internal PAL & ERFA libraries. *) args="${args} -last_pal";; esac # Generate arguments for linking the 2D graphics system. # ------------------------------------------------------ case "${grf}" in # If using Starlink PGPLOT, link with the AST PGPLOT interface and # the Fortran library via the PGP link script. pgp) args="${args} -last_pgplot `pgp_link_adam`";; # If using native PGPLOT, link with the AST PGPLOT interface and # the Fortran library via the PGPLOT link script. pgplot) args="${args} -last_pgplot `pgplot_link_adam`";; # If using own graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # If using own graphics which conform to the requirements of version 5.6 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 5.6. v5.6) :;; # If using own graphics which conform to the requirements of version 3.2 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 3.2. v3.2) args="${args} -last_grf_5.6";; # If using own graphics which conform to the requirements of version 2.0 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 2.0. v2.0) args="${args} -last_grf_3.2 -last_grf_5.6";; # Default graphics (none) requires linking with all the default (null) AST # "grf" modules. *) args="${args} -last_grf_2.0 -last_grf_3.2 -last_grf_5.6";; esac # Generate arguments for linking the 3D graphics system. # ------------------------------------------------------ case "${grf3d}" in # If using Starlink PGPLOT, link with the AST 3D PGPLOT interface and # the Fortran library via the PGP link script (if found). pgp) args="${args} -last_pgplot3d `\`find pgp_link\``" f77='y';; # If using native PGPLOT, link with the AST 3D PGPLOT interface and the # Fortran library via the PGPLOT link script (if found). pgplot) args="${args} -last_pgplot3d `\`find pgplot_link\``" f77='y';; # If using own 3D graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # Default graphics (none) requires linking with all the default (null) AST # "grf3d" modules. *) args="${args} -last_grf3d";; esac # Make a second pass through the AST library. # ------------------------------------------- # This library is a link to the main AST library and results in a second # pass to resolve any backward references generated by the other modules # used above. A different library name must be used to avoid the two passes # being merged into one (either below, or by other link scripts). args="${args} -last_pass2" # Generate arguments for linking the error reporting system. # ---------------------------------------------------------- case "${err}" in # If using own error reporting, do not produce any arguments. my) :;; # Default error reporting requires linking with the AST EMS interface and # the EMS library via the link script. *) args="${args} -last_ems `ems_link_adam`";; esac # Link with the maths library. # ---------------------------- args="${args} -lm" # Link with the starmem library, if available. # -------------------------------------------- args="${args} `\`find starmem_link\``" # Pass the resulting argument list through an awk script which eliminates # all except the last reference to each library. echo "${args}" \ | awk 'BEGIN{RS=" ";FS="\n"} {if($1)f[i++]=$1} END{for(;i--;)if(!w[f[i]]++)l=f[i]" "l;print l}' # End of script. ast-8.3.0/permmap.c0000664000175000017500000035154213004147321011046 00000000000000/* *class++ * Name: * PermMap * Purpose: * Coordinate permutation Mapping. * Constructor Function: c astPermMap f AST_PERMMAP * Description: * A PermMap is a Mapping which permutes the order of coordinates, * and possibly also changes the number of coordinates, between its * input and output. * * In addition to permuting the coordinate order, a PermMap may * also assign constant values to coordinates. This is useful when * the number of coordinates is being increased as it allows fixed * values to be assigned to any new ones. * Inheritance: * The PermMap class inherits from the Mapping class. * Attributes: * The PermMap class does not define any new attributes beyond * those which are applicable to all Mappings. * Functions: c The PermMap class does not define any new functions beyond those f The PermMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 29-FEB-1996 (RFWS): * Original version. * 26-SEP-1996 (RFWS): * Added external interface and I/O facilities. * 3-JUN-1997 (RFWS): * Over-ride the MapMerge method. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitPermMapVtab * method. * 11-SEP-2003 (DSB): * Added methods astGetInPerm and astGetOutPerm. * 2-NOV-2004 (DSB): * Added method astGetConstants. * 14-MAR-2006 (DSB): * Override astEqual. * 2-MAY-2007 (DSB): * Change MapSplit so that it does not try to use the * implementation from the parent Mapping class, since this * class can do a better job. * 11-SEP-2007 (DSB): * In MapSplit, check that the permuted axis index is less than the * number of axes available. Use AST__BAD otherwise. * 10-JAN-2011 (DSB): * Add protected PermSplit attribute. * 11-FEB-2011 (DSB): * Do not allow MapSplit to return a Mapping with zero outputs. * 22-NOV-2012 (DSB): * When using a default inperm array (as indicated by a NULL pointer * for inperm), ensure the array is padded with "-1" values if the * number of inputs exceeds the number of outputs. Also do the * equivalent for default outperm arrays. * 26-MAY-2016 (DSB): * Allow the PermSplit attribute to be changed at any time. This is * because it does not directly affect either the forward or inverse * transformation of the PermMap. The FitsCHan class needs to be able * to change it to determine when checking if the -TAB algorithm can * be used. *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 PermMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "unitmap.h" /* Unit Mappings */ #include "permmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* Module Macros */ /* ============= */ /* A macro that returns the inperm or outperm value to use for a given index, taking account of the possibility that the inperm or outperm may be NULL (implying a unit permutation), and that he numbers of inputs and outputs may not be equal. "perms" is a pointer to the integer permutation array (inperm or outperm), "i" is the index of the required element of the permutation array, and "maxperm" is one more than the maximum value allowed in the permutation array (i.e. the number of PermMap outputs if "perms" is inperm, or PermMap inputs if "perms" is outperm). */ #define PERMVAL( perms, i, maxperm ) ( perms ? perms[ i ] : ( i < maxperm ? i : -1 )) /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(PermMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(PermMap,Class_Init) #define class_vtab astGLOBAL(PermMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPermMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstPermMap *astPermMapId_( int, const int [], int, const int [], const double [], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double *GetConstants( AstPermMap *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int Equal( AstObject *, AstObject *, int * ); static int *GetInPerm( AstPermMap *, int * ); static int *GetOutPerm( AstPermMap *, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int NullPerm( AstPermMap *, int, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void SetPermSplit( AstPermMap *, int, int * ); static void ClearPermSplit( AstPermMap *, int * ); static int TestPermSplit( AstPermMap *, int * ); static int GetPermSplit( AstPermMap *, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two PermMaps are equivalent. * Type: * Private function. * Synopsis: * #include "permmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * PermMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two PermMaps are equivalent. * Parameters: * this * Pointer to the first Object (a PermMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the PermMaps are equivalent, zero otherwise. * 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: */ AstPermMap *that; AstPermMap *this; int *that_inp; int *that_outp; int *this_inp; int *this_outp; int i; int nin; int nin_that; int nout; int nout_that; int p1; int p2; int result; int that_inp_len; int that_outp_len; int this_inp_len; int this_outp_len; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two PermMap structures. */ this = (AstPermMap *) this_object; that = (AstPermMap *) that_object; /* Check the second object is a PermMap. We know the first is a PermMap since we have arrived at this implementation of the virtual function. */ if( astIsAPermMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNout( that ) == nout && astGetNin( that ) == nin ) { /* Assume the PermMaps are equivalent. */ result = 1; /* Get the number of inputs and outputs in the second PermMap. */ nin_that = astGetNin( that ); nout_that = astGetNout( that ); /* Get pointers to the effective inperm and outperm array for each PermMap. If the Invert flags of the two PermMaps are not equal, we swap the arrays for the second PermMap in order to take account of the relative inversion of the second PermMap. */ this_inp = this->inperm; this_outp = this->outperm; if( astGetInvert( this ) ) { this_inp_len = nout; this_outp_len = nin; } else { this_inp_len = nin; this_outp_len = nout; } if( astGetInvert( this ) != astGetInvert( that ) ) { that_inp = that->outperm; that_outp = that->inperm; if( astGetInvert( that ) ) { that_inp_len = nin_that; that_outp_len = nout_that; } else { that_inp_len = nout_that; that_outp_len = nin_that; } } else { that_inp = that->inperm; that_outp = that->outperm; if( astGetInvert( that ) ) { that_inp_len = nout_that; that_outp_len = nin_that; } else { that_inp_len = nin_that; that_outp_len = nout_that; } } /* Loop round every PermMap input. */ for( i = 0; i < nin; i++ ) { /* See what is fed to this input by the inverse transformation. A zero or positive integer "p" value indicates that the input is fed from the output with the corresponding index. A negative integer "p" value means the input is fed a constant value stored at index (-p-1) in the associated constants array. */ p1 = PERMVAL( this_inp, i, this_outp_len ); p2 = PERMVAL( that_inp, i, that_outp_len ); /* If the "p" values differ, we may have evidence that the PermMaps are not equivalent. */ if( p1 != p2 ) { /* If either "p" value is zero or positive, then the PermMaps are definitely different since input "i" is fed from differing outputs, or one is fed from an input and the other is fed a constant. */ if( p1 >= 0 || p2 >= 0 ) { result = 0; break; /* If both "p" values are negative, then both inputs are fed a constant value. The PermMaps differ if these constants differ. */ } else if( this->constant[ -p1 - 1 ] != that->constant[ -p2 - 1 ] ) { result = 0; break; } } } /* If we have not yet discovered any evidence that the PermMaps differ, go on to check each output in the same way that we have just checked the inputs. */ if( result ) { for( i = 0; i < nout; i++ ) { p1 = PERMVAL( this_outp, i, this_inp_len ); p2 = PERMVAL( that_outp, i, that_inp_len ); if( p1 != p2 ) { if( p1 >= 0 || p2 >= 0 ) { result = 0; break; } else if( this->constant[ -p1 - 1 ] != that->constant[ -p2 - 1 ] ) { result = 0; break; } } } } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static double *GetConstants( AstPermMap *this, int *status ){ /* *+ * Name: * astGetConstants * Purpose: * Return a pointer to the constants array of a PermMap. * Type: * Protected virtual function. * Synopsis: * #include "permmap.h" * double *astGetConstants( AstPermMap *this ) * Class Membership: * PermMap method * Description: * This function returns a pointer to a dynamically allocated array * holding a copy of the constants array supplied when the PermMap was * created. * * Negative values in the arrays returned by the astGetInPerm and * astGetOutPerm methods can be used as indices into the constants * array returned by this method, if they are first negated and then * decrement by one. Thus an inperm value of -3 refers to element 2 of * the constants array. * Parameters: * this * Pointer to the PermMap. * Returned Value: * A pointer to a dynamically allocated array holding a copy of the * constants array. The pointer should be freed using astFree when it is * no longer needed. NULL will be returned if the PermMap has no * constants. * Notes: * - A value of NULL will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ double *result; /* Pointer to the returned array */ /* Initialise the returned result. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate memory and put a copy of the InPerm array in it. */ result = (double *) astStore( NULL, this->constant, astSizeOf( this->constant ) ); /* Return the result. */ return result; } static int *GetInPerm( AstPermMap *this, int *status ){ /* * Name: * GetInPerm * Purpose: * Return a pointer to the InPerm array of a PermMap. * Type: * Protected virtual function. * Synopsis: * #include "permmap.h" * int *astGetInPerm( AstPermMap *this, int *status ) * Class Membership: * PermMap method * Description: * This function returns a pointer to a dynamically allocated array * holding a copy of the InPerm array supplied when thre PermMap was * created. * Parameters: * this * Pointer to the PermMap. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated array holding a copy of the * InPerm array. The pointer should be freed using astFree when it is * no longer needed. The number of elements in the array will be given * by the value of the Nin attribute. The value in element "i" is the * zero-based index of the output axis which provides values for input * "i" when the inverse transformation is used. If the value in element * "i" is less than zero, then input "i" is fed a constant value. This * constant value is stored in the "constants" array (see astGetConstants) * at an index equal to the absolute value of inperm[i], minus 1. Thus * if element 3 of the array returned by this function has value -2, * then input axis 3 is fed the value held in constants[1]. If the * value of element "i" of the returned inperm array is greater than * or equal to the number of output axes, then input "i" will be fed * the constant AST__BAD. * Notes: * - A value of NULL will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ int i; /* Loop count */ int nin; /* Number of inputs. */ int *result; /* Pointer to the returned array */ /* Initialise the returned result. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If no inperm array is stored, every input is derived from the corresponding output. Therefore, return an array holding 0 to Nin-1. */ if( !this->inperm ) { nin = astGetNin( this ); result = (int *) astMalloc( sizeof( int ) * (size_t) nin ); if( astOK ) for( i = 0; i < nin; i++ ) result[ i ] = i; /* Otherwise, allocate memoy and put a copy of the InPerm array in it. */ } else { result = (int *) astStore( NULL, this->inperm, sizeof( int ) * (size_t) astGetNin( this ) ); } /* Return the result. */ return result; } static int *GetOutPerm( AstPermMap *this, int *status ){ /* * Name: * GetOutPerm * Purpose: * Return a pointer to the OutPerm array of a PermMap. * Type: * Protected virtual function. * Synopsis: * #include "permmap.h" * int *astGetOutPerm( AstPermMap *this, int *status ) * Class Membership: * PermMap method * Description: * This function returns a pointer to a dynamically allocated array * holding a copy of the OutPerm array supplied when thre PermMap was * created. * Parameters: * this * Pointer to the PermMap. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated array holding a copy of the * OutPerm array. The pointer should be freed using astFree when it is * no longer needed. The number of elements in the array will be given * by the value of the Nout attribute. The value in element "i" is the * zero-based index of the input axis which provides values for output * "i" when the forward transformation is used. If the value in element * "i" is less than zero, then output "i" is fed a constant value. This * constant value is stored in the "constants" array (see astGetConstants) * at an index equal to the absolute value of outperm[i], minus 1. Thus * if element 3 of the array returned by this function has value -2, * then output axis 3 is fed the value held in constants[1]. If the * value of element "i" of the returned outperm array is greater than * or equal to the number of input axes, then output "i" will be fed * the constant AST__BAD. * Notes: * - A value of NULL will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ int i; /* Loop count */ int nout; /* Number of outputs. */ int *result; /* Pointer to the returned array */ /* Initialise the returned result. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If no outperm array is stored, every output is derived from the corresponding input. Therefore, return an array holding 0 to Nout-1. */ if( !this->outperm ) { nout = astGetNout( this ); result = (int *) astMalloc( sizeof( int ) * (size_t) nout ); if( astOK ) for( i = 0; i < nout; i++ ) result[ i ] = i; /* Otherwise, allocate memory and put a copy of the OutPerm array in it. */ } else { result = (int *) astStore( NULL, this->outperm, sizeof( int ) * (size_t) astGetNout( this ) ); } /* Return the result. */ return result; } void astInitPermMapVtab_( AstPermMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPermMapVtab * Purpose: * Initialise a virtual function table for a PermMap. * Type: * Protected function. * Synopsis: * #include "permmap.h" * void astInitPermMapVtab( AstPermMapVtab *vtab, const char *name ) * Class Membership: * PermMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the PermMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPermMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->GetConstants = GetConstants; vtab->GetInPerm = GetInPerm; vtab->GetOutPerm = GetOutPerm; vtab->ClearPermSplit = ClearPermSplit; vtab->GetPermSplit = GetPermSplit; vtab->SetPermSplit = SetPermSplit; vtab->TestPermSplit = TestPermSplit; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; mapping->MapSplit = MapSplit; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->Rate = Rate; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "PermMap", "Coordinate permutation" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a PermMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * PermMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated PermMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated PermMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated PermMap which is to be merged with * its neighbours. This should be a cloned copy of the PermMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * PermMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated PermMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *map; /* Pointer to Mapping */ AstMapping *new; /* Pointer to replacement Mapping */ AstPermMap *permmap; /* Pointer to PermMap */ const char *class; /* Pointer to Mapping class string */ double *con; /* Pointer to constants array */ double constant; /* Constant value */ int *inperm; /* Pointer to "inperm" permutation array */ int *newperm; /* Pointer to new permutation array */ int *outperm; /* Pointer to "outperm" permutation array */ int *perm; /* Pointer to individual permutation array */ int back; /* Considering inverse transformation? */ int coord; /* Loop counter for coordinates */ int icon; /* Loop counter for constants */ int iend; /* Loop ending value */ int imap1; /* Index of first Mapping */ int imap2; /* Index of last Mapping */ int imap; /* Loop counter for Mappings */ int inc; /* Loop increment */ int invert; /* Invert attribute value */ int istart; /* Loop starting value */ int maxperm; /* Max value (+1) allowed in permutation array */ int ncon; /* Number of constants */ int ncoord_in; /* Effective number of input coordinates */ int ncoord_out; /* Effective number of output coordinates */ int ngone; /* Number of Mappings eliminated */ int nin; /* Total number of input coordinates */ int ninsum; /* Accumulated count of input coordinates */ int nout; /* Total number of output coordinates */ int noutsum; /* Accumulated count of output coordinates */ int nperm; /* Number of permutation array elements */ int p; /* Permuted coordinate index */ int result; /* Result value to return */ int simpler; /* Mapping(s) simplified? */ int store_in; /* Need to store "inperm" array contents? */ int store_out; /* Need to store "outperm" array contents? */ int unit; /* Replacement Mapping is a UnitMap? */ /* Initialise the returned result. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ con = NULL; inperm = outperm = NULL; ncon = 0; permmap = NULL; /* In series. */ /* ---------- */ /* Handle the case where the Mappings are connected in series. */ if ( series ) { /* Search adjacent lower-numbered Mappings until one is found which is not a PermMap or a UnitMap. */ imap1 = where; while ( ( imap1 - 1 ) >= 0 ) { class = astGetClass( ( *map_list )[ imap1 - 1 ] ); if ( astOK ) { if ( strcmp( class, "PermMap" ) && strcmp( class, "UnitMap" ) ) break; imap1--; } } /* Similarly search adjacent higher-numbered Mappings. */ imap2 = where; while ( ( imap2 + 1 ) < *nmap ) { class = astGetClass( ( *map_list )[ imap2 + 1 ] ); if ( astOK ) { if ( strcmp( class, "PermMap" ) && strcmp( class, "UnitMap" ) ) break; imap2++; } } /* Obtain a pointer to the first Mapping found and determine if it is to be applied with its Invert attribute set. */ map = ( *map_list )[ imap1 ]; invert = ( *invert_list )[ imap1 ]; /* Use this first Mapping (allowing for how its Invert attribute is currently set) to determine the number of input coordinates that the simplified Mapping should have. */ if ( astGetInvert( map ) ) { nin = invert ? astGetNin( map ) : astGetNout( map ); } else { nin = invert ? astGetNout( map ) : astGetNin( map ); } /* Repeat this process for the last Mapping found, to determine the number of output coordinates for the simplified Mapping. */ map = ( *map_list )[ imap2 ]; invert = ( *invert_list )[ imap2 ]; if ( astGetInvert( map ) ) { nout = invert ? astGetNout( map ) : astGetNin( map ); } else { nout = invert ? astGetNin( map ) : astGetNout( map ); } /* Allocate memory to hold input and output permutation arrays for the simplified Mapping, together with a list of constants. */ inperm = astMalloc( sizeof( int ) * (size_t) nin ); outperm = astMalloc( sizeof( int ) * (size_t) nout ); con = astMalloc( sizeof( double ) * (size_t) ( nin + nout ) ); if ( astOK ) { /* Initialise the number of constants. */ ncon = 0; /* Loop twice, to calculate the forward and inverse (backward) simplified permutation arrays in turn. */ for ( back = 0; back <= 1; back++ ) { /* Obtain a pointer to the appropriate (forward/inverse) permutation array that we wish to fill, and obtain the number of elements it will contain. Initialise the array contents to represent a null permutation.*/ newperm = back ? outperm : inperm; nperm = back ? nout : nin; for ( coord = 0; coord < nperm; coord++ ) newperm[ coord ] = coord; /* Set up limits to scan through the list of Mappings being merged in either the forward or reverse order, as required. */ istart = back ? imap2 : imap1; iend = back ? imap1 - 1 : imap2 + 1; inc = back ? -1 : 1; /* Loop through the Mappings, obtaining a pointer to each, together with the value to be used for its Invert attribute. Invert this attribute value if calculating the overall inverse (backward) permutation array. */ for ( imap = istart; imap != iend; imap += inc ) { map = ( *map_list )[ imap ]; invert = ( *invert_list )[ imap ]; if ( back ) invert = !invert; /* Determine the class to which the Mapping belongs. */ class = astGetClass( map ); if ( astOK ) { /* If it is a PermMap, obtain a pointer to the PermMap structure and hence to the relevant permutation array. Otherwise (if it is a UnitMap), leave the permutation array pointer NULL, which indicates a null permutation. */ perm = NULL; maxperm = astGetNout( map ); if ( !strcmp( class, "PermMap" ) ) { permmap = (AstPermMap *) map; perm = invert ? permmap->outperm : permmap->inperm; } /* Obtain the effective number of output coordinates associated with this individual Mapping (when transforming points in the direction to which this permutation array applies). */ if ( astGetInvert( map ) ) { ncoord_out = invert ? astGetNout( map ) : astGetNin( map ); } else { ncoord_out = invert ? astGetNin( map ) : astGetNout( map ); } /* Loop through the elements of the simplified permutation array to accumulate the effects of the current individual Mapping. */ if ( astOK ) { for ( coord = 0; coord < nperm; coord++ ) { /* Find the effective input coordinate for the current Mapping from the permutation accumulated so far, and check this is not negative. If it is, the accumulated permutation refers to a "bad" coordinate value or a constant, so the current Mapping makes no further difference. */ p = newperm[ coord ]; if ( p >= 0 ) { /* Otherwise, obtain the permuting effect of the current Mapping, allowing for the possibility of its permutation array being NULL (implying a null permutation). */ p = PERMVAL( perm, p, maxperm ); /* If the permuted index refers to a valid (effective) output coordinate for the individual Mapping, then accumulate its effect in the overall permutation array. */ if ( ( p >= 0 ) && ( p < ncoord_out ) ) { newperm[ coord ] = p; /* Otherwise (this can only occur if the individual Mapping is a PermMap), determine whether it refers to a "bad" coordinate value or a constant. If the former, extract the constant's value, otherwise use a constant value of AST__BAD. */ } else { if ( ( p < 0 ) && permmap->constant ) { constant = permmap->constant[ (-p) - 1 ]; } else { constant = AST__BAD; } /* If the result (however reached) is a coordinate value of AST__BAD, then mark the accumulated permutation array with a value of -1 to indicate this. */ if ( constant == AST__BAD ) { newperm[ coord ] = -1; /* Otherwise, search the array of constants to see if this one has been encountered before. If not, append the new constant to the list. */ } else { for ( icon = 0; icon < ncon; icon++ ) { if ( con[ icon ] == constant ) break; } if ( icon == ncon ) con[ ncon++ ] = constant; /* Store a (negative) reference to the new constant in the accumulated permutation array (note we use an extra offset of -1 here in forming these references, so that the value -1 itself can be used to indicate a "bad" coordinate value without an entry in the constants array). */ newperm[ coord ] = (-icon) - 2; } } } } } } } } } /* In parallel. */ /* ------------ */ /* Handle the case where the Mappings are connected in parallel. */ } else { /* Obtain a pointer to the nominated Mapping (which is a PermMap) and determine if it is to be applied with its Invert attribute set. */ map = ( *map_list )[ where ]; invert = ( *invert_list )[ where ]; /* Use this nominated Mapping to initialise the counts of input and output coordinates for the simplified Mapping (allowing for how its Invert attribute is currently set). */ if ( astGetInvert( map ) ) { nin = invert ? astGetNin( map ) : astGetNout( map ); nout = invert ? astGetNout( map ) : astGetNin( map ); } else { nin = invert ? astGetNout( map ) : astGetNin( map ); nout = invert ? astGetNin( map ) : astGetNout( map ); } /* Search adjacent lower-numbered Mappings until one is found which is not a PermMap or a UnitMap. */ imap1 = where; while ( astOK && ( ( imap1 - 1 ) >= 0 ) ) { map = ( *map_list )[ imap1 - 1 ]; class = astGetClass( map ); if ( astOK ) { if ( strcmp( class, "PermMap" ) && strcmp( class, "UnitMap" ) ) break; /* For each Mapping found, obtain the effective numbers of input and output coordinates (allowing for all the direction flags, as above) and accumulate the total count of input and output coordinates for the overall simplified Mapping. */ invert = ( *invert_list )[ imap1 - 1 ]; if ( astGetInvert( map ) ) { nin += ( invert ? astGetNin( map ) : astGetNout( map ) ); nout += ( invert ? astGetNout( map ) : astGetNin( map ) ); } else { nin += ( invert ? astGetNout( map ) : astGetNin( map ) ); nout += ( invert ? astGetNin( map ) : astGetNout( map ) ); } imap1--; } } /* Similarly search higher-numbered Mappings and accumulate their coordinate counts. */ imap2 = where; while ( astOK && ( ( imap2 + 1 ) < *nmap ) ) { map = ( *map_list )[ imap2 + 1 ]; class = astGetClass( map ); if ( astOK ) { if ( strcmp( class, "PermMap" ) && strcmp( class, "UnitMap" ) ) break; invert = ( *invert_list )[ imap2 + 1 ]; if ( astGetInvert( map ) ) { nin += ( invert ? astGetNin( map ) : astGetNout( map ) ); nout += ( invert ? astGetNout( map ) : astGetNin( map ) ); } else { nin += ( invert ? astGetNout( map ) : astGetNin( map ) ); nout += ( invert ? astGetNin( map ) : astGetNout( map ) ); } imap2++; } } /* Allocate memory to hold input and output permutation arrays for the simplified Mapping, together with a list of constants. */ inperm = astMalloc( sizeof( int ) * (size_t) nin ); outperm = astMalloc( sizeof( int ) * (size_t) nout ); con = astMalloc( sizeof( double ) * (size_t) ( nin + nout ) ); if ( astOK ) { /* Initialise the number of constants. */ ncon = 0; /* Loop twice, to calculate the forward and inverse (backward) simplified permutation arrays in turn. */ for ( back = 0; back <= 1; back++ ) { /* Obtain a pointer to the appropriate (forward/inverse) permutation array that we wish to fill, and obtain the number of elements it will contain. */ newperm = back ? outperm : inperm; nperm = back ? nout : nin; /* Initialise counts of (effective) input and output coordinates. */ ninsum = noutsum = 0; /* Loop through the Mappings, obtaining a pointer to each, together with the value to be used for its Invert attribute. Invert this attribute value if calculating the overall inverse (backward) permutation array. */ for ( imap = imap1; imap <= imap2; imap++ ) { map = ( *map_list )[ imap ]; invert = ( *invert_list )[ imap ]; if ( back ) invert = !invert; /* Determine the class to which the Mapping belongs. */ class = astGetClass( map ); if ( astOK ) { /* If it is a PermMap, obtain a pointer to the PermMap structure and hence to the relevant permutation array. Otherwise (if it is a UnitMap), leave the permutation array pointer NULL, which indicates a null permutation. */ perm = NULL; maxperm = astGetNout( map ); if ( !strcmp( class, "PermMap" ) ) { permmap = (AstPermMap *) map; perm = invert ? permmap->outperm : permmap->inperm; } /* Obtain the effective number of input and output coordinates associated with this individual Mapping (when transforming points in the direction to which this permutation array applies). */ if ( astGetInvert( map ) ) { ncoord_in = invert ? astGetNin( map ) : astGetNout( map ); ncoord_out = invert ? astGetNout( map ) : astGetNin( map ); } else { ncoord_in = invert ? astGetNout( map ) : astGetNin( map ); ncoord_out = invert ? astGetNin( map ) : astGetNout( map ); } /* Loop through the (effective) input coordinates of the current individual Mapping to accumulate their effect on the overall permutation array. */ if ( astOK ) { for ( coord = 0; coord < ncoord_in; coord++ ) { /* Obtain the permuting effect of the current Mapping, allowing for the possibility of its permutation array being NULL. */ p = PERMVAL( perm, coord, maxperm ); /* If the permuted index refers to a valid (effective) output coordinate for the individual Mapping, then accumulate its effect on the overall permutation array, allowing for the coordinate numbering offset produced by any Mappings already accumulated. */ if ( ( p >= 0 ) && ( p < ncoord_out ) ) { newperm[ coord + ninsum ] = p + noutsum; /* Otherwise (this can only occur if the individual Mapping is a PermMap), determine whether it refers to a "bad" coordinate value or a constant. If the former, extract the constant's value, otherwise use a constant value of AST__BAD. */ } else { if ( ( p < 0 ) && permmap->constant ) { constant = permmap->constant[ (-p) - 1 ]; } else { constant = AST__BAD; } /* If the result (however reached) is a coordinate value of AST__BAD, then mark the accumulated permutation array with a value of -1 to indicate this. */ if ( constant == AST__BAD ) { newperm[ coord + ninsum ] = -1; /* Otherwise, search the array of constants to see if this one has been encountered before. If not, append the new constant to the list. */ } else { int icon; for ( icon = 0; icon < ncon; icon++ ) { if ( con[ icon ] == constant ) break; } if ( icon == ncon ) con[ ncon++ ] = constant; /* Store a (negative) reference to the new constant in the accumulated permutation array (note we use an extra offset of -1 here in forming these references, so that the value -1 itself can be used to indicate a "bad" coordinate value without an entry in the constants array). */ newperm[ coord + ninsum ] = (-icon) - 2; } } } } /* Accumulate the counts of (effective) input and output coordinates for each individual Mapping. */ ninsum += ncoord_in; noutsum += ncoord_out; } } } } } /* Inspect each element of the accumulated "inperm" array to determine if it needs to be stored by the replacement PermMap. */ if ( astOK ) { store_in = 0; for ( coord = 0; coord < nin; coord++ ) { /* It need not be stored if it produces a null permutation, where each input coordinate takes its value from the corresponding output coordinate (or where a "bad" value results if there is no corresponding output coordinate). Note any deviation from this pattern. */ if ( coord < nout ) { store_in = store_in || ( inperm[ coord ] != coord ); } else { store_in = store_in || ( inperm[ coord ] != -1 ); } /* Also convert permutation array values of -1 into non-existent positive coordinate indices (indicating "bad" coordinate values) and adjust (negative) references to constants by +1 to eliminate the extra offset of -1 used temporarily above. This returns the permutation array values to normal. */ if ( inperm[ coord ] < 0 ) { if ( !++inperm[ coord ] ) inperm[ coord ] = nout; } } /* Similarly inspect the "outperm" array and return its values to normal. */ store_out = 0; for ( coord = 0; coord < nout; coord++ ) { if ( coord < nin ) { store_out = store_out || ( outperm[ coord ] != coord ); } else { store_out = store_out || ( outperm[ coord ] != -1 ); } if ( outperm[ coord ] < 0 ) { if ( !++outperm[ coord ] ) outperm[ coord ] = nin; } } /* Determine how many adjacent Mappings can be eliminated by merging them. */ ngone = imap2 - imap1; /* Determine if the resultant PermMap can be simplified still further to become a UnitMap (a null Mapping). This will be the case if both the forward and inverse coordinate permutations it produces are null, and if the number of input and output coordinates are equal. */ unit = !store_in && !store_out && ( nin == nout ); /* We must now determine whether we have actually produced any simplification. This is important, because if we indicate a simplification when none has, in fact, been achieved, then this function may get called over and over again without end. */ /* Simplification is clearly evident if (a) Mappings have been eliminated ("ngone" is non-zero), or (b) a PermMap has been reduced to a UnitMap, or (c) where there was originally only one PermMap to simplify, its invert flag was set (the replacement Mapping will always have this flag cleared). */ simpler = ngone || unit || ( *invert_list )[ where ]; /* If the above tests do not indicate simplification, then we can only be considering the case where there was a single initial PermMap. In this case we have also achieved simplification if either the "inperm" or "outperm" array no longer needs storing whereas previously it was stored. */ permmap = (AstPermMap *) ( *map_list )[ where ]; if ( !simpler ) { simpler = ( !store_in && !NullPerm( permmap, 0, status ) ) || ( !store_out && !NullPerm( permmap, 1, status ) ); } /* If we still haven't detected any simplification, then compare the original and replacement "inperm" arrays (if present) in detail for equality. We declare simplification to have occurred if they differ. */ if ( !simpler && store_in ) { for ( coord = 0; coord < nin; coord++ ) { simpler = ( inperm[ coord ] != permmap->inperm[ coord ] ); if ( simpler ) break; } } /* Similarly, if necessary, compare the original and replacement "outperm" arrays. */ if ( !simpler && store_out ) { for ( coord = 0; coord < nout; coord++ ) { simpler = ( outperm[ coord ] != permmap->outperm[ coord ] ); if ( simpler ) break; } } /* Do nothing more unless there has been some simplification. */ if ( simpler ) { /* If the PermMaps (and UnitMaps) can be replaced by a UnitMap, then create the replacement. */ if ( unit ) { new = (AstMapping *) astUnitMap( nin, "", status ); /* Otherwise, create a replacement PermMap, setting as many arguments to NULL in the constructor function as can be achieved without affecting the result. */ } else { new = (AstMapping *) astPermMap( nin, store_in ? inperm : NULL, nout, store_out ? outperm : NULL, ncon ? con : NULL, "", status ); } /* Annul the pointers to all the Mappings that are being replaced. */ if ( astOK ) { for ( imap = imap1; imap <= imap2; imap++ ) { ( *map_list )[ imap ] = astAnnul( ( *map_list )[ imap ] ); } /* Insert the new pointer and the associated invert flag. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Loop to close the resulting gap by moving subsequent elements down in the arrays. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - ngone ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - ngone ] = ( *invert_list )[ imap ]; } /* Clear the vacated elements at the end. */ for ( imap = *nmap - ngone; imap < *nmap; imap++ ) { ( *map_list )[ imap ] = NULL; ( *invert_list )[ imap ] = 0; } /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap ) -= ngone; result = imap1; } } } /* Free the workspace arrays. */ inperm = astFree( inperm ); outperm = astFree( outperm ); con = astFree( con ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } 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 * PermMap. * Type: * Private function. * Synopsis: * #include "permmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * PermMap 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 PermMap. This is only possible if the specified inputs * correspond to some subset of the PermMap outputs. That is, there * must exist a subset of the PermMap outputs for which each output * depends only on the selected PermMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied PermMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the PermMap to be split (the PermMap 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 PermMap, 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 PermMap 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 PermMap. 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: */ AstPermMap *this; /* Pointer to PermMap structure */ double *con; /* Pointer to constants array */ int *inp; /* Input perm array to use with supplied PermMap */ int *inpm; /* Input perm array to use with new PermMap */ int *outp; /* Output perm array to use with supplied PermMap */ int *outpm; /* Output perm array to use with new PermMap */ int *result; /* Pointer to returned array */ int i; /* Loop count */ int iin; /* Mapping input index */ int iout; /* Output index */ int j; /* Loop count */ int nout; /* No. of outputs in the new PermMap */ int npin; /* No. of inputs in the supplied Mapping */ int npout; /* No. of outputs in the supplied Mapping */ int ok; /* Are input indices OK? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the PermMap structure. */ this = (AstPermMap *) this_map; /* Get the number of inputs and outputs in the supplied PermMap. */ npin = astGetNin( this ); npout = astGetNout( this ); /* Check all input axis indices are valid. */ ok = 1; for( i = 0; i < nin; i++ ) { if( in[ i ] < 0 || in[ i ] >= npin ) { ok = 0; break; } } /* Get pointers to the input and output permutation arrays and constant array taking account of whether the PermMap has been inverted. */ if( astGetInvert( this ) ) { outp = this->inperm; inp = this->outperm; } else { outp = this->outperm; inp = this->inperm; } con = this->constant; /* The "normal" method, as described in the prologue. */ if( astGetPermSplit( this ) == 0 ) { /* Allocate memory for the returned array of output indices. */ result = astMalloc( sizeof( int )*(size_t) npout ); /* Allocate memory for the inperm and outperm arrays of the returned PermMap. Make these the largest they could possible need to be. */ inpm = astMalloc( sizeof( int )*(size_t) npin ); outpm = astMalloc( sizeof( int )*(size_t) npout ); if( astOK ) { /* Initialise number of outputs in returned PermMap. */ nout = 0; /* Loop round each output of the supplied PermMap. */ for( iout = 0; iout < npout; iout++ ) { /* Is this output fed by one of the selected inputs? If so store the input index of the returned Mapping, which feeds this output and add this output index to the list of returned outputs. */ iin = PERMVAL( outp, iout, npin ); if( iin >= 0 && iin < npin ) { for( i = 0; i < nin; i++ ) { if( in[ i ] == iin ) { outpm[ nout ] = i; result[ nout ] = iout; nout++; break; } } } } /* We now need to set up the inperm array for the returned PermMap. This ensures that the inverse transformation in the returned Mapping provides values for the selected inputs. Loop round all the selected inputs. */ for( i = 0; i < nin; i++ ) { iin = in[ i ]; /* Is this input constant or fed by one of the selected outputs? If so store the output or constant index in the returned Mapping which feeds this input. */ ok = 0; iout = PERMVAL( inp, iin, npout ); if( iout >= 0 && iout < npout ) { for( j = 0; j < nout; j++ ) { if( result[ j ] == iout ) { ok = 1; inpm[ i ] = j; break; } } } else { inpm[ i ] = iout; ok = 1; } /* If this input is fed by an output which has not been selected, then we cannot produce the required Mapping. */ if( !ok ) break; } /* If possible produce the returned PermMap. Otherwise, free the returned array. */ if( ok && nout > 0 ) { *map = (AstMapping *) astPermMap( nin, inpm, nout, outpm, con, "", status ); } else { result = astFree( result ); } /* Free other resources. */ inpm = astFree( inpm ); outpm = astFree( outpm ); } /* The "alternative" method. Only the inperm array is used - the outperm array is assumed to be an exact inverse of the inperm array. In other words, only the inverse transformation is used, and the forward transformation is assumed to be the exact opposite. */ } else { /* The returned array of output indices holds the "inperm" values for the selected inputs. */ result = astMalloc( sizeof( int )*(size_t) nin ); if( astOK ) { for( i = 0; i < nin; i++ ) { result[ i ] = PERMVAL( inp, in[ i ], npout ); /* Check the input is not fed by a constant. */ if( result[ i ] < 0 ) { result = astFree( result ); break; /* Check that the the output has not already been used. */ } else { for( j = 0; j < i; j++ ) { if( result[ j ] == result[ i ] ) { result = astFree( result ); break; } } } } /* If the split was possible, the returned Mapping is a UnitMap. */ if( result ) *map = (AstMapping *) astUnitMap( nin, " ", status ); } } /* If the returned Mapping has no outputs, do not return it. */ if( !result && *map ) { *map = astAnnul( *map ); } /* 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 NullPerm( AstPermMap *this, int forward, int *status ){ /* * Name: * NullPerm * Purpose: * See if a PermMap transformation represents a null axis permutation. * Type: * Private function. * Synopsis: * #include "permmap.h" * int NullPerm( AstPermMap *this, int forward, int *status ) * Class Membership: * PermMap method * Description: * This function returns a logical value indicating if the specified * transformation of the supplied PermMap is a null (i.e. unit) * transformation. * Parameters: * this * Pointer to the PermMap. * forward * Check the forward transformation? Otherise, check the inverse * transformation. * status * Pointer to the inherited status variable. * Returned Value: * One if the specified transformation is a null axis permutation. * Zero 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: */ int i; /* Coordinate index */ int nin; /* Number of Mapping inputs */ int nout; /* Number of Mapping outputs */ int result; /* Returned value */ /* Initialise the returned result. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* First check the forward transformation, given by the outperm array. */ if( forward ) { /* If no outperm array is stored, every output is derived from the corresponding input. Therefore, return 1 indicating a null axis permutation. */ if( !this->outperm ) { result = 1; /* Otherwise, check that every element in the outperm array indicates that the output is derived from the input with the saem index. */ } else { result = 1; nout = astGetNout( this ); for( i = 0; i < nout; i++ ) { if( this->outperm[ i ] != i ) { result = 0; break; } } } /* Now check the inverse transformation, given by the inperm array. */ } else { /* If no inperm array is stored, every input is derived from the corresponding output. Therefore, return 1 indicating a null axis permutation. */ if( !this->inperm ) { result = 1; /* Otherwise, check that every element in the inperm array indicates that the input is derived from the output with the same index. */ } else { result = 1; nin = astGetNin( this ); for( i = 0; i < nin; i++ ) { if( this->inperm[ i ] != i ) { result = 0; break; } } } } /* If an error has occurred, return zero. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static double Rate( AstMapping *this, 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 "permmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * PermMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ /* Local Variables: */ AstPermMap *map; int *outperm; int result; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the PermMap structure. */ map = (AstPermMap *) this; /* Obtain a pointer to the appropriate output coordinate permutation array, according to whether the PermMap has been inverted. If the specified output is derived from the specified input then the rate is unity. Otherwise it is zero. */ outperm = astGetInvert( this ) ? map->inperm : map->outperm; if( outperm ) { result = ( ax2 == outperm[ ax1 ] ) ? 1.0 : 0.0; } else { result = ( ax2 == ax1 ) ? 1.0 : 0.0; } return result; } static AstPointSet *Transform( AstMapping *map, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a PermMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "permmap.h" * AstPointSet *Transform( AstMapping *map, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * PermMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a PermMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required coordinate * permutation. * Parameters: * map * Pointer to the PermMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the PermMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPermMap *this; /* Pointer to PermMap to be applied */ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double constant; /* Constant coordinate value */ int *perm; /* Pointer to permutation array */ int coord; /* Loop counter for coordinates */ int maxperm; /* Max value in permutation array */ int ncoord_in; /* Number of coordinates per input point */ int ncoord_out; /* Number of coordinates per output point */ int npoint; /* Number of points */ int p; /* Permuted coordinate index */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the PermMap. */ this = (AstPermMap *) map; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( map, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the permutation needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input and output PointSets and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); ncoord_out = astGetNcoord( result ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Obtain a pointer to the appropriate coordinate permutation array, according to the direction of transformation required and whether the PermMap has been inverted. Also get the maximum allowed value in the permutation array. */ if ( ( astGetInvert( this ) != 0 ) == ( forward != 0 ) ) { perm = this->inperm; maxperm = ncoord_out; } else { perm = this->outperm; maxperm = ncoord_in; } /* Perform coordinate permutation. */ /* ------------------------------- */ if ( astOK ) { /* Loop to generate values for each output coordinate. */ for ( coord = 0; coord < ncoord_out; coord++ ) { /* If the permutation array is not NULL, use it to look up which input coordinate to use. Otherwise, use the corresponding input coordinate. */ p = PERMVAL( perm, coord, maxperm ); /* If a valid input coordinate has been identified, simply copy the required coordinate values from input to output. */ if ( ( p >= 0 ) && ( p < ncoord_in ) ) { (void) memcpy( ptr_out[ coord ], ptr_in[ p ], sizeof( double ) * (size_t) npoint ); /* If the permuted coordinate index is negative, use it to index the "constant" array to obtain a constant value to assign. If this array is NULL, use AST__BAD as the constant. */ } else if ( p < 0 ) { constant = this->constant ? this->constant[ (-p) - 1 ] : AST__BAD; /* Assign the constant value to the output coordinate for all points. */ for ( point = 0; point < npoint; point++ ) { ptr_out[ coord ][ point ] = constant; } /* In all other cases, simply assign the value AST__BAD to the output coordinate for all points. */ } else { for ( point = 0; point < npoint; point++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* *att+ * Name: * PermSplit * Purpose: * The method to use when splitting a PermMap using astMapSplit. * Type: * Protected attribute. * Synopsis: * Integer. * Description: * This attribute controls the behaviour of the implementation of the * astMapSplit method provided by the PermMap class. If set to zero (the * default), astMapSplit will split PermMaps according to the public * documentation for the method. If set non-zero, the forward transformation * of the PermMap defined by the "outperm" array will be ignored. * Instead, the forward transformation is assumed to be the exact * inverse of the inverse transformation. The Mapping returned will * then be a UnitMap with Nin equal to the number of picked inputs, * and the returned array of output indices will hold the "inperm" * values for the picked inputs. Note, if any of these "inperm" values * are negative (indicating that the inverse transformation supplies a * constant value for the input), or if more than one of the selected * inputs are fed (by the inverse transformation) by the same output, * then the PermMap cannot be split. * * Note, unlike most Mapping attributes, the value of this attribute * may be changed at any time. This is because it does not change the * nature of either the forward or inverse transformation of the Mapping. * Applicability: * PermMap * All PermMaps have this attribute. *att- */ astMAKE_CLEAR(PermMap,PermSplit,permsplit,-INT_MAX) astMAKE_GET(PermMap,PermSplit,int,0,( this->permsplit != -INT_MAX ? this->permsplit : 0 )) astMAKE_SET(PermMap,PermSplit,int,permsplit,( value != 0 )) astMAKE_TEST(PermMap,PermSplit,( this->permsplit != -INT_MAX )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for PermMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for PermMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstPermMap *in; /* Pointer to input PermMap */ AstPermMap *out; /* Pointer to output PermMap */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output PermMaps. */ in = (AstPermMap *) objin; out = (AstPermMap *) objout; /* For safety, first clear any references to the input memory from the output PermMap. */ out->inperm = NULL; out->outperm = NULL; out->constant = NULL; /* For each input array which is not NULL, make a copy in allocated memory, storing a pointer to it in the output PermMap structure. */ if ( in->inperm ) out->inperm = astStore( NULL, in->inperm, astSizeOf( in->inperm ) ); if ( in->outperm ) out->outperm = astStore( NULL, in->outperm, astSizeOf( in->outperm ) ); if ( in->constant ) out->constant = astStore( NULL, in->constant, astSizeOf( in->constant ) ); /* If an error occurred, clean up by freeing all memory allocated above. */ if ( !astOK ) { out->inperm = astFree( out->inperm ); out->outperm = astFree( out->outperm ); out->constant = astFree( out->constant ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for PermMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for PermMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstPermMap *this; /* Pointer to PermMap */ /* Obtain a pointer to the PermMap structure. */ this = (AstPermMap *) obj; /* Free all memory allocated by the PermMap. */ this->inperm = astFree( this->inperm ); this->outperm = astFree( this->outperm ); this->constant = astFree( this->constant ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for PermMap 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 PermMap class to an output Channel. * Parameters: * this * Pointer to the PermMap 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: */ AstPermMap *this; /* Pointer to the PermMap structure */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment strings */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword strings */ int coord; /* Loop counter for coordinates */ int iconst; /* Loop counter for constants */ int invert; /* Invert attribute value */ int ival; /* Integer value */ int nconst; /* Number of constants */ int nin; /* Number of input coordinates */ int nout; /* Number of output coordinates */ int set; /* Value is "set"? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PermMap structure. */ this = (AstPermMap *) this_object; /* Determine if the PermMap is inverted and obtain the "true" number of input and output coordinates by un-doing the effects of any inversion. */ invert = astGetInvert( this ); nin = !invert ? astGetNin( this ) : astGetNout( this ); nout = !invert ? astGetNout( this ) : astGetNin( this ); /* Initialise the count of constants in use. */ nconst = 0; /* Write out values representing the instance variables for the PermMap 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. */ /* PermSplit */ /* --------- */ set = TestPermSplit( this, status ); ival = set ? GetPermSplit( this, status ) : astGetPermSplit( this ); astWriteInt( channel, "pmsplt", set, 0, ival, ival ? "Use alternative astMapSplit implementation" : "Use normal astMapSplit implementation" ); /* "outperm" array contents. */ /* ------------------------- */ /* Write the boolean "OutCpy" value to indicate if output coordinates are obtained simply by copying corresponding input coordinates. This will be the case if "this->outperm" is NULL. */ ival = this->outperm ? 0 : 1; set = ( ival != 0 ); astWriteInt( channel, "OutCpy", set, 0, ival, ival ? "Output coordinates = input coordinates" : "Output coordinates specified individually" ); /* If output coordinates are specified individually, create a keyword for each element of the "outperm" array. */ if ( this->outperm ) { for ( coord = 0; coord < nout; coord++ ) { (void) sprintf( key, "Out%d", coord + 1 ); /* Obtain the array value. If it refers to a coordinate that does not exist, change the value to zero (indicating a "bad" value for this coordinate). Create an appropriate comment. */ ival = this->outperm[ coord ]; if ( ival >= nin ) { ival = 0; (void) sprintf( comment, "Output coordinate %d is \"bad\"", coord + 1 ); /* If the coordinate reference is valid, convert to 1-based coordinate numbering and create an appropriate comment. */ } else if ( ival >= 0 ) { ival++; (void) sprintf( comment, "Output coordinate %d = input coordinate %d", coord + 1, ival ); /* If the reference is to a constant, create an appropriate comment (which depends on whether there are any constants). */ } else { if ( this->constant ) { (void) sprintf( comment, "Output coordinate %d = constant no. %d", coord + 1, -ival ); } else { (void) sprintf( comment, "Output coordinate %d is \"bad\"", coord + 1 ); } /* Update the top constant number referenced. */ if ( nconst < -ival ) nconst = -ival; } /* Write out the array value with accompanying comment. */ astWriteInt( channel, key, 1, 1, ival, comment ); } } /* "inperm" array contents. */ /* ------------------------ */ /* Write the boolean "InCpy" value to indicate if input coordinates are obtained simply by copying corresponding output coordinates. This will be the case if "this->inperm" is NULL. */ ival = this->inperm ? 0 : 1; set = ( ival != 0 ); astWriteInt( channel, "InCpy", set, 0, ival, ival ? "Input coordinates = output coordinates" : "Input coordinates specified individually" ); /* If input coordinates are specified individually, create a keyword for each element of the "inperm" array. */ if ( this->inperm ) { for ( coord = 0; coord < nin; coord++ ) { (void) sprintf( key, "In%d", coord + 1 ); /* Obtain the array value. If it refers to a coordinate that does not exist, change the value to zero (indicating a "bad" value for this coordinate). Create an appropriate comment. */ ival = this->inperm[ coord ]; if ( ival >= nout ) { ival = 0; (void) sprintf( comment, "Input coordinate %d is \"bad\"", coord + 1 ); /* If the coordinate reference is valid, convert to 1-based coordinate numbering and create an appropriate comment. */ } else if ( ival >= 0 ) { ival++; (void) sprintf( comment, "Input coordinate %d = output coordinate %d", coord + 1, ival ); /* If the reference is to a constant, create an appropriate comment (which depends on whether there are any constants). */ } else { if ( this->constant ) { (void) sprintf( comment, "Input coordinate %d = constant no. %d", coord + 1, -ival ); } else { (void) sprintf( comment, "Input coordinate %d is \"bad\"", coord + 1 ); } /* Update the top constant number referenced. */ if ( nconst < -ival ) nconst = -ival; } /* Write out the array value with accompanying comment. */ astWriteInt( channel, key, 1, 1, ival, comment ); } } /* Number of constants. */ /* -------------------- */ /* First check if there are any constants, then write out how many there are. */ if ( !this->constant ) nconst = 0; set = ( nconst != 0 ); astWriteInt( channel, "Nconst", set, 0, nconst, "Number of constants" ); /* Constants. */ /* ---------- */ /* Loop to create a keyword and comment for each constant. */ for ( iconst = 0; iconst < nconst; iconst++ ) { (void) sprintf( key, "Con%d", iconst + 1 ); (void) sprintf( comment, "Constant number %d", iconst + 1 ); /* Write out each constant value and comment. */ set = ( this->constant[ iconst ] != AST__BAD ); if ( set ) { astWriteDouble( channel, key, 1, 1, this->constant[ iconst ], comment ); } else { astWriteString( channel, key, 0, 1, "", comment ); } } /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPermMap and astCheckPermMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(PermMap,Mapping) astMAKE_CHECK(PermMap) AstPermMap *astPermMap_( int nin, const int inperm[], int nout, const int outperm[], const double constant[], const char *options, int *status, ...) { /* *++ * Name: c astPermMap f AST_PERMMAP * Purpose: * Create a PermMap. * Type: * Public function. * Synopsis: c #include "permmap.h" c AstPermMap *astPermMap( int nin, const int inperm[], int nout, c const int outperm[], double constant[], c const char *options, ... ) f RESULT = AST_PERMMAP( NIN, INPERM, NOUT, OUTPERM, CONSTANT, OPTIONS, f STATUS ) * Class Membership: * PermMap constructor. * Description: * This function creates a new PermMap and optionally initialises its * attributes. * * A PermMap is a Mapping which permutes the order of coordinates, * and possibly also changes the number of coordinates, between its * input and output. * * In addition to permuting the coordinate order, a PermMap may * also assign constant values to coordinates. This is useful when * the number of coordinates is being increased as it allows fixed * values to be assigned to any new ones. * Parameters: c nin f NIN = INTEGER (Given) * The number of input coordinates. c inperm f INPERM = INTEGER( NIN ) (Given) c An optional array with "nin" elements which, for each input f An array which, for each input * coordinate, should contain the number of the output * coordinate whose value is to be used (note that this array * therefore defines the inverse coordinate transformation). * Coordinates are numbered starting from 1. * * For details of additional special values that may be used in c this array, see the description of the "constant" parameter. f this array, see the description of the CONSTANT argument. c c If a NULL pointer is supplied instead of an array, each input c coordinate will obtain its value from the corresponding c output coordinate (or will be assigned the value AST__BAD if c there is no corresponding output coordinate). c nout f NOUT = INTEGER (Given) * The number of output coordinates. c outperm f OUTPERM = INTEGER( NOUT ) (Given) c An optional array with "nout" elements which, for each output f An array which, for each output * coordinate, should contain the number of the input coordinate * whose value is to be used (note that this array therefore * defines the forward coordinate transformation). Coordinates * are numbered starting from 1. * * For details of additional special values that may be used in c this array, see the description of the "constant" parameter. f this array, see the description of the CONSTANT argument. c c If a NULL pointer is supplied instead of an array, each output c coordinate will obtain its value from the corresponding c input coordinate (or will be assigned the value AST__BAD if c there is no corresponding input coordinate). c constant f CONSTANT = DOUBLE PRECISION( * ) (Given) c An optional array containing values which may be assigned to f An array containing values which may be assigned to * input and/or output coordinates instead of deriving them c from other coordinate values. If either of the "inperm" or f from other coordinate values. If either of the INPERM or c "outperm" arrays contains a negative value, it is used to f OUTPERM arrays contains a negative value, it is used to c address this "constant" array (such that -1 addresses the f address this CONSTANT array (such that -1 addresses the * first element, -2 addresses the second element, etc.) and the * value obtained is used as the corresponding coordinate value. * * Care should be taken to ensure that locations lying outside * the extent of this array are not accidentally addressed. The c array is not used if the "inperm" and "outperm" arrays do not f array is not used if the INPERM and OUTPERM arrays do not * contain negative values. c c If a NULL pointer is supplied instead of an array, the c behaviour is as if the array were of infinite length and c filled with the value AST__BAD. 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 PermMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new PermMap. The syntax used is identical to that for the f AST_SET routine. 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 astPermMap() f AST_PERMMAP = INTEGER * A pointer to the new PermMap. * Notes: c - If either of the "inperm" or "outperm" arrays contains a f - If either of the INPERM or OUTPERM arrays contains a * zero value (or a positive value which does not identify a valid * output/input coordinate, as appropriate), then the value * AST__BAD is assigned as the new coordinate value. * - This function does not attempt to ensure that the forward and * inverse transformations performed by the PermMap are * self-consistent in any way. You are therefore free to supply * coordinate permutation arrays that achieve whatever effect is * desired. * - 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPermMap *new; /* Pointer to new PermMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the PermMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPermMap( NULL, sizeof( AstPermMap ), !class_init, &class_vtab, "PermMap", nin, inperm, nout, outperm, constant ); /* 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 PermMap'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 PermMap. */ return new; } AstPermMap *astPermMapId_( int nin, const int inperm[], int nout, const int outperm[], const double constant[], const char *options, ... ) { /* * Name: * astPermMapId_ * Purpose: * Create a PermMap. * Type: * Private function. * Synopsis: * #include "permmap.h" * AstPermMap *astPermMapId_( int nin, const int inperm[], int nout, * const int outperm[], const double constant[], * const char *options, ... ) * Class Membership: * PermMap constructor. * Description: * This function implements the external (public) interface to the * astPermMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astPermMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * This function also converts the coordinate numbering in the * permutation arrays from 1-based (used externally) to zero-based * (used internally). * * The variable argument list also prevents this function from * invoking astPermMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astPermMap_. * Returned Value: * The ID value associated with the new PermMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPermMap *new; /* Pointer to new PermMap */ int *inperm1; /* Pointer to temporary copy of "inperm" */ int *outperm1; /* Pointer to temporary copy of "outperm" */ int coord; /* Loop counter for coordinates */ /* Variable argument list */ va_list args; /* Get a pointer to the thread specific global data structure. */ int *status; /* Pointer to inherited status value */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* If the "nin" and "nout" values are acceptable, allocate memory to hold temporary copies of the "inperm" and "outperm" arrays (but only if these arrays are not NULL). */ inperm1 = NULL; outperm1 = NULL; if ( ( nin >= 0 ) && ( nout >= 0 ) ) { if ( inperm ) inperm1 = astMalloc( sizeof( int ) * (size_t) nin ); if ( outperm ) outperm1 = astMalloc( sizeof( int ) * (size_t) nout ); if ( astOK ) { /* If necessary, make a copy of the "inperm" array, converting any zero values into (zero-based) coordinate numbers that do not exist, indicating a "bad" coordinate value. */ if ( inperm ) { for ( coord = 0; coord < nin; coord++ ) { if ( inperm[ coord ] < 0 ) { inperm1[ coord ] = inperm[ coord ]; } else if ( inperm[ coord ] == 0 ) { inperm1[ coord ] = nout; /* Convert valid coordinate references from 1-based (used externally) to zero-based (used internally). */ } else { inperm1[ coord ] = inperm[ coord ] - 1; } } } /* Repeat this process on the "outperm" array. */ if ( outperm ) { for ( coord = 0; coord < nout; coord++ ) { if ( outperm[ coord ] < 0 ) { outperm1[ coord ] = outperm[ coord ]; } else if ( outperm[ coord ] == 0 ) { outperm1[ coord ] = nin; } else { outperm1[ coord ] = outperm[ coord ] - 1; } } } } } /* Initialise the PermMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPermMap( NULL, sizeof( AstPermMap ), !class_init, &class_vtab, "PermMap", nin, inperm1, nout, outperm1, constant ); /* If necessary, free the temporary arrays allocated above. */ if ( ( nin >= 0 ) && ( nout >= 0 ) ) { if ( inperm ) inperm1 = astFree( inperm1 ); if ( outperm ) outperm1 = astFree( outperm1 ); } /* 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 PermMap'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 PermMap. */ return astMakeId( new ); } AstPermMap *astInitPermMap_( void *mem, size_t size, int init, AstPermMapVtab *vtab, const char *name, int nin, const int inperm[], int nout, const int outperm[], const double constant[], int *status ) { /* *+ * Name: * astInitPermMap * Purpose: * Initialise a PermMap. * Type: * Protected function. * Synopsis: * #include "permmap.h" * AstPermMap *astInitPermMap( void *mem, size_t size, int init, * AstPermMapVtab *vtab, const char *name, * int nin, const int inperm[], * int nout, const int outperm[], * const double constant[] ) * Class Membership: * PermMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new PermMap object. It allocates memory (if necessary) to accommodate * the PermMap plus any additional data associated with the derived class. * It then initialises a PermMap 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 PermMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the PermMap is to be initialised. * This must be of sufficient size to accommodate the PermMap data * (sizeof(PermMap)) 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 PermMap (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 PermMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the PermMap'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 PermMap. * 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 Object * astClass function). * nin * The number of input coordinate values per point. * inperm * Pointer to an array of int, with nin elements. For each input * coordinate, the corresponding element of this array should contain the * (zero-based) index of the output coordinate whose value is to be used. * (Note that this array therefore defines the inverse coordinate * transformation.) If a NULL value is supplied, the corresponding output * coordinate value is used (or AST__BAD if there is no corresponding * output coordinate). * * For details of additional special values that may be used in this * array, see the description of the "constant" parameter. * nout * The number of output coordinate values per point. * outperm * Pointer to an array of int, with nout elements. For each output * coordinate, the corresponding element of this array should contain the * (zero-based) index of the input coordinate whose value is to be used. * (Note that this array therefore defines the forward coordinate * transformation.) If a NULL value is supplied, the corresponding input * coordinate value is used (or AST__BAD if there is no corresponding * input coordinate). * * For details of additional special values that may be used in this * array, see the description of the "constant" parameter. * constant * Pointer to an array of double, which contains optional values which * may be assigned to input and/or output coordinate values (instead of * deriving them from other coordinate values). If either of the * "inperm" or "outperm" arrays contains a negative value, it is used to * address this "constant" array (such that -1 addresses the first * element, -2 addresses the second element, etc.) and the value obtained * is used as the corresponding coordinate value. Care should be taken * to ensure that locations lying outside the extent of this array are * not accidentally addressed. * * If a NULL value is supplied for this parameter, the behaviour is as * if the constant array were of infinite length and filled with the * value AST__BAD. * Returned Value: * A pointer to the new PermMap. * Notes: * - This function does not attempt to ensure that the forward and inverse * transformations performed by the resulting PermMap are consistent in any * way. The caller is therefore free to define the permutation arrays to * achieve whatever effect is desired. * - If either of the "inperm" or "outperm" arrays contains a positive * value which does not identify a valid output/input coordinate (as * appropriate), then the value AST__BAD is assigned as the new coordinate * value. * - This function makes a copy of the contents of the arrays supplied. * - 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: */ AstPermMap *new; /* Pointer to new PermMap */ int i; /* Loop counter for coordinates */ int neg; /* Most negative permutation index */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPermMapVtab( vtab, name ); /* Initialise a Mapping structure (the parent class) as the first component within the PermMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstPermMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, 1, 1 ); if ( astOK ) { /* Initialise the PermMap data. */ /* ---------------------------- */ new->permsplit = -INT_MAX; /* Initialise the array pointers. */ new->inperm = NULL; new->outperm = NULL; new->constant = NULL; /* If an "inperm" and/or "outperm" array has been supplied, allocate memory and store a copy. */ if ( inperm ) new->inperm = astStore( NULL, inperm, sizeof( int ) * (size_t) nin ); if ( outperm ) new->outperm = astStore( NULL, outperm, sizeof( int ) * (size_t) nout ); /* If a "constant" array has been supplied, we must also store a copy of it, but must first determine how many of its elements we need. */ if ( constant ) { /* Loop through the "inperm" array (if supplied) to find the most negative value it contains. This corresponds with the maximum index into the constant array. */ neg = 0; if ( inperm ) { for ( i = 0; i < nin; i++ ) { if ( inperm[ i ] < neg ) neg = inperm[ i ]; } } /* Also perform this process on the "outperm" array (if supplied). */ if ( outperm ) { for ( i = 0; i < nout; i++ ) { if ( outperm[ i ] < neg ) neg = outperm[ i ]; } } /* If a negative value was found, use its size to determine how many elements of the "constant" array to store in allocated memory. */ if ( neg < 0 ) { new->constant = astStore( NULL, constant, sizeof( double ) * (size_t) (-neg) ); } } /* 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; } AstPermMap *astLoadPermMap_( void *mem, size_t size, AstPermMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPermMap * Purpose: * Load a PermMap. * Type: * Protected function. * Synopsis: * #include "permmap.h" * AstPermMap *astLoadPermMap( void *mem, size_t size, * AstPermMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * PermMap loader. * Description: * This function is provided to load a new PermMap 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 * PermMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a PermMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the PermMap is to be * loaded. This must be of sufficient size to accommodate the * PermMap data (sizeof(PermMap)) 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 PermMap (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 PermMap 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(AstPermMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new PermMap. If this is NULL, a pointer * to the (static) virtual function table for the PermMap 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 "PermMap" is used instead. * Returned Value: * A pointer to the new PermMap. * 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: */ AstPermMap *new; /* Pointer to the new PermMap */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword strings */ int coord; /* Loop counter for coordinates */ int iconst; /* Loop counter for constants */ int in_cpy; /* Input coordinates obtained by copying? */ int invert; /* Invert attribute value */ int ival; /* Integer value */ int nconst; /* Number of constants */ int nin; /* Number of input coordinates */ int nout; /* Number of output coordinates */ int out_cpy; /* Output coordinates obtained by copying? */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this PermMap. In this case the PermMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPermMap ); vtab = &class_vtab; name = "PermMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPermMapVtab( 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 PermMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "PermMap" ); /* 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. */ /* Initialise the PermMap's pointers. */ new->inperm = NULL; new->outperm = NULL; new->constant = NULL; /* Determine if the PermMap is inverted and obtain the "true" number of input and output coordinates by un-doing the effects of any inversion. */ invert = astGetInvert( new ); nin = !invert ? astGetNin( new ) : astGetNout( new ); nout = !invert ? astGetNout( new ) : astGetNin( new ); /* PermSplit. */ /* ---------- */ new->permsplit = astReadInt( channel, "pmsplt", -INT_MAX ); if ( TestPermSplit( new, status ) ) SetPermSplit( new, new->permsplit, status ); /* InCpy and OutCpy. */ /* ----------------- */ /* Obtain boolean values via the "InCpy" and "OutCpy" keywords which indicate if input/output coordinates should be obtained simply by copying the corresponding output/input coordinates. */ in_cpy = astReadInt( channel, "incpy", 0 ); out_cpy = astReadInt( channel, "outcpy", 0 ); /* If coordinates are specified individually (not simply copied), then allocate memory for the coordinate permutation arrays. */ if ( !in_cpy ) new->inperm = astMalloc( sizeof( int ) * (size_t) nin ); if ( !out_cpy ) new->outperm = astMalloc( sizeof( int ) * (size_t) nout ); /* If an error occurred, ensure that all allocated memory is freed. */ if ( !astOK ) { if ( !in_cpy ) new->inperm = astFree( new->inperm ); if ( !out_cpy ) new->outperm = astFree( new->outperm ); /* Otherwise read data into these arrays... */ } else { /* "inperm" array contents. */ /* ------------------------ */ /* If required, create a keyword for each element of the "inperm" array and read the element's value. */ if ( !in_cpy ) { for ( coord = 0; coord < nin; coord++ ) { (void) sprintf( key, "in%d", coord + 1 ); ival = astReadInt( channel, key, 0 ); /* If the value is zero (indicating a "bad" coordinate), convert it to a (zero-based) coordinate number that doesn't exist. */ if ( ival == 0 ) { ival = nout; /* If the coordinate reference is valid, convert to zero-based coordinate numbering for internal use. */ } else if ( ival > 0 ) { ival--; } /* Store the value. */ new->inperm[ coord ] = ival; } } /* "outperm" array contents. */ /* ------------------------- */ /* If required, create a keyword for each element of the "outperm" array and read the element's value. */ if ( !out_cpy ) { for ( coord = 0; coord < nout; coord++ ) { (void) sprintf( key, "out%d", coord + 1 ); ival = astReadInt( channel, key, 0 ); /* If the value is zero (indicating a "bad" coordinate), convert it to a (zero-based) coordinate number that doesn't exist. */ if ( ival == 0 ) { ival = nin; /* If the coordinate reference is valid, convert to zero-based coordinate numbering for internal use. */ } else if ( ival > 0 ) { ival--; } /* Store the value. */ new->outperm[ coord ] = ival; } } /* Number of constants. */ /* -------------------- */ /* Determine the number of constants and allocate memory to hold them. */ nconst = astReadInt( channel, "nconst", 0 ); if ( nconst < 0 ) nconst = 0; new->constant = astMalloc( sizeof( double ) * (size_t) nconst ); if ( astOK ) { /* Constants. */ /* ---------- */ /* Create a keyword for each constant and read its value. */ for ( iconst = 0; iconst < nconst; iconst++ ) { (void) sprintf( key, "con%d", iconst + 1 ); new->constant[ iconst ] = astReadDouble( channel, key, AST__BAD ); } } } /* If an error occurred, clean up by deleting the new PermMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new PermMap 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. */ double *astGetConstants_( AstPermMap *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,PermMap,GetConstants))( this, status ); } int *astGetInPerm_( AstPermMap *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,PermMap,GetInPerm))( this, status ); } int *astGetOutPerm_( AstPermMap *this, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,PermMap,GetOutPerm))( this, status ); } ast-8.3.0/err.h0000664000175000017500000000340513004147321010172 00000000000000#if !defined( ERR_INCLUDED ) /* Include this file only once */ #define ERR_INCLUDED /* *+ * Name: * err.h * Type: * C include file. * Purpose: * Define the interface to the err module. * Invocation: * #include "err.h" * Description: * This include file defines the interface to the err module and * provides the type definitions, function prototypes and macros, etc. * needed to use this module. * Inheritance: * The err module is not a class and does not inherit. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (STARLINK) * {enter_new_authors_here} * History: * 6-NOV-1996 (DSB): * Original version. * {enter_changes_here} *- */ /* Function prototypes. */ /* ==================== */ #if defined(astCLASS) /* Protected */ void astPutErr_( int, const char * ); /* Function interfaces. */ /* ==================== */ #define astPutErr(status,message) astPutErr_(status,message) #endif #endif ast-8.3.0/specframe.c0000664000175000017500000077140313004147321011354 00000000000000/* *class++ * Name: * SpecFrame * Purpose: * Spectral coordinate system description. * Constructor Function: c astSpecFrame f AST_SPECFRAME * Description: * A SpecFrame is a specialised form of one-dimensional Frame which * represents various coordinate systems used to describe positions within * an electro-magnetic spectrum. The particular coordinate system to be * used is specified by setting the SpecFrame's System attribute (the * default is wavelength) qualified, as necessary, by other attributes * such as the rest frequency, the standard of rest, the epoch of * observation, units, etc (see the description of the System attribute * for details). * * By setting a value for thr SpecOrigin attribute, a SpecFrame can be made * to represent offsets from a given spectral position, rather than absolute * spectral values. * Inheritance: * The SpecFrame class inherits from the Frame class. * Attributes: * In addition to those attributes common to all Frames, every * SpecFrame also has the following attributes: * * - AlignSpecOffset: Align SpecFrames using the offset coordinate system? * - AlignStdOfRest: Standard of rest in which to align SpecFrames * - RefDec: Declination of the source (FK5 J2000) * - RefRA: Right ascension of the source (FK5 J2000) * - RestFreq: Rest frequency * - SourceSys: Source velocity spectral system * - SourceVel: Source velocity * - SourceVRF: Source velocity rest frame * - SpecOrigin: The zero point for SpecFrame axis values * - StdOfRest: Standard of rest * * Several of the Frame attributes inherited by the SpecFrame class * refer to a specific axis of the Frame (for instance Unit(axis), * Label(axis), etc). Since a SpecFrame is strictly one-dimensional, * it allows these attributes to be specified without an axis index. * So for instance, "Unit" is allowed in place of "Unit(1)". * Functions: c In addition to those functions applicable to all Frames, the c following functions may also be applied to all SpecFrames: f In addition to those routines applicable to all Frames, the f following routines may also be applied to all SpecFrames: * c - astSetRefPos: Set reference position in any celestial system f - AST_SETREFPOS: Set reference position in any celestial system c - astGetRefPos: Get reference position in any celestial system f - AST_GETREFPOS: Get reference position in any celestial system * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 4-NOV-2002 (DSB): * Original version. * 2-FEB-2005 (DSB): * - Avoid using astStore to allocate more storage than is supplied * in the "data" pointer. This can cause access violations since * astStore will then read beyond the end of the "data" area. * 22-MAR-2005 (DSB): * - Re-structure MakeSpecMapping in order to avoid unnecessary * access to SpecFrame attributes which may not be set, and to * check that all required attributes have been set if UseDefs is * zero. * 23-MAR-2005 (DSB): * - Added missing rest frames to SorEqual. * 12-AUG-2005 (DSB): * - Remove GeoLon and GeoLat attributes. Use the new ObsLon and * ObsLat attributes in the parent Frame class instead. Note, for * backward compatibility the public attribute accessors and the * astLoadSpecFrame functions still recogonise GeoLon and GeoLat, * but use the ObsLat/ObsLon attributes internally. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 6-OCT-2006 (DSB): * Guard against annulling null pointers in subFrame. * 18-OCT-2006 (DSB): * Added SpecOrigin and AlignSpecOffset attributes. * 23-OCT-2006 (DSB): * Fix memory leak caused by addition of SpecOrigin and AlignSpecOffset * attributes. * 15-NOV-2006 (DSB): * Only write out SpecOrigin if it is not bad. * 8-JAN-2006 (DSB): * - SubFrame: Copy the SourceSystem and SourceStdOfRest attributes * to the System and StdOfRest attributes of the "align_frm" * SpecFrame before calling MakeSpecMapping. Previously, the * values assigned to SourceSystem and SourceStdOfRest were * ignored, and alignment was always performed in the templates System * and StdOfRest. * - MakeSpecMapping: Correct logic used to decide if steps 2 and 7 * can be cancelled. * - OriginSystem: Clear the AlignSpecOffset attributes before * finding the Mapping between the old and new Systems. * 16-JAN-2006 (DSB): * Fix bug in Dump that caused SrcVRF not to be written out. * 31-JAN-2007 (DSB): * Modified so that a SpecFrame can be used as a template to find a * SpecFrame contained within a CmpFrame. This involves changes in * Match and the removal of the local versions of SetMaxAxes and * SetMinAxes. * 8-AUG-2007 (DSB): * Changed Overlay to avoid the possibility of making permanent * changes to the supplied template Frame. * 3-SEP-2007 (DSB): * In SubFrame, since AlignSystem is extended by the SpecFrame class * it needs to be cleared before invoking the parent SubFrame * method in cases where the result Frame is not a SkyFrame. * 2-OCT-2007 (DSB): * In Overlay, clear AlignSystem as well as System before calling * the parent overlay method. * 4-SEP-2009 (DSB): * In MakeSpecMapping, in order to produce alignment that is not * affected by the epoch or reference position, make the alignment * frame adapt to the epoch and reference position of the target * and result Frames. * 14-SEP-2009 (DSB): * In MakeSpecMapping, extend the 4-SEP-2009 fix to cover other * attributes that define the available rest frames (e.g. * SourceVRF, SourceVel, ObsLat, ObsLon, ObsAlt). * 16-SEP-2009 (DSB): * In MakeSpecMapping, retain the original alignment frame attribute * values if we are restoring the integrity of a FrameSet. * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. *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 SpecFrame /* Define the first and last acceptable System values. */ #define FIRST_SYSTEM AST__FREQ #define LAST_SYSTEM AST__VREL /* Define the first and last acceptable StdOfRest values. */ #define FIRST_SOR AST__TPSOR #define LAST_SOR AST__SCSOR /* The supported spectral coordinate systems fall into two groups; "relative", and "absolute". The relative systems define each axis value with respect to the rest frequency, whereas the absolute systems have axis values which do not depend on the rest frequency. Define a macro which returns one if the specified system is absolute, and zero otherwise. */ #define ABS_SYSTEM(sys) \ ( ( sys == AST__ENERGY || \ sys == AST__WAVENUM || \ sys == AST__WAVELEN || \ sys == AST__AIRWAVE || \ sys == AST__FREQ ) ? 1 : 0 ) /* Define other numerical constants for use in this module. */ #define GETATTRIB_BUFF_LEN 50 #define GETLABEL_BUFF_LEN 200 #define GETSYMBOL_BUFF_LEN 20 #define GETTITLE_BUFF_LEN 200 /* 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 "unit.h" /* Units management facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "specmap.h" /* Spectral coordinate Mappings */ #include "frame.h" /* Parent Frame class */ #include "skyframe.h" /* Celestial coordinate frames */ #include "specframe.h" /* Interface definition for this class */ #include "mapping.h" /* Coordinate Mappings */ #include "cmpmap.h" /* Compound Mappings */ #include "unitmap.h" /* Unit Mappings */ #include "pal.h" /* SlaLib interface */ #include "shiftmap.h" /* Change of origin */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* 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 used or extended by this class. */ static int (* parent_getobjsize)( AstObject *, int * ); static AstSystemType (* parent_getalignsystem)( AstFrame *, int * ); static AstSystemType (* parent_getsystem)( AstFrame *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static const char *(* parent_getdomain)( AstFrame *, int * ); static const char *(* parent_getlabel)( AstFrame *, int, int * ); static const char *(* parent_getsymbol)( AstFrame *, int, int * ); static const char *(* parent_gettitle)( AstFrame *, int * ); static const char *(* parent_getunit)( AstFrame *, int, int * ); static int (* parent_match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int (* parent_subframe)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_setunit)( AstFrame *, int, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_overlay)( AstFrame *, const int *, AstFrame *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_setsystem)( AstFrame *, AstSystemType, int * ); static void (* parent_clearsystem)( AstFrame *, int * ); static void (* parent_clearunit)( AstFrame *, int, int * ); /* Define a variable to hold a SkyFrame which will be used for formatting and unformatting sky positions, etc. */ static AstSkyFrame *skyframe; /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->GetLabel_Buff[ 0 ] = 0; \ globals->GetSymbol_Buff[ 0 ] = 0; \ globals->GetTitle_Buff[ 0 ] = 0; \ /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SpecFrame) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SpecFrame,Class_Init) #define class_vtab astGLOBAL(SpecFrame,Class_Vtab) #define getattrib_buff astGLOBAL(SpecFrame,GetAttrib_Buff) #define getlabel_buff astGLOBAL(SpecFrame,GetLabel_Buff) #define getsymbol_buff astGLOBAL(SpecFrame,GetSymbol_Buff) #define gettitle_buff astGLOBAL(SpecFrame,GetTitle_Buff) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffer returned by GetAttrib. */ static char getattrib_buff[ 51 ]; /* Default GetLabel string buffer */ static char getlabel_buff[ 201 ]; /* Default GetSymbol buffer */ static char getsymbol_buff[ 21 ]; /* Default Title string buffer */ static char gettitle_buff[ 201 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSpecFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #endif /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstStdOfRestType StdOfRestCode( const char *, int * ); static int GetObjSize( AstObject *, int * ); static AstSystemType GetAlignSystem( AstFrame *, int * ); static AstSystemType SystemCode( AstFrame *, const char *, int * ); static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); static const char *DefUnit( AstSystemType, const char *, const char *, int * ); static const char *GetDomain( AstFrame *, 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 *SpecMapUnit( AstSystemType, const char *, const char *, int * ); static const char *StdOfRestString( AstStdOfRestType, int * ); static const char *SystemLabel( AstSystemType, int * ); static const char *SystemString( AstFrame *, AstSystemType, int * ); static double ConvertSourceVel( AstSpecFrame *, AstStdOfRestType, AstSystemType, int * ); static int EqualSor( AstSpecFrame *, AstSpecFrame *, int * ); static int GetActiveUnit( AstFrame *, int * ); static int MakeSpecMapping( AstSpecFrame *, AstSpecFrame *, AstSpecFrame *, int, AstMapping **, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SorConvert( AstSpecFrame *, AstSpecFrame *, AstSpecMap *, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int TestActiveUnit( 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 GetRefPos( AstSpecFrame *, AstSkyFrame *, double *, double *, int * ); static void Overlay( AstFrame *, const int *, AstFrame *, int * ); static void SetRefPos( AstSpecFrame *, AstSkyFrame *, double, double, int * ); static void SetUnit( AstFrame *, int, const char *, int * ); static void VerifyAttrs( AstSpecFrame *, const char *, const char *, const char *, int * ); static double ToUnits( AstSpecFrame *, const char *, double, const char *, int * ); static void OriginStdOfRest( AstSpecFrame *, AstStdOfRestType, const char *, int * ); static void OriginSystem( AstSpecFrame *, AstSystemType, const char *, int * ); static AstSystemType GetSystem( AstFrame *, int * ); static void SetSystem( AstFrame *, AstSystemType, int * ); static void ClearSystem( AstFrame *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static AstStdOfRestType GetAlignStdOfRest( AstSpecFrame *, int * ); static int TestAlignStdOfRest( AstSpecFrame *, int * ); static void ClearAlignStdOfRest( AstSpecFrame *, int * ); static void SetAlignStdOfRest( AstSpecFrame *, AstStdOfRestType, int * ); static AstStdOfRestType GetStdOfRest( AstSpecFrame *, int * ); static int TestStdOfRest( AstSpecFrame *, int * ); static void ClearStdOfRest( AstSpecFrame *, int * ); static void SetStdOfRest( AstSpecFrame *, AstStdOfRestType, int * ); static double GetRestFreq( AstSpecFrame *, int * ); static int TestRestFreq( AstSpecFrame *, int * ); static void ClearRestFreq( AstSpecFrame *, int * ); static void SetRestFreq( AstSpecFrame *, double, int * ); static double GetSourceVel( AstSpecFrame *, int * ); static int TestSourceVel( AstSpecFrame *, int * ); static void ClearSourceVel( AstSpecFrame *, int * ); static void SetSourceVel( AstSpecFrame *, double, int * ); static double GetRefRA( AstSpecFrame *, int * ); static int TestRefRA( AstSpecFrame *, int * ); static void ClearRefRA( AstSpecFrame *, int * ); static void SetRefRA( AstSpecFrame *, double, int * ); static double GetRefDec( AstSpecFrame *, int * ); static int TestRefDec( AstSpecFrame *, int * ); static void ClearRefDec( AstSpecFrame *, int * ); static void SetRefDec( AstSpecFrame *, double, int * ); static AstStdOfRestType GetSourceVRF( AstSpecFrame *, int * ); static int TestSourceVRF( AstSpecFrame *, int * ); static void ClearSourceVRF( AstSpecFrame *, int * ); static void SetSourceVRF( AstSpecFrame *, AstStdOfRestType, int * ); static AstSystemType GetSourceSys( AstSpecFrame *, int * ); static int TestSourceSys( AstSpecFrame *, int * ); static void ClearSourceSys( AstSpecFrame *, int * ); static void SetSourceSys( AstSpecFrame *, AstSystemType, int * ); static double GetSpecOrigin( AstSpecFrame *, int * ); static int TestSpecOrigin( AstSpecFrame *, int * ); static void ClearSpecOrigin( AstSpecFrame *, int * ); static void SetSpecOrigin( AstSpecFrame *, double, int * ); static double GetSpecOriginCur( AstSpecFrame *, int * ); static int GetAlignSpecOffset( AstSpecFrame *, int * ); static int TestAlignSpecOffset( AstSpecFrame *, int * ); static void SetAlignSpecOffset( AstSpecFrame *, int, int * ); static void ClearAlignSpecOffset( AstSpecFrame *, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SpecFrame 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 * SpecFrame, so that the default value will subsequently be used. * Parameters: * this * Pointer to the SpecFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ char *new_attrib; /* Pointer value to new attribute name */ int len; /* Length of attrib string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* First look for axis attributes defined by the Frame class. Since a SpecFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent ClearAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); (*parent_clearattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignStdOfRest. */ /* --------------- */ } else if ( !strcmp( attrib, "alignstdofrest" ) ) { astClearAlignStdOfRest( this ); /* GeoLat. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had GeoLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( !strcmp( attrib, "geolat" ) ) { astClearAttrib( this, "obslat" ); /* GeoLon. */ /* ------- */ } else if ( !strcmp( attrib, "geolon" ) ) { astClearAttrib( this, "obslon" ); /* RefDec. */ /* ---------- */ } else if ( !strcmp( attrib, "refdec" ) ) { astClearRefDec( this ); /* RefRA. */ /* --------- */ } else if ( !strcmp( attrib, "refra" ) ) { astClearRefRA( this ); /* RestFreq. */ /* --------- */ } else if ( !strcmp( attrib, "restfreq" ) ) { astClearRestFreq( this ); /* SourceVel. */ /* ---------- */ } else if ( !strcmp( attrib, "sourcevel" ) ) { astClearSourceVel( this ); /* SpecOrigin. */ /* ---------- */ } else if ( !strcmp( attrib, "specorigin" ) ) { astClearSpecOrigin( this ); /* AlignSpecOffset. */ /* ---------------- */ } else if ( !strcmp( attrib, "alignspecoffset" ) ) { astClearAlignSpecOffset( this ); /* SourceVRF */ /* --------- */ } else if ( !strcmp( attrib, "sourcevrf" ) ) { astClearSourceVRF( this ); /* SourceSys */ /* --------- */ } else if ( !strcmp( attrib, "sourcesys" ) ) { astClearSourceSys( this ); /* StdOfRest. */ /* ---------- */ } else if ( !strcmp( attrib, "stdofrest" ) ) { astClearStdOfRest( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearSystem( AstFrame *this_frame, int *status ) { /* * Name: * ClearSystem * Purpose: * Clear the System attribute for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void ClearSystem( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astClearSystem protected * method inherited from the Frame class). * Description: * This function clears the System attribute for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ AstSystemType newsys; /* System after clearing */ AstSystemType oldsys; /* System before clearing */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* Save the original system */ oldsys = astGetSystem( this_frame ); /* Use the parent ClearSystem method to clear the System value. */ (*parent_clearsystem)( this_frame, status ); /* Get the default System. */ newsys = astGetSystem( this_frame ); /* If the system has actually changed. */ if( newsys != oldsys ) { /* Changing the System value will in general require the Units to change as well. If the used has previously specified the units to be used with the new system, then re-instate them (they are stored in the "usedunits" array in the SpecFrame structure). Otherwise, clear the units so that the default units will eb used with the new System. */ if( (int) newsys < this->nuunits && this->usedunits && this->usedunits[ (int) newsys ] ) { astSetUnit( this, 0, this->usedunits[ (int) newsys ] ); } else { astClearUnit( this, 0 ); } /* Also, clear all attributes which have system-specific defaults. */ astClearLabel( this_frame, 0 ); astClearSymbol( this_frame, 0 ); astClearTitle( this_frame ); /* Modify the SpecOrigin value to use the new System */ OriginSystem( this, oldsys, "astClearSystem", status ); } } static void ClearStdOfRest( AstSpecFrame *this, int *status ) { /* *+ * Name: * astClearStdOfRest * Purpose: * Clear the StdOfRest attribute for a SpecFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * void astClearStdOfRest( AstSpecFrame *this ) * Class Membership: * SpecFrame virtual function * Description: * This function clears the StdOfRest attribute for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Modify the SpecOrigin value stored in the SpecFrame structure to refer to the default rest frame (heliocentric). */ OriginStdOfRest( this, AST__HLSOR, "astClearStdOfRest", status ); /* Store a bad value for the standard of rest in the SpecFrame structure. */ this->stdofrest = AST__BADSOR; } static void ClearUnit( AstFrame *this_frame, int axis, int *status ) { /* * Name: * ClearUnit * Purpose: * Clear the value of the Unit string for a SpecFrame's axis. * Type: * Private function. * Synopsis: * #include "specframe.h" * void ClearUnit( AstFrame *this_frame, int axis ) * Class Membership: * SpecFrame member function (over-rides the astClearUnit method inherited * from the Frame class). * Description: * This function clears the Unit string for a specified axis of a * SpecFrame. It also clears the UsedUnit item in the SpecFrame * structure corresponding to the current System. * Parameters: * this * Pointer to the SpecFrame. * axis * The number of the axis (zero-based). */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ int system; /* The SpecFrame's System value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astClearUnit" ); /* Clear the UsedUnit item for the current System, if current set. */ system = (int) astGetSystem( this ); if( system < this->nuunits && this->usedunits ) { this->usedunits[ system ] = astFree( this->usedunits[ system ] ); } /* Use the parent method to clear the Unit attribute of the axis. */ (*parent_clearunit)( this_frame, axis, status ); } static double ConvertSourceVel( AstSpecFrame *this, AstStdOfRestType newsor, AstSystemType newsys, int *status ) { /* * Name: * ConvertSourceVel * Purpose: * Convert the SourceVel value to a specified rest frame and spectral * system. * Type: * Private function. * Synopsis: * #include "specframe.h" * double ConvertSourceVel( AstSpecFrame *this, AstStdOfRestType newsor, * AstSystemType newsys, int *status ) * Class Membership: * SpecFrame member function * Description: * This function convert the SourceVel value to a specified rest frame * and spectral system, and returns the new value. * Parameters: * this * Pointer to the SpecFrame. * newsor * The rest frame in which the source velocity is required. * newsys * The spectral system (AST__VREL or AST__REDSHIFT) in which the * source velocity is required. * status * Pointer to the inherited status variable. * Returned Value: * The converted source velocity (m/s), or redshift. * Notes: * - This function returns zero if an error occurs. */ /* Local Variables: */ AstSpecFrame *from; /* Pointer to a source SpecFrame */ AstSpecFrame *to; /* Pointer to a destination SpecFrame */ AstSpecMap *specmap; /* Pointer to a SpecMap */ AstStdOfRestType sor; /* Standard of rest in which SourceVel is defined */ AstSystemType sys; /* Spectral system in which SourceVel is defined */ double ret; /* The returned value */ double rf; /* Rest frequency (Hz) */ double temp; /* Temporary storage */ /* Initialise */ ret = 0.0; /* Check the global error status. */ if ( !astOK ) return ret; /* Get the value of the SourceVel attribute. This will be a velocity in m/s (relativistic, radio or optical), or unitless redshift or beta factor, depending on the current value of SourceSys. */ ret = astGetSourceVel( this ); /* Check it can be used (depends on whether a value has been set and whether the UseDefs attribute is zero). */ VerifyAttrs( this, "convert source velocity to a new standard of rest", "SourceVel", "astMatch", status ); /* Get the rest frame and spectral system to which value refers. */ sor = astGetSourceVRF( this ); sys = astGetSourceSys( this ); /* If necessary, convert to the requested rest frame and spectral system. */ if( sor != newsor || sys != newsys ) { /* Verify that usable value is available for the RestFreq attribute. An error is reported if not. */ VerifyAttrs( this, "convert source velocity to a new standard of rest", "RestFreq", "astMatch", status ); /* Take two copies of the supplied SpecFrame and set their StdOfRest attributes to the required values. */ from = astCopy( this ); astSetStdOfRest( from, sor ); to = astCopy( this ); astSetStdOfRest( to, newsor ); /* Initialise a new SpecMap to describe the conversion. The new SpecMap initially represents a UnitMap. */ specmap = astSpecMap( 1, 0, "", status ); /* Add a conversion from the spectral system in which the SourceVEl value is stored, to relativistic velocity. */ if( sys == AST__VRADIO ) { astSpecAdd( specmap, "VRTOVL", NULL ); } else if( sys == AST__VOPTICAL ) { astSpecAdd( specmap, "VOTOVL", NULL ); } else if( sys == AST__REDSHIFT ) { astSpecAdd( specmap, "ZOTOVL", NULL ); } else if( sys == AST__BETA ) { astSpecAdd( specmap, "BTTOVL", NULL ); } /* Add a conversion from velocity to frequency since SorConvert converts frequencies. */ rf = astGetRestFreq( this ); astSpecAdd( specmap, "VLTOFR", &rf ); /* Now add a conversion from frequency in the SourveVRF standard of rest to frequency in the required rest frame. */ SorConvert( from, to, specmap, status ); /* Add a conversion from frequency back to velocity. Note, the value of the rest frequency does not affect the overall conversion. */ astSpecAdd( specmap, "FRTOVL", &rf ); /* Add a conversion from relativistic velocity to the required spectral system, if needed. */ if( newsys == AST__VRADIO ) { astSpecAdd( specmap, "VLTOVR", NULL ); } else if( newsys == AST__VOPTICAL ) { astSpecAdd( specmap, "VLTOVO", NULL ); } else if( newsys == AST__REDSHIFT ) { astSpecAdd( specmap, "VLTOZO", NULL ); } else if( newsys == AST__BETA ) { astSpecAdd( specmap, "VLTOBT", NULL ); } /* Use the SpecMap to convert the source velocity in the SourceVRF standard of rest and SourceSys spectral system to the required rest frame and spectral system. */ temp = ret; astTran1( specmap, 1, &temp, 1, &ret ); /* Free resources */ specmap = astAnnul( specmap ); to = astAnnul( to ); from = astAnnul( from ); } /* Return zero if an error has occurred. */ if( !astOK ) ret = 0.0; /* Return the answer. */ return ret; } static const char *DefUnit( AstSystemType system, const char *method, const char *class, int *status ){ /* * Name: * DefUnit * Purpose: * Return the default units for a spectral coordinate system type. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *DefUnit( AstSystemType system, const char *method, * const char *class, int *status ) * Class Membership: * SpecFrame member function. * Description: * This function returns a textual representation of the default * units associated with the specified spectral coordinate system. * Parameters: * system * The spectral coordinate system. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * As tring describing the default units. This string follows the * units syntax described in FITS WCS paper I "Representations of world * coordinates in FITS" (Greisen & Calabretta). * Notes: * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ const char *result; /* Value to return */ /* Initialize */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get an identifier for the default units. */ if( system == AST__FREQ ) { result = "GHz"; } else if( system == AST__ENERGY ) { result = "J"; } else if( system == AST__WAVENUM ) { result = "1/m"; } else if( system == AST__WAVELEN ) { result = "Angstrom"; } else if( system == AST__AIRWAVE ) { result = "Angstrom"; } else if( system == AST__VRADIO ) { result = "km/s"; } else if( system == AST__VOPTICAL ) { result = "km/s"; } else if( system == AST__REDSHIFT ) { result = ""; } else if( system == AST__BETA ) { result = ""; } else if( system == AST__VREL ) { result = "km/s"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "%s(%s): Corrupt %s contains illegal System " "identification code (%d).", status, method, class, class, (int) system ); } /* Return the result. */ return result; } static int EqualSor( AstSpecFrame *this, AstSpecFrame *that, int *status ) { /* * Name: * EqualSor * Purpose: * Do two SpecFrames use the same standard of rest? * Type: * Private function. * Synopsis: * #include "specframe.h" * int EqualSor( AstSpecFrame *this, AstSpecFrame *that, int *status ) * Class Membership: * SpecFrame member function * Description: * This function returns non-zero if the two supplied SpecFrames use * the same standard of rest. * Parameters: * this * Pointer to the first SpecFrame. * that * Pointer to the second SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the two SpecFrames use the same standard of rest. Zero * otherwise. */ /* Local Variables: */ AstStdOfRestType sor; /* Standard of rest */ int result; /* Value to return */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 1; /* Compare StdOfRest attributes. */ sor = astGetStdOfRest( this ); if( astGetStdOfRest( that ) != sor ) { result = 0; /* If the standards of rest are equal we need to check the the attributes which specify the precise rest frame. */ } else { /* The reference RA and Dec need to be equal */ if( !astEQUAL( astGetRefRA( this ), astGetRefRA( that ) ) || !astEQUAL( astGetRefDec( this ), astGetRefDec( that ) ) ) { result = 0; /* For source rest frame, the source velocities, rest frames and systems must be equal */ } else if( sor == AST__SCSOR ){ if( !astEQUAL( astGetSourceVel( this ), astGetSourceVel( that ) ) || astGetSourceVRF( this ) != astGetSourceVRF( that ) || astGetSourceSys( this ) != astGetSourceSys( that ) ) { result = 0; } /* For geocentric, barycentric and heliocentric rest frames, the epochs must be the same */ } else if( sor == AST__GESOR || sor == AST__BYSOR || sor == AST__HLSOR ){ if( !astEQUAL( astGetEpoch( this ), astGetEpoch( that ) ) ) result = 0; /* For topocentric rest frame, the epoch and position of the observer must be the same */ } else if( sor == AST__TPSOR ){ if( !astEQUAL( astGetEpoch( this ), astGetEpoch( that ) ) || !astEQUAL( astGetObsAlt( this ), astGetObsAlt( that ) ) || !astEQUAL( astGetObsLon( this ), astGetObsLon( that ) ) || !astEQUAL( astGetObsLat( this ), astGetObsLat( that ) ) ) result = 0; } else if( sor != AST__LKSOR && sor != AST__LDSOR && sor != AST__GLSOR && sor != AST__LGSOR && astOK ) { astError( AST__INTER, "SorEqual(SpecFrame): Function SorEqual " "does not yet support rest frame %d (AST internal " "programming error)", status, sor ); } } /* Return the result */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "specframe.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SpecFrame, * in bytes. * Parameters: * this * Pointer to the SpecFrame. * 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: */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ int result; /* Result value to return */ int i; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SpecFrame structure. */ this = (AstSpecFrame *) 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 ); if( this->usedunits ) { for( i = 0; i < this->nuunits; i++ ) { result += astTSizeOf( this->usedunits[ i ] ); } result += astTSizeOf( this->usedunits ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * GetActiveUnit * Purpose: * Obtain the value of the ActiveUnit flag for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * int GetActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetActiveUnit protected * method inherited from the Frame class). * Description: * This function returns the value of the ActiveUnit flag for a * SpecFrame, which is always 1. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * The value to use for the ActiveUnit flag (1). */ return 1; } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SpecFrame 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 SpecFrame, formatted as a character string. * Parameters: * this * Pointer to the SpecFrame. * attrib * Pointer to a null-terminated string containing the name of * the attribute whose value is required. This name should be in * lower case, with all white space removed. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a null-terminated string containing the attribute * value. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - The returned string pointer may point at memory allocated * within the SpecFrame, 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 SpecFrame. 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 */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ AstStdOfRestType sor; /* Standard of rest */ AstSystemType sys; /* Spectral system */ char *new_attrib; /* Pointer value to new attribute name */ const char *result; /* Pointer value to return */ double dval; /* Attribute value */ int ival; /* Attribute value */ int len; /* Length of attrib string */ /* 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 SpecFrame structure. */ this = (AstSpecFrame *) this_object; /* Create an FK5 J2000 SkyFrame which will be used for formatting and unformatting sky positions, etc. */ LOCK_MUTEX2 if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000", status ); astEndPM; } UNLOCK_MUTEX2 /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* First look for axis attributes defined by the Frame class. Since a SpecFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent GetAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); result = (*parent_getattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignStdOfRest. */ /* --------------- */ /* Obtain the AlignStdOfRest code and convert to a string. */ } else if ( !strcmp( attrib, "alignstdofrest" ) ) { sor = astGetAlignStdOfRest( this ); if ( astOK ) { result = StdOfRestString( sor, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid AlignStdOfRest " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) sor ); } } /* AlignSpecOffset */ /* --------------- */ } else if ( !strcmp( attrib, "alignspecoffset" ) ) { ival = astGetAlignSpecOffset( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* GeoLat. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had GeoLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( !strcmp( attrib, "geolat" ) ) { result = astGetAttrib( this, "obslat" ); /* GeoLon. */ /* ------- */ } else if ( !strcmp( attrib, "geolon" ) ) { result = astGetAttrib( this, "obslon" ); /* RefDec. */ /* ------- */ /* Convert to a string using the SkyFrame Format method. */ } else if ( !strcmp( attrib, "refdec" ) ) { dval = astGetRefDec( this ); if ( astOK ) { result = astFormat( skyframe, 1, dval ); } /* RefRA. */ /* ------ */ /* Convert to a string using the SkyFrame Format method. */ } else if ( !strcmp( attrib, "refra" ) ) { dval = astGetRefRA( this ); if ( astOK ) { result = astFormat( skyframe, 0, dval ); } /* RestFreq. */ /* --------- */ } else if ( !strcmp( attrib, "restfreq" ) ) { dval = astGetRestFreq( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval*1.0E-9 ); result = getattrib_buff; } /* SourceVel */ /* --------- */ } else if ( !strcmp( attrib, "sourcevel" ) ) { dval = astGetSourceVel( this ); if ( astOK ) { /* Convert from m/s to km/s if the SourceVel value is a velocity. . */ if( astGetSourceSys( this ) == AST__VREL || astGetSourceSys( this ) == AST__VRADIO || astGetSourceSys( this ) == AST__VOPTICAL ) dval *= 1.0E-3; /* Format */ (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* SpecOrigin. */ /* ----------- */ } else if ( !strcmp( attrib, "specorigin" ) ) { dval = GetSpecOriginCur( this, status ); if( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* SourceVRF */ /* ----------*/ } else if ( !strcmp( attrib, "sourcevrf" ) ) { sor = astGetSourceVRF( this ); if ( astOK ) { result = StdOfRestString( sor, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid SourceVRF " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) sor ); } } /* SourceSys */ /* ----------*/ } else if ( !strcmp( attrib, "sourcesys" ) ) { sys = astGetSourceSys( this ); if ( astOK ) { result = SystemString( (AstFrame *) this, sys, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid SourceSys " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) sys ); } } /* StdOfRest. */ /* ---------- */ /* Obtain the StdOfRest code and convert to a string. */ } else if ( !strcmp( attrib, "stdofrest" ) ) { sor = astGetStdOfRest( this ); if ( astOK ) { result = StdOfRestString( sor, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid StdOfRest " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) sor ); } } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static const char *GetDomain( AstFrame *this_frame, int *status ) { /* * Name: * GetDomain * Purpose: * Obtain a pointer to the Domain attribute string for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetDomain( AstFrame *this, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetDomain protected * method inherited from the Frame class). * Description: * This function returns a pointer to the Domain attribute string * for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a constant null-terminated string containing the * Domain value. * Notes: * - The returned pointer or the string it refers to may become * invalid following further invocation of this function or * modification of the SpecFrame. * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to SpecFrame 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 SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* If a Domain attribute string has been set, invoke the parent method to obtain a pointer to it. */ if ( astTestDomain( this ) ) { result = (*parent_getdomain)( this_frame, status ); /* Otherwise, provide a pointer to a suitable default string. */ } else { result = "SPECTRUM"; } /* Return the result. */ return result; } static const char *GetLabel( AstFrame *this, int axis, int *status ) { /* * Name: * GetLabel * Purpose: * Access the Label string for a SpecFrame axis. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetLabel( AstFrame *this, int axis, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetLabel method inherited * from the Frame class). * Description: * This function returns a pointer to the Label string for a specified axis * of a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstMapping *map; /* Mapping between units */ AstSystemType system; /* Code identifying type of spectral coordinates */ char *new_lab; /* Modified label string */ const char *result; /* Pointer to label string */ double orig; /* Spec origin */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetLabel" ); /* Check if a value has been set for the required axis label string. If so, invoke the parent astGetLabel method to obtain a pointer to it. */ if ( astTestLabel( this, axis ) ) { result = (*parent_getlabel)( this, axis, status ); /* Otherwise, identify the spectral coordinate system described by the SpecFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default label string. */ if ( astOK ) { result = strcpy( getlabel_buff, SystemLabel( system, status ) ); getlabel_buff[ 0 ] = toupper( getlabel_buff[ 0 ] ); /* If a non-zero SpecOrigin has been specified, include the offset now. */ orig = GetSpecOriginCur( (AstSpecFrame *) this, status ); if( orig != 0.0 ) { sprintf( getlabel_buff + strlen( getlabel_buff ), " offset from %s", astFormat( this, 0, orig ) ); } /* Modify this default to take account of the current value of the Unit attribute, if set. */ if( astTestUnit( this, axis ) ) { /* Find a Mapping from the default Units for the current System, to the units indicated by the Unit attribute. This Mapping is used to modify the existing default label appropriately. For instance, if the default units is "Hz" and the actual units is "log(Hz)", then the default label of "Frequency" is changed to "log( frequency )". */ map = astUnitMapper( DefUnit( system, "astGetLabel", astGetClass( this ), status ), astGetUnit( this, axis ), result, &new_lab ); if( new_lab ) { result = strcpy( getlabel_buff, new_lab ); new_lab = astFree( new_lab ); } /* Annul the unused Mapping. */ if( map ) map = astAnnul( map ); } } } /* Return the result. */ return result; } static void GetRefPos( AstSpecFrame *this, AstSkyFrame *frm, double *lon, double *lat, int *status ){ /* *++ * Name: c astGetRefPos f AST_GETREFPOS * Purpose: * Return the reference position in a specified celestial coordinate system. * Type: * Public virtual function. * Synopsis: c #include "specframe.h" c void astGetRefPos( AstSpecFrame *this, AstSkyFrame *frm, double *lon, c double *lat ) f CALL AST_GETREFPOS( THIS, FRM, LON, LAT, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * returns the reference position (specified by attributes RefRA and * RefDec) converted to the celestial coordinate system represented by * a supplied SkyFrame. The celestial longitude and latitude values * are returned in radians. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the SpecFrame. c frm f FRM = INTEGER (Given) * Pointer to the SkyFrame which defines the required celestial * coordinate system. c If NULL f If AST__NULL * is supplied, then the longitude and latitude values are returned * as FK5 J2000 RA and Dec values. c lon f LON = DOUBLE PRECISION (Returned) c A pointer to a double in which to store the f The * longitude of the reference point, in the coordinate system * represented by the supplied SkyFrame (radians). c lat f LAT = DOUBLE PRECISION (Returned) c A pointer to a double in which to store the f The * latitude of the reference point, in the coordinate system * represented by the supplied SkyFrame (radians). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Values of AST__BAD will be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- */ /* Local Variables: */ AstFrameSet *fs; /* Conversion FrameSet */ AstFrame *fb; /* Base Frame */ AstFrame *fc; /* Current Frame */ double xin[ 1 ]; /* Axis 1 values */ double yin[ 1 ]; /* Axis 2 values */ double xout[ 1 ]; /* Axis 1 values */ double yout[ 1 ]; /* Axis 2 values */ /* Initialise. */ if( lon ) *lon = AST__BAD; if( lat ) *lat = AST__BAD; /* Check the global error status. */ if ( !astOK ) return; /* If no SkyFrame was supplied, just return the stored RefRA and RefDec values. */ if( !frm ) { if( lon ) *lon = astGetRefRA( this ); if( lat ) *lat = astGetRefDec( this ); /* Otherwise, convert the stored values to the requested system. */ } else { /* Create an FK5 J2000 SkyFrame which will be used for formatting and unformatting sky positions, etc. */ LOCK_MUTEX2 if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000", status ); astEndPM; } UNLOCK_MUTEX2 /* Find the Mapping from the SkyFrame which describes the internal format in which the RefRA and RefDec attribute values are stored, to the supplied Frame. */ fs = astFindFrame( skyframe, frm, "" ); /* If alignment was possible, use the Mapping to transform the internal RefRA and RefDec values. Check for axis permutatuion. */ if( fs ) { fb = astGetFrame( fs, AST__BASE ); if( astGetLonAxis( fb ) == 0 ) { xin[ 0 ] = astGetRefRA( this ); yin[ 0 ] = astGetRefDec( this ); } else { yin[ 0 ] = astGetRefRA( this ); xin[ 0 ] = astGetRefDec( this ); } astTran2( fs, 1, xin, yin, 1, xout, yout ); /* Store the returned values, checking to see if the axes of the supplied SkyFrame have been permuted. */ fc = astGetFrame( fs, AST__CURRENT ); if( astGetLonAxis( fc ) == 0 ) { if( lon ) *lon = xout[ 0 ]; if( lat ) *lat = yout[ 0 ]; } else { if( lon ) *lon = yout[ 0 ]; if( lat ) *lat = xout[ 0 ]; } /* Annul object references. */ fc = astAnnul( fc ); fb = astAnnul( fb ); fs = astAnnul( fs ); } } } static const char *GetSymbol( AstFrame *this, int axis, int *status ) { /* * Name: * GetSymbol * Purpose: * Obtain a pointer to the Symbol string for a SpecFrame axis. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetSymbol( AstFrame *this, int axis, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetSymbol method inherited * from the Frame class). * Description: * This function returns a pointer to the Symbol string for a specified axis * of a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstMapping *map; /* Mapping between units */ AstSystemType system; /* Code identifying type of sky coordinates */ char *new_sym; /* Modified symbol string */ const char *result; /* Pointer to symbol string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetSymbol" ); /* Check if a value has been set for the required axis symbol string. If so, invoke the parent astGetSymbol method to obtain a pointer to it. */ if ( astTestSymbol( this, axis ) ) { result = (*parent_getsymbol)( this, axis, status ); /* Otherwise, identify the sky coordinate system described by the SpecFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default Symbol string. */ if ( astOK ) { if( system == AST__FREQ ) { result = "FREQ"; } else if( system == AST__ENERGY ) { result = "ENER"; } else if( system == AST__WAVENUM ) { result = "WAVN"; } else if( system == AST__WAVELEN ) { result = "WAVE"; } else if( system == AST__AIRWAVE ) { result = "AWAV"; } else if( system == AST__VRADIO ) { result = "VRAD"; } else if( system == AST__VOPTICAL ) { result = "VOPT"; } else if( system == AST__REDSHIFT ) { result = "ZOPT"; } else if( system == AST__BETA ) { result = "BETA"; } else if( system == AST__VREL ) { result = "VELO"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "astGetSymbol(%s): Corrupt %s contains " "invalid System identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } /* Modify this default to take account of the current value of the Unit attribute, if set. */ if( astTestUnit( this, axis ) ) { /* Find a Mapping from the default Units for the current System, to the units indicated by the Unit attribute. This Mapping is used to modify the existing default symbol appropriately. For instance, if the default units is "Hz" and the actual units is "log(Hz)", then the default symbol of "nu" is changed to "log( nu )". */ map = astUnitMapper( DefUnit( system, "astGetSymbol", astGetClass( this ), status ), astGetUnit( this, axis ), result, &new_sym ); if( new_sym ) { result = strcpy( getsymbol_buff, new_sym ); new_sym = astFree( new_sym ); } /* Annul the unused Mapping. */ if( map ) map = astAnnul( map ); } } } /* Return the result. */ return result; } static AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetAlignSystem * Purpose: * Obtain the AlignSystem attribute for a SpecFrame. * Type: * Private function. * Synopsis: * #include "Specframe.h" * AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetAlignSystem protected * method inherited from the Frame class). * Description: * This function returns the AlignSystem attribute for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * The AlignSystem value. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* If a AlignSystem attribute has been set, invoke the parent method to obtain it. */ if ( astTestAlignSystem( this ) ) { result = (*parent_getalignsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__WAVELEN; } /* Return the result. */ return result; } static AstSystemType GetSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetSystem * Purpose: * Obtain the System attribute for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * AstSystemType GetSystem( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetSystem protected * method inherited from the Frame class). * Description: * This function returns the System attribute for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * The System value. * Notes: * - AST__BADSYSTEM is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* If a System attribute has been set, invoke the parent method to obtain it. */ if ( astTestSystem( this ) ) { result = (*parent_getsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__WAVELEN; } /* Return the result. */ return result; } static const char *GetTitle( AstFrame *this_frame, int *status ) { /* * Name: * GetTitle * Purpose: * Obtain a pointer to the Title string for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetTitle( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astGetTitle method inherited * from the Frame class). * Description: * This function returns a pointer to the Title string for a SpecFrame. * A pointer to a suitable default string is returned if no Title value has * previously been set. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null-terminated character string containing the requested * information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ AstStdOfRestType sor; /* Code identifying standard of rest */ AstSystemType system; /* Code identifying type of coordinates */ const char *sor_string; /* Pointer to SOR description */ const char *result; /* Pointer to result string */ double rf; /* Rest frequency */ int nc; /* No. of characters added */ int pos; /* Buffer position to enter text */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_frame); /* Initialise. */ result = NULL; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* See if a Title string has been set. If so, use the parent astGetTitle method to obtain a pointer to it. */ if ( astTestTitle( this ) ) { result = (*parent_gettitle)( this_frame, status ); /* Otherwise, we will generate a default Title string. Obtain the values of the SpecFrame's attributes that determine what this string will be. */ } else { system = astGetSystem( this ); sor = astGetStdOfRest( this ); sor_string = StdOfRestString( sor, status ); rf = astGetRestFreq( this ); /* Classify the coordinate system type and create an appropriate Title string. (Note that when invoking the astFmtDecimalYr function we must use a separate sprintf on each occasion so as not to over-write its internal buffer before the result string has been used.) */ if ( astOK ) { result = gettitle_buff; /* Begin with the system's default label. */ pos = sprintf( gettitle_buff, "%s", SystemLabel( system, status ) ); gettitle_buff[ 0 ] = toupper( gettitle_buff[ 0 ] ); /* Append the standard of rest in parentheses, if set. */ if( astTestStdOfRest( this ) ) { nc = sprintf( gettitle_buff+pos, " (%s)", sor_string ); pos += nc; } /* Append the rest frequency if relevant. */ if( !ABS_SYSTEM(system) && ( astTestRestFreq( this ) || astGetUseDefs( this ) ) ) { pos += sprintf( gettitle_buff+pos, ", rest frequency = %g GHz", rf*1.0E-9 ); } } } /* If an error occurred, clear the returned pointer value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static double GetSpecOriginCur( AstSpecFrame *this, int *status ) { /* * Name: * GetSpecOriginCur * Purpose: * Obtain the SpecOrigin attribute for a SpecFrame in current units. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double GetSpecOriginCur( AstSpecFrame *this, int *status ) * Class Membership: * SpecFrame virtual function * Description: * This function returns the SpecOrigin attribute for a SpecFrame, in * the current units of the SpecFrame. The protected astGetSpecOrigin * method can be used to obtain the time origin in the default units of * the SpecFrame's System. * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * The SpecOrigin value, in the units, system and rest frame specified * by the current values of the Unit, System and StdOfRest attributes * within "this". * Notes: * - AST__BAD is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstMapping *map; const char *cur; const char *def; double result; double defval; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get the value in the default units */ result = astGetSpecOrigin( this ); /* If SpecOrigin is non-zero and non-BAD we convert it to the current units.*/ if( result != 0.0 && result != AST__BAD ) { /* Get the default units for the SpecFrame's System. */ def = DefUnit( astGetSystem( this ), "astGetSpecOrigin", "SpecFrame", status ); /* Get the current units from the SpecFrame. */ cur = astGetUnit( this, 0 ); /* If the units differ, get a Mapping from default to current units. */ if( cur && def ){ if( strcmp( cur, def ) ) { map = astUnitMapper( def, cur, NULL, NULL ); /* Report an error if the units are incompatible. */ if( !map ) { astError( AST__BADUN, "%s(%s): The current units (%s) are not suitable " "for a SpecFrame.", status, "astGetSpecOrigin", astGetClass( this ), cur ); /* Otherwise, transform the stored origin value.*/ } else { defval = result; astTran1( map, 1, &defval, 1, &result ); map = astAnnul( map ); } } } } /* Return the result. */ return result; } static const char *GetUnit( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetUnit * Purpose: * Obtain a pointer to the Unit string for a SpecFrame's axis. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *GetUnit( AstFrame *this_frame, int axis ) * Class Membership: * SpecFrame member function (over-rides the astGetUnit method inherited * from the Frame class). * Description: * This function returns a pointer to the Unit string for a specified axis * of a SpecFrame. If the Unit attribute has not been set for the axis, a * pointer to a suitable default string is returned instead. * Parameters: * this * Pointer to the SpecFrame. * axis * The number of the axis (zero-based) for which information is required. * Returned Value: * A pointer to a null-terminated string containing the Unit value. * 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: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ AstSystemType system; /* The SpecFrame's System value */ const char *result; /* Pointer value to return */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetUnit" ); /* If a value has been set for the Unit attribute, use the parent GetUnit method to return a pointer to the required Unit string. */ if( astTestUnit( this, axis ) ){ result = (*parent_getunit)( this_frame, axis, status ); /* Otherwise, identify the spectral coordinate system described by the SpecFrame. */ } else { system = astGetSystem( this ); /* Return a string describing the default units. */ result = DefUnit( system, "astGetUnit", astGetClass( this ), status ); } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } void astInitSpecFrameVtab_( AstSpecFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSpecFrameVtab * Purpose: * Initialise a virtual function table for a SpecFrame. * Type: * Protected function. * Synopsis: * #include "specframe.h" * void astInitSpecFrameVtab( AstSpecFrameVtab *vtab, const char *name ) * Class Membership: * SpecFrame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SpecFrame 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 */ 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 astIsASpecFrame) 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->GetRefPos = GetRefPos; vtab->SetRefPos = SetRefPos; vtab->ClearAlignStdOfRest = ClearAlignStdOfRest; vtab->TestAlignStdOfRest = TestAlignStdOfRest; vtab->GetAlignStdOfRest = GetAlignStdOfRest; vtab->SetAlignStdOfRest = SetAlignStdOfRest; vtab->ClearSourceVRF = ClearSourceVRF; vtab->TestSourceVRF = TestSourceVRF; vtab->GetSourceVRF = GetSourceVRF; vtab->SetSourceVRF = SetSourceVRF; vtab->ClearSourceSys = ClearSourceSys; vtab->TestSourceSys = TestSourceSys; vtab->GetSourceSys = GetSourceSys; vtab->SetSourceSys = SetSourceSys; vtab->ClearRefDec = ClearRefDec; vtab->TestRefDec = TestRefDec; vtab->GetRefDec = GetRefDec; vtab->SetRefDec = SetRefDec; vtab->ClearRefRA = ClearRefRA; vtab->TestRefRA = TestRefRA; vtab->GetRefRA = GetRefRA; vtab->SetRefRA = SetRefRA; vtab->ClearRestFreq = ClearRestFreq; vtab->TestRestFreq = TestRestFreq; vtab->GetRestFreq = GetRestFreq; vtab->SetRestFreq = SetRestFreq; vtab->ClearStdOfRest = ClearStdOfRest; vtab->TestStdOfRest = TestStdOfRest; vtab->GetStdOfRest = GetStdOfRest; vtab->SetStdOfRest = SetStdOfRest; vtab->ClearSourceVel = ClearSourceVel; vtab->TestSourceVel = TestSourceVel; vtab->GetSourceVel = GetSourceVel; vtab->SetSourceVel = SetSourceVel; vtab->ClearSpecOrigin = ClearSpecOrigin; vtab->TestSpecOrigin = TestSpecOrigin; vtab->GetSpecOrigin = GetSpecOrigin; vtab->SetSpecOrigin = SetSpecOrigin; vtab->TestAlignSpecOffset = TestAlignSpecOffset; vtab->SetAlignSpecOffset = SetAlignSpecOffset; vtab->GetAlignSpecOffset = GetAlignSpecOffset; vtab->ClearAlignSpecOffset = ClearAlignSpecOffset; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; frame = (AstFrameVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_getdomain = frame->GetDomain; frame->GetDomain = GetDomain; parent_getsystem = frame->GetSystem; frame->GetSystem = GetSystem; parent_setsystem = frame->SetSystem; frame->SetSystem = SetSystem; parent_clearsystem = frame->ClearSystem; frame->ClearSystem = ClearSystem; parent_getalignsystem = frame->GetAlignSystem; frame->GetAlignSystem = GetAlignSystem; parent_getlabel = frame->GetLabel; frame->GetLabel = GetLabel; parent_getsymbol = frame->GetSymbol; frame->GetSymbol = GetSymbol; parent_gettitle = frame->GetTitle; frame->GetTitle = GetTitle; parent_clearunit = frame->ClearUnit; frame->ClearUnit = ClearUnit; parent_getunit = frame->GetUnit; frame->GetUnit = GetUnit; parent_setunit = frame->SetUnit; frame->SetUnit = SetUnit; parent_match = frame->Match; frame->Match = Match; parent_overlay = frame->Overlay; frame->Overlay = Overlay; parent_subframe = frame->SubFrame; frame->SubFrame = SubFrame; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ frame->GetActiveUnit = GetActiveUnit; frame->TestActiveUnit = TestActiveUnit; frame->ValidateSystem = ValidateSystem; frame->SystemString = SystemString; frame->SystemCode = SystemCode; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "SpecFrame", "Description of spectral coordinate system" ); /* If we have just initialised the vtab for the current class, indicate that the vtab is now initialised, and store a pointer to the class identifier in the base "object" level of the vtab. */ if( vtab == &class_vtab ) { class_init = 1; astSetVtabClassIdentifier( vtab, &(vtab->id) ); } } static int MakeSpecMapping( AstSpecFrame *target, AstSpecFrame *result, AstSpecFrame *align_frm, int report, AstMapping **map, int *status ) { /* * Name: * MakeSpecMapping * Purpose: * Generate a Mapping between two SpecFrames. * Type: * Private function. * Synopsis: * #include "specframe.h" * int MakeSpecMapping( AstSpecFrame *target, AstSpecFrame *result, * AstSpecFrame *align_frm, int report, * AstMapping **map, int *status ) { * Class Membership: * SpecFrame member function. * Description: * This function takes two SpecFrames and generates a Mapping that * converts between them, taking account of differences in their * coordinate systems, rest frequency, standard of rest, etc. * * In order to cut down the number of transformations to be considered, * the scheme works by first converting from the target frame to an * "alignment" Frame, using the attributes of the target to define the * transformation. A transformation is then found from the alignment * frame to the required result Frame, using the attributes of the * result to define the transformation. The alignment Frame is * described by the AlignSystem and AlignStdOfRest attributes of the * "align_frm" SpecFrame. * * Thus, different forms of alignment can be obtained by suitable * choice of the attributes of "align_frm". For instance, to compare the * radio velocity dispersion of two lines at different rest frequencies, * you would set "system=radio velocity" and (probably) "stdofrest=local * group" in "align_frm". On the other hand if you wanted to re-calibrate * an existing radio velocity Frame within a FrameSet to use a different * rest frequency, you would make the SpecFrame the current Frame and then * set the rest frequency attribute for the FrameSet. The "integrity * checking" system in the FrameSet class would then get the Mapping * between the original and the modified SpecFrames. In this case, the * "alignment system" needs to be "frequency" since you want the original * and modified SpecFrames to be aligned in frequency, not radio velocity. * Parameters: * target * Pointer to the first SpecFrame. * result * Pointer to the second SpecFrame. * align_frm * A SpecFrame defining the system and standard of rest in which to * align the target and result SpecFrames. * report * Should errors be reported if no match is possible? These reports * will describe why no match was possible. * map * Pointer to a location which is to receive a pointer to the * returned Mapping. The forward transformation of this Mapping * will convert from "target" coordinates to "result" * coordinates, and the inverse transformation will convert in * the opposite direction (all coordinate values in radians). * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Mapping could be generated, or zero if the two * SpecFrames are sufficiently un-related that no meaningful Mapping * can be produced (albeit an "unmeaningful" Mapping will be returned * in this case, which will need to be annulled). * Notes: * A value of zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Constants: */ #define MAX_ARGS 1 /* Max arguments for an SpecMap conversion */ /* Local Variables: */ AstMapping *map1; /* Intermediate Mapping */ AstMapping *map2; /* Intermediate Mapping */ AstMapping *umap1; /* First Units Mapping */ AstMapping *umap2; /* Second Units Mapping */ AstSpecMap *specmap; /* Pointer to SpecMap */ AstShiftMap *sm; /* ShiftMap pointer */ AstSpecFrame *align_target; /* Alignment Frame with target properties */ AstSpecFrame *align_result; /* Alignment Frame with result properties */ AstSystemType serr; /* Erroneous system */ AstSystemType align_system; /* Code to identify alignment system */ AstSystemType target_system; /* Code to identify target system */ AstSystemType result_system; /* Code to identify result system */ const char *uerr; /* Erroneous units */ const char *ures; /* Results units */ const char *utarg; /* Target units */ const char *vmess; /* Text for use in error messages */ double args[ MAX_ARGS ]; /* Conversion argument array */ double target_rf; /* Target rest frequency (Hz) */ double result_rf; /* Result rest frequency (Hz) */ double target_origin; /* Target origin */ double result_origin; /* Result origin */ int match; /* Mapping can be generated? */ int step2; /* Perform the 2nd step in the Mapping? */ int step3; /* Perform the 3rd step in the Mapping? */ int step4; /* Perform the 4th step in the Mapping? */ int step5; /* Perform the 5th step in the Mapping? */ int step6; /* Perform the 6th step in the Mapping? */ int step7; /* Perform the 7th step in the Mapping? */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise the returned values. */ match = 1; *map = NULL; /* Create an initial (null) SpecMap. This is a 1D Mapping which converts spectral axis values between different systems and standard of rest. The axis units used by the SpecMap class match the default units used by this class. Any discrepancy between units is taken into account at the end of this function, once the total SpecMap has been created. */ specmap = astSpecMap( 1, 0, "", status ); /* Define local macros as shorthand for adding spectral coordinate conversions to this SpecMap. Each macro simply stores details of the additional arguments in the "args" array and then calls astSpecAdd. The macros differ in the number of additional argument values. */ #define TRANSFORM_0(cvt) \ astSpecAdd( specmap, cvt, NULL ); #define TRANSFORM_1(cvt,arg0) \ args[ 0 ] = arg0; \ astSpecAdd( specmap, cvt, args ); /* Get all the necessary attributes from the result, target and alignment Frames. */ target_rf = astGetRestFreq( target ); result_rf = astGetRestFreq( result ); target_system = astGetSystem( target ); result_system = astGetSystem( result ); align_system = astGetSystem( align_frm ); /* Define text for error messages.*/ vmess = "convert between spectral systems"; /* Verify that values for the standard of rest have been set if required (i.e if the UseDefs attribute of either SpecFrame is false). */ VerifyAttrs( result, vmess, "StdOfRest", "astMatch", status ); VerifyAttrs( target, vmess, "StdOfRest", "astMatch", status ); /* There are two different strategies for alignment. I'll use the Source rest frame as an example, although the same argument applies to other rest frames. In the first strategy, all "Source" rest frames are considered equal. That is, if two SpecFrames respresent (for example) frequencies in the source frame, then the SpecFrames are aligned using a UnitMap even if the details of the two source rest frames differ. This is usually what users want to see when (for instance) aligning plots of two spectra which both represent source frequencies but where the source frames details differ. In the second strategy, "Source" rest frames are aligned using a SpecMap that takes into account any differences in the properties of the source rest frames. This is what should happen when changes are made to the properties of a SpecFrame within a FrameSet. For instance, if the user changes the SourceVel attribute of the current Frame (assumed here to be a SpecFrame) in a FrameSet, then the process of restoring the integrity of the FrameSet (see frameset.c for details of integrity restoration) should cause the base->current Mapping in the FrameSet to be modified to reflect the new SourceVel value. So if the current call to this function is part of the process of restoring a FrameSet's integrity following changes to the FrameSet's current Frame, then we want to retain the properties of the supplied alignment Frame. So we use clones of the supplied alignment Frame. */ if( astGetFrameFlags( target ) & AST__INTFLAG ) { align_target = astClone( align_frm ); align_result = astClone( align_frm ); /* Buf if we are not restoring the integrity of a FrameSet, we want to ignore any differences in the properties that define the available rest frames. So create copies of the alignment Frame in which the properies defining the available rest frames are the same as in the target and result Frames. */ } else { align_target = astCopy( align_frm ); astSetEpoch( align_target, astGetEpoch( target ) ); astSetRefRA( align_target, astGetRefRA( target ) ); astSetRefDec( align_target, astGetRefDec( target ) ); astSetSourceVRF( align_target, astGetSourceVRF( target ) ); astSetSourceVel( align_target, astGetSourceVel( target ) ); astSetObsLat( align_target, astGetObsLat( target ) ); astSetObsLon( align_target, astGetObsLon( target ) ); astSetObsAlt( align_target, astGetObsAlt( target ) ); align_result = astCopy( align_frm ); astSetEpoch( align_result, astGetEpoch( result ) ); astSetRefRA( align_result, astGetRefRA( result ) ); astSetRefDec( align_result, astGetRefDec( result ) ); astSetSourceVRF( align_result, astGetSourceVRF( result ) ); astSetSourceVel( align_result, astGetSourceVel( result ) ); astSetObsLat( align_result, astGetObsLat( result ) ); astSetObsLon( align_result, astGetObsLon( result ) ); astSetObsAlt( align_result, astGetObsAlt( result ) ); } /* The supported spectral coordinate systems fall into two groups; "relative", and "absolute". The relative systems define each axis value with respect to the rest frequency, whereas the absolute systems have axis values which do not depend on the rest frequency. In order to convert an axis value from a system in one group to a system in the other group, the rest frequency must be known. However, the rest frequency is not necessary in order to convert axis values between two systems belonging to the same group. Determine if the alignment system is absolute or relative. If absolute, we ignore the system of the supplied "align_frm" and align in frequency, since aligning in any absolute system will automatically ensure that all the other absolute systems are aligned. Similarly, aligning in any relative system will automatically ensure that all the other relative systems are aligned. Doing this cuts down the complexity of the conversion process since we do not need to check every possible alignment system. */ align_system = ( ABS_SYSTEM( align_system ) ) ? AST__FREQ : AST__VREL; /* The total Mapping is made up of the following steps in series: 0) Convert from an offset value to an absolute value (if SpecOrigin set) 1) Convert target units to default units for the targets system 2) Convert from target system in target SOR to frequency in target SOR 3) Convert from freq in target SOR to freq in alignment SOR 4) Convert from freq in alignment SOR to alignment system in alignment SOR 5) Convert from alignment system in alignment SOR to freq in alignment SOR 6) Convert from freq in alignment SOR to freq in result SOR 7) Convert from freq in result SOR to result system in result SOR 8) Convert default units for the result system to results unit 9) Convert from an absolute value to an offset value (if SpecOrigin set) Steps 1,2,3,4 are performed using the attributes of the target (rest frequency, reference farem, etc), whilst steps 5,6,7,8 are performed using the attributes of the target (rest frequency, reference frame, etc). It is necessary to go from target system to alignment system via frequency because SOR conversion can only be performed in the frequency domain. Some of these steps may not be necessary. Initially assume all steps are necessary (we leave steps 0, 1, 8 and 9 out of this process and implement them once all other steps have been done). */ step2 = 1; step3 = 1; step4 = 1; step5 = 1; step6 = 1; step7 = 1; /* Step 2 is not necessary if the target system is frequency. */ if( target_system == AST__FREQ ) step2 = 0; /* Step 3 is not necessary if the alignment SOR is the same as the target SOR. */ if( EqualSor( target, align_target, status ) ) step3 = 0; /* Step 6 is not necessary if the alignment SOR is the same as the result SOR. */ if( EqualSor( result, align_result, status ) ) step6 = 0; /* Step 7 is not necessary if the result system is frequency. */ if( result_system == AST__FREQ ) step7 = 0; /* Steps 4 and 5 are not necessary if the alignment system is frequency, or if the target and result rest frequencies are equal. */ if( align_system == AST__FREQ || result_rf == target_rf ) step4 = step5 = 0; /* Steps 3 and 6 are not necessary if steps 4 and 5 are not necessary, and the target sor equals the result sor. */ if( !step4 && !step5 && EqualSor( target, result, status ) ) step3 = step6 = 0; /* Steps 2 and 7 are not necessary if steps 3, 4, 5 and 6 are not necessary, and the target sor equals the result sor, and the target and results systems are equal (if the systems are relative they must also have equal rest frequencies). */ if( !step3 && !step4 && !step5 && !step6 && EqualSor( target, result, status ) && target_system == result_system ) { if( !ABS_SYSTEM( target_system ) && result_rf == target_rf ) step2 = step7 = 0; } /* Now we know which steps are needed, let's do them (we delay unit conversion to the end)... */ /* Step 2: target system in target rest frame to frequency in target rest frame. */ if( step2 ) { if( target_system != AST__FREQ ) { /* If the target system is absolute, we can convert directly to frequency. */ if ( target_system == AST__ENERGY ) { TRANSFORM_0( "ENTOFR" ) } else if ( target_system == AST__WAVENUM ) { TRANSFORM_0( "WNTOFR" ) } else if ( target_system == AST__WAVELEN ) { TRANSFORM_0( "WVTOFR" ) } else if ( target_system == AST__AIRWAVE ) { TRANSFORM_0( "AWTOFR" ) /* If the target target_system is relative, we first need to convert to apparent radial velocity, and then to frequency using the rest frequency. */ } else { if ( target_system == AST__VRADIO ) { TRANSFORM_0( "VRTOVL" ) } else if ( target_system == AST__VOPTICAL ) { TRANSFORM_0( "VOTOVL" ) } else if ( target_system == AST__REDSHIFT ) { TRANSFORM_0( "ZOTOVL" ) } else if ( target_system == AST__BETA ) { TRANSFORM_0( "BTTOVL" ) } VerifyAttrs( target, vmess, "RestFreq", "astMatch", status ); TRANSFORM_1( "VLTOFR", target_rf ) } } } /* Step 3: frequency in target rest frame to frequency in alignment rest frame. */ if( step3 ) match = SorConvert( target, align_target, specmap, status ); /* Step 4: frequency in alignment rest frame to alignment system in alignment rest frame. The alignment will be either relativistic velocity or frequency. */ if( step4 ) { if( align_system == AST__VREL ) { VerifyAttrs( target, vmess, "RestFreq", "astMatch", status ); TRANSFORM_1( "FRTOVL", target_rf ) } } /* Step 5: Alignment system in alignment rest frame to frequency in alignment rest frame (from now on use the attributes of the result SpecFrame to define the conversion parameters). */ if( step5 ) { if( align_system == AST__VREL ) { VerifyAttrs( result, vmess, "RestFreq", "astMatch", status ); TRANSFORM_1( "VLTOFR", result_rf ) } } /* Step 6: frequency in alignment rest frame to frequency in result rest frame. */ if( step6 ) match = SorConvert( align_result, result, specmap, status ); /* Step 7: frequency in result rest frame to result system in result rest frame. */ if( step7 ) { if( result_system != AST__FREQ ) { /* If the results system is absolute, we can convert directly. */ if ( result_system == AST__ENERGY ) { TRANSFORM_0( "FRTOEN" ) } else if ( result_system == AST__WAVENUM ) { TRANSFORM_0( "FRTOWN" ) } else if ( result_system == AST__WAVELEN ) { TRANSFORM_0( "FRTOWV" ) } else if ( result_system == AST__AIRWAVE ) { TRANSFORM_0( "FRTOAW" ) /* If the result system is relative, we first need to convert to apparent radial velocity from frequency using the rest frequency. Report an error if the rest frequency is undefined. */ } else { VerifyAttrs( result, vmess, "RestFreq", "astMatch", status ); TRANSFORM_1( "FRTOVL", result_rf ) /* Now convert from apparent radial velocity to the required result system. */ if ( result_system == AST__VRADIO ) { TRANSFORM_0( "VLTOVR" ) } else if ( result_system == AST__VOPTICAL ) { TRANSFORM_0( "VLTOVO" ) } else if ( result_system == AST__REDSHIFT ) { TRANSFORM_0( "VLTOZO" ) } else if ( result_system == AST__BETA ) { TRANSFORM_0( "VLTOBT" ) } } } } /* The SpecMap created above class assumes that the axis values supplied to its Transform method are in units which correspond to the default units for its class (the returned values also use these units). However, the Unit attributes of the supplied Frames may have been set to some non-default value, and so we need to add Mappings before and after the SpecMap which convert to and from the default units. Find the Mapping from the target Frame Units to the default Units for the target's system. */ utarg = astGetUnit( target, 0 ); umap1 = astUnitMapper( utarg, SpecMapUnit( target_system, "MakeSpecMap", "SpecFrame", status ), NULL, NULL ); /* Find the Mapping from the default Units for the result's system to the Units of the result Frame. */ ures = astGetUnit( result, 0 ); umap2 = astUnitMapper( SpecMapUnit( result_system, "MakeSpecMap", "SpecFrame", status ), ures, NULL, NULL ); /* If both units Mappings were created OK, sandwich the SpecMap between them. */ if( umap1 && umap2 ) { map1 = (AstMapping *) astCmpMap( umap1, specmap, 1, "", status ); map2 = (AstMapping *) astCmpMap( map1, umap2, 1, "", status ); map1 = astAnnul( map1 ); /* If the simplified SpecMap is a UnitMap, and the target and result units are the same, we do not need to know the mapping between units. Otherwise, report an error and indicate that we cannot convert between the Frames. */ } else { map2 = astSimplify( specmap ); if( !astIsAUnitMap( map2 ) || strcmp( ures, utarg ) ) { match = 0; if( astOK && report ) { if( !umap1 ) { uerr = utarg; serr = astGetSystem( target ); } else { uerr = ures; serr = astGetSystem( result ); } astError( AST__BADUN, "astMatch(SpecFrame): Inappropriate units (%s) " "specified for a %s axis.", status, uerr, SystemLabel( serr, status ) ); } } } /* Step 0: offset to absolute value in target system. Prepend the Maping created above with a ShiftMap that does the required shift of origin. */ target_origin = GetSpecOriginCur( target, status ); if( target_origin != 0.0 ) { sm = astShiftMap( 1, &target_origin, "", status ); map1 = (AstMapping *) astCmpMap( sm, map2, 1, "", status ); sm = astAnnul( sm ); } else { map1 = astClone( map2 ); } map2 = astAnnul( map2 ); /* Step 9: absolute value to offset in result system. If we are aligning in the offset system, use the transformed target origin as the new zero point. Otherwise use the origin from the result frame. First get the origin for the result system. */ if( astGetAlignSpecOffset( target ) && astGetAlignSpecOffset( result ) ) { result_origin = 0.0; astTran1( map1, 1, &result_origin, 1, &result_origin ); } else { result_origin = GetSpecOriginCur( result, status ); } /* Now create the ShiftMap and apend it to the end of the Maping. */ if( result_origin != 0.0 ) { result_origin = -result_origin; sm = astShiftMap( 1, &result_origin, "", status ); map2 = (AstMapping *) astCmpMap( map1, sm, 1, "", status ); sm = astAnnul( sm ); } else { map2 = astClone( map1 ); } map1 = astAnnul( map1 ); /* Return the simplified Mapping. */ *map = astSimplify( map2 ); /* Annul remaining resources. */ map2 = astAnnul( map2 ); specmap = astAnnul( specmap ); if( umap1 ) umap1 = astAnnul( umap1 ); if( umap2 ) umap2 = astAnnul( umap2 ); align_result = astAnnul( align_result ); align_target = astAnnul( align_target ); /* If an error occurred, annul the returned Mapping and clear the returned values. */ if ( !astOK ) { *map = astAnnul( *map ); match = 0; } /* Return the result. */ return match; /* Undefine macros local to this function. */ #undef MAX_ARGS #undef TRANSFORM_0 #undef TRANSFORM_1 } static int Match( AstFrame *template_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 "specframe.h" * int Match( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result, int *status ) * Class Membership: * SpecFrame member function (over-rides the protected astMatch method * inherited from the Frame class). * Description: * This function matches a "template" SpecFrame to a "target" Frame and * determines whether it is possible to convert coordinates between them. * If it is, a mapping that performs the transformation is returned along * with a new Frame that describes the coordinate system that results when * this mapping is applied to the "target" coordinate system. In addition, * information is returned to allow the axes in this "result" Frame to be * associated with the corresponding axes in the "target" and "template" * Frames from which they are derived. * Parameters: * template * Pointer to the template SpecFrame. This describes the coordinate * system (or set of possible coordinate systems) into which we wish to * convert our coordinates. * target * Pointer to the target Frame. This describes the coordinate system in * which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case. * 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 template SpecFrame axis from * which it is derived. If it is not derived from any template * SpecFrame 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 and the template Frames. In * particular, when the template allows the possibility of transformaing * to any one of a set of alternative coordinate systems, the "result" * Frame will indicate which of the alternatives was used. * 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. * Implementation Notes: * This implementation addresses the matching of a SpecFrame class * object to any other class of Frame. A SpecFrame will match any class * of SpecFrame (i.e. possibly from a derived class) but will not match * a less specialised class of Frame. */ /* Local Variables: */ AstFrame *frame0; /* Pointer to Frame underlying axis 0 */ AstSpecFrame *template; /* Pointer to template SpecFrame structure */ int iaxis0; /* Axis index underlying axis 0 */ int iaxis; /* Axis index */ int match; /* Coordinate conversion possible? */ int target_axis0; /* Index of SpecFrame axis in the target */ int target_naxes; /* Number of target axes */ /* Initialise the returned values. */ *template_axes = NULL; *target_axes = NULL; *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain a pointer to the template SpecFrame structure. */ template = (AstSpecFrame *) template_frame; /* Obtain the number of axes in the target Frame. */ target_naxes = astGetNaxes( target ); /* The first criterion for a match is that the template matches as a Frame class object. This ensures that the number of axes (1) and domain, etc. of the target Frame are suitable. Invoke the parent "astMatch" method to verify this. */ match = (*parent_match)( template_frame, target, matchsub, template_axes, target_axes, map, result, status ); /* If a match was found, annul the returned objects, which are not needed, but keep the memory allocated for the axis association arrays, which we will re-use. */ if ( astOK && match ) { *map = astAnnul( *map ); *result = astAnnul( *result ); } /* If OK so far, obtain pointers to the primary Frames which underlie all target axes. Stop when a SpecFrame axis is found. */ if ( match && astOK ) { match = 0; for( iaxis = 0; iaxis < target_naxes; iaxis++ ) { astPrimaryFrame( target, iaxis, &frame0, &iaxis0 ); if( astIsASpecFrame( frame0 ) ) { frame0 = astAnnul( frame0 ); target_axis0 = iaxis; match = 1; break; } else { frame0 = astAnnul( frame0 ); } } } /* Check at least one SpecFrame axis was found it the target. Store the axis associataions. */ if( match && astOK ) { (*template_axes)[ 0 ] = 0; (*target_axes)[ 0 ] = target_axis0; /* Use the target's "astSubFrame" method to create a new Frame (the result Frame) with copies of the target axes in the required order. This process also overlays the template attributes on to the target Frame and returns a Mapping between the target and result Frames which effects the required coordinate conversion. */ match = astSubFrame( target, template, 1, *target_axes, *template_axes, map, result ); } /* If an error occurred, or conversion to the result Frame's coordinate system was not possible, then free all memory, annul the returned objects, and reset the returned value. */ if ( !astOK || !match ) { *template_axes = astFree( *template_axes ); *target_axes = astFree( *target_axes ); if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } static void OriginStdOfRest( AstSpecFrame *this, AstStdOfRestType newsor, const char *method, int *status ){ /* * Name: * OriginStdOfRest * Purpose: * Convert the SpecOrigin in a SpecFrame to a new rest frame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void OriginStdOfRest( AstSpecFrame *this, AstStdOfRestType newsor, * const char *method, int *status ) * Class Membership: * SpecFrame member function * Description: * This function converts the value of the SpecOrigin attribute stored * within a supplied SpecFrame from the rest frame currently associated * with the SpecFrame, to the new rest frame indicated by "newsor". * Parameters: * this * Point to the SpecFrame. On entry, the SpecOrigin value is * assumed to refer to the re st frame given by the astGetStdOfRest * method. On exit, the SpecOrigin value refers to the rest frame * supplied in "newsor". The StdOfRest attribute of the SpecFrame * should then be modified in order to keep things consistent. * newsor * The rest frame to which the SpecOrigin value stored within "this" * should refer on exit. * method * Pointer to a string holding the name of the method to be * included in any error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSpecFrame *sf; AstFrameSet *fs; double origin; double neworigin; /* Check the global error status. */ if ( !astOK ) return; /* Do nothing if the SpecOrigin attribute has not been assigned a value. */ if( astTestSpecOrigin( this ) ) { /* Do nothing if the rest frame will not change. */ if( newsor != astGetStdOfRest( this ) ) { /* Save the original SpecOrigin value (in the current SpecFrame units) and then clear it. */ origin = GetSpecOriginCur( this, status ); astClearSpecOrigin( this ); /* Take a copy of the SpecFrame and set the new StdOfRest. */ sf = astCopy( this ); astSetStdOfRest( sf, newsor ); /* Create a Mapping to perform the rest frame change, then use it to convert the value to the new rest frame. */ fs = astConvert( this, sf, "" ); neworigin = AST__BAD; if( fs ) { astTran1( fs, 1, &origin, 1, &neworigin ); fs = astAnnul( fs ); } /* If succesful, convert from the current units to the default units, and store in "this". */ if( neworigin != AST__BAD ) { astSetSpecOrigin( this, ToUnits( this, astGetUnit( this, 0 ), neworigin, method, status ) ); } else if( astOK ) { astError( AST__ATSER, "%s(%s): Cannot convert the SpecOrigin " "value to a different rest frame.", status, method, astGetClass( this ) ); } } } } static void OriginSystem( AstSpecFrame *this, AstSystemType oldsys, const char *method, int *status ){ /* * Name: * OriginSystem * Purpose: * Convert the SpecOrigin in a SpecFrame to a new System. * Type: * Private function. * Synopsis: * #include "specframe.h" * void OriginSystem( AstSpecFrame *this, AstSystemType oldsys, * const char *method, int *status ) * Class Membership: * SpecFrame member function * Description: * This function converts the value of the SpecOrigin attribute stored * within a supplied SpecFrame from its original System, etc, to the * System, etc, currently associated with the SpecFrame. * Parameters: * this * Point to the SpecFrame. On entry, the SpecOrigin value is * assumed to refer to the System given by "oldsys", etc. On exit, the * SpecOrigin value refers to the System returned by the astGetSystem * method, etc. * oldsys * The System to which the SpecOrigin value stored within "this" * refers on entry. * method * A string containing the method name for error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSpecFrame *sf1; AstSpecFrame *sf2; AstFrameSet *fs; double origin; double neworigin; /* Check the global error status. */ if ( !astOK ) return; /* Do nothing if the SpecOrigin attribute has not been assigned a value. */ if( astTestSpecOrigin( this ) ) { /* Do nothing if the System will not change. */ if( oldsys != astGetSystem( this ) ) { /* Note the original SpecOrigin value, in the SpecFrame's default units. */ origin = astGetSpecOrigin( this ); /* Take a copy of the original SpecFrame and ensure the Units, SpecOrigin and AlignSpecOffset attributes are cleared. */ sf1 = astCopy( this ); astClearUnit( sf1, 0 ); astClearSpecOrigin( sf1 ); astClearAlignSpecOffset( sf1 ); /* Take another copy of the SpecFrame and set the old system. */ sf2 = astCopy( sf1 ); astSetSystem( sf2, oldsys ); /* Create a Mapping to perform the rest frame change, then use it to convert the value to the current system. */ fs = astConvert( sf2, sf1, "" ); neworigin = AST__BAD; if( fs ) { astTran1( fs, 1, &origin, 1, &neworigin ); fs = astAnnul( fs ); } /* Free resources */ sf1 = astAnnul( sf1 ); sf2 = astAnnul( sf2 ); /* If succesful, store it in "this". */ if( neworigin != AST__BAD ) { astSetSpecOrigin( this, neworigin ); } else if( astOK ) { astError( AST__ATSER, "%s(%s): Cannot convert the SpecOrigin " "value to a different spectral system.", status, method, astGetClass( this ) ); } } } } static void Overlay( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { /* * Name: * Overlay * Purpose: * Overlay the attributes of a template SpecFrame on to another Frame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void Overlay( AstFrame *template, const int *template_axes, * AstFrame *result, int *status ) * Class Membership: * SpecFrame member function (over-rides the protected astOverlay method * inherited from the Frame class). * Description: * This function overlays attributes of a SpecFrame (the "template") on to * another Frame, so as to over-ride selected attributes of that second * Frame. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which a Frame acquires attributes from the template, but * retains its original attributes (as the default) if new values have not * previously been explicitly set in the template. * * Note that if the result Frame is a SpecFrame and a change of spectral * coordinate system occurs as a result of overlaying its System * attribute, then some of its original attribute values may no * longer be appropriate (e.g. the Title, or attributes describing * its axes). In this case, these will be cleared before overlaying * any new values. * Parameters: * template * Pointer to the template SpecFrame, for which values should have been * explicitly set for any attribute which is to be transferred. * template_axes * Pointer to an array of int, with one element for each axis of the * "result" Frame (see below). For each axis in the result frame, the * corresponding element of this array should contain the (zero-based) * index of the template axis to which it corresponds. This array is used * to establish from which template axis any axis-dependent attributes * should be obtained. * * If any axis in the result Frame is not associated with a template * axis, the corresponding element of this array should be set to -1. * * If a NULL pointer is supplied, the template and result axis * indices are assumed to be identical. * result * Pointer to the Frame which is to receive the new attribute values. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - In general, if the result Frame is not from the same class as the * template SpecFrame, or from a class derived from it, then attributes may * exist in the template SpecFrame which do not exist in the result Frame. * In this case, these attributes will not be transferred. */ /* Local Variables: */ AstFrame *templt; /* Copy of supplied template Frame */ AstSystemType new_system; /* Code identifying new cordinates */ AstSystemType old_system; /* Code identifying old coordinates */ const char *method; /* Pointer to method string */ const char *new_class; /* Pointer to template class string */ const char *old_class; /* Pointer to result class string */ int specframe; /* Result Frame is a SpecFrame? */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise strings used in error messages. */ new_class = astGetClass( template ); old_class = astGetClass( result ); method = "astOverlay"; /* Get the old and new systems. */ old_system = astGetSystem( result ); new_system = astGetSystem( template ); /* It may be necessary to make temporary changes to the template Frame below. In order to ensure that we make no permanent changes to the supplied frame, we will, if necessary, take a deep copy of the supplied Frame, storing a pointer to the copy in "templt". If it is not necessary to make any changes to the template, we still want "templt" to hold a usable pointer, so we initialise it now to hold a clone of the supplied pointer. This pointer will be replaced by a pointer to a deep copy (if required) below. */ templt = astClone( template ); /* If the result Frame is a SpecFrame, we must test to see if overlaying its System attribute will change the type of coordinate system it describes. Determine the value of this attribute for the result and template SpecFrames. */ specframe = astIsASpecFrame( result ); if( specframe ) { /* If the coordinate system will change, any value already set for the result SpecFrame's Title will no longer be appropriate, so clear it. */ if ( new_system != old_system ) { astClearTitle( result ); /* If the systems have the same default units, we can retain the current Unit value. */ if( strcmp( DefUnit( new_system, method, new_class, status ), DefUnit( old_system, method, old_class, status ) ) ) { astClearUnit( result, 0 ); } /* If necessary, clear inappropriate values for all those axis attributes whose access functions are over-ridden by this class (these access functions will then provide suitable defaults appropriate to the new coordinate system instead). */ astClearLabel( result, 0 ); astClearSymbol( result, 0 ); } /* If the result Frame is not a SpecFrame, we must temporarily clear the System and AlignSystem values since the values used by this class are only appropriate to this class. Use a deep copy to avoid the danger of making any permanent changes to the suppied Frame. */ } else { if( astTestSystem( template ) ) { templt = astAnnul( templt ); templt = astCopy( template ); astClearSystem( templt ); astClearAlignSystem( templt ); } } /* Invoke the parent class astOverlay method to transfer attributes inherited from the parent class. */ (*parent_overlay)( templt, template_axes, result, status ); /* Check if the result Frame is a SpecFrame or from a class derived from SpecFrame. If not, we cannot transfer SpecFrame attributes to it as it is insufficiently specialised. In this case simply omit these attributes. */ if ( specframe && astOK ) { /* Define macros that test whether an attribute is set in the template and, if so, transfers its value to the result. */ #define OVERLAY(attribute) \ if ( astTest##attribute( template ) ) { \ astSet##attribute( result, astGet##attribute( template ) ); \ } /* Use the macro to transfer each SpecFrame attribute in turn. Note, SourceVRF must be overlayed before SourceVel. Otherwise the stored value for SourceVel would be changed from the default SourceVRF to the specified SourceVRF when SourceVRF was overlayed. */ OVERLAY(AlignStdOfRest) OVERLAY(AlignSpecOffset); OVERLAY(RefDec) OVERLAY(RefRA) OVERLAY(RestFreq) OVERLAY(SourceSys) OVERLAY(SourceVRF) OVERLAY(SourceVel) OVERLAY(StdOfRest) OVERLAY(SpecOrigin) } /* Free resources */ templt = astAnnul( templt ); /* Undefine macros local to this function. */ #undef OVERLAY } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * SpecFrame member function (extends the astSetAttrib method inherited from * the Mapping class). * Description: * This function assigns an attribute value for a SpecFrame, 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 SpecFrame. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This protected method is intended to be invoked by the Object astSet * method and makes additional attributes accessible to it. */ /* Local Vaiables: */ AstMapping *umap; /* Mapping between units */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ AstStdOfRestType sor; /* Standard of rest type code */ AstSystemType sys; /* Spectral system type code */ char *a; /* Pointer to next character */ char *new_setting; /* Pointer value to new attribute setting */ double dval; /* Double atribute value */ double dtemp; /* Temporary double atribute value */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int ulen; /* Used length of setting string */ int namelen; /* Length of attribute name in setting */ int nc; /* Number of characters read by astSscanf */ int off; /* Offset of attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_object; /* Create an FK5 J2000 SkyFrame which will be used for formatting and unformatting sky positions, etc. */ LOCK_MUTEX2 if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000", status ); astEndPM; } UNLOCK_MUTEX2 /* Obtain the length of the setting string. */ len = strlen( setting ); /* Obtain the used length of the setting string. */ ulen = astChrLen( 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. */ /* First look for axis attributes defined by the Frame class. Since a SpecFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strncmp( setting, "direction=", 10 ) || !strncmp( setting, "bottom=", 7 ) || !strncmp( setting, "top=", 4 ) || !strncmp( setting, "format=", 7 ) || !strncmp( setting, "label=", 6 ) || !strncmp( setting, "symbol=", 7 ) || !strncmp( setting, "unit=", 5 ) ) { /* Create a new setting string from the original by appending the string "(1)" to the end of the attribute name and then use the parent SetAttrib method. */ new_setting = astMalloc( len + 4 ); if( new_setting ) { memcpy( new_setting, setting, len + 1 ); a = strchr( new_setting, '=' ); namelen = a - new_setting; memcpy( a, "(1)", 4 ); a += 3; strcpy( a, setting + namelen ); (*parent_setattrib)( this_object, new_setting, status ); new_setting = astFree( new_setting ); } /* AlignStdOfRest. */ /* --------------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "alignstdofrest=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a StdOfRest code before use. */ sor = StdOfRestCode( setting + off, status ); if ( sor != AST__BADSOR ) { astSetAlignStdOfRest( this, sor ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid standard of rest " "description \"%s\".", status, astGetClass( this ), setting+off ); } /* GeoLat. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had GeoLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( nc = 0, ( 0 == astSscanf( setting, "geolat=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { new_setting = astStore( NULL, setting, len + 1 ); new_setting[ 0 ] = 'o'; new_setting[ 1 ] = 'b'; new_setting[ 2 ] = 's'; astSetAttrib( this, new_setting ); new_setting = astFree( new_setting ); /* GeoLon. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "geolon=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { new_setting = astStore( NULL, setting, len + 1 ); new_setting[ 0 ] = 'o'; new_setting[ 1 ] = 'b'; new_setting[ 2 ] = 's'; astSetAttrib( this, new_setting ); new_setting = astFree( new_setting ); /* RefDec. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "refdec=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { /* Convert the string to a radians value before use. */ ival = astUnformat( skyframe, 1, setting + off, &dval ); if ( ival == ulen - off ) { astSetRefDec( this, dval ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid reference " "declination \"%s\".", status, astGetClass( this ), setting + off ); } /* RefRA. */ /* ------ */ } else if ( nc = 0, ( 0 == astSscanf( setting, "refra=%n%*s %n", &off, &nc ) ) && ( nc >= 6 ) ) { /* Convert the string to a radians value before use. */ ival = astUnformat( skyframe, 0, setting + off, &dval ); if ( ival == ulen - off ) { astSetRefRA( this, dval ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid reference right " "ascension \"%s\".", status, astGetClass( this ), setting + off ); } /* AlignSpecOffset. */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "alignspecoffset= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetAlignSpecOffset( this, ival ); /* RestFreq. */ /* --------- */ /* Without any units indication - assume GHz. Convert to Hz for storage. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "restfreq= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetRestFreq( this, dval*1.0E9 ); /* With units indication. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "restfreq= %lg %n%*s %n", &dval, &off, &nc ) ) && ( nc >= len ) ) { dtemp = AST__BAD; /* Is there a Mapping from the supplied units to Hz? If so, use the Mapping to convert the supplied value to Hz. */ if( ( umap = astUnitMapper( setting + off, "Hz", NULL, NULL ) ) ) { astTran1( umap, 1, &dval, 1, &dtemp ); umap = astAnnul( umap ); /* Otherwise, if there is a Mapping from the supplied units to metre, assume the supplied unit is a vacuum wavelength. */ } else if( ( umap = astUnitMapper( setting + off, "m", NULL, NULL ) ) ) { /* Convert the supplied wavelength to metres. */ astTran1( umap, 1, &dval, 1, &dtemp ); umap = astAnnul( umap ); /* Convert the wavelength (m) to frequency (Hz). */ if( dtemp != AST__BAD && dtemp != 0.0 ) { dtemp = AST__C/dtemp; } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): Invalid rest wavelength " "\"%g %s\" supplied.", status, astGetClass( this ), dval, setting + off ); } /* Otherwise, if there is a Mapping from the supplied units to Joule, assume the supplied unit is an energy. */ } else if( ( umap = astUnitMapper( setting + off, "J", NULL, NULL ) ) ) { /* Convert the supplied energy to Joules. */ astTran1( umap, 1, &dval, 1, &dtemp ); umap = astAnnul( umap ); /* Convert the energy (J) to frequency (Hz). */ if( dtemp != AST__BAD ) { dtemp *= 1.0/AST__H; } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): Invalid rest energy " "\"%g %s\" supplied.", status, astGetClass( this ), dval, setting + off ); } /* Otherwise report an error. */ } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): Rest frequency given in an " "unsupported system of units \"%g %s\".", status, astGetClass( this ), dval, setting + off ); } /* Set the rest frequency. */ astSetRestFreq( this, dtemp ); /* SourceVel. */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "sourcevel= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { /* Convert from km/s to m/s if the SourceVel value is a velocity. */ if( astGetSourceSys( this ) == AST__VREL || astGetSourceSys( this ) == AST__VRADIO || astGetSourceSys( this ) == AST__VOPTICAL ) dval *= 1.0E3; /* Store the value */ astSetSourceVel( this, dval ); /* SourceVRF */ /* --------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "sourcevrf=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a StdOfRest code before use. */ sor = StdOfRestCode( setting + off, status ); if ( sor != AST__BADSOR ) { astSetSourceVRF( this, sor ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid standard of rest " "description \"%s\".", status, astGetClass( this ), setting+off ); } /* SourceSys */ /* --------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "sourcesys=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a System code before use. */ sys = SystemCode( (AstFrame *) this, setting + off, status ); astSetSourceSys( this, sys ); /* StdOfRest. */ /* ---------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "stdofrest=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a StdOfRest code before use. */ sor = StdOfRestCode( setting + off, status ); if ( sor != AST__BADSOR ) { astSetStdOfRest( this, sor ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid standard of rest " "description \"%s\".", status, astGetClass( this ), setting + off ); } /* SpecOrigin */ /* ---------- */ /* Floating-point without any units indication - assume the current Unit value. Convert from current units to default units for current system. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "specorigin= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetSpecOrigin( this, ToUnits( this, astGetUnit( this, 0 ), dval, "astSetSpecOrigin", status ) ); /* Floating-point with units. Convert the supplied value to the default units for the SpecFrame's System. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "specorigin= %lg %n%*s %n", &dval, &off, &nc ) ) && ( nc >= len ) ) { astSetSpecOrigin( this, ToUnits( this, setting + off, dval, "astSetSpecOrigin", status ) ); /* Pass any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetRefPos( AstSpecFrame *this, AstSkyFrame *frm, double lon, double lat, int *status ){ /* *++ * Name: c astSetRefPos f AST_SETREFPOS * Purpose: * Set the reference position in a specified celestial coordinate system. * Type: * Public virtual function. * Synopsis: c #include "specframe.h" c void astSetRefPos( AstSpecFrame *this, AstSkyFrame *frm, double lon, c double lat ) f CALL AST_SETREFPOS( THIS, FRM, LON, LAT, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * sets the reference position (see attributes RefRA and RefDec) using * axis values (in radians) supplied within the celestial coordinate * system represented by a supplied SkyFrame. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the SpecFrame. c frm f FRM = INTEGER (Given) * Pointer to the SkyFrame which defines the celestial coordinate * system in which the longitude and latitude values are supplied. c If NULL f If AST__NULL * is supplied, then the supplied longitude and latitude values are * assumed to be FK5 J2000 RA and Dec values. c lon f LON = DOUBLE PRECISION (Given) * The longitude of the reference point, in the coordinate system * represented by the supplied SkyFrame (radians). c lat f LAT = DOUBLE PRECISION (Given) * The latitude of the reference point, in the coordinate system * represented by the supplied SkyFrame (radians). f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstFrameSet *fs; /* Conversion FrameSet */ AstFrame *fb; /* Base Frame */ AstFrame *fc; /* Current Frame */ double xin[ 1 ]; /* Axis 1 values */ double yin[ 1 ]; /* Axis 2 values */ double xout[ 1 ]; /* Axis 1 values */ double yout[ 1 ]; /* Axis 2 values */ /* Check the global error status. */ if ( !astOK ) return; /* If no SkyFrame was supplied, just store the supplied RefRA and RefDec values. */ if( !frm ) { astSetRefRA( this, lon ); astSetRefDec( this, lat ); /* Otherwise, convert the supplied values from the requested system. */ } else { /* Create an FK5 J2000 SkyFrame which will be used for formatting and unformatting sky positions, etc. */ LOCK_MUTEX2 if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000", status ); astEndPM; } UNLOCK_MUTEX2 /* Find the Mapping from the supplied SkyFrame, to the SkyFrame which describes the internal format in which the RefRA and RefDec attribute values are stored. */ fs = astFindFrame( frm, skyframe, "" ); /* If alignment was possible, use the Mapping to transform the supplied axis values, checking to see if the axes of the supplied SkyFrame have been permuted. */ if( fs ) { /* Find the longitude axis in the Base Frame, and store the supplied longitude and latitude values. */ fb = astGetFrame( fs, AST__BASE ); if( astGetLonAxis( fb ) == 0 ) { xin[ 0 ] = lon; yin[ 0 ] = lat; } else { xin[ 0 ] = lat; yin[ 0 ] = lon; } astTran2( fs, 1, xin, yin, 1, xout, yout ); /* Store the corresponding RefRA and RefDec values. */ fc = astGetFrame( fs, AST__CURRENT ); if( astGetLonAxis( fc ) == 0 ) { astSetRefRA( this, xout[ 0 ] ); astSetRefDec( this, yout[ 0 ] ); } else { astSetRefRA( this, yout[ 0 ] ); astSetRefDec( this, xout[ 0 ] ); } /* Annul object references. */ fc = astAnnul( fc ); fb = astAnnul( fb ); fs = astAnnul( fs ); } } } static void SetStdOfRest( AstSpecFrame *this, AstStdOfRestType value, int *status ) { /* *+ * Name: * astSetStdOfRest * Purpose: * Set the StdOfRest attribute for a SpecFrame. * Type: * Protected function. * Synopsis: * #include "specframe.h" * void astSetStdOfRest( AstSpecFrame *this, AstStdOfRestType value ) * Class Membership: * SpecFrame virtual function * Description: * This function set a new value for the StdOfRest attribute for a * SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * value * The new value. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the StdOfRest value being set and report an error if necessary. */ if( value < FIRST_SOR || value > LAST_SOR ) { astError( AST__ATTIN, "%s(%s): Bad value (%d) given for StdOfRest attribute.", status, "astSetStdOfRest", astGetClass( this ), (int) value ); /* Otherwise set the new StdOfRest */ } else { /* Modify the SpecOrigin value stored in the SpecFrame structure to refer to the new rest frame. */ OriginStdOfRest( this, value, "astSetStdOfRest", status ); /* Store the new value for the rest frame in the SpecFrame structure. */ this->stdofrest = value; } } static void SetSystem( AstFrame *this_frame, AstSystemType newsys, int *status ) { /* * Name: * SetSystem * Purpose: * Set the System attribute for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void SetSystem( AstFrame *this_frame, AstSystemType newsys, int *status ) * Class Membership: * SpecFrame member function (over-rides the astSetSystem protected * method inherited from the Frame class). * Description: * This function sets the System attribute for a SpecFrame. * Parameters: * this * Pointer to the SpecFrame. * newsys * The new System value to be stored. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to SpecFrame structure */ AstSystemType oldsys; /* Original System value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* Save the original System value */ oldsys = astGetSystem( this_frame ); /* Use the parent SetSystem method to store the new System value. */ (*parent_setsystem)( this_frame, newsys, status ); /* If the system has changed... */ if( oldsys != newsys ) { /* Changing the System value will in general require the Units to change as well. If the user has previously specified the units to be used with the new system, then re-instate them (they are stored in the "usedunits" array in the SpecFrame structure). Otherwise, clear the units so that the default units will eb used with the new System. */ if( (int) newsys < this->nuunits && this->usedunits && this->usedunits[ (int) newsys ] ) { astSetUnit( this, 0, this->usedunits[ (int) newsys ] ); } else { astClearUnit( this, 0 ); } /* Modify the stored SpecOrigin. */ OriginSystem( this, oldsys, "astSetSystem", status ); /* Also, clear all attributes which have system-specific defaults. */ astClearLabel( this_frame, 0 ); astClearSymbol( this_frame, 0 ); astClearTitle( this_frame ); } } static void SetUnit( AstFrame *this_frame, int axis, const char *value, int *status ) { /* * Name: * SetUnit * Purpose: * Set a pointer to the Unit string for a SpecFrame's axis. * Type: * Private function. * Synopsis: * #include "specframe.h" * void SetUnit( AstFrame *this_frame, int axis, const char *value ) * Class Membership: * SpecFrame member function (over-rides the astSetUnit method inherited * from the Frame class). * Description: * This function stores a pointer to the Unit string for a specified axis * of a SpecFrame. It also stores the string in the "usedunits" array * in the SpecFrame structure, in the element associated with the * current System. * Parameters: * this * Pointer to the SpecFrame. * axis * The number of the axis (zero-based) for which information is required. * unit * The new string to store. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ int i; /* Loop counter */ int system; /* The SpecFrame's System value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_frame; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astSetUnit" ); /* Store the supplied value as the UsedUnit for the current System. First ensure the array is big enough. Free any previous value stored for the current system. */ system = (int) astGetSystem( this ); if( system >= this->nuunits ) { this->usedunits = astGrow( this->usedunits, system + 1, sizeof(char *) ); if( astOK ) { for( i = this->nuunits; i < system + 1; i++ ) this->usedunits[ i ] = NULL; this->nuunits = system + 1; } } /* Now store a copy of the value, if it is different to the stored string. */ if( astOK && ( !this->usedunits[ system ] || strcmp( this->usedunits[ system ], value ) ) ) { this->usedunits[ system ] = astStore( this->usedunits[ system ], value, strlen( value ) + 1 ); } /* Now use the parent SetUnit method to store the value in the Axis structure */ (*parent_setunit)( this_frame, axis, value, status ); } static int SorConvert( AstSpecFrame *this, AstSpecFrame *that, AstSpecMap *specmap, int *status ) { /* * Name: * SorConvert * Purpose: * Add a conversion to a SpecMap which transforms between two * standards of rest. * Type: * Private function. * Synopsis: * #include "specframe.h" * int SorConvert( AstSpecFrame *this, AstSpecFrame *that, * AstSpecMap *specmap, int *status ) * Class Membership: * SpecFrame member function. * Description: * This function adds a conversion to a SpecMap which transforms * frequencies from the standard of rest specified by "this" to * the standard of rest specified by "that". Note the conversion is * always between frequency in the two rest frames no matter what the * System attributes of the two SpecFrames may be (which are ignored). * Parameters: * this * The SpecFrame which defines the input rest frame. * that * The SpecFrame which defines the output rest frame. * specmap * The SpecMap to which the conversion is to be added. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the conversion could not be performed. One is * returned otherwise. */ /* Local Constants: */ #define MAX_ARGS 7 /* Max arguments for an SpecMap conversion */ /* Local Variables: */ AstStdOfRestType from; /* Input standard of rest */ AstStdOfRestType to; /* Output standard of rest */ const char *vmess; /* Text for use in error messages */ double args[ MAX_ARGS ]; /* Conversion argument array */ double dec; /* DEC of source (radians, FK5 J2000) */ double epoch; /* Epoch of observation (MJD) */ double alt; /* Observers geodetic altitude (radians) */ double lat; /* Observers geodetic latitude (radians) */ double lon; /* Observers geodetic longitude (radians) */ double ra; /* RA of source (radians, FK5 J2000) */ int result; /* Returned value */ /* Initialise */ result = 1; /* Check the global error status. */ if ( !astOK ) return result; /* No conversion is required if the rest frames are equal. */ if( !EqualSor( this, that, status ) ) { /* Define local macros as shorthand for adding spectral coordinate conversions to the SpecMap. Each macro simply stores details of the additional arguments in the "args" array and then calls astSpecAdd. The macros differ in the number of additional argument values. */ #define TRANSFORM_2(cvt,arg0,arg1) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ astSpecAdd( specmap, cvt, args ); #define TRANSFORM_3(cvt,arg0,arg1,arg2) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ args[ 2 ] = arg2; \ astSpecAdd( specmap, cvt, args ); #define TRANSFORM_6(cvt,arg0,arg1,arg2,arg3,arg4,arg5) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ args[ 2 ] = arg2; \ args[ 3 ] = arg3; \ args[ 4 ] = arg4; \ args[ 5 ] = arg5; \ astSpecAdd( specmap, cvt, args ); /* A string for use in error messages. */ vmess = "convert between different standards of rest"; /* Get the required values from "this". */ from = astGetStdOfRest( this ); ra = astGetRefRA( this ); dec = astGetRefDec( this ); lon = astGetObsLon( this ); lat = astGetObsLat( this ); alt = astGetObsAlt( this ); epoch = astGetEpoch( this ); /* Verify that the reference RA and DEC can be used (they are needed by all the conversions used below). */ VerifyAttrs( this, vmess, "RefRA RefDec", "astMatch", status ); /* Convert from the "this" rest frame to heliographic. */ if( from == AST__TPSOR ) { VerifyAttrs( this, vmess, "ObsLon ObsLat ObsAlt Epoch", "astMatch", status ); TRANSFORM_6( "TPF2HL", lon, lat, alt, epoch, ra, dec ) } else if( from == AST__GESOR ) { VerifyAttrs( this, vmess, "Epoch", "astMatch", status ); TRANSFORM_3( "GEF2HL", epoch, ra, dec ) } else if( from == AST__BYSOR ) { VerifyAttrs( this, vmess, "Epoch", "astMatch", status ); TRANSFORM_3( "BYF2HL", epoch, ra, dec ) } else if( from == AST__LKSOR ) { TRANSFORM_2( "LKF2HL", ra, dec ) } else if( from == AST__LDSOR ) { TRANSFORM_2( "LDF2HL", ra, dec ) } else if( from == AST__LGSOR ) { TRANSFORM_2( "LGF2HL", ra, dec ) } else if( from == AST__GLSOR ) { TRANSFORM_2( "GLF2HL", ra, dec ) } else if( from == AST__SCSOR ) { TRANSFORM_3( "USF2HL", ConvertSourceVel( this, AST__HLSOR, AST__VREL, status ), ra, dec ) } /* Now go from heliocentric to the "to" frame. */ to = astGetStdOfRest( that ); ra = astGetRefRA( that ); dec = astGetRefDec( that ); lon = astGetObsLon( that ); lat = astGetObsLat( that ); alt = astGetObsAlt( that ); epoch = astGetEpoch( that ); VerifyAttrs( that, vmess, "RefRA RefDec", "astMatch", status ); if( to == AST__TPSOR ) { VerifyAttrs( that, vmess, "ObsLon ObsLat ObsAlt Epoch", "astMatch", status ); TRANSFORM_6( "HLF2TP", lon, lat, alt, epoch, ra, dec ) } else if( to == AST__GESOR ) { VerifyAttrs( that, vmess, "Epoch", "astMatch", status ); TRANSFORM_3( "HLF2GE", epoch, ra, dec ) } else if( to == AST__BYSOR ) { VerifyAttrs( that, vmess, "Epoch", "astMatch", status ); TRANSFORM_3( "HLF2BY", epoch, ra, dec ) } else if( to == AST__LKSOR ) { TRANSFORM_2( "HLF2LK", ra, dec ) } else if( to == AST__LDSOR ) { TRANSFORM_2( "HLF2LD", ra, dec ) } else if( to == AST__LGSOR ) { TRANSFORM_2( "HLF2LG", ra, dec ) } else if( to == AST__GLSOR ) { TRANSFORM_2( "HLF2GL", ra, dec ) } else if( to == AST__SCSOR ) { TRANSFORM_3( "HLF2US", ConvertSourceVel( that, AST__HLSOR, AST__VREL, status ), ra, dec ) } } /* Return the result. */ return result; /* Undefine macros local to this function. */ #undef MAX_ARGS #undef TRANSFORM_2 #undef TRANSFORM_3 #undef TRANSFORM_6 } static const char *SpecMapUnit( AstSystemType system, const char *method, const char *class, int *status ){ /* * Name: * SpecMapUnit * Purpose: * Return the default units for a spectral coordinate system type used * by the SpecMap class. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *SpecMapUnit( AstSystemType system, const char *method, * const char *class, int *status ) * Class Membership: * SpecFrame member function. * Description: * This function returns a textual representation of the * units used by the SpecMap class for the specified spectral * coordinate system. In general, the SpecMap class uses SI units * (m/s, Hz, m, etc), but this class (SpecFrame) has default units * more appropriate to astronomers (km/s, GHz, Angstroms, etc). * Parameters: * system * The spectral coordinate system. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A string describing the default units. This string follows the * units syntax described in FITS WCS paper I "Representations of world * coordinates in FITS" (Greisen & Calabretta). * Notes: * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ const char *result; /* Value to return */ /* Initialize */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get an identifier for the default units. */ if( system == AST__FREQ ) { result = "Hz"; } else if( system == AST__ENERGY ) { result = "J"; } else if( system == AST__WAVENUM ) { result = "1/m"; } else if( system == AST__WAVELEN ) { result = "m"; } else if( system == AST__AIRWAVE ) { result = "m"; } else if( system == AST__VRADIO ) { result = "m/s"; } else if( system == AST__VOPTICAL ) { result = "m/s"; } else if( system == AST__REDSHIFT ) { result = ""; } else if( system == AST__BETA ) { result = ""; } else if( system == AST__VREL ) { result = "m/s"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "%s(%s): Corrupt %s contains illegal System " "identification code (%d).", status, method, class, class, (int) system ); } /* Return the result. */ return result; } static AstStdOfRestType StdOfRestCode( const char *sor, int *status ) { /* * Name: * StdOfRestCode * Purpose: * Convert a string into a standard of rest type code. * Type: * Private function. * Synopsis: * #include "specframe.h" * AstStdOfRestType StdOfRestCode( const char *sor ) * Class Membership: * SpecFrame member function. * Description: * This function converts a string used for the external description of * a standard of rest into a SpecFrame standard of rest type code * (StdOfRest attribute value). It is the inverse of the * StdOfRestString function. * Parameters: * sor * Pointer to a constant null-terminated string containing the * external description of the standard of rest. * Returned Value: * The StdOfRest type code. * Notes: * - A value of AST__BADSOR is returned if the standard of rest * description was not recognised. This does not produce an error. * - A value of AST__BADSOR is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ AstStdOfRestType result; /* Result value to return */ /* Initialise. */ result = AST__BADSOR; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "sor" string against each possibility and assign the result. */ if ( astChrMatch( "TOPO", sor ) || astChrMatch( "TOPOCENT", sor ) || astChrMatch( "TOPOCENTRIC", sor ) ) { result = AST__TPSOR; } else if ( astChrMatch( "GEO", sor ) || astChrMatch( "GEOCENTR", sor ) || astChrMatch( "GEOCENTRIC", sor ) ) { result = AST__GESOR; } else if ( astChrMatch( "BARY", sor ) || astChrMatch( "BARYCENT", sor ) || astChrMatch( "BARYCENTRIC", sor ) ) { result = AST__BYSOR; } else if ( astChrMatch( "HELIO", sor ) || astChrMatch( "HELIOCEN", sor ) || astChrMatch( "HELIOCENTRIC", sor ) ) { result = AST__HLSOR; } else if ( astChrMatch( "LSRK", sor ) || astChrMatch( "LSR", sor ) ) { result = AST__LKSOR; } else if ( astChrMatch( "LSRD", sor ) ) { result = AST__LDSOR; } else if ( astChrMatch( "GAL", sor ) || astChrMatch( "GALACTOC", sor ) || astChrMatch( "GALACTIC", sor ) ) { result = AST__GLSOR; } else if ( astChrMatch( "LG", sor ) || astChrMatch( "LOCALGRP", sor ) || astChrMatch( "LOCAL_GROUP", sor ) || astChrMatch( "LOCAL-GROUP", sor ) ) { result = AST__LGSOR; } else if ( astChrMatch( "SOURCE", sor ) || astChrMatch( "SRC", sor ) ) { result = AST__SCSOR; } /* Return the result. */ return result; } static const char *StdOfRestString( AstStdOfRestType sor, int *status ) { /* * Name: * StdOfRestString * Purpose: * Convert a standard of rest type code into a string. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *StdOfRestString( AstStdOfRestType sor, int *status ) * Class Membership: * SpecFrame member function. * Description: * This function converts a SpecFrame standard of rest type code * (StdOfRest attribute value) into a string suitable for use as an * external representation of the standard of rest type. * Parameters: * sor * The standard of rest 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 standard of rest * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "sor" value against each possibility and convert to a string pointer. (Where possible, return the same string as would be used in the FITS WCS representation of the standard of rest). */ switch ( sor ) { case AST__TPSOR: result = "Topocentric"; break; case AST__GESOR: result = "Geocentric"; break; case AST__BYSOR: result = "Barycentric"; break; case AST__HLSOR: result = "Heliocentric"; break; case AST__LDSOR: result = "LSRD"; break; case AST__LKSOR: result = "LSRK"; break; case AST__LGSOR: result = "Local_group"; break; case AST__GLSOR: result = "Galactic"; break; case AST__SCSOR: result = "Source"; break; } /* Return the result pointer. */ return result; } static int SubFrame( AstFrame *target_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 SpecFrame and convert to the new coordinate * system. * Type: * Private function. * Synopsis: * #include "specframe.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: * SpecFrame 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 a "target" SpecFrame and creates a new Frame with copies of * the selected axes assembled in the requested order. It then * optionally overlays the attributes of a "template" Frame on to the * result. It returns both the resulting Frame and a Mapping that * describes how to convert between the coordinate systems described by * the target and result Frames. If necessary, this Mapping takes * account of any differences in the Frames' attributes due to the * influence of the template. * Parameters: * target * Pointer to the target SpecFrame, from which axes are to be * selected. * template * Pointer to the template Frame, from which new attributes for the * result Frame are to be obtained. Optionally, this may be NULL, in * which case no overlaying of template attributes will be performed. * result_naxes * Number of axes to be selected from the target Frame. This number may * be greater than or less than the number of axes in this Frame (or * equal). * target_axes * Pointer to an array of int with result_naxes elements, giving a list * of the (zero-based) axis indices of the axes to be selected from the * target SpecFrame. The order in which these are given determines * the order in which the axes appear in the result Frame. If any of the * values in this array is set to -1, the corresponding result axis will * not be derived from the target Frame, but will be assigned default * attributes instead. * template_axes * Pointer to an array of int with result_naxes elements. This should * contain a list of the template axes (given as zero-based axis indices) * with which the axes of the result Frame are to be associated. This * array determines which axes are used when overlaying axis-dependent * attributes of the template on to the result. If any element of this * array is set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not used and * a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned Mapping. * The forward transformation of this Mapping will describe how to * convert coordinates from the coordinate system described by the target * SpecFrame 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 target and the result Frame. Otherwise zero is returned and * *map and *result are returned as NULL (but this will not in itself * result in an error condition). In general, coordinate conversion should * always be possible if no template Frame is supplied but may not always * be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * Implementation Notes: * - This implementation addresses the selection of axes from a * SpecFrame object. This results in another object of the same class * only if the single SpecFrame axis is selected exactly once. * Otherwise, the result is a Frame class object which inherits the * SpecFrame's axis information (if appropriate) but none of the other * properties of a SpecFrame. * - In the event that a SpecFrame results, the returned Mapping will * take proper account of the relationship between the target and result * coordinate systems. * - In the event that a Frame class object results, the returned Mapping * will only represent a selection/permutation of axes. * Implementation Deficiencies: * - Any axis selection is currently permitted. Probably this should be * restricted so that each axis can only be selected once. The * astValidateAxisSelection method will do this but currently there are bugs * in the CmpFrame class that cause axis selections which will not pass this * test. Install the validation when these are fixed. */ /* Local Variables: */ AstSpecFrame *target; /* Pointer to the SpecFrame structure */ AstSpecFrame *temp; /* Pointer to copy of target SpecFrame */ AstSpecFrame *align_frm; /* Frame in which to align the SpecFrames */ int match; /* Coordinate conversion is possible? */ int report; /* Report errors if SpecFrames cannot be aligned? */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain a pointer to the target SpecFrame structure. */ target = (AstSpecFrame *) target_frame; /* Result is a SpecFrame. */ /* -------------------------- */ /* Check if the result Frame is to have one axis obtained by selecting the single target SpecFrame axis. If so, the result will also be a SpecFrame. */ if ( ( result_naxes == 1 ) && ( target_axes[ 0 ] == 0 ) ) { /* Form the result from a copy of the target. */ *result = astCopy( target ); /* Initialise a flag to indicate that MakeSpecMapping should not report errors if no Mapping can be created. */ report = 0; /* If required, overlay the template attributes on to the result SpecFrame. Also get the system and standard of rest in which to align the two SpecFrames. These are the values from the template (if there is a template). */ if ( template ) { astOverlay( template, template_axes, *result ); if( astIsASpecFrame( template ) ) { align_frm = astCopy( template ); /* Since we now know that both the template and target are SpecFrames, it should usually be possible to convert betwen them. If conversion is *not* possible (fpr instance if no rest frequency is availalbe, etc) then the user will probably be interested in knowing the reason why conversion is not possible. Therefore, indicate that MakeSpecMapping should report errors if no Mapping can be created. */ report = 1; } else { align_frm = astCopy( target ); } /* If no template was supplied, align in the System and StdOfRest of the target. */ } else { VerifyAttrs( target, "convert between different spectral systems", "StdOfRest", "astMatch", status ); align_frm = astCopy( target ); } /* The MakeSpecMapping function uses the System and StdOfRest attributes to define the alignment frame. But the AlignSystem and AlignStdOfRest attributes should be used for this purpose. Therefore, copy the values of the AlignSystem and AlignStdOfRest attributes to the System and StdOfRest attribute. */ astSetSystem( align_frm, astGetAlignSystem( align_frm ) ); astSetStdOfRest( align_frm, astGetAlignStdOfRest( align_frm ) ); /* Generate a Mapping that takes account of changes in the sky coordinate system (equinox, epoch, etc.) between the target SpecFrame and the result SpecFrame. If this Mapping can be generated, set "match" to indicate that coordinate conversion is possible. If the template is a specframe, report errors if a match is not possible. */ match = ( MakeSpecMapping( target, (AstSpecFrame *) *result, align_frm, report, map, status ) != 0 ); /* Free resources. */ align_frm = astAnnul( align_frm ); /* Result is not a SpecFrame. */ /* ------------------------------ */ /* In this case, we select axes as if the target were from the Frame class. However, since the resulting data will then be separated from their enclosing SpecFrame, default attribute values may differ if the methods for obtaining them were over-ridden by the SpecFrame class. To overcome this, we ensure that these values are explicitly set for the result Frame (rather than relying on their defaults). */ } else { /* Make a temporary copy of the target SpecFrame. We will explicitly set the attribute values in this copy so as not to modify the original. */ temp = astCopy( target ); /* Define a macro to test if an attribute is set. If not, set it explicitly to its default value. */ #define SET(attribute) \ if ( !astTest##attribute( temp ) ) { \ astSet##attribute( temp, astGet##attribute( temp ) ); \ } /* Set attribute values which apply to the Frame as a whole and which we want to retain, but whose defaults are over-ridden by the SpecFrame class. */ SET(Domain) SET(Title) /* Define a macro to test if an attribute is set for axis zero (the only axis of a SpecFrame). If not, set it explicitly to its default value. */ #define SET_AXIS(attribute) \ if ( !astTest##attribute( temp, 0 ) ) { \ astSet##attribute( temp, 0, \ astGet##attribute( temp, 0 ) ); \ } /* Use this macro to set explicit values for all the axis attributes for which the SpecFrame class over-rides the default value. */ SET_AXIS(Label) SET_AXIS(Symbol) SET_AXIS(Unit) /* Clear attributes which have an extended range of values allowed by this class. */ astClearSystem( temp ); astClearAlignSystem( temp ); /* Invoke the astSubFrame method inherited from the Frame class to produce the result Frame by selecting the required set of axes and overlaying the template Frame's attributes. */ match = (*parent_subframe)( (AstFrame *) temp, template, result_naxes, target_axes, template_axes, map, result, status ); /* Delete the temporary copy of the target SpecFrame. */ temp = astDelete( temp ); } /* If an error occurred or no match was found, annul the returned objects and reset the returned result. */ if ( !astOK || !match ) { if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; /* Undefine macros local to this function. */ #undef SET #undef SET_AXIS } static AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) { /* * Name: * SystemCode * Purpose: * Convert a string into a coordinate system type code. * Type: * Private function. * Synopsis: * #include "specframe.h" * AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) * Class Membership: * SpecFrame member function (over-rides the astSystemCode method * inherited from the Frame class). * Description: * This function converts a string used for the external * description of a coordinate system into a SpecFrame * coordinate system type code (System attribute value). It is the * inverse of the astSystemString function. * Parameters: * this * The Frame. * system * Pointer to a constant null-terminated string containing the * external description of the sky 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 sky coordinate * system description was not recognised. This does not produce an * error. * - A value of AST__BADSYSTEM is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ AstSystemType result; /* Result value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" string against each possibility and assign the result. */ if ( astChrMatch( "FREQ", system ) ) { result = AST__FREQ; } else if ( astChrMatch( "ENER", system ) || astChrMatch( "ENERGY", system ) ) { result = AST__ENERGY; } else if ( astChrMatch( "WAVN", system ) || astChrMatch( "WAVENUM", system ) ) { result = AST__WAVENUM; } else if ( astChrMatch( "WAVE", system ) || astChrMatch( "WAVELEN", system ) ) { result = AST__WAVELEN; } else if ( astChrMatch( "AWAV", system ) || astChrMatch( "AIRWAVE", system ) ) { result = AST__AIRWAVE; } else if ( astChrMatch( "VRAD", system ) || astChrMatch( "VRADIO", system ) ) { result = AST__VRADIO; } else if ( astChrMatch( "VOPT", system ) || astChrMatch( "VOPTICAL", system ) ) { result = AST__VOPTICAL; } else if ( astChrMatch( "ZOPT", system ) || astChrMatch( "REDSHIFT", system ) ) { result = AST__REDSHIFT; } else if ( astChrMatch( "BETA", system ) ) { result = AST__BETA; } else if ( astChrMatch( "VELO", system ) || astChrMatch( "VREL", system ) ) { result = AST__VREL; } /* Return the result. */ return result; } static const char *SystemLabel( AstSystemType system, int *status ) { /* * Name: * SystemLabel * Purpose: * Return a label for a coordinate system type code. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *SystemLabel( AstSystemType system, int *status ) * Class Membership: * SpecFrame member function. * Description: * This function converts a SpecFrame coordinate system type code * (System attribute value) into a descriptive string for human readers. * Parameters: * 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 sky coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. */ switch ( system ) { case AST__FREQ: result = "frequency"; break; case AST__ENERGY: result = "energy"; break; case AST__WAVENUM: result = "wave-number"; break; case AST__WAVELEN: result = "wavelength"; break; case AST__AIRWAVE: result = "wavelength in air"; break; case AST__VRADIO: result = "radio velocity"; break; case AST__VOPTICAL: result = "optical velocity"; break; case AST__REDSHIFT: result = "redshift"; break; case AST__BETA: result = "beta factor"; break; case AST__VREL: result = "apparent radial velocity"; break; } /* Return the result pointer. */ return result; } static const char *SystemString( AstFrame *this, AstSystemType system, int *status ) { /* * Name: * SystemString * Purpose: * Convert a coordinate system type code into a string. * Type: * Private function. * Synopsis: * #include "specframe.h" * const char *SystemString( AstFrame *this, AstSystemType system, int *status ) * Class Membership: * SpecFrame member function (over-rides the astSystemString method * inherited from the Frame class). * Description: * This function converts a SpecFrame coordinate system type code * (System attribute value) into a string suitable for use as an * external representation of the coordinate system type. * Parameters: * this * 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 sky coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. (Where possible, return the same string as would be used in the FITS WCS representation of the coordinate system). */ switch ( system ) { case AST__FREQ: result = "FREQ"; break; case AST__ENERGY: result = "ENER"; break; case AST__WAVENUM: result = "WAVN"; break; case AST__WAVELEN: result = "WAVE"; break; case AST__AIRWAVE: result = "AWAV"; break; case AST__VRADIO: result = "VRAD"; break; case AST__VOPTICAL: result = "VOPT"; break; case AST__REDSHIFT: result = "ZOPT"; break; case AST__BETA: result = "BETA"; break; case AST__VREL: result = "VELO"; break; } /* Return the result pointer. */ return result; } static int TestActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * TestActiveUnit * Purpose: * Test the ActiveUnit flag for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * int TestActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * SpecFrame member function (over-rides the astTestActiveUnit protected * method inherited from the Frame class). * Description: * This function test the value of the ActiveUnit flag for a SpecFrame, * which is always "unset". * Parameters: * this * Pointer to the SpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * The result of the test (0). */ return 0; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a SpecFrame. * Type: * Private function. * Synopsis: * #include "specframe.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SpecFrame 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 SpecFrame's attributes. * Parameters: * this * Pointer to the SpecFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Returned Value: * One if a value has been set, otherwise zero. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ char *new_attrib; /* Pointer value to new attribute name */ int len; /* Length of attrib string */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* First look for axis attributes defined by the Frame class. Since a SpecFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent TestAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); result = (*parent_testattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignStdOfRest. */ /* --------------- */ } else if ( !strcmp( attrib, "alignstdofrest" ) ) { result = astTestAlignStdOfRest( this ); /* GeoLat. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had GeoLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( !strcmp( attrib, "geolat" ) ) { result = astTestAttrib( this, "obslat" ); /* GeoLon. */ /* ------- */ } else if ( !strcmp( attrib, "geolon" ) ) { result = astTestAttrib( this, "obslon" ); /* RefDec. */ /* ------- */ } else if ( !strcmp( attrib, "refdec" ) ) { result = astTestRefDec( this ); /* RefRA. */ /* ------ */ } else if ( !strcmp( attrib, "refra" ) ) { result = astTestRefRA( this ); /* RestFreq. */ /* --------- */ } else if ( !strcmp( attrib, "restfreq" ) ) { result = astTestRestFreq( this ); /* SourceVel. */ /* ---------- */ } else if ( !strcmp( attrib, "sourcevel" ) ) { result = astTestSourceVel( this ); /* SourceVRF */ /* --------- */ } else if ( !strcmp( attrib, "sourcevrf" ) ) { result = astTestSourceVRF( this ); /* SourceSys */ /* --------- */ } else if ( !strcmp( attrib, "sourcesys" ) ) { result = astTestSourceSys( this ); /* StdOfRest. */ /* ---------- */ } else if ( !strcmp( attrib, "stdofrest" ) ) { result = astTestStdOfRest( this ); /* SpecOrigin. */ /* --------- */ } else if ( !strcmp( attrib, "specorigin" ) ) { result = astTestSpecOrigin( this ); /* AlignSpecOffset */ /* --------------- */ } else if ( !strcmp( attrib, "alignspecoffset" ) ) { result = astTestAlignSpecOffset( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static double ToUnits( AstSpecFrame *this, const char *oldunit, double oldval, const char *method, int *status ){ /* * * Name: * ToUnits * Purpose: * Convert a supplied spectral value to the default units of the supplied * SpecFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double ToUnits( AstSpecFrame *this, const char *oldunit, double oldval, * const char *method, int *status ) * Class Membership: * SpecFrame member function * Description: * This function converts the supplied value from the supplied units to * the default units associated with the supplied SpecFrame's System. * Parameters: * this * Pointer to the SpecFrame. * oldunit * The units in which "oldval" is supplied. * oldval * The value to be converted. * method * Pointer to a string holding the name of the method to be * included in any error messages. * status * Pointer to the inherited status variable. * Returned Value: * The converted value. */ /* Local Variables: */ AstMapping *map; const char *defunit; double result; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get default units associated with the System attribute of the supplied SpecFrame, and find a Mapping from the old units to the default. */ defunit = DefUnit( astGetSystem( this ), method, "SpecFrame", status ); map = astUnitMapper( oldunit, defunit, NULL, NULL ); if( map ) { /* Use the Mapping to convert the supplied value. */ astTran1( map, 1, &oldval, 1, &result ); /* Free resources. */ map = astAnnul( map ); /* Report an error if no conversion is possible. */ } else if( astOK ){ astError( AST__BADUN, "%s(%s): Cannot convert the supplied attribute " "value from units of %s to %s.", status, method, astGetClass( this ), oldunit, defunit ); } /* Return the result */ return result; } static int ValidateSystem( AstFrame *this, AstSystemType system, const char *method, int *status ) { /* * * Name: * ValidateSystem * Purpose: * Validate a value for a Frame's System attribute. * Type: * Protected virtual function. * Synopsis: * #include "specframe.h" * int ValidateSystem( AstFrame *this, AstSystemType system, * const char *method, int *status ) * Class Membership: * SpecFrame member function (over-rides the 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 */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* If the value is out of bounds, report an error. */ if ( system < FIRST_SYSTEM || system > LAST_SYSTEM ) { astError( AST__AXIIN, "%s(%s): Bad value (%d) given for the System " "or AlignSystem attribute of a %s.", status, method, astGetClass( this ), (int) system, astGetClass( this ) ); /* Otherwise, return the supplied value. */ } else { result = system; } /* Return the result. */ return result; } static void VerifyAttrs( AstSpecFrame *this, const char *purp, const char *attrs, const char *method, int *status ) { /* * Name: * VerifyAttrs * Purpose: * Verify that usable attribute values are available. * Type: * Private function. * Synopsis: * #include "specframe.h" * void VerifyAttrs( AstSpecFrame *this, const char *purp, * const char *attrs, const char *method, int *status ) * Class Membership: * SpecFrame member function * Description: * This function tests each attribute listed in "attrs". It returns * without action if 1) an explicit value has been set for each attribute * or 2) the UseDefs attribute of the supplied SpecFrame is non-zero. * * If UseDefs is zero (indicating that default values should not be * used for attributes), and any of the named attributes does not have * an explicitly set value, then an error is reported. * Parameters: * this * Pointer to the SpecFrame. * purp * Pointer to a text string containing a message which will be * included in any error report. This shouldindicate the purpose * for which the attribute value is required. * attrs * A string holding a space separated list of attribute names. * method * A string holding the name of the calling method for use in error * messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *a; const char *desc; const char *p; int len; int set; int state; /* Check inherited status */ if( !astOK ) return; /* If the SpecFrame has a non-zero value for its UseDefs attribute, then all attributes are assumed to have usable values, since the defaults will be used if no explicit value has been set. So we only need to do any checks if UseDefs is zero. */ if( !astGetUseDefs( this ) ) { /* Stop compiler warnings about uninitialised variables */ a = NULL; desc = NULL; len = 0; set = 0; /* Loop round the "attrs" string identifying the start and length of each non-blank word in the string. */ state = 0; p = attrs; while( 1 ) { if( state == 0 ) { if( !isspace( *p ) ) { a = p; len = 1; state = 1; } } else { if( isspace( *p ) || !*p ) { /* The end of a word has just been reached. Compare it to each known attribute value. Get a flag indicating if the attribute has a set value, and a string describing the attribute.*/ if( len > 0 ) { if( !strncmp( "ObsLat", a, len ) ) { set = astTestObsLat( this ); desc = "observer's latitude"; } else if( !strncmp( "ObsLon", a, len ) ) { set = astTestObsLon( this ); desc = "observer's longitude"; } else if( !strncmp( "ObsAlt", a, len ) ) { set = astTestObsAlt( this ); desc = "observer's altitude"; } else if( !strncmp( "RefRA", a, len ) ) { set = astTestRefRA( this ); desc = "source RA"; } else if( !strncmp( "RefDec", a, len ) ) { set = astTestRefDec( this ); desc = "source Dec"; } else if( !strncmp( "RestFreq", a, len ) ) { set = astTestRestFreq( this ); desc = "rest frequency"; } else if( !strncmp( "SourceVel", a, len ) ) { set = astTestSourceVel( this ); desc = "source velocity"; } else if( !strncmp( "StdOfRest", a, len ) ) { set = astTestStdOfRest( this ); desc = "spectral standard of rest"; } else if( !strncmp( "Epoch", a, len ) ) { set = astTestEpoch( this ); desc = "epoch of observation"; } else { astError( AST__INTER, "VerifyAttrs(SpecFrame): " "Unknown attribute name \"%.*s\" supplied (AST " "internal programming error).", status, len, a ); } /* If the attribute does not have a set value, report an error. */ if( !set && astOK ) { astError( AST__NOVAL, "%s(%s): Cannot %s.", status, method, astGetClass( this ), purp ); astError( AST__NOVAL, "No value has been set for " "the AST \"%.*s\" attribute (%s).", status, len, a, desc ); } /* Continue the word search algorithm. */ } len = 0; state = 0; } else { len++; } } if( !*(p++) ) break; } } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* *att++ * Name: * AlignSpecOffset * Purpose: * Align SpecFrames using the offset coordinate system? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which controls how a SpecFrame * behaves when it is used (by c astFindFrame or astConvert) as a template to match another (target) f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) * SpecFrame. It determines whether alignment occurs between the offset * values defined by the current value of the SpecOffset attribute, or * between the corresponding absolute spectral values. * * The default value of zero results in the two SpecFrames being aligned * so that a given absolute spectral value in one is mapped to the same * absolute value in the other. A non-zero value results in the SpecFrames * being aligned so that a given offset value in one is mapped to the same * offset value in the other. * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ astMAKE_CLEAR(SpecFrame,AlignSpecOffset,alignspecoffset,-INT_MAX) astMAKE_GET(SpecFrame,AlignSpecOffset,int,0,( ( this->alignspecoffset != -INT_MAX ) ? this->alignspecoffset : 0 )) astMAKE_SET(SpecFrame,AlignSpecOffset,int,alignspecoffset,( value != 0 )) astMAKE_TEST(SpecFrame,AlignSpecOffset,( this->alignspecoffset != -INT_MAX )) /* *att++ * Name: * AlignStdOfRest * Purpose: * Standard of rest to use when aligning SpecFrames. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls how a SpecFrame behaves when it is used (by c astFindFrame or astConvert) as a template to match another (target) f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) * SpecFrame. It identifies the standard of rest in which alignment is * to occur. See the StdOfRest attribute for a desription of the values * which may be assigned to this attribute. The default AlignStdOfRest * value is "Helio" (heliographic). * c When astFindFrame or astConvert is used on two SpecFrames (potentially f When AST_FindFrame or AST_CONVERT is used on two SpecFrames (potentially * describing different spectral coordinate systems), it returns a Mapping * which can be used to transform a position in one SpecFrame into the * corresponding position in the other. The Mapping is made up of the * following steps in the indicated order: * * - Map values from the system used by the target (wavelength, * apparent radial velocity, etc) to the system specified by the * AlignSystem attribute, using the target's rest frequency if necessary. * * - Map these values from the target's standard of rest to the standard of * rest specified by the AlignStdOfRest attribute, using the Epoch, ObsLat, * ObsLon, ObsAlt, RefDec and RefRA attributes of the target to define the * two standards of rest. * * - Map these values from the standard of rest specified by the * AlignStdOfRest attribute, to the template's standard of rest, using the * Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the * template to define the two standards of rest. * * - Map these values from the system specified by the AlignSystem * attribute, to the system used by the template, using the template's * rest frequency if necessary. * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The AlignStdOfRest value has a value of AST__BADSOR when not set yielding a default of AST__HLSOR. */ astMAKE_TEST(SpecFrame,AlignStdOfRest,( this->alignstdofrest != AST__BADSOR )) astMAKE_CLEAR(SpecFrame,AlignStdOfRest,alignstdofrest,AST__BADSOR) astMAKE_GET(SpecFrame,AlignStdOfRest,AstStdOfRestType,AST__BADSOR,( ( this->alignstdofrest == AST__BADSOR ) ? AST__HLSOR : this->alignstdofrest ) ) /* Validate the AlignStdOfRest value being set and report an error if necessary. */ astMAKE_SET(SpecFrame,AlignStdOfRest,AstStdOfRestType,alignstdofrest,( ( ( value >= FIRST_SOR ) && ( value <= LAST_SOR ) ) ? value : ( astError( AST__ATTIN, "%s(%s): Bad value (%d) " "given for AlignStdOfRest attribute.", status, "astSetAlignStdOfRest", astGetClass( this ), (int) value ), /* Leave the value unchanged on error. */ this->alignstdofrest ) ) ) /* *att++ * Name: * RefDec * Purpose: * The declination of the reference point * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the FK5 J2000.0 declination of a reference * point on the sky. See the description of attribute RefRA for details. * The default RefDec is "0:0:0". * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The reference declination (FK5 J2000, radians). Clear the RefDec value by setting it to AST__BAD, which results in a default value of zero. Any value is acceptable. */ astMAKE_CLEAR(SpecFrame,RefDec,refdec,AST__BAD) astMAKE_GET(SpecFrame,RefDec,double,0.0,((this->refdec!=AST__BAD)?this->refdec:0.0)) astMAKE_SET(SpecFrame,RefDec,double,refdec,value) astMAKE_TEST(SpecFrame,RefDec,( this->refdec != AST__BAD )) /* *att++ * Name: * RefRA * Purpose: * The right ascension of the reference point * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute, together with the RefDec attribute, specifies the FK5 * J2000.0 coordinates of a reference point on the sky. For 1-dimensional * spectra, this should normally be the position of the source. For * spectral data with spatial coverage (spectral cubes, etc), this should * be close to centre of the spatial coverage. It is used to define the * correction for Doppler shift to be applied when using the c astFindFrame or astConvert f AST_FINDFRAME or AST_CONVERT * method to convert between different standards of rest. * * The SpecFrame class assumes this velocity correction is spatially * invariant. If a single SpecFrame is used (for instance, as a * component of a CmpFrame) to describe spectral values at different * points on the sky, then it is assumes that the doppler shift at any * spatial position is the same as at the reference position. The * maximum velocity error introduced by this assumption is of the order * of V*SIN(FOV), where FOV is the angular field of view, and V is the * relative velocity of the two standards of rest. As an example, when * correcting from the observers rest frame (i.e. the topocentric rest * frame) to the kinematic local standard of rest the maximum value of V * is about 20 km/s, so for 5 arc-minute field of view the maximum velocity * error introduced by the correction will be about 0.03 km/s. As another * example, the maximum error when correcting from the observers rest frame * to the local group is about 5 km/s over a 1 degree field of view. * * The RefRA and RefDec attributes are stored internally in radians, but * are converted to and from a string for access. The format "hh:mm:ss.ss" * is used for RefRA, and "dd:mm:ss.s" is used for RefDec. The methods c astSetRefPos and astGetRefPos may be used to access the values of f AST_SETREFPOS and AST_GETREFPOS may be used to access the value of * these attributes directly as unformatted values in radians. * * The default for RefRA is "0:0:0". * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The reference right ascension (FK5 J2000, radians). Clear the RefRA value by setting it to AST__BAD, which gives a default value of 0.0. Any value is acceptable. */ astMAKE_CLEAR(SpecFrame,RefRA,refra,AST__BAD) astMAKE_GET(SpecFrame,RefRA,double,0.0,((this->refra!=AST__BAD)?this->refra:0.0)) astMAKE_SET(SpecFrame,RefRA,double,refra,value) astMAKE_TEST(SpecFrame,RefRA,( this->refra != AST__BAD )) /* *att++ * Name: * RestFreq * Purpose: * The rest frequency. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute specifies the frequency corresponding to zero * velocity. It is used when converting between between velocity-based * coordinate systems and and other coordinate systems (such as frequency, * wavelength, energy, etc). The default value is 1.0E5 GHz. * * When setting a new value for this attribute, the new value can be * supplied either directly as a frequency, or indirectly as a wavelength * or energy, in which case the supplied value is converted to a frequency * before being stored. The nature of the supplied value is indicated by * appending text to the end of the numerical value indicating the units in * which the value is supplied. If the units are not specified, then the * supplied value is assumed to be a frequency in units of GHz. If the * supplied unit is a unit of frequency, the supplied value is assumed to * be a frequency in the given units. If the supplied unit is a unit of * length, the supplied value is assumed to be a (vacuum) wavelength. If * the supplied unit is a unit of energy, the supplied value is assumed to * be an energy. For instance, the following strings all result in * a rest frequency of around 1.4E14 Hz being used: "1.4E5", "1.4E14 Hz", * "1.4E14 s**-1", "1.4E5 GHz", "2.14E-6 m", "21400 Angstrom", "9.28E-20 J", * "9.28E-13 erg", "0.58 eV", etc. * * When getting the value of this attribute, the returned value is * always a frequency in units of GHz. * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The rest frequency (Hz). Clear the RestFreq value by setting it to AST__BAD, which gives 1.0E14 as the default value. Any value is acceptable. */ astMAKE_CLEAR(SpecFrame,RestFreq,restfreq,AST__BAD) astMAKE_GET(SpecFrame,RestFreq,double,1.0E14,((this->restfreq!=AST__BAD)?this->restfreq:1.0E14)) astMAKE_SET(SpecFrame,RestFreq,double,restfreq,value) astMAKE_TEST(SpecFrame,RestFreq,( this->restfreq != AST__BAD )) /* *att++ * Name: * SourceVel * Purpose: * The source velocity. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute (together with SourceSys, SourceVRF, RefRA and RefDec) * defines the "Source" standard of rest (see attribute StdOfRest). This is * a rest frame which is moving towards the position given by RefRA and * RefDec at a velocity given by SourceVel. A positive value means * the source is moving away from the observer. When a new value is * assigned to this attribute, the supplied value is assumed to refer * to the spectral system specified by the SourceSys attribute. For * instance, the SourceVel value may be supplied as a radio velocity, a * redshift, a beta factor, etc. Similarly, when the current value of * the SourceVel attribute is obtained, the returned value will refer * to the spectral system specified by the SourceSys value. If the * SourceSys value is changed, any value previously stored for the SourceVel * attribute will be changed automatically from the old spectral system * to the new spectral system. * * When setting a value for SourceVel, the value should be supplied in the * rest frame specified by the SourceVRF attribute. Likewise, when getting * the value of SourceVel, it will be returned in the rest frame specified * by the SourceVRF attribute. * * The default SourceVel value is zero. * Applicability: * SpecFrame * All SpecFrames have this attribute. * Notes: * - It is important to set an appropriate value for SourceVRF and * SourceSys before setting a value for SourceVel. If a new value is later * set for SourceVRF or SourceSys, the value stored for SourceVel will * simultaneously be changed to the new standard of rest or spectral * system. *att-- */ /* The source velocity (velocities are stored internally in m/s). Clear it by setting it to AST__BAD, which returns a default value of zero. Any value is acceptable. */ astMAKE_CLEAR(SpecFrame,SourceVel,sourcevel,AST__BAD) astMAKE_SET(SpecFrame,SourceVel,double,sourcevel,value) astMAKE_TEST(SpecFrame,SourceVel,( this->sourcevel != AST__BAD )) astMAKE_GET(SpecFrame,SourceVel,double,0.0,((this->sourcevel!=AST__BAD)?this->sourcevel:0.0)) /* *att++ * Name: * SourceVRF * Purpose: * Rest frame in which the source velocity is stored. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute identifies the rest frame in which the source * velocity or redshift is stored (the source velocity or redshift is * accessed using attribute SourceVel). When setting a new value for the * SourceVel attribute, the source velocity or redshift should be supplied * in the rest frame indicated by this attribute. Likewise, when getting * the value of the SourceVel attribute, the velocity or redshift will be * returned in this rest frame. * * If the value of SourceVRF is changed, the value stored for SourceVel * will be converted from the old to the new rest frame. * * The values which can be supplied are the same as for the StdOfRest * attribute (except that SourceVRF cannot be set to "Source"). The * default value is "Helio". * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The SourceVRF value has a value of AST__BADSOR when not set yielding a default of AST__HLSOR. */ astMAKE_TEST(SpecFrame,SourceVRF,( this->sourcevrf != AST__BADSOR )) astMAKE_GET(SpecFrame,SourceVRF,AstStdOfRestType,AST__BADSOR,( ( this->sourcevrf == AST__BADSOR ) ? AST__HLSOR : this->sourcevrf ) ) /* When clearing SourceVRF, convert the SourceVel value to heliocentric (but only if set)*/ astMAKE_CLEAR(SpecFrame,SourceVRF,sourcevrf,((astTestSourceVel( this )? (void)(astSetSourceVel( this, ConvertSourceVel( this, AST__HLSOR, astGetSourceSys( this ), status ) ),NULL): NULL),AST__BADSOR)) /* Validate the SourceVRF value being set and report an error if necessary. If OK, convert the stored SourceVel value into the new rest frame (but only if set)*/ astMAKE_SET(SpecFrame,SourceVRF,AstStdOfRestType,sourcevrf,( ( ( value >= FIRST_SOR ) && ( value <= LAST_SOR ) && value != AST__SCSOR ) ? (astTestSourceVel( this )? (void)(astSetSourceVel( this,ConvertSourceVel(this,value,astGetSourceSys( this ), status )),NULL): NULL), value:( astError( AST__ATTIN, "%s(%s): Bad value (%d) " "given for SourceVRF attribute.", status, "astSetSourceVRF", astGetClass( this ), (int) value ), /* Leave the value unchanged on error. */ this->sourcevrf ) ) ) /* *att++ * Name: * SourceSys * Purpose: * Spectral system in which the source velocity is stored. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute identifies the spectral system in which the * SourceVel attribute value (the source velocity) is supplied and * returned. It can be one of the following: * * - "VRAD" or "VRADIO": Radio velocity (km/s) * - "VOPT" or "VOPTICAL": Optical velocity (km/s) * - "ZOPT" or "REDSHIFT": Redshift (dimensionless) * - "BETA": Beta factor (dimensionless) * - "VELO" or "VREL": Apparent radial ("relativistic") velocity (km/s) * * When setting a new value for the SourceVel attribute, the source * velocity should be supplied in the spectral system indicated * by this attribute. Likewise, when getting the value of the SourceVel * attribute, the velocity will be returned in this spectral system. * * If the value of SourceSys is changed, the value stored for SourceVel * will be converted from the old to the new spectral systems. * * The default value is "VELO" (apparent radial velocity). * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The SourceSys value has a value of AST__BADSYS when not set yielding a default of AST__VREL. */ astMAKE_TEST(SpecFrame,SourceSys,( this->sourcesys != AST__BADSYSTEM )) astMAKE_GET(SpecFrame,SourceSys,AstSystemType,AST__BADSYSTEM,( ( this->sourcesys == AST__BADSYSTEM ) ? AST__VREL : this->sourcesys ) ) /* When clearing SourceSys, convert the SourceVel value to relativistic velocity (but only if set) */ astMAKE_CLEAR(SpecFrame,SourceSys,sourcesys,((astTestSourceVel( this )? (void)(astSetSourceVel( this, ConvertSourceVel( this, astGetSourceVRF( this ), AST__VREL, status ) ),NULL):NULL),AST__BADSYSTEM)) /* Validate the SourceSys value being set and report an error if necessary. If OK, convert the stored SourceVel value into the new rest frame (but only if set)*/ astMAKE_SET(SpecFrame,SourceSys,AstSystemType,sourcesys,( ( ( value == AST__VREL ) || ( value == AST__BETA ) || ( value == AST__VRADIO ) || ( value == AST__REDSHIFT ) || ( value == AST__VOPTICAL ) ) ? (astTestSourceVel( this )? (void)(astSetSourceVel( this, ConvertSourceVel( this, astGetSourceVRF( this ), value, status )),NULL):NULL), value: ( astError( AST__ATTIN, "%s(%s): Bad value (%d) " "given for SourceSys attribute.", status, "astSetSourceSys", astGetClass( this ), (int) value ), /* Leave the value unchanged on error. */ this->sourcesys ) ) ) /* *att++ * Name: * StdOfRest * Purpose: * Standard of rest. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute identifies the standard of rest to which the spectral * axis values of a SpecFrame refer, and may take any of the values * listed in the "Standards of Rest" section (below). * * The default StdOfRest value is "Helio". * Applicability: * SpecFrame * All SpecFrames have this attribute. * Standards of Rest: * The SpecFrame class supports the following StdOfRest values (all are * case-insensitive): * * - "Topocentric", "Topocent" or "Topo": The observers rest-frame (assumed * to be on the surface of the earth). Spectra recorded in this standard of * rest suffer a Doppler shift which varies over the course of a day * because of the rotation of the observer around the axis of the earth. * This standard of rest must be qualified using the ObsLat, ObsLon, * ObsAlt, Epoch, RefRA and RefDec attributes. * * - "Geocentric", "Geocentr" or "Geo": The rest-frame of the earth centre. * Spectra recorded in this standard of rest suffer a Doppler shift which * varies over the course of a year because of the rotation of the earth * around the Sun. This standard of rest must be qualified using the Epoch, * RefRA and RefDec attributes. * * - "Barycentric", "Barycent" or "Bary": The rest-frame of the solar-system * barycentre. Spectra recorded in this standard of rest suffer a Doppler * shift which depends both on the velocity of the Sun through the Local * Standard of Rest, and on the movement of the planets through the solar * system. This standard of rest must be qualified using the Epoch, RefRA * and RefDec attributes. * * - "Heliocentric", "Heliocen" or "Helio": The rest-frame of the Sun. * Spectra recorded in this standard of rest suffer a Doppler shift which * depends on the velocity of the Sun through the Local Standard of Rest. * This standard of rest must be qualified using the RefRA and RefDec * attributes. * * - "LSRK", "LSR": The rest-frame of the kinematical Local Standard of * Rest. Spectra recorded in this standard of rest suffer a Doppler shift * which depends on the velocity of the kinematical Local Standard of Rest * through the galaxy. This standard of rest must be qualified using the * RefRA and RefDec attributes. * * - "LSRD": The rest-frame of the dynamical Local Standard of Rest. Spectra * recorded in this standard of rest suffer a Doppler shift which depends * on the velocity of the dynamical Local Standard of Rest through the * galaxy. This standard of rest must be qualified using the RefRA and * RefDec attributes. * * - "Galactic", "Galactoc" or "Gal": The rest-frame of the galactic centre. * Spectra recorded in this standard of rest suffer a Doppler shift which * depends on the velocity of the galactic centre through the local group. * This standard of rest must be qualified using the RefRA and RefDec * attributes. * * - "Local_group", "Localgrp" or "LG": The rest-frame of the local group. * This standard of rest must be qualified using the RefRA and RefDec * attributes. * * - "Source", or "src": The rest-frame of the source. This standard of * rest must be qualified using the RefRA, RefDec and SourceVel attributes. * * Where more than one alternative System value is shown above, the * first of these will be returned when an enquiry is made. *att-- */ /* The StdOfRest value has a value of AST__BADSOR when not set yielding a default of AST__HLSOR. */ astMAKE_TEST(SpecFrame,StdOfRest,( this->stdofrest != AST__BADSOR )) astMAKE_GET(SpecFrame,StdOfRest,AstStdOfRestType,AST__BADSOR,( ( this->stdofrest == AST__BADSOR ) ? AST__HLSOR : this->stdofrest ) ) /* *att++ * Name: * SpecOrigin * Purpose: * The zero point for SpecFrame axis values * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This specifies the origin from which all spectral values are measured. * The default value (zero) results in the SpecFrame describing * absolute spectral values in the system given by the System attribute * (e.g. frequency, velocity, etc). If a SpecFrame is to be used to * describe offset from some origin, the SpecOrigin attribute * should be set to hold the required origin value. The SpecOrigin value * stored inside the SpecFrame structure is modified whenever SpecFrame * attribute values are changed so that it refers to the original spectral * position. * * When setting a new value for this attribute, the supplied value is assumed * to be in the system, units and standard of rest described by the SpecFrame. * Likewise, when getting the value of this attribute, the value is returned * in the system, units and standard of rest described by the SpecFrame. If * any of these attributes are changed, then any previously stored SpecOrigin * value will also be changed so that refers to the new system, units or * standard of rest. * Applicability: * SpecFrame * All SpecFrames have this attribute. *att-- */ /* The spec origin, stored internally in the default units associated with the current System value. Clear the SpecOrigin value by setting it to AST__BAD, which gives 0.0 as the default value. Any value is acceptable. */ astMAKE_CLEAR(SpecFrame,SpecOrigin,specorigin,AST__BAD) astMAKE_GET(SpecFrame,SpecOrigin,double,0.0,((this->specorigin!=AST__BAD)?this->specorigin:0.0)) astMAKE_SET(SpecFrame,SpecOrigin,double,specorigin,value) astMAKE_TEST(SpecFrame,SpecOrigin,( this->specorigin != AST__BAD )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SpecFrame objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SpecFrame 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: */ AstSpecFrame *in; /* Pointer to input SpecFrame */ AstSpecFrame *out; /* Pointer to output SpecFrame */ char *usedunit; /* Pointer to an element of usedunits array */ int i; /* Loop count */ int nused; /* Size of "usedunits" array */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SpecFrames. */ in = (AstSpecFrame *) objin; out = (AstSpecFrame *) objout; /* Nullify the pointers stored in the output object since these will currently be pointing at the input data (since the output is a simple byte-for-byte copy of the input). Otherwise, the input data could be freed by accidient if the output object is deleted due to an error occuring in this function. */ out->usedunits = NULL; /* Store the last used units in the output SpecMap. */ if( in && in->usedunits ) { nused = in->nuunits; out->usedunits = astMalloc( nused*sizeof( char * ) ); if( out->usedunits ) { for( i = 0; i < nused; i++ ) { usedunit = in->usedunits[ i ]; if( usedunit ) { out->usedunits[ i ] = astStore( NULL, usedunit, strlen( usedunit ) + 1 ); } else { out->usedunits[ i ] = NULL; } } } } /* If an error has occurred, free the output resources. */ if( !astOK ) Delete( (AstObject *) out, status ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SpecFrame objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SpecFrame 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: */ AstSpecFrame *this; int i; /* Release the memory referred to in the SpecFrame structure. */ this = (AstSpecFrame *) obj; if( this && this->usedunits ) { for( i = 0; i < this->nuunits; i++ ) { this->usedunits[ i ] = astFree( this->usedunits[ i ] ); } this->usedunits = astFree( this->usedunits ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SpecFrame 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 SpecFrame class to an output Channel. * Parameters: * this * Pointer to the SpecFrame 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 Variables: */ AstSpecFrame *this; /* Pointer to the SpecFrame structure */ AstStdOfRestType sor; /* StdOfRest attribute value */ AstSystemType sys; /* Spectral system value */ char buff[ 20 ]; /* Buffer for item name */ char comm[ 50 ]; /* Buffer for comment */ const char *sval; /* Pointer to string value */ double dval; /* Double value */ int i; /* Loop count */ int ival; /* int value */ int j; /* Loop count */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SpecFrame structure. */ this = (AstSpecFrame *) this_object; /* Write out values representing the instance variables for the SpecFrame 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. */ /* StdOfRest. */ /* ---------- */ set = TestStdOfRest( this, status ); sor = set ? GetStdOfRest( this, status ) : astGetStdOfRest( this ); /* If set, convert explicitly to a string for the external representation. */ sval = ""; if ( set ) { if ( astOK ) { sval = StdOfRestString( sor, status ); /* Report an error if the StdOfRest value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid standard of rest " "identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) sor ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "stdofrest" ); } /* Write out the value. */ astWriteString( channel, "SoR", set, 1, sval, "Standard of rest" ); /* AlignStdOfRest. */ /* --------------- */ set = TestAlignStdOfRest( this, status ); sor = set ? GetAlignStdOfRest( this, status ) : astGetAlignStdOfRest( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = StdOfRestString( sor, status ); /* Report an error if the StdOfRest value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid alignment standard " "of rest identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) sor ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "alignstdofrest" ); } /* Write out the value. */ astWriteString( channel, "AlSoR", set, 0, sval, "Alignment standard of rest" ); /* RefRA. */ /* ------ */ set = TestRefRA( this, status ); dval = set ? GetRefRA( this, status ) : astGetRefRA( this ); astWriteDouble( channel, "RefRA", set, 0, dval, "Reference RA (rads, FK5 J2000)" ); /* RefDec. */ /* ------- */ set = TestRefDec( this, status ); dval = set ? GetRefDec( this, status ) : astGetRefDec( this ); astWriteDouble( channel, "RefDec", set, 0, dval, "Reference Dec (rads, FK5 J2000)" ); /* RestFreq. */ /* --------- */ set = TestRestFreq( this, status ); dval = set ? GetRestFreq( this, status ) : astGetRestFreq( this ); astWriteDouble( channel, "RstFrq", set, 0, dval, "Rest frequency (Hz)" ); /* SourceVel. */ /* ---------- */ set = TestSourceVel( this, status ); dval = set ? GetSourceVel( this, status ) : astGetSourceVel( this ); astWriteDouble( channel, "SrcVel", set, 0, dval, "Source velocity (m/s)" ); /* SourceVRF. */ /* ---------- */ set = TestSourceVRF( this, status ); sor = set ? GetSourceVRF( this, status ) : astGetSourceVRF( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = StdOfRestString( sor, status ); /* Report an error if the value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid source velocity " "rest frame identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) sor ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "sourcevrf" ); } /* Write out the value. */ astWriteString( channel, "SrcVRF", set, 0, sval, "Source velocity rest frame" ); /* SourceSys. */ /* ---------- */ set = TestSourceSys( this, status ); sys = set ? GetSourceSys( this, status ) : astGetSourceSys( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = SystemString( (AstFrame *) this, sys, status ); /* Report an error if the value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid source velocity " "spectral system identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) sys ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "sourcesys" ); } /* Write out the value. */ astWriteString( channel, "SrcSys", set, 0, sval, "Source velocity spectral system" ); /* AlignSpecOffset. */ /* ---------------- */ set = TestAlignSpecOffset( this, status ); ival = set ? GetAlignSpecOffset( this, status ) : astGetAlignSpecOffset( this ); astWriteInt( channel, "AlSpOf", set, 0, ival, ival ? "Align in offset coords" : "Align in system coords" ); /* UsedUnits */ /* --------- */ if( this->usedunits ) { for( i = 0; i < this->nuunits; i++ ) { if( this->usedunits[ i ] ) { sprintf( buff, "U%s", astSystemString( this, (AstSystemType) i )); for( j = 2; j < strlen( buff ); j++ ) buff[ j ] = tolower( buff[ j ] ); sprintf( comm, "Preferred units for %s", SystemLabel( (AstSystemType) i, status ) ); astWriteString( channel, buff, 1, 0, this->usedunits[ i ], comm ); } } } /* SpecOrigin. */ /* ----------- */ set = TestSpecOrigin( this, status ); dval = set ? GetSpecOrigin( this, status ) : astGetSpecOrigin( this ); if( dval != AST__BAD ) { astWriteDouble( channel, "SpOrg", set, 0, dval, "Spec offset" ); } } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASpecFrame and astCheckSpecFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SpecFrame,Frame) astMAKE_CHECK(SpecFrame) AstSpecFrame *astSpecFrame_( const char *options, int *status, ...) { /* *+ * Name: * astSpecFrame * Purpose: * Create a SpecFrame. * Type: * Protected function. * Synopsis: * #include "specframe.h" * AstSpecFrame *astSpecFrame( const char *options, int *status, ... ) * Class Membership: * SpecFrame constructor. * Description: * This function creates a new SpecFrame and optionally initialises its * attributes. * Parameters: * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new SpecFrame. 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 SpecFrame. * 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 SpecFrame constructor which * is available via the protected interface to the SpecFrame class. * A public interface is provided by the astSpecFrameId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *um; /* Mapping from default to actual units */ AstSpecFrame *new; /* Pointer to new SpecFrame */ AstSystemType s; /* System */ const char *u; /* Units string */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SpecFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecFrame( NULL, sizeof( AstSpecFrame ), !class_init, &class_vtab, "SpecFrame" ); /* 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 SpecFrame's attributes. */ va_start( args, status ); astVSet( new, options, NULL, args ); va_end( args ); /* Check the Units are appropriate for the System. */ u = astGetUnit( new, 0 ); s = astGetSystem( new ); um = astUnitMapper( DefUnit( s, "astSpecFrame", "SpecFrame", status ), u, NULL, NULL ); if( um ) { um = astAnnul( um ); } else { astError( AST__BADUN, "astSpecFrame: Inappropriate units (%s) " "specified for a %s axis.", status, u, SystemLabel( s, status ) ); } /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new SpecFrame. */ return new; } AstSpecFrame *astInitSpecFrame_( void *mem, size_t size, int init, AstSpecFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSpecFrame * Purpose: * Initialise a SpecFrame. * Type: * Protected function. * Synopsis: * #include "specframe.h" * AstSpecFrame *astInitSpecFrame( void *mem, size_t size, int init, * AstFrameVtab *vtab, const char *name ) * Class Membership: * SpecFrame initialiser. * Description: * This function is provided for use by class implementations to * initialise a new SpecFrame object. It allocates memory (if * necessary) to accommodate the SpecFrame plus any additional data * associated with the derived class. It then initialises a * SpecFrame 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 SpecFrame at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SpecFrame is to be * created. This must be of sufficient size to accommodate the * SpecFrame data (sizeof(SpecFrame)) 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 SpecFrame (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 SpecFrame structure, so a valid value must be supplied * even if not required for allocating memory. * init * A logical flag indicating if the SpecFrame'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 SpecFrame. * 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). * Returned Value: * A pointer to the new SpecFrame. * 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: */ AstSpecFrame *new; /* Pointer to the new SpecFrame */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSpecFrameVtab( vtab, name ); /* Initialise a 1D Frame structure (the parent class) as the first component within the SpecFrame structure, allocating memory if necessary. */ new = (AstSpecFrame *) astInitFrame( mem, size, 0, (AstFrameVtab *) vtab, name, 1 ); if ( astOK ) { /* Initialise the SpecFrame data. */ /* ----------------------------- */ /* Initialise all attributes to their "undefined" values. */ new->alignstdofrest = AST__BADSOR; new->refdec = AST__BAD; new->refra = AST__BAD; new->restfreq = AST__BAD; new->sourcevel = AST__BAD; new->sourcevrf = AST__BADSOR; new->sourcesys = AST__BADSYSTEM; new->stdofrest = AST__BADSOR; new->nuunits = 0; new->usedunits = NULL; new->specorigin = AST__BAD; new->alignspecoffset = -INT_MAX; /* 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; } AstSpecFrame *astLoadSpecFrame_( void *mem, size_t size, AstSpecFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSpecFrame * Purpose: * Load a SpecFrame. * Type: * Protected function. * Synopsis: * #include "specframe.h" * AstSpecFrame *astLoadSpecFrame( void *mem, size_t size, * AstSpecFrameVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * SpecFrame loader. * Description: * This function is provided to load a new SpecFrame 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 * SpecFrame structure in this memory, using data read from the * input Channel. * Parameters: * mem * A pointer to the memory into which the SpecFrame is to be * loaded. This must be of sufficient size to accommodate the * SpecFrame data (sizeof(SpecFrame)) 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 SpecFrame (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 SpecFrame 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(AstSpecFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SpecFrame. If this is NULL, a pointer * to the (static) virtual function table for the SpecFrame 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 "SpecFrame" is used instead. * Returned Value: * A pointer to the new SpecFrame. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSpecFrame *new; /* Pointer to the new SpecFrame */ char buff[ 20 ]; /* Buffer for item name */ char *sval; /* Pointer to string value */ double obslat; /* Value for ObsLat attribute */ double obslon; /* Get a pointer to the thread specific global data structure. */ /* Value for ObsLon attribute */ int i; /* Loop count */ int j; /* Loop count */ int nc; /* String length */ int sys; /* System value */ 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 SpecFrame. In this case the SpecFrame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSpecFrame ); vtab = &class_vtab; name = "SpecFrame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSpecFrameVtab( 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 SpecFrame. */ 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, "SpecFrame" ); /* 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. */ /* StdOfRest. */ /* ---------- */ /* Set the default and read the external representation as a string. */ new->stdofrest = AST__BADSOR; sval = astReadString( channel, "sor", NULL ); /* If a value was read, convert from a string to a StdOfRest code. */ if ( sval ) { if ( astOK ) { new->stdofrest = StdOfRestCode( sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->stdofrest == AST__BADSOR ) { astError( AST__ATTIN, "astRead(%s): Invalid standard of rest description " "\"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* AlignStdOfRest. */ /* --------------- */ /* Set the default and read the external representation as a string. */ new->alignstdofrest = AST__BADSOR; sval = astReadString( channel, "alsor", NULL ); /* If a value was read, convert from a string to a StdOfRest code. */ if ( sval ) { if ( astOK ) { new->alignstdofrest = StdOfRestCode( sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->alignstdofrest == AST__BADSOR ) { astError( AST__ATTIN, "astRead(%s): Invalid alignment standard of rest " "description \"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* GeoLat. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had a GeoLat attribute (now ObsLat is used instead). */ if( !astTestObsLat( new ) ) { obslat = astReadDouble( channel, "geolat", AST__BAD ); if ( obslat != AST__BAD ) astSetObsLat( new, obslat ); } /* GeoLon. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which SpecFrame had a GeoLon attribute (now ObsLon is used instead). */ if( !astTestObsLon( new ) ) { obslon = astReadDouble( channel, "geolon", AST__BAD ); if ( obslon != AST__BAD ) astSetObsLon( new, obslon ); } /* RefRA. */ /* ------ */ new->refra = astReadDouble( channel, "refra", AST__BAD ); if ( TestRefRA( new, status ) ) SetRefRA( new, new->refra, status ); /* RefDec. */ /* ------- */ new->refdec = astReadDouble( channel, "refdec", AST__BAD ); if ( TestRefDec( new, status ) ) SetRefDec( new, new->refdec, status ); /* RestFreq. */ /* --------- */ new->restfreq = astReadDouble( channel, "rstfrq", AST__BAD ); if ( TestRestFreq( new, status ) ) SetRestFreq( new, new->restfreq, status ); /* AlignSpecOffset */ /* --------------- */ new->alignspecoffset = astReadInt( channel, "alspof", -INT_MAX ); if ( TestAlignSpecOffset( new, status ) ) SetAlignSpecOffset( new, new->alignspecoffset, status ); /* SourceVel. */ /* ---------- */ new->sourcevel = astReadDouble( channel, "srcvel", AST__BAD ); if ( TestSourceVel( new, status ) ) SetSourceVel( new, new->sourcevel, status ); /* SourceVRF */ /* --------- */ /* Set the default and read the external representation as a string. */ new->sourcevrf = AST__BADSOR; sval = astReadString( channel, "srcvrf", NULL ); /* If a value was read, convert from a string to a StdOfRest code. */ if ( sval ) { if ( astOK ) { new->sourcevrf = StdOfRestCode( sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->sourcevrf == AST__BADSOR ) { astError( AST__ATTIN, "astRead(%s): Invalid source velocity rest frame " "description \"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* SourceSys */ /* --------- */ /* Set the default and read the external representation as a string. */ new->sourcesys = AST__BADSYSTEM; sval = astReadString( channel, "srcsys", NULL ); /* If a value was read, convert from a string to a System code. */ if ( sval ) { if ( astOK ) { new->sourcesys = SystemCode( (AstFrame *) new, sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->sourcesys == AST__BADSYSTEM ) { astError( AST__ATTIN, "astRead(%s): Invalid source velocity spectral system " "description \"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* UsedUnits */ /* --------- */ new->nuunits = 0; new->usedunits = NULL; for( sys = FIRST_SYSTEM; sys <= LAST_SYSTEM; sys++ ) { nc = sprintf( buff, "u%s", astSystemString( new, (AstSystemType) sys )); for( j = 0; j < nc; j++ ) buff[ j ] = tolower( buff[ j ] ); sval = astReadString( channel, buff, NULL ); if( sval ) { if( (int) sys >= new->nuunits ) { new->usedunits = astGrow( new->usedunits, sys + 1, sizeof(char *) ); if( astOK ) { for( i = new->nuunits; i < sys + 1; i++ ) new->usedunits[ i ] = NULL; new->nuunits = sys + 1; } } else { new->usedunits[ sys ] = astFree( new->usedunits[ sys ] ); } if( astOK ) { new->usedunits[ sys ] = astStore( new->usedunits[ sys ], sval, strlen( sval ) + 1 ); } sval = astFree( sval); } } /* SpecOrigin. */ /* --------- */ new->specorigin = astReadDouble( channel, "sporg", AST__BAD ); if ( TestSpecOrigin( new, status ) ) SetSpecOrigin( new, new->specorigin, status ); /* If an error occurred, clean up by deleting the new SpecFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SpecFrame pointer. */ return new; } /* 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 astGetRefPos_( AstSpecFrame *this, AstSkyFrame *frm, double *lon, double *lat, int *status ){ if ( !astOK ) return; (**astMEMBER(this,SpecFrame,GetRefPos))(this,frm,lon,lat, status ); } void astSetRefPos_( AstSpecFrame *this, AstSkyFrame *frm, double lon, double lat, int *status ){ if ( !astOK ) return; (**astMEMBER(this,SpecFrame,SetRefPos))(this,frm,lon,lat, status ); } void astSetStdOfRest_( AstSpecFrame *this, AstStdOfRestType value, int *status ){ if ( !astOK ) return; (**astMEMBER(this,SpecFrame,SetStdOfRest))(this,value, status ); } void astClearStdOfRest_( AstSpecFrame *this, int *status ){ if ( !astOK ) return; (**astMEMBER(this,SpecFrame,ClearStdOfRest))(this, 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. */ AstSpecFrame *astSpecFrameId_( const char *, ... ); /* Special interface function implementations. */ /* ------------------------------------------- */ AstSpecFrame *astSpecFrameId_( const char *options, ... ) { /* *++ * Name: c astSpecFrame f AST_SPECFRAME * Purpose: * Create a SpecFrame. * Type: * Public function. * Synopsis: c #include "specframe.h" c AstSpecFrame *astSpecFrame( const char *options, ... ) f RESULT = AST_SPECFRAME( OPTIONS, STATUS ) * Class Membership: * SpecFrame constructor. * Description: * This function creates a new SpecFrame and optionally initialises * its attributes. * * A SpecFrame is a specialised form of one-dimensional Frame which * represents various coordinate systems used to describe positions within * an electro-magnetic spectrum. The particular coordinate system to be * used is specified by setting the SpecFrame's System attribute (the * default is wavelength) qualified, as necessary, by other attributes * such as the rest frequency, the standard of rest, the epoch of * observation, etc (see the description of the System attribute for * details). * * By setting a value for thr SpecOrigin attribute, a SpecFrame can be made * to represent offsets from a given spectral position, rather than absolute * Parameters: 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 SpecFrame. 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 SpecFrame. 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 astSpecFrame() f AST_SPECFRAME = INTEGER * A pointer to the new SpecFrame. * Examples: c frame = astSpecFrame( "" ); f FRAME = AST_SPECFRAME( ' ', STATUS ) * Creates a SpecFrame to describe the default wavelength spectral * coordinate system. The RestFreq attribute (rest frequency) is * unspecified, so it will not be possible to align this SpecFrame * with another SpecFrame on the basis of a velocity-based system. The * standard of rest is also unspecified. This means that alignment * will be possible with other SpecFrames, but no correction will be * made for Doppler shift caused by change of rest frame during the * alignment. c frame = astSpecFrame( "System=VELO, RestFreq=1.0E15, StdOfRest=LSRK" ); f FRAME = AST_SPECFRAME( 'System=VELO, RestFreq=1.0E15, StdOfRest=LSRK', STATUS ) * Creates a SpecFrame describing a apparent radial velocity ("VELO") axis * with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured * in the kinematic Local Standard of Rest ("LSRK"). Since the * source position has not been specified (using attributes RefRA and * RefDec), it will only be possible to align this SpecFrame with * other SpecFrames which are also measured in the LSRK standard of * rest. * Notes: * - When conversion between two SpecFrames is requested (as when c supplying SpecFrames to astConvert), f supplying SpecFrames AST_CONVERT), * account will be taken of the nature of the spectral coordinate systems * they represent, together with any qualifying rest frequency, standard * of rest, epoch values, etc. The AlignSystem and AlignStdOfRest * attributes will also be taken into account. The results will therefore * fully reflect the relationship between positions measured in the two * systems. In addition, any difference in the Unit attributes of the two * systems will also be taken into account. * - 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 astSpecFrame constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astSpecFrame_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astSpecFrame_ directly, so it must be a * re-implementation of it in all respects, except for the final * conversion of the result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *um; /* Mapping from default to actual units */ AstSpecFrame *new; /* Pointer to new SpecFrame */ AstSystemType s; /* System */ const char *u; /* Units string */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ astGET_GLOBALS(NULL); /* Get a pointer to the thread specific global data structure. */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SpecFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSpecFrame( NULL, sizeof( AstSpecFrame ), !class_init, &class_vtab, "SpecFrame" ); /* 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 SpecFrame's attributes. */ va_start( args, options ); astVSet( new, options, NULL, args ); va_end( args ); /* Check the Units are appropriate for the System. */ u = astGetUnit( new, 0 ); s = astGetSystem( new ); um = astUnitMapper( DefUnit( s, "astSpecFrame", "SpecFrame", status ), u, NULL, NULL ); if( um ) { um = astAnnul( um ); } else { astError( AST__BADUN, "astSpecFrame: Inappropriate units (%s) " "specified for a %s axis.", status, u, SystemLabel( s, status ) ); } /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return an ID value for the new SpecFrame. */ return astMakeId( new ); } ast-8.3.0/config.h.in0000664000175000017500000000676213004147326011272 00000000000000/* config.h.in. Generated from configure.ac by autoheader. */ /* use external PAL and ERFA libraries */ #undef EXTERNAL_PAL /* Define to 1 if you have the `backtrace' function. */ #undef HAVE_BACKTRACE /* Define to 1 if you have the declaration of `isfinite', and to 0 if you don't. */ #undef HAVE_DECL_ISFINITE /* Define to 1 if you have the declaration of `isnan', and to 0 if you don't. */ #undef HAVE_DECL_ISNAN /* Define to 1 if you have the header file. */ #undef HAVE_DLFCN_H /* Define to 1 if you have the header file. */ #undef HAVE_EXECINFO_H /* Define to 1 if the system has the type `int64_t'. */ #undef HAVE_INT64_T /* Define to 1 if you have the header file. */ #undef HAVE_INTTYPES_H /* Define to 1 if you have the `isfinite' function. */ #undef HAVE_ISFINITE /* Define to 1 if you have the `isnan' function. */ #undef HAVE_ISNAN /* Define to 1 if you have the `pthread' library (-lpthread). */ #undef HAVE_LIBPTHREAD /* Define to 1 if the system has the type `long double'. */ #undef HAVE_LONG_DOUBLE /* Define to 1 if you have the header file. */ #undef HAVE_MEMORY_H /* The sscanf shows the non-ANSI behaviour reported by Bill Joye */ #undef HAVE_NONANSI_SSCANF /* Define to 1 if the Fortran compiler supports the VAX %LOC extension */ #undef HAVE_PERCENTLOC /* Use the starmem library for memory management */ #undef HAVE_STAR_MEM_H /* Define to 1 if you have the header file. */ #undef HAVE_STDARG_H /* Define to 1 if you have the header file. */ #undef HAVE_STDINT_H /* Define to 1 if you have the header file. */ #undef HAVE_STDLIB_H /* Define to 1 if you have the `strerror_r' function. */ #undef HAVE_STRERROR_R /* Define to 1 if you have the header file. */ #undef HAVE_STRINGS_H /* Define to 1 if you have the header file. */ #undef HAVE_STRING_H /* Define to 1 if you have the `strtok_r' function. */ #undef HAVE_STRTOK_R /* Define to 1 if you have the header file. */ #undef HAVE_SYS_STAT_H /* Define to 1 if you have the header file. */ #undef HAVE_SYS_TYPES_H /* Define to 1 if the system has the type `uint64_t'. */ #undef HAVE_UINT64_T /* Define to 1 if you have the header file. */ #undef HAVE_UNISTD_H /* Define to 1 if you have the header file. */ #undef HAVE_VARARGS_H /* Define to 1 if you have the `vsnprintf' function. */ #undef HAVE_VSNPRINTF /* Define to the sub-directory in which libtool stores uninstalled libraries. */ #undef LT_OBJDIR /* enable AST memory leak debugging functions in memory.c */ #undef MEM_DEBUG /* Name of package */ #undef PACKAGE /* Define to the address where bug reports for this package should be sent. */ #undef PACKAGE_BUGREPORT /* Define to the full name of this package. */ #undef PACKAGE_NAME /* Define to the full name and version of this package. */ #undef PACKAGE_STRING /* Define to the one symbol short name of this package. */ #undef PACKAGE_TARNAME /* Define to the home page for this package. */ #undef PACKAGE_URL /* Define to the version of this package. */ #undef PACKAGE_VERSION /* The size of `long', as computed by sizeof. */ #undef SIZEOF_LONG /* The size of `long long', as computed by sizeof. */ #undef SIZEOF_LONG_LONG /* The size of `void*', as computed by sizeof. */ #undef SIZEOF_VOIDP /* Define to 1 if you have the ANSI C header files. */ #undef STDC_HEADERS /* Type of Fortran CNF TRAIL argument */ #undef TRAIL_TYPE /* Version number of package */ #undef VERSION ast-8.3.0/fregion.c0000664000175000017500000002160013004147321011023 00000000000000/* *+ * Name: * fregion.c * Purpose: * Define a FORTRAN 77 interface to the AST Region class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Region class. * Routines Defined: * AST_NEGATE * AST_ISAREGION * AST_MAPREGION * AST_GETREGIONBOUNDS * AST_GETREGIONFRAME * AST_GETREGIONFRAMESET * AST_OVERLAP * AST_SETUNC * AST_GETUNC * AST_SHOWMESH * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-MAR-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "region.h" /* C interface to the Region class */ /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_SUBROUTINE(ast_negate)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_NEGATE", NULL, 0 ); astWatchSTATUS( astNegate( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_setunc)( INTEGER(THIS), INTEGER(UNC), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(UNC) astAt( "AST_SETUNC", NULL, 0 ); astWatchSTATUS( astSetUnc( astI2P( *THIS ), astI2P( *UNC ) ); ) } F77_LOGICAL_FUNCTION(ast_isaregion)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAREGION", NULL, 0 ); astWatchSTATUS( RESULT = astIsARegion( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_getregionframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETREGIONFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetRegionFrame( astI2P( *THIS ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_getregionframeset)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETREGIONFRAMESET", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetRegionFrameSet( astI2P( *THIS ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_getunc)( INTEGER(THIS), LOGICAL(DEF), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_LOGICAL(DEF) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETUNC", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetUnc( astI2P( *THIS ), F77_ISTRUE( *DEF ) ? 1 : 0 ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_mapregion)( INTEGER(REG), INTEGER(MAP), INTEGER(FRM), INTEGER(STATUS) ) { GENPTR_INTEGER(REG) GENPTR_INTEGER(MAP) GENPTR_INTEGER(FRM) F77_INTEGER_TYPE(RESULT); astAt( "AST_MAPREGION", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astMapRegion( astI2P( *REG ), astI2P( *MAP ), astI2P( *FRM ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_overlap)( INTEGER(THIS), INTEGER(THAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(THAT) F77_INTEGER_TYPE(RESULT); astAt( "AST_OVERLAP", NULL, 0 ); astWatchSTATUS( RESULT = astOverlap( astI2P( *THIS ), astI2P( *THAT ) ); ) return RESULT; } /* AST_MASK requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_MASK(f,F,Ftype,X,Xtype) \ F77_INTEGER_FUNCTION(ast_mask##f)( INTEGER(THIS), \ INTEGER(MAP), \ LOGICAL(INSIDE), \ INTEGER(NDIM), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ Ftype##_ARRAY(IN), \ Ftype(VAL), \ INTEGER(STATUS) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_INTEGER(MAP) \ GENPTR_LOGICAL(INSIDE) \ GENPTR_INTEGER(NDIM) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_##Ftype##_ARRAY(IN) \ GENPTR_##Ftype(VAL) \ GENPTR_INTEGER(STATUS) \ \ F77_INTEGER_TYPE RESULT; \ \ astAt( "AST_MASK"#F, NULL, 0 ); \ astWatchSTATUS( \ \ RESULT = astMask##X( astI2P( *THIS ), astI2P( *MAP ), \ F77_ISTRUE( *INSIDE ) ? 1 : 0, *NDIM, \ LBND, UBND, (Xtype *) IN, *VAL ); \ ) \ return RESULT; \ } /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_MASK(d,D,DOUBLE,D,double) MAKE_AST_MASK(r,R,REAL,F,float) MAKE_AST_MASK(i,I,INTEGER,I,int) MAKE_AST_MASK(ui,UI,INTEGER,UI,unsigned int) MAKE_AST_MASK(s,S,WORD,S,short int) MAKE_AST_MASK(us,US,UWORD,US,unsigned short int) MAKE_AST_MASK(w,W,WORD,S,short int) MAKE_AST_MASK(uw,UW,UWORD,US,unsigned short int) MAKE_AST_MASK(b,B,BYTE,B,signed char) MAKE_AST_MASK(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_MASK F77_SUBROUTINE(ast_getregionbounds)( INTEGER(THIS), DOUBLE(LBND), DOUBLE(UBND), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE(XOUT) GENPTR_DOUBLE(YOUT) astAt( "AST_GETREGIONBOUNDS", NULL, 0 ); astWatchSTATUS( astGetRegionBounds( astI2P( *THIS ), LBND, UBND ); ) } F77_SUBROUTINE(ast_showmesh)( INTEGER(THIS), LOGICAL(FORMAT), CHARACTER(TTL), INTEGER(STATUS) TRAIL(TTL) ) { GENPTR_INTEGER(THIS) GENPTR_LOGICAL(FORMAT) GENPTR_CHARACTER(TTL) char *ttl; astAt( "AST_SHOWMESH", NULL, 0 ); astWatchSTATUS( ttl = astString( TTL, TTL_length ); astShowMesh( astI2P( *THIS ), F77_ISTRUE( *FORMAT ) ? 1 : 0, ttl ); ttl = astFree( ttl ); ) } F77_SUBROUTINE(ast_getregionpoints)( INTEGER(THIS), INTEGER(MAXPOINT), INTEGER(MAXCOORD), INTEGER(NPOINT), DOUBLE_ARRAY(POINTS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(MAXPOINT) GENPTR_INTEGER(MAXCOORD) GENPTR_INTEGER(NPOINT) GENPTR_DOUBLE_ARRAY(POINTS) astAt( "AST_GETREGIONPOINT", NULL, 0 ); astWatchSTATUS( astGetRegionPoints( astI2P( *THIS ), *MAXPOINT, *MAXCOORD, NPOINT, POINTS ); ) } F77_SUBROUTINE(ast_getregionmesh)( INTEGER(THIS), LOGICAL(SURFACE), INTEGER(MAXPOINT), INTEGER(MAXCOORD), INTEGER(NPOINT), DOUBLE_ARRAY(POINTS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_LOGICAL(SURFACE) GENPTR_INTEGER(MAXPOINT) GENPTR_INTEGER(MAXCOORD) GENPTR_INTEGER(NPOINT) GENPTR_DOUBLE_ARRAY(POINTS) astAt( "AST_GETREGIONMESH", NULL, 0 ); astWatchSTATUS( astGetRegionMesh( astI2P( *THIS ), F77_ISTRUE( *SURFACE ), *MAXPOINT, *MAXCOORD, NPOINT, POINTS ); ) } ast-8.3.0/skyframe.h0000664000175000017500000004705613004147321011235 00000000000000#if !defined( SKYFRAME_INCLUDED ) /* Include this file only once */ #define SKYFRAME_INCLUDED /* *+ * Name: * skyframe.h * Type: * C include file. * Purpose: * Define the interface to the SkyFrame class. * Invocation: * #include "skyframe.h" * Description: * This include file defines the interface to the SkyFrame class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * Inheritance: * The SkyFrame class inherits from the Frame class. * Macros: * None. * Type Definitions: * Public: * AstSkyFrame * SkyFrame object type. * Protected: * AstSkyFrameVtab * SkyFrame virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 4-MAR-1996 (RFWS): * Original version. * 24-MAY-1996 (RFWS): * Tidied up, etc. * 24-SEP-1996 (RFWS): * Added I/O facilities. * 16-JUL-1997 (RFWS): * Added Projection attribute. * 26-FEB-1998 (RFWS): * Over-ride the astUnformat method. * 3-APR-2001 (DSB): * Added "Unknown" option for the System attribute. Added read-only * attributes LatAxis and LonAxis. * 10-OCT-2002 (DSB): * Moved definitions of macros for SkyFrame system values into * this file from skyframe.c. * 15-NOV-2002 (DSB): * Move the System attribute from this class to the parent (Frame) * class. * 8-JAN-2003 (DSB): * Added protected astInitSkyFrameVtab method. * 19-APR-2004 (DSB): * Added SkyRef, SkyRefIs, SkyRefP and AlignOffset attributes. * Simplified prologue. * 2-DEC-2004 (DSB): * Added System "J2000" * 22-FEB-2006 (DSB): * Added Local Apparent Sidereal Time to the SkyFrame structure. * 3-OCT-2006 (DSB): * Added Equation of Equinoxes to the SkyFrame structure. * 6-OCT-2006 (DSB): * Removed Equation of Equinoxes from the SkyFrame structure. * Added dut1 to the SkyFrame structure. * Added Dut1 accessor methods. * 14-OCT-2006 (DSB): * Moved dut1 to the Frame class. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "frame.h" /* Parent Frame class */ /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* Define values for the different values of the SkyRefIs attribute. */ #define AST__BAD_REF 0 #define AST__POLE_REF 1 #define AST__ORIGIN_REF 2 #define AST__IGNORED_REF 3 /* Values used to represent different System attribute values. */ #define AST__FK4 1 #define AST__FK4_NO_E 2 #define AST__FK5 3 #define AST__GAPPT 4 #define AST__ECLIPTIC 5 #define AST__GALACTIC 6 #define AST__SUPERGALACTIC 7 #define AST__ICRS 8 #define AST__HELIOECLIPTIC 9 #define AST__J2000 10 #define AST__UNKNOWN 11 #define AST__AZEL 12 /* Define constants used to size global arrays in this module. */ /* Define other numerical constants for use in this module. */ #define AST__SKYFRAME_GETATTRIB_BUFF_LEN 200 #define AST__SKYFRAME_GETFORMAT_BUFF_LEN 50 #define AST__SKYFRAME_GETLABEL_BUFF_LEN 40 #define AST__SKYFRAME_GETSYMBOL_BUFF_LEN 20 #define AST__SKYFRAME_GETTITLE_BUFF_LEN 200 #endif /* Type Definitions. */ /* ================= */ /* Cached LAST look-up table. */ /* -------------------------- */ /* Holds a list of epoch values and the corresponding Local Apparent Sidereal Time values. Also holds the observatory position and DUT1 value used when calculating the LAST values. */ typedef struct AstSkyLastTable { double obslat; /* ObsLat at which LAST values were calculated */ double obslon; /* ObsLon at which LAST values were calculated */ double obsalt; /* ObsAlt at which LAST values were calculated */ double dut1; /* Dut1 values at which LAST values were calculated */ int nentry; /* Number of entries in the epoch and last arrays */ double *epoch; /* Array of epoch values */ double *last; /* Array of LAST values */ } AstSkyLastTable; /* SkyFrame structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSkyFrame { /* Attributes inherited from the parent class. */ AstFrame frame; /* Parent class structure */ /* Attributes specific to objects in this class. */ char *projection; /* Description of sky projection */ double equinox; /* Modified Julian Date of mean equinox */ int neglon; /* Display negative longitude values? */ double skytol; /* Smallest significant distance */ int alignoffset; /* Align SkyFrame in offset coords? */ int skyrefis; /* Nature of offset coord system */ double skyref[ 2 ]; /* Origin or pole of offset coord system */ double skyrefp[ 2 ]; /* Point on primary meridian of offset coord system */ double last; /* Local Apparent Sidereal Time */ double eplast; /* Epoch used to calculate "last" */ double klast; /* Ratio of solar to sidereal time */ double diurab; /* Magnitude of diurnal aberration vector */ } AstSkyFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSkyFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstMapping *(* SkyOffsetMap)( AstSkyFrame *, int * ); const char *(* GetProjection)( AstSkyFrame *, int * ); double (* GetEquinox)( AstSkyFrame *, int * ); int (* GetNegLon)( AstSkyFrame *, int * ); int (* GetAsTime)( AstSkyFrame *, int, int * ); int (* GetIsLatAxis)( AstSkyFrame *, int, int * ); int (* GetIsLonAxis)( AstSkyFrame *, int, int * ); int (* GetLatAxis)( AstSkyFrame *, int * ); int (* GetLonAxis)( AstSkyFrame *, int * ); int (* TestAsTime)( AstSkyFrame *, int, int * ); int (* TestEquinox)( AstSkyFrame *, int * ); int (* TestNegLon)( AstSkyFrame *, int * ); int (* TestProjection)( AstSkyFrame *, int * ); void (* ClearAsTime)( AstSkyFrame *, int, int * ); void (* ClearEquinox)( AstSkyFrame *, int * ); void (* ClearNegLon)( AstSkyFrame *, int * ); void (* ClearProjection)( AstSkyFrame *, int * ); void (* SetAsTime)( AstSkyFrame *, int, int, int * ); void (* SetEquinox)( AstSkyFrame *, double, int * ); void (* SetNegLon)( AstSkyFrame *, int, int * ); void (* SetProjection)( AstSkyFrame *, const char *, int * ); int (* GetSkyRefIs)( AstSkyFrame *, int * ); int (* TestSkyRefIs)( AstSkyFrame *, int * ); void (* ClearSkyRefIs)( AstSkyFrame *, int * ); void (* SetSkyRefIs)( AstSkyFrame *, int, int * ); double (* GetSkyTol)( AstSkyFrame *, int * ); int (* TestSkyTol)( AstSkyFrame *, int * ); void (* ClearSkyTol)( AstSkyFrame *, int * ); void (* SetSkyTol)( AstSkyFrame *, double, int * ); double (* GetSkyRef)( AstSkyFrame *, int, int * ); int (* TestSkyRef)( AstSkyFrame *, int, int * ); void (* ClearSkyRef)( AstSkyFrame *, int, int * ); void (* SetSkyRef)( AstSkyFrame *, int, double, int * ); double (* GetSkyRefP)( AstSkyFrame *, int, int * ); int (* TestSkyRefP)( AstSkyFrame *, int, int * ); void (* ClearSkyRefP)( AstSkyFrame *, int, int * ); void (* SetSkyRefP)( AstSkyFrame *, int, double, int * ); int (* GetAlignOffset)( AstSkyFrame *, int * ); int (* TestAlignOffset)( AstSkyFrame *, int * ); void (* ClearAlignOffset)( AstSkyFrame *, int * ); void (* SetAlignOffset)( AstSkyFrame *, int, int * ); } AstSkyFrameVtab; #if defined(THREAD_SAFE) /* The AstSkyFrameGlobals structure makes a forward reference to the AstTimeFrame structure which is not defined here (since the timeframe.h file includes skyframe.h). Hence make a preliminary definition available now. */ struct AstTimeFrame; /* Define a structure holding all data items that are global within this class. */ typedef struct AstSkyFrameGlobals { AstSkyFrameVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__SKYFRAME_GETATTRIB_BUFF_LEN + 1 ]; char GetFormat_Buff[ AST__SKYFRAME_GETFORMAT_BUFF_LEN + 1 ]; char GetLabel_Buff[ AST__SKYFRAME_GETLABEL_BUFF_LEN + 1 ]; char GetSymbol_Buff[ AST__SKYFRAME_GETSYMBOL_BUFF_LEN + 1 ]; char GetTitle_Buff[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; char GetTitle_Buff2[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; struct AstTimeFrame *TDBFrame; struct AstTimeFrame *LASTFrame; } AstSkyFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SkyFrame) /* Check class membership */ astPROTO_ISA(SkyFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstSkyFrame *astSkyFrame_( const char *, int *, ...); #else AstSkyFrame *astSkyFrameId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSkyFrame *astInitSkyFrame_( void *, size_t, int, AstSkyFrameVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitSkyFrameVtab_( AstSkyFrameVtab *, const char *, int * ); /* Loader. */ AstSkyFrame *astLoadSkyFrame_( void *, size_t, AstSkyFrameVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitSkyFrameGlobals_( AstSkyFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstMapping *astSkyOffsetMap_( AstSkyFrame *, int * ); #if defined(astCLASS) /* Protected */ const char *astGetProjection_( AstSkyFrame *, int * ); double astGetEquinox_( AstSkyFrame *, int * ); int astGetNegLon_( AstSkyFrame *, int * ); int astGetAsTime_( AstSkyFrame *, int, int * ); int astGetIsLatAxis_( AstSkyFrame *, int, int * ); int astGetIsLonAxis_( AstSkyFrame *, int, int * ); int astGetLatAxis_( AstSkyFrame *, int * ); int astGetLonAxis_( AstSkyFrame *, int * ); int astTestAsTime_( AstSkyFrame *, int, int * ); int astTestEquinox_( AstSkyFrame *, int * ); int astTestNegLon_( AstSkyFrame *, int * ); int astTestProjection_( AstSkyFrame *, int * ); void astClearAsTime_( AstSkyFrame *, int, int * ); void astClearEquinox_( AstSkyFrame *, int * ); void astClearNegLon_( AstSkyFrame *, int * ); void astClearProjection_( AstSkyFrame *, int * ); void astSetAsTime_( AstSkyFrame *, int, int, int * ); void astSetEquinox_( AstSkyFrame *, double, int * ); void astSetNegLon_( AstSkyFrame *, int, int * ); void astSetProjection_( AstSkyFrame *, const char *, int * ); int astGetAlignOffset_( AstSkyFrame *, int * ); int astTestAlignOffset_( AstSkyFrame *, int * ); void astClearAlignOffset_( AstSkyFrame *, int * ); void astSetAlignOffset_( AstSkyFrame *, int, int * ); int astGetSkyRefIs_( AstSkyFrame *, int * ); int astTestSkyRefIs_( AstSkyFrame *, int * ); void astClearSkyRefIs_( AstSkyFrame *, int * ); void astSetSkyRefIs_( AstSkyFrame *, int, int * ); double astGetSkyRef_( AstSkyFrame *, int, int * ); int astTestSkyRef_( AstSkyFrame *, int, int * ); void astClearSkyRef_( AstSkyFrame *, int, int * ); void astSetSkyRef_( AstSkyFrame *, int, double, int * ); double astGetSkyRefP_( AstSkyFrame *, int, int * ); int astTestSkyRefP_( AstSkyFrame *, int, int * ); void astClearSkyRefP_( AstSkyFrame *, int, int * ); void astSetSkyRefP_( AstSkyFrame *, int, double, int * ); double astGetSkyTol_( AstSkyFrame *, int * ); int astTestSkyTol_( AstSkyFrame *, int * ); void astClearSkyTol_( AstSkyFrame *, int * ); void astSetSkyTol_( AstSkyFrame *, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSkyFrame(this) astINVOKE_CHECK(SkyFrame,this,0) #define astVerifySkyFrame(this) astINVOKE_CHECK(SkyFrame,this,1) /* Test class membership. */ #define astIsASkyFrame(this) astINVOKE_ISA(SkyFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astSkyFrame astINVOKE(F,astSkyFrame_) #else #define astSkyFrame astINVOKE(F,astSkyFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSkyFrame(mem,size,init,vtab,name) \ astINVOKE(O,astInitSkyFrame_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSkyFrameVtab(vtab,name) astINVOKE(V,astInitSkyFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSkyFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSkyFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ #define astSkyOffsetMap(this) \ astINVOKE(O,astSkyOffsetMap_(astCheckSkyFrame(this),STATUS_PTR)) /* Interfaces to protected member functions. */ /* ----------------------------------------- */ /* Here we make use of astCheckSkyFrame to validate SkyFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearAsTime(this,axis) \ astINVOKE(V,astClearAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astClearEquinox(this) \ astINVOKE(V,astClearEquinox_(astCheckSkyFrame(this),STATUS_PTR)) #define astClearNegLon(this) \ astINVOKE(V,astClearNegLon_(astCheckSkyFrame(this),STATUS_PTR)) #define astClearProjection(this) \ astINVOKE(V,astClearProjection_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetAsTime(this,axis) \ astINVOKE(V,astGetAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astGetEquinox(this) \ astINVOKE(V,astGetEquinox_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetNegLon(this) \ astINVOKE(V,astGetNegLon_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetIsLatAxis(this,axis) \ astINVOKE(V,astGetIsLatAxis_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astGetIsLonAxis(this,axis) \ astINVOKE(V,astGetIsLonAxis_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astGetLatAxis(this) \ astINVOKE(V,astGetLatAxis_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetLonAxis(this) \ astINVOKE(V,astGetLonAxis_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetProjection(this) \ astINVOKE(V,astGetProjection_(astCheckSkyFrame(this),STATUS_PTR)) #define astSetAsTime(this,axis,value) \ astINVOKE(V,astSetAsTime_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) #define astSetEquinox(this,value) \ astINVOKE(V,astSetEquinox_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astSetNegLon(this,value) \ astINVOKE(V,astSetNegLon_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astSetProjection(this,value) \ astINVOKE(V,astSetProjection_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astTestAsTime(this,axis) \ astINVOKE(V,astTestAsTime_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astTestEquinox(this) \ astINVOKE(V,astTestEquinox_(astCheckSkyFrame(this),STATUS_PTR)) #define astTestNegLon(this) \ astINVOKE(V,astTestNegLon_(astCheckSkyFrame(this),STATUS_PTR)) #define astTestProjection(this) \ astINVOKE(V,astTestProjection_(astCheckSkyFrame(this),STATUS_PTR)) #define astClearAlignOffset(this) astINVOKE(V,astClearAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetAlignOffset(this) astINVOKE(V,astGetAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) #define astSetAlignOffset(this,value) astINVOKE(V,astSetAlignOffset_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astTestAlignOffset(this) astINVOKE(V,astTestAlignOffset_(astCheckSkyFrame(this),STATUS_PTR)) #define astClearSkyRefIs(this) astINVOKE(V,astClearSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetSkyRefIs(this) astINVOKE(V,astGetSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) #define astSetSkyRefIs(this,value) astINVOKE(V,astSetSkyRefIs_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astTestSkyRefIs(this) astINVOKE(V,astTestSkyRefIs_(astCheckSkyFrame(this),STATUS_PTR)) #define astClearSkyRef(this,axis) astINVOKE(V,astClearSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astGetSkyRef(this,axis) astINVOKE(V,astGetSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astSetSkyRef(this,axis,value) astINVOKE(V,astSetSkyRef_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) #define astTestSkyRef(this,axis) astINVOKE(V,astTestSkyRef_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astClearSkyRefP(this,axis) astINVOKE(V,astClearSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astGetSkyRefP(this,axis) astINVOKE(V,astGetSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astSetSkyRefP(this,axis,value) astINVOKE(V,astSetSkyRefP_(astCheckSkyFrame(this),axis,value,STATUS_PTR)) #define astTestSkyRefP(this,axis) astINVOKE(V,astTestSkyRefP_(astCheckSkyFrame(this),axis,STATUS_PTR)) #define astClearSkyTol(this) astINVOKE(V,astClearSkyTol_(astCheckSkyFrame(this),STATUS_PTR)) #define astGetSkyTol(this) astINVOKE(V,astGetSkyTol_(astCheckSkyFrame(this),STATUS_PTR)) #define astSetSkyTol(this,value) astINVOKE(V,astSetSkyTol_(astCheckSkyFrame(this),value,STATUS_PTR)) #define astTestSkyTol(this) astINVOKE(V,astTestSkyTol_(astCheckSkyFrame(this),STATUS_PTR)) #endif #endif ast-8.3.0/fsphmap.c0000664000175000017500000000570313004147321011036 00000000000000/* *+ * Name: * fsphmap.c * Purpose: * Define a FORTRAN 77 interface to the AST SphMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the SphMap class. * Routines Defined: * AST_ISASPHMAP * AST_SPHMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 25-OCT-1996 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "sphmap.h" /* C interface to the SphMap class */ F77_LOGICAL_FUNCTION(ast_isasphmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASPHMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsASphMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_sphmap)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_SPHMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astSphMap( "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/frame.h0000664000175000017500000020052113004147321010472 00000000000000#if !defined( FRAME_INCLUDED ) /* Include this file only once */ #define FRAME_INCLUDED /* *+ * Name: * frame.h * Type: * C include file. * Purpose: * Define the interface to the Frame class. * Invocation: * #include "frame.h" * Description: * This include file defines the interface to the Frame class and * provides the type definitions, function prototypes and macros, etc. * needed to use this class. * * A Frame object encapsulates information about a coordinate * system, including its axes. It may also act as a "template" to * be matched against another Frame object. This process determines * whether it is possible to perform a coordinate transformation * between the two coordinates systems they describe. * Inheritance: * The Frame class inherits from the Mapping class. * Attributes Over-Ridden: * Nin (integer, readonly) * The Frame class sets this value to be equal to the number of * Frame axes. * Nout (integer, readonly) * The Frame class sets this value to be equal to the number of * Frame axes. * New Attributes Defined: * AlignSystem (string) * This attribute takes a value to identify the coordinate system * in which the Frame should be aligned with other Frames. * Digits [or Digits(axis)] (integer) * Specifies how many digits of precision are required by * default when a coordinate value for a Frame is formatted * (e.g. using the astFormat method). The Digits value acts as a * default only and is over-ridden if a Format string is * specified for an axis explicitly. * * The default Digits value for a Frame is 7. This attribute * normally applies to all the Frame's axes, but reference may * be made to a particular axis by adding an axis subscript * (e.g. Digits(1)). If a value is set for an individual axis, * it will over-ride the Digits value for the Frame as a whole * when formatting values for that axis. * Direction(axis) (integer) * A boolean value which specifies how coordinate values for * each Frame axis should be displayed (e.g. in graphs). By * default, it has the value one, indicating that they should be * shown in the conventional sense (i.e. increasing left to * right for an abscissa and bottom to top for an ordinate). If * set to zero, this attribute indicates that the direction * should be reversed (as would often be done for an * astronomical magnitude or a right ascension axis, for * example). * Epoch (double) * This value is used to qualify coordinate systems by * giving the moment in time when the coordinates are known to * be correct. Often, this will be the date of observation. * Format(axis) (string) * Specifies the format to be used to display coordinate values * for each Frame axis (i.e. to convert them from binary to * character form). The interpretation of this string (e.g. by * derived classes) is left to the astFormat method which, in * turn will invoke the astAxisFormat for the Axis object that * describes each axis. By default, the Frame class supplies an * Axis class object for each axis and this will interpret this * parameter as a C "printf" format string which should be * capable of formatting a single coordinate value stored as a * double (e.g. "%1.7G"). If no Format string is set, the * default format is based on the value of the Digits attribute. * Label(axis) (string) * Specifies the label to be attached to each Frame axis when it * is represented in (e.g.) a graph. It is intended purely for * interpretation by human readers and not by software. The * default supplied by the Frame class is the string "Axis ", * where is 1, 2, etc. for each successive axis. * MatchEnd (integer) * A boolean value that controls how a Frame behaves when used * as a template to match another Frame. If it is zero and a * template Frame matches a target frame which has a different * number of axes, then the axes wich occur first in the target * frame will be matched and any trailing axes in either the * target or template will be discarded (if necessary). If it is * non-zero, however, the last axes in each frame will be * matched and any un-matched leading axes will be discarded * instead. The default value supplied by the Frame class is * zero. * MaxAxes (integer) * Specifies the maximum number of axes in a target Frame that * can be matched when using the Frame as a template. Normally, * by default, this value is equal to the number of Frame axes, * so that a Frame will only match another Frame with the same * number of axes as itself. By setting a different value, * however, Frames with different numbers of axes may be matched * (the MatchEnd attribute then determines which of the * individual axes are matched). * * When setting this value, the value of the MinAxes attribute * may be silently changed so that it remains consistent with * (i.e. does not exceed) the new value. The default value may * also be reduced if necessary to remain consistent with the * MinAxes value. * MinAxes (integer) * Specifies the minimum number of axes in a target Frame that * can be matched when using the Frame as a template. Normally, * by default, this value is equal to the number of Frame axes, * so that a Frame will only match another Frame with the same * number of axes as itself. By setting a different value, * however, Frames with different numbers of axes may be matched * (the MatchEnd attribute then determines which of the * individual axes are matched). * * When setting this value, the value of the MaxAxes attribute * may be silently changed so that it remains consistent with * (i.e. is not less than) the new value. The default value may * also be reduced if necessary to remain consistent with the * MaxAxes value. * Domain (string) * A string which may be used to identify the physical domain to * which a Frame applies and used as an additional key when * matching a target Frame with a template. If the Domain * attribute in the template Frame is set, then only target * frames with the same Domain value will be matched. If a * Domain is not set in the template Frame, the target Frame's * Domain value will be ignored and has no effect on * matching. The default value supplied by the Frame class is an * empty string. Domain values are automatically converted to * upper case and all white space is removed before use. * Naxes (integer) * A read-only attribute that gives the number of axes in a * Frame (i.e. the number of dimensions of the space which the * Frame describes). This value is determined when the Frame is * created. * Permute (integer) * A boolean value which specifies whether the axis order of a * target Frame may be permuted in order to obtain a match with * a template. If this value is set to zero in the template * Frame, it will only match a target if it can do so without * changing the order of its axes. The default value supplied by * the Frame class is 1 (i.e. allow axis permutations). * PreserveAxes (integer) * A boolean value which determines how the "result" Frame is * produced whan a target frame is matched by a template. If * this value is zero in the template Frame, then the result * Frame will have the same number of axes as the template. If * it is non-zero, however, the axes of the target Frame will be * preserved, so that the result Frame will have the same number * of axes as the target. The default supplied by the Frame * class is zero (i.e. target axes are not preserved). * * The main use for this attribute is when the MaxAxes and/or * MinAxes attributes have been set to search for a Frame which * may have a different number of axes from the template. For * example, if a 2-dimensional template Frame matches a * 3-dimensional target Frame, then by default the result is * 2-dimensional and the last axis (normally) will be * discarded. However, if the template's PreserveAxes value is * non-zero, the result will instead be 3-dimensional to * correspond with the target Frame. * Symbol(axis) (string) * Specifies the symbol to be used to represent coordinate * values for each Frame axis in "short form", such as in * algebraic expressions where a full description of the axis * would be inappropriate. Examples include "RA" and "Dec" (for * Right Ascension and Declination). * * The default supplied by the Frame class is the string * "", where is 1, 2, etc. for successive axes, * and is the value of the Frame's Domain attribute * (with any white space replaced by underscores and truncated * if necessary so that the final string does not exceed 15 * characters). If no Domain value has been set, "x" is used as * the value in constructing this default string. * System (string) * This attribute takes a value to identify the coordinate system * used to describe positions within the domain of the Frame. * Title (string) * Specifies a string to be used as a title on (e.g.) graphs to * describe the coordinate system which the Frame * represents. Examples would be "Detector Coordinates" or * "Galactic Coordinates". This string is intended solely for * interpretation by human readers and not by software. The * default supplied by the Frame class is "-D Coordinate * System", where is the number of Frame axes. * Unit(axis) (string) * Describes the units used to represent coordinate values on * each Frame axis. The default supplied by the Frame class is * an empty string. * Methods Over-Ridden: * Public: * astGetNin * Get the number of input coordinates for a Frame. * astGetNout * Get the number of output coordinates for a Frame. * astTransform * Use a Frame to transform a set of points. * Protected: * astClearAttrib * Clear an attribute value for a Frame. * astGetAttrib * Get an attribute value for a Frame. * astReportPoints * Report the effect of transforming a set of points using a Frame. * astSetAttrib * Set an attribute value for a Frame. * astTestAttrib * Test if an attribute value has been set for a Frame. * New Methods Defined: * Public: * astAngle * Calculate the angle between three points. * astAxAngle * Find the angle from an axis to a line through two points. * astAxDistance * Calculate the distance between two axis values * astAxOffset * Calculate an offset along an axis * astConvert * Determine how to convert between two coordinate systems. * astDistance * Calculate the distance between two points. * astFindFrame * Find a coordinate system with specified characteristics * astFormat * Format a coordinate value for a Frame axis. * astNorm * Normalise a set of Frame coordinates. * astOffset * Calculate an offset along a geodesic curve. * astOffset2 * Calculate an offset along a geodesic curve for a 2D Frame. * astPermAxes * Permute the order of a Frame's axes. * astPickAxes * Create a new Frame by picking axes from an existing one. * astResolve * Resolve a vector into two orthogonal components. * astUnformat * Read a formatted coordinate value for a Frame axis. * Protected: * astAbbrev * Abbreviate a formatted Frame axis value by skipping * leading fields. * astCheckPerm * Check that an array contains a valid permutation. * astClearDigits * Clear the Digits attribute for a Frame. * astClearDirection * Clear the Direction attribute for a Frame axis. * astClearDomain * Clear the Domain attribute for a Frame. * astClearFormat * Clear the Format attribute for a Frame axis. * astClearLabel * Clear the Label attribute for a Frame axis. * astClearMatchEnd * Clear the MatchEnd attribute for a Frame. * astClearMaxAxes * Clear the MaxAxes attribute for a Frame. * astClearMinAxes * Clear the MinAxes attribute for a Frame. * astClearPermute * Clear the Permute attribute for a Frame. * astClearPreserveAxes * Clear the PreserveAxes attribute for a Frame. * astClearSymbol * Clear the Symbol attribute for a Frame axis. * astClearSystem * Clear the value of the System attribute for a Frame. * astClearTitle * Clear the Title attribute for a Frame. * astClearUnit * Clear the Unit attribute for a Frame axis. * astConvertX * Determine how to convert between two coordinate systems. * astFields * Identify the fields within a formatted Frame axis value. * astCentre * Find a "nice" central value for tabulating Frame axis values. * astGap * Find a "nice" gap for tabulating Frame axis values. * astGetAxis * Obtain a pointer to a specified Axis from a Frame. * astGetDigits * Get the value of the Digits attribute for a Frame. * astGetDirection * Get the value of the Direction attribute for a Frame axis. * astGetDomain * Get a pointer to the Domain attribute for a Frame. * astGetFormat * Get a pointer to the Format attribute for a Frame axis. * astGetLabel * Get a pointer to the Label attribute for a Frame axis. * astGetMatchEnd * Get the value of the MatchEnd attribute for a Frame. * astGetMaxAxes * Get the value of the MaxAxes attribute for a Frame. * astGetMinAxes * Get the value of the MinAxes attribute for a Frame. * astGetNaxes * Determine how many axes a Frame has. * astGetPerm * Access the axis permutation array for a Frame. * astGetPermute * Get the value of the Permute attribute for a Frame. * astGetPreserveAxes * Get the value of the PreserveAxes attribute for a Frame. * astGetSymbol * Get a pointer to the Symbol attribute for a Frame axis. * astGetSystem * Get the value of the System attribute for a Frame. * astGetTitle * Get a pointer to the Title attribute for a Frame. * astGetUnit * Get a pointer to the Unit attribute for a Frame axis. * astIsUnitFrame * Returns a flag indicating if a Frame is equivalent to a UnitMap. * astMatch * Determine if conversion is possible between two coordinate systems. * astOverlay * Overlay the attributes of a template Frame on to another Frame. * astPrimaryFrame * Uniquely identify a primary Frame and one of its axes. * astResolvePoints * Resolve many vectors into two orthogonal components. * astSetAxis * Set a new Axis for a Frame. * astSetDigits * Set the value of the Digits attribute for a Frame. * astSetDirection * Set the value of the Direction attribute for a Frame axis. * astSetDomain * Set the value of the Domain attribute for a Frame. * astSetFormat * Set the value of the Format attribute for a Frame axis. * astSetLabel * Set the value of the Label attribute for a Frame axis. * astSetMatchEnd * Set the value of the MatchEnd attribute for a Frame. * astSetMaxAxes * Set the value of the MaxAxes attribute for a Frame. * astSetMinAxes * Set the value of the MinAxes attribute for a Frame. * astSetPermute * Set the value of the Permute attribute for a Frame. * astSetPreserveAxes * Set the value of the PreserveAxes attribute for a Frame. * astSetSymbol * Set the value of the Symbol attribute for a Frame axis. * astSetSystem * Set the value of the System attribute for a Frame. * astSetTitle * Set the value of the Title attribute for a Frame. * astSetUnit * Set the value of the Unit attribute for a Frame axis. * astSubFrame * Select axes from a Frame and convert to the new coordinate system. * astTestDigits * Test whether a value has been set for the Digits attribute of a * Frame. * astTestDirection * Test whether a value has been set for the Direction attribute of a * Frame axis. * astTestDomain * Test whether a value has been set for the Domain attribute of a * Frame. * astTestFormat * Test whether a value has been set for the Format attribute of a * Frame axis. * astTestLabel * Test whether a value has been set for the Label attribute of a * Frame axis. * astTestMatchEnd * Test whether a value has been set for the MatchEnd attribute of a * Frame. * astTestMaxAxes * Test whether a value has been set for the MaxAxes attribute of a * Frame. * astTestMinAxes * Test whether a value has been set for the MinAxes attribute of a * Frame. * astTestPermute * Test whether a value has been set for the Permute attribute of a * Frame. * astTestPreserveAxes * Test whether a value has been set for the PreserveAxes attribute of * a Frame. * astTestSymbol * Test whether a value has been set for the Symbol attribute of a * Frame axis. * astTestSystem * Test whether a value has been set for the System attribute of a * Frame. * astTestTitle * Test whether a value has been set for the Title attribute of a * Frame. * astTestUnit * Test whether a value has been set for the Unit attribute of a Frame * axis. * astValidateAxis * Validate and permute a Frame's axis index. * astValidateAxisSelection * Check that a set of axes selected from a Frame is valid. * astValidateSystem * Validate a Frame's System attribute. * astSystemString * Return a string representation of a System code. * astSystemCode * Return a code for a string representation of a System value * Other Class Functions: * Public: * astFrame * Create a Frame. * astIsAFrame * Test class membership. * Protected: * astCheckFrame * Validate class membership. * astInitFrame * Initialise a Frame. * astInitFrameVtab * Initialise the virtual function table for the Frame class. * astLoadFrame * Load a Frame. * Macros: * Public: * None. * Protected: * AST__BADSYSTEM * A "bad" (undefined) value for the System attribute. * Type Definitions: * Public: * AstFrame * Frame object type. * Protected: * AstFrameVtab * Frame virtual function table type. * AstSystemType * Enumerated type used for the System attribute. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: B.S. Berry (Starlink) * History: * 1-MAR-1996 (RFWS): * Original version. * 25-APR-1996 (RFWS): * Tidied up, etc. * 11-SEP-1996 (RFWS): * Added astGap (written by DSB). * 10-JUN-1997 (RFWS): * Revised astConvert and added astFindFrame. * 15-FEB-1998 (RFWS): * Added astUnformat. * 21-JUN-2001 (DSB): * Added astAngle and astOffset2. * 29-AUG-2001 (DSB): * Added astAxDistance and astAxOffset. * 4-SEP-2001 (DSB): * Added astResolve. * 9-SEP-2001 (DSB): * Added astBear. * 21-SEP-2001 (DSB): * Replace astBear with astAxAngle. * 15-NOV-2002 (DSB): * Moved System and Epoch attributes from SkyFrame into this class. * Added AlignSystem attribute. * 8-JAN-2003 (DSB): * Added protected astInitFrameVtab method. * 24-JAN-2004 (DSB): * o Added astFields. * o Added argument "fmt" to astAbbrev. * 24-JUN-2004 (DSB): * Remove unused entry "void (* SetMatchRange)( AstFrame *, int, int );" * from AstFrameVtab structure. * 9-NOV-2004 (DSB): * Added protected astIsAUnitFrame method. * 12-AUG-2005 (DSB): * Added ObsLat and ObsLon attributes. * 14-OCT-2006 (DSB): * Added dut1 to the Frame structure. * Added Dut1 accessor methods. * 17-MAY-2007 (DSB): * Added NormUnit attribute. * 14-JAN-2009 (DSB): * Added astIntersect method. * 18-JUN-2009 (DSB): * Added ObsAlt attribute. * 17-APR-2015 (DSB): * Added astCentre. * 27-APR-2015 (DSB): * Added InternalUnit attribute. * 26-OCT-2016 (DSB): * Added method astAxNorm. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "axis.h" /* Coordinate Axis class */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #include /* Macros. */ /* ------- */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* A bad value for the System attribute. */ #define AST__BADSYSTEM -1 /* The legal System values recognized by this class of Frame. */ #define AST__CART 0 /* Flag bitmasks for use with astSetFrameFlags. */ # define AST__INTFLAG 1 /* FrameSet integrity is currently being restored */ /* Define constants used to size global arrays in this module. */ #define AST__FRAME_LABEL_BUFF_LEN 100 /* Max length of default axis Label string */ #define AST__FRAME_SYMBOL_BUFF_LEN 50 /* Max length of default axis Symbol string */ #define AST__FRAME_TITLE_BUFF_LEN 100 /* Max length of default title string */ #define AST__FRAME_GETATTRIB_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ #define AST__FRAME_ASTFMTDECIMALYR_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ #define AST__FRAME_ASTFORMATID_MAX_STRINGS 50 /* Number of string values buffer by astFormatID*/ #endif /* Type Definitions. */ /* ================= */ /* Integer type used to store the System attribute values. */ typedef int AstSystemType; /* Frame structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstFrame { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstAxis **axis; /* Pointer to array of Axis objects */ char *domain; /* Pointer to Domain string */ char *title; /* Pointer to Title string */ double epoch; /* Epoch as Modified Julian Date */ double obslat; /* Geodetic latitude of observer */ double obslon; /* Geodetic longitude of observer */ double obsalt; /* Height above reference spheroid (geodetic, metres) */ double dut1; /* UT1-UTC in seconds */ int *perm; /* Pointer to axis permutation array */ int digits; /* Default digits of precision */ int match_end; /* Match final axes of target? */ int active_unit; /* Use Unit when aligning Frames? */ int max_axes; /* Minimum no. axes matched */ int min_axes; /* Max. no. axes matched */ int naxes; /* Number of axes */ int permute; /* Permute axes in order to match? */ int preserve_axes; /* Preserve target axes? */ AstSystemType system; /* Code identifying coordinate system */ AstSystemType alignsystem; /* Code for Alignment coordinate system */ int flags; /* Bit mask containing various protected flags */ struct AstFrameSet *variants; /* FrameSet defining alternative properties for the Frame */ } AstFrame; /* Cached Line structure. */ /* ---------------------- */ /* This structure contains information describing a line segment within a 2D Frame. It is used by other classes to store intermediate cached values relating to the line in order to speed up repeated operations on the line. */ typedef struct AstLineDef { AstFrame *frame; /* Pointer to Frame in which the line is defined */ double length; /* Line length */ int infinite; /* Disregard the start and end of the line? */ double start[2]; /* Frame axis values at line start */ double end[2]; /* Frame axis values at line end */ double dir[2]; /* Unit vector defining line direction */ double q[2]; /* Unit vector perpendicular to line */ } AstLineDef; /* Virtual function table. */ /* ----------------------- */ /* The virtual function table makes a forward reference to the AstFrameSet structure which is not defined until "frameset.h" is included (below). Hence make a preliminary definition available now. */ struct AstFrameSet; /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstAxis *(* GetAxis)( AstFrame *, int, int * ); AstFrame *(* PickAxes)( AstFrame *, int, const int[], AstMapping **, int * ); AstLineDef *(* LineDef)( AstFrame *, const double[2], const double[2], int * ); AstPointSet *(* ResolvePoints)( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); const char *(* Abbrev)( AstFrame *, int, const char *, const char *, const char *, int * ); const char *(* Format)( AstFrame *, int, double, int * ); const char *(* GetDomain)( AstFrame *, int * ); const char *(* GetFormat)( AstFrame *, int, int * ); const char *(* GetLabel)( AstFrame *, int, int * ); const char *(* GetSymbol)( AstFrame *, int, int * ); const char *(* GetTitle)( AstFrame *, int * ); const char *(* GetInternalUnit)( AstFrame *, int, int * ); const char *(* GetNormUnit)( AstFrame *, int, int * ); const char *(* GetUnit)( AstFrame *, int, int * ); const int *(* GetPerm)( AstFrame *, int * ); double (* Angle)( AstFrame *, const double[], const double[], const double[], int * ); double (* Distance)( AstFrame *, const double[], const double[], int * ); double (* Centre)( AstFrame *, int, double, double, int * ); double (* Gap)( AstFrame *, int, double, int *, int * ); int (* Fields)( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); double (* AxDistance)( AstFrame *, int, double, double, int * ); void (* AxNorm)( AstFrame *, int, int, int, double *, int * ); double (* AxOffset)( AstFrame *, int, double, double, int * ); int (* AxIn)( AstFrame *, int, double, double, double, int, int * ); int (* GetDigits)( AstFrame *, int * ); int (* GetDirection)( AstFrame *, int, int * ); int (* GetMatchEnd)( AstFrame *, int * ); int (* GetMaxAxes)( AstFrame *, int * ); int (* GetMinAxes)( AstFrame *, int * ); int (* GetNaxes)( AstFrame *, int * ); int (* GetPermute)( AstFrame *, int * ); int (* GetPreserveAxes)( AstFrame *, int * ); int (* IsUnitFrame)( AstFrame *, int * ); int (* LineCrossing)( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); int (* LineContains)( AstFrame *, AstLineDef *, int, double *, int * ); int (* Match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); int (* SubFrame)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); int (* TestDigits)( AstFrame *, int * ); int (* TestDirection)( AstFrame *, int, int * ); int (* TestDomain)( AstFrame *, int * ); int (* TestFormat)( AstFrame *, int, int * ); int (* TestLabel)( AstFrame *, int, int * ); int (* TestMatchEnd)( AstFrame *, int * ); int (* TestMaxAxes)( AstFrame *, int * ); int (* TestMinAxes)( AstFrame *, int * ); int (* TestPermute)( AstFrame *, int * ); int (* TestPreserveAxes)( AstFrame *, int * ); int (* TestSymbol)( AstFrame *, int, int * ); int (* TestTitle)( AstFrame *, int * ); int (* TestUnit)( AstFrame *, int, int * ); int (* Unformat)( AstFrame *, int, const char *, double *, int * ); int (* ValidateAxis)( AstFrame *, int, int, const char *, int * ); AstSystemType (* ValidateSystem)( AstFrame *, AstSystemType, const char *, int * ); AstSystemType (* SystemCode)( AstFrame *, const char *, int * ); const char *(* SystemString)( AstFrame *, AstSystemType, int * ); struct AstFrameSet *(* Convert)( AstFrame *, AstFrame *, const char *, int * ); struct AstFrameSet *(* ConvertX)( AstFrame *, AstFrame *, const char *, int * ); struct AstFrameSet *(* FindFrame)( AstFrame *, AstFrame *, const char *, int * ); void (* MatchAxes)( AstFrame *, AstFrame *, int[], int * ); void (* MatchAxesX)( AstFrame *, AstFrame *, int[], int * ); void (* CheckPerm)( AstFrame *, const int *, const char *, int * ); void (* ClearDigits)( AstFrame *, int * ); void (* ClearDirection)( AstFrame *, int, int * ); void (* ClearDomain)( AstFrame *, int * ); void (* ClearFormat)( AstFrame *, int, int * ); void (* ClearLabel)( AstFrame *, int, int * ); void (* ClearMatchEnd)( AstFrame *, int * ); void (* ClearMaxAxes)( AstFrame *, int * ); void (* ClearMinAxes)( AstFrame *, int * ); void (* ClearPermute)( AstFrame *, int * ); void (* ClearPreserveAxes)( AstFrame *, int * ); void (* ClearSymbol)( AstFrame *, int, int * ); void (* ClearTitle)( AstFrame *, int * ); void (* ClearUnit)( AstFrame *, int, int * ); void (* Intersect)( AstFrame *, const double[2], const double[2], const double[2], const double[2], double[2], int * ); void (* Norm)( AstFrame *, double[], int * ); void (* NormBox)( AstFrame *, double *, double *, AstMapping *, int * ); void (* Offset)( AstFrame *, const double[], const double[], double, double[], int * ); double (* AxAngle)( AstFrame *, const double[2], const double[2], int, int * ); double (* Offset2)( AstFrame *, const double[2], double, double, double[2], int * ); void (* Overlay)( AstFrame *, const int *, AstFrame *, int * ); void (* PermAxes)( AstFrame *, const int[], int * ); void (* PrimaryFrame)( AstFrame *, int, AstFrame **, int *, int * ); void (* Resolve)( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); void (* SetAxis)( AstFrame *, int, AstAxis *, int * ); void (* SetDigits)( AstFrame *, int, int * ); void (* SetDirection)( AstFrame *, int, int, int * ); void (* SetDomain)( AstFrame *, const char *, int * ); void (* SetFormat)( AstFrame *, int, const char *, int * ); void (* SetLabel)( AstFrame *, int, const char *, int * ); void (* SetMatchEnd)( AstFrame *, int, int * ); void (* SetMaxAxes)( AstFrame *, int, int * ); void (* SetMinAxes)( AstFrame *, int, int * ); void (* SetPermute)( AstFrame *, int, int * ); void (* SetPreserveAxes)( AstFrame *, int, int * ); void (* SetSymbol)( AstFrame *, int, const char *, int * ); void (* SetTitle)( AstFrame *, const char *, int * ); void (* SetUnit)( AstFrame *, int, const char *, int * ); void (* ValidateAxisSelection)( AstFrame *, int, const int *, const char *, int * ); void (* LineOffset)( AstFrame *, AstLineDef *, double, double, double[2], int * ); AstPointSet *(* FrameGrid)( AstFrame *, int, const double *, const double *, int * ); struct AstFrameSet *(* GetFrameVariants)( AstFrame *, int * ); void (* SetFrameVariants)( AstFrame *, struct AstFrameSet *, int * ); double (* GetTop)( AstFrame *, int, int * ); int (* TestTop)( AstFrame *, int, int * ); void (* ClearTop)( AstFrame *, int, int * ); void (* SetTop)( AstFrame *, int, double, int * ); double (* GetBottom)( AstFrame *, int, int * ); int (* TestBottom)( AstFrame *, int, int * ); void (* ClearBottom)( AstFrame *, int, int * ); void (* SetBottom)( AstFrame *, int, double, int * ); AstSystemType (* GetSystem)( AstFrame *, int * ); int (* TestSystem)( AstFrame *, int * ); void (* ClearSystem)( AstFrame *, int * ); void (* SetSystem)( AstFrame *, AstSystemType, int * ); AstSystemType (* GetAlignSystem)( AstFrame *, int * ); int (* TestAlignSystem)( AstFrame *, int * ); void (* ClearAlignSystem)( AstFrame *, int * ); void (* SetAlignSystem)( AstFrame *, AstSystemType, int * ); double (* GetEpoch)( AstFrame *, int * ); int (* TestEpoch)( AstFrame *, int * ); void (* ClearEpoch)( AstFrame *, int * ); void (* SetEpoch)( AstFrame *, double, int * ); int (* TestActiveUnit)( AstFrame *, int * ); int (* GetActiveUnit)( AstFrame *, int * ); void (* SetActiveUnit)( AstFrame *, int, int * ); double (* GetObsLon)( AstFrame *, int * ); int (* TestObsLon)( AstFrame *, int * ); void (* ClearObsLon)( AstFrame *, int * ); void (* SetObsLon)( AstFrame *, double, int * ); double (* GetObsLat)( AstFrame *, int * ); int (* TestObsLat)( AstFrame *, int * ); void (* ClearObsLat)( AstFrame *, int * ); void (* SetObsLat)( AstFrame *, double, int * ); double (* GetObsAlt)( AstFrame *, int * ); int (* TestObsAlt)( AstFrame *, int * ); void (* ClearObsAlt)( AstFrame *, int * ); void (* SetObsAlt)( AstFrame *, double, int * ); double (* GetDut1)( AstFrame *, int * ); int (* TestDut1)( AstFrame *, int * ); void (* ClearDut1)( AstFrame *, int * ); void (* SetDut1)( AstFrame *, double, int * ); void (* SetFrameFlags)( AstFrame *, int, int * ); int (* GetFrameFlags)( AstFrame *, int * ); } AstFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstFrameGlobals { AstFrameVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__FRAME_GETATTRIB_BUFF_LEN + 1 ]; char *AstFormatID_Strings[ AST__FRAME_ASTFORMATID_MAX_STRINGS ]; int AstFormatID_Istr; int AstFormatID_Init; char Label_Buff[ AST__FRAME_LABEL_BUFF_LEN + 1 ]; char Symbol_Buff[ AST__FRAME_SYMBOL_BUFF_LEN + 1 ]; char Title_Buff[ AST__FRAME_TITLE_BUFF_LEN + 1 ]; char AstFmtDecimalYr_Buff[ AST__FRAME_ASTFMTDECIMALYR_BUFF_LEN + 1 ]; } AstFrameGlobals; #endif #endif /* More include files. */ /* =================== */ /* The interface to the FrameSet class must be included here (after the type definitions for the Frame class) because "frameset.h" itself includes this file ("frame.h"), although "frameset.h" refers to the AstFrameSet structure above. This seems a little strange at first, but is simply analogous to making a forward reference to a structure type when recursively defining a normal C structure (except that here the definitions happen to be in separate include files). */ #include "frameset.h" /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Frame) /* Check class membership */ astPROTO_ISA(Frame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstFrame *astFrame_( int, const char *, int *, ...); #else AstFrame *astFrameId_( int, const char *, ... )__attribute__((format(printf,2,3))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstFrame *astInitFrame_( void *, size_t, int, AstFrameVtab *, const char *, int, int * ); /* Vtab initialiser. */ void astInitFrameVtab_( AstFrameVtab *, const char *, int * ); /* Loader. */ AstFrame *astLoadFrame_( void *, size_t, AstFrameVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitFrameGlobals_( AstFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstFrameSet *astConvert_( AstFrame *, AstFrame *, const char *, int * ); AstFrameSet *astFindFrame_( AstFrame *, AstFrame *, const char *, int * ); double astAngle_( AstFrame *, const double[], const double[], const double[], int * ); double astAxAngle_( AstFrame *, const double[2], const double[2], int, int * ); double astAxDistance_( AstFrame *, int, double, double, int * ); double astAxOffset_( AstFrame *, int, double, double, int * ); double astDistance_( AstFrame *, const double[], const double[], int * ); double astOffset2_( AstFrame *, const double[2], double, double, double[2], int * ); int astGetActiveUnit_( AstFrame *, int * ); void astAxNorm_( AstFrame *, int, int, int, double *, int * ); void astIntersect_( AstFrame *, const double[2], const double[2], const double[2], const double[2], double[2], int * ); void astMatchAxes_( AstFrame *, AstFrame *, int[], int * ); void astNorm_( AstFrame *, double[], int * ); void astOffset_( AstFrame *, const double[], const double[], double, double[], int * ); void astResolve_( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); void astSetActiveUnit_( AstFrame *, int, int * ); AstFrameSet *astGetFrameVariants_( AstFrame *, int * ); void astSetFrameVariants_( AstFrame *, AstFrameSet *, int * ); #if defined(astCLASS) /* Protected */ void astNormBox_( AstFrame *, double *, double *, AstMapping *, int * ); AstFrame *astPickAxes_( AstFrame *, int, const int[], AstMapping **, int * ); const char *astFormat_( AstFrame *, int, double, int * ); int astUnformat_( AstFrame *, int, const char *, double *, int * ); void astPermAxes_( AstFrame *, const int[], int * ); #else AstFrame *astPickAxesId_( AstFrame *, int, const int[], AstMapping **, int * ); const char *astFormatId_( AstFrame *, int, double, int * ); int astUnformatId_( AstFrame *, int, const char *, double *, int * ); void astPermAxesId_( AstFrame *, const int[], int * ); #endif #if defined(astCLASS) /* Protected */ int astAxIn_( AstFrame *, int, double, double, double, int, int * ); AstAxis * astGetAxis_( AstFrame *, int, int * ); AstFrameSet *astConvertX_( AstFrame *, AstFrame *, const char *, int * ); void astMatchAxesX_( AstFrame *, AstFrame *, int[], int * ); AstLineDef *astLineDef_( AstFrame *, const double[2], const double[2], int * ); AstPointSet *astResolvePoints_( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); const char *astAbbrev_( AstFrame *, int, const char *, const char *, const char *, int * ); const char *astGetDomain_( AstFrame *, int * ); const char *astGetFormat_( AstFrame *, int, int * ); const char *astGetLabel_( AstFrame *, int, int * ); const char *astGetSymbol_( AstFrame *, int, int * ); const char *astGetTitle_( AstFrame *, int * ); const char *astGetUnit_( AstFrame *, int, int * ); const char *astGetInternalUnit_( AstFrame *, int, int * ); const char *astGetNormUnit_( AstFrame *, int, int * ); const int *astGetPerm_( AstFrame *, int * ); double astCentre_( AstFrame *, int, double, double, int * ); double astGap_( AstFrame *, int, double, int *, int * ); int astFields_( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); int astGetDigits_( AstFrame *, int * ); int astGetDirection_( AstFrame *, int, int * ); int astGetMatchEnd_( AstFrame *, int * ); int astGetMaxAxes_( AstFrame *, int * ); int astGetMinAxes_( AstFrame *, int * ); int astGetNaxes_( AstFrame *, int * ); int astGetPermute_( AstFrame *, int * ); int astGetPreserveAxes_( AstFrame *, int * ); int astIsUnitFrame_( AstFrame *, int * ); int astLineCrossing_( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); int astLineContains_( AstFrame *, AstLineDef *, int, double *, int * ); int astMatch_( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); int astSubFrame_( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); int astTestDigits_( AstFrame *, int * ); int astTestDirection_( AstFrame *, int, int * ); int astTestDomain_( AstFrame *, int * ); int astTestFormat_( AstFrame *, int, int * ); int astTestLabel_( AstFrame *, int, int * ); int astTestMatchEnd_( AstFrame *, int * ); int astTestMaxAxes_( AstFrame *, int * ); int astTestMinAxes_( AstFrame *, int * ); int astTestPermute_( AstFrame *, int * ); int astTestPreserveAxes_( AstFrame *, int * ); int astTestSymbol_( AstFrame *, int, int * ); int astTestTitle_( AstFrame *, int * ); int astTestUnit_( AstFrame *, int, int * ); int astValidateAxis_( AstFrame *, int, int, const char *, int * ); AstSystemType astValidateSystem_( AstFrame *, AstSystemType, const char *, int * ); AstSystemType astSystemCode_( AstFrame *, const char *, int * ); const char *astSystemString_( AstFrame *, AstSystemType, int * ); void astCheckPerm_( AstFrame *, const int *, const char *, int * ); void astClearDigits_( AstFrame *, int * ); void astClearDirection_( AstFrame *, int, int * ); void astClearDomain_( AstFrame *, int * ); void astClearFormat_( AstFrame *, int, int * ); void astClearLabel_( AstFrame *, int, int * ); void astClearMatchEnd_( AstFrame *, int * ); void astClearMaxAxes_( AstFrame *, int * ); void astClearMinAxes_( AstFrame *, int * ); void astClearPermute_( AstFrame *, int * ); void astClearPreserveAxes_( AstFrame *, int * ); void astClearSymbol_( AstFrame *, int, int * ); void astClearTitle_( AstFrame *, int * ); void astClearUnit_( AstFrame *, int, int * ); void astOverlay_( AstFrame *, const int *, AstFrame *, int * ); void astPrimaryFrame_( AstFrame *, int, AstFrame **, int *, int * ); void astSetAxis_( AstFrame *, int, AstAxis *, int * ); void astSetDigits_( AstFrame *, int, int * ); void astSetDirection_( AstFrame *, int, int, int * ); void astSetDomain_( AstFrame *, const char *, int * ); void astSetFormat_( AstFrame *, int, const char *, int * ); void astSetLabel_( AstFrame *, int, const char *, int * ); void astSetMatchEnd_( AstFrame *, int, int * ); void astSetMaxAxes_( AstFrame *, int, int * ); void astSetMinAxes_( AstFrame *, int, int * ); void astSetPermute_( AstFrame *, int, int * ); void astSetPreserveAxes_( AstFrame *, int, int * ); void astSetSymbol_( AstFrame *, int, const char *, int * ); void astSetTitle_( AstFrame *, const char *, int * ); void astSetUnit_( AstFrame *, int, const char *, int * ); void astValidateAxisSelection_( AstFrame *, int, const int *, const char *, int * ); double astReadDateTime_( const char *, int * ); const char *astFmtDecimalYr_( double, int, int * ); void astLineOffset_( AstFrame *, AstLineDef *, double, double, double[2], int * ); AstPointSet *astFrameGrid_( AstFrame *, int, const double *, const double *, int * ); double astGetTop_( AstFrame *, int, int * ); int astTestTop_( AstFrame *, int, int * ); void astClearTop_( AstFrame *, int, int * ); void astSetTop_( AstFrame *, int, double, int * ); double astGetBottom_( AstFrame *, int, int * ); int astTestBottom_( AstFrame *, int, int * ); void astClearBottom_( AstFrame *, int, int * ); void astSetBottom_( AstFrame *, int, double, int * ); AstSystemType astGetSystem_( AstFrame *, int * ); int astTestSystem_( AstFrame *, int * ); void astClearSystem_( AstFrame *, int * ); void astSetSystem_( AstFrame *, AstSystemType, int * ); AstSystemType astGetAlignSystem_( AstFrame *, int * ); int astTestAlignSystem_( AstFrame *, int * ); void astClearAlignSystem_( AstFrame *, int * ); void astSetAlignSystem_( AstFrame *, AstSystemType, int * ); double astGetEpoch_( AstFrame *, int * ); int astTestEpoch_( AstFrame *, int * ); void astClearEpoch_( AstFrame *, int * ); void astSetEpoch_( AstFrame *, double, int * ); double astGetObsLon_( AstFrame *, int * ); int astTestObsLon_( AstFrame *, int * ); void astClearObsLon_( AstFrame *, int * ); void astSetObsLon_( AstFrame *, double, int * ); double astGetObsLat_( AstFrame *, int * ); int astTestObsLat_( AstFrame *, int * ); void astClearObsLat_( AstFrame *, int * ); void astSetObsLat_( AstFrame *, double, int * ); double astGetObsAlt_( AstFrame *, int * ); int astTestObsAlt_( AstFrame *, int * ); void astClearObsAlt_( AstFrame *, int * ); void astSetObsAlt_( AstFrame *, double, int * ); double astGetDut1_( AstFrame *, int * ); int astTestDut1_( AstFrame *, int * ); void astClearDut1_( AstFrame *, int * ); void astSetDut1_( AstFrame *, double, int * ); int astTestActiveUnit_( AstFrame *, int * ); void astSetFrameFlags_( AstFrame *, int, int * ); int astGetFrameFlags_( AstFrame *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckFrame(this) astINVOKE_CHECK(Frame,this,0) #define astVerifyFrame(this) astINVOKE_CHECK(Frame,this,1) /* Test class membership. */ #define astIsAFrame(this) astINVOKE_ISA(Frame,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astFrame astINVOKE(F,astFrame_) #else #define astFrame astINVOKE(F,astFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitFrame(mem,size,init,vtab,name,naxes) \ astINVOKE(O,astInitFrame_(mem,size,init,vtab,name,naxes,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitFrameVtab(vtab,name) astINVOKE(V,astInitFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckFrame to validate Frame pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astConvert(from,to,domainlist) \ astINVOKE(O,astConvert_(astCheckFrame(from),astCheckFrame(to),domainlist,STATUS_PTR)) #define astAngle(this,a,b,c) \ astINVOKE(V,astAngle_(astCheckFrame(this),a,b,c,STATUS_PTR)) #define astDistance(this,point1,point2) \ astINVOKE(V,astDistance_(astCheckFrame(this),point1,point2,STATUS_PTR)) #define astFindFrame(target,template,domainlist) \ astINVOKE(O,astFindFrame_(astCheckFrame(target),astCheckFrame(template),domainlist,STATUS_PTR)) #define astMatchAxes(frm1,frm2,axes) \ astINVOKE(V,astMatchAxes_(astCheckFrame(frm1),astCheckFrame(frm2),axes,STATUS_PTR)) #define astNorm(this,value) \ astINVOKE(V,astNorm_(astCheckFrame(this),value,STATUS_PTR)) #define astAxDistance(this,axis,v1,v2) \ astINVOKE(V,astAxDistance_(astCheckFrame(this),axis,v1,v2,STATUS_PTR)) #define astAxNorm(this,axis,oper,nval,values) \ astINVOKE(V,astAxNorm_(astCheckFrame(this),axis,oper,nval,values,STATUS_PTR)) #define astAxOffset(this,axis,v1,dist) \ astINVOKE(V,astAxOffset_(astCheckFrame(this),axis,v1,dist,STATUS_PTR)) #define astOffset(this,point1,point2,offset,point3) \ astINVOKE(V,astOffset_(astCheckFrame(this),point1,point2,offset,point3,STATUS_PTR)) #define astAxAngle(this,a,b,axis) \ astINVOKE(V,astAxAngle_(astCheckFrame(this),a,b,axis,STATUS_PTR)) #define astIntersect(this,a1,a2,b1,b2,cross) \ astINVOKE(V,astIntersect_(astCheckFrame(this),a1,a2,b1,b2,cross,STATUS_PTR)) #define astOffset2(this,point1,angle,offset,point2) \ astINVOKE(V,astOffset2_(astCheckFrame(this),point1,angle,offset,point2,STATUS_PTR)) #define astResolve(this,point1,point2,point3,point4,d1,d2) \ astINVOKE(V,astResolve_(astCheckFrame(this),point1,point2,point3,point4,d1,d2,STATUS_PTR)) #define astGetActiveUnit(this) \ astINVOKE(V,astGetActiveUnit_(astCheckFrame(this),STATUS_PTR)) #define astSetActiveUnit(this,value) \ astINVOKE(V,astSetActiveUnit_(astCheckFrame(this),value,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astGetFrameVariants(this) \ astINVOKE(O,astGetFrameVariants_(astCheckFrame(this),STATUS_PTR)) #define astSetFrameVariants(this,variants) \ astINVOKE(V,astSetFrameVariants_(astCheckFrame(this),astCheckFrameSet(variants),STATUS_PTR)) #define astNormBox(this,lbnd,ubnd,reg) \ astINVOKE(V,astNormBox_(astCheckFrame(this),lbnd,ubnd,astCheckMapping(reg),STATUS_PTR)) #define astFormat(this,axis,value) \ astINVOKE(V,astFormat_(astCheckFrame(this),axis,value,STATUS_PTR)) #define astPermAxes(this,perm) \ astINVOKE(V,astPermAxes_(astCheckFrame(this),perm,STATUS_PTR)) #define astPickAxes(this,naxes,axes,map) \ astINVOKE(O,astPickAxes_(astCheckFrame(this),naxes,axes,(AstMapping **)(map),STATUS_PTR)) #define astUnformat(this,axis,string,value) \ astINVOKE(V,astUnformat_(astCheckFrame(this),axis,string,value,STATUS_PTR)) #else #define astFormat(this,axis,value) \ astINVOKE(V,astFormatId_(astCheckFrame(this),axis,value,STATUS_PTR)) #define astPermAxes(this,perm) \ astINVOKE(V,astPermAxesId_(astCheckFrame(this),perm,STATUS_PTR)) #define astPickAxes(this,naxes,axes,map) \ astINVOKE(O,astPickAxesId_(astCheckFrame(this),naxes,axes,(AstMapping **)(map),STATUS_PTR)) #define astUnformat(this,axis,string,value) \ astINVOKE(V,astUnformatId_(astCheckFrame(this),axis,string,value,STATUS_PTR)) #endif #if defined(astCLASS) /* Protected */ #define astAxIn(this,axis,lo,hi,val,closed) \ astINVOKE(V,astAxIn_(astCheckFrame(this),axis,lo,hi,val,closed,STATUS_PTR)) #define astAbbrev(this,axis,fmt,str1,str2) \ astINVOKE(V,astAbbrev_(astCheckFrame(this),axis,fmt,str1,str2,STATUS_PTR)) #define astFields(this,axis,fmt,str,maxfld,fields,nc,val) \ astINVOKE(V,astFields_(astCheckFrame(this),axis,fmt,str,maxfld,fields,nc,val,STATUS_PTR)) #define astCheckPerm(this,perm,method) \ astINVOKE(V,astCheckPerm_(astCheckFrame(this),perm,method,STATUS_PTR)) #define astResolvePoints(this,p1,p2,in,out) \ astINVOKE(O,astResolvePoints_(astCheckFrame(this),p1,p2,astCheckPointSet(in),((out)?astCheckPointSet(out):NULL),STATUS_PTR)) #define astLineDef(this,p1,p2) \ astINVOKE(V,astLineDef_(astCheckFrame(this),p1,p2,STATUS_PTR)) #define astLineOffset(this,line,par,prp,point) \ astINVOKE(V,astLineOffset_(astCheckFrame(this),line,par,prp,point,STATUS_PTR)) #define astFrameGrid(this,size,lbnd,ubnd) \ astINVOKE(O,astFrameGrid_(astCheckFrame(this),size,lbnd,ubnd,STATUS_PTR)) #define astLineCrossing(this,l1,l2,cross) \ astINVOKE(V,astLineCrossing_(astCheckFrame(this),l1,l2,cross,STATUS_PTR)) #define astLineContains(this,l,def,point) \ astINVOKE(V,astLineContains_(astCheckFrame(this),l,def,point,STATUS_PTR)) #define astClearDigits(this) \ astINVOKE(V,astClearDigits_(astCheckFrame(this),STATUS_PTR)) #define astClearDirection(this,axis) \ astINVOKE(V,astClearDirection_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearDomain(this) \ astINVOKE(V,astClearDomain_(astCheckFrame(this),STATUS_PTR)) #define astClearFormat(this,axis) \ astINVOKE(V,astClearFormat_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearLabel(this,axis) \ astINVOKE(V,astClearLabel_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearMatchEnd(this) \ astINVOKE(V,astClearMatchEnd_(astCheckFrame(this),STATUS_PTR)) #define astClearMaxAxes(this) \ astINVOKE(V,astClearMaxAxes_(astCheckFrame(this),STATUS_PTR)) #define astClearMinAxes(this) \ astINVOKE(V,astClearMinAxes_(astCheckFrame(this),STATUS_PTR)) #define astClearPermute(this) \ astINVOKE(V,astClearPermute_(astCheckFrame(this),STATUS_PTR)) #define astClearPreserveAxes(this) \ astINVOKE(V,astClearPreserveAxes_(astCheckFrame(this),STATUS_PTR)) #define astClearSymbol(this,axis) \ astINVOKE(V,astClearSymbol_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearTitle(this) \ astINVOKE(V,astClearTitle_(astCheckFrame(this),STATUS_PTR)) #define astClearUnit(this,axis) \ astINVOKE(V,astClearUnit_(astCheckFrame(this),axis,STATUS_PTR)) #define astConvertX(to,from,domainlist) \ astINVOKE(O,astConvertX_(astCheckFrame(to),astCheckFrame(from),domainlist,STATUS_PTR)) #define astCentre(this,axis,value,gap) \ astINVOKE(V,astCentre_(astCheckFrame(this),axis,value,gap,STATUS_PTR)) #define astGap(this,axis,gap,ntick) \ astINVOKE(V,astGap_(astCheckFrame(this),axis,gap,ntick,STATUS_PTR)) #define astGetAxis(this,axis) \ astINVOKE(O,astGetAxis_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetDigits(this) \ astINVOKE(V,astGetDigits_(astCheckFrame(this),STATUS_PTR)) #define astGetDirection(this,axis) \ astINVOKE(V,astGetDirection_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetDomain(this) \ astINVOKE(V,astGetDomain_(astCheckFrame(this),STATUS_PTR)) #define astGetFormat(this,axis) \ astINVOKE(V,astGetFormat_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetLabel(this,axis) \ astINVOKE(V,astGetLabel_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetMatchEnd(this) \ astINVOKE(V,astGetMatchEnd_(astCheckFrame(this),STATUS_PTR)) #define astGetMaxAxes(this) \ astINVOKE(V,astGetMaxAxes_(astCheckFrame(this),STATUS_PTR)) #define astGetMinAxes(this) \ astINVOKE(V,astGetMinAxes_(astCheckFrame(this),STATUS_PTR)) #define astGetNaxes(this) \ astINVOKE(V,astGetNaxes_(astCheckFrame(this),STATUS_PTR)) #define astGetPerm(this) \ astINVOKE(V,astGetPerm_(astCheckFrame(this),STATUS_PTR)) #define astGetPermute(this) \ astINVOKE(V,astGetPermute_(astCheckFrame(this),STATUS_PTR)) #define astGetPreserveAxes(this) \ astINVOKE(V,astGetPreserveAxes_(astCheckFrame(this),STATUS_PTR)) #define astGetSymbol(this,axis) \ astINVOKE(V,astGetSymbol_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetTitle(this) \ astINVOKE(V,astGetTitle_(astCheckFrame(this),STATUS_PTR)) #define astGetUnit(this,axis) \ astINVOKE(V,astGetUnit_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetNormUnit(this,axis) \ astINVOKE(V,astGetNormUnit_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetInternalUnit(this,axis) \ astINVOKE(V,astGetInternalUnit_(astCheckFrame(this),axis,STATUS_PTR)) #define astMatch(template,target,matchsub,template_axes,target_axes,map,result) \ astINVOKE(V,astMatch_(astCheckFrame(template),astCheckFrame(target),matchsub,template_axes,target_axes,(AstMapping **)(map),(AstFrame **)(result),STATUS_PTR)) #define astIsUnitFrame(this) \ astINVOKE(V,astIsUnitFrame_(astCheckFrame(this),STATUS_PTR)) #define astOverlay(template,template_axes,result) \ astINVOKE(V,astOverlay_(astCheckFrame(template),template_axes,astCheckFrame(result),STATUS_PTR)) #define astPrimaryFrame(this,axis1,frame,axis2) \ astINVOKE(V,astPrimaryFrame_(astCheckFrame(this),axis1,(AstFrame **)(frame),axis2,STATUS_PTR)) #define astSetAxis(this,axis,newaxis) \ astINVOKE(V,astSetAxis_(astCheckFrame(this),axis,astCheckAxis(newaxis),STATUS_PTR)) #define astSetDigits(this,digits) \ astINVOKE(V,astSetDigits_(astCheckFrame(this),digits,STATUS_PTR)) #define astSetDirection(this,axis,direction) \ astINVOKE(V,astSetDirection_(astCheckFrame(this),axis,direction,STATUS_PTR)) #define astSetDomain(this,domain) \ astINVOKE(V,astSetDomain_(astCheckFrame(this),domain,STATUS_PTR)) #define astSetFormat(this,axis,format) \ astINVOKE(V,astSetFormat_(astCheckFrame(this),axis,format,STATUS_PTR)) #define astSetLabel(this,axis,label) \ astINVOKE(V,astSetLabel_(astCheckFrame(this),axis,label,STATUS_PTR)) #define astSetMatchEnd(this,value) \ astINVOKE(V,astSetMatchEnd_(astCheckFrame(this),value,STATUS_PTR)) #define astSetMaxAxes(this,value) \ astINVOKE(V,astSetMaxAxes_(astCheckFrame(this),value,STATUS_PTR)) #define astSetMinAxes(this,value) \ astINVOKE(V,astSetMinAxes_(astCheckFrame(this),value,STATUS_PTR)) #define astSetPermute(this,value) \ astINVOKE(V,astSetPermute_(astCheckFrame(this),value,STATUS_PTR)) #define astSetPreserveAxes(this,value) \ astINVOKE(V,astSetPreserveAxes_(astCheckFrame(this),value,STATUS_PTR)) #define astSetSymbol(this,axis,symbol) \ astINVOKE(V,astSetSymbol_(astCheckFrame(this),axis,symbol,STATUS_PTR)) #define astSetTitle(this,title) \ astINVOKE(V,astSetTitle_(astCheckFrame(this),title,STATUS_PTR)) #define astSetUnit(this,axis,unit) \ astINVOKE(V,astSetUnit_(astCheckFrame(this),axis,unit,STATUS_PTR)) #define astSubFrame(target,template,result_naxes,target_axes,template_axes,map,result) \ astINVOKE(V,astSubFrame_(astCheckFrame(target),template?astCheckFrame(template):NULL,result_naxes,target_axes,template_axes,(AstMapping **)(map),(AstFrame **)(result),STATUS_PTR)) #define astTestDigits(this) \ astINVOKE(V,astTestDigits_(astCheckFrame(this),STATUS_PTR)) #define astTestDirection(this,axis) \ astINVOKE(V,astTestDirection_(astCheckFrame(this),axis,STATUS_PTR)) #define astTestDomain(this) \ astINVOKE(V,astTestDomain_(astCheckFrame(this),STATUS_PTR)) #define astTestFormat(this,axis) \ astINVOKE(V,astTestFormat_(astCheckFrame(this),axis,STATUS_PTR)) #define astTestLabel(this,axis) \ astINVOKE(V,astTestLabel_(astCheckFrame(this),axis,STATUS_PTR)) #define astTestMatchEnd(this) \ astINVOKE(V,astTestMatchEnd_(astCheckFrame(this),STATUS_PTR)) #define astTestMaxAxes(this) \ astINVOKE(V,astTestMaxAxes_(astCheckFrame(this),STATUS_PTR)) #define astTestMinAxes(this) \ astINVOKE(V,astTestMinAxes_(astCheckFrame(this),STATUS_PTR)) #define astTestPermute(this) \ astINVOKE(V,astTestPermute_(astCheckFrame(this),STATUS_PTR)) #define astTestPreserveAxes(this) \ astINVOKE(V,astTestPreserveAxes_(astCheckFrame(this),STATUS_PTR)) #define astTestSymbol(this,axis) \ astINVOKE(V,astTestSymbol_(astCheckFrame(this),axis,STATUS_PTR)) #define astTestTitle(this) \ astINVOKE(V,astTestTitle_(astCheckFrame(this),STATUS_PTR)) #define astTestUnit(this,axis) \ astINVOKE(V,astTestUnit_(astCheckFrame(this),axis,STATUS_PTR)) #define astValidateAxis(this,axis,fwd,method) \ astINVOKE(V,astValidateAxis_(astCheckFrame(this),axis,fwd,method,STATUS_PTR)) #define astValidateAxisSelection(this,naxes,axes,method) \ astINVOKE(V,astValidateAxisSelection_(astCheckFrame(this),naxes,axes,method,STATUS_PTR)) #define astMatchAxesX(frm2,frm1,axes) \ astINVOKE(V,astMatchAxesX_(astCheckFrame(frm2),astCheckFrame(frm1),axes,STATUS_PTR)) #define astFmtDecimalYr(year,digits) astFmtDecimalYr_(year,digits,STATUS_PTR) #define astReadDateTime(value) astReadDateTime_(value,STATUS_PTR) #define astValidateSystem(this,system,method) \ astINVOKE(V,astValidateSystem_(astCheckFrame(this),system,method,STATUS_PTR)) #define astSystemString(this,system) \ astINVOKE(V,astSystemString_(astCheckFrame(this),system,STATUS_PTR)) #define astSystemCode(this,system) \ astINVOKE(V,astSystemCode_(astCheckFrame(this),system,STATUS_PTR)) #define astClearTop(this,axis) \ astINVOKE(V,astClearTop_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetTop(this,axis) \ astINVOKE(V,astGetTop_(astCheckFrame(this),axis,STATUS_PTR)) #define astSetTop(this,axis,value) \ astINVOKE(V,astSetTop_(astCheckFrame(this),axis,value,STATUS_PTR)) #define astTestTop(this,axis) \ astINVOKE(V,astTestTop_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearBottom(this,axis) \ astINVOKE(V,astClearBottom_(astCheckFrame(this),axis,STATUS_PTR)) #define astGetBottom(this,axis) \ astINVOKE(V,astGetBottom_(astCheckFrame(this),axis,STATUS_PTR)) #define astSetBottom(this,axis,value) \ astINVOKE(V,astSetBottom_(astCheckFrame(this),axis,value,STATUS_PTR)) #define astTestBottom(this,axis) \ astINVOKE(V,astTestBottom_(astCheckFrame(this),axis,STATUS_PTR)) #define astClearSystem(this) \ astINVOKE(V,astClearSystem_(astCheckFrame(this),STATUS_PTR)) #define astGetSystem(this) \ astINVOKE(V,astGetSystem_(astCheckFrame(this),STATUS_PTR)) #define astSetSystem(this,value) \ astINVOKE(V,astSetSystem_(astCheckFrame(this),value,STATUS_PTR)) #define astTestSystem(this) \ astINVOKE(V,astTestSystem_(astCheckFrame(this),STATUS_PTR)) #define astClearAlignSystem(this) \ astINVOKE(V,astClearAlignSystem_(astCheckFrame(this),STATUS_PTR)) #define astGetAlignSystem(this) \ astINVOKE(V,astGetAlignSystem_(astCheckFrame(this),STATUS_PTR)) #define astSetAlignSystem(this,value) \ astINVOKE(V,astSetAlignSystem_(astCheckFrame(this),value,STATUS_PTR)) #define astTestAlignSystem(this) \ astINVOKE(V,astTestAlignSystem_(astCheckFrame(this),STATUS_PTR)) #define astClearEpoch(this) \ astINVOKE(V,astClearEpoch_(astCheckFrame(this),STATUS_PTR)) #define astGetEpoch(this) \ astINVOKE(V,astGetEpoch_(astCheckFrame(this),STATUS_PTR)) #define astSetEpoch(this,value) \ astINVOKE(V,astSetEpoch_(astCheckFrame(this),value,STATUS_PTR)) #define astTestEpoch(this) \ astINVOKE(V,astTestEpoch_(astCheckFrame(this),STATUS_PTR)) #define astGetObsLon(this) \ astINVOKE(V,astGetObsLon_(astCheckFrame(this),STATUS_PTR)) #define astTestObsLon(this) \ astINVOKE(V,astTestObsLon_(astCheckFrame(this),STATUS_PTR)) #define astClearObsLon(this) \ astINVOKE(V,astClearObsLon_(astCheckFrame(this),STATUS_PTR)) #define astSetObsLon(this,value) \ astINVOKE(V,astSetObsLon_(astCheckFrame(this),value,STATUS_PTR)) #define astGetObsLat(this) \ astINVOKE(V,astGetObsLat_(astCheckFrame(this),STATUS_PTR)) #define astTestObsLat(this) \ astINVOKE(V,astTestObsLat_(astCheckFrame(this),STATUS_PTR)) #define astClearObsLat(this) \ astINVOKE(V,astClearObsLat_(astCheckFrame(this),STATUS_PTR)) #define astSetObsLat(this,value) \ astINVOKE(V,astSetObsLat_(astCheckFrame(this),value,STATUS_PTR)) #define astGetObsAlt(this) \ astINVOKE(V,astGetObsAlt_(astCheckFrame(this),STATUS_PTR)) #define astTestObsAlt(this) \ astINVOKE(V,astTestObsAlt_(astCheckFrame(this),STATUS_PTR)) #define astClearObsAlt(this) \ astINVOKE(V,astClearObsAlt_(astCheckFrame(this),STATUS_PTR)) #define astSetObsAlt(this,value) \ astINVOKE(V,astSetObsAlt_(astCheckFrame(this),value,STATUS_PTR)) #define astClearDut1(this) \ astINVOKE(V,astClearDut1_(astCheckFrame(this),STATUS_PTR)) #define astGetDut1(this) \ astINVOKE(V,astGetDut1_(astCheckFrame(this),STATUS_PTR)) #define astSetDut1(this,value) \ astINVOKE(V,astSetDut1_(astCheckFrame(this),value,STATUS_PTR)) #define astTestDut1(this) \ astINVOKE(V,astTestDut1_(astCheckFrame(this),STATUS_PTR)) #define astTestActiveUnit(this) \ astINVOKE(V,astTestActiveUnit_(astCheckFrame(this),STATUS_PTR)) #define astSetFrameFlags(this,flags) \ astINVOKE(V,astSetFrameFlags_(astCheckFrame(this),flags,STATUS_PTR)) #define astGetFrameFlags(this) \ astINVOKE(V,astGetFrameFlags_(astCheckFrame(this),STATUS_PTR)) #endif #endif ast-8.3.0/loader.h0000664000175000017500000000252313004147321010650 00000000000000#if !defined( LOADER_INCLUDED ) /* Include this file only once */ #define LOADER_INCLUDED /* *+ * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 18-NOV-1997 (RFWS): * Original version. *- */ #include "object.h" #include "channel.h" #if defined(astCLASS) /* Protected */ typedef AstObject *(AstLoaderType)( void *, size_t, AstObjectVtab *, const char *, AstChannel *, int * ); AstLoaderType *astGetLoader( const char *, int * ); #endif #endif ast-8.3.0/sun211.tex0000664000175000017500001003043613004147401011010 00000000000000\documentclass[twoside,11pt]{starlink} % ? Specify used packages % ? End of specify used packages % ----------------------------------------------------------------------------- % ? Document identification % Fixed part \stardoccategory {Starlink User Note} \stardocinitials {SUN} \stardocsource {sun\stardocnumber} % Variable part - replace [xxx] as appropriate. \stardocnumber {211.27} \stardocauthors {R.F. Warren-Smith \& D.S. Berry} \stardocdate {26th October 2016} \stardoctitle {AST\linebreak% A Library for Handling\linebreak% World Coordinate Systems\linebreak% in Astronomy} \stardoccopyright {Copyright (C) 2014 Science \& Technology Facilities Council} \stardocversion {V8.3} \stardocmanual {Programmer's Guide\\(C Version)} \startitlepic{ \includegraphics[width=0.25\textwidth]{sun211_figures/fronta}~~~~~\hfill \includegraphics[width=0.25\textwidth]{sun211_figures/frontb}~~~~~\hfill \includegraphics[width=0.25\textwidth]{sun211_figures/frontc} } \stardocabstract { The AST library provides a comprehensive range of facilities for attaching world coordinate systems to astronomical data, for retrieving and interpreting that information in a variety of formats, including FITS-WCS, and for generating graphical output based on it. This programmer's manual should be of interest to anyone writing astronomical applications which need to manipulate coordinate system data, especially celestial or spectral coordinate systems. AST is portable and environment-independent. } % ? End of document identification % ----------------------------------------------------------------------------- % ? Document specific \providecommand or \newenvironment commands. \providecommand{\appref}[1]{Appendix~\ref{#1}} \providecommand{\secref}[1]{\S\ref{#1}} \providecommand{\fitskey}[3]{{#1}&{#2}&{#3}\\} % Use {\tt ... } as \texttt{...} does not work if there are new lines in #1 \providecommand{\sstsynopsis}[1]{\sstdiytopic{Synopsis}{\tt #1}} % Format the constructor section. \providecommand{\sstconstructor}[1]{\sstdiytopic{Constructor Function}{#1}} % ? End of document specific commands % ----------------------------------------------------------------------------- % \htmlref{Title}{Title} Page. % =========== \begin{document} \scfrontmatter \begin{center} \emph{This is the C version of this document.\\ For the Fortran version, please see \xref{SUN/210}{sun210}{}.} \end{center} % Main text of document. \vspace{7mm} \section{Introduction} Welcome to the AST library. If you are writing software for astronomy and need to use celestial coordinates (\emph{e.g.}\ RA and Dec), spectral coordinates (\emph{e.g.}\ wavelength, frequency, \emph{etc.}), or other coordinate system information, then this library should be of interest. It provides solutions for most of the problems you will meet and allows you to write robust and flexible software. It is able to read and write WCS information in a variety of formats, including \htmladdnormallink{FITS-WCS}{http://fits.gsfc.nasa.gov/fits_wcs.html}. %\subsection{TBW---What is a World Coordinate \htmlref{System}{System}?} \subsection{What Problems Does AST Tackle?} Here are some of the main problems you may face when handling world coordinate system (WCS) information and the solutions that AST provides: \begin{description} \item[1. The Variety of Coordinate Systems]\mbox{}\\ Astronomers use a wide range of differing coordinate systems to describe positions within a variety of physical domains. For instance, there are a large number of celestial coordinate systems in use within astronomy to describe positions on the sky. Understanding these, and knowing how to convert coordinates between them, can require considerable expertise. It can also be difficult to decide which of them your software should support. The same applies to coordinate systems describing other domains, such as position within an electro-magnetic spectrum. \textbf{Solution.} AST has built-in knowledge of many coordinate systems and allows you to convert freely between them without specialist knowledge. This avoids the need to embed details of specific coordinate systems in your software. You also benefit automatically when new coordinate systems are added to AST. \item[2. Storing and Retrieving WCS Information]\mbox{}\\ Storing coordinate system information in astronomical datasets and retrieving it later can present a considerable challenge. Typically, it requires knowledge of rather complex conventions (\emph{e.g.}\ FITS) which are low-level, often mis-interpreted and may be subject to change. Exchanging information with other software systems is further complicated by the number of different conventions in use. \textbf{Solution.} AST combines a unifying high-level description of WCS information with the ability to save and restore this using a variety of formats. Details of the formats, which include FITS, are handled internally by AST. This frees you from the need to understand them or embed the details in your software. Again, you benefit automatically when new formats are added to AST. \item[3. Generating Graphical Output]\mbox{}\\ Producing graphical displays involving curvilinear coordinate systems, such as celestial coordinate grids, can be complicated. Particular difficulties arise when handling large areas of sky, the polar regions and discontinuous (\emph{e.g.}\ segmented) sky projections. Even just numbering and labelling curvilinear axes is rarely straightforward. \textbf{Solution.} AST provides plotting facilities especially designed for use with curvilinear coordinate systems. These include the plotting of axes and complete labelled coordinate grids. A large number of options are provided for tailoring the output to your specific needs. Three dimensional coordinate grids can also be produced. \item[4. Aligning Data from Different Sources]\mbox{}\\ One of the main uses of coordinate systems is to facilitate the inter-comparison of data from different sources. A typical use might be to plot (say) radio contours over an optical image. In practice, however, different celestial coordinate systems may have been used, making accurate alignment far from simple. \textbf{Solution} AST provides a one-step method of aligning datasets, searching for all possible intermediate coordinate systems. This makes it simple to directly inter-relate the pixel coordinates of different datasets. \item[5. Handling Different Types of Coordinate \htmlref{System}{System}]\mbox{}\\ Not all coordinate systems used in astronomy are celestial ones, so if you are writing general-purpose software such as (say) a display tool, you may also need to handle axes representing wavelength, distance, time or whatever else comes along. Obviously, you would prefer not to handle each one as a special case. \textbf{Solution} AST uses the same flexible high-level model to describe all types of coordinate system. This allows you to write software that handles different kinds of coordinate axis without introducing special cases. \end{description} \subsection{Other Design Objectives} As well as its scientific objectives, the AST library's design includes a number of technical criteria intended to make it applicable to as wide a range of projects as possible. The main considerations are described here: \begin{enumerate} \item {\bf{Minimum Software Dependencies.}} The AST library depends on no other other software\footnote{It comes with bundled copies of the ERFA and \xref{Starlink PAL libraries}{sun268}{} which are built at the same time as the other AST internal libraries. Alternatively, external PAL and ERFA libraries may be used by specifying the ``\texttt{--with-external\_pal}'' option when configuring AST}. \item {\bf{Environment Independence.}} AST is designed so that it can operate in a variety of ``programming environments'' and is not tied to any particular one. To allow this, it uses simple, flexible interfaces to obtain the following services: \begin{itemize} \item {\bf{Data Storage.}} Data I/O operations are based on text and/or FITS headers. This makes it easy to interface to a wide variety of astronomical data formats in a machine-independent way. \item {\bf{Graphics.}} Graphical output is produced \emph{via} a simple generic graphics interface, which may easily be re-implemented over different graphics systems. AST provides a default implementation based on the widely-used PGPLOT graphics system (\xref{SUN/15}{sun15}{}). \item {\bf{Error Handling.}} Error messages are written to standard error by default, but go through a simple generic interface similar to that used for graphics (above). This permits error message delivery \emph{via} other routes when necessary (\emph{e.g.} in a graphical interface). \end{itemize} \item {\bf{Multiple Language Support.}} AST has been designed to be called from more than one language. Both C and Fortran interfaces are available (see \xref{SUN/210}{sun210}{} for the Fortran version) and use from C$++$ is also straightforward if the C interface is included using: \begin{small} \begin{terminalv} extern "C" { #include "ast.h" } \end{terminalv} \end{small} A JNI interface (known as ``JNIAST'' - see \url{http://www.starlink.ac.uk/jniast/}) has also been developed by Starlink which allows AST to be used from Java. \item {\bf{\htmlref{Object}{Object} Oriented Design.}} AST uses ``object oriented'' techniques internally in order to provide a flexible and easily-extended programming model. A fairly traditional calling interface is provided, however, so that the library's facilities are easily accessible to programmers using C and Fortran. \item {\bf{Portability.}} AST is implemented entirely in ANSI standard C and, when called \emph{via} its C interface, makes no explicit use of any machine-dependent facilities. The Fortran interface is, unavoidably, machine dependent. However, the potential for problems has been minimised by encapsulating the interface layer in a compact set of C macros which facilitate its transfer to other platforms. No Fortran compiler is needed to build the library. Currently, AST is supported by Starlink on PC~Linux, Sun~Solaris and Tru64~Unix (formerly DEC~UNIX) platforms. \end{enumerate} \subsection{What Does ``AST'' Stand For?} The library name ``AST'' stands for ``ASTrometry Library''. The name arose when it was thought that knowledge of ``astrometry'' (\emph{i.e.}\ celestial coordinate systems) would form the bulk of the library. In fact, it turns out that astrometry forms only a minor component, but the name AST has stuck. \cleardoublepage \section{Overview of AST Concepts} This section presents a brief overview of AST concepts. It is intended as a basic orientation course before you move on to the more technical considerations in subsequent sections. \subsection{\label{ss:mappingoverview}Relationships Between Coordinate Systems} The relationships between coordinate systems are represented in AST by Objects called Mappings. A \htmlref{Mapping}{Mapping} does not represent a coordinate system itself, but merely the process by which you move from one coordinate system to another related one. A convenient picture of a Mapping is as a ``black box'' (Figure~\ref{fig:mapping}) into which you can feed sets of coordinates. \begin{figure}[bhtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/mapping} \caption{A Mapping viewed as a ``black box'' for transforming coordinates.} \label{fig:mapping} \end{center} \end{figure} For each set you feed in, the Mapping returns a corresponding set of transformed coordinates. Since each set of coordinates represents a point in a coordinate space, the Mapping acts to inter-relate corresponding positions in the two spaces, although what these spaces represent is unspecified. Notice that a Mapping need not have the same number of input and output coordinates. That is, the two coordinate spaces which it inter-relates need not have the same number of dimensions. In many cases, the transformation can, in principle, be performed in either direction: either from the \emph{input} coordinate space to the \emph{output}, or \emph{vice versa}. The first of these is termed the \emph{forward} transformation and the other the \emph{inverse} transformation. \textbf{Further reading:} For a more complete discussion of Mappings, see~\secref{ss:mappings}. \subsection{\label{ss:mappingselection}Mappings Available} The basic concept of a \htmlref{Mapping}{Mapping} (\secref{ss:mappingoverview}) is rather generic and obviously it is necessary to have specific Mappings that implement specific relationships between coordinate systems. AST provides a range of these, to perform transformations such as the following and, where appropriate, their inverses: \begin{itemize} \item Conversions between various celestial coordinate systems (the \htmlref{SlaMap}{SlaMap}). \item Conversions between various spectral coordinate systems (the \htmlref{SpecMap}{SpecMap} and \htmlref{GrismMap}{GrismMap}). \item Conversions between various time systems (the \htmlref{TimeMap}{TimeMap}). \item Conversion between 2-dimensional spherical celestial coordinates (longitude and latitude) and a 3-dimensional vectorial positions (the \htmlref{SphMap}{SphMap}). \item Various projections of the celestial sphere on to 2-dimensional coordinate spaces---\emph{i.e.}\ map projections (the \htmlref{DssMap}{DssMap} and \htmlref{WcsMap}{WcsMap}). \item Permutation, introduction and elimination of coordinates (the \htmlref{PermMap}{PermMap}). \item Various linear coordinate transformations (the \htmlref{MatrixMap}{MatrixMap}, \htmlref{WinMap}{WinMap}, \htmlref{ShiftMap}{ShiftMap} and \htmlref{ZoomMap}{ZoomMap}). \item General N-dimensional polynomial transformations (the \htmlref{PolyMap}{PolyMap}). \item Lookup tables (the \htmlref{LutMap}{LutMap}). \item General-purpose transformations expressed using arithmetic operations and functions similar to those available in C (the \htmlref{MathMap}{MathMap}). \item Transformations for internal use within a program, based on private transformation functions which you write yourself in C (the \htmlref{IntraMap}{IntraMap}). \end{itemize} \textbf{Further reading:} For a more complete description of each of the Mappings mentioned above, see its entry in \appref{ss:classdescriptions}. In addition, see the discussion of the PermMap in \secref{ss:permmapexample}, the \htmlref{UnitMap}{UnitMap} in \secref{ss:unitmapexample} and the IntraMap in \secref{ss:intramaps}. The ZoomMap is used as an example throughout \secref{ss:primer}. \subsection{\label{ss:cmpmapoverview}Compound Mappings} The Mappings described in \secref{ss:mappingselection} provide a set of basic building blocks from which more complex Mappings may be constructed. The key to doing this is a type of \htmlref{Mapping}{Mapping} called a \htmlref{CmpMap}{CmpMap}, or compound Mapping. A CmpMap's role is, in principle, very simple: it allows any other pair of Mappings to be joined together into a single entity which behaves as if it were a single Mapping. A CmpMap is therefore a container for another pair of Mappings. A pair of Mappings may be combined using a CmpMap in either of two ways. The first of these, \emph{in series}, is illustrated in Figure~\ref{fig:seriescmpmap}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/series} \caption[A CmpMap composed of two component Mappings joined in series]{A CmpMap (compound Mapping) composed of two component Mappings joined in series. The output coordinates of the first Mapping feed into the input coordinates of the second one, so that the whole entity behaves like a single Mapping.} \label{fig:seriescmpmap} \end{center} \end{figure} Here, the transformations implemented by each component Mapping are performed one after the other, with the output from the first Mapping feeding into the second. The second way, \emph{in parallel}, is shown in Figure~\ref{fig:parallelcmpmap}. \begin{figure} \begin{center} \includegraphics[width=0.5\textwidth]{sun211_figures/parallel} \caption[A CmpMap composed of two Mappings joined in parallel.]{A CmpMap composed of two Mappings joined in parallel. Each component Mapping acts on a complementary subset of the input and output coordinates.} \label{fig:parallelcmpmap} \end{center} \end{figure} In this case, each Mapping acts on a complementary subset of the input and output coordinates.\footnote{A pair of Mappings can be combined in a third way using a \htmlref{TranMap}{TranMap}. A TranMap allows the forward transformation of one Mapping to be combined with the inverse transformation of another to produce a single Mapping.} The CmpMap forms the key to building arbitrarily complex Mappings because it is itself a form of Mapping. This means that a CmpMap may contain other CmpMaps as components (\emph{e.g.}\ Figure~\ref{fig:complexcmpmap}). This nesting of CmpMaps can be repeated indefinitely, so that complex Mappings may be built in a hierarchical manner out of simper ones. \begin{figure} \begin{center} \includegraphics[width=0.65\textwidth]{sun211_figures/complex} \caption[CmpMaps may be nested in order to construct complex Mappings out of simpler building blocks.]{CmpMaps (compound Mappings) may be nested in order to construct complex Mappings out of simpler building blocks.} \label{fig:complexcmpmap} \end{center} \end{figure} This gives AST great flexibility in the coordinate transformations it can describe. \textbf{Further reading:} For a more complete description of CmpMaps, see \secref{ss:cmpmaps}. Also see the CmpMap entry in \appref{ss:classdescriptions}. \subsection{Representing Coordinate Systems} While Mappings (\secref{ss:mappingoverview}) represent the relationships between coordinate systems in AST, the coordinate systems themselves are represented by Objects called Frames (Figure~\ref{fig:frames}). \begin{figure} \begin{center} \includegraphics[width=0.55\textwidth]{sun211_figures/frames} \caption[Representing coordinate systems as Frames.]{(a) A basic Frame is used to represent a Cartesian coordinate system, here 2-dimensional. (b) A \htmlref{SkyFrame}{SkyFrame} represents a (spherical) celestial coordinate system. (c) The axis order of any \htmlref{Frame}{Frame} may be permuted to match the coordinate space it describes.} \label{fig:frames} \end{center} \end{figure} A Frame is similar in concept to the frame you might draw around a graph. It contains information about the labels which appear on the axes, the axis units, a title, knowledge of how to format the coordinate values on each axis, \emph{etc.} An AST Frame is not, however, restricted to two dimensions and may have any number of axes. A basic Frame may be used to represent a Cartesian coordinate system by setting values for its \emph{attributes} (all AST Objects have values associated with them called attributes, which may be set and enquired). Usually, this would involve setting appropriate axis labels and units, for example. Functions are provided for use with Frames to perform operations such as formatting coordinate values as text, calculating distances between points, interchanging axes, \emph{etc.} There are several more specialised forms of Frame, which provide the additional functionality required when handling coordinates within some specific physical domain. This ranges from tasks such as formatting axis values, to complex tasks such as determining the transformation between any pair of related coordinate systems. For instance, the SkyFrame (Figure~\ref{fig:frames}b,c), represents celestial coordinate systems, the \htmlref{SpecFrame}{SpecFrame} represents spectral coordinate systems, and the \htmlref{TimeFrame}{TimeFrame} represents time coordinate systems. All these provide a wide range of different systems for describing positions within their associated physical domain, and these may be selected by setting appropriate attributes. As with compound Mappings (\secref{ss:cmpmapoverview}), it is possible to merge two Frames together to form a compound Frame, or \htmlref{CmpFrame}{CmpFrame}, in which both sets of axes are combined. One could, for example, have celestial coordinates on two axes and an unrelated coordinate (wavelength, perhaps) on a third (Figure~\ref{fig:cmpframe}). Knowledge of the relationships between the axes is preserved internally by the process of constructing the CmpFrame which represents them. \begin{figure} \begin{center} \includegraphics[width=0.4\textwidth]{sun211_figures/cmpframe} \caption[A CmpFrame (compound Frame) formed by combining two simpler Frames.]{A CmpFrame (compound Frame) formed by combining two simpler Frames. Note how the special relationship which exists between the RA and Dec axes is preserved within this data structure. As with compound Mappings (Figure~\ref{fig:complexcmpmap}), CmpFrames may be nested in order to build more complex Frames.} \label{fig:cmpframe} \end{center} \end{figure} \textbf{Further reading:} For a more complete description of Frames see \secref{ss:frames}, for SkyFrames see \secref{ss:skyframes} and for SpecFrames see \secref{ss:specframes}. Also see the Frame, SkyFrame, SpecFrame, TimeFrame and CmpFrame entries in \appref{ss:classdescriptions}. \subsection{Networks of Coordinate Systems} Mappings and Frames may be connected together to form networks called FrameSets, which are used to represent sets of inter-related coordinate systems (Figure~\ref{fig:frameset}). \begin{figure} \begin{center} \includegraphics[width=0.65\textwidth]{sun211_figures/frameset} \caption[A FrameSet is a network of Frames.]{A FrameSet is a network of Frames inter-connected by Mappings such that there is exactly one conversion path, \emph{via} Mappings, between any pair of Frames.} \label{fig:frameset} \end{center} \end{figure} A \htmlref{FrameSet}{FrameSet} may be extended by adding a new \htmlref{Frame}{Frame} to it, together with an associated \htmlref{Mapping}{Mapping} which relates the new coordinate system to one which is already present. This process ensures that there is always exactly one path, \emph{via} Mappings, between any pair of Frames. A function is provided for identifying this path and returning the complete Mapping. One of the Frames in a FrameSet is termed its \emph{base} Frame. This underlies the FrameSet's purpose, which is to calibrate datasets and other entities by attaching coordinate systems to them. In this context, the base Frame represents the ``native'' coordinate system (for example, the pixel coordinates of an image). Similarly, one Frame is termed the \emph{current} Frame and represents the ``currently-selected'' coordinates. It might, typically, be a celestial or spectral coordinate system and would be used during interactions with a user, as when plotting axes on a graph or producing a table of results. Other Frames within the FrameSet represent a library of alternative coordinate systems which a software user can select by making them current. \textbf{Further reading:} For a more complete description of FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. Also see the FrameSet entry in \appref{ss:classdescriptions}. \subsection{Input/Output Facilities} AST allows you to convert any kind of \htmlref{Object}{Object} into a stream of text which contains a full description of that Object. This text may be written out by one program and read back in by another, thus allowing the original Object to be reconstructed. The filter which converts Objects into text and back again is itself a kind of Object, called a \htmlref{Channel}{Channel}. A Channel provides a number of options for controlling the information content of the text, such as the addition of comments for human interpretation. It is also possible to intercept the text being processed by a Channel so that it may be redirected to/from any chosen external data store, such as a text file, an astronomical dataset, or a network connection. The text format used by the basic Channel class is peculiar to the AST library - no other software will understand it. However, more specialised forms of Channel are provided which use text formats more widely understood. To further facilitate the storage of coordinate system information in astronomical datasets, a more specialised form of Channel called a \htmlref{FitsChan}{FitsChan} is provided. Instead of using free-format text, a FitsChan converts AST Objects to and from FITS header cards. It also allows the information to be encoded in the FITS cards in a number of ways (called \emph{encodings}), so that WCS information from a variety of sources can be handled. Another sub-class of Channel, called \htmlref{XmlChan}{XmlChan}, is a specialised form of Channel that stores the text in the form of XML markup. Currently, two markup formats are provided by the XmlChan class, one is closely related to the text format produced by the basic Channel class (currently, no schema or DTD is available describing this format). The other is a subset of an early draft of the IVOA Space-Time-Coordinates XML (STC-X) schema (V1.20) described at \url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html }\footnote{XML documents which use only the subset of the STC schema supported by AST can be read by the XmlChan class to produce corresponding AST objects (subclasses of the \htmlref{Stc}{Stc} class). However, the reverse is not possible. That is, AST objects can not currently be written out in the form of STC documents.}. The version of STC-X that has been adopted by the IVOA differs in several significant respects from V1.20, and therefore this XmlChan format is of historical interest only. Finally, the \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing IVOA STC-S region descriptions. STC-S (see \url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string syntax that allows simple specification of STC metadata. AST supports a subset of the STC-S specification, allowing an STC-S description of a region within an AST-supported astronomical coordinate system to be converted into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. \textbf{Further reading:} For a more complete description of Channels see \secref{ss:channels} and for FitsChans see \secref{ss:nativefits} and \secref{ss:foreignfits}. Also see the Channel and FitsChan entries in \appref{ss:classdescriptions} and the \htmlref{Encoding}{Encoding} entry in \appref{ss:attributedescriptions}. \subsection{Producing Graphical Output} Two dimensional graphical output is supported by a specialised form of \htmlref{FrameSet}{FrameSet} called a \htmlref{Plot}{Plot}, whose base \htmlref{Frame}{Frame} corresponds with the native coordinates of the underlying graphics system. Plotting operations are specified in \emph{physical coordinates} which correspond with the Plot's current Frame. Typically, this might be a celestial coordinate system. Three dimensional plotting is also supported, via the \htmlref{Plot3D}{Plot3D} class - sub-class of Plot. Operations, such as drawing lines, are automatically transformed from physical to graphical coordinates before plotting, using an adaptive algorithm which ensures smooth curves (because the transformation is usually non-linear). ``Missing'' coordinates (\emph{e.g.}\ graphical coordinates which do not project on to the celestial sphere), discontinuities and generalised clipping are all consistently handled. It is possible, for example, to plot in equatorial coordinates and clip in galactic coordinates. The usual plotting operations are provided (text, markers), but a geodesic curve replaces the primitive straight line element. There is also a separate function for drawing axis lines, since these are normally not geodesics. In addition to drawing coordinate grids over an area of the sky, another common use of the Plot class is to produce line plots such as flux against wavelength, displacement again time, \emph{etc}. For these situations the current Frame of the Plot would be a compound Frame (\htmlref{CmpFrame}{CmpFrame}) containing a pair of 1-dimensional Frames - the first representing the X axis quantity (wavelength, time, etc), and the second representing the Y axis quantity (flux, displacement, etc). The Plot class includes an option for axes to be plotted logarithmically. Perhaps the most useful graphics function available is for drawing fully annotated coordinate grids (\emph{e.g.}\ Figure~\ref{fig:gridplot}). \begin{figure} \begin{center} \includegraphics[width=0.6\textwidth]{sun211_figures/gridplot_bw} \caption[A labelled coordinate grid for an all-sky zenithal equal area projection in ecliptic coordinates.]{A labelled coordinate grid for an all-sky zenithal equal area projection in ecliptic coordinates. This was composed and drawn \emph{via} a Plot using a single function call.} \label{fig:gridplot} \end{center} \end{figure} This uses a general algorithm which does not depend on knowledge of the coordinates being represented, so can also handle programmer-defined coordinate systems. Grids for all-sky projections, including polar regions, can be drawn and most aspects of the output (colour, line style, \emph{etc.}) can be adjusted by setting appropriate Plot attributes. \textbf{Further reading:} For a more complete description of Plots and how to produce graphical output, see \secref{ss:plots}. Also see the Plot entry in \appref{ss:classdescriptions}. \cleardoublepage \section{\label{ss:howto}How To\ldots} For those of you with a plane to catch, this section provides some instant templates and recipes for performing the most commonly-required operations using AST, but without going into detail. The examples given (sort of) follow on from each other, so you should be able to construct a variety of programs by piecing them together. Note that some of them appear longer than they actually are, because we have included plenty of comments and a few options that you probably won't need. If any of this material has you completely baffled, then you may want to read the introduction to AST programming concepts in \secref{ss:primer} first. Otherwise, references to more detailed reading are given after each example, just in case they don't quite do what you want. \subsection{\ldots Obtain and Install AST} The AST library is available both as a stand-alone package and also as part of the Starlink Software Collection\footnote{The Starlink Software Collection can be downloaded from \url{http://www.starlink.ac.uk/Download/}.}. If your site has the Starlink Software Collection installed then AST should already be available. If not, you can download the AST library by itself from \url{http://www.starlink.ac.uk/ast/}. \subsection{\ldots Structure an AST Program} An AST program normally has the following structure: \begin{small} \begin{terminalv} /* Include the interface to the AST library. */ #include "ast.h" /* Main program (or could be any function). */ main () { /* Enclose the parts which use AST between the astBegin and astEnd macros. */ astBegin; astEnd; } \end{terminalv} \end{small} The use of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} is optional, but has the effect of tidying up after you have finished using AST, so is normally recommended. For more details of this, see \secref{ss:contexts}. For details of how to access the ``ast.h'' header file, see \secref{ss:accessingheaderfile}. \subsection{\label{ss:howtobuild}\ldots Build an AST Program} To build a simple AST program that doesn't use graphics, use: \begin{small} \begin{terminalv} cc program.c -L/star/lib -I/star/include `ast_link` -o program \end{terminalv} \end{small} To build a program which uses PGPLOT for graphics, use: \begin{small} \begin{terminalv} cc program.c -L/star/lib `ast_link -pgplot` -o program \end{terminalv} \end{small} For more details about accessing the ``ast.h'' header file, see \secref{ss:accessingheaderfile}. For more details about linking programs, see \secref{ss:linking} and the description of the ``\htmlref{ast\_link}{ast\_link}'' command in \appref{ss:commanddescriptions}. \subsection{\label{ss:howtoreadwcs}\ldots Read a WCS Calibration from a Dataset} Precisely how you extract world coordinate system (WCS) information from a dataset obviously depends on what type of dataset it is. Usually, however, you should be able to obtain a set of FITS header cards which contain the WCS information (and probably much more besides). Suppose that ``cards'' is a pointer to a string containing a complete set of concatenated FITS header cards (such as produced by the CFITSIO function fits\_hdr2str). Then proceed as follows: \begin{small} \begin{terminalv} fitsfile *fptr; AstFitsChan *fitschan; AstFrameSet *wcsinfo; char *header; int nkeys, status; ... /* Obtain all the cards in the header concatenated into a single dynamically allocated null-terminated character string. Note, we do not exclude any cards since we may later modify the WCS information within the header and consequently want to write the entire header out again. */ if( fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) printf(" Error getting header\n"); ... /* Header obtained succesfully... */ } else { /* Create a FitsChan and fill it with FITS header cards. */ fitschan = astFitsChan( NULL, NULL, "" ); astPutCards( fitschan, header ); /* Free the memory holding the concatenated header cards. */ header = free( header ); /* Read WCS information from the FitsChan. */ wcsinfo = astRead( fitschan ); ... \end{terminalv} \end{small} The result should be a pointer, ``wcsinfo'', to a \htmlref{FrameSet}{FrameSet} which contains the WCS information. This pointer can now be used to perform many useful tasks, some of which are illustrated in the following recipes. Some datasets which do not easily yield FITS header cards may require a different approach, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} (\secref{ss:channels}) rather than a \htmlref{FitsChan}{FitsChan}. In the case of the Starlink NDF data format, for example, all the above may be replaced by a single call to the function \xref{ndfGtwcs}{sun33}{ndfGtwcs}---see \xref{SUN/33}{sun33}{}. The whole process can probably be encapsulated in a similar way for most data systems, whether they use FITS header cards or not. For more details about reading WCS information from datasets, see \secref{ss:identifyingfitsencoding} and \secref{ss:readingforeignfits}. For a more general description of FitsChans and their use with FITS header cards, see \secref{ss:nativefits} and \secref{ss:foreignfits}. For more details about FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. \subsection{\ldots Validate WCS Information} Once you have read WCS information from a dataset, as in \secref{ss:howtoreadwcs}, you may wish to check that you have been successful. The following will detect and classify the things that might possibly go wrong: \begin{small} \begin{terminalv} #include ... if ( !astOK ) { } else if ( wcsinfo == AST__NULL ) { } else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { } else { } \end{terminalv} \end{small} For more information about detecting errors in AST functions, see \secref{ss:errordetection}. For details of how to validate input data read by AST, see \secref{ss:validatinginput} and \secref{ss:readingforeignfits}. \subsection{\ldots Display AST Data} If you have a pointer to any AST \htmlref{Object}{Object}, you can display the data stored in that Object in textual form as follows: \begin{small} \begin{terminalv} astShow( wcsinfo ); \end{terminalv} \end{small} Here, we have used a pointer to the \htmlref{FrameSet}{FrameSet} which we read earlier (\secref{ss:howtoreadwcs}). The result is written to the program's standard output stream. This can be very useful during debugging. For more details about using \htmlref{astShow}{astShow}, see \secref{ss:displayingobjects}. For information about interpreting the output, also see \secref{ss:textualoutputformat}. \subsection{\label{ss:howtotransform}\ldots Convert Between Pixel and World Coordinates} You may use a pointer to a \htmlref{FrameSet}{FrameSet}, such as we read in \secref{ss:howtoreadwcs}, to transform a set of points between the pixel coordinates of an image and the associated world coordinates. If you are working in two dimensions, proceed as follows: \begin{small} \begin{terminalv} double xpixel[ N ], ypixel[ N ]; double xworld[ N ], yworld[ N ]; ... astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); \end{terminalv} \end{small} Here, N is the number of points to be transformed, ``xpixel'' and ``ypixel'' hold the pixel coordinates, and ``xworld'' and ``yworld'' receive the returned world coordinates.\footnote{By pixel coordinates, we mean a coordinate system in which the first pixel in the image is centred on (1,1) and each pixel is a unit square. Note that the world coordinates will not necessarily be celestial coordinates, but if they are, then they will be in radians.} To transform in the opposite direction, interchange the two pairs of arrays (so that the world coordinates are given as input) and change the fifth argument of \htmlref{astTran2}{astTran2} to zero. To transform points in one dimension, use \htmlref{astTran1}{astTran1}. In any other number of dimensions (or if the number of dimensions is initially unknown), use \htmlref{astTranN}{astTranN} or \htmlref{astTranP}{astTranP}. These functions are described in \appref{ss:functiondescriptions}. For more information about transforming coordinates, see \secref{ss:transforming} and \secref{ss:framesetasmapping}. For details of how to handle missing coordinates, see \secref{ss:badcoordinates}. \subsection{\label{ss:howtotestforcelestial}\ldots Test if a WCS is a Celestial Coordinate System} The world coordinate system (WCS) currently associated with an image may often be a celestial coordinate system, but this need not necessarily be the case. For instance, instead of right ascension and declination, an image might have a WCS with axes representing wavelength and slit position, or maybe just plain old pixels. If you have obtained a WCS calibration for an image, as in \secref{ss:howtoreadwcs}, in the form of a pointer ``wcsinfo'' to a \htmlref{FrameSet}{FrameSet}, then you may determine if the current coordinate system is a celestial one or not, as follows: \begin{small} \begin{terminalv} AstFrame *frame; int issky; ... /* Obtain a pointer to the current Frame and determine if it is a SkyFrame. */ frame = astGetFrame( wcsinfo, AST__CURRENT ); issky = astIsASkyFrame( frame ); frame = astAnnul( frame ); \end{terminalv} \end{small} This will set ``issky'' to 1 if the WCS is a celestial coordinate system, and to zero otherwise. \subsection{\label{ss:howtotestforspectral}\ldots Test if a WCS is a Spectral Coordinate System} Testing for a spectral coordinate system is basically the same as testing for a celestial coordinate system (see the previous section). The one difference is that you use the astIsASpecFrame function in place of the astIsASkyFrame function. \subsection{\label{ss:howtoformatcoordinates}\ldots Format Coordinates for Display} Once you have converted pixel coordinates into world coordinates (\secref{ss:howtotransform}), you may want to format them as text before displaying them. Typically, this would convert from (say) radians into something more comprehensible. Using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in \secref{ss:howtoreadwcs} and a pair of world coordinates ``xw'' and ``yw'' (\emph{e.g.}\ see \secref{ss:howtotransform}), you could proceed as follows: \begin{small} \begin{terminalv} #include const char *xtext, *ytext; double xw, yw; ... xtext = astFormat( wcsinfo, 1, xw ); ytext = astFormat( wcsinfo, 2, yw ); (void) printf( "Position = %s, %s\n", xtext, ytext ); \end{terminalv} \end{small} Here, the second argument to \htmlref{astFormat}{astFormat} is the axis number. With celestial coordinates, this will usually result in sexagesimal notation, such as ``12:34:56.7''. However, the same method may be applied to any type of coordinates and appropriate formatting will be employed. For more information about formatting coordinate values and how to control the style of formatting used, see \secref{ss:formattingaxisvalues} and \secref{ss:formattingskyaxisvalues}. If necessary, also see \secref{ss:normalising} for details of how to ``normalise'' a set of coordinates so that they lie within the standard range (\emph{e.g.}\ 0 to 24 hours for right ascension and $\pm 90^\circ$ for declination). \subsection{\ldots Display Coordinates as they are Transformed} In addition to formatting coordinates as part of a program's output, you may also want to examine coordinate values while debugging your program. To save time, you can ``eavesdrop'' on the coordinate values being processed every time they are transformed. For example, when using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in \secref{ss:howtoreadwcs} to transform coordinates (\secref{ss:howtotransform}), you could inspect the coordinate values as follows: \begin{small} \begin{terminalv} astSet( wcsinfo, "Report=1" ); astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); \end{terminalv} \end{small} By setting the FrameSet's \htmlref{Report}{Report} attribute to 1, coordinate transformations are automatically displayed on the program's standard output stream, appropriately formatted, for example: \begin{terminalv} (42.1087, 20.2717) --> (2:06:03.0, 34:22:39) (43.0197, 21.1705) --> (2:08:20.6, 35:31:24) (43.9295, 22.0716) --> (2:10:38.1, 36:40:09) (44.8382, 22.9753) --> (2:12:55.6, 37:48:55) (45.7459, 23.8814) --> (2:15:13.1, 38:57:40) (46.6528, 24.7901) --> (2:17:30.6, 40:06:25) (47.5589, 25.7013) --> (2:19:48.1, 41:15:11) (48.4644, 26.6149) --> (2:22:05.6, 42:23:56) (49.3695, 27.5311) --> (2:24:23.1, 43:32:41) (50.2742, 28.4499) --> (2:26:40.6, 44:41:27) \end{terminalv} For a complete description of the Report attribute, see its entry in \appref{ss:attributedescriptions}. For further details of how to set and enquire attribute values, see \secref{ss:settingattributes} and \secref{ss:gettingattributes}. \subsection{\ldots Read Coordinates Entered by a User} In addition to writing out coordinate values generated by your program (\secref{ss:howtoformatcoordinates}), you may also need to accept coordinates entered by a user, or perhaps read from a file. In this case, you will probably want to allow ``free-format'' input, so that the user has some flexibility in the format that can be used. You will probably also want to detect any typing errors. Let's assume that you want to read a number of lines of text, each containing the world coordinates of a single point, and to split each line into individual numerical coordinate values. Using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained earlier (\secref{ss:howtoreadwcs}), you could proceed as follows: \begin{small} \begin{terminalv} #include char *t; char text[ MAXCHARS + 2 ]; double coord[ 10 ]; int iaxis, n, naxes; ... /* Obtain the number of coordinate axes (if not already known). */ naxes = astGetI( wcsinfo, "Naxes" ); /* Loop to read each line of input text, in this case from the standard input stream (your programming environment will probably provide a better way of reading text than this). Set the pointer "t" to the start of each line read. */ while ( t = fgets( text, MAXCHARS + 2, stdin ) ) { /* Attempt to read a coordinate for each axis. */ for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { n = astUnformat( wcsinfo, iaxis, t, &coord[ iaxis - 1 ] ); /* If nothing was read and this is not the first axis or the end-of-string, try stepping over a separator and reading again. */ if ( !n && ( iaxis > 1 ) && *t ) n = astUnformat( wcsinfo, iaxis, ++t, &coord[ iaxis - 1 ] ); /* Quit if nothing was read, otherwise move on to the next coordinate. */ if ( !n ) break; t += n; } /* Test for the possible errors that may occur... */ /* Error detected by AST (a message will have been issued). */ if ( !astOK ) { break; /* Error in input data at character t[n]. */ } else if ( *t || !n ) { break; } else { } } \end{terminalv} \end{small} This algorithm has the advantage of accepting free-format input in whatever style is appropriate for the world coordinates in use (under the control of the FrameSet whose pointer you provide). For example, wavelength values might be read as floating point numbers (\emph{e.g.}\ ``1.047'' or ``4787''), whereas celestial positions could be given in sexagesimal format (\emph{e.g.}\ ``12:34:56'' or ``12~34.5'') and would be converted into radians. Individual coordinate values may be separated by white space and/or any non-ambiguous separator character, such as a comma. For more information on reading coordinate values using the \htmlref{astUnformat}{astUnformat} function, see \secref{ss:unformattingaxisvalues}. For details of how sexagesimal formats are handled, and the forms of input that may be used for celestial coordinates, see \secref{ss:unformattingskyaxisvalues}. \subsection{\label{ss:howtocreatenewwcs}\ldots Create a New WCS Calibration} This section describes how to add a WCS calibration to a data set which you are creating from scratch, rather than modifying an existing data set. In most common cases, the simplest way to create a new WCS calibration from scratch is probably to create a set of strings describing the required calibration in terms of the keywords used by the FITS WCS standard, and then convert these strings into an AST \htmlref{FrameSet}{FrameSet} describing the calibration. This FrameSet can then be used for many other purposes, or simply stored in the data set. The full FITS-WCS standard is quite involved, currently running to four separate papers, but the basic kernel is quite simple, involving the following keywords (all of which end with an integer axis index, indicated below by $$): \begin{description} \item[CRPIX]\mbox{}\\ hold the pixel coordinates at a reference point \item[CRVAL]\mbox{}\\ hold the corresponding WCS coordinates at the reference point \item[CTYPE]\mbox{}\\ name the quantity represented by the WCS axes, together with the projection algorithm used to convert the scaled and rotated pixel coordinates to WCS coordinates. \item[CD\_]\mbox{}\\ a set of keywords which specify the elements of a matrix. This matrix scales pixel offsets from the reference point into the offsets required as input by the projection algorithm specified by the CTYPE keywords. This matrix specifies the scale and rotation of the image. If there is no rotation the off-diagonal elements of the matrix (\emph{e.g.} CD1\_2 and CD2\_1) can be omitted. \end{description} As an example consider the common case of a simple 2D image of the sky in which north is parallel to the second pixel axis and east parallel to the (negative) first pixel axis. The image scale is 1.2 arc-seconds per pixel on both axes, and the image is presumed to have been obtained with a tangent plane projection. Furthermore, it is known that pixel coordinates (100.5,98.4) correspond to an RA of 11:00:10 and a Dec. of -23:26:02. A suitable set of FITS-WCS header cards could be: \begin{small} \begin{terminalv} CTYPE1 = 'RA---TAN' / Axis 1 represents RA with a tan projection CTYPE2 = 'DEC--TAN' / Axis 2 represents Dec with a tan projection CRPIX1 = 100.5 / Pixel coordinates of reference point CRPIX2 = 98.4 / Pixel coordinates of reference point CRVAL1 = 165.04167 / Degrees equivalent of "11:00:10" hours CRVAL2 = -23.433889 / Decimal equivalent of "-23:26:02" degrees CD1_1 = -0.0003333333 / Decimal degrees equivalent of -1.2 arc-seconds CD2_2 = 0.0003333333 / Decimal degrees equivalent of 1.2 arc-seconds \end{terminalv} \end{small} Notes: \begin{itemize} \item a FITS header card begins with the keyword name starting at column 1, has an equals sign in column 9, and the keyword value in columns 11 to 80. \item string values must be enclosed in single quotes. \item celestial longitude and latitude must both be specified in decimal degrees. \item the CD1\_1 value is negative to indicate that RA increases as the first pixel axis decreases. \item the (RA,Dec) coordinates will be taken as ICRS coordinates. For FK5 you should add: \begin{small} \begin{terminalv} RADESYS = 'FK5' EQUINOX = 2005.6 \end{terminalv} \end{small} The EQUINOX value defaults to J2000.0 if omitted. FK4 can also be used in place of FK5, in which case EQUINOX defaults to B1950.0. \end{itemize} Once you have created these FITS-WCS header card strings, you should store them in a \htmlref{FitsChan}{FitsChan} and then read the corresponding FrameSet from the FitsChan. How to do this is described in \secref{ss:howtoreadwcs}. Having created the WCS calibration, you may want to store it in a data file. How to do this is described in \secref{ss:howtowritewcs}).\footnote{If you are writing the WCS calibration to a FITS file you obviously have the choice of storing the FITS-WCS cards directly.} If the required WCS calibration cannot be described as a set of FITS-WCS headers, then a different approach is necessary. In this case, you should first create a \htmlref{Frame}{Frame} describing pixel coordinates, and store this Frame in a new FrameSet. You should then create a new Frame describing the world coordinate system. This Frame may be a specific subclass of Frame such as a \htmlref{SkyFrame}{SkyFrame} for celestial coordinates, a \htmlref{SpecFrame}{SpecFrame} for spectral coordinates, a Timeframe for time coordinates, or a \htmlref{CmpFrame}{CmpFrame} for a combination of different coordinates. You also need to create a suitable \htmlref{Mapping}{Mapping} which transforms pixel coordinates into world coordinates. AST provides many different types of Mappings, all of which can be combined together in arbitrary fashions to create more complicated Mappings. The WCS Frame should then be added into the FrameSet, using the Mapping to connect the WCS Frame with the pixel Frame. \subsection{\label{ss:howtomodifywcs}\ldots Modify a WCS Calibration} The usual reason for wishing to modify the WCS calibration associated with a dataset is that the data have been geometrically transformed in some way (here, we will assume a 2-dimensional image dataset). This causes the image features (stars, galaxies, \emph{etc.}) to move with respect to the grid of pixels which they occupy, so that any coordinate systems previously associated with the image become invalid. To correct for this, it is necessary to set up a \htmlref{Mapping}{Mapping} which expresses the positions of image features in the new data grid in terms of their positions in the old grid. In both cases, the grid coordinates we use will have the first pixel centred at (1,1) with each pixel being a unit square. AST allows you to correct for any type of geometrical transformation in this way, so long as a suitable Mapping to describe it can be constructed. For purposes of illustration, we will assume here that the new image coordinates ``xnew'' and ``ynew'' can be expressed in terms of the old coordinates ``xold'' and ``yold'' as follows: \begin{small} \begin{terminalv} double xnew, xold, ynew, yold; double m[ 4 ], z[ 2 ]; ... xnew = xold * m[ 0 ] + yold * m[ 1 ] + z[ 0 ]; ynew = xold * m[ 2 ] + yold * m[ 3 ] + z[ 1 ]; \end{terminalv} \end{small} where ``m'' is a 2$\times$2 transformation matrix and ``z'' represents a shift of origin. This is therefore a general linear coordinate transformation which can represent displacement, rotation, magnification and shear. In AST, it can be represented by concatenating two Mappings. The first is a \htmlref{MatrixMap}{MatrixMap}, which implements the matrix multiplication. The second is a \htmlref{WinMap}{WinMap}, which linearly transforms one coordinate window on to another, but will be used here simply to implement the shift of origin (alternatively, a \htmlref{ShiftMap}{ShiftMap} could have been used in place of a WinMap). These Mappings may be constructed and concatenated as follows: \begin{small} \begin{terminalv} AstCmpMap *newmap; AstMatrixMap *matrixmap; AstWinMap *winmap; ... /* The MatrixMap may be constructed directly from the matrix "m". */ matrixmap = astMatrixMap( 2, 2, 0, m, "" ); /* For the WinMap, we set up the coordinates of the corners of a unit square (window) and then the same square shifted by the required amount. */ { double ina[] = { 0.0, 0.0 }; double inb[] = { 1.0, 1.0 }; double outa[] = { z[ 0 ], z[ 1 ] }; double outb[] = { 1.0 + z[ 0 ], 1.0 + z[ 1 ] }; /* The WinMap will then implement this shift. */ winmap = astWinMap( 2, ina, inb, outa, outb, "" ); } /* Join the two Mappings together, so that they are applied one after the other. */ newmap = astCmpMap( matrixmap, winmap, 1, "" ); \end{terminalv} \end{small} You might, of course, create any other form of Mapping depending on the type of geometrical transformation involved. For an overview of the Mappings provided by AST, see \secref{ss:mappingselection}, and for a description of the capabilities of each class of Mapping, see its entry in \appref{ss:classdescriptions}. For an overview of how individual Mappings may be combined, see \secref{ss:cmpmapoverview} (\secref{ss:cmpmaps} gives more details). Assuming you have obtained a WCS calibration for your original image in the form of a pointer to a \htmlref{FrameSet}{FrameSet}, ``wcsinfo1'' (\secref{ss:howtoreadwcs}), the Mapping created above may be used to produce a calibration for the new image as follows: \begin{small} \begin{terminalv} AstFrameSet *wcsinfo1, *wcsinfo2; ... /* If necessary, make a copy of the WCS calibration, since we are about to alter it. */ wcsinfo2 = astCopy( wcsinfo1 ); /* Re-map the base Frame so that it refers to the new data grid instead of the old one. */ astRemapFrame( wcsinfo2, AST__BASE, newmap ); \end{terminalv} \end{small} This will produce a pointer, ``wcsinfo2'', to a new FrameSet in which all the coordinate systems associated with your original image are modified so that they are correctly registered with the new image instead. For more information about re-mapping the Frames within a FrameSet, see \secref{ss:remapframe}. Also see \secref{ss:wcsprocessingexample} for a similar example to the above, applicable to the case of reducing the size of an image by binning. \subsection{\label{ss:howtowritewcs}\ldots Write a Modified WCS Calibration to a Dataset} If you have modified the WCS calibration associated with a dataset, such as in the example above (\secref{ss:howtomodifywcs}), then you will need to write the modified version out along with any new data. In the same way as when reading a WCS calibration (\secref{ss:howtoreadwcs}), how you do this will depend on your data system, but we will assume that you wish to generate a set of FITS header cards that can be stored with the data. You should usually make preparations for doing this when you first read the WCS calibration from your input dataset by modifying the example given in \secref{ss:howtoreadwcs} as follows: \begin{small} \begin{terminalv} AstFitsChan *fitschan1; AstFrameSet *wcsinfo1; const char *encode; ... /* Create an input FitsChan and fill it with FITS header cards. Note, if you have all the header cards in a single string, use astPutCards in place of astPutFits. */ fitschan1 = astFitsChan( NULL, NULL, "" ); for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan1, cards[ icard ], 0 ); /* Note which encoding has been used for the WCS information. */ encode = astGetC( fitschan1, "Encoding" ); /* Rewind the input FitsChan and read the WCS information from it. */ astClear( fitschan1, "Card" ); wcsinfo1 = astRead( fitschan1 ); \end{terminalv} \end{small} Note how we have added an enquiry to determine how the WCS information is encoded in the input FITS cards, storing a pointer to the resulting string in the ``encode'' variable. This must be done \textbf{before} actually reading the WCS calibration. \emph{(\textbf{N.B.}\ If you will be making extensive use of astGetC in your program, then you should allocate a buffer and make a copy of this string, because the pointer returned by astGetC will only remain valid for 50 invocations of the function, and you will need to use the \htmlref{Encoding}{Encoding} value again later on.)} Once you have produced a modified WCS calibration for the output dataset (\emph{e.g.}\ \secref{ss:howtomodifywcs}), in the form of a \htmlref{FrameSet}{FrameSet} identified by the pointer ``wcsinfo2'', you can produce a new \htmlref{FitsChan}{FitsChan} containing the output FITS header cards as follows: \small \begin{terminalv} AstFitsChan *fitschan2; AstFrameSet *wcsinfo2; ... /* Make a copy of the input FitsChan, AFTER the WCS information has been read from it. This will propagate all the input FITS header cards, apart from those describing the input WCS calibration. */ fitschan2 = astCopy( fitschan1 ); /* If necessary, make modifications to the cards in "fitschan2" (e.g. you might need to change NAXIS1, NAXIS2, etc., to account for a change in image size). You probably only need to do this if your data system does not provide these facilities itself. */
/* Alternatively, if your data system handles the propagation of FITS header cards to the output dataset for you, then simply create an empty FitsChan to contain the output WCS information alone. fitschan2 = astFitsChan( NULL, NULL, "" ); */ /* Rewind the new FitsChan (if necessary) and attempt to write the output WCS information to it using the same encoding method as the input dataset. */ astSet( fitschan2, "Card=1, Encoding=%s", encode ); if ( !astWrite( fitschan2, wcsinfo2 ) ) { /* If this didn't work (the WCS FrameSet has become too complex), then use the native AST encoding instead. */ astSet( fitschan2, "Encoding=NATIVE" ); (void) astWrite( fitschan2, wcsinfo2 ); } \end{terminalv} \normalsize For details of how to modify the contents of the output FitsChan in other ways, such as by adding, over-writing or deleting header cards, see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and \secref{ss:findingandchangingfits}. Once you have assembled the output FITS cards, you may retrieve them from the FitsChan that contains them as follows: \small \begin{terminalv} #include char card[ 81 ]; ... astClear( fitschan2, "Card" ); while ( astFindFits( fitschan2, "%f", card, 1 ) ) (void) printf( "%s\n", card ); \end{terminalv} \normalsize Here, we have simply written each card to the standard output stream, but you would obviously replace this with a function invocation to store the cards in your output dataset. For data systems that do not use FITS header cards, a different approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} (\secref{ss:channels}) rather than a FitsChan. In the case of the Starlink NDF data format, for example, all of the above may be replaced by a single call to the function \xref{ndfPtwcs}{sun33}{ndfPtwcs}---see \xref{SUN/33}{sun33}{}. The whole process can probably be encapsulated in a similar way for most data systems, whether they use FITS header cards or not. For an overview of how to propagate WCS information through data processing steps, see \secref{ss:propagatingwcsinformation}. For more information about writing WCS information to FitsChans, see \secref{ss:writingnativefits} and \secref{ss:writingforeignfits}. For information about the options for encoding WCS information in FITS header cards, see \secref{ss:nativeencoding}, \secref{ss:foreignencodings}, and the description of the Encoding attribute in \appref{ss:attributedescriptions}. For a complete understanding of FitsChans and their use with FITS header cards, you should read \secref{ss:nativefits} and \secref{ss:foreignfits}. \subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid} A common requirement when displaying image data is to plot an associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid}) over the displayed image. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/overgrid_bw} \caption[An example of a displayed image with a coordinate grid plotted over it.]{An example of a displayed image with a coordinate grid plotted over it.} \label{fig:overgrid} \end{center} \end{figure} The use of AST in such circumstances is independent of the underlying graphics system, so starting up the graphics system, setting up a coordinate system, displaying the image, and closing down afterwards can all be done using the graphics functions you would normally use. However, displaying an image at a precise location can be a little fiddly with some graphics systems, and obviously the grid drawn by AST will not be accurately registered with the image unless this is done correctly. In the following template, we therefore illustrate both steps, basing the image display on the C interface to the PGPLOT graphics package.\footnote{An interface is provided with AST that allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics, although interfaces to other graphics systems may also be written.} Plotting a coordinate grid with AST then becomes a relatively minor part of what is almost a complete graphics program. Once again, we assume that a pointer, ``wcsinfo'', to a suitable \htmlref{FrameSet}{FrameSet} associated with the image has already been obtained (\secref{ss:howtoreadwcs}). \small \begin{terminalv} #include "cpgplot.h" AstPlot *plot; const float *data; float hi, lo, scale, x1, x2, xleft, xright, xscale; float y1, y2, ybottom, yscale, ytop; int nx, ny; ... /* Access the image data, which we assume has dimension sizes "nx" and "ny", and will be accessed via the "data" pointer. Also derive limits for scaling it, which we assign to the variables "hi" and "lo". */ /* Open PGPLOT using the device given by environment variable PGPLOT_DEV and check for success. */ if( cpgbeg( 0, " ", 1, 1 ) == 1 ) { /* Clear the screen and ensure equal scales on both axes. */ cpgpage(); cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f ); /* Obtain the extent of the plotting area (not strictly necessary for PGPLOT, but possibly for other graphics systems). From this, derive the display scale in graphics units per pixel so that the image will fit within the display area. */ cpgqwin( &x1, &x2, &y1, &y2 ); xscale = ( x2 - x1 ) / nx; yscale = ( y2 - y1 ) / ny; scale = ( xscale < yscale ) ? xscale : yscale; /* Calculate the extent of the area in graphics units that the image will occupy, so as to centre it within the display area. */ xleft = 0.5f * ( x1 + x2 - nx * scale ); xright = 0.5f * ( x1 + x2 + nx * scale ); ybottom = 0.5f * ( y1 + y2 - ny * scale ); ytop = 0.5f * ( y1 + y2 + ny * scale ); /* Set up a PGPLOT coordinate transformation matrix and display the image data as a grey scale map (these details are specific to PGPLOT). */ { float tr[] = { xleft - 0.5f * scale, scale, 0.0f, ybottom - 0.5f * scale, 0.0f, scale }; cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr ); } /* BEGINNING OF AST BIT */ /* ==================== */ /* Store the locations of the bottom left and top right corners of the region used to display the image, in graphics coordinates. */ { float gbox[] = { xleft, ybottom, xright, ytop }; /* Similarly, store the locations of the image's bottom left and top right corners, in pixel coordinates -- with the first pixel centred at (1,1). */ double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 }; /* Create a Plot, based on the FrameSet associated with the image. This attaches the Plot to the graphics surface so that it matches the displayed image. Specify that a complete set of grid lines should be drawn (rather than just coordinate axes). */ plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" ); } /* Optionally, we can now set other Plot attributes to control the appearance of the grid. The values assigned here use the colour/font indices defined by the underlying graphics system. */ astSet( plot, "Colour(grid)=2, Font(textlab)=3" ); /* Use the Plot to draw the coordinate grid. */ astGrid( plot ); /* Annul the Plot when finished (or use the astBegin/astEnd technique shown earlier). */ plot = astAnnul( plot ); /* END OF AST BIT */ /* ============== */ /* Close down the graphics system. */ cpgend(); } \end{terminalv} \normalsize Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a displayed image, you may also use it to generate further graphical output of your own, specified in the image's world coordinate system (such as markers to represent astronomical objects, annotation, \emph{etc.}). There is also a range of Plot attributes which gives control over most aspects of the output's appearance. For details of the facilities available, see \secref{ss:plots} and the description of the Plot class in \appref{ss:classdescriptions}. For details of how to build a graphics program which uses PGPLOT, see \secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in \appref{ss:commanddescriptions}. \subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid} Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid (\secref{ss:howtoplotgrid}), it is a simple matter to change things so that the grid represents a different celestial coordinate system. For example, after creating the Plot with \htmlref{astPlot}{astPlot}, you could use: \small \begin{terminalv} astSet( plot, "System=Galactic" ); \end{terminalv} \normalsize or: \small \begin{terminalv} astSet( plot, "System=FK5, Equinox=J2010" ); \end{terminalv} \normalsize and any axes and/or grid drawn subsequently would represent the new celestial coordinate system you specified. Note, however, that this will only work if the original grid represented celestial coordinates of some kind (see \secref{ss:howtotestforcelestial} for how to determine if this is the case\footnote{Note that the methods applied to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not, you will get an error message. For more information about the celestial coordinate systems available, see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in \appref{ss:attributedescriptions}. \subsection{\ldots Give a User Control Over the Appearance of a Plot} The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the graphical output it produces (\secref{ss:howtoplotgrid} and \secref{ss:howtoswitchgrid}) can easily be extended to allow the user of a program complete control over such matters. For instance, if the file ``plot.config'' contains a series of plotting options in the form of Plot attribute assignments (see below for an example), then we could create a Plot and implement these assignments before producing the graphical output as follows: \small \begin{terminalv} #include #define MAXCHARS 120 FILE *stream; char line[ MAXCHARS + 2 ]; int base; ... /* Create a Plot and define the default appearance of the graphical output it will produce. */ plot = astPlot( wcsinfo, gbox, pbox, "Grid=1, Colour(grid)=2, Font(textlab)=3" ); /* Obtain the value of any Plot attributes we want to preserve. */ base = astGetI( plot, "Base" ); /* Open the plot configuration file, if it exists. Read each line of text and use it to set new Plot attribute values. Close the file when done. */ if ( stream = fopen( "plot.config", "r" ) ) { while ( fgets( line, MAXCHARS + 2, stream ) ) astSet( plot, "%s", line ); close( stream ); } /* Restore any attribute values we are preserving. */ astSetI( plot, "Base", base ); /* Produce the graphical output (e.g.). */ astGrid( plot ); \end{terminalv} \normalsize Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved so that the user cannot change it. This is because graphical output will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe the plotting surface to which we attached the Plot when we created it. The arrangement shown above allows the contents of the ``plot.config'' file to control most aspects of the graphical output produced (including the coordinate system used; the colour, line style, thickness and font used for each component; the positioning of axes and tick marks; the precision, format and positioning of labels; \emph{etc.}) \emph{via} assignments of the form: \small \begin{terminalv} System=Galactic, Equinox = 2001 Border = 1, Colour( border ) = 1 Colour( grid ) = 2 DrawAxes = 1 Colour( axes ) = 3 Digits = 8 Labelling = Interior \end{terminalv} \normalsize For a more sophisticated interface, you could obviously perform pre-processing on this input---for example, to translate words like ``red'', ``green'' and ``blue'' into colour indices, to permit comments and blank lines, \emph{etc.} For a full list of the attributes that may be used to control the appearance of graphical output, see the description of the Plot class in \appref{ss:classdescriptions}. For a complete description of each individual attribute (\emph{e.g.}\ those above), see the attribute's entry in \appref{ss:attributedescriptions}. \cleardoublepage \section{\label{ss:primer}An AST Object Primer} The AST library deals throughout with entities called Objects and a basic understanding of how to handle these is needed before you can use the library effectively. If you are already familiar with an object-oriented language, such as C$++$, few of the concepts should seem new to you. Be aware, however, that AST is designed to be used \emph{via} fairly conventional C and Fortran interfaces, so some things have to be done a little differently. If you are not already familiar with object-oriented programming, then don't worry---we will not emphasise this aspect more than is necessary and will not assume any background knowledge. Instead, this section concentrates on presenting all the fundamental information you will need, explaining how AST Objects behave and how to manipulate them from conventional C programs. If you like to read documents from cover to cover, then you can consider this section as an introduction to the programming techniques used in the rest of the document. Otherwise, you may prefer to skim through it on a first reading and return to it later as reference material. \subsection{AST Objects} An AST \htmlref{Object}{Object} is an entity which is used to store information and Objects come in various kinds, called \emph{classes}, according to the sort of information they hold. Throughout this section, we will make use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to illustrate many of the basic concepts. A ZoomMap is an Object that contains a recipe for converting coordinates between two hypothetical coordinate systems. It does this by multiplying all the coordinate values by a constant called the \emph{\htmlref{Zoom}{Zoom} factor}. A ZoomMap is a very simple Object which exists mainly for use in examples. It allows us to illustrate the ways in which Objects are manipulated and to introduce the concept of a \htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental to the way the AST library works. \subsection{\label{ss:objectcreation}Object Creation and Pointers} Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very simply as follows: \small \begin{terminalv} #include "ast.h" AstZoomMap *zoommap; ... zoommap = astZoomMap( 2, 5.0, "" ) \end{terminalv} \normalsize The first step is to include the header file ``ast.h'' which declares the interface to the AST library. We then declare a pointer of type AstZoomMap$*$ to receive the result and invoke the function \htmlref{astZoomMap}{astZoomMap} to create the ZoomMap. The pattern is the same for all other classes of AST \htmlref{Object}{Object}---you simply prefix ``ast'' to the class name to obtain the function that creates the Object and prefix ``Ast'' to obtain the type of the returned pointer. These functions are called \emph{constructor functions}, or simply \emph{constructors} (you can find an individual description of all AST functions in \appref{ss:functiondescriptions}) and the arguments passed to the constructor are used to initialise the new Object. In this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we are going to work in a 2-dimensional space) and 5.0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a C double value. We will return to the final argument, an empty string, shortly (\secref{ss:attributeinitialisation}). The value returned by the constructor is termed an \emph{Object pointer} or, in this case, a \emph{ZoomMap pointer} and is used to refer to the Object. You perform all subsequent operations on the Object by passing this pointer to other AST functions. \subsection{\label{ss:objecthierarchy}The Object Hierarchy} Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it relates to other kinds of \htmlref{Object}{Object} before investigating what we can do with it. We have so far indicated that a ZoomMap is a kind of Object and have also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements can be represented very simply using the following hierarchy: \small \begin{terminalv} Object Mapping ZoomMap \end{terminalv} \normalsize which is a way of stating that a ZoomMap is a special class of Mapping, while a Mapping, in turn, is a special class of Object. This is exactly like saying that an Oak is a special form of Tree, while a Tree, in turn, is a special form of Plant. This may seem almost trivial, but before you turn to read something less dull, be assured that it is a very important idea to keep in mind in what follows. If we look at some of the other Objects used by the AST library, we can see how these are all related in a similar way (don't worry about what they do at this stage): \label{ss:mappinghierarchy} \small \begin{terminalv} Object Mapping Frame FrameSet Plot UnitMap ZoomMap Channel FitsChan XmlChan \end{terminalv} \normalsize Notice that there are several different types of Mapping available (\emph{i.e.}\ there are classes of Object indented beneath the ``Mapping'' heading) and, in addition, other types of Object which are not Mappings---Channels for instance (which are at the same hierarchical level as Mappings). The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we will not discuss in detail until \secref{ss:plots}). As you can see, a Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and, like everything else, ultimately an Object. What this means is that you can use a Plot not only for its own specialised behaviour, but also whenever any of these other less-specialised classes of Object is called for. The general rule is that an Object of a particular class may substitute for any of the classes appearing above it in this hierarchy. The Object is then said to \emph{inherit} the behaviour of these higher classes. We can therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object is called for. Sometimes, this can lead to some spectacular short-cuts by avoiding the need to break large Objects down in order to access their components. With some practice and a little lateral thinking you should soon be able to spot opportunities for this. You can find the full \emph{class hierarchy}, as this is called, for the AST library in \appref{ss:classhierarchy} and you may need to refer to it occasionally until you are familiar with the classes you need to use. \subsection{\label{ss:displayingobjects}Displaying Objects} Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier (\secref{ss:objectcreation}) and examine what it's made of. There is a function for doing this, called \htmlref{astShow}{astShow}, which is provided mainly for looking at Objects while you are debugging programs. If you consult the description of astShow in \appref{ss:functiondescriptions}, you will find that it takes a pointer to an \htmlref{Object}{Object} (of type AstObject$*$) as its argument. Although we have only a ZoomMap pointer available, this is not a problem. If you refer to the brief class hierarchy described above (\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an Object, albeit a specialised one, so it inherits the properties of all Objects and can be substituted wherever an Object is required. We can therefore pass our ZoomMap pointer directly to astShow, as follows: \small \begin{terminalv} astShow( zoommap ); \end{terminalv} \normalsize The output from this will appear on the standard output stream and should look like the following: \small \begin{terminalv} Begin ZoomMap Nin = 2 IsA Mapping Zoom = 5 End ZoomMap \end{terminalv} \normalsize Here, the ``Begin'' and ``End'' lines mark the beginning and end of the ZoomMap, while the values 2 and 5 are simply the values we supplied to initialise it (\secref{ss:objectcreation}). These have been given simple names to make them easy to refer to. The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a property shared by all Mappings, so the ZoomMap has inherited this from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however, is specific to a ZoomMap and isn't shared by other kinds of Mappings. \subsection{\label{ss:gettingattributes}Getting Attribute Values} We saw above (\secref{ss:displayingobjects}) how to display the internal values of an \htmlref{Object}{Object}, but what about accessing these values from a program? Not all internal Object values are accessible in this way, but many are. Those that are, are called \emph{attributes}. A description of all the attributes used by the AST library can be found in \appref{ss:attributedescriptions}. Attributes come in several data types (character string, integer, boolean and floating point) and there is a standard way of obtaining their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin} attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as follows: \small \begin{terminalv} int nin; ... nin = astGetI( zoommap, "Nin" ); \end{terminalv} \normalsize Here, the function astGetI is used to extract the attribute value by giving it the ZoomMap pointer and the attribute name (attribute names are not case sensitive, but we have used consistent capitalisation in this document in order to identify them). Remember to use the ``ast.h'' header file to include the function prototype. If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably have used astGetD instead, this being a double version of the same function, for example: \small \begin{terminalv} double zoom; ... zoom = astGetD( zoommap, "Zoom" ); \end{terminalv} \normalsize However, we could equally well have read the Nin value as double, or the Zoom value as an integer, or whatever we wanted. The data type you want returned is specified simply by replacing the final character of the astGetX function name with C~(character string), D~(double), F~(float), I~(int) or L~(long). If possible, the value is converted to the type you want. If not, an error message will result. Note that all floating point values are stored internally as double, and all integer values as int. Boolean values are also stored as integers, but only take the values 1 and 0 (for true/false). \subsection{\label{ss:settingattributes}Setting Attribute Values} Some attribute values are read-only and cannot be altered after an \htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing the number of coordinates) is like this. It is defined when the ZoomMap is created, but cannot then be altered. Other attributes, however, can be modified whenever you want. A ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this could be done simply as follows: \small \begin{terminalv} astSetD( zoommap, "Zoom", 99.6 ); \end{terminalv} \normalsize which sets the value to 99.6. As when getting an attribute value (\secref{ss:gettingattributes}), you have a choice of which data type you will use to supply the new value. For instance, you could use an integer value, as in: \small \begin{terminalv} astSetI( zoommap, "Zoom", 99 ); \end{terminalv} \normalsize and the necessary data conversion would occur. You specify the data type you want to supply simply by replacing the final character of the astSetX function name with C~(character string), D~(double), F~(float), I~(int) or L~(long). Setting a boolean attribute to any non-zero integer causes it to take the value 1. An alternative way of setting attribute values for Objects is to use the \htmlref{astSet}{astSet} function (\emph{i.e.}\ with no final character specifying a data type). In this case, you supply the attribute values in a character string. The big advantage of this method is that you can assign values to several attributes at once, separating them with commas. This also reads more naturally in programs. For example: \small \begin{terminalv} astSet( zoommap, "Zoom=99.6, Report=1" ); \end{terminalv} \normalsize would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute (about which more shortly---\secref{ss:transforming}). You don't really have to worry about data types with this method, as any character representation will do. Note, when using astSet, a literal comma may be included in an attribute value by enclosed the value in quotation marks: \small \begin{terminalv} astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' ); \end{terminalv} \normalsize Another attractive feature of astSet is that you can build the character string which contains the attribute settings in the same way as when using the C run time library ``printf'' function. This is most useful when the values you want to set are held in other variables. For example: \small \begin{terminalv} double zoom = 99.6; int report = 1; ... astSet( zoommap, "Zoom=%g, Report=%d", zoom, report ); \end{terminalv} \normalsize would replace the ``\%'' conversion specifications by the values supplied as additional arguments. Any number of additional arguments may be supplied and the formatting rules are exactly the same as for the C ``printf'' family of functions. This is a very flexible technique, but does contain one pitfall: \begin{quote} \textbf{Pitfall.} The default precision used by ``printf'' (and astSet) for floating point values is only 6 decimal digits, corresponding approximately to float on most machines, whereas the AST library stores such values internally as doubles. You should be careful to specify a larger precision (such as DBL\_DIG, as defined in $<$float.h$>$) when necessary. For example: \small \begin{terminalv} #include ... astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value ); \end{terminalv} \normalsize \end{quote} Substituted strings may contain commas and this is a useful way of assigning such strings as attribute values without the comma being interpreted as an assignment separator, for example: \small \begin{terminalv} astSet( object, "Attribute=%s", "A string, containing a comma" ); \end{terminalv} \normalsize This is equivalent to using astSetC and one of these two methods should always be used when assigning string attribute values which might potentially contain a comma (\emph{e.g.}\ strings obtained from an external source). However, you should not attempt to use astSet to substitute strings that contain newline characters, since these are used internally as separators between adjacent attribute assignments. \label{ss:attributeinitialisation} Finally, a very convenient way of setting attribute values is to do so at the same time as you create an Object. Every Object constructor function has a final character string argument which allows you to do this. Although you can simply supply an empty string, it is an ideal opportunity to initialise the Object to have just the attributes you want. For example, we might have created our original ZoomMap with: \small \begin{terminalv} zoommap = astZoomMap( 2, 5.0, "Report=1" ); \end{terminalv} \normalsize and it would then start life with its Report attribute set to 1. The ``printf''-style substitution described above may also be used here. \subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes} You can use the astGetX family of functions (\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute at any time, regardless of whether a value has previously been set for it. If no value has been set, the AST library will generate a suitable default value. Often, the default value of an attribute will not simply be trivial (zero or blank) but may involve considerable processing to calculate. Wherever possible, defaults are designed to be real-life, sensible values that convey information about the state of the Object. In particular, they may often be based on the values of other attributes, so their values may change in response to changes in these other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a little too simple to show this behaviour, but we will meet it later on. An attribute that returns a default value in this way is said to be \emph{un-set}. Conversely, once an explicit value has been assigned to an attribute, it becomes \emph{set} and will always return precisely that value, never a default. The distinction between set and un-set attributes is important and affects the behaviour of several key routines in the AST library. You can test if an attribute is set using the function \htmlref{astTest}{astTest}, which returns a boolean (integer) result, as in: \small \begin{terminalv} if ( astTest( zoommap, "Report" ) ) { } \end{terminalv} \normalsize Once an attribute is set, you can return it to its un-set state using \htmlref{astClear}{astClear}. The effect is as if it had never been set in the first place. For example: \small \begin{terminalv} astClear( zoommap, "Report" ); \end{terminalv} \normalsize would ensure that the default value of the \htmlref{Report}{Report} attribute is used subsequently. %\subsection{TBW--Handling Character Attributes} \subsection{\label{ss:transforming}Transforming Coordinates} We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show what it is really for. Here, we will also encounter a routine that is a little more fussy about the type of pointer it will accept. The purpose of a ZoomMap is to multiply coordinates by a constant zoom factor. To witness this in action, we will first set the \htmlref{Report}{Report} attribute for our ZoomMap to a non-zero value: \small \begin{terminalv} astSet( zoommap, "Report=1" ); \end{terminalv} \normalsize This boolean (integer) attribute, which is present in all Mappings (and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all coordinate values that the Mapping converts. It is not a good idea to leave this feature turned on in a finished program, but it can save a lot of work during debugging. Our next step is to set up some coordinates for the ZoomMap to work on, using two arrays ``xin'' and ``yin'', and two arrays to receive the transformed coordinates, ``xout'' and ``yout''. Note that these are arrays of double, as are all coordinate data processed by the AST library: \small \begin{terminalv} double xin[ 10 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 }; double yin[ 10 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0 }; double xout[ 10 ]; double yout[ 10 ]; \end{terminalv} \normalsize We will now use the function \htmlref{astTran2}{astTran2} to transform the input coordinates. This is the most commonly-used (2-dimensional) coordinate transformation function. If you look at its description in \appref{ss:functiondescriptions}, you will see that it requires a pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer, as we could with the functions discussed previously. If we passed it a pointer to an inappropriate Object, an error message would result. Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we can use it with astTran2 to transform our coordinates, as follows: \small \begin{terminalv} astTran2( zoommap, 10, xin, yin, 1, xout, yout ); \end{terminalv} \normalsize Here, 10 is the number of points we want to transform and the fifth argument value of 1 indicates that we want to transform in the \emph{forward} direction (from input to output). Because our ZoomMap's Report attribute is set to 1, this will cause the effects of the ZoomMap on the coordinates to be displayed on the standard output stream: \small \begin{terminalv} (0, 0) --> (0, 0) (1, 2) --> (5, 10) (2, 4) --> (10, 20) (3, 6) --> (15, 30) (4, 8) --> (20, 40) (5, 10) --> (25, 50) (6, 12) --> (30, 60) (7, 14) --> (35, 70) (8, 16) --> (40, 80) (9, 18) --> (45, 90) \end{terminalv} \normalsize This shows the coordinate values of each point both before and after the ZoomMap is applied. You can see that each coordinate value has been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute value. The transformed coordinates are now stored in the ``xout'' and ``yout'' arrays. If we wanted to transform in the opposite direction, we need simply change the fifth argument of astTran2 from 1 to 0. We can also feed the output coordinates from the above back into the function: \small \begin{terminalv} astTran2( zoommap, 10, xout, yout, 0, xin, yin ); \end{terminalv} \normalsize The output would then look like: \small \begin{terminalv} (0, 0) --> (0, 0) (5, 10) --> (1, 2) (10, 20) --> (2, 4) (15, 30) --> (3, 6) (20, 40) --> (4, 8) (25, 50) --> (5, 10) (30, 60) --> (6, 12) (35, 70) --> (7, 14) (40, 80) --> (8, 16) (45, 90) --> (9, 18) \end{terminalv} \normalsize This is termed the \emph{inverse} transformation (we have converted from output to input) and you can see that the original coordinates have been recovered by dividing by the Zoom factor. \subsection{\label{ss:annullingpointers}Managing Object Pointers} So far, we have looked at creating Objects and using them in various simple ways but have not yet considered how to get rid of them again. Every \htmlref{Object}{Object} consumes various computer resources (principally memory) and should be disposed of when it is no longer required, so as to free up these resources. One way of doing this (not necessarily the best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once you have finished with it, using \htmlref{astAnnul}{astAnnul}. For example: \small \begin{terminalv} zoommap = astAnnul( zoommap ); \end{terminalv} \normalsize This indicates that you have finished with the pointer. Since astAnnul always returns the null value AST\_\_NULL (as defined in ``ast.h''), the recommended way of using it, as here, is to assign the returned value to the pointer being annulled. This ensures that any attempt to use the pointer again will generate an error message. In general, this process may not delete the Object, because there may still be other pointers associated with it. However, each Object maintains a count of the number of pointers associated with it and will be deleted if you annul the final pointer. Using astAnnul consistently will therefore ensure that all Objects are disposed of at the correct time. You can determine how many pointers are associated with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute. \subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End} The use of \htmlref{astAnnul}{astAnnul} (\secref{ss:annullingpointers}) is not completely foolproof, however. Consider the following: \small \begin{terminalv} astShow( astZoomMap( 2, 5.0, "" ) ); \end{terminalv} \normalsize This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output (\secref{ss:displayingobjects}). Using function invocations as arguments to other functions in this way is very convenient because it avoids the need for intermediate pointer variables. However, the pointer generated by \htmlref{astZoomMap}{astZoomMap} is still active, and since we have not stored its value, we cannot use astAnnul to annul it. The ZoomMap will therefore stay around until the end of the program. A simple way to avoid this problem is to enclose all use of AST functions between invocations of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}, for example: \small \begin{terminalv} astBegin; astShow( astZoomMap( 2, 5.0, "" ) ); astEnd; \end{terminalv} \normalsize When the expansion of astEnd (which is a macro) executes, every \htmlref{Object}{Object} pointer created since the previous use of astBegin (also a macro) is automatically annulled and any Objects left without pointers are deleted. This provides a simple solution to managing Objects and their pointers, and allows you to create Objects very freely without needing to keep detailed track of each one. Because this is so convenient, we implicitly assume that astBegin and astEnd are used in most of the examples given in this document. Pointer management is not generally shown explicitly unless it is particularly relevant to the point being illustrated. If necessary, astBegin and astEnd may be nested, like blocks delimited by ``\{\ldots\}'' in C, to define a series of AST pointer contexts. Each use of astEnd will then annul only those Object pointers created since the matching use of astBegin. \subsection{Exporting, Importing and Exempting AST Pointers} The \htmlref{astExport}{astExport} function allows you to export particular pointers from one AST context (\secref{ss:contexts}) to the next outer one, as follows: \small \begin{terminalv} astExport( zoommap ); \end{terminalv} \normalsize This would identify the pointer stored in ``zoommap'' as being required after the end of the current AST context. It causes any pointers nominated in this way to survive the next use of \htmlref{astEnd}{astEnd} (but only one such use) unscathed, so that they are available to the next outer context. This facility is not needed often, but is invaluable when the purpose of your \htmlref{astBegin}{astBegin}\ldots astEnd block is basically to generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting that pointer out. The \htmlref{astImport}{astImport} routine can be used in a similar manner to import a pointer into the current context, so that it is deleted when the current context is closed using astEnd. Sometimes, you may also want to exempt a pointer from all the effects of AST contexts. You should not need to do this often, but it will prove essential if you ever need to write a library of functions that stores AST pointers as part of its own internal data. Without some form of exemption, the caller of your routines could cause the pointers you have stored to be annulled---thus corrupting your internal data---simply by using astEnd. To avoid this, you should use \htmlref{astExempt}{astExempt} on each pointer that you store, for example: \small \begin{terminalv} astExempt( zoommap ); \end{terminalv} \normalsize This will prevent the pointer being affected by any subsequent use of astEnd. Of course, it then becomes your responsibility to annul this pointer (using \htmlref{astAnnul}{astAnnul}) when it is no longer required. \subsection{AST Objects within Multi-threaded Applications} When the AST library is built from source, the build process checks to see if the POSIX threads library (``\texttt{pthreads}'') is available. If so, appropriate \texttt{pthreads} calls are inserted into the AST source code to ensure that AST is thread-safe, and the AST\_\_THREADSAFE macro (defined in the ``ast.h'' header file) is set to ``\texttt{1}''. If the \texttt{pthreads} library cannot be found when AST is built, a working version of the AST library will still be created, but it will not be thread-safe. In this case the AST\_\_THREADSAFE macro will be set to ``\texttt{0}'' in ast.h. The rest of this section assumes that the thread-safe version of AST is being used. Note, some AST functions call externally specified functions (\emph{e.g.} the source and sink functions used by the \htmlref{Channel}{Channel} class or the graphics primitives functions used by the \htmlref{Plot}{Plot} class). AST does not know whether such functions are thread-safe or not. For this reason, invocations of these functions within a multi-threaded environment are serialised using a mutex in order to avoid two or more threads executing an external function simultaneously. If an application uses more than one thread, the possibility arises that an \htmlref{Object}{Object} created by one thread may be accessed by another thread, potentially simultaneously. If any of the threads modifies any aspect of the Object, this could lead to serious problems within the other threads. For this reason, some restrictions are placed on how Objects can be used in a multi-threaded application. \subsubsection{Locking AST Objects for Exclusive Use} The basic restriction is that a thread can only access Objects that it has previously locked for its own exclusive use. If a thread attempts to access any \htmlref{Object}{Object} that it has not locked, an error is reported. The \htmlref{astAnnul}{astAnnul} function is the one exception to this restriction. Pointers for Objects not currently locked by the calling thread can be annulled succesfully using astAnnul. This means that a thread that has finished with an Object pointer can unlock the Object by passing the pointer to \htmlref{astUnlock}{astUnlock} (so that other threads can use the Object via their own cloned pointers), and can then annul the pointer using astAnnul. Note, however, that an error will be reported by astAnnul if the supplied pointer has been locked by another thread using \htmlref{astLock}{astLock}. When an Object is created, it is initially locked by the calling thread. Therefore a thread does not need to lock an Object explicitly if it was created in the same thread. If the Object pointer is then passed to another thread, the first thread must unlock the Object using astUnlock and the second thread must then lock it using astLock. If a thread attempts to lock an Object that is already locked by another thread, it can choose to report an error immediately or to wait until the Object is available. The \htmlref{astThread}{astThread} function can be used to determine whether an Object is locked by the running thread, locked by another thread, or unlocked. If two or more threads need simultaneous access to an Object, a deep copy of the Object should be taken for each thread, using \htmlref{astCopy}{astCopy}, and then the copies should be unlocked and passed to the othe threads, which should then lock them. Note, if a thread modifies the Object, the modification will have no effect on the other threads, because the Object copies are independent of each other. \subsubsection{AST Pointer Contexts} Each thread maintains its own set of nested AST contexts, so when \htmlref{astEnd}{astEnd} is called, only Objects that are locked by the current thread will be annulled. If an \htmlref{Object}{Object} is unlocked by a thread using \htmlref{astUnlock}{astUnlock}, it is exempted from context handling so that subsequent invocations of astEnd will not cause it to be annulled (this is similar to using \htmlref{astExempt}{astExempt} on the Object). When the Object is subsequently locked by another thread using \htmlref{astLock}{astLock}, it will be imported into the context that was active when astLock was called. \subsection{\label{ss:copyingobjects}Copying Objects} The AST library makes extensive use of pointers, not only for accessing Objects directly, but also as a means of storing Objects inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to hold collections of other Objects). Rather than copy an Object in its entirety, a pointer to the interior Object is simply stored in the enclosing Object. This means that Objects may frequently not be completely independent of each other because, for instance, they both contain pointers to the same sub-Object. In this situation, changing one Object (say assigning an attribute value) may affect the other one \emph{via} the common Object. It is difficult to describe all cases where this may happen, so you should always be alert to the possibility. Fortunately, there is a simple solution. If you require two Objects to be independent, then simply use \htmlref{astCopy}{astCopy} to make a copy of one, \emph{e.g.}: \small \begin{terminalv} AstZoomMap *zoommap1, *zoommap2; ... zoommap2 = astCopy( zoommap1 ); \end{terminalv} \normalsize This process will create a true copy of any Object and return a pointer to the copy. This copy will not contain any pointers to any component of the original Object (everything is duplicated), so you can then modify it safely, without fear of affecting either the original or any other Object. %\subsection{TBW - Inheritance} \subsection{C Pointer Types} At this point it is necessary to confess to a small amount of deception. So far, we have been passing \htmlref{Object}{Object} pointers to AST functions in order to perform operations on those Objects. In fact, however, what we were using were not true C functions at all, but merely macros which invoke a related set of hidden functions with essentially the same arguments. In practical terms, this makes very little difference to how you use the functions, as we will continue to call them.\footnote{About the only difference is that you cannot store a pointer to an AST ``function'' in a variable and use the variable's value to invoke that function again later.} The reason for this deception has to do with the rules for data typing in C. Recall that most AST functions can be used to process Objects from a range of different classes (\secref{ss:objecthierarchy}). In C, this means passing different pointer types to the same function and most C compilers will not permit this (at least, not without grumbling) because it usually indicates a programming error. In AST, however, it is perfectly safe if done properly. Some way is therefore needed of circumventing the normal compiler checking. The normal way of doing this in C is with a cast. This approach quickly becomes cumbersome, however, so we have adopted the strategy of wrapping each function in a macro which applies the appropriate cast for you. This means that you can pass pointers of any type to any AST function. For example, in passing a \htmlref{ZoomMap}{ZoomMap} pointer to \htmlref{astShow}{astShow}: \small \begin{terminalv} AstZoomMap *zoommap; ... zoommap = astZoomMap( 2, 5.0, "" ); astShow( zoommap ); \end{terminalv} \normalsize we are exploiting this mechanism to avoid a compiler warning, because the notional type of astShow's parameter is AstObject$*$ (not AstZoomMap$*$). We must still guard against programming errors, however, so every pointer's type is checked by the enclosing macro immediately before any AST function executes. This allows pointer mis-matches (in the more liberal AST sense---\emph{i.e.}\ taking account of the class hierarchy, rather than the stricter C sense) to be detected at run-time and a suitable error message will be reported. This message should also identify the line where the error occurs. A similar strategy is used when pointers are returned by AST functions (\emph{i.e.}\ as the function result). In this case the pointer is cast to void$*$, although we retain the notional pointer type in the function's documentation (\emph{e.g.}\ \appref{ss:functiondescriptions}). This allows you to assign function results to pointer variables without using an explicit cast. For example, the \htmlref{astRead}{astRead} function returns an Object pointer, but might be used to read (say) a ZoomMap as follows: \small \begin{terminalv} AstChannel *channel; AstZoomMap *zoommap; ... zoommap = astRead( channel ); \end{terminalv} \normalsize Strictly, there is a C pointer mis-match here, but it is ignored because the operation makes perfect sense to AST. \textbf{There is an important exception to this, however, in that constructor functions always return strongly-typed pointers.} What we mean by this is that the returned pointer is never implicitly cast to void$*$. You must therefore match pointer types when you initially create an Object using its constructor, such as in the following: \small \begin{terminalv} AstZoomMap *zoommap; ... zoommap = astZoomMap( 2, 5.0, "" ); \end{terminalv} \normalsize If the variable receiving the pointer is of a different type, an appropriate cast should be used, as in: \small \begin{terminalv} AstMapping *mapping; ... mapping = (AstMapping *) astZoomMap( 2, 5.0, "" ); \end{terminalv} \normalsize This is an encouragement for you to declare your pointer types consistently, since this is of great benefit to anyone trying to understand your software. Finally, we should also make one more small confession---AST pointers are not really pointers at all. Although they behave like pointers, the actual ``values'' stored are not the addresses of C data structures. This means that you cannot de-reference an AST pointer to examine the data within (although you can use astShow instead---\secref{ss:displayingobjects}). This is necessary so that AST pointers can be made unique even although several of them might reference the same Object. \subsection{\label{ss:errordetection}Error Detection} If an error occurs in an AST function (for example, if you supply an invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an error message will be written to the standard error stream and the function will immediately return. To indicate than an error has occurred, an AST \emph{error status} value is used. This integer value is stored internally by AST and is initially clear (\emph{i.e.}\ set to zero\footnote{We will assume throughout that the ``OK'' value is zero, as it currently is. However, a different value could, in principle, be used if the environment in which AST is running requires it. This is why a simple interface is provided to isolate you from the actual value of the error status.} to indicate no error). If an error occurs, it becomes set to a different \emph{error value}, which allows you to detect the error, as follows: \small \begin{terminalv} zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" ); if ( !astOK ) { } \end{terminalv} \normalsize The macro \htmlref{astOK}{astOK} is used to test whether the AST error status is still OK. In this example it would not be, because we have attempted to set a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not have such an attribute. The actual value of the AST error status can be obtained using the \htmlref{astStatus}{astStatus} macro, as follows: \small \begin{terminalv} int status; ... status = astStatus; \end{terminalv} \normalsize A consequence of the AST error status being set is that almost all AST functions will subsequently cease to function and will instead simply return without action. This means that you do not need to use astOK to check for errors very frequently. Instead, you can usually simply invoke a succession of AST functions. If an error occurs in any of them, the following ones will do nothing and you can check for the error at the end, for example: \small \begin{terminalv} astFunctionA( ... ); astFunctionB( ... ); astFunctionC( ... ); if ( !astOK ) { } \end{terminalv} \normalsize There are, however, a few functions which do not adhere to this general rule and which will attempt to execute if the AST error status is set. These functions, such as \htmlref{astAnnul}{astAnnul}, are concerned with cleaning up and recovering resources. For example, in the following: \small \begin{terminalv} zoommap = astZoomMap( 2, 5.0, "" ); astFunctionX( ... ); astFunctionY( ... ); astFunctionZ( ... ); zoommap = astAnnul( zoommap ); if ( !astOK ) { } \end{terminalv} \normalsize astAnnul will execute normally in order to recover the resources associated with the ZoomMap that was created earlier, regardless of whether an error has occurred in any of the intermediate functions. Functions which behave in this way are noted in the relevant descriptions in \appref{ss:functiondescriptions}. If a serious error occurs, you will probably want to abort your program, but sometimes you may want to recover and carry on. Because very few AST functions will execute once the AST error status has been set, you must first clear this status by using the \htmlref{astClearStatus}{astClearStatus} macro, as follows: \small \begin{terminalv} astClearStatus; \end{terminalv} \normalsize This will restore the AST error status to its OK value, so that AST functions execute normally again. Occasionally, you may also need to set the AST error status to an explicit error value (see \secref{ss:channelsink} for an example). This is done using \htmlref{astSetStatus}{astSetStatus} and can be used to communicate to AST that an error has occurred in some other item of software, for example: \small \begin{terminalv} int new_status; ... astSetStatus( new_status ); \end{terminalv} \normalsize The effect is that most AST routines will subsequently return without action, just as if an error had occurred within the AST library itself. \subsection{Sharing the Error Status} In some software, it is usual to maintain a single integer error status variable which is accessed by each function as it executes. If an error occurs, this status variable is set and other functions can detect this and take appropriate action. If you use AST in such a situation, it can be awkward to have a separate internal error status used by AST functions alone. To remedy this, AST is capable of sharing the error status variable used by any other software, so long as they use the same conventions (\emph{i.e.}\ a C int with the same ``OK'' value). To enable this facility, you should pass the address of your status variable to \htmlref{astWatch}{astWatch}, as follows: \small \begin{terminalv} int my_status; int *old_address; ... old_address = astWatch( &my_status ); \end{terminalv} \normalsize Henceforth, instead of using its own internal error status variable, AST will use the one you supply, so that it can detect errors flagged by other parts of your software. The address of the original error status variable is returned by astWatch, so you can restore the original behaviour later if necessary. Note that this facility is not available \emph{via} the Fortran interface to the AST library. \cleardoublepage \section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)} In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a \htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its input to its output and back again (\secref{ss:transforming}). We also saw how its behaviour could be controlled by setting various attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made it display coordinate values as it transformed them. In this section, we will look at Mappings a bit more thoroughly and explore the behaviour which is common to all the Mappings provided by AST. This is good background for what follows, because many of the Objects we discuss later will also turn out to be Mappings in various disguises. \subsection{\label{ss:mappingclass}The Mapping Class} Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class as a whole and some of the sub-classes it contains: \begin{terminalv} Mapping CmpMap DssMap GrismMap IntraMap LutMap MathMap MatrixMap PermMap PolyMap SlaMap SpecMap TimeMap UnitMap WcsMap ZoomMap Frame \end{terminalv} The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered in detail in \secref{ss:frames}. We start by looking at the parent class, Mapping. AST does not provide a function to create a basic Mapping (\emph{i.e.}\ the astMapping constructor does not exist). This is because the Mapping class itself is ``virtual'' and basic Mappings are of no use in themselves. The Mapping class serves simply to contain the various specialised Mappings that exist. However, it provides more than just a convenient heading for them because it bestows all classes of Mapping with common properties (\emph{e.g.}\ attributes) and behaviour. By examining the Mapping class, we are therefore examining the things that all other Mappings have in common. \subsection{The Mapping Model} The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}. It is a black box which you can supply with a set of coordinate values in return for a set of transformed coordinates. The two sets are termed \emph{input} and \emph{output} coordinates. You can also go back the other way and transform output coordinates back into input coordinates, as we saw in \secref{ss:transforming}. \subsection{Changing Attributes of a Mapping} Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each coordinate is to be multiplied. These attribute values should be set when the Mapping is created and should not be changed afterwards. Indeed, the AST library will report an error if an attempt is made to change the value of a Mapping attribute. This is because, once created, Mappings are often later included within other objects such as FrameSets and CmpMaps. This means that in general there could be many active references to a single Mapping object within a program. Changing an attribute of the Mapping via one particular reference (i.e pointer) would cause all the other references to change too, with often undesirable or unpredictable consequences. To avoid this, Mappings are considered \emph{immutable} in most situations. The one exception is if the Mapping has not yet been cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference couint of one) - changing the attributes of such a Mapping is allowed, and will not generate an error. Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and can be changed at any time. \subsection{Input and Output Coordinate Numbers} In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to represent a single point need not be the same as the number that comes out. Often these numbers will be the same, and often they will both equal 2 (because 2-dimensional coordinate systems are common), but this needn't necessarily be the case. The number of coordinates required to specify an input point is represented by the integer attribute \htmlref{Nin}{Nin} and the number required to specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only attributes common to all Mappings. Generally, their values are fixed when a Mapping is created. In \secref{ss:objectcreation}, we saw how the Nin attribute for a \htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function \htmlref{astZoomMap}{astZoomMap} which created it. In this case, the Nout attribute was not needed and it implicitly took the same value as Nin, but we could have enquired about its value had we wanted, as follows: \small \begin{terminalv} #include "ast.h" AstZoomMap *zoommap; int nout; ... nout = astGetI( zoommap, "Nout" ); \end{terminalv} \normalsize \subsection{Forward and Inverse Transformations} We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates either from input to output, or \emph{vice versa}. These are termed its \emph{forward} and \emph{inverse} transformations. This statement was not quite accurate, however, because in general Mappings are only \textbf{potentially} capable of working in both directions. In practice, coordinate transformation may only be feasible in one direction or the other because some functions are not easily inverted (they may be multi-valued, for instance). Allowance must be made for this, so each Mapping has two read-only boolean (integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate whether each transformation is available. A transformation is available if the corresponding attribute is non-zero, otherwise it is not.\footnote{Most of the Mappings provided by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can behave otherwise.} If you enquire about the value of these attributes, a value of 0 or 1 is returned. Attempting to use a Mapping to apply a transformation which is not available will result in an error. \subsection{\label{ss:invertingmappings}Inverting Mappings} An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert} flag. This is a boolean (integer) attribute that can be assigned a new value at any time. If it is non-zero, it has the effect of interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the Mapping is then said to be \emph{inverted}. By default, the Invert attribute is zero. There is no magic in this. There is no fancy arithmetic involved in inverting mathematical functions, for instance. The Invert flag is simply a switch that interchanges a Mapping's input and output ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and when you ask for what was once the forward transformation you get the inverse transformation instead (and \emph{vice versa}). When you return the Invert attribute to zero, or clear it, the Mapping returns to its original behaviour. Often, the actual value of the Invert attribute is unimportant and you simply wish to invert its boolean sense, so that what was the Mapping's input becomes its output and \emph{vice versa}. This is most easily accomplished using \htmlref{astInvert}{astInvert}, as follows: \small \begin{terminalv} AstMapping *mapping; ... astInvert( mapping ); \end{terminalv} \normalsize If the Mapping you have happens to be the wrong way around, astInvert allows you to correct the problem. \subsection{Finding the Rate of Change of a Mapping Output} The \htmlref{astRate}{astRate} function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output with respect to any Mapping input, at a given input position. The method used produces good accuracy (typically a relative error of 10E-10 or less) but may require the Mapping to be evaluated 100 or more times. An estimate of the second derivative is also produced by this function. \subsection{Reporting Coordinate Transformations} We have already seen (\secref{ss:transforming}) how the boolean (integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the operation of transforming a set of coordinates will result in a report being written to standard output. This will display the coordinate values before and after transformation. It can save considerable time during program development by eliminating the need to add loops and output statements to your program. In a finished program, however, you should be careful that the Report attribute is not set to a non-zero value unless you want to see the output (there may often be rather a lot of this!). To help prevent unwanted output being produced by accident, the Report attribute is unusual in that its value is not preserved when a Mapping is copied using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). Instead, it reverts to its default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to zero when a Mapping is written out, \emph{e.g.}\ to a file using a \htmlref{Channel}{Channel} (\secref{ss:channels}). %\subsection{TBW---More on Transforming Coordinates} \subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values} Even when coordinates can, in principle, be transformed in either direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific coordinate values cannot be handled. For example, the Mapping may be mathematically intractable (\emph{e.g.}\ singular) in certain places, or it may map a subset of one space on to another, so that some points in one space are not represented in the other. Sky projections often show this behaviour, since it is quite common to project only half of the celestial sphere on to two dimensions, omitting points on the opposite side of the sky. There are many other examples. To indicate when coordinates cannot be transformed, for whatever reason, AST substitutes a special output coordinate value given by the macro AST\_\_BAD (as defined in the ``ast.h'' header file). Before making use of coordinates generated by any of the AST transformation functions, therefore, you may need to check for the presence of this value. Because coordinates with the value AST\_\_BAD can be generated in this way, all other AST functions are also capable of recognising this value and handling it appropriately. The coordinate transformation functions do this by propagating any missing input coordinate information through to their output. This means that if you supply coordinates with the value AST\_\_BAD, the returned coordinates are also likely to contain this value. Here, for example, is what happens if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of coordinates: \small \begin{terminalv} (0, 0) --> (0, 0) (, 2) --> (, 10) (2, 4) --> (10, 20) (3, 6) --> (15, 30) (4, ) --> (20, ) (5, 10) --> (25, 50) (, ) --> (, ) (7, 14) --> (35, 70) (8, 16) --> (40, 80) (9, 18) --> (45, 90) \end{terminalv} \normalsize The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This is a case of ``garbage in, garbage out'' but at least it's consistent garbage that you can recognise! Note how the presence of the AST\_\_BAD value in one input dimension does not necessarily result in the loss of information for all output dimensions. Sometimes, such loss will be unavoidable, but in general an attempt is made to preserve information as far as possible. The exact behaviour will depend on the Mapping involved. \subsection{\label{ss:unitmapexample}Example---the UnitMap} The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its purpose is simply to copy coordinate values, unaltered, from its input to its output and \emph{vice versa}. A UnitMap has no additional attributes beyond those of a basic Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are specified by the first argument supplied to its constructor. For example: \small \begin{terminalv} AstUnitMap *unitmap; ... unitmap = astUnitMap( 2, "" ); \end{terminalv} \normalsize will create a UnitMap that copies 2-dimensional coordinates. Inverting a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert} attribute. The main use of a UnitMap is to allow a Mapping to be supplied when one is required (as an argument to a function, for example) but you wish it to leave coordinate values unchanged. \subsection{\label{ss:permmapexample}Example---the PermMap} The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met previously. Its purpose is to change the order, or number, of coordinates. It is also able to substitute fixed values for coordinates. To illustrate its action, suppose our input coordinates are denoted by ($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore, should rotate the coordinate values by one position. To create such a PermMap, we first set up two integer arrays. One of these, ``outperm'', controls the selection of input coordinates for use in the output and the other, ``inperm'', controls selection of output coordinates for use in the input: \small \begin{terminalv} int outperm[ 4 ] = { 4, 1, 2, 3 }; int inperm[ 4 ] = { 2, 3, 4, 1 }; \end{terminalv} \normalsize Note that the numbers we store in these arrays are the indices of the coordinates that we want to select. We have chosen these so that the forward and inverse transformations will perform complementary permutations on the coordinates. The PermMap is then created by passing these arrays to its constructor, as follows: \small \begin{terminalv} AstPermMap *permmap; ... permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" ); \end{terminalv} \normalsize Note that we specify the number of input and output coordinates separately, but set both to 4 in this example. The resulting PermMap would have the following effect when used to transform coordinates: \begin{terminalv} Forward: (1, 2, 3, 4) --> (4, 1, 2, 3) (2, 4, 6, 8) --> (8, 2, 4, 6) (3, 6, 9, 12) --> (12, 3, 6, 9) (4, 8, 12, 16) --> (16, 4, 8, 12) (5, 10, 15, 20) --> (20, 5, 10, 15) Inverse: (4, 1, 2, 3) --> (1, 2, 3, 4) (8, 2, 4, 6) --> (2, 4, 6, 8) (12, 3, 6, 9) --> (3, 6, 9, 12) (16, 4, 8, 12) --> (4, 8, 12, 16) (20, 5, 10, 15) --> (5, 10, 15, 20) \end{terminalv} If the number of input and output coordinates are unequal so, also, will be the size of the ``outperm'' and ``inperm'' arrays. This means, however, that we cannot fill them with coordinate indices so that they perform complementary permutations, because one transformation will lose information (discard a coordinate) that the other cannot recover. To give an example, consider the following: \small \begin{terminalv} int outperm[ 3 ] = { 4, 3, 2 }; int inperm[ 4 ] = { -1, 3, 2, 1 }; double con[ 1 ] = { 99.004 }; \end{terminalv} \normalsize In this case, the forward transformation will change ($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The inverse transformation restores the original coordinate order, but has no value to assign to the first coordinate. In this case, the number entered in the ``inperm'' array is $-$1. This negative value indicates that the coordinate value should be obtained by addressing the first element of the ``con'' array (\emph{i.e.}\ element zero). This array, ignored in the previous example, may then be used to supply a value for the missing coordinate. The constructor function: \small \begin{terminalv} permmap = astPermMap( 4, inperm, 3, outperm, con, "" ); \end{terminalv} \normalsize will then create a PermMap with the following effect when used to transform coordinates: \begin{terminalv} Forward: (1, 2, 3, 4) --> (4, 3, 2) (2, 4, 6, 8) --> (8, 6, 4) (3, 6, 9, 12) --> (12, 9, 6) (4, 8, 12, 16) --> (16, 12, 8) (5, 10, 15, 20) --> (20, 15, 10) Inverse: (4, 3, 2) --> (99.004, 2, 3, 4) (8, 6, 4) --> (99.004, 4, 6, 8) (12, 9, 6) --> (99.004, 6, 9, 12) (16, 12, 8) --> (99.004, 8, 12, 16) (20, 15, 10) --> (99.004, 10, 15, 20) \end{terminalv} The ``con'' array may contain more than one value if necessary and may be addressed by both the ``inperm'' and ``outperm'' arrays using coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the first, second, third,~\emph{etc.}\ elements. If there is no suitable replacement value that can be supplied \emph{via} the ``con'' array, a value of zero may be entered into the ``outperm'' and/or ``inperm'' arrays. This causes the value AST\_\_BAD to be used for the affected coordinate (as defined in the ``ast.h'' header file), thus indicating a missing coordinate value (\secref{ss:badcoordinates}). The principle use for a PermMap lies in matching a coordinate system to a data array where there is a choice of storage order for the data. PermMaps are also useful for discarding unwanted coordinates so as to reduce the number of dimensions, such as when selecting a ``slice'' from a multi-dimensional array. \cleardoublepage \section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)} We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The Mappings we have considered so far have been atomic, in the sense that they perform pre-defined elementary transformations. A CmpMap, however, is a compound Mapping. In essence, it is a framework for containing other Mappings and its purpose is to allow those Mappings to work together in various combinations while appearing as a single \htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is determined by the other Mappings it contains. \subsection{\label{ss:seriescmpmap}Combining Mappings in Series} Consider a simple example based on two 2-dimensional coordinate systems. Suppose that to convert from one to the other we must swap the coordinate order and multiply both coordinates by 5, so that the coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done in two stages: \begin{enumerate} \item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the coordinate order. \item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both coordinate values by the constant 5. \end{enumerate} The PermMap and ZoomMap are then said to operate \emph{in series}, because they are applied sequentially (\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}). We can create a \htmlref{CmpMap}{CmpMap} that applies these Mappings in series as follows: \small \begin{terminalv} #include "ast.h" AstCmpMap *cmpmap; AstPermMap *permmap; AstZoomMap *zoommap; ... /* Create the individual Mappings. */ { int inperm[ 2 ] = { 2, 1 }; int outperm[ 2 ] = { 2, 1 }; permmap = astPermMap( 2, inperm, 2, outperm, NULL, "" ); } zoommap = astZoomMap( 2, 5.0, "" ) /* Combine them in series. */ cmpmap = astCmpMap( permmap, zoommap, 1, "" ); /* Annul the individual Mapping pointers. */ permmap = astAnnul( permmap ); zoommap = astAnnul( zoommap ); \end{terminalv} \normalsize Here, the third argument (1) of the constructor function \htmlref{astCmpMap}{astCmpMap} indicates ``in series''. When used to transform coordinates in the forward direction, the resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap) and then the second one (the ZoomMap). When transforming in the inverse direction, it will apply the second one (in the inverse direction) and then the first one (also in the inverse direction). In general, although not in this particular example, the order in which the two component Mappings are supplied is significant. Clearly, also, the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for the second one. \subsection{Combining Mappings in Parallel} Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the only way of combining them. The alternative, \emph{in parallel}, involves applying the two Mappings at once but on different subsets of the coordinate values. Consider, for example, a set of 3-dimensional coordinates and suppose we wish to transform them by swapping the first two coordinate values and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms into ($x_2,x_1,5x_3$). Again, we can perform each of these steps individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is 1-dimensional and the individual Mappings are applied in parallel (\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}). Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple: \small \begin{terminalv} cmpmap = astCmpMap( permmap, zoommap, 0, "" ); \end{terminalv} \normalsize The only difference is that the third argument of \htmlref{astCmpMap}{astCmpMap} is now zero, meaning ``in parallel''. As before, the order in which the two component Mappings are supplied is significant. The first one acts on the lower-numbered input coordinate values (however many it needs) and produces the lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on the higher-numbered input coordinates (however many remain) and generates the remaining higher-numbered output coordinates. When the CmpMap transforms coordinates in the inverse direction, both component Mappings are applied to the same coordinates, but in the inverse direction. Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings (\emph{i.e.}\ the numbers of input and output coordinates) will sum to give the Nin and Nout attributes of the overall CmpMap. \subsection{\label{ss:cmpmapcomponents}The Component Mappings} A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply holds pointers to them. In the example above (\secref{ss:seriescmpmap}), we were free to annul the individual \htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount} attribute) of each component Mapping by one. The individual components are therefore not deleted by \htmlref{astAnnul}{astAnnul}, but retained until the CmpMap itself is deleted and annuls the pointers it holds. Consistent use of astAnnul (\secref{ss:annullingpointers}) and/or pointer contexts (\secref{ss:contexts}) will therefore ensure that all Objects are deleted at the appropriate time. Note that access to a CmpMap's component Mappings is not generally available unless pointers to them are retained when the CmpMap is created. If such pointers are retained, then subsequent modifications to the individual components can be used to indirectly modify the behaviour of the overall CmpMap. There is an important exception to this, however, because a CmpMap retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its components and uses these in order to ignore any subsequent external changes. This means that you may invert either component Mapping before inserting it into a CmpMap and need not worry if you un-invert it again later. The CmpMap's behaviour will not be affected by the later action. \subsection{\label{ss:complexcmpmap}Creating More Complex Mappings} Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can substitute (\secref{ss:objecthierarchy}) as a component Mapping when constructing a new CmpMap using \htmlref{astCmpMap}{astCmpMap}. This has the effect of nesting one CmpMap inside another and opens up many new possibilities. For example, combining three Mappings in series can be accomplished as follows: \small \begin{terminalv} AstMapping *map1, *map2, *map3; ... cmpmap = astCmpMap( map1, astCmpMap( map2, map3, 1, "" ), 1, "" ); \end{terminalv} \normalsize The way in which the individual component Mappings are grouped within the nested CmpMaps is not usually important. A similar technique can be used to combine multiple Mappings in parallel and, of course, mixed series and parallel combinations are also possible (Figure~\ref{fig:complexcmpmap}). There is no built-in limit to how many CmpMaps may be nested in this way, so this mechanism provides an indefinitely extensible method of building complex Mappings out of the elemental building blocks provided by AST. In practice, you might not need to construct such complex CmpMaps yourself very frequently, but they will often be returned by AST routines. Nested CmpMaps underlie the library's entire ability to represent a wide range of different coordinate transformations. \subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images} Consider, as a practical example of CmpMaps, two images of the sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from pixel coordinates to a standard celestial coordinate system, say FK5~(J2000.0). If we wish to inter-compare these images, we can do so by using this celestial coordinate system to align them. That is, we first convert from pixel coordinates in the first image into FK5 coordinates and we then convert from FK5 coordinates into pixel coordinates in the second image. If ``mapa'' and ``mapb'' are pointers to our two original Mappings, we could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel coordinates of the first and second images by combining these Mappings, as follows: \small \begin{terminalv} AstCmpMap *alignmap; AstMapping *mapa, *mapb; ... astInvert( mapb ); alignmap = astCmpMap( mapa, mapb, 1, "" ); astInvert( mapb ); \end{terminalv} \normalsize Here, we have used \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}) to invert ``mapb'' before inserting it into the CmpMap because, as supplied, it converted in the wrong direction. Afterwards, we invert it again to return it to its original state. The CmpMap, however, will ignore this subsequent change (\secref{ss:cmpmapcomponents}). The forward transformation of the resulting CmpMap will now transform from pixel coordinates in the first image to pixel coordinates in the second image, while its inverse transformation will convert in the opposite direction. \subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings} While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it unfortunately also provides an opportunity for representing simple Mappings in complex ways. Sometimes, unnecessary complexity can be difficult to avoid but can obscure important simplifications. Consider the example above (\secref{ss:cmpmapexample}), in which we inter-related two images of the sky \emph{via} a CmpMap. If the two images turned out to be simply offset from each other by a shift along each pixel axis, then this approach would align them correctly, but it would be inefficient. This is because it would introduce unnecessary and expensive transformations to and from an intermediate celestial coordinate system, whereas a simple shift of pixel origin would suffice. Recognising that a simpler and more efficient solution exists obviously requires a little more than simply joining two Mappings end-to-end. We must also determine whether the resulting CmpMap is more complex than it needs to be, \emph{i.e.}\ contains redundant information. If it is, we then need a way to simplify it. The problem is not always just one of efficiency, however. Sometimes we may also need to know something about the actual form a \htmlref{Mapping}{Mapping} takes---\emph{i.e.}\ the nature of the operations it performs. Unnecessary complexity can obscure this, but such complexity can easily accumulate during normal data processing. For example, a Mapping that transforms pixel coordinates into positions on the sky might be repeatedly modified as changes are made to the shape and size of the image. Typically, on each occasion, another Mapping will be concatenated to reflect what has happened to the image. This could soon make it difficult to discern the overall nature of the transformation from the complex CmpMap that accumulates. If only shifts of origin were involved on each occasion, however, they could be combined into a single shift which could be represented much more simply. Suppose we now wanted to represent our image's celestial coordinate calibration using FITS conventions (\secref{ss:foreignfits}). This requires AST to determine whether the Mapping which relates pixel coordinate to sky positions conforms to the FITS model (for example, whether it is equivalent to applying a single set of shifts and scale factors followed by a map projection). Clearly, there is an important use here for some means of simplifying the internal structure of a CmpMap. \subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings} The ability to simplify compound Mappings is provided by the \htmlref{astSimplify}{astSimplify} function. This function encapsulates a number of heuristics for converting Mappings, or combinations of Mappings within a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap, astSimplify tries to reduce the number of individual Mappings within it by merging neighbouring component Mappings together. It will do this with both series and parallel combinations of Mappings, or both, and will handle CmpMaps nested to any depth (\secref{ss:complexcmpmap}). To illustrate how astSimplify works, consider the combination of Mappings shown in Figure~\ref{fig:simplifyexample}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/simpexamp} \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps, ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single UnitMap. The enclosing nested CmpMaps have been omitted for clarity.} \label{fig:simplifyexample} \end{center} \end{figure} If this were contained in a CmpMap, it could be simplified as follows: \small \begin{terminalv} AstMapping *simpler; ... simpler = astSimplify( cmpmap ); \end{terminalv} \normalsize In this case, the result would be a simple 3-dimensional UnitMap (the identity \htmlref{Mapping}{Mapping}). To reach this conclusion, astSimplify will have made a number of deductions, roughly as follows: \begin{enumerate} \item The two 2-dimensional ZoomMaps in series are equivalent to a single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is equivalent to a 2-dimensional UnitMap. \item This UnitMap in parallel with the other 1-dimensional UnitMap is equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched between any other pair of Mappings, can then be eliminated. \item The remaining two PermMaps in series are equivalent to a single 3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap is found to be equivalent to a 3-dimensional UnitMap. \end{enumerate} This example is a little contrived, but illustrates how astSimplify can deal with even quite complicated compound Mappings through a series of incremental simplifications. Where possible, this will result in either a simpler compound Mapping or, if feasible, an atomic (non-compound) Mapping, as here. If no simplification is possible, astSimplify will just return a pointer to the original Mapping. Although astSimplify cannot identify every simplification that is theoretically possible, sufficient rules are included to deal with the most common and important cases. \cleardoublepage \section{\label{ss:frames}Representing Coordinate Systems (Frames)} An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is used to describe how to convert between coordinate systems. The two concepts are complementary and we will see how they work together in \secref{ss:framesets}. In this section we will discuss only basic Frames, which represent Cartesian coordinate systems. More specialised types of Frame (\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes}) and, naturally, inherit the properties and behaviour of the simple Frames discussed here. \subsection{The Frame Model} The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would plot around a graph. In two dimensions, you would have an ``$x$'' and a ``$y$'' axis, a title on the graph and labels on the axes, together with an indication of the physical units being plotted. The values marked along each axis would be formatted in a human-readable way. The frame around a graph therefore defines a coordinate space within which you can locate points, draw lines, calculate distances, \emph{etc.} An AST Frame works in much the same way, embodying all of these concepts and a few more. It also allows any number of axes, which means that a Frame can represent coordinate systems with any number of dimensions. You specify how many when you create it. Remember that the basic Frame we are considering here is completely general. It knows nothing of celestial coordinates, for example, and all its axes are equivalent. It can be adapted to describe any general purpose Cartesian coordinate system by setting its attributes, such as its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values. \subsection{\label{ss:creatingframes}Creating a Frame} Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern: \small \begin{terminalv} #include "ast.h" astFrame *frame; ... frame = astFrame( 2, "" ); \end{terminalv} \normalsize The first argument of the \htmlref{astFrame}{astFrame} constructor function specifies the number of axes which the Frame should have. \subsection{\label{ss:frameasmapping}Using a Frame as a Mapping} We should briefly point out that the \htmlref{Frame}{Frame} we created above (\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping} (\secref{ss:mappingclass}) and therefore inherits the properties and behaviour common to other Mappings. One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited from the Mapping class) to a non-zero value and pass the Frame pointer to a coordinate transformation function, such as \htmlref{astTran2}{astTran2}. \small \begin{terminalv} double xin[ 5 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 }; double yin[ 5 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0 }; double xout[ 5 ]; double yout[ 5 ]; ... astSet( frame, "Report=1" ); astTran2( frame, 5, xin, yin, 1, xout, yout ); \end{terminalv} \normalsize The resulting output might then look like this: \begin{terminalv} (1, 2) --> (1, 2) (2, 4) --> (2, 4) (3, 6) --> (3, 6) (4, 8) --> (4, 8) (5, 10) --> (5, 10) \end{terminalv} This is not very exciting because a Frame implements an identity transformation just like a \htmlref{UnitMap}{UnitMap} (\secref{ss:unitmapexample}). However, it illustrates that a Frame can be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both equal to the number of Frame axes. When we consider more specialised Frames (\emph{e.g.}~\secref{ss:framesets}), we will see that using them as Mappings can be very useful indeed. \subsection{\label{ss:frameaxisattributes}Frame Axis Attributes} Frames have a number of attributes which can take multiple values, one for each axis. These separate values are identified by appending the axis number in parentheses to the attribute name. For example, the Label(1) attribute is a character string containing the label which appears on the first axis. \htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes (\secref{ss:gettingattributes}, \secref{ss:settingattributes} and \secref{ss:defaultingattributes}). For example, the Label on the second axis might be obtained as follows: \small \begin{terminalv} const char *label; ... label = astGetC( frame, "Label(2)" ); \end{terminalv} \normalsize Other attribute access functions (astSetX, \htmlref{astTest}{astTest} and \htmlref{astClear}{astClear}) may also be applied to axis attributes in the same way. If the axis number is stored in a program variable, then its value must be formatted to generate a suitable attribute name before using this to access the attribute itself. For example, the following will print out the Label value for each axis of a \htmlref{Frame}{Frame}: \small \begin{terminalv} #include char name[ 18 ]; int iaxis, naxes; ... naxes = astGetI( frame, "Naxes" ); for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { (void) sprintf( name, "Label(%d)", iaxis ); label = astGetC( frame, name ); (void) printf( "Label %2d: %s\n", iaxis, label ); } \end{terminalv} \normalsize Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame axes. The output from this might look like the following: \begin{terminalv} Label 1: Axis 1 Label 2: Axis 2 \end{terminalv} In this case, the Frame's default axis Labels have been revealed as rather un-exciting. Normally, you would set much more useful values, typically when you create the Frame---perhaps something like: \small \begin{terminalv} frame = astFrame( 2, "Label(1)=Offset from centre of field," "Unit(1) =mm," "Label(2)=Transmission coefficient," "Unit(2) =%" ); \end{terminalv} \normalsize Here, we have also set the (character string) Unit attribute for each axis to describe the physical units represented on that axis. All the attribute assignments have been combined into a single string, separated by commas. \subsection{\label{ss:frameattributes}Frame Attributes} We will now briefly outline the various attributes associated with a \htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the \htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each attribute, for which you should consult the appropriate description in \appref{ss:attributedescriptions}. Instead, we aim simply to sketch the range of facilities available: \begin{quote} \begin{description} \item[\htmlref{Naxes}{Naxes}]\mbox{}\\ A read-only integer giving the number of Frame axes. \item[\htmlref{Title}{Title}]\mbox{}\\ A string describing the coordinate system which the Frame represents. \item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\ A label string for each axis. \item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\ A string describing the physical units on each axis. You can choose whether to make this attribute ``active'' or ``passive'' (using \htmlref{astSetActiveUnit}{astSetActiveUnit} ). If active, its value will be taken into account when finding the Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used to connect two axis with units of ``km'' and ``m''). If passive, its value is ignored. Its use is described in more detail in \secref{ss:frameunits}. \item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\ A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X'' or ``Y'') used to represent the quantity plotted on each axis. \item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\ The preferred number of digits of precision to be used when formatting values for display on each axis. \item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\ A string containing a \emph{format specifier} which determines exactly how values should be formatted for display on each axis (\secref{ss:formattingaxisvalues}). If this attribute is un-set, the formatting is based on the Digits value, otherwise the Format string over-rides the Digits value. \item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\ A boolean (integer) value which indicates in which direction each axis should be plotted. If it is non-zero (the default), the axis should be plotted in the conventional direction---\emph{i.e.}\ increasing to the right for the abscissa and increasing upwards for the ordinate. If it is zero, the axis should be plotted in reverse. This attribute is provided as a hint only and programs are free to ignore it if they wish. \item[\htmlref{Domain}{Domain}]\mbox{}\\ A character string which identifies the \emph{physical domain} to which the Frame's coordinate system applies. The primary purpose of this attribute is to prevent unwanted conversions from occurring between coordinate systems which are not related. Its use is described in more detail in \secref{ss:framedomains}. \item[\htmlref{System}{System}]\mbox{}\\ A character string which identifies the specific coordinate system used to describe positions within the physical domain represented by the Frame. For a simple Frame, this attribute currently has a fixed value of ``Cartesian'', but could in principle be extended to include options such as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame} and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be appropriate to the domain which they describe. For instance, the SkyFrame allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows values such as ``frequency'' and ``wavelength''. \item[\htmlref{Epoch}{Epoch}]\mbox{}\\ This value is used to qualify a coordinate system by giving the moment in time when the coordinates are correct. Usually, this will be the date of observation. The Epoch value is important in cases where coordinates systems move with respect to each other over time. An example of two such coordinate systems are the FK4 and FK5 celestial coordinate systems. \item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\ Specifies the longitude of the observer (assumed to be on the surface of the earth). The basic Frame class does not use this value, but specialised sub-classes may. For instance, the SpecFrame class uses it to calculate the relative velocity of the observer and the centre of the earth for use in converting between standards of rest. \item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\ Specifies the latitude of the observer. Use in conjunction with ObsLon. \end{description} \end{quote} There are also some further Frame attributes, not described above, which are important when Frames are used as templates to search for other Frames. Their use goes beyond the present discussion. %TBW---Add reference here. \subsection{\label{ss:formattingaxisvalues}Formatting Axis Values} The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored (\emph{e.g.}\ within your program) as double values. The Frame class therefore provides a function, \htmlref{astFormat}{astFormat}, to convert these values into formatted strings for display: \small \begin{terminalv} const char *string double value; ... string = astFormat( frame, iaxis, value ); \end{terminalv} \normalsize Here, the astFormat function is passed a Frame pointer, the number of an axis (``iaxis'') and a double precision value to format (``value''). It returns a pointer to character string containing the formatted value. \label{ss:formattingwithdigits} By default, the formatting applied will be determined by the Frame's Digits attribute and will normally display results with seven digits of precision (corresponding approximately to the C ``float'' data type on many machines). Setting a different Digits value, however, allows you to adjust the precision as necessary to suit the accuracy of the coordinate data you are processing. If finer control is needed, it is also possible to set a Digits value for each individual axis by appending an axis number to the attribute name (\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the effect of the Frame's main Digits value for that axis. Even finer control is possible by setting the (character string) Format attribute for a Frame axis. The string given should contain a C \emph{format specifier} which explicitly determines how the values on that axis should be formatted. This will over-ride the effects of any Digits value\footnote{The exception to this rule is that if the Format value includes a precision of ``$.*$'', then Digits will be used to determine the actual precision used.}. Any valid ``printf'' format specifier may be used so long as it consumes exactly one double value. When setting Format values, remember that the ``\%'' which appears in the format specifier may need to be doubled to ``\%\%'' if you are using a function (such as \htmlref{astSet}{astSet}) which interprets ``printf'' format specifiers itself. It is recommended that you use astFormat whenever you display formatted coordinate values, even although you could format them yourself using ``sprintf''. This is because it puts the Frame in control of formatting. When you start to handle more elaborate Frames (representing, say, celestial coordinates), you will need different formatting methods. This approach delivers them without any change to your software. You should also consider regularly using the \htmlref{astNorm}{astNorm} function, described below (\secref{ss:normalising}), for any values that will be made visible to the user of your software. \subsection{\label{ss:normalising}Normalising Frame Coordinates} The function \htmlref{astNorm}{astNorm} is provided to cope with the fact that some coordinate systems do not extend indefinitely in all directions. Some may have boundaries, outside which coordinates are meaningless, while others wrap around on themselves, so that after a certain distance you return to the beginning again (coordinate systems based on circles and spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but other more specialised Frames (such as SkyFrames, representing the celestial sphere---\secref{ss:skyframes}) do. The role played by astNorm is to \emph{normalise} any arbitrary set of coordinates by converting them into a set which is ``within bounds'', interpreted according to the particular Frame in question. For example, on the celestial sphere, a right ascension value of 24~hours or more can have a suitable multiple of 24~hours subtracted without affecting its meaning and astNorm would perform this task. Similarly, negative values of right ascension would have a multiple of 24~hours added, so that the result lies in the range zero to 24~hours. The coordinates in question are modified in place by astNorm, as follows: \small \begin{terminalv} double point[ 2 ]; ... astNorm( frame, point ); \end{terminalv} \normalsize If the coordinates supplied are initially OK, as they would always be with a basic Frame, then they are returned unchanged. Because the main purpose of astNorm is to convert coordinates into the preferred range for human consumption, its use is almost always appropriate immediately before formatting coordinate values for display using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}). Even if the Frame in question does not restrict the range of coordinates, so that astNorm does nothing, using it will allow you to process other more specialised Frames, where normalisation is important, without changing your software. \subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values} The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame} axis, such as might be produced by \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}), back into a numerical (double) value ready for processing is performed by \htmlref{astUnformat}{astUnformat}. However, although this process is essentially the inverse of that performed by astFormat, there are a number of additional difficulties that must be addressed in practice. The main use for astUnformat is in reading formatted coordinate values which have been entered by the user of a program, or read from a file. As such, we can rarely assume that the values are neatly formatted in the way that astFormat would produce. Instead, it is usually desirable to allow considerable flexibility in the form of input that can be accommodated, so as to permit ``free-format'' data input by the user. In addition, we may need to extract individual coordinate values embedded in other textual data. Underlying these requirements is the root difficulty that the textual format used to represent a coordinate value will depend on the class of Frame we are considering. For example, for a basic Frame, astUnformat may have to read a value like ``1.25e-6'', whereas for a more specialised Frame representing celestial coordinates it may have to handle a value like ``-07d~49m~13s''. Of course, the format might also depend on which axis is being considered. Ideally, we would like to write software that can handle any kind of Frame. However, this makes it a little more difficult to analyse textual input data to extract individual coordinate values, since we cannot make assumptions about how the values are formatted. It would not be safe, for example, simply to assume that the values being read are separated by white space. This is not just because they might be separated by some other character, but also because celestial coordinate values might themselves contain spaces. In fact, to be completely safe, we cannot make any assumptions about how a formatted coordinate value is separated from the surrounding text, except that it should be separated in some way which is not ambiguous. This is the very basic assumption upon which astUnformat works. It is invoked as follows: \small \begin{terminalv} int n; ... n = astUnformat( frame, iaxis, string, &value ); \end{terminalv} \normalsize It is supplied with a Frame pointer (``frame''), the number of an axis (``iaxis'') and a character string to be read (``string''). If it succeeds in reading a value, astUnformat returns the resulting coordinate to the address supplied \emph{via} the final argument (``\&value''). The returned function value indicates how many characters were read from the string in order to obtain this result. The string is read as follows: \begin{enumerate} \item Any white space at the start is skipped over. \item Further characters are considered, one at a time, until the next character no longer matches any of the acceptable forms of input (given the characters that precede it). The longest sequence of characters which matches is then considered ``read''. \item If a suitable sequence of characters was read successfully, it is converted into a coordinate value which is returned. Any white space following this sequence is then skipped over and the total number of characters consumed is returned as the function value. \item If the sequence of characters read is empty, or insufficient to define a coordinate value, then the string does not contain a value to read. In this case, the read is aborted and astUnformat returns a function value of zero and no coordinate value. However, it returns without error. \end{enumerate} Note that failing to read a coordinate value does not constitute an error, at least so far as astUnformat is concerned. However, an error can occur if the sequence of characters read appears to have the correct form but cannot be converted into a valid coordinate value. Typically, this will be because it violates some constraint, such as a limit on the value of one of its fields. The resulting error message will give details. For any given Frame axis, astUnformat does not necessarily always use the same algorithm for converting the sequence of characters it reads into a coordinate value. This is because some forms of input (particularly free-format input) can be ambiguous and might be interpreted in several ways depending on the context. For example, the celestial longitude ``12:34:56.7'' could represent an angle in degrees or a right ascension in hours. To decide which to use, astUnformat may examine the Frame's attributes and, in particular, the appropriate \htmlref{Format(axis)}{Format(axis)} string which is used by astFormat when formatting coordinate values (\secref{ss:formattingaxisvalues}). This is done in order that astFormat and astUnformat should complement each other---so that formatting a value and then un-formatting it will yield the original value, subject to any rounding error. To give a simple (but crucially incomplete!) example, consider reading a value for the axis of a basic Frame, as follows: \small \begin{terminalv} n = astUnformat( frame, iaxis, " 1.5e6 -99.0", &value ); \end{terminalv} \normalsize astUnformat will skip over the initial space in the string supplied and then examine each successive character. It will accept the sequence ``1.5e6'' as input, but reject the space which follows because it does not form part of the format of a floating point number. It will then convert the characters ``1.5e6'' into a coordinate value and skip over the three spaces which follow them. The returned function value will therefore be 9, equal to the total number of characters consumed. This result may be used to address the string during a subsequent read, so as to commence reading at the start of ``-99.0''. Most importantly, however, note that if the user of a program mistakenly enters the string ``~1.5r6\ldots'' instead of ``~1.5e6\ldots'', a coordinate value of 1.5 and a function result of 4 will be returned, because the ``r'' would prematurely terminate the attempt to read the value. Because this sort of mistake does not automatically result in an error but can produce incorrect results, it is \textbf{vital} to check the returned function value to ensure that the expected number of characters have been read.\footnote{Anyone who seriously uses the C run time library ``scanf'' function will know about the need for this check!} For example, if the string is expected to contain exactly one value, and nothing else, then the following would suffice: \small \begin{terminalv} n = astUnformat( frame, iaxis, string, &value ); if ( astOK ) { if ( string[ n ] || !n ) { } else { } } \end{terminalv} \normalsize If astUnformat does not detect an error itself, we check that it has read to the end-of-string and consumed at least one character (which traps the case of a zero-length input string). If this reveals an error, the value of ``n'' indicates where it occurred. Another common requirement is to obtain a position by reading a list of coordinates from a string which contains one value for each axis of a Frame. We assume that the values are separated in some unambiguous manner, perhaps using white space and/or some unspecified single-character separator. The choice of separator is up to the data supplier, who must choose it so as not to conflict with the format of the coordinate values, but our software does not need to know what it is. The following is a template algorithm for reading data in this form: \small \begin{terminalv} const char *s; double values[ 10 ]; ... /* Initialise a string pointer. */ s = string; /* Obtain the number of Frame axes and loop through them. */ naxes = astGetI( frame, "Naxes" ); for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { /* Attempt to read a value for this axis. */ n = astUnformat( frame, iaxis, s, &values[ iaxis - 1 ] ); /* If nothing was read and this is not the first axis or the end-of-string, try stepping over a separator and reading again. */ if ( !n && ( iaxis > 1 ) && *s ) n = astUnformat( frame, iaxis, ++s, &values[ iaxis - 1 ] ); /* Quit if nothing was read, otherwise move on to the next value. */ if ( !n ) break; s += n; } /* Check for possible errors. */ if ( astOK ) { if ( *s || !n ) { } else { } } \end{terminalv} \normalsize In this case, ``s'' will point to the location of any input error. Note that this algorithm is insensitive to the precise format of the data and will therefore work with any class of Frame and any reasonably unambiguous input data. For example, here is a range of suitable input data for a 3-dimensional basic Frame: \small \begin{terminalv} 1 2.5 3 3.1,3.2,3.3 1.5, 2.6, -9.9e2 -1.1+0.4-1.8 .1/.2/.3 44.0 ; 55.1 -14 \end{terminalv} \normalsize \subsection{\label{ss:permutingaxes}Permuting Frame Axes} Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number of axes it contains, but it is possible to change the order in which these axes occur. To do so, an integer \emph{permutation array} is filled with the numbers of the axes so as to specify the new order, \emph{e.g.:} \small \begin{terminalv} int perm[ 2 ] = { 2, 1 }; \end{terminalv} \normalsize In this case, the axes of a 2-dimensional Frame could be interchanged by passing this permutation array to the \htmlref{astPermAxes}{astPermAxes} function. That is, an ($x_1,x_2$) coordinate system would be changed into an ($x_2,x_1$) coordinate system by: \small \begin{terminalv} astPermAxes( frame, perm ); \end{terminalv} \normalsize If the axes are permuted more than once, the effects are cumulative. You are, of course, not restricted to Frames with only two axes. \subsection{Selecting Frame Axes} An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not allowed, is to create a new Frame by selecting axes from an existing one. The method of doing this is very similar to the way \htmlref{astPermAxes}{astPermAxes} is used (\secref{ss:permutingaxes}), in that we supply an integer array filled with the numbers of the axes we want, in their new order. In this case, however, the number of array elements need not equal the number of Frame axes. For example, we could select axes 3 and 2 (in that order) from a 3-dimensional Frame as follows: \small \begin{terminalv} astFrame *frame1, *frame2; astMapping *mapping; int pick[ 2 ] = { 3, 2 }; ... frame2 = astPickAxes( frame1, 2, pick, &mapping ); \end{terminalv} \normalsize This would return a pointer to a 2-dimensional Frame (``frame2'') which contains the information associated with axes 3 and 2, in that order, from the original Frame (``frame1''). The original Frame is not altered by this process. Beware, however, that the axis information may still be shared by both Frames, so if you wish to alter either of them independently you may first need to use \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}) to make an independent copy. In addition to the new Frame pointer, \htmlref{astPickAxes}{astPickAxes} will also return a pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument (you may supply a NULL pointer as an argument if you do not want this Mapping). This Mapping will inter-relate the two Frames. By this we mean that its forward transformation will convert coordinates originally in the coordinate system represented by ``frame1'' into that represented by ``frame2'', while its inverse transformation will convert in the opposite direction. In this particular case, the Mapping would be a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following transformations: \begin{terminalv} Forward: (1, 2, 3) --> (3, 2) (2, 4, 6) --> (6, 4) (3, 6, 9) --> (9, 6) (4, 8, 12) --> (12, 8) (5, 10, 15) --> (15, 10) Inverse: (3, 2) --> (, 2, 3) (6, 4) --> (, 4, 6) (9, 6) --> (, 6, 9) (12, 8) --> (, 8, 12) (15, 10) --> (, 10, 15) \end{terminalv} This is our first introduction to the idea of inter-relating pairs of Frames \emph{via} a Mapping, but this will assume a central role later on. Note that when using astPickAxes, it is also possible to request more axes than there were in the original Frame. This will involve selecting axes from the original Frame that do not exist. To do this, the corresponding axis number (in the ``pick'' array) should be set to zero and the effect is to introduce an additional new axis which is not derived from the original Frame. This axis will have default values for all its attributes. You will need to do this because astPickAxes does not allow you to select any of the original axes more than once.\footnote{It will probably not be obvious why this restriction is necessary, but consider creating a Frame with one longitude axis and two latitude axes. Which latitude axis should be associated with the longitude axis?} \subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets} Some complementary functions are provided for use with Frames to allow you to perform geometric operations without needing to know the nature of the coordinate system represented by the \htmlref{Frame}{Frame}. Functions can be used to find the distance between two points, and to offset a specified distance along a line joining two points, \emph{etc.} In essence, these define the metric of the coordinate space which the Frame represents. In the case of a basic Frame, this is a Cartesian metric. The first of these functions, \htmlref{astDistance}{astDistance}, returns a double distance value when supplied with the Frame coordinates of two points. For example: \small \begin{terminalv} double dist; double point1[ 2 ] = { 0.0, 0.0 }; double point2[ 2 ] = { 1.0, 1.0 }; ... dist = astDistance( frame, point1, point2 ); \end{terminalv} \normalsize This calculates the distance between the origin (0,0) and a point at position (1,1). In this case, the result, as you would expect, is $\surd{2}$. However, this is only true for the Cartesian coordinate system which a basic Frame represents. In general, astDistance will calculate the geodesic distance between the two points, so that with a more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial sphere) a great-circle distance might be returned. The \htmlref{astOffset}{astOffset} function is really the inverse of astDistance. Given two points in a Frame, it calculates the coordinates of a third point which is offset a specified distance away from the first point along the geodesic joining it to the second one. For example: \small \begin{terminalv} double point1[ 2 ] = { 0.0, 0.0 }; double point2[ 2 ] = { 1.0, 1.0 }; double point3[ 2 ]; ... astOffset( frame, point1. point2, 0.5, point3 ); \end{terminalv} \normalsize This would fill the ``point3'' array with the coordinates of a point which is offset 0.5 units away from the origin (0,0) in the direction of the position (1,1). Again, this is a simple result in a Cartesian Frame, as varying the offset will trace out a straight line. On the celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would trace out a great circle. The functions \htmlref{astAxDistance}{astAxDistance} and \htmlref{astAxOffset}{astAxOffset} are similar to astDistance and astOffset, except that the curves which they use as ``straight lines'' are not geodesics, but curves parallel to a specified axis\footnote {For instance, a line of constant Declination is not a geodesic}. One reason for using these functions is to deal with the cyclic ambiguity of longitude and latitude axes. The \htmlref{astOffset2}{astOffset2} function is similar to astOffset, but instead of using the geodesic which passes through two positions, it uses the geodesic which passes at a given position angle through the starting position. Position angles are always measured from the positive direction of the second Frame axis to the required line, with positive angles being in the same sense as rotation from the positive direction of the second axis to the positive direction of the first Frame axis. This definition applies to all classes of Frame, including SkyFrame. The default ordering of axes in a SkyFrame makes the second axis equivalent to north, and so the definition of position angle given above corresponds to the normal astronomical usage, ``from north, through east''. However, it should be remembered that it is possible to permute the axes of a SkyFrame (or indeed any Frame), so that north becomes axis 1. In this case, an AST ``position angle'' would be the angle ``from east, through north''. Always take the axis ordering into account when deriving an astronomical position angle from an AST position angle. Within a Cartesian coordinate system, the position angle of a geodesic (\emph{i.e.}\ a straight line) is constant along its entire length, but this is not necessarily true of other coordinate systems. Within a spherical coordinate system, for instance, the position angle of a geodesic will vary along its length (except for the special cases of a meridian and the equator). In addition to returning the required offset position, the astOffset2 function returns the position angle of the geodesic at the offset position. This is useful if you want to trace out a path which involves turning through specified angles. For instance, tracing out a rectangle in which each side is a geodesic involves turning through 90 degrees at the corners. To do this, use astOffset2 to calculate the position of each corner, and then add (or subtract) 90 degrees from the position angle returned by astOffset2. The \htmlref{astAngle}{astAngle} function calculates the angle subtended by two points, at a third point. If used with a 2-dimensional Frame the returned angle is signed to indicate the sense of rotation (clockwise or anti-clockwise) in taking the ``shortest route'' from the first point to the second. If the Frame has more than 2 axes, the result is un-signed and is always in the range zero to $\pi$. The \htmlref{astAxAngle}{astAxAngle} function is similar to astAngle, but the ``reference direction'', from which angles are measured, is a specified axis. The \htmlref{astResolve}{astResolve} function resolves a given displacement within a Frame into two components, parallel and perpendicular to a given reference direction. The displacement is specified by two positions within the Frame; the starting and ending positions. The reference direction is defined by the geodesic curve passing through the starting position and a third specified position. The lengths of the two components are returned, together with the position on the reference geodesic which is closest to the third supplied point. \subsection{\label{ss:framedomains}The Domain Attribute} The \htmlref{Domain}{Domain} attribute is one of the most important properties of a \htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little subtle. We will introduce it here, but its true value will probably not become apparent until later (\secref{ss:framesetconverting}). To understand the need for the Domain attribute, consider using different Frames to represent the following different coordinate systems associated with a CCD image: \begin{enumerate} \item A coordinate system based on pixel numbers. \item Positions on the CCD chip, measured in $\mu$m. \item Positions in the focal plane of the telescope, measured in mm. \item A celestial coordinate system, measured in radians. \end{enumerate} If we had two such CCD images, we might legitimately want to align them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based on pixel numbers) in order to, say, divide by a flat-field exposure. We might similarly consider aligning them using any of the other coordinate systems so as to achieve different results. For example, we might consider merging separate images from a CCD mosaic by using focal plane positions. It would obviously not be legitimate, however, to directly compare positions in one image measured in pixels with positions in the other measured in mm, nor to equate chip positions in $\mu$m with sky coordinates in radians. If we wanted to inter-compare these coordinates, we would need to do it indirectly, using other information based on the experimental set-up. For instance, we might need to know the size of the pixels expressed in mm and the orientation of the CCD chip in the focal plane. Note that it is not simply the difference in physical units which prevents certain coordinates from being directly inter-compared (because the appropriate unit scaling factors could be included without any additional information). Neither is it the fact that different coordinate systems are in use (because we could legitimately inter-compare two different celestial coordinate systems without any extra information). Instead, it is the different nature of the coordinate spaces to which these coordinate systems have been applied. We normally express this by saying that the coordinate systems apply to different \emph{physical domains}. Although we may establish \emph{ad hoc} relationships between coordinates in different physical domains, they are not intrinsically related to each other and we need to supply extra information before we can convert coordinates between them. In AST, the role of the (character string) Domain attribute is to assign Frames to their respective physical domains. The way it operates is as follows: \begin{itemize} \item Coordinate systems which apply to the same physical domain (\emph{i.e.}\ whose Frames have the same Domain value) can be directly inter-compared. If the domain has several coordinate systems associated with it (\emph{e.g.}\ the celestial sphere), then a coordinate conversion may be involved. Otherwise, coordinate values may simply be equated. \item Coordinate systems which apply to different physical domains (\emph{i.e.}\ whose Frames have different Domain values) cannot be directly inter-compared. If any relationship does exist between such coordinate systems---and it need not---then additional information must be supplied in order to establish the relationship between them in any particular case. We will see later (\secref{ss:framesets}) how to establish such relationships between Frames in different domains. \end{itemize} With the basic Frames we are considering here, each physical domain only has a single (Cartesian) coordinate system associated with it, so that if two such Frames have the same Domain value, their coordinate systems will be identical and may simply be equated. With more specialised Frames, however, more than one coordinate system may apply to each domain. In such cases, a coordinate conversion may need to be performed. When a basic Frame is created, its Domain attribute defaults to an empty string. This means that all such Frames belong to the same (null) domain by default and therefore describe the same unspecified physical coordinate space. In order to assign a Frame to a different domain, you simply need to set its Domain value. This is normally most conveniently done when it is created, as follows: \small \begin{terminalv} frame1 = astFrame( 2, "Domain=CCD_CHIP," "Unit(1)=micron," "Unit(2)=micron" ); frame2 = astFrame( 2, "Domain=FOCAL_PLANE," "Unit(1)=mm," "Unit(2)=mm" ); \end{terminalv} \normalsize Here, we have created two Frames in different physical domains. Although their coordinate values all have units of length, they cannot be directly inter-compared (because their axes may be rotated with respect to each other, for instance). All Domain values are automatically converted to upper case and white space is removed, but there are no other restrictions on the names you may use to label different physical domains. From a practical point of view, however, it is worth following a few conventions (\secref{ss:domainconventions}). \subsection{\label{ss:domainconventions}Conventions for Domain Names} When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it obviously makes sense to avoid generic names which might clash with those used for similar (but subtly different!) purposes by other programmers. If you are developing software for an instrument, for example, and want to identify an instrumental coordinate system, then it is sensible to add a distinguishing prefix. For instance, you might use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an acronym) identifies your instrument. For some purposes, however, a standard choice of Domain name is desirable so that different items of software can communicate. For this purpose, the following Domain names are reserved by AST and the use recommended below should be carefully observed: \begin{quote} \begin{description} \item[GRAPHICS]\mbox{}\\ Identifies the coordinate space used by an underlying computer graphics system to specify plotting operations. Typically, when performing graphical operations, AST is used to define additional coordinate systems which are related to these ``native'' graphical coordinates. Plotting may be carried out in any of these coordinate systems, but the GRAPHICS domain identifies the native coordinates through which AST communicates with the underlying graphics system. \item[GRID]\mbox{}\\ Identifies the instantaneous \emph{data grid} used to store and handle data, together with an associated coordinate system. In this coordinate system, the first element stored in an array of data always has a coordinate value of unity at its centre and all elements have unit extent. This applies to all dimensions. If data are copied or transformed to a new data grid (by whatever means), or a subset of the original grid is extracted, then the same rules apply to the copy or subset. Its first element therefore has GRID coordinate values of unity at its centre. Note that this means that GRID coordinates remain attached to the first element of the data grid and not to its data content (\emph{e.g.}\ the features in an image). \item[PIXEL]\mbox{}\\ Identifies an array of pixels and an associated \emph{pixel-based} coordinate system which is related to the GRID coordinate system (above) simply by a shift of origin along each axis. This shift may be integral, fractional, positive, negative or zero. The data elements retain their unit extent along each axis. Because the amount of shift is unspecified, the PIXEL domain is distinct from the GRID domain. The relationship between them contains a degree of uncertainty, such as typically arises from the different conventions used by different software systems. For instance, in some software the first pixel is regarded as being centred at (1,1), while in other software it is at (0.5,0.5). In addition, some software packages implement a ``pixel origin'' which allows pixel coordinates to start at an arbitrary value. The GRID domain (which corresponds with the pixel-numbering convention used by FITS) is a special case of the PIXEL domain and avoids this uncertainty. In general, additional information is required in order to convert from one to the other. \item[SKY]\mbox{}\\ Identifies the domain which contains all equivalent celestial coordinate systems. Because these are represented in AST by SkyFrames (\secref{ss:skyframes}), it should be no surprise that the default Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you probably won't need to change this very often. \item[SPECTRUM]\mbox{}\\ Identifies the domain used to describe positions within an electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes}) class describes positions within this domain, allowing a wide range of different coordinate systems to be used (frequency, wavelength, \emph{etc}). The default Domain value for a SpecFrame is SPECTRUM. \item[TIME]\mbox{}\\ Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame} class describes positions within this domain, allowing a wide range of different coordinate systems and timescales to be used. The default Domain value for a TimeFrame is TIME. \end{description} \end{quote} Although we have drawn a necessary distinction here between the GRID and PIXEL domains, we will continue to refer in general terms to image ``pixels'' and ``pixel coordinates'' whenever this distinction is not important. This should not be taken to imply that the GRID convention for numbering pixels is excluded---in fact, it is usually to be preferred (at the level of data handling being discussed in this document) and we recommend it. \subsection{\label{ss:frameunits}The Unit Attribute} Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used to describe positions on the axis. The index of the axis to which the attribute refers should normally be placed in parentheses following the attribute name (``Unit(2)'' for instance). However, if the Frame has only a single axis, then the axis index can be omitted. In versions of AST prior to version 2.0, the Unit attribute was nothing more than a descriptive string intended purely for human readers---no part of the AST system used the Unit string for any purpose (other than inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between two Frames. Thus if the conversion between a pair of 1-dimensional Frames representing velocity was found (using \htmlref{astConvert}{astConvert} ) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is referred to below as a \emph{passive} Unit attribute. As of AST version 2.0, a facility exists which allows the Unit attribute to be \emph{active}; that is, differences in the Unit attribute may be taken into account when finding the Mapping between two Frames. In order to minimise the risk of breaking older software, the \emph{default} behaviour of simple Frames and SkyFrames is unchanged from previous versions (\emph{i.e.} they have passive Unit attributes). However, the new functions \htmlref{astSetActiveUnit}{astSetActiveUnit} and \htmlref{astGetActiveUnit}{astGetActiveUnit} allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame} classes \emph{always} have an active Unit attribute (attempts to change this are ignored). For instance, consider the above example of two 1-dimensional Frames describing velocity. These Frames can be created as follows: \small \begin{terminalv} AstFrame *frame1, *frame2; frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" ); frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" ); \end{terminalv} \normalsize By default, these Frames have passive Unit attributes, and so an attempt to find a Mapping between them would ignore the difference in their Unit attributes and return a unit Mapping. To avoid this, we indicate that we want these Frames to have \emph{active} Unit attributes, as follows: \small \begin{terminalv} astSetActiveUnit( frame1, 1 ); astSetActiveUnit( frame2, 1 ); \end{terminalv} \normalsize If we then find the Mapping between them as follows: \small \begin{terminalv} AstFrameSet *cvt; ... cvt = astConvert( frame1, frame2, "" ); \end{terminalv} \normalsize the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by astConvert will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a velocity in $km/h$) by a factor of 0.278 to create its output (a velocity in $m/s$). In fact we need not have set the Unit attribute active in ``frame1'' since the behaviour of astConvert is determined by its ``to'' Frame (the second Frame parameter). \subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings} Conversion between units systems relies on the use of a specific syntax for the Unit attribute. If the value of the Unit attribute does not conform to this syntax, then an error will be reported if an attempt is made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen if the Unit attribute is \emph{passive}). The adopted syntax is that described in FITS-WCS paper I "Representation of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish here between ``basic'' units and ``derived'' units: derived units are defined in terms of other units (either derived or basic), whereas basic units have no such definitions. Derived units may be represented by their own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a \emph{mathematical expression} which combines other symbols and constants to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per second). Unit symbols may be prefixed by a string representing a standard multiple or sub-multiple. In addition to the unit symbols listed in FITS-WCS Paper I, any other arbitrary unit symbol may be used, with the proviso that it will not be possible to convert between Frames using such units. The exception to this is if both Frames refer to the same unknown unit string. For instance, an axis with unknown unit symbol "flop" \emph{could} be converted to an axis with unit "Mflop" (Mega-flop). Unit symbols (optionally prefixed with a multiple or sub-multiple) can be combined together using a limited range of mathematical operators and functions, to produce new units. Such expressions may also contain parentheses and numerical constants (these may optionally use ``scientific'' notation including an ``E'' character to represent the power of 10). The following tables list the symbols for the basic and derived units which may be included in a units string, the standard prefixes for multiples and sub-multiples, and the strings which may be used to represent mathematical operators and functions. \begin{table}[htbp] \begin{center} \begin{tabular}{|l|l|l|} \hline \multicolumn{3}{|c|}{{\large Basic units}} \\ \hline \multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & \multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline length & m & metre \\ mass & g & gram \\ time & s & second \\ plane angle & rad & radian \\ solid angle & sr & steradian \\ temperature & K & Kelvin \\ electric current & A & Ampere \\ amount of substance & mol & mole \\ luminous intensity & cd & candela \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{small} \begin{tabular}{|l|l|l|l|} \hline \multicolumn{4}{|c|}{{\large Derived units}} \\ \hline \multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & \multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline area & barn & barn & 1.0E-28 m**2 \\ area & pix & pixel & \\ area & pixel & pixel & \\ electric capacitance & F & Farad & C/V \\ electric charge & C & Coulomb & A s \\ electric conductance & S & Siemens & A/V \\ electric potential & V & Volt & J/C \\ electric resistance & Ohm & Ohm & V/A \\ energy & J & Joule & N m \\ energy & Ry & Rydberg & 13.605692 eV \\ energy & eV & electron-Volt & 1.60217733E-19 J \\ energy & erg & erg & 1.0E-7 J \\ events & count & count & \\ events & ct & count & \\ events & ph & photon & \\ events & photon & photon & \\ flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\ flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\ flux density & mag & magnitude & \\ force & N & Newton & kg m/s**2 \\ frequency & Hz & Hertz & 1/s \\ illuminance & lx & lux & lm/m**2 \\ inductance & H & Henry & Wb/A \\ length & AU & astronomical unit & 1.49598E11 m \\ length & Angstrom & Angstrom & 1.0E-10 m \\ length & lyr & light year & 9.460730E15 m \\ length & pc & parsec & 3.0867E16 m \\ length & solRad & solar radius & 6.9599E8 m \\ luminosity & solLum & solar luminosity & 3.8268E26 W \\ luminous flux & lm & lumen & cd sr \\ magnetic field & G & Gauss & 1.0E-4 T \\ magnetic flux & Wb & Weber & V s \\ mass & solMass & solar mass & 1.9891E30 kg \\ mass & u & unified atomic mass unit & 1.6605387E-27 kg \\ magnetic flux density & T & Tesla & Wb/m**2 \\ plane angle & arcmin & arc-minute & 1/60 deg \\ plane angle & arcsec & arc-second & 1/3600 deg \\ plane angle & mas & milli-arcsecond & 1/3600000 deg \\ plane angle & deg & degree & pi/180 rad \\ power & W & Watt & J/s \\ pressure, stress & Pa & Pascal & N/m**2 \\ time & a & year & 31557600 s \\ time & d & day & 86400 s \\ time & h & hour & 3600 s \\ time & yr & year & 31557600 s \\ time & min & minute & 60 s \\ & D & Debye & 1.0E-29/3 C.m \\ \hline \end{tabular} \end{small} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{tabular}{|lll|lll|} \hline \multicolumn{6}{|c|}{{\large Prefixes for multiples \& sub-multiples}} \\ \hline \multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & \multicolumn{1}{c|}{Prefix} & \multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & \multicolumn{1}{c|}{Prefix} \\ \hline $10^{-1}$ & deci & d & $10$ & deca & da \\ $10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\ $10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\ $10^{-6}$ & micro & u & $10^{6}$ & mega & M \\ $10^{-9}$ & nano & n & $10^{9}$ & giga & G \\ $10^{-12}$ & pico & p & $10^{12}$ & tera & T \\ $10^{-15}$ & femto & f & $10^{15}$ & peta & P \\ $10^{-18}$ & atto & a & $10^{18}$ & exa & E \\ $10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\ $10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[htbp] \begin{center} \begin{tabular}{|l|l|} \hline \multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\ \hline \multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline sym1 sym2 & multiplication (a space) \\ sym1*sym2 & multiplication (an asterisk) \\ sym1.sym2 & multiplication (a dot) \\ sym1/sym2 & division \\ sym1**y & exponentiation ($y$ must be a numerical constant)\\ sym1\verb+^+y & exponentiation ($y$ must be a numerical constant)\\ log(sym1) & common logarithm \\ ln(sym1) & natural logarithm \\ exp(sym1) & exponential \\ sqrt(sym1) & square root \\ \hline \end{tabular} \end{center} \end{table} \subsubsection{Side-effects of Changing the Unit attribute} If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by setting a new value or by clearing it so that the default value is re-instated) may cause the Label and Symbol attributes to be changed accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'', ``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)'' will cause AST to change its Label and Symbol to ``log(Frequency)'' and ``Log(nu)''. These changes are only made if the Unit attribute is active, and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change to the Label or Symbol attributes. \cleardoublepage \section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)} A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on the celestial sphere is obviously of great importance in astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine the additional properties and behaviour of a SkyFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The SkyFrame Model} A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a SkyFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a SkyFrame represents a 2-dimensional \emph{spherical} coordinate system, in which the shortest distance between two points is a great circle. A SkyFrame therefore always has exactly two axes which represent the longitude and latitude of a coordinate system residing on the celestial sphere. Many such coordinate systems can be represented by a SkyFrame, as we will see shortly. A SkyFrame can represent any of the commonly used celestial coordinate systems. Optionally, the origin of the longitude/latitude system can be moved to any specified point in the standard celestial system, allowing a SkyFrame to represent offsets from a specified sky position. When it is first created, a SkyFrame's axes are always in the order (longitude,~latitude) but this can be changed, if required, by using the \htmlref{astPermAxes}{astPermAxes} function (\secref{ss:permutingaxes}). The order of the axes can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A SkyFrame's coordinate values are always stored as angles in (double precision) radians, regardless of the setting of the Unit attribute \footnote{The units used for the internal floating-point representation of an axis value can be determined by examining the InternalUnit attribute of the Frame. For most Frames, the Unit and InternalUnit attributes will be equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}. \subsection{Creating a SkyFrame} The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a SkyFrame with default attributes is created as follows: \small \begin{terminalv} #include "ast.h" AstSkyFrame *skyframe; ... skyframe = astSkyFrame( "" ); \end{terminalv} \normalsize Such a SkyFrame would represent the default celestial coordinate system which, at present, is the ICRS system (the default was "FK5(J2000)" in versions of AST prior to 3.0). \subsection{Specifying a Particular Celestial Coordinate System} For many purposes, the ICRS coordinate system is perfectly adequate. In order to support conversion between a variety of celestial coordinate systems, however, you can create SkyFrames that represent any of these. Selection of a particular coordinate system is performed simply by setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System} attribute. This setting is most conveniently done when the SkyFrame is created. For example, a SkyFrame representing the old FK4~(B1950.0) coordinate system would be created by: \small \begin{terminalv} skyframe = astSkyFrame( "System=FK4" ); \end{terminalv} \normalsize Note that specifying ``System$=$FK4'' also changes the associated equinox (from J2000.0 to B1950.0). This is because the default value of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions} and include a variety of equatorial coordinate systems, together with ecliptic and galactic coordinates. General spherical coordinates are supported by specifying ``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be created to convert between ``unknown'' coordinates and any of the other celestial coordinate systems (see \secref{ss:introducingconversion} ). \subsection{Attributes which Qualify Celestial Coordinate Systems} Many celestial coordinate systems have some additional free parameters which serve to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, the FK5~(J2010.0) system is distinguished from the FK5~(J2000.0) system by a different equinox---and the coordinates of a fixed astronomical source would have different values when expressed in these two systems. In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main SkyFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\ This attribute is inherited from the Frame class. It gives the moment in time when the coordinates are correct for the astronomical source under study (usually the date of observation). \item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\ This value is used to qualify celestial coordinate systems that are notionally based on the Earth's equator and/or the ecliptic (the plane of the Earth's orbit around the Sun). The position of either of these planes is difficult to specify precisely, so in practice a model \emph{mean} equator and/or ecliptic are used instead. These, together with the point on the sky that defines the coordinate origin (termed the \emph{mean equinox}) move with time according to some model which smoothes out the more rapid fluctuations. The SkyFrame class supports both the old FK4 model and the newer FK5 one. Coordinates expressed in any of these systems vary with time due to movement (by definition) of the coordinate system itself, and must therefore be qualified by a moment in time (the \emph{epoch of the mean equinox}, or ``equinox'' for short) which specifies the position of the model coordinate system on the sky. This is the role of the Equinox attribute. Note that it is quite valid and common to relate the position of a source to an equinox other than the date of observation. Usually a standard equinox such as J2000.0 is used, meaning that the coordinates are referred to axes defined by where the model mean equator and ecliptic would lie on the sky at the Julian epoch J2000.0. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). For the interested reader, an excellent overview of celestial coordinate systems can also be found in the documentation for the SLALIB library (\xref{SUN/67}{sun67}{}). The value of these qualifying attributes is most conveniently set at the same time as the System value, \emph{e.g.}\ when a SkyFrame is created. For instance: \small \begin{terminalv} skyframe = astSkyFrame( "System=Ecliptic, Equinox=J2005.5" ); \end{terminalv} \normalsize would create a SkyFrame representing an ecliptic coordinate system referred to the mean equinox and ecliptic of Julian epoch J2005.5. Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System value. Any such values are stored, but are not used unless the System value is later set so that they become relevant. \subsection{Using Default SkyFrame Attributes} The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this means that there is usually little need to specify many of these attributes explicitly unless you have some special requirement. This can be illustrated by using \htmlref{astShow}{astShow} to examine a SkyFrame, as follows: \small \begin{terminalv} astShow( astSkyFrame( "System=FK4-NO-E, Epoch=1958" ) ); \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0; epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain Epoch = 1958 # Besselian epoch of observation # Lbl1 = "Right ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 System = "FK4-NO-E" # Coordinate system type # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction # Bot2 = -1.5707963267949 # Lowest legal axis value # Top2 = 1.5707963267949 # Highest legal axis value Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} Note that the defaults (indicated by the ``\verb?#?'' comment character at the start of the line) for attributes such as the \htmlref{Title}{Title}, axis Labels and Format specifiers are all set to values appropriate for the particular equatorial coordinate system that the SkyFrame represents. This means, for example, that if we were to use this SkyFrame to format a right ascension value stored in radians using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}), it would automatically result in a string in sexagesimal notation (such as ``12:14:35.7'') suitable for display. If we changed the value of the SkyFrame's Digits attribute (which is inherited from the \htmlref{Frame}{Frame} class), the number of digits appearing would also change accordingly. These choices would be appropriate for a System value of ``FK4-NO-E'', but if a different System value were set, the defaults would be correspondingly different. For example, ecliptic longitude is traditionally expressed in degrees, so setting ``System=ecliptic'' would result in coordinate values being formatted as degrees by default. Of course, if you do not like any of these defaults, you may always over-ride them by setting explicit attribute values yourself. \subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates} SkyFrames use \htmlref{astFormat}{astFormat} for formatting coordinate values in the same way as other Frames (\secref{ss:formattingaxisvalues}). However, they offer a different set of formatting options more appropriate to celestial coordinates. The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the precision with which celestial coordinates are displayed can also be adjusted in this way. However, the range of format specifiers that can be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format resulting from any particular Digits value, is different. The syntax of SkyFrame format specifiers is detailed under the description of the Format(axis) attribute in \appref{ss:attributedescriptions}. Briefly, however, it allows celestial coordinates to be expressed either as angles or times and to include one or more of the fields: \begin{quote} \begin{itemize} \item degrees or hours \item arc-minutes or minutes \item arc-seconds or seconds \end{itemize} \end{quote} with a specified number of decimal places for the final field. A range of field separators is also available, as the following examples show: \begin{quote} \begin{center} \begin{tabular}{|l|l|} \hline \textbf{Format Specifier} & \textbf{Example Formatted Value}\\ \hline \hline {\tt{d}} & {\tt{219}}\\ {\tt{d.3}} & {\tt{219.123}}\\ {\tt{dm}} & {\tt{219:05}}\\ {\tt{dm.2}} & {\tt{219:05.44}}\\ {\tt{dms}} & {\tt{219:05:42}}\\ {\tt{hms.1}} & {\tt{15:44:13.8}}\\ {\tt{bdms.2}} & {\tt{219 05 42.81}}\\ {\tt{lhms.3}} & {\tt{15h44m13.88s}}\\ {\tt{+zlhms}} & {\tt{+06h10m44s}}\\ {\tt{ms.1}} & {\tt{13145:42.8}}\\ {\tt{lmst.3}} & {\tt{876m22.854s}}\\ {\tt{s.2}} & {\tt{788742.81}}\\ \hline \end{tabular} \end{center} \end{quote} Note the following key points: \begin{itemize} \item The required fields are specified using characters chosen from either ``dms'' or ``hms'' according to whether the value is to be formatted as an angle (in degrees) or a time (in hours). \item If no degrees or hours field is required, the distinction between angle and time may be made by including ``t'' to request time. \item The number of decimal places (for the final field) is indicated using ``\texttt{.}'' followed by an integer. An asterisk can be used in place of an integer, in which case the number of decimal places is chosen so that the total number of digits in the formatted value is equal to the value of the Digits attribute. \item ``b'' causes fields to be separated by blanks, while ``l'' causes them to be separated by the appropriate letters (the default being a colon). \item ``z'' causes padding with leading zeros. \item ``+'' cause a plus sign to be prefixed to positive values (negative values always have a minus sign). \end{itemize} The formatting performed by a SkyFrame is also influenced by the \htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each SkyFrame axis. It determines whether the default format specifier for an axis will present values as angles (\emph{e.g.}\ in degrees) if it is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero. The default AsTime value depends on the celestial coordinate system which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System} attribute value. For example, equatorial longitude values (right ascension) are normally expressed in hours, whereas ecliptic longitudes are normally expressed in degrees, so their default AsTime values will reflect this difference. The value of the AsTime attribute may be set explicitly to over-ride these defaults if required, with the formatting precision being determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the Format(axis) attribute may be set explicitly to specify both the format and precision required. Setting an explicit Format value always over-rides the effects of both the Digits and AsTime attributes (unless the Format value does not specify the required number of decimal places, in which case Digits is used to determine the default number of decimal places) \subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates} The process of converting formatted celestial coordinates, such as might be produced by the \htmlref{astFormat}{astFormat} function (\secref{ss:formattingskyaxisvalues}), into numerical (double) coordinate values is performed by using \htmlref{astUnformat}{astUnformat} (\secref{ss:unformattingaxisvalues}) and passing it a pointer to a \htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats accepted is appropriate to positions on the sky expressed as angles and/or times, while the returned value is in radians. The following describes the forms of celestial coordinate which are supported: \begin{itemize} \item You may supply an optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03''). \item Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (\emph{e.g.}\ decimal degrees might be given as ``124.707'', while degrees and decimal arc-minutes might be given as ``$-$13~33.8''). \item The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (\emph{e.g.} ``720~45~31'' is valid, whereas ``11~45~61'' is not). \item Fields may be separated by white space or by ``:'' (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1''). \item The following field identification characters may be used as separators to replace those above (or may be appended to the final field), in order to identify the field to which they are appended: \begin{quote} \begin{tabular}{lll} d & -- & degrees \\ h & -- & hours \\ m & -- & minutes (of arc or time) \\ s & -- & seconds (of arc or time) \\ \texttt{'} & -- & arc-minutes \\ \texttt{"} & -- & arc-seconds \end{tabular} \end{quote} Either lower or upper case may be used. Fields must be given in order of decreasing significance (\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s''). \item The presence of certain field identification characters indicates whether the value is to be interpreted as an angle or a time (with 24 hours corresponding to 360 degrees), as follows: \begin{quote} \begin{tabular}{lll} d & -- & angle \\ \texttt{'} & -- & angle \\ \texttt{"} & -- & angle \\ h & -- & time \end{tabular} \end{quote} Incompatible angle/time identification characters may not be mixed (\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either. \item If no preference for an angle or a time is expressed anywhere within the value, then it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat (\secref{ss:formattingskyaxisvalues}) are correctly interpreted by astUnformat. \item Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters. For example: \begin{quote} \begin{tabular}{lll} 10d & -- & degrees \\ 10d12 & -- & degrees and arc-minutes \\ 11:14\texttt{"} & -- & arc-minutes and arc-seconds \\ 9h13s & -- & hours and seconds of time \\ :45:33 & -- & minutes and seconds (of arc or time) \\ :55: & -- & minutes (of arc or time) \\ ::13 & -- & seconds (of arc or time) \\ $-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\ 07m14 & -- & minutes and seconds (of arc or time) \\ $-$8:14\texttt{'} & -- & degrees and arc-minutes \\ $-$h3:14 & -- & minutes and seconds of time \\ h:2.1 & -- & seconds of time \end{tabular} \end{quote} \item If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. ``01:02''), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce. \end{itemize} This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters. However, it also affects other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set to ``mst.1'' (producing two fields representing minutes and seconds of time), then formatted input would be interpreted by astUnformat as follows: \begin{quote} \begin{tabular}{lll} 12 13 & -- & minutes and seconds \\ 12 & -- & minutes \\ :13 & -- & seconds \\ $-$18: & -- & minutes \\ 12.8 & -- & minutes \\ 1 2 3 & -- & hours, minutes and seconds \\ & & \\ 4\texttt{'} & -- & arc-minutes \\ 60::\texttt{"} & -- & degrees \\ $-$23:\texttt{"} & -- & arc-minutes \\ $-$33h & -- & hours \end{tabular} \end{quote} (in the last four cases, explicit field identification has been given which overrides the implicit identification). Alternatively, if the Format(axis) string were set to ``s.3'' (producing only an arc-seconds field), then formatted input would be interpreted by astUnformat as follows: \begin{quote} \begin{tabular}{lll} 12.8 & -- & arc-seconds \\ 12 13 & -- & arc-minutes and arc-seconds \\ :12 & -- & arc-seconds \\ 13: & -- & arc-minutes \\ 1 2 3 & -- & degrees, arc-minutes and arc-seconds \end{tabular} \end{quote} In general, if you are preparing formatted input data containing celestial coordinates and wish to omit certain fields, then you are advised to identify clearly those that you do provide by using the appropriate field identification characters and/or extra colon separators. This prevents you depending on the implicit field identification described above which, in turn, depends on an appropriate Format(axis) string having been set. When writing software, it is also a good idea to set the Format(axis) string so that data input will be as simple as possible for the user. Unless some special effect is desired, this normally means that it should contain ``d'' or ``h'' to ensure that the first field entered by the user will be interpreted as degrees or hours, unless otherwise identified. This is the normal behaviour unless an explicit Format(axis) value has been set to override the default. \subsection{Representing Offsets from a Specified Sky Position} A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are referred to an origin at any specified sky position. Such a coordinate system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System} attribute should be set to represent the celestial coordinate system in which the origin is to be specified. Then the SkyRef attribute should be set to hold the coordinates of the origin within the selected celestial coordinate system. By default, ``north'' in the new offset coordinate system is parallel to north in the original celestial coordinate system. However, the direction of north in the offset system can be controlled by assigning a value to the SkyRefP attribute. This attribute should be assigned the celestial coordinates of a point which is on the zero longitude meridian and which has non-zero latitude. By default, the position given by the SkyRef attribute is used as the origin of the new longitude/latitude system, but an option exists to use it as the north pole of the system instead. This option is controlled by the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what sort of offset coordinate system you want. Setting SkyRefIs to ``Origin'' (the default) produces an offset coordinate system which is approximately Cartesian close to the specified position. Setting SkyRefIs to ``Pole'' produces an offset coordinate system which is approximately Polar close to the specified position. \cleardoublepage \section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)} The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate systems which describe a position within an electro-magnetic spectrum. In this section we examine the additional properties and behaviour of a SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The SpecFrame Model} As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a SpecFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a SpecFrame represents a wide range of different 1-dimensional coordinate system which can be used to describe positions within a spectrum. The options available largely mirror those described in the FITS-WCS paper III \emph{Representations of spectral coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen). \subsection{Creating a SpecFrame} The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a SpecFrame with default attributes is created as follows: \small \begin{terminalv} #include "ast.h" AstSpecFrame *specframe; ... specframe = astSpecFrame( "" ); \end{terminalv} \normalsize Such a SpecFrame would represent the default coordinate system which is heliocentric wavelength in metres (i.e. wavelength corrected to take into account the Doppler shift caused by the velocity of the observer around the sun). \subsection{Specifying a Particular Spectral Coordinate System} Selection of a particular coordinate system is performed simply by setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System} attribute. This setting is most conveniently done when the SpecFrame is created. For example, a SpecFrame representing Energy would be created by: \small \begin{terminalv} specframe = astSpecFrame( "System=Energy" ); \end{terminalv} \normalsize Note that specifying ``System$=$Energy'' also changes the associated Unit (from metres to Joules). This is because the default value of the SpecFrame's Unit attribute depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions} and include a variety of velocity systems, together with frequency, wavelength, energy, wave-number, \emph{etc}. \subsection{Attributes which Qualify Spectral Coordinate Systems} Many spectral coordinate systems have some additional free parameters which serve to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, the velocity systems are all parameterised by a rest frequency---the frequency which defines zero velocity, and all coordinate systems are qualified by a `standard of rest'' which indicates the rest frame to which the values refer. In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main SpecFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\htmlref{Epoch}{Epoch}]\mbox{}\\ This attribute is inherited from the Frame class. It gives the moment in time when the coordinates are correct for the astronomical source under study (usually the date of observation). It is needed in order to calculate the Doppler shift produced by the velocity of the observer relative to the centre of the earth, and of the earth relative to the sun. \item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\ This specifies the rest frame in which the coordinates are correct. Transforming between different standards of rest involves taking account of the Doppler shift introduced by the relative motion of the two standards of rest. \item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\ Specifies the frequency which correspond to zero velocity. When setting a value for this attribute, the value may be supplied as a wavelength (including an indication of the units being used, ``nm'' ``Angstrom'', \emph{etc.}), which will be automatically be converted to a frequency. \item[\htmlref{RefRA}{RefRA}]\mbox{}\\ Specifies the RA (FK5 J2000) of the source. This is used when converting between standards of rest. It specifies the direction along which the component of the relative velocity of the two standards of rest is taken. \item[\htmlref{RefDec}{RefDec}]\mbox{}\\ Specifies the Dec (FK5 J2000) of the source. Used in conjunction with REFRA. \item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\ This defines the ``source'' standard of rest. This is a rest frame which is moving towards the position given by RefRA and RefDec, at a velocity given by SourceVel. The velocity is stored internally as a heliocentric velocity, but can be given in any of the other supported standards of rest. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System value. Any such values are stored, but are not used unless the System value is later set so that they become relevant. \subsection{Using Default SpecFrame Attributes} The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this means that there is usually little need to specify many of these attributes explicitly unless you have some special requirement. This can be illustrated by using \htmlref{astShow}{astShow} to examine a SpecFrame, as follows: \small \begin{terminalv} astShow( astSpecFrame( "System=Vopt, RestFreq=250 GHz" ) ); \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} Begin SpecFrame # Description of spectral coordinate system # Title = "Optical velocity, rest frequency = 250 GHz" # Title of coordinate system Naxes = 1 # Number of coordinate axes # Domain = "SPECTRUM" # Coordinate system domain # Epoch = 2000 # Julian epoch of observation # Lbl1 = "Optical velocity" # Label for axis 1 System = "VOPT" # Coordinate system type # Uni1 = "km/s" # Units for axis 1 Ax1 = # Axis number 1 Begin Axis # Coordinate axis End Axis IsA Frame # Coordinate system description # SoR = "Heliocentric" # Standard of rest RstFrq = 250000000000 # Rest frequency (Hz) End SpecFrame \end{terminalv} Note that the defaults (indicated by the ``\verb?#?'' comment character at the start of the line) for attributes such as the \htmlref{Title}{Title}, axis Labels and Unit specifiers are all set to values appropriate for the particular velocity system that the SpecFrame represents. These choices would be appropriate for a System value of ``Vopt'', but if a different System value were set, the defaults would be correspondingly different. For example, by default frequency is measured in units of GHz, not $km/s$, so setting ``System=freq'' would change the appropriate line above from: \begin{terminalv} # Uni1 = "km/s" # Units for axis 1 \end{terminalv} to \begin{terminalv} # Uni1 = "GHz" # Units for axis 1 \end{terminalv} Of course, if you do not like any of these defaults, you may always over-ride them by setting explicit attribute values yourself. For instance, you may choose to have your frequency axis expressed in ``kHz'' rather than ``GHz''. To do this simply set the attribute value as follows: \small \begin{terminalv} astSetC( specframe, "Unit", "kHz" ); \end{terminalv} \normalsize No error will be reported if you accidentally set an inappropriate Unit value (say "J" - Joules)---after all, AST cannot tell what you are about to do, and you \emph{may} be about to change the System value to ``Energy''. However, an error \emph{will} be reported if you attempt to find a conversion between two SpecFrames (for instance using \htmlref{astConvert}{astConvert} ) if either SpecFrame has a Unit value which is inappropriate for its System value. SpecFrame attributes, like all other attributes, all have default value. However, be aware that for some attributes these default values can never be more than ``a legal numerical value'' and have no astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes (which give the source position) both have a default value of zero. So unless your source happens to be at that point (highly unlikely!) you will need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute has an arbitrary default value of 1.0E5 GHz. Some operations are not affected by inappropriate values for these attributes (for instance, converting from frequency to wavelength, changing axis units, \emph{etc}), but some are. For instance, converting from frequency to velocity requires a correct rest frequency, moving between different standards of rest requires a correct source position. The moral is, always set explicit values for as many attributes as possible. \subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes} You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube containing two spatial axes and a spectral axis. To do this you would create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame} (often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}. \small \begin{terminalv} AstSkyFrame *skyframe; AstSpecFrame *specframe; AstCmpFrame *cmpframe; ... skyframe = astSkyFrame( "Epoch=J2002" ); specframe = astSpecFrame( "System=Freq,StdOfRest=LSRK" ); cmpframe = astCmpFrame( skyframe, specframe, "" ); \end{terminalv} \normalsize In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis 3 will be Frequency. If this is not the order you want, you can permute the axes using \htmlref{astPermAxes}{astPermAxes}. There is one potential problem with this approach if you are interested in unusually high accuracy. Conversion between different standards of rest involves taking account of the Doppler shift caused by the relative motion of the two standards of rest. At some point this involves finding the component of the relative velocity in the direction of interest. For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, even if the SpecFrame is embedded within a CmpFrame as above. It would be more appropriate if this ``direction of interest'' was specified by the values passed into the CmpFrame on the RA and DEC axes, allowing each pixel within a data cube to have a slightly different correction for Doppler shift. Unfortunately, the SpecFrame class cannot do this (since it is purely a 1-dimensional Frame), and so some small degree of error will be introduced when converting between standards of rest, the size of the error varying from pixel to pixel. It is hoped that at some point in the future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which allows for this spatial variation in Doppler shift. The maximum velocity error introduced by this problem is of the order of $V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of $V$ is about 20 $km/s$, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 $km/s$. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 $km/s$ over a 1 degree field of view. \subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra} Dual sideband super-heterodyne receivers produce spectra in which each channel contains contributions from two different frequencies, referred to as the ``upper sideband frequency'' and the ``lower sideband frequency''. In the rest frame of the observer (topocentric), these are related to each other as follows: \begin{quote} \begin{small} \begin{equation} \label{eqn:dsb} f_{lsb} = 2.f_{LO} - f_{usb} \end{equation} \end{small} \end{quote} where $f_{LO}$ is a fixed frequency known as the ``local oscillator frequency''. In other words, the local oscillator frequency is always mid-way between any pair of corresponding upper and lower sideband frequencies\footnote{Note, this simple relationship only applies if all frequencies are topocentric.}. If you want to describe the spectral axis of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot describe both sidebands simultaneously. However, there is a sub-class of SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty. A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the DSBSpecFrame is currently being used to describe the upper or lower sideband spectral axis. The value of this attribute can be changed at any time. If you use the \htmlref{astConvert}{astConvert} function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for the two SideBand attributes will be taken into account. Thus, if you take a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use astConvert to find a Mapping from the original to the modified copy, the resulting Mapping will be of the form of equation \ref{eqn:dsb} (if the DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric''). In general, when finding a Mapping between two arbitrary DSBSpecFrames, the total Mapping is made of of three parts in series: \begin{enumerate} \item A Mapping which converts the first DSBSpecFrame into its upper sideband representation. If the DSBSpecFrame already represents its upper sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}. \item A Mapping which converts from the first to the second DSBSpecFrame, treating them as if they were both basic SpecFrames. This takes account of any difference in units, standard of rest, system, \emph{etc} between the two DSBSpecFrames. \item A Mapping which converts the second DSBSpecFrame from its upper sideband representation to its current sideband. If the DSBSpecFrame currently represents its upper sideband, this Mapping will be a UnitMap. \end{enumerate} If an attempt is made to find the Mapping between a DSBSpecFrame and a basic SpecFrame, then the DSBSpecFrame will be treated like a basic SpecFrame. In other words, the returned Mapping will not be affected by the setting of the SideBand attribute (or any of the other attributes specific to the DSBSpecFrame class). In practice, the local oscillator frequency for a dual sideband instrument may not be easily available to an observer. Instead, it is common practice to specify the spectral position of some central feature in the observation (commonly the centre of the instrument passband), together with an ``intermediate frequency''. Together, these two values allow the local oscillator frequency to be determined. The intermediate frequency is the difference between the topocentric frequency at the central spectral position and the topocentric frequency of the local oscillator. So: \begin{quote} \begin{small} \begin{equation} \label{eqn:dsb2} f_{LO} = f_{central} + f_{if} \end{equation} \end{small} \end{quote} The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the intermediate frequency ($f_{if}$). The DSBCentre value is given and returned in the spectral system described by the DSBSpecFrame (thus you do not need to calculate the corresponding topocentric frequency yourself - this will be done automatically by the DSBSpecFrame when you assign a new value to the DSBCentre attribute). The value assigned to the IF attribute should always be a topocentric frequency in units of Hz, however a negative value may be given to indicate that the DSBCentre value is in the upper sideband (that is, if $IF < 0$ then $f_{central} > f_{LO}$). A positive value for IF indicates that the DSBCentre value is in the lower sideband (that is, if $IF > 0$ then $f_{central} < f_{LO}$). \cleardoublepage \section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)} The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in time. In this section we examine the additional properties and behaviour of a TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}). \subsection{The TimeFrame Model} As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and behaviour of these two ancestral classes. When used as a Mapping, a TimeFrame implements a unit transformation, exactly like a basic Frame (\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its behaviour is not of great importance. When used as a Frame, however, a TimeFrame represents a wide range of different 1-dimensional coordinate system which can be used to describe moments in time. Absolute times and relative (i.e. elapsed) times are supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales (attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch}, \emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to allow them to be used with any unit of time (attribute Unit). The TimeFrame class also allows times to formatted as either a simple floating point value or as a Gregorian date and time of day (attribute Format). \subsection{Creating a TimeFrame} The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a TimeFrame with default attributes is created as follows: \small \begin{terminalv} #include "ast.h" AstTimeFrame *timeframe; ... timeframe = astTimeFrame( "" ); \end{terminalv} \normalsize Such a TimeFrame would represent the default coordinate system which is Modified Julian Date (with the usual units of days) in the International Atomic Time (TAI) time scale. \subsection{Specifying a Particular Time System} By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}). Selection of a particular coordinate system is performed simply by setting a value for the TimeFrame's (character string) System attribute. This setting is most conveniently done when the TimeFrame is created. For example, a TimeFrame representing Julian Epoch would be created by: \small \begin{terminalv} timeframe = astTimeFrame( "System=JEPOCH" ); \end{terminalv} \normalsize Note that specifying ``System$=$JEPOCH'' also changes the associated default Unit (from days to years). This is because the default value of the TimeFrame's Unit attribute depends on the System attribute setting. You may change the System value at any time, although this is not usually needed. The values supported are set out in the attribute's description in \appref{ss:attributedescriptions}. \subsection{Attributes which Qualify Time Coordinate Systems} Time coordinate systems require some additional free parameters to identify a particular coordinate system from amongst a broader class of related coordinate systems. For example, all TimeFrames are qualified by the time scale (that is, the physical process used to define the flow of time), and some require the position of the observer's clock. In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame} attributes, each of which has a default appropriate to (\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying attributes} may, however, be assigned an explicit value so as to select a particular coordinate system. Note, it is usually best to assign explicit values whenever possible rather than relying on defaults. Attribute should only be left at their default value if you ``don't care'' what value is used. In certain circumstances (particularly, when aligning two Frames), a default value for an attribute may be replaced by the value from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by assigning an explicit value to the attribute, rather than simply relying on the default. The main TimeFrame attributes which qualify the System attribute are: \begin{quote} \begin{description} \item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\ This specifies the time scale. \item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\ This specifies the offset from Local Time to UTC in hours (time zones east of Greenwich have positive values). Note, AST uses the value as supplied without making any correction for daylight saving. \item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\ This specifies the zero point from which time values are measured, within the system specified by the System attribute. Thus, a value of zero (the default) indicates that time values represent absolute times. Non-zero values may be used to indicate that the TimeFrame represents elapsed time since the specified origin. \end{description} \end{quote} For further details of these attributes you should consult their descriptions in \appref{ss:attributedescriptions} and for details of the System settings for which they are relevant, see the description of the System attribute (also in \appref{ss:attributedescriptions}). Note that it does no harm to assign values to qualifying attributes which are not relevant to the main System or TimeScale value. Any such values are stored, but are not used unless the System and/or TimeScale value is later set so that they become relevant. \cleardoublepage \section{\label{ss:cmpframes}Compound Frames (CmpFrames)} We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The Frames we have considered so far have been atomic, in the sense that they represent pre-defined elementary physical domains. A CmpFrame, however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for containing other Frames and its purpose is to allow those Frames to work together in various combinations while appearing as a single \htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is determined by the other Frames it contains (its ``component'' Frames). As with compound Mappings, compound Frames can be nested within each other, forming arbitrarily complex Frames. \subsection{Creating a CmpFrame} A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a ``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes represents position within a spectrum, and the other two axes represent position on the sky (or some other spatial domain such as the focal plane of a telescope). As an example, we create such a CmpFrame in which axes 1 and 2 represent Right Ascension and Declination (ICRS), and axis 3 represents wavelength (these are the default coordinate Systems represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively): \small \begin{terminalv} AstSkyFrame *skyframe; AstSpecFrame *specframe; AstCmpFrame *cmpframe; ... skyframe = astSkyFrame( "" ); specframe = astSpecFrame( "" ); cmpframe = astCmpFrame( skyframe, specframe, "" ); \end{terminalv} \normalsize If it was desired to make RA and Dec correspond to axes 1 and 3, with axis 2 being the spectral axis, then the axes of the CmpFrame created above would need to be permuted as follows: \small \begin{terminalv} int perm[ 3 ]; ... perm[ 0 ] = 0; perm[ 1 ] = 2; perm[ 2 ] = 1; astPermAxes( cmpframe, perm ); \end{terminalv} \normalsize \subsection{The Attributes of a CmpFrame} A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame. The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by concatenating the Domains of the two component Frames, separated by a minus sign (``-'').\footnote{If both component Frames have blank Domains, then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed) value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to change the System value of a CmpFrame is ignored.} A CmpFrame has no further attributes over and above those common to all Frames. However, attributes of the two component Frames can be accessed as if they were attributes of the CmpFrame, as described below. Frame attributes which are specific to individual axes (such as Label(2), Format(1), \emph{etc}) simply mirror the corresponding axes of the relevant component Frame. That is, if the ``Label(2)'' attribute of a CmpFrame is accessed, the CmpFrame will forward the access request to the component Frame which contains axis 2. Thus, default values for axis attributes will be the same as those provided by the component Frames. An axis index can optionally be appended to the name of Frames attributes which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title}, \emph{etc}). If this is done, the access request is forwarded to the component Frame containing the indicated axis. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes have not been permuted, then getting the value of attribute ``System'' will return ``Compound'' as mentioned above (that is, the System value of the CmpFrame as a whole), whereas getting the value of attribute ``System(1)'' will return ``Spectral''(that is, the System value of the component Frame containing axis 1 --- the SpecFrame). This technique is not limited to attributes common to all Frames. For instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is not held by other classes of Frames. To set a value for the Equinox attribute of the SkyFrame contained within the above CmpFrame, assign the value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame defines both axes 2 and 3 of the CmpFrame, we could equivalently have set a value for ``Equinox(3)'' since this would also result in the attribute access being forwarded to the SkyFrame. Finally, if an attribute is not qualified by a axis index, attempts will be made to access it using each of the CmpFrame axes in turn. Using the above example of the spectral cube, if an attempt was made to get the value of attribute ``Equinox'' (with no axis index), each axis in turn would be used. Since axis 1 is contained within a SpecFrame, the first attempt would fail since the SpecFrame class does not have an Equinox attribute. However, the second attempt would succeed because axis 2 is contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus the returned attribute value would be that obtained from the SkyFrame containing axis 2. When getting or testing an attribute value, the returned value is determined by the \emph{first} axis which recognises the attribute. When setting an attribute value, \emph{all} axes which recognises the attribute have the attribute value set to the given value. Likewise, when clearing an attribute value, all axes which recognises the attribute have the attribute value cleared. \cleardoublepage \section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions} In this section, we start to look at techniques for converting between different coordinate systems. At this stage, the tools we have available are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}), SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and various Mappings (\secref{ss:mappings}). These are sufficient to allow us to begin examining the problem, but more sophisticated approaches will also emerge later (\secref{ss:framesetconverting}). \subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems} We begin by examining how to convert between two celestial coordinate systems represented by SkyFrames, as this is both an illuminating and practical example. Consider the problem of converting celestial coordinates between: \begin{enumerate} \item The old FK4 system, with no E terms, a Besselian epoch of 1958.0 and a Besselian equinox of 1960.0. \item An ecliptic coordinate system based on the mean equinox and ecliptic of Julian epoch 2010.5. \end{enumerate} This example is arbitrary but not completely unrealistic. Unless you already have expertise with such conversions, you are unlikely to find it straightforward. Using AST, we begin by creating two SkyFrames to represent these coordinate systems, as follows: \small \begin{terminalv} #include "ast.h" AstSkyFrame *skyframe1, *skyframe2; ... skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); \end{terminalv} \normalsize Note how specifying the coordinate systems consists simply of initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately. The next step is to find a way of converting between these SkyFrames. This is done using \htmlref{astConvert}{astConvert}, as follows: \small \begin{terminalv} AstFrameSet *cvt; ... cvt = astConvert( skyframe1, skyframe2, "" ); if ( cvt == AST__NULL ) { } else { } \end{terminalv} \normalsize The third argument of astConvert is not used here and should be an empty string. astConvert will return a null result, AST\_\_NULL (as defined in the ``ast.h'' header file), if conversion is not possible. In this example, conversion is possible, so it will return a pointer to a new \htmlref{Object}{Object} that describes the conversion. The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed FrameSets yet (\secref{ss:framesets}), but for the present purposes we can consider them simply as Objects that can behave both as Mappings and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we are mainly interested here, because the Mapping it implements is the one we require---\emph{i.e.}\ it converts between the two celestial coordinate systems (\secref{ss:framesetsfromconvert}). For example, if ``alpha1'' and ``delta1'' are two arrays containing the longitude and latitude, in radians, of N points on the sky in the original coordinate system (corresponding to ``skyframe1''), then they could be converted into the new coordinate system (represented by ``skyframe2'') as follows: \small \begin{terminalv} #define N 10 double alpha1[ N ], delta1[ N ]; double alpha2[ N ], delta2[ N ]; ... astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); \end{terminalv} \normalsize The new coordinates are returned \emph{via} the ``alpha2'' and ``delta2'' arrays. To transform coordinates in the opposite direction, we simply invert the 5th (boolean int) argument to \htmlref{astTran2}{astTran2}, as follows: \small \begin{terminalv} astTran2( cvt, N, alpha2, delta2, 0, alpha1, delta1 ); \end{terminalv} \normalsize The FrameSet returned by astConvert also contains information about the SkyFrames used in the conversion (\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the ``destination'' Frame used in the conversion (\emph{i.e.}\ like ``skyframe2''). We could therefore use the ``cvt'' FrameSet to calculate the distance between two points (with coordinates in radians) in the destination coordinate system, using \htmlref{astDistance}{astDistance}: \small \begin{terminalv} double distance, point1[ 2 ], point2[ 2 ]; ... distance = astDistance( cvt, point1, point2 ); \end{terminalv} \normalsize and the result would be the same as if the ``skyframe2'' SkyFrame had been used. Another way to see how the FrameSet produced by astConvert retains information about the coordinate systems involved is to set its \htmlref{Report}{Report} attribute (inherited from the Mapping class) so that it displays the coordinates before and after conversion (\secref{ss:transforming}): \small \begin{terminalv} astSet( cvt, "Report=1" ); astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); \end{terminalv} \normalsize The output from this might look like the following: \begin{terminalv} (2:06:03.0, 34:22:39) --> (42.1087, 20.2717) (2:08:20.6, 35:31:24) --> (43.0197, 21.1705) (2:10:38.1, 36:40:09) --> (43.9295, 22.0716) (2:12:55.6, 37:48:55) --> (44.8382, 22.9753) (2:15:13.1, 38:57:40) --> (45.7459, 23.8814) (2:17:30.6, 40:06:25) --> (46.6528, 24.7901) (2:19:48.1, 41:15:11) --> (47.5589, 25.7013) (2:22:05.6, 42:23:56) --> (48.4644, 26.6149) (2:24:23.1, 43:32:41) --> (49.3695, 27.5311) (2:26:40.6, 44:41:27) --> (50.2742, 28.4499) \end{terminalv} Here, we see that the input FK4 equatorial coordinate values (given in radians) have been formatted automatically in sexagesimal notation using the conventional hours for right ascension and degrees for declination. Conversely, the output ecliptic coordinates are shown in decimal degrees, as is conventional for ecliptic coordinates. Both are displayed using the default precision of 7 digits.\footnote{The leading digit is zero and is therefore not seen in this particular example.} In fact, the ``cvt'' FrameSet has access to all the information in the original SkyFrames which were passed to astConvert. If you had set a new Digits attribute value for either of these, the formatting above would reflect the different precision you requested by displaying a greater or smaller number of digits. \subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems} The principles described in the previous section for converting between celestial coordinate systems also apply to the task of converting between spectral coordinate systems. As an example, let's look at how we might convert between frequency measured in $GHz$ as measured in the rest frame of the telescope, and radio velocity measured in $km/s$ measured with respect the kinematic Local Standard of Rest. First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to describe the required radio velocity system (this is slightly more convenient, given the relatively large number of attributes, than specifying the attribute values in a single string such as would be passed to the SpecFrame constructor). We then take a copy of this SpecFrame, and change the attribute values so that the copy describes the original frequency system (modifying a copy, rather than creating a new SpecFrame from scratch, avoids the need to specify the epoch, reference position, \emph{etc} a second time since they are all inherited by the copy): \small \begin{terminalv} #include "ast.h" AstSpecFrame *specframe1, *specframe2; ... specframe1 = astSpecFrame( "" ); astSet( specframe1, "System=vradio" ); astSet( specframe1, "Unit=km/s" ); astSet( specframe1, "Epoch=1996-Oct-2 12:13:56.985" ); astSet( specframe1, "ObsLon=W155:28:18" ); astSet( specframe1, "ObsLat=N19:49:34" ); astSet( specframe1, "RefRA=18:14:50.6" ); astSet( specframe1, "RefDec=-4:40:49" ); astSet( specframe1, "RestFreq=230.538 GHz" ); astSet( specframe1, "StdOfRest=LSRK" ); specframe2 = astCopy( specframe1 ); astSet( specframe1, "System=freq" ); astSet( specframe1, "Unit=GHz" ); astSet( specframe1, "StdOfRest=Topocentric" ); \end{terminalv} \normalsize Note, the fact that a SpecFrame has only a single axis means that we were able to refer to the Unit attribute without an axis index. The other attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the standard of rest (\htmlref{StdOfRest}{StdOfRest}). The next step is to find a way of converting between these SpecFrames. We use exactly the same code that we did in the previous section where we were converting between celestial coordinate systems: \small \begin{terminalv} AstFrameSet *cvt; ... cvt = astConvert( specframe1, specframe2, "" ); if ( cvt == AST__NULL ) { } else { } \end{terminalv} \normalsize A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible, which should always be the case for our example), and we can use the FrameSet to convert between the two spectral coordinate systems. We use \htmlref{astTran1}{astTran1} in place of \htmlref{astTran2}{astTran2} since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two). For example, if ``frq'' is an array containing the observed frequency, in GHz, of N spectral channels (describe by ``specframe1''), then they could be converted into the new coordinate system (represented by ``specframe2'') as follows: \small \begin{terminalv} #define N 10 double frq[ N ]; double vel[ N ]; ... astTran1( cvt, N, frq, 1, vel ); \end{terminalv} \normalsize The radio velocity values are returned in the ``vel'' array. \subsection{Converting between Time Coordinate Systems} All the principles outlined in the previous section about aligning spectral cocordinate systems (SpecFrames) can be applied directly to the problem of aligning time coordinate systems (TimeFrames). \subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations} We can illustrate an important point if we swap the axis order of either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes}) before identifying the conversion. Let's assume we use \htmlref{astPermAxes}{astPermAxes} (\secref{ss:permutingaxes}) to do this to the second SkyFrame, before applying \htmlref{astConvert}{astConvert}, as follows: \small \begin{terminalv} int perm[ 2 ] = { 2, 1 }; ... astPermAxes( skyframe2, perm ); cvt = astConvert( skyframe1, skyframe2, "" ); \end{terminalv} \normalsize Now, the destination SkyFrame system no longer represents the coordinate system: \begin{quote} (ecliptic~longitude, ecliptic~latitude) \end{quote} but instead represents the transposed system: \begin{quote} (ecliptic~latitude, ecliptic~longitude) \end{quote} As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by astConvert to apply a coordinate transformation, we obtain something like the following: \begin{terminalv} (2:06:03.0, 34:22:39) --> (20.2717, 42.1087) (2:08:20.6, 35:31:24) --> (21.1705, 43.0197) (2:10:38.1, 36:40:09) --> (22.0716, 43.9295) (2:12:55.6, 37:48:55) --> (22.9753, 44.8382) (2:15:13.1, 38:57:40) --> (23.8814, 45.7459) (2:17:30.6, 40:06:25) --> (24.7901, 46.6528) (2:19:48.1, 41:15:11) --> (25.7013, 47.5589) (2:22:05.6, 42:23:56) --> (26.6149, 48.4644) (2:24:23.1, 43:32:41) --> (27.5311, 49.3695) (2:26:40.6, 44:41:27) --> (28.4499, 50.2742) \end{terminalv} When compared to the original (\secref{ss:convertingskyframes}), the output coordinate order has been swapped to compensate for the different destination SkyFrame axis order. In all, there are four possible axis combinations, corresponding to two possible axis orders for each of the source and destination SkyFrames, and astConvert will convert correctly between any of these. The point to note is that a SkyFrame contains knowledge about how to convert to and from other SkyFrames. Since its two axes (longitude and latitude) are distinguishable, the conversion is able to take account of the axis order. If you need to identify the axes of a SkyFrame explicitly, taking into account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be used. These are read-only attributes which give the indices of the latitude and longitude axes respectively. \subsection{\label{ss:convertingframes}Converting Between Frames} Having seen how clever SkyFrames are (\secref{ss:convertingskyframes} and \secref{ss:convertingpermutedaxes}), we will next examine how dumb a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two 2-dimensional Frames and use \htmlref{astConvert}{astConvert} to derive a conversion between them, as follows: \small \begin{terminalv} AstFrame *frame1, *frame2; ... frame1 = astFrame( 2, "" ); frame2 = astFrame( 2, "" ); cvt = astConvert( frame1, frame2, "" ); \end{terminalv} \normalsize then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs will be as follows: \begin{terminalv} (1, 2) --> (1, 2) (2, 4) --> (2, 4) (3, 6) --> (3, 6) (4, 8) --> (4, 8) (5, 10) --> (5, 10) \end{terminalv} This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap} (\secref{ss:unitmapexample}). Even if we permute the axis order of our Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will fare no better. The conversion between our two basic Frames will always be an identity transformation. The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start life the same and have axes that are indistinguishable. Therefore, permuting their axes doesn't make them look any different---they still represent the same coordinate system. %Actually, this behaviour isn't as dumb as it seems and can actually be %very useful, as the following example illustrates. % %\subsection{Distinguishable and Indistinguishable Axes} % %c+ %Imagine you have two Frames which represent the pixel coordinates of %two 2-dimensional images. Let's call their axes ``X'' and ``Y''. %Suppose you now transpose the second image and swap its Frame axes %(with \htmlref{astPermAxes}{astPermAxes}) to take account of this. %c- %f+ %Imagine you have two Frames which represent the pixel coordinates of %two 2-dimensional images. Let's call their axes ``X'' and ``Y''. %Suppose you now transpose the second image and swap its Frame axes %(with astPermAxes) to take account of this. %f- % %Next, consider what happens if you want to subtract one image from the %other. If you have a ``subtract'' program that is intelligent and %tries to align the two images for you, one of two things could happen: % %\begin{enumerate} %c+ %\item If the axes are distinguishable, when your program invokes %astConvert it will derive a transformation between the two images %which swaps the X and Y coordinates (corresponding to the transposition %you applied to the second image). However, in aligning X-with-X and %Y-with-Y, this will completely undo the effects of your transposition! %c- %f+ %\item If the axes are distinguishable, when your program invokes %AST\_CONVERT it will derive a transformation between the two images %which swaps the X and Y coordinates (corresponding to the transposition %you applied to the second image). However, in aligning X-with-X and %Y-with-Y, this will completely undo the effects of your transposition! %f- % %\item If the axes are indistinguishable, the transformation between %the two images will always be an identity %(\secref{ss:convertingframes}). Therefore, your program will align %X-with-Y and Y-with-X, so that you see the effects of your earlier %transposition of the second image. %\end{enumerate} % %Clearly, if we are considering pixel coordinates, the latter behaviour %is preferable, since there would be no point in implementing an image %transposition program if we could never see the effects of it. This %indicates that a basic Frame, with is indistinguishable axes, is the %correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where %this behaviour is necessary. % %Conversely, the former behaviour would be more useful if the axes we %were considering were, say, wavelength (in nm) and slit position (in %mm). In this case, we would expect our ``subtract'' program to %subtract data at corresponding wavelengths and slit positions, not %just at corresponding pixels. This case requires distinguishable axes, %so that corresponding axes in the two images can be matched up, just %as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}). % %Of course, there may also be intermediate cases, where some axes are %distinguishable and others aren't. \subsection{\label{ss:alignmentsystem}The Choice of Alignment System} In practice, when AST is asked to find a conversion between two Frames describing two different coordinate systems on a given physical domain, it uses an intermediate ``alignment'' system. Thus, when finding a conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from system A to some alignment system, system C, and then finds the Mapping from this system C to the required system B. It finally concatenates these two Mappings to get the Mapping from system A to system B. One advantage of this is that it cuts down the number of conversion algorithms required. If there are $N$ different Systems which may be used to describe positions within the \htmlref{Domain}{Domain}, then this approach requires about $2*N$ conversion algorithms to be written. The alternative approach of going directly from system A to system B would require about $N*N$ conversion algorithms. In addition, the use of an intermediate alignment system highlights the nature of the conversion process. What do we mean by saying that a Mapping ``converts a position in one coordinate system into the corresponding position in another''? In practice, it means that the input and output coordinates correspond to the same coordinates \emph{in some third coordinate system}. The choice of this third coordinate system, the ``alignment'' system, can completely alter the nature of the Mapping. The \htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to specify the alignment system. As an example, consider the case of aligning two spectra calibrated in radio velocity, but each with a different rest frequency (each spectrum will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a given velocity will correspond to different frequencies in the two spectra. So when we come to ``align'' these two spectra (that is, find a Mapping which converts positions in one SpecFrame to the corresponding positions in the other), we have the choice of aligning the frequencies or aligning the velocities. Different Mappings will be required to describe these two forms of alignment. If we set AlignSystem to ``Freq'' then the returned Mapping will align the frequencies described by the two SpecFrames. On the other hand, if we set AlignSystem to ``Vradio'' then the returned Mapping will align the velocities. Some choices of alignment system are redundant. For instance, in the above example, changing the alignment system from frequency to wavelength has no effect on the returned Mapping: if two spectra are aligned in frequency they will also be aligned in wavelength (assuming the speed of light doesn't change). The default value for AlignSystem depends on the class of Frame. For a SpecFrame, the default is wavelength (or equivalently, frequency) since this is the system in which observations are usually made. The SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which allows the standard of rest of the alignment system to be specified. Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale} which allows the time scale of the alignment system to be specified. Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since this is a close approximation to an inertial frame of rest. \cleardoublepage \section{\label{ss:framesets}Coordinate System Networks (FrameSets)} We saw in \secref{ss:introducingconversion} how \htmlref{astConvert}{astConvert} could be used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems represented by Frames. There is a limitation to this, however, in that it can only be applied to coordinate systems that are inter-related by suitable conventions. In the case of celestial coordinates, the relevant conventions are standards set out by the International Astronomical Union, and others, that define what these coordinate systems mean. In practice, however, the relationships between many other coordinate systems are also of practical importance. Consider, for example, the focal plane of a telescope upon which an image of the sky is falling. We could measure positions in this focal plane in millimetres or, if there were a detector system such as a CCD present, we could count pixels. We could also use celestial coordinates of many different kinds. All of these systems are equivalent in their effectiveness at specifying positions in the focal plane, but some are more convenient than others for particular purposes. Although we could, in principle, convert between all of these focal plane coordinate systems, there is no pre-defined convention for doing so. This is because the conversions required depend on where the telescope is pointing and how the CCD is mounted in the focal plane. Clearly, knowledge about this cannot be built into the AST library and must be supplied in some other way. Note that this is exactly the same problem as we met in \secref{ss:framedomains} when discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that apply to different physical domains require that extra information be supplied before we can convert between them. What we need, therefore, is a general way to describe how coordinate systems are inter-related, so that when there is no convention already in place, we can define our own. We can then look forward to converting, say, from pixels into galactic coordinates and {\emph{vice versa.} In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability. \subsection{The FrameSet Model} Consider a coordinate system (call it number 1) which is represented by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to the coordinates in system 1 yields coordinates in another system, number 2. The Mapping therefore inter-relates coordinate systems 1 and 2. Now consider a second Mapping which inter-relates system 1 and a further coordinate system, number 3. If we wanted to convert coordinates between systems 2 and 3, we could do so by: \begin{enumerate} \item Applying our first Mapping in reverse, so as to convert between systems 2 and 1. \item Applying the second Mapping, as given, to convert between systems 1 and 3. \end{enumerate} We are not limited to three coordinate systems, of course. In fact, we could continue to introduce any number of further coordinate systems, so long as we have a suitable Mapping for each one which relates it to one of the Frames already present. Continuing in this way, we can build up a network in which Frames are inter-related by Mappings in such a way that there is always a way of converting between any pair of coordinate systems. The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas. It is a network composed of Frames and associated Mappings, in which there is always exactly one path, \emph{via} Mappings, between any pair of Frames. Since we assemble FrameSets ourselves, they can be used to represent any coordinate systems we choose and to set up the particular relationships between them that we want. \subsection{\label{ss:creatingaframeset}Creating a FrameSet} Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to put into it, so let's create a simple one: \small \begin{terminalv} #include "ast.h" AstFrame *frame1; ... frame1 = astFrame( 2, "Domain=A" ); \end{terminalv} \normalsize We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to A so that it will be distinct from the others we will be using. We can now create a new FrameSet containing just this Frame, as follows: \small \begin{terminalv} AstFrameSet *frameset; ... frameset = astFrameSet( frame1, "" ); \end{terminalv} \normalsize So far, however, this Frame isn't related to any others. \subsection{\label{ss:addingframes}Adding New Frames to a FrameSet} We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above (\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that are already present (there is only one present so far). To keep the example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates by 10. The required Objects are created as follows: \small \begin{terminalv} AstFrame *frame2; AstMapping *mapping12; ... frame2 = astFrame( 2, "Domain=B" ); mapping12 = astZoomMap( 2, 10.0, "" ); \end{terminalv} \normalsize To add the new Frame into our FrameSet, we use the \htmlref{astAddFrame}{astAddFrame} function: \small \begin{terminalv} astAddFrame( frameset, 1, mapping12, frame2 ); \end{terminalv} \normalsize Whenever a Frame is added to a FrameSet, it is assigned an integer index. This index starts with 1 for the initial Frame used to create the FrameSet (\secref{ss:creatingaframeset}) and increments by one every time a new Frame is added. This index is the primary way of identifying the Frames within a FrameSet. When a Frame is added, we also have to specify which of the existing ones the new Frame is related to. Here, we chose number 1, the only one present so far, and the new one we added became number 2. Note that a FrameSet does not make copies of the Frames and Mappings that you insert into it. Instead, it holds pointers to them. This means that if you retain the original pointers to these Objects and alter them, you will indirectly be altering the FrameSet's contents. You can, of course, always use \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if you need to ensure its independence. We could also add a third Frame into our FrameSet, this time defining a coordinate system which is reached by multiplying the original coordinates (of ``frame1'') by 5: \small \begin{terminalv} astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) ); \end{terminalv} \normalsize Here, we have avoided storing unnecessary pointer values by using function invocations directly as arguments for astAddFrame. This assumes that we are using \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} (\secref{ss:contexts}) to ensure that Objects are correctly deleted when no longer required. Our example FrameSet now contains three Frames and two Mappings with the arrangement shown in Figure~\ref{fig:fsexample}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/fsexample} \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to Frame~1 by multiplying its coordinates by factors of 10 and 5 respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its \htmlref{Current}{Current} attribute has the value 3. The transformation performed when the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to its current Frame) is shown in bold.} \label{fig:fsexample} \end{center} \end{figure} The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute. \subsection{\label{ss:baseandcurrent}The Base and Current Frames} At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its \emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame (Figure~\ref{fig:fsexample}). These Frames are identified by two integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices of the nominated Frames within the FrameSet. The existence of the base and current Frames reflects an important application of FrameSets, which is to attach coordinate systems to entities such as data arrays, data files, plotting surfaces (for graphics), \emph{etc.} In this context, the base Frame represents the ``native'' coordinate system of the attached entity---for example, the pixel coordinates of an image or the intrinsic coordinates of a plotting surface. The other Frames within the FrameSet represent alternative coordinate systems which may also be used to refer to positions within that entity. The current Frame represents the particular coordinate system which is currently selected for use. For instance, if an image were being displayed, you would aim to label it with coordinates corresponding to the current Frame. In order to see a different coordinate system, a software user would arrange for a different Frame to be made current. The choice of base and current Frames may be changed at any time, simply by assigning new values to the FrameSet's Base and Current attributes. For example, to make the Frame with index 3 become the current Frame, you could use: \small \begin{terminalv} astSetI( frameset, "Current", 3 ); \end{terminalv} \normalsize You can nominate the same Frame to be both the base and current Frame if you wish. \label{ss:baseandcurrentdefault} By default (\emph{i.e.}\ if the Base or Current attribute is un-set), the first Frame added to a FrameSet becomes its base Frame and the last one added becomes its current Frame.\footnote{Although this is reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a new Frame is added to a FrameSet, the Current attribute is modified so that the new Frame becomes the current one. This behaviour is reflected in the state of the example FrameSet in Figure~\ref{fig:fsexample}. \subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames} It is often necessary to refer to the base and current Frames (\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes on each occasion. To make this easier, two macros, AST\_\_BASE and AST\_\_CURRENT, are defined in the ``ast.h'' header file and may be used to represent the indices of the base and current Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is required. For example, when adding a new Frame to a FrameSet (\secref{ss:addingframes}), you could use the following to indicate that the new Frame is related to the existing current Frame, whatever its index happens to be: \small \begin{terminalv} AstFrame *frame; AstMapping *mapping; ... astAddFrame( frameset, AST__CURRENT, mapping, frame ); \end{terminalv} \normalsize Of course, the Frame you added would then become the new current Frame. \subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping} The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame} class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class (\secref{ss:mappings}). Its behaviour when used as a Mapping is particularly important. Consider, for instance, passing a FrameSet pointer to a coordinate transformation function such as \htmlref{astTran2}{astTran2}: \small \begin{terminalv} #define N 10 double xin[ N ], yin[ N ], xout[ N ], yout[ N ]; ... astTran2( frameset, N, xin, yin, 1, xout, yout ); \end{terminalv} \normalsize The coordinate transformation applied by this FrameSet would be the one which converts between its base and current Frames. Using the FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates would be multiplied by a factor of 5. If we instead requested the FrameSet's inverse transformation, we would be transforming from its current Frame to its base Frame, so our example FrameSet would then multiply by a factor of 0.2. Whenever the choice of base and current Frames changes, the transformations which a FrameSet performs when used as a Mapping also change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in consequence, because they are determined by the numbers of axes in the FrameSet's base and current Frames respectively. These numbers need not necessarily be equal, of course. Like any Mapping, a FrameSet may also be inverted by changing the boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}). If this is happens, the values of the FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with its Nin and Nout attributes, so that its base and current Frames swap places. When used as a Mapping, the FrameSet will therefore perform the inverse transformation to that which it performed previously. To summarise, a FrameSet may be used exactly like any other Mapping which inter-relates the coordinate systems described by its base and current Frames. \subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet} Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is required (\secref{ss:framesetasmapping}), a FrameSet necessarily contains additional information and sometimes this might cause inefficiency or confusion. For example, if you wanted to use a Mapping contained in one FrameSet and insert it into another, it would probably not be efficient to insert the whole of the first FrameSet into the second one, although it would work. In such a situation, the \htmlref{astGetMapping}{astGetMapping} function allows you to extract a Mapping from a FrameSet. You do this by specifying the two Frames which the Mapping should inter-relate using their indices within the FrameSet. For example: \small \begin{terminalv} map = astGetMapping( frameset, 2, 3 ); \end{terminalv} \normalsize would return a pointer to a Mapping that converted between Frames~2 and 3 in the FrameSet. Its inverse transformation would then convert in the opposite direction, \emph{i.e.}\ between Frames~3 and 2. Note that this Mapping might not be independent of the Mappings contained within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so \htmlref{astCopy}{astCopy} should be used to make a copy if you need to guarantee independence (\secref{ss:copyingobjects}). Very often, the Mapping returned by astGetMapping will be a compound Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that conversion between the two Frames may need to be done \emph{via} an intermediate coordinate system so that several stages may be involved. You can, however, easily simplify this Mapping (where this is possible) by using the \htmlref{astSimplify}{astSimplify} function (\secref{ss:simplifyingcmpmaps}) and this is recommended if you plan to use it for transforming a large amount of data. \subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame} A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost always behaves as if its current Frame had been used instead. For example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using: \small \begin{terminalv} const char *title; ... title = astGetC( frameset, "Title" ); \end{terminalv} \normalsize the result will be the Title of the current Frame, or a suitable default if the current Frame's Title attribute is un-set. The same also applies to other attribute operations---\emph{i.e.}\ setting, clearing and testing attributes. Most attributes shared by both Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)}, \htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions: \begin{quote} \begin{description} \item[\htmlref{Class}{Class}]\mbox{}\\ Has the value ``FrameSet''. \item[\htmlref{ID}{ID}]\mbox{}\\ Identifies the particular FrameSet (not its current Frame). \item[\htmlref{Nin}{Nin}]\mbox{}\\ Equals the number of axes in the FrameSet's base Frame. \item[\htmlref{Invert}{Invert}]\mbox{}\\ Is independent of any of the Objects within the FrameSet. \item[\htmlref{Nobject}{Nobject}]\mbox{}\\ Counts the number of active FrameSets. \item[\htmlref{RefCount}{RefCount}]\mbox{}\\ Counts the number of active pointers to the FrameSet (not to its current Frame). \end{description} \end{quote} Note that the set of attributes possessed by a FrameSet can vary, depending on the nature of its current Frame. For example, if the current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired, \emph{etc.} However, if the current Frame is changed to be a basic Frame, which does not have an Equinox attribute, then this attribute will be absent from the FrameSet as well. Any attempt to reference it will then result in an error. \subsection{Extracting a Frame from a FrameSet} Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most situations, it is sometimes convenient to have direct access to a specified Frame within it. This may be obtained using the \htmlref{astGetFrame}{astGetFrame} function, as follows: \small \begin{terminalv} frame = astGetFrame( frameset, AST__BASE ); \end{terminalv} \normalsize This would return a pointer (not a copy) to the base Frame within the FrameSet. Note the use of AST\_\_BASE (\secref{ss:astbaseandastcurrent}) as shorthand for the value of the FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index. \subsection{Removing a Frame from a FrameSet} Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed using the \htmlref{astRemoveFrame}{astRemoveFrame} function. You identify the Frame you wish to remove in the usual way, by giving its index within the FrameSet. For example, the following would remove the Frame with index 1: \small \begin{terminalv} astRemoveFrame( frameset, 1 ); \end{terminalv} \normalsize The only restriction is that you cannot remove the last remaining Frame because a FrameSet must always contain at least one Frame. When a Frame is removed, the Frames which follow it are re-numbered (\emph{i.e.}\ their indices are reduced by one) so as to preserve the sequence of consecutive Frame indices. The FrameSet's \htmlref{Nframe}{Nframe} attribute is also decremented. If appropriate, astRemoveFrame will modify the FrameSet's \htmlref{Base}{Base} and/or \htmlref{Current}{Current} attributes so that they continue to identify the same Frames as previously. If either the base or current Frame is removed, however, the corresponding attribute will become un-set, so that it reverts to its default value (\secref{ss:baseandcurrentdefault}) and therefore identifies an alternative Frame. Note that it is quite permissible to remove any Frame from a FrameSet, even although other Frames may appear to depend on it. For example, in Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct relationship between Frames~2 and 3 would still be preserved, although they would be re-numbered as Frames~1 and 2. \cleardoublepage \section{\label{ss:fshigher}Higher Level Operations on FrameSets} \subsection{\label{ss:framesetsfromconvert}Creating FrameSets with astConvert} Before considering the important subject of using FrameSets to convert between coordinate systems (\secref{ss:framesetconverting}), let us return briefly to reconsider the output generated by \htmlref{astConvert}{astConvert}. We used this function earlier (\secref{ss:introducingconversion}), when converting between the coordinate systems represented by various kinds of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the coordinate conversion it identifies. We are now in a position to examine the structure of this FrameSet. Take our earlier example (\secref{ss:convertingskyframes}) of converting between the celestial coordinate systems represented by two SkyFrames: \small \begin{terminalv} #include "ast.h" AstFrameSet *cvt; AstSkyFrame *skyframe1, *skyframe2; ... skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); cvt = astConvert( skyframe1, skyframe2, "" ); \end{terminalv} \normalsize This will produce a pointer, ``cvt'', to the FrameSet shown in Figure~\ref{fig:fsconvert}. \begin{figure}[bhtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/fsconvert} \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when astConvert is used to convert between the coordinate systems represented by two SkyFrames. The source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the required conversion.} \label{fig:fsconvert} \end{center} \end{figure} As can be seen, this FrameSet contains just two Frames. The source Frame supplied to astConvert becomes its base Frame, while the destination Frame becomes its current Frame. (The FrameSet, of course, simply holds pointers to these Frames, rather than making copies.) The Mapping which relates the base Frame to the current Frame is the one which implements the required conversion. As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet returned by astConvert may be used both as a Mapping and as a Frame to perform most of the functions you are likely to need. However, the Mapping may be extracted for use on its own if necessary, using \htmlref{astGetMapping}{astGetMapping} (\secref{ss:extractingamapping}), for example: \small \begin{terminalv} AstMapping *mapping; ... mapping = astGetMapping( cvt, AST__BASE, AST__CURRENT ); \end{terminalv} \normalsize \subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems} We now consider the process of converting between the coordinate systems represented by two FrameSets. This is a most important operation, as a subsequent example (\secref{ss:registeringimages}) will show, and is illustrated in Figure~\ref{fig:fsalign}. \begin{figure} \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/fsalign} \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion between two FrameSets is performed by establishing a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion between these two Frames is possible, then a route for converting between the current Frames of both FrameSets can also be found. In practice, there may be many ways of pairing Frames to find the ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to narrow the choice.} \label{fig:fsalign} \end{center} \end{figure} Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave like its current \htmlref{Frame}{Frame} when necessary, conversion between two FrameSets is performed using \htmlref{astConvert}{astConvert} (\secref{ss:convertingskyframes}), but supplying pointers to FrameSets instead of Frames. The effect of this is to convert between the coordinate systems represented by the current Frames of each FrameSet: \small \begin{terminalv} AstFrameSet *frameseta, *framesetb; ... cvt = astConvert( frameseta, framesetb, "SKY" ); \end{terminalv} \normalsize When using FrameSets, we are presented with considerably more conversion options than when using Frames alone. This is because each current Frame is related to all the other Frames in its respective FrameSet. Therefore, if we can establish a link between any pair of Frames, one from each FrameSet, we can form a complete conversion path between the two current Frames (Figure~\ref{fig:fsalign}). This expanded range of options is, of course, precisely the intention. By connecting Frames together within a FrameSet, we have extended the range of coordinate systems that can be reached from any one of them. We are therefore no longer restricted to converting between Frames with the same Domain value (\secref{ss:framedomains}), but can go \emph{via} a range of intermediate coordinate systems in order to make the connection we require. Transformation between different domains has therefore become possible because, in assembling the FrameSets, we provided the additional information needed to inter-relate them. It is important to appreciate, however, that the choice of ``missing link'' is crucial in determining the conversion that results. Although each FrameSet may be perfectly self-consistent internally, this does not mean that all conversion paths through the combined network of Mappings are equivalent. Quite the contrary in fact: everything depends on where the inter-connecting link between the two FrameSets is made. In practice, there may be a large number of possible pairings of Frames and hence of possible links. Other factors must therefore be used to restrict the choice. These are: \begin{enumerate} \item Not every possible pairing of Frames is legitimate. For example, you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which belong to different classes, so such pairings will be ignored. \item In a similar way, you cannot convert directly between Frames with different Domain values (\secref{ss:framedomains}). If the Domain attribute is used consistently (typically only one Frame in each FrameSet will have a particular Domain value), then this further restricts the choice. \item The third argument of astConvert may then be used to specify explicitly which Domain value the paired Frames should have. You may also supply a comma-separated list of preferences here (see below). \item If the above steps fail to uniquely identify the link, then the first suitable pairing of Frames is used, so that any ambiguity is resolved by the order in which Frames are considered for pairing (see the description of the astConvert function in \appref{ss:functiondescriptions} for details of the search order).\footnote{If you find that how this ambiguity is resolved actually makes a difference to the conversion that results, then you have probably constructed a FrameSet which lacks internal self-consistency. For example, you might have two Frames representing indistinguishable coordinate systems but inter-related by a non-null \htmlref{Mapping}{Mapping}.} \end{enumerate} In the example above we supplied the string ``SKY'' as the third argument of astConvert. This constitutes a request that a pair of Frames with the Domain value SKY (\emph{i.e.}\ representing celestial coordinate systems) should be used to inter-relate the two FrameSets. Note that this does not specify which celestial coordinate system to use, but is a general request that the two FrameSets be inter-related using coordinates on the celestial sphere. Of course, it may be that this request cannot be met because there may not be a celestial coordinate system in both FrameSets. If this is likely to happen, we can supply a list of preferences, or a \emph{domain search path}, as the third argument to astConvert, such as the following: \small \begin{terminalv} cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID," ); \end{terminalv} \normalsize Now, if the two FrameSets cannot be inter-related using the SKY domain, astConvert will attempt to use the PIXEL domain instead. If this also fails, it will try the GRID domain. A blank field in the domain search path (here indicated by the final comma) allows any Domain value to be used. This can be employed as a last resort when all else has failed. If astConvert succeeds in identifying a conversion, it will return a pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the source and destination Frames are inter-connected by the required Mapping. In this case, of course, these Frames will be the current Frames of the two FrameSets, but in all other respects the returned FrameSet is the same as when converting between Frames. Very importantly, however, astConvert may modify the FrameSets you are converting between. It does this, in order to indicate which pairing of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base} attribute for each FrameSet so that the Frame used in the pairing becomes its base Frame (\secref{ss:baseandcurrent}). Finally, note that astConvert may also be used to convert between a FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is supplied for either the first or second argument, it will behave like a FrameSet containing only a single Frame. \subsection{\label{ss:registeringimages}Example---Registering Two Images} Consider two images which have been calibrated by attaching FrameSets to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the raw data grid coordinates of each image (the GRID domain of \secref{ss:domainconventions}). Suppose, also, that these FrameSets contain an unknown number of other Frames, representing alternative world coordinate systems. What we wish to do is register these two images, such that we can transform from a position in the data grid of one into the corresponding position in the data grid of the other. This is a very practical example because images will typically be calibrated using FrameSets in precisely this way. The first step will probably involve making a copy of both FrameSets (using \htmlref{astCopy}{astCopy}---\secref{ss:copyingobjects}), since we will be modifying them. Let ``frameseta'' and ``framesetb'' be pointers to these copies. Since we want to convert between the base Frames of these FrameSets (\emph{i.e.}\ their data grid coordinates), the next step is to make these Frames current. This is simply done by inverting both FrameSets, which interchanges their base and current Frames. \htmlref{astInvert}{astInvert} will perform this task: \small \begin{terminalv} astInvert( frameseta ); astInvert( framesetb ); \end{terminalv} \normalsize To identify the required conversion, we now use \htmlref{astConvert}{astConvert}, supplying a suitable domain search path with which we would like our two images to be registered: \small \begin{terminalv} cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID" ); if ( cvt == AST__NULL ) { } else { } \end{terminalv} \normalsize The effects of this are: \begin{enumerate} \item astConvert first attempts to register the two images on the celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it searches for a celestial coordinate system, although not necessarily the same one, attached to each image. If it finds a suitable pair of coordinate systems, it then registers the images by matching corresponding positions on the sky. \item If this fails, astConvert next tries to match positions in the PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two images will then be registered so that their corresponding pixel positions correspond. If the PIXEL domain is offset from the data grid (as typically happens in data reduction systems which implement a ``pixel origin''), then this will be correctly accounted for. \item If this also fails, the GRID domain is finally used. This will result in image registration by matching corresponding points in the data grids used by both images. This means they will be aligned so that the first element their data arrays correspond. \item If all of the above fail, astConvert will return the value AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned. \end{enumerate} The resulting ``cvt'' FrameSet may then be used directly (\secref{ss:convertingskyframes}) to convert between positions in the data grid of the first image and corresponding positions in the data grid of the second image. To determine which domain was used to achieve registration, we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by astConvert to indicate which intermediate Frames were used. We can therefore simply invert either FrameSet (to make its base Frame become the current one) and then enquire the \htmlref{Domain}{Domain} value: \small \begin{terminalv} const char *domain; ... astInvert( frameseta ); domain = astGetC( frameseta, "Domain" ); \end{terminalv} \normalsize If conversion was successful, the result will be one of the strings ``SKY'', ``PIXEL'' or ``GRID''. \subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System} As discussed earlier (\secref{ss:baseandcurrent}), an important application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to be attached to entities such as images in order to calibrate them. In addition, one of the main objectives of AST is to simplify the propagation of such information through successive stages of data processing, so that it remains consistent with the associated image data. In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with the image's data grid coordinates and its other Frames (if any) with the various alternative world coordinate systems associated with the image. If the data processing being performed does not change the relationship between the image's data grid coordinates and any of the associated world coordinate systems, then propagation of the WCS information is straightforward and simply involves copying the FrameSet associated with the image. If any of these relationships change, however, then corresponding changes must be made to the way Frames within the FrameSet are inter-related. By far the most common case occurs when the image undergoes some geometrical transformation resulting in ``re-gridding'' on to another data grid, but the same principles can be applied to any re-definition of a coordinate system. To pursue the re-gridding example, we would need to modify our FrameSet to account for the fact that the image's data grid coordinate system (corresponding to the FrameSet's base Frame) has changed. Looking at the steps needed in detail, we might proceed as follows: \begin{enumerate} \item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the original data grid coordinate system and the new one. \item Obtain a Frame to represent the new data grid coordinate system (we could re-use the original base Frame here, using \htmlref{astGetFrame}{astGetFrame} to obtain a pointer to it). \item Add the new Frame to the FrameSet, related to the original base Frame by the new Mapping. This Frame now represents the new data grid coordinate system and is correctly related to all the other Frames present.\footnote{This is because any transformation to or from this new Frame must go \emph{via} the base Frame representing the original data grid coordinate system, which we assume was correctly related to all the other Frames present.} \item Remove the original base Frame (representing the old data grid coordinate system). \item Make the new Frame the base Frame and restore the original current Frame. \end{enumerate} The effect of these steps is to change the relationship between the base Frame and all the other Frames present. It is as if a new Mapping has been interposed between the Frame we want to alter and all the other Frames within the FrameSet (Figure~\ref{fig:fsremap}). \begin{figure}[hbtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/fsremap} \caption[Interposing a Mapping into a FrameSet]{The effect of \htmlref{astRemapFrame}{astRemapFrame} is to interpose a Mapping between a nominated Frame within a FrameSet and the remaining contents of the FrameSet. This effectively ``re-defines'' the coordinate system represented by the affected Frame. It may be used to compensate (say) for geometrical changes made to an associated image. The inter-relationships between all the other Frames within the FrameSet remain unchanged.} \label{fig:fsremap} \end{center} \end{figure} Performing the steps above is rather lengthy, however, so the astRemapFrame function is provided to perform all of these operations in one go. A practical example of its use is given below (\secref{ss:wcsprocessingexample}). \subsection{\label{ss:wcsprocessingexample}Example---Binning an Image} As an example of using \htmlref{astRemapFrame}{astRemapFrame}, consider a case where the pixels of a 2-dimensional image have been binned 2$\times$2, so as to reduce the image size by a factor of two in each dimension. We must now modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the image. Much the same process would be needed for any other geometrical change the image might undergo. We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the data grid coordinates in the original image to those in the new one: \small \begin{terminalv} AstWinMap *winmap; double ina[ 2 ] = { 0.5, 0.5 }; double inb[ 2 ] = { 2.5, 2.5 }; double outa[ 2 ] = { 0.5, 0.5 }; double outb[ 2 ] = { 1.5, 1.5 }; ... winmap = astWinMap( 2, ina, inb, outa, outb, "" ); \end{terminalv} \normalsize Here, we have simply set up arrays containing the data grid coordinates of the bottom left and top right corners of the first element in the output image (``outa'' and ``outb'') and the corresponding coordinates in the input image (``ina'' and ``inb''). \htmlref{astWinMap}{astWinMap} then creates a WinMap which performs the required transformation. We do not need to know the size of the image. We can then pass this WinMap to astRemapFrame. This modifies the relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in the FrameSet, so that the base Frame represents the data grid coordinate system of the new image rather than the old one: \small \begin{terminalv} AstFrameSet *frameset; ... astRemapFrame( frameset, AST__BASE, winmap ); \end{terminalv} \normalsize Any other coordinate systems described by the FrameSet, no matter how many of these there might be, are now correctly associated with the new image. \subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets} When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into which you can place any combination of Frames and Mappings that you wish. There are relatively few constraints on this process and no checks are performed to see whether the FrameSet you construct makes physical sense. It is quite possible, for example, to construct a FrameSet containing two identical SkyFrames which are inter-related by a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes no sense, because applying a non-unit Mapping to any set of celestial coordinates cannot yield positions that are still in the original coordinate system. If you use such a FrameSet to perform coordinate conversions, you are likely to get unpredictable results because the information in the FrameSet is corrupt. It is, of course, your responsibility as a programmer to ensure the validity of any information which you insert into a FrameSet. Normally, this is straightforward and simply consists of formulating your problem correctly (a diagram can often help to clarify how coordinate systems are inter-related) and writing the appropriate bug-free code to construct the FrameSet. However, once you start to modify an existing FrameSet, there are new opportunities for corrupting it! Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute simply by using \htmlref{astSet}{astSet} on the FrameSet, as follows: \small \begin{terminalv} astSet( frameset, "Equinox=J2010" ); \end{terminalv} \normalsize The effect of this will be to change the celestial coordinate system which the current Frame represents. You can see, however, that this has the potential to make the FrameSet corrupt unless corresponding changes are also made to the Mapping which relates this SkyFrame to the other Frames within the FrameSet. In fact, it is a general rule that any change to a FrameSet which affects its current Frame can potentially require corresponding changes to the FrameSet's Mappings in order to maintain its overall integrity. Fortunately, once you have stored valid information in a FrameSet, AST will look after these details for you automatically, so that the FrameSet's integrity is maintained. In the example above, it would do this by appropriately re-mapping the current Frame (as if \htmlref{astRemapFrame}{astRemapFrame} had been used---\secref{ss:remapframe}) in response to the use of astSet. One way of illustrating this process is as follows: \small \begin{terminalv} AstSkyFrame *skyframe; ... skyframe = astSkyFrame( "" ); frameSet = astFrameSet( skyframe ); astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe ); \end{terminalv} \normalsize This constructs a trivial FrameSet whose base and current Frames are both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this as a ``pipe'' connecting two coordinate systems. At present, these two systems represent identical ICRS coordinates, so the FrameSet implements a unit Mapping. We can change the coordinate system on the current end of this pipe as follows: \small \begin{terminalv} astSet( frameset, "System=Ecliptic, Equinox=J2010" ); \end{terminalv} \normalsize and the Mapping which the FrameSet implements would change accordingly. To change the coordinate system on the base end of the pipe, we might use: \small \begin{terminalv} astInvert( frameset ); astSet( frameset, "System=Galactic" ); astInvert( frameset ); \end{terminalv} \normalsize The FrameSet would then convert between galactic and ecliptic coordinates. Note that astSet is not the only function which has this effect: \htmlref{astClear}{astClear} behaves similarly, as also does \htmlref{astPermAxes}{astPermAxes} (\secref{ss:permutingaxes}). If you need to circumvent this mechanism for any reason, this can be done by going behind the scenes and obtaining a pointer directly to the Frame you wish to modify. Consider the following, for example: \small \begin{terminalv} skyframe = astGetFrame( frameset, AST__CURRENT ); astSet( skyframe, "Equinox=J2010" ); skyframe = astAnnul( skyframe ); \end{terminalv} \normalsize Here, astSet is applied to the SkyFrame pointer rather than the FrameSet pointer, so the usual checks on FrameSet integrity do not occur. The SkyFrame's Equinox attribute will therefore be modified without any corresponding change to the FrameSet's Mappings. In this case you must take responsibility yourself for maintaining the FrameSet's integrity, perhaps through appropriate use of astRemapFrame. \subsection{Merging FrameSets} As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet} (\secref{ss:addingframes}), it is also possible to add complete sets of inter-related Frames which are contained within another FrameSet. This, of course, corresponds to the process of merging two FrameSets (Figure~\ref{fig:fsmerge}). \begin{figure}[hbtp] \begin{center} \includegraphics[width=0.7\textwidth]{sun211_figures/fsmerge} \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using \htmlref{astAddFrame}{astAddFrame}. FrameSet~B is being added to FrameSet~A by supplying a new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1) and the current Frame of B. In the merged FrameSet, the Frames contributed by B will be re-numbered to become Frames~4, 5 and 6. The base Frame will remain unchanged, but the current Frame of B becomes the new current Frame. Note that FrameSet~B itself is not altered by this process.} \label{fig:fsmerge} \end{center} \end{figure} This process is performed by adding one FrameSet to another using astAddFrame, in much the same manner as when adding a new Frame to an existing FrameSet (\secref{ss:addingframes}). It is simply a matter of providing a FrameSet pointer, instead of a Frame pointer, for the 4th argument. In performing the merger you must, as usual, supply a Mapping, but in this case the Mapping should relate the current Frame of the FrameSet being added to one of the Frames already present. For example, you might perform the merger shown in Figure~\ref{fig:fsmerge} as follows: \small \begin{terminalv} AstMapping *mapping; ... astAddFrame( frameseta, 1, mapping, framesetb ); \end{terminalv} \normalsize The Frames acquired by ``frameseta'' from the FrameSet being added (``framesetb'') are re-numbered so that they retain their original order and follow on consecutively after the Frames that were already present, whose indices remain unchanged. The base Frame of ``frameseta'' remains unchanged, but the current Frame of ``framesetb'' becomes its new current Frame. All the inter-relationships between Frames in both FrameSets remain in place and are preserved in the merged FrameSet. Note that while this process modifies the first FrameSet (``frameseta''), it leaves the original contents of the one being added (``framesetb'') unchanged. %\cleardoublepage %\section{\label{ss:searching}TBW - Searching for Coordinate Systems} \cleardoublepage \section{\label{ss:channels}Saving and Restoring Objects (Channels)} Facilities are provided by the AST library for performing input and output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible to write any Object into various external representations for storage, and then to read these representations back in, so as to restore the original Object. Typically, an Object would be written by one program and read back in by another. We refer to ``external representations'' in the plural because AST is designed to function independently of any particular data storage system. This means that Objects may need converting into a number of different external representations in order to be compatible with (say) the astronomical data storage system in which they will reside. In this section, we discuss the basic I/O facilities which support external representations based on a textual format referred to as the AST ``native format''. These are implemented using a new kind of Object---a \htmlref{Channel}{Channel}. We will examine later how to use other representations, based on an XML format or on the use of FITS headers, for storing Objects. These are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan} (\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}). \subsection{The Channel Model} The best way to start thinking about a \htmlref{Channel}{Channel} is like a C file stream, and to think of the process of creating a Channel as that of opening a file and obtaining a FILE pointer. Subsequently, you can read and write Objects \emph{via} the Channel. This analogy is not quite perfect, however, because a Channel has, in principle, two ``files'' attached to it. One is used when reading, and the other when writing. These are termed the Channel's \emph{source} and \emph{sink} respectively. In practice, the source and sink may both be the same, in which case the analogy with the C file stream is correct, but this need not always be so. It is not necessarily so with the basic Channel, as we will now see (\secref{ss:creatingachannel}). \subsection{\label{ss:creatingachannel}Creating a Channel} The process of creating a \htmlref{Channel}{Channel} is straightforward. As you might expect, it uses the constructor function \htmlref{astChannel}{astChannel}: \small \begin{terminalv} #include "ast.h" AstChannel *channel; ... channel = astChannel( NULL, NULL, "" ); \end{terminalv} \normalsize The first two arguments to astChannel specify the external source and sink that the Channel is to use. There arguments are pointers to C functions and we will examine their use in more detail later (\secref{ss:channelsource} and \secref{ss:channelsink}). In this very simple example we have supplied NULL pointers for both the source and sink functions. This requests the default behaviour, which means that textual input will be read from the program's standard input stream (typically, this means your keyboard) while textual output will go to the standard output stream (typically appearing on your screen). On UNIX systems, of course, either of these streams can easily be redirected to files. This default behaviour can be changed by assigning values to the Channel's \htmlref{SinkFile}{SinkFile} and/or \htmlref{SourceFile}{SourceFile} attributes. These attributes specify the paths to text files that are to be used in place of the standard input and output streams. \subsection{\label{ss:writingtoachannel}Writing Objects to a Channel} The process of saving Objects is very straightforward. You can simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{astWrite}{astWrite} function, as follows: \small \begin{terminalv} int nobj; AstObject *object; ... nobj = astWrite( channel, object ); \end{terminalv} \normalsize The effect of this will be to produce a textual description of the Object which will appear, by default, on your program's standard output stream. Any class of Object may be converted into text in this way. astWrite returns a count of the number of Objects written. Usually, this will be one, unless the Object supplied cannot be represented. With a basic Channel all Objects can be represented, so a value of one will always be returned unless there has been an error. We will see later, however, that more specialised forms of Channel may impose restrictions on the kind of Object you can write (\secref{ss:foreignfitslimitations}). In such cases, astWrite may return zero to indicate that the Object was not acceptable. \subsection{\label{ss:readingfromachannel}Reading Objects from a Channel} Before discussing the format of the output produced above (\secref{ss:writingtoachannel}), let us consider how to read it back, so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first need to save the output in a file. We can do that either by using the \htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output to a file using a shell command like: \small \begin{terminalv} program1 >file \end{terminalv} \normalsize Within a subsequent program, we can read this Object back in by using the \htmlref{astRead}{astRead} function, having first created a suitable \htmlref{Channel}{Channel}: \small \begin{terminalv} object = astRead( channel ); \end{terminalv} \normalsize By default, this function will read from the standard input stream (the default source for a basic Channel), so we would need to ensure that our second program reads its input from the file in which the Object description is stored. On UNIX systems, we could again use a shell redirection command such as: \small \begin{terminalv} program2 $}{astIsA$<$Class$>$} family of functions: \small \begin{terminalv} int ok; ... ok = astIsAFrame( object ); \end{terminalv} \normalsize Note, however, that this will accept any Frame, so would be equally happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}. An alternative validation strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute and then test this character string, as follows: \small \begin{terminalv} #include ... ok = !strcmp( astGetC( object, "Class" ), "Frame" ); \end{terminalv} \normalsize This would only accept a basic Frame and would reject a SkyFrame. \subsection{Storing an ID String with an Object} Occasionally, you may want to store a number of Objects and later retrieve them and use each for a different purpose. If the Objects are of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish them when you read them back (\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the order in which they are stored is a possible solution, this becomes complicated if some of the Objects are optional and may not always be present. It also makes extending your data format in future more difficult. To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident} attribute, both of which allows you, in effect, to attach a textual identification label to it. You simply set the ID or Ident attribute before writing the Object: \small \begin{terminalv} astSet( object, "ID=Calibration" ); nobj = astWrite( channel, object ); \end{terminalv} \normalsize You can then test its value after you read the Object back: \small \begin{terminalv} object = astRead( channel ); if ( !strcmp( astGetC( object, "ID" ), "Calibration" ) ) { } else { } \end{terminalv} \normalsize The only difference between the ID and Ident attributes is that the ID attribute is unique to a particular Object and is lost if, for example, you make a copy of the Object. The Ident attrubute, on the other hand, is transferred to the new Object when a copy is made. Consequently, it is safest to set the value of the ID attribute immediately before you perform the write. \subsection{\label{ss:textualoutputformat}The Textual Output Format} Let us now examine the format of the textual output produced by writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}). To give a concrete example, suppose the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows: \small \begin{terminalv} AstSkyFrame *skyframe; ... nobj = astWrite( channel, skyframe ); \end{terminalv} \normalsize The output should then look like the following: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain # Lbl1 = "Right Ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction (hint) Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} \normalsize You will notice that this output is designed both for a human reader, in that it is formatted, and also to be read back by a computer in order to reconstruct the SkyFrame. In fact, this is precisely the way that \htmlref{astShow}{astShow} works (\secref{ss:displayingobjects}), this function being roughly equivalent to the following use of a Channel: \small \begin{terminalv} channel = astChannel( NULL, NULL, "" ); (void) astWrite( channel, object ); channel = astAnnul( channel ); \end{terminalv} \normalsize Some lines of the output start with a ``\verb?#?'' comment character, which turns the rest of the line into a comment. These lines will be ignored when read back in by \htmlref{astRead}{astRead}. They typically contain default values, or values that can be derived in some way from the other data present, so that they do not actually need to be stored in order to reconstruct the original Object. They are provided purely for human information. The same comment character is also used to append explanatory comments to most output lines. It is not sensible to attempt a complete description of this output format because every class of Object is potentially different and each can define how its own data should be represented. However, there are some basic rules, which mean that the following common features will usually be present: \begin{enumerate} \item Each Object is delimited by matching ``Begin'' and ``End'' lines, which also identify the class of Object involved. \item Within each Object description, data values are represented by a simple ``keyword~$=$~value'' syntax, with one value to a line. \item Lines beginning ``IsA'' are used to mark the divisions between data belonging to different levels in the class hierarchy (\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data associated with the Frame class and the start of data associated with some derived class (a SkyFrame in the above example). ``IsA'' lines may be omitted if associated data values are absent and no confusion arises. \item Objects may contain other Objects as data. This is indicated by an absent value, with the description of the data Object following on subsequent lines. \item Indentation is used to clarify the overall structure. \end{enumerate} Beyond these general principles, the best guide to what a particular line of output represents will generally be the comment which accompanies it together with a general knowledge of the class of Object being described. \subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output} It is not always necessary for the output from \htmlref{astWrite}{astWrite} (\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has attributes that allow the amount of detail in the output to be controlled. The first of these is the integer attribute \htmlref{Full}{Full}, which controls the extent to which optional, commented out, output lines are produced. By default, Full is zero, and this results in the standard style of output (\secref{ss:textualoutputformat}) where default values that may be helpful to humans are included. To suppress these optional lines, Full should be set to $-$1. This is most conveniently done when the Channel is created, so that: \small \begin{terminalv} channel = astChannel( NULL, NULL, "Full=-1" ); (void) astWrite( channel, skyframe ); channel = astAnnul( channel ); \end{terminalv} \normalsize would result in output containing only the essential information, such as: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system Naxes = 2 # Number of coordinate axes Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation End SkyFrame \end{terminalv} \normalsize In contrast, setting Full to $+$1 will result in additional output lines which will reveal every last detail of the \htmlref{Object}{Object}'s construction. Often this will be rather more than you want, especially for more complex Objects, but it can sometimes help when debugging programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail: \small \begin{terminalv} Begin SkyFrame # Description of celestial coordinate system # RefCnt = 1 # Count of active Object pointers # Nobj = 1 # Count of active Objects in same class IsA Object # Astrometry Object # Nin = 2 # Number of input coordinates # Nout = 2 # Number of output coordinates # Invert = 0 # Mapping not inverted # Fwd = 1 # Forward transformation defined # Inv = 1 # Inverse transformation defined # Report = 0 # Don't report coordinate transformations IsA Mapping # Mapping between coordinate systems # Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system Naxes = 2 # Number of coordinate axes # Domain = "SKY" # Coordinate system domain # Lbl1 = "Right Ascension" # Label for axis 1 # Lbl2 = "Declination" # Label for axis 2 # Sym1 = "RA" # Symbol for axis 1 # Sym2 = "Dec" # Symbol for axis 2 # Uni1 = "hh:mm:ss.s" # Units for axis 1 # Uni2 = "ddd:mm:ss" # Units for axis 2 # Dig1 = 7 # Individual precision for axis 1 # Dig2 = 7 # Individual precision for axis 2 # Digits = 7 # Default formatting precision # Fmt1 = "hms.1" # Format specifier for axis 1 # Fmt2 = "dms" # Format specifier for axis 2 # Dir1 = 0 # Plot axis 1 in reverse direction (hint) # Dir2 = 1 # Plot axis 2 in conventional direction (hint) # Presrv = 0 # Don't preserve target axes # Permut = 1 # Axes may be permuted to match # MinAx = 2 # Minimum number of axes to match # MaxAx = 2 # Maximum number of axes to match # MchEnd = 0 # Match initial target axes # Prm1 = 1 # Axis 1 not permuted # Prm2 = 2 # Axis 2 not permuted Ax1 = # Axis number 1 Begin SkyAxis # Celestial coordinate axis # RefCnt = 1 # Count of active Object pointers # Nobj = 2 # Count of active Objects in same class IsA Object # Astrometry Object # Label = "Angle on Sky" # Axis Label # Symbol = "delta" # Axis symbol # Unit = "ddd:mm:ss" # Axis units # Digits = 7 # Default formatting precision # Format = "dms" # Format specifier # Dirn = 1 # Plot in conventional direction IsA Axis # Coordinate axis # Format = "dms" # Format specifier # IsLat = 0 # Longitude axis (not latitude) # AsTime = 0 # Display values as angles (not times) End SkyAxis Ax2 = # Axis number 2 Begin SkyAxis # Celestial coordinate axis # RefCnt = 1 # Count of active Object pointers # Nobj = 2 # Count of active Objects in same class IsA Object # Astrometry Object # Label = "Angle on Sky" # Axis Label # Symbol = "delta" # Axis symbol # Unit = "ddd:mm:ss" # Axis units # Digits = 7 # Default formatting precision # Format = "dms" # Format specifier # Dirn = 1 # Plot in conventional direction IsA Axis # Coordinate axis # Format = "dms" # Format specifier # IsLat = 0 # Longitude axis (not latitude) # AsTime = 0 # Display values as angles (not times) End SkyAxis IsA Frame # Coordinate system description System = "FK4-NO-E" # Celestial coordinate system type Epoch = 1958 # Besselian epoch of observation # Eqnox = 1950 # Besselian epoch of mean equinox End SkyFrame \end{terminalv} \normalsize \subsection{\label{ss:channelcommenting}Controlling Commenting} Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments are appended to describe the purpose of each value. Comment has the value 1 by default but, if set to zero, will suppress these comments. This is normally appropriate only if you wish to minimise the amount of output, for example: \small \begin{terminalv} astSet( channel, "Full=-1, Comment=0" ); nobj = astWrite( channel, skyframe ); \end{terminalv} \normalsize might result in the following more compact output: \small \begin{terminalv} Begin SkyFrame Naxes = 2 Ax1 = Begin SkyAxis End SkyAxis Ax2 = Begin SkyAxis End SkyAxis IsA Frame System = "FK4-NO-E" Epoch = 1958 End SkyFrame \end{terminalv} \normalsize \subsection{Editing Textual Output} The safest advice about editing the textual output from \htmlref{astWrite}{astWrite} (or \htmlref{astShow}{astShow}) is ``don't!''---unless you know what you are doing. Having given that warning, however, it is sometimes possible to make changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from scratch, and to read the results back in to construct new Objects. Normally, simple changes to numerical values are safest, but be aware that this is a back door method of creating Objects, so you are on your own! There are a number of potential pitfalls. In particular: \begin{itemize} \item \htmlref{astRead}{astRead} is intended for retrieving data written by astWrite and not for reading data input by humans. As such, the data validation provided is very limited and is certainly not foolproof. This makes it quite easy to construct Objects that are internally inconsistent by this means. In contrast, the normal programming interface incorporates numerous checks designed to make it impossible to construct invalid Objects. You should not necessarily think you have found a bug if your changes to an Object's textual description fail to produce the results you expected! \item In many instances the names associated with values in textual output will correspond with Object attributes. Sometimes, however, these names may differ from the attribute name. This is mainly because of length restrictions imposed by other common external formats, such as FITS headers. Some of the names used do not correspond with attributes at all. \item It is safest to change single numerical or string values. Beware of changing the size or shape of Objects (\emph{e.g.}\ the number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others stored elsewhere within the Object and changing them in a haphazard fashion will not produce useful results. \item Be wary about un-commenting default values. Sometimes this will work, but often these values are derived from other Objects stored more deeply in the structure and the proper place to insert a new value is not where the default itself appears. \end{itemize} \subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text} By default, when you use \htmlref{astRead}{astRead} to read from a basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}), it is assumed that you are reading a stream of text containing only AST Objects, which follow each other end-to-end. If any extraneous input data are encountered which do not appear to form part of the textual description of an \htmlref{Object}{Object}, then an error will result. In particular, the first input line must identify the start of an Object description, so you cannot start reading half way through an Object. Sometimes, however, you may want to store AST Object descriptions intermixed with other textual data. You can do this by setting the Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every read to skip over extraneous data until the start of a new AST Object description, if any, is found. So long as your other data do not mimic the appearance of an AST Object description, the two sets of data can co-exist. For example, by setting Skip to 1, the following complete C program will read all the AST Objects whose descriptions appear in the source of this document, ignoring the other text. \htmlref{astShow}{astShow} is used to display those found: \small \begin{terminalv} #include "ast.h" main() { AstChannel *channel; AstObject *object; channel = astChannel( NULL, NULL, "Skip=1" ); while ( ( object = astRead( channel ) ) != AST__NULL ) { astShow( object ); object = astAnnul( object ); } channel = astAnnul( channel ); } \end{terminalv} \normalsize \subsection{\label{ss:channelsource}Reading Objects from Files} Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel} in reading and writing Objects through a program's standard input and output streams. We will now consider how to access Objects stored in files more directly. The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of the Channel. For instance, the following will read a pair of Objects from a text file called ``fred.txt'': \small \begin{terminalv} astSet( channel, "SourceFile=fred.txt" ); obj1 = astRead( channel ); obj2 = astRead( channel ); astClear( channel, "SourceFile" ); \end{terminalv} \normalsize Note, the act of clearing the attribute tells AST that no more Objects are to be read from the file and so the file is then closed. If the attribute is not cleared, the file will remain open and further Objects can be read from it. The file will always be closed when the Channel is deleted. This simple approach will normally be sufficient. However, because the AST library is designed to be used from more than one language, it has to be a little careful about reading and writing to files. This is due to incompatibilities that may exist between the file I/O facilities provided by different languages. If such incompatibilities prevent the above simple system being used, we need to adopt a system that off-loads all file I/O to external code. What this means in practice is that if the above simple approach cannot be used, you must instead provide some simple C functions that perform the actual transfer of data to and from files and similar external data stores. The functions you provide are supplied as the source and/or sink function arguments to \htmlref{astChannel}{astChannel} when you create a Channel (\secref{ss:creatingachannel}). An example is the best way to illustrate this. Consider the following simple function called Source. It reads a single line of text from a C input stream and returns a pointer to it, or NULL if there is no more input: \small \begin{terminalv} #include #define LEN 200 static FILE *input_stream; const char *Source( void ) { static char buffer[ LEN + 2 ]; return fgets( buffer, LEN + 2, input_stream ); } \end{terminalv} \normalsize Note that the input stream is a static variable which we will also access from our main program. This might look something like this (omitting error checking for brevity): \small \begin{terminalv} /* Open the input file. */ input_stream = fopen( "infile.ast", "r" ); /* Create a Channel and read an Object from it. */ channel = astChannel( Source, NULL, "" ); object = astRead( channel ); ... /* Annul the Channel and close the file when done. */ channel = astAnnul( channel ); (void) fclose( input_stream ); \end{terminalv} \normalsize Here, we first open the required input file, saving the resulting FILE pointer. We then pass a pointer to our Source function as the first argument to astChannel when creating a new Channel. When we read an \htmlref{Object}{Object} from this Channel with \htmlref{astRead}{astRead}, the Source function will be called to obtain the textual data from the file, the end-of-file being detected when this function returns NULL. Note, if a value is set for the SourceFile attribute, the astRead function will ignore any source function specified when the Channel was created. \subsection{\label{ss:channelsink}Writing Objects to Files} As for reading, writing Objects to files can be done in two different ways. Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}. For instance, the following will write a pair of Objects to a text file called ``fred.txt'': \small \begin{terminalv} astSet( channel, "SinkFile=fred.txt" ); nobj = astWrite( channel, object1 ); nobj = astWrite( channel, object2 ); astClear( channel, "SinkFile" ); \end{terminalv} \normalsize Note, the act of clearing the attribute tells AST that no more output will be written to the file and so the file is then closed. If the attribute is not cleared, the file will remain open and further Objects can be written to it. The file will always be closed when the Channel is deleted. If the details of the language's I/O system on the computer you are using means that the above approach cannot be used, then we can write a Sink function, that writes a line of output text to a file, and use it in basically the same way as the Source function in the previous section (\secref{ss:channelsource}): \small \begin{terminalv} static FILE *output_stream; void Sink( const char *line ) { (void) fprintf( output_stream, "%s\n", line ); } \end{terminalv} \normalsize Note that we must supply the final newline character ourselves. In this case, our main program would supply a pointer to this Sink function as the second argument to \htmlref{astChannel}{astChannel}, as follows: \small \begin{terminalv} /* Open the output file. */ output_stream = fopen( "outfile.ast", "w" ); /* Create a Channel and write an Object to it. */ channel = astChannel( Source, Sink, "" ); nobj = astWrite( channel, object ); ... /* Annul the Channel and close the file when done. */ channel = astAnnul( channel ); (void) fclose( output_stream ); \end{terminalv} \normalsize Note that we can specify a source and/or a sink function for the Channel, and that these may use either the same file, or different files according to whether we are reading or writing. AST has no knowledge of the underlying file system, nor of file positioning. It just reads and writes sequentially. If you wish, for example, to reposition a file at the beginning in between reads and writes, then this can be done directly (and completely independently of AST) using standard C functions. If an error occurs in your source or sink function, you can communicate this to the AST library by setting its error status to any error value using \htmlref{astSetStatus}{astSetStatus} (\secref{ss:errordetection}). This will immediately terminate the read or write operation. Note, if a value is set for the SinkFile attribute, the \htmlref{astWrite}{astWrite} function will ignore any sink function specified when the Channel was created. \subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places} It should be obvious from the above (\secref{ss:channelsource} and \secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink functions provide a flexible means of intercepting textual data that describes AST Objects as it flows in and out of your program. In fact, you might like to regard a Channel simply as a filter for converting AST Objects to and from a stream of text which is then handled by your source and sink functions, where the real I/O occurs. This gives you the ability to store AST Objects in virtually any data system, so long as you can convert a stream of text into something that can be stored (it need no longer be text) and retrieve it again. There is generally no need to retain comments. Other possibilities, such as inter-process and network communication, could also be implemented \emph{via} source and sink functions in basically the same way. \cleardoublepage \section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)} A FITS header is a sequence of 80-character strings, formatted according to particular rules defined by the Flexible Image Transport \htmlref{System}{System} (FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/} is a widely-used standard for data interchange in astronomy and has also been adopted as a data processing format in some astronomical data reduction systems. The individual 80-character strings in a FITS header are usually called \emph{cards} or \emph{header cards} (for entirely anachronistic reasons). A sequence of FITS cards appears as a header at the start of every FITS data file, and sometimes also at other points within it, and is used to provide ancillary information which qualifies or describes the main array of data stored in the file. As such, FITS headers are prime territory for storing information about the coordinate systems associated with data held in FITS files. In this section, we will examine how to store information in FITS headers directly in the form of AST Objects---a process which is supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our discussion here will turn out to be a transitional step that emphasises the similarities between a FitsChan and a Channel (\secref{ss:channels}). At the same time, it will prepare us for the next section (\secref{ss:foreignfits}), where we will examine how to use a FitsChan to tackle some of the more difficult problems that FITS headers can present. \subsection{\label{ss:nativeencoding}The Native FITS Encoding} As it turns out, we are not the first to have thought of storing WCS information in FITS headers. In fact, the original FITS standard (1981 vintage) defined a set of header keywords for this purpose which have been widely used, although they have proved too limited for many practical purposes. At the time of writing, a number of different ways of using FITS headers for storing WCS information are in use, most (although not all) based on the original standard. We will refer to these alternative ways of storing the information as FITS \emph{encodings} but will defer a discussion of their advantages and limitations until the next section (\secref{ss:foreignfits}). Here, we will examine how to store AST Objects directly in FITS headers. In effect, this defines a new encoding, which we will term the \emph{native encoding}. This is a special kind of encoding, because not only does it allow us to associate conventional WCS calibration information with FITS data, but it also allows any other information that can be expressed in terms of AST Objects to be stored as well. In fact, the native encoding provides us with facilities roughly analogous to those of the \htmlref{Channel}{Channel} (\secref{ss:channels})---\emph{i.e.}\ a lossless way of transferring AST Objects from program to program---but based on FITS headers instead of free-format text. \subsection{The FitsChan Model} I/O between AST Objects and FITS headers is supported by a specialised form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which may hold any number, including zero, of FITS header cards. This buffer forms a workspace in which you can assemble FITS cards and manipulate them before writing them out to a file. By default, when a FitsChan is first created, it contains no cards and there are five ways of inserting cards into it: \begin{enumerate} \item You may add cards yourself, one at a time, using \htmlref{astPutFits}{astPutFits} (\secref{ss:addingfitscards}). \item You may add cards yourself, supplying all cards concatenated into a single string, using \htmlref{astPutCards}{astPutCards} (\secref{ss:addingmulticards}). \item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{astWrite}{astWrite}), which will have the effect of creating new cards within the FitsChan which describe the Object (\secref{ss:writingnativefits}). \item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan. The value should be the path to a text file holding a set of FITS header cards, one per line. When the SourceFile value is set (using astSetC or \htmlref{astSet}{astSet}), the file is opened and the headers copied from it into the FitsChan. The file is then immediately closed. \item You may specify a source function which reads data from some external store of FITS cards, just like the source associated with a basic Channel (\secref{ss:channelsource}). If you supply a source function, it will be called when the FitsChan is created in order to fill it with an initial set of cards (\secref{ss:fitssourceandsink}). \end{enumerate} There are also four ways of removing cards from a FitsChan: \begin{enumerate} \item You may delete cards yourself, one at a time, using \htmlref{astDelFits}{astDelFits} (\secref{ss:findingandchangingfits}). \item You may read an AST Object from the FitsChan (using \htmlref{astRead}{astRead}), which will have the effect of removing those cards from the FitsChan which describe the Object (\secref{ss:readingnativefits}). \item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When the FitsChan is deleted, any remaining headers are written out to a text file with path equal to the value of the SinkFile attribute. \item Alternatively, you may specify a sink function which writes data to some external store of FITS cards, just like the sink associated with a basic Channel (\secref{ss:channelsink}). If you supply a sink function, it will be called when the FitsChan is deleted in order to write out any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note, the sink function is not called if the SinkFile attribute has been set. \end{enumerate} Note, in particular, that reading an AST Object from a FitsChan is \emph{destructive}. That is, it deletes the FITS cards that describe the Object. The reason for this is explained in \secref{ss:destructiveread}. In addition to the above, you may also read individual cards from a FitsChan using the function \htmlref{astFindFits}{astFindFits} (which is not destructive). This is the main means of writing out FITS cards if you have not supplied a sink function. astFindFits also provides a means of searching for particular FITS cards (by keyword, for example) and there are other facilities for overwriting cards when required (\secref{ss:findingandchangingfits}). \subsection{\label{ss:creatingafitschan}Creating a FitsChan} The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{astFitsChan}{astFitsChan}, is straightforward to use: \small \begin{terminalv} #include "ast.h" AstFitsChan *fitschan; ... fitschan = astFitsChan( NULL, NULL, "Encoding=NATIVE" ); \end{terminalv} \normalsize Here, we have omitted any source or sink functions by supplying NULL pointers for the first two arguments. We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to NATIVE. This indicates that we will be using the native encoding (\secref{ss:nativeencoding}) to store and retrieve Objects. If this was left unspecified, the default would depend on the FitsChan's contents. An attempt is made to use whatever encoding appears to have been used previously. For an empty FitsChan, the default is NATIVE, but it does no harm to be sure. \subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan} Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a mechanism is needed for addressing them. This allows you to specify where new cards are to be added, for example, or which card is to be deleted. This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which gives the index of the \emph{current card} in the FitsChan. You can nominate any card you like to be current, simply by setting a new value for the Card attribute, for example: \small \begin{terminalv} int icard; ... astSetI( fitschan, "Card", icard ) \end{terminalv} \normalsize where ``icard'' contains the index of the card on which you wish to operate next. Some functions will update the Card attribute as a means of advancing through the sequence of cards, when reading them for example, or to indicate which card matches a search criterion. The default value for Card is one, which is the index of the first card. This means that you can ``rewind'' a FitsChan to access its first card by clearing the Card attribute: \small \begin{terminalv} astClear( fitschan, "Card" ); \end{terminalv} \normalsize The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard} attribute. This is a read-only attribute whose value is automatically updated as you add or remove cards. It means you can address all the cards in sequence using a loop such as the following: \small \begin{terminalv} int ncard; ... ncard = astGetI( fitschan, "Ncard" ); for ( icard = 1; icard <= ncard; icard++ ) { astSetI( fitschan, "Card", icard ); } \end{terminalv} \normalsize However, it is usually possible to write slightly tidier loops based on the \htmlref{astFindFits}{astFindFits} function described later (\secref{ss:extractingfitscards} and \secref{ss:findingandchangingfits}). If you set the Card attribute to a value larger than Ncard, the FitsChan is regarded as being positioned at its \emph{end-of-file}. In this case there is no current card and an attempt to obtain a value for the Card attribute will always return the value Ncard~$+$~1. When a FitsChan is empty, it is always at the end-of-file. \subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan} Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you can write any AST \htmlref{Object}{Object} to it in the native encoding using the \htmlref{astWrite}{astWrite} function. Let us assume we are writing a \htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet}, but for purposes of illustration a SkyFrame contains a more manageable amount of data.} as follows: \small \begin{terminalv} AstSkyFrame *skyframe; int nobj; ... nobj = astWrite( fitschan, skyframe ); \end{terminalv} \normalsize Since we have selected the native encoding (\secref{ss:nativeencoding}), there are no restrictions on the class of Object we may write, so astWrite should always return a value of one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), this write operation will not produce any output from our program. The FITS headers produced are simply stored inside the FitsChan. After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card} attribute will point at the card immediately after the last one written. Since our FitsChan was initially empty, the Card attribute will, in this example, point at the end-of-file (\secref{ss:addressingfitscards}). The FITS standard imposes a limit of 68 characters on the length of strings which may be stored in a single header card. Sometimes, a description of an AST Object involves the use of strings which exceed this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If this occurs, the long string will be split over two or more header cards. Each ``continuation'' card will have the keyword \texttt{CONTINUE} in columns 1 to 8, and will contain a space in column 9 (instead of the usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of each of the strings (except the last one) to indicate that the string is continued on the next card. Note, this splitting of long strings over several cards only occurs when writing AST Objects to a FitsChan using the astWrite function and the \emph{native} encoding. If a long string is stored in a FitsChan using (for instance) the \htmlref{astPutFits}{astPutFits} or \htmlref{astPutCards}{astPutCards} function, it will simply be truncated. \subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan} To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame} above (\secref{ss:writingnativefits}), we must write a simple loop to extract each card in turn and print it out. We must also remember to rewind the FitsChan first, \emph{e.g.}\ using \htmlref{astClear}{astClear}. The following loop would do: \small \begin{terminalv} #include char card[ 81 ]; ... astClear( fitschan, "Card" ); while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); \end{terminalv} \normalsize Here, we have used the \htmlref{astFindFits}{astFindFits} function to find a FITS card by keyword. It is given a keyword template of ``\%f'', which matches any FITS keyword, so it always finds the current card, which it returns. Its fourth argument is set to 1, to indicate that the \htmlref{Card}{Card} attribute should be incremented afterwards so that the following card will be found the next time around the loop. astFindFits returns zero when it reaches the end-of-file and this terminates the loop. If we were storing the FITS headers in an output FITS file instead of printing them out, we might use a loop like this but replace ``printf'' with a suitable data storage operation. This would only be necessary if we had not provided a sink function for the FitsChan (\secref{ss:fitssourceandsink}). \subsection{The Native FitsChan Output Format} If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote earlier (\secref{ss:writingnativefits}), we should obtain something like the following: \small \begin{terminalv} COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST COMMENT AST Beginning of AST data for SkyFrame object AST COMMENT AST ................................................................ AST BEGAST_A= 'SkyFrame' / Description of celestial coordinate system NAXES_A = 2 / Number of coordinate axes AX1_A = ' ' / Axis number 1 BEGAST_B= 'SkyAxis ' / Celestial coordinate axis ENDAST_A= 'SkyAxis ' / End of object definition AX2_A = ' ' / Axis number 2 BEGAST_C= 'SkyAxis ' / Celestial coordinate axis ENDAST_B= 'SkyAxis ' / End of object definition ISA_A = 'Frame ' / Coordinate system description SYSTEM_A= 'FK4-NO-E' / Celestial coordinate system type EPOCH_A = 1958.0 / Besselian epoch of observation ENDAST_C= 'SkyFrame' / End of object definition COMMENT AST ................................................................ AST COMMENT AST End of AST data for SkyFrame object AST COMMENT AST ---------------------------------------------------------------- AST \end{terminalv} \normalsize As you can see, this resembles the information that would be written to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame (\secref{ss:textualoutputformat}), except that it has been formatted into 80-character header cards according to FITS conventions. There are also a number of other differences worth noting: \begin{enumerate} \item There is no unnecessary information about default values provided for the benefit of the human reader. This is because the \htmlref{Full}{Full} attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You can restore the information if you wish by setting Full to 0 or $+$1, in which case additional COMMENT cards will be generated to hold it. \item The information is not indented, because FITS does not allow this. However, if you change the Full attribute to 0 or $+$1, comments will be included that are intended to help break up the sequence of headers and highlight its structure. This will probably only be of use if you are attempting to track down a problem by examining the FITS cards produced in detail. \item The FITS keywords which appear to the left of the ``$=$'' signs have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to them. This is done in order to make each keyword unique. \end{enumerate} This last point is worth further comment and is necessary because the FITS standard only allows for certain keywords (such as COMMENT and HISTORY) to appear more than once. \htmlref{astWrite}{astWrite} therefore appends an arbitrary sequence of two characters to each new keyword it generates in order to ensure that it does not duplicate any already present in the FitsChan. The main risk from not following this convention is that some software might ignore (say) all but the last occurrence of a keyword before passing the FITS headers on. Such an event is unlikely, but would obviously destroy the information present, so astWrite enforces the uniqueness of the keywords it uses. The extra characters added are ignored when the information is read back. As with a basic Channel, you can also suppress the comments produced in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to zero (\secref{ss:channelcommenting}). However, FITS headers are traditionally generously commented, so this is not recommended. \subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan} To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back as Objects for example, you should use the \htmlref{astPutFits}{astPutFits} function. You can insert a card in front of the current one as follows: \small \begin{terminalv} astPutFits( fitschan, card, 0 ); \end{terminalv} \normalsize where the third argument of zero indicates that the current card should not be overwritten. Note that facilities are not provided by AST for formatting the card contents. After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the original Card, or at the end-of-file if the FitsChan was originally empty. Entering a sequence of cards is therefore straightforward. If ``cards'' is an array of pointers to strings containing FITS header cards and ``ncards'' is the number of cards, then a loop such as the following will insert the cards in sequence into a FitsChan: \small \begin{terminalv} #define MAXCARD 100 char *cards[ MAXCARD ]; int ncard; ... for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); \end{terminalv} \normalsize The string containing a card need not be null terminated if it is at least 80 characters long (we have not allocated space for the strings themselves in this brief example). Note that astPutFits enforces the validity of a FitsChan by rejecting any cards which do not adhere to the FITS standard. If any such cards are detected, an error will result. \subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan} If you have all your cards concatenated together into a single long string, each occupying 80 characters (with no delimiters), you can insert them into a \htmlref{FitsChan}{FitsChan} in a single call using \htmlref{astPutCards}{astPutCards}. This call first empties the supplied FitsChan of any existing cards, then inserts the new cards, and finally rewinds the FitsChan so that a subsequent call to \htmlref{astRead}{astRead} will start reading from the first supplied card. The astPutCards function uses \htmlref{astPutFits}{astPutFits} internally to interpret and store each individual card, and so the caveats in \secref{ss:addingfitscards} should be read. For instance, if you are using the CFITSIO library for access to FITS files, you can use the CFITSIO fits\_hdr2str function to obtain a string suitable for passing to astPutCards: \small \begin{terminalv} if( !fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) fitschan = astFitsChan( NULL, NULL, "" ); astPutCards( fitschan, header ); header = free( header ); wcsinfo = astRead( fitschan ); ... } \end{terminalv} \normalsize \subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan} Once you have stored a FITS header description of an \htmlref{Object}{Object} in a \htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}), you can read it back using \htmlref{astRead}{astRead} in much the same way as with a basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments about validating the Object you read also apply (\secref{ss:validatinginput}). If you have just written to the FitsChan, you must remember to rewind it first: \small \begin{terminalv} AstObject *object; ... astClear( fitschan, "Card" ); object = astRead( fitschan ); \end{terminalv} \normalsize An important feature of a FitsChan is that read operations are destructive. This means that if an Object description is found, it will be consumed by astRead which will remove all the cards involved, including associated COMMENT cards, from the FitsChan. Thus, if you write an Object to a FitsChan, rewind, and read the same Object back, you should end up with the original FitsChan contents. If you need to circumvent this behaviour for any reason, it is a simple matter to make a copy of a FitsChan using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). If you then read from the copy, the original FitsChan will remain untouched. After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the card immediately following the last card read, or the end-of-file of there are no more cards. Since the \emph{native} encoding is being used, any long strings involved in the object description will have been split into two or more adjacent contuation cards when the Object was stored in the header using function \htmlref{astWrite}{astWrite}. The astRead function reverses this process by concatenating any such adjacent continuation cards to re-create the original long string. \subsection{Saving and Restoring Multiple Objects in a FitsChan} When using the native FITS encoding, multiple Objects may be stored and all I/O operations are sequential. This means that you can simply write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation, the \htmlref{Card}{Card} attribute will be updated so that the next write appends the next \htmlref{Object}{Object} description to the previous one. If you then rewind the FitsChan, you can read the Objects back in the original order. Reading them back will, of course, remove their descriptions from the FitsChan (\secref{ss:readingnativefits}) but the behaviour of the Card attribute is such that successive reads will simply return each Object in sequence. The only thing that may require care, given that a FitsChan can always be addressed randomly by setting its Card attribute, is to avoid writing one Object on top of another. For obvious reasons, the Object descriptions in a FitsChan must remain separate if they are to make sense when read back. \subsection{Mixing Native Objects with Other FITS Cards} Of course, any real FITS header will contain other information besides AST Objects, if only the mandatory FITS cards that must accompany all FITS data. When FITS headers are read in from a real dataset, therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with many other cards. Because this is the normal state of affairs, the boolean (integer) \htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when you read an Object From a FitsChan, any irrelevant cards will simply be skipped over until the start of the next Object description, if any, is found. If you start reading part way through an Object description, no error will result. The remainder of the description will simply be skipped. Setting Skip to zero will change this behaviour to resemble that of a basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data are not permitted by default, but this will probably rarely be useful. \subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan} You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by keyword, using the function \htmlref{astFindFits}{astFindFits}. This performs a search, starting at the current card, until it finds a card whose keyword matches the template you supply, or the end-of-file is reached. If a suitable card is found, astFindFits optionally returns the card's contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to identify the card found, or the one following it. The way you want the Card attribute to be set is indicated by the final boolean (int) argument to astFindFits. A value of one is returned to indicate success. If a suitable card cannot be found, astFindFits returns a value of zero to indicate failure and sets the FitsChan's Card attribute to the end-of-file. Requesting that the Card attribute be set to indicate the card that astFindFits finds is useful if you want to replace that card with a new one, as in this example: \small \begin{terminalv} char newcard[ 81 ]; ... (void) astFindFits( fitschan, "AIRMASS", NULL, 0 ); astPutFits( fitschan, newcard, 1 ); \end{terminalv} \normalsize Here, astFindFits is used to search for a card with the keyword AIRMASS, with a NULL pointer being given to indicate that we do not want the card's contents returned. If the card is found, \htmlref{astPutFits}{astPutFits} then overwrites it with a new card. Otherwise, the Card attribute ends up pointing at the end-of-file and the new card is simply appended to the end of the FitsChan. A similar approach can be used to delete selected cards from a FitsChan using \htmlref{astDelFits}{astDelFits}, which deletes the current card: \small \begin{terminalv} if ( astFindFits( fitschan, "BSCALE", NULL, 0 ) ) astDelFits( fitschan ); \end{terminalv} \normalsize This deletes the first card, if any, with the BSCALE keyword. Requesting that astFindFits increments the Card attribute to identify the card following the one found is more useful when writing loops. For example, the following loop extracts each card whose keyword matches the template ``CD\%6d'' (that is, ``CD'' followed by six decimal digits): \small \begin{terminalv} while ( astFindFits( fitschan, "CD%6d", card, 1 ) { } \end{terminalv} \normalsize For further details of keyword templates, see the description of astFindFits in \appref{ss:functiondescriptions}. \subsection{\label{ss:fitssourceandsink}Source and Sink Functions for FitsChans} The use of source and sink functions with a \htmlref{FitsChan}{FitsChan} is optional. This is because you can always arrange to explicitly fill a FitsChan with FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards}) and you can also extract any cards that remain and write them out yourself (\secref{ss:extractingfitscards}) before you delete the FitsChan. If you choose to use these functions, however, they behave in a very similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource} and \secref{ss:channelsink}). You supply pointers to these functions, as arguments to the constructor function \htmlref{astFitsChan}{astFitsChan} when you create the FitsChan (\secref{ss:creatingafitschan}). The source function is invoked implicitly at this point to fill the FitsChan with FITS cards and the FitsChan is then rewound, so that the first card becomes current. The sink function is automatically invoked later, when the FitsChan is deleted, in order to write out any cards that remain in it. The only real difference between the source and sink functions for a FitsChan and a basic Channel is that FITS cards are limited in length to 80~characters, so the choice of buffer size is simplified. The ``Source'' and ``Sink'' functions in \secref{ss:channelsource} and \secref{ss:channelsink} could therefore be used to access FITS headers stored in text files simply by changing LEN to be 80. If you were not accessing a text file, however, appropriate changes to the I/O statements would be needed since the separating newline characters would be absent. The details obviously depend on the format of the file you are handling, which need not necessarily be a true FITS file. \cleardoublepage \section{\label{ss:foreignfits}Using Foreign FITS Encodings} We saw in the previous section (\secref{ss:nativefits}) how to store and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a \htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to NATIVE. However, the Objects we wrote could then only be read back by other programs that use AST. In practice, we will also encounter FITS headers containing WCS information written by other software systems. We will probably also need to write FITS headers in a format that can be understood by these systems. Indeed, this interchange of data is one of the main reasons for the existence of FITS, so in this section we will examine how to accommodate these requirements. \subsection{\label{ss:foreignencodings}The Foreign FITS Encodings} As mentioned previously (\secref{ss:nativeencoding}), there are a number of conventions currently in use for storing WCS information in FITS headers, which we call \emph{encodings}. Here, we are concerned with those encodings defined by software systems other than AST, which we term \emph{foreign encodings}. Currently, AST supports six foreign encodings, which may be selected by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the following (character string) values: \begin{quote} \begin{description} \item[DSS]\mbox{}\\ This encoding stores WCS information using the convention developed at the Space Telescope Science Institute for the Digitised Sky Survey (DSS) astrometric plate calibrations. DSS images which use this convention are widely available and it is understood by a number of important and well-established astronomy applications. However, the calibration model used (based on a polynomial fit) is not easily applicable to other types of data and creating the polynomial coefficients needed to calibrate your own images can prove difficult. For this reason, the DSS encoding is probably best viewed as a ``read-only'' format. It is possible, however, to read in WCS information using this encoding and then to write it back out again, so long as only minor changes have been made. \item[FITS-WCS]\mbox{}\\ This encoding is very important because it is based on a new FITS standard which should, for the first time, address the problem of celestial coordinate systems in a proper manner, by considerably extending the original FITS standard. The conventions used are described in a series of papers by E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the ``FITS-WCS papers''. They are described at \url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers in this series have been agreed, this encoding should be understood by any FITS-WCS compliant software and it is likely to be adopted widely for FITS data in future. For details of the coverage of these conventions provided by the FitsChan class, see \appref{ss:fitswcscoverage}. \item[FITS-IRAF]\mbox{}\\ This encoding is based on the conventions described in the document ``World Coordinate Systems Representations Within the FITS Format'' by R.J. Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. This encoding is in effect a sub-set of the current FITS-WCS encoding. \item[FITS-PC]\mbox{}\\ This encoding is based on a previous version of the proposed new FITS WCS standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe axis rotation and scaling. Versions of AST prior to V1.5 used this scheme for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j} keywords instead.\footnote{There are many other differences between the previous and the current FITS-WCS encodings. The keywords to describe axis rotation and scaling is used purely as a label to identify the scheme.} The FITS-PC encoding is included in AST V1.5 only to allow FITS-WCS data created with previous versions to be read. It should not, in general, be used to create new data sets. \item[FITS-AIPS]\mbox{}\\ This encoding is based on the conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS data analysis facility, so its use will facilitate data exchange with AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to describe axis rotation and scaling. \item[FITS-AIPS++]\mbox{}\\ Encodes coordinate system information in FITS header cards using the conventions used by the AIPS++ project. This is an extension of FITS-AIPS which includes some of the features of FITS-PC and FITS-IRAF. \end{description} \end{quote} For more detail about the above encodings, see the description of the Encoding attribute in \appref{ss:attributedescriptions}. \subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings} The foreign encodings available for storing WCS information in FITS headers have a number of limitations when compared with the native encoding of AST Objects (\secref{ss:nativefits}). The main ones are: \begin{enumerate} \item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented using a foreign FITS encoding. This should not come as a surprise, because the purpose of storing WCS information in FITS headers is to attach coordinate systems to an associated array of data. Since the FrameSet is the AST Object designed for the same purpose (\secref{ss:baseandcurrent}), there is a natural correspondence. The way in which a FrameSet is translated to and from the foreign encoding also follows from this correspondence. The FrameSet's base \htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS data. These are the same as FITS pixel coordinates, in which the first pixel (in 2 dimensions) has coordinates (1,1) at its centre. Similarly, the current Frame of the FrameSet identifies the FITS world coordinate system associated with the data. \item You may store a representation of only a single FrameSet in any individual set of FITS header cards (\emph{i.e.}\ in a single \htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may over-write the previous one or generate an invalid representation of your WCS information. This is mainly a consequence of the use of fixed FITS keywords by foreign encodings and the fact that you cannot, in general, have multiple FITS cards with the same keyword. \item In general, it will not be possible to store every possible FrameSet that you might construct. Depending on the encoding, only certain FrameSets that conform to particular restrictions can be represented and, even then, some of their information may be lost. See the description of the \htmlref{Encoding}{Encoding} attribute in \appref{ss:attributedescriptions} for more details of these limitations. \end{enumerate} It should be understood that using foreign encodings to read and write information held in AST Objects is essentially a process of converting the data format. As such, it potentially suffers from the same problems faced by all such processes, \emph{i.e.}\ differences between the AST data model and that of the foreign encoding may cause some information to be lost. Because the AST model is extremely flexible, however, any data loss can largely be eliminated when reading. Instead, this effect manifests itself in the form of the above encoding-dependent restrictions on the kind of AST Objects which may be written. One of the aims of the AST library, of course, is to insulate you from the details of these foreign encodings and the restrictions they impose. We will see shortly, therefore, how AST provides a mechanism for determining whether your WCS information satisfies the necessary conditions and allows you to make an automatic choice of which encoding to use. \subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input} Let us now examine the practicalities of extracting WCS information from a set of FITS header cards which have been written by some other software system. We will pretend that our program does not know which encoding has been used for the WCS information and must discover this for itself. In order to have a concrete example, however, we will use the following set of cards. These use the FITS-AIPS encoding and contain a typical mix of other FITS cards which are irrelevant to the WCS information in which we are interested: \small \begin{terminalv} SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 BITPIX = -32 / Bits per pixel. NAXIS = 2 / Number of dimensions NAXIS1 = 300 / Length of x axis. NAXIS2 = 300 / Length of y axis. CTYPE1 = 'GLON-ZEA' / X-axis type CTYPE2 = 'GLAT-ZEA' / Y-axis type CRVAL1 = -149.56866 / Reference pixel value CRVAL2 = -19.758201 / Reference pixel value CRPIX1 = 150.500 / Reference pixel CRPIX2 = 150.500 / Reference pixel CDELT1 = -1.20000 / Degrees/pixel CDELT2 = 1.20000 / Degrees/pixel CROTA1 = 0.00000 / Rotation in degrees. SURVEY = 'COBE DIRBE' BUNITS = 'MJy/sr ' / ORIGIN = 'CDAC ' / Cosmology Data Analysis Center TELESCOP= 'COBE ' / COsmic Background Explorer satellite INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] PIXRESOL= 9 / Quad tree pixel resolution [6, 9] DATE = '27/09/94' / FITS file creation date (dd/mm/yy) DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) COMMENT COBE specific keywords DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) \end{terminalv} \normalsize The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into it. If ``cards'' is an array of pointers to character strings holding the header cards and ``ncards'' is the number of cards, this could be done as follows: \small \begin{terminalv} #include "ast.h" #define MAXCARD 100 AstFitsChan *fitschan; char *cards[ MAXCARD ]; int icard, ncard; ... fitschan = astFitsChan( NULL, NULL, "" ); for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); \end{terminalv} \normalsize Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to use the native encoding. This is because we are pretending not to know which encoding to use and want AST to determine this for us. By leaving the Encoding attribute un-set, its default value will adjust to whichever encoding AST considers to be most appropriate, according to the FITS header cards present. For details of how this choice is made, see the description of the Encoding attribute in \appref{ss:attributedescriptions}. This approach has the obvious advantages of making our program simpler and more flexible and of freeing us from having to know about the different encodings available. As a bonus, it also means that the program will be able to read any new encodings that AST may support in future, without needing to be changed. At this point, we could enquire the default value of the Encoding attribute, which indicates which encoding AST intends to use, as follows: \small \begin{terminalv} const char *encode; ... encode = astGetC( fitschan, "Encoding" ); \end{terminalv} \normalsize The result of this enquiry would be the string ``FITS-AIPS''. Note that we could also have set the FitsChan's Encoding attribute explicitly, such as when creating it: \small \begin{terminalv} fitschan = astFitsChan( NULL, NULL, "Encoding=FITS-AIPS" ); \end{terminalv} \normalsize If we tried to read information using this encoding (\secref{ss:readingforeignfits}), but failed, we could then change the encoding and try again. This would allow our program to take control of how the optimum choice of encoding is arrived at. However, it would also involve using explicit knowledge of the encodings available and this is best avoided if possible. \subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header} Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined how the WCS information is encoded (\secref{ss:identifyingfitsencoding}), the next step is to read an AST \htmlref{Object}{Object} from the FitsChan using \htmlref{astRead}{astRead}. We must also remember to rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card} attribute, which defaults to 1: \small \begin{terminalv} AstObject *wcsinfo; ... astClear( fitschan, "Card" ); wcsinfo = astRead( fitschan ); \end{terminalv} \normalsize If the pointer returned by astRead is not equal to AST\_\_NULL, then an Object has been read successfully. Otherwise, there was either no information to read or the choice of FITS encoding (\secref{ss:identifyingfitsencoding}) was inappropriate. At this point you might like to indulge in a little data validation along the lines described in \secref{ss:validatinginput}, for example: \small \begin{terminalv} if ( !strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { } else { } \end{terminalv} \normalsize If a foreign encoding has definitely been used, then the Object will automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so this stage can be omitted. However, if the native encoding (\secref{ss:nativeencoding}) might have been employed, which is a possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then any class of Object might have been read and a quick check would be worthwhile. If you used \htmlref{astShow}{astShow} (\secref{ss:displayingobjects}) to examine the FrameSet which results from reading our example FITS header (\secref{ss:identifyingfitsencoding}), you would find that its base \htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which incorporates the effects of various rotations, scalings and a ``zenithal equal area'' sky projection, so that each pixel of the FITS image is mapped on to a corresponding sky position in galactic coordinates. Because this FrameSet may be used both as a Mapping (\secref{ss:framesetasmapping}) and as a Frame (\secref{ss:framesetasframe}), it may be employed directly to perform many useful operations without any need to decompose it into its component parts. These include: \begin{itemize} \item Transforming data grid (FITS pixel) coordinates into galactic coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}). \item Formatting coordinate values (either pixel or galactic coordinates) ready for display to a user (\secref{ss:formattingaxisvalues} and \secref{ss:normalising}). \item Enquiring about axis labels (or other axis information---\secref{ss:frameattributes}) which might be used, for example, to label columns of coordinates in a table (\secref{ss:frameaxisattributes}). \item Aligning the image with another image from which a similar FrameSet has been obtained (\secref{ss:registeringimages}). \item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay a variety of graphical information (including a coordinate grid---Figure~\ref{fig:gridplot}) on the displayed image. \item Generating a new FrameSet which reflects any geometrical processing you perform on the associated image data (\secref{ss:wcsprocessingexample}). This new FrameSet could then be written out as FITS headers to describe the modified image (\secref{ss:writingforeignfits}). \end{itemize} If the FrameSet contains other Frames (apart from the base and current Frames), then you would also have access to information about other coordinate systems associated with the image. \subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read} It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan} after we have read a \htmlref{FrameSet}{FrameSet} from it (\secref{ss:readingforeignfits}). The following would rewind our FitsChan and display its contents: \small \begin{terminalv} #include char card[ 81 ]; ... astClear( fitschan, "Card" ); while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); \end{terminalv} \normalsize The output, if we started with the example FITS header in \secref{ss:identifyingfitsencoding}, might look like this: \small \begin{terminalv} SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 BITPIX = -32 / Bits per pixel. NAXIS = 2 / Number of dimensions NAXIS1 = 300 / Length of x axis. NAXIS2 = 300 / Length of y axis. SURVEY = 'COBE DIRBE' BUNITS = 'MJy/sr ' ORIGIN = 'CDAC ' / Cosmology Data Analysis Center TELESCOP= 'COBE ' / COsmic Background Explorer satellite INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] PIXRESOL= 9 / Quad tree pixel resolution [6, 9] DATE = '27/09/94' / FITS file creation date (dd/mm/yy) DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) COMMENT COBE specific keywords DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) \end{terminalv} \normalsize Comparing this with the original, you can see that all the FITS cards that represent WCS information have been removed. They have effectively been ``sucked out'' of the FitsChan by the destructive read that \htmlref{astRead}{astRead} performs and converted into an equivalent FrameSet. AST remembers where they were stored, however, so that if we later write WCS information back into the FitsChan (\secref{ss:writingforeignfits}) they will, as far as possible, go back into their original locations. This helps to preserve the overall layout of the FITS header. You can now see why astRead performs destructive reads. It is a mechanism for removing WCS information from a FITS header while insulating you, as a programmer, from the details of the encoding being used. It means you can ensure that all relevant header cards have been removed, giving you a clean slate, without having to know which FITS keywords any particular encoding uses. Clearing this WCS information out of a FITS header is particularly important when considering how to write new WCS information back after processing (\secref{ss:writingforeignfits}). If any relevant FITS cards are left over from the input dataset and find their way into the new processed header, they could interfere with the new information being written.\footnote{This can happen if a particular keyword is present in the input header but is not used in the output header (whether particular keywords are used can depend on the WCS information being stored). In such a case, the original value would not be over-written by a new output value, so would remain erroneously present.} The destructive read mechanism ensures that this doesn't happen. \subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps} One of the purposes of AST is to make it feasible to propagate WCS information through successive stages of data processing, so that it remains consistent with the associated image data. As far as possible, this should happen regardless of the FITS encoding used to store the original WCS information. If the data processing being performed does not change the relationship between image pixel and world coordinates (whatever these may be), then propagation of the WCS information is straightforward. You can simply copy the FITS header from input to output. If this relationship changes, however, then the WCS information must be processed alongside the image data and a new FITS header generated to represent it. In this case, the sequence of operations within your program would probably be as follows: \begin{enumerate} \item Read the image data and associated FITS header from the input dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan} (\secref{ss:identifyingfitsencoding}). \item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically using a foreign FITS encoding---\secref{ss:readingforeignfits}). \item Process the image data and modify the FrameSet accordingly (\emph{e.g.}~\secref{ss:wcsprocessingexample}). \item Write the FrameSet back into the FitsChan (\secref{ss:writingforeignfits}). \item Perform any other modification of FITS header cards your program may require. \item Write the FitsChan contents (\emph{i.e.}\ processed header cards) and image data to the output dataset. \end{enumerate} In stage (2), the original WCS information will be removed from the FitsChan by a destructive read. Later, in stage (4), new WCS information is written to replace it. This is the process which we consider next (\secref{ss:writingforeignfits}). \subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header} Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS encoding to use. Unfortunately, we cannot simply depend on the default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the input information (\secref{ss:identifyingfitsencoding}), because the destructive action of reading the WCS data (\secref{ss:destructiveread}) will have altered the FitsChan's contents. This, in turn, will have changed the choice of default encoding, probably causing it to revert to NATIVE. We will return to the question of the optimum choice of encoding below. For now, let's assume that we want to use the same encoding for output as we used for input. Since we enquired what that was before we read the input WCS data from the FitsChan (\secref{ss:identifyingfitsencoding}), we can now set that value explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at the same time (because the write will fail if the FitsChan is not rewound). \htmlref{astWrite}{astWrite} can then be used to write the output WCS information into the FitsChan: \small \begin{terminalv} int nobj; ... astSet( fitschan, "Card=1, Encoding=%s", encode ); nobj = astWrite( fitschan, wcsinfo ); \end{terminalv} \normalsize The value returned by astWrite (assigned to ``nobj'') indicates how many Objects were written. This will either be 1 or zero. A value of zero is used to indicate that the information could not be encoded in the form you requested. If this happens, nothing will have been written. If your choice of encoding proves inadequate, the probable reason is that the changes you have made to the FrameSet have caused it to depart from the data model which the encoding assumes. AST knows about the data model used by each encoding and will attempt to simplify the FrameSet you provide so as to fit into that model, thus relieving you of the need to understand the details and limitations of each encoding yourself.\footnote{Storing values in the FitsChan for FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels), before invoking astWrite can sometimes help to produce a successful write.} When this attempt fails, however, you must consider what alternative encoding to use. Ideally, you would probably want to try a sequence of alternative encodings, using an approach such as the following: \small \begin{terminalv} /* 1. */ astSet( fitschan, "Card=1, Encoding=FITS-IRAF" ); if ( !astWrite( fitschan, wcsinfo ) ) { /* 2. */ astSetC( fitschan, "Encoding", encode ); if ( !astWrite( fitschan, wcsinfo ) ) { /* 3. */ astSet( fitschan, "Encoding=NATIVE" ); (void) astWrite( fitschan, wcsinfo ); } } \end{terminalv} \normalsize That is: \begin{enumerate} \item Start by trying the FITS-WCS encoding, on the grounds that FITS should provide a universal interchange standard in which all WCS information should be expressed if possible. \item If that fails, then try the original encoding used for the input WCS information, on the grounds that you are at least not making the information any harder for others to read than it originally was. \item If that also fails, then you are probably trying to store fairly complex information for which you need the native encoding. Only other AST programs will then be able to read this information, but these are probably the only programs that will be able to do anything sensible with it anyway. \end{enumerate} An alternative approach might be to encode the WCS information in several ways, since this gives the maximum chance that other software will be able to read it. This approach is only possible if there is no significant conflict between the FITS keywords used by the different encodings\footnote{In practice, this means you should avoid mixing FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share many keywords.}. Adopting this approach would simply require multiple calls to astWrite, rewinding the FitsChan and changing its Encoding value before each one. Unfortunately, however, there is a drawback to duplicating WCS information in the FITS header in this way, because any program which modifies one version of this information and simply copies the remainder of the header will risk producing two inconsistent sets of information. This could obviously be confusing to subsequent software. Whether you consider this a worthwhile risk probably depends on the use to which you expect your data to be put. \cleardoublepage \section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)} \htmladdnormallinkfoot{XML}{http://www.w3.org/XML/} is fast becoming the standard format for passing structured data around the internet, and much general purpose software has been written for tasks such as the parsing, editing, display and transformation of XML data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides facilities for storing AST objects externally in the form of XML documents, thus allowing such software to be used. The primary XML format used by the XmlChan class is a fairly close transliteration of the AST native format produced by the basic Channel class. Currently, there is no DTD or schema defining the structure of data produced in this format by an XmlChan. The following is a native AST representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full} attribute set to zero so that some default attribute values are included as extra comments): \small \begin{terminalv} Begin Frame # Coordinate system description # Title = "1-d coordinate system" # Title of coordinate system Naxes = 1 # Number of coordinate axes Domain = "SCREEN" # Coordinate system domain # Lbl1 = "Axis 1" # Label for axis 1 # Uni1 = "cm" # Units for axis 1 Ax1 = # Axis number 1 Begin Axis # Coordinate axis Unit = "cm" # Axis units End Axis End Frame \end{terminalv} \normalsize The corresponding XmlChan output would look like: \small \begin{terminalv} <_attribute name="Title" quoted="true" value="1-d coordinate system" desc="Title of coordinate system" default="true"/> <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/> <_attribute name="Domain" quoted="true" value="SCREEN" desc="Coordinate system domain"/> <_attribute name="Lbl1" quoted="true" value="Axis 1" desc="Label for axis 1" default="true"/> <_attribute name="Uni1" quoted="true" value="cm" desc="Units for axis 1" default="true"/> <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/> \end{terminalv} \normalsize Notes: \begin{enumerate} \item The AST class name is used as the name for an XML element which contain a description of an AST object. \item AST attributes are described by XML elements with the name ``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML to refer to a ``name=value'' pair within an element start tag. So for instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described within an XML element with name ``\_attribute'' in which the XML attribute ``name'' has the value ``Title'', and the XML attribute ``value'' has the value ``1-d coordinate system''. The moral is always to be clear clear about the context (AST or XML) in which the word \emph{attribute} is being used! \item The XML includes comments both as XML attributes with the name ``desc'', and as separate comment tags. \item Elements which describe default values are identified by the fact that they have an XML attribute called ``default'' set to the value ``true''. These elements are ignored when being read back into an XmlChan. \item The outer-most XML element of an AST object will set the default namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be inherited by all nested elements. \end{enumerate} The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full attributes (inherited from the base Channel class) to zero and -1, resulting in terse output by default. With the default values for these attributes, the above XML is reduced to the following: \small \begin{terminalv} <_attribute name="Naxes" value="1"/> <_attribute name="Domain" quoted="true" value="SCREEN"/> <_attribute name="Unit" quoted="true" value="cm"/> \end{terminalv} \normalsize The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel class. If Skip is zero (the default) then an error will be reported if the text supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If Skip is non-zero, then initial text is skipped over without error until the start of an AST object is found. this allows an AST object to be located within a larger XML document. \subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions} The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML documents which use a restricted subset of an early draft (V1.20) of the IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, and so the STC-X support currently provided by AST is mainly of historical interest. Note, AST also supports the alternative ``STC-S'' linear string description of the STC model (see \secref{ss:stcschans}). STC-X V1.20 is documented at \url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current version is documented at \url{http://www.ivoa.net/Documents/latest/STC-X.html}. When an STC-X document is read using an XmlChan, the read operation produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of \htmlref{Region}{Region}. Specifically, each such Object will be an instance of \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or \htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the \htmlref{XmlFormat}{XmlFormat} attribute for further details. \cleardoublepage \section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)} The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing IVOA ``STC-S'' descriptions. STC-S (see \url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string syntax that allows simple specification of the STC metadata describing a region in an astronomical coordinate system. AST supports a subset of the STC-S specification, allowing an STC-S description of a region within an AST-supported astronomical coordinate system to be converted into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further details, see the full description of the StcsChan class in \appref{ss:classdescriptions}. \cleardoublepage \section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)} \subsection{The Need for Extensibility} However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you will want to transform coordinates in some way that has not been foreseen. You might want to plot a graph in some novel curvilinear coordinate system (perhaps you already have a WCS system in your software and just want to use AST for its graphical capabilities). Alternatively, you might need to calibrate a complex dataset (like an objective prism plate) where each position must be converted to world coordinates with reference to calibration data under the control of an elaborate algorithm. In such cases, it is clear that the basic pre-formed components provided by AST for building Mappings are just not enough. What you need is access to a programming language. However, if you write your own software to transform coordinate values, then it must be made available in the form of an AST class (from which you can create Objects) before it can be used in conjunction with other AST facilities. At this point you might consider writing your own AST class, but this is not recommended. Not only would the internal conventions used by AST take some time to master, but you might also find yourself having to change your software whenever a new version of AST was released. Fortunately, there is a much easier route provided by the \htmlref{IntraMap}{IntraMap} class. \subsection{The IntraMap Model} To allow you to write your own Mappings, AST provides a special kind of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper'' for a coordinate transformation function written in C. You write this function yourself and then register it with AST. This, in effect, creates a new class from which you can create Mappings (\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever way your transformation function specifies. Because IntraMaps are Mappings, they may be used in the same way as any other Mapping. For instance, they may be combined in series or parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}), they may be inverted (\secref{ss:invertingmappings}), you may enquire about their attributes (\secref{ss:gettingattributes}), they may be inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do, however, have some important limitations of which you should be aware before we go on to consider how to create them. \subsection{\label{ss:intramaplimitations}Limitations of IntraMaps} By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is required at all. After all, why not simply write your own coordinate transformation functions in C, wrap them up in IntraMaps and do away with all the other Mapping classes in AST? The reason is not too hard to find. Any transformation function you write is created solely by you, so it is a private extension which does not form a permanent part of AST. If you use it to calibrate some data and then pass that data to someone else, who has only the standard version of AST, then they will not be able to interpret it. Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators (who we assume have access to the same transformation functions), it does not address the need for universal data exchange like other AST Mappings do. This is where the ``Intra'' in the class name ``IntraMap'' comes from, implying private or internal usage. For this reason, it is unwise to store IntraMaps in datasets, unless they will be used solely for communication between collaborating items of software which share conventions about their use. A private database describing coordinate systems on a graphics device might be an example where IntraMaps would be suitable, because the data would probably never be accessed by anyone else's software. Restricting IntraMap usage to within a single program (\emph{i.e.} never writing it out) is, of course, completely safe. If, by accident, an IntraMap should happen to escape as part of a dataset, then the unsuspecting recipient is likely to receive an error message when they attempt to read the data. However, AST will associate details of the IntraMap's transformation function and its author (if provided) with the data, so that the recipient can make an intelligent enquiry to obtain the necessary software if this proves essential. \subsection{\label{ss:transformationfunctions}Writing a Transformation Function} The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate transformation function. This should have a calling interface like the \htmlref{astTranP}{astTranP} function provided by AST (\emph{q.v.}). Here is a simple example of a suitable transformation function which transforms coordinates by squaring them: \xlabel{SqrTran} \small \begin{terminalv} #include "ast.h" #include void SqrTran( AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[] ) { int point, coord; double x; /* Forward transformation. */ if ( forward ) { for ( point = 0; point < npoint; point++ ) { for ( coord = 0; coord < ncoord_in; coord++ ) { x = ptr_in[ coord ][ point ]; ptr_out[ coord ][ point ] = ( x == AST__BAD ) ? AST__BAD : x * x; } } /* Inverse transformation. */ } else { for ( point = 0; point < npoint; point++ ) { for ( coord = 0; coord < ncoord_in; coord++ ) { x = ptr_in[ coord ][ point ]; ptr_out[ coord ][ point ] = ( x < 0.0 || x == AST__BAD ) ? AST__BAD : sqrt( x ); } } } } \end{terminalv} \normalsize As you can see, the function comes in two halves which implement the forward and inverse coordinate transformations. The number of points to be transformed (``npoint'') and the numbers of input and output coordinates per point (``ncoord\_in'' and ``ncoord\_out''---in this case both are assumed equal) are passed to the function. A pair of loops then accesses all the coordinate values. Note that it is legitimate to omit one or other of the forward/inverse transformations and simply not to implement it, if it will not be required. It is also permissible to require that the numbers of input and output coordinates be fixed (\emph{e.g.}\ at 2), or to write the function so that it can handle arbitrary dimensionality, as here. Before using an incoming coordinate, the function must first check that it is not set to the value AST\_\_BAD, which indicates missing data (\secref{ss:badcoordinates}). If it is, the same value is also assigned to any affected output coordinates. The value AST\_\_BAD is also generated if any coordinates cannot be transformed. In this example, this can happen with the inverse transformation if negative values are encountered, so that the square root cannot be taken. There are very few restrictions on what a coordinate transformation function may do. For example, it may freely perform I/O to access any external data needed, it may invoke other AST facilities (but beware of unwanted recursion), \emph{etc.} Typically, you may also want to pass information to it \emph{via}\ global variables. Remember, however, that whatever facilities the transformation function requires must be available in every program which uses it. Generally, it is not a good idea to retain context information within a transformation function. That is, it should transform each set of coordinates as a single point and retain no memory of the points it has transformed before. This is in order to conform with the AST model of a \htmlref{Mapping}{Mapping}. If an error occurs within a transformation function, it should use the \htmlref{astSetStatus}{astSetStatus} function (\secref{ss:errordetection}) to set the AST status to an error value before returning. This will alert AST to the error, causing it to abort the current operation. The error value AST\_\_ITFER is available for this purpose, but other values may also be used (\emph{e.g.}\ if you wish to distinguish different types of error). \subsection{\label{ss:registeringintramaps}Registering a Transformation Function} Having written your coordinate transformation function, the next step is to register it with AST. Registration is performed using \htmlref{astIntraReg}{astIntraReg}, as follows: \small \begin{terminalv} void SqrTran( AstMapping *, int, int, const double *[], int, int, double *[] ); const char *author, *contact, *purpose; ... purpose = "Square each coordinate value"; author = "R.F. Warren-Smith & D.S. Berry"; contact = "http://www.starlink.ac.uk/cgi-bin/htxserver/sun211.htx/?xref_SqrTran"; astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact ); \end{terminalv} \normalsize Note that you should also provide a function prototype to describe the transformation function (the implementation of the function itself would suffice, of course). The first argument to astIntraReg is a name by which the transformation function will be known. This will be used when we come to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you use the actual function name here and make this sufficiently unusual that it is unlikely to clash with any other functions in most people's software. The next two arguments specify the number of input and output coordinates which the transformation function will handle. These correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will create. Here, we have set them both to 2, which means that we will only be able to create IntraMaps with 2 input and 2 output coordinates (despite the fact that the transformation function can actually handle other dimensionalities). We will see later (\secref{ss:variableintramapcoordinates}) how to remove this restriction. The fourth argument should contain a set of flags which describe the transformation function in a little more detail. We will return to this shortly (\secref{ss:restrictedintramaps} \& \secref{ss:simplifyingintramaps}). For now, we supply a value of zero. The remaining arguments are character strings which document the transformation function, mainly for the benefit of anyone who is unfortunate enough to encounter a reference to it in their data which they cannot interpret. As explained above (\secref{ss:intramaplimitations}), you should try and avoid this, but accidents will happen, so you should always provide strings containing the following: \begin{enumerate} \item A short description of what the transformation function is for. \item The name of the author. \item Contact details, such as an e-mail or WWW address. \end{enumerate} The idea is that anyone finding an IntraMap in their data, but lacking the necessary transformation function, should be able to contact the author and make a sensible enquiry in order to obtain it. If you expect many enquiries, you may like to set up a World Wide Web page and use that instead (in the example above, we use the WWW address of the relevant part of this document). \subsection{Creating an IntraMap} Once a transformation function has been registered, creating an \htmlref{IntraMap}{IntraMap} from it is simple: \small \begin{terminalv} AstIntraMap *intramap; ... intramap = astIntraMap( "SqrTran", 2, 2, "" ); \end{terminalv} \normalsize We simply use the \htmlref{astIntraMap}{astIntraMap} constructor function and pass it the name of the transformation function to use. This name is the same (case sensitive) one that we associated with the function when we registered it using \htmlref{astIntraReg}{astIntraReg} (\secref{ss:registeringintramaps}). You can, of course, register any number of transformation functions and select which one to use whenever you create an IntraMap. You can also create any number of independent IntraMaps using each transformation function. In this sense, each transformation function you register effectively creates a new ``sub-class'' of IntraMap, from which you can create Objects just like any other class. However, an error will occur if you attempt to use a transformation function that has not yet been registered. The second and third arguments to astIntraMap are the numbers of input and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for the IntraMap that is created and they must match the corresponding numbers given when the transformation function was registered. The final argument is the usual attribute initialisation string. You may set attribute values for an IntraMap in exactly the same way as for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see \secref{ss:intraflag}). \subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Functions} You may not always want to use both the forward and inverse transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit either from the underlying coordinate transformation function. Consider the following, for example: \small \begin{terminalv} void Poly3Tran( AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[] ) { double x; int point; /* Forward transformation. */ for ( point = 0; point < npoint; point++ ) { x = ptr_in[ 0 ][ point ]; ptr_out[ 0 ][ point ] = ( x == AST__BAD ) ? AST__BAD : 6.18 + x * ( 0.12 + x * ( -0.003 + x * 0.0000101 ) ); } } \end{terminalv} \normalsize This implements a 1-dimensional cubic polynomial transformation. Since this is somewhat awkward to invert, however, we have only implemented the forward transformation. When registering the function, this is indicated via the ``flags'' argument to \htmlref{astIntraReg}{astIntraReg}, as follows: \small \begin{terminalv} void Poly3Tran( AstMapping *, int, int, const double *[], int, int, double *[] ); ... astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, purpose, author, contact ); \end{terminalv} \normalsize Here, the fifth argument has been set to the flag value AST\_\_NOINV to indicate the lack of an inverse. If the forward transformation were absent, we would use AST\_\_NOFOR instead. Flag values for this argument may be combined using a bitwise OR if necessary. \subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates} In our earlier examples, we have used a fixed number of input and output coordinates when registering a coordinate transformation function. It is not necessary to impose this restriction, however, if the transformation function can cope with a variable number of coordinates (as with the example in \secref{ss:transformationfunctions}). We indicate the acceptability of a variable number when registering the transformation function by supplying the value AST\_\_ANY for the number of input and/or output coordinates, as follows: \small \begin{terminalv} astIntraReg( "SqrTran", AST__ANY, AST__ANY, SqrTran, 0, purpose, author, contact ); \end{terminalv} \normalsize The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of input and output coordinates. For example: \small \begin{terminalv} AstIntraMap *intramap1, *intramap2; ... intramap1 = astIntraMap( "SqrTran", 1, 1, "" ); intramap2 = astIntraMap( "SqrTran", 3, 3, "Invert=1" ); \end{terminalv} \normalsize It is possible to fix either the number of input or output coordinates (by supplying an explicit number to \htmlref{astIntraReg}{astIntraReg}), but more subtle restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} be equal, are not supported. This means that: \small \begin{terminalv} intramap = astIntraMap( "SqrTran", 1, 2, "" ); \end{terminalv} \normalsize will be accepted without error, although the transformation function cannot actually handle such a combination sensibly. If this is important, it would be worth adding a check within the transformation function itself, so that the error would be detected when it came to be used. \subsection{\label{ss:intraflag}Adapting a Transformation Function to Individual IntraMaps} In the examples given so far, our coordinate transformation functions have not made use of the ``this'' pointer passed to them (which identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In practice, this will often be the case. However, the presence of the ``this'' pointer allows the transformation function to invoke any other AST function on the IntraMap, and this permits enquiries about its attributes. The transformation function's behaviour can therefore be modified according to any attribute values which are set. This turns out to be a useful thing to do, so each IntraMap has a special \htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose. Consider, for instance, the case where the transformation function has access to several alternative sets of internally-stored data which it may apply to perform its transformation. Rather than implement many different versions of the transformation function, you may switch between them by setting a value for the IntraFlag attribute when you create an instance of an IntraMap, for example: \small \begin{terminalv} intramap1 = astIntraMap( "MyTran", 2, 2, "IntraFlag=A" ); intramap2 = astIntraMap( "MyTran", 2, 2, "IntraFlag=B" ); \end{terminalv} \normalsize The transformation function may then enquire the value of the IntraFlag attribute (\emph{e.g.}\ using astGetC and passing it the ``this'' pointer) and use whichever dataset is required for that particular IntraMap. This approach is particularly useful when the number of possible transformations is unbounded or not known in advance, in which case the IntraFlag attribute may be used to hold numerical values encoded as part of a character string (effectively using them as data for the IntraMap). It is also superior to the use of a global switch for communication (\emph{e.g.}\ setting an index to select the ``current'' data before using the IntraMap), because it continues to work when several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping}, when you may have no control over the order in which they are used. \subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps} A notable disadvantage of IntraMaps is that they are ``black boxes'' as far as AST is concerned. This means that they have limited ability to participate in the simplification of compound Mappings performed, \emph{e.g.}, by \htmlref{astSimplify}{astSimplify} (\secref{ss:simplifyingcmpmaps}), because AST cannot know how they interact with other Mappings. In reality, of course, they will often implement such specialised coordinate transformations that the simplification possibilities will be rather limited anyway. One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This is important because Mappings are frequently used to relate a dataset to some external standard (a celestial coordinate system, for example). When inter-relating two similar datasets calibrated using the same standard, part of the Mapping often cancels, because it is applied first in one direction and then the other, effectively eliminating the reference to the standard. This is often a useful simplification and can lead to greater efficiency. Many transformations have this property of cancelling with their own inverse, but not necessarily all. Consider the following transformation function, for example: \small \begin{terminalv} void MaxTran( AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[] ) { double hi, x; int coord, point; /* Forward transformation. */ if ( forward ) { for ( point = 0; point < npoint; point++ ) { hi = AST__BAD; for ( coord = 0; coord < ncoord_in; coord++ ) { x = ptr_in[ coord ][ point ]; if ( x != AST__BAD ) { if ( x > hi || hi == AST__BAD ) hi = x; } } ptr_out[ 0 ][ point ] = hi; } /* Inverse transformation. */ } else { for ( coord = 0; coord < ncoord_out; coord++ ) { for ( point = 0; point < npoint; point++ ) { ptr_out[ coord ][ point ] = ptr_in[ 0 ][ point ]; } } } } \end{terminalv} \normalsize This function takes any number of input coordinates and returns a single output coordinate which is the maximum value of the input coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the input coordinates to the value of the output coordinate.\footnote{Remember that ``ptr\_in'' identifies the original ``output'' coordinates when applying the inverse transformation and ``ptr\_out'' identifies the original ``input'' coordinates.} If this function is applied in the forward direction and then in the inverse direction, it does \textbf{not} in general restore the original coordinate values. However, if applied in the inverse direction and then the forward direction, it does. Hence, replacing the sequence of operations with an equivalent UnitMap is possible in the latter case, but not in the former. To distinguish these possibilities, two flag values are provided for use with \htmlref{astIntraReg}{astIntraReg} to indicate what simplification (if any) is possible. For example, to register the above transformation function, we might use: \small \begin{terminalv} void MaxTran( AstMapping *, int, int, const double *[], int, int, double *[] ); ... astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, purpose, author, contact ); \end{terminalv} \normalsize Here, the flag value AST\_\_SIMPIF supplied for the fifth argument indicates that simplification is possible if the transformation is applied in the inverse direction followed by the forward direction. To indicate the complementary case, the flag AST\_\_SIMPFI would be used instead. If both simplifications are possible (as with the SqrTran function in \secref{ss:transformationfunctions}), then we would use the bitwise OR of both values. In practice, some judgement is usually necessary when deciding whether to allow simplification. For example, seen in one light our SqrTran function (\secref{ss:transformationfunctions}) does not cancel with its own inverse, because squaring a coordinate value and then taking its square root can change the original value, if this was negative. Therefore, replacing this combination with a UnitMap will change the behaviour of a compound Mapping and should not be allowed. Seen in another light, however, where the coordinates being processed are intrinsically all positive, it is a permissible and probably useful simplification. If such distinctions are ever important in practice, it is simple to register the same transformation function twice with different flag values (use a separate name for each) and then use whichever is appropriate when creating an \htmlref{IntraMap}{IntraMap}. \subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps} It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a \htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation function which it uses is not stored with it. To do so is impossible, because the function has been compiled and loaded into memory ready for execution before AST gets to see it. However, AST does store the name associated with the transformation function and various details about the IntraMap itself. This means that any program attempting to read the IntraMap (\secref{ss:readingfromachannel}) cannot make use of it unless it also has independent access to the original transformation function. If it does not have access to this function, an error will occur at the point where the IntraMap is read and the associated error message will direct the user to the author of the transformation function for more information. However, if the necessary transformation function is available, and has been registered before the read operation takes place, then AST is able to re-create the original IntraMap and will do so. Registration of the transformation function must, of course, use the same name (and, in fact, be identical in most particulars) as was used in the original program which wrote the data. This means that a set of co-operating programs which all have access to the same set of transformation functions and register them in identical fashion (see \secref{ss:intramaplibrary} for how this can best be achieved) can freely exchange data that contain IntraMaps. The need to avoid exporting such data to unsuspecting third parties (\secref{ss:intramaplimitations}) must, however, be re-iterated. \subsection{\label{ss:intramaplibrary}Managing Transformation Functions in Libraries} If you are developing a large suite of data reduction software, you may have a need to use IntraMaps at various points within it. Very probably this will occur in unrelated modules which are compiled separately and then stored in a library. Since the transformation functions required must be registered before they can be used, this makes it difficult to decide where to perform this registration, especially since any particular data reduction program may use an arbitrary subset of the modules in your library. To assist with this problem, AST allows you to perform the same registration of a transformation function any number of times, so long as it is performed using an identical invocation of \htmlref{astIntraReg}{astIntraReg} on each occasion (\emph{i.e.}\ all of its arguments must be identical). This means you do not have to keep track of whether a particular function has already been registered but could, in fact, register it on each occasion immediately before it is required (wherever that may be). In order that all registrations are identical, however, it is recommended that you group them all together into a single function, perhaps as follows: \small \begin{terminalv} void MyTrans( void ) { ... astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, purpose, author, contact ); ... astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, purpose, author, contact ); ... astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact ); } \end{terminalv} \normalsize You can then simply invoke this function wherever necessary. It is, in fact, particularly important to register all relevant transformation functions in this way before you attempt to read an \htmlref{Object}{Object} that might be (or contain) an \htmlref{IntraMap}{IntraMap} (\secref{ss:readingandwritingintramaps}). This is because you may not know in advance which of these transformation functions the IntraMap will use, so they must all be available in order to avoid an error. \cleardoublepage \section{\label{ss:plots}Producing Graphical Output (Plots)} Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot}, which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the graphical content itself, but is a route through which plotting operations, such as drawing lines and curves, are conveyed on to a plotting surface to appear as visible graphics. \subsection{The Plot Model} When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or logarithmically (as specified by the LogPlot attribues) on to a \emph{plotting area}. This is a rectangular region in the graphical coordinate space of the underlying graphics system and becomes the new base Frame of the Plot. In effect, the Plot becomes attached to the plotting surface, in rather the same way that a basic FrameSet might be attached to (say) an image. The current Frame of the Plot (derived from the current Frame of the FrameSet supplied) is used to represent a \emph{physical coordinate system}. This is the system in which plotting operations are performed by your program. Every plotting operation is then transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current and base Frames in order to appear on the plotting surface. An example may help here. Suppose we start with a FrameSet whose base Frame describes the pixel coordinates of an image and whose current Frame describes a celestial (equatorial) coordinate system. Let us assume that these two Frames are inter-related by a Mapping within the FrameSet which represents a particular sky projection. When a Plot is created from this FrameSet, we specify how the pixel coordinates (the base Frame) maps on to the plotting surface. This simply corresponds to telling the Plot where we have previously plotted the image data. If we now use the Plot to plot a line with latitude zero in our physical coordinate system, as given by the current Frame, this line would appear as a curve (the equator) on the plotting surface, correctly registered with the image. There are a number of plotting functions provided, which all work in a similar way. Plotting operations are transformed through the Mapping which the Plot represents before they appear on the plotting surface.\footnote{Like any FrameSet, a Plot can be used as a Mapping. In this case it is the inverse transformation which is used when plotting (\emph{i.e.}\ that which transforms between the current and base Frames).} It is possible to draw symbols, lines, axes, entire grids and more in this way. %\subsection{TBW---Creating a Plot} \subsection{Plotting Symbols} The simplest form of plotting is to draw symbols (termed \emph{markers}) at a set of points. This is performed by \htmlref{astMark}{astMark}, which is supplied with a set of physical coordinates at which to place the markers: \small \begin{terminalv} #include "ast.h" #define NCOORD 2 #define NMARK 10 double in[ NCOORD ][ NMARK ]; int type; ... astMark( plot, NMARK, NCOORD, NMARK, in, type ); \end{terminalv} \normalsize Here, NMARK specifies how many markers to plot and NCOORD specifies how many coordinates are being supplied for each point.\footnote{Remember, the physical coordinate space need not necessarily be 2-dimensional, even if the plotting surface is.} The array ``in'' supplies the coordinates and the integer ``type'' specifies which type of marker to plot. \subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves} There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight line in physical coordinates can potentially turn into a curve in graphical coordinates. We therefore start by considering how to draw geodesic curves. These are curves which trace the path of shortest distance between two points in physical coordinates and are the basic drawing element in a Plot. In many instances, the geodesic will, in fact, be a straight line, but this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a celestial coordinate system, for instance, it will be a great circle (corresponding with the behaviour of the \htmlref{astDistance}{astDistance} function which defines the metric of the physical coordinate space). The geodesic will, of course, be transformed into graphics coordinates before being plotted. A geodesic curve is plotted using \htmlref{astCurve}{astCurve} as follows: \small \begin{terminalv} double start[ NCOORD ], finish[ NCOORD ]; ... astCurve( plot, start, finish ); \end{terminalv} \normalsize Here, ``start'' and ``finish'' are arrays containing the starting and finishing coordinates of the curve. The \htmlref{astOffset}{astOffset} and astDistance functions can often be useful for computing these (\secref{ss:distanceandoffset}). If you need to draw a series of curves end-to-end (when drawing a contour line, for example), then a more efficient alternative is to use \htmlref{astPolyCurve}{astPolyCurve}. This has the same effect as a sequence of invocations of astCurve, but allows you to supply a whole set of points at one time. astPolyCurve then joins them, in sequence, using geodesic curves: \small \begin{terminalv} #define NPOINT 100 double coords[ NCOORD ][ NPOINT ]; ... astPolyCurve( plot, NPOINT, NCOORD, NPOINT, coords ); \end{terminalv} \normalsize Here, NPOINT specifies how many points are to be joined and NCOORD specifies how many coordinates are being supplied for each point. The array ``coords'' supplies the coordinates of the points in the Plot's physical coordinate system. \subsection{Plotting Curves Parallel to Axes} As there is no \htmlref{Plot}{Plot} function to draw a ``straight line'', drawing axes and grid lines to represent coordinate systems requires a slightly different approach. The problem is that for some coordinate systems, these grid lines will not be geodesics, so \htmlref{astCurve}{astCurve} and \htmlref{astPolyCurve}{astPolyCurve} (\secref{ss:plottinggeodesics}) cannot easily be used (you would have to resort to approximating grid lines by many small elements). Lines of constant celestial latitude provide an example of this, with the exception of the equator which is a geodesic. The \htmlref{astGridLine}{astGridLine} function allows these curves to be drawn, as follows: \small \begin{terminalv} int axis; double length; ... astGridLine( plot, axis, start, length ); \end{terminalv} \normalsize Here, ``axis'' specifies which physical coordinate axis we wish to draw parallel to. The ``start'' array contains the coordinates of the start of the curve and ``length'' specifies the distance to draw along the axis in physical coordinate space. \subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves} We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot} class includes another method, \htmlref{astGenCurve}{astGenCurve}, which allows curves of \emph{any} form to be drawn. The caller supplies a \htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the start of the curve is at offset 0.0 and the end of the curve is at offset 1.0 - offset need not be linearly related to distance.} into the corresponding position in the current \htmlref{Frame}{Frame} of the Plot. astGenCurve, then takes care of Mapping these positions into graphics coordinates. The choice of exactly which positions along the curve are to be used to define the curve is also made by astGenCurve, using an adaptive algorithm which concentrates points around areas where the curve is bending sharply or is discontinuous in graphics coordinates. The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows you to code your own Mappings to do any transformation you choose. \subsection{\label{ss:clipping}Clipping} Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics you produce. This means that plotting is restricted to certain regions of the plotting surface so that anything drawn outside these regions will not appear. All Plots automatically clip at the edges of the plotting area specified when the Plot is created. This means that graphics are ultimately restricted to the rectangular region of plotting space to which you have attached the Plot. In addition to this, you may also specify lower and upper limits on each axis at which clipping should occur. This permits you to further restrict the plotting region. Moreover, you may attach these clipping limits to \emph{any} of the Frames in the Plot. This allows you to place restrictions on where plotting will take place in either the physical coordinate system, the graphical coordinate system, or in any other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot. For example, you could plot using equatorial coordinates and set up clipping limits in galactic coordinates. In general, you could set up arbitrary clipping regions by adding a new Frame to a Plot (in which clipping will be performed) and inter-relating this to the other Frames in a suitable way. Clipping limits are defined using the \htmlref{astClip}{astClip} function, as follows: \small \begin{terminalv} #define NAXES 2 int iframe; double lbnd[ NAXES ], ubnd[ NAXES ]; ... astClip( plot, iframe, lbnd, ubnd); \end{terminalv} \normalsize Here, the ``iframe'' value gives the index of the Frame within the Plot to which clipping is to be applied, while ``lbnd'' and ``ubnd'' give the limits on each axis of the selected Frame (NAXES is the number of axes in this Frame). You can remove clipping by giving a value of AST\_\_NOFRAME for ``iframe''. \subsection{Using a Plot as a Mapping} All Plots are also Mappings (just like the FrameSets from which they are derived), so can be used to transform coordinates. Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert coordinates between the base and current Frames (\emph{i.e.}\ between graphical and physical coordinates). This would be useful if you were (say) reading a cursor position in graphical coordinates and needed to convert this into physical coordinates for display. Conversely, a Plot's inverse transformation converts between its current and base Frames (\emph{i.e.}\ from physical coordinates to graphical coordinates). This transformation is applied automatically whenever plotting operations are carried out by AST functions. It may also be useful to apply it directly, however, if you wish to perform additional plotting operations (\emph{e.g.}\ those provided by the native graphics system) at positions specified in physical coordinates. There is, however, one important difference between using a \htmlref{FrameSet}{FrameSet} and a Plot to transform coordinates, and this is that clipping may be applied by a Plot (if it has been enabled using \htmlref{astClip}{astClip}---\secref{ss:clipping}). Any point which lies within the clipped region of a Plot will, when transformed, yield coordinates with the value AST\_\_BAD. If you wish to avoid this clipping, you should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using \htmlref{astGetMapping}{astGetMapping}) and use this, instead of the Plot, to transform the coordinates. \subsection{Using a Plot as a Frame} Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units, \emph{etc.}, which are typically used when displaying data and/or coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from the current Frame of the Plot (\secref{ss:framesetasframe}). They are also used automatically when using the Plot to plot coordinate axes and coordinate grids (\emph{e.g.}\ for labelling them---\secref{ss:plottingagrid}). Because the current Frame of a Plot represents physical coordinates, any Frame operation applied to the Plot will effectively be working in this coordinate system. For example, the \htmlref{astDistance}{astDistance} and \htmlref{astOffset}{astOffset} functions will compute distances and offsets in physical coordinate space, while \htmlref{astFormat}{astFormat} and \htmlref{astNorm}{astNorm} will format physical coordinates in an appropriate way for display. \subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates} When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot} into graphics coordinates for plotting, they may not always yield valid coordinates, irrespective of any clipping being applied (\secref{ss:clipping}). To indicate this, the resulting coordinate values will be set to the value AST\_\_BAD (\secref{ss:badcoordinates}). There are a number of reasons why this may occur, but typically it will be because physical coordinates only map on to a subset of the graphics coordinate space. This situation is commonly encountered with all-sky projections where, typically, the celestial sphere appears, when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which does not entirely fill the graphics space. In some cases, there may even be multiple regions of valid and invalid physical coordinates. When plotting is performed \emph{via} a Plot, graphical output will only appear in the regions of valid physical coordinates. Nothing will appear where invalid coordinates occur. Such output is effectively clipped. If you wish to plot in these areas, you must change coordinate system and use, say, graphical coordinates to address the plotting surface directly. \subsection{Plotting Borders} The \htmlref{astBorder}{astBorder} function is provided to draw a (line) border around your graphical output. With most graphics systems, this would simply be a rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this boundary follows the edge of each region containing valid, unclipped physical coordinates (\secref{ss:validphysicalcoordinates}). This means, for example, that if you were plotting an all-sky projection, this boundary would outline the perimeter of the celestial sphere when projected on to your plotting surface. Of course, if there is no clipping and all physical coordinates are valid, then you will get the traditional rectangular box. astBorder requires only a pointer to the Plot: \small \begin{terminalv} int holes; ... holes = astBorder( plot ); \end{terminalv} \normalsize It returns a boolean (integer) value to indicate if any invalid or clipped physical coordinates were found within the plotting area. If they were, it will draw around the valid unclipped regions and return a value of one. Otherwise, it will draw a simple rectangular border and return zero. \subsection{Plotting Text} Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be displayed and a position in physical coordinates where the text is to appear. The position is transformed into graphical coordinates to determine where the text should appear on the plotting surface. You must also provide a 2-element ``up'' vector which gives the upward direction of the text in graphical coordinates. This allows text to be drawn at any angle. Plotting is performed by \htmlref{astText}{astText}, for example: \small \begin{terminalv} char text[ 21 ]; double pos[ NCOORD ]; float up[ 2 ] = { 0.0f, 1.0f }; ... astText( plot, text, pos, up, "TL" ); \end{terminalv} \normalsize Here, ``text'' contains the string to be drawn, ``pos'' is an array of physical coordinates and ``up'' specifies the upward vector. In this case, the text will be drawn horizontally. The final argument specifies the text justification, here indicating that the top left corner of the text should appear at the position given. Further control over the appearance of the text is possible by setting values for various Plot attributes, for example Colour, Font and Size. Sub-strings within the displayed text can be given different appearances, or turned into super-scripts or sub-scripts, by the inclusion of escape sequences (see section~\secref{ss:escapes}) within the supplied text string. \subsection{\label{ss:plottingagrid}Plotting a Grid} The most comprehensive plotting function available is \htmlref{astGrid}{astGrid}, which can be used to draw labelled coordinate axes and, optionally, to overlay coordinate grids on the plotting area (Figure~\ref{fig:gridplot}). The routine is straightforward to use, simply requiring a pointer to the \htmlref{Plot}{Plot}: \small \begin{terminalv} astGrid( plot ); \end{terminalv} \normalsize It will draw both linear and curvilinear axes and grids, as required by the particular Plot. The appearance of the output can be modified in a wide variety of ways by setting various Plot attributes. The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings within these strings can be given different appearances, or turned into super-scripts or sub-scripts, by the inclusion of escape sequences (see section~\secref{ss:escapes}) within the Label attributes. \subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings} Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be plotted so that all characters in the string have the same font size, colour, \emph{etc.}, specified by the appropriate attributes of the Plot. However, it is possible to include \emph{escape sequences} within the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be used to change, colour, font, size, width, to introduce extra horizontal space between characters, and to change the base line of characters (thus allowing super-scripts and sub-scripts to be created). See the entry for the Escape attribute in \appref{ss:attributedescriptions} for details. As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a super-scripted exponent. The exponent text will be 70\% of the size of normal text (as determined by the Size attribute), and its baseline will be raised by 50\% of the height of a normal character. Such escape sequences can be used in the strings assigned to textual attributes of the Plot (such as the axis Labels), and may also be included in strings plotted using \htmlref{astText}{astText}. The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option which will cause escape sequences to be included when formatting celestial positions so that super-script characters are used as delimiters for the various fields (a super-script ``h'' for hours, ``m'' for minutes, \emph{etc}). Note, the facility for interpreting escape sequences is only available if the graphics wrapper functions which provide the interface to the underlying graphics system support all the functions included in the \verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be extended by the addition of new functions before escape sequences can be interpretted. \subsection{\label{ss:logaxes}Producing Logarithmic Axes} In certain situations you may wish for one or both of the plotted axes to be displayed logarithmically rather than linearly. For instance, you may wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux against frequency. In this case, you can cause the frequency axis to be drawn logarithmically simply by setting the boolean LogPlot attribute for the frequency axis to a non-zero value. This causes several things to happen: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents the underlying graphics world coordinate system) and the base Frame of the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By default, this mapping is linear on both axes, but setting LogPlot non-zero for an axis causes the Mapping to be modified so that it is logarithmic on the specified axis. This is only possible if the displayed section of the axis does not include the value zero (otherwise the attempt to set a new value for LogPlot is ignored,and it retains its default value of zero). \item The major tick marks drawn as part of the annotated coordinate grid are spaced logarithmically rather than linearly. That is, major axis values are chosen so that there is a constant ratio between adjacent tick mark values. This ratio is constrained to be a power of ten. The minor tick marks are drawn at linearly distributed points between the adjoining major tick values. Thus if a pair of adjacent major tick values are drawn at axis values 10.0 and 100.0, minor ticks will be placed at 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick marks are drawn). \item If possible, numerical axis labels are shown as powers of ten. This depends on the facilities implemented by the graphics wrapper functions (see the next section). Extra functions were introduced to this set of wrapper functions at AST V3.2 which enable super-scripts and sub-scripts to be produced. Some older wrappers may not yet have implemented these functiosn and this will result in axis labels being drawn in usual scientific or decimal notation. \end{enumerate} Whilst the LogPlot attribute can be used to control all three of the above facilities, it is possible to control them individually as well. The LogTicks and LogLabel attributes control the behaviour specified in items 2 and 3 above, but the default values for these attributes depend on the setting of the LogPlot attribute. This means that setting LogPlot non-zero will swicth all three facilites on, so long as zero values have not been assigned explicitly to LogTicks or LogLabel. \subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package} The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a graphics device. Instead, it requires a set of functions to be provided which it uses to draw the required graphics. These include functions to draw a straight line, draw a text string, \emph{etc}. You may choose to provide functions from your favorite graphics package, or you can even write your own! To accomodate variations in the calling interfaces of different graphics packages, AST defines a standard interface for these routines. If this interface differs from the interface provided by your graphics package (which in general it will), then you must write a set of \emph{wrapper functions}, which provide the interface expected by AST but which then call functions from your graphics package to provide the required functionality. AST comes with wrapper functions suitable for the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}). There are two ways of indicating which wrapper functions are to be used by the Plot class: \begin{enumerate} \item A file containing C functions with pre-defined names can be written and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command. (see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT functions to implement the required functionality. This file can be used as a template for writing your own. \item The \htmlref{astGrfSet}{astGrfSet} method of the Plot class can be used to ``register'' wrapper functions at run-time. This allows an application to switch between graphics systems if required. Graphics functions registered in this way do not need to have the pre-defined names used in the link-time method described above. \end{enumerate} For details of the interfaces of the wrapper routines, see either the \texttt{grf\_pgplot.c} file included in the AST source distribution, or the reference documentation for the astGrfSet method. \cleardoublepage \section{Compiling and Linking Software that Uses AST} A small number of UNIX commands are provided by AST to assist with the process of building software. A description of these can be found in \appref{ss:commanddescriptions} and their use is discussed here. Note that in order to access these commands, the appropriate directory (normally ``/star/bin'') should be on your PATH.\footnote{If you have not installed AST in the usual location, then substitute the appropriate directory in place of ``/star'' wherever it occurs.} \subsection{\label{ss:accessingheaderfile}Accessing the ``ast.h'' Header File} The ``ast.h'' header file defines the external interface to the AST library, including all constants, function prototypes, macros, \emph{etc.}. This file should be located using the usual compiler options for finding C include files, for instance: \small \begin{terminalv} cc prog.c -I/star/include -o prog \end{terminalv} \normalsize This is preferable to specifying the file's absolute name within your software. \subsection{\label{ss:linking}Linking with AST Facilities} C programs which use AST facilities may be linked by including execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command line. Thus, to compile and link a program called ``prog'', the following might be used: \small \begin{terminalv} cc prog.c -L/star/lib `ast_link` -o prog \end{terminalv} \normalsize Note the use of backward quote characters, which cause the ``ast\_link'' command to be executed and its result substituted into the compiler command. An alternative is to save the output from ``ast\_link'' in (say) a shell variable and use this instead. You may find this a little faster if you are building software repeatedly during development. Programs which use AST can also be linked in a number of other ways, depending on the facilities they require. In the example above, we have used the default method which assumes that the program will not be generating graphical output, so that no graphics libraries need be linked. If you need other facilities, then various switches can be applied to the ``ast\_link'' command in order to control the linking process. For example, if you were producing graphical output using the PGPLOT graphics package, you could link with the AST/PGPLOT interface by using the ``$-$pgplot'' switch with ``ast\_link'', as follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use the Starlink version of PGPLOT which uses GKS to generate its output.} \small \begin{terminalv} cc prog.c -L/star/lib `ast_link -pgplot` -o prog \end{terminalv} \normalsize See the ``ast\_link'' command description in \appref{ss:commanddescriptions} for details of the options available. \subsection{Building ADAM Applications that Use AST} Users of Starlink's \xref{ADAM}{sg4}{} programming environment \latex{(SG/4)} on UNIX should use the ``\xref{alink}{sun144}{ADAM_link_scripts}'' command (\xref{SUN/144}{sun144}{}) to compile and link applications and can access the AST library by including execution of the command ``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows: \begin{small} \begin{terminalv} alink adamprog.c `ast_link_adam` \end{terminalv} \end{small} Note the use of backward quote characters. By default, AST error messages produced by applications built in this way will be delivered \emph{via} the Starlink EMS Error Message Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is consistent with the \xref{\emph{inherited status}}{sun104}{inherited_status} error handling normally used in Starlink software. Switches may be given to the ``ast\_link\_adam'' command (in a similar way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with additional AST-related facilities, such as a graphics interface. See the ``ast\_link\_adam'' command description in \appref{ss:commanddescriptions} for details of the options available. \appendix \cleardoublepage \section{\label{ss:classhierarchy}The AST Class Hierarchy} The following table shows the hierarchy of classes in the AST library. For a description of each class, you should consult \appref{ss:classdescriptions}. \small \begin{terminalv} Object - Base class for all AST Objects Axis - Store axis information SkyAxis - Store celestial axis information Channel - Basic (textual) I/O channel FitsChan - I/O Channel using FITS header cards XmlChan - I/O Channel using XML StcsChan - I/O Channel using IVOA STC-S descriptions KeyMap - Store a set of key/value pairs Table - Store a 2-dimensional table of values Mapping - Inter-relate two coordinate systems CmpMap - Compound Mapping DssMap - Map points using Digitised Sky Survey plate solution Frame - Coordinate system description CmpFrame - Compound Frame SpecFluxFrame - Observed value versus spectral position FluxFrame - Observed value at a given fixed spectral position FrameSet - Set of inter-related coordinate systems Plot - Provide facilities for 2D graphical output Plot3D - Provide facilities for 3D graphical output Region - Specify areas within a coordinate system Box - A box region with sides parallel to the axes of a Frame Circle - A circular or spherical region within a Frame CmpRegion - A combination of two regions within a single Frame Ellipse - An elliptical region within a 2-dimensional Frame Interval - Intervals on one or more axes of a Frame. NullRegion - A boundless region within a Frame PointList - A collection of points in a Frame Polygon - A polygonal region within a 2-dimensional Frame Prism - An extrusion of a Region into orthogonal dimensions Stc - Represents an generic instance of an IVOA STC-X description StcResourceProfile - Represents an an IVOA STC-X ResourceProfile StcSearchLocation - Represents an an IVOA STC-X SearchLocation StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation SkyFrame - Celestial coordinate system description SpecFrame - Spectral coordinate system description DSBSpecFrame - Dual sideband spectral coordinate system description TimeFrame - Time coordinate system description GrismMap - Models the spectral dispersion produced by a grism IntraMap - Map points using a private transformation function LutMap - Transform 1-dimensional coordinates using a lookup table MathMap - Transform coordinates using mathematical expressions MatrixMap - Map positions by multiplying them by a matrix NormMap - Normalise coordinates using a supplied Frame PcdMap - Apply 2-dimensional pincushion/barrel distortion PermMap - Coordinate permutation Mapping PolyMap - General N-dimensional polynomial Mapping RateMap - Calculates an element of a Mapping's Jacobian matrix SelectorMap - Locates positions within a set of Regions ShiftMap - Shifts each axis by a constant amount SlaMap - Sequence of celestial coordinate conversions SpecMap - Sequence of spectral coordinate conversions SphMap - Map 3-d Cartesian to 2-d spherical coordinates SwitchMap - Encapuslates a set of alternate Mappings TimeMap - Sequence of time coordinate conversions TranMap - Combine fwd. and inv. transformations from two Mappings UnitMap - Unit (null) Mapping UnitNormMap - Converts a vector to a unit vector plus length WcsMap - Implement a FITS-WCS sky projection WinMap - Match windows by scaling and shifting each axis ZoomMap - Zoom coordinates about the origin \end{terminalv} \normalsize \cleardoublepage \section{\label{ss:functiondescriptions}AST Function Descriptions} \small \sstroutine{ astSet }{ Set attribute values for an Object }{ \sstdescription{ This function assigns a set of attribute values to an \htmlref{Object}{Object}, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute\texttt{'} s data type. The string supplied may also contain \texttt{"} printf\texttt{"} -style format specifiers, identified by \texttt{"} \%\texttt{"} signs in the usual way. If present, these will be substituted by values supplied as additional optional arguments (using the normal \texttt{"} printf\texttt{"} rules) before the string is used. } \sstsynopsis{ void astSet( AstObject $*$this, const char $*$settings, ... ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ settings }{ Pointer to a null-terminated character string containing a comma-separated list of attribute settings in the form described above. } \sstsubsection{ ... }{ Optional additional arguments which supply values to be substituted for any \texttt{"} printf\texttt{"} -style format specifiers that appear in the \texttt{"} settings\texttt{"} string. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstexamples{ \sstexamplesubsection{ astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"} ); }{ Sets the Report attribute for Object \texttt{"} map\texttt{"} to the value 1 and the Zoom attribute to 25.0. } \sstexamplesubsection{ astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis ); }{ Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"} to a suitable string, where the axis number is obtained from \texttt{"} axis\texttt{"} , a variable of type int. } \sstexamplesubsection{ astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring ); }{ Sets the Title attribute for Object \texttt{"} frame\texttt{"} to the contents of the string \texttt{"} mystring\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned). \sstitem To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. Alternatively, you can use \texttt{"} \%s\texttt{"} format and supply the value as a separate additional argument to astSet (or use the astSetC function instead). \sstitem The same procedure may be adopted if \texttt{"} \%\texttt{"} signs are to be included and are not to be interpreted as format specifiers (alternatively, the \texttt{"} printf\texttt{"} convention of writing \texttt{"} \%\%\texttt{"} may be used). \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ astAddColumn }{ Add a new column definition to a table }{ \sstdescription{ Adds the definition of a new column to the supplied table. Initially, the column is empty. Values may be added subsequently using the methods of the \htmlref{KeyMap}{KeyMap} class. } \sstsynopsis{ void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim, int $*$dims, const char $*$unit ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ name }{ The column name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. } \sstsubsection{ type }{ The data type associated with the column. See \texttt{"} Applicability:\texttt{"} below. } \sstsubsection{ ndim }{ The number of dimensions spanned by the values stored in a single cell of the column. Zero if the column holds scalar values. } \sstsubsection{ dims }{ An array holding the the lengths of each of the axes spanned by the values stored in a single cell of the column. Ignored if the column holds scalara values. } \sstsubsection{ unit }{ A string specifying the units of the column. Supply a blank string if the column is unitless. } } \sstapplicability{ \sstsubsection{ Table }{ Tables can hold columns with any of the following data types - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for short int), AST\_\_BYTETYPE (for unsigned bytes - i.e. unsigned chars), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{astMapPutU}{astMapPutU}). } \sstsubsection{ \htmlref{FitsTable}{FitsTable} }{ FitsTables can hold columns with any of the following data types - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for short int), AST\_\_BYTETYPE (for unsigned bytes - i.e. unsigned chars), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string). } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if a column already exists in the Table with the supplied name and properties. However an error is reported if any of the properties differ. } } } \sstroutine{ astAddFrame }{ Add a Frame to a FrameSet to define a new coordinate system }{ \sstdescription{ This function adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a \htmlref{FrameSet}{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\texttt{'} s current Frame. This function may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet. } \sstsynopsis{ void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map, AstFrame $*$frame ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe }{ 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 \htmlref{Nframe}{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). } \sstsubsection{ map }{ Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index \texttt{"} iframe\texttt{"} ) into coordinates in the new system. The Mapping\texttt{'} s forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction. The supplied Mapping is ignored if parameter \texttt{"} iframe\texttt{"} is equal to AST\_\_ALLFRAMES. } \sstsubsection{ frame }{ Pointer to a Frame that describes the new coordinate system. Any class of Frame may be supplied (including Regions and FrameSets). This function may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this parameter (see the Notes section for details). } } \sstnotes{ \sstitemlist{ \sstitem Deep copies of the supplied \texttt{"} mapping\texttt{"} and \texttt{"} frame\texttt{"} 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. \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current Frame respectively. \sstitem This function sets the value of the \htmlref{Current}{Current} attribute for the FrameSet so that the new Frame subsequently becomes the current Frame. \sstitem The number of input coordinate values accepted by the supplied Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the Frame identified by the \texttt{"} iframe\texttt{"} parameter. Similarly, the number of output coordinate values generated by this Mapping (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new Frame. \sstitem As a special case, if a pointer to a FrameSet is given for the \texttt{"} frame\texttt{"} parameter, this is treated as a request to merge a pair of FrameSets. This is done by appending all the new Frames (in the \texttt{"} frame\texttt{"} 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 the \texttt{"} iframe\texttt{"} parameter (in the original FrameSet) and the current Frame of the \texttt{"} frame\texttt{"} FrameSet. This latter Frame becomes the current Frame in the merged FrameSet. \sstitem As another special case, if a value of AST\_\_ALLFRAMES is supplied for parameter \texttt{"} iframe\texttt{"} , 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 \htmlref{CmpFrame}{CmpFrame} containing the original Frame and the Frame specified by parameter \texttt{"} frame\texttt{"} . In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap} containing the original Mapping and a \htmlref{UnitMap}{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 \htmlref{astSimplify}{astSimplify} before being stored in the FrameSet. } } } \sstroutine{ astAddParameter }{ Add a new global parameter definition to a table }{ \sstdescription{ Adds the definition of a new global parameter to the supplied table. Note, this does not store a value for the parameter. To get or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class should be used, using the name of the parameter as the key. } \sstsynopsis{ void astAddParameter( AstTable $*$this, const char $*$name ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ name }{ The parameter name. Trailing spaces are ignored (all other spaces are significant). The supplied string is converted to upper case. } } \sstnotes{ \sstitemlist{ \sstitem Unlike columns, the definition of a parameter does not specify its type, size or dimensionality. } } } \sstroutine{ astAddVariant }{ Store a new variant Mapping for the current Frame in a FrameSet }{ \sstdescription{ This function allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"} attribute for more details. It can also be used to rename the currently selected variant Mapping. } \sstsynopsis{ void astAddVariant( AstFrameSet $*$this, AstMapping $*$map, const char $*$name, int $*$status ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ map }{ Pointer to a Mapping which describes how to convert coordinates from the current Frame to the new variant of the current Frame. If NULL is supplied, then the name associated with the currently selected variant of the current Frame is set to the value supplied for \texttt{"} name\texttt{"} , but no new variant is added. } \sstsubsection{ name }{ The name to associate with the new variant Mapping (or the currently selected variant Mapping if \texttt{"} map\texttt{"} is NULL). } } \sstnotes{ \sstitemlist{ \sstitem The newly added Variant becomes the current variant on exit (this is equivalent to setting the Variant attribute to the value supplied for \texttt{"} name). \sstitem An error is reported if a variant with the supplied name already exists in the current Frame. \sstitem 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 \htmlref{astMirrorVariants}{astMirrorVariants} function has been called to make the current Frame act as a mirror. } } } \sstroutine{ astAngle }{ Calculate the angle subtended by two points at a third point }{ \sstdescription{ 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 \htmlref{Frame}{Frame} in use. For instance, in \htmlref{SkyFrame}{SkyFrame}, they will be great circles. } \sstsynopsis{ double astAngle( AstFrame $*$this, const double a[], const double b[], const double c[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ a }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ b }{ An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. } \sstsubsection{ c }{ An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the third point. } } \sstreturnedvalue{ \sstsubsection{ 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 \$$\backslash$pm $\backslash$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 \$$\backslash$pi\$. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem 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. } } } \sstroutine{ astAnnul }{ Annul a pointer to an Object }{ \sstdescription{ This function annuls a pointer to an \htmlref{Object}{Object} so that it is no longer recognised as a valid pointer by the AST library. Any resources associated with the pointer are released and made available for re-use. This function also decrements the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute by one. If this attribute reaches zero (which happens when the last pointer to the Object is annulled), then the Object is deleted. } \sstsynopsis{ AstObject $*$astAnnul( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ The Object pointer to be annulled. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astAnnul() }{ A null Object pointer (AST\_\_NULL) is always returned. } } \sstnotes{ \sstitemlist{ \sstitem This function will attempt to annul the pointer even if the Object is not currently locked by the calling thread (see \htmlref{astLock}{astLock}). \sstitem This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. In particular, it will fail if the pointer suppled is not valid, but this will only be reported if the error status is clear on entry. } } } \sstroutine{ astAxAngle }{ Returns the angle from an axis, to a line through two points }{ \sstdescription{ 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. } \sstsynopsis{ double astAxAngle( AstFrame $*$this, const double a[], const double b[], int axis ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Frame}{Frame}. } \sstsubsection{ a }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ b }{ An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates of the second point. } \sstsubsection{ axis }{ The number of the Frame axis from which the angle is to be measured (axis numbering starts at 1 for the first axis). } } \sstreturnedvalue{ \sstsubsection{ astAxAngle }{ The angle in radians, from the positive direction of the specified axis, to the line AB. If the Frame is 2-dimensional, it will be in the range [-PI/2,$+$PI/2], and positive rotation is in the same sense as rotation from the positive direction of axis 2 to the positive direction of axis 1. If the Frame has more than 2 axes, a positive value will always be returned in the range zero to PI. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this function is the path of shortest distance between two points, as defined by the \htmlref{astDistance}{astDistance} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the require position angle is undefined. } } } \sstroutine{ astAxDistance }{ Find the distance between two axis values }{ \sstdescription{ This function returns a signed value representing the axis increment from axis value v1 to axis value v2. For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the difference between the two axis values. But for other derived classes of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. } \sstsynopsis{ double astAxDistance( AstFrame $*$this, int axis, double v1, double v2 ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ axis }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ v1 }{ The first axis value. } \sstsubsection{ v2 }{ The second axis value. } } \sstreturnedvalue{ \sstsubsection{ astAxDistance }{ The distance from the first to the second axis value. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input values has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astAxNorm }{ Normalise an array of axis values }{ \sstdescription{ This function modifies a supplied array of axis values so that they are normalised in the manner indicated by parameter \texttt{"} oper\texttt{"} . No normalisation is possible for a simple \htmlref{Frame}{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 \htmlref{SkyFrame}{SkyFrame} has a discontinuity at zero longitude and so a longitude value can be expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the \texttt{"} Applicability:\texttt{"} section below for details. } \sstsynopsis{ void astAxNorm( AstFrame $*$this, int axis, int oper, int nval, double $*$values, int $*$status ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ axis }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ oper }{ Indicates the type of normalisation to be applied. If zero is supplied, the normalisation will be the same as that performed by function \htmlref{astNorm}{astNorm}. If 1 is supplied, the normalisation will be chosen automatically so that the resulting list has the smallest range. } \sstsubsection{ nval }{ The number of points in the values array. } \sstsubsection{ values }{ On entry, the axis values to be normalised. Modified on exit to hold the normalised values. } } \sstapplicability{ \sstsubsection{ SkyFrame }{ If \texttt{"} oper\texttt{"} is 0, longitude values are returned in the range [0,2$*$PI]. If \texttt{"} oper\texttt{"} is 1, longitude values are returned in either the range [0,2$*$PI] or [-PI,PI]. The choice is made so that that the resulting list has the smallest range. Latitude values are always returned in the range [-PI,PI]. } \sstsubsection{ All other classes of Frame }{ The supplied axis values are returned unchanged. } } } \sstroutine{ astAxOffset }{ Add an increment onto a supplied axis value }{ \sstdescription{ This function returns an axis value formed by adding a signed axis increment onto a supplied axis value. For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the sum of the two supplied values. But for other derived classes of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. } \sstsynopsis{ double astAxOffset( AstFrame $*$this, int axis, double v1, double dist ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ axis }{ The index of the axis to which the supplied values refer. The first axis has index 1. } \sstsubsection{ v1 }{ The original axis value. } \sstsubsection{ dist }{ The axis increment to add to the original axis value. } } \sstreturnedvalue{ \sstsubsection{ astAxOffset }{ The incremented axis value. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input values has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astBBuf }{ Begin a new graphical buffering context }{ \sstdescription{ This function starts a new graphics buffering context. A matching call to the function \htmlref{astEBuf}{astEBuf} should be used to end the context. } \sstsynopsis{ void astBBuf( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Plot}{Plot}. } } \sstnotes{ \sstitemlist{ \sstitem The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this function to this function simply invokes the astGBBuf function in the grf module. } } } \sstroutine{ astBegin }{ Begin a new AST context }{ \sstdescription{ This macro invokes a function to begin a new AST context. Any \htmlref{Object}{Object} pointers created within this context will be annulled when it is later ended using \htmlref{astEnd}{astEnd} (just as if \htmlref{astAnnul}{astAnnul} had been invoked), unless they have first been exported using \htmlref{astExport}{astExport} or rendered exempt using \htmlref{astExempt}{astExempt}. If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. } \sstsynopsis{ void astBegin } \sstapplicability{ \sstsubsection{ Object }{ This macro applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem astBegin attempts to execute even if the AST error status is set on entry. \sstitem Contexts delimited by astBegin and astEnd may be nested to any depth. } } } \sstroutine{ astBorder }{ Draw a border around valid regions of a Plot }{ \sstdescription{ This function draws a (line) border around regions of the plotting area of a \htmlref{Plot}{Plot} which correspond to valid, unclipped physical coordinates. For example, when plotting using an all-sky map projection, this function could be used to draw the boundary of the celestial sphere when it is projected on to the plotting surface. If the entire plotting area contains valid, unclipped physical coordinates, then the boundary will just be a rectangular box around the edges of the plotting area. If the Plot is a \htmlref{Plot3D}{Plot3D}, this method is applied individually to each of the three 2D Plots encapsulated within the Plot3D (each of these Plots corresponds to a single 2D plane in the 3D graphics system). In addition, if the entire plotting volume has valid coordinates in the 3D current \htmlref{Frame}{Frame} of the Plot3D, then additional lines are drawn along the edges of the 3D plotting volume so that the entire plotting volume is enclosed within a cuboid grid. } \sstsynopsis{ int astBorder( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } } \sstreturnedvalue{ \sstsubsection{ astBorder() }{ Zero is returned if the plotting space is completely filled by valid, unclipped physical coordinates (so that only a rectangular box was drawn around the edge). Otherwise, one is returned. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. \sstitem An error results if either the current Frame or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the base and current Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} attribute is zero). } } } \sstroutine{ astBoundingBox }{ Return a bounding box for previously drawn graphics }{ \sstdescription{ This function returns the bounds of a box which just encompasess the graphics produced by the previous call to any of the \htmlref{Plot}{Plot} methods which produce graphical output. If no such previous call has yet been made, or if the call failed for any reason, then the bounding box returned by this function is undefined. } \sstsynopsis{ void astBoundingBox( AstPlot $*$this, float lbnd[2], float ubnd[2] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ lbnd }{ A two element array in which is returned the lower limits of the bounding box on each of the two axes of the graphics coordinate system (the base \htmlref{Frame}{Frame} of the Plot). } \sstsubsection{ ubnd }{ A two element array in which is returned the upper limits of the bounding box on each of the two axes of the graphics coordinate system (the base Frame of the Plot). } } \sstnotes{ \sstitemlist{ \sstitem An error results if the base Frame of the Plot is not 2-dimensional. } } } \sstroutine{ astBox }{ Create a Box }{ \sstdescription{ This function creates a new \htmlref{Box}{Box} and optionally initialises its attributes. The Box class implements a \htmlref{Region}{Region} which represents a box with sides parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a pole). } \sstsynopsis{ AstBox $*$astBox( AstFrame $*$frame, int form, const double point1[], const double point2[], AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ form }{ Indicates how the box is described by the remaining parameters. A value of zero indicates that the box is specified by a centre position and a corner position. A value of one indicates that the box is specified by a two opposite corner positions. } \sstsubsection{ point1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). If \texttt{"} form\texttt{"} is zero, this array should contain the coordinates at the centre of the box. If \texttt{"} form\texttt{"} is one, it should contain the coordinates at the corner of the box which is diagonally opposite the corner specified by \texttt{"} point2\texttt{"} . } \sstsubsection{ point2 }{ An array of double, with one element for each Frame axis (Naxes attribute) containing the coordinates at any corner of the box. } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Box. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astBox() }{ A pointer to the new Box. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astChannel }{ Create a Channel }{ \sstdescription{ This function creates a new \htmlref{Channel}{Channel} and optionally initialises its attributes. A Channel implements low-level input/output for the AST library. Writing an \htmlref{Object}{Object} to a Channel (using \htmlref{astWrite}{astWrite}) will generate a textual representation of that Object, and reading from a Channel (using \htmlref{astRead}{astRead}) will create a new Object from its textual representation. Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output. Alternatively, a Channel can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstsynopsis{ AstChannel $*$astChannel( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) } \sstparameters{ \sstsubsection{ source }{ Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the Channel to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read. If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile attribute, the Channel will read from standard input instead. } \sstsubsection{ sink }{ Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the Channel to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store. If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile attribute, the Channel will write to standard output instead. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Channel. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astChannel() }{ A pointer to the new Channel. } } \sstnotes{ \sstitemlist{ \sstitem Application code can pass arbitrary data (such as file descriptors, etc) to source and sink functions using the \htmlref{astPutChannelData}{astPutChannelData} function. The source or sink function should use the \htmlref{astChannelData}{astChannelData} macro to retrieve this data. \sstitem 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. } } } \sstroutine{ astChannelData }{ Return a pointer to user-supplied data stored with a Channel }{ \sstdescription{ This macro is intended to be used within the source or sink functions associated with a \htmlref{Channel}{Channel}. It returns any pointer previously stored in the Channel (that is, the Channel that has invoked the source or sink function) using \htmlref{astPutChannelData}{astPutChannelData}. This mechanism is a thread-safe alternative to passing file descriptors, etc, via static global variables. } \sstsynopsis{ void $*$astChannelData } \sstapplicability{ \sstsubsection{ Channel }{ This macro applies to all Channels. } } \sstreturnedvalue{ \sstsubsection{ astChannelData }{ The pointer previously stored with the Channel using astPutChannelData. A NULL pointer will be returned if no such pointer has been stored with the Channel. } } \sstnotes{ \sstitemlist{ \sstitem This routine is not available in the Fortran 77 interface to the AST library. } } } \sstroutine{ astCircle }{ Create a Circle }{ \sstdescription{ This function creates a new \htmlref{Circle}{Circle} and optionally initialises its attributes. A Circle is a \htmlref{Region}{Region} which represents a circle or sphere within the supplied \htmlref{Frame}{Frame}. } \sstsynopsis{ AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[], const double point[], AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ form }{ Indicates how the circle is described by the remaining parameters. A value of zero indicates that the circle is specified by a centre position and a position on the circumference. A value of one indicates that the circle is specified by a centre position and a scalar radius. } \sstsubsection{ centre }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of the circle or sphere. } \sstsubsection{ point }{ If \texttt{"} form\texttt{"} is zero, then this array should have one element for each Frame axis (Naxes attribute), and should be supplied holding the coordinates at a point on the circumference of the circle or sphere. If \texttt{"} form\texttt{"} is one, then this array should have one element only which should be supplied holding the scalar radius of the circle or sphere, as a geodesic distance within the Frame. } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Circle being created. The uncertainty in any point on the boundary of the Circle is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, Circle, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Circle. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Circle being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Circle. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astCircle() }{ A pointer to the new Circle. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astCirclePars }{ Returns the geometric parameters of an Circle }{ \sstdescription{ This function returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}. } \sstsynopsis{ void astCirclePars( AstCircle $*$this, double $*$centre, double $*$radius, double $*$p1 ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Region}{Region}. } \sstsubsection{ centre }{ Pointer to an array in which to return the coordinates of the Circle centre. The length of this array should be no less than the number of axes in the associated coordinate system. } \sstsubsection{ radius }{ Returned holding the radius of the Circle, as an geodesic distance in the associated coordinate system. } \sstsubsection{ p1 }{ Pointer to an array in which to return the coordinates of a point on the circumference of the Circle. The length of this array should be no less than the number of axes in the associated coordinate system. A NULL pointer can be supplied if the circumference position is not needed. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Circle has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Circle object may not be an accurate circle. } } } \sstroutine{ astClear }{ Clear attribute values for an Object }{ \sstdescription{ This function clears the values of a specified set of attributes for an \htmlref{Object}{Object}. 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 \htmlref{astTest}{astTest} function to return the value zero for the attribute, indicating that no value has been set. } \sstsynopsis{ void astClear( AstObject $*$this, const char $*$attrib ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ attrib }{ Pointer to a null-terminated character string containing a comma-separated list of the names of the attributes to be cleared. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem It does no harm to clear an attribute whose value has not been set. \sstitem An error will result if an attempt is made to clear the value of a read-only attribute. } } } \sstroutine{ astClearStatus }{ Clear the AST error status }{ \sstdescription{ This macro resets the AST error status to an OK value, indicating that an error condition (if any) has been cleared. } \sstsynopsis{ void astClearStatus } \sstnotes{ \sstitemlist{ \sstitem If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. Using astClearStatus will restore normal behaviour. } } } \sstroutine{ astClip }{ Set up or remove clipping for a Plot }{ \sstdescription{ This function defines regions of a \htmlref{Plot}{Plot} which are to be clipped. Any subsequent graphical output created using the Plot will then be visible only within the unclipped regions of the plotting area. See also the \htmlref{Clip}{Clip} attribute. } \sstsynopsis{ void astClip( AstPlot $*$this, int iframe, const double lbnd[], const double ubnd[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ iframe }{ The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping limits supplied in \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} (below) refer. Clipping may be applied to any of the coordinate systems associated with a Plot (as defined by the Frames it contains), so this index may take any value from 1 to the number of Frames in the Plot (\htmlref{Nframe}{Nframe} attribute). In addition, the values AST\_\_BASE and AST\_\_CURRENT may be used to specify the base and current Frames respectively. For example, a value of AST\_\_CURRENT causes clipping to be performed in physical coordinates, while a value of AST\_\_BASE would clip in graphical coordinates. Clipping may also be removed completely by giving a value of AST\_\_NOFRAME. In this case any clipping bounds supplied (below) are ignored. } \sstsubsection{ lbnd }{ An array with one element for each axis of the clipping Frame (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the lower bound, on each axis, of the region which is to remain visible (unclipped). } \sstsubsection{ ubnd }{ An array with one element for each axis of the clipping Frame (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the upper bound, on each axis, of the region which is to remain visible (unclipped). } } \sstnotes{ \sstitemlist{ \sstitem Only one clipping Frame may be active at a time. This function will deactivate any previously-established clipping Frame before setting up new clipping limits. \sstitem The clipping produced by this function is in addition to that specified by the Clip attribute which occurs at the edges of the plotting area established when the Plot is created (see \htmlref{astPlot}{astPlot}). The underlying graphics system may also impose further clipping. \sstitem When testing a graphical position for clipping, it is first transformed into the clipping Frame. The resulting coordinate on each axis is then checked against the clipping limits (given by \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} ). By default, a position is clipped if any coordinate lies outside these limits. However, if a non-zero value is assigned to the Plot\texttt{'} s \htmlref{ClipOp}{ClipOp} attribute, then a position is only clipped if the coordinates on all axes lie outside their clipping limits. \sstitem If the lower clipping limit exceeds the upper limit for any axis, then the sense of clipping for that axis is reversed (so that coordinate values lying between the limits are clipped instead of those lying outside the limits). To produce a \texttt{"} hole\texttt{"} in a coordinate space (that is, an internal region where nothing is plotted), you should supply all the bounds in reversed order, and set the ClipOp attribute for the Plot to a non-zero value. \sstitem Either clipping limit may be set to the value AST\_\_BAD, which is equivalent to setting it to infinity (or minus infinity for a lower bound) so that it is not used. \sstitem If a graphical position results in any bad coordinate values (AST\_\_BAD) when transformed into the clipping Frame, then it is treated (for the purposes of producing graphical output) as if it were clipped. \sstitem When a Plot is used as a \htmlref{Mapping}{Mapping} to transform points (e.g. using \htmlref{astTran2}{astTran2}), any clipped output points are assigned coordinate values of AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. } } } \sstroutine{ astClone }{ Clone (duplicate) an Object pointer }{ \sstdescription{ This function returns a duplicate pointer to an existing \htmlref{Object}{Object}. It also increments the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to keep track of how many pointers have been issued. Note that this function is NOT equivalent to an assignment statement, as in general the two pointers will not have the same value. } \sstsynopsis{ AstObject $*$astClone( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Original pointer to the Object. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astClone() }{ A duplicate pointer to the same Object. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astCmpFrame }{ Create a CmpFrame }{ \sstdescription{ This function creates a new \htmlref{CmpFrame}{CmpFrame} and optionally initialises its attributes. A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame). Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way. Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values. } \sstsynopsis{ AstCmpFrame $*$astCmpFrame( AstFrame $*$frame1, AstFrame $*$frame2, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame1 }{ Pointer to the first component Frame. } \sstsubsection{ frame2 }{ Pointer to the second component Frame. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astCmpFrame() }{ A pointer to the new CmpFrame. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astCmpMap }{ Create a CmpMap }{ \sstdescription{ This function creates a new \htmlref{CmpMap}{CmpMap} and optionally initialises its attributes. A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be \texttt{"} in series\texttt{"} (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the earlier coordinates for each point and the second Mapping simultaneously transforms the later coordinates). Since a CmpMap is itself a Mapping, it can be used as a component in forming further CmpMaps. Mappings of arbitrary complexity may be built from simple individual Mappings in this way. } \sstsynopsis{ AstCmpMap $*$astCmpMap( AstMapping $*$map1, AstMapping $*$map2, int series, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ map1 }{ Pointer to the first component Mapping. } \sstsubsection{ map2 }{ Pointer to the second component Mapping. } \sstsubsection{ series }{ If a non-zero value is given for this parameter, the two component Mappings will be connected in series. A zero value requests that they are connected in parallel. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astCmpMap() }{ A pointer to the new CmpMap. } } \sstnotes{ \sstitemlist{ \sstitem If the component Mappings are connected in series, then using the resulting CmpMap to transform coordinates will cause the first Mapping to be applied, followed by the second Mapping. If the inverse CmpMap transformation is requested, the two component Mappings will be applied in both the reverse order and the reverse direction. \sstitem When connecting two component Mappings in series, the number of output coordinates generated by the first Mapping (its \htmlref{Nout}{Nout} attribute) must equal the number of input coordinates accepted by the second Mapping (its \htmlref{Nin}{Nin} attribute). \sstitem If the component Mappings of a CmpMap are connected in parallel, then the first Mapping will be used to transform the earlier input coordinates for each point (and to produce the earlier output coordinates) and the second Mapping will be used simultaneously to transform the remaining input coordinates (to produce the remaining output coordinates for each point). If the inverse transformation is requested, each Mapping will still be applied to the same coordinates, but in the reverse direction. \sstitem When connecting two component Mappings in parallel, there is no restriction on the number of input and output coordinates for each Mapping. \sstitem Note that the component Mappings supplied are not copied by astCmpMap (the new CmpMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a CmpMap containing a copy of its component Mappings is required, then a copy of the CmpMap should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astCmpRegion }{ Create a CmpRegion }{ \sstdescription{ This function creates a new \htmlref{CmpRegion}{CmpRegion} and optionally initialises its attributes. A CmpRegion is a \htmlref{Region}{Region} which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion. The two component Region need not refer to the same coordinate \htmlref{Frame}{Frame}, but it must be possible for the \htmlref{astConvert}{astConvert} function to determine a \htmlref{Mapping}{Mapping} between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region. Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way. } \sstsynopsis{ AstCmpRegion $*$astCmpRegion( AstRegion $*$region1, AstRegion $*$region2, int oper, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region1 }{ Pointer to the first component Region. } \sstsubsection{ region2 }{ Pointer to the second component Region. This Region will be transformed into the coordinate Frame of the first region before use. An error will be reported if this is not possible. } \sstsubsection{ oper }{ The boolean operator with which to combine the two Regions. This must be one of the symbolic constants AST\_\_AND, AST\_\_OR or AST\_\_XOR. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new CmpRegion. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astCmpRegion() }{ A pointer to the new CmpRegion. } } \sstnotes{ \sstitemlist{ \sstitem If one of the supplied Regions has an associated uncertainty, that uncertainty will also be used for the returned CmpRegion. If both supplied Regions have associated uncertainties, the uncertainty associated with the first Region will be used for the returned CmpRegion. \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the CmpRegion. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astColumnName }{ Get the name of the column at a given index within the Table }{ \sstdescription{ This function returns a string holding the name of the column with the given index within the \htmlref{Table}{Table}. This function is intended primarily as a means of iterating round all the columns in a Table. For this purpose, the number of columns in the Table is given by the \htmlref{Ncolumn}{Ncolumn} attribute of the Table. This function could then be called in a loop, with the index value going from zero to one less than Ncolumn. Note, the index associated with a column decreases monotonically with the age of the column: the oldest Column in the Table will have index one, and the Column added most recently to the Table will have the largest index. } \sstsynopsis{ const char $*$astColumnName( AstTable $*$this, int index ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ index }{ The index into the list of columns. The first column has index one, and the last has index \texttt{"} Ncolumn\texttt{"} . } } \sstreturnedvalue{ \sstsubsection{ astColumnName() }{ A pointer to a null-terminated string containing the upper case column name. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. \sstitem A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astColumnNull }{ Get or set the null value for an integer column of a FITS table }{ \sstdescription{ This function allows a null value to be stored with a named integer-valued column in a \htmlref{FitsTable}{FitsTable}. The supplied null value is assigned to the TNULLn keyword in the FITS header associated with the FitsTable. A value in the named column is then considered to be null if 1) it equals the null value supplied to this function, or 2) no value has yet been stored in the cell. As well as setting a new null value, this function also returns the previous null value. If no null value has been set previously, a default value will be returned. This default will be an integer value that does not currently occur anywhere within the named column. If no such value can be found, what happens depends on whether the column contains any cells in which no values have yet been stored. If so, an error will be reported. Otherwise (i.e. if there are no null values in the column), an arbitrary value of zero will be returned as the function value, and no TNULLn keyword will be stored in the FITS header. A flag is returned indicating if the returned null value was set explicitly by a previous call to this function, or is a default value. A second flag is returned indicating if the named column contains any null values (i.e. values equal to the supplied null value, or cells to which no value has yet been assigned). } \sstsynopsis{ int astColumnNull( AstFitsTable $*$this, const char $*$column, int set, int newval, int $*$wasset, int $*$hasnull ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ column }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ set }{ If non-zero, the value supplied for parameter \texttt{"} newval\texttt{"} will be stored as the current null value, replacing any value set by a previous call to this function. If zero, the value supplied for parameter \texttt{"} newval\texttt{"} is ignored and the current null value is left unchanged. } \sstsubsection{ newval }{ The new null value to use. Ignored if \texttt{"} set\texttt{"} is zero. An error will be reported if the supplied value is outside the range of values that can be stored in the integer data type associated with the column. } \sstsubsection{ wasset }{ Pointer to an int that will be returned non-zero if the returned null value was set previously via an earlier invocation of this function. Zero is returned otherwise. If the named column does not exist, or an error occurs, a value of zero is returned. } \sstsubsection{ hasnull }{ Pointer to an int that will be returned non-zero if and only if the named column currently contains any values equal to the null value on exit (i.e. \texttt{"} newval\texttt{"} if \texttt{"} set\texttt{"} is non-zero, or the returned function value otherwise), or contains any empty cells. If the named column does not exist, or an error occurs, a value of zero is returned. If a NULL pointer is supplied for \texttt{"} hasnull\texttt{"} , no check on the presence of null values will be performed. } } \sstreturnedvalue{ \sstsubsection{ astColumnNull() }{ The null value that was in use on entry to this function. If a null value has been set by a previous invocation of this function, it will be returned. Otherwise, if \texttt{"} set\texttt{"} is non-zero, the supplied \texttt{"} newval\texttt{"} value is returned. Otherwise, a default value is chosen (if possible) that does not currently occur in the named column. If all available values are in use in the column, an error is reported if and only if the column contains any empty cells. Otherwise, a value of zero is returned. A value of zero is also returned if the named column does not exist, or an error occurs. } } \sstnotes{ \sstitemlist{ \sstitem The FITS binary table definition allows only integer-valued columns to have an associated null value. This routine will return without action if the column is not integer-valued. } } } \sstroutine{ astColumnShape }{ Returns the shape of the values in a named column }{ \sstdescription{ This function returns the number of dimensions spaned by each value in a named column of a \htmlref{Table}{Table}, together with the length of each dimension. These are the values supplied when the column was created using \htmlref{astAddColumn}{astAddColumn}. } \sstsynopsis{ void astColumnShape( AstTable $*$this, const char $*$column, int mxdim, int $*$ndim, int $*$dims ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ column }{ The character string holding the upper case name of the column. Trailing spaces are ignored. } \sstsubsection{ mxdim }{ The length of the \texttt{"} dims\texttt{"} array. } \sstsubsection{ ndim }{ Pointer to an int in which to return the number of dimensions spanned by values in the named column. This will be zero if the column contains scalar values. } \sstsubsection{ dims }{ Pointer to an array in which to return the length of each dimension. Any excess trailing elements will be filled with the value 1. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested column cannot be found in the given Table. A value of zero is returned for \texttt{"} ndim\texttt{"} and the supplied values in \texttt{"} dims\texttt{"} are left unchanged. \sstitem A value of zero is returned for \texttt{"} ndim\texttt{"} if an error occurs. } } } \sstroutine{ astColumnSize }{ Get the number of bytes needed to hold a full column of data }{ \sstdescription{ This function returns the number of bytes of memory that must be allocated prior to retrieving the data from a column using \htmlref{astGetColumnData}{astGetColumnData}. } \sstsynopsis{ size\_t astColumnSize( AstFitsTable $*$this, const char $*$column, int $*$hasnull ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Table}{Table}. } \sstsubsection{ column }{ The character string holding the name of the column. Trailing spaces are ignored. } } \sstreturnedvalue{ \sstsubsection{ \htmlref{astColumnNull}{astColumnNull}() }{ The number of bytes required to store the column data. } } \sstnotes{ \sstitemlist{ \sstitem An error will be reported if the named column does not exist in the \htmlref{FitsTable}{FitsTable}. \sstitem Zero will be returned as the function value in an error occurs. } } } \sstroutine{ astConvert }{ Determine how to convert between two coordinate systems }{ \sstdescription{ This function compares two Frames and determines whether it is possible to convert between the coordinate systems which they represent. If conversion is possible, it returns a \htmlref{FrameSet}{FrameSet} which describes the conversion and which may be used (as a \htmlref{Mapping}{Mapping}) to transform coordinate values in either direction. The same function may also be used to determine how to convert between two FrameSets (or between a \htmlref{Frame}{Frame} and a FrameSet, or vice versa). This mode is intended for use when (for example) two images have been calibrated by attaching a FrameSet to each. astConvert might then be used to search for a celestial coordinate system that both images have in common, and the result could then be used to convert between the pixel coordinates of both images -- having effectively used their celestial coordinate systems to align them. When using FrameSets, there may be more than one possible intermediate coordinate system in which to perform the conversion (for instance, two FrameSets might both have celestial coordinates, detector coordinates, pixel coordinates, etc.). A comma-separated list of coordinate system domains may therefore be given which defines a priority order to use when selecting the intermediate coordinate system. The path used for conversion must go via an intermediate coordinate system whose \htmlref{Domain}{Domain} attribute matches one of the domains given. If conversion cannot be achieved using the first domain, the next one is considered, and so on, until success is achieved. } \sstsynopsis{ AstFrameSet $*$astConvert( AstFrame $*$from, AstFrame $*$to, const char $*$domainlist ) } \sstparameters{ \sstsubsection{ from }{ Pointer to a Frame which represents the \texttt{"} source\texttt{"} coordinate system. This is the coordinate system in which you already have coordinates available. If a FrameSet is given, its current Frame (as determined by its \htmlref{Current}{Current} attribute) is taken to describe the source coordinate system. Note that the \htmlref{Base}{Base} attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). } \sstsubsection{ to }{ Pointer to a Frame which represents the \texttt{"} destination\texttt{"} coordinate system. This is the coordinate system into which you wish to convert your coordinates. If a FrameSet is given, its current Frame (as determined by its Current attribute) is taken to describe the destination coordinate system. Note that the Base attribute of this FrameSet may be modified by this function to indicate which intermediate coordinate system was used (see under \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). } \sstsubsection{ 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 an intermediate coordinate system whose Domain attribute matches the first domain in this list. If this fails, the second domain in the list will be used, and so on, until conversion is achieved. A blank domain (e.g. two consecutive commas) indicates that all coordinate systems should be considered, regardless of their domains. This list is case-insensitive and all white space is ignored. If you do not wish to restrict the domain in this way, you should supply an empty string. This is normally appropriate if either of the source or destination coordinate systems are described by Frames (rather than FrameSets), since there is then usually only one possible choice of intermediate coordinate system. } } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ If the \htmlref{AlignSideBand}{AlignSideBand} attribute is non-zero, alignment occurs in the upper sideband expressed within the spectral system and standard of rest given by attributes \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}. If AlignSideBand is zero, the two DSBSpecFrames are aligned as if they were simple SpecFrames (i.e. the \htmlref{SideBand}{SideBand} is ignored). } \sstsubsection{ Frame }{ This function applies to all Frames. Alignment occurs within the coordinate system given by attribute AlignSystem. } \sstsubsection{ FrameSet }{ If either of the \texttt{"} from\texttt{"} or \texttt{"} to\texttt{"} parameters is a pointer to a FrameSet, then astConvert will attempt to convert from the coordinate system described by the current Frame of the \texttt{"} from\texttt{"} FrameSet to that described by the current Frame of the \texttt{"} to\texttt{"} FrameSet. To achieve this, it will consider all of the Frames within each FrameSet as a possible way of reaching an intermediate coordinate system that can be used for the conversion. There is then the possibility that more than one conversion path may exist and, unless the choice is sufficiently restricted by the \texttt{"} domainlist\texttt{"} string, the sequence in which the Frames are considered can be important. In this case, the search for a conversion path proceeds as follows: \sstitemlist{ \sstitem Each field in the \texttt{"} domainlist\texttt{"} string is considered in turn. \sstitem The Frames within each FrameSet are considered in a specific order: (1) the base Frame is always considered first, (2) after this come all the other Frames in Frame-index order (but omitting the base and current Frames), (3) the current Frame is always considered last. However, if either FrameSet\texttt{'} s \htmlref{Invert}{Invert} attribute is set to a non-zero value (so that the FrameSet is inverted), then its Frames are considered in reverse order. (Note that this still means that the base Frame is considered first and the current Frame last, because the Invert value will also cause these Frames to swap places.) \sstitem All source Frames are first considered (in the appropriate order) for conversion to the first destination Frame. If no suitable intermediate coordinate system emerges, they are then considered again for conversion to the second destination Frame (in the appropriate order), and so on. \sstitem Generally, the first suitable intermediate coordinate system found is used. However, the overall Mapping between the source and destination coordinate systems is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one transformation is defined, the forward one is preferred. \sstitem If the domain of the intermediate coordinate system matches the current \texttt{"} domainlist\texttt{"} field, the conversion path is accepted. Otherwise, the next \texttt{"} domainlist\texttt{"} field is considered and the process repeated. } If conversion is possible, the Base attributes of the two FrameSets will be modified on exit to identify the Frames used to access the intermediate coordinate system which was finally accepted. Note that it is possible to force a particular Frame within a FrameSet to be used as the basis for the intermediate coordinate system, if it is suitable, by (a) focussing attention on it by specifying its domain in the \texttt{"} domainlist\texttt{"} string, or (b) making it the base Frame, since this is always considered first. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ Alignment occurs within the spectral system and standard of rest given by attributes AlignSystem and AlignStdOfRest. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ Alignment occurs within the time system and time scale given by attributes AlignSystem and \htmlref{AlignTimeScale}{AlignTimeScale}. } } \sstreturnedvalue{ \sstsubsection{ astConvert() }{ If the requested coordinate conversion is possible, the function returns a pointer to a FrameSet which describes the conversion. Otherwise, a null \htmlref{Object}{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 \texttt{"} from\texttt{"} parameter. Frame number 2 (its current Frame) will describe the destination coordinate system, corresponding to the \texttt{"} to\texttt{"} parameter. The Mapping which inter-relates these two Frames will perform the required conversion between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates from the source to the destination coordinate system (or vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the destination coordinate system. } } \sstexamples{ \sstexamplesubsection{ cvt = astConvert( a, b, \texttt{"} \texttt{"} ); }{ Attempts to convert between the coordinate systems represented by \texttt{"} a\texttt{"} and \texttt{"} b\texttt{"} (assumed to be Frames). If successful, a FrameSet is returned via the \texttt{"} cvt\texttt{"} pointer which may be used to apply the conversion to sets of coordinates (e.g. using astTran2). } \sstexamplesubsection{ cvt = astConvert( \htmlref{astSkyFrame}{astSkyFrame}(\texttt{"} \texttt{"} ), astSkyFrame(\texttt{"} \htmlref{Equinox}{Equinox}=2005\texttt{"} ), \texttt{"} \texttt{"} ); }{ Creates a FrameSet which describes precession in the default FK5 celestial coordinate system between equinoxes J2000 (also the default) and J2005. The returned \texttt{"} cvt\texttt{"} pointer may then be passed to astTran2 to apply this precession correction to any number of coordinate values given in radians. Note that the returned FrameSet also contains information about how to format coordinate values. This means that setting its \htmlref{Report}{Report} attribute to 1 is a simple way to obtain printed output (formatted in sexagesimal notation) to show the coordinate values before and after conversion. } \sstexamplesubsection{ cvt = astConvert( a, b, \texttt{"} sky,detector,\texttt{"} ); }{ Attempts to convert between the coordinate systems represented by the current Frames of \texttt{"} a\texttt{"} and \texttt{"} b\texttt{"} (now assumed to be FrameSets), via the intermediate \texttt{"} SKY\texttt{"} coordinate system. This, by default, is the Domain associated with a celestial coordinate system represented by a \htmlref{SkyFrame}{SkyFrame}. If this fails (for example, because either FrameSet lacks celestial coordinate information), then the user-defined \texttt{"} DETECTOR\texttt{"} coordinate system is used instead. If this also fails, then all other possible ways of achieving conversion are considered before giving up. The returned pointer \texttt{"} cvt\texttt{"} indicates whether conversion was possible and will have the value AST\_\_NULL if it was not. If conversion was possible, \texttt{"} cvt\texttt{"} will point at a new FrameSet describing the conversion. The Base attributes of the two FrameSets will be set by astConvert to indicate which of their Frames was used for the intermediate coordinate system. This means that you can subsequently determine which coordinate system was used by enquiring the Domain attribute of either base Frame. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the AlignSystem attribute of the \texttt{"} to\texttt{"} Frame. See the description of the AlignSystem attribute for further details. \sstitem When aligning (say) two images, which have been calibrated by attaching FrameSets to them, it is usually necessary to convert between the base Frames (representing \texttt{"} native\texttt{"} pixel coordinates) of both FrameSets. This may be achieved by inverting the FrameSets (e.g. using \htmlref{astInvert}{astInvert}) so as to interchange their base and current Frames before using astConvert. \sstitem 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. } } } \sstroutine{ astConvex$<$X$>$ }{ Create a new Polygon representing the convex hull of a 2D data grid }{ \sstdescription{ This is a set of functions that create the shortest \htmlref{Polygon}{Polygon} that encloses all pixels with a specified value within a gridded 2-dimensional data array (e.g. an image). A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter \texttt{"} starpix\texttt{"} . You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astConvex$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are procesing data with type \texttt{"} float\texttt{"} , you should use the function astConvexF (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstsynopsis{ AstPolygon $*$astConvex$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], const int lbnd[2], const int ubnd[2], int starpix ) } \sstparameters{ \sstsubsection{ value }{ A data value that specifies the pixels to be included within the convex hull. } \sstsubsection{ oper }{ Indicates how the \texttt{"} value\texttt{"} parameter is used to select the required pixels. It can have any of the following values: \sstitemlist{ \sstitem AST\_\_LT: include pixels with value less than \texttt{"} value\texttt{"} . \sstitem AST\_\_LE: include pixels with value less than or equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_EQ: include pixels with value equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_NE: include pixels with value not equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_GE: include pixels with value greater than or equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_GT: include pixels with value greater than \texttt{"} value\texttt{"} . } } \sstsubsection{ array }{ Pointer to a 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astConvexF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ lbnd }{ Pointer to an array of two integers containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd }{ Pointer to an array of two integers containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter \texttt{"} starpix\texttt{"} . } \sstsubsection{ starpix }{ A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If non-zero, the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If zero, the definition of pixel coordinate used by other AST functions such as astResample, astMask, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). } } \sstreturnedvalue{ \sstsubsection{ astConvex$<$X$>$() }{ A pointer to the required Polygon. NULL is returned without error if the array contains no pixels that satisfy the criterion specified by \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astConvex$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem L: long int \sstitem UL: unsigned long int \sstitem I: int \sstitem UI: unsigned int \sstitem S: short int \sstitem US: unsigned short int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astConvexD would be used to process \texttt{"} double\texttt{"} data, while astConvexS would be used to process \texttt{"} short int\texttt{"} data, etc. } } \sstroutine{ astCopy }{ Copy an Object }{ \sstdescription{ This function creates a copy of an \htmlref{Object}{Object} and returns a pointer to the resulting new Object. It makes a \texttt{"} deep\texttt{"} copy, which contains no references to any other Object (i.e. if the original Object contains references to other Objects, then the actual data are copied, not simply the references). This means that modifications may safely be made to the copy without indirectly affecting any other Object. } \sstsynopsis{ AstObject $*$astCopy( const AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be copied. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astCopy() }{ Pointer to the new Object. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astCurrentTime }{ Return the current system time }{ \sstdescription{ This function returns the current system time, represented in the form specified by the supplied \htmlref{TimeFrame}{TimeFrame}. That is, the returned floating point value should be interpreted using the attribute values of the TimeFrame. This includes \htmlref{System}{System}, \htmlref{TimeOrigin}{TimeOrigin}, \htmlref{LTOffset}{LTOffset}, \htmlref{TimeScale}{TimeScale}, and Unit. } \sstsynopsis{ double astCurrentTime( AstTimeFrame $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the TimeFrame. } } \sstreturnedvalue{ \sstsubsection{ astCurrentTime() }{ A TimeFrame axis value representing the current system time. } } \sstnotes{ \sstitemlist{ \sstitem Values of AST\_\_BAD will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. \sstitem It is assumes that the system time (returned by the C time() function) follows the POSIX standard, representing a continuous monotonic increasing count of SI seconds since the epoch 00:00:00 UTC 1 January 1970 AD (equivalent to TAI with a constant offset). Resolution is one second. \sstitem An error will be reported if the TimeFrame has a TimeScale value which cannot be converted to TAI (e.g. \texttt{"} angular\texttt{"} systems such as UT1, GMST, LMST and LAST). \sstitem Any inaccuracy in the system clock will be reflected in the value returned by this function. } } } \sstroutine{ astCurve }{ Draw a geodesic curve }{ \sstdescription{ This function draws a geodesic curve between two points in the physical coordinate system of a \htmlref{Plot}{Plot}. The curve drawn is the path of shortest distance joining the two points (as defined by the \htmlref{astDistance}{astDistance} function for the current \htmlref{Frame}{Frame} of the Plot). For example, if the current Frame is a basic Frame, then the curve joining the two points will be a straight line in physical coordinate space. If the current Frame is more specialised and describes, for instance, a sky coordinate system, then the geodesic curve would be a great circle in physical coordinate space passing through the two sky positions given. Note that the geodesic curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{astClip}{astClip}. If you need to draw many geodesic curves end-to-end, then the \htmlref{astPolyCurve}{astPolyCurve} function is equivalent to repeatedly using astCurve, but will usually be more efficient. If you need to draw curves which are not geodesics, see \htmlref{astGenCurve}{astGenCurve} or \htmlref{astGridLine}{astGridLine}. } \sstsynopsis{ void astCurve( AstPlot $*$this, const double start[], const double finish[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ start }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the first point on the geodesic curve. } \sstsubsection{ finish }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the second point on the geodesic curve. } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn if either of the \texttt{"} start\texttt{"} or \texttt{"} finish\texttt{"} arrays contains any coordinates with the value AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astDSBSpecFrame }{ Create a DSBSpecFrame }{ \sstdescription{ This function creates a new \htmlref{DSBSpecFrame}{DSBSpecFrame} and optionally initialises its attributes. A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents positions in a spectrum obtained using a dual sideband instrument. Such an instrument produces a spectrum in which each point contains contributions from two distinctly different frequencies, one from the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). Corresponding LSB and USB frequencies are connected by the fact that they are an equal distance on either side of a fixed central frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. When quoting a position within such a spectrum, it is necessary to indicate whether the quoted position is the USB position or the corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this indication. Another option that the SideBand attribute provides is to represent a spectral position by its topocentric offset from the LO frequency. In practice, the LO frequency is specified by giving the distance from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically this central position is that of some interesting spectral feature. The distance from this central position to the LO frequency is known as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can be a signed value in order to indicate whether the LO frequency is above or below the central position. } \sstsynopsis{ AstDSBSpecFrame $*$astDSBSpecFrame( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new DSBSpecFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astDSBSpecFrame() }{ A pointer to the new DSBSpecFrame. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astDecompose }{ Decompose a Mapping into two component Mappings }{ \sstdescription{ This function returns pointers to two Mappings which, when applied either in series or parallel, are equivalent to the supplied \htmlref{Mapping}{Mapping}. Since the \htmlref{Frame}{Frame} class inherits from the Mapping class, Frames can be considered as special types of Mappings and so this method can be used to decompose either CmpMaps or CmpFrames. } \sstsynopsis{ void astDecompose( AstMapping $*$this, AstMapping $*$$*$map1, AstMapping $*$$*$map2, int $*$series, int $*$invert1, int $*$invert2 ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping. } \sstsubsection{ map1 }{ Address of a location to receive a pointer to first component Mapping. } \sstsubsection{ map2 }{ Address of a location to receive a pointer to second component Mapping. } \sstsubsection{ series }{ Address of a location to receive a value indicating if the component Mappings are applied in series or parallel. A non-zero value means that the supplied Mapping is equivalent to applying map1 followed by map2 in series. A zero value means that the supplied Mapping is equivalent to applying map1 to the lower numbered axes and map2 to the higher numbered axes, in parallel. } \sstsubsection{ invert1 }{ The value of the \htmlref{Invert}{Invert} attribute to be used with map1. } \sstsubsection{ invert2 }{ The value of the Invert attribute to be used with map2. } } \sstapplicability{ \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If the supplied Mapping is a CmpMap, then map1 and map2 will be returned holding pointers to the component Mappings used to create the CmpMap, either in series or parallel. Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied CmpMap. This is because the CmpMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the CmpMap was first created). These are the Invert values which are returned in invert1 and invert2. } \sstsubsection{ \htmlref{TranMap}{TranMap} }{ If the supplied Mapping is a TranMap, then map1 and map2 will be returned holding pointers to the forward and inverse Mappings represented by the TranMap (zero will be returned for series). Note, changing the Invert attribute of either of the component Mappings using the returned pointers will have no effect on the supplied TranMap. This is because the TranMap remembers and uses the original settings of the Invert attributes (that is, the values of the Invert attributes when the TranMap was first created). These are the Invert values which are returned in invert1 and invert2. } \sstsubsection{ Mapping }{ For any class of Mapping other than a CmpMap, map1 will be returned holding a clone of the supplied Mapping pointer, and map2 will be returned holding a NULL pointer. Invert1 will be returned holding the current value of the Invert attribute for the supplied Mapping, and invert2 will be returned holding zero. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ If the supplied Mapping is a CmpFrame, then map1 and map2 will be returned holding pointers to the component Frames used to create the CmpFrame. The component Frames are considered to be in applied in parallel. } \sstsubsection{ Frame }{ For any class of Frame other than a CmpFrame, map1 will be returned holding a clone of the supplied Frame pointer, and map2 will be returned holding a NULL pointer. } } \sstnotes{ \sstitemlist{ \sstitem The returned Invert values should be used in preference to the current values of the Invert attribute in map1 and map2. This is because the attributes may have changed value since the Mappings were combined. \sstitem Any changes made to the component Mappings using the returned pointers will be reflected in the supplied Mapping. } } } \sstroutine{ astDelFits }{ Delete the current FITS card in a FitsChan }{ \sstdescription{ This function deletes the current FITS card from a \htmlref{FitsChan}{FitsChan}. The current card may be selected using the \htmlref{Card}{Card} attribute (if its index is known) or by using \htmlref{astFindFits}{astFindFits} (if only the FITS keyword is known). After deletion, the following card becomes the current card. } \sstsynopsis{ void astDelFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if the FitsChan is initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the Card attribute exceeds the number of cards in the FitsChan). \sstitem If there are no subsequent cards in the FitsChan, then the Card attribute is left pointing at the \texttt{"} end-of-file\texttt{"} after deletion (i.e. is set to one more than the number of cards in the FitsChan). } } } \sstroutine{ astDelete }{ Delete an Object }{ \sstdescription{ This function deletes an \htmlref{Object}{Object}, freeing all resources associated with it and rendering any remaining pointers to the Object invalid. Note that deletion is unconditional, regardless of whether other pointers to the Object are still in use (possibly within other Objects). A safer approach is to defer deletion, until all references to an Object have expired, by using \htmlref{astBegin}{astBegin}/\htmlref{astEnd}{astEnd} (together with \htmlref{astClone}{astClone} and \htmlref{astAnnul}{astAnnul} if necessary). } \sstsynopsis{ AstObject $*$astDelete( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be deleted. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astDelete() }{ A null Object pointer (AST\_\_NULL) is always returned. } } \sstnotes{ \sstitemlist{ \sstitem This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. } } } \sstroutine{ astDistance }{ Calculate the distance between two points in a Frame }{ \sstdescription{ This function finds the distance between two points whose \htmlref{Frame}{Frame} coordinates are given. The distance calculated is that along the geodesic curve that joins the two points. For example, in a basic Frame, the distance calculated will be the Cartesian distance along the straight line joining the two points. For a more specialised Frame describing a sky coordinate system, however, it would be the distance along the great circle passing through two sky positions. } \sstsynopsis{ double astDistance( AstFrame $*$this, const double point1[], const double point2[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ point1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. } \sstsubsection{ point2 }{ An array of double, with one element for each Frame axis containing the coordinates of the second point. } } \sstreturnedvalue{ \sstsubsection{ astDistance }{ The distance between the two points. } } \sstnotes{ \sstitemlist{ \sstitem This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if any of the input coordinates has this value. \sstitem A \texttt{"} bad\texttt{"} value will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astDownsize }{ Reduce the number of vertices in a Polygon }{ \sstdescription{ This function returns a pointer to a new \htmlref{Polygon}{Polygon} that contains a subset of the vertices in the supplied Polygon. The subset is chosen so that the returned Polygon is a good approximation to the supplied Polygon, within the limits specified by the supplied parameter values. That is, the density of points in the returned Polygon is greater at points where the curvature of the boundary of the supplied Polygon is greater. } \sstsynopsis{ AstPolygon $*$astDownsize( AstPolygon $*$this, double maxerr, int maxvert ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Polygon. } \sstsubsection{ maxerr }{ The maximum allowed discrepancy between the supplied and returned Polygons, expressed as a geodesic distance within the Polygon\texttt{'} s coordinate frame. If this is zero or less, the returned Polygon will have the number of vertices specified by maxvert. } \sstsubsection{ maxvert }{ The maximum allowed number of vertices in the returned Polygon. If this is less than 3, the number of vertices in the returned Polygon will be the minimum needed to achieve the maximum discrepancy specified by maxerr. } } \sstreturnedvalue{ \sstsubsection{ astDownsize() }{ Pointer to the new Polygon. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astEBuf }{ End the current graphical buffering context }{ \sstdescription{ This function ends the current graphics buffering context. It should match a corresponding call to the \htmlref{astBBuf}{astBBuf} function. } \sstsynopsis{ void astEBuf( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Plot}{Plot}. } } \sstnotes{ \sstitemlist{ \sstitem The nature of the buffering is determined by the underlying graphics system (as defined by the current grf module). Each call to this function simply invokes the astGEBuf function in the grf module. } } } \sstroutine{ astEllipse }{ Create a Ellipse }{ \sstdescription{ This function creates a new \htmlref{Ellipse}{Ellipse} and optionally initialises its attributes. A Ellipse is a \htmlref{Region}{Region} which represents a elliptical area within the supplied 2-dimensional \htmlref{Frame}{Frame}. } \sstsynopsis{ AstEllipse $*$astEllipse( AstFrame $*$frame, int form, const double centre[2], const double point1[2], const double point2[2], AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ form }{ Indicates how the ellipse is described by the remaining parameters. A value of zero indicates that the ellipse is specified by a centre position and two positions on the circumference. A value of one indicates that the ellipse is specified by its centre position, the half-lengths of its two axes, and the orientation of its first axis. } \sstsubsection{ centre }{ An array of 2 doubles, containing the coordinates at the centre of the ellipse. } \sstsubsection{ point1 }{ An array of 2 doubles. If \texttt{"} form\texttt{"} is zero, this array should contain the coordinates of one of the four points where an axis of the ellipse crosses the circumference of the ellipse. If \texttt{"} form\texttt{"} is one, it should contain the lengths of semi-major and semi-minor axes of the ellipse, given as geodesic distances within the Frame. } \sstsubsection{ point2 }{ An array of 2 doubles. If \texttt{"} form\texttt{"} is zero, this array should containing the coordinates at some other point on the circumference of the ellipse, distinct from \texttt{"} point1\texttt{"} . If \texttt{"} form\texttt{"} is one, the first element of this array should hold the angle between the second axis of the Frame and the first ellipse axis (i.e. the ellipse axis which is specified first in the \texttt{"} point1\texttt{"} array), and the second element will be ignored. The angle should be given in radians, measured positive in the same sense as rotation from the positive direction of the second Frame axis to the positive direction of the first Frame axis. } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Ellipse being created. The uncertainty in any point on the boundary of the Ellipse is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, Ellipse, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Ellipse. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Ellipse being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Ellipse. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astEllipse() }{ A pointer to the new Ellipse. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astEllipsePars }{ Returns the geometric parameters of an Ellipse }{ \sstdescription{ This function returns the geometric parameters describing the supplied ellipse. } \sstsynopsis{ void astEllipsePars( AstEllipse $*$this, double centre[2], double $*$a, double $*$b, double $*$angle, double p1[2], double p2[2] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Region}{Region}. } \sstsubsection{ centre }{ The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays. } \sstsubsection{ a }{ Returned holding the half-length of the first axis of the ellipse. } \sstsubsection{ b }{ Returned holding the half-length of the second axis of the ellipse. } \sstsubsection{ angle }{ If the coordinate system in which the Ellipse is defined has axes (X,Y), then \texttt{"} $*$angle\texttt{"} is returned holding the angle from the positive direction of the Y axis to the first axis of the ellipse, in radians. Positive rotation is in the same sense as rotation from the positive direction of Y to the positive direction of X. } \sstsubsection{ p1 }{ An array in which to return the coordinates at one of the two ends of the first axis of the ellipse. A NULL pointer can be supplied if these coordinates are not needed. } \sstsubsection{ p2 }{ An array in which to return the coordinates at one of the two ends of the second axis of the ellipse. A NULL pointer can be supplied if these coordinates are not needed. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Ellipse has been changed since it was first created, the returned parameters refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape represented by the supplied Ellipse object may not be an accurate ellipse. \sstitem Values of AST\_\_BAD are returned for the parameters without error if the ellipse is degenerate or undefined. } } } \sstroutine{ astEmptyFits }{ Delete all cards in a FitsChan }{ \sstdescription{ This function deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}. } \sstsynopsis{ void astEmptyFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem This method simply deletes the cards currently in the FitsChan. Unlike \htmlref{astWriteFits}{astWriteFits}, they are not first written out to the sink function or sink file. \sstitem Any Tables or warnings stored in the FitsChan are also deleted. \sstitem This method attempt to execute even if an error has occurred previously. } } } \sstroutine{ astEnd }{ End an AST context }{ \sstdescription{ This macro invokes a function to end an AST context which was begun with a matching invocation of \htmlref{astBegin}{astBegin}. Any \htmlref{Object}{Object} pointers created within this context will be annulled (just as if \htmlref{astAnnul}{astAnnul} had been invoked) and will cease to be valid afterwards, unless they have previously been exported using \htmlref{astExport}{astExport} or rendered exempt using \htmlref{astExempt}{astExempt}. If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to fall to zero (which happens when the last pointer to it is annulled), then the Object will be deleted. } \sstsynopsis{ void astEnd } \sstapplicability{ \sstsubsection{ Object }{ This macro applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem astEnd attempts to execute even if the AST error status is set. \sstitem Contexts delimited by astBegin and astEnd may be nested to any depth. } } } \sstroutine{ astEscapes }{ Control whether graphical escape sequences are included in strings }{ \sstdescription{ The \htmlref{Plot}{Plot} class defines a set of escape sequences which can be included within a text string in order to control the appearance of sub-strings within the text. See the \htmlref{Escape}{Escape} attribute for a description of these escape sequences. It is usually inappropriate for AST to return strings containing such escape sequences when called by application code. For instance, an application which displays the value of the \htmlref{Title}{Title} attribute of a \htmlref{Frame}{Frame} usually does not want the displayed string to include potentially long escape sequences which a human read would have difficuly interpreting. Therefore the default behaviour is for AST to strip out such escape sequences when called by application code. This default behaviour can be changed using this function. } \sstsynopsis{ int astEscapes( int new\_value ) } \sstparameters{ \sstsubsection{ new\_value }{ A flag which indicates if escapes sequences should be included in returned strings. If zero is supplied, escape sequences will be stripped out of all strings returned by any AST function. If a positive value is supplied, then any escape sequences will be retained in the value returned to the caller. If a negative value is supplied, the current value of the flag will be left unchanged. } } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ This macro applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astEscapes }{ The value of the flag on entry to this function. } } \sstnotes{ \sstitemlist{ \sstitem This function also controls whether the \htmlref{astStripEscapes}{astStripEscapes} function removes escape sequences from the supplied string, or returns the supplied string without change. \sstitem This function attempts to execute even if an error has already occurred. } } } \sstroutine{ astExempt }{ Exempt an Object pointer from AST context handling }{ \sstdescription{ This function exempts an \htmlref{Object}{Object} pointer from AST context handling, as implemented by \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}. This means that the pointer will not be affected when astEnd is invoked and will remain active until the end of the program, or until explicitly annulled using \htmlref{astAnnul}{astAnnul}. If possible, you should avoid using this function when writing applications. It is provided mainly for developers of other libraries, who may wish to retain references to AST Objects in internal data structures, and who therefore need to avoid the effects of astBegin and astEnd. } \sstsynopsis{ void astExempt( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Object pointer to be exempted from context handling. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } } \sstroutine{ astExport }{ Export an Object pointer to an outer context }{ \sstdescription{ This function exports an \htmlref{Object}{Object} pointer from the current AST context into the context that encloses the current one. This means that the pointer will no longer be annulled when the current context is ended (with \htmlref{astEnd}{astEnd}), but only when the next outer context (if any) ends. } \sstsynopsis{ void astExport( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Object pointer to be exported. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem It is only sensible to apply this function to pointers that have been created within (or exported to) the current context and have not been rendered exempt using \htmlref{astExempt}{astExempt}. Applying it to an unsuitable Object pointer has no effect. } } } \sstroutine{ astFindFits }{ Find a FITS card in a FitsChan by keyword }{ \sstdescription{ This function searches for a card in a \htmlref{FitsChan}{FitsChan} by keyword. The search commences at the current card (identified by the \htmlref{Card}{Card} attribute) and ends when a card is found whose FITS keyword matches the template supplied, or when the last card in the FitsChan has been searched. If the search is successful (i.e. a card is found which matches the template), the contents of the card are (optionally) returned and the Card attribute is adjusted to identify the card found or, if required, the one following it. If the search is not successful, the function returns zero and the Card attribute is set to the \texttt{"} end-of-file\texttt{"} . } \sstsynopsis{ int astFindFits( AstFitsChan $*$this, const char $*$name, char card[ 81 ], int inc ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ name }{ Pointer to a null-terminated character string containing a template for the keyword to be found. In the simplest case, this should simply be the keyword name (the search is case insensitive and trailing spaces are ignored). However, this template may also contain \texttt{"} field specifiers\texttt{"} which are capable of matching a range of characters (see the \texttt{"} Keyword Templates\texttt{"} section for details). In this case, the first card with a keyword which matches the template will be found. To find the next FITS card regardless of its keyword, you should use the template \texttt{"} \%f\texttt{"} . } \sstsubsection{ card }{ An array of at least 81 characters (to allow room for a terminating null) in which the FITS card which is found will be returned. If the search is not successful (or a NULL pointer is given), a card will not be returned. } \sstsubsection{ inc }{ If this value is zero (and the search is successful), the FitsChan\texttt{'} s Card attribute will be set to the index of the card that was found. If it is non-zero, however, the Card attribute will be incremented to identify the card which follows the one found. } } \sstreturnedvalue{ \sstsubsection{ astFindFits() }{ One if the search was successful, otherwise zero. } } \sstexamples{ \sstexamplesubsection{ result = astFindFits( fitschan, \texttt{"} \%f\texttt{"} , card, 1 ); }{ Returns the current card in a FitsChan and advances the Card attribute to identify the card that follows (the \texttt{"} \%f\texttt{"} template matches any keyword). } \sstexamplesubsection{ result = astFindFits( fitschan, \texttt{"} BITPIX\texttt{"} , card, 1 ); }{ Searches a FitsChan for a FITS card with the \texttt{"} BITPIX\texttt{"} keyword and returns that card. The Card attribute is then incremented to identify the card that follows it. } \sstexamplesubsection{ result = astFindFits( fitschan, \texttt{"} COMMENT\texttt{"} , NULL, 0 ); }{ Sets the Card attribute of a FitsChan to identify the next COMMENT card (if any). The card itself is not returned. } \sstexamplesubsection{ result = astFindFits( fitschan, \texttt{"} CRVAL\%1d\texttt{"} , card, 1 ); }{ Searches a FitsChan for the next card with a keyword of the form \texttt{"} CRVALi\texttt{"} (for example, any of the keywords \texttt{"} CRVAL1\texttt{"} , \texttt{"} CRVAL2\texttt{"} or \texttt{"} CRVAL3\texttt{"} would be matched). The card found (if any) is returned, and the Card attribute is then incremented to identify the following card (ready to search for another keyword with the same form, perhaps). } } \sstnotes{ \sstitemlist{ \sstitem The search always starts with the current card, as identified by the Card attribute. To ensure you search the entire contents of a FitsChan, you should first clear the Card attribute (using \htmlref{astClear}{astClear}). This effectively \texttt{"} rewinds\texttt{"} the FitsChan. \sstitem If a search is unsuccessful, the Card attribute is set to the \texttt{"} end-of-file\texttt{"} (i.e. to one more than the number of cards in the FitsChan). No error occurs. \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } \sstdiytopic{ Keyword Templates }{ The templates used to match FITS keywords are normally composed of literal characters, which must match the keyword exactly (apart from case). However, a template may also contain \texttt{"} field specifiers\texttt{"} which can match a range of possible characters. This allows you to search for keywords that contain (for example) numbers, where the digits comprising the number are not known in advance. A field specifier starts with a \texttt{"} \%\texttt{"} character. This is followed by an optional single digit (0 to 9) specifying a field width. Finally, there is a single character which specifies the type of character to be matched, as follows: \sstitemlist{ \sstitem \texttt{"} c\texttt{"} : matches all upper case letters, \sstitem \texttt{"} d\texttt{"} : matches all decimal digits, \sstitem \texttt{"} f\texttt{"} : matches all characters which are permitted within a FITS keyword (upper case letters, digits, underscores and hyphens). } If the field width is omitted, the field specifier matches one or more characters. If the field width is zero, it matches zero or more characters. Otherwise, it matches exactly the number of characters specified. In addition to this: \sstitemlist{ \sstitem The template \texttt{"} \%f\texttt{"} will match a blank FITS keyword consisting of 8 spaces (as well as matching all other keywords). \sstitem A template consisting of 8 spaces will match a blank keyword (only). } For example: \sstitemlist{ \sstitem The template \texttt{"} BitPix\texttt{"} will match the keyword \texttt{"} BITPIX\texttt{"} only. \sstitem The template \texttt{"} crpix\%1d\texttt{"} will match keywords consisting of \texttt{"} CRPIX\texttt{"} followed by one decimal digit. \sstitem The template \texttt{"} P\%c\texttt{"} will match any keyword starting with \texttt{"} P\texttt{"} and followed by one or more letters. \sstitem The template \texttt{"} E\%0f\texttt{"} will match any keyword beginning with \texttt{"} E\texttt{"} . \sstitem The template \texttt{"} \%f\texttt{"} will match any keyword at all (including a blank one). } } } \sstroutine{ astFindFrame }{ Find a coordinate system with specified characteristics }{ \sstdescription{ This function uses a \texttt{"} template\texttt{"} \htmlref{Frame}{Frame} to search another Frame (or \htmlref{FrameSet}{FrameSet}) to identify a coordinate system which has a specified set of characteristics. If a suitable coordinate system can be found, the function returns a pointer to a FrameSet which describes the required coordinate system and how to convert coordinates to and from it. This function is provided to help answer general questions about coordinate systems, such as typically arise when coordinate information is imported into a program as part of an initially unknown dataset. For example: \sstitemlist{ \sstitem Is there a wavelength scale? \sstitem Is there a 2-dimensional coordinate system? \sstitem Is there a celestial coordinate system? \sstitem Can I plot the data in ecliptic coordinates? } You can also use this function as a means of reconciling a user\texttt{'} s preference for a particular coordinate system (for example, what type of axes to draw) with what is actually possible given the coordinate information available. To perform a search, you supply a \texttt{"} target\texttt{"} Frame (or FrameSet) which represents the set of coordinate systems to be searched. If a basic Frame is given as the target, this set of coordinate systems consists of the one described by this Frame, plus all other \texttt{"} virtual\texttt{"} coordinate systems which can potentially be reached from it by applying built-in conversions (for example, any of the celestial coordinate conversions known to the AST library would constitute a \texttt{"} built-in\texttt{"} conversion). If a FrameSet is given as the target, the set of coordinate systems to be searched consists of the union of those represented by all the individual Frames within it. To select from this large set of possible coordinate systems, you supply a \texttt{"} template\texttt{"} Frame which is an instance of the type of Frame you are looking for. Effectively, you then ask the function to \texttt{"} find a coordinate system that looks like this\texttt{"} . You can make your request more or less specific by setting attribute values for the template Frame. If a particular attribute is set in the template, then the function will only find coordinate systems which have exactly the same value for that attribute. If you leave a template attribute un-set, however, then the function has discretion about the value the attribute should have in any coordinate system it finds. The attribute will then take its value from one of the actual (rather than virtual) coordinate systems in the target. If the target is a FrameSet, its \htmlref{Current}{Current} attribute will be modified to indicate which of its Frames was used for this purpose. The result of this process is a coordinate system represented by a hybrid Frame which acquires some attributes from the template (but only if they were set) and the remainder from the target. This represents the \texttt{"} best compromise\texttt{"} between what you asked for and what was available. A \htmlref{Mapping}{Mapping} is then generated which converts from the target coordinate system to this hybrid one, and the returned FrameSet encapsulates all of this information. } \sstsynopsis{ AstFrameSet $*$astFindFrame( AstFrame $*$target, AstFrame $*$template, const char $*$domainlist ) } \sstparameters{ \sstsubsection{ target }{ Pointer to the target Frame (or FrameSet). Note that if a FrameSet is supplied (and a suitable coordinate system is found), then its Current attribute will be modified to indicate which Frame was used to obtain attribute values which were not specified by the template. This Frame will, in some sense, represent the \texttt{"} closest\texttt{"} non-virtual coordinate system to the one you requested. } \sstsubsection{ template }{ Pointer to the template Frame, which should be an instance of the type of Frame you wish to find. If you wanted to find a Frame describing a celestial coordinate system, for example, then you might use a \htmlref{SkyFrame}{SkyFrame} here. See the \texttt{"} Examples\texttt{"} section for more ideas. } \sstsubsection{ 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 \htmlref{Domain}{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. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. } \sstsubsection{ FrameSet }{ If the target is a FrameSet, the possibility exists that several of the Frames within it might be matched by the template. Unless the choice is sufficiently restricted by the \texttt{"} domainlist\texttt{"} string, the sequence in which Frames are searched can then become important. In this case, the search proceeds as follows: \sstitemlist{ \sstitem Each field in the \texttt{"} domainlist\texttt{"} string is considered in turn. \sstitem An attempt is made to match the template to each of the target\texttt{'} s Frames in the order: (1) the current Frame, (2) the base Frame, (3) each remaining Frame in the order of being added to the target FrameSet. \sstitem Generally, the first match found is used. However, the Mapping between the target coordinate system and the resulting Frame is also examined. Preference is given to cases where both the forward and inverse transformations are defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one transformation is defined, the forward one is preferred. \sstitem If a match is found and the domain of the resulting Frame also matches the current \texttt{"} domainlist\texttt{"} field, it is accepted. Otherwise, the next \texttt{"} domainlist\texttt{"} field is considered and the process repeated. } If a suitable coordinate system is found, the Current attribute of the target FrameSet will be modified on exit to identify the Frame whose match with the target was eventually accepted. } } \sstreturnedvalue{ \sstsubsection{ astFindFrame() }{ 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 \htmlref{Object}{Object} pointer (AST\_\_NULL) is returned without error. If a FrameSet is returned, it will contain two Frames. Frame number 1 (its base Frame) represents the target coordinate system and will be the same as the (base Frame of the) target. Frame number 2 (its current Frame) will be a Frame representing the coordinate system which the function found. The Mapping which inter-relates these two Frames will describe how to convert between their respective coordinate systems. Note that a FrameSet may be used both as a Mapping and as a Frame. If the result is used as a Mapping (e.g. with \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates from the target coordinate system into the new coordinate system that was found (and vice versa if its inverse transformation is selected). If it is used as a Frame, its attributes will describe the new coordinate system. } } \sstexamples{ \sstexamplesubsection{ result = astFindFrame( target, \htmlref{astFrame}{astFrame}( 3, \texttt{"} \texttt{"} ), \texttt{"} \texttt{"} ); }{ Searches for a 3-dimensional coordinate system in the target Frame (or FrameSet). No attributes have been set in the template Frame (created by astFrame), so no restriction has been placed on the required coordinate system, other than that it should have 3 dimensions. The first suitable Frame found will be returned as part of the \texttt{"} result\texttt{"} FrameSet. } \sstexamplesubsection{ result = astFindFrame( target, \htmlref{astSkyFrame}{astSkyFrame}( \texttt{"} \texttt{"} ), \texttt{"} \texttt{"} ); }{ Searches for a celestial coordinate system in the target Frame (or FrameSet). The type of celestial coordinate system is unspecified, so astFindFrame will return the first one found as part of the \texttt{"} result\texttt{"} FrameSet. If the target is a FrameSet, then its Current attribute will be updated to identify the Frame that was used. If no celestial coordinate system can be found, a value of AST\_\_NULL will be returned without error. } \sstexamplesubsection{ result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{MaxAxes}{MaxAxes}=100\texttt{"} ), \texttt{"} \texttt{"} ); }{ This is like the last example, except that in the event of the target being a \htmlref{CmpFrame}{CmpFrame}, the component Frames encapsulated by the CmpFrame will be searched for a SkyFrame. If found, the returned Mapping will included a \htmlref{PermMap}{PermMap} which selects the required axes from the target CmpFrame. This is acomplished by setting the MaxAxes attribute of the template SkyFrame to a large number (larger than or equal to the number of axes in the target CmpFrame). This allows the SkyFrame to be used as a match for Frames containing from 2 to 100 axes. } \sstexamplesubsection{ result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{System}{System}=FK5\texttt{"} ), \texttt{"} \texttt{"} ); }{ Searches for an equatorial (FK5) coordinate system in the target. The \htmlref{Equinox}{Equinox} value for the coordinate system has not been specified, so will be obtained from the target. If the target is a FrameSet, its Current attribute will be updated to indicate which SkyFrame was used to obtain this value. } \sstexamplesubsection{ result = astFindFrame( target, astFrame( 2, \texttt{"} \texttt{"} ), \texttt{"} sky,pixel,\texttt{"} ); }{ Searches for a 2-dimensional coordinate system in the target. Initially, a search is made for a suitable coordinate system whose Domain attribute has the value \texttt{"} SKY\texttt{"} . If this search fails, a search is then made for one with the domain \texttt{"} PIXEL\texttt{"} . If this also fails, then any 2-dimensional coordinate system is returned as part of the \texttt{"} result\texttt{"} FrameSet. Only if no 2-dimensional coordinate systems can be reached by applying built-in conversions to any of the Frames in the target will a value of AST\_\_NULL be returned. } \sstexamplesubsection{ result = astFindFrame( target, astFrame( 1, \texttt{"} Domain=WAVELENGTH\texttt{"} ), \texttt{"} \texttt{"} ); }{ Searches for any 1-dimensional coordinate system in the target which has the domain \texttt{"} WAVELENGTH\texttt{"} . } \sstexamplesubsection{ result = astFindFrame( target, astFrame( 1, \texttt{"} \texttt{"} ), \texttt{"} wavelength\texttt{"} ); }{ This example has exactly the same effect as that above. It illustrates the equivalence of the template\texttt{'} s Domain attribute and the fields in the \texttt{"} domainlist\texttt{"} string. } \sstexamplesubsection{ result = astFindFrame( target, astFrame( 1, \texttt{"} MaxAxes=3\texttt{"} ), \texttt{"} \texttt{"} ); }{ This is a more advanced example which will search for any coordinate system in the target having 1, 2 or 3 dimensions. The Frame returned (as part of the \texttt{"} result\texttt{"} FrameSet) will always be 1-dimensional, but will be related to the coordinate system that was found by a suitable Mapping (e.g. a PermMap) which simply extracts the first axis. If we had wanted a Frame representing the actual (1, 2 or 3-dimensional) coordinate system found, we could set the \htmlref{PreserveAxes}{PreserveAxes} attribute to a non-zero value in the template. } \sstexamplesubsection{ result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{Permute}{Permute}=0\texttt{"} ), \texttt{"} \texttt{"} ); }{ Searches for any celestial coordinate system in the target, but only finds one if its axes are in the conventional (longitude,latitude) order and have not been permuted (e.g. with \htmlref{astPermAxes}{astPermAxes}). } } \sstnotes{ \sstitemlist{ \sstitem The Mapping represented by the returned FrameSet results in alignment taking place in the coordinate system specified by the \htmlref{AlignSystem}{AlignSystem} attribute of the \texttt{"} template\texttt{"} Frame. See the description of the AlignSystem attribute for further details. \sstitem Beware of setting the Domain attribute of the template and then using a \texttt{"} domainlist\texttt{"} string which does not include the template\texttt{'} s domain (or a blank field). If you do so, no coordinate system will be found. \sstitem 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. } } \sstdiytopic{ More on Using Templates }{ A Frame (describing a coordinate system) will be found by this function if (a) it is \texttt{"} matched\texttt{"} by the template you supply, and (b) the value of its Domain attribute appears in the \texttt{"} domainlist\texttt{"} string (except that a blank field in this string permits any domain). A successful match by the template depends on a number of criteria, as outlined below: \sstitemlist{ \sstitem In general, a template will only match another Frame which belongs to the same class as the template, or to a derived (more specialised) class. For example, a SkyFrame template will match any other SkyFrame, but will not match a basic Frame. Conversely, a basic Frame template will match any class of Frame. \sstitem The exception to this is that a Frame of any class can be used to match a CmpFrame, if that CmpFrame contains a Frame of the same class as the template. Note however, the MaxAxes and \htmlref{MinAxes}{MinAxes} attributes of the template must be set to suitable values to allow it to match the CmpFrame. That is, the MinAxes attribute must be less than or equal to the number of axes in the target, and the MaxAxes attribute must be greater than or equal to the number of axes in the target. \sstitem If using a CmpFrame as a template frame, the MinAxes and MaxAxes for the template are determined by the MinAxes and MaxAxes values of the component Frames within the template. So if you want a template CmpFrame to be able to match Frames with different numbers of axes, then you must set the MaxAxes and/or MinAxes attributes in the component template Frames, before combining them together into the template CmpFrame. \sstitem If a template has a value set for any of its main attributes, then it will only match Frames which have an identical value for that attribute (or which can be transformed, using a built-in conversion, so that they have the required value for that attribute). If any attribute in the template is un-set, however, then Frames are matched regardless of the value they may have for that attribute. You may therefore make a template more or less specific by choosing the attributes for which you set values. This requirement does not apply to \texttt{'} descriptive\texttt{'} attributes such as titles, labels, symbols, etc. \sstitem An important application of this principle involves the Domain attribute. Setting the Domain attribute of the template has the effect of restricting the search to a particular type of Frame (with the domain you specify). Conversely, if the Domain attribute is not set in the template, then the domain of the Frame found is not relevant, so all Frames are searched. Note that the \texttt{"} domainlist\texttt{"} string provides an alternative way of restricting the search in the same manner, but is a more convenient interface if you wish to search automatically for another domain if the first search fails. \sstitem Normally, a template will only match a Frame which has the same number of axes as itself. However, for some classes of template, this default behaviour may be changed by means of the MinAxes, MaxAxes and \htmlref{MatchEnd}{MatchEnd} attributes. In addition, the behaviour of a template may be influenced by its Permute and PreserveAxes attributes, which control whether it matches Frames whose axes have been permuted, and whether this permutation is retained in the Frame which is returned (as opposed to returning the axes in the order specified in the template, which is the default behaviour). You should consult the descriptions of these attributes for details of this more advanced use of templates. } } } \sstroutine{ astFitsChan }{ Create a FitsChan }{ \sstdescription{ This function creates a new \htmlref{FitsChan}{FitsChan} and optionally initialises its attributes. A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O operations involving the use of FITS (Flexible Image Transport \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description. While a FitsChan is active, it represents a buffer which may contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} card, to which subsequent operations apply. Searches based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and existing ones may be deleted (\htmlref{astDelFits}{astDelFits}) or changed (astSetFits$<$X$>$). When you create a FitsChan, you have the option of specifying \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using astPutFits, astPutCards, astWrite or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from which headers should be read). When the FitsChan is deleted, any remaining header cards in the FitsChan can be saved in either of two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the name of a text file to which header cards should be written), or 2) by providing a sink function (used to to deliver header cards to an external data store). If you do not provide a sink function or a value for SinkFile, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using astFindFits or \htmlref{astRead}{astRead}). Coordinate system information may be described using FITS header cards using several different conventions, termed \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers). The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings. The detailed behaviour of astRead and astWrite, when used with a FitsChan, depends on the encoding in use. In general, however, all use of astRead is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the \htmlref{astRetainFits}{astRetainFits} function). If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using astWrite will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence. } \sstsynopsis{ AstFitsChan $*$astFitsChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) } \sstparameters{ \sstsubsection{ source }{ Pointer to a source function which takes no arguments and returns a pointer to a null-terminated string. This function will be used by the FitsChan to obtain input FITS header cards. On each invocation, it should read the next input card from some external source (such as a FITS file), and return a pointer to the (null-terminated) contents of the card. It should return a NULL pointer when there are no more cards to be read. If \texttt{"} source\texttt{"} is NULL, the FitsChan will remain empty until cards are explicitly stored in it (e.g. using astPutCards, astPutFits or via the SourceFile attribute). } \sstsubsection{ sink }{ Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the FitsChan to deliver any FITS header cards it contains when it is finally deleted. On each invocation, it should deliver the contents of the character string passed to it as a FITS header card to some external data store (such as a FITS file). If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile attribute, the contents of the FitsChan will be lost when it is deleted. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsChan. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). Note, the FITSCHAN\_OPTIONS environment variable may be used to specify default options for all newly created FitsChans. } } \sstreturnedvalue{ \sstsubsection{ astFitsChan() }{ A pointer to the new FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem No FITS \texttt{"} END\texttt{"} card will be written via the sink function. You should add this card yourself after the FitsChan has been deleted. \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astFitsTable }{ Create a FitsTable }{ \sstdescription{ This function creates a new \htmlref{FitsTable}{FitsTable} and optionally initialises its attributes. The FitsTable class is a representation of a FITS binary table. It inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the binary data of the main table, and a \htmlref{FitsChan}{FitsChan} is used to hold the FITS header. Note, there is no provision for binary data following the main table (such data is referred to as a \texttt{"} heap\texttt{"} in the FITS standard). Note - it is not recommended to use the FitsTable class to store very large tables. } \sstsynopsis{ AstFitsTable $*$astFitsTable( AstFitsChan $*$header, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ header }{ Pointer to an optional FitsChan containing headers to be stored in the FitsTable. NULL may be supplied if the new FitsTable is to be left empty. If supplied, and if the headers describe columns of a FITS binary table, then equivalent (empty) columns are added to the FitsTable. Each column has the same index in the FitsTable that it has in the supplied header. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsTable. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astFitsTable() }{ A pointer to the new FitsTable. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astFluxFrame }{ Create a FluxFrame }{ \sstdescription{ This function creates a new \htmlref{FluxFrame}{FluxFrame} and optionally initialises its attributes. A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various systems used to represent the signal level in an observation. The particular coordinate system to be used is specified by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by other attributes such as the units, etc (see the description of the System attribute for details). All flux values are assumed to be measured at the same frequency or wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is more appropriate for use with images rather than spectra. } \sstsynopsis{ AstFluxFrame $*$astFluxFrame( double specval, AstSpecFrame $*$specfrm, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ specval }{ The spectral value to which the flux values refer, given in the spectral coordinate system specified by \texttt{"} specfrm\texttt{"} . The value supplied for the \texttt{"} specval\texttt{"} parameter becomes the default value for the SpecVal attribute. A value of AST\_\_BAD may be supplied if the spectral position is unknown, but this may result in it not being possible for the \htmlref{astConvert}{astConvert} function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and some other FluxFrame. } \sstsubsection{ specfrm }{ A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system in which the \texttt{"} specval\texttt{"} parameter is given. A deep copy of this object is taken, so any subsequent changes to the SpecFrame using the supplied pointer will have no effect on the new FluxFrame. A NULL pointer can be supplied if AST\_\_BAD is supplied for \texttt{"} specval\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new FluxFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astFluxFrame() }{ A pointer to the new FluxFrame. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two FluxFrames is requested (as when supplying FluxFrames to astConvert), account will be taken of the nature of the flux coordinate systems they represent, together with any qualifying attribute values, including the \htmlref{AlignSystem}{AlignSystem} attribute. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astFormat }{ Format a coordinate value for a Frame axis }{ \sstdescription{ This function returns a pointer to a string containing the formatted (character) version of a coordinate value for a \htmlref{Frame}{Frame} axis. The formatting applied is determined by the Frame\texttt{'} s attributes and, in particular, by any Format attribute string that has been set for the axis. A suitable default format (based on the Digits attribute value) will be applied if necessary. } \sstsynopsis{ const char $*$astFormat( AstFrame $*$this, int axis, double value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ axis }{ The number of the Frame axis for which formatting is to be performed (axis numbering starts at 1 for the first axis). } \sstsubsection{ value }{ The coordinate value to be formatted. } } \sstreturnedvalue{ \sstsubsection{ astFormat() }{ A pointer to a null-terminated string containing the formatted value. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. \sstitem A formatted value may be converted back into a numerical (double) value using \htmlref{astUnformat}{astUnformat}. \sstitem A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astFrame }{ Create a Frame }{ \sstdescription{ This function creates a new \htmlref{Frame}{Frame} and optionally initialises its attributes. A Frame is used to represent a coordinate system. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a \htmlref{Title}{Title} (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two. Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame. Frames may also contain knowledge of how to transform to and from related coordinate systems. } \sstsynopsis{ AstFrame $*$astFrame( int naxes, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ naxes }{ The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes). } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Frame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astFrame() }{ A pointer to the new Frame. } } \sstexamples{ \sstexamplesubsection{ frame = astFrame( 2, \texttt{"} Title=Energy Spectrum: \htmlref{Plot}{Plot} \%d\texttt{"} , n ); }{ Creates a new 2-dimensional Frame and initialises its Title attribute to the string \texttt{"} Energy Spectrum: Plot $<$n$>$\texttt{"} , where $<$n$>$ takes the value of the int variable \texttt{"} n\texttt{"} . } \sstexamplesubsection{ frame = astFrame( 2, \texttt{"} Label(1)=Energy, Label(2)=Response\texttt{"} ); }{ Creates a new 2-dimensional Frame and initialises its axis Label attributes to suitable string values. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astFrameSet }{ Create a FrameSet }{ \sstdescription{ This function creates a new \htmlref{FrameSet}{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 \htmlref{Mapping}{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 \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} 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\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{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 \texttt{"} native\texttt{"} coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the \texttt{"} apparent\texttt{"} 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 \htmlref{Title}{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 \texttt{"} native\texttt{"} coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), 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 \htmlref{Region}{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. } \sstsynopsis{ AstFrameSet $*$astFrameSet( AstFrame $*$frame, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ 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 \htmlref{astAddFrame}{astAddFrame} function.) } \sstsubsection{ 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 identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astFrameSet() }{ A pointer to the new FrameSet. } } \sstnotes{ \sstitemlist{ \sstitem If a pointer to an existing FrameSet is given for the \texttt{"} frame\texttt{"} parameter, 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 similar to making a copy of a FrameSet (see \htmlref{astCopy}{astCopy}), except that the Frames and Mappings contained in the original are not themselves copied, but are shared by both FrameSets. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astFromString }{ Re-create an Object from an in-memory serialisation }{ \sstdescription{ This function returns a pointer to a new \htmlref{Object}{Object} created from the supplied text string, which should have been created by \htmlref{astToString}{astToString}. } \sstsynopsis{ AstObject $*$astFromString( const char $*$string ) } \sstparameters{ \sstsubsection{ string }{ Pointer to a text string holding an Object serialisation created previously by astToString. } } \sstreturnedvalue{ \sstsubsection{ astFromString() }{ Pointer to a new Object created from the supplied serialisation, or NULL if the serialisation was invalid, or an error occurred. } } } \sstroutine{ astGenCurve }{ Draw a generalized curve }{ \sstdescription{ This function draws a general user-defined curve defined by the supplied \htmlref{Mapping}{Mapping}. Note that the curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the Mapping involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{astClip}{astClip}. If you need to draw simple straight lines (geodesics), \htmlref{astCurve}{astCurve} or \htmlref{astPolyCurve}{astPolyCurve} will usually be easier to use and faster. } \sstsynopsis{ void astGenCurve( AstPlot $*$this, astMapping $*$map ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ map }{ Pointer to a Mapping. This Mapping should have 1 input coordinate representing offset along the required curve, normalized so that the start of the curve is at offset 0.0, and the end of the curve is at offset 1.0. Note, this offset does not need to be linearly related to distance along the curve. The number of output coordinates should equal the number of axes in the current \htmlref{Frame}{Frame} of the Plot. The Mapping should map a specified offset along the curve, into the corresponding coordinates in the current Frame of the Plot. The inverse transformation need not be defined. } } \sstnotes{ \sstitemlist{ \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astGet$<$X$>$ }{ Get an attribute value for an Object }{ \sstdescription{ This is a family of functions which return a specified attribute value for an \htmlref{Object}{Object} using one of several different data types. The type is selected by replacing $<$X$>$ in the function name by C, D, F, I or L, to obtain a result in const char$*$ (i.e. string), double, float, int, or long format, respectively. If possible, the attribute value is converted to the type you request. If conversion is not possible, an error will result. } \sstsynopsis{ $<$X$>$type astGet$<$X$>$( AstObject $*$this, const char $*$attrib ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ attrib }{ Pointer to a null-terminated string containing the name of the attribute whose value is required. } } \sstapplicability{ \sstsubsection{ Object }{ These functions apply to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astGet$<$X$>$() }{ The attribute value, in the data type corresponding to $<$X$>$ (or, in the case of astGetC, a pointer to a constant null-terminated character string containing this value). } } \sstexamples{ \sstexamplesubsection{ printf( \texttt{"} \htmlref{RefCount}{RefCount} = \%d$\backslash$n\texttt{"} , astGetI( z, \texttt{"} RefCount\texttt{"} ) ); }{ Prints the RefCount attribute value for Object \texttt{"} z\texttt{"} as an int. } \sstexamplesubsection{ title = astGetC( axis, \texttt{"} \htmlref{Title}{Title}\texttt{"} ); }{ Obtains a pointer to a null-terminated character string containing the Title attribute of Object \texttt{"} axis\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem An appropriate \texttt{"} null\texttt{"} value will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. This null value is zero for numeric values and NULL for pointer values. \sstitem The pointer returned by astGetC is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. } } } \sstroutine{ astGetActiveUnit }{ Determines how the Unit attribute will be used }{ \sstdescription{ This function returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See the description of the \htmlref{astSetActiveUnit}{astSetActiveUnit} function for a description of the ActiveUnit flag. } \sstsynopsis{ int astGetActiveUnit( AstFrame $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } } \sstreturnedvalue{ \sstsubsection{ astGetActiveUnit }{ The current value of the ActiveUnit flag. } } \sstnotes{ \sstitemlist{ \sstitem A zero value will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astGetColumnData }{ Retrieve all the data values stored in a column }{ \sstdescription{ This function copies all data values from a named column into a supplied buffer } \sstsynopsis{ void astGetColumnData( AstFitsTable $*$this, const char $*$column, float fnull, double dnull, size\_t mxsize, void $*$coldata, int $*$nelem ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{FitsTable}{FitsTable}. } \sstsubsection{ column }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ fnull }{ The value to return in \texttt{"} coldata\texttt{"} for any cells for which no value has been stored in the FitsTable. Ignored if the column\texttt{'} s data type is not AST\_\_FLOATTYPE. Supplying AST\_\_NANF will cause a single precision IEEE NaN value to be used. } \sstsubsection{ dnull }{ The value to return in \texttt{"} coldata\texttt{"} for any cells for which no value has been stored in the FitsTable. Ignored if the column\texttt{'} s data type is not AST\_\_DOUBLETYPE. Supplying AST\_\_NAN will cause a double precision IEEE NaN value to be used. } \sstsubsection{ mxsize }{ The size of the \texttt{"} coldata\texttt{"} array, in bytes. The amount of memory needed to hold the data from a column may be determined using \htmlref{astColumnSize}{astColumnSize}. If the supplied array is too small to hold all the column data, trailing column values will be omitted from the returned array, but no error will be reported. } \sstsubsection{ coldata }{ A pointer to an area of memory in which to return the data values currently stored in the column. The values are stored in row order. If the column holds non-scalar values, the elements of each value are stored in \texttt{"} Fortran\texttt{"} order. No data type conversion is performed - the data type of each returned value is the data type associated with the column when the column was added to the table. If the column holds strings, the returned strings will be null terminated. Any excess room at the end of the array will be left unchanged. } \sstsubsection{ nelem }{ The number of elements returned in the \texttt{"} coldata\texttt{"} array. This is the product of the number of rows returned and the number of elements in each column value. } } \sstnotes{ \sstitemlist{ \sstitem The \texttt{"} fnull\texttt{"} and \texttt{"} dnull\texttt{"} parameters specify the value to be returned for any empty cells within columns holding floating point values. For columns holding integer values, the value returned for empty cells is the value returned by the astColumNull function. For columns holding string values, the ASCII NULL character is returned for empty cells. } } } \sstroutine{ astGetFits$<$X$>$ }{ Get a named keyword value from a FitsChan }{ \sstdescription{ This is a family of functions which gets a value for a named keyword, or the value of the current card, from a \htmlref{FitsChan}{FitsChan} using one of several different data types. The data type of the returned value is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS data types: \sstitemlist{ \sstitem CF - Complex floating point values. \sstitem CI - Complex integer values. \sstitem F - Floating point values. \sstitem I - Integer values. \sstitem L - Logical (i.e. boolean) values. \sstitem S - String values. \sstitem CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but are encoded without an equals sign. } The data type of the \texttt{"} value\texttt{"} parameter depends on $<$X$>$ as follows: \sstitemlist{ \sstitem CF - \texttt{"} double $*$\texttt{"} (a pointer to a 2 element array to hold the real and imaginary parts of the complex value). \sstitem CI - \texttt{"} int $*$\texttt{"} (a pointer to a 2 element array to hold the real and imaginary parts of the complex value). \sstitem F - \texttt{"} double $*$\texttt{"} . \sstitem I - \texttt{"} int $*$\texttt{"} . \sstitem L - \texttt{"} int $*$\texttt{"} . \sstitem S - \texttt{"} char $*$$*$\texttt{"} (a pointer to a static \texttt{"} char\texttt{"} array is returned at the location given by the \texttt{"} value\texttt{"} parameter, Note, the stored string may change on subsequent invocations of astGetFitsS so a permanent copy should be taken of the string if necessary). \sstitem CN - Like\texttt{"} S\texttt{"} . } } \sstsynopsis{ int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ name }{ Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. If NULL is supplied, the value of the current card is returned. } \sstsubsection{ value }{ A pointer to a buffer to receive the keyword value. The data type depends on $<$X$>$ as described above. The conents of the buffer on entry are left unchanged if the keyword is not found. } } \sstreturnedvalue{ \sstsubsection{ astGetFits$<$X$>$$<$X$>$() }{ A value of zero is returned if the keyword was not found in the FitsChan (no error is reported). Otherwise, a value of one is returned. } } \sstnotes{ \sstitemlist{ \sstitem If a name is supplied, the card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards. \sstitem If the requested card is found, it becomes the current card, otherwise the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem If the stored keyword value is not of the requested type, it is converted into the requested type. \sstitem If the keyword is found in the FitsChan, but has no associated value, an error is reported. If necessary, the \htmlref{astTestFits}{astTestFits} function can be used to determine if the keyword has a defined value in the FitsChan prior to calling this function. \sstitem An error will be reported if the keyword name does not conform to FITS requirements. \sstitem Zero \sstitem .FALSE. is returned as the function value if an error has already occurred, or if this function should fail for any reason. \sstitem The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the string returned by astGetFitsS if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings. } } } \sstroutine{ astGetFrame }{ Obtain a pointer to a specified Frame in a FrameSet }{ \sstdescription{ This function returns a pointer to a specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet}. } \sstsynopsis{ AstFrame $*$astGetFrame( AstFrameSet $*$this, int iframe ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe }{ 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 \htmlref{Nframe}{Nframe} attribute). } } \sstreturnedvalue{ \sstsubsection{ astGetFrame() }{ A pointer to the requested Frame. } } \sstnotes{ \sstitemlist{ \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current Frame respectively. \sstitem This function increments the \htmlref{RefCount}{RefCount} attribute of the selected Frame by one. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetGrfContext }{ Return the KeyMap that describes a Plot\texttt{'} s graphics context }{ \sstdescription{ This function returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing functions registered using \htmlref{astGrfSet}{astGrfSet}. This KeyMap can be used by an application to pass information to the drawing functions about the context in which they are being called. The contents of the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself. } \sstsynopsis{ AstKeyMap $*$astGetGrfContext( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } } \sstreturnedvalue{ \sstsubsection{ astGetGrfContext() }{ A pointer to the graphics context KeyMap. The returned pointer should be annulled when it is no longer needed. } } } \sstroutine{ astGetMapping }{ Obtain a Mapping that converts between two Frames in a FrameSet }{ \sstdescription{ This function returns a pointer to a \htmlref{Mapping}{Mapping} that will convert coordinates between the coordinate systems represented by two Frames in a \htmlref{FrameSet}{FrameSet}. } \sstsynopsis{ AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe1 }{ The index of the first \htmlref{Frame}{Frame} in the FrameSet. This Frame describes the coordinate system for the \texttt{"} input\texttt{"} end of the Mapping. } \sstsubsection{ iframe2 }{ The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the \texttt{"} output\texttt{"} end of the Mapping. } } \sstreturnedvalue{ \sstsubsection{ astGetMapping() }{ 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. } } \sstnotes{ \sstitemlist{ \sstitem 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). \sstitem The values given for the \texttt{"} iframe1\texttt{"} and \texttt{"} iframe2\texttt{"} parameters should lie in the range from 1 to the number of Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). A value of AST\_\_BASE or AST\_\_CURRENT may also be given to identify the FrameSet\texttt{'} s base Frame or current Frame respectively. It is permissible for both these parameters to have the same value, in which case a unit Mapping (\htmlref{UnitMap}{UnitMap}) is returned. \sstitem 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 \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes of the returned Mapping should be inspected to determine if the required transformation is available. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetRefPos }{ Return the reference position in a specified celestial coordinate system }{ \sstdescription{ This function returns the reference position (specified by attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) converted to the celestial coordinate system represented by a supplied \htmlref{SkyFrame}{SkyFrame}. The celestial longitude and latitude values are returned in radians. } \sstsynopsis{ void astGetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double $*$lon, double $*$lat ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{SpecFrame}{SpecFrame}. } \sstsubsection{ frm }{ Pointer to the SkyFrame which defines the required celestial coordinate system. If NULL is supplied, then the longitude and latitude values are returned as FK5 J2000 RA and Dec values. } \sstsubsection{ lon }{ A pointer to a double in which to store the longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ lat }{ A pointer to a double in which to store the latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } } \sstnotes{ \sstitemlist{ \sstitem Values of AST\_\_BAD will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astGetRegionBounds }{ Returns the bounding box of Region }{ \sstdescription{ This function returns the upper and lower limits of a box which just encompasses the supplied \htmlref{Region}{Region}. The limits are returned as axis values within the \htmlref{Frame}{Frame} represented by the Region. The value of the \htmlref{Negated}{Negated} attribute is ignored (i.e. it is assumed that the Region has not been negated). } \sstsynopsis{ void astGetRegionBounds( AstRegion $*$this, double $*$lbnd, double $*$ubnd ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ lbnd }{ Pointer to an array in which to return the lower axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no lower limit, the returned value will be the largest possible negative value. } \sstsubsection{ ubnd }{ Pointer to an array in which to return the upper axis bounds covered by the Region. It should have at least as many elements as there are axes in the Region. If an axis has no upper limit, the returned value will be the largest possible positive value. } } \sstnotes{ \sstitemlist{ \sstitem The value of the Negated attribute is ignored (i.e. it is assumed that the Region has not been negated). \sstitem If an axis has no extent on an axis then the lower limit will be returned larger than the upper limit. Note, this is different to an axis which has a constant value (in which case both lower and upper limit will be returned set to the constant value). \sstitem If the bounds on an axis cannot be determined, AST\_\_BAD is returned for both upper and lower bounds } } } \sstroutine{ astGetRegionFrame }{ Obtain a pointer to the encapsulated Frame within a Region }{ \sstdescription{ This function returns a pointer to the \htmlref{Frame}{Frame} represented by a \htmlref{Region}{Region}. } \sstsynopsis{ AstFrame $*$astGetRegionFrame( AstRegion $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } } \sstreturnedvalue{ \sstsubsection{ astGetRegionFrame() }{ A pointer to a deep copy of the Frame represented by the Region. Using this pointer to modify the Frame will have no effect on the Region. To modify the Region, use the Region pointer directly. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetRegionFrameSet }{ Obtain a pointer to the encapsulated FrameSet within a Region }{ \sstdescription{ This function returns a pointer to the \htmlref{FrameSet}{FrameSet} encapsulated by a \htmlref{Region}{Region}. The base \htmlref{Frame}{Frame} is the Frame in which the box was originally defined, and the current Frame is the Frame into which the Region is currently mapped (i.e. it will be the same as the Frame returned by \htmlref{astGetRegionFrame}{astGetRegionFrame}). } \sstsynopsis{ AstFrame $*$astGetRegionFrameSet( AstRegion $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } } \sstreturnedvalue{ \sstsubsection{ astGetRegionFrameSet() }{ A pointer to a deep copy of the FrameSet represented by the Region. Using this pointer to modify the FrameSet will have no effect on the Region. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetRegionMesh }{ Return a mesh of points covering the surface or volume of a Region }{ \sstdescription{ This function returns the axis values at a mesh of points either covering the surface (i.e. boundary) of the supplied \htmlref{Region}{Region}, or filling the interior (i.e. volume) of the Region. The number of points in the mesh is approximately equal to the \htmlref{MeshSize}{MeshSize} attribute. } \sstsynopsis{ void astGetRegionMesh( AstRegion $*$this, int surface, int maxpoint, int maxcoord, int $*$npoint, double $*$points ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ surface }{ If non-zero, the returned points will cover the surface or the Region. Otherwise, they will fill the interior of the Region. } \sstsubsection{ maxpoint }{ If zero, the number of points in the mesh is returned in \texttt{"} $*$npoint\texttt{"} , but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the second dimension of the \texttt{"} points\texttt{"} array. An error is reported if the number of points in the mesh exceeds this number. } \sstsubsection{ maxcoord }{ The length of the first dimension of the \texttt{"} points\texttt{"} array. An error is reported if the number of axes in the supplied Region exceeds this number. } \sstsubsection{ npoint }{ A pointer to an integer in which to return the number of points in the returned mesh. } \sstsubsection{ points }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return the coordinate values at the mesh positions. These are stored such that the value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} point\texttt{"} is found in element \texttt{"} points[coord][point]\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem An error is reported if the Region is unbounded. \sstitem If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (\htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc). } } } \sstroutine{ astGetRegionPoints }{ Returns the positions that define the given Region }{ \sstdescription{ This function returns the axis values at the points that define the supplied \htmlref{Region}{Region}. The particular meaning of these points will depend on the type of class supplied, as listed below under \texttt{"} Applicability:\texttt{"} . } \sstsynopsis{ void astGetRegionPoints( AstRegion $*$this, int maxpoint, int maxcoord, int $*$npoint, double $*$points ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ maxpoint }{ If zero, the number of points needed to define the Region is returned in \texttt{"} $*$npoint\texttt{"} , but no axis values are returned and all other parameters are ignored. If not zero, the supplied value should be the length of the second dimension of the \texttt{"} points\texttt{"} array. An error is reported if the number of points needed to define the Region exceeds this number. } \sstsubsection{ maxcoord }{ The length of the first dimension of the \texttt{"} points\texttt{"} array. An error is reported if the number of axes in the supplied Region exceeds this number. } \sstsubsection{ npoint }{ A pointer to an integer in which to return the number of points defining the Region. } \sstsubsection{ points }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return the coordinate values at the positions that define the Region. These are stored such that the value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} point\texttt{"} is found in element \texttt{"} points[coord][point]\texttt{"} . } } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{Box}{Box} }{ The first returned position is the Box centre, and the second is a Box corner. } \sstsubsection{ \htmlref{Circle}{Circle} }{ The first returned position is the Circle centre, and the second is a point on the circumference. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ Returns a value of zero for \texttt{"} $*$npoint\texttt{"} and leaves the supplied array contents unchanged. To find the points defining a CmpRegion, use this method on the component Regions, which can be accessed by invoking \htmlref{astDecompose}{astDecompose} on the CmpRegion. } \sstsubsection{ \htmlref{Ellipse}{Ellipse} }{ The first returned position is the Ellipse centre. The second is the end of one of the axes of the ellipse. The third is some other point on the circumference of the ellipse, distinct from the second point. } \sstsubsection{ \htmlref{Interval}{Interval} }{ The first point corresponds to the lower bounds position, and the second point corresponds to the upper bounds position. These are reversed to indicate an extcluded interval rather than an included interval. See the Interval constructor for more information. } \sstsubsection{ \htmlref{NullRegion}{NullRegion} }{ Returns a value of zero for \texttt{"} $*$npoint\texttt{"} and leaves the supplied array contents unchanged. } \sstsubsection{ \htmlref{PointList}{PointList} }{ The positions returned are those that were supplied when the PointList was constructed. } \sstsubsection{ \htmlref{Polygon}{Polygon} }{ The positions returned are the vertex positions that were supplied when the Polygon was constructed. } \sstsubsection{ \htmlref{Prism}{Prism} }{ Returns a value of zero for \texttt{"} $*$npoint\texttt{"} and leaves the supplied array contents unchanged. To find the points defining a Prism, use this method on the component Regions, which can be accessed by invoking astDecompose on the CmpRegion. } } \sstnotes{ \sstitemlist{ \sstitem If the coordinate system represented by the Region has been changed since it was first created, the returned axis values refer to the new (changed) coordinate system, rather than the original coordinate system. Note however that if the transformation from original to new coordinate system is non-linear, the shape within the new coordinate system may be distorted, and so may not match that implied by the name of the Region subclass (Circle, Box, etc). } } } \sstroutine{ astGetStcCoord }{ Return information about an AstroCoords element stored in an Stc }{ \sstdescription{ When any sub-class of \htmlref{Stc}{Stc} is created, the constructor function allows one or more AstroCoords elements to be stored within the Stc. This function allows any one of these AstroCoords elements to be retrieved. The format of the returned information is the same as that used to pass the original information to the Stc constructor. That is, the information is returned in a \htmlref{KeyMap}{KeyMap} structure containing elements with one or more of the keys given by symbolic constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE and AST\_\_STCPIXSZ. If the coordinate system represented by the Stc has been changed since it was created (for instance, by changing its \htmlref{System}{System} attribute), then the sizes and positions in the returned KeyMap will reflect the change in coordinate system. } \sstsynopsis{ AstKeyMap $*$astGetStcCoord( AstStc $*$this, int icoord ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Stc. } \sstsubsection{ icoord }{ The index of the AstroCoords element required. The first has index one. The number of AstroCoords elements in the Stc can be found using function astGetStcNcoord. } } \sstreturnedvalue{ \sstsubsection{ astGetStcCoord() }{ A pointer to a new KeyMap containing the required information. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetStcNCoord }{ Return the number of AstroCoords elements stored in an Stc }{ \sstdescription{ This function returns the number of AstroCoords elements stored in an \htmlref{Stc}{Stc}. } \sstsynopsis{ int astGetStcNCoord( AstStc $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Stc. } } \sstreturnedvalue{ \sstsubsection{ astGetStcNCoord() }{ The number of AstroCoords elements stored in the Stc. } } \sstnotes{ \sstitemlist{ \sstitem Zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astGetStcRegion }{ Obtain a copy of the encapsulated Region within a Stc }{ \sstdescription{ This function returns a pointer to a deep copy of the \htmlref{Region}{Region} supplied when the \htmlref{Stc}{Stc} was created. } \sstsynopsis{ AstRegion $*$astGetStcRegion( AstStc $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Stc. } } \sstreturnedvalue{ \sstsubsection{ astGetStcRegion() }{ A pointer to a deep copy of the Region encapsulated within the supplied Stc. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetTableHeader }{ Get the FITS headers from a FitsTable }{ \sstdescription{ This function returns a pointer to a \htmlref{FitsChan}{FitsChan} holding copies of the FITS headers associated with a \htmlref{FitsTable}{FitsTable}. } \sstsynopsis{ AstFitsChan $*$astGetTableHeader( AstFitsTable $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsTable. } } \sstreturnedvalue{ \sstsubsection{ astGetTableHeader() }{ A pointer to a deep copy of the FitsChan stored within the FitsTable. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer should be annulled using \htmlref{astAnnul}{astAnnul} when it is no longer needed. \sstitem Changing the contents of the returned FitsChan will have no effect on the FitsTable. To modify the FitsTable, the modified FitsChan must be stored in the FitsTable using \htmlref{astPutTableHeader}{astPutTableHeader}. } } } \sstroutine{ astGetTables }{ Retrieve any FitsTables currently in a FitsChan }{ \sstdescription{ If the supplied \htmlref{FitsChan}{FitsChan} currently contains any tables, then this function returns a pointer to a \htmlref{KeyMap}{KeyMap}. Each entry in the KeyMap is a pointer to a \htmlref{FitsTable}{FitsTable} holding the data for a FITS binary table. The key used to access each entry is the FITS extension name in which the table should be stored. Tables can be present in a FitsChan as a result either of using the \htmlref{astPutTable}{astPutTable} (or \htmlref{astPutTables}{astPutTables}) method to store existing tables in the FitsChan, or of using the \htmlref{astWrite}{astWrite} method to write a \htmlref{FrameSet}{FrameSet} to the FitsChan. For the later case, if the FitsChan \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute is positive and the FrameSet requires a look-up table to describe one or more axes, then the \texttt{"} -TAB\texttt{"} algorithm code described in FITS-WCS paper III is used and the table values are stored in the FitsChan in the form of a FitsTable object (see the documentation for the \texttt{"} TabOK\texttt{"} attribute). } \sstsynopsis{ AstKeyMap $*$astGetTables( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstreturnedvalue{ \sstsubsection{ astGetTables() }{ A pointer to a deep copy of the KeyMap holding the tables currently in the FitsChan, or NULL if the FitsChan does not contain any tables. The returned pointer should be annulled using \htmlref{astAnnul}{astAnnul} when no longer needed. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astGetUnc }{ Obtain uncertainty information from a Region }{ \sstdescription{ This function returns a \htmlref{Region}{Region} which represents the uncertainty associated with positions within the supplied Region. See \htmlref{astSetUnc}{astSetUnc} for more information about Region uncertainties and their use. } \sstsynopsis{ AstRegion $*$astGetUnc( AstRegion $*$this, int def ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ def }{ Controls what is returned if no uncertainty information has been associated explicitly with the supplied Region. If a non-zero value is supplied, then the default uncertainty Region used internally within AST is returned (see \texttt{"} Applicability\texttt{"} below). If zero is supplied, then NULL will be returned (without error). } } \sstapplicability{ \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default uncertainty for a CmpRegion is taken from one of the two component Regions. If the first component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. Otherwise, if the second component Region has a non-default uncertainty, then it is used as the default uncertainty for the parent CmpRegion. If neither of the component Regions has non-default uncertainty, then the default uncertainty for the CmpRegion is 1.0E-6 of the bounding box of the CmpRegion. } \sstsubsection{ \htmlref{Prism}{Prism} }{ The default uncertainty for a Prism is formed by combining the uncertainties from the two component Regions. If a component Region does not have a non-default uncertainty, then its default uncertainty will be used to form the default uncertainty of the parent Prism. } \sstsubsection{ Region }{ For other classes of Region, the default uncertainty is 1.0E-6 of the bounding box of the Region. If the bounding box has zero width on any axis, then the uncertainty will be 1.0E-6 of the axis value. } } \sstreturnedvalue{ \sstsubsection{ astGetUnc() }{ A pointer to a Region describing the uncertainty in the supplied Region. } } \sstnotes{ \sstitemlist{ \sstitem If uncertainty information is associated with a Region, and the coordinate system described by the Region is subsequently changed (e.g. by changing the value of its \htmlref{System}{System} attribute, or using the \htmlref{astMapRegion}{astMapRegion} function), then the uncertainty information returned by this function will be modified so that it refers to the coordinate system currently described by the supplied Region. \sstitem A null \htmlref{Object}{Object} pointer (NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astGrfPop }{ Restore previously saved graphics functions used by a Plot }{ \sstdescription{ This function restores a snapshot of the graphics functions stored previously by calling \htmlref{astGrfPush}{astGrfPush}. The restored graphics functions become the current graphics functions used by the \htmlref{Plot}{Plot}. The astGrfPush and astGrfPop functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the Plot. The current functions should first be saved by calling astGrfPush. New functions should then be registered using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced. Finally, astGrfPop should be called to restore the original graphics functions. } \sstsynopsis{ void astGrfPop( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if there are no snapshots to restore. No error is reported in this case. } } } \sstroutine{ astGrfPush }{ Save the current graphics functions used by a Plot }{ \sstdescription{ This function takes a snapshot of the graphics functions which are currently registered with the supplied \htmlref{Plot}{Plot}, and saves the snapshot on a first-in-last-out stack within the Plot. The snapshot can be restored later using function \htmlref{astGrfPop}{astGrfPop}. The astGrfPush and astGrfPop functions are intended for situations where it is necessary to make temporary changes to the graphics functions used by the Plot. The current functions should first be saved by calling astGrfPush. New functions should then be registered using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced. Finally, astGrfPop should be called to restore the original graphics functions. } \sstsynopsis{ void astGrfPush( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } } } \sstroutine{ astGrfSet }{ Register a graphics function for use by a Plot }{ \sstdescription{ This function can be used to select the underlying graphics functions to be used when the supplied \htmlref{Plot}{Plot} produces graphical output. If this function is not called prior to producing graphical output, then the underlying graphics functions selected at link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use alternative graphics functions, call this function before the graphical output is created, specifying the graphics functions to be used. This will register the function for future use, but the function will not actually be used until the \htmlref{Grf}{Grf} attribute is given a non-zero value. } \sstsynopsis{ void astGrfSet( AstPlot $*$this, const char $*$name, AstGrfFun fun ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ name }{ A name indicating the graphics function to be replaced. Various graphics functions are used by the Plot class, and any combination of them may be supplied by calling this function once for each function to be replaced. If any of the graphics functions are not replaced in this way, the corresponding functions in the graphics interface selected at link-time (using the ast\_link command) are used. The allowed names are: \sstitemlist{ \sstitem Attr - Enquire or set a graphics attribute value \sstitem BBuf - Start a new graphics buffering context \sstitem Cap - Inquire a capability \sstitem EBuf - End the current graphics buffering context \sstitem Flush - Flush all pending graphics to the output device \sstitem Line - Draw a polyline (i.e. a set of connected lines) \sstitem Mark - Draw a set of markers \sstitem Qch - Return the character height in world coordinates \sstitem Scales - Get the axis scales \sstitem Text - Draw a character string \sstitem TxExt - Get the extent of a character string } The string is case insensitive. For details of the interface required for each, see the sections below. } \sstsubsection{ fun }{ A Pointer to the function to be used to provide the functionality indicated by parameter name. The interface for each function is described below, but the function pointer should be cast to a type of AstGrfFun when calling astGrfSet. Once a function has been provided, a null pointer can be supplied in a subsequent call to astGrfSet to reset the function to the corresponding function in the graphics interface selected at link-time. } } \sstdiytopic{ Function Interfaces }{ All the functions listed below (except for \texttt{"} Cap\texttt{"} ) should return an integer value of 0 if an error occurs, and 1 otherwise. All x and y values refer to \texttt{"} graphics cordinates\texttt{"} as defined by the graphbox parameter of the \htmlref{astPlot}{astPlot} call which created the Plot. The first parameter (\texttt{"} grfcon\texttt{"} ) for each function is an AST \htmlref{KeyMap}{KeyMap} pointer that can be used by the called function to establish the context in which it is being called. The contents of the KeyMap are determined by the calling application, which should obtain a pointer to the KeyMap using the \htmlref{astGetGrfContext}{astGetGrfContext} function, and then store any necessary information in the KeyMap using the methods of the KeyMap class. Note, the functions listed below should never annul or delete the supplied KeyMap pointer. } \sstdiytopic{ Attr }{ The \texttt{"} Attr\texttt{"} function returns the current value of a specified graphics attribute, and optionally establishes a new value. The supplied value is converted to an integer value if necessary before use. It requires the following interface: int Attr( AstObject $*$grfcon, int attr, double value, double $*$old\_value, int prim ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem attr - An integer value identifying the required attribute. The following symbolic values are defined in grf.h: GRF\_\_STYLE (Line style), GRF\_\_WIDTH (Line width), GRF\_\_SIZE (Character and marker size scale factor), GRF\_\_FONT (Character font), GRF\_\_COLOUR (Colour index). \sstitem value - A new value to store for the attribute. If this is AST\_\_BAD no value is stored. \sstitem old\_value - A pointer to a double in which to return the attribute value. If this is NULL, no value is returned. \sstitem prim - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in grf.h: GRF\_\_LINE, GRF\_\_MARK, GRF\_\_TEXT. } } \sstdiytopic{ BBuf }{ The \texttt{"} BBuf\texttt{"} function should start a new graphics buffering context. A matching call to the function \texttt{"} EBuf\texttt{"} should be used to end the context. The nature of the buffering is determined by the underlying graphics system. int BBuf( AstObject $*$grfcon ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Cap }{ The \texttt{"} Cap\texttt{"} function is called to determine if the grf module has a given capability, as indicated by the \texttt{"} cap\texttt{"} argument: int Cap( AstObject $*$grfcon, int cap, int value ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem cap - The capability being inquired about. This will be one of the following constants defined in grf.h: } GRF\_\_SCALES: This function should return a non-zero value if the \texttt{"} Scales\texttt{"} function is implemented, and zero otherwise. The supplied \texttt{"} value\texttt{"} argument should be ignored. GRF\_\_MJUST: This function should return a non-zero value if the \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions recognise \texttt{"} M\texttt{"} as a character in the justification string. If the first character of a justification string is \texttt{"} M\texttt{"} , then the text should be justified with the given reference point at the bottom of the bounding box. This is different to \texttt{"} B\texttt{"} justification, which requests that the reference point be put on the baseline of the text, since some characters hang down below the baseline. If the \texttt{"} Text\texttt{"} or \texttt{"} TxExt\texttt{"} function cannot differentiate between \texttt{"} M\texttt{"} and \texttt{"} B\texttt{"} , then this function should return zero, in which case \texttt{"} M\texttt{"} justification will never be requested by Plot. The supplied \texttt{"} value\texttt{"} argument should be ignored. GRF\_\_ESC: This function should return a non-zero value if the \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions can recognise and interpret graphics escape sequences within the supplied string (see attribute \htmlref{Escape}{Escape}). Zero should be returned if escape sequences cannot be interpreted (in which case the Plot class will interpret them itself if needed). The supplied \texttt{"} value\texttt{"} argument should be ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} . Otherwise, \texttt{"} value\texttt{"} indicates whether \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} should interpret escape sequences in subsequent calls. If \texttt{"} value\texttt{"} is non-zero then escape sequences should be interpreted by \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} . Otherwise, they should be drawn as literal text. \sstitemlist{ \sstitem value - The use of this parameter depends on the value of \texttt{"} cap\texttt{"} as described above. \sstitem Returned Function Value: The value returned by the function depends on the value of \texttt{"} cap\texttt{"} as described above. Zero should be returned if the supplied capability is not recognised. } } \sstdiytopic{ EBuf }{ The \texttt{"} EBuf\texttt{"} function should end the current graphics buffering context. See the description of \texttt{"} BBuf\texttt{"} above for further details. It requires the following interface: int EBuf( AstObject $*$grfcon ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Flush }{ The \texttt{"} Flush\texttt{"} function ensures that the display device is up-to-date, by flushing any pending graphics to the output device. It requires the following interface: int Flush( AstObject $*$grfcon ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. } } \sstdiytopic{ Line }{ The \texttt{"} Line\texttt{"} function displays lines joining the given positions and requires the following interface: int Line( AstObject $*$grfcon, int n, const float $*$x, const float $*$y ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem n - The number of positions to be joined together. \sstitem x - A pointer to an array holding the \texttt{"} n\texttt{"} x values. \sstitem y - A pointer to an array holding the \texttt{"} n\texttt{"} y values. } } \sstdiytopic{ Mark }{ The \texttt{"} Mark\texttt{"} function displays markers at the given positions. It requires the following interface: int Mark( AstObject $*$grfcon, int n, const float $*$x, const float $*$y, int type ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem n - The number of positions to be marked. \sstitem x - A pointer to an array holding the \texttt{"} n\texttt{"} x values. \sstitem y - A pointer to an array holding the \texttt{"} n\texttt{"} y values. \sstitem type - An integer which can be used to indicate the type of marker symbol required. } } \sstdiytopic{ Qch }{ The \texttt{"} Qch\texttt{"} function returns the heights of characters drawn vertically and horizontally in graphics coordinates. It requires the following interface: int Qch( AstObject $*$grfcon, float $*$chv, float $*$chh ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem chv - A pointer to the float which is to receive the height of characters drawn with a vertical baseline. This will be an increment in the X axis. \sstitem chh - A pointer to the float which is to receive the height of characters drawn with a horizontal baseline. This will be an increment in the Y axis. } } \sstdiytopic{ Scales }{ The \texttt{"} Scales\texttt{"} function returns two values (one for each axis) which scale increments on the corresponding axis into a \texttt{"} normal\texttt{"} coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, and 3) Y values increase from bottom to top. It requires the following interface: int Scales( AstObject $*$grfcon, float $*$alpha, float $*$beta ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem alpha - A pointer to the float which is to receive the scale for the X axis (i.e. Xnorm = alpha$*$Xworld). \sstitem beta - A pointer to the float which is to receive the scale for the Y axis (i.e. Ynorm = beta$*$Yworld). } } \sstdiytopic{ Text }{ The \texttt{"} Text\texttt{"} function displays a character string at a given position using a specified justification and up-vector. It requires the following interface: int Text( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, float upx, float upy ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem text - Pointer to a null-terminated character string to be displayed. \sstitem x - The reference x coordinate. \sstitem y - The reference y coordinate. \sstitem just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be \texttt{'} T\texttt{'} for \texttt{"} top\texttt{"} , \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} B\texttt{'} for \texttt{"} bottom\texttt{"} , and specifies the vertical location of the reference position. Note, \texttt{"} bottom\texttt{"} corresponds to the base-line of normal text. Some characters (eg \texttt{"} y\texttt{"} , \texttt{"} g\texttt{"} , \texttt{"} p\texttt{"} , etc) descend below the base-line. The second character may be \texttt{'} L\texttt{'} for \texttt{"} left\texttt{"} , \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} R\texttt{'} for \texttt{"} right\texttt{"} , and specifies the horizontal location of the reference position. If the string has less than 2 characters then \texttt{'} C\texttt{'} is used for the missing characters. \sstitem upx - The x component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen. \sstitem upy - The y component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen. } } \sstdiytopic{ TxExt }{ The \texttt{"} TxExt\texttt{"} function returns the corners of a box which would enclose the supplied character string if it were displayed using the Text function described above. The returned box includes any leading or trailing spaces. It requires the following interface: int TxExt( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, float upx, float upy, float $*$xb, float $*$yb ) \sstitemlist{ \sstitem grfcon - A KeyMap containing information passed from the calling application. \sstitem text - Pointer to a null-terminated character string to be displayed. \sstitem x - The reference x coordinate. \sstitem y - The reference y coordinate. \sstitem just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. See \texttt{"} Text\texttt{"} above. \sstitem upx - The x component of the up-vector for the text. See \texttt{"} Text\texttt{"} above. \sstitem upy - The y component of the up-vector for the text. See \texttt{"} Text\texttt{"} above. \sstitem xb - An array of 4 elements in which to return the x coordinate of each corner of the bounding box. \sstitem yb - An array of 4 elements in which to return the y coordinate of each corner of the bounding box. } } } \sstroutine{ astGrid }{ Draw a set of labelled coordinate axes }{ \sstdescription{ This function draws a complete annotated set of coordinate axes for a \htmlref{Plot}{Plot} with (optionally) a coordinate grid superimposed. Details of the axes and grid can be controlled by setting values for the various attributes defined by the Plot class (q.v.). } \sstsynopsis{ void astGrid( AstPlot $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied Plot is a \htmlref{Plot3D}{Plot3D}, the axes will be annotated using three 2-dimensional Plots, one for each 2D plane in the 3D current coordinate system. The plots will be \texttt{"} pasted\texttt{"} onto 3 faces of the cuboid graphics volume specified when the Plot3D was constructed. The faces to be used can be controlled by the \texttt{"} \htmlref{RootCorner}{RootCorner}\texttt{"} attribute. \sstitem An error results if either the current \htmlref{Frame}{Frame} or the base Frame of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the base and current Frames of the Plot is not defined in either direction (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} or \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astGridLine }{ Draw a grid line (or axis) for a Plot }{ \sstdescription{ This function draws a curve in the physical coordinate system of a \htmlref{Plot}{Plot} by varying only one of the coordinates along the length of the curve. It is intended for drawing coordinate axes, coordinate grids, and tick marks on axes (but note that these are also available via the more comprehensive \htmlref{astGrid}{astGrid} function). The curve is transformed into graphical coordinate space for plotting, so that a straight line in physical coordinates may result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the Mapping between physical and graphical coordinates are catered for, as is any clipping established using \htmlref{astClip}{astClip}. } \sstsynopsis{ void astGridLine( AstPlot $*$this, int axis, const double start[], double length ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ axis }{ The index of the Plot axis whose physical coordinate value is to be varied along the length of the curve (all other coordinates will remain fixed). This value should lie in the range from 1 to the number of Plot axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ start }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the start of the curve. } \sstsubsection{ length }{ The length of curve to be drawn, given as an increment along the selected physical axis. This may be positive or negative. } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn if the \texttt{"} start\texttt{"} array contains any coordinates with the value AST\_\_BAD, nor if \texttt{"} length\texttt{"} has this value. \sstitem An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astGrismMap }{ Create a GrismMap }{ \sstdescription{ This function creates a new \htmlref{GrismMap}{GrismMap} and optionally initialises its attributes. A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III \texttt{"} Representation of spectral coordinates in FITS\texttt{"} . This describes the dispersion produced by gratings, prisms and grisms. When initially created, the forward transformation of a GrismMap transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as \texttt{"} the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length\texttt{"} . The units in which wavelength values are expected or returned is determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will also be used for the wavelength values. } \sstsynopsis{ AstGrismMap $*$astGrismMap( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new GrismMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astGrismMap() }{ A pointer to the new GrismMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astHasAttribute }{ Test if an Object has a named attribute }{ \sstdescription{ This function returns a boolean result (0 or 1) to indicate whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name. } \sstsynopsis{ int astHasAttribute( AstObject $*$this, const char $*$attrib ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the first Object. } \sstsubsection{ attrib }{ Pointer to a string holding the name of the attribute to be tested. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astHasAttribute() }{ One if the Object has the named attribute, otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astHasColumn }{ Returns a flag indicating if a column is present in a Table }{ \sstdescription{ This function returns a flag indicating if a named column exists in a \htmlref{Table}{Table}, for instance, by having been added to to the Table using \htmlref{astAddColumn}{astAddColumn}. } \sstsynopsis{ int astHasColumn( AstTable $*$this, const char $*$column ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ column }{ The character string holding the upper case name of the column. Trailing spaces are ignored. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned for if an error occurs. } } } \sstroutine{ astHasParameter }{ Returns a flag indicating if a named global parameter is present in a Table }{ \sstdescription{ This function returns a flag indicating if a named parameter exists in a \htmlref{Table}{Table}, for instance, by having been added to to the Table using \htmlref{astAddParameter}{astAddParameter}. } \sstsynopsis{ int astHasParameter( AstTable $*$this, const char $*$parameter ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ parameter }{ The character string holding the upper case name of the parameter. Trailing spaces are ignored. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned for if an error occurs. } } } \sstroutine{ astImport }{ Import an Object pointer to the current context }{ \sstdescription{ This function imports an \htmlref{Object}{Object} pointer that was created in a higher or lower level context, into the current AST context. This means that the pointer will be annulled when the current context is ended (with \htmlref{astEnd}{astEnd}). } \sstsynopsis{ void astImport( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Object pointer to be imported. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } } \sstroutine{ astIntersect }{ Find the point of intersection between two geodesic curves }{ \sstdescription{ 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. It can only be used with 2-dimensional Frames. For example, in a basic \htmlref{Frame}{Frame}, it will find the point of intersection between two straight lines. But for a \htmlref{SkyFrame}{SkyFrame} it will find an intersection of two great circles. } \sstsynopsis{ void astIntersect( AstFrame $*$this, const double a1[2], const double a2[2], const double b1[2], const double b2[2], double cross[2] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ a1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the first point on the first geodesic curve. } \sstsubsection{ a2 }{ An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the first geodesic curve. It should not be co-incident with the first point. } \sstsubsection{ b1 }{ An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of the first point on the second geodesic curve. } \sstsubsection{ b2 }{ An array of double, with one element for each Frame axis (Naxes attribute). This should contain the coordinates of a second point on the second geodesic curve. It should not be co-incident with the first point. } \sstsubsection{ cross }{ An array of double, with one element for each Frame axis in which the coordinates of the required intersection will be returned. } } \sstnotes{ \sstitemlist{ \sstitem 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 \texttt{"} a1\texttt{"} . \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the two points defining either geodesic are co-incident, or if the two curves do not intersect. \sstitem The geodesic curve used by this function is the path of shortest distance between two points, as defined by the \htmlref{astDistance}{astDistance} function. \sstitem An error will be reported if the Frame is not 2-dimensional. } } } \sstroutine{ astInterval }{ Create a Interval }{ \sstdescription{ This function creates a new \htmlref{Interval}{Interval} and optionally initialises its attributes. A Interval is a \htmlref{Region}{Region} which represents upper and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval. At least one axis limit must be supplied. Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} should usually be used in these cases since this requires the user to think about suitable upper and lower limits, } \sstsynopsis{ AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[], const double ubnd[], AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ lbnd }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute) containing the lower limits on each axis. Set a value to AST\_\_BAD to indicate that the axis has no lower limit. } \sstsubsection{ ubnd }{ An array of double, with one element for each Frame axis (Naxes attribute) containing the upper limits on each axis. Set a value to AST\_\_BAD to indicate that the axis has no upper limit. } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Interval being created. The uncertainty in any point on the boundary of the Interval is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Interval. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Interval being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Interval. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astInterval() }{ A pointer to the new Interval. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astIntraMap }{ Create an IntraMap }{ \sstdescription{ This function creates a new \htmlref{IntraMap}{IntraMap} and optionally initialises its attributes. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates a privately-defined coordinate transformation function (e.g. written in C) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. However, an IntraMap is intended for use within a single program or a private suite of software, where all programs have access to the same coordinate transformation functions (i.e. can be linked against them). IntraMaps should not normally be stored in datasets which may be exported for processing by other software, since that software will not have the necessary transformation functions available, resulting in an error. You must register any coordinate transformation functions to be used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap. } \sstsynopsis{ AstIntraMap $*$astIntraMap( const char $*$name, int nin, int nout, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ name }{ Pointer to a null-terminated string containing the name of the transformation function to use (which should previously have been registered using astIntraReg). This name is case sensitive. All white space will be removed before use. } \sstsubsection{ nin }{ The number of input coordinates. This must be compatible with the number of input coordinates accepted by the transformation function (as specified when this function was registered using astIntraReg). } \sstsubsection{ nout }{ The number of output coordinates. This must be compatible with the number of output coordinates produced by the transformation function (as specified when this function was registered using astIntraReg). } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new IntraMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astIntraMap() }{ A pointer to the new IntraMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astIntraReg }{ Register a transformation function for use by an IntraMap }{ \sstdescription{ This function registers a privately-defined coordinate transformation function written in C so that it may be used to create an \htmlref{IntraMap}{IntraMap}. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates the C function so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. Registration of relevant transformation functions is required before using the \htmlref{astIntraMap}{astIntraMap} constructor function to create an IntraMap or reading an external representation of an IntraMap from a \htmlref{Channel}{Channel}. } \sstsynopsis{ astIntraReg( const char $*$name, int nin, int nout, void ($*$ tran)( AstMapping $*$, int, int, const double $*$[], int, int, double $*$[] ), unsigned int flags, const char $*$purpose, const char $*$author, const char $*$contact ) } \sstparameters{ \sstsubsection{ name }{ Pointer to a null-terminated string containing a unique name to be associated with the transformation function in order to identify it. This name is case sensitive. All white space will be removed before use. } \sstsubsection{ nin }{ The number of input coordinates accepted by the transformation function (i.e. the number of dimensions of the space in which the input points reside). A value of AST\_\_ANY may be given if the function is able to accommodate a variable number of input coordinates. } \sstsubsection{ nout }{ The number of output coordinates produced by the transformation function (i.e. the number of dimensions of the space in which the output points reside). A value of AST\_\_ANY may be given if the function is able to produce a variable number of output coordinates. } \sstsubsection{ tran }{ Pointer to the transformation function to be registered. This function should perform whatever coordinate transformations are required and should have an interface like \htmlref{astTranP}{astTranP} (q.v.). } \sstsubsection{ flags }{ This value may be used to supply a set of flags which describe the transformation function and which may affect the behaviour of any IntraMap which uses it. Often, a value of zero will be given here, but you may also supply the bitwise OR of a set of flags as described in the \texttt{"} Transformation Flags\texttt{"} section (below). } \sstsubsection{ purpose }{ Pointer to a null-terminated string containing a short (one line) textual comment to describe the purpose of the transformation function. } \sstsubsection{ author }{ Pointer to a null-terminated string containing the name of the author of the transformation function. } \sstsubsection{ contact }{ Pointer to a null-terminated string containing contact details for the author of the transformation function (e.g. an e-mail or WWW address). If any IntraMap which uses this transformation function is exported as part of a dataset to an external user who does not have access to the function, then these contact details should allow them to obtain the necessary code. } } \sstnotes{ \sstitemlist{ \sstitem Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation function which it uses, so will only refer to the function by its name (as assigned using astIntraReg). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation function with the same name using an identical invocation of astIntraReg. If no such registration has been performed, then attempting to read the external representation will result in an error. \sstitem You may use astIntraReg to register a transformation function with the same name more than once, but only if the arguments supplied are identical on each occasion (i.e there is no way of changing things once a function has been successfully registered under a given name, and attempting to do so will result in an error). This feature simply allows registration to be performed independently, but consistently, at several places within your program, without having to check whether it has already been done. \sstitem If an error occurs in the transformation function, this may be indicated by setting the AST error status to an error value (using \htmlref{astSetStatus}{astSetStatus}) before it returns. This will immediately terminate the current AST operation. The error value AST\_\_ITFER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). } } \sstdiytopic{ Transformation Flags }{ The following flags are defined in the ``ast.h\texttt{'} \texttt{'} header file and allow you to provide further information about the nature of the transformation function. Having selected the set of flags which apply, you should supply the bitwise OR of their values as the ``flags\texttt{'} \texttt{'} argument to astIntraReg. \sstitemlist{ \sstitem AST\_\_NOFWD: If this flag is set, it indicates that the transformation function does not implement a forward coordinate transformation. In this case, any IntraMap which uses it will have a \htmlref{TranForward}{TranForward} attribute value of zero and the transformation function itself will not be invoked with its ``forward\texttt{'} \texttt{'} argument set to a non-zero value. By default, it is assumed that a forward transformation is provided. \sstitem AST\_\_NOINV: If this flag is set, it indicates that the transformation function does not implement an inverse coordinate transformation. In this case, any IntraMap which uses it will have a \htmlref{TranInverse}{TranInverse} attribute value of zero and the transformation function itself will not be invoked with its ``forward\texttt{'} \texttt{'} argument set to zero. By default, it is assumed that an inverse transformation is provided. \sstitem AST\_\_SIMPFI: You may set this flag if applying the transformation function\texttt{'} s forward coordinate transformation, followed immediately by the matching inverse transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). It is not necessary that both transformations have actually been implemented. \sstitem AST\_\_SIMPIF: You may set this flag if applying the transformation function\texttt{'} s inverse coordinate transformation, followed immediately by the matching forward transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented. } } } \sstroutine{ astInvert }{ Invert a Mapping }{ \sstdescription{ This function inverts a \htmlref{Mapping}{Mapping} by reversing the boolean sense of its \htmlref{Invert}{Invert} attribute. If this attribute is zero (the default), the Mapping will transform coordinates in the way specified when it was created. If it is non-zero, the input and output coordinates will be inter-changed so that the direction of the Mapping is reversed. This will cause it to display the inverse of its original behaviour. } \sstsynopsis{ void astInvert( AstMapping $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping. } } } \sstroutine{ astIsA$<$Class$>$ }{ Test membership of a class by an Object }{ \sstdescription{ This is a family of functions which test whether an \htmlref{Object}{Object} is a member of the class called $<$\htmlref{Class}{Class}$>$, or of any class derived from it. } \sstsynopsis{ int astIsA$<$Class$>$( const Ast$<$Class$>$ $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } } \sstapplicability{ \sstsubsection{ Object }{ These functions apply to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astIsA$<$Class$>$() }{ One if the Object belongs to the class called $<$Class$>$ (or to a class derived from it), otherwise zero. } } \sstexamples{ \sstexamplesubsection{ member = astIsAFrame( obj ); }{ Tests whether Object \texttt{"} obj\texttt{"} is a member of the \htmlref{Frame}{Frame} class, or of any class derived from a Frame. } } \sstnotes{ \sstitemlist{ \sstitem Every AST class provides a function (astIsA$<$Class$>$) of this form, where $<$Class$>$ should be replaced by the class name. \sstitem This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem A value of zero will be returned if this function should fail for any reason. In particular, it will fail if the pointer supplied does not identify an Object of any sort. } } } \sstroutine{ astKeyMap }{ Create a KeyMap }{ \sstdescription{ This function creates a new empty \htmlref{KeyMap}{KeyMap} and optionally initialises its attributes. Entries can then be added to the KeyMap using the \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$} and \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$} functions. The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), void pointer, character string or AST \htmlref{Object}{Object} pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap. } \sstsynopsis{ AstKeyMap $*$astKeyMap( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new KeyMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astKeyMap() }{ A pointer to the new KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astLinearApprox }{ Obtain a linear approximation to a Mapping, if appropriate }{ \sstdescription{ This function tests the forward coordinate transformation implemented by a \htmlref{Mapping}{Mapping} over a given range of input coordinates. If the transformation is found to be linear to a specified level of accuracy, then an array of fit coefficients is returned. These may be used to implement a linear approximation to the Mapping\texttt{'} s forward transformation within the specified range of output coordinates. If the transformation is not sufficiently linear, no coefficients are returned. } \sstsynopsis{ int astLinearApprox( AstMapping $*$this, const double $*$lbnd, const double $*$ubnd, double tol, double $*$fit ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping. } \sstsubsection{ lbnd }{ Pointer to an array of doubles containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This box should specify the region over which linearity is required. } \sstsubsection{ ubnd }{ Pointer to an array of doubles containing the upper bounds of the box specifying the region over which linearity is required. } \sstsubsection{ tol }{ The maximum permitted deviation from linearity, expressed as a positive Cartesian displacement in the output coordinate space of the Mapping. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then no fit coefficients will be returned. } \sstsubsection{ fit }{ Pointer to an array of doubles in which to return the co-efficients of the linear approximation to the specified transformation. This array should have at least \texttt{"} ( Nin $+$ 1 ) $*$ \htmlref{Nout}{Nout}\texttt{"} , elements. The first Nout elements hold the constant offsets for the transformation outputs. The remaining elements hold the gradients. So if the Mapping has 2 inputs and 3 outputs the linear approximation to the forward transformation is: X\_out = fit[0] $+$ fit[3]$*$X\_in $+$ fit[4]$*$Y\_in Y\_out = fit[1] $+$ fit[5]$*$X\_in $+$ fit[6]$*$Y\_in Z\_out = fit[2] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in } } \sstreturnedvalue{ \sstsubsection{ astLinearApprox() }{ If the forward transformation is sufficiently linear, a non-zero value is returned. Otherwise zero is returned and the fit co-efficients are set to AST\_\_BAD. } } \sstnotes{ \sstitemlist{ \sstitem This function fits the Mapping\texttt{'} s forward transformation. To fit the inverse transformation, the Mapping should be inverted using \htmlref{astInvert}{astInvert} before invoking this function. \sstitem 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. } } } \sstroutine{ astLock }{ Lock an Object for exclusive use by the calling thread }{ \sstdescription{ The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an \htmlref{Object}{Object} that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using \htmlref{astUnlock}{astUnlock}) and the new thread must then lock it (using astLock) before the new thread can use the Object. The \texttt{"} wait\texttt{"} parameter determines what happens if the supplied Object is curently locked by another thread when this function is invoked. } \sstsynopsis{ void astLock( AstObject $*$this, int wait ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be locked. } \sstsubsection{ wait }{ If the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for \texttt{"} wait\texttt{"} , the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem The \htmlref{astAnnul}{astAnnul} function is exceptional in that it can be used on pointers for Objects that are not currently locked by the calling thread. All other AST functions will report an error. \sstitem The Locked object will belong to the current AST context. \sstitem This function returns without action if the Object is already locked by the calling thread. \sstitem If simultaneous use of the same object is required by two or more threads, \htmlref{astCopy}{astCopy} should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy). \sstitem This function is only available in the C interface. \sstitem This function returns without action if the AST library has been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} option was not specified when running the \texttt{"} configure\texttt{"} script). } } } \sstroutine{ astLutMap }{ Create a LutMap }{ \sstdescription{ This function creates a new \htmlref{LutMap}{LutMap} and optionally initialises its attributes. A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. Each input coordinate value is first scaled to give the index of an entry in the table by subtracting a starting value (the input coordinate corresponding to the first table entry) and dividing by an increment (the difference in input coordinate value between adjacent table entries). The resulting index will usually contain a fractional part, so the output coordinate value is then generated by interpolating linearly between the appropriate entries in the table. If the index lies outside the range of the table, linear extrapolation is used based on the two nearest entries (i.e. the two entries at the start or end of the table, as appropriate). If the lookup table entries increase or decrease monotonically, then the inverse transformation may also be performed. } \sstsynopsis{ AstLutMap $*$astLutMap( int nlut, const double lut[], double start, double inc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nlut }{ The number of entries in the lookup table. This value must be at least 2. } \sstsubsection{ lut }{ An array containing the \texttt{"} nlut\texttt{"} lookup table entries. } \sstsubsection{ start }{ The input coordinate value which corresponds to the first lookup table entry. } \sstsubsection{ inc }{ The lookup table spacing (the increment in input coordinate value between successive lookup table entries). This value may be positive or negative, but must not be zero. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new LutMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astLutMap() }{ A pointer to the new LutMap. } } \sstnotes{ \sstitemlist{ \sstitem If the entries in the lookup table either increase or decrease monotonically, then the new LutMap\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute will have a value of one, indicating that the inverse transformation can be performed. Otherwise, it will have a value of zero, so that any attempt to use the inverse transformation will result in an error. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astMapBox }{ Find a bounding box for a Mapping }{ \sstdescription{ This function allows you to find the \texttt{"} bounding box\texttt{"} which just encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping} (using either its forward or inverse transformation). A typical use might be to calculate the size of an image after being transformed by a Mapping. The function works on one dimension at a time. When supplied with the lower and upper bounds of a rectangular region (box) of input coordinate space, it finds the lowest and highest values taken by a nominated output coordinate within that region. Optionally, it also returns the input coordinates where these bounding values are attained. It should be used repeatedly to obtain the extent of the bounding box in more than one dimension. } \sstsynopsis{ void astMapBox( AstMapping $*$this, const double lbnd\_in[], const double ubnd\_in[], int forward, int coord\_out, double $*$lbnd\_out, double $*$ubnd\_out, double xl[], double xu[] ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping. } \sstsubsection{ lbnd\_in }{ Pointer to an array of double, with one element for each Mapping input coordinate. This should contain the lower bound of the input box in each input dimension. } \sstsubsection{ ubnd\_in }{ Pointer to an array of double, with one element for each Mapping input coordinate. This should contain the upper bound of the input box in each input dimension. Note that it is permissible for the upper bound to be less than the corresponding lower bound, as the values will simply be swapped before use. } \sstsubsection{ forward }{ If this value is non-zero, then the Mapping\texttt{'} s forward transformation will be used to transform the input box. Otherwise, its inverse transformation will be used. (If the inverse transformation is selected, then references to \texttt{"} input\texttt{"} and \texttt{"} output\texttt{"} coordinates in this description should be transposed. For example, the size of the \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} arrays should match the number of output coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout} attribute. Similarly, the \texttt{"} coord\_out\texttt{"} parameter, below, should nominate one of the Mapping\texttt{'} s input coordinates.) } \sstsubsection{ coord\_out }{ The index of the output coordinate for which the lower and upper bounds are required. This value should be at least one, and no larger than the number of Mapping output coordinates. } \sstsubsection{ lbnd\_out }{ Pointer to a double in which to return the lowest value taken by the nominated output coordinate within the specified region of input coordinate space. } \sstsubsection{ ubnd\_out }{ Pointer to a double in which to return the highest value taken by the nominated output coordinate within the specified region of input coordinate space. } \sstsubsection{ xl }{ An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the lower bound value returned in \texttt{"} $*$lbnd\_out\texttt{"} . If these coordinates are not required, a NULL pointer may be supplied. } \sstsubsection{ xu }{ An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the upper bound value returned in \texttt{"} $*$ubnd\_out\texttt{"} . If these coordinates are not required, a NULL pointer may be supplied. } } \sstnotes{ \sstitemlist{ \sstitem Any input points which are transformed by the Mapping to give output coordinates containing the value AST\_\_BAD are regarded as invalid and are ignored. They will make no contribution to determining the output bounds, even although the nominated output coordinate might still have a valid value at such points. \sstitem An error will occur if the required output bounds cannot be found. Typically, this might happen if all the input points which the function considers turn out to be invalid (see above). The number of points considered before generating such an error is quite large, so this is unlikely to occur by accident unless valid points are restricted to a very small subset of the input coordinate space. \sstitem The values returned via \texttt{"} lbnd\_out\texttt{"} , \texttt{"} ubnd\_out\texttt{"} , \texttt{"} xl\texttt{"} and \texttt{"} xu\texttt{"} will be set to the value AST\_\_BAD if this function should fail for any reason. Their initial values on entry will not be altered if the function is invoked with the AST error status set. } } } \sstroutine{ astMapCopy }{ Copy entries from one KeyMap into another }{ \sstdescription{ This function copies all entries from one \htmlref{KeyMap}{KeyMap} into another. } \sstsynopsis{ void astMapCopy( AstKeyMap $*$this, AstKeyMap $*$that ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the destination KeyMap. } \sstsubsection{ that }{ Pointer to the source KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem Entries from the source KeyMap will replace any existing entries in the destination KeyMap that have the same key. \sstitem The one exception to the above rule is that if a source entry contains a scalar KeyMap entry, and the destination contains a scalar KeyMap entry with the same key, then the source KeyMap entry will be copied into the destination KeyMap entry using this function, rather than simply replacing the destination KeyMap entry. \sstitem If the destination entry has a non-zero value for its \htmlref{MapLocked}{MapLocked} attribute, then an error will be reported if the source KeyMap contains any keys that do not already exist within the destination KeyMap. } } } \sstroutine{ astMapDefined }{ Check if a KeyMap contains a defined value for a key }{ \sstdescription{ This function checks to see if a \htmlref{KeyMap}{KeyMap} contains a defined value for a given key. If the key is present in the KeyMap but has an undefined value it returns zero (unlike \htmlref{astMapHasKey}{astMapHasKey} which would return non-zero). } \sstsynopsis{ int astMapDefined( AstKeyMap $*$this, const char $*$key ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } \sstreturnedvalue{ \sstsubsection{ astMapDefined() }{ A non-zero value is returned if the requested key name is present in the KeyMap and has a defined value. } } } \sstroutine{ astMapGet0$<$X$>$ }{ Get a scalar value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a scalar value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). } \sstsynopsis{ int astMapGet0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type $*$value ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ value }{ A pointer to a buffer in which to return the requested value. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{astMapPutU}{astMapPutU}), then the contents of the buffer on entry to this function will be unchanged on exit. For pointer types (\texttt{"} A\texttt{"} and \texttt{"} C\texttt{"} ), the buffer should be a suitable pointer, and the address of this pointer should be supplied as the \texttt{"} value\texttt{"} parameter. } } \sstreturnedvalue{ \sstsubsection{ astMapGet0$<$X$>$() }{ A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, but a zero value will be returned as the function value. The supplied buffer will be returned unchanged. \sstitem If the stored value is a vector value, then the first value in the vector will be returned. \sstitem A string pointer returned by astMapGet0C is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. The calling code should never attempt to free the returned pointer (for instance, using \htmlref{astFree}{astFree}). \sstitem If the returned value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object. The returned pointer should be annulled using \htmlref{astAnnul}{astAnnul} when it is no longer needed. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem F: float \sstitem D: double \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: Unsigned byte (i.e. word) } For example, astMapGet0D would be used to get a \texttt{"} double\texttt{"} value, while astMapGet0I would be used to get an \texttt{"} int\texttt{"} , etc. } } \sstroutine{ astMapGet1$<$X$>$ }{ Get a vector value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a vector value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the astMapGet1C function has an extra parameter \texttt{"} l\texttt{"} which specifies the maximum length of each string to be stored in the \texttt{"} value\texttt{"} buffer (see the \texttt{"} astMapGet1C\texttt{"} section below). } \sstsynopsis{ int astMapGet1$<$X$>$( AstKeyMap $*$this, const char $*$key, int mxval, int $*$nval, $<$X$>$type $*$value ) int astMapGet1C( AstKeyMap $*$this, const char $*$key, int l, int mxval, int $*$nval, const char $*$value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ mxval }{ The number of elements in the \texttt{"} value\texttt{"} array. } \sstsubsection{ nval }{ The address of an integer in which to put the number of elements stored in the \texttt{"} value\texttt{"} array. Any unused elements of the array are left unchanged. } \sstsubsection{ value }{ A pointer to an array in which to return the requested values. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{astMapPutU}{astMapPutU}), then the contents of the buffer on entry to this function will be unchanged on exit. } } \sstreturnedvalue{ \sstsubsection{ astMapGet1$<$X$>$() }{ A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, but a zero value will be returned as the function value. The supplied array will be returned unchanged. \sstitem If the stored value is a scalar value, then the value will be returned in the first element of the supplied array, and \texttt{"} nval\texttt{"} will be returned set to 1. } } \sstdiytopic{ astMapGet1C }{ The \texttt{"} value\texttt{"} buffer supplied to the astMapGet1C function should be a pointer to a character array with \texttt{"} mxval$*$l\texttt{"} elements, where \texttt{"} l\texttt{"} is the maximum length of a string to be returned. The value of \texttt{"} l\texttt{"} should be supplied as an extra parameter following \texttt{"} key\texttt{"} when invoking astMapGet1C, and should include space for a terminating null character. } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: Unsigned byte (i.e. char) } For example, astMapGet1D would be used to get \texttt{"} double\texttt{"} values, while astMapGet1I would be used to get \texttt{"} int\texttt{"} values, etc. For D or I, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to an array of doubles or ints, with \texttt{"} mxval\texttt{"} elements. For C, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a character string with \texttt{"} mxval$*$l\texttt{"} elements. For A, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to an array of AstObject pointers. } } \sstroutine{ astMapGetElem$<$X$>$ }{ Get a single element of a vector value from a KeyMap }{ \sstdescription{ This is a set of functions for retrieving a single element of a vector value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the astMapGetElemC function has an extra parameter \texttt{"} l\texttt{"} which specifies the maximum length of the string to be stored in the \texttt{"} value\texttt{"} buffer (see the \texttt{"} astMapGetElemC\texttt{"} section below). } \sstsynopsis{ int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, $<$X$>$type $*$value ) int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem, char $*$value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ elem }{ The index of the required vector element, starting at zero. An error will be reported if the value is outside the range of the vector. } \sstsubsection{ value }{ A pointer to a buffer in which to return the requested value. If the requested key is not found, or if it is found but has an undefined value (see \htmlref{astMapPutU}{astMapPutU}), then the contents of the buffer on entry to this function will be unchanged on exit. } } \sstreturnedvalue{ \sstsubsection{ astMapGetElem$<$X$>$() }{ A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise. } } \sstnotes{ \sstitemlist{ \sstitem No error is reported if the requested key cannot be found in the given KeyMap, or if it has an undefined value, but a zero value will be returned as the function value. } } \sstdiytopic{ astMapGetElemC }{ The \texttt{"} value\texttt{"} buffer supplied to the astMapGetElemC function should be a pointer to a character array with \texttt{"} l\texttt{"} elements, where \texttt{"} l\texttt{"} is the maximum length of the string to be returned. The value of \texttt{"} l\texttt{"} should be supplied as an extra parameter following \texttt{"} key\texttt{"} when invoking astMapGetElemC, and should include space for a terminating null character. } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: Unsigned byte (i.e. char) } For example, astMapGetElemD would be used to get a \texttt{"} double\texttt{"} value, while astMapGetElemI would be used to get an \texttt{"} int\texttt{"} value, etc. For D or I, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a double or int. For C, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a character string with \texttt{"} l\texttt{"} elements. For A, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to an AstObject pointer. } } \sstroutine{ astMapHasKey }{ Check if an entry with a given key exists in a KeyMap }{ \sstdescription{ This function returns a flag indicating if the \htmlref{KeyMap}{KeyMap} contains an entry with the given key. } \sstsynopsis{ int astMapHasKey( AstKeyMap $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } \sstreturnedvalue{ \sstsubsection{ astMapHasKey() }{ Non-zero if the key was found, and zero otherwise. } } \sstnotes{ \sstitemlist{ \sstitem A non-zero function value is returned if the key exists but has an undefined value (that is, the returned value does not depend on whether the entry has a defined value or not). See also \htmlref{astMapDefined}{astMapDefined}, which returns zero in such a case. \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astMapKey }{ Get the key at a given index within the KeyMap }{ \sstdescription{ This function returns a string holding the key for the entry with the given index within the \htmlref{KeyMap}{KeyMap}. This function is intended primarily as a means of iterating round all the elements in a KeyMap. For this purpose, the number of entries in the KeyMap should first be found using \htmlref{astMapSize}{astMapSize} and this function should then be called in a loop, with the index value going from zero to one less than the size of the KeyMap. The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy} attribute. } \sstsynopsis{ const char $*$astMapKey( AstKeyMap $*$this, int index ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ index }{ The index into the KeyMap. The first entry has index zero, and the last has index \texttt{"} size-1\texttt{"} , where \texttt{"} size\texttt{"} is the value returned by the astMapSize function. } } \sstreturnedvalue{ \sstsubsection{ astMapKey() }{ A pointer to a null-terminated string containing the key. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. \sstitem A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astMapLenC }{ Get the number of characters in a character entry in a KeyMap }{ \sstdescription{ This function returns the minimum length which a character variable which must have in order to be able to store a specified entry in the supplied \htmlref{KeyMap}{KeyMap}. If the named entry is a vector entry, then the returned value is the length of the longest element of the vector value. } \sstsynopsis{ int astMapLenC( AstKeyMap $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } \sstreturnedvalue{ \sstsubsection{ astMapLenC() }{ The length (i.e. number of characters) of the longest formatted value associated with the named entry. This does not include the trailing null character. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned without error if the named entry cannot be formatted as a character string. \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astMapLength }{ Get the vector length of an entry in a KeyMap }{ \sstdescription{ This function returns the vector length of a named entry in a \htmlref{KeyMap}{KeyMap}, (that is, how many values are associated with the entry). } \sstsynopsis{ int astMapLength( AstKeyMap $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } \sstreturnedvalue{ \sstsubsection{ astMapLength() }{ The length of the entry. One for a scalar, greater than one for a vector. A value of zero is returned if the KeyMap does not contain the named entry. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astMapPut0$<$X$>$ }{ Add a scalar value to a KeyMap }{ \sstdescription{ This is a set of functions for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a function which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic function name astMapPut0$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). } \sstsynopsis{ void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value, const char $*$comment ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap in which to store the supplied value. } \sstsubsection{ key }{ A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ value }{ The value to be stored. The data type of this value should match the 1-character type code appended to the function name (e.g. if you are using astMapPut0A, the type of this value should be \texttt{"} pointer to AstObject\texttt{"} ). } \sstsubsection{ comment }{ A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the new value will replace the old value. \sstitem If the stored value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference count is incremented by this call. Any subsequent changes made to the Object using the returned pointer will be reflected in any any other active pointers for the Object, including any obtained later using astMapget0A. The reference count for the Object will be decremented when the KeyMap is destroyed, or the entry is removed or over-written with a different pointer. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPut0$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: unsigned byte (i.e. unsigned char) } For example, astMapPut0D would be used to store a \texttt{"} double\texttt{"} value, while astMapPut0I would be used to store an \texttt{"} int\texttt{"} , etc. Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"} pointers cannot be written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if this is attempted. } } \sstroutine{ astMapPut1$<$X$>$ }{ Add a vector value to a KeyMap }{ \sstdescription{ This is a set of functions for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a function which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic function name astMapPut1$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). } \sstsynopsis{ void astMapPut1$<$X$>$( AstKeyMap $*$this, const char $*$key, int size, const $<$X$>$type value[], const char $*$comment ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap in which to store the supplied values. } \sstsubsection{ key }{ A character string to be stored with the values, which can later be used to identify the values. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ size }{ The number of elements in the supplied array of values. } \sstsubsection{ value }{ The array of values to be stored. The data type of this value should match the 1-character type code appended to the function name (e.g. if you are using astMapPut1A, the type of this value should be \texttt{"} array of pointers to AstObject\texttt{"} ). } \sstsubsection{ comment }{ A pointer to a null-terminated comment string to be stored with the values. A NULL pointer may be supplied, in which case no comment is stored. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the new values will replace the old values. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPut1$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: Unsigned byte (i.e. char) } For example, astMapPut1D would be used to store \texttt{"} double\texttt{"} values, while astMapPut1I would be used to store \texttt{"} int\texttt{"} , etc. Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"} pointers cannot be written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if this is attempted. } } \sstroutine{ astMapPutElem$<$X$>$ }{ Put a value into an element of a vector value in a KeyMap }{ \sstdescription{ This is a set of functions for storing a value in a single element of a vector value in a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name astMapPutElem$<$X$>$ by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} section below for the code appropriate to each supported data type). The supplied value is converted from the data type indicated by $<$X$>$ to the data type of the KeyMap entry before being stored (an error is reported if it is not possible to convert the value to the required data type). } \sstsynopsis{ void astMapPutElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, $<$X$>$type $*$value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ elem }{ The index of the vector element to modify, starting at zero. } \sstsubsection{ value }{ The value to store. } } \sstapplicability{ \sstsubsection{ KeyMap }{ If the \texttt{"} elem\texttt{"} index is outside the range of the vector, the length of the vector will be increased by one element and the supplied value will be stored at the end of the vector in the new element. } \sstsubsection{ \htmlref{Table}{Table} }{ If the \texttt{"} elem\texttt{"} index is outside the range of the vector, an error will be reported. The number of elements in each cell of a column is specified when the column is created using \htmlref{astAddColumn}{astAddColumn}. } } \sstnotes{ \sstitemlist{ \sstitem If the entry originally holds a scalar value, it will be treated like a vector entry of length 1. \sstitem If the specified key cannot be found in the given KeyMap, or is found but has an undefined value, a new vector entry with the given name, and data type implied by $<$X$>$, is created and the supplied value is stored in its first entry. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPutElem$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem C: \texttt{"} const\texttt{"} pointer to null terminated character string \sstitem A: Pointer to AstObject \sstitem P: Generic \texttt{"} void $*$\texttt{"} pointer \sstitem S: short int \sstitem B: Unsigned byte (i.e. char) } For example, astMapPutElemD would be used to put a \texttt{"} double\texttt{"} value, while astMapPutElemI would be used to put an \texttt{"} int\texttt{"} value, etc. For D or I, the supplied \texttt{"} value\texttt{"} parameter should be a double or int. For C, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a character string. For A, the supplied \texttt{"} value\texttt{"} parameter should be an AstObject pointer. } } \sstroutine{ astMapPutU }{ Add an entry to a KeyMap with an undefined value }{ \sstdescription{ This function adds a new entry to a \htmlref{KeyMap}{KeyMap}, but no value is stored with the entry. The entry therefore has a special data type represented by symbolic constant AST\_\_UNDEFTYPE. An example use is to add entries with undefined values to a KeyMap prior to locking them with the \htmlref{MapLocked}{MapLocked} attribute. Such entries can act as placeholders for values that can be added to the KeyMap later. } \sstsynopsis{ void astMapPutU( AstKeyMap $*$this, const char $*$key, const char $*$comment ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap in which to store the supplied value. } \sstsubsection{ key }{ A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ comment }{ A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored. } } \sstnotes{ \sstitemlist{ \sstitem If the supplied key is already in use in the KeyMap, the value associated with the key will be removed. } } } \sstroutine{ astMapRegion }{ Transform a Region into a new Frame using a given Mapping }{ \sstdescription{ This function returns a pointer to a new \htmlref{Region}{Region} which corresponds to supplied Region described by some other specified coordinate system. A \htmlref{Mapping}{Mapping} is supplied which transforms positions between the old and new coordinate systems. The new Region may not be of the same class as the original region. } \sstsynopsis{ AstRegion $*$astMapRegion( AstRegion $*$this, AstMapping $*$map, AstFrame $*$frame ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ map }{ Pointer to a Mapping which transforms positions from the coordinate system represented by the supplied Region to the coordinate system specified by \texttt{"} frame\texttt{"} . The supplied Mapping should define both forward and inverse transformations, and these transformations should form a genuine inverse pair. That is, transforming a position using the forward transformation and then using the inverse transformation should produce the original input position. Some Mapping classes (such as \htmlref{PermMap}{PermMap}, \htmlref{MathMap}{MathMap}, \htmlref{SphMap}{SphMap}) can result in Mappings for which this is not true. } \sstsubsection{ frame }{ Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which the new Region is required. } } \sstreturnedvalue{ \sstsubsection{ astMapRegion() }{ A pointer to a new Region. This Region will represent the area within the coordinate system specified by \texttt{"} frame\texttt{"} which corresponds to the supplied Region. } } \sstnotes{ \sstitemlist{ \sstitem The uncertainty associated with the supplied Region is modified using the supplied Mapping. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astMapRemove }{ Removed a named entry from a KeyMap }{ \sstdescription{ This function removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the KeyMap does not contain the specified key. } \sstsynopsis{ void astMapRemove( AstKeyMap $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } } \sstroutine{ astMapRename }{ Rename an existing KeyMap entry }{ \sstdescription{ This function associated a new key with an existing entry in a \htmlref{KeyMap}{KeyMap}. It returns without action if the oldkey does not exist in the KeyMap. } \sstsynopsis{ void astMapRename( AstKeyMap $*$this, const char $*$oldkey, const char $*$newkey ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ oldkey }{ The character string identifying the entry to be renamed. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } \sstsubsection{ newkey }{ The new character string to associated with the renamed entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero. } } } \sstroutine{ astMapSize }{ Get the number of entries in a KeyMap }{ \sstdescription{ This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}. } \sstsynopsis{ int astMapSize( AstKeyMap $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } } \sstreturnedvalue{ \sstsubsection{ astMapSize() }{ The number of entries in the KeyMap. } } \sstnotes{ \sstitemlist{ \sstitem A function value of zero will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astMapSplit }{ Split a Mapping up into parallel component Mappings }{ \sstdescription{ This function creates a new \htmlref{Mapping}{Mapping} which connects specified inputs within a supplied Mapping to the corresponding outputs of the supplied Mapping. This is only possible if the specified inputs correspond to some subset of the Mapping outputs. That is, there must exist a subset of the Mapping outputs for which each output depends only on the selected Mapping inputs, and not on any of the inputs which have not been selected. Also, any output which is not in this subset must not depend on any of the selected inputs. If these conditions are not met by the supplied Mapping, then a NULL Mapping pointer is returned. } \sstsynopsis{ void astMapSplit( AstMapping $*$this, int nin, const int $*$in, int $*$out, AstMapping $*$$*$map ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be split. } \sstsubsection{ nin }{ The number of inputs to pick from \texttt{"} this\texttt{"} . } \sstsubsection{ in }{ Pointer to an array holding the indices within the supplied Mapping of the inputs which are to be picked from the Mapping. This array should have \texttt{"} nin\texttt{"} elements. If \texttt{"} \htmlref{Nin}{Nin}\texttt{"} is the number of inputs of the supplied Mapping, then each element should have a value in the range 1 to Nin. } \sstsubsection{ out }{ Pointer to an array in which to return the indices of the outputs of the supplied Mapping which are fed by the picked inputs. A value of one is used to refer to the first Mapping output. The supplied array should have a length at least equal to the number of outputs in the supplied Mapping. The number of values stored in the array on exit will equal the number of outputs in the returned Mapping. The i\texttt{'} th element in the returned array holds the index within the supplied Mapping which corresponds to the i\texttt{'} th output of the returned Mapping. } \sstsubsection{ map }{ Address of a location at which to return a pointer to the returned Mapping. This Mapping will have \texttt{"} nin\texttt{"} inputs (the number of outputs may be different to \texttt{"} nin\texttt{"} ). NULL is returned if the supplied Mapping has no subset of outputs which depend only on the selected inputs. The returned Mapping is a deep copy of the required parts of the supplied Mapping. } } \sstnotes{ \sstitemlist{ \sstitem If this function is invoked with the global error status set, or if it should fail for any reason, then a NULL value will be returned for the \texttt{"} map\texttt{"} pointer. } } } \sstroutine{ astMapType }{ Get the data type of an entry in a KeyMap }{ \sstdescription{ This function returns a value indicating the data type of a named entry in a \htmlref{KeyMap}{KeyMap}. This is the data type which was used when the entry was added to the KeyMap. } \sstsynopsis{ int astMapType( AstKeyMap $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the KeyMap. } \sstsubsection{ key }{ The character string identifying the KeyMap entry. Trailing spaces are ignored. The supplied string is converted to upper case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. } } \sstreturnedvalue{ \sstsubsection{ astMapType() }{ One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for short int), AST\_\_BYTETYPE (for unsigned bytes \sstitemlist{ \sstitem i.e. unsigned chars ) AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{astMapPutU}{astMapPutU}). AST\_\_BADTYPE is returned if the supplied key is not found in the KeyMap. } } } \sstnotes{ \sstitemlist{ \sstitem A function value of AST\_\_BADTYPE will be returned if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astMark }{ Draw a set of markers for a Plot }{ \sstdescription{ This function draws a set of markers (symbols) at positions specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The positions are transformed into graphical coordinates to determine where the markers should appear within the plotting area. } \sstsynopsis{ void astMark( AstPlot $*$this, int nmark, int ncoord, int indim, const double $*$in, int type ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ nmark }{ The number of markers to draw. This may be zero, in which case nothing will be drawn. } \sstsubsection{ ncoord }{ The number of coordinates being supplied for each mark (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given by its \htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ indim }{ The number of elements along the second dimension of the \texttt{"} in\texttt{"} array (which contains the marker coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than \texttt{"} nmark\texttt{"} . } \sstsubsection{ in }{ The address of the first element of a 2-dimensional array of shape \texttt{"} [ncoord][indim]\texttt{"} giving the physical coordinates of the points where markers are to be drawn. These should be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for input mark number \texttt{"} mark\texttt{"} is found in element \texttt{"} in[coord][mark]\texttt{"} . } \sstsubsection{ type }{ A value specifying the type (e.g. shape) of marker to be drawn. The set of values which may be used (and the shapes that will result) is determined by the underlying graphics system. } } \sstnotes{ \sstitemlist{ \sstitem Markers are not drawn at positions which have any coordinate equal to the value AST\_\_BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST\_\_BAD). \sstitem If any marker position is clipped (see \htmlref{astClip}{astClip}), then the entire marker is not drawn. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astMask$<$X$>$ }{ Mask a region of a data grid }{ \sstdescription{ This is a set of functions for masking out regions within gridded data (e.g. an image). The functions modifies a given data grid by assigning a specified value to all samples which are inside (or outside if \texttt{"} inside\texttt{"} is zero) the specified \htmlref{Region}{Region}. You should use a masking function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astMask$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are masking data with type \texttt{"} float\texttt{"} , you should use the function astMaskF (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstsynopsis{ int astMask$<$X$>$( AstRegion $*$this, AstMapping $*$map, int inside, int ndim, const int lbnd[], const int ubnd[], $<$Xtype$>$ in[], $<$Xtype$>$ val ) } \sstparameters{ \sstsubsection{ this }{ Pointer to a Region. } \sstsubsection{ map }{ Pointer to a \htmlref{Mapping}{Mapping}. The forward transformation should map positions in the coordinate system of the supplied Region into pixel coordinates as defined by the \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} parameters. A NULL pointer can be supplied if the coordinate system of the supplied Region corresponds to pixel coordinates. This is equivalent to supplying a \htmlref{UnitMap}{UnitMap}. The number of inputs for this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of axes in the supplied Region (as given by the \htmlref{Naxes}{Naxes} attribute of the Region). The number of outputs for the Mapping (as given by its \htmlref{Nout}{Nout} attribute) should match the number of grid dimensions given by the value of \texttt{"} ndim\texttt{"} below. } \sstsubsection{ inside }{ A boolean value which indicates which pixel are to be masked. If a non-zero value is supplied, then all grid pixels with centres inside the supplied Region are assigned the value given by \texttt{"} val\texttt{"} , and all other pixels are left unchanged. If zero is supplied, then all grid pixels with centres not inside the supplied Region are assigned the value given by \texttt{"} val\texttt{"} , and all other pixels are left unchanged. Note, the \htmlref{Negated}{Negated} attribute of the Region is used to determine which pixel are inside the Region and which are outside. So the inside of a Region which has not been negated is the same as the outside of the corresponding negated Region. For types of Region such as \htmlref{PointList}{PointList} which have zero volume, pixel centres will rarely fall exactly within the Region. For this reason, the inclusion criterion is changed for zero-volume Regions so that pixels are included (or excluded) if any part of the Region passes through the pixel. For a PointList, this means that pixels are included (or excluded) if they contain at least one of the points listed in the PointList. } \sstsubsection{ ndim }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ lbnd }{ Pointer to an array of integers, with \texttt{"} ndim\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd }{ Pointer to an array of integers, with \texttt{"} ndim\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ in }{ Pointer to an array, with one element for each pixel in the input grid, containing the data to be masked. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astMaskF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). On exit, the samples specified by \texttt{"} inside\texttt{"} are set to the value of \texttt{"} val\texttt{"} . All other samples are left unchanged. } \sstsubsection{ val }{ This argument should have the same type as the elements of the \texttt{"} in\texttt{"} array. It specifies the value used to flag the masked data (see \texttt{"} inside\texttt{"} ). } } \sstreturnedvalue{ \sstsubsection{ astMask$<$X$>$() }{ The number of pixels to which a value of \texttt{"} badval\texttt{"} has been assigned. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem An error will be reported if the overlap of the Region and the array cannot be determined. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astMask$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem L: long int \sstitem UL: unsigned long int \sstitem I: int \sstitem UI: unsigned int \sstitem S: short int \sstitem US: unsigned short int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astMaskD would be used to process \texttt{"} double\texttt{"} data, while astMaskS would be used to process \texttt{"} short int\texttt{"} data, etc. } } \sstroutine{ astMatchAxes }{ Find any corresponding axes in two Frames }{ \sstdescription{ 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 \htmlref{Frame}{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. } \sstsynopsis{ void astMatchAxes( AstFrame $*$frm1, AstFrame $*$frm2, int $*$axes ) } \sstparameters{ \sstsubsection{ frm1 }{ Pointer to the first Frame. } \sstsubsection{ frm2 }{ Pointer to the second Frame. } \sstsubsection{ 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. \htmlref{Axis}{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. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. } } \sstnotes{ \sstitemlist{ \sstitem Corresponding axes are identified by the fact that a \htmlref{Mapping}{Mapping} can be found between them using \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}. Thus, \texttt{"} corresponding axes\texttt{"} are not necessarily identical. For instance, \htmlref{SkyFrame}{SkyFrame} axes in two Frames will match even if they describe different celestial coordinate systems } } } \sstroutine{ astMathMap }{ Create a MathMap }{ \sstdescription{ This function creates a new \htmlref{MathMap}{MathMap} and optionally initialises its attributes. A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs. } \sstsynopsis{ AstMathMap $*$astMathMap( int nin, int nout, int nfwd, const char $*$fwd[], int ninv, const char $*$inv[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nin }{ Number of input variables for the MathMap. This determines the value of its \htmlref{Nin}{Nin} attribute. } \sstsubsection{ nout }{ Number of output variables for the MathMap. This determines the value of its \htmlref{Nout}{Nout} attribute. } \sstsubsection{ nfwd }{ The number of forward transformation functions being supplied. This must be at least equal to \texttt{"} nout\texttt{"} , but may be increased to accommodate any additional expressions which define intermediate variables for the forward transformation (see the \texttt{"} Calculating Intermediate Values\texttt{"} section below). } \sstsubsection{ fwd }{ An array (with \texttt{"} nfwd\texttt{"} elements) of pointers to null terminated strings which contain the expressions defining the forward transformation. The syntax of these expressions is described below. } \sstsubsection{ ninv }{ The number of inverse transformation functions being supplied. This must be at least equal to \texttt{"} nin\texttt{"} , but may be increased to accommodate any additional expressions which define intermediate variables for the inverse transformation (see the \texttt{"} Calculating Intermediate Values\texttt{"} section below). } \sstsubsection{ inv }{ An array (with \texttt{"} ninv\texttt{"} elements) of pointers to null terminated strings which contain the expressions defining the inverse transformation. The syntax of these expressions is described below. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new MathMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astMathMap() }{ A pointer to the new MathMap. } } \sstnotes{ \sstitemlist{ \sstitem The sequence of numbers produced by the random number functions available within a MathMap is normally unpredictable and different for each MathMap. However, this behaviour may be controlled by means of the MathMap\texttt{'} s \htmlref{Seed}{Seed} attribute. \sstitem Normally, compound Mappings (CmpMaps) which involve MathMaps will not be subject to simplification (e.g. using \htmlref{astSimplify}{astSimplify}) because AST cannot know how different MathMaps will interact. However, in the special case where a MathMap occurs in series with its own inverse, then simplification may be possible. Whether simplification does, in fact, occur under these circumstances is controlled by the MathMap\texttt{'} s \htmlref{SimpFI}{SimpFI} and \htmlref{SimpIF}{SimpIF} attributes. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Defining Transformation Functions }{ A MathMap\texttt{'} s transformation functions are supplied as a set of expressions in an array of character strings. Normally you would supply the same number of expressions for the forward transformation, via the \texttt{"} fwd\texttt{"} parameter, as there are output variables (given by the MathMap\texttt{'} s Nout attribute). For instance, if Nout is 2 you might use: \sstitemlist{ \sstitem \texttt{"} r = sqrt( x $*$ x $+$ y $*$ y )\texttt{"} \sstitem \texttt{"} theta = atan2( y, x )\texttt{"} } which defines a transformation from Cartesian to polar coordinates. Here, the variables that appear on the left of each expression (\texttt{"} r\texttt{"} and \texttt{"} theta\texttt{"} ) provide names for the output variables and those that appear on the right (\texttt{"} x\texttt{"} and \texttt{"} y\texttt{"} ) are references to input variables. To complement this, you must also supply expressions for the inverse transformation via the \texttt{"} inv\texttt{"} parameter. In this case, the number of expressions given would normally match the number of MathMap input coordinates (given by the Nin attribute). If Nin is 2, you might use: \sstitemlist{ \sstitem \texttt{"} x = r $*$ cos( theta )\texttt{"} \sstitem \texttt{"} y = r $*$ sin( theta )\texttt{"} } which expresses the transformation from polar to Cartesian coordinates. Note that here the input variables (\texttt{"} x\texttt{"} and \texttt{"} y\texttt{"} ) are named on the left of each expression, and the output variables (\texttt{"} r\texttt{"} and \texttt{"} theta\texttt{"} ) are referenced on the right. Normally, you cannot refer to a variable on the right of an expression unless it is named on the left of an expression in the complementary set of functions. Therefore both sets of functions (forward and inverse) must be formulated using the same consistent set of variable names. This means that if you wish to leave one of the transformations undefined, you must supply dummy expressions which simply name each of the output (or input) variables. For example, you might use: \sstitemlist{ \sstitem \texttt{"} x\texttt{"} \sstitem \texttt{"} y\texttt{"} } for the inverse transformation above, which serves to name the input variables but without defining an inverse transformation. } \sstdiytopic{ Calculating Intermediate Values }{ It is sometimes useful to calculate intermediate values and then to use these in the final expressions for the output (or input) variables. This may be done by supplying additional expressions for the forward (or inverse) transformation functions. For instance, the following array of five expressions describes 2-dimensional pin-cushion distortion: \sstitemlist{ \sstitem \texttt{"} r = sqrt( xin $*$ xin $+$ yin $*$ yin )\texttt{"} \sstitem \texttt{"} rout = r $*$ ( 1 $+$ 0.1 $*$ r $*$ r )\texttt{"} \sstitem \texttt{"} theta = atan2( yin, xin )\texttt{"} \sstitem \texttt{"} xout = rout $*$ cos( theta )\texttt{"} \sstitem \texttt{"} yout = rout $*$ sin( theta )\texttt{"} } Here, we first calculate three intermediate results (\texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"} and \texttt{"} theta\texttt{"} ) and then use these to calculate the final results (\texttt{"} xout\texttt{"} and \texttt{"} yout\texttt{"} ). The MathMap knows that only the final two results constitute values for the output variables because its Nout attribute is set to 2. You may define as many intermediate variables in this way as you choose. Having defined a variable, you may then refer to it on the right of any subsequent expressions. Note that when defining the inverse transformation you may only refer to the output variables \texttt{"} xout\texttt{"} and \texttt{"} yout\texttt{"} . The intermediate variables \texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"} and \texttt{"} theta\texttt{"} (above) are private to the forward transformation and may not be referenced by the inverse transformation. The inverse transformation may, however, define its own private intermediate variables. } \sstdiytopic{ Expression Syntax }{ The expressions given for the forward and inverse transformations closely follow the syntax of the C programming language (with some extensions for compatibility with Fortran). They may contain references to variables and literal constants, together with arithmetic, boolean, relational and bitwise operators, and function invocations. A set of symbolic constants is also available. Each of these is described in detail below. Parentheses may be used to over-ride the normal order of evaluation. There is no built-in limit to the length of expressions and they are insensitive to case or the presence of additional white space. } \sstdiytopic{ Variables }{ Variable names must begin with an alphabetic character and may contain only alphabetic characters, digits, and the underscore character \texttt{"} \_\texttt{"} . There is no built-in limit to the length of variable names. } \sstdiytopic{ Literal Constants }{ Literal constants, such as \texttt{"} 0\texttt{"} , \texttt{"} 1\texttt{"} , \texttt{"} 0.007\texttt{"} or \texttt{"} 2.505e-16\texttt{"} may appear in expressions, with the decimal point and exponent being optional (a \texttt{"} D\texttt{"} may also be used as an exponent character for compatibility with Fortran). A unary minus \texttt{"} -\texttt{"} may be used as a prefix. } \sstdiytopic{ Arithmetic Precision }{ All arithmetic is floating point, performed in double precision. } \sstdiytopic{ Propagation of Missing Data }{ Unless indicated otherwise, if any argument of a function or operator has the value AST\_\_BAD (indicating missing data), then the result of that function or operation is also AST\_\_BAD, so that such values are propagated automatically through all operations performed by MathMap transformations. The special value AST\_\_BAD can be represented in expressions by the symbolic constant \texttt{"} $<$bad$>$\texttt{"} . A $<$bad$>$ result (i.e. equal to AST\_\_BAD) is also produced in response to any numerical error (such as division by zero or numerical overflow), or if an invalid argument value is provided to a function or operator. } \sstdiytopic{ Arithmetic Operators }{ The following arithmetic operators are available: \sstitemlist{ \sstitem x1 $+$ x2: Sum of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . \sstitem x1 - x2: Difference of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . \sstitem x1 $*$ x2: Product of \texttt{"} x1\texttt{"} and \texttt{"} x1\texttt{"} . \sstitem x1 / x2: Ratio of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . \sstitem x1 $*$$*$ x2: \texttt{"} x1\texttt{"} raised to the power of \texttt{"} x2\texttt{"} . \sstitem $+$ x: Unary plus, has no effect on its argument. \sstitem - x: Unary minus, negates its argument. } } \sstdiytopic{ Boolean Operators }{ Boolean values are represented using zero to indicate false and non-zero to indicate true. In addition, the value AST\_\_BAD is taken to mean \texttt{"} unknown\texttt{"} . The values returned by boolean operators may therefore be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"} logic is implemented. For example, \texttt{"} a$|$$|$b\texttt{"} may evaluate to 1 if \texttt{"} a\texttt{"} is non-zero, even if \texttt{"} b\texttt{"} has the value AST\_\_BAD. This is because the result of the operation would not be affected by the value of \texttt{"} b\texttt{"} , so long as \texttt{"} a\texttt{"} is non-zero. The following boolean operators are available: \sstitemlist{ \sstitem x1 \&\& x2: Boolean AND between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning 1 if both \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym \texttt{"} .and.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $|$$|$ x2: Boolean OR between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning 1 if either \texttt{"} x1\texttt{"} or \texttt{"} x2\texttt{"} are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym \texttt{"} .or.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $\wedge$$\wedge$ x2: Boolean exclusive OR (XOR) between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning 1 if exactly one of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} is non-zero, and 0 otherwise. Tri-state logic is not used with this operator. (The synonyms \texttt{"} .neqv.\texttt{"} and \texttt{"} .xor.\texttt{"} are also provided for compatibility with Fortran, although the second of these is not standard.) \sstitem x1 .eqv. x2: This is provided only for compatibility with Fortran and tests whether the boolean states of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} (i.e. true/false) are equal. It is the negative of the exclusive OR (XOR) function. Tri-state logic is not used with this operator. \sstitem ! x: Boolean unary NOT operation, returning 1 if \texttt{"} x\texttt{"} is zero, and 0 otherwise. (The synonym \texttt{"} .not.\texttt{"} is also provided for compatibility with Fortran.) } } \sstdiytopic{ Relational Operators }{ Relational operators return the boolean result (0 or 1) of comparing the values of two floating point values for equality or inequality. The value AST\_\_BAD may also be returned if either argument is $<$bad$>$. The following relational operators are available: \sstitemlist{ \sstitem x1 == x2: Tests whether \texttt{"} x1\texttt{"} equals \texttt{"} x1\texttt{"} . (The synonym \texttt{"} .eq.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 != x2: Tests whether \texttt{"} x1\texttt{"} is unequal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .ne.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $>$ x2: Tests whether \texttt{"} x1\texttt{"} is greater than \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .gt.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $>$= x2: Tests whether \texttt{"} x1\texttt{"} is greater than or equal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .ge.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $<$ x2: Tests whether \texttt{"} x1\texttt{"} is less than \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .lt.\texttt{"} is also provided for compatibility with Fortran.) \sstitem x1 $<$= x2: Tests whether \texttt{"} x1\texttt{"} is less than or equal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .le.\texttt{"} is also provided for compatibility with Fortran.) } Note that relational operators cannot usefully be used to compare values with the $<$bad$>$ value (representing missing data), because the result is always $<$bad$>$. The isbad() function should be used instead. } \sstdiytopic{ Bitwise Operators }{ The bitwise operators provided by C are often useful when operating on raw data (e.g. from instruments), so they are also provided for use in MathMap expressions. In this case, however, the values on which they operate are floating point values rather than pure integers. In order to produce results which match the pure integer case, the operands are regarded as fixed point binary numbers (i.e. with the binary equivalent of a decimal point) with negative numbers represented using twos-complement notation. For integer values, the resulting bit pattern corresponds to that of the equivalent signed integer (digits to the right of the point being zero). Operations on the bits representing the fractional part are also possible, however. The following bitwise operators are available: \sstitemlist{ \sstitem x1 $>$$>$ x2: Rightward bit shift. The integer value of \texttt{"} x2\texttt{"} is taken (rounding towards zero) and the bits representing \texttt{"} x1\texttt{"} are then shifted this number of places to the right (or to the left if the number of places is negative). This is equivalent to dividing \texttt{"} x1\texttt{"} by the corresponding power of 2. \sstitem x1 $<$$<$ x2: Leftward bit shift. The integer value of \texttt{"} x2\texttt{"} is taken (rounding towards zero), and the bits representing \texttt{"} x1\texttt{"} are then shifted this number of places to the left (or to the right if the number of places is negative). This is equivalent to multiplying \texttt{"} x1\texttt{"} by the corresponding power of 2. \sstitem x1 \& x2: Bitwise AND between the bits of \texttt{"} x1\texttt{"} and those of \texttt{"} x2\texttt{"} (equivalent to a boolean AND applied at each bit position in turn). \sstitem x1 $|$ x2: Bitwise OR between the bits of \texttt{"} x1\texttt{"} and those of \texttt{"} x2\texttt{"} (equivalent to a boolean OR applied at each bit position in turn). \sstitem x1 $\wedge$ x2: Bitwise exclusive OR (XOR) between the bits of \texttt{"} x1\texttt{"} and those of \texttt{"} x2\texttt{"} (equivalent to a boolean XOR applied at each bit position in turn). } Note that no bit inversion operator (\texttt{"} $\sim$\texttt{"} in C) is provided. This is because inverting the bits of a twos-complement fixed point binary number is equivalent to simply negating it. This differs from the pure integer case because bits to the right of the binary point are also inverted. To invert only those bits to the left of the binary point, use a bitwise exclusive OR with the value -1 (i.e. \texttt{"} x$\wedge$-1\texttt{"} ). } \sstdiytopic{ Functions }{ The following functions are available: \sstitemlist{ \sstitem abs(x): Absolute value of \texttt{"} x\texttt{"} (sign removal), same as fabs(x). \sstitem acos(x): Inverse cosine of \texttt{"} x\texttt{"} , in radians. \sstitem acosd(x): Inverse cosine of \texttt{"} x\texttt{"} , in degrees. \sstitem acosh(x): Inverse hyperbolic cosine of \texttt{"} x\texttt{"} . \sstitem acoth(x): Inverse hyperbolic cotangent of \texttt{"} x\texttt{"} . \sstitem acsch(x): Inverse hyperbolic cosecant of \texttt{"} x\texttt{"} . \sstitem aint(x): Integer part of \texttt{"} x\texttt{"} (round towards zero), same as int(x). \sstitem asech(x): Inverse hyperbolic secant of \texttt{"} x\texttt{"} . \sstitem asin(x): Inverse sine of \texttt{"} x\texttt{"} , in radians. \sstitem asind(x): Inverse sine of \texttt{"} x\texttt{"} , in degrees. \sstitem asinh(x): Inverse hyperbolic sine of \texttt{"} x\texttt{"} . \sstitem atan(x): Inverse tangent of \texttt{"} x\texttt{"} , in radians. \sstitem atand(x): Inverse tangent of \texttt{"} x\texttt{"} , in degrees. \sstitem atanh(x): Inverse hyperbolic tangent of \texttt{"} x\texttt{"} . \sstitem atan2(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in radians. \sstitem atan2d(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in degrees. \sstitem ceil(x): Smallest integer value not less then \texttt{"} x\texttt{"} (round towards plus infinity). \sstitem cos(x): Cosine of \texttt{"} x\texttt{"} in radians. \sstitem cosd(x): Cosine of \texttt{"} x\texttt{"} in degrees. \sstitem cosh(x): Hyperbolic cosine of \texttt{"} x\texttt{"} . \sstitem coth(x): Hyperbolic cotangent of \texttt{"} x\texttt{"} . \sstitem csch(x): Hyperbolic cosecant of \texttt{"} x\texttt{"} . \sstitem dim(x1, x2): Returns \texttt{"} x1-x2\texttt{"} if \texttt{"} x1\texttt{"} is greater than \texttt{"} x2\texttt{"} , otherwise 0. \sstitem exp(x): Exponential function of \texttt{"} x\texttt{"} . \sstitem fabs(x): Absolute value of \texttt{"} x\texttt{"} (sign removal), same as abs(x). \sstitem floor(x): Largest integer not greater than \texttt{"} x\texttt{"} (round towards minus infinity). \sstitem fmod(x1, x2): Remainder when \texttt{"} x1\texttt{"} is divided by \texttt{"} x2\texttt{"} , same as mod(x1, x2). \sstitem gauss(x1, x2): Random sample from a Gaussian distribution with mean \texttt{"} x1\texttt{"} and standard deviation \texttt{"} x2\texttt{"} . \sstitem int(x): Integer part of \texttt{"} x\texttt{"} (round towards zero), same as aint(x). \sstitem isbad(x): Returns 1 if \texttt{"} x\texttt{"} has the $<$bad$>$ value (AST\_\_BAD), otherwise 0. \sstitem log(x): Natural logarithm of \texttt{"} x\texttt{"} . \sstitem log10(x): Logarithm of \texttt{"} x\texttt{"} to base 10. \sstitem max(x1, x2, ...): Maximum of two or more values. \sstitem min(x1, x2, ...): Minimum of two or more values. \sstitem mod(x1, x2): Remainder when \texttt{"} x1\texttt{"} is divided by \texttt{"} x2\texttt{"} , same as fmod(x1, x2). \sstitem nint(x): Nearest integer to \texttt{"} x\texttt{"} (round to nearest). \sstitem poisson(x): Random integer-valued sample from a Poisson distribution with mean \texttt{"} x\texttt{"} . \sstitem pow(x1, x2): \texttt{"} x1\texttt{"} raised to the power of \texttt{"} x2\texttt{"} . \sstitem qif(x1, x2, x3): Returns \texttt{"} x2\texttt{"} if \texttt{"} x1\texttt{"} is true, and \texttt{"} x3\texttt{"} otherwise. \sstitem rand(x1, x2): Random sample from a uniform distribution in the range \texttt{"} x1\texttt{"} to \texttt{"} x2\texttt{"} inclusive. \sstitem sech(x): Hyperbolic secant of \texttt{"} x\texttt{"} . \sstitem sign(x1, x2): Absolute value of \texttt{"} x1\texttt{"} with the sign of \texttt{"} x2\texttt{"} (transfer of sign). \sstitem sin(x): Sine of \texttt{"} x\texttt{"} in radians. \sstitem sinc(x): Sinc function of \texttt{"} x\texttt{"} [= \texttt{"} sin(x)/x\texttt{"} ]. \sstitem sind(x): Sine of \texttt{"} x\texttt{"} in degrees. \sstitem sinh(x): Hyperbolic sine of \texttt{"} x\texttt{"} . \sstitem sqr(x): Square of \texttt{"} x\texttt{"} (= \texttt{"} x$*$x\texttt{"} ). \sstitem sqrt(x): Square root of \texttt{"} x\texttt{"} . \sstitem tan(x): Tangent of \texttt{"} x\texttt{"} in radians. \sstitem tand(x): Tangent of \texttt{"} x\texttt{"} in degrees. \sstitem tanh(x): Hyperbolic tangent of \texttt{"} x\texttt{"} . } } \sstdiytopic{ Symbolic Constants }{ The following symbolic constants are available (the enclosing \texttt{"} $<$$>$\texttt{"} brackets must be included): \sstitemlist{ \sstitem $<$bad$>$: The \texttt{"} bad\texttt{"} value (AST\_\_BAD) used to flag missing data. Note that you cannot usefully compare values with this constant because the result is always $<$bad$>$. The isbad() function should be used instead. \sstitem $<$dig$>$: Number of decimal digits of precision available in a floating point (double) value. \sstitem $<$e$>$: \htmlref{Base}{Base} of natural logarithms. \sstitem $<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is distinguishable from unity. \sstitem $<$mant\_dig$>$: The number of base $<$radix$>$ digits stored in the mantissa of a floating point (double) value. \sstitem $<$max$>$: Maximum representable floating point (double) value. \sstitem $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power can be represented as a floating point (double) value. \sstitem $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that power minus 1 can be represented as a floating point (double) value. \sstitem $<$min$>$: Smallest positive number which can be represented as a normalised floating point (double) value. \sstitem $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double) value. \sstitem $<$min\_exp$>$: Minimum negative integer such that $<$radix$>$ raised to that power minus 1 can be represented as a normalised floating point (double) value. \sstitem $<$pi$>$: Ratio of the circumference of a circle to its diameter. \sstitem $<$radix$>$: The radix (number base) used to represent the mantissa of floating point (double) values. \sstitem $<$rounds$>$: The mode used for rounding floating point results after addition. Possible values include: -1 (indeterminate), 0 (toward zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus infinity). Other values indicate machine-dependent behaviour. } } \sstdiytopic{ Evaluation Precedence and Associativity }{ Items appearing in expressions are evaluated in the following order (highest precedence first): \sstitemlist{ \sstitem Constants and variables \sstitem Function arguments and parenthesised expressions \sstitem Function invocations \sstitem Unary $+$ - ! .not. \sstitem $*$$*$ \sstitem $*$ / \sstitem $+$ - \sstitem $<$$<$ $>$$>$ \sstitem $<$ .lt. $<$= .le. $>$ .gt. $>$= .ge. \sstitem == .eq. != .ne. \sstitem \& \sstitem $\wedge$ \sstitem $|$ \sstitem \&\& .and. \sstitem $\wedge$$\wedge$ \sstitem $|$$|$ .or \sstitem .eqv. .neqv. .xor. } All operators associate from left-to-right, except for unary $+$, unary -, !, .not. and $*$$*$ which associate from right-to-left. } } \sstroutine{ astMatrixMap }{ Create a MatrixMap }{ \sstdescription{ This function creates a new \htmlref{MatrixMap}{MatrixMap} and optionally initialises its attributes. A MatrixMap is a form of \htmlref{Mapping}{Mapping} which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed. } \sstsynopsis{ AstMatrixMap $*$astMatrixMap( int nin, int nout, int form, const double matrix[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nin }{ The number of input coordinates, which determines the number of columns in the matrix. } \sstsubsection{ nout }{ The number of output coordinates, which determines the number of rows in the matrix. } \sstsubsection{ form }{ An integer which indicates the form in which the matrix elements will be supplied. A value of zero indicates that a full \texttt{"} nout\texttt{"} x \texttt{"} nin\texttt{"} matrix of values will be supplied via the \texttt{"} matrix\texttt{"} parameter (below). In this case, the elements should be given in row order (the elements of the first row, followed by the elements of the second row, etc.). A value of 1 indicates that only the diagonal elements of the matrix will be supplied, and that all others should be zero. In this case, the elements of \texttt{"} matrix\texttt{"} should contain only the diagonal elements, stored consecutively. A value of 2 indicates that a \texttt{"} unit\texttt{"} matrix is required, whose diagonal elements are set to unity (with all other elements zero). In this case, the \texttt{"} matrix\texttt{"} parameter is ignored and a NULL pointer may be supplied. } \sstsubsection{ matrix }{ The array of matrix elements to be used, stored according to the value of \texttt{"} form\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new MatrixMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astMatrixMap() }{ A pointer to the new MatrixMap. } } \sstnotes{ \sstitemlist{ \sstitem In general, a MatrixMap\texttt{'} s forward transformation will always be available (as indicated by its \htmlref{TranForward}{TranForward} attribute), but its inverse transformation (\htmlref{TranInverse}{TranInverse} attribute) will only be available if the associated matrix is square and non-singular. \sstitem As an exception to this, the inverse transformation is always available if a unit or diagonal matrix is specified. In this case, if the matrix is not square, one or more of the input coordinate values may not be recoverable from a set of output coordinates. Any coordinates affected in this way will simply be set to the value zero. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astMirrorVariants }{ Make the current Frame mirror the variant Mappings in another Frame }{ \sstdescription{ This function indicates that all access to the \htmlref{Variant}{Variant} attribute of the current \htmlref{Frame}{Frame} should should be forwarded to some other nominated Frame in the \htmlref{FrameSet}{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 \htmlref{Mapping}{Mapping} using either the pre-existing Frame or the new Frame. } \sstsynopsis{ void astMirrorVariants( AstFrameSet $*$this, int iframe, int $*$status ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe }{ 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 \htmlref{Nframe}{Nframe} attribute). If AST\_\_NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this function is disabled. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to the \htmlref{astAddVariant}{astAddVariant} function will cause an error to be reported if the current Frame is mirroring another Frame. \sstitem A value of AST\_\_BASE may be given for the \texttt{"} iframe\texttt{"} parameter to specify the base Frame. \sstitem Any variant Mappings explicitly added to the current Frame using astAddVariant will be ignored if the current Frame is mirroring another Frame. } } } \sstroutine{ astNegate }{ Negate the area represented by a Region }{ \sstdescription{ This function negates the area represented by a \htmlref{Region}{Region}. That is, points which were previously inside the region will then be outside, and points which were outside will be inside. This is acomplished by toggling the state of the \htmlref{Negated}{Negated} attribute for the supplied region. } \sstsynopsis{ void astNegate( AstRegion $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } } } \sstroutine{ astNorm }{ Normalise a set of Frame coordinates }{ \sstdescription{ This function normalises a set of \htmlref{Frame}{Frame} coordinate values which might be unsuitable for display (e.g. may lie outside the expected range) into a set of acceptable values suitable for display. } \sstsynopsis{ void astNorm( AstFrame $*$this, double value[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ value }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). Initially, this should contain a set of coordinate values representing a point in the space which the Frame describes. If these values lie outside the expected range for the Frame, they will be replaced with more acceptable (normalised) values. Otherwise, they will be returned unchanged. } } \sstnotes{ \sstitemlist{ \sstitem For some classes of Frame, whose coordinate values are not constrained, this function will never modify the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as zero to 2$*$pi. \sstitem The \htmlref{NormMap}{NormMap} class is a \htmlref{Mapping}{Mapping} which can be used to normalise a set of points using the astNorm function of a specified Frame. \sstitem It is intended to be possible to put any set of coordinates into a form suitable for display by using this function to normalise them, followed by appropriate formatting (using \htmlref{astFormat}{astFormat}). } } } \sstroutine{ astNormMap }{ Create a NormMap }{ \sstdescription{ This function creates a new \htmlref{NormMap}{NormMap} and optionally initialises its attributes. A NormMap is a \htmlref{Mapping}{Mapping} which normalises coordinate values using the \htmlref{astNorm}{astNorm} function of the supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap are both equal to the number of axes in the supplied Frame. The forward and inverse transformation of a NormMap are both defined but are identical (that is, they do not form a real inverse pair in that the inverse transformation does not undo the normalisation, instead it reapplies it). However, the \htmlref{astSimplify}{astSimplify} function will replace neighbouring pairs of forward and inverse NormMaps by a single \htmlref{UnitMap}{UnitMap}. } \sstsynopsis{ AstNormMap $*$astNormMap( AstFrame $*$frame, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame which is to be used to normalise the supplied axis values. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new NormMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astNormMap() }{ A pointer to the new NormMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astNullRegion }{ Create a NullRegion }{ \sstdescription{ This function creates a new \htmlref{NullRegion}{NullRegion} and optionally initialises its attributes. A NullRegion is a \htmlref{Region}{Region} with no bounds. If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion represents a Region containing no points. If the Negated attribute of a NullRegion is true, the NullRegion represents an infinite Region containing all points within the coordinate system. } \sstsynopsis{ AstNullRegion $*$astNullRegion( AstFrame $*$frame, AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the \htmlref{Frame}{Frame} in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with positions in the supplied Frame. The uncertainty in any point in the Frame is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created NullRegion. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty of zero is used. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new NullRegion. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astNullRegion() }{ A pointer to the new NullRegion. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astOK }{ Test whether AST functions have been successful }{ \sstdescription{ This macro returns a boolean value (0 or 1) to indicate if preceding AST functions have completed successfully (i.e. without setting the AST error status). If the error status is set to an error value, a value of zero is returned, otherwise the result is one. } \sstsynopsis{ int astOK } \sstreturnedvalue{ \sstsubsection{ astOK }{ One if the AST error status is OK, otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use \htmlref{astClearStatus}{astClearStatus}. } } } \sstroutine{ astOffset }{ Calculate an offset along a geodesic curve }{ \sstdescription{ This function finds the \htmlref{Frame}{Frame} coordinate values of a point which is offset a specified distance along the geodesic curve between two other points. For example, in a basic Frame, this offset will be along the straight line joining two points. For a more specialised Frame describing a sky coordinate system, however, it would be along the great circle passing through two sky positions. } \sstsynopsis{ void astOffset( AstFrame $*$this, const double point1[], const double point2[], double offset, double point3[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ point1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the point marking the start of the geodesic curve. } \sstsubsection{ point2 }{ An array of double, with one element for each Frame axis This should contain the coordinates of the point marking the end of the geodesic curve. } \sstsubsection{ 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. } \sstsubsection{ point3 }{ An array of double, with one element for each Frame axis in which the coordinates of the required point will be returned. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this function is the path of shortest distance between two points, as defined by the \htmlref{astDistance}{astDistance} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value. \sstitem \texttt{"} Bad\texttt{"} 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. } } } \sstroutine{ astOffset2 }{ Calculate an offset along a geodesic curve in a 2D Frame }{ \sstdescription{ This function finds the \htmlref{Frame}{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. } \sstsynopsis{ double astOffset2( AstFrame $*$this, const double point1[2], double angle, double offset, double point2[2] ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ point1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the point marking the start of the geodesic curve. } \sstsubsection{ 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. } \sstsubsection{ 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. } \sstsubsection{ point2 }{ An array of double, with one element for each Frame axis in which the coordinates of the required point will be returned. } } \sstreturnedvalue{ \sstsubsection{ astOffset2 }{ 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. } } \sstnotes{ \sstitemlist{ \sstitem The geodesic curve used by this function is the path of shortest distance between two points, as defined by the \htmlref{astDistance}{astDistance} function. \sstitem An error will be reported if the Frame is not 2-dimensional. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value. } } } \sstroutine{ astOutline$<$X$>$ }{ Create a new Polygon outling values in a 2D data grid }{ \sstdescription{ This is a set of functions that create a \htmlref{Polygon}{Polygon} enclosing a single contiguous set of pixels that have a specified value within a gridded 2-dimensional data array (e.g. an image). A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter \texttt{"} starpix\texttt{"} . The \texttt{"} maxerr\texttt{"} and \texttt{"} maxvert\texttt{"} parameters can be used to control how accurately the returned Polygon represents the required region in the data array. The number of vertices in the returned Polygon will be the minimum needed to achieve the required accuracy. You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astOutline$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are procesing data with type \texttt{"} float\texttt{"} , you should use the function astOutlineF (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). } \sstsynopsis{ AstPolygon $*$astOutline$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], const int lbnd[2], const int ubnd[2], double maxerr, int maxvert, const int inside[2], int starpix ) } \sstparameters{ \sstsubsection{ value }{ A data value that specifies the pixels to be outlined. } \sstsubsection{ oper }{ Indicates how the \texttt{"} value\texttt{"} parameter is used to select the outlined pixels. It can have any of the following values: \sstitemlist{ \sstitem AST\_\_LT: outline pixels with value less than \texttt{"} value\texttt{"} . \sstitem AST\_\_LE: outline pixels with value less than or equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_EQ: outline pixels with value equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_NE: outline pixels with value not equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_GE: outline pixels with value greater than or equal to \texttt{"} value\texttt{"} . \sstitem AST\_\_GT: outline pixels with value greater than \texttt{"} value\texttt{"} . } } \sstsubsection{ array }{ Pointer to a 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astOutlineF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ lbnd }{ Pointer to an array of two integers containing the pixel index of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd }{ Pointer to an array of two integers containing the pixel index of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and size of the input pixel grid, its extent along a particular (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 pixels. For FITS images, the lbnd values will be 1 and the ubnd values will be equal to the NAXISi header values. Other data systems, such as the Starlink NDF system, allow an arbitrary pixel origin to be used (i.e. lbnd is not necessarily 1). These bounds also define the input grid\texttt{'} s floating point coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter \texttt{"} starpix\texttt{"} . } \sstsubsection{ maxerr }{ Together with \texttt{"} maxvert\texttt{"} , this determines how accurately the returned Polygon represents the required region of the data array. It gives the target discrepancy between the returned Polygon and the accurate outline in the data array, expressed as a number of pixels. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals \texttt{"} maxvert\texttt{"} , or the largest discrepancy between the accurate outline and the returned Polygon is greater than \texttt{"} maxerr\texttt{"} . If \texttt{"} maxerr\texttt{"} is zero or less, its value is ignored and the returned Polygon will have the number of vertices specified by \texttt{"} maxvert\texttt{"} . } \sstsubsection{ maxvert }{ Together with \texttt{"} maxerr\texttt{"} , this determines how accurately the returned Polygon represents the required region of the data array. It gives the maximum allowed number of vertices in the returned Polygon. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals \texttt{"} maxvert\texttt{"} , or the largest discrepancy between the accurate outline and the returned Polygon is greater than \texttt{"} maxerr\texttt{"} . If \texttt{"} maxvert\texttt{"} is less than 3, its value is ignored and the number of vertices in the returned Polygon will be the minimum needed to ensure that the discrepancy between the accurate outline and the returned Polygon is less than \texttt{"} maxerr\texttt{"} . } \sstsubsection{ inside }{ Pointer to an array of two integers containing the pixel indices of a pixel known to be inside the required region. This is needed because the supplied data array may contain several disjoint areas of pixels that satisfy the criterion specified by \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} . In such cases, the area described by the returned Polygon will be the one that contains the pixel specified by \texttt{"} inside\texttt{"} . If the specified pixel is outside the bounds given by \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} , or has a value that does not meet the criterion specified by \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} , then this function will search for a suitable pixel. The search starts at the central pixel and proceeds in a spiral manner until a pixel is found that meets the specified crierion. } \sstsubsection{ starpix }{ A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If non-zero, the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If zero, the definition of pixel coordinate used by other AST functions such as astResample, astMask, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates). } } \sstreturnedvalue{ \sstsubsection{ astOutline$<$X$>$() }{ A pointer to the required Polygon. } } \sstnotes{ \sstitemlist{ \sstitem This function proceeds by first finding a very accurate polygon, and then removing insignificant vertices from this fine polygon using \htmlref{astDownsize}{astDownsize}. \sstitem The returned Polygon is the outer boundary of the contiguous set of pixels that includes ths specified \texttt{"} inside\texttt{"} point, and satisfy the specified value requirement. This set of pixels may potentially include \texttt{"} holes\texttt{"} where the pixel values fail to meet the specified value requirement. Such holes will be ignored by this function. \sstitem NULL will be returned if this function is invoked with the global error status set, or if it should fail for any reason. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate masking function, you should replace $<$X$>$ in the generic function name astOutline$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem L: long int \sstitem UL: unsigned long int \sstitem I: int \sstitem UI: unsigned int \sstitem S: short int \sstitem US: unsigned short int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astOutlineD would be used to process \texttt{"} double\texttt{"} data, while astOutlineS would be used to process \texttt{"} short int\texttt{"} data, etc. } } \sstroutine{ astOverlap }{ Test if two regions overlap each other }{ \sstdescription{ This function returns an integer value indicating if the two supplied Regions overlap. The two Regions are converted to a commnon coordinate system before performing the check. If this conversion is not possible (for instance because the two Regions represent areas in different domains), then the check cannot be performed and a zero value is returned to indicate this. } \sstsynopsis{ int astOverlap( AstRegion $*$this, AstRegion $*$that ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the first \htmlref{Region}{Region}. } \sstsubsection{ that }{ Pointer to the second Region. } } \sstreturnedvalue{ \sstsubsection{ astOverlap() }{ A value indicating if there is any overlap between the two Regions. Possible values are: 0 - The check could not be performed because the second Region could not be mapped into the coordinate system of the first Region. 1 - There is no overlap between the two Regions. 2 - The first Region is completely inside the second Region. 3 - The second Region is completely inside the first Region. 4 - There is partial overlap between the two Regions. 5 - The Regions are identical to within their uncertainties. 6 - The second Region is the exact negation of the first Region to within their uncertainties. } } \sstnotes{ \sstitemlist{ \sstitem The returned values 5 and 6 do not check the value of the \htmlref{Closed}{Closed} attribute in the two Regions. \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astParameterName }{ Get the name of the global parameter at a given index within the Table }{ \sstdescription{ This function returns a string holding the name of the global parameter with the given index within the \htmlref{Table}{Table}. This function is intended primarily as a means of iterating round all the parameters in a Table. For this purpose, the number of parameters in the Table is given by the \htmlref{Nparameter}{Nparameter} attribute of the Table. This function could then be called in a loop, with the index value going from zero to one less than Nparameter. Note, the index associated with a parameter decreases monotonically with the age of the parameter: the oldest Parameter in the Table will have index one, and the Parameter added most recently to the Table will have the largest index. } \sstsynopsis{ const char $*$astParameterName( AstTable $*$this, int index ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ index }{ The index into the list of parameters. The first parameter has index one, and the last has index \texttt{"} Nparameter\texttt{"} . } } \sstreturnedvalue{ \sstsubsection{ astParameterName() }{ A pointer to a null-terminated string containing the upper case parameter name. } } \sstnotes{ \sstitemlist{ \sstitem The returned pointer is guaranteed to remain valid and the string to which it points will not be over-written for a total of 50 successive invocations of this function. After this, the memory containing the string may be re-used, so a copy of the string should be made if it is needed for longer than this. \sstitem A NULL pointer will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astPcdMap }{ Create a PcdMap }{ \sstdescription{ This function creates a new \htmlref{PcdMap}{PcdMap} and optionally initialises its attributes. A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. This can take the form either of pincushion or barrel distortion, and is characterized by a single distortion coefficient. A PcdMap is specified by giving this distortion coefficient and the coordinates of the centre of the radial distortion. The forward transformation of a PcdMap applies the distortion: RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) where R is the undistorted radial distance from the distortion centre (specified by attribute PcdCen), RD is the radial distance from the same centre in the presence of distortion, and C is the distortion coefficient (given by attribute \htmlref{Disco}{Disco}). The inverse transformation of a PcdMap removes the distortion produced by the forward transformation. The expression used to derive R from RD is an approximate inverse of the expression above, obtained from two iterations of the Newton-Raphson method. The mismatch between the forward and inverse expressions is negligible for astrometric applications (to reach 1 milliarcsec at the edge of the Anglo-Australian Telescope triplet or a Schmidt field would require field diameters of 2.4 and 42 degrees respectively). If a PcdMap is inverted (e.g. using \htmlref{astInvert}{astInvert}) then the roles of the forward and inverse transformations are reversed; the forward transformation will remove the distortion, and the inverse transformation will apply it. } \sstsynopsis{ AstPcdMap $*$astPcdMap( double disco, const double pcdcen[2], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ disco }{ The distortion coefficient. Negative values give barrel distortion, positive values give pincushion distortion, and zero gives no distortion. } \sstsubsection{ pcdcen }{ A 2-element array containing the coordinates of the centre of the distortion. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PcdMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPcdMap() }{ A pointer to the new PcdMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astPermAxes }{ Permute the axis order in a Frame }{ \sstdescription{ This function permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur. } \sstsynopsis{ void astPermAxes( AstFrame $*$this, const int perm[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ perm }{ An array with one element for each axis of the Frame (\htmlref{Naxes}{Naxes} attribute). This should list the axes in their new order, using the original axis numbering (which starts at 1 for the first axis). } } \sstnotes{ \sstitemlist{ \sstitem Only genuine permutations of the axis order are permitted, so each axis must be referenced exactly once in the \texttt{"} perm\texttt{"} array. \sstitem If successive axis permutations are applied to a Frame, then the effects are cumulative. } } } \sstroutine{ astPermMap }{ Create a PermMap }{ \sstdescription{ This function creates a new \htmlref{PermMap}{PermMap} and optionally initialises its attributes. A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output. In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones. } \sstsynopsis{ AstPermMap $*$astPermMap( int nin, const int inperm[], int nout, const int outperm[], double constant[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nin }{ The number of input coordinates. } \sstsubsection{ inperm }{ An optional array with \texttt{"} nin\texttt{"} elements which, for each input coordinate, should contain the number of the output coordinate whose value is to be used (note that this array therefore defines the inverse coordinate transformation). Coordinates are numbered starting from 1. For details of additional special values that may be used in this array, see the description of the \texttt{"} constant\texttt{"} parameter. If a NULL pointer is supplied instead of an array, each input coordinate will obtain its value from the corresponding output coordinate (or will be assigned the value AST\_\_BAD if there is no corresponding output coordinate). } \sstsubsection{ nout }{ The number of output coordinates. } \sstsubsection{ outperm }{ An optional array with \texttt{"} nout\texttt{"} elements which, for each output coordinate, should contain the number of the input coordinate whose value is to be used (note that this array therefore defines the forward coordinate transformation). Coordinates are numbered starting from 1. For details of additional special values that may be used in this array, see the description of the \texttt{"} constant\texttt{"} parameter. If a NULL pointer is supplied instead of an array, each output coordinate will obtain its value from the corresponding input coordinate (or will be assigned the value AST\_\_BAD if there is no corresponding input coordinate). } \sstsubsection{ constant }{ An optional array containing values which may be assigned to input and/or output coordinates instead of deriving them from other coordinate values. If either of the \texttt{"} inperm\texttt{"} or \texttt{"} outperm\texttt{"} arrays contains a negative value, it is used to address this \texttt{"} constant\texttt{"} array (such that -1 addresses the first element, -2 addresses the second element, etc.) and the value obtained is used as the corresponding coordinate value. Care should be taken to ensure that locations lying outside the extent of this array are not accidentally addressed. The array is not used if the \texttt{"} inperm\texttt{"} and \texttt{"} outperm\texttt{"} arrays do not contain negative values. If a NULL pointer is supplied instead of an array, the behaviour is as if the array were of infinite length and filled with the value AST\_\_BAD. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PermMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPermMap() }{ A pointer to the new PermMap. } } \sstnotes{ \sstitemlist{ \sstitem If either of the \texttt{"} inperm\texttt{"} or \texttt{"} outperm\texttt{"} arrays contains a zero value (or a positive value which does not identify a valid output/input coordinate, as appropriate), then the value AST\_\_BAD is assigned as the new coordinate value. \sstitem This function does not attempt to ensure that the forward and inverse transformations performed by the PermMap are self-consistent in any way. You are therefore free to supply coordinate permutation arrays that achieve whatever effect is desired. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astPickAxes }{ Create a new Frame by picking axes from an existing one }{ \sstdescription{ This function creates a new \htmlref{Frame}{Frame} whose axes are copied from an existing Frame along with other Frame attributes, such as its \htmlref{Title}{Title}. Any number (zero or more) of the original Frame\texttt{'} s axes may be copied, in any order, and additional axes with default attributes may also be included in the new Frame. Optionally, a \htmlref{Mapping}{Mapping} that converts between the coordinate systems described by the two Frames will also be returned. } \sstsynopsis{ AstFrame $*$astPickAxes( AstFrame $*$this, int naxes, const int axes[], AstMapping $*$$*$map ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the original Frame. } \sstsubsection{ naxes }{ The number of axes required in the new Frame. } \sstsubsection{ axes }{ An array, with \texttt{"} naxes\texttt{"} elements, which lists the axes to be copied. These should be given in the order required in the new Frame, using the axis numbering in the original Frame (which starts at 1 for the first axis). Axes may be selected in any order, but each may only be used once. If additional (default) axes are also to be included, the corresponding elements of this array should be set to zero. } \sstsubsection{ map }{ Address of a location in which to return a pointer to a new Mapping. This will be a \htmlref{PermMap}{PermMap} (or a \htmlref{UnitMap}{UnitMap} as a special case) that describes the axis permutation that has taken place between the original and new Frames. The Mapping\texttt{'} s forward transformation will convert coordinates from the original Frame into the new one, and vice versa. If this Mapping is not required, a NULL value may be supplied for this parameter. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. The class of Frame returned may differ from that of the original Frame, depending on which axes are selected. For example, if a single axis is picked from a \htmlref{SkyFrame}{SkyFrame} (which must always have two axes) then the resulting Frame cannot be a valid SkyFrame, so will revert to the parent class (Frame) instead. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ Using this function on a FrameSet is identical to using it on the current Frame in the FrameSet. The returned Frame will not be a FrameSet. } \sstsubsection{ \htmlref{Region}{Region} }{ If this function is used on a Region, an attempt is made to retain the bounds information on the selected axes. If succesful, the returned Frame will be a Region of some class. Otherwise, the returned Frame is obtained by calling this function on the Frame represented by the supplied Region (the returned Frame will then not be a Region). In order to be succesful, the selected axes in the Region must be independent of the others. For instance, a \htmlref{Box}{Box} can be split in this way but a \htmlref{Circle}{Circle} cannot. Another requirement for success is that no default axes are added (that is, the \texttt{"} axes\texttt{"} array must not contain any zero values. } } \sstreturnedvalue{ \sstsubsection{ astPickAxes() }{ A pointer to the new Frame. } } \sstnotes{ \sstitemlist{ \sstitem The new Frame will contain a \texttt{"} deep\texttt{"} copy (c.f. \htmlref{astCopy}{astCopy}) of all the data selected from the original Frame. Modifying any aspect of the new Frame will therefore not affect the original one. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astPlot }{ Create a Plot }{ \sstdescription{ This function creates a new \htmlref{Plot}{Plot} and optionally initialises its attributes. A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created. The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect). Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see \htmlref{astCurve}{astCurve}). A Plot also provides facilities for drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with optional coordinate grids (\htmlref{astGrid}{astGrid}). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these functions. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot, using its \htmlref{Current}{Current} attribute. You may also set up clipping (see \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in. Like any FrameSet, a Plot may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a Mapping, a Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST\_\_BAD). } \sstsynopsis{ AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ], const double basebox[ 4 ], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ Pointer to a Frame describing the physical coordinate system in which to plot. A pointer to a FrameSet may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below). If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default 2-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. } \sstsubsection{ graphbox }{ An array giving the position and extent of the plotting area (on the plotting surface of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system. The first pair of values should give the coordinates of the bottom left corner of the plotting area and the second pair should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. } \sstsubsection{ basebox }{ An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting area, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPlot() }{ A pointer to the new Plot. } } \sstnotes{ \sstitemlist{ \sstitem The base Frame of the returned Plot will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot. The choice of base Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a Plot has been created (although you could use this as a way of moving the plotting area around on the plotting surface). \sstitem If a Frame is supplied (via the \texttt{"} frame\texttt{"} pointer), then it becomes the current Frame of the new Plot and is given a Frame index of 2. \sstitem If a FrameSet is supplied (via the \texttt{"} frame\texttt{"} pointer), then all the Frames within this FrameSet become part of the new Plot (where their Frame indices are increased by 1), with the FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot. \sstitem If a null Object pointer (AST\_\_NULL) is supplied (via the \texttt{"} frame\texttt{"} pointer), then the returned Plot will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot \htmlref{Title}{Title} and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates. \sstitem An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 2-dimensional. \sstitem 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. } } } \sstroutine{ astPlot3D }{ Create a Plot3D }{ \sstdescription{ This function creates a new \htmlref{Plot3D}{Plot3D} and optionally initialises its attributes. A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities for producing 3D graphical output. } \sstsynopsis{ AstPlot3D $*$astPlot3D( AstFrame $*$frame, const float graphbox[ 6 ], const double basebox[ 6 ], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ Pointer to a \htmlref{Frame}{Frame} describing the physical coordinate system in which to plot. A pointer to a \htmlref{FrameSet}{FrameSet} may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below). If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default 3-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. } \sstsubsection{ graphbox }{ An array giving the position and extent of the plotting volume (within the plotting space of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system. The first triple of values should give the coordinates of the bottom left corner of the plotting volume and the second triple should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations. } \sstsubsection{ basebox }{ An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting volume, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Plot3D. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPlot3D() }{ A pointer to the new Plot3D. } } \sstnotes{ \sstitemlist{ \sstitem The base Frame of the returned Plot3D will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot3D. The choice of base Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a Plot3D has been created (although you could use this as a way of moving the plotting area around on the plotting surface). \sstitem If a Frame is supplied (via the \texttt{"} frame\texttt{"} pointer), then it becomes the current Frame of the new Plot3D and is given a Frame index of 2. \sstitem If a FrameSet is supplied (via the \texttt{"} frame\texttt{"} pointer), then all the Frames within this FrameSet become part of the new Plot3D (where their Frame indices are increased by 1), with the FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot3D. \sstitem At least one of the three axes of the current Frame must be independent of the other two current Frame axes. \sstitem If a null Object pointer (AST\_\_NULL) is supplied (via the \texttt{"} frame\texttt{"} pointer), then the returned Plot3D will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot3D \htmlref{Title}{Title} and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates. \sstitem An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 3-dimensional. \sstitem 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. } } } \sstroutine{ astPointList }{ Create a PointList }{ \sstdescription{ This function creates a new \htmlref{PointList}{PointList} object and optionally initialises its attributes. A PointList object is a specialised type of \htmlref{Region}{Region} which represents a collection of points in a coordinate \htmlref{Frame}{Frame}. } \sstsynopsis{ AstPointList $*$astPointList( AstFrame $*$frame, int npnt, int ncoord, int dim, const double $*$points, AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region. } \sstsubsection{ npnt }{ The number of points in the Region. } \sstsubsection{ ncoord }{ The number of coordinates being supplied for each point. This must equal the number of axes in the supplied Frame, given by its \htmlref{Naxes}{Naxes} attribute. } \sstsubsection{ dim }{ The number of elements along the second dimension of the \texttt{"} points\texttt{"} array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than \texttt{"} npnt\texttt{"} . } \sstsubsection{ points }{ The address of the first element of a 2-dimensional array of shape \texttt{"} [ncoord][dim]\texttt{"} giving the physical coordinates of the points. These should be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} pnt\texttt{"} is found in element \texttt{"} in[coord][pnt]\texttt{"} . } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with each point in the PointList being created. The uncertainty at any point in the PointList is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the bounding box of the PointList being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PointList. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPointList() }{ A pointer to the new PointList. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astPolyCurve }{ Draw a series of connected geodesic curves }{ \sstdescription{ This function joins a series of points specified in the physical coordinate system of a \htmlref{Plot}{Plot} by drawing a sequence of geodesic curves. It is equivalent to making repeated use of the \htmlref{astCurve}{astCurve} function (q.v.), except that astPolyCurve will generally be more efficient when drawing many geodesic curves end-to-end. A typical application of this might be in drawing contour lines. As with astCurve, full account is taken of the \htmlref{Mapping}{Mapping} between physical and graphical coordinate systems. This includes any discontinuities and clipping established using \htmlref{astClip}{astClip}. } \sstsynopsis{ void astPolyCurve( AstPlot $*$this, int npoint, int ncoord, int indim, const double $*$in ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ npoint }{ The number of points between which geodesic curves are to be drawn. } \sstsubsection{ ncoord }{ The number of coordinates being supplied for each point (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given by its \htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ indim }{ The number of elements along the second dimension of the \texttt{"} in\texttt{"} array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than \texttt{"} npoint\texttt{"} . } \sstsubsection{ in }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [ncoord][indim]\texttt{"} giving the physical coordinates of the points which are to be joined in sequence by geodesic curves. These should be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} point\texttt{"} is found in element \texttt{"} in[coord][point]\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem No curve is drawn on either side of any point which has any coordinate equal to the value AST\_\_BAD. \sstitem An error results if the base Frame of the Plot is not 2-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astPolyMap }{ Create a PolyMap }{ \sstdescription{ This function creates a new \htmlref{PolyMap}{PolyMap} and optionally initialises its attributes. A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, an iterative method can be used to evaluate the inverse based only on the forward transformation. } \sstsynopsis{ AstPolyMap $*$astPolyMap( int nin, int nout, int ncoeff\_f, const double coeff\_f[], int ncoeff\_i, const double coeff\_i[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nin }{ The number of input coordinates. } \sstsubsection{ nout }{ The number of output coordinates. } \sstsubsection{ ncoeff\_f }{ The number of non-zero coefficients necessary to define the forward transformation of the PolyMap. If zero is supplied, the forward transformation will be undefined. } \sstsubsection{ coeff\_f }{ An array containing \texttt{"} ncoeff\_f$*$( 2 $+$ nin )\texttt{"} elements. Each group of \texttt{"} 2 $+$ nin\texttt{"} adjacent elements describe a single coefficient of the forward transformation. Within each such group, the first element is the coefficient value; the next element is the integer index of the PolyMap output which uses the coefficient within its defining polynomial (the first output has index 1); the remaining elements of the group give the integer powers to use with each input coordinate value (powers must not be negative, and floating point values are rounded to the nearest integer). If \texttt{"} ncoeff\_f\texttt{"} is zero, a NULL pointer may be supplied for \texttt{"} coeff\_f\texttt{"} . For instance, if the PolyMap has 3 inputs and 2 outputs, each group consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"} describes a coefficient with value 1.2 which is used within the definition of output 2. The output value is incremented by the product of the coefficient value, the value of input coordinate 1 raised to the power 1, and the value of input coordinate 2 raised to the power 3. Input coordinate 3 is not used since its power is specified as zero. As another example, the group \texttt{"} (-1.0, 1.0, 0.0, 0.0, 0.0 )\texttt{"} describes adds a constant value -1.0 onto output 1 (it is a constant value since the power for every input axis is given as zero). Each final output coordinate value is the sum of the \texttt{"} ncoeff\_f\texttt{"} terms described by the \texttt{"} ncoeff\_f\texttt{"} groups within the supplied array. } \sstsubsection{ ncoeff\_i }{ The number of non-zero coefficients necessary to define the inverse transformation of the PolyMap. If zero is supplied, the inverse transformation will be undefined. } \sstsubsection{ coeff\_i }{ An array containing \texttt{"} ncoeff\_i$*$( 2 $+$ nout )\texttt{"} elements. Each group of \texttt{"} 2 $+$ nout\texttt{"} adjacent elements describe a single coefficient of the inverse transformation, using the same schame as \texttt{"} coeff\_f\texttt{"} , except that \texttt{"} inputs\texttt{"} and \texttt{"} outputs\texttt{"} are transposed. If \texttt{"} ncoeff\_i\texttt{"} is zero, a NULL pointer may be supplied for \texttt{"} coeff\_i\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new PolyMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPolyMap() }{ A pointer to the new PolyMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astPolyTran }{ Fit a PolyMap inverse or forward transformation }{ \sstdescription{ This function creates a new \htmlref{PolyMap}{PolyMap} which is a copy of the supplied PolyMap, in which a specified transformation (forward or inverse) has been replaced by a new polynomial transformation. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values. This method can only be used on (1-input,1-output) or (2-input,2-output) PolyMaps. The transformation to create is specified by the \texttt{"} forward\texttt{"} parameter. In what follows \texttt{"} X\texttt{"} refers to the inputs of the PolyMap, and \texttt{"} Y\texttt{"} to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials, P\_f or P\_i: Y=P\_f(X) for the forward transformation and X=P\_i(Y) for the inverse transformation. The \texttt{"} forward\texttt{"} parameter specifies the transformation to be replaced. If it is non-zero, a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap\texttt{'} s output space. The coefficients of the required forward polynomial, Y=P\_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P\_f(X). If \texttt{"} forward\texttt{"} is zero (probably the most likely case), a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap\texttt{'} s input space. The coefficients of the required inverse polynomial, X=P\_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P\_i(Y). This fitting process is performed repeatedly with increasing polynomial orders (starting with linear) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than \texttt{"} maxacc\texttt{"} . If it is not, an error is reported. } \sstsynopsis{ AstPolyMap $*$astPolyTran( AstPolyMap $*$this, int forward, double acc, double maxacc, int maxorder, const double $*$lbnd, const double $*$ubnd ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the original \htmlref{Mapping}{Mapping}. } \sstsubsection{ forward }{ If non-zero, the forward PolyMap transformation is replaced. Otherwise the inverse transformation is replaced. } \sstsubsection{ acc }{ The target accuracy, expressed as a geodesic distance within the PolyMap\texttt{'} s input space (if \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). } \sstsubsection{ maxacc }{ The maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap\texttt{'} s input space (if \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). } \sstsubsection{ maxorder }{ The maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial. Note, cross terms with total powers greater than or equal to maxorder are not inlcuded in the fit. So the maximum number of terms in each of the fitted polynomials is maxorder$*$(maxorder$+$1)/2. } \sstsubsection{ lbnd }{ Pointer to an array holding the lower bounds of a rectangular region within the PolyMap\texttt{'} s input space (if \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap\texttt{'} s \htmlref{Nin}{Nin} or \htmlref{Nout}{Nout} attribute, depending on \texttt{"} forward\texttt{"} . } \sstsubsection{ ubnd }{ Pointer to an array holding the upper bounds of a rectangular region within the PolyMap\texttt{'} s input space (if \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap\texttt{'} s Nin or Nout attribute, depending on \texttt{"} forward\texttt{"} . } } \sstreturnedvalue{ \sstsubsection{ astPolyTran() }{ A pointer to the new PolyMap. A NULL pointer will be returned if the fit fails to achieve the accuracy specified by \texttt{"} maxacc\texttt{"} , but no error will be reported. } } \sstnotes{ \sstitemlist{ \sstitem This function can only be used on 1D or 2D PolyMaps which have the same number of inputs and outputs. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astPolygon }{ Create a Polygon }{ \sstdescription{ This function creates a new \htmlref{Polygon}{Polygon} object and optionally initialises its attributes. The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon. Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied). } \sstsynopsis{ AstPolygon $*$astPolygon( AstFrame $*$frame, int npnt, int dim, const double $*$points, AstRegion $*$unc, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame }{ A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the \htmlref{Region}{Region}. } \sstsubsection{ npnt }{ The number of points in the Region. } \sstsubsection{ dim }{ The number of elements along the second dimension of the \texttt{"} points\texttt{"} array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than \texttt{"} npnt\texttt{"} . } \sstsubsection{ points }{ The address of the first element of a 2-dimensional array of shape \texttt{"} [2][dim]\texttt{"} giving the physical coordinates of the vertices. These should be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} pnt\texttt{"} is found in element \texttt{"} in[coord][pnt]\texttt{"} . } \sstsubsection{ unc }{ An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Polygon being created. The uncertainty in any point on the boundary of the Polygon is found by shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Polygon. Alternatively, a NULL \htmlref{Object}{Object} pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Polygon being created. The uncertainty Region has two uses: 1) when the \htmlref{astOverlap}{astOverlap} function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using \htmlref{astSimplify}{astSimplify}), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Polygon. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPolygon() }{ A pointer to the new Polygon. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astPrism }{ Create a Prism }{ \sstdescription{ This function creates a new \htmlref{Prism}{Prism} and optionally initialises its attributes. A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region into one or more orthogonal dimensions (specified by another Region). If the Region to be extruded has N axes, and the Region defining the extrusion has M axes, then the resulting Prism will have (M$+$N) axes. A point is inside the Prism if the first N axis values correspond to a point inside the Region being extruded, and the remaining M axis values correspond to a point inside the Region defining the extrusion. As an example, a cylinder can be represented by extruding an existing \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the Interval would have a single axis and would specify the upper and lower limits of the cylinder along its length. } \sstsynopsis{ AstPrism $*$astPrism( AstRegion $*$region1, AstRegion $*$region2, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region1 }{ Pointer to the Region to be extruded. } \sstsubsection{ region2 }{ Pointer to the Region defining the extent of the extrusion. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Prism. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astPrism() }{ A pointer to the new Prism. } } \sstnotes{ \sstitemlist{ \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the Prism. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astPurgeRows }{ Remove all empty rows from a table }{ \sstdescription{ This function removes all empty rows from the \htmlref{Table}{Table}, renaming the key associated with each table cell accordingly. } \sstsynopsis{ void astPurgeRows( AstTable $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } } } \sstroutine{ astPurgeWCS }{ Delete all cards in the FitsChan describing WCS information }{ \sstdescription{ This function deletes all cards in a \htmlref{FitsChan}{FitsChan} that relate to any of the recognised WCS encodings. On exit, the current card is the first remaining card in the FitsChan. } \sstsynopsis{ void astPurgeWCS( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } } \sstroutine{ astPutCards }{ Store a set of FITS header cards in a FitsChan }{ \sstdescription{ This function stores a set of FITS header cards in a \htmlref{FitsChan}{FitsChan}. The cards are supplied concatenated together into a single character string. Any existing cards in the FitsChan are removed before the new cards are added. The FitsChan is \texttt{"} re-wound\texttt{"} on exit by clearing its \htmlref{Card}{Card} attribute. This means that a subsequent invocation of \htmlref{astRead}{astRead} can be made immediately without the need to re-wind the FitsChan first. } \sstsynopsis{ void astPutCards( AstFitsChan $*$this, const char $*$cards ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ cards }{ Pointer to a null-terminated character string containing the FITS cards to be stored. Each individual card should occupy 80 characters in this string, and there should be no delimiters, new lines, etc, between adjacent cards. The final card may be less than 80 characters long. This is the format produced by the fits\_hdr2str function in the CFITSIO library. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if the supplied string contains any cards which cannot be interpreted. } } } \sstroutine{ astPutChannelData }{ Store arbitrary data to be passed to a source or sink function }{ \sstdescription{ This function stores a supplied arbitrary pointer in the \htmlref{Channel}{Channel}. When a source or sink function is invoked by the Channel, the invoked function can use the \htmlref{astChannelData}{astChannelData} macro to retrieve the pointer. This provides a thread-safe alternative to passing file descriptors, etc, via global static variables. } \sstsynopsis{ void astPutChannelData( AstChannel $*$this, void $*$data ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Channel. } \sstsubsection{ data }{ A pointer to be made available to the source and sink functions via the astChannelData macro. May be NULL. } } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this function. } } \sstnotes{ \sstitemlist{ \sstitem This routine is not available in the Fortran 77 interface to the AST library. } } } \sstroutine{ astPutColumnData }{ Store new data values for all rows of a column }{ \sstdescription{ This function copies data values from a supplied buffer into a named column. The first element in the buffer becomes the first element in the first row of the column. If the buffer does not completely fill the column, then any trailing rows are filled with null values. } \sstsynopsis{ void astPutColumnData( AstFitsTable $*$this, const char $*$column, int clen, size\_t size, void $*$coldata ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{FitsTable}{FitsTable}. } \sstsubsection{ column }{ The character string holding the name of the column. Trailing spaces are ignored. } \sstsubsection{ clen }{ If the column holds character strings, then this must be set to the length of each fixed length string in the supplied array. This is often determined by the appropriate TFORMn keyword in the binary table header. The supplied value is ignored if the column does not hold character data. } \sstsubsection{ size }{ The size of the \texttt{"} coldata\texttt{"} array, in bytes. This should be an integer multiple of the number of bytes needed to hold the full vector value stored in a single cell of the column. An error is reported if this is not the case. } \sstsubsection{ coldata }{ A pointer to an area of memory holding the data to copy into the column. The values should be stored in row order. If the column holds non-scalar values, the elements of each value should be stored in \texttt{"} Fortran\texttt{"} order. No data type conversion is performed. } } } \sstroutine{ astPutFits }{ Store a FITS header card in a FitsChan }{ \sstdescription{ This function stores a FITS header card in a \htmlref{FitsChan}{FitsChan}. The card is either inserted before the current card (identified by the \htmlref{Card}{Card} attribute), or over-writes the current card, as required. } \sstsynopsis{ void astPutFits( AstFitsChan $*$this, const char card[ 80 ], int overwrite ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ card }{ Pointer to a possibly null-terminated character string containing the FITS card to be stored. No more than 80 characters will be used from this string (or fewer if a null occurs earlier). } \sstsubsection{ overwrite }{ If this value is zero, the new card is inserted in front of the current card in the FitsChan (as identified by the initial value of the Card attribute). If it is non-zero, the new card replaces the current card. In either case, the Card attribute is then incremented by one so that it subsequently identifies the card following the one stored. } } \sstnotes{ \sstitemlist{ \sstitem If the Card attribute initially points at the \texttt{"} end-of-file\texttt{"} (i.e. exceeds the number of cards in the FitsChan), then the new card is appended as the last card in the FitsChan. \sstitem An error will result if the supplied string cannot be interpreted as a FITS header card. } } } \sstroutine{ astPutTable }{ Store a single FitsTable in a FitsChan }{ \sstdescription{ This function allows a representation of a single FITS binary table to be stored in a \htmlref{FitsChan}{FitsChan}. For instance, this may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling \htmlref{astRead}{astRead}, the astTablesSource function provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. } \sstsynopsis{ void astPutTable( AstFitsChan $*$this, AstFitsTable $*$table, const char $*$extnam ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ table }{ Pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. If a FitsTable with the associated extension name already exists in the FitsChan, it is replaced with the new one. A deep copy of the FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTable will have no effect on the behaviour of the FitsChan. } \sstsubsection{ extnam }{ The name of the FITS extension associated with the table. } } \sstnotes{ \sstitemlist{ \sstitem Tables stored in the FitsChan may be retrieved using \htmlref{astGetTables}{astGetTables}. \sstitem The \htmlref{astPutTables}{astPutTables} method can add multiple FitsTables in a single call. } } } \sstroutine{ astPutTableHeader }{ Store new FITS headers in a FitsTable }{ \sstdescription{ This function stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing headers are first deleted. } \sstsynopsis{ void astPutTableHeader( AstFitsTable $*$this, AstFitsChan $*$header ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsTable. } \sstsubsection{ header }{ Pointer to a \htmlref{FitsChan}{FitsChan} holding the headers for the FitsTable. A deep copy of the supplied FitsChan is stored in the FitsTable, replacing the current FitsChan in the Fitstable. Keywords that are fixed either by the properties of the \htmlref{Table}{Table}, or by the FITS standard, are removed from the copy (see \texttt{"} Notes:\texttt{"} below). } } \sstnotes{ \sstitemlist{ \sstitem The attributes of the supplied FitsChan, together with any source and sink functions associated with the FitsChan, are copied to the FitsTable. \sstitem Values for the following keywords are generated automatically by the FitsTable (any values for these keywords in the supplied FitsChan will be ignored): \texttt{"} XTENSION\texttt{"} , \texttt{"} BITPIX\texttt{"} , \texttt{"} NAXIS\texttt{"} , \texttt{"} NAXIS1\texttt{"} , \texttt{"} NAXIS2\texttt{"} , \texttt{"} PCOUNT\texttt{"} , \texttt{"} GCOUNT\texttt{"} , \texttt{"} TFIELDS\texttt{"} , \texttt{"} TFORM\%d\texttt{"} , \texttt{"} TTYPE\%d\texttt{"} , \texttt{"} TNULL\%d\texttt{"} , \texttt{"} THEAP\texttt{"} , \texttt{"} TDIM\%d\texttt{"} . } } } \sstroutine{ astPutTables }{ Store one or more FitsTables in a FitsChan }{ \sstdescription{ This function allows representations of one or more FITS binary tables to be stored in a \htmlref{FitsChan}{FitsChan}. For instance, these may provide the coordinate look-up tables needed subequently when reading FITS-WCS headers for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, the calling application may not know which tables will be needed - if any - prior to calling \htmlref{astRead}{astRead}, the astTablesSource function provides an alternative mechanism in which a caller-supplied function is invoked to store a named table in the FitsChan. } \sstsynopsis{ void astPutTables( AstFitsChan $*$this, AstKeyMap $*$tables ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ tables }{ Pointer to a \htmlref{KeyMap}{KeyMap} holding the tables that are to be added to the FitsChan. Each entry should hold a scalar value which is a pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. Any unusable entries are ignored. The key associated with each entry should be the name of the FITS binary extension from which the table was read. If a FitsTable with the associated key already exists in the FitsChan, it is replaced with the new one. A deep copy of each usable FitsTable is stored in the FitsChan, so any subsequent changes made to the FitsTables will have no effect on the behaviour of the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem Tables stored in the FitsChan may be retrieved using \htmlref{astGetTables}{astGetTables}. \sstitem The tables in the supplied KeyMap are added to any tables already in the FitsChan. \sstitem The \htmlref{astPutTable}{astPutTable} method provides a simpler means of adding a single table to a FitsChan. } } } \sstroutine{ astQuadApprox }{ Obtain a quadratic approximation to a 2D Mapping }{ \sstdescription{ This function returns the co-efficients of a quadratic fit to the supplied \htmlref{Mapping}{Mapping} over the input area specified by \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} . The Mapping must have 2 inputs, but may have any number of outputs. The i\texttt{'} th Mapping output is modelled as a quadratic function of the 2 inputs (x,y): output\_i = a\_i\_0 $+$ a\_i\_1$*$x $+$ a\_i\_2$*$y $+$ a\_i\_3$*$x$*$y $+$ a\_i\_4$*$x$*$x $+$ a\_i\_5$*$y$*$y The \texttt{"} fit\texttt{"} array is returned holding the values of the co-efficients a\_0\_0, a\_0\_1, etc. } \sstsynopsis{ int QuadApprox( AstMapping $*$this, const double lbnd[2], const double ubnd[2], int nx, int ny, double $*$fit, double $*$rms ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping. } \sstsubsection{ lbnd }{ Pointer to an array of doubles containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This box should specify the region over which the fit is to be performed. } \sstsubsection{ ubnd }{ Pointer to an array of doubles containing the upper bounds of the box specifying the region over which the fit is to be performed. } \sstsubsection{ nx }{ The number of points to place along the first Mapping input. The first point is at \texttt{"} lbnd[0]\texttt{"} and the last is at \texttt{"} ubnd[0]\texttt{"} . If a value less than three is supplied a value of three will be used. } \sstsubsection{ ny }{ The number of points to place along the second Mapping input. The first point is at \texttt{"} lbnd[1]\texttt{"} and the last is at \texttt{"} ubnd[1]\texttt{"} . If a value less than three is supplied a value of three will be used. } \sstsubsection{ fit }{ Pointer to an array of doubles in which to return the co-efficients of the quadratic approximation to the specified transformation. This array should have at least \texttt{"} 6$*$\htmlref{Nout}{Nout}\texttt{"} , elements. The first 6 elements hold the fit to the first Mapping output. The next 6 elements hold the fit to the second Mapping output, etc. So if the Mapping has 2 inputs and 2 outputs the quadratic approximation to the forward transformation is: X\_out = fit[0] $+$ fit[1]$*$X\_in $+$ fit[2]$*$Y\_in $+$ fit[3]$*$X\_in$*$Y\_in $+$ fit[4]$*$X\_in$*$X\_in $+$ fit[5]$*$Y\_in$*$Y\_in Y\_out = fit[6] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in $+$ fit[9]$*$X\_in$*$Y\_in $+$ fit[10]$*$X\_in$*$X\_in $+$ fit[11]$*$Y\_in$*$Y\_in } \sstsubsection{ rms }{ Pointer to a double in which to return the RMS residual between the fit and the Mapping, summed over all Mapping outputs. } } \sstreturnedvalue{ \sstsubsection{ astQuadApprox() }{ If a quadratic approximation was created, a non-zero value is returned. Otherwise zero is returned and the fit co-efficients are set to AST\_\_BAD. } } \sstnotes{ \sstitemlist{ \sstitem This function fits the Mapping\texttt{'} s forward transformation. To fit the inverse transformation, the Mapping should be inverted using \htmlref{astInvert}{astInvert} before invoking this function. \sstitem 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. } } } \sstroutine{ astRate }{ Calculate the rate of change of a Mapping output }{ \sstdescription{ This function evaluates the rate of change of a specified output of the supplied \htmlref{Mapping}{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. This method produces good accuracy but can involve evaluating the Mapping 100 or more times. } \sstsynopsis{ double astRate( AstMapping $*$this, double $*$at, int ax1, int ax2 ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ 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. } \sstsubsection{ ax1 }{ The index of the Mapping output for which the rate of change is to be found (output numbering starts at 1 for the first output). } \sstsubsection{ ax2 }{ The index of the Mapping input which is to be varied in order to find the rate of change (input numbering starts at 1 for the first input). } } \sstreturnedvalue{ \sstsubsection{ astRate() }{ The rate of change of Mapping output \texttt{"} ax1\texttt{"} with respect to input \texttt{"} ax2\texttt{"} , evaluated at \texttt{"} at\texttt{"} , or AST\_\_BAD if the value cannot be calculated. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } } \sstroutine{ astRateMap }{ Create a RateMap }{ \sstdescription{ This function creates a new \htmlref{RateMap}{RateMap} and optionally initialises its attributes. A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created). A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation. } \sstsynopsis{ AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ map }{ Pointer to the encapsulated Mapping. } \sstsubsection{ ax1 }{ Index of the output from the encapsulated Mapping for which the rate of change is required. This corresponds to the delta quantity forming the numerator of the required element of the Jacobian matrix. The first axis has index 1. } \sstsubsection{ ax2 }{ Index of the input to the encapsulated Mapping which is to be varied. This corresponds to the delta quantity forming the denominator of the required element of the Jacobian matrix. The first axis has index 1. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new RateMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astRateMap() }{ A pointer to the new RateMap. } } \sstnotes{ \sstitemlist{ \sstitem The forward transformation of the encapsulated Mapping must be defined. \sstitem Note that the component Mappings supplied are not copied by astRateMap (the new RateMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a RateMap containing a copy of its component Mappings is required, then a copy of the RateMap should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astRead }{ Read an Object from a Channel }{ \sstdescription{ This function reads the next \htmlref{Object}{Object} from a \htmlref{Channel}{Channel} and returns a pointer to the new Object. } \sstsynopsis{ AstObject $*$astRead( AstChannel $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Channel. } } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All successful use of astRead on a FitsChan is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the FitsChan \htmlref{astRetainFits}{astRetainFits} function). An unsuccessful call of astRead (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The AST Object returned by a successful use of astRead on an StcsChan, will be either a \htmlref{Region}{Region} or a \htmlref{KeyMap}{KeyMap}, depending on the values of the \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} attributes. See the documentation for these attributes for further information. } } \sstreturnedvalue{ \sstsubsection{ astRead() }{ A pointer to the new Object. The class to which this will belong is determined by the input data, so is not known in advance. } } \sstnotes{ \sstitemlist{ \sstitem A null Object pointer (AST\_\_NULL) will be returned, without error, if the Channel contains no further Objects to be read. \sstitem A null Object pointer will also be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astReadFits }{ Read cards into a FitsChan from the source function }{ \sstdescription{ This function reads cards from the source function that was specified when the \htmlref{FitsChan}{FitsChan} was created, and stores them in the FitsChan. This normally happens once-only, when the FitsChan is accessed for the first time. This function provides a means of forcing a re-read of the external source, and may be useful if (say) new cards have been deposited into the external source. Any newcards read from the source are appended to the end of the current contents of the FitsChan. } \sstsynopsis{ void astReadFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if no source function was specified when the FitsChan was created. \sstitem The \htmlref{SourceFile}{SourceFile} attribute is ignored by this function. New cards are read from the source file whenever a new value is assigned to the SourceFile attribute. } } } \sstroutine{ astRebin$<$X$>$ }{ Rebin a region of a data grid }{ \sstdescription{ This is a set of functions for rebinning gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Rebinning may be restricted to a specified region of the input grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the rebined output data. Propagation of missing data (bad pixels) is supported. Note, if you will be rebining a sequence of input arrays and then co-adding them into a single array, the alternative \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} functions will in general be more efficient. You should use a rebinning function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astRebin$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are rebinning data with type \texttt{"} float\texttt{"} , you should use the function astRebinF (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). Rebinning of the grid of input data is performed by transforming the coordinates of the centre of each input grid element (or pixel) into the coordinate system of the output grid. The input pixel value is then divided up and assigned to the output pixels in the neighbourhood of the central output coordinates. A choice of schemes are provided for determining how each input pixel value is divided up between the output pixels. In general, each output pixel may be assigned values from more than one input pixel. All contributions to a given output pixel are summed to produce the final output pixel value. Output pixels can be set to the supplied bad value if they receive contributions from an insufficient number of input pixels. This is controlled by the \texttt{"} wlim\texttt{"} parameter. Input pixel coordinates are transformed into the coordinate system of the output grid using the forward transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping\texttt{'} s forward transformation as they are transferred from the input to the output grid. In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel. This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstsynopsis{ void astRebin$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in, const int lbnd\_in[], const int ubnd\_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], int spread, const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim\_out, const int lbnd\_out[], const int ubnd\_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] ); } \sstparameters{ \sstsubsection{ this }{ Pointer to a Mapping, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by \texttt{"} ndim\_out\texttt{"} . } \sstsubsection{ wlim }{ Gives the required number of input pixel values which must contribute to an output pixel in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied \texttt{"} wlim\texttt{"} value, then the output pixel value is returned set to the supplied bad value. } \sstsubsection{ ndim\_in }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ lbnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ in }{ Pointer to an array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astRebinF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ in\_var }{ An optional pointer to a second array with the same size and type as the \texttt{"} in\texttt{"} array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the \texttt{"} in\texttt{"} array. If this array is supplied (together with the corresponding \texttt{"} out\_var\texttt{"} array), then estimates of the variance of the rebined output data will be calculated. If no input variance estimates are being provided, a NULL pointer should be given. } \sstsubsection{ spread }{ This parameter specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} section below. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST\_\_LINEAR). } \sstsubsection{ params }{ An optional pointer to an array of double which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} section below. If no additional parameters are required, this array is not used and a NULL pointer may be given. } \sstsubsection{ flags }{ The bitwise OR of a set of flag values which may be used to provide additional control over the rebinning operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ tol }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. } \sstsubsection{ maxpix }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting \texttt{"} tol\texttt{"} to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ badval }{ This argument should have the same type as the elements of the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} (and \texttt{"} in\_var\texttt{"} ) array(s). In all cases, this value is also used to flag any output elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which rebined values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). } \sstsubsection{ ndim\_out }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ lbnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ ubnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the shape, size and coordinate system of the output grid in the same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size and coordinate system of the input grid. } \sstsubsection{ lbnd }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. } \sstsubsection{ ubnd }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} arrays). Regions of the input grid lying outside this region will not be used. } \sstsubsection{ out }{ Pointer to an array, with one element for each pixel in the output grid, in which the rebined data values will be returned. The numerical type of this array should match that of the \texttt{"} in\texttt{"} array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ out\_var }{ An optional pointer to an array with the same type and size as the \texttt{"} out\texttt{"} array. If given, this array will be used to return variance estimates for the rebined data values. This array will only be used if the \texttt{"} in\_var\texttt{"} array has also been supplied. The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the pixel spreading schemes employed. If no output variance estimates are required, a NULL pointer should be given. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name astRebin$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astRebinD would be used to process \texttt{"} double\texttt{"} data, while astRebinI would be used to process \texttt{"} int\texttt{"} data, etc. Note that, unlike \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, the astRebin$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. } \sstdiytopic{ Pixel Spreading Schemes }{ The pixel spreading scheme specifies the Point Spread Function (PSF) applied to each input pixel value as it is copied into the output array. It can be thought of as the inverse of the sub-pixel interpolation schemes used by the astResample$<$X$>$ group of functions. That is, in a sub-pixel interpolation scheme the kernel specifies the weight to assign to each input pixel when forming the weighted mean of the input pixels, whereas the kernel in a pixel spreading scheme specifies the fraction of the input data value which is to be assigned to each output pixel. As for interpolation, the choice of suitable pixel spreading scheme involves stricking a balance between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features but which often tend to introduce unwanted artifacts. See the astResample$<$X$>$ documentation for further discussion. The binning algorithm used has the ability to introduce artifacts not seen when using a resampling algorithm. Particularly, when viewing the output image at high contrast, systems of curves lines covering the entire image may be visible. These are caused by a beating effect between the input pixel positions and the output pixels position, and their nature and strength depend critically upon the nature of the Mapping and the spreading function being used. In general, the nearest neighbour spreading function demonstrates this effect more clearly than the other functions, and for this reason should be used with caution. The following values (defined in the \texttt{"} ast.h\texttt{"} header file) may be assigned to the \texttt{"} spread\texttt{"} parameter. See the astResample$<$X$>$ documentation for details of these schemes including the use of the \texttt{"} fspread\texttt{"} and \texttt{"} params\texttt{"} parameters: \sstitemlist{ \sstitem AST\_\_NEAREST \sstitem AST\_\_LINEAR \sstitem AST\_\_SINC \sstitem AST\_\_SINCSINC \sstitem AST\_\_SINCCOS \sstitem AST\_\_SINCGAUSS \sstitem AST\_\_SOMBCOS } In addition, the following schemes can be used with astRebin$<$X$>$ but not with astResample$<$X$>$: \sstitemlist{ \sstitem AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant determined by the full-width at half-maximum (FWHM). The FWHM should be supplied in units of output pixels by means of the \texttt{"} params[1]\texttt{"} value and should be at least 0.1. The \texttt{"} params[0]\texttt{"} value should be used to specify at what point the Gaussian is truncated to zero. This should be given as a number of output pixels on either side of the central output point in each dimension (the nearest integer value is used). } } \sstdiytopic{ Control Flags }{ The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: \sstitemlist{ \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). If this flag is not set, all input values are treated literally and the \texttt{"} badval\texttt{"} value is only used for flagging output array values. } } \sstdiytopic{ Propagation of Missing Data }{ Instances of missing data (bad pixels) in the output grid are identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} array. These are produced if the sum of the weights of the contributing input pixels is less than \texttt{"} wlim\texttt{"} . An input pixel is considered bad (and is consequently ignored) if its data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter. In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} value in the \texttt{"} out\_var\texttt{"} array for similar reasons. } } \sstroutine{ astRebinSeq$<$X$>$ }{ Rebin a region of a sequence of data grids }{ \sstdescription{ This set of functions is identical to \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} except that the rebinned input data is added into the supplied output arrays, rather than simply over-writing the contents of the output arrays. Thus, by calling this function repeatedly, a sequence of input arrays can be rebinned and accumulated into a single output array, effectively forming a mosaic of the input data arrays. In addition, the weights associated with each output pixel are returned. The weight of an output pixel indicates the number of input pixels which have been accumulated in that output pixel. If the entire value of an input pixel is assigned to a single output pixel, then the weight of that output pixel is incremented by one. If some fraction of the value of an input pixel is assigned to an output pixel, then the weight of that output pixel is incremented by the fraction used. The start of a new sequence is indicated by specifying the AST\_\_REBININIT flag via the \texttt{"} flags\texttt{"} parameter. This causes the supplied arrays to be filled with zeros before the rebinned input data is added into them. Subsequenct invocations within the same sequence should omit the AST\_\_REBININIT flag. The last call in a sequence is indicated by specifying the AST\_\_REBINEND flag. Depending on which flags are supplied, this may cause the output data and variance arrays to be normalised before being returned. This normalisation consists of dividing the data array by the weights array, and can eliminate artifacts which may be introduced into the rebinned data as a consequence of aliasing between the input and output grids. This results in each output pixel value being the weighted mean of the input pixel values that fall in the neighbourhood of the output pixel (rather like \htmlref{astResample$<$X$>$}{astResample$<$X$>$}). Optionally, these normalised values can then be multiplied by a scaling factor to ensure that the total data sum in any small area is unchanged. This scaling factor is equivalent to the number of input pixel values that fall into each output pixel. In addition to normalisation of the output data values, any output variances are also appropriately normalised, and any output data values with weight less than \texttt{"} wlim\texttt{"} are set to \texttt{"} badval\texttt{"} . Output variances can be generated in two ways; by rebinning the supplied input variances with appropriate weights, or by finding the spread of input data values contributing to each output pixel (see the AST\_\_GENVAR and AST\_\_USEVAR flags). } \sstsynopsis{ void astRebinSeq$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in, const int lbnd\_in[], const int ubnd\_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], int spread, const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim\_out, const int lbnd\_out[], const int ubnd\_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], double weights[], int64\_t $*$nused ); } \sstparameters{ \sstsubsection{ this }{ Pointer to a \htmlref{Mapping}{Mapping}, whose forward transformation will be used to transform the coordinates of pixels in the input grid into the coordinate system of the output grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by \texttt{"} ndim\_out\texttt{"} . If \texttt{"} in\texttt{"} is NULL, the Mapping will not be used, but a valid Mapping must still be supplied. } \sstsubsection{ wlim }{ This value is only used if the AST\_\_REBINEND flag is specified via the \texttt{"} flags\texttt{"} parameter. It gives the required number of input pixel values which must contribute to an output pixel (i.e. the output pixel weight) in order for the output pixel value to be considered valid. If the sum of the input pixel weights contributing to an output pixel is less than the supplied \texttt{"} wlim\texttt{"} value, then the output pixel value is returned set to the supplied bad value. If the supplied value is less than 1.0E-10 then 1.0E-10 is used instead. } \sstsubsection{ ndim\_in }{ The number of dimensions in the input grid. This should be at least one. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ lbnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ ubnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ in }{ Pointer to an array, with one element for each pixel in the input grid, containing the input data to be rebined. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astRebinSeqF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). If a NULL pointer is supplied for \texttt{"} in\texttt{"} , then no data is added to the output arrays, but any initialisation or normalisation requested by \texttt{"} flags\texttt{"} is still performed. } \sstsubsection{ in\_var }{ An optional pointer to a second array with the same size and type as the \texttt{"} in\texttt{"} array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the \texttt{"} in\texttt{"} array. If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no input variance estimates are required and this pointer will not be used. A NULL pointer may then be supplied. } \sstsubsection{ spread }{ This parameter specifies the scheme to be used for dividing each input data value up amongst the corresponding output pixels. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the astRebin$<$X$>$ functions. If a value of zero is supplied, then the default linear spreading scheme is used (equivalent to supplying the value AST\_\_LINEAR). Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ params }{ An optional pointer to an array of double which should contain any additional parameter values required by the pixel spreading scheme. If such parameters are required, this will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the astRebin$<$X$>$ functions. If no additional parameters are required, this array is not used and a NULL pointer may be given. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ flags }{ The bitwise OR of a set of flag values which may be used to provide additional control over the rebinning operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ tol }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the output grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher, and may cause the edges of the panel to be visible when viewing the output image at high contrast. If this is a problem, reduce the tolerance value used. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ maxpix }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting \texttt{"} tol\texttt{"} to zero). Although this may degrade performance, accurate results will still be obtained. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ badval }{ This argument should have the same type as the elements of the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} (and \texttt{"} in\_var\texttt{"} ) array(s). In all cases, this value is also used to flag any output elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which rebined values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). } \sstsubsection{ ndim\_out }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ lbnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ ubnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the shape, size and coordinate system of the output grid in the same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size and coordinate system of the input grid. } \sstsubsection{ lbnd }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the first pixel in the region of the input grid which is to be included in the rebined output array. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ ubnd }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the last pixel in the region of the input grid which is to be included in the rebined output array. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and position of a (hyper-)rectangular region of the input grid which is to be included in the rebined output array. This region should lie wholly within the extent of the input grid (as defined by the \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} arrays). Regions of the input grid lying outside this region will not be used. Not used if \texttt{"} in\texttt{"} is NULL. } \sstsubsection{ out }{ Pointer to an array, with one element for each pixel in the output grid. The rebined data values will be added into the original contents of this array. The numerical type of this array should match that of the \texttt{"} in\texttt{"} array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ out\_var }{ A pointer to an array with the same type and size as the \texttt{"} out\texttt{"} array. This pointer will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set in which case variance estimates for the rebined data values will be added into the array. If neither the AST\_\_USEVAR flag nor the AST\_\_GENVAR flag is set, no output variance estimates will be calculated and this pointer will not be used. A NULL pointer may then be supplied. } \sstsubsection{ weights }{ Pointer to an array of double, with one or two elements for each pixel in the output grid, depending on whether or not the AST\_\_GENVAR flag has been supplied via the \texttt{"} flags\texttt{"} parameter. If AST\_\_GENVAR has not been specified then the array should have one element for each output pixel, and it will be used to accumulate the weight associated with each output pixel. If AST\_\_GENVAR has been specified then the array should have two elements for each output pixel. The first half of the array is again used to accumulate the weight associated with each output pixel, and the second half is used to accumulate the square of the weights. In each half, the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ nused }{ A pointer to an int64\_t containing the number of input data values that have been added into the output array so far. The supplied value is incremented on exit by the number of input values used. The value is initially set to zero if the AST\_\_REBININIT flag is set in \texttt{"} flags\texttt{"} . } } \sstdiytopic{ Data Type Codes }{ To select the appropriate rebinning function, you should replace $<$X$>$ in the generic function name astRebinSeq$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem I: int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astRebinSeqD would be used to process \texttt{"} double\texttt{"} data, while astRebinSeqI would be used to process \texttt{"} int\texttt{"} data, etc. Note that, unlike astResample$<$X$>$, the astRebinSeq$<$X$>$ set of functions does not yet support unsigned integer data types or integers of different sizes. } \sstdiytopic{ Control Flags }{ The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and may be used to provide additional control over the rebinning process. Having selected a set of flags, you should supply the bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: \sstitemlist{ \sstitem AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates that the supplied \texttt{"} out\texttt{"} , \texttt{"} out\_var\texttt{"} and \texttt{"} weights\texttt{"} arrays should be filled with zeros (thus over-writing any supplied values) before adding the rebinned input data into them. This flag should be used when rebinning the first input array in a sequence. \sstitem AST\_\_REBINEND: Used to mark the last call in a sequence. It causes each value in the \texttt{"} out\texttt{"} and \texttt{"} out\_var\texttt{"} arrays to be divided by a normalisation factor before being returned. The normalisation factor for each output data value is just the corresponding value from the weights array. The normalisation factor for each output variance value is the square of the data value normalisation factor (see also AST\_\_CONSERVEFLUX). It also causes output data values to be set bad if the corresponding weight is less than the value supplied for parameter \texttt{"} wlim\texttt{"} . It also causes any temporary values stored in the output variance array (see flag AST\_\_GENVAR below) to be converted into usable variance values. Note, this flag is ignored if the AST\_\_NONORM flag is set. \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). If this flag is not set, all input values are treated literally and the \texttt{"} badval\texttt{"} value is only used for flagging output array values. \sstitem AST\_\_USEVAR: Indicates that output variance estimates should be created by rebinning the supplied input variance estimates. An error will be reported if both this flag and the AST\_\_GENVAR flag are supplied. \sstitem AST\_\_GENVAR: Indicates that output variance estimates should be created based on the spread of input data values contributing to each output pixel. An error will be reported if both this flag and the AST\_\_USEVAR flag are supplied. If the AST\_\_GENVAR flag is specified, the supplied output variance array is first used as a work array to accumulate the temporary values needed to generate the output variances. When the sequence ends (as indicated by the AST\_\_REBINEND flag), the contents of the output variance array are converted into the required variance estimates. If the generation of such output variances is required, this flag should be used on every invocation of this function within a sequence, and any supplied input variances will have no effect on the output variances (although input variances will still be used to weight the input data if the AST\_\_VARWGT flag is also supplied). The statistical meaning of these output varianes is determined by the presence or absence of the AST\_\_DISVAR flag (see below). \sstitem AST\_\_DISVAR: This flag is ignored unless the AST\_\_GENVAR flag has also been specified. It determines the statistical meaning of the generated output variances. If AST\_\_DISVAR is not specified, generated variances represent variances on the output mean values. If AST\_\_DISVAR is specified, the generated variances represent the variance of the distribution from which the input values were taken. Each output variance created with AST\_\_DISVAR will be larger than that created without AST\_\_DISVAR by a factor equal to the number of input samples that contribute to the output sample. \sstitem AST\_\_VARWGT: Indicates that the input data should be weighted by the reciprocal of the input variances. Otherwise, all input data are given equal weight. If this flag is specified, the calculation of the output variances (if any) is modified to take account of the varying weights assigned to the input data values. \sstitem AST\_\_NONORM: If the simple unnormalised sum of all input data falling in each output pixel is required, then this flag should be set on each call in the sequence and the AST\_\_REBINEND should not be used on the last call. In this case NULL pointers can be supplied for \texttt{"} weights\texttt{"} and \texttt{"} nused\texttt{"} . This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR or AST\_\_VARWGT flag. \sstitem AST\_\_CONSERVEFLUX: Indicates that the normalized output pixel values generated by the AST\_\_REBINEND flag should be scaled in such a way as to preserve the total data value in a feature on the sky. Without this flag, each normalised output pixel value represents a weighted mean of the input data values around the corresponding input position. is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST\_\_CONSERVEFLUX flag could be of use. It causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size. } This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the \texttt{"} tol\texttt{"} parameter is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the \texttt{"} tol\texttt{"} parameter until the difference between adjacent panels is sufficiently small to be insignificant. This flag should normally be supplied on each invocation of astRebinSeq$<$X$>$ within a given sequence. Note, this flag cannot be used in conjunction with the AST\_\_NOSCALE flag (an error will be reported if both flags are specified). } \sstdiytopic{ Propagation of Missing Data }{ Instances of missing data (bad pixels) in the output grid are identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} array. These are only produced if the AST\_\_REBINEND flag is specified and a pixel has zero weight. An input pixel is considered bad (and is consequently ignored) if its data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter. In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} value in the \texttt{"} out\_var\texttt{"} array for similar reasons. } } \sstroutine{ astRegionOutline }{ Draw the outline of an AST Region }{ \sstdescription{ This function draws an outline around the supplied AST \htmlref{Region}{Region} object. } \sstsynopsis{ void astRegionOutline( AstPlot $*$this, AstRegion $*$region ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Plot}{Plot}. } \sstsubsection{ region }{ Pointer to the Region. } } } \sstroutine{ astRemapFrame }{ Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet }{ \sstdescription{ This function modifies the relationship (i.e. \htmlref{Mapping}{Mapping}) between a specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{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 FrameSet using this function. } \sstsynopsis{ void astRemapFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe }{ 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 \htmlref{Nframe}{Nframe} attribute). } \sstsubsection{ map }{ 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. } } \sstnotes{ \sstitemlist{ \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current Frame respectively. \sstitem The relationship between the selected Frame and any other Frame within the FrameSet will be modified by this function, but the relationship between all other Frames in the FrameSet remains unchanged. \sstitem The number of input coordinate values accepted by the Mapping (its \htmlref{Nin}{Nin} attribute) and the number of output coordinate values generated (its \htmlref{Nout}{Nout} attribute) must be equal and must match the number of axes in the Frame being modified. \sstitem If a simple change of axis order is required, then the \htmlref{astPermAxes}{astPermAxes} function may provide a more straightforward method of making the required changes to the FrameSet. \sstitem This function cannot be used to change the number of Frame axes. To achieve this, a new Frame must be added to the FrameSet (\htmlref{astAddFrame}{astAddFrame}) and the original one removed if necessary (\htmlref{astRemoveFrame}{astRemoveFrame}). \sstitem 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 \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). } } } \sstroutine{ astRemoveColumn }{ Remove a column from a table }{ \sstdescription{ This function removes a specified column from the supplied table. The function returns without action if the named column does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstsynopsis{ void astRemoveColumn( AstTable $*$this, const char $*$name ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ name }{ The column name. Trailing spaces are ignored (all other spaces are significant). Case is significant. } } } \sstroutine{ astRemoveFrame }{ Remove a Frame from a FrameSet }{ \sstdescription{ This function removes a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet}. All other Frames in the FrameSet have their indices re-numbered from one (if necessary), but are otherwise unchanged. } \sstsynopsis{ void astRemoveFrame( AstFrameSet $*$this, int iframe ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FrameSet. } \sstsubsection{ iframe }{ 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 \htmlref{Nframe}{Nframe} attribute). } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem 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. \sstitem A value of AST\_\_BASE or AST\_\_CURRENT may be given for the \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current Frame respectively. \sstitem If a FrameSet\texttt{'} s base or current Frame is removed, the \htmlref{Base}{Base} or \htmlref{Current}{Current} attribute (respectively) of the FrameSet will have its value cleared, so that another Frame will then assume its role by default. \sstitem 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. } } } \sstroutine{ astRemoveParameter }{ Remove a global parameter from a table }{ \sstdescription{ This function removes a specified global parameter from the supplied table. The function returns without action if the named parameter does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstsynopsis{ void astRemoveParameter( AstTable $*$this, const char $*$name ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ name }{ The parameter name. Trailing spaces are ignored (all other spaces are significant). Case is significant. } } } \sstroutine{ astRemoveRegions }{ Remove any Regions from a Mapping }{ \sstdescription{ This function searches the suppliedMapping (which may be a compound \htmlref{Mapping}{Mapping} such as a \htmlref{CmpMap}{CmpMap}) for any component Mappings that are instances of the AST \htmlref{Region}{Region} class. It then creates a new Mapping from which all Regions have been removed. If a Region cannot simply be removed (for instance, if it is a component of a parallel CmpMap), then it is replaced with an equivalent \htmlref{UnitMap}{UnitMap} in the returned Mapping. } \sstsynopsis{ AstMapping $*$astRemoveRegions( AstMapping $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the original Mapping. } } \sstapplicability{ \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ If the supplied Mapping is a CmpFrame, any component Frames that are instances of the Region class are replaced by the equivalent \htmlref{Frame}{Frame}. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which Regions have been removed from all the inter-Frame Mappings, and any Frames which are instances of the Region class are repalced by the equivalent Frame. } \sstsubsection{ Mapping }{ This function applies to all Mappings. } \sstsubsection{ Region }{ If the supplied Mapping is a Region, the returned Mapping will be the equivalent Frame. } } \sstreturnedvalue{ \sstsubsection{ astRemoveRegions() }{ A new pointer to the (possibly modified) Mapping. } } \sstnotes{ \sstitemlist{ \sstitem This function can safely be applied even to Mappings which contain no Regions. If no Regions are found, it behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the original Mapping. \sstitem The Mapping returned by this function may not be independent of the original (even if some Regions were removed), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astRemoveRow }{ Remove a row from a table }{ \sstdescription{ This function removes a specified row from the supplied table. The function returns without action if the row does not exist in the \htmlref{Table}{Table} (no error is reported). } \sstsynopsis{ void astRemoveRow( AstTable $*$this, int index ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Table. } \sstsubsection{ index }{ The index of the row to be removed. The first row has index 1. } } } \sstroutine{ astRemoveTables }{ Remove one or more tables from a FitsChan }{ \sstdescription{ This function removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error is reported if any the tables do not exist). } \sstsynopsis{ void astRemoveTables( AstFitsChan $*$this, const char $*$key ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ key }{ The key indicating which tables to exist. A single key or a comma-separated list of keys can be supplied. If a blank string is supplied, all tables are removed. } } } \sstroutine{ astResample$<$X$>$ }{ Resample a region of a data grid }{ \sstdescription{ This is a set of functions for resampling gridded data (e.g. an image) under the control of a geometrical transformation, which is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of data grids (input and output), each of which may have any number of dimensions. Resampling may be restricted to a specified region of the output grid. An associated grid of error estimates associated with the input data may also be supplied (in the form of variance values), so as to produce error estimates for the resampled output data. Propagation of missing data (bad pixels) is supported. You should use a resampling function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name astResample$<$X$>$ by an appropriate 1- or 2-character type code. For example, if you are resampling data with type \texttt{"} float\texttt{"} , you should use the function astResampleF (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to other numerical types). Resampling of the grid of input data is performed by transforming the coordinates of the centre of each output grid element (or pixel) into the coordinate system of the input grid. Since the resulting coordinates will not, in general, coincide with the centre of an input pixel, sub-pixel interpolation is performed between the neighbouring input pixels. This produces a resampled value which is then assigned to the output pixel. A choice of sub-pixel interpolation schemes is provided, but you may also implement your own. This algorithm samples the input data value, it does not integrate it. Thus total data value in the input image will not, in general, be conserved. However, an option is provided (see the \texttt{"} Control Flags\texttt{"} section below) which can produce approximate flux conservation by scaling the output values using the ratio of the output pixel size to the input pixel size. However, if accurate flux conservation is important to you, consder using the \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} or \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} family of functions instead. Output pixel coordinates are transformed into the coordinate system of the input grid using the inverse transformation of the Mapping which is supplied. This means that geometrical features in the input data are subjected to the Mapping\texttt{'} s forward transformation as they are transferred from the input to the output grid (although the Mapping\texttt{'} s forward transformation is not explicitly used). In practice, transforming the coordinates of every pixel of a large data grid can be time-consuming, especially if the Mapping involves complicated functions, such as sky projections. To improve performance, it is therefore possible to approximate non-linear Mappings by a set of linear transformations which are applied piece-wise to separate sub-regions of the data. This approximation process is applied automatically by an adaptive algorithm, under control of an accuracy criterion which expresses the maximum tolerable geometrical distortion which may be introduced, as a fraction of a pixel. This algorithm first attempts to approximate the Mapping with a linear transformation applied over the whole region of the output grid which is being used. If this proves to be insufficiently accurate, the output region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstsynopsis{ int astResample$<$X$>$( AstMapping $*$this, int ndim\_in, const int lbnd\_in[], const int ubnd\_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], int interp, void ($*$ finterp)( void ), const double params[], int flags, double tol, int maxpix, $<$Xtype$>$ badval, int ndim\_out, const int lbnd\_out[], const int ubnd\_out[], const int lbnd[], const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] ); } \sstparameters{ \sstsubsection{ this }{ Pointer to a Mapping, whose inverse transformation will be used to transform the coordinates of pixels in the output grid into the coordinate system of the input grid. This yields the positions which are used to obtain resampled values by sub-pixel interpolation within the input grid. The number of input coordinates used by this Mapping (as given by its \htmlref{Nin}{Nin} attribute) should match the number of input grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} attribute) should match the number of output grid dimensions given by \texttt{"} ndim\_out\texttt{"} . } \sstsubsection{ ndim\_in }{ The number of dimensions in the input grid. This should be at least one. } \sstsubsection{ lbnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ in }{ Pointer to an array, with one element for each pixel in the input grid, containing the input data to be resampled. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using astResampleF, the type of each array element should be \texttt{"} float\texttt{"} ). The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ in\_var }{ An optional pointer to a second array with the same size and type as the \texttt{"} in\texttt{"} array. If given, this should contain a set of non-negative values which represent estimates of the statistical variance associated with each element of the \texttt{"} in\texttt{"} array. If this array is supplied (together with the corresponding \texttt{"} out\_var\texttt{"} array), then estimates of the variance of the resampled output data will be calculated. If no input variance estimates are being provided, a NULL pointer should be given. } \sstsubsection{ interp }{ This parameter specifies the scheme to be used for sub-pixel interpolation within the input grid. It may be used to select from a set of pre-defined schemes by supplying one of the values described in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below. If a value of zero is supplied, then the default linear interpolation scheme is used (equivalent to supplying the value AST\_\_LINEAR). Alternatively, you may supply a value which indicates that you will provide your own function to perform sub-pixel interpolation by means of the \texttt{"} finterp \texttt{"} parameter. Again, see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below for details. } \sstsubsection{ finterp }{ If the value given for the \texttt{"} interp\texttt{"} parameter indicates that you will provide your own function for sub-pixel interpolation, then a pointer to that function should be given here. For details of the interface which the function should have (several are possible, depending on the value of \texttt{"} interp\texttt{"} ), see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below. If the \texttt{"} interp\texttt{"} parameter has any other value, corresponding to one of the pre-defined interpolation schemes, then this function will not be used and you may supply a NULL pointer. } \sstsubsection{ params }{ An optional pointer to an array of double which should contain any additional parameter values required by the sub-pixel interpolation scheme. If such parameters are required, this will be noted in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below (you may also use this array to pass values to your own interpolation function). If no additional parameters are required, this array is not used and a NULL pointer may be given. } \sstsubsection{ flags }{ The bitwise OR of a set of flag values which may be used to provide additional control over the resampling operation. See the \texttt{"} Control Flags\texttt{"} section below for a description of the options available. If no flag values are to be set, a value of zero should be given. } \sstsubsection{ tol }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement in pixels in the input grid\texttt{'} s coordinate system. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. } \sstsubsection{ maxpix }{ A value which specifies an initial scale size (in pixels) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the output grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire output region. If a smaller value is used, the output region will first be divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} pixels in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 pixels can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting \texttt{"} tol\texttt{"} to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ badval }{ This argument should have the same type as the elements of the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing data (bad pixels) in the input and output arrays. If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} (and \texttt{"} in\_var\texttt{"} ) array(s). Unless the AST\_\_NOBAD flag is set via the \texttt{"} flags\texttt{"} parameter, this value is also used to flag any output elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which resampled values could not be obtained (see the \texttt{"} Propagation of Missing Data\texttt{"} section below for details of the circumstances under which this may occur). The astResample$<$X$>$ function return value indicates whether any such values have been produced. If the AST\_\_NOBAD flag is set. then output array elements for which no resampled value could be obtained are left set to the value they had on entry to this function. } \sstsubsection{ ndim\_out }{ The number of dimensions in the output grid. This should be at least one. It need not necessarily be equal to the number of dimensions in the input grid. } \sstsubsection{ lbnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the first pixel in the output grid along each dimension. } \sstsubsection{ ubnd\_out }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the centre of the last pixel in the output grid along each dimension. Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the shape, size and coordinate system of the output grid in the same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size and coordinate system of the input grid. } \sstsubsection{ lbnd }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the first pixel in the region of the output grid for which a resampled value is to be calculated. } \sstsubsection{ ubnd }{ Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, containing the coordinates of the last pixel in the region of the output grid for which a resampled value is to be calculated. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and position of a (hyper-)rectangular region of the output grid for which resampled values should be produced. This region should lie wholly within the extent of the output grid (as defined by the \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} arrays). Regions of the output grid lying outside this region will not be modified. } \sstsubsection{ out }{ Pointer to an array, with one element for each pixel in the output grid, into which the resampled data values will be returned. The numerical type of this array should match that of the \texttt{"} in\texttt{"} array, and the data storage order should be such that the index of the first grid dimension varies most rapidly and that of the final dimension least rapidly (i.e. Fortran array indexing is used). } \sstsubsection{ out\_var }{ An optional pointer to an array with the same type and size as the \texttt{"} out\texttt{"} array. If given, this array will be used to return variance estimates for the resampled data values. This array will only be used if the \texttt{"} in\_var\texttt{"} array has also been supplied. The output variance values will be calculated on the assumption that errors on the input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors) when several input pixels contribute to an output data value. If this assumption is not valid, then the output error estimates may be biased. In addition, note that the statistical errors on neighbouring output data values (as well as the estimates of those errors) may often be correlated, even if the above assumption about the input data is correct, because of the sub-pixel interpolation schemes employed. If no output variance estimates are required, a NULL pointer should be given. } } \sstreturnedvalue{ \sstsubsection{ astResample$<$X$>$() }{ The number of output pixels for which no valid resampled value could be obtained. Thus, in the absence of any error, a returned value of zero indicates that all the required output pixels received valid resampled data values (and variances). See the \texttt{"} badval\texttt{"} and \texttt{"} flags\texttt{"} parameters. } } \sstnotes{ \sstitemlist{ \sstitem 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. } } \sstdiytopic{ Data Type Codes }{ To select the appropriate resampling function, you should replace $<$X$>$ in the generic function name astResample$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows: \sstitemlist{ \sstitem D: double \sstitem F: float \sstitem L: long int (may be 32 or 64 bit) \sstitem K: 64 bit int \sstitem UL: unsigned long int (may be 32 or 64 bit) \sstitem UK: unsigned 64 bit int \sstitem I: int \sstitem UI: unsigned int \sstitem S: short int \sstitem US: unsigned short int \sstitem B: byte (signed char) \sstitem UB: unsigned byte (unsigned char) } For example, astResampleD would be used to process \texttt{"} double\texttt{"} data, while astResampleS would be used to process \texttt{"} short int\texttt{"} data, etc. } \sstdiytopic{ Sub-Pixel Interpolation Schemes }{ There is no such thing as a perfect sub-pixel interpolation scheme and, in practice, all resampling will result in some degradation of gridded data. A range of schemes is therefore provided, from which you can choose the one which best suits your needs. In general, a balance must be struck between schemes which tend to degrade sharp features in the data by smoothing them, and those which attempt to preserve sharp features. The latter will often tend to introduce unwanted oscillations, typically visible as \texttt{"} ringing\texttt{"} around sharp features and edges, especially if the data are under-sampled (i.e. if the sharpest features are less than about two pixels across). In practice, a good interpolation scheme is likely to be a compromise and may exhibit some aspects of both these features. For under-sampled data, some interpolation schemes may appear to preserve data resolution because they transform single input pixels into single output pixels, rather than spreading their data between several output pixels. While this may look better cosmetically, it can result in a geometrical shift of sharp features in the data. You should beware of this if you plan to use such features (e.g.) for image alignment. The following are two easy-to-use sub-pixel interpolation schemes which are generally applicable. They are selected by supplying the appropriate value (defined in the \texttt{"} ast.h\texttt{"} header file) via the \texttt{"} interp\texttt{"} parameter. In these cases, the \texttt{"} finterp\texttt{"} and \texttt{"} params\texttt{"} parameters are not used: \sstitemlist{ \sstitem AST\_\_NEAREST: This is the simplest possible scheme, in which the value of the input pixel with the nearest centre to the interpolation point is used. This is very quick to execute and will preserve single-pixel features in the data, but may displace them by up to half their width along each dimension. It often gives a good cosmetic result, so is useful for quick-look processing, but is unsuitable if accurate geometrical transformation is required. \sstitem AST\_\_LINEAR: This is the default scheme, which uses linear interpolation between the nearest neighbouring pixels in the input grid (there are two neighbours in one dimension, four neighbours in two dimensions, eight in three dimensions, etc.). It is superior to the nearest-pixel scheme (above) in not displacing features in the data, yet it still executes fairly rapidly. It is generally a safe choice if you do not have any particular reason to favour another scheme, since it cannot introduce oscillations. However, it does introduce some spatial smoothing which varies according to the distance of the interpolation point from the neighbouring pixels. This can degrade the shape of sharp features in the data in a position-dependent way. It may also show in the output variance grid (if used) as a pattern of stripes or fringes. } An alternative set of interpolation schemes is based on forming the interpolated value from the weighted sum of a set of surrounding pixel values (not necessarily just the nearest neighbours). This approach has its origins in the theory of digital filtering, in which interpolated values are obtained by conceptually passing the sampled data (represented by a grid of delta functions) through a linear filter which implements a convolution. Because the convolution kernel is continuous, the convolution yields a continuous function which may then be evaluated at fractional pixel positions. The (possibly multi-dimensional) kernel is usually regarded as \texttt{"} separable\texttt{"} and formed from the product of a set of identical 1-dimensional kernel functions, evaluated along each dimension. Different interpolation schemes are then distinguished by the choice of this 1-dimensional interpolation kernel. The number of surrounding pixels which contribute to the result may also be varied. From a practical standpoint, it is useful to divide the weighted sum of pixel values by the sum of the weights when determining the interpolated value. Strictly, this means that a true convolution is no longer being performed. However, the distinction is rarely important in practice because (for slightly subtle reasons) the sum of weights is always approximately constant for good interpolation kernels. The advantage of this technique, which is used here, is that it can easily accommodate missing data and tends to minimise unwanted oscillations at the edges of the data grid. In the following schemes, which are based on a 1-dimensional interpolation kernel, the first element of the \texttt{"} params\texttt{"} array should be used to specify how many pixels are to contribute to the interpolated result on either side of the interpolation point in each dimension (the nearest integer value is used). Execution time increases rapidly with this number. Typically, a value of 2 is appropriate and the minimum value used will be 1 (i.e. two pixels altogether, one on either side of the interpolation point). A value of zero or less may be given for \texttt{"} params[0]\texttt{"} to indicate that a suitable number of pixels should be calculated automatically. In each of these cases, the \texttt{"} finterp\texttt{"} parameter is not used: \sstitemlist{ \sstitem AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k a positive constant. The full-width at half-maximum (FWHM) is given by \texttt{"} params[1]\texttt{"} to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1\% of its maximum value). This kernel suppresses noise at the expense of smoothing the output array. \sstitem AST\_\_SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the pixel offset from the interpolation point and sinc(z)=sin(z)/z. This sometimes features as an \texttt{"} optimal\texttt{"} interpolation kernel in books on image processing. Its supposed optimality depends on the assumption that the data are band-limited (i.e. have no spatial frequencies above a certain value) and are adequately sampled. In practice, astronomical data rarely meet these requirements. In addition, high spatial frequencies are often present due (e.g.) to image defects and cosmic ray events. Consequently, substantial ringing can be experienced with this kernel. The kernel also decays slowly with distance, so that many surrounding pixels are required, leading to poor performance. Abruptly truncating it, by using only a few neighbouring pixels, improves performance and may reduce ringing (if \texttt{"} params[0]\texttt{"} is set to zero, then only two pixels will be used on either side). However, a more gradual truncation, as implemented by other kernels, is generally to be preferred. This kernel is provided mainly so that you can convince yourself not to use it! \sstitem AST\_\_SINCSINC: This scheme uses an improved kernel, of the form sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor provides an \texttt{"} envelope\texttt{"} which gradually rolls off the normal sinc(pi$*$x) kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the \texttt{"} params[1]\texttt{"} value, which should be at least 1.0 (in addition, setting \texttt{"} params[0]\texttt{"} to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). The case given by \texttt{"} params[0]=2, params[1]=2\texttt{"} is typically a good choice and is sometimes known as the Lanczos kernel. This is a valuable general-purpose interpolation scheme, intermediate in its visual effect on images between the AST\_\_NEAREST and AST\_\_LINEAR schemes. Although the kernel is slightly oscillatory, ringing is adequately suppressed if the data are well sampled. \sstitem AST\_\_SINCCOS: This scheme uses a kernel of the form sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor provides an envelope which gradually rolls off the sinc() kernel at large offsets. The width of this envelope is specified by giving the number of pixels offset at which it goes to zero by means of the \texttt{"} params[1]\texttt{"} value, which should be at least 1.0 (in addition, setting \texttt{"} params[0]\texttt{"} to zero will select the number of contributing pixels so as to utilise the full width of the kernel, out to where it reaches zero). This scheme gives similar results to the AST\_\_SINCSINC scheme, which it resembles. \sstitem AST\_\_SINCGAUSS: This scheme uses a kernel of the form sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc() kernel is rolled off using a Gaussian envelope which is specified by giving its full-width at half-maximum (FWHM) by means of the \texttt{"} params[1]\texttt{"} value, which should be at least 0.1 (in addition, setting \texttt{"} params[0]\texttt{"} to zero will select the number of contributing pixels so as to utilise the width of the kernel out to where the envelope declines to 1\% of its maximum value). On astronomical images and spectra, good results are often obtained by approximately matching the FWHM of the envelope function, given by \texttt{"} params[1]\texttt{"} , to the point spread function of the input data. However, there does not seem to be any theoretical reason for this. \sstitem AST\_\_SOMB: This scheme uses a somb(pi$*$x) kernel (a \texttt{"} sombrero\texttt{"} function), where x is the pixel offset from the interpolation point and somb(z)=2$*$J1(z)/z (J1 is a Bessel function of the first kind of order 1). It is similar to the AST\_\_SINC kernel, and has the same parameter usage. \sstitem AST\_\_SOMBCOS: This scheme uses a kernel of the form somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the AST\_\_SINCCOS kernel, and has the same parameter usage. } In addition, the following schemes are provided which are not based on a 1-dimensional kernel: \sstitemlist{ \sstitem AST\_\_BLOCKAVE: This scheme simply takes an average of all the pixels on the input grid in a cube centred on the interpolation point. The number of pixels in the cube is determined by the value of the first element of the \texttt{"} params\texttt{"} array, which gives the number of pixels in each dimension on either side of the central point. Hence a block of (2 $*$ params[0])$\wedge$ndim\_in pixels in the input grid will be examined to determine the value of the output pixel. If the variance is not being used (var\_in or var\_out = NULL) then all valid pixels in this cube will be averaged in to the result with equal weight. If variances are being used, then each input pixel will be weighted proportionally to the reciprocal of its variance; any pixel without a valid variance will be discarded. This scheme is suitable where the output grid is much coarser than the input grid; if the ratio of pixel sizes is R then a suitable value of params[0] may be R/2. } Finally, supplying the following values for \texttt{"} interp\texttt{"} allows you to implement your own sub-pixel interpolation scheme by means of your own function. You should supply a pointer to this function via the \texttt{"} finterp\texttt{"} parameter: \sstitemlist{ \sstitem AST\_\_UKERN1: In this scheme, you supply a function to evaluate your own 1-dimensional interpolation kernel, which is then used to perform sub-pixel interpolation (as described above). The function you supply should have the same interface as the fictitious \htmlref{astUkern1}{astUkern1} function (q.v.). In addition, a value should be given via \texttt{"} params[0]\texttt{"} to specify the number of neighbouring pixels which are to contribute to each interpolated value (in the same way as for the pre-defined interpolation schemes described above). Other elements of the \texttt{"} params\texttt{"} array are available to pass values to your interpolation function. \sstitem AST\_\_UINTERP: This is a completely general scheme, in which your interpolation function has access to all of the input data. This allows you to implement any interpolation algorithm you choose, which could (for example) be non-linear, or adaptive. In this case, the astResample$<$X$>$ functions play no role in the sub-pixel interpolation process and simply handle the geometrical transformation of coordinates and other housekeeping. The function you supply should have the same interface as the fictitious \htmlref{astUinterp}{astUinterp} function (q.v.). In this case, the \texttt{"} params\texttt{"} parameter is not used by astResample$<$X$>$, but is available to pass values to your interpolation function. } } \sstdiytopic{ Control Flags }{ The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and may be used to provide additional control over the resampling process. Having selected a set of flags, you should supply the bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: \sstitemlist{ \sstitem AST\_\_NOBAD: Indicates that any output array elements for which no resampled value could be obtained should be left set to the value they had on entry to this function. If this flag is not supplied, such output array elements are set to the value supplied for parameter \texttt{"} badval\texttt{"} . Note, this flag cannot be used in conjunction with the AST\_\_CONSERVEFLUX flag (an error will be reported if both flags are specified). \sstitem AST\_\_URESAMP1, 2, 3 \& 4: A set of four flags which are reserved for your own use. They may be used to pass private information to any sub-pixel interpolation function which you implement yourself. They are ignored by all the pre-defined interpolation schemes. \sstitem AST\_\_USEBAD: Indicates that there may be bad pixels in the input array(s) which must be recognised by comparing with the value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). If this flag is not set, all input values are treated literally and the \texttt{"} badval\texttt{"} value is only used for flagging output array values. \sstitem AST\_\_CONSERVEFLUX: Indicates that the output pixel values should be scaled in such a way as to preserve (approximately) the total data value in a feature on the sky. Without this flag, each output pixel value represents an instantaneous sample of the input data values at the corresponding input position. This is appropriate if the input data represents the spatial density of some quantity (e.g. surface brightness in Janskys per square arc-second) because the output pixel values will have the same normalisation and units as the input pixel values. However, if the input data values represent flux (or some other physical quantity) per pixel, then the AST\_\_CONSERVEFLUX flag could be used. This causes each output pixel value to be scaled by the ratio of the output pixel size to the input pixel size. } This flag can only be used if the Mapping is successfully approximated by one or more linear transformations. Thus an error will be reported if it used when the \texttt{"} tol\texttt{"} parameter is set to zero (which stops the use of linear approximations), or if the Mapping is too non-linear to be approximated by a piece-wise linear transformation. The ratio of output to input pixel size is evaluated once for each panel of the piece-wise linear approximation to the Mapping, and is assumed to be constant for all output pixels in the panel. The scaling factors for adjacent panels will in general differ slightly, and so the joints between panels may be visible when viewing the output image at high contrast. If this is a problem, reduce the value of the \texttt{"} tol\texttt{"} parameter until the difference between adjacent panels is sufficiently small to be insignificant. Note, this flag cannot be used in conjunction with the AST\_\_NOBAD flag (an error will be reported if both flags are specified). } \sstdiytopic{ Propagation of Missing Data }{ Unless the AST\_\_NOBAD flag is specified, instances of missing data (bad pixels) in the output grid are identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} array. These may be produced if any of the following happen: \sstitemlist{ \sstitem The input position (the transformed position of the output pixel\texttt{'} s centre) lies outside the boundary of the grid of input pixels. \sstitem The input position lies inside the boundary of a bad input pixel. In this context, an input pixel is considered bad if its data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter. (Positions which have half-integral coordinate values, and therefore lie on a pixel boundary, are regarded as lying within the pixel with the larger, i.e. more positive, index.) \sstitem The set of neighbouring input pixels (excluding those which are bad) is unsuitable for calculating an interpolated value. Whether this is true may depend on the sub-pixel interpolation scheme in use. \sstitem The interpolated value lies outside the range which can be represented using the data type of the \texttt{"} out\texttt{"} array. } In addition, associated output variance estimates (if calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} value in the \texttt{"} out\_var\texttt{"} array under any of the following circumstances: \sstitemlist{ \sstitem The associated resampled data value (in the \texttt{"} out\texttt{"} array) is bad. \sstitem The set of neighbouring input pixels which contributed to the output data value do not all have valid variance estimates associated with them. In this context, an input variance estimate may be regarded as bad either because it has the value \texttt{"} badval\texttt{"} (and the AST\_\_USEBAD flag is set), or because it is negative. \sstitem The set of neighbouring input pixels for which valid variance values are available is unsuitable for calculating an overall variance value. Whether this is true may depend on the sub-pixel interpolation scheme in use. \sstitem The variance value lies outside the range which can be represented using the data type of the \texttt{"} out\_var\texttt{"} array. } If the AST\_\_NOBAD flag is specified via parameter \texttt{"} flags\texttt{"} , then output array elements that would otherwise be set to \texttt{"} badval\texttt{"} are instead left holding the value they had on entry to this function. The number of such array elements is returned as the function value. } } \sstroutine{ astResolve }{ Resolve a vector into two orthogonal components }{ \sstdescription{ 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. } \sstsynopsis{ void astResolve( AstFrame $*$this, const double point1[], const double point2[], const double point3[], double point4[], double $*$d1, double $*$d2 ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{Frame}{Frame}. } \sstsubsection{ point1 }{ An array of double, with one element for each Frame axis (\htmlref{Naxes}{Naxes} attribute). This marks the start of the basis vector, and of the vector to be resolved. } \sstsubsection{ point2 }{ An array of double, with one element for each Frame axis (Naxes attribute). This marks the end of the basis vector. } \sstsubsection{ point3 }{ An array of double, with one element for each Frame axis (Naxes attribute). This marks the end of the vector to be resolved. } \sstsubsection{ 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. } \sstsubsection{ 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. } \sstsubsection{ 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. } } \sstnotes{ \sstitemlist{ \sstitem Each vector used in this function is the path of shortest distance between two points, as defined by the \htmlref{astDistance}{astDistance} function. \sstitem This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) if any of the input coordinates has this value, or if the required output values are undefined. } } } \sstroutine{ astRetainFits }{ Indicate that the current card in a FitsChan should be retained }{ \sstdescription{ This function stores a flag with the current card in the \htmlref{FitsChan}{FitsChan} indicating that the card should not be removed from the FitsChan when an \htmlref{Object}{Object} is read from the FitsChan using \htmlref{astRead}{astRead}. Cards that have not been flagged in this way are removed when a read operation completes succesfully, but only if the card was used in the process of creating the returned AST Object. Any cards that are irrelevant to the creation of the AST Object are retained whether or not they are flagged. } \sstsynopsis{ void astRetainFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem This function returns without action if the FitsChan is initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the \htmlref{Card}{Card} attribute exceeds the number of cards in the FitsChan). \sstitem The current card is not changed by this function. } } } \sstroutine{ astSame }{ Test if two AST pointers refer to the same Object }{ \sstdescription{ This function returns a boolean result (0 or 1) to indicate whether two pointers refer to the same \htmlref{Object}{Object}. } \sstsynopsis{ int astSame( AstObject $*$this, AstObject $*$that ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the first Object. } \sstsubsection{ that }{ Pointer to the second Object. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astSame() }{ One if the two pointers refer to the same Object, otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem Two independent Objects that happen to be identical are not considered to be the same Object by this function. \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astSelectorMap }{ Create a SelectorMap }{ \sstdescription{ This function creates a new \htmlref{SelectorMap}{SelectorMap} and optionally initialises its attributes. A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains a given input position. A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation. For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation. If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{astSimplify}{astSimplify}. In practice, SelectorMaps are often used in conjunction with SwitchMaps. } \sstsynopsis{ AstSelectorMap $*$astSelectorMap( int nreg, AstRegion $*$regs[], double badval, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nreg }{ The number of supplied Regions. } \sstsubsection{ regs }{ An array of pointers to the Regions. All the supplied Regions must relate to the same coordinate Frame. The number of axes in this coordinate Frame defines the number of inputs for the SelectorMap. } \sstsubsection{ badval }{ The value to be returned by the forward transformation of the SelectorMap for any input positions that have a bad (AST\_\_BAD) value on any axis. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SelectorMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSelectorMap() }{ A pointer to the new SelectorMap. } } \sstnotes{ \sstitemlist{ \sstitem Deep copies are taken of the supplied Regions. This means that any subsequent changes made to the component Regions using the supplied pointers will have no effect on the SelectorMap. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSet }{ Set attribute values for an Object }{ \sstdescription{ This function assigns a set of attribute values to an \htmlref{Object}{Object}, over-riding any previous values. The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute\texttt{'} s data type. The string supplied may also contain \texttt{"} printf\texttt{"} -style format specifiers, identified by \texttt{"} \%\texttt{"} signs in the usual way. If present, these will be substituted by values supplied as additional optional arguments (using the normal \texttt{"} printf\texttt{"} rules) before the string is used. } \sstsynopsis{ void astSet( AstObject $*$this, const char $*$settings, ... ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ settings }{ Pointer to a null-terminated character string containing a comma-separated list of attribute settings in the form described above. } \sstsubsection{ ... }{ Optional additional arguments which supply values to be substituted for any \texttt{"} printf\texttt{"} -style format specifiers that appear in the \texttt{"} settings\texttt{"} string. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstexamples{ \sstexamplesubsection{ astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"} ); }{ Sets the Report attribute for Object \texttt{"} map\texttt{"} to the value 1 and the Zoom attribute to 25.0. } \sstexamplesubsection{ astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis ); }{ Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"} to a suitable string, where the axis number is obtained from \texttt{"} axis\texttt{"} , a variable of type int. } \sstexamplesubsection{ astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring ); }{ Sets the Title attribute for Object \texttt{"} frame\texttt{"} to the contents of the string \texttt{"} mystring\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned). \sstitem To include a literal comma in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes. Alternatively, you can use \texttt{"} \%s\texttt{"} format and supply the value as a separate additional argument to astSet (or use the astSetC function instead). \sstitem The same procedure may be adopted if \texttt{"} \%\texttt{"} signs are to be included and are not to be interpreted as format specifiers (alternatively, the \texttt{"} printf\texttt{"} convention of writing \texttt{"} \%\%\texttt{"} may be used). \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ astSet$<$X$>$ }{ Set an attribute value for an Object }{ \sstdescription{ This is a family of functions which set a specified attribute value for an \htmlref{Object}{Object} using one of several different data types. The type is selected by replacing $<$X$>$ in the function name by C, D, F, I or L, to supply a value in const char$*$ (i.e. string), double, float, int, or long format, respectively. If possible, the value you supply is converted to the type of the attribute. If conversion is not possible, an error will result. } \sstsynopsis{ void astSet$<$X$>$( AstObject $*$this, const char $*$attrib, $<$X$>$type value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ attrib }{ Pointer to a null-terminated character string containing the name of the attribute whose value is to be set. } \sstsubsection{ value }{ The value to be set for the attribute, in the data type corresponding to $<$X$>$ (or, in the case of astSetC, a pointer to a null-terminated character string containing this value). } } \sstapplicability{ \sstsubsection{ Object }{ These functions apply to all Objects. } } \sstexamples{ \sstexamplesubsection{ astSetI( frame, \texttt{"} Preserve\texttt{"} , 1 ); }{ Sets the Preserve attribute value for Object \texttt{"} frame\texttt{"} to 1. } \sstexamplesubsection{ astSetC( plot, \texttt{"} Format(1)\texttt{"} , \texttt{"} \%.2g\texttt{"} ); }{ Sets the Format(1) attribute value for Object \texttt{"} plot\texttt{"} to the character string \texttt{"} \%.2g\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem An error will result if an attempt is made to set a value for a read-only attribute. } } } \sstroutine{ astSetActiveUnit }{ Specify how the Unit attribute should be used }{ \sstdescription{ This function sets the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}, which controls how the Frame behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) to match another Frame. If the ActiveUnit flag is set in both template and target Frames then the returned \htmlref{Mapping}{Mapping} takes into account any differences in axis units. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0. If the ActiveUnit flag of either Frame is zero, then the Mapping will ignore any difference in the Unit attributes of corresponding template and target axes. In this mode, the Unit attributes are purely descriptive commentary for the benefit of human readers and do not influence the Mappings between Frames. This is the behaviour which all Frames had in older version of AST, prior to the introduction of this attribute. If the ActiveUnit flag of both Frames is non-zero, then the Mapping from template to target will take account of any difference in the axis Unit attributes, where-ever possible. For instance, if corresponding target and template axes have Unit strings of \texttt{"} km\texttt{"} and \texttt{"} m\texttt{"} , then the \htmlref{FrameSet}{FrameSet} class will use a \htmlref{ZoomMap}{ZoomMap} to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I \texttt{"} Representations of world coordinates in FITS\texttt{"} (Greisen \& Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus \texttt{"} flops\texttt{"} can be transformed to \texttt{"} Mflops\texttt{"} even though \texttt{"} flops\texttt{"} is not a standard FITS unit symbol). A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an \texttt{"} s\texttt{"} to the end of Angstrom, using a lower case \texttt{"} a\texttt{"} at the start of \texttt{"} angstrom\texttt{"} , \texttt{"} micron\texttt{"} instead of \texttt{"} um\texttt{"} , \texttt{"} sec\texttt{"} instead of \texttt{"} s\texttt{"} , etc. If the ActiveUnit flag is non-zero, setting a new Unit value for an axis may also change its Label and Symbol attributes. For instance, if an axis has Unit \texttt{"} Hz\texttt{"} and Label \texttt{"} frequency\texttt{"} , then changing its Unit to \texttt{"} log(Hz)\texttt{"} will change its Label to \texttt{"} log( frequency )\texttt{"} . In addition, the \htmlref{Axis}{Axis} Format attribute will be cleared when-ever a new value is assigned to the Unit attribute. Note, if a non-zero value is set for the ActiveUnit flag, then changing a Unit value for the current Frame within a FrameSet will result in the Frame being re-mapped (that is, the Mappings which define the relationships between Frames within the FrameSet will be modified to take into account the change in Units). } \sstsynopsis{ void astSetActiveUnit( AstFrame $*$this, int value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ value }{ The new value to use. } } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The ActiveUnit flag for a SkyFrame is always 0 (any value supplied using this function is ignored). } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The ActiveUnit flag for a SpecFrame is always 1 (any value supplied using this function is ignored). } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The ActiveUnit flag for a FluxFrame is always 1 (any value supplied using this function is ignored). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default ActiveUnit flag for a CmpFrame is 1 if both of the component Frames are using active units, and zero otherwise. When a new value is set for the ActiveUnit flag, the flag value is propagated to the component Frames. This change will be reflected through all references to the component Frames, not just those encapsulated within the CmpFrame. } \sstsubsection{ \htmlref{Region}{Region}: }{ Regions always use active units if possible. } } \sstnotes{ \sstitemlist{ \sstitem The ActiveUnit flag resembles a Frame attribute, except that it cannot be tested or cleared, and it cannot be accessed using the generic \htmlref{astGet$<$X$>$}{astGet$<$X$>$} and \htmlref{astSet$<$X$>$}{astSet$<$X$>$} functions. \sstitem The \htmlref{astGetActiveUnit}{astGetActiveUnit} function can be used to retrieve the current value of the ActiveUnit flag. } } } \sstroutine{ astSetFits$<$X$>$ }{ Store a keyword value in a FitsChan }{ \sstdescription{ This is a family of functions which store values for named keywords within a \htmlref{FitsChan}{FitsChan} at the current card position. The supplied keyword value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan. The keyword data type is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS data types: \sstitemlist{ \sstitem CF - Complex floating point values. \sstitem CI - Complex integer values. \sstitem F - Floating point values. \sstitem I - Integer values. \sstitem L - Logical (i.e. boolean) values. \sstitem S - String values. \sstitem CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but are encoded without an equals sign. } The data type of the \texttt{"} value\texttt{"} parameter depends on $<$X$>$ as follows: \sstitemlist{ \sstitem CF - \texttt{"} double $*$\texttt{"} (a pointer to a 2 element array holding the real and imaginary parts of the complex value). \sstitem CI - \texttt{"} int $*$\texttt{"} (a pointer to a 2 element array holding the real and imaginary parts of the complex value). \sstitem F - \texttt{"} double\texttt{"} . \sstitem I - \texttt{"} int\texttt{"} . \sstitem L - \texttt{"} int\texttt{"} . \sstitem S - \texttt{"} const char $*$\texttt{"} . \sstitem CN - \texttt{"} const char $*$\texttt{"} . } } \sstsynopsis{ void astSetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type value, const char $*$comment, int overwrite ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ name }{ Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ value }{ The keyword value to store with the named keyword. The data type of this parameter depends on $<$X$>$ as described above. } \sstsubsection{ comment }{ A pointer to a null terminated string holding a comment to associated with the keyword. If a NULL pointer or a blank string is supplied, then any comment included in the string supplied for the \texttt{"} name\texttt{"} parameter is used instead. If \texttt{"} name\texttt{"} contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. } \sstsubsection{ overwrite }{ If non-zero, the new card formed from the supplied keyword name, value and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } } \sstnotes{ \sstitemlist{ \sstitem The function \htmlref{astSetFitsU}{astSetFitsU} can be used to indicate that no value is associated with a keyword. \sstitem The function \htmlref{astSetFitsCM}{astSetFitsCM} can be used to store a pure comment card (i.e. a card with a blank keyword). \sstitem To assign a new value for an existing keyword within a FitsChan, first find the card describing the keyword using \htmlref{astFindFits}{astFindFits}, and then use one of the astSetFits$<$X$>$ family to over-write the old value. \sstitem If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem An error will be reported if the keyword name does not conform to FITS requirements. } } } \sstroutine{ astSetFitsCM }{ Store a comment card in a FitsChan }{ \sstdescription{ This function stores a comment card ( i.e. a card with no keyword name or equals sign) within a \htmlref{FitsChan}{FitsChan} at the current card position. The new card can either over-write an existing card, or can be inserted as a new card into the FitsChan. } \sstsynopsis{ void astSetFitsCM( AstFitsChan $*$this, const char $*$comment, int overwrite ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ comment }{ A pointer to a null terminated string holding the text of the comment card. If a NULL pointer or a blank string is supplied, then a totally blank card is produced. } \sstsubsection{ overwrite }{ If non-zero, the new card over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } } \sstnotes{ \sstitemlist{ \sstitem If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . } } } \sstroutine{ astSetFitsU }{ Store an undefined keyword value in a FitsChan }{ \sstdescription{ This function stores an undefined value for a named keyword within a \htmlref{FitsChan}{FitsChan} at the current card position. The new undefined value can either over-write an existing keyword value, or can be inserted as a new header card into the FitsChan. } \sstsynopsis{ void astSetFitsU( AstFitsChan $*$this, const char $*$name, const char $*$comment, int overwrite ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ name }{ Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ comment }{ A pointer to a null terminated string holding a comment to associated with the keyword. If a NULL pointer or a blank string is supplied, then any comment included in the string supplied for the \texttt{"} name\texttt{"} parameter is used instead. If \texttt{"} name\texttt{"} contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card. } \sstsubsection{ overwrite }{ If non-zero, the new card formed from the supplied keyword name and comment string over-writes the current card, and the current card is incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If zero, the new card is inserted in front of the current card and the current card is left unchanged. In either case, if the current card on entry points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of the list. } } \sstnotes{ \sstitemlist{ \sstitem If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . \sstitem An error will be reported if the keyword name does not conform to FITS requirements. } } } \sstroutine{ astSetRefPos }{ Set the reference position in a specified celestial coordinate system }{ \sstdescription{ This function sets the reference position (see attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) using axis values (in radians) supplied within the celestial coordinate system represented by a supplied \htmlref{SkyFrame}{SkyFrame}. } \sstsynopsis{ void astSetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double lon, double lat ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the \htmlref{SpecFrame}{SpecFrame}. } \sstsubsection{ frm }{ Pointer to the SkyFrame which defines the celestial coordinate system in which the longitude and latitude values are supplied. If NULL is supplied, then the supplied longitude and latitude values are assumed to be FK5 J2000 RA and Dec values. } \sstsubsection{ lon }{ The longitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } \sstsubsection{ lat }{ The latitude of the reference point, in the coordinate system represented by the supplied SkyFrame (radians). } } } \sstroutine{ astSetStatus }{ Set the AST error status to an explicit value }{ \sstdescription{ This function sets the AST error status to the value supplied. It does not cause any error message to be produced and should not be used as part of normal error reporting. Its purpose is simply to communicate to AST that an error has occurred in some other item of software. For example, a source or sink function supplied as an argument to \htmlref{astChannel}{astChannel} or \htmlref{astFitsChan}{astFitsChan} might use this to signal that an input/output error has occurred. AST could then respond by terminating the current read or write operation. } \sstsynopsis{ void astSetStatus( int status\_value ) } \sstparameters{ \sstsubsection{ status\_value }{ The new error status value to be set. } } \sstnotes{ \sstitemlist{ \sstitem If the AST error status is set to an error value, most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use \htmlref{astClearStatus}{astClearStatus}. } } } \sstroutine{ astSetUnc }{ Store uncertainty information in a Region }{ \sstdescription{ Each \htmlref{Region}{Region} (of any class) can have an \texttt{"} uncertainty\texttt{"} which specifies the uncertainties associated with the boundary of the Region. This information is supplied in the form of a second Region. The uncertainty in any point on the boundary of a Region is found by shifting the associated \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points. The uncertainty is usually specified when the Region is created, but this function allows it to be changed at any time. } \sstsynopsis{ void astSetUnc( AstRegion $*$this, AstRegion $*$unc ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region which is to be assigned a new uncertainty. } \sstsubsection{ unc }{ Pointer to the new uncertainty Region. This must be of a class for which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the Region \texttt{"} this\texttt{"} . } } } \sstroutine{ astShiftMap }{ Create a ShiftMap }{ \sstdescription{ This function creates a new \htmlref{ShiftMap}{ShiftMap} and optionally initialises its attributes. A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a specified constant value. } \sstsynopsis{ AstShiftMap $*$astShiftMap( int ncoord, const double shift[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ shift }{ An array containing the values to be added on to the input coordinates in order to create the output coordinates. A separate value should be supplied for each coordinate. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ShiftMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astShiftMap() }{ A pointer to the new ShiftMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astShow }{ Display a textual representation of an Object on standard output }{ \sstdescription{ This function displays a textual description of any AST \htmlref{Object}{Object} on standard output. It is provided primarily as an aid to debugging. } \sstsynopsis{ void astShow( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be displayed. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } } \sstroutine{ astShowFits }{ Display the contents of a FitsChan on standard output }{ \sstdescription{ This function formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output. } \sstsynopsis{ void astShowFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } } \sstroutine{ astShowMesh }{ Display a mesh of points covering the surface of a Region }{ \sstdescription{ This function writes a table to standard output containing the axis values at a mesh of points covering the surface of the supplied \htmlref{Region}{Region}. Each row of output contains a tab-separated list of axis values, one for each axis in the \htmlref{Frame}{Frame} encapsulated by the Region. The number of points in the mesh is determined by the \htmlref{MeshSize}{MeshSize} attribute. The table is preceded by a given title string, and followed by a single line containing the word \texttt{"} ENDMESH\texttt{"} . } \sstsynopsis{ void astShowMesh( AstRegion $*$this, int format, const char $*$ttl ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Region. } \sstsubsection{ format }{ A boolean value indicating if the displayed axis values should be formatted according to the Format attribute associated with the Frame\texttt{'} s axis. Otherwise, they are displayed as simple floating point values. } \sstsubsection{ ttl }{ A title to display before displaying the first position. } } } \sstroutine{ astSimplify }{ Simplify a Mapping }{ \sstdescription{ This function simplifies a \htmlref{Mapping}{Mapping} (which may be a compound Mapping such as a \htmlref{CmpMap}{CmpMap}) to eliminate redundant computational steps, or to merge separate steps which can be performed more efficiently in a single operation. As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation. This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates. } \sstsynopsis{ AstMapping $*$astSimplify( AstMapping $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the original Mapping. } } \sstapplicability{ \sstsubsection{ Mapping }{ This function applies to all Mappings. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ If the supplied Mapping is a FrameSet, the returned Mapping will be a copy of the supplied FrameSet in which all the inter-\htmlref{Frame}{Frame} Mappings have been simplified. } } \sstreturnedvalue{ \sstsubsection{ astSimplify() }{ A new pointer to the (possibly simplified) Mapping. } } \sstnotes{ \sstitemlist{ \sstitem Mappings that have a set value for their \htmlref{Ident}{Ident} attribute are left unchanged after simplification. This is so that their individual identity is preserved. This restriction does not apply to the simplification of Frames. \sstitem This function can safely be applied even to Mappings which cannot be simplified. If no simplification is possible, it behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the original Mapping. \sstitem The Mapping returned by this function may not be independent of the original (even if simplification was possible), and modifying it may therefore result in indirect modification of the original. If a completely independent result is required, a copy should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSkyFrame }{ Create a SkyFrame }{ \sstdescription{ This function creates a new \htmlref{SkyFrame}{SkyFrame} and optionally initialises its attributes. A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or an \htmlref{Epoch}{Epoch}. For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs} and SkyRefP All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using \htmlref{astFormat}{astFormat}. } \sstsynopsis{ AstSkyFrame $*$astSkyFrame( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SkyFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSkyFrame() }{ A pointer to the new SkyFrame. } } \sstexamples{ \sstexamplesubsection{ frame = astSkyFrame( \texttt{"} \texttt{"} ); }{ Creates a SkyFrame to describe the default ICRS celestial coordinate system. } \sstexamplesubsection{ frame = astSkyFrame( \texttt{"} System = FK5, Equinox = J2005, Digits = 10\texttt{"} ); }{ Creates a SkyFrame to describe the FK5 celestial coordinate system, with a mean Equinox of J2005.0. Because especially accurate coordinates will be used, additional precision (10 digits) has been requested. This will be used when coordinate values are formatted for display. } \sstexamplesubsection{ frame = astSkyFrame( \texttt{"} System = FK4, Equinox = 1955-sep-2\texttt{"} ); }{ Creates a SkyFrame to describe the old FK4 celestial coordinate system. A default Epoch value (B1950.0) is used, but the mean Equinox value is given explicitly as \texttt{"} 1955-sep-2\texttt{"} . } \sstexamplesubsection{ frame = astSkyFrame( \texttt{"} System = GAPPT, Epoch = \%s\texttt{"} , date ); }{ Creates a SkyFrame to describe the Geocentric Apparent celestial coordinate system. The Epoch value, which specifies the date of observation, is obtained from a date/time string supplied via the string pointer \texttt{"} date\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem Currently, the default celestial coordinate system is ICRS. However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in behaviour with future versions of this function). If you intend to use the ICRS system indefinitely, then you should specify it explicitly using an \texttt{"} options\texttt{"} value of \texttt{"} System=ICRS\texttt{"} . \sstitem Whichever celestial coordinate system is represented, it will have two axes. The first of these will be the longitude axis and the second will be the latitude axis. This order can be changed using \htmlref{astPermAxes}{astPermAxes} if required. \sstitem When conversion between two SkyFrames is requested (as when supplying SkyFrames to \htmlref{astConvert}{astConvert}), account will be taken of the nature of the celestial coordinate systems they represent, together with any qualifying mean Equinox or Epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} attribute will also be taken into account. The results will therefore fully reflect the relationship between positions on the sky measured in the two systems. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSkyOffsetMap }{ Returns a Mapping which goes from absolute coordinates to offset coordinates }{ \sstdescription{ This function returns a \htmlref{Mapping}{Mapping} in which the forward transformation transforms a position in the coordinate system given by the \htmlref{System}{System} attribute of the supplied \htmlref{SkyFrame}{SkyFrame}, into the offset coordinate system specified by the SkyRef, SkyRefP and \htmlref{SkyRefIs}{SkyRefIs} attributes of the supplied SkyFrame. A \htmlref{UnitMap}{UnitMap} is returned if the SkyFrame does not define an offset coordinate system. } \sstsynopsis{ AstMapping $*$astSkyOffsetMap( AstSkyFrame $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the SkyFrame. } } \sstreturnedvalue{ \sstsubsection{ astSkyOffsetMap() }{ Pointer to the returned Mapping. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSlaAdd }{ Add a celestial coordinate conversion to an SlaMap }{ \sstdescription{ This function adds one of the standard celestial coordinate system conversions provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67) to an existing \htmlref{SlaMap}{SlaMap}. When an SlaMap is first created (using \htmlref{astSlaMap}{astSlaMap}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSlaAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SlaMap will perform in sequence. This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. Normally, if an SlaMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSlaAdd in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the SlaMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SlaMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstsynopsis{ void astSlaAdd( AstSlaMap $*$this, const char $*$cvt, const double args[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the SlaMap. } \sstsubsection{ cvt }{ Pointer to a null-terminated string which identifies the celestial coordinate conversion to be added to the SlaMap. See the \texttt{"} SLALIB Conversions\texttt{"} section for details of those available. } \sstsubsection{ args }{ An array containing argument values for the celestial coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} SLALIB Conversions\texttt{"} section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. } } \sstnotes{ \sstitemlist{ \sstitem All coordinate values processed by an SlaMap are in radians. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude. \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, converting to the standard FK5 coordinate system as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting SlaMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This function does not check to ensure that the sequence of coordinate conversions added to an SlaMap is physically meaningful. } } \sstdiytopic{ SLALIB Conversions }{ The following strings (which are case-insensitive) may be supplied via the \texttt{"} cvt\texttt{"} parameter to indicate which celestial coordinate conversion is to be added to the SlaMap. Each string is derived from the name of the SLALIB routine that performs the conversion and the relevant documentation (SUN/67) should be consulted for details. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the \texttt{"} args\texttt{"} array, in the order indicated. The argument names match the corresponding SLALIB routine arguments and their values should be given using exactly the same units, time scale, calendar, etc. as described in SUN/67: \sstitemlist{ \sstitem \texttt{"} ADDET\texttt{"} (EQ): Add E-terms of aberration. \sstitem \texttt{"} SUBET\texttt{"} (EQ): Subtract E-terms of aberration. \sstitem \texttt{"} PREBN\texttt{"} (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4) precession model. \sstitem \texttt{"} PREC\texttt{"} (EP0,EP1): Apply IAU 1975 (FK5) precession model. \sstitem \texttt{"} FK45Z\texttt{"} (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax). \sstitem \texttt{"} FK54Z\texttt{"} (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax). \sstitem \texttt{"} AMP\texttt{"} (DATE,EQ): Convert geocentric apparent to mean place. \sstitem \texttt{"} MAP\texttt{"} (EQ,DATE): Convert mean place to geocentric apparent. \sstitem \texttt{"} ECLEQ\texttt{"} (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} EQECL\texttt{"} (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates. \sstitem \texttt{"} GALEQ\texttt{"} : Convert galactic coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} EQGAL\texttt{"} : Convert FK5 J2000.0 equatorial to galactic coordinates. \sstitem \texttt{"} HFK5Z\texttt{"} (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial. \sstitem \texttt{"} FK5HZ\texttt{"} (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS. \sstitem \texttt{"} GALSUP\texttt{"} : Convert galactic to supergalactic coordinates. \sstitem \texttt{"} SUPGAL\texttt{"} : Convert supergalactic coordinates to galactic. \sstitem \texttt{"} J2000H\texttt{"} : Convert dynamical J2000.0 to ICRS. \sstitem \texttt{"} HJ2000\texttt{"} : Convert ICRS to dynamical J2000.0. \sstitem \texttt{"} R2H\texttt{"} (LAST): Convert RA to Hour Angle. \sstitem \texttt{"} H2R\texttt{"} (LAST): Convert Hour Angle to RA. } For example, to use the \texttt{"} ADDET\texttt{"} conversion, which takes a single argument EQ, you should consult the documentation for the SLALIB routine SLA\_ADDET. This describes the conversion in detail and shows that EQ is the Besselian epoch of the mean equator and equinox. This value should then be supplied to astSlaAdd in args[0]. In addition the following strings may be supplied for more complex conversions which do not correspond to any one single SLALIB routine (DIURAB is the magnitude of the diurnal aberration vector in units of \texttt{"} day/(2.PI)\texttt{"} , DATE is the Modified Julian Date of the observation, and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian coordinates, in metres, of the observer): \sstitemlist{ \sstitem \texttt{"} HPCEQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHPC\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian. \sstitem \texttt{"} HPREQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHPR\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial. \sstitem \texttt{"} HEEQ\texttt{"} (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial. \sstitem \texttt{"} EQHE\texttt{"} (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic. \sstitem \texttt{"} H2E\texttt{"} (LAT,DIRUAB): Convert horizon coordinates to equatorial. \sstitem \texttt{"} E2H\texttt{"} (LAT,DIURAB): Convert equatorial coordinates to horizon. } Note, the \texttt{"} H2E\texttt{"} and \texttt{"} E2H\texttt{"} conversions convert between topocentric horizon coordinates (azimuth,elevation), and apparent local equatorial coordinates (hour angle,declination). Thus, the effects of diurnal aberration are taken into account in the conversions but the effects of atmospheric refraction are not. } } \sstroutine{ astSlaMap }{ Create an SlaMap }{ \sstdescription{ This function creates a new \htmlref{SlaMap}{SlaMap} and optionally initialises its attributes. An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems. When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd} function, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. For details of the individual coordinate conversions available, see the description of the astSlaAdd function. } \sstsynopsis{ AstSlaMap $*$astSlaMap( int flags, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ flags }{ This parameter is reserved for future use and should currently always be set to zero. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SlaMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSlaMap() }{ A pointer to the new SlaMap. } } \sstnotes{ \sstitemlist{ \sstitem The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes (number of input and output coordinates) for an SlaMap are both equal to 2. The first coordinate is the celestial longitude and the second coordinate is the celestial latitude. All coordinate values are in radians. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSpecAdd }{ Add a spectral coordinate conversion to a SpecMap }{ \sstdescription{ This function adds one of the standard spectral coordinate system conversions listed below to an existing \htmlref{SpecMap}{SpecMap}. When a SpecMap is first created (using \htmlref{astSpecMap}{astSpecMap}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSpecAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the SpecMap will perform in sequence. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class. Normally, if a SpecMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astSpecAdd in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the SpecMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the SpecMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstsynopsis{ void astSpecAdd( AstSpecMap $*$this, const char $*$cvt, const double args[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the SpecMap. } \sstsubsection{ cvt }{ Pointer to a null-terminated string which identifies the spectral coordinate conversion to be added to the SpecMap. See the \texttt{"} Available Conversions\texttt{"} section for details of those available. } \sstsubsection{ args }{ An array containing argument values for the spectral coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} Available Conversions\texttt{"} section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. } } \sstnotes{ \sstitemlist{ \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. For example, when converting between reference frames, converting first to the heliographic reference frame as an intermediate stage is often sensible in formulating the problem, but may introduce unnecessary extra conversion steps. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting SpecMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This function does not check to ensure that the sequence of coordinate conversions added to a SpecMap is physically meaningful. } } \sstdiytopic{ Available Conversions }{ The following strings (which are case-insensitive) may be supplied via the \texttt{"} cvt\texttt{"} parameter to indicate which spectral coordinate conversion is to be added to the SpecMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the \texttt{"} args\texttt{"} array, in the order indicated. Units and argument names are described at the end of the list of conversions. \sstitemlist{ \sstitem \texttt{"} FRTOVL\texttt{"} (RF): Convert frequency to relativistic velocity. \sstitem \texttt{"} VLTOFR\texttt{"} (RF): Convert relativistic velocity to Frequency. \sstitem \texttt{"} ENTOFR\texttt{"} : Convert energy to frequency. \sstitem \texttt{"} FRTOEN\texttt{"} : Convert frequency to energy. \sstitem \texttt{"} WNTOFR\texttt{"} : Convert wave number to frequency. \sstitem \texttt{"} FRTOWN\texttt{"} : Convert frequency to wave number. \sstitem \texttt{"} WVTOFR\texttt{"} : Convert wavelength (vacuum) to frequency. \sstitem \texttt{"} FRTOWV\texttt{"} : Convert frequency to wavelength (vacuum). \sstitem \texttt{"} AWTOFR\texttt{"} : Convert wavelength (air) to frequency. \sstitem \texttt{"} FRTOAW\texttt{"} : Convert frequency to wavelength (air). \sstitem \texttt{"} VRTOVL\texttt{"} : Convert radio to relativistic velocity. \sstitem \texttt{"} VLTOVR\texttt{"} : Convert relativistic to radio velocity. \sstitem \texttt{"} VOTOVL\texttt{"} : Convert optical to relativistic velocity. \sstitem \texttt{"} VLTOVO\texttt{"} : Convert relativistic to optical velocity. \sstitem \texttt{"} ZOTOVL\texttt{"} : Convert redshift to relativistic velocity. \sstitem \texttt{"} VLTOZO\texttt{"} : Convert relativistic velocity to redshift. \sstitem \texttt{"} BTTOVL\texttt{"} : Convert beta factor to relativistic velocity. \sstitem \texttt{"} VLTOBT\texttt{"} : Convert relativistic velocity to beta factor. \sstitem \texttt{"} USF2HL\texttt{"} (VOFF,RA,DEC): Convert frequency from a user-defined reference frame to heliocentric. \sstitem \texttt{"} HLF2US\texttt{"} (VOFF,RA,DEC): Convert frequency from heliocentric reference frame to user-defined. \sstitem \texttt{"} TPF2HL\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from topocentric reference frame to heliocentric. \sstitem \texttt{"} HLF2TP\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to topocentric. \sstitem \texttt{"} GEF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from geocentric reference frame to heliocentric. \sstitem \texttt{"} HLF2GE\texttt{"} (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to geocentric. \sstitem \texttt{"} BYF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from barycentric reference frame to heliocentric. \sstitem \texttt{"} HLF2BY\texttt{"} (EPOCH,RA,DEC): Convert frequency from heliocentric reference frame to barycentric. \sstitem \texttt{"} LKF2HL\texttt{"} (RA,DEC): Convert frequency from kinematic LSR reference frame to heliocentric. \sstitem \texttt{"} HLF2LK\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to kinematic LSR. \sstitem \texttt{"} LDF2HL\texttt{"} (RA,DEC): Convert frequency from dynamical LSR reference frame to heliocentric. \sstitem \texttt{"} HLF2LD\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to dynamical LSR. \sstitem \texttt{"} LGF2HL\texttt{"} (RA,DEC): Convert frequency from local group reference frame to heliocentric. \sstitem \texttt{"} HLF2LG\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to local group. \sstitem \texttt{"} GLF2HL\texttt{"} (RA,DEC): Convert frequency from galactic reference frame to heliocentric. \sstitem \texttt{"} HLF2GL\texttt{"} (RA,DEC): Convert frequency from heliocentric reference frame to galactic. } The units for the values processed by the above conversions are as follows: \sstitemlist{ \sstitem all velocities: metres per second (positive if the source receeds from the observer). \sstitem frequency: Hertz. \sstitem all wavelengths: metres. \sstitem energy: Joules. \sstitem wave number: cycles per metre. } The arguments used in the above conversions are as follows: \sstitemlist{ \sstitem RF: Rest frequency (Hz). \sstitem OBSALT: Geodetic altitude of observer (IAU 1975, metres). \sstitem OBSLAT: Geodetic latitude of observer (IAU 1975, radians). \sstitem OBSLON: Longitude of observer (radians - positive eastwards). \sstitem EPOCH: \htmlref{Epoch}{Epoch} of observation (UT1 expressed as a Modified Julian Date). \sstitem RA: Right Ascension of source (radians, FK5 J2000). \sstitem DEC: Declination of source (radians, FK5 J2000). \sstitem VOFF: Velocity of the user-defined reference frame, towards the position given by RA and DEC, measured in the heliocentric reference frame. } If the SpecMap is 3-dimensional, source positions are provided by the values supplied to inputs 2 and 3 of the SpecMap (which are simply copied to outputs 2 and 3). Note, usable values are still required for the RA and DEC arguments in order to define the \texttt{"} user-defined\texttt{"} reference frame used by USF2HL and HLF2US. However, AST\_\_BAD can be supplied for RA and DEC if the user-defined reference frame is not required. } } \sstroutine{ astSpecFluxFrame }{ Create a SpecFluxFrame }{ \sstdescription{ This function creates a new \htmlref{SpecFluxFrame}{SpecFluxFrame} and optionally initialises its attributes. A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents spectral position and the second axis represents flux. } \sstsynopsis{ AstSpecFluxFrame $*$astSpecFluxFrame( AstSpecFrame $*$frame1, AstFluxFrame $*$frame2, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ frame1 }{ Pointer to the SpecFrame. This will form the first axis in the new SpecFluxFrame. } \sstsubsection{ frame2 }{ Pointer to the FluxFrame. This will form the second axis in the new SpecFluxFrame. The \texttt{"} \htmlref{SpecVal}{SpecVal}\texttt{"} attribute of this FluxFrame is not used by the SpecFluxFrame class and so may be set to AST\_\_BAD when the FluxFrame is created. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFluxFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSpecFluxFrame() }{ A pointer to the new SpecFluxFrame. } } \sstnotes{ \sstitemlist{ \sstitem The supplied Frame pointers are stored directly, rather than being used to create deep copies of the supplied Frames. This means that any subsequent changes made to the Frames via the supplied pointers will result in equivalent changes being visible in the SpecFluxFrame. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astSpecFrame }{ Create a SpecFrame }{ \sstdescription{ This function creates a new \htmlref{SpecFrame}{SpecFrame} and optionally initialises its attributes. A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, etc (see the description of the System attribute for details). By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute } \sstsynopsis{ AstSpecFrame $*$astSpecFrame( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSpecFrame() }{ A pointer to the new SpecFrame. } } \sstexamples{ \sstexamplesubsection{ frame = astSpecFrame( \texttt{"} \texttt{"} ); }{ Creates a SpecFrame to describe the default wavelength spectral coordinate system. The \htmlref{RestFreq}{RestFreq} attribute (rest frequency) is unspecified, so it will not be possible to align this SpecFrame with another SpecFrame on the basis of a velocity-based system. The standard of rest is also unspecified. This means that alignment will be possible with other SpecFrames, but no correction will be made for Doppler shift caused by change of rest frame during the alignment. } \sstexamplesubsection{ frame = astSpecFrame( \texttt{"} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{"} ); }{ Creates a SpecFrame describing a apparent radial velocity (\texttt{"} VELO\texttt{"} ) axis with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured in the kinematic Local Standard of Rest (\texttt{"} LSRK\texttt{"} ). Since the source position has not been specified (using attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}), it will only be possible to align this SpecFrame with other SpecFrames which are also measured in the LSRK standard of rest. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two SpecFrames is requested (as when supplying SpecFrames to \htmlref{astConvert}{astConvert}), account will be taken of the nature of the spectral coordinate systems they represent, together with any qualifying rest frequency, standard of rest, epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest} attributes will also be taken into account. The results will therefore fully reflect the relationship between positions measured in the two systems. In addition, any difference in the Unit attributes of the two systems will also be taken into account. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSpecMap }{ Create a SpecMap }{ \sstdescription{ This function creates a new \htmlref{SpecMap}{SpecMap} and optionally initialises its attributes. An SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard spectral coordinate systems. This includes conversions between frequency, wavelength, and various forms of velocity, as well as conversions between different standards of rest. When a SpecMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} function, a series of coordinate conversion steps may then be added, selected from the list of supported conversions. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of the building blocks provided by this class. For details of the individual coordinate conversions available, see the description of the astSpecAdd function. Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output). } \sstsynopsis{ AstSpecMap $*$astSpecMap( int nin, int flags, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ nin }{ The number of inputs to the Mapping (this will also equal the number of outputs). This value must be either 1 or 3. In either case, the first input and output correspoindis the spectral axis. For a 3-axis SpecMap, the second and third axes give the RA and DEC (J2000 FK5) of the source. This positional information is used by conversions which transform between standards of rest, and replaces the \texttt{"} RA\texttt{"} and \texttt{"} DEC\texttt{"} arguments for the individual conversions listed in description of the \texttt{"} SpecAdd\texttt{"} function. } \sstsubsection{ flags }{ This parameter is reserved for future use and should currently always be set to zero. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SpecMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSpecMap() }{ A pointer to the new SpecMap. } } \sstnotes{ \sstitemlist{ \sstitem The nature and units of the coordinate values supplied for the first input (i.e. the spectral input) of a SpecMap must be appropriate to the first conversion step applied by the SpecMap. For instance, if the first conversion step is \texttt{"} FRTOVL\texttt{"} (frequency to relativistic velocity), then the coordinate values for the first input should be frequency in units of Hz. Similarly, the nature and units of the coordinate values returned by a SpecMap will be determined by the last conversion step applied by the SpecMap. For instance, if the last conversion step is \texttt{"} VLTOVO\texttt{"} (relativistic velocity to optical velocity), then the coordinate values for the first output will be optical velocity in units of metres per second. See the description of the astSpecAdd function for the units expected and returned by each conversion. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astSphMap }{ Create a SphMap }{ \sstdescription{ This function creates a new \htmlref{SphMap}{SphMap} and optionally initialises its attributes. A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors). } \sstsynopsis{ AstSphMap $*$astSphMap( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SphMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSphMap() }{ A pointer to the new SphMap. } } \sstnotes{ \sstitemlist{ \sstitem The spherical coordinates are longitude (positive anti-clockwise looking from the positive latitude pole) and latitude. The Cartesian coordinates are right-handed, with the x axis (axis 1) at zero longitude and latitude, and the z axis (axis 3) at the positive latitude pole. \sstitem At either pole, the longitude is set to the value of the \htmlref{PolarLong}{PolarLong} attribute. \sstitem If the Cartesian coordinates are all zero, then the longitude and latitude are set to the value AST\_\_BAD. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astStatus }{ Obtain the current AST error status value }{ \sstdescription{ This function returns the current value of the AST error status. } \sstsynopsis{ int astStatus } \sstreturnedvalue{ \sstsubsection{ astStatus }{ The AST error status value. } } \sstnotes{ \sstitemlist{ \sstitem If the AST error status is set to an error value (after an error), most AST functions will not execute and will simply return without action. To clear the error status and restore normal behaviour, use \htmlref{astClearStatus}{astClearStatus}. } } } \sstroutine{ astStcCatalogEntryLocation }{ Create a StcCatalogEntryLocation }{ \sstdescription{ This function creates a new \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} and optionally initialises its attributes. The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstsynopsis{ AstStcCatalogEntryLocation $*$astStcCatalogEntryLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ ncoords }{ The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. } \sstsubsection{ coords }{ Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by \texttt{"} region\texttt{"} . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by \texttt{"} region\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcCatalogEntryLocation. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astStcCatalogEntryLocation() }{ A pointer to the new StcCatalogEntryLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astStcObsDataLocation }{ Create a StcObsDataLocation }{ \sstdescription{ This function creates a new \htmlref{StcObsDataLocation}{StcObsDataLocation} and optionally initialises its attributes. The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstsynopsis{ AstStcObsDataLocation $*$astStcObsDataLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ ncoords }{ The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. } \sstsubsection{ coords }{ Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by \texttt{"} region\texttt{"} . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by \texttt{"} region\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcObsDataLocation. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astStcObsDataLocation() }{ A pointer to the new StcObsDataLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astStcResourceProfile }{ Create a StcResourceProfile }{ \sstdescription{ This function creates a new \htmlref{StcResourceProfile}{StcResourceProfile} and optionally initialises its attributes. The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstsynopsis{ AstStcResourceProfile $*$astStcResourceProfile( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ ncoords }{ The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. } \sstsubsection{ coords }{ Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by \texttt{"} region\texttt{"} . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by \texttt{"} region\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcResourceProfile. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astStcResourceProfile() }{ A pointer to the new StcResourceProfile. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astStcSearchLocation }{ Create a StcSearchLocation }{ \sstdescription{ This function creates a new \htmlref{StcSearchLocation}{StcSearchLocation} and optionally initialises its attributes. The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of a VO query. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstsynopsis{ AstStcResourceProfile $*$astStcSearchLocation( AstRegion $*$region, int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ region }{ Pointer to the encapsulated \htmlref{Region}{Region}. } \sstsubsection{ ncoords }{ The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. } \sstsubsection{ coords }{ Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} describes the contents of a single STC $<$AstroCoords$>$ element, and should have elements with keys given by constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other elements should be included. If supplied, the AST\_\_STCNAME element should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} item for each axis in the coordinate system represented by \texttt{"} region\texttt{"} . Any other supplied elements should be scalar elements, each holding a pointer to a Region describing the associated item of ancillary information (error, resolution, size, pixel size or value). These Regions should describe a volume within the coordinate system represented by \texttt{"} region\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcSearchLocation. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astStcSearchLocation() }{ A pointer to the new StcSearchLocation. } } \sstnotes{ \sstitemlist{ \sstitem A deep copy is taken of the supplied Region. This means that any subsequent changes made to the encapsulated Region using the supplied pointer will have no effect on the Stc. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astStcsChan }{ Create an StcsChan }{ \sstdescription{ This function creates a new \htmlref{StcsChan}{StcsChan} and optionally initialises its attributes. A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description. Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output. Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstsynopsis{ AstStcsChan $*$astStcsChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) } \sstparameters{ \sstsubsection{ source }{ Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the StcsChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read. If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile attribute, the StcsChan will read from standard input instead. } \sstsubsection{ sink }{ Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the StcsChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store. If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile attribute, the StcsChan will write to standard output instead. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new StcsChan. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astStcsChan() }{ A pointer to the new StcsChan. } } \sstnotes{ \sstitemlist{ \sstitem If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST. \sstitem 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. } } } \sstroutine{ astStripEscapes }{ Remove AST escape sequences from a string }{ \sstdescription{ This function removes AST escape sequences from a supplied string, returning the resulting text as the function value. The behaviour of this function can be controlled by invoking the \htmlref{astEscapes}{astEscapes} function, which can be used to supress or enable the removal of escape sequences by this function. AST escape sequences are used by the \htmlref{Plot}{Plot} class to modify the appearance and position of sub-strings within a plotted text string. See the \texttt{"} \htmlref{Escape}{Escape}\texttt{"} attribute for further information. } \sstsynopsis{ const char $*$astStripEscapes( const char $*$text ) } \sstparameters{ \sstsubsection{ text }{ Pointer to the string to be checked. } } \sstreturnedvalue{ \sstsubsection{ astStripEscapes() }{ Pointer to the modified string. If no escape sequences were found in the supplied string, then a copy of the supplied pointer is returned. Otherwise, the pointer will point to a static buffer holding the modified text. This text will be over-written by subsequent invocations of this function. If the astEscapes function has been called indicating that escape sequences should not be stripped, then the supplied string is returned without change. } } } \sstroutine{ astSwitchMap }{ Create a SwitchMap }{ \sstdescription{ This function creates a new \htmlref{SwitchMap}{SwitchMap} and optionally initialises its attributes. A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap. A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input. When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST\_\_BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position. When the SwitchMap is used to transform a position in the inverse direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is set to a value of AST\_\_BAD on every axis. In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly appropriate for this purpose. If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{astSimplify}{astSimplify}. } \sstsynopsis{ AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap, int nroute, AstMapping $*$routemaps[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ fsmap }{ Pointer to the forward selector Mapping. This must have a defined forward transformation, but need not have a defined inverse transformation. It must have one output, and the number of inputs must match the number of inputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined forward Mapping. } \sstsubsection{ ismap }{ Pointer to the inverse selector Mapping. This must have a defined inverse transformation, but need not have a defined forward transformation. It must have one input, and the number of outputs must match the number of outputs of each of the supplied route Mappings. NULL may be supplied, in which case the SwitchMap will have an undefined inverse Mapping. } \sstsubsection{ nroute }{ The number of supplied route Mappings. } \sstsubsection{ routemaps }{ An array of pointers to the route Mappings. All the supplied route Mappings must have common values for the Nin and Nout attributes, and these values define the number of inputs and outputs of the SwitchMap. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new SwitchMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astSwitchMap() }{ A pointer to the new SwitchMap. } } \sstnotes{ \sstitemlist{ \sstitem Note that the component Mappings supplied are not copied by astSwitchMap (the new SwitchMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a SwitchMap containing a copy of its component Mappings is required, then a copy of the SwitchMap should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astTable }{ Create a Table }{ \sstdescription{ This function creates a new empty \htmlref{Table}{Table} and optionally initialises its attributes. The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional table of values. The astMapGet... and astMapPut... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the name of a table column and \texttt{"} i\texttt{"} is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table. Columns must be declared using the \htmlref{astAddColumn}{astAddColumn} method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape (specified when the column is declared). Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the \htmlref{astAddParameter}{astAddParameter} method before being accessed. Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables. } \sstsynopsis{ AstTable $*$astTable( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Table. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astTable() }{ A pointer to the new Table. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astTableSource }{ Register a source function for accessing tables in FITS files }{ \sstdescription{ This function can be used to register a call-back function with a \htmlref{FitsChan}{FitsChan}. The registered function is called when-ever the FitsChan needs to read information from a binary table contained within a FITS file. This occurs if the \htmlref{astRead}{astRead} function is invoked to read a \htmlref{FrameSet}{FrameSet} from a set of FITS headers that use the \texttt{"} -TAB\texttt{"} algorithm to describe one or more axes. Such axes use a FITS binary table to store a look-up table of axis values. The FitsChan will fail to read such axes unless the \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute is set to a non-zero positive integer value. The table containing the axis values must be made available to the FitsChan either by storing the table contents in the FitsChan (using \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) prior to invoking astRead or by registering a call-back function using astTableSource. The first method is possibly simpler, but requires that the name of the extension containing the table be known in advance. Since the table name is embedded in the FITS headers, the name is often not known in advance. If a call-back is registered, the FitsChan will determine the name of the required table and invoke the call-back function to supply the table at the point where it is needed (i.e. within the astRead method). } \sstsynopsis{ void astTableSource( AstFitsChan $*$this, void ($*$ tabsource)( AstFitsChan $*$, const char $*$, int, int, int $*$ ) ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ tabsource }{ Pointer to the table source function to use. It takes five arguments - the first is a pointer to the FitsChan, the second is a string holding the name of the FITS extension containing the required binary table (\texttt{"} EXTNAME\texttt{"} ), the third is the integer FITS \texttt{"} EXTVER\texttt{"} header value for the required extension, the fourth is the integer FITS \texttt{"} EXTLEVEL\texttt{"} header value for the required extension, and the fifth is a pointer to the inherited integer status value. The call-back should read the entire contents (header and data) of the binary table in the named extension of the external FITS file, storing the contents in a newly created \htmlref{FitsTable}{FitsTable} object. It should then store this FitsTable in the FitsChan using the astPutTables or astPutTable method, and finally annull its local copy of the FitsTable pointer. If the table cannot be read for any reason, or if any other error occurs, it should return a non-zero integer for the final (third) argument. If \texttt{"} tabsource\texttt{"} is NULL, any registered call-back function will be removed. } } \sstnotes{ \sstitemlist{ \sstitem Application code can pass arbitrary data (such as file descriptors, etc) to the table source function using the \htmlref{astPutChannelData}{astPutChannelData} function. The source function should use the \htmlref{astChannelData}{astChannelData} macro to retrieve this data. } } } \sstroutine{ astTest }{ Test if an Object attribute value is set }{ \sstdescription{ This function returns a boolean result (0 or 1) to indicate whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s attributes. } \sstsynopsis{ int astTest( AstObject $*$this, const char $*$attrib ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object. } \sstsubsection{ attrib }{ Pointer to a null-terminated character string containing the name of the attribute to be tested. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astTest() }{ One if a value has previously been explicitly set for the attribute (and hasn\texttt{'} t been cleared), otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem Attribute names are not case sensitive and may be surrounded by white space. \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. \sstitem A value of zero will also be returned if this function is used to test a read-only attribute, although no error will result. } } } \sstroutine{ astTestFits }{ See if a named keyword has a defined value in a FitsChan }{ \sstdescription{ This function serches for a named keyword in a \htmlref{FitsChan}{FitsChan}. If found, and if the keyword has a value associated with it, a non-zero value is returned. If the keyword is not found, or if it does not have an associated value, a zero value is returned. } \sstsynopsis{ int astTestFits( AstFitsChan $*$this, const char $*$name, int $*$there ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } \sstsubsection{ name }{ Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string. } \sstsubsection{ there }{ Pointer to an integer which will be returned holding a non-zero value if the keyword was found in the header, and zero otherwise. This parameter allows a distinction to be made between the case where a keyword is not present, and the case where a keyword is present but has no associated value. A NULL pointer may be supplied if this information is not required. } } \sstreturnedvalue{ \sstsubsection{ astTestFits() }{ A value of zero is returned if the keyword was not found in the FitsChan or has no associated value. Otherwise, a value of one is returned. } } \sstnotes{ \sstitemlist{ \sstitem The current card is left unchanged by this function. \sstitem The card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards. \sstitem An error will be reported if the keyword name does not conform to FITS requirements. \sstitem Zero is returned as the function value if an error has already occurred, or if this function should fail for any reason. } } } \sstroutine{ astText }{ Draw a text string for a Plot }{ \sstdescription{ This function draws a string of text at a position specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The physical position is transformed into graphical coordinates to determine where the text should appear within the plotting area. } \sstsynopsis{ void astText( AstPlot $*$this, const char $*$text, const double pos[], const float up[], const char $*$just ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Plot. } \sstsubsection{ text }{ Pointer to a null-terminated character string containing the text to be drawn. Trailing white space is ignored. } \sstsubsection{ pos }{ An array, with one element for each axis of the Plot, giving the physical coordinates of the point where the reference position of the text string is to be placed. } \sstsubsection{ up }{ An array holding the components of a vector in the \texttt{"} up\texttt{"} direction of the text (in graphical coordinates). For example, to get horizontal text, the vector \{0.0f,1.0f\} should be supplied. For a basic Plot, 2 values should be supplied. For a \htmlref{Plot3D}{Plot3D}, 3 values should be supplied, and the actual up vector used is the projection of the supplied up vector onto the text plane specified by the current value of the Plot3D\texttt{'} s Norm attribute. } \sstsubsection{ just }{ Pointer to a null-terminated character string identifying the reference point for the text being drawn. The first character in this string identifies the reference position in the \texttt{"} up\texttt{"} direction and may be \texttt{"} B\texttt{"} (baseline), \texttt{"} C\texttt{"} (centre), \texttt{"} T\texttt{"} (top) or \texttt{"} M\texttt{"} (bottom). The second character identifies the side-to-side reference position and may be \texttt{"} L\texttt{"} (left), \texttt{"} C\texttt{"} (centre) or \texttt{"} R\texttt{"} (right ). The string is case-insensitive, and only the first two characters are significant. For example, a value of \texttt{"} BL\texttt{"} means that the left end of the baseline of the original (un-rotated) text is to be drawn at the position given by \texttt{"} pos\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem The Plot3D class currently does not interpret graphical escape sequences contained within text displayed using this method. \sstitem Text is not drawn at positions which have any coordinate equal to the value AST\_\_BAD (or where the transformation into graphical coordinates yields coordinates containing the value AST\_\_BAD). \sstitem If the plotting position is clipped (see \htmlref{astClip}{astClip}), then no text is drawn. \sstitem An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. \sstitem An error also results if the transformation between the current and base Frames of the Plot is not defined (i.e. the Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). } } } \sstroutine{ astThread }{ Determine the thread that owns an Object }{ \sstdescription{ Returns an integer that indicates whether the supplied \htmlref{Object}{Object} (or Object pointer) is currently unlocked, or is currently locked by the running thread, or another thread. } \sstsynopsis{ int astThread( AstObject $*$this, int ptr ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be checked. } \sstsubsection{ ptr }{ If non-zero, returns information about the supplied Object pointer, rather than the Object structure itself. See \texttt{"} Object Pointers and Structures\texttt{"} below. } } \sstreturnedvalue{ \sstsubsection{ astThread() }{ A value of AST\_\_UNLOCKED is returned if the Object (or pointer) is currently unlocked (i.e. has been unlocked using \htmlref{astUnlock}{astUnlock} but has not yet been locked using \htmlref{astLock}{astLock}). A value of AST\_\_RUNNING is returned if the Object (or pointer) is currently locked by the running thread. A value of AST\_\_OTHER is returned if the Object (or pointer) is currently locked by the another thread. } } \sstnotes{ \sstitemlist{ \sstitem This function attempts to execute even if the global error status is set, but no further error report will be made if it subsequently fails under these circumstances. \sstitem This function is only available in the C interface. \sstitem This function always returns AST\_\_RUNNING if the AST library has been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} option was not specified when running the \texttt{"} configure\texttt{"} script). } } \sstdiytopic{ Object Pointers and Structures }{ At any one time, an AST Object can have several distinct pointers, any one of which can be used to access the Object structure. For instance, the \htmlref{astClone}{astClone} function will produce a new distinct pointer for a given Object. In fact, an AST \texttt{"} pointer\texttt{"} is not a real pointer at all - it is an identifier for a \texttt{"} handle\texttt{"} structure, encoded to make it look like a pointer. Each handle contains (amongst othere things) a \texttt{"} real\texttt{"} pointer to the Object structure. This allows more than one handle to refer to the same Object structure. So when you call astClone (for instance) you get back an identifier for a new handle that refers to the same Object as the supplied handle. In order to use an Object for anything useful, it must be locked for use by the running thread (either implicitly at creation or explicitly using astLock). The identity of the thread is stored in both the Object structure, and in the handle that was passed to astLock (or returned by the constructor function). Thus it is possible for a thread to have active pointers for Objects that are currently locked by another thread. In general, if such a pointer is passed to an AST function an error will be reported indicating that the Object is currently locked by another thread. The two exceptions to this is that \htmlref{astAnnul}{astAnnul} can be used to annull such a pointer, and this function can be used to return information about the pointer. The other practical consequence of this is that when \htmlref{astEnd}{astEnd} is called, all active pointers currently owned by the running thread (at the current context level) are annulled. This includes pointers for Objects that are currently locked by other threads. If the \texttt{"} ptr\texttt{"} parameter is zero, then the returned value describes the Object structure itself. If \texttt{"} ptr\texttt{"} is non-zero, then the returned value describes the supplied Object pointer (i.e. handle), rather than the Object structure. } } \sstroutine{ astTimeAdd }{ Add a time coordinate conversion to a TimeMap }{ \sstdescription{ This function adds one of the standard time coordinate system conversions listed below to an existing \htmlref{TimeMap}{TimeMap}. When a TimeMap is first created (using \htmlref{astTimeMap}{astTimeMap}), it simply performs a unit (null) \htmlref{Mapping}{Mapping}. By using astTimeAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the TimeMap will perform in sequence. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of the building blocks provided by this class. Normally, if a TimeMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astTimeAdd in the order given (i.e. with the most recently added conversion applied last). This order is reversed if the TimeMap\texttt{'} s Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the TimeMap. In this case, the first conversion to be applied would be the inverse of the one most recently added. } \sstsynopsis{ void astTimeAdd( AstTimeMap $*$this, const char $*$cvt, const double args[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the TimeMap. } \sstsubsection{ cvt }{ Pointer to a null-terminated string which identifies the time coordinate conversion to be added to the TimeMap. See the \texttt{"} Available Conversions\texttt{"} section for details of those available. } \sstsubsection{ args }{ An array containing argument values for the time coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the \texttt{"} Available Conversions\texttt{"} section). This array is ignored and a NULL pointer may be supplied if no arguments are needed. } } \sstnotes{ \sstitemlist{ \sstitem When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. A solution to this is to include all the steps which are (logically) necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting TimeMap. The simplification process will eliminate any steps which turn out not to be needed. \sstitem This function does not check to ensure that the sequence of coordinate conversions added to a TimeMap is physically meaningful. } } \sstdiytopic{ Available Conversions }{ The following strings (which are case-insensitive) may be supplied via the \texttt{"} cvt\texttt{"} parameter to indicate which time coordinate conversion is to be added to the TimeMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the \texttt{"} args\texttt{"} array, in the order indicated. Units and argument names are described at the end of the list of conversions, and \texttt{"} MJD\texttt{"} means Modified Julian Date. \sstitemlist{ \sstitem \texttt{"} MJDTOMJD\texttt{"} (MJDOFF1,MJDOFF2): Convert MJD from one offset to another. \sstitem \texttt{"} MJDTOJD\texttt{"} (MJDOFF,JDOFF): Convert MJD to Julian Date. \sstitem \texttt{"} JDTOMJD\texttt{"} (JDOFF,MJDOFF): Convert Julian Date to MJD. \sstitem \texttt{"} MJDTOBEP\texttt{"} (MJDOFF,BEPOFF): Convert MJD to Besselian epoch. \sstitem \texttt{"} BEPTOMJD\texttt{"} (BEPOFF,MJDOFF): Convert Besselian epoch to MJD. \sstitem \texttt{"} MJDTOJEP\texttt{"} (MJDOFF,JEPOFF): Convert MJD to Julian epoch. \sstitem \texttt{"} JEPTOMJD\texttt{"} (JEPOFF,MJDOFF): Convert Julian epoch to MJD. \sstitem \texttt{"} TAITOUTC\texttt{"} (MJDOFF): Convert a TAI MJD to a UTC MJD. \sstitem \texttt{"} UTCTOTAI\texttt{"} (MJDOFF): Convert a UTC MJD to a TAI MJD. \sstitem \texttt{"} TAITOTT\texttt{"} (MJDOFF): Convert a TAI MJD to a TT MJD. \sstitem \texttt{"} TTTOTAI\texttt{"} (MJDOFF): Convert a TT MJD to a TAI MJD. \sstitem \texttt{"} TTTOTDB\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD. \sstitem \texttt{"} TDBTOTT\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD. \sstitem \texttt{"} TTTOTCG\texttt{"} (MJDOFF): Convert a TT MJD to a TCG MJD. \sstitem \texttt{"} TCGTOTT\texttt{"} (MJDOFF): Convert a TCG MJD to a TT MJD. \sstitem \texttt{"} TDBTOTCB\texttt{"} (MJDOFF): Convert a TDB MJD to a TCB MJD. \sstitem \texttt{"} TCBTOTDB\texttt{"} (MJDOFF): Convert a TCB MJD to a TDB MJD. \sstitem \texttt{"} UTTOGMST\texttt{"} (MJDOFF): Convert a UT MJD to a GMST MJD. \sstitem \texttt{"} GMSTTOUT\texttt{"} (MJDOFF): Convert a GMST MJD to a UT MJD. \sstitem \texttt{"} GMSTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. \sstitem \texttt{"} LMSTTOGMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. \sstitem \texttt{"} LASTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. \sstitem \texttt{"} LMSTTOLAST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. \sstitem \texttt{"} UTTOUTC\texttt{"} (DUT1): Convert a UT1 MJD to a UTC MJD. \sstitem \texttt{"} UTCTOUT\texttt{"} (DUT1): Convert a UTC MJD to a UT1 MJD. \sstitem \texttt{"} LTTOUTC\texttt{"} (LTOFF): Convert a Local Time MJD to a UTC MJD. \sstitem \texttt{"} UTCTOLT\texttt{"} (LTOFF): Convert a UTC MJD to a Local Time MJD. } The units for the values processed by the above conversions are as follows: \sstitemlist{ \sstitem Julian epochs and offsets: Julian years \sstitem Besselian epochs and offsets: Tropical years \sstitem Modified Julian Dates and offsets: days \sstitem Julian Dates and offsets: days } The arguments used in the above conversions are the zero-points used by the astTransform function. The axis values supplied and returned by astTransform are offsets away from these zero-points: \sstitemlist{ \sstitem MJDOFF: The zero-point being used with MJD values. \sstitem JDOFF: The zero-point being used with Julian Date values. \sstitem BEPOFF: The zero-point being used with Besselian epoch values. \sstitem JEPOFF: The zero-point being used with Julian epoch values. \sstitem OBSLON: Observer longitude in radians ($+$ve westwards). \sstitem OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards). \sstitem OBSALT: Observer geodetic altitude (IAU 1975) in metres. \sstitem DUT1: The UT1-UTC value to use. \sstitem LTOFF: The offset between Local Time and UTC (in hours, positive for time zones east of Greenwich). } } } \sstroutine{ astTimeFrame }{ Create a TimeFrame }{ \sstdescription{ This function creates a new \htmlref{TimeFrame}{TimeFrame} and optionally initialises its attributes. A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions in time. A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame representing time offsets from the specified zero point. Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years. The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that is, the physical proces used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales. When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute). } \sstsynopsis{ AstTimeFrame $*$astTimeFrame( const char $*$options, ... ) } \sstparameters{ \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeFrame. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astTimeFrame() }{ A pointer to the new TimeFrame. } } \sstnotes{ \sstitemlist{ \sstitem When conversion between two TimeFrames is requested (as when supplying TimeFrames to \htmlref{astConvert}{astConvert}), account will be taken of the nature of the time coordinate systems they represent, together with any qualifying time scale, offset, unit, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignTimeScale}{AlignTimeScale} attributes will also be taken into account. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astTimeMap }{ Create a TimeMap }{ \sstdescription{ This function creates a new \htmlref{TimeMap}{TimeMap} and optionally initialises its attributes. A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard time coordinate systems. When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd} function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks. For details of the individual coordinate conversions available, see the description of the astTimeAdd function. } \sstsynopsis{ AstTimeMap $*$astTimeMap( int flags, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ flags }{ This parameter is reserved for future use and should currently always be set to zero. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TimeMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If no initialisation is required, a zero-length string may be supplied. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astTimeMap() }{ A pointer to the new TimeMap. } } \sstnotes{ \sstitemlist{ \sstitem The nature and units of the coordinate values supplied for the first input (i.e. the time input) of a TimeMap must be appropriate to the first conversion step applied by the TimeMap. For instance, if the first conversion step is \texttt{"} MJDTOBEP\texttt{"} (Modified Julian Date to Besselian epoch) then the coordinate values for the first input should be date in units of days. Similarly, the nature and units of the coordinate values returned by a TimeMap will be determined by the last conversion step applied by the TimeMap. \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astToString }{ Create an in-memory serialisation of an Object }{ \sstdescription{ This function returns a string holding a minimal textual serialisation of the supplied AST \htmlref{Object}{Object}. The Object can re re-created from the serialisation using \htmlref{astFromString}{astFromString}. } \sstsynopsis{ char $*$astToString( AstObject $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be serialised. } } \sstreturnedvalue{ \sstsubsection{ astToString() }{ Pointer to dynamically allocated memory holding the serialisation, or NULL if an error occurs. The pointer should be freed when no longer needed using \htmlref{astFree}{astFree}. } } } \sstroutine{ astTran1 }{ Transform 1-dimensional coordinates }{ \sstdescription{ This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in one dimension. } \sstsynopsis{ void astTran1( AstMapping $*$this, int npoint, const double xin[], int forward, double xout[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ npoint }{ The number of points to be transformed. } \sstsubsection{ xin }{ An array of \texttt{"} npoint\texttt{"} coordinate values for the input (untransformed) points. } \sstsubsection{ forward }{ A non-zero value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. } \sstsubsection{ xout }{ An array (with \texttt{"} npoint\texttt{"} elements) into which the coordinates of the output (transformed) points will be written. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. } } } \sstroutine{ astTran2 }{ Transform 2-dimensional coordinates }{ \sstdescription{ This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in two dimensions. } \sstsynopsis{ void astTran2( AstMapping $*$this, int npoint, const double xin[], const double yin[], int forward, double xout[], double yout[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ npoint }{ The number of points to be transformed. } \sstsubsection{ xin }{ An array of \texttt{"} npoint\texttt{"} X-coordinate values for the input (untransformed) points. } \sstsubsection{ yin }{ An array of \texttt{"} npoint\texttt{"} Y-coordinate values for the input (untransformed) points. } \sstsubsection{ forward }{ A non-zero value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. } \sstsubsection{ xout }{ An array (with \texttt{"} npoint\texttt{"} elements) into which the X-coordinates of the output (transformed) points will be written. } \sstsubsection{ yout }{ An array (with \texttt{"} npoint\texttt{"} elements) into which the Y-coordinates of the output (transformed) points will be written. } } \sstnotes{ \sstitemlist{ \sstitem The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. } } } \sstroutine{ astTranGrid }{ Transform a grid of positions }{ \sstdescription{ This function uses the supplied \htmlref{Mapping}{Mapping} to transforms a regular square grid of points covering a specified box. It attempts to do this quickly by first approximating the Mapping with a linear transformation applied over the whole region of the input grid which is being used. If this proves to be insufficiently accurate, the input region is sub-divided into two along its largest dimension and the process is repeated within each of the resulting sub-regions. This process of sub-division continues until a sufficiently good linear approximation is found, or the region to which it is being applied becomes too small (in which case the original Mapping is used directly). } \sstsynopsis{ void astTranGrid( AstMapping $*$this, int ncoord\_in, const int lbnd[], const int ubnd[], double tol, int maxpix, int forward, int ncoord\_out, int outdim, double $*$out ); } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ ncoord\_in }{ The number of coordinates being supplied for each box corner (i.e. the number of dimensions of the space in which the input points reside). } \sstsubsection{ lbnd }{ Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd }{ Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and size of the input grid, its extent along a particular (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the index \texttt{"} j\texttt{"} to be zero-based). They also define the input grid\texttt{'} s coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre. } \sstsubsection{ tol }{ The maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement within the output coordinate system of the Mapping. If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time. If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher. If this is a problem, reduce the tolerance value used. } \sstsubsection{ maxpix }{ A value which specifies an initial scale size (in input grid points) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} grid points in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 grid points can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting \texttt{"} tol\texttt{"} to zero). Although this may degrade performance, accurate results will still be obtained. } \sstsubsection{ forward }{ A non-zero value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. } \sstsubsection{ ncoord\_out }{ The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as \texttt{"} ncoord\_in\texttt{"} . } \sstsubsection{ outdim }{ The number of elements along the second dimension of the \texttt{"} out\texttt{"} array (which will contain the output coordinates). The value given should not be less than the number of points in the grid. } \sstsubsection{ out }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} will be found in element \texttt{"} out[coord][point]\texttt{"} . The points are ordered such that the first axis of the input grid changes most rapidly. For example, if the input grid is 2-dimensional and extends from (2,-1) to (3,1), the output points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), (2,1), (3,1). } } \sstnotes{ \sstitemlist{ \sstitem If the forward coordinate transformation is being applied, the Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} attribute. If the inverse transformation is being applied, these values should be reversed. } } } \sstroutine{ astTranMap }{ Create a TranMap }{ \sstdescription{ This function creates a new \htmlref{TranMap}{TranMap} and optionally initialises its attributes. A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist). When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed. } \sstsynopsis{ AstTranMap $*$astTranMap( AstMapping $*$map1, AstMapping $*$map2, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ map1 }{ Pointer to the first component Mapping, which defines the forward transformation. } \sstsubsection{ map2 }{ Pointer to the second component Mapping, which defines the inverse transformation. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new TranMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astTranMap() }{ A pointer to the new TranMap. } } \sstnotes{ \sstitemlist{ \sstitem The number of output coordinates generated by the two Mappings (their \htmlref{Nout}{Nout} attribute) must be equal, as must the number of input coordinates accepted by each Mapping (their \htmlref{Nin}{Nin} attribute). \sstitem The forward transformation of the first Mapping must exist. \sstitem The inverse transformation of the second Mapping must exist. \sstitem Note that the component Mappings supplied are not copied by astTranMap (the new TranMap simply retains a reference to them). They may continue to be used for other purposes, but should not be deleted. If a TranMap containing a copy of its component Mappings is required, then a copy of the TranMap should be made using \htmlref{astCopy}{astCopy}. \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astTranN }{ Transform N-dimensional coordinates }{ \sstdescription{ This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in a single array (which they need not fill completely). If the coordinates are not stored in a single array, then the \htmlref{astTranP}{astTranP} function might be more suitable. } \sstsynopsis{ void astTranN( AstMapping $*$this, int npoint, int ncoord\_in, int indim, const double $*$in, int forward, int ncoord\_out, int outdim, double $*$out ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ npoint }{ The number of points to be transformed. } \sstsubsection{ ncoord\_in }{ The number of coordinates being supplied for each input point (i.e. the number of dimensions of the space in which the input points reside). } \sstsubsection{ indim }{ The number of elements along the second dimension of the \texttt{"} in\texttt{"} array (which contains the input coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than \texttt{"} npoint\texttt{"} . } \sstsubsection{ in }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [ncoord\_in][indim]\texttt{"} , containing the coordinates of the input (untransformed) points. These should be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for input point number \texttt{"} point\texttt{"} is found in element \texttt{"} in[coord][point]\texttt{"} . } \sstsubsection{ forward }{ A non-zero value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. } \sstsubsection{ ncoord\_out }{ The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as \texttt{"} ncoord\_in\texttt{"} . } \sstsubsection{ outdim }{ The number of elements along the second dimension of the \texttt{"} out\texttt{"} array (which will contain the output coordinates). This value is required so that the coordinate values can be correctly located if they will not entirely fill this array. The value given should not be less than \texttt{"} npoint\texttt{"} . } \sstsubsection{ out }{ The address of the first element in a 2-dimensional array of shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into which the coordinates of the output (transformed) points will be written. These will be stored such that the value of coordinate number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} will be found in element \texttt{"} out[coord][point]\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem If the forward coordinate transformation is being applied, the Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} attribute. If the inverse transformation is being applied, these values should be reversed. } } } \sstroutine{ astTranP }{ Transform N-dimensional coordinates held in separate arrays }{ \sstdescription{ This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of a set of points in an arbitrary number of dimensions. It is the appropriate routine to use if the coordinates are not purely 1- or 2-dimensional and are stored in separate arrays, since each coordinate array is located by supplying a separate pointer to it. If the coordinates are stored in a single (2-dimensional) array, then the \htmlref{astTranN}{astTranN} function might be more suitable. } \sstsynopsis{ void astTranP( AstMapping $*$this, int npoint, int ncoord\_in, const double $*$ptr\_in[], int forward, int ncoord\_out, double $*$ptr\_out[] ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Mapping to be applied. } \sstsubsection{ npoint }{ The number of points to be transformed. } \sstsubsection{ ncoord\_in }{ The number of coordinates being supplied for each input point (i.e. the number of dimensions of the space in which the input points reside). } \sstsubsection{ ptr\_in }{ An array of pointers to double, with \texttt{"} ncoord\_in\texttt{"} elements. Element \texttt{"} ptr\_in[coord]\texttt{"} should point at the first element of an array of double (with \texttt{"} npoint\texttt{"} elements) which contain the values of coordinate number \texttt{"} coord\texttt{"} for each input (untransformed) point. The value of coordinate number \texttt{"} coord\texttt{"} for input point number \texttt{"} point\texttt{"} is therefore given by \texttt{"} ptr\_in[coord][point]\texttt{"} (assuming both indices are zero-based). } \sstsubsection{ forward }{ A non-zero value indicates that the Mapping\texttt{'} s forward coordinate transformation is to be applied, while a zero value indicates that the inverse transformation should be used. } \sstsubsection{ ncoord\_out }{ The number of coordinates being generated by the Mapping for each output point (i.e. the number of dimensions of the space in which the output points reside). This need not be the same as \texttt{"} ncoord\_in\texttt{"} . } \sstsubsection{ ptr\_out }{ An array of pointers to double, with \texttt{"} ncoord\_out\texttt{"} elements. Element \texttt{"} ptr\_out[coord]\texttt{"} should point at the first element of an array of double (with \texttt{"} npoint\texttt{"} elements) into which the values of coordinate number \texttt{"} coord\texttt{"} for each output (transformed) point will be written. The value of coordinate number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} will therefore be found in \texttt{"} ptr\_out[coord][point]\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem If the forward coordinate transformation is being applied, the Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} attribute. If the inverse transformation is being applied, these values should be reversed. \sstitem This routine is not available in the Fortran 77 interface to the AST library. } } } \sstroutine{ astTune }{ Set or get an integer-valued AST global tuning parameter }{ \sstdescription{ This function returns the current value of an integer-valued AST global tuning parameter, optionally storing a new value for the parameter. For character-valued tuning parameters, see \htmlref{astTuneC}{astTuneC}. } \sstsynopsis{ int astTune( const char $*$name, int value ) } \sstparameters{ \sstsubsection{ name }{ The name of the tuning parameter (case-insensitive). } \sstsubsection{ value }{ The new value for the tuning parameter. If this is AST\_\_TUNULL, the existing current value will be retained. } } \sstreturnedvalue{ \sstsubsection{ astTune() }{ The original value of the tuning parameter. A default value will be returned if no value has been set for the parameter. } } \sstnotes{ \sstitemlist{ \sstitem This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem All threads in a process share the same AST tuning parameters values. } } \sstdiylist{ Tuning Parameters }{ \sstsubsection{ ObjectCaching }{ A boolean flag which indicates what should happen to the memory occupied by an AST \htmlref{Object}{Object} when the Object is deleted (i.e. when its reference count falls to zero or it is deleted using \htmlref{astDelete}{astDelete}). If this is zero, the memory is simply freed using the systems \texttt{"} free\texttt{"} function. If it is non-zero, the memory is not freed. Instead a pointer to it is stored in a pool of such pointers, all of which refer to allocated but currently unused blocks of memory. This allows AST to speed up subsequent Object creation by re-using previously allocated memory blocks rather than allocating new memory using the systems malloc function. The default value for this parameter is zero. Setting it to a non-zero value will result in Object memory being cached in future. Setting it back to zero causes any memory blocks currently in the pool to be freed. Note, this tuning parameter only controls the caching of memory used to store AST Objects. To cache other memory blocks allocated by AST, use MemoryCaching. } \sstsubsection{ MemoryCaching }{ A boolean flag similar to ObjectCaching except that it controls caching of all memory blocks of less than 300 bytes allocated by AST (whether for internal or external use), not just memory used to store AST Objects. } } } \sstroutine{ astTuneC }{ Set or get a character-valued AST global tuning parameter }{ \sstdescription{ This function returns the current value of a character-valued AST global tuning parameter, optionally storing a new value for the parameter. For integer-valued tuning parameters, see \htmlref{astTune}{astTune}. } \sstsynopsis{ void astTuneC( const char $*$name, const char $*$value, char $*$buff, int bufflen ) } \sstparameters{ \sstsubsection{ name }{ The name of the tuning parameter (case-insensitive). } \sstsubsection{ value }{ The new value for the tuning parameter. If this is NULL, the existing current value will be retained. } \sstsubsection{ buff }{ A character string in which to return the original value of the tuning parameter. An error will be reported if the buffer is too small to hold the value. NULL may be supplied if the old value is not required. } \sstsubsection{ bufflen }{ The size of the supplied \texttt{"} buff\texttt{"} array. Ignored if \texttt{"} buff\texttt{"} is NULL. } } \sstnotes{ \sstitemlist{ \sstitem This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. \sstitem All threads in a process share the same AST tuning parameters values. } } \sstdiylist{ Tuning Parameters }{ \sstsubsection{ HRDel }{ A string to be drawn following the hours field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use (see the Format attribute). This string may include escape sequences to produce super-scripts, etc. (see the Escapes attribute for details of the escape sequences allowed). The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$h\%$+$\texttt{"} which produces a super-script \texttt{"} h\texttt{"} . } \sstsubsection{ MNDel }{ A string to be drawn following the minutes field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$m\%$+$\texttt{"} which produces a super-script \texttt{"} m\texttt{"} . } \sstsubsection{ SCDel }{ A string to be drawn following the seconds field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$50$+$\%s70$+$s\%$+$\texttt{"} which produces a super-script \texttt{"} s\texttt{"} . } \sstsubsection{ DGDel }{ A string to be drawn following the degrees field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$53$+$\%s60$+$o\%$+$\texttt{"} which produces a super-script \texttt{"} o\texttt{"} . } \sstsubsection{ AMDel }{ A string to be drawn following the arc-minutes field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$20$+$\%s85$+$\texttt{'} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{'} \texttt{"} (single quote). } \sstsubsection{ ASDel }{ A string to be drawn following the arc-seconds field in a formatted sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} \%-\%$\wedge$20$+$\%s85$+$$\backslash$\texttt{"} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{"} \texttt{"} (double quote). } \sstsubsection{ EXDel }{ A string to be drawn to introduce the exponent in a value when \texttt{"} g\texttt{"} format is in use. The default value is \texttt{"} 10\%-\%$\wedge$50$+$\%s70$+$\texttt{"} which produces \texttt{"} 10\texttt{"} followed by the exponent as a super-script. } } } \sstroutine{ astUinterp }{ Perform sub-pixel interpolation on a grid of data }{ \sstdescription{ This is a fictitious function which does not actually exist. Instead, this description constitutes a template so that you may implement a function with this interface for yourself (and give it any name you wish). A pointer to such a function may be passed via the \texttt{"} finterp\texttt{"} parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$} functions (q.v.) in order to perform sub-pixel interpolation during resampling of gridded data (you must also set the \texttt{"} interp\texttt{"} parameter of astResample$<$X$>$ to the value AST\_\_UINTERP). This allows you to use your own interpolation algorithm in addition to those which are pre-defined. The function interpolates an input grid of data (and, optionally, processes associated statistical variance estimates) at a specified set of points. } \sstsynopsis{ void astUinterp( int ndim\_in, const int lbnd\_in[], const int ubnd\_in[], const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], int npoint, const int offset[], const double $*$const coords[], const double params[], int flags, $<$Xtype$>$ badval, $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], int $*$nbad ) } \sstparameters{ \sstsubsection{ ndim\_in }{ The number of dimensions in the input grid. This will be at least one. } \sstsubsection{ lbnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension. } \sstsubsection{ ubnd\_in }{ Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, containing the coordinates of the centre of the last pixel in the input grid along each dimension. Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape, size and coordinate system of the input grid in the same way as they do in astResample$<$X$>$. } \sstsubsection{ in }{ Pointer to an array, with one element for each pixel in the input grid, containing the input data. This will be the same array as was passed to astResample$<$X$>$ via the \texttt{"} in\texttt{"} parameter. The numerical type of this array should match that of the data being processed. } \sstsubsection{ in\_var }{ Pointer to an optional second array with the same size and type as the \texttt{"} in\texttt{"} array. If given, this will contain the set of variance values associated with the input data and will be the same array as was passed to astResample$<$X$>$ via the \texttt{"} in\_var\texttt{"} parameter. If no variance values are being processed, this will be a NULL pointer. } \sstsubsection{ npoint }{ The number of points at which the input grid is to be interpolated. This will be at least one. } \sstsubsection{ offset }{ Pointer to an array of integers with \texttt{"} npoint\texttt{"} elements. For each interpolation point, this will contain the zero-based index in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) at which the interpolated value (and its variance, if required) should be stored. For example, the interpolated value for point number \texttt{"} point\texttt{"} should be stored in \texttt{"} out[offset[point]]\texttt{"} (assuming the index \texttt{"} point\texttt{"} is zero-based). } \sstsubsection{ coords }{ An array of pointers to double, with \texttt{"} ndim\_in\texttt{"} elements. Element \texttt{"} coords[coord]\texttt{"} will point at the first element of an array of double (with \texttt{"} npoint\texttt{"} elements) which contains the values of coordinate number \texttt{"} coord\texttt{"} for each interpolation point. The value of coordinate number \texttt{"} coord\texttt{"} for interpolation point number \texttt{"} point\texttt{"} is therefore given by \texttt{"} coords[coord][point]\texttt{"} (assuming both indices are zero-based). If any interpolation point has any of its coordinates equal to the value AST\_\_BAD (as defined in the \texttt{"} ast.h\texttt{"} header file), then the corresponding output data (and variance) should either be set to the value given by \texttt{"} badval\texttt{"} , or left unchanged, depending on whether the AST\_\_NOBAD flag is specified by \texttt{"} flags\texttt{"} . } \sstsubsection{ params }{ This will be a pointer to the same array as was given via the \texttt{"} params\texttt{"} parameter of astResample$<$X$>$. You may use this to pass any additional parameter values required by your interpolation algorithm. } \sstsubsection{ flags }{ This will be the same value as was given via the \texttt{"} flags\texttt{"} parameter of astResample$<$X$>$. You may test this value to provide additional control over the operation of your resampling algorithm. Note that the special flag values AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see astResample$<$X$>$). } \sstsubsection{ badval }{ This will be the same value as was given via the \texttt{"} badval\texttt{"} parameter of astResample$<$X$>$, and will have the same numerical type as the data being processed (i.e. as elements of the \texttt{"} in\texttt{"} array). It should be used to test for bad pixels in the input grid (but only if the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter) and (unless the AST\_\_NOBAD flag is set in \texttt{"} flags\texttt{"} ) for identifying bad output values in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s). } \sstsubsection{ out }{ Pointer to an array with the same numerical type as the \texttt{"} in\texttt{"} array, into which the interpolated data values should be returned. Note that details of the storage order and number of dimensions of this array are not required, since the \texttt{"} offset\texttt{"} array contains all necessary information about where each returned value should be stored. In general, not all elements of this array (or the \texttt{"} out\_var\texttt{"} array below) may be used in any particular invocation of the function. Those which are not used should be returned unchanged. } \sstsubsection{ out\_var }{ Pointer to an optional array with the same type and size as the \texttt{"} out\texttt{"} array, into which variance estimates for the resampled values should be returned. This array will only be given if the \texttt{"} in\_var\texttt{"} array has also been given. If given, it is addressed in exactly the same way (via the \texttt{"} offset\texttt{"} array) as the \texttt{"} out\texttt{"} array. The values returned should be estimates of the statistical variance of the corresponding values in the \texttt{"} out\texttt{"} array, on the assumption that all errors in input data values are statistically independent and that their variance estimates may simply be summed (with appropriate weighting factors). If no output variance estimates are required, a NULL pointer will be given. } \sstsubsection{ nbad }{ Pointer to an int in which to return the number of interpolation points at which no valid interpolated value could be obtained. The maximum value that should be returned is \texttt{"} npoint\texttt{"} , and the minimum is zero (indicating that all output values were successfully obtained). } } \sstnotes{ \sstitemlist{ \sstitem The data type $<$Xtype$>$ indicates the numerical type of the data being processed, as for astResample$<$X$>$. \sstitem This function will typically be invoked more than once for each invocation of astResample$<$X$>$. \sstitem If an error occurs within this function, it should use \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value. This will cause an immediate return from astResample$<$X$>$. The error value AST\_\_UINER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). } } } \sstroutine{ astUkern1 }{ 1-dimensional sub-pixel interpolation kernel }{ \sstdescription{ This is a fictitious function which does not actually exist. Instead, this description constitutes a template so that you may implement a function with this interface for yourself (and give it any name you wish). A pointer to such a function may be passed via the \texttt{"} finterp\texttt{"} parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$} functions (q.v.) in order to supply a 1-dimensional interpolation kernel to the algorithm which performs sub-pixel interpolation during resampling of gridded data (you must also set the \texttt{"} interp\texttt{"} parameter of astResample$<$X$>$ to the value AST\_\_UKERN1). This allows you to use your own interpolation kernel in addition to those which are pre-defined. The function calculates the value of a 1-dimensional sub-pixel interpolation kernel. This determines how the weight given to neighbouring pixels in calculating an interpolated value depends on the pixel\texttt{'} s offset from the interpolation point. In more than one dimension, the weight assigned to a pixel is formed by evaluating this 1-dimensional kernel using the offset along each dimension in turn. The product of the returned values is then used as the pixel weight. } \sstsynopsis{ void astUkern1( double offset, const double params[], int flags, double $*$value ) } \sstparameters{ \sstsubsection{ offset }{ This will be the offset of the pixel from the interpolation point, measured in pixels. This value may be positive or negative, but for most practical interpolation schemes its sign should be ignored. } \sstsubsection{ params }{ This will be a pointer to the same array as was given via the \texttt{"} params\texttt{"} parameter of astResample$<$X$>$. You may use this to pass any additional parameter values required by your kernel, but note that \texttt{"} params[0]\texttt{"} will already have been used to specify the number of neighbouring pixels which contribute to the interpolated value. } \sstsubsection{ flags }{ This will be the same value as was given via the \texttt{"} flags\texttt{"} parameter of astResample$<$X$>$. You may test this value to provide additional control over the operation of your function. Note that the special flag values AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your own purposes and will not clash with other pre-defined flag values (see astResample$<$X$>$). } \sstsubsection{ value }{ Pointer to a double to receive the calculated kernel value, which may be positive or negative. } } \sstnotes{ \sstitemlist{ \sstitem Not all functions make good interpolation kernels. In general, acceptable kernels tend to be symmetrical about zero, to have a positive peak (usually unity) at zero, and to evaluate to zero whenever the pixel offset has any other integral value (this ensures that the interpolated values pass through the original data). An interpolation kernel may or may not have regions with negative values. You should consult a good book on image processing for more details. \sstitem If an error occurs within this function, it should use \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value. This will cause an immediate return from astResample$<$X$>$. The error value AST\_\_UK1ER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error). } } } \sstroutine{ astUnformat }{ Read a formatted coordinate value for a Frame axis }{ \sstdescription{ This function reads a formatted coordinate value (given as a character string) for a \htmlref{Frame}{Frame} axis and returns the equivalent numerical (double) value. It also returns the number of characters read from the string. The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame\texttt{'} s attributes (in particular, the Format string associated with the Frame\texttt{'} s axis). This function is, in essence, the inverse of \htmlref{astFormat}{astFormat}. } \sstsynopsis{ int astUnformat( AstFrame $*$this, int axis, const char $*$string, double $*$value ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Frame. } \sstsubsection{ axis }{ The number of the Frame axis for which a coordinate value is to be read (axis numbering starts at 1 for the first axis). } \sstsubsection{ string }{ Pointer to a null-terminated character string containing the formatted coordinate value. This string may contain additional information following the value to be read, in which case reading stops at the first character which cannot be interpreted as part of the value. Any white space before or after the value is discarded. } \sstsubsection{ value }{ Pointer to a double in which the coordinate value read will be returned. } } \sstapplicability{ \sstsubsection{ Frame }{ This function applies to all Frames. See the \texttt{"} Frame Input Format\texttt{"} section below for details of the input formats accepted by a basic Frame. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the \texttt{"} SkyFrame Input Format\texttt{"} section below for details of the formats accepted. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The input formats accepted by a FrameSet are determined by its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstreturnedvalue{ \sstsubsection{ astUnformat() }{ The number of characters read from the string in order to obtain the coordinate value. This will include any white space which occurs before or after the value. } } \sstnotes{ \sstitemlist{ \sstitem 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. \sstitem Beware that it is possible for a formatting error part-way through an input string to terminate input before it has been completely read, but to yield a coordinate value that appears valid. For example, if a user types \texttt{"} 1.5r6\texttt{"} instead of \texttt{"} 1.5e6\texttt{"} , the \texttt{"} r\texttt{"} will terminate input, giving an incorrect coordinate value of 1.5. It is therefore most important to check the return value of this function to ensure that the correct number of characters have been read. \sstitem An error will result if a value is read which appears to have the correct format, but which cannot be converted into a valid coordinate value (for instance, because the value of one or more of its fields is invalid). \sstitem The string \texttt{"} $<$bad$>$\texttt{"} is recognised as a special case and will yield the coordinate value AST\_\_BAD without error. The test for this string is case-insensitive and also permits embedded white space. \sstitem A function result of zero will be returned and no coordinate value will be returned via the \texttt{"} value\texttt{"} pointer if this function is invoked with the AST error status set, or if it should fail for any reason. } } \sstdiytopic{ Frame Input Format }{ The input format accepted for a basic Frame axis is as follows: \sstitemlist{ \sstitem An optional sign, followed by: \sstitem A sequence of one or more digits possibly containing a decimal point, followed by: \sstitem An optional exponent field. \sstitem The exponent field, if present, consists of \texttt{"} E\texttt{"} or \texttt{"} e\texttt{"} followed by a possibly signed integer. } Examples of acceptable Frame input formats include: \sstitemlist{ \sstitem 99 \sstitem 1.25 \sstitem -1.6 \sstitem 1E8 \sstitem -.99e-17 \sstitem $<$bad$>$ } } \sstdiytopic{ SkyFrame Input Format }{ The input format accepted for a SkyFrame axis is as follows: \sstitemlist{ \sstitem An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. \texttt{"} -12 42 03\texttt{"} ). \sstitem Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as \texttt{"} 124.707\texttt{"} , while degrees and decimal arc-minutes might be given as \texttt{"} -13 33.8\texttt{"} ). \sstitem The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. \texttt{"} 720 45 31\texttt{"} is valid, whereas \texttt{"} 11 45 61\texttt{"} is not). \sstitem Fields may be separated by white space or by \texttt{"} :\texttt{"} (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. \texttt{"} - 2: 04 : 7.1\texttt{"} ). \sstitem The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: \texttt{"} d\texttt{"} ---degrees; \texttt{"} h\texttt{"} ---hours; \texttt{"} m\texttt{"} ---minutes of arc or time; \texttt{"} s\texttt{"} ---seconds of arc or time; \texttt{"} \texttt{'} \texttt{"} (single quote)---minutes of arc; \texttt{"} \texttt{"} \texttt{"} (double quote)---seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. \texttt{"} -11D 3\texttt{'} 14.4\texttt{"} \texttt{"} or \texttt{"} 22h14m11.2s\texttt{"} ). \sstitem The presence of any of the field identification characters \texttt{"} d\texttt{"} , \texttt{"} \texttt{'} \texttt{"} (single quote) or \texttt{"} \texttt{"} \texttt{"} (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of \texttt{"} h\texttt{"} indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. \texttt{"} 10h14\texttt{'} 3\texttt{"} \texttt{"} is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either. \sstitem If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by astFormat are correctly interpreted by astUnformat. \sstitem Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. \texttt{"} -05m13s\texttt{"} is equivalent to \texttt{"} -:05:13\texttt{"} ). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. \texttt{"} 14:25.4s\texttt{"} specifies minutes and seconds, while \texttt{"} 14::25.4s\texttt{"} specifies degrees and seconds). \sstitem If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. \texttt{"} 01:02\texttt{"} ), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that astFormat would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that astFormat would produce. } This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters. Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include: \sstitemlist{ \sstitem -14d 13m 22.2s (-14d 13\texttt{'} 22.2\texttt{"} ) \sstitem $+$ 12:34:56.7 (12d 34\texttt{'} 56.7\texttt{"} or 12h 34m 56.7s) \sstitem 001 : 02 : 03.4 (1d 02\texttt{'} 03.4\texttt{"} or 1h 02m 03.4s) \sstitem 22h 30 (22h 30m 00s) \sstitem 136::10\texttt{"} (136d 00\texttt{'} 10\texttt{"} or 136h 00m 10s) \sstitem -14M 27S (-0d 14\texttt{'} 27\texttt{"} or -0h 14m 27s) \sstitem -:14: (-0d 14\texttt{'} 00\texttt{"} or -0h 14m 00s) \sstitem -::4.1 (-0d 00\texttt{'} 04.1\texttt{"} or -0h 00m 04.1s) \sstitem .9\texttt{"} (0d 00\texttt{'} 00.9\texttt{"} ) \sstitem d12m (0d 12\texttt{'} 00\texttt{"} ) \sstitem H 12:22.3s (0h 12m 22.3s) \sstitem $<$bad$>$ (AST\_\_BAD) } Where alternative interpretations are shown, the choice of angle or time depends on the associated \htmlref{Format(axis)}{Format(axis)} attribute. } } \sstroutine{ astUnitMap }{ Create a UnitMap }{ \sstdescription{ This function creates a new \htmlref{UnitMap}{UnitMap} and optionally initialises its attributes. A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the coordinates supplied to it. They are simply copied. This can be useful if a Mapping is required (e.g. to pass to another function) but you do not want it to have any effect. } \sstsynopsis{ AstUnitMap $*$astUnitMap( int ncoord, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of input and output coordinates (these numbers are necessarily the same). } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astUnitMap() }{ A pointer to the new UnitMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } } \sstroutine{ astUnitNormMap }{ Create a UnitNormMap }{ \sstdescription{ This function creates a new \htmlref{UnitNormMap}{UnitNormMap} and optionally initialises its attributes. The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm. The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. UnitNormMap enables radially symmetric transformations, as follows: \sstitemlist{ \sstitem apply a UnitNormMap to produce a unit vector and norm (radius) \sstitem apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged \sstitem apply the same UnitNormMap in the inverse direction to produce the result } } \sstsynopsis{ AstUnitNormMap $*$astUnitNormMap( int ncoord, const double centre[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). Output will include one additional coordinate. } \sstsubsection{ centre }{ An array containing the values to be subtracted from the input coordinates before computing unit vector and norm. A separate value must be supplied for each coordinate. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new UnitNormMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astUnitNormMap() }{ A pointer to the new UnitNormMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astUnlock }{ Unlock an Object for use by other threads }{ \sstdescription{ Unlocks an \htmlref{Object}{Object} previously locked using \htmlref{astLock}{astLock}, so that other threads can use the Object. See astLock for further details. } \sstsynopsis{ void astUnlock( AstObject $*$this, int report ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Object to be unlocked. } \sstsubsection{ report }{ If non-zero, an error will be reported if the supplied Object, or any Object contained within the supplied Object, is not currently locked by the running thread. If zero, such Objects will be left unchanged, and no error will be reported. } } \sstapplicability{ \sstsubsection{ Object }{ This function applies to all Objects. } } \sstnotes{ \sstitemlist{ \sstitem This function attempts to execute even if the global error status is set, but no further error report will be made if it subsequently fails under these circumstances. \sstitem All unlocked Objects are excluded from AST context handling until they are re-locked using astLock. \sstitem This function is only available in the C interface. \sstitem This function returns without action if the Object is not currently locked by any thread. If it is locked by the running thread, it is unlocked. If it is locked by another thread, an error will be reported if \texttt{"} error\texttt{"} is non-zero. \sstitem This function returns without action if the AST library has been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} option was not specified when running the \texttt{"} configure\texttt{"} script). } } } \sstroutine{ astVersion }{ Return the version of the AST library being used }{ \sstdescription{ This macro invokes a function which returns an integer representing the version of the AST library being used. The library version is formatted as a string such as \texttt{"} 2.0-7\texttt{"} which contains integers representing the \texttt{"} major version\texttt{"} (2), the \texttt{"} minor version\texttt{"} (0) and the \texttt{"} release\texttt{"} (7). The integer returned by this function combines all three integers together into a single integer using the expresion: (major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release) } \sstsynopsis{ int astVersion } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ This macro applies to all Objects. } } \sstreturnedvalue{ \sstsubsection{ astVersion }{ The major version, minor version and release numbers for the AST library, encoded as a single integer. } } } \sstroutine{ astWarnings }{ Returns any warnings issued by the previous read or write operation }{ \sstdescription{ This function returns an AST \htmlref{KeyMap}{KeyMap} object holding the text of any warnings issued as a result of the previous invocation of the \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} function on the \htmlref{Channel}{Channel}. If no warnings were issued, a a NULL value will be returned. Such warnings are non-fatal and will not prevent the read or write operation succeeding. However, the converted object may not be identical to the original object in all respects. Differences which would usually be deemed as insignificant in most usual cases will generate a warning, whereas more significant differences will generate an error. The \texttt{"} \htmlref{Strict}{Strict}\texttt{"} attribute allows this warning facility to be switched off, so that a fatal error is always reported for any conversion error. } \sstsynopsis{ AstKeyMap $*$astWarnings( AstChannel $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Channel. } } \sstapplicability{ \sstsubsection{ Channel }{ The basic Channel class generates a warning when ever an un-recognised item is encountered whilst reading an \htmlref{Object}{Object} from an external data source. If Strict is zero (the default), then unexpected items in the Object description are simply ignored, and any remaining items are used to construct the returned Object. If Strict is non-zero, an error will be reported and a NULL Object pointer returned if any unexpected items are encountered. As AST continues to be developed, new attributes are added occasionally to selected classes. If an older version of AST is used to read external Object descriptions created by a more recent version of AST, then the Channel class will, by default, ignore the new attributes, using the remaining attributes to construct the Object. This is usually a good thing. However, since external Object descriptions are often stored in plain text, it is possible to edit them using a text editor. This gives rise to the possibility of genuine errors in the description due to finger-slips, typos, or simple mis-understanding. Such inappropriate attributes will be ignored if Strict is left at its default zero value. This will cause the mis-spelled attribute to revert to its default value, potentially causing subtle changes in the behaviour of application software. If such an effect is suspected, the Strict attribute can be set non-zero, resulting in the erroneous attribute being identified in an error message. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The returned KeyMap will contain warnings for all conditions listed in the \htmlref{Warnings}{Warnings} attribute. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ Reports conversion errors that result in what are usally insignificant changes. } } \sstreturnedvalue{ \sstsubsection{ astWarnings() }{ A pointer to the KeyMap holding the warning messages, or NULL if no warnings were issued during the previous read operation. } } \sstnotes{ \sstitemlist{ \sstitem The returned KeyMap uses keys of the form \texttt{"} Warning\_1\texttt{"} , \texttt{"} Warning\_2\texttt{"} , etc. \sstitem A value of NULL will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. } } } \sstroutine{ astWatch }{ Identify a new error status variable for the AST library }{ \sstdescription{ This function allows a new error status variable to be accessed by the AST library when checking for and reporting error conditions. By default, the library uses an internal integer error status which is set to an error value if an error occurs. Use of astWatch allows the internal error status to be replaced by an integer variable of your choosing, so that the AST library can share its error status directly with other code which uses the same error detection convention. If an alternative error status variable is supplied, it is used by all related AST functions and macros (e.g. \htmlref{astOK}{astOK}, \htmlref{astStatus}{astStatus} and \htmlref{astClearStatus}{astClearStatus}). } \sstsynopsis{ int $*$astWatch( int $*$status\_ptr ) } \sstparameters{ \sstsubsection{ status\_ptr }{ Pointer to an int whose value is to be used subsequently as the AST inherited status value. If a NULL pointer is supplied, the AST library will revert to using its own internal error status. } } \sstreturnedvalue{ \sstsubsection{ astWatch() }{ Address of the previous error status variable. This may later be passed back to astWatch to restore the previous behaviour of the library. (Note that on the first invocation of astWatch the returned value will be the address of the internal error status variable.) } } \sstnotes{ \sstitemlist{ \sstitem This function is not available in the FORTRAN 77 interface to the AST library. } } } \sstroutine{ astWcsMap }{ Create a WcsMap }{ \sstdescription{ This function creates a new \htmlref{WcsMap}{WcsMap} and optionally initialises its attributes. A WcsMap is used to represent sky coordinate projections as described in the (draft) FITS world coordinate system (FITS-WCS) paper by E.W. Griesen and M. Calabretta (A \& A, in preparation). This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa). A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection plane\texttt{"} coordinates. These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS). The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be associated with each axis. These specify the precise form of the projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is the integer axis index (starting at 1), and m is an integer \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper. } \sstsynopsis{ AstWcsMap $*$astWcsMap( int ncoord, int type, int lonax, int latax, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). This must be at least 2. The same number is applicable to both input and output points. } \sstsubsection{ type }{ The type of FITS-WCS projection to apply. This should be given using a macro value such as AST\_\_TAN (for a tangent plane projection), where the characters following the double underscore give the projection type code (in upper case) as used in the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword. You should consult the FITS-WCS paper for a list of the available projections. The additional code of AST\_\_TPN can be supplied which represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper. } \sstsubsection{ lonax }{ The index of the longitude axis. This should lie in the range 1 to \texttt{"} ncoord\texttt{"} . } \sstsubsection{ latax }{ The index of the latitude axis. This should lie in the range 1 to \texttt{"} ncoord\texttt{"} and be distinct from \texttt{"} lonax\texttt{"} . } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new WcsMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. If the sky projection to be implemented requires projection parameter values to be set, then this should normally be done here via the PVi\_m attribute (see the \texttt{"} Examples\texttt{"} section). Setting values for these parameters is mandatory if they do not have default values (as defined in the FITS-WCS paper). } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astWcsMap() }{ A pointer to the new WcsMap. } } \sstexamples{ \sstexamplesubsection{ wcsmap = astWcsMap( 2, AST\_\_MER, 1, 2, \texttt{"} \texttt{"} ); }{ Creates a WcsMap that implements a FITS-WCS Mercator projection on pairs of coordinates, with coordinates 1 and 2 representing the longitude and latitude respectively. Note that the FITS-WCS Mercator projection does not require any projection parameters. } \sstexamplesubsection{ wcsmap = astWcsMap( 3, AST\_\_COE, 2, 3, \texttt{"} PV3\_1=40.0\texttt{"} ); }{ Creates a WcsMap that implements a FITS-WCS conical equal area projection. The WcsMap acts on points in a 3-dimensional space; coordinates 2 and 3 represent longitude and latitude respectively, while the values of coordinate 1 are copied unchanged. \htmlref{Projection}{Projection} parameter 1 associatyed with the latitude axis (corresponding to FITS keyword \texttt{"} PV3\_1\texttt{"} ) is required and has no default, so is set explicitly to 40.0 degrees. Projection parameter 2 (corresponding to FITS keyword \texttt{"} PV3\_2\texttt{"} ) is required but has a default of zero, so need not be specified. } } \sstnotes{ \sstitemlist{ \sstitem The forward transformation of a WcsMap converts between FITS-WCS \texttt{"} native spherical\texttt{"} and \texttt{"} relative physical\texttt{"} coordinates, while the inverse transformation converts in the opposite direction. This arrangement may be reversed, if required, by using \htmlref{astInvert}{astInvert} or by setting the \htmlref{Invert}{Invert} attribute to a non-zero value. \sstitem If any set of coordinates cannot be transformed (for example, many projections do not cover the entire celestial sphere), then a WcsMap will yield coordinate values of AST\_\_BAD. \sstitem The validity of any projection parameters given via the PVi\_m parameter in the \texttt{"} options\texttt{"} string is not checked by this function. However, their validity is checked when the resulting WcsMap is used to transform coordinates, and an error will result if the projection parameters do not satisfy all the required constraints (as defined in the FITS-WCS paper). \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astWinMap }{ Create a WinMap }{ \sstdescription{ This function creates a new \htmlref{WinMap}{WinMap} and optionally initialises its attributes. A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes). A WinMap is specified by giving the coordinates of two opposite corners (A and B) of the window in both the input and output coordinate systems. } \sstsynopsis{ AstWinMap $*$astWinMap( int ncoord, const double ina[], const double inb[], const double outa[], const double outb[], const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ ina }{ An array containing the \texttt{"} ncoord\texttt{"} coordinates of corner A of the window in the input coordinate system. } \sstsubsection{ inb }{ An array containing the \texttt{"} ncoord\texttt{"} coordinates of corner B of the window in the input coordinate system. } \sstsubsection{ outa }{ An array containing the \texttt{"} ncoord\texttt{"} coordinates of corner A of the window in the output coordinate system. } \sstsubsection{ outb }{ An array containing the \texttt{"} ncoord\texttt{"} coordinates of corner B of the window in the output coordinate system. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new WinMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astWinMap() }{ A pointer to the new WinMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \sstroutine{ astWrite }{ Write an Object to a Channel }{ \sstdescription{ This function writes an \htmlref{Object}{Object} to a \htmlref{Channel}{Channel}, appending it to any previous Objects written to that Channel. } \sstsynopsis{ int astWrite( AstChannel $*$this, AstObject $*$object ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the Channel. } \sstsubsection{ object }{ Pointer to the Object which is to be written. } } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather than the native AST encoding, then storing values in the FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking astWrite can help to produce a successful write. } } \sstreturnedvalue{ \sstsubsection{ astWrite() }{ The number of Objects written to the Channel by this invocation of astWrite (normally, this will be one). } } \sstnotes{ \sstitemlist{ \sstitem A value of zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason. \sstitem Invoking this function will usually cause the sink function associated with the channel to be called in order to transfer a textual description of the supplied object to some external data store. However, the FitsChan class behaves differently. Invoking this function on a FitsChan causes new FITS header cards to be added to an internal buffer (the sink function is not invoked). This buffer is written out through the sink function only when the FitsChan is deleted. } } } \sstroutine{ astWriteFits }{ Write out all cards in a FitsChan to the sink function }{ \sstdescription{ This function writes out all cards currently in the \htmlref{FitsChan}{FitsChan}. If the \htmlref{SinkFile}{SinkFile} attribute is set, they will be written out to the specified sink file. Otherwise, they will be written out using the sink function specified when the FitsChan was created. All cards are then deleted from the FitsChan. } \sstsynopsis{ void astWriteFits( AstFitsChan $*$this ) } \sstparameters{ \sstsubsection{ this }{ Pointer to the FitsChan. } } \sstnotes{ \sstitemlist{ \sstitem If the SinkFile is unset, and no sink function is available, this method simply empties the FitsChan, and is then equivalent to \htmlref{astEmptyFits}{astEmptyFits}. \sstitem This method attempt to execute even if an error has occurred previously. } } } \sstroutine{ astXmlChan }{ Create an XmlChan }{ \sstdescription{ This function creates a new \htmlref{XmlChan}{XmlChan} and optionally initialises its attributes. A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O operations. Writing an \htmlref{Object}{Object} to an XmlChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description. Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting XML text. By default, however, an XmlChan will read from standard input and write to standard output. Alternatively, an XmlChan can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstsynopsis{ AstXmlChan $*$astXmlChan( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... ) } \sstparameters{ \sstsubsection{ source }{ Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. If no value has been set for the SourceFile attribute, this function will be used by the XmlChan to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read. If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile attribute, the XmlChan will read from standard input instead. } \sstsubsection{ sink }{ Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. If no value has been set for the SinkFile attribute, this function will be used by the XmlChan to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store. If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile attribute, the XmlChan will write to standard output instead. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new XmlChan. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astXmlChan() }{ A pointer to the new XmlChan. } } \sstnotes{ \sstitemlist{ \sstitem If the external data source or sink uses a character encoding other than ASCII, the supplied source and sink functions should translate between the external character encoding and the internal ASCII encoding used by AST. \sstitem 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. } } } \sstroutine{ astZoomMap }{ Create a ZoomMap }{ \sstdescription{ This function creates a new \htmlref{ZoomMap}{ZoomMap} and optionally initialises its attributes. A ZoomMap is a \htmlref{Mapping}{Mapping} which \texttt{"} zooms\texttt{"} a set of points about the origin by multiplying all coordinate values by the same scale factor (the inverse transformation is performed by dividing by this scale factor). } \sstsynopsis{ AstZoomMap $*$astZoomMap( int ncoord, double zoom, const char $*$options, ... ) } \sstparameters{ \sstsubsection{ ncoord }{ The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). The same number is applicable to both input and output points. } \sstsubsection{ zoom }{ Initial scale factor by which coordinate values should be multiplied (by the forward transformation) or divided (by the inverse transformation). This factor may subsequently be changed via the ZoomMap\texttt{'} s \htmlref{Zoom}{Zoom} attribute. It may be positive or negative, but should not be zero. } \sstsubsection{ options }{ Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new ZoomMap. The syntax used is identical to that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. } \sstsubsection{ ... }{ If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then an optional list of additional 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 function (and for the C \texttt{"} printf\texttt{"} function). } } \sstreturnedvalue{ \sstsubsection{ astZoomMap() }{ A pointer to the new ZoomMap. } } \sstnotes{ \sstitemlist{ \sstitem A null \htmlref{Object}{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. } } \sstdiytopic{ Status Handling }{ The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: \texttt{"} int $*$status\texttt{"} . } } \normalsize \cleardoublepage \section{\label{ss:attributedescriptions}AST Attribute Descriptions} \small \sstroutine{ Abbrev(axis) }{ Abbreviate leading fields within numerical axis labels? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether matching leading fields should be removed from adjacent numerical axis labels. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} Abbrev(2)=0\texttt{"} specifies that matching leading fields should not be removed on the second axis. If the Abbrev value of a Plot is non-zero (the default), then leading fields will be removed from adjacent axis labels if they are equal. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} Abbrev\texttt{"} instead of \texttt{"} Abbrev(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Abbrev(1) value. } } } \sstroutine{ Adaptive }{ Should the area adapt to changes in the coordinate system? }{ \sstdescription{ The coordinate system represented by a \htmlref{Region}{Region} may be changed by assigning new values to attributes such as \htmlref{System}{System}, Unit, etc. For instance, a Region representing an area on the sky in ICRS coordinates may have its System attribute changed so that it represents (say) Galactic coordinates instead of ICRS. This attribute controls what happens when the coordinate system represented by a Region is changed in this way. If Adaptive is non-zero (the default), then area represented by the Region adapts to the new coordinate system. That is, the numerical values which define the area represented by the Region are changed by mapping them from the old coordinate system into the new coordinate system. Thus the Region continues to represent the same physical area. If Adaptive is zero, then area represented by the Region does not adapt to the new coordinate system. That is, the numerical values which define the area represented by the Region are left unchanged. Thus the physical area represented by the Region will usually change. As an example, consider a Region describe a range of wavelength from 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region is changed from Angstrom to \texttt{"} nm\texttt{"} (nanometre), what happens depends on the setting of Adaptive. If Adaptive is non-zero, the \htmlref{Mapping}{Mapping} from the old to the new coordinate system is found. In this case it is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). This Mapping is then used to modify the numerical values within the Region, changing 2000 to 200 and 4000 to 400. Thus the modified region represents 200 nm to 400 nm, the same physical space as the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive had been zero, then the numerical values would not have been changed, resulting in the final Region representing 2000 nm to 4000 nm. Setting Adaptive to zero can be necessary if you want correct inaccurate attribute settings in an existing Region. For instance, when creating a Region you may not know what \htmlref{Epoch}{Epoch} value to use, so you would leave Epoch unset resulting in some default value being used. If at some later point in the application, the correct Epoch value is determined, you could assign the correct value to the Epoch attribute. However, you would first need to set Adaptive temporarily to zero, because otherwise the area represented by the Region would be Mapped from the spurious default Epoch to the new correct Epoch, which is not what is required. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ AlignOffset }{ Align SkyFrames using the offset coordinate system? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{SkyFrame}{SkyFrame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) SkyFrame. It determines the coordinate system in which the two SkyFrames are aligned if a match occurs. If the template and target SkyFrames both have defined offset coordinate systems (i.e. the \htmlref{SkyRefIs}{SkyRefIs} attribute is set to either \texttt{"} Origin\texttt{"} or \texttt{"} Pole\texttt{"} ), and they both have a non-zero value for AlignOffset, then alignment occurs within the offset coordinate systems (that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). If either the template or target SkyFrame has zero (the default value) for AlignOffset, or if either SkyFrame has SkyRefIs set to \texttt{"} Ignored\texttt{"} , then alignment occurring within the coordinate system specified by the \htmlref{AlignSystem}{AlignSystem} attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ AlignSideBand }{ Should the SideBand attribute be taken into account when aligning this \htmlref{DSBSpecFrame}{DSBSpecFrame} with another DSBSpecFrame? }{ \sstdescription{ This attribute controls how a DSBSpecFrame behaves when an attempt is made to align it with another DSBSpecFrame using \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}. If both DSBSpecFrames have a non-zero value for AlignSideBand, the value of the \htmlref{SideBand}{SideBand} attribute in each DSBSpecFrame is used so that alignment occurs between sidebands. That is, if one DSBSpecFrame represents USB and the other represents LSB then astFindFrame and astConvert will recognise that the DSBSpecFrames represent different sidebands and will take this into account when constructing the \htmlref{Mapping}{Mapping} that maps positions in one DSBSpecFrame into the other. If AlignSideBand in either DSBSpecFrame is set to zero, then the values of the SideBand attributes are ignored. In the above example, this would result in a frequency in the first DSBSpecFrame being mapped onto the same frequency in the second DSBSpecFrame, even though those frequencies refer to different sidebands. In other words, if either AlignSideBand attribute is zero, then the two DSBSpecFrames aligns like basic SpecFrames. The default value for AlignSideBand is zero. When astFindFrame or astConvert is used on two DSBSpecFrames (potentially describing different spectral coordinate systems and/or sidebands), it returns a Mapping which can be used to transform a position in one DSBSpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the target\texttt{'} s current sideband (given by its SideBand attribute) to the observed sideband (whether USB or LSB). If the target already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted. \sstitem Map the values from the spectral system of the target to the spectral system of the template. This Mapping takes into account all the inherited \htmlref{SpecFrame}{SpecFrame} attributes such as \htmlref{System}{System}, \htmlref{StdOfRest}{StdOfRest}, Unit, etc. \sstitem If both DSBSpecFrames have a value of 1 for the AlignSideBand attribute, map values from the result\texttt{'} s observed sideband to the result\texttt{'} s current sideband (given by its SideBand attribute). If the result already represents the observed sideband, this step will leave the values unchanged. If either of the two DSBSpecFrames have a value of zero for its AlignSideBand attribute, then this step is omitted. } } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ AlignSpecOffset }{ Align SpecFrames using the offset coordinate system? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) SpecFrame. It determines whether alignment occurs between the offset values defined by the current value of the SpecOffset attribute, or between the corresponding absolute spectral values. The default value of zero results in the two SpecFrames being aligned so that a given absolute spectral value in one is mapped to the same absolute value in the other. A non-zero value results in the SpecFrames being aligned so that a given offset value in one is mapped to the same offset value in the other. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ AlignStdOfRest }{ Standard of rest to use when aligning SpecFrames }{ \sstdescription{ This attribute controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) SpecFrame. It identifies the standard of rest in which alignment is to occur. See the \htmlref{StdOfRest}{StdOfRest} attribute for a desription of the values which may be assigned to this attribute. The default AlignStdOfRest value is \texttt{"} Helio\texttt{"} (heliographic). When astFindFrame or astConvert is used on two SpecFrames (potentially describing different spectral coordinate systems), it returns a \htmlref{Mapping}{Mapping} which can be used to transform a position in one SpecFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem Map values from the system used by the target (wavelength, apparent radial velocity, etc) to the system specified by the \htmlref{AlignSystem}{AlignSystem} attribute, using the target\texttt{'} s rest frequency if necessary. \sstitem Map these values from the target\texttt{'} s standard of rest to the standard of rest specified by the AlignStdOfRest attribute, using the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{RefDec}{RefDec} and \htmlref{RefRA}{RefRA} attributes of the target to define the two standards of rest. \sstitem Map these values from the standard of rest specified by the AlignStdOfRest attribute, to the template\texttt{'} s standard of rest, using the Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the template to define the two standards of rest. \sstitem Map these values from the system specified by the AlignSystem attribute, to the system used by the template, using the template\texttt{'} s rest frequency if necessary. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ AlignSystem }{ Coordinate system in which to align the Frame }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) Frame. It identifies the coordinate system in which the two Frames will be aligned by the match. The values which may be assigned to this attribute, and its default value, depend on the class of Frame and are described in the \texttt{"} Applicability\texttt{"} section below. In general, the AlignSystem attribute will accept any of the values which may be assigned to the \htmlref{System}{System} attribute. The \htmlref{Mapping}{Mapping} returned by AST\_FINDFRAME or AST\_CONVERT will use the coordinate system specified by the AlignSystem attribute as an intermediate coordinate system. The total returned Mapping will first map positions from the first Frame into this intermediate coordinate system, using the attributes of the first Frame. It will then map these positions from the intermediate coordinate system into the second Frame, using the attributes of the second Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The AlignSystem attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The AlignSystem attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The AlignSystem attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The default AlignSystem attribute for a SkyFrame is \texttt{"} ICRS\texttt{"} . } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The default AlignSystem attribute for a SpecFrame is \texttt{"} Wave\texttt{"} (wavelength). } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The default AlignSystem attribute for a TimeFrame is \texttt{"} MJD\texttt{"} . } } } \sstroutine{ AlignTimeScale }{ Time scale to use when aligning TimeFrames }{ \sstdescription{ This attribute controls how a \htmlref{TimeFrame}{TimeFrame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) TimeFrame. It identifies the time scale in which alignment is to occur. See the \htmlref{TimeScale}{TimeScale} attribute for a desription of the values which may be assigned to this attribute. The default AlignTimeScale value depends on the current value of TimeScale: if TimeScale is UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all other TimeScales the default is TAI. When astFindFrame or astConvert is used on two TimeFrames (potentially describing different time coordinate systems), it returns a \htmlref{Mapping}{Mapping} which can be used to transform a position in one TimeFrame into the corresponding position in the other. The Mapping is made up of the following steps in the indicated order: \sstitemlist{ \sstitem Map values from the system used by the target (MJD, JD, etc) to the system specified by the \htmlref{AlignSystem}{AlignSystem} attribute. \sstitem Map these values from the target\texttt{'} s time scale to the time scale specified by the AlignTimeScale attribute. \sstitem Map these values from the time scale specified by the AlignTimeScale attribute, to the template\texttt{'} s time scale. \sstitem Map these values from the system specified by the AlignSystem attribute, to the system used by the template. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } } \sstroutine{ AllVariants }{ A list of the variant Mappings associated with the current Frame }{ \sstdescription{ This attrbute gives a space separated list of the names of all the variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the current Frame. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ All FrameSets have this attribute. } } } \sstroutine{ AllWarnings }{ A list of all currently available condition names }{ \sstdescription{ This read-only attribute is a space separated list of all the conditions names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed below. } \sstattributetype{ String, read-only } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } \sstdiytopic{ Conditions }{ The following conditions are currently recognised (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a non-Native encoded FitsChan if an unknown celestial co-ordinate system is specified by the CTYPE keywords. \sstitem \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if an illegal algorithm code is specified by a CTYPE keyword, and the illegal code can be converted to an equivalent legal code. \sstitem \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is encountered that contains an illegal character (i.e. one not allowed by the FITS standard). \sstitem \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword cannot be determined from the content of the header card. \sstitem \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if the latitude of the reference point has an absolute value greater than 90 degrees. The actual absolute value used is set to exactly 90 degrees in these cases. \sstitem \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the transformation from pixel offsets to intermediate world coordinates cannot be inverted. This matrix describes the scaling, rotation, shear, etc., applied to the pixel axes, and is specified by keywords such as PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable if any rows or columns consist entirely of zeros. The FITS-WCS Paper I \texttt{"} Representation of World Coordinates in FITS\texttt{"} by Greisen \& Calabretta requires that this matrix be invertable. Many operations (such as grid plotting) will not be possible if the matrix cannot be inverted. \sstitem \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found that refers to a projection parameter that is not used by the projection type specified by CTYPE, or the PV values are otherwise inappropriate for the projection type. \sstitem \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if it is not possible to convert the value of a FITS keywords to the expected type. For instance, this can occur if the FITS header contains a string value for a keyword which should have a floating point value, or if the keyword has no value at all (i.e. is a comment card). \sstitem \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a non-Native encoded FitsChan if any of the CTYPE keywords specify an unsupported distortion code using the \texttt{"} 4-3-3\texttt{"} format specified in FITS-WCS paper IV. Such distortion codes are ignored. \sstitem \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used within \htmlref{astRead}{astRead}, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoEquinox\texttt{"} : This condition arises if a default equinox value is used within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoRadesys\texttt{"} : This condition arises if a default reference frame is used for an equatorial co-ordinate system within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoLonpole\texttt{"} : This condition arises if a default value is used for the LONPOLE keyword within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoLatpole\texttt{"} : This condition arises if a default value is used for the LATPOLE keyword within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} NoMjd-obs\texttt{"} : This condition arises if a default value is used for the date of observation within astRead, due to no value being present in the supplied FitsChan. This condition is only tested for when using non-Native encodings. \sstitem \texttt{"} Tnx\texttt{"} : This condition arises if a FrameSet is read from a FITS header containing an IRAF \texttt{"} TNX\texttt{"} projection which includes terms not supproted by AST. Such terms are ignored and so the resulting FrameSet may be inaccurate. \sstitem \texttt{"} Zpx\texttt{"} : This condition arises if a FrameSet is read from a FITS header containing an IRAF \texttt{"} ZPX\texttt{"} projection which includes \texttt{"} lngcor\texttt{"} or \texttt{"} latcor\texttt{"} correction terms. These terms are not supported by AST and are ignored. The resulting FrameSet may therefore be inaccurate. } } } \sstroutine{ AsTime(axis) }{ Format celestal coordinates as times? }{ \sstdescription{ This attribute specifies the default style of formatting to be used (e.g. by \htmlref{astFormat}{astFormat}) for the celestial coordinate values described by a \htmlref{SkyFrame}{SkyFrame}. It takes a separate boolean value for each SkyFrame axis so that, for instance, the setting \texttt{"} AsTime(2)=0\texttt{"} specifies the default formatting style for celestial latitude values. If the AsTime attribute for a SkyFrame axis is zero, then coordinates on that axis will be formatted as angles by default (using degrees, minutes and seconds), otherwise they will be formatted as times (using hours, minutes and seconds). The default value of AsTime is chosen according to the sky coordinate system being represented, as determined by the SkyFrame\texttt{'} s \htmlref{System}{System} attribute. This ensures, for example, that right ascension values will be formatted as times by default, following normal conventions. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The AsTime attribute operates by changing the default value of the corresponding \htmlref{Format(axis)}{Format(axis)} attribute. This, in turn, may also affect the value of the \htmlref{Unit(axis)}{Unit(axis)} attribute. \sstitem Only the default style of formatting is affected by the AsTime value. If an explicit Format(axis) value is set, it will over-ride any effect from the AsTime attribute. } } } \sstroutine{ Base }{ FrameSet base Frame index }{ \sstdescription{ This attribute gives the index of the \htmlref{Frame}{Frame} which is to be regarded as the \texttt{"} base\texttt{"} Frame within a \htmlref{FrameSet}{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 \htmlref{Domain}{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. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Inverting a FrameSet (inverting the boolean sense of its \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will interchange the values of its Base and \htmlref{Current}{Current} attributes. } } } \sstroutine{ Border }{ Draw a border around valid regions of a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether a border is drawn around regions corresponding to the valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{astBorder}{astBorder}). If the Border value of a Plot is non-zero, then this border will be drawn as part of the grid. Otherwise, the border is not drawn (although axis labels and tick marks will still appear, unless other relevant Plot attributes indicate that they should not). The default behaviour is to draw the border if tick marks and numerical labels will be drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit it otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ Bottom(axis) }{ Lowest axis value to display }{ \sstdescription{ This attribute gives the lowest axis value to be displayed (for instance, by the \htmlref{astGrid}{astGrid} method). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ The default supplied by the Frame class is to display all axis values, without any limit. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Bottom value to -90 degrees for latitude axes, and 0 degrees for co-latitude axes. The default for longitude axes is to display all axis values. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ Bounded }{ Is the Region bounded? }{ \sstdescription{ This is a read-only attribute indicating if the \htmlref{Region}{Region} is bounded. A Region is bounded if it is contained entirely within some finite-size bounding box. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ CDMatrix }{ Use CDi\_j keywords to represent pixel scaling, rotation, etc? }{ \sstdescription{ This attribute is a boolean value which specifies how the linear transformation from pixel coordinates to intermediate world coordinates should be represented within a \htmlref{FitsChan}{FitsChan} when using FITS-WCS encoding. This transformation describes the scaling, rotation, shear, etc., of the pixel axes. If the attribute has a non-zero value then the transformation is represented by a set of CDi\_j keywords representing a square matrix (where \texttt{"} i\texttt{"} is the index of an intermediate world coordinate axis and \texttt{"} j\texttt{"} is the index of a pixel axis). If the attribute has a zero value the transformation is represented by a set of PCi\_j keywords (which also represent a square matrix) together with a corresponding set of CDELTi keywords representing the axis scalings. See FITS-WCS paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by M. Calabretta \& E.W. Greisen, for a complete description of these two schemes. The default value of the CDMatrix attribute is determined by the contents of the FitsChan at the time the attribute is accessed. If the FitsChan contains any CDi\_j keywords then the default value is non-zero. Otherwise it is zero. Note, reading a \htmlref{FrameSet}{FrameSet} from a FitsChan will in general consume any CDi\_j keywords present in the FitsChan. Thus the default value for CDMatrix following a read will usually be zero, even if the FitsChan originally contained some CDi\_j keywords. This behaviour is similar to that of the \htmlref{Encoding}{Encoding} attribute, the default value for which is determined by the contents of the FitsChan at the time the attribute is accessed. If you wish to retain the original value of the CDMatrix attribute (that is, the value before reading the FrameSet) then you should enquire the default value before doing the read, and then set that value explicitly. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CarLin }{ Ignore spherical rotations on CAR projections? }{ \sstdescription{ This attribute is a boolean value which specifies how FITS \texttt{"} CAR\texttt{"} (plate carree, or \texttt{"} Cartesian\texttt{"} ) projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero (the default), it is assumed that the CAR projection conforms to the conventions described in the FITS world coordinate system (FITS-WCS) paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by M. Calabretta \& E.W. Greisen. If CarLin is non-zero, then these conventions are ignored, and it is assumed that the mapping from pixel coordinates to celestial coordinates is a simple linear transformation (hence the attribute name \texttt{"} CarLin\texttt{"} ). This is appropriate for some older FITS data which claims to have a \texttt{"} CAR\texttt{"} projection, but which in fact do not conform to the conventions of the FITS-WCS paper. The FITS-WCS paper specifies that headers which include a CAR projection represent a linear mapping from pixel coordinates to \texttt{"} native spherical coordinates\texttt{"} , NOT celestial coordinates. An extra mapping is then required from native spherical to celestial. This mapping is a 3D rotation and so the overall \htmlref{Mapping}{Mapping} from pixel to celestial coordinates is NOT linear. See the FITS-WCS papers for further details. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } } \sstroutine{ Card }{ Index of current FITS card in a FitsChan }{ \sstdescription{ This attribute gives the index of the \texttt{"} current\texttt{"} FITS header card within a \htmlref{FitsChan}{FitsChan}, the first card having an index of 1. The choice of current card affects the behaviour of functions that access the contents of the FitsChan, such as \htmlref{astDelFits}{astDelFits}, \htmlref{astFindFits}{astFindFits} and \htmlref{astPutFits}{astPutFits}. A value assigned to Card will position the FitsChan at any desired point, so that a particular card within it can be accessed. Alternatively, the value of Card may be enquired in order to determine the current position of a FitsChan. The default value of Card is 1. This means that clearing this attribute (using \htmlref{astClear}{astClear}) effectively \texttt{"} rewinds\texttt{"} the FitsChan, so that the first card is accessed next. If Card is set to a value which exceeds the total number of cards in the FitsChan (as given by its \htmlref{Ncard}{Ncard} attribute), it is regarded as pointing at the \texttt{"} end-of-file\texttt{"} . In this case, the value returned in response to an enquiry is always one more than the number of cards in the FitsChan. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardComm }{ The comment for the current card in a FitsChan }{ \sstdescription{ This attribute gives the comment for the current card of the \htmlref{FitsChan}{FitsChan}. A zero-length string is returned if the card has no comment. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardName }{ The keyword name of the current card in a FitsChan }{ \sstdescription{ This attribute gives the name of the keyword for the current card of the \htmlref{FitsChan}{FitsChan}. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ CardType }{ The data type of the current card in a FitsChan }{ \sstdescription{ This attribute gives the data type of the keyword value for the current card of the \htmlref{FitsChan}{FitsChan}. It will be one of the following integer constants: AST\_\_NOTYPE, AST\_\_COMMENT, AST\_\_INT, AST\_\_FLOAT, AST\_\_STRING, AST\_\_COMPLEXF, AST\_\_COMPLEXI, AST\_\_LOGICAL, AST\_\_CONTINUE, AST\_\_UNDEF. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Class }{ Object class name }{ \sstdescription{ This attribute gives the name of the class to which an \htmlref{Object}{Object} belongs. } \sstattributetype{ Character string, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Clean }{ Remove cards used whilst reading even if an error occurs? }{ \sstdescription{ This attribute indicates whether or not cards should be removed from the \htmlref{FitsChan}{FitsChan} if an error occurs within \htmlref{astRead}{astRead}. A succesful read on a FitsChan always results in the removal of the cards which were involved in the description of the returned \htmlref{Object}{Object}. However, in the event of an error during the read (for instance if the cards in the FitsChan have illegal values, or if some required cards are missing) no cards will be removed from the FitsChan if the Clean attribute is zero (the default). If Clean is non-zero then any cards which were used in the aborted attempt to read an object will be removed. This provides a means of \texttt{"} cleaning\texttt{"} a FitsChan of WCS related cards which works even in the event of the cards not forming a legal WCS description. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Clip }{ Clip lines and/or markers at the Plot boundary? }{ \sstdescription{ This attribute controls whether curves and markers are clipped at the boundary of the graphics box specified when the \htmlref{Plot}{Plot} was created. A value of 3 implies both markers and curves are clipped at the Plot boundary. A value of 2 implies markers are clipped, but not curves. A value of 1 implies curves are clipped, but not markers. A value of zero implies neither curves nor markers are clipped. The default value is 1. Note, this attributes controls only the clipping performed internally within AST. The underlying graphics system may also apply clipping. In such cases, removing clipping using this attribute does not guarantee that no clipping will be visible in the final plot. The \htmlref{astClip}{astClip} function can be used to establish generalised clipping within arbitrary regions of the Plot. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ ClipOp }{ Combine Plot clipping limits using a boolean OR? }{ \sstdescription{ This attribute controls how the clipping limits specified for each axis of a \htmlref{Plot}{Plot} (using the \htmlref{astClip}{astClip} function) are combined. This, in turn, determines which parts of the graphical output will be visible. If the ClipOp attribute of a Plot is zero (the default), graphical output is visible only if it satisfies the clipping limits on all the axes of the clipping \htmlref{Frame}{Frame} (a boolean AND). Otherwise, if ClipOp is non-zero, output is visible if it satisfies the clipping limits on one or more axes (a boolean OR). An important use of this attribute is to allow areas of a Plot to be left clear (e.g. as a background for some text). To achieve this, the lower and upper clipping bounds supplied to astClip should be reversed, and the ClipOp attribute of the Plot should be set to a non-zero value. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ Closed }{ Should the boundary be considered to be inside the region? }{ \sstdescription{ This attribute controls whether points on the boundary of a \htmlref{Region}{Region} are considered to be inside or outside the region. If the attribute value is non-zero (the default), points on the boundary are considered to be inside the region (that is, the Region is \texttt{"} closed\texttt{"} ). However, if the attribute value is zero, points on the bounary are considered to be outside the region. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{PointList}{PointList} }{ The value of the Closed attribute is ignored by PointList regions. If the PointList region has not been negated, then it is always assumed to be closed. If the PointList region has been negated, then it is always assumed to be open. This is required since points have zero volume and therefore consist entirely of boundary. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default Closed value for a CmpRegion is the Closed value of its first component Region. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default Closed value for an Stc is the Closed value of its encapsulated Region. } } } \sstroutine{ Colour(element) }{ Colour index for a Plot element }{ \sstdescription{ This attribute determines the colour index used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Colour(title)=2\texttt{"} causes the Plot title to be drawn using colour index 2. The synonym \texttt{"} Color\texttt{"} may also be used. The range of integer colour indices available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default colour index supplied by this graphics system (normally, this is likely to result in white plotting on a black background, or vice versa). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Colour\texttt{"} instead of \texttt{"} Colour(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Colour(TextLab) value. } } } \sstroutine{ ColumnLenC(column) }{ The largest string length of any value in a column }{ \sstdescription{ This attribute holds the minimum length which a character variable must have in order to be able to store the longest value currently present (at any row) in a specified column of the supplied \htmlref{Table}{Table}. This does not include room for a trailing null character. The required column name should be placed inside the parentheses in the attribute name. If the named column holds vector values, then the attribute value is the length of the longest element of the vector value. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Table }{ All Tables have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the named column holds numerical values, the length returned is the length of the largest string that would be generated if the column values were accessed as strings. } } } \sstroutine{ ColumnLength(column) }{ The number of elements in each value in a column }{ \sstdescription{ This attribute holds the number of elements in each value stored in a named column. Each value can be a scalar (in which case the ColumnLength attribute has a value of 1), or a multi-dimensional array ( in which case the ColumnLength value is equal to the product of the array dimensions). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ ColumnNdim(column) }{ The number of axes spanned by each value in a column }{ \sstdescription{ This attribute holds the number of axes spanned by each value in a column. If each cell in the column is a scalar, ColumnNdim will be zero. If each cell in the column is a 1D spectrum, ColumnNdim will be one. If each cell in the column is a 2D image, ColumnNdim will be two, etc. The required column name should be placed inside the parentheses in the attribute name. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ ColumnType(column) }{ The data type of each value in a column }{ \sstdescription{ This attribute holds a integer value indicating the data type of a named column in a \htmlref{Table}{Table}. This is the data type which was used when the column was added to the Table using \htmlref{astAddColumn}{astAddColumn}. The required column name should be placed inside the parentheses in the attribute name. The attribute value will be one of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for short int), AST\_\_BYTETYPE (for unsigned bytes - i.e. unsigned chars), AST\_\_DOUBLETYPE (for double precision floating point), AST\_\_FLOATTYPE (for single precision floating point), AST\_\_STRINGTYPE (for character string), AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values created by \htmlref{astMapPutU}{astMapPutU}). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Table }{ All Tables have this attribute. } } } \sstroutine{ Comment }{ Include textual comments in output? }{ \sstdescription{ This is a boolean attribute which controls whether textual comments are to be included in the output generated by a \htmlref{Channel}{Channel}. If included, they will describe what each item of output represents. If Comment is non-zero, then comments will be included. If it is zero, comments will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ The default value is non-zero for a normal Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The default value is non-zero for a FitsChan. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value is zero for an XmlChan. } } } \sstroutine{ Current }{ FrameSet current Frame index }{ \sstdescription{ This attribute gives the index of the \htmlref{Frame}{Frame} which is to be regarded as the \texttt{"} current\texttt{"} Frame within a \htmlref{FrameSet}{FrameSet}. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet\texttt{'} s \htmlref{Nframe}{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 \htmlref{Domain}{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. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Inverting a FrameSet (inverting the boolean sense of its \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will interchange the values of its \htmlref{Base}{Base} and Current attributes. } } } \sstroutine{ DSBCentre }{ The central position of interest in a dual sideband spectrum }{ \sstdescription{ This attribute specifies the central position of interest in a dual sideband spectrum. Its sole use is to determine the local oscillator frequency (the frequency which marks the boundary between the lower and upper sidebands). See the description of the \htmlref{IF}{IF} (intermediate frequency) attribute for details of how the local oscillator frequency is calculated. The sideband containing this central position is referred to as the \texttt{"} observed\texttt{"} sideband, and the other sideband as the \texttt{"} image\texttt{"} sideband. The value is accessed as a position in the spectral system represented by the \htmlref{SpecFrame}{SpecFrame} attributes inherited by this class, but is stored internally as topocentric frequency. Thus, if the \htmlref{System}{System} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} is set to \texttt{"} VRAD\texttt{"} , the Unit attribute set to \texttt{"} m/s\texttt{"} and the \htmlref{StdOfRest}{StdOfRest} attribute set to \texttt{"} LSRK\texttt{"} , then values for the DSBCentre attribute should be supplied as radio velocity in units of \texttt{"} m/s\texttt{"} relative to the kinematic LSR (alternative units may be used by appending a suitable units string to the end of the value). This value is then converted to topocentric frequency and stored. If (say) the Unit attribute is subsequently changed to \texttt{"} km/s\texttt{"} before retrieving the current value of the DSBCentre attribute, the stored topocentric frequency will be converted back to LSRK radio velocity, this time in units of \texttt{"} km/s\texttt{"} , before being returned. The default value for this attribute is 30 GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } \sstdiytopic{ Note }{ \sstitemlist{ \sstitem The attributes which define the transformation to or from topocentric frequency should be assigned their correct values before accessing this attribute. These potentially include System, Unit, StdOfRest, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec} and \htmlref{RestFreq}{RestFreq}. } } } \sstroutine{ DefB1950 }{ Use FK4 B1950 as defaults? }{ \sstdescription{ This attribute is a boolean value which specifies a default equinox and reference frame to use when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} with a foreign (i.e. non-native) encoding. It is only used if the FITS header contains RA and DEC axes but contains no information about the reference frame or equinox. If this is the case, then values of FK4 and B1950 are assumed if the DefB1950 attribute has a non-zero value and ICRS is assumed if DefB1950 is zero. The default value for DefB1950 depends on the value of the \htmlref{Encoding}{Encoding} attribute: for FITS-WCS encoding the default is zero, and for all other encodings it is one. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Digits/Digits(axis) }{ Number of digits of precision }{ \sstdescription{ This attribute specifies how many digits of precision are required by default when a coordinate value is formatted for a \htmlref{Frame}{Frame} axis (e.g. using \htmlref{astFormat}{astFormat}). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will over-ride the value for the Frame as a whole. Note that the Digits value acts only as a means of determining a default Format string. Its effects are over-ridden if a Format string is set explicitly for an axis. However, if the Format attribute specifies the precision using the string \texttt{"} .$*$\texttt{"} , then the Digits attribute is used to determine the number of decimal places to produce. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default Digits value supplied by the Frame class is 7. If a value less than 1 is supplied, then 1 is used instead. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Digits attribute of a FrameSet (or one of its axes) is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{Plot}{Plot} }{ The default Digits value used by the Plot class when drawing annotated axis labels is the smallest value which results in all adjacent labels being distinct. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The Digits attribute is ignored when a TimeFrame formats a value as a date and time string (see the Format attribute). } } } \sstroutine{ Direction(axis) }{ Display axis in conventional direction? }{ \sstdescription{ This attribute is a boolean value which suggests how the axes of a \htmlref{Frame}{Frame} should be displayed (e.g.) in graphical output. By default, it has the value one, indicating that they should be shown in the conventional sense (increasing left to right for an abscissa, and bottom to top for an ordinate). If set to zero, this attribute indicates that the direction should be reversed, as would often be done for an astronomical magnitude or a right ascension axis. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ The default Direction value supplied by the Frame class is 1, indicating that all axes should be displayed in the conventional direction. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Direction value to suggest that certain axes (e.g. right ascension) should be plotted in reverse when appropriate. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Direction attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{Plot}{Plot} }{ The Direction attribute of the base Frame in a Plot is set to indicate the sense of the two graphics axes, as implied by the graphics bounding box supplied when the Plot was created. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. \sstitem The Direction attribute does not directly affect the behaviour of the AST library. Instead, it serves as a hint to applications programs about the orientation in which they may wish to display any data associated with the Frame. Applications are free to ignore this hint if they wish. } } } \sstroutine{ Disco }{ PcdMap pincushion/barrel distortion coefficient }{ \sstdescription{ This attribute specifies the pincushion/barrel distortion coefficient used by a \htmlref{PcdMap}{PcdMap}. This coefficient is set when the PcdMap is created, but may later be modified. If the attribute is cleared, its default value is zero, which gives no distortion. For pincushion distortion, the value should be positive. For barrel distortion, it should be negative. Note that the forward transformation of a PcdMap applies the distortion specified by this attribute and the inverse transformation removes this distortion. If the PcdMap is inverted (e.g. using \htmlref{astInvert}{astInvert}), then the forward transformation will remove the distortion and the inverse transformation will apply it. The distortion itself will still be given by the same value of Disco. Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ PcdMap }{ All PcdMaps have this attribute. } } } \sstroutine{ Domain }{ Coordinate system domain }{ \sstdescription{ This attribute contains a string which identifies the physical domain of the coordinate system that a \htmlref{Frame}{Frame} describes. The Domain attribute also controls how a Frame behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It does this by specifying the Domain that the target Frame should have in order to match the template. If the Domain value in the template Frame is set, then only targets with the same Domain value will be matched. If the template\texttt{'} s Domain value is not set, however, then the target\texttt{'} s Domain will be ignored. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default Domain value supplied by the Frame class is an empty string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Domain value to be \texttt{"} SKY\texttt{"} . } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The CmpFrame class re-defines the default Domain value to be of the form \texttt{"} $<$dom1$>$-$<$dom2$>$\texttt{"} , where $<$dom1$>$ and $<$dom2$>$ are the Domains of the two component Frames. If both these Domains are blank, then the string \texttt{"} CMP\texttt{"} is used as the default Domain name. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Domain attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The SpecFrame class re-defines the default Domain value to be \texttt{"} SPECTRUM\texttt{"} . } \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ The DSBSpecFrame class re-defines the default Domain value to be \texttt{"} DSBSPECTRUM\texttt{"} . } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The FluxFrame class re-defines the default Domain value to be \texttt{"} FLUX\texttt{"} . } \sstsubsection{ \htmlref{SpecFluxFrame}{SpecFluxFrame} }{ The FluxFrame class re-defines the default Domain value to be \texttt{"} SPECTRUM-FLUX\texttt{"} . } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Domain value to be \texttt{"} TIME\texttt{"} . } } \sstnotes{ \sstitemlist{ \sstitem All Domain values are converted to upper case and white space is removed before use. } } } \sstroutine{ DrawAxes(axis) }{ Draw axes for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether curves representing coordinate axes should be drawn. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} DrawAxes(2)=0\texttt{"} specifies that no axis should be drawn for the second axis. If drawn, these axis lines will pass through any tick marks associated with numerical labels drawn to mark values on the axes. The location of these tick marks and labels (and hence the axis lines) is determined by the Plot\texttt{'} s \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute. If the DrawAxes value of a Plot is non-zero (the default), then axis lines will be drawn, otherwise they will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem \htmlref{Axis}{Axis} lines are drawn independently of any coordinate grid lines (see the \htmlref{Grid}{Grid} attribute) so grid lines may be used to substitute for axis lines if required. \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the DrawAxes attribute is ignored. \sstitem If no axis is specified, (e.g. \texttt{"} DrawAxes\texttt{"} instead of \texttt{"} DrawAxes(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the DrawAxes(1) value. } } } \sstroutine{ DrawTitle }{ Draw a title for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether a title is drawn. If the DrawTitle value of a \htmlref{Plot}{Plot} is non-zero (the default), then the title will be drawn, otherwise it will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes, assuming a value of zero. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the title is obtained from the Plot\texttt{'} s \htmlref{Title}{Title} attribute. \sstitem The vertical placement of the title can be controlled using the \htmlref{TitleGap}{TitleGap} attribute. } } } \sstroutine{ Dut1 }{ The UT1-UTC correction }{ \sstdescription{ This attribute is used when calculating the Local Apparent Sidereal Time corresponding to \htmlref{SkyFrame}{SkyFrame}\texttt{'} s \htmlref{Epoch}{Epoch} value (used when converting positions to or from the \texttt{"} AzEl\texttt{"} system). It should be set to the difference, in seconds, between the UT1 and UTC timescales at the moment in time represented by the SkyFrame\texttt{'} s Epoch attribute. The value to use is unpredictable and depends on changes in the earth\texttt{'} s rotation speed. Values for UT1-UTC can be obtained from the International Earth Rotation and Reference Systems Service (IERS) at http://www.iers.org/. Currently, the correction is always less than 1 second. This is ensured by the occasional introduction of leap seconds into the UTC timescale. Therefore no great error will usually result if no value is assigned to this attribute (in which case a default value of zero is used). However, it is possible that a decision may be taken at some time in the future to abandon the introduction of leap seconds, in which case the DUT correction could grow to significant sizes. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ All Frames have this attribute. } } } \sstroutine{ Edge(axis) }{ Which edges to label in a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining which edges of a \htmlref{Plot}{Plot} are used for displaying numerical and descriptive axis labels. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} Edge(2)=left\texttt{"} specifies which edge to use to display labels for the second axis. The values \texttt{"} left\texttt{"} , \texttt{"} top\texttt{"} , \texttt{"} right\texttt{"} and \texttt{"} bottom\texttt{"} (or any abbreviation) can be supplied for this attribute. The default is usually \texttt{"} bottom\texttt{"} for the first axis and \texttt{"} left\texttt{"} for the second axis. However, if exterior labelling was requested (see the \htmlref{Labelling}{Labelling} attribute) but cannot be produced using these default Edge values, then the default values will be swapped if this enables exterior labelling to be produced. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes. Instead it uses its own \htmlref{RootCorner}{RootCorner} attribute to determine which edges of the 3D plot to label. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels will be drawn along internal grid lines instead of at the edges of the plotting area (see the Labelling attribute). In this case, the Edge attribute only affects the placement of the descriptive labels (these are drawn at the edges of the plotting area, rather than along the axis lines). } } } \sstroutine{ Encoding }{ System for encoding Objects as FITS headers }{ \sstdescription{ This attribute specifies the encoding system to use when AST Objects are stored as FITS header cards in a \htmlref{FitsChan}{FitsChan}. It affects the behaviour of the \htmlref{astWrite}{astWrite} and \htmlref{astRead}{astRead} functions when they are used to transfer any AST \htmlref{Object}{Object} to or from an external representation consisting of FITS header cards (i.e. whenever a write or read operation is performed using a FitsChan as the I/O \htmlref{Channel}{Channel}). There are several ways (conventions) by which coordinate system information may be represented in the form of FITS headers and the Encoding attribute is used to specify which of these should be used. The encoding options available are outlined in the \texttt{"} Encodings Available\texttt{"} section below, and in more detail in the sections which follow. Encoding systems differ in the range of possible Objects (e.g. classes) they can represent, in the restrictions they place on these Objects (e.g. compatibility with some externally-defined coordinate system model) and in the number of Objects that can be stored together in any particular set of FITS header cards (e.g. multiple Objects, or only a single Object). The choice of encoding also affects the range of external applications which can potentially read and interpret the FITS header cards produced. The encoding options available are not necessarily mutually exclusive, and it may sometimes be possible to store multiple Objects (or the same Object several times) using different encodings within the same set of FITS header cards. This possibility increases the likelihood of other applications being able to read and interpret the information. By default, a FitsChan will attempt to determine which encoding system is already in use, and will set the default Encoding value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical FITS keywords which only occur in particular encodings. For details of how this works, see the \texttt{"} Choice of Default Encoding\texttt{"} section below. If you wish to ensure that a particular encoding system is used, independently of any FITS cards already present, you should set an explicit Encoding value yourself. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } \sstdiytopic{ Encodings Available }{ The Encoding attribute can take any of the following (case insensitive) string values to select the corresponding encoding system: \sstitemlist{ \sstitem \texttt{"} DSS\texttt{"} : Encodes coordinate system information in FITS header cards using the convention developed at the Space Telescope Science Institute (STScI) for the Digitised Sky Survey (DSS) astrometric plate calibrations. The main advantages of this encoding are that FITS images which use it are widely available and it is understood by a number of important and well-established astronomy applications. For further details, see the section \texttt{"} The DSS Encoding\texttt{"} below. \sstitem \texttt{"} FITS-WCS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in the FITS world coordinate system (FITS-WCS) papers by E.W. Greisen, M. Calabretta, et al. The main advantages of this encoding are that it should be understood by any FITS-WCS compliant application and is likely to be adopted widely for FITS data in future. For further details, see the section \texttt{"} The FITS-WCS Encoding\texttt{"} below. \sstitem \texttt{"} FITS-PC\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in an earlier draft of the FITS world coordinate system papers by E.W. Greisen and M. Calabretta. This encoding uses a combination of CDELTi and PCiiijjj keywords to describe the scale and rotation of the pixel axes. This encoding is included to support existing data and software which uses these now superceded conventions. In general, the \texttt{"} FITS-WCS\texttt{"} encoding (which uses CDi\_j or PCi\_j keywords to describe the scale and rotation) should be used in preference to \texttt{"} FITS-PC\texttt{"} . \sstitem \texttt{"} FITS-IRAF\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions described in the document \texttt{"} World Coordinate Systems Representations Within the FITS Format\texttt{"} by R.J. Hanisch and D.G. Wells, 1988. This encoding is currently employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. Its main advantages are that it is a stable convention which approximates to a subset of the propsed FITS-WCS encoding (above). This makes it suitable as an interim method for storing coordinate system information in FITS headers until the FITS-WCS encoding becomes stable. Since many datasets currently use the FITS-IRAF encoding, conversion of data from FITS-IRAF to the final form of FITS-WCS is likely to be well supported. \sstitem \texttt{"} FITS-AIPS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions originally introduced by the AIPS data analysis facility. This is base on the use of CDELTi and CROTAi keuwords to desribe the scale and rotation of each axis. These conventions have been superceded but are still widely used. \sstitem \texttt{"} FITS-AIPS$+$$+$\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions used by the AIPS$+$$+$ project. This is an extension of FITS-AIPS which includes some of the features of FITS-IRAF and FITS-PC. \sstitem \texttt{"} FITS-CLASS\texttt{"} : Encodes coordinate system information in FITS header cards using the conventions used by the CLASS project. CLASS is a software package for reducing single-dish radio and sub-mm spectroscopic data. See the section \texttt{"} CLASS FITS format\texttt{"} at http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/. \sstitem \texttt{"} NATIVE\texttt{"} : Encodes AST Objects in FITS header cards using a convention which is private to the AST library (but adheres to the general FITS standard) and which uses FITS keywords that will not clash with other encoding systems. The main advantages of this are that any class of AST Object may be encoded, and any (reasonable) number of Objects may be stored sequentially in the same FITS header. This makes FITS headers an almost loss-less communication path for passing AST Objects between applications (although all such applications must, of course, make use of the AST library to interpret the information). For further details, see the section \texttt{"} The NATIVE Encoding\texttt{"} below. } } \sstdiytopic{ Choice of Default Encoding }{ If the Encoding attribute of a FitsChan is not set, the default value it takes is determined by the presence of certain critical FITS keywords within the FitsChan. The sequence of decisions used to arrive at the default value is as follows: \sstitemlist{ \sstitem If the FitsChan contains any keywords beginning with the string \texttt{"} BEGAST\texttt{"} , then NATIVE encoding is used, \sstitem Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV keyword and a keyword of the form VELO-xxx, where xxx indicates one of the rest frames used by class (e.g. \texttt{"} VELO-LSR\texttt{"} ), or \texttt{"} VLSR\texttt{"} . \sstitem Otherwise, if the FitsChan contains a CTYPE keyword which represents a spectral axis using the conventions of the AIPS and AIPS$+$$+$ projects (e.g. \texttt{"} FELO-LSR\texttt{"} , etc), then one of FITS-AIPS or FITS-AIPS$+$$+$ encoding is used. FITS-AIPS$+$$+$ is used if any of the keywords CDi\_j, PROJP, LONPOLE or LATPOLE are found in the FitsChan. Otherwise FITS-AIPS is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} PCiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-PC encoding is used, \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} CDiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-IRAF encoding is used, \sstitem Otherwise, if the FitsChan contains a keyword of the form \texttt{"} CDi\_j\texttt{"} , and at least one of RADECSYS, PROJPi, or CjVALi where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-IRAF encoding is used. \sstitem Otherwise, if the FitsChan contains any keywords of the form PROJPi, CjVALi or RADECSYS, where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-PC encoding is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form CROTAi, where \texttt{"} i\texttt{"} is a single digit, then FITS-AIPS encoding is used. \sstitem Otherwise, if the FitsChan contains a keyword of the form CRVALi, where \texttt{"} i\texttt{"} is a single digit, then FITS-WCS encoding is used. \sstitem Otherwise, if the FitsChan contains the \texttt{"} PLTRAH\texttt{"} keyword, then DSS encoding is used, \sstitem Otherwise, if none of these conditions is met (as would be the case when using an empty FitsChan), then NATIVE encoding is used. } Except for the NATIVE and DSS encodings, all the above checks also require that the header contains at least one CTYPE, CRPIX and CRVAL keyword (otherwise the checking process continues to the next case). Setting an explicit value for the Encoding attribute always over-rides this default behaviour. Note that when writing information to a FitsChan, the choice of encoding will depend greatly on the type of application you expect to be reading the information in future. If you do not know this, there may sometimes be an advantage in writing the information several times, using a different encoding on each occasion. } \sstdiytopic{ The DSS Encoding }{ The DSS encoding uses FITS header cards to store a multi-term polynomial which relates pixel positions on a digitised photographic plate to celestial coordinates (right ascension and declination). This encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a \htmlref{FrameSet}{FrameSet} which conforms to the STScI/DSS coordinate system model (this means the \htmlref{Mapping}{Mapping} which relates its base and current Frames must include either a \htmlref{DssMap}{DssMap} or a \htmlref{WcsMap}{WcsMap} with type AST\_\_TAN or AST\_\_TPN). When reading a DSS encoded Object (using astRead), the FitsChan concerned must initially be positioned at the first card (its \htmlref{Card}{Card} attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base \htmlref{Frame}{Frame} of this FrameSet represents DSS pixel coordinates, and the current Frame represents DSS celestial coordinates. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound. When astWrite is used to store a FrameSet using DSS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the DSS model. Specifically, the current Frame must be a FK5 \htmlref{SkyFrame}{SkyFrame}; the projection must be a tangent plane (gnomonic) projection with polynomial corrections conforming to DSS requirements, and north must be parallel to the second base Frame axis. If the simplification process succeeds, a description of the FrameSet is written to the FitsChan using appropriate DSS FITS header cards. The base Frame of the FrameSet is used to form the DSS pixel coordinate system and the current Frame gives the DSS celestial coordinate system. A successful write operation will over-write any existing DSS encoded data in the FitsChan, but will not affect other (non-DSS) header cards. If a destructive read of a DSS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. If an attempt to simplify a FrameSet to conform to the DSS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and astWrite will return zero. No error will result. } \sstdiytopic{ The FITS-WCS Encoding }{ The FITS-WCS convention uses FITS header cards to describe the relationship between pixels in an image (not necessarily 2-dimensional) and one or more related \texttt{"} world coordinate systems\texttt{"} . The FITS-WCS encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSet which conforms to the FITS-WCS model (the FrameSet may, however, contain multiple Frames which will be result in multiple FITS \texttt{"} alternate axis descriptions\texttt{"} ). Details of the use made by this Encoding of the conventions described in the FITS-WCS papers are given in the appendix \texttt{"} FITS-WCS Coverage\texttt{"} of this document. A few main points are described below. The rotation and scaling of the intermediate world coordinate system can be specified using either \texttt{"} CDi\_j\texttt{"} keywords, or \texttt{"} PCi\_j\texttt{"} together with \texttt{"} CDELTi\texttt{"} keywords. When writing a FrameSet to a FitsChan, the the value of the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan determines which system is used. In addition, this encoding supports the \texttt{"} TAN with polynomial correction terms\texttt{"} projection which was included in a draft of the FITS-WCS paper, but was not present in the final version. A \texttt{"} TAN with polynomial correction terms\texttt{"} projection is represented using a WcsMap with type AST\_\_TPN (rather than AST\_\_TAN which is used to represent simple TAN projections). When reading a FITS header, a CTYPE keyword value including a \texttt{"} -TAN\texttt{"} code results in an AST\_\_TPN projection if there are any projection parameters (given by the \htmlref{PVi\_m}{PVi\_m} keywords) associated with the latitude axis, or if there are projection parameters associated with the longitude axis for m greater than 4. When writing a FrameSet to a FITS header, an AST\_\_TPN projection gives rise to a CTYPE value including the normal \texttt{"} -TAN\texttt{"} code, but the projection parameters are stored in keywords with names \texttt{"} QVi\_m\texttt{"} , instead of the usual \texttt{"} PVi\_m\texttt{"} . Since these QV parameters are not part of the FITS-WCS standard they will be ignored by other non-AST software, resulting in the WCS being interpreted as a simple TAN projection without any corrections. This should be seen as an interim solution until such time as an agreed method for describing projection distortions within FITS-WCS has been published. AST extends the range of celestial coordinate systems which may be described using this encoding by allowing the inclusion of \texttt{"} AZ--\texttt{"} and \texttt{"} EL--\texttt{"} as the coordinate specification within CTYPE values. These form a longitude/latitude pair of axes which describe azimuth and elevation. The geographic position of the observer should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS paper III. Currently, a simple model is used which includes diurnal aberration, but ignores atmospheric refraction, polar motion, etc. These may be added in a later release. If an AST SkyFrame that represents offset rather than absolute coordinates (see attribute \htmlref{SkyRefIs}{SkyRefIs}) is written to a FitsChan using FITS-WCS encoding, two alternate axis descriptions will be created. One will describe the offset coordinates, and will use \texttt{"} OFLN\texttt{"} and \texttt{"} OFLT\texttt{"} as the axis codes in the CTYPE keywords. The other will describe absolute coordinates as specified by the \htmlref{System}{System} attribute of the SkyFrame, using the usual CTYPE codes (\texttt{"} RA--\texttt{"} /\texttt{"} DEC-\texttt{"} , etc). In addition, the absolute coordinates description will contain AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the header to be read back into AST in order to reconstruct the original SkyFrame. When reading a FITS-WCS encoded Object (using astRead), the FitsChan concerned must initially be positioned at the first card (its Card attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base Frame of this FrameSet represents FITS-WCS pixel coordinates, and the current Frame represents the physical coordinate system described by the FITS-WCS primary axis descriptions. If secondary axis descriptions are also present, then the FrameSet may contain additional (non-current) Frames which represent these. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound. When astWrite is used to store a FrameSet using FITS-WCS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the FITS-WCS model. If this simplification process succeeds (as it often should, as the model is reasonably flexible), a description of the FrameSet is written to the FitsChan using appropriate FITS header cards. The base Frame of the FrameSet is used to form the FITS-WCS pixel coordinate system and the current Frame gives the physical coordinate system to be described by the FITS-WCS primary axis descriptions. Any additional Frames in the FrameSet may be used to construct secondary axis descriptions, where appropriate. A successful write operation will over-write any existing FITS-WCS encoded data in the FitsChan, but will not affect other (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. Otherwise, the new cards will be inserted following any other FITS-WCS related header cards present or, failing that, in front of the current card (as given by the Card attribute). If an attempt to simplify a FrameSet to conform to the FITS-WCS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and astWrite will return zero. No error will result. } \sstdiytopic{ The FITS-IRAF Encoding }{ The FITS-IRAF encoding can, for most purposes, be considered as a subset of the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following: \sstitemlist{ \sstitem The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic, \sstitem Sky projections can be represented only if any associated projection parameters are set to their default values. \sstitem Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored. } Note that this encoding is provided mainly as an interim measure to provide a more stable alternative to the FITS-WCS encoding until the FITS standard for encoding WCS information is finalised. The name \texttt{"} FITS-IRAF\texttt{"} indicates the general keyword conventions used and does not imply that this encoding will necessarily support all features of the WCS scheme used by IRAF software. Nevertheless, an attempt has been made to support a few such features where they are known to be used by important sources of data. When writing a FrameSet using the FITS-IRAF encoding, axis rotations are specified by a matrix of FITS keywords of the form \texttt{"} CDi\_j\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits. The alternative form \texttt{"} CDiiijjj\texttt{"} , which is also in use, is recognised when reading an Object, but is never written. In addition, the experimental IRAF \texttt{"} ZPX\texttt{"} and \texttt{"} TNX\texttt{"} sky projections will be accepted when reading, but will never be written (the corresponding FITS \texttt{"} ZPN\texttt{"} or \texttt{"} distorted TAN\texttt{"} projection being used instead). However, there are restrictions on the use of these experimental projections. For \texttt{"} ZPX\texttt{"} , longitude and latitude correction surfaces (appearing as \texttt{"} lngcor\texttt{"} or \texttt{"} latcor\texttt{"} terms in the IRAF-specific \texttt{"} WAT\texttt{"} keywords) are not supported. For \texttt{"} TNX\texttt{"} projections, only cubic surfaces encoded as simple polynomials with \texttt{"} half cross-terms\texttt{"} are supported. If an un-usable \texttt{"} TNX\texttt{"} or \texttt{"} ZPX\texttt{"} projection is encountered while reading from a FitsChan, a simpler form of TAN or ZPN projection is used which ignores the unsupported features and may therefore be inaccurate. If this happens, a warning message is added to the contents of the FitsChan as a set of cards using the keyword \texttt{"} ASTWARN\texttt{"} . You should not normally attempt to mix the foreign FITS encodings within the same FitsChan, since there is a risk that keyword clashes may occur. } \sstdiytopic{ The FITS-PC Encoding }{ The FITS-PC encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions. } \sstdiytopic{ The FITS-AIPS Encoding }{ The FITS-AIPS encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following: \sstitemlist{ \sstitem The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic, \sstitem Spectral axes can only be represented if they represent frequency, radio velocity or optical velocity, and are linearly sampled in frequency. In addition, the standard of rest must be LSRK, LSRD, barycentric or geocentric. \sstitem Sky projections can be represented only if any associated projection parameters are set to their default values. \sstitem The AIT, SFL and MER projections can only be written if the CRVAL keywords are zero for both longitude and latitude axes. \sstitem Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored. \sstitem If there are more than 2 axes in the base and current Frames, any rotation must be restricted to the celestial plane, and must involve no shear. } } \sstdiytopic{ The FITS-AIPS$+$$+$ Encoding }{ The FITS-AIPS$+$$+$ encoding is based on the FITS-AIPS encoding, but includes some features of the FITS-IRAF and FITS-PC encodings. Specifically, any celestial projections supported by FITS-PC may be used, including those which require parameterisation, and the axis rotation and scaling may be specified using CDi\_j keywords. When writing a FITS header, rotation will be specified using CROTA/CDELT keywords if possible, otherwise CDi\_j keywords will be used instead. } \sstdiytopic{ The FITS-CLASS Encoding }{ The FITS-CLASS encoding uses the conventions of the CLASS project. These are described in the section \texttt{"} Developer Manual\texttt{"} /\texttt{"} CLASS FITS Format\texttt{"} contained in the CLASS documentation at: http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html. This encoding is similar to FITS-AIPS with the following restrictions: \sstitemlist{ \sstitem When a \htmlref{SpecFrame}{SpecFrame} is created by reading a FITS-CLASS header, the attributes describing the observer\texttt{'} s position (\htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon} and \htmlref{ObsAlt}{ObsAlt}) are left unset because the CLASS encoding does not specify these values. Conversions to or from the topocentric standard of rest will therefore be inaccurate (typically by up to about 0.5 km/s) unless suitable values are assigned to these attributes after the FrameSet has been created. \sstitem When writing a FrameSet to a FITS-CLASS header, the current Frame in the FrameSet must have at least 3 WCS axes, of which one must be a linear spectral axis. The spectral axis in the created header will always describe frequency. If the spectral axis in the supplied FrameSet refers to some other system (e.g. radio velocity, etc), then it will be converted to frequency. \sstitem There must be a pair of celestial axes - either (RA,Dec) or (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000. \sstitem A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) can be used. For AIT and SFL, the reference point must be at the origin of longitude and latitude. For SIN, the associated projection parameters must both be zero. \sstitem No rotation of the celestial axes is allowed, unless the spatial axes are degenerate (i.e. cover only a single pixel). \sstitem The frequency axis in the created header will always describe frequency in the source rest frame. If the supplied FrameSet uses some other standard of rest then suitable conversion will be applied. \sstitem The source velocity must be defined. In other words, the SpecFrame attributes \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} must have been assigned values. \sstitem The frequency axis in a FITS-CLASS header does not represent absolute frequency, but instead represents offsets from the rest frequency in the standard of rest of the source. } When writing a FrameSet out using FITS-CLASS encoding, the current Frame may be temporarily modified if this will allow the header to be produced. If this is done, the associated pixel-$>$WCS Mapping will also be modified to take account of the changes to the Frame. The modifications performed include re-ordering axes (WCS axes, not pixel axes), changing spectral coordinate system and standard of rest, changing the celestial coordinate system and reference equinox, and changing axis units. } \sstdiytopic{ The NATIVE Encoding }{ The NATIVE encoding may be used to store a description of any class of AST Object in the form of FITS header cards, and (for most practical purposes) any number of these Object descriptions may be stored within a single set of FITS cards. If multiple Object descriptions are stored, they are written and read sequentially. The NATIVE encoding makes use of unique FITS keywords which are designed not to clash with keywords that have already been used for other purposes (if a potential clash is detected, an alternative keyword is constructed to avoid the clash). When reading a NATIVE encoded object from a FitsChan (using astRead), FITS header cards are read, starting at the current card (as determined by the Card attribute), until the start of the next Object description is found. This description is then read and converted into an AST Object, for which a pointer is returned. Such a read is always destructive and causes all the FITS header cards involved in the Object description to be removed from the FitsChan, which is left positioned at the following card. The Object returned may be of any class, depending on the description that was read, and other AST routines may be used to validate it (for example, by examining its \htmlref{Class}{Class} or \htmlref{ID}{ID} attribute using astGetC). If further NATIVE encoded Object descriptions exist in the FitsChan, subsequent calls to astRead will return the Objects they describe in sequence (and destroy their descriptions) until no more remain between the current card and the \texttt{"} end-of-file\texttt{"} . When astWrite is used to write an Object using NATIVE encoding, a description of the Object is inserted immediately before the current card (as determined by the Card attribute). Multiple Object descriptions may be written in this way and are stored separately (and sequentially if the Card attribute is not modified between the writes). A write operation using the NATIVE encoding does not over-write previously written Object descriptions. Note, however, that subsequent behaviour is undefined if an Object description is written inside a previously-written description, so this should be avoided. When an Object is written to a FitsChan using NATIVE encoding, astWrite should (barring errors) always transfer data and return a value of 1. } } \sstroutine{ Epoch }{ Epoch of observation }{ \sstdescription{ This attribute is used to qualify the coordinate systems described by a \htmlref{Frame}{Frame}, by giving the moment in time when the coordinates are known to be correct. Often, this will be the date of observation, and is important in cases where coordinates systems move with respect to each other over the course of time. The Epoch attribute is stored as a Modified Julian Date, but when setting its value it may be given in a variety of formats. See the \texttt{"} Input Formats\texttt{"} section (below) for details. Strictly, the Epoch value should be supplied in the TDB timescale, but for some purposes (for instance, for converting sky positions between different types of equatorial system) the timescale is not significant, and UTC may be used. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. The basic Frame class provides a default of J2000.0 (Julian) but makes no use of the Epoch value. This is because the Frame class does not distinguish between different Cartesian coordinate systems (see the \htmlref{System}{System} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default Epoch value for a CmpFrame is selected as follows; if the Epoch attribute has been set in the first component Frame then the Epoch value from the first component Frame is used as the default for the CmpFrame. Otherwise, if the Epoch attribute has been set in the second component Frame then the Epoch value from the second component Frame is used as the default for the CmpFrame. Otherwise, the default Epoch value from the first component Frame is used as the default for the CmpFrame. When the Epoch attribute of a CmpFrame is set or cleared, it is also set or cleared in the two component Frames. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Epoch attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The coordinates of sources within a SkyFrame can changed with time for various reasons, including: (i) changing aberration of light caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer\texttt{'} s position with time, (iii) fictitious motion due to rotation of non-inertial coordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame class because it affects individual sources rather than the coordinate system as a whole). The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the System attribute) and J2000.0 (Julian) for all others. Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator). See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ A TimeFrame describes a general time axis and so cannot be completely characterised by a single Epoch value. For this reason the TimeFrame class makes no use of the Epoch attribute. However, user code can still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"} time spanned by the TimeFrame. The default Epoch value for a TimeFrame will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin, then the default Epoch value is J2000.0. } } \sstdiytopic{ Input Formats }{ The formats accepted when setting an Epoch value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters: \sstitemlist{ \sstitem Besselian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). \sstitem Julian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). \sstitem Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"} for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise. \sstitem Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for example). \sstitem Modified Julian Date: With or without decimal places (\texttt{"} MJD 54321.4\texttt{"} for example). \sstitem Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours). \sstitem Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). } } \sstdiytopic{ Output Format }{ When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"} format described under \texttt{"} Input Formats\texttt{"} . This is a value in decimal years which will be a Besselian epoch if less than 1984.0 and a Julian epoch otherwise. By omitting any character prefix, this format allows the Epoch value to be obtained as either a character string or a floating point value. } } \sstroutine{ Equinox }{ Epoch of the mean equinox }{ \sstdescription{ This attribute is used to qualify those celestial coordinate systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun) and/or the Earth\texttt{'} s equator. Both of these planes are in motion and their positions are difficult to specify precisely. In practice, therefore, a model ecliptic and/or equator are used instead. These, together with the point on the sky that defines the coordinate origin (the intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move with time according to some model which removes the more rapid fluctuations. The SkyFrame class supports both the FK4 and FK5 models. The position of a fixed source expressed in any of these coordinate systems will appear to change with time due to movement of the coordinate system itself (rather than motion of the source). Such coordinate systems must therefore be qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"} or \texttt{"} equinox\texttt{"} for short) which allows the position of the model coordinate system on the sky to be determined. This is the role of the Equinox attribute. The Equinox attribute is stored as a Modified Julian Date, but when setting or getting its value you may use the same formats as for the \htmlref{Epoch}{Epoch} attribute (q.v.). The default Equinox value is B1950.0 (Besselian) for the old FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and J2000.0 (Julian) for all others. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent coordinate system (based on solar system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify coordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer\texttt{'} s motion, etc. \sstitem See the description of the System attribute for details of which qualifying attributes apply to each celestial coordinate system. } } } \sstroutine{ Escape }{ Allow changes of character attributes within strings? }{ \sstdescription{ This attribute controls the appearance of text strings and numerical labels drawn by the \htmlref{astGrid}{astGrid} and (for the \htmlref{Plot}{Plot} class) \htmlref{astText}{astText} functions, by determining if any escape sequences contained within the strings should be used to control the appearance of the text, or should be printed literally. Note, the \htmlref{Plot3D}{Plot3D} class only interprets escape sequences within the astGrid function. If the Escape value of a Plot is one (the default), then any escape sequences in text strings produce the effects described below when printed. Otherwise, they are printed literally. See also the \htmlref{astEscapes}{astEscapes} function. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstdiytopic{ Escape Sequences }{ Escape sequences are introduced into the text string by a percent \texttt{"} \%\texttt{"} character. Any unrecognised, illegal or incomplete escape sequences are printed literally. The following escape sequences are currently recognised (\texttt{"} ...\texttt{"} represents a string of one or more decimal digits): \%\% - Print a literal \texttt{"} \%\texttt{"} character. \%$\wedge$...$+$ - Draw subsequent characters as super-scripts. The digits \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} text to the base-line of the super-script text, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%$\wedge$$+$ - Draw subsequent characters with the normal base-line. \%v...$+$ - Draw subsequent characters as sub-scripts. The digits \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} text to the base-line of the sub-script text, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%v$+$ - Draw subsequent characters with the normal base-line (equivalent to \%$\wedge$$+$). \%$>$...$+$ - Leave a gap before drawing subsequent characters. The digits \texttt{"} ...\texttt{"} give the size of the gap, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%$<$...$+$ - Move backwards before drawing subsequent characters. The digits \texttt{"} ...\texttt{"} give the size of the movement, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to the height of \texttt{"} normal\texttt{"} text. \%s...$+$ - Change the Size attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Size as a fraction of the \texttt{"} normal\texttt{"} Size, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to 1.0; \%s$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. \%w...$+$ - Change the Width attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new width as a fraction of the \texttt{"} normal\texttt{"} Width, scaled so that a value of \texttt{"} 100\texttt{"} corresponds to 1.0; \%w$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. \%f...$+$ - Change the Font attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Font value. \%f$+$ - Reset the Font attribute to its \texttt{"} normal\texttt{"} value. \%c...$+$ - Change the Colour attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Colour value. \%c$+$ - Reset the Colour attribute to its \texttt{"} normal\texttt{"} value. \%t...$+$ - Change the Style attribute for subsequent characters. The digits \texttt{"} ...\texttt{"} give the new Style value. \%t$+$ - Reset the Style attribute to its \texttt{"} normal\texttt{"} value. \%h$+$ - Remember the current horizontal position (see \texttt{"} \%g$+$\texttt{"} ) \%g$+$ - Go to the horizontal position of the previous \texttt{"} \%h$+$\texttt{"} (if any). \%- - Push the current graphics attribute values onto the top of the stack (see \texttt{"} \%$+$\texttt{"} ). \%$+$ - Pop attributes values of the top the stack (see \texttt{"} \%-\texttt{"} ). If the stack is empty, \texttt{"} normal\texttt{"} attribute values are restored. } } \sstroutine{ FillFactor }{ Fraction of the Region which is of interest }{ \sstdescription{ This attribute indicates the fraction of the \htmlref{Region}{Region} which is of interest. AST does not use this attribute internally for any purpose. Typically, it could be used to indicate the fraction of the Region for which data is available. The supplied value must be in the range 0.0 to 1.0, and the default value is 1.0 (except as noted below). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default FillFactor for a CmpRegion is the FillFactor of its first component Region. } \sstsubsection{ \htmlref{Prism}{Prism} }{ The default FillFactor for a Prism is the product of the FillFactors of its two component Regions. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default FillFactor for an Stc is the FillFactor of its encapsulated Region. } } } \sstroutine{ FitsAxisOrder }{ Frame title }{ \sstdescription{ This attribute specifies the order for the WCS axes in any new FITS-WCS headers created using the \htmlref{astWrite}{astWrite} method. The value of the FitsAxisOrder attribute can be either \texttt{"} $<$auto$>$\texttt{"} (the default value), \texttt{"} $<$copy$>$\texttt{"} or a space-separated list of axis symbols: \texttt{"} $<$auto$>$\texttt{"} : causes the WCS axis order to be chosen automatically so that the i\texttt{'} th WCS axis in the new FITS header is the WCS axis which is more nearly parallel to the i\texttt{'} th pixel axis. \texttt{"} $<$copy$>$\texttt{"} : causes the WCS axis order to be set so that the i\texttt{'} th WCS axis in the new FITS header is the i\texttt{'} th WCS axis in the current \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} being written out to the header. \texttt{"} Sym1 Sym2...\texttt{"} : the space-separated list is seached in turn for the Symbol attribute of each axis in the current Frame of the FrameSet. The order in which these Symbols occur within the space-separated list defines the order of the WCS axes in the new FITS header. An error is reported if Symbol for a current Frame axis is not present in the supplied list. However, no error is reported if the list contains extra words that do not correspond to the Symbol of any current Frame axis. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All FitsChans have this attribute. } } } \sstroutine{ FitsDigits }{ Digits of precision for floating point FITS values }{ \sstdescription{ This attribute gives the number of significant decimal digits to use when formatting floating point values for inclusion in the FITS header cards within a \htmlref{FitsChan}{FitsChan}. By default, a positive value is used which results in no loss of information, assuming that the value\texttt{'} s precision is double. Usually, this causes no problems. However, to adhere strictly to the recommendations of the FITS standard, the width of the formatted value (including sign, decimal point and exponent) ought not to be more than 20 characters. If you are concerned about this, you should set FitsDigits to a negative value, such as -15. In this case, the absolute value ($+$15) indicates the maximum number of significant digits to use, but the actual number used may be fewer than this to ensure that the FITS recommendations are satisfied. When using this approach, the resulting number of significant digits may depend on the value being formatted and on the presence of any sign, decimal point or exponent. The value of this attribute is effective when FITS header cards are output, either using \htmlref{astFindFits}{astFindFits} or by the action of the FitsChan\texttt{'} s sink function when it is finally deleted. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Font(element) }{ Character font for a Plot element }{ \sstdescription{ This attribute determines the character font index used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Font(title)=2\texttt{"} causes the Plot title to be drawn using font number 2. The range of integer font indices available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default font supplied by this graphics system. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Font\texttt{"} instead of \texttt{"} Font(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Font(TextLab) value. } } } \sstroutine{ Format(axis) }{ Format specification for axis values }{ \sstdescription{ This attribute specifies the format to be used when displaying coordinate values associated with a particular \htmlref{Frame}{Frame} axis (i.e. to convert values from binary to character form). It is interpreted by the \htmlref{astFormat}{astFormat} function and determines the formatting which it applies. If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The Frame class interprets this attribute as a format specification string to be passed to the C \texttt{"} printf\texttt{"} function (e.g. \texttt{"} \%1.7G\texttt{"} ) in order to format a single coordinate value (supplied as a double precision number). When supplying a value for this attribute, beware that the \texttt{"} \%\texttt{"} character may be interpreted directly as a format specification by some printf-like functions (such as \htmlref{astSet}{astSet}). You may need to double it (i.e. use \texttt{"} \%\%\texttt{"} ) to avoid this. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the \texttt{"} SkyFrame Formats\texttt{"} section. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). Note that the syntax of the Format string is also determined by the current Frame. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the \texttt{"} TimeFrame Formats\texttt{"} section. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } \sstdiytopic{ SkyFrame Formats }{ The Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity: \sstitemlist{ \sstitem \texttt{"} $+$\texttt{"} : Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used. \sstitem \texttt{"} z\texttt{"} : Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added. \sstitem \texttt{"} i\texttt{"} : Use the standard ISO field separator (a colon) between fields. This is the default behaviour. \sstitem \texttt{"} b\texttt{"} : Use a blank to separate fields. \sstitem \texttt{"} l\texttt{"} : Use a letter (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} as appropriate) to separate fields. \sstitem \texttt{"} g\texttt{"} : Use a letter and symbols to separate fields (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} , etc, as appropriate), but include escape sequences in the formatted value so that the \htmlref{Plot}{Plot} class will draw the separators as small super-scripts. The default escape sequences are optimised for the pgplot graphics package, but new escape sequences may be specified using function astSetSkyDelim. \sstitem \texttt{"} d\texttt{"} : Include a degrees field. Expressing the angle purely in degrees is also the default if none of \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} , \texttt{"} s\texttt{"} or \texttt{"} t\texttt{"} are given. \sstitem \texttt{"} h\texttt{"} : Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if \texttt{"} t\texttt{"} is given without either \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} . \sstitem \texttt{"} m\texttt{"} : Include a minutes field. By default this is not included. \sstitem \texttt{"} s\texttt{"} : Include a seconds field. By default this is not included. This request is ignored if \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is given, unless a minutes field is also included. \sstitem \texttt{"} t\texttt{"} : Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If \texttt{"} t\texttt{"} is given without \texttt{"} d\texttt{"} , \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} being present, then it is equivalent to \texttt{"} h\texttt{"} . \sstitem \texttt{"} .\texttt{"} : Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The \texttt{"} .\texttt{"} should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits attribute. } All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both \texttt{"} i\texttt{"} and \texttt{"} b\texttt{"} appear), then the character occurring last takes precedence, except that \texttt{"} d\texttt{"} and \texttt{"} h\texttt{"} always override \texttt{"} t\texttt{"} . If the format string starts with a percentage sign (\%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value. } \sstdiytopic{ TimeFrame Formats }{ The Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C \texttt{"} printf\texttt{"} format string), or the extended \texttt{"} iso\texttt{"} syntax described below (the default value is inherited from the Frame class): \sstitemlist{ \sstitem C \texttt{"} printf\texttt{"} syntax: If the Format string is a C \texttt{"} printf\texttt{"} format description such as \texttt{"} \%1.7G\texttt{"} , the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute, measured in units given by the TimeFrame\texttt{'} s Unit attribute. \sstitem \texttt{"} iso\texttt{"} syntax: This is used to format a TimeFrame axis value as a Gregorian date followed by an optional time of day. If the Format value commences with the string \texttt{"} iso\texttt{"} then the TimeFrame axis value will be converted to an absolute MJD, including the addition of the current TimeOrigin value, and then formatted as a Gregorian date using the format \texttt{"} yyyy-mm-dd\texttt{"} . Optionally, the Format value may include an integer precision following the \texttt{"} iso\texttt{"} specification (e.g. \texttt{"} iso.2\texttt{"} ), in which case the time of day will be appended to the formatted date (if no time of day is included, the date field is rounded to the nearest day). The integer value in the Format string indicates the number of decimal places to use in the seconds field. For instance, a Format value of \texttt{"} iso.0\texttt{"} produces a time of day of the form \texttt{"} hh:mm:ss\texttt{"} , and a Format value of \texttt{"} iso.2\texttt{"} produces a time of day of the form \texttt{"} hh:mm:ss.ss\texttt{"} . The date and time fields will be separated by a space unless \texttt{'} T\texttt{'} is appended to the end of string, in which case the letter T (upper case) will be used as the separator. The value of the Digits attribute is ignored when using this \texttt{"} iso\texttt{"} format. } } } \sstroutine{ Full }{ Set level of output detail }{ \sstdescription{ This attribute is a three-state flag and takes values of -1, 0 or $+$1. It controls the amount of information included in the output generated by a \htmlref{Channel}{Channel}. If Full is zero, then a modest amount of non-essential but useful information will be included in the output. If Full is negative, all non-essential information will be suppressed to minimise the amount of output, while if it is positive, the output will include the maximum amount of detailed information about the \htmlref{Object}{Object} being written. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Channel }{ The default value is zero for a normal Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The default value is zero for a FitsChan. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value is -1 for an XmlChan. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The default value is zero for an StcsChan. Set a positive value to cause default values to be included in STC-S descriptions. } } \sstnotes{ \sstitemlist{ \sstitem All positive values supplied for this attribute are converted to $+$1 and all negative values are converted to -1. } } } \sstroutine{ Gap(axis) }{ Interval between linearly spaced major axis values of a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the linear interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} Gap(2)=3.0\texttt{"} specifies the difference between adjacent major values along the second axis. The Gap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be linear. If major axis values are logarithmically spaced then the gap is specified using attribute LogGap. The Gap value supplied will usually be rounded to the nearest \texttt{"} nice\texttt{"} value, suitable (e.g.) for generating axis labels, before use. To avoid this \texttt{"} nicing\texttt{"} you should set an explicit format for the axis using the \htmlref{Format(axis)}{Format(axis)} or \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} attribute. The default behaviour is for the Plot to generate its own Gap value when required, based on the range of axis values to be represented. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The Gap value should use the same units as are used internally for storing coordinate values on the corresponding axis. For example, with a celestial coordinate system, the Gap value should be in radians, not hours or degrees. \sstitem If no axis is specified, (e.g. \texttt{"} Gap\texttt{"} instead of \texttt{"} Gap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Gap(1) value. } } } \sstroutine{ Grf }{ Use Grf functions registered through astGrfSet? }{ \sstdescription{ This attribute selects the functions which are used to draw graphics by the \htmlref{Plot}{Plot} class. If it is zero, then the functions in the graphics interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script). Otherwise, functions registered using \htmlref{astGrfSet}{astGrfSet} are used. In this case, if a function is needed which has not been registered, then the function in the graphics interface selected at link-time is used. The default is to use the graphics interface } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes, assuming a value of zero. } } \sstnotes{ \sstitemlist{ \sstitem The value of this attribute is not saved when the Plot is written out through a \htmlref{Channel}{Channel} to an external data store. On re-loading such a Plot using \htmlref{astRead}{astRead}, the attribute will be cleared, resulting in the graphics interface selected at link-time being used. } } } \sstroutine{ Grid }{ Draw grid lines for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether grid lines (a grid of curves marking the \texttt{"} major\texttt{"} values on each axis) are drawn across the plotting area. If the Grid value of a \htmlref{Plot}{Plot} is non-zero, then grid lines will be drawn. Otherwise, short tick marks on the axes are used to mark the major axis values. The default behaviour is to use tick marks if the entire plotting area is filled by valid physical coordinates, but to draw grid lines otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The spacing between major axis values, which determines the spacing of grid lines, may be set using the \htmlref{Gap(axis)}{Gap(axis)} attribute. } } } \sstroutine{ GrismAlpha }{ The angle of incidence of the incoming light on the grating surface }{ \sstdescription{ This attribute holds the angle between the incoming light and the normal to the grating surface, in radians. The default value is 0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismEps }{ The angle between the normal and the dispersion plane }{ \sstdescription{ This attribute holds the angle (in radians) between the normal to the grating or exit prism face, and the dispersion plane. The dispersion plane is the plane spanned by the incoming and outgoing ray. The default value is 0.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismG }{ The grating ruling density }{ \sstdescription{ This attribute holds the number of grating rulings per unit length. The unit of length used should be consistent with the units used for attributes \htmlref{GrismWaveR}{GrismWaveR} and \htmlref{GrismNRP}{GrismNRP}. The default value is 0.0. (the appropriate value for a pure prism disperser with no grating). Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismM }{ The interference order }{ \sstdescription{ This attribute holds the interference order being considered. The default value is 0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismNR }{ The refractive index at the reference wavelength }{ \sstdescription{ This attribute holds refractive index of the grism material at the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 1.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismNRP }{ The rate of change of refractive index with wavelength }{ \sstdescription{ This attribute holds the rate of change of the refractive index of the grism material with respect to wavelength at the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 0.0 (the appropriate value for a pure grating disperser with no prism). The units of this attribute should be consistent with those of attributes GrismWaveR and \htmlref{GrismG}{GrismG}. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismTheta }{ Angle between normal to detector plane and reference ray }{ \sstdescription{ This attribute gives the angle of incidence of light of the reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}) onto the detector. Specifically, it holds the angle (in radians) between the normal to the detector plane and an incident ray at the reference wavelength. The default value is 0.0. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ GrismWaveR }{ The reference wavelength }{ \sstdescription{ This attribute holds reference wavelength. The default value is 5000 (Angstrom). The units of this attribute should be consistent with those of attributes \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG}. Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} has no more than one reference. That is, an error is reported if the GrismMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ GrismMap }{ All GrismMaps have this attribute. } } } \sstroutine{ ID }{ Object identification string }{ \sstdescription{ This attribute contains a string which may be used to identify the \htmlref{Object}{Object} to which it is attached. There is no restriction on the contents of this string, which is not used internally by the AST library, and is simply returned without change when required. The default value is an empty string. An identification string can be valuable when, for example, several Objects have been stored in a file (using \htmlref{astWrite}{astWrite}) and are later retrieved (using \htmlref{astRead}{astRead}). Consistent use of the ID attribute allows the retrieved Objects to be identified without depending simply on the order in which they were stored. This attribute may also be useful during debugging, to distinguish similar Objects when using \htmlref{astShow}{astShow} to display them. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Unlike most other attributes, the value of the ID attribute is not transferred when an Object is copied. Instead, its value is undefined (and therefore defaults to an empty string) in any copy. However, it is retained in any external representation of an Object produced by the astWrite function. } } } \sstroutine{ IF }{ The intermediate frequency in a dual sideband spectrum }{ \sstdescription{ This attribute specifies the (topocentric) intermediate frequency in a dual sideband spectrum. Its sole use is to determine the local oscillator (LO) frequency (the frequency which marks the boundary between the lower and upper sidebands). The LO frequency is equal to the sum of the centre frequency and the intermediate frequency. Here, the \texttt{"} centre frequency\texttt{"} is the topocentric frequency in Hz corresponding to the current value of the \htmlref{DSBCentre}{DSBCentre} attribute. The value of the IF attribute may be positive or negative: a positive value results in the LO frequency being above the central frequency, whilst a negative IF value results in the LO frequency being below the central frequency. The sign of the IF attribute value determines the default value for the \htmlref{SideBand}{SideBand} attribute. When setting a new value for this attribute, the units in which the frequency value is supplied may be indicated by appending a suitable string to the end of the formatted value. If the units are not specified, then the supplied value is assumed to be in units of GHz. For instance, the following strings all result in an IF of 4 GHz being used: \texttt{"} 4.0\texttt{"} , \texttt{"} 4.0 GHz\texttt{"} , \texttt{"} 4.0E9 Hz\texttt{"} , etc. When getting the value of this attribute, the returned value is always in units of GHz. The default value for this attribute is 4 GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ Ident }{ Permanent Object identification string }{ \sstdescription{ This attribute is like the \htmlref{ID}{ID} attribute, in that it contains a string which may be used to identify the \htmlref{Object}{Object} to which it is attached. The only difference between ID and Ident is that Ident is transferred when an Object is copied, but ID is not. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ ImagFreq }{ The image sideband equivalent of the rest frequency }{ \sstdescription{ This is a read-only attribute giving the frequency which corresponds to the rest frequency but is in the opposite sideband. The value is calculated by first transforming the rest frequency (given by the \htmlref{RestFreq}{RestFreq} attribute) from the standard of rest of the source (given by the \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} attributes) to the standard of rest of the observer (i.e. the topocentric standard of rest). The resulting topocentric frequency is assumed to be in the same sideband as the value given for the \htmlref{DSBCentre}{DSBCentre} attribute (the \texttt{"} observed\texttt{"} sideband), and is transformed to the other sideband (the \texttt{"} image\texttt{"} sideband). The new frequency is converted back to the standard of rest of the source, and the resulting value is returned as the attribute value, in units of GHz. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ Indent }{ Specifies the indentation to use in text produced by a Channel }{ \sstdescription{ This attribute controls the indentation within the output text produced by the \htmlref{astWrite}{astWrite} function. It gives the increase in the indentation for each level in the object heirarchy. If it is set to zero, no indentation will be used. [3] } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Channel}{Channel} }{ The default value is zero for a basic Channel. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The FitsChan class ignores this attribute. } \sstsubsection{ \htmlref{StcsChan}{StcsChan} }{ The default value for an StcsChan is zero, which causes the entire STC-S description is written out by a single invocation of the sink function. The text supplied to the sink function will not contain any linefeed characters, and each pair of adjacent words will be separated by a single space. The text may thus be arbitrarily large and the \htmlref{StcsLength}{StcsLength} attribute is ignored. If Indent is non-zero, then the text is written out via multiple calls to the sink function, each call corresponding to a single \texttt{"} line\texttt{"} of text (although no line feed characters will be inserted by AST). The complete STC-S description is broken into lines so that: \sstitemlist{ \sstitem the line length specified by attribute StcsLength is not exceeded \sstitem each sub-phrase (time, space, etc.) starts on a new line \sstitem each argument in a compound spatial region starts on a new line } If this causes a sub-phrase to extend to two or more lines, then the second and subsequent lines will be indented by three spaces compared to the first line. In addition, lines within a compound spatial region will have extra indentation to highlight the nesting produced by the parentheses. Each new level of nesting will be indented by a further three spaces. } \sstsubsection{ \htmlref{XmlChan}{XmlChan} }{ The default value for an XmlChan is zero, which results in no linefeeds or indentation strings being added to output text. If any non-zero value is assigned to Indent, then extra linefeed and space characters will be inserted as necessary to ensure that each XML tag starts on a new line, and each tag will be indented by a further 3 spaces to show its depth in the containment hierarchy. } } } \sstroutine{ InternalUnit(axis) }{ Physical units for unformated axis values }{ \sstdescription{ This read-only attribute contains a textual representation of the physical units used to represent unformatted (i.e. floating point) values on a particular axis of a \htmlref{Frame}{Frame}, typically handled internally within application code. In most cases, the value of the InternalUnit attribute will be the same as Unit attribute (i.e. formatted and unformatted axis values will normally use the same system of units). The main exception to this is the \htmlref{SkyFrame}{SkyFrame} class, which represents unformatted axis values in radians, regardless of the current setting of the Unit attribute. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ IntraFlag }{ IntraMap identification string }{ \sstdescription{ This attribute allows an \htmlref{IntraMap}{IntraMap} to be flagged so that it is distinguishable from other IntraMaps. The transformation function associated with the IntraMap may then enquire the value of this attribute and adapt the transformation it provides according to the particular IntraMap involved. Although this is a string attribute, it may often be useful to store numerical values here, encoded as a character string, and to use these as data within the transformation function. Note, however, that this mechanism is not suitable for transferring large amounts of data (more than about 1000 characters) to an IntraMap. For that purpose, global variables are recommended, although the IntraFlag value can be used to supplement this approach. The default IntraFlag value is an empty string. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ IntraMap }{ All IntraMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem A pair of IntraMaps whose transformations may potentially cancel cannot be simplified to produce a \htmlref{UnitMap}{UnitMap} (e.g. using \htmlref{astSimplify}{astSimplify}) unless they have the same IntraFlag values. The test for equality is case-sensitive. } } } \sstroutine{ Invert }{ Mapping inversion flag }{ \sstdescription{ This attribute controls which one of a \htmlref{Mapping}{Mapping}\texttt{'} s two possible coordinate transformations is considered the \texttt{"} forward\texttt{"} transformation (the other being the \texttt{"} inverse\texttt{"} transformation). If the attribute value is zero (the default), the Mapping\texttt{'} s behaviour will be the same as when it was first created. However, if it is non-zero, its two transformations will be inter-changed, so that the Mapping displays the inverse of its original behaviour. Inverting the boolean sense of the Invert attribute will cause the values of a Mapping\texttt{'} s \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes to be interchanged. The values of its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes will also be interchanged. This operation may be performed with the \htmlref{astInvert}{astInvert} function. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{UnitMap}{UnitMap} }{ The value of the Invert attribute has no effect on the behaviour of a UnitMap. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ Inverting the boolean sense of the Invert attribute for a FrameSet will cause its base and current Frames (and its \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes) to be interchanged. This, in turn, may affect other properties and attributes of the FrameSet (such as Nin, Nout, \htmlref{Naxes}{Naxes}, TranForward, TranInverse, etc.). The Invert attribute of a FrameSet is not itself affected by selecting a new base or current \htmlref{Frame}{Frame}. } } } \sstroutine{ Invisible }{ Draw graphics using invisible ink? }{ \sstdescription{ This attribute controls the appearance of all graphics produced by \htmlref{Plot}{Plot} methods by determining whether graphics should be visible or invisible. If the Invisible value of a Plot is non-zero, then all the Plot methods which normally generate graphical output do not do so (you can think of them drawing with \texttt{"} invisible ink\texttt{"} ). Such methods do, however, continue to do all the calculations which would be needed to produce the graphics. In particular, the bounding box enclosing the graphics is still calculated and can be retrieved as normal using \htmlref{astBoundingBox}{astBoundingBox}. The default value is zero, resulting in all methods drawing graphics as normal, using visible ink. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ IsLatAxis(axis) }{ Is the specified celestial axis a latitude axis? }{ \sstdescription{ This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial latitude axis (Declination, Galactic latitude, etc), and is zero otherwise. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. } } } \sstroutine{ IsLinear }{ Is the Mapping linear? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is an instance of a class that always represents a linear transformation. Note, some Mapping classes can represent linear or non-linear transformations (the \htmlref{MathMap}{MathMap} class for instance). Such classes have a zero value for the IsLinear attribute. Specific instances of such classes can be tested for linearity using the \htmlref{astLinearApprox}{astLinearApprox} function. AST\_LINEARAPPROX routine. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The IsLinear value for a CmpMap is determined by the classes of the encapsulated Mappings. For instance, a CmpMap that combines a \htmlref{ZoomMap}{ZoomMap} and a \htmlref{ShiftMap}{ShiftMap} will have a non-zero value for its IsLinear attribute, but a CmpMap that contains a MathMap will have a value of zero for its IsLinear attribute. } \sstsubsection{ \htmlref{Frame}{Frame} }{ The IsLinear value for a Frame is 1 (since a Frame is equivalent to a \htmlref{UnitMap}{UnitMap}). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The IsLinear value for a FrameSet is obtained from the Mapping from the base Frame to the current Frame. } } } \sstroutine{ IsLonAxis(axis) }{ Is the specified celestial axis a longitude axis? }{ \sstdescription{ This is a read-only boolean attribute that indicates the nature of the specified axis. The attribute has a non-zero value if the specified axis is a celestial longitude axis (Right Ascension, Galactic longitude, etc), and is zero otherwise. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the SkyFrame axis to be tested. } } } \sstroutine{ IsSimple }{ Has the Mapping been simplified? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} has been simplified by the \htmlref{astSimplify}{astSimplify} method. If the IsSimple value is non-zero, then the Mapping has been simplified and so there is nothing to be gained by simplifying it again. Indeed, the astSimplify method will immediately return the Mapping unchanged if the IsSimple attribute indicates that the Mapping has already been simplified. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{Frame}{Frame} }{ All classes of Frame return zero for the IsSimple attribute. This is because changes can be made to a Frame which affect the Mapping represented by the Frame, and so there can be no guarantee that the Mapping may not need re-simplifying. Most non-Frame Mappings, on the other hand, are immutable and so when they are simplified it is certain that they weill remain in a simple state. } } } \sstroutine{ IterInverse }{ Provide an iterative inverse transformation? }{ \sstdescription{ This attribute indicates whether the inverse transformation of the \htmlref{PolyMap}{PolyMap} should be implemented via an iterative Newton-Raphson approximation that uses the forward transformation to transform candidate input positions until an output position is found which is close to the required output position. By default, an iterative inverse is provided if, and only if, no inverse polynomial was supplied when the PolyMap was constructed. The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that control the behaviour of the inverse approcimation method. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ PolyMap }{ All PolyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem An iterative inverse can only be used if the PolyMap has equal numbers of inputs and outputs, as given by the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes. An error will be reported if IterInverse is set non-zero for a PolyMap that does not meet this requirement. } } } \sstroutine{ Iwc }{ Include a Frame representing FITS-WCS intermediate world coordinates? }{ \sstdescription{ This attribute is a boolean value which is used when a \htmlref{FrameSet}{FrameSet} is read from a \htmlref{FitsChan}{FitsChan} with a foreign FITS encoding (e.g. FITS-WCS) using \htmlref{astRead}{astRead}. If it has a non-zero value then the returned FrameSet will include Frames representing \texttt{"} intermediate world coordinates\texttt{"} (IWC). These Frames will have \htmlref{Domain}{Domain} name \texttt{"} IWC\texttt{"} for primary axis descriptions, and \texttt{"} IWCa\texttt{"} for secondary axis descriptions, where \texttt{"} a\texttt{"} is replaced by the single alternate axis description character, as used in the FITS-WCS header. The default value for \texttt{"} Iwc\texttt{"} is zero. FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one axis for each WCS axis, and is the coordinate system produced by the rotation matrix (represented by FITS keyword PCi\_j, CDi\_j, etc). For instance, for a 2-D FITS-WCS header describing projected celestial longitude and latitude, the intermediate world coordinates represent offsets in degrees from the reference point within the plane of projection. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ KeyCase }{ Are keys case sensitive? }{ \sstdescription{ This attribute is a boolean value which controls how keys are used. If KeyCase is zero, then key strings supplied to any method are automatically converted to upper case before being used. If KeyCase is non-zero (the default), then supplied key strings are used without modification. The value of this attribute can only be changed if the \htmlref{KeyMap}{KeyMap} is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to change the attribute value when the KeyMap contains any entries. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } \sstsubsection{ \htmlref{Table}{Table} }{ The Table class over-rides this attribute by forcing it to zero. That is, keys within a Table are always case insensitive. } } } \sstroutine{ KeyError }{ Report an error when getting the value of a non-existant KeyMap entry? }{ \sstdescription{ This attribute is a boolean value which controls how the astMapGet... functions behave if the requested key is not found in the \htmlref{KeyMap}{KeyMap}. If KeyError is zero (the default), then these functions will return zero but no error will be reported. If KeyError is non-zero, then the same values are returned but an error is also reported. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When setting a new value for KeyError, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap. \sstitem When clearing the KeyError attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. } } } \sstroutine{ LTOffset }{ The offset from UTC to Local Time, in hours }{ \sstdescription{ This specifies the offset from UTC to Local Time, in hours (fractional hours can be supplied). It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ All TimeFrames have this attribute. } } } \sstroutine{ Label(axis) }{ Axis label }{ \sstdescription{ This attribute specifies a label to be attached to each axis of a \htmlref{Frame}{Frame} when it is represented (e.g.) in graphical output. If a Label value has not been set for a Frame axis, then a suitable default is supplied. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is the string \texttt{"} \htmlref{Axis}{Axis} $<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for each successive axis. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Label value (e.g. to \texttt{"} Right ascension\texttt{"} or \texttt{"} Galactic latitude\texttt{"} ) as appropriate for the particular celestial coordinate system being represented. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Label value as appropriate for the particular time system being represented. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Label attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem Axis labels are intended purely for interpretation by human readers and not by software. \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ LabelAt(axis) }{ Where to place numerical labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining where numerical axis labels and associated tick marks are placed. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LabelAt(2)=10.0\texttt{"} specifies where the numerical labels and tick marks for the second axis should be drawn. For each axis, the LabelAt value gives the value on the other axis at which numerical labels and tick marks should be placed (remember that Plots suitable for use with astGrid may only have two axes). For example, in a celestial (RA,Dec) coordinate system, LabelAt(1) gives a Dec value which defines a line (of constant Dec) along which the numerical RA labels and their associated tick marks will be drawn. Similarly, LabelAt(2) gives the RA value at which the Dec labels and ticks will be drawn. The default bahaviour is for the Plot to generate its own position for numerical labels and tick marks. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The LabelAt value should use the same units as are used internally for storing coordinate values on the appropriate axis. For example, with a celestial coordinate system, the LabelAt value should be in radians, not hours or degrees. \sstitem Normally, the LabelAt value also determines where the lines representing coordinate axes will be drawn, so that the tick marks will lie on these lines (but also see the DrawAxes attribute). \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the LabelAt attribute is ignored. } } } \sstroutine{ LabelUnits(axis) }{ Use axis unit descriptions in a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether the descriptive labels drawn for each axis of a \htmlref{Plot}{Plot} should include a description of the units being used on the axis. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} LabelUnits(2)=1\texttt{"} specifies that a unit description should be included in the label for the second axis. If the LabelUnits value of a Plot axis is non-zero, a unit description will be included in the descriptive label for that axis, otherwise it will be omitted. The default behaviour is to include a unit description unless the current \htmlref{Frame}{Frame} of the Plot is a \htmlref{SkyFrame}{SkyFrame} representing equatorial, ecliptic, galactic or supergalactic coordinates, in which case it is omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the unit description is obtained from the Plot\texttt{'} s \htmlref{Unit(axis)}{Unit(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} LabelUnits\texttt{"} instead of \texttt{"} LabelUnits(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LabelUnits(1) value. \sstitem If the current Frame of the Plot is not a SkyFrame, but includes axes which were extracted from a SkyFrame, then the default behaviour is to include a unit description only for those axes which were not extracted from a SkyFrame. } } } \sstroutine{ LabelUp(axis) }{ Draw numerical Plot labels upright? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether the numerical labels for each axis of a \htmlref{Plot}{Plot} should be drawn upright or not. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} LabelUp(2)=1\texttt{"} specifies that numerical labels for the second axis should be drawn upright. If the LabelUp value of a Plot axis is non-zero, it causes numerical labels for that axis to be plotted upright (i.e. as normal, horizontal text), otherwise labels are drawn parallel to the axis to which they apply. The default is to produce upright labels if the labels are placed around the edge of the plot, and to produce labels that follow the axes if the labels are placed within the interior of the plot (see attribute \htmlref{Labelling}{Labelling}). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels and tick marks are drawn around the edges of the plotting area (see the Labelling attribute). In this case, the value of the LabelUp attribute is ignored. \sstitem If no axis is specified, (e.g. \texttt{"} LabelUp\texttt{"} instead of \texttt{"} LabelUp(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LabelUp(1) value. } } } \sstroutine{ Labelling }{ Label and tick placement option for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the strategy for placing numerical labels and tick marks for a \htmlref{Plot}{Plot}. If the Labelling value of a Plot is \texttt{"} exterior\texttt{"} (the default), then numerical labels and their associated tick marks are placed around the edges of the plotting area, if possible. If this is not possible, or if the Labelling value is \texttt{"} interior\texttt{"} , then they are placed along grid lines inside the plotting area. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute may be used to determine the exact placement of labels and tick marks that are drawn inside the plotting area. } } } \sstroutine{ LatAxis }{ Index of the latitude axis }{ \sstdescription{ This read-only attribute gives the index (1 or 2) of the latitude axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis permutations). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ ListSize }{ Number of points in a PointList }{ \sstdescription{ This is a read-only attribute giving the number of points in a \htmlref{PointList}{PointList}. This value is determined when the PointList is created. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ PointList }{ All PointLists have this attribute. } } } \sstroutine{ LogGap(axis) }{ Interval between major axis values of a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the logarithmic interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at which (for example) major tick marks are drawn. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} LogGap(2)=100.0\texttt{"} specifies the ratio between adjacent major values along the second axis. The LogGap attribute is only used when the LogTicks attribute indicates that the spacing between major axis values is to be logarithmic. If major axis values are linearly spaced then the gap is specified using attribute Gap. The LogGap value supplied will be rounded to the nearest power of 10. The reciprocal of the supplied value may be used if this is necessary to produce usable major axis values. If a zero or negative value is supplied, an error will be reported when the grid is drawn. The default behaviour is for the Plot to generate its own LogGap value when required, based on the range of axis values to be represented. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The LogGap value is a ratio between axis values and is therefore dimensionless. \sstitem If no axis is specified, (e.g. \texttt{"} LogGap\texttt{"} instead of \texttt{"} LogGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogGap(1) value. } } } \sstroutine{ LogLabel(axis) }{ Use exponential format for numerical axis labels? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether the numerical axis labels should be in normal decimal form or should be represented as 10 raised to the appropriate power. That is, an axis value of 1000.0 will be drawn as \texttt{"} 1000.0\texttt{"} if LogLabel is zero, but as \texttt{"} 10$\wedge$3\texttt{"} if LogLabel is non-zero. If graphical escape sequences are supported (see attribute \htmlref{Escape}{Escape}), the power in such exponential labels will be drawn as a small superscript instead of using a \texttt{"} $\wedge$\texttt{"} character to represent exponentiation. The default is to produce exponential labels if the major tick marks are logarithmically spaced (see the LogTicks attribute). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Plot}{Plot} }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} LogLabel\texttt{"} instead of \texttt{"} LogLabel(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogLabel(1) value. } } } \sstroutine{ LogPlot(axis) }{ Map the plot logarithmically onto the screen? }{ \sstdescription{ This attribute controls the appearance of all graphics produced by the \htmlref{Plot}{Plot}, by determining whether the axes of the plotting surface are mapped logarithmically or linearly onto the base \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} supplied when the Plot was constructed. It takes a separate value for each axis of the graphics coordinate system (i.e. the base Frame in the Plot) so that, for instance, the setting \texttt{"} LogPlot(2)=1\texttt{"} specifies that the second axis of the graphics coordinate system (usually the vertical axis) should be mapped logarithmically onto the second axis of the base Frame of the FrameSet supplied when the Plot was constructed. If the LogPlot value of a Plot axis is non-zero, it causes that axis to be mapped logarithmically, otherwise (the default) the axis is mapped linearly. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The setting of the LogPlot attribute provides the default value for the related LogTicks attribute. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vice-versa). \sstitem An axis may only be mapped logarithmically if the visible part of the axis does not include the value zero. The visible part of the axis is that part which is mapped onto the plotting area, and is measured within the base Frame of the FrameSet which was supplied when the Plot was constructed. Any attempt to set LogPlot to a non-zero value will be ignored (without error) if the visible part of the axis includes the value zero \sstitem If no axis is specified, (e.g. \texttt{"} LogPlot\texttt{"} instead of \texttt{"} LogPlot(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogPlot(1) value. } } } \sstroutine{ LogTicks(axis) }{ Space the major tick marks logarithmically? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether the major tick marks should be spaced logarithmically or linearly in axis value. It takes a separate value for each physical axis of the \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LogTicks(2)=1\texttt{"} specifies that the major tick marks on the second axis should be spaced logarithmically. If the LogTicks value for a physical axis is non-zero, the major tick marks on that axis will be spaced logarithmically (that is, there will be a constant ratio between the axis values at adjacent major tick marks). An error will be reported if the dynamic range of the axis (the ratio of the largest to smallest displayed axis value) is less than 10.0. If the LogTicks value is zero, the major tick marks will be evenly spaced (that is, there will be a constant difference between the axis values at adjacent major tick marks). The default is to produce logarithmically spaced tick marks if the corresponding LogPlot attribute is non-zero and the ratio of maximum axis value to minimum axis value is 100 or more. If either of these conditions is not met, the default is to produce linearly spaced tick marks. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The setting of the LogTicks attribute does not affect the mapping of the plot onto the screen, which is controlled by attribute LogPlot. By selecting suitable values for LogPlot and LogTicks, it is possible to have tick marks which are evenly spaced in value but which are mapped logarithmically onto the screen (and vica-versa). \sstitem An error will be reported when drawing an annotated axis grid if the visible part of the physical axis includes the value zero. \sstitem If no axis is specified, (e.g. \texttt{"} LogTicks\texttt{"} instead of \texttt{"} LogTicks(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the LogTicks(1) value. } } } \sstroutine{ LonAxis }{ Index of the longitude axis }{ \sstdescription{ This read-only attribute gives the index (1 or 2) of the longitude axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis permutations). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ LutEpsilon }{ The relative error of the values held in the took-up table }{ \sstdescription{ This attribute holds the relative error of the values held in the took-up table. It is used when simplifying a \htmlref{LutMap}{LutMap}, to determine if the LutMap should be considered linear. Setting a larger value makes it more likely that a LutMap will be replaced by a \htmlref{WinMap}{WinMap} (i.e. a linear \htmlref{Mapping}{Mapping}) when simplified. The default value is the value of the system constant DBL\_EPSILON (typically around 1e-16 or 2E-16). If the values in the look-up table were derived from single precision data, it may be appropriate to set this attribute to a value around 1E-7. Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ LutMap }{ All LutMaps have this attribute. } } } \sstroutine{ LutInterp }{ Look-up table interpolation method }{ \sstdescription{ This attribute indicates the method to be used when finding the output value of a \htmlref{LutMap}{LutMap} for an input value part way between two table entries. If it is set to 0 (the default) then linear interpolation is used. Otherwise, nearest neighbour interpolation is used. Using nearest neighbour interpolation causes AST\_\_BAD to be returned for any point which falls outside the bounds of the table. Linear interpolation results in an extrapolated value being returned based on the two end entries in the table. Note, the value of this attribute may changed only if the LutMap has no more than one reference. That is, an error is reported if the LutMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ LutMap }{ All LutMaps have this attribute. } } } \sstroutine{ MajTickLen(axis) }{ Length of major tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the length of the major tick marks drawn on the axes of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} MajTickLen(2)=0\texttt{"} specifies the length of the major tick marks drawn on the second axis. The MajTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause major tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside. The default behaviour depends on whether a coordinate grid is drawn inside the plotting area (see the \htmlref{Grid}{Grid} attribute). If so, the default MajTickLen value is zero (so that major ticks are not drawn), otherwise the default is $+$0.015. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} MajTickLen\texttt{"} instead of \texttt{"} MajTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MajTickLen(1) value. } } } \sstroutine{ MapLocked }{ Prevent new entries being added to a KeyMap? }{ \sstdescription{ If this boolean attribute is set to a non-zero value, an error will be reported if an attempt is made to add a new entry to the \htmlref{KeyMap}{KeyMap}. Note, the value associated with any existing entries can still be changed, but no new entries can be stored in the KeyMap. The default value (zero) allows new entries to be added to the KeyMap. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When setting a new value for MapLocked, the supplied value is propagated to any KeyMaps contained within the supplied KeyMap. \sstitem When clearing the MapLocked attribute, the attribute is also cleared in any KeyMaps contained within the supplied KeyMap. } } } \sstroutine{ MatchEnd }{ Match trailing axes? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It applies only in the case where a match occurs between template and target Frames with different numbers of axes. If the MatchEnd value of the template Frame is zero, then the axes which occur first in the target Frame will be matched and any trailing axes (in either the target or template) will be disregarded. If it is non-zero, the final axes in each Frame will be matched and any un-matched leading axes will be disregarded instead. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ The default MatchEnd value for a Frame is zero, so that trailing axes are disregarded. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MatchEnd attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ MaxAxes }{ Maximum number of Frame axes to match }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It specifies the maximum number of axes that the target Frame may have in order to match the template. Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default MaxAxes value for a Frame is equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The MaxAxes attribute of a CmpFrame defaults to a large number (1000000) which is much larger than any likely number of axes in a Frame. Combined with the \htmlref{MinAxes}{MinAxes} default of zero (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MaxAxes and MinAxes attributes to the number of axes in the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MaxAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When setting a MaxAxes value, the value of the MinAxes attribute may also be silently changed so that it remains consistent with (i.e. does not exceed) the new value. The default MaxAxes value may also be reduced to remain consistent with the MinAxes value. \sstitem If a template Frame is used to match a target with a different number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used to determine how the individual axes of each Frame should match. } } } \sstroutine{ MeshSize }{ Number of points used to represent the boundary of a Region }{ \sstdescription{ This attribute controls how many points are used when creating a mesh of points covering the boundary or volume of a \htmlref{Region}{Region}. Such a mesh is returned by the \htmlref{astGetRegionMesh}{astGetRegionMesh} method. The boundary mesh is also used when testing for overlap between two Regions: each point in the bomdary mesh of the first Region is checked to see if it is inside or outside the second Region. Thus, the reliability of the overlap check depends on the value assigned to this attribute. If the value used is very low, it is possible for overlaps to go unnoticed. High values produce more reliable results, but can result in the overlap test being very slow. The default value is 200 for two dimensional Regions and 2000 for three or more dimensional Regions (this attribute is not used for 1-dimensional regions since the boundary of a simple 1-d Region can only ever have two points). A value of five is used if the supplied value is less than five. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } \sstsubsection{ \htmlref{CmpRegion}{CmpRegion} }{ The default MeshSize for a CmpRegion is the MeshSize of its first component Region. } \sstsubsection{ \htmlref{Stc}{Stc} }{ The default MeshSize for an Stc is the MeshSize of its encapsulated Region. } } } \sstroutine{ MinAxes }{ Minimum number of Frame axes to match }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It specifies the minimum number of axes that the target Frame may have in order to match the template. Normally, this value will equal the number of Frame axes, so that a template Frame will only match another Frame with the same number of axes as itself. By setting a different value, however, the matching process may be used to identify Frames with specified numbers of axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Frame }{ The default MinAxes value for a Frame is equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The MinAxes attribute of a CmpFrame defaults to zero. Combined with the \htmlref{MaxAxes}{MaxAxes} default of 1000000 (for a CmpFrame), this means that the default behaviour for a CmpFrame is to match any target Frame that consists of a subset of the axes in the template CmpFrame. To change this so that a CmpFrame will only match Frames that have the same number of axes, you should set the CmpFrame MinAxes and MaxAxes attributes to the number of axes in the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The MinAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When setting a MinAxes value, the value of the MaxAxes attribute may also be silently changed so that it remains consistent with (i.e. is not less than) the new value. The default MinAxes value may also be reduced to remain consistent with the MaxAxes value. \sstitem If a template Frame is used to match a target with a different number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used to determine how the individual axes of each Frame should match. } } } \sstroutine{ MinTick(axis) }{ Density of minor tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the density of minor tick marks which appear between the major axis values of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} MinTick(2)=2\texttt{"} specifies the density of minor tick marks along the second axis. The value supplied should be the number of minor divisions required between each pair of major axis values, this being one more than the number of minor tick marks to be drawn. By default, a value is chosen that depends on the gap between major axis values and the nature of the axis. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} MinTick\texttt{"} instead of \texttt{"} MinTick(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MinTick(1) value. } } } \sstroutine{ MinTickLen(axis) }{ Length of minor tick marks for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining the length of the minor tick marks drawn on the axes of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of the Plot so that, for instance, the setting \texttt{"} MinTickLen(2)=0\texttt{"} specifies the length of the minor tick marks drawn on the second axis. The MinTickLen value should be given as a fraction of the minimum dimension of the plotting area. Negative values cause minor tick marks to be placed on the outside of the corresponding grid line or axis (but subject to any clipping imposed by the underlying graphics system), while positive values cause them to be placed on the inside. The default value is $+$0.007. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The number of minor tick marks drawn is determined by the Plot\texttt{'} s \htmlref{MinTick(axis)}{MinTick(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} MinTickLen\texttt{"} instead of \texttt{"} MinTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the MinTickLen(1) value. } } } \sstroutine{ NatLat }{ Native latitude of the reference point of a FITS-WCS projection }{ \sstdescription{ This attribute gives the latitude of the reference point of the FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in radians in the \texttt{"} native spherical\texttt{"} coordinate system. This value is fixed for most projections, for instance it is PI/2 (90 degrees) for all zenithal projections. For some projections (e.g. the conics) the value is not fixed, but is specified by parameter one on the latitude axis. FITS-WCS paper II introduces the concept of a \texttt{"} fiducial point\texttt{"} which is logical distinct from the projection reference point. It is easy to confuse the use of these two points. The fiducial point is the point which has celestial coordinates given by the CRVAL FITS keywords. The native spherical coordinates for this point default to the values of the NatLat and \htmlref{NatLon}{NatLon}, but these defaults mey be over-ridden by values stored in the PVi\_j keywords. Put another way, the CRVAL keywords will by default give the celestial coordinates of the projection reference point, but may refer to some other point if alternative native longitude and latitude values are provided through the PVi\_j keywords. The NatLat attribute is read-only. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem A default value of AST\_\_BAD is used if no latitude value is available. } } } \sstroutine{ NatLon }{ Native longitude of the reference point of a FITS-WCS projection }{ \sstdescription{ This attribute gives the longitude of the reference point of the FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in radians in the \texttt{"} native spherical\texttt{"} coordinate system, and will usually be zero. See the description of attribute \htmlref{NatLat}{NatLat} for further information. The NatLon attribute is read-only. } \sstattributetype{ Floating point, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ Naxes }{ Number of Frame axes }{ \sstdescription{ This is a read-only attribute giving the number of axes in a \htmlref{Frame}{Frame} (i.e. the number of dimensions of the coordinate space which the Frame describes). This value is determined when the Frame is created. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Naxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The Naxes attribute of a CmpFrame is equal to the sum of the Naxes values of its two component Frames. } } } \sstroutine{ Ncard }{ Number of FITS header cards in a FitsChan }{ \sstdescription{ This attribute gives the total number of FITS header cards stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Ncolumn }{ The number of columns in the table }{ \sstdescription{ This attribute holds the number of columns currently in the table. Columns are added and removed using the \htmlref{astAddColumn}{astAddColumn} and \htmlref{astRemoveColumn}{astRemoveColumn} functions. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ NegLon }{ Display negative longitude values? }{ \sstdescription{ This attribute is a boolean value which controls how longitude values are normalized for display by \htmlref{astNorm}{astNorm}. If the NegLon attribute is zero, then normalized longitude values will be in the range zero to 2.pi. If NegLon is non-zero, then normalized longitude values will be in the range -pi to pi. The default value depends on the current value of the \htmlref{SkyRefIs}{SkyRefIs} attribute, If SkyRefIs has a value of \texttt{"} Origin\texttt{"} , then the default for NegLon is one, otherwise the default is zero. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ All SkyFrames have this attribute. } } } \sstroutine{ Negated }{ Region negation flag }{ \sstdescription{ This attribute controls whether a \htmlref{Region}{Region} represents the \texttt{"} inside\texttt{"} or the \texttt{"} outside\texttt{"} of the area which was supplied when the Region was created. If the attribute value is zero (the default), the Region represents the inside of the original area. However, if it is non-zero, it represents the outside of the original area. The value of this attribute may be toggled using the \htmlref{astNegate}{astNegate} function. Note, whether the boundary is considered to be inside the Region or not is controlled by the \htmlref{Closed}{Closed} attribute. Changing the value of the Negated attribute does not change the value of the Closed attribute. Thus, if Region is closed, then the boundary of the Region will be inside the Region, whatever the setting of the Negated attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Region }{ All Regions have this attribute. } } } \sstroutine{ Nframe }{ Number of Frames in a FrameSet }{ \sstdescription{ This attrbute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This value will change as Frames are added or removed, but will always be at least one. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } } \sstroutine{ Nin }{ Number of input coordinates for a Mapping }{ \sstdescription{ This attribute gives the number of coordinate values required to specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of dimensions of the space in which the Mapping\texttt{'} s input points reside). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If a CmpMap\texttt{'} s component Mappings are joined in series, then its Nin attribute is equal to the Nin attribute of the first component (or to the \htmlref{Nout}{Nout} attribute of the second component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). If a CmpMap\texttt{'} s component Mappings are joined in parallel, then its Nin attribute is given by the sum of the Nin attributes of each component (or to the sum of their Nout attributes if the CmpMap\texttt{'} s Invert attribute is non-zero). } \sstsubsection{ \htmlref{Frame}{Frame} }{ The Nin attribute for a Frame is always equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Nin attribute of a FrameSet is equal to the number of axes (Naxes attribute) of its base Frame (as specified by the FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may therefore change if a new base Frame is selected. } } } \sstroutine{ NiterInverse }{ Maximum number of iterations for the iterative inverse transformation }{ \sstdescription{ This attribute controls the iterative inverse transformation used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. Its value gives the maximum number of iterations of the Newton-Raphson algorithm to be used for each transformed position. The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ \htmlref{PolyMap}{PolyMap} }{ All PolyMaps have this attribute. } } } \sstroutine{ Nkey }{ Number of unique FITS keywords in a FitsChan }{ \sstdescription{ This attribute gives the total number of unique FITS keywords stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or deleted. If no keyword occurrs more than once in the FitsChan, the \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs more than once, the Nkey attribute value will be smaller than the Ncard attribute value. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ Nobject }{ Number of Objects in class }{ \sstdescription{ This attribute gives the total number of Objects currently in existence in the same class as the \htmlref{Object}{Object} whose attribute value is requested. This count does not include Objects which belong to derived (more specialised) classes. This attribute is mainly intended for debugging. It can be used to detect whether Objects which should have been deleted have, in fact, been deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Norm(axis) }{ Specifies the plane upon which a Plot3D draws text and markers }{ \sstdescription{ This attribute controls the appearance of text and markers drawn by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which text and markers will be drawn by all subsequent invocations of the \htmlref{astText}{astText} and \htmlref{astMark}{astMark} functions. When setting or getting the Norm attribute, the attribute name must be qualified by an axis index in the range 1 to 3. The 3 elements of the Norm attribute are together interpreted as a vector in 3D graphics coordinates that is normal to the plane upon which text and marks should be drawn. When testing or clearing the attribute, the axis index is optional. If no index is supplied, then clearing the Norm attribute will clear all three elements, and testing the Norm attribute will return a non-zero value if any of the three elements are set. The default value is 1.0 for each of the 3 elements. The length of the vector is insignificant, but an error will be reported when attempting to draw text or markers if the vector has zero length. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Plot}{Plot} }{ All Plot3Ds have this attribute. } } } \sstroutine{ NormUnit(axis) }{ Normalised physical units for formatted axis values }{ \sstdescription{ The value of this read-only attribute is derived from the current value of the Unit attribute. It will represent an equivalent system of units to the Unit attribute, but will potentially be simplified. For instance, if Unit is set to \texttt{"} s$*$(m/s)\texttt{"} , the NormUnit value will be \texttt{"} m\texttt{"} . If no simplification can be performed, the value of the NormUnit attribute will equal that of the Unit attribute. } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ All Frames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ Nout }{ Number of output coordinates for a Mapping }{ \sstdescription{ This attribute gives the number of coordinate values generated by a \htmlref{Mapping}{Mapping} to specify each output point (i.e. the number of dimensions of the space in which the Mapping\texttt{'} s output points reside). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ If a CmpMap\texttt{'} s component Mappings are joined in series, then its Nout attribute is equal to the Nout attribute of the second component (or to the \htmlref{Nin}{Nin} attribute of the first component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). If a CmpMap\texttt{'} s component Mappings are joined in parallel, then its Nout attribute is given by the sum of the Nout attributes of each component (or to the sum of their Nin attributes if the CmpMap\texttt{'} s Invert attribute is non-zero). } \sstsubsection{ \htmlref{Frame}{Frame} }{ The Nout attribute for a Frame is always equal to the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Nout attribute of a FrameSet is equal to the number of FrameSet axes (Naxes attribute) which, in turn, is equal to the Naxes attribute of the FrameSet\texttt{'} s current Frame (as specified by the \htmlref{Current}{Current} attribute). The Nout attribute value may therefore change if a new current Frame is selected. } } } \sstroutine{ Nparameter }{ The number of global parameters in the table }{ \sstdescription{ This attribute holds the number of global parameters currently in the table. Parameters are added and removed using the \htmlref{astAddParameter}{astAddParameter} and \htmlref{astRemoveParameter}{astRemoveParameter} functions. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ Nrow }{ The number of rows in the table }{ \sstdescription{ This attribute holds the index of the last row to which any contents have been added using any of the astMapPut... AST\_MAPPUT... functions. The first row has index 1. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ \htmlref{Table}{Table} }{ All Tables have this attribute. } } } \sstroutine{ NumLab(axis) }{ Draw numerical axis labels for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether labels should be drawn to represent the numerical values along each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} NumLab(2)=1\texttt{"} specifies that numerical labels should be drawn for the second axis. If the NumLab value of a Plot axis is non-zero (the default), then numerical labels will be drawn for that axis, otherwise they will be omitted. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The drawing of associated descriptive axis labels for a Plot (describing the quantity being plotted along each axis) is controlled by the \htmlref{TextLab(axis)}{TextLab(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} NumLab\texttt{"} instead of \texttt{"} NumLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the NumLab(1) value. } } } \sstroutine{ NumLabGap(axis) }{ Spacing of numerical labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining where numerical axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} NumLabGap(2)=-0.01\texttt{"} specifies where the numerical label for the second axis should be drawn. For each axis, the NumLabGap value gives the spacing between the axis line (or edge of the plotting area, if appropriate) and the nearest edge of the corresponding numerical axis labels. Positive values cause the descriptive label to be placed on the opposite side of the line to the default tick marks, while negative values cause it to be placed on the same side. The NumLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.01. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} NumLabGap\texttt{"} instead of \texttt{"} NumLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the NumLabGap(1) value. } } } \sstroutine{ ObjSize }{ The in-memory size of the Object }{ \sstdescription{ This attribute gives the total number of bytes of memory used by the \htmlref{Object}{Object}. This includes any Objects which are encapsulated within the supplied Object. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ ObsAlt }{ The geodetic altitude of the observer }{ \sstdescription{ This attribute specifies the geodetic altitude of the observer, in metres, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ ObsLat }{ The geodetic latitude of the observer }{ \sstdescription{ This attribute specifies the geodetic latitude of the observer, in degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} , \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can optionally be indicated using characters \texttt{"} N\texttt{"} and \texttt{"} S\texttt{"} in place of the usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the format \texttt{"} [s]dd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} N\texttt{"} or \texttt{"} S\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ ObsLon }{ The geodetic longitude of the observer }{ \sstdescription{ This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this attribute, but specialised subclasses of Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value is zero. The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} , \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can optionally be indicated using characters \texttt{"} E\texttt{"} and \texttt{"} W\texttt{"} in place of the usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the format \texttt{"} [s]ddd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} E\texttt{"} or \texttt{"} W\texttt{"} and the numerical value is chosen to be less than 180 degrees. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ SpecFrame }{ Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, it defines the Doppler shift introduced by the observers diurnal motion around the earths axis, which is needed when converting to or from the topocentric standard of rest. The maximum velocity error which can be caused by an incorrect value is 0.5 km/s. The default value for the attribute is zero. } \sstsubsection{ TimeFrame }{ Together with the ObsLon attribute, it is used when converting between certain time scales (TDB, TCB, LMST, LAST) } } } \sstroutine{ PVMax(i) }{ Maximum number of FITS-WCS projection parameters }{ \sstdescription{ This attribute specifies the largest legal index for a PV projection parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the largest legal value for \texttt{"} m\texttt{"} when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"} attribute). The axis index is specified by i, and should be in the range 1 to 99. The value for each axis is determined by the projection type specified when the WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be changed. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ PVi\_m }{ FITS-WCS projection parameters }{ \sstdescription{ This attribute specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection. Each PV attribute name should include two integers, i and m, separated by an underscore. The axis index is specified by i, and should be in the range 1 to 99. The parameter number is specified by m, and should be in the range 0 to 99. For example, \texttt{"} PV2\_1=45.0\texttt{"} would specify a value for projection parameter 1 of axis 2 in a WcsMap. These projection parameters correspond exactly to the values stored using the FITS-WCS keywords \texttt{"} PV1\_1\texttt{"} , \texttt{"} PV1\_2\texttt{"} , etc. This means that projection parameters which correspond to angles must be given in degrees (despite the fact that the angular coordinates and other attributes used by a WcsMap are in radians). The set of projection parameters used by a WcsMap depends on the type of projection, which is determined by its \htmlref{WcsType}{WcsType} parameter. Most projections either do not require projection parameters, or use parameters 1 and 2 associated with the latitude axis. You should consult the FITS-WCS paper for details. Some projection parameters have default values (as defined in the FITS-WCS paper) which apply if no explicit value is given. You may omit setting a value for these \texttt{"} optional\texttt{"} parameters and the default will apply. Some projection parameters, however, have no default and a value must be explicitly supplied. This is most conveniently done using the \texttt{"} options\texttt{"} argument of \htmlref{astWcsMap}{astWcsMap} (q.v.) when a WcsMap is first created. An error will result when a WcsMap is used to transform coordinates if any of its required projection parameters has not been set and lacks a default value. A \texttt{"} get\texttt{"} operation for a parameter which has not been assigned a value will return the default value defined in the FITS-WCS paper, or AST\_\_BAD if the paper indicates that the parameter has no default. A default value of zero is returned for parameters which are not accessed by the projection. Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude axis to hold the native longitude and latitude of the fiducial point of the projection, in degrees. The default values for these parameters are determined by the projection type. The AST-specific TPN projection does not use this convention - all projection parameters for both axes are used to represent polynomical correction terms, and the native longitude and latitude at the fiducial point may not be changed from the default values of zero and 90 degrees. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. \sstitem If the projection parameter values given for a WcsMap do not satisfy all the required constraints (as defined in the FITS-WCS paper), then an error will result when the WcsMap is used to transform coordinates. } } } \sstroutine{ PcdCen(axis) }{ Centre coordinates of pincushion/barrel distortion }{ \sstdescription{ This attribute specifies the centre of the pincushion/barrel distortion implemented by a \htmlref{PcdMap}{PcdMap}. It takes a separate value for each axis of the PcdMap so that, for instance, the settings \texttt{"} PcdCen(1)=345.0,PcdCen(2)=-104.4\texttt{"} specify that the pincushion distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2 respectively. This attribute is set when a PcdMap is created, but may later be modified. If the attribute is cleared, the default value for both axes is zero. Note, the value of this attribute may changed only if the PcdMap has no more than one reference. That is, an error is reported if the PcdMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ PcdMap }{ All PcdMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If no axis is specified, (e.g. \texttt{"} PcdCen\texttt{"} instead of \texttt{"} PcdCen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of both axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the PcdCen(1) value. } } } \sstroutine{ Permute }{ Permute axis order? }{ \sstdescription{ This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It specifies whether the axis order of the target Frame may be permuted in order to obtain a match. If the template\texttt{'} s Permute value is zero, it will match a target only if it can do so without changing the order of its axes. Otherwise, it will attempt to permute the target\texttt{'} s axes as necessary. The default value is 1, so that axis permutation will be attempted. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. However, the Frame class effectively ignores this attribute and behaves as if it has the value 1. This is because the axes of a basic Frame are not distinguishable and will always match any other Frame whatever their order. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ Unlike a basic Frame, the SkyFrame class makes use of this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Permute attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ PolarLong }{ The longitude value to assign to either pole }{ \sstdescription{ This attribute holds the longitude value, in radians, to be returned when a Cartesian position corresponding to either the north or south pole is transformed into spherical coordinates. The default value is zero. Note, the value of this attribute may changed only if the \htmlref{SphMap}{SphMap} has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ SphMap }{ All SphMaps have this attribute. } } } \sstroutine{ PolyTan }{ Use PVi\_m keywords to define distorted TAN projection? }{ \sstdescription{ This attribute is a boolean value which specifies how FITS \texttt{"} TAN\texttt{"} projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero, the projection is assumed to conform to the published FITS-WCS standard. If positive, the convention for a distorted TAN projection included in an early draft version of FITS-WCS paper II are assumed. In this convention the coefficients of a polynomial distortion to be applied to intermediate world coordinates are specified by the \htmlref{PVi\_m}{PVi\_m} keywords. This convention was removed from the paper before publication and so does not form part of the standard. Indeed, it is incompatible with the published standard because it re-defines the meaning of the first five PVi\_m keywords on the longitude axis, which are reserved by the published standard for other purposes. However, headers that use this convention are still to be found, for instance the SCAMP utility (http://www.astromatic.net/software/scamp) creates them. The default value for the PolyTan attribute is -1. A negative values causes the used convention to depend on the contents of the \htmlref{FitsChan}{FitsChan}. If the FitsChan contains any PVi\_m keywords for the latitude axis, or if it contains PVi\_m keywords for the longitude axis with \texttt{"} m\texttt{"} greater than 4, then the distorted TAN convention is used. Otherwise, the standard convention is used. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ PreserveAxes }{ Preserve axes? }{ \sstdescription{ This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It determines which axes appear (and in what order) in the \texttt{"} result\texttt{"} Frame produced. If PreserveAxes is zero in the template Frame, then the result Frame will have the same number (and order) of axes as the template. If it is non-zero, however, the axes of the target Frame will be preserved, so that the result Frame will have the same number (and order) of axes as the target. The default value is zero, so that target axes are not preserved and the result Frame resembles the template. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Frame }{ All Frames have this attribute. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The PreserveAxes attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } } \sstroutine{ ProjP(m) }{ FITS-WCS projection parameters }{ \sstdescription{ This attribute provides aliases for the PV attributes, which specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection. ProjP is retained for compatibility with previous versions of FITS-WCS and AST. New applications should use the PV attibute instead. Attributes ProjP(0) to ProjP(9) correspond to attributes PV$<$axlat$>$\_0 to PV$<$axlat$>$\_9, where $<$axlat$>$ is replaced by the index of the latitude axis (given by attribute WcsAxis(2)). See PV for further details. Note, the value of this attribute may changed only if the WcsMap has no more than one reference. That is, an error is reported if the WcsMap has been cloned, either by including it within another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ Projection }{ Sky projection description }{ \sstdescription{ This attribute provides a place to store a description of the type of sky projection used when a \htmlref{SkyFrame}{SkyFrame} is attached to a 2-dimensional object, such as an image or plotting surface. For example, typical values might be \texttt{"} orthographic\texttt{"} , \texttt{"} Hammer-Aitoff\texttt{"} or \texttt{"} cylindrical equal area\texttt{"} . The Projection value is purely descriptive and does not affect the celestial coordinate system represented by the SkyFrame in any way. If it is set to a non-blank string, the description provided may be used when forming the default value for the SkyFrame\texttt{'} s \htmlref{Title}{Title} attribute (so that typically it will appear in graphical output, for instance). The default value is an empty string. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ RefCount }{ Count of active Object pointers }{ \sstdescription{ This attribute gives the number of active pointers associated with an \htmlref{Object}{Object}. It is modified whenever pointers are created or annulled (by \htmlref{astClone}{astClone}, \htmlref{astAnnul}{astAnnul} or \htmlref{astEnd}{astEnd} for example). The count includes the initial pointer issued when the Object was created. If the reference count for an Object falls to zero as the result of annulling a pointer to it, then the Object will be deleted. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ RefDec }{ The declination of the reference point }{ \sstdescription{ This attribute specifies the FK5 J2000.0 declination of a reference point on the sky. See the description of attribute \htmlref{RefRA}{RefRA} for details. The default RefDec is \texttt{"} 0:0:0\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ RefRA }{ The right ascension of the reference point }{ \sstdescription{ This attribute, together with the \htmlref{RefDec}{RefDec} attribute, specifies the FK5 J2000.0 coordinates of a reference point on the sky. For 1-dimensional spectra, this should normally be the position of the source. For spectral data with spatial coverage (spectral cubes, etc), this should be close to centre of the spatial coverage. It is used to define the correction for Doppler shift to be applied when using the \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert} method to convert between different standards of rest. The \htmlref{SpecFrame}{SpecFrame} class assumes this velocity correction is spatially invariant. If a single SpecFrame is used (for instance, as a component of a \htmlref{CmpFrame}{CmpFrame}) to describe spectral values at different points on the sky, then it is assumes that the doppler shift at any spatial position is the same as at the reference position. The maximum velocity error introduced by this assumption is of the order of V$*$SIN(FOV), where FOV is the angular field of view, and V is the relative velocity of the two standards of rest. As an example, when correcting from the observers rest frame (i.e. the topocentric rest frame) to the kinematic local standard of rest the maximum value of V is about 20 km/s, so for 5 arc-minute field of view the maximum velocity error introduced by the correction will be about 0.03 km/s. As another example, the maximum error when correcting from the observers rest frame to the local group is about 5 km/s over a 1 degree field of view. The RefRA and RefDec attributes are stored internally in radians, but are converted to and from a string for access. The format \texttt{"} hh:mm:ss.ss\texttt{"} is used for RefRA, and \texttt{"} dd:mm:ss.s\texttt{"} is used for RefDec. The methods \htmlref{astSetRefPos}{astSetRefPos} and \htmlref{astGetRefPos}{astGetRefPos} may be used to access the values of these attributes directly as unformatted values in radians. The default for RefRA is \texttt{"} 0:0:0\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ RegionClass }{ The AST class name of the Region encapsulated within an Stc }{ \sstdescription{ This is a read-only attribute giving the AST class name of the \htmlref{Region}{Region} encapsulated within an \htmlref{Stc}{Stc} (that is, the class of the Region which was supplied when the Stc was created). } \sstattributetype{ String, read-only. } \sstapplicability{ \sstsubsection{ Stc }{ All Stc objects this attribute. } } } \sstroutine{ Report }{ Report transformed coordinates? }{ \sstdescription{ This attribute controls whether coordinate values are reported whenever a \htmlref{Mapping}{Mapping} is used to transform a set of points. If its value is zero (the default), no report is made. However, if it is non-zero, the coordinates of each point are reported (both before and after transformation) by writing them to standard output. This attribute is provided as an aid to debugging, and to avoid having to report values explicitly in simple programs. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ When applied to a compound Mapping (CmpMap), only the Report attribute of the CmpMap, and not those of its component Mappings, is used. Coordinate information is never reported for the component Mappings individually, only for the complete CmpMap. } \sstsubsection{ \htmlref{Frame}{Frame} }{ When applied to any Frame, the formatting capabilities of the Frame (as provided by the \htmlref{astFormat}{astFormat} function) will be used to format the reported coordinates. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ When applied to any FrameSet, the formatting capabilities of the base and current Frames will be used (as above) to individually format the input and output coordinates, as appropriate. The Report attribute of a FrameSet is not itself affected by selecting a new base or current Frame, but the resulting formatting capabilities may be. } } \sstnotes{ \sstitemlist{ \sstitem Unlike most other attributes, the value of the Report attribute is not transferred when a Mapping is copied. Instead, its value is undefined (and therefore defaults to zero) in any copy. Similarly, it becomes undefined in any external representation of a Mapping produced by the \htmlref{astWrite}{astWrite} function. } } } \sstroutine{ ReportLevel }{ Determines which read/write conditions are reported }{ \sstdescription{ This attribute determines which, if any, of the conditions that occur whilst reading or writing an \htmlref{Object}{Object} should be reported. These conditions will generate either a fatal error or a warning, as determined by attribute \htmlref{Strict}{Strict}. ReportLevel can take any of the following values: 0 - Do not report any conditions. 1 - \htmlref{Report}{Report} only conditions where significant information content has been changed. For instance, an unsupported time-scale has been replaced by a supported near-equivalent time-scale. Another example is if a basic \htmlref{Channel}{Channel} unexpected encounters data items that may have been introduced by later versions of AST. 2 - Report the above, and in addition report significant default values. For instance, if no time-scale was specified when reading an Object from an external data source, report the default time-scale that is being used. 3 - Report the above, and in addition report any other potentially interesting conditions that have no significant effect on the conversion. For instance, report if a time-scale of \texttt{"} TT\texttt{"} (terrestrial time) is used in place of \texttt{"} ET\texttt{"} (ephemeris time). This change has no signficiant effect because ET is the predecessor of, and is continuous with, TT. Synonyms such as \texttt{"} IAT\texttt{"} and \texttt{"} TAI\texttt{"} are another example. The default value is 1. Note, there are many other conditions that can occur whilst reading or writing an Object that completely prevent the conversion taking place. Such conditions will always generate errors, irrespective of the ReportLevel and Strict attributes. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ All the conditions selected by the FitsChan \htmlref{Warnings}{Warnings} attribute are reported at level 1. } } } \sstroutine{ RestFreq }{ The rest frequency }{ \sstdescription{ This attribute specifies the frequency corresponding to zero velocity. It is used when converting between between velocity-based coordinate systems and and other coordinate systems (such as frequency, wavelength, energy, etc). The default value is 1.0E5 GHz. When setting a new value for this attribute, the new value can be supplied either directly as a frequency, or indirectly as a wavelength or energy, in which case the supplied value is converted to a frequency before being stored. The nature of the supplied value is indicated by appending text to the end of the numerical value indicating the units in which the value is supplied. If the units are not specified, then the supplied value is assumed to be a frequency in units of GHz. If the supplied unit is a unit of frequency, the supplied value is assumed to be a frequency in the given units. If the supplied unit is a unit of length, the supplied value is assumed to be a (vacuum) wavelength. If the supplied unit is a unit of energy, the supplied value is assumed to be an energy. For instance, the following strings all result in a rest frequency of around 1.4E14 Hz being used: \texttt{"} 1.4E5\texttt{"} , \texttt{"} 1.4E14 Hz\texttt{"} , \texttt{"} 1.4E14 s$*$$*$-1\texttt{"} , \texttt{"} 1.4E5 GHz\texttt{"} , \texttt{"} 2.14E-6 m\texttt{"} , \texttt{"} 21400 Angstrom\texttt{"} , \texttt{"} 9.28E-20 J\texttt{"} , \texttt{"} 9.28E-13 erg\texttt{"} , \texttt{"} 0.58 eV\texttt{"} , etc. When getting the value of this attribute, the returned value is always a frequency in units of GHz. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ RootCorner }{ Specifies which edges of the 3D box should be annotated }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining which edges of the cube enclosing the 3D graphics space are used for displaying numerical and descriptive axis labels. The attribute value identifies one of the eight corners of the cube within which graphics are being drawn (i.e. the cube specified by the \texttt{"} graphbox\texttt{"} parameter when \htmlref{astPlot3D}{astPlot3D} was called tp create the \htmlref{Plot3D}{Plot3D}). \htmlref{Axis}{Axis} labels and tick marks will be placed on the three cube edges that meet at the given corner. The attribute value should consist of three character, each of which must be either \texttt{"} U\texttt{"} or \texttt{"} L\texttt{"} . The first character in the string specifies the position of the corner on the first graphics axis. If the character is \texttt{"} U\texttt{"} then the corner is at the upper bound on the first graphics axis. If it is \texttt{"} L\texttt{"} , then the corner is at the lower bound on the first axis. Likewise, the second and third characters in the string specify the location of the corner on the second and third graphics axes. For instance, corner \texttt{"} LLL\texttt{"} is the corner that is at the lower bound on all three graphics axes, and corner \texttt{"} ULU\texttt{"} is at the upper bound on axes 1 and 3 but at the lower bound on axis 2. The default value is \texttt{"} LLL\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Plot3D }{ All Plot3Ds have this attribute. } } } \sstroutine{ Seed }{ Random number seed for a MathMap }{ \sstdescription{ This attribute, which may take any integer value, determines the sequence of random numbers produced by the random number functions in \htmlref{MathMap}{MathMap} expressions. It is set to an unpredictable default value when a MathMap is created, so that by default each MathMap uses a different set of random numbers. If required, you may set this Seed attribute to a value of your choosing in order to produce repeatable behaviour from the random number functions. You may also enquire the Seed value (e.g. if an initially unpredictable value has been used) and then use it to reproduce the resulting sequence of random numbers, either from the same MathMap or from another one. Clearing the Seed attribute gives it a new unpredictable default value. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } } \sstroutine{ SideBand }{ Indicates which sideband a dual sideband spectrum represents }{ \sstdescription{ This attribute indicates whether the \htmlref{DSBSpecFrame}{DSBSpecFrame} currently represents its lower or upper sideband, or an offset from the local oscillator frequency. When querying the current value, the returned string is always one of \texttt{"} usb\texttt{"} (for upper sideband), \texttt{"} lsb\texttt{"} (for lower sideband), or \texttt{"} lo\texttt{"} (for offset from the local oscillator frequency). When setting a new value, any of the strings \texttt{"} lsb\texttt{"} , \texttt{"} usb\texttt{"} , \texttt{"} observed\texttt{"} , \texttt{"} image\texttt{"} or \texttt{"} lo\texttt{"} may be supplied (case insensitive). The \texttt{"} observed\texttt{"} sideband is which ever sideband (upper or lower) contains the central spectral position given by attribute \htmlref{DSBCentre}{DSBCentre}, and the \texttt{"} image\texttt{"} sideband is the other sideband. It is the sign of the \htmlref{IF}{IF} attribute which determines if the observed sideband is the upper or lower sideband. The default value for SideBand is the observed sideband. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ DSBSpecFrame }{ All DSBSpecFrames have this attribute. } } } \sstroutine{ SimpFI }{ Forward-inverse MathMap pairs simplify? }{ \sstdescription{ This attribute should be set to a non-zero value if applying a \htmlref{MathMap}{MathMap}\texttt{'} s forward transformation, followed immediately by the matching inverse transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). By default, the SimpFI attribute is zero, so that AST will not perform this simplification unless you have set SimpFI to indicate that it is safe to do so. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient. \sstitem The consent of both MathMaps is required before simplification can take place. If either has a SimpFI value of zero, then simplification will not occur. \sstitem The SimpFI attribute controls simplification only in the case where a MathMap\texttt{'} s forward transformation is followed by the matching inverse transformation. It does not apply if an inverse transformation is followed by a forward transformation. This latter case is controlled by the \htmlref{SimpIF}{SimpIF} attribute. \sstitem The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"} and \texttt{"} inv\texttt{"} parameters of its constructor function). If the MathMap is inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. } } } \sstroutine{ SimpIF }{ Inverse-forward MathMap pairs simplify? }{ \sstdescription{ This attribute should be set to a non-zero value if applying a \htmlref{MathMap}{MathMap}\texttt{'} s inverse transformation, followed immediately by the matching forward transformation will always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). By default, the SimpIF attribute is zero, so that AST will not perform this simplification unless you have set SimpIF to indicate that it is safe to do so. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ MathMap }{ All MathMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For simplification to occur, the two MathMaps must be in series and be identical (with textually identical transformation functions). Functional equivalence is not sufficient. \sstitem The consent of both MathMaps is required before simplification can take place. If either has a SimpIF value of zero, then simplification will not occur. \sstitem The SimpIF attribute controls simplification only in the case where a MathMap\texttt{'} s inverse transformation is followed by the matching forward transformation. It does not apply if a forward transformation is followed by an inverse transformation. This latter case is controlled by the \htmlref{SimpFI}{SimpFI} attribute. \sstitem The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"} and \texttt{"} inv\texttt{"} parameters of its constructor function). If the MathMap is inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the SimpFI and SimpIF attributes will be interchanged. } } } \sstroutine{ SimpVertices }{ Simplify a Polygon by transforming its vertices? }{ \sstdescription{ This attribute controls the behaviour of the \htmlref{astSimplify}{astSimplify} method when applied to a \htmlref{Polygon}{Polygon}. The simplified Polygon is created by transforming the vertices from the \htmlref{Frame}{Frame} in which the Polygon was originally defined into the Frame currently represented by the Polygon. If SimpVertices is non-zero (the default) then this simplified Polygon is returned without further checks. If SimpVertices is zero, a check is made that the edges of the new Polygon do not depart significantly from the edges of the original Polygon (as determined by the uncertainty associated with the Polygon). This could occur, for instance, if the \htmlref{Mapping}{Mapping} frrm the original to the current Frame is highly non-linear. If this check fails, the original unsimplified Polygon is returned without change. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Polygon }{ All Polygons have this attribute. } } } \sstroutine{ SinkFile }{ Output file to which to data should be written }{ \sstdescription{ This attribute specifies the name of a file to which the \htmlref{Channel}{Channel} should write data. If specified it is used in preference to any sink function specified when the Channel was created. Assigning a new value to this attribute will cause any previously opened SinkFile to be closed. The first subsequent call to \htmlref{astWrite}{astWrite} will attempt to open the new file (an error will be reported if the file cannot be opened), and write data to it. All subsequent call to astWrite will write data to the new file, until the SinkFile attribute is cleared or changed. Clearing the attribute causes any open SinkFile to be closed. All subsequent data writes will use the sink function specified when the Channel was created, or will write to standard output if no sink function was specified. If no value has been assigned to SinkFile, a null string will be returned if an attempt is made to get the attribute value. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ When the FitsChan is destroyed, any headers in the FitsChan will be written out to the sink file, if one is specified (if not, the sink function used when the FitsChan was created is used). The sink file is a text file (not a FITS file) containing one header per line. } } \sstnotes{ \sstitemlist{ \sstitem A new SinkFile will over-write any existing file with the same name unless the existing file is write protected, in which case an error will be reported. \sstitem Any open SinkFile is closed when the Channel is deleted. \sstitem If the Channel is copied or dumped (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow}) the SinkFile attribute is left in a cleared state in the output Channel (i.e. the value of the SinkFile attribute is not copied). } } } \sstroutine{ Size(element) }{ Character size for a Plot element }{ \sstdescription{ This attribute determines the character size used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Size(title)=2.0\texttt{"} causes the Plot title to be drawn using twice the default character size. The range of character sizes available and the appearance of the resulting text is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default character size supplied by this graphics system. } \sstattributetype{ Floating Point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Size\texttt{"} instead of \texttt{"} Size(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Size(TextLab) value. } } } \sstroutine{ SizeGuess }{ The expected size of the KeyMap }{ \sstdescription{ This is attribute gives an estimate of the number of entries that will be stored in the \htmlref{KeyMap}{KeyMap}. It is used to tune the internal properties of the KeyMap for speed and efficiency. A larger value will result in faster access at the expense of increased memory requirements. However if the SizeGuess value is much larger than the actual size of the KeyMap, then there will be little, if any, speed gained by making the SizeGuess even larger. The default value is 300. The value of this attribute can only be changed if the KeyMap is empty. Its value can be set conveniently when creating the KeyMap. An error will be reported if an attempt is made to set or clear the attribute when the KeyMap contains any entries. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } } \sstroutine{ Skip }{ Skip irrelevant data? }{ \sstdescription{ This is a boolean attribute which indicates whether the \htmlref{Object}{Object} data being read through a \htmlref{Channel}{Channel} are inter-mixed with other, irrelevant, external data. If Skip is zero (the default), then the source of input data is expected to contain descriptions of AST Objects and comments and nothing else (if anything else is read, an error will result). If Skip is non-zero, then any non-Object data encountered between Objects will be ignored and simply skipped over in order to reach the next Object. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ The FitsChan class sets the default value of this attribute to 1, so that all irrelevant FITS headers will normally be ignored. } } } \sstroutine{ SkyRef(axis) }{ Position defining the offset coordinate system }{ \sstdescription{ This attribute allows a \htmlref{SkyFrame}{SkyFrame} to represent offsets, rather than absolute axis values, within the coordinate system specified by the \htmlref{System}{System} attribute. If supplied, SkyRef should be set to hold the longitude and latitude of a point within the coordinate system specified by the System attribute. The coordinate system represented by the SkyFrame will then be rotated in order to put the specified position at either the pole or the origin of the new coordinate system (as indicated by the \htmlref{SkyRefIs}{SkyRefIs} attribute). The orientation of the modified coordinate system is then controlled using the SkyRefP attribute. If an integer axis index is included in the attribute name (e.g. \texttt{"} SkyRef(1)\texttt{"} ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). If no axis index is included in the attribute name (e.g. \texttt{"} SkyRef\texttt{"} ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute. The default values for SkyRef are zero longitude and zero latitude. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the System attribute of the SkyFrame is changed, any position given for SkyRef is transformed into the new System. \sstitem If a value has been assigned to SkyRef attribute, then the default values for certain attributes are changed as follows: the default axis Labels for the SkyFrame are modified by appending \texttt{"} offset\texttt{"} to the end, the default axis Symbols for the SkyFrame are modified by prepending the character \texttt{"} D\texttt{"} to the start, and the default title is modified by replacing the projection information by the origin information. } } \sstdiytopic{ Aligning SkyFrames with Offset Coordinate Systems }{ The offset coordinate system within a SkyFrame should normally be considered as a superficial \texttt{"} re-badging\texttt{"} of the axes of the coordinate system specified by the System attribute - it merely provides an alternative numerical \texttt{"} label\texttt{"} for each position in the System coordinate system. The SkyFrame retains full knowledge of the celestial coordinate system on which the offset coordinate system is based (given by the System attribute). For instance, the SkyFrame retains knowledge of the way that one celestial coordinate system may \texttt{"} drift\texttt{"} with respect to another over time. Normally, if you attempt to align two SkyFrames (e.g. using the \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame} routine), the effect of any offset coordinate system defined in either SkyFrame will be removed, resulting in alignment being performed in the celestial coordinate system given by the \htmlref{AlignSystem}{AlignSystem} attribute. However, by setting the \htmlref{AlignOffset}{AlignOffset} attribute ot a non-zero value, it is possible to change this behaviour so that the effect of the offset coordinate system is not removed when aligning two SkyFrames. } } \sstroutine{ SkyRefIs }{ Selects the nature of the offset coordinate system }{ \sstdescription{ This attribute controls how the values supplied for the SkyRef and SkyRefP attributes are used. These three attributes together allow a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin or pole within the coordinate system specified by the \htmlref{System}{System} attribute, rather than absolute axis values. SkyRefIs can take one of the case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"} or \texttt{"} Ignored\texttt{"} . If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system represented by the SkyFrame is modified to put the origin of longitude and latitude at the position specified by the SkyRef attribute. If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented by the SkyFrame is modified to put the north pole at the position specified by the SkyRef attribute. If SkyRefIs is set to \texttt{"} Ignored\texttt{"} (the default), then any value set for the SkyRef attribute is ignored, and the SkyFrame represents the coordinate system specified by the System attribute directly without any rotation. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ SkyRefP(axis) }{ Position on primary meridian of offset coordinate system }{ \sstdescription{ This attribute is used to control the orientation of the offset coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used, it should be set to hold the longitude and latitude of a point within the coordinate system specified by the \htmlref{System}{System} attribute. The offset coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in order to put the position supplied for SkyRefP on the zero longitude meridian. This rotation is about an axis from the centre of the celestial sphere to the point specified by the SkyRef attribute. The default value for SkyRefP is usually the north pole (that is, a latitude of $+$90 degrees in the coordinate system specified by the System attribute). The exception to this is if the SkyRef attribute is itself set to either the north or south pole. In these cases the default for SkyRefP is the origin (that is, a (0,0) in the coordinate system specified by the System attribute). If an integer axis index is included in the attribute name (e.g. \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single floating point axis value, in radians, when setting a value for the attribute, and will be returned in the same form when getting the value of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then the attribute value should be supplied as a character string containing two formatted axis values (an axis 1 value followed by a comma, followed by an axis 2 value). The same form will be used when getting the value of the attribute. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If the position given by the SkyRef attribute defines the origin of the offset coordinate system (that is, if the SkyRefIs attribute is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations which will put the supplied SkyRefP position on the zero longitude meridian. The orientation which is actually used is the one which gives the SkyRefP position a positive latitude in the offset coordinate system (the other possible orientation would give the SkyRefP position a negative latitude). \sstitem An error will be reported if an attempt is made to use a SkyRefP value which is co-incident with SkyRef or with the point diametrically opposite to SkyRef on the celestial sphere. The reporting of this error is deferred until the SkyRef and SkyRefP attribute values are used within a calculation. \sstitem If the System attribute of the SkyFrame is changed, any position given for SkyRefP is transformed into the new System. } } } \sstroutine{ SkyTol }{ The smallest significant shift in sky coordinates }{ \sstdescription{ This attribute indicates the accuracy of the axis values that will be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two positions within the SkyFrame is smaller than the value of SkyTol, then the two positions will (for the puposes indicated below) be considered to be co-incident. This value is used only when constructing the \htmlref{Mapping}{Mapping} between two different SkyFrames (for instance, when calling \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame}). If the transformation between the two SkyFrames causes positions to shift by less than SkyTol arc-seconds, then the transformation is replaced by a \htmlref{UnitMap}{UnitMap}. This could in certain circumatances allow major simplifications to be made to the transformation between any pixel grids associated with the two SkyFrames (for instance, if each SkyFrame is part of the WCS \htmlref{FrameSet}{FrameSet} associated with an image). A common case is when two SkyFrames use the FK5 system, but have slightly different \htmlref{Epoch}{Epoch} values. If the \htmlref{AlignSystem}{AlignSystem} attribute has its default value of \texttt{"} ICRS\texttt{"} , then the transformation between the two SkyFrames will include a very small rotation (FK5 rotates with respect to ICRS as a rate of about 0.0005 arc-seconds per year). In most circumstances such a small rotation is insignificant. Setting SkyTol to some suitably small non-zero value will cause this rotation to be ignored, allowing much simpler transformations to be used. The test to determine the shift introduced by transforming between the two SkyFrames is performed by transforming a set of 14 position spread evenly over the whole sky. The largest shift produced at any of these 14 positions is compared to the value of SkyTol. The SkyTol value is in units of arc-seconds, and the default value is 0.001. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SkyFrame }{ All SkyFrames have this attribute. } } } \sstroutine{ SortBy }{ Determines how keys are sorted in a KeyMap }{ \sstdescription{ This attribute determines the order in which keys are returned by the \htmlref{astMapKey}{astMapKey} function. It may take the following values (the default is \texttt{"} None\texttt{"} ): \sstitemlist{ \sstitem \texttt{"} None\texttt{"} : The keys are returned in an arbitrary order. This is the fastest method as it avoids the need for a sorted list of keys to be maintained and used. \sstitem \texttt{"} AgeDown\texttt{"} : The keys are returned in the order in which values were stored in the \htmlref{KeyMap}{KeyMap}, with the key for the most recent value being returned last. If the value of an existing entry is changed, it goes to the end of the list. \sstitem \texttt{"} AgeUp\texttt{"} : The keys are returned in the order in which values were stored in the KeyMap, with the key for the most recent value being returned first. If the value of an existing entry is changed, it goes to the top of the list. \sstitem \texttt{"} KeyAgeDown\texttt{"} : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned last. If the value of an existing entry is changed, its position in the list does not change. \sstitem \texttt{"} KeyAgeUp\texttt{"} : The keys are returned in the order in which they were originally stored in the KeyMap, with the most recent key being returned first. If the value of an existing entry is changed, its position in the list does not change. \sstitem \texttt{"} KeyDown\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} being returned last. \sstitem \texttt{"} KeyUp\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} being returned first. } } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ KeyMap }{ All KeyMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If a new value is assigned to SortBy (or if SortBy is cleared), all entries currently in the KeyMap are re-sorted according to the new SortBy value. } } } \sstroutine{ SourceFile }{ Input file from which to read data }{ \sstdescription{ This attribute specifies the name of a file from which the \htmlref{Channel}{Channel} should read data. If specified it is used in preference to any source function specified when the Channel was created. Assigning a new value to this attribute will cause any previously opened SourceFile to be closed. The first subsequent call to \htmlref{astRead}{astRead} will attempt to open the new file (an error will be reported if the file cannot be opened), and read data from it. All subsequent call to astRead will read data from the new file, until the SourceFile attribute is cleared or changed. Clearing the attribute causes any open SourceFile to be closed. All subsequent data reads will use the source function specified when the Channel was created, or will read from standard input if no source function was specified. If no value has been assigned to SourceFile, a null string will be returned if an attempt is made to get the attribute value. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{FitsChan}{FitsChan} }{ In the case of a FitsChan, the specified SourceFile supplements the source function specified when the FitsChan was created, rather than replacing the source function. The source file should be a text file (not a FITS file) containing one header per line. When a value is assigned to SourceFile, the file is opened and read immediately, and all headers read from the file are appended to the end of any header already in the FitsChan. The file is then closed. Clearing the SourceFile attribute has no further effect, other than nullifying the string (i.e. the file name) associated with the attribute. } } \sstnotes{ \sstitemlist{ \sstitem Any open SourceFile is closed when the Channel is deleted. \sstitem If the Channel is copied or dumped (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow}) the SourceFile attribute is left in a cleared state in the output Channel (i.e. the value of the SourceFile attribute is not copied). } } } \sstroutine{ SourceSys }{ Spectral system in which the source velocity is stored }{ \sstdescription{ This attribute identifies the spectral system in which the \htmlref{SourceVel}{SourceVel} attribute value (the source velocity) is supplied and returned. It can be one of the following: \sstitemlist{ \sstitem \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) \sstitem \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) \sstitem \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) \sstitem \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) \sstitem \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) } When setting a new value for the SourceVel attribute, the source velocity should be supplied in the spectral system indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity will be returned in this spectral system. If the value of SourceSys is changed, the value stored for SourceVel will be converted from the old to the new spectral systems. The default value is \texttt{"} VELO\texttt{"} (apparent radial velocity). } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ SourceVRF }{ Rest frame in which the source velocity is stored }{ \sstdescription{ This attribute identifies the rest frame in which the source velocity or redshift is stored (the source velocity or redshift is accessed using attribute \htmlref{SourceVel}{SourceVel}). When setting a new value for the SourceVel attribute, the source velocity or redshift should be supplied in the rest frame indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity or redshift will be returned in this rest frame. If the value of SourceVRF is changed, the value stored for SourceVel will be converted from the old to the new rest frame. The values which can be supplied are the same as for the \htmlref{StdOfRest}{StdOfRest} attribute (except that SourceVRF cannot be set to \texttt{"} Source\texttt{"} ). The default value is \texttt{"} Helio\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } } \sstroutine{ SourceVel }{ The source velocity }{ \sstdescription{ This attribute (together with \htmlref{SourceSys}{SourceSys}, \htmlref{SourceVRF}{SourceVRF}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) defines the \texttt{"} Source\texttt{"} standard of rest (see attribute \htmlref{StdOfRest}{StdOfRest}). This is a rest frame which is moving towards the position given by RefRA and RefDec at a velocity given by SourceVel. A positive value means the source is moving away from the observer. When a new value is assigned to this attribute, the supplied value is assumed to refer to the spectral system specified by the SourceSys attribute. For instance, the SourceVel value may be supplied as a radio velocity, a redshift, a beta factor, etc. Similarly, when the current value of the SourceVel attribute is obtained, the returned value will refer to the spectral system specified by the SourceSys value. If the SourceSys value is changed, any value previously stored for the SourceVel attribute will be changed automatically from the old spectral system to the new spectral system. When setting a value for SourceVel, the value should be supplied in the rest frame specified by the SourceVRF attribute. Likewise, when getting the value of SourceVel, it will be returned in the rest frame specified by the SourceVRF attribute. The default SourceVel value is zero. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ All SpecFrames have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem It is important to set an appropriate value for SourceVRF and SourceSys before setting a value for SourceVel. If a new value is later set for SourceVRF or SourceSys, the value stored for SourceVel will simultaneously be changed to the new standard of rest or spectral system. } } } \sstroutine{ SpecOrigin }{ The zero point for SpecFrame axis values }{ \sstdescription{ This specifies the origin from which all spectral values are measured. The default value (zero) results in the \htmlref{SpecFrame}{SpecFrame} describing absolute spectral values in the system given by the \htmlref{System}{System} attribute (e.g. frequency, velocity, etc). If a SpecFrame is to be used to describe offset from some origin, the SpecOrigin attribute should be set to hold the required origin value. The SpecOrigin value stored inside the SpecFrame structure is modified whenever SpecFrame attribute values are changed so that it refers to the original spectral position. When setting a new value for this attribute, the supplied value is assumed to be in the system, units and standard of rest described by the SpecFrame. Likewise, when getting the value of this attribute, the value is returned in the system, units and standard of rest described by the SpecFrame. If any of these attributes are changed, then any previously stored SpecOrigin value will also be changed so that refers to the new system, units or standard of rest. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } } \sstroutine{ SpecVal }{ The spectral position at which flux values are measured }{ \sstdescription{ This attribute specifies the spectral position (frequency, wavelength, etc.), at which the values described by the \htmlref{FluxFrame}{FluxFrame} are measured. It is used when determining the \htmlref{Mapping}{Mapping} between between FluxFrames. The default value and spectral system used for this attribute are both specified when the FluxFrame is created. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ FluxFrame }{ All FluxFrames have this attribute. } } } \sstroutine{ StcsArea }{ Return the CoordinateArea component when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{astRead}{astRead} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsArea is set non-zero (the default), then a \htmlref{Region}{Region} representing the STC CoordinateArea will be returned by astRead. If StcsArea is set to zero, then the STC CoordinateArea will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by astRead will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this case, the Region representing the STC CoordinateArea will be stored in the returned KeyMap using the key \texttt{"} AREA\texttt{"} . If StcsArea is the only attribute to be set non-zero, then the Object returned by astRead will be the CoordinateArea Region itself. \sstitem The class of Region used to represent the CoordinateArea for each STC-S sub-phrase is determined by the first word in the sub-phrase (the \texttt{"} sub-phrase identifier\texttt{"} ). The individual sub-phrase Regions are combined into a single \htmlref{Prism}{Prism}, which is then simplified using \htmlref{astSimplify}{astSimplify} to form the returned region. \sstitem Sub-phrases that represent a single value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} or \texttt{"} Redshift\texttt{"} ) are considered to be be part of the STC CoordinateArea component. \sstitem The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times. \sstitem The \htmlref{Epoch}{Epoch} attribute for the returned Region is set in the same way as the TimeOrigin attribute (see above). } } } \sstroutine{ StcsCoords }{ Return the Coordinates component when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{astRead}{astRead} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsCoords is set non-zero, then a \htmlref{PointList}{PointList} representing the STC Coordinates will be returned by astRead. If StcsCoords is set to zero (the default), then the STC Coordinates will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsArea}{StcsArea} and \htmlref{StcsProps}{StcsProps} can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by astRead will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this case, the PointList representing the STC Coordinates will be stored in the returned KeyMap using the key \texttt{"} COORDS\texttt{"} . If StcsCoords is the only attribute to be set non-zero, then the Object returned by astRead will be the Coordinates PointList itself. \sstitem The Coordinates component is specified by the additional axis values embedded within the body of each STC-S sub-phrase that represents an extended area. Sub-phrases that represent a single value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} or \texttt{"} Redshift\texttt{"} ) are not considered to be be part of the STC Coordinates component. \sstitem If the STC-S documents does not contain a Coordinates component, then a NULL object pointer will be returned by astRead if the Coordinates component is the only object being returned. If other objects are also being returned (see attributes StcsProps and StcsArea), then the returned KeyMap will contain a \texttt{"} COORDS\texttt{"} key only if the Coordinates component is read succesfully. \sstitem The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no start time is specified by the sub-phrase, then the stop time will be used instead. If no stop time is specified by the sub-phrase, then the single time value specified in the sub-phrase will be used instead. Subsequently clearing the TimeOrigin attribute (or setting its value to zero) will cause the TimeFrame to reprsent absolute times. \sstitem The \htmlref{Epoch}{Epoch} attribute for the returned \htmlref{Region}{Region} is set in the same way as the TimeOrigin attribute (see above). } } } \sstroutine{ StcsLength }{ Controls output line length }{ \sstdescription{ This attribute specifies the maximum length to use when writing out text through the sink function supplied when the \htmlref{StcsChan}{StcsChan} was created. It is ignored if the \htmlref{Indent}{Indent} attribute is zero (in which case the text supplied to the sink function can be of any length). The default value is 70. The number of characters in each string written out through the sink function will not usually be greater than the value of this attribute (but may be less). However, if any single word in the STC-S description exceeds the specified length, then the word will be written out as a single line. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } } \sstroutine{ StcsProps }{ Return all properties when reading an STC-S document? }{ \sstdescription{ This is a boolean attribute which controls what is returned by the \htmlref{astRead}{astRead} function when it is used to read from an \htmlref{StcsChan}{StcsChan}. If StcsProps is set non-zero, then a \htmlref{KeyMap}{KeyMap} containing all the properties read from the STC-S document will be returned by astRead. If StcsProps is set to zero (the default), then the properties will not be returned. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ StcsChan }{ All StcsChans have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsArea}{StcsArea} can be used to specify other Objects to be returned by astRead. If more than one of these attributes is set non-zero, then the actual \htmlref{Object}{Object} returned by astRead will be a KeyMap containing the requested Objects. In this case, the properties KeyMap will be stored in the returned KeyMap using the key \texttt{"} PROPS\texttt{"} . If StcsProps is the only attribute to be set non-zero, then the Object returned by astRead will be the properties KeyMap itself. \sstitem The KeyMap containing the properties will have entries for one or more of the following keys: \texttt{"} TIME\_PROPS\texttt{"} , \texttt{"} SPACE\_PROPS\texttt{"} , \texttt{"} SPECTRAL\_PROPS\texttt{"} and \texttt{"} REDSHIFT\_PROPS\texttt{"} . Each of these entries will be another KeyMap containing the properties of the corresponding STC-S sub-phrase. } } } \sstroutine{ StdOfRest }{ Standard of rest }{ \sstdescription{ This attribute identifies the standard of rest to which the spectral axis values of a \htmlref{SpecFrame}{SpecFrame} refer, and may take any of the values listed in the \texttt{"} Standards of Rest\texttt{"} section (below). The default StdOfRest value is \texttt{"} Helio\texttt{"} . } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ SpecFrame }{ All SpecFrames have this attribute. } } \sstdiytopic{ Standards of Rest }{ The SpecFrame class supports the following StdOfRest values (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} Topocentric\texttt{"} , \texttt{"} Topocent\texttt{"} or \texttt{"} Topo\texttt{"} : The observers rest-frame (assumed to be on the surface of the earth). Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a day because of the rotation of the observer around the axis of the earth. This standard of rest must be qualified using the \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes. \sstitem \texttt{"} Geocentric\texttt{"} , \texttt{"} Geocentr\texttt{"} or \texttt{"} Geo\texttt{"} : The rest-frame of the earth centre. Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a year because of the rotation of the earth around the Sun. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes. \sstitem \texttt{"} Barycentric\texttt{"} , \texttt{"} Barycent\texttt{"} or \texttt{"} Bary\texttt{"} : The rest-frame of the solar-system barycentre. Spectra recorded in this standard of rest suffer a Doppler shift which depends both on the velocity of the Sun through the Local Standard of Rest, and on the movement of the planets through the solar system. This standard of rest must be qualified using the Epoch, RefRA and RefDec attributes. \sstitem \texttt{"} Heliocentric\texttt{"} , \texttt{"} Heliocen\texttt{"} or \texttt{"} Helio\texttt{"} : The rest-frame of the Sun. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the Sun through the Local Standard of Rest. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} LSRK\texttt{"} , \texttt{"} LSR\texttt{"} : The rest-frame of the kinematical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the kinematical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} LSRD\texttt{"} : The rest-frame of the dynamical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the dynamical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Galactic\texttt{"} , \texttt{"} Galactoc\texttt{"} or \texttt{"} Gal\texttt{"} : The rest-frame of the galactic centre. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the galactic centre through the local group. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Local\_group\texttt{"} , \texttt{"} Localgrp\texttt{"} or \texttt{"} LG\texttt{"} : The rest-frame of the local group. This standard of rest must be qualified using the RefRA and RefDec attributes. \sstitem \texttt{"} Source\texttt{"} , or \texttt{"} src\texttt{"} : The rest-frame of the source. This standard of rest must be qualified using the RefRA, RefDec and \htmlref{SourceVel}{SourceVel} attributes. } Where more than one alternative \htmlref{System}{System} value is shown above, the first of these will be returned when an enquiry is made. } } \sstroutine{ Strict }{ Report an error if any unexpeted data items are found? }{ \sstdescription{ This is a boolean attribute which indicates whether a warning rather than an error should be issed for insignificant conversion problems. If it is set non-zero, then fatal errors are issued instead of warnings, resulting in the AST error status being set. If Strict is zero (the default), then execution continues after minor conversion problems, and a warning message is added to the \htmlref{Channel}{Channel} structure. Such messages can be retrieved using the \htmlref{astWarnings}{astWarnings} function. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Channel }{ All Channels have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem This attribute was introduced in AST version 5.0. Prior to this version of AST unexpected data items read by a basic Channel always caused an error to be reported. So applications linked against versions of AST prior to version 5.0 may not be able to read \htmlref{Object}{Object} descriptions created by later versions of AST, if the Object\texttt{'} s class description has changed. } } } \sstroutine{ Style(element) }{ Line style for a Plot element }{ \sstdescription{ This attribute determines the line style used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Style(border)=2\texttt{"} causes the Plot border to be drawn using line style 2 (which might result in, say, a dashed line). The range of integer line styles available and their appearance is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line style supplied by this graphics system (normally, this is likely to give a solid line). } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Style\texttt{"} instead of \texttt{"} Style(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Style(\htmlref{Border}{Border}) value. } } } \sstroutine{ Symbol(axis) }{ Axis symbol }{ \sstdescription{ This attribute specifies a short-form symbol to be used to represent coordinate values for a particular axis of a \htmlref{Frame}{Frame}. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include \texttt{"} RA\texttt{"} and \texttt{"} Dec\texttt{"} (for Right Ascension and Declination). If a Symbol value has not been set for a Frame axis, then a suitable default is supplied. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default Symbol value supplied by the Frame class is the string \texttt{"} $<$\htmlref{Domain}{Domain}$>$$<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for successive axes, and $<$Domain$>$ is the value of the Frame\texttt{'} s Domain attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, \texttt{"} x\texttt{"} is used as the $<$Domain$>$ value in constructing this default string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Symbol value (e.g. to \texttt{"} RA\texttt{"} or \texttt{"} Dec\texttt{"} ) as appropriate for the particular celestial coordinate system being represented. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Symbol value as appropriate for the particular time system being represented. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Symbol attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ System }{ Coordinate system used to describe positions within the domain }{ \sstdescription{ In general it is possible for positions within a given physical domain to be described using one of several different coordinate systems. For instance, the \htmlref{SkyFrame}{SkyFrame} class can use galactic coordinates, equatorial coordinates, etc, to describe positions on the sky. As another example, the \htmlref{SpecFrame}{SpecFrame} class can use frequency, wavelength, velocity, etc, to describe a position within an electromagnetic spectrum. The System attribute identifies the particular coordinate system represented by a \htmlref{Frame}{Frame}. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System value is shown, the first of will be returned when an enquiry is made. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The System attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , and may not be altered. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The System attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , and may not be altered. In addition, the CmpFrame class allows the System attribute to be referenced for a component Frame by including the index of an axis within the required component Frame. For instance, \texttt{"} System(3)\texttt{"} refers to the System attribute of the component Frame which includes axis 3 of the CmpFrame. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The System attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } \sstsubsection{ SkyFrame }{ The SkyFrame class supports the following System values and associated celestial coordinate systems: \sstitemlist{ \sstitem \texttt{"} AZEL\texttt{"} : Horizon coordinates. The longitude axis is azimuth such that geographic north has an azimuth of zero and geographic east has an azimuth of $+$PI/2 radians. The zenith has elevation $+$PI/2. When converting to and from other celestial coordinate systems, no corrections are applied for atmospheric refraction or polar motion (however, a correction for diurnal aberattion is applied). Note, unlike most other celestial coordinate systems, this system is right handed. Also, unlike other SkyFrame systems, the AzEl system is sensitive to the timescale in which the \htmlref{Epoch}{Epoch} value is supplied. This is because of the gross diurnal rotation which this system undergoes, causing a small change in time to translate to a large rotation. When converting to or from an AzEl system, the Epoch value for both source and destination SkyFrames should be supplied in the TDB timescale. The difference between TDB and TT is between 1 and 2 milliseconds, and so a TT value can usually be supplied in place of a TDB value. The TT timescale is related to TAI via TT = TAI $+$ 32.184 seconds. \sstitem \texttt{"} ECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox specified by the qualifying \htmlref{Equinox}{Equinox} value. \sstitem \texttt{"} FK4\texttt{"} : The old FK4 (barycentric) equatorial coordinate system, which should be qualified by an Equinox value. The underlying model on which this is based is non-inertial and rotates slowly with time, so for accurate work FK4 coordinate systems should also be qualified by an Epoch value. \sstitem \texttt{"} FK4-NO-E\texttt{"} or \texttt{"} FK4\_NO\_E\texttt{"} : The old FK4 (barycentric) equatorial system but without the \texttt{"} E-terms of aberration\texttt{"} (e.g. some radio catalogues). This coordinate system should also be qualified by both an Equinox and an Epoch value. \sstitem \texttt{"} FK5\texttt{"} or \texttt{"} EQUATORIAL\texttt{"} : The modern FK5 (barycentric) equatorial coordinate system. This should be qualified by an Equinox value. \sstitem \texttt{"} GALACTIC\texttt{"} : Galactic coordinates (IAU 1958). \sstitem \texttt{"} GAPPT\texttt{"} , \texttt{"} GEOCENTRIC\texttt{"} or \texttt{"} APPARENT\texttt{"} : The geocentric apparent equatorial coordinate system, which gives the apparent positions of sources relative to the true plane of the Earth\texttt{'} s equator and the equinox (the coordinate origin) at a time specified by the qualifying Epoch value. (Note that no Equinox is needed to qualify this coordinate system because no model \texttt{"} mean equinox\texttt{"} is involved.) These coordinates give the apparent right ascension and declination of a source for a specified date of observation, and therefore form an approximate basis for pointing a telescope. Note, however, that they are applicable to a fictitious observer at the Earth\texttt{'} s centre, and therefore ignore such effects as atmospheric refraction and the (normally much smaller) aberration of light due to the rotational velocity of the Earth\texttt{'} s surface. Geocentric apparent coordinates are derived from the standard FK5 (J2000.0) barycentric coordinates by taking account of the gravitational deflection of light by the Sun (usually small), the aberration of light caused by the motion of the Earth\texttt{'} s centre with respect to the barycentre (larger), and the precession and nutation of the Earth\texttt{'} s spin axis (normally larger still). \sstitem \texttt{"} HELIOECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the ecliptic and mean equinox of J2000.0, in which an offset is added to the longitude value which results in the centre of the sun being at zero longitude at the date given by the Epoch attribute. Attempts to set a value for the Equinox attribute will be ignored, since this system is always referred to J2000.0. \sstitem \texttt{"} ICRS\texttt{"} : The Internation Celestial Reference System, realised through the Hipparcos catalogue. Whilst not an equatorial system by definition, the ICRS is very close to the FK5 (J2000) system and is usually treated as an equatorial system. The distinction between ICRS and FK5 (J2000) only becomes important when accuracies of 50 milli-arcseconds or better are required. ICRS need not be qualified by an Equinox value. \sstitem \texttt{"} J2000\texttt{"} : An equatorial coordinate system based on the mean dynamical equator and equinox of the J2000 epoch. The dynamical equator and equinox differ slightly from those used by the FK5 model, and so a \texttt{"} J2000\texttt{"} SkyFrame will differ slightly from an \texttt{"} FK5(Equinox=J2000)\texttt{"} SkyFrame. The J2000 System need not be qualified by an Equinox value \sstitem \texttt{"} SUPERGALACTIC\texttt{"} : De Vaucouleurs Supergalactic coordinates. \sstitem \texttt{"} UNKNOWN\texttt{"} : Any other general spherical coordinate system. No \htmlref{Mapping}{Mapping} can be created between a pair of SkyFrames if either of the SkyFrames has System set to \texttt{"} Unknown\texttt{"} . } Currently, the default System value is \texttt{"} ICRS\texttt{"} . However, this default may change in future as new astrometric standards evolve. The intention is to track the most modern appropriate standard. For this reason, you should use the default only if this is what you intend (and can tolerate any associated slight change in future). If you intend to use the ICRS system indefinitely, then you should specify it explicitly. } \sstsubsection{ SpecFrame }{ The SpecFrame class supports the following System values and associated spectral coordinate systems (the default is \texttt{"} WAVE\texttt{"} - wavelength). They are all defined in FITS-WCS paper III: \sstitemlist{ \sstitem \texttt{"} FREQ\texttt{"} : Frequency (GHz) \sstitem \texttt{"} ENER\texttt{"} or \texttt{"} ENERGY\texttt{"} : Energy (J) \sstitem \texttt{"} WAVN\texttt{"} or \texttt{"} WAVENUM\texttt{"} : Wave-number (1/m) \sstitem \texttt{"} WAVE\texttt{"} or \texttt{"} WAVELEN\texttt{"} : Vacuum wave-length (Angstrom) \sstitem \texttt{"} AWAV\texttt{"} or \texttt{"} AIRWAVE\texttt{"} : Wave-length in air (Angstrom) \sstitem \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) \sstitem \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) \sstitem \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) \sstitem \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) \sstitem \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) } The default value for the Unit attribute for each system is shown in parentheses. Note that the default value for the ActiveUnit flag is non-zero for a SpecFrame, meaning that changes to the Unit attribute for a SpecFrame will result in the SpecFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see \htmlref{astSetActiveUnit}{astSetActiveUnit} function for further information). } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class supports the following System values and associated coordinate systems (the default is \texttt{"} MJD\texttt{"} ): \sstitemlist{ \sstitem \texttt{"} MJD\texttt{"} : Modified Julian Date (d) \sstitem \texttt{"} JD\texttt{"} : Julian Date (d) \sstitem \texttt{"} JEPOCH\texttt{"} : Julian epoch (yr) \sstitem \texttt{"} BEPOCH\texttt{"} : Besselian (yr) } The default value for the Unit attribute for each system is shown in parentheses. Strictly, these systems should not allow changes to be made to the units. For instance, the usual definition of \texttt{"} MJD\texttt{"} and \texttt{"} JD\texttt{"} include the statement that the values will be in units of days. However, AST does allow the use of other units with all the above supported systems (except BEPOCH), on the understanding that conversion to the \texttt{"} correct\texttt{"} units involves nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined in terms of tropical years of 365.2422 days, rather than the usual Julian year of 365.25 days. Therefore, to avoid any confusion, the Unit attribute is automatically cleared to \texttt{"} yr\texttt{"} when a System value of BEPOCH System is selected, and an error is reported if any attempt is subsequently made to change the Unit attribute. Note that the default value for the ActiveUnit flag is non-zero for a TimeFrame, meaning that changes to the Unit attribute for a TimeFrame will result in the TimeFrame being re-mapped within its enclosing FrameSet in order to reflect the change in units (see astSetActiveUnit function for further information). } \sstsubsection{ \htmlref{FluxFrame}{FluxFrame} }{ The FluxFrame class supports the following System values and associated systems for measuring observed value: \sstitemlist{ \sstitem \texttt{"} FLXDN\texttt{"} : Flux per unit frequency (W/m$\wedge$2/Hz) \sstitem \texttt{"} FLXDNW\texttt{"} : Flux per unit wavelength (W/m$\wedge$2/Angstrom) \sstitem \texttt{"} SFCBR\texttt{"} : Surface brightness in frequency units (W/m$\wedge$2/Hz/arcmin$*$$*$2) \sstitem \texttt{"} SFCBRW\texttt{"} : Surface brightness in wavelength units (W/m$\wedge$2/Angstrom/arcmin$*$$*$2) } The above lists specified the default units for each System. If an explicit value is set for the Unit attribute but no value is set for System, then the default System value is determined by the Unit string (if the units are not appropriate for describing any of the supported Systems then an error will be reported when an attempt is made to access the System value). If no value has been specified for either Unit or System, then System=FLXDN and Unit=W/m$\wedge$2/Hz are used. } } } \sstroutine{ TabOK }{ Should the FITS-WCS -TAB algorithm be recognised? }{ \sstdescription{ This attribute is an integer value which indicates if the \texttt{"} -TAB\texttt{"} algorithm, defined in FITS-WCS paper III, should be supported by the \htmlref{FitsChan}{FitsChan}. The default value is zero. A zero or negative value results in no support for -TAB axes (i.e. axes that have \texttt{"} -TAB\texttt{"} in their CTYPE keyword value). In this case, the \htmlref{astWrite}{astWrite} method will return zero if the write operation would required the use of the -TAB algorithm, and the \htmlref{astRead}{astRead} method will return a NULL pointer if any axis in the supplied header uses the -TAB algorithm. If TabOK is set to a non-zero positive integer, these methods will recognise and convert axes described by the -TAB algorithm, as follows: The astWrite method will generate headers that use the -TAB algorithm (if possible) if no other known FITS-WCS algorithm can be used to describe the supplied \htmlref{FrameSet}{FrameSet}. This will result in a table of coordinate values and index vectors being stored in the FitsChan. After the write operation, the calling application should check to see if such a table has been stored in the FitsChan. If so, the table should be retrived from the FitsChan using the \htmlref{astGetTables}{astGetTables} method, and the data (and headers) within it copied into a new FITS binary table extension. See astGetTables for more information. The FitsChan uses a \htmlref{FitsTable}{FitsTable} object to store the table data and headers. This FitsTable will contain the required columns and headers as described by FITS-WCS paper III - the coordinates array will be in a column named \texttt{"} COORDS\texttt{"} , and the index vector(s) will be in columns named \texttt{"} INDEX$<$i$>$\texttt{"} (where $<$i$>$ is the index of the corresponding FITS WCS axis). Note, index vectors are only created if required. The EXTNAME value will be set to the value of the AST\_\_TABEXTNAME constant (currently \texttt{"} WCS-TAB\texttt{"} ). The EXTVER header will be set to the positive integer value assigned to the TabOK attribute. No value will be stored for the EXTLEVEL header, and should therefore be considered to default to 1. The astRead method will generate a FrameSet from headers that use the -TAB algorithm so long as the necessary FITS binary tables are made available. There are two ways to do this: firstly, if the application knows which FITS binary tables will be needed, then it can create a Fitstable describing each such table and store it in the FitsChan (using method \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) before invoking the astRead method. Secondly, if the application does not know which FITS binary tables will be needed by astRead, then it can register a call-back function with the FitsChan using method \htmlref{astTableSource}{astTableSource}. This call-back function will be called from within astRead if and when a -TAB header is encountered. When called, its arguments will give the name, version and level of the FITS extension containing a required table. The call-back function should read this table from an external FITS file, and create a corresponding FitsTable which it should then return to astRead. Note, currently astRead can only handle -TAB headers that describe 1-dimensional (i.e. separable) axes. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } } \sstroutine{ TextLab(axis) }{ Draw descriptive axis labels for a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether textual labels should be drawn to describe the quantity being represented on each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each physical axis of a Plot so that, for instance, the setting \texttt{"} TextLab(2)=1\texttt{"} specifies that descriptive labels should be drawn for the second axis. If the TextLab value of a Plot axis is non-zero, then descriptive labels will be drawn for that axis, otherwise they will be omitted. The default behaviour is to draw descriptive labels if tick marks and numerical labels are being drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit them otherwise. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the descriptive labels is derived from the Plot\texttt{'} s \htmlref{Label(axis)}{Label(axis)} attribute, together with its \htmlref{Unit(axis)}{Unit(axis)} attribute if appropriate (see the \htmlref{LabelUnits(axis)}{LabelUnits(axis)} attribute). \sstitem The drawing of numerical axis labels for a Plot (which indicate values on the axis) is controlled by the \htmlref{NumLab(axis)}{NumLab(axis)} attribute. \sstitem If no axis is specified, (e.g. \texttt{"} TextLab\texttt{"} instead of \texttt{"} TextLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the TextLab(1) value. } } } \sstroutine{ TextLabGap(axis) }{ Spacing of descriptive axis labels for a Plot }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining where descriptive axis labels are placed relative to the axes they describe. It takes a separate value for each physical axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} TextLabGap(2)=0.01\texttt{"} specifies where the descriptive label for the second axis should be drawn. For each axis, the TextLabGap value gives the spacing between the descriptive label and the edge of a box enclosing all other parts of the annotated grid (excluding other descriptive labels). The gap is measured to the nearest edge of the label (i.e. the top or the bottom). Positive values cause the descriptive label to be placed outside the bounding box, while negative values cause it to be placed inside. The TextLabGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.01. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem If drawn, descriptive labels are always placed at the edges of the plotting area, even although the corresponding numerical labels may be drawn along axis lines in the interior of the plotting area (see the \htmlref{Labelling}{Labelling} attribute). \sstitem If no axis is specified, (e.g. \texttt{"} TextLabGap\texttt{"} instead of \texttt{"} TextLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the TextLabGap(1) value. } } } \sstroutine{ TickAll }{ Draw tick marks on all edges of a Plot? }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining whether tick marks should be drawn on all edges of a \htmlref{Plot}{Plot}. If the TickAll value of a Plot is non-zero (the default), then tick marks will be drawn on all edges of the Plot. Otherwise, they will be drawn only on those edges where the numerical and descriptive axis labels are drawn (see the \htmlref{Edge(axis)}{Edge(axis)} attribute). } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem In some circumstances, numerical labels and tick marks are drawn along grid lines inside the plotting area, rather than around its edges (see the \htmlref{Labelling}{Labelling} attribute). In this case, the value of the TickAll attribute is ignored. } } } \sstroutine{ TimeOrigin }{ The zero point for TimeFrame axis values }{ \sstdescription{ This specifies the origin from which all time values are measured. The default value (zero) results in the \htmlref{TimeFrame}{TimeFrame} describing absolute time values in the system given by the \htmlref{System}{System} attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } \sstdiytopic{ Input Formats }{ The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters: \sstitemlist{ \sstitem Besselian \htmlref{Epoch}{Epoch}: Expressed in decimal years, with or without decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). \sstitem Julian Epoch: Expressed in decimal years, with or without decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). \sstitem Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame\texttt{'} s System attribute, in the units given by the TimeFrame\texttt{'} s Unit attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value (\texttt{"} 123.4 d\texttt{"} for example), in which case the supplied value is scaled into the units specified by the Unit attribute. \sstitem Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for example). \sstitem Modified Julian Date: With or without decimal places (\texttt{"} MJD 54321.4\texttt{"} for example). \sstitem Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours). \sstitem Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). } } \sstdiytopic{ Output Format }{ When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame\texttt{'} s System, in the unit specified by the TimeFrame\texttt{'} s Unit attribute. } } \sstroutine{ TimeScale }{ Time scale }{ \sstdescription{ This attribute identifies the time scale to which the time axis values of a \htmlref{TimeFrame}{TimeFrame} refer, and may take any of the values listed in the \texttt{"} Time Scales\texttt{"} section (below). The default TimeScale value depends on the current \htmlref{System}{System} value; if the current TimeFrame system is \texttt{"} Besselian epoch\texttt{"} the default is \texttt{"} TT\texttt{"} , otherwise it is \texttt{"} TAI\texttt{"} . Note, if the System attribute is set so that the TimeFrame represents Besselian \htmlref{Epoch}{Epoch}, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT. Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the \htmlref{Dut1}{Dut1} attribute (defined by the parent \htmlref{Frame}{Frame} class). This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute for further details. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ TimeFrame }{ All TimeFrames have this attribute. } } \sstdiytopic{ Time Scales }{ The TimeFrame class supports the following TimeScale values (all are case-insensitive): \sstitemlist{ \sstitem \texttt{"} TAI\texttt{"} - International Atomic Time \sstitem \texttt{"} UTC\texttt{"} - Coordinated Universal Time \sstitem \texttt{"} UT1\texttt{"} - Universal Time \sstitem \texttt{"} GMST\texttt{"} - Greenwich Mean Sidereal Time \sstitem \texttt{"} LAST\texttt{"} - Local Apparent Sidereal Time \sstitem \texttt{"} LMST\texttt{"} - Local Mean Sidereal Time \sstitem \texttt{"} TT\texttt{"} - Terrestrial Time \sstitem \texttt{"} TDB\texttt{"} - Barycentric Dynamical Time \sstitem \texttt{"} TCB\texttt{"} - Barycentric Coordinate Time \sstitem \texttt{"} TCG\texttt{"} - Geocentric Coordinate Time \sstitem \texttt{"} LT\texttt{"} - Local Time (the offset from UTC is given by attribute \htmlref{LTOffset}{LTOffset}) } An very informative description of these and other time scales is available at http://www.ucolick.org/$\sim$sla/leapsecs/timescales.html. } \sstdiytopic{ UTC \htmlref{Warnings}{Warnings} }{ UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won\texttt{'} t matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times. } } \sstroutine{ Title }{ Frame title }{ \sstdescription{ This attribute holds a string which is used as a title in (e.g.) graphical output to describe the coordinate system which a \htmlref{Frame}{Frame} represents. Examples might be \texttt{"} Detector Coordinates\texttt{"} or \texttt{"} Galactic Coordinates\texttt{"} . If a Title value has not been set for a Frame, then a suitable default is supplied, depending on the class of the Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is \texttt{"} $<$n$>$-d coordinate system\texttt{"} , where $<$n$>$ is the number of Frame axes (\htmlref{Naxes}{Naxes} attribute). } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The CmpFrame class re-defines the default Title value to be \texttt{"} $<$n$>$-d compound coordinate system\texttt{"} , where $<$n$>$ is the number of CmpFrame axes (Naxes attribute). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Title attribute of a FrameSet is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem A Frame\texttt{'} s Title is intended purely for interpretation by human readers and not by software. } } } \sstroutine{ TitleGap }{ Vertical spacing for a Plot title }{ \sstdescription{ This attribute controls the appearance of an annotated coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining where the title of a \htmlref{Plot}{Plot} is drawn. Its value gives the spacing between the bottom edge of the title and the top edge of a bounding box containing all the other parts of the annotated grid. Positive values cause the title to be drawn outside the box, while negative values cause it to be drawn inside. The TitleGap value should be given as a fraction of the minimum dimension of the plotting area, the default value being $+$0.05. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } \sstsubsection{ \htmlref{Plot3D}{Plot3D} }{ The Plot3D class ignores this attributes since it does not draw a \htmlref{Title}{Title}. } } \sstnotes{ \sstitemlist{ \sstitem The text used for the title is obtained from the Plot\texttt{'} s Title attribute. } } } \sstroutine{ Tol }{ Plotting tolerance }{ \sstdescription{ This attribute specifies the plotting tolerance (or resolution) to be used for the graphical output produced by a \htmlref{Plot}{Plot}. Smaller values will result in smoother and more accurate curves being drawn, but may slow down the plotting process. Conversely, larger values may speed up the plotting process in cases where high resolution is not required. The Tol value should be given as a fraction of the minimum dimension of the plotting area, and should lie in the range from 1.0e-7 to 1.0. By default, a value of 0.01 is used. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } } \sstroutine{ TolInverse }{ Target relative error for the iterative inverse transformation }{ \sstdescription{ This attribute controls the iterative inverse transformation used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. Its value gives the target relative error in teh axis values of each transformed position. Further iterations will be performed until the target relative error is reached, or the maximum number of iterations given by attribute \htmlref{NiterInverse}{NiterInverse} is reached. The default value is 1.0E-6. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{PolyMap}{PolyMap} }{ All PolyMaps have this attribute. } } } \sstroutine{ Top(axis) }{ Highest axis value to display }{ \sstdescription{ This attribute gives the highest axis value to be displayed (for instance, by the \htmlref{astGrid}{astGrid} method). } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ \htmlref{Frame}{Frame} }{ The default supplied by the Frame class is to display all axis values, without any limit. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Top value to $+$90 degrees for latitude axes, and 180 degrees for co-latitude axes. The default for longitude axes is to display all axis values. } } \sstnotes{ \sstitemlist{ \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ TranForward }{ Forward transformation defined? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform coordinates in the \texttt{"} forward\texttt{"} direction (i.e. converting input coordinates into output coordinates). If this attribute is non-zero, the forward transformation is available. Otherwise, it is not. } \sstattributetype{ Integer (boolean), read-only. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The TranForward attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The TranForward attribute of a FrameSet applies to the transformation which converts between the FrameSet\texttt{'} s base \htmlref{Frame}{Frame} and its current Frame (as specified by the \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes). This value is given by the boolean AND of the TranForward values which apply to each of the individual sub-Mappings required to perform this conversion. The TranForward attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if a Mapping with a TranForward value of zero is used to transform coordinates in the forward direction. } } } \sstroutine{ TranInverse }{ Inverse transformation defined? }{ \sstdescription{ This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform coordinates in the \texttt{"} inverse\texttt{"} direction (i.e. converting output coordinates back into input coordinates). If this attribute is non-zero, the inverse transformation is available. Otherwise, it is not. } \sstattributetype{ Integer (boolean), readonly. } \sstapplicability{ \sstsubsection{ Mapping }{ All Mappings have this attribute. } \sstsubsection{ \htmlref{CmpMap}{CmpMap} }{ The TranInverse attribute value for a CmpMap is given by the boolean AND of the value for each component Mapping. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The TranInverse attribute of a FrameSet applies to the transformation which converts between the FrameSet\texttt{'} s current \htmlref{Frame}{Frame} and its base Frame (as specified by the \htmlref{Current}{Current} and \htmlref{Base}{Base} attributes). This value is given by the boolean AND of the TranInverse values which apply to each of the individual sub-Mappings required to perform this conversion. The TranInverse attribute value for a FrameSet may therefore change if a new Base or Current Frame is selected. } } \sstnotes{ \sstitemlist{ \sstitem An error will result if a Mapping with a TranInverse value of zero is used to transform coordinates in the inverse direction. } } } \sstroutine{ Unit(axis) }{ Physical units for formatted axis values }{ \sstdescription{ This attribute contains a textual representation of the physical units used to represent formatted coordinate values on a particular axis of a \htmlref{Frame}{Frame}. The \htmlref{astSetActiveUnit}{astSetActiveUnit} function controls how the Unit values are used. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Frame }{ The default supplied by the Frame class is an empty string. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ The SkyFrame class re-defines the default Unit value (e.g. to \texttt{"} hh:mm:ss.sss\texttt{"} ) to describe the character string returned by the \htmlref{astFormat}{astFormat} function when formatting coordinate values. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ The SpecFrame class re-defines the default Unit value so that it is appropriate for the current \htmlref{System}{System} value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit. } \sstsubsection{ \htmlref{TimeFrame}{TimeFrame} }{ The TimeFrame class re-defines the default Unit value so that it is appropriate for the current System value. See the System attribute for details. An error will be reported if an attempt is made to use an inappropriate Unit (e.g. \texttt{"} km\texttt{"} ). } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The Unit attribute of a FrameSet axis is the same as that of its current Frame (as specified by the \htmlref{Current}{Current} attribute). } } \sstnotes{ \sstitemlist{ \sstitem This attribute described the units used when an axis value is formatted into a string using astFormat. In some cases these units may be different to those used to represent floating point axis values within application code (for instance a SkyFrame always uses radians to represent floating point axis values). The InternalUnit attribute described the units used for floating point values. \sstitem When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies. } } } \sstroutine{ UnitRadius }{ SphMap input vectors lie on a unit sphere? }{ \sstdescription{ This is a boolean attribute which indicates whether the 3-dimensional vectors which are supplied as input to a \htmlref{SphMap}{SphMap} are known to always have unit length, so that they lie on a unit sphere centred on the origin. If this condition is true (indicated by setting UnitRadius non-zero), it implies that a \htmlref{CmpMap}{CmpMap} which is composed of a SphMap applied in the forward direction followed by a similar SphMap applied in the inverse direction may be simplified (e.g. by \htmlref{astSimplify}{astSimplify}) to become a \htmlref{UnitMap}{UnitMap}. This is because the input and output vectors will both have unit length and will therefore have the same coordinate values. If UnitRadius is zero (the default), then although the output vector produced by the CmpMap (above) will still have unit length, the input vector may not have. This will, in general, change the coordinate values, so it prevents the pair of SphMaps being simplified. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ SphMap }{ All SphMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem This attribute is intended mainly for use when SphMaps are involved in a sequence of Mappings which project (e.g.) a dataset on to the celestial sphere. By regarding the celestial sphere as a unit sphere (and setting UnitRadius to be non-zero) it becomes possible to cancel the SphMaps present, along with associated sky projections, when two datasets are aligned using celestial coordinates. This often considerably improves performance. \sstitem Such a situations often arises when interpreting FITS data and is handled automatically by the \htmlref{FitsChan}{FitsChan} class. \sstitem The value of the UnitRadius attribute is used only to control the simplification of Mappings and has no effect on the value of the coordinates transformed by a SphMap. The lengths of the input 3-dimensional Cartesian vectors supplied are always ignored, even if UnitRadius is non-zero. \sstitem The value of this attribute may changed only if the SphMap has no more than one reference. That is, an error is reported if the SphMap has been cloned, either by including it within another object such as a CmpMap or \htmlref{FrameSet}{FrameSet} or by calling the \htmlref{astClone}{astClone} function. } } } \sstroutine{ UseDefs }{ Use default values for unspecified attributes? }{ \sstdescription{ This attribute specifies whether default values should be used internally for object attributes which have not been assigned a value explicitly. If a non-zero value (the default) is supplied for UseDefs, then default values will be used for attributes which have not explicitly been assigned a value. If zero is supplied for UseDefs, then an error will be reported if an attribute for which no explicit value has been supplied is needed internally within AST. Many attributes (including the UseDefs attribute itself) are unaffected by the setting of the UseDefs attribute, and default values will always be used without error for such attributes. The \texttt{"} Applicability:\texttt{"} section below lists the attributes which are affected by the setting of UseDefs. Note, UseDefs only affects access to attributes internally within AST. The public accessor functions such as astGetC is unaffected by the UseDefs attribute - default values will always be returned if no value has been set. Application code should use the \htmlref{astTest}{astTest} function if required to determine if a value has been set for an attribute. } \sstattributetype{ Integer (boolean). } \sstapplicability{ \sstsubsection{ \htmlref{Object}{Object} }{ All Objects have this attribute, but ignore its setting except as described below for individual classes. } \sstsubsection{ \htmlref{FrameSet}{FrameSet} }{ The default value of UseDefs for a FrameSet is redefined to be the UseDefs value of its current \htmlref{Frame}{Frame}. } \sstsubsection{ \htmlref{CmpFrame}{CmpFrame} }{ The default value of UseDefs for a CmpFrame is redefined to be the UseDefs value of its first component Frame. } \sstsubsection{ \htmlref{Region}{Region} }{ The default value of UseDefs for a Region is redefined to be the UseDefs value of its encapsulated Frame. } \sstsubsection{ Frame }{ If UseDefs is zero, an error is reported when aligning Frames if the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat} or \htmlref{ObsLon}{ObsLon} attribute is required but has not been assigned a value explicitly. } \sstsubsection{ \htmlref{SkyFrame}{SkyFrame} }{ If UseDefs is zero, an error is reported when aligning SkyFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{Equinox}{Equinox}. } \sstsubsection{ \htmlref{SpecFrame}{SpecFrame} }{ If UseDefs is zero, an error is reported when aligning SpecFrames if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec}, \htmlref{RestFreq}{RestFreq}, \htmlref{SourceVel}{SourceVel}, \htmlref{StdOfRest}{StdOfRest}. } \sstsubsection{ \htmlref{DSBSpecFrame}{DSBSpecFrame} }{ If UseDefs is zero, an error is reported when aligning DSBSpecFrames or when accessing the \htmlref{ImagFreq}{ImagFreq} attribute if any of the following attributes are required but have not been assigned a value explicitly: Epoch, \htmlref{DSBCentre}{DSBCentre}, \htmlref{IF}{IF}. } } } \sstroutine{ Variant }{ Indicates which variant of the current Frame is to be used }{ \sstdescription{ This attribute can be used to change the \htmlref{Mapping}{Mapping} that connects the current \htmlref{Frame}{Frame} to the other Frames in the \htmlref{FrameSet}{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 \htmlref{astRemapFrame}{astRemapFrame} method. However, it is also possible to associate multiple Mappings with a Frame, each Mapping having an identifying name. If this is done, the \texttt{"} Variant\texttt{"} 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 \htmlref{Domain}{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 \texttt{"} SKY\texttt{"} . That is, instead of searching for Frames that have a class of \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , such software searches for Frames that have a Domain of \texttt{"} SKY\texttt{"} . 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 \texttt{"} Variant\texttt{"} 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 \htmlref{astAddFrame}{astAddFrame} method. By default, the Mapping supplied to astAddFrame is assigned a name equal to the Domain name of the Frame. To assign a different name to it, the \htmlref{astAddVariant}{astAddVariant} method should then be called specifying the required name and a NULL Mapping. The astAddVariant 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 \htmlref{astMirrorVariants}{astMirrorVariants} function 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 \texttt{"} Variant\texttt{"} 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 \texttt{"} Variant\texttt{"} 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 \texttt{"} Variant\texttt{"} attribute will have the effect of removing all variant Mappings (except for the currently selected Mapping) from the current Frame. Testing the \texttt{"} Variant\texttt{"} attribute will return a non-zero value if the current Frame contains any variant Mappings, and zero otherwise. A complete list of the names associated with all the available variant Mappings in the current Frame can be obtained from the \htmlref{AllVariants}{AllVariants} attribute. If a Frame with variant Mappings is remapped using the astRemapFrame method, the currently selected variant Mapping is used by astRemapFrame and the other variant Mappings are removed from the Frame. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ FrameSet }{ All FrameSets have this attribute. } } } \sstroutine{ Warnings }{ Controls the issuing of warnings about various conditions }{ \sstdescription{ This attribute controls the issuing of warnings about selected conditions when an \htmlref{Object}{Object} or keyword is read from or written to a \htmlref{FitsChan}{FitsChan}. The value supplied for the Warnings attribute should consist of a space separated list of condition names (see the \htmlref{AllWarnings}{AllWarnings} attribute for a list of the currently defined names). Each name indicates a condition which should be reported. The default value for Warnings is the string \texttt{"} BadKeyName BadKeyValue Tnx Zpx BadCel BadMat BadPV BadCTYPE\texttt{"} . The text of any warning will be stored within the FitsChan in the form of one or more new header cards with keyword ASTWARN. If required, applications can check the FitsChan for ASTWARN cards (using \htmlref{astFindFits}{astFindFits}) after the call to \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} has been performed, and report the text of any such cards to the user. ASTWARN cards will be propagated to any output header unless they are deleted from the FitsChan using \htmlref{astDelFits}{astDelFits}. } \sstattributetype{ String } \sstapplicability{ \sstsubsection{ FitsChan }{ All FitsChans have this attribute. } } \sstnotes{ This attribute only controls the warnings that are to be stored as a set of header cards in the FitsChan as described above. It has no effect on the storage of warnings in the parent \htmlref{Channel}{Channel} structure. All warnings are stored in the parent Channel structure, from where they can be retrieved using the \htmlref{astWarnings}{astWarnings} function. } } \sstroutine{ WcsAxis(lonlat) }{ FITS-WCS projection axes }{ \sstdescription{ This attribute gives the indices of the longitude and latitude coordinates of the FITS-WCS projection within the coordinate space used by a \htmlref{WcsMap}{WcsMap}. These indices are defined when the WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be altered. If \texttt{"} lonlat\texttt{"} is 1, the index of the longitude axis is returned. Otherwise, if it is 2, the index of the latitude axis is returned. } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } } \sstroutine{ WcsType }{ FITS-WCS projection type }{ \sstdescription{ This attribute specifies which type of FITS-WCS projection will be performed by a \htmlref{WcsMap}{WcsMap}. The value is specified when a WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be changed. The values used are represented by macros with names of the form \texttt{"} AST\_\_XXX\texttt{"} , where \texttt{"} XXX\texttt{"} is the (upper case) 3-character code used by the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword to identify the projection. For example, possible values are AST\_\_TAN (for the tangent plane or gnomonic projection) and AST\_\_AIT (for the Hammer-Aitoff projection). AST\_\_TPN is an exception in that it is not part of the FITS-WCS standard (it represents a TAN projection with polynomial correction terms as defined in an early draft of the FITS-WCS paper). } \sstattributetype{ Integer, read-only. } \sstapplicability{ \sstsubsection{ WcsMap }{ All WcsMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of available projections, see the FITS-WCS paper. } } } \sstroutine{ Width(element) }{ Line width for a Plot element }{ \sstdescription{ This attribute determines the line width used when drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a separate value for each graphical element so that, for instance, the setting \texttt{"} Width(border)=2.0\texttt{"} causes the Plot border to be drawn using a line width of 2.0. A value of 1.0 results in a line thickness which is approximately 0.0005 times the length of the diagonal of the entire display surface. The actual appearance of lines drawn with any particular width, and the range of available widths, is determined by the underlying graphics system. The default behaviour is for all graphical elements to be drawn using the default line width supplied by this graphics system. This will not necessarily correspond to a Width value of 1.0. } \sstattributetype{ Floating point. } \sstapplicability{ \sstsubsection{ Plot }{ All Plots have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem For a list of the graphical elements available, see the description of the Plot class. \sstitem If no graphical element is specified, (e.g. \texttt{"} Width\texttt{"} instead of \texttt{"} Width(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Width(\htmlref{Border}{Border}) value. } } } \sstroutine{ XmlFormat }{ System for formatting Objects as XML }{ \sstdescription{ This attribute specifies the formatting system to use when AST Objects are written out as XML through an \htmlref{XmlChan}{XmlChan}. It affects the behaviour of the \htmlref{astWrite}{astWrite} function when they are used to transfer any AST \htmlref{Object}{Object} to or from an external XML representation. The XmlChan class allows AST objects to be represented in the form of XML in several ways (conventions) and the XmlFormat attribute is used to specify which of these should be used. The formatting options available are outlined in the \texttt{"} Formats Available\texttt{"} section below. By default, an XmlChan will attempt to determine which format system is already in use, and will set the default XmlFormat value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical items which only occur in particular formats. For details of how this works, see the \texttt{"} Choice of Default Format\texttt{"} section below. If you wish to ensure that a particular format system is used, independently of any XML already read, you should set an explicit XmlFormat value yourself. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ XmlChan }{ All XmlChans have this attribute. } } \sstdiytopic{ Formats Available }{ The XmlFormat attribute can take any of the following (case insensitive) string values to select the corresponding formatting system: \sstitemlist{ \sstitem \texttt{"} NATIVE\texttt{"} : This is a direct conversion to XML of the heirarchical format used by a standard XML channel (and also by the NATIVE encoding of a \htmlref{FitsChan}{FitsChan}). \sstitem \texttt{"} QUOTED\texttt{"} : This is the same as NATIVE format except that extra information is included which allows client code to convert the XML into a form which can be read by a standard AST \htmlref{Channel}{Channel}. This extra information indicates which AST attribute values should be enclosed in quotes before being passed to a Channel. \sstitem \texttt{"} IVOA\texttt{"} : This is a format that uses an early draft of the STC-X schema developed by the International Virtual Observatory Alliance (IVOA - see \texttt{"} http://www.ivoa.net/\texttt{"} ) to describe coordinate systems, regions, mappings, etc. Support is limited to V1.20 described at \texttt{"} http://www.ivoa.net/Documents/WD/STC/STC-20050225.html\texttt{"} . Since the version of STC-X finally adopted by the IVOA differs in several significant respects from V1.20, this format is now mainly of historical interest. Note, the alternative \texttt{"} STC-S\texttt{"} format (a simpler non-XML encoding of the STC metadata) is supported by the \htmlref{StcsChan}{StcsChan} class. } } \sstdiytopic{ Choice of Default Format; }{ If the XmlFormat attribute of an XmlChan is not set, the default value it takes is determined by the presence of certain critical items within the document most recently read using \htmlref{astRead}{astRead}. The sequence of decision used to arrive at the default value is as follows: \sstitemlist{ \sstitem If the previous document read contained any elements in any of the STC namespaces (\texttt{"} urn:nvo-stc\texttt{"} , \texttt{"} urn:nvo-coords\texttt{"} or \texttt{"} urn:nvo-region\texttt{"} ), then the default value is IVOA. \sstitem If the previous document read contained any elements in the AST namespace which had an associated XML attribute called \texttt{"} quoted\texttt{"} , then the default value is QUOTED. \sstitem Otherwise, if none of these conditions is met (as would be the case if no document had yet been read), then NATIVE format is used. } Setting an explicit value for the XmlFormat attribute always over-rides this default behaviour. } \sstdiytopic{ The IVOA Format }{ The IVOA support caters only for certain parts of V1.20 of the draft Space-Time Coordinate (STC) schema (see http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this draft has now been superceded by an officially adopted version that differs in several significant respects from V1.20. Consequently, the \texttt{"} IVOA\texttt{"} XmlChan format is of historical interest only. The following points should be noted when using an XmlChan to read or write STC information (note, this list is currently incomplete): \sstitemlist{ \sstitem Objects can currently only be read using this format, not written. \sstitem The AST object generated by reading an $<$STCMetadata$>$ element will be an instance of one of the AST \texttt{"} \htmlref{Stc}{Stc}\texttt{"} classes: \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcObsDataLocation}{StcObsDataLocation}. \sstitem When reading an $<$STCMetadata$>$ element, the axes in the returned AST Object will be in the order space, time, spectral, redshift, irrespective of the order in which the axes occur in the $<$STCMetadata$>$ element. If the supplied $<$STCMetadata$>$ element does not contain all of these axes, the returned AST Object will also omit them, but the ordering of those axes which are present will be as stated above. If the spatial frame represents a celestial coordinate system the spatial axes will be in the order (longitude, latitude). \sstitem Until such time as the AST \htmlref{TimeFrame}{TimeFrame} is complete, a simple 1-dimensional \htmlref{Frame}{Frame} (with \htmlref{Domain}{Domain} set to TIME) will be used to represent the STC $<$TimeFrame$>$ element. Consequently, most of the information within a $<$TimeFrame$>$ element is currently ignored. \sstitem $<$SpaceFrame$>$ elements can only be read if they describe a celestial longitude and latitude axes supported by the AST \htmlref{SkyFrame}{SkyFrame} class. The space axes will be returned in the order (longitude, latitude). \sstitem Velocities associated with SpaceFrames cannot be read. \sstitem Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element are currently ignored. \sstitem Any second or subsequent $<$AstroCoordSystem$>$ found within an STCMetaData element is ignored. \sstitem Any second or subsequent $<$AstroCoordArea$>$ found within an STCMetaData element is ignored. \sstitem Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored. \sstitem Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored. \sstitem $<$SpaceFrame$>$ elements can only be read if they refer to one of the following space reference frames: ICRS, GALACTIC\_II, SUPER\_GALACTIC, HEE, FK4, FK5, ECLIPTIC. \sstitem $<$SpaceFrame$>$ elements can only be read if the reference position is TOPOCENTER. Also, any planetary ephemeris is ignored. \sstitem Regions: there is currently no support for STC regions of type Sector, ConvexHull or SkyIndex. \sstitem The AST \htmlref{Region}{Region} read from a CoordInterval element is considered to be open if either the lo\_include or the hi\_include attribute is set to false. \sstitem $<$RegionFile$>$ elements are not supported. \sstitem Vertices within $<$\htmlref{Polygon}{Polygon}$>$ elements are always considered to be joined using great circles (that is, $<$SmallCircle$>$ elements are ignored). } } } \sstroutine{ XmlLength }{ Controls output buffer length }{ \sstdescription{ This attribute specifies the maximum length to use when writing out text through the sink function supplied when the \htmlref{XmlChan}{XmlChan} was created. The number of characters in each string written out through the sink function will not be greater than the value of this attribute (but may be less). A value of zero (the default) means there is no limit - each string can be of any length. } \sstattributetype{ Integer. } \sstapplicability{ \sstsubsection{ XmlChan }{ All XmlChans have this attribute. } } } \sstroutine{ XmlPrefix }{ The namespace prefix to use when writing }{ \sstdescription{ This attribute is a string which is to be used as the namespace prefix for all XML elements created as a result of writing an AST \htmlref{Object}{Object} out through an \htmlref{XmlChan}{XmlChan}. The URI associated with the namespace prefix is given by the symbolic constant AST\_\_XMLNS defined in ast.h. A definition of the namespace prefix is included in each top-level element produced by the XmlChan. The default value is a blank string which causes no prefix to be used. In this case each top-level element will set the default namespace to be the value of AST\_\_XMLNS. } \sstattributetype{ String. } \sstapplicability{ \sstsubsection{ Object }{ All Objects have this attribute. } } } \sstroutine{ Zoom }{ ZoomMap scale factor }{ \sstdescription{ This attribute holds the \htmlref{ZoomMap}{ZoomMap} scale factor, by which coordinate values are multiplied (by the forward transformation) or divided (by the inverse transformation). The default value is unity. Note that if a ZoomMap is inverted (e.g. by using \htmlref{astInvert}{astInvert}), then the reciprocal of this zoom factor will, in effect, be used. In general, \htmlref{Mapping}{Mapping} attributes cannot be changed after the Mapping has been created (the exception to this is the \htmlref{Invert}{Invert} attribute, which can be changed at any time). However, several of the oldest Mapping classes - including the ZoomMap class - were introduced into the AST library before this restriction was enforced. To reduce the chances of breaking existing software, the attributes of such Mappings may still be changed, but only for Mapping instances that have exactly one active reference. In other words, an error will be reported if an attempt is made to set or clear an attribute of a Mapping (other than the Invert attribute) if that Mapping has been cloned. Mappings are cloned when they are incorporated into another object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet}, or when the \htmlref{astClone}{astClone} function is used. } \sstattributetype{ Double precision. } \sstapplicability{ \sstsubsection{ ZoomMap }{ All ZoomMaps have this attribute. } } \sstnotes{ \sstitemlist{ \sstitem The Zoom attribute may not be set to zero. } } } \normalsize \cleardoublepage \section{\label{ss:classdescriptions}AST Class Descriptions} \small \sstroutine{ Axis }{ Store axis information }{ \sstdescription{ The Axis class is used to store information associated with a particular axis of a \htmlref{Frame}{Frame}. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from \htmlref{astWrite}{astWrite}). } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Axis class inherits from the \htmlref{Object}{Object} class. } } \sstroutine{ Box }{ A box region with sides parallel to the axes of a Frame }{ \sstdescription{ The Box class implements a \htmlref{Region}{Region} which represents a box with sides parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the only real difference being that the Interval class allows some axis limits to be unspecified. Note, a Box will only look like a box if the Frame geometry is approximately flat. For instance, a Box centred close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a pole). } \sstconstructor{ \htmlref{astBox}{astBox} } \sstdiytopic{ Inheritance }{ The Box class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Box class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Box class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ Channel }{ Basic (textual) I/O channel }{ \sstdescription{ The Channel class implements low-level input/output for the AST library. Writing an \htmlref{Object}{Object} to a Channel will generate a textual representation of that Object, and reading from a Channel will create a new Object from its textual representation. Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output. Alternatively, a Channel can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstconstructor{ \htmlref{astChannel}{astChannel} } \sstdiytopic{ Inheritance }{ The Channel class inherits from the Object class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every Channel also has the following attributes: \sstitemlist{ \sstitem \htmlref{Comment}{Comment}: Include textual comments in output? \sstitem \htmlref{Full}{Full}: Set level of output detail \sstitem \htmlref{Indent}{Indent}: Indentation increment between objects \sstitem \htmlref{ReportLevel}{ReportLevel}: Selects the level of error reporting \sstitem \htmlref{SinkFile}{SinkFile}: The path to a file to which the Channel should write \sstitem \htmlref{Skip}{Skip}: Skip irrelevant data? \sstitem \htmlref{SourceFile}{SourceFile}: The path to a file from which the Channel should read \sstitem \htmlref{Strict}{Strict}: Generate errors instead of warnings? } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Objects, the following functions may also be applied to all Channels: \sstitemlist{ \sstitem \htmlref{astWarnings}{astWarnings}: Return warnings from the previous read or write \sstitem \htmlref{astPutChannelData}{astPutChannelData}: Store data to pass to source or sink functions \sstitem \htmlref{astRead}{astRead}: Read an Object from a Channel \sstitem \htmlref{astWrite}{astWrite}: Write an Object to a Channel } } } \sstroutine{ Circle }{ A circular or spherical region within a Frame }{ \sstdescription{ The Circle class implements a \htmlref{Region}{Region} which represents a circle or sphere within a \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{astCircle}{astCircle} } \sstdiytopic{ Inheritance }{ The Circle class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Circle class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Regions, the following functions may also be applied to all Circles: \sstitemlist{ \sstitem \htmlref{astCirclePars}{astCirclePars}: Get the geometric parameters of the Circle } } } \sstroutine{ CmpFrame }{ Compound Frame }{ \sstdescription{ A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames (of any class) to be merged together to form a more complex Frame. The axes of the two component Frames then appear together in the resulting CmpFrame (those of the first Frame, followed by those of the second Frame). Since a CmpFrame is itself a Frame, it can be used as a component in forming further CmpFrames. Frames of arbitrary complexity may be built from simple individual Frames in this way. Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} (a sub-class of Frame), then the CmpFrame will use the Region as a Mapping when transforming values for axes described by the Region. Thus input axis values corresponding to positions which are outside the Region will result in bad output axis values. } \sstconstructor{ \htmlref{astCmpFrame}{astCmpFrame} } \sstdiytopic{ Inheritance }{ The CmpFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ The CmpFrame class does not define any new attributes beyond those which are applicable to all Frames. However, the attributes of the component Frames can be accessed as if they were attributes of the CmpFrame. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame}, then the CmpFrame will recognise the \texttt{"} \htmlref{Equinox}{Equinox}\texttt{"} attribute and forward access requests to the component SkyFrame. Likewise, it will recognise the \texttt{"} \htmlref{RestFreq}{RestFreq}\texttt{"} attribute and forward access requests to the component SpecFrame. An axis index can optionally be appended to the end of any attribute name, in which case the request to access the attribute will be forwarded to the primary Frame defining the specified axis. } \sstdiytopic{ Functions }{ The CmpFrame class does not define any new functions beyond those which are applicable to all Frames. } } \sstroutine{ CmpMap }{ Compound Mapping }{ \sstdescription{ A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be \texttt{"} in series\texttt{"} (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the earlier coordinates for each point and the second Mapping simultaneously transforms the later coordinates). Since a CmpMap is itself a Mapping, it can be used as a component in forming further CmpMaps. Mappings of arbitrary complexity may be built from simple individual Mappings in this way. } \sstconstructor{ \htmlref{astCmpMap}{astCmpMap} } \sstdiytopic{ Inheritance }{ The CmpMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The CmpMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The CmpMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ CmpRegion }{ A combination of two regions within a single Frame }{ \sstdescription{ A CmpRegion is a \htmlref{Region}{Region} which allows two component Regions (of any class) to be combined to form a more complex Region. This combination may be performed a boolean AND, OR or XOR (exclusive OR) operator. If the AND operator is used, then a position is inside the CmpRegion only if it is inside both of its two component Regions. If the OR operator is used, then a position is inside the CmpRegion if it is inside either (or both) of its two component Regions. If the XOR operator is used, then a position is inside the CmpRegion if it is inside one but not both of its two component Regions. Other operators can be formed by negating one or both component Regions before using them to construct a new CmpRegion. The two component Region need not refer to the same coordinate \htmlref{Frame}{Frame}, but it must be possible for the \htmlref{astConvert}{astConvert} function to determine a \htmlref{Mapping}{Mapping} between them (an error will be reported otherwise when the CmpRegion is created). For instance, a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} with a Region defined within a Galactic SkyFrame. This is acceptable because the SkyFrame class knows how to convert between these two systems, and consequently the astConvert function will also be able to convert between them. In such cases, the second component Region will be mapped into the coordinate Frame of the first component Region, and the Frame represented by the CmpRegion as a whole will be the Frame of the first component Region. Since a CmpRegion is itself a Region, it can be used as a component in forming further CmpRegions. Regions of arbitrary complexity may be built from simple individual Regions in this way. } \sstconstructor{ \htmlref{astCmpRegion}{astCmpRegion} } \sstdiytopic{ Inheritance }{ The CmpRegion class inherits from the Region class. } \sstdiytopic{ Attributes }{ The CmpRegion class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The CmpRegion class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ DSBSpecFrame }{ Dual sideband spectral coordinate system description }{ \sstdescription{ A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents positions in a spectrum obtained using a dual sideband instrument. Such an instrument produces a spectrum in which each point contains contributions from two distinctly different frequencies, one from the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). Corresponding LSB and USB frequencies are connected by the fact that they are an equal distance on either side of a fixed central frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. When quoting a position within such a spectrum, it is necessary to indicate whether the quoted position is the USB position or the corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this indication. Another option that the SideBand attribute provides is to represent a spectral position by its topocentric offset from the LO frequency. In practice, the LO frequency is specified by giving the distance from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically this central position is that of some interesting spectral feature. The distance from this central position to the LO frequency is known as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can be a signed value in order to indicate whether the LO frequency is above or below the central position. } \sstconstructor{ \htmlref{astDSBSpecFrame}{astDSBSpecFrame} } \sstdiytopic{ Inheritance }{ The DSBSpecFrame class inherits from the SpecFrame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all SpecFrames, every DSBSpecFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignSideBand}{AlignSideBand}: Should alignment occur between sidebands? \sstitem \htmlref{DSBCentre}{DSBCentre}: The central position of interest. \sstitem \htmlref{IF}{IF}: The intermediate frequency used to define the LO frequency. \sstitem \htmlref{ImagFreq}{ImagFreq}: The image sideband equivalent of the rest frequency. \sstitem \htmlref{SideBand}{SideBand}: Indicates which sideband the DSBSpecFrame represents. } } \sstdiytopic{ Functions }{ The DSBSpecFrame class does not define any new functions beyond those which are applicable to all SpecFrames. } } \sstroutine{ DssMap }{ Map points using a Digitised Sky Survey plate solution }{ \sstdescription{ The DssMap class implements a \htmlref{Mapping}{Mapping} which transforms between 2-dimensional pixel coordinates and an equatorial sky coordinate system (right ascension and declination) using a Digitised Sky Survey (DSS) astrometric plate solution. The input coordinates are pixel numbers along the first and second dimensions of an image, where the centre of the first pixel is located at (1,1) and the spacing between pixel centres is unity. The output coordinates are right ascension and declination in radians. The celestial coordinate system used (FK4, FK5, etc.) is unspecified, and will usually be indicated by appropriate keywords in a FITS header. } \sstconstructor{ The DssMap class does not have a constructor function. A DssMap is created only as a by-product of reading a \htmlref{FrameSet}{FrameSet} (using \htmlref{astRead}{astRead}) from a \htmlref{FitsChan}{FitsChan} which contains FITS header cards describing a DSS plate solution, and whose \htmlref{Encoding}{Encoding} attribute is set to \texttt{"} DSS\texttt{"} . The result of such a read, if successful, is a FrameSet whose base and current Frames are related by a DssMap. } \sstdiytopic{ Inheritance }{ The DssMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The DssMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The DssMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Ellipse }{ An elliptical region within a 2-dimensional Frame }{ \sstdescription{ The Ellipse class implements a \htmlref{Region}{Region} which represents a ellipse within a 2-dimensional \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{astEllipse}{astEllipse} } \sstdiytopic{ Inheritance }{ The Ellipse class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Ellipse class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Regions, the following functions may also be applied to all Ellipses: \sstitemlist{ \sstitem \htmlref{astEllipsePars}{astEllipsePars}: Get the geometric parameters of the Ellipse } } } \sstroutine{ FitsChan }{ I/O Channel using FITS header cards to represent Objects }{ \sstdescription{ A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O operations involving the use of FITS (Flexible Image Transport \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description. While a FitsChan is active, it represents a buffer which may contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} card, to which subsequent operations apply. Searches based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and existing ones may be deleted (\htmlref{astDelFits}{astDelFits}), extracted (\htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}), or changed (astSetFits$<$X$>$). When you create a FitsChan, you have the option of specifying \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using astPutFits, astPutCards, astWrite or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from which headers should be read). When the FitsChan is deleted, any remaining header cards in the FitsChan can be saved in either of two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the name of a text file to which header cards should be written), or 2) by providing a sink function (used to to deliver header cards to an external data store). If you do not provide a sink function or a value for SinkFile, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using astFindFits or \htmlref{astRead}{astRead}). Coordinate system information may be described using FITS header cards using several different conventions, termed \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers). The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings. The detailed behaviour of astRead and astWrite, when used with a FitsChan, depends on the encoding in use. In general, however, all successful use of astRead is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the \htmlref{astRetainFits}{astRetainFits} function). An unsuccessful call of astRead (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged. If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using astWrite will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence. } \sstconstructor{ \htmlref{astFitsChan}{astFitsChan} } \sstdiytopic{ Inheritance }{ The FitsChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every FitsChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{AllWarnings}{AllWarnings}: A list of the available conditions \sstitem \htmlref{Card}{Card}: Index of current FITS card in a FitsChan \sstitem \htmlref{CardComm}{CardComm}: The comment of the current FITS card in a FitsChan \sstitem \htmlref{CardName}{CardName}: The keyword name of the current FITS card in a FitsChan \sstitem \htmlref{CardType}{CardType}: The data type of the current FITS card in a FitsChan \sstitem \htmlref{CarLin}{CarLin}: Ignore spherical rotations on CAR projections? \sstitem \htmlref{CDMatrix}{CDMatrix}: Use a CD matrix instead of a PC matrix? \sstitem \htmlref{Clean}{Clean}: Remove cards used whilst reading even if an error occurs? \sstitem \htmlref{DefB1950}{DefB1950}: Use FK4 B1950 as default equatorial coordinates? \sstitem \htmlref{Encoding}{Encoding}: System for encoding Objects as FITS headers \sstitem \htmlref{FitsAxisOrder}{FitsAxisOrder}: Sets the order of WCS axes within new FITS-WCS headers \sstitem \htmlref{FitsDigits}{FitsDigits}: Digits of precision for floating-point FITS values \sstitem \htmlref{Iwc}{Iwc}: Add a \htmlref{Frame}{Frame} describing Intermediate World Coords? \sstitem \htmlref{Ncard}{Ncard}: Number of FITS header cards in a FitsChan \sstitem \htmlref{Nkey}{Nkey}: Number of unique keywords in a FitsChan \sstitem \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"} algorithm be recognised? \sstitem \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection? \sstitem \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Channels, the following functions may also be applied to all FitsChans: \sstitemlist{ \sstitem \htmlref{astDelFits}{astDelFits}: Delete the current FITS card in a FitsChan \sstitem \htmlref{astEmptyFits}{astEmptyFits}: Delete all cards in a FitsChan \sstitem \htmlref{astFindFits}{astFindFits}: Find a FITS card in a FitsChan by keyword \sstitem \htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}: Get a keyword value from a FitsChan \sstitem \htmlref{astGetTables}{astGetTables}: Retrieve any FitsTables from a FitsChan \sstitem \htmlref{astPurgeWCS}{astPurgeWCS}: Delete all WCS-related cards in a FitsChan \sstitem \htmlref{astPutCards}{astPutCards}: Stores a set of FITS header card in a FitsChan \sstitem \htmlref{astPutFits}{astPutFits}: Store a FITS header card in a FitsChan \sstitem \htmlref{astPutTable}{astPutTable}: Store a single \htmlref{FitsTable}{FitsTable} in a FitsChan \sstitem \htmlref{astPutTables}{astPutTables}: Store multiple FitsTables in a FitsChan \sstitem \htmlref{astReadFits}{astReadFits}: Read cards in through the source function \sstitem \htmlref{astRemoveTables}{astRemoveTables}: Remove one or more FitsTables from a FitsChan \sstitem \htmlref{astRetainFits}{astRetainFits}: Ensure current card is retained in a FitsChan \sstitem \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}: Store a new keyword value in a FitsChan \sstitem \htmlref{astShowFits}{astShowFits}: Display the contents of a FitsChan on standard output \sstitem \htmlref{astTableSource}{astTableSource}: Register a source function for FITS table access \sstitem \htmlref{astTestFits}{astTestFits}: Test if a keyword has a defined value in a FitsChan \sstitem \htmlref{astWriteFits}{astWriteFits}: Write all cards out to the sink function \sstitem AST\_SHOWFITS: Display the contents of a FitsChan on standard output } } } \sstroutine{ FitsTable }{ A representation of a FITS binary table }{ \sstdescription{ The FitsTable class is a representation of a FITS binary table. It inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the binary data of the main table, and a \htmlref{FitsChan}{FitsChan} (encapsulated within the FitsTable) is used to hold the FITS header. Note - it is not recommended to use the FitsTable class to store very large tables. FitsTables are primarily geared towards the needs of the \texttt{"} -TAB\texttt{"} algorithm defined in FITS-WCS paper 2, and so do not support all features of FITS binary tables. In particularly, they do not provide any equivalent to the following features of FITS binary tables: \texttt{"} heap\texttt{"} data (i.e. binary data following the main table), columns holding complex values, columns holding variable length arrays, scaled columns, column formats, columns holding bit values, 8-byte integer values or logical values. } \sstconstructor{ \htmlref{astFitsTable}{astFitsTable} } \sstdiytopic{ Inheritance }{ The FitsTable class inherits from the Table class. } \sstdiytopic{ Attributes }{ The FitsTable class does not define any new attributes beyond those which are applicable to all Tables. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Tables, the following functions may also be applied to all FitsTables: \sstitemlist{ \sstitem \htmlref{astColumnNull}{astColumnNull}: Get/set the null value for a column of a FitsTable \sstitem \htmlref{astColumnSize}{astColumnSize}: Get number of bytes needed to hold a full column of data \sstitem \htmlref{astGetColumnData}{astGetColumnData}: Retrieve all the data values stored in a column \sstitem \htmlref{astGetTableHeader}{astGetTableHeader}: Get the FITS headers from a FitsTable \sstitem \htmlref{astPutColumnData}{astPutColumnData}: Store data values in a column \sstitem \htmlref{astPutTableHeader}{astPutTableHeader}: Store FITS headers within a FitsTable } } } \sstroutine{ FluxFrame }{ Measured flux description }{ \sstdescription{ A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various systems used to represent the signal level in an observation. The particular coordinate system to be used is specified by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by other attributes such as the units, etc (see the description of the System attribute for details). All flux values are assumed to be measured at the same frequency or wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is more appropriate for use with images rather than spectra. } \sstconstructor{ \htmlref{astFluxFrame}{astFluxFrame} } \sstdiytopic{ Inheritance }{ The FluxFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every FluxFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{SpecVal}{SpecVal}: The spectral position at which the flux values are measured. } } \sstdiytopic{ Functions }{ The FluxFrame class does not define any new functions beyond those which are applicable to all Frames. } } \sstroutine{ Frame }{ Coordinate system description }{ \sstdescription{ This class is used to represent coordinate systems. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a \htmlref{Title}{Title} (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two. Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame. Frames may also contain knowledge of how to transform to and from related coordinate systems. } \sstconstructor{ \htmlref{astFrame}{astFrame} } \sstnotes{ \sstitemlist{ \sstitem When used as a \htmlref{Mapping}{Mapping}, a Frame implements a unit (null) transformation in both the forward and inverse directions (equivalent to a \htmlref{UnitMap}{UnitMap}). The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attribute values are both equal to the number of Frame axes. } } \sstdiytopic{ Inheritance }{ The Frame class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every Frame also has the following attributes (if the Frame has only one axis, the axis specifier can be omited from the following attribute names): \sstitemlist{ \sstitem \htmlref{AlignSystem}{AlignSystem}: Coordinate system used to align Frames \sstitem \htmlref{Bottom(axis)}{Bottom(axis)}: Lowest axis value to display \sstitem \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}: Number of digits of precision \sstitem \htmlref{Direction(axis)}{Direction(axis)}: Display axis in conventional direction? \sstitem \htmlref{Domain}{Domain}: Coordinate system domain \sstitem \htmlref{Dut1}{Dut1}: Difference between the UT1 and UTC timescale \sstitem \htmlref{Epoch}{Epoch}: Epoch of observation \sstitem \htmlref{Format(axis)}{Format(axis)}: Format specification for axis values \sstitem \htmlref{InternalUnit(axis)}{InternalUnit(axis)}: Physical units for unformated axis values \sstitem \htmlref{Label(axis)}{Label(axis)}: \htmlref{Axis}{Axis} label \sstitem \htmlref{MatchEnd}{MatchEnd}: Match trailing axes? \sstitem \htmlref{MaxAxes}{MaxAxes}: Maximum number of Frame axes to match \sstitem \htmlref{MinAxes}{MinAxes}: Minimum number of Frame axes to match \sstitem \htmlref{Naxes}{Naxes}: Number of Frame axes \sstitem \htmlref{NormUnit(axis)}{NormUnit(axis)}: Normalised physical units for formatted axis values \sstitem \htmlref{ObsAlt}{ObsAlt}: Geodetic altitude of observer \sstitem \htmlref{ObsLat}{ObsLat}: Geodetic latitude of observer \sstitem \htmlref{ObsLon}{ObsLon}: Geodetic longitude of observer \sstitem \htmlref{Permute}{Permute}: Permute axis order? \sstitem \htmlref{PreserveAxes}{PreserveAxes}: Preserve axes? \sstitem \htmlref{Symbol(axis)}{Symbol(axis)}: Axis symbol \sstitem \htmlref{System}{System}: Coordinate system used to describe the domain \sstitem \htmlref{Title}{Title}: Frame title \sstitem \htmlref{Top(axis)}{Top(axis)}: Highest axis value to display \sstitem \htmlref{Unit(axis)}{Unit(axis)}: Physical units for formatted axis values } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Mappings, the following functions may also be applied to all Frames: \sstitemlist{ \sstitem \htmlref{astAngle}{astAngle}: Calculate the angle subtended by two points at a third point \sstitem \htmlref{astAxAngle}{astAxAngle}: Find the angle from an axis, to a line through two points \sstitem \htmlref{astAxDistance}{astAxDistance}: Calculate the distance between two axis values \sstitem \htmlref{astAxNorm}{astAxNorm}: Normalises an array of axis values \sstitem \htmlref{astAxOffset}{astAxOffset}: Calculate an offset along an axis \sstitem \htmlref{astConvert}{astConvert}: Determine how to convert between two coordinate systems \sstitem \htmlref{astDistance}{astDistance}: Calculate the distance between two points in a Frame \sstitem \htmlref{astFindFrame}{astFindFrame}: Find a coordinate system with specified characteristics \sstitem \htmlref{astFormat}{astFormat}: Format a coordinate value for a Frame axis \sstitem \htmlref{astGetActiveUnit}{astGetActiveUnit}: Determines how the Unit attribute will be used \sstitem \htmlref{astIntersect}{astIntersect}: Find the intersection between two geodesic curves \sstitem \htmlref{astMatchAxes}{astMatchAxes}: Find any corresponding axes in two Frames \sstitem \htmlref{astNorm}{astNorm}: Normalise a set of Frame coordinates \sstitem \htmlref{astOffset}{astOffset}: Calculate an offset along a geodesic curve \sstitem \htmlref{astOffset2}{astOffset2}: Calculate an offset along a geodesic curve in a 2D Frame \sstitem \htmlref{astPermAxes}{astPermAxes}: Permute the order of a Frame\texttt{'} s axes \sstitem \htmlref{astPickAxes}{astPickAxes}: Create a new Frame by picking axes from an existing one \sstitem \htmlref{astResolve}{astResolve}: Resolve a vector into two orthogonal components \sstitem \htmlref{astSetActiveUnit}{astSetActiveUnit}: Specify how the Unit attribute should be used \sstitem \htmlref{astUnformat}{astUnformat}: Read a formatted coordinate value for a Frame axis } } } \sstroutine{ FrameSet }{ Set of inter-related coordinate systems }{ \sstdescription{ 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 \htmlref{Mapping}{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 \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} 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\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{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 \texttt{"} native\texttt{"} coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the \texttt{"} apparent\texttt{"} 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 \htmlref{Title}{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 \texttt{"} native\texttt{"} coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), 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 \htmlref{Region}{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. } \sstconstructor{ \htmlref{astFrameSet}{astFrameSet} } \sstdiytopic{ Inheritance }{ The FrameSet class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every FrameSet also has the following attributes: \sstitemlist{ \sstitem \htmlref{AllVariants}{AllVariants}: List of all variant mappings store with current Frame \sstitem \htmlref{Base}{Base}: FrameSet base Frame index \sstitem \htmlref{Current}{Current}: FrameSet current Frame index \sstitem \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet \sstitem \htmlref{Variant}{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\texttt{'} s class. (For example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{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. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Frames, the following functions may also be applied to all FrameSets: \sstitemlist{ \sstitem \htmlref{astAddFrame}{astAddFrame}: Add a Frame to a FrameSet to define a new coordinate system \sstitem \htmlref{astAddVariant}{astAddVariant}: Add a variant Mapping to the current Frame \sstitem \htmlref{astGetFrame}{astGetFrame}: Obtain a pointer to a specified Frame in a FrameSet \sstitem \htmlref{astGetMapping}{astGetMapping}: Obtain a Mapping between two Frames in a FrameSet \sstitem \htmlref{astMirrorVariants}{astMirrorVariants}: Make the current Frame mirror variant Mappings in another Frame \sstitem \htmlref{astRemapFrame}{astRemapFrame}: Modify a Frame\texttt{'} s relationship to the other Frames in a FrameSet \sstitem \htmlref{astRemoveFrame}{astRemoveFrame}: Remove a Frame from a FrameSet } } } \sstroutine{ GrismMap }{ Transform 1-dimensional coordinates using a grism dispersion equation }{ \sstdescription{ A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III \texttt{"} Representation of spectral coordinates in FITS\texttt{"} . This describes the dispersion produced by gratings, prisms and grisms. When initially created, the forward transformation of a GrismMap transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as \texttt{"} the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length\texttt{"} . The units in which wavelength values are expected or returned is determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will also be used for the wavelength values. } \sstconstructor{ \htmlref{astGrismMap}{astGrismMap} } \sstdiytopic{ Inheritance }{ The GrismMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every GrismMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{GrismNR}{GrismNR}: The refractive index at the reference wavelength \sstitem \htmlref{GrismNRP}{GrismNRP}: Rate of change of refractive index with wavelength \sstitem \htmlref{GrismWaveR}{GrismWaveR}: The reference wavelength \sstitem \htmlref{GrismAlpha}{GrismAlpha}: The angle of incidence of the incoming light \sstitem \htmlref{GrismG}{GrismG}: The grating ruling density \sstitem \htmlref{GrismM}{GrismM}: The interference order \sstitem \htmlref{GrismEps}{GrismEps}: The angle between the normal and the dispersion plane \sstitem \htmlref{GrismTheta}{GrismTheta}: Angle between normal to detector plane and reference ray } } \sstdiytopic{ Functions }{ The GrismMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Interval }{ A region representing an interval on one or more axes of a Frame }{ \sstdescription{ The Interval class implements a \htmlref{Region}{Region} which represents upper and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval. Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} should usually be used in these cases since this requires the user to think about suitable upper and lower limits, } \sstconstructor{ \htmlref{astInterval}{astInterval} } \sstdiytopic{ Inheritance }{ The Interval class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Interval class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Interval class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ IntraMap }{ Map points using a private transformation function }{ \sstdescription{ The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which encapsulates a privately-defined coordinate transformation other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. However, an IntraMap is intended for use within a single program or a private suite of software, where all programs have access to the same coordinate transformation functions (i.e. can be linked against them). IntraMaps should not normally be stored in datasets which may be exported for processing by other software, since that software will not have the necessary transformation functions available, resulting in an error. You must register any coordinate transformation functions to be used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap. } \sstconstructor{ \htmlref{astIntraMap}{astIntraMap} (also see astIntraReg) } \sstdiytopic{ Inheritance }{ The IntraMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every IntraMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{IntraFlag}{IntraFlag}: IntraMap identification string } } \sstdiytopic{ Functions }{ The IntraMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ KeyMap }{ Store a set of key/value pairs }{ \sstdescription{ The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), void pointer, character string or AST \htmlref{Object}{Object} pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap. } \sstconstructor{ \htmlref{astKeyMap}{astKeyMap} } \sstdiytopic{ Inheritance }{ The KeyMap class inherits from the Object class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every KeyMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{KeyCase}{KeyCase}: Sets the case in which keys are stored \sstitem \htmlref{KeyError}{KeyError}: \htmlref{Report}{Report} an error if the requested key does not exist? \sstitem \htmlref{SizeGuess}{SizeGuess}: The expected size of the KeyMap. \sstitem \htmlref{SortBy}{SortBy}: Determines how keys are sorted in a KeyMap. \sstitem \htmlref{MapLocked}{MapLocked}: Prevent new entries being added to the KeyMap? } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Objects, the following functions may also be applied to all KeyMaps: \sstitemlist{ \sstitem \htmlref{astMapDefined}{astMapDefined}: Does a KeyMap contain a defined value for a key? \sstitem \htmlref{astMapGet0$<$X$>$}{astMapGet0$<$X$>$}: Get a named scalar entry from a KeyMap \sstitem \htmlref{astMapGet1$<$X$>$}{astMapGet1$<$X$>$}: Get a named vector entry from a KeyMap \sstitem \htmlref{astMapGetElem$<$X$>$}{astMapGetElem$<$X$>$}: Get an element of a named vector entry from a KeyMap \sstitem \htmlref{astMapHasKey}{astMapHasKey}: Does the KeyMap contain a named entry? \sstitem \htmlref{astMapKey}{astMapKey}: Return the key name at a given index in the KeyMap \sstitem \htmlref{astMapLenC}{astMapLenC}: Get the length of a named character entry in a KeyMap \sstitem \htmlref{astMapLength}{astMapLength}: Get the length of a named entry in a KeyMap \sstitem \htmlref{astMapCopy}{astMapCopy}: Copy entries from one KeyMap into another \sstitem \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$}: Add a new scalar entry to a KeyMap \sstitem \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$}: Add a new vector entry to a KeyMap \sstitem \htmlref{astMapPutElem$<$X$>$}{astMapPutElem$<$X$>$}: Puts a value into a vector entry in a KeyMap \sstitem \htmlref{astMapPutU}{astMapPutU}: Add a new entry to a KeyMap with an undefined value \sstitem \htmlref{astMapRemove}{astMapRemove}: Removed a named entry from a KeyMap \sstitem \htmlref{astMapRename}{astMapRename}: Rename an existing entry in a KeyMap \sstitem \htmlref{astMapSize}{astMapSize}: Get the number of entries in a KeyMap \sstitem \htmlref{astMapType}{astMapType}: Return the data type of a named entry in a map } } } \sstroutine{ LutMap }{ Transform 1-dimensional coordinates using a lookup table }{ \sstdescription{ A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms 1-dimensional coordinates by using linear interpolation in a lookup table. Each input coordinate value is first scaled to give the index of an entry in the table by subtracting a starting value (the input coordinate corresponding to the first table entry) and dividing by an increment (the difference in input coordinate value between adjacent table entries). The resulting index will usually contain a fractional part, so the output coordinate value is then generated by interpolating linearly between the appropriate entries in the table. If the index lies outside the range of the table, linear extrapolation is used based on the two nearest entries (i.e. the two entries at the start or end of the table, as appropriate). If either of the entries used for the interplation has a value of AST\_\_BAD, then the interpolated value is returned as AST\_\_BAD. If the lookup table entries increase or decrease monotonically (ignoring any flat sections), then the inverse transformation may also be performed. } \sstconstructor{ \htmlref{astLutMap}{astLutMap} } \sstdiytopic{ Inheritance }{ The LutMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every LutMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{LutEpsilon}{LutEpsilon}: The relative error of the values in the table. \sstitem \htmlref{LutInterp}{LutInterp}: The interpolation method to use between table entries. } } \sstdiytopic{ Functions }{ The LutMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Mapping }{ Inter-relate two coordinate systems }{ \sstdescription{ This class provides the basic facilities for transforming a set of coordinates (representing \texttt{"} input\texttt{"} points) to give a new set of coordinates (representing \texttt{"} output\texttt{"} points). It is used to describe the relationship which exists between two different coordinate systems and to implement operations which make use of this (such as transforming coordinates and resampling grids of data). However, the Mapping class does not have a constructor function of its own, as it is simply a container class for a family of specialised Mappings which implement particular types of coordinate transformation. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Mapping class inherits from the \htmlref{Object}{Object} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Objects, every Mapping also has the following attributes: \sstitemlist{ \sstitem \htmlref{Invert}{Invert}: Mapping inversion flag \sstitem \htmlref{IsLinear}{IsLinear}: Is the Mapping linear? \sstitem \htmlref{IsSimple}{IsSimple}: Has the Mapping been simplified? \sstitem \htmlref{Nin}{Nin}: Number of input coordinates for a Mapping \sstitem \htmlref{Nout}{Nout}: Number of output coordinates for a Mapping \sstitem \htmlref{Report}{Report}: Report transformed coordinates? \sstitem \htmlref{TranForward}{TranForward}: Forward transformation defined? \sstitem \htmlref{TranInverse}{TranInverse}: Inverse transformation defined? } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Objects, the following functions may also be applied to all Mappings: \sstitemlist{ \sstitem \htmlref{astDecompose}{astDecompose}: Decompose a Mapping into two component Mappings \sstitem \htmlref{astTranGrid}{astTranGrid}: Transform a grid of positions \sstitem \htmlref{astInvert}{astInvert}: Invert a Mapping \sstitem \htmlref{astLinearApprox}{astLinearApprox}: Calculate a linear approximation to a Mapping \sstitem \htmlref{astMapBox}{astMapBox}: Find a bounding box for a Mapping \sstitem \htmlref{astMapSplit}{astMapSplit}: Split a Mapping up into parallel component Mappings \sstitem \htmlref{astQuadApprox}{astQuadApprox}: Calculate a quadratic approximation to a 2D Mapping \sstitem \htmlref{astRate}{astRate}: Calculate the rate of change of a Mapping output \sstitem \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}: Rebin a region of a data grid \sstitem \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$}: Rebin a region of a sequence of data grids \sstitem \htmlref{astResample$<$X$>$}{astResample$<$X$>$}: Resample a region of a data grid \sstitem \htmlref{astRemoveRegions}{astRemoveRegions}: Remove any Regions from a Mapping \sstitem \htmlref{astSimplify}{astSimplify}: Simplify a Mapping \sstitem \htmlref{astTran1}{astTran1}: Transform 1-dimensional coordinates \sstitem \htmlref{astTran2}{astTran2}: Transform 2-dimensional coordinates \sstitem \htmlref{astTranN}{astTranN}: Transform N-dimensional coordinates \sstitem \htmlref{astTranP}{astTranP}: Transform N-dimensional coordinates held in separate arrays } } } \sstroutine{ MathMap }{ Transform coordinates using mathematical expressions }{ \sstdescription{ A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs. } \sstconstructor{ \htmlref{astMathMap}{astMathMap} } \sstdiytopic{ Inheritance }{ The MathMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every MathMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Seed}{Seed}: Random number seed \sstitem \htmlref{SimpFI}{SimpFI}: Forward-inverse MathMap pairs simplify? \sstitem \htmlref{SimpIF}{SimpIF}: Inverse-forward MathMap pairs simplify? } } \sstdiytopic{ Functions }{ The MathMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ MatrixMap }{ Map coordinates by multiplying by a matrix }{ \sstdescription{ A MatrixMap is form of \htmlref{Mapping}{Mapping} which performs a general linear transformation. Each set of input coordinates, regarded as a column-vector, are pre-multiplied by a matrix (whose elements are specified when the MatrixMap is created) to give a new column-vector containing the output coordinates. If appropriate, the inverse transformation may also be performed. } \sstconstructor{ \htmlref{astMatrixMap}{astMatrixMap} } \sstdiytopic{ Inheritance }{ The MatrixMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The MatrixMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The MatrixMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ NormMap }{ Normalise coordinates using a supplied Frame }{ \sstdescription{ The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate values using the \htmlref{astNorm}{astNorm} function of a supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap are both equal to the number of axes in the supplied Frame. The forward and inverse transformation of a NormMap are both defined but are identical (that is, they do not form a real inverse pair in that the inverse transformation does not undo the normalisation, instead it reapplies it). However, the \htmlref{astSimplify}{astSimplify} function will replace neighbouring pairs of forward and inverse NormMaps by a single \htmlref{UnitMap}{UnitMap}. } \sstconstructor{ \htmlref{astNormMap}{astNormMap} } \sstdiytopic{ Inheritance }{ The NormMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The NormMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The NormMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ NullRegion }{ A boundless region within a Frame }{ \sstdescription{ The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}. If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion represents a Region containing no points. If the Negated attribute of a NullRegion is true, the NullRegion represents an infinite Region (that is, all points in the coordinate system are inside the NullRegion). } \sstconstructor{ \htmlref{astNullRegion}{astNullRegion} } \sstdiytopic{ Inheritance }{ The NullRegion class inherits from the Region class. } \sstdiytopic{ Attributes }{ The NullRegion class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The NullRegion class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ Object }{ Base class for all AST Objects }{ \sstdescription{ This class is the base class from which all other classes in the AST library are derived. It provides all the basic Object behaviour and Object manipulation facilities required throughout the library. There is no Object constructor, however, as Objects on their own are not useful. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Object base class does not inherit from any other class. } \sstdiytopic{ Attributes }{ All Objects have the following attributes: \sstitemlist{ \sstitem \htmlref{Class}{Class}: Object class name \sstitem \htmlref{ID}{ID}: Object identification string \sstitem \htmlref{Ident}{Ident}: Permanent Object identification string \sstitem \htmlref{Nobject}{Nobject}: Number of Objects in class \sstitem \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes \sstitem \htmlref{RefCount}{RefCount}: Count of active Object pointers \sstitem \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes? } } \sstdiytopic{ Functions }{ The following functions may be applied to all Objects: \sstitemlist{ \sstitem \htmlref{astAnnul}{astAnnul}: Annul a pointer to an Object \sstitem \htmlref{astBegin}{astBegin}: Begin a new AST context \sstitem \htmlref{astClear}{astClear}: Clear attribute values for an Object \sstitem \htmlref{astClone}{astClone}: Clone a pointer to an Object \sstitem \htmlref{astCopy}{astCopy}: Copy an Object \sstitem \htmlref{astDelete}{astDelete}: Delete an Object \sstitem \htmlref{astEnd}{astEnd}: End an AST context \sstitem \htmlref{astEscapes}{astEscapes}: Control whether graphical escape sequences are removed \sstitem \htmlref{astExempt}{astExempt}: Exempt an Object pointer from AST context handling \sstitem \htmlref{astExport}{astExport}: Export an Object pointer to an outer context \sstitem \htmlref{astGet$<$X$>$}{astGet$<$X$>$}: Get an attribute value for an Object \sstitem \htmlref{astHasAttribute}{astHasAttribute}: Test if an Object has a named attribute \sstitem \htmlref{astImport}{astImport}: Import an Object pointer to the current context \sstitem \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$}: Test class membership \sstitem \htmlref{astLock}{astLock}: Lock an Object for use by the calling thread \sstitem \htmlref{astToString}{astToString}: Create an in-memory serialisation of an Object \sstitem \htmlref{astSame}{astSame}: Do two AST pointers refer to the same Object? \sstitem \htmlref{astSet}{astSet}: Set attribute values for an Object \sstitem \htmlref{astSet$<$X$>$}{astSet$<$X$>$}: Set an attribute value for an Object \sstitem \htmlref{astShow}{astShow}: Display a textual representation of an Object on standard output \sstitem \htmlref{astTest}{astTest}: Test if an attribute value is set for an Object \sstitem \htmlref{astTune}{astTune}: Set or get an integer AST tuning parameter \sstitem \htmlref{astTuneC}{astTuneC}: Set or get a character AST tuning parameter \sstitem \htmlref{astUnlock}{astUnlock}: Unlock an Object for use by other threads \sstitem \htmlref{astFromString}{astFromString}: Re-create an Object from an in-memory serialisation \sstitem \htmlref{astVersion}{astVersion}: Return the verson of the AST library being used. } } } \sstroutine{ PcdMap }{ Apply 2-dimensional pincushion/barrel distortion }{ \sstdescription{ A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional positions to correct for the radial distortion introduced by some cameras and telescopes. This can take the form either of pincushion or barrel distortion, and is characterized by a single distortion coefficient. A PcdMap is specified by giving this distortion coefficient and the coordinates of the centre of the radial distortion. The forward transformation of a PcdMap applies the distortion: RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) where R is the undistorted radial distance from the distortion centre (specified by attribute PcdCen), RD is the radial distance from the same centre in the presence of distortion, and C is the distortion coefficient (given by attribute \htmlref{Disco}{Disco}). The inverse transformation of a PcdMap removes the distortion produced by the forward transformation. The expression used to derive R from RD is an approximate inverse of the expression above. } \sstconstructor{ \htmlref{astPcdMap}{astPcdMap} } \sstdiytopic{ Inheritance }{ The PcdMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every PcdMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient \sstitem \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion } } \sstdiytopic{ Functions }{ The PcdMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ PermMap }{ Coordinate permutation Mapping }{ \sstdescription{ A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, and possibly also changes the number of coordinates, between its input and output. In addition to permuting the coordinate order, a PermMap may also assign constant values to coordinates. This is useful when the number of coordinates is being increased as it allows fixed values to be assigned to any new ones. } \sstconstructor{ \htmlref{astPermMap}{astPermMap} } \sstdiytopic{ Inheritance }{ The PermMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The PermMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The PermMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Plot }{ Provide facilities for 2D graphical output }{ \sstdescription{ This class provides facilities for producing 2D graphical output. A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created. The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect). Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve} and \htmlref{astPolyCurve}{astPolyCurve}). A Plot also provides facilities for drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with optional coordinate grids (\htmlref{astGrid}{astGrid}). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these functions. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot, using its \htmlref{Current}{Current} attribute. You may also set up clipping (see \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in. Like any FrameSet, a Plot may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a Mapping, a Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST\_\_BAD). } \sstconstructor{ \htmlref{astPlot}{astPlot} } \sstdiytopic{ Inheritance }{ The Plot class inherits from the FrameSet class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all FrameSets, every Plot also has the following attributes: \sstitemlist{ \sstitem Abbrev: Abbreviate leading fields? \sstitem \htmlref{Border}{Border}: Draw a border around valid regions of a Plot? \sstitem \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary? \sstitem \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR? \sstitem \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element \sstitem \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot? \sstitem \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot? \sstitem \htmlref{Escape}{Escape}: Allow changes of character attributes within strings? \sstitem \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot \sstitem \htmlref{Font(element)}{Font(element)}: Character font for a Plot element \sstitem \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values \sstitem \htmlref{Grf}{Grf}: Select the graphics interface to use. \sstitem \htmlref{Grid}{Grid}: Draw grid lines for a Plot? \sstitem \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink? \sstitem \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot \sstitem \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot? \sstitem \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright? \sstitem \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot \sstitem \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values \sstitem \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically? \sstitem \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically? \sstitem \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot \sstitem \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot \sstitem \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot \sstitem \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot? \sstitem \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot \sstitem \htmlref{Size(element)}{Size(element)}: Character size for a Plot element \sstitem \htmlref{Style(element)}{Style(element)}: Line style for a Plot element \sstitem \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot? \sstitem \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot \sstitem \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot? \sstitem \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title \sstitem \htmlref{Tol}{Tol}: Plotting tolerance \sstitem \htmlref{Width(element)}{Width(element)}: Line width for a Plot element } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all FrameSets, the following functions may also be applied to all Plots: \sstitemlist{ \sstitem \htmlref{astBBuf}{astBBuf}: Begin a new graphical buffering context \sstitem \htmlref{astBorder}{astBorder}: Draw a border around valid regions of a Plot \sstitem \htmlref{astBoundingBox}{astBoundingBox}: Returns a bounding box for previously drawn graphics \sstitem \htmlref{astClip}{astClip}: Set up or remove clipping for a Plot \sstitem \htmlref{astCurve}{astCurve}: Draw a geodesic curve \sstitem \htmlref{astEBuf}{astEBuf}: End the current graphical buffering context \sstitem \htmlref{astGenCurve}{astGenCurve}: Draw a generalized curve \sstitem \htmlref{astGetGrfContext}{astGetGrfContext}: Get the graphics context for a Plot \sstitem \htmlref{astGrfPop}{astGrfPop}: Retrieve previously saved graphics functions \sstitem \htmlref{astGrfPush}{astGrfPush}: Save the current graphics functions \sstitem \htmlref{astGrfSet}{astGrfSet}: Register a graphics routine for use by a Plot \sstitem \htmlref{astGrid}{astGrid}: Draw a set of labelled coordinate axes \sstitem \htmlref{astGridLine}{astGridLine}: Draw a grid line (or axis) for a Plot \sstitem \htmlref{astMark}{astMark}: Draw a set of markers for a Plot \sstitem \htmlref{astPolyCurve}{astPolyCurve}: Draw a series of connected geodesic curves \sstitem \htmlref{astRegionOutline}{astRegionOutline}: Draw the outline of an AST \htmlref{Region}{Region} \sstitem \htmlref{astText}{astText}: Draw a text string for a Plot } } \sstdiytopic{ Graphical Elements }{ The colour index, character font, character size, line style and line width used for plotting can be set independently for various elements of the graphical output produced by a Plot. The different graphical elements are identified by appending the strings listed below as subscripts to the Plot attributes Colour(element), Font(element), Size(element), Style(element) and Width(element). These strings are case-insensitive and unambiguous abbreviations may be used. Elements of the graphical output which relate to individual axes can be referred to either independently (e.g. \texttt{"} (Grid1)\texttt{"} and \texttt{"} (Grid2)\texttt{"} ) or together (e.g. \texttt{"} (Grid)\texttt{"} ): \sstitemlist{ \sstitem Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using astGrid \sstitem Axis1: Axis line drawn through tick marks on axis 1 using astGrid \sstitem Axis2: Axis line drawn through tick marks on axis 2 using astGrid \sstitem Border: The Plot border drawn using astBorder, astGrid or astRegionOutline \sstitem Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve \sstitem Grid: Grid lines drawn using astGridLine or astGrid \sstitem Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid \sstitem Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid \sstitem Markers: Graphical markers (symbols) drawn using astMark \sstitem NumLab: Numerical axis labels drawn using astGrid \sstitem NumLab1: Numerical labels for axis 1 drawn using astGrid \sstitem NumLab2: Numerical labels for axis 2 drawn using astGrid \sstitem Strings: Text strings drawn using astText \sstitem TextLab: Descriptive axis labels drawn using astGrid \sstitem TextLab1: Descriptive label for axis 1 drawn using astGrid \sstitem TextLab2: Descriptive label for axis 2 drawn using astGrid \sstitem Ticks: Tick marks (both major and minor) drawn using astGrid \sstitem Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid \sstitem Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid \sstitem \htmlref{Title}{Title}: The Plot title drawn using astGrid } } } \sstroutine{ Plot3D }{ Provide facilities for 3D graphical output }{ \sstdescription{ A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities for producing 3D graphical output, including fully annotated 3D coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional \texttt{"} graphical\texttt{"} coordinate system. The axes of this coordinate system are assumed to be right-handed (that is, if X appears horizontally to the right and Y vertically upwards, then Z is out of the screen towards the viewer), and are assumed to be equally scaled (that is, the same units are used to measure positions on each of the 3 axes). The upper and lower bounds of a volume within this graphical coordinate system is specified when the Plot3D is created, and all subsequent graphics are \texttt{"} drawn\texttt{"} in this volume. The Plot3D class does not itself include any ability to draw on a graphics device. Instead it calls upon function in an externally supplied module (the \texttt{"} grf3d\texttt{"} module) to do the required drawing. A module should be written that implements the functions of the grf3d interface using the facilities of a specific graphics system This module should then be linked into the application so that the Plot3D class can use its functions (see the description of the \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface defines a few simple functions for drawing primitives such as straight lines, markers and character strings. These functions all accept positions in the 3D graphics coordinate system (the base Frame of the Plot3D), and so the grf3d module must also manage the projection of these 3D coordinates onto the 2D viewing surface, including the choice of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"} position, direction of viewing, etc. The AST library includes a sample implementation of the grf3d interface based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This implementation also serves to document the grf3d interface itself and should be consulted for details before writing a new implementation. The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"} 3-dimensional coordinate system, which is the coordinate system in which plotting operations are specified when invoking the methods of the Plot3D class. The results of each plotting operation are automatically transformed into 3D graphical coordinates before being plotted using the facilities of the grf3d module linked into the application. Note, at least one of the three axes of the current Frame must be independent of the other two current Frame axes. You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot3D, using its \htmlref{Current}{Current} attribute. Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system. When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation between 3D graphical coordinates (its base Frame) and 3D physical coordinates (its current Frame). Although the Plot3D class inherits from the Plot class, several of the facilities of the Plot class are not available in the Plot3D class, and an error will be reported if any attempt is made to use them. Specifically, the Plot3D class does not support clipping using the \htmlref{astClip}{astClip} function. Nor does it support the specification of graphics primitive functions at run-time using the \htmlref{astGrfSet}{astGrfSet}, \htmlref{astGrfPop}{astGrfPop}, \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGetGrfContext}{astGetGrfContext} functions. } \sstconstructor{ \htmlref{astPlot3D}{astPlot3D} } \sstdiytopic{ Inheritance }{ The Plot3D class inherits from the Plot class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Plots, every Plot3D also has the following attributes: \sstitemlist{ \sstitem Norm: Normal vector defining the 2D plane used for text and markers \sstitem \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated. } Some attributes of the Plot class refer to specific physical coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic Plot, the axis index must be 1 or 2, but for a Plot3D the axis index can be 1, 2 or 3. Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation for details. All other Plot attributes can be set for a specific plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"} or \texttt{"} \_YZ\texttt{"} to the end of the Plot attribute name. For instance, \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"} refers to the \texttt{"} Grid\texttt{"} attribute for the plane spanning the second (Y) and third (Z) axes of the 3-d plot. } \sstdiytopic{ Functions }{ The Plot3D class does not define any new functions beyond those which are applicable to all Plots. Note, however, that the following methods inherited from the Plot class cannot be used with a Plot3D and will report an error if called: \sstitemlist{ \sstitem \htmlref{astBoundingBox}{astBoundingBox}, astClip, \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve}, astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, \htmlref{astGridLine}{astGridLine}, \htmlref{astPolyCurve}{astPolyCurve}. } } } \sstroutine{ PointList }{ A collection of points in a Frame }{ \sstdescription{ The PointList class implements a \htmlref{Region}{Region} which represents a collection of points in a \htmlref{Frame}{Frame}. } \sstconstructor{ \htmlref{astPointList}{astPointList} } \sstdiytopic{ Inheritance }{ The PointList class inherits from the Region class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every PointList also has the following attributes: \sstitemlist{ \sstitem \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList } } \sstdiytopic{ Functions }{ The PointList class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ PolyMap }{ Map coordinates using polynomial functions }{ \sstdescription{ A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, an iterative method can be used to evaluate the inverse based only on the forward transformation. } \sstconstructor{ \htmlref{astPolyMap}{astPolyMap} } \sstdiytopic{ Inheritance }{ The PolyMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every PolyMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation? \sstitem \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse \sstitem \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Objects, the following functions may also be applied to all Mappings: \sstitemlist{ \sstitem \htmlref{astPolyTran}{astPolyTran}: Fit a PolyMap inverse or forward transformation } } } \sstroutine{ Polygon }{ A polygonal region within a 2-dimensional Frame }{ \sstdescription{ The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon. Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied). } \sstconstructor{ \htmlref{astPolygon}{astPolygon} } \sstdiytopic{ Inheritance }{ The Polygon class inherits from the \htmlref{Region}{Region} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every Polygon also has the following attributes: \sstitemlist{ \sstitem \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices? } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Regions, the following functions may also be applied to all Polygons: \sstitemlist{ \sstitem \htmlref{astDownsize}{astDownsize}: Reduce the number of vertices in a Polygon. \sstitem \htmlref{astConvex$<$X$>$}{astConvex$<$X$>$}: Create a Polygon giving the convex hull of a pixel array \sstitem \htmlref{astOutline$<$X$>$}{astOutline$<$X$>$}: Create a Polygon outlining values in a pixel array } } } \sstroutine{ Prism }{ An extrusion of a region into higher dimensions }{ \sstdescription{ A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region into one or more orthogonal dimensions (specified by another Region). If the Region to be extruded has N axes, and the Region defining the extrusion has M axes, then the resulting Prism will have (M$+$N) axes. A point is inside the Prism if the first N axis values correspond to a point inside the Region being extruded, and the remaining M axis values correspond to a point inside the Region defining the extrusion. As an example, a cylinder can be represented by extruding an existing \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the Interval would have a single axis and would specify the upper and lower limits of the cylinder along its length. } \sstconstructor{ \htmlref{astPrism}{astPrism} } \sstdiytopic{ Inheritance }{ The Prism class inherits from the Region class. } \sstdiytopic{ Attributes }{ The Prism class does not define any new attributes beyond those which are applicable to all Regions. } \sstdiytopic{ Functions }{ The Prism class does not define any new functions beyond those which are applicable to all Regions. } } \sstroutine{ RateMap }{ Mapping which represents differentiation }{ \sstdescription{ A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the Jacobian matrix of another Mapping. The Mapping for which the Jacobian is required is specified when the new RateMap is created, and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. The number of inputs to a RateMap is the same as the number of inputs to its encapsulated Mapping. The number of outputs from a RateMap is always one. This one output equals the rate of change of a specified output of the encapsulated Mapping with respect to a specified input of the encapsulated Mapping (the input and output to use are specified when the RateMap is created). A RateMap which has not been inverted does not define an inverse transformation. If a RateMap has been inverted then it will define an inverse transformation but not a forward transformation. } \sstconstructor{ \htmlref{astRateMap}{astRateMap} } \sstdiytopic{ Inheritance }{ The RateMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The RateMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The RateMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Region }{ Represents a region within a coordinate system }{ \sstdescription{ This class provides the basic facilities for describing a region within a specified coordinate system. However, the Region class does not have a constructor function of its own, as it is simply a container class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc, which implement Regions with particular shapes. All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region is created. This Frame describes the coordinate system in which the Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"} below. Constructors will also typically required one or more positions to be supplied which define the location and extent of the region. These positions must be supplied within the encapsulated Frame. The Region class inherits from the Frame class, and so a Region can be supplied where-ever a Frame is expected. In these cases, supplying a Region is equivalent to supplying a reference to its encapsulated Frame. Thus all the methods of the Frame class can be used on the Region class. For instance, the \htmlref{astFormat}{astFormat} function may be used on a Region to format an axis value. In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort of Mapping. Transforming positions by supplying a Region to one of the astTran$<$X$>$ functions is the way to determine if a given position is inside or outside the Region. When used as a Mapping, most classes of Frame are equivalent to a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a Region acts like a UnitMap only for input positions which are within the area represented by the Region. Input positions which are outside the area produce bad output values (i.e. the output values are equal to AST\_\_BAD). This behaviour is the same for both the forward and the inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"} is not a true inverse of the forward transformation, since applying the forward transformation to a point outside the Region, and then applying the inverse transformation results, in a set of AST\_\_BAD axis values rather than the original axis values. If required, the \htmlref{astRemoveRegions}{astRemoveRegions} function can be used to remove the \texttt{"} masking\texttt{"} effect of any Regions contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by replacing each Region with a UnitMap or equivalent Frame (depending on the context in which the Region is used). If the coordinate system represented by the Region is changed (by changing the values of one or more of the attribute which the Region inherits from its encapsulated Frame), the area represented by the Region is mapped into the new coordinate system. For instance, let\texttt{'} s say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being supplied to the constructor so that the Circle describes a circular area on the sky in FK4 equatorial coordinates. Since Region inherits from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then changed from FK4 to FK5, the circular area represented by the Region will automatically be mapped from the FK4 system into the FK5 system. In general, changing the coordinate system in this way may result in the region changing shape - for instance, a circle may change into an ellipse if the transformation from the old to the new coordinate system is linear but with different scales on each axis. Thus the specific class of a Region cannot be used as a guarantee of the shape in any particular coordinate system. If the \htmlref{astSimplify}{astSimplify} function is used on a Region, it will endeavour to return a new Region of a sub-class which accurately describes the shape in the current coordinate system of the Region (but this may not always be possible). It is possible to negate an existing Region so that it represents all areas of the encapsulated Frame except for the area specified when the Region was created. } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The Region class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every Region also has the following attributes: \sstitemlist{ \sstitem \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system? \sstitem \htmlref{Negated}{Negated}: Has the original region been negated? \sstitem \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region? \sstitem \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region \sstitem \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest \sstitem \htmlref{Bounded}{Bounded}: Is the Region bounded? } Every Region also inherits any further attributes that belong to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is inherited by any Region which represents a SkyFrame.) } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Frames, the following functions may also be applied to all Regions: \sstitemlist{ \sstitem \htmlref{astGetRegionBounds}{astGetRegionBounds}: Get the bounds of a Region \sstitem \htmlref{astGetRegionFrame}{astGetRegionFrame}: Get a copy of the Frame represent by a Region \sstitem \htmlref{astGetRegionFrameSet}{astGetRegionFrameSet}: Get a copy of the Frameset encapsulated by a Region \sstitem \htmlref{astGetRegionMesh}{astGetRegionMesh}: Get a mesh of points covering a Region \sstitem \htmlref{astGetRegionPoints}{astGetRegionPoints}: Get the positions that define a Region \sstitem \htmlref{astGetUnc}{astGetUnc}: Obtain uncertainty information from a Region \sstitem \htmlref{astMapRegion}{astMapRegion}: Transform a Region into a new coordinate system \sstitem \htmlref{astNegate}{astNegate}: Toggle the value of the Negated attribute \sstitem \htmlref{astOverlap}{astOverlap}: Determines the nature of the overlap between two Regions \sstitem \htmlref{astMask$<$X$>$}{astMask$<$X$>$}: Mask a region of a data grid \sstitem \htmlref{astSetUnc}{astSetUnc}: Associate a new uncertainty with a Region \sstitem \htmlref{astShowMesh}{astShowMesh}: Display a mesh of points on the surface of a Region } } } \sstroutine{ SelectorMap }{ A Mapping that locates positions within one of a set of alternate Regions }{ \sstdescription{ A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains a given input position. A SelectorMap encapsulates a number of Regions that all have the same number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes spanned by one of the encapsulated Region. All SelectorMaps have only a single output. SelectorMaps do not define an inverse transformation. For each input position, the forward transformation of a SelectorMap searches through the encapsulated Regions (in the order supplied when the SelectorMap was created) until a Region is found which contains the input position. The index associated with this Region is returned as the SelectorMap output value (the index value is the position of the Region within the list of Regions supplied when the SelectorMap was created, starting at 1 for the first Region). If an input position is not contained within any Region, a value of zero is returned by the forward transformation. If a compound Mapping contains a SelectorMap in series with its own inverse, the combination of the two adjacent SelectorMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{astSimplify}{astSimplify}. In practice, SelectorMaps are often used in conjunction with SwitchMaps. } \sstconstructor{ \htmlref{astSelectorMap}{astSelectorMap} } \sstdiytopic{ Inheritance }{ The SelectorMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SelectorMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The SelectorMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ ShiftMap }{ Add a constant value to each coordinate }{ \sstdescription{ A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a specified constant value. } \sstconstructor{ \htmlref{astShiftMap}{astShiftMap} } \sstdiytopic{ Inheritance }{ The ShiftMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The ShiftMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The ShiftMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ SkyAxis }{ Store celestial axis information }{ \sstdescription{ The SkyAxis class is used to store information associated with a particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from \htmlref{astWrite}{astWrite}). } \sstconstructor{ None. } \sstdiytopic{ Inheritance }{ The SkyAxis class inherits from the \htmlref{Axis}{Axis} class. } } \sstroutine{ SkyFrame }{ Celestial coordinate system description }{ \sstdescription{ A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or an \htmlref{Epoch}{Epoch}. For each of the supported celestial coordinate systems, a SkyFrame can apply an optional shift of origin to create a coordinate system representing offsets within the celestial coordinate system from some specified reference point. This offset coordinate system can also be rotated to define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using \htmlref{astFormat}{astFormat}. For a SkyFrame, the Unit attribute describes the formatted value of a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a formatted axis value contains colon-separated fields for hours, minutes and seconds. On the other hand, the InternalUnit attribute for a SkyFrame is always set to \texttt{"} rad\texttt{"} (i.e. radians), indicating that the unformatted (i.e. floating point) axis values used by application code are always in units of radians } \sstconstructor{ \htmlref{astSkyFrame}{astSkyFrame} } \sstdiytopic{ Inheritance }{ The SkyFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every SkyFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system? \sstitem \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times? \sstitem \htmlref{Equinox}{Equinox}: Epoch of the mean equinox \sstitem IsLatAxis: Is the specified axis the latitude axis? \sstitem IsLonAxis: Is the specified axis the longitude axis? \sstitem \htmlref{LatAxis}{LatAxis}: Index of the latitude axis \sstitem \htmlref{LonAxis}{LonAxis}: Index of the longitude axis \sstitem \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]? \sstitem \htmlref{Projection}{Projection}: Sky projection description. \sstitem SkyRef: Position defining location of the offset coordinate system \sstitem \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system \sstitem SkyRefP: Position defining orientation of the offset coordinate system \sstitem \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Frames, the following functions may also be applied to all SkyFrames: \sstitemlist{ \sstitem \htmlref{astSkyOffsetMap}{astSkyOffsetMap}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates } } } \sstroutine{ SlaMap }{ Sequence of celestial coordinate conversions }{ \sstdescription{ An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard celestial (longitude, latitude) coordinate systems. When an SlaMap is first created, it simply performs a unit (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd} function, a series of coordinate conversion steps may then be added, selected from those provided by the SLALIB Positional Astronomy Library (Starlink User Note SUN/67). This allows multi-step conversions between a variety of celestial coordinate systems to be assembled out of the building blocks provided by SLALIB. For details of the individual coordinate conversions available, see the description of the astSlaAdd function. } \sstconstructor{ \htmlref{astSlaMap}{astSlaMap} (also see astSlaAdd) } \sstdiytopic{ Inheritance }{ The SlaMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SlaMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Mappings, the following function may also be applied to all SlaMaps: \sstitemlist{ \sstitem \htmlref{astSlaAdd}{astSlaAdd}: Add a celestial coordinate conversion to an SlaMap } } } \sstroutine{ SpecFluxFrame }{ Compound spectrum/flux Frame }{ \sstdescription{ A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents spectral position and the second axis represents flux. } \sstconstructor{ \htmlref{astSpecFluxFrame}{astSpecFluxFrame} } \sstdiytopic{ Inheritance }{ The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class. } \sstdiytopic{ Attributes }{ The SpecFluxFrame class does not define any new attributes beyond those which are applicable to all CmpFrames. However, the attributes of the component Frames can be accessed as if they were attributes of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"} attribute and forward access requests to the component SpecFrame. An axis index can optionally be appended to the end of any attribute name, in which case the request to access the attribute will be forwarded to the primary Frame defining the specified axis. } \sstdiytopic{ Functions }{ The SpecFluxFrame class does not define any new functions beyond those which are applicable to all CmpFrames. } } \sstroutine{ SpecFrame }{ Spectral coordinate system description }{ \sstdescription{ A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions within an electro-magnetic spectrum. The particular coordinate system to be used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the default is wavelength) qualified, as necessary, by other attributes such as the rest frequency, the standard of rest, the epoch of observation, units, etc (see the description of the System attribute for details). By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute spectral values. } \sstconstructor{ \htmlref{astSpecFrame}{astSpecFrame} } \sstdiytopic{ Inheritance }{ The SpecFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every SpecFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system? \sstitem \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames \sstitem \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000) \sstitem \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000) \sstitem \htmlref{RestFreq}{RestFreq}: Rest frequency \sstitem \htmlref{SourceSys}{SourceSys}: Source velocity spectral system \sstitem \htmlref{SourceVel}{SourceVel}: Source velocity \sstitem \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame \sstitem \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values \sstitem \htmlref{StdOfRest}{StdOfRest}: Standard of rest } Several of the Frame attributes inherited by the SpecFrame class refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional, it allows these attributes to be specified without an axis index. So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Frames, the following functions may also be applied to all SpecFrames: \sstitemlist{ \sstitem \htmlref{astSetRefPos}{astSetRefPos}: Set reference position in any celestial system \sstitem \htmlref{astGetRefPos}{astGetRefPos}: Get reference position in any celestial system } } } \sstroutine{ SpecMap }{ Sequence of spectral coordinate conversions }{ \sstdescription{ A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard spectral coordinate systems. When an SpecMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of spectral coordinate systems to be assembled out of a set of building blocks. Conversions are available to transform between standards of rest. Such conversions need to know the source position as an RA and DEC. This information can be supplied in the form of parameters for the relevant conversions, in which case the SpecMap is 1-dimensional, simply transforming the spectral axis values. This means that the same source position will always be used by the SpecMap. However, this may not be appropriate for an accurate description of a 3-D spectral cube, where changes of spatial position can produce significant changes in the Doppler shift introduced when transforming between standards of rest. For this situation, a 3-dimensional SpecMap can be created in which axes 2 and 3 correspond to the source RA and DEC The SpecMap simply copies values for axes 2 and 3 from input to output), but modifies axis 1 values (the spectral axis) appropriately. For details of the individual coordinate conversions available, see the description of the astSpecAdd function. } \sstconstructor{ \htmlref{astSpecMap}{astSpecMap} (also see astSpecAdd) } \sstdiytopic{ Inheritance }{ The SpecMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SpecMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Mappings, the following function may also be applied to all SpecMaps: \sstitemlist{ \sstitem \htmlref{astSpecAdd}{astSpecAdd}: Add a spectral coordinate conversion to an SpecMap } } } \sstroutine{ SphMap }{ Map 3-d Cartesian to 2-d spherical coordinates }{ \sstdescription{ A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors). } \sstconstructor{ \htmlref{astSphMap}{astSphMap} } \sstdiytopic{ Inheritance }{ The SphMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every SphMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere? \sstitem \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole } } \sstdiytopic{ Functions }{ The SphMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Stc }{ Represents an instance of the IVOA STC class }{ \sstdescription{ The Stc class is an implementation of the IVOA STC class which forms part of the IVOA Space-Time Coordinate Metadata system. See: http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html The Stc class does not have a constructor function of its own, as it is simply a container class for a family of specialised sub-classes including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation} and \htmlref{StcObsDataLocation}{StcObsDataLocation}. } \sstconstructor{ astStc } \sstdiytopic{ Inheritance }{ The Stc class inherits from the \htmlref{Region}{Region} class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Regions, every Stc also has the following attributes: \sstitemlist{ \sstitem \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region. } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Regions, the following functions may also be applied to all Stc\texttt{'} s: \sstitemlist{ \sstitem \htmlref{astGetStcRegion}{astGetStcRegion}: Get a pointer to the encapsulated Region \sstitem \htmlref{astGetStcCoord}{astGetStcCoord}: Get information about an AstroCoords element \sstitem \htmlref{astGetStcNCoord}{astGetStcNCoord}: Returns the number of AstroCoords elements in an Stc } } } \sstroutine{ StcCatalogEntryLocation }{ Correspond to the IVOA STCCatalogEntryLocation class }{ \sstdescription{ The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{astStcCatalogEntryLocation}{astStcCatalogEntryLocation} } \sstdiytopic{ Inheritance }{ The StcCatalogEntryLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcCatalogEntryLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcCatalogEntryLocation class does not define any new functions beyond those which are applicable to all Stcs. } } \sstroutine{ StcObsDataLocation }{ Correspond to the IVOA ObsDataLocation class }{ \sstdescription{ The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coordinate space occupied by a particular observational dataset. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html An STC ObsDataLocation element specifies the extent of the observation within a specified coordinate system, and also specifies the observatory location within a second coordinate system. The AST StcObsDataLocation class inherits from Stc, and therefore an StcObsDataLocation can be used directly as an Stc. When used in this way, the StcObsDataLocation describes the location of the observation (not the observatory). Eventually, this class will have a method for returning an Stc describing the observatory location. However, AST currently does not include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar system positions. Therefore, the provision for returning observatory location as an Stc is not yet available. However, for terrestrial observations, the position of the observatory can still be recorded using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated within the Stc representing the observation location (this assumes the observatory is located at sea level). } \sstconstructor{ \htmlref{astStcObsDataLocation}{astStcObsDataLocation} } \sstdiytopic{ Inheritance }{ The StcObsDataLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcObsDataLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcObsDataLocation class does not define any new functions beyond those which are applicable to all Stcs. } } \sstroutine{ StcResourceProfile }{ Correspond to the IVOA STCResourceProfile class }{ \sstdescription{ The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of the datasets contained in some VO resource. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{astStcResourceProfile}{astStcResourceProfile} } \sstdiytopic{ Inheritance }{ The StcResourceProfile class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcResourceProfile class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcResourceProfile class does not define any new functions beyond those which are applicable to all Stcs. } } \sstroutine{ StcSearchLocation }{ Correspond to the IVOA SearchLocation class }{ \sstdescription{ The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe the coverage of a query. See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html } \sstconstructor{ \htmlref{astStcSearchLocation}{astStcSearchLocation} } \sstdiytopic{ Inheritance }{ The StcSearchLocation class inherits from the Stc class. } \sstdiytopic{ Attributes }{ The StcSearchLocation class does not define any new attributes beyond those which are applicable to all Stcs. } \sstdiytopic{ Functions }{ The StcSearchLocation class does not define any new functions beyond those which are applicable to all Stcs. } } \sstroutine{ StcsChan }{ I/O Channel using STC-S to represent Objects }{ \sstdescription{ A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an STC-S description of that Object, and reading from an StcsChan will create a new Object from its STC-S description. When an STC-S description is read using \htmlref{astRead}{astRead}, the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC AstroCoords (i.e. a single point of interest within the coordinate frame described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC AstrCoordsArea (i.e. an area or volume of interest within the coordinate frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap} containing the uninterpreted property values read form the STC-S description, or 4) a KeyMap containing any combination of the first 3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} control which of the above is returned by astRead. When an STC-S description is created from an AST Object using astWrite, the AST Object must be either a Region or a KeyMap. If it is a Region, it is assumed to define the AstroCoordsArea or (if the Region is a single point) the AstroCoords to write to the STC-S description. If the Object is a KeyMap, it may contain an entry with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} , holding a Region (a PointList) to be used to create the AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding a KeyMap that contains uninterpreted property values to be used as defaults for any STC-S properties that are not determined by the other supplied Regions. In addition, a KeyMap supplied to astWrite may itself hold the default STC-S properties (rather than defaults being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"} entry in the supplied KeyMap). The astRead and astWrite functions work together so that any Object returned by astRead can immediately be re-written using astWrite. Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output. Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. Support for STC-S is currently based on the IVOA document \texttt{"} STC-S: Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} , version 1.30 (dated 5th December 2007), available at http://www.ivoa.net/Documents/latest/STC-S.html. Note, this document is a recommednation only and does not constitute an accepted IVOA standard. The full text of version 1.30 is supported by the StcsChan class, with the following exceptions and provisos: \sstitemlist{ \sstitem When reading an STC-S phrase, case is ignored except when reading units strings. \sstitem There is no support for multiple intervals specified within a TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval. \sstitem If the ET timescale is specified, TT is used instead. \sstitem If the TEB timescale is specified, TDB is used instead. \sstitem The LOCAL timescale is not supported. \sstitem The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a reference position to be specified. Consequently, any $<$refpos$>$ specified within the Time or Space sub-phrase of an STC-S document is ignored. \sstitem The Convex identifier for the space sub-phrase is not supported. \sstitem The GEO\_C and GEO\_D space frames are not supported. \sstitem The UNITSPHERE and SPHER3 space flavours are not supported. \sstitem If any Error values are supplied in a space sub-phrase, then the number of values supplied should equal the number of spatial axes, and the values are assumed to specify an error box (i.e. error circles, ellipses, etc, are not supported). \sstitem The spectral and redshift sub-phrases do not support the following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos, EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO. \sstitem Error values are supported but error ranges are not. \sstitem Resolution, PixSize and Size values are ignored. \sstitem Space velocity sub-phrases are ignored. } } \sstconstructor{ \htmlref{astStcsChan}{astStcsChan} } \sstdiytopic{ Inheritance }{ The StcsChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every StcsChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S? \sstitem \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S? \sstitem \htmlref{StcsLength}{StcsLength}: Controls output buffer length \sstitem \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S? } } \sstdiytopic{ Functions }{ The StcsChan class does not define any new functions beyond those which are applicable to all Channels. } } \sstroutine{ SwitchMap }{ A Mapping that encapsulates a set of alternate Mappings }{ \sstdescription{ A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate Mappings, each of which is used to transform positions within a particular region of the input or output coordinate system of the SwitchMap. A SwitchMap can encapsulate any number of Mappings, but they must all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms positions between the input and output coordinate space of the entire SwitchMap, but only one Mapping will be used to transform any given position. The selection of the appropriate route Mapping to use with any given input position is made by another Mapping, called the \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping must have the same number of inputs as the route Mappings, but should have only one output. Likewise, the inverse selector Mapping must have the same number of outputs as the route Mappings, but should have only one input. When the SwitchMap is used to transform a position in the forward direction (from input to output), each supplied input position is first transformed by the forward transformation of the forward selector Mapping. This produces a single output value for each input position referred to as the selector value. The nearest integer to the selector value is found, and is used to index the array of route Mappings (the first supplied route Mapping has index 1, the second route Mapping has index 2, etc). If the nearest integer to the selector value is less than 1 or greater than the number of route Mappings, then the SwitchMap output position is set to a value of AST\_\_BAD on every axis. Otherwise, the forward transformation of the selected route Mapping is used to transform the supplied input position to produce the SwitchMap output position. When the SwitchMap is used to transform a position in the inverse direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} position. Again, the nearest integer to the selector value is found, and is used to index the array of route Mappings. If this selector index value is within the bounds of the array of route Mappings, then the inverse transformation of the selected route Mapping is used to transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is set to a value of AST\_\_BAD on every axis. In practice, appropriate selector Mappings should be chosen to associate a different route Mapping with each region of coordinate space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly appropriate for this purpose. If a compound Mapping contains a SwitchMap in series with its own inverse, the combination of the two adjacent SwitchMaps will be replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using \htmlref{astSimplify}{astSimplify}. } \sstconstructor{ \htmlref{astSwitchMap}{astSwitchMap} } \sstdiytopic{ Inheritance }{ The SwitchMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The SwitchMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The SwitchMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ Table }{ A 2-dimensional table of values }{ \sstdescription{ The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional table of values. The astMapGet... and astMapPut... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the upper-case name of a table column and \texttt{"} i\texttt{"} is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table. Columns must be declared using the \htmlref{astAddColumn}{astAddColumn} method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape, as specified when the column is added to the Table. Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the \htmlref{astAddParameter}{astAddParameter} method before being accessed. Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables. } \sstconstructor{ \htmlref{astTable}{astTable} } \sstdiytopic{ Inheritance }{ The Table class inherits from the KeyMap class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all KeyMaps, every Table also has the following attributes: \sstitemlist{ \sstitem \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column \sstitem \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column \sstitem \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column \sstitem \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column \sstitem ColumnUnit(column): The unit string describing each value in a column \sstitem \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table \sstitem \htmlref{Nrow}{Nrow}: The number of rows currently in the Table \sstitem \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table } } \sstdiytopic{ Functions }{ In addition to those functions applicable to all KeyMaps, the following functions may also be applied to all Tables: \sstitemlist{ \sstitem \htmlref{astAddColumn}{astAddColumn}: Add a new column definition to a Table \sstitem \htmlref{astAddParameter}{astAddParameter}: Add a new global parameter definition to a Table \sstitem \htmlref{astColumnName}{astColumnName}: Return the name of the column with a given index \sstitem \htmlref{astColumnShape}{astColumnShape}: Return the shape of the values in a named column \sstitem \htmlref{astHasColumn}{astHasColumn}: Checks if a column exists in a Table \sstitem \htmlref{astHasParameter}{astHasParameter}: Checks if a global parameter exists in a Table \sstitem \htmlref{astParameterName}{astParameterName}: Return the name of the parameter with a given index \sstitem \htmlref{astPurgeRows}{astPurgeRows}: Remove all empty rows from a Table \sstitem \htmlref{astRemoveColumn}{astRemoveColumn}: Remove a column from a Table \sstitem \htmlref{astRemoveParameter}{astRemoveParameter}: Remove a global parameter from a Table \sstitem \htmlref{astRemoveRow}{astRemoveRow}: Remove a row from a Table } } } \sstroutine{ TimeFrame }{ Time coordinate system description }{ \sstdescription{ A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which represents various coordinate systems used to describe positions in time. A TimeFrame represents a moment in time as either an Modified Julian Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame representing time offsets from the specified zero point. Even though JD and MJD are defined as being in units of days, the TimeFrame class allows other units to be used (via the Unit attribute) on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs can be described in units other than the usual years. Besselian epoch are always represented in units of (tropical) years. The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that is, the physical process used to define the rate of flow of time). MJD, JD and Julian epoch can be used to represent a time in any supported time scale. However, Besselian epoch may only be used with the \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales includes universal time and siderial time. Strictly, these represent angles rather than time scales, but are included in the list since they are in common use and are often thought of as time scales. When a time value is formatted it can be formated either as a simple floating point value, or as a Gregorian date (see the Format attribute). } \sstconstructor{ \htmlref{astTimeFrame}{astTimeFrame} } \sstdiytopic{ Inheritance }{ The TimeFrame class inherits from the Frame class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Frames, every TimeFrame also has the following attributes: \sstitemlist{ \sstitem \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames \sstitem \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours. \sstitem \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values \sstitem \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame } Several of the Frame attributes inherited by the TimeFrame class refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional, it allows these attributes to be specified without an axis index. So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Frames, the following functions may also be applied to all TimeFrames: \sstitemlist{ \sstitem \htmlref{astCurrentTime}{astCurrentTime}: Return the current system time } } } \sstroutine{ TimeMap }{ Sequence of time coordinate conversions }{ \sstdescription{ A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be used to represent a sequence of conversions between standard time coordinate systems. When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd} function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks. For details of the individual coordinate conversions available, see the description of the astTimeAdd function. } \sstconstructor{ \htmlref{astTimeMap}{astTimeMap} (also see astTimeAdd) } \sstdiytopic{ Inheritance }{ The TimeMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The TimeMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ In addition to those functions applicable to all Mappings, the following function may also be applied to all TimeMaps: \sstitemlist{ \sstitem \htmlref{astTimeAdd}{astTimeAdd}: Add a time coordinate conversion to an TimeMap } } } \sstroutine{ TranMap }{ Mapping with specified forward and inverse transformations }{ \sstdescription{ A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of a supplied Mapping with the inverse transformation of another supplied Mapping, ignoring the un-used transformation in each Mapping (indeed the un-used transformation need not exist). When the forward transformation of the TranMap is referred to, the transformation actually used is the forward transformation of the first Mapping supplied when the TranMap was constructed. Likewise, when the inverse transformation of the TranMap is referred to, the transformation actually used is the inverse transformation of the second Mapping supplied when the TranMap was constructed. } \sstconstructor{ \htmlref{astTranMap}{astTranMap} } \sstdiytopic{ Inheritance }{ The TranMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The TranMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The TranMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ UnitMap }{ Unit (null) Mapping }{ \sstdescription{ A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the coordinates supplied to it. They are simply copied. This can be useful if a Mapping is required (e.g. to pass to another function) but you do not want it to have any effect. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and are specified when it is created. } \sstconstructor{ \htmlref{astUnitMap}{astUnitMap} } \sstdiytopic{ Inheritance }{ The UnitMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The UnitMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The UnitMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ UnitNormMap }{ Convert a vector to a unit vector and its norm, relative to a specified centre }{ \sstdescription{ The forward transformation of a UnitNormMap subtracts the specified centre and then transforms the resulting vector to a unit vector and the vector norm. The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm. The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. UnitNormMap enables radially symmetric transformations, as follows: \sstitemlist{ \sstitem apply a UnitNormMap to produce a unit vector and norm (radius) \sstitem apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged \sstitem apply the same UnitNormMap in the inverse direction to produce the result } } \sstconstructor{ \htmlref{astUnitNormMap}{astUnitNormMap} } \sstdiytopic{ Inheritance }{ The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class. } \sstdiytopic{ Attributes }{ The UnitNormMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The UnitNormMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ WcsMap }{ Implement a FITS-WCS sky projection }{ \sstdescription{ This class is used to represent sky coordinate projections as described in the FITS world coordinate system (FITS-WCS) paper II \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"} by M. Calabretta and E.W. Griesen. This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa). A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection plane\texttt{"} coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} . These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS). The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be associated with each axis. These specify the precise form of the projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is the integer axis index (starting at 1), and m is an integer \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper. } \sstconstructor{ \htmlref{astWcsMap}{astWcsMap} } \sstdiytopic{ Inheritance }{ The WcsMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every WcsMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection \sstitem \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection \sstitem \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters \sstitem PVMax: Maximum number of FITS-WCS projection parameters \sstitem \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes \sstitem \htmlref{WcsType}{WcsType}: FITS-WCS projection type } } \sstdiytopic{ Functions }{ The WcsMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ WinMap }{ Map one window on to another by scaling and shifting each axis }{ \sstdescription{ A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular window in one coordinate system into a similar window in another coordinate system by scaling and shifting each axis (the window edges being parallel to the coordinate axes). A WinMap is specified by giving the coordinates of two opposite corners (A and B) of the window in both the input and output coordinate systems. } \sstconstructor{ \htmlref{astWinMap}{astWinMap} } \sstdiytopic{ Inheritance }{ The WinMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ The WinMap class does not define any new attributes beyond those which are applicable to all Mappings. } \sstdiytopic{ Functions }{ The WinMap class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ XmlChan }{ I/O Channel using XML to represent Objects }{ \sstdescription{ A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O operations. Writing an \htmlref{Object}{Object} to an XmlChan (using \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an XML description of that Object, and reading from an XmlChan will create a new Object from its XML description. Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to an external data store by reading and writing the resulting XML text. These functions should perform any conversions needed between external character encodings and the internal ASCII encoding. If no such functions are supplied, a Channel will read from standard input and write to standard output. Alternatively, an XmlChan can be told to read or write from specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, in which case no sink or source function need be supplied. } \sstconstructor{ \htmlref{astXmlChan}{astXmlChan} } \sstdiytopic{ Inheritance }{ The XmlChan class inherits from the Channel class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Channels, every XmlChan also has the following attributes: \sstitemlist{ \sstitem \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML \sstitem \htmlref{XmlLength}{XmlLength}: Controls output buffer length \sstitem \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing } } \sstdiytopic{ Functions }{ The XmlChan class does not define any new functions beyond those which are applicable to all Mappings. } } \sstroutine{ ZoomMap }{ Zoom coordinates about the origin }{ \sstdescription{ The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"} transformation by multiplying all coordinate values by the same scale factor (the inverse transformation is performed by dividing by this scale factor). The number of coordinate values representing each point is unchanged. } \sstconstructor{ \htmlref{astZoomMap}{astZoomMap} } \sstdiytopic{ Inheritance }{ The ZoomMap class inherits from the Mapping class. } \sstdiytopic{ Attributes }{ In addition to those attributes common to all Mappings, every ZoomMap also has the following attributes: \sstitemlist{ \sstitem \htmlref{Zoom}{Zoom}: ZoomMap scale factor } } \sstdiytopic{ Functions }{ The ZoomMap class does not define any new functions beyond those which are applicable to all Mappings. } } \normalsize \cleardoublepage \section{\label{ss:commanddescriptions}UNIX Command Descriptions} The commands described here are provided for use from the UNIX shell to assist with developing software which uses AST. To use these commands, you should ensure that the directory ``/star/bin''\footnote{Or the equivalent directory if AST is installed in a non-standard location.} is on your PATH. \small \sstroutine{ ast\_link }{ Link a program with the AST library }{ \sstdescription{ This command should be used when building programs which use the AST library, in order to generate the correct arguments to allow the compiler to link your program. The arguments generated are written to standard output but may be substituted into the compiler command line in the standard UNIX way using backward quotes (see below). By default, it is assumed that you are building a stand-alone program which does not produce graphical output. However, switches are provided for linking other types of program. } \sstinvocation{ cc program.c -L/star/lib `ast\_link [switches]` -o program } \sstexamples{ \sstexamplesubsection{ cc display.c -L/star/lib `ast\_link -pgplot` -o display }{ Compiles and links a C program called ``display\texttt{'} \texttt{'} which uses the standard version of PGPLOT for graphical output. } \sstexamplesubsection{ cc plotit.c -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit }{ Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } \sstexamplesubsection{ cc plotit.c -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit }{ Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } } \sstdiytopic{ Switches }{ The following switches may optionally be given to this command to modify its behaviour: \sstitemlist{ \sstitem ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages produced by the AST library are delivered via the Starlink EMS (Error Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default, error messages are simply written to standard error. \sstitem ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages produced by the AST library are delivered via the DRAMA Ers (Error Reporting Service) library. By default, error messages are simply written to standard error. \sstitem ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 2D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new graphics system yourself and wish to provide your own arguments for linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in that it assumes that your graphics module implements the complete interface required by the current version of AST. If future versions of AST introduce new functions to the graphics interface, this switch will cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you that you need to implement new functions in your graphics module. To avoid such errors, you can use one of the other, version-specific, switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time errors to be reported if any AST function is invoked which requires facilities not in the implemented interface. \sstitem ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. It indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V2.0 of AST. \sstitem ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V3.2 of AST. \sstitem ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V5.6 of AST. \sstitem ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how error messages produced by the AST library should be delivered. You should use this option only if you have implemented an interface to a new error delivery system yourself and wish to provide your own arguments for linking with it. \sstitem ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, but is retained in order to allow applications to be linked with a graphics module which implements the 2D interface used by AST V2.0. It is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. \sstitem ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 2D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 2D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 3D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new 3D graphics system yourself and wish to provide your own arguments for linking with it. \sstitem ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. } } \sstdiytopic{ ERFA \& PAL }{ The AST distribution includes bundled copies of the ERFA and PAL libraries. These will be used for fundamental positional astronomy calculations unless the \texttt{"} --with-external\_pal\texttt{"} option was used when AST was configured. If \texttt{"} --with-external\_pal\texttt{"} is used, this script will include \texttt{"} -lpal\texttt{"} in the returned list of linking options, and the user should then ensure that external copies of the PAL and ERFA libraries are available (ERFA functions are used within PAL). } } \sstroutine{ ast\_link\_adam }{ Link an ADAM program with the AST library }{ \sstdescription{ This command should only be used when building Starlink ADAM programs which use the AST library, in order to generate the correct arguments to allow the ADAM ``alink\texttt{'} \texttt{'} command to link the program. The arguments generated are written to standard output but may be substituted into the ``alink\texttt{'} \texttt{'} command line in the standard UNIX way using backward quotes (see below). By default, it is assumed that you are building an ADAM program which does not produce graphical output. However, switches are provided for linking other types of program. This command should not be used when building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'} command instead. } \sstinvocation{ alink program.o -L/star/lib `ast\_link\_adam [switches]` } \sstexamples{ \sstexamplesubsection{ alink display.o -L/star/lib `ast\_link\_adam -pgplot` }{ Links an ADAM program ``display\texttt{'} \texttt{'} which uses the standard version of PGPLOT for graphical output. } \sstexamplesubsection{ alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf` -lgrf }{ Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } \sstexamplesubsection{ alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf }{ Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\_v2.0\texttt{'} \texttt{'} switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library reference. } } \sstdiytopic{ Switches }{ The following switches may optionally be given to this command to modify its behaviour: \sstitemlist{ \sstitem ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. \sstitem ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 2D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new graphics system yourself and wish to provide your own arguments for linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in that it assumes that your graphics module implements the complete interface required by the current version of AST. If future versions of AST introduce new functions to the graphics interface, this switch will cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you that you need to implement new functions in your graphics module. To avoid such errors, you can use one of the other, version-specific, switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time errors to be reported if any AST function is invoked which requires facilities not in the implemented interface. \sstitem ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. It indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V2.0 of AST. \sstitem ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V3.2 of AST. \sstitem ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V5.6 of AST. \sstitem ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how error messages produced by the AST library should be delivered. You should use this option only if you have implemented an interface to a new error delivery system yourself and wish to provide your own arguments for linking with it. By default, error messages are delivered in the standard ADAM way via the EMS Error Message Service (Starlink \htmlref{System}{System} Note SSN/4). \sstitem ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, but is retained in order to allow applications to be linked with a graphics module which implements the interface used by AST V2.0. It is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. \sstitem ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which 3D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new 3D graphics system yourself and wish to provide your own arguments for linking with it. \sstitem ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. \sstitem ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D graphical output from the AST library is displayed via the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics package. By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output. } } \sstdiytopic{ SLALIB }{ The AST distribution includes a cut down subset of the C version of the SLALIB library written by Pat Wallace. This subset contains only the functions needed by the AST library. It is built as part of the process of building AST and is distributed under GPL (and is thus compatible with the AST license). Previous version of this script allowed AST applications to be linked against external SLALIB libraries (either Fortran or C) rather than the internal version. The current version of this script does not provide this option, and always uses the internal SLALIB library. However, for backward compatibility, this script still allows the \texttt{"} -fsla\texttt{"} and \texttt{"} -csla\texttt{"} flags (previously used for selecting which version of SLALIB to use) to be specified, but they will be ignored. } } \normalsize \cleardoublepage \section{\label{ss:memoryfunctions}AST Memory Management and Utility Functions} AST provides a memory management layer that can be used in place of system functions such as \texttt{malloc}, \texttt{free}, \texttt{realloc}, \emph{etc.} The AST replacements for these functions ( \texttt{\htmlref{astMalloc}{astMalloc}}, \texttt{\htmlref{astFree}{astFree}} and \texttt{\htmlref{astRealloc}{astRealloc}}) add extra information to each allocated memory block that allows AST to check the validity of supplied pointers. For example, this extra information allows \texttt{astFree} to detect if the supplied pointer has already been freed, and if so to issue an appropriate error message. The existence of this extra information is invisible to outside callers, and stored in a header block located just before the returned memory block. In addition to the standard functions, AST provides other memory management functions, such as: \begin{description} \item [\texttt{\htmlref{astStore}{astStore}}] - stores data in dynamically allocated memory, allocating the memory (or adjusting the size of previously allocated memory) to match the amount of data to be stored. \item [\texttt{\htmlref{astGrow}{astGrow}}] - allocates and expands memory to hold an adjustable-sized array. \item [\texttt{\htmlref{astAppendString}{astAppendString}}] - allocates and expands memory to hold a concatenated string. \end{description} Theses are just a few of the available utilities functions in the AST memory management layer. Prototypes for all AST memory management functions are included in the header file ``\texttt{ast.h}''. An important restriction on these functions is that pointers created by other memory management functions, such as the system version of \texttt{malloc} \emph{etc.}, should never supplied to an AST memory management function. Only pointers created by AST should be used by these functions. In addition to memory management functions, AST provides various other utility functions, such as a basic regular expression facility, and other string manipulation functions. These are also documented in this appendix. The AST memory management layer is implemented on top of the usual \texttt{malloc}, {tt free} and \texttt{realloc} functions. By default these will be the standard functions provided by . However, the facilities of the STARMEM package (included in the Starlink Software Collection) can be used to specify alternative functions to use. This requires that AST be configured using the ``--with-starmem'' option when it is built. The STARMEM package provides a wrapper for the standard malloc implementation that enables the user to switch malloc schemes at runtime by setting the STARMEM\_MALLOC environment variable. Currently allowed values for this variable are: \begin{description} \item [SYSTEM] - standard system malloc/free - the default \item [DL] - Doug Lea's malloc/free \item [GC] - Hans-Boehm Garbage Collection \end{description} \small \sstroutine{ astAppendString }{ Append a string to another string which grows dynamically }{ \sstdescription{ This function appends one string to another dynamically allocated string, extending the dynamic string as necessary to accommodate the new characters (plus the final null). } \sstsynopsis{ char $*$astAppendString( char $*$str1, int $*$nc, const char $*$str2 ) } \sstparameters{ \sstsubsection{ str1 }{ Pointer to the null-terminated dynamic string, whose memory has been allocated using an AST memory allocation function. If no space has yet been allocated for this string, a NULL pointer may be given and fresh space will be allocated by this function. } \sstsubsection{ nc }{ Pointer to an integer containing the number of characters in the dynamic string (excluding the final null). This is used to save repeated searching of this string to determine its length and it defines the point where the new string will be appended. Its value is updated by this function to include the extra characters appended. If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will be ignored and zero will be used. } \sstsubsection{ str2 }{ Pointer to a constant null-terminated string, a copy of which is to be appended to \texttt{"} str1\texttt{"} . } } \sstreturnedvalue{ \sstsubsection{ astAppendString() }{ A possibly new pointer to the dynamic string with the new string appended (its location in memory may have to change if it has to be extended, in which case the original memory is automatically freed by this function). When the string is no longer required, its memory should be freed using \htmlref{astFree}{astFree}. } } \sstnotes{ \sstitemlist{ \sstitem If this function is invoked with the global error status set or if it should fail for any reason, then the returned pointer will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be unchanged. } } } \sstroutine{ astAppendStringf }{ Append a string to another string, allowing printf format specifiers }{ \sstdescription{ This function appends one string to another dynamically allocated string, extending the dynamic string as necessary to accommodate the new characters (plus the final null). It is the same as \htmlref{astAppendString}{astAppendString}, except that the \texttt{"} str2\texttt{"} string ay include printf format specifiers. } \sstsynopsis{ char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... ) } \sstparameters{ \sstsubsection{ str1 }{ Pointer to the null-terminated dynamic string, whose memory has been allocated using an AST memory allocation function. If no space has yet been allocated for this string, a NULL pointer may be given and fresh space will be allocated by this function. } \sstsubsection{ nc }{ Pointer to an integer containing the number of characters in the dynamic string (excluding the final null). This is used to save repeated searching of this string to determine its length and it defines the point where the new string will be appended. Its value is updated by this function to include the extra characters appended. If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will be ignored and zero will be used. } \sstsubsection{ str2 }{ Pointer to a constant null-terminated string, a copy of which is to be appended to \texttt{"} str1\texttt{"} . It may contain format specifications such as used with the C \texttt{"} printf\texttt{"} family of functions. } \sstsubsection{ ... }{ Additional optional arguments (as used by e.g. \texttt{"} printf\texttt{"} ) which specify values which are to be substituted into the \texttt{"} str2\texttt{"} string in place of any format specifications. } } \sstreturnedvalue{ \sstsubsection{ astAppendString() }{ A possibly new pointer to the dynamic string with the new string appended (its location in memory may have to change if it has to be extended, in which case the original memory is automatically freed by this function). When the string is no longer required, its memory should be freed using \htmlref{astFree}{astFree}. } } \sstnotes{ \sstitemlist{ \sstitem If this function is invoked with the global error status set or if it should fail for any reason, then the returned pointer will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be unchanged. } } } \sstroutine{ astCalloc }{ Allocate and initialise memory }{ \sstdescription{ This function allocates memory in a similar manner to the standard C \texttt{"} calloc\texttt{"} function, but with improved security (against memory leaks, etc.) and with error reporting. It also fills the allocated memory with zeros. Like \htmlref{astMalloc}{astMalloc}, it allows zero-sized memory allocation (without error), resulting in a NULL returned pointer value. } \sstsynopsis{ void $*$astCalloc( size\_t nmemb, size\_t size ) } \sstparameters{ \sstsubsection{ nmemb }{ The number of array elements for which memory is to be allocated. } \sstsubsection{ size }{ The size of each array element, in bytes. } } \sstreturnedvalue{ \sstsubsection{ astCalloc() }{ If successful, the function returns a pointer to the start of the allocated memory region. If the size allocated is zero, this will be a NULL pointer. } } \sstnotes{ \sstitemlist{ \sstitem A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. } } } \sstroutine{ astChr2Double }{ read a double value from a string }{ \sstdescription{ This function reads a double from the supplied null-terminated string, ignoring leading and trailing white space. AST\_\_BAD is ereturned without error if the string is not a numerical value. } \sstsynopsis{ double astChr2Double( const char $*$str ) } \sstparameters{ \sstsubsection{ str }{ Pointer to the string. } } \sstreturnedvalue{ \sstsubsection{ astChr2Double() }{ The double value, or AST\_\_BAD. } } \sstnotes{ \sstitemlist{ \sstitem A value of AST\_\_BAD is returned if this function is invoked with the global error status set or if it should fail for any reason. } } } \sstroutine{ astChrCase }{ Convert a string to upper or lower case }{ \sstdescription{ This function converts a supplied string to upper or lower case, storing the result in a supplied buffer. The \htmlref{astStringCase}{astStringCase} function is similar, but stores the result in a dynamically allocated buffer. } \sstsynopsis{ void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status ) } \sstparameters{ \sstsubsection{ in }{ Pointer to the null terminated string to be converted. If this is NULL, the supplied contents of the \texttt{"} out\texttt{"} string are used as the input string. } \sstsubsection{ out }{ Pointer to the buffer to receive the converted string. The length of this buffer is given by \texttt{"} blen\texttt{"} . If NULL is supplied for \texttt{"} in\texttt{"} , then the supplied contents of \texttt{"} out\texttt{"} are converted and written back into \texttt{"} out\texttt{"} over-writing the supplied contents. } \sstsubsection{ upper }{ If non-zero, the string is converted to upper case. Otherwise it is converted to lower case. } \sstsubsection{ blen }{ The length of the output buffer. Ignored if \texttt{"} in\texttt{"} is NULL. No more than \texttt{"} blen - 1\texttt{"} characters will be copied from \texttt{"} in\texttt{"} to \texttt{"} out\texttt{"} , and a terminating null character will then be added. } } } \sstroutine{ astChrLen }{ Determine the used length of a string }{ \sstdescription{ This function returns the used length of a string. This excludes any trailing white space or non-printable characters (such as the trailing null character). } \sstsynopsis{ size\_t astChrLen( const char $*$string ) } \sstparameters{ \sstsubsection{ string }{ Pointer to the string. } } \sstreturnedvalue{ \sstsubsection{ astChrLen() }{ The number of characters in the supplied string, not including the trailing newline, and any trailing white-spaces or non-printable characters. } } } \sstroutine{ astChrMatch }{ Case insensitive string comparison }{ \sstdescription{ This function compares two null terminated strings for equality, discounting differences in case and any trailing white space in either string. } \sstsynopsis{ int astChrMatch( const char $*$str1, const char $*$str2 ) } \sstparameters{ \sstsubsection{ str1 }{ Pointer to the first string. } \sstsubsection{ str2 }{ Pointer to the second string. } } \sstreturnedvalue{ \sstsubsection{ astChrMatch() }{ Non-zero if the two strings match, otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned if this function is invoked with the global error status set or if it should fail for any reason. } } } \sstroutine{ astChrMatchN }{ Case insensitive string comparison of at most N characters }{ \sstdescription{ This function compares two null terminated strings for equality, discounting differences in case and any trailing white space in either string. No more than \texttt{"} n\texttt{"} characters are compared. } \sstsynopsis{ int astChrMatchN( const char $*$str1, const char $*$str2, size\_t n ) } \sstparameters{ \sstsubsection{ str1 }{ Pointer to the first string. } \sstsubsection{ str2 }{ Pointer to the second string. } \sstsubsection{ n }{ Maximum number of characters to compare. } } \sstreturnedvalue{ \sstsubsection{ astChrMatchN() }{ Non-zero if the two strings match, otherwise zero. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned if this function is invoked with the global error status set or if it should fail for any reason. } } } \sstroutine{ astChrSplit }{ Extract words from a supplied string }{ \sstdescription{ This function extracts all space-separated words form the supplied string and returns them in an array of dynamically allocated strings. } \sstsynopsis{ char $*$$*$astChrSplit\_( const char $*$str, int $*$n ) } \sstparameters{ \sstsubsection{ str }{ Pointer to the string to be split. } \sstsubsection{ n }{ Address of an int in which to return the number of words returned. } } \sstreturnedvalue{ \sstsubsection{ astChrSplit() }{ A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. Each element is a pointer to a dynamically allocated character string containing a word extracted from the supplied string. Each of these words will have no leading or trailing white space. } } \sstnotes{ \sstitemlist{ \sstitem A NULL pointer is returned if this function is invoked with the global error status set or if it should fail for any reason, or if the supplied string contains no words. } } } \sstroutine{ astChrSplitC }{ Split a string using a specified character delimiter }{ \sstdescription{ This function extracts all sub-strings separated by a given character from the supplied string and returns them in an array of dynamically allocated strings. The delimiter character itself is not included in the returned strings. Delimiter characters that are preceded by \texttt{"} $\backslash$\texttt{"} are not used as delimiters but are included in the returned word instead (without the \texttt{"} $\backslash$\texttt{"} ). } \sstsynopsis{ char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n ) } \sstparameters{ \sstsubsection{ str }{ Pointer to the string to be split. } \sstsubsection{ c }{ The delimiter character. } \sstsubsection{ n }{ Address of an int in which to return the number of words returned. } } \sstreturnedvalue{ \sstsubsection{ astChrSplitC() }{ A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. Each element is a pointer to a dynamically allocated character string containing a word extracted from the supplied string. } } \sstnotes{ \sstitemlist{ \sstitem A NULL pointer is returned if this function is invoked with the global error status set or if it should fail for any reason, or if the supplied string contains no words. } } } \sstroutine{ astChrSplitRE }{ Extract sub-strings matching a specified regular expression }{ \sstdescription{ This function compares the supplied string with the supplied regular expression. If they match, each section of the test string that corresponds to a parenthesised sub-string in the regular expression is copied and stored in the returned array. } \sstsynopsis{ char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n, const char $*$$*$matchend ) } \sstparameters{ \sstsubsection{ str }{ Pointer to the string to be split. } \sstsubsection{ regexp }{ The regular expression. See \texttt{"} Template Syntax:\texttt{"} in the \htmlref{astChrSub}{astChrSub} prologue. Note, this function differs from astChrSub in that any equals signs (=) in the regular expression are treated literally. } \sstsubsection{ n }{ Address of an int in which to return the number of sub-strings returned. } \sstsubsection{ matchend }{ A pointer to a location at which to return a pointer to the character that follows the last character within the supplied test string that matched any parenthesises sub-section of \texttt{"} regexp\texttt{"} . A NULL pointer is returned if no matches were found. A NULL pointer may be supplied if the location of the last matching character is not needed. } } \sstreturnedvalue{ \sstsubsection{ astChrSplitRE() }{ A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. Each element is a pointer to a dynamically allocated character string containing a sub-string extracted from the supplied string. The array itself, and the strings within it, should all be freed using \htmlref{astFree}{astFree} when no longer needed. } } \sstnotes{ \sstitemlist{ \sstitem If a parenthesised sub-string in the regular expression is matched by more than one sub-string within the test string, then only the first is returned. To return multiple matches, the regular expression should include multiple copies of the parenthesised sub-string (for instance, separated by \texttt{"} .$+$?\texttt{"} if the intervening string is immaterial). \sstitem A NULL pointer is returned if this function is invoked with the global error status set or if it should fail for any reason, or if the supplied string contains no words. } } } \sstroutine{ astChrSub }{ Performs substitutions on a supplied string }{ \sstdescription{ This function checks a supplied test string to see if it matches a supplied template. If it does, specified sub-sections of the test string may optionally be replaced by supplied substitution strings. The resulting string is returned. } \sstsynopsis{ char $*$astChrSub( const char $*$test, const char $*$pattern, const char $*$subs[], int nsub ) } \sstparameters{ \sstsubsection{ test }{ The string to be tested. } \sstsubsection{ pattern }{ The template string. See \texttt{"} Template Syntax:\texttt{"} below. } \sstsubsection{ subs }{ An array of strings that are to replace the sections of the test string that match each parenthesised sub-string in \texttt{"} pattern\texttt{"} . The first element of \texttt{"} subs\texttt{"} replaces the part of the test string that matches the first parenthesised sub-string in the template, etc. If \texttt{"} nsub\texttt{"} is zero, then the \texttt{"} subs\texttt{"} pointer is ignored. In this case, substitution strings may be specified by appended them to the end of the \texttt{"} pattern\texttt{"} string, separated by \texttt{"} =\texttt{"} characters. Note, if you need to include a literal \texttt{"} =\texttt{"} character in the pattern, precede it by an escape \texttt{"} $\backslash$\texttt{"} character. } \sstsubsection{ nsub }{ The number of substitution strings supplied in array \texttt{"} subs\texttt{"} . } } \sstreturnedvalue{ \sstsubsection{ astChrSub() }{ A pointer to a dynamically allocated string holding the result of the substitutions, or NULL if the test string does not match the template string. This string should be freed using \htmlref{astFree}{astFree} when no longer needed. If no substituions are specified then a copy of the test string is returned if it matches the template. } } \sstnotes{ \sstitemlist{ \sstitem A NULL pointer is returned if this function is invoked with the global error status set or if it should fail for any reason, or if the supplied test string does not match the template. } } \sstdiytopic{ Template Syntax }{ The template syntax is a minimal form of regular expression, The quantifiers allowed are \texttt{"} $*$\texttt{"} , \texttt{"} ?\texttt{"} , \texttt{"} $+$\texttt{"} , \texttt{"} \{n\}\texttt{"} , \texttt{"} $*$?\texttt{"} and \texttt{"} $+$?\texttt{"} (the last two are non-greedy - they match the minimum length possible that still gives an overall match to the template). The only constraints allowed are \texttt{"} $\wedge$\texttt{"} and \texttt{"} \$\texttt{"} . The following atoms are allowed: \sstitemlist{ \sstitem [chars]: Matches any of the specified characters. \sstitem [$\wedge$chars]: Matches anything but the specified characters. \sstitem .: Matches any single character. \sstitem x: Matches the character x so long as x has no other significance. \sstitem $\backslash$x: Always matches the character x (except for [dDsSwW]). \sstitem $\backslash$d: Matches a single digit. \sstitem $\backslash$D: Matches anything but a single digit. \sstitem $\backslash$w: Matches any alphanumeric character, and \texttt{"} \_\texttt{"} . \sstitem $\backslash$W: Matches anything but alphanumeric characters, and \texttt{"} \_\texttt{"} . \sstitem $\backslash$s: Matches white space. \sstitem $\backslash$S: Matches anything but white space. } Note, minus signs (\texttt{"} -\texttt{"} ) within brackets have no special significance, so ranges of characters must be specified explicitly. Multiple template strings can be concatenated, using the \texttt{"} $|$\texttt{"} character to separate them. The test string is compared against each one in turn until a match is found. Parentheses are used within each template to identify sub-strings that are to be replaced by the strings supplied in \texttt{"} sub\texttt{"} . If \texttt{"} nsub\texttt{"} is supplied as zero, then substitution strings may be specified by appended them to the end of the \texttt{"} pattern\texttt{"} string, separated by \texttt{"} =\texttt{"} characters. If \texttt{"} nsub\texttt{"} is not zero, then any substitution strings appended to the end of \texttt{"} pattern\texttt{"} are ignored. Each element of \texttt{"} subs\texttt{"} may contain a reference to a token of the form \texttt{"} \$1\texttt{"} , \texttt{"} \$2\texttt{"} , etc. The \texttt{"} \$1\texttt{"} token will be replaced by the part of the test string that matched the first parenthesised sub-string in \texttt{"} pattern\texttt{"} . The \texttt{"} \$2\texttt{"} token will be replaced by the part of the test string that matched the second parenthesised sub-string in \texttt{"} pattern\texttt{"} , etc. } } \sstroutine{ astChrTrunc }{ Terminate a string to exclude trailing spaces }{ \sstdescription{ This function pokes a null character into the supplied string to remove any trailing spaces. } \sstsynopsis{ void astChrTrunc( char $*$text ) } \sstparameters{ \sstsubsection{ text }{ The string to be truncated. } } } \sstroutine{ astFree }{ Free previously allocated memory }{ \sstdescription{ This function frees memory that has previouly been dynamically allocated using one of the AST memory function. } \sstsynopsis{ void $*$astFree( void $*$ptr ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to previously allocated memory. An error will result if the memory has not previously been allocated by another function in this module. However, a NULL pointer value is accepted (without error) as indicating that no memory has yet been allocated, so that no action is required. } } \sstreturnedvalue{ \sstsubsection{ astFree() }{ Always returns a NULL pointer. } } } \sstroutine{ astFreeDouble }{ Free previously double allocated memory }{ \sstdescription{ This function frees memory that has previouly been dynamically allocated using one of the AST memory function. It assumes that the supplied pointer is a pointer to an array of pointers. Each of these pointers is first freed, and then the supplied pointer is freed. Note, this routine should not be used with arrays allocated by \htmlref{astGrow}{astGrow} since astGrow over-allocates and so there may be non-initialised pointers at the end of the array. } \sstsynopsis{ void $*$astFreeDouble( void $*$ptr ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to previously allocated memory. An error will result if the memory has not previously been allocated by another function in this module. However, a NULL pointer value is accepted (without error) as indicating that no memory has yet been allocated, so that no action is required. } } \sstreturnedvalue{ \sstsubsection{ astFreeDouble() }{ Always returns a NULL pointer. } } } \sstroutine{ astGrow }{ Allocate memory for an adjustable array }{ \sstdescription{ This function allocates memory in which to store an array of data whose eventual size is unknown. It should be invoked whenever a new array size is determined and will appropriately increase the amount of memory allocated when necessary. In general, it will over-allocate in anticipation of future growth so that the amount of memory does not need adjusting on every invocation. } \sstsynopsis{ void $*$astGrow( void $*$ptr, int n, size\_t size ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to previously allocated memory (or NULL if none has yet been allocated). } \sstsubsection{ n }{ Number of array elements to be stored (may be zero). } \sstsubsection{ size }{ The size of each array element. } } \sstreturnedvalue{ \sstsubsection{ astGrow() }{ If the memory was allocated successfully, a pointer to the start of the possibly new memory region is returned (this may be the same as the original pointer). } } \sstnotes{ \sstitemlist{ \sstitem When new memory is allocated, the existing contents are preserved. \sstitem This function does not free memory once it is allocated, so the size allocated grows to accommodate the maximum size of the array (or \texttt{"} high water mark\texttt{"} ). Other memory handling routines may be used to free the memory (or alter its size) if necessary. \sstitem If this function is invoked with the global error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. } } } \sstroutine{ astIsDynamic }{ Returns a flag indicating if memory was allocated dynamically }{ \sstdescription{ This function takes a pointer to a region of memory and tests if the memory has previously been dynamically allocated using other functions from this module. It does this by checking for the presence of a \texttt{"} magic\texttt{"} number in the header which precedes the allocated memory. If the magic number is not present (or the pointer is invalid for any other reason), zero is returned. Otherwise 1 is returned. } \sstsynopsis{ int astIsDynamic\_( const void $*$ptr ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to test. } } \sstreturnedvalue{ \sstsubsection{ astIsDynamic() }{ Non-zero if the memory was allocated dynamically. Zero is returned if the supplied pointer is NULL. } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned if this function is invoked with the global error status set, or if it fails for any reason. } } } \sstroutine{ astMalloc }{ Allocate memory }{ \sstdescription{ This function allocates memory in a similar manner to the standard C \texttt{"} malloc\texttt{"} function, but with improved security (against memory leaks, etc.) and with error reporting. It also allows zero-sized memory allocation (without error), resulting in a NULL returned pointer value. } \sstsynopsis{ void $*$astMalloc( size\_t size ) } \sstparameters{ \sstsubsection{ size }{ The size of the memory region required (may be zero). } } \sstreturnedvalue{ \sstsubsection{ astMalloc() }{ If successful, the function returns a pointer to the start of the allocated memory region. If the size allocated is zero, this will be a NULL pointer. } } \sstnotes{ \sstitemlist{ \sstitem A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. } } } \sstroutine{ astMemCaching }{ Controls whether allocated but unused memory is cached in this module }{ \sstdescription{ This function sets a flag indicating if allocated but unused memory should be cached or not. It also returns the original value of the flag. If caching is switched on or off as a result of this call, then the current contents of the cache are discarded. Note, each thread has a separate cache. Calling this function affects only the currently executing thread. } \sstsynopsis{ int astMemCaching( int newval ) } \sstparameters{ \sstsubsection{ newval }{ The new value for the MemoryCaching tuning parameter (see \htmlref{astTune}{astTune} in objectc.c). If AST\_\_TUNULL is supplied, the current value is left unchanged. } } \sstreturnedvalue{ \sstsubsection{ astMemCaching() }{ The original value of the MemoryCaching tuning parameter. } } } \sstroutine{ astRealloc }{ Change the size of a dynamically allocated region of memory }{ \sstdescription{ This function changes the size of a dynamically allocated region of memory, preserving its contents up to the minimum of the old and new sizes. This may involve copying the contents to a new location, so a new pointer is returned (and the old memory freed if necessary). This function is similar to the standard C \texttt{"} realloc\texttt{"} function except that it provides better security against programming errors and also supports the allocation of zero-size memory regions (indicated by a NULL pointer). } \sstsynopsis{ void $*$astRealloc( void $*$ptr, size\_t size ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to previously allocated memory (or NULL if the previous size of the allocated memory was zero). } \sstsubsection{ size }{ New size required for the memory region. This may be zero, in which case a NULL pointer is returned (no error results). It should not be negative. } } \sstreturnedvalue{ \sstsubsection{ astRealloc() }{ If the memory was reallocated successfully, a pointer to the start of the new memory region is returned (this may be the same as the original pointer). If size was given as zero, a NULL pointer is returned. } } \sstnotes{ \sstitemlist{ \sstitem If this function is invoked with the error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. Note that this behaviour differs from that of the standard C \texttt{"} realloc\texttt{"} function which returns NULL if it fails. } } } \sstroutine{ astRemoveLeadingBlanks }{ Remove any leading white space from a string }{ \sstdescription{ This function moves characters in the supplied string to the left in order to remove any leading white space. } \sstsynopsis{ void astRemoveLeadingBlanks( char $*$string ) } \sstparameters{ \sstsubsection{ string }{ Pointer to the string. } } } \sstroutine{ astSizeOf }{ Determine the size of a dynamically allocated region of memory }{ \sstdescription{ This function returns the size of a region of dynamically allocated memory. } \sstsynopsis{ size\_t astSizeOf( const void $*$ptr ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to dynamically allocated memory (or NULL if the size of the allocated memory was zero). } } \sstreturnedvalue{ \sstsubsection{ astSizeOf() }{ The allocated size. This will be zero if a NULL pointer was supplied (no error will result). } } \sstnotes{ \sstitemlist{ \sstitem A value of zero is returned if this function is invoked with the global error status set, or if it fails for any reason. } } } \sstroutine{ astStore }{ Store data in dynamically allocated memory }{ \sstdescription{ This function stores data in dynamically allocated memory, allocating the memory (or adjusting the size of previously allocated memory) to match the amount of data to be stored. } \sstsynopsis{ void $*$astStore( void $*$ptr, const void $*$data, size\_t size ) } \sstparameters{ \sstsubsection{ ptr }{ Pointer to previously allocated memory (or NULL if none has yet been allocated). } \sstsubsection{ data }{ Pointer to the start of the data to be stored. This may be given as NULL if there are no data, in which case it will be ignored and this function behaves like \htmlref{astRealloc}{astRealloc}, preserving the existing memory contents. } \sstsubsection{ size }{ The total size of the data to be stored and/or the size of memory to be allocated. This may be zero, in which case the data parameter is ignored, any previously-allocated memory is freed and a NULL pointer is returned. } } \sstreturnedvalue{ \sstsubsection{ astStore() }{ If the data were stored successfully, a pointer to the start of the possibly new memory region is returned (this may be the same as the original pointer). If size was given as zero, a NULL pointer is returned. } } \sstnotes{ \sstitemlist{ \sstitem This is a convenience function for use when storing data of arbitrary size in memory which is to be allocated dynamically. It is appropriate when the size of the data will not change frequently because the size of the memory region will be adjusted to fit the data on every invocation. \sstitem If this function is invoked with the error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. } } } \sstroutine{ astString }{ Create a C string from an array of characters }{ \sstdescription{ This function allocates memory to hold a C string and fills the string with the sequence of characters supplied. It then terminates the string with a null character and returns a pointer to its start. The memory used for the string may later be de-allocated using \htmlref{astFree}{astFree}. This function is intended for constructing null terminated C strings from arrays of characters which are not null terminated, such as when importing a character argument from a Fortran 77 program. } \sstsynopsis{ char $*$astString( const char $*$chars, int nchars ) } \sstparameters{ \sstsubsection{ chars }{ Pointer to the array of characters to be used to fill the string. } \sstsubsection{ nchars }{ The number of characters in the array (zero or more). } } \sstreturnedvalue{ \sstsubsection{ astString() }{ If successful, the function returns a pointer to the start of the allocated string. If the number of characters is zero, a zero-length string is still allocated and a pointer to it is returned. } } \sstnotes{ \sstitemlist{ \sstitem A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. } } } \sstroutine{ astStringArray }{ Create an array of C strings from an array of characters }{ \sstdescription{ This function turns an array of fixed-length character data into a dynamicllay allocated array of null-terminated C strings with an index array that may be used to access them. The array of character data supplied is assumed to hold \texttt{"} nel\texttt{"} adjacent fixed-length strings (without terminating nulls), each of length \texttt{"} len\texttt{"} characters. This function allocates memory and creates a null-terminated copy of each of these strings. It also creates an array of \texttt{"} nel\texttt{"} pointers which point at the start of each of these new strings. A pointer to this index array is returned. The memory used is allocated in a single block and should later be de-allocated using \htmlref{astFree}{astFree}. } \sstsynopsis{ char $*$$*$astStringArray( const char $*$chars, int nel, int len ) } \sstparameters{ \sstsubsection{ chars }{ Pointer to the array of input characters. The number of characters in this array should be at least equal to (nel $*$ len). } \sstsubsection{ nel }{ The number of fixed-length strings in the input character array. This may be zero but should not be negative. } \sstsubsection{ len }{ The number of characters in each fixed-length input string. This may be zero but should not be negative. } } \sstreturnedvalue{ \sstsubsection{ astStringArray() }{ A pointer to the start of the index array, which contains \texttt{"} nel\texttt{"} pointers pointing at the start of each null-terminated output string. The returned pointer should be passed to astFree to de-allocate the memory used when it is no longer required. This will free both the index array and the memory used by the strings it points at. } } \sstnotes{ \sstitemlist{ \sstitem A NULL pointer will also be returned if the value of \texttt{"} nel\texttt{"} is zero, in which case no memory is allocated. \sstitem A pointer value of NULL will also be returned if this function is invoked with the global error status set or if it fails for any reason. } } } \sstroutine{ astStringCase }{ Convert a string to upper or lower case }{ \sstdescription{ This function converts a supplied string to upper or lower case, storing the result in dynamically allocated memory. The \htmlref{astChrCase}{astChrCase} function is similar, but stores the result in a supplied buffer. } \sstsynopsis{ char $*$astStringCase( const char string, int upper ) } \sstparameters{ \sstsubsection{ string }{ Pointer to the null terminated string to be converted. } \sstsubsection{ upper }{ If non-zero, the string is converted to upper case. Otherwise it is converted to lower case. } } \sstreturnedvalue{ \sstsubsection{ astStringCase() }{ If successful, the function returns a pointer to the start of the allocated string. The returned memory should be freed using \htmlref{astFree}{astFree} when no longer needed. } } \sstnotes{ \sstitemlist{ \sstitem A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. } } } \normalsize \newpage \section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage} This appendix gives details of the \htmlref{FitsChan}{FitsChan} class implementation of the conventions described in the FITS-WCS papers available at \url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan has the value ``FITS-WCS'' (whether set explicitly or defaulted). It should always be possible for a \htmlref{FrameSet}{FrameSet} to be read (using the \htmlref{astRead}{astRead} function) from a FitsChan containing a header which conforms to these conventions. However, only those FrameSets which are compatible with the FITS-WCS model can be \emph{written} to a FitsChan using the \htmlref{astWrite}{astWrite} function. For instance, if the current \htmlref{Frame}{Frame} of a FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{MathMap} then the FrameSet will no longer be compatible with the FITS-WCS model, and so will not be written out successfully to a FitsChan. The following sub-sections describe the details of the implementation of each of the first four FITS-WCS papers. Here, the term ``pixel axes'' is used to refer to the FITS pixel coordinates (i.e. the centre of the first image pixel has a value 1.0 on each pixel axis); the term ``IWC axes'' is used to refer to the axes of the Intermediate World Coordinate system; and the term ``WCS axes'' is used to refer to the axes of the final physical coordinate system described by the CTYPE\emph{i} keywords. \subsection{Paper I - General Linear Coordinates} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} keyword values within the FitsChan do not conform to the conventions described in later papers, in which case the axes are assumed to be linear. When writing a FrameSet to a FitsChan, these conventions are used for axes which are described by a simple \htmlref{Frame}{Frame} (\emph{i.e.} not a \htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}). \htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword defined by FITS-WCS paper I. \begin{table}[htbp] \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS Frame - only written if different to NAXIS.} \fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference Point'' below).} \fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always written (see ``Choice of Reference Point'' below).} \fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is set to zero.} \fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only written in FITS-AIPS and FITS-AIPS++ encodings.} \fitskey{CTYPE\emph{ia}}{Used to choose the class and attributes of the WCS Frame, and to create the pixel to WCS Mapping (note, ``STOKES'' and ``COMPLEX'' axes are treated as unknown linear axes).}{Always written (see ``Use and Choice of CTYPE keywords'' below).} \fitskey{CUNIT\emph{ia}}{Used to set the Units attributes of the WCS Frame.}{Only written if the Units attribute of the WCS Frame has been set explicitly. If so, the Units value for each axis is used as the CUNIT value.} \fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to zero.} \fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to a non-zero value.} \fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes are linear.} \fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.} \fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{Domain} attribute of the WCS Frame.}{Only written if the Domain attribute of the WCS Frame has been set explicitly. If so, the Domain value is used as the WCSNAME value.} \fitskey{CRDER\emph{ia}}{Ignored.}{Not used.} \fitskey{CSYER\emph{ia}}{Ignored.}{Not used.} \hline \end{tabular} \vspace{3.mm} \caption{Use of FITS-WCS Paper I keywords} \label{tab:fitspaper1} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan}, success depends on the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the WCS Frame being linear. The write operation will fail if this is not the case. \subsubsection{Use and Choice of CTYPE\emph{i} keywords} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from the CNAME\emph{i} keywords, if present in the header. Otherwise they are set from the CTYPE\emph{i} comments strings in the header, so long as each axis has a unique non-blank comment. Otherwise, the Label attributes are set to the CTYPE\emph{i} values. The above procedure is over-ridden if the axis types conform to the conventions described in paper II or III, as described below. When writing a FrameSet to a FitsChan, each CTYPE\emph{i} value is set to the value of the Symbol attribute of the corresponding axis in the Frame being written. If a value has been set explicitly for the axis Label attribute, it is used as the axis comment (except that any existing comments in the FitsChan take precedence if the keyword value has not changed). The above procedure is over-ridden if the Frame is a \htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which case the CTYPE\emph{i} value is derived from the \htmlref{System}{System} attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping} according to the conventions of papers II and III, as described below. \subsubsection{Choice of Reference Point} When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, the pixel coordinates of the reference point for linear axes (i.e. the CRPIX\emph{j} values) are chosen as follows: \begin{itemize} \item If the FrameSet is being written to a FitsChan which previously contained a set of axis descriptions with the same identifying letter, then the previous CRVAL\emph{j}values are converted into the coordinate system of the \htmlref{Frame}{Frame} being written (if possible). These values are then transformed into the pixel Frame, and the closest integer pixel values are used as the CRPIX keywords. \item If the above step could not be performed for any reason, the central pixel is used as the reference point. This requires the image dimensions to be present in the FitsChan in the form of a set of NAXIS\emph{j} keyword values. \item If both the above two steps failed for any axis, then the pixel reference position is set to a value of 1.0 on the pixel axis. \end{itemize} The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding CRVAL\emph{j}values. Again, the above procedure is over-ridden if the Frame is a \htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which case the conventions of papers II and III are used as described below. \subsubsection{Choice of Axis Ordering} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current \htmlref{Frame}{Frame} of the resulting FrameSet corresponds to axis $i$ in the FITS header. When writing a FrameSet to a FitsChan, the axis ordering for the FITS header is chosen to make the CD\emph{i\_j} or PC\emph{i\_j} matrix predominately diagonal. This means that the axis numbering in the FITS header will not necessarily be the same as that in the AST Frame. \subsubsection{Alternate Axis Descriptions} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions, each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added to the final FrameSet, connected via an appropriate \htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{Ident} attribute of the Frame is set to hold the single alphabetical character which is used to identify the set of axis descriptions within the FITS header (a single space is used for the primary axis descriptions). When writing a FrameSet to a FitsChan, it is assumed that the base Frame represents pixel coordinates, and the current Frame represents the primary axis descriptions. If there are any other Frames present in the FrameSet, an attempt is made to create a complete set of ``alternate'' set of keywords describing each additional Frame. The first character in the Ident attribute of the Frame is used as the single character descriptor to be appended to the keyword, with the proviso that a given character can only be used once. If a second Frame is found with an Ident attribute which has already been used, its Ident attribute is ignored and the next free character is used instead. Note, failure to write a set of alternate axis descriptions does not result in failure of the entire write operation: the primary axis descriptions are still written, together with any other alternate axis descriptions which can be produced successfully. \subsection{Paper II - Celestial Coordinates} These conventions are used when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i} values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame}. \htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper II. \begin{table}[htbp] \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types listed in paper II are supported (note, ``CUBEFACE'' axes are treated as unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar HEALPix) are supported.}{Determined by the \htmlref{System}{System} attribute of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the \htmlref{WcsMap}{WcsMap} within the FrameSet.} \fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.} \fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values are stored as attributes of a WcsMap within this Mapping).}{Values are obtained from the WcsMap in the pixel to WCS Mapping.} \fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also stored as a \htmlref{PVi\_m}{PVi\_m} attribute for the longitude axis of the WcsMap.}{Only written if not equal to the default value defined in paper II (see ``Choice of LONPOLE/LATPOLE'' below).} \fitskey{LATPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also stored as a PV attribute for the longitude axis of the WcsMap.}{Only written if not equal to the default value defined in paper II (see ``Choice of LONPOLE/LATPOLE'' below).} \fitskey{RADESYS\emph{a}}{Used to set the attributes of the SkyFrame. All values supported except that ecliptic coordinates are currently always assumed to be FK5.}{Always written. Determined by the System attribute of the SkyFrame.} \fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of the SkyFrame.} \fitskey{EPOCH}{Used to set the Equinox attribute of the SkyFrame.}{Only written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute of the SkyFrame.} \fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{Epoch} attribute of the SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on RADESYS and EQUINOX is used if used if DATE-OBS is not present either.}{Determined by the Epoch attribute of the SkyFrame. Only written if this attribute has been set to an explicit value (in which case DATE-OBS is also written).} \hline \end{tabular} \vspace{3.mm} \caption{Use of FITS-WCS Paper II keywords} \label{tab:fitspaper2} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a \htmlref{FitsChan}{FitsChan}, success depends on the following conditions being met: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}. \item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear. \item The Mapping after the WcsMap (\emph{i.e.} from native spherical to celestial coordinates) is a spherical rotation for the celestial axes, and linear for any other axes. \item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan, and the longitude and latitude axes are separable. In this case the Mapping will be described by a pair of 1-dimensional look-up tables, using the ``-TAB'' algorithm described in FITS-WCS paper III. \end{enumerate} If none of the above conditions hold, the write operation will be unsuccessful. \subsubsection{Choice of LONPOLE/LATPOLE} When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, the choice of LONPOLE and LATPOLE values is determined as follows: \begin{enumerate} \item If the projection represented by the \htmlref{WcsMap}{WcsMap} is azimuthal, then any values set for attributes ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis) within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a FrameSet from a FITS-WCS header results in the original LONPOLE and LATPOLE values being stored within a WcsMap within the FrameSet. Consequently, if a FrameSet is read from a FITS-WCS header and it is subsequently written out to a new FITS-WCS header, the original LONPOLE and LATPOLE values will usually be used in the new header (the exception being if the WcsMap has been explicitly modified before being written out again). Any extra rotation of the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is possible only if the projection is azimuthal). \item If the projection represented by the WcsMap is azimuthal but no values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' attributes within the WcsMap, then the default LONPOLE and LATPOLE values are used. This results in no LONPOLE or LATPOLE keywords being stored in the header since default values are never stored. Any extra rotation of the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is possible only if the projection is azimuthal). \item If the projection represented by the WcsMap is not azimuthal, then the values of LONPOLE and LATPOLE are found by transforming the coordinates of the celestial north pole (\emph{i.e} longitude zero, latitude $+\pi/2$) into native spherical coordinates using the inverse of the \htmlref{Mapping}{Mapping} which follows the WcsMap. \end{enumerate} \subsubsection{User Defined Fiducial Points} When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis ``\emph{i}'') are used to indicate a user-defined fiducial point as described in section 2.5 of paper II. This results in a shift of IWC origin being applied \emph{before} the \htmlref{WcsMap}{WcsMap} which converts IWC into native spherical coordinates. The values of these projection parameters, if supplied, are stored as the corresponding \htmlref{PVi\_m}{PVi\_m} attributes of the WcsMap. When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap determine the native coordinates of the fiducial point (the fixed defaults for each projection described in paper II are used if the PV attributes of the WcsMap have not been assigned a value). The corresponding celestial coordinates are used as the CRVAL\emph{i} keywords and the corresponding pixel coordinates as the CRPIX\emph{j} keywords. \subsubsection{Common Non-Standard Features} A collection of common non-standard features are supported when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, in addition to those embodied within the available encodings of the FitsChan class. These are translated into the equivalent standard features before being used to create a FrameSet. Note, the reverse operation is never performed: it is not possible to produce non-standard features when writing a FrameSet to a FitsChan (other than those embodied in the available encodings of the FitsChan class). The supported non-standard features include: \begin{itemize} \item EQUINOX keywords with string values equal to a date preceded by the letter B or J (\emph{e.g.} ``B1995.0''). \item EQUINOX or EPOCH keywords with value zero (these are converted to B1950). \item The IRAF ``ZPX'' projection is represented by a \htmlref{WcsMap}{WcsMap} with type of AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn} keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic ZPN projection by including ``lngcor'' or ``latcor'' terms. These are supported if they use half cross-terms, in either simple or Chebyshev representation. \item The IRAF ``TNX'' projection is represented by a WcsMap with type of AST\_\_TPN (a distorted TAN projection retained within the WcsMap class from an early draft of the FITS-WCS paper II). Projection parameter values are read from any WAT\emph{i\_nnn} keywords, and corresponding PV attributes are set in the WcsMap. If the TNX projection cannot be converted exactly into an AST\_\_TPN projection, ASTWARN keywords are added to the FitsChan containing a warning message (but only if the \htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently, TNX projections that use half cross-terms, in either simple or Chebyshev representation, are supported. \item ``QV'' parameters for TAN projections (as produced by \xref{AUTOASTROM}{sun242}{} \footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}} are renamed to the equivalent ``PV'' parameters. \item TAN projections that have associated ``PV'' parameters on the latitude axis are converted to the corresponding TPN (distorted TAN) projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute of the FitsChan class. \end{itemize} \subsection{Paper III - Spectral Coordinates} These conventions are used when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which includes appropriate CTYPE\emph{i} values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}. \htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper III. \begin{table}[htbp] \begin{footnotesize} \begin{tabular}{|l|p{2.5in}|p{2.5in}|} \hline \multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} & \multicolumn{1}{c|}{\textbf{Write}} \\ \hline \fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types listed in paper III are supported algorithm (the ``-LOG'' algorithm may also be applied to non-spectral linear axes; the ``-TAB'' algorithm requires the \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the SpecFrame and the nature of the pixel to SpecFrame \htmlref{Mapping}{Mapping}.} \fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of the SpecFrame (note, SpecFrames always have an ``active'' Units attribute (see \htmlref{astSetActiveUnit}{astSetActiveUnit}).}{Always written.} \fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values are stored as attributes of a \htmlref{GrismMap}{GrismMap}).} {Set from the attributes of the GrismMap, if present, and if set explicitly.} \fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame (all systems are supported except CMBDIPOL).} {Set from the StdOfRest attribute of the SpecFrame, but only if it has been set explicitly.} \fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.} \fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame (the observers height above sea level is ignored).}{Set from the ObsLon and ObsLat attributes of the Frame, if they have been set explicitly (it is assumed that the observer is at sea level).} \fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has been set explicitly.} \fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the SpecFrame (all systems are supported except CMBDIPOL).} {Set from the SourceVRF attribute of the SpecFrame.} \fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{SourceVel} attribute of the SpecFrame (the SourceVRF attribute is first set to the system indicated by the SSYSSRC keyword, and the ZSOURCE value is then converted to an apparent radial velocity and stored as the SourceVel attribute).} {Set from the SourceVel attribute of the SpecFrame, if it has been set explicitly (the SourceVel value is first converted from apparent radial velocity to redshift).} \fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the SpecFrame that define the standard of rest and the observers position.} \fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{RestFreq} attribute of the SpecFrame.}{Set from the RestFreq attribute of the SpecFrame, but only if the System attribute is not set to ``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set explicitly.} \fitskey{RESTWAV\emph{a}}{Used to set the RestFreq attribute of the SpecFrame (after conversion from wavelength to frequency).} {Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the System attribute is set to ``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set explicitly.} \fitskey{CNAME\emph{ia}}{Used to set the Label attributes of the WCS Frame keywords.}{Set from the Label attributes of the WCS Frame, if they have been set explicitly.} \hline \end{tabular} \end{footnotesize} \vspace{3.mm} \caption{Use of FITS-WCS Paper III keywords} \label{tab:fitspaper3} \end{table} \subsubsection{Requirements for a Successful Write Operation} When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a \htmlref{FitsChan}{FitsChan}, the write operation is successful only if the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame in the FrameSet) to the SpecFrame satisfies one of the following conditions: \begin{enumerate} \item It is linear. \item It is logarithmic. \item It is linear if the SpecFrame were to be re-mapped into one of the other spectral systems supported by FITS-WCS paper III. \item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from pixel coordinates to grism parameter) is linear, and the Mapping after the GrismMap is either null or represents a change of spectral system from wavelength (air or vacuum) to one of the supported spectral systems. \item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan. \end{enumerate} If none of the above conditions hold, the write operation will be unsuccessful. Note, if the FitsChan's TabOK attribute is set to a positive non-zero value then any Mapping that does not meet any of the earlier conditions will be written out as a look-up table, using the ``-TAB'' algorithm described in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or negative in the FitsChan, then the write operation will be unsuccessful unless one of the eaerlier conditions is met.\footnote{If the -TAB algorithm is used, the positive value of the TabOK attribute is used as the table version number (the EXTVER header) in the associated FITS binary table.} \subsubsection{Common Non-Standard Features} The following non-standard features are supported when reading spectral axes from a \htmlref{FitsChan}{FitsChan}: \begin{itemize} \item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes (specified in early drafts of paper III) to the corresponding ``-X2P'' form. \item Conversion of ``RESTFREQ'' to ``RESTFRQ'' \end{itemize} \subsection{Paper IV - Coordinate Distortions} This paper proposes that an additional 4 character code be appended to the end of the CTYPE\emph{i} keyword to specify the nature of any distortion away from the basic algorithm described by the first 8 characters of the CTYPE\emph{i} value. Currently AST ignores all such codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} (except for the ``-SIP'' code defined by the Spitzer Space Telescope project - see below). This means that a FrameSet can still be read from such headers, but the \htmlref{Mapping}{Mapping} which gives the WCS position associated with a given pixel position will reflect only the basic algorithm and will not include the effects of the distortion. If such a FrameSet is then written out to a FitsChan, the resulting CTYPE\emph{i} keywords will include no distortion code. \subsubsection{The ``-SIP'' distortion code} The Spitzer Space Telescope project (\url{http://www.spitzer.caltech.edu/}) has developed its own system for encoding 2-dimensional image distortion within a FITS header, based on the proposals of paper IV. A description of this system is available in \url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}. In this system, the presence of distortion is indicated by appending the distortion code ``-SIP'' to the CTYPE\emph{i} keyword values for the celestial axes. The distortion takes the form of a polynomial function which is applied to the pixel coordinates, after subtraction of the CRPIX\emph{j} values. This system is a strictly 2 dimensional system. When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which includes the ``-SIP'' distortion code, AST assumes that it is only applied to the first 2 WCS axes in a FITS header (i.e. CTYPE1 and CTYPE2). If the ``-SIP'' distortion code is attached to other axes, it will be ignored. The distortion itself is represented by a \htmlref{PolyMap}{PolyMap} within the resulting FrameSet. If a FrameSet is read from a FitsChan which includes ``-SIP'' distortion, and an attempt is then made to write this FrameSet out to a FitsChan, the write operation will fail unless the distortion is insignificant (\emph{i.e.} is so small that the tests for linearity built into AST are passed). In this case, no distortion code will be appended to the resulting CTYPE\emph{i} keyword values. \newpage \section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes} \subsection{Changes Introduced in V1.1} The following describes the most significant changes which occurred in the AST library between versions V1.0 and V1.1 (not the most recent version): \begin{enumerate} \item A new ``How To\ldots'' section (\secref{ss:howto}) has been added to this document. It contains simple recipies for performing commonly-required operations using AST. \item A new \htmlref{astUnformat}{astUnformat} function has been provided to read formatted coordinate values for the axes of a \htmlref{Frame}{Frame} (\secref{ss:unformattingaxisvalues}). In essence, this function is the inverse of \htmlref{astFormat}{astFormat}. It may be used to decode user-supplied formatted values representing coordinates, turning them into numerical values for processing. Celestial coordinates may also be read using this function (\secref{ss:unformattingskyaxisvalues}) and free-format input is supported. \item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting celestial coordinate values now allows the degrees/hours field to be omitted, so that celestial coordinates may be given in (\emph{e.g.}) arc-minutes and/or arc-seconds (\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours field is no longer included by default. A new ``t'' format specifier has been introduced (see the Format attribute) to allow minutes and/or seconds of time to be specified if required. \item A new function \htmlref{astMapBox}{astMapBox} has been introduced. This allows you to find the extent of a ``bounding box'' which just encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to calculate the size which an image would have if it were transformed by the Mapping. \item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced (\secref{ss:intramaps}). This is a specialised form of Mapping which encapsulates a privately-defined coordinate transformation function (\emph{e.g.}\ written in C) so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation. \item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically preserved whenever changes are made to any attributes which affect the current Frame (either by setting or clearing their values). This is accomplished by appropriately re-mapping the current Frame to account for any change to the coordinate system which it represents (\secref{ss:framesetintegrity}). \item The internal structure of a FrameSet is now automatically tidied to eliminate redundant nodes whenever any of its Frames is removed or re-mapped. Automatic simplification of any compound Mappings which result may also occur. The effect of this change is to prevent the accumulation of unnecessary structure in FrameSets which are repeatedly modified. \item Some improvements have been made to the algorithms for simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. \item The textual representation used for some Objects (\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed slightly, but remains compatible with earlier versions of AST. \item Interfaces to the internal functions and macros used by AST for handling memory and error conditions are now provided \emph{via} the ``ast.h'' header file. This is for the benefit of those writing (\emph{e.g.}) new graphics interfaces for AST. \item A problem has been fixed which could result when using \htmlref{astRead}{astRead} to read FITS headers in which the CDELT value is zero. Previously, this could produce a Mapping whose inverse transformation was not defined and this could unnecessarily restrict the use to which it could be put. The problem has been overcome by supplying a suitable small CDELT value for FITS axes which have only a single pixel. \item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap} to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of a compound Mapping which is being simplified using astSimplify. \item A problem has been fixed which could prevent tick marks being drawn on a coordinate axis close to a singularity in the coordinate system. \end{enumerate} \subsection{Changes Introduced in V1.2} The following describes the most significant changes which occurred in the AST library between versions V1.1 and V1.2 (not the most recent version): \begin{enumerate} \item A new function, \htmlref{astPolyCurve}{astPolyCurve}, has been introduced to allow more efficient plotting of multiple geodesic curves (\secref{ss:plottinggeodesics}). \item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to perform resampling of gridded data such as images (\emph{i.e.}\ re-gridding) under the control of a geometrical transformation specified by a \htmlref{Mapping}{Mapping}. \item The command-line options ``$-$pgp'' and ``$-$pgplot'', which were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and ``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option ``$-$pgp'' now causes linking with the Starlink version of PGPLOT (which uses GKS to generate its output), while ``$-$pgplot'' links with the standard (or ``native'') version of PGPLOT. \item The function \htmlref{astMapBox}{astMapBox} has been changed to execute more quickly, although this has been achieved at the cost of some loss of robustness when used with difficult Mappings. \item A new value of ``FITS-IRAF'' has been introduced for the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an interim solution to the problem of storing coordinate system information in FITS headers, until the proposed new FITS-WCS standard becomes stable. \item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame} of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to ``GRID''. This reflects the fact that this Frame represents FITS data grid coordinates (equivalent to FITS pixel coordinates---see \secref{ss:domainconventions}). Previously, this Domain value was not set. \item \htmlref{astFindFits}{astFindFits} now ignores trailing spaces in its keyword template. \item \htmlref{astPutFits}{astPutFits} now recognises ``D'' and ``d'' as valid exponent characters in floating point numbers. \item The FitsChan class is now more tolerant of common minor violations of the FITS standard. \item The FitsChan class now incorporates an improved test for the linearity of Mappings, allowing more reliable conversion of AST data into FITS (using ``foreign'' FITS encodings). \item Some further improvements have been made to the algorithms for simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. \item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap} class. This allows improved simplification of compound Mappings (CmpMaps) involving SphMaps and typically improves performance when handling FITS world coordinate information. \item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of AST\_\_BAD automatically to all output coordinates. If certain output coordinates do not depend on the affected input coordinate(s) because the relevant matrix elements are zero, then they may now remain valid. \item A minor bug has been corrected which could cause certain projections which involve half the celestial sphere to produce valid coordinates for the other (unprojected) half of the sphere as well. \item A bug has been fixed which could occasionally cause \htmlref{astConvert}{astConvert} to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was possible when, in fact, it wasn't. \end{enumerate} \subsection{Changes Introduced in V1.3} The following describes the most significant changes which occurred in the AST library between versions V1.2 and V1.3 (not the most recent version): \begin{enumerate} \item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to provide efficient resampling of gridded data, such as spectra and images, under the control of a geometrical transformation specified by a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported. \item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised form of Mapping which implements 2-dimensional pincushion or barrel distortion. \item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too many digits when formatting floating point values for inclusion in a FITS header if the numerical value was in the range -0.00099999\ldots to -0.0001. \item A bug has been fixed which could cause a FitsChan to lose the comment associated with a string value in a FITS header. \item A FitsChan now reports an error if it reads a FITS header which identifies a non-standard sky projection (previously, this was accepted without error and a Cartesian projection used instead). \item A bug has been fixed which could prevent conversion between the coordinate systems represented by two CmpFrames. This could only occur if the CmpFrames contained a relatively large number of nested Frames. %\item A bug has been fixed which could cause a program to crash if %FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet} %had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The %problem could only occur if the nested structure was loaded from a data %c+ %file (using \htmlref{astRead}{astRead}). %c- %f+ %file (using AST\_READ). %f- % \item Further improvements have been made to the simplification of compound Mappings, including fixes for several bugs which could cause indefinite looping or unwanted error messages. \item Some memory leaks have been fixed. \item A small number of documentation errors have been corrected. \end{enumerate} \subsection{Changes Introduced in V1.4} The following describes the most significant changes which have occurred in the AST library between versions V1.3 and V1.4 (not the most recent version): \begin{enumerate} \item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of \htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a flexible and transportable way using arithmetic operations and mathematical functions similar to those available in C. \item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation functions used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{astIntraReg}{astIntraReg}) now require a ``this'' pointer as their first parameter. \textbf{Existing implementations will not continue to work correctly with this version of AST unless this parameter is added.} There is no need for existing software to make use of this pointer, but it must be present. This change has been introduced so that transformation functions can gain access to IntraMap attributes. \item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap class. This allows the transformation functions used by IntraMaps to adapt to produce the required transformation on a per-IntraMap basis (\secref{ss:intraflag}). \item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the length of major and minor tick marks on coordinate axes, may now be subscripted using an axis number. This allows tick marks of different lengths to be used on each axis. It also allows tick marks to be suppressed on one axis only by setting the length to zero. \item The value of the Plot attribute NumLab, which controls the plotting of numerical labels on coordinate axes, no longer has any effect on whether labelling of a coordinate grid is interior or exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute). \item The \htmlref{FitsChan}{FitsChan} class now provides some support for the IRAF-specific ``ZPX'' sky projection, which is converted transparently into the equivalent FITS ``ZPN'' projection (see the description of the \htmlref{Encoding}{Encoding} attribute for details). \item The FitsChan class now recognises the coordinate system ``ICRS'' (International Celestial Reference \htmlref{System}{System}) as equivalent to ``FK5''. This is an interim measure and full support for the (exceedingly small) difference between ICRS and FK5 will be added at a future release. Note that ``ICRS'' is not yet recognised as a coordinate system by other classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the importation of foreign data. \item A bug in the FitsChan class has been fixed which could result in longitude values being incorrect by 180 degrees when using cylindrical sky projections, such as the FITS ``CAR'' projection. \item A bug in the FitsChan class has been fixed which could result in the FITS sky projection parameters ProjP(0) to ProjP(9) being incorrectly named PROJP1 to PROJP10 when written out as FITS cards. \item A bug in the FitsChan class has been fixed which could cause confusion between the FITS-IRAF and FITS-WCS encoding schemes if both a CD matrix and a PC matrix are erroneously present in a FITS header. \item Some minor memory leaks have been fixed. \item A small number of documentation errors have been corrected. \end{enumerate} \subsection{Changes Introduced in V1.5} The following describes the most significant changes which have occurred in the AST library between versions V1.4 and V1.5 (not the most recent version): \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft FITS WCS standard, described in the two papers ``Representation of world coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th November, 1999), and ``Representation of celestial coordinates in FITS'' (M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are available at \url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}. The FITS-WCS encoding now uses these updated conventions. The main changes are: \begin{itemize} \item Rotation and scaling of pixel axes is now represented by a matrix of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and \texttt{CDELTj} keywords. \item \htmlref{Projection}{Projection} parameters are now associated with particular axes and are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm} keywords. \item The tangent plane projection (``TAN'') can now include optional polynomial correction terms. \item An entire set of keywords must be supplied for each set of secondary axis descriptions, and each such keyword must finish with a single character indicating which set it belongs to. This means that keywords which previously occupied eight characters have been shorten to seven to leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}. \end{itemize} \item Two new encodings have been added to the FitsChan class: \begin{description} \item [FITS-PC] This encoding uses the conventions of the now superseded FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords \texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation. These are the conventions which were used by the FITS-WCS encoding prior to version 1.5 of AST. This encoding is provided to allow existing data which use these conventions to be read. It should not in general be used to create new data. \item [FITS-AIPS] This encoding is based on the conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to describe axis rotation and scaling. \end{description} \item The FitsChan class now provides some support for the IRAF-specific ``TNX'' sky projection, which is converted transparently into the equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding} attribute for details). \item FrameSets originally read from a DSS encoded FITS header can now be written out using the FITS-WCS encoding (a TAN projection with correction terms will be used) in addition to the DSS encoding. The reverse is also possible: FrameSets originally read from a FITS-WCS encoded FITS header and which use a TAN projection can now be written out using the DSS encoding. \item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet} conforms to the FITS-WCS model has been improved so that FrameSets including more complex mixtures of parallel and serial Mappings can be written out using the FITS-WCS encoding. \item The FitsChan class has been changed so that long strings included in the description of an \htmlref{Object}{Object} can be saved and restored without truncation when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles, mathematical expressions, \emph{etc.} were truncated if they exceeded the capacity of a single FITS header card. They are now split over several header cards so that they can be restored without truncation. Note, this facility is only available when using NATIVE encoding. \item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which can be used to select potentially dangerous conditions under which warnings should be issued. These conditions include (for instance) unsupported features within non-standard projections, missing keywords for which default values will be used, \emph{etc}. \item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the FITS-WCS encoding in the FitsChan class: \begin{itemize} \item Projection parameters are now associated with a particular axis and are specified using a new set of attributes called PVj\_m. Here, ``j'' is the index of an axis of WcsMap, and ``m'' is the index of the projection parameter. \item The old attributes ProjP(0) to ProjP(9) are still available but are now deprecated in favour of the new PVj\_m attributes. They are interpreted as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of the latitude axis. \item The GLS projection projection has been renamed as SFL, but the AST\_\_GLS type has been retained as an alias for AST\_\_SFL. \end{itemize} \end{enumerate} \subsection{Changes Introduced in V1.6} The following describes the most significant changes which have occurred in the AST library between versions V1.5 and V1.6: \begin{enumerate} \item The C interface to several methods (\htmlref{astTranN}{astTranN}, \htmlref{astMark}{astMark} and \htmlref{astPolyCurve}{astPolyCurve}) have been changed to make them easier to call from C++. Parameters which previously had type ``double (*)[]'' have been changed to the simpler ``double *''. Using the old types may result in non-fatal compiler warnings, but should not change the behaviour of the methods. \item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups of tick marks to be skipped when using very small gaps. \item A bug has been fixed in the Plot class which could cause axes to be labeled outside the visible window, resulting in no axes being visible. \item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding Frames in the returned FrameSet. When writing a FrameSet to a FITS header the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the header. \item The FITS-WCS encoding used by the FitsChan class now attempts to retain the identification letter associated with multiple axis descriptions. When reading a FrameSet from a FITS header, the identification letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a FrameSet to a FITS header, the identification letter is read from the Ident attribute of each Frame. The letter to associate with each Frame can be changed by assigning a new value to the Frame's Ident attribute. \item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to ``Unknown'' if the CTYPE keywords in the supplied header refers to an unknown celestial coordinate system. Previously, a Frame was used instead of a SkyFrame. \item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the FitsChan class no longer report an error if the FITS header contains no CTYPE keywords. It is assumed that a missing CTYPE keyword implies that the world coordinate system is linear and identically equal to ``intermediate world coordinates''. \item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute of the FitsChan class. This value causes warnings to be issued if CTYPE keywords are missing from foreign encodings. \item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan class. This is a read-only, space separated list of all the known condition names which can be specified in the Warnings attribute. \item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in a FrameSet read using a foreign encoding. The Title is based on the Domain name of the Frame. If the Frame has no Domain name, the default Title supplied by the Frame class is retained. \item The FitsChan class uses the comments associated with CTYPE keywords as axis labels when reading a foreign encoding. This behaviour has been modified so that the default labels provided by the Frame class are retained (instead of using the CTYPE comments) if any of the CTYPE comments are identical. \item A new ``interpolation'' scheme identified by the symbolic constant AST\_\_BLOCKAVE has been added to the AST\_RESAMPLE$<$X$>$ set of functions. The new scheme calculates each output pixel value by finding the mean of the input pixels in a box centred on the output pixel. \item The SkyFrame class can now be used to represent an arbitrary spherical coordinate system by setting its System attribute to ``Unknown''. \item The indices of the latitude and longitude axes of a SkyFrame can now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The effects of any axis permutation is taken into account. \item A new attribute called Ident has been added to the \htmlref{Object}{Object} class. This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID) its value is transferred to the new Object when a copy is made. \item A bug has been fixed which could prevent complex CmpFrames behaving correctly (for instance, resulting in the failure of attempts to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself). \end{enumerate} \subsection{Changes Introduced in V1.7} The following describes the most significant changes which have occurred in the AST library between versions V1.6 and V1.7: \begin{enumerate} \item The \htmlref{Frame}{Frame} class has a new method called \htmlref{astAngle}{astAngle} which returns the angle subtended by two points at a third point within a 2 or 3 dimensional Frame. \item The Frame class has a new method called \htmlref{astOffset2}{astOffset2} which calculates a position which is offset away from a given starting point by a specified distance along a geodesic curve which passes through the starting point at a given position angle. It can only be used with 2-dimensional Frames. \item The Frame class has a new method called \htmlref{astAxDistance}{astAxDistance} which returns the increment between two supplied axis values. For axes belonging to SkyFrames, the returned value is normalized into the range $\pm\pi$. \item The Frame class has a new method called \htmlref{astAxOffset}{astAxOffset} which returns an axis value a given increment away from a specified axis value. For axes belonging to SkyFrames, the returned value is normalized into the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude axes). \item The \htmlref{Plot}{Plot} class has a new method called \htmlref{astGenCurve}{astGenCurve} which allows generalised user-defined curves to be drawn. The curve is defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve into the corresponding position in the current Frame of the Plot. The new method then maps these current Frame position into graphics coordinates, taking care of any non-linearities or discontinuities in the mapping. \item The Plot class has a new method called \htmlref{astGrfSet}{astGrfSet} which allows the underlying primitive graphics functions to be selected at run-time. Previously, the functions used by the Plot class to produce graphics could only be selected at link-time, using the options of the \htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride the functions established at link-time, by specifying alternative primitive graphics routines. In addition, the two new Plot methods \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGrfPop}{astGrfPop} allow the current graphics routines to be saved and restore on a first-in-last-out stack, allowing temporary changes to be made to the set of registered graphics routines. \item The DrawAxes attribute of the Plot class can now be specified independantly for each axis, by appending the axis index to the end of the attribute name. \item A bug has been fixed in the Plot class which could result in axis labels being drawn on inappropriate edges of the plotting box when using ``interior'' labelling. \item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps to be corrupted after transforming any points. \item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause inappropriate ordering of headers within a FitsChan when writing or reading objects using NATIVE encodings. \item A bug has been fixed in the FitsChan class which could cause the celestial longitude of a pixel to be estimated incorrectly by 180 degrees if the reference point is at either the north or the south pole. \end{enumerate} \subsection{Changes Introduced in V1.8-2} The following describes the most significant changes which have occurred in the AST library between versions V1.7 and V1.8-2: \begin{enumerate} \item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows longitude values to be displayed in the range $-\pi$ to $+\pi$, instead of the usual range zero to $2.\pi$. \item Some new functions (\htmlref{astAngle}{astAngle}, \htmlref{astAxAngle}{astAxAngle}, \htmlref{astResolve}{astResolve}, \htmlref{astOffset2}{astOffset2}, \htmlref{astAxOffset}{astAxOffset}, \htmlref{astAxDistance}{astAxDistance}) have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space to be performed without needing to know the underlying geometry of the co-ordinate system (for instance, whether it is Cartesian or spherical). Note, version 1.8-1 contained many of these facilities, but some have been changed in version 1.8-2. Particularly, positions angles are now referred to the second Frame axis for \emph{all} classes of Frames (including SkyFrames), and the astBear function has been replaced by astAxAngle. \end{enumerate} \subsection{Changes Introduced in V1.8-3} The following describes the most significant changes which occurred in the AST library between versions V1.8-2 and V1.8-3: \begin{enumerate} \item A new method called \htmlref{astDecompose}{astDecompose} has been added to the \htmlref{Mapping}{Mapping} class which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and \htmlref{CmpFrame}{CmpFrame} objects. \item Functions within proj.c and wcstrig.c have been renamed to avoid name clashes with functions in more recent versions of Mark Calabretta's wcslib library. \end{enumerate} \subsection{Changes Introduced in V1.8-4} The following describes the most significant changes which occurred in the AST library between versions V1.8-3 and V1.8-4: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be used to select the default reference frame and equinox to be used if a FitsChan with foreign encoding contains no indication of the reference frame or equinox. \item A bug has been fixed in the FitsChan class which could prevent \htmlref{astWrite}{astWrite} from creating a set of FITS headers from an otherwise valid \htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding. \item A bug has been fixed in the FitsChan class which could cause \htmlref{astRead}{astRead} to mis-interpret the FITS CROTA keyword when using FITS-AIPS encoding. \end{enumerate} \subsection{Changes Introduced in V1.8-5} The following describes the most significant changes which occurred in the AST library between versions V1.8-4 and V1.8-5: \begin{enumerate} \item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2, Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2. These allow graphical attributes (colour, width, etc) to be set for each axis individually. Previously, graphical attributes could only be set for both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs, TextLabs and Ticks. \end{enumerate} \subsection{Changes Introduced in V1.8-7} The following describes the most significant changes which occurred in the AST library between versions V1.8-5 and V1.8-7: \begin{enumerate} \item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class which controls the way CAR projections are handled when reading a \htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR projection to represent a simple linear transformation between pixel coordinates and celestial sky coordinates. This is not consistent with the definition of the CAR projection in the draft FITS-WCS standard, which requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native spherical coordinates to celestial spherical coordinates, thus making the Mapping non-linear. Setting CarLin to 1 forces \htmlref{astRead}{astRead} to ignore the FITS-WCS standard and treat any CAR projections as simple linear Mappings from pixel coordinates to celestial coordinates. \item A bug has been fixed which could result in axis Format attributes set by the user being ignored under certain circumstances. \item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class has been fixed. This bug could result in extra ticks marks being displayed at inappropriate positions. This bug manifested itself, for instance, if the Mapping represented by the Plot was a simple Cartesian to Polar Mapping. In this example, the bug caused tick marks to be drawn at negative radius values. \item A bug has been fixed which could prevent attribute settings from being read correctly by \htmlref{astSet}{astSet}, etc., on certain platforms (MacOS, for instance). \end{enumerate} \subsection{Changes Introduced in V1.8-8} The following describes the most significant changes which occurred in the AST library between versions V1.8-7 and V1.8-8: \begin{enumerate} \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS information stored in the form of Digitised Digitised Sky Survey (DSS) keywords. These problems only occurred for DSS fields in the southern hemisphere, and resulted in pixel positions being mapped to sky positions close to the corresponding \emph{northern} hemispshere field. \item A new method called \htmlref{astBoundingBox}{astBoundingBox} has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of the previous graphical output produced by a Plot method. \item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class which suppresses the graphical output normally produced by Plot methods. All the calculations needed to produce the normal output are still performed however, and so the bounding box returned by the new astBoundingBox method is still usable. \item Bugs have been fixed related to the appearance of graphical output produced by the Plot class. These bugs were to do with the way in which graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.) interacted with the corresponding generic element (e.g. \texttt{Colour(axes)}, etc.). \end{enumerate} \subsection{Changes Introduced in V1.8-13} The following describes the most significant changes which occurred in the AST library between versions V1.8-8 and V1.8-13: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords are only produced by \htmlref{astWrite}{astWrite} when necessary. For zenithal projections such as TAN, the LONPOLE keyword can always take its default value and so is not included in the FITS header produced by astWrite. Previously, the unnecessary production of a LONPOLE keyword could prevent FrameSets being written out using encodings which do not support the LONPOLE keyword (such as FITS-IRAF). \item The FitsChan class has been modified to retain leading and trailing spaces within COMMENT cards. \item The FitsChan class has been modified to only use CTYPE comments as axis labels if all non-celestial axes have unique non-blank comments (otherwise the CTYPE keyword values are used as labels). \item The FitsChan class has been modified so that it does not append a trailing ``Z'' character to the end of DATE-OBS keyword values. \item The FitsChan class has been modified to use latest list of FITS-WCS projections, as described in the FITS-WCS paper II, ``Representations of celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23 April 2002). Support has been retained for the polynomial correction terms which previous drafts have allowed to be associated with TAN projections. \item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN (which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN projection type now represents a simple TAN projection and has no associated projection parameters. In addition, the usage of projection parameters has been brought into line with the the FITS-WCS paper II. \item The WcsMap class has been modified so that a ``get'' operation on a projection parameter attribute will return the default value defined in the FITS-WCS paper II if no value has been set for the attribute. Previously, a value of AST\_\_BAD was returned in such a situation. \item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which allow a ``plottable range'' to be specified for each Frame axis. The grid produced by the \htmlref{astGrid}{astGrid} method will not extend beyond these limits. \end{enumerate} \subsection{Changes Introduced in V2.0} Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by applications linked with earlier versions of AST. This applies to Frame descriptions created using: \begin{itemize} \item the \htmlref{Channel}{Channel} class \item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used \item the \htmlref{astShow}{astShow} function \end{itemize} Applications must be re-linked with AST V2.0 in order to be able to read Frame descriptions created by AST v2.0. The following describes the most significant changes which have occurred in the AST library between versions V1.8-13 and V2.0 (the current version): \begin{enumerate} \item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame} class has been changed from ``CMP'' to a string formed by concatenating the Domain attributes of the two component Frames, separated by a minus sign. If both component Domains are blank, then the old default of ``CMP'' is retained for the CmpFrame Domain. \item The implementation of the \htmlref{astWrite}{astWrite} function within the FitsChan class has been modified. It will now attempt to produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the \htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This has always been possible with NATIVE encoding, but has not previously been possible for foreign encodings. The WCSAXES keyword is used to store the number of WCS axes in the FITS header. \item Another change to the astWrite function within the FitsChan class is that the ordering of ``foreign'' axes (\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix as diagonal as possible - any element of axis transposition is removed by this re-ordering as recommended in FITS-WCS paper I. Previously the ordering was determined by the order of the axes in the Current Frame of the supplied FrameSet. This change does not affect NATIVE encoding. \item Support for spectral coordinate systems has been introduced throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}. The SpecFrame is a 1-dimensional Frame which can be used to describe positions within an electromagnetic spectrum in various systems (wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred to various standards of rest (topocentric, geocentric, heliocentric LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral axis values between these various systems and standards of rest. Note, FitsChans which have a foreign encoding (\emph{i.e.} any encoding other than NATIVE) are not yet able to read or write these new classes. \item Facilities have been added to the Frame class which allow differences in axis units to be taken into account when finding a Mapping between two Frames. In previous versions of AST, the Unit attribute was a purely descriptive item intended only for human readers - changing the value of Unit made no difference to the behaviour of the Frame. As of version 2.0, the Unit attribute can influence the nature of the Mappings between Frames. For instance, if the astFindrame or \htmlref{astConvert}{astConvert} method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m'' and another Axis with Unit set to ``km'', then the method will return a \htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes. These facilities assume that units are specified following the rules included in FITS-WCS paper I (\emph{Representation of World Coordinates in FITS}, Greisen \& Calabretta). In order to minimise the risk of breaking existing software, the default behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.} to retain the previous behaviour). However, the new Frame method \htmlref{astSetActiveUnit}{astSetActiveUnit} may be used to ``activate'' (or deactivate) the new facilities within a specific Frame. Note, the new SpecFrame class is different to the simple Frame class in that the new facilities for handling units are always active within a SpecFrame. \item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been moved to the parent Frame class. This enables all sub-classes of Frame (such as the new SpecFrame class) to share these attributes, and to provide suitable options for each class. \item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows control over the alignment process performed by the methods \htmlref{astFindFrame}{astFindFrame} and astConvert. \item The CmpFrame class has been modified so that attributes of a component Frame can be accessed without needing to extract the Frame first. To do this, append an axis index to the end of the attribute name. For instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order), then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the ``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently ``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the CmpFrame will refer to the System attribute of the SpecFrame, whereas the ``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the System attribute of the SkyFrame (the ``System'' attribute without an axis specifier will refer to the System attribute of the CmpFrame as a whole, since System is an attribute of all Frames, and a CmpFrame is a Frame and so has its own System value which is independant of the System attributes of its component Frames). \item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit overlapping axis labels, and the abbreviation of redundant leading fields within sexagesimal axis labels, have been improved to avoid some anomolous behaviour in previous versions. \item The curve drawing algorithm used by the Plot class has been modified to reduce the chance of it ``missing'' small curve sections, such as may be produced if a grid line cuts across the plot very close to a corner. Previously, these missed sections could sometimes result in axis labels being omitted. \item A new function (\htmlref{astVersion}{astVersion}) has been added to return the version of the AST library in use. \item Bugs have been fixed in the Plot class which caused serious problems when plotting high precision data. These problems could range from the omission of some tick marks to complete failure to produce a plot. \end{enumerate} Programs which are statically linked will need to be re-linked in order to take advantage of these new facilities. \subsection{Changes Introduced in V3.0} The following describes the most significant changes which occurred in the AST library between versions V2.0 and V3.0: \begin{enumerate} \item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring the FITS-WCS encoding into line with the current versions of the FITS-WCS papers (see \url{http://www.atnf.csiro.au/people/mcalabre/WCS/}): \begin{itemize} \item The rotation and scaling of the pixel axes may now be specified using either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS header. \item The FITS-WCS encoding now supports most of the conventions described in FITS-WCS paper III for the description of spectral coordinates. The exceptions are that the SSYSOBS keyword is not supported, and WCS stored in tabular form (as indicated by the ``-TAB'' algorithm code) is not supported. \item User-specified fiducial points for WCS projections are now supported by FitsChans which use FITS-WCS encoding. This use keywords PVi\_0, PVi\_1 and PVi\_2 for the longitude axis. \item When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3 and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE and LATPOLE keywords which may be present. When writing a FITS-WCS header, both forms are written out. \item The number of WCS axes is stored in the WCSAXES keyword if its value would be different to that of the NAXIS keyword. \item Helio-ecliptic coordinates are now supported by FitsChans which use FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all the usual facilities, such as conversion to other celestial systems, are available. \item The FITS-WCS encoding now supports most of the conventions described in FITS-WCS paper III for the description of spectral coordinates. The exceptions are that the SSYSOBS keyword is not supported, and WCS stored in tabular form (as indicated by the ``-TAB'' algorithm code) is not supported. \item When reading a FITS-WCS header, a FitsChan will now ignore any distortion codes which are present in CTYPE keywords. Here, a ``distortion code'' is the final group of four characters in a CTYPE value of the form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception to this is that the ``-SIP'' distortion code (as used by the Spitzer Space Telescope project - see \url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes can only be read, not written. A FrameSet which uses a PolyMap will not in general be able to be written out to a FitsChan using any foreign encoding (although NATIVE encoding can of course be used). \item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values ``BadVal'' (which gives warnings about conversion errors when reading FITS keyword values), ``Distortion'' (which gives warnings about unsupported distortion codes within CTYPE values), and ``BadMat'' (which gives a warning if the rotation/scaling matrix cannot be inverted). \item When writing a FrameSet to a FitsChan which uses a non-Native encoding, the comment associated with any card already in the FitsChan will be retained if the keyword value being written is the same as the keyword value already in the FitsChan. \item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN projection with polynomial distortion terms) can now be written to a FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard ``-TAN'' code is used within the CTYPE values, and the distortion coefficients are encoded in keywords of the form `` QVi\_ma'', which are directly analogous to the standard ``PVi\_ma'' projection parameter keywords. Thus a FITS reader which does not recognise the QV keywords will still be able to read the header, but the distortion will be ignored. \item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value of the Encoding attribute. \item A new appendix has been added to SUN/210 and SUN/211 giving details of the implementation provided by the FitsChan class of the conventions contained in the first four FITS-WCS papers. \end{itemize} \item The SkyFrame class now supports two new coordinate systems ``ICRS'' and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames has been changed from ``FK5'' to ``ICRS''. \item The \htmlref{astRate}{astRate} function has been added which allows an estimate to be made of the rate of change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs. \item All attribute names for Frames of any class may now include an optional axis specifier. This includes those attributes which describe a property of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases such as this, where the attribute describes a property of the whole Frame, axis specifiers will usually be ignored. The exception is that a \htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the attribute name relates to the primary Frame containing the specified axis, rather than to the CmpFrame as a whole. \item A new subclass of Mapping, the PolyMap, has been added which performs a general N-dimensional polynomial mapping. \item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which models the spectral dispersion produced by a grating, prism or grism. \item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap} with unit scaling on all axes). \item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice and placement of numerical axis labels. \item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the longitude value to be returned when a Cartesian position corresponding to either the north or south pole is transformed into spherical coordinates. \item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output celestial coordinates which have a latitude of plus or minus 90 degrees. \item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been changed so that they now return the fixed native coordinates of the projection reference point, rather than the native coordinates of the user-defined fiducial point. \item Notation has been changed in both the WcsMap and FitsChan classes to reflect the convention used in the FITS-WCS papers that index ``i'' refers to a world coordinate axis, and index ``j'' refers to a pixel axis. \item Changes have been made to several Mapping classes in order to allow the \htmlref{astSimplify}{astSimplify} function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not possible. \item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates. \item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the refractive index of air as given in the current version of FITS-WCS paper III. Also, the forward and inverse transformations between frequency and air-wavelength have been made more compatible by using an iterative procedure to calculate the inverse. \end{enumerate} \subsection{Changes Introduced in V3.1} The following describes the most significant changes which have occurred in the AST library between versions V3.0 and V3.1 (the current version): \begin{enumerate} \item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which reads and writes AST objects in the form of XML. \item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect graphical attributes to be used for various parts of the plot if either axis has no tick marks (i.e. if both major and minor tick marks have zero length). \end{enumerate} Programs which are statically linked will need to be re-linked in order to take advantage of these new facilities. \subsection{Changes Introduced in V3.2} The following describes the most significant changes which have occurred in the AST library between versions V3.1 and V3.2: \begin{enumerate} \item A new function \htmlref{astPutCards}{astPutCards} has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header cards to be stored in a FitsChan in a single call, providing an alternative to the existing astPutCards function. \item Some signficant changes have been made to the simplification of Mappings which should resultin a greater degree of simplication taking place.Some bugs have also been fixed which could result in an infinite loop being entered when attempting to simplify certain Mappings. \item The FitsChan class now translates the spectral algorithm codes ``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to the corresponding ``-X2P'' form when reading a spectral axis description from a set of FITS header cards. \item A bug has been fixed in the FitsChan class which could cause keywords associated with alternate axis descriptions to be mis-interpreted. \item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance of sub-strings within text strings such as axis labels, titles, \emph{etc}, by producing super-scripts, sub-scripts, changing the font colour, size, \emph{etc}. See attribute \htmlref{Escape}{Escape}. \item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been changed from 0.001 to 0.01. This should not usually cause any significant visible change to the plot, but should make the plotting faster. You may need to set a lower value for Tol if you are producing a particularly large plot. \item The algorithm for finding the default value for the Gap attribute has been changed. This attribute specifies the gap between major axis values in an annotated grid drawn by the Plot class. The change in algorithm may cause the default value to be different to previous versions in cirtain circumstances. \item Some bugs have been fixed in the Plot class which could cause the system to hang for a long time while drawing certain all-sky grids (notable some of the FITS Quad-cube projections). \item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition of the ``g'' option. this option is similar to the older ``l'' option in that it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as delimiters between the sexagesimal fields of the celestial position. The difference is that the ``g'' option includes graphics escape sequences in the returned formatted string which result in the field delimiter characters being drawn as super-scripts when plotted as numerical axis values by a Plot. \item The Plot class has been extended to include facilities for producing logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel. \item New functions astGCap and astGScales have been added to the interface defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so that the \verb+-mygrf+ switch loads dummy versions of the new grf functions. This means that applications should continue to build without any change. However, the facilities for interpreting escape sequences within strings drawn by the Plot class will not be available unless the new grf functions are implemented. If you choose to implement them, you should modify your linking procedure to use the \verb+-grf+ switch in place of the older \verb+-mygrf+ switch. See the description of the ast\_link command for details of the new switches. Also note that the astGQch function, whilst included in verb+grf.h+ in pervious versions of AST, was not actually called. As of this version of AST, calls are made to the astGQch function, and so any bugs in the implementation of astGQch may cause spurious behaviour when plotting text strings. \item A new 'static' method called \htmlref{astEscapes}{astEscapes} has been added which is used to control and enquire whether astGetC and \htmlref{astFormat}{astFormat} will strip any graphical escape sequences which may be present out of the returned value. \item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It allows XML written by the XmlChan class to include an explicit namespace prefix on each element. \item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It specifies the format in which AST objects should be written. \item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap takes its forward transformation from an existing Mapping, and its inverse transformation from another existing Mapping. \item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to include erroneous axis numbers when referring to missing parameter values. \end{enumerate} \subsection{Changes Introduced in V3.3} The following describes the most significant changes which have occurred in the AST library between versions V3.2 and V3.3: \begin{enumerate} \item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the origin of celestial coordinates to be moved to any specified point. See the new attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. \item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra Frames representing cartesian projection plane coordinates (``intermediate world coordinates'' in the parlance of FITS-WCS) to be created when reading WCS information from a foreign FITS header. This option is controlled by a new attribute called \htmlref{Iwc}{Iwc}. \item The FitsChan class which been modified to interpret FITS-WCS CAR projection headers correctly if the longitude reference pixel (CRPIX) is very large. \item The FITS-AIPS++ encoding in the FitsChan class now recognised spectral axes if they conform to the AIPS convention in which the spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB" where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD, HEL or OBS. Such spectral axes can be both read and written. \item The FitsChan class now has a FITS-AIPS++ encoding which represents WCS information using FITS header cards recognised by the AIPS++ project. Support for spectral axes is identical to the FITS-AIPS encoding. \item The organisation of the AST distribution and the commands for building it have been changed. Whereas AST used to be built and installed with \verb+./mk build; ./mk install+, it now builds using the more standard idiom \verb+./configure; make; make install+. The installation location is controlled by the \verb+--prefix+ argument to ./configure (as is usual for other packages which use this scheme). Note that the INSTALL environment variable now has a \emph{different} meaning to that which it had before, and it should generally be \emph{unset}. Also, there is no need to set the SYSTEM variable. \item Shared libraries are now installed in the same directory as the static libraries. In addition, links to sharable libraries are installed with names which include version information, and ``libtool libraries'' are also installed (see \url{http://www.gnu.org/software/libtool/manual.html}). \item The \verb+ast_dev+ script has been removed. Instead, the location of the AST include files should be specified using the -I option when compiling. \end{enumerate} \subsection{Changes Introduced in V3.4} The following describes the most significant changes which have occurred in the AST library between versions V3.3 and V3.4: \begin{enumerate} \item The \htmlref{Mapping}{Mapping} class has a new method (\htmlref{astLinearApprox}{astLinearApprox}) which calculates the co-efficients of a linear approximation to a Mapping. \item The Format attribute for simple Frames and SkyFrames has been extended. It has always been possible, in both classes, to specify a precision by including a dot in the Format value followed by an integer (\emph{e.g.} ``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}). The precision can now also be specified using an asterisk in place of the integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the precision to be derived on the basis of the Digits attribute value. \item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the Digits attribute is chosen to be the smallest value which results in no pair of adjacent labels being identical. For instance, if an annotated grid is being drawn describing a SkyFrame, and the Format(1) value is set to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as superscripts), and the Digits(1) value is unset, then the seconds field will have a number of decimal places which results in no pair of labels being identical. \item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes associated with dual sideband spectral data. \item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS'' projection code, converting them to the corresponding modern ``-SFL'' code, provided that the celestial axes are not rotated. \item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows the reading and writing of FITS headers using the conventions of the CLASS package - see \url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}). \end{enumerate} \subsection{Changes Introduced in V3.5} The following describes the most significant changes which have occurred in the AST library between versions V3.4 and V3.5: \begin{enumerate} \item AST now provides facilities for representing regions of various shapes within a coordinate system. The \htmlref{Region}{Region} class provides general facilities which are independent of the specific shape of region being used. Various sub-classes of Region are also now available which provide means of creating Regions of specific shape. Facilities provided by the Region class include testing points to see if they are inside the Region, testing two Regions for overlap, transforming Regions from one coordinate system to another \emph{etc}. \item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which can be used to describe various systems for describing ovserved value at a single fixed spectral position. \item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which can be used to describe a 2-d frame spanned by a spectral position axis and and an observed value axis. \item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates a previously created Mapping. The inputs of the RateMap correspond to the inputs of the encapsulated Mapping. All RateMaps have just a single output which correspond to the rate of change of a specified output of the encapsulated Mapping with respect to a specified input. \item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}. This system is an equatorial system based on the mean dynamical equator and equinox at J2000, and differs slightly from an FK5(J2000) system. \item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to store a collection of vector or scalar values or Objects, indexed by a character string rather than an integer. \item The parameter list for the \htmlref{astRate}{astRate} method of the Mapping class has been modified. It no longer returns a second derivative estimate. Existing code which uses this method will need to be changed. \item Methods (astSetFits) have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named keywords to be changed or added. \end{enumerate} \subsection{Changes Introduced in V3.6} The following describes the most significant changes which occurred in the AST library between versions V3.5 and V3.6: \begin{enumerate} \item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame} starts with a percent character (``\verb+%+''), then axis values are now formatted and unformatted as a decimal radians value, using the Format syntax of a simple \htmlref{Frame}{Frame}. \item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the clipping performed by AST at the plot boundary. \item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}. The new PolyMap class always writes new styles keys but can read either old or new style keys. Consequently, PolyMap dumps written by this version of AST cannot be read by older versions of AST. \item A mimimal cut down subset of the C version of SLALIB is now included with the AST distribution and built as part of building AST. This means that it is no longer necessary to have SLALIB installed separately at your site. The SLALIB code included with AST is distrubuted under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to link with this internal slalib subset. However, the ``-csla'' option can still be used to force linking with an external full C SLALIB library. A new option ``-fsla'' has been introduced which forces linking with the external full Fortran SLALIB library. \end{enumerate} \subsection{Changes Introduced in V3.7} The following describes the most significant changes which occurred in the AST library between versions V3.6 and V3.7: \begin{enumerate} \item Support for time coordinate systems has been introduced throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}. The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe moments in time (either absolute or relative) in various systems (MJD, Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC, UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time values between these various systems and time scales. Note, FitsChans which have a foreign encoding (\emph{i.e.} any encoding other than NATIVE) are not able to read or write these new classes. \end{enumerate} \subsection{Changes Introduced in V4.0} The following describes the most significant changes which occurred in the AST library between versions V3.7 and V4.0: \begin{enumerate} \item Experimental support for reading IVOA Space-Time-Coordinates (STC-X) descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included for a subset of V1.20 of the draft STC specification. \item A new set of methods (AST\_REBIN/astRebin) has been added to the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing AST\_RESAMPLE/astResample methods. \end{enumerate} \subsection{Changes Introduced in V4.1} The following describes the most significant changes which occurred in the AST library between versions V4.0 and V4.1: \begin{enumerate} \item A new control flag has been added to the AST\_RESAMPLE/astResample functions which produces approximate flux conservation. \item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to ast.h. These specify kernels for astResample and astRebin based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the first order Bessel function of the first kind). \item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding to horizon (azimuth/elevation) coordinates. \item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and ``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values. \item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify the geodetic longitude and latitude of the observer. \item The ClockLon and ClockLat attributes have been removed from the \htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and ObsLat attributes of the parent Frame class instead. However, the old attribute names can be used as synonyms for ObsLat and ObsLon. Also, dumps created using the old scheme can be read succesfully by AST V4.1 and converted to the new form. \item A new function \htmlref{astMapSplit}{astMapSplit} has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component Mappings which, when combined in parallel, are equivalent to the original Mapping. \item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from ``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame to represent offsets from some origin position, you must now set the SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in addition to assigning the required origin position to the SkyRef attribute. \end{enumerate} \subsection{Changes Introduced in V4.2} The following describes the most significant changes which occurred in the AST library between versions V4.1 and V4.2: \begin{enumerate} \item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the DSBSpecFrame to represent the offset from the local oscillator frequency, rather than either of the two sidebands. \item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric apparent velocity of the standard of rest). FitsChan also strips out VELOSYS keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding. \item The FitsChan class has a new method called \htmlref{astRetainFits}{astRetainFits} that indicates that the current card in the FitsChan should not be stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan. Unless this method is used, all cards that were involved in the creation of the AST Object will be stripped from the FitsChan afte a read operation. \item A problem with unaligned memory access that could cause bus errors on Solaris has been fixed. \item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the Object. Note, this is the size of the internal in-memory representation of the Object, not the size of the textual representation produced by writing the Object out through a \htmlref{Channel}{Channel}. \item A new function \htmlref{astTune}{astTune} has been added which can be used to get and set global AST tuning parameters. At the moment there are only two such parameter, both of which are concerned with memory management within AST. \item A new method called \htmlref{astTranGrid}{astTranGrid} has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular grid of points covering a rectangular region within the input space of a Mapping, and then transforms this set of points into the output space of the Mapping, using a piecewise-continuous linear approximation to the Mapping if appropriate in order to achive higher speed. \item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A SwitchMap represents several alternate Mappings, each of which is used to transforms input positions within a different region of the input coordinate space. \item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A SelectorMap tests each input position to see if it falls within one of several Regions. If it does, the index of the \htmlref{Region}{Region} containing the input position is returned as the Mapping output. \item The behaviour of the \htmlref{astConvert}{astConvert} method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been modified. If no conversion between positions in the Frame and CmpFrame can be found, an attempt is now made to find a conversion between the Frame and one of two component Frames contained within the CmpFrame. Thus is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad values for the extra axes (i.e. for the SpecFrame axis in the above example). \item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the \verb+-fsla+ and \verb+-csla+ options, and always link against the minimal cut-down version of SLALIB distributed as part of AST. \end{enumerate} \subsection{Changes Introduced in V4.3} The following describes the most significant changes which occurred in the AST library between versions V4.2 and V4.3: \begin{enumerate} \item The astGetFitsS function now strips trailing white space from the returned string, if the original string contains 8 or fewer characters \item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the source) should be accessed as an apparent radial velocity or a redshift. Note, any existing software that assumes that SourceVel always represents a velocity in km/s should be changed to allow for the possibility of SourceVel representing a redshift value. \end{enumerate} \subsection{Changes Introduced in V4.4} The following describes the most significant changes which occurred in the AST library between versions V4.3 and V4.4: \begin{enumerate} \item The \htmlref{astFindFrame}{astFindFrame} function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame} or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as the ``template'' when calling astFindFrame, and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the current Frame is a CmpFrame), then the component Frames within the CmpFrame will be searched for an instance of the supplied template Frame, and, if found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the required axes from the CmpFrame) will be returned by astFindFrame. Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template Frame must be set so that they cover a range that includes the number of axes in the target CmpFrame. \item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes now allow the MaxAxes and MinAxes attributes to be set freely to any value. In previous versions of AST, any attempt to change the value of MinAxes or MaxAxes was ignored, resulting in them always taking the default values. \item The DSBSpecFrame class has a new attribute called AlignSB that specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when aligning two DSBSpecFrames using \htmlref{astConvert}{astConvert}. \item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to store a value for the difference between the UT1 and UTC timescales at the epoch referred to by the Frame. \item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and \htmlref{ObsLon}{ObsLon} has been increased. \item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This attribute is used to control how two SkyFrames are aligned by astConvert. If the template and target SkyFrames both have a non-zero value for AlignOffset, then alignment occurs between the offset coordinate systems (that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). \item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be used to force exterior (rather than interior) tick marks to be produced. By default, exterior ticks are only produced if this would result in more than 3 tick marks being drawn. \item The TimeFrame class now supports conversion between angle based timescales such as UT1 and atomic based timescales such as UTC. \end{enumerate} \subsection{Changes Introduced in V4.5} The following describes the most significant changes that occurred in the AST library between versions V4.4 and V4.5: \begin{enumerate} \item All FITS-CLASS headers are now created with a frequency axis. If the \htmlref{FrameSet}{FrameSet} supplied to \htmlref{astWrite}{astWrite} contains a velocity axis (or any other form of spectral axis) it will be converted to an equivalent frequency axis before being used to create the FITS-CLASS header. \item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed from the velocity of the source to the velocity of the reference channel. \item Addition of a new method call \htmlref{astPurgeWCS}{astPurgeWCS} to the \htmlref{FitsChan}{FitsChan} class. This method removes all WCS-related header cards from a FitsChan. \item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used to comminicate context information between an application and any graphics functions registered with the Plot class via the \htmlref{astGrfSet}{astGrfSet} function. \item Functions registered with the Plot class using astGrfSet now take a new additional integer parameter, ``grfcon''. The Plot class sets this parameter to the value of the Plot's GrfContext attribute before calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE THAT USES astGrfSet TO BE MODIFIED TO INCLUDE THE NEW PARAMETER. \item The astRebinSeq functions now have an extra parameter that is used to record the total number of input data values added into the output array. This is necessary to correct a flaw in the calculation of output variances based on the spread of input values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO INCLUDE THE NEW PARAMETER (CALLED "NUSED"). \item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection. \item A new flag ``AST\_\_VARWGT'' can be supplied to astRebinSeq. This causes the input data values to be weighted using the reciprocals of the input variances (if supplied). \item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that returns the normalised value of the Unit attribute for an axis. Here, ``normalisation'' means cancelling redundant units, etc. So for instance, a Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''. \item A new function \htmlref{astShowMesh}{astShowMesh} has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering the surface of a Region by writing out a table of axis values to standard output. \item The Plot class now honours the value of the LabelUp attribute even if numerical labels are placed around the edge of the Plot. Previously LabelUp was only used if the labels were drawn within the interior of the plot. The LabelUp attribute controls whether numerical labels are drawn horizontally or parallel to the axis they describe. \item A bug has been fixed that could segmentation violations when setting attribute values. \end{enumerate} \subsection{Changes Introduced in V4.6} The following describes the most significant changes which have occurred in the AST library between versions V4.5 and V4.6: \begin{enumerate} \item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset from UTC to Local Time is specified by a new TimeFrame attribute called \htmlref{LTOffset}{LTOffset}. \item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows the creation of 3-dimensional annotated coordinate grids. \item A correction for diurnal aberration is now included when converting between AZEL and other celestial coordinate systems. The correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the geodetic latitude of the observer). \item A bug has been fixed which caused the DUT1 attribute to be ignored by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other celestial coordinate systems. \end{enumerate} \subsection{Changes Introduced in V5.0} The following describes the most significant changes which occurred in the AST library between versions V4.6 and V5.0: \begin{enumerate} \item The AST library is now thread-safe (assuming that the POSIX pthreads library is available when AST is built). Many of the macros defined in the ast.h header file have changed. It is therefore necessary to re-compile all source code that includes ast.h. \item New methods \htmlref{astLock}{astLock} and \htmlref{astUnlock}{astUnlock} allow an AST \htmlref{Object}{Object} to be locked for exclusive use by a thread. \item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset from UTC to Local Time is specified by a new TimeFrame attribute called \htmlref{LTOffset}{LTOffset}. \item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls whether or not to report an error if unexpected data items are found within an AST Object description read from an external data source. Note, the default behaviour is now not to report such errors. This differs from previous versions of AST which always reported an error is unexpected input items were encountered. \end{enumerate} \subsection{Changes Introduced in V5.1} The following describes the most significant changes which occurred in the AST library between versions V5.0 and V5.1: \begin{enumerate} \item The \htmlref{astUnlock}{astUnlock} function now has an extra parameter that controls whether or not an error is reported if the \htmlref{Object}{Object} is currently locked by another thread. \item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval} could be used for this purpose. \item The values of the AST\_\_THREADSAFE macro (defined in ast.h) have been changed from ``yes'' and ``no'' to ``1'' and ``0''. \item Improvements have been made to the way that Prisms are simplified when \htmlref{astSimplify}{astSimplify} is called. The changes mean that more types of Prism will now simplify into a simpler class of Region. \item The \htmlref{PointList}{PointList} class has a new method, astPoints, that copies the axis values from the PointList into a supplied array. \item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that gives the number of points stored in the PointList. \item The handling of warnings within different classes of \htmlref{Channel}{Channel} has been rationalised. The XmlStrict attribute and astXmlWarnings function have been removed. The same functionality is now available via the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new attribute called \htmlref{ReportLevel}{ReportLevel}, and the new \htmlref{astWarnings}{astWarnings} function. This new function can be used on any class of Channel. Teh \htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as header cards within the FitsChan, but it also now stores warnings in the parent Channel structure, from where they can be retrieved using the astWarnings function. \item A new function called astIntercept has been added to the \htmlref{Frame}{Frame} class. This function finds the point of intersection beteeen two geodesic curves. \item A bug in the type-checking of Objects passed as arguments to constructor functions has been fixed. This bug could lead to applications crashing or showing strange behaviour if an inappropriate class of Object was supplied as an argument to a constructor. \item The \htmlref{astPickAxes}{astPickAxes} function will now return a Region, if possible, when applied to a Region. If this is not possible, a Frame will be returned as before. \item The choice of default tick-mark for time axes has been improved, to avoid previous issues which could result in no suitable gap being found, or inappropriate tick marks when using formatted dates. \item A new function called \htmlref{astTestFits}{astTestFits} has been added to the FitsChan class. This function tests a FitsChan to see if it contains a defined value for specified FITS keyword. \item The AST\_\_UNDEF parameters used to flag undefined FITS keyword values have been removed. Use the new astTestFits function instead. \item The astIsUndef functions used to test FITS keyword values have been removed. Use the new astTestFits function instead. \end{enumerate} \subsection{Changes Introduced in V5.2} The following describes the most significant changes which occurred in the AST library between versions V5.1 and V5.2: \begin{enumerate} \item A new method called \htmlref{astSetFitsCM}{astSetFitsCM} has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a FitsChan (that is, a card with no keyword name or equals sign). \item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It records the geodetic altitude of the observer, in metres. It defaults to zero. It is used when converting times to or from the TDB timescale, or converting spectral positions to or from the topocentric rest frame, or converting sky positions to or from horizon coordinates. The FitsChan class will include its effect when creating a set of values for the OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a set of OBSGEO-X/Y/Z keyword values from a FITS header. \item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap} conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument - the observer's geodetic altitude. \item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the IVOA STC definition of a Polygon. Specifically, the inside of a polygon is now the area to the left of each edge as the vertices are traversed in an anti-clockwise manner, as seen from the inside of the celestial sphere. Previously, AST used the anti-clockwise convention, but viewed from the outside of the celestial sphere instead of the inside. Any Polygon saved using previous versions of AST will be identified and negated automatically when read by AST V5.2. \item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows conversion of suitable AST Objects to and from IVOA STC-S format. \item A new method called \htmlref{astRemoveRegions}{astRemoveRegions} has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound) Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either removes them, or replaces them with UnitMaps (or equivalent Frames). It can be used to remove the masking effects of Regions from a compound Mapping or Frame. \item A new method called \htmlref{astDownsize}{astDownsize} has been added to the Polygon class. It produces a new Polygon that contains a subset of the vertices in the supplied Polygon. The subset is chosen to retain the main features of the supplied Polygion, in so far as that is possible, within specified constraints. \item A new constructor called astOutline has been added to the Polygon class. Given a 2D data array, it identifies the boundary of a region within the array that holds pixels with specified values. It then creates a new Polygon to describe this boundary to a specified accuracy. \item A new set of methods, called astMapGetElem has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector valued entry to be returned. \item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It controls whether the astMapGet... family of functions report an error if an entry with the requested key does not exist in the KeyMap. \end{enumerate} \subsection{Changes Introduced in V5.3} The following describes the most significant changes which occurred in the AST library between versions V5.2 and V5.3: \begin{enumerate} \item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the \htmlref{astFindFrame}{astFindFrame} and \htmlref{astConvert}{astConvert} functions have been changed. The changes mean that a Frame can now be aligned with an instance of a sub-class of Frame, so long as the number of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic 2-dimensional Frame with Domain ``SKY'' will now align succesfully with a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a \htmlref{UnitMap}{UnitMap}. \item The arrays that supply input values for astMapPut1 are now declared ``const''. \item Added method \htmlref{astMatchAxes}{astMatchAxes} to the Frame class. This method allows corresponding axes within two Frames to be identified. \item The \htmlref{astAddFrame}{astAddFrame} method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}. \end{enumerate} \subsection{Changes Introduced in V5.3-1} The following describes the most significant changes which have occurred in the AST library between versions V5.3 and V5.3-1: \begin{enumerate} \item The utility functions provided by the AST memory management layer are now documented in an appendix. \item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A new method called \htmlref{astMapPutU}{astMapPutU} will store an entry with undefined value in a keymap. Methods that retrieve values from a KeyMap (astMapGet0, etc.) ignore entries with undefined values when searching for an entry with a given key. \item The KeyMap class has a new method called \htmlref{astMapCopy}{astMapCopy} that copies entries from one KeyMap to another KeyMap. \item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If non-zero, an error is reported if an attempt is made to add any new entries to a KeyMap (the value associated with any old entry may still be changed without error). The default is zero. \item The \htmlref{Object}{Object} class has a new method called \htmlref{astHasAttribute}{astHasAttribute}/AST\_HASATTRIBUTE that returns a boolean value indicating if a specified Object has a named attribute. \item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called IsLatAxis and IsLonAxis that can be used to determine the nature of a specified SkyFrame axis. \item A bug has been fixed in the astRebin(Seq) methods that could cause flux to be lost from the edges of the supplied array. \item A bug has been fixed in the astRebin(Seq) methods that caused the first user supplied parameter to be interpreted as the full width of the spreading kernel, rather than the half-width. \item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except that units strings are still case sensitive). \item A new \htmlref{Mapping}{Mapping} method, \htmlref{astQuadApprox}{astQuadApprox}, produces a quadratic least-squares fit to a 2D Mapping. \item A new Mapping method, \htmlref{astSkyOffsetMap}{astSkyOffsetMap}, produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame coordinates. \item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation in the text created by \htmlref{astWrite}{astWrite}. The StcsIndent and XmlIndent attributes have been removed. \item All classes of Channel now use the string ``'' to represent the floating point value AST\_\_BAD, rather than the literal formatted value (typically ``-1.79769313486232e+308'' ). \item The KeyMap class now uses the string ``'' to represent the floating point value AST\_\_BAD, rather than the literal formatted value (typically ``-1.79769313486232e+308'' ). \item The KeyMap class has a new method called astMapPutElem that allows a value to be put into a single element of a vector entry in a KeyMap. The vector entry is extended automatically to hold the new element if required. \item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator frequency is less than the absoliute value of the intermediate frequency. \end{enumerate} \subsection{Changes Introduced in V5.3-2} The following describes the most significant changes which occurred in the AST library between versions V5.3-1 and V5.3-2: \begin{enumerate} \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength axes to be assigned the units ``m/s'' when reading WCS information from a FITS header. \item The \htmlref{astSet}{astSet} function now allows literal commas to be included in string attribute values. String attribute values that include a literal comma should be enclosed in quotation marks. \item A bug in FitsChan has been fixed that caused ``-SIN'' projection codes within FITS-WCS headers to be mis-interpreted, resulting in no \htmlref{FrameSet}{FrameSet} being read by \htmlref{astRead}{astRead}. \item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls the order in which keys are returned by the \htmlref{astMapKey}{astMapKey} function. Keys can be sorted alphabetically or by age, or left unsorted. \item Access to KeyMaps holding thousands of entries is now significantly faster. \item KeyMaps can now hold word (i.e. short integer) values. \end{enumerate} \subsection{Changes Introduced in V5.4-0} The following describes the most significant changes which occurred in the AST library between versions V5.3-2 and V5.4-0: \begin{enumerate} \item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}. See the documentation for TabOK for more information. \item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in which each entry represents a cell in a two-dimensional table. \item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a Table that has an associated FitsChan holding headers appropriate to a FITS binary table. \item KeyMaps can now hold byte values. These are held in variables of type "unsigned char". \item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to make the handling of keys case insensitive. \item a memory leak associated with the use of the astMapPutElem functions has been fixed. \item A new method called \htmlref{astMapRename}{astMapRename} has been added to rename existing entry in a KeyMap. \end{enumerate} \subsection{Changes Introduced in V5.5-0} The following describes the most significant changes which occurred in the AST library between versions V5.4-0 and V5.5-0: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather than a boolean value. If TabOK is set to a non-zero positive integer before invoking the \htmlref{astWrite}{astWrite} method, its value is used as the version number for any table that is created as a consequence of the write operation. This is the value stored in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the binary table header. In previous versions of AST, the value used for these headers could not be controlled and was fixed at 1. If TabOK is set to a negative or zero value, the -TAB algorithm will not be supported by either the astWrite or \htmlref{astRead}{astRead} methods. \end{enumerate} \subsection{Changes Introduced in V5.6-0} The following describes the most significant changes which occurred in the AST library between versions V5.5-0 and V5.6-0: \begin{enumerate} \item New functions \htmlref{astBBuf}{astBBuf} and \htmlref{astEBuf}{astEBuf} have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical output produced by other Plot methods. \item New functions astGBBuf and astGEBuf have been added to the interface defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf functions. This means that applications that use the \verb+-grf_v3.2+ switch should continue to build without any change. However, the new public functions astBBuf and astEBuf will report an error unless the new grf functions are implemented. If you choose to implement them, you should modify your linking procedure to use the \verb+-grf+ (or \verb+-grf_v5.6+ ) switch in place of the older \verb+-grf_v3.2+ switch. See the description of the ast\_link command for details of these switches. \item New method \htmlref{astGetRegionMesh}{astGetRegionMesh} returns a set of positions covering the boundary, or volume, of a supplied \htmlref{Region}{Region}. \end{enumerate} \subsection{ChangesIntroduced in V5.6-1} The following describes the most significant changes which occurred in the AST library between versions V5.6-0 and V5.6-1: \begin{enumerate} \item Tables can now have any number of parameters describing the global properties of the \htmlref{Table}{Table}. \item Frames now interpret the unit string ``A'' as meaning ``Ampere'' rather than ``Angstrom'', as specified by FITS-WCS paper I. \item A bug has been fixed in the \htmlref{astFindFrame}{astFindFrame} method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match a target frame of a less specialised class. For example, this bug would allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer happens. \end{enumerate} \subsection{Changes Introduced in V5.7-0} The following describes the most significant changes which occurred in the AST library between versions V5.6-1 and V5.7-0: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has been extended to include reading TNX headers that use a Chebyshev representation for the distortion polynomial. \item The FitsChan class support for the IRAF-specific ``ZPX'' projection has been extended to include reading ZPX headers that use simple or Chebyshev representation for the distortion polynomial. \item A bug has been fixed in the FitsChan class that caused headers including the Spitzer ``-SIP'' distortion code to be read incorrectly if no inverse polynomial was specified in the header. \item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It can be used to indicate that FITS headers that specify a TAN projection should be interpreted according to the ``distorted TAN'' convention included in an early draft of FITS-WCS paper II. Such headers are created by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}). \item The \htmlref{PolyMap}{PolyMap} class now provides a method called \htmlref{astPolyTran}{astPolyTran} that adds an inverse transformation to a PolyMap by sampling the forward transformation on a regular grid, and then fitting a polynomial function from the resulting output values to the grid of input values. \end{enumerate} \subsection{Changes Introduced in V5.7-1} The following describes the most significant changes which occurred in the AST library between versions V5.7-0 and V5.7-1: \begin{enumerate} \item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified text files, without the need to provide source and sink functions when the Channel is created. The files to use are specified by the new attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}. \item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header. \item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, the FitsChan class will now use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the inverse polynomial correction. \end{enumerate} \subsection{Changes Introduced in V5.7-2} The following describes the most significant changes which occurred in the AST library between versions V5.7-1 and V5.7-2: \begin{enumerate} \item The \htmlref{Object}{Object} class has a new function \htmlref{astToString}{astToString} (C only), which creates an in-memory textual serialisation of a given AST Object. A corresponding new function called \htmlref{astFromString}{astFromString} re-creates the Object from its serialisation. \item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to evaluate the inverse the inverse transformation if no inverse transformation is defined when the PolyMap is created. \item The \htmlref{FitsChan}{FitsChan} class has a new method \htmlref{astWriteFits}{astWriteFits} which writes out all cards currently in the FitsChan to the associated external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the sink function supplied when the FitsChan was created), and then empties the FitsChan. \item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which holds the number of keywords for which values are held in a FitsChan. \item The FitsChan astGetFits methods can now be used to returned the value of the current card. \item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which holds the data type of the keyword value for the current card. \item The FitsChan class has a new method \htmlref{astReadFits}{astReadFits} which forces the FitsChan to reads cards from the associated external source and appends them to the end of the FitsChan. \item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the -SIP (Spitzer) distortion code within the CTYPE values, but which does not provide an inverse polynomial correction, and for which the PolyTran method of the PolyMap class fails to create an accurate estimate of the inverse polynomial correction, then an iterative method will be used to evaluate the inverse correction for each point transformed. \end{enumerate} \subsection{Changes Introduced in V6.0} The following describes the most significant changes which occurred in the AST library between versions V5.7-2 and V6.0: \begin{enumerate} \item This version of AST is the first that can be used with the Python AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}. \item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the non-standard ``TPV'' projection code within a CTYPE keyword value. This code is used by SCAMP (see www.astromatic.net/software/scamp) to represent a distorted TAN projection. \item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as incorrectly rotated numerical axis labels) if the graphics coordinates have unequal scales on the X and Y axes. - The graphics escape sequences used to produce graphical sky axis labels can now be changed using the new function \htmlref{astTuneC}{astTuneC}. \end{enumerate} \subsection{Changes Introduced in V6.0-1} The following describes the most significant changes which occurred in the AST library between versions V6.0 and V6.0-1: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion code within FITS headers that describe non-celestial axes, as well as celestial axes. \item A bug has been fixed that could cause inappropriate equinox values to be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set. \item The versioning string for AST has changed from ``$.-$'' to ``$..$''. \end{enumerate} \subsection{Changes Introduced in V7.0.0} The following describes the most significant changes which occurred in the AST library between versions V6.0-1 and V7.0.0: \begin{enumerate} \item Fundamental positional astronomy calculations are now performed using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{} otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB library re-written in C). Copies of these libraries are bundled with AST and so do not need to be obtained or built separately, although external copies of SOFA and PAL can be used if necessary by including the ``\texttt{--with-external\_pal}'' option when configuring AST. \end{enumerate} \subsection{Changes Introduced in V7.0.1} The following describes the most significant changes which occurred in the AST library between versions V7.0.0 and V7.0.1: \begin{enumerate} \item The levmar and wcslib code distributed within AST is now stored in the main AST library (libast.so) rather than in separate libraries. \end{enumerate} \subsection{Changes Introduced in V7.0.2} The following describes the most significant changes which occurred in the AST library between versions V7.0.1 and V7.0.2: \begin{enumerate} \item The libast\_pal library is no longer built if the ``--with-external\_pal'' option is used when AST is configured. \end{enumerate} \subsection{Changes Introduced in V7.0.3} The following describes the most significant changes which occurred in the AST library between versions V7.0.2 and V7.0.3: \begin{enumerate} \item A bug has been fixed which could cause an incorrect axis to be used when accessing axis attributes within CmpFrames. This could happen if axes within the \htmlref{CmpFrame}{CmpFrame} have been permuted. \item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two values of the SkyRef and/or SkyRefP attributes to be reversed. \item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately. Previously, component Regions nested deeply inside a CmpRegion may have been completely or partially ignored. \item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation violation if the MinTick attribute was set to zero. \item The astResampleX set of methods now includes astResampleK and astResampleUK that handles 64 bit integer data. \end{enumerate} \subsection{Changes Introduced in V7.0.4} The following describes the most significant changes which occurred in the AST library between versions V7.0.3 and V7.0.4: \begin{enumerate} \item The previously private grf3d.h header file is now installed into prefix/include. \end{enumerate} \subsection{Changes Introduced in V7.0.5} The following describes the most significant changes which occurred in the AST library between versions V7.0.4 and V7.0.5: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO convention for representing distorted TAN projections, based on the use of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial. \end{enumerate} \subsection{Changes Introduced in V7.0.6} The following describes the most significant changes which occurred in the AST library between versions V7.0.5 and V7.0.6: \begin{enumerate} \item A bug has been fixed in astRebinSeq which could result in incorrect normalisation of the final binned data and variance values. \item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1 and CNPIX2 now default to zero if absent. Previously an error was reported. \end{enumerate} \subsection{Changes Introduced in V7.1.0} The following describes the most significant changes which occurred in the AST library between versions V7.0.6 and V7.1.0: \begin{enumerate} \item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied when calling astRebinSeq. Without this flag, each output value is a weighted mean of the neighbouring input values. \item A new flag AST\_\_NONORM can be used with astRebinSeq to indicate that normalisation of the output arrays is not required. In this case no weights array need be supplied. \item A bug has been fixed in \htmlref{astAddFrame}{astAddFrame} method that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet} when the AST\_\_ALLFRAMES flag is supplied for the "iframe" parameter. \item The \htmlref{astRate}{astRate} method has been re-written to make it faster and more reliable. \end{enumerate} \subsection{Changes Introduced in V7.1.1} The following describes the most significant changes which occurred in the AST library between versions V7.1.0 and V7.1.1: \begin{enumerate} \item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute \htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions are now created - one for the offset coordinates and one for the absolute coordinates. If such a header is subsequently read back into AST, the original offset SkyFrame is recreated. \item A bug has been fixed in FitsChan that caused inappropriate CTYPE values to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a SkyFrame with \htmlref{System}{System}=Unknown). \end{enumerate} \subsection{Changes Introduced in V7.2.0} The following describes the most significant changes which occurred in the AST library between versions V7.1.1 and V7.2.0: \begin{enumerate} \item A new method call \htmlref{astMapDefined}{astMapDefined} has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has a defined value in a given KeyMap. \end{enumerate} \subsection{Changes Introduced in V7.3.0} The following describes the most significant changes which occurred in the AST library between versions V7.2.0 and V7.3.0: \begin{enumerate} \item The interface for the astRebinSeq family of functions has been changed in order to allow a greater number of pixels to be pasted into the output array. The "nused" parameter is now a pointer to a "int64\_t" variable, instead of an "int". APPLICATION CODE SHOULD BE CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC BEHAVIOUR. \item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be associated with multiple Mappings, any one of which can be used to connect the Frame to the other Frames in the FrameSet. The choice of which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the FrameSet class. \item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident} attribute are now left unchanged by the c \htmlref{astSimplify}{astSimplify} function. f AST\_SIMPLIFY routine. \end{enumerate} \subsection{Changes Introduced in V7.3.1} The following describes the most significant changes which occurred in the AST library between versions V7.3.0 and V7.3.1: \begin{enumerate} \item Fix a bug that could cauise a segmentation violation when reading certain FITS headers that use a TNX projection. \end{enumerate} \subsection{Changes Introduced in V7.3.2} The following describes the most significant changes which occurred in the AST library between versions V7.3.1 and V7.3.2: \begin{enumerate} \item Fix support for reading FITS header that use a GLS projection. Previously, an incorrect transformation was used for such projections if any CRVAL or CROTA value was non-zero. \item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and ``KeyAgeDown'' that retain the position of an existing entry if its value is changed. See the \htmlref{SortBy}{SortBy} attribute. \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords for sky axes to be treated as radians rather than degrees when reading a FITS header, if the corresponding CTYPE values included no projection code. \end{enumerate} \subsection{Changes Introduced in V7.3.3} The following describes the most significant changes which occurred in the AST library between versions V7.3.2 and V7.3.3: \begin{enumerate} \item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold the keyword name and comment of the current card. \item When using the FitsChan class to read FITS-WCS headers that include polynomial distortion in the SIP format, any inverse transformation specified in the header is now ignored and a new inverse is created to replace it based on the supplied forward transformation. Previously, an inverse was created only if the header did not include an inverse. The accuracy of the inverse transformation has also been improved, although it may now be slower to evaluate in some circumstances. \end{enumerate} \subsection{Changes Introduced in V7.3.4} The following describes the most significant changes which occurred in the AST library between versions V7.3.3 and V7.3.4: \begin{enumerate} \item By default, the simplification of Polygons no longer checks that the edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices}, can be set to zero in order to re-instate this check. \item The \htmlref{Polygon}{Polygon} class has a new mathod, astConvex, that returns a Polygon representing the shortest polygon (i.e. convex hull) enclosing a specified set of pixel values within a supplied array. \end{enumerate} \subsection{Changes Introduced in V8.0.0} The following describes the most significant changes which occurred in the AST library between versions V7.3.4 and V8.0.0: \begin{enumerate} \item AST is now distributed under the Lesser GPL licence. \item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform least squares fitting of N-dimensional polynomials. \item Use of the IAU SOFA library has been replaced by ERFA library, which is a re-badged copy of SOFA distributed under a less restrictive license. A copy of ERFA is included within AST. \end{enumerate} \subsection{Changes Introduced in V8.0.1} The following describes the most significant changes which occurred in the AST library between versions V8.0.0 and V8.0.1: \begin{enumerate} \item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}. \item The order of WCS axes within new FITS-WCS headers created by \htmlref{astWrite}{astWrite} can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}. \item Supported added for FITS XPH (polar HEALPIX) projection. \item The macro used to invoke the \htmlref{astAppendString}{astAppendString} utility function has changed to allow printf-style converstions to be included in the supplied text. Any code that uses this macro must be re-compiled. \item The astRebin and astRebinSeq family of functions now include support for arrays with char (byte) and unsigned char (unsigned byte) data types. \end{enumerate} \subsection{Changes Introduced in V8.0.2} The following describes the most significant changes which occurred in the AST library between versions V8.0.1 and V8.0.2: \begin{enumerate} \item For security reasons, the change introduced to \htmlref{astAppendString}{astAppendString} in V8.0.1 has been moved to a new function called \htmlref{astAppendStringf}{astAppendStringf}, and astAppendString itself has been reverted to its V8.0.0 version. Any software that has been built against V8.0.1 will need to be re-compiled and re-linked against V8.0.2. \end{enumerate} \subsection{Changes Introduced in V8.0.3} The following describes the most significant changes which occurred in the AST library between versions V8.0.2 and V8.0.3: \begin{enumerate} \item Methods astRebin, astRebinSeq, astResample and \htmlref{astTranGrid}{astTranGrid} now report an error if an array is specified that has more pixels than can be counted by a 32 bit integer. \item The hypertext documentation is now generated using Tex4HT rather than latex2html. The format of the hypertext docs has changed significantly. \item Another bug fix associated with reading CAR projections from FITS-WCS headers. \item Constructor options strings of the form ``\texttt{..., "\%s", text );}'' can now be supplied. This avoids a security issue associated with the alternative form ``\texttt{..., text );}''. \end{enumerate} \subsection{Changes Introduced in V8.0.4} The following describes the most significant changes which occurred in the AST library between versions V8.0.3 and V8.0.4: \begin{enumerate} \item The behaviour of the \htmlref{astAddFrame}{astAddFrame} method has been changed slightly. Previously, astAddFrame modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and \htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes to the current Frame of the modified FrameSet also affected the supplied Frame object. Now, deep copies of the Mapping and Frame objects (rather than references) are stored within the modified FrameSet. This means that subsequent changes to the modified FrameSet will now have no effect on the supplied Frame. \item The choice of default tick-mark gaps for time axes has been improved, to avoid a previous issue which could result in no suitable gap being found. - A new method called \htmlref{astRegionOutline}{astRegionOutline} has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST \htmlref{Region}{Region}. \item A bug has been fixed that could cause astSimplfy to enter an infinite loop. \item Some improvements have been made to the Mapping simplification process that allow more Mappings to be simplified. \item The Frame class has a new read-only attribute called InternalUnit, which gives the units used for the unformatted (i.e. floating-point) axis values used internally by application code. For most Frames, the InternalUnit value is just the same as the Unit value (i.e. formatted and unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of Unit, indicating that floating-point SkyFrame axis values are always in units of radians. \item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies the relative error of the values in the table. It is used to decide if the LutMap can be simplified to a straight line. \end{enumerate} \subsection{Changes Introduced in V8.0.5} The following describes the most significant changes which occurred in the AST library between versions V8.0.4 and V8.0.5: \begin{enumerate} \item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies the smallest significant distance within the SkyFrame. It is used to decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit transformation. The default value is 0.001 arc-seconds. \item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal characters within FITS keyword names (i.e. characters not allowed by the FITS standard) being detected. This bug could under some circumstances cause a subsequent segmentation violation to occur. \item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS keyword name is encountered that contains any illegal characters. See attribute ``\htmlref{Warnings}{Warnings}'' and function ``\htmlref{astWarnings}{astWarnings}''. \end{enumerate} \subsection{Changes Introduced in V8.1.0} The following describes the most significant changes which occurred in the AST library between versions V8.0.5 and V8.1.0: \begin{enumerate} \item The configure script has a new option ``--without-fortran'' that allows AST to be built in situations where no Fortran compiler is available. The resulting library has no Fortran interface and so cannot be used within Fortran applications. Also, the link scripts do not attempt to include the fortran runtime libraries. \end{enumerate} \subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes Introduced in V8.2} The following describes the most significant changes which occurred in the AST library between versions V8.1.0 and V8.2.0: \begin{enumerate} \item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts a vector to a unit vector relative to a specified centre, plus length. A UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates represent a unit vector parallel to the supplied input vector, and the (N+1)'th output coordinate is the length of the input vector. \item The restriction that Mappings are immutable has been extended to all Mapping classes. This means that attributes representing parameters of a Mapping's forward or inverse transformation cannot be changed after the Mapping has been created. In order to minimise the risk to existing software, this rule does not apply to Mappings that have not yet been included in other objects such as CmpMaps or FrameSets, or which have not yet been cloned. In other words, an error is reported if an attempt is made to change the nature of a Mapping's transformation, but only if the reference count of the Mapping is greater than one. The Mapping classes affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}. \end{enumerate} \subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes Introduced in V8.3} The following describes the most significant changes which have occurred in the AST library between versions V8.2.0 and V8.3.0 (the current version): \begin{enumerate} \item A new method called \htmlref{astAxNorm}{astAxNorm} has been added to the \htmlref{Frame}{Frame} class that normalises an array of axis values. When used with SkyFrames, it allows longitude values to be normalised into the shortest range. \item A bug has been fixed in the \htmlref{astGetRegionBounds}{astGetRegionBounds} method that could cause the wrong bounds to be returned for regions spanning a longitude = zero singularity. \end{enumerate} % Programs which are statically linked will need to be re-linked in % order to take advantage of these new facilities. \end{document} ast-8.3.0/stc.c0000664000175000017500000035173313004147321010200 00000000000000/* *class++ * Name: * Stc * Purpose: * Represents an instance of the IVOA STC class. * Constructor Function: c astStc f AST_STC * Description: * The Stc class is an implementation of the IVOA STC class which forms * part of the IVOA Space-Time Coordinate Metadata system. See: * * http://hea-www.harvard.edu/~arots/nvometa/STC.html * * The Stc class does not have a constructor function of its own, as it * is simply a container class for a family of specialised sub-classes * including StcCatalogEntryLocation, StcResourceProfile, StcSearchLocation * and StcObsDataLocation. * Inheritance: * The Stc class inherits from the Region class. * Attributes: * In addition to those attributes common to all Regions, every * Stc also has the following attributes: * * - RegionClass: The class name of the encapsulated Region. * Functions: c In addition to those functions applicable to all Regions, the c following functions may also be applied to all Stc's: f In addition to those routines applicable to all Regions, the f following routines may also be applied to all Stc's: * c - astGetStcRegion: Get a pointer to the encapsulated Region f - AST_GETSTCREGION: Get a pointer to the encapsulated Region c - astGetStcCoord: Get information about an AstroCoords element f - AST_GETSTCCOORD: Get information about an AstroCoords element c - astGetStcNCoord: Returns the number of AstroCoords elements in an Stc f - AST_GETSTCNCOORD: Returns the number of AstroCoords elements in an Stc * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-NOV-2004 (DSB): * Original version. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 13-MAR-2009 (DSB): * Over-ride astRegBasePick. *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 Stc /* The number of components in an AstroCoords element which are described using a Region within a KeyMap. */ #define NREG 5 /* Include 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 "unitmap.h" /* Unit Mappings */ #include "region.h" /* Regions (parent class) */ #include "channel.h" /* I/O channels */ #include "stc.h" /* Interface definition for this class */ #include "keymap.h" /* Lists of value/key pairs */ #include "pointlist.h" /* Individual points in a Frame */ #include "ellipse.h" /* Ellipses within a Frame */ #include "interval.h" /* Axis intervals within a Frame */ #include "prism.h" /* Extrusions into higher dimensions */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 AstMapping *(* parent_simplify)( AstMapping *, int * ); static AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *(* parent_getdefunc)( AstRegion *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_equal)( AstObject *, AstObject *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_getusedefs)( AstObject *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (*parent_regclearattrib)( AstRegion *, const char *, char **, int * ); static void (*parent_regsetattrib)( AstRegion *, const char *, char **, int * ); static void (* parent_clearnegated)( AstRegion *, int * ); static void (* parent_clearclosed)( AstRegion *, int * ); static void (* parent_clearfillfactor)( AstRegion *, int * ); static void (* parent_clearmeshsize)( AstRegion *, int * ); static void (* parent_setclosed)( AstRegion *, int, int * ); static void (* parent_setfillfactor)( AstRegion *, double, int * ); static void (* parent_setmeshsize)( AstRegion *, int, int * ); static void (* parent_setnegated)( AstRegion *, int, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* The keys associated with each component of an AstroCoords element within KeyMap */ static const char *regkey[ NREG ] = { AST__STCERROR, AST__STCRES, AST__STCSIZE, AST__STCPIXSZ, AST__STCVALUE }; /* The comments associated with each component of an AstroCoords element within KeyMap */ static const char *regcom[ NREG ] = { "AstroCoords error region", "AstroCoords resolution region", "AstroCoords size region", "AstroCoords pixel size region", "AstroCoords value region" }; #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Stc) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Stc,Class_Init) #define class_vtab astGLOBAL(Stc,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstStcVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External Interface Function Prototypes. */ /* ======================================= */ /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstKeyMap *GetStcCoord( AstStc *, int, int * ); static AstKeyMap *MakeAstroCoordsKeyMap( AstRegion *, AstKeyMap *, const char *, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *GetDefUnc( AstRegion *, int * ); static AstRegion *GetStcRegion( AstStc *, int * ); static AstRegion *RegBasePick( AstRegion *this, int, const int *, int * ); static const char *GetRegionClass( AstStc *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetBounded( AstRegion *, int * ); static int GetObjSize( AstObject *, int * ); static int GetStcNCoord( AstStc *, int * ); static int GetUseDefs( AstObject *, int * ); static int Overlap( AstRegion *, AstRegion *, int * ); static int OverlapX( AstRegion *, AstRegion *, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void GetRegion( AstStc *, AstRegion **, int *, int * ); static void RegBaseBox( AstRegion *, double *, double *, int * ); static void RegClearAttrib( AstRegion *, const char *, char **, int * ); static void RegSetAttrib( AstRegion *, const char *, char **, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearClosed( AstRegion *, int * ); static int GetClosed( AstRegion *, int * ); static void SetClosed( AstRegion *, int, int * ); static int TestClosed( AstRegion *, int * ); static void ClearMeshSize( AstRegion *, int * ); static int GetMeshSize( AstRegion *, int * ); static void SetMeshSize( AstRegion *, int, int * ); static int TestMeshSize( AstRegion *, int * ); static void ClearFillFactor( AstRegion *, int * ); static double GetFillFactor( AstRegion *, int * ); static void SetFillFactor( AstRegion *, double, int * ); static int TestFillFactor( AstRegion *, int * ); static void ClearNegated( AstRegion *, int * ); static int GetNegated( AstRegion *, int * ); static void SetNegated( AstRegion *, int, int * ); static int TestNegated( AstRegion *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Stc member function (over-rides the astClearAttrib protected * method inherited from the Region class). * Description: * This function clears the value of a specified attribute for a * Stc, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Stc. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstStc *this; /* Pointer to the Stc structure */ int len; /* Length of attrib string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* (none as yet) */ /* ------------- */ /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then report an error. */ if ( !strcmp( attrib, "regionclass" ) ) { 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); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Objects are equivalent. * Type: * Private function. * Synopsis: * #include "stc.h" * int Equal( AstObject *this_object, AstObject *that_object, int *status ) * Class Membership: * Stc member function (over-rides the astEqual protected * method inherited from the Region class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Stcs are equivalent. * Parameters: * this * Pointer to the first Stc. * that * Pointer to the second Stc. * status * Pointer to the inherited status variable. * Returned Value: * One if the Stcs are equivalent, zero otherwise. * Notes: * - The Stcs are equivalent if their encapsulated Region are * equivalent, and if they have the same boolean operation, negation * and closed flags. * - 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: */ AstStc *that; AstStc *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the Equal method inherited from the parent Region class. This checks that the Objects are both of the same class, and have the same Negated and Closed flags (amongst other things). */ if( (*parent_equal)( this_object, that_object, status ) ) { /* Obtain pointers to the two Stc structures. */ this = (AstStc *) this_object; that = (AstStc *) that_object; /* Test their encapsulated Region for equality. */ result = astEqual( this->region, that->region ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } /* * Name: * MAKE_SET * Purpose: * Define a function to set an attribute value for a Stc. * Type: * Private macro. * Synopsis: * #include "stc.h" * MAKE_SET(attribute,lattribute,type) * Class Membership: * Defined by the Stc class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static void Set( AstRegion *this, value ) * * that sets the value of a specified Region attribute in the parent * Region structure and also in the encapsulated Region. * Parameters: * attribute * Name of the attribute, as it appears in the function name. * lattribute * Name of the attribute, all in lower case. * type * The C type of the attribute. */ /* Define the macro. */ #define MAKE_SET(attribute,lattribute,type) \ static void Set##attribute( AstRegion *this_region, type value, int *status ) { \ \ /* Local Variables: */ \ AstStc *this; /* Pointer to the Stc structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Use the parent method to set the value in the parent Region structure. */ \ (*parent_set##lattribute)( this_region, value, status ); \ \ /* Also set the value in the encapsulated Region. */ \ this = (AstStc *) this_region; \ astSet##attribute( this->region, value ); \ } /* Use the above macro to create accessors for the MeshSize, Closed and FillFactor attributes. */ MAKE_SET(FillFactor,fillfactor,double) MAKE_SET(MeshSize,meshsize,int) MAKE_SET(Closed,closed,int) MAKE_SET(Negated,negated,int) /* Undefine the macro. */ #undef MAKE_SET /* * Name: * MAKE_CLEAR * Purpose: * Define a function to clear an attribute value for a Stc. * Type: * Private macro. * Synopsis: * #include "stc.h" * MAKE_CLEAR(attribute,lattribute) * Class Membership: * Defined by the Stc class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static void Clear( AstRegion *this ) * * that sets the value of a specified Region attribute in the parent * Region structure and also in the encapsulated Region. * Parameters: * attribute * Name of the attribute, as it appears in the function name. * lattribute * Name of the attribute, all in lower case. */ /* Define the macro. */ #define MAKE_CLEAR(attribute,lattribute) \ static void Clear##attribute( AstRegion *this_region, int *status ) { \ \ /* Local Variables: */ \ AstStc *this; /* Pointer to the Stc structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Use the parent method to clear the value in the parent Region structure. */ \ (*parent_clear##lattribute)( this_region, status ); \ \ /* Also clear the value in the encapsulated Region. */ \ this = (AstStc *) this_region; \ astClear##attribute( this->region ); \ } /* Use the above macro to create accessors for the MeshSize, Closed and FillFactor attributes. */ MAKE_CLEAR(FillFactor,fillfactor) MAKE_CLEAR(MeshSize,meshsize) MAKE_CLEAR(Closed,closed) MAKE_CLEAR(Negated,negated) /* Undefine the macro. */ #undef MAKE_CLEAR /* * Name: * MAKE_GET * Purpose: * Define a function to get an attribute value for a Stc. * Type: * Private macro. * Synopsis: * #include "stc.h" * MAKE_GET(attribute,type,bad) * Class Membership: * Defined by the Stc class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static Get( AstRegion *this ) * * that gets the value of a specified Region attribute from the encapsulated * Region. * Parameters: * attribute * Name of the attribute, as it appears in the function name. * type * The C type of the attribute. * bad * Value to return in caseof error. */ /* Define the macro. */ #define MAKE_GET(attribute,type,bad) \ static type Get##attribute( AstRegion *this_region, int *status ) { \ \ /* Local Variables: */ \ AstStc *this; /* Pointer to the Stc structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad); \ \ /* Get the value from the encapsulated Region. */ \ this = (AstStc *) this_region; \ return astGet##attribute( this->region ); \ } /* Use the above macro to create accessors for the MeshSize, Closed and FillFactor attributes. */ MAKE_GET(FillFactor,double,AST__BAD) MAKE_GET(MeshSize,int,100) MAKE_GET(Closed,int,1) MAKE_GET(Negated,int,0) /* Undefine the macro. */ #undef MAKE_GET /* * Name: * MAKE_TEST * Purpose: * Define a function to test an attribute value for a Stc. * Type: * Private macro. * Synopsis: * #include "stc.h" * MAKE_TEST(attribute) * Class Membership: * Defined by the Stc class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static int Test( AstRegion *this ) * * that test the value of a specified Region attribute from the encapsulated * Region. * 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_TEST(attribute) \ static int Test##attribute( AstRegion *this_region, int *status ) { \ \ /* Local Variables: */ \ AstStc *this; /* Pointer to the Stc structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Test the value from the encapsulated Region. */ \ this = (AstStc *) this_region; \ return astTest##attribute( this->region ); \ } /* Use the above macro to create accessors for the MeshSize, Closed and FillFactor attributes. */ MAKE_TEST(FillFactor) MAKE_TEST(MeshSize) MAKE_TEST(Closed) MAKE_TEST(Negated) /* Undefine the macro. */ #undef MAKE_TEST static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "stc.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Stc member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Stc, * in bytes. * Parameters: * this * Pointer to the Stc. * 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: */ AstStc *this; /* Pointer to Stc structure */ int result; /* Result value to return */ int i; /* AstroCoords index */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Stc structure. */ this = (AstStc *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->region ); if( this->coord ) { for( i = 0; i < this->ncoord; i++ ) { result += astGetObjSize( this->coord[ i ] ); } result += astTSizeOf( this->coord ); } /* 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 Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Stc member function (over-rides the protected astGetAttrib * method inherited from the Region class). * Description: * This function returns a pointer to the value of a specified * attribute for a Stc, formatted as a character string. * Parameters: * this * Pointer to the Stc. * 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 Stc, 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 Stc. 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: */ AstStc *this; /* Pointer to the Stc structure */ const char *result; /* Pointer value to return */ int len; /* Length of attrib string */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Compare "attrib" with each recognised attribute name in turn, obtaining the value of the required attribute. If necessary, write the value into "buff" as a null-terminated string in an appropriate format. Set "result" to point at the result string. */ /* RegionClass. */ /* ------------ */ if ( !strcmp( attrib, "regionclass" ) ) { result = astGetClass( this->region ); /* Not recognised. */ /* --------------- */ /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetBounded( AstRegion *this_region, int *status ) { /* * Name: * GetBounded * Purpose: * Is the Region bounded? * Type: * Private function. * Synopsis: * #include "stc.h" * int GetBounded( AstRegion *this, int *status ) * Class Membership: * Stc method (over-rides the astGetBounded method inherited from * the Region class). * Description: * This function returns a flag indicating if the Region is bounded. * The implementation provided by the base Region class is suitable * for Region sub-classes representing the inside of a single closed * curve (e.g. Circle, Ellipse, Box, etc). Other sub-classes (such as * Stc, PointList, etc ) may need to provide their own implementations. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Region is bounded. Zero otherwise. */ /* Local Variables: */ AstStc *this; /* Pointer to Stc structure */ AstRegion *reg; /* Pointer to the encapsulated Region */ int neg; /* Negated flag to use */ int neg_old; /* Original Negated flag */ int result; /* Returned result */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Stc structure. */ this = (AstStc *) this_region; /* Get the encapsulated Region, and the Negated value which should be used with it. The returned values take account of whether the supplied Stc has itself been Negated or not. The returned Region represent a region within the base Frame of the FrameSet encapsulated by the parent Region structure. */ GetRegion( this, ®, &neg, status ); /* Temporarily set the Negated attribute to the required value.*/ neg_old = astGetNegated( reg ); astSetNegated( reg, neg ); /* See if the encapsulated Region is bounded. */ result = astGetBounded( reg ); /* Re-instate the original value for the Negated attribute of the encapsulated Region. */ if( reg ) astSetNegated( reg, neg_old ); /* Free resources. */ reg = astAnnul( reg ); /* Return zero if an error occurred. */ if( !astOK ) result = 0; /* Return the required pointer. */ return result; } static AstRegion *GetDefUnc( AstRegion *this_region, int *status ) { /* * Name: * GetDefUnc * Purpose: * Obtain a pointer to the default uncertainty Region for a given Region. * Type: * Private function. * Synopsis: * #include "stc.h" * AstRegion *GetDefUnc( AstRegion *this ) * Class Membership: * Stc method (over-rides the astGetDefUnc method inherited from * the Region class). * This function returns a pointer to a Region which represents the * default uncertainty associated with a position on the boundary of the * given Region. The returned Region refers to the base Frame within the * FrameSet encapsulated by the supplied Region. * Parameters: * this * Pointer to the Region. * Returned Value: * A pointer to the Region. This should be annulled (using astAnnul) * when no longer needed. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstStc *this; /* Pointer to the Stc structure */ AstRegion *result; /* Returned pointer */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Stc structure. */ this = (AstStc *) this_region; /* If the encapsulated region has non-default uncertainty, use it as the default uncertainty for the Cmpregion. Note, the current Frame of an uncertainty Region is assumed to be the same as the base Frame in the Stc. */ if( astTestUnc( this->region ) ) { result = astGetUncFrm( this->region, AST__CURRENT ); /* Otherwise, use the parent method to determine the default uncertainty. */ } else { result = (* parent_getdefunc)( this_region, status ); } /* Return NULL if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the required pointer. */ return result; } static void GetRegion( AstStc *this, AstRegion **reg, int *neg, int *status ) { /* * * Name: * GetRegion * Purpose: * Get the encapsulated Region of a Stc. * Type: * Private function. * Synopsis: * #include "region.h" * void GetRegion( AstStc *this, AstRegion **reg, int *neg, int *status ) * Class Membership: * Stc member function * Description: * This function returns a pointer to a Region which is equivalent to * the supplied Stc. If the Stc has been negated, then the returned * "negated" flag will be set such that it represents the negated Stc. * * The current Frames in returned encapsulated Region will be equivalent * to the base Frame in the FrameSet encapsulated by the parent Region * structure. * Parameters: * this * Pointer to the Stc. * reg * Address of a location to receive a pointer to the encapsulated * Region. The current Frame in this region will be equivalent to * the base Frame in the FrameSet * neg * The value of the Negated attribute to be used with reg. * status * Pointer to the inherited status variable. * Notes: * - Any changes made to the encapsulated Region using the returned * pointer will be reflected in the supplied Stc. */ /* Initialise */ if( reg ) *reg = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Return the component Region pointers. */ if( reg ) *reg = astClone( this->region ); /* Initialise the other returned items. Note, the Stc initialiser stored a deep copy of the supplied encapsulated Region, and so we do not need to worry about attributes of the Region having been changed after the creation of the Stc. This is different to the CmpMap class which merely clones its supplied component pointers and so has to save copies of the original Invert settings within the CmpMap structure. */ if( neg ) *neg = astGetNegated( this->region ); /* If the Stc has been inverted, we modify the boolean operator and negation flags so that they reflect the inverted Stc. */ if( astGetNegated( this ) && neg ) *neg = *neg ? 0 : 1; } static const char *GetRegionClass( AstStc *this, int *status ){ /* *+ * Name: * astGetRegionClass * Purpose: * Get the value of a RegionClass attribute for a Stc. * Type: * Protected function. * Synopsis: * #include "stc.h" * const char *astGetRegionClass( AstStc *this ) * Class Membership: * Stc virtual function * Description: * This function returns a pointer to the value of the RegionClass * attribute for a Stc. * Parameters: * this * Pointer to the Stc. * Returned Value: * - Pointer to a null-terminated string containing the attribute * value. * Notes: * - The returned string pointer may point at memory allocated * within the Stc, 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 Stc. 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. *- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain and return the class of the encapsulated Region. */ return astGetClass( ((AstStc *) this)->region ); } static AstKeyMap *GetStcCoord( AstStc *this, int icoord, int *status ){ /* *++ * Name: c astGetStcCoord f AST_GETSTCCOORD * Purpose: * Return information about an AstroCoords element stored in an Stc. * Type: * Public virtual function. * Synopsis: c #include "specframe.h" c AstKeyMap *astGetStcCoord( AstStc *this, int icoord ) f RESULT = AST_GETSTCCOORD( THIS, ICOORD, STATUS ) * Class Membership: * Stc method. * Description: * When any sub-class of Stc is created, the constructor function * allows one or more AstroCoords elements to be stored within the Stc. * This function allows any one of these AstroCoords elements to be * retrieved. The format of the returned information is the same as * that used to pass the original information to the Stc constructor. * That is, the information is returned in a KeyMap structure * containing elements with one or more of the keys given by symbolic * constants AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, * AST__STCSIZE and AST__STCPIXSZ. * * If the coordinate system represented by the Stc has been changed * since it was created (for instance, by changing its System * attribute), then the sizes and positions in the returned KeyMap * will reflect the change in coordinate system. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Stc. c icoord f ICOORD = INTEGER (Given) * The index of the AstroCoords element required. The first has index * one. The number of AstroCoords elements in the Stc can be found using c function astGetStcNcoord. f function AST_GETSTCNCOORD. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetStcCoord() f AST_GETSTCCOORD = INTEGER * A pointer to a new KeyMap containing the required information. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ AstFrame *frm; AstKeyMap *result; AstMapping *map; AstMapping *smap; AstObject *obj; AstRegion *reg; AstRegion *rereg; AstRegion *srereg; int ikey; int nc; /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the supplied index. */ nc = astGetStcNCoord( this ); if( icoord < 1 || icoord > nc ) { astError( AST__STCIND, "astGetStcCoord(%s): Supplied AstroCoords " "index (%d) is invalid.", status, astGetClass( this ), icoord ); if( icoord < 1 ) { astError( AST__STCIND, "The index of the first AstroCoord " "element is one, not zero." , status); } else if( nc == 0 ) { astError( AST__STCIND, "There are no AstroCoords elements in " "the supplied %s.", status, astGetClass( this ) ); } else if( nc == 1 ) { astError( AST__STCIND, "There is 1 AstroCoords element in " "the supplied %s.", status, astGetClass( this ) ); } else { astError( AST__STCIND, "There are %d AstroCoords elements in " "the supplied %s.", status, nc, astGetClass( this ) ); } /* If the index is OK, initialise the returned KeyMap to be a copy of the KeyMap holding information about the required AstroCoords element.*/ } else { result = astCopy( this->coord[ icoord - 1 ] ); /* The Regions stored within this KeyMap describe regions within the base Frame of the parent Region structure. If the Mapping from base to current Frame in the parent Region structure is not a UnitMap, we need to change these to represent regions within the current Frame of the parent Region structure. */ map = astGetMapping( ((AstRegion *)this)->frameset, AST__BASE, AST__CURRENT ); smap = astSimplify( map ); frm = astGetFrame( ((AstRegion *)this)->frameset, AST__CURRENT ); /* If the Frame represented by the Region has changed, erase the Names element since they may no longer be correct. */ if( !astIsAUnitMap( smap ) ) astMapRemove( result, AST__STCNAME ); /* Loop round keys for which a Region may be stored in the KeyMap. */ for( ikey = 0; ikey < NREG; ikey++ ) { /* If the KeyMap contains a Region for this key, get a pointer to it. */ if( astMapGet0A( result, regkey[ ikey ], &obj ) ){ reg = (AstRegion *) obj; /* Sets its RegionFS attribute so that the encapsulated FrameSet will be included in any dump of the Region. This is needed since the returned Region pointer will have no parent Region from which the FrameSet can be determined. */ astSetRegionFS( reg, 1 ); /* If necessary, remap the Region into the current Frame, and simplify. */ if( !astIsAUnitMap( smap ) ) { rereg = astMapRegion( reg, smap, frm ); srereg = astSimplify( rereg ); rereg = astAnnul( rereg ); } else { srereg = astClone( reg ); } /* Replace the Region in the KeyMap with the remapped Region. */ astMapPut0A( result, regkey[ ikey ], srereg, NULL ); /* Free resources */ reg = astAnnul( reg ); srereg = astAnnul( srereg ); } } frm = astAnnul( frm ); map = astAnnul( map ); smap = astAnnul( smap ); /* Annul the returned KeyMap if an error has occurred. */ if( !astOK ) result = astAnnul( result ); } /* Return the pointer */ return result; } static int GetStcNCoord( AstStc *this, int *status ){ /* *++ * Name: c astGetStcNCoord f AST_GETSTCNCOORD * Purpose: * Return the number of AstroCoords elements stored in an Stc. * Type: * Public virtual function. * Synopsis: c #include "stc.h" c int astGetStcNCoord( AstStc *this ) f RESULT = AST_GETSTCNCOORD( THIS, STATUS ) * Class Membership: * Stc method. * Description: * This function returns the number of AstroCoords elements stored in * an Stc. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Stc. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetStcNCoord() f AST_GETSTCNCOORD = INTEGER * The number of AstroCoords elements stored in the Stc. * Notes: * - Zero 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. *-- */ /* Return the required value. */ return astOK ? this->ncoord : 0; } static AstRegion *GetStcRegion( AstStc *this, int *status ) { /* *++ * Name: c astGetStcRegion f AST_GETSTCREGION * Purpose: * Obtain a copy of the encapsulated Region within a Stc. * Type: * Public virtual function. * Synopsis: c #include "stc.h" c AstRegion *astGetStcRegion( AstStc *this ) f RESULT = AST_GETSTCREGION( THIS, STATUS ) * Class Membership: * Region method. * Description: * This function returns a pointer to a deep copy of the Region * supplied when the Stc was created. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Stc. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetStcRegion() f AST_GETSTCREGION = INTEGER * A pointer to a deep copy of the Region encapsulated within the * supplied Stc. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Return a pointer to a copy of the encapsulated Region. */ return astCopy( this->region ); } static int GetUseDefs( AstObject *this_object, int *status ) { /* * Name: * GetUseDefs * Purpose: * Get the value of the UseDefs attribute for a Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * int GetUseDefs( AstObject *this_object, int *status ) { * Class Membership: * Stc member function (over-rides the protected astGetUseDefs * method inherited from the Region class). * Description: * This function returns the value of the UseDefs attribute for a * Stc, supplying a suitable default. * Parameters: * this * Pointer to the Stc. * status * Pointer to the inherited status variable. * Returned Value: * - The USeDefs value. */ /* Local Variables: */ AstStc *this; /* Pointer to the Stc structure */ int result; /* Value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) this_object; /* If the UseDefs value for the Stc has been set explicitly, use the Get method inherited from the parent Region class to get its value. */ if( astTestUseDefs( this ) ) { result = (*parent_getusedefs)( this_object, status ); /* Otherwise, supply a default value equal to the UseDefs value of the encapsulated Region. */ } else { result = astGetUseDefs( this->region ); } /* Return the result. */ return result; } void astInitStcVtab_( AstStcVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitStcVtab * Purpose: * Initialise a virtual function table for a Stc. * Type: * Protected function. * Synopsis: * #include "stc.h" * void astInitStcVtab( AstStcVtab *vtab, const char *name ) * Class Membership: * Stc vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Stc class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAStc) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->GetRegionClass = GetRegionClass; vtab->GetStcRegion = GetStcRegion; vtab->GetStcCoord = GetStcCoord; vtab->GetStcNCoord = GetStcNCoord; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_equal = object->Equal; object->Equal = Equal; parent_clearclosed = region->ClearClosed; region->ClearClosed = ClearClosed; parent_setclosed = region->SetClosed; region->SetClosed = SetClosed; region->TestClosed = TestClosed; region->GetClosed = GetClosed; parent_regsetattrib = region->RegSetAttrib; region->RegSetAttrib = RegSetAttrib; parent_regclearattrib = region->RegClearAttrib; region->RegClearAttrib = RegClearAttrib; parent_clearnegated = region->ClearNegated; region->ClearNegated = ClearNegated; parent_setnegated = region->SetNegated; region->SetNegated = SetNegated; region->TestNegated = TestNegated; region->GetNegated = GetNegated; parent_setmeshsize = region->SetMeshSize; region->SetMeshSize = SetMeshSize; parent_clearmeshsize = region->ClearMeshSize; region->ClearMeshSize = ClearMeshSize; region->TestMeshSize = TestMeshSize; region->GetMeshSize = GetMeshSize; parent_setfillfactor = region->SetFillFactor; region->SetFillFactor = SetFillFactor; parent_clearfillfactor = region->ClearFillFactor; region->ClearFillFactor = ClearFillFactor; region->TestFillFactor = TestFillFactor; region->GetFillFactor = GetFillFactor; parent_getusedefs = object->GetUseDefs; object->GetUseDefs = GetUseDefs; parent_getdefunc = region->GetDefUnc; region->GetDefUnc = GetDefUnc; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ region->Overlap = Overlap; region->OverlapX = OverlapX; region->RegBaseBox = RegBaseBox; region->RegBaseMesh = RegBaseMesh; region->RegBasePick = RegBasePick; region->RegPins = RegPins; region->GetBounded = GetBounded; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "Stc", "An IVOA Space-Time-Coords object" ); /* 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 AstKeyMap *MakeAstroCoordsKeyMap( AstRegion *reg, AstKeyMap *coord, const char *class, int *status ){ /* * Name: * MakeAstroCoordsKeyMap * Purpose: * Create a new KeyMap holding Regions describing a supplied * AstroCoords element. * Type: * Private function. * Synopsis: * #include "stc.h" * AstKeyMap *MakeAstroCoordsKeyMap( AstRegion *reg, AstKeyMap *coord, * const char *class, int *status ) * Class Membership: * Stc member function * Description: * This function returns a pointer to a new KeyMap containing elements * which correspond to the components of an STC AstroCoords element. * The element with key AST__STCNAME holds a vector of character * strings containing the names associated with each of the axies. * The other elements of the returned KeyMap such as AST__STCERROR, * AST__STCRES, etc, hold pointers to Regions describing the error * box, resolution, etc, in the Frame of the supplied Region "reg". * Parameters: * reg * Pointer to the Region in which the AstroCoords is defined. * coordId * An ID (not a pointer) to a KeyMap defining a single * element, having elements with keys given by constants AST__STCNAME, * AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. Any of these elements may be omitted, but no other * elements should be included. If supplied, the AST__STCNAME element * should be a vector of character string pointers holding the "Name" * item for each axis. Any other supplied elements should be scalar * elements, each holding a pointer to a Region describing the * associated item of ancillary information (error, resolution, size, * pixel size or value). These Regions should refer to the coordinate * system represented by "region". * class * Pointer to a string holding the STC class name. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to the new KeyMap. * 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 *frm; /* Pointer to current Frame */ AstFrameSet *fs; /* Pointer to conversion FrameSet */ AstKeyMap *result; /* Pointer value to return */ AstMapping *map; /* Pointer to conversion Mapping */ AstObject *obj; /* Pointer to Object stored in supplied KeyMap */ AstRegion *areg; /* Pointer to remapped Region */ AstRegion *sareg; /* Pointer to simplified remapped Region */ const char *key; /* Current key */ int j; /* Index of key within KeyMap */ int naxes; /* Number of axes in region */ int nkey; /* Number of keys in supplied KeyMap */ int nv; /* Number of values in KeyMap element */ int type; /* Data type of entry */ /* Initialise. */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Confirm it is a genuine KeyMap pointer. */ if( !astIsAKeyMap( coord ) && astOK ) { astError( AST__STCKEY, "astInitStc(%s): Supplied pointer is for " "a %s, not a KeyMap.", status, class, astGetClass( coord ) ); } /* Initialise the new KeyMap to be a copy of the supplied KeyMap. */ result = astCopy( coord ); /* Check the supplied KeyMap is usable. */ naxes = astGetNaxes( reg ); nkey = astMapSize( result ); for( j = 0; j < nkey; j++ ) { key = astMapKey( result, j ); if( key ) { nv = astMapLength( result, key ); type = astMapType( result, key ); /* Check no unknown keys are present in the KeyMap. */ if( strcmp( key, AST__STCNAME ) && strcmp( key, AST__STCVALUE ) && strcmp( key, AST__STCERROR ) && strcmp( key, AST__STCRES ) && strcmp( key, AST__STCSIZE ) && strcmp( key, AST__STCPIXSZ ) ) { astError( AST__STCKEY, "astInitStc(%s): Unknown key " "\"%s\" supplied in an AstroCoords list.", status, class, key ); break; /* Check that the "Name" element is a vector of "naxes" strings. */ } else if( !strcmp( key, AST__STCNAME ) ) { if( nv != naxes ) { astError( AST__STCKEY, "astInitStc(%s): %d \"%s\" " "values supplied in an AstroCoords list, but " "the Stc has %d axes. ", status, class, nv, key, naxes ); break; } else if( type != AST__STRINGTYPE ) { astError( AST__STCKEY, "astInitStc(%s): The \"%s\" " "values supplied in an AstroCoords list are " "not character strings. ", status, class, key ); break; } /* Check that all other elements are scalar. */ } else if( nv != 1 ) { astError( AST__STCKEY, "astInitStc(%s): %d \"%s\" " "values supplied in an AstroCoords list, but " "only one is allowed. ", status, class, nv, key ); break; /* Check that all other elements are AST Object pointers. */ } else if( type != AST__OBJECTTYPE ) { astError( AST__STCKEY, "astInitStc(%s): The \"%s\" " "value supplied in an AstroCoords list is " "not an AST Object pointer. ", status, class, key ); break; /* Check that the Object pointers are not NULL. */ } else { astMapGet0A( result, key, &obj ); if( astOK ) { if( !obj ) { astError( AST__STCKEY, "astInitStc(%s): The \"%s\" " "value supplied in an AstroCoords list is " "a NULL pointer. ", status, class, key ); break; /* Check that the Object pointers are Region pointers. */ } else if( !astIsARegion( obj ) ){ astError( AST__STCKEY, "astInitStc(%s): The \"%s\" " "value supplied in an AstroCoords list is " "a %s, not a Region. ", status, class, key, astGetClass(obj) ); obj = astAnnul( obj ); break; /* Check that the Region pointers can be converted to the coordinate system represented by the supplied Region. */ } else { fs = astConvert( obj, reg, "" ); if( !fs ) { obj = astAnnul( obj ); astError( AST__STCKEY, "astInitStc(%s): The \"%s\" " "value supplied in an AstroCoords list " "cannot be converted to the coordinate " "system of its parent Stc object.", status, class, key ); break; /* If necessary, map the Region into the same frame as the supplied Region, and replace the Region in the returned KeyMap with the remapped Region. Also set the RegionFS attribute to indicate that the FrameSet in the Region does not need to be dumped if it contains a UnitMap. */ } else { map = astGetMapping( fs, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) ) { frm = astGetFrame( fs, AST__CURRENT ); areg = astMapRegion( (AstRegion *) obj, map, frm ); sareg = astSimplify( areg ); astSetRegionFS( sareg, 0 ); astMapPut0A( result, key, sareg, NULL ); areg = astAnnul( areg ); sareg = astAnnul( sareg ); frm = astAnnul( frm ); } else { astSetRegionFS( (AstRegion *) obj, 0 ); } map = astAnnul( map ); fs = astAnnul( fs ); } obj = astAnnul( obj ); } } } } } /* Free the returned KeyMap if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* 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: * Stc 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: */ AstStc *this; /* Pointer to STC 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 STC structure. */ this = (AstStc *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->region, mode, extra, fail ); for( i = 0; i < this->ncoord; i++ ) { if( !result ) result = astManageLock( this->coord[ i ], mode, extra, fail ); } return result; } #endif static int Overlap( AstRegion *this, AstRegion *that, int *status ){ /* * Name: * Overlap * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "stc.h" * int Overlap( AstRegion *this, AstRegion *that, int *status ) * Class Membership: * Stc member function (over-rides the astOverlap method inherited * from the Region class). * Description: * This function returns an integer value indicating if the two * supplied Regions overlap. The two Regions are converted to a commnon * coordinate system before performing the check. If this conversion is * not possible (for instance because the two Regions represent areas in * different domains), then the check cannot be performed and a zero value * is returned to indicate this. * Parameters: * this * Pointer to the first Region. * that * Pointer to the second Region. * status * Pointer to the inherited status variable. * Returned Value: * astOverlap() * A value indicating if there is any overlap between the two Regions. * Possible values are: * * 0 - The check could not be performed because the second Region * could not be mapped into the coordinate system of the first * Region. * * 1 - There is no overlap between the two Regions. * * 2 - The first Region is completely inside the second Region. * * 3 - The second Region is completely inside the first Region. * * 4 - There is partial overlap between the two Regions. * * 5 - The Regions are identical. * * 6 - The second Region is the negation of the first Region. * Notes: * - The returned values 5 and 6 do not check the value of the Closed * attribute in the two Regions. * - A value of zero will be returned if this function is invoked with the * AST error status set, or if it should fail for any reason. */ /* Check the inherited status. */ if ( !astOK ) return 0; /* Invoke the "astOverlap" method on the encapsulated Region. */ return astOverlap( ((AstStc *)this)->region, that ); } static int OverlapX( AstRegion *that, AstRegion *this, int *status ){ /* * Name: * OverlapX * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "stc.h" * int OverlapX( AstRegion *that, AstRegion *this ) * Class Membership: * Stc member function (over-rides the astOverlapX method inherited * from the Region class). * Description: * This function performs the processing for the public astOverlap * method and has exactly the same interface except that the order * of the two arguments is swapped. This is a trick to allow * the astOverlap method to be over-ridden by derived classes on * the basis of the class of either of its two arguments. * * See the astOverlap method for details of the interface. */ /* Local Variables: */ int result; /* Check the inherited status. */ if ( !astOK ) return 0; /* Invoke the "astOverlapX" method on the encapsulated Region. */ result = astOverlap( ((AstStc *)that)->region, this ); /* Swap the returned values 2 and 3 to take account of the swapping of the regions.*/ if( result == 2 ) { result = 3; } else if( result == 3 ) { result = 2; } /* Return the result. */ return result; } static void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "stc.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Stc member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Invoke the method on the encapsulated Region. */ astRegBaseBox( ((AstStc *)this)->region, lbnd, ubnd ); } static AstPointSet *RegBaseMesh( AstRegion *this, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Create a new PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "stc.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Stc member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function creates a new PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. Annul the pointer using astAnnul when it * is no longer needed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Check the global error status. */ if( !astOK ) return NULL; /* Invoke the astRegMesh method on the encapsulated Region. This returns a mesh in the current Frame of the encapsulated Region which is the same as the base Frame of the Stc Region. */ return astRegMesh( ((AstStc *)this)->region ); } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "stc.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * Stc member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Invoke the astRegBaePick method on the encapsulated Region. */ return astRegBasePick( ((AstStc *)this_region)->region, naxes, axes ); } static void RegClearAttrib( AstRegion *this_region, const char *attrib, char **base_attrib, int *status ) { /* * Name: * RegClearAttrib * Purpose: * Clear an attribute value for a Region. * Type: * Protected function. * Synopsis: * #include "stc.h" * void RegClearAttrib( AstRegion *this, const char *attrib, * char **base_attrib, int *status ) * Class Membership: * Stc method (over-rides the astRegClearAttrib method inherited from * the Region class). * Description: * This function clears the value of an attribute in both the base and * current Frame in the FrameSet encapsulated within a Region, without * remapping either Frame. * * No error is reported if the attribute is not recognised by the base * Frame. * Parameters: * this * Pointer to the Region. * attrib * Pointer to a null terminated string containing an attribute name. * NOTE, IT SHOULD BE ENTIRELY LOWER CASE. * base_attrib * Address of a location at which to return a pointer to the null * terminated string holding the name of the attribute which was * cleared in the base Frame of the encapsulated FrameSet. This may * differ from the supplied name if the supplied name contains an axis * index and the current->base Mapping in the FrameSet produces an * axis permutation. The returned pointer should be freed using * astFree when no longer needed. A NULL pointer may be supplied in * which case no pointer is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstStc *this; char *batt; int rep; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Stc structure. */ this = (AstStc *) this_region; /* Use the RegClearAttrib method inherited from the parent class to clear the attribute in the current and base Frames in the FrameSet encapsulated by the parent Region structure. */ (*parent_regclearattrib)( this_region, attrib, &batt, status ); /* Now clear the base Frame attribute in the encapsulated Region (the current Frame within the encapsulated Region is equivalent to the base Frame in the parent Region structure). Annul any "attribute unknown" error that results from attempting to do this. */ if( astOK ) { rep = astReporting( 0 ); astRegClearAttrib( this->region, batt, NULL ); if( astStatus == AST__BADAT ) astClearStatus; astReporting( rep ); } /* If required, return the base Frame attribute name, otherwise free it. */ if( base_attrib ) { *base_attrib = batt; } else { batt = astFree( batt ); } } static int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Stc member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Stc. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Stc "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Stc. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Check the global error status. */ if( !astOK ) return 0; /* Invoke the method on the encapsulated Region. */ return astRegPins( ((AstStc *)this)->region, pset, unc, mask ); } static void RegSetAttrib( AstRegion *this_region, const char *setting, char **base_setting, int *status ) { /* * Name: * RegSetAttrib * Purpose: * Set an attribute value for a Region. * Type: * Private function. * Synopsis: * #include "stc.h" * void RegSetAttrib( AstRegion *this, const char *setting, * char **base_setting, int *status ) * Class Membership: * Stc method (over-rides the astRegSetAttrib method inherited from * the Region class). * Description: * This function assigns an attribute value to both the base and * current Frame in the FrameSet encapsulated within a Region, without * remapping either Frame. * * No error is reported if the attribute is not recognised by the base * Frame. * Parameters: * this * Pointer to the Region. * setting * Pointer to a null terminated attribute setting string. NOTE, IT * SHOULD BE ENTIRELY LOWER CASE. The supplied string will be * interpreted using the public interpretation implemented by * astSetAttrib. This can be different to the interpretation of the * protected accessor functions. For instance, the public * interpretation of an unqualified floating point value for the * Epoch attribute is to interpet the value as a gregorian year, * but the protected interpretation is to interpret the value as an * MJD. * base_setting * Address of a location at which to return a pointer to the null * terminated attribute setting string which was applied to the * base Frame of the encapsulated FrameSet. This may differ from * the supplied setting if the supplied setting contains an axis * index and the current->base Mapping in the FrameSet produces an * axis permutation. The returned pointer should be freed using * astFree when no longer needed. A NULL pointer may be supplied in * which case no pointer is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstKeyMap *keymap; AstObject *obj; AstRegion *reg; AstStc *this; char *bset; int i; int ikey; int rep; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Stc structure. */ this = (AstStc *) this_region; /* Use the RegSetAttrib method inherited from the parent class to apply the setting to the current and base Frames in the FrameSet encapsulated by the parent Region structure. */ (*parent_regsetattrib)( this_region, setting, &bset, status ); /* Now apply the base Frame setting to the encapsulated Region (the current Frame within the encapsulated Region is equivalent to the base Frame in the parent Region structure). Annul any "attribute unknown" error that results from attempting to do this. Also do any AstroCoords in the Stc. */ if( astOK ) { rep = astReporting( 0 ); astRegSetAttrib( this->region, bset, NULL ); if( astStatus == AST__BADAT ) astClearStatus; /* Loop round all AstroCoords elements. */ for( i = 0; i < this->ncoord; i++ ) { /* Get a pointer to the KeyMap holding a description of the current AstroCoords element. */ keymap = this->coord[ i ]; /* Loop round all the elements of this KeyMap which may hold a Region pointer. */ for( ikey = 0; ikey < NREG; ikey++ ) { /* If the KeyMap contains a Region for this key, get a pointer to it. */ if( astMapGet0A( keymap, regkey[ ikey ], &obj ) ){ reg = (AstRegion *) obj; /* Modify it by applying the attribute setting. */ astRegSetAttrib( reg, bset, NULL ); if( astStatus == AST__BADAT ) astClearStatus; /* Annul the pointer. */ reg = astAnnul( reg ); } } } astReporting( rep ); } /* If required, return the base Frame setting string, otherwise free it. */ if( base_setting ) { *base_setting = bset; } else { bset = astFree( bset ); } } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Stc member function (over-rides the astSetAttrib method inherited * from the Region class). * Description: * This function assigns an attribute value for a Stc, 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 Stc. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Vaiables: */ AstStc *this; /* Pointer to the Stc structure */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) 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. */ /* (none as yet) */ /* Read-only attributes. */ /* --------------------- */ /* Define a macro to see if the setting string matches any of the read-only attributes of this class. */ #define MATCH(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ ( nc >= len ) ) /* Use this macro to report an error if a read-only attribute has been specified. */ if ( MATCH( "regionclass" ) ) { 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); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "stc.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Stc method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstRegion *creg; /* Pointer to encapsulated Region structure */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* If the encapsulated Region has a dummy FrameSet use this method recursively to give it the same FrameSet. */ creg = ((AstStc *) this_region )->region; if( creg && !astGetRegionFS( creg ) ) astSetRegFS( creg, frm ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify a Region. * Type: * Private function. * Synopsis: * #include "region.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Stc method (over-rides the astSimplify method inherited from * the Region class). * Description: * This function simplifies a Stc 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 Region. * status * Pointer to the inherited status variable. * Returned Value: * A new pointer to the (possibly simplified) Region. * 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 *frm; /* Current Frame */ AstKeyMap *keymap; /* KeyMap holding stroCoords element */ AstMapping *map; /* Base->current Mapping */ AstObject *obj; /* Pointer to object retrieved from keymap */ AstRegion *newreg; /* New encapsulated Region */ AstRegion *reg; /* AstroCoords Region pointer */ AstRegion *treg; /* Temporary Region pointer */ AstStc *stc; /* Returned Stc Structure. */ AstStc *temp; /* Temporary Stc pointer */ int i; /* Index of current AstroCoords element */ int ikey; /* Index of key to be tested */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Invoke the Simplify method of the parent Region class. This simplifies the FrameSet and uncertainty Region in the parent Region structure. */ stc = (AstStc *) (AstRegion *) (* parent_simplify)( this_mapping, status ); /* If the Stc is negated, we can perform a simplication by transferring the negated state from the Stc itself to the encapsulated Region. */ if( astGetNegated( stc ) ) { /* Ensure that modifying "stc" will not modify the supplied Stc, by creating a copy of the supplied Stc, if this has not already been done. */ if( stc == (AstStc *) this_mapping ) { temp = (AstStc *) astCopy( stc ); (void) astAnnul( stc ); stc = temp; } /* Modify "temp" by negating both the Stc structure and its encapsulated Region. */ astNegate( stc ); astNegate( stc->region ); } /* Get the base->current Mapping from the parent Region structure, and the current Frame. */ map = astGetMapping( ((AstRegion *) stc)->frameset, AST__BASE, AST__CURRENT ); frm = astGetFrame( ((AstRegion *) stc)->frameset, AST__CURRENT ); /* We may be able to perform some more simplication on the encapsulated Region itself. If the above mapping is not a unit map, remap the encapsulated Region into the current Frame of the parent Region structure and simplify it. This transfers complication from the Mapping in the parent Region structure to the encapsulated Region. */ if( !astIsAUnitMap( map ) ) { treg = astMapRegion( stc->region, map, frm ); newreg = astSimplify( treg ); treg = astAnnul( treg ); /* If the base->current Mapping in the parent Region structure is a unit map, simplification of the whole Stc is possible if the encapsulated Region (without any remapping) can be simplied. */ } else { newreg = astSimplify( stc->region ); } /* If the encapsulated Region has been changed, store it in the returned Stc. */ if( newreg != stc->region ) { /* Ensure that modifying "stc" will not modify the supplied Stc, by creating a copy of the supplied Stc, if this has not already been done. */ if( stc == (AstStc *) this_mapping ) { temp = (AstStc *) astCopy( stc ); (void) astAnnul( stc ); stc = temp; } /* Store the new region in "stc", annulling the existing Region. */ if( stc ) { (void) astAnnul( stc->region ); stc->region = astClone( newreg ); } /* The encapsulated Region now represents an area in the current Frame represented by the supplied Stc. Since the encapsulated Region is defined as being in the base Frame of the FrameSet in the parent Region structure, the parent FrameSet should just be a UnitMap. Modify it appropriately (if it not already a UnitMap). */ if( !astIsAUnitMap( map ) ) astSetRegFS( stc, frm ); } /* Free resources */ newreg = astAnnul( newreg ); /* Now we do a similar process on any Regions held within an AstroCoords elements. Loop round all AstroCoords elements. */ if( stc ) { for( i = 0; i < stc->ncoord; i++ ) { /* Get a pointewr to the KeyMap holding a description of the current AstroCoords element. */ keymap = stc->coord[ i ]; /* Loop round all the elements of this KeyMap which may hold a Region pointer. */ for( ikey = 0; ikey < NREG; ikey++ ) { /* If the KeyMap contains a Region for this key, get a pointer to it. */ if( astMapGet0A( keymap, regkey[ ikey ], &obj ) ){ reg = (AstRegion *) obj; /* We have two tasks now, firstly to ensure that this AstroCoords Region describes an area in the base Frame of the FrameSet in the parent Region structure (which may have been changed by the earlier simplications performed by this function), and secondly, to attempt to simplify the Region. The Stc structure addressed by the "stc" pointer will have a current Frame given by "frm". This will also be its base Frame, and the base->current Mapping will consequently be a UnitMap. The Mapping from the original base Frame to the new base Frame is given by "map". Unless this is a UnitMap, we need to remap the Region.*/ if( !astIsAUnitMap( map ) ) { treg = astMapRegion( reg, map, frm ); } else { treg = astClone( reg ); } /* Now attempt to simplify the Region.*/ newreg = astSimplify( treg ); /* If the Region has been changed by either of these steps, we need to store the modified Region back in the "stc" structure which is being returned. But we need to be careful we do not modify the supplied Stc structure. */ if( newreg != reg ) { if( stc == (AstStc *) this_mapping ) { temp = astCopy( stc ); (void) astAnnul( stc ); stc = temp; keymap = temp->coord[ i ]; } astMapPut0A( keymap, regkey[ ikey ], newreg, regcom[ ikey ] ); } /* Free resources */ reg = astAnnul( reg ); treg = astAnnul( treg ); newreg = astAnnul( newreg ); } } } } /* Free resources */ map = astAnnul( map ); frm = astAnnul( frm ); /* If an error occurred, annul the returned Mapping. */ if ( !astOK ) stc = astAnnul( stc ); /* Return the result. */ return (AstMapping *) stc; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Stc. * Type: * Private function. * Synopsis: * #include "stc.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Stc member function (over-rides the astTestAttrib protected * method inherited from the Region class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Stc's attributes. * Parameters: * this * Pointer to the Stc. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Returned Value: * One if a value has been set, otherwise zero. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstStc *this; /* Pointer to the Stc structure */ int len; /* Length of attrib string */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then return zero. */ if ( !strcmp( attrib, "regionclass" ) ) { result = 0; /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Stc to transform a set of points. * Type: * Private function. * Synopsis: * #include "stc.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Stc member function (over-rides the astTransform method inherited * from the Region class). * Description: * This function takes a Stc and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Region. * This implies applying each of the Stc's encapsulated Region in turn, * either in series or in parallel. * Parameters: * this * Pointer to the Stc. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Stc being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *ps; /* Pointer to PointSet */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ AstRegion *reg; /* Pointer to encapsulated Region */ AstStc *this; /* Pointer to the Stc structure */ double **ptr; /* Pointer to axis values */ double **ptr_out; /* Pointer to output coordinate data */ int coord; /* Zero-based index for coordinates */ int good; /* Is the point inside the Stc? */ int ncoord_out; /* No. of coordinates per output point */ int ncoord_tmp; /* No. of coordinates per base Frame point */ int neg; /* Negated value for encapsulated Region */ int neg_old; /* Original Negated flag */ int npoint; /* No. of points */ int point; /* Loop counter for points */ int rep; /* Original error reporting status */ int status_value; /* AST status value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a Pointer to the Stc structure */ this = (AstStc *) this_mapping; /* Get the encapsulated Region, and the Negated value which should be used with it. The returned values take account of whether the supplied Stc has itself been Negated or not. The returned Region represent a region within the base Frame of the FrameSet encapsulated by the parent Region structure. */ GetRegion( this, ®, &neg, status ); /* Temporarily set the Negated attribute to the required value.*/ neg_old = astGetNegated( reg ); astSetNegated( reg, neg ); /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet in the parent Region structure to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Stc), to the base Frame (the Frame in which the encapsulated Region are defined). Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( this, in, 0, NULL, NULL ); /* Now transform this PointSet using the encapsulated Region. */ ps = astTransform( reg, pset_tmp, 0, NULL ); /* Determine the numbers of points and coordinates per point for these base Frame PointSets and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( pset_tmp ); ncoord_tmp = astGetNcoord( pset_tmp ); ptr = astGetPoints( ps ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { for ( point = 0; point < npoint; point++ ) { good = 0; for ( coord = 0; coord < ncoord_tmp; coord++ ) { if( ptr[ coord ][ point ] != AST__BAD ) { good = 1; break; } } if( !good ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Re-instate the original value for the Negated attribute of the encapsulated Region. Do this even if an error has occurred. */ status_value = astStatus; astClearStatus; rep = astReporting( 0 ); if( reg ) astSetNegated( reg, neg_old ); astReporting( rep ); astSetStatus( status_value ); /* Free resources. */ reg = astAnnul( reg ); ps = astAnnul( ps ); pset_tmp = astAnnul( pset_tmp ); /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Stc Attributes: */ /* =============== */ /* *att++ * Name: * RegionClass * Purpose: * The AST class name of the Region encapsulated within an Stc * Type: * Public attribute. * Synopsis: * String, read-only. * Description: * This is a read-only attribute giving the AST class name of the * Region encapsulated within an Stc (that is, the class of the Region * which was supplied when the Stc was created). * Applicability: * Stc * All Stc objects this attribute. *att-- */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Stc objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Stc objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Regions within the Stc. */ /* Local Variables: */ AstStc *in; /* Pointer to input Stc */ AstStc *out; /* Pointer to output Stc */ int i; /* AstroCoords index */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Stcs. */ in = (AstStc *) objin; out = (AstStc *) objout; /* For safety, start by clearing any references to the input component Regions, etc, from the output Stc. */ out->region = NULL; out->coord = NULL; out->ncoord = 0; /* Make a copy of the Region and store a pointer to it in the output Stc structure. */ out->region = astCopy( in->region ); /* Copy any memory holding AstroCoords values */ if( in->coord && in->ncoord ) { out->ncoord = in->ncoord; out->coord = astMalloc( sizeof(AstKeyMap *) * (size_t)in->ncoord ); if( out->coord ) { for( i = 0; i < in->ncoord; i++ ) { out->coord[ i ] = astCopy( in->coord[ i ] ); } } } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Stc objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Stc objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstStc *this; /* Pointer to Stc */ int i; /* AstroCoords index */ /* Obtain a pointer to the Stc structure. */ this = (AstStc *) obj; /* Annul the pointer to the encapsulated Region. */ this->region = astAnnul( this->region ); /* Free any memory holding AstroCoords values */ if( this->coord ) { for( i = 0; i < this->ncoord; i++ ) { this->coord[ i ] = astAnnul( this->coord[ i ] ); } this->coord = astFree( this->coord ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Stc 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 Stc class to an output Channel. * Parameters: * this * Pointer to the Stc 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: */ AstStc *this; /* Pointer to the Stc structure */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment string */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int ico; /* Loop counter for KeyMaps */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Stc structure. */ this = (AstStc *) this_object; /* Write out values representing the instance variables for the Stc 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. */ /* Encapsulated Region. */ /* -------------------- */ astWriteObject( channel, "Region", 1, 1, this->region, "STC Region" ); /* AstroCoords info */ /* ---------------- */ astWriteInt( channel, "Ncoord", ( this->ncoord != 0 ), 0, this->ncoord, "Number of AstroCoords elements" ); for ( ico = 1; ico <= this->ncoord; ico++ ) { (void) sprintf( key, "Coord%d", ico ); (void) sprintf( comment, "AstroCoords number %d", ico ); astWriteObject( channel, key, 1, 1, this->coord[ ico - 1 ], comment ); } /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAStc and astCheckStc functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Stc,Region) astMAKE_CHECK(Stc) AstStc *astInitStc_( void *mem, size_t size, int init, AstStcVtab *vtab, const char *name, AstRegion *region, int ncoords, AstKeyMap **coords, int *status ) { /* *+ * Name: * astInitStc * Purpose: * Initialise a Stc. * Type: * Protected function. * Synopsis: * #include "stc.h" * AstStc *astInitStc( void *mem, size_t size, int init, AstStcVtab *vtab, * const char *name, AstRegion *region, int ncoords, * AstKeyMap **coords ) * Class Membership: * Stc initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Stc object. It allocates memory (if necessary) to * accommodate the Stc plus any additional data associated with the * derived class. It then initialises a Stc 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 Stc at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Stc is to be initialised. * This must be of sufficient size to accommodate the Stc data * (sizeof(Stc)) 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 Stc (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 * Stc structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the Stc'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 Stc. * 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 Object * astClass function). * region * Pointer to the Region represented by the Stc. * ncoords * Number of KeyMap pointers supplied in "coords". Can be zero. * Ignored if "coords" is NULL. * coords * Pointer to an array of "ncoords" KeyMap pointers, or NULL if * "ncoords" is zero. Each KeyMap defines defines a single * element, and should have elements with keys given by constants * AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. Any of these elements may be omitted, but no other * elements should be included. If supplied, the AST__STCNAME element * should be a vector of character string pointers holding the "Name" * item for each axis. Any other supplied elements should be scalar * elements, each holding a pointer to a Region describing the * associated item of ancillary information (error, resolution, size, * pixel size or value). These Regions should describe a volume within * the coordinate system represented by "region". * Returned Value: * A pointer to the new Stc. * Notes: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. *- */ /* Local Variables: */ AstMapping *frm; /* Current Frame in supplied Stc */ AstMapping *map; /* Base -> Current Mapping in supplied Stc */ AstRegion *reg; /* Copy of supplied Region */ AstStc *new; /* Pointer to new Stc */ int i; /* AstroCoords index */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitStcVtab( vtab, name ); /* Initialise. */ new = NULL; /* If the supplied Region is an Stc, create a new Region by mapping the encapsulated Region within the supplied Stc into the current Frame of the Stc. */ if( astIsAStc( region ) ) { map = astGetMapping( region->frameset, AST__BASE, AST__CURRENT ); frm = astGetFrame( region->frameset, AST__CURRENT ); reg = astMapRegion( ((AstStc *) region)->region, map, frm ); frm = astAnnul( frm ); map = astAnnul( map ); /* Otherwise, just take a copy of the supplied Region. */ } else { reg = astCopy( region ); } /* Initialise a Region structure (the parent class) as the first component within the Stc structure, allocating memory if necessary. A NULL PointSet is suppled as the encapsulated Region will perform the function of defining the Region shape. The base Frame of the FrameSet in the parent Region structure will be the same as the current Frames of the FrameSets in the two encapsulated Region. */ if ( astOK ) { new = (AstStc *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, reg, NULL, NULL ); /* Initialise the Stc data. */ /* --------------------------- */ /* Store a pointer to the encapsulated Region. */ new->region = astClone( reg ); /* No AstroCoords info as yet. */ new->ncoord = 0; new->coord = NULL; /* Transfer attributes from the encapsulated region to the parent region. */ astRegOverlay( new, reg, 1 ); if( astTestIdent( reg ) ) astSetIdent( new, astGetIdent( reg ) ); /* If the base->current Mapping in the FrameSet within the encapsulated Region is a UnitMap, then the FrameSet does not need to be included in the Dump of the new Stc. Set the RegionFS attribute of the encapsulated Region to zero to flag this. Note, we do this after the previous class to astRegOverlay because we do not want this zero value for RegionFS to be copied into the new Stc object. */ astSetRegionFS( reg, 0 ); /* For each supplied AstroCoords, create a new KeyMap holding Regions representing the various elements of the AstroCoords, and store the new KeyMap in the Stc structure. */ if( coords && ncoords > 0 ) { new->ncoord = ncoords; new->coord = astMalloc( sizeof( AstKeyMap *)*(size_t) ncoords ); if( new->coord ) { for( i = 0; i < ncoords; i++ ) { new->coord[ i ] = MakeAstroCoordsKeyMap( reg, coords[ i ], name, status ); } } } /* If an error occurred, clean up deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Free resources */ reg = astAnnul( reg ); /* Return a pointer to the new object. */ return new; } AstStc *astLoadStc_( void *mem, size_t size, AstStcVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadStc * Purpose: * Load a Stc. * Type: * Protected function. * Synopsis: * #include "stc.h" * AstStc *astLoadStc( void *mem, size_t size, AstStcVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Stc loader. * Description: * This function is provided to load a new Stc 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 * Stc structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Stc at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Stc is to be * loaded. This must be of sufficient size to accommodate the * Stc data (sizeof(Stc)) 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 Stc (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 Stc 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(AstStc) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Stc. If this is NULL, a pointer to * the (static) virtual function table for the Stc 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 "Stc" is used instead. * Returned Value: * A pointer to the new Stc. * Notes: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Constants: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstFrame *f1; /* Base Frame in parent Region */ AstObject *obj; /* Pointer to Object retrieved from KeyMap */ AstRegion *creg; /* Pointer to encapsulated Region */ AstStc *new; /* Pointer to the new Stc */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int ico; /* Loop counter for AstroCoords */ int ikey; /* Index of KeyMap */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Stc. In this case the Stc belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstStc ); vtab = &class_vtab; name = "Stc"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitStcVtab( 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 Stc. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Stc" ); /* 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. */ /* Encapsulated Region. */ /* -------------------- */ new->region = astReadObject( channel, "region", NULL ); /* Get a pointer to the base Frame in the FrameSet encapsulated by the parent Region structure. */ f1 = astGetFrame( ((AstRegion *) new)->frameset, AST__BASE ); /* If the encapsulated Region has a dummy FrameSet rather than the correct FrameSet, the correct FrameSet will have copies of the base Frame of the new Stc as both its current and base Frames, connected by a UnitMap (this is equivalent to a FrameSet containing a single Frame). However if the new Stc being loaded has itself got a dummy FrameSet, then we do not do this since we do not yet know what the correct FrameSet is. In this case we wait until the parent Region invokes the astSetRegFS method on the new Stc. */ if( !astRegDummyFS( new ) ) { creg = new->region; if( astRegDummyFS( creg ) ) astSetRegFS( creg, f1 ); } /* AstroCoords info */ /* ---------------- */ /* The number of AstroCoords described in the new Stc. */ new->ncoord = astReadInt( channel, "ncoord", 0 ); if( new->ncoord < 0 ) new->ncoord = 0; /* Read back each KeyMap describing these AstroCoords. */ new->coord = astMalloc( sizeof( AstKeyMap *) * (size_t) new->ncoord ); for( ico = 1; ico <= new->ncoord; ico++ ) { (void) sprintf( key, "coord%d", ico ); new->coord[ ico - 1 ] = astReadObject( channel, key, NULL ); /* Ensure the Regions within the KeyMap do not have dummy FrameSets. */ if( new->coord[ ico - 1 ] && !astRegDummyFS( new ) ) { for( ikey = 0; ikey < NREG; ikey++ ) { if( astMapGet0A( new->coord[ ico - 1 ], regkey[ ikey ], &obj ) ){ creg = (AstRegion *) obj; if( astRegDummyFS( creg ) ) { astSetRegFS( creg, f1 ); astMapPut0A( new->coord[ ico - 1 ], regkey[ ikey ], creg, regcom[ ikey ] ); } creg = astAnnul( creg ); } } } } /* Free resources */ f1 = astAnnul( f1 ); /* If an error occurred, clean up by deleting the new Stc. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Stc pointer. */ return new; /* Undefine macros local to this function. */ #undef KEY_LEN } /* Virtual function interfaces. */ /* ============================ */ /* These provide the external interface to the virtual functions defined by this class. Each simply checks the global error status and then locates and executes the appropriate member function, using the function pointer stored in the object's virtual function table (this pointer is located using the astMEMBER macro defined in "object.h"). Note that the member function may not be the one defined here, as it may have been over-ridden by a derived class. However, it should still have the same interface. */ const char *astGetRegionClass_( AstStc *this, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Stc,GetRegionClass))( this, status ); } AstRegion *astGetStcRegion_( AstStc *this, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Stc,GetStcRegion))( this, status ); } AstKeyMap *astGetStcCoord_( AstStc *this, int icoord, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Stc,GetStcCoord))( this, icoord, status ); } int astGetStcNCoord_( AstStc *this, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Stc,GetStcNCoord))( this, status ); } ast-8.3.0/polygon.c0000664000175000017500000073762313004147321011104 00000000000000/* *class++ * Name: * Polygon * Purpose: * A polygonal region within a 2-dimensional Frame. * Constructor Function: c astPolygon f AST_POLYGON * Description: * The Polygon class implements a polygonal area, defined by a * collection of vertices, within a 2-dimensional Frame. The vertices * are connected together by geodesic curves within the encapsulated Frame. * For instance, if the encapsulated Frame is a simple Frame then the * geodesics will be straight lines, but if the Frame is a SkyFrame then * the geodesics will be great circles. Note, the vertices must be * supplied in an order such that the inside of the polygon is to the * left of the boundary as the vertices are traversed. Supplying them * in the reverse order will effectively negate the polygon. * * Within a SkyFrame, neighbouring vertices are always joined using the * shortest path. Thus if an edge of 180 degrees or more in length is * required, it should be split into section each of which is less * than 180 degrees. The closed path joining all the vertices in order * will divide the celestial sphere into two disjoint regions. The * inside of the polygon is the region which is circled in an * anti-clockwise manner (when viewed from the inside of the celestial * sphere) when moving through the list of vertices in the order in * which they were supplied when the Polygon was created (i.e. the * inside is to the left of the boundary when moving through the * vertices in the order supplied). * Inheritance: * The Polygon class inherits from the Region class. * Attributes: * In addition to those attributes common to all Regions, every * Polygon also has the following attributes: * - SimpVertices: Simplify by transforming the vertices? * Functions: c In addition to those functions applicable to all Regions, the c following functions may also be applied to all Polygons: f In addition to those routines applicable to all Regions, the f following routines may also be applied to all Polygons: * c - astDownsize: Reduce the number of vertices in a Polygon. f - AST_DOWNSIZE: Reduce the number of vertices in a Polygon. c - astConvex: Create a Polygon giving the convex hull of a pixel array f - AST_CONVEX: Create a Polygon giving the convex hull of a pixel array c - astOutline: Create a Polygon outlining values in a pixel array f - AST_OUTLINE: Create a Polygon outlining values in a pixel array * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-OCT-2004 (DSB): * Original version. * 28-MAY-2009 (DSB): * Added astDownsize. * 29-MAY-2009 (DSB): * Added astOutline. * 30-JUN-2009 (DSB): * Override astGetBounded. * 4-NOV-2013 (DSB): * Modify RegPins so that it can handle uncertainty regions that straddle * a discontinuity. Previously, such uncertainty Regions could have a huge * bounding box resulting in matching region being far too big. * 6-DEC-2013 (DSB): * Reverse the order of the vertices when the Polygon is created, * if necessary, to ensure that the unnegated Polygon is bounded. * The parent Region class assumes that unnegated regions are * bounded. * 6-JAN-2014 (DSB): * Free edges when clearing the cache, not when establishing a new * cache, as the number of edges may have changed. * 10-JAN-2014 (DSB): * - Remove unused parameter description in prologue of for astOutline * 24-FEB-2014 (DSB): * Added astConvex. * 25-FEB-2014 (DSB): * Added attribute SimpVertices. * 7-SEP-2015 (DSB): * Shrink outline polygons by a small fraction of a pixel, in order * to avoid placing vertices exactly on pixel edges. This is because * rounding errors in subsequent code may push the vertices into * neighbouring pixels, which may have bad WCS coords (e.g. * vertices on the boundary of a polar cusp in an HPX map). *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 Polygon /* Define a macro for testing if a pixel value satisfies the requirements specified by and . Compiler optimisation should remove all the "if" testing from this expression. */ #define ISVALID(V,OperI,Value) ( \ ( OperI == AST__LT ) ? ( (V) < Value ) : ( \ ( OperI == AST__LE ) ? ( (V) <= Value ) : ( \ ( OperI == AST__EQ ) ? ( (V) == Value ) : ( \ ( OperI == AST__GE ) ? ( (V) >= Value ) : ( \ ( OperI == AST__NE ) ? ( (V) != Value ) : ( \ (V) > Value \ ) \ ) \ ) \ ) \ ) \ ) /* Macros specifying whether a point is inside, outside or on the boundary of the polygon. */ #define UNKNOWN 0 #define IN 1 #define OUT 2 #define ON 3 /* Size of pertubation (in pixels) used to avoid placing vertices exactly on a pixel edge. */ #define DELTA 0.01 /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "box.h" /* Box Regions */ #include "wcsmap.h" /* Definitons of AST__DPI etc */ #include "polygon.h" /* Interface definition for this class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mapping */ #include "pal.h" /* SLALIB library interface */ #include "frame.h" /* Coordinate system description */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* Type definitions. */ /* ================= */ /* A structure that holds information about an edge of the new Polygon being created by astDownsize. The edge is a line betweeen two of the vertices of the original Polygon. */ typedef struct Segment { int i1; /* Index of starting vertex within old Polygon */ int i2; /* Index of ending vertex within old Polygon */ double error; /* Max geodesic distance from any old vertex to the line */ int imax; /* Index of the old vertex at which max error is reached */ struct Segment *next;/* Pointer to next Segment in a double link list */ struct Segment *prev;/* Pointer to previous Segment in a double link list */ } Segment; /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (* parent_resetcache)( AstRegion *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Polygon) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Polygon,Class_Init) #define class_vtab astGLOBAL(Polygon,Class_Vtab) #define getattrib_buff astGLOBAL(Polygon,GetAttrib_Buff) #include #else static char getattrib_buff[ 51 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPolygonVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstPolygon *astPolygonId_( void *, int, int, const double *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ /* Define a macro that expands to a single prototype for function FindInsidePoint for a given data type and operation. */ #define FINDINSIDEPOINT_PROTO0(X,Xtype,Oper) \ static void FindInsidePoint##Oper##X( Xtype, const Xtype *, const int[2], const int[2], int *, int *, int *, int * ); /* Define a macro that expands to a set of prototypes for all operations for function FindInsidePoint for a given data type. */ #define FINDINSIDEPOINT_PROTO(X,Xtype) \ FINDINSIDEPOINT_PROTO0(X,Xtype,LT) \ FINDINSIDEPOINT_PROTO0(X,Xtype,LE) \ FINDINSIDEPOINT_PROTO0(X,Xtype,EQ) \ FINDINSIDEPOINT_PROTO0(X,Xtype,GE) \ FINDINSIDEPOINT_PROTO0(X,Xtype,GT) \ FINDINSIDEPOINT_PROTO0(X,Xtype,NE) /* Use the above macros to define all FindInsidePoint prototypes for all data types and operations. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ FINDINSIDEPOINT_PROTO(LD,long double) #endif FINDINSIDEPOINT_PROTO(D,double) FINDINSIDEPOINT_PROTO(L,long int) FINDINSIDEPOINT_PROTO(UL,unsigned long int) FINDINSIDEPOINT_PROTO(I,int) FINDINSIDEPOINT_PROTO(UI,unsigned int) FINDINSIDEPOINT_PROTO(S,short int) FINDINSIDEPOINT_PROTO(US,unsigned short int) FINDINSIDEPOINT_PROTO(B,signed char) FINDINSIDEPOINT_PROTO(UB,unsigned char) FINDINSIDEPOINT_PROTO(F,float) /* Define a macro that expands to a single prototype for function TraceEdge for a given data type and operation. */ #define TRACEEDGE_PROTO0(X,Xtype,Oper) \ static AstPointSet *TraceEdge##Oper##X( Xtype, const Xtype *, const int[2], const int[2], int, int, int, int, int, int * ); /* Define a macro that expands to a set of prototypes for all operations for function TraceEdge for a given data type. */ #define TRACEEDGE_PROTO(X,Xtype) \ TRACEEDGE_PROTO0(X,Xtype,LT) \ TRACEEDGE_PROTO0(X,Xtype,LE) \ TRACEEDGE_PROTO0(X,Xtype,EQ) \ TRACEEDGE_PROTO0(X,Xtype,GE) \ TRACEEDGE_PROTO0(X,Xtype,GT) \ TRACEEDGE_PROTO0(X,Xtype,NE) /* Use the above macros to define all TraceEdge prototypes for all data types and operations. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ TRACEEDGE_PROTO(LD,long double) #endif TRACEEDGE_PROTO(D,double) TRACEEDGE_PROTO(L,long int) TRACEEDGE_PROTO(UL,unsigned long int) TRACEEDGE_PROTO(I,int) TRACEEDGE_PROTO(UI,unsigned int) TRACEEDGE_PROTO(S,short int) TRACEEDGE_PROTO(US,unsigned short int) TRACEEDGE_PROTO(B,signed char) TRACEEDGE_PROTO(UB,unsigned char) TRACEEDGE_PROTO(F,float) /* Define a macro that expands to a single prototype for function PartHull for a given data type and operation. */ #define PARTHULL_PROTO0(X,Xtype,Oper) \ static void PartHull##Oper##X( Xtype, const Xtype[], int, int, int, int, int, int, int, const int[2], double **, double **, int *, int * ); /* Define a macro that expands to a set of prototypes for all operations for function PartHull for a given data type. */ #define PARTHULL_PROTO(X,Xtype) \ PARTHULL_PROTO0(X,Xtype,LT) \ PARTHULL_PROTO0(X,Xtype,LE) \ PARTHULL_PROTO0(X,Xtype,EQ) \ PARTHULL_PROTO0(X,Xtype,GE) \ PARTHULL_PROTO0(X,Xtype,GT) \ PARTHULL_PROTO0(X,Xtype,NE) /* Use the above macros to define all PartHull prototypes for all data types and operations. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ PARTHULL_PROTO(LD,long double) #endif PARTHULL_PROTO(D,double) PARTHULL_PROTO(L,long int) PARTHULL_PROTO(UL,unsigned long int) PARTHULL_PROTO(I,int) PARTHULL_PROTO(UI,unsigned int) PARTHULL_PROTO(S,short int) PARTHULL_PROTO(US,unsigned short int) PARTHULL_PROTO(B,signed char) PARTHULL_PROTO(UB,unsigned char) PARTHULL_PROTO(F,float) /* Define a macro that expands to a single prototype for function ConvexHull for a given data type and operation. */ #define CONVEXHULL_PROTO0(X,Xtype,Oper) \ static AstPointSet *ConvexHull##Oper##X( Xtype, const Xtype[], const int[2], int, int, int, int * ); /* Define a macro that expands to a set of prototypes for all operations for function ConvexHull for a given data type. */ #define CONVEXHULL_PROTO(X,Xtype) \ CONVEXHULL_PROTO0(X,Xtype,LT) \ CONVEXHULL_PROTO0(X,Xtype,LE) \ CONVEXHULL_PROTO0(X,Xtype,EQ) \ CONVEXHULL_PROTO0(X,Xtype,GE) \ CONVEXHULL_PROTO0(X,Xtype,GT) \ CONVEXHULL_PROTO0(X,Xtype,NE) /* Use the above macros to define all ConvexHull prototypes for all data types and operations. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ CONVEXHULL_PROTO(LD,long double) #endif CONVEXHULL_PROTO(D,double) CONVEXHULL_PROTO(L,long int) CONVEXHULL_PROTO(UL,unsigned long int) CONVEXHULL_PROTO(I,int) CONVEXHULL_PROTO(UI,unsigned int) CONVEXHULL_PROTO(S,short int) CONVEXHULL_PROTO(US,unsigned short int) CONVEXHULL_PROTO(B,signed char) CONVEXHULL_PROTO(UB,unsigned char) CONVEXHULL_PROTO(F,float) /* Define a macro that expands to a single prototype for function FindBoxEdge for a given data type and operation. */ #define FINDBOXEDGE_PROTO0(X,Xtype,Oper) \ static void FindBoxEdge##Oper##X( Xtype, const Xtype[], int, int, int, int, int *, int *, int *, int * ); /* Define a macro that expands to a set of prototypes for all operations for function FindBoxEdge for a given data type. */ #define FINDBOXEDGE_PROTO(X,Xtype) \ FINDBOXEDGE_PROTO0(X,Xtype,LT) \ FINDBOXEDGE_PROTO0(X,Xtype,LE) \ FINDBOXEDGE_PROTO0(X,Xtype,EQ) \ FINDBOXEDGE_PROTO0(X,Xtype,GE) \ FINDBOXEDGE_PROTO0(X,Xtype,GT) \ FINDBOXEDGE_PROTO0(X,Xtype,NE) /* Use the above macros to define all FindBoxEdge prototypes for all data types and operations. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ FINDBOXEDGE_PROTO(LD,long double) #endif FINDBOXEDGE_PROTO(D,double) FINDBOXEDGE_PROTO(L,long int) FINDBOXEDGE_PROTO(UL,unsigned long int) FINDBOXEDGE_PROTO(I,int) FINDBOXEDGE_PROTO(UI,unsigned int) FINDBOXEDGE_PROTO(S,short int) FINDBOXEDGE_PROTO(US,unsigned short int) FINDBOXEDGE_PROTO(B,signed char) FINDBOXEDGE_PROTO(UB,unsigned char) FINDBOXEDGE_PROTO(F,float) /* Non-generic function prototypes. */ static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *DownsizePoly( AstPointSet *, double, int, AstFrame *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstPolygon *Downsize( AstPolygon *, double, int, int * ); static Segment *AddToChain( Segment *, Segment *, int * ); static Segment *NewSegment( Segment *, int, int, int, int * ); static Segment *RemoveFromChain( Segment *, Segment *, int * ); static double Polywidth( AstFrame *, AstLineDef **, int, int, double[ 2 ], int * ); static int GetBounded( AstRegion *, int * ); static int IntCmp( const void *, const void * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static int RegTrace( AstRegion *, int, double *, double **, int * ); static void Cache( AstPolygon *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void EnsureInside( AstPolygon *, int * ); static void FindMax( Segment *, AstFrame *, double *, double *, int, int, int * ); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void ResetCache( AstRegion *this, int * ); static void SetPointSet( AstPolygon *, AstPointSet *, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); static void SmoothPoly( AstPointSet *, int, double, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int GetSimpVertices( AstPolygon *, int * ); static int TestSimpVertices( AstPolygon *, int * ); static void ClearSimpVertices( AstPolygon *, int * ); static void SetSimpVertices( AstPolygon *, int, int * ); /* Member functions. */ /* ================= */ static Segment *AddToChain( Segment *head, Segment *seg, int *status ){ /* * Name: * AddToChain * Purpose: * Add a Segment into the linked list of Segments, maintaining the * required order in the list. * Type: * Private function. * Synopsis: * #include "polygon.h" * Segment *AddToChain( Segment *head, Segment *seg, int *status ) * Class Membership: * Polygon member function * Description: * The linked list of Segments maintained by astDownsize is searched * from the high error end (the head), until a Segment is foound which * has a lower error than the supplied segment. The supplied Segment * is then inserted into the list at that point. * Parameters: * head * The Segment structure at the head of the list (i.e. the segment * with maximum error). * seg * The Segment to be added into the list. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the link head (which will have changed if "seg" has a * higher error than the original head). */ /* Local Variables: */ Segment *tseg; /* Check the global error status. */ if ( !astOK ) return head; /* If the list is empty, return the supplied segment as the new list head. */ if( !head ) { head = seg; /* If the supplied segment has a higher error than the original head, insert the new segment in front of the original head. */ } else if( seg->error > head->error ){ seg->next = head; head->prev = seg; head = seg; /* Otherwise, move down the list from the head until a segment is found which has a lower error than the supplied Segment. Then insert the supplied segment into the list in front of it. */ } else { tseg = head; seg->next = NULL; while( tseg->next ) { if( seg->error > tseg->next->error ) { seg->next = tseg->next; seg->prev = tseg; tseg->next->prev = seg; tseg->next = seg; break; } tseg = tseg->next; } if( !seg->next ) { tseg->next = seg; seg->prev = tseg; } } /* Return the new head. */ return head; } static void Cache( AstPolygon *this, int *status ){ /* * Name: * Cache * Purpose: * Calculate intermediate values and cache them in the Polygon structure. * Type: * Private function. * Synopsis: * #include "polygon.h" * void Cache( AstPolygon *this, int *status ) * Class Membership: * Polygon member function * Description: * This function uses the PointSet stored in the parent Region to calculate * some intermediate values which are useful in other methods. These * values are stored within the Polygon structure. * Parameters: * this * Pointer to the Polygon. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; /* Pointer to base Frame in Polygon */ double **ptr; /* Pointer to data in the encapsulated PointSet */ double end[ 2 ]; /* Start position for edge */ double maxwid; /* Maximum polygon width found so far */ double polcen[ 2 ]; /* Polygon centre perpendicular to current edge */ double polwid; /* Polygon width perpendicular to current edge */ double start[ 2 ]; /* Start position for edge */ int i; /* Axis index */ int nv; /* Number of vertices in Polygon */ /* Check the global error status. */ if ( !astOK ) return; /* Do nothing if the cached information is up to date. */ if( this->stale ) { /* Get a pointer to the base Frame. */ frm = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); /* Get the number of vertices. */ nv = astGetNpoint( ((AstRegion *) this)->points ); /* Get pointers to the coordinate data in the parent Region structure. */ ptr = astGetPoints( ((AstRegion *) this)->points ); /* Free any existing edge information in the Polygon structure. */ if( this->edges ) { for( i = 0; i < nv; i++ ) { this->edges[ i ] = astFree( this->edges[ i ] ); } /* Allocate memory to store new edge information if necessary. */ } else { this->edges = astMalloc( sizeof( AstLineDef *)*(size_t) nv ); this->startsat = astMalloc( sizeof( double )*(size_t) nv ); } /* Check pointers can be used safely. */ if( this->edges ) { /* Create and store a description of each edge. Also form the total distance round the polygon, and the distance from the first vertex at which each edge starts. */ this->totlen = 0.0; start[ 0 ] = ptr[ 0 ][ nv - 1 ]; start[ 1 ] = ptr[ 1 ][ nv - 1 ]; for( i = 0; i < nv; i++ ) { end[ 0 ] = ptr[ 0 ][ i ]; end[ 1 ] = ptr[ 1 ][ i ]; this->edges[ i ] = astLineDef( frm, start, end ); start[ 0 ] = end[ 0 ]; start[ 1 ] = end[ 1 ]; this->startsat[ i ] = this->totlen; this->totlen += this->edges[ i ]->length; } /* We now look for a point that is inside the polygon. We want a point that is well within the polygon, since points that are only just inside the polygon can give numerical problems. Loop round each edge with non-zero length. */ maxwid = -1.0; for( i = 0; i < nv; i++ ) { if( this->edges[ i ]->length > 0.0 ) { /* We define another line perpendicular to the current edge, passing through the mid point of the edge, extending towards the inside of the polygon. The following function returns the distance we can travel along this line before we hit any of the other polygon edges. It also puts the position corresponding to half that distance into "polcen". */ polwid = Polywidth( frm, this->edges, i, nv, polcen, status ); /* If the width of the polygon perpendicular to the current edge is greater than the width perpdeicular to any other edge, record the width and also store the current polygon centre. */ if( polwid > maxwid && polwid != AST__BAD ) { maxwid = polwid; (this->in)[ 0 ] = polcen[ 0 ]; (this->in)[ 1 ] = polcen[ 1 ]; } } } /* If no width was found it probably means that the polygon vertices were given in clockwise order, resulting in the above process probing the infinite extent outside the polygonal hole. In this case any point outside the hole will do, so we use the current contents of the "polcen" array. Set a flag indicating if the vertices are stored in anti-clockwise order. */ if( maxwid < 0.0 ) { (this->in)[ 0 ] = polcen[ 0 ]; (this->in)[ 1 ] = polcen[ 1 ]; this->acw = 0; } else { this->acw = 1; } } /* Free resources */ frm = astAnnul( frm ); /* Indicate cached information is up to date. */ this->stale = 0; } } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Polygon member function (over-rides the astClearAttrib protected * method inherited from the Region class). * Description: * This function clears the value of a specified attribute for a * Polygon, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Polygon. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPolygon *this; /* Pointer to the Polygon structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* SimpVertices. */ /* ------------- */ if ( !strcmp( attrib, "simpvertices" ) ) { astClearSimpVertices( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } /* *++ * Name: c astConvex f AST_CONVEX * Purpose: * Create a new Polygon representing the convex hull of a 2D data grid. * Type: * Public function. * Synopsis: c #include "polygon.h" c AstPolygon *astConvex( value, int oper, const array[], c const int lbnd[2], const int ubnd[2], int starpix ) f RESULT = AST_CONVEX( VALUE, OPER, ARRAY, LBND, UBND, STARPIX, STATUS ) * Class Membership: * Polygon method. * Description: * This is a set of functions that create the shortest Polygon that * encloses all pixels with a specified value within a gridded * 2-dimensional data array (e.g. an image). * * A basic 2-dimensional Frame is used to represent the pixel coordinate * system in the returned Polygon. The Domain attribute is set to * "PIXEL", the Title attribute is set to "Pixel coordinates", and the * Unit attribute for each axis is set to "pixel". All other * attributes are left unset. The nature of the pixel coordinate system * is determined by parameter c "starpix". f STARPIX. * * You should use a function which matches the numerical type of the * data you are processing by replacing in the generic function * name c astConvex f AST_CONVEX c by an appropriate 1- or 2-character type code. For example, if you * are procesing data with type c "float", you should use the function astConvexF f REAL, you should use the function AST_CONVEXR * (see the "Data Type Codes" section below for the codes appropriate to * other numerical types). * Parameters: c value f VALUE = (Given) * A data value that specifies the pixels to be included within the * convex hull. c oper f OPER = INTEGER (Given) * Indicates how the c "value" f VALUE * parameter is used to select the required pixels. It can * have any of the following values: c - AST__LT: include pixels with value less than "value". c - AST__LE: include pixels with value less than or equal to "value". c - AST__EQ: include pixels with value equal to "value". c - AST__NE: include pixels with value not equal to "value". c - AST__GE: include pixels with value greater than or equal to "value". c - AST__GT: include pixels with value greater than "value". f - AST__LT: include pixels with value less than VALUE. f - AST__LE: include pixels with value less than or equal to VALUE. f - AST__EQ: include pixels with value equal to VALUE. f - AST__NE: include pixels with value not equal to VALUE. f - AST__GE: include pixels with value greater than or equal to VALUE. f - AST__GT: include pixels with value greater than VALUE. c array f ARRAY( * ) = (Given) c Pointer to a f A * 2-dimensional array containing the data to be processed. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if c you are using astConvexF, the type of each array element c should be "float"). f you are using AST_CONVEXR, the type of each array element f should be REAL). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the second dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c lbnd f LBND( 2 ) = INTEGER (Given) c Pointer to an array of two integers f An array * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. c ubnd f UBND( 2) = INTEGER (Given) c Pointer to an array of two integers f An array * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * c Note that "lbnd" and "ubnd" together define the shape f Note that LBND and UBND together define the shape * and size of the input grid, its extent along a particular c (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the c index "j" to be zero-based). They also define f (J'th) dimension being UBND(J)-LBND(J)+1. They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre or upper corner, as selected by parameter c "starpix". f STARPIX. c starpix f STARPIX = LOGICAL (Given) * A flag indicating the nature of the pixel coordinate system used * to describe the vertex positions in the returned Polygon. If c non-zero, f .TRUE., * the standard Starlink definition of pixel coordinate is used in * which a pixel with integer index I spans a range of pixel coordinate * from (I-1) to I (i.e. pixel corners have integral pixel coordinates). c If zero, f If .FALSE., * the definition of pixel coordinate used by other AST functions c such as astResample, astMask, f such as AST_RESAMPLE, AST_MASK, * etc., is used. In this definition, a pixel with integer index I * spans a range of pixel coordinate from (I-0.5) to (I+0.5) (i.e. * pixel centres have integral pixel coordinates). f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astConvex() f AST_CONVEX = INTEGER * A pointer to the required Polygon. c NULL f AST__NULL * is returned without error if the array contains no pixels that * satisfy the criterion specified by c "value" and "oper". f VALUE and OPER. * Notes: c - NULL f - AST__NULL * will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. * Data Type Codes: * To select the appropriate masking function, you should c replace in the generic function name astConvex with a f replace in the generic function name AST_CONVEX with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: c - D: double c - F: float c - L: long int c - UL: unsigned long int c - I: int c - UI: unsigned int c - S: short int c - US: unsigned short int c - B: byte (signed char) c - UB: unsigned byte (unsigned char) f - D: DOUBLE PRECISION f - R: REAL f - I: INTEGER f - UI: INTEGER (treated as unsigned) f - S: INTEGER*2 (short integer) f - US: INTEGER*2 (short integer, treated as unsigned) f - B: BYTE (treated as signed) f - UB: BYTE (treated as unsigned) * c For example, astConvexD would be used to process "double" c data, while astConvexS would be used to process "short int" c data, etc. f For example, AST_CONVEXD would be used to process DOUBLE f PRECISION data, while AST_CONVEXS would be used to process f short integer data (stored in an INTEGER*2 array), etc. f f For compatibility with other Starlink facilities, the codes W f and UW are provided as synonyms for S and US respectively (but f only in the Fortran interface to AST). *-- */ /* Define a macro to implement the function for a specific data type. Note, this function cannot be a virtual function since the argument list does not include a Polygon, and so no virtual function table is available. */ #define MAKE_CONVEX(X,Xtype) \ AstPolygon *astConvex##X##_( Xtype value, int oper, const Xtype array[], \ const int lbnd[2], const int ubnd[2], \ int starpix, int *status ) { \ \ /* Local Variables: */ \ AstFrame *frm; /* Frame in which to define the Polygon */ \ AstPointSet *candidate; /* Candidate polygon vertices */ \ AstPolygon *result; /* Result value to return */ \ int xdim; /* Number of pixels per row */ \ int ydim; /* Number of rows */ \ static double junk[ 6 ] = {0.0, 0.0, 1.0, 1.0, 0.0, 1.0 }; /* Junk poly */ \ \ /* Initialise. */ \ result = NULL; \ candidate = NULL; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Get the array dimensions. */ \ xdim = ubnd[ 0 ] - lbnd[ 0 ] + 1; \ ydim = ubnd[ 1 ] - lbnd[ 1 ] + 1; \ \ /* Get the basic concvex hull. */ \ if( oper == AST__LT ) { \ candidate = ConvexHullLT##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( oper == AST__LE ) { \ candidate = ConvexHullLE##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( oper == AST__EQ ) { \ candidate = ConvexHullEQ##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( oper == AST__NE ) { \ candidate = ConvexHullNE##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( oper == AST__GE ) { \ candidate = ConvexHullGE##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( oper == AST__GT ) { \ candidate = ConvexHullGT##X( value, array, lbnd, starpix, xdim, ydim, status ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astConvex"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ } \ \ /* Check some good selected values were found. */ \ if( candidate ) { \ \ /* Create a default Polygon with 3 junk vertices. */ \ frm = astFrame( 2, "Domain=PIXEL,Unit(1)=pixel,Unit(2)=pixel," \ "Title=Pixel coordinates", status ); \ result = astPolygon( frm, 3, 3, junk, NULL, " ", status ); \ \ /* Change the PointSet within the Polygon to the one created above. */ \ SetPointSet( result, candidate, status ); \ \ /* Free resources. */ \ frm = astAnnul( frm ); \ candidate = astAnnul( candidate ); \ } \ \ /* If an error occurred, clear the returned result. */ \ if ( !astOK ) result = astAnnul( result ); \ \ /* Return the result. */ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_CONVEX(LD,long double) #endif MAKE_CONVEX(D,double) MAKE_CONVEX(L,long int) MAKE_CONVEX(UL,unsigned long int) MAKE_CONVEX(I,int) MAKE_CONVEX(UI,unsigned int) MAKE_CONVEX(S,short int) MAKE_CONVEX(US,unsigned short int) MAKE_CONVEX(B,signed char) MAKE_CONVEX(UB,unsigned char) MAKE_CONVEX(F,float) /* Undefine the macros. */ #undef MAKE_CONVEX /* * Name: * ConvexHull * Purpose: * Find the convex hull enclosing selected pixels in a 2D array. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstPointSet *ConvexHull( value, const array[], * const int lbnd[2], int starpix, * int xdim, int ydim, int *status ) * Class Membership: * Polygon member function * Description: * This function uses an algorithm similar to "Andrew's Monotone Chain * Algorithm" to create a list of vertices describing the convex hull * enclosing the selected pixels in the supplied array. The vertices * are returned in a PointSet. * Parameters: * value * A data value that specifies the pixels to be selected. * array * Pointer to a 2-dimensional array containing the data to be * processed. The numerical type of this array should match the 1- * or 2-character type code appended to the function name. * lbnd * The lower pixel index bounds of the array. * starpix * If non-zero, the usual Starlink definition of pixel coordinate * is used (integral values at pixel corners). Otherwise, the * system used by other AST functions such as astResample is used * (integral values at pixel centres). * xdim * The number of pixels along each row of the array. * ydim * The number of rows in the array. * status * Pointer to the inherited status variable. * Returned Value: * A PointSet holding the vertices of the convex hull, or NULL if an * error occurs. * Notes: * - The following code has been designed with a view to it being * multi-threaded at some point. */ /* Define a macro to implement the function for a specific data type and operation. */ #define MAKE_CONVEXHULL(X,Xtype,Oper,OperI) \ static AstPointSet *ConvexHull##Oper##X( Xtype value, const Xtype array[], \ const int lbnd[2], int starpix, \ int xdim, int ydim, int *status ) { \ \ /* Local Variables: */ \ AstPointSet *result; \ double **ptr; \ double *xv1; \ double *xv2; \ double *xv3; \ double *xv4; \ double *xvert; \ double *yv1; \ double *yv2; \ double *yv3; \ double *yv4; \ double *yvert; \ int nv1; \ int nv2; \ int nv3; \ int nv4; \ int nv; \ int xhi; \ int xhiymax; \ int xhiymin; \ int xlo; \ int xloymax; \ int xloymin; \ int yhi; \ int yhixmax; \ int yhixmin; \ int ylo; \ int yloxmax; \ int yloxmin; \ \ /* Initialise */ \ result = NULL; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Find the lowest Y value at any selected pixel, and find the max and \ min X value of the selected pixels at that lowest Y value. */ \ FindBoxEdge##Oper##X( value, array, xdim, ydim, 1, 1, &ylo, &yloxmax, \ &yloxmin, status ); \ \ /* Skip if there are no selected values in the array. */ \ if( ylo > 0 ) { \ \ /* Find the highest Y value at any selected pixel, and find the max and \ min X value of the selected pixels at that highest Y value. */ \ FindBoxEdge##Oper##X( value, array, xdim, ydim, 1, 0, &yhi, &yhixmax, \ &yhixmin, status ); \ \ /* Find the lowest X value at any selected pixel, and find the max and \ min Y value of the selected pixels at that lowest X value. */ \ FindBoxEdge##Oper##X( value, array, xdim, ydim, 0, 1, &xlo, &xloymax, \ &xloymin, status ); \ \ /* Find the highest X value at any selected pixel, and find the max and \ min Y value of the selected pixels at that highest X value. */ \ FindBoxEdge##Oper##X( value, array, xdim, ydim, 0, 0, &xhi, &xhiymax, \ &xhiymin, status ); \ \ /* Create a list of vertices for the bottom right corner of the bounding \ box of the selected pixels. */ \ PartHull##Oper##X( value, array, xdim, ydim, yloxmax, ylo, xhi, xhiymin, \ starpix, lbnd, &xv1, &yv1, &nv1, status ); \ \ /* Create a list of vertices for the top right corner of the bounding \ box of the selected pixels. */ \ PartHull##Oper##X( value, array, xdim, ydim, xhi, xhiymax, yhixmax, yhi, \ starpix, lbnd, &xv2, &yv2, &nv2, status ); \ \ /* Create a list of vertices for the top left corner of the bounding \ box of the selected pixels. */ \ PartHull##Oper##X( value, array, xdim, ydim, yhixmin, yhi, xlo, xloymax, \ starpix, lbnd, &xv3, &yv3, &nv3, status ); \ \ /* Create a list of vertices for the bottom left corner of the bounding \ box of the selected pixels. */ \ PartHull##Oper##X( value, array, xdim, ydim, xlo, xloymin, yloxmin, ylo, \ starpix, lbnd, &xv4, &yv4, &nv4, status ); \ \ /* Concatenate the four vertex lists and store them in the returned \ PointSet. */ \ nv = nv1 + nv2 + nv3 + nv4; \ result = astPointSet( nv, 2, " ", status ); \ ptr = astGetPoints( result ); \ if( astOK ) { \ xvert = ptr[ 0 ]; \ yvert = ptr[ 1 ]; \ \ memcpy( xvert, xv1, nv1*sizeof( double ) ); \ memcpy( yvert, yv1, nv1*sizeof( double ) ); \ xvert += nv1; \ yvert += nv1; \ \ memcpy( xvert, xv2, nv2*sizeof( double ) ); \ memcpy( yvert, yv2, nv2*sizeof( double ) ); \ xvert += nv2; \ yvert += nv2; \ \ memcpy( xvert, xv3, nv3*sizeof( double ) ); \ memcpy( yvert, yv3, nv3*sizeof( double ) ); \ xvert += nv3; \ yvert += nv3; \ \ memcpy( xvert, xv4, nv4*sizeof( double ) ); \ memcpy( yvert, yv4, nv4*sizeof( double ) ); \ } \ \ /* Free resources. */ \ xv1 = astFree( xv1 ); \ xv2 = astFree( xv2 ); \ xv3 = astFree( xv3 ); \ xv4 = astFree( xv4 ); \ yv1 = astFree( yv1 ); \ yv2 = astFree( yv2 ); \ yv3 = astFree( yv3 ); \ yv4 = astFree( yv4 ); \ } \ \ /* Free the returned PointSet if an error occurred. */ \ if( result && !astOK ) result = astAnnul( result ); \ \ /* Return the result. */ \ return result; \ } /* Define a macro that uses the above macro to to create implementations of ConvexHull for all operations. */ #define MAKEALL_CONVEXHULL(X,Xtype) \ MAKE_CONVEXHULL(X,Xtype,LT,AST__LT) \ MAKE_CONVEXHULL(X,Xtype,LE,AST__LE) \ MAKE_CONVEXHULL(X,Xtype,EQ,AST__EQ) \ MAKE_CONVEXHULL(X,Xtype,NE,AST__NE) \ MAKE_CONVEXHULL(X,Xtype,GE,AST__GE) \ MAKE_CONVEXHULL(X,Xtype,GT,AST__GT) /* Expand the above macro to generate a function for each required data type and operation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKEALL_CONVEXHULL(LD,long double) #endif MAKEALL_CONVEXHULL(D,double) MAKEALL_CONVEXHULL(L,long int) MAKEALL_CONVEXHULL(UL,unsigned long int) MAKEALL_CONVEXHULL(I,int) MAKEALL_CONVEXHULL(UI,unsigned int) MAKEALL_CONVEXHULL(S,short int) MAKEALL_CONVEXHULL(US,unsigned short int) MAKEALL_CONVEXHULL(B,signed char) MAKEALL_CONVEXHULL(UB,unsigned char) MAKEALL_CONVEXHULL(F,float) /* Undefine the macros. */ #undef MAKE_CONVEXHULL #undef MAKEALL_CONVEXHULL static AstPolygon *Downsize( AstPolygon *this, double maxerr, int maxvert, int *status ) { /* *++ * Name: c astDownsize f AST_DOWNSIZE * Purpose: * Reduce the number of vertices in a Polygon. * Type: * Public virtual function. * Synopsis: c #include "polygon.h" c AstPolygon *astDownsize( AstPolygon *this, double maxerr, int maxvert ) f RESULT = AST_DOWNSIZE( THIS, MAXERR, MAXVERT, STATUS ) * Class Membership: * Polygon method. * Description: * This function returns a pointer to a new Polygon that contains a * subset of the vertices in the supplied Polygon. The subset is * chosen so that the returned Polygon is a good approximation to * the supplied Polygon, within the limits specified by the supplied * parameter values. That is, the density of points in the returned * Polygon is greater at points where the curvature of the boundary of * the supplied Polygon is greater. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Polygon. c maxerr f MAXERR = DOUBLE PRECISION (Given) * The maximum allowed discrepancy between the supplied and * returned Polygons, expressed as a geodesic distance within the * Polygon's coordinate frame. If this is zero or less, the * returned Polygon will have the number of vertices specified by c maxvert. f MAXVERT. c maxvert f MAXVERT = INTEGER (Given) * The maximum allowed number of vertices in the returned Polygon. * If this is less than 3, the number of vertices in the returned * Polygon will be the minimum needed to achieve the maximum * discrepancy specified by c maxerr. f MAXERR. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astDownsize() f AST_DOWNSIZE = INTEGER * Pointer to the new Polygon. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ AstFrame *frm; /* Base Frame from the Polygon */ AstPointSet *pset; /* PointSet holding vertices of downsized polygon */ AstPolygon *result; /* Returned pointer to new Polygon */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the base Frame of the Polygon. */ frm = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); /* Create a PointSet holding the vertices of the downsized polygon. */ pset = DownsizePoly( ((AstRegion *) this)->points, maxerr, maxvert, frm, status ); /* Take a deep copy of the supplied Polygon. */ result = astCopy( this ); /* Change the PointSet within the result Polygon to the one created above. */ \ SetPointSet( result, pset, status ); \ /* Free resources. */ frm = astAnnul( frm ); pset = astAnnul( pset ); /* If an error occurred, annul the returned Polygon. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *DownsizePoly( AstPointSet *pset, double maxerr, int maxvert, AstFrame *frm, int *status ) { /* * Name: * DownsizePoly * Purpose: * Reduce the number of vertices in a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstPointSet *DownsizePoly( AstPointSet *pset, double maxerr, int maxvert, * AstFrame *frm, int *status ) * Class Membership: * Polygon member function. * Description: * This function returns a pointer to a new PointSet that contains a * subset of the vertices in the supplied PointSet. The subset is * chosen so that the returned polygon is a good approximation to * the supplied polygon, within the limits specified by the supplied * parameter values. That is, the density of points in the returned * polygon is greater at points where the curvature of the boundary of * the supplied polygon is greater. * Parameters: * pset * Pointer to the PointSet holding the polygon vertices. * maxerr * The maximum allowed discrepancy between the supplied and * returned Polygons, expressed as a geodesic distance within the * Polygon's coordinate frame. If this is zero or less, the * returned Polygon will have the number of vertices specified by * maxvert. * maxvert * The maximum allowed number of vertices in the returned Polygon. * If this is less than 3, the number of vertices in the returned * Polygon will be the minimum needed to achieve the maximum * discrepancy specified by * maxerr. * frm * Pointer to the Frame in which the polygon is defined. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the new PointSet. * 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: */ AstPointSet *result; /* Returned pointer to new PointSet */ Segment *head; /* Pointer to new polygon edge with highest error */ Segment *seg1; /* Pointer to new polygon edge */ Segment *seg2; /* Pointer to new polygon edge */ Segment *seg3; /* Pointer to new polygon edge */ double **ptr; /* Pointer to arrays of axis values */ double *x; /* Pointer to array of X values for old Polygon */ double *xnew; /* Pointer to array of X values for new Polygon */ double *y; /* Pointer to array of Y values for old Polygon */ double *ynew; /* Pointer to array of Y values for new Polygon */ double x1; /* Lowest X value at any vertex */ double x2; /* Highest X value at any vertex */ double y1; /* Lowest Y value at any vertex */ double y2; /* Highest Y value at any vertex */ int *newpoly; /* Holds indices of retained input vertices */ int i1; /* Index of first vertex added to output polygon */ int i1x; /* Index of vertex with lowest X */ int i1y; /* Index of vertex with lowest Y */ int i2; /* Index of second vertex added to output polygon */ int i2x; /* Index of vertex with highest X */ int i2y; /* Index of vertex with highest Y */ int i3; /* Index of third vertex added to output polygon */ int iadd; /* Normalised vertex index */ int iat; /* Index at which to store new vertex index */ int newlen; /* Number of vertices currently in new Polygon */ int nv; /* Number of vertices in old Polygon */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the number of vertices in the supplied polygon. */ nv = astGetNpoint( pset ); /* If the maximum error allowed is zero, and the maximum number of vertices is equal to or greater than the number in the supplied polygon, just return a deep copy of the supplied PointSet. */ if( maxerr <= 0.0 && ( maxvert < 3 || maxvert >= nv ) ) { result = astCopy( pset ); /* Otherwise... */ } else { /* Get pointers to the X and Y arrays holding the vertex coordinates in the supplied polygon. */ ptr = astGetPoints( pset ); x = ptr[ 0 ]; y = ptr[ 1 ]; /* Allocate memory for an array to hold the original indices of the vertices to be used to create the returned Polygon. This array is expanded as needed. */ newpoly = astMalloc( 10*sizeof( int ) ); /* Check the pointers can be used safely. */ if( astOK ) { /* We first need to decide on three widely spaced vertices which form a reasonable triangular approximation to the whole polygon. First find the vertices with the highest and lowest Y values, and the highest and lowest X values. */ x1 = DBL_MAX; x2 = -DBL_MAX; y1 = DBL_MAX; y2 = -DBL_MAX; i1y = i1x = 0; i2y = i2x = nv/2; for( i3 = 0; i3 < nv; i3++ ) { if( y[ i3 ] < y1 ) { y1 = y[ i3 ]; i1y = i3; } else if( y[ i3 ] > y2 ) { y2 = y[ i3 ]; i2y = i3; } if( x[ i3 ] < x1 ) { x1 = x[ i3 ]; i1x = i3; } else if( x[ i3 ] > x2 ) { x2 = x[ i3 ]; i2x = i3; } } /* Use the axis which spans the greater range. */ if( y2 - y1 > x2 - x1 ) { i1 = i1y; i2 = i2y; } else { i1 = i1x; i2 = i2x; } /* The index with vertex i1 is definitely going to be one of our three vertices. We are going to use the line from i1 to i2 to choose the two other vertices to use. Create a structure describing the segment of the Polygon from the lowest value on the selected axis (X or Y) to the highest value. As always, the polygons is traversed in an anti-clockwise direction. */ seg1 = NewSegment( NULL, i1, i2, nv, status ); /* Find the vertex within this segment which is furthest away from the line on the right hand side (as moving from vertex i1 to vertex i2). */ FindMax( seg1, frm, x, y, nv, 0, status ); /* Likewise, create a structure describing the remained of the Polygon (i.e. the segment from the highest value on the selected axis to the lowest value). Then find the vertex within this segment which is furthest away from the line on the right hand side. */ seg2 = NewSegment( NULL, i2, i1, nv, status ); FindMax( seg2, frm, x, y, nv, 0, status ); /* Select the segment for which the found vertex is furthest from the line. */ if( seg2->error > seg1->error ) { /* If the second segment, we will use the vertex that is farthest from the line as one of our threee vertices. To ensure that movement from vertex i1 to i2 to i3 is anti-clockwise, we must use this new vertex as vertex i3, not i2. */ i3 = seg2->imax; /* Create a description of the polygon segment from vertex i1 to i3, and find the vertex which is furthest to the right of the line joining the two vertices. We use this as the middle vertex (i2). */ seg1 = NewSegment( seg1, i1, i3, nv, status ); FindMax( seg1, frm, x, y, nv, 0, status ); i2 = seg1->imax; /* Do the same if we are choosing the other segment, ordering the vertices to retain anti-clockwise movement from i1 to i2 to i3. */ } else { i2 = seg1->imax; seg1 = NewSegment( seg1, i2, i1, nv, status ); FindMax( seg1, frm, x, y, nv, 0, status ); i3 = seg1->imax; } /* Ensure the vertex indices are in the first cycle. */ if( i2 >= nv ) i2 -= nv; if( i3 >= nv ) i3 -= nv; /* Create Segment structures to describe each of these three edges. */ seg1 = NewSegment( seg1, i1, i2, nv, status ); seg2 = NewSegment( seg2, i2, i3, nv, status ); seg3 = NewSegment( NULL, i3, i1, nv, status ); /* Record these 3 vertices in an array holding the original indices of the vertices to be used to create the returned Polygon. */ newpoly[ 0 ] = i1; newpoly[ 1 ] = i2; newpoly[ 2 ] = i3; /* Indicate the new polygon currently has 3 vertices. */ newlen = 3; /* Search the old vertices between the start and end of segment 3, looking for the vertex which lies furthest from the line of segment 3. The residual between this point and the line is stored in the Segment structure, as is the index of the vertex at which this maximum residual occurred. */ FindMax( seg3, frm, x, y, nv, 1, status ); /* The "head" variable points to the head of a double linked list of Segment structures. This list is ordered by residual, so that the Segment with the maximum residual is at the head, and the Segment with the minimum residual is at the tail. Initially "seg3" is at the head. */ head = seg3; /* Search the old vertices between the start and end of segment 1, looking for the vertex which lies furthest from the line of segment 1. The residual between this point and the line is stored in the Segment structure, as is the index of the vertex at which this maximum residual occurred. */ FindMax( seg1, frm, x, y, nv, 1, status ); /* Insert segment 1 into the linked list of Segments, at a position that maintains the ordering of the segments by error. Thus the head of the list will still have the max error. */ head = AddToChain( head, seg1, status ); /* Do the same for segment 2. */ FindMax( seg2, frm, x, y, nv, 1, status ); head = AddToChain( head, seg2, status ); /* If the maximum allowed number of vertices in the output Polygon is less than 3, allow any number of vertices up to the number in the input Polygon (termination will then be determined just by "maxerr"). */ if( maxvert < 3 ) maxvert = nv; /* Loop round adding an extra vertex to the returned Polygon until the maximum residual between the new and old polygons is no more than "maxerr". Abort early if the specified maximum number of vertices is reached. */ while( head->error > maxerr && newlen < maxvert ) { /* The segment at the head of the list has the max error (that is, it is the segment that departs most from the supplied Polygon). To make the new polygon a better fit to the old polygon, we add the vertex that is furthest away from this segment to the new polygon. Remember that a polygon is cyclic so if the vertex has an index that is greater than the number of vertices in the old polygon, reduce the index by the number of vertices in the old polygon. */ iadd = head->imax; if( iadd >= nv ) iadd -= nv; iat = newlen++; newpoly = astGrow( newpoly, newlen, sizeof( int ) ); if( !astOK ) break; newpoly[ iat ] = iadd; /* We now split the segment that had the highest error into two segments. The split occurs at the vertex that had the highest error. */ seg1 = NewSegment( NULL, head->imax, head->i2, nv, status ); seg2 = head; seg2->i2 = head->imax; /* We do not know where these two new segments should be in the ordered linked list, so remove them from the list. */ head = RemoveFromChain( head, seg1, status ); head = RemoveFromChain( head, seg2, status ); /* Find the vertex that deviates most from the first of these two new segments, and then add the segment into the list of vertices, using the maximum deviation to determine the position of the segment within the list. */ FindMax( seg1, frm, x, y, nv, 1, status ); head = AddToChain( head, seg1, status ); /* Do the same for the second new segment. */ FindMax( seg2, frm, x, y, nv, 1, status ); head = AddToChain( head, seg2, status ); } /* Now we have reached the required accuracy, free resources. */ while( head ) { seg1 = head; head = head->next; seg1 = astFree( seg1 ); } /* If no vertices have been left out, return a deep copy of the supplied PointSet. */ if( newlen == nv ) { result = astCopy( pset ); /* Otherwise, sort the indices of the vertices to be retained so that they are in the same order as they were in the supplied Polygon. */ } else if( astOK ){ qsort( newpoly, newlen, sizeof( int ), IntCmp ); /* Create a new PointSet and get pointers to its axis values. */ result = astPointSet( newlen, 2, " ", status ); ptr = astGetPoints( result ); xnew = ptr[ 0 ]; ynew = ptr[ 1 ]; /* Copy the axis values for the retained vertices from the old to the new PointSet. */ if( astOK ) { for( iat = 0; iat < newlen; iat++ ) { *(xnew++) = x[ newpoly[ iat ] ]; *(ynew++) = y[ newpoly[ iat ] ]; } } } } /* Free resources. */ newpoly = astFree( newpoly ); } /* If an error occurred, annul the returned PointSet. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void EnsureInside( AstPolygon *this, int *status ){ /* * Name: * EnsureInside * Purpose: * Ensure the unnegated Polygon represents the inside of the polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * void EnsureInside( AstPolygon *this, int *status ) * Class Membership: * Polygon member function * Description: * Reversing the order of the vertices of a Polygon is like negating * the Polygon. But the parent Region class assumes that an unnegated * region bounded by closed curves (e.g. boxes, circles, ellipses, etc) * is bounded. So we need to have a way to ensure that a Polygon also * follows this convention. So this function reverses the order of the * vertices in the Polygon, if necessary, to ensure that the unnegated * Polygon is bounded. * Parameters: * this * The Polygon. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstRegion *this_region; double **ptr; double *p; double *q; double tmp; int bounded; int i; int j; int jmid; int negated; int np; /* Check the global error status. */ if ( !astOK ) return; /* Is the unnegated Polygon unbounded? If so, we need to reverse the vertices. */ bounded = astGetBounded( this ); negated = astGetNegated( this ); if( ( bounded && negated ) || ( !bounded && !negated ) ) { this_region = (AstRegion *) this; /* Get a pointer to the arrays holding the coordinates at the Polygon vertices. */ ptr = astGetPoints( this_region->points ); /* Get the number of vertices. */ np = astGetNpoint( this_region->points ); /* Store the index of the last vertex to swap. For odd "np" the central vertex does not need to be swapped. */ jmid = np/2; /* Loop round the two axes spanned by the Polygon. */ for( i = 0; i < 2; i++ ) { /* Get pointers to the first pair of axis values to be swapped - i.e. the first and last axis values. */ p = ptr[ i ]; q = p + np - 1; /* Loop round all pairs of axis values. */ for( j = 0; j < jmid; j++ ) { /* Swap the pair. */ tmp = *p; *(p++) = *q; *(q--) = tmp; } } /* Invert the value of the "Negated" attribute to cancel out the effect of the above vertex reversal. */ astNegate( this ); /* Indicate the cached information in the Polygon structure is stale. */ this->stale = 1; } } /* * Name: * FindBoxEdge * Purpose: * Find an edge of the bounding box containing the selected pixels. * Type: * Private function. * Synopsis: * #include "polygon.h" * void FindBoxEdge( value, const array[], * int xdim, int ydim, int axis, int low, * int *val, int *valmax, int *valmin, * int *status ) * Class Membership: * Polygon member function * Description: * This function search for an edge of the bounding box containing the * selected pixels in the supplied array. * Parameters: * value * A data value that specifies the pixels to be selected. * array * Pointer to a 2-dimensional array containing the data to be * processed. The numerical type of this array should match the 1- * or 2-character type code appended to the function name. * xdim * The number of pixels along each row of the array. * ydim * The number of rows in the array. * axis * The index (0 or 1) of the pixel axis perpendicular to the edge of the * bounding box being found. * low * If non-zero, the lower edge of the bounding box on the axis * specified by "axis" is found and returned. Otherwise, the higher * edge of the bounding box on the axis specified by "axis" is * found and returned. * val * Address of an int in which to return the value on axis "axis" of * the higher or lower (as specified by "low") edge of the bounding * box. * valmax * Address of an int in which to return the highest value on axis * "1-axis" of the selected pixels on the returned edge. * valmin * Address of an int in which to return the lowest value on axis * "1-axis" of the selected pixels on the returned edge. * status * Pointer to the inherited status variable. * Notes; * - Zero is returned for "*val" if no good values are found, or if * an error occurs. */ /* Define a macro to implement the function for a specific data type and operation. */ #define MAKE_FINDBOXEDGE(X,Xtype,Oper,OperI) \ static void FindBoxEdge##Oper##X( Xtype value, const Xtype array[], int xdim, \ int ydim, int axis, int low, int *val, \ int *valmax, int *valmin, int *status ) { \ \ /* Local Variables: */ \ int astep; \ int bstep; \ int a0; \ int a1; \ int b0; \ int b1; \ int inc; \ int a; \ int b; \ const Xtype *pc; \ \ /* Initialise. */ \ *val = 0; \ *valmin = 0; \ *valmax = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* If we are finding an edge that is parallel to the X axis... */ \ if( axis ) { \ \ /* Get the vector step between adjacent pixels on the selected axis, and \ on the other axis. */ \ astep = xdim; \ bstep = 1; \ \ /* Get the first and last value to check on the selected axis, and the \ increment between checks. */ \ if( low ) { \ a0 = 1; \ a1 = ydim; \ inc = 1; \ } else { \ a0 = ydim; \ a1 = 1; \ inc = -1; \ } \ \ /* The first and last value to check on the other axis. */ \ b0 = 1; \ b1 = xdim; \ \ /* Do the same if we are finding an edge that is parallel to the Y axis. */ \ } else { \ astep = 1; \ bstep = xdim; \ \ if( low ) { \ a0 = 1; \ a1 = xdim; \ inc = 1; \ } else { \ a0 = xdim; \ a1 = 1; \ inc = -1; \ } \ \ b0 = 1; \ b1 = ydim; \ } \ \ /* Loop round the axis values. */ \ a = a0; \ while( 1 ) { \ \ /* Get a pointer to the first value to be checked at this axis value. */ \ pc = array + (a - 1)*astep + (b0 - 1)*bstep; \ \ /* Scan the other axis to find the first and last selected pixel. */ \ for( b = b0; b <= b1; b++ ) { \ if( ISVALID(*pc,OperI,value) ) { \ if( *valmin == 0 ) *valmin = b; \ *valmax = b; \ } \ pc += bstep; \ } \ \ /* If any selected pixels were found, store the axis value and exit. */ \ if( *valmax ) { \ *val = a; \ break; \ } \ \ /* Move on to the next axis value. */ \ if( a != a1 ) { \ a += inc; \ } else { \ break; \ } \ \ } \ } /* Define a macro that uses the above macro to to create implementations of FindBoxEdge for all operations. */ #define MAKEALL_FINDBOXEDGE(X,Xtype) \ MAKE_FINDBOXEDGE(X,Xtype,LT,AST__LT) \ MAKE_FINDBOXEDGE(X,Xtype,LE,AST__LE) \ MAKE_FINDBOXEDGE(X,Xtype,EQ,AST__EQ) \ MAKE_FINDBOXEDGE(X,Xtype,NE,AST__NE) \ MAKE_FINDBOXEDGE(X,Xtype,GE,AST__GE) \ MAKE_FINDBOXEDGE(X,Xtype,GT,AST__GT) /* Expand the above macro to generate a function for each required data type and operation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKEALL_FINDBOXEDGE(LD,long double) #endif MAKEALL_FINDBOXEDGE(D,double) MAKEALL_FINDBOXEDGE(L,long int) MAKEALL_FINDBOXEDGE(UL,unsigned long int) MAKEALL_FINDBOXEDGE(I,int) MAKEALL_FINDBOXEDGE(UI,unsigned int) MAKEALL_FINDBOXEDGE(S,short int) MAKEALL_FINDBOXEDGE(US,unsigned short int) MAKEALL_FINDBOXEDGE(B,signed char) MAKEALL_FINDBOXEDGE(UB,unsigned char) MAKEALL_FINDBOXEDGE(F,float) /* Undefine the macros. */ #undef MAKE_FINDBOXEDGE #undef MAKEALL_FINDBOXEDGE /* * Name: * FindInsidePoint * Purpose: * Find a point that is inside the required outline. * Type: * Private function. * Synopsis: * #include "polygon.h" * void FindInsidePoint( value, const array[], * const int lbnd[ 2 ], const int ubnd[ 2 ], * int *inx, int *iny, int *iv, * int *status ); * Class Membership: * Polygon member function * Description: * The central pixel in the array is checked to see if its value meets * the requirements implied by and "value". If so, its pixel * indices and vector index are returned> if not, a spiral search is * made until such a pixel value is found. * Parameters: * value * The data value defining valid pixels. * array * The data array. * lbnd * The lower pixel index bounds of the array. * ubnd * The upper pixel index bounds of the array. * inx * Pointer to an int in which to return the X pixel index of the * first point that meets the requirements implied by and * "value". * iny * Pointer to an int in which to return the Y pixel index of the * first point that meets the requirements implied by and * "value". * iv * Pointer to an int in which to return the vector index of the * first point that meets the requirements implied by and * "value". * status * Pointer to the inherited status variable. * Notes: * - must be one of LT, LE, EQ, NE, GE, GT. */ /* Define a macro to implement the function for a specific data type and operation. */ #define MAKE_FINDINSIDEPOINT(X,Xtype,Oper,OperI) \ static void FindInsidePoint##Oper##X( Xtype value, const Xtype array[], \ const int lbnd[ 2 ], const int ubnd[ 2 ], \ int *inx, int *iny, int *iv, \ int *status ){ \ \ /* Local Variables: */ \ const Xtype *pv; /* Pointer to next data value to test */ \ const char *text; /* Pointer to text describing oper */ \ int cy; /* Central row index */ \ int iskin; /* Index of spiral layer being searched */ \ int nskin; /* Number of spiral layers to search */ \ int nx; /* Pixel per row */ \ int tmp; /* Temporary storage */ \ int xhi; /* High X pixel index bound of current skin */ \ int xlo; /* Low X pixel index bound of current skin */ \ int yhi; /* High X pixel index bound of current skin */ \ int ylo; /* Low X pixel index bound of current skin */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Find number of pixels in one row of the array. */ \ nx = ( ubnd[ 0 ] - lbnd[ 0 ] + 1 ); \ \ /* Find the pixel indices of the central pixel */ \ *inx = ( ubnd[ 0 ] + lbnd[ 0 ] )/2; \ *iny = ( ubnd[ 1 ] + lbnd[ 1 ] )/2; \ \ /* Initialise the vector index and pointer to refer to the central pixel. */ \ *iv = ( *inx - lbnd[ 0 ] ) + nx*( *iny - lbnd[ 1 ] ) ; \ pv = array + (*iv); \ \ /* Test the pixel value, returning if it is valid. This \ relies on the compiler optimisation to remove the "if" statements \ for all but the operation appropriate to the function being defined. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* The central pixel is invalid if we arrive here. So we need to do a \ spiral search out from the centre looking for a valid pixel. Record \ the central row index (this is the row at which we jump to the next \ outer skin when doing the spiral search below). */ \ cy = *iny; \ \ /* Find how many skins can be searched as part of the spiral search \ before the edge of the array is encountered. */ \ nskin = ubnd[ 0 ] - *inx; \ tmp = *inx - lbnd[ 0 ]; \ if( tmp < nskin ) nskin = tmp; \ tmp = ubnd[ 1 ] - *iny; \ if( tmp < nskin ) nskin = tmp; \ tmp = *iny - lbnd[ 1 ]; \ if( tmp < nskin ) nskin = tmp; \ \ /* Initialise the skin box bounds to be just the central pixel. */ \ xlo = xhi = *inx; \ ylo = yhi = *iny; \ \ /* Loop round each skin looking for a valid test pixel. */ \ for( iskin = 0; iskin < nskin; iskin++ ) { \ \ /* Increment the upper and lower bounds of the box forming the next \ skin. */ \ xhi++; \ xlo--; \ yhi++; \ ylo--; \ \ /* Initialise things for the first pixel in the new skin by moving one \ pixel to the right. */ \ pv++; \ (*iv)++; \ (*inx)++; \ \ /* Move up the right hand edge of the box corresponding to the current \ skin. We start at the middle of the right hand edge. */ \ for( *iny = cy; *iny <= yhi; (*iny)++ ) { \ \ /* Test the pixel value, returning if it is valid. This relies on the \ compiler optimisation to remove the "if" statements for all but the \ operation appropriate to the function being defined. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* Move up a pixel. */ \ pv += nx; \ *iv += nx; \ } \ \ /* Move down a pixel so that *iny == yhi. */ \ pv -= nx; \ *iv -= nx; \ (*iny)--; \ \ /* Move left along the top edge of the box corresponding to the current \ skin. */ \ for( *inx = xhi; *inx >= xlo; (*inx)-- ) { \ \ /* Test the pixel value, returning if it is valid. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* Move left a pixel. */ \ pv--; \ (*iv)--; \ } \ \ /* Move right a pixel so that *inx == xlo. */ \ pv++; \ (*iv)++; \ (*inx)++; \ \ /* Move down along the left hand edge of the box corresponding to the current \ skin. */ \ for( *iny = yhi; *iny >= ylo; (*iny)-- ) { \ \ /* Test the pixel value, returning if it is valid. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* Move down a pixel. */ \ pv -= nx; \ *iv -= nx; \ } \ \ /* Move up a pixel so that *iny == ylo. */ \ pv += nx; \ *iv += nx; \ (*iny)++; \ \ /* Move right along the bottom edge of the box corresponding to the current \ skin. */ \ for( *inx = xlo; *inx <= xhi; (*inx)++ ) { \ \ /* Test the pixel value, returning if it is valid. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* Move right a pixel. */ \ pv++; \ (*iv)++; \ } \ \ /* Move left a pixel so that *inx == xhi. */ \ pv--; \ (*iv)--; \ (*inx)--; \ \ /* Move up the right hand edge of the box correspionding to the current \ skin. We stop just below the middle of the right hand edge. */ \ for( *iny = ylo; *iny < cy; (*iny)++ ) { \ \ /* Test the pixel value, returning if it is valid. This relies on the \ compiler optimisation to remove the "if" statements for all but the \ operation appropriate to the function being defined. */ \ if( OperI == AST__LT ) { \ if( *pv < value ) return; \ \ } else if( OperI == AST__LE ) { \ if( *pv <= value ) return; \ \ } else if( OperI == AST__EQ ) { \ if( *pv == value ) return; \ \ } else if( OperI == AST__NE ) { \ if( *pv != value ) return; \ \ } else if( OperI == AST__GE ) { \ if( *pv >= value ) return; \ \ } else { \ if( *pv > value ) return; \ } \ \ /* Move up a pixel. */ \ pv += nx; \ *iv += nx; \ } \ } \ \ /* Report an error if no inside pooint could be found. */ \ if( OperI == AST__LT ) { \ text = "less than"; \ } else if( OperI == AST__LE ) { \ text = "less than or equal to"; \ } else if( OperI == AST__EQ ) { \ text = "equal to"; \ } else if( OperI == AST__NE ) { \ text = "not equal to"; \ } else if( OperI == AST__GE ) { \ text = "greater than or equal to"; \ } else { \ text = "greater than"; \ } \ astError( AST__NONIN, "astOutline"#X": Could not find a pixel value %s " \ "%g in the supplied array.", status, text, (double) value ); \ } /* Define a macro that uses the above macro to to create implementations of FindInsidePoint for all operations. */ #define MAKEALL_FINDINSIDEPOINT(X,Xtype) \ MAKE_FINDINSIDEPOINT(X,Xtype,LT,AST__LT) \ MAKE_FINDINSIDEPOINT(X,Xtype,LE,AST__LE) \ MAKE_FINDINSIDEPOINT(X,Xtype,EQ,AST__EQ) \ MAKE_FINDINSIDEPOINT(X,Xtype,GE,AST__GE) \ MAKE_FINDINSIDEPOINT(X,Xtype,GT,AST__GT) \ MAKE_FINDINSIDEPOINT(X,Xtype,NE,AST__NE) /* Expand the above macro to generate a function for each required data type and operation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKEALL_FINDINSIDEPOINT(LD,long double) #endif MAKEALL_FINDINSIDEPOINT(D,double) MAKEALL_FINDINSIDEPOINT(L,long int) MAKEALL_FINDINSIDEPOINT(UL,unsigned long int) MAKEALL_FINDINSIDEPOINT(I,int) MAKEALL_FINDINSIDEPOINT(UI,unsigned int) MAKEALL_FINDINSIDEPOINT(S,short int) MAKEALL_FINDINSIDEPOINT(US,unsigned short int) MAKEALL_FINDINSIDEPOINT(B,signed char) MAKEALL_FINDINSIDEPOINT(UB,unsigned char) MAKEALL_FINDINSIDEPOINT(F,float) /* Undefine the macros. */ #undef MAKE_FINDINSIDEPOINT #undef MAKEALL_FINDINSIDEPOINT static void FindMax( Segment *seg, AstFrame *frm, double *x, double *y, int nv, int abs, int *status ){ /* * Name: * FindMax * Purpose: * Find the maximum discrepancy between a given line segment and the * Polygon being downsized. * Type: * Private function. * Synopsis: * #include "polygon.h" * void FindMax( Segment *seg, AstFrame *frm, double *x, double *y, * int nv, int abs, int *status ) * Class Membership: * Polygon member function * Description: * The supplied Segment structure describes a range of vertices in * the polygon being downsized. This function checks each of these * vertices to find the one that lies furthest from the line joining the * first and last vertices in the segment. The maximum error, and the * vertex index at which this maximum error is found, is stored in the * Segment structure. * Parameters: * seg * The structure describing the range of vertices to check. It * corresponds to a candidate edge in the downsized polygon. * frm * The Frame in which the positions are defined. * x * Pointer to the X axis values in the original Polygon. * y * Pointer to the Y axis values in the original Polygon. * nv * Total number of vertics in the old Polygon.. * abs * If non-zero, then the stored maximum is the position with * maximum absolute error. Otherwise, the stored maximum is the * position with maximum positive error (positive errors are to the * right when travelling from start to end of the segment). * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding vertex positions */ AstPointSet *pset2; /* PointSet holding offset par/perp components */ double **ptr1; /* Pointers to "pset1" data arrays */ double **ptr2; /* Pointers to "pset2" data arrays */ double *px; /* Pointer to next X value */ double *py; /* Pointer to next Y value */ double ax; /* X value at start */ double ay; /* Y value at start */ double ba; /* Distance between a and b */ double bax; /* X increment from a to b */ double bay; /* Y increment from a to b */ double cax; /* X increment from a to c */ double cay; /* Y increment from a to c */ double end[ 2 ]; /* Position of starting vertex */ double error; /* Error value for current vertex */ double start[ 2 ]; /* Position of starting vertex */ int i1; /* Starting index (always in first cycle) */ int i2; /* Ending index converted to first cycle */ int i2b; /* Upper vertex limit in first cycle */ int i; /* Loop count */ int n; /* Number of vertices to check */ /* Check the global error status. */ if ( !astOK ) return; /* Stuff needed for handling cyclic redundancy of vertex indices. */ i1 = seg->i1; i2 = seg->i2; n = i2 - i1 - 1; i2b = i2; if( i2 >= nv ) { i2 -= nv; i2b = nv; } /* If the segment has no intermediate vertices, set the segment error to zero and return. */ if( n < 1 ) { seg->error = 0.0; seg->imax = i1; /* For speed, we use simple plane geometry if the Polygon is defined in a simple Frame. */ } else if( !strcmp( astGetClass( frm ), "Frame" ) ) { /* Point "a" is the vertex that marks the start of the segment. Point "b" is the vertex that marks the end of the segment. */ ax = x[ i1 ]; ay = y[ i1 ]; bax = x[ i2 ] - ax; bay = y[ i2 ] - ay; ba = sqrt( bax*bax + bay*bay ); /* Initialise the largest error found so far. */ seg->error = -1.0; /* Check the vertices from the start (plus one) up to the end (minus one) or the last vertex (which ever comes first). */ for( i = i1 + 1; i < i2b; i++ ) { /* Position "c" is the vertex being tested. Find the squared distance from "c" to the line joining "a" and "b". */ cax = x[ i ] - ax; cay = y[ i ] - ay; error = ( bay*cax - cay*bax )/ba; if( abs ) error = fabs( error ); /* If this is the largest value found so far, record it. Note the error here is a squared distance. */ if( error > seg->error ) { seg->error = error; seg->imax = i; } } /* If the end vertex is in the next cycle, check the remaining vertex posI would have thought a telentitions in the same way. */ if( i2b != i2 ) { for( i = 0; i < i2; i++ ) { cax = x[ i ] - ax; cay = y[ i ] - ay; error = ( bay*cax - cay*bax )/ba; if( abs ) error = fabs( error ); if( error > seg->error ) { seg->error = error; seg->imax = i + i2b; } } } /* If the polygon is not defined in a simple Frame, we use the overloaded Frame methods to do the geometry. */ } else { /* Create a PointSet to hold the positions of the vertices to test. We do not need to test the start or end vertex. */ pset1 = astPointSet( n, 2, " ", status ); ptr1 = astGetPoints( pset1 ); if( astOK ) { /* Copy the vertex axis values form the start (plus one) up to the end (minus one) vertex or the last vertex (which ever comes first). */ px = ptr1[ 0 ]; py = ptr1[ 1 ]; for( i = i1 + 1; i < i2b; i++ ){ *(px++) = x[ i ]; *(py++) = y[ i ]; } /* If the end vertex is in the next cycle, copy the remaining vertex positions into the PointSet. */ if( i2b != i2 ) { for( i = 0; i < i2; i++ ) { *(px++) = x[ i ]; *(py++) = y[ i ]; } } /* Record the start and end vertex positions. */ start[ 0 ] = x[ i1 ]; start[ 1 ] = y[ i1 ]; end[ 0 ] = x[ i2 ]; end[ 1 ] = y[ i2 ]; /* Resolve the vector from the start to each vertex into two components, parallel and perpendicular to the start->end vector. */ pset2 = astResolvePoints( frm, start, end, pset1, NULL ); ptr2 = astGetPoints( pset2 ); if( astOK ) { /* Find the vertex with largest perpendicular component. */ seg->error = -1.0; py = ptr2[ 1 ]; for( i = 1; i <= n; i++ ) { error = *(py++); if( abs ) error = fabs( error ); if( error > seg->error ) { seg->error = error; seg->imax = i + i1; } } } /* Free resources. */ pset2 = astAnnul( pset2 ); } pset1 = astAnnul( pset1 ); } } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Polygon member function (over-rides the protected astGetAttrib * method inherited from the Region class). * Description: * This function returns a pointer to the value of a specified * attribute for a Polygon, formatted as a character string. * Parameters: * this * Pointer to the Polygon. * 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 Polygon, 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 Polygon. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPolygon *this; /* Pointer to the Polygon structure */ const char *result; /* Pointer value to return */ int ival; /* Integer attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) 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. */ /* SimpVertices. */ /* ------------- */ if ( !strcmp( attrib, "simpvertices" ) ) { ival = astGetSimpVertices( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetBounded( AstRegion *this, int *status ) { /* * Name: * GetBounded * Purpose: * Is the Region bounded? * Type: * Private function. * Synopsis: * #include "polygon.h" * int GetBounded( AstRegion *this, int *status ) * Class Membership: * Polygon method (over-rides the astGetBounded method inherited from * the Region class). * Description: * This function returns a flag indicating if the Region is bounded. * The implementation provided by the base Region class is suitable * for Region sub-classes representing the inside of a single closed * curve (e.g. Circle, Interval, Box, etc). Other sub-classes (such as * CmpRegion, PointList, etc ) may need to provide their own * implementations. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Region is bounded. Zero otherwise. */ /* Local Variables: */ int neg; /* Has the Polygon been negated? */ int result; /* Returned result */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Ensure cached information is available. */ Cache( (AstPolygon *) this, status ); /* See if the Polygon has been negated. */ neg = astGetNegated( this ); /* If the polygon vertices are stored in anti-clockwise order, then the polygon is bounded if it has not been negated. */ if( ( (AstPolygon *) this)->acw ) { result = (! neg ); /* If the polygon vertices are stored in clockwise order, then the polygon is bounded if it has been negated. */ } else { result = neg; } /* Return the result. */ return result; } void astInitPolygonVtab_( AstPolygonVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPolygonVtab * Purpose: * Initialise a virtual function table for a Polygon. * Type: * Protected function. * Synopsis: * #include "polygon.h" * void astInitPolygonVtab( AstPolygonVtab *vtab, const char *name ) * Class Membership: * Polygon vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Polygon 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPolygon) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->Downsize = Downsize; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_resetcache = region->ResetCache; region->ResetCache = ResetCache; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; region->RegPins = RegPins; region->RegBaseMesh = RegBaseMesh; region->RegBaseBox = RegBaseBox; region->RegTrace = RegTrace; region->GetBounded = GetBounded; vtab->ClearSimpVertices = ClearSimpVertices; vtab->GetSimpVertices = GetSimpVertices; vtab->SetSimpVertices = SetSimpVertices; vtab->TestSimpVertices = TestSimpVertices; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump functions. */ astSetDump( vtab, Dump, "Polygon", "Polygonal region" ); astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); /* 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 int IntCmp( const void *a, const void *b ){ /* * Name: * IntCmp * Purpose: * An integer comparison function for the "qsort" function. * Type: * Private function. * Synopsis: * #include "polygon.h" * int IntCmp( const void *a, const void *b ) * Class Membership: * Polygon member function * Description: * See the docs for "qsort". * Parameters: * a * Pointer to the first int * b * Pointer to the second int * Returnd Value: * Positive, negative or zero, depending on whether a is larger than, * equal to, or less than b. */ return *((int*)a) - *((int*)b); } static Segment *NewSegment( Segment *seg, int i1, int i2, int nvert, int *status ){ /* * Name: * NewSegment * Purpose: * Initialise a structure describing a segment of the new Polygon * created by astDownsize. * Type: * Private function. * Synopsis: * #include "polygon.h" * Segment *NewSegment( Segment *seg, int i1, int i2, int nvert, * int *status ) * Class Membership: * Polygon member function * Description: * This function initialises the contents of a structure describing * the specified range of vertices within a Polygon. The cyclic nature * of vertex indices is taken into account. * * If no structure is supplied, memory is allocated to hold a new * structure. * Parameters: * seg * Pointer to a structure to initialise, or NULL if a new structure * is to be allocated. * i1 * The index of a vertex within the old Polygon (supplied to * astDownsize) that marks the start of the new line segment in * the downsized polygon. * i2 * The index of a vertex within the old Polygon (supplied to * astDownsize) that marks the end of the new line segment in * the downsized polygon. * nvert * Total number of vertics in the old Polygon.. * status * Pointer to the inherited status variable. * Returnd Value: * Pointer to the initialised Segment structure. It should be freed using * astFree when no longer needed. */ /* Local Variables: */ Segment *result; /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure to be initialised, allocating memory for a new structure if none was supplied. */ result = seg ? seg : astMalloc( sizeof( Segment ) ); /* Check the pointer can be used safely. */ if( result ) { /* If the supplied ending index is less than the starting index, the ending index must have gone all the way round the polygon and started round again. Increase the ending index by the number of vertices to put it in the same cycle as the starting index. */ if( i2 < i1 ) i2 += nvert; /* If the supplied starting index is within the first cycle (i.e. zero -> nvert-1 ), use the indices as they are (which may mean that the ending index is greater than nvert, but this is handled correctly by other functions). */ if( i1 < nvert ) { result->i1 = i1; result->i2 = i2; /* If the supplied starting index is within the second cycle (i.e. nvert or greater) the ending index will be even greater, so we can reduce both by "nvert" to put them both in the first cycle. The goal is that the starting index should always be in the first cycle, but the ending index may possibly be in the second cycle. */ } else { result->i1 = i1 - nvert; result->i2 = i2 - nvert; } /* Nullify the links to other Segments */ result->next = NULL; result->prev = NULL; } /* Return the pointer to the new Segment structure. */ return result; } /* *++ * Name: c astOutline f AST_OUTLINE * Purpose: * Create a new Polygon outling values in a 2D data grid. * Type: * Public function. * Synopsis: c #include "polygon.h" c AstPolygon *astOutline( value, int oper, const array[], c const int lbnd[2], const int ubnd[2], double maxerr, c int maxvert, const int inside[2], int starpix ) f RESULT = AST_OUTLINE( VALUE, OPER, ARRAY, LBND, UBND, MAXERR, f MAXVERT, INSIDE, STARPIX, STATUS ) * Class Membership: * Polygon method. * Description: * This is a set of functions that create a Polygon enclosing a single * contiguous set of pixels that have a specified value within a gridded * 2-dimensional data array (e.g. an image). * * A basic 2-dimensional Frame is used to represent the pixel coordinate * system in the returned Polygon. The Domain attribute is set to * "PIXEL", the Title attribute is set to "Pixel coordinates", and the * Unit attribute for each axis is set to "pixel". All other * attributes are left unset. The nature of the pixel coordinate system * is determined by parameter c "starpix". f STARPIX. * * The c "maxerr" and "maxvert" f MAXERR and MAXVERT * parameters can be used to control how accurately the returned * Polygon represents the required region in the data array. The * number of vertices in the returned Polygon will be the minimum * needed to achieve the required accuracy. * * You should use a function which matches the numerical type of the * data you are processing by replacing in the generic function * name c astOutline f AST_OUTLINE c by an appropriate 1- or 2-character type code. For example, if you * are procesing data with type c "float", you should use the function astOutlineF f REAL, you should use the function AST_OUTLINER * (see the "Data Type Codes" section below for the codes appropriate to * other numerical types). * Parameters: c value f VALUE = (Given) * A data value that specifies the pixels to be outlined. c oper f OPER = INTEGER (Given) * Indicates how the c "value" f VALUE * parameter is used to select the outlined pixels. It can * have any of the following values: c - AST__LT: outline pixels with value less than "value". c - AST__LE: outline pixels with value less than or equal to "value". c - AST__EQ: outline pixels with value equal to "value". c - AST__NE: outline pixels with value not equal to "value". c - AST__GE: outline pixels with value greater than or equal to "value". c - AST__GT: outline pixels with value greater than "value". f - AST__LT: outline pixels with value less than VALUE. f - AST__LE: outline pixels with value less than or equal to VALUE. f - AST__EQ: outline pixels with value equal to VALUE. f - AST__NE: outline pixels with value not equal to VALUE. f - AST__GE: outline pixels with value greater than or equal to VALUE. f - AST__GT: outline pixels with value greater than VALUE. c array f ARRAY( * ) = (Given) c Pointer to a f A * 2-dimensional array containing the data to be processed. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if c you are using astOutlineF, the type of each array element c should be "float"). f you are using AST_OUTLINER, the type of each array element f should be REAL). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the second dimension least rapidly c (i.e. Fortran array indexing is used). f (i.e. normal Fortran array storage order). c lbnd f LBND( 2 ) = INTEGER (Given) c Pointer to an array of two integers f An array * containing the pixel index of the first pixel in the input grid * along each dimension. c ubnd f UBND( 2) = INTEGER (Given) c Pointer to an array of two integers f An array * containing the pixel index of the last pixel in the input grid * along each dimension. * c Note that "lbnd" and "ubnd" together define the shape f Note that LBND and UBND together define the shape * and size of the input pixel grid, its extent along a particular c (j'th) dimension being ubnd[j]-lbnd[j]+1 pixels. f (J'th) dimension being UBND(J)-LBND(J)+1 pixels. * For FITS images, c the lbnd values will be 1 and the ubnd f the LBND values will be 1 and the UBND * values will be equal to the NAXISi header values. Other * data systems, such as the Starlink NDF system, allow an c arbitrary pixel origin to be used (i.e. lbnd f arbitrary pixel origin to be used (i.e. LBND * is not necessarily 1). * * These bounds also define the input grid's floating point coordinate * system, each pixel having unit extent along each dimension with * integral coordinate values at its centre or upper corner, as selected * by parameter c "starpix". f STARPIX. c maxerr f MAXERR = DOUBLE PRECISION (Given) * Together with c "maxvert", f MAXVERT, * this determines how accurately the returned Polygon represents * the required region of the data array. It gives the target * discrepancy between the returned Polygon and the accurate outline * in the data array, expressed as a number of pixels. Insignificant * vertices are removed from the accurate outline, one by one, until * the number of vertices remaining in the returned Polygon equals c "maxvert", f MAXVERT, * or the largest discrepancy between the accurate outline and the * returned Polygon is greater than c "maxerr". If "maxerr" f MAXERR. If MAXERR * is zero or less, its value is ignored and the returned Polygon will * have the number of vertices specified by c "maxvert". f MAXVERT. c maxvert f MAXVERT = INTEGER (Given) * Together with c "maxerr", f MAXERR, * this determines how accurately the returned Polygon represents * the required region of the data array. It gives the maximum * allowed number of vertices in the returned Polygon. Insignificant * vertices are removed from the accurate outline, one by one, until * the number of vertices remaining in the returned Polygon equals c "maxvert", f MAXVERT, * or the largest discrepancy between the accurate outline and the * returned Polygon is greater than c "maxerr". If "maxvert" f MAXERR. If MAXVERT * is less than 3, its value is ignored and the number of vertices in * the returned Polygon will be the minimum needed to ensure that the * discrepancy between the accurate outline and the returned * Polygon is less than c "maxerr". f MAXERR. c inside f INSIDE( 2 ) = INTEGER (Given) c Pointer to an array of two integers f An array * containing the pixel indices of a pixel known to be inside the * required region. This is needed because the supplied data * array may contain several disjoint areas of pixels that satisfy * the criterion specified by c "value" and "oper". f VALUE and OPER. * In such cases, the area described by the returned Polygon will * be the one that contains the pixel specified by c "inside". f INSIDE. * If the specified pixel is outside the bounds given by c "lbnd" and "ubnd", f LBND and UBND, * or has a value that does not meet the criterion specified by c "value" and "oper", f VALUE and OPER, * then this function will search for a suitable pixel. The search * starts at the central pixel and proceeds in a spiral manner until * a pixel is found that meets the specified crierion. c starpix f STARPIX = LOGICAL (Given) * A flag indicating the nature of the pixel coordinate system used * to describe the vertex positions in the returned Polygon. If c non-zero, f .TRUE., * the standard Starlink definition of pixel coordinate is used in * which a pixel with integer index I spans a range of pixel coordinate * from (I-1) to I (i.e. pixel corners have integral pixel coordinates). c If zero, f If .FALSE., * the definition of pixel coordinate used by other AST functions c such as astResample, astMask, f such as AST_RESAMPLE, AST_MASK, * etc., is used. In this definition, a pixel with integer index I * spans a range of pixel coordinate from (I-0.5) to (I+0.5) (i.e. * pixel centres have integral pixel coordinates). f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astOutline() f AST_OUTLINE = INTEGER * A pointer to the required Polygon. * Notes: * - This function proceeds by first finding a very accurate polygon, * and then removing insignificant vertices from this fine polygon * using c astDownsize. f AST_DOWNSIZE. * - The returned Polygon is the outer boundary of the contiguous set * of pixels that includes ths specified "inside" point, and satisfy * the specified value requirement. This set of pixels may potentially * include "holes" where the pixel values fail to meet the specified * value requirement. Such holes will be ignored by this function. c - NULL f - AST__NULL * will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. * Data Type Codes: * To select the appropriate masking function, you should c replace in the generic function name astOutline with a f replace in the generic function name AST_OUTLINE with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: c - D: double c - F: float c - L: long int c - UL: unsigned long int c - I: int c - UI: unsigned int c - S: short int c - US: unsigned short int c - B: byte (signed char) c - UB: unsigned byte (unsigned char) f - D: DOUBLE PRECISION f - R: REAL f - I: INTEGER f - UI: INTEGER (treated as unsigned) f - S: INTEGER*2 (short integer) f - US: INTEGER*2 (short integer, treated as unsigned) f - B: BYTE (treated as signed) f - UB: BYTE (treated as unsigned) * c For example, astOutlineD would be used to process "double" c data, while astOutlineS would be used to process "short int" c data, etc. f For example, AST_OUTLINED would be used to process DOUBLE f PRECISION data, while AST_OUTLINES would be used to process f short integer data (stored in an INTEGER*2 array), etc. f f For compatibility with other Starlink facilities, the codes W f and UW are provided as synonyms for S and US respectively (but f only in the Fortran interface to AST). *-- */ /* Define a macro to implement the function for a specific data type. Note, this function cannot be a virtual function since the argument list does not include a Polygon, and so no virtual function table is available. */ #define MAKE_OUTLINE(X,Xtype) \ AstPolygon *astOutline##X##_( Xtype value, int oper, const Xtype array[], \ const int lbnd[2], const int ubnd[2], double maxerr, \ int maxvert, const int inside[2], int starpix, \ int *status ) { \ \ /* Local Variables: */ \ AstFrame *frm; /* Frame in which to define the Polygon */ \ AstPointSet *candidate; /* Candidate polygon vertices */ \ AstPointSet *pset; /* PointSet holding downsized polygon vertices */ \ AstPolygon *result; /* Result value to return */ \ const Xtype *pv; /* Pointer to next test point */ \ Xtype v; /* Value of current pixel */ \ double **ptr; /* Pointers to PointSet arrays */ \ int boxsize; /* Half width of smoothign box in vertices */ \ int inx; /* X index of inside point */ \ int iny; /* Y index of inside point */ \ int iv; /* Vector index of next test pixel */ \ int ixv; /* X pixel index of next test point */ \ int nv0; /* Number of vertices in accurate outline */ \ int nx; /* Length of array x axis */ \ int smooth; /* Do we need to smooth the polygon? */ \ int stop_at_invalid; /* Indicates when to stop rightwards search */ \ int tmp; /* Alternative boxsize */ \ int valid; /* Does current pixel meet requirements? */ \ static double junk[ 6 ] = {0.0, 0.0, 1.0, 1.0, 0.0, 1.0 }; /* Junk poly */ \ \ /* Initialise. */ \ result = NULL; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Avoid compiler warnings. */ \ iv = 0; \ \ /* If we are going to be smoothing the polygon before downsizing it, we \ need to ensure that the full polygon is retained within TraceEdge. if \ this is not the case, TraceEdge can remove all vertices from straight \ lines, except for the vertices that mark the beinning and end of the \ straight line. */ \ smooth = ( maxerr > 0.0 || maxvert > 2 ); \ \ /* Store the X dimension of the array. */ \ nx = ubnd[ 0 ] - lbnd[ 0 ] + 1; \ \ /* See if a valid inside point was supplied. It must be inside the bounds \ of the array, and must have a pixel value that meets the specified \ requirement. */ \ inx = inside[ 0 ]; \ iny = inside[ 1 ]; \ valid = ( inx >= lbnd[ 0 ] && inx <= ubnd[ 0 ] && \ iny >= lbnd[ 1 ] && iny <= ubnd[ 1 ] ); \ \ if( valid ) { \ iv = ( inx - lbnd[ 0 ] ) + (iny - lbnd[ 1 ] )*nx; \ v = array[ iv ]; \ \ if( oper == AST__LT ) { \ valid = ( v < value ); \ \ } else if( oper == AST__LE ) { \ valid = ( v <= value ); \ \ } else if( oper == AST__EQ ) { \ valid = ( v == value ); \ \ } else if( oper == AST__NE ) { \ valid = ( v != value ); \ \ } else if( oper == AST__GE ) { \ valid = ( v >= value ); \ \ } else if( oper == AST__GT ) { \ valid = ( v > value ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astOutline"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ } \ } \ \ /* If no valid inside point was supplied, find one now. */ \ if( !valid ) { \ \ if( oper == AST__LT ) { \ FindInsidePointLT##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( oper == AST__LE ) { \ FindInsidePointLE##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( oper == AST__EQ ) { \ FindInsidePointEQ##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( oper == AST__NE ) { \ FindInsidePointNE##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( oper == AST__GE ) { \ FindInsidePointGE##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( oper == AST__GT ) { \ FindInsidePointGT##X( value, array, lbnd, ubnd, &inx, &iny, &iv, status ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astOutline"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ } \ } \ \ /* We now need to find a point on the boundary of the region containing \ the inside point. Starting at the inside point, move to the right \ through the array until a pixel is found which fails to meet the value \ requirement or the edge of the array is reached. */ \ \ candidate = NULL; \ pv = array + iv; \ ixv = inx; \ stop_at_invalid = 1; \ \ while( ++ixv <= ubnd[ 0 ] ) { \ \ /* Get the next pixel value. */ \ v = *(++pv); \ \ /* See if it meets the value requirement. */ \ if( oper == AST__LT ) { \ valid = ( v < value ); \ \ } else if( oper == AST__LE ) { \ valid = ( v <= value ); \ \ } else if( oper == AST__EQ ) { \ valid = ( v == value ); \ \ } else if( oper == AST__NE ) { \ valid = ( v != value ); \ \ } else if( oper == AST__GE ) { \ valid = ( v >= value ); \ \ } else if( oper == AST__GT ) { \ valid = ( v > value ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astOutline"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ break; \ } \ \ /* If we are currently looking for the next invalid pixel, and this pixel \ is invalid... */ \ if( stop_at_invalid ) { \ if( ! valid ) { \ \ /* The current pixel may be on the required polygon, or it may be on the \ edge of a hole contained within the region being outlined. We would \ like to jump over such holes so that we can continue to look for the \ real edge of the region being outlined. In order to determine if we \ have reached a hole, we trace the edge that passes through the current \ pixel, forming a candidate polygon in the process. In the process, We \ see if the inside point falls within this candidate polygon. If it does \ then the polygon is accepted as the required polygon. Otherwise, it is \ rejected as a mere hole, and we continue moving away from the inside \ point, looking for a new edge. */ \ if( oper == AST__LT ) { \ candidate = TraceEdgeLT##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__LE ) { \ candidate = TraceEdgeLE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__EQ ) { \ candidate = TraceEdgeEQ##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__NE ) { \ candidate = TraceEdgeNE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__GE ) { \ candidate = TraceEdgeGE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__GT ) { \ candidate = TraceEdgeGT##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astOutline"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ } \ \ /* If the candidate polygon is the required polygon, break out of the \ loop. Otherwise, indicate that we want to continue moving right, \ across the hole, until we reach the far side of the hole (i.e. find \ the next valid pixel). */ \ if( candidate ) { \ break; \ } else { \ stop_at_invalid = 0; \ } \ } \ \ /* If we are currently looking for the next valid pixel, and the current \ pixel is valid... */ \ } else if( valid ) { \ \ /* We have reached the far side of a hole. Continue moving right, looking \ now for the next invalid pixel (which may be on the required polygon). */ \ stop_at_invalid = 1; \ } \ } \ \ /* If we have not yet found the required polygon, we must have reached \ the right hand edge of the array. So we now follow the edge of the \ array round until we meet the boundary of the required region. */ \ if( !candidate ) { \ if( oper == AST__LT ) { \ candidate = TraceEdgeLT##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__LE ) { \ candidate = TraceEdgeLE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__EQ ) { \ candidate = TraceEdgeEQ##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__NE ) { \ candidate = TraceEdgeNE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__GE ) { \ candidate = TraceEdgeGE##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( oper == AST__GT ) { \ candidate = TraceEdgeGT##X( value, array, lbnd, ubnd, iv - 1, \ ixv - 1, iny, starpix, smooth, status ); \ \ } else if( astOK ){ \ astError( AST__OPRIN, "astOutline"#X": Invalid operation code " \ "(%d) supplied (programming error).", status, oper ); \ } \ } \ \ /* If required smooth the full resolution polygon before downsizing it. */ \ if( smooth ) { \ \ /* Initially, set the boxsize to be equal to the required accouracy. */ \ if( maxerr > 0 ) { \ boxsize = (int) maxerr; \ } else { \ boxsize = INT_MAX; \ } \ \ /* Determine a second box size equal to the average number of vertices in \ the accurate outline, per vertex in the returned Polygon. */ \ nv0 = astGetNpoint( candidate ); \ if( maxvert > 2 ) { \ tmp = nv0/(2*maxvert); \ } else { \ tmp = INT_MAX; \ } \ \ /* Use the minimum of the two box sizes. */ \ if( tmp < boxsize ) boxsize = tmp; \ \ /* Ensure the box is sufficiently small to allow at least 10 full boxes \ (=20 half boxes) around the polygon. */ \ tmp = nv0/20; \ if( tmp < boxsize ) boxsize = tmp; \ if( boxsize == 0 ) boxsize = 1; \ \ /* Smooth the polygon. */ \ SmoothPoly( candidate, boxsize, 1.0, status ); \ } \ \ /* Reduce the number of vertices in the outline. */ \ frm = astFrame( 2, "Domain=PIXEL,Unit(1)=pixel,Unit(2)=pixel," \ "Title=Pixel coordinates", status ); \ pset = DownsizePoly( candidate, maxerr, maxvert, frm, status ); \ \ /* Create a default Polygon with 3 junk vertices. */ \ result = astPolygon( frm, 3, 3, junk, NULL, " ", status ); \ \ /* Change the PointSet within the Polygon to the one created above. */ \ SetPointSet( result, pset, status ); \ \ /* Free resources. Note, we need to free the arrays within the candidate \ PointSet explicitly, since they were not created as part of the \ construction of the PointSet (see TraceEdge). */ \ pset = astAnnul( pset ); \ frm = astAnnul( frm ); \ ptr = astGetPoints( candidate ); \ if( astOK ) { \ astFree( ptr[ 0 ] ); \ astFree( ptr[ 1 ] ); \ } \ candidate = astAnnul( candidate ); \ \ /* If an error occurred, clear the returned result. */ \ if ( !astOK ) result = astAnnul( result ); \ \ /* Return the result. */ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_OUTLINE(LD,long double) #endif MAKE_OUTLINE(D,double) MAKE_OUTLINE(L,long int) MAKE_OUTLINE(UL,unsigned long int) MAKE_OUTLINE(I,int) MAKE_OUTLINE(UI,unsigned int) MAKE_OUTLINE(S,short int) MAKE_OUTLINE(US,unsigned short int) MAKE_OUTLINE(B,signed char) MAKE_OUTLINE(UB,unsigned char) MAKE_OUTLINE(F,float) /* Undefine the macros. */ #undef MAKE_OUTLINE /* * Name: * PartHull * Purpose: * Find the convex hull enclosing selected pixels in one corner of a 2D array. * Type: * Private function. * Synopsis: * #include "polygon.h" * void PartHull( value, const array[], int xdim, * int ydim, int xs, int ys, int xe, int ye, * int starpix, const int lbnd[2], double **xvert, * double **yvert, int *nvert, int *status ) * Class Membership: * Polygon member function * Description: * This function uses an algorithm similar to "Andrew's Monotone Chain * Algorithm" to create a list of vertices describing one corner of the * convex hull enclosing the selected pixels in the supplied array. * The corner is defined to be the area of the array to the right of * the line from (xs,ys) to (xe,ye). * Parameters: * value * A data value that specifies the pixels to be selected. * array * Pointer to a 2-dimensional array containing the data to be * processed. The numerical type of this array should match the 1- * or 2-character type code appended to the function name. * xdim * The number of pixels along each row of the array. * ydim * The number of rows in the array. * xs * The X GRID index of the first pixel on the line to be checked. * ys * The Y GRID index of the first pixel on the line to be checked. * xe * The X GRID index of the last pixel on the line to be checked. * ye * The Y GRID index of the last pixel on the line to be checked. * starpix * If non-zero, the usual Starlink definition of pixel coordinate * is used (integral values at pixel corners). Otherwise, the * system used by other AST functions such as astResample is used * (integral values at pixel centres). * lbnd * The lower pixel index bounds of the array. * xvert * Address of a pointer in which to return a pointer to the list * of GRID x values on the hull. * yvert * Address of a pointer in which to return a pointer to the list * of GRID y values on the hull. * nvert * Address of a pointer in which to return the number of points in * the returned xvert and yvert arrays. * status * Pointer to the inherited status variable. */ /* Define a macro to implement the function for a specific data type and operation. */ #define MAKE_PARTHULL(X,Xtype,Oper,OperI) \ static void PartHull##Oper##X( Xtype value, const Xtype array[], int xdim, \ int ydim, int xs, int ys, int xe, int ye, \ int starpix, const int lbnd[2], \ double **xvert, double **yvert, int *nvert, \ int *status ) { \ \ /* Local Variables: */ \ const Xtype *pc; \ double *pxy; \ double dx2; \ double dx1; \ double dy1; \ double dy2; \ double off; \ double xdelta; \ int ivert; \ int ix; \ int iy; \ int x0; \ int x1; \ int xl; \ int xlim; \ int xr; \ int yinc; \ \ /* Initialise */ \ *yvert = NULL; \ *xvert = NULL; \ *nvert = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* If the line has zero length. just return a single vertex. */ \ if( xs == xe && ys == ye ) { \ *xvert = astMalloc( sizeof( double ) ); \ *yvert = astMalloc( sizeof( double ) ); \ if( astOK ) { \ if( starpix ) { \ (*xvert)[ 0 ] = xs + lbnd[ 0 ] - 1.5; \ (*yvert)[ 0 ] = ys + lbnd[ 1 ] - 1.5; \ } else { \ (*xvert)[ 0 ] = xs + lbnd[ 0 ] - 1.0; \ (*yvert)[ 0 ] = ys + lbnd[ 1 ] - 1.0; \ } \ *nvert = 1; \ } \ return; \ } \ \ /* Otherwise check the line is sloping. */ \ if( xs == xe ) { \ astError( AST__INTER, "astOutline(Polygon): Bounding box " \ "has zero width (internal AST programming error).", \ status ); \ return; \ } else if( ys == ye ) { \ astError( AST__INTER, "astOutline(Polygon): Bounding box " \ "has zero height (internal AST programming error).", \ status ); \ return; \ } \ \ /* Calculate the difference in length between adjacent rows of the area \ to be tested. */ \ xdelta = ((double)( xe - xs ))/((double)( ye - ys )); \ \ /* The left and right X limits */ \ if( xe > xs ) { \ xl = xs; \ xr = xe; \ } else { \ xl = xe; \ xr = xs; \ } \ \ /* Get the increment in row number as we move from the start to the end \ of the line. */ \ yinc = ( ye > ys ) ? 1 : -1; \ \ /* Loop round all rows that cross the region to be tested, from start to \ end of the supplied line. */ \ iy = ys; \ while( astOK ) { \ \ /* Get the GRID X coord where the line crosses this row. */ \ xlim = (int)( 0.5 + xs + xdelta*( iy - ys ) ); \ \ /* Get the index of the first and last columns to be tested on this row. */ \ if( yinc < 0 ) { \ x0 = xl; \ x1 = xlim; \ } else { \ x0 = xlim; \ x1 = xr; \ } \ \ /* Get a pointer to the first pixel to be tested at this row. */ \ pc = array + ( iy - 1 )*xdim + x0 - 1; \ \ /* Loop round all columns to be tested in this row. */ \ for( ix = x0; ix <= x1 && astOK; ix++,pc++ ) { \ \ /* Ignore pixels that are not selected. */ \ if( ISVALID(*pc,OperI,value) ) { \ \ /* If this is the very first pixel, initialise the hull to contain just \ the first pixel. */ \ if( *nvert == 0 ){ \ *xvert = astMalloc( 200*sizeof( double ) ); \ *yvert = astMalloc( 200*sizeof( double ) ); \ if( astOK ) { \ (*xvert)[ 0 ] = ix; \ (*yvert)[ 0 ] = iy; \ *nvert = 1; \ } else { \ break; \ } \ \ /* Otherwise.... */ \ } else { \ \ /* Loop until the hull has been corrected to include the current pixel. */ \ while( 1 ) { \ \ /* If the hull currently contains only one pixel, add the current pixel to \ the end of the hull. */ \ if( *nvert == 1 ){ \ (*xvert)[ 1 ] = ix; \ (*yvert)[ 1 ] = iy; \ *nvert = 2; \ break; \ \ /* Otherwise... */ \ } else { \ \ /* Extend the line from the last-but-one pixel on the hull to the last \ pixel on the hull, and see if the current pixel is to the left of \ this line. If it is, it too is on the hull and so push it onto the end \ of the list of vertices. */ \ dx1 = (*xvert)[ *nvert - 1 ] - (*xvert)[ *nvert - 2 ]; \ dy1 = (*yvert)[ *nvert - 1 ] - (*yvert)[ *nvert - 2 ]; \ dx2 = ix - (*xvert)[ *nvert - 2 ]; \ dy2 = iy - (*yvert)[ *nvert - 2 ]; \ \ if( dx1*dy2 > dx2*dy1 ) { \ ivert = (*nvert)++; \ *xvert = astGrow( *xvert, *nvert, sizeof( double ) ); \ *yvert = astGrow( *yvert, *nvert, sizeof( double ) ); \ if( astOK ) { \ (*xvert)[ ivert ] = ix; \ (*yvert)[ ivert ] = iy; \ } \ \ /* Leave the loop now that the new point is on the hull. */ \ break; \ \ /* If the new point is to the left of the line, then the last point \ previously thought to be on hull is in fact not on the hull, so remove \ it. We then loop again to compare the new pixel with modified hull. */ \ } else { \ (*nvert)--; \ } \ } \ } \ } \ } \ } \ \ if( iy == ye ) { \ break; \ } else { \ iy += yinc; \ } \ \ } \ \ /* Convert GRID coords to PIXEL coords. */ \ if( astOK ) { \ pxy = *xvert; \ off = starpix ? lbnd[ 0 ] - 1.5 : lbnd[ 0 ] - 1.0; \ for( ivert = 0; ivert < *nvert; ivert++ ) *(pxy++) += off; \ \ pxy = *yvert; \ off = starpix ? lbnd[ 1 ] - 1.5 : lbnd[ 1 ] - 1.0; \ for( ivert = 0; ivert < *nvert; ivert++ ) *(pxy++) += off; \ \ /* Free lists if an error has occurred. */ \ } else { \ *xvert = astFree( *xvert ); \ *yvert = astFree( *yvert ); \ *nvert = 0; \ } \ } /* Define a macro that uses the above macro to to create implementations of PartHull for all operations. */ #define MAKEALL_PARTHULL(X,Xtype) \ MAKE_PARTHULL(X,Xtype,LT,AST__LT) \ MAKE_PARTHULL(X,Xtype,LE,AST__LE) \ MAKE_PARTHULL(X,Xtype,EQ,AST__EQ) \ MAKE_PARTHULL(X,Xtype,NE,AST__NE) \ MAKE_PARTHULL(X,Xtype,GE,AST__GE) \ MAKE_PARTHULL(X,Xtype,GT,AST__GT) /* Expand the above macro to generate a function for each required data type and operation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKEALL_PARTHULL(LD,long double) #endif MAKEALL_PARTHULL(D,double) MAKEALL_PARTHULL(L,long int) MAKEALL_PARTHULL(UL,unsigned long int) MAKEALL_PARTHULL(I,int) MAKEALL_PARTHULL(UI,unsigned int) MAKEALL_PARTHULL(S,short int) MAKEALL_PARTHULL(US,unsigned short int) MAKEALL_PARTHULL(B,signed char) MAKEALL_PARTHULL(UB,unsigned char) MAKEALL_PARTHULL(F,float) /* Undefine the macros. */ #undef MAKE_PARTHULL #undef MAKEALL_PARTHULL static double Polywidth( AstFrame *frm, AstLineDef **edges, int i, int nv, double cen[ 2 ], int *status ){ /* * Name: * Polywidth * Purpose: * Find the width of a polygon perpendicular to a given edge. * Type: * Private function. * Synopsis: * #include "polygon.h" * double Polywidth( AstFrame *frm, AstLineDef **edges, int i, int nv, * double cen[ 2 ], int *status ) * Class Membership: * Polygon member function * Description: * This function defines a line perpendicular to a given polygon edge, * passing through the mid point of the edge, extending towards the * inside of the polygon. It returns the distance that can be travelled * along this line before any of the other polygon edges are hit (the * "width" of the polygon perpendicular to the given edge). It also * puts the position corresponding to half that distance into "cen". * Parameters: * frm * The Frame in which the lines are defined. * edges * Array of "nv" pointers to AstLineDef structures, each defining an * edge of the polygon. * i * The index of the edge that is to define the polygon width. * nv * Total number of edges. * cen * An array into which are put the coords of the point half way * along the polygon width line. * status * Pointer to the inherited status variable. * Returnd Value: * The width of the polygon perpendicular to the given edge, or * AST__BAD if the width cannot be determined (usually because the * vertices been supplied in a clockwise direction, effectively * negating the Polygon). */ /* Local Variables: */ AstLineDef *line; double *cross; double d; double end[ 2 ]; double l1; double l2; double result; double start[ 2 ]; int j; /* Check the global error status. */ result = AST__BAD; if ( !astOK ) return result; /* Create a Line description for a line perpendicular to the specified edge, passing through the mid point of the edge, and extending towards the inside of the polygon. First move away from the start along the line to the mid point. This gives the start of the new line. */ l1 = 0.5*( edges[ i ]->length ); astLineOffset( frm, edges[ i ], l1, 0.0, start ); /* We now move away from this position at right angles to the line. We start off by moving 5 times the length of the specified edge. For some Frames (e.g. SkyFrames) this may result in a position that is much too close (i.e. if it goes all the way round the great circle and comes back to the beginning). Therefore, we check that the end point is the requested distance from the start point, and if not, we halve the length of the line and try again. */ l2 = 10.0*l1; while( 1 ) { astLineOffset( frm, edges[ i ], l1, l2, end ); d = astDistance( frm, start, end ); if( d != AST__BAD && fabs( d - l2 ) < 1.0E-6*l2 ) break; l2 *= 0.5; } /* Create a description of the required line. */ line = astLineDef( frm, start, end ); /* Loop round every edge, except for the supplied edge. */ for( j = 0; j < nv; j++ ) { if( j != i ) { /* Find the position at which the line created above crosses the current edge. Skip to the next edge if the line does not intersect the edge within the length of the edge. */ if( astLineCrossing( frm, line, edges[ j ], &cross ) ) { /* Find the distance between the crossing point and the line start. */ d = astDistance( frm, start, cross ); /* If this is less than the smallest found so far, record it. */ if( d != AST__BAD && ( d < result || result == AST__BAD ) ) { result = d; } } /* Free resources */ cross = astFree( cross ); } } line = astFree( line ); /* If a width was found, return the point half way across the polygon. */ if( result != AST__BAD ) { astOffset( frm, start, end, 0.5*result, cen ); /* The usual reason for not finding a width is if the polygon vertices are supplied in clockwise order, effectively negating the polygon, and resulting in the "inside" of the polygon being the infinite region outside a polygonal hole. In this case, the end point of the line perpendicular to the initial edge can be returned as a representative "inside" point. */ } else { cen[ 0 ] = end[ 0 ]; cen[ 1 ] = end[ 1 ]; } /* Return the width. */ return result; } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "polygon.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Polygon member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; /* Pointer to encapsulated Frame */ AstPointSet *pset; /* Pointer to PointSet defining the Region */ AstPolygon *this; /* Pointer to Polygon structure */ AstRegion *reg; /* Base Frame equivalent of supplied Polygon */ double **ptr; /* Pointer to PointSet data */ double *x; /* Pointer to next X axis value */ double *y; /* Pointer to next Y axis value */ double dist; /* Offset along an axis */ double x0; /* The first X axis value */ double y0; /* The first Y axis value */ int ip; /* Point index */ int np; /* No. of points in PointSet */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Polygon structure. */ this = (AstPolygon *) this_region; /* If the base Frame bounding box has already been found, return the values stored in the Polygon structure. */ if( this->lbnd[ 0 ] != AST__BAD ) { lbnd[ 0 ] = this->lbnd[ 0 ]; lbnd[ 1 ] = this->lbnd[ 1 ]; ubnd[ 0 ] = this->ubnd[ 0 ]; ubnd[ 1 ] = this->ubnd[ 1 ]; /* If the base Frame bounding box has not yet been found, find it now and store it in the Polygon structure. */ } else { /* Get the axis values for the PointSet which defines the location and extent of the region in the base Frame of the encapsulated FrameSet. */ pset = this_region->points; ptr = astGetPoints( pset ); np = astGetNpoint( pset ); /* Get a pointer to the base Frame in the frameset encapsulated by the parent Region structure. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Find the upper and lower bounds of the box enclosing all the vertices. The box is expressed in terms of axis offsets from the first vertex, in order to avoid problems with boxes that cross RA=0 or RA=12h */ lbnd[ 0 ] = 0.0; lbnd[ 1 ] = 0.0; ubnd[ 0 ] = 0.0; ubnd[ 1 ] = 0.0; x = ptr[ 0 ]; y = ptr[ 1 ]; x0 = *x; y0 = *y; for( ip = 0; ip < np; ip++, x++, y++ ) { dist = astAxDistance( frm, 1, x0, *x ); if( dist < lbnd[ 0 ] ) { lbnd[ 0 ] = dist; } else if( dist > ubnd[ 0 ] ) { ubnd[ 0 ] = dist; } dist = astAxDistance( frm, 2, y0, *y ); if( dist < lbnd[ 1 ] ) { lbnd[ 1 ] = dist; } else if( dist > ubnd[ 1 ] ) { ubnd[ 1 ] = dist; } } /* Convert the box bounds to absolute values, rather than values relative to the first vertex. */ lbnd[ 0 ] += x0; lbnd[ 1 ] += y0; ubnd[ 0 ] += x0; ubnd[ 1 ] += y0; /* The astNormBox requires a Mapping which can be used to test points in this base Frame. Create a copy of the Polygon and then set its FrameSet so that the current Frame in the copy is the same as the base Frame in the original. */ reg = astCopy( this ); astSetRegFS( reg, frm ); astSetNegated( reg, 0 ); /* Normalise this box. */ astNormBox( frm, lbnd, ubnd, reg ); /* Free resources */ reg = astAnnul( reg ); frm = astAnnul( frm ); /* Store it in the olygon structure for future use. */ this->lbnd[ 0 ] = lbnd[ 0 ]; this->lbnd[ 1 ] = lbnd[ 1 ]; this->ubnd[ 0 ] = ubnd[ 0 ]; this->ubnd[ 1 ] = ubnd[ 1 ]; } } static AstPointSet *RegBaseMesh( AstRegion *this_region, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Polygon member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. Annul the pointer using astAnnul when it * is no longer needed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *frm; /* Base Frame in encapsulated FrameSet */ AstPointSet *result; /* Returned pointer */ AstPolygon *this; /* The Polygon structure */ double **rptr; /* Pointers to returned mesh data */ double **vptr; /* Pointers to vertex data */ double *lens; /* Pointer to work space holding edge lengths */ double d; /* Length of this edge */ double delta; /* Angular separation of points */ double end[ 2 ]; /* End position */ double mp; /* No. of mesh points per unit distance */ double p[ 2 ]; /* Position in 2D Frame */ double start[ 2 ]; /* Start position */ double total; /* Total length of polygon */ int ip; /* Point index */ int iv; /* Vertex index */ int n; /* No. of points on this edge */ int next; /* Index of next point in returned PointSet */ int np; /* No. of points in returned PointSet */ int nv; /* No. of polygon vertices */ /* Initialise */ result= NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this_region->basemesh ) { result = astClone( this_region->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Get a pointer to the Polygon structure. */ this = (AstPolygon *) this_region; /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Get the number of vertices and pointers to the vertex axis values. */ nv = astGetNpoint( this_region->points ); vptr = astGetPoints( this_region->points ); /* Allocate memory to hold the geodesic length of each edge. */ lens = astMalloc( sizeof( double )*(size_t) nv ); if( astOK ) { /* Find the total geodesic distance around the boundary. */ total = 0.0; start[ 0 ] = vptr[ 0 ][ 0 ]; start[ 1 ] = vptr[ 1 ][ 0 ]; for( iv = 1; iv < nv; iv++ ) { end[ 0 ] = vptr[ 0 ][ iv ]; end[ 1 ] = vptr[ 1 ][ iv ]; d = astDistance( frm, start, end ); if( d != AST__BAD ) total += fabs( d ); lens[ iv ] = d; start[ 0 ] = end[ 0 ]; start[ 1 ] = end[ 1 ]; } end[ 0 ] = vptr[ 0 ][ 0 ]; end[ 1 ] = vptr[ 1 ][ 0 ]; d = astDistance( frm, start, end ); if( d != AST__BAD ) total += fabs( d ); lens[ 0 ] = d; /* Find the number of mesh points per unit geodesic distance. */ if( total > 0.0 ){ mp = astGetMeshSize( this )/total; /* Find the total number of mesh points required. */ np = 0; for( iv = 0; iv < nv; iv++ ) { if( lens[ iv ] != AST__BAD ) np += 1 + (int)( lens[ iv ]*mp ); } /* Create a suitable PointSet to hold the returned positions. */ result = astPointSet( np, 2, "", status ); rptr = astGetPoints( result ); if( astOK ) { /* Initialise the index of the next point to be added to the returned PointSet. */ next = 0; /* Loop round each good edge of the polygon. The edge ends at vertex "iv". */ start[ 0 ] = vptr[ 0 ][ 0 ]; start[ 1 ] = vptr[ 1 ][ 0 ]; for( iv = 1; iv < nv; iv++ ) { end[ 0 ] = vptr[ 0 ][ iv ]; end[ 1 ] = vptr[ 1 ][ iv ]; if( lens[ iv ] != AST__BAD ) { /* Add the position of the starting vertex to the returned mesh. */ rptr[ 0 ][ next ] = start[ 0 ]; rptr[ 1 ][ next ] = start[ 1 ]; next++; /* Find the number of points on this edge, and the geodesic distance between them. */ n = 1 + (int) ( lens[ iv ]*mp ); /* If more than one point, find the distance between points. */ if( n > 1 ) { delta = lens[ iv ]/n; /* Loop round the extra points. */ for( ip = 1; ip < n; ip++ ) { /* Find the position of the next mesh point. */ astOffset( frm, start, end, delta*ip, p ); /* Add it to the mesh. */ rptr[ 0 ][ next ] = p[ 0 ]; rptr[ 1 ][ next ] = p[ 1 ]; next++; } } } /* The end of this edge becomes the start of the next. */ start[ 0 ] = end[ 0 ]; start[ 1 ] = end[ 1 ]; } /* Now do the edge which ends at the first vertex. */ end[ 0 ] = vptr[ 0 ][ 0 ]; end[ 1 ] = vptr[ 1 ][ 0 ]; if( lens[ 0 ] != AST__BAD ) { rptr[ 0 ][ next ] = start[ 0 ]; rptr[ 1 ][ next ] = start[ 1 ]; next++; n = 1 + (int)( lens[ 0 ]*mp ); if( n > 1 ) { delta = lens[ 0 ]/n; for( ip = 1; ip < n; ip++ ) { astOffset( frm, start, end, delta*ip, p ); rptr[ 0 ][ next ] = p[ 0 ]; rptr[ 1 ][ next ] = p[ 1 ]; next++; } } } /* Check the PointSet size was correct. */ if( next != np && astOK ) { astError( AST__INTER, "astRegBaseMesh(%s): Error in the " "allocated PointSet size (%d) - should have " "been %d (internal AST programming error).", status, astGetClass( this ), np, next ); } /* Save the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK ) this_region->basemesh = astClone( result ); } } else if( astOK ) { astError( AST__BADIN, "astRegBaseMesh(%s): The boundary of " "the supplied %s has an undefined length.", status, astGetClass( this ), astGetClass( this ) ); } } /* Free resources. */ frm = astAnnul( frm ); lens = astFree( lens ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Polygon member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Polygon. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Polygon "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Polygon. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstFrame *frm; /* Base Frame in supplied Polygon */ AstPointSet *pset1; /* Pointer to copy of supplied PointSet */ AstPointSet *pset2; /* Pointer to PointSet holding resolved components */ AstPolygon *this; /* Pointer to the Polygon structure. */ AstRegion *tunc; /* Uncertainity Region from "this" */ double **ptr1; /* Pointer to axis values in "pset1" */ double **ptr2; /* Pointer to axis values in "pset2" */ double **vptr; /* Pointer to axis values at vertices */ double *safe; /* An interior point in "this" */ double edge_len; /* Length of current edge */ double end[2]; /* Position of end of current edge */ double l1; /* Length of bounding box diagonal */ double l2; /* Length of bounding box diagonal */ double lbnd_tunc[2]; /* Lower bounds of "this" uncertainty Region */ double lbnd_unc[2]; /* Lower bounds of supplied uncertainty Region */ double par; /* Parallel component */ double parmax; /* Max acceptable parallel component */ double prp; /* Perpendicular component */ double start[2]; /* Position of start of current edge */ double ubnd_tunc[2]; /* Upper bounds of "this" uncertainty Region */ double ubnd_unc[2]; /* Upper bounds of supplied uncertainty Region */ double wid; /* Width of acceptable margin around polygon */ int *m; /* Pointer to next mask value */ int i; /* Edge index */ int ip; /* Point index */ int np; /* No. of supplied points */ int nv; /* No. of vertices */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Polygon structure. */ this = (AstPolygon *) this_region; /* Check the supplied PointSet has 2 axis values per point. */ if( astGetNcoord( pset ) != 2 && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axis " "values per point (%d) in the supplied PointSet - should be " "2 (internal AST programming error).", status, astGetClass( this ), astGetNcoord( pset ) ); } /* Get the number of axes in the uncertainty Region and check it is also 2. */ if( unc && astGetNaxes( unc ) != 2 && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axes (%d) " "in the supplied uncertainty Region - should be 2 " "(internal AST programming error).", status, astGetClass( this ), astGetNaxes( unc ) ); } /* Get pointers to the axis values at the polygon vertices. */ vptr = astGetPoints( this_region->points ); /* Get the number of vertices. */ nv = astGetNpoint( this_region->points ); /* Take a copy of the supplied PointSet and get pointers to its axis values,and its size */ pset1 = astCopy( pset ); ptr1 = astGetPoints( pset1 ); np = astGetNpoint( pset1 ); /* Create a PointSet to hold the resolved components and get pointers to its axis data. */ pset2 = astPointSet( np, 2, "", status ); ptr2 = astGetPoints( pset2 ); /* Create a mask array if required. */ if( mask ) *mask = astMalloc( sizeof(int)*(size_t) np ); /* Get the centre of the region in the base Frame. We use this as a "safe" interior point within the region. */ safe = astRegCentre( this, NULL, NULL, 0, AST__BASE ); /* We now find the maximum distance on each axis that a point can be from the boundary of the Polygon for it still to be considered to be on the boundary. First get the Region which defines the uncertainty within the Polygon being checked (in its base Frame), re-centre it on the interior point found above (to avoid problems if the uncertainty region straddles a discontinuity), and get its bounding box. The current Frame of the uncertainty Region is the same as the base Frame of the Polygon. */ tunc = astGetUncFrm( this, AST__BASE ); if( safe ) astRegCentre( tunc, safe, NULL, 0, AST__CURRENT ); astGetRegionBounds( tunc, lbnd_tunc, ubnd_tunc ); /* Find the geodesic length within the base Frame of "this" of the diagonal of the bounding box. */ frm = astGetFrame( this_region->frameset, AST__BASE ); l1 = astDistance( frm, lbnd_tunc, ubnd_tunc ); /* Also get the Region which defines the uncertainty of the supplied points and get its bounding box. First re-centre the uncertainty at the interior position to avoid problems from uncertainties that straddle a discontinuity. */ if( unc ) { if( safe ) astRegCentre( unc, safe, NULL, 0, AST__CURRENT ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); /* Find the geodesic length of the diagonal of this bounding box. */ l2 = astDistance( frm, lbnd_unc, ubnd_unc ); /* Assume zero uncertainty if no "unc" Region was supplied. */ } else { l2 = 0.0; } /* The required border width is half of the total diagonal of the two bounding boxes. */ if( astOK ) { wid = 0.5*( l1 + l2 ); /* Loop round each edge of the polygon. Edge "i" starts at vertex "i-1" and ends at vertex "i". Edge zero starts at vertex "nv-1" and ends at vertex zero. */ start[ 0 ] = vptr[ 0 ][ nv - 1 ]; start[ 1 ] = vptr[ 1 ][ nv - 1 ]; for( i = 0; i < nv; i++ ) { end[ 0 ] = vptr[ 0 ][ i ]; end[ 1 ] = vptr[ 1 ][ i ]; /* Find the length of this edge. */ edge_len = astDistance( frm, start, end ); /* Resolve all the supplied mesh points into components parallel and perpendicular to this edge. */ (void) astResolvePoints( frm, start, end, pset1, pset2 ); /* A point is effectively on this edge if the parallel component is greater than (-wid) and less than (edge_len+wid) AND the perpendicular component has an absolute value less than wid. Identify such positions and set them bad in pset1. */ parmax = edge_len + wid; for( ip = 0; ip < np; ip++ ) { par = ptr2[ 0 ][ ip ]; prp = ptr2[ 1 ][ ip ]; if( par != AST__BAD && prp != AST__BAD ) { if( par > -wid && par < parmax && prp > -wid && prp < wid ) { ptr1[ 0 ][ ip ] = AST__BAD; ptr1[ 1 ][ ip ] = AST__BAD; } } } /* The end of the current edge becomes the start of the next. */ start[ 0 ] = end[ 0 ]; start[ 1 ] = end[ 1 ]; } /* See if any good points are left in pset1. If so, it means that those points were not on any edge of hte Polygon. We use two alogorithms here depending on whether we are creating a mask array, since we can abort the check upon finding the first good point if we are not producing a mask. */ result = 1; if( mask ) { m = *mask; for( ip = 0; ip < np; ip++, m++ ) { if( ptr1[ 0 ][ ip ] != AST__BAD && ptr1[ 1 ][ ip ] != AST__BAD ) { *m = 0; result = 0; } else { *m = 1; } } } else { for( ip = 0; ip < np; ip++ ) { if( ptr1[ 0 ][ ip ] != AST__BAD && ptr1[ 1 ][ ip ] != AST__BAD ) { result = 0; break; } } } } /* Free resources. */ tunc = astAnnul( tunc ); frm = astAnnul( frm ); safe = astFree( safe ); pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static int RegTrace( AstRegion *this_region, int n, double *dist, double **ptr, int *status ){ /* *+ * Name: * RegTrace * Purpose: * Return requested positions on the boundary of a 2D Region. * Type: * Private function. * Synopsis: * #include "polygon.h" * int astTraceRegion( AstRegion *this, int n, double *dist, double **ptr ); * Class Membership: * Polygon member function (overrides the astTraceRegion method * inherited from the parent Region class). * Description: * This function returns positions on the boundary of the supplied * Region, if possible. The required positions are indicated by a * supplied list of scalar parameter values in the range zero to one. * Zero corresponds to some arbitrary starting point on the boundary, * and one corresponds to the end (which for a closed region will be * the same place as the start). * Parameters: * this * Pointer to the Region. * n * The number of positions to return. If this is zero, the function * returns without action (but the returned function value still * indicates if the method is supported or not). * dist * Pointer to an array of "n" scalar parameter values in the range * 0 to 1.0. * ptr * A pointer to an array of pointers. The number of elements in * this array should equal tthe number of axes in the Frame spanned * by the Region. Each element of the array should be a pointer to * an array of "n" doubles, in which to return the "n" values for * the corresponding axis. The contents of the arrays are unchanged * if the supplied Region belongs to a class that does not * implement this method. * Returned Value: * Non-zero if the astTraceRegion method is implemented by the class * of Region supplied, and zero if not. *- */ /* Local Variables; */ AstFrame *frm; AstMapping *map; AstPointSet *bpset; AstPointSet *cpset; AstPolygon *this; double **bptr; double d; double p[ 2 ]; int i; int j0; int j; int ncur; int nv; int monotonic; /* Check inherited status, and the number of points to return, returning a non-zero value to indicate that this class supports the astRegTrace method. */ if( ! astOK || n == 0 ) return 1; /* Get a pointer to the Polygon structure. */ this = (AstPolygon *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* We first determine the required positions in the base Frame of the Region, and then transform them into the current Frame. Get the base->current Mapping, and the number of current Frame axes. */ map = astGetMapping( this_region->frameset, AST__BASE, AST__CURRENT ); /* If it's a UnitMap we do not need to do the transformation, so put the base Frame positions directly into the supplied arrays. */ if( astIsAUnitMap( map ) ) { bpset = NULL; bptr = ptr; ncur = 2; /* Otherwise, create a PointSet to hold the base Frame positions (known to be 2D since this is an polygon). */ } else { bpset = astPointSet( n, 2, " ", status ); bptr = astGetPoints( bpset ); ncur = astGetNout( map ); } /* Check the pointers can be used safely. */ if( astOK ) { /* Get the number of vertices. */ nv = astGetNpoint( this_region->points ); /* If we have a reasonable number of pointsand there are a reasonable number of vertices, we can be quicker if we know if the parameteric distances are monotonic increasing. Find out now. */ if( n > 5 && nv > 5 ) { monotonic = 1; for( i = 1; i < n; i++ ) { if( dist[ i ] < dist[ i - 1 ] ) { monotonic = 0; break; } } } else { monotonic = 0; } /* Loop round each point. */ j0 = 1; for( i = 0; i < n; i++ ) { /* Get the required round the polygon, starting from vertex zero. */ d = dist[ i ]*this->totlen; /* Loop round each vertex until we find one which is beyond the required point. If the supplied distances are monotonic increasing, we can start the checks at the same vertex that was used for the previous since we know there will never be a backward step. */ for( j = j0; j < nv; j++ ) { if( this->startsat[ j ] > d ) break; } /* If the distances are monotonic increasing, record the vertex that we have reached so far. */ if( monotonic ) j0 = j; /* Find the distance to travel beyond the previous vertex. */ d -= this->startsat[ j - 1 ]; /* Find the position, that is the required distance from the previous vertex towards the next vertex. */ astLineOffset( frm, this->edges[ j - 1 ], d, 0.0, p ); /* Store the resulting axis values. */ bptr[ 0 ][ i ] = p[ 0 ]; bptr[ 1 ][ i ] = p[ 1 ]; } } /* If required, transform the base frame positions into the current Frame, storing them in the supplied array. Then free resources. */ if( bpset ) { cpset = astPointSet( n, ncur, " ", status ); astSetPoints( cpset, ptr ); (void) astTransform( map, bpset, 1, cpset ); cpset = astAnnul( cpset ); bpset = astAnnul( bpset ); } /* Free remaining resources. */ map = astAnnul( map ); frm = astAnnul( frm ); /* Return a non-zero value to indicate that this class supports the astRegTrace method. */ return 1; } static Segment *RemoveFromChain( Segment *head, Segment *seg, int *status ){ /* * Name: * RemoveFromChain * Purpose: * Remove a Segment from the link list maintained by astDownsize. * Type: * Private function. * Synopsis: * #include "polygon.h" * Segment *RemoveFromChain( Segment *head, Segment *seg, int *status ) * Class Membership: * Polygon member function * Description: * The supplied Segment is removed form the list, and the gap is * closed up. * Parameters: * head * The Segment structure at the head of the list. * seg * The Segment to be removed from the list. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the link head (which will have changed if "seg" was the * original head). */ /* Check the global error status. */ if ( !astOK ) return head; /* If the Segment was the original head, make the next segment the new head. */ if( head == seg ) head = seg->next; /* Close up the links between the Segments on either side of the segment being removed. */ if( seg->prev ) seg->prev->next = seg->next; if( seg->next ) seg->next->prev = seg->prev; /* Nullify the links in the segment being removed. */ seg->next = NULL; seg->prev = NULL; /* Return the new head. */ return head; } static void ResetCache( AstRegion *this_region, int *status ){ /* * Name: * ResetCache * Purpose: * Clear cached information within the supplied Region. * Type: * Private function. * Synopsis: * #include "polygon.h" * void ResetCache( AstRegion *this, int *status ) * Class Membership: * Region member function (overrides the astResetCache method * inherited from the parent Region class). * Description: * This function clears cached information from the supplied Region * structure. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPolygon *this; int i; int nv; /* Get a pointer to the Polygon structure. */ this = (AstPolygon *) this_region; /* If a Polygon was supplied, indicate cached information needs to be recalculated. */ if( this ) { this->stale = 1; this->lbnd[ 0 ] = AST__BAD; /* Free any edge structures (number of vertices may be about to change so this cannot be left until the next call to "Cache()". */ if( this->edges ) { nv = astGetNpoint( this_region->points ); for( i = 0; i < nv; i++ ) { this->edges[ i ] = astFree( this->edges[ i ] ); } this->edges = astFree( this->edges ); } /* Clear the cache of the parent class. */ (*parent_resetcache)( this_region, status ); } } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Polygon member function (extends the astSetAttrib method inherited from * the Region class). * Description: * This function assigns an attribute value for a Polygon, 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 Polygon. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Returned Value: * void */ /* Local Vaiables: */ AstPolygon *this; /* Pointer to the Polygon structure */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) 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. */ /* SimpVertices. */ /* ------------- */ if ( nc = 0, ( 1 == astSscanf( setting, "simpvertices= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetSimpVertices( this, ival ); /* Pass any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetPointSet( AstPolygon *this, AstPointSet *pset, int *status ){ /* * Name: * SetPointSet * Purpose: * Store a new set of vertices in an existing Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * void SetPointSet( AstPolygon *this, AstPointSet *pset, int *status ) * Class Membership: * Polygon member function * Description: * The PointSet in the supplied Polygon is annulled, and replaced by a * clone of the supplied PointSet pointer. * Parameters: * this * Pointer to the Polygon to be changed. * pset * The PointSet containing the new vertex information. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Indicate the cached information in the polygon will need to be re-calculated when needed. */ astResetCache( this ); /* Annul the pointer to the PointSet already in the supplied Polygon. */ (void) astAnnul( ((AstRegion *) this)->points ); /* Store a clone of the supplied new PointSet pointer. */ ((AstRegion *) this)->points = astClone( pset ); } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "polygon.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Polygon method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Indicate cached information eeds re-calculating. */ astResetCache( this_region ); /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Polygon method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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 *frm; /* Current Frame */ AstMapping *map; /* Base -> current Mapping */ AstMapping *result; /* Result pointer to return */ AstPointSet *mesh; /* Mesh of current Frame positions */ AstPointSet *ps2; /* Polygon PointSet in current Frame */ AstPolygon *newpol; /* New Polygon */ AstRegion *new; /* Pointer to simplified Region */ AstRegion *this; /* Pointer to supplied Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr2; /* Pointer axis values in "ps2" */ double *mem; /* Pointer to array holding new vertex coords */ double *p; /* Pointer to next vertex coords */ double *q; /* Pointer to next vertex coords */ int iv; /* Vertex index */ int nv; /* Number of vertices in polygon */ int ok; /* Are the new polygon vertices good? */ int simpler; /* Has some simplication taken place? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the supplied Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* We attempt to simplify the Polygon by re-defining it within its current Frame. Transforming the Polygon from its base to its current Frame may result in the region no having the same edges. If required, we test this by transforming a set of bounds on the Polygon boundary. This can only be done if the current Frame is 2-dimensional. Also, there is only any point in doing it if the Mapping from base to current Frame in the Polygon is not a UnitMap. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) && astGetNout( map ) == 2 ) { /* Get a pointer to the Frame represented by the Polgon. */ frm = astGetFrame( new->frameset, AST__CURRENT ); /* Get the Region describing the positional uncertainty in this Frame. */ unc = astGetUncFrm( new, AST__CURRENT ); /* Get the positions of the vertices within this Frame. */ ps2 = astRegTransform( this, this->points, 1, NULL, NULL ); ptr2 = astGetPoints( ps2 ); /* Get the number of vertices. */ nv = astGetNpoint( ps2 ); /* Re-organise the vertex axis values into the form required by the Polygon constructor function. */ mem = astMalloc( sizeof( double)*(size_t)( 2*nv ) ); if( astOK ) { ok = 1; p = mem; q = ptr2[ 0 ]; for( iv = 0; iv < nv; iv++ ) { if( ( *(p++) = *(q++) ) == AST__BAD ) ok = 0; } q = ptr2[ 1 ]; for( iv = 0; iv < nv; iv++ ) *(p++) = *(q++); /* Create a new Polygon using these transformed vertices. */ if( ok ) { newpol = astPolygon( frm, nv, nv, mem, unc, "", status ); /* If the SimpVertices attribute is zero, we now check that the transformation has not bent the edges of the polygon significantly. If it has, we annul the new Polygon. */ if( !astGetSimpVertices( this ) ) { /* Get a mesh of points covering the Polygon in this Frame. */ mesh = astRegMesh( new ); /* See if all points within the mesh created from the original Polygon fall on the boundary of the new Polygon, to within the uncertainty of the Region. If not, annul the new Polgon. */ if( !astRegPins( newpol, mesh, NULL, NULL ) ) { newpol = astAnnul( newpol ); } /* Free the mesh. */ mesh = astAnnul( mesh ); } /* If we still have a new polygon, use the new Polygon in place of the original Region. */ if( newpol ) { (void) astAnnul( new ); new = (AstRegion *) newpol; simpler = 1; } } } /* Free other resources. */ frm = astAnnul( frm ); unc = astAnnul( unc ); ps2 = astAnnul( ps2 ); mem = astFree( mem ); } map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void SmoothPoly( AstPointSet *pset, int boxsize, double strength, int *status ) { /* * Name: * SmoothPoly * Purpose: * Smoooth a polygon assuming plane geometry. * Type: * Private function. * Synopsis: * #include "polygon.h" * void SmoothPoly( AstPointSet *pset, int boxsize, double strength, * int *status ) * Class Membership: * Polygon member function * Description: * This function smooths a polygon, without changing the number of * vertices. It assumes plane geometry, so should not be used to * smooth polygons defined within a SkyFrame or CmpFrame. * * Each vertex is replaced by a new vertex determined as follows: the * mean X and Y axis value of the vertices in a section of the polygon * centred on the vertex being replaced are found (the length of the * section is given by parameter "boxsize"). The new vertex position * is then the weighted mean of this mean (X,Y) position and the old * vertex position. The weight for the mean (X,Y) position is given * by parameter "strength", and the weight for the old vertex * position is (1.0 - strength) * Parameters: * pset * A PointSet holding the polygon vertices. * boxsize * Half width of the box filter, given as a number of vertices. * strength * The weight to use for the mean (X,Y) position when finding each * new vertex position. Should be in the range 0.0 to 1.0. A value * of zero results in no change being made to the polygon. A value * of 1.0 results in the returned polygon being fully smoothed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double **ptr; double *newx; double *newy; double *nx; double *ny; double *oldx; double *oldy; double *ox; double *oy; double *px; double *py; double *qx; double *qy; double a; double b; double sx; double sy; int half_width; int i; int nv; int top; /* Check the global error status. */ if ( !astOK ) return; /* Get the number of vertices. */ nv = astGetNpoint( pset ); /* Get pointers to arrays holding the supplied vertex positions. */ ptr = astGetPoints( pset ); oldx = ptr[ 0 ]; oldy = ptr[ 1 ]; /* Allocate arrays to hold the returned vertex positions. */ newx = astMalloc( nv*sizeof( double ) ); newy = astMalloc( nv*sizeof( double ) ); /* Check these pointers can be used safely. */ if( astOK ) { /* Get weighting factors for the fully smoothed and unsmoothed positions. */ a = strength; b = 1.0 - a; /* Ensure the box size is sufficiently small for there to be room for two boxes along the polygon. */ half_width = nv/4 - 1; if( boxsize < half_width ) half_width = boxsize; if( half_width < 1 ) half_width = 1; /* Modify the weight for the fully smoothed position to include the normalisation factor needed to account for the box width. */ a /= 2*half_width + 1; /* Find the sum of the x and y coordinates within a box centred on the first vertex. This includes vertices from the end of the polygon. */ px = oldx + 1; qx = oldx + nv; sx = (oldx)[ 0 ]; py = oldy + 1; qy = oldy + nv; sy = (oldy)[ 0 ]; for( i = 0; i < half_width; i++ ) { sx += *(px++) + *(--qx); sy += *(py++) + *(--qy); } /* Replacing vertices within the first half box will include vertices at both ends of the polygon. Set up the pointers accordingly, and then find replacements for each vertex in the first half box.*/ ox = oldx; oy = oldy; nx = newx; ny = newy; for( i = 0; i < half_width; i++ ) { /* Form the new vertex (x,y) values as the weighted mean of the mean (x,y) values in the box, and the old (x,y) values. */ *(nx++) = a*sx + b*( *(ox++) ); *(ny++) = a*sy + b*( *(oy++) ); /* Add in the next vertex X and Y axis values to the running sums, and remove the position that has now passed out of the box. */ sx += *(px++) - *(qx++); sy += *(py++) - *(qy++); } /* Adjust the pointer for the rest of the polygon, up to one half box away from the end. In this section, the smoothing box does not touch either end of the polygon. */ top = nv - half_width - 1; qx = oldx; qy = oldy; for( ; i < top; i++ ){ /* Form the new vertex (x,y) values as the weighted mean of the mean (x,y) values in the box, and the old (x,y) values. */ *(nx++) = a*sx + b*( *(ox++) ); *(ny++) = a*sy + b*( *(oy++) ); /* Add in the next vertex X and Y axis values to the running sums, and remove the position that has now passed out of the box. */ sx += *(px++) - *(qx++); sy += *(py++) - *(qy++); } /* Now do the last half box (which includes vertices from the start of the polygon). */ top = nv; px = oldx; py = oldy; for( ; i < top; i++ ){ *(nx++) = a*sx + b*( *(ox++) ); *(ny++) = a*sy + b*( *(oy++) ); sx += *(px++) - *(qx++); sy += *(py++) - *(qy++); } /* Replace the data points in the PointSet. */ ptr[ 0 ] = newx; ptr[ 1 ] = newy; oldx = astFree( oldx ); oldy = astFree( oldy ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Polygon member function (over-rides the astTestAttrib protected * method inherited from the Region class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Polygon's attributes. * Parameters: * this * Pointer to the Polygon. * 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: */ AstPolygon *this; /* Pointer to the Polygon structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* SimpVertices. */ /* ------------- */ if ( !strcmp( attrib, "simpvertices" ) ) { result = astTestSimpVertices( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } /* * Name: * TraceEdge * Purpose: * Find a point that is inside the required outline. * Type: * Private function. * Synopsis: * #include "polygon.h" * void TraceEdge( value, const array[], * const int lbnd[ 2 ], const int ubnd[ 2 ], * int iv0, int ix0, int iy0, int starpix, * int full, int *status ); * Class Membership: * Polygon member function * Description: * This function forms a polygon enclosing the region of the data * array specified by and "value". If this polygon contains * the point "(inx,iny)", then a PointSet is returned holding the * pixel coordinates of the Polygon vertices. If the polygon * does not contain "(inx,iny)", a NULL pointer is returned. * * Each vertex in the polygon corresponds to a corner of a pixel in * the data array. * Parameters: * value * The data value defining valid pixels. * array * The data array. * lbnd * The lower pixel index bounds of the array. * ubnd * The upper pixel index bounds of the array. * iv0 * The vector index of a pixel inside the region such that the * pixel to the right is NOT inside the region. This defines the * start of the polygon. * ix0 * The X pixel index of the pixel specified by "iv0". * inx * The X pixel index of a point which must be inside the polygon * for the polygon to be acceptable. * iny * The Y pixel index of a point which must be inside the polygon * for the polygon to be acceptable. * starpix * If non-zero, the usual Starlink definition of pixel coordinate * is used (integral values at pixel corners). Otherwise, the * system used by other AST functions such as astResample is used * (integral values at pixel centres). * full * If non-zero, the full polygon is stored. If zero, vertices in the * middle of straight sections of the Polygon are omitted. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a PointSet holding the vertices of the polygon, or * NULL if the polygon did not contain "(inx,iny)". * Notes: * - must be one of LT, LE, EQ, GE, GT, NE. */ /* Define a macro to implement the function for a specific data type and operation. */ #define MAKE_TRACEEDGE(X,Xtype,Oper,OperI) \ static AstPointSet *TraceEdge##Oper##X( Xtype value, const Xtype array[], \ const int lbnd[ 2 ], const int ubnd[ 2 ], \ int iv0, int ix0, int iy0, \ int starpix, int full, \ int *status ){ \ \ /* Local Variables: */ \ AstPointSet *result; /* Pointer to text describing oper */ \ const Xtype *pa; /* Pointer to current valid pixel value */ \ const Xtype *pb; /* Pointer to neigbouring valid pixel value */ \ const Xtype *pc; /* Pointer to neigbouring valid pixel value */ \ double *ptr[ 2 ]; /* PointSet data pointers */ \ double *xvert; /* Pointer to array holding vertex X axis values */ \ double *yvert; /* Pointer to array holding vertex Y axis values */ \ double dx; /* Pertubation in X (pixels) to avoid the pixel edge */ \ double dy; /* Pertubation in Y (pixels) to avoid the pixel edge */ \ double xx; /* Pixel X coord at corner */ \ double yy; /* Pixel Y coord at corner */ \ int at; /* The pixel corner to draw to */ \ int done; /* Have we arrived back at the start of the polygon? */ \ int ii; /* Index of new vertex */ \ int ix; /* X pixel index of current valid pixel */ \ int iy; /* Y pixel index of current valid pixel */ \ int nright; /* Overall number of right hand turns along polygon */ \ int nvert; /* Number of vertices */ \ int nx; /* Pixels per row */ \ \ /* Initialise */ \ result = NULL; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ \ /* Initialise pointers to arrays holding the X and Y pixel coordinates at \ the vertices of the polygon. */ \ xvert = NULL; \ yvert = NULL; \ nvert = 0; \ \ /* Find number of pixels in one row of the array. */ \ nx = ( ubnd[ 0 ] - lbnd[ 0 ] + 1 ); \ \ /* The four corners of a pixel are numbered as follows: 0=bottom left, \ 1=top left, 2=top right, 3=bottom right. The following algorithm moves \ along pixel edges, from corner to corner, using the above numbering \ scheme to identify the corners. We start the polygon by moving from the \ bottom right to the top right corner of pixel "(ix0,iy0)". */ \ ix = ix0; \ iy = iy0; \ at = 2; \ \ /* Store a pointer to the first good pixel value. */ \ pa = array + ( ix - lbnd[ 0 ] ) + nx*( iy - lbnd[ 1 ] ) ; \ \ /* We count the number of times the polygon turns to the right compared \ to the left. Initialise it to zero. */ \ nright = 0; \ \ /* Loop round tracing out the polygon until we arrive back at the \ beginning. The Polygon class requires that the inside of the polygon \ is to the left as we move round the polygon in an anti-clockwise \ direction. So at each corner, we attempt to move to the next \ anti-clockwise good pixel corner. */ \ done = 0; \ while( !done ) { \ \ /* If we have arrived at the bottom left corner of the good pixel, we must \ have come from the top left corner since all movements around a pixel \ must be anti-clockwise. */ \ if( at == 0 ) { \ \ /* Note the pixel coordinates at the bottom left corner of the current \ pixel. */ \ if( starpix ) { \ xx = ix - 1.0; \ yy = iy - 1.0; \ } else { \ xx = ix - 0.5; \ yy = iy - 0.5; \ } \ \ /* Get a pointer to lower left pixel value */ \ pb = pa - nx - 1; \ \ /* Get a pointer to lower mid pixel value. */ \ pc = pb + 1; \ \ /* If the lower left pixel is within the array and meets the validity \ requirements, move to the left along its top edge. */ \ if( iy > lbnd[ 1 ] && ix > lbnd[ 0 ] && ISVALID(*pb,OperI,value) ) { \ nright++; \ pa = pb; \ at = 1; \ ix--; \ iy--; \ dx = DELTA; \ dy = -DELTA; \ \ /* Otherwise, if lower mid pixel is good, move down its left edge. */ \ } else if( iy > lbnd[ 1 ] && ISVALID(*pc,OperI,value) ) { \ pa = pc; \ at = 0; \ iy--; \ dx = DELTA; \ dy = 0.0; \ \ /* Otherwise, move to the right along the bottom edge of the current pixel. */ \ } else { \ nright--; \ at = 3; \ dx = DELTA; \ dy = DELTA; \ } \ \ /* If the polygon bends at this point, or if we will be smoothing the \ polygon, append the pixel coordinates at this pixel corner to the \ polygon. */ \ if( full || pa != pc ) ADD( xx, yy ); \ \ /* If we have arrived at the top left corner of the good pixel, we must \ have come from the top right corner. */ \ } else if( at == 1 ) { \ \ /* Note the pixel coordinates at the top left corner of the current \ pixel. */ \ if( starpix ) { \ xx = ix - 1.0; \ yy = iy; \ } else { \ xx = ix - 0.5; \ yy = iy + 0.5; \ } \ \ /* Get a pointer to upper left pixel value */ \ pb = pa + nx - 1; \ \ /* Get a pointer to mid left pixel value. */ \ pc = pa - 1; \ \ /* If upper left pixel is good, move up its left edge. */ \ if( iy < ubnd[ 1 ] && ix > lbnd[ 0 ] && ISVALID(*pb,OperI,value) ) { \ nright++; \ pa = pb; \ at = 2; \ ix--; \ iy++; \ dx = -DELTA; \ dy = -DELTA; \ \ /* Otherwise, if left mid pixel is good, move left along its top edge. */ \ } else if( ix > lbnd[ 0 ] && ISVALID(*pc,OperI,value) ) { \ pa = pc; \ at = 1; \ ix--; \ dx = 0.0; \ dy = -DELTA; \ \ /* Otherwise, move down the left edge of the current pixel. */ \ } else { \ nright--; \ at = 0; \ dx = DELTA; \ dy = -DELTA; \ } \ \ /* If the polygon bends at this point, or if we will be smoothing the \ polygon, append the pixel coordinates at this pixel corner to the \ polygon. */ \ if( full || pa != pc ) ADD( xx, yy ); \ \ /* If we have arrived at the top right corner of the good pixel, we must \ have come from the bottom right corner. */ \ } else if( at == 2 ) { \ \ /* Note the pixel coordinates at the top right corner of the current \ pixel. */ \ if( starpix ) { \ xx = ix; \ yy = iy; \ } else { \ xx = ix + 0.5; \ yy = iy + 0.5; \ } \ \ /* Pointer to upper right pixel value */ \ pb = pa + nx + 1; \ \ /* Pointer to top mid pixel value. */ \ pc = pa + nx; \ \ /* If upper right pixel is good, move right along its bottom edge. */ \ if( iy < ubnd[ 1 ] && ix < ubnd[ 0 ] && ISVALID(*pb,OperI,value) ){ \ nright++; \ pa = pb; \ at = 3; \ ix++; \ iy++; \ dx = -DELTA; \ dy = DELTA; \ \ /* Otherwise, if upper mid pixel is good, move up its right edge. */ \ } else if( iy < ubnd[ 1 ] && ISVALID(*pc,OperI,value) ) { \ pa = pc; \ at = 2; \ iy++; \ dx = -DELTA; \ dy = 0.0; \ \ /* Otherwise, move left along the top edge of the current pixel. */ \ } else { \ nright--; \ at = 1; \ dx = -DELTA; \ dy = -DELTA; \ } \ \ /* If the polygon bends at this point, or if we will be smoothing the \ polygon, append the pixel coordinates at this pixel corner to the \ polygon. */ \ if( full || pa != pc ) ADD( xx, yy ); \ \ /* Arrived at bottom right corner of good pixel from lower left. */ \ } else { \ \ /* Note the pixel coordinates at the bottom right corner of the current \ pixel. */ \ if( starpix ) { \ xx = ix; \ yy = iy - 1.0; \ } else { \ xx = ix + 0.5; \ yy = iy - 0.5; \ } \ \ /* Pointer to lower right pixel value */ \ pb = pa - ( nx - 1 ); \ \ /* Pointer to mid right pixel value. */ \ pc = pa + 1; \ \ /* If lower right pixel is good, move down its left edge. */ \ if( iy > lbnd[ 1 ] && ix < ubnd[ 0 ] && ISVALID(*pb,OperI,value) ) { \ nright++; \ pa = pb; \ at = 0; \ ix++; \ iy--; \ dx = DELTA; \ dy = DELTA; \ \ /* Otherwise, if right mid pixel is good, move right along its lower edge. */ \ } else if( ix < ubnd[ 0 ] && ISVALID(*pc,OperI,value) ) { \ pa = pc; \ at = 3; \ ix++; \ dx = 0.0; \ dy = DELTA; \ \ /* Otherwise, move up the right edge of the current pixel. */ \ } else { \ nright--; \ at = 2; \ dx = -DELTA; \ dy = DELTA; \ } \ \ /* If the polygon bends at this point, or if we will be smoothing the \ polygon, append the pixel coordinates at this pixel corner to the \ polygon. */ \ if( full || pa != pc ) ADD( xx, yy ); \ } \ \ /* If we have arrived back at the start, break out of the loop. */ \ if( ix == ix0 && iy == iy0 && at == 2 ) done = 1; \ } \ \ /* If we have circled round to the right, the polygon will not enclosed \ the specified position, so free resources and return a NULL pointer. */ \ if( nright > 0 ) { \ xvert = astFree( xvert ); \ yvert = astFree( yvert ); \ \ /* If we have circled round to the left, the polygon will enclose \ the specified position, so create and return a PointSet. */ \ } else { \ result = astPointSet( nvert, 2, " ", status ); \ ptr[ 0 ] = xvert; \ ptr[ 1 ] = yvert; \ astSetPoints( result, ptr ); \ } \ \ /* Annul the returned PointSet if anythign went wrong. */ \ if( !astOK && result ) result = astAnnul( result ); \ \ /* Return the PointSet pointer. */ \ return result; \ } /* Define a macro to add a vertex position to dynamically allocated arrays of X and Y positions. We offset the supplied position by a small fraction of a pixel towards the centre of hte polygon to avoid placing vertices exactly on the edge, which may cause problems later for pixels that are on the edge of an area of bad pixel. */ #define ADD(X,Y) {\ ii = nvert++; \ xvert = (double *) astGrow( xvert, nvert, sizeof( double ) ); \ yvert = (double *) astGrow( yvert, nvert, sizeof( double ) ); \ if( astOK ) { \ xvert[ ii ] = (X+dx); \ yvert[ ii ] = (Y+dy); \ } \ } /* Define a macro that uses the above macro to to create implementations of TraceEdge for all operations. */ #define MAKEALL_TRACEEDGE(X,Xtype) \ MAKE_TRACEEDGE(X,Xtype,LT,AST__LT) \ MAKE_TRACEEDGE(X,Xtype,LE,AST__LE) \ MAKE_TRACEEDGE(X,Xtype,EQ,AST__EQ) \ MAKE_TRACEEDGE(X,Xtype,NE,AST__NE) \ MAKE_TRACEEDGE(X,Xtype,GE,AST__GE) \ MAKE_TRACEEDGE(X,Xtype,GT,AST__GT) /* Expand the above macro to generate a function for each required data type and operation. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKEALL_TRACEEDGE(LD,long double) #endif MAKEALL_TRACEEDGE(D,double) MAKEALL_TRACEEDGE(L,long int) MAKEALL_TRACEEDGE(UL,unsigned long int) MAKEALL_TRACEEDGE(I,int) MAKEALL_TRACEEDGE(UI,unsigned int) MAKEALL_TRACEEDGE(S,short int) MAKEALL_TRACEEDGE(US,unsigned short int) MAKEALL_TRACEEDGE(B,signed char) MAKEALL_TRACEEDGE(UB,unsigned char) MAKEALL_TRACEEDGE(F,float) /* Undefine the macros. */ #undef MAKE_TRACEEDGE #undef MAKEALL_TRACEEDGE static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Polygon to transform a set of points. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Polygon member function (over-rides the astTransform protected * method inherited from the Region class). * Description: * This function takes a Polygon and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the Polygon. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the Polygon. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstFrame *frm; /* Pointer to base Frame in FrameSet */ AstLineDef *a; /* Line from inside point to test point */ AstLineDef *b; /* Polygon edge */ AstPointSet *in_base; /* PointSet holding base Frame input positions*/ AstPointSet *result; /* Pointer to output PointSet */ AstPolygon *this; /* Pointer to Polygon */ double **ptr_in; /* Pointer to input base Frame coordinate data */ double **ptr_out; /* Pointer to output current Frame coordinate data */ double *px; /* Pointer to array of first axis values */ double *py; /* Pointer to array of second axis values */ double p[ 2 ]; /* Current test position */ int closed; /* Is the boundary part of the Region? */ int i; /* Edge index */ int icoord; /* Coordinate index */ int in_region; /* Is the point inside the Region? */ int ncoord_out; /* No. of current Frame axes */ int ncross; /* Number of crossings */ int neg; /* Has the Region been negated? */ int npoint; /* No. of input points */ int nv; /* No. of vertices */ int point; /* Loop counter for input points */ int pos; /* Is test position in, on, or outside boundary? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) this_mapping; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* Get the number of points to be transformed. */ npoint = astGetNpoint( result ); /* Get a pointer to the output axis values. */ ptr_out = astGetPoints( result ); /* Find the number of axes in the current Frame. This need not be 2 (the number of axes in the *base* Frame must be 2 however). */ ncoord_out = astGetNcoord( result ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). This call also returns a pointer to the base Frame of the encapsulated FrameSet. Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ in_base = astRegTransform( this, in, 0, NULL, &frm ); ptr_in = astGetPoints( in_base ); /* Get the number of vertices in the polygon. */ nv = astGetNpoint( ((AstRegion *) this)->points ); /* See if the boundary is part of the Region. */ closed = astGetClosed( this ); /* See if the Region has been negated. */ neg = astGetNegated( this ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { px = ptr_in[ 0 ]; py = ptr_in[ 1 ]; /* Loop round each supplied point in the base Frame of the polygon. */ for ( point = 0; point < npoint; point++, px++, py++ ) { /* If the input point is bad, indicate that bad output values should be returned. */ if( *px == AST__BAD || *py == AST__BAD ) { in_region = 0; /* Otherwise, we first determine if the point is inside, outside, or on, the Polygon boundary. Initialially it is unknown. */ } else { /* Ensure cached information is available.*/ Cache( this, status ); /* Create a definition of the line from a point which is inside the polygon to the supplied point. This is a structure which includes cached intermediate information which can be used to speed up subsequent calculations. */ p[ 0 ] = *px; p[ 1 ] = *py; a = astLineDef( frm, this->in, p ); /* We now determine the number of times this line crosses the polygon boundary. Initialise the number of crossings to zero. */ ncross = 0; pos = UNKNOWN; /* Loop rouind all edges of the polygon. */ for( i = 0; i < nv; i++ ) { b = this->edges[ i ]; /* If this point is on the current edge, then we need do no more checks since we know it is either inside or outside the polygon (depending on whether the polygon is closed or not). */ if( astLineContains( frm, b, 0, p ) ) { pos = ON; break; /* Otherwise, see if the two lines cross within their extent. If so, increment the number of crossings. */ } else if( astLineCrossing( frm, b, a, NULL ) ) { ncross++; } } /* Free resources */ a = astFree( a ); /* If the position is not on the boundary, it is inside the boundary if the number of crossings is even, and outside otherwise. */ if( pos == UNKNOWN ) pos = ( ncross % 2 == 0 )? IN : OUT; /* Whether the point is in the Region depends on whether the point is inside the polygon boundary, whether the Polygon has been negated, and whether the polygon is closed. */ if( neg ) { if( pos == IN ) { in_region = 0; } else if( pos == OUT ) { in_region = 1; } else if( closed ) { in_region = 1; } else { in_region = 0; } } else { if( pos == IN ) { in_region = 1; } else if( pos == OUT ) { in_region = 0; } else if( closed ) { in_region = 1; } else { in_region = 0; } } } /* If the point is not inside the Region, store bad output values. */ if( !in_region ) { for ( icoord = 0; icoord < ncoord_out; icoord++ ) { ptr_out[ icoord ][ point ] = AST__BAD; } } } } /* Free resources */ in_base = astAnnul( in_base ); frm = astAnnul( frm ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * SimpVertices * Purpose: * Simplify a Polygon by transforming its vertices? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the behaviour of the c astSimplify f AST_SIMPLIFY * method when applied to a Polygon. The simplified Polygon is created * by transforming the vertices from the Frame in which the Polygon * was originally defined into the Frame currently represented by the * Polygon. If SimpVertices is non-zero (the default) then this * simplified Polygon is returned without further checks. If SimpVertices * is zero, a check is made that the edges of the new Polygon do not * depart significantly from the edges of the original Polygon (as * determined by the uncertainty associated with the Polygon). This * could occur, for instance, if the Mapping frrm the original to the * current Frame is highly non-linear. If this check fails, the * original unsimplified Polygon is returned without change. * Applicability: * Polygon * All Polygons have this attribute. *att-- */ astMAKE_CLEAR(Polygon,SimpVertices,simp_vertices,-INT_MAX) astMAKE_GET(Polygon,SimpVertices,int,0,( ( this->simp_vertices != -INT_MAX ) ? this->simp_vertices : 1 )) astMAKE_SET(Polygon,SimpVertices,int,simp_vertices,( value != 0 )) astMAKE_TEST(Polygon,SimpVertices,( this->simp_vertices != -INT_MAX )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Polygon objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Polygon 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: */ AstPolygon *out; /* Pointer to output Polygon */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the output Polygon. */ out = (AstPolygon *) objout; /* For safety, first clear any references to the input memory from the output Polygon. */ out->edges = NULL; out->startsat = NULL; /* Indicate cached information needs nre-calculating. */ astResetCache( (AstPolygon *) out ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Polygon objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Polygon 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: */ AstPointSet *ps; /* Pointer to PointSet inside Region */ AstPolygon *this; /* Pointer to Polygon */ int i; /* Index of vertex */ int istat; /* Original AST error status */ int nv; /* Number of vertices */ int rep; /* Original error reporting state */ /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) obj; /* Annul all resources. */ ps = ((AstRegion *) this)->points; if( this->edges && ps ) { /* Ensure we get a value for "nv" even if an error has occurred. */ istat = astStatus; astClearStatus; rep = astReporting( 0 ); nv = astGetNpoint( ps ); astSetStatus( istat ); astReporting( rep ); /* Free the structures holding the edge information. */ for( i = 0; i < nv; i++ ) { this->edges[ i ] = astFree( this->edges[ i ] ); } this->edges = astFree( this->edges ); this->startsat = astFree( this->startsat ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Polygon 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 Polygon class to an output Channel. * Parameters: * this * Pointer to the Polygon 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 Variables: */ AstPolygon *this; /* Pointer to the Polygon structure */ int ival; /* Integer attribute value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Polygon structure. */ this = (AstPolygon *) this_object; /* Write out values representing the instance variables for the Polygon 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. */ /* SimpVertices. */ /* ------------ */ /* Write out the forward-inverse simplification flag. */ set = TestSimpVertices( this, status ); ival = set ? GetSimpVertices( this, status ) : astGetSimpVertices( this ); astWriteInt( channel, "SimpVT", set, 0, ival, "Simplify by transforming vertices?" ); /* A flag indicating the convention used for determining the interior of the polygon. A zero value indicates that the old AST system is in use (inside to the left when moving anti-clockwise round the vertices as viewed from the outside of the celestial sphere). A non-zero value indicates the STC system is in use (inside to the left when moving anti-clockwise round the vertices as viewed from the inside of the celestial sphere). AST currently uses the STC system. */ astWriteInt( channel, "Order", 1, 0, 1, "Polygon uses STC vertex order convention" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPolygon and astCheckPolygon functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Polygon,Region) astMAKE_CHECK(Polygon) AstPolygon *astPolygon_( void *frame_void, int npnt, int dim, const double *points, AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astPolygon f AST_POLYGON * Purpose: * Create a Polygon. * Type: * Public function. * Synopsis: c #include "polygon.h" c AstPolygon *astPolygon( AstFrame *frame, int npnt, int dim, c const double *points, AstRegion *unc, c const char *options, ... ) f RESULT = AST_POLYGON( FRAME, NPNT, DIM, POINTS, UNC, OPTIONS, STATUS ) * Class Membership: * Polygon constructor. * Description: * This function creates a new Polygon object and optionally initialises * its attributes. * * The Polygon class implements a polygonal area, defined by a * collection of vertices, within a 2-dimensional Frame. The vertices * are connected together by geodesic curves within the encapsulated Frame. * For instance, if the encapsulated Frame is a simple Frame then the * geodesics will be straight lines, but if the Frame is a SkyFrame then * the geodesics will be great circles. Note, the vertices must be * supplied in an order such that the inside of the polygon is to the * left of the boundary as the vertices are traversed. Supplying them * in the reverse order will effectively negate the polygon. * * Within a SkyFrame, neighbouring vertices are always joined using the * shortest path. Thus if an edge of 180 degrees or more in length is * required, it should be split into section each of which is less * than 180 degrees. The closed path joining all the vertices in order * will divide the celestial sphere into two disjoint regions. The * inside of the polygon is the region which is circled in an * anti-clockwise manner (when viewed from the inside of the celestial * sphere) when moving through the list of vertices in the order in * which they were supplied when the Polygon was created (i.e. the * inside is to the left of the boundary when moving through the * vertices in the order supplied). * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. It must * have exactly 2 axes. A deep copy is taken of the supplied Frame. * This means that any subsequent changes made to the Frame using the * supplied pointer will have no effect the Region. c npnt f NPNT = INTEGER (Given) * The number of points in the Region. c dim f DIM = INTEGER (Given) c The number of elements along the second dimension of the "points" f The number of elements along the first dimension of the POINTS * array (which contains the point coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value c given should not be less than "npnt". f given should not be less than NPNT. c points f POINTS( DIM, 2 ) = DOUBLE PRECISION (Given) c The address of the first element of a 2-dimensional array of c shape "[2][dim]" giving the physical coordinates of the vertices. c These should be stored such that the value of coordinate c number "coord" for point number "pnt" is found in element c "in[coord][pnt]". f A 2-dimensional array giving the physical coordinates of the f vertices. These should be stored such that the value of coordinate f number COORD for point number PNT is found in element IN(PNT,COORD). c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with the boundary of the Polygon being created. * The uncertainty in any point on the boundary of the Polygon is found by * shifting the supplied "uncertainty" Region so that it is centred at * the boundary point being considered. The area covered by the * shifted uncertainty Region then represents the uncertainty in the * boundary position. The uncertainty is assumed to be the same for * all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Polygon. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the Polygon being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 Polygon. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Polygon. The syntax used is identical to that for the f AST_SET routine. 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 astPolygon() f AST_POLYGON = INTEGER * A pointer to the new Polygon. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstPolygon *new; /* Pointer to new Polygon */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the Polygon, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPolygon( NULL, sizeof( AstPolygon ), !class_init, &class_vtab, "Polygon", frame, npnt, dim, points, unc ); /* 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 Polygon'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 Polygon. */ return new; } AstPolygon *astPolygonId_( void *frame_void, int npnt, int dim, const double *points, void *unc_void, const char *options, ... ) { /* * Name: * astPolygonId_ * Purpose: * Create a Polygon. * Type: * Private function. * Synopsis: * #include "polygon.h" * AstPolygon *astPolygonId_( void *frame_void, int npnt, * int dim, const double *points, void *unc_void, * const char *options, ... ) * Class Membership: * Polygon constructor. * Description: * This function implements the external (public) interface to the * astPolygon constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astPolygon_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astPolygon_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astPolygon_. * Returned Value: * The ID value associated with the new Polygon. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstPolygon *new; /* Pointer to new Polygon */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the Polygon, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPolygon( NULL, sizeof( AstPolygon ), !class_init, &class_vtab, "Polygon", frame, npnt, dim, points, unc ); /* 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 Polygon'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 Polygon. */ return astMakeId( new ); } AstPolygon *astInitPolygon_( void *mem, size_t size, int init, AstPolygonVtab *vtab, const char *name, AstFrame *frame, int npnt, int dim, const double *points, AstRegion *unc, int *status ) { /* *+ * Name: * astInitPolygon * Purpose: * Initialise a Polygon. * Type: * Protected function. * Synopsis: * #include "polygon.h" * AstPolygon *astInitPolygon( void *mem, size_t size, int init, AstPolygonVtab *vtab, * const char *name, AstFrame *frame, int npnt, * int dim, const double *points, AstRegion *unc ) * Class Membership: * Polygon initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Polygon object. It allocates memory (if necessary) to accommodate * the Polygon plus any additional data associated with the derived class. * It then initialises a Polygon 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 Polygon at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Polygon is to be initialised. * This must be of sufficient size to accommodate the Polygon data * (sizeof(Polygon)) 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 Polygon (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 Polygon * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Polygon'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 Polygon. * 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 * A pointer to the Frame in which the region is defined. * npnt * The number of points in the Region. * dim * The number of elements along the second dimension of the "points" * array (which contains the point coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value * given should not be less than "npnt". * points * The address of the first element of a 2-dimensional array of * shape "[2][dim]" giving the physical coordinates of the * points. These should be stored such that the value of coordinate * number "coord" for point number "pnt" is found in element * "in[coord][pnt]". * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points in the new Polygon being * initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal * to 1.0E-6 of the dimensions of the new Polygon's bounding box are * used. If an uncertainty Region is supplied, it must be either a Box, * a Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new Polygon. * 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: */ AstPolygon *new; /* Pointer to new Polygon */ AstPointSet *pset; /* Pointer to PointSet holding points */ const double *q; /* Pointer to next supplied axis value */ double **ptr; /* Pointer to data in pset */ double *p; /* Pointer to next PointSet axis value */ int i; /* Axis index */ int j; /* Point index */ int nin; /* No. of axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPolygonVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the number of axis values per position is correct. */ nin = astGetNaxes( frame ); if( nin != 2 ) { astError( AST__BADIN, "astInitPolygon(%s): The supplied %s has %d " "axes - polygons must have exactly 2 axes.", status, name, astGetClass( frame ), nin ); /* If so create a PointSet and store the supplied points in it. Check none are bad. */ } else { pset = astPointSet( npnt, 2, "", status ); ptr = astGetPoints( pset ); for( i = 0; i < 2 && astOK; i++ ) { p = ptr[ i ]; q = points + i*dim; for( j = 0; j < npnt; j++ ) { if( (*(p++) = *(q++)) == AST__BAD ) { astError( AST__BADIN, "astInitPolygon(%s): One or more " "bad axis values supplied for the vertex " "number %d.", status, name, j + 1 ); break; } } } /* Initialise a Region structure (the parent class) as the first component within the Polygon structure, allocating memory if necessary. */ new = (AstPolygon *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, pset, unc ); if ( astOK ) { /* Initialise the Polygon data. */ /* ------------------------------ */ new->lbnd[ 0 ] = AST__BAD; new->ubnd[ 0 ] = AST__BAD; new->lbnd[ 1 ] = AST__BAD; new->ubnd[ 1 ] = AST__BAD; new->simp_vertices = -INT_MAX; new->edges = NULL; new->startsat = NULL; new->totlen = 0.0; new->acw = 1; new->stale = 1; /* Ensure the vertices are stored such that the unnegated Polygon represents the inside of the polygon. */ EnsureInside( new, status ); /* If an error occurred, clean up by deleting the new Polygon. */ if ( !astOK ) new = astDelete( new ); } /* Free resources. */ pset = astAnnul( pset ); } /* Return a pointer to the new Polygon. */ return new; } AstPolygon *astLoadPolygon_( void *mem, size_t size, AstPolygonVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPolygon * Purpose: * Load a Polygon. * Type: * Protected function. * Synopsis: * #include "polygon.h" * AstPolygon *astLoadPolygon( void *mem, size_t size, AstPolygonVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Polygon loader. * Description: * This function is provided to load a new Polygon 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 * Polygon structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Polygon at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Polygon is to be * loaded. This must be of sufficient size to accommodate the * Polygon data (sizeof(Polygon)) 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 Polygon (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 Polygon 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(AstPolygon) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Polygon. If this is NULL, a pointer * to the (static) virtual function table for the Polygon 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 "Polygon" is used instead. * Returned Value: * A pointer to the new Polygon. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPolygon *new; /* Pointer to the new Polygon */ int order; /* Is the new (STC) order convention used? */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Polygon. In this case the Polygon belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPolygon ); vtab = &class_vtab; name = "Polygon"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPolygonVtab( 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 Polygon. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Polygon" ); /* 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. */ new->simp_vertices = astReadInt( channel, "simpvt", -INT_MAX ); if ( TestSimpVertices( new, status ) ) SetSimpVertices( new, new->simp_vertices, status ); /* A flag indicating what order the vertices are stored in. See the Dump function. */ order = astReadInt( channel, "order", 0 ); /* Initialise other class properties. */ new->lbnd[ 0 ] = AST__BAD; new->ubnd[ 0 ] = AST__BAD; new->lbnd[ 1 ] = AST__BAD; new->ubnd[ 1 ] = AST__BAD; new->edges = NULL; new->startsat = NULL; new->totlen = 0.0; new->acw = 1; new->stale = 1; /* If the order in which the vertices were written used the old AST convention, negate the Polygon so that it is consistent with the current conevtion (based on STC). */ if( ! order ) astNegate( new ); /* Ensure the vertices are stored such that the unnegated Polygon represents the inside of the polygon. */ EnsureInside( new, status ); /* If an error occurred, clean up by deleting the new Polygon. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Polygon pointer. */ return new; } /* 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. */ AstPolygon *astDownsize_( AstPolygon *this, double maxerr, int maxvert, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Polygon,Downsize))( this, maxerr, maxvert, status ); } ast-8.3.0/fnormmap.c0000664000175000017500000000606313004147321011217 00000000000000/* *+ * Name: * fnormmap.c * Purpose: * Define a FORTRAN 77 interface to the AST NormMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the NormMap class. * Routines Defined: * AST_ISANORMMAP * AST_NORMMAP * 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 * . * Authors: * DSB: David S.Berry (Starlink) * History: * 11-JUL-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "normmap.h" /* C interface to the NormMap class */ F77_LOGICAL_FUNCTION(ast_isanormmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astWatchSTATUS( astAt( "AST_ISANORMMAP", NULL, 0 ); RESULT = astIsANormMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_normmap)( INTEGER(FRAME), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_NORMMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astNormMap( astI2P( *FRAME ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/pointlist.c0000664000175000017500000036275213004147321011437 00000000000000/* *class++ * Name: * PointList * Purpose: * A collection of points in a Frame. * Constructor Function: c astPointList f AST_POINTLIST * Description: * The PointList class implements a Region which represents a collection * of points in a Frame. * Inheritance: * The PointList class inherits from the Region class. * Attributes: * In addition to those attributes common to all Regions, every * PointList also has the following attributes: * * - ListSize: The number of positions stored in the PointList * Functions: c The PointList class does not define any new functions beyond those f The PointList class does not define any new routines beyond those * which are applicable to all Regions. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-MAR-2004 (DSB): * Original version. * 20-JAN-2009 (DSB): * Over-ride astRegBasePick. * 21-JAN-2009 (DSB): * - Add methods astGetEnclosure, astSetEnclosure and astPoints, and * attribute ListSize. * - Override astGetObjSize and astEqual. * 26-JAN-2009 (DSB): * Change protected constructor to accept a PointSet rather than an * array of doubles. * 6-FEB-2009 (DSB): * Over-ride astMapMerge. * 9-FEB-2009 (DSB): * Move methods astGetEnclosure and astSetEnclosure to Region class. * 8-JUL-2009 (DSB): * In Transform, use "ptr2", not "ptr", if we are creating a mask. *class-- * Implementation Deficiencies: * - Use of simple arrays to hold lists of points is probably not * efficient for large numbers of points. For instance, use of k-tree * structures instead of arrays could result in a much more efficient * implementation of the Transform function. Maybe the PointSet class * should be extended to provide a k-tree representation as well as a * simple array. */ /* 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 PointList /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "pointlist.h" /* Interface definition for this class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mapping */ #include "frame.h" /* Coordinate systems */ #include "cmpframe.h" /* Compound Frames */ #include "cmpmap.h" /* Compound Mappings */ #include "prism.h" /* Extruded Regions */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstMapping *(* parent_simplify)( AstMapping *, int * ); static AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(PointList) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(PointList,Class_Init) #define class_vtab astGLOBAL(PointList,Class_Vtab) #define getattrib_buff astGLOBAL(PointList,GetAttrib_Buff) #include #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPointListVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstPointList *astPointListId_( void *, int, int, int, const double *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ static int MaskLD( AstRegion *, AstMapping *, int, int, const int[], const int ubnd[], long double [], long double, int * ); #endif static int MaskB( AstRegion *, AstMapping *, int, int, const int[], const int[], signed char[], signed char, int * ); static int MaskD( AstRegion *, AstMapping *, int, int, const int[], const int[], double[], double, int * ); static int MaskF( AstRegion *, AstMapping *, int, int, const int[], const int[], float[], float, int * ); static int MaskI( AstRegion *, AstMapping *, int, int, const int[], const int[], int[], int, int * ); static int MaskL( AstRegion *, AstMapping *, int, int, const int[], const int[], long int[], long int, int * ); static int MaskS( AstRegion *, AstMapping *, int, int, const int[], const int[], short int[], short int, int * ); static int MaskUB( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned char[], unsigned char, int * ); static int MaskUI( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned int[], unsigned int, int * ); static int MaskUL( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned long int[], unsigned long int, int * ); static int MaskUS( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned short int[], unsigned short int, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *RegBasePick( AstRegion *, int, const int *, int * ); static int GetClosed( AstRegion *, int * ); static int GetListSize( AstPointList *, int * ); static int GetObjSize( AstObject *, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void PointListPoints( AstPointList *, AstPointSet **, int *); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void RegBaseBox( AstRegion *, double *, double *, int * ); static AstRegion *MergePointList( AstPointList *, AstRegion *, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PointList member function (over-rides the astClearAttrib * protected method inherited from the Object class). * Description: * This function clears the value of a specified attribute for a * PointList, so that the default value will subsequently be used. * Parameters: * this * Pointer to the PointList. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointList *this; /* Pointer to the PointList structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Test if the name matches any of the read-only attributes of this class. If it does, then report an error. */ if ( !strcmp( attrib, "listsize" ) ) { 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); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PointList member function (over-rides the protected astGetAttrib * method inherited from the Region class). * Description: * This function returns a pointer to the value of a specified * attribute for a PointList, formatted as a character string. * Parameters: * this * Pointer to the PointList. * 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 PointList, 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 PointList. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPointList *this; /* Pointer to the PointList structure */ const char *result; /* Pointer value to return */ int ival; /* Integer attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) 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. */ /* ListSize. */ /* -------- */ if ( !strcmp( attrib, "listsize" ) ) { ival = astGetListSize( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetClosed( AstRegion *this, int *status ) { /* * Name: * GetClosed * Purpose: * Get the value of the CLosed attribute for a PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * int GetClosed( AstRegion *this, int *status ) * Class Membership: * PointList member function (over-rides the astGetClosed method * inherited from the Region class). * Description: * This function returns the value of the Closed attribute for a * PointList. Since points have zero volume they consist entirely of * boundary. Therefore the Region is always considered to be closed * unless it has been negated, in which case it is always assumed to * be open. * Parameters: * this * Pointer to the PointList. * status * Pointer to the inherited status variable. * Returned Value: * The value to use for the Closed attribute. * 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; /* The value to be used for the Closed attribute is always the opposite of the Negated attribute. */ return ( astGetNegated( this ) == 0 ); } static int GetListSize( AstPointList *this, int *status ) { /* *+ * Name: * astGetListSize * Purpose: * Determine how many points there are in a PointList. * Type: * Protected virtual function. * Synopsis: * #include "pointlist.h" * int astGetListSize( AstPointList *this ) * Class Membership: * PointList method. * Description: * This function returns the number of points stored in a Point|List. * Parameters: * this * Pointer to the PointList. * Returned Value: * The number of points in the PointList. * 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 points by querying the PointSet that holds the points. */ return astGetNpoint( ((AstRegion *) this)->points ); } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "pointlist.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * PointList member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied PointList, * in bytes. * Parameters: * this * Pointer to the PointList. * 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: */ AstPointList *this; /* Pointer to PointList structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the PointList structure. */ this = (AstPointList *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->lbnd ); result += astGetObjSize( this->ubnd ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitPointListVtab_( AstPointListVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPointListVtab * Purpose: * Initialise a virtual function table for a PointList. * Type: * Protected function. * Synopsis: * #include "pointlist.h" * void astInitPointListVtab( AstPointListVtab *vtab, const char *name ) * Class Membership: * PointList vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the PointList class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPointList) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->GetListSize = GetListSize; vtab->PointListPoints = PointListPoints; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->MapMerge = MapMerge; region->RegBaseMesh = RegBaseMesh; region->RegBaseBox = RegBaseBox; region->RegBasePick = RegBasePick; region->RegPins = RegPins; region->GetClosed = GetClosed; region->MaskB = MaskB; region->MaskD = MaskD; region->MaskF = MaskF; region->MaskI = MaskI; region->MaskL = MaskL; region->MaskS = MaskS; region->MaskUB = MaskUB; region->MaskUI = MaskUI; region->MaskUL = MaskUL; region->MaskUS = MaskUS; #if HAVE_LONG_DOUBLE /* Not normally implemented */ region->MaskLD = MaskLD; #endif /* Declare the class dump function. There is no copy constructor or destructor. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "PointList", "Collection of points" ); /* 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) ); } } /* * Name: * Mask * Purpose: * Mask a region of a data grid. * Type: * Private function. * Synopsis: * #include "pointlist.h" * int Mask( AstRegion *this, AstMapping *map, int inside, int ndim, * const int lbnd[], const int ubnd[], in[], * val ) * Class Membership: * PointList function method (replaces the astMask methods * inherited from the parent Region class). * Description: * This is a set of functions for masking out regions within gridded data * (e.g. an image). The functions modifies a given data grid by * assigning a specified value to all samples which are inside (or outside * if "inside" is zero) the specified Region. * * You should use a masking function which matches the numerical * type of the data you are processing by replacing in * the generic function name astMask by an appropriate 1- or * 2-character type code. For example, if you are masking data * with type "float", you should use the function astMaskF (see * the "Data Type Codes" section below for the codes appropriate to * other numerical types). * Parameters: * this * Pointer to a Region. * map * Pointer to a Mapping. The forward transformation should map * positions in the coordinate system of the supplied Region * into pixel coordinates as defined by the "lbnd" and "ubnd" * parameters. A NULL pointer can be supplied if the coordinate * system of the supplied Region corresponds to pixel coordinates. * This is equivalent to supplying a UnitMap. * * The number of inputs for this Mapping (as given by its Nin attribute) * should match the number of axes in the supplied Region (as given * by the Naxes attribute of the Region). The number of outputs for the * Mapping (as given by its Nout attribute) should match the number of * grid dimensions given by the value of "ndim" below. * inside * A boolean value which indicates which pixel are to be masked. If * a non-zero value is supplied, then all grid pixels which are inside * the supplied Region are assigned the value given by "val", * and all other pixels are left unchanged. If zero is supplied, then * all grid pixels which are not inside the supplied Region are * assigned the value given by "val", and all other pixels are left * unchanged. Note, the Negated attribute of the Region is used to * determine which pixel are inside the Region and which are outside. * So the inside of a Region which has not been negated is the same as * the outside of the corresponding negated Region. * ndim * The number of dimensions in the input grid. This should be at * least one. * lbnd * Pointer to an array of integers, with "ndim" elements, * containing the coordinates of the centre of the first pixel * in the input grid along each dimension. * ubnd * Pointer to an array of integers, with "ndim" elements, * containing the coordinates of the centre of the last pixel in * the input grid along each dimension. * * Note that "lbnd" and "ubnd" together define the shape * and size of the input grid, its extent along a particular * (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the * index "j" to be zero-based). They also define * the input grid's coordinate system, each pixel having unit * extent along each dimension with integral coordinate values * at its centre. * in * Pointer to an array, with one element for each pixel in the * input grid, containing the data to be masked. The * numerical type of this array should match the 1- or * 2-character type code appended to the function name (e.g. if * you are using astMaskF, the type of each array element * should be "float"). * * The storage order of data within this array should be such * that the index of the first grid dimension varies most * rapidly and that of the final dimension least rapidly * (i.e. Fortran array indexing is used). * * On exit, the samples specified by "inside" are set to the value * of "val". All other samples are left unchanged. * val * This argument should have the same type as the elements of * the "in" array. It specifies the value used to flag the * masked data (see "inside"). * Returned Value: * The number of pixels to which a value of "badval" has been assigned. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * Data Type Codes: * To select the appropriate masking function, you should * replace in the generic function name astMask with a * 1- or 2-character data type code, so as to match the numerical * type of the data you are processing, as follows: * - D: double * - F: float * - L: long int * - UL: unsigned long int * - I: int * - UI: unsigned int * - S: short int * - US: unsigned short int * - B: byte (signed char) * - UB: unsigned byte (unsigned char) * * For example, astMaskD would be used to process "double" * data, while astMaskS would be used to process "short int" * data, etc. */ /* Define a macro to implement the function for a specific data type. */ #define MAKE_MASK(X,Xtype) \ static int Mask##X( AstRegion *this, AstMapping *map, int inside, int ndim, \ const int lbnd[], const int ubnd[], \ Xtype in[], Xtype val, int *status ) { \ \ /* Local Variables: */ \ AstFrame *grid_frame; /* Pointer to Frame describing grid coords */ \ AstPointSet *pset1; /* Pointer to base Frame positions */ \ AstPointSet *pset2; /* Pointer to current Frame positions */ \ AstRegion *used_region; /* Pointer to Region to be used by astResample */ \ Xtype *temp; /* Pointer to temp storage for retained points */ \ double **ptr2; /* Pointer to pset2 data values */ \ int *iv; /* Pointer to index array */ \ int i; /* Point index */ \ int idim; /* Loop counter for coordinate dimensions */ \ int ii; /* Vectorised point index */ \ int j; /* Axis index */ \ int nax; /* Number of Region axes */ \ int negated; /* Has Region been negated? */ \ int nin; /* Number of Mapping input coordinates */ \ int nout; /* Number of Mapping output coordinates */ \ int npnt; /* Number of points in PointList */ \ int result; /* Result value to return */ \ int vlen; /* Length of vectorised array */ \ \ /* Initialise. */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Obtain value for the Naxes attribute of the Region. */ \ nax = astGetNaxes( this ); \ \ /* If supplied, obtain values for the Nin and Nout attributes of the Mapping. */ \ if( map ) { \ nin = astGetNin( map ); \ nout = astGetNout( map ); \ \ /* If OK, check that the number of mapping inputs matches the \ number of axes in the Region. Report an error if necessary. */ \ if ( astOK && ( nax != nin ) ) { \ astError( AST__NGDIN, "astMask"#X"(%s): Bad number of mapping " \ "inputs (%d).", status, astGetClass( this ), nin ); \ astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ "to specify a position.", status, \ astGetClass( this ), nax, ( nax == 1 ) ? "" : "s" ); \ } \ \ /* If OK, check that the number of mapping outputs matches the \ number of grid dimensions. Report an error if necessary. */ \ if ( astOK && ( ndim != nout ) ) { \ astError( AST__NGDIN, "astMask"#X"(%s): Bad number of mapping " \ "outputs (%d).", status, astGetClass( this ), nout ); \ astError( AST__NGDIN, "The pixel grid requires %d coordinate value%s " \ "to specify a position.", status, \ ndim, ( ndim == 1 ) ? "" : "s" ); \ } \ \ /* Create a new Region by mapping the supplied Region with the supplied \ Mapping.*/ \ grid_frame = astFrame( ndim, "Domain=grid", status ); \ used_region = astMapRegion( this, map, grid_frame ); \ grid_frame = astAnnul( grid_frame ); \ \ /* If no Mapping was supplied check that the number of grid dimensions \ matches the number of axes in the Region.*/ \ } else if ( astOK && ( ( ndim != nax ) || ( ndim < 1 ) ) ) { \ used_region = NULL; \ astError( AST__NGDIN, "astMask"#X"(%s): Bad number of input grid " \ "dimensions (%d).", status, astGetClass( this ), ndim ); \ if ( ndim != nax ) { \ astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ "to specify an input position.", status, \ astGetClass( this ), nax, ( nax == 1 ) ? "" : "s" ); \ } \ \ /* If no Mapping was supplied and the parameters look OK, clone the \ supplied Region pointer for use later on. */ \ } else { \ used_region = astClone( this ); \ } \ \ /* Check that the lower and upper bounds of the input grid are \ consistent. Report an error if any pair is not. */ \ if ( astOK ) { \ for ( idim = 0; idim < ndim; idim++ ) { \ if ( lbnd[ idim ] > ubnd[ idim ] ) { \ astError( AST__GBDIN, "astMask"#X"(%s): Lower bound of " \ "input grid (%d) exceeds corresponding upper bound " \ "(%d).", status, astGetClass( this ), \ lbnd[ idim ], ubnd[ idim ] ); \ astError( AST__GBDIN, "Error in input dimension %d.", status, \ idim + 1 ); \ break; \ } \ } \ } \ \ /* Get the PointSet in the base Frame of the Region's FrameSet, and \ transform to the current (GRID) Frame. */ \ pset1 = used_region->points; \ pset2 = astRegTransform( used_region, pset1, 1, NULL, NULL ); \ ptr2 =astGetPoints( pset2 ); \ \ /* Allocate memory to hold the corresponding vector indices. */ \ npnt = astGetNpoint( pset2 ); \ iv = astMalloc( sizeof(int)*(size_t) npnt ); \ if( astOK ) { \ \ /* Convert the transformed GRID positions into integer indices into the \ vectorised data array. Also form the total size of the data array. */ \ vlen = 0; \ for( i = 0; i < npnt; i++ ) { \ vlen = 1; \ ii = 0; \ for( j = 0; j < ndim; j++ ) { \ ii += vlen*( (int)( ptr2[ j ][ i ] + 0.5 ) - lbnd[ j ] ); \ vlen *= ubnd[ i ] - lbnd[ i ] + 1; \ } \ iv[ i ] = ii; \ } \ \ /* See if the Region is negated. */ \ negated = astGetNegated( used_region ); \ \ /* If necessary, set the transformed pixel coords to the supplied value. */ \ if( ( inside && !negated ) || ( !inside && negated ) ) { \ for( i = 0; i < npnt; i++ ) in[ iv[ i ] ] = val; \ result = npnt; \ \ /* If necessary, set all except the transformed pixel coords to the supplied \ value. */ \ } else { \ temp = astMalloc( sizeof( Xtype )*(size_t)npnt ); \ if( astOK ) { \ for( i = 0; i < npnt; i++ ) temp[ i ] = in[ iv[ i ] ]; \ for( i = 0; i < vlen; i++ ) in[ i ] = val; \ for( i = 0; i < npnt; i++ ) in[ iv[ i ] ] = temp[ i ]; \ result = vlen - npnt; \ } \ temp = astFree( temp ); \ } \ } \ \ /* Free resources */ \ iv = astFree( iv ); \ pset2 = astAnnul( pset2 ); \ used_region = astAnnul( used_region ); \ \ /* If an error occurred, clear the returned result. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } /* Expand the above macro to generate a function for each required data type. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ MAKE_MASK(LD,long double) #endif MAKE_MASK(D,double) MAKE_MASK(F,float) MAKE_MASK(L,long int) MAKE_MASK(UL,unsigned long int) MAKE_MASK(I,int) MAKE_MASK(UI,unsigned int) MAKE_MASK(S,short int) MAKE_MASK(US,unsigned short int) MAKE_MASK(B,signed char) MAKE_MASK(UB,unsigned char) /* Undefine the macro. */ #undef MAKE_MASK static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a PointList. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * PointList method (over-rides the protected astMapMerge method * inherited from the Region class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated PointList in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated PointList with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated PointList which is to be merged with * its neighbours. This should be a cloned copy of the PointList * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * PointList it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated PointList resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstPointList *oldint; /* Pointer to supplied PointList */ AstMapping *map; /* Pointer to adjacent Mapping */ AstMapping *new; /* Simplified or merged Region */ int i1; /* Index of first Mapping merged */ int i; /* Loop counter */ int result; /* Result value to return */ /* Initialise. */ result = -1; i1 = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the PointList. */ oldint = (AstPointList *) this; /* First of all, see if the PointList can be replaced by a simpler Region, without reference to the neighbouring Regions in the list. */ /* =====================================================================*/ /* Try to simplify the PointList. If the pointer value has changed, we assume some simplification took place. */ new = astSimplify( oldint ); if( new != (AstMapping *) oldint ) { /* Annul the PointList pointer in the list and replace it with the new Region pointer, and indicate that the forward transformation of the returned Region should be used (not really needed but keeps things clean). */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the PointList itself could not be simplified, see if it can be merged with the Regions on either side of it in the list. We can only merge in parallel. */ /* =====================================================================*/ } else if( ! series ){ new = astAnnul( new ); /* Attempt to merge the PointList with its lower neighbour (if any). */ if( where > 0 ) { i1 = where - 1; map = ( *map_list )[ where - 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergePointList( oldint, (AstRegion *) map, 0, status ); } } /* If this did not produced a merged Region, attempt to merge the PointList with its upper neighbour (if any). */ if( !new && where < *nmap - 1 ) { i1 = where; map = ( *map_list )[ where + 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergePointList( oldint, (AstRegion *) map, 1, status ); } } /* If succesfull... */ if( new ){ /* Annul the first of the two Mappings, and replace it with the merged Region. Also clear the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = new; ( *invert_list )[ i1 ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i1 + 1 ] ); for ( i = i1 + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } } else { new = astAnnul( new ); } /* Return the result. */ return result; } static AstRegion *MergePointList( AstPointList *this, AstRegion *reg, int plsfirst, int *status ) { /* * Name: * MergePointList * Purpose: * Attempt to merge a PointList with another Region to form a Region of * higher dimensionality. * Type: * Private function. * Synopsis: * #include "pointlist.h" * AstRegion *MergePointList( AstPointList *this, AstRegion *reg, * int plsfirst, int *status ) * Class Membership: * PointList member function. * Description: * This function attempts to combine the supplied Regions together * into a Region of higher dimensionality. * Parameters: * this * Pointer to a PointList. * reg * Pointer to another Region. * plsfirst * If non-zero, then the PointList axes are put first in the new Region. * Otherwise, the other Region's axes are put first. * status * Pointer to the inherited status value. * Returned Value: * A pointer to a new region, or NULL if the supplied Regions could * not be merged. */ /* Local Variables: */ AstFrame *bfrm; /* Pointer to base Frame for "result" */ AstFrame *cfrm; /* Pointer to current Frame for "result" */ AstFrame *frm_reg; /* Pointer to Frame from "reg" */ AstFrame *frm_this; /* Pointer to Frame from "this" */ AstMapping *bcmap; /* Base->current Mapping for "result" */ AstMapping *map_reg; /* Base->current Mapping from "reg" */ AstMapping *map_this; /* Base->current Mapping from "this" */ AstMapping *sbunc; /* Simplified uncertainty */ AstPointSet *pset_new; /* PointSet for new PointList */ AstPointSet *pset_reg; /* PointSet from reg */ AstPointSet *pset_this; /* PointSet from this */ AstRegion *bunc; /* Base Frame uncertainty Region */ AstRegion *new; /* Pointer to new PointList in base Frame */ AstRegion *result; /* Pointer to returned PointList in current Frame */ AstRegion *unc_reg; /* Current Frame uncertainty Region from "reg" */ AstRegion *unc_this; /* Current Frame uncertainty Region from "this" */ double **ptr_new; /* PointSet data pointers for new PointList */ double **ptr_reg; /* PointSet data pointers for reg */ double **ptr_this; /* PointSet data pointers for this */ double fac_reg; /* Ratio of used to default MeshSize for "reg" */ double fac_this; /* Ratio of used to default MeshSize for "this" */ int i; /* Axis index */ int msz_reg; /* Original MeshSize for "reg" */ int msz_reg_set; /* Was MeshSize originally set for "reg"? */ int msz_this; /* Original MeshSize for "this" */ int msz_this_set; /* Was MeshSize originally set for "this"? */ int nax; /* Number of axes in "result" */ int nax_reg; /* Number of axes in "reg" */ int nax_this; /* Number of axes in "this" */ int neg_reg; /* Negated attribute value for other supplied Region */ int neg_this; /* Negated attribute value for supplied PointList */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get the Closed attributes of the two Regions. They must be the same in each Region if we are to merge the Regions. In addition, in order to merge, either both Regions must have a defined uncertainty, or neither Region must have a defined Uncertainty. */ if( astGetClosed( this ) == astGetClosed( reg ) && astTestUnc( this ) == astTestUnc( reg ) ) { /* Get the Nagated attributes of the two Regions. */ neg_this = astGetNegated( this ); neg_reg = astGetNegated( reg ); /* We only check for merging with another PointList (other classes such as Box and Interval check for merging of PointLists with other classes). The result will be an PointList. Both Regions must have the same value for the Negated flag, and can contain only a single point. */ if( astIsAPointList( reg ) && neg_this == neg_reg && astGetListSize( this ) == 1 && astGetListSize( (AstPointList *) reg ) == 1 ) { /* Get the number of axes in the two supplied Regions. */ nax_reg = astGetNaxes( reg ); nax_this = astGetNaxes( this ); /* Get the number of axes the combination will have. */ nax = nax_reg + nax_this; /* Get the base Frames from the two Region FrameSets, and combine them into a single CmpFrame that will be used to create the new Region. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); frm_reg = astGetFrame( reg->frameset, AST__BASE ); if( plsfirst ) { bfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { bfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); /* Get pointers to the coordinate data in the two PointLists */ pset_this = ((AstRegion *) this)->points; ptr_this = astGetPoints( pset_this ); pset_reg = reg->points; ptr_reg = astGetPoints( pset_reg ); /* Create a PointSet to hold the points for the returned PointList. */ pset_new = astPointSet( 1, nax, "", status ); /* Get pointers to its data. */ ptr_new = astGetPoints( pset_new ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the point positions fon the selected axes into the arrays allocated above, in the requested order. */ if( plsfirst ) { for( i = 0; i < nax_this; i++ ) { ptr_new[ i ][ 0 ] = ptr_this[ i ][ 0 ]; } for( ; i < nax; i++ ) { ptr_new[ i ][ 0 ] = ptr_reg[ i - nax_this ][ 0 ]; } } else { for( i = 0; i < nax_reg; i++ ) { ptr_new[ i ][ 0 ] = ptr_reg[ i ][ 0 ]; } for( ; i < nax; i++ ) { ptr_new[ i ][ 0 ] = ptr_this[ i - nax_reg ][ 0 ]; } } /* Create the new PointList. */ new = (AstRegion *) astPointList( bfrm, pset_new, NULL, "", status ); /* Propagate remaining attributes of the supplied Region to it. */ astRegOverlay( new, this, 1 ); /* Ensure the Negated flag is set correctly in the returned PointList. */ if( neg_this ) { astSetNegated( new, neg_this ); } else { astClearNegated( new ); } /* If both the supplied Regions have uncertainty, assign the new Region an uncertainty. */ if( astTestUnc( this ) && astTestUnc( reg ) ) { /* Get the uncertainties from the two supplied Regions. */ unc_this = astGetUncFrm( this, AST__BASE ); unc_reg = astGetUncFrm( reg, AST__BASE ); /* Combine them into a single Region (a Prism), in the correct order. */ if( plsfirst ) { bunc = (AstRegion *) astPrism( unc_this, unc_reg, "", status ); } else { bunc = (AstRegion *) astPrism( unc_reg, unc_this, "", status ); } /* Attempt to simplify the Prism. */ sbunc = astSimplify( bunc ); /* Use the simplified Prism as the uncertainty for the returned Region. */ astSetUnc( new, sbunc ); /* Free resources. */ sbunc = astAnnul( sbunc ); bunc = astAnnul( bunc ); unc_reg = astAnnul( unc_reg ); unc_this = astAnnul( unc_this ); } /* Get the current Frames from the two Region FrameSets, and combine them into a single CmpFrame. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__CURRENT ); frm_reg = astGetFrame( reg->frameset, AST__CURRENT ); if( plsfirst ) { cfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { cfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } /* Get the base -> current Mappings from the two Region FrameSets, and combine them into a single parallel CmpMap that connects bfrm and cfrm. */ map_this = astGetMapping( ((AstRegion *) this)->frameset, AST__BASE, AST__CURRENT ); map_reg = astGetMapping( reg->frameset, AST__BASE, AST__CURRENT ); if( plsfirst ) { bcmap = (AstMapping *) astCmpMap( map_this, map_reg, 0, "", status ); } else { bcmap = (AstMapping *) astCmpMap( map_reg, map_this, 0, "", status ); } /* Map the new Region into the new current Frame. */ result = astMapRegion( new, bcmap, cfrm ); /* The filling factor in the returned is the product of the filling factors for the two supplied Regions. */ if( astTestFillFactor( reg ) || astTestFillFactor( this ) ) { astSetFillFactor( result, astGetFillFactor( reg )* astGetFillFactor( this ) ); } /* If the MeshSize value is set in either supplied Region, set a value for the returned Region which scales the default value by the product of the scaling factors for the two supplied Regions. First see if either MeshSize value is set. */ msz_this_set = astTestMeshSize( this ); msz_reg_set = astTestMeshSize( reg ); if( msz_this_set || msz_reg_set ) { /* If so, get the two MeshSize values (one of which may be a default value), and then clear them so that the default value will be returned in future. */ msz_this = astGetMeshSize( this ); msz_reg = astGetMeshSize( reg ); astClearMeshSize( this ); astClearMeshSize( reg ); /* Get the ratio of the used MeshSize to the default MeshSize for both Regions. */ fac_this = (double)msz_this/(double)astGetMeshSize( this ); fac_reg = (double)msz_reg/(double)astGetMeshSize( reg ); /* The MeshSize of the returned Returned is the default value scaled by the product of the two ratios found above. */ astSetMeshSize( result, fac_this*fac_reg*astGetMeshSize( result ) ); /* Re-instate the original MeshSize values for the supplied Regions (if set) */ if( msz_this_set ) astSetMeshSize( this, msz_this ); if( msz_reg_set ) astSetMeshSize( reg, msz_reg ); } /* Free remaining resources */ frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); map_this = astAnnul( map_this ); map_reg = astAnnul( map_reg ); bcmap = astAnnul( bcmap ); cfrm = astAnnul( cfrm ); new = astAnnul( new ); } bfrm = astAnnul( bfrm ); pset_new = astAnnul( pset_new ); } } /* If an error has occurred, annul the returned pointer. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } void PointListPoints( AstPointList *this, AstPointSet **pset, int *status) { /* *+ * Name: * astPointListPoints * Purpose: * Return the defining points of a PointList. * Type: * Protected function. * Synopsis: * #include "pointlist.h" * astPointListPoints( AstPointList *this, AstPointSet **pset ) * Class Membership: * Region virtual function. * Description: * This function returns the axis values at the points defining the * supplied PointList. * Parameters: * this * Pointer to the PointList. * pset * Address of a location at which to return a pointer to a PointSet * holding the points in the PointList, in the base Frame of the * encapsulated FrameSet. The returned Pointer should be annulled * when no longer needed. *- */ /* Check the inherited status. */ if( !astOK ) return; /* Return a clone of the PointSet holding the points defining the PointList. */ *pset = astClone( ((AstRegion *) this)->points ); } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "pointlist.h" * void astRegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * PointList member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; /* Pointer to encapsulated Frame */ AstPointList *this; /* Pointer to PointList structure */ AstPointSet *pset; /* Pointer to PointSet defining the Region */ double **ptr; /* Pointer to PointSet data */ double *p; /* Pointer to next axis value */ double *lb; /* Pointer to lower limit array */ double *ub; /* Pointer to upper limit array */ double d; /* Axis offset from refernce value */ double p0; /* Reference axis value */ int ic; /* Axis index */ int ip; /* Point index */ int nb; /* Number of bytes to be copied */ int nc; /* No. of axes in base Frame */ int np; /* No. of points in PointSet */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the PointList structure. */ this = (AstPointList *) this_region; /* Calculate the number of bytes in each array. */ nb = sizeof( double )*(size_t) astGetNaxes( this ); /* If the base Frame bounding box has not yet been found, find it now and store it in the PointList structure. */ if( !this->lbnd || !this->ubnd ) { /* Allocate memory to store the bounding box in the PointList structure. */ lb = astMalloc( nb ); ub = astMalloc( nb ); /* Get the axis values for the PointSet which defines the location and extent of the region in the base Frame of the encapsulated FrameSet. */ pset = this_region->points; ptr = astGetPoints( pset ); nc = astGetNcoord( pset ); np = astGetNpoint( pset ); /* Get a pointer to the base Frame in the encaposulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Check pointers can be used safely. */ if( astOK ) { /* Find the bounds on each axis in turn. */ for( ic = 0; ic < nc; ic++ ) { /* We first find the max and min axis offsets from the first point. We used astAxDistance to cater for the possbility that the Frame may be a SkyFrame and thus have circular redundancy. */ p = ptr[ ic ] + 1; p0 = p[ -1 ]; lb[ ic ] = 0.0; ub[ ic ] = 0.0; for( ip = 1; ip < np; ip++, p++ ) { d = astAxDistance( frm, ic + 1, p0, *p ); if( d < lb[ ic ] ) lb[ ic ] = d; if( d > ub[ ic ] ) ub[ ic ] = d; } /* Now convert these offsets to actual axis values. */ lb[ ic ] = astAxOffset( frm, ic + 1, p0, lb[ ic ] ); ub[ ic ] = astAxOffset( frm, ic + 1, p0, ub[ ic ] ); } } /* Free resources */ frm = astAnnul( frm ); /* Store the pointers in the PointList structure. */ if( astOK ) { this->lbnd = lb; this->ubnd = ub; } else { this->lbnd = astFree( this->lbnd ); this->ubnd = astFree( this->ubnd ); } } /* If the bounding box has been found succesfully, copy it into the supplied arrays. */ if( astOK ) { memcpy( lbnd, this->lbnd, nb ); memcpy( ubnd, this->ubnd, nb ); } } static AstPointSet *RegBaseMesh( AstRegion *this, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "pointlist.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * PointList member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. The axis values in this PointSet will have * associated accuracies derived from the accuracies which were * supplied when the Region was created. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstPointSet *result; /* Check the global error status. */ if ( !astOK ) return NULL; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this->basemesh ) { result = astClone( this->basemesh ); /* Otherwise, create a new mesh. */ } else { /* It is just a copy of the encapsulated PointSet. */ result = astCopy( this->points ); /* Same the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this->basemesh = astClone( result ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "pointlist.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * PointList member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; /* The base Frame in the supplied Region */ AstFrame *frm; /* The base Frame in the returned Region */ AstPointSet *pset; /* Holds axis values defining the supplied Region */ AstPointSet *pset_new; /* Holds axis values defining the returned Region */ AstRegion *bunc; /* The uncertainty in the supplied Region */ AstRegion *result; /* Returned Region */ AstRegion *unc; /* The uncertainty in the returned Region */ double **ptr; /* Holds axis values defining the supplied Region */ double **ptr_new; /* Holds axis values defining the returned Region */ double *p; /* Pointer to next input axis value */ double *q; /* Pointer to next output axis value */ int i; /* Index of axis within returned Region */ int j; /* Point index */ int npnt; /* Number of points in PointList */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the base Frame of the encapsulated FrameSet. */ bfrm = astGetFrame( this_region->frameset, AST__BASE ); /* Create a Frame by picking the selected axes from the base Frame of the encapsulated FrameSet. */ frm = astPickAxes( bfrm, naxes, axes, NULL ); /* Get the uncertainty Region (if any) within the base Frame of the supplied Region, and select the required axes from it. If the resulting Object is not a Region, annul it so that the returned Region will have no uncertainty. */ if( astTestUnc( this_region ) ) { bunc = astGetUncFrm( this_region, AST__BASE ); unc = astPickAxes( bunc, naxes, axes, NULL ); bunc = astAnnul( bunc ); if( ! astIsARegion( unc ) ) unc = astAnnul( unc ); } else { unc = NULL; } /* Get pointers to the coordinate data in the parent Region structure. */ pset = this_region->points; ptr = astGetPoints( pset ); npnt = astGetNpoint( pset ); /* Create a PointSet to hold the points for the returned PointList. */ pset_new = astPointSet( npnt, naxes, "", status ); /* Get pointers to its data. */ ptr_new = astGetPoints( pset_new ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the point positions on the selected axes into the arrays allocated above. */ for( i = 0; i < naxes; i++ ) { p = ptr[ axes[ i ] ]; q = ptr_new[ i ]; for( j = 0; j < npnt; j++ ) *(q++) = *(p++); } /* Create the new PointList. */ result = (AstRegion *) astPointList( frm, pset_new, unc, "", status ); } /* Free resources */ frm = astAnnul( frm ); bfrm = astAnnul( bfrm ); if( unc ) unc = astAnnul( unc ); pset_new = astAnnul( pset_new ); /* Return a NULL pointer if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * PointList member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given PointList. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied PointList "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the PointList. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "this". * Each element in the returned array is set to 1 if the * corresponding position in "this" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstPointList *pl; /* Pointer to PointList holding supplied points */ AstPointList *this; /* Pointer to the PointList structure. */ AstPointSet *pset2; /* Supplied points masked by this PointList */ AstPointSet *pset3; /* This PointList masked by supplied points */ double **ptr2; /* Pointer to axis values in "pset2" */ double **ptr3; /* Pointer to axis values in "pset3" */ double **ptr; /* Pointer to axis values in "this" */ double *p; /* Pointer to next axis value to read */ int ic; /* Axis index */ int icurr; /* Index of original current Frame in "this" */ int ip; /* Point index */ int nc; /* No. of axes in Box base frame */ int neg_old; /* Original Negated flag for "this" */ int np; /* No. of supplied points */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Box structure. */ this = (AstPointList *) this_region; /* Temporarily ensure that the current Frame in "this" is the same as the base Frame. We need to do this since the supplied points are in the base Frame of "this", but the astTransform method below assumes that it is transforming points in the current Frame of the Region. */ icurr = astGetCurrent( this_region->frameset ); astSetCurrent( this_region->frameset, AST__BASE ); /* Get pointer to the supplied axis values, the number of points and the number of axis values per point. */ ptr = astGetPoints( pset ); np = astGetNpoint( pset ); nc = astGetNcoord( pset ); /* All the supplied points should be within the supplied PointsList region (given that "within" implies some tolerance). Transform the positions using this PointList and check if any of the resulting points fell outside this PointList. We need to ensure that the PointList is not negated first. */ neg_old = astGetNegated( this ); astSetNegated( this, 0 ); pset2 = astTransform( this, pset, 1, NULL ); ptr2 = astGetPoints( pset2 ); /* Check pointers can be used. */ if( astOK ) { /* Check there are no bad points (i.e. check that none of the points are outside the supplied PointList). The algorithm used to do this depends on whether we need to create an output mask. */ result = 1; if( mask ) { /* Create the returned mask array. */ *mask = astMalloc( np ); if( astOK ) { /* Initialise the mask elements on the basis of the first axis values */ result = 1; p = ptr2[ 0 ]; for( ip = 0; ip < np; ip++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ ip ] = 0; } else { (*mask)[ ip ] = 1; } } /* Now check for bad values on other axes. */ for( ic = 1; ic < nc; ic++ ) { p = ptr2[ ic ]; for( ip = 0; ip < np; ip++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ ip ] = 0; } } } } /* If no output mask is to be made, we can break out of the check as soon as the first bad value is found. */ } else { for( ic = 0; ic < nc && result; ic++ ){ p = ptr2[ ic ]; for( ip = 0; ip < np; ip++,p++ ){ if( *p == AST__BAD ) { result = 0; break; } } } } /* If this check was passed, we perform a similar check in the opposite direction: we create a new PointList from the supplied list of points, and then we transform the points associated with the supplied PointList using the new PointList. This checks that all the points in the supplied PointList are close to the supplied points. Create the new PointList holding the supplied points. */ if( result ) { pl = astPointList( unc, pset, unc, "", status ); /* Transform the points in "this" PointList using the new PointList as a Mapping. */ pset3 = astTransform( pl, this_region->points, 1, NULL ); ptr3 = astGetPoints( pset3 ); /* Check pointers can be used. */ if( astOK ) { for( ic = 0; ic < nc && result; ic++ ){ p = ptr3[ ic ]; for( ip = 0; ip < np; ip++,p++ ){ if( *p == AST__BAD ) { result = 0; break; } } } } /* Free resources. */ pl = astAnnul( pl ); pset3 = astAnnul( pset3 ); } } pset2 = astAnnul( pset2 ); /* Re-instate the original current Frame in "this". */ astSetCurrent( this_region->frameset, icurr ); /* Re-instate the original Negated flag for "this". */ astSetNegated( this, neg_old ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * PointList member function (over-rides the astSetAttrib protected * method inherited from the Object class). * Description: * This function assigns an attribute value for a PointList, 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 PointList. * setting * Pointer to a null-terminated string specifying the new * attribute value. */ /* Local Variables: */ AstPointList *this; /* Pointer to the PointList structure */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* Define a macro to see if the setting string matches any of the read-only attributes of this class. */ #define MATCH(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ ( nc >= len ) ) /* Use this macro to report an error if a read-only attribute has been specified. */ if ( MATCH( "listsize" ) ) { 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 ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "pointlist.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * PointList method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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 *fr; /* Pointer to encapsulated Frame */ AstMapping *map; /* Pointer to frameset Mapping */ AstMapping *result; /* Result pointer to return */ AstPointList *new2; /* Pointer to simplified Region */ AstPointSet *pset1; /* Original base Frame positions */ AstPointSet *pset2; /* Current Frame Frame positions */ AstRegion *new; /* Pointer to simplified Region */ AstRegion *this; /* Pointer to original Region structure */ AstRegion *unc; /* Pointer to new uncertainty Region */ double **ptr2; /* Pointer to current Frame points */ int simpler; /* Has some simplication taken place? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* Get the Mapping from base to current Frame. We can modify the PointList so that a UnitMap can be used. This is good because it means that the serialised PointList is simpler since the Dump function only needs to record one Frame instead of the whole FrameSet. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) ){ /* Get a pointer to the current Region Frame */ fr = astGetFrame( this->frameset, AST__CURRENT ); /* Get the PointSet which holds the base Frame positions defining this PointList. */ pset1 = this->points; /* Transform the PointSet using this Mapping. */ pset2 = astTransform( map, pset1, 1, NULL ); ptr2 = astGetPoints( pset2 ); /* Get the Region describing the positional uncertainty within the supplied PointList, in its current Frame. */ unc = astGetUncFrm( new, AST__CURRENT ); /* Create a new PointList, and use it in place of the original. */ new2 = astPointList( fr, pset2, unc, "", status ); (void) astAnnul( new ); new = (AstRegion *) new2; simpler = 1; /* Free resources. */ fr = astAnnul( fr ); pset2 = astAnnul( pset2 ); unc = astAnnul( unc ); } /* Free resources. */ map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a PointList. * Type: * Private function. * Synopsis: * #include "pointlist.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PointList member function (over-rides the astTestAttrib protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for one of a PointList's attributes. * Parameters: * this * Pointer to the PointList. * 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: */ AstPointList *this; /* Pointer to the PointList structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Test if the name matches any of the read-only attributes of this class. If it does, then return zero. */ if ( !strcmp( attrib, "listsize" ) ){ result = 0; /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a PointList to transform a set of points. * Type: * Private function. * Synopsis: * #include "pointlist.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * PointList member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a PointList and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region covered by the * PointList. PointList inside the region are copied unchanged from input * to output. * Parameters: * this * Pointer to the PointList. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the PointList. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *in_base; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *ps1; /* Pointer to accumulation PointSet */ AstPointSet *ps2; /* Pointer to accumulation PointSet */ AstPointSet *ps3; /* Pointer for swapping PointSet pointers */ AstPointSet *pset_base; /* PointList positions in "unc" base Frame */ AstPointSet *pset_reg; /* Pointer to Region PointSet */ AstPointSet *result; /* Pointer to output PointSet */ AstRegion *this; /* Pointer to the Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr1; /* Pointer to mask pointer array */ double **ptr_base; /* Pointer to axis values for "pset_base" */ double **ptr_out; /* Pointer to output coordinate data */ double *cen_orig; /* Pointer to array holding original centre coords */ double *mask; /* Pointer to mask axis values */ int coord; /* Zero-based index for coordinates */ int ncoord_base; /* No. of coordinates per base Frame point */ int ncoord_out; /* No. of coordinates per output point */ int npoint; /* No. of supplied input test points */ int nrp; /* No. of points in Region PointSet */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Avoid -Wall compiler warnings. */ ps1 = NULL; ps2 = NULL; /* Obtain a pointer to the Region structure. */ this = (AstRegion *) this_mapping; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). */ in_base = astRegTransform( this, in, 0, NULL, NULL ); /* The PointSet pointer returned above may be a clone of the "in" pointer. If so take a copy of the PointSet so we can change it safely. */ if( in_base == in ) { ps3 = astCopy( in_base ); (void) astAnnul( in_base ); in_base = ps3; ps3 = NULL; } /* Determine the numbers of points and coordinates per point from the base Frame PointSet and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( in_base ); ncoord_base = astGetNcoord( in_base ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* Get the axis values for the PointSet which defines the location and extent of the region in the base Frame, and check them. */ pset_reg = this->points; nrp = astGetNpoint( pset_reg ); if( astGetNcoord( pset_reg ) != ncoord_base && astOK ) { astError( AST__INTER, "astTransform(PointList): Illegal number of " "coords (%d) in the Region - should be %d " "(internal AST programming error).", status, astGetNcoord( pset_reg ), ncoord_base ); } /* Get the base Frame uncertainty Region. Temporarily set its negated flag. */ unc = astGetUncFrm( this, AST__BASE ); astSetNegated( unc, 1 ); /* Transform the PointList PointSet into the base Frame of the uncertainty Region, and get pointers to the corresponding axis value. */ pset_base = astRegTransform( unc, pset_reg, 0, NULL, NULL ); ptr_base = astGetPoints( pset_base ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* Save the original base Frame centre coords of the uncertainty Region. */ cen_orig = astRegCentre( unc, NULL, NULL, 0, AST__BASE ); /* We use the PointSet created above as the initial input to astTransform below. Also indicate we currently have no output PointSet. This will cause a new PointSet to be created on the first pass through the loop below. */ ps1 = astClone( in_base ); ps2 = NULL; /* Loop round all the points in the PointList. */ for ( point = 0; point < nrp; point++ ) { /* Centre the uncertainty Region at this PointList position. Note, the base Frame of the PointList should be the same as the current Frame of the uncertainty Region. */ astRegCentre( unc, NULL, ptr_base, point, AST__BASE ); /* Use the uncertainty Region to transform the supplied PointSet. This will set supplied points bad if they are within the uncertainty Region (since the uncertainty Region has been negated above). */ ps2 = astTransform( unc, ps1, 0, ps2 ); /* Use the output PointSet created above as the input for the next position. This causes bad points to be accumulated in the output PointSet. */ ps3 = ps2; ps2 = ps1; ps1 = ps3; } /* Re-instate the original centre coords of the uncertainty Region. */ astRegCentre( unc, cen_orig, NULL, 0, AST__BASE ); cen_orig = astFree( cen_orig ); /* The ps1 PointSet will now be a copy of the supplied PointSet but with positions set to bad if they are inside any of the re-centred uncertainty Regions. If this PointList has been negated, this is what we want so we just transfer this bad position mask to the result PointSet. If this PointList has not been negated we need to invert the bad position mask. Get a pointer to the first axis of the resulting PointSet. */ ptr1 = astGetPoints( ps1 ); if( astOK ) { mask = ptr1[ 0 ]; /* Apply the mask to the returned PointSet, inverted if necessary. */ if( astGetNegated( this ) ) { for ( point = 0; point < npoint; point++, mask++ ) { if( *mask == AST__BAD ) { for( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } else { for ( point = 0; point < npoint; point++, mask++ ) { if( *mask != AST__BAD ) { for( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } } } /* Clear the negated flag for the uncertainty Region. */ astClearNegated( unc ); /* Free resources */ in_base = astAnnul( in_base ); pset_base = astAnnul( pset_base ); unc = astAnnul( unc ); if( ps2 ) ps2 = astAnnul( ps2 ); if( ps1 ) ps1 = astAnnul( ps1 ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * ListSize * Purpose: * Number of points in a PointList. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This is a read-only attribute giving the number of points in a * PointList. This value is determined when the PointList is created. * Applicability: * PointList * All PointLists have this attribute. *att-- */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for PointList objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for PointList 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: */ AstPointList *in; /* Pointer to input PointList */ AstPointList *out; /* Pointer to output PointList */ int nb; /* Number of bytes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output PointLists. */ in = (AstPointList *) objin; out = (AstPointList *) objout; /* For safety, first clear any references to the input memory from the output PointList. */ out->lbnd = NULL; out->ubnd = NULL; /* Copy dynamic memory contents */ if( in->lbnd && in->ubnd ) { nb = sizeof( double )*astGetNaxes( in ); out->lbnd = astStore( NULL, in->lbnd, nb ); out->ubnd = astStore( NULL, in->ubnd, nb ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for PointList objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for PointList 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: */ AstPointList *this; /* Pointer to PointList */ /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) obj; /* Annul all resources. */ this->lbnd = astFree( this->lbnd ); this->ubnd = astFree( this->ubnd ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for PointList 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 PointList class to an output Channel. * Parameters: * this * Pointer to the PointList 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 Variables: */ AstPointList *this; /* Pointer to the PointList structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PointList structure. */ this = (AstPointList *) this_object; /* Write out values representing the instance variables for the PointList 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. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPointList and astCheckPointList functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(PointList,Region) astMAKE_CHECK(PointList) AstPointList *astPointList_( void *frame_void, AstPointSet *points, AstRegion *unc, const char *options, int *status, ...) { /* *+ * Name: * astPointList * Purpose: * Create a PointList. * Type: * Protected function. * Synopsis: * #include "pointlist.h" * AstPointList *astPointList( AstFrame *frame, AstPointSet *points, * AstRegion *unc, const char *options, * int *status, ...) { * Class Membership: * PointList constructor. * Description: * This function implements the protected interface to the astPointList * constructor function, returning a true C pointer. The parameter list * differs from the public constructor, in that the positions are * defined by a PointSet rather than an array of doubles. * Parameters: * frame * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. * points * A PointSet holding the physical coordinates of the points. * unc * An optional pointer to an existing Region which specifies the * uncertainties associated with each point in the PointList being * created. The uncertainty at any point in the PointList is found by * shifting the supplied "uncertainty" Region so that it is centred at * the point being considered. The area covered by the shifted * uncertainty Region then represents the uncertainty in the position. * The uncertainty is assumed to be the same for all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Box. Alternatively, a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the bounding box of the * PointList being created. * * The uncertainty Region has two uses: 1) when the astOverlap * function compares two Regions for equality the uncertainty Region * is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using astSimplify), the uncertainties are * used to determine if the transformed boundary can be accurately * represented by a specific shape of Region. * options * Pointer to a null-terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new PointList. The syntax used is identical to * that for the astSet function and may include "printf" format * specifiers identified by "%" symbols in the normal way. * status * Pointer to the inherited status value. * ... * If the "options" string contains "%" format specifiers, then * an optional list of additional 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 function (and for the C "printf" * function). * Returned Value: * A pointer to the new PointList. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstPointList *new; /* Pointer to new PointList */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the PointList, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPointList( NULL, sizeof( AstPointList ), !class_init, &class_vtab, "PointList", frame, points, unc ); /* 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 PointList'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 PointList. */ return new; } AstPointList *astPointListId_( void *frame_void, int npnt, int ncoord, int dim, const double *points, void *unc_void, const char *options, ... ) { /* *++ * Name: c astPointList f AST_POINTLIST * Purpose: * Create a PointList. * Type: * Public function. * Synopsis: c #include "pointlist.h" c AstPointList *astPointList( AstFrame *frame, int npnt, int ncoord, int dim, c const double *points, AstRegion *unc, c const char *options, ... ) f RESULT = AST_POINTLIST( FRAME, NPNT, COORD, DIM, POINTS, UNC, OPTIONS, STATUS ) * Class Membership: * PointList constructor. * Description: * This function creates a new PointList object and optionally initialises * its attributes. * * A PointList object is a specialised type of Region which represents a * collection of points in a coordinate Frame. * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. c npnt f NPNT = INTEGER (Given) * The number of points in the Region. c ncoord f NCOORD = INTEGER (Given) * The number of coordinates being supplied for each point. This * must equal the number of axes in the supplied Frame, given by * its Naxes attribute. c dim f DIM = INTEGER (Given) c The number of elements along the second dimension of the "points" f The number of elements along the first dimension of the POINTS * array (which contains the point coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value c given should not be less than "npnt". f given should not be less than NPNT. c points f POINTS( DIM, NCOORD ) = DOUBLE PRECISION (Given) c The address of the first element of a 2-dimensional array of c shape "[ncoord][dim]" giving the physical coordinates of the c points. These should be stored such that the value of coordinate c number "coord" for point number "pnt" is found in element c "in[coord][pnt]". f A 2-dimensional array giving the physical coordinates of the f points. These should be stored such that the value of coordinate f number COORD for point number PNT is found in element IN(PNT,COORD). c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the uncertainties * associated with each point in the PointList being created. The * uncertainty at any point in the PointList is found by shifting the * supplied "uncertainty" Region so that it is centred at the point * being considered. The area covered by the shifted uncertainty Region * then represents the uncertainty in the position. The uncertainty is * assumed to be the same for all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Box. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the bounding box of the * PointList being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 PointList. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new PointList. The syntax used is identical to that for the f AST_SET routine. 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 astPointList() f AST_POINTLIST = INTEGER * A pointer to the new PointList. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ AstFrame *frame; /* Pointer to Frame structure */ AstPointList *new; /* Pointer to new PointList */ AstPointSet *pset; /* Pointer to PointSet holding points */ AstRegion *unc; /* Pointer to Region structure */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const double *q; /* Pointer to next supplied axis value */ double **ptr; /* Pointer to data in pset */ double *p; /* Pointer to next PointSet axis value */ int *status; /* Pointer to inherited status value */ int i; /* Axis index */ int j; /* Point index */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Create a PointSet and store the supplied points in it. */ pset = astPointSet( npnt, ncoord , "", status ); ptr = astGetPoints( pset ); if( astOK ) { for( i = 0; i < ncoord; i++ ) { p = ptr[ i ]; q = points + i*dim; for( j = 0; j < npnt; j++ ) *(p++) = *(q++); } } /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the PointList, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPointList( NULL, sizeof( AstPointList ), !class_init, &class_vtab, "PointList", frame, pset, unc ); /* 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 PointList'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 ); } /* Free resources. */ pset = astAnnul( pset ); /* Return an ID value for the new PointList. */ return astMakeId( new ); } AstPointList *astInitPointList_( void *mem, size_t size, int init, AstPointListVtab *vtab, const char *name, AstFrame *frame, AstPointSet *points, AstRegion *unc, int *status ) { /* *+ * Name: * astInitPointList * Purpose: * Initialise a PointList. * Type: * Protected function. * Synopsis: * #include "pointlist.h" * AstPointList *astInitPointList( void *mem, size_t size, int init, * AstPointListVtab *vtab, const char *name, * AstFrame *frame, AstPointSet *points, * AstRegion *unc, int *status ) * Class Membership: * PointList initialiser. * Description: * This function is provided for use by class implementations to initialise * a new PointList object. It allocates memory (if necessary) to accommodate * the PointList plus any additional data associated with the derived class. * It then initialises a PointList 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 PointList at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the PointList is to be initialised. * This must be of sufficient size to accommodate the PointList data * (sizeof(PointList)) 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 PointList (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 PointList * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the PointList'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 PointList. * 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 * A pointer to the Frame in which the region is defined. * points * A PointSet containing the Points for the PointList. * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points in the new PointList being * initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal * to 1.0E-6 of the dimensions of the new PointList's bounding box are * used. If an uncertainty Region is supplied, it must be either a Box, * a Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new PointList. * 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: */ AstPointList *new; /* Pointer to new PointList */ int ncoord; /* No. of axes in PointSet */ int nin; /* No. of axes in Frame */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPointListVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the number of axis values per position is correct. */ nin = astGetNaxes( frame ); ncoord = astGetNcoord( points ); if( nin != ncoord ) { astError( AST__NCPIN, "astInitPointList(): Bad number of coordinate " "values (%d).", status, ncoord ); astError( AST__NCPIN, "The %s given requires %d coordinate value(s) for " "each input point.", status, astGetClass( frame ), nin ); } /* Initialise a Region structure (the parent class) as the first component within the PointList structure, allocating memory if necessary. */ if( astOK ) { new = (AstPointList *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, points, unc ); if ( astOK ) { /* Initialise the PointList data. */ /* ------------------------------ */ new->lbnd = NULL; new->ubnd = NULL; /* If an error occurred, clean up by deleting the new PointList. */ if ( !astOK ) new = astDelete( new ); } } /* Return a pointer to the new PointList. */ return new; } AstPointList *astLoadPointList_( void *mem, size_t size, AstPointListVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPointList * Purpose: * Load a PointList. * Type: * Protected function. * Synopsis: * #include "pointlist.h" * AstPointList *astLoadPointList( void *mem, size_t size, AstPointListVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * PointList loader. * Description: * This function is provided to load a new PointList 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 * PointList structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a PointList at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the PointList is to be * loaded. This must be of sufficient size to accommodate the * PointList data (sizeof(PointList)) 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 PointList (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 PointList 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(AstPointList) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new PointList. If this is NULL, a pointer * to the (static) virtual function table for the PointList 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 "PointList" is used instead. * Returned Value: * A pointer to the new PointList. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPointList *new; /* Pointer to the new PointList */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this PointList. In this case the PointList belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPointList ); vtab = &class_vtab; name = "PointList"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPointListVtab( 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 PointList. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "PointList" ); /* 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. */ /* If an error occurred, clean up by deleting the new PointList. */ if ( !astOK ) new = astDelete( new ); } /* Return the new PointList pointer. */ return new; } /* 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. */ int astGetListSize_( AstPointList *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,PointList,GetListSize))( this, status ); } void astPointListPoints_( AstPointList *this, AstPointSet **pset, int *status) { if ( !astOK ) return; (**astMEMBER(this,PointList,PointListPoints))( this, pset, status ); return; } ast-8.3.0/switchmap.h0000664000175000017500000002102413004147321011376 00000000000000#if !defined( SWITCHMAP_INCLUDED ) /* Include this file only once */ #define SWITCHMAP_INCLUDED /* *+ * Name: * switchmap.h * Type: * C include file. * Purpose: * Define the interface to the SwitchMap class. * Invocation: * #include "switchmap.h" * Description: * This include file defines the interface to the SwitchMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The SwitchMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astMapMerge * Merge a SwitchMap within a sequence of Mappings. * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsASwitchMap * Test class membership. * astSwitchMap * Create a SwitchMap. * * Protected: * astCheckSwitchMap * Validate class membership. * astInitSwitchMap * Initialise a SwitchMap. * astInitSwitchMapVtab * Initialise the virtual function table for the SwitchMap class. * astLoadSwitchMap * Load a SwitchMap. * Macros: * None. * Type Definitions: * Public: * AstSwitchMap * SwitchMap object type. * * Protected: * AstSwitchMapVtab * SwitchMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 13-MAR-2006 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* SwitchMap structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSwitchMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstMapping *fsmap; /* Pointer to forward selector Mapping */ AstMapping *ismap; /* Pointer to inverse selector Mapping */ int fsinv; /* Inversion flag for forward selector Mapping */ int isinv; /* Inversion flag for inverse selector Mapping */ int nroute; /* The number of route Mappings in the SwitchMap */ AstMapping **routemap; /* Array of route Mapping pointers */ int *routeinv; /* Array of inversion flags for route Mappings */ } AstSwitchMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSwitchMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ /* None. */ } AstSwitchMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstSwitchMapGlobals { AstSwitchMapVtab Class_Vtab; int Class_Init; } AstSwitchMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitSwitchMapGlobals_( AstSwitchMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SwitchMap) /* Check class membership */ astPROTO_ISA(SwitchMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSwitchMap *astSwitchMap_( void *, void *, int, void **, const char *, int *, ...); #else AstSwitchMap *astSwitchMapId_( void *, void *, int, void **, const char *, ... )__attribute__((format(printf,5,6))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSwitchMap *astInitSwitchMap_( void *, size_t, int, AstSwitchMapVtab *, const char *, AstMapping *, AstMapping *, int, AstMapping **, int * ); /* Vtab initialiser. */ void astInitSwitchMapVtab_( AstSwitchMapVtab *, const char *, int * ); /* Loader. */ AstSwitchMap *astLoadSwitchMap_( void *, size_t, AstSwitchMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ int astSwitchList_( AstSwitchMap *, int, int *, AstMapping ***, int **, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSwitchMap(this) astINVOKE_CHECK(SwitchMap,this,0) #define astVerifySwitchMap(this) astINVOKE_CHECK(SwitchMap,this,1) /* Test class membership. */ #define astIsASwitchMap(this) astINVOKE_ISA(SwitchMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSwitchMap astINVOKE(F,astSwitchMap_) #else #define astSwitchMap astINVOKE(F,astSwitchMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSwitchMap(mem,size,init,vtab,name,fsmap,ismap,nroute,routemaps) \ astINVOKE(O,astInitSwitchMap_(mem,size,init,vtab,name,astCheckMapping(fsmap),\ astCheckMapping(ismap),nroute,routemaps,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSwitchMapVtab(vtab,name) astINVOKE(V,astInitSwitchMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSwitchMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSwitchMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #define astSwitchList astSwitchList_ #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSwitchMap to validate SwitchMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ /* None. */ #endif ast-8.3.0/makeh0000664000175000017500000002155113004147321010243 00000000000000#!/usr/bin/perl #+ # Name: # makeh # Purpose: # Generate the contents of the "ast.h" header file. # Type: # Perl script. # Invocation: # makeh file_list # Description: # This script processes private header files used within the AST library # in order to extract the public information they contain. This information # is produced in a form suitable for use in the public "ast.h" header file, # which defines the public interface to the library. # Parameters: # file_list # A space-separated list of the private AST header files whose public # information is to be extracted. # Result: # The contents of the "ast.h" header file are written to standard output. # Notes: # - This script is specific to the AST library and contains some knowledge # of the input file contents. # History: # 10-JAN-2005 (DSB): # Added second argument (mode) to the mkdir invocation which creates # the temporary directory. # 2-MAR-2006 (DSB): # Check for "config.h" as well as # 6-JAN-2010 (DSB): # Add work-around for GCC 4.4.2 problem - the pre-processor seesm to simply # throw away backslshes that escape newlines in the input header file. Reported # by Bryan Irby at GSFC. # 27-JUL-2011 (DSB): # Include the process ID in the name of the temporary directory and # file, so that simultaneous invocations of this script do not trample # all over each other. #- ( $#ARGV >= 0 ) || Usage(); # Test whether we need to include config.h in the result. $need_config_h = 0; # Location of source files (makefile variable $(srcdir)). # This is most typically '.', but can be different. $srcdir = '.'; while ( $ARGV[0] =~ /^-/ ) { if ( $ARGV[0] eq '-s' ) { shift @ARGV; ( $#ARGV >= 0 ) || Usage(); $srcdir = $ARGV[0]; shift @ARGV; } else { Usage(); } } # Create a scratch directory. $tmpdir="/tmp/makeh-$$.tmp"; unless ( -d $tmpdir && -w $tmpdir ) { if ( -e $tmpdir ) { die "Temp $tmpdir exists, but is unwritable or is not a directory\n"; } mkdir $tmpdir, 0777 || die "Failed to create temporary directory $tmpdir\n"; } # Open each input file. foreach $file ( @ARGV ) { protect_copy_file( $file ); } # Open a pipe to a script (in the current directory) which runs the C # preprocessor and direct its output to a scratch file. open( CC, "| ./ast_cpp >/tmp/ast-$$.h" ) || die "Can't open pipe to C preprocessor (cpp)"; if ( $need_config_h ) { # Include this directory's config.h, unescaped, in the output. We # need to pay attention to the values in this file, but don't want # them unexpanded in the final ast.h. chomp($cwd = `pwd`); print(CC "#include \"$cwd/config.h\"\n"); } # Before including each file, write an underlined heading in the form of # C comments (with comment characters suitably protected so that they will # be passed unchanged by cpp). foreach $file ( @ARGV ) { $comment = $file; $comment =~ s|^.*/||; $comment =~ s|.h$||; print( CC "/_* " . $comment . ". *_/\n" ); $comment =~ s/./=/g; print( CC "/_* " . $comment . "= *_/\n" ); # Write #include "xxx.h" lines to cpp so that it includes (and # preprocesses) each of the temporary files created above in turn. $tmp_file = $file; $tmp_file =~ s|^.*/||; printf(CC "#include \"%s/%s\"\n", $tmpdir, $tmp_file); }; # Close the pipe to cpp. close( CC ) || die "C preprocessor (cpp) error"; # Remove the temporary directory and the files it contains. print( stderr `rm -r $tmpdir` ); # Write the output preamble. print( '#if !defined(AST_INCLUDED) #define AST_INCLUDED /* *+ * Name: * ast.h * Purpose: * Define the public C interface to the AST library. * Language: * ANSI C * Type of Module: * C header file. * Description: * This file defines the public C interface to the AST library. It contains * all the type definitions, function prototypes, macro definitions, etc. * needed to use the library. * 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 * . * Authors: * DSB: D.S. Berry (STARLINK) * RFWS: R.F. Warren-Smith (STARLINK) * {enter_new_authors_here} * History: * ' ); # Add the current date at this point. ( $sec, $min, $hour, $mday, $mon, $year ) = localtime; print( $mday, '-', ( 'JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC' )[ $mon ], '-', ( $year > 95 ? 1900 : 2000 ) + $year ); print( ' (makeh): * Original version, generated automatically from the internal header * files by the "makeh" script. * {enter_changes_here} *- */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif ' ); # Open the scratch file created above and read it. $space = 0; open( TEMP, " ) { # Remove the underscores from the protected lines and macros. s/^_#include(\s)/#include$1/; s/^_#define(\s)/#define$1/; s/___LINE__/__LINE__/g; s/___FILE__/__FILE__/g; # Also un-protect protected comments. s|/_\*|/*|g; s|\*_/|*/|g; # Convert multiple blank lines (cpp creates lots of these) into single blank # lines. if ( /^\s*$/ ) { $space = 1; } else { # Remove additional unwanted lines that cpp creates. if ( ! /^# \d+/ ) { if ( $space ) { print( "\n" ) }; $space = 0; # Output the lines we want to keep. print; } } } # Write closing output lines. print( ' #endif ' ); # Close and remove the scratch file. close( TEMP ); unlink "/tmp/ast-$$.h"; sub protect_copy_file { my $file = shift; open( INCLUDE, "$srcdir/$file" ) || die "Can't open input file " . $srcdir/$file; # Inicate we have no deferred text to write out. $total = ""; # Open an output file with the same name in the temporary directory. $tmp_file = $file; $tmp_file =~ s|^.*/||; open( TEMP, ">$tmpdir/$tmp_file" ); # Read the input file and detect "#include <...>" lines, extracting the name # of the header file being included. line: while ( ) { # Omit any config.h includes, and note that we saw this if (/^\s*\#\s*include\s+/ || /^\s*\#\s*include\s+"config.h"/) { $need_config_h = 1; next line; } if ( ( $header ) = /^\#include\s+<(.+)>/ ) { # If this system header file has already been included, ignore it and go on to # the next input line. next line if $done{ $header }++; # Otherwise, protect the #include with an underscore to prevent the file # actually being included. s/^/_/; } # Also protect "#define ..." lines, to prevent macro substitution being # performed by the C preprocessor. Do not do this to lines of the form # "#define XXX_INCLUDED" because these are still needed to determine which # AST header files get included. if ( /^\#define\s/ ) { if ( ! /^\#define\s+\w*_INCLUDED/ ) { s/^/_/ }; } # Similarly add underscores to protect standard C macros. s/__LINE__/___LINE__/g; s/__FILE__/___FILE__/g; # Some pre-processors (e.g. GCC 4.4.2) seem to simply throw away trailing # backslashes used to concatenate consecutive lines, producing two # independent lines in the output rather than one. This completely fouls # up the resulting header file. To avoid this, we concatenate such lines # explicitly, before writing them out to the temporary output file. # If the current line ends with an escaped newline, remove the escape # character and newline, and concatenate it with any previously deferred # lines. if( /^(.*)\\\s*$/ ) { $total .= $1; # If the current line does not end with an escaped newline, concatenate it # with any previously deferred lines, and write the total string out. Then # reset the total string to indicate we have no deferred text. } else { $total .= $_; print TEMP $total; $total = ""; } } # Close each file when done. close( INCLUDE ); close( TEMP ); } sub Usage { print STDERR "$0 [-s srcdir] file...\n"; exit (1); } ast-8.3.0/pcdmap.h0000664000175000017500000002701313004147321010647 00000000000000#if !defined( PCDMAP_INCLUDED ) /* Include this file only once */ #define PCDMAP_INCLUDED /* *+ * Name: * pcdmap.h * Type: * C include file. * Purpose: * Define the interface to the PcdMap class. * Invocation: * #include "pcdmap.h" * Description: * This include file defines the interface to the PcdMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The PcdMap class implements Mappings which perform pincushion * distortion. * Inheritance: * The PcdMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Disco (double) * This attribute holds the PcdMap distortion coefficient used by * the forward transformation. This coefficient is set when a * PcdMap is created, but may later be modified. The default value * is zero, which gives no distortion. For pincushion distortion, * the supplied value should be positive. For barrel distortion, it * should be negative. * * Note that the forward transformation of a PcdMap applies the * distortion corresponding to this attribute, and the inverse * transformation removes this distortion. If a PcdMap is inverted * (e.g. by using astInvert), then the forward transformation will * remove the distortion and the inverse transformation will apply * it. The distortion itself will still be given by the same value of * Disco. * PcdCen(axis) * This attribute specifies the centre of a pincushion distortion. * It takes a separate value for each axis of the PcdMap so that, for * instance, the settings "PcdCen(1)=345.0,PcdCen(2)=-104.4" specify * that the pincushion distortion is centred at values of 345.0 and * -104.4 on axes 1 and 2 of the PcdMap. The default for both axes is * zero. * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a PcdMap. * astGetAttrib * Get an attribute value for a PcdMap. * astSetAttrib * Set an attribute value for a PcdMap. * astTestAttrib * Test if an attribute value has been set for a PcdMap. * astTransform * Apply a PcdMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astClearDisco * Clear the Disco attribute value for a PcdMap. * astGetDisco * Get the Disco attribute value for a PcdMap. * astSetDisco * Set the Disco attribute value for a PcdMap. * astTestDisco * Test if a Disco attribute value has been set for a PcdMap. * astClearPcdCen * Clear the PcdCen attribute value for a PcdMap. * astGetPcdCen * Get the PcdCen attribute value for a PcdMap. * astSetPcdCen * Set the PcdCen attribute value for a PcdMap. * astTestPcdCen * Test if a PcdCen attribute value has been set for a PcdMap. * Other Class Functions: * Public: * astIsAPcdMap * Test class membership. * astPcdMap * Create a PcdMap. * * Protected: * astCheckPcdMap * Validate class membership. * astInitPcdMap * Initialise a PcdMap. * astInitPcdMapVtab * Initialise the virtual function table for the PcdMap class. * astLoadPcdMap * Load a PcdMap. * Macros: * None. * Type Definitions: * Public: * AstPcdMap * PcdMap object type. * * Protected: * AstPcdMapVtab * PcdMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 18-MAY-1999 (DSB): * Original version. * 8-JAN-2003 (DSB): * Added protected astInitPcdMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* PcdMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPcdMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double disco; /* Distortion coefficient */ double pcdcen[2]; /* Distortion centre */ } AstPcdMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPcdMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (*GetDisco)( AstPcdMap *, int * ); int (* TestDisco)( AstPcdMap *, int * ); void (* ClearDisco)( AstPcdMap *, int * ); void (* SetDisco)( AstPcdMap *, double, int * ); double (*GetPcdCen)( AstPcdMap *, int, int * ); int (* TestPcdCen)( AstPcdMap *, int, int * ); void (* ClearPcdCen)( AstPcdMap *, int, int * ); void (* SetPcdCen)( AstPcdMap *, int, double, int * ); } AstPcdMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstPcdMapGlobals { /* Define the thread-specific globals. */ char GetAttrib_Buff[ 101 ]; AstPcdMapVtab Class_Vtab; int Class_Init; } AstPcdMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(PcdMap) /* Check class membership */ astPROTO_ISA(PcdMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPcdMap *astPcdMap_( double, const double [2], const char *, int *, ...); #else AstPcdMap *astPcdMapId_( double, const double [2], const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPcdMap *astInitPcdMap_( void *, size_t, int, AstPcdMapVtab *, const char *, double, const double [2], int * ); /* Vtab initialiser. */ void astInitPcdMapVtab_( AstPcdMapVtab *, const char *, int * ); /* Loader. */ AstPcdMap *astLoadPcdMap_( void *, size_t, AstPcdMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitPcdMapGlobals_( AstPcdMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ double astGetDisco_( AstPcdMap *, int * ); int astTestDisco_( AstPcdMap *, int * ); void astClearDisco_( AstPcdMap *, int * ); void astSetDisco_( AstPcdMap *, double, int * ); double astGetPcdCen_( AstPcdMap *, int, int * ); int astTestPcdCen_( AstPcdMap *, int, int * ); void astClearPcdCen_( AstPcdMap *, int, int * ); void astSetPcdCen_( AstPcdMap *, int, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPcdMap(this) astINVOKE_CHECK(PcdMap,this,0) #define astVerifyPcdMap(this) astINVOKE_CHECK(PcdMap,this,1) /* Test class membership. */ #define astIsAPcdMap(this) astINVOKE_ISA(PcdMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astPcdMap astINVOKE(F,astPcdMap_) #else #define astPcdMap astINVOKE(F,astPcdMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPcdMap(mem,size,init,vtab,name,disco,pcdcen) \ astINVOKE(O,astInitPcdMap_(mem,size,init,vtab,name,disco,pcdcen,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPcdMapVtab(vtab,name) astINVOKE(V,astInitPcdMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPcdMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPcdMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckPcdMap to validate PcdMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearDisco(this) astINVOKE(V,astClearDisco_(astCheckPcdMap(this),STATUS_PTR)) #define astGetDisco(this) astINVOKE(V,astGetDisco_(astCheckPcdMap(this),STATUS_PTR)) #define astSetDisco(this,value) \ astINVOKE(V,astSetDisco_(astCheckPcdMap(this),value,STATUS_PTR)) #define astTestDisco(this) astINVOKE(V,astTestDisco_(astCheckPcdMap(this),STATUS_PTR)) #define astClearPcdCen(this,axis) \ astINVOKE(V,astClearPcdCen_(astCheckPcdMap(this),axis,STATUS_PTR)) #define astGetPcdCen(this,axis) \ astINVOKE(V,astGetPcdCen_(astCheckPcdMap(this),axis,STATUS_PTR)) #define astSetPcdCen(this,axis,value) \ astINVOKE(V,astSetPcdCen_(astCheckPcdMap(this),axis,value,STATUS_PTR)) #define astTestPcdCen(this,axis) \ astINVOKE(V,astTestPcdCen_(astCheckPcdMap(this),axis,STATUS_PTR)) #endif #endif ast-8.3.0/build-aux/0000775000175000017500000000000013004147574011213 500000000000000ast-8.3.0/build-aux/test-driver0000755000175000017500000001027712710131217013324 00000000000000#! /bin/sh # test-driver - basic testsuite driver script. scriptversion=2013-07-13.22; # UTC # Copyright (C) 2011-2013 Free Software Foundation, Inc. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, 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 General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # This file is maintained in Automake, please report # bugs to or send patches to # . # Make unconditional expansion of undefined variables an error. This # helps a lot in preventing typo-related bugs. set -u usage_error () { echo "$0: $*" >&2 print_usage >&2 exit 2 } print_usage () { cat <$log_file 2>&1 estatus=$? if test $enable_hard_errors = no && test $estatus -eq 99; then estatus=1 fi case $estatus:$expect_failure in 0:yes) col=$red res=XPASS recheck=yes gcopy=yes;; 0:*) col=$grn res=PASS recheck=no gcopy=no;; 77:*) col=$blu res=SKIP recheck=no gcopy=yes;; 99:*) col=$mgn res=ERROR recheck=yes gcopy=yes;; *:yes) col=$lgn res=XFAIL recheck=no gcopy=yes;; *:*) col=$red res=FAIL recheck=yes gcopy=yes;; esac # Report outcome to console. echo "${col}${res}${std}: $test_name" # Register the test result, and other relevant metadata. echo ":test-result: $res" > $trs_file echo ":global-test-result: $res" >> $trs_file echo ":recheck: $recheck" >> $trs_file echo ":copy-in-global-log: $gcopy" >> $trs_file # Local Variables: # mode: shell-script # sh-indentation: 2 # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: ast-8.3.0/build-aux/config.guess0000755000175000017500000013135512710131217013447 00000000000000#! /bin/sh # Attempt to guess a canonical system name. # Copyright 1992-2013 Free Software Foundation, Inc. timestamp='2013-11-29' # This file is free software; you can redistribute it and/or modify it # under the terms of the GNU 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 # General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, see . # # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that # program. This Exception is an additional permission under section 7 # of the GNU General Public License, version 3 ("GPLv3"). # # Originally written by Per Bothner. # # You can get the latest version of this script from: # http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD # # Please send patches with a ChangeLog entry to config-patches@gnu.org. me=`echo "$0" | sed -e 's,.*/,,'` usage="\ Usage: $0 [OPTION] Output the configuration name of the system \`$me' is run on. Operation modes: -h, --help print this help, then exit -t, --time-stamp print date of last modification, then exit -v, --version print version number, then exit Report bugs and patches to ." version="\ GNU config.guess ($timestamp) Originally written by Per Bothner. Copyright 1992-2013 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." help=" Try \`$me --help' for more information." # Parse command line while test $# -gt 0 ; do case $1 in --time-stamp | --time* | -t ) echo "$timestamp" ; exit ;; --version | -v ) echo "$version" ; exit ;; --help | --h* | -h ) echo "$usage"; exit ;; -- ) # Stop option processing shift; break ;; - ) # Use stdin as input. break ;; -* ) echo "$me: invalid option $1$help" >&2 exit 1 ;; * ) break ;; esac done if test $# != 0; then echo "$me: too many arguments$help" >&2 exit 1 fi trap 'exit 1' 1 2 15 # CC_FOR_BUILD -- compiler used by this script. Note that the use of a # compiler to aid in system detection is discouraged as it requires # temporary files to be created and, as you can see below, it is a # headache to deal with in a portable fashion. # Historically, `CC_FOR_BUILD' used to be named `HOST_CC'. We still # use `HOST_CC' if defined, but it is deprecated. # Portable tmp directory creation inspired by the Autoconf team. set_cc_for_build=' trap "exitcode=\$?; (rm -f \$tmpfiles 2>/dev/null; rmdir \$tmp 2>/dev/null) && exit \$exitcode" 0 ; trap "rm -f \$tmpfiles 2>/dev/null; rmdir \$tmp 2>/dev/null; exit 1" 1 2 13 15 ; : ${TMPDIR=/tmp} ; { tmp=`(umask 077 && mktemp -d "$TMPDIR/cgXXXXXX") 2>/dev/null` && test -n "$tmp" && test -d "$tmp" ; } || { test -n "$RANDOM" && tmp=$TMPDIR/cg$$-$RANDOM && (umask 077 && mkdir $tmp) ; } || { tmp=$TMPDIR/cg-$$ && (umask 077 && mkdir $tmp) && echo "Warning: creating insecure temp directory" >&2 ; } || { echo "$me: cannot create a temporary directory in $TMPDIR" >&2 ; exit 1 ; } ; dummy=$tmp/dummy ; tmpfiles="$dummy.c $dummy.o $dummy.rel $dummy" ; case $CC_FOR_BUILD,$HOST_CC,$CC in ,,) echo "int x;" > $dummy.c ; for c in cc gcc c89 c99 ; do if ($c -c -o $dummy.o $dummy.c) >/dev/null 2>&1 ; then CC_FOR_BUILD="$c"; break ; fi ; done ; if test x"$CC_FOR_BUILD" = x ; then CC_FOR_BUILD=no_compiler_found ; fi ;; ,,*) CC_FOR_BUILD=$CC ;; ,*,*) CC_FOR_BUILD=$HOST_CC ;; esac ; set_cc_for_build= ;' # This is needed to find uname on a Pyramid OSx when run in the BSD universe. # (ghazi@noc.rutgers.edu 1994-08-24) if (test -f /.attbin/uname) >/dev/null 2>&1 ; then PATH=$PATH:/.attbin ; export PATH fi UNAME_MACHINE=`(uname -m) 2>/dev/null` || UNAME_MACHINE=unknown UNAME_RELEASE=`(uname -r) 2>/dev/null` || UNAME_RELEASE=unknown UNAME_SYSTEM=`(uname -s) 2>/dev/null` || UNAME_SYSTEM=unknown UNAME_VERSION=`(uname -v) 2>/dev/null` || UNAME_VERSION=unknown case "${UNAME_SYSTEM}" in Linux|GNU|GNU/*) # If the system lacks a compiler, then just pick glibc. # We could probably try harder. LIBC=gnu eval $set_cc_for_build cat <<-EOF > $dummy.c #include #if defined(__UCLIBC__) LIBC=uclibc #elif defined(__dietlibc__) LIBC=dietlibc #else LIBC=gnu #endif EOF eval `$CC_FOR_BUILD -E $dummy.c 2>/dev/null | grep '^LIBC'` ;; esac # Note: order is significant - the case branches are not exclusive. case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in *:NetBSD:*:*) # NetBSD (nbsd) targets should (where applicable) match one or # more of the tuples: *-*-netbsdelf*, *-*-netbsdaout*, # *-*-netbsdecoff* and *-*-netbsd*. For targets that recently # switched to ELF, *-*-netbsd* would select the old # object file format. This provides both forward # compatibility and a consistent mechanism for selecting the # object file format. # # Note: NetBSD doesn't particularly care about the vendor # portion of the name. We always set it to "unknown". sysctl="sysctl -n hw.machine_arch" UNAME_MACHINE_ARCH=`(/sbin/$sysctl 2>/dev/null || \ /usr/sbin/$sysctl 2>/dev/null || echo unknown)` case "${UNAME_MACHINE_ARCH}" in armeb) machine=armeb-unknown ;; arm*) machine=arm-unknown ;; sh3el) machine=shl-unknown ;; sh3eb) machine=sh-unknown ;; sh5el) machine=sh5le-unknown ;; *) machine=${UNAME_MACHINE_ARCH}-unknown ;; esac # The Operating System including object format, if it has switched # to ELF recently, or will in the future. case "${UNAME_MACHINE_ARCH}" in arm*|i386|m68k|ns32k|sh3*|sparc|vax) eval $set_cc_for_build if echo __ELF__ | $CC_FOR_BUILD -E - 2>/dev/null \ | grep -q __ELF__ then # Once all utilities can be ECOFF (netbsdecoff) or a.out (netbsdaout). # Return netbsd for either. FIX? os=netbsd else os=netbsdelf fi ;; *) os=netbsd ;; esac # The OS release # Debian GNU/NetBSD machines have a different userland, and # thus, need a distinct triplet. However, they do not need # kernel version information, so it can be replaced with a # suitable tag, in the style of linux-gnu. case "${UNAME_VERSION}" in Debian*) release='-gnu' ;; *) release=`echo ${UNAME_RELEASE}|sed -e 's/[-_].*/\./'` ;; esac # Since CPU_TYPE-MANUFACTURER-KERNEL-OPERATING_SYSTEM: # contains redundant information, the shorter form: # CPU_TYPE-MANUFACTURER-OPERATING_SYSTEM is used. echo "${machine}-${os}${release}" exit ;; *:Bitrig:*:*) UNAME_MACHINE_ARCH=`arch | sed 's/Bitrig.//'` echo ${UNAME_MACHINE_ARCH}-unknown-bitrig${UNAME_RELEASE} exit ;; *:OpenBSD:*:*) UNAME_MACHINE_ARCH=`arch | sed 's/OpenBSD.//'` echo ${UNAME_MACHINE_ARCH}-unknown-openbsd${UNAME_RELEASE} exit ;; *:ekkoBSD:*:*) echo ${UNAME_MACHINE}-unknown-ekkobsd${UNAME_RELEASE} exit ;; *:SolidBSD:*:*) echo ${UNAME_MACHINE}-unknown-solidbsd${UNAME_RELEASE} exit ;; macppc:MirBSD:*:*) echo powerpc-unknown-mirbsd${UNAME_RELEASE} exit ;; *:MirBSD:*:*) echo ${UNAME_MACHINE}-unknown-mirbsd${UNAME_RELEASE} exit ;; alpha:OSF1:*:*) case $UNAME_RELEASE in *4.0) UNAME_RELEASE=`/usr/sbin/sizer -v | awk '{print $3}'` ;; *5.*) UNAME_RELEASE=`/usr/sbin/sizer -v | awk '{print $4}'` ;; esac # According to Compaq, /usr/sbin/psrinfo has been available on # OSF/1 and Tru64 systems produced since 1995. I hope that # covers most systems running today. This code pipes the CPU # types through head -n 1, so we only detect the type of CPU 0. ALPHA_CPU_TYPE=`/usr/sbin/psrinfo -v | sed -n -e 's/^ The alpha \(.*\) processor.*$/\1/p' | head -n 1` case "$ALPHA_CPU_TYPE" in "EV4 (21064)") UNAME_MACHINE="alpha" ;; "EV4.5 (21064)") UNAME_MACHINE="alpha" ;; "LCA4 (21066/21068)") UNAME_MACHINE="alpha" ;; "EV5 (21164)") UNAME_MACHINE="alphaev5" ;; "EV5.6 (21164A)") UNAME_MACHINE="alphaev56" ;; "EV5.6 (21164PC)") UNAME_MACHINE="alphapca56" ;; "EV5.7 (21164PC)") UNAME_MACHINE="alphapca57" ;; "EV6 (21264)") UNAME_MACHINE="alphaev6" ;; "EV6.7 (21264A)") UNAME_MACHINE="alphaev67" ;; "EV6.8CB (21264C)") UNAME_MACHINE="alphaev68" ;; "EV6.8AL (21264B)") UNAME_MACHINE="alphaev68" ;; "EV6.8CX (21264D)") UNAME_MACHINE="alphaev68" ;; "EV6.9A (21264/EV69A)") UNAME_MACHINE="alphaev69" ;; "EV7 (21364)") UNAME_MACHINE="alphaev7" ;; "EV7.9 (21364A)") UNAME_MACHINE="alphaev79" ;; esac # A Pn.n version is a patched version. # A Vn.n version is a released version. # A Tn.n version is a released field test version. # A Xn.n version is an unreleased experimental baselevel. # 1.2 uses "1.2" for uname -r. echo ${UNAME_MACHINE}-dec-osf`echo ${UNAME_RELEASE} | sed -e 's/^[PVTX]//' | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz'` # Reset EXIT trap before exiting to avoid spurious non-zero exit code. exitcode=$? trap '' 0 exit $exitcode ;; Alpha\ *:Windows_NT*:*) # How do we know it's Interix rather than the generic POSIX subsystem? # Should we change UNAME_MACHINE based on the output of uname instead # of the specific Alpha model? echo alpha-pc-interix exit ;; 21064:Windows_NT:50:3) echo alpha-dec-winnt3.5 exit ;; Amiga*:UNIX_System_V:4.0:*) echo m68k-unknown-sysv4 exit ;; *:[Aa]miga[Oo][Ss]:*:*) echo ${UNAME_MACHINE}-unknown-amigaos exit ;; *:[Mm]orph[Oo][Ss]:*:*) echo ${UNAME_MACHINE}-unknown-morphos exit ;; *:OS/390:*:*) echo i370-ibm-openedition exit ;; *:z/VM:*:*) echo s390-ibm-zvmoe exit ;; *:OS400:*:*) echo powerpc-ibm-os400 exit ;; arm:RISC*:1.[012]*:*|arm:riscix:1.[012]*:*) echo arm-acorn-riscix${UNAME_RELEASE} exit ;; arm*:riscos:*:*|arm*:RISCOS:*:*) echo arm-unknown-riscos exit ;; SR2?01:HI-UX/MPP:*:* | SR8000:HI-UX/MPP:*:*) echo hppa1.1-hitachi-hiuxmpp exit ;; Pyramid*:OSx*:*:* | MIS*:OSx*:*:* | MIS*:SMP_DC-OSx*:*:*) # akee@wpdis03.wpafb.af.mil (Earle F. Ake) contributed MIS and NILE. if test "`(/bin/universe) 2>/dev/null`" = att ; then echo pyramid-pyramid-sysv3 else echo pyramid-pyramid-bsd fi exit ;; NILE*:*:*:dcosx) echo pyramid-pyramid-svr4 exit ;; DRS?6000:unix:4.0:6*) echo sparc-icl-nx6 exit ;; DRS?6000:UNIX_SV:4.2*:7* | DRS?6000:isis:4.2*:7*) case `/usr/bin/uname -p` in sparc) echo sparc-icl-nx7; exit ;; esac ;; s390x:SunOS:*:*) echo ${UNAME_MACHINE}-ibm-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; sun4H:SunOS:5.*:*) echo sparc-hal-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; sun4*:SunOS:5.*:* | tadpole*:SunOS:5.*:*) echo sparc-sun-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; i86pc:AuroraUX:5.*:* | i86xen:AuroraUX:5.*:*) echo i386-pc-auroraux${UNAME_RELEASE} exit ;; i86pc:SunOS:5.*:* | i86xen:SunOS:5.*:*) eval $set_cc_for_build SUN_ARCH="i386" # If there is a compiler, see if it is configured for 64-bit objects. # Note that the Sun cc does not turn __LP64__ into 1 like gcc does. # This test works for both compilers. if [ "$CC_FOR_BUILD" != 'no_compiler_found' ]; then if (echo '#ifdef __amd64'; echo IS_64BIT_ARCH; echo '#endif') | \ (CCOPTS= $CC_FOR_BUILD -E - 2>/dev/null) | \ grep IS_64BIT_ARCH >/dev/null then SUN_ARCH="x86_64" fi fi echo ${SUN_ARCH}-pc-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; sun4*:SunOS:6*:*) # According to config.sub, this is the proper way to canonicalize # SunOS6. Hard to guess exactly what SunOS6 will be like, but # it's likely to be more like Solaris than SunOS4. echo sparc-sun-solaris3`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; sun4*:SunOS:*:*) case "`/usr/bin/arch -k`" in Series*|S4*) UNAME_RELEASE=`uname -v` ;; esac # Japanese Language versions have a version number like `4.1.3-JL'. echo sparc-sun-sunos`echo ${UNAME_RELEASE}|sed -e 's/-/_/'` exit ;; sun3*:SunOS:*:*) echo m68k-sun-sunos${UNAME_RELEASE} exit ;; sun*:*:4.2BSD:*) UNAME_RELEASE=`(sed 1q /etc/motd | awk '{print substr($5,1,3)}') 2>/dev/null` test "x${UNAME_RELEASE}" = "x" && UNAME_RELEASE=3 case "`/bin/arch`" in sun3) echo m68k-sun-sunos${UNAME_RELEASE} ;; sun4) echo sparc-sun-sunos${UNAME_RELEASE} ;; esac exit ;; aushp:SunOS:*:*) echo sparc-auspex-sunos${UNAME_RELEASE} exit ;; # The situation for MiNT is a little confusing. The machine name # can be virtually everything (everything which is not # "atarist" or "atariste" at least should have a processor # > m68000). The system name ranges from "MiNT" over "FreeMiNT" # to the lowercase version "mint" (or "freemint"). Finally # the system name "TOS" denotes a system which is actually not # MiNT. But MiNT is downward compatible to TOS, so this should # be no problem. atarist[e]:*MiNT:*:* | atarist[e]:*mint:*:* | atarist[e]:*TOS:*:*) echo m68k-atari-mint${UNAME_RELEASE} exit ;; atari*:*MiNT:*:* | atari*:*mint:*:* | atarist[e]:*TOS:*:*) echo m68k-atari-mint${UNAME_RELEASE} exit ;; *falcon*:*MiNT:*:* | *falcon*:*mint:*:* | *falcon*:*TOS:*:*) echo m68k-atari-mint${UNAME_RELEASE} exit ;; milan*:*MiNT:*:* | milan*:*mint:*:* | *milan*:*TOS:*:*) echo m68k-milan-mint${UNAME_RELEASE} exit ;; hades*:*MiNT:*:* | hades*:*mint:*:* | *hades*:*TOS:*:*) echo m68k-hades-mint${UNAME_RELEASE} exit ;; *:*MiNT:*:* | *:*mint:*:* | *:*TOS:*:*) echo m68k-unknown-mint${UNAME_RELEASE} exit ;; m68k:machten:*:*) echo m68k-apple-machten${UNAME_RELEASE} exit ;; powerpc:machten:*:*) echo powerpc-apple-machten${UNAME_RELEASE} exit ;; RISC*:Mach:*:*) echo mips-dec-mach_bsd4.3 exit ;; RISC*:ULTRIX:*:*) echo mips-dec-ultrix${UNAME_RELEASE} exit ;; VAX*:ULTRIX*:*:*) echo vax-dec-ultrix${UNAME_RELEASE} exit ;; 2020:CLIX:*:* | 2430:CLIX:*:*) echo clipper-intergraph-clix${UNAME_RELEASE} exit ;; mips:*:*:UMIPS | mips:*:*:RISCos) eval $set_cc_for_build sed 's/^ //' << EOF >$dummy.c #ifdef __cplusplus #include /* for printf() prototype */ int main (int argc, char *argv[]) { #else int main (argc, argv) int argc; char *argv[]; { #endif #if defined (host_mips) && defined (MIPSEB) #if defined (SYSTYPE_SYSV) printf ("mips-mips-riscos%ssysv\n", argv[1]); exit (0); #endif #if defined (SYSTYPE_SVR4) printf ("mips-mips-riscos%ssvr4\n", argv[1]); exit (0); #endif #if defined (SYSTYPE_BSD43) || defined(SYSTYPE_BSD) printf ("mips-mips-riscos%sbsd\n", argv[1]); exit (0); #endif #endif exit (-1); } EOF $CC_FOR_BUILD -o $dummy $dummy.c && dummyarg=`echo "${UNAME_RELEASE}" | sed -n 's/\([0-9]*\).*/\1/p'` && SYSTEM_NAME=`$dummy $dummyarg` && { echo "$SYSTEM_NAME"; exit; } echo mips-mips-riscos${UNAME_RELEASE} exit ;; Motorola:PowerMAX_OS:*:*) echo powerpc-motorola-powermax exit ;; Motorola:*:4.3:PL8-*) echo powerpc-harris-powermax exit ;; Night_Hawk:*:*:PowerMAX_OS | Synergy:PowerMAX_OS:*:*) echo powerpc-harris-powermax exit ;; Night_Hawk:Power_UNIX:*:*) echo powerpc-harris-powerunix exit ;; m88k:CX/UX:7*:*) echo m88k-harris-cxux7 exit ;; m88k:*:4*:R4*) echo m88k-motorola-sysv4 exit ;; m88k:*:3*:R3*) echo m88k-motorola-sysv3 exit ;; AViiON:dgux:*:*) # DG/UX returns AViiON for all architectures UNAME_PROCESSOR=`/usr/bin/uname -p` if [ $UNAME_PROCESSOR = mc88100 ] || [ $UNAME_PROCESSOR = mc88110 ] then if [ ${TARGET_BINARY_INTERFACE}x = m88kdguxelfx ] || \ [ ${TARGET_BINARY_INTERFACE}x = x ] then echo m88k-dg-dgux${UNAME_RELEASE} else echo m88k-dg-dguxbcs${UNAME_RELEASE} fi else echo i586-dg-dgux${UNAME_RELEASE} fi exit ;; M88*:DolphinOS:*:*) # DolphinOS (SVR3) echo m88k-dolphin-sysv3 exit ;; M88*:*:R3*:*) # Delta 88k system running SVR3 echo m88k-motorola-sysv3 exit ;; XD88*:*:*:*) # Tektronix XD88 system running UTekV (SVR3) echo m88k-tektronix-sysv3 exit ;; Tek43[0-9][0-9]:UTek:*:*) # Tektronix 4300 system running UTek (BSD) echo m68k-tektronix-bsd exit ;; *:IRIX*:*:*) echo mips-sgi-irix`echo ${UNAME_RELEASE}|sed -e 's/-/_/g'` exit ;; ????????:AIX?:[12].1:2) # AIX 2.2.1 or AIX 2.1.1 is RT/PC AIX. echo romp-ibm-aix # uname -m gives an 8 hex-code CPU id exit ;; # Note that: echo "'`uname -s`'" gives 'AIX ' i*86:AIX:*:*) echo i386-ibm-aix exit ;; ia64:AIX:*:*) if [ -x /usr/bin/oslevel ] ; then IBM_REV=`/usr/bin/oslevel` else IBM_REV=${UNAME_VERSION}.${UNAME_RELEASE} fi echo ${UNAME_MACHINE}-ibm-aix${IBM_REV} exit ;; *:AIX:2:3) if grep bos325 /usr/include/stdio.h >/dev/null 2>&1; then eval $set_cc_for_build sed 's/^ //' << EOF >$dummy.c #include main() { if (!__power_pc()) exit(1); puts("powerpc-ibm-aix3.2.5"); exit(0); } EOF if $CC_FOR_BUILD -o $dummy $dummy.c && SYSTEM_NAME=`$dummy` then echo "$SYSTEM_NAME" else echo rs6000-ibm-aix3.2.5 fi elif grep bos324 /usr/include/stdio.h >/dev/null 2>&1; then echo rs6000-ibm-aix3.2.4 else echo rs6000-ibm-aix3.2 fi exit ;; *:AIX:*:[4567]) IBM_CPU_ID=`/usr/sbin/lsdev -C -c processor -S available | sed 1q | awk '{ print $1 }'` if /usr/sbin/lsattr -El ${IBM_CPU_ID} | grep ' POWER' >/dev/null 2>&1; then IBM_ARCH=rs6000 else IBM_ARCH=powerpc fi if [ -x /usr/bin/oslevel ] ; then IBM_REV=`/usr/bin/oslevel` else IBM_REV=${UNAME_VERSION}.${UNAME_RELEASE} fi echo ${IBM_ARCH}-ibm-aix${IBM_REV} exit ;; *:AIX:*:*) echo rs6000-ibm-aix exit ;; ibmrt:4.4BSD:*|romp-ibm:BSD:*) echo romp-ibm-bsd4.4 exit ;; ibmrt:*BSD:*|romp-ibm:BSD:*) # covers RT/PC BSD and echo romp-ibm-bsd${UNAME_RELEASE} # 4.3 with uname added to exit ;; # report: romp-ibm BSD 4.3 *:BOSX:*:*) echo rs6000-bull-bosx exit ;; DPX/2?00:B.O.S.:*:*) echo m68k-bull-sysv3 exit ;; 9000/[34]??:4.3bsd:1.*:*) echo m68k-hp-bsd exit ;; hp300:4.4BSD:*:* | 9000/[34]??:4.3bsd:2.*:*) echo m68k-hp-bsd4.4 exit ;; 9000/[34678]??:HP-UX:*:*) HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` case "${UNAME_MACHINE}" in 9000/31? ) HP_ARCH=m68000 ;; 9000/[34]?? ) HP_ARCH=m68k ;; 9000/[678][0-9][0-9]) if [ -x /usr/bin/getconf ]; then sc_cpu_version=`/usr/bin/getconf SC_CPU_VERSION 2>/dev/null` sc_kernel_bits=`/usr/bin/getconf SC_KERNEL_BITS 2>/dev/null` case "${sc_cpu_version}" in 523) HP_ARCH="hppa1.0" ;; # CPU_PA_RISC1_0 528) HP_ARCH="hppa1.1" ;; # CPU_PA_RISC1_1 532) # CPU_PA_RISC2_0 case "${sc_kernel_bits}" in 32) HP_ARCH="hppa2.0n" ;; 64) HP_ARCH="hppa2.0w" ;; '') HP_ARCH="hppa2.0" ;; # HP-UX 10.20 esac ;; esac fi if [ "${HP_ARCH}" = "" ]; then eval $set_cc_for_build sed 's/^ //' << EOF >$dummy.c #define _HPUX_SOURCE #include #include int main () { #if defined(_SC_KERNEL_BITS) long bits = sysconf(_SC_KERNEL_BITS); #endif long cpu = sysconf (_SC_CPU_VERSION); switch (cpu) { case CPU_PA_RISC1_0: puts ("hppa1.0"); break; case CPU_PA_RISC1_1: puts ("hppa1.1"); break; case CPU_PA_RISC2_0: #if defined(_SC_KERNEL_BITS) switch (bits) { case 64: puts ("hppa2.0w"); break; case 32: puts ("hppa2.0n"); break; default: puts ("hppa2.0"); break; } break; #else /* !defined(_SC_KERNEL_BITS) */ puts ("hppa2.0"); break; #endif default: puts ("hppa1.0"); break; } exit (0); } EOF (CCOPTS= $CC_FOR_BUILD -o $dummy $dummy.c 2>/dev/null) && HP_ARCH=`$dummy` test -z "$HP_ARCH" && HP_ARCH=hppa fi ;; esac if [ ${HP_ARCH} = "hppa2.0w" ] then eval $set_cc_for_build # hppa2.0w-hp-hpux* has a 64-bit kernel and a compiler generating # 32-bit code. hppa64-hp-hpux* has the same kernel and a compiler # generating 64-bit code. GNU and HP use different nomenclature: # # $ CC_FOR_BUILD=cc ./config.guess # => hppa2.0w-hp-hpux11.23 # $ CC_FOR_BUILD="cc +DA2.0w" ./config.guess # => hppa64-hp-hpux11.23 if echo __LP64__ | (CCOPTS= $CC_FOR_BUILD -E - 2>/dev/null) | grep -q __LP64__ then HP_ARCH="hppa2.0w" else HP_ARCH="hppa64" fi fi echo ${HP_ARCH}-hp-hpux${HPUX_REV} exit ;; ia64:HP-UX:*:*) HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'` echo ia64-hp-hpux${HPUX_REV} exit ;; 3050*:HI-UX:*:*) eval $set_cc_for_build sed 's/^ //' << EOF >$dummy.c #include int main () { long cpu = sysconf (_SC_CPU_VERSION); /* The order matters, because CPU_IS_HP_MC68K erroneously returns true for CPU_PA_RISC1_0. CPU_IS_PA_RISC returns correct results, however. */ if (CPU_IS_PA_RISC (cpu)) { switch (cpu) { case CPU_PA_RISC1_0: puts ("hppa1.0-hitachi-hiuxwe2"); break; case CPU_PA_RISC1_1: puts ("hppa1.1-hitachi-hiuxwe2"); break; case CPU_PA_RISC2_0: puts ("hppa2.0-hitachi-hiuxwe2"); break; default: puts ("hppa-hitachi-hiuxwe2"); break; } } else if (CPU_IS_HP_MC68K (cpu)) puts ("m68k-hitachi-hiuxwe2"); else puts ("unknown-hitachi-hiuxwe2"); exit (0); } EOF $CC_FOR_BUILD -o $dummy $dummy.c && SYSTEM_NAME=`$dummy` && { echo "$SYSTEM_NAME"; exit; } echo unknown-hitachi-hiuxwe2 exit ;; 9000/7??:4.3bsd:*:* | 9000/8?[79]:4.3bsd:*:* ) echo hppa1.1-hp-bsd exit ;; 9000/8??:4.3bsd:*:*) echo hppa1.0-hp-bsd exit ;; *9??*:MPE/iX:*:* | *3000*:MPE/iX:*:*) echo hppa1.0-hp-mpeix exit ;; hp7??:OSF1:*:* | hp8?[79]:OSF1:*:* ) echo hppa1.1-hp-osf exit ;; hp8??:OSF1:*:*) echo hppa1.0-hp-osf exit ;; i*86:OSF1:*:*) if [ -x /usr/sbin/sysversion ] ; then echo ${UNAME_MACHINE}-unknown-osf1mk else echo ${UNAME_MACHINE}-unknown-osf1 fi exit ;; parisc*:Lites*:*:*) echo hppa1.1-hp-lites exit ;; C1*:ConvexOS:*:* | convex:ConvexOS:C1*:*) echo c1-convex-bsd exit ;; C2*:ConvexOS:*:* | convex:ConvexOS:C2*:*) if getsysinfo -f scalar_acc then echo c32-convex-bsd else echo c2-convex-bsd fi exit ;; C34*:ConvexOS:*:* | convex:ConvexOS:C34*:*) echo c34-convex-bsd exit ;; C38*:ConvexOS:*:* | convex:ConvexOS:C38*:*) echo c38-convex-bsd exit ;; C4*:ConvexOS:*:* | convex:ConvexOS:C4*:*) echo c4-convex-bsd exit ;; CRAY*Y-MP:*:*:*) echo ymp-cray-unicos${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit ;; CRAY*[A-Z]90:*:*:*) echo ${UNAME_MACHINE}-cray-unicos${UNAME_RELEASE} \ | sed -e 's/CRAY.*\([A-Z]90\)/\1/' \ -e y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/ \ -e 's/\.[^.]*$/.X/' exit ;; CRAY*TS:*:*:*) echo t90-cray-unicos${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit ;; CRAY*T3E:*:*:*) echo alphaev5-cray-unicosmk${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit ;; CRAY*SV1:*:*:*) echo sv1-cray-unicos${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit ;; *:UNICOS/mp:*:*) echo craynv-cray-unicosmp${UNAME_RELEASE} | sed -e 's/\.[^.]*$/.X/' exit ;; F30[01]:UNIX_System_V:*:* | F700:UNIX_System_V:*:*) FUJITSU_PROC=`uname -m | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz'` FUJITSU_SYS=`uname -p | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz' | sed -e 's/\///'` FUJITSU_REL=`echo ${UNAME_RELEASE} | sed -e 's/ /_/'` echo "${FUJITSU_PROC}-fujitsu-${FUJITSU_SYS}${FUJITSU_REL}" exit ;; 5000:UNIX_System_V:4.*:*) FUJITSU_SYS=`uname -p | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz' | sed -e 's/\///'` FUJITSU_REL=`echo ${UNAME_RELEASE} | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz' | sed -e 's/ /_/'` echo "sparc-fujitsu-${FUJITSU_SYS}${FUJITSU_REL}" exit ;; i*86:BSD/386:*:* | i*86:BSD/OS:*:* | *:Ascend\ Embedded/OS:*:*) echo ${UNAME_MACHINE}-pc-bsdi${UNAME_RELEASE} exit ;; sparc*:BSD/OS:*:*) echo sparc-unknown-bsdi${UNAME_RELEASE} exit ;; *:BSD/OS:*:*) echo ${UNAME_MACHINE}-unknown-bsdi${UNAME_RELEASE} exit ;; *:FreeBSD:*:*) UNAME_PROCESSOR=`/usr/bin/uname -p` case ${UNAME_PROCESSOR} in amd64) echo x86_64-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;; *) echo ${UNAME_PROCESSOR}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;; esac exit ;; i*:CYGWIN*:*) echo ${UNAME_MACHINE}-pc-cygwin exit ;; *:MINGW64*:*) echo ${UNAME_MACHINE}-pc-mingw64 exit ;; *:MINGW*:*) echo ${UNAME_MACHINE}-pc-mingw32 exit ;; i*:MSYS*:*) echo ${UNAME_MACHINE}-pc-msys exit ;; i*:windows32*:*) # uname -m includes "-pc" on this system. echo ${UNAME_MACHINE}-mingw32 exit ;; i*:PW*:*) echo ${UNAME_MACHINE}-pc-pw32 exit ;; *:Interix*:*) case ${UNAME_MACHINE} in x86) echo i586-pc-interix${UNAME_RELEASE} exit ;; authenticamd | genuineintel | EM64T) echo x86_64-unknown-interix${UNAME_RELEASE} exit ;; IA64) echo ia64-unknown-interix${UNAME_RELEASE} exit ;; esac ;; [345]86:Windows_95:* | [345]86:Windows_98:* | [345]86:Windows_NT:*) echo i${UNAME_MACHINE}-pc-mks exit ;; 8664:Windows_NT:*) echo x86_64-pc-mks exit ;; i*:Windows_NT*:* | Pentium*:Windows_NT*:*) # How do we know it's Interix rather than the generic POSIX subsystem? # It also conflicts with pre-2.0 versions of AT&T UWIN. Should we # UNAME_MACHINE based on the output of uname instead of i386? echo i586-pc-interix exit ;; i*:UWIN*:*) echo ${UNAME_MACHINE}-pc-uwin exit ;; amd64:CYGWIN*:*:* | x86_64:CYGWIN*:*:*) echo x86_64-unknown-cygwin exit ;; p*:CYGWIN*:*) echo powerpcle-unknown-cygwin exit ;; prep*:SunOS:5.*:*) echo powerpcle-unknown-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'` exit ;; *:GNU:*:*) # the GNU system echo `echo ${UNAME_MACHINE}|sed -e 's,[-/].*$,,'`-unknown-${LIBC}`echo ${UNAME_RELEASE}|sed -e 's,/.*$,,'` exit ;; *:GNU/*:*:*) # other systems with GNU libc and userland echo ${UNAME_MACHINE}-unknown-`echo ${UNAME_SYSTEM} | sed 's,^[^/]*/,,' | tr '[A-Z]' '[a-z]'``echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'`-${LIBC} exit ;; i*86:Minix:*:*) echo ${UNAME_MACHINE}-pc-minix exit ;; aarch64:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; aarch64_be:Linux:*:*) UNAME_MACHINE=aarch64_be echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; alpha:Linux:*:*) case `sed -n '/^cpu model/s/^.*: \(.*\)/\1/p' < /proc/cpuinfo` in EV5) UNAME_MACHINE=alphaev5 ;; EV56) UNAME_MACHINE=alphaev56 ;; PCA56) UNAME_MACHINE=alphapca56 ;; PCA57) UNAME_MACHINE=alphapca56 ;; EV6) UNAME_MACHINE=alphaev6 ;; EV67) UNAME_MACHINE=alphaev67 ;; EV68*) UNAME_MACHINE=alphaev68 ;; esac objdump --private-headers /bin/sh | grep -q ld.so.1 if test "$?" = 0 ; then LIBC="gnulibc1" ; fi echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; arc:Linux:*:* | arceb:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; arm*:Linux:*:*) eval $set_cc_for_build if echo __ARM_EABI__ | $CC_FOR_BUILD -E - 2>/dev/null \ | grep -q __ARM_EABI__ then echo ${UNAME_MACHINE}-unknown-linux-${LIBC} else if echo __ARM_PCS_VFP | $CC_FOR_BUILD -E - 2>/dev/null \ | grep -q __ARM_PCS_VFP then echo ${UNAME_MACHINE}-unknown-linux-${LIBC}eabi else echo ${UNAME_MACHINE}-unknown-linux-${LIBC}eabihf fi fi exit ;; avr32*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; cris:Linux:*:*) echo ${UNAME_MACHINE}-axis-linux-${LIBC} exit ;; crisv32:Linux:*:*) echo ${UNAME_MACHINE}-axis-linux-${LIBC} exit ;; frv:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; hexagon:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; i*86:Linux:*:*) echo ${UNAME_MACHINE}-pc-linux-${LIBC} exit ;; ia64:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; m32r*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; m68*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; mips:Linux:*:* | mips64:Linux:*:*) eval $set_cc_for_build sed 's/^ //' << EOF >$dummy.c #undef CPU #undef ${UNAME_MACHINE} #undef ${UNAME_MACHINE}el #if defined(__MIPSEL__) || defined(__MIPSEL) || defined(_MIPSEL) || defined(MIPSEL) CPU=${UNAME_MACHINE}el #else #if defined(__MIPSEB__) || defined(__MIPSEB) || defined(_MIPSEB) || defined(MIPSEB) CPU=${UNAME_MACHINE} #else CPU= #endif #endif EOF eval `$CC_FOR_BUILD -E $dummy.c 2>/dev/null | grep '^CPU'` test x"${CPU}" != x && { echo "${CPU}-unknown-linux-${LIBC}"; exit; } ;; or1k:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; or32:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; padre:Linux:*:*) echo sparc-unknown-linux-${LIBC} exit ;; parisc64:Linux:*:* | hppa64:Linux:*:*) echo hppa64-unknown-linux-${LIBC} exit ;; parisc:Linux:*:* | hppa:Linux:*:*) # Look for CPU level case `grep '^cpu[^a-z]*:' /proc/cpuinfo 2>/dev/null | cut -d' ' -f2` in PA7*) echo hppa1.1-unknown-linux-${LIBC} ;; PA8*) echo hppa2.0-unknown-linux-${LIBC} ;; *) echo hppa-unknown-linux-${LIBC} ;; esac exit ;; ppc64:Linux:*:*) echo powerpc64-unknown-linux-${LIBC} exit ;; ppc:Linux:*:*) echo powerpc-unknown-linux-${LIBC} exit ;; ppc64le:Linux:*:*) echo powerpc64le-unknown-linux-${LIBC} exit ;; ppcle:Linux:*:*) echo powerpcle-unknown-linux-${LIBC} exit ;; s390:Linux:*:* | s390x:Linux:*:*) echo ${UNAME_MACHINE}-ibm-linux-${LIBC} exit ;; sh64*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; sh*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; sparc:Linux:*:* | sparc64:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; tile*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; vax:Linux:*:*) echo ${UNAME_MACHINE}-dec-linux-${LIBC} exit ;; x86_64:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; xtensa*:Linux:*:*) echo ${UNAME_MACHINE}-unknown-linux-${LIBC} exit ;; i*86:DYNIX/ptx:4*:*) # ptx 4.0 does uname -s correctly, with DYNIX/ptx in there. # earlier versions are messed up and put the nodename in both # sysname and nodename. echo i386-sequent-sysv4 exit ;; i*86:UNIX_SV:4.2MP:2.*) # Unixware is an offshoot of SVR4, but it has its own version # number series starting with 2... # I am not positive that other SVR4 systems won't match this, # I just have to hope. -- rms. # Use sysv4.2uw... so that sysv4* matches it. echo ${UNAME_MACHINE}-pc-sysv4.2uw${UNAME_VERSION} exit ;; i*86:OS/2:*:*) # If we were able to find `uname', then EMX Unix compatibility # is probably installed. echo ${UNAME_MACHINE}-pc-os2-emx exit ;; i*86:XTS-300:*:STOP) echo ${UNAME_MACHINE}-unknown-stop exit ;; i*86:atheos:*:*) echo ${UNAME_MACHINE}-unknown-atheos exit ;; i*86:syllable:*:*) echo ${UNAME_MACHINE}-pc-syllable exit ;; i*86:LynxOS:2.*:* | i*86:LynxOS:3.[01]*:* | i*86:LynxOS:4.[02]*:*) echo i386-unknown-lynxos${UNAME_RELEASE} exit ;; i*86:*DOS:*:*) echo ${UNAME_MACHINE}-pc-msdosdjgpp exit ;; i*86:*:4.*:* | i*86:SYSTEM_V:4.*:*) UNAME_REL=`echo ${UNAME_RELEASE} | sed 's/\/MP$//'` if grep Novell /usr/include/link.h >/dev/null 2>/dev/null; then echo ${UNAME_MACHINE}-univel-sysv${UNAME_REL} else echo ${UNAME_MACHINE}-pc-sysv${UNAME_REL} fi exit ;; i*86:*:5:[678]*) # UnixWare 7.x, OpenUNIX and OpenServer 6. case `/bin/uname -X | grep "^Machine"` in *486*) UNAME_MACHINE=i486 ;; *Pentium) UNAME_MACHINE=i586 ;; *Pent*|*Celeron) UNAME_MACHINE=i686 ;; esac echo ${UNAME_MACHINE}-unknown-sysv${UNAME_RELEASE}${UNAME_SYSTEM}${UNAME_VERSION} exit ;; i*86:*:3.2:*) if test -f /usr/options/cb.name; then UNAME_REL=`sed -n 's/.*Version //p' /dev/null >/dev/null ; then UNAME_REL=`(/bin/uname -X|grep Release|sed -e 's/.*= //')` (/bin/uname -X|grep i80486 >/dev/null) && UNAME_MACHINE=i486 (/bin/uname -X|grep '^Machine.*Pentium' >/dev/null) \ && UNAME_MACHINE=i586 (/bin/uname -X|grep '^Machine.*Pent *II' >/dev/null) \ && UNAME_MACHINE=i686 (/bin/uname -X|grep '^Machine.*Pentium Pro' >/dev/null) \ && UNAME_MACHINE=i686 echo ${UNAME_MACHINE}-pc-sco$UNAME_REL else echo ${UNAME_MACHINE}-pc-sysv32 fi exit ;; pc:*:*:*) # Left here for compatibility: # uname -m prints for DJGPP always 'pc', but it prints nothing about # the processor, so we play safe by assuming i586. # Note: whatever this is, it MUST be the same as what config.sub # prints for the "djgpp" host, or else GDB configury will decide that # this is a cross-build. echo i586-pc-msdosdjgpp exit ;; Intel:Mach:3*:*) echo i386-pc-mach3 exit ;; paragon:*:*:*) echo i860-intel-osf1 exit ;; i860:*:4.*:*) # i860-SVR4 if grep Stardent /usr/include/sys/uadmin.h >/dev/null 2>&1 ; then echo i860-stardent-sysv${UNAME_RELEASE} # Stardent Vistra i860-SVR4 else # Add other i860-SVR4 vendors below as they are discovered. echo i860-unknown-sysv${UNAME_RELEASE} # Unknown i860-SVR4 fi exit ;; mini*:CTIX:SYS*5:*) # "miniframe" echo m68010-convergent-sysv exit ;; mc68k:UNIX:SYSTEM5:3.51m) echo m68k-convergent-sysv exit ;; M680?0:D-NIX:5.3:*) echo m68k-diab-dnix exit ;; M68*:*:R3V[5678]*:*) test -r /sysV68 && { echo 'm68k-motorola-sysv'; exit; } ;; 3[345]??:*:4.0:3.0 | 3[34]??A:*:4.0:3.0 | 3[34]??,*:*:4.0:3.0 | 3[34]??/*:*:4.0:3.0 | 4400:*:4.0:3.0 | 4850:*:4.0:3.0 | SKA40:*:4.0:3.0 | SDS2:*:4.0:3.0 | SHG2:*:4.0:3.0 | S7501*:*:4.0:3.0) OS_REL='' test -r /etc/.relid \ && OS_REL=.`sed -n 's/[^ ]* [^ ]* \([0-9][0-9]\).*/\1/p' < /etc/.relid` /bin/uname -p 2>/dev/null | grep 86 >/dev/null \ && { echo i486-ncr-sysv4.3${OS_REL}; exit; } /bin/uname -p 2>/dev/null | /bin/grep entium >/dev/null \ && { echo i586-ncr-sysv4.3${OS_REL}; exit; } ;; 3[34]??:*:4.0:* | 3[34]??,*:*:4.0:*) /bin/uname -p 2>/dev/null | grep 86 >/dev/null \ && { echo i486-ncr-sysv4; exit; } ;; NCR*:*:4.2:* | MPRAS*:*:4.2:*) OS_REL='.3' test -r /etc/.relid \ && OS_REL=.`sed -n 's/[^ ]* [^ ]* \([0-9][0-9]\).*/\1/p' < /etc/.relid` /bin/uname -p 2>/dev/null | grep 86 >/dev/null \ && { echo i486-ncr-sysv4.3${OS_REL}; exit; } /bin/uname -p 2>/dev/null | /bin/grep entium >/dev/null \ && { echo i586-ncr-sysv4.3${OS_REL}; exit; } /bin/uname -p 2>/dev/null | /bin/grep pteron >/dev/null \ && { echo i586-ncr-sysv4.3${OS_REL}; exit; } ;; m68*:LynxOS:2.*:* | m68*:LynxOS:3.0*:*) echo m68k-unknown-lynxos${UNAME_RELEASE} exit ;; mc68030:UNIX_System_V:4.*:*) echo m68k-atari-sysv4 exit ;; TSUNAMI:LynxOS:2.*:*) echo sparc-unknown-lynxos${UNAME_RELEASE} exit ;; rs6000:LynxOS:2.*:*) echo rs6000-unknown-lynxos${UNAME_RELEASE} exit ;; PowerPC:LynxOS:2.*:* | PowerPC:LynxOS:3.[01]*:* | PowerPC:LynxOS:4.[02]*:*) echo powerpc-unknown-lynxos${UNAME_RELEASE} exit ;; SM[BE]S:UNIX_SV:*:*) echo mips-dde-sysv${UNAME_RELEASE} exit ;; RM*:ReliantUNIX-*:*:*) echo mips-sni-sysv4 exit ;; RM*:SINIX-*:*:*) echo mips-sni-sysv4 exit ;; *:SINIX-*:*:*) if uname -p 2>/dev/null >/dev/null ; then UNAME_MACHINE=`(uname -p) 2>/dev/null` echo ${UNAME_MACHINE}-sni-sysv4 else echo ns32k-sni-sysv fi exit ;; PENTIUM:*:4.0*:*) # Unisys `ClearPath HMP IX 4000' SVR4/MP effort # says echo i586-unisys-sysv4 exit ;; *:UNIX_System_V:4*:FTX*) # From Gerald Hewes . # How about differentiating between stratus architectures? -djm echo hppa1.1-stratus-sysv4 exit ;; *:*:*:FTX*) # From seanf@swdc.stratus.com. echo i860-stratus-sysv4 exit ;; i*86:VOS:*:*) # From Paul.Green@stratus.com. echo ${UNAME_MACHINE}-stratus-vos exit ;; *:VOS:*:*) # From Paul.Green@stratus.com. echo hppa1.1-stratus-vos exit ;; mc68*:A/UX:*:*) echo m68k-apple-aux${UNAME_RELEASE} exit ;; news*:NEWS-OS:6*:*) echo mips-sony-newsos6 exit ;; R[34]000:*System_V*:*:* | R4000:UNIX_SYSV:*:* | R*000:UNIX_SV:*:*) if [ -d /usr/nec ]; then echo mips-nec-sysv${UNAME_RELEASE} else echo mips-unknown-sysv${UNAME_RELEASE} fi exit ;; BeBox:BeOS:*:*) # BeOS running on hardware made by Be, PPC only. echo powerpc-be-beos exit ;; BeMac:BeOS:*:*) # BeOS running on Mac or Mac clone, PPC only. echo powerpc-apple-beos exit ;; BePC:BeOS:*:*) # BeOS running on Intel PC compatible. echo i586-pc-beos exit ;; BePC:Haiku:*:*) # Haiku running on Intel PC compatible. echo i586-pc-haiku exit ;; x86_64:Haiku:*:*) echo x86_64-unknown-haiku exit ;; SX-4:SUPER-UX:*:*) echo sx4-nec-superux${UNAME_RELEASE} exit ;; SX-5:SUPER-UX:*:*) echo sx5-nec-superux${UNAME_RELEASE} exit ;; SX-6:SUPER-UX:*:*) echo sx6-nec-superux${UNAME_RELEASE} exit ;; SX-7:SUPER-UX:*:*) echo sx7-nec-superux${UNAME_RELEASE} exit ;; SX-8:SUPER-UX:*:*) echo sx8-nec-superux${UNAME_RELEASE} exit ;; SX-8R:SUPER-UX:*:*) echo sx8r-nec-superux${UNAME_RELEASE} exit ;; Power*:Rhapsody:*:*) echo powerpc-apple-rhapsody${UNAME_RELEASE} exit ;; *:Rhapsody:*:*) echo ${UNAME_MACHINE}-apple-rhapsody${UNAME_RELEASE} exit ;; *:Darwin:*:*) UNAME_PROCESSOR=`uname -p` || UNAME_PROCESSOR=unknown eval $set_cc_for_build if test "$UNAME_PROCESSOR" = unknown ; then UNAME_PROCESSOR=powerpc fi if test `echo "$UNAME_RELEASE" | sed -e 's/\..*//'` -le 10 ; then if [ "$CC_FOR_BUILD" != 'no_compiler_found' ]; then if (echo '#ifdef __LP64__'; echo IS_64BIT_ARCH; echo '#endif') | \ (CCOPTS= $CC_FOR_BUILD -E - 2>/dev/null) | \ grep IS_64BIT_ARCH >/dev/null then case $UNAME_PROCESSOR in i386) UNAME_PROCESSOR=x86_64 ;; powerpc) UNAME_PROCESSOR=powerpc64 ;; esac fi fi elif test "$UNAME_PROCESSOR" = i386 ; then # Avoid executing cc on OS X 10.9, as it ships with a stub # that puts up a graphical alert prompting to install # developer tools. Any system running Mac OS X 10.7 or # later (Darwin 11 and later) is required to have a 64-bit # processor. This is not true of the ARM version of Darwin # that Apple uses in portable devices. UNAME_PROCESSOR=x86_64 fi echo ${UNAME_PROCESSOR}-apple-darwin${UNAME_RELEASE} exit ;; *:procnto*:*:* | *:QNX:[0123456789]*:*) UNAME_PROCESSOR=`uname -p` if test "$UNAME_PROCESSOR" = "x86"; then UNAME_PROCESSOR=i386 UNAME_MACHINE=pc fi echo ${UNAME_PROCESSOR}-${UNAME_MACHINE}-nto-qnx${UNAME_RELEASE} exit ;; *:QNX:*:4*) echo i386-pc-qnx exit ;; NEO-?:NONSTOP_KERNEL:*:*) echo neo-tandem-nsk${UNAME_RELEASE} exit ;; NSE-*:NONSTOP_KERNEL:*:*) echo nse-tandem-nsk${UNAME_RELEASE} exit ;; NSR-?:NONSTOP_KERNEL:*:*) echo nsr-tandem-nsk${UNAME_RELEASE} exit ;; *:NonStop-UX:*:*) echo mips-compaq-nonstopux exit ;; BS2000:POSIX*:*:*) echo bs2000-siemens-sysv exit ;; DS/*:UNIX_System_V:*:*) echo ${UNAME_MACHINE}-${UNAME_SYSTEM}-${UNAME_RELEASE} exit ;; *:Plan9:*:*) # "uname -m" is not consistent, so use $cputype instead. 386 # is converted to i386 for consistency with other x86 # operating systems. if test "$cputype" = "386"; then UNAME_MACHINE=i386 else UNAME_MACHINE="$cputype" fi echo ${UNAME_MACHINE}-unknown-plan9 exit ;; *:TOPS-10:*:*) echo pdp10-unknown-tops10 exit ;; *:TENEX:*:*) echo pdp10-unknown-tenex exit ;; KS10:TOPS-20:*:* | KL10:TOPS-20:*:* | TYPE4:TOPS-20:*:*) echo pdp10-dec-tops20 exit ;; XKL-1:TOPS-20:*:* | TYPE5:TOPS-20:*:*) echo pdp10-xkl-tops20 exit ;; *:TOPS-20:*:*) echo pdp10-unknown-tops20 exit ;; *:ITS:*:*) echo pdp10-unknown-its exit ;; SEI:*:*:SEIUX) echo mips-sei-seiux${UNAME_RELEASE} exit ;; *:DragonFly:*:*) echo ${UNAME_MACHINE}-unknown-dragonfly`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` exit ;; *:*VMS:*:*) UNAME_MACHINE=`(uname -p) 2>/dev/null` case "${UNAME_MACHINE}" in A*) echo alpha-dec-vms ; exit ;; I*) echo ia64-dec-vms ; exit ;; V*) echo vax-dec-vms ; exit ;; esac ;; *:XENIX:*:SysV) echo i386-pc-xenix exit ;; i*86:skyos:*:*) echo ${UNAME_MACHINE}-pc-skyos`echo ${UNAME_RELEASE}` | sed -e 's/ .*$//' exit ;; i*86:rdos:*:*) echo ${UNAME_MACHINE}-pc-rdos exit ;; i*86:AROS:*:*) echo ${UNAME_MACHINE}-pc-aros exit ;; x86_64:VMkernel:*:*) echo ${UNAME_MACHINE}-unknown-esx exit ;; esac eval $set_cc_for_build cat >$dummy.c < # include #endif main () { #if defined (sony) #if defined (MIPSEB) /* BFD wants "bsd" instead of "newsos". Perhaps BFD should be changed, I don't know.... */ printf ("mips-sony-bsd\n"); exit (0); #else #include printf ("m68k-sony-newsos%s\n", #ifdef NEWSOS4 "4" #else "" #endif ); exit (0); #endif #endif #if defined (__arm) && defined (__acorn) && defined (__unix) printf ("arm-acorn-riscix\n"); exit (0); #endif #if defined (hp300) && !defined (hpux) printf ("m68k-hp-bsd\n"); exit (0); #endif #if defined (NeXT) #if !defined (__ARCHITECTURE__) #define __ARCHITECTURE__ "m68k" #endif int version; version=`(hostinfo | sed -n 's/.*NeXT Mach \([0-9]*\).*/\1/p') 2>/dev/null`; if (version < 4) printf ("%s-next-nextstep%d\n", __ARCHITECTURE__, version); else printf ("%s-next-openstep%d\n", __ARCHITECTURE__, version); exit (0); #endif #if defined (MULTIMAX) || defined (n16) #if defined (UMAXV) printf ("ns32k-encore-sysv\n"); exit (0); #else #if defined (CMU) printf ("ns32k-encore-mach\n"); exit (0); #else printf ("ns32k-encore-bsd\n"); exit (0); #endif #endif #endif #if defined (__386BSD__) printf ("i386-pc-bsd\n"); exit (0); #endif #if defined (sequent) #if defined (i386) printf ("i386-sequent-dynix\n"); exit (0); #endif #if defined (ns32000) printf ("ns32k-sequent-dynix\n"); exit (0); #endif #endif #if defined (_SEQUENT_) struct utsname un; uname(&un); if (strncmp(un.version, "V2", 2) == 0) { printf ("i386-sequent-ptx2\n"); exit (0); } if (strncmp(un.version, "V1", 2) == 0) { /* XXX is V1 correct? */ printf ("i386-sequent-ptx1\n"); exit (0); } printf ("i386-sequent-ptx\n"); exit (0); #endif #if defined (vax) # if !defined (ultrix) # include # if defined (BSD) # if BSD == 43 printf ("vax-dec-bsd4.3\n"); exit (0); # else # if BSD == 199006 printf ("vax-dec-bsd4.3reno\n"); exit (0); # else printf ("vax-dec-bsd\n"); exit (0); # endif # endif # else printf ("vax-dec-bsd\n"); exit (0); # endif # else printf ("vax-dec-ultrix\n"); exit (0); # endif #endif #if defined (alliant) && defined (i860) printf ("i860-alliant-bsd\n"); exit (0); #endif exit (1); } EOF $CC_FOR_BUILD -o $dummy $dummy.c 2>/dev/null && SYSTEM_NAME=`$dummy` && { echo "$SYSTEM_NAME"; exit; } # Apollos put the system type in the environment. test -d /usr/apollo && { echo ${ISP}-apollo-${SYSTYPE}; exit; } # Convex versions that predate uname can use getsysinfo(1) if [ -x /usr/convex/getsysinfo ] then case `getsysinfo -f cpu_type` in c1*) echo c1-convex-bsd exit ;; c2*) if getsysinfo -f scalar_acc then echo c32-convex-bsd else echo c2-convex-bsd fi exit ;; c34*) echo c34-convex-bsd exit ;; c38*) echo c38-convex-bsd exit ;; c4*) echo c4-convex-bsd exit ;; esac fi cat >&2 < in order to provide the needed information to handle your system. config.guess timestamp = $timestamp uname -m = `(uname -m) 2>/dev/null || echo unknown` uname -r = `(uname -r) 2>/dev/null || echo unknown` uname -s = `(uname -s) 2>/dev/null || echo unknown` uname -v = `(uname -v) 2>/dev/null || echo unknown` /usr/bin/uname -p = `(/usr/bin/uname -p) 2>/dev/null` /bin/uname -X = `(/bin/uname -X) 2>/dev/null` hostinfo = `(hostinfo) 2>/dev/null` /bin/universe = `(/bin/universe) 2>/dev/null` /usr/bin/arch -k = `(/usr/bin/arch -k) 2>/dev/null` /bin/arch = `(/bin/arch) 2>/dev/null` /usr/bin/oslevel = `(/usr/bin/oslevel) 2>/dev/null` /usr/convex/getsysinfo = `(/usr/convex/getsysinfo) 2>/dev/null` UNAME_MACHINE = ${UNAME_MACHINE} UNAME_RELEASE = ${UNAME_RELEASE} UNAME_SYSTEM = ${UNAME_SYSTEM} UNAME_VERSION = ${UNAME_VERSION} EOF exit 1 # Local variables: # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "timestamp='" # time-stamp-format: "%:y-%02m-%02d" # time-stamp-end: "'" # End: ast-8.3.0/build-aux/missing0000755000175000017500000001533012710131217012520 00000000000000#! /bin/sh # Common wrapper for a few potentially missing GNU programs. scriptversion=2013-10-28.13; # UTC # Copyright (C) 1996-2013 Free Software Foundation, Inc. # Originally written by Fran,cois Pinard , 1996. # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, 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 General Public License for more details. # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. if test $# -eq 0; then echo 1>&2 "Try '$0 --help' for more information" exit 1 fi case $1 in --is-lightweight) # Used by our autoconf macros to check whether the available missing # script is modern enough. exit 0 ;; --run) # Back-compat with the calling convention used by older automake. shift ;; -h|--h|--he|--hel|--help) echo "\ $0 [OPTION]... PROGRAM [ARGUMENT]... Run 'PROGRAM [ARGUMENT]...', returning a proper advice when this fails due to PROGRAM being missing or too old. Options: -h, --help display this help and exit -v, --version output version information and exit Supported PROGRAM values: aclocal autoconf autoheader autom4te automake makeinfo bison yacc flex lex help2man Version suffixes to PROGRAM as well as the prefixes 'gnu-', 'gnu', and 'g' are ignored when checking the name. Send bug reports to ." exit $? ;; -v|--v|--ve|--ver|--vers|--versi|--versio|--version) echo "missing $scriptversion (GNU Automake)" exit $? ;; -*) echo 1>&2 "$0: unknown '$1' option" echo 1>&2 "Try '$0 --help' for more information" exit 1 ;; esac # Run the given program, remember its exit status. "$@"; st=$? # If it succeeded, we are done. test $st -eq 0 && exit 0 # Also exit now if we it failed (or wasn't found), and '--version' was # passed; such an option is passed most likely to detect whether the # program is present and works. case $2 in --version|--help) exit $st;; esac # Exit code 63 means version mismatch. This often happens when the user # tries to use an ancient version of a tool on a file that requires a # minimum version. if test $st -eq 63; then msg="probably too old" elif test $st -eq 127; then # Program was missing. msg="missing on your system" else # Program was found and executed, but failed. Give up. exit $st fi perl_URL=http://www.perl.org/ flex_URL=http://flex.sourceforge.net/ gnu_software_URL=http://www.gnu.org/software program_details () { case $1 in aclocal|automake) echo "The '$1' program is part of the GNU Automake package:" echo "<$gnu_software_URL/automake>" echo "It also requires GNU Autoconf, GNU m4 and Perl in order to run:" echo "<$gnu_software_URL/autoconf>" echo "<$gnu_software_URL/m4/>" echo "<$perl_URL>" ;; autoconf|autom4te|autoheader) echo "The '$1' program is part of the GNU Autoconf package:" echo "<$gnu_software_URL/autoconf/>" echo "It also requires GNU m4 and Perl in order to run:" echo "<$gnu_software_URL/m4/>" echo "<$perl_URL>" ;; esac } give_advice () { # Normalize program name to check for. normalized_program=`echo "$1" | sed ' s/^gnu-//; t s/^gnu//; t s/^g//; t'` printf '%s\n' "'$1' is $msg." configure_deps="'configure.ac' or m4 files included by 'configure.ac'" case $normalized_program in autoconf*) echo "You should only need it if you modified 'configure.ac'," echo "or m4 files included by it." program_details 'autoconf' ;; autoheader*) echo "You should only need it if you modified 'acconfig.h' or" echo "$configure_deps." program_details 'autoheader' ;; automake*) echo "You should only need it if you modified 'Makefile.am' or" echo "$configure_deps." program_details 'automake' ;; aclocal*) echo "You should only need it if you modified 'acinclude.m4' or" echo "$configure_deps." program_details 'aclocal' ;; autom4te*) echo "You might have modified some maintainer files that require" echo "the 'autom4te' program to be rebuilt." program_details 'autom4te' ;; bison*|yacc*) echo "You should only need it if you modified a '.y' file." echo "You may want to install the GNU Bison package:" echo "<$gnu_software_URL/bison/>" ;; lex*|flex*) echo "You should only need it if you modified a '.l' file." echo "You may want to install the Fast Lexical Analyzer package:" echo "<$flex_URL>" ;; help2man*) echo "You should only need it if you modified a dependency" \ "of a man page." echo "You may want to install the GNU Help2man package:" echo "<$gnu_software_URL/help2man/>" ;; makeinfo*) echo "You should only need it if you modified a '.texi' file, or" echo "any other file indirectly affecting the aspect of the manual." echo "You might want to install the Texinfo package:" echo "<$gnu_software_URL/texinfo/>" echo "The spurious makeinfo call might also be the consequence of" echo "using a buggy 'make' (AIX, DU, IRIX), in which case you might" echo "want to install GNU make:" echo "<$gnu_software_URL/make/>" ;; *) echo "You might have modified some files without having the proper" echo "tools for further handling them. Check the 'README' file, it" echo "often tells you about the needed prerequisites for installing" echo "this package. You may also peek at any GNU archive site, in" echo "case some other package contains this missing '$1' program." ;; esac } give_advice "$1" | sed -e '1s/^/WARNING: /' \ -e '2,$s/^/ /' >&2 # Propagate the correct exit status (expected to be 127 for a program # not found, 63 for a program that failed due to version mismatch). exit $st # Local variables: # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: ast-8.3.0/build-aux/compile0000755000175000017500000001624512710131217012505 00000000000000#! /bin/sh # Wrapper for compilers which do not understand '-c -o'. scriptversion=2012-10-14.11; # UTC # Copyright (C) 1999-2013 Free Software Foundation, Inc. # Written by Tom Tromey . # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, 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 General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # This file is maintained in Automake, please report # bugs to or send patches to # . nl=' ' # We need space, tab and new line, in precisely that order. Quoting is # there to prevent tools from complaining about whitespace usage. IFS=" "" $nl" file_conv= # func_file_conv build_file lazy # Convert a $build file to $host form and store it in $file # Currently only supports Windows hosts. If the determined conversion # type is listed in (the comma separated) LAZY, no conversion will # take place. func_file_conv () { file=$1 case $file in / | /[!/]*) # absolute file, and not a UNC file if test -z "$file_conv"; then # lazily determine how to convert abs files case `uname -s` in MINGW*) file_conv=mingw ;; CYGWIN*) file_conv=cygwin ;; *) file_conv=wine ;; esac fi case $file_conv/,$2, in *,$file_conv,*) ;; mingw/*) file=`cmd //C echo "$file " | sed -e 's/"\(.*\) " *$/\1/'` ;; cygwin/*) file=`cygpath -m "$file" || echo "$file"` ;; wine/*) file=`winepath -w "$file" || echo "$file"` ;; esac ;; esac } # func_cl_dashL linkdir # Make cl look for libraries in LINKDIR func_cl_dashL () { func_file_conv "$1" if test -z "$lib_path"; then lib_path=$file else lib_path="$lib_path;$file" fi linker_opts="$linker_opts -LIBPATH:$file" } # func_cl_dashl library # Do a library search-path lookup for cl func_cl_dashl () { lib=$1 found=no save_IFS=$IFS IFS=';' for dir in $lib_path $LIB do IFS=$save_IFS if $shared && test -f "$dir/$lib.dll.lib"; then found=yes lib=$dir/$lib.dll.lib break fi if test -f "$dir/$lib.lib"; then found=yes lib=$dir/$lib.lib break fi if test -f "$dir/lib$lib.a"; then found=yes lib=$dir/lib$lib.a break fi done IFS=$save_IFS if test "$found" != yes; then lib=$lib.lib fi } # func_cl_wrapper cl arg... # Adjust compile command to suit cl func_cl_wrapper () { # Assume a capable shell lib_path= shared=: linker_opts= for arg do if test -n "$eat"; then eat= else case $1 in -o) # configure might choose to run compile as 'compile cc -o foo foo.c'. eat=1 case $2 in *.o | *.[oO][bB][jJ]) func_file_conv "$2" set x "$@" -Fo"$file" shift ;; *) func_file_conv "$2" set x "$@" -Fe"$file" shift ;; esac ;; -I) eat=1 func_file_conv "$2" mingw set x "$@" -I"$file" shift ;; -I*) func_file_conv "${1#-I}" mingw set x "$@" -I"$file" shift ;; -l) eat=1 func_cl_dashl "$2" set x "$@" "$lib" shift ;; -l*) func_cl_dashl "${1#-l}" set x "$@" "$lib" shift ;; -L) eat=1 func_cl_dashL "$2" ;; -L*) func_cl_dashL "${1#-L}" ;; -static) shared=false ;; -Wl,*) arg=${1#-Wl,} save_ifs="$IFS"; IFS=',' for flag in $arg; do IFS="$save_ifs" linker_opts="$linker_opts $flag" done IFS="$save_ifs" ;; -Xlinker) eat=1 linker_opts="$linker_opts $2" ;; -*) set x "$@" "$1" shift ;; *.cc | *.CC | *.cxx | *.CXX | *.[cC]++) func_file_conv "$1" set x "$@" -Tp"$file" shift ;; *.c | *.cpp | *.CPP | *.lib | *.LIB | *.Lib | *.OBJ | *.obj | *.[oO]) func_file_conv "$1" mingw set x "$@" "$file" shift ;; *) set x "$@" "$1" shift ;; esac fi shift done if test -n "$linker_opts"; then linker_opts="-link$linker_opts" fi exec "$@" $linker_opts exit 1 } eat= case $1 in '') echo "$0: No command. Try '$0 --help' for more information." 1>&2 exit 1; ;; -h | --h*) cat <<\EOF Usage: compile [--help] [--version] PROGRAM [ARGS] Wrapper for compilers which do not understand '-c -o'. Remove '-o dest.o' from ARGS, run PROGRAM with the remaining arguments, and rename the output as expected. If you are trying to build a whole package this is not the right script to run: please start by reading the file 'INSTALL'. Report bugs to . EOF exit $? ;; -v | --v*) echo "compile $scriptversion" exit $? ;; cl | *[/\\]cl | cl.exe | *[/\\]cl.exe ) func_cl_wrapper "$@" # Doesn't return... ;; esac ofile= cfile= for arg do if test -n "$eat"; then eat= else case $1 in -o) # configure might choose to run compile as 'compile cc -o foo foo.c'. # So we strip '-o arg' only if arg is an object. eat=1 case $2 in *.o | *.obj) ofile=$2 ;; *) set x "$@" -o "$2" shift ;; esac ;; *.c) cfile=$1 set x "$@" "$1" shift ;; *) set x "$@" "$1" shift ;; esac fi shift done if test -z "$ofile" || test -z "$cfile"; then # If no '-o' option was seen then we might have been invoked from a # pattern rule where we don't need one. That is ok -- this is a # normal compilation that the losing compiler can handle. If no # '.c' file was seen then we are probably linking. That is also # ok. exec "$@" fi # Name of file we expect compiler to create. cofile=`echo "$cfile" | sed 's|^.*[\\/]||; s|^[a-zA-Z]:||; s/\.c$/.o/'` # Create the lock directory. # Note: use '[/\\:.-]' here to ensure that we don't use the same name # that we are using for the .o file. Also, base the name on the expected # object file name, since that is what matters with a parallel build. lockdir=`echo "$cofile" | sed -e 's|[/\\:.-]|_|g'`.d while true; do if mkdir "$lockdir" >/dev/null 2>&1; then break fi sleep 1 done # FIXME: race condition here if user kills between mkdir and trap. trap "rmdir '$lockdir'; exit 1" 1 2 15 # Run the compile. "$@" ret=$? if test -f "$cofile"; then test "$cofile" = "$ofile" || mv "$cofile" "$ofile" elif test -f "${cofile}bj"; then test "${cofile}bj" = "$ofile" || mv "${cofile}bj" "$ofile" fi rmdir "$lockdir" exit $ret # Local Variables: # mode: shell-script # sh-indentation: 2 # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: ast-8.3.0/build-aux/install-sh0000755000175000017500000003325512710131217013133 00000000000000#!/bin/sh # install - install a program, script, or datafile scriptversion=2011-11-20.07; # UTC # This originates from X11R5 (mit/util/scripts/install.sh), which was # later released in X11R6 (xc/config/util/install.sh) with the # following copyright and license. # # Copyright (C) 1994 X Consortium # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to # deal in the Software without restriction, including without limitation the # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or # sell copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN # AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNEC- # TION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # # Except as contained in this notice, the name of the X Consortium shall not # be used in advertising or otherwise to promote the sale, use or other deal- # ings in this Software without prior written authorization from the X Consor- # tium. # # # FSF changes to this file are in the public domain. # # Calling this script install-sh is preferred over install.sh, to prevent # 'make' implicit rules from creating a file called install from it # when there is no Makefile. # # This script is compatible with the BSD install script, but was written # from scratch. nl=' ' IFS=" "" $nl" # set DOITPROG to echo to test this script # Don't use :- since 4.3BSD and earlier shells don't like it. doit=${DOITPROG-} if test -z "$doit"; then doit_exec=exec else doit_exec=$doit fi # Put in absolute file names if you don't have them in your path; # or use environment vars. chgrpprog=${CHGRPPROG-chgrp} chmodprog=${CHMODPROG-chmod} chownprog=${CHOWNPROG-chown} cmpprog=${CMPPROG-cmp} cpprog=${CPPROG-cp} mkdirprog=${MKDIRPROG-mkdir} mvprog=${MVPROG-mv} rmprog=${RMPROG-rm} stripprog=${STRIPPROG-strip} posix_glob='?' initialize_posix_glob=' test "$posix_glob" != "?" || { if (set -f) 2>/dev/null; then posix_glob= else posix_glob=: fi } ' posix_mkdir= # Desired mode of installed file. mode=0755 chgrpcmd= chmodcmd=$chmodprog chowncmd= mvcmd=$mvprog rmcmd="$rmprog -f" stripcmd= src= dst= dir_arg= dst_arg= copy_on_change=false no_target_directory= usage="\ Usage: $0 [OPTION]... [-T] SRCFILE DSTFILE or: $0 [OPTION]... SRCFILES... DIRECTORY or: $0 [OPTION]... -t DIRECTORY SRCFILES... or: $0 [OPTION]... -d DIRECTORIES... In the 1st form, copy SRCFILE to DSTFILE. In the 2nd and 3rd, copy all SRCFILES to DIRECTORY. In the 4th, create DIRECTORIES. Options: --help display this help and exit. --version display version info and exit. -c (ignored) -C install only if different (preserve the last data modification time) -d create directories instead of installing files. -g GROUP $chgrpprog installed files to GROUP. -m MODE $chmodprog installed files to MODE. -o USER $chownprog installed files to USER. -s $stripprog installed files. -t DIRECTORY install into DIRECTORY. -T report an error if DSTFILE is a directory. Environment variables override the default commands: CHGRPPROG CHMODPROG CHOWNPROG CMPPROG CPPROG MKDIRPROG MVPROG RMPROG STRIPPROG " while test $# -ne 0; do case $1 in -c) ;; -C) copy_on_change=true;; -d) dir_arg=true;; -g) chgrpcmd="$chgrpprog $2" shift;; --help) echo "$usage"; exit $?;; -m) mode=$2 case $mode in *' '* | *' '* | *' '* | *'*'* | *'?'* | *'['*) echo "$0: invalid mode: $mode" >&2 exit 1;; esac shift;; -o) chowncmd="$chownprog $2" shift;; -s) stripcmd=$stripprog;; -t) dst_arg=$2 # Protect names problematic for 'test' and other utilities. case $dst_arg in -* | [=\(\)!]) dst_arg=./$dst_arg;; esac shift;; -T) no_target_directory=true;; --version) echo "$0 $scriptversion"; exit $?;; --) shift break;; -*) echo "$0: invalid option: $1" >&2 exit 1;; *) break;; esac shift done if test $# -ne 0 && test -z "$dir_arg$dst_arg"; then # When -d is used, all remaining arguments are directories to create. # When -t is used, the destination is already specified. # Otherwise, the last argument is the destination. Remove it from $@. for arg do if test -n "$dst_arg"; then # $@ is not empty: it contains at least $arg. set fnord "$@" "$dst_arg" shift # fnord fi shift # arg dst_arg=$arg # Protect names problematic for 'test' and other utilities. case $dst_arg in -* | [=\(\)!]) dst_arg=./$dst_arg;; esac done fi if test $# -eq 0; then if test -z "$dir_arg"; then echo "$0: no input file specified." >&2 exit 1 fi # It's OK to call 'install-sh -d' without argument. # This can happen when creating conditional directories. exit 0 fi if test -z "$dir_arg"; then do_exit='(exit $ret); exit $ret' trap "ret=129; $do_exit" 1 trap "ret=130; $do_exit" 2 trap "ret=141; $do_exit" 13 trap "ret=143; $do_exit" 15 # Set umask so as not to create temps with too-generous modes. # However, 'strip' requires both read and write access to temps. case $mode in # Optimize common cases. *644) cp_umask=133;; *755) cp_umask=22;; *[0-7]) if test -z "$stripcmd"; then u_plus_rw= else u_plus_rw='% 200' fi cp_umask=`expr '(' 777 - $mode % 1000 ')' $u_plus_rw`;; *) if test -z "$stripcmd"; then u_plus_rw= else u_plus_rw=,u+rw fi cp_umask=$mode$u_plus_rw;; esac fi for src do # Protect names problematic for 'test' and other utilities. case $src in -* | [=\(\)!]) src=./$src;; esac if test -n "$dir_arg"; then dst=$src dstdir=$dst test -d "$dstdir" dstdir_status=$? else # Waiting for this to be detected by the "$cpprog $src $dsttmp" command # might cause directories to be created, which would be especially bad # if $src (and thus $dsttmp) contains '*'. if test ! -f "$src" && test ! -d "$src"; then echo "$0: $src does not exist." >&2 exit 1 fi if test -z "$dst_arg"; then echo "$0: no destination specified." >&2 exit 1 fi dst=$dst_arg # If destination is a directory, append the input filename; won't work # if double slashes aren't ignored. if test -d "$dst"; then if test -n "$no_target_directory"; then echo "$0: $dst_arg: Is a directory" >&2 exit 1 fi dstdir=$dst dst=$dstdir/`basename "$src"` dstdir_status=0 else # Prefer dirname, but fall back on a substitute if dirname fails. dstdir=` (dirname "$dst") 2>/dev/null || expr X"$dst" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ X"$dst" : 'X\(//\)[^/]' \| \ X"$dst" : 'X\(//\)$' \| \ X"$dst" : 'X\(/\)' \| . 2>/dev/null || echo X"$dst" | sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ s//\1/ q } /^X\(\/\/\)[^/].*/{ s//\1/ q } /^X\(\/\/\)$/{ s//\1/ q } /^X\(\/\).*/{ s//\1/ q } s/.*/./; q' ` test -d "$dstdir" dstdir_status=$? fi fi obsolete_mkdir_used=false if test $dstdir_status != 0; then case $posix_mkdir in '') # Create intermediate dirs using mode 755 as modified by the umask. # This is like FreeBSD 'install' as of 1997-10-28. umask=`umask` case $stripcmd.$umask in # Optimize common cases. *[2367][2367]) mkdir_umask=$umask;; .*0[02][02] | .[02][02] | .[02]) mkdir_umask=22;; *[0-7]) mkdir_umask=`expr $umask + 22 \ - $umask % 100 % 40 + $umask % 20 \ - $umask % 10 % 4 + $umask % 2 `;; *) mkdir_umask=$umask,go-w;; esac # With -d, create the new directory with the user-specified mode. # Otherwise, rely on $mkdir_umask. if test -n "$dir_arg"; then mkdir_mode=-m$mode else mkdir_mode= fi posix_mkdir=false case $umask in *[123567][0-7][0-7]) # POSIX mkdir -p sets u+wx bits regardless of umask, which # is incompatible with FreeBSD 'install' when (umask & 300) != 0. ;; *) tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$ trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0 if (umask $mkdir_umask && exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1 then if test -z "$dir_arg" || { # Check for POSIX incompatibilities with -m. # HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or # other-writable bit of parent directory when it shouldn't. # FreeBSD 6.1 mkdir -m -p sets mode of existing directory. ls_ld_tmpdir=`ls -ld "$tmpdir"` case $ls_ld_tmpdir in d????-?r-*) different_mode=700;; d????-?--*) different_mode=755;; *) false;; esac && $mkdirprog -m$different_mode -p -- "$tmpdir" && { ls_ld_tmpdir_1=`ls -ld "$tmpdir"` test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1" } } then posix_mkdir=: fi rmdir "$tmpdir/d" "$tmpdir" else # Remove any dirs left behind by ancient mkdir implementations. rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null fi trap '' 0;; esac;; esac if $posix_mkdir && ( umask $mkdir_umask && $doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir" ) then : else # The umask is ridiculous, or mkdir does not conform to POSIX, # or it failed possibly due to a race condition. Create the # directory the slow way, step by step, checking for races as we go. case $dstdir in /*) prefix='/';; [-=\(\)!]*) prefix='./';; *) prefix='';; esac eval "$initialize_posix_glob" oIFS=$IFS IFS=/ $posix_glob set -f set fnord $dstdir shift $posix_glob set +f IFS=$oIFS prefixes= for d do test X"$d" = X && continue prefix=$prefix$d if test -d "$prefix"; then prefixes= else if $posix_mkdir; then (umask=$mkdir_umask && $doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir") && break # Don't fail if two instances are running concurrently. test -d "$prefix" || exit 1 else case $prefix in *\'*) qprefix=`echo "$prefix" | sed "s/'/'\\\\\\\\''/g"`;; *) qprefix=$prefix;; esac prefixes="$prefixes '$qprefix'" fi fi prefix=$prefix/ done if test -n "$prefixes"; then # Don't fail if two instances are running concurrently. (umask $mkdir_umask && eval "\$doit_exec \$mkdirprog $prefixes") || test -d "$dstdir" || exit 1 obsolete_mkdir_used=true fi fi fi if test -n "$dir_arg"; then { test -z "$chowncmd" || $doit $chowncmd "$dst"; } && { test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } && { test "$obsolete_mkdir_used$chowncmd$chgrpcmd" = false || test -z "$chmodcmd" || $doit $chmodcmd $mode "$dst"; } || exit 1 else # Make a couple of temp file names in the proper directory. dsttmp=$dstdir/_inst.$$_ rmtmp=$dstdir/_rm.$$_ # Trap to clean up those temp files at exit. trap 'ret=$?; rm -f "$dsttmp" "$rmtmp" && exit $ret' 0 # Copy the file name to the temp name. (umask $cp_umask && $doit_exec $cpprog "$src" "$dsttmp") && # and set any options; do chmod last to preserve setuid bits. # # If any of these fail, we abort the whole thing. If we want to # ignore errors from any of these, just make sure not to ignore # errors from the above "$doit $cpprog $src $dsttmp" command. # { test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } && { test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } && { test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } && { test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } && # If -C, don't bother to copy if it wouldn't change the file. if $copy_on_change && old=`LC_ALL=C ls -dlL "$dst" 2>/dev/null` && new=`LC_ALL=C ls -dlL "$dsttmp" 2>/dev/null` && eval "$initialize_posix_glob" && $posix_glob set -f && set X $old && old=:$2:$4:$5:$6 && set X $new && new=:$2:$4:$5:$6 && $posix_glob set +f && test "$old" = "$new" && $cmpprog "$dst" "$dsttmp" >/dev/null 2>&1 then rm -f "$dsttmp" else # Rename the file to the real destination. $doit $mvcmd -f "$dsttmp" "$dst" 2>/dev/null || # The rename failed, perhaps because mv can't rename something else # to itself, or perhaps because mv is so ancient that it does not # support -f. { # Now remove or move aside any old file at destination location. # We try this two ways since rm can't unlink itself on some # systems and the destination file might be busy for other # reasons. In this case, the final cleanup might fail but the new # file should still install successfully. { test ! -f "$dst" || $doit $rmcmd -f "$dst" 2>/dev/null || { $doit $mvcmd -f "$dst" "$rmtmp" 2>/dev/null && { $doit $rmcmd -f "$rmtmp" 2>/dev/null; :; } } || { echo "$0: cannot unlink or rename $dst" >&2 (exit 1); exit 1 } } && # Now rename the file to the real destination. $doit $mvcmd "$dsttmp" "$dst" } fi || exit 1 trap '' 0 fi done # Local variables: # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: ast-8.3.0/build-aux/depcomp0000755000175000017500000005601612710131217012504 00000000000000#! /bin/sh # depcomp - compile a program generating dependencies as side-effects scriptversion=2013-05-30.07; # UTC # Copyright (C) 1999-2013 Free Software Foundation, Inc. # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, 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 General Public License for more details. # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # Originally written by Alexandre Oliva . case $1 in '') echo "$0: No command. Try '$0 --help' for more information." 1>&2 exit 1; ;; -h | --h*) cat <<\EOF Usage: depcomp [--help] [--version] PROGRAM [ARGS] Run PROGRAMS ARGS to compile a file, generating dependencies as side-effects. Environment variables: depmode Dependency tracking mode. source Source file read by 'PROGRAMS ARGS'. object Object file output by 'PROGRAMS ARGS'. DEPDIR directory where to store dependencies. depfile Dependency file to output. tmpdepfile Temporary file to use when outputting dependencies. libtool Whether libtool is used (yes/no). Report bugs to . EOF exit $? ;; -v | --v*) echo "depcomp $scriptversion" exit $? ;; esac # Get the directory component of the given path, and save it in the # global variables '$dir'. Note that this directory component will # be either empty or ending with a '/' character. This is deliberate. set_dir_from () { case $1 in */*) dir=`echo "$1" | sed -e 's|/[^/]*$|/|'`;; *) dir=;; esac } # Get the suffix-stripped basename of the given path, and save it the # global variable '$base'. set_base_from () { base=`echo "$1" | sed -e 's|^.*/||' -e 's/\.[^.]*$//'` } # If no dependency file was actually created by the compiler invocation, # we still have to create a dummy depfile, to avoid errors with the # Makefile "include basename.Plo" scheme. make_dummy_depfile () { echo "#dummy" > "$depfile" } # Factor out some common post-processing of the generated depfile. # Requires the auxiliary global variable '$tmpdepfile' to be set. aix_post_process_depfile () { # If the compiler actually managed to produce a dependency file, # post-process it. if test -f "$tmpdepfile"; then # Each line is of the form 'foo.o: dependency.h'. # Do two passes, one to just change these to # $object: dependency.h # and one to simply output # dependency.h: # which is needed to avoid the deleted-header problem. { sed -e "s,^.*\.[$lower]*:,$object:," < "$tmpdepfile" sed -e "s,^.*\.[$lower]*:[$tab ]*,," -e 's,$,:,' < "$tmpdepfile" } > "$depfile" rm -f "$tmpdepfile" else make_dummy_depfile fi } # A tabulation character. tab=' ' # A newline character. nl=' ' # Character ranges might be problematic outside the C locale. # These definitions help. upper=ABCDEFGHIJKLMNOPQRSTUVWXYZ lower=abcdefghijklmnopqrstuvwxyz digits=0123456789 alpha=${upper}${lower} if test -z "$depmode" || test -z "$source" || test -z "$object"; then echo "depcomp: Variables source, object and depmode must be set" 1>&2 exit 1 fi # Dependencies for sub/bar.o or sub/bar.obj go into sub/.deps/bar.Po. depfile=${depfile-`echo "$object" | sed 's|[^\\/]*$|'${DEPDIR-.deps}'/&|;s|\.\([^.]*\)$|.P\1|;s|Pobj$|Po|'`} tmpdepfile=${tmpdepfile-`echo "$depfile" | sed 's/\.\([^.]*\)$/.T\1/'`} rm -f "$tmpdepfile" # Avoid interferences from the environment. gccflag= dashmflag= # Some modes work just like other modes, but use different flags. We # parameterize here, but still list the modes in the big case below, # to make depend.m4 easier to write. Note that we *cannot* use a case # here, because this file can only contain one case statement. if test "$depmode" = hp; then # HP compiler uses -M and no extra arg. gccflag=-M depmode=gcc fi if test "$depmode" = dashXmstdout; then # This is just like dashmstdout with a different argument. dashmflag=-xM depmode=dashmstdout fi cygpath_u="cygpath -u -f -" if test "$depmode" = msvcmsys; then # This is just like msvisualcpp but w/o cygpath translation. # Just convert the backslash-escaped backslashes to single forward # slashes to satisfy depend.m4 cygpath_u='sed s,\\\\,/,g' depmode=msvisualcpp fi if test "$depmode" = msvc7msys; then # This is just like msvc7 but w/o cygpath translation. # Just convert the backslash-escaped backslashes to single forward # slashes to satisfy depend.m4 cygpath_u='sed s,\\\\,/,g' depmode=msvc7 fi if test "$depmode" = xlc; then # IBM C/C++ Compilers xlc/xlC can output gcc-like dependency information. gccflag=-qmakedep=gcc,-MF depmode=gcc fi case "$depmode" in gcc3) ## gcc 3 implements dependency tracking that does exactly what ## we want. Yay! Note: for some reason libtool 1.4 doesn't like ## it if -MD -MP comes after the -MF stuff. Hmm. ## Unfortunately, FreeBSD c89 acceptance of flags depends upon ## the command line argument order; so add the flags where they ## appear in depend2.am. Note that the slowdown incurred here ## affects only configure: in makefiles, %FASTDEP% shortcuts this. for arg do case $arg in -c) set fnord "$@" -MT "$object" -MD -MP -MF "$tmpdepfile" "$arg" ;; *) set fnord "$@" "$arg" ;; esac shift # fnord shift # $arg done "$@" stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi mv "$tmpdepfile" "$depfile" ;; gcc) ## Note that this doesn't just cater to obsosete pre-3.x GCC compilers. ## but also to in-use compilers like IMB xlc/xlC and the HP C compiler. ## (see the conditional assignment to $gccflag above). ## There are various ways to get dependency output from gcc. Here's ## why we pick this rather obscure method: ## - Don't want to use -MD because we'd like the dependencies to end ## up in a subdir. Having to rename by hand is ugly. ## (We might end up doing this anyway to support other compilers.) ## - The DEPENDENCIES_OUTPUT environment variable makes gcc act like ## -MM, not -M (despite what the docs say). Also, it might not be ## supported by the other compilers which use the 'gcc' depmode. ## - Using -M directly means running the compiler twice (even worse ## than renaming). if test -z "$gccflag"; then gccflag=-MD, fi "$@" -Wp,"$gccflag$tmpdepfile" stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" echo "$object : \\" > "$depfile" # The second -e expression handles DOS-style file names with drive # letters. sed -e 's/^[^:]*: / /' \ -e 's/^['$alpha']:\/[^:]*: / /' < "$tmpdepfile" >> "$depfile" ## This next piece of magic avoids the "deleted header file" problem. ## The problem is that when a header file which appears in a .P file ## is deleted, the dependency causes make to die (because there is ## typically no way to rebuild the header). We avoid this by adding ## dummy dependencies for each header file. Too bad gcc doesn't do ## this for us directly. ## Some versions of gcc put a space before the ':'. On the theory ## that the space means something, we add a space to the output as ## well. hp depmode also adds that space, but also prefixes the VPATH ## to the object. Take care to not repeat it in the output. ## Some versions of the HPUX 10.20 sed can't process this invocation ## correctly. Breaking it into two sed invocations is a workaround. tr ' ' "$nl" < "$tmpdepfile" \ | sed -e 's/^\\$//' -e '/^$/d' -e "s|.*$object$||" -e '/:$/d' \ | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; hp) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; sgi) if test "$libtool" = yes; then "$@" "-Wp,-MDupdate,$tmpdepfile" else "$@" -MDupdate "$tmpdepfile" fi stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" if test -f "$tmpdepfile"; then # yes, the sourcefile depend on other files echo "$object : \\" > "$depfile" # Clip off the initial element (the dependent). Don't try to be # clever and replace this with sed code, as IRIX sed won't handle # lines with more than a fixed number of characters (4096 in # IRIX 6.2 sed, 8192 in IRIX 6.5). We also remove comment lines; # the IRIX cc adds comments like '#:fec' to the end of the # dependency line. tr ' ' "$nl" < "$tmpdepfile" \ | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' \ | tr "$nl" ' ' >> "$depfile" echo >> "$depfile" # The second pass generates a dummy entry for each header file. tr ' ' "$nl" < "$tmpdepfile" \ | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' -e 's/$/:/' \ >> "$depfile" else make_dummy_depfile fi rm -f "$tmpdepfile" ;; xlc) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; aix) # The C for AIX Compiler uses -M and outputs the dependencies # in a .u file. In older versions, this file always lives in the # current directory. Also, the AIX compiler puts '$object:' at the # start of each line; $object doesn't have directory information. # Version 6 uses the directory in both cases. set_dir_from "$object" set_base_from "$object" if test "$libtool" = yes; then tmpdepfile1=$dir$base.u tmpdepfile2=$base.u tmpdepfile3=$dir.libs/$base.u "$@" -Wc,-M else tmpdepfile1=$dir$base.u tmpdepfile2=$dir$base.u tmpdepfile3=$dir$base.u "$@" -M fi stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" do test -f "$tmpdepfile" && break done aix_post_process_depfile ;; tcc) # tcc (Tiny C Compiler) understand '-MD -MF file' since version 0.9.26 # FIXME: That version still under development at the moment of writing. # Make that this statement remains true also for stable, released # versions. # It will wrap lines (doesn't matter whether long or short) with a # trailing '\', as in: # # foo.o : \ # foo.c \ # foo.h \ # # It will put a trailing '\' even on the last line, and will use leading # spaces rather than leading tabs (at least since its commit 0394caf7 # "Emit spaces for -MD"). "$@" -MD -MF "$tmpdepfile" stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" # Each non-empty line is of the form 'foo.o : \' or ' dep.h \'. # We have to change lines of the first kind to '$object: \'. sed -e "s|.*:|$object :|" < "$tmpdepfile" > "$depfile" # And for each line of the second kind, we have to emit a 'dep.h:' # dummy dependency, to avoid the deleted-header problem. sed -n -e 's|^ *\(.*\) *\\$|\1:|p' < "$tmpdepfile" >> "$depfile" rm -f "$tmpdepfile" ;; ## The order of this option in the case statement is important, since the ## shell code in configure will try each of these formats in the order ## listed in this file. A plain '-MD' option would be understood by many ## compilers, so we must ensure this comes after the gcc and icc options. pgcc) # Portland's C compiler understands '-MD'. # Will always output deps to 'file.d' where file is the root name of the # source file under compilation, even if file resides in a subdirectory. # The object file name does not affect the name of the '.d' file. # pgcc 10.2 will output # foo.o: sub/foo.c sub/foo.h # and will wrap long lines using '\' : # foo.o: sub/foo.c ... \ # sub/foo.h ... \ # ... set_dir_from "$object" # Use the source, not the object, to determine the base name, since # that's sadly what pgcc will do too. set_base_from "$source" tmpdepfile=$base.d # For projects that build the same source file twice into different object # files, the pgcc approach of using the *source* file root name can cause # problems in parallel builds. Use a locking strategy to avoid stomping on # the same $tmpdepfile. lockdir=$base.d-lock trap " echo '$0: caught signal, cleaning up...' >&2 rmdir '$lockdir' exit 1 " 1 2 13 15 numtries=100 i=$numtries while test $i -gt 0; do # mkdir is a portable test-and-set. if mkdir "$lockdir" 2>/dev/null; then # This process acquired the lock. "$@" -MD stat=$? # Release the lock. rmdir "$lockdir" break else # If the lock is being held by a different process, wait # until the winning process is done or we timeout. while test -d "$lockdir" && test $i -gt 0; do sleep 1 i=`expr $i - 1` done fi i=`expr $i - 1` done trap - 1 2 13 15 if test $i -le 0; then echo "$0: failed to acquire lock after $numtries attempts" >&2 echo "$0: check lockdir '$lockdir'" >&2 exit 1 fi if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" # Each line is of the form `foo.o: dependent.h', # or `foo.o: dep1.h dep2.h \', or ` dep3.h dep4.h \'. # Do two passes, one to just change these to # `$object: dependent.h' and one to simply `dependent.h:'. sed "s,^[^:]*:,$object :," < "$tmpdepfile" > "$depfile" # Some versions of the HPUX 10.20 sed can't process this invocation # correctly. Breaking it into two sed invocations is a workaround. sed 's,^[^:]*: \(.*\)$,\1,;s/^\\$//;/^$/d;/:$/d' < "$tmpdepfile" \ | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; hp2) # The "hp" stanza above does not work with aCC (C++) and HP's ia64 # compilers, which have integrated preprocessors. The correct option # to use with these is +Maked; it writes dependencies to a file named # 'foo.d', which lands next to the object file, wherever that # happens to be. # Much of this is similar to the tru64 case; see comments there. set_dir_from "$object" set_base_from "$object" if test "$libtool" = yes; then tmpdepfile1=$dir$base.d tmpdepfile2=$dir.libs/$base.d "$@" -Wc,+Maked else tmpdepfile1=$dir$base.d tmpdepfile2=$dir$base.d "$@" +Maked fi stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile1" "$tmpdepfile2" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" do test -f "$tmpdepfile" && break done if test -f "$tmpdepfile"; then sed -e "s,^.*\.[$lower]*:,$object:," "$tmpdepfile" > "$depfile" # Add 'dependent.h:' lines. sed -ne '2,${ s/^ *// s/ \\*$// s/$/:/ p }' "$tmpdepfile" >> "$depfile" else make_dummy_depfile fi rm -f "$tmpdepfile" "$tmpdepfile2" ;; tru64) # The Tru64 compiler uses -MD to generate dependencies as a side # effect. 'cc -MD -o foo.o ...' puts the dependencies into 'foo.o.d'. # At least on Alpha/Redhat 6.1, Compaq CCC V6.2-504 seems to put # dependencies in 'foo.d' instead, so we check for that too. # Subdirectories are respected. set_dir_from "$object" set_base_from "$object" if test "$libtool" = yes; then # Libtool generates 2 separate objects for the 2 libraries. These # two compilations output dependencies in $dir.libs/$base.o.d and # in $dir$base.o.d. We have to check for both files, because # one of the two compilations can be disabled. We should prefer # $dir$base.o.d over $dir.libs/$base.o.d because the latter is # automatically cleaned when .libs/ is deleted, while ignoring # the former would cause a distcleancheck panic. tmpdepfile1=$dir$base.o.d # libtool 1.5 tmpdepfile2=$dir.libs/$base.o.d # Likewise. tmpdepfile3=$dir.libs/$base.d # Compaq CCC V6.2-504 "$@" -Wc,-MD else tmpdepfile1=$dir$base.d tmpdepfile2=$dir$base.d tmpdepfile3=$dir$base.d "$@" -MD fi stat=$? if test $stat -ne 0; then rm -f "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" do test -f "$tmpdepfile" && break done # Same post-processing that is required for AIX mode. aix_post_process_depfile ;; msvc7) if test "$libtool" = yes; then showIncludes=-Wc,-showIncludes else showIncludes=-showIncludes fi "$@" $showIncludes > "$tmpdepfile" stat=$? grep -v '^Note: including file: ' "$tmpdepfile" if test $stat -ne 0; then rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" echo "$object : \\" > "$depfile" # The first sed program below extracts the file names and escapes # backslashes for cygpath. The second sed program outputs the file # name when reading, but also accumulates all include files in the # hold buffer in order to output them again at the end. This only # works with sed implementations that can handle large buffers. sed < "$tmpdepfile" -n ' /^Note: including file: *\(.*\)/ { s//\1/ s/\\/\\\\/g p }' | $cygpath_u | sort -u | sed -n ' s/ /\\ /g s/\(.*\)/'"$tab"'\1 \\/p s/.\(.*\) \\/\1:/ H $ { s/.*/'"$tab"'/ G p }' >> "$depfile" echo >> "$depfile" # make sure the fragment doesn't end with a backslash rm -f "$tmpdepfile" ;; msvc7msys) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; #nosideeffect) # This comment above is used by automake to tell side-effect # dependency tracking mechanisms from slower ones. dashmstdout) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout, regardless of -o. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # Remove '-o $object'. IFS=" " for arg do case $arg in -o) shift ;; $object) shift ;; *) set fnord "$@" "$arg" shift # fnord shift # $arg ;; esac done test -z "$dashmflag" && dashmflag=-M # Require at least two characters before searching for ':' # in the target name. This is to cope with DOS-style filenames: # a dependency such as 'c:/foo/bar' could be seen as target 'c' otherwise. "$@" $dashmflag | sed "s|^[$tab ]*[^:$tab ][^:][^:]*:[$tab ]*|$object: |" > "$tmpdepfile" rm -f "$depfile" cat < "$tmpdepfile" > "$depfile" # Some versions of the HPUX 10.20 sed can't process this sed invocation # correctly. Breaking it into two sed invocations is a workaround. tr ' ' "$nl" < "$tmpdepfile" \ | sed -e 's/^\\$//' -e '/^$/d' -e '/:$/d' \ | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; dashXmstdout) # This case only exists to satisfy depend.m4. It is never actually # run, as this mode is specially recognized in the preamble. exit 1 ;; makedepend) "$@" || exit $? # Remove any Libtool call if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # X makedepend shift cleared=no eat=no for arg do case $cleared in no) set ""; shift cleared=yes ;; esac if test $eat = yes; then eat=no continue fi case "$arg" in -D*|-I*) set fnord "$@" "$arg"; shift ;; # Strip any option that makedepend may not understand. Remove # the object too, otherwise makedepend will parse it as a source file. -arch) eat=yes ;; -*|$object) ;; *) set fnord "$@" "$arg"; shift ;; esac done obj_suffix=`echo "$object" | sed 's/^.*\././'` touch "$tmpdepfile" ${MAKEDEPEND-makedepend} -o"$obj_suffix" -f"$tmpdepfile" "$@" rm -f "$depfile" # makedepend may prepend the VPATH from the source file name to the object. # No need to regex-escape $object, excess matching of '.' is harmless. sed "s|^.*\($object *:\)|\1|" "$tmpdepfile" > "$depfile" # Some versions of the HPUX 10.20 sed can't process the last invocation # correctly. Breaking it into two sed invocations is a workaround. sed '1,2d' "$tmpdepfile" \ | tr ' ' "$nl" \ | sed -e 's/^\\$//' -e '/^$/d' -e '/:$/d' \ | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" "$tmpdepfile".bak ;; cpp) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # Remove '-o $object'. IFS=" " for arg do case $arg in -o) shift ;; $object) shift ;; *) set fnord "$@" "$arg" shift # fnord shift # $arg ;; esac done "$@" -E \ | sed -n -e '/^# [0-9][0-9]* "\([^"]*\)".*/ s:: \1 \\:p' \ -e '/^#line [0-9][0-9]* "\([^"]*\)".*/ s:: \1 \\:p' \ | sed '$ s: \\$::' > "$tmpdepfile" rm -f "$depfile" echo "$object : \\" > "$depfile" cat < "$tmpdepfile" >> "$depfile" sed < "$tmpdepfile" '/^$/d;s/^ //;s/ \\$//;s/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; msvisualcpp) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi IFS=" " for arg do case "$arg" in -o) shift ;; $object) shift ;; "-Gm"|"/Gm"|"-Gi"|"/Gi"|"-ZI"|"/ZI") set fnord "$@" shift shift ;; *) set fnord "$@" "$arg" shift shift ;; esac done "$@" -E 2>/dev/null | sed -n '/^#line [0-9][0-9]* "\([^"]*\)"/ s::\1:p' | $cygpath_u | sort -u > "$tmpdepfile" rm -f "$depfile" echo "$object : \\" > "$depfile" sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s::'"$tab"'\1 \\:p' >> "$depfile" echo "$tab" >> "$depfile" sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s::\1\::p' >> "$depfile" rm -f "$tmpdepfile" ;; msvcmsys) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; none) exec "$@" ;; *) echo "Unknown depmode $depmode" 1>&2 exit 1 ;; esac exit 0 # Local Variables: # mode: shell-script # sh-indentation: 2 # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: ast-8.3.0/build-aux/config.sub0000755000175000017500000010541212710131217013105 00000000000000#! /bin/sh # Configuration validation subroutine script. # Copyright 1992-2013 Free Software Foundation, Inc. timestamp='2013-10-01' # This file is free software; you can redistribute it and/or modify it # under the terms of the GNU 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 # General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, see . # # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that # program. This Exception is an additional permission under section 7 # of the GNU General Public License, version 3 ("GPLv3"). # Please send patches with a ChangeLog entry to config-patches@gnu.org. # # Configuration subroutine to validate and canonicalize a configuration type. # Supply the specified configuration type as an argument. # If it is invalid, we print an error message on stderr and exit with code 1. # Otherwise, we print the canonical config type on stdout and succeed. # You can get the latest version of this script from: # http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD # This file is supposed to be the same for all GNU packages # and recognize all the CPU types, system types and aliases # that are meaningful with *any* GNU software. # Each package is responsible for reporting which valid configurations # it does not support. The user should be able to distinguish # a failure to support a valid configuration from a meaningless # configuration. # The goal of this file is to map all the various variations of a given # machine specification into a single specification in the form: # CPU_TYPE-MANUFACTURER-OPERATING_SYSTEM # or in some cases, the newer four-part form: # CPU_TYPE-MANUFACTURER-KERNEL-OPERATING_SYSTEM # It is wrong to echo any other type of specification. me=`echo "$0" | sed -e 's,.*/,,'` usage="\ Usage: $0 [OPTION] CPU-MFR-OPSYS $0 [OPTION] ALIAS Canonicalize a configuration name. Operation modes: -h, --help print this help, then exit -t, --time-stamp print date of last modification, then exit -v, --version print version number, then exit Report bugs and patches to ." version="\ GNU config.sub ($timestamp) Copyright 1992-2013 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." help=" Try \`$me --help' for more information." # Parse command line while test $# -gt 0 ; do case $1 in --time-stamp | --time* | -t ) echo "$timestamp" ; exit ;; --version | -v ) echo "$version" ; exit ;; --help | --h* | -h ) echo "$usage"; exit ;; -- ) # Stop option processing shift; break ;; - ) # Use stdin as input. break ;; -* ) echo "$me: invalid option $1$help" exit 1 ;; *local*) # First pass through any local machine types. echo $1 exit ;; * ) break ;; esac done case $# in 0) echo "$me: missing argument$help" >&2 exit 1;; 1) ;; *) echo "$me: too many arguments$help" >&2 exit 1;; esac # Separate what the user gave into CPU-COMPANY and OS or KERNEL-OS (if any). # Here we must recognize all the valid KERNEL-OS combinations. maybe_os=`echo $1 | sed 's/^\(.*\)-\([^-]*-[^-]*\)$/\2/'` case $maybe_os in nto-qnx* | linux-gnu* | linux-android* | linux-dietlibc | linux-newlib* | \ linux-musl* | linux-uclibc* | uclinux-uclibc* | uclinux-gnu* | kfreebsd*-gnu* | \ knetbsd*-gnu* | netbsd*-gnu* | \ kopensolaris*-gnu* | \ storm-chaos* | os2-emx* | rtmk-nova*) os=-$maybe_os basic_machine=`echo $1 | sed 's/^\(.*\)-\([^-]*-[^-]*\)$/\1/'` ;; android-linux) os=-linux-android basic_machine=`echo $1 | sed 's/^\(.*\)-\([^-]*-[^-]*\)$/\1/'`-unknown ;; *) basic_machine=`echo $1 | sed 's/-[^-]*$//'` if [ $basic_machine != $1 ] then os=`echo $1 | sed 's/.*-/-/'` else os=; fi ;; esac ### Let's recognize common machines as not being operating systems so ### that things like config.sub decstation-3100 work. We also ### recognize some manufacturers as not being operating systems, so we ### can provide default operating systems below. case $os in -sun*os*) # Prevent following clause from handling this invalid input. ;; -dec* | -mips* | -sequent* | -encore* | -pc532* | -sgi* | -sony* | \ -att* | -7300* | -3300* | -delta* | -motorola* | -sun[234]* | \ -unicom* | -ibm* | -next | -hp | -isi* | -apollo | -altos* | \ -convergent* | -ncr* | -news | -32* | -3600* | -3100* | -hitachi* |\ -c[123]* | -convex* | -sun | -crds | -omron* | -dg | -ultra | -tti* | \ -harris | -dolphin | -highlevel | -gould | -cbm | -ns | -masscomp | \ -apple | -axis | -knuth | -cray | -microblaze*) os= basic_machine=$1 ;; -bluegene*) os=-cnk ;; -sim | -cisco | -oki | -wec | -winbond) os= basic_machine=$1 ;; -scout) ;; -wrs) os=-vxworks basic_machine=$1 ;; -chorusos*) os=-chorusos basic_machine=$1 ;; -chorusrdb) os=-chorusrdb basic_machine=$1 ;; -hiux*) os=-hiuxwe2 ;; -sco6) os=-sco5v6 basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco5) os=-sco3.2v5 basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco4) os=-sco3.2v4 basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco3.2.[4-9]*) os=`echo $os | sed -e 's/sco3.2./sco3.2v/'` basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco3.2v[4-9]*) # Don't forget version if it is 3.2v4 or newer. basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco5v6*) # Don't forget version if it is 3.2v4 or newer. basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -sco*) os=-sco3.2v2 basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -udk*) basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -isc) os=-isc2.2 basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -clix*) basic_machine=clipper-intergraph ;; -isc*) basic_machine=`echo $1 | sed -e 's/86-.*/86-pc/'` ;; -lynx*178) os=-lynxos178 ;; -lynx*5) os=-lynxos5 ;; -lynx*) os=-lynxos ;; -ptx*) basic_machine=`echo $1 | sed -e 's/86-.*/86-sequent/'` ;; -windowsnt*) os=`echo $os | sed -e 's/windowsnt/winnt/'` ;; -psos*) os=-psos ;; -mint | -mint[0-9]*) basic_machine=m68k-atari os=-mint ;; esac # Decode aliases for certain CPU-COMPANY combinations. case $basic_machine in # Recognize the basic CPU types without company name. # Some are omitted here because they have special meanings below. 1750a | 580 \ | a29k \ | aarch64 | aarch64_be \ | alpha | alphaev[4-8] | alphaev56 | alphaev6[78] | alphapca5[67] \ | alpha64 | alpha64ev[4-8] | alpha64ev56 | alpha64ev6[78] | alpha64pca5[67] \ | am33_2.0 \ | arc | arceb \ | arm | arm[bl]e | arme[lb] | armv[2-8] | armv[3-8][lb] | armv7[arm] \ | avr | avr32 \ | be32 | be64 \ | bfin \ | c4x | c8051 | clipper \ | d10v | d30v | dlx | dsp16xx \ | epiphany \ | fido | fr30 | frv \ | h8300 | h8500 | hppa | hppa1.[01] | hppa2.0 | hppa2.0[nw] | hppa64 \ | hexagon \ | i370 | i860 | i960 | ia64 \ | ip2k | iq2000 \ | k1om \ | le32 | le64 \ | lm32 \ | m32c | m32r | m32rle | m68000 | m68k | m88k \ | maxq | mb | microblaze | microblazeel | mcore | mep | metag \ | mips | mipsbe | mipseb | mipsel | mipsle \ | mips16 \ | mips64 | mips64el \ | mips64octeon | mips64octeonel \ | mips64orion | mips64orionel \ | mips64r5900 | mips64r5900el \ | mips64vr | mips64vrel \ | mips64vr4100 | mips64vr4100el \ | mips64vr4300 | mips64vr4300el \ | mips64vr5000 | mips64vr5000el \ | mips64vr5900 | mips64vr5900el \ | mipsisa32 | mipsisa32el \ | mipsisa32r2 | mipsisa32r2el \ | mipsisa64 | mipsisa64el \ | mipsisa64r2 | mipsisa64r2el \ | mipsisa64sb1 | mipsisa64sb1el \ | mipsisa64sr71k | mipsisa64sr71kel \ | mipsr5900 | mipsr5900el \ | mipstx39 | mipstx39el \ | mn10200 | mn10300 \ | moxie \ | mt \ | msp430 \ | nds32 | nds32le | nds32be \ | nios | nios2 | nios2eb | nios2el \ | ns16k | ns32k \ | open8 \ | or1k | or32 \ | pdp10 | pdp11 | pj | pjl \ | powerpc | powerpc64 | powerpc64le | powerpcle \ | pyramid \ | rl78 | rx \ | score \ | sh | sh[1234] | sh[24]a | sh[24]aeb | sh[23]e | sh[34]eb | sheb | shbe | shle | sh[1234]le | sh3ele \ | sh64 | sh64le \ | sparc | sparc64 | sparc64b | sparc64v | sparc86x | sparclet | sparclite \ | sparcv8 | sparcv9 | sparcv9b | sparcv9v \ | spu \ | tahoe | tic4x | tic54x | tic55x | tic6x | tic80 | tron \ | ubicom32 \ | v850 | v850e | v850e1 | v850e2 | v850es | v850e2v3 \ | we32k \ | x86 | xc16x | xstormy16 | xtensa \ | z8k | z80) basic_machine=$basic_machine-unknown ;; c54x) basic_machine=tic54x-unknown ;; c55x) basic_machine=tic55x-unknown ;; c6x) basic_machine=tic6x-unknown ;; m6811 | m68hc11 | m6812 | m68hc12 | m68hcs12x | nvptx | picochip) basic_machine=$basic_machine-unknown os=-none ;; m88110 | m680[12346]0 | m683?2 | m68360 | m5200 | v70 | w65 | z8k) ;; ms1) basic_machine=mt-unknown ;; strongarm | thumb | xscale) basic_machine=arm-unknown ;; xgate) basic_machine=$basic_machine-unknown os=-none ;; xscaleeb) basic_machine=armeb-unknown ;; xscaleel) basic_machine=armel-unknown ;; # We use `pc' rather than `unknown' # because (1) that's what they normally are, and # (2) the word "unknown" tends to confuse beginning users. i*86 | x86_64) basic_machine=$basic_machine-pc ;; # Object if more than one company name word. *-*-*) echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 exit 1 ;; # Recognize the basic CPU types with company name. 580-* \ | a29k-* \ | aarch64-* | aarch64_be-* \ | alpha-* | alphaev[4-8]-* | alphaev56-* | alphaev6[78]-* \ | alpha64-* | alpha64ev[4-8]-* | alpha64ev56-* | alpha64ev6[78]-* \ | alphapca5[67]-* | alpha64pca5[67]-* | arc-* | arceb-* \ | arm-* | armbe-* | armle-* | armeb-* | armv*-* \ | avr-* | avr32-* \ | be32-* | be64-* \ | bfin-* | bs2000-* \ | c[123]* | c30-* | [cjt]90-* | c4x-* \ | c8051-* | clipper-* | craynv-* | cydra-* \ | d10v-* | d30v-* | dlx-* \ | elxsi-* \ | f30[01]-* | f700-* | fido-* | fr30-* | frv-* | fx80-* \ | h8300-* | h8500-* \ | hppa-* | hppa1.[01]-* | hppa2.0-* | hppa2.0[nw]-* | hppa64-* \ | hexagon-* \ | i*86-* | i860-* | i960-* | ia64-* \ | ip2k-* | iq2000-* \ | k1om-* \ | le32-* | le64-* \ | lm32-* \ | m32c-* | m32r-* | m32rle-* \ | m68000-* | m680[012346]0-* | m68360-* | m683?2-* | m68k-* \ | m88110-* | m88k-* | maxq-* | mcore-* | metag-* \ | microblaze-* | microblazeel-* \ | mips-* | mipsbe-* | mipseb-* | mipsel-* | mipsle-* \ | mips16-* \ | mips64-* | mips64el-* \ | mips64octeon-* | mips64octeonel-* \ | mips64orion-* | mips64orionel-* \ | mips64r5900-* | mips64r5900el-* \ | mips64vr-* | mips64vrel-* \ | mips64vr4100-* | mips64vr4100el-* \ | mips64vr4300-* | mips64vr4300el-* \ | mips64vr5000-* | mips64vr5000el-* \ | mips64vr5900-* | mips64vr5900el-* \ | mipsisa32-* | mipsisa32el-* \ | mipsisa32r2-* | mipsisa32r2el-* \ | mipsisa64-* | mipsisa64el-* \ | mipsisa64r2-* | mipsisa64r2el-* \ | mipsisa64sb1-* | mipsisa64sb1el-* \ | mipsisa64sr71k-* | mipsisa64sr71kel-* \ | mipsr5900-* | mipsr5900el-* \ | mipstx39-* | mipstx39el-* \ | mmix-* \ | mt-* \ | msp430-* \ | nds32-* | nds32le-* | nds32be-* \ | nios-* | nios2-* | nios2eb-* | nios2el-* \ | none-* | np1-* | ns16k-* | ns32k-* \ | open8-* \ | orion-* \ | pdp10-* | pdp11-* | pj-* | pjl-* | pn-* | power-* \ | powerpc-* | powerpc64-* | powerpc64le-* | powerpcle-* \ | pyramid-* \ | rl78-* | romp-* | rs6000-* | rx-* \ | sh-* | sh[1234]-* | sh[24]a-* | sh[24]aeb-* | sh[23]e-* | sh[34]eb-* | sheb-* | shbe-* \ | shle-* | sh[1234]le-* | sh3ele-* | sh64-* | sh64le-* \ | sparc-* | sparc64-* | sparc64b-* | sparc64v-* | sparc86x-* | sparclet-* \ | sparclite-* \ | sparcv8-* | sparcv9-* | sparcv9b-* | sparcv9v-* | sv1-* | sx?-* \ | tahoe-* \ | tic30-* | tic4x-* | tic54x-* | tic55x-* | tic6x-* | tic80-* \ | tile*-* \ | tron-* \ | ubicom32-* \ | v850-* | v850e-* | v850e1-* | v850es-* | v850e2-* | v850e2v3-* \ | vax-* \ | we32k-* \ | x86-* | x86_64-* | xc16x-* | xps100-* \ | xstormy16-* | xtensa*-* \ | ymp-* \ | z8k-* | z80-*) ;; # Recognize the basic CPU types without company name, with glob match. xtensa*) basic_machine=$basic_machine-unknown ;; # Recognize the various machine names and aliases which stand # for a CPU type and a company and sometimes even an OS. 386bsd) basic_machine=i386-unknown os=-bsd ;; 3b1 | 7300 | 7300-att | att-7300 | pc7300 | safari | unixpc) basic_machine=m68000-att ;; 3b*) basic_machine=we32k-att ;; a29khif) basic_machine=a29k-amd os=-udi ;; abacus) basic_machine=abacus-unknown ;; adobe68k) basic_machine=m68010-adobe os=-scout ;; alliant | fx80) basic_machine=fx80-alliant ;; altos | altos3068) basic_machine=m68k-altos ;; am29k) basic_machine=a29k-none os=-bsd ;; amd64) basic_machine=x86_64-pc ;; amd64-*) basic_machine=x86_64-`echo $basic_machine | sed 's/^[^-]*-//'` ;; amdahl) basic_machine=580-amdahl os=-sysv ;; amiga | amiga-*) basic_machine=m68k-unknown ;; amigaos | amigados) basic_machine=m68k-unknown os=-amigaos ;; amigaunix | amix) basic_machine=m68k-unknown os=-sysv4 ;; apollo68) basic_machine=m68k-apollo os=-sysv ;; apollo68bsd) basic_machine=m68k-apollo os=-bsd ;; aros) basic_machine=i386-pc os=-aros ;; aux) basic_machine=m68k-apple os=-aux ;; balance) basic_machine=ns32k-sequent os=-dynix ;; blackfin) basic_machine=bfin-unknown os=-linux ;; blackfin-*) basic_machine=bfin-`echo $basic_machine | sed 's/^[^-]*-//'` os=-linux ;; bluegene*) basic_machine=powerpc-ibm os=-cnk ;; c54x-*) basic_machine=tic54x-`echo $basic_machine | sed 's/^[^-]*-//'` ;; c55x-*) basic_machine=tic55x-`echo $basic_machine | sed 's/^[^-]*-//'` ;; c6x-*) basic_machine=tic6x-`echo $basic_machine | sed 's/^[^-]*-//'` ;; c90) basic_machine=c90-cray os=-unicos ;; cegcc) basic_machine=arm-unknown os=-cegcc ;; convex-c1) basic_machine=c1-convex os=-bsd ;; convex-c2) basic_machine=c2-convex os=-bsd ;; convex-c32) basic_machine=c32-convex os=-bsd ;; convex-c34) basic_machine=c34-convex os=-bsd ;; convex-c38) basic_machine=c38-convex os=-bsd ;; cray | j90) basic_machine=j90-cray os=-unicos ;; craynv) basic_machine=craynv-cray os=-unicosmp ;; cr16 | cr16-*) basic_machine=cr16-unknown os=-elf ;; crds | unos) basic_machine=m68k-crds ;; crisv32 | crisv32-* | etraxfs*) basic_machine=crisv32-axis ;; cris | cris-* | etrax*) basic_machine=cris-axis ;; crx) basic_machine=crx-unknown os=-elf ;; da30 | da30-*) basic_machine=m68k-da30 ;; decstation | decstation-3100 | pmax | pmax-* | pmin | dec3100 | decstatn) basic_machine=mips-dec ;; decsystem10* | dec10*) basic_machine=pdp10-dec os=-tops10 ;; decsystem20* | dec20*) basic_machine=pdp10-dec os=-tops20 ;; delta | 3300 | motorola-3300 | motorola-delta \ | 3300-motorola | delta-motorola) basic_machine=m68k-motorola ;; delta88) basic_machine=m88k-motorola os=-sysv3 ;; dicos) basic_machine=i686-pc os=-dicos ;; djgpp) basic_machine=i586-pc os=-msdosdjgpp ;; dpx20 | dpx20-*) basic_machine=rs6000-bull os=-bosx ;; dpx2* | dpx2*-bull) basic_machine=m68k-bull os=-sysv3 ;; ebmon29k) basic_machine=a29k-amd os=-ebmon ;; elxsi) basic_machine=elxsi-elxsi os=-bsd ;; encore | umax | mmax) basic_machine=ns32k-encore ;; es1800 | OSE68k | ose68k | ose | OSE) basic_machine=m68k-ericsson os=-ose ;; fx2800) basic_machine=i860-alliant ;; genix) basic_machine=ns32k-ns ;; gmicro) basic_machine=tron-gmicro os=-sysv ;; go32) basic_machine=i386-pc os=-go32 ;; h3050r* | hiux*) basic_machine=hppa1.1-hitachi os=-hiuxwe2 ;; h8300hms) basic_machine=h8300-hitachi os=-hms ;; h8300xray) basic_machine=h8300-hitachi os=-xray ;; h8500hms) basic_machine=h8500-hitachi os=-hms ;; harris) basic_machine=m88k-harris os=-sysv3 ;; hp300-*) basic_machine=m68k-hp ;; hp300bsd) basic_machine=m68k-hp os=-bsd ;; hp300hpux) basic_machine=m68k-hp os=-hpux ;; hp3k9[0-9][0-9] | hp9[0-9][0-9]) basic_machine=hppa1.0-hp ;; hp9k2[0-9][0-9] | hp9k31[0-9]) basic_machine=m68000-hp ;; hp9k3[2-9][0-9]) basic_machine=m68k-hp ;; hp9k6[0-9][0-9] | hp6[0-9][0-9]) basic_machine=hppa1.0-hp ;; hp9k7[0-79][0-9] | hp7[0-79][0-9]) basic_machine=hppa1.1-hp ;; hp9k78[0-9] | hp78[0-9]) # FIXME: really hppa2.0-hp basic_machine=hppa1.1-hp ;; hp9k8[67]1 | hp8[67]1 | hp9k80[24] | hp80[24] | hp9k8[78]9 | hp8[78]9 | hp9k893 | hp893) # FIXME: really hppa2.0-hp basic_machine=hppa1.1-hp ;; hp9k8[0-9][13679] | hp8[0-9][13679]) basic_machine=hppa1.1-hp ;; hp9k8[0-9][0-9] | hp8[0-9][0-9]) basic_machine=hppa1.0-hp ;; hppa-next) os=-nextstep3 ;; hppaosf) basic_machine=hppa1.1-hp os=-osf ;; hppro) basic_machine=hppa1.1-hp os=-proelf ;; i370-ibm* | ibm*) basic_machine=i370-ibm ;; i*86v32) basic_machine=`echo $1 | sed -e 's/86.*/86-pc/'` os=-sysv32 ;; i*86v4*) basic_machine=`echo $1 | sed -e 's/86.*/86-pc/'` os=-sysv4 ;; i*86v) basic_machine=`echo $1 | sed -e 's/86.*/86-pc/'` os=-sysv ;; i*86sol2) basic_machine=`echo $1 | sed -e 's/86.*/86-pc/'` os=-solaris2 ;; i386mach) basic_machine=i386-mach os=-mach ;; i386-vsta | vsta) basic_machine=i386-unknown os=-vsta ;; iris | iris4d) basic_machine=mips-sgi case $os in -irix*) ;; *) os=-irix4 ;; esac ;; isi68 | isi) basic_machine=m68k-isi os=-sysv ;; m68knommu) basic_machine=m68k-unknown os=-linux ;; m68knommu-*) basic_machine=m68k-`echo $basic_machine | sed 's/^[^-]*-//'` os=-linux ;; m88k-omron*) basic_machine=m88k-omron ;; magnum | m3230) basic_machine=mips-mips os=-sysv ;; merlin) basic_machine=ns32k-utek os=-sysv ;; microblaze*) basic_machine=microblaze-xilinx ;; mingw64) basic_machine=x86_64-pc os=-mingw64 ;; mingw32) basic_machine=i686-pc os=-mingw32 ;; mingw32ce) basic_machine=arm-unknown os=-mingw32ce ;; miniframe) basic_machine=m68000-convergent ;; *mint | -mint[0-9]* | *MiNT | *MiNT[0-9]*) basic_machine=m68k-atari os=-mint ;; mips3*-*) basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'` ;; mips3*) basic_machine=`echo $basic_machine | sed -e 's/mips3/mips64/'`-unknown ;; monitor) basic_machine=m68k-rom68k os=-coff ;; morphos) basic_machine=powerpc-unknown os=-morphos ;; msdos) basic_machine=i386-pc os=-msdos ;; ms1-*) basic_machine=`echo $basic_machine | sed -e 's/ms1-/mt-/'` ;; msys) basic_machine=i686-pc os=-msys ;; mvs) basic_machine=i370-ibm os=-mvs ;; nacl) basic_machine=le32-unknown os=-nacl ;; ncr3000) basic_machine=i486-ncr os=-sysv4 ;; netbsd386) basic_machine=i386-unknown os=-netbsd ;; netwinder) basic_machine=armv4l-rebel os=-linux ;; news | news700 | news800 | news900) basic_machine=m68k-sony os=-newsos ;; news1000) basic_machine=m68030-sony os=-newsos ;; news-3600 | risc-news) basic_machine=mips-sony os=-newsos ;; necv70) basic_machine=v70-nec os=-sysv ;; next | m*-next ) basic_machine=m68k-next case $os in -nextstep* ) ;; -ns2*) os=-nextstep2 ;; *) os=-nextstep3 ;; esac ;; nh3000) basic_machine=m68k-harris os=-cxux ;; nh[45]000) basic_machine=m88k-harris os=-cxux ;; nindy960) basic_machine=i960-intel os=-nindy ;; mon960) basic_machine=i960-intel os=-mon960 ;; nonstopux) basic_machine=mips-compaq os=-nonstopux ;; np1) basic_machine=np1-gould ;; neo-tandem) basic_machine=neo-tandem ;; nse-tandem) basic_machine=nse-tandem ;; nsr-tandem) basic_machine=nsr-tandem ;; op50n-* | op60c-*) basic_machine=hppa1.1-oki os=-proelf ;; openrisc | openrisc-*) basic_machine=or32-unknown ;; os400) basic_machine=powerpc-ibm os=-os400 ;; OSE68000 | ose68000) basic_machine=m68000-ericsson os=-ose ;; os68k) basic_machine=m68k-none os=-os68k ;; pa-hitachi) basic_machine=hppa1.1-hitachi os=-hiuxwe2 ;; paragon) basic_machine=i860-intel os=-osf ;; parisc) basic_machine=hppa-unknown os=-linux ;; parisc-*) basic_machine=hppa-`echo $basic_machine | sed 's/^[^-]*-//'` os=-linux ;; pbd) basic_machine=sparc-tti ;; pbb) basic_machine=m68k-tti ;; pc532 | pc532-*) basic_machine=ns32k-pc532 ;; pc98) basic_machine=i386-pc ;; pc98-*) basic_machine=i386-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pentium | p5 | k5 | k6 | nexgen | viac3) basic_machine=i586-pc ;; pentiumpro | p6 | 6x86 | athlon | athlon_*) basic_machine=i686-pc ;; pentiumii | pentium2 | pentiumiii | pentium3) basic_machine=i686-pc ;; pentium4) basic_machine=i786-pc ;; pentium-* | p5-* | k5-* | k6-* | nexgen-* | viac3-*) basic_machine=i586-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pentiumpro-* | p6-* | 6x86-* | athlon-*) basic_machine=i686-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pentiumii-* | pentium2-* | pentiumiii-* | pentium3-*) basic_machine=i686-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pentium4-*) basic_machine=i786-`echo $basic_machine | sed 's/^[^-]*-//'` ;; pn) basic_machine=pn-gould ;; power) basic_machine=power-ibm ;; ppc | ppcbe) basic_machine=powerpc-unknown ;; ppc-* | ppcbe-*) basic_machine=powerpc-`echo $basic_machine | sed 's/^[^-]*-//'` ;; ppcle | powerpclittle | ppc-le | powerpc-little) basic_machine=powerpcle-unknown ;; ppcle-* | powerpclittle-*) basic_machine=powerpcle-`echo $basic_machine | sed 's/^[^-]*-//'` ;; ppc64) basic_machine=powerpc64-unknown ;; ppc64-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'` ;; ppc64le | powerpc64little | ppc64-le | powerpc64-little) basic_machine=powerpc64le-unknown ;; ppc64le-* | powerpc64little-*) basic_machine=powerpc64le-`echo $basic_machine | sed 's/^[^-]*-//'` ;; ps2) basic_machine=i386-ibm ;; pw32) basic_machine=i586-unknown os=-pw32 ;; rdos | rdos64) basic_machine=x86_64-pc os=-rdos ;; rdos32) basic_machine=i386-pc os=-rdos ;; rom68k) basic_machine=m68k-rom68k os=-coff ;; rm[46]00) basic_machine=mips-siemens ;; rtpc | rtpc-*) basic_machine=romp-ibm ;; s390 | s390-*) basic_machine=s390-ibm ;; s390x | s390x-*) basic_machine=s390x-ibm ;; sa29200) basic_machine=a29k-amd os=-udi ;; sb1) basic_machine=mipsisa64sb1-unknown ;; sb1el) basic_machine=mipsisa64sb1el-unknown ;; sde) basic_machine=mipsisa32-sde os=-elf ;; sei) basic_machine=mips-sei os=-seiux ;; sequent) basic_machine=i386-sequent ;; sh) basic_machine=sh-hitachi os=-hms ;; sh5el) basic_machine=sh5le-unknown ;; sh64) basic_machine=sh64-unknown ;; sparclite-wrs | simso-wrs) basic_machine=sparclite-wrs os=-vxworks ;; sps7) basic_machine=m68k-bull os=-sysv2 ;; spur) basic_machine=spur-unknown ;; st2000) basic_machine=m68k-tandem ;; stratus) basic_machine=i860-stratus os=-sysv4 ;; strongarm-* | thumb-*) basic_machine=arm-`echo $basic_machine | sed 's/^[^-]*-//'` ;; sun2) basic_machine=m68000-sun ;; sun2os3) basic_machine=m68000-sun os=-sunos3 ;; sun2os4) basic_machine=m68000-sun os=-sunos4 ;; sun3os3) basic_machine=m68k-sun os=-sunos3 ;; sun3os4) basic_machine=m68k-sun os=-sunos4 ;; sun4os3) basic_machine=sparc-sun os=-sunos3 ;; sun4os4) basic_machine=sparc-sun os=-sunos4 ;; sun4sol2) basic_machine=sparc-sun os=-solaris2 ;; sun3 | sun3-*) basic_machine=m68k-sun ;; sun4) basic_machine=sparc-sun ;; sun386 | sun386i | roadrunner) basic_machine=i386-sun ;; sv1) basic_machine=sv1-cray os=-unicos ;; symmetry) basic_machine=i386-sequent os=-dynix ;; t3e) basic_machine=alphaev5-cray os=-unicos ;; t90) basic_machine=t90-cray os=-unicos ;; tile*) basic_machine=$basic_machine-unknown os=-linux-gnu ;; tx39) basic_machine=mipstx39-unknown ;; tx39el) basic_machine=mipstx39el-unknown ;; toad1) basic_machine=pdp10-xkl os=-tops20 ;; tower | tower-32) basic_machine=m68k-ncr ;; tpf) basic_machine=s390x-ibm os=-tpf ;; udi29k) basic_machine=a29k-amd os=-udi ;; ultra3) basic_machine=a29k-nyu os=-sym1 ;; v810 | necv810) basic_machine=v810-nec os=-none ;; vaxv) basic_machine=vax-dec os=-sysv ;; vms) basic_machine=vax-dec os=-vms ;; vpp*|vx|vx-*) basic_machine=f301-fujitsu ;; vxworks960) basic_machine=i960-wrs os=-vxworks ;; vxworks68) basic_machine=m68k-wrs os=-vxworks ;; vxworks29k) basic_machine=a29k-wrs os=-vxworks ;; w65*) basic_machine=w65-wdc os=-none ;; w89k-*) basic_machine=hppa1.1-winbond os=-proelf ;; xbox) basic_machine=i686-pc os=-mingw32 ;; xps | xps100) basic_machine=xps100-honeywell ;; xscale-* | xscalee[bl]-*) basic_machine=`echo $basic_machine | sed 's/^xscale/arm/'` ;; ymp) basic_machine=ymp-cray os=-unicos ;; z8k-*-coff) basic_machine=z8k-unknown os=-sim ;; z80-*-coff) basic_machine=z80-unknown os=-sim ;; none) basic_machine=none-none os=-none ;; # Here we handle the default manufacturer of certain CPU types. It is in # some cases the only manufacturer, in others, it is the most popular. w89k) basic_machine=hppa1.1-winbond ;; op50n) basic_machine=hppa1.1-oki ;; op60c) basic_machine=hppa1.1-oki ;; romp) basic_machine=romp-ibm ;; mmix) basic_machine=mmix-knuth ;; rs6000) basic_machine=rs6000-ibm ;; vax) basic_machine=vax-dec ;; pdp10) # there are many clones, so DEC is not a safe bet basic_machine=pdp10-unknown ;; pdp11) basic_machine=pdp11-dec ;; we32k) basic_machine=we32k-att ;; sh[1234] | sh[24]a | sh[24]aeb | sh[34]eb | sh[1234]le | sh[23]ele) basic_machine=sh-unknown ;; sparc | sparcv8 | sparcv9 | sparcv9b | sparcv9v) basic_machine=sparc-sun ;; cydra) basic_machine=cydra-cydrome ;; orion) basic_machine=orion-highlevel ;; orion105) basic_machine=clipper-highlevel ;; mac | mpw | mac-mpw) basic_machine=m68k-apple ;; pmac | pmac-mpw) basic_machine=powerpc-apple ;; *-unknown) # Make sure to match an already-canonicalized machine name. ;; *) echo Invalid configuration \`$1\': machine \`$basic_machine\' not recognized 1>&2 exit 1 ;; esac # Here we canonicalize certain aliases for manufacturers. case $basic_machine in *-digital*) basic_machine=`echo $basic_machine | sed 's/digital.*/dec/'` ;; *-commodore*) basic_machine=`echo $basic_machine | sed 's/commodore.*/cbm/'` ;; *) ;; esac # Decode manufacturer-specific aliases for certain operating systems. if [ x"$os" != x"" ] then case $os in # First match some system type aliases # that might get confused with valid system types. # -solaris* is a basic system type, with this one exception. -auroraux) os=-auroraux ;; -solaris1 | -solaris1.*) os=`echo $os | sed -e 's|solaris1|sunos4|'` ;; -solaris) os=-solaris2 ;; -svr4*) os=-sysv4 ;; -unixware*) os=-sysv4.2uw ;; -gnu/linux*) os=`echo $os | sed -e 's|gnu/linux|linux-gnu|'` ;; # First accept the basic system types. # The portable systems comes first. # Each alternative MUST END IN A *, to match a version number. # -sysv* is not here because it comes later, after sysvr4. -gnu* | -bsd* | -mach* | -minix* | -genix* | -ultrix* | -irix* \ | -*vms* | -sco* | -esix* | -isc* | -aix* | -cnk* | -sunos | -sunos[34]*\ | -hpux* | -unos* | -osf* | -luna* | -dgux* | -auroraux* | -solaris* \ | -sym* | -kopensolaris* | -plan9* \ | -amigaos* | -amigados* | -msdos* | -newsos* | -unicos* | -aof* \ | -aos* | -aros* \ | -nindy* | -vxsim* | -vxworks* | -ebmon* | -hms* | -mvs* \ | -clix* | -riscos* | -uniplus* | -iris* | -rtu* | -xenix* \ | -hiux* | -386bsd* | -knetbsd* | -mirbsd* | -netbsd* \ | -bitrig* | -openbsd* | -solidbsd* \ | -ekkobsd* | -kfreebsd* | -freebsd* | -riscix* | -lynxos* \ | -bosx* | -nextstep* | -cxux* | -aout* | -elf* | -oabi* \ | -ptx* | -coff* | -ecoff* | -winnt* | -domain* | -vsta* \ | -udi* | -eabi* | -lites* | -ieee* | -go32* | -aux* \ | -chorusos* | -chorusrdb* | -cegcc* \ | -cygwin* | -msys* | -pe* | -psos* | -moss* | -proelf* | -rtems* \ | -mingw32* | -mingw64* | -linux-gnu* | -linux-android* \ | -linux-newlib* | -linux-musl* | -linux-uclibc* \ | -uxpv* | -beos* | -mpeix* | -udk* \ | -interix* | -uwin* | -mks* | -rhapsody* | -darwin* | -opened* \ | -openstep* | -oskit* | -conix* | -pw32* | -nonstopux* \ | -storm-chaos* | -tops10* | -tenex* | -tops20* | -its* \ | -os2* | -vos* | -palmos* | -uclinux* | -nucleus* \ | -morphos* | -superux* | -rtmk* | -rtmk-nova* | -windiss* \ | -powermax* | -dnix* | -nx6 | -nx7 | -sei* | -dragonfly* \ | -skyos* | -haiku* | -rdos* | -toppers* | -drops* | -es*) # Remember, each alternative MUST END IN *, to match a version number. ;; -qnx*) case $basic_machine in x86-* | i*86-*) ;; *) os=-nto$os ;; esac ;; -nto-qnx*) ;; -nto*) os=`echo $os | sed -e 's|nto|nto-qnx|'` ;; -sim | -es1800* | -hms* | -xray | -os68k* | -none* | -v88r* \ | -windows* | -osx | -abug | -netware* | -os9* | -beos* | -haiku* \ | -macos* | -mpw* | -magic* | -mmixware* | -mon960* | -lnews*) ;; -mac*) os=`echo $os | sed -e 's|mac|macos|'` ;; -linux-dietlibc) os=-linux-dietlibc ;; -linux*) os=`echo $os | sed -e 's|linux|linux-gnu|'` ;; -sunos5*) os=`echo $os | sed -e 's|sunos5|solaris2|'` ;; -sunos6*) os=`echo $os | sed -e 's|sunos6|solaris3|'` ;; -opened*) os=-openedition ;; -os400*) os=-os400 ;; -wince*) os=-wince ;; -osfrose*) os=-osfrose ;; -osf*) os=-osf ;; -utek*) os=-bsd ;; -dynix*) os=-bsd ;; -acis*) os=-aos ;; -atheos*) os=-atheos ;; -syllable*) os=-syllable ;; -386bsd) os=-bsd ;; -ctix* | -uts*) os=-sysv ;; -nova*) os=-rtmk-nova ;; -ns2 ) os=-nextstep2 ;; -nsk*) os=-nsk ;; # Preserve the version number of sinix5. -sinix5.*) os=`echo $os | sed -e 's|sinix|sysv|'` ;; -sinix*) os=-sysv4 ;; -tpf*) os=-tpf ;; -triton*) os=-sysv3 ;; -oss*) os=-sysv3 ;; -svr4) os=-sysv4 ;; -svr3) os=-sysv3 ;; -sysvr4) os=-sysv4 ;; # This must come after -sysvr4. -sysv*) ;; -ose*) os=-ose ;; -es1800*) os=-ose ;; -xenix) os=-xenix ;; -*mint | -mint[0-9]* | -*MiNT | -MiNT[0-9]*) os=-mint ;; -aros*) os=-aros ;; -zvmoe) os=-zvmoe ;; -dicos*) os=-dicos ;; -nacl*) ;; -none) ;; *) # Get rid of the `-' at the beginning of $os. os=`echo $os | sed 's/[^-]*-//'` echo Invalid configuration \`$1\': system \`$os\' not recognized 1>&2 exit 1 ;; esac else # Here we handle the default operating systems that come with various machines. # The value should be what the vendor currently ships out the door with their # machine or put another way, the most popular os provided with the machine. # Note that if you're going to try to match "-MANUFACTURER" here (say, # "-sun"), then you have to tell the case statement up towards the top # that MANUFACTURER isn't an operating system. Otherwise, code above # will signal an error saying that MANUFACTURER isn't an operating # system, and we'll never get to this point. case $basic_machine in score-*) os=-elf ;; spu-*) os=-elf ;; *-acorn) os=-riscix1.2 ;; arm*-rebel) os=-linux ;; arm*-semi) os=-aout ;; c4x-* | tic4x-*) os=-coff ;; c8051-*) os=-elf ;; hexagon-*) os=-elf ;; tic54x-*) os=-coff ;; tic55x-*) os=-coff ;; tic6x-*) os=-coff ;; # This must come before the *-dec entry. pdp10-*) os=-tops20 ;; pdp11-*) os=-none ;; *-dec | vax-*) os=-ultrix4.2 ;; m68*-apollo) os=-domain ;; i386-sun) os=-sunos4.0.2 ;; m68000-sun) os=-sunos3 ;; m68*-cisco) os=-aout ;; mep-*) os=-elf ;; mips*-cisco) os=-elf ;; mips*-*) os=-elf ;; or1k-*) os=-elf ;; or32-*) os=-coff ;; *-tti) # must be before sparc entry or we get the wrong os. os=-sysv3 ;; sparc-* | *-sun) os=-sunos4.1.1 ;; *-be) os=-beos ;; *-haiku) os=-haiku ;; *-ibm) os=-aix ;; *-knuth) os=-mmixware ;; *-wec) os=-proelf ;; *-winbond) os=-proelf ;; *-oki) os=-proelf ;; *-hp) os=-hpux ;; *-hitachi) os=-hiux ;; i860-* | *-att | *-ncr | *-altos | *-motorola | *-convergent) os=-sysv ;; *-cbm) os=-amigaos ;; *-dg) os=-dgux ;; *-dolphin) os=-sysv3 ;; m68k-ccur) os=-rtu ;; m88k-omron*) os=-luna ;; *-next ) os=-nextstep ;; *-sequent) os=-ptx ;; *-crds) os=-unos ;; *-ns) os=-genix ;; i370-*) os=-mvs ;; *-next) os=-nextstep3 ;; *-gould) os=-sysv ;; *-highlevel) os=-bsd ;; *-encore) os=-bsd ;; *-sgi) os=-irix ;; *-siemens) os=-sysv4 ;; *-masscomp) os=-rtu ;; f30[01]-fujitsu | f700-fujitsu) os=-uxpv ;; *-rom68k) os=-coff ;; *-*bug) os=-coff ;; *-apple) os=-macos ;; *-atari*) os=-mint ;; *) os=-none ;; esac fi # Here we handle the case where we know the os, and the CPU type, but not the # manufacturer. We pick the logical manufacturer. vendor=unknown case $basic_machine in *-unknown) case $os in -riscix*) vendor=acorn ;; -sunos*) vendor=sun ;; -cnk*|-aix*) vendor=ibm ;; -beos*) vendor=be ;; -hpux*) vendor=hp ;; -mpeix*) vendor=hp ;; -hiux*) vendor=hitachi ;; -unos*) vendor=crds ;; -dgux*) vendor=dg ;; -luna*) vendor=omron ;; -genix*) vendor=ns ;; -mvs* | -opened*) vendor=ibm ;; -os400*) vendor=ibm ;; -ptx*) vendor=sequent ;; -tpf*) vendor=ibm ;; -vxsim* | -vxworks* | -windiss*) vendor=wrs ;; -aux*) vendor=apple ;; -hms*) vendor=hitachi ;; -mpw* | -macos*) vendor=apple ;; -*mint | -mint[0-9]* | -*MiNT | -MiNT[0-9]*) vendor=atari ;; -vos*) vendor=stratus ;; esac basic_machine=`echo $basic_machine | sed "s/unknown/$vendor/"` ;; esac echo $basic_machine$os exit # Local variables: # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "timestamp='" # time-stamp-format: "%:y-%02m-%02d" # time-stamp-end: "'" # End: ast-8.3.0/build-aux/ltmain.sh0000644000175000017500000105152212710131171012744 00000000000000 # libtool (GNU libtool) 2.4.2 # Written by Gordon Matzigkeit , 1996 # Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006, # 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. # This is free software; see the source for copying conditions. There is NO # warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. # GNU Libtool is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # As a special exception to the GNU General Public License, # if you distribute this file as part of a program or library that # is built using GNU Libtool, you may include this file under the # same distribution terms that you use for the rest of that program. # # GNU Libtool 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 # General Public License for more details. # # You should have received a copy of the GNU General Public License # along with GNU Libtool; see the file COPYING. If not, a copy # can be downloaded from http://www.gnu.org/licenses/gpl.html, # or obtained by writing to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # Usage: $progname [OPTION]... [MODE-ARG]... # # Provide generalized library-building support services. # # --config show all configuration variables # --debug enable verbose shell tracing # -n, --dry-run display commands without modifying any files # --features display basic configuration information and exit # --mode=MODE use operation mode MODE # --preserve-dup-deps don't remove duplicate dependency libraries # --quiet, --silent don't print informational messages # --no-quiet, --no-silent # print informational messages (default) # --no-warn don't display warning messages # --tag=TAG use configuration variables from tag TAG # -v, --verbose print more informational messages than default # --no-verbose don't print the extra informational messages # --version print version information # -h, --help, --help-all print short, long, or detailed help message # # MODE must be one of the following: # # clean remove files from the build directory # compile compile a source file into a libtool object # execute automatically set library path, then run a program # finish complete the installation of libtool libraries # install install libraries or executables # link create a library or an executable # uninstall remove libraries from an installed directory # # MODE-ARGS vary depending on the MODE. When passed as first option, # `--mode=MODE' may be abbreviated as `MODE' or a unique abbreviation of that. # Try `$progname --help --mode=MODE' for a more detailed description of MODE. # # When reporting a bug, please describe a test case to reproduce it and # include the following information: # # host-triplet: $host # shell: $SHELL # compiler: $LTCC # compiler flags: $LTCFLAGS # linker: $LD (gnu? $with_gnu_ld) # $progname: (GNU libtool) 2.4.2 # automake: $automake_version # autoconf: $autoconf_version # # Report bugs to . # GNU libtool home page: . # General help using GNU software: . PROGRAM=libtool PACKAGE=libtool VERSION=2.4.2 TIMESTAMP="" package_revision=1.3337 # Be Bourne compatible if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then emulate sh NULLCMD=: # Zsh 3.x and 4.x performs word splitting on ${1+"$@"}, which # is contrary to our usage. Disable this feature. alias -g '${1+"$@"}'='"$@"' setopt NO_GLOB_SUBST else case `(set -o) 2>/dev/null` in *posix*) set -o posix;; esac fi BIN_SH=xpg4; export BIN_SH # for Tru64 DUALCASE=1; export DUALCASE # for MKS sh # A function that is used when there is no print builtin or printf. func_fallback_echo () { eval 'cat <<_LTECHO_EOF $1 _LTECHO_EOF' } # NLS nuisances: We save the old values to restore during execute mode. lt_user_locale= lt_safe_locale= for lt_var in LANG LANGUAGE LC_ALL LC_CTYPE LC_COLLATE LC_MESSAGES do eval "if test \"\${$lt_var+set}\" = set; then save_$lt_var=\$$lt_var $lt_var=C export $lt_var lt_user_locale=\"$lt_var=\\\$save_\$lt_var; \$lt_user_locale\" lt_safe_locale=\"$lt_var=C; \$lt_safe_locale\" fi" done LC_ALL=C LANGUAGE=C export LANGUAGE LC_ALL $lt_unset CDPATH # Work around backward compatibility issue on IRIX 6.5. On IRIX 6.4+, sh # is ksh but when the shell is invoked as "sh" and the current value of # the _XPG environment variable is not equal to 1 (one), the special # positional parameter $0, within a function call, is the name of the # function. progpath="$0" : ${CP="cp -f"} test "${ECHO+set}" = set || ECHO=${as_echo-'printf %s\n'} : ${MAKE="make"} : ${MKDIR="mkdir"} : ${MV="mv -f"} : ${RM="rm -f"} : ${SHELL="${CONFIG_SHELL-/bin/sh}"} : ${Xsed="$SED -e 1s/^X//"} # Global variables: EXIT_SUCCESS=0 EXIT_FAILURE=1 EXIT_MISMATCH=63 # $? = 63 is used to indicate version mismatch to missing. EXIT_SKIP=77 # $? = 77 is used to indicate a skipped test to automake. exit_status=$EXIT_SUCCESS # Make sure IFS has a sensible default lt_nl=' ' IFS=" $lt_nl" dirname="s,/[^/]*$,," basename="s,^.*/,," # func_dirname file append nondir_replacement # Compute the dirname of FILE. If nonempty, add APPEND to the result, # otherwise set result to NONDIR_REPLACEMENT. func_dirname () { func_dirname_result=`$ECHO "${1}" | $SED "$dirname"` if test "X$func_dirname_result" = "X${1}"; then func_dirname_result="${3}" else func_dirname_result="$func_dirname_result${2}" fi } # func_dirname may be replaced by extended shell implementation # func_basename file func_basename () { func_basename_result=`$ECHO "${1}" | $SED "$basename"` } # func_basename may be replaced by extended shell implementation # func_dirname_and_basename file append nondir_replacement # perform func_basename and func_dirname in a single function # call: # dirname: Compute the dirname of FILE. If nonempty, # add APPEND to the result, otherwise set result # to NONDIR_REPLACEMENT. # value returned in "$func_dirname_result" # basename: Compute filename of FILE. # value retuned in "$func_basename_result" # Implementation must be kept synchronized with func_dirname # and func_basename. For efficiency, we do not delegate to # those functions but instead duplicate the functionality here. func_dirname_and_basename () { # Extract subdirectory from the argument. func_dirname_result=`$ECHO "${1}" | $SED -e "$dirname"` if test "X$func_dirname_result" = "X${1}"; then func_dirname_result="${3}" else func_dirname_result="$func_dirname_result${2}" fi func_basename_result=`$ECHO "${1}" | $SED -e "$basename"` } # func_dirname_and_basename may be replaced by extended shell implementation # func_stripname prefix suffix name # strip PREFIX and SUFFIX off of NAME. # PREFIX and SUFFIX must not contain globbing or regex special # characters, hashes, percent signs, but SUFFIX may contain a leading # dot (in which case that matches only a dot). # func_strip_suffix prefix name func_stripname () { case ${2} in .*) func_stripname_result=`$ECHO "${3}" | $SED "s%^${1}%%; s%\\\\${2}\$%%"`;; *) func_stripname_result=`$ECHO "${3}" | $SED "s%^${1}%%; s%${2}\$%%"`;; esac } # func_stripname may be replaced by extended shell implementation # These SED scripts presuppose an absolute path with a trailing slash. pathcar='s,^/\([^/]*\).*$,\1,' pathcdr='s,^/[^/]*,,' removedotparts=':dotsl s@/\./@/@g t dotsl s,/\.$,/,' collapseslashes='s@/\{1,\}@/@g' finalslash='s,/*$,/,' # func_normal_abspath PATH # Remove doubled-up and trailing slashes, "." path components, # and cancel out any ".." path components in PATH after making # it an absolute path. # value returned in "$func_normal_abspath_result" func_normal_abspath () { # Start from root dir and reassemble the path. func_normal_abspath_result= func_normal_abspath_tpath=$1 func_normal_abspath_altnamespace= case $func_normal_abspath_tpath in "") # Empty path, that just means $cwd. func_stripname '' '/' "`pwd`" func_normal_abspath_result=$func_stripname_result return ;; # The next three entries are used to spot a run of precisely # two leading slashes without using negated character classes; # we take advantage of case's first-match behaviour. ///*) # Unusual form of absolute path, do nothing. ;; //*) # Not necessarily an ordinary path; POSIX reserves leading '//' # and for example Cygwin uses it to access remote file shares # over CIFS/SMB, so we conserve a leading double slash if found. func_normal_abspath_altnamespace=/ ;; /*) # Absolute path, do nothing. ;; *) # Relative path, prepend $cwd. func_normal_abspath_tpath=`pwd`/$func_normal_abspath_tpath ;; esac # Cancel out all the simple stuff to save iterations. We also want # the path to end with a slash for ease of parsing, so make sure # there is one (and only one) here. func_normal_abspath_tpath=`$ECHO "$func_normal_abspath_tpath" | $SED \ -e "$removedotparts" -e "$collapseslashes" -e "$finalslash"` while :; do # Processed it all yet? if test "$func_normal_abspath_tpath" = / ; then # If we ascended to the root using ".." the result may be empty now. if test -z "$func_normal_abspath_result" ; then func_normal_abspath_result=/ fi break fi func_normal_abspath_tcomponent=`$ECHO "$func_normal_abspath_tpath" | $SED \ -e "$pathcar"` func_normal_abspath_tpath=`$ECHO "$func_normal_abspath_tpath" | $SED \ -e "$pathcdr"` # Figure out what to do with it case $func_normal_abspath_tcomponent in "") # Trailing empty path component, ignore it. ;; ..) # Parent dir; strip last assembled component from result. func_dirname "$func_normal_abspath_result" func_normal_abspath_result=$func_dirname_result ;; *) # Actual path component, append it. func_normal_abspath_result=$func_normal_abspath_result/$func_normal_abspath_tcomponent ;; esac done # Restore leading double-slash if one was found on entry. func_normal_abspath_result=$func_normal_abspath_altnamespace$func_normal_abspath_result } # func_relative_path SRCDIR DSTDIR # generates a relative path from SRCDIR to DSTDIR, with a trailing # slash if non-empty, suitable for immediately appending a filename # without needing to append a separator. # value returned in "$func_relative_path_result" func_relative_path () { func_relative_path_result= func_normal_abspath "$1" func_relative_path_tlibdir=$func_normal_abspath_result func_normal_abspath "$2" func_relative_path_tbindir=$func_normal_abspath_result # Ascend the tree starting from libdir while :; do # check if we have found a prefix of bindir case $func_relative_path_tbindir in $func_relative_path_tlibdir) # found an exact match func_relative_path_tcancelled= break ;; $func_relative_path_tlibdir*) # found a matching prefix func_stripname "$func_relative_path_tlibdir" '' "$func_relative_path_tbindir" func_relative_path_tcancelled=$func_stripname_result if test -z "$func_relative_path_result"; then func_relative_path_result=. fi break ;; *) func_dirname $func_relative_path_tlibdir func_relative_path_tlibdir=${func_dirname_result} if test "x$func_relative_path_tlibdir" = x ; then # Have to descend all the way to the root! func_relative_path_result=../$func_relative_path_result func_relative_path_tcancelled=$func_relative_path_tbindir break fi func_relative_path_result=../$func_relative_path_result ;; esac done # Now calculate path; take care to avoid doubling-up slashes. func_stripname '' '/' "$func_relative_path_result" func_relative_path_result=$func_stripname_result func_stripname '/' '/' "$func_relative_path_tcancelled" if test "x$func_stripname_result" != x ; then func_relative_path_result=${func_relative_path_result}/${func_stripname_result} fi # Normalisation. If bindir is libdir, return empty string, # else relative path ending with a slash; either way, target # file name can be directly appended. if test ! -z "$func_relative_path_result"; then func_stripname './' '' "$func_relative_path_result/" func_relative_path_result=$func_stripname_result fi } # The name of this program: func_dirname_and_basename "$progpath" progname=$func_basename_result # Make sure we have an absolute path for reexecution: case $progpath in [\\/]*|[A-Za-z]:\\*) ;; *[\\/]*) progdir=$func_dirname_result progdir=`cd "$progdir" && pwd` progpath="$progdir/$progname" ;; *) save_IFS="$IFS" IFS=${PATH_SEPARATOR-:} for progdir in $PATH; do IFS="$save_IFS" test -x "$progdir/$progname" && break done IFS="$save_IFS" test -n "$progdir" || progdir=`pwd` progpath="$progdir/$progname" ;; esac # Sed substitution that helps us do robust quoting. It backslashifies # metacharacters that are still active within double-quoted strings. Xsed="${SED}"' -e 1s/^X//' sed_quote_subst='s/\([`"$\\]\)/\\\1/g' # Same as above, but do not quote variable references. double_quote_subst='s/\(["`\\]\)/\\\1/g' # Sed substitution that turns a string into a regex matching for the # string literally. sed_make_literal_regex='s,[].[^$\\*\/],\\&,g' # Sed substitution that converts a w32 file name or path # which contains forward slashes, into one that contains # (escaped) backslashes. A very naive implementation. lt_sed_naive_backslashify='s|\\\\*|\\|g;s|/|\\|g;s|\\|\\\\|g' # Re-`\' parameter expansions in output of double_quote_subst that were # `\'-ed in input to the same. If an odd number of `\' preceded a '$' # in input to double_quote_subst, that '$' was protected from expansion. # Since each input `\' is now two `\'s, look for any number of runs of # four `\'s followed by two `\'s and then a '$'. `\' that '$'. bs='\\' bs2='\\\\' bs4='\\\\\\\\' dollar='\$' sed_double_backslash="\ s/$bs4/&\\ /g s/^$bs2$dollar/$bs&/ s/\\([^$bs]\\)$bs2$dollar/\\1$bs2$bs$dollar/g s/\n//g" # Standard options: opt_dry_run=false opt_help=false opt_quiet=false opt_verbose=false opt_warning=: # func_echo arg... # Echo program name prefixed message, along with the current mode # name if it has been set yet. func_echo () { $ECHO "$progname: ${opt_mode+$opt_mode: }$*" } # func_verbose arg... # Echo program name prefixed message in verbose mode only. func_verbose () { $opt_verbose && func_echo ${1+"$@"} # A bug in bash halts the script if the last line of a function # fails when set -e is in force, so we need another command to # work around that: : } # func_echo_all arg... # Invoke $ECHO with all args, space-separated. func_echo_all () { $ECHO "$*" } # func_error arg... # Echo program name prefixed message to standard error. func_error () { $ECHO "$progname: ${opt_mode+$opt_mode: }"${1+"$@"} 1>&2 } # func_warning arg... # Echo program name prefixed warning message to standard error. func_warning () { $opt_warning && $ECHO "$progname: ${opt_mode+$opt_mode: }warning: "${1+"$@"} 1>&2 # bash bug again: : } # func_fatal_error arg... # Echo program name prefixed message to standard error, and exit. func_fatal_error () { func_error ${1+"$@"} exit $EXIT_FAILURE } # func_fatal_help arg... # Echo program name prefixed message to standard error, followed by # a help hint, and exit. func_fatal_help () { func_error ${1+"$@"} func_fatal_error "$help" } help="Try \`$progname --help' for more information." ## default # func_grep expression filename # Check whether EXPRESSION matches any line of FILENAME, without output. func_grep () { $GREP "$1" "$2" >/dev/null 2>&1 } # func_mkdir_p directory-path # Make sure the entire path to DIRECTORY-PATH is available. func_mkdir_p () { my_directory_path="$1" my_dir_list= if test -n "$my_directory_path" && test "$opt_dry_run" != ":"; then # Protect directory names starting with `-' case $my_directory_path in -*) my_directory_path="./$my_directory_path" ;; esac # While some portion of DIR does not yet exist... while test ! -d "$my_directory_path"; do # ...make a list in topmost first order. Use a colon delimited # list incase some portion of path contains whitespace. my_dir_list="$my_directory_path:$my_dir_list" # If the last portion added has no slash in it, the list is done case $my_directory_path in */*) ;; *) break ;; esac # ...otherwise throw away the child directory and loop my_directory_path=`$ECHO "$my_directory_path" | $SED -e "$dirname"` done my_dir_list=`$ECHO "$my_dir_list" | $SED 's,:*$,,'` save_mkdir_p_IFS="$IFS"; IFS=':' for my_dir in $my_dir_list; do IFS="$save_mkdir_p_IFS" # mkdir can fail with a `File exist' error if two processes # try to create one of the directories concurrently. Don't # stop in that case! $MKDIR "$my_dir" 2>/dev/null || : done IFS="$save_mkdir_p_IFS" # Bail out if we (or some other process) failed to create a directory. test -d "$my_directory_path" || \ func_fatal_error "Failed to create \`$1'" fi } # func_mktempdir [string] # Make a temporary directory that won't clash with other running # libtool processes, and avoids race conditions if possible. If # given, STRING is the basename for that directory. func_mktempdir () { my_template="${TMPDIR-/tmp}/${1-$progname}" if test "$opt_dry_run" = ":"; then # Return a directory name, but don't create it in dry-run mode my_tmpdir="${my_template}-$$" else # If mktemp works, use that first and foremost my_tmpdir=`mktemp -d "${my_template}-XXXXXXXX" 2>/dev/null` if test ! -d "$my_tmpdir"; then # Failing that, at least try and use $RANDOM to avoid a race my_tmpdir="${my_template}-${RANDOM-0}$$" save_mktempdir_umask=`umask` umask 0077 $MKDIR "$my_tmpdir" umask $save_mktempdir_umask fi # If we're not in dry-run mode, bomb out on failure test -d "$my_tmpdir" || \ func_fatal_error "cannot create temporary directory \`$my_tmpdir'" fi $ECHO "$my_tmpdir" } # func_quote_for_eval arg # Aesthetically quote ARG to be evaled later. # This function returns two values: FUNC_QUOTE_FOR_EVAL_RESULT # is double-quoted, suitable for a subsequent eval, whereas # FUNC_QUOTE_FOR_EVAL_UNQUOTED_RESULT has merely all characters # which are still active within double quotes backslashified. func_quote_for_eval () { case $1 in *[\\\`\"\$]*) func_quote_for_eval_unquoted_result=`$ECHO "$1" | $SED "$sed_quote_subst"` ;; *) func_quote_for_eval_unquoted_result="$1" ;; esac case $func_quote_for_eval_unquoted_result in # Double-quote args containing shell metacharacters to delay # word splitting, command substitution and and variable # expansion for a subsequent eval. # Many Bourne shells cannot handle close brackets correctly # in scan sets, so we specify it separately. *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") func_quote_for_eval_result="\"$func_quote_for_eval_unquoted_result\"" ;; *) func_quote_for_eval_result="$func_quote_for_eval_unquoted_result" esac } # func_quote_for_expand arg # Aesthetically quote ARG to be evaled later; same as above, # but do not quote variable references. func_quote_for_expand () { case $1 in *[\\\`\"]*) my_arg=`$ECHO "$1" | $SED \ -e "$double_quote_subst" -e "$sed_double_backslash"` ;; *) my_arg="$1" ;; esac case $my_arg in # Double-quote args containing shell metacharacters to delay # word splitting and command substitution for a subsequent eval. # Many Bourne shells cannot handle close brackets correctly # in scan sets, so we specify it separately. *[\[\~\#\^\&\*\(\)\{\}\|\;\<\>\?\'\ \ ]*|*]*|"") my_arg="\"$my_arg\"" ;; esac func_quote_for_expand_result="$my_arg" } # func_show_eval cmd [fail_exp] # Unless opt_silent is true, then output CMD. Then, if opt_dryrun is # not true, evaluate CMD. If the evaluation of CMD fails, and FAIL_EXP # is given, then evaluate it. func_show_eval () { my_cmd="$1" my_fail_exp="${2-:}" ${opt_silent-false} || { func_quote_for_expand "$my_cmd" eval "func_echo $func_quote_for_expand_result" } if ${opt_dry_run-false}; then :; else eval "$my_cmd" my_status=$? if test "$my_status" -eq 0; then :; else eval "(exit $my_status); $my_fail_exp" fi fi } # func_show_eval_locale cmd [fail_exp] # Unless opt_silent is true, then output CMD. Then, if opt_dryrun is # not true, evaluate CMD. If the evaluation of CMD fails, and FAIL_EXP # is given, then evaluate it. Use the saved locale for evaluation. func_show_eval_locale () { my_cmd="$1" my_fail_exp="${2-:}" ${opt_silent-false} || { func_quote_for_expand "$my_cmd" eval "func_echo $func_quote_for_expand_result" } if ${opt_dry_run-false}; then :; else eval "$lt_user_locale $my_cmd" my_status=$? eval "$lt_safe_locale" if test "$my_status" -eq 0; then :; else eval "(exit $my_status); $my_fail_exp" fi fi } # func_tr_sh # Turn $1 into a string suitable for a shell variable name. # Result is stored in $func_tr_sh_result. All characters # not in the set a-zA-Z0-9_ are replaced with '_'. Further, # if $1 begins with a digit, a '_' is prepended as well. func_tr_sh () { case $1 in [0-9]* | *[!a-zA-Z0-9_]*) func_tr_sh_result=`$ECHO "$1" | $SED 's/^\([0-9]\)/_\1/; s/[^a-zA-Z0-9_]/_/g'` ;; * ) func_tr_sh_result=$1 ;; esac } # func_version # Echo version message to standard output and exit. func_version () { $opt_debug $SED -n '/(C)/!b go :more /\./!{ N s/\n# / / b more } :go /^# '$PROGRAM' (GNU /,/# warranty; / { s/^# // s/^# *$// s/\((C)\)[ 0-9,-]*\( [1-9][0-9]*\)/\1\2/ p }' < "$progpath" exit $? } # func_usage # Echo short help message to standard output and exit. func_usage () { $opt_debug $SED -n '/^# Usage:/,/^# *.*--help/ { s/^# // s/^# *$// s/\$progname/'$progname'/ p }' < "$progpath" echo $ECHO "run \`$progname --help | more' for full usage" exit $? } # func_help [NOEXIT] # Echo long help message to standard output and exit, # unless 'noexit' is passed as argument. func_help () { $opt_debug $SED -n '/^# Usage:/,/# Report bugs to/ { :print s/^# // s/^# *$// s*\$progname*'$progname'* s*\$host*'"$host"'* s*\$SHELL*'"$SHELL"'* s*\$LTCC*'"$LTCC"'* s*\$LTCFLAGS*'"$LTCFLAGS"'* s*\$LD*'"$LD"'* s/\$with_gnu_ld/'"$with_gnu_ld"'/ s/\$automake_version/'"`(${AUTOMAKE-automake} --version) 2>/dev/null |$SED 1q`"'/ s/\$autoconf_version/'"`(${AUTOCONF-autoconf} --version) 2>/dev/null |$SED 1q`"'/ p d } /^# .* home page:/b print /^# General help using/b print ' < "$progpath" ret=$? if test -z "$1"; then exit $ret fi } # func_missing_arg argname # Echo program name prefixed message to standard error and set global # exit_cmd. func_missing_arg () { $opt_debug func_error "missing argument for $1." exit_cmd=exit } # func_split_short_opt shortopt # Set func_split_short_opt_name and func_split_short_opt_arg shell # variables after splitting SHORTOPT after the 2nd character. func_split_short_opt () { my_sed_short_opt='1s/^\(..\).*$/\1/;q' my_sed_short_rest='1s/^..\(.*\)$/\1/;q' func_split_short_opt_name=`$ECHO "$1" | $SED "$my_sed_short_opt"` func_split_short_opt_arg=`$ECHO "$1" | $SED "$my_sed_short_rest"` } # func_split_short_opt may be replaced by extended shell implementation # func_split_long_opt longopt # Set func_split_long_opt_name and func_split_long_opt_arg shell # variables after splitting LONGOPT at the `=' sign. func_split_long_opt () { my_sed_long_opt='1s/^\(--[^=]*\)=.*/\1/;q' my_sed_long_arg='1s/^--[^=]*=//' func_split_long_opt_name=`$ECHO "$1" | $SED "$my_sed_long_opt"` func_split_long_opt_arg=`$ECHO "$1" | $SED "$my_sed_long_arg"` } # func_split_long_opt may be replaced by extended shell implementation exit_cmd=: magic="%%%MAGIC variable%%%" magic_exe="%%%MAGIC EXE variable%%%" # Global variables. nonopt= preserve_args= lo2o="s/\\.lo\$/.${objext}/" o2lo="s/\\.${objext}\$/.lo/" extracted_archives= extracted_serial=0 # If this variable is set in any of the actions, the command in it # will be execed at the end. This prevents here-documents from being # left over by shells. exec_cmd= # func_append var value # Append VALUE to the end of shell variable VAR. func_append () { eval "${1}=\$${1}\${2}" } # func_append may be replaced by extended shell implementation # func_append_quoted var value # Quote VALUE and append to the end of shell variable VAR, separated # by a space. func_append_quoted () { func_quote_for_eval "${2}" eval "${1}=\$${1}\\ \$func_quote_for_eval_result" } # func_append_quoted may be replaced by extended shell implementation # func_arith arithmetic-term... func_arith () { func_arith_result=`expr "${@}"` } # func_arith may be replaced by extended shell implementation # func_len string # STRING may not start with a hyphen. func_len () { func_len_result=`expr "${1}" : ".*" 2>/dev/null || echo $max_cmd_len` } # func_len may be replaced by extended shell implementation # func_lo2o object func_lo2o () { func_lo2o_result=`$ECHO "${1}" | $SED "$lo2o"` } # func_lo2o may be replaced by extended shell implementation # func_xform libobj-or-source func_xform () { func_xform_result=`$ECHO "${1}" | $SED 's/\.[^.]*$/.lo/'` } # func_xform may be replaced by extended shell implementation # func_fatal_configuration arg... # Echo program name prefixed message to standard error, followed by # a configuration failure hint, and exit. func_fatal_configuration () { func_error ${1+"$@"} func_error "See the $PACKAGE documentation for more information." func_fatal_error "Fatal configuration error." } # func_config # Display the configuration for all the tags in this script. func_config () { re_begincf='^# ### BEGIN LIBTOOL' re_endcf='^# ### END LIBTOOL' # Default configuration. $SED "1,/$re_begincf CONFIG/d;/$re_endcf CONFIG/,\$d" < "$progpath" # Now print the configurations for the tags. for tagname in $taglist; do $SED -n "/$re_begincf TAG CONFIG: $tagname\$/,/$re_endcf TAG CONFIG: $tagname\$/p" < "$progpath" done exit $? } # func_features # Display the features supported by this script. func_features () { echo "host: $host" if test "$build_libtool_libs" = yes; then echo "enable shared libraries" else echo "disable shared libraries" fi if test "$build_old_libs" = yes; then echo "enable static libraries" else echo "disable static libraries" fi exit $? } # func_enable_tag tagname # Verify that TAGNAME is valid, and either flag an error and exit, or # enable the TAGNAME tag. We also add TAGNAME to the global $taglist # variable here. func_enable_tag () { # Global variable: tagname="$1" re_begincf="^# ### BEGIN LIBTOOL TAG CONFIG: $tagname\$" re_endcf="^# ### END LIBTOOL TAG CONFIG: $tagname\$" sed_extractcf="/$re_begincf/,/$re_endcf/p" # Validate tagname. case $tagname in *[!-_A-Za-z0-9,/]*) func_fatal_error "invalid tag name: $tagname" ;; esac # Don't test for the "default" C tag, as we know it's # there but not specially marked. case $tagname in CC) ;; *) if $GREP "$re_begincf" "$progpath" >/dev/null 2>&1; then taglist="$taglist $tagname" # Evaluate the configuration. Be careful to quote the path # and the sed script, to avoid splitting on whitespace, but # also don't use non-portable quotes within backquotes within # quotes we have to do it in 2 steps: extractedcf=`$SED -n -e "$sed_extractcf" < "$progpath"` eval "$extractedcf" else func_error "ignoring unknown tag $tagname" fi ;; esac } # func_check_version_match # Ensure that we are using m4 macros, and libtool script from the same # release of libtool. func_check_version_match () { if test "$package_revision" != "$macro_revision"; then if test "$VERSION" != "$macro_version"; then if test -z "$macro_version"; then cat >&2 <<_LT_EOF $progname: Version mismatch error. This is $PACKAGE $VERSION, but the $progname: definition of this LT_INIT comes from an older release. $progname: You should recreate aclocal.m4 with macros from $PACKAGE $VERSION $progname: and run autoconf again. _LT_EOF else cat >&2 <<_LT_EOF $progname: Version mismatch error. This is $PACKAGE $VERSION, but the $progname: definition of this LT_INIT comes from $PACKAGE $macro_version. $progname: You should recreate aclocal.m4 with macros from $PACKAGE $VERSION $progname: and run autoconf again. _LT_EOF fi else cat >&2 <<_LT_EOF $progname: Version mismatch error. This is $PACKAGE $VERSION, revision $package_revision, $progname: but the definition of this LT_INIT comes from revision $macro_revision. $progname: You should recreate aclocal.m4 with macros from revision $package_revision $progname: of $PACKAGE $VERSION and run autoconf again. _LT_EOF fi exit $EXIT_MISMATCH fi } # Shorthand for --mode=foo, only valid as the first argument case $1 in clean|clea|cle|cl) shift; set dummy --mode clean ${1+"$@"}; shift ;; compile|compil|compi|comp|com|co|c) shift; set dummy --mode compile ${1+"$@"}; shift ;; execute|execut|execu|exec|exe|ex|e) shift; set dummy --mode execute ${1+"$@"}; shift ;; finish|finis|fini|fin|fi|f) shift; set dummy --mode finish ${1+"$@"}; shift ;; install|instal|insta|inst|ins|in|i) shift; set dummy --mode install ${1+"$@"}; shift ;; link|lin|li|l) shift; set dummy --mode link ${1+"$@"}; shift ;; uninstall|uninstal|uninsta|uninst|unins|unin|uni|un|u) shift; set dummy --mode uninstall ${1+"$@"}; shift ;; esac # Option defaults: opt_debug=: opt_dry_run=false opt_config=false opt_preserve_dup_deps=false opt_features=false opt_finish=false opt_help=false opt_help_all=false opt_silent=: opt_warning=: opt_verbose=: opt_silent=false opt_verbose=false # Parse options once, thoroughly. This comes as soon as possible in the # script to make things like `--version' happen as quickly as we can. { # this just eases exit handling while test $# -gt 0; do opt="$1" shift case $opt in --debug|-x) opt_debug='set -x' func_echo "enabling shell trace mode" $opt_debug ;; --dry-run|--dryrun|-n) opt_dry_run=: ;; --config) opt_config=: func_config ;; --dlopen|-dlopen) optarg="$1" opt_dlopen="${opt_dlopen+$opt_dlopen }$optarg" shift ;; --preserve-dup-deps) opt_preserve_dup_deps=: ;; --features) opt_features=: func_features ;; --finish) opt_finish=: set dummy --mode finish ${1+"$@"}; shift ;; --help) opt_help=: ;; --help-all) opt_help_all=: opt_help=': help-all' ;; --mode) test $# = 0 && func_missing_arg $opt && break optarg="$1" opt_mode="$optarg" case $optarg in # Valid mode arguments: clean|compile|execute|finish|install|link|relink|uninstall) ;; # Catch anything else as an error *) func_error "invalid argument for $opt" exit_cmd=exit break ;; esac shift ;; --no-silent|--no-quiet) opt_silent=false func_append preserve_args " $opt" ;; --no-warning|--no-warn) opt_warning=false func_append preserve_args " $opt" ;; --no-verbose) opt_verbose=false func_append preserve_args " $opt" ;; --silent|--quiet) opt_silent=: func_append preserve_args " $opt" opt_verbose=false ;; --verbose|-v) opt_verbose=: func_append preserve_args " $opt" opt_silent=false ;; --tag) test $# = 0 && func_missing_arg $opt && break optarg="$1" opt_tag="$optarg" func_append preserve_args " $opt $optarg" func_enable_tag "$optarg" shift ;; -\?|-h) func_usage ;; --help) func_help ;; --version) func_version ;; # Separate optargs to long options: --*=*) func_split_long_opt "$opt" set dummy "$func_split_long_opt_name" "$func_split_long_opt_arg" ${1+"$@"} shift ;; # Separate non-argument short options: -\?*|-h*|-n*|-v*) func_split_short_opt "$opt" set dummy "$func_split_short_opt_name" "-$func_split_short_opt_arg" ${1+"$@"} shift ;; --) break ;; -*) func_fatal_help "unrecognized option \`$opt'" ;; *) set dummy "$opt" ${1+"$@"}; shift; break ;; esac done # Validate options: # save first non-option argument if test "$#" -gt 0; then nonopt="$opt" shift fi # preserve --debug test "$opt_debug" = : || func_append preserve_args " --debug" case $host in *cygwin* | *mingw* | *pw32* | *cegcc*) # don't eliminate duplications in $postdeps and $predeps opt_duplicate_compiler_generated_deps=: ;; *) opt_duplicate_compiler_generated_deps=$opt_preserve_dup_deps ;; esac $opt_help || { # Sanity checks first: func_check_version_match if test "$build_libtool_libs" != yes && test "$build_old_libs" != yes; then func_fatal_configuration "not configured to build any kind of library" fi # Darwin sucks eval std_shrext=\"$shrext_cmds\" # Only execute mode is allowed to have -dlopen flags. if test -n "$opt_dlopen" && test "$opt_mode" != execute; then func_error "unrecognized option \`-dlopen'" $ECHO "$help" 1>&2 exit $EXIT_FAILURE fi # Change the help message to a mode-specific one. generic_help="$help" help="Try \`$progname --help --mode=$opt_mode' for more information." } # Bail if the options were screwed $exit_cmd $EXIT_FAILURE } ## ----------- ## ## Main. ## ## ----------- ## # func_lalib_p file # True iff FILE is a libtool `.la' library or `.lo' object file. # This function is only a basic sanity check; it will hardly flush out # determined imposters. func_lalib_p () { test -f "$1" && $SED -e 4q "$1" 2>/dev/null \ | $GREP "^# Generated by .*$PACKAGE" > /dev/null 2>&1 } # func_lalib_unsafe_p file # True iff FILE is a libtool `.la' library or `.lo' object file. # This function implements the same check as func_lalib_p without # resorting to external programs. To this end, it redirects stdin and # closes it afterwards, without saving the original file descriptor. # As a safety measure, use it only where a negative result would be # fatal anyway. Works if `file' does not exist. func_lalib_unsafe_p () { lalib_p=no if test -f "$1" && test -r "$1" && exec 5<&0 <"$1"; then for lalib_p_l in 1 2 3 4 do read lalib_p_line case "$lalib_p_line" in \#\ Generated\ by\ *$PACKAGE* ) lalib_p=yes; break;; esac done exec 0<&5 5<&- fi test "$lalib_p" = yes } # func_ltwrapper_script_p file # True iff FILE is a libtool wrapper script # This function is only a basic sanity check; it will hardly flush out # determined imposters. func_ltwrapper_script_p () { func_lalib_p "$1" } # func_ltwrapper_executable_p file # True iff FILE is a libtool wrapper executable # This function is only a basic sanity check; it will hardly flush out # determined imposters. func_ltwrapper_executable_p () { func_ltwrapper_exec_suffix= case $1 in *.exe) ;; *) func_ltwrapper_exec_suffix=.exe ;; esac $GREP "$magic_exe" "$1$func_ltwrapper_exec_suffix" >/dev/null 2>&1 } # func_ltwrapper_scriptname file # Assumes file is an ltwrapper_executable # uses $file to determine the appropriate filename for a # temporary ltwrapper_script. func_ltwrapper_scriptname () { func_dirname_and_basename "$1" "" "." func_stripname '' '.exe' "$func_basename_result" func_ltwrapper_scriptname_result="$func_dirname_result/$objdir/${func_stripname_result}_ltshwrapper" } # func_ltwrapper_p file # True iff FILE is a libtool wrapper script or wrapper executable # This function is only a basic sanity check; it will hardly flush out # determined imposters. func_ltwrapper_p () { func_ltwrapper_script_p "$1" || func_ltwrapper_executable_p "$1" } # func_execute_cmds commands fail_cmd # Execute tilde-delimited COMMANDS. # If FAIL_CMD is given, eval that upon failure. # FAIL_CMD may read-access the current command in variable CMD! func_execute_cmds () { $opt_debug save_ifs=$IFS; IFS='~' for cmd in $1; do IFS=$save_ifs eval cmd=\"$cmd\" func_show_eval "$cmd" "${2-:}" done IFS=$save_ifs } # func_source file # Source FILE, adding directory component if necessary. # Note that it is not necessary on cygwin/mingw to append a dot to # FILE even if both FILE and FILE.exe exist: automatic-append-.exe # behavior happens only for exec(3), not for open(2)! Also, sourcing # `FILE.' does not work on cygwin managed mounts. func_source () { $opt_debug case $1 in */* | *\\*) . "$1" ;; *) . "./$1" ;; esac } # func_resolve_sysroot PATH # Replace a leading = in PATH with a sysroot. Store the result into # func_resolve_sysroot_result func_resolve_sysroot () { func_resolve_sysroot_result=$1 case $func_resolve_sysroot_result in =*) func_stripname '=' '' "$func_resolve_sysroot_result" func_resolve_sysroot_result=$lt_sysroot$func_stripname_result ;; esac } # func_replace_sysroot PATH # If PATH begins with the sysroot, replace it with = and # store the result into func_replace_sysroot_result. func_replace_sysroot () { case "$lt_sysroot:$1" in ?*:"$lt_sysroot"*) func_stripname "$lt_sysroot" '' "$1" func_replace_sysroot_result="=$func_stripname_result" ;; *) # Including no sysroot. func_replace_sysroot_result=$1 ;; esac } # func_infer_tag arg # Infer tagged configuration to use if any are available and # if one wasn't chosen via the "--tag" command line option. # Only attempt this if the compiler in the base compile # command doesn't match the default compiler. # arg is usually of the form 'gcc ...' func_infer_tag () { $opt_debug if test -n "$available_tags" && test -z "$tagname"; then CC_quoted= for arg in $CC; do func_append_quoted CC_quoted "$arg" done CC_expanded=`func_echo_all $CC` CC_quoted_expanded=`func_echo_all $CC_quoted` case $@ in # Blanks in the command may have been stripped by the calling shell, # but not from the CC environment variable when configure was run. " $CC "* | "$CC "* | " $CC_expanded "* | "$CC_expanded "* | \ " $CC_quoted"* | "$CC_quoted "* | " $CC_quoted_expanded "* | "$CC_quoted_expanded "*) ;; # Blanks at the start of $base_compile will cause this to fail # if we don't check for them as well. *) for z in $available_tags; do if $GREP "^# ### BEGIN LIBTOOL TAG CONFIG: $z$" < "$progpath" > /dev/null; then # Evaluate the configuration. eval "`${SED} -n -e '/^# ### BEGIN LIBTOOL TAG CONFIG: '$z'$/,/^# ### END LIBTOOL TAG CONFIG: '$z'$/p' < $progpath`" CC_quoted= for arg in $CC; do # Double-quote args containing other shell metacharacters. func_append_quoted CC_quoted "$arg" done CC_expanded=`func_echo_all $CC` CC_quoted_expanded=`func_echo_all $CC_quoted` case "$@ " in " $CC "* | "$CC "* | " $CC_expanded "* | "$CC_expanded "* | \ " $CC_quoted"* | "$CC_quoted "* | " $CC_quoted_expanded "* | "$CC_quoted_expanded "*) # The compiler in the base compile command matches # the one in the tagged configuration. # Assume this is the tagged configuration we want. tagname=$z break ;; esac fi done # If $tagname still isn't set, then no tagged configuration # was found and let the user know that the "--tag" command # line option must be used. if test -z "$tagname"; then func_echo "unable to infer tagged configuration" func_fatal_error "specify a tag with \`--tag'" # else # func_verbose "using $tagname tagged configuration" fi ;; esac fi } # func_write_libtool_object output_name pic_name nonpic_name # Create a libtool object file (analogous to a ".la" file), # but don't create it if we're doing a dry run. func_write_libtool_object () { write_libobj=${1} if test "$build_libtool_libs" = yes; then write_lobj=\'${2}\' else write_lobj=none fi if test "$build_old_libs" = yes; then write_oldobj=\'${3}\' else write_oldobj=none fi $opt_dry_run || { cat >${write_libobj}T </dev/null` if test "$?" -eq 0 && test -n "${func_convert_core_file_wine_to_w32_tmp}"; then func_convert_core_file_wine_to_w32_result=`$ECHO "$func_convert_core_file_wine_to_w32_tmp" | $SED -e "$lt_sed_naive_backslashify"` else func_convert_core_file_wine_to_w32_result= fi fi } # end: func_convert_core_file_wine_to_w32 # func_convert_core_path_wine_to_w32 ARG # Helper function used by path conversion functions when $build is *nix, and # $host is mingw, cygwin, or some other w32 environment. Relies on a correctly # configured wine environment available, with the winepath program in $build's # $PATH. Assumes ARG has no leading or trailing path separator characters. # # ARG is path to be converted from $build format to win32. # Result is available in $func_convert_core_path_wine_to_w32_result. # Unconvertible file (directory) names in ARG are skipped; if no directory names # are convertible, then the result may be empty. func_convert_core_path_wine_to_w32 () { $opt_debug # unfortunately, winepath doesn't convert paths, only file names func_convert_core_path_wine_to_w32_result="" if test -n "$1"; then oldIFS=$IFS IFS=: for func_convert_core_path_wine_to_w32_f in $1; do IFS=$oldIFS func_convert_core_file_wine_to_w32 "$func_convert_core_path_wine_to_w32_f" if test -n "$func_convert_core_file_wine_to_w32_result" ; then if test -z "$func_convert_core_path_wine_to_w32_result"; then func_convert_core_path_wine_to_w32_result="$func_convert_core_file_wine_to_w32_result" else func_append func_convert_core_path_wine_to_w32_result ";$func_convert_core_file_wine_to_w32_result" fi fi done IFS=$oldIFS fi } # end: func_convert_core_path_wine_to_w32 # func_cygpath ARGS... # Wrapper around calling the cygpath program via LT_CYGPATH. This is used when # when (1) $build is *nix and Cygwin is hosted via a wine environment; or (2) # $build is MSYS and $host is Cygwin, or (3) $build is Cygwin. In case (1) or # (2), returns the Cygwin file name or path in func_cygpath_result (input # file name or path is assumed to be in w32 format, as previously converted # from $build's *nix or MSYS format). In case (3), returns the w32 file name # or path in func_cygpath_result (input file name or path is assumed to be in # Cygwin format). Returns an empty string on error. # # ARGS are passed to cygpath, with the last one being the file name or path to # be converted. # # Specify the absolute *nix (or w32) name to cygpath in the LT_CYGPATH # environment variable; do not put it in $PATH. func_cygpath () { $opt_debug if test -n "$LT_CYGPATH" && test -f "$LT_CYGPATH"; then func_cygpath_result=`$LT_CYGPATH "$@" 2>/dev/null` if test "$?" -ne 0; then # on failure, ensure result is empty func_cygpath_result= fi else func_cygpath_result= func_error "LT_CYGPATH is empty or specifies non-existent file: \`$LT_CYGPATH'" fi } #end: func_cygpath # func_convert_core_msys_to_w32 ARG # Convert file name or path ARG from MSYS format to w32 format. Return # result in func_convert_core_msys_to_w32_result. func_convert_core_msys_to_w32 () { $opt_debug # awkward: cmd appends spaces to result func_convert_core_msys_to_w32_result=`( cmd //c echo "$1" ) 2>/dev/null | $SED -e 's/[ ]*$//' -e "$lt_sed_naive_backslashify"` } #end: func_convert_core_msys_to_w32 # func_convert_file_check ARG1 ARG2 # Verify that ARG1 (a file name in $build format) was converted to $host # format in ARG2. Otherwise, emit an error message, but continue (resetting # func_to_host_file_result to ARG1). func_convert_file_check () { $opt_debug if test -z "$2" && test -n "$1" ; then func_error "Could not determine host file name corresponding to" func_error " \`$1'" func_error "Continuing, but uninstalled executables may not work." # Fallback: func_to_host_file_result="$1" fi } # end func_convert_file_check # func_convert_path_check FROM_PATHSEP TO_PATHSEP FROM_PATH TO_PATH # Verify that FROM_PATH (a path in $build format) was converted to $host # format in TO_PATH. Otherwise, emit an error message, but continue, resetting # func_to_host_file_result to a simplistic fallback value (see below). func_convert_path_check () { $opt_debug if test -z "$4" && test -n "$3"; then func_error "Could not determine the host path corresponding to" func_error " \`$3'" func_error "Continuing, but uninstalled executables may not work." # Fallback. This is a deliberately simplistic "conversion" and # should not be "improved". See libtool.info. if test "x$1" != "x$2"; then lt_replace_pathsep_chars="s|$1|$2|g" func_to_host_path_result=`echo "$3" | $SED -e "$lt_replace_pathsep_chars"` else func_to_host_path_result="$3" fi fi } # end func_convert_path_check # func_convert_path_front_back_pathsep FRONTPAT BACKPAT REPL ORIG # Modifies func_to_host_path_result by prepending REPL if ORIG matches FRONTPAT # and appending REPL if ORIG matches BACKPAT. func_convert_path_front_back_pathsep () { $opt_debug case $4 in $1 ) func_to_host_path_result="$3$func_to_host_path_result" ;; esac case $4 in $2 ) func_append func_to_host_path_result "$3" ;; esac } # end func_convert_path_front_back_pathsep ################################################## # $build to $host FILE NAME CONVERSION FUNCTIONS # ################################################## # invoked via `$to_host_file_cmd ARG' # # In each case, ARG is the path to be converted from $build to $host format. # Result will be available in $func_to_host_file_result. # func_to_host_file ARG # Converts the file name ARG from $build format to $host format. Return result # in func_to_host_file_result. func_to_host_file () { $opt_debug $to_host_file_cmd "$1" } # end func_to_host_file # func_to_tool_file ARG LAZY # converts the file name ARG from $build format to toolchain format. Return # result in func_to_tool_file_result. If the conversion in use is listed # in (the comma separated) LAZY, no conversion takes place. func_to_tool_file () { $opt_debug case ,$2, in *,"$to_tool_file_cmd",*) func_to_tool_file_result=$1 ;; *) $to_tool_file_cmd "$1" func_to_tool_file_result=$func_to_host_file_result ;; esac } # end func_to_tool_file # func_convert_file_noop ARG # Copy ARG to func_to_host_file_result. func_convert_file_noop () { func_to_host_file_result="$1" } # end func_convert_file_noop # func_convert_file_msys_to_w32 ARG # Convert file name ARG from (mingw) MSYS to (mingw) w32 format; automatic # conversion to w32 is not available inside the cwrapper. Returns result in # func_to_host_file_result. func_convert_file_msys_to_w32 () { $opt_debug func_to_host_file_result="$1" if test -n "$1"; then func_convert_core_msys_to_w32 "$1" func_to_host_file_result="$func_convert_core_msys_to_w32_result" fi func_convert_file_check "$1" "$func_to_host_file_result" } # end func_convert_file_msys_to_w32 # func_convert_file_cygwin_to_w32 ARG # Convert file name ARG from Cygwin to w32 format. Returns result in # func_to_host_file_result. func_convert_file_cygwin_to_w32 () { $opt_debug func_to_host_file_result="$1" if test -n "$1"; then # because $build is cygwin, we call "the" cygpath in $PATH; no need to use # LT_CYGPATH in this case. func_to_host_file_result=`cygpath -m "$1"` fi func_convert_file_check "$1" "$func_to_host_file_result" } # end func_convert_file_cygwin_to_w32 # func_convert_file_nix_to_w32 ARG # Convert file name ARG from *nix to w32 format. Requires a wine environment # and a working winepath. Returns result in func_to_host_file_result. func_convert_file_nix_to_w32 () { $opt_debug func_to_host_file_result="$1" if test -n "$1"; then func_convert_core_file_wine_to_w32 "$1" func_to_host_file_result="$func_convert_core_file_wine_to_w32_result" fi func_convert_file_check "$1" "$func_to_host_file_result" } # end func_convert_file_nix_to_w32 # func_convert_file_msys_to_cygwin ARG # Convert file name ARG from MSYS to Cygwin format. Requires LT_CYGPATH set. # Returns result in func_to_host_file_result. func_convert_file_msys_to_cygwin () { $opt_debug func_to_host_file_result="$1" if test -n "$1"; then func_convert_core_msys_to_w32 "$1" func_cygpath -u "$func_convert_core_msys_to_w32_result" func_to_host_file_result="$func_cygpath_result" fi func_convert_file_check "$1" "$func_to_host_file_result" } # end func_convert_file_msys_to_cygwin # func_convert_file_nix_to_cygwin ARG # Convert file name ARG from *nix to Cygwin format. Requires Cygwin installed # in a wine environment, working winepath, and LT_CYGPATH set. Returns result # in func_to_host_file_result. func_convert_file_nix_to_cygwin () { $opt_debug func_to_host_file_result="$1" if test -n "$1"; then # convert from *nix to w32, then use cygpath to convert from w32 to cygwin. func_convert_core_file_wine_to_w32 "$1" func_cygpath -u "$func_convert_core_file_wine_to_w32_result" func_to_host_file_result="$func_cygpath_result" fi func_convert_file_check "$1" "$func_to_host_file_result" } # end func_convert_file_nix_to_cygwin ############################################# # $build to $host PATH CONVERSION FUNCTIONS # ############################################# # invoked via `$to_host_path_cmd ARG' # # In each case, ARG is the path to be converted from $build to $host format. # The result will be available in $func_to_host_path_result. # # Path separators are also converted from $build format to $host format. If # ARG begins or ends with a path separator character, it is preserved (but # converted to $host format) on output. # # All path conversion functions are named using the following convention: # file name conversion function : func_convert_file_X_to_Y () # path conversion function : func_convert_path_X_to_Y () # where, for any given $build/$host combination the 'X_to_Y' value is the # same. If conversion functions are added for new $build/$host combinations, # the two new functions must follow this pattern, or func_init_to_host_path_cmd # will break. # func_init_to_host_path_cmd # Ensures that function "pointer" variable $to_host_path_cmd is set to the # appropriate value, based on the value of $to_host_file_cmd. to_host_path_cmd= func_init_to_host_path_cmd () { $opt_debug if test -z "$to_host_path_cmd"; then func_stripname 'func_convert_file_' '' "$to_host_file_cmd" to_host_path_cmd="func_convert_path_${func_stripname_result}" fi } # func_to_host_path ARG # Converts the path ARG from $build format to $host format. Return result # in func_to_host_path_result. func_to_host_path () { $opt_debug func_init_to_host_path_cmd $to_host_path_cmd "$1" } # end func_to_host_path # func_convert_path_noop ARG # Copy ARG to func_to_host_path_result. func_convert_path_noop () { func_to_host_path_result="$1" } # end func_convert_path_noop # func_convert_path_msys_to_w32 ARG # Convert path ARG from (mingw) MSYS to (mingw) w32 format; automatic # conversion to w32 is not available inside the cwrapper. Returns result in # func_to_host_path_result. func_convert_path_msys_to_w32 () { $opt_debug func_to_host_path_result="$1" if test -n "$1"; then # Remove leading and trailing path separator characters from ARG. MSYS # behavior is inconsistent here; cygpath turns them into '.;' and ';.'; # and winepath ignores them completely. func_stripname : : "$1" func_to_host_path_tmp1=$func_stripname_result func_convert_core_msys_to_w32 "$func_to_host_path_tmp1" func_to_host_path_result="$func_convert_core_msys_to_w32_result" func_convert_path_check : ";" \ "$func_to_host_path_tmp1" "$func_to_host_path_result" func_convert_path_front_back_pathsep ":*" "*:" ";" "$1" fi } # end func_convert_path_msys_to_w32 # func_convert_path_cygwin_to_w32 ARG # Convert path ARG from Cygwin to w32 format. Returns result in # func_to_host_file_result. func_convert_path_cygwin_to_w32 () { $opt_debug func_to_host_path_result="$1" if test -n "$1"; then # See func_convert_path_msys_to_w32: func_stripname : : "$1" func_to_host_path_tmp1=$func_stripname_result func_to_host_path_result=`cygpath -m -p "$func_to_host_path_tmp1"` func_convert_path_check : ";" \ "$func_to_host_path_tmp1" "$func_to_host_path_result" func_convert_path_front_back_pathsep ":*" "*:" ";" "$1" fi } # end func_convert_path_cygwin_to_w32 # func_convert_path_nix_to_w32 ARG # Convert path ARG from *nix to w32 format. Requires a wine environment and # a working winepath. Returns result in func_to_host_file_result. func_convert_path_nix_to_w32 () { $opt_debug func_to_host_path_result="$1" if test -n "$1"; then # See func_convert_path_msys_to_w32: func_stripname : : "$1" func_to_host_path_tmp1=$func_stripname_result func_convert_core_path_wine_to_w32 "$func_to_host_path_tmp1" func_to_host_path_result="$func_convert_core_path_wine_to_w32_result" func_convert_path_check : ";" \ "$func_to_host_path_tmp1" "$func_to_host_path_result" func_convert_path_front_back_pathsep ":*" "*:" ";" "$1" fi } # end func_convert_path_nix_to_w32 # func_convert_path_msys_to_cygwin ARG # Convert path ARG from MSYS to Cygwin format. Requires LT_CYGPATH set. # Returns result in func_to_host_file_result. func_convert_path_msys_to_cygwin () { $opt_debug func_to_host_path_result="$1" if test -n "$1"; then # See func_convert_path_msys_to_w32: func_stripname : : "$1" func_to_host_path_tmp1=$func_stripname_result func_convert_core_msys_to_w32 "$func_to_host_path_tmp1" func_cygpath -u -p "$func_convert_core_msys_to_w32_result" func_to_host_path_result="$func_cygpath_result" func_convert_path_check : : \ "$func_to_host_path_tmp1" "$func_to_host_path_result" func_convert_path_front_back_pathsep ":*" "*:" : "$1" fi } # end func_convert_path_msys_to_cygwin # func_convert_path_nix_to_cygwin ARG # Convert path ARG from *nix to Cygwin format. Requires Cygwin installed in a # a wine environment, working winepath, and LT_CYGPATH set. Returns result in # func_to_host_file_result. func_convert_path_nix_to_cygwin () { $opt_debug func_to_host_path_result="$1" if test -n "$1"; then # Remove leading and trailing path separator characters from # ARG. msys behavior is inconsistent here, cygpath turns them # into '.;' and ';.', and winepath ignores them completely. func_stripname : : "$1" func_to_host_path_tmp1=$func_stripname_result func_convert_core_path_wine_to_w32 "$func_to_host_path_tmp1" func_cygpath -u -p "$func_convert_core_path_wine_to_w32_result" func_to_host_path_result="$func_cygpath_result" func_convert_path_check : : \ "$func_to_host_path_tmp1" "$func_to_host_path_result" func_convert_path_front_back_pathsep ":*" "*:" : "$1" fi } # end func_convert_path_nix_to_cygwin # func_mode_compile arg... func_mode_compile () { $opt_debug # Get the compilation command and the source file. base_compile= srcfile="$nonopt" # always keep a non-empty value in "srcfile" suppress_opt=yes suppress_output= arg_mode=normal libobj= later= pie_flag= for arg do case $arg_mode in arg ) # do not "continue". Instead, add this to base_compile lastarg="$arg" arg_mode=normal ;; target ) libobj="$arg" arg_mode=normal continue ;; normal ) # Accept any command-line options. case $arg in -o) test -n "$libobj" && \ func_fatal_error "you cannot specify \`-o' more than once" arg_mode=target continue ;; -pie | -fpie | -fPIE) func_append pie_flag " $arg" continue ;; -shared | -static | -prefer-pic | -prefer-non-pic) func_append later " $arg" continue ;; -no-suppress) suppress_opt=no continue ;; -Xcompiler) arg_mode=arg # the next one goes into the "base_compile" arg list continue # The current "srcfile" will either be retained or ;; # replaced later. I would guess that would be a bug. -Wc,*) func_stripname '-Wc,' '' "$arg" args=$func_stripname_result lastarg= save_ifs="$IFS"; IFS=',' for arg in $args; do IFS="$save_ifs" func_append_quoted lastarg "$arg" done IFS="$save_ifs" func_stripname ' ' '' "$lastarg" lastarg=$func_stripname_result # Add the arguments to base_compile. func_append base_compile " $lastarg" continue ;; *) # Accept the current argument as the source file. # The previous "srcfile" becomes the current argument. # lastarg="$srcfile" srcfile="$arg" ;; esac # case $arg ;; esac # case $arg_mode # Aesthetically quote the previous argument. func_append_quoted base_compile "$lastarg" done # for arg case $arg_mode in arg) func_fatal_error "you must specify an argument for -Xcompile" ;; target) func_fatal_error "you must specify a target with \`-o'" ;; *) # Get the name of the library object. test -z "$libobj" && { func_basename "$srcfile" libobj="$func_basename_result" } ;; esac # Recognize several different file suffixes. # If the user specifies -o file.o, it is replaced with file.lo case $libobj in *.[cCFSifmso] | \ *.ada | *.adb | *.ads | *.asm | \ *.c++ | *.cc | *.ii | *.class | *.cpp | *.cxx | \ *.[fF][09]? | *.for | *.java | *.go | *.obj | *.sx | *.cu | *.cup) func_xform "$libobj" libobj=$func_xform_result ;; esac case $libobj in *.lo) func_lo2o "$libobj"; obj=$func_lo2o_result ;; *) func_fatal_error "cannot determine name of library object from \`$libobj'" ;; esac func_infer_tag $base_compile for arg in $later; do case $arg in -shared) test "$build_libtool_libs" != yes && \ func_fatal_configuration "can not build a shared library" build_old_libs=no continue ;; -static) build_libtool_libs=no build_old_libs=yes continue ;; -prefer-pic) pic_mode=yes continue ;; -prefer-non-pic) pic_mode=no continue ;; esac done func_quote_for_eval "$libobj" test "X$libobj" != "X$func_quote_for_eval_result" \ && $ECHO "X$libobj" | $GREP '[]~#^*{};<>?"'"'"' &()|`$[]' \ && func_warning "libobj name \`$libobj' may not contain shell special characters." func_dirname_and_basename "$obj" "/" "" objname="$func_basename_result" xdir="$func_dirname_result" lobj=${xdir}$objdir/$objname test -z "$base_compile" && \ func_fatal_help "you must specify a compilation command" # Delete any leftover library objects. if test "$build_old_libs" = yes; then removelist="$obj $lobj $libobj ${libobj}T" else removelist="$lobj $libobj ${libobj}T" fi # On Cygwin there's no "real" PIC flag so we must build both object types case $host_os in cygwin* | mingw* | pw32* | os2* | cegcc*) pic_mode=default ;; esac if test "$pic_mode" = no && test "$deplibs_check_method" != pass_all; then # non-PIC code in shared libraries is not supported pic_mode=default fi # Calculate the filename of the output object if compiler does # not support -o with -c if test "$compiler_c_o" = no; then output_obj=`$ECHO "$srcfile" | $SED 's%^.*/%%; s%\.[^.]*$%%'`.${objext} lockfile="$output_obj.lock" else output_obj= need_locks=no lockfile= fi # Lock this critical section if it is needed # We use this script file to make the link, it avoids creating a new file if test "$need_locks" = yes; then until $opt_dry_run || ln "$progpath" "$lockfile" 2>/dev/null; do func_echo "Waiting for $lockfile to be removed" sleep 2 done elif test "$need_locks" = warn; then if test -f "$lockfile"; then $ECHO "\ *** ERROR, $lockfile exists and contains: `cat $lockfile 2>/dev/null` This indicates that another process is trying to use the same temporary object file, and libtool could not work around it because your compiler does not support \`-c' and \`-o' together. If you repeat this compilation, it may succeed, by chance, but you had better avoid parallel builds (make -j) in this platform, or get a better compiler." $opt_dry_run || $RM $removelist exit $EXIT_FAILURE fi func_append removelist " $output_obj" $ECHO "$srcfile" > "$lockfile" fi $opt_dry_run || $RM $removelist func_append removelist " $lockfile" trap '$opt_dry_run || $RM $removelist; exit $EXIT_FAILURE' 1 2 15 func_to_tool_file "$srcfile" func_convert_file_msys_to_w32 srcfile=$func_to_tool_file_result func_quote_for_eval "$srcfile" qsrcfile=$func_quote_for_eval_result # Only build a PIC object if we are building libtool libraries. if test "$build_libtool_libs" = yes; then # Without this assignment, base_compile gets emptied. fbsd_hideous_sh_bug=$base_compile if test "$pic_mode" != no; then command="$base_compile $qsrcfile $pic_flag" else # Don't build PIC code command="$base_compile $qsrcfile" fi func_mkdir_p "$xdir$objdir" if test -z "$output_obj"; then # Place PIC objects in $objdir func_append command " -o $lobj" fi func_show_eval_locale "$command" \ 'test -n "$output_obj" && $RM $removelist; exit $EXIT_FAILURE' if test "$need_locks" = warn && test "X`cat $lockfile 2>/dev/null`" != "X$srcfile"; then $ECHO "\ *** ERROR, $lockfile contains: `cat $lockfile 2>/dev/null` but it should contain: $srcfile This indicates that another process is trying to use the same temporary object file, and libtool could not work around it because your compiler does not support \`-c' and \`-o' together. If you repeat this compilation, it may succeed, by chance, but you had better avoid parallel builds (make -j) in this platform, or get a better compiler." $opt_dry_run || $RM $removelist exit $EXIT_FAILURE fi # Just move the object if needed, then go on to compile the next one if test -n "$output_obj" && test "X$output_obj" != "X$lobj"; then func_show_eval '$MV "$output_obj" "$lobj"' \ 'error=$?; $opt_dry_run || $RM $removelist; exit $error' fi # Allow error messages only from the first compilation. if test "$suppress_opt" = yes; then suppress_output=' >/dev/null 2>&1' fi fi # Only build a position-dependent object if we build old libraries. if test "$build_old_libs" = yes; then if test "$pic_mode" != yes; then # Don't build PIC code command="$base_compile $qsrcfile$pie_flag" else command="$base_compile $qsrcfile $pic_flag" fi if test "$compiler_c_o" = yes; then func_append command " -o $obj" fi # Suppress compiler output if we already did a PIC compilation. func_append command "$suppress_output" func_show_eval_locale "$command" \ '$opt_dry_run || $RM $removelist; exit $EXIT_FAILURE' if test "$need_locks" = warn && test "X`cat $lockfile 2>/dev/null`" != "X$srcfile"; then $ECHO "\ *** ERROR, $lockfile contains: `cat $lockfile 2>/dev/null` but it should contain: $srcfile This indicates that another process is trying to use the same temporary object file, and libtool could not work around it because your compiler does not support \`-c' and \`-o' together. If you repeat this compilation, it may succeed, by chance, but you had better avoid parallel builds (make -j) in this platform, or get a better compiler." $opt_dry_run || $RM $removelist exit $EXIT_FAILURE fi # Just move the object if needed if test -n "$output_obj" && test "X$output_obj" != "X$obj"; then func_show_eval '$MV "$output_obj" "$obj"' \ 'error=$?; $opt_dry_run || $RM $removelist; exit $error' fi fi $opt_dry_run || { func_write_libtool_object "$libobj" "$objdir/$objname" "$objname" # Unlock the critical section if it was locked if test "$need_locks" != no; then removelist=$lockfile $RM "$lockfile" fi } exit $EXIT_SUCCESS } $opt_help || { test "$opt_mode" = compile && func_mode_compile ${1+"$@"} } func_mode_help () { # We need to display help for each of the modes. case $opt_mode in "") # Generic help is extracted from the usage comments # at the start of this file. func_help ;; clean) $ECHO \ "Usage: $progname [OPTION]... --mode=clean RM [RM-OPTION]... FILE... Remove files from the build directory. RM is the name of the program to use to delete files associated with each FILE (typically \`/bin/rm'). RM-OPTIONS are options (such as \`-f') to be passed to RM. If FILE is a libtool library, object or program, all the files associated with it are deleted. Otherwise, only FILE itself is deleted using RM." ;; compile) $ECHO \ "Usage: $progname [OPTION]... --mode=compile COMPILE-COMMAND... SOURCEFILE Compile a source file into a libtool library object. This mode accepts the following additional options: -o OUTPUT-FILE set the output file name to OUTPUT-FILE -no-suppress do not suppress compiler output for multiple passes -prefer-pic try to build PIC objects only -prefer-non-pic try to build non-PIC objects only -shared do not build a \`.o' file suitable for static linking -static only build a \`.o' file suitable for static linking -Wc,FLAG pass FLAG directly to the compiler COMPILE-COMMAND is a command to be used in creating a \`standard' object file from the given SOURCEFILE. The output file name is determined by removing the directory component from SOURCEFILE, then substituting the C source code suffix \`.c' with the library object suffix, \`.lo'." ;; execute) $ECHO \ "Usage: $progname [OPTION]... --mode=execute COMMAND [ARGS]... Automatically set library path, then run a program. This mode accepts the following additional options: -dlopen FILE add the directory containing FILE to the library path This mode sets the library path environment variable according to \`-dlopen' flags. If any of the ARGS are libtool executable wrappers, then they are translated into their corresponding uninstalled binary, and any of their required library directories are added to the library path. Then, COMMAND is executed, with ARGS as arguments." ;; finish) $ECHO \ "Usage: $progname [OPTION]... --mode=finish [LIBDIR]... Complete the installation of libtool libraries. Each LIBDIR is a directory that contains libtool libraries. The commands that this mode executes may require superuser privileges. Use the \`--dry-run' option if you just want to see what would be executed." ;; install) $ECHO \ "Usage: $progname [OPTION]... --mode=install INSTALL-COMMAND... Install executables or libraries. INSTALL-COMMAND is the installation command. The first component should be either the \`install' or \`cp' program. The following components of INSTALL-COMMAND are treated specially: -inst-prefix-dir PREFIX-DIR Use PREFIX-DIR as a staging area for installation The rest of the components are interpreted as arguments to that command (only BSD-compatible install options are recognized)." ;; link) $ECHO \ "Usage: $progname [OPTION]... --mode=link LINK-COMMAND... Link object files or libraries together to form another library, or to create an executable program. LINK-COMMAND is a command using the C compiler that you would use to create a program from several object files. The following components of LINK-COMMAND are treated specially: -all-static do not do any dynamic linking at all -avoid-version do not add a version suffix if possible -bindir BINDIR specify path to binaries directory (for systems where libraries must be found in the PATH setting at runtime) -dlopen FILE \`-dlpreopen' FILE if it cannot be dlopened at runtime -dlpreopen FILE link in FILE and add its symbols to lt_preloaded_symbols -export-dynamic allow symbols from OUTPUT-FILE to be resolved with dlsym(3) -export-symbols SYMFILE try to export only the symbols listed in SYMFILE -export-symbols-regex REGEX try to export only the symbols matching REGEX -LLIBDIR search LIBDIR for required installed libraries -lNAME OUTPUT-FILE requires the installed library libNAME -module build a library that can dlopened -no-fast-install disable the fast-install mode -no-install link a not-installable executable -no-undefined declare that a library does not refer to external symbols -o OUTPUT-FILE create OUTPUT-FILE from the specified objects -objectlist FILE Use a list of object files found in FILE to specify objects -precious-files-regex REGEX don't remove output files matching REGEX -release RELEASE specify package release information -rpath LIBDIR the created library will eventually be installed in LIBDIR -R[ ]LIBDIR add LIBDIR to the runtime path of programs and libraries -shared only do dynamic linking of libtool libraries -shrext SUFFIX override the standard shared library file extension -static do not do any dynamic linking of uninstalled libtool libraries -static-libtool-libs do not do any dynamic linking of libtool libraries -version-info CURRENT[:REVISION[:AGE]] specify library version info [each variable defaults to 0] -weak LIBNAME declare that the target provides the LIBNAME interface -Wc,FLAG -Xcompiler FLAG pass linker-specific FLAG directly to the compiler -Wl,FLAG -Xlinker FLAG pass linker-specific FLAG directly to the linker -XCClinker FLAG pass link-specific FLAG to the compiler driver (CC) All other options (arguments beginning with \`-') are ignored. Every other argument is treated as a filename. Files ending in \`.la' are treated as uninstalled libtool libraries, other files are standard or library object files. If the OUTPUT-FILE ends in \`.la', then a libtool library is created, only library objects (\`.lo' files) may be specified, and \`-rpath' is required, except when creating a convenience library. If OUTPUT-FILE ends in \`.a' or \`.lib', then a standard library is created using \`ar' and \`ranlib', or on Windows using \`lib'. If OUTPUT-FILE ends in \`.lo' or \`.${objext}', then a reloadable object file is created, otherwise an executable program is created." ;; uninstall) $ECHO \ "Usage: $progname [OPTION]... --mode=uninstall RM [RM-OPTION]... FILE... Remove libraries from an installation directory. RM is the name of the program to use to delete files associated with each FILE (typically \`/bin/rm'). RM-OPTIONS are options (such as \`-f') to be passed to RM. If FILE is a libtool library, all the files associated with it are deleted. Otherwise, only FILE itself is deleted using RM." ;; *) func_fatal_help "invalid operation mode \`$opt_mode'" ;; esac echo $ECHO "Try \`$progname --help' for more information about other modes." } # Now that we've collected a possible --mode arg, show help if necessary if $opt_help; then if test "$opt_help" = :; then func_mode_help else { func_help noexit for opt_mode in compile link execute install finish uninstall clean; do func_mode_help done } | sed -n '1p; 2,$s/^Usage:/ or: /p' { func_help noexit for opt_mode in compile link execute install finish uninstall clean; do echo func_mode_help done } | sed '1d /^When reporting/,/^Report/{ H d } $x /information about other modes/d /more detailed .*MODE/d s/^Usage:.*--mode=\([^ ]*\) .*/Description of \1 mode:/' fi exit $? fi # func_mode_execute arg... func_mode_execute () { $opt_debug # The first argument is the command name. cmd="$nonopt" test -z "$cmd" && \ func_fatal_help "you must specify a COMMAND" # Handle -dlopen flags immediately. for file in $opt_dlopen; do test -f "$file" \ || func_fatal_help "\`$file' is not a file" dir= case $file in *.la) func_resolve_sysroot "$file" file=$func_resolve_sysroot_result # Check to see that this really is a libtool archive. func_lalib_unsafe_p "$file" \ || func_fatal_help "\`$lib' is not a valid libtool archive" # Read the libtool library. dlname= library_names= func_source "$file" # Skip this library if it cannot be dlopened. if test -z "$dlname"; then # Warn if it was a shared library. test -n "$library_names" && \ func_warning "\`$file' was not linked with \`-export-dynamic'" continue fi func_dirname "$file" "" "." dir="$func_dirname_result" if test -f "$dir/$objdir/$dlname"; then func_append dir "/$objdir" else if test ! -f "$dir/$dlname"; then func_fatal_error "cannot find \`$dlname' in \`$dir' or \`$dir/$objdir'" fi fi ;; *.lo) # Just add the directory containing the .lo file. func_dirname "$file" "" "." dir="$func_dirname_result" ;; *) func_warning "\`-dlopen' is ignored for non-libtool libraries and objects" continue ;; esac # Get the absolute pathname. absdir=`cd "$dir" && pwd` test -n "$absdir" && dir="$absdir" # Now add the directory to shlibpath_var. if eval "test -z \"\$$shlibpath_var\""; then eval "$shlibpath_var=\"\$dir\"" else eval "$shlibpath_var=\"\$dir:\$$shlibpath_var\"" fi done # This variable tells wrapper scripts just to set shlibpath_var # rather than running their programs. libtool_execute_magic="$magic" # Check if any of the arguments is a wrapper script. args= for file do case $file in -* | *.la | *.lo ) ;; *) # Do a test to see if this is really a libtool program. if func_ltwrapper_script_p "$file"; then func_source "$file" # Transform arg to wrapped name. file="$progdir/$program" elif func_ltwrapper_executable_p "$file"; then func_ltwrapper_scriptname "$file" func_source "$func_ltwrapper_scriptname_result" # Transform arg to wrapped name. file="$progdir/$program" fi ;; esac # Quote arguments (to preserve shell metacharacters). func_append_quoted args "$file" done if test "X$opt_dry_run" = Xfalse; then if test -n "$shlibpath_var"; then # Export the shlibpath_var. eval "export $shlibpath_var" fi # Restore saved environment variables for lt_var in LANG LANGUAGE LC_ALL LC_CTYPE LC_COLLATE LC_MESSAGES do eval "if test \"\${save_$lt_var+set}\" = set; then $lt_var=\$save_$lt_var; export $lt_var else $lt_unset $lt_var fi" done # Now prepare to actually exec the command. exec_cmd="\$cmd$args" else # Display what would be done. if test -n "$shlibpath_var"; then eval "\$ECHO \"\$shlibpath_var=\$$shlibpath_var\"" echo "export $shlibpath_var" fi $ECHO "$cmd$args" exit $EXIT_SUCCESS fi } test "$opt_mode" = execute && func_mode_execute ${1+"$@"} # func_mode_finish arg... func_mode_finish () { $opt_debug libs= libdirs= admincmds= for opt in "$nonopt" ${1+"$@"} do if test -d "$opt"; then func_append libdirs " $opt" elif test -f "$opt"; then if func_lalib_unsafe_p "$opt"; then func_append libs " $opt" else func_warning "\`$opt' is not a valid libtool archive" fi else func_fatal_error "invalid argument \`$opt'" fi done if test -n "$libs"; then if test -n "$lt_sysroot"; then sysroot_regex=`$ECHO "$lt_sysroot" | $SED "$sed_make_literal_regex"` sysroot_cmd="s/\([ ']\)$sysroot_regex/\1/g;" else sysroot_cmd= fi # Remove sysroot references if $opt_dry_run; then for lib in $libs; do echo "removing references to $lt_sysroot and \`=' prefixes from $lib" done else tmpdir=`func_mktempdir` for lib in $libs; do sed -e "${sysroot_cmd} s/\([ ']-[LR]\)=/\1/g; s/\([ ']\)=/\1/g" $lib \ > $tmpdir/tmp-la mv -f $tmpdir/tmp-la $lib done ${RM}r "$tmpdir" fi fi if test -n "$finish_cmds$finish_eval" && test -n "$libdirs"; then for libdir in $libdirs; do if test -n "$finish_cmds"; then # Do each command in the finish commands. func_execute_cmds "$finish_cmds" 'admincmds="$admincmds '"$cmd"'"' fi if test -n "$finish_eval"; then # Do the single finish_eval. eval cmds=\"$finish_eval\" $opt_dry_run || eval "$cmds" || func_append admincmds " $cmds" fi done fi # Exit here if they wanted silent mode. $opt_silent && exit $EXIT_SUCCESS if test -n "$finish_cmds$finish_eval" && test -n "$libdirs"; then echo "----------------------------------------------------------------------" echo "Libraries have been installed in:" for libdir in $libdirs; do $ECHO " $libdir" done echo echo "If you ever happen to want to link against installed libraries" echo "in a given directory, LIBDIR, you must either use libtool, and" echo "specify the full pathname of the library, or use the \`-LLIBDIR'" echo "flag during linking and do at least one of the following:" if test -n "$shlibpath_var"; then echo " - add LIBDIR to the \`$shlibpath_var' environment variable" echo " during execution" fi if test -n "$runpath_var"; then echo " - add LIBDIR to the \`$runpath_var' environment variable" echo " during linking" fi if test -n "$hardcode_libdir_flag_spec"; then libdir=LIBDIR eval flag=\"$hardcode_libdir_flag_spec\" $ECHO " - use the \`$flag' linker flag" fi if test -n "$admincmds"; then $ECHO " - have your system administrator run these commands:$admincmds" fi if test -f /etc/ld.so.conf; then echo " - have your system administrator add LIBDIR to \`/etc/ld.so.conf'" fi echo echo "See any operating system documentation about shared libraries for" case $host in solaris2.[6789]|solaris2.1[0-9]) echo "more information, such as the ld(1), crle(1) and ld.so(8) manual" echo "pages." ;; *) echo "more information, such as the ld(1) and ld.so(8) manual pages." ;; esac echo "----------------------------------------------------------------------" fi exit $EXIT_SUCCESS } test "$opt_mode" = finish && func_mode_finish ${1+"$@"} # func_mode_install arg... func_mode_install () { $opt_debug # There may be an optional sh(1) argument at the beginning of # install_prog (especially on Windows NT). if test "$nonopt" = "$SHELL" || test "$nonopt" = /bin/sh || # Allow the use of GNU shtool's install command. case $nonopt in *shtool*) :;; *) false;; esac; then # Aesthetically quote it. func_quote_for_eval "$nonopt" install_prog="$func_quote_for_eval_result " arg=$1 shift else install_prog= arg=$nonopt fi # The real first argument should be the name of the installation program. # Aesthetically quote it. func_quote_for_eval "$arg" func_append install_prog "$func_quote_for_eval_result" install_shared_prog=$install_prog case " $install_prog " in *[\\\ /]cp\ *) install_cp=: ;; *) install_cp=false ;; esac # We need to accept at least all the BSD install flags. dest= files= opts= prev= install_type= isdir=no stripme= no_mode=: for arg do arg2= if test -n "$dest"; then func_append files " $dest" dest=$arg continue fi case $arg in -d) isdir=yes ;; -f) if $install_cp; then :; else prev=$arg fi ;; -g | -m | -o) prev=$arg ;; -s) stripme=" -s" continue ;; -*) ;; *) # If the previous option needed an argument, then skip it. if test -n "$prev"; then if test "x$prev" = x-m && test -n "$install_override_mode"; then arg2=$install_override_mode no_mode=false fi prev= else dest=$arg continue fi ;; esac # Aesthetically quote the argument. func_quote_for_eval "$arg" func_append install_prog " $func_quote_for_eval_result" if test -n "$arg2"; then func_quote_for_eval "$arg2" fi func_append install_shared_prog " $func_quote_for_eval_result" done test -z "$install_prog" && \ func_fatal_help "you must specify an install program" test -n "$prev" && \ func_fatal_help "the \`$prev' option requires an argument" if test -n "$install_override_mode" && $no_mode; then if $install_cp; then :; else func_quote_for_eval "$install_override_mode" func_append install_shared_prog " -m $func_quote_for_eval_result" fi fi if test -z "$files"; then if test -z "$dest"; then func_fatal_help "no file or destination specified" else func_fatal_help "you must specify a destination" fi fi # Strip any trailing slash from the destination. func_stripname '' '/' "$dest" dest=$func_stripname_result # Check to see that the destination is a directory. test -d "$dest" && isdir=yes if test "$isdir" = yes; then destdir="$dest" destname= else func_dirname_and_basename "$dest" "" "." destdir="$func_dirname_result" destname="$func_basename_result" # Not a directory, so check to see that there is only one file specified. set dummy $files; shift test "$#" -gt 1 && \ func_fatal_help "\`$dest' is not a directory" fi case $destdir in [\\/]* | [A-Za-z]:[\\/]*) ;; *) for file in $files; do case $file in *.lo) ;; *) func_fatal_help "\`$destdir' must be an absolute directory name" ;; esac done ;; esac # This variable tells wrapper scripts just to set variables rather # than running their programs. libtool_install_magic="$magic" staticlibs= future_libdirs= current_libdirs= for file in $files; do # Do each installation. case $file in *.$libext) # Do the static libraries later. func_append staticlibs " $file" ;; *.la) func_resolve_sysroot "$file" file=$func_resolve_sysroot_result # Check to see that this really is a libtool archive. func_lalib_unsafe_p "$file" \ || func_fatal_help "\`$file' is not a valid libtool archive" library_names= old_library= relink_command= func_source "$file" # Add the libdir to current_libdirs if it is the destination. if test "X$destdir" = "X$libdir"; then case "$current_libdirs " in *" $libdir "*) ;; *) func_append current_libdirs " $libdir" ;; esac else # Note the libdir as a future libdir. case "$future_libdirs " in *" $libdir "*) ;; *) func_append future_libdirs " $libdir" ;; esac fi func_dirname "$file" "/" "" dir="$func_dirname_result" func_append dir "$objdir" if test -n "$relink_command"; then # Determine the prefix the user has applied to our future dir. inst_prefix_dir=`$ECHO "$destdir" | $SED -e "s%$libdir\$%%"` # Don't allow the user to place us outside of our expected # location b/c this prevents finding dependent libraries that # are installed to the same prefix. # At present, this check doesn't affect windows .dll's that # are installed into $libdir/../bin (currently, that works fine) # but it's something to keep an eye on. test "$inst_prefix_dir" = "$destdir" && \ func_fatal_error "error: cannot install \`$file' to a directory not ending in $libdir" if test -n "$inst_prefix_dir"; then # Stick the inst_prefix_dir data into the link command. relink_command=`$ECHO "$relink_command" | $SED "s%@inst_prefix_dir@%-inst-prefix-dir $inst_prefix_dir%"` else relink_command=`$ECHO "$relink_command" | $SED "s%@inst_prefix_dir@%%"` fi func_warning "relinking \`$file'" func_show_eval "$relink_command" \ 'func_fatal_error "error: relink \`$file'\'' with the above command before installing it"' fi # See the names of the shared library. set dummy $library_names; shift if test -n "$1"; then realname="$1" shift srcname="$realname" test -n "$relink_command" && srcname="$realname"T # Install the shared library and build the symlinks. func_show_eval "$install_shared_prog $dir/$srcname $destdir/$realname" \ 'exit $?' tstripme="$stripme" case $host_os in cygwin* | mingw* | pw32* | cegcc*) case $realname in *.dll.a) tstripme="" ;; esac ;; esac if test -n "$tstripme" && test -n "$striplib"; then func_show_eval "$striplib $destdir/$realname" 'exit $?' fi if test "$#" -gt 0; then # Delete the old symlinks, and create new ones. # Try `ln -sf' first, because the `ln' binary might depend on # the symlink we replace! Solaris /bin/ln does not understand -f, # so we also need to try rm && ln -s. for linkname do test "$linkname" != "$realname" \ && func_show_eval "(cd $destdir && { $LN_S -f $realname $linkname || { $RM $linkname && $LN_S $realname $linkname; }; })" done fi # Do each command in the postinstall commands. lib="$destdir/$realname" func_execute_cmds "$postinstall_cmds" 'exit $?' fi # Install the pseudo-library for information purposes. func_basename "$file" name="$func_basename_result" instname="$dir/$name"i func_show_eval "$install_prog $instname $destdir/$name" 'exit $?' # Maybe install the static library, too. test -n "$old_library" && func_append staticlibs " $dir/$old_library" ;; *.lo) # Install (i.e. copy) a libtool object. # Figure out destination file name, if it wasn't already specified. if test -n "$destname"; then destfile="$destdir/$destname" else func_basename "$file" destfile="$func_basename_result" destfile="$destdir/$destfile" fi # Deduce the name of the destination old-style object file. case $destfile in *.lo) func_lo2o "$destfile" staticdest=$func_lo2o_result ;; *.$objext) staticdest="$destfile" destfile= ;; *) func_fatal_help "cannot copy a libtool object to \`$destfile'" ;; esac # Install the libtool object if requested. test -n "$destfile" && \ func_show_eval "$install_prog $file $destfile" 'exit $?' # Install the old object if enabled. if test "$build_old_libs" = yes; then # Deduce the name of the old-style object file. func_lo2o "$file" staticobj=$func_lo2o_result func_show_eval "$install_prog \$staticobj \$staticdest" 'exit $?' fi exit $EXIT_SUCCESS ;; *) # Figure out destination file name, if it wasn't already specified. if test -n "$destname"; then destfile="$destdir/$destname" else func_basename "$file" destfile="$func_basename_result" destfile="$destdir/$destfile" fi # If the file is missing, and there is a .exe on the end, strip it # because it is most likely a libtool script we actually want to # install stripped_ext="" case $file in *.exe) if test ! -f "$file"; then func_stripname '' '.exe' "$file" file=$func_stripname_result stripped_ext=".exe" fi ;; esac # Do a test to see if this is really a libtool program. case $host in *cygwin* | *mingw*) if func_ltwrapper_executable_p "$file"; then func_ltwrapper_scriptname "$file" wrapper=$func_ltwrapper_scriptname_result else func_stripname '' '.exe' "$file" wrapper=$func_stripname_result fi ;; *) wrapper=$file ;; esac if func_ltwrapper_script_p "$wrapper"; then notinst_deplibs= relink_command= func_source "$wrapper" # Check the variables that should have been set. test -z "$generated_by_libtool_version" && \ func_fatal_error "invalid libtool wrapper script \`$wrapper'" finalize=yes for lib in $notinst_deplibs; do # Check to see that each library is installed. libdir= if test -f "$lib"; then func_source "$lib" fi libfile="$libdir/"`$ECHO "$lib" | $SED 's%^.*/%%g'` ### testsuite: skip nested quoting test if test -n "$libdir" && test ! -f "$libfile"; then func_warning "\`$lib' has not been installed in \`$libdir'" finalize=no fi done relink_command= func_source "$wrapper" outputname= if test "$fast_install" = no && test -n "$relink_command"; then $opt_dry_run || { if test "$finalize" = yes; then tmpdir=`func_mktempdir` func_basename "$file$stripped_ext" file="$func_basename_result" outputname="$tmpdir/$file" # Replace the output file specification. relink_command=`$ECHO "$relink_command" | $SED 's%@OUTPUT@%'"$outputname"'%g'` $opt_silent || { func_quote_for_expand "$relink_command" eval "func_echo $func_quote_for_expand_result" } if eval "$relink_command"; then : else func_error "error: relink \`$file' with the above command before installing it" $opt_dry_run || ${RM}r "$tmpdir" continue fi file="$outputname" else func_warning "cannot relink \`$file'" fi } else # Install the binary that we compiled earlier. file=`$ECHO "$file$stripped_ext" | $SED "s%\([^/]*\)$%$objdir/\1%"` fi fi # remove .exe since cygwin /usr/bin/install will append another # one anyway case $install_prog,$host in */usr/bin/install*,*cygwin*) case $file:$destfile in *.exe:*.exe) # this is ok ;; *.exe:*) destfile=$destfile.exe ;; *:*.exe) func_stripname '' '.exe' "$destfile" destfile=$func_stripname_result ;; esac ;; esac func_show_eval "$install_prog\$stripme \$file \$destfile" 'exit $?' $opt_dry_run || if test -n "$outputname"; then ${RM}r "$tmpdir" fi ;; esac done for file in $staticlibs; do func_basename "$file" name="$func_basename_result" # Set up the ranlib parameters. oldlib="$destdir/$name" func_to_tool_file "$oldlib" func_convert_file_msys_to_w32 tool_oldlib=$func_to_tool_file_result func_show_eval "$install_prog \$file \$oldlib" 'exit $?' if test -n "$stripme" && test -n "$old_striplib"; then func_show_eval "$old_striplib $tool_oldlib" 'exit $?' fi # Do each command in the postinstall commands. func_execute_cmds "$old_postinstall_cmds" 'exit $?' done test -n "$future_libdirs" && \ func_warning "remember to run \`$progname --finish$future_libdirs'" if test -n "$current_libdirs"; then # Maybe just do a dry run. $opt_dry_run && current_libdirs=" -n$current_libdirs" exec_cmd='$SHELL $progpath $preserve_args --finish$current_libdirs' else exit $EXIT_SUCCESS fi } test "$opt_mode" = install && func_mode_install ${1+"$@"} # func_generate_dlsyms outputname originator pic_p # Extract symbols from dlprefiles and create ${outputname}S.o with # a dlpreopen symbol table. func_generate_dlsyms () { $opt_debug my_outputname="$1" my_originator="$2" my_pic_p="${3-no}" my_prefix=`$ECHO "$my_originator" | sed 's%[^a-zA-Z0-9]%_%g'` my_dlsyms= if test -n "$dlfiles$dlprefiles" || test "$dlself" != no; then if test -n "$NM" && test -n "$global_symbol_pipe"; then my_dlsyms="${my_outputname}S.c" else func_error "not configured to extract global symbols from dlpreopened files" fi fi if test -n "$my_dlsyms"; then case $my_dlsyms in "") ;; *.c) # Discover the nlist of each of the dlfiles. nlist="$output_objdir/${my_outputname}.nm" func_show_eval "$RM $nlist ${nlist}S ${nlist}T" # Parse the name list into a source file. func_verbose "creating $output_objdir/$my_dlsyms" $opt_dry_run || $ECHO > "$output_objdir/$my_dlsyms" "\ /* $my_dlsyms - symbol resolution table for \`$my_outputname' dlsym emulation. */ /* Generated by $PROGRAM (GNU $PACKAGE$TIMESTAMP) $VERSION */ #ifdef __cplusplus extern \"C\" { #endif #if defined(__GNUC__) && (((__GNUC__ == 4) && (__GNUC_MINOR__ >= 4)) || (__GNUC__ > 4)) #pragma GCC diagnostic ignored \"-Wstrict-prototypes\" #endif /* Keep this code in sync between libtool.m4, ltmain, lt_system.h, and tests. */ #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE) /* DATA imports from DLLs on WIN32 con't be const, because runtime relocations are performed -- see ld's documentation on pseudo-relocs. */ # define LT_DLSYM_CONST #elif defined(__osf__) /* This system does not cope well with relocations in const data. */ # define LT_DLSYM_CONST #else # define LT_DLSYM_CONST const #endif /* External symbol declarations for the compiler. */\ " if test "$dlself" = yes; then func_verbose "generating symbol list for \`$output'" $opt_dry_run || echo ': @PROGRAM@ ' > "$nlist" # Add our own program objects to the symbol list. progfiles=`$ECHO "$objs$old_deplibs" | $SP2NL | $SED "$lo2o" | $NL2SP` for progfile in $progfiles; do func_to_tool_file "$progfile" func_convert_file_msys_to_w32 func_verbose "extracting global C symbols from \`$func_to_tool_file_result'" $opt_dry_run || eval "$NM $func_to_tool_file_result | $global_symbol_pipe >> '$nlist'" done if test -n "$exclude_expsyms"; then $opt_dry_run || { eval '$EGREP -v " ($exclude_expsyms)$" "$nlist" > "$nlist"T' eval '$MV "$nlist"T "$nlist"' } fi if test -n "$export_symbols_regex"; then $opt_dry_run || { eval '$EGREP -e "$export_symbols_regex" "$nlist" > "$nlist"T' eval '$MV "$nlist"T "$nlist"' } fi # Prepare the list of exported symbols if test -z "$export_symbols"; then export_symbols="$output_objdir/$outputname.exp" $opt_dry_run || { $RM $export_symbols eval "${SED} -n -e '/^: @PROGRAM@ $/d' -e 's/^.* \(.*\)$/\1/p' "'< "$nlist" > "$export_symbols"' case $host in *cygwin* | *mingw* | *cegcc* ) eval "echo EXPORTS "'> "$output_objdir/$outputname.def"' eval 'cat "$export_symbols" >> "$output_objdir/$outputname.def"' ;; esac } else $opt_dry_run || { eval "${SED} -e 's/\([].[*^$]\)/\\\\\1/g' -e 's/^/ /' -e 's/$/$/'"' < "$export_symbols" > "$output_objdir/$outputname.exp"' eval '$GREP -f "$output_objdir/$outputname.exp" < "$nlist" > "$nlist"T' eval '$MV "$nlist"T "$nlist"' case $host in *cygwin* | *mingw* | *cegcc* ) eval "echo EXPORTS "'> "$output_objdir/$outputname.def"' eval 'cat "$nlist" >> "$output_objdir/$outputname.def"' ;; esac } fi fi for dlprefile in $dlprefiles; do func_verbose "extracting global C symbols from \`$dlprefile'" func_basename "$dlprefile" name="$func_basename_result" case $host in *cygwin* | *mingw* | *cegcc* ) # if an import library, we need to obtain dlname if func_win32_import_lib_p "$dlprefile"; then func_tr_sh "$dlprefile" eval "curr_lafile=\$libfile_$func_tr_sh_result" dlprefile_dlbasename="" if test -n "$curr_lafile" && func_lalib_p "$curr_lafile"; then # Use subshell, to avoid clobbering current variable values dlprefile_dlname=`source "$curr_lafile" && echo "$dlname"` if test -n "$dlprefile_dlname" ; then func_basename "$dlprefile_dlname" dlprefile_dlbasename="$func_basename_result" else # no lafile. user explicitly requested -dlpreopen . $sharedlib_from_linklib_cmd "$dlprefile" dlprefile_dlbasename=$sharedlib_from_linklib_result fi fi $opt_dry_run || { if test -n "$dlprefile_dlbasename" ; then eval '$ECHO ": $dlprefile_dlbasename" >> "$nlist"' else func_warning "Could not compute DLL name from $name" eval '$ECHO ": $name " >> "$nlist"' fi func_to_tool_file "$dlprefile" func_convert_file_msys_to_w32 eval "$NM \"$func_to_tool_file_result\" 2>/dev/null | $global_symbol_pipe | $SED -e '/I __imp/d' -e 's/I __nm_/D /;s/_nm__//' >> '$nlist'" } else # not an import lib $opt_dry_run || { eval '$ECHO ": $name " >> "$nlist"' func_to_tool_file "$dlprefile" func_convert_file_msys_to_w32 eval "$NM \"$func_to_tool_file_result\" 2>/dev/null | $global_symbol_pipe >> '$nlist'" } fi ;; *) $opt_dry_run || { eval '$ECHO ": $name " >> "$nlist"' func_to_tool_file "$dlprefile" func_convert_file_msys_to_w32 eval "$NM \"$func_to_tool_file_result\" 2>/dev/null | $global_symbol_pipe >> '$nlist'" } ;; esac done $opt_dry_run || { # Make sure we have at least an empty file. test -f "$nlist" || : > "$nlist" if test -n "$exclude_expsyms"; then $EGREP -v " ($exclude_expsyms)$" "$nlist" > "$nlist"T $MV "$nlist"T "$nlist" fi # Try sorting and uniquifying the output. if $GREP -v "^: " < "$nlist" | if sort -k 3 /dev/null 2>&1; then sort -k 3 else sort +2 fi | uniq > "$nlist"S; then : else $GREP -v "^: " < "$nlist" > "$nlist"S fi if test -f "$nlist"S; then eval "$global_symbol_to_cdecl"' < "$nlist"S >> "$output_objdir/$my_dlsyms"' else echo '/* NONE */' >> "$output_objdir/$my_dlsyms" fi echo >> "$output_objdir/$my_dlsyms" "\ /* The mapping between symbol names and symbols. */ typedef struct { const char *name; void *address; } lt_dlsymlist; extern LT_DLSYM_CONST lt_dlsymlist lt_${my_prefix}_LTX_preloaded_symbols[]; LT_DLSYM_CONST lt_dlsymlist lt_${my_prefix}_LTX_preloaded_symbols[] = {\ { \"$my_originator\", (void *) 0 }," case $need_lib_prefix in no) eval "$global_symbol_to_c_name_address" < "$nlist" >> "$output_objdir/$my_dlsyms" ;; *) eval "$global_symbol_to_c_name_address_lib_prefix" < "$nlist" >> "$output_objdir/$my_dlsyms" ;; esac echo >> "$output_objdir/$my_dlsyms" "\ {0, (void *) 0} }; /* This works around a problem in FreeBSD linker */ #ifdef FREEBSD_WORKAROUND static const void *lt_preloaded_setup() { return lt_${my_prefix}_LTX_preloaded_symbols; } #endif #ifdef __cplusplus } #endif\ " } # !$opt_dry_run pic_flag_for_symtable= case "$compile_command " in *" -static "*) ;; *) case $host in # compiling the symbol table file with pic_flag works around # a FreeBSD bug that causes programs to crash when -lm is # linked before any other PIC object. But we must not use # pic_flag when linking with -static. The problem exists in # FreeBSD 2.2.6 and is fixed in FreeBSD 3.1. *-*-freebsd2.*|*-*-freebsd3.0*|*-*-freebsdelf3.0*) pic_flag_for_symtable=" $pic_flag -DFREEBSD_WORKAROUND" ;; *-*-hpux*) pic_flag_for_symtable=" $pic_flag" ;; *) if test "X$my_pic_p" != Xno; then pic_flag_for_symtable=" $pic_flag" fi ;; esac ;; esac symtab_cflags= for arg in $LTCFLAGS; do case $arg in -pie | -fpie | -fPIE) ;; *) func_append symtab_cflags " $arg" ;; esac done # Now compile the dynamic symbol file. func_show_eval '(cd $output_objdir && $LTCC$symtab_cflags -c$no_builtin_flag$pic_flag_for_symtable "$my_dlsyms")' 'exit $?' # Clean up the generated files. func_show_eval '$RM "$output_objdir/$my_dlsyms" "$nlist" "${nlist}S" "${nlist}T"' # Transform the symbol file into the correct name. symfileobj="$output_objdir/${my_outputname}S.$objext" case $host in *cygwin* | *mingw* | *cegcc* ) if test -f "$output_objdir/$my_outputname.def"; then compile_command=`$ECHO "$compile_command" | $SED "s%@SYMFILE@%$output_objdir/$my_outputname.def $symfileobj%"` finalize_command=`$ECHO "$finalize_command" | $SED "s%@SYMFILE@%$output_objdir/$my_outputname.def $symfileobj%"` else compile_command=`$ECHO "$compile_command" | $SED "s%@SYMFILE@%$symfileobj%"` finalize_command=`$ECHO "$finalize_command" | $SED "s%@SYMFILE@%$symfileobj%"` fi ;; *) compile_command=`$ECHO "$compile_command" | $SED "s%@SYMFILE@%$symfileobj%"` finalize_command=`$ECHO "$finalize_command" | $SED "s%@SYMFILE@%$symfileobj%"` ;; esac ;; *) func_fatal_error "unknown suffix for \`$my_dlsyms'" ;; esac else # We keep going just in case the user didn't refer to # lt_preloaded_symbols. The linker will fail if global_symbol_pipe # really was required. # Nullify the symbol file. compile_command=`$ECHO "$compile_command" | $SED "s% @SYMFILE@%%"` finalize_command=`$ECHO "$finalize_command" | $SED "s% @SYMFILE@%%"` fi } # func_win32_libid arg # return the library type of file 'arg' # # Need a lot of goo to handle *both* DLLs and import libs # Has to be a shell function in order to 'eat' the argument # that is supplied when $file_magic_command is called. # Despite the name, also deal with 64 bit binaries. func_win32_libid () { $opt_debug win32_libid_type="unknown" win32_fileres=`file -L $1 2>/dev/null` case $win32_fileres in *ar\ archive\ import\ library*) # definitely import win32_libid_type="x86 archive import" ;; *ar\ archive*) # could be an import, or static # Keep the egrep pattern in sync with the one in _LT_CHECK_MAGIC_METHOD. if eval $OBJDUMP -f $1 | $SED -e '10q' 2>/dev/null | $EGREP 'file format (pei*-i386(.*architecture: i386)?|pe-arm-wince|pe-x86-64)' >/dev/null; then func_to_tool_file "$1" func_convert_file_msys_to_w32 win32_nmres=`eval $NM -f posix -A \"$func_to_tool_file_result\" | $SED -n -e ' 1,100{ / I /{ s,.*,import, p q } }'` case $win32_nmres in import*) win32_libid_type="x86 archive import";; *) win32_libid_type="x86 archive static";; esac fi ;; *DLL*) win32_libid_type="x86 DLL" ;; *executable*) # but shell scripts are "executable" too... case $win32_fileres in *MS\ Windows\ PE\ Intel*) win32_libid_type="x86 DLL" ;; esac ;; esac $ECHO "$win32_libid_type" } # func_cygming_dll_for_implib ARG # # Platform-specific function to extract the # name of the DLL associated with the specified # import library ARG. # Invoked by eval'ing the libtool variable # $sharedlib_from_linklib_cmd # Result is available in the variable # $sharedlib_from_linklib_result func_cygming_dll_for_implib () { $opt_debug sharedlib_from_linklib_result=`$DLLTOOL --identify-strict --identify "$1"` } # func_cygming_dll_for_implib_fallback_core SECTION_NAME LIBNAMEs # # The is the core of a fallback implementation of a # platform-specific function to extract the name of the # DLL associated with the specified import library LIBNAME. # # SECTION_NAME is either .idata$6 or .idata$7, depending # on the platform and compiler that created the implib. # # Echos the name of the DLL associated with the # specified import library. func_cygming_dll_for_implib_fallback_core () { $opt_debug match_literal=`$ECHO "$1" | $SED "$sed_make_literal_regex"` $OBJDUMP -s --section "$1" "$2" 2>/dev/null | $SED '/^Contents of section '"$match_literal"':/{ # Place marker at beginning of archive member dllname section s/.*/====MARK====/ p d } # These lines can sometimes be longer than 43 characters, but # are always uninteresting /:[ ]*file format pe[i]\{,1\}-/d /^In archive [^:]*:/d # Ensure marker is printed /^====MARK====/p # Remove all lines with less than 43 characters /^.\{43\}/!d # From remaining lines, remove first 43 characters s/^.\{43\}//' | $SED -n ' # Join marker and all lines until next marker into a single line /^====MARK====/ b para H $ b para b :para x s/\n//g # Remove the marker s/^====MARK====// # Remove trailing dots and whitespace s/[\. \t]*$// # Print /./p' | # we now have a list, one entry per line, of the stringified # contents of the appropriate section of all members of the # archive which possess that section. Heuristic: eliminate # all those which have a first or second character that is # a '.' (that is, objdump's representation of an unprintable # character.) This should work for all archives with less than # 0x302f exports -- but will fail for DLLs whose name actually # begins with a literal '.' or a single character followed by # a '.'. # # Of those that remain, print the first one. $SED -e '/^\./d;/^.\./d;q' } # func_cygming_gnu_implib_p ARG # This predicate returns with zero status (TRUE) if # ARG is a GNU/binutils-style import library. Returns # with nonzero status (FALSE) otherwise. func_cygming_gnu_implib_p () { $opt_debug func_to_tool_file "$1" func_convert_file_msys_to_w32 func_cygming_gnu_implib_tmp=`$NM "$func_to_tool_file_result" | eval "$global_symbol_pipe" | $EGREP ' (_head_[A-Za-z0-9_]+_[ad]l*|[A-Za-z0-9_]+_[ad]l*_iname)$'` test -n "$func_cygming_gnu_implib_tmp" } # func_cygming_ms_implib_p ARG # This predicate returns with zero status (TRUE) if # ARG is an MS-style import library. Returns # with nonzero status (FALSE) otherwise. func_cygming_ms_implib_p () { $opt_debug func_to_tool_file "$1" func_convert_file_msys_to_w32 func_cygming_ms_implib_tmp=`$NM "$func_to_tool_file_result" | eval "$global_symbol_pipe" | $GREP '_NULL_IMPORT_DESCRIPTOR'` test -n "$func_cygming_ms_implib_tmp" } # func_cygming_dll_for_implib_fallback ARG # Platform-specific function to extract the # name of the DLL associated with the specified # import library ARG. # # This fallback implementation is for use when $DLLTOOL # does not support the --identify-strict option. # Invoked by eval'ing the libtool variable # $sharedlib_from_linklib_cmd # Result is available in the variable # $sharedlib_from_linklib_result func_cygming_dll_for_implib_fallback () { $opt_debug if func_cygming_gnu_implib_p "$1" ; then # binutils import library sharedlib_from_linklib_result=`func_cygming_dll_for_implib_fallback_core '.idata$7' "$1"` elif func_cygming_ms_implib_p "$1" ; then # ms-generated import library sharedlib_from_linklib_result=`func_cygming_dll_for_implib_fallback_core '.idata$6' "$1"` else # unknown sharedlib_from_linklib_result="" fi } # func_extract_an_archive dir oldlib func_extract_an_archive () { $opt_debug f_ex_an_ar_dir="$1"; shift f_ex_an_ar_oldlib="$1" if test "$lock_old_archive_extraction" = yes; then lockfile=$f_ex_an_ar_oldlib.lock until $opt_dry_run || ln "$progpath" "$lockfile" 2>/dev/null; do func_echo "Waiting for $lockfile to be removed" sleep 2 done fi func_show_eval "(cd \$f_ex_an_ar_dir && $AR x \"\$f_ex_an_ar_oldlib\")" \ 'stat=$?; rm -f "$lockfile"; exit $stat' if test "$lock_old_archive_extraction" = yes; then $opt_dry_run || rm -f "$lockfile" fi if ($AR t "$f_ex_an_ar_oldlib" | sort | sort -uc >/dev/null 2>&1); then : else func_fatal_error "object name conflicts in archive: $f_ex_an_ar_dir/$f_ex_an_ar_oldlib" fi } # func_extract_archives gentop oldlib ... func_extract_archives () { $opt_debug my_gentop="$1"; shift my_oldlibs=${1+"$@"} my_oldobjs="" my_xlib="" my_xabs="" my_xdir="" for my_xlib in $my_oldlibs; do # Extract the objects. case $my_xlib in [\\/]* | [A-Za-z]:[\\/]*) my_xabs="$my_xlib" ;; *) my_xabs=`pwd`"/$my_xlib" ;; esac func_basename "$my_xlib" my_xlib="$func_basename_result" my_xlib_u=$my_xlib while :; do case " $extracted_archives " in *" $my_xlib_u "*) func_arith $extracted_serial + 1 extracted_serial=$func_arith_result my_xlib_u=lt$extracted_serial-$my_xlib ;; *) break ;; esac done extracted_archives="$extracted_archives $my_xlib_u" my_xdir="$my_gentop/$my_xlib_u" func_mkdir_p "$my_xdir" case $host in *-darwin*) func_verbose "Extracting $my_xabs" # Do not bother doing anything if just a dry run $opt_dry_run || { darwin_orig_dir=`pwd` cd $my_xdir || exit $? darwin_archive=$my_xabs darwin_curdir=`pwd` darwin_base_archive=`basename "$darwin_archive"` darwin_arches=`$LIPO -info "$darwin_archive" 2>/dev/null | $GREP Architectures 2>/dev/null || true` if test -n "$darwin_arches"; then darwin_arches=`$ECHO "$darwin_arches" | $SED -e 's/.*are://'` darwin_arch= func_verbose "$darwin_base_archive has multiple architectures $darwin_arches" for darwin_arch in $darwin_arches ; do func_mkdir_p "unfat-$$/${darwin_base_archive}-${darwin_arch}" $LIPO -thin $darwin_arch -output "unfat-$$/${darwin_base_archive}-${darwin_arch}/${darwin_base_archive}" "${darwin_archive}" cd "unfat-$$/${darwin_base_archive}-${darwin_arch}" func_extract_an_archive "`pwd`" "${darwin_base_archive}" cd "$darwin_curdir" $RM "unfat-$$/${darwin_base_archive}-${darwin_arch}/${darwin_base_archive}" done # $darwin_arches ## Okay now we've a bunch of thin objects, gotta fatten them up :) darwin_filelist=`find unfat-$$ -type f -name \*.o -print -o -name \*.lo -print | $SED -e "$basename" | sort -u` darwin_file= darwin_files= for darwin_file in $darwin_filelist; do darwin_files=`find unfat-$$ -name $darwin_file -print | sort | $NL2SP` $LIPO -create -output "$darwin_file" $darwin_files done # $darwin_filelist $RM -rf unfat-$$ cd "$darwin_orig_dir" else cd $darwin_orig_dir func_extract_an_archive "$my_xdir" "$my_xabs" fi # $darwin_arches } # !$opt_dry_run ;; *) func_extract_an_archive "$my_xdir" "$my_xabs" ;; esac my_oldobjs="$my_oldobjs "`find $my_xdir -name \*.$objext -print -o -name \*.lo -print | sort | $NL2SP` done func_extract_archives_result="$my_oldobjs" } # func_emit_wrapper [arg=no] # # Emit a libtool wrapper script on stdout. # Don't directly open a file because we may want to # incorporate the script contents within a cygwin/mingw # wrapper executable. Must ONLY be called from within # func_mode_link because it depends on a number of variables # set therein. # # ARG is the value that the WRAPPER_SCRIPT_BELONGS_IN_OBJDIR # variable will take. If 'yes', then the emitted script # will assume that the directory in which it is stored is # the $objdir directory. This is a cygwin/mingw-specific # behavior. func_emit_wrapper () { func_emit_wrapper_arg1=${1-no} $ECHO "\ #! $SHELL # $output - temporary wrapper script for $objdir/$outputname # Generated by $PROGRAM (GNU $PACKAGE$TIMESTAMP) $VERSION # # The $output program cannot be directly executed until all the libtool # libraries that it depends on are installed. # # This wrapper script should never be moved out of the build directory. # If it is, it will not operate correctly. # Sed substitution that helps us do robust quoting. It backslashifies # metacharacters that are still active within double-quoted strings. sed_quote_subst='$sed_quote_subst' # Be Bourne compatible if test -n \"\${ZSH_VERSION+set}\" && (emulate sh) >/dev/null 2>&1; then emulate sh NULLCMD=: # Zsh 3.x and 4.x performs word splitting on \${1+\"\$@\"}, which # is contrary to our usage. Disable this feature. alias -g '\${1+\"\$@\"}'='\"\$@\"' setopt NO_GLOB_SUBST else case \`(set -o) 2>/dev/null\` in *posix*) set -o posix;; esac fi BIN_SH=xpg4; export BIN_SH # for Tru64 DUALCASE=1; export DUALCASE # for MKS sh # The HP-UX ksh and POSIX shell print the target directory to stdout # if CDPATH is set. (unset CDPATH) >/dev/null 2>&1 && unset CDPATH relink_command=\"$relink_command\" # This environment variable determines our operation mode. if test \"\$libtool_install_magic\" = \"$magic\"; then # install mode needs the following variables: generated_by_libtool_version='$macro_version' notinst_deplibs='$notinst_deplibs' else # When we are sourced in execute mode, \$file and \$ECHO are already set. if test \"\$libtool_execute_magic\" != \"$magic\"; then file=\"\$0\"" qECHO=`$ECHO "$ECHO" | $SED "$sed_quote_subst"` $ECHO "\ # A function that is used when there is no print builtin or printf. func_fallback_echo () { eval 'cat <<_LTECHO_EOF \$1 _LTECHO_EOF' } ECHO=\"$qECHO\" fi # Very basic option parsing. These options are (a) specific to # the libtool wrapper, (b) are identical between the wrapper # /script/ and the wrapper /executable/ which is used only on # windows platforms, and (c) all begin with the string "--lt-" # (application programs are unlikely to have options which match # this pattern). # # There are only two supported options: --lt-debug and # --lt-dump-script. There is, deliberately, no --lt-help. # # The first argument to this parsing function should be the # script's $0 value, followed by "$@". lt_option_debug= func_parse_lt_options () { lt_script_arg0=\$0 shift for lt_opt do case \"\$lt_opt\" in --lt-debug) lt_option_debug=1 ;; --lt-dump-script) lt_dump_D=\`\$ECHO \"X\$lt_script_arg0\" | $SED -e 's/^X//' -e 's%/[^/]*$%%'\` test \"X\$lt_dump_D\" = \"X\$lt_script_arg0\" && lt_dump_D=. lt_dump_F=\`\$ECHO \"X\$lt_script_arg0\" | $SED -e 's/^X//' -e 's%^.*/%%'\` cat \"\$lt_dump_D/\$lt_dump_F\" exit 0 ;; --lt-*) \$ECHO \"Unrecognized --lt- option: '\$lt_opt'\" 1>&2 exit 1 ;; esac done # Print the debug banner immediately: if test -n \"\$lt_option_debug\"; then echo \"${outputname}:${output}:\${LINENO}: libtool wrapper (GNU $PACKAGE$TIMESTAMP) $VERSION\" 1>&2 fi } # Used when --lt-debug. Prints its arguments to stdout # (redirection is the responsibility of the caller) func_lt_dump_args () { lt_dump_args_N=1; for lt_arg do \$ECHO \"${outputname}:${output}:\${LINENO}: newargv[\$lt_dump_args_N]: \$lt_arg\" lt_dump_args_N=\`expr \$lt_dump_args_N + 1\` done } # Core function for launching the target application func_exec_program_core () { " case $host in # Backslashes separate directories on plain windows *-*-mingw | *-*-os2* | *-cegcc*) $ECHO "\ if test -n \"\$lt_option_debug\"; then \$ECHO \"${outputname}:${output}:\${LINENO}: newargv[0]: \$progdir\\\\\$program\" 1>&2 func_lt_dump_args \${1+\"\$@\"} 1>&2 fi exec \"\$progdir\\\\\$program\" \${1+\"\$@\"} " ;; *) $ECHO "\ if test -n \"\$lt_option_debug\"; then \$ECHO \"${outputname}:${output}:\${LINENO}: newargv[0]: \$progdir/\$program\" 1>&2 func_lt_dump_args \${1+\"\$@\"} 1>&2 fi exec \"\$progdir/\$program\" \${1+\"\$@\"} " ;; esac $ECHO "\ \$ECHO \"\$0: cannot exec \$program \$*\" 1>&2 exit 1 } # A function to encapsulate launching the target application # Strips options in the --lt-* namespace from \$@ and # launches target application with the remaining arguments. func_exec_program () { case \" \$* \" in *\\ --lt-*) for lt_wr_arg do case \$lt_wr_arg in --lt-*) ;; *) set x \"\$@\" \"\$lt_wr_arg\"; shift;; esac shift done ;; esac func_exec_program_core \${1+\"\$@\"} } # Parse options func_parse_lt_options \"\$0\" \${1+\"\$@\"} # Find the directory that this script lives in. thisdir=\`\$ECHO \"\$file\" | $SED 's%/[^/]*$%%'\` test \"x\$thisdir\" = \"x\$file\" && thisdir=. # Follow symbolic links until we get to the real thisdir. file=\`ls -ld \"\$file\" | $SED -n 's/.*-> //p'\` while test -n \"\$file\"; do destdir=\`\$ECHO \"\$file\" | $SED 's%/[^/]*\$%%'\` # If there was a directory component, then change thisdir. if test \"x\$destdir\" != \"x\$file\"; then case \"\$destdir\" in [\\\\/]* | [A-Za-z]:[\\\\/]*) thisdir=\"\$destdir\" ;; *) thisdir=\"\$thisdir/\$destdir\" ;; esac fi file=\`\$ECHO \"\$file\" | $SED 's%^.*/%%'\` file=\`ls -ld \"\$thisdir/\$file\" | $SED -n 's/.*-> //p'\` done # Usually 'no', except on cygwin/mingw when embedded into # the cwrapper. WRAPPER_SCRIPT_BELONGS_IN_OBJDIR=$func_emit_wrapper_arg1 if test \"\$WRAPPER_SCRIPT_BELONGS_IN_OBJDIR\" = \"yes\"; then # special case for '.' if test \"\$thisdir\" = \".\"; then thisdir=\`pwd\` fi # remove .libs from thisdir case \"\$thisdir\" in *[\\\\/]$objdir ) thisdir=\`\$ECHO \"\$thisdir\" | $SED 's%[\\\\/][^\\\\/]*$%%'\` ;; $objdir ) thisdir=. ;; esac fi # Try to get the absolute directory name. absdir=\`cd \"\$thisdir\" && pwd\` test -n \"\$absdir\" && thisdir=\"\$absdir\" " if test "$fast_install" = yes; then $ECHO "\ program=lt-'$outputname'$exeext progdir=\"\$thisdir/$objdir\" if test ! -f \"\$progdir/\$program\" || { file=\`ls -1dt \"\$progdir/\$program\" \"\$progdir/../\$program\" 2>/dev/null | ${SED} 1q\`; \\ test \"X\$file\" != \"X\$progdir/\$program\"; }; then file=\"\$\$-\$program\" if test ! -d \"\$progdir\"; then $MKDIR \"\$progdir\" else $RM \"\$progdir/\$file\" fi" $ECHO "\ # relink executable if necessary if test -n \"\$relink_command\"; then if relink_command_output=\`eval \$relink_command 2>&1\`; then : else $ECHO \"\$relink_command_output\" >&2 $RM \"\$progdir/\$file\" exit 1 fi fi $MV \"\$progdir/\$file\" \"\$progdir/\$program\" 2>/dev/null || { $RM \"\$progdir/\$program\"; $MV \"\$progdir/\$file\" \"\$progdir/\$program\"; } $RM \"\$progdir/\$file\" fi" else $ECHO "\ program='$outputname' progdir=\"\$thisdir/$objdir\" " fi $ECHO "\ if test -f \"\$progdir/\$program\"; then" # fixup the dll searchpath if we need to. # # Fix the DLL searchpath if we need to. Do this before prepending # to shlibpath, because on Windows, both are PATH and uninstalled # libraries must come first. if test -n "$dllsearchpath"; then $ECHO "\ # Add the dll search path components to the executable PATH PATH=$dllsearchpath:\$PATH " fi # Export our shlibpath_var if we have one. if test "$shlibpath_overrides_runpath" = yes && test -n "$shlibpath_var" && test -n "$temp_rpath"; then $ECHO "\ # Add our own library path to $shlibpath_var $shlibpath_var=\"$temp_rpath\$$shlibpath_var\" # Some systems cannot cope with colon-terminated $shlibpath_var # The second colon is a workaround for a bug in BeOS R4 sed $shlibpath_var=\`\$ECHO \"\$$shlibpath_var\" | $SED 's/::*\$//'\` export $shlibpath_var " fi $ECHO "\ if test \"\$libtool_execute_magic\" != \"$magic\"; then # Run the actual program with our arguments. func_exec_program \${1+\"\$@\"} fi else # The program doesn't exist. \$ECHO \"\$0: error: \\\`\$progdir/\$program' does not exist\" 1>&2 \$ECHO \"This script is just a wrapper for \$program.\" 1>&2 \$ECHO \"See the $PACKAGE documentation for more information.\" 1>&2 exit 1 fi fi\ " } # func_emit_cwrapperexe_src # emit the source code for a wrapper executable on stdout # Must ONLY be called from within func_mode_link because # it depends on a number of variable set therein. func_emit_cwrapperexe_src () { cat < #include #ifdef _MSC_VER # include # include # include #else # include # include # ifdef __CYGWIN__ # include # endif #endif #include #include #include #include #include #include #include #include /* declarations of non-ANSI functions */ #if defined(__MINGW32__) # ifdef __STRICT_ANSI__ int _putenv (const char *); # endif #elif defined(__CYGWIN__) # ifdef __STRICT_ANSI__ char *realpath (const char *, char *); int putenv (char *); int setenv (const char *, const char *, int); # endif /* #elif defined (other platforms) ... */ #endif /* portability defines, excluding path handling macros */ #if defined(_MSC_VER) # define setmode _setmode # define stat _stat # define chmod _chmod # define getcwd _getcwd # define putenv _putenv # define S_IXUSR _S_IEXEC # ifndef _INTPTR_T_DEFINED # define _INTPTR_T_DEFINED # define intptr_t int # endif #elif defined(__MINGW32__) # define setmode _setmode # define stat _stat # define chmod _chmod # define getcwd _getcwd # define putenv _putenv #elif defined(__CYGWIN__) # define HAVE_SETENV # define FOPEN_WB "wb" /* #elif defined (other platforms) ... */ #endif #if defined(PATH_MAX) # define LT_PATHMAX PATH_MAX #elif defined(MAXPATHLEN) # define LT_PATHMAX MAXPATHLEN #else # define LT_PATHMAX 1024 #endif #ifndef S_IXOTH # define S_IXOTH 0 #endif #ifndef S_IXGRP # define S_IXGRP 0 #endif /* path handling portability macros */ #ifndef DIR_SEPARATOR # define DIR_SEPARATOR '/' # define PATH_SEPARATOR ':' #endif #if defined (_WIN32) || defined (__MSDOS__) || defined (__DJGPP__) || \ defined (__OS2__) # define HAVE_DOS_BASED_FILE_SYSTEM # define FOPEN_WB "wb" # ifndef DIR_SEPARATOR_2 # define DIR_SEPARATOR_2 '\\' # endif # ifndef PATH_SEPARATOR_2 # define PATH_SEPARATOR_2 ';' # endif #endif #ifndef DIR_SEPARATOR_2 # define IS_DIR_SEPARATOR(ch) ((ch) == DIR_SEPARATOR) #else /* DIR_SEPARATOR_2 */ # define IS_DIR_SEPARATOR(ch) \ (((ch) == DIR_SEPARATOR) || ((ch) == DIR_SEPARATOR_2)) #endif /* DIR_SEPARATOR_2 */ #ifndef PATH_SEPARATOR_2 # define IS_PATH_SEPARATOR(ch) ((ch) == PATH_SEPARATOR) #else /* PATH_SEPARATOR_2 */ # define IS_PATH_SEPARATOR(ch) ((ch) == PATH_SEPARATOR_2) #endif /* PATH_SEPARATOR_2 */ #ifndef FOPEN_WB # define FOPEN_WB "w" #endif #ifndef _O_BINARY # define _O_BINARY 0 #endif #define XMALLOC(type, num) ((type *) xmalloc ((num) * sizeof(type))) #define XFREE(stale) do { \ if (stale) { free ((void *) stale); stale = 0; } \ } while (0) #if defined(LT_DEBUGWRAPPER) static int lt_debug = 1; #else static int lt_debug = 0; #endif const char *program_name = "libtool-wrapper"; /* in case xstrdup fails */ void *xmalloc (size_t num); char *xstrdup (const char *string); const char *base_name (const char *name); char *find_executable (const char *wrapper); char *chase_symlinks (const char *pathspec); int make_executable (const char *path); int check_executable (const char *path); char *strendzap (char *str, const char *pat); void lt_debugprintf (const char *file, int line, const char *fmt, ...); void lt_fatal (const char *file, int line, const char *message, ...); static const char *nonnull (const char *s); static const char *nonempty (const char *s); void lt_setenv (const char *name, const char *value); char *lt_extend_str (const char *orig_value, const char *add, int to_end); void lt_update_exe_path (const char *name, const char *value); void lt_update_lib_path (const char *name, const char *value); char **prepare_spawn (char **argv); void lt_dump_script (FILE *f); EOF cat <= 0) && (st.st_mode & (S_IXUSR | S_IXGRP | S_IXOTH))) return 1; else return 0; } int make_executable (const char *path) { int rval = 0; struct stat st; lt_debugprintf (__FILE__, __LINE__, "(make_executable): %s\n", nonempty (path)); if ((!path) || (!*path)) return 0; if (stat (path, &st) >= 0) { rval = chmod (path, st.st_mode | S_IXOTH | S_IXGRP | S_IXUSR); } return rval; } /* Searches for the full path of the wrapper. Returns newly allocated full path name if found, NULL otherwise Does not chase symlinks, even on platforms that support them. */ char * find_executable (const char *wrapper) { int has_slash = 0; const char *p; const char *p_next; /* static buffer for getcwd */ char tmp[LT_PATHMAX + 1]; int tmp_len; char *concat_name; lt_debugprintf (__FILE__, __LINE__, "(find_executable): %s\n", nonempty (wrapper)); if ((wrapper == NULL) || (*wrapper == '\0')) return NULL; /* Absolute path? */ #if defined (HAVE_DOS_BASED_FILE_SYSTEM) if (isalpha ((unsigned char) wrapper[0]) && wrapper[1] == ':') { concat_name = xstrdup (wrapper); if (check_executable (concat_name)) return concat_name; XFREE (concat_name); } else { #endif if (IS_DIR_SEPARATOR (wrapper[0])) { concat_name = xstrdup (wrapper); if (check_executable (concat_name)) return concat_name; XFREE (concat_name); } #if defined (HAVE_DOS_BASED_FILE_SYSTEM) } #endif for (p = wrapper; *p; p++) if (*p == '/') { has_slash = 1; break; } if (!has_slash) { /* no slashes; search PATH */ const char *path = getenv ("PATH"); if (path != NULL) { for (p = path; *p; p = p_next) { const char *q; size_t p_len; for (q = p; *q; q++) if (IS_PATH_SEPARATOR (*q)) break; p_len = q - p; p_next = (*q == '\0' ? q : q + 1); if (p_len == 0) { /* empty path: current directory */ if (getcwd (tmp, LT_PATHMAX) == NULL) lt_fatal (__FILE__, __LINE__, "getcwd failed: %s", nonnull (strerror (errno))); tmp_len = strlen (tmp); concat_name = XMALLOC (char, tmp_len + 1 + strlen (wrapper) + 1); memcpy (concat_name, tmp, tmp_len); concat_name[tmp_len] = '/'; strcpy (concat_name + tmp_len + 1, wrapper); } else { concat_name = XMALLOC (char, p_len + 1 + strlen (wrapper) + 1); memcpy (concat_name, p, p_len); concat_name[p_len] = '/'; strcpy (concat_name + p_len + 1, wrapper); } if (check_executable (concat_name)) return concat_name; XFREE (concat_name); } } /* not found in PATH; assume curdir */ } /* Relative path | not found in path: prepend cwd */ if (getcwd (tmp, LT_PATHMAX) == NULL) lt_fatal (__FILE__, __LINE__, "getcwd failed: %s", nonnull (strerror (errno))); tmp_len = strlen (tmp); concat_name = XMALLOC (char, tmp_len + 1 + strlen (wrapper) + 1); memcpy (concat_name, tmp, tmp_len); concat_name[tmp_len] = '/'; strcpy (concat_name + tmp_len + 1, wrapper); if (check_executable (concat_name)) return concat_name; XFREE (concat_name); return NULL; } char * chase_symlinks (const char *pathspec) { #ifndef S_ISLNK return xstrdup (pathspec); #else char buf[LT_PATHMAX]; struct stat s; char *tmp_pathspec = xstrdup (pathspec); char *p; int has_symlinks = 0; while (strlen (tmp_pathspec) && !has_symlinks) { lt_debugprintf (__FILE__, __LINE__, "checking path component for symlinks: %s\n", tmp_pathspec); if (lstat (tmp_pathspec, &s) == 0) { if (S_ISLNK (s.st_mode) != 0) { has_symlinks = 1; break; } /* search backwards for last DIR_SEPARATOR */ p = tmp_pathspec + strlen (tmp_pathspec) - 1; while ((p > tmp_pathspec) && (!IS_DIR_SEPARATOR (*p))) p--; if ((p == tmp_pathspec) && (!IS_DIR_SEPARATOR (*p))) { /* no more DIR_SEPARATORS left */ break; } *p = '\0'; } else { lt_fatal (__FILE__, __LINE__, "error accessing file \"%s\": %s", tmp_pathspec, nonnull (strerror (errno))); } } XFREE (tmp_pathspec); if (!has_symlinks) { return xstrdup (pathspec); } tmp_pathspec = realpath (pathspec, buf); if (tmp_pathspec == 0) { lt_fatal (__FILE__, __LINE__, "could not follow symlinks for %s", pathspec); } return xstrdup (tmp_pathspec); #endif } char * strendzap (char *str, const char *pat) { size_t len, patlen; assert (str != NULL); assert (pat != NULL); len = strlen (str); patlen = strlen (pat); if (patlen <= len) { str += len - patlen; if (strcmp (str, pat) == 0) *str = '\0'; } return str; } void lt_debugprintf (const char *file, int line, const char *fmt, ...) { va_list args; if (lt_debug) { (void) fprintf (stderr, "%s:%s:%d: ", program_name, file, line); va_start (args, fmt); (void) vfprintf (stderr, fmt, args); va_end (args); } } static void lt_error_core (int exit_status, const char *file, int line, const char *mode, const char *message, va_list ap) { fprintf (stderr, "%s:%s:%d: %s: ", program_name, file, line, mode); vfprintf (stderr, message, ap); fprintf (stderr, ".\n"); if (exit_status >= 0) exit (exit_status); } void lt_fatal (const char *file, int line, const char *message, ...) { va_list ap; va_start (ap, message); lt_error_core (EXIT_FAILURE, file, line, "FATAL", message, ap); va_end (ap); } static const char * nonnull (const char *s) { return s ? s : "(null)"; } static const char * nonempty (const char *s) { return (s && !*s) ? "(empty)" : nonnull (s); } void lt_setenv (const char *name, const char *value) { lt_debugprintf (__FILE__, __LINE__, "(lt_setenv) setting '%s' to '%s'\n", nonnull (name), nonnull (value)); { #ifdef HAVE_SETENV /* always make a copy, for consistency with !HAVE_SETENV */ char *str = xstrdup (value); setenv (name, str, 1); #else int len = strlen (name) + 1 + strlen (value) + 1; char *str = XMALLOC (char, len); sprintf (str, "%s=%s", name, value); if (putenv (str) != EXIT_SUCCESS) { XFREE (str); } #endif } } char * lt_extend_str (const char *orig_value, const char *add, int to_end) { char *new_value; if (orig_value && *orig_value) { int orig_value_len = strlen (orig_value); int add_len = strlen (add); new_value = XMALLOC (char, add_len + orig_value_len + 1); if (to_end) { strcpy (new_value, orig_value); strcpy (new_value + orig_value_len, add); } else { strcpy (new_value, add); strcpy (new_value + add_len, orig_value); } } else { new_value = xstrdup (add); } return new_value; } void lt_update_exe_path (const char *name, const char *value) { lt_debugprintf (__FILE__, __LINE__, "(lt_update_exe_path) modifying '%s' by prepending '%s'\n", nonnull (name), nonnull (value)); if (name && *name && value && *value) { char *new_value = lt_extend_str (getenv (name), value, 0); /* some systems can't cope with a ':'-terminated path #' */ int len = strlen (new_value); while (((len = strlen (new_value)) > 0) && IS_PATH_SEPARATOR (new_value[len-1])) { new_value[len-1] = '\0'; } lt_setenv (name, new_value); XFREE (new_value); } } void lt_update_lib_path (const char *name, const char *value) { lt_debugprintf (__FILE__, __LINE__, "(lt_update_lib_path) modifying '%s' by prepending '%s'\n", nonnull (name), nonnull (value)); if (name && *name && value && *value) { char *new_value = lt_extend_str (getenv (name), value, 0); lt_setenv (name, new_value); XFREE (new_value); } } EOF case $host_os in mingw*) cat <<"EOF" /* Prepares an argument vector before calling spawn(). Note that spawn() does not by itself call the command interpreter (getenv ("COMSPEC") != NULL ? getenv ("COMSPEC") : ({ OSVERSIONINFO v; v.dwOSVersionInfoSize = sizeof(OSVERSIONINFO); GetVersionEx(&v); v.dwPlatformId == VER_PLATFORM_WIN32_NT; }) ? "cmd.exe" : "command.com"). Instead it simply concatenates the arguments, separated by ' ', and calls CreateProcess(). We must quote the arguments since Win32 CreateProcess() interprets characters like ' ', '\t', '\\', '"' (but not '<' and '>') in a special way: - Space and tab are interpreted as delimiters. They are not treated as delimiters if they are surrounded by double quotes: "...". - Unescaped double quotes are removed from the input. Their only effect is that within double quotes, space and tab are treated like normal characters. - Backslashes not followed by double quotes are not special. - But 2*n+1 backslashes followed by a double quote become n backslashes followed by a double quote (n >= 0): \" -> " \\\" -> \" \\\\\" -> \\" */ #define SHELL_SPECIAL_CHARS "\"\\ \001\002\003\004\005\006\007\010\011\012\013\014\015\016\017\020\021\022\023\024\025\026\027\030\031\032\033\034\035\036\037" #define SHELL_SPACE_CHARS " \001\002\003\004\005\006\007\010\011\012\013\014\015\016\017\020\021\022\023\024\025\026\027\030\031\032\033\034\035\036\037" char ** prepare_spawn (char **argv) { size_t argc; char **new_argv; size_t i; /* Count number of arguments. */ for (argc = 0; argv[argc] != NULL; argc++) ; /* Allocate new argument vector. */ new_argv = XMALLOC (char *, argc + 1); /* Put quoted arguments into the new argument vector. */ for (i = 0; i < argc; i++) { const char *string = argv[i]; if (string[0] == '\0') new_argv[i] = xstrdup ("\"\""); else if (strpbrk (string, SHELL_SPECIAL_CHARS) != NULL) { int quote_around = (strpbrk (string, SHELL_SPACE_CHARS) != NULL); size_t length; unsigned int backslashes; const char *s; char *quoted_string; char *p; length = 0; backslashes = 0; if (quote_around) length++; for (s = string; *s != '\0'; s++) { char c = *s; if (c == '"') length += backslashes + 1; length++; if (c == '\\') backslashes++; else backslashes = 0; } if (quote_around) length += backslashes + 1; quoted_string = XMALLOC (char, length + 1); p = quoted_string; backslashes = 0; if (quote_around) *p++ = '"'; for (s = string; *s != '\0'; s++) { char c = *s; if (c == '"') { unsigned int j; for (j = backslashes + 1; j > 0; j--) *p++ = '\\'; } *p++ = c; if (c == '\\') backslashes++; else backslashes = 0; } if (quote_around) { unsigned int j; for (j = backslashes; j > 0; j--) *p++ = '\\'; *p++ = '"'; } *p = '\0'; new_argv[i] = quoted_string; } else new_argv[i] = (char *) string; } new_argv[argc] = NULL; return new_argv; } EOF ;; esac cat <<"EOF" void lt_dump_script (FILE* f) { EOF func_emit_wrapper yes | $SED -n -e ' s/^\(.\{79\}\)\(..*\)/\1\ \2/ h s/\([\\"]\)/\\\1/g s/$/\\n/ s/\([^\n]*\).*/ fputs ("\1", f);/p g D' cat <<"EOF" } EOF } # end: func_emit_cwrapperexe_src # func_win32_import_lib_p ARG # True if ARG is an import lib, as indicated by $file_magic_cmd func_win32_import_lib_p () { $opt_debug case `eval $file_magic_cmd \"\$1\" 2>/dev/null | $SED -e 10q` in *import*) : ;; *) false ;; esac } # func_mode_link arg... func_mode_link () { $opt_debug case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2* | *-cegcc*) # It is impossible to link a dll without this setting, and # we shouldn't force the makefile maintainer to figure out # which system we are compiling for in order to pass an extra # flag for every libtool invocation. # allow_undefined=no # FIXME: Unfortunately, there are problems with the above when trying # to make a dll which has undefined symbols, in which case not # even a static library is built. For now, we need to specify # -no-undefined on the libtool link line when we can be certain # that all symbols are satisfied, otherwise we get a static library. allow_undefined=yes ;; *) allow_undefined=yes ;; esac libtool_args=$nonopt base_compile="$nonopt $@" compile_command=$nonopt finalize_command=$nonopt compile_rpath= finalize_rpath= compile_shlibpath= finalize_shlibpath= convenience= old_convenience= deplibs= old_deplibs= compiler_flags= linker_flags= dllsearchpath= lib_search_path=`pwd` inst_prefix_dir= new_inherited_linker_flags= avoid_version=no bindir= dlfiles= dlprefiles= dlself=no export_dynamic=no export_symbols= export_symbols_regex= generated= libobjs= ltlibs= module=no no_install=no objs= non_pic_objects= precious_files_regex= prefer_static_libs=no preload=no prev= prevarg= release= rpath= xrpath= perm_rpath= temp_rpath= thread_safe=no vinfo= vinfo_number=no weak_libs= single_module="${wl}-single_module" func_infer_tag $base_compile # We need to know -static, to get the right output filenames. for arg do case $arg in -shared) test "$build_libtool_libs" != yes && \ func_fatal_configuration "can not build a shared library" build_old_libs=no break ;; -all-static | -static | -static-libtool-libs) case $arg in -all-static) if test "$build_libtool_libs" = yes && test -z "$link_static_flag"; then func_warning "complete static linking is impossible in this configuration" fi if test -n "$link_static_flag"; then dlopen_self=$dlopen_self_static fi prefer_static_libs=yes ;; -static) if test -z "$pic_flag" && test -n "$link_static_flag"; then dlopen_self=$dlopen_self_static fi prefer_static_libs=built ;; -static-libtool-libs) if test -z "$pic_flag" && test -n "$link_static_flag"; then dlopen_self=$dlopen_self_static fi prefer_static_libs=yes ;; esac build_libtool_libs=no build_old_libs=yes break ;; esac done # See if our shared archives depend on static archives. test -n "$old_archive_from_new_cmds" && build_old_libs=yes # Go through the arguments, transforming them on the way. while test "$#" -gt 0; do arg="$1" shift func_quote_for_eval "$arg" qarg=$func_quote_for_eval_unquoted_result func_append libtool_args " $func_quote_for_eval_result" # If the previous option needs an argument, assign it. if test -n "$prev"; then case $prev in output) func_append compile_command " @OUTPUT@" func_append finalize_command " @OUTPUT@" ;; esac case $prev in bindir) bindir="$arg" prev= continue ;; dlfiles|dlprefiles) if test "$preload" = no; then # Add the symbol object into the linking commands. func_append compile_command " @SYMFILE@" func_append finalize_command " @SYMFILE@" preload=yes fi case $arg in *.la | *.lo) ;; # We handle these cases below. force) if test "$dlself" = no; then dlself=needless export_dynamic=yes fi prev= continue ;; self) if test "$prev" = dlprefiles; then dlself=yes elif test "$prev" = dlfiles && test "$dlopen_self" != yes; then dlself=yes else dlself=needless export_dynamic=yes fi prev= continue ;; *) if test "$prev" = dlfiles; then func_append dlfiles " $arg" else func_append dlprefiles " $arg" fi prev= continue ;; esac ;; expsyms) export_symbols="$arg" test -f "$arg" \ || func_fatal_error "symbol file \`$arg' does not exist" prev= continue ;; expsyms_regex) export_symbols_regex="$arg" prev= continue ;; framework) case $host in *-*-darwin*) case "$deplibs " in *" $qarg.ltframework "*) ;; *) func_append deplibs " $qarg.ltframework" # this is fixed later ;; esac ;; esac prev= continue ;; inst_prefix) inst_prefix_dir="$arg" prev= continue ;; objectlist) if test -f "$arg"; then save_arg=$arg moreargs= for fil in `cat "$save_arg"` do # func_append moreargs " $fil" arg=$fil # A libtool-controlled object. # Check to see that this really is a libtool object. if func_lalib_unsafe_p "$arg"; then pic_object= non_pic_object= # Read the .lo file func_source "$arg" if test -z "$pic_object" || test -z "$non_pic_object" || test "$pic_object" = none && test "$non_pic_object" = none; then func_fatal_error "cannot find name of object for \`$arg'" fi # Extract subdirectory from the argument. func_dirname "$arg" "/" "" xdir="$func_dirname_result" if test "$pic_object" != none; then # Prepend the subdirectory the object is found in. pic_object="$xdir$pic_object" if test "$prev" = dlfiles; then if test "$build_libtool_libs" = yes && test "$dlopen_support" = yes; then func_append dlfiles " $pic_object" prev= continue else # If libtool objects are unsupported, then we need to preload. prev=dlprefiles fi fi # CHECK ME: I think I busted this. -Ossama if test "$prev" = dlprefiles; then # Preload the old-style object. func_append dlprefiles " $pic_object" prev= fi # A PIC object. func_append libobjs " $pic_object" arg="$pic_object" fi # Non-PIC object. if test "$non_pic_object" != none; then # Prepend the subdirectory the object is found in. non_pic_object="$xdir$non_pic_object" # A standard non-PIC object func_append non_pic_objects " $non_pic_object" if test -z "$pic_object" || test "$pic_object" = none ; then arg="$non_pic_object" fi else # If the PIC object exists, use it instead. # $xdir was prepended to $pic_object above. non_pic_object="$pic_object" func_append non_pic_objects " $non_pic_object" fi else # Only an error if not doing a dry-run. if $opt_dry_run; then # Extract subdirectory from the argument. func_dirname "$arg" "/" "" xdir="$func_dirname_result" func_lo2o "$arg" pic_object=$xdir$objdir/$func_lo2o_result non_pic_object=$xdir$func_lo2o_result func_append libobjs " $pic_object" func_append non_pic_objects " $non_pic_object" else func_fatal_error "\`$arg' is not a valid libtool object" fi fi done else func_fatal_error "link input file \`$arg' does not exist" fi arg=$save_arg prev= continue ;; precious_regex) precious_files_regex="$arg" prev= continue ;; release) release="-$arg" prev= continue ;; rpath | xrpath) # We need an absolute path. case $arg in [\\/]* | [A-Za-z]:[\\/]*) ;; *) func_fatal_error "only absolute run-paths are allowed" ;; esac if test "$prev" = rpath; then case "$rpath " in *" $arg "*) ;; *) func_append rpath " $arg" ;; esac else case "$xrpath " in *" $arg "*) ;; *) func_append xrpath " $arg" ;; esac fi prev= continue ;; shrext) shrext_cmds="$arg" prev= continue ;; weak) func_append weak_libs " $arg" prev= continue ;; xcclinker) func_append linker_flags " $qarg" func_append compiler_flags " $qarg" prev= func_append compile_command " $qarg" func_append finalize_command " $qarg" continue ;; xcompiler) func_append compiler_flags " $qarg" prev= func_append compile_command " $qarg" func_append finalize_command " $qarg" continue ;; xlinker) func_append linker_flags " $qarg" func_append compiler_flags " $wl$qarg" prev= func_append compile_command " $wl$qarg" func_append finalize_command " $wl$qarg" continue ;; *) eval "$prev=\"\$arg\"" prev= continue ;; esac fi # test -n "$prev" prevarg="$arg" case $arg in -all-static) if test -n "$link_static_flag"; then # See comment for -static flag below, for more details. func_append compile_command " $link_static_flag" func_append finalize_command " $link_static_flag" fi continue ;; -allow-undefined) # FIXME: remove this flag sometime in the future. func_fatal_error "\`-allow-undefined' must not be used because it is the default" ;; -avoid-version) avoid_version=yes continue ;; -bindir) prev=bindir continue ;; -dlopen) prev=dlfiles continue ;; -dlpreopen) prev=dlprefiles continue ;; -export-dynamic) export_dynamic=yes continue ;; -export-symbols | -export-symbols-regex) if test -n "$export_symbols" || test -n "$export_symbols_regex"; then func_fatal_error "more than one -exported-symbols argument is not allowed" fi if test "X$arg" = "X-export-symbols"; then prev=expsyms else prev=expsyms_regex fi continue ;; -framework) prev=framework continue ;; -inst-prefix-dir) prev=inst_prefix continue ;; # The native IRIX linker understands -LANG:*, -LIST:* and -LNO:* # so, if we see these flags be careful not to treat them like -L -L[A-Z][A-Z]*:*) case $with_gcc/$host in no/*-*-irix* | /*-*-irix*) func_append compile_command " $arg" func_append finalize_command " $arg" ;; esac continue ;; -L*) func_stripname "-L" '' "$arg" if test -z "$func_stripname_result"; then if test "$#" -gt 0; then func_fatal_error "require no space between \`-L' and \`$1'" else func_fatal_error "need path for \`-L' option" fi fi func_resolve_sysroot "$func_stripname_result" dir=$func_resolve_sysroot_result # We need an absolute path. case $dir in [\\/]* | [A-Za-z]:[\\/]*) ;; *) absdir=`cd "$dir" && pwd` test -z "$absdir" && \ func_fatal_error "cannot determine absolute directory name of \`$dir'" dir="$absdir" ;; esac case "$deplibs " in *" -L$dir "* | *" $arg "*) # Will only happen for absolute or sysroot arguments ;; *) # Preserve sysroot, but never include relative directories case $dir in [\\/]* | [A-Za-z]:[\\/]* | =*) func_append deplibs " $arg" ;; *) func_append deplibs " -L$dir" ;; esac func_append lib_search_path " $dir" ;; esac case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2* | *-cegcc*) testbindir=`$ECHO "$dir" | $SED 's*/lib$*/bin*'` case :$dllsearchpath: in *":$dir:"*) ;; ::) dllsearchpath=$dir;; *) func_append dllsearchpath ":$dir";; esac case :$dllsearchpath: in *":$testbindir:"*) ;; ::) dllsearchpath=$testbindir;; *) func_append dllsearchpath ":$testbindir";; esac ;; esac continue ;; -l*) if test "X$arg" = "X-lc" || test "X$arg" = "X-lm"; then case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-beos* | *-cegcc* | *-*-haiku*) # These systems don't actually have a C or math library (as such) continue ;; *-*-os2*) # These systems don't actually have a C library (as such) test "X$arg" = "X-lc" && continue ;; *-*-openbsd* | *-*-freebsd* | *-*-dragonfly*) # Do not include libc due to us having libc/libc_r. test "X$arg" = "X-lc" && continue ;; *-*-rhapsody* | *-*-darwin1.[012]) # Rhapsody C and math libraries are in the System framework func_append deplibs " System.ltframework" continue ;; *-*-sco3.2v5* | *-*-sco5v6*) # Causes problems with __ctype test "X$arg" = "X-lc" && continue ;; *-*-sysv4.2uw2* | *-*-sysv5* | *-*-unixware* | *-*-OpenUNIX*) # Compiler inserts libc in the correct place for threads to work test "X$arg" = "X-lc" && continue ;; esac elif test "X$arg" = "X-lc_r"; then case $host in *-*-openbsd* | *-*-freebsd* | *-*-dragonfly*) # Do not include libc_r directly, use -pthread flag. continue ;; esac fi func_append deplibs " $arg" continue ;; -module) module=yes continue ;; # Tru64 UNIX uses -model [arg] to determine the layout of C++ # classes, name mangling, and exception handling. # Darwin uses the -arch flag to determine output architecture. -model|-arch|-isysroot|--sysroot) func_append compiler_flags " $arg" func_append compile_command " $arg" func_append finalize_command " $arg" prev=xcompiler continue ;; -mt|-mthreads|-kthread|-Kthread|-pthread|-pthreads|--thread-safe \ |-threads|-fopenmp|-openmp|-mp|-xopenmp|-omp|-qsmp=*) func_append compiler_flags " $arg" func_append compile_command " $arg" func_append finalize_command " $arg" case "$new_inherited_linker_flags " in *" $arg "*) ;; * ) func_append new_inherited_linker_flags " $arg" ;; esac continue ;; -multi_module) single_module="${wl}-multi_module" continue ;; -no-fast-install) fast_install=no continue ;; -no-install) case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2* | *-*-darwin* | *-cegcc*) # The PATH hackery in wrapper scripts is required on Windows # and Darwin in order for the loader to find any dlls it needs. func_warning "\`-no-install' is ignored for $host" func_warning "assuming \`-no-fast-install' instead" fast_install=no ;; *) no_install=yes ;; esac continue ;; -no-undefined) allow_undefined=no continue ;; -objectlist) prev=objectlist continue ;; -o) prev=output ;; -precious-files-regex) prev=precious_regex continue ;; -release) prev=release continue ;; -rpath) prev=rpath continue ;; -R) prev=xrpath continue ;; -R*) func_stripname '-R' '' "$arg" dir=$func_stripname_result # We need an absolute path. case $dir in [\\/]* | [A-Za-z]:[\\/]*) ;; =*) func_stripname '=' '' "$dir" dir=$lt_sysroot$func_stripname_result ;; *) func_fatal_error "only absolute run-paths are allowed" ;; esac case "$xrpath " in *" $dir "*) ;; *) func_append xrpath " $dir" ;; esac continue ;; -shared) # The effects of -shared are defined in a previous loop. continue ;; -shrext) prev=shrext continue ;; -static | -static-libtool-libs) # The effects of -static are defined in a previous loop. # We used to do the same as -all-static on platforms that # didn't have a PIC flag, but the assumption that the effects # would be equivalent was wrong. It would break on at least # Digital Unix and AIX. continue ;; -thread-safe) thread_safe=yes continue ;; -version-info) prev=vinfo continue ;; -version-number) prev=vinfo vinfo_number=yes continue ;; -weak) prev=weak continue ;; -Wc,*) func_stripname '-Wc,' '' "$arg" args=$func_stripname_result arg= save_ifs="$IFS"; IFS=',' for flag in $args; do IFS="$save_ifs" func_quote_for_eval "$flag" func_append arg " $func_quote_for_eval_result" func_append compiler_flags " $func_quote_for_eval_result" done IFS="$save_ifs" func_stripname ' ' '' "$arg" arg=$func_stripname_result ;; -Wl,*) func_stripname '-Wl,' '' "$arg" args=$func_stripname_result arg= save_ifs="$IFS"; IFS=',' for flag in $args; do IFS="$save_ifs" func_quote_for_eval "$flag" func_append arg " $wl$func_quote_for_eval_result" func_append compiler_flags " $wl$func_quote_for_eval_result" func_append linker_flags " $func_quote_for_eval_result" done IFS="$save_ifs" func_stripname ' ' '' "$arg" arg=$func_stripname_result ;; -Xcompiler) prev=xcompiler continue ;; -Xlinker) prev=xlinker continue ;; -XCClinker) prev=xcclinker continue ;; # -msg_* for osf cc -msg_*) func_quote_for_eval "$arg" arg="$func_quote_for_eval_result" ;; # Flags to be passed through unchanged, with rationale: # -64, -mips[0-9] enable 64-bit mode for the SGI compiler # -r[0-9][0-9]* specify processor for the SGI compiler # -xarch=*, -xtarget=* enable 64-bit mode for the Sun compiler # +DA*, +DD* enable 64-bit mode for the HP compiler # -q* compiler args for the IBM compiler # -m*, -t[45]*, -txscale* architecture-specific flags for GCC # -F/path path to uninstalled frameworks, gcc on darwin # -p, -pg, --coverage, -fprofile-* profiling flags for GCC # @file GCC response files # -tp=* Portland pgcc target processor selection # --sysroot=* for sysroot support # -O*, -flto*, -fwhopr*, -fuse-linker-plugin GCC link-time optimization -64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \ -t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \ -O*|-flto*|-fwhopr*|-fuse-linker-plugin) func_quote_for_eval "$arg" arg="$func_quote_for_eval_result" func_append compile_command " $arg" func_append finalize_command " $arg" func_append compiler_flags " $arg" continue ;; # Some other compiler flag. -* | +*) func_quote_for_eval "$arg" arg="$func_quote_for_eval_result" ;; *.$objext) # A standard object. func_append objs " $arg" ;; *.lo) # A libtool-controlled object. # Check to see that this really is a libtool object. if func_lalib_unsafe_p "$arg"; then pic_object= non_pic_object= # Read the .lo file func_source "$arg" if test -z "$pic_object" || test -z "$non_pic_object" || test "$pic_object" = none && test "$non_pic_object" = none; then func_fatal_error "cannot find name of object for \`$arg'" fi # Extract subdirectory from the argument. func_dirname "$arg" "/" "" xdir="$func_dirname_result" if test "$pic_object" != none; then # Prepend the subdirectory the object is found in. pic_object="$xdir$pic_object" if test "$prev" = dlfiles; then if test "$build_libtool_libs" = yes && test "$dlopen_support" = yes; then func_append dlfiles " $pic_object" prev= continue else # If libtool objects are unsupported, then we need to preload. prev=dlprefiles fi fi # CHECK ME: I think I busted this. -Ossama if test "$prev" = dlprefiles; then # Preload the old-style object. func_append dlprefiles " $pic_object" prev= fi # A PIC object. func_append libobjs " $pic_object" arg="$pic_object" fi # Non-PIC object. if test "$non_pic_object" != none; then # Prepend the subdirectory the object is found in. non_pic_object="$xdir$non_pic_object" # A standard non-PIC object func_append non_pic_objects " $non_pic_object" if test -z "$pic_object" || test "$pic_object" = none ; then arg="$non_pic_object" fi else # If the PIC object exists, use it instead. # $xdir was prepended to $pic_object above. non_pic_object="$pic_object" func_append non_pic_objects " $non_pic_object" fi else # Only an error if not doing a dry-run. if $opt_dry_run; then # Extract subdirectory from the argument. func_dirname "$arg" "/" "" xdir="$func_dirname_result" func_lo2o "$arg" pic_object=$xdir$objdir/$func_lo2o_result non_pic_object=$xdir$func_lo2o_result func_append libobjs " $pic_object" func_append non_pic_objects " $non_pic_object" else func_fatal_error "\`$arg' is not a valid libtool object" fi fi ;; *.$libext) # An archive. func_append deplibs " $arg" func_append old_deplibs " $arg" continue ;; *.la) # A libtool-controlled library. func_resolve_sysroot "$arg" if test "$prev" = dlfiles; then # This library was specified with -dlopen. func_append dlfiles " $func_resolve_sysroot_result" prev= elif test "$prev" = dlprefiles; then # The library was specified with -dlpreopen. func_append dlprefiles " $func_resolve_sysroot_result" prev= else func_append deplibs " $func_resolve_sysroot_result" fi continue ;; # Some other compiler argument. *) # Unknown arguments in both finalize_command and compile_command need # to be aesthetically quoted because they are evaled later. func_quote_for_eval "$arg" arg="$func_quote_for_eval_result" ;; esac # arg # Now actually substitute the argument into the commands. if test -n "$arg"; then func_append compile_command " $arg" func_append finalize_command " $arg" fi done # argument parsing loop test -n "$prev" && \ func_fatal_help "the \`$prevarg' option requires an argument" if test "$export_dynamic" = yes && test -n "$export_dynamic_flag_spec"; then eval arg=\"$export_dynamic_flag_spec\" func_append compile_command " $arg" func_append finalize_command " $arg" fi oldlibs= # calculate the name of the file, without its directory func_basename "$output" outputname="$func_basename_result" libobjs_save="$libobjs" if test -n "$shlibpath_var"; then # get the directories listed in $shlibpath_var eval shlib_search_path=\`\$ECHO \"\${$shlibpath_var}\" \| \$SED \'s/:/ /g\'\` else shlib_search_path= fi eval sys_lib_search_path=\"$sys_lib_search_path_spec\" eval sys_lib_dlsearch_path=\"$sys_lib_dlsearch_path_spec\" func_dirname "$output" "/" "" output_objdir="$func_dirname_result$objdir" func_to_tool_file "$output_objdir/" tool_output_objdir=$func_to_tool_file_result # Create the object directory. func_mkdir_p "$output_objdir" # Determine the type of output case $output in "") func_fatal_help "you must specify an output file" ;; *.$libext) linkmode=oldlib ;; *.lo | *.$objext) linkmode=obj ;; *.la) linkmode=lib ;; *) linkmode=prog ;; # Anything else should be a program. esac specialdeplibs= libs= # Find all interdependent deplibs by searching for libraries # that are linked more than once (e.g. -la -lb -la) for deplib in $deplibs; do if $opt_preserve_dup_deps ; then case "$libs " in *" $deplib "*) func_append specialdeplibs " $deplib" ;; esac fi func_append libs " $deplib" done if test "$linkmode" = lib; then libs="$predeps $libs $compiler_lib_search_path $postdeps" # Compute libraries that are listed more than once in $predeps # $postdeps and mark them as special (i.e., whose duplicates are # not to be eliminated). pre_post_deps= if $opt_duplicate_compiler_generated_deps; then for pre_post_dep in $predeps $postdeps; do case "$pre_post_deps " in *" $pre_post_dep "*) func_append specialdeplibs " $pre_post_deps" ;; esac func_append pre_post_deps " $pre_post_dep" done fi pre_post_deps= fi deplibs= newdependency_libs= newlib_search_path= need_relink=no # whether we're linking any uninstalled libtool libraries notinst_deplibs= # not-installed libtool libraries notinst_path= # paths that contain not-installed libtool libraries case $linkmode in lib) passes="conv dlpreopen link" for file in $dlfiles $dlprefiles; do case $file in *.la) ;; *) func_fatal_help "libraries can \`-dlopen' only libtool libraries: $file" ;; esac done ;; prog) compile_deplibs= finalize_deplibs= alldeplibs=no newdlfiles= newdlprefiles= passes="conv scan dlopen dlpreopen link" ;; *) passes="conv" ;; esac for pass in $passes; do # The preopen pass in lib mode reverses $deplibs; put it back here # so that -L comes before libs that need it for instance... if test "$linkmode,$pass" = "lib,link"; then ## FIXME: Find the place where the list is rebuilt in the wrong ## order, and fix it there properly tmp_deplibs= for deplib in $deplibs; do tmp_deplibs="$deplib $tmp_deplibs" done deplibs="$tmp_deplibs" fi if test "$linkmode,$pass" = "lib,link" || test "$linkmode,$pass" = "prog,scan"; then libs="$deplibs" deplibs= fi if test "$linkmode" = prog; then case $pass in dlopen) libs="$dlfiles" ;; dlpreopen) libs="$dlprefiles" ;; link) libs="$deplibs %DEPLIBS% $dependency_libs" ;; esac fi if test "$linkmode,$pass" = "lib,dlpreopen"; then # Collect and forward deplibs of preopened libtool libs for lib in $dlprefiles; do # Ignore non-libtool-libs dependency_libs= func_resolve_sysroot "$lib" case $lib in *.la) func_source "$func_resolve_sysroot_result" ;; esac # Collect preopened libtool deplibs, except any this library # has declared as weak libs for deplib in $dependency_libs; do func_basename "$deplib" deplib_base=$func_basename_result case " $weak_libs " in *" $deplib_base "*) ;; *) func_append deplibs " $deplib" ;; esac done done libs="$dlprefiles" fi if test "$pass" = dlopen; then # Collect dlpreopened libraries save_deplibs="$deplibs" deplibs= fi for deplib in $libs; do lib= found=no case $deplib in -mt|-mthreads|-kthread|-Kthread|-pthread|-pthreads|--thread-safe \ |-threads|-fopenmp|-openmp|-mp|-xopenmp|-omp|-qsmp=*) if test "$linkmode,$pass" = "prog,link"; then compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" else func_append compiler_flags " $deplib" if test "$linkmode" = lib ; then case "$new_inherited_linker_flags " in *" $deplib "*) ;; * ) func_append new_inherited_linker_flags " $deplib" ;; esac fi fi continue ;; -l*) if test "$linkmode" != lib && test "$linkmode" != prog; then func_warning "\`-l' is ignored for archives/objects" continue fi func_stripname '-l' '' "$deplib" name=$func_stripname_result if test "$linkmode" = lib; then searchdirs="$newlib_search_path $lib_search_path $compiler_lib_search_dirs $sys_lib_search_path $shlib_search_path" else searchdirs="$newlib_search_path $lib_search_path $sys_lib_search_path $shlib_search_path" fi for searchdir in $searchdirs; do for search_ext in .la $std_shrext .so .a; do # Search the libtool library lib="$searchdir/lib${name}${search_ext}" if test -f "$lib"; then if test "$search_ext" = ".la"; then found=yes else found=no fi break 2 fi done done if test "$found" != yes; then # deplib doesn't seem to be a libtool library if test "$linkmode,$pass" = "prog,link"; then compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" else deplibs="$deplib $deplibs" test "$linkmode" = lib && newdependency_libs="$deplib $newdependency_libs" fi continue else # deplib is a libtool library # If $allow_libtool_libs_with_static_runtimes && $deplib is a stdlib, # We need to do some special things here, and not later. if test "X$allow_libtool_libs_with_static_runtimes" = "Xyes" ; then case " $predeps $postdeps " in *" $deplib "*) if func_lalib_p "$lib"; then library_names= old_library= func_source "$lib" for l in $old_library $library_names; do ll="$l" done if test "X$ll" = "X$old_library" ; then # only static version available found=no func_dirname "$lib" "" "." ladir="$func_dirname_result" lib=$ladir/$old_library if test "$linkmode,$pass" = "prog,link"; then compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" else deplibs="$deplib $deplibs" test "$linkmode" = lib && newdependency_libs="$deplib $newdependency_libs" fi continue fi fi ;; *) ;; esac fi fi ;; # -l *.ltframework) if test "$linkmode,$pass" = "prog,link"; then compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" else deplibs="$deplib $deplibs" if test "$linkmode" = lib ; then case "$new_inherited_linker_flags " in *" $deplib "*) ;; * ) func_append new_inherited_linker_flags " $deplib" ;; esac fi fi continue ;; -L*) case $linkmode in lib) deplibs="$deplib $deplibs" test "$pass" = conv && continue newdependency_libs="$deplib $newdependency_libs" func_stripname '-L' '' "$deplib" func_resolve_sysroot "$func_stripname_result" func_append newlib_search_path " $func_resolve_sysroot_result" ;; prog) if test "$pass" = conv; then deplibs="$deplib $deplibs" continue fi if test "$pass" = scan; then deplibs="$deplib $deplibs" else compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" fi func_stripname '-L' '' "$deplib" func_resolve_sysroot "$func_stripname_result" func_append newlib_search_path " $func_resolve_sysroot_result" ;; *) func_warning "\`-L' is ignored for archives/objects" ;; esac # linkmode continue ;; # -L -R*) if test "$pass" = link; then func_stripname '-R' '' "$deplib" func_resolve_sysroot "$func_stripname_result" dir=$func_resolve_sysroot_result # Make sure the xrpath contains only unique directories. case "$xrpath " in *" $dir "*) ;; *) func_append xrpath " $dir" ;; esac fi deplibs="$deplib $deplibs" continue ;; *.la) func_resolve_sysroot "$deplib" lib=$func_resolve_sysroot_result ;; *.$libext) if test "$pass" = conv; then deplibs="$deplib $deplibs" continue fi case $linkmode in lib) # Linking convenience modules into shared libraries is allowed, # but linking other static libraries is non-portable. case " $dlpreconveniencelibs " in *" $deplib "*) ;; *) valid_a_lib=no case $deplibs_check_method in match_pattern*) set dummy $deplibs_check_method; shift match_pattern_regex=`expr "$deplibs_check_method" : "$1 \(.*\)"` if eval "\$ECHO \"$deplib\"" 2>/dev/null | $SED 10q \ | $EGREP "$match_pattern_regex" > /dev/null; then valid_a_lib=yes fi ;; pass_all) valid_a_lib=yes ;; esac if test "$valid_a_lib" != yes; then echo $ECHO "*** Warning: Trying to link with static lib archive $deplib." echo "*** I have the capability to make that library automatically link in when" echo "*** you link to this library. But I can only do this if you have a" echo "*** shared version of the library, which you do not appear to have" echo "*** because the file extensions .$libext of this argument makes me believe" echo "*** that it is just a static archive that I should not use here." else echo $ECHO "*** Warning: Linking the shared library $output against the" $ECHO "*** static library $deplib is not portable!" deplibs="$deplib $deplibs" fi ;; esac continue ;; prog) if test "$pass" != link; then deplibs="$deplib $deplibs" else compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" fi continue ;; esac # linkmode ;; # *.$libext *.lo | *.$objext) if test "$pass" = conv; then deplibs="$deplib $deplibs" elif test "$linkmode" = prog; then if test "$pass" = dlpreopen || test "$dlopen_support" != yes || test "$build_libtool_libs" = no; then # If there is no dlopen support or we're linking statically, # we need to preload. func_append newdlprefiles " $deplib" compile_deplibs="$deplib $compile_deplibs" finalize_deplibs="$deplib $finalize_deplibs" else func_append newdlfiles " $deplib" fi fi continue ;; %DEPLIBS%) alldeplibs=yes continue ;; esac # case $deplib if test "$found" = yes || test -f "$lib"; then : else func_fatal_error "cannot find the library \`$lib' or unhandled argument \`$deplib'" fi # Check to see that this really is a libtool archive. func_lalib_unsafe_p "$lib" \ || func_fatal_error "\`$lib' is not a valid libtool archive" func_dirname "$lib" "" "." ladir="$func_dirname_result" dlname= dlopen= dlpreopen= libdir= library_names= old_library= inherited_linker_flags= # If the library was installed with an old release of libtool, # it will not redefine variables installed, or shouldnotlink installed=yes shouldnotlink=no avoidtemprpath= # Read the .la file func_source "$lib" # Convert "-framework foo" to "foo.ltframework" if test -n "$inherited_linker_flags"; then tmp_inherited_linker_flags=`$ECHO "$inherited_linker_flags" | $SED 's/-framework \([^ $]*\)/\1.ltframework/g'` for tmp_inherited_linker_flag in $tmp_inherited_linker_flags; do case " $new_inherited_linker_flags " in *" $tmp_inherited_linker_flag "*) ;; *) func_append new_inherited_linker_flags " $tmp_inherited_linker_flag";; esac done fi dependency_libs=`$ECHO " $dependency_libs" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` if test "$linkmode,$pass" = "lib,link" || test "$linkmode,$pass" = "prog,scan" || { test "$linkmode" != prog && test "$linkmode" != lib; }; then test -n "$dlopen" && func_append dlfiles " $dlopen" test -n "$dlpreopen" && func_append dlprefiles " $dlpreopen" fi if test "$pass" = conv; then # Only check for convenience libraries deplibs="$lib $deplibs" if test -z "$libdir"; then if test -z "$old_library"; then func_fatal_error "cannot find name of link library for \`$lib'" fi # It is a libtool convenience library, so add in its objects. func_append convenience " $ladir/$objdir/$old_library" func_append old_convenience " $ladir/$objdir/$old_library" elif test "$linkmode" != prog && test "$linkmode" != lib; then func_fatal_error "\`$lib' is not a convenience library" fi tmp_libs= for deplib in $dependency_libs; do deplibs="$deplib $deplibs" if $opt_preserve_dup_deps ; then case "$tmp_libs " in *" $deplib "*) func_append specialdeplibs " $deplib" ;; esac fi func_append tmp_libs " $deplib" done continue fi # $pass = conv # Get the name of the library we link against. linklib= if test -n "$old_library" && { test "$prefer_static_libs" = yes || test "$prefer_static_libs,$installed" = "built,no"; }; then linklib=$old_library else for l in $old_library $library_names; do linklib="$l" done fi if test -z "$linklib"; then func_fatal_error "cannot find name of link library for \`$lib'" fi # This library was specified with -dlopen. if test "$pass" = dlopen; then if test -z "$libdir"; then func_fatal_error "cannot -dlopen a convenience library: \`$lib'" fi if test -z "$dlname" || test "$dlopen_support" != yes || test "$build_libtool_libs" = no; then # If there is no dlname, no dlopen support or we're linking # statically, we need to preload. We also need to preload any # dependent libraries so libltdl's deplib preloader doesn't # bomb out in the load deplibs phase. func_append dlprefiles " $lib $dependency_libs" else func_append newdlfiles " $lib" fi continue fi # $pass = dlopen # We need an absolute path. case $ladir in [\\/]* | [A-Za-z]:[\\/]*) abs_ladir="$ladir" ;; *) abs_ladir=`cd "$ladir" && pwd` if test -z "$abs_ladir"; then func_warning "cannot determine absolute directory name of \`$ladir'" func_warning "passing it literally to the linker, although it might fail" abs_ladir="$ladir" fi ;; esac func_basename "$lib" laname="$func_basename_result" # Find the relevant object directory and library name. if test "X$installed" = Xyes; then if test ! -f "$lt_sysroot$libdir/$linklib" && test -f "$abs_ladir/$linklib"; then func_warning "library \`$lib' was moved." dir="$ladir" absdir="$abs_ladir" libdir="$abs_ladir" else dir="$lt_sysroot$libdir" absdir="$lt_sysroot$libdir" fi test "X$hardcode_automatic" = Xyes && avoidtemprpath=yes else if test ! -f "$ladir/$objdir/$linklib" && test -f "$abs_ladir/$linklib"; then dir="$ladir" absdir="$abs_ladir" # Remove this search path later func_append notinst_path " $abs_ladir" else dir="$ladir/$objdir" absdir="$abs_ladir/$objdir" # Remove this search path later func_append notinst_path " $abs_ladir" fi fi # $installed = yes func_stripname 'lib' '.la' "$laname" name=$func_stripname_result # This library was specified with -dlpreopen. if test "$pass" = dlpreopen; then if test -z "$libdir" && test "$linkmode" = prog; then func_fatal_error "only libraries may -dlpreopen a convenience library: \`$lib'" fi case "$host" in # special handling for platforms with PE-DLLs. *cygwin* | *mingw* | *cegcc* ) # Linker will automatically link against shared library if both # static and shared are present. Therefore, ensure we extract # symbols from the import library if a shared library is present # (otherwise, the dlopen module name will be incorrect). We do # this by putting the import library name into $newdlprefiles. # We recover the dlopen module name by 'saving' the la file # name in a special purpose variable, and (later) extracting the # dlname from the la file. if test -n "$dlname"; then func_tr_sh "$dir/$linklib" eval "libfile_$func_tr_sh_result=\$abs_ladir/\$laname" func_append newdlprefiles " $dir/$linklib" else func_append newdlprefiles " $dir/$old_library" # Keep a list of preopened convenience libraries to check # that they are being used correctly in the link pass. test -z "$libdir" && \ func_append dlpreconveniencelibs " $dir/$old_library" fi ;; * ) # Prefer using a static library (so that no silly _DYNAMIC symbols # are required to link). if test -n "$old_library"; then func_append newdlprefiles " $dir/$old_library" # Keep a list of preopened convenience libraries to check # that they are being used correctly in the link pass. test -z "$libdir" && \ func_append dlpreconveniencelibs " $dir/$old_library" # Otherwise, use the dlname, so that lt_dlopen finds it. elif test -n "$dlname"; then func_append newdlprefiles " $dir/$dlname" else func_append newdlprefiles " $dir/$linklib" fi ;; esac fi # $pass = dlpreopen if test -z "$libdir"; then # Link the convenience library if test "$linkmode" = lib; then deplibs="$dir/$old_library $deplibs" elif test "$linkmode,$pass" = "prog,link"; then compile_deplibs="$dir/$old_library $compile_deplibs" finalize_deplibs="$dir/$old_library $finalize_deplibs" else deplibs="$lib $deplibs" # used for prog,scan pass fi continue fi if test "$linkmode" = prog && test "$pass" != link; then func_append newlib_search_path " $ladir" deplibs="$lib $deplibs" linkalldeplibs=no if test "$link_all_deplibs" != no || test -z "$library_names" || test "$build_libtool_libs" = no; then linkalldeplibs=yes fi tmp_libs= for deplib in $dependency_libs; do case $deplib in -L*) func_stripname '-L' '' "$deplib" func_resolve_sysroot "$func_stripname_result" func_append newlib_search_path " $func_resolve_sysroot_result" ;; esac # Need to link against all dependency_libs? if test "$linkalldeplibs" = yes; then deplibs="$deplib $deplibs" else # Need to hardcode shared library paths # or/and link against static libraries newdependency_libs="$deplib $newdependency_libs" fi if $opt_preserve_dup_deps ; then case "$tmp_libs " in *" $deplib "*) func_append specialdeplibs " $deplib" ;; esac fi func_append tmp_libs " $deplib" done # for deplib continue fi # $linkmode = prog... if test "$linkmode,$pass" = "prog,link"; then if test -n "$library_names" && { { test "$prefer_static_libs" = no || test "$prefer_static_libs,$installed" = "built,yes"; } || test -z "$old_library"; }; then # We need to hardcode the library path if test -n "$shlibpath_var" && test -z "$avoidtemprpath" ; then # Make sure the rpath contains only unique directories. case "$temp_rpath:" in *"$absdir:"*) ;; *) func_append temp_rpath "$absdir:" ;; esac fi # Hardcode the library path. # Skip directories that are in the system default run-time # search path. case " $sys_lib_dlsearch_path " in *" $absdir "*) ;; *) case "$compile_rpath " in *" $absdir "*) ;; *) func_append compile_rpath " $absdir" ;; esac ;; esac case " $sys_lib_dlsearch_path " in *" $libdir "*) ;; *) case "$finalize_rpath " in *" $libdir "*) ;; *) func_append finalize_rpath " $libdir" ;; esac ;; esac fi # $linkmode,$pass = prog,link... if test "$alldeplibs" = yes && { test "$deplibs_check_method" = pass_all || { test "$build_libtool_libs" = yes && test -n "$library_names"; }; }; then # We only need to search for static libraries continue fi fi link_static=no # Whether the deplib will be linked statically use_static_libs=$prefer_static_libs if test "$use_static_libs" = built && test "$installed" = yes; then use_static_libs=no fi if test -n "$library_names" && { test "$use_static_libs" = no || test -z "$old_library"; }; then case $host in *cygwin* | *mingw* | *cegcc*) # No point in relinking DLLs because paths are not encoded func_append notinst_deplibs " $lib" need_relink=no ;; *) if test "$installed" = no; then func_append notinst_deplibs " $lib" need_relink=yes fi ;; esac # This is a shared library # Warn about portability, can't link against -module's on some # systems (darwin). Don't bleat about dlopened modules though! dlopenmodule="" for dlpremoduletest in $dlprefiles; do if test "X$dlpremoduletest" = "X$lib"; then dlopenmodule="$dlpremoduletest" break fi done if test -z "$dlopenmodule" && test "$shouldnotlink" = yes && test "$pass" = link; then echo if test "$linkmode" = prog; then $ECHO "*** Warning: Linking the executable $output against the loadable module" else $ECHO "*** Warning: Linking the shared library $output against the loadable module" fi $ECHO "*** $linklib is not portable!" fi if test "$linkmode" = lib && test "$hardcode_into_libs" = yes; then # Hardcode the library path. # Skip directories that are in the system default run-time # search path. case " $sys_lib_dlsearch_path " in *" $absdir "*) ;; *) case "$compile_rpath " in *" $absdir "*) ;; *) func_append compile_rpath " $absdir" ;; esac ;; esac case " $sys_lib_dlsearch_path " in *" $libdir "*) ;; *) case "$finalize_rpath " in *" $libdir "*) ;; *) func_append finalize_rpath " $libdir" ;; esac ;; esac fi if test -n "$old_archive_from_expsyms_cmds"; then # figure out the soname set dummy $library_names shift realname="$1" shift libname=`eval "\\$ECHO \"$libname_spec\""` # use dlname if we got it. it's perfectly good, no? if test -n "$dlname"; then soname="$dlname" elif test -n "$soname_spec"; then # bleh windows case $host in *cygwin* | mingw* | *cegcc*) func_arith $current - $age major=$func_arith_result versuffix="-$major" ;; esac eval soname=\"$soname_spec\" else soname="$realname" fi # Make a new name for the extract_expsyms_cmds to use soroot="$soname" func_basename "$soroot" soname="$func_basename_result" func_stripname 'lib' '.dll' "$soname" newlib=libimp-$func_stripname_result.a # If the library has no export list, then create one now if test -f "$output_objdir/$soname-def"; then : else func_verbose "extracting exported symbol list from \`$soname'" func_execute_cmds "$extract_expsyms_cmds" 'exit $?' fi # Create $newlib if test -f "$output_objdir/$newlib"; then :; else func_verbose "generating import library for \`$soname'" func_execute_cmds "$old_archive_from_expsyms_cmds" 'exit $?' fi # make sure the library variables are pointing to the new library dir=$output_objdir linklib=$newlib fi # test -n "$old_archive_from_expsyms_cmds" if test "$linkmode" = prog || test "$opt_mode" != relink; then add_shlibpath= add_dir= add= lib_linked=yes case $hardcode_action in immediate | unsupported) if test "$hardcode_direct" = no; then add="$dir/$linklib" case $host in *-*-sco3.2v5.0.[024]*) add_dir="-L$dir" ;; *-*-sysv4*uw2*) add_dir="-L$dir" ;; *-*-sysv5OpenUNIX* | *-*-sysv5UnixWare7.[01].[10]* | \ *-*-unixware7*) add_dir="-L$dir" ;; *-*-darwin* ) # if the lib is a (non-dlopened) module then we can not # link against it, someone is ignoring the earlier warnings if /usr/bin/file -L $add 2> /dev/null | $GREP ": [^:]* bundle" >/dev/null ; then if test "X$dlopenmodule" != "X$lib"; then $ECHO "*** Warning: lib $linklib is a module, not a shared library" if test -z "$old_library" ; then echo echo "*** And there doesn't seem to be a static archive available" echo "*** The link will probably fail, sorry" else add="$dir/$old_library" fi elif test -n "$old_library"; then add="$dir/$old_library" fi fi esac elif test "$hardcode_minus_L" = no; then case $host in *-*-sunos*) add_shlibpath="$dir" ;; esac add_dir="-L$dir" add="-l$name" elif test "$hardcode_shlibpath_var" = no; then add_shlibpath="$dir" add="-l$name" else lib_linked=no fi ;; relink) if test "$hardcode_direct" = yes && test "$hardcode_direct_absolute" = no; then add="$dir/$linklib" elif test "$hardcode_minus_L" = yes; then add_dir="-L$absdir" # Try looking first in the location we're being installed to. if test -n "$inst_prefix_dir"; then case $libdir in [\\/]*) func_append add_dir " -L$inst_prefix_dir$libdir" ;; esac fi add="-l$name" elif test "$hardcode_shlibpath_var" = yes; then add_shlibpath="$dir" add="-l$name" else lib_linked=no fi ;; *) lib_linked=no ;; esac if test "$lib_linked" != yes; then func_fatal_configuration "unsupported hardcode properties" fi if test -n "$add_shlibpath"; then case :$compile_shlibpath: in *":$add_shlibpath:"*) ;; *) func_append compile_shlibpath "$add_shlibpath:" ;; esac fi if test "$linkmode" = prog; then test -n "$add_dir" && compile_deplibs="$add_dir $compile_deplibs" test -n "$add" && compile_deplibs="$add $compile_deplibs" else test -n "$add_dir" && deplibs="$add_dir $deplibs" test -n "$add" && deplibs="$add $deplibs" if test "$hardcode_direct" != yes && test "$hardcode_minus_L" != yes && test "$hardcode_shlibpath_var" = yes; then case :$finalize_shlibpath: in *":$libdir:"*) ;; *) func_append finalize_shlibpath "$libdir:" ;; esac fi fi fi if test "$linkmode" = prog || test "$opt_mode" = relink; then add_shlibpath= add_dir= add= # Finalize command for both is simple: just hardcode it. if test "$hardcode_direct" = yes && test "$hardcode_direct_absolute" = no; then add="$libdir/$linklib" elif test "$hardcode_minus_L" = yes; then add_dir="-L$libdir" add="-l$name" elif test "$hardcode_shlibpath_var" = yes; then case :$finalize_shlibpath: in *":$libdir:"*) ;; *) func_append finalize_shlibpath "$libdir:" ;; esac add="-l$name" elif test "$hardcode_automatic" = yes; then if test -n "$inst_prefix_dir" && test -f "$inst_prefix_dir$libdir/$linklib" ; then add="$inst_prefix_dir$libdir/$linklib" else add="$libdir/$linklib" fi else # We cannot seem to hardcode it, guess we'll fake it. add_dir="-L$libdir" # Try looking first in the location we're being installed to. if test -n "$inst_prefix_dir"; then case $libdir in [\\/]*) func_append add_dir " -L$inst_prefix_dir$libdir" ;; esac fi add="-l$name" fi if test "$linkmode" = prog; then test -n "$add_dir" && finalize_deplibs="$add_dir $finalize_deplibs" test -n "$add" && finalize_deplibs="$add $finalize_deplibs" else test -n "$add_dir" && deplibs="$add_dir $deplibs" test -n "$add" && deplibs="$add $deplibs" fi fi elif test "$linkmode" = prog; then # Here we assume that one of hardcode_direct or hardcode_minus_L # is not unsupported. This is valid on all known static and # shared platforms. if test "$hardcode_direct" != unsupported; then test -n "$old_library" && linklib="$old_library" compile_deplibs="$dir/$linklib $compile_deplibs" finalize_deplibs="$dir/$linklib $finalize_deplibs" else compile_deplibs="-l$name -L$dir $compile_deplibs" finalize_deplibs="-l$name -L$dir $finalize_deplibs" fi elif test "$build_libtool_libs" = yes; then # Not a shared library if test "$deplibs_check_method" != pass_all; then # We're trying link a shared library against a static one # but the system doesn't support it. # Just print a warning and add the library to dependency_libs so # that the program can be linked against the static library. echo $ECHO "*** Warning: This system can not link to static lib archive $lib." echo "*** I have the capability to make that library automatically link in when" echo "*** you link to this library. But I can only do this if you have a" echo "*** shared version of the library, which you do not appear to have." if test "$module" = yes; then echo "*** But as you try to build a module library, libtool will still create " echo "*** a static module, that should work as long as the dlopening application" echo "*** is linked with the -dlopen flag to resolve symbols at runtime." if test -z "$global_symbol_pipe"; then echo echo "*** However, this would only work if libtool was able to extract symbol" echo "*** lists from a program, using \`nm' or equivalent, but libtool could" echo "*** not find such a program. So, this module is probably useless." echo "*** \`nm' from GNU binutils and a full rebuild may help." fi if test "$build_old_libs" = no; then build_libtool_libs=module build_old_libs=yes else build_libtool_libs=no fi fi else deplibs="$dir/$old_library $deplibs" link_static=yes fi fi # link shared/static library? if test "$linkmode" = lib; then if test -n "$dependency_libs" && { test "$hardcode_into_libs" != yes || test "$build_old_libs" = yes || test "$link_static" = yes; }; then # Extract -R from dependency_libs temp_deplibs= for libdir in $dependency_libs; do case $libdir in -R*) func_stripname '-R' '' "$libdir" temp_xrpath=$func_stripname_result case " $xrpath " in *" $temp_xrpath "*) ;; *) func_append xrpath " $temp_xrpath";; esac;; *) func_append temp_deplibs " $libdir";; esac done dependency_libs="$temp_deplibs" fi func_append newlib_search_path " $absdir" # Link against this library test "$link_static" = no && newdependency_libs="$abs_ladir/$laname $newdependency_libs" # ... and its dependency_libs tmp_libs= for deplib in $dependency_libs; do newdependency_libs="$deplib $newdependency_libs" case $deplib in -L*) func_stripname '-L' '' "$deplib" func_resolve_sysroot "$func_stripname_result";; *) func_resolve_sysroot "$deplib" ;; esac if $opt_preserve_dup_deps ; then case "$tmp_libs " in *" $func_resolve_sysroot_result "*) func_append specialdeplibs " $func_resolve_sysroot_result" ;; esac fi func_append tmp_libs " $func_resolve_sysroot_result" done if test "$link_all_deplibs" != no; then # Add the search paths of all dependency libraries for deplib in $dependency_libs; do path= case $deplib in -L*) path="$deplib" ;; *.la) func_resolve_sysroot "$deplib" deplib=$func_resolve_sysroot_result func_dirname "$deplib" "" "." dir=$func_dirname_result # We need an absolute path. case $dir in [\\/]* | [A-Za-z]:[\\/]*) absdir="$dir" ;; *) absdir=`cd "$dir" && pwd` if test -z "$absdir"; then func_warning "cannot determine absolute directory name of \`$dir'" absdir="$dir" fi ;; esac if $GREP "^installed=no" $deplib > /dev/null; then case $host in *-*-darwin*) depdepl= eval deplibrary_names=`${SED} -n -e 's/^library_names=\(.*\)$/\1/p' $deplib` if test -n "$deplibrary_names" ; then for tmp in $deplibrary_names ; do depdepl=$tmp done if test -f "$absdir/$objdir/$depdepl" ; then depdepl="$absdir/$objdir/$depdepl" darwin_install_name=`${OTOOL} -L $depdepl | awk '{if (NR == 2) {print $1;exit}}'` if test -z "$darwin_install_name"; then darwin_install_name=`${OTOOL64} -L $depdepl | awk '{if (NR == 2) {print $1;exit}}'` fi func_append compiler_flags " ${wl}-dylib_file ${wl}${darwin_install_name}:${depdepl}" func_append linker_flags " -dylib_file ${darwin_install_name}:${depdepl}" path= fi fi ;; *) path="-L$absdir/$objdir" ;; esac else eval libdir=`${SED} -n -e 's/^libdir=\(.*\)$/\1/p' $deplib` test -z "$libdir" && \ func_fatal_error "\`$deplib' is not a valid libtool archive" test "$absdir" != "$libdir" && \ func_warning "\`$deplib' seems to be moved" path="-L$absdir" fi ;; esac case " $deplibs " in *" $path "*) ;; *) deplibs="$path $deplibs" ;; esac done fi # link_all_deplibs != no fi # linkmode = lib done # for deplib in $libs if test "$pass" = link; then if test "$linkmode" = "prog"; then compile_deplibs="$new_inherited_linker_flags $compile_deplibs" finalize_deplibs="$new_inherited_linker_flags $finalize_deplibs" else compiler_flags="$compiler_flags "`$ECHO " $new_inherited_linker_flags" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` fi fi dependency_libs="$newdependency_libs" if test "$pass" = dlpreopen; then # Link the dlpreopened libraries before other libraries for deplib in $save_deplibs; do deplibs="$deplib $deplibs" done fi if test "$pass" != dlopen; then if test "$pass" != conv; then # Make sure lib_search_path contains only unique directories. lib_search_path= for dir in $newlib_search_path; do case "$lib_search_path " in *" $dir "*) ;; *) func_append lib_search_path " $dir" ;; esac done newlib_search_path= fi if test "$linkmode,$pass" != "prog,link"; then vars="deplibs" else vars="compile_deplibs finalize_deplibs" fi for var in $vars dependency_libs; do # Add libraries to $var in reverse order eval tmp_libs=\"\$$var\" new_libs= for deplib in $tmp_libs; do # FIXME: Pedantically, this is the right thing to do, so # that some nasty dependency loop isn't accidentally # broken: #new_libs="$deplib $new_libs" # Pragmatically, this seems to cause very few problems in # practice: case $deplib in -L*) new_libs="$deplib $new_libs" ;; -R*) ;; *) # And here is the reason: when a library appears more # than once as an explicit dependence of a library, or # is implicitly linked in more than once by the # compiler, it is considered special, and multiple # occurrences thereof are not removed. Compare this # with having the same library being listed as a # dependency of multiple other libraries: in this case, # we know (pedantically, we assume) the library does not # need to be listed more than once, so we keep only the # last copy. This is not always right, but it is rare # enough that we require users that really mean to play # such unportable linking tricks to link the library # using -Wl,-lname, so that libtool does not consider it # for duplicate removal. case " $specialdeplibs " in *" $deplib "*) new_libs="$deplib $new_libs" ;; *) case " $new_libs " in *" $deplib "*) ;; *) new_libs="$deplib $new_libs" ;; esac ;; esac ;; esac done tmp_libs= for deplib in $new_libs; do case $deplib in -L*) case " $tmp_libs " in *" $deplib "*) ;; *) func_append tmp_libs " $deplib" ;; esac ;; *) func_append tmp_libs " $deplib" ;; esac done eval $var=\"$tmp_libs\" done # for var fi # Last step: remove runtime libs from dependency_libs # (they stay in deplibs) tmp_libs= for i in $dependency_libs ; do case " $predeps $postdeps $compiler_lib_search_path " in *" $i "*) i="" ;; esac if test -n "$i" ; then func_append tmp_libs " $i" fi done dependency_libs=$tmp_libs done # for pass if test "$linkmode" = prog; then dlfiles="$newdlfiles" fi if test "$linkmode" = prog || test "$linkmode" = lib; then dlprefiles="$newdlprefiles" fi case $linkmode in oldlib) if test -n "$dlfiles$dlprefiles" || test "$dlself" != no; then func_warning "\`-dlopen' is ignored for archives" fi case " $deplibs" in *\ -l* | *\ -L*) func_warning "\`-l' and \`-L' are ignored for archives" ;; esac test -n "$rpath" && \ func_warning "\`-rpath' is ignored for archives" test -n "$xrpath" && \ func_warning "\`-R' is ignored for archives" test -n "$vinfo" && \ func_warning "\`-version-info/-version-number' is ignored for archives" test -n "$release" && \ func_warning "\`-release' is ignored for archives" test -n "$export_symbols$export_symbols_regex" && \ func_warning "\`-export-symbols' is ignored for archives" # Now set the variables for building old libraries. build_libtool_libs=no oldlibs="$output" func_append objs "$old_deplibs" ;; lib) # Make sure we only generate libraries of the form `libNAME.la'. case $outputname in lib*) func_stripname 'lib' '.la' "$outputname" name=$func_stripname_result eval shared_ext=\"$shrext_cmds\" eval libname=\"$libname_spec\" ;; *) test "$module" = no && \ func_fatal_help "libtool library \`$output' must begin with \`lib'" if test "$need_lib_prefix" != no; then # Add the "lib" prefix for modules if required func_stripname '' '.la' "$outputname" name=$func_stripname_result eval shared_ext=\"$shrext_cmds\" eval libname=\"$libname_spec\" else func_stripname '' '.la' "$outputname" libname=$func_stripname_result fi ;; esac if test -n "$objs"; then if test "$deplibs_check_method" != pass_all; then func_fatal_error "cannot build libtool library \`$output' from non-libtool objects on this host:$objs" else echo $ECHO "*** Warning: Linking the shared library $output against the non-libtool" $ECHO "*** objects $objs is not portable!" func_append libobjs " $objs" fi fi test "$dlself" != no && \ func_warning "\`-dlopen self' is ignored for libtool libraries" set dummy $rpath shift test "$#" -gt 1 && \ func_warning "ignoring multiple \`-rpath's for a libtool library" install_libdir="$1" oldlibs= if test -z "$rpath"; then if test "$build_libtool_libs" = yes; then # Building a libtool convenience library. # Some compilers have problems with a `.al' extension so # convenience libraries should have the same extension an # archive normally would. oldlibs="$output_objdir/$libname.$libext $oldlibs" build_libtool_libs=convenience build_old_libs=yes fi test -n "$vinfo" && \ func_warning "\`-version-info/-version-number' is ignored for convenience libraries" test -n "$release" && \ func_warning "\`-release' is ignored for convenience libraries" else # Parse the version information argument. save_ifs="$IFS"; IFS=':' set dummy $vinfo 0 0 0 shift IFS="$save_ifs" test -n "$7" && \ func_fatal_help "too many parameters to \`-version-info'" # convert absolute version numbers to libtool ages # this retains compatibility with .la files and attempts # to make the code below a bit more comprehensible case $vinfo_number in yes) number_major="$1" number_minor="$2" number_revision="$3" # # There are really only two kinds -- those that # use the current revision as the major version # and those that subtract age and use age as # a minor version. But, then there is irix # which has an extra 1 added just for fun # case $version_type in # correct linux to gnu/linux during the next big refactor darwin|linux|osf|windows|none) func_arith $number_major + $number_minor current=$func_arith_result age="$number_minor" revision="$number_revision" ;; freebsd-aout|freebsd-elf|qnx|sunos) current="$number_major" revision="$number_minor" age="0" ;; irix|nonstopux) func_arith $number_major + $number_minor current=$func_arith_result age="$number_minor" revision="$number_minor" lt_irix_increment=no ;; esac ;; no) current="$1" revision="$2" age="$3" ;; esac # Check that each of the things are valid numbers. case $current in 0|[1-9]|[1-9][0-9]|[1-9][0-9][0-9]|[1-9][0-9][0-9][0-9]|[1-9][0-9][0-9][0-9][0-9]) ;; *) func_error "CURRENT \`$current' must be a nonnegative integer" func_fatal_error "\`$vinfo' is not valid version information" ;; esac case $revision in 0|[1-9]|[1-9][0-9]|[1-9][0-9][0-9]|[1-9][0-9][0-9][0-9]|[1-9][0-9][0-9][0-9][0-9]) ;; *) func_error "REVISION \`$revision' must be a nonnegative integer" func_fatal_error "\`$vinfo' is not valid version information" ;; esac case $age in 0|[1-9]|[1-9][0-9]|[1-9][0-9][0-9]|[1-9][0-9][0-9][0-9]|[1-9][0-9][0-9][0-9][0-9]) ;; *) func_error "AGE \`$age' must be a nonnegative integer" func_fatal_error "\`$vinfo' is not valid version information" ;; esac if test "$age" -gt "$current"; then func_error "AGE \`$age' is greater than the current interface number \`$current'" func_fatal_error "\`$vinfo' is not valid version information" fi # Calculate the version variables. major= versuffix= verstring= case $version_type in none) ;; darwin) # Like Linux, but with the current version available in # verstring for coding it into the library header func_arith $current - $age major=.$func_arith_result versuffix="$major.$age.$revision" # Darwin ld doesn't like 0 for these options... func_arith $current + 1 minor_current=$func_arith_result xlcverstring="${wl}-compatibility_version ${wl}$minor_current ${wl}-current_version ${wl}$minor_current.$revision" verstring="-compatibility_version $minor_current -current_version $minor_current.$revision" ;; freebsd-aout) major=".$current" versuffix=".$current.$revision"; ;; freebsd-elf) major=".$current" versuffix=".$current" ;; irix | nonstopux) if test "X$lt_irix_increment" = "Xno"; then func_arith $current - $age else func_arith $current - $age + 1 fi major=$func_arith_result case $version_type in nonstopux) verstring_prefix=nonstopux ;; *) verstring_prefix=sgi ;; esac verstring="$verstring_prefix$major.$revision" # Add in all the interfaces that we are compatible with. loop=$revision while test "$loop" -ne 0; do func_arith $revision - $loop iface=$func_arith_result func_arith $loop - 1 loop=$func_arith_result verstring="$verstring_prefix$major.$iface:$verstring" done # Before this point, $major must not contain `.'. major=.$major versuffix="$major.$revision" ;; linux) # correct to gnu/linux during the next big refactor func_arith $current - $age major=.$func_arith_result versuffix="$major.$age.$revision" ;; osf) func_arith $current - $age major=.$func_arith_result versuffix=".$current.$age.$revision" verstring="$current.$age.$revision" # Add in all the interfaces that we are compatible with. loop=$age while test "$loop" -ne 0; do func_arith $current - $loop iface=$func_arith_result func_arith $loop - 1 loop=$func_arith_result verstring="$verstring:${iface}.0" done # Make executables depend on our current version. func_append verstring ":${current}.0" ;; qnx) major=".$current" versuffix=".$current" ;; sunos) major=".$current" versuffix=".$current.$revision" ;; windows) # Use '-' rather than '.', since we only want one # extension on DOS 8.3 filesystems. func_arith $current - $age major=$func_arith_result versuffix="-$major" ;; *) func_fatal_configuration "unknown library version type \`$version_type'" ;; esac # Clear the version info if we defaulted, and they specified a release. if test -z "$vinfo" && test -n "$release"; then major= case $version_type in darwin) # we can't check for "0.0" in archive_cmds due to quoting # problems, so we reset it completely verstring= ;; *) verstring="0.0" ;; esac if test "$need_version" = no; then versuffix= else versuffix=".0.0" fi fi # Remove version info from name if versioning should be avoided if test "$avoid_version" = yes && test "$need_version" = no; then major= versuffix= verstring="" fi # Check to see if the archive will have undefined symbols. if test "$allow_undefined" = yes; then if test "$allow_undefined_flag" = unsupported; then func_warning "undefined symbols not allowed in $host shared libraries" build_libtool_libs=no build_old_libs=yes fi else # Don't allow undefined symbols. allow_undefined_flag="$no_undefined_flag" fi fi func_generate_dlsyms "$libname" "$libname" "yes" func_append libobjs " $symfileobj" test "X$libobjs" = "X " && libobjs= if test "$opt_mode" != relink; then # Remove our outputs, but don't remove object files since they # may have been created when compiling PIC objects. removelist= tempremovelist=`$ECHO "$output_objdir/*"` for p in $tempremovelist; do case $p in *.$objext | *.gcno) ;; $output_objdir/$outputname | $output_objdir/$libname.* | $output_objdir/${libname}${release}.*) if test "X$precious_files_regex" != "X"; then if $ECHO "$p" | $EGREP -e "$precious_files_regex" >/dev/null 2>&1 then continue fi fi func_append removelist " $p" ;; *) ;; esac done test -n "$removelist" && \ func_show_eval "${RM}r \$removelist" fi # Now set the variables for building old libraries. if test "$build_old_libs" = yes && test "$build_libtool_libs" != convenience ; then func_append oldlibs " $output_objdir/$libname.$libext" # Transform .lo files to .o files. oldobjs="$objs "`$ECHO "$libobjs" | $SP2NL | $SED "/\.${libext}$/d; $lo2o" | $NL2SP` fi # Eliminate all temporary directories. #for path in $notinst_path; do # lib_search_path=`$ECHO "$lib_search_path " | $SED "s% $path % %g"` # deplibs=`$ECHO "$deplibs " | $SED "s% -L$path % %g"` # dependency_libs=`$ECHO "$dependency_libs " | $SED "s% -L$path % %g"` #done if test -n "$xrpath"; then # If the user specified any rpath flags, then add them. temp_xrpath= for libdir in $xrpath; do func_replace_sysroot "$libdir" func_append temp_xrpath " -R$func_replace_sysroot_result" case "$finalize_rpath " in *" $libdir "*) ;; *) func_append finalize_rpath " $libdir" ;; esac done if test "$hardcode_into_libs" != yes || test "$build_old_libs" = yes; then dependency_libs="$temp_xrpath $dependency_libs" fi fi # Make sure dlfiles contains only unique files that won't be dlpreopened old_dlfiles="$dlfiles" dlfiles= for lib in $old_dlfiles; do case " $dlprefiles $dlfiles " in *" $lib "*) ;; *) func_append dlfiles " $lib" ;; esac done # Make sure dlprefiles contains only unique files old_dlprefiles="$dlprefiles" dlprefiles= for lib in $old_dlprefiles; do case "$dlprefiles " in *" $lib "*) ;; *) func_append dlprefiles " $lib" ;; esac done if test "$build_libtool_libs" = yes; then if test -n "$rpath"; then case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2* | *-*-beos* | *-cegcc* | *-*-haiku*) # these systems don't actually have a c library (as such)! ;; *-*-rhapsody* | *-*-darwin1.[012]) # Rhapsody C library is in the System framework func_append deplibs " System.ltframework" ;; *-*-netbsd*) # Don't link with libc until the a.out ld.so is fixed. ;; *-*-openbsd* | *-*-freebsd* | *-*-dragonfly*) # Do not include libc due to us having libc/libc_r. ;; *-*-sco3.2v5* | *-*-sco5v6*) # Causes problems with __ctype ;; *-*-sysv4.2uw2* | *-*-sysv5* | *-*-unixware* | *-*-OpenUNIX*) # Compiler inserts libc in the correct place for threads to work ;; *) # Add libc to deplibs on all other systems if necessary. if test "$build_libtool_need_lc" = "yes"; then func_append deplibs " -lc" fi ;; esac fi # Transform deplibs into only deplibs that can be linked in shared. name_save=$name libname_save=$libname release_save=$release versuffix_save=$versuffix major_save=$major # I'm not sure if I'm treating the release correctly. I think # release should show up in the -l (ie -lgmp5) so we don't want to # add it in twice. Is that correct? release="" versuffix="" major="" newdeplibs= droppeddeps=no case $deplibs_check_method in pass_all) # Don't check for shared/static. Everything works. # This might be a little naive. We might want to check # whether the library exists or not. But this is on # osf3 & osf4 and I'm not really sure... Just # implementing what was already the behavior. newdeplibs=$deplibs ;; test_compile) # This code stresses the "libraries are programs" paradigm to its # limits. Maybe even breaks it. We compile a program, linking it # against the deplibs as a proxy for the library. Then we can check # whether they linked in statically or dynamically with ldd. $opt_dry_run || $RM conftest.c cat > conftest.c </dev/null` $nocaseglob else potential_libs=`ls $i/$libnameglob[.-]* 2>/dev/null` fi for potent_lib in $potential_libs; do # Follow soft links. if ls -lLd "$potent_lib" 2>/dev/null | $GREP " -> " >/dev/null; then continue fi # The statement above tries to avoid entering an # endless loop below, in case of cyclic links. # We might still enter an endless loop, since a link # loop can be closed while we follow links, # but so what? potlib="$potent_lib" while test -h "$potlib" 2>/dev/null; do potliblink=`ls -ld $potlib | ${SED} 's/.* -> //'` case $potliblink in [\\/]* | [A-Za-z]:[\\/]*) potlib="$potliblink";; *) potlib=`$ECHO "$potlib" | $SED 's,[^/]*$,,'`"$potliblink";; esac done if eval $file_magic_cmd \"\$potlib\" 2>/dev/null | $SED -e 10q | $EGREP "$file_magic_regex" > /dev/null; then func_append newdeplibs " $a_deplib" a_deplib="" break 2 fi done done fi if test -n "$a_deplib" ; then droppeddeps=yes echo $ECHO "*** Warning: linker path does not have real file for library $a_deplib." echo "*** I have the capability to make that library automatically link in when" echo "*** you link to this library. But I can only do this if you have a" echo "*** shared version of the library, which you do not appear to have" echo "*** because I did check the linker path looking for a file starting" if test -z "$potlib" ; then $ECHO "*** with $libname but no candidates were found. (...for file magic test)" else $ECHO "*** with $libname and none of the candidates passed a file format test" $ECHO "*** using a file magic. Last file checked: $potlib" fi fi ;; *) # Add a -L argument. func_append newdeplibs " $a_deplib" ;; esac done # Gone through all deplibs. ;; match_pattern*) set dummy $deplibs_check_method; shift match_pattern_regex=`expr "$deplibs_check_method" : "$1 \(.*\)"` for a_deplib in $deplibs; do case $a_deplib in -l*) func_stripname -l '' "$a_deplib" name=$func_stripname_result if test "X$allow_libtool_libs_with_static_runtimes" = "Xyes" ; then case " $predeps $postdeps " in *" $a_deplib "*) func_append newdeplibs " $a_deplib" a_deplib="" ;; esac fi if test -n "$a_deplib" ; then libname=`eval "\\$ECHO \"$libname_spec\""` for i in $lib_search_path $sys_lib_search_path $shlib_search_path; do potential_libs=`ls $i/$libname[.-]* 2>/dev/null` for potent_lib in $potential_libs; do potlib="$potent_lib" # see symlink-check above in file_magic test if eval "\$ECHO \"$potent_lib\"" 2>/dev/null | $SED 10q | \ $EGREP "$match_pattern_regex" > /dev/null; then func_append newdeplibs " $a_deplib" a_deplib="" break 2 fi done done fi if test -n "$a_deplib" ; then droppeddeps=yes echo $ECHO "*** Warning: linker path does not have real file for library $a_deplib." echo "*** I have the capability to make that library automatically link in when" echo "*** you link to this library. But I can only do this if you have a" echo "*** shared version of the library, which you do not appear to have" echo "*** because I did check the linker path looking for a file starting" if test -z "$potlib" ; then $ECHO "*** with $libname but no candidates were found. (...for regex pattern test)" else $ECHO "*** with $libname and none of the candidates passed a file format test" $ECHO "*** using a regex pattern. Last file checked: $potlib" fi fi ;; *) # Add a -L argument. func_append newdeplibs " $a_deplib" ;; esac done # Gone through all deplibs. ;; none | unknown | *) newdeplibs="" tmp_deplibs=`$ECHO " $deplibs" | $SED 's/ -lc$//; s/ -[LR][^ ]*//g'` if test "X$allow_libtool_libs_with_static_runtimes" = "Xyes" ; then for i in $predeps $postdeps ; do # can't use Xsed below, because $i might contain '/' tmp_deplibs=`$ECHO " $tmp_deplibs" | $SED "s,$i,,"` done fi case $tmp_deplibs in *[!\ \ ]*) echo if test "X$deplibs_check_method" = "Xnone"; then echo "*** Warning: inter-library dependencies are not supported in this platform." else echo "*** Warning: inter-library dependencies are not known to be supported." fi echo "*** All declared inter-library dependencies are being dropped." droppeddeps=yes ;; esac ;; esac versuffix=$versuffix_save major=$major_save release=$release_save libname=$libname_save name=$name_save case $host in *-*-rhapsody* | *-*-darwin1.[012]) # On Rhapsody replace the C library with the System framework newdeplibs=`$ECHO " $newdeplibs" | $SED 's/ -lc / System.ltframework /'` ;; esac if test "$droppeddeps" = yes; then if test "$module" = yes; then echo echo "*** Warning: libtool could not satisfy all declared inter-library" $ECHO "*** dependencies of module $libname. Therefore, libtool will create" echo "*** a static module, that should work as long as the dlopening" echo "*** application is linked with the -dlopen flag." if test -z "$global_symbol_pipe"; then echo echo "*** However, this would only work if libtool was able to extract symbol" echo "*** lists from a program, using \`nm' or equivalent, but libtool could" echo "*** not find such a program. So, this module is probably useless." echo "*** \`nm' from GNU binutils and a full rebuild may help." fi if test "$build_old_libs" = no; then oldlibs="$output_objdir/$libname.$libext" build_libtool_libs=module build_old_libs=yes else build_libtool_libs=no fi else echo "*** The inter-library dependencies that have been dropped here will be" echo "*** automatically added whenever a program is linked with this library" echo "*** or is declared to -dlopen it." if test "$allow_undefined" = no; then echo echo "*** Since this library must not contain undefined symbols," echo "*** because either the platform does not support them or" echo "*** it was explicitly requested with -no-undefined," echo "*** libtool will only create a static version of it." if test "$build_old_libs" = no; then oldlibs="$output_objdir/$libname.$libext" build_libtool_libs=module build_old_libs=yes else build_libtool_libs=no fi fi fi fi # Done checking deplibs! deplibs=$newdeplibs fi # Time to change all our "foo.ltframework" stuff back to "-framework foo" case $host in *-*-darwin*) newdeplibs=`$ECHO " $newdeplibs" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` new_inherited_linker_flags=`$ECHO " $new_inherited_linker_flags" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` deplibs=`$ECHO " $deplibs" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` ;; esac # move library search paths that coincide with paths to not yet # installed libraries to the beginning of the library search list new_libs= for path in $notinst_path; do case " $new_libs " in *" -L$path/$objdir "*) ;; *) case " $deplibs " in *" -L$path/$objdir "*) func_append new_libs " -L$path/$objdir" ;; esac ;; esac done for deplib in $deplibs; do case $deplib in -L*) case " $new_libs " in *" $deplib "*) ;; *) func_append new_libs " $deplib" ;; esac ;; *) func_append new_libs " $deplib" ;; esac done deplibs="$new_libs" # All the library-specific variables (install_libdir is set above). library_names= old_library= dlname= # Test again, we may have decided not to build it any more if test "$build_libtool_libs" = yes; then # Remove ${wl} instances when linking with ld. # FIXME: should test the right _cmds variable. case $archive_cmds in *\$LD\ *) wl= ;; esac if test "$hardcode_into_libs" = yes; then # Hardcode the library paths hardcode_libdirs= dep_rpath= rpath="$finalize_rpath" test "$opt_mode" != relink && rpath="$compile_rpath$rpath" for libdir in $rpath; do if test -n "$hardcode_libdir_flag_spec"; then if test -n "$hardcode_libdir_separator"; then func_replace_sysroot "$libdir" libdir=$func_replace_sysroot_result if test -z "$hardcode_libdirs"; then hardcode_libdirs="$libdir" else # Just accumulate the unique libdirs. case $hardcode_libdir_separator$hardcode_libdirs$hardcode_libdir_separator in *"$hardcode_libdir_separator$libdir$hardcode_libdir_separator"*) ;; *) func_append hardcode_libdirs "$hardcode_libdir_separator$libdir" ;; esac fi else eval flag=\"$hardcode_libdir_flag_spec\" func_append dep_rpath " $flag" fi elif test -n "$runpath_var"; then case "$perm_rpath " in *" $libdir "*) ;; *) func_append perm_rpath " $libdir" ;; esac fi done # Substitute the hardcoded libdirs into the rpath. if test -n "$hardcode_libdir_separator" && test -n "$hardcode_libdirs"; then libdir="$hardcode_libdirs" eval "dep_rpath=\"$hardcode_libdir_flag_spec\"" fi if test -n "$runpath_var" && test -n "$perm_rpath"; then # We should set the runpath_var. rpath= for dir in $perm_rpath; do func_append rpath "$dir:" done eval "$runpath_var='$rpath\$$runpath_var'; export $runpath_var" fi test -n "$dep_rpath" && deplibs="$dep_rpath $deplibs" fi shlibpath="$finalize_shlibpath" test "$opt_mode" != relink && shlibpath="$compile_shlibpath$shlibpath" if test -n "$shlibpath"; then eval "$shlibpath_var='$shlibpath\$$shlibpath_var'; export $shlibpath_var" fi # Get the real and link names of the library. eval shared_ext=\"$shrext_cmds\" eval library_names=\"$library_names_spec\" set dummy $library_names shift realname="$1" shift if test -n "$soname_spec"; then eval soname=\"$soname_spec\" else soname="$realname" fi if test -z "$dlname"; then dlname=$soname fi lib="$output_objdir/$realname" linknames= for link do func_append linknames " $link" done # Use standard objects if they are pic test -z "$pic_flag" && libobjs=`$ECHO "$libobjs" | $SP2NL | $SED "$lo2o" | $NL2SP` test "X$libobjs" = "X " && libobjs= delfiles= if test -n "$export_symbols" && test -n "$include_expsyms"; then $opt_dry_run || cp "$export_symbols" "$output_objdir/$libname.uexp" export_symbols="$output_objdir/$libname.uexp" func_append delfiles " $export_symbols" fi orig_export_symbols= case $host_os in cygwin* | mingw* | cegcc*) if test -n "$export_symbols" && test -z "$export_symbols_regex"; then # exporting using user supplied symfile if test "x`$SED 1q $export_symbols`" != xEXPORTS; then # and it's NOT already a .def file. Must figure out # which of the given symbols are data symbols and tag # them as such. So, trigger use of export_symbols_cmds. # export_symbols gets reassigned inside the "prepare # the list of exported symbols" if statement, so the # include_expsyms logic still works. orig_export_symbols="$export_symbols" export_symbols= always_export_symbols=yes fi fi ;; esac # Prepare the list of exported symbols if test -z "$export_symbols"; then if test "$always_export_symbols" = yes || test -n "$export_symbols_regex"; then func_verbose "generating symbol list for \`$libname.la'" export_symbols="$output_objdir/$libname.exp" $opt_dry_run || $RM $export_symbols cmds=$export_symbols_cmds save_ifs="$IFS"; IFS='~' for cmd1 in $cmds; do IFS="$save_ifs" # Take the normal branch if the nm_file_list_spec branch # doesn't work or if tool conversion is not needed. case $nm_file_list_spec~$to_tool_file_cmd in *~func_convert_file_noop | *~func_convert_file_msys_to_w32 | ~*) try_normal_branch=yes eval cmd=\"$cmd1\" func_len " $cmd" len=$func_len_result ;; *) try_normal_branch=no ;; esac if test "$try_normal_branch" = yes \ && { test "$len" -lt "$max_cmd_len" \ || test "$max_cmd_len" -le -1; } then func_show_eval "$cmd" 'exit $?' skipped_export=false elif test -n "$nm_file_list_spec"; then func_basename "$output" output_la=$func_basename_result save_libobjs=$libobjs save_output=$output output=${output_objdir}/${output_la}.nm func_to_tool_file "$output" libobjs=$nm_file_list_spec$func_to_tool_file_result func_append delfiles " $output" func_verbose "creating $NM input file list: $output" for obj in $save_libobjs; do func_to_tool_file "$obj" $ECHO "$func_to_tool_file_result" done > "$output" eval cmd=\"$cmd1\" func_show_eval "$cmd" 'exit $?' output=$save_output libobjs=$save_libobjs skipped_export=false else # The command line is too long to execute in one step. func_verbose "using reloadable object file for export list..." skipped_export=: # Break out early, otherwise skipped_export may be # set to false by a later but shorter cmd. break fi done IFS="$save_ifs" if test -n "$export_symbols_regex" && test "X$skipped_export" != "X:"; then func_show_eval '$EGREP -e "$export_symbols_regex" "$export_symbols" > "${export_symbols}T"' func_show_eval '$MV "${export_symbols}T" "$export_symbols"' fi fi fi if test -n "$export_symbols" && test -n "$include_expsyms"; then tmp_export_symbols="$export_symbols" test -n "$orig_export_symbols" && tmp_export_symbols="$orig_export_symbols" $opt_dry_run || eval '$ECHO "$include_expsyms" | $SP2NL >> "$tmp_export_symbols"' fi if test "X$skipped_export" != "X:" && test -n "$orig_export_symbols"; then # The given exports_symbols file has to be filtered, so filter it. func_verbose "filter symbol list for \`$libname.la' to tag DATA exports" # FIXME: $output_objdir/$libname.filter potentially contains lots of # 's' commands which not all seds can handle. GNU sed should be fine # though. Also, the filter scales superlinearly with the number of # global variables. join(1) would be nice here, but unfortunately # isn't a blessed tool. $opt_dry_run || $SED -e '/[ ,]DATA/!d;s,\(.*\)\([ \,].*\),s|^\1$|\1\2|,' < $export_symbols > $output_objdir/$libname.filter func_append delfiles " $export_symbols $output_objdir/$libname.filter" export_symbols=$output_objdir/$libname.def $opt_dry_run || $SED -f $output_objdir/$libname.filter < $orig_export_symbols > $export_symbols fi tmp_deplibs= for test_deplib in $deplibs; do case " $convenience " in *" $test_deplib "*) ;; *) func_append tmp_deplibs " $test_deplib" ;; esac done deplibs="$tmp_deplibs" if test -n "$convenience"; then if test -n "$whole_archive_flag_spec" && test "$compiler_needs_object" = yes && test -z "$libobjs"; then # extract the archives, so we have objects to list. # TODO: could optimize this to just extract one archive. whole_archive_flag_spec= fi if test -n "$whole_archive_flag_spec"; then save_libobjs=$libobjs eval libobjs=\"\$libobjs $whole_archive_flag_spec\" test "X$libobjs" = "X " && libobjs= else gentop="$output_objdir/${outputname}x" func_append generated " $gentop" func_extract_archives $gentop $convenience func_append libobjs " $func_extract_archives_result" test "X$libobjs" = "X " && libobjs= fi fi if test "$thread_safe" = yes && test -n "$thread_safe_flag_spec"; then eval flag=\"$thread_safe_flag_spec\" func_append linker_flags " $flag" fi # Make a backup of the uninstalled library when relinking if test "$opt_mode" = relink; then $opt_dry_run || eval '(cd $output_objdir && $RM ${realname}U && $MV $realname ${realname}U)' || exit $? fi # Do each of the archive commands. if test "$module" = yes && test -n "$module_cmds" ; then if test -n "$export_symbols" && test -n "$module_expsym_cmds"; then eval test_cmds=\"$module_expsym_cmds\" cmds=$module_expsym_cmds else eval test_cmds=\"$module_cmds\" cmds=$module_cmds fi else if test -n "$export_symbols" && test -n "$archive_expsym_cmds"; then eval test_cmds=\"$archive_expsym_cmds\" cmds=$archive_expsym_cmds else eval test_cmds=\"$archive_cmds\" cmds=$archive_cmds fi fi if test "X$skipped_export" != "X:" && func_len " $test_cmds" && len=$func_len_result && test "$len" -lt "$max_cmd_len" || test "$max_cmd_len" -le -1; then : else # The command line is too long to link in one step, link piecewise # or, if using GNU ld and skipped_export is not :, use a linker # script. # Save the value of $output and $libobjs because we want to # use them later. If we have whole_archive_flag_spec, we # want to use save_libobjs as it was before # whole_archive_flag_spec was expanded, because we can't # assume the linker understands whole_archive_flag_spec. # This may have to be revisited, in case too many # convenience libraries get linked in and end up exceeding # the spec. if test -z "$convenience" || test -z "$whole_archive_flag_spec"; then save_libobjs=$libobjs fi save_output=$output func_basename "$output" output_la=$func_basename_result # Clear the reloadable object creation command queue and # initialize k to one. test_cmds= concat_cmds= objlist= last_robj= k=1 if test -n "$save_libobjs" && test "X$skipped_export" != "X:" && test "$with_gnu_ld" = yes; then output=${output_objdir}/${output_la}.lnkscript func_verbose "creating GNU ld script: $output" echo 'INPUT (' > $output for obj in $save_libobjs do func_to_tool_file "$obj" $ECHO "$func_to_tool_file_result" >> $output done echo ')' >> $output func_append delfiles " $output" func_to_tool_file "$output" output=$func_to_tool_file_result elif test -n "$save_libobjs" && test "X$skipped_export" != "X:" && test "X$file_list_spec" != X; then output=${output_objdir}/${output_la}.lnk func_verbose "creating linker input file list: $output" : > $output set x $save_libobjs shift firstobj= if test "$compiler_needs_object" = yes; then firstobj="$1 " shift fi for obj do func_to_tool_file "$obj" $ECHO "$func_to_tool_file_result" >> $output done func_append delfiles " $output" func_to_tool_file "$output" output=$firstobj\"$file_list_spec$func_to_tool_file_result\" else if test -n "$save_libobjs"; then func_verbose "creating reloadable object files..." output=$output_objdir/$output_la-${k}.$objext eval test_cmds=\"$reload_cmds\" func_len " $test_cmds" len0=$func_len_result len=$len0 # Loop over the list of objects to be linked. for obj in $save_libobjs do func_len " $obj" func_arith $len + $func_len_result len=$func_arith_result if test "X$objlist" = X || test "$len" -lt "$max_cmd_len"; then func_append objlist " $obj" else # The command $test_cmds is almost too long, add a # command to the queue. if test "$k" -eq 1 ; then # The first file doesn't have a previous command to add. reload_objs=$objlist eval concat_cmds=\"$reload_cmds\" else # All subsequent reloadable object files will link in # the last one created. reload_objs="$objlist $last_robj" eval concat_cmds=\"\$concat_cmds~$reload_cmds~\$RM $last_robj\" fi last_robj=$output_objdir/$output_la-${k}.$objext func_arith $k + 1 k=$func_arith_result output=$output_objdir/$output_la-${k}.$objext objlist=" $obj" func_len " $last_robj" func_arith $len0 + $func_len_result len=$func_arith_result fi done # Handle the remaining objects by creating one last # reloadable object file. All subsequent reloadable object # files will link in the last one created. test -z "$concat_cmds" || concat_cmds=$concat_cmds~ reload_objs="$objlist $last_robj" eval concat_cmds=\"\${concat_cmds}$reload_cmds\" if test -n "$last_robj"; then eval concat_cmds=\"\${concat_cmds}~\$RM $last_robj\" fi func_append delfiles " $output" else output= fi if ${skipped_export-false}; then func_verbose "generating symbol list for \`$libname.la'" export_symbols="$output_objdir/$libname.exp" $opt_dry_run || $RM $export_symbols libobjs=$output # Append the command to create the export file. test -z "$concat_cmds" || concat_cmds=$concat_cmds~ eval concat_cmds=\"\$concat_cmds$export_symbols_cmds\" if test -n "$last_robj"; then eval concat_cmds=\"\$concat_cmds~\$RM $last_robj\" fi fi test -n "$save_libobjs" && func_verbose "creating a temporary reloadable object file: $output" # Loop through the commands generated above and execute them. save_ifs="$IFS"; IFS='~' for cmd in $concat_cmds; do IFS="$save_ifs" $opt_silent || { func_quote_for_expand "$cmd" eval "func_echo $func_quote_for_expand_result" } $opt_dry_run || eval "$cmd" || { lt_exit=$? # Restore the uninstalled library and exit if test "$opt_mode" = relink; then ( cd "$output_objdir" && \ $RM "${realname}T" && \ $MV "${realname}U" "$realname" ) fi exit $lt_exit } done IFS="$save_ifs" if test -n "$export_symbols_regex" && ${skipped_export-false}; then func_show_eval '$EGREP -e "$export_symbols_regex" "$export_symbols" > "${export_symbols}T"' func_show_eval '$MV "${export_symbols}T" "$export_symbols"' fi fi if ${skipped_export-false}; then if test -n "$export_symbols" && test -n "$include_expsyms"; then tmp_export_symbols="$export_symbols" test -n "$orig_export_symbols" && tmp_export_symbols="$orig_export_symbols" $opt_dry_run || eval '$ECHO "$include_expsyms" | $SP2NL >> "$tmp_export_symbols"' fi if test -n "$orig_export_symbols"; then # The given exports_symbols file has to be filtered, so filter it. func_verbose "filter symbol list for \`$libname.la' to tag DATA exports" # FIXME: $output_objdir/$libname.filter potentially contains lots of # 's' commands which not all seds can handle. GNU sed should be fine # though. Also, the filter scales superlinearly with the number of # global variables. join(1) would be nice here, but unfortunately # isn't a blessed tool. $opt_dry_run || $SED -e '/[ ,]DATA/!d;s,\(.*\)\([ \,].*\),s|^\1$|\1\2|,' < $export_symbols > $output_objdir/$libname.filter func_append delfiles " $export_symbols $output_objdir/$libname.filter" export_symbols=$output_objdir/$libname.def $opt_dry_run || $SED -f $output_objdir/$libname.filter < $orig_export_symbols > $export_symbols fi fi libobjs=$output # Restore the value of output. output=$save_output if test -n "$convenience" && test -n "$whole_archive_flag_spec"; then eval libobjs=\"\$libobjs $whole_archive_flag_spec\" test "X$libobjs" = "X " && libobjs= fi # Expand the library linking commands again to reset the # value of $libobjs for piecewise linking. # Do each of the archive commands. if test "$module" = yes && test -n "$module_cmds" ; then if test -n "$export_symbols" && test -n "$module_expsym_cmds"; then cmds=$module_expsym_cmds else cmds=$module_cmds fi else if test -n "$export_symbols" && test -n "$archive_expsym_cmds"; then cmds=$archive_expsym_cmds else cmds=$archive_cmds fi fi fi if test -n "$delfiles"; then # Append the command to remove temporary files to $cmds. eval cmds=\"\$cmds~\$RM $delfiles\" fi # Add any objects from preloaded convenience libraries if test -n "$dlprefiles"; then gentop="$output_objdir/${outputname}x" func_append generated " $gentop" func_extract_archives $gentop $dlprefiles func_append libobjs " $func_extract_archives_result" test "X$libobjs" = "X " && libobjs= fi save_ifs="$IFS"; IFS='~' for cmd in $cmds; do IFS="$save_ifs" eval cmd=\"$cmd\" $opt_silent || { func_quote_for_expand "$cmd" eval "func_echo $func_quote_for_expand_result" } $opt_dry_run || eval "$cmd" || { lt_exit=$? # Restore the uninstalled library and exit if test "$opt_mode" = relink; then ( cd "$output_objdir" && \ $RM "${realname}T" && \ $MV "${realname}U" "$realname" ) fi exit $lt_exit } done IFS="$save_ifs" # Restore the uninstalled library and exit if test "$opt_mode" = relink; then $opt_dry_run || eval '(cd $output_objdir && $RM ${realname}T && $MV $realname ${realname}T && $MV ${realname}U $realname)' || exit $? if test -n "$convenience"; then if test -z "$whole_archive_flag_spec"; then func_show_eval '${RM}r "$gentop"' fi fi exit $EXIT_SUCCESS fi # Create links to the real library. for linkname in $linknames; do if test "$realname" != "$linkname"; then func_show_eval '(cd "$output_objdir" && $RM "$linkname" && $LN_S "$realname" "$linkname")' 'exit $?' fi done # If -module or -export-dynamic was specified, set the dlname. if test "$module" = yes || test "$export_dynamic" = yes; then # On all known operating systems, these are identical. dlname="$soname" fi fi ;; obj) if test -n "$dlfiles$dlprefiles" || test "$dlself" != no; then func_warning "\`-dlopen' is ignored for objects" fi case " $deplibs" in *\ -l* | *\ -L*) func_warning "\`-l' and \`-L' are ignored for objects" ;; esac test -n "$rpath" && \ func_warning "\`-rpath' is ignored for objects" test -n "$xrpath" && \ func_warning "\`-R' is ignored for objects" test -n "$vinfo" && \ func_warning "\`-version-info' is ignored for objects" test -n "$release" && \ func_warning "\`-release' is ignored for objects" case $output in *.lo) test -n "$objs$old_deplibs" && \ func_fatal_error "cannot build library object \`$output' from non-libtool objects" libobj=$output func_lo2o "$libobj" obj=$func_lo2o_result ;; *) libobj= obj="$output" ;; esac # Delete the old objects. $opt_dry_run || $RM $obj $libobj # Objects from convenience libraries. This assumes # single-version convenience libraries. Whenever we create # different ones for PIC/non-PIC, this we'll have to duplicate # the extraction. reload_conv_objs= gentop= # reload_cmds runs $LD directly, so let us get rid of # -Wl from whole_archive_flag_spec and hope we can get by with # turning comma into space.. wl= if test -n "$convenience"; then if test -n "$whole_archive_flag_spec"; then eval tmp_whole_archive_flags=\"$whole_archive_flag_spec\" reload_conv_objs=$reload_objs\ `$ECHO "$tmp_whole_archive_flags" | $SED 's|,| |g'` else gentop="$output_objdir/${obj}x" func_append generated " $gentop" func_extract_archives $gentop $convenience reload_conv_objs="$reload_objs $func_extract_archives_result" fi fi # If we're not building shared, we need to use non_pic_objs test "$build_libtool_libs" != yes && libobjs="$non_pic_objects" # Create the old-style object. reload_objs="$objs$old_deplibs "`$ECHO "$libobjs" | $SP2NL | $SED "/\.${libext}$/d; /\.lib$/d; $lo2o" | $NL2SP`" $reload_conv_objs" ### testsuite: skip nested quoting test output="$obj" func_execute_cmds "$reload_cmds" 'exit $?' # Exit if we aren't doing a library object file. if test -z "$libobj"; then if test -n "$gentop"; then func_show_eval '${RM}r "$gentop"' fi exit $EXIT_SUCCESS fi if test "$build_libtool_libs" != yes; then if test -n "$gentop"; then func_show_eval '${RM}r "$gentop"' fi # Create an invalid libtool object if no PIC, so that we don't # accidentally link it into a program. # $show "echo timestamp > $libobj" # $opt_dry_run || eval "echo timestamp > $libobj" || exit $? exit $EXIT_SUCCESS fi if test -n "$pic_flag" || test "$pic_mode" != default; then # Only do commands if we really have different PIC objects. reload_objs="$libobjs $reload_conv_objs" output="$libobj" func_execute_cmds "$reload_cmds" 'exit $?' fi if test -n "$gentop"; then func_show_eval '${RM}r "$gentop"' fi exit $EXIT_SUCCESS ;; prog) case $host in *cygwin*) func_stripname '' '.exe' "$output" output=$func_stripname_result.exe;; esac test -n "$vinfo" && \ func_warning "\`-version-info' is ignored for programs" test -n "$release" && \ func_warning "\`-release' is ignored for programs" test "$preload" = yes \ && test "$dlopen_support" = unknown \ && test "$dlopen_self" = unknown \ && test "$dlopen_self_static" = unknown && \ func_warning "\`LT_INIT([dlopen])' not used. Assuming no dlopen support." case $host in *-*-rhapsody* | *-*-darwin1.[012]) # On Rhapsody replace the C library is the System framework compile_deplibs=`$ECHO " $compile_deplibs" | $SED 's/ -lc / System.ltframework /'` finalize_deplibs=`$ECHO " $finalize_deplibs" | $SED 's/ -lc / System.ltframework /'` ;; esac case $host in *-*-darwin*) # Don't allow lazy linking, it breaks C++ global constructors # But is supposedly fixed on 10.4 or later (yay!). if test "$tagname" = CXX ; then case ${MACOSX_DEPLOYMENT_TARGET-10.0} in 10.[0123]) func_append compile_command " ${wl}-bind_at_load" func_append finalize_command " ${wl}-bind_at_load" ;; esac fi # Time to change all our "foo.ltframework" stuff back to "-framework foo" compile_deplibs=`$ECHO " $compile_deplibs" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` finalize_deplibs=`$ECHO " $finalize_deplibs" | $SED 's% \([^ $]*\).ltframework% -framework \1%g'` ;; esac # move library search paths that coincide with paths to not yet # installed libraries to the beginning of the library search list new_libs= for path in $notinst_path; do case " $new_libs " in *" -L$path/$objdir "*) ;; *) case " $compile_deplibs " in *" -L$path/$objdir "*) func_append new_libs " -L$path/$objdir" ;; esac ;; esac done for deplib in $compile_deplibs; do case $deplib in -L*) case " $new_libs " in *" $deplib "*) ;; *) func_append new_libs " $deplib" ;; esac ;; *) func_append new_libs " $deplib" ;; esac done compile_deplibs="$new_libs" func_append compile_command " $compile_deplibs" func_append finalize_command " $finalize_deplibs" if test -n "$rpath$xrpath"; then # If the user specified any rpath flags, then add them. for libdir in $rpath $xrpath; do # This is the magic to use -rpath. case "$finalize_rpath " in *" $libdir "*) ;; *) func_append finalize_rpath " $libdir" ;; esac done fi # Now hardcode the library paths rpath= hardcode_libdirs= for libdir in $compile_rpath $finalize_rpath; do if test -n "$hardcode_libdir_flag_spec"; then if test -n "$hardcode_libdir_separator"; then if test -z "$hardcode_libdirs"; then hardcode_libdirs="$libdir" else # Just accumulate the unique libdirs. case $hardcode_libdir_separator$hardcode_libdirs$hardcode_libdir_separator in *"$hardcode_libdir_separator$libdir$hardcode_libdir_separator"*) ;; *) func_append hardcode_libdirs "$hardcode_libdir_separator$libdir" ;; esac fi else eval flag=\"$hardcode_libdir_flag_spec\" func_append rpath " $flag" fi elif test -n "$runpath_var"; then case "$perm_rpath " in *" $libdir "*) ;; *) func_append perm_rpath " $libdir" ;; esac fi case $host in *-*-cygwin* | *-*-mingw* | *-*-pw32* | *-*-os2* | *-cegcc*) testbindir=`${ECHO} "$libdir" | ${SED} -e 's*/lib$*/bin*'` case :$dllsearchpath: in *":$libdir:"*) ;; ::) dllsearchpath=$libdir;; *) func_append dllsearchpath ":$libdir";; esac case :$dllsearchpath: in *":$testbindir:"*) ;; ::) dllsearchpath=$testbindir;; *) func_append dllsearchpath ":$testbindir";; esac ;; esac done # Substitute the hardcoded libdirs into the rpath. if test -n "$hardcode_libdir_separator" && test -n "$hardcode_libdirs"; then libdir="$hardcode_libdirs" eval rpath=\" $hardcode_libdir_flag_spec\" fi compile_rpath="$rpath" rpath= hardcode_libdirs= for libdir in $finalize_rpath; do if test -n "$hardcode_libdir_flag_spec"; then if test -n "$hardcode_libdir_separator"; then if test -z "$hardcode_libdirs"; then hardcode_libdirs="$libdir" else # Just accumulate the unique libdirs. case $hardcode_libdir_separator$hardcode_libdirs$hardcode_libdir_separator in *"$hardcode_libdir_separator$libdir$hardcode_libdir_separator"*) ;; *) func_append hardcode_libdirs "$hardcode_libdir_separator$libdir" ;; esac fi else eval flag=\"$hardcode_libdir_flag_spec\" func_append rpath " $flag" fi elif test -n "$runpath_var"; then case "$finalize_perm_rpath " in *" $libdir "*) ;; *) func_append finalize_perm_rpath " $libdir" ;; esac fi done # Substitute the hardcoded libdirs into the rpath. if test -n "$hardcode_libdir_separator" && test -n "$hardcode_libdirs"; then libdir="$hardcode_libdirs" eval rpath=\" $hardcode_libdir_flag_spec\" fi finalize_rpath="$rpath" if test -n "$libobjs" && test "$build_old_libs" = yes; then # Transform all the library objects into standard objects. compile_command=`$ECHO "$compile_command" | $SP2NL | $SED "$lo2o" | $NL2SP` finalize_command=`$ECHO "$finalize_command" | $SP2NL | $SED "$lo2o" | $NL2SP` fi func_generate_dlsyms "$outputname" "@PROGRAM@" "no" # template prelinking step if test -n "$prelink_cmds"; then func_execute_cmds "$prelink_cmds" 'exit $?' fi wrappers_required=yes case $host in *cegcc* | *mingw32ce*) # Disable wrappers for cegcc and mingw32ce hosts, we are cross compiling anyway. wrappers_required=no ;; *cygwin* | *mingw* ) if test "$build_libtool_libs" != yes; then wrappers_required=no fi ;; *) if test "$need_relink" = no || test "$build_libtool_libs" != yes; then wrappers_required=no fi ;; esac if test "$wrappers_required" = no; then # Replace the output file specification. compile_command=`$ECHO "$compile_command" | $SED 's%@OUTPUT@%'"$output"'%g'` link_command="$compile_command$compile_rpath" # We have no uninstalled library dependencies, so finalize right now. exit_status=0 func_show_eval "$link_command" 'exit_status=$?' if test -n "$postlink_cmds"; then func_to_tool_file "$output" postlink_cmds=`func_echo_all "$postlink_cmds" | $SED -e 's%@OUTPUT@%'"$output"'%g' -e 's%@TOOL_OUTPUT@%'"$func_to_tool_file_result"'%g'` func_execute_cmds "$postlink_cmds" 'exit $?' fi # Delete the generated files. if test -f "$output_objdir/${outputname}S.${objext}"; then func_show_eval '$RM "$output_objdir/${outputname}S.${objext}"' fi exit $exit_status fi if test -n "$compile_shlibpath$finalize_shlibpath"; then compile_command="$shlibpath_var=\"$compile_shlibpath$finalize_shlibpath\$$shlibpath_var\" $compile_command" fi if test -n "$finalize_shlibpath"; then finalize_command="$shlibpath_var=\"$finalize_shlibpath\$$shlibpath_var\" $finalize_command" fi compile_var= finalize_var= if test -n "$runpath_var"; then if test -n "$perm_rpath"; then # We should set the runpath_var. rpath= for dir in $perm_rpath; do func_append rpath "$dir:" done compile_var="$runpath_var=\"$rpath\$$runpath_var\" " fi if test -n "$finalize_perm_rpath"; then # We should set the runpath_var. rpath= for dir in $finalize_perm_rpath; do func_append rpath "$dir:" done finalize_var="$runpath_var=\"$rpath\$$runpath_var\" " fi fi if test "$no_install" = yes; then # We don't need to create a wrapper script. link_command="$compile_var$compile_command$compile_rpath" # Replace the output file specification. link_command=`$ECHO "$link_command" | $SED 's%@OUTPUT@%'"$output"'%g'` # Delete the old output file. $opt_dry_run || $RM $output # Link the executable and exit func_show_eval "$link_command" 'exit $?' if test -n "$postlink_cmds"; then func_to_tool_file "$output" postlink_cmds=`func_echo_all "$postlink_cmds" | $SED -e 's%@OUTPUT@%'"$output"'%g' -e 's%@TOOL_OUTPUT@%'"$func_to_tool_file_result"'%g'` func_execute_cmds "$postlink_cmds" 'exit $?' fi exit $EXIT_SUCCESS fi if test "$hardcode_action" = relink; then # Fast installation is not supported link_command="$compile_var$compile_command$compile_rpath" relink_command="$finalize_var$finalize_command$finalize_rpath" func_warning "this platform does not like uninstalled shared libraries" func_warning "\`$output' will be relinked during installation" else if test "$fast_install" != no; then link_command="$finalize_var$compile_command$finalize_rpath" if test "$fast_install" = yes; then relink_command=`$ECHO "$compile_var$compile_command$compile_rpath" | $SED 's%@OUTPUT@%\$progdir/\$file%g'` else # fast_install is set to needless relink_command= fi else link_command="$compile_var$compile_command$compile_rpath" relink_command="$finalize_var$finalize_command$finalize_rpath" fi fi # Replace the output file specification. link_command=`$ECHO "$link_command" | $SED 's%@OUTPUT@%'"$output_objdir/$outputname"'%g'` # Delete the old output files. $opt_dry_run || $RM $output $output_objdir/$outputname $output_objdir/lt-$outputname func_show_eval "$link_command" 'exit $?' if test -n "$postlink_cmds"; then func_to_tool_file "$output_objdir/$outputname" postlink_cmds=`func_echo_all "$postlink_cmds" | $SED -e 's%@OUTPUT@%'"$output_objdir/$outputname"'%g' -e 's%@TOOL_OUTPUT@%'"$func_to_tool_file_result"'%g'` func_execute_cmds "$postlink_cmds" 'exit $?' fi # Now create the wrapper script. func_verbose "creating $output" # Quote the relink command for shipping. if test -n "$relink_command"; then # Preserve any variables that may affect compiler behavior for var in $variables_saved_for_relink; do if eval test -z \"\${$var+set}\"; then relink_command="{ test -z \"\${$var+set}\" || $lt_unset $var || { $var=; export $var; }; }; $relink_command" elif eval var_value=\$$var; test -z "$var_value"; then relink_command="$var=; export $var; $relink_command" else func_quote_for_eval "$var_value" relink_command="$var=$func_quote_for_eval_result; export $var; $relink_command" fi done relink_command="(cd `pwd`; $relink_command)" relink_command=`$ECHO "$relink_command" | $SED "$sed_quote_subst"` fi # Only actually do things if not in dry run mode. $opt_dry_run || { # win32 will think the script is a binary if it has # a .exe suffix, so we strip it off here. case $output in *.exe) func_stripname '' '.exe' "$output" output=$func_stripname_result ;; esac # test for cygwin because mv fails w/o .exe extensions case $host in *cygwin*) exeext=.exe func_stripname '' '.exe' "$outputname" outputname=$func_stripname_result ;; *) exeext= ;; esac case $host in *cygwin* | *mingw* ) func_dirname_and_basename "$output" "" "." output_name=$func_basename_result output_path=$func_dirname_result cwrappersource="$output_path/$objdir/lt-$output_name.c" cwrapper="$output_path/$output_name.exe" $RM $cwrappersource $cwrapper trap "$RM $cwrappersource $cwrapper; exit $EXIT_FAILURE" 1 2 15 func_emit_cwrapperexe_src > $cwrappersource # The wrapper executable is built using the $host compiler, # because it contains $host paths and files. If cross- # compiling, it, like the target executable, must be # executed on the $host or under an emulation environment. $opt_dry_run || { $LTCC $LTCFLAGS -o $cwrapper $cwrappersource $STRIP $cwrapper } # Now, create the wrapper script for func_source use: func_ltwrapper_scriptname $cwrapper $RM $func_ltwrapper_scriptname_result trap "$RM $func_ltwrapper_scriptname_result; exit $EXIT_FAILURE" 1 2 15 $opt_dry_run || { # note: this script will not be executed, so do not chmod. if test "x$build" = "x$host" ; then $cwrapper --lt-dump-script > $func_ltwrapper_scriptname_result else func_emit_wrapper no > $func_ltwrapper_scriptname_result fi } ;; * ) $RM $output trap "$RM $output; exit $EXIT_FAILURE" 1 2 15 func_emit_wrapper no > $output chmod +x $output ;; esac } exit $EXIT_SUCCESS ;; esac # See if we need to build an old-fashioned archive. for oldlib in $oldlibs; do if test "$build_libtool_libs" = convenience; then oldobjs="$libobjs_save $symfileobj" addlibs="$convenience" build_libtool_libs=no else if test "$build_libtool_libs" = module; then oldobjs="$libobjs_save" build_libtool_libs=no else oldobjs="$old_deplibs $non_pic_objects" if test "$preload" = yes && test -f "$symfileobj"; then func_append oldobjs " $symfileobj" fi fi addlibs="$old_convenience" fi if test -n "$addlibs"; then gentop="$output_objdir/${outputname}x" func_append generated " $gentop" func_extract_archives $gentop $addlibs func_append oldobjs " $func_extract_archives_result" fi # Do each command in the archive commands. if test -n "$old_archive_from_new_cmds" && test "$build_libtool_libs" = yes; then cmds=$old_archive_from_new_cmds else # Add any objects from preloaded convenience libraries if test -n "$dlprefiles"; then gentop="$output_objdir/${outputname}x" func_append generated " $gentop" func_extract_archives $gentop $dlprefiles func_append oldobjs " $func_extract_archives_result" fi # POSIX demands no paths to be encoded in archives. We have # to avoid creating archives with duplicate basenames if we # might have to extract them afterwards, e.g., when creating a # static archive out of a convenience library, or when linking # the entirety of a libtool archive into another (currently # not supported by libtool). if (for obj in $oldobjs do func_basename "$obj" $ECHO "$func_basename_result" done | sort | sort -uc >/dev/null 2>&1); then : else echo "copying selected object files to avoid basename conflicts..." gentop="$output_objdir/${outputname}x" func_append generated " $gentop" func_mkdir_p "$gentop" save_oldobjs=$oldobjs oldobjs= counter=1 for obj in $save_oldobjs do func_basename "$obj" objbase="$func_basename_result" case " $oldobjs " in " ") oldobjs=$obj ;; *[\ /]"$objbase "*) while :; do # Make sure we don't pick an alternate name that also # overlaps. newobj=lt$counter-$objbase func_arith $counter + 1 counter=$func_arith_result case " $oldobjs " in *[\ /]"$newobj "*) ;; *) if test ! -f "$gentop/$newobj"; then break; fi ;; esac done func_show_eval "ln $obj $gentop/$newobj || cp $obj $gentop/$newobj" func_append oldobjs " $gentop/$newobj" ;; *) func_append oldobjs " $obj" ;; esac done fi func_to_tool_file "$oldlib" func_convert_file_msys_to_w32 tool_oldlib=$func_to_tool_file_result eval cmds=\"$old_archive_cmds\" func_len " $cmds" len=$func_len_result if test "$len" -lt "$max_cmd_len" || test "$max_cmd_len" -le -1; then cmds=$old_archive_cmds elif test -n "$archiver_list_spec"; then func_verbose "using command file archive linking..." for obj in $oldobjs do func_to_tool_file "$obj" $ECHO "$func_to_tool_file_result" done > $output_objdir/$libname.libcmd func_to_tool_file "$output_objdir/$libname.libcmd" oldobjs=" $archiver_list_spec$func_to_tool_file_result" cmds=$old_archive_cmds else # the command line is too long to link in one step, link in parts func_verbose "using piecewise archive linking..." save_RANLIB=$RANLIB RANLIB=: objlist= concat_cmds= save_oldobjs=$oldobjs oldobjs= # Is there a better way of finding the last object in the list? for obj in $save_oldobjs do last_oldobj=$obj done eval test_cmds=\"$old_archive_cmds\" func_len " $test_cmds" len0=$func_len_result len=$len0 for obj in $save_oldobjs do func_len " $obj" func_arith $len + $func_len_result len=$func_arith_result func_append objlist " $obj" if test "$len" -lt "$max_cmd_len"; then : else # the above command should be used before it gets too long oldobjs=$objlist if test "$obj" = "$last_oldobj" ; then RANLIB=$save_RANLIB fi test -z "$concat_cmds" || concat_cmds=$concat_cmds~ eval concat_cmds=\"\${concat_cmds}$old_archive_cmds\" objlist= len=$len0 fi done RANLIB=$save_RANLIB oldobjs=$objlist if test "X$oldobjs" = "X" ; then eval cmds=\"\$concat_cmds\" else eval cmds=\"\$concat_cmds~\$old_archive_cmds\" fi fi fi func_execute_cmds "$cmds" 'exit $?' done test -n "$generated" && \ func_show_eval "${RM}r$generated" # Now create the libtool archive. case $output in *.la) old_library= test "$build_old_libs" = yes && old_library="$libname.$libext" func_verbose "creating $output" # Preserve any variables that may affect compiler behavior for var in $variables_saved_for_relink; do if eval test -z \"\${$var+set}\"; then relink_command="{ test -z \"\${$var+set}\" || $lt_unset $var || { $var=; export $var; }; }; $relink_command" elif eval var_value=\$$var; test -z "$var_value"; then relink_command="$var=; export $var; $relink_command" else func_quote_for_eval "$var_value" relink_command="$var=$func_quote_for_eval_result; export $var; $relink_command" fi done # Quote the link command for shipping. relink_command="(cd `pwd`; $SHELL $progpath $preserve_args --mode=relink $libtool_args @inst_prefix_dir@)" relink_command=`$ECHO "$relink_command" | $SED "$sed_quote_subst"` if test "$hardcode_automatic" = yes ; then relink_command= fi # Only create the output if not a dry run. $opt_dry_run || { for installed in no yes; do if test "$installed" = yes; then if test -z "$install_libdir"; then break fi output="$output_objdir/$outputname"i # Replace all uninstalled libtool libraries with the installed ones newdependency_libs= for deplib in $dependency_libs; do case $deplib in *.la) func_basename "$deplib" name="$func_basename_result" func_resolve_sysroot "$deplib" eval libdir=`${SED} -n -e 's/^libdir=\(.*\)$/\1/p' $func_resolve_sysroot_result` test -z "$libdir" && \ func_fatal_error "\`$deplib' is not a valid libtool archive" func_append newdependency_libs " ${lt_sysroot:+=}$libdir/$name" ;; -L*) func_stripname -L '' "$deplib" func_replace_sysroot "$func_stripname_result" func_append newdependency_libs " -L$func_replace_sysroot_result" ;; -R*) func_stripname -R '' "$deplib" func_replace_sysroot "$func_stripname_result" func_append newdependency_libs " -R$func_replace_sysroot_result" ;; *) func_append newdependency_libs " $deplib" ;; esac done dependency_libs="$newdependency_libs" newdlfiles= for lib in $dlfiles; do case $lib in *.la) func_basename "$lib" name="$func_basename_result" eval libdir=`${SED} -n -e 's/^libdir=\(.*\)$/\1/p' $lib` test -z "$libdir" && \ func_fatal_error "\`$lib' is not a valid libtool archive" func_append newdlfiles " ${lt_sysroot:+=}$libdir/$name" ;; *) func_append newdlfiles " $lib" ;; esac done dlfiles="$newdlfiles" newdlprefiles= for lib in $dlprefiles; do case $lib in *.la) # Only pass preopened files to the pseudo-archive (for # eventual linking with the app. that links it) if we # didn't already link the preopened objects directly into # the library: func_basename "$lib" name="$func_basename_result" eval libdir=`${SED} -n -e 's/^libdir=\(.*\)$/\1/p' $lib` test -z "$libdir" && \ func_fatal_error "\`$lib' is not a valid libtool archive" func_append newdlprefiles " ${lt_sysroot:+=}$libdir/$name" ;; esac done dlprefiles="$newdlprefiles" else newdlfiles= for lib in $dlfiles; do case $lib in [\\/]* | [A-Za-z]:[\\/]*) abs="$lib" ;; *) abs=`pwd`"/$lib" ;; esac func_append newdlfiles " $abs" done dlfiles="$newdlfiles" newdlprefiles= for lib in $dlprefiles; do case $lib in [\\/]* | [A-Za-z]:[\\/]*) abs="$lib" ;; *) abs=`pwd`"/$lib" ;; esac func_append newdlprefiles " $abs" done dlprefiles="$newdlprefiles" fi $RM $output # place dlname in correct position for cygwin # In fact, it would be nice if we could use this code for all target # systems that can't hard-code library paths into their executables # and that have no shared library path variable independent of PATH, # but it turns out we can't easily determine that from inspecting # libtool variables, so we have to hard-code the OSs to which it # applies here; at the moment, that means platforms that use the PE # object format with DLL files. See the long comment at the top of # tests/bindir.at for full details. tdlname=$dlname case $host,$output,$installed,$module,$dlname in *cygwin*,*lai,yes,no,*.dll | *mingw*,*lai,yes,no,*.dll | *cegcc*,*lai,yes,no,*.dll) # If a -bindir argument was supplied, place the dll there. if test "x$bindir" != x ; then func_relative_path "$install_libdir" "$bindir" tdlname=$func_relative_path_result$dlname else # Otherwise fall back on heuristic. tdlname=../bin/$dlname fi ;; esac $ECHO > $output "\ # $outputname - a libtool library file # Generated by $PROGRAM (GNU $PACKAGE$TIMESTAMP) $VERSION # # Please DO NOT delete this file! # It is necessary for linking the library. # The name that we can dlopen(3). dlname='$tdlname' # Names of this library. library_names='$library_names' # The name of the static archive. old_library='$old_library' # Linker flags that can not go in dependency_libs. inherited_linker_flags='$new_inherited_linker_flags' # Libraries that this one depends upon. dependency_libs='$dependency_libs' # Names of additional weak libraries provided by this library weak_library_names='$weak_libs' # Version information for $libname. current=$current age=$age revision=$revision # Is this an already installed library? installed=$installed # Should we warn about portability when linking against -modules? shouldnotlink=$module # Files to dlopen/dlpreopen dlopen='$dlfiles' dlpreopen='$dlprefiles' # Directory that this library needs to be installed in: libdir='$install_libdir'" if test "$installed" = no && test "$need_relink" = yes; then $ECHO >> $output "\ relink_command=\"$relink_command\"" fi done } # Do a symbolic link so that the libtool archive can be found in # LD_LIBRARY_PATH before the program is installed. func_show_eval '( cd "$output_objdir" && $RM "$outputname" && $LN_S "../$outputname" "$outputname" )' 'exit $?' ;; esac exit $EXIT_SUCCESS } { test "$opt_mode" = link || test "$opt_mode" = relink; } && func_mode_link ${1+"$@"} # func_mode_uninstall arg... func_mode_uninstall () { $opt_debug RM="$nonopt" files= rmforce= exit_status=0 # This variable tells wrapper scripts just to set variables rather # than running their programs. libtool_install_magic="$magic" for arg do case $arg in -f) func_append RM " $arg"; rmforce=yes ;; -*) func_append RM " $arg" ;; *) func_append files " $arg" ;; esac done test -z "$RM" && \ func_fatal_help "you must specify an RM program" rmdirs= for file in $files; do func_dirname "$file" "" "." dir="$func_dirname_result" if test "X$dir" = X.; then odir="$objdir" else odir="$dir/$objdir" fi func_basename "$file" name="$func_basename_result" test "$opt_mode" = uninstall && odir="$dir" # Remember odir for removal later, being careful to avoid duplicates if test "$opt_mode" = clean; then case " $rmdirs " in *" $odir "*) ;; *) func_append rmdirs " $odir" ;; esac fi # Don't error if the file doesn't exist and rm -f was used. if { test -L "$file"; } >/dev/null 2>&1 || { test -h "$file"; } >/dev/null 2>&1 || test -f "$file"; then : elif test -d "$file"; then exit_status=1 continue elif test "$rmforce" = yes; then continue fi rmfiles="$file" case $name in *.la) # Possibly a libtool archive, so verify it. if func_lalib_p "$file"; then func_source $dir/$name # Delete the libtool libraries and symlinks. for n in $library_names; do func_append rmfiles " $odir/$n" done test -n "$old_library" && func_append rmfiles " $odir/$old_library" case "$opt_mode" in clean) case " $library_names " in *" $dlname "*) ;; *) test -n "$dlname" && func_append rmfiles " $odir/$dlname" ;; esac test -n "$libdir" && func_append rmfiles " $odir/$name $odir/${name}i" ;; uninstall) if test -n "$library_names"; then # Do each command in the postuninstall commands. func_execute_cmds "$postuninstall_cmds" 'test "$rmforce" = yes || exit_status=1' fi if test -n "$old_library"; then # Do each command in the old_postuninstall commands. func_execute_cmds "$old_postuninstall_cmds" 'test "$rmforce" = yes || exit_status=1' fi # FIXME: should reinstall the best remaining shared library. ;; esac fi ;; *.lo) # Possibly a libtool object, so verify it. if func_lalib_p "$file"; then # Read the .lo file func_source $dir/$name # Add PIC object to the list of files to remove. if test -n "$pic_object" && test "$pic_object" != none; then func_append rmfiles " $dir/$pic_object" fi # Add non-PIC object to the list of files to remove. if test -n "$non_pic_object" && test "$non_pic_object" != none; then func_append rmfiles " $dir/$non_pic_object" fi fi ;; *) if test "$opt_mode" = clean ; then noexename=$name case $file in *.exe) func_stripname '' '.exe' "$file" file=$func_stripname_result func_stripname '' '.exe' "$name" noexename=$func_stripname_result # $file with .exe has already been added to rmfiles, # add $file without .exe func_append rmfiles " $file" ;; esac # Do a test to see if this is a libtool program. if func_ltwrapper_p "$file"; then if func_ltwrapper_executable_p "$file"; then func_ltwrapper_scriptname "$file" relink_command= func_source $func_ltwrapper_scriptname_result func_append rmfiles " $func_ltwrapper_scriptname_result" else relink_command= func_source $dir/$noexename fi # note $name still contains .exe if it was in $file originally # as does the version of $file that was added into $rmfiles func_append rmfiles " $odir/$name $odir/${name}S.${objext}" if test "$fast_install" = yes && test -n "$relink_command"; then func_append rmfiles " $odir/lt-$name" fi if test "X$noexename" != "X$name" ; then func_append rmfiles " $odir/lt-${noexename}.c" fi fi fi ;; esac func_show_eval "$RM $rmfiles" 'exit_status=1' done # Try to remove the ${objdir}s in the directories where we deleted files for dir in $rmdirs; do if test -d "$dir"; then func_show_eval "rmdir $dir >/dev/null 2>&1" fi done exit $exit_status } { test "$opt_mode" = uninstall || test "$opt_mode" = clean; } && func_mode_uninstall ${1+"$@"} test -z "$opt_mode" && { help="$generic_help" func_fatal_help "you must specify a MODE" } test -z "$exec_cmd" && \ func_fatal_help "invalid operation mode \`$opt_mode'" if test -n "$exec_cmd"; then eval exec "$exec_cmd" exit $EXIT_FAILURE fi exit $exit_status # The TAGs below are defined such that we never get into a situation # in which we disable both kinds of libraries. Given conflicting # choices, we go for a static library, that is the most portable, # since we can't tell whether shared libraries were disabled because # the user asked for that or because the platform doesn't support # them. This is particularly important on AIX, because we don't # support having both static and shared libraries enabled at the same # time on that platform, so we default to a shared-only configuration. # If a disable-shared tag is given, we'll fallback to a static-only # configuration. But we'll never go from static-only to shared-only. # ### BEGIN LIBTOOL TAG CONFIG: disable-shared build_libtool_libs=no build_old_libs=yes # ### END LIBTOOL TAG CONFIG: disable-shared # ### BEGIN LIBTOOL TAG CONFIG: disable-static build_old_libs=`case $build_libtool_libs in yes) echo no;; *) echo yes;; esac` # ### END LIBTOOL TAG CONFIG: disable-static # Local Variables: # mode:shell-script # sh-indentation:2 # End: # vi:sw=2 ast-8.3.0/fframeset.c0000664000175000017500000001437213004147321011356 00000000000000/* *+ * Name: * fframeset.c * Purpose: * Define a FORTRAN 77 interface to the AST FrameSet class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the FrameSet class. * Routines Defined: * AST_ADDFRAME * AST_ADDVARIANT * AST_MIRRORVARIANTS * AST_FRAMESET * AST_GETFRAME * AST_GETMAPPING * AST_ISAFRAMESET * AST_REMAPFRAME * AST_REMOVEFRAME * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 1-AUG-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "mapping.h" /* C interface to the Mapping class */ #include "frame.h" /* C interface to the Frame class */ #include "frameset.h" /* C interface to the FrameSet class */ F77_SUBROUTINE(ast_addframe)( INTEGER(THIS), INTEGER(IFRAME), INTEGER(MAP), INTEGER(FRAME), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) GENPTR_INTEGER(MAP) GENPTR_INTEGER(FRAME) astAt( "AST_ADDFRAME", NULL, 0 ); astWatchSTATUS( astAddFrame( astI2P( *THIS ), *IFRAME, astI2P( *MAP ), astI2P( *FRAME ) ); ) } F77_INTEGER_FUNCTION(ast_frameset)( INTEGER(FRAME), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_FRAMESET", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astFrameSet( astI2P( *FRAME ), "%s", options ) ); astFree( options ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_getframe)( INTEGER(THIS), INTEGER(IFRAME), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetFrame( astI2P( *THIS ), *IFRAME ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_getmapping)( INTEGER(THIS), INTEGER(IFRAME1), INTEGER(IFRAME2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME1) GENPTR_INTEGER(IFRAME2) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETMAPPING", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetMapping( astI2P( *THIS ), *IFRAME1, *IFRAME2 ) ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isaframeset)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAFRAMESET", NULL, 0 ); astWatchSTATUS( RESULT = astIsAFrameSet( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_SUBROUTINE(ast_remapframe)( INTEGER(THIS), INTEGER(IFRAME), INTEGER(MAP), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) GENPTR_INTEGER(MAP) astAt( "AST_REMAPFRAME", NULL, 0 ); astWatchSTATUS( astRemapFrame( astI2P( *THIS ), *IFRAME, astI2P( *MAP ) ); ) } F77_SUBROUTINE(ast_removeframe)( INTEGER(THIS), INTEGER(IFRAME), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) astAt( "AST_REMOVEFRAME", NULL, 0 ); astWatchSTATUS( astRemoveFrame( astI2P( *THIS ), *IFRAME ); ) } F77_SUBROUTINE(ast_addvariant)( INTEGER(THIS), INTEGER(MAP), CHARACTER(NAME), INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(MAP) GENPTR_CHARACTER(NAME) char *name; astAt( "AST_ADDVARIANT", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); astAddVariant( astI2P( *THIS ), astI2P( *MAP ), name ); name = astFree( name ); ) } F77_SUBROUTINE(ast_mirrorvariants)( INTEGER(THIS), INTEGER(IFRAME), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) astAt( "AST_MIRRORVARIANTS", NULL, 0 ); astWatchSTATUS( astMirrorVariants( astI2P( *THIS ), *IFRAME ); ) } ast-8.3.0/lutmap.c0000664000175000017500000026350613004147321010711 00000000000000/* *class++ * Name: * LutMap * Purpose: * Transform 1-dimensional coordinates using a lookup table. * Constructor Function: c astLutMap f AST_LUTMAP * Description: * A LutMap is a specialised form of Mapping which transforms * 1-dimensional coordinates by using linear interpolation in a * lookup table. * * Each input coordinate value is first scaled to give the index of * an entry in the table by subtracting a starting value (the input * coordinate corresponding to the first table entry) and dividing * by an increment (the difference in input coordinate value * between adjacent table entries). * * The resulting index will usually contain a fractional part, so * the output coordinate value is then generated by interpolating * linearly between the appropriate entries in the table. If the * index lies outside the range of the table, linear extrapolation * is used based on the two nearest entries (i.e. the two entries * at the start or end of the table, as appropriate). If either of the * entries used for the interplation has a value of AST__BAD, then the * interpolated value is returned as AST__BAD. * * If the lookup table entries increase or decrease monotonically * (ignoring any flat sections), then the inverse transformation may * also be performed. * Inheritance: * The LutMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * LutMap also has the following attributes: * * - LutEpsilon: The relative error of the values in the table. * - LutInterp: The interpolation method to use between table entries. * Functions: c The LutMap class does not define any new functions beyond those f The LutMap class does not define any new routines beyond those * which are applicable to all Mappings. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2007-2011 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (JAC, UCLan) * History: * 8-JUL-1997 (RFWS): * Original version. * 10-JUL-1997 (RFWS): * Added the MapMerge function. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitLutMapVtab * method. * 12-JAN-2004 (DSB): * Check for AST__BAD values in the supplied lut array. * 17-MAR-2006 (DSB): * - MapMerge changed so that a LutMap will cancel with its own * inverse. * - Added attribute LutInterp * 10-MAY-2006 (DSB): * Override astEqual. * 4-OCT-2006 (DSB): * - Correct "mintick" to "lutinterp" in SetAttrib. * - Do not include bad values in the dumped LUT array. * 8-NOV-2007 (DSB): * - Take account of the requested invert flag when comparing two * neighbouring LutMaps for equality in MapMerge. * 19-NOV-2010 (DSB): * Added (protected) astGetLutMapInfo function. * 24-JAN-2011 (DSB): * Implement an inverse transformation even if the coordinate * array contains sections of equal or bad values. The inverse * transformation will generate bad values if used within such * regions of the coordinate array. * 6-JUL-2011 (DSB): * Avoid indexing the lut array beyond the end when doing an * inverse transform. * 2-OCT-2012 (DSB): * Check for Infs as well as NaNs. * 21-MAY-2015 (DSB): * Aded LutEpsilon * 23-SEP-2015 (DSB): * The GetMonotonic function had a bug that caused all LutMaps * to be considered monotonic, and thus have an inverse * transformation. *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 LutMap #define LINEAR 0 #define NEAR 1 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "winmap.h" /* Linear mappings between windows */ #include "channel.h" /* I/O channels */ #include "unitmap.h" /* Unit mappings */ #include "lutmap.h" /* Interface definition for this class */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(LutMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(LutMap,Class_Init) #define class_vtab astGLOBAL(LutMap,Class_Vtab) #define getattrib_buff astGLOBAL(LutMap,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstLutMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstLutMap *astLutMapId_( int, const double [], double, double, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int GetLinear( AstMapping *, int * ); static int GetMonotonic( int, const double *, int *, double **, int **, int **, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int Equal( AstObject *, AstObject *, int * ); static double *GetLutMapInfo( AstLutMap *, double *, double *, int *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static int GetLutInterp( AstLutMap *, int * ); static int TestLutInterp( AstLutMap *, int * ); static void ClearLutInterp( AstLutMap *, int * ); static void SetLutInterp( AstLutMap *, int, int * ); static double GetLutEpsilon( AstLutMap *, int * ); static int TestLutEpsilon( AstLutMap *, int * ); static void ClearLutEpsilon( AstLutMap *, int * ); static void SetLutEpsilon( AstLutMap *, double, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a LutMap. * Type: * Private function. * Synopsis: * #include "lutmap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * LutMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * LutMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the LutMap. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstLutMap *this; /* Pointer to the LutMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* LutInterp. */ /* ---------- */ if ( !strcmp( attrib, "lutinterp" ) ) { astClearLutInterp( this ); /* LutEpsilon. */ /* ------------- */ } else if ( !strcmp( attrib, "lutepsilon" ) ) { astClearLutEpsilon( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two LutMaps are equivalent. * Type: * Private function. * Synopsis: * #include "lutmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * LutMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two LutMaps are equivalent. * Parameters: * this * Pointer to the first Object (a LutMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the LutMaps are equivalent, zero otherwise. * 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: */ AstLutMap *that; AstLutMap *this; int i; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two LutMap structures. */ this = (AstLutMap *) this_object; that = (AstLutMap *) that_object; /* Check the second object is a LutMap. We know the first is a LutMap since we have arrived at this implementation of the virtual function. */ if( astIsALutMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two LutMaps differ, it may still be possible for them to be equivalent. First compare the LutMaps if their Invert flags are the same. In this case all the attributes of the two LutMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { if( astEQUAL( this->start, that->start ) && astEQUAL( this->inc, that->inc ) && this->nlut == that->nlut && this->lutinterp == that->lutinterp ){ result = 1; for( i = 0; i < this->nlut; i++ ) { if( !astEQUAL( (this->lut)[ i ], (that->lut)[ i ] ) ) { result = 0; break; } } } /* If the Invert flags for the two LutMaps differ, the attributes of the two LutMaps must be inversely related to each other. */ } else { /* In the specific case of a LutMap, Invert flags must be equal. */ result = 0; } } } /* 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 LutMap. * Type: * Private function. * Synopsis: * #include "lutmap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * LutMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a LutMap, formatted as a character string. * Parameters: * this * Pointer to the LutMap. * 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 LutMap, 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 LutMap. 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: */ AstLutMap *this; /* Pointer to the LutMap structure */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *result; /* Pointer value to return */ double luteps; /* LutEpsilon attribute value */ int lutinterp; /* LutInterp attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) 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. */ /* LutInterp. */ /* ---------- */ if ( !strcmp( attrib, "lutinterp" ) ) { lutinterp = astGetLutInterp( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", lutinterp ); result = getattrib_buff; } /* LutEpsilon. */ /* ------------- */ } else if ( !strcmp( attrib, "lutepsilon" ) ) { luteps = astGetLutEpsilon( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, luteps ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetLinear( AstMapping *this_mapping, int *status ) { /* * Name: * GetLinear * Purpose: * Determine if a LutMap implements a linear coordinate transformation. * Type: * Private function. * Synopsis: * #include "lutmap.h" * int GetLinear( AstMapping *this, int *status ) * Class Membership: * LutMap member function. * Description: * This function returns a boolean value to indicate if the LutMap * supplied is equivalent to a linear coordinate * transformation. This will be the case if the lookup table * elements increase or decrease linearly. * Parameters: * this * Pointer to the LutMap. * status * Pointer to the inherited status variable. * 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: */ AstLutMap *this; /* Pointer to the LutMap structure */ double *lut; /* Pointer to the lookup table */ double eps; /* Relative error on the table values */ double fract; /* Fractional position within table */ double hi; /* Largest value */ double interp; /* Interpolated value */ double lo; /* Smallest value */ double tol1; /* First tolerance estimate */ double tol2; /* Second tolerance estimate */ double tol; /* Tolerance value used */ int ilut; /* Loop counter for table elements */ int linear; /* Result to be returned */ int nlut; /* Number of lookup table elements */ /* Initialise. */ linear = 0; /* Check the global error status. */ if ( !astOK ) return linear; /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) this_mapping; /* Nearest neighbour LutMaps are not considered to be linear because of the discontinuities at the start and end of the table. */ if( astGetLutInterp( this ) != NEAR ) { /* Obtain the lookup table details. */ lut = this->lut; nlut = this->nlut; /* Loop to identify the largest and smallest values in the lookup table. */ lo = DBL_MAX; hi = -DBL_MAX; for ( ilut = 0; ilut < nlut; ilut++ ) { if ( lut[ ilut ] > hi ) hi = lut[ ilut ]; if ( lut[ ilut ] < lo ) lo = lut[ ilut ]; } /* Check if the values are all the same (this makes the LutMap linear, although it will have no inverse). */ linear = ( hi == lo ); if ( !linear ) { /* Get the relative error associated with the table values. */ eps = astGetLutEpsilon( this ); /* Form a tolerance estimate based on the overall range of values in the lookup table. */ tol1 = fabs( hi - lo ) * eps; /* Now loop to inspect all the lookup table elements except the first and last. */ linear = 1; for ( ilut = 1; ilut < ( nlut - 1 ); ilut++ ) { /* Calculate the fractional position of the current element within the table. */ fract = ( (double) ilut ) / ( (double) ( nlut - 1 ) ); /* Calculate the value it should have if the table is linear by interpolating between the first and last values. */ interp = lut[ 0 ] * ( 1.0 - fract ) + lut[ nlut - 1 ] * fract; /* Form a second tolerance estimate from this interpolated value. Select whichever tolerance estimate is larger (this avoids problems when values are near zero). */ tol2 = fabs( interp ) * eps; tol = ( tol1 > tol2 ) ? tol1 : tol2; /* Test for linearity within a small multiple of the tolerance. */ linear = ( fabs( lut[ ilut ] - interp ) <= ( 2.0 * tol ) ); if ( !linear ) break; } } } /* Return the result. */ return linear; } static double *GetLutMapInfo( AstLutMap *this, double *start, double *inc, int *nlut, int *status ){ /* * Name: * GetLutMapInfo * Purpose: * Return information about a LutMap. * Type: * Protected virtual function. * Synopsis: * #include "permmap.h" * double *astGetLutMapInfo( AstLutMap *this, double *start, double *inc, * int *nlut, int *status ) * Class Membership: * LutMap method * Description: * This function returns information about the supplied LutMap. * Parameters: * this * Pointer to the LutMap. * start * Pointer to a double in which to return the "start" value * supplied when the LutMap was created. * inc * Pointer to a double in which to return the "inc" value * supplied when the LutMap was created. * nlut * Pointer to a double in which to return the number of values in * the LUT. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated array holding a copy of the * look-up table. This is an array of "nlut" elements, giving the * output values for input values "start", "start+inc", "start+2*inc", * etc. The pointer should be freed using astFree when no longer * needed. * Notes: * - A value of NULL will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Store the scalar values. */ *start = this->start; *inc = this->inc; *nlut = this->nlut; /* Return a copy of the look up table. */ return astStore( NULL, this->lut, sizeof( double )*this->nlut ); } static int GetMonotonic( int nlut, const double *lut, int *nluti, double **luti, int **flagsi, int **indexi, int *status ) { /* * Name: * GetMonotonic * Purpose: * Determine if a array is monotonic increasing or decreasing. * Type: * Private function. * Synopsis: * #include "lutmap.h" * int GetMonotonic( int nlut, const double *lut, int *nluti, double **luti, * int **flagsi, int **indexi, int *status ) * Class Membership: * LutMap member function. * Description: * This function returns a flag indiciating the supplied array is * monotonic increasing, monotonic decreasing, or non-monotonic. * Sections of equal or bad values do not invalidate an otherwise * monotonic array. * * It also returns information needed to implement the inverse * transformation of a LutMap. * Parameters: * nlut * The length of the array. * lut * The array to check. * nluti * Address of an int in which to store the length of the returned * "luti" and "flags" arrays. * luti * Address at which to return a pointer to a newly allocated array * containing "*nluti" elements. This is a copy of the supplied * "lut" array but with any bad or NaN values omitted. Subsequent * elements are shuffled down to fill the holes left by removing * these bad values. A NULL pointer is returned if there are no bad * values in "lut". * flagsi * Address at which to return a pointer to a newly allocated array * containing "*nluti" elements. Each element is non-zero if the * corresponding value stored in "luti" was adjacent to a bad value * in the supplied "lut" array. A NULL pointer is returned if there * are no bad values in "lut". * indexi * Address at which to return a pointer to a newly allocated array * containing "*nluti" elements. Each element is the index within * "lut" of the corresponding value stored in "luti". A NULL pointer * is returned if there are no bad values in "lut". * status * Pointer to the inherited status variable. * 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: */ const double *p3; double *p1; double lval; int *p2; int *p4; int ilut; int nbad; int result; /* Initialise. */ result = 0; *nluti = 0; *luti = NULL; *flagsi = NULL; *indexi = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* As yet we have not found a good value. */ lval = AST__BAD; /* As yet we have not found a bad value. */ nbad = 0; /* Loop round the supplied array, ignoring bad (AST__BAD or NaN) values. */ for ( ilut = 0; ilut < nlut; ilut++ ) { if( !astISBAD( lut[ ilut ] ) ) { /* If this is the first good value, record it. */ if( lval == AST__BAD ) { lval = lut[ ilut ]; /* If this is not the first good value, ignore it if it is equal to the previous god value. */ } else if( lut[ ilut ] != lval ) { /* Set the returned flag on the basis of the first pair of good values. */ if( result == 0 ) { result = ( lut[ ilut ] > lval ) ? 1 : -1; /* For subsequent pairs of good values, check the pair increases or decreases in the same way as the first pair. Reset the returned value to zero and break if not. */ } else if( result == 1 && lut[ ilut ] < lval ) { result = 0; break; } else if( result == -1 && lut[ ilut ] >lval ) { result = 0; break; } /* Record the current good value. */ lval = lut[ ilut ]; } } else { nbad++; } } /* If any bad values were found, we now allocate the required returned arrays. */ if( nbad ) { *nluti = nlut - nbad; *luti = astMalloc( sizeof( double )*( *nluti ) ); *flagsi = astMalloc( sizeof( double )*( *nluti ) ); *indexi = astMalloc( sizeof( double )*( *nluti ) ); if( astOK ) { /* Into "luti" copy all good values from "lut", shuffling down values to fill holes left by bad values. Into "flagsi", store a flag indicating if the corresponding "luti" value was adjacent to a bad value in the full "lut" array. */ p1 = *luti; p2 = *flagsi; p3 = lut; p4 = *indexi; /* Do the first input point (it has no lower neighbour). */ if( !astISBAD( *p3 ) ) { *(p1++) = *p3; *(p2++) = astISBAD( p3[ +1 ] ); *(p4++) = 0; } /* Do all remaining input points except for the last one. */ for ( ilut = 1,p3++; ilut < nlut-1; ilut++,p3++ ) { if( !astISBAD( *p3 ) ) { *(p1++) = *p3; *(p2++) = astISBAD( p3[ -1 ] ) || astISBAD( p3[ +1 ] ); *(p4++) = ilut; } } /* Do the last input point (it has no upper neighbour). */ if( !astISBAD( *p3 ) ) { *p1 = *p3; *p2 = astISBAD( p3[ -1 ] ); *p4 = ilut; } } } /* Return the result. */ return result; } void astInitLutMapVtab_( AstLutMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitLutMapVtab * Purpose: * Initialise a virtual function table for a LutMap. * Type: * Protected function. * Synopsis: * #include "lutmap.h" * void astInitLutMapVtab( AstLutMapVtab *vtab, const char *name ) * Class Membership: * LutMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the LutMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsALutMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearLutInterp = ClearLutInterp; vtab->GetLutInterp = GetLutInterp; vtab->SetLutInterp = SetLutInterp; vtab->TestLutInterp = TestLutInterp; vtab->ClearLutEpsilon = ClearLutEpsilon; vtab->GetLutEpsilon = GetLutEpsilon; vtab->SetLutEpsilon = SetLutEpsilon; vtab->TestLutEpsilon = TestLutEpsilon; vtab->GetLutMapInfo = GetLutMapInfo; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the class dump, copy and delete functions.*/ astSetDump( vtab, Dump, "LutMap", "Map 1-d coordinates using a lookup table" ); astSetCopy( (AstObjectVtab *) vtab, Copy ); astSetDelete( (AstObjectVtab *) vtab, Delete ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a LutMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * LutMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated LutMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated LutMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated LutMap which is to be merged with * its neighbours. This should be a cloned copy of the LutMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * LutMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated LutMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstLutMap *map; /* Pointer to LutMap */ AstLutMap *neb; /* Pointer to neighbouring LutMap */ AstMapping *new; /* Pointer to replacement Mapping */ double a1; /* First input coordinate value */ double a2; /* Second input coordinate value */ double b1; /* First output coordinate value */ double b2; /* Second output coordinate value */ int equal; /* Are LutMaps equal? */ int i; /* Mapping index */ int ilo; /* Index of lower LutMap */ int invneb; /* Should the neigbour be used inverted? */ int old_inv; /* Original Invert value for neigbour */ int result; /* Result value to return */ int simpler; /* Mapping simplified? */ /* Initialise the returned result. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the nominated LutMap. */ map = (AstLutMap *) ( *map_list )[ where ]; /* See if the LutMap is linear. If so, it can probably be simplified. */ simpler = GetLinear( (AstMapping *) map, status ); if ( simpler ) { /* Obtain the range of input values corresponding to the first and last lookup table elements. */ a1 = map->start; a2 = map->start + map->inc * ( map->nlut - 1 ); /* Obtain the corresponding range of output values and check these values are not the same. */ b1 = map->lut[ 0 ]; b2 = map->lut[ map->nlut - 1 ]; if ( b1 != b2 ) { /* Create a new WinMap that implements an equivalent linear Mapping, allowing for the invert flag associated with the LutMap. */ if ( !( *invert_list )[ where ] ) { new = (AstMapping *) astWinMap( 1, &a1, &a2, &b1, &b2, "", status ); } else { new = (AstMapping *) astWinMap( 1, &b1, &b2, &a1, &a2, "", status ); } /* If OK, annul the original LutMap pointer and substitute the new one. Also clear the associated invert flag. */ if ( astOK ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = 0; /* Assign the result value. */ result = where; } } /* Otherwise, see if the LutMap is in series with its own inverse. If so the pair of LutMaps can be replaced by a UnitMap. */ } else if( series ) { /* Is the higher neighbour a LutMap? If so get a pointer to it, and note the index of the lower of the two adjacent LutMaps. */ if( where < ( *nmap - 1 ) && astIsALutMap( ( *map_list )[ where + 1 ] ) ){ neb = (AstLutMap *) ( *map_list )[ where + 1 ]; invneb = ( *invert_list )[ where + 1 ]; ilo = where; /* If not, is the lower neighbour a LutMap? If so get a pointer to it, and note the index of the lower of the two adjacent LutMaps. */ } else if( where > 0 && astIsALutMap( ( *map_list )[ where - 1 ] ) ){ neb = (AstLutMap *) ( *map_list )[ where - 1 ]; invneb = ( *invert_list )[ where - 1 ]; ilo = where - 1; } else { neb = NULL; } /* If a neighbouring LutMap was found, we can replace the pair by a UnitMap if the two LutMaps are equal but have opposite values for their Invert flags. Temporarily invert the neighbour, then compare the two LutMaps for equality, then re-invert the neighbour. */ if( neb ) { old_inv = astGetInvert( neb ); astSetInvert( neb, invneb ); astInvert( neb ); equal = astEqual( map, neb ); astSetInvert( neb, old_inv ); /* If the two LutMaps are equal but opposite, annul the first of the two Mappings, and replace it with a UnitMap. Also set the invert flag. */ if( equal ) { new = (AstMapping *) astUnitMap( 1, "", status ); (void) astAnnul( ( *map_list )[ ilo ] ); ( *map_list )[ ilo ] = new; ( *invert_list )[ ilo ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ ilo + 1 ] ); for ( i = ilo + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = where; } } } /* If an error occurred, clear the returned result. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a LutMap. * Type: * Private function. * Synopsis: * #include "lutmap.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * LutMap member function (over-rides the astSetAttrib protected * method inherited from the Mapping class). * Description: * This function assigns an attribute value for a LutMap, 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 LutMap. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstLutMap *this; /* Pointer to the LutMap structure */ double luteps; /* LutEpsilon attribute value */ int lutinterp; /* LutInterp attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* LutInterp. */ /* ---------- */ if ( nc = 0, ( 1 == astSscanf( setting, "lutinterp= %d %n", &lutinterp, &nc ) ) && ( nc >= len ) ) { astSetLutInterp( this, lutinterp ); /* LutEpsilon. */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "lutepsilon= %lf %n", &luteps, &nc ) ) && ( nc >= len ) ) { astSetLutEpsilon( this, luteps ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a LutMap. * Type: * Private function. * Synopsis: * #include "lutmap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * LutMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a LutMap's attributes. * Parameters: * this * Pointer to the LutMap. * 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: */ AstLutMap *this; /* Pointer to the LutMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* LutInterp. */ /* ---------- */ if ( !strcmp( attrib, "lutinterp" ) ) { result = astTestLutInterp( this ); /* LutEpsilon. */ /* ------------- */ } else if ( !strcmp( attrib, "lutepsilon" ) ) { result = astTestLutEpsilon( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a LutMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "lutmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * LutMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a LutMap and a set of points encapsulated * in a PointSet and transforms the points so as to apply the * lookup table transformation. * Parameters: * this * Pointer to the LutMap. * 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: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * - The number of coordinate values per point in the input * PointSet must equal 1. * - If an output PointSet is supplied, it must have space for * sufficient number of points (with 1 coordinate value per point) * to accommodate the result. Any excess space will be ignored. */ /* Local Variables: */ AstLutMap *map; /* Pointer to LutMap to be applied */ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *lut; /* Pointer to LUT */ double d1; /* Offset to I1 value */ double d2; /* Offset to I2 value */ double fract; /* Fractional interpolation distance */ double scale; /* Normalising scale factor */ double value_in; /* Input coordinate value */ double value_out; /* Output coordinate value */ double x; /* Value normalised to LUT increment */ double xi; /* Integer value of "x" */ int *flags; /* Flags indicating an adjacent bad value */ int *index; /* Translates reduced to original indices */ int i1; /* Lower adjacent LUT index */ int i2; /* Upper adjacent LUT index */ int i; /* New LUT index */ int istart; /* Original LUT index at start of interval */ int ix; /* "x" converted to an int */ int near; /* Perform nearest neighbour interpolation? */ int nlut; /* Number of LUT entries */ int nlutm1; /* Number of LUT entries minus one */ int npoint; /* Number of points */ int ok; /* Lookup table is not flat */ int point; /* Loop counter for points */ int up; /* LUT values are increasing? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the LutMap. */ map = (AstLutMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Forward transformation. */ /* ----------------------- */ if( astOK ){ if ( forward ) { /* Obtain lookup table details. */ lut = map->lut; nlut = map->nlut; near = ( astGetLutInterp( map ) == NEAR ); nlutm1 = nlut - 1; /* Calculate the scale factor required. */ scale = 1.0 / map->inc; /* Loop to transform each input point. */ for ( point = 0; point < npoint; point++ ) { /* Extract the input coordinate value. */ value_in = ptr_in[ 0 ][ point ]; /* First check if this is the same value as we transformed last. If so, re-use the last result. */ if ( value_in == map->last_fwd_in ) { value_out = map->last_fwd_out; /* Check for bad input coordinates and generate a bad result if necessary. */ } else if ( value_in == AST__BAD ) { value_out = AST__BAD; /* For nearest-neighbour interpolation, return the value of the lookup table entry corresponding to the input coordinate. */ } else if( near ){ x = ( value_in - map->start ) * scale; xi = floor( x + 0.5 ); ix = (int) xi; if ( ix < 0 || ix >= nlut ) { value_out = AST__BAD; } else { value_out = lut[ ix ]; } /* Otherwise, (for linear interpolation) identify the lookup table entry corresponding to the input coordinate. */ } else { x = ( value_in - map->start ) * scale; xi = floor( x ); ix = (int) xi; /* If the input value lies below the first lookup table entry, extrapolate using the first two table values. */ if ( ix < 0 ) { if( lut[ 0 ] != AST__BAD && lut[ 1 ] != AST__BAD ) { value_out = lut[ 0 ] + x * ( lut[ 1 ] - lut[ 0 ] ); } else { value_out = AST__BAD; } /* If the input value lies above the last lookup table entry (or equals it), extrapolate using the last two table values. */ } else if ( ix >= nlutm1 ) { if( lut[ nlutm1 ] != AST__BAD && lut[ nlut - 2 ] != AST__BAD ) { value_out = lut[ nlutm1 ] + ( x - (double) ( nlutm1 ) ) * ( lut[ nlutm1 ] - lut[ nlut - 2 ] ); } else { value_out = AST__BAD; } /* Otherwise, interpolate between the adjacent entries. */ } else { if( lut[ ix ] != AST__BAD && lut[ ix + 1 ] != AST__BAD ) { fract = x - xi; value_out = lut[ ix ] * ( 1.0 - fract ) + lut[ ix + 1 ] * fract; } else { value_out = AST__BAD; } } } /* Assign the output coordinate value. */ ptr_out[ 0 ][ point ] = value_out; /* Retain the input and output coordinate values for possible re-use in future. */ map->last_fwd_in = value_in; map->last_fwd_out = value_out; } /* Inverse transformation. */ /* ----------------------- */ } else { /* Obtain details of the lookup table to be used by the inverse transformation. This is the same as the forward transformation lookup table, except that any bad values are omitted. Also, get a pointer to a array of flags that indicate if the corresponding lookup table entries were adjacent to a bad value or not in the full lookup table. */ if( map->luti ) { lut = map->luti; flags = map->flagsi; nlut = map->nluti; index = map->indexi; } else { lut = map->lut; flags = NULL; nlut = map->nlut; index = NULL; } near = ( astGetLutInterp( map ) == NEAR ); nlutm1 = nlut - 1; /* Loop to transform each input point. */ for ( point = 0; point < npoint; point++ ) { /* Extract the input coordinate value. */ value_in = ptr_in[ 0 ][ point ]; /* First check if this is the same value as we transformed last. If so, re-use the last result. */ if ( value_in == map->last_inv_in ) { value_out = map->last_inv_out; /* Check for bad input coordinates and generate a bad result if necessary. */ } else if ( value_in == AST__BAD ) { value_out = AST__BAD; /* Otherwise, we can determine an inverse. Note the inverse transformation will not be defined, so will not be attempted, unless all the table entries are monotonically increasing or decreasing, possibly with sections of equal or bad values. */ } else { up = ( lut[ nlutm1 ] > lut[ 0 ] ); /* Perform a binary search to identify two adjacent lookup table elements whose values bracket the input coordinate value. */ i1 = -1; i2 = nlutm1; while ( i2 > ( i1 + 1 ) ) { i = ( i1 + i2 ) / 2; *( ( ( value_in >= lut[ i ] ) == up ) ? &i1 : &i2 ) = i; } /* If the lower table value is equal to the required value, and either of its neighbours is also equal to the required value, then we have been asked to find the inverse in a flat region of the table, so return a bad value. Likewise, if the upper table value is equal to the required value, and either of its neighbours is also equal to the required value, then we have been asked to find the inverse in a flat region of the table, so return a bad value. */ ok = 1; if( lut[ i1 ] == value_in ) { if( i1 > 0 && lut[ i1 - 1 ] == value_in ) ok = 0; if( lut[ i2 ] == value_in ) ok = 0; } else if( lut[ i2 ] == value_in ) { if( i2 < nlutm1 && lut[ i2 + 1 ] == value_in ) ok = 0; if( lut[ i1 ] == value_in ) ok = 0; } if( !ok ) { value_out = AST__BAD; /* If both of the two table elements were adjacent to a bad value in the full lookup table, return a bad output value. */ } else if( flags && ( flags[ i1 ] && flags[ i2 ] ) ) { value_out = AST__BAD; /* Nearest neighbour interpolation: return the closest of i1 or i2. Return AST__BAD if the supplied value is less than either or greater than either. */ } else if( near ) { d1 = lut[ i1 ] - value_in; d2 = lut[ i2 ] - value_in; if( ( d1 > 0.0 && d2 > 0.0 ) || ( d1 < 0.0 && d2 < 0.0 ) ) { value_out = AST__BAD; } else { if( fabs( d1 ) < fabs( d2 ) ){ istart = index ? index[ i1 ] : i1; } else { istart = index ? index[ i2 ] : i2; } value_out = map->start + map->inc * istart; } /* Linear interpolation... */ } else { /* We are interested in the lower bracketing table element. If necessary, restrict this element's index to lie within the table. This causes extrapolation to occur (instead of interpolation) if the input value actually lies outside the range of the lookup table. */ if ( i1 < 0 ) i1 = 0; if ( i1 > ( nlut - 2 ) ) i1 = nlut - 2; /* Interpolate (or extrapolate) to derive the output coordinate value. */ istart = index ? index[ i1 ] : i1; value_out = map->start + map->inc * ( (double) istart + ( ( value_in - lut[ i1 ] ) / ( lut[ i1 + 1 ] - lut[ i1 ] ) ) ); } } /* Assign the output coordinate value. */ ptr_out[ 0 ][ point ] = value_out; /* Retain the input and output coordinate values for possible re-use in future. */ map->last_inv_in = value_in; map->last_inv_out = value_out; } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * LutInterp * Purpose: * Look-up table interpolation method. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute indicates the method to be used when finding the * output value of a LutMap for an input value part way between two * table entries. If it is set to 0 (the default) then linear * interpolation is used. Otherwise, nearest neighbour interpolation * is used. * * Using nearest neighbour interpolation causes AST__BAD to be returned * for any point which falls outside the bounds of the table. Linear * interpolation results in an extrapolated value being returned based * on the two end entries in the table. * * Note, the value of this attribute may changed only if the LutMap * has no more than one reference. That is, an error is reported if the * LutMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * LutMap * All LutMaps have this attribute. *att-- */ astMAKE_CLEAR1(LutMap,LutInterp,lutinterp,-INT_MAX) astMAKE_GET(LutMap,LutInterp,int,LINEAR,( ( this->lutinterp == -INT_MAX ) ? LINEAR : this->lutinterp )) astMAKE_SET1(LutMap,LutInterp,int,lutinterp,(( value == LINEAR ) ? LINEAR : NEAR )) astMAKE_TEST(LutMap,LutInterp,( this->lutinterp != -INT_MAX )) /* *att++ * Name: * LutEpsilon * Purpose: * The relative error of the values held in the took-up table. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the relative error of the values held in the * took-up table. It is used when simplifying a LutMap, to determine * if the LutMap should be considered linear. Setting a larger value * makes it more likely that a LutMap will be replaced by a WinMap * (i.e. a linear Mapping) when simplified. * * The default value is the value of the system constant DBL_EPSILON * (typically around 1e-16 or 2E-16). If the values in the look-up * table were derived from single precision data, it may be appropriate * to set this attribute to a value around 1E-7. * * Note, the value of this attribute may changed only if the LutMap * has no more than one reference. That is, an error is reported if the * LutMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * LutMap * All LutMaps have this attribute. *att-- */ astMAKE_CLEAR1(LutMap,LutEpsilon,lutepsilon,AST__BAD) astMAKE_GET(LutMap,LutEpsilon,double,DBL_EPSILON,( ( this->lutepsilon == AST__BAD ) ? DBL_EPSILON : this->lutepsilon )) astMAKE_SET1(LutMap,LutEpsilon,double,lutepsilon,(value)) astMAKE_TEST(LutMap,LutEpsilon,( this->lutepsilon != AST__BAD )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for LutMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for LutMap objects. * Parameters: * objin * Pointer to the LutMap to be copied. * objout * Pointer to the LutMap being constructed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstLutMap *out; /* Pointer to output LutMap */ AstLutMap *in; /* Pointer to input LutMap */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the input and output LutMaps. */ in= (AstLutMap *) objin; out = (AstLutMap *) objout; /* Nullify all output pointers. */ out->lut = NULL; out->luti = NULL; out->flagsi = NULL; out->indexi = NULL; /* Allocate memory and store a copy of the lookup table data. */ out->lut = astStore( NULL, in->lut, sizeof( double ) * (size_t) in->nlut ); /* Do the arrays used for the inverse transformation, if they exist. */ if( in->luti ) out->luti = astStore( NULL, in->luti, sizeof( double ) * (size_t) in->nluti ); if( in->flagsi ) out->flagsi = astStore( NULL, in->flagsi, sizeof( double ) * (size_t) in->nluti ); if( in->indexi ) out->indexi = astStore( NULL, in->indexi, sizeof( double ) * (size_t) in->nluti ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for LutMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for LutMap objects. * Parameters: * obj * Pointer to the LutMap to be deleted. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstLutMap *this; /* Pointer to LutMap */ /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) obj; /* Free the memory holding the lookup tables, etc. */ this->lut = astFree( this->lut ); this->luti = astFree( this->luti ); this->flagsi = astFree( this->flagsi ); this->indexi = astFree( this->indexi ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for LutMap 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 LutMap class to an output Channel. * Parameters: * this * Pointer to the LutMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Local Constants: */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstLutMap *this; /* Pointer to the LutMap structure */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ double dval; /* Double value */ int ilut; /* Loop counter for table elements */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the LutMap structure. */ this = (AstLutMap *) this_object; /* Write out values representing the instance variables for the LutMap class. Accompany these with appropriate comment strings, possibly depending on the values being written. */ /* Number of lookup table elements. */ astWriteInt( channel, "Nlut", 1, 1, this->nlut, "Number of lookup table elements" ); /* Input coordinate at first element centre. */ astWriteDouble( channel, "Start", ( this->start != 0.0 ), 1, this->start, "Input value at first element" ); /* Element spacing. */ astWriteDouble( channel, "Incr", ( this->inc != 1.0 ), 1, this->inc, "Input value increment between elements" ); /* Interpolation method */ set = TestLutInterp( this, status ); ival = set ? GetLutInterp( this, status ) : astGetLutInterp( this ); astWriteInt( channel, "LutInt", set, 1, ival, "Interpolation method" ); /* Precision */ if( TestLutEpsilon( this, status ) ) { dval = GetLutEpsilon( this, status ); astWriteDouble( channel, "LutEps", 1, 1, dval, "Table relative error" ); } /* Lookup table contents. */ for ( ilut = 0; ilut < this->nlut; ilut++ ) { if( this->lut[ ilut ] != AST__BAD ) { (void) sprintf( buff, "L%d", ilut + 1 ); astWriteDouble( channel, buff, 1, 1, this->lut[ ilut ], ilut ? "" : "Lookup table elements..." ); } } /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsALutMap and astCheckLutMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(LutMap,Mapping) astMAKE_CHECK(LutMap) AstLutMap *astLutMap_( int nlut, const double lut[], double start, double inc, const char *options, int *status, ...) { /* *++ * Name: c astLutMap f AST_LUTMAP * Purpose: * Create a LutMap. * Type: * Public function. * Synopsis: c #include "lutmap.h" c AstLutMap *astLutMap( int nlut, const double lut[], c double start, double inc, c const char *options, ... ) f RESULT = AST_LUTMAP( NLUT, LUT, START, INC, OPTIONS, STATUS ) * Class Membership: * LutMap constructor. * Description: * This function creates a new LutMap and optionally initialises * its attributes. * * A LutMap is a specialised form of Mapping which transforms * 1-dimensional coordinates by using linear interpolation in a * lookup table. Each input coordinate value is first scaled to * give the index of an entry in the table by subtracting a * starting value (the input coordinate corresponding to the first * table entry) and dividing by an increment (the difference in * input coordinate value between adjacent table entries). * * The resulting index will usually contain a fractional part, so * the output coordinate value is then generated by interpolating * linearly between the appropriate entries in the table. If the * index lies outside the range of the table, linear extrapolation * is used based on the two nearest entries (i.e. the two entries * at the start or end of the table, as appropriate). * * If the lookup table entries increase or decrease monotonically, * then the inverse transformation may also be performed. * Parameters: c nlut f NLUT = INTEGER (Given) * The number of entries in the lookup table. This value must be * at least 2. c lut f LUT( NLUT ) = DOUBLE PRECISION (Given) c An array containing the "nlut" f An array containing the * lookup table entries. c start f START = DOUBLE PRECISION (Given) * The input coordinate value which corresponds to the first lookup * table entry. c inc f INC = DOUBLE PRECISION (Given) * The lookup table spacing (the increment in input coordinate * value between successive lookup table entries). This value * may be positive or negative, but must not be zero. 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 LutMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new LutMap. The syntax used is identical to that for the f AST_SET routine. 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 astLutMap() f AST_LUTMAP = INTEGER * A pointer to the new LutMap. * Notes: * - If the entries in the lookup table either increase or decrease * monotonically, then the new LutMap's TranInverse attribute will * have a value of one, indicating that the inverse transformation * can be performed. Otherwise, it will have a value of zero, so * that any attempt to use the inverse transformation will result * in an error. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstLutMap *new; /* Pointer to new LutMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the LutMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitLutMap( NULL, sizeof( AstLutMap ), !class_init, &class_vtab, "LutMap", nlut, lut, start, inc ); /* 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 LutMap'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 LutMap. */ return new; } AstLutMap *astLutMapId_( int nlut, const double lut[], double start, double inc, const char *options, ... ) { /* * Name: * astLutMapId_ * Purpose: * Create a LutMap. * Type: * Private function. * Synopsis: * #include "lutmap.h" * AstLutMap *astLutMapId( int nlut, const double lut[], * double start, double inc, * const char *options, ... ) * Class Membership: * LutMap constructor. * Description: * This function implements the external (public) interface to the * astLutMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astLutMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astLutMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astLutMap_. * Returned Value: * The ID value associated with the new LutMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstLutMap *new; /* Pointer to new LutMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the LutMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitLutMap( NULL, sizeof( AstLutMap ), !class_init, &class_vtab, "LutMap", nlut, lut, start, inc ); /* 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 LutMap'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 LutMap. */ return astMakeId( new ); } AstLutMap *astInitLutMap_( void *mem, size_t size, int init, AstLutMapVtab *vtab, const char *name, int nlut, const double lut[], double start, double inc, int *status ) { /* *+ * Name: * astInitLutMap * Purpose: * Initialise a LutMap. * Type: * Protected function. * Synopsis: * #include "lutmap.h" * AstLutMap *astInitLutMap( void *mem, size_t size, int init, * AstLutMapVtab *vtab, const char *name, * int nlut, const double lut[], * double start, double inc ) * Class Membership: * LutMap initialiser. * Description: * This function is provided for use by class implementations to * initialise a new LutMap object. It allocates memory (if * necessary) to accommodate the LutMap plus any additional data * associated with the derived class. It then initialises a LutMap * 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 LutMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the LutMap is to be * initialised. This must be of sufficient size to accommodate * the LutMap data (sizeof(LutMap)) 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 LutMap (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 LutMap structure, so a valid value must be * supplied even if not required for allocating memory. * init * A logical flag indicating if the LutMap'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 LutMap. * 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). * nlut * The number of elements in the lookup table. This value must * be at least 2. * lut * An array containing the "nlut" lookup table elements. * start * The input coordinate value which corresponds with the first * lookup table element. * inc * The lookup table element spacing (i.e. the increment in input * coordinate value between successive lookup table elements). * Returned Value: * A pointer to the new LutMap. * 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: */ AstLutMap *new; /* Pointer to new LutMap */ double *luti; /* Pointer to table for inverse transformation */ double *p; /* Pointer to next lut element */ int *flagsi; /* Pointer to flags for inverse transformation */ int *indexi; /* Pointer to translation from original to reduced */ int dirn; /* +1 => values increasing, -1 => values decreasing */ int ilut; /* Loop counter for LUT elements */ int nluti; /* Length of "luti" array */ /* Initialise. */ new = NULL; /* Check the global status. */ if ( !astOK ) return new; /* If necessary, initialise the virtual function table. */ if ( init ) astInitLutMapVtab( vtab, name ); /* Check that the number of lookup table elements is valid. */ if ( nlut < 2 ) { astError( AST__LUTIN, "astInitLutMap(%s): Invalid number of lookup " "table elements (%d).", status, name, nlut ); astError( AST__LUTIN, "This value should be at least 2." , status); /* Also check that the input value increment is not zero. */ } else if ( inc == 0.0 ) { astError( AST__LUTII, "astInitLutMap(%s): An input value increment of " "zero between lookup table elements is not allowed.", status, name ); /* Determine if the element values increase or decrease monotonically (except that adjacent entries can be equal). We can only implement the inverse transformation if this is so. The inverse transformation will generate AST__BAD output values for sections of the table that contain equal adjacent values, or hold AST__BAD values. */ } else { dirn = GetMonotonic( nlut, lut, &nluti, &luti, &flagsi, &indexi, status ); /* Initialise a Mapping structure (the parent class) as the first component within the LutMap structure, allocating memory if necessary. Specify that the Mapping should be defined in the forward direction, and conditionally in the inverse direction. */ new = (AstLutMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 1, 1, 1, ( dirn != 0 ) ); if ( astOK ) { /* Initialise the LutMap data. */ /* ---------------------------- */ new->nlut = nlut; new->start = start; new->inc = inc; new->lutinterp = LINEAR; new->lutepsilon = AST__BAD; new->nluti = nluti; new->luti = luti; new->flagsi = flagsi; new->indexi = indexi; /* Allocate memory and store the lookup table. */ new->lut = astStore( NULL, lut, sizeof( double ) * (size_t) nlut ); /* Replace an NaN values by AST__BAD */ p = new->lut; for ( ilut = 0; ilut < nlut; ilut++, p++ ) { if( !astISFINITE(*p) ) *p = AST__BAD; } /* Initialise the retained input and output coordinate values. */ new->last_fwd_in = AST__BAD; new->last_fwd_out = AST__BAD; new->last_inv_in = AST__BAD; new->last_inv_out = AST__BAD; } /* If an error occurred, clean up by deleting the new LutMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new LutMap. */ return new; } AstLutMap *astLoadLutMap_( void *mem, size_t size, AstLutMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadLutMap * Purpose: * Load a LutMap. * Type: * Protected function. * Synopsis: * #include "lutmap.h" * AstLutMap *astLoadLutMap( void *mem, size_t size, * AstLutMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * LutMap loader. * Description: * This function is provided to load a new LutMap 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 * LutMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a LutMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the LutMap is to be * loaded. This must be of sufficient size to accommodate the * LutMap data (sizeof(LutMap)) 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 LutMap (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 LutMap 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(AstLutMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new LutMap. If this is NULL, a pointer * to the (static) virtual function table for the LutMap 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 "LutMap" is used instead. * Returned Value: * A pointer to the new LutMap. * 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: */ AstLutMap *new; /* Pointer to the new LutMap */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int ilut; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Loop counter for table elements */ /* 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 LutMap. In this case the LutMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstLutMap ); vtab = &class_vtab; name = "LutMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitLutMapVtab( 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 LutMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "LutMap" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* Number of lookup table elements. */ new->nlut = astReadInt( channel, "nlut", 2 ); /* Starting input coordinate value. */ new->start = astReadDouble( channel, "start", 0.0 ); /* Input coordinate value increment. */ new->inc = astReadDouble( channel, "incr", 1.0 ); /* Interpolation method */ new->lutinterp = astReadInt( channel, "lutint", LINEAR ); if ( TestLutInterp( new, status ) ) SetLutInterp( new, new->lutinterp, status ); /* Precision */ new->lutepsilon = astReadDouble( channel, "luteps", AST__BAD ); if ( TestLutEpsilon( new, status ) ) SetLutEpsilon( new, new->lutepsilon, status ); /* Allocate memory to hold the lookup table elements. */ new->lut = astMalloc( sizeof( double ) * (size_t) new->nlut ); /* If OK, loop to read each element. */ if ( astOK ) { for ( ilut = 0; ilut < new->nlut; ilut++ ) { (void) sprintf( buff, "l%d", ilut + 1 ); new->lut[ ilut ] = astReadDouble( channel, buff, AST__BAD ); } /* Initialise the retained input and output coordinate values. */ new->last_fwd_in = AST__BAD; new->last_fwd_out = AST__BAD; new->last_inv_in = AST__BAD; new->last_inv_out = AST__BAD; /* See if the array is monotonic increasing or decreasing. */ (void) GetMonotonic( new->nlut, new->lut, &(new->nluti), &(new->luti), &(new->flagsi), &(new->indexi), status ); } } /* If an error occurred, clean up by deleting the new LutMap. */ if ( !astOK ) new = astDelete( new ); /* Return the new LutMap 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. */ double *astGetLutMapInfo_( AstLutMap *this, double *start, double *inc, int *nlut, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,LutMap,GetLutMapInfo))( this, start, inc, nlut, status ); } ast-8.3.0/unitmap.c0000664000175000017500000014073313004147321011060 00000000000000/* *class++ * Name: * UnitMap * Purpose: * Unit (null) Mapping. * Constructor Function: c astUnitMap f AST_UNITMAP * Description: * A UnitMap is a unit (null) Mapping that has no effect on the * coordinates supplied to it. They are simply copied. This can be * useful if a Mapping is required (e.g. to pass to another c function) but you do not want it to have any effect. f routine) but you do not want it to have any effect. * The Nin and Nout attributes of a UnitMap are always equal and * are specified when it is created. * Inheritance: * The UnitMap class inherits from the Mapping class. * Attributes: * The UnitMap class does not define any new attributes beyond * those which are applicable to all Mappings. * Functions: c The UnitMap class does not define any new functions beyond those f The UnitMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S Berry (JAC, Hawaii) * History: * 7-FEB-1996 (RFWS): * Original version. * 13-DEC-1996 (RFWS): * Over-ride the astMapMerge method. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitUnitMapVtab * method. * 10-MAY-2006 (DSB): * Override astEqual. * 17-FEB-2012 (DSB): * In Transform, do not copy the coordinate values if the input and * output array are the same. *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 UnitMap /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "object.h" /* Base Object class */ #include "memory.h" /* AST memory management */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "unitmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(UnitMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(UnitMap,Class_Init) #define class_vtab astGLOBAL(UnitMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstUnitMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstUnitMap *astUnitMapId_( int, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, 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 GetIsLinear( AstMapping *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Dump( AstObject *, AstChannel *, int * ); /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two UnitMaps are equivalent. * Type: * Private function. * Synopsis: * #include "unitmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * UnitMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two UnitMaps are equivalent. * Parameters: * this * Pointer to the first Object (a UnitMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the UnitMaps are equivalent, zero otherwise. * 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: */ AstUnitMap *that; AstUnitMap *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two UnitMap structures. */ this = (AstUnitMap *) this_object; that = (AstUnitMap *) that_object; /* Check the second object is a UnitMap. We know the first is a UnitMap since we have arrived at this implementation of the virtual function. */ if( astIsAUnitMap( that ) ) { /* Get the number of inputs check they are the same for both. */ result = ( astGetNin( this ) == astGetNin( that ) ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* 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 UnitMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * UnitMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one. * Parameters: * this * Pointer to the UnitMap. * status * Pointer to the inherited status variable. */ return 1; } void astInitUnitMapVtab_( AstUnitMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitUnitMapVtab * Purpose: * Initialise a virtual function table for a UnitMap. * Type: * Protected function. * Synopsis: * #include "unitmap.h" * void astInitUnitMapVtab( AstUnitMapVtab *vtab, const char *name ) * Class Membership: * UnitMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the UnitMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAUnitMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->MapSplit = MapSplit; mapping->Rate = Rate; mapping->GetIsLinear = GetIsLinear; /* Declare the class dump function. There is no copy constructor or destructor. */ astSetDump( vtab, Dump, "UnitMap", "Unit (null) Mapping" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a UnitMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * UnitMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated UnitMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated UnitMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated UnitMap which is to be merged with * its neighbours. This should be a cloned copy of the UnitMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * UnitMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated UnitMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *new; /* Pointer to replacement UnitMap */ const char *class; /* Pointer to Mapping class string */ int i1; /* Index of first UnitMap to merge */ int i2; /* Index of last UnitMap to merge */ int i; /* Loop counter for Mappings */ int ngone; /* Number of UnitMaps eliminated */ int nin; /* Number of coordinates for UnitMap */ int result; /* Result value to return */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* If the Mapping sequence consists of a single UnitMap, simply check if the asociated Invert flag is set, and clear it if necessary. */ if ( *nmap == 1 ) { if ( ( *invert_list )[ 0 ] ) { ( *invert_list )[ 0 ] = 0; /* Note if the Mapping sequence was modified. */ result = 0; } /* In series. */ /* ========== */ /* If a UnitMap occurs in series with any other Mapping, it can simply be eliminated, so annul its Mapping pointer. */ } else if ( *nmap > 1 ) { if ( series ) { ( *map_list )[ where ] = astAnnul( ( *map_list )[ where ] ); /* Loop to move any following pointers and their Invert flags down in the array to fill the gap, and clear the vacated elements at the end of the arrays. */ for ( i = where + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = where; /* In parallel. */ /* ============ */ /* If a UnitMap occurs in parallel with other Mappings, it can be merged with any UnitMaps on either side of itself. */ } else { /* Initialise indices to identify any adjacent UnitMaps and the number of coordinates to be handled by the replacement. */ i1 = i2 = where; nin = astGetNin( ( *map_list )[ where ] ); /* Loop to inspect earlier Mappings, obtaining the Mapping Class name and checking it is "UnitMap". Quit looping as soon as any other class of Mapping is found. */ while ( i1 - 1 >= 0 ) { class = astGetClass( ( *map_list )[ i1 - 1 ] ); if ( !astOK || strcmp( class, "UnitMap" ) ) break; /* Update the index of the earliest UnitMap that is to be merged and increment the total number of coordinates involved. */ i1--; nin += astGetNin( ( *map_list )[ i1 ] ); } /* Repeat the above process to inspect any later Mappings in the sequence. */ while ( i2 + 1 < *nmap ) { class = astGetClass( ( *map_list )[ i2 + 1 ] ); if ( !astOK || strcmp( class, "UnitMap" ) ) break; i2++; nin += astGetNin( ( *map_list )[ i2 ] ); } /* Calculate the net number of Mappings that can be removed from the sequence and check if this is zero, meaning that there were no adjacent UnitMaps to merge with. */ if ( astOK ) { ngone = i2 - i1; if ( !ngone ) { /* If so, simply check if the nominated UnitMap's Invert flag is set, and clear it if necessary. */ if ( ( *invert_list )[ where ] ) { ( *invert_list )[ where ] = 0; /* Note if the Mapping sequence was modified. */ result = where; } /* If UnitMaps can be merged, create the replacement UnitMap. */ } else { new = (AstMapping *) astUnitMap( nin, "", status ); if ( astOK ) { /* Annul the pointers to all the UnitMaps that are being replaced. */ for ( i = i1; i <= i2; i++ ) { ( *map_list )[ i ] = astAnnul( ( *map_list )[ i ] ); } /* Insert the new pointer and the associated Invert flag. */ ( *map_list )[ i1 ] = new; ( *invert_list )[ i1 ] = 0; /* Loop to close the resulting gap by moving subsequent elements down in the arrays. */ for ( i = i2 + 1; i < *nmap; i++ ) { ( *map_list )[ i - ngone ] = ( *map_list )[ i ]; ( *invert_list )[ i - ngone ] = ( *invert_list )[ i ]; } /* Clear the vacated elements at the end. */ for ( i = *nmap - ngone; i < *nmap; i++ ) { ( *map_list )[ i ] = NULL; ( *invert_list )[ i ] = 0; } /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap ) -= ngone; result = i1; } } } } } /* Return the result. */ return result; } 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 * UnitMap. * Type: * Private function. * Synopsis: * #include "unitmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * UnitMap 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 UnitMap. This is only possible if the specified inputs * correspond to some subset of the UnitMap outputs. That is, there * must exist a subset of the UnitMap outputs for which each output * depends only on the selected UnitMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied UnitMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the UnitMap to be split (the UnitMap 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 UnitMap, 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 UnitMap 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 UnitMap. 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: */ AstUnitMap *this; /* Pointer to UnitMap structure */ int *result; /* Pointer to returned array */ int i; /* Loop count */ int iin; /* Mapping input index */ int mnin; /* No. of Mapping inputs */ int ok; /* Are input indices OK? */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the UnitMap structure. */ this = (AstUnitMap *) this_map; /* Allocate memory for the returned array and create a UnitMap with the required number of axes. */ result = astMalloc( sizeof( int )*(size_t) nin ); *map = (AstMapping *) astUnitMap( nin, "", status ); /* Check pointers can be used safely. */ if( astOK ) { /* Store the required output axis indices. At the same time check that each axis is valid. */ mnin = astGetNin( this ); ok = 1; for( i = 0; i < nin; i++ ) { iin = in[ i ]; if( iin >= 0 && iin < mnin ) { result[ i ] = iin; } else { ok = 0; break; } } /* If the "in" array contained any invalid values, free the returned resources. */ if( !ok ) { result = astFree( result ); *map = astAnnul( *map ); } } /* 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 double Rate( AstMapping *this, 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 "unitmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * UnitMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ return ( ax1 == ax2 ) ? 1.0 : 0.0; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a UnitMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "unitmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * UnitMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a UnitMap and a set of points encapsulated in a * PointSet and transforms the points so as to perform the identity * transformation (i.e. simply copies the coordinate values). * Parameters: * this * Pointer to the UnitMap. * in * Pointer to the PointSet holding the input coordinate data. * forward * A non-zero value indicates that the forward coordinate transformation * should be applied, while a zero value requests the inverse * transformation. In this case, both transformations are equivalent. * out * Pointer to a PointSet which will hold the transformed (output) * coordinate values. A NULL value may also be given, in which case a * new PointSet will be created by this function. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the output (possibly new) PointSet. * Notes: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the UnitMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstUnitMap *map; /* Pointer to UnitMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ int coord; /* Loop counter for coordinates */ int ncoord_in; /* Number of coordinates per input point */ int npoint; /* Number of points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the UnitMap. */ map = (AstUnitMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the coordinate copy needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* We need not determine whether to apply the forward or inverse transformation, as they are both the same. */ /* Copy the coordinate values. */ /* --------------------------- */ if ( astOK ) { /* Loop to copy the values for each coordinate. Use a memory copy for speed. Do not do the copy if the input and output arrays are the same. */ for ( coord = 0; coord < ncoord_in; coord++ ) { if( ptr_out[ coord ] != ptr_in[ coord ] ) { (void) memcpy( (void *) ptr_out[ coord ], (const void *) ptr_in[ coord ], sizeof( double ) * (size_t) npoint ); } } } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ /* No copy constructor is needed, as a byte-by-byte copy suffices. */ /* Destructor. */ /* ----------- */ /* No destructor is needed as no memory, etc. needs freeing. */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for UnitMap 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 UnitMap class to an output Channel. * Parameters: * this * Pointer to the UnitMap 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 Variables: */ AstUnitMap *this; /* Pointer to the UnitMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the UnitMap structure. */ this = (AstUnitMap *) this_object; /* Write out values representing the instance variables for the UnitMap 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAUnitMap and astCheckUnitMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(UnitMap,Mapping) astMAKE_CHECK(UnitMap) AstUnitMap *astUnitMap_( int ncoord, const char *options, int *status, ...) { /* *++ * Name: c astUnitMap f AST_UNITMAP * Purpose: * Create a UnitMap. * Type: * Public function. * Synopsis: c #include "unitmap.h" c AstUnitMap *astUnitMap( int ncoord, const char *options, ... ) f RESULT = AST_UNITMAP( NCOORD, OPTIONS, STATUS ) * Class Membership: * UnitMap constructor. * Description: * This function creates a new UnitMap and optionally initialises * its attributes. * * A UnitMap is a unit (null) Mapping that has no effect on the * coordinates supplied to it. They are simply copied. This can be * useful if a Mapping is required (e.g. to pass to another c function) but you do not want it to have any effect. f routine) but you do not want it to have any effect. * Parameters: c ncoord f NCOORD = INTEGER (Given) * The number of input and output coordinates (these numbers are * necessarily the same). 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 UnitMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new UnitMap. The syntax used is identical to that for the f AST_SET routine. 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 astUnitMap() f AST_UNITMAP = INTEGER * A pointer to the new UnitMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstUnitMap *new; /* Pointer to new UnitMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the UnitMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitUnitMap( NULL, sizeof( AstUnitMap ), !class_init, &class_vtab, "UnitMap", ncoord ); /* 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 UnitMap'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 UnitMap. */ return new; } AstUnitMap *astUnitMapId_( int ncoord, const char *options, ... ) { /* * Name: * astUnitMapId_ * Purpose: * Create a UnitMap. * Type: * Private function. * Synopsis: * #include "unitmap.h" * AstUnitMap *astUnitMapId_( int ncoord, const char *options, ... ) * Class Membership: * UnitMap constructor. * Description: * This function implements the external (public) interface to the * astUnitMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astUnitMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astUnitMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astUnitMap_. * Returned Value: * The ID value associated with the new UnitMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstUnitMap *new; /* Pointer to new UnitMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the UnitMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitUnitMap( NULL, sizeof( AstUnitMap ), !class_init, &class_vtab, "UnitMap", ncoord ); /* 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 UnitMap'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 UnitMap. */ return astMakeId( new ); } AstUnitMap *astInitUnitMap_( void *mem, size_t size, int init, AstUnitMapVtab *vtab, const char *name, int ncoord, int *status ) { /* *+ * Name: * astInitUnitMap * Purpose: * Initialise a UnitMap. * Type: * Protected function. * Synopsis: * #include "unitmap.h" * AstUnitMap *astInitUnitMap( void *mem, size_t size, int init, * AstUnitMapVtab *vtab, const char *name, * int ncoord ) * Class Membership: * UnitMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new UnitMap object. It allocates memory (if necessary) to accommodate * the UnitMap plus any additional data associated with the derived class. * It then initialises a UnitMap 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 UnitMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the UnitMap is to be initialised. * This must be of sufficient size to accommodate the UnitMap data * (sizeof(UnitMap)) 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 UnitMap (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 UnitMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the UnitMap'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 UnitMap. * 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 Object * astClass function). * ncoord * The number of coordinate values per point. * Returned Value: * A pointer to the new UnitMap. * 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: */ AstUnitMap *new; /* Pointer to new UnitMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitUnitMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a Mapping structure (the parent class) as the first component within the UnitMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstUnitMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, ncoord, ncoord, 1, 1 ); if ( astOK ) { /* Initialise the UnitMap data. */ /* ---------------------------- */ /* There is nothing else to store. */ /* If an error occurred, clean up by deleting the new object (if any other resources had been allocated, we would free these first). */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new object. */ return new; } AstUnitMap *astLoadUnitMap_( void *mem, size_t size, AstUnitMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadUnitMap * Purpose: * Load a UnitMap. * Type: * Protected function. * Synopsis: * #include "unitmap.h" * AstUnitMap *astLoadUnitMap( void *mem, size_t size, * AstUnitMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * UnitMap loader. * Description: * This function is provided to load a new UnitMap 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 * UnitMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a UnitMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the UnitMap is to be * loaded. This must be of sufficient size to accommodate the * UnitMap data (sizeof(UnitMap)) 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 UnitMap (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 UnitMap 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(AstUnitMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new UnitMap. If this is NULL, a pointer * to the (static) virtual function table for the UnitMap 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 "UnitMap" is used instead. * Returned Value: * A pointer to the new UnitMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstUnitMap *new; /* Pointer to the new UnitMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this UnitMap. In this case the UnitMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstUnitMap ); vtab = &class_vtab; name = "UnitMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitUnitMapVtab( 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 UnitMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "UnitMap" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* If an error occurred, clean up by deleting the new UnitMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new UnitMap pointer. */ return new; } /* 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. */ /* There are none of these. */ ast-8.3.0/ffitstable.c0000664000175000017500000001643213004147321011524 00000000000000/* *+ * Name: * ffitstable.c * Purpose: * Define a FORTRAN 77 interface to the AST FitsTable class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the FitsTable class. * Routines Defined: * AST_ISAFITSTABLE * AST_FITSTABLE * Copyright: * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S.Berry (Starlink) * History: * 25-NOV-2010 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "ast_err.h" /* AST error codes */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "fitstable.h" /* C interface to the FitsTable class */ F77_LOGICAL_FUNCTION(ast_isafitstable)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astWatchSTATUS( astAt( "AST_ISAFITSTABLE", NULL, 0 ); RESULT = astIsAFitsTable( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_fitstable)( INTEGER(HEADER), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(HEADER) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_FITSTABLE", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astFitsTable( astI2P( *HEADER ), "%s", options ) ); astFree( options ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_gettableheader)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETTABLEHEADER", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetTableHeader( astI2P( *THIS ) ) ); ) return RESULT; } F77_SUBROUTINE(ast_puttableheader)( INTEGER(THIS), INTEGER(HEADER), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(HEADER) astAt( "AST_PUTTABLEHEADER", NULL, 0 ); astWatchSTATUS( astPutTableHeader( astI2P( *THIS ), astI2P( *HEADER ) ); ) } F77_INTEGER_FUNCTION(ast_columnnull)( INTEGER(THIS), CHARACTER(COLUMN), LOGICAL(SET), INTEGER(NEWVAL), LOGICAL(WASSET), LOGICAL(HASNULL), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) GENPTR_LOGICAL(SET) GENPTR_INTEGER(NEWVAL) GENPTR_LOGICAL(WASSET) GENPTR_LOGICAL(HASNULL) F77_INTEGER_TYPE(RESULT); int wasset, hasnull; char *column; astAt( "AST_COLUMNNULL", NULL, 0 ); astWatchSTATUS( column = astString( COLUMN, COLUMN_length ); RESULT = astColumnNull( astI2P( *THIS ), column, F77_ISTRUE( *SET ) ? 1 : 0, *NEWVAL, &wasset, &hasnull ); *WASSET = wasset ? F77_TRUE : F77_FALSE; *HASNULL = hasnull ? F77_TRUE : F77_FALSE; astFree( column ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_columnsize)( INTEGER(THIS), CHARACTER(COLUMN), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) F77_INTEGER_TYPE(RESULT); char *column; size_t result; astAt( "AST_COLUMNSIZE", NULL, 0 ); astWatchSTATUS( column = astString( COLUMN, COLUMN_length ); result = astColumnSize( astI2P( *THIS ), column ); astFree( column ); RESULT = result; if( (size_t) RESULT != result && astOK ) { astError( AST__BIGTAB, "AST_COLUMNSIZE(FitsTable): The number of bytes in the " "column is too large to fit in a Fortran INTEGER.", status ); } ) return RESULT; } F77_SUBROUTINE(ast_getcolumndata)( INTEGER(THIS), CHARACTER(COLUMN), REAL(RNULL), DOUBLE(DNULL), INTEGER(MXSIZE), BYTE_ARRAY(COLDATA), INTEGER(NELEM), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) GENPTR_REAL(RNULL) GENPTR_DOUBLE(DNULL) GENPTR_INTEGER(MXSIZE) GENPTR_BYTE_ARRAY(COLDATA) GENPTR_INTEGER(NELEM) char *column; astAt( "AST_GETCOLUMNDATA", NULL, 0 ); astWatchSTATUS( column = astString( COLUMN, COLUMN_length ); astGetColumnData( astI2P( *THIS ), column, *RNULL, *DNULL, *MXSIZE, (void *) COLDATA, NELEM ); astFree( column ); ) } F77_SUBROUTINE(ast_putcolumndata)( INTEGER(THIS), CHARACTER(COLUMN), INTEGER(CLEN), INTEGER(SIZE), BYTE_ARRAY(COLDATA), INTEGER(STATUS) TRAIL(COLUMN) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(COLUMN) GENPTR_INTEGER(CLEN) GENPTR_INTEGER(SIZE) GENPTR_BYTE_ARRAY(COLDATA) char *column; astAt( "AST_PUTCOLUMNDATA", NULL, 0 ); astWatchSTATUS( column = astString( COLUMN, COLUMN_length ); astPutColumnData( astI2P( *THIS ), column, *CLEN, *SIZE, (void *) COLDATA ); astFree( column ); ) } ast-8.3.0/sphmap.h0000664000175000017500000003113613004147321010674 00000000000000#if !defined( SPHMAP_INCLUDED ) /* Include this file only once */ #define SPHMAP_INCLUDED /* *+ * Name: * sphmap.h * Type: * C include file. * Purpose: * Define the interface to the SphMap class. * Invocation: * #include "sphmap.h" * Description: * This include file defines the interface to the SphMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The SphMap class implements Mappings which maps positions from * 3-dimensional Cartesian coordinates into 2-dimensional spherical * coordinates (i.e. longitude and latitude on a unit sphere). The * inverse Mapping always produces vectors of unit length. * * The spherical coordinates are longitude (positive anti-clockwise * looking from the positive latitude pole) and latitude. The * Cartesian coordinates are right-handed, with the x-axis (axis 1) * at zero longitude and latitude, and the z-axis (axis 3) at the * positive latitude pole. * * At either pole, the longitude is set to the value of the PolarLong * attribute. If the Cartesian coordinates are all zero, then the * longitude and latitude values are set to AST__BAD. * Inheritance: * The SphMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * PolarLong (double) * This attribute holds the longitude value, in radians, to be * returned when a Cartesian position corresponding to either the north * or south pole is transformed into spherical coordinates. The * default value is zero. * UnitRadius (integer) * This is a boolean attribute which indicates whether the * 3-dimensional vectors which are supplied as input to a SphMap * are known to always have unit length, so that they lie on a * unit sphere centred on the origin. * * If this condition is true (indicated by setting UnitRadius * non-zero), it implies that a CmpMap which is composed of a * SphMap applied in the forward direction followed by a similar * SphMap applied in the inverse direction may be simplified * (e.g. by astSimplify) to become a UnitMap. This is because * the input and output vectors will both have unit length and * will therefore have the same coordinate values. * * If UnitRadius is zero (the default), then although the output * vector produced by the CmpMap (above) will still have unit * length, the input vector may not have. This will, in general, * change the coordinate values, so it prevents the pair of * SphMaps being simplified. * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a SphMap. * astGetAttrib * Get an attribute value for a SphMap. * astMapMerge * Simplify a sequence of Mappings containing a SphMap. * astSetAttrib * Set an attribute value for a SphMap. * astTestAttrib * Test if an attribute value has been set for a SphMap. * astTransform * Apply a SphMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astClearUnitRadius * Clear the UnitRadius attribute value for a SphMap. * astGetUnitRadius * Get the UnitRadius attribute value for a SphMap. * astSetUnitRadius * Set the UnitRadius attribute value for a SphMap. * astTestUnitRadius * Test if a UnitRadius attribute value has been set for a SphMap. * astClearPolarLong * Clear the PolarLong attribute value for a SphMap. * astGetPolarLong * Get the PolarLong attribute value for a SphMap. * astSetPolarLong * Set the PolarLong attribute value for a SphMap. * astTestPolarLong * Test if a PolarLong attribute value has been set for a SphMap. * Other Class Functions: * Public: * astIsASphMap * Test class membership. * astSphMap * Create a SphMap. * * Protected: * astCheckSphMap * Validate class membership. * astInitSphMap * Initialise a SphMap. * astInitSphMapVtab * Initialise the virtual function table for the SphMap class. * astLoadSphMap * Load a SphMap. * Macros: * None. * Type Definitions: * Public: * AstSphMap * SphMap object type. * * Protected: * AstSphMapVtab * SphMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 25-OCT-1996 (DSB): * Original version. * 24-MAR-1998 (RFWS): * Override the astMapMerge method. * 4-SEP-1998 (DSB): * Added UnitRadius attribute. * 8-JAN-2003 (DSB): * Added protected astInitSphMapVtab method. * 11-JUN-2003 (DSB): * Added PolarLong attribute. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* SphMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSphMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double polarlong; /* Longitude to assign to either pole */ int unitradius; /* Are input vectors always of unit length? */ } AstSphMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSphMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetUnitRadius)( AstSphMap *, int * ); int (* TestUnitRadius)( AstSphMap *, int * ); void (* ClearUnitRadius)( AstSphMap *, int * ); void (* SetUnitRadius)( AstSphMap *, int, int * ); double (* GetPolarLong)( AstSphMap *, int * ); int (* TestPolarLong)( AstSphMap *, int * ); void (* ClearPolarLong)( AstSphMap *, int * ); void (* SetPolarLong)( AstSphMap *, double, int * ); } AstSphMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstSphMapGlobals { AstSphMapVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 51 ]; } AstSphMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SphMap) /* Check class membership */ astPROTO_ISA(SphMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSphMap *astSphMap_( const char *, int *, ...); #else AstSphMap *astSphMapId_( const char *, ...)__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSphMap *astInitSphMap_( void *, size_t, int, AstSphMapVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitSphMapVtab_( AstSphMapVtab *, const char *, int * ); /* Loader. */ AstSphMap *astLoadSphMap_( void *, size_t, AstSphMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitSphMapGlobals_( AstSphMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astGetUnitRadius_( AstSphMap *, int * ); int astTestUnitRadius_( AstSphMap *, int * ); void astClearUnitRadius_( AstSphMap *, int * ); void astSetUnitRadius_( AstSphMap *, int, int * ); double astGetPolarLong_( AstSphMap *, int * ); int astTestPolarLong_( AstSphMap *, int * ); void astClearPolarLong_( AstSphMap *, int * ); void astSetPolarLong_( AstSphMap *, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSphMap(this) astINVOKE_CHECK(SphMap,this,0) #define astVerifySphMap(this) astINVOKE_CHECK(SphMap,this,1) /* Test class membership. */ #define astIsASphMap(this) astINVOKE_ISA(SphMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSphMap astINVOKE(F,astSphMap_) #else #define astSphMap astINVOKE(F,astSphMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define \ astInitSphMap(mem,size,init,vtab,name) \ astINVOKE(O,astInitSphMap_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSphMapVtab(vtab,name) astINVOKE(V,astInitSphMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSphMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSphMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSphMap to validate SphMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearUnitRadius(this) astINVOKE(V,astClearUnitRadius_(astCheckSphMap(this),STATUS_PTR)) #define astGetUnitRadius(this) astINVOKE(V,astGetUnitRadius_(astCheckSphMap(this),STATUS_PTR)) #define astSetUnitRadius(this,value) astINVOKE(V,astSetUnitRadius_(astCheckSphMap(this),value,STATUS_PTR)) #define astTestUnitRadius(this) astINVOKE(V,astTestUnitRadius_(astCheckSphMap(this),STATUS_PTR)) #define astClearPolarLong(this) astINVOKE(V,astClearPolarLong_(astCheckSphMap(this),STATUS_PTR)) #define astGetPolarLong(this) astINVOKE(V,astGetPolarLong_(astCheckSphMap(this),STATUS_PTR)) #define astSetPolarLong(this,value) astINVOKE(V,astSetPolarLong_(astCheckSphMap(this),value,STATUS_PTR)) #define astTestPolarLong(this) astINVOKE(V,astTestPolarLong_(astCheckSphMap(this),STATUS_PTR)) #endif #endif ast-8.3.0/polygon.h0000664000175000017500000003567413004147321011106 00000000000000#if !defined( POLYGON_INCLUDED ) /* Include this file only once */ #define POLYGON_INCLUDED /* *+ * Name: * polygon.h * Type: * C include file. * Purpose: * Define the interface to the Polygon class. * Invocation: * #include "polygon.h" * Description: * This include file defines the interface to the Polygon class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The Polygon class implements a Region which represents a collection * of points in a Frame. * Inheritance: * The Polygon class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-OCT-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "frame.h" /* Coordinate systems */ #include "region.h" /* Coordinate regions (parent class) */ #include "timeframe.h" /* For AST__LT definition */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Flags used to indicate how astOutline should define the pixel region to be outlined. We omit AST__LT here since it is defined in timeframe.h (with value 11). */ #define AST__LE 2 #define AST__EQ 3 #define AST__GE 4 #define AST__GT 5 #define AST__NE 6 /* Type Definitions. */ /* ================= */ /* Polygon structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPolygon { /* Attributes inherited from the parent class. */ AstRegion region; /* Parent class structure */ /* Attributes specific to objects in this class. */ double in[2]; /* A point which is inside the polygon */ double lbnd[2]; /* Lower axis limits of bounding box */ double ubnd[2]; /* Upper axis limits of bounding box */ AstLineDef **edges; /* Cached description of edges */ double *startsat; /* Perimeter distance to each vertex */ double totlen; /* Total perimeter distance round polygon */ int acw; /* Are vertices stored in anti-clockwise order? */ int stale; /* Is cached information stale? */ int simp_vertices; /* Simplify by transforming vertices? */ } AstPolygon; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPolygonVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstPolygon *(* Downsize)( AstPolygon *, double, int, int * ); int (* GetSimpVertices)( AstPolygon *, int * ); int (* TestSimpVertices)( AstPolygon *, int * ); void (* ClearSimpVertices)( AstPolygon *, int * ); void (* SetSimpVertices)( AstPolygon *, int, int * ); } AstPolygonVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstPolygonGlobals { AstPolygonVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 51 ]; } AstPolygonGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitPolygonGlobals_( AstPolygonGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Polygon) /* Check class membership */ astPROTO_ISA(Polygon) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstPolygon *astPolygon_( void *, int, int, const double *, AstRegion *, const char *, int *, ...); #else AstPolygon *astPolygonId_( void *, int, int, const double *, AstRegion *, const char *, ... )__attribute__((format(printf,6,7))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPolygon *astInitPolygon_( void *, size_t, int, AstPolygonVtab *, const char *, AstFrame *, int, int, const double *, AstRegion *, int * ); /* Vtab initialiser. */ void astInitPolygonVtab_( AstPolygonVtab *, const char *, int * ); /* Loader. */ AstPolygon *astLoadPolygon_( void *, size_t, AstPolygonVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstPolygon *astDownsize_( AstPolygon *, double, int, int * ); #if HAVE_LONG_DOUBLE /* Not normally implemented */ AstPolygon *astOutlineLD_( long double, int, const long double[], const int[2], const int[2], double, int, const int[2], int, int * ); #endif AstPolygon *astOutlineB_( signed char, int, const signed char[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineD_( double, int, const double[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineF_( float, int, const float[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineI_( int, int, const int[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineL_( long int, int, const long int[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineS_( short int, int, const short int[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineUB_( unsigned char, int, const unsigned char[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineUI_( unsigned int, int, const unsigned int[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineUL_( unsigned long int, int, const unsigned long int[], const int[2], const int[2], double, int, const int[2], int, int * ); AstPolygon *astOutlineUS_( unsigned short int, int, const unsigned short int[], const int[2], const int[2], double, int, const int[2], int, int * ); #if HAVE_LONG_DOUBLE /* Not normally implemented */ AstPolygon *astConvexLD_( long double, int, const long double[], const int[2], const int[2], int, int * ); #endif AstPolygon *astConvexB_( signed char, int, const signed char[], const int[2], const int[2], int, int * ); AstPolygon *astConvexD_( double, int, const double[], const int[2], const int[2], int, int * ); AstPolygon *astConvexF_( float, int, const float[], const int[2], const int[2], int, int * ); AstPolygon *astConvexI_( int, int, const int[], const int[2], const int[2], int, int * ); AstPolygon *astConvexL_( long int, int, const long int[], const int[2], const int[2], int, int * ); AstPolygon *astConvexS_( short int, int, const short int[], const int[2], const int[2], int, int * ); AstPolygon *astConvexUB_( unsigned char, int, const unsigned char[], const int[2], const int[2], int, int * ); AstPolygon *astConvexUI_( unsigned int, int, const unsigned int[], const int[2], const int[2], int, int * ); AstPolygon *astConvexUL_( unsigned long int, int, const unsigned long int[], const int[2], const int[2], int, int * ); AstPolygon *astConvexUS_( unsigned short int, int, const unsigned short int[], const int[2], const int[2], int, int * ); # if defined(astCLASS) /* Protected */ int astGetSimpVertices_( AstPolygon *, int * ); int astTestSimpVertices_( AstPolygon *, int * ); void astClearSimpVertices_( AstPolygon *, int * ); void astSetSimpVertices_( AstPolygon *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPolygon(this) astINVOKE_CHECK(Polygon,this,0) #define astVerifyPolygon(this) astINVOKE_CHECK(Polygon,this,1) /* Test class membership. */ #define astIsAPolygon(this) astINVOKE_ISA(Polygon,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astPolygon astINVOKE(F,astPolygon_) #else #define astPolygon astINVOKE(F,astPolygonId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPolygon(mem,size,init,vtab,name,frame,npnt,indim,points,unc) \ astINVOKE(O,astInitPolygon_(mem,size,init,vtab,name,frame,npnt,indim,points,unc,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPolygonVtab(vtab,name) astINVOKE(V,astInitPolygonVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPolygon(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPolygon_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckPolygon to validate Polygon pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astDownsize(this,maxerr,maxvert) \ astINVOKE(O,astDownsize_(astCheckPolygon(this),maxerr,maxvert,STATUS_PTR)) #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define astOutlineLD(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineLD_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #endif #define astOutlineB(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineB_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineD(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineD_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineF(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineF_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineI(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineI_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineL(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineL_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineS(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineS_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineUB(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineUB_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineUI(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineUI_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineUL(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineUL_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #define astOutlineUS(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix) \ astINVOKE(O,astOutlineUS_(value,oper,array,lbnd,ubnd,maxerr,maxvert,inside,starpix,STATUS_PTR)) #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define astConvexLD(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O,astConvexLD_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #endif #define astConvexB(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexB_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexD(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexD_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexF(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexF_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexI(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexI_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexL(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexL_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexS(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexS_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexUB(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexUB_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexUI(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexUI_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexUL(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexUL_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #define astConvexUS(value,oper,array,lbnd,ubnd,starpix) \ astINVOKE(O, astConvexUS_(value,oper,array,lbnd,ubnd,starpix,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astClearSimpVertices(this) \ astINVOKE(V,astClearSimpVertices_(astCheckPolygon(this),STATUS_PTR)) #define astGetSimpVertices(this) \ astINVOKE(V,astGetSimpVertices_(astCheckPolygon(this),STATUS_PTR)) #define astSetSimpVertices(this,value) \ astINVOKE(V,astSetSimpVertices_(astCheckPolygon(this),value,STATUS_PTR)) #define astTestSimpVertices(this) \ astINVOKE(V,astTestSimpVertices_(astCheckPolygon(this),STATUS_PTR)) #endif #endif ast-8.3.0/xml.c0000664000175000017500000066444113004147321010212 00000000000000/* * Name: * xml.c * Purpose: * Implement XML functions for AST. * Description: * This file implements the Xml module which provides generic XML * reading and writing functions for the XmlChan class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-OCT-2003 (DSB): * Original version. * 12-JAN-2004 (DSB): * Major revisions. * 10-FEB-2004 (DSB): * - Added debug conditional code to keep track of memory leaks. * - Other minor bug fixes. * 6-FEB-2004 (DSB): * DefaultURI and astXmlAddURI modified to allow a blank URI to be * used to ignore a default namespace URI provided by an enclosing * element. * 29-NOV-2004 (DSB): * Added astXmlGetType method. * 27-JAN-2005 (DSB): * - Move astXmlTrace and associated code into conditional * compilation blokc (included if DEBUG macro is defined). This * speeds up the create and destruction of XmlObjects in non-DEBUG code. * - Renamed the private Delete function as astXmlDelete and gave * it protected access. * - Modify astXmlDelete so that it can succesfully annul objects * which have no parent. * - Include extra info in some error messages. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 10-DEC-2008 (DSB): * Allow a prefix to be included with the attribute name in * astXmlGetAttributeValue. */ /* Module Constants. */ /* ----------------- */ /* Set the name of the module we are implementing. This indicates to the header files that define class interfaces that they should make "protected" symbols available. NB, this module is not a proper AST class, but it defines this macro sanyway in order to get the protected symbols defined in memory.h */ #define astCLASS Xml #define IND_INC 3 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "memory.h" /* Interface to the memory management module */ #include "error.h" /* Interface to the error module */ #include "xml.h" /* Interface to this module */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* * Name: * MAKE_CHECK * Type: * Private macro. * Purpose: * Implement the astXmlCheck_ function for XML structures. * Synopsis: * #include "xml.h" * MAKE_CHECK(type,id) * Class Membership: * Defined by the xml module. * Description: * This macro expands to an implementation of the protected * astXmlCheck_ function (q.v.) which validates membership of * a specified XML data type. * Parameters: * type * The type whose membership is to be validated (e.g. "Element" not * "XmlElement"). * id * The constant (e.g. "AST__XMLELEM") defining the data type. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_CHECK(type,id) \ \ /* Declare the function */ \ AstXml##type *astXmlCheck##type##_( void *this, int nullok, int *status ) { \ \ /* Local Variables: */\ AstXml##type *result; /* The returned pointer */\ \ /* Check the global error status. If an error has already occurred just\ return the supplied pointer. This is so that functions such as\ astXmlAnnul which do not check the inherited status receive the\ supplied pointer. */\ if( !astOK ) return this;\ \ /* Initialise */\ result = NULL;\ \ /* If the pointer is NULL issue an error if nullok is zero. */\ if( !this ) {\ if( !nullok ) astError( AST__PTRIN, "astXmlCheck"#type": Invalid "\ "NULL pointer supplied." , status);\ \ /* Otherwise get the "type" component which holds a magic value for each\ different class of structure. Compare this value against all valid \ classes of structure. If no match is found, the pointer does not \ identify an suitable structure, and so report an error and return \ NULL. */\ } else {\ if( !astXmlCheckType( ( AstXmlObject * ) this, id ) ) {\ astError( AST__PTRIN, "astXmlCheck"#type": Invalid pointer "\ "supplied; pointer to AstXml"#type" required." , status);\ } else {\ result = (AstXml##type *) this;\ }\ }\ \ /* Return the result. */\ return result;\ } /* Module variables. */ /* ================= */ /* Define macros for accessing all items of thread-safe global data used by this module. */ #ifdef THREAD_SAFE #define next_id astGLOBAL(Xml,Next_ID) #define gettag_buff astGLOBAL(Xml,GetTag_Buff) #define GLOBAL_inits globals->Next_ID = 0; astMAKE_INITGLOBALS(Xml) /* Set up mutexes */ static pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX1 pthread_mutex_lock( &mutex1 ); #define UNLOCK_MUTEX1 pthread_mutex_unlock( &mutex1 ); /* If thread safety is not needed, declare globals at static variables. */ #else static int next_id = 0; static char gettag_buff[ AST__XML_GETTAG_BUFF_LEN + 1 ]; #define LOCK_MUTEX1 #define UNLOCK_MUTEX1 #ifdef DEBUG /* Not available in thread-safe compilations */ static int nobj = 0; static AstXmlObject **existing_objects = NULL; #endif #endif /* Function prototypes. */ /* ==================== */ /* Private member functions. */ /* ------------------------- */ static AstXmlAttribute *FindAttribute( AstXmlElement *, const char *, int * ); static AstXmlAttribute *NewAttribute( const char *, const char *, const char *, int * ); static AstXmlDocument *NewDocument( int * ); static AstXmlPrologue *NewPrologue( AstXmlDocument *, int * ); static AstXmlNamespace *NewNamespace( const char *, const char *, int * ); static char *AppendChar( char *, int *, char, int * ); static char *AppendLine( char *, int *, const char *, int, int * ); static char *RemoveEscapes( const char *, int * ); static char *CleanText( const char *, int * ); static const char *AddEscapes( const char *, int * ); static const char *DefaultURI( AstXmlElement *, int * ); static const char *Format( AstXmlObject *, int, int * ); static char *FormatTag( AstXmlObject *, int, int * ); static const char *ResolvePrefix( const char *, AstXmlElement *, int * ); static int CheckType( long int, long int, int * ); static int MatchName( AstXmlElement *, const char *, int * ); static int Ustrcmp( const char *, const char *, int * ); static void AddContent( AstXmlParent *, int, AstXmlContentItem *, int * ); static void CheckName( const char *, const char *, const char *, int, int * ); static void CheckPrefName( char *, const char *, const char *, int * ); static void CleanXml( AstXmlObject *, long int, int * ); static void InitXmlAttribute( AstXmlAttribute *, int, const char *, const char *, const char *, int * ); static void InitXmlCDataSection( AstXmlCDataSection *, int, const char *, int * ); static void InitXmlWhite( AstXmlWhite *, int, const char *, int * ); static void InitXmlBlack( AstXmlBlack *, int, const char *, int * ); static void InitXmlComment( AstXmlComment *, int, const char *, int * ); static void InitXmlDocument( AstXmlDocument *, int, int * ); static void InitXmlPrologue( AstXmlPrologue *, int, int * ); static void InitXmlDeclPI( AstXmlDeclPI *, int, const char *, int * ); static void InitXmlDTDec( AstXmlDTDec *, int, const char *, const char *, const char *, int * ); static void InitXmlElement( AstXmlElement *, int, const char *, const char *, int * ); static void InitXmlNamespace( AstXmlNamespace *, int, const char *, const char *, int * ); static void InitXmlObject( AstXmlObject *, long int, int * ); static void InitXmlPI( AstXmlPI *, int, const char *, const char *, int * ); static AstXmlElement *ReadContent( AstXmlDocument **, int, int (*)( AstXmlElement *, int * ), int, char (*)( void *, int * ), void *, int, int * ); #ifdef DEBUG static void AddObjectToList( AstXmlObject * ); static void RemoveObjectFromList( AstXmlObject * ); #endif /* Function implementations. */ /* ========================= */ /* Create the astXmlCheck... functiosn which check a pointer identifies an XML structure of a given type. */ MAKE_CHECK(Document,AST__XMLDOC) MAKE_CHECK(Object,AST__XMLOBJECT) MAKE_CHECK(Element,AST__XMLELEM) MAKE_CHECK(Attribute,AST__XMLATTR) MAKE_CHECK(CDataSection,AST__XMLCDATA) MAKE_CHECK(Comment,AST__XMLCOM) MAKE_CHECK(PI,AST__XMLPI) MAKE_CHECK(Namespace,AST__XMLNAME) MAKE_CHECK(Prologue,AST__XMLPRO) MAKE_CHECK(DeclPI,AST__XMLDEC) MAKE_CHECK(DTDec,AST__XMLDTD) MAKE_CHECK(White,AST__XMLWHITE) MAKE_CHECK(Black,AST__XMLBLACK) MAKE_CHECK(CharData,AST__XMLCHAR) MAKE_CHECK(ContentItem,AST__XMLCONT) MAKE_CHECK(MiscItem,AST__XMLMISC) MAKE_CHECK(Parent,AST__XMLPAR) static void AddContent( AstXmlParent *this, int where, AstXmlContentItem *item, int *status ){ /* * Name: * AddContent * Purpose: * Add a content item to an XmlElement. * Type: * Private function. * Synopsis: * #include "xml.h" * void AddContent( AstXmlParent *this, int where, AstXmlContentItem *item, int *status ) * Description: * This function adds a supplied item to a specified XmlElement or * XmlDocument. An error is reported if the item is not appropriate. * Parameters: * this * The pointer to the element or document to be modified. * where * Ignored if "this" is an XmlElement pointer. Otherwise, "where" * indicates where the item should be added to the document: * 1 - In the prologue, after the XML declaration but before the DTD. * 2 - In the prologue, after the DTD but before the root element. * 3 - In the epilogue, after the root element. * item * Pointer to the content item to be added to the element. If * "this" is an XmlElement, this can be a pointer to any of the * following types: AstXmlElement, AstXmlWhite, AstXmlBlack, * AstXmlCDataSection, AstXmlComment, AstXmlPI. If "this" is a * document, the list is restricted to: AstXmlWhite, AstXmlComment, * AstXmlPI. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstXmlDocument *doc; /* Document pointer */ AstXmlElement *elem; /* Element pointer */ AstXmlPrologue *pro; /* Prologue pointer */ int nitem; /* Number of items in the parent */ /* Check the global error status and the supplied pointers. */ if( !astOK || !this || !item ) return; /* Split for the two forms of parent. */ if( astXmlCheckType( this, AST__XMLELEM ) ) { elem = (AstXmlElement *) this; /* Save the number of content items currently stored in the element. */ nitem = ( elem->items ) ? elem->nitem : 0; /* Attempt to extend the array to hold an extra item. */ elem->items = astGrow( elem->items, nitem + 1, sizeof( AstXmlContentItem * ) ); /* Check the memory was allocated succesfully. */ if( astOK ) { /* Store the supplied pointer in the array of content items. */ elem->items[ nitem ] = item; /* Increment the number of content items in this element */ elem->nitem = nitem + 1; /* Indicate that the item is owned by the element. */ ( (AstXmlObject *) item )->parent = this; } /* Now deal with cases where we are adding an item to the prologue or epilogue of the document. */ } else { if( !astXmlCheckType( item, AST__XMLMISC ) ){ astError( AST__INTER, "AddContent(xml): Inappropriate attempt to " "add an item of type %ld to an XML document (internal " "AST programming error).", status, ( (AstXmlObject *) item)->type ); } else if( !astXmlCheckType( this, AST__XMLDOC ) ){ astError( AST__INTER, "AddContent(xml): Inappropriate attempt to " "add an item of type %ld to an XML object of type %ld " "(internal AST programming error).", status, ( (AstXmlObject *) item)->type, ( (AstXmlObject *) this)->type ); } else { doc = (AstXmlDocument *) this; /* Create a prologue if necessary. */ if( where < 3 && !doc->prolog ) doc->prolog = NewPrologue( doc, status ); pro = doc->prolog; if( where < 2 ) { nitem = ( pro->misc1 ) ? pro->nmisc1 : 0; pro->misc1 = astGrow( pro->misc1, nitem + 1, sizeof( AstXmlMiscItem * ) ); if( astOK ) { pro->misc1[ nitem ] = item; pro->nmisc1 = nitem + 1; ( (AstXmlObject *) item )->parent = (AstXmlParent *) pro; } } else if( where == 2 ) { nitem = ( pro->misc2 ) ? pro->nmisc2 : 0; pro->misc2 = astGrow( pro->misc2, nitem + 1, sizeof( AstXmlMiscItem * ) ); if( astOK ) { pro->misc2[ nitem ] = item; pro->nmisc2 = nitem + 1; ( (AstXmlObject *) item )->parent = (AstXmlParent *) pro; } } else { nitem = ( doc->epilog ) ? doc->nepi : 0; doc->epilog = astGrow( doc->epilog, nitem + 1, sizeof( AstXmlMiscItem * ) ); if( astOK ) { doc->epilog[ nitem ] = item; doc->nepi = nitem + 1; ( (AstXmlObject *) item )->parent = this; } } } } } static const char *AddEscapes( const char *text, int *status ){ /* * Name: * AddEscapes * Purpose: * Replaces characters by corresponding entity references. * Type: * Private function. * Synopsis: * #include "xml.h" * const char *AddEscapes( const char *text, int *status ) * Description: * This function produces a dynamic copy of the supplied text in which * occurrences of "&", "<", ">", and "\"" are replaced by the corresponding * XML entity reference. * * The "&" character is only replaced by an entity reference if it is * followed by a non-name character (i.e. anything except a letter * underscore or colon). If it is followed by a name character, it is * assumed to mark the start of an entity reference. * Parameters: * text * A pointer to a text string. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated string containing the required * copy. * Notes: * - NULL is returned if this function is called with the global error * status set, or if it should fail for any reason. */ /* Local Variables: */ char *result; /* Returned pointer */ const char *c; /* Pointer to next supplied character */ char *d; /* Pointer to next returned character */ /* Initialise */ result = NULL; /* Return if the pointer is NULL or if an error has occurred. */ if( !astOK || !text ) return result; /* Allocate the maximum possible amount of memory that may be needed to store the returned string. */ result = astMalloc( 6*strlen( text ) + 1 ); /* Check the pointer can be used safely. */ if( astOK ) { /* Loop round every character in the supplied text. */ c = text - 1; d = result; while( *(++c) ) { /* We replace this character if it is a <, >, ', &, or ". */ if( *c == '<' ) { strcpy( d, "<" ); d += 4; } else if( *c == '>' ) { strcpy( d, ">" ); d += 4; } else if( *c == '"' ) { strcpy( d, """ ); d += 6; } else if( *c == '\'' ) { strcpy( d, "'" ); d += 6; } else if( *c == '&' ) { strcpy( d, "&" ); d += 5; /* Otherwise just append the supplied character. */ } else { *(d++) = *c; } } /* Terminate the returned string. */ *d = 0; /* Reallocate the string to free up any unused space. */ result = astRealloc( result, d - result + 1 ); } /* Return the result. */ return (const char *) result; } #ifdef DEBUG static void AddObjectToList( AstXmlObject *obj ){ /* * Name: * AddObjectToList * Purpose: * Adds an XmlObject to a static list of all currently active XmlObjects. * Type: * Private function. * Synopsis: * #include "xml.h" * void AddObjectToList( AstXmlObject *obj ) * Description: * This function adds the supplied pointer to a static list of pointers, * and increments the number of elements in the list. This list holds * pointers to all the XmlObjects which currently exist. * Parameters: * this * A pointer to a new XmlObject. */ /* Return if the pointer is NULL or if an error has occurred. */ if( !astOK || !obj ) return; /* Increment the number of objects in the list and increase the size of the list. */ astBeginPM; existing_objects = astGrow( existing_objects, ++nobj, sizeof( AstXmlObject *) ); astEndPM; /* Add the new pointer to the end of the list. */ existing_objects[ nobj - 1 ] = obj; } #endif static char *AppendChar( char *str1, int *nc, char ch, int *status ) { /* * Name: * AppendChar * Purpose: * Append a character to a string which grows dynamically. * Type: * Private function. * Synopsis: * #include "xml.h" * char *AppendChar( char *str1, int *nc, char ch, int *status ) * Description: * This function appends a character to a dynamically * allocated string, extending the dynamic string as necessary to * accommodate the new character (plus the final null). * Parameters: * str1 * Pointer to the null-terminated dynamic string, whose memory * has been allocated using the AST memory allocation functions * defined in "memory.h". If no space has yet been allocated for * this string, a NULL pointer may be given and fresh space will * be allocated by this function. * nc * Pointer to an integer containing the number of characters in * the dynamic string (excluding the final null). This is used * to save repeated searching of this string to determine its * length and it defines the point where the new string will be * appended. Its value is updated by this function to include * the extra characters appended. * * If "str1" is NULL, the initial value supplied for "*nc" will * be ignored and zero will be used. * ch * The character which is to be appended to "str1". * status * Pointer to the inherited status variable. * Returned Value: * A possibly new pointer to the dynamic string with the new character * appended (its location in memory may have to change if it has to * be extended, in which case the original memory is automatically * freed by this function). When the string is no longer required, * its memory should be freed using astFree. * Notes: * - If this function is invoked with the global error status set * or if it should fail for any reason, then the returned pointer * will be equal to "str1" and the dynamic string contents will be * unchanged. */ /* Local Variables: */ char *result; /* Pointer value to return */ int len; /* Length of new string */ /* Initialise. */ result = str1; /* If the first string pointer is NULL, also initialise the character count to zero. */ if ( !str1 ) *nc = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Calculate the total string length once the character has been added. */ len = *nc + 1; /* Extend the dynamic string to the required length, including a final null. Save the resulting pointer, which will be returned. */ result = astGrow( str1, len + 1, sizeof( char ) ); /* If OK, append the second string and update the total character count. */ if ( astOK ) { result[ *nc ] = ch; *nc = len; result[ *nc ] = 0; } /* Return the result pointer. */ return result; } static char *AppendLine( char *str1, int *nc, const char *str2, int ind, int *status ) { /* * Name: * AppendLine * Purpose: * Append an indented new line to another string which grows dynamically. * Type: * Private function. * Synopsis: * #include "xml.h" * char *AppendLine( char *str1, int *nc, const char *str2, int ind, int *status ) * Description: * This function appends one string to another dynamically * allocated string, extending the dynamic string as necessary to * accommodate the new characters (plus the final null). * * A newline character is inserted if necessary to ensure that the "str2" * string starts on a newline. If "ind" is positive, spaces are added * as necessary to ensure that "str2" begins with the specified number of * spaces. * Parameters: * str1 * Pointer to the null-terminated dynamic string, whose memory * has been allocated using the AST memory allocation functions * defined in "memory.h". If no space has yet been allocated for * this string, a NULL pointer may be given and fresh space will * be allocated by this function. * nc * Pointer to an integer containing the number of characters in * the dynamic string (excluding the final null). This is used * to save repeated searching of this string to determine its * length and it defines the point where the new string will be * appended. Its value is updated by this function to include * the extra characters appended. * * If "str1" is NULL, the initial value supplied for "*nc" will * be ignored and zero will be used. * str2 * Pointer to a constant null-terminated string, a copy of which * is to be appended to "str1". * ind * The number of spaces to use as the indentation string. * status * Pointer to the inherited status variable. * Returned Value: * A possibly new pointer to the dynamic string with the new string * appended (its location in memory may have to change if it has to * be extended, in which case the original memory is automatically * freed by this function). When the string is no longer required, * its memory should be freed using astFree. * Notes: * - If this function is invoked with the global error status set * or if it should fail for any reason, then the returned pointer * will be equal to "str1" and the dynamic string contents will be * unchanged. */ /* Local Variables: */ char *c; /* Point to next character */ char *result; /* Pointer value to return */ char *temp; /* Pointer to modified string */ int j; /* Loop count */ /* Initialise. */ result = str1; /* If the first string pointer is NULL, also initialise the character count to zero. */ if ( !str1 ) *nc = 0; /* Check the global error status. */ if ( !astOK || !str2 ) return result; /* Remove any trailing white space (except for newlines) from the supplied string. */ if( *nc > 0 ) { c = str1 + *nc - 1; while( isspace( *c ) && *c != '\n' ) { *(c--) = 0; (*nc)--; } /* If the last character in the returned string is not now a newline, append a newline, so long as the new item does not start with a newline. */ if( str1[ *nc - 1 ] != '\n' ) { temp = AppendChar( str1, nc, '\n', status ); } else { temp = str1; } } else { temp = str1; } /* If a fixed indentation is specified, skip over any leading spaces in the second string. */ if( str2 ) { if( ind > 0 ) { while( isspace( *str2 ) ) str2++; } /* If the first character of the second string is a newline, ignore it. */ if( str2[ 0 ] == '\n' ) str2++; } /* Append the indentation string. */ for( j = 0; j < ind; j++ ) temp = AppendChar( temp, nc, ' ', status ); /* Append the supplied string. */ return astAppendString( temp, nc, str2 ); } void astXmlAddAttr_( AstXmlElement *this, const char *name, const char *value, const char *prefix, int *status ){ /* *+ * Name: * astXmlAddAttr * Purpose: * Add an attribute to an XmlElement. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddAttr( AstXmlElement *this, const char *name, * const char *value, const char *prefix ) * Description: * This function adds an attribute to a specified XmlElement. If the * element already contains an attribute with the given name amd prefix, * then the value of the attribute is changed to be the supplied value. * Parameters: * this * The pointer to the element to be modified. * name * Pointer to a null terminated string containing the attribute name. * value * Pointer to a null terminated string containing the attribute value. * prefix * The namespace prefix for the attribute. May be NULL or blank, in * which case any prefix at the start of "name" is used. *- */ /* Local Variables: */ AstXmlAttribute *attr; /* The new attribute. */ AstXmlAttribute *oldattr; /* Pointer to existing attribute */ int i; /* Loop index */ int nattr; /* Number of attributes in the element */ int oldi; /* Index of existing attribute */ char *my_value; /* Cleaned value text */ /* Check the global error status. */ if( !astOK ) return; /* Initialise */ oldattr = NULL; /* Clean the value text. */ my_value = CleanText( value, status ); /* Create a new XmlAttribute. */ attr = NewAttribute( name, my_value, prefix, status ); /* Free the memory */ my_value = astFree( my_value ); /* If OK, indicate that the attribute is owned by the element. */ if( astOK ) { ( (AstXmlObject *) attr )->parent = (AstXmlParent *) this; /* Save the number of attributes currently stored in the element. */ nattr = ( this->attrs ) ? this->nattr : 0; /* Search the existing attributes to see if an attribute with the given name and prefix already exists. */ oldi = -1; for( i = 0; i < nattr; i++ ) { oldattr = this->attrs[ i ]; if( !strcmp( oldattr->name, attr->name ) ) { if( !oldattr->prefix && !attr->prefix ) { oldi = i; break; } else if( oldattr->prefix && attr->prefix && !strcmp( oldattr->prefix, attr->prefix ) ){ oldi = i; break; } } } /* If there is an existing attribute with the same name and prefix, replace the old attribute with the new one created above. */ if( oldi > -1 ){ ((AstXmlObject *)oldattr)->parent = NULL; oldattr = astXmlAnnul( oldattr ); this->attrs[ oldi ] = attr; /* Otherwise, attempt to extend the array to hold an extra attribute. */ } else { this->attrs = astGrow( this->attrs, nattr + 1, sizeof( AstXmlAttribute * ) ); /* Check all has gone OK. */ if( astOK ) { /* Store the attribute pointer in the array of attribute pointers. */ this->attrs[ nattr ] = attr; /* Increment the number of content items in this element */ this->nattr = nattr + 1; } } } } void astXmlAddCDataSection_( AstXmlElement *this, const char *text, int *status ){ /* *+ * Name: * astXmlAddCDataSection * Purpose: * Create a new XmlCDataSection and add it to an XmlElement. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddCDataSection( AstXmlElement *this, const char *text ) * Description: * This function creates a new XmlCDataSection structure representing * an unparsed character data (CDATA) section, and adds it into an * existing element. * Parameters: * this * A pointer to the element to be modified. * text * Pointer to a null terminated string containing the character data. *- */ /* Local Variables: */ AstXmlCDataSection *new; /* Pointer to new structure */ char *my_text; /* Cleaned text */ /* Check the global error status. */ if( !astOK ) return; /* Allocate space for the new structure. */ new = (AstXmlCDataSection *) astMalloc( sizeof( AstXmlCDataSection ) ); /* Clean the text. */ my_text = CleanText( text, status ); /* Initialise it. */ InitXmlCDataSection( new, AST__XMLCDATA, my_text, status ); /* Free the memory */ my_text = astFree( my_text ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, add the content item to the element. */ } else { AddContent( (AstXmlParent *) this, 0, (AstXmlContentItem *) new, status ); } } void astXmlAddCharData_( AstXmlParent *this, int where, const char *text, int *status ){ /* *+ * Name: * astXmlAddCharData * Purpose: * Create a new XmlCharData and add it to an XmlElement or XmlDocument. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddCharData( AstXmlParent *this, int where, const char *text ) * Description: * This function creates a new XmlCharData structure representing * parsed character data, and adds it into an existing element or * document. * Parameters: * this * Pointer to the element or document to be modified. * where * Ignored if "this" is an XmlElement pointer. Otherwise, "where" * indicates where the item should be added to the document: * 1 - In the prologue, after the XML declaration but before the DTD. * 2 - In the prologue, after the DTD but before the root element. * 3 - In the epilogue, after the root element. * text * Pointer to a null terminated string containing the character data. * If "this" is a document, the text must consist entirely of white * space. *- */ /* Local Variables: */ AstXmlCharData *new; /* Pointer to the new structure */ char *my_text; /* Pointer to cleaned text */ char *c; /* Pointer to next character */ /* Check the global error status. */ if( !astOK ) return; /* Initialise */ new = NULL; /* Clean the text by replacing "\r\n" by "\n". */ my_text = CleanText( text, status ); /* See if the text is all white. */ c = my_text - 1; while( *(++c) && isspace( *c ) ); /* If the string contains a non-white character, allocate memory for a XmlBlack structure, and initialise it to hold the supplied text. Otherwise, allocate memory for a XmlWhite structure, and initialise it to hold the supplied text. */ if( *c ) { if( astXmlCheckType( this, AST__XMLDOC ) ) { astError( AST__XMLCM, "astXmlAddCharData(xml): Illegal attempt " "to add non-white character data to the prologue or " "epilogue of an XML document: \"%s\".", status, my_text ); } else { new = (AstXmlCharData *) astMalloc( sizeof( AstXmlBlack ) ); InitXmlBlack( (AstXmlBlack *) new, AST__XMLBLACK, my_text, status ); } } else { new = (AstXmlCharData *) astMalloc( sizeof( AstXmlWhite ) ); InitXmlWhite( (AstXmlWhite *) new, AST__XMLWHITE, my_text, status ); } /* Free the memory holding the cleaned text */ my_text = astFree( my_text ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, add the content item to the element. */ } else { AddContent( this, where, (AstXmlContentItem *) new, status ); } } void astXmlAddComment_( AstXmlParent *this, int where, const char *text, int *status ){ /* *+ * Name: * astXmlAddComment * Purpose: * Create a new XmlComment and add it to an XmlElement or XmlDocument. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddComment( AstXmlParent *this, int where, const char *text ) * Description: * This function creates a new XmlComment structure representing * an XML comment, and adds it into an existing element or document. * Parameters: * this * Pointer to the element or document to be modified. * where * Ignored if "this" is an XmlElement pointer. Otherwise, "where" * indicates where the item should be added to the document: * 1 - In the prologue, after the XML declaration but before the DTD. * 2 - In the prologue, after the DTD but before the root element. * 3 - In the epilogue, after the root element. * text * Pointer to a null terminated string containing the comment text. *- */ /* Local Variables: */ AstXmlComment *new; /* Pointer to the new structure */ char *my_text; /* Cleaned text */ /* Check the global error status. */ if( !astOK ) return; /* Allocate space for the new structure. */ new = (AstXmlComment *) astMalloc( sizeof( AstXmlComment ) ); /* Clean the text. */ my_text = CleanText( text, status ); /* Initialise it. */ InitXmlComment( new, AST__XMLCOM, my_text, status ); /* Free the memory */ my_text = astFree( my_text ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, add the content item to the element. */ } else { AddContent( this, where, (AstXmlContentItem *) new, status ); } } AstXmlElement *astXmlAddElement_( AstXmlElement *this, const char *name, const char *prefix, int *status ){ /* *+ * Name: * astXmlAddElement * Purpose: * Create a new empty XmlElement and adds it to an XmlElement. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlElement *astXmlAddElement( AstXmlElement *this, const char *name, * const char *prefix ) * Description: * This function creates a new XmlElement structure representing an * empty XML element with the given name and namespace prefix, and * adds it into an existing element. * Parameters: * this * A pointer to the element to be modified. This may be NULL. * name * The name for the element. * prefix * The namespace prefix for the element. May be NULL or blank, in * which case any prefix at the start of "name" is used. * Returned Value: * A pointer to the new structure is returned. This pointer should be * freed using astXmlAnnul when no longer needed. * Notes: * - A NULL pointer is returned if the inherited status value * indicates an error has occurred on entry, or if this function * should fail for any reason. *- */ /* Local Variables: */ AstXmlElement *new; /* The returned pointer */ /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Allocate space for the new structure. */ new = (AstXmlElement *) astMalloc( sizeof( AstXmlElement ) ); /* Initialise it. */ InitXmlElement( new, AST__XMLELEM, name, prefix, status ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, add the content item to the element. */ } else { AddContent( (AstXmlParent *) this, 0, (AstXmlContentItem *) new, status ); } /* Return the result. */ return new; } void astXmlAddPI_( AstXmlParent *this, int where, const char *target, const char *text, int *status ){ /* *+ * Name: * astXmlAddPI * Purpose: * Create a new XmlPI and add it to an element or document. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddPI( AstXmlParent *this, int where, const char *target, * const char *text ) * Description: * This function creates a new XmlPI structure representing an * XML "programming instruction", and adds it into an existing element * or document. * Parameters: * this * Pointer to the element or document to be modified. This should * be a pointer to an XmlElement or an XmlDocument. * where * Ignored if "this" is an XmlElement pointer. Otherwise, "where" * indicates where the PI should be added to the document: * 1 - In the prologue, after the XML declaration but before the DTD. * 2 - In the prologue, after the DTD but before the root element. * 3 - In the epilogue, after the root element. * target * Pointer to a null terminated string containing the PI target. * text * Pointer to a null terminated string containing the PI text. *- */ /* Local Variables: */ AstXmlPI *new; /* Pointer to the new structure */ char *my_text; /* Cleaned text */ /* Check the global error status. */ if( !astOK ) return; /* Allocate space for the new structure. */ new = (AstXmlPI *) astMalloc( sizeof( AstXmlPI ) ); /* Clean the text. */ my_text = CleanText( text, status ); /* Initialise it. */ InitXmlPI( new, AST__XMLPI, target, my_text, status ); /* Free the memory */ my_text = astFree( my_text ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, add the content item to the element. */ } else { AddContent( this, where, (AstXmlContentItem *) new, status ); } } void astXmlAddURI_( AstXmlElement *this, const char *prefix, const char *uri, int *status ){ /* *+ * Name: * astXmlAddURI * Purpose: * Add a namespace prefix definition to an XmlElement, or change the * default namespace. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlAddURI( AstXmlElement *this, const char *prefix, * const char *uri ) * Description: * This function adds a namespace prefix definition to a specified * XmlElement, or changes the default namespace. If the suppliedprefix * is already defined in the element, the associated URI is changed to * the supplied URI. * Parameters: * this * The pointer to the element to be modified. * prefix * Pointer to a null terminated string containing the namespace * prefix. If this is NULL or blank, then the supplied URI is used * as the default namespace for this element and all child elements * (except for child elements which define their own default * namespace). * uri * Pointer to a null terminated string containing the namespace URI. * If this is NULL or blank, and "prefix" is also NULL or blank, then * this has the same effect of there being no default namespace within * the supplied element. *- */ /* Local Variables: */ AstXmlNamespace *ns; /* The new namespace definition */ AstXmlNamespace *oldns; /* The existing namespace definition */ int i; /* Loop index */ int nc; /* Length of namespace prefix */ int nnspref; /* Number of namespace defintions in the element */ int oldi; /* Index of existing attribute */ /* Check the global error status. */ if( !astOK ) return; /* Initialise */ oldns = NULL; /* Store the used length of the namespace prefix. */ nc = prefix ? astChrLen( prefix ) : 0; /* If no namespace prefix has been supplied, just change the default namespace URI. */ if( !nc ) { if( uri ) { this->defns = astStore( this->defns, uri, strlen( uri ) + 1 ); } else { this->defns = astStore( this->defns, "", 1 ); } /* Otherwise, add the namespace definition to the element. */ } else { /* Create a new XmlNamespace. */ ns = NewNamespace( prefix, uri, status ); /* If OK, indicate that the namespace is owned by the element. */ if( astOK ) { ( (AstXmlObject *) ns )->parent = (AstXmlParent *) this; /* Save the number of namespace definitions currently stored in the element. */ nnspref = ( this->nsprefs ) ? this->nnspref : 0; /* Search the existing prefixes to see if a namespace with the given prefix already exists. */ oldi = -1; for( i = 0; i < nnspref; i++ ) { oldns = this->nsprefs[ i ]; if( !strcmp( oldns->prefix, ns->prefix ) ) { oldi = i; break; } } /* If there is an existing namespace with the same prefix, replace the old namespace with the new one created above. */ if( oldi > -1 ){ ((AstXmlObject *)oldns)->parent = NULL; oldns = astXmlAnnul( oldns ); this->nsprefs[ oldi ] = ns; /* Otherwise, attempt to extend the array to hold an extra namespace definition. */ } else { this->nsprefs = astGrow( this->nsprefs, nnspref + 1, sizeof( AstXmlNamespace * ) ); /* Check all has gone OK. */ if( astOK ) { /* Store the Namespace pointer in the array of Namespace pointers. */ this->nsprefs[ nnspref ] = ns; /* Increment the number of namespaces in this element */ this->nnspref = nnspref + 1; } } } } } void *astXmlAnnul_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlAnnul * Purpose: * Free the resources used by an XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * void *astXmlAnnul( AstXmlObject *this ) * Description: * This function frees the resources used to hold the XmlObject, together * with any child objects contained within the supplied XmlObject. A NULL * pointer is always returned. If the supplied object is still in use * (that is, if its parent XmlElement still exists) then the resources * are not freed, and a copy of the supplied pointer is returned. * Parameters: * this * pointer to the XmlObject to be freed. * Returned Value: * A NULL pointer, or the supplied pointer if the XmlObject is still * in use. * Notes: * - This function attempts to execute even if an error has already * occurred. *- */ /* Return if a NULL pointer has been suppplied. */ if( !this ) return NULL; /* Return the supplied pointer if the objects parent still exists. */ if( this->parent && astXmlCheckType( this->parent, AST__XMLPAR ) ) return this; #ifdef DEBUG /* Remove the supplied object from the list of currently active XmlObjects. */ RemoveObjectFromList( this ); #endif /* Clean the objects contents, and free the memory holding the XmlObject. */ CleanXml( this, this->type, status ); astFree( this ); /* Return a NULL pointer. */ return NULL; } void *astXmlAnnulTree_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlAnnulTree * Purpose: * Free the resources used by a tree of XmlObjects. * Type: * Protected function. * Synopsis: * #include "xml.h" * void *astXmlAnnulTree( AstXmlObject *this ) * Description: * This function finds the head of the tree containing the supplied * XmlObject (either an XmlElement or an XmlDocument), and frees the * resources associated with all members of the tree. A NULL pointer * is always returned. * Parameters: * this * Pointer to a member of the tree of XmlObjects to be freed. * Returned Value: * A NULL pointer. * Notes: * - This function attempts to execute even if an error has already * occurred. *- */ /* Return if a NULL pointer has been suppplied. */ if( !this ) return NULL; /* Find the root and annull it. This will free all children (i.e. the entire tree). */ return astXmlAnnul( astXmlGetRoot( this ) ); } AstXmlObject *astXmlCopy_( AstXmlObject *this, int *status ) { /* *+ * Name: * astXmlCopy * Purpose: * Produce a deep copy of a supplied XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlObject *astXmlCopy( AstXmlObject *this ) * Description: * This function returns a pointer to a deep copy of the supplied * XmlObject. * Parameters: * this * Pointer to the XmlObject to copy. * Returned Value: * Pointer to the new copy. * Notes: * - NULL is returned if NULL pointer is supplied. * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ AstXmlAttribute *attr; AstXmlBlack *black; AstXmlCDataSection *cdata; AstXmlComment *comm; AstXmlDTDec *dtd; AstXmlDeclPI *dec; AstXmlDocument *doc, *newdoc; AstXmlElement *elem, *newelem; AstXmlNamespace *ns; AstXmlObject *new; AstXmlPI *pi; AstXmlPrologue *pro, *newpro; AstXmlWhite *white; int i, type; /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK || !this ) return new; /* Initialise a new XmlObject of the required class, and copy any sub-objects. */ type = this->type; if( type == AST__XMLELEM ){ elem = (AstXmlElement *) this; new = astMalloc( sizeof( AstXmlElement ) ); InitXmlElement( (AstXmlElement *) new, AST__XMLELEM, elem->name, elem->prefix, status ); newelem = (AstXmlElement *) new; newelem->attrs = astMalloc( sizeof( AstXmlAttribute *) * (size_t)elem->nattr ); newelem->nattr = elem->nattr; for( i = 0; i < elem->nattr; i++ ) { newelem->attrs[ i ] = (AstXmlAttribute *) astXmlCopy( elem->attrs[ i ] ); ((AstXmlObject *) newelem->attrs[ i ])->parent = (AstXmlParent *) newelem; } newelem->items = astMalloc( sizeof( AstXmlContentItem *) * (size_t)elem->nitem ); newelem->nitem = elem->nitem; for( i = 0; i < elem->nitem; i++ ) { newelem->items[ i ] = (AstXmlContentItem *) astXmlCopy( elem->items[ i ] ); ((AstXmlObject *) newelem->items[ i ])->parent = (AstXmlParent *) newelem; } newelem->nsprefs = astMalloc( sizeof( AstXmlNamespace *) * (size_t)elem->nnspref ); newelem->nnspref = elem->nnspref; for( i = 0; i < elem->nnspref; i++ ) { newelem->nsprefs[ i ] = (AstXmlNamespace *) astXmlCopy( elem->nsprefs[ i ] ); ((AstXmlObject *) newelem->nsprefs[ i ])->parent = (AstXmlParent *) newelem; } if( elem->defns ) { newelem->defns = astStore( NULL, elem->defns, strlen( elem->defns ) + 1 ); } newelem->complete = elem->complete; } else if( type == AST__XMLATTR ){ attr = (AstXmlAttribute *) this; new = astMalloc( sizeof( AstXmlAttribute ) ); InitXmlAttribute( (AstXmlAttribute *) new, AST__XMLATTR, attr->name, attr->value, attr->prefix, status ); } else if( type == AST__XMLBLACK ){ black = (AstXmlBlack *) this; new = astMalloc( sizeof( AstXmlBlack ) ); InitXmlBlack( (AstXmlBlack *) new, AST__XMLBLACK, black->text, status ); } else if( type == AST__XMLWHITE ){ white = (AstXmlWhite *) this; new = astMalloc( sizeof( AstXmlWhite ) ); InitXmlWhite( (AstXmlWhite *) new, AST__XMLWHITE, white->text, status ); } else if( type == AST__XMLCDATA ){ cdata = (AstXmlCDataSection *) this; new = astMalloc( sizeof( AstXmlCDataSection ) ); InitXmlCDataSection( (AstXmlCDataSection *) new, AST__XMLCDATA, cdata->text, status ); } else if( type == AST__XMLCOM ){ comm = (AstXmlComment *) this; new = astMalloc( sizeof( AstXmlComment ) ); InitXmlComment( (AstXmlComment *) new, AST__XMLCOM, comm->text, status ); } else if( type == AST__XMLPI ){ pi = (AstXmlPI *) this; new = astMalloc( sizeof( AstXmlPI ) ); InitXmlPI( (AstXmlPI *) new, AST__XMLPI, pi->target, pi->text, status ); } else if( type == AST__XMLNAME ){ ns = (AstXmlNamespace *) this; new = astMalloc( sizeof( AstXmlNamespace ) ); InitXmlNamespace( (AstXmlNamespace *) new, AST__XMLNAME, ns->prefix, ns->uri, status ); } else if( type == AST__XMLDOC ){ doc = (AstXmlDocument *) this; new = astMalloc( sizeof( AstXmlDocument ) ); InitXmlDocument( (AstXmlDocument *) new, AST__XMLDOC, status ); newdoc = (AstXmlDocument *) new; if( doc->prolog ) { newdoc->prolog = (AstXmlPrologue *) astXmlCopy( doc->prolog ); ((AstXmlObject *) newdoc->prolog)->parent = (AstXmlParent *) newdoc; } if( doc->root ) { newdoc->root = (AstXmlElement *) astXmlCopy( doc->root ); ((AstXmlObject *) newdoc->root)->parent = (AstXmlParent *) newdoc; } newdoc->epilog = astMalloc( sizeof( AstXmlMiscItem *) * (size_t)doc->nepi ); newdoc->nepi = doc->nepi; for( i = 0; i < doc->nepi; i++ ) { newdoc->epilog[ i ] = (AstXmlMiscItem *) astXmlCopy( doc->epilog[ i ] ); ((AstXmlObject *) newdoc->epilog[ i ])->parent = (AstXmlParent *) newdoc; } newdoc->current = NULL; } else if( type == AST__XMLPRO ){ pro = (AstXmlPrologue *) this; new = astMalloc( sizeof( AstXmlPrologue ) ); InitXmlPrologue( (AstXmlPrologue *) new, AST__XMLPRO, status ); newpro = (AstXmlPrologue *) new; if( pro->xmldecl ) { newpro->xmldecl = (AstXmlDeclPI *) astXmlCopy( pro->xmldecl ); ((AstXmlObject *) newpro->xmldecl)->parent = (AstXmlParent *) newpro; } if( pro->dtdec ) { newpro->dtdec = (AstXmlDTDec *) astXmlCopy( pro->dtdec ); ((AstXmlObject *) newpro->dtdec)->parent = (AstXmlParent *) newpro; } newpro->misc1 = astMalloc( sizeof( AstXmlMiscItem *) * (size_t)pro->nmisc1 ); newpro->nmisc1 = pro->nmisc1; for( i = 0; i < pro->nmisc1; i++ ) { newpro->misc1[ i ] = (AstXmlMiscItem *) astXmlCopy( pro->misc1[ i ] ); ((AstXmlObject *) newpro->misc1[ i ])->parent = (AstXmlParent *) newpro; } newpro->misc2 = astMalloc( sizeof( AstXmlMiscItem *) * (size_t)pro->nmisc2 ); newpro->nmisc2 = pro->nmisc2; for( i = 0; i < pro->nmisc2; i++ ) { newpro->misc2[ i ] = (AstXmlMiscItem *) astXmlCopy( pro->misc2[ i ] ); ((AstXmlObject *) newpro->misc2[ i ])->parent = (AstXmlParent *) newpro; } } else if( type == AST__XMLDEC ){ dec = (AstXmlDeclPI *) this; new = astMalloc( sizeof( AstXmlDeclPI ) ); InitXmlDeclPI( (AstXmlDeclPI *) new, AST__XMLDEC, dec->text, status ); } else if( type == AST__XMLDTD ){ dtd = (AstXmlDTDec *) this; new = astMalloc( sizeof( AstXmlDTDec ) ); InitXmlDTDec( (AstXmlDTDec *) new, AST__XMLDTD, dtd->name, dtd->external, dtd->internal, status ); } else if( astOK ) { astError( AST__INTER, "CopyXml: Invalid object type (%d) supplied " "(internal AST programming error).", status, type ); } /* If an error occurred, delete the new structure. */ if( !astOK ) new = astXmlDelete( new ); /* Return the result. */ return new; } const char *astXmlFormat_( AstXmlObject *this, int *status ) { /* *+ * Name: * astXmlFormat * Purpose: * Converts an XmlObject into a character string. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlFormat( AstXmlObject *this ) * Description: * This function returns a pointer to a dynamically allocated string * containing a textual representation of the supplied XmlObject. * Parameters: * this * Pointer to the XmlObject to format. * Returned Value: * Pointer to a null terminated string holding the formated XmlObject. * This string should be freed when no longer needed using astFree. * Notes: * - No newlines or indentation strings are added to the returned string. * - NULL is returned if NULL pointer is supplied. * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ return Format( this, -1, status ); } const char *astXmlGetAttributeValue_( AstXmlElement *this, const char *name, int *status ){ /* *+ * Name: * astXmlGetAttributeValue * Purpose: * Return a pointer to a string holding the value of a named attribute. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetAttributeValue( AstXmlElement *this, const char *name ) * Description: * This function returns a pointer to a constant string holding the * value of a named attribute of a supplied element. If the element * does not have the named attribute, a NULL pointer is returned but * no error is reported. * Parameters: * this * The pointer to the XmlElement. * name * Pointer to a string holding the name of the attribute. The name * may be preceded with a "prefix:" string, in which case the * prefix will also be matched. If no prefix is included, the first * attribute with the specified name is returned, regardless of * its prefix. * Returned Value: * Pointer to a string holding the value of the attribute within the * supplied element, or NULL if the attribute was not found. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ const char *result; /* Returned pointer */ AstXmlAttribute *attr; /* Pointer to the attribute */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Find the attribute. */ attr = FindAttribute( this, name, status ); /* Get its value. */ if( attr ) result = attr->value; /* Return the result. */ return result; } AstXmlContentItem *astXmlGetItem_( AstXmlElement *this, int item, int *status ){ /* *+ * Name: * astXmlGetItem * Purpose: * Return a specified item of the content of an element. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlContentItem *astXmlGetItem( AstXmlElement *this, int item ) * Description: * This function returns a pointer to an item of the content of the * specified element. * Parameters: * this * The pointer to the XmlElement. * item * The index of the required item, in the range zero to "nitem-1", * where "nitem" is the number of items in the element as returned * by astXmlGetNitem. An error is reported if the specified index * is out of bounds. * Returned Value: * A pointer to the requested item. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ AstXmlContentItem *result; /* The returned pointer */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Report an error if the supplie dindex is bad. */ if( this->nitem == 0 ) { astError( AST__XMLIT, "astXmlGetItem(xml): The supplied item index (%d) " "is out of bounds. The supplied XmlObject has no content.", status, item ); } else if( item < 0 || item >= this->nitem ) { astError( AST__XMLIT, "astXmlGetItem(xml): The supplied item index (%d) " "is out of bounds. Should be in the range 0 to %d.", status, item, this->nitem-1 ); } else { result = this->items[ item ]; } /* Return the result. */ return result; } const char *astXmlGetName_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlGetName * Purpose: * Return a pointer to a string holding the name of an XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetName( AstXmlObject *this ) * Description: * This function returns a pointer to a constant string holding the * name associated with an XmlObject. For elements and attributes, the * "name" value is returned. For PI elements, the "target" value is * returned. For namespace definitions, the "prefix" value is returned. * An error is reported if the supplied XmlObject is of any other class. * Parameters: * this * The pointer to the XmlObject. * Returned Value: * Pointer to the name string within the XML object. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ const char *result; /* Returned pointer */ int type; /* Object type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Return the relevant component of the structure, depending on its type. */ type = this->type; if( type == AST__XMLELEM ){ result = ( (AstXmlElement *) this )->name; } else if( type == AST__XMLATTR ){ result = ( (AstXmlAttribute *) this )->name; } else if( type == AST__XMLPI ){ result = ( (AstXmlPI *) this )->target; } else if( type == AST__XMLNAME ){ result = ( (AstXmlNamespace *) this )->prefix; } else { astError( AST__INTER, "astXmlGetName: Inappropriate object type (%d) supplied " "(internal AST programming error).", status, type ); } /* Return the result. */ return result; } int astXmlGetNattr_( AstXmlElement *this, int *status ){ /* *+ * Name: * astXmlGetNattr * Purpose: * Return the number of attributes held by an element. * Type: * Protected function. * Synopsis: * #include "xml.h" * int astXmlGetNattr( AstXmlElement *this ) * Description: * This function returns the number of attributes held by an element. * Parameters: * this * The pointer to the XmlElement. * Returned Value: * The number of attributes held by the supplied element. * Notes: * - Zero is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Check the global error status. */ if( !astOK ) return 0; /* Return the result. */ return ( this->attrs ) ? this->nattr : 0; } int astXmlGetNitem_( AstXmlElement *this, int *status ){ /* *+ * Name: * astXmlGetNitem * Purpose: * Return the number of items within the content of an element. * Type: * Protected function. * Synopsis: * #include "xml.h" * int astXmlGetNitem( AstXmlElement *this ) * Description: * This function returns the number of items within the content of an * XmlElement. * Parameters: * this * The pointer to the XmlElement. * Returned Value: * The number of items in the content of the supplied element. * Notes: * - Zero is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Check the global error status. */ if( !astOK ) return 0; /* Return the result. */ return this->nitem; } AstXmlParent *astXmlGetParent_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlGetParent * Purpose: * Return a pointer to the object which contains the supplied XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlParent *astXmlGetParent( AstXmlObject *this ) * Description: * This function returns a pointer to the XmlParent object (either an * XmlElement or an XmlDocument) which contains the specified XmlObject. * The object can be a content item (an element, a comment, a CDATA * section, a PI, or character data) in which case the enclosing * XmlElement is returned, or an attribute or namespace definition in * which case the XmlElement to which object refers is returned. * If "this" is the root element of a document, a pointer to the * XmlDocument is returned. * Parameters: * this * The pointer to check. * Returned Value: * Pointer to the parent, or NULL if the object does not have a parent. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Check the global error status. */ if( !astOK ) return NULL; /* Return the result. */ return this->parent; } AstXmlObject *astXmlGetRoot_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlGetRoot * Purpose: * Return a pointer to the root XmlObject which contains the supplied * XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlObject *astXmlGetRoot( AstXmlObject *this ) * Description: * This function returns a pointer to the XmlObject which is the root of * the tree containing the specified XmlObject. A pointer to the * supplied XmlObject is returned if it has no parent. * Parameters: * this * The pointer to check. * Returned Value: * Pointer to the root XmlObject, or a copy of the supplied pointer if * the supplied XmlObject is the root. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ AstXmlObject *result; /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* If "this" is a document, check it has no parent. If not, return a pointer ot it. */ if( astXmlCheckType( this, AST__XMLDOC ) ) { if( this->parent ) { astError( AST__INTER, "astXmlGetRoot(xml): An XmlDocument has a " "non-null parent of type %ld (internal AST programming " "error).", status, this->type ); } else { result = (AstXmlObject *) this; } /* Otherwise... */ } else if( this->parent ) { result = astXmlGetRoot( this->parent ); } else { result = this; } /* Return the result. */ return result; } const char *astXmlGetTag_( AstXmlObject *this, int opening, int *status ){ /* *+ * Name: * astXmlGetTag * Purpose: * Returns a string holding an XML tag describing the given XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetTag( AstXmlObject *this, int opening ) * Description: * This function returns a pointer to a static string containing an * XML tag describing the given XmlObject. * Parameters: * this * Pointer to the XmlObject. * opening * Indicates which tag is to be returned; the start tag or the end * tag. If non-zero the start tag is returned. Otherwise, the * end tag is returned. If the supplied XmlObject has no end * tag (i.e. if it is an empty element, or if it is not an element), * then NULL is returned but no error is reported. * Returned Value: * Pointer to a null terminated string holding the tag. If the tag * exceeds 200 characters, only the first 197 characters are returned * and "..." is appended to the end. * Notes: * - Subsequent invocations of this function will over-write the * buffer which used to hold the returned string. * - Empty elements are represented as an start tag of the form <.../>, * with no corresponding end tag. * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char *result; /* The returned pointer */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a dynamic string holding the formatted tag. */ result = FormatTag( this, opening, status ); /* If OK, copy the result into the static buffer. */ gettag_buff[ 0 ] = 0; if( result ) { if( astOK ) { if( strlen( result ) > AST__XML_GETTAG_BUFF_LEN ) { strncpy( gettag_buff, result, AST__XML_GETTAG_BUFF_LEN -3 ); strcpy( gettag_buff + AST__XML_GETTAG_BUFF_LEN - 3, "..." ); } else { strncpy( gettag_buff, result, AST__XML_GETTAG_BUFF_LEN ); } gettag_buff[ AST__XML_GETTAG_BUFF_LEN ] = 0; astFree( result ); result = gettag_buff; } else { result = astFree( result ); } } /* Return the result. */ return result; } const char *astXmlGetType_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlGetType * Purpose: * Returns a string holding the type of the given XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetType( AstXmlObject *this ) * Description: * This function returns a pointer to a static string containing the * type of the given XmlObject. * Parameters: * this * Pointer to the XmlObject. * Returned Value: * Pointer to a null terminated string holding the type string. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ const char *result; /* The returned pointer */ int type; /* Element type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; type = this->type; if( type == AST__XMLELEM ) { result = "element"; } else if( type == AST__XMLATTR ) { result = "attribute"; } else if( type == AST__XMLCDATA ) { result = "CDATA section"; } else if( type == AST__XMLCOM ) { result = "comment"; } else if( type == AST__XMLPI ) { result = "processing instruction"; } else if( type == AST__XMLNAME ) { result = "namespace"; } else if( type == AST__XMLDOC ) { result = "document"; } else if( type == AST__XMLPRO ) { result = "prologue"; } else if( type == AST__XMLDEC ) { result = "XML delaration PI"; } else if( type == AST__XMLDTD ) { result = "DTD"; } else if( type == AST__XMLWHITE ) { result = "white-space character data "; } else if( type == AST__XMLBLACK ) { result = "non-blank character data"; } else { result = "unknown XML object"; } /* Return the result. */ return result; } const char *astXmlGetURI_( AstXmlObject *this, int *status ){ /* *+ * Name: * astXmlGetURI * Purpose: * Return a pointer to a string holding the namespace URI of an XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetURI( AstXmlObject *this ) * Description: * This function returns a pointer to a constant string holding the * namespace URI associated with an XmlObject. Only attributes, * elements and namespaces have associated URIs, so a NULL pointer is * returned for any other class of XmlObject. A NULL pointer is also * returned if XmlObject does not belong to any namespace, or if it * belongs to a unknown namespace (i.e. one for which no URI is * available). Any namespace prefix attached to the supplied object is * resolved first using any "xmlns" attributes contained in the same * element, then using any "xmlns" attributes contained in the parent * element, etc. * Parameters: * this * The pointer to the XmlObject. * Returned Value: * Pointer to a string holding the namespace URI, or NULL. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ const char *prefix; /* Namespace prefix */ const char *result; /* Returned pointer */ int type; /* Object type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Do each type of object separately. */ type = this->type; if( type == AST__XMLATTR ){ prefix = ( (AstXmlAttribute *) this )->prefix; /* Attributes have no default name space. Therefore if there is no prefix, return NULL. If there is a prefix, resolve it within the context of the attributes parent element. */ if( prefix ) { result = ResolvePrefix( prefix, (AstXmlElement *) this->parent, status ); } } else if( type == AST__XMLELEM ){ prefix = ( (AstXmlElement *) this )->prefix; /* If there is a prefix, resolve it within the context of this element. */ if( prefix ) { result = ResolvePrefix( prefix, (AstXmlElement *) this, status ); /* Elements do have a default name space. Therefore if there is no prefix, return the default name space within the context of this element. */ } else { result = DefaultURI( (AstXmlElement *) this, status ); } /* If the supplied object is a namespace, just return the associated URI. */ } else if( type == AST__XMLNAME ){ result = ( (AstXmlNamespace *) this )->uri; } /* Return the result. */ return result; } const char *astXmlGetValue_( AstXmlObject *this, int report, int *status ){ /* *+ * Name: * astXmlGetValue * Purpose: * Return a pointer to a string holding the value of an XmlObject. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlGetValue( AstXmlObject *this, int report ) * Description: * This function returns a pointer to a constant string holding the * value associated with an XmlObject. For attributes, the attribute value * is returned. For PI elements, the "text" value is returned. For * namespace definitions, the "URI" value is returned. For character * data, the character data is returned. For CDATA sections the "text" * value is returned. For comments, the "text" value is returned. * If the XmlObject is an element, then a non-NULL value is returned * only if the element contains a single content item holding character * data. In this case a pointer to the character data is returned. * A null value is returned in all other cases (but no error is * reported unless "report" is non-zero). * Parameters: * this * The pointer to the XmlObject. * report * Report an error if the supplied XmlObject does not have a value? * Returned Value: * Pointer to a string holding the value of the XML object. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ AstXmlContentItem *item;/* Element content */ const char *result; /* Returned pointer */ int type; /* Object type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Return the relevant component of the structure, depending on its type. */ type = this->type; if( type == AST__XMLATTR ){ result = ( (AstXmlAttribute *) this )->value; } else if( type == AST__XMLBLACK ){ result = ( (AstXmlBlack *) this )->text; } else if( type == AST__XMLWHITE ){ result = ( (AstXmlWhite *) this )->text; } else if( type == AST__XMLCDATA ){ result = ( (AstXmlCDataSection *) this )->text; } else if( type == AST__XMLCOM ){ result = ( (AstXmlComment *) this )->text; } else if( type == AST__XMLPI ){ result = ( (AstXmlPI *) this )->text; } else if( type == AST__XMLNAME ){ result = ( (AstXmlNamespace *) this )->uri; } else if( type == AST__XMLELEM ){ if( astXmlGetNitem( (AstXmlElement *) this ) == 1 ) { item = astXmlGetItem( (AstXmlElement *) this, 0 ); if( astXmlCheckType( item, AST__XMLCHAR ) ) { result = astXmlGetValue( item, report ); } } if( !result && astOK && report ) { astError( AST__BADIN, "astRead(xml): Cannot get the value of " "element \"<%s>\": its contents are not pure character " "data.", status, astXmlGetName( this ) ); } } else if( report ) { astError( AST__INTER, "astXmlGetValue(xml): Cannot get the value of " "an XmlObject of type %d (internal AST programming " "error).", status, type ); } /* Return the result. */ return result; } void astXmlInsertElement_( AstXmlElement *this, AstXmlElement *elem, int *status ){ /* *+ * Name: * astXmlInsertElement * Purpose: * Inserts an existing XmlElement into another XmlElement. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlInsertElement( AstXmlElement *this, AstXmlElement *elem ) * Description: * This function inserts a given XmlElement "elem" into another given * XmlElement "this". An error is reported if "elem" already has a * parent. * Parameters: * this * A pointer to the element to be modified. * elem * The element to be inserted into "this". *- */ /* Check the global error status. */ if( !astOK ) return; /* Report AN error if "elem" has already been inserted into another element. */ if( ((AstXmlObject *) elem)->parent ) { astError( AST__INTER, "astXmlInsertElement(xml): Cannot insert \"%s\" " "into \"%s\" because it already has a parent (\"%s\") " "(internal AST programming error).", status, astXmlGetTag( elem, 1 ), astXmlGetTag( this, 1 ), astXmlGetTag( ((AstXmlObject *) elem)->parent, 1 ) ); /* Otherwise, add the content item to the element. */ } else { AddContent( (AstXmlParent *) this, 0, (AstXmlContentItem *) elem, status ); } } void astXmlPurge_( AstXmlParent *this, int *status ) { /* *+ * Name: * astXmlPurge * Purpose: * Remove blank content from a parent object. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlPurge( AstXmlParent *this ) * Description: * This function removes all character data containing only whitespace * from the supplied document or element. It is recursive, in that it also * removes white space from all children elements. * Parameters: * this * Pointer to the document or element. *- */ /* Local Variables: */ int i; /* Content item index */ AstXmlContentItem *item; /* Next content item */ AstXmlMiscItem *misc; /* Nest miscalleneous item */ AstXmlDocument *doc; /* This document */ AstXmlPrologue *pro; /* This document prologue */ AstXmlElement *elem; /* This element */ /* Check the global error status. */ if( !astOK || !this ) return; /* If this is a a document.. */ if( astXmlCheckType( this, AST__XMLDOC ) ) { doc = (AstXmlDocument *) this; astXmlPurge( doc->prolog ); astXmlPurge( doc->root ); i = -1; while( ++i < doc->nepi ) { misc = doc->epilog[ i ]; if( astXmlCheckType( misc, AST__XMLWHITE ) ) { misc = astXmlDelete( misc ); i--; } } /* If this is a prologue.. */ } else if( astXmlCheckType( this, AST__XMLPRO ) ) { pro = (AstXmlPrologue *) this; i = -1; while( ++i < pro->nmisc1 ) { misc = pro->misc1[ i ]; if( astXmlCheckType( misc, AST__XMLWHITE ) ) { misc = astXmlDelete( misc ); i--; } } i = -1; while( ++i < pro->nmisc2 ) { misc = pro->misc2[ i ]; if( astXmlCheckType( misc, AST__XMLWHITE ) ) { misc = astXmlDelete( misc ); i--; } } /* If this is an element */ } else if( astXmlCheckType( this, AST__XMLELEM ) ) { elem = (AstXmlElement *) this; i = -1; while( ++i < elem->nitem ) { item = elem->items[ i ]; if( astXmlCheckType( item, AST__XMLWHITE ) ) { item = astXmlDelete( item ); i--; } else if( astXmlCheckType( item, AST__XMLELEM ) ) { astXmlPurge( (AstXmlParent *) item ); } } } } void astXmlRemoveAttr_( AstXmlElement *this, const char *name, const char *prefix, int *status ){ /* *+ * Name: * astXmlRemoveAttr * Purpose: * Removes an attribute from its parent element. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlRemoveAttr( AstXmlElement *this, const char *name, * const char *prefix ) * Description: * This function removes a named attribute from its parent element. * Parameters: * this * The pointer to the element containing the attribute to be removed. * name * Pointer to a null terminated string containing the attribute name. * prefix * The namespace prefix for the attribute. May be NULL or blank, in * which case any prefix at the start of "name" is used. *- */ /* Local Variables: */ AstXmlAttribute *attr; /* Pointer to temporary attribute structure */ AstXmlAttribute *oldattr; /* Pointer to existing attribute */ int i; /* Attribute index */ int nattr; /* Number of attributes in parent */ int oldi; /* Indexof existing attribute */ /* Check the global error status. */ if( !astOK ) return; /* Initialise */ oldattr = NULL; /* Create a new XmlAttribute with blank value. */ attr = NewAttribute( name, "", prefix, status ); if( astOK ) { /* Get the number of attributes currently stored in the element. */ nattr = ( this->attrs ) ? this->nattr : 0; /* Search the existing attributes to see if an attribute with the given name and prefix already exists. */ oldi = -1; for( i = 0; i < nattr; i++ ) { oldattr = this->attrs[ i ]; if( !strcmp( oldattr->name, attr->name ) ) { if( !oldattr->prefix && !attr->prefix ) { oldi = i; break; } else if( oldattr->prefix && attr->prefix && !strcmp( oldattr->prefix, attr->prefix ) ){ oldi = i; break; } } } /* If there is an existing attribute with the same name and prefix, delete it. */ if( oldi > -1 ) astXmlDelete( oldattr ); /* Delete the temporary attribute structure. */ attr = astXmlDelete( attr ); } } void astXmlRemoveItem_( AstXmlContentItem *this, int *status ){ /* *+ * Name: * astXmlRemoveItem * Purpose: * Removes an item of content from its parent element or document. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlRemoveItem( AstXmlContentItem *this ) * Description: * This function removes an item of content from its parent element, * or removes the root element from a document. The removed item is not * annulled and may be subsequently added into another element. * Parameters: * this * The pointer to the item to be removed form its parent. *- */ /* Local Variables: */ AstXmlDocument *doc; /* Pointer to parent document */ AstXmlElement *elem; /* Pointer to parent element */ AstXmlParent *parent; /* Pointer to parent */ int found; /* Was the item found within its parent? */ int i; /* Item index */ int j; /* Item index */ /* Check the global error status. */ if( !astOK ) return; /* Get a pointer to the items parent element, and check it is not null. */ parent = ( (AstXmlObject *) this )->parent; if( parent && astXmlCheckType( parent, AST__XMLELEM ) ) { elem = (AstXmlElement *) parent; /* Search through all the items within the parent element looking for the supplied item. */ found = 0; for( i = 0; i < elem->nitem; i++ ) { if( elem->items[ i ] == this ) { /* When found, decrement the number of items in the element, and shuffle all the remaining item pointers down one slot to over-write it, then nullify the parent pointer in the supplied object and leave the loop. */ (elem->nitem)--; for( j = i; j < elem->nitem; j++ ) { elem->items[ j ] = elem->items[ j + 1 ]; } ( (AstXmlObject *) this )->parent = NULL; found = 1; break; } } /* Report an error if the item was not found. */ if( !found ) { astError( AST__INTER, "astXmlRemoveItem: The parent of the supplied " "item does not contain the item (internal AST programming " "error)." , status); } /* If the parent is an XmlDocument, check the item being removed is the root element. */ } else if( parent && astXmlCheckType( parent, AST__XMLDOC ) ) { doc = (AstXmlDocument *) parent; if( (AstXmlElement *) this == doc->root ) { ( (AstXmlObject *) this )->parent = NULL; doc->root = NULL; } } } void astXmlRemoveURI_( AstXmlElement *this, const char *prefix, int *status ){ /* *+ * Name: * astXmlRemoveURI * Purpose: * Removes an namespace prefix from its parent element. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlRemoveURI( AstXmlElement *this, const char *prefix ) * Description: * This function removes a named namespace prefix from its parent element. * Parameters: * this * The pointer to the element containing the namespace prefix to be * removed. * prefix * The namespace prefix to remove. *- */ /* Local Variables: */ AstXmlNamespace *ns; /* Temporary namespace structure */ AstXmlNamespace *oldns; /* Pointer to existing namespace */ int oldi; /* Index of namespace within its parent */ int i; /* Namespace index */ int nns; /* Number of existing namespaces */ /* Check the global error status. */ if( !astOK ) return; /* Initialise */ oldns = NULL; /* Create a new XmlNamespace with blank URI. */ ns = NewNamespace( prefix, "", status ); if( astOK ) { /* Get the number of namespace prefixes currently stored in the element. */ nns = ( this->nsprefs ) ? this->nnspref : 0; /* Search the list of existing namespace prefixes to see if the given prefix is included. */ oldi = -1; for( i = 0; i < nns; i++ ) { oldns = this->nsprefs[ i ]; if( !strcmp( oldns->prefix, ns->prefix ) ){ oldi = i; break; } } /* If the supplied namespace prefix was found in the list, delete it. */ if( oldi > -1 ) astXmlDelete( oldns ); /* Delete the temporary namespace structure. */ ns = astXmlDelete( ns ); } } void astXmlSetDTDec_( AstXmlDocument *this, const char *text1, const char *text2, const char *text3, int *status ){ /* *+ * Name: * astXmlSetDTDec * Purpose: * Set the Document Type declaration for a document. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlSetDTDEC( AstXmlDocument *this, const char *text1, * const char *text2, const char *text3 ) * Description: * This function stores an Document Type declaration of the form * * * * in the supplied document. Any previous DTD is removed. * Parameters: * this * The pointer to the document. * text1 * The document type name. * text2 * The text defining the external elements of the document type * (may be NULL). * text3 * The text defining the internal elements of the document type * (may be NULL). Do not include delimiting "[" and "]" characters. *- */ /* Local Variables: */ AstXmlDTDec *new; /* Pointer to new DT declaration */ AstXmlPrologue *pro; /* Pointer to prologue */ char *my_text2; /* Cleaned text2 */ char *my_text3; /* Cleaned text3 */ /* Check the global error status. */ if( !astOK ) return; /* Allocate space for the new structure. */ new = (AstXmlDTDec *) astMalloc( sizeof( AstXmlDTDec ) ); /* Clean the text. */ my_text2 = CleanText( text2, status ); my_text3 = CleanText( text3, status ); /* Initialise it. */ InitXmlDTDec( new, AST__XMLDTD, text1, my_text2, my_text3, status ); /* Free the memory */ my_text2 = astFree( my_text2 ); my_text3 = astFree( my_text3 ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, store it in the document, deleting any existing declaration first. */ } else { /* Create a prologue if necessary. */ if( !this->prolog ) this->prolog = NewPrologue( this, status ); pro = this->prolog; if( pro->dtdec ) astXmlDelete( pro->dtdec ); pro->dtdec = new; } } void astXmlSetXmlDec_( AstXmlDocument *this, const char *text, int *status ){ /* *+ * Name: * astXmlSetXmlDec * Purpose: * Set the XML declaration for a document. * Type: * Protected function. * Synopsis: * #include "xml.h" * void astXmlSetXmlDec( AstXmlDocument *this, const char *text ) * Description: * This function stores an XML declaration of the form * * * * in the supplied document. Any previous XML declaration is removed. * Parameters: * this * The pointer to the document. * text * The text to include in the XML declaration tag. *- */ /* Local Variables: */ AstXmlDeclPI *new; /* Pointer to new XML delcaration */ AstXmlPrologue *pro; /* Pointer to prologue */ char *my_text; /* Cleaned text */ /* Check the global error status. */ if( !astOK ) return; /* Allocate space for the new structure. */ new = (AstXmlDeclPI *) astMalloc( sizeof( AstXmlDeclPI ) ); /* Clean the text. */ my_text = CleanText( text, status ); /* Initialise it. */ InitXmlDeclPI( new, AST__XMLDEC, my_text, status ); /* Free the memory */ my_text = astFree( my_text ); /* If an error occurred, delete the new structure. */ if( !astOK ) { new = astXmlDelete( new ); /* Otherwise, store it in the document, deleting any existing declaration first. */ } else { /* Create a prologue if necessary. */ if( !this->prolog ) this->prolog = NewPrologue( this, status ); pro = this->prolog; if( pro->xmldecl ) astXmlDelete( pro->xmldecl ); pro->xmldecl = new; } } const char *astXmlShow_( AstXmlObject *this, int *status ) { /* *+ * Name: * astXmlShow * Purpose: * Converts an XmlObject into a character string with indentation. * Type: * Protected function. * Synopsis: * #include "xml.h" * const char *astXmlShow( AstXmlObject *this ) * Description: * This function returns a pointer to a dynamically allocated string * containing a textual representation of the supplied XmlObject. * Newline characters are added to the string if needed to ensure that * each item of content within an element starts on a new line, and all * tags are preceded by an indentation string consisting of a number * of spaces. * Parameters: * this * Pointer to the XmlObject to format. * Returned Value: * Pointer to a null terminated string holding the formated XmlObject. * This string should be freed when no longer needed using astFree. * Notes: * - NULL is returned if a NULL pointer is supplied. * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ return Format( this, 0, status ); } static void CheckName( const char *name, const char *noun, const char *method, int nullok, int *status ){ /* * Name: * CheckName * Purpose: * Checks the supplied string is a valid XML name. * Type: * Private function. * Synopsis: * #include "xml.h" * void CheckName( const char *name, const char *noun, const char *method, * int nullok, int *status ) * Description: * This function checks that the supplied string is a valid XML name, * and reports an error otherwise. * Parameters: * name * The name string to check * noun * A word to describe the object which the name applies to - for use in * error messages only. * method * The name of the calling method - for use in error messages only. * nullok * If non-zero, then a null or empty name is assumed to be * acceptable. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *c; /* Pointer to next character to check */ /* Check the global error status. */ if( !astOK ) return; /* Check the string is not null. */ if( !name ) { if( !nullok ) astError( AST__XMLNM, "%s: A NULL pointer was supplied " "instead of an XML %s name.", status, method, noun ); } else { c = name; if( *c == 0 ) { if( !nullok ) astError( AST__XMLNM, "%s: An empty string was supplied " "instead of an XML %s name.", status, method, noun ); } else { if( !isalpha( *c ) && *c != '_' ) { astError( AST__XMLNM, "%s: The illegal XML %s name \"%s\" was " "encountered.", status, method, noun, name ); } else { while( *(++c) ) { if( !isalnum( *c ) && *c != '_' && *c != '-' && *c != '.' ){ astError( AST__XMLNM, "%s: The illegal XML %s name \"%s\" was " "encountered.", status, method, noun, name ); break; } } } } } } static void CheckPrefName( char *name, const char *noun, const char *method, int *status ){ /* * Name: * CheckPrefName * Purpose: * Checks the supplied string is a valid XML (prefix:)name. * Type: * Private function. * Synopsis: * #include "xml.h" * void CheckPrefName( char *name, const char *noun, const char *method, int *status ) * Description: * This function checks that the supplied string is a valid XML * (prefix:)name combination and reports an error otherwise. * Parameters: * name * The string to check * noun * A word to describe the object which the name applies to - for use in * error messages only. * method * The name of the calling method - for use in error messages only. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char *colon; /* Pointer to first colon */ char *temp; /* Pointer to temporary string */ int nc; /* Length of temporary string */ /* Check the global error status. */ if( !astOK ) return; /* Search for a ":" character. */ colon = strchr( name, ':' ); /* If found, temporarily convert the colon into a null so that it terminates the prefix string. */ if( colon ) { *colon = 0; /* Check the string before the colon is a valid name. */ temp = NULL; temp = astAppendString( temp, &nc, noun ); temp = astAppendString( temp, &nc, " prefix" ); CheckName( name, temp, method, 0, status ); temp = astFree( temp ); /* Restore the colon. */ *colon = ':'; /* Check the string following the colon is a valid name. */ CheckName( colon + 1, noun, method, 0, status ); /* If not found, the whole supplied string must be a name. */ } else { CheckName( name, noun, method, 0, status ); } } static int CheckType( long int given, long int want, int *status ){ /* * Name: * CheckType * Purpose: * Check that the supplied type identifies an object of a given class. * Type: * Private function. * Synopsis: * #include "xml.h" * int CheckType( long int given, long int want, int *status ) * Description: * This function checks that the supplied type identifier identifies * a specified class of XML object, or a derived class. A flag is * returned indicating if the check succeeds. No error is reported if * the check fails. * Parameters: * given * The type value to be checked. * want * The type of the required class. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the check is passed, zero if not of if an error has * already occurred. * Notes: * - This function attempts to execute even if the error status is set. */ /* Local Variables: */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the wanted type is recognised. Report an error if not. */ if( want != AST__XMLOBJECT && want != AST__XMLELEM && want != AST__XMLATTR && want != AST__XMLCHAR && want != AST__XMLCDATA && want != AST__XMLCOM && want != AST__XMLPI && want != AST__XMLNAME && want != AST__XMLCONT && want != AST__XMLPRO && want != AST__XMLDEC && want != AST__XMLDTD && want != AST__XMLMISC && want != AST__XMLBLACK && want != AST__XMLWHITE && want != AST__XMLPAR && want != AST__XMLDOC ) { if( astOK ) { astError( AST__INTER, "CheckType(Xml): Unsupported XML object " "type (%ld) supplied for parameter \"want\" (internal " "AST programming error). ", status, want ); } /* You should never be given a generic "interface" type since the "wanted" value comes from the "type" component of an XmlObject (an explicit class type should always be given). */ } else if( given == AST__XMLPAR || given == AST__XMLMISC || given == AST__XMLCONT || given == AST__XMLCHAR ) { if( astOK ) { astError( AST__INTER, "CheckType(Xml): Generic type (%ld) supplied for " "parameter \"given\" (internal AST programming error).", status, given ); } /* If the above is OK, return a non-zero value if the type to be tested equals the wanted type. */ } else if( want == given ) { result = 1; /* If any class of XmlObject is acceptable, check that he given class type is a valid XML class type. */ } else if( want == AST__XMLOBJECT ) { result = ( given == AST__XMLELEM || given == AST__XMLATTR || given == AST__XMLCDATA || given == AST__XMLCOM || given == AST__XMLPI || given == AST__XMLNAME || given == AST__XMLPRO || given == AST__XMLDEC || given == AST__XMLDTD || given == AST__XMLWHITE || given == AST__XMLBLACK || given == AST__XMLDOC ); /* Otherwise, for "interface" types, check if the given class "implements the interface". */ } else if( want == AST__XMLCONT ) { result = ( given == AST__XMLELEM || given == AST__XMLBLACK || given == AST__XMLWHITE || given == AST__XMLCDATA || given == AST__XMLCOM || given == AST__XMLPI ); } else if( want == AST__XMLMISC ) { result = ( given == AST__XMLWHITE || given == AST__XMLCOM || given == AST__XMLPI ); } else if( want == AST__XMLCHAR ) { result = ( given == AST__XMLWHITE || given == AST__XMLBLACK ); } else if( want == AST__XMLPAR ) { result = ( given == AST__XMLDOC || given == AST__XMLPRO || given == AST__XMLELEM ); } /* Return the result. */ return result; } int astXmlCheckType_( void *this, long int want, int *status ){ /* *+ * Name: * astXmlCheckType * Purpose: * Check that the supplied object is of a given class. * Type: * Protected function. * Synopsis: * #include "xml.h" * int astXmlCheckType( void *this, long int want ) * Description: * This function checks that the supplied XmlObject is of a specified * class of XML object, or a derived class. A flag is returned indicating * if the check succeeds. No error is reported if the check fails. * Parameters: * this * The object to check. * want * The type of the required class. * Returned Value: * Non-zero if the check is passed, zero if not of if an error has * already occurred. * Notes: * - This function attempts to execute even if the error status is set. *- */ if( this ) { return CheckType( ((AstXmlObject *) this)->type, want, status ); } else { return 0; } } static char *CleanText( const char *text, int *status ){ /* * Name: * CleanText * Purpose: * Normalise end-of-lines in the supplied text. * Type: * Private function. * Synopsis: * #include "xml.h" * char *CleanText( const char *text, int *status ) * Description: * This function returns a copy of "text in which "\r\n" has been * replaced by "\n" and any remaining "\r" characters have been * replaced by "\n". * Parameters: * text * A pointer to a text string. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated string containing the required * copy. * Notes: * - NULL is returned if this function is called with the global error * status set, or if it should fail for any reason. */ /* Local Variables: */ char *d; /* Pointer to next returned character */ char *result; /* Returned pointer */ char *c; /* Pointer to next supplied character */ char lc; /* Previous character */ /* Initialise */ result = NULL; /* Return if the pointer is NULL or if an error has occurred. */ if( !astOK || !text ) return result; /* Take a copy of the supplied text */ result = astStore( NULL, text, strlen( text ) + 1 ); /* Clean the text by replacing "\r\n" by "\n". */ c = result - 1; d = c; lc = 0; while( *(++c) ) { if( *c != '\n' || lc != '\r' ) d++; *d = ( lc = *c ); } *(++d) = 0; /* Now further clean it by replacing "\r" by "\n". */ c = result - 1; while( *(++c) ) { if( *c == '\r' ) *c = '\n'; } /* Return the result. */ return result; } static void CleanXml( AstXmlObject *this, long int type, int *status ){ /* * Name: * CleanXml * Purpose: * Free the resources used within an XmlObject. * Type: * Private function. * Synopsis: * #include "xml.h" * void CleanXml( AstXmlObject *this, long int type, int *status ) * Description: * This function frees the resources used internally within the * supplied XmlObject. * Parameters: * this * pointer to the XmlObject to be cleaned. * type * The type of XmlObject being cleaned. * status * Pointer to the inherited status variable. * Notes: * This function attempts to execute even if an error has already * occurred. *- */ /* Local Variables: */ AstXmlAttribute *attr; AstXmlBlack *black; AstXmlCDataSection *cdatasec; AstXmlComment *comm; AstXmlDTDec *dtd; AstXmlDeclPI *dec; AstXmlDocument *doc; AstXmlElement *elem; AstXmlNamespace *ns; AstXmlPI *pi; AstXmlPrologue *pro; AstXmlWhite *white; /* Return if a NULL pointer has been suppplied. */ if( !this ) return; /* For the base XmlObject class, clear the object type, etc. */ if( type == AST__XMLOBJECT ){ this->type = AST__XMLBAD; this->parent = NULL; /* For each derived class of XmlObject, first clean the parent component, then clean any further resources. */ } else if( type == AST__XMLELEM ){ elem = (AstXmlElement *) this; elem->name = astFree( elem->name ); elem->defns = astFree( elem->defns ); elem->prefix = astFree( elem->prefix ); while( elem->nattr > 0 ) astXmlDelete( elem->attrs[ 0 ] ); elem->attrs = astFree( elem->attrs ); while( elem->nitem > 0 ) astXmlDelete( elem->items[ 0 ] ); elem->items = astFree( elem->items ); while( elem->nnspref > 0 ) astXmlDelete( elem->nsprefs[ 0 ] ); elem->nsprefs = astFree( elem->nsprefs ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLATTR ){ attr = (AstXmlAttribute *) this; attr->name = astFree( attr->name ); attr->value = astFree( attr->value ); attr->prefix = astFree( attr->prefix ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLBLACK ){ black = (AstXmlBlack *) this; black->text = astFree( black->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLWHITE ){ white = (AstXmlWhite *) this; white->text = astFree( white->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLCDATA ){ cdatasec = (AstXmlCDataSection *) this; cdatasec->text = astFree( cdatasec->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLCOM ){ comm = (AstXmlComment *) this; comm->text = astFree( comm->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLPI ){ pi = (AstXmlPI *) this; pi->target = astFree( pi->target ); pi->text = astFree( pi->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLNAME ){ ns = (AstXmlNamespace *) this; ns->prefix = astFree( ns->prefix ); ns->uri = astFree( ns->uri ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLDOC ){ doc = (AstXmlDocument *) this; doc->prolog = astXmlDelete( doc->prolog ); doc->root = astXmlDelete( doc->root ); while( doc->nepi > 0 ) astXmlDelete( doc->epilog[ 0 ] ); doc->epilog = astFree( doc->epilog ); doc->current = NULL; CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLPRO ){ pro = (AstXmlPrologue *) this; pro->xmldecl = astXmlDelete( pro->xmldecl ); while( pro->nmisc1 > 0 ) astXmlDelete( pro->misc1[ 0 ] ); pro->misc1 = astFree( pro->misc1 ); pro->dtdec = astXmlDelete( pro->dtdec ); while( pro->nmisc2 > 0 ) astXmlDelete( pro->misc2[ 0 ] ); pro->misc2 = astFree( pro->misc2 ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLDEC ){ dec = (AstXmlDeclPI *) this; dec->text = astFree( dec->text ); CleanXml( this, AST__XMLOBJECT, status ); } else if( type == AST__XMLDTD ){ dtd = (AstXmlDTDec *) this; dtd->name = astFree( dtd->name ); dtd->external = astFree( dtd->external ); dtd->internal = astFree( dtd->internal ); CleanXml( this, AST__XMLOBJECT, status ); } else if( astOK ) { astError( AST__INTER, "CleanXml: Invalid object type (%ld) supplied " "(internal AST programming error).", status, type ); } } static const char *DefaultURI( AstXmlElement *elem, int *status ){ /* * Name: * DefaultURI * Purpose: * Find the URI associated with the default namespace. * Type: * Private function. * Synopsis: * #include "xml.h" * const char *DefaultURI( AstXmlElement *elem, int *status ) * Description: * This function returns the default namespace URI defined within the * given element. If the element does not define a default namespace URI, * then this function is called recursively on the parent element. If * there is no parent element, NULL is returned. * Parameters: * elem * The pointer to the XmlElement. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a string holding the URI, or NULL if not found. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. */ /* Local Variables: */ AstXmlParent *parent; /* Parent of "this" */ const char *result; /* Returned pointer */ /* Initialise */ result = NULL; /* Check the global error status, and the supplied element. */ if( !astOK || !elem ) return result; /* If the supplied element defines a default namespace URI, return it. Otherwise, call this function to get the default namespace URI from the parent element. */ result = elem->defns; if( !result ) { parent = ( (AstXmlObject *) elem )->parent; if( astXmlCheckType( parent, AST__XMLELEM ) ) { result = DefaultURI( (AstXmlElement *) parent, status ); } } /* If the element has a blank default namespace URI, then return NULL since the XML namespaces specification says that "The default namespace can be set to the empty string. This has the same effect, within the scope of the declaration, of there being no default namespace". */ if( result && astChrLen( result ) == 0 ) result = NULL; /* Return the result. */ return result; } void *astXmlDelete_( void *obj_ptr, int *status ){ /* *+ * Name: * astXmlDelete * Purpose: * Remove the supplied XmlObject from its parent and delete it. * Type: * Protected function. * Synopsis: * #include "xml.h" * void *astXmlDelete( void *obj ) * Description: * This function removes the supplied XmlObject from its parent and * deletes it using astXmlAnnul. * Parameters: * obj * The pointer to the XmlObject to be deleted. * Returned Value: * NULL * Notes: * - This function attempts to execute even if an error has already * occurred. *- */ /* Local Variables: */ AstXmlDocument *doc; /* Pointer to XM document */ AstXmlElement *elem; /* Pointer to XML element */ AstXmlObject *obj; /* Pointer to XmlObject */ AstXmlParent *parent; /* Pointer to parent */ AstXmlPrologue *pro; /* Pointer to XML prologue */ int i; /* Loop counter */ int j; /* Loop counter */ int n; /* Number of values in list */ int ok; /* Is obj a child of its parent? */ void *result; /* Returned pointer */ /* Initialise */ result = NULL; ok = 0; /* Check we have an XmlObject. */ if( !astXmlCheckType( obj_ptr, AST__XMLOBJECT ) ) return result; /* Get the parent of the supplied object. */ obj = (AstXmlObject *) obj_ptr; parent = obj->parent; if( parent ) { /* First deal with cases where we are deleting items from a document. */ if( astXmlCheckType( parent, AST__XMLDOC ) ) { doc = (AstXmlDocument *) parent; if( astXmlCheckType( obj, AST__XMLPRO ) ) { if( (AstXmlPrologue *) obj == doc->prolog ) { doc->prolog = NULL; ok = 1; } } else if( astXmlCheckType( obj, AST__XMLELEM ) ) { if( (AstXmlElement *) obj == doc->root ) { doc->root = NULL; ok = 1; } } else if( astXmlCheckType( obj, AST__XMLMISC ) ) { n = doc->nepi; for( i = 0; i < n; i++ ) { if( doc->epilog[ i ] == (AstXmlMiscItem *) obj ) { for( j = i + 1; j < n; j++ ) { doc->epilog[ j - 1 ] = doc->epilog[ j ]; } doc->epilog[ --doc->nepi ] = NULL; ok = 1; break; } } } else if( astOK ) { astError( AST__INTER, "astXmlDelete(xml): XmlObject of type %ld has " "inappropriate parent of type %ld (internal AST " "programming error).", status, obj->type, parent->type ); } /* Now deal with cases where we are deleting items from a prologue. */ } else if( astXmlCheckType( parent, AST__XMLPRO ) ) { pro = (AstXmlPrologue *) parent; if( astXmlCheckType( obj, AST__XMLDEC ) ) { if( (AstXmlDeclPI *) obj == pro->xmldecl ) { pro->xmldecl = NULL; ok = 1; } } else if( astXmlCheckType( obj, AST__XMLDTD ) ) { if( (AstXmlDTDec *) obj == pro->dtdec ) { pro->dtdec = NULL; ok = 1; } } else if( astXmlCheckType( obj, AST__XMLMISC ) ) { n = pro->nmisc1; for( i = 0; i < n; i++ ) { if( pro->misc1[ i ] == (AstXmlMiscItem *) obj ) { for( j = i + 1; j < n; j++ ) { pro->misc1[ j - 1 ] = pro->misc1[ j ]; } pro->misc1[ --pro->nmisc1 ] = NULL; ok = 1; break; } } if( !ok ) { n = pro->nmisc2; for( i = 0; i < n; i++ ) { if( pro->misc2[ i ] == (AstXmlMiscItem *) obj ) { for( j = i + 1; j < n; j++ ) { pro->misc2[ j - 1 ] = pro->misc2[ j ]; } pro->misc2[ --pro->nmisc2 ] = NULL; ok = 1; break; } } } } else if( astOK ) { astError( AST__INTER, "astXmlDelete(xml): XmlObject of type %ld has " "inappropriate parent of type %ld (internal AST " "programming error).", status, obj->type, parent->type ); } /* Now deal with cases where we are deleting items from an element. */ } else if( astXmlCheckType( parent, AST__XMLELEM ) ) { elem = (AstXmlElement *) parent; /* Remove the object form the appropriate list in the parent, and then shuffle down the remaining entries in the list and decrement the size of the list. */ if( astXmlCheckType( obj, AST__XMLATTR ) ) { n = elem->nattr; for( i = 0; i < n; i++ ) { if( elem->attrs[ i ] == (AstXmlAttribute *) obj ) { for( j = i + 1; j < n; j++ ) { elem->attrs[ j - 1 ] = elem->attrs[ j ]; } elem->attrs[ --elem->nattr ] = NULL; ok = 1; break; } } } else if( astXmlCheckType( obj, AST__XMLNAME ) ) { n = elem->nnspref; for( i = 0; i < n; i++ ) { if( elem->nsprefs[ i ] == (AstXmlNamespace *) obj ) { for( j = i + 1; j < n; j++ ) { elem->nsprefs[ j - 1 ] = elem->nsprefs[ j ]; } elem->nsprefs[ --elem->nnspref ] = NULL; ok = 1; break; } } } else if( astXmlCheckType( obj, AST__XMLCONT ) ) { n = elem->nitem; for( i = 0; i < n; i++ ) { if( elem->items[ i ] == (AstXmlContentItem *) obj ) { for( j = i + 1; j < n; j++ ) { elem->items[ j - 1 ] = elem->items[ j ]; } elem->items[ --elem->nitem ] = NULL; ok = 1; break; } } } } else if( astOK ) { astError( AST__INTER, "astXmlDelete(xml): XmlObject of type %ld has " "inappropriate parent of type %ld (internal AST " "programming error).", status, obj->type, parent->type ); } /* Nullify the parent pointer so that astXmlAnnul will delete the object. */ obj->parent = NULL; /* If the supplied object has no parent, we can continue to annul it. */ } else { ok = 1; } /* Report an error if required. */ if( !ok && astOK ) { astError( AST__INTER, "astXmlDelete(xml): Supplied XmlObject (type %ld) " "is not owned by its own parent (internal AST " "programming error).", status, obj->type ); } /* Delete the object. */ result = astXmlAnnul( obj ); /* Annul the object and return the resulting NULL pointer. */ return result; } static AstXmlAttribute *FindAttribute( AstXmlElement *this, const char *name0, int *status ){ /* * Name: * FindAttribute * Purpose: * Search an XmlElement for a named attribute * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlAttribute *FindAttribute( AstXmlElement *this, const char *name0, * int *status ) * Description: * This function searches the supplied XmlElement for an attribute * with the given name. If found, a pointer to the XmlAttribute is * returned. Otherwise NULL is returned. * Parameters: * this * The pointer to the XmlElement. * name0 * Pointer to a string holding the name of the attribute. The name * may be preceded with a "prefix:" string, in which case the * prefix will also be matched. If no prefix is included, the first * attribute with the specified name is returned, regardless of * its prefix. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the XmlAttribute, or NULL if not found. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. */ /* Local Variables: */ AstXmlAttribute *result; /* Returned pointer */ char name_buffer[ 50 ]; /* Buffer for name */ char prefix_buffer[ 50 ]; /* Buffer for prefix */ const char *colon; /* Pointer to colon in supplied string */ const char *name1; /* Pointer to name to be checked */ const char *name; /* Pointer to name to be searched for */ const char *prefix1; /* Pointer to prefix to be checked */ const char *prefix; /* Pointer to prefix to be searched for */ int i; /* Loop count */ size_t len; /* Length of string */ /* Initialise */ result = NULL; name = name0; prefix = NULL; /* Check the global error status. */ if( !astOK ) return result; /* If the supplied name string contains a colon, split it up into prefix and name. */ if( ( colon = strchr( name0, ':' ) ) ) { len = colon - name0; if( len > 49 ) { astError( AST__XMLNM, "FindAttribute: The XML prefix in \"%s\" " "is too long (> 49 characters).", status, name0 ); } else { strncpy( prefix_buffer, name0, len ); prefix_buffer[ len ] = 0; prefix = prefix_buffer; len = strlen( colon + 1 ); if( len > 49 ) { astError( AST__XMLNM, "FindAttribute: The XML attribute name " "in \"%s\" is too long (> 49 characters).", status, name0 ); } else { strcpy( name_buffer, colon + 1 ); name = name_buffer; } } } /* Loop round all the attributes in the element. */ for( i = 0; i < this->nattr; i++ ) { name1 = this->attrs[ i ]->name; prefix1 = this->attrs[ i ]->prefix; /* Compare the attribute name (and prefix) with the supplied name (and prefix). Leave the loop if they match. */ if( !strcmp( name1, name ) && ( !prefix || ( prefix1 && !strcmp( prefix1, prefix ) ) ) ) { result = this->attrs[ i ]; break; } } /* Return the result. */ return result; } static const char *Format( AstXmlObject *this, int ind, int *status ){ /* * Name: * Format * Purpose: * Converts an XmlObject into a character string. * Type: * Private function. * Synopsis: * #include "xml.h" * const char *Format( AstXmlObject *this, int ind, int *status ) * Description: * This function returns a pointer to a dynamically allocated string * containing a textual representation of the supplied XmlObject. * Parameters: * this * Pointer to the XmlObject to format. * ind * If the XmlObject is an element, then each content item within * the element will be prefixed by a string containing "ind" spaces * (indenting the returned element itself is the responsibility of * the caller and so "this" is not itself indented within this function). * In addition, a newline character will be included at the start * of the prefix if required, to ensure that each new item starts * on a new line. If "ind" is less than zero, then no prefixes are * added. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null terminated string holding the formated XmlObject. * This string should be freed when no longer needed using astFree. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. */ /* Local Variables: */ AstXmlPrologue *pro; /* Pointer to XML prologue */ AstXmlDocument *doc; /* Pointer to XML document */ AstXmlAttribute *attrib; /* Pointer to XML attribute */ AstXmlWhite *white; /* Pointer to character data */ AstXmlBlack *black; /* Pointer to character data */ AstXmlElement *elem; /* Pointer to XML element */ AstXmlNamespace *ns; /* Pointer to XML namespace instruction */ char *result; /* The returned pointer */ const char *temp; /* A temporary string pointer */ int i; /* Loop count */ int nc; /* Length of returned string */ int type; /* Object type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK || !this ) return result; /* Get the object type */ type = this->type; /* If this is an element... */ if( this->type == AST__XMLELEM ) { temp = FormatTag( this, 1, status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); elem = (AstXmlElement *) this; if( elem->nitem > 0 ) { /* Go round all the items of content. */ for( i = 0; i < elem->nitem; i++ ) { /* Ignore whitespace elements unless we are not producing indentation. */ if( !astXmlCheckType( elem->items[ i ], AST__XMLWHITE ) || ind < 0 ) { /* Format the item */ temp = Format( (AstXmlObject *) elem->items[ i ], ( ( ind > -1 ) ? ind + IND_INC : -1 ), status ); if( temp ) { /* Now append the next item of content, and free its memory. */ if( ind > -1 ) { result = AppendLine( result, &nc, temp, ( (ind > -1) ? ind + IND_INC : -1 ), status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } } } /* Finally append the end tag. */ temp = FormatTag( this, 0, status ); if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } /* If this is an attribute... */ } else if( type == AST__XMLATTR ){ attrib = (AstXmlAttribute *) this; if( attrib->prefix ) { result = astAppendString( result, &nc, attrib->prefix ); result = astAppendString( result, &nc, ":" ); } temp = AddEscapes( attrib->value, status ); result = astAppendString( result, &nc, attrib->name ); result = astAppendString( result, &nc, "=\"" ); result = astAppendString( result, &nc, temp ); result = astAppendString( result, &nc, "\"" ); temp = astFree( (void *) temp ); } else if( type == AST__XMLWHITE ){ white = (AstXmlWhite *) this; temp = AddEscapes( white->text, status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); } else if( type == AST__XMLBLACK ){ black = (AstXmlBlack *) this; temp = AddEscapes( black->text, status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); } else if( type == AST__XMLCDATA || type == AST__XMLCOM || type == AST__XMLPI || type == AST__XMLDEC || type == AST__XMLDTD ){ temp = FormatTag( this, 1, status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); } else if( type == AST__XMLNAME ){ ns = (AstXmlNamespace *) this; result = astAppendString( result, &nc, "xmlns:" ); result = astAppendString( result, &nc, ns->prefix ); result = astAppendString( result, &nc, "=\"" ); result = astAppendString( result, &nc, ns->uri ); result = astAppendString( result, &nc, "\"" ); } else if( type == AST__XMLPRO ){ pro = (AstXmlPrologue *) this; result = astAppendString( result, &nc, Format( (AstXmlObject *) pro->xmldecl, ind, status ) ); /* Append all the miscalleneous items before the DTD. */ for( i = 0; i < pro->nmisc1; i++ ) { temp = Format( (AstXmlObject *) pro->misc1[ i ], ind, status ); if( temp ) { if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } } /* Append the DTD. */ temp = Format( (AstXmlObject *) pro->dtdec, ind, status ); if( temp ) { if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } /* Append all the miscalleneous items after the DTD. */ for( i = 0; i < pro->nmisc2; i++ ) { temp = Format( (AstXmlObject *) pro->misc2[ i ], ind, status ); if( temp ) { if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } } } else if( type == AST__XMLDOC ){ doc = (AstXmlDocument *) this; /* Format the prologue. */ result = astAppendString( result, &nc, Format( (AstXmlObject *) doc->prolog, ind, status ) ); /* Append the root element. */ temp = Format( (AstXmlObject *) doc->root, ind, status ); if( temp ) { if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } /* Append all the miscalleneous items in the epilogue. */ for( i = 0; i < doc->nepi; i++ ) { temp = Format( (AstXmlObject *) doc->epilog[ i ], ind, status ); if( temp ) { if( ind > -1 ) { result = AppendLine( result, &nc, temp, ind, status ); } else { result = astAppendString( result, &nc, temp ); } temp = astFree( (void *) temp ); } } } else if( astOK ) { astError( AST__INTER, "Format(xml): Invalid object type (%d) supplied " "(internal AST programming error).", status, type ); } /* Free the returned string if an error has occurred. */ if( !astOK ) result = astFree( result ); /* Return the result. */ return result; } static char *FormatTag( AstXmlObject *this, int opening, int *status ){ /* * Name: * FormatTag * Purpose: * Returns a string holding an XML tag describing the given XmlObject. * Type: * Private function. * Synopsis: * #include "xml.h" * char *FormatTag( AstXmlObject *this, int opening, int *status ) * Description: * This function returns a pointer to a dynamic string containing an * XML tag describing the given XmlObject. * Parameters: * this * Pointer to the XmlObject. * opening * Indicates which tag is to be returned; the start tag or the end * tag. If non-zero the start tag is returned. Otherwise, the * end tag is returned. If the supplied XmlObject has no end * tag (i.e. if it is an empty element, or if it is not an element), * then NULL is returned but no error is reported. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a dynamically allocated string holding the tag. * Notes: * - Empty elements are represented as an start tag of the form <.../>, * with no corresponding end tag. * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. *- */ /* Local Variables: */ AstXmlCDataSection *cdata;/* Pointer to XML CDATA section */ AstXmlElement *elem; /* Pointer to XML element */ AstXmlComment *com; /* Pointer to XML comment */ AstXmlPI *pi; /* Pointer to XML processing instruction */ AstXmlDTDec *dtd; /* Pointer to XML data type declaration */ AstXmlDeclPI *xmlpi; /* XML version declaration */ char *result; /* The returned pointer */ const char *temp; /* A temporary string pointer */ int i; /* Loop count */ int nc; /* Length of returned string */ int type; /* Object type */ /* Initialise */ result = NULL; /* Check the global error status. */ if( !astOK ) return result; /* Get the object type */ type = this->type; /* If this is an element... */ if( this->type == AST__XMLELEM ) { elem = (AstXmlElement *) this; if( opening ) { result = astAppendString( result, &nc, "<" ); if( elem->prefix ) { result = astAppendString( result, &nc, elem->prefix ); result = astAppendString( result, &nc, ":" ); } result = astAppendString( result, &nc, elem->name ); if( elem->defns ) { result = astAppendString( result, &nc, " xmlns=\"" ); result = astAppendString( result, &nc, elem->defns ); result = astAppendString( result, &nc, "\"" ); } for( i = 0; i < elem->nnspref; i++ ) { temp = Format( (AstXmlObject *) elem->nsprefs[ i ], -1, status ); if( temp ) { result = AppendChar( result, &nc, ' ', status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); } } for( i = 0; i < elem->nattr; i++ ) { temp = Format( (AstXmlObject *) elem->attrs[ i ], -1, status ); if( temp ){ result = AppendChar( result, &nc, ' ', status ); result = astAppendString( result, &nc, temp ); temp = astFree( (void *) temp ); } } if( elem->nitem == 0 ) result = astAppendString( result, &nc, "/" ); result = astAppendString( result, &nc, ">" ); } else if( elem->nitem > 0 ) { result = astAppendString( result, &nc, "prefix ) { result = astAppendString( result, &nc, elem->prefix ); result = astAppendString( result, &nc, ":" ); } result = astAppendString( result, &nc, elem->name ); result = astAppendString( result, &nc, ">" ); } } else if( type == AST__XMLDTD ){ dtd = (AstXmlDTDec *) this; if( opening && dtd->name && dtd->name[0] ) { result = astAppendString( result, &nc, "name ); if( dtd->external && dtd->external[ 0 ] ) { result = astAppendString( result, &nc, " " ); result = astAppendString( result, &nc, dtd->external ); } if( dtd->internal && dtd->internal[ 0 ] ) { result = astAppendString( result, &nc, " [" ); result = astAppendString( result, &nc, dtd->internal ); result = astAppendString( result, &nc, "]" ); } result = astAppendString( result, &nc, ">" ); } } else if( type == AST__XMLCDATA ){ if( opening ) { cdata = (AstXmlCDataSection *) this; result = astAppendString( result, &nc, "text ); result = astAppendString( result, &nc, "]]>" ); } } else if( type == AST__XMLCOM ){ if( opening ) { com = (AstXmlComment *) this; result = astAppendString( result, &nc, "" ); } } else if( type == AST__XMLPI ){ pi = (AstXmlPI *) this; if( opening ) { result = astAppendString( result, &nc, "target ); if( pi->text && pi->text[0] ) { result = astAppendString( result, &nc, " " ); result = astAppendString( result, &nc, pi->text ); } result = astAppendString( result, &nc, "?>" ); } } else if( type == AST__XMLDEC ){ xmlpi = (AstXmlDeclPI *) this; if( opening && xmlpi->text && xmlpi->text[0] ) { result = astAppendString( result, &nc, "text && xmlpi->text[0] ) { result = astAppendString( result, &nc, " " ); result = astAppendString( result, &nc, xmlpi->text ); } result = astAppendString( result, &nc, "?>" ); } } /* If notOK, free the rteurned string. */ if( !astOK ) result = astFree( result ); /* Return the result. */ return result; } static void InitXmlAttribute( AstXmlAttribute *new, int type, const char *name, const char *value, const char *prefix, int *status ){ /* * Name: * InitXmlAttribute * Purpose: * Initialise a new XmlAttribute. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlAttribute( AstXmlAttribute *new, int type, const char *name, * const char *value, const char *prefix, int *status ) * Description: * This function initialises supplied memory to hold an XmlAttribute * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * name * The name for the attribute. * value * The value for the attribute * prefix * The namespace prefix for the attribute. May be NULL or blank, in * which case any prefix at the start of "name" is used. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *colon; /* Pointer to colon within supplied name */ char *newname; /* Pointer to name string (no prefix) */ char *newpref; /* Pointer to name string */ int nc; /* Length of prefix string */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLATTR, status ) ){ astError( AST__INTER, "InitXmlAttribute: Supplied object type (%d) " "does not represent an XmlAttribute", status, type ); } /* Ensure we have non-NULL pointers. */ if( !name ) name = ""; if( !value ) value = ""; /* If no prefix was supplied, extract any prefix from the start of the supplied name. */ newname = (char *) name; newpref = (char *) prefix; colon = NULL; if( !prefix || astChrLen( prefix ) == 0 ){ colon = strchr( name, ':' ); if( colon ) { nc = colon - name; newpref = astStore( NULL, name, nc + 1 ); newpref[ nc ] = 0; nc = strlen( name ) - ( colon - name ) - 1; newname = astStore( NULL, colon + 1, nc + 1 ); newname[ nc ] = 0; } } /* Check the supplied name and prefix are valid XML 'names'. */ CheckName( newname, "attribute", "InitXmlAttribute", 0, status ); CheckName( newpref, "attribute", "InitXmlAttribute", 1, status ); /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Initialise the items specific to this class of structure. */ new->name = astStore( NULL, newname, strlen( newname ) + 1 ); new->value = astStore( NULL, value, strlen( value ) + 1 ); new->prefix = NULL; if( newpref ) { nc = strlen( newpref ); if( nc > 0 ) new->prefix = astStore( NULL, newpref, nc + 1 ); } /* Free any name and prefix extracted from the supplied name string */ if( colon ) { newname = astFree( newname ); newpref = astFree( newpref ); } } static void InitXmlCDataSection( AstXmlCDataSection *new, int type, const char *text, int *status ){ /* * Name: * InitXmlCDataSection * Purpose: * Initialise a new XmlCDataSection. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlCDataSection( AstXmlCDataSection *new, int type, * const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlCDataSection * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * text * Pointer to a null terminated string holding the text. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLCDATA, status ) ){ astError( AST__INTER, "InitXmlCDataSection: Supplied object type (%d) " "does not represent an XmlCDataSection", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !text ) text = ""; /* Initialise the items specific to this class of structure. */ new->text = astStore( NULL, text, strlen( text ) + 1 ); } static void InitXmlWhite( AstXmlWhite *new, int type, const char *text, int *status ){ /* * Name: * InitXmlWhite * Purpose: * Initialise a new XmlWhite. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlWhite( AstXmlWhite *new, int type, const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlWhite * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * text * Pointer to a null terminated string holding the text. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *c; /* Pointer to next character */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLWHITE, status ) ){ astError( AST__INTER, "InitXmlWhite: Supplied object type (%d) " "does not represent an XmlWhite", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !text ) text = ""; /* Report an error if the text is not white. */ c = text - 1; while( *(++c) ) { if( !isspace( *c ) ) { astError( AST__XMLCM, "InitXmlWhite(xml): Illegal XML whitespace " "string supplied \"%s\" - not all characters are white.", status, text ); break; } } /* Initialise the items specific to this class of structure. */ new->text = astStore( NULL, text, strlen( text ) + 1 ); } static void InitXmlBlack( AstXmlBlack *new, int type, const char *text, int *status ){ /* * Name: * InitXmlBlack * Purpose: * Initialise a new XmlBlack. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlBlack( AstXmlBlack *new, int type, const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlBlack * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * text * Pointer to a null terminated string holding the text. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLBLACK, status ) ){ astError( AST__INTER, "InitXmlBlack: Supplied object type (%d) " "does not represent an XmlBlack", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !text ) text = ""; /* Initialise the items specific to this class of structure. */ new->text = astStore( NULL, text, strlen( text ) + 1 ); } static void InitXmlComment( AstXmlComment *new, int type, const char *text, int *status ){ /* * Name: * InitXmlComment * Purpose: * Initialise a new XmlComment. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlComment( AstXmlComment *new, int type, const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlComment * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * text * Pointer to a null terminated string holding the text. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLCOM, status ) ){ astError( AST__INTER, "InitXmlComment: Supplied object type (%d) " "does not represent an XmlComment", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !text ) text = ""; /* Initialise the items specific to this class of structure. Report an error if the comment is illegal. */ if( strstr( text, "--" ) && astOK ) { astError( AST__XMLCM, "InitXmlCom(xml): Illegal XML comment " "supplied \"%s\" - comments may not contain the " "string \"--\".", status, text ); new->text = NULL; } else { new->text = astStore( NULL, text, strlen( text ) + 1 ); } } static void InitXmlDeclPI( AstXmlDeclPI *new, int type, const char *text, int *status ){ /* * Name: * InitXmlDeclPI * Purpose: * Initialise a new XmlDeclPI. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlDeclPI( AstXmlDeclPI *new, int type, const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlDeclPI * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * text * Pointer to a null terminated string holding the text. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLDEC, status ) ){ astError( AST__INTER, "InitXmlDeclPI: Supplied object type (%d) " "does not represent an XmlDeclPI", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !text ) text = ""; /* Initialise the items specific to this class of structure. */ new->text = astStore( NULL, text, strlen( text ) + 1 ); } static void InitXmlDocument( AstXmlDocument *new, int type, int *status ){ /* * Name: * InitXmlDocument * Purpose: * Initialise a new XmlDocument. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlDocument( AstXmlDocument *new, int type, int *status ) * Description: * This function initialises supplied memory to hold an XmlDocument * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLDOC, status ) ){ astError( AST__INTER, "InitXmlDocument: Supplied object type (%d) " "does not represent an XmlDocument", status, type ); } /* Initialise the parent XmlObject */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Initialise the items specific to this class of structure. */ new->prolog = NULL; new->root = NULL; new->epilog = NULL; new->nepi = 0; new->current = NULL; } static void InitXmlDTDec( AstXmlDTDec *new, int type, const char *name, const char *external, const char *internal, int *status ){ /* * Name: * InitXmlDTDec * Purpose: * Initialise a new XmlDTDec. * Type: * Private function. * Synopsis: * #include "xml.h" * void InitXmlDTDec( AstXmlDTDec *new, int type, const char *name, * const char *external, const char *internal, int *status ) * Description: * This function initialises supplied memory to hold an XmlDTDec * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * name * The document type name * external * The external SYSTEM id. * internal * The internal declaration markup text (this is not checked or * parsed). * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLDTD, status ) ){ astError( AST__INTER, "InitXmlDTDec: Supplied object type (%d) " "does not represent an XmlDTDec", status, type ); } /* Initialise the parent XmlObject */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !name ) name = ""; if( !external ) external = ""; if( !internal ) internal = ""; /* Initialise the items specific to this class of structure. */ new->name = astStore( NULL, name, strlen( name ) + 1 ); new->external = astStore( NULL, external, strlen( external ) + 1 ); new->internal = astStore( NULL, internal, strlen( internal ) + 1 ); } static void InitXmlElement( AstXmlElement *new, int type, const char *name, const char *prefix, int *status ){ /* * Name: * InitXmlElement * Purpose: * Initialise a new XmlElement. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlElement( AstXmlElement *new, int type, const char *name, * const char *prefix, int *status ) * Description: * This function initialises supplied memory to hold an XmlElement * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * name * The name for the element. * prefix * The namespace prefix for the element. May be NULL or blank, in * which case any prefix at the start of "name" is used. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *colon; /* Pointer to colon within supplied name */ char *newname; /* Pointer to name string (no prefix) */ char *newpref; /* Pointer to name string */ int nc; /* Length of prefix string */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLELEM, status ) ){ astError( AST__INTER, "InitXmlElement: Supplied object type (%d) " "does not represent an XmlElement", status, type ); } /* Ensure we have non-NULL pointers. */ if( !name ) name = ""; /* If no prefix was supplied, extract any prefix from the start of the supplied name. */ newname = (char *) name; newpref = (char *) prefix; colon = NULL; if( !prefix || astChrLen( prefix ) == 0 ){ colon = strchr( name, ':' ); if( colon ) { nc = colon - name; newpref = astStore( NULL, name, nc + 1 ); newpref[ nc ] = 0; nc = strlen( name ) - ( colon - name ) - 1; newname = astStore( NULL, colon + 1, nc + 1 ); newname[ nc ] = 0; } } /* Check the supplied name and prefix are valid XML 'names'. */ CheckName( newname, "element", "InitXmlElement", 0, status ); CheckName( newpref, "element", "InitXmlElement", 1, status ); /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Initialise the items specific to this class of structure. */ new->name = astStore( NULL, newname, strlen( newname ) + 1 ); new->attrs = NULL; new->nattr = 0; new->items = NULL; new->nitem = 0; new->defns = NULL; new->nsprefs = NULL; new->nnspref = 0; new->complete = 0; new->prefix = NULL; if( newpref ) { nc = strlen( newpref ); if( nc > 0 ) new->prefix = astStore( NULL, newpref, nc + 1 ); } /* Free any name and prefix extracted from the supplied name string */ if( colon ) { newname = astFree( newname ); newpref = astFree( newpref ); } } static void InitXmlNamespace( AstXmlNamespace *new, int type, const char *prefix, const char *uri, int *status ){ /* * Name: * InitXmlNamespace * Purpose: * Initialise a new XmlNamespace. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlNamespace( AstXmlNamespace *new, int type, const char *prefix, * const char *uri, int *status ) * Description: * This function initialises supplied memory to hold an XmlNamespace * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * prefix * Pointer to a null terminated string holding the namespace prefix. * uri * Pointer to a null terminated string holding the namespace URI. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLNAME, status ) ){ astError( AST__INTER, "InitXmlNamespace: Supplied object type (%d) " "does not represent an XmlNamespace", status, type ); } /* Ensure we have non-NULL pointers. */ if( !prefix ) prefix = ""; if( !uri ) uri = ""; /* Check the supplied prefix is a valid XML 'name'. */ CheckName( prefix, "namespace prefix", "InitXmlNamespace", 0, status ); /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Initialise the items specific to this class of structure. */ new->prefix = astStore( NULL, prefix, strlen( prefix ) + 1 ); new->uri = astStore( NULL, uri, strlen( uri ) + 1 ); } static void InitXmlObject( AstXmlObject *new, long int type, int *status ){ /* * Name: * InitXmlObject * Purpose: * Initialise a new XmlObject. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlObject( AstXmlObject *new, long int type, int *status ) * Description: * This function initialises supplied memory to hold an XmlObject * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Check the global error status. */ if( !astOK ) return; /* If needed, get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the supplied object type is OK. Report an error if not. */ if( !CheckType( type, AST__XMLOBJECT, status ) ){ astError( AST__INTER, "InitXmlObject: Supplied object type (%ld) " "is not appropriate for an XmlObject", status, type ); } /* This class of structure is the base class for XML objects so it has no parent class to be initialised. So just initialise the items specific to this class of structure. */ new->parent = NULL; new->type = type; new->id = next_id++; #ifdef DEBUG /* Add the new XmlObject to the list of all XmlObjects. */ AddObjectToList( new ); #endif } static void InitXmlPI( AstXmlPI *new, int type, const char *target, const char *text, int *status ){ /* * Name: * InitXmlPI * Purpose: * Initialise a new XmlPI. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlPI( AstXmlPI *new, int type, const char *target, * const char *text, int *status ) * Description: * This function initialises supplied memory to hold an XmlPI * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * target * Pointer to a null terminated string holding the PI target. * text * Pointer to a null terminated string holding the PI text. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLPI, status ) ){ astError( AST__INTER, "InitXmlPI: Supplied object type (%d) " "does not represent an XmlPI", status, type ); } /* Initialise the parent XmlObject component. */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Ensure we have non-NULL pointers. */ if( !target ) target = ""; if( !text ) text = ""; /* Initialise the items specific to this class of structure. Report an error if anything is illegal. */ new->target = NULL; new->text = NULL; if( !Ustrcmp( target, "XML", status ) && astOK ) { astError( AST__XMLPT, "InitXmlPI(xml): Illegal XML PI target \"%s\"" " supplied.", status, target ); } else { new->target = astStore( NULL, target, strlen( target ) + 1 ); new->text = astStore( NULL, text, strlen( text ) + 1 ); } } static void InitXmlPrologue( AstXmlPrologue *new, int type, int *status ){ /* * Name: * InitXmlPrologue * Purpose: * Initialise a new XmlPrologue. * Type: * Private function. * Synopsis: * #include "xml.h" * InitXmlPrologue( AstXmlPrologue *new, int type, int *status ) * Description: * This function initialises supplied memory to hold an XmlPrologue * structure. * Parameters: * new * The memory in which to initialise the structure. * type * An identifier for the structure type. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if( !astOK ) return; /* Check the supplied object type is appropriate for the class of structure being initialised. If not report an error. */ if( !CheckType( type, AST__XMLPRO, status ) ){ astError( AST__INTER, "InitXmlPrologue: Supplied object type (%d) " "does not represent an XmlPrologue", status, type ); } /* Initialise the parent XmlObject */ InitXmlObject( (AstXmlObject *) new, type, status ); /* Initialise the items specific to this class of structure. */ new->xmldecl = NULL; new->misc1 = NULL; new->nmisc1 = 0; new->dtdec = NULL; new->misc2 = NULL; new->nmisc2 = 0; } static int MatchName( AstXmlElement *this, const char *name, int *status ){ /* * Name: * MatchName * Purpose: * Check that an element has a specified name and/or prefix. * Type: * Private function. * Synopsis: * #include "xml.h" * int MatchName( AstXmlElement *this, const char *name, int *status ) * Description: * This function checks that an element has a specified name and/or prefix. * Parameters: * this * The XmlElement to check. * name * The name for the element (may include a namespace prefix). * status * Pointer to the inherited status variable. * Returned Value: * One if the supplied element has the supplie dname/prefix. Zero * otherwise. */ /* Local Variables: */ const char *colon; /* Pointer to colon within supplied name */ char *newname; /* Pointer to name string (no prefix) */ char *newpref; /* Pointer to name string */ int nc; /* Length of prefix string */ int result; /* Returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if( !astOK ) return result; /* Extract any prefix from the start of the supplied name. */ newpref = NULL; newname = (char *) name; colon = strchr( name, ':' ); if( colon ) { nc = colon - name; newpref = astStore( NULL, name, nc + 1 ); newpref[ nc ] = 0; nc = strlen( name ) - ( colon - name ) - 1; newname = astStore( NULL, colon + 1, nc + 1 ); newname[ nc ] = 0; } /* Compare the prefix. */ if( newpref && this->prefix ) { result = !strcmp( newpref, this->prefix ); } else if( !newpref && !this->prefix ) { result = 1; } else { result = 0; } /* If the prefixes matches, compare the names */ if( result ) { if( newname && this->name ) { result = !strcmp( newname, this->name ); } else if( !newname && !this->name ) { result = 1; } else { result = 0; } } /* Free any name and prefix extracted from the supplied name string */ if( colon ) { newname = astFree( newname ); newpref = astFree( newpref ); } /* Return the result. */ return result; } static AstXmlAttribute *NewAttribute( const char *name, const char *value, const char *prefix, int *status ){ /* * Name: * NewAttribute * Purpose: * Create a new XmlAttribute. * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlAttribute *NewAttribute( const char *name, const char *value, * const char *prefix, int *status ) * Description: * This function creates a new XmlAttribute structure representing an * XML attribute with the given name, value and namespace prefix. * Parameters: * name * Pointer to a null terminated string containing the attribute name. * value * Pointer to a null terminated string containing the attribute value. * prefix * Pointer to a null terminated string containing the attribute * namespace prefix (may be NULL or blank). * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new structure is returned. * Notes: * - A NULL pointer is returned if the inherited status value * indicates an error has occurred on entry, or if this function * should fail for any reason. */ /* Local Variables: */ AstXmlAttribute *new; /* The returned pointer */ /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Allocate space for the new structure. */ new = (AstXmlAttribute *) astMalloc( sizeof( AstXmlAttribute ) ); /* Initialise it. */ InitXmlAttribute( new, AST__XMLATTR, name, value, prefix, status ); /* If an error occurred, delete the new structure. */ if( !astOK ) new = astXmlDelete( new ); /* Return the result. */ return new; } static AstXmlDocument *NewDocument( int *status ){ /* * Name: * NewDocument * Purpose: * Create a new empty XmlDocument. * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlDocument *NewDocument( int *status ) * Description: * This function creates a new empty XmlDocument structure representing * an entire XML Document. * Parameters: * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new structure is returned. * Notes: * - A NULL pointer is returned if the inherited status value * indicates an error has occurred on entry, or if this function * should fail for any reason. */ /* Local Variables: */ AstXmlDocument *new; /* The returned pointer */ /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Allocate space for the new structure. */ new = (AstXmlDocument *) astMalloc( sizeof( AstXmlDocument ) ); /* Initialise it. */ InitXmlDocument( new, AST__XMLDOC, status ); /* If an error occurred, delete the new structure. */ if( !astOK ) new = astXmlDelete( new ); /* Return the result. */ return new; } static AstXmlNamespace *NewNamespace( const char *prefix, const char *uri, int *status ){ /* * Name: * NewNamespace * Purpose: * Create a new XmlNamespace. * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlNamespace *NewNamespace( const char *prefix, * const char *uri, int *status ) * Description: * This function creates a new XmlNamespace structure representing an * XML namespace with the given prefix and uri. * Parameters: * prefix * Pointer to a null terminated string containing the namespace prefix. * uri * Pointer to a null terminated string containing the associated URI. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new structure is returned. * Notes: * - A NULL pointer is returned if the inherited status value * indicates an error has occurred on entry, or if this function * should fail for any reason. */ /* Local Variables: */ AstXmlNamespace *new; /* The returned pointer */ /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Allocate space for the new structure. */ new = (AstXmlNamespace *) astMalloc( sizeof( AstXmlNamespace ) ); /* Initialise it. */ InitXmlNamespace( new, AST__XMLNAME, prefix, uri, status ); /* If an error occurred, delete the new structure. */ if( !astOK ) new = astXmlDelete( new ); /* Return the result. */ return new; } static AstXmlPrologue *NewPrologue( AstXmlDocument *doc, int *status ){ /* * Name: * NewPrologue * Purpose: * Create a new empty XmlPrologue. * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlPrologue *NewPrologue( AstXmlDocument *doc, int *status ) * Description: * This function creates a new empty XmlPrologue structure representing * an entire prologue. * Parameters: * doc * A pointer to the XmlDocument to add the XmlPrologue to, or NULL. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new structure is returned. * Notes: * - A NULL pointer is returned if the inherited status value * indicates an error has occurred on entry, or if this function * should fail for any reason. */ /* Local Variables: */ AstXmlPrologue *new; /* The returned pointer */ /* Initialise */ new = NULL; /* Check the global error status. */ if( !astOK ) return new; /* Allocate space for the new structure. */ new = (AstXmlPrologue *) astMalloc( sizeof( AstXmlPrologue ) ); /* Initialise it. */ InitXmlPrologue( new, AST__XMLPRO, status ); /* Set its parent. */ ((AstXmlObject *) new )->parent = (AstXmlParent *) doc; /* If an error occurred, delete the new structure. */ if( !astOK ) new = astXmlDelete( new ); /* Return the result. */ return new; } static char *RemoveEscapes( const char *text, int *status ){ /* * Name: * RemoveEscapes * Purpose: * Replaces entity references by corresponding ascii characters. * Type: * Private function. * Synopsis: * #include "xml.h" * char *RemoveEscapes( const char *text, int *status ) * Description: * This function produces a dynamic copy of the supplied text in which * occurrences of XML entity references are replaced by the corresponding * ASCII text. * Parameters: * text * A pointer to a text string. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated string containing the required * copy. * Notes: * - NULL is returned if this function is called with the global error * status set, or if it should fail for any reason. */ /* Local Variables: */ char *d; /* Pointer to next returned character */ char *result; /* Returned pointer */ char rc; /* Replacement character */ const char *c; /* Pointer to next supplied character */ int nc; /* Number of characters to skip */ /* Initialise */ result = NULL; nc = 0; /* Return if the pointer is NULL or if an error has occurred. */ if( !astOK || !text ) return result; /* Allocate memory to hold a copy of the supplied text. */ result = astMalloc( strlen( text ) + 1 ); /* Check the pointer can be used safely. */ if( astOK ) { /* Loop round every character in the supplied text. */ c = text - 1; d = result; while( *(++c) ) { /* If this character marks the start of a entity reference, replace it by the corresponding ascii character and shuffle the remaining text down. */ if( !strncmp( c, "&", 5 ) ) { rc = '&'; nc= 4; } else if( !strncmp( c, "<", 4 ) ) { rc = '<'; nc= 3; } else if( !strncmp( c, ">", 4 ) ) { rc = '>'; nc= 3; } else if( !strncmp( c, "'", 6 ) ) { rc = '\''; nc= 5; } else if( !strncmp( c, """, 6 ) ) { rc = '"'; nc= 5; } else { rc = 0; } if( rc ) { *(d++) = rc; c += nc; } else { *(d++) = *c; } } /* Terminate the returned string. */ *d = 0; /* Reallocate the string to free up any unused space. */ result = astRealloc( result, d - result + 1 ); } /* Return the result. */ return result; } #ifdef DEBUG static void RemoveObjectFromList( AstXmlObject *obj ){ /* * Name: * RemoveObjectFromList * Purpose: * Removes an XmlObject from a static list of all currently active XmlObjects. * Type: * Private function. * Synopsis: * #include "xml.h" * void RemoveObjectFromList( AstXmlObject *obj ) * Description: * This function removes the supplied pointer from a static list of * pointers, and decrements the number of elements in the list. This list * holds pointers to all the XmlObjects which currently exist. If the * supplied pointer is not found in the list, this function returns * without action. * Parameters: * this * A pointer to the XmlObject. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variavles: */ int i; int ii; /* Locate the supplied pointer within the list of pointers to all currently active XmlObjects. */ ii = -1; for( i = 0; i < nobj; i++ ){ if( existing_objects[ i ]->id == obj->id ) { ii = i; break; } } /* Check the pointer was found. */ if( ii != -1 ) { /* Shuffle all higher index pointers down one in the list in order to fill the gap left by removing the supplied pointer. */ for( ii++; ii < nobj; ii++ ){ existing_objects[ ii - 1 ] = existing_objects[ ii ]; } /* Decrement the number of pointers in the list. */ nobj--; /* Nullify the pointer at the end of the list which is no longer used. */ existing_objects[ nobj ] = NULL; } } #endif static const char *ResolvePrefix( const char *prefix, AstXmlElement *elem, int *status ){ /* * Name: * ResolvePrefix * Purpose: * Find the URI associated with a namespace prefix. * Type: * Private function. * Synopsis: * #include "xml.h" * const char *ResolvePrefix( const char *prefix, AstXmlElement *elem, int *status) * Description: * This function searches the namespaces defined within the supplied * element for a prefix which matches the supplied prefix. If found, * it returns a pointer to the URI string associated with the prefix. * If not found, it calls this function recursively on the parent * element. If there is no parent element, NULL is returned. * Parameters: * prefix * Pointer to a string holding the namespace prefix. * elem * The pointer to the XmlElement. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a string holding the URI, or NULL if not found. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. */ /* Local Variables: */ AstXmlParent *parent; /* Parent object */ AstXmlNamespace *ns; /* Next namespace */ const char *result; /* Returned pointer */ int i; /* Loop count */ /* Initialise */ result = NULL; /* Check the global error status, and the supplied element. */ if( !astOK || !elem ) return result; /* Loop round all the namespace definitions in the element. */ for( i = 0; i < elem->nnspref; i++ ) { ns = elem->nsprefs[ i ]; /* Compare the namespace prefix with the supplied prefix (case sensitive). Store a pointer to the associated URI if they match, and leave the loop. */ if( !strcmp( ns->prefix, prefix ) ) { result = ns->uri; break; } } /* If no matching namespace was found, attempt to resolve the prefix within the context of the parent element. */ if( !result ) { parent = ((AstXmlObject *) elem )->parent; if( astXmlCheckType( parent, AST__XMLELEM ) ) { result = ResolvePrefix( prefix, (AstXmlElement *) parent, status ); } } /* Return the result. */ return result; } static int Ustrcmp( const char *a, const char *b, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strcmp. * Type: * Private function. * Synopsis: * #include "xml.h" * int Ustrcmp( const char *a, const char *b ) * Description: * Returns 0 if there are no differences between the two strings, and 1 * otherwise. Comparisons are case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strcmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Loop round each character. */ while( 1 ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } #ifdef DEBUG int astXmlTrace( int show ){ /* *+ * Name: * astXmlTrace * Purpose: * List details of XML objects currently in existence. * Type: * Protected function. * Synopsis: * #include "xml.h" * int astXmlTrace( int show ) * Description: * Lists details of XML objects currently in existence. Details are * written to standard output. * Parameters: * show * - 0, the ID values of all currently active XmlObjects are * listed. The objects themselves are unchanged. * - 1, each object is displayed using astXmlShow unless it has * already been included in the display of a previous object, and then * annulled. Consequently, this mode is destructive, and none of the * displayed XmlObjects will be acessable afterwards. * - 2, each object is displayed using astXmlShow whether or not it * has already been included in the display of a previous object. * The objects are left unchanged. * - 3, nothing is written to standard output, but the number of * active XmlObjects is still returned. * Returned Value: * The number of XMLObjects which are in existence on entry to this * function. *- */ /* Local Variables: */ AstXmlObject *root; int i, result, old_status; old_status = astStatus; astClearStatus; result = nobj; if( show == 0 ) { printf( "Current list of active XmlObject identifiers: " ); for( i = 0; i < nobj; i++ ) printf( "%d ", existing_objects[ i ]->id ); printf("\n"); } else if( show ==1 ){ while( nobj > 0 ) { root = astXmlGetRoot( existing_objects[0] ); printf( "ID = %d (type %ld)\n%s\n------------\n", root->id, root->type, astXmlShow( root ) ); root = astXmlAnnulTree( root ); } } else if( show == 2 ) { for( i = 0; i < nobj; i++ ) printf( "%d\n%s\n------------\n", existing_objects[ i ]->id, astXmlShow(existing_objects[ i ]) ); printf("\n"); } astSetStatus( old_status ); return result; } #endif AstXmlElement *astXmlReadDocument_( AstXmlDocument **doc, int (*is_wanted)( AstXmlElement *, int * ), int skip, char (*source)( void *, int * ), void *data, int *status ){ /* *+ * Name: * astXmlReadDocument * Purpose: * Read and parse an XML document. * Type: * Protected function. * Synopsis: * #include "xml.h" * AstXmlElement *astXmlReadDocument( AstXmlDocument **doc, * int (*is_wanted)( AstXmlElement *, int * ), * int skip, char (*source)( void *, int * ), * void *data ) * Description: * This function reads and parses text from an XML source. The text is * obtained by calling the supplied "source" function, which returns * the next character read from the external source on each invocation. * * The reading scheme combines elements of the SAX and DOM schemes in * an attempt to minimise memory requirements (a potential problem with * DOM) whilst retaining a simple interface for accessing the XML * elements of interest to the client (a potential problem for SAX). * * When an element start tag is encountered in the source, the client * is asked to indicate whether the element is of interest. This is * done by calling the supplied "is_wanted" function. If the client * indicates that the element is of interest, its contents are read * and a pointer to a corresponding XmlElement structure is returned. * Reading stops when the element has been read. If the client * indicates that the element is not of interest, then (if "skip" is * non-zero) the contents of the element are skipped over, and reading * continues following the element end tag. When the next element is * encountered the client will again be asked to indicate its interest * in the element. This continues until either the client indicates that * an element is of interest, or the end of the source is reached. If * "skip" is zero, then an error is reported if the first element in * the document is not of interest. * * The client has an option to reply that an element is not itself of * interest, but may possibly contain interesting elements. In this case, * the sub-elements within the element are read and checked in the same * way. * * This function returns, and no more characters are read from the * source, once the contents of the first "interesting" element has been * read. * * The function thus returns a pointer to an XmlElement containing the * entire contents of the first interesting element encountered in the * source. This function can then be invoked again to read further * interesting elements from the source. In this case, the XmlDocument * structure created by the initial invocation (see parameter "doc") * must be supplied, as this indicates the point in the total document * structure at which the previous "interesting" element was located. * Parameters: * doc * Address of a location holding a pointer to an AstXmlDocument * structure. The AstXmlDocument pointer should be supplied as NULL * when invoking this function for the first time on a document * source (i.e. when reading from the beginning of the document). * In this case a new AstXmlDocument structure will be created and a * pointer to it stored at the supplied address. This structure * holds the context which enables subsequent invocations of this * function to determine the point in the document structure at * which to store any further text read from the source. It also * holds the document prologue, root element, and epilogue. * is_wanted * Pointer to a function which is called to decide if the client is * interested in each element start tag which has just been read. * It has a single argument which is a pointer to the (empty) XmlElement * corresponding to the element start tag which has just been read. * It returns an integer: * -1 : the element is not itself of interest but it may contain * an interesting element, so look through the content and * ask the client again about any elements found inside it. * 0 : the element definately contains nothing of interest to * the client. kip its content and continue looking for new * elements. * 1 : the element is definately of interest to the client so * read its contents and return a pointer to it. * If NULL is supplied, a value of "+1" is assumed. * skip * Indicates if any uninteresting elements may proceed the first * element of interest. If zero, then an error is reported if the * first element read from the source is not of interest to the client. * If non-zero, then any uninteresting elements are simply skipped * over until an interesting element is found or the document ends. * source * Pointer to a function which is called to return the next * character from the source. It has a single argument which is * used to pass any supplied data to it. It should return zero when * the end of the source is reached. * data * Pointer to a structure to pass to the source function. This * structure may contain any data needed by the source function. * Returned Value: * A pointer to the first element of interest, or NULL if there are no * interesting elements in the source. The returned element will be a * descendant of "*doc". For this reason, the returned pointer need not * be annulled explicitly since it will be freed when the XmlDocument * is annulled. However, if required (e.g. to save memory) it may be * annulled before the document is annulled by using astXmlRemoveItem to * remove it from its parent, and then using astXmlAnnul to annul it. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. * - It is assumed that the read commences outside any tag (i.e. * in between tags or within character data). *- */ /* Local Variables: */ AstXmlElement *result; /* Check any supplied pointer is for an XmlDocument. */ astXmlCheckDocument( *doc, 1 ); /* Read and parse the source text. Indicate that the element being read *may* contain items of interest to the client. Surround with a mutex since the supplied functions may not be thread-safe. */ LOCK_MUTEX1; result = ReadContent( doc, -1, is_wanted, skip, source, data, 0, status ); UNLOCK_MUTEX1; /* Return the result. */ return result; } static AstXmlElement *ReadContent( AstXmlDocument **doc, int wanted, int (*is_wanted)( AstXmlElement *, int * ), int skip, char (*source)( void *, int * ), void *data, int depth, int *status ){ /* * Name: * ReadContent * Purpose: * Read and parse an XML document. * Type: * Private function. * Synopsis: * #include "xml.h" * AstXmlElement *ReadContent( AstXmlDocument **doc, int wanted, * int (*is_wanted)( AstXmlElement *, int * ), * int skip, char (*source)( void *, int * ), * void *data, int depth, int *status ) * Description: * This function reads and parses text from an XML source. The text is * obtained by calling the supplied "source" function, which returns * the next character read from the external source on each invocation. * * See astXmlReadDocument for more details. * Parameters: * doc * Address of a location holding a pointer to an AstXmlDocument * structure. The AstXmlDocument pointer should be supplied as NULL * when invoking this function for the first time on a document * source (i.e. when reading from the beginning of the document). * In this case a new AstXmlDocument structure will be created and a * pointer to it stored at the supplied address. This structure * holds the context which enables subsequent invocations of this * function to determine the point in the document structure at * which to store any further text read from the source. It also * holds the document prologue, root element, and epilogue. * wanted * Indicates if the content read from the XML source is of interest * to the client. If a positive value is supplied, all content read * from the source (up to the end tag which corresponds to the * supplied "parent") is added to the "parent" element (if supplied). * If zero is supplied, then all content read from the source is * discarded. If a negative value is supplied, then all content up * to the first element start tag is discarded. When the first * element start tag is encountered, it is passed back to the client * by invoking the supplied "is_wanted" function. If this function * returns a non-zero value, then the contents of the new element * is read (by calling this function recursively) and a pointer to * the new element is returned as the function value (reading then * stops and the function returns). If the "is_wanted" function returns * zero, then the contents of the new element is skipped over, and * reading continues until the next element start tag is encountered, * when the "is_wanted" function is again invoked. * is_wanted * Pointer to a function which is called to decide if the client is * interested in the element start tag which has just been read. * It has a single argument which is a pointer to the (empty) XmlElement * corresponding to the element start tag which has just been read. * It returns an integer: * -1 : the element is not itself of interest but it may contain * an interesting element, so look through the content and * ask the client again about any elements found inside it. * 0 : the element definately contains nothing of interest to * the client. kip its content and continue looking for new * elements. * 1 : the element is definately of interest to the client so * read its contents and return a pointer to it. * If NULL is supplied, a value of "+1" is assumed. * skip * Indicates if any uninteresting elements may proceed the first * element of interest. If zero, then an error is reported if the * first element read from the source is not of interest to the client. * If non-zero, then any uninteresting elements are simply skipped * over until an interesting element is found or the document ends. * source * Pointer to a function which is called to return the next * character from the source. It has a single argument which is * used to pass any supplied data to it. It should return zero when * the end of the source is reached. * data * Pointer to a structure to pass to the source function. This * structure may contain any data needed by the source function. * depth * Depth of nesting (i.e. zero if this function was invoked from * astXmlReadDocument, and a positive value if it was invoked * recursively from within itself). * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the first element of interest, or NULL if there are no * interesting elements in the source. If the first element of * interest has already been found (as indicated by "wanted" being +1) * then NULL is returned. The returned element may be a child of a * parent element containing namespace definitions (which may itself * have a parent, etc). For this reason, the returned pointer should be * freed using astXmlAnnulTree rather than astXmlAnnul. * Notes: * - NULL is returned if an error has already occurred, or if this * function should fail for any reason. * - It is assumed that the read commences outside any tag (i.e. * in between tags or within character data). */ /* Local Variables; */ AstXmlElement *answer; /* Result of reading a sub-element */ AstXmlElement *parent; /* Pointer to current parent element */ AstXmlElement *elem; /* A new element to be read */ AstXmlElement *result; /* The returned pointer */ char *cc; /* Pointer to next character */ char *msg; /* Pointer to message buffer */ char *text1; /* Pointer to dynamic string */ char *text2; /* Pointer to another dynamic string */ char *text3; /* Pointer to another dynamic string */ char *text4; /* Pointer to another dynamic string */ char c; /* Current character read from source */ char lc2; /* Last but one character read */ char lc; /* Last character read */ char quoted; /* Character which opened current quote */ int nc1; /* No. of characters stored in text1 */ int nc2; /* No. of characters stored in text2 */ int nc3; /* No. of characters stored in text2 */ int ncmsg; /* Length of "msg" */ int newwanted; /* Is the new element wanted? */ int state; /* Current action being performed */ int prolog_ok; /* OK for source to start with a prolog? */ int where; /* Where to add the item within the document */ /* Initialise */ result = NULL; elem = NULL; /* Check the global error status. */ if( !astOK ) return result; /* If no XmlDocument was supplied, assume we are commencing to read a new document from the begining. Create a new XmlDocument to store the prologue, root element and epilogue, together with a pointer to the "current" element, i.e. the element whose content is currently being read. Also, since we have not yet asked the client if it is interested in anything, ignore the supplied "wanted" value and use -1 to ensure that we ask the client when the first element start tag is encountered. */ if( !*doc ){ prolog_ok = 1; *doc = NewDocument( status ); wanted = -1; } else { prolog_ok = 0; } /* Any content read from the source (except for prologue and epilogue) will be placed into the "parent" element. A pointer to this element is stored in the XmlDocument structure. The parent element will always be a descendant of the root element, or the root element itself. */ parent = (*doc)->current; /* If the supplied parent has already been completed (typically because it was read from an empty element tag), then just return without action. */ if( parent && parent->complete ) { /* If an error has occurred, or if this invocation of ReadContent was made recursively (rather than by the client), or if we have something to return, return. */ if( !astOK || depth > 0 || result ) { return result; /* Otherwise, returning would result in returning a null pointer to the client even though the end of the document may not have been reached. Revert to state 0 and search for further interesting elements. */ } else { if( parent != (*doc)->root ) { (*doc)->current = (AstXmlElement *) ( (AstXmlObject *) parent )->parent; } else { (*doc)->current = NULL; } parent = (*doc)->current; state = 0; } } /* Initialise the previous two characters read. */ lc = 0; lc2 = 0; /* Initialise pointer to dynamically allocated strings. */ text1 = NULL; text2 = NULL; text3 = NULL; msg = NULL; /* We are not in a quote. */ quoted = 0; /* Initialise the "state" variable which indicates what we are currently looking for. */ state = 0; /* Loop round reading characters from the source. */ while( 1 ) { c = (*source)( data, status ); /* Leave the loop if an error occurred whilst reading the character. */ if( !astOK ) break; /* If a parent element has been supplied, (i.e. if we are currently reading the content of an element), or if we are not in state zero, report an error and leave the loop if the end of the text has been reached. If no parent was supplied, just leave the loop. */ if( !c ) { if( parent ) { astError( AST__XMLWF, "astRead(XmlChan): End of XML input text " "reached whilst reading the content of element %s.", status, astXmlGetTag( parent, 1 ) ); } else if( state > 1 ) { if( msg ) { astError( AST__XMLWF, "astRead(XmlChan): End of XML input text " "reached whilst reading the document epilogue " "(\"%s\").", status, msg ); } else { astError( AST__XMLWF, "astRead(XmlChan): End of XML input text " "reached whilst reading the document epilogue." , status); } } break; } /* Save text which is not character data for use in error messages. */ if( state < 2 ) { if( msg ) msg = astFree( msg ); } else { msg = AppendChar( msg, &ncmsg, c, status ); } /* State 0: Use the first character to decide what sort of content item follows (character data or a tag of some form). */ if( state == 0 ) { if( c != '<' ) { state = 1; text1 = AppendChar( text1, &nc1, c, status ); } else { msg = AppendChar( msg, &ncmsg, '<', status ); state = 2; } /* State 1: We are reading character data. The character data ends at the first occurrence of "<", at which point the character data is added to the parent if required and we continue to state 2.*/ } else if( state == 1 ) { if( c != '<' ) { text1 = AppendChar( text1, &nc1, c, status ); } else { msg = AppendChar( msg, &ncmsg, '<', status ); if( text1 ){ /* If we have a parent element, just add it to the element. */ if( parent ) { if( wanted > 0 ) { text4 = RemoveEscapes( text1, status ); astXmlAddCharData( (AstXmlParent *) parent, 0, text4 ); text4 = astFree( text4 ); /* If we are not allowed to skip over non-blank content, report an error if the text is not blank. */ } else if( !skip ) { cc = text1 - 1; while( *(++cc) ) { if( !isspace( *cc ) ) { if( parent ) { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data \"%s\" within element %s.", status, text1, astXmlGetTag( parent, 1 ) ); } else { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data: \"%s\".", status, text1 ); } break; } } } /* Otherwise, add it to the document prologue or epilogue. */ } else { if( (*doc)->root ) { where = 3; } else if( (*doc)->prolog && (*doc)->prolog->dtdec ){ where = 2; } else { where = 1; } text4 = RemoveEscapes( text1, status ); astXmlAddCharData( (AstXmlParent *) *doc, where, text4 ); text4 = astFree( text4 ); } text1 = astFree( text1 ); } state = 2; } /* State 2: We are using the character following a "<" to determine what type of tag is commencing. */ } else if( state == 2 ) { /* If the character is a ">", report an error. */ if( c == '>' ) { if( parent ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"<>\" " "encountered within element %s.", status, astXmlGetTag( parent, 1 ) ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"<>\" " "encountered." , status); } break; /* If the character is a "?", this must be a PI tag. */ } else if( c == '?' ) { state = 3; /* If the character is a "!", it must be a comment or a CDATA section or a DTD. */ } else if( c == '!' ) { state = 4; /* If the character is a "/", it must be an element end tag. */ } else if( c == '/' ) { state = 5; /* Otherwise, this must be an element start tag. Append the character to "text1". */ } else { state = 6; text1 = AppendChar( text1, &nc1, c, status ); } /* State 3: We are reading the initial text following the opening "" string is the target text. */ } else if( state == 3 ) { if( c == '>' && lc == '?' ) { if( text1 ) text1[ --nc1 ] = 0; state = 100; } else if( isspace( c ) ) { state = 7; } else { text1 = AppendChar( text1, &nc1, c, status ); } /* State 4: We are using the characters following the opening "' ) { state = 101; } else { text1 = AppendChar( text1, &nc1, c, status ); } /* State 6: We are looking for the (prefix:)name combination at the start of an element start tag. */ } else if( state == 6 ) { if( c == '>' ) { state = ( lc != '/' ) ? 102 : 103; } else if( isspace( c ) ) { state = 104; } else if( c != '/' ){ text1 = AppendChar( text1, &nc1, c, status ); } /* State 7: We are reading the remaining text in a PI tag following the target text. */ } else if( state == 7 ) { if( c == '>' && lc == '?' ) { if( text2 ) text2[ --nc2 ] = 0; state = 100; } else if( text2 || !isspace( c ) ) { text2 = AppendChar( text2, &nc2, c, status ); } /* State 8: We are looking for the start of the text within a comment tag. */ } else if( state == 8 ) { if( c == '-' ) { state = 10; } else { if( parent ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag " "starting with \"" is reached, check the previous 2 characters are "--" and then terminate the text1 string in order to remove these two characters from the comment text. */ } else if( state == 10 ) { if( c == '>' && lc == '-' && lc2 == '-' ) { text1[ nc1 - 2 ] = 0; state = 105; } else { text1 = AppendChar( text1, &nc1, c, status ); } /* State 11: We are reading the remaining text in a CDATA tag. */ } else if( state == 11 ) { if( c == '>' && lc == ']' && lc2 == ']' ) { text1[ nc1 - 2 ] = 0; state = 106; } else { text1 = AppendChar( text1, &nc1, c, status ); } /* State 12: We are looking for an equals sign marking the end of an attribute name within an element start tag. */ } else if( state == 12 ) { if( c == '=' ) { state = 13; } else if( c == '>' ) { if( text1 ) { if( parent ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag " " \"%s...\" encountered within element %s.", status, msg, astXmlGetTag( parent, 1 ) ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s...\" " "encountered.", status, msg ); } break; } else { if( lc == '/' ) { state = 108; } else { state = 200; } } } else if( text1 || !isspace( c ) ) { if( c != '/' ) text1 = AppendChar( text1, &nc1, c, status ); } /* State 13: We are looking for a '"' or ''' marking the start of an attribute value within an element start tag. */ } else if( state == 13 ) { if( c == '"' ) { state = 14; } else if( c == '\'' ) { state = 15; } else if( c == '>' ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal value for attribute " "\"%s\" in XML tag \"%s...\".", status, text1, msg ); break; } /* State 14: We are looking for a '"' marking the end of an attribute value within an element start tag. */ } else if( state == 14 ) { if( c == '"' ) { state = 107; } else if( c == '>' ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal value for attribute " "\"%s\" in XML tag \"%s...\".", status, text1, msg ); break; } else { text2 = AppendChar( text2, &nc2, c, status ); } /* State 15: We are looking for a ''' marking the end of an attribute value within an element start tag. */ } else if( state == 15 ) { if( c == '\'' ) { state = 107; } else if( c == '>' ) { astError( AST__XMLWF, "astRead(XmlChan): Illegal value for attribute " "\"%s\" in XML tag \"%s...\".", status, text1, msg ); break; } else { text2 = AppendChar( text2, &nc2, c, status ); } /* State 16: We are looking for the end of a DOCTYPE string. */ } else if( state == 16 ) { if( isspace( c ) ) { if( !strcmp( text1, "' ) { state = 109; } else { text1 = AppendChar( text1, &nc1, c, status ); } /* State 19: We are looking for the start of a string following a DOCTYPE name string. */ } else if( state == 19 ) { if( !isspace( c ) ) { if( c == '[' ) { state = 20; } else if( c == '>' ) { state = 109; } else { state = 21; text2 = AppendChar( text2, &nc2, c, status ); } } /* State 20: We are looking for the "]" marking the end of the internal markup of a DOCTYPE element. Avoid the contents of quoted strings (such as #FIXED attribute values). */ } else if( state == 20 ) { text3 = AppendChar( text3, &nc3, c, status ); if( c == '\'' ) { if( quoted == '\'' ) { quoted = 0; } else if( !quoted ) { quoted = '\''; } } else if( c == '"' ) { if( quoted == '"' ) { quoted = 0; } else if( !quoted ) { quoted = '"'; } } else if( !quoted && c == ']' ) { text3[ --nc3 ] = 0; state = 22; } /* State 21: We are looking for the start of a DOCTYPE internal section. */ } else if( state == 21 ) { if( c == '[' ) { state = 20; } else if( c == '>' ) { state = 109; } else { text2 = AppendChar( text2, &nc2, c, status ); } /* State 22: We are looking for the ">" at the end of a DOCTYPE. */ } else if( state == 22 ) { if( !isspace( c ) ) { if( c == '>' ) { state = 109; } else { astError( AST__XMLWF, "astRead(XmlChan): Extra text found " "at end of XML DOCTYPE tag \"%s\".", status, msg ); } } } else { astError( AST__INTER, "ReadContent(xml): Illegal state (%d) encountered " "(AST internal programming error).", status, state ); } /* The following states perform actions consequent on the decisons made above, but which must be performed before reading the next character. */ /* In most cases there will be no actions to perform. Therefore check for this first (to avoid the time spent doing all the following usually irrelevant checks). */ if( state < 23 ) { /* State 100: We have just reached the end of a PI tag. Create a new XmlPI and store it in the parent (if required). */ } else if( state == 100 ) { if( text1 ){ /* First deal with XML declaration PI's. These must be the first item in the source. */ if( !strcmp( text1, "xml" ) ) { if( (*doc)->root || (*doc)->prolog || (*doc)->nepi > 0 ) { astError( AST__XMLWF, "astRead(XmlChan): An XML " "declaration \"%s\" was encountered within the " "body of the document.", status, msg ); } else { astXmlSetXmlDec( *doc, text2 ); } /* Now deal with other PI's. */ } else { /* If we have a parent element, just add it to the element. */ if( parent ) { if( wanted > 0 ) { astXmlAddPI( (AstXmlParent *) parent, 0, text1, text2 ); } else if( !skip ) { if( parent ) { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data \"%s\" within element %s.", status, msg, astXmlGetTag( parent, 1 ) ); } else { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data: \"%s\".", status, msg ); } break; } /* Otherwise, add it to the document prologue or epilogue. */ } else { if( (*doc)->root ) { where = 3; } else if( (*doc)->prolog->dtdec ){ where = 2; } else { where = 1; } astXmlAddPI( (AstXmlParent *) *doc, where, text1, text2 ); } } text1 = astFree( text1 ); if( text2 ) text2 = astFree( text2 ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } state = 0; /* State 101: We have just reached the end of an element end tag. Check that the (prefix:)name is legal, and matches that of the current parent, re-instate the parent's parent as the current element in the document, and leave the loop if appropriate. */ } else if( state == 101 ) { if( text1 ){ CheckPrefName( text1, "element", "astRead(XmlChan)", status ); if( parent ) { if( MatchName( parent, text1, status ) ) { parent->complete = 1; if( parent != (*doc)->root ) { (*doc)->current = (AstXmlElement *) ( (AstXmlObject *) parent )->parent; } else { (*doc)->current = NULL; } } else { astError( AST__XMLWF, "astRead(XmlChan): Start tag \"%s\" " "closed by end tag \"%s\".", status, astXmlGetTag( parent, 1 ), msg ); } } else { (*doc)->current = NULL; astError( AST__XMLWF, "astRead(XmlChan): Unmatched end tag " "\"%s\" encountered.", status, msg ); } text1 = astFree( text1 ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); } /* If an error has occurred, or if this invocation of ReadContent was made recursively (rather tnan by the client), or if we have something to return, break out of the loop. */ if( !astOK || depth > 0 || result ) { break; /* Otherwise, breaking would result in returning a null pointer to the client even though the end of the document may not have been reached. Revert to state 0 and search for further intersting elements. */ } else { parent = (*doc)->current; state = 0; } /* State 102: We have just got the (prefix:)name for an element start tag, and the start tag contains no attributes, etc. Create a new XmlElement, adding it to the supplied parent, and then proceed to state 200 to read the content of the element. */ } else if( state == 102 ) { if( text1 ){ elem = astXmlAddElement( parent, text1, NULL ); text1 = astFree( text1 ); state = 200; } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } /* State 103: We have just got the (prefix:)name for an empty element tag, and the tag does not contain further attributes, etc. Create a new XmlElement and store it in the container (if any). Indicate that there is no content to read, and then go on to state 200. */ } else if( state == 103 ) { if( text1 ){ elem = astXmlAddElement( parent, text1, NULL ); elem->complete = 1; text1 = astFree( text1 ); state = 200; } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } /* State 104: We have just got the (prefix:)name for an element start tag, but the start tag may contain further attributes, etc. Create a new XmlElement and store it in the container (if any). Then go to state 12 in which we look for further attributes, etc. */ } else if( state == 104 ) { if( text1 ){ elem = astXmlAddElement( parent, text1, NULL ); text1 = astFree( text1 ); state = 12; } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } /* State 105: We have just reached the end of a comment tag. Create a new XmlComment and store it in the parent. */ } else if( state == 105 ) { if( text1 ){ /* If we have a parent element, just add it to the element. */ if( parent ) { if( wanted > 0 ) { astXmlAddComment( (AstXmlParent *) parent, 0, text1 ); } else if( !skip ) { if( parent ) { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data \"%s\" within element %s.", status, msg, astXmlGetTag( parent, 1 ) ); } else { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data: \"%s\".", status, msg ); } break; } /* Otherwise, add it to the document prologue or epilogue. */ } else { if( (*doc)->root ) { where = 3; } else if( (*doc)->prolog->dtdec ){ where = 2; } else { where = 1; } astXmlAddComment( (AstXmlParent *) *doc, where, text1 ); } text1 = astFree( text1 ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } state = 0; /* State 106: We have just reached the end of a CDATA tag. Create a new XmlCDATASection and store it in the container (if any). */ } else if( state == 106 ) { if( text1 ){ if( parent && wanted > 0 ) { astXmlAddCDataSection( parent, text1 ); } else if( !skip ) { if( parent ) { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data \"%s\" within element %s.", status, msg, astXmlGetTag( parent, 1 ) ); } else { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data: \"%s\".", status, msg ); } break; } text1 = astFree( text1 ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } state = 0; /* State 107: We have just reached the end of an attribute or namespace setting. Create a new object and store it in the element created earlier. */ } else if( state == 107 ) { if( text1 ){ if( !elem ) { astError( AST__INTER, "ReadContent(xml): Container lost at state " "107 (AST internal programming error).", status ); break; } if( !strcmp( text1, "xmlns" ) ) { astXmlAddURI( elem, NULL, text2 ); } else if( !strncmp( text1, "xmlns:", 6 ) ) { astXmlAddURI( elem, text1+6, text2 ); } else { text4 = RemoveEscapes( text2, status ); astXmlAddAttr( elem, text1, text4, NULL ); text4 = astFree( text4 ); } text1 = astFree( text1 ); text2 = astFree( text2 ); } else { astError( AST__XMLWF, "astRead(XmlChan): Illegal XML tag \"%s\" " "encountered.", status, msg ); break; } state = 12; /* State 108: We have just reached the end of an empty element tag to which we have been adding attributes, etc. */ } else if( state == 108 ) { if( elem ) { elem->complete = 1; state = 200; } else { astError( AST__INTER, "Parse(xml): No container in state 108 " "(AST internal programming error).", status ); break; } /* State 109: We have just reached the end of a DOCTYPE tag. */ } else if( state == 109 ) { if( (*doc)->root ){ astError( AST__XMLWF, "astRead(XmlChan): An DOCTYPE tag " "\"%s\" was encountered within the body of the " "document.", status, msg ); break; } else if( (*doc)->prolog->dtdec ){ astError( AST__XMLWF, "astRead(XmlChan): Multiple DOCTYPE tags " "encountered." , status); break; } else { astXmlSetDTDec( *doc, text1, text2, text3 ); text1 = astFree( text1 ); text2 = astFree( text2 ); text3 = astFree( text3 ); state = 0; } } else if( state != 200 ) { astError( AST__INTER, "ReadContent(xml): Illegal state (%d) encountered " "(AST internal programming error).", status, state ); } /* State 200: We now have now read a complete element start tag and have a corresponding XmlElement ("elem"), with all attributes and namespaces, etc (but no content). Call the "is_wanted" function to see if the client is interested in the element. */ if( state == 200 ) { /* If this element is found at the root level of the document, store a pointer to it as the root element. Report an error if there is already a root element. */ if( !parent ) { if( (*doc)->root ){ if( astOK ) { astError( AST__XMLWF, "astRead(XmlChan): Multiple root " "elements encountered." , status); elem = astXmlDelete( elem ); } break; } else { (*doc)->root = elem; ((AstXmlObject *) elem )->parent = (AstXmlParent *) (*doc); } } /* If we do not already know, ask the caller if it is interested in this new element. If no "is_wanted" function was supplied, assume all elements are interesting. */ if( wanted == -1 ) { newwanted = is_wanted ? (*is_wanted)( elem, status ) : 1; } else { newwanted = wanted; } /* If it is not interested, report an error if skip is zero. */ if( newwanted != 1 && !skip ) { if( parent ) { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data \"%s\" within element %s.", status, msg, astXmlGetTag( parent, 1 ) ); } else { astError( AST__BADIN, "astRead(XmlChan): Cannot interpret " "the input data: \"%s\".", status, msg ); } break; } /* Make the new element the "current" element in the document. */ (*doc)->current = elem; /* Read the contents of the new element from the source. If the client is interested in the element, the read contents will be added to the element, otherwise they will be discarded after being read. */ answer = ReadContent( doc, newwanted, is_wanted, skip, source, data, depth + 1, status ); /* If the first interesting element was found inside "elem", then return it. If "elem" is not interesting and did not contain anything of interest, delete it and return the initialised NULL pointer. */ if( newwanted < 0 ) { if( answer ) { result = answer; } else { elem = astXmlDelete( elem ); } /* If the elem is of no interest, delete it and return the initialised NULL pointer. */ } else if( newwanted == 0 ) { elem = astXmlDelete( elem ); /* Otherwise, "elem" itself is definitely of interest. If "elem" is the first item of interest, return it. */ } else if( wanted < 0 ) { result = elem; } /* If we have an answer to return, leave the loop, otherwise re-instate the original current element in the document and continue to read any text following the element. */ if( result ) { break; } else { (*doc)->current = parent; state = 0; } } if( state > 22 ) { astError( AST__INTER, "ReadContent(xml): Illegal state (%d) encountered " "(AST internal programming error).", status, state ); } /* Remember the previous two character */ lc2 = lc; lc = c; } /* Free any dynamic strings */ text1 = astFree( text1 ); text2 = astFree( text2 ); text3 = astFree( text3 ); if( msg ) msg = astFree( msg ); /* Delete the returned object if an error occurred. */ if( !astOK ) result = astXmlDelete( result ); /* Return the result. */ return result; } ast-8.3.0/fitschan.h0000664000175000017500000010337513004147321011210 00000000000000#if !defined( FITSCHAN_INCLUDED ) /* Include this file only once */ #define FITSCHAN_INCLUDED /* *+ * Name: * fitschan.h * Type: * C include file. * Purpose: * Define the interface to the FitsChan class. * Invocation: * #include "fitschan.h" * Description: * This include file defines the interface to the FitsChan class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The FitsChan class provides facilities for reading and writing AST * Objects in the form of FITS header cards. * Inheritance: * The FitsChan class inherits from the Channel class. * Macros: * Protected: * AST__NOTYPE * Integer dentifier for an illegal FITS data type. * AST__COMMENT * Integer dentifier for a FITS comment keyword. * AST__INT * Integer dentifier for the integer FITS data type. * AST__FLOAT * Integer dentifier for the floating point FITS data type. * AST__STRING * Integer dentifier for the string FITS data type. * AST__CONTINUE * Integer dentifier for the continuation string FITS data type. * AST__COMPLEXF * Integer dentifier for the complex floating point FITS data type. * AST__COMPLEXI * Integer dentifier for the complex integer FITS data type. * AST__LOGICAL * Integer dentifier for the logical FITS data type. * AST__UNDEF * Integer dentifier for undefined FITS data type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 11-DEC-1996 (DSB): * Original version. * 30-Jun-1997 (DSB): * Changed character pointer argument to character array in PutFits. * 26-SEP-1997 (DSB): * Added CDMatrix attribute. * 21-OCT-1997 (DSB): * o Renamed astFields as astKeyFields. * 1-APR-2000 (DSB): * Changes for CDi_j based FITS-WCS standard. * 18-MAY-2000 (DSB): * Added Warnings attribute. * 4-APR-2001 (DSB): * Added AllWarnings attribute. * 20-FEB-2002 (DSB): * Added CarLin attribute. * 8-JAN-2003 (DSB): * Added protected astInitFitsChanVtab method. * 13-FEB-2003 (DSB): * Added Clean attribute. * 19-MAR-2004 (DSB): * Added astPutCards function. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" /* I/O channels (parent class) */ #include "pointset.h" /* Defines AST__BAD */ #include "keymap.h" /* Defines the AstKeyMap type */ /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__NOTYPE -1 #define AST__COMMENT 0 #define AST__INT 1 #define AST__FLOAT 2 #define AST__STRING 3 #define AST__COMPLEXF 4 #define AST__COMPLEXI 5 #define AST__LOGICAL 6 #define AST__CONTINUE 7 #define AST__UNDEF 8 #if defined(astCLASS) /* Protected */ /* Define constants used to size global arrays in this module. */ #define AST__FITSCHAN_FITSCARDLEN 80 #define AST__FITSCHAN_GETATTRIB_BUFF_LEN 50 #endif /* The EXTNAME value for FITS binary tables used to store coordinate arrays for the -TAB algorithm. */ #define AST_TABEXTNAME "WCS-TAB" /* Type Definitions. */ /* ================= */ /* FitsChan structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ struct AstFitsChan; typedef struct AstFitsChan { /* Attributes inherited from the parent class. */ AstChannel channel; /* Parent class structure */ /* Attributes specific to objects in this class. */ int encoding; /* System for encoding AST objects ito FITS headers */ int defb1950; /* Use FK4 B1950 as defaults? */ int tabok; /* Support -TAB algorithm? */ int cdmatrix; /* Use a CD matrix in FITS-WCS Encoding? */ int polytan; /* Use distorted TAN convention? */ int carlin; /* Use linear CAR mappings? */ int iwc; /* Include an IWC Frame? */ int clean; /* Remove used cards even if an error occurs? */ int fitsdigits; /* No. of decmial places in formatted floating point keyword values */ char *fitsaxisorder; /* Pointer to a string defining WCS axis order */ char *warnings; /* Pointer to a string containing warning conditions */ void *card; /* Pointer to next FitsCard to be read */ void *head; /* Pointer to first FitsCard in the circular linked list */ AstKeyMap *keyseq; /* List of keyword sequence numbers used */ AstKeyMap *keywords; /* A KeyMap holding the keywords in the FitsChan */ AstKeyMap *tables; /* A KeyMap holding the binary tables in the FitsChan */ const char *(* source)( void ); /* Pointer to source function */ const char *(* saved_source)( void ); /* Pointer to saved source function */ char *(* source_wrap)( const char *(*)( void ), int * ); /* Source wrapper function pointer */ void (* sink)( const char * ); /* Pointer to sink function */ void (* sink_wrap)( void (*)( const char * ), const char *, int * ); /* Sink wrapper function pointer */ void (* tabsource)( void ); /* Pointer to table source function */ void (* tabsource_wrap)( void (*)( void ), struct AstFitsChan *, const char *, int, int, int * ); /* Table source wrapper function pointer */ } AstFitsChan; /* Virtual function table. */ /* ----------------------- */ /* The virtual function table makes a forward reference to the AstFitsTable structure which is not defined until "fitstable.h" is included (below). Hence make a preliminary definition available now. */ struct AstFitsTable; /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstFitsChanVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstChannelVtab channel_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstKeyMap *(* GetTables)( AstFitsChan *, int * ); int (* FindFits)( AstFitsChan *, const char *, char [81], int, int * ); int (* FitsEof)( AstFitsChan *, int * ); int (* FitsGetCom)( AstFitsChan *, const char *, char **, int * ); int (* GetFitsCF)( AstFitsChan *, const char *, double *, int * ); int (* GetFitsCI)( AstFitsChan *, const char *, int *, int * ); int (* GetFitsCN)( AstFitsChan *, const char *, char **, int * ); int (* GetFitsF)( AstFitsChan *, const char *, double *, int * ); int (* GetFitsI)( AstFitsChan *, const char *, int *, int * ); int (* GetFitsL)( AstFitsChan *, const char *, int *, int * ); int (* GetFitsS)( AstFitsChan *, const char *, char **, int * ); int (* KeyFields)( AstFitsChan *, const char *, int, int *, int *, int * ); int (* TestFits)( AstFitsChan *, const char *, int *, int * ); void (* DelFits)( AstFitsChan *, int * ); void (* Empty)( AstFitsChan *, int * ); void (* ReadFits)( AstFitsChan *, int * ); void (* WriteFits)( AstFitsChan *, int * ); void (* EmptyFits)( AstFitsChan *, int * ); void (* ShowFits)( AstFitsChan *, int * ); void (* PurgeWCS)( AstFitsChan *, int * ); void (* PutCards)( AstFitsChan *, const char *, int * ); void (* PutFits)( AstFitsChan *, const char [81], int, int * ); void (* PutTable)( AstFitsChan *, struct AstFitsTable *, const char *, int * ); void (* PutTables)( AstFitsChan *, AstKeyMap *, int * ); void (* RemoveTables)( AstFitsChan *, const char *, int * ); void (* RetainFits)( AstFitsChan *, int * ); void (* SetFitsCF)( AstFitsChan *, const char *, double *, const char *, int, int * ); void (* SetFitsCI)( AstFitsChan *, const char *, int *, const char *, int, int * ); void (* SetFitsCM)( AstFitsChan *, const char *, int, int * ); void (* SetFitsCN)( AstFitsChan *, const char *, const char *, const char *, int, int * ); void (* SetFitsCom)( AstFitsChan *, const char *, const char *, int, int * ); void (* SetFitsF)( AstFitsChan *, const char *, double, const char *, int, int * ); void (* SetFitsI)( AstFitsChan *, const char *, int, const char *, int, int * ); void (* SetFitsL)( AstFitsChan *, const char *, int, const char *, int, int * ); void (* SetFitsS)( AstFitsChan *, const char *, const char *, const char *, int, int * ); void (* SetFitsU)( AstFitsChan *, const char *, const char *, int, int * ); int (* GetCard)( AstFitsChan *, int * ); int (* TestCard)( AstFitsChan *, int * ); void (* SetCard)( AstFitsChan *, int, int * ); void (* ClearCard)( AstFitsChan *, int * ); int (* GetFitsDigits)( AstFitsChan *, int * ); int (* TestFitsDigits)( AstFitsChan *, int * ); void (* SetFitsDigits)( AstFitsChan *, int, int * ); void (* ClearFitsDigits)( AstFitsChan *, int * ); const char *(* GetFitsAxisOrder)( AstFitsChan *, int * ); int (* TestFitsAxisOrder)( AstFitsChan *, int * ); void (* SetFitsAxisOrder)( AstFitsChan *, const char *, int * ); void (* ClearFitsAxisOrder)( AstFitsChan *, int * ); int (* GetDefB1950)( AstFitsChan *, int * ); int (* TestDefB1950)( AstFitsChan *, int * ); void (* SetDefB1950)( AstFitsChan *, int, int * ); void (* ClearDefB1950)( AstFitsChan *, int * ); int (* GetTabOK)( AstFitsChan *, int * ); int (* TestTabOK)( AstFitsChan *, int * ); void (* SetTabOK)( AstFitsChan *, int, int * ); void (* ClearTabOK)( AstFitsChan *, int * ); int (* GetCarLin)( AstFitsChan *, int * ); int (* TestCarLin)( AstFitsChan *, int * ); void (* SetCarLin)( AstFitsChan *, int, int * ); void (* ClearCarLin)( AstFitsChan *, int * ); int (* GetNcard)( AstFitsChan *, int * ); int (* GetCardType)( AstFitsChan *, int * ); const char *(* GetCardName)( AstFitsChan *, int * ); const char *(* GetCardComm)( AstFitsChan *, int * ); int (* GetNkey)( AstFitsChan *, int * ); int (* GetEncoding)( AstFitsChan *, int * ); int (* TestEncoding)( AstFitsChan *, int * ); void (* SetEncoding)( AstFitsChan *, int, int * ); void (* ClearEncoding)( AstFitsChan *, int * ); const char *(* GetAllWarnings)( AstFitsChan *, int * ); const char *(* GetWarnings)( AstFitsChan *, int * ); int (* TestWarnings)( AstFitsChan *, int * ); void (* ClearWarnings)( AstFitsChan *, int * ); void (* SetWarnings)( AstFitsChan *, const char *, int * ); int (* GetClean)( AstFitsChan *, int * ); int (* TestClean)( AstFitsChan *, int * ); void (* SetClean)( AstFitsChan *, int, int * ); void (* ClearClean)( AstFitsChan *, int * ); int (* GetCDMatrix)( AstFitsChan *, int * ); int (* TestCDMatrix)( AstFitsChan *, int * ); void (* SetCDMatrix)( AstFitsChan *, int, int * ); void (* ClearCDMatrix)( AstFitsChan *, int * ); int (* GetPolyTan)( AstFitsChan *, int * ); int (* TestPolyTan)( AstFitsChan *, int * ); void (* SetPolyTan)( AstFitsChan *, int, int * ); void (* ClearPolyTan)( AstFitsChan *, int * ); int (* GetIwc)( AstFitsChan *, int * ); int (* TestIwc)( AstFitsChan *, int * ); void (* SetIwc)( AstFitsChan *, int, int * ); void (* ClearIwc)( AstFitsChan *, int * ); void (* SetTableSource)( AstFitsChan *, void (*)( void ), void (*)( void (*)( void ), AstFitsChan *, const char *, int, int, int * ), int * ); void (* TableSource)( AstFitsChan *, void (*)( AstFitsChan *, const char *, int, int, int * ), int * ); } AstFitsChanVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstFitsChanGlobals { AstFitsChanVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__FITSCHAN_GETATTRIB_BUFF_LEN + 1 ]; char CnvType_Text[ AST__FITSCHAN_FITSCARDLEN + 1 ]; char CnvType_Text0[ AST__FITSCHAN_FITSCARDLEN + 1 ]; char CnvType_Text1[ AST__FITSCHAN_FITSCARDLEN + 1 ]; int Items_Written; int Write_Nest; int Current_Indent; int Ignore_Used; int Mark_New; int CreateKeyword_Seq_Nchars; char FormatKey_Buff[ 10 ]; char FitsGetCom_Sval[ AST__FITSCHAN_FITSCARDLEN + 1 ]; const char *IsSpectral_Ret; char Match_Fmt[ 10 ]; const char *Match_Template; int *Match_PA; int *Match_PB; int Match_NA; int Match_NB; int Match_Nentry; char WcsCelestial_Type[ 4 ]; } AstFitsChanGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(FitsChan) /* Check class membership */ astPROTO_ISA(FitsChan) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstFitsChan *astFitsChan_( const char *(*)( void ), void (*)( const char * ), const char *, int *, ...); #else AstFitsChan *astFitsChanId_( const char *(*)( void ), void (*)( const char * ), const char *, ... )__attribute__((format(printf,3,4))); AstFitsChan *astFitsChanForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstFitsChan *astInitFitsChan_( void *, size_t, int, AstFitsChanVtab *, const char *, const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), int * ); /* Vtab initialiser. */ void astInitFitsChanVtab_( AstFitsChanVtab *, const char *, int * ); /* Loader. */ AstFitsChan *astLoadFitsChan_( void *, size_t, AstFitsChanVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitFitsChanGlobals_( AstFitsChanGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstKeyMap *astGetTables_( AstFitsChan *, int * ); int astFindFits_( AstFitsChan *, const char *, char [81], int, int * ); int astGetFitsCF_( AstFitsChan *, const char *, double *, int * ); int astGetFitsCI_( AstFitsChan *, const char *, int *, int * ); int astGetFitsCN_( AstFitsChan *, const char *, char **, int * ); int astGetFitsF_( AstFitsChan *, const char *, double *, int * ); int astGetFitsI_( AstFitsChan *, const char *, int *, int * ); int astGetFitsL_( AstFitsChan *, const char *, int *, int * ); int astGetFitsS_( AstFitsChan *, const char *, char **, int * ); int astTestFits_( AstFitsChan *, const char *, int *, int * ); void astDelFits_( AstFitsChan *, int * ); void astReadFits_( AstFitsChan *, int * ); void astWriteFits_( AstFitsChan *, int * ); void astEmptyFits_( AstFitsChan *, int * ); void astShowFits_( AstFitsChan *, int * ); void astPurgeWCS_( AstFitsChan *, int * ); void astPutCards_( AstFitsChan *, const char *, int * ); void astPutFits_( AstFitsChan *, const char [81], int, int * ); void astPutTable_( AstFitsChan *, struct AstFitsTable *, const char *, int * ); void astPutTables_( AstFitsChan *, AstKeyMap *, int * ); void astRemoveTables_( AstFitsChan *, const char *, int * ); void astRetainFits_( AstFitsChan *, int * ); void astSetFitsCF_( AstFitsChan *, const char *, double *, const char *, int, int * ); void astSetFitsCI_( AstFitsChan *, const char *, int *, const char *, int, int * ); void astSetFitsCM_( AstFitsChan *, const char *, int, int * ); void astSetFitsCN_( AstFitsChan *, const char *, const char *, const char *, int, int * ); void astSetFitsF_( AstFitsChan *, const char *, double, const char *, int, int * ); void astSetFitsI_( AstFitsChan *, const char *, int, const char *, int, int * ); void astSetFitsL_( AstFitsChan *, const char *, int, const char *, int, int * ); void astSetFitsS_( AstFitsChan *, const char *, const char *, const char *, int, int * ); void astSetFitsU_( AstFitsChan *, const char *, const char *, int, int * ); void astTableSource_( AstFitsChan *, void (*)( AstFitsChan *, const char *, int, int, int * ), int * ); # if defined(astCLASS) || defined(astFORTRAN77) /* Protected or F77 interface */ void astSetTableSource_( AstFitsChan *, void (*)( void ), void (*)( void (*)( void ), AstFitsChan *, const char *, int, int, int * ), int * ); #endif # if defined(astCLASS) /* Protected */ int astFitsEof_( AstFitsChan *, int * ); int astFitsGetCom_( AstFitsChan *, const char *, char **, int * ); void astSetFitsCom_( AstFitsChan *, const char *, const char *, int, int * ); int astKeyFields_( AstFitsChan *, const char *, int, int *, int *, int * ); int astGetCard_( AstFitsChan *, int * ); int astTestCard_( AstFitsChan *, int * ); void astSetCard_( AstFitsChan *, int, int * ); void astClearCard_( AstFitsChan *, int * ); int astGetDefB1950_( AstFitsChan *, int * ); int astTestDefB1950_( AstFitsChan *, int * ); void astSetDefB1950_( AstFitsChan *, int, int * ); void astClearDefB1950_( AstFitsChan *, int * ); int astGetTabOK_( AstFitsChan *, int * ); int astTestTabOK_( AstFitsChan *, int * ); void astSetTabOK_( AstFitsChan *, int, int * ); void astClearTabOK_( AstFitsChan *, int * ); int astGetCDMatrix_( AstFitsChan *, int * ); int astTestCDMatrix_( AstFitsChan *, int * ); void astSetCDMatrix_( AstFitsChan *, int, int * ); void astClearCDMatrix_( AstFitsChan *, int * ); int astGetPolyTan_( AstFitsChan *, int * ); int astTestPolyTan_( AstFitsChan *, int * ); void astSetPolyTan_( AstFitsChan *, int, int * ); void astClearPolyTan_( AstFitsChan *, int * ); int astGetCarLin_( AstFitsChan *, int * ); int astTestCarLin_( AstFitsChan *, int * ); void astSetCarLin_( AstFitsChan *, int, int * ); void astClearCarLin_( AstFitsChan *, int * ); int astGetIwc_( AstFitsChan *, int * ); int astTestIwc_( AstFitsChan *, int * ); void astSetIwc_( AstFitsChan *, int, int * ); void astClearIwc_( AstFitsChan *, int * ); int astGetClean_( AstFitsChan *, int * ); int astTestClean_( AstFitsChan *, int * ); void astSetClean_( AstFitsChan *, int, int * ); void astClearClean_( AstFitsChan *, int * ); int astGetFitsDigits_( AstFitsChan *, int * ); int astTestFitsDigits_( AstFitsChan *, int * ); void astSetFitsDigits_( AstFitsChan *, int, int * ); void astClearFitsDigits_( AstFitsChan *, int * ); const char *astGetFitsAxisOrder_( AstFitsChan *, int * ); int astTestFitsAxisOrder_( AstFitsChan *, int * ); void astSetFitsAxisOrder_( AstFitsChan *, const char *, int * ); void astClearFitsAxisOrder_( AstFitsChan *, int * ); const char *astGetAllWarnings_( AstFitsChan *, int * ); const char *astGetWarnings_( AstFitsChan *, int * ); int astTestWarnings_( AstFitsChan *, int * ); void astClearWarnings_( AstFitsChan *, int * ); void astSetWarnings_( AstFitsChan *, const char *, int * ); int astGetNcard_( AstFitsChan *, int * ); int astGetCardType_( AstFitsChan *, int * ); const char *astGetCardName_( AstFitsChan *, int * ); const char *astGetCardComm_( AstFitsChan *, int * ); int astGetNkey_( AstFitsChan *, int * ); int astGetEncoding_( AstFitsChan *, int * ); int astTestEncoding_( AstFitsChan *, int * ); void astSetEncoding_( AstFitsChan *, int, int * ); void astClearEncoding_( AstFitsChan *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckFitsChan(this) astINVOKE_CHECK(FitsChan,this,0) #define astVerifyFitsChan(this) astINVOKE_CHECK(FitsChan,this,1) /* Test class membership. */ #define astIsAFitsChan(this) astINVOKE_ISA(FitsChan,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astFitsChan astINVOKE(F,astFitsChan_) #else #define astFitsChan astINVOKE(F,astFitsChanId_) #define astFitsChanFor astINVOKE(F,astFitsChanForId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitFitsChan(mem,size,init,vtab,name,source,sourcewrap,sink,sinkwrap) \ astINVOKE(O,astInitFitsChan_(mem,size,init,vtab,name,source,sourcewrap,sink,sinkwrap,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitFitsChanVtab(vtab,name) astINVOKE(V,astInitFitsChanVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadFitsChan(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadFitsChan_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* More include files. */ /* =================== */ /* The interface to the FitsTable class must be included here (after the type definitions for the FitsChan class) because "fitstable.h" itself includes this file ("fitschan.h"), although "fitschan.h" refers to the AstFitsTable structure above. This seems a little strange at first, but is simply analogous to making a forward reference to a structure type when recursively defining a normal C structure (except that here the definitions happen to be in separate include files). */ #include "fitstable.h" /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckFitsChan to validate FitsChan pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astPutFits(this,card,overwrite) \ astINVOKE(V,astPutFits_(astCheckFitsChan(this),card,overwrite,STATUS_PTR)) #define astPutCards(this,cards) \ astINVOKE(V,astPutCards_(astCheckFitsChan(this),cards,STATUS_PTR)) #define astDelFits(this) \ astINVOKE(V,astDelFits_(astCheckFitsChan(this),STATUS_PTR)) #define astPurgeWCS(this) \ astINVOKE(V,astPurgeWCS_(astCheckFitsChan(this),STATUS_PTR)) #define astGetTables(this) \ astINVOKE(O,astGetTables_(astCheckFitsChan(this),STATUS_PTR)) #define astPutTable(this,table,extnam) \ astINVOKE(V,astPutTable_(astCheckFitsChan(this),astCheckFitsTable(table),extnam,STATUS_PTR)) #define astPutTables(this,tables) \ astINVOKE(V,astPutTables_(astCheckFitsChan(this),astCheckKeyMap(tables),STATUS_PTR)) #define astRemoveTables(this,key) \ astINVOKE(V,astRemoveTables_(astCheckFitsChan(this),key,STATUS_PTR)) #define astRetainFits(this) \ astINVOKE(V,astRetainFits_(astCheckFitsChan(this),STATUS_PTR)) #define astFindFits( this, name, card, inc ) \ astINVOKE(V,astFindFits_(astCheckFitsChan(this),name,card,inc,STATUS_PTR)) #define astSetFitsI(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsI_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsF(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsF_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsS(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsS_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsCN(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsCN_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsCI(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsCI_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsCF(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsCF_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsL(this,name,value,comment,overwrite) \ astINVOKE(V,astSetFitsL_(astCheckFitsChan(this),name,value,comment,overwrite,STATUS_PTR)) #define astSetFitsU(this,name,comment,overwrite) \ astINVOKE(V,astSetFitsU_(astCheckFitsChan(this),name,comment,overwrite,STATUS_PTR)) #define astSetFitsCM(this,comment,overwrite) \ astINVOKE(V,astSetFitsCM_(astCheckFitsChan(this),comment,overwrite,STATUS_PTR)) #define astGetFitsCF(this,name,value) \ astINVOKE(V,astGetFitsCF_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astGetFitsCI(this,name,value) \ astINVOKE(V,astGetFitsCI_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astGetFitsF(this,name,value) \ astINVOKE(V,astGetFitsF_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astGetFitsI(this,name,value) \ astINVOKE(V,astGetFitsI_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astGetFitsL(this,name,value) \ astINVOKE(V,astGetFitsL_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astTestFits(this,name,there) \ astINVOKE(V,astTestFits_(astCheckFitsChan(this),name,there,STATUS_PTR)) #define astGetFitsS(this,name,value) \ astINVOKE(V,astGetFitsS_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astGetFitsCN(this,name,value) \ astINVOKE(V,astGetFitsCN_(astCheckFitsChan(this),name,value,STATUS_PTR)) #define astReadFits(this) \ astINVOKE(V,astReadFits_(astCheckFitsChan(this),STATUS_PTR)) #define astWriteFits(this) \ astINVOKE(V,astWriteFits_(astCheckFitsChan(this),STATUS_PTR)) #define astEmptyFits(this) \ astINVOKE(V,astEmptyFits_(astCheckFitsChan(this),STATUS_PTR)) #define astShowFits(this) \ astINVOKE(V,astShowFits_(astCheckFitsChan(this),STATUS_PTR)) #define astTableSource(this,tabsource) \ astINVOKE(V,astTableSource_(astCheckFitsChan(this),tabsource,STATUS_PTR)) #if defined(astCLASS) || defined(astFORTRAN77) /* Protected or F77 interface */ #define astSetTableSource(this,tabsource,tabsource_wrap) \ astINVOKE(V,astSetTableSource_(astCheckFitsChan(this),tabsource,tabsource_wrap,STATUS_PTR)) #endif #if defined(astCLASS) /* Protected */ #define astFitsEof(this) \ astINVOKE(V,astFitsEof_(astCheckFitsChan(this),STATUS_PTR)) #define astFitsGetCom(this,name,comment) \ astINVOKE(V,astFitsGetCom_(astCheckFitsChan(this),name,comment,STATUS_PTR)) #define astSetFitsCom(this,name,comment,overwrite) \ astINVOKE(V,astSetFitsCom_(astCheckFitsChan(this),name,comment,overwrite,STATUS_PTR)) #define astKeyFields(this,filter,maxfld,ubnd,lbnd) \ astINVOKE(V,astKeyFields_(astCheckFitsChan(this),filter,maxfld,ubnd,lbnd,STATUS_PTR)) #define astClearCard(this) \ astINVOKE(V,astClearCard_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCard(this) \ astINVOKE(V,astGetCard_(astCheckFitsChan(this),STATUS_PTR)) #define astSetCard(this,card) \ astINVOKE(V,astSetCard_(astCheckFitsChan(this),card,STATUS_PTR)) #define astTestCard(this) \ astINVOKE(V,astTestCard_(astCheckFitsChan(this),STATUS_PTR)) #define astClearDefB1950(this) \ astINVOKE(V,astClearDefB1950_(astCheckFitsChan(this),STATUS_PTR)) #define astGetDefB1950(this) \ astINVOKE(V,astGetDefB1950_(astCheckFitsChan(this),STATUS_PTR)) #define astSetDefB1950(this,defb950) \ astINVOKE(V,astSetDefB1950_(astCheckFitsChan(this),defb950,STATUS_PTR)) #define astTestDefB1950(this) \ astINVOKE(V,astTestDefB1950_(astCheckFitsChan(this),STATUS_PTR)) #define astClearTabOK(this) \ astINVOKE(V,astClearTabOK_(astCheckFitsChan(this),STATUS_PTR)) #define astGetTabOK(this) \ astINVOKE(V,astGetTabOK_(astCheckFitsChan(this),STATUS_PTR)) #define astSetTabOK(this,tabok) \ astINVOKE(V,astSetTabOK_(astCheckFitsChan(this),tabok,STATUS_PTR)) #define astTestTabOK(this) \ astINVOKE(V,astTestTabOK_(astCheckFitsChan(this),STATUS_PTR)) #define astClearCDMatrix(this) \ astINVOKE(V,astClearCDMatrix_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCDMatrix(this) \ astINVOKE(V,astGetCDMatrix_(astCheckFitsChan(this),STATUS_PTR)) #define astSetCDMatrix(this,cdmatrix) \ astINVOKE(V,astSetCDMatrix_(astCheckFitsChan(this),cdmatrix,STATUS_PTR)) #define astTestCDMatrix(this) \ astINVOKE(V,astTestCDMatrix_(astCheckFitsChan(this),STATUS_PTR)) #define astClearPolyTan(this) \ astINVOKE(V,astClearPolyTan_(astCheckFitsChan(this),STATUS_PTR)) #define astGetPolyTan(this) \ astINVOKE(V,astGetPolyTan_(astCheckFitsChan(this),STATUS_PTR)) #define astSetPolyTan(this,value) \ astINVOKE(V,astSetPolyTan_(astCheckFitsChan(this),value,STATUS_PTR)) #define astTestPolyTan(this) \ astINVOKE(V,astTestPolyTan_(astCheckFitsChan(this),STATUS_PTR)) #define astClearCarLin(this) \ astINVOKE(V,astClearCarLin_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCarLin(this) \ astINVOKE(V,astGetCarLin_(astCheckFitsChan(this),STATUS_PTR)) #define astSetCarLin(this,carln) \ astINVOKE(V,astSetCarLin_(astCheckFitsChan(this),carln,STATUS_PTR)) #define astTestCarLin(this) \ astINVOKE(V,astTestCarLin_(astCheckFitsChan(this),STATUS_PTR)) #define astClearClean(this) \ astINVOKE(V,astClearClean_(astCheckFitsChan(this),STATUS_PTR)) #define astGetClean(this) \ astINVOKE(V,astGetClean_(astCheckFitsChan(this),STATUS_PTR)) #define astSetClean(this,value) \ astINVOKE(V,astSetClean_(astCheckFitsChan(this),value,STATUS_PTR)) #define astTestClean(this) \ astINVOKE(V,astTestClean_(astCheckFitsChan(this),STATUS_PTR)) #define astClearFitsDigits(this) \ astINVOKE(V,astClearFitsDigits_(astCheckFitsChan(this),STATUS_PTR)) #define astGetFitsDigits(this) \ astINVOKE(V,astGetFitsDigits_(astCheckFitsChan(this),STATUS_PTR)) #define astSetFitsDigits(this,fitsdigits) \ astINVOKE(V,astSetFitsDigits_(astCheckFitsChan(this),fitsdigits,STATUS_PTR)) #define astTestFitsDigits(this) \ astINVOKE(V,astTestFitsDigits_(astCheckFitsChan(this),STATUS_PTR)) #define astClearFitsAxisOrder(this) \ astINVOKE(V,astClearFitsAxisOrder_(astCheckFitsChan(this),STATUS_PTR)) #define astGetFitsAxisOrder(this) \ astINVOKE(V,astGetFitsAxisOrder_(astCheckFitsChan(this),STATUS_PTR)) #define astSetFitsAxisOrder(this,fitsaxisorder) \ astINVOKE(V,astSetFitsAxisOrder_(astCheckFitsChan(this),fitsaxisorder,STATUS_PTR)) #define astTestFitsAxisOrder(this) \ astINVOKE(V,astTestFitsAxisOrder_(astCheckFitsChan(this),STATUS_PTR)) #define astClearWarnings(this) \ astINVOKE(V,astClearWarnings_(astCheckFitsChan(this),STATUS_PTR)) #define astGetWarnings(this) \ astINVOKE(V,astGetWarnings_(astCheckFitsChan(this),STATUS_PTR)) #define astSetWarnings(this,warnings) \ astINVOKE(V,astSetWarnings_(astCheckFitsChan(this),warnings,STATUS_PTR)) #define astTestWarnings(this) \ astINVOKE(V,astTestWarnings_(astCheckFitsChan(this),STATUS_PTR)) #define astGetAllWarnings(this) \ astINVOKE(V,astGetAllWarnings_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCardType(this) \ astINVOKE(V,astGetCardType_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCardName(this) \ astINVOKE(V,astGetCardName_(astCheckFitsChan(this),STATUS_PTR)) #define astGetCardComm(this) \ astINVOKE(V,astGetCardComm_(astCheckFitsChan(this),STATUS_PTR)) #define astGetNcard(this) \ astINVOKE(V,astGetNcard_(astCheckFitsChan(this),STATUS_PTR)) #define astGetNkey(this) \ astINVOKE(V,astGetNkey_(astCheckFitsChan(this),STATUS_PTR)) #define astClearEncoding(this) \ astINVOKE(V,astClearEncoding_(astCheckFitsChan(this),STATUS_PTR)) #define astGetEncoding(this) \ astINVOKE(V,astGetEncoding_(astCheckFitsChan(this),STATUS_PTR)) #define astSetEncoding(this,encoding) \ astINVOKE(V,astSetEncoding_(astCheckFitsChan(this),encoding,STATUS_PTR)) #define astTestEncoding(this) \ astINVOKE(V,astTestEncoding_(astCheckFitsChan(this),STATUS_PTR)) #define astClearIwc(this) \ astINVOKE(V,astClearIwc_(astCheckFitsChan(this),STATUS_PTR)) #define astGetIwc(this) \ astINVOKE(V,astGetIwc_(astCheckFitsChan(this),STATUS_PTR)) #define astSetIwc(this,iwc) \ astINVOKE(V,astSetIwc_(astCheckFitsChan(this),iwc,STATUS_PTR)) #define astTestIwc(this) \ astINVOKE(V,astTestIwc_(astCheckFitsChan(this),STATUS_PTR)) #endif #endif ast-8.3.0/box.c0000664000175000017500000052726313004147321010202 00000000000000/* *class++ * Name: * Box * Purpose: * A box region with sides parallel to the axes of a Frame. * Constructor Function: c astBox f AST_BOX * Description: * The Box class implements a Region which represents a box with sides * parallel to the axes of a Frame (i.e. an area which encloses a given * range of values on each axis). A Box is similar to an Interval, the * only real difference being that the Interval class allows some axis * limits to be unspecified. Note, a Box will only look like a box if * the Frame geometry is approximately flat. For instance, a Box centred * close to a pole in a SkyFrame will look more like a fan than a box * (the Polygon class can be used to create a box-like region close to a * pole). * Inheritance: * The Box class inherits from the Region class. * Attributes: * The Box class does not define any new attributes beyond * those which are applicable to all Regions. * Functions: c The Box class does not define any new functions beyond those f The Box class does not define any new routines beyond those * which are applicable to all Regions. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008-2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-MAR-2004 (DSB): * Original version. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 5-JUN-2007 (DSB): * Improve astSimplify algorithm. * 6-JUN-2007 (DSB): * Change the iterating algorithm in MakeGrid so that it uses * pixel index rather than axis value. This is more robust against * rounding errors. * 9-OCT-2007 (DSB): * - Fix bug in RegBaseMesh that could cause incorrect meshes for 2D * Boxes. * - In RegBaseMesh, use flat geometry if all axes come from simple * frames or from 1-dimensional specialist frames. * 26-MAY-2008 (DSB): * Fix bug in RegBaseMesh that caused an error to be reported if * the Box occupies a single point. * 20-JAN-2009 (DSB): * Over-ride astRegBasePick. * 26-JAN-2009 (DSB): * Over-ride astMapMerge. * 12-JUL-2009 (DSB): * Modify Simplify so that if a Box can be split into two * simpler components and then joined together into a Prism, it * does so. This is because being able to express a Region in * its current Frame is more important than having the simplest * possible structure. * 28-FEB-2011 (DSB): * Do not assume the first axis value is good in function BestBox. * 22-MAR-2011 (DSB): * Improve uniformity of points within grid produced by astRegBaseGrid. * 16-JUL-2013 (DSB): * Use a more robust algorithm for determining the order of the * vertices whan a Box is simplified to a Polygon. The old method * sometimes resulted in an unbounded "inside-out" polygon. * 4-NOV-2013 (DSB): * Modify RegPins so that it can handle uncertainty regions that straddle * a discontinuity. Previously, such uncertainty Regions could have a huge * bounding box resulting in matching region being far too big. * 10-APR-2014 (DSB): * More work (in function Cache() ) on handling uncertainty regions that straddle * a discontinuity. This time ensure that the extent of the box on each axis takes * account of the possibly cyclic nature of the base Frame. * 25-4-2016 (DSB): * Remove the unused box shrinking facility (a hang over from the * days when the RegBaseGrid function operated by creating multiple * meshes on the surface of the box, shrinking the box each time). *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 Box /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "cmpmap.h" /* Compound Mappings */ #include "cmpframe.h" /* Compound Frames */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "box.h" /* Interface definition for this class */ #include "polygon.h" /* Interface definition for this class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mappings */ #include "permmap.h" /* Axis permutation Mappings */ #include "interval.h" /* Axis interval regions */ #include "nullregion.h" /* Empty regions */ #include "pointlist.h" /* List of points in a Frame */ #include "prism.h" /* Extruded regions */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); static void (* parent_setnegated)( AstRegion *, int, int * ); static void (* parent_setclosed)( AstRegion *, int, int * ); static void (* parent_clearnegated)( AstRegion *, int * ); static void (* parent_clearclosed)( AstRegion *, int * ); static void (* parent_setunc)( AstRegion *, AstRegion *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (* parent_resetcache)( AstRegion *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Box) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Box,Class_Init) #define class_vtab astGLOBAL(Box,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstBoxVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstBox *astBoxId_( void *, int, const double[], const double[], void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstBox *BestBox( AstFrame *, AstPointSet *, AstRegion *, int * ); static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseGrid( AstRegion *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *MergeBox( AstBox *, AstRegion *, int, int * ); static AstRegion *RegBasePick( AstRegion *this, int, const int *, int * ); static double *GeoCorner( AstFrame *, int, double *, double *, double *, int * ); static double *GeoLengths( AstFrame *, int, double *, double *, double *, int * ); static double *RegCentre( AstRegion *this, double *, double **, int, int, int * ); static int GetObjSize( AstObject *, int * ); static int MakeGrid( int, double **, int, double *, double *, int *, int, int, double, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static int RegTrace( AstRegion *, int, double *, double **, int * ); static void BoxPoints( AstBox *, double *, double *, int *); static void Cache( AstBox *, int, int * ); static void ClearClosed( AstRegion *, int * ); static void ClearNegated( AstRegion *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void ResetCache( AstRegion *this, int * ); static void SetClosed( AstRegion *, int, int * ); static void SetNegated( AstRegion *, int, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); static void SetUnc( AstRegion *, AstRegion *, int * ); /* Member functions. */ /* ================= */ void BoxPoints( AstBox *this, double *centre, double *corner, int *status) { /* *+ * Name: * astBoxPoints * Purpose: * Return the defining points of a Box. * Type: * Protected function. * Synopsis: * #include "box.h" * astBoxPoints( AstBox *this, double *centre, double *corner ) * Class Membership: * Region virtual function. * Description: * This function returns the axis values at the points defining the * supplied Box. * Parameters: * this * Pointer to the Box. * centre * A pointer to an array in which to return the centre position of * the Box, in the base Frame of the encapsulated FrameSet. * corner * A pointer to an array in which to return the position of a corner * of the Box, in the base Frame of the encapsulated FrameSet. * Notes: * - It is assumed that the length of the supplied arrays is at least * equal to the number of axes in the base frame of the encapsulated * FrameSet. *- */ /* Local Variables: */ AstPointSet *pset; double **ptr; int nc; int i; /* Check the inherited status. */ if( !astOK ) return; /* Get a pointer to the PointSet holding the points defining the Box. */ pset = ((AstRegion *) this)->points; /* Get a pointer to the PointSet's data arrays. */ ptr = astGetPoints( pset ); /* See how many axes each point in the PointSet has. */ nc = astGetNcoord( pset ); /* Copy the centre and corner positions form the PointSet into the supplied arrays. */ for( i = 0; i < nc; i++ ) { centre[ i ] = ptr[ i ] [ 0 ]; corner[ i ] = ptr[ i ] [ 1 ]; } } static void ClearClosed( AstRegion *this, int *status ){ /* * Name: * ClearClosed * Purpose: * Clear the Closed attribute of a Region. * Type: * Private function. * Synopsis: * #include "box.h" * void ClearClosed( AstRegion *this, int *status ) * Class Membership: * Box member function (over-rides the protected astClearClosed * method inherited from the Region class). * Description: * This function clears the Closed attribute of the supplied Region. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int old; /* Check the global error status. */ if ( !astOK ) return; /* Get the original attribute value */ old = astGetClosed( this ); /* Invoke the clear method inherited from the parent Region class */ (*parent_clearclosed)( this, status ); /* If the new value is not the same as the old value, inidcatethat we need to re-calculate the cached information in the Box. */ if( astGetClosed( this ) != old ) astResetCache( this ); } static void ClearNegated( AstRegion *this, int *status ){ /* * Name: * ClearNegated * Purpose: * Clear the Negated attribute of a Region. * Type: * Private function. * Synopsis: * #include "box.h" * void ClearNegated( AstRegion *this, int *status ) * Class Membership: * Box member function (over-rides the protected astClearNegated * method inherited from the Region class). * Description: * This function clears the Negated attribute of the supplied Region. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int old; /* Check the global error status. */ if ( !astOK ) return; /* Get the original attribute value */ old = astGetNegated( this ); /* Invoke the clear method inherited from the parent Region class */ (*parent_clearnegated)( this, status ); /* If the new value is not the same as the old value, inidcatethat we need to re-calculate the cached information in the Box. */ if( astGetNegated( this ) != old ) astResetCache( this ); } static AstBox *BestBox( AstFrame *frm, AstPointSet *mesh, AstRegion *unc, int *status ){ /* * Name: * BestBox * Purpose: * Find the best fitting Box through a given mesh of points. * Type: * Private function. * Synopsis: * #include "box.h" * AstBox *BestBox( AstFrame *frm, AstPointSet *mesh, AstRegion *unc, int *status ) * Class Membership: * Box member function * Description: * This function finds the best fitting Box through a given mesh of points. * Parameters: * frm * Defines the geometry of the axes. * mesh * Pointer to a PointSet holding the mesh of points. They are * assumed to be in the Frame represented by "unc". * unc * A Region representing the uncertainty associated with each point * on the mesh. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the best fitting Region. It will inherit the positional * uncertainty and Frame represented by "unc". NULL is returned if all * the supplied positions are bad. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstBox *result; double **ptr; double *axval; double *blbnd; double *bubnd; double *lbnd; double *p; double *ubnd; double eps; double lb; double lim2; double lim; double liml; double limu; double mxl; double mxu; double org; double sxl2; double sxl; double sxu2; double sxu; double ub; double p0; double d; double dinc; int ic; int ip; int nc; int np; int nxl; int nxu; int ok; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get no. of points in the mesh, and the number of axis values per point. */ np = astGetNpoint( mesh ); nc = astGetNcoord( mesh ); /* Get pointers to the axis values. */ ptr = astGetPoints( mesh ); /* Allocate work space. */ lbnd = astMalloc( sizeof( double )*(size_t) nc ); ubnd = astMalloc( sizeof( double )*(size_t) nc ); blbnd = astMalloc( sizeof( double )*(size_t) nc ); bubnd = astMalloc( sizeof( double )*(size_t) nc ); axval = astMalloc( sizeof( double )*(size_t) np ); /* Check pointers can be used safely */ if( axval ) { /* Get the bounding box of the uncertainty region. */ astGetRegionBounds( unc, lbnd, ubnd ); /* We fit the box one axis at a time. */ ok = 1; for( ic = 0; ic < nc; ic++ ) { /* Find the first good value on this axis. */ for( ip = 0; ip < np; ip++ ) { org = ptr[ ic ][ ip ]; axval[ ip ] = org; if( org != AST__BAD ) break; } /* Abort if all the axis values werebad. */ if( ip >= np ) { ok = 0; break; } /* Find the upper and lower limits of the supplied mesh on this axis. */ lb = 0.0; ub = 0.0; ip++; p = ptr[ ic ] + ip; p0 = org; d = 0.0; for( ; ip < np; ip++, p++ ) { dinc = astAxDistance( frm, ic + 1, p0, *p ); if( dinc != AST__BAD ) { d += dinc; if( d < lb ) lb = d; if( d > ub ) ub = d; } axval[ ip ] = org + d; p0 = *p; } /* Now convert these relative offsets to actual axis values. */ lb += org; ub += org; /* Now scan the list of axis values again, looking for values which are "close to" either lower or upper bound. These will be the points which are on the faces of the box which are orthogonal to the current axis. Here "close to" means within 20 times the uncertainty associated with this axis, or one tenth of the box size (which ever is smaller). We find the mean and standard deviation of such "close" values, and then do a single sigma-clipping iteration (at 3-sigma) to get rid of any values which are on one of the other faces of the box. */ lim = 20*( ubnd[ ic ] - lbnd[ ic ] ); lim2 = 0.1*( ub - lb ); if( lim2 < lim ) lim = lim2; sxl = 0.0; sxl2 = 0.0; nxl = 0; sxu = 0.0; sxu2 = 0.0; nxu = 0; p = axval; for( ip = 0; ip < np; ip++, p++ ) { if( *p != AST__BAD ) { if( fabs( *p - lb ) <= lim ) { sxl += *p; sxl2 += (*p)*(*p); nxl++; } else if( fabs( *p - ub ) <= lim ) { sxu += *p; sxu2 += (*p)*(*p); nxu++; } } } if( nxl > 0 ) { mxl = sxl/nxl; liml = sxl2/nxl - mxl*mxl; eps = 100*mxl*DBL_EPSILON; if( liml < eps*eps ) { liml = eps; } else { liml = 3.0*sqrt( liml ); } } else { mxl = lb; liml = 0.0; } if( nxu > 0 ) { mxu = sxu/nxu; limu = sxu2/nxu - mxu*mxu; eps = 100*mxu*DBL_EPSILON; if( limu < eps*eps ) { limu = eps; } else { limu = 3.0*sqrt( limu ); } } else { mxu = ub; limu = 0.0; } sxl = 0.0; nxl = 0; sxu = 0.0; nxu = 0; p = axval; for( ip = 0; ip < np; ip++, p++ ) { if( *p != AST__BAD ) { if( fabs( *p - mxl ) <= liml ) { sxl += *p; nxl++; } else if( fabs( *p - mxu ) <= limu ) { sxu += *p; nxu++; } } } if( nxl > 0 ) { mxl = sxl/nxl; } else { mxl = lb; } if( nxu > 0 ) { mxu = sxu/nxu; } else { mxu = ub; } /* The resulting mean axis values are the bounds of the required box on the current axis.*/ blbnd[ ic ] = mxl; bubnd[ ic ] = mxu; } /* If possible, create the returned Box. */ if( ok ) result = astBox( unc, 1, blbnd, bubnd, unc, " ", status ); } /* Free resources */ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); blbnd = astFree( blbnd ); bubnd = astFree( bubnd ); axval = astFree( axval ); /* Return NULL if anything went wrong. */ if( !astOK ) result = astAnnul( result ); /* Return the result.*/ return result; } static void Cache( AstBox *this, int lohi, int *status ){ /* * Name: * Cache * Purpose: * Calculate intermediate values and cache them in the Box structure. * Type: * Private function. * Synopsis: * #include "box.h" * void Cache( AstRegion *this, int lohi, int *status ) * Class Membership: * Box member function * Description: * This function uses the PointSet stored in the parent Region to calculate * some intermediate values which are useful in other methods. These * values are stored within the Box structure. * Parameters: * this * Pointer to the Box. * lohi * Are the lo and hi arrays to be used? * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; AstPointSet *pset; AstRegion *unc; double **ptr; double *centre; double *extent; double *hi; double *lbnd_unc; double *geolen; double *lo; double *ubnd_unc; double wid; int i; int nc; /* Check the global error status. Also return if the currently cached information is usable. */ if ( !astOK || !this->stale ) return; /* Get the number of base Frame axes. */ nc = astGetNin( ((AstRegion *)this)->frameset ); /* Allocate memory to store the half-width of the box on each axis. */ extent = (double *) astMalloc( sizeof( double )*(size_t) nc ); /* Allocate memory to store the centre of the box on each axis. */ centre = (double *) astMalloc( sizeof( double )*(size_t) nc ); /* Allocate memory to store the high and low bounds. */ hi = (double *) astMalloc( sizeof( double )*(size_t) nc ); lo = (double *) astMalloc( sizeof( double )*(size_t) nc ); /* Memory to store the uncertainty bounding box */ lbnd_unc = astMalloc( sizeof( double)*(size_t) nc ); ubnd_unc = astMalloc( sizeof( double)*(size_t) nc ); /* Memory to store the geodesic half-dimensions of the box. */ geolen = astMalloc( sizeof( double)*(size_t) nc ); /* Get pointers to the coordinate data in the parent Region structure. */ pset = ((AstRegion *) this)->points; ptr = astGetPoints( pset ); /* Check pointers can be used safely. */ if( ptr ) { /* Store the centre and corner axis values. */ for( i = 0; i < nc; i++ ) { centre[ i ] = ptr[ i ][ 0 ]; hi[ i ] = ptr[ i ][ 1 ]; } /* Calculate the geodesic half-dimensions of the box. */ frm = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); GeoLengths( frm, nc, centre, hi, geolen, status ); /* Calculate the half-width and store in the above array. Also store the lower and upper bounds. */ for( i = 0; i < nc; i++ ) { extent[ i ] = fabs( astAxDistance( frm, i + 1, ptr[ i ][ 1 ], centre[ i ] ) ); lo[ i ] = centre[ i ] - extent[ i ]; hi[ i ] = centre[ i ] + extent[ i ]; } frm = astAnnul( frm ); /* Store the pointers to these arrays in the Box structure, and indicate the information is usable. */ if( astOK ) { astFree( this->extent ); astFree( this->centre ); astFree( this->lo ); astFree( this->hi ); astFree( this->geolen ); this->extent = extent; this->centre = centre; this->lo = lo; this->hi = hi; this->geolen = geolen; this->stale = 0; extent = NULL; centre = NULL; lo = NULL; hi = NULL; geolen = NULL; } /* If lo and hi values are to be used, ensure they are expanded to at least the width of an uncertainty box. */ if( lohi ) { /* If we are dealing with an unnegated closed Box or a negated open Box, ensure that the box does not have zero width on any axis. We do this by ensuring that the extent on all axes is at least half the width of the bounding box of the uncertainty Region. */ if( astGetNegated( this ) != astGetClosed( this ) ) { /* Get the bounding box of the uncertainty Region in the base Frame of the supplied Box. */ unc = astGetUncFrm( this, AST__BASE ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); /* Ensure the extents are at least half the width of the uncertainty bounding box. */ for ( i = 0; i < nc; i++ ) { wid = 0.5*( ubnd_unc[ i ] - lbnd_unc[ i ] ); if( this->extent[ i ] < wid ) { this->extent[ i ] = wid; this->lo[ i ] = this->centre[ i ] - wid; this->hi[ i ] = this->centre[ i ] + wid; } } /* Free resources. */ unc = astAnnul( unc ); } } } /* Annul the memory allocated above if an error occurred. */ if( !astOK ) { extent = astFree( extent ); centre = astFree( centre ); lo = astFree( lo ); hi = astFree( hi ); } /* Free other resources */ lbnd_unc = astFree( lbnd_unc ); ubnd_unc = astFree( ubnd_unc ); } static double *GeoCorner( AstFrame *frm, int nc, double *centre, double *geolen, double *corner, int *status ){ /* * Name: * GeoCorner * Purpose: * Find the corner position implied by the supplied centre position * and geodesic box dimensions. * Type: * Private function. * Synopsis: * #include "box.h" * double *GeoCorner( AstFrame *frm, int nc, double *centre, * double *geolen, double *corner, int *status ) * Class Membership: * Box member function * Description: * This function returns the corner position that is implied by the * supplied centre position and geodesic box dimensions. The returned * corner position is found by offsetting away from the supplied * centre position along each axis in turn, by the geodesic distance * specified in "geolen". * Parameters: * frm * Defines the geometry of the axes. * nc * The number of Frame axes. * centre * Pointer to an array holding the box centre axis values. * geolen * Pointer to an array holding the geodesic distance corresponding * to each half axis of the box. * corner * Pointer to an array in which to store the axis values at the * returned corner position. If this is NULL a new array is * allocated and a pointer to it returned as the function value. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the array holding the corner axis values. If a non-NULL * value is supplied for parameter "corner", then the same value will * be returned as the function value. Otherwise, the returned value * will be a pointer to a newly allocated array that should be freed * using astFree when no longer needed. */ /* Local Variables: */ double *p1; double *p2; double *p3; double *pt; double *result; double *work1; double *work2; double off; double off0; int i; /* Initialise */ result = corner; /* Check the global error status. */ if ( !astOK ) return result; /* Ensure we have a results array. */ if( ! result ) result = astMalloc( sizeof( double )*nc ); /* Also allocate two work arrays to hold a single position. */ work1 = astMalloc( sizeof( double )*nc ); work2 = astMalloc( sizeof( double )*nc ); /* Check the pointers can be used safely. */ if( astOK ) { /* Select which array to use as the initial results array so that the final results end up in the returned array. */ if( ( nc % 2 ) == 0 ) { p1 = result; p2 = work1; p3 = work2; } else { p1 = work2; p2 = work1; p3 = result; } /* Initialise the current corner position to be at the centre of the box. */ for( i = 0; i < nc; i++ ) p1[ i ] = centre[ i ]; /* Loop round offsetting along each side of the box. */ for( i = 0; i < nc; i++ ) { /* In the p2 array put the axis values at a point which is offset slightly along the current axis away from the current "corner" position (p1). */ memcpy( p2, p1, sizeof( double )*nc ); if( geolen[ i ] != 0.0 ) { off = 0.0001*fabs( geolen[ i ] ); } else { off = 1.0E-6; } off0 = fabs( 1.0E-10*centre[ i ] ); if( off < off0 ) off = off0; p2[ i ] += off; /* Offset away from the current corner position (p1) towards the position found above (p2), moving by the geodesic distance supplied for this axis. Put the resulting axis values in p3. */ astOffset( frm, p1, p2, geolen[ i ], p3 ); /* Swap the p3 and p1 arrays so that the offset position found above (p3) becomes the starting position (p1) for the next offset. */ pt = p1; p1 = p3; p3 = pt; } } /* Free resources */ work1 = astFree( work1 ); work2 = astFree( work2 ); /* Return the result */ return result; } static double *GeoLengths( AstFrame *frm, int nc, double *centre, double *corner, double *geolen, int *status ){ /* * Name: * GeoLengths * Purpose: * Find the geodesic dimensions of a box. * Type: * Private function. * Synopsis: * #include "box.h" * double *GeoLengths( AstFrame *frm, int nc, double *centre, * double *corner, double *geolen, int *status ) * Class Membership: * Box member function * Description: * This function returns half the geodesic distance along each edge of * the supplied box. * Parameters: * frm * Defines the geometry of the axes. * nc * The number of Frame axes. * centre * Pointer to an array holding rhe box centre axis values. * corner * Pointer to an array holding the axis values at the corner * position. * geolen * Pointer to an array in which to return the geodesic distances * corresponding to each half axis of the box. If this is NULL a * new array is allocated and a pointer to it returned as the * function value. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the array holding the geodesic half-dimensions of the box. * If a non-NULL value is supplied for parameter "corner", then the same * value will be returned as the function value. Otherwise, the * returned value will be a pointer to a newly allocated array that * should be freed using astFree when no longer needed. */ /* Local Variables: */ double *result; double *p1; double *p2; int i; /* Initialise */ result = geolen; /* Check the global error status. */ if ( !astOK ) return result; /* Ensure we have a results array. */ if( ! result ) result = astMalloc( sizeof( double )*nc ); /* Also allocate two work arrays to hold a single position. */ p1 = astMalloc( sizeof( double )*nc ); p2 = astMalloc( sizeof( double )*nc ); /* Check the pointers can be used safely. */ if( astOK ) { /* Initialise the coords as the start and end of the line. */ memcpy( p1, centre, sizeof( double )*nc ); memcpy( p2, centre, sizeof( double )*nc ); /* Loop round finding the geodesic half-length of each side of the box. */ for( i = 0; i < nc; i++ ) { /* The end of the line is the same as the start of the line, except that it has the corner value for the current axis. */ p2[ i ] = corner[ i ]; /* Find and return the geodesic distance along the line (i.e. from p1 to p2). */ result[ i ] = astDistance( frm, p1, p2 ); /* The start of the next line wil lbe at the end of the current line. */ p1[ i ] = corner[ i ]; } } /* Free resources */ p1 = astFree( p1 ); p2 = astFree( p2 ); /* Return the result */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "box.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Box member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Box, * in bytes. * Parameters: * this * Pointer to the Box. * 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: */ AstBox *this; /* Pointer to Box structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Box structure. */ this = (AstBox *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->extent ); result += astTSizeOf( this->centre ); result += astTSizeOf( this->lo ); result += astTSizeOf( this->hi ); result += astTSizeOf( this->geolen ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitBoxVtab_( AstBoxVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitBoxVtab * Purpose: * Initialise a virtual function table for a Box. * Type: * Protected function. * Synopsis: * #include "box.h" * void astInitBoxVtab( AstBoxVtab *vtab, const char *name ) * Class Membership: * Box vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Box 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsABox) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->BoxPoints = BoxPoints; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_setnegated = region->SetNegated; region->SetNegated = SetNegated; parent_setunc = region->SetUnc; region->SetUnc = SetUnc; parent_setclosed = region->SetClosed; region->SetClosed = SetClosed; parent_clearnegated = region->ClearNegated; region->ClearNegated = ClearNegated; parent_clearclosed = region->ClearClosed; region->ClearClosed = ClearClosed; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_resetcache = region->ResetCache; region->ResetCache = ResetCache; mapping->MapMerge = MapMerge; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ region->RegBaseGrid = RegBaseGrid; region->RegBaseMesh = RegBaseMesh; region->RegBasePick = RegBasePick; region->RegBaseBox = RegBaseBox; region->RegPins = RegPins; region->RegTrace = RegTrace; region->RegCentre = RegCentre; /* Declare the copy constructor, destructor and class dump functions. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Box", "Axis intervals" ); /* 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 int MakeGrid( int naxes, double **ptr, int ip, double *lbnd, double *ubnd, int *np_axes, int np_axis, int iaxis, double axval, int *status ){ /* * Name: * MakeGrid * Purpose: * Create a grid covering the entire volume of a specified box. * Type: * Private function. * Synopsis: * #include "box.h" * int MakeGrid( int naxes, double **ptr, int ip, double *lbnd, * double *ubnd, int *np_axes, int np_axis, int iaxis, * double axval, int *status ) * Class Membership: * Box member function * Description: * This function creates an evenly sampled grid covering a given * volume of n-D space, putting the coordinates at the sample points * into a supplied array and returning the number of samples added. * Optionally, the volume can be assumed to have a constant value on * a specified axis. * Parameters: * naxes * The number of axes. * ptr * Pointer to an array with "naxes" elements. Each element is a * pointer to an array in which to store the values for the axis. * ip * The index of the first point to be added to the "ptr" arrays. * lbnd * Pointer to an array containing the lower axis bounds of the * volume to be sampled. * ubnd * Pointer to an array containing the upper axis bounds of the * volume to be sampled. * np_axes * Pointer to an array with one element for every axis, giving the * number of samples along each axis (except, optionally, the axis * specified by "iaxis"). The first sample (sample 0) for each axis * will be at the lower bound given in "lbnd" and the last sample * (sample "np_axes[iax]-1") will be at the upper bound given in * "ubnd". If NULL, then the single scalar avalue given by * "np_axis" is used for all axes. * np_axis * The constant number of samples along every axis (except, optionally, * the axis specified by "iaxis"). The first sample (sample 0) for each * axis will be at the lower bound given in "lbnd" and the last sample * (sample "np_axis-1") will be at the upper bound given in "ubnd". * The supplied value is only used if "np_axes" is NULL. * iaxis * The index of an axis which has constant value in the volume, or * -1 if all axes are to span the full volume given by lbnd/ubnd. * The values in "lbnd" and "ubnd" are ignored for this axis and all * sample positions will have the axis value given by "axval". * axval * The constant value for the axis with index "iaxis". Ignored if * "iaxis" is -1. * status * Pointer to the inherited status variable. * Returned Value: * The number of points added to the "ptr" arrays. */ /* Local Variables: */ double *step; /* Pointer to array holding axis step sizes */ int *maxi; /* Pointer to array of maximum index values */ int *pi; /* Pointer to array holding current sample indices */ int i; /* Axis index */ int ipp; /* Index of next point */ int nsamp; /* Number of samples along the axis */ /* Check the global error status. */ if ( !astOK ) return 0; /* Allocate memory to hold the max indices on each axis. */ maxi = astMalloc( sizeof( int )*(size_t) naxes ); /* Allocate memory to hold the indices of the current position.*/ pi = astMalloc( sizeof( int )*(size_t) naxes ); /* Allocate memory to hold the step size for each axis. */ step = astMalloc( sizeof( double )*(size_t) naxes ); if( astOK ) { /* For every axis, set up the step size, initialise the current position to the lower bound, and store a modified upper limit which includes some safety marging to allow for rounding errors. */ for( i = 0; i < naxes; i++ ) { nsamp = np_axes ? np_axes[ i ] : np_axis; step[ i ] = ( ubnd[ i ] - lbnd[ i ] )/( nsamp - 1 ); pi[ i ] = 0; maxi[ i ] = nsamp - 1; } if( iaxis >= 0 ) { maxi[ iaxis ] = 0; step[ iaxis ] = 0.0; pi[ iaxis ] = 0; } /* Initialise the index of the next position to store. */ ipp = ip; /* Loop round adding points to the array until the whole volume has been done. */ i = 0; while( i < naxes ) { /* Add the current point to the supplied array,and increment the index of the next point to add. */ for( i = 0; i < naxes; i++ ) { if( i == iaxis ) { ptr[ i ][ ipp ] = axval; } else { ptr[ i ][ ipp ] = lbnd[ i ] + pi[ i ]*step[ i ]; } } ipp++; /* We now move the current position on to the next sample */ i = 0; while( i < naxes ) { pi[ i ]++; if( pi[ i ] > maxi[ i ] ) { pi[ i ] = 0; i++; } else { break; } } } } else { ipp = ip; } /* Free resources. */ maxi = astFree( maxi ); pi = astFree( pi ); step = astFree( step ); /* Return the result. */ return astOK ? ( ipp - ip ): 0 ; } static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a Box. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * Box method (over-rides the protected astMapMerge method * inherited from the Region class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated Box in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated Box with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated Box which is to be merged with * its neighbours. This should be a cloned copy of the Box * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * Box it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated Box resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstBox *oldbox; /* Pointer to supplied Box */ AstMapping *map; /* Pointer to adjacent Mapping */ AstMapping *new; /* Simplified or merged Region */ int i1; /* Index of first Mapping merged */ int i; /* Loop counter */ int result; /* Result value to return */ /* Initialise. */ result = -1; i1 = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Box. */ oldbox = (AstBox *) this; /* First of all, see if the Box can be replaced by a simpler Region, without reference to the neighbouring Regions in the list. */ /* =====================================================================*/ /* Try to simplify the box. If the pointer value has changed, we assume some simplification took place. */ new = astSimplify( oldbox ); if( new != (AstMapping *) oldbox ) { /* Annul the Box pointer in the list and replace it with the new Region pointer, and indicate that the forward transformation of the returned Region should be used (not really needed but keeps things clean). */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the Box itself could not be simplified, see if it can be merged with the Regions on either side of it in the list. We can only merge in parallel. */ /* =====================================================================*/ } else if( ! series ){ new = astAnnul( new ); /* Attempt to merge the Box with its lower neighbour (if any). */ if( where > 0 ) { i1 = where - 1; map = ( *map_list )[ where - 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeBox( oldbox, (AstRegion *) map, 0, status ); } } /* If this did not produced a merged Region, attempt to merge the Box with its upper neighbour (if any). */ if( !new && where < *nmap - 1 ) { i1 = where; map = ( *map_list )[ where + 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeBox( oldbox, (AstRegion *) map, 1, status ); } } /* If succesfull... */ if( new ){ /* Annul the first of the two Mappings, and replace it with the merged Region. Also clear the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = new; ( *invert_list )[ i1 ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i1 + 1 ] ); for ( i = i1 + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } } else { new = astAnnul( new ); } /* Return the result. */ return result; } static AstRegion *MergeBox( AstBox *this, AstRegion *reg, int boxfirst, int *status ) { /* * Name: * MergeBox * Purpose: * Attempt to merge a Box with another Region to form a Region of higher * dimensionality. * Type: * Private function. * Synopsis: * #include "box.h" * AstRegion *MergeBox( AstBox *this, AstRegion *reg, int boxfirst, int *status ) * Class Membership: * Box member function. * Description: * This function attempts to combine the supplied Regions together * into a Region of higher dimensionality. * Parameters: * this * Pointer to a Box. * reg * Pointer to another Region. * boxfirst * If non-zero, then the Box axes are put first in the new Region. * Otherwise, the other Region's axes are put first. * status * Pointer to the inherited status value. * Returned Value: * A pointer to a new region, or NULL if the supplied Regions could * not be merged. */ /* Local Variables: */ AstFrame *bfrm; /* Pointer to base Frame for "result" */ AstFrame *cfrm; /* Pointer to current Frame for "result" */ AstFrame *frm_reg; /* Pointer to Frame from "reg" */ AstFrame *frm_this; /* Pointer to Frame from "this" */ AstMapping *bcmap; /* Base->current Mapping for "result" */ AstMapping *map_reg; /* Base->current Mapping from "reg" */ AstMapping *map_this; /* Base->current Mapping from "this" */ AstMapping *sbunc; /* Simplified uncertainty */ AstPointSet *pset_new; /* PointSet holding PointList axis values for new */ AstPointSet *pset_reg; /* PointSet holding PointList axis values for reg */ AstRegion *bunc; /* Base Frame uncertainty Region */ AstRegion *new; /* Pointer to new Interval in base Frame */ AstRegion *result; /* Pointer to returned Interval in current Frame */ AstRegion *unc_reg; /* Current Frame uncertainty Region from "reg" */ AstRegion *unc_this; /* Current Frame uncertainty Region from "this" */ double **ptr_new; /* Pointers to arrays holding new axis values */ double **ptr_reg; /* Pointers to arrays holding reg axis values */ double *centre; /* Array to hold box centre axis values */ double *corner; /* Array to hold box corner axis values */ double *lbnd; /* Array to hold lower axis bounds */ double *p; /* Pointer to next input value */ double *q; /* Pointer to next output value */ double *ubnd; /* Array to hold upper axis bounds */ double fac_reg; /* Ratio of used to default MeshSize for "reg" */ double fac_this; /* Ratio of used to default MeshSize for "this" */ double temp; /* Temporary storage */ int i; /* Loop count */ int j; /* Loop count */ int msz_reg; /* Original MeshSize for "reg" */ int msz_reg_set; /* Was MeshSize originally set for "reg"? */ int msz_this; /* Original MeshSize for "this" */ int msz_this_set; /* Was MeshSize originally set for "this"? */ int nax; /* Number of axes in "result" */ int nax_reg; /* Number of axes in "reg" */ int nax_this; /* Number of axes in "this" */ int neg_reg; /* Negated attribute value for other supplied Region */ int neg_this; /* Negated attribute value for supplied Box */ int npnt; /* Number of points in PointList */ int ok; /* Can supplied Regions be merged? */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get the Closed attributes of the two Regions. They must be the same in each Region if we are to merge the Regions. In addition, in order to merge, either both Regions must have a defined uncertainty, or neither Region must have a defined Uncertainty. */ if( astGetClosed( this ) == astGetClosed( reg ) && astTestUnc( this ) == astTestUnc( reg ) ) { /* Get the Nagated attributes of the two Regions. */ neg_this = astGetNegated( this ); neg_reg = astGetNegated( reg ); /* Get the number of axes in the two supplied Regions. */ nax_reg = astGetNaxes( reg ); nax_this = astGetNaxes( this ); /* If the Regions can be combined, get the number of axes the combination will have. */ nax = nax_reg + nax_this; /* Get the base Frames from the two Region FrameSets, and combine them into a single CmpFrame that will be used to create any new Region. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); frm_reg = astGetFrame( reg->frameset, AST__BASE ); if( boxfirst ) { bfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { bfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); /* Indicate we do not yet have a merged Region. */ new = NULL; /* First attempt to merge with another Box. The result will be a Box. Both Boxes must be un-negated. */ if( astIsABox( reg ) && !neg_this && !neg_reg ) { /* Allocate memory to store the centre and corner of the returned Box. */ centre = astMalloc( sizeof( double )*(size_t) nax ); corner = astMalloc( sizeof( double )*(size_t) nax ); /* Copy the centres and corners from the supplied Boxes into the above arrays, in the requested order. */ if( boxfirst ) { astBoxPoints( this, centre, corner ); astBoxPoints( reg, centre + nax_this, corner + nax_this ); } else { astBoxPoints( reg, centre, corner ); astBoxPoints( this, centre + nax_reg, corner + nax_reg ); } /* Create the new Box, initially with no uncertainty. */ new = (AstRegion *) astBox( bfrm, 0, centre, corner, NULL, "", status ); /* Free resources .*/ centre = astFree( centre ); corner = astFree( corner ); /* Now attempt to merge with an Interval. The result will be an Interval. Both Intervals must be un-negated. */ } else if( astIsAInterval( reg ) && !neg_this && !neg_reg ) { /* Allocate memory to store the bounds of the returned Interval. */ lbnd = astMalloc( sizeof( double )*(size_t) nax ); ubnd = astMalloc( sizeof( double )*(size_t) nax ); /* Copy the centre and corner from the supplied Box into the required part of the above arrays. */ if( boxfirst ) { centre = lbnd; corner = ubnd; } else { centre = lbnd + nax_reg; corner = ubnd + nax_reg; } astBoxPoints( this, centre, corner ); /* Convert these centre and corner positions into upper and lower bounds. */ if( astOK ) { for( i = 0; i < nax_this; i++ ) { centre[ i ] = 2*centre[ i ] - corner[ i ]; if( centre[ i ] > corner[ i ] ) { temp = centre[ i ]; centre[ i ] = corner[ i ]; corner[ i ] = temp; } } } /* Get the bounds from the interval and add them into the above arrays. */ if( boxfirst ) { astIntervalPoints( reg, lbnd + nax_this, ubnd + nax_this ); } else { astIntervalPoints( reg, lbnd, ubnd ); } /* Create the new Interval, initially with no uncertainty. */ new = (AstRegion *) astInterval( bfrm, lbnd, ubnd, NULL, "", status ); /* Free resources .*/ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Now attempt to merge with a NullRegion. The result will be an Interval. The NullRegion must be negated and the Box must not. */ } else if( astIsANullRegion( reg ) && !neg_this && neg_reg ) { /* Allocate memory to store the bounds of the returned Interval. */ lbnd = astMalloc( sizeof( double )*(size_t) nax ); ubnd = astMalloc( sizeof( double )*(size_t) nax ); /* Copy the centre and corner from the supplied Box into the required part of the above arrays. */ if( boxfirst ) { centre = lbnd; corner = ubnd; } else { centre = lbnd + nax_reg; corner = ubnd + nax_reg; } astBoxPoints( this, centre, corner ); /* Convert these centre and corner positions into upper and lower bounds. */ if( astOK ) { for( i = 0; i < nax_this; i++ ) { centre[ i ] = 2*centre[ i ] - corner[ i ]; if( centre[ i ] > corner[ i ] ) { temp = centre[ i ]; centre[ i ] = corner[ i ]; corner[ i ] = temp; } } /* Fill the other axes with bad values to indicate they are unbounded. */ if( boxfirst ) { for( i = nax_this; i < nax; i++ ) { lbnd[ i ] = AST__BAD; ubnd[ i ] = AST__BAD; } } else { for( i = 0; i < nax_reg; i++ ) { lbnd[ i ] = AST__BAD; ubnd[ i ] = AST__BAD; } } /* Create the new Interval, initially with no uncertainty. */ new = (AstRegion *) astInterval( bfrm, lbnd, ubnd, NULL, "", status ); } /* Free resources .*/ lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* Now attempt to merge with a PointList. The result will be a PointList. Both Regions must be un-negated. */ } else if( astIsAPointList( reg ) && !neg_this && !neg_reg ) { /* We can only do this if the Box has zero width on each axis (i.e. represents a point). Get the Box centre and corner. */ centre = astMalloc( sizeof( double )*(size_t) nax_this ); corner = astMalloc( sizeof( double )*(size_t) nax_this ); astBoxPoints( this, centre, corner ); /* Get the size of the Box's uncertainty region. */ lbnd = astMalloc( sizeof( double )*(size_t) nax_this ); ubnd = astMalloc( sizeof( double )*(size_t) nax_this ); bunc = astGetUncFrm( this, AST__BASE ); astGetRegionBounds( bunc, lbnd, ubnd ); /* Set "ok" to zero if the Box does not have zero width on any axis. Here "zero width" means a width less than half the uncertainty on the axis. */ if( astOK ) { ok = 1; for( i = 0; i < nax_this; i++ ) { if( fabs( centre[ i ] - corner[ i ] ) > 0.25*fabs( ubnd[ i ] - lbnd[ i ] ) ) { ok = 0; break; } } /* If the Box is a point, we go on to create a new PointList. */ if( ok ) { /* Get a PointSet holding the axis values in the supplied PointList data. Also get the number of points in the PointSet and pointers to the arrays holding the axis values. */ astPointListPoints( reg, &pset_reg ); npnt = astGetNpoint( pset_reg ); ptr_reg = astGetPoints( pset_reg ); /* Create a new PointSet with room for the same number of points, but with the extra required axes. Get pointers to its axis arrays. */ pset_new = astPointSet( npnt, nax, "", status ); ptr_new = astGetPoints( pset_new ); /* Copy the PointList axis values into the new PointSet, and then include the extra axis values defined by the Box to each point. */ if( astOK ) { for( j = 0; j < nax_reg; j++ ) { p = ptr_reg[ j ]; q = ptr_new[ boxfirst ? nax_this + j : j ]; for( i = 0; i < npnt; i++ ) *(q++) = *(p++); } for( j = 0; j < nax_this; j++ ) { p = centre + j; q = ptr_new[ boxfirst ? j : nax_reg + j ]; for( i = 0; i < npnt; i++ ) *(q++) = *p; } /* Create the new PointList, initially with no uncertainty. */ new = (AstRegion *) astPointList( bfrm, pset_new, NULL, "", status ); } /* Free resources .*/ pset_new = astAnnul( pset_new ); pset_reg = astAnnul( pset_reg ); } } centre = astFree( centre ); corner = astFree( corner ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); bunc = astAnnul( bunc ); } /* If a new Region was created above, propagate remaining attributes of the supplied Region to it. */ if( new ) { astRegOverlay( new, this, 1 ); /* The above Prism constructors create the Prism with the correct value for the Nagated attribute (i.e. zero). Ensure the above call to astRegOverlay has not changed this. */ astClearNegated( new ); /* If both the supplied Regions have uncertainty, assign the new Region an uncertainty. */ if( astTestUnc( this ) && astTestUnc( reg ) ) { /* Get the uncertainties from the two supplied Regions. */ unc_this = astGetUncFrm( this, AST__BASE ); unc_reg = astGetUncFrm( reg, AST__BASE ); /* Combine them into a single Region (a Prism), in the correct order. */ if( boxfirst ) { bunc = (AstRegion *) astPrism( unc_this, unc_reg, "", status ); } else { bunc = (AstRegion *) astPrism( unc_reg, unc_this, "", status ); } /* Attempt to simplify the Prism. */ sbunc = astSimplify( bunc ); /* Use the simplified Prism as the uncertainty for the returned Region. */ astSetUnc( new, sbunc ); /* Free resources. */ sbunc = astAnnul( sbunc ); bunc = astAnnul( bunc ); unc_reg = astAnnul( unc_reg ); unc_this = astAnnul( unc_this ); } /* Get the current Frames from the two Region FrameSets, and combine them into a single CmpFrame. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__CURRENT ); frm_reg = astGetFrame( reg->frameset, AST__CURRENT ); if( boxfirst ) { cfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { cfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } /* Get the base -> current Mappings from the two Region FrameSets, and combine them into a single parallel CmpMap that connects bfrm and cfrm. */ map_this = astGetMapping( ((AstRegion *) this)->frameset, AST__BASE, AST__CURRENT ); map_reg = astGetMapping( reg->frameset, AST__BASE, AST__CURRENT ); if( boxfirst ) { bcmap = (AstMapping *) astCmpMap( map_this, map_reg, 0, "", status ); } else { bcmap = (AstMapping *) astCmpMap( map_reg, map_this, 0, "", status ); } /* Map the new Region into the new current Frame. */ result = astMapRegion( new, bcmap, cfrm ); /* The filling factor in the returned is the product of the filling factors for the two supplied Regions. */ if( astTestFillFactor( reg ) || astTestFillFactor( this ) ) { astSetFillFactor( result, astGetFillFactor( reg )* astGetFillFactor( this ) ); } /* If the MeshSize value is set in either supplied Region, set a value for the returned Region which scales the default value by the product of the scaling factors for the two supplied Regions. First see if either MeshSize value is set. */ msz_this_set = astTestMeshSize( this ); msz_reg_set = astTestMeshSize( reg ); if( msz_this_set || msz_reg_set ) { /* If so, get the two MeshSize values (one of which may be a default value), and then clear them so that the default value will be returned in future. */ msz_this = astGetMeshSize( this ); msz_reg = astGetMeshSize( reg ); astClearMeshSize( this ); astClearMeshSize( reg ); /* Get the ratio of the used MeshSize to the default MeshSize for both Regions. */ fac_this = (double)msz_this/(double)astGetMeshSize( this ); fac_reg = (double)msz_reg/(double)astGetMeshSize( reg ); /* The MeshSize of the returned Returned is the default value scaled by the product of the two ratios found above. */ astSetMeshSize( result, fac_this*fac_reg*astGetMeshSize( result ) ); /* Re-instate the original MeshSize values for the supplied Regions (if set) */ if( msz_this_set ) astSetMeshSize( this, msz_this ); if( msz_reg_set ) astSetMeshSize( reg, msz_reg ); } /* Free remaining resources */ frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); map_this = astAnnul( map_this ); map_reg = astAnnul( map_reg ); bcmap = astAnnul( bcmap ); new = astAnnul( new ); cfrm = astAnnul( cfrm ); } bfrm = astAnnul( bfrm ); } /* If an error has occurred, annul the returned pointer. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "box.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Box member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstBox *this; /* Pointer to Box structure */ double axcen; /* Central axis value */ double axlen; /* Half width of box on axis */ int i; /* Axis index */ int nc; /* No. of axes in base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Box structure */ this = (AstBox *) this_region; /* Ensure cached information is up to date. */ Cache( this, 0, status ); /* Get the number of base Frame axes in the Region. */ nc = astGetNin( this_region->frameset ); /* The first point is the centre of the box, the second point is the half size of the box on each axis.*/ for( i = 0; i < nc; i++ ) { axcen = this->centre[ i ]; axlen = this->extent[ i ]; lbnd[ i ] = axcen - axlen; ubnd[ i ] = axcen + axlen; } } static AstPointSet *RegBaseGrid( AstRegion *this, int *status ){ /* * Name: * RegBaseGrid * Purpose: * Return a PointSet containing points spread through the volume of a * Region. * Type: * Private function. * Synopsis: * #include "box.h" * AstPointSet *RegBaseGrid( AstRegion *this, int *status ) * Class Membership: * Box member function (over-rides the astRegBaseGrid protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a set of points spread * through the volume of the supplied Box. The points refer to the base * Frame of the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. If the Region is unbounded, a NULL pointer * will be returned. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *frm; /* Base Frame in encapsulated FrameSet */ AstPointSet *result; /* Returned pointer */ double *lbnd; /* Pointer to array of lower bounds of box */ double *ubnd; /* Pointer to array of upper bounds of box */ int meshsize; /* Requested size of grid */ int naxes; /* No. of axes in base Frame */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return NULL; /* If the Region structure contains a pointer to a PointSet holding a previously created grid, return it. */ if( this->basegrid ) { result = astClone( this->basegrid ); /* Otherwise, create a new one, but only if the Box is bounded. */ } else if( astGetBounded( this ) ) { /* Get the base Frame in the Region's FrameSet. */ frm = astGetFrame( this->frameset, AST__BASE ); /* Get the number of axes in the base Frame */ naxes = astGetNaxes( frm ); /* Get the bounds of the Region in the base Frame. */ lbnd = astMalloc( sizeof( double )*(size_t) naxes ); ubnd = astMalloc( sizeof( double )*(size_t) naxes ); astRegBaseBox( this, lbnd, ubnd ); /* Get the number of points which would be used to create a boundary mesh. We use the same number to determine the number of points in the grid. */ meshsize = astGetMeshSize( this ); /* Create the PointSet holding the grid. */ result = astFrameGrid( frm, meshsize, lbnd, ubnd ); /* Save the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this->basegrid = astClone( result ); /* Free remaining resources. */ frm = astAnnul( frm ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); } /* Annul the result if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result */ return result; } static AstPointSet *RegBaseMesh( AstRegion *this, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "box.h" * AstPointSet *RegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Box member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. The axis values in this PointSet will have * associated accuracies derived from the accuracies which were * supplied when the Region was created. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Constants: */ #define NP_EDGE 50 /* No. of points for determining geodesic length of each axis. */ /* Local Variables: */ AstFrame *frm; /* Base Frame in encapsulated FrameSet */ AstFrame *pfrm0; /* Primary Frame defining axis 0 */ AstFrame *pfrm1; /* Primary Frame defining axis 1 */ AstPointSet *result; /* Returned pointer */ const char *class0; /* Pointer to class string from pfrm0 */ const char *class1; /* Pointer to class string from pfrm1 */ double **ptr; /* Pointers to data */ double *ax; /* Pointer to next first axis value */ double *ay; /* Pointer to next second axis value */ double *lbnd; /* Pointer to array of lower bounds of box */ double *ubnd; /* Pointer to array of lower bounds of box */ double c[ 5 ][ 2 ]; /* Positions of corners for 2D boxes */ double dx; /* Increment along first axis of 2D box */ double dy; /* Increment along second axis of 2D box */ double edge_len[ 4 ]; /* Length of each edge of 2D boundary */ double lax; /* Previous value on first axis */ double lay; /* Previous value on second axis */ double len; /* Length of edge of 2D boundary */ double p0[ 2 ]; /* Position in 2D Frame */ double p1[ 2 ]; /* Position in 2D Frame */ double ppd; /* Points per unit distance */ double total_len; /* Total length of 2D boundary */ int flat; /* Assume Frame geometry is flat? */ int i; /* Point index */ int iaxis; /* Axis index */ int iedge; /* Edge index */ int ip; /* Index of next point */ int metric; /* Does Frame have a usable metric? */ int nax0; /* No. of axes in first primary Frame */ int nax1; /* No. of axes in second primary Frame */ int naxes; /* No. of axes in base Frame */ int np; /* No. of points in returned PointSet */ int np0; /* No. of points per edge */ int np_axis; /* No. of points per axis in ND box */ int np_edge[ 4 ]; /* No. of points per edge in 2D box */ int paxis; /* Axis index in primary Frame */ int single; /* Does the Box occupy a single point? */ /* Initialise */ result= NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this->basemesh ) { result = astClone( this->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Get the base Frame in the Region's FrameSet. */ frm = astGetFrame( this->frameset, AST__BASE ); /* Get the number of axes in the base Frame */ naxes = astGetNaxes( frm ); /* Get the bounds of the Region in the base Frame. */ lbnd = astMalloc( sizeof( double )*(size_t) naxes ); ubnd = astMalloc( sizeof( double )*(size_t) naxes ); astRegBaseBox( this, lbnd, ubnd ); /* Get the requested number of points to put on the mesh. */ np = astGetMeshSize( this ); /* See if the box occupies a single point. */ single = 1; for( i = 0; i < naxes; i++ ) { if( ubnd[ i ] > lbnd[ i ] ) { single = 0; break; } } /* If so, we return a PointSet holding a single point. */ if( single ) { result = astPointSet( 1, naxes, "", status ); ptr = astGetPoints( result ); if( astOK ) { for( i = 0; i < naxes; i++ ) { ptr[ i ][ 0 ] = 0.5*( lbnd[ 0 ] + ubnd[ 0 ] ); } } /* Otherwise, first deal with 1-D boxes. */ } else if( naxes == 1 ) { /* The boundary of a 1-D box consists of 2 points - the two extreme values. Create a PointSet to hold 2 1-D values, and store the extreme values. */ result = astPointSet( 2, 1, "", status ); ptr = astGetPoints( result ); if( astOK ) { ptr[ 0 ][ 0 ] = lbnd[ 0 ]; ptr[ 0 ][ 1 ] = ubnd[ 0 ]; } /* Now deal with 2-D boxes. */ } else if( naxes == 2 ){ /* Store the coords of each corner for easy access. */ c[ 0 ][ 0 ] = lbnd[ 0 ]; c[ 0 ][ 1 ] = lbnd[ 1 ]; c[ 1 ][ 0 ] = lbnd[ 0 ]; c[ 1 ][ 1 ] = ubnd[ 1 ]; c[ 2 ][ 0 ] = ubnd[ 0 ]; c[ 2 ][ 1 ] = ubnd[ 1 ]; c[ 3 ][ 0 ] = ubnd[ 0 ]; c[ 3 ][ 1 ] = lbnd[ 1 ]; c[ 4 ][ 0 ] = lbnd[ 0 ]; c[ 4 ][ 1 ] = lbnd[ 1 ]; /* See if we can assume that the frame has flat geometry. This is the case if both axes belong to simple Frames, or are 1D, but may not be the case if either axis does not belong to a simple Frame that has more than 1 axis. */ astPrimaryFrame( frm, 0, &pfrm0, &paxis ); astPrimaryFrame( frm, 1, &pfrm1, &paxis ); class0 = astGetClass( pfrm0 ); class1 = astGetClass( pfrm1 ); nax0 = astGetNaxes( pfrm0 ); nax1 = astGetNaxes( pfrm1 ); if( astOK ) { flat = ( !strcmp( class0, "Frame" ) || nax0 == 1 ) && ( !strcmp( class1, "Frame" ) || nax1 == 1 ); } else { flat = 0; } /* Our choice of distribution of points depends on whether the axes have the same units or not. If the axes have the same units, or if they share the same primary Frame, then we assume that the axes span some space in which a single "distance" is defined. If not, (e.g. for a Frame representing frequency in Hz on one axis - typical value 1.0E10, and slit position in metres on the other axis - typical value 1.0E-2) we assume that "distance" is defined differently for each axis. The primary frame requirement is because some classes of Frame (e.g. SkyFrame) have a defined distance, even though the Units attributes for its axes may differ (since Units refers to the external representation - e.g. hours and degrees for a SkyFrame - rather than the internal representation). */ if( astOK && !strcmp( astGetUnit( frm, 0 ), astGetUnit( frm, 1 ) ) ) { metric = 1; } else { metric = ( pfrm0 == pfrm1 ); } /* If we have a usable metric, distribute the points according to the aspect ratio of the box (i.e. the shorter box sides gets fewer points). */ if( metric ){ /* Find the approximate geodesic length of each edge of the box. Since the edges of the box may not correspond to single geodesic (e.g. a line of constant latitude is not a geodesic), we do this by testing a set of points along each edge of the box and finding the total of the geodesic distances between each pair of adjacent points. Initialise the total length round all edges. */ total_len = 0.0; /* Do each edge in turn.*/ for( iedge = 0; iedge < 4; iedge++ ) { /* Find the increment in x and y between adjacent points along this edge. We put a point at each end of the edge. Note, one of dx or dy will be zero since the edges are parallel to the axes. */ dx = ( c[ iedge + 1 ][ 0 ] - c[ iedge ][ 0 ] )/( NP_EDGE - 1 ); dy = ( c[ iedge + 1 ][ 1 ] - c[ iedge ][ 1 ] )/( NP_EDGE - 1 ); /* Store the coords of the first point. */ p0[ 0 ] = c[ iedge ][ 0 ]; p0[ 1 ] = c[ iedge ][ 1 ]; /* Initialise the length of this edge and loop round the remaining points. */ len = 0.0; for( i = 1; i < NP_EDGE; i++ ) { /* Save the position of the previous point. */ p1[ 0 ] = p0[ 0 ]; p1[ 1 ] = p0[ 1 ]; /* Find the position of the new point. */ p0[ 0 ] = p1[ 0 ] + dx; p0[ 1 ] = p1[ 1 ] + dy; /* Increment the length of the edge by the geodesic distance from this point to the previous point. If the Frame is flat, this is simple (given that we know that one of dx and dy must be zero). */ if( flat ) { len += fabs( dx + dy ); } else { len += astDistance( frm, p0, p1 ); } } /* Save the length of this edge, and also form the total length round all edges. */ edge_len[ iedge ] = len; total_len += len; } /* Find the average number of points per unit geodesic distance around the boundary. */ if( total_len > 0.0 ) { ppd = np / total_len; /* Use this, with the geodesic length of each edge found above, to find the number of points to put along each edge of the boundary, and update the total number of points to use. In the returned boundary we put a point at the start of each edge but not at the end (since the end of one edge will be the start of the next edge). */ np = 0; for( iedge = 0; iedge < 4; iedge++ ) { np_edge[ iedge ] = (int) ( edge_len[ iedge ]*ppd ); if( np_edge[ iedge ] == 0 ) np_edge[ iedge ] = 1; np += np_edge[ iedge ]; } /* Report error if total length round box is zero. */ } else if( astOK ) { astError( AST__INTER, "astRegBaseMesh(%s): Distance around " "box perimeter is zero (internal AST programming " "error).", status, astGetClass( this ) ); } /* If the Frame has no usable metric, give an equal number of points (equal to a quarter of the total) to all 4 sides of the box. */ } else { np0 = (int) ( 0.25*np ); np = 0; for( iedge = 0; iedge < 4; iedge++ ) { np_edge[ iedge ] = np0; np += np_edge[ iedge ]; } } /* Create a PointSet with enough room and get a pointer to its data arrays. */ result = astPointSet( np, 2, "", status ); ptr = astGetPoints( result ); if( astOK ) { /* Initialise pointers to the first element for each axis in the returned PointSet. */ ax = ptr[ 0 ]; ay = ptr[ 1 ]; /* Loop round each edge. */ for( iedge = 0; iedge < 4; iedge++ ) { /* Find the increment in x and y between adjacent points along this edge. */ dx = ( c[ iedge + 1 ][ 0 ] - c[ iedge ][ 0 ] )/ np_edge[ iedge ]; dy = ( c[ iedge + 1 ][ 1 ] - c[ iedge ][ 1 ] )/ np_edge[ iedge ]; /* Store the first point. */ lax = c[ iedge ][ 0 ]; lay = c[ iedge ][ 1 ]; *(ax++) = lax; *(ay++) = lay; /* Loop round the remaining points, incrementing the pointers at the same time. */ for( i = 1; i < np_edge[ iedge ]; i++, ax++, ay++ ) { /* Find the position of the new point and store it. */ lax += dx; lay += dy; *ax = lax; *ay = lay; } } } /* Free resources. */ pfrm0 = astAnnul( pfrm0 ); pfrm1 = astAnnul( pfrm1 ); /* Now deal with boxes with more than 2 dimensions. */ } else { /* Number of samples along each edge of the hyper-cube. */ np_axis = 1 + (int) pow( np/(2*naxes), 1.0/(naxes-1) ); if( np_axis < 2 ) np_axis = 2; /* Each face of the hyper-cube will have np_axis**(naxes-1) points, and there are 2*naxes faces. Create a PointSet with the correct number of points. */ np = 2*naxes; for( iaxis = 1; iaxis < naxes; iaxis++ ) np *= np_axis; result = astPointSet( np, naxes, "", status ); ptr = astGetPoints( result ); if( astOK ) { /* Initialise the index of the next point to add into the PointSet. */ ip = 0; /* Create the upper and lower faces for each axis in turn. */ for( iaxis = 0; iaxis < naxes; iaxis++ ) { /* First do the upper face for this axis. */ ip += MakeGrid( naxes, ptr, ip, lbnd, ubnd, NULL, np_axis, iaxis, ubnd[ iaxis ], status ); /* Now do the lower face for this axis. */ ip += MakeGrid( naxes, ptr, ip, lbnd, ubnd, NULL, np_axis, iaxis, lbnd[ iaxis ], status ); } /* Remove any unused space at the end of the PointSet. */ if( ip < np ) astSetNpoint( result, ip ); } } /* Same the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this->basemesh = astClone( result ); /* Free resources. */ frm = astAnnul( frm ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; /* Undefine macros local to this function. */ #undef NP_EDGE } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "box.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * Box member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; /* The base Frame in the supplied Region */ AstFrame *frm; /* The base Frame in the returned Region */ AstPointSet *pset; /* Holds axis values defining the supplied Region */ AstRegion *bunc; /* The uncertainty in the supplied Region */ AstRegion *result; /* Returned Region */ AstRegion *unc; /* The uncertainty in the returned Region */ double **ptr; /* Holds axis values defining the supplied Region */ double *cen; /* Base Frm axis values at centre of returned Box */ double *cor; /* Base Frm axis values at a corner of returned Box */ int i; /* Index of axis within returned Region */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the base Frame of the encapsulated FrameSet. */ bfrm = astGetFrame( this_region->frameset, AST__BASE ); /* Create a Frame by picking the selected axes from the base Frame of the encapsulated FrameSet. */ frm = astPickAxes( bfrm, naxes, axes, NULL ); /* Get the uncertainty Region (if any) within the base Frame of the supplied Region, and select the required axes from it. If the resulting Object is not a Region, annul it so that the returned Region will have no uncertainty. */ if( astTestUnc( this_region ) ) { bunc = astGetUncFrm( this_region, AST__BASE ); unc = astPickAxes( bunc, naxes, axes, NULL ); bunc = astAnnul( bunc ); if( ! astIsARegion( unc ) ) unc = astAnnul( unc ); } else { unc = NULL; } /* Get pointers to the coordinate data in the parent Region structure. */ pset = this_region->points; ptr = astGetPoints( pset ); /* Get space to hold the centre and corner of the Box in the new Frame. */ cen = astMalloc( sizeof( *cen )*naxes ); cor = astMalloc( sizeof( *cor )*naxes ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the centre and corner axis values for the selected axes into the arrays allocated above. */ for( i = 0; i < naxes; i++ ) { cen[ i ] = ptr[ axes[ i ] ][ 0 ]; cor[ i ] = ptr[ axes[ i ] ][ 1 ]; } /* Create the new Box. */ result = (AstRegion *) astBox( frm, 0, cen, cor, unc, "", status ); } /* Free resources */ frm = astAnnul( frm ); bfrm = astAnnul( bfrm ); if( unc ) unc = astAnnul( unc ); cen = astFree( cen ); cor = astFree( cor ); /* Return a NULL pointer if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static double *RegCentre( AstRegion *this_region, double *cen, double **ptr, int index, int ifrm, int *status ){ /* * Name: * RegCentre * Purpose: * Re-centre a Region. * Type: * Private function. * Synopsis: * #include "box.h" * double *RegCentre( AstRegion *this, double *cen, double **ptr, * int index, int ifrm, int *status ) * Class Membership: * Box member function (over-rides the astRegCentre protected * method inherited from the Region class). * Description: * This function shifts the centre of the supplied Region to a * specified position, or returns the current centre of the Region. * Parameters: * this * Pointer to the Region. * cen * Pointer to an array of axis values, giving the new centre. * Supply a NULL value for this in order to use "ptr" and "index" to * specify the new centre. * ptr * Pointer to an array of points, one for each axis in the Region. * Each pointer locates an array of axis values. This is the format * returned by the PointSet method astGetPoints. Only used if "cen" * is NULL. * index * The index of the point within the arrays identified by "ptr" at * which is stored the coords for the new centre position. Only used * if "cen" is NULL. * ifrm * Should be AST__BASE or AST__CURRENT. Indicates whether the centre * position is supplied and returned in the base or current Frame of * the FrameSet encapsulated within "this". * status * Pointer to the inherited status variable. * Returned Value: * If both "cen" and "ptr" are NULL then a pointer to a newly * allocated dynamic array is returned which contains the centre * coords of the Region. This array should be freed using astFree when * no longer needed. If either of "ptr" or "cen" is not NULL, then a * NULL pointer is returned. * Notes: * - Some Region sub-classes do not have a centre. Such classes will report * an AST__INTER error code if this method is called with either "ptr" or * "cen" not NULL. If "ptr" and "cen" are both NULL, then no error is * reported if this method is invoked on a Region of an unsuitable class, * but NULL is always returned. */ /* Local Variables: */ AstBox *this; /* Pointer to Box structure */ AstFrame *frm; /* Pointer to Box's base Frame */ double **rptr; /* Data pointers for Region PointSet */ double *bc; /* Base Frame centre position */ double *corner; /* Array holding corner axis values */ double *result; /* Returned pointer */ double *tmp; /* Temporary array pointer */ double axval; /* Axis value */ int ic; /* Coordinate index */ int ncb; /* Number of base frame coordinate values per point */ int ncc; /* Number of current frame coordinate values per point */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get a pointer to the Box structure. */ this = (AstBox *) this_region; /* First ensure cached information (which includes the centre coords) is up to date. */ Cache( this, 0, status ); /* Get the number of axis values per point in the base and current Frames. */ ncb = astGetNin( this_region->frameset ); ncc = astGetNout( this_region->frameset ); /* If the centre coords are to be returned, return either a copy of the base Frame centre coords, or transform the base Frame centre coords into the current Frame. First ensure cached information (which includes the centre coords) is up to date. */ if( !ptr && !cen ) { if( ifrm == AST__CURRENT ) { result = astRegTranPoint( this_region, this->centre, 1, 1 ); } else { result = astStore( NULL, this->centre, sizeof( double )*ncb ); } /* Otherwise, we store the supplied new centre coords and return a NULL pointer. */ } else { /* Get a pointer to the axis values stored in the Region structure. */ rptr = astGetPoints( this_region->points ); /* Check pointers can be used safely */ if( astOK ) { /* If the centre position was supplied in the current Frame, find the corresponding base Frame position... */ if( ifrm == AST__CURRENT ) { if( cen ) { bc = astRegTranPoint( this_region, cen, 1, 0 ); } else { tmp = astMalloc( sizeof( double)*(size_t)ncc ); if( astOK ) { for( ic = 0; ic < ncc; ic++ ) tmp[ ic ] = ptr[ ic ][ index ]; } bc = astRegTranPoint( this_region, tmp, 1, 0 ); tmp = astFree( tmp ); } /* Replace any bad centre values with their current values. */ for( ic = 0; ic < ncb; ic++ ) { if( bc[ ic ] == AST__BAD ) bc[ ic ] = this->centre[ ic ]; } /* If the centre position was supplied in the base Frame, store the centre coords in this->centre, skipping bad values. */ } else { bc = this->centre; for( ic = 0; ic < ncb; ic++ ) { axval = cen ? cen[ ic ] : ptr[ ic ][ index ]; if( axval != AST__BAD ) bc[ ic ] = axval; } } /* Find the coordinates at the new box corner. */ frm = astGetFrame( this_region->frameset, AST__BASE ); corner = GeoCorner( frm, ncb, bc, this->geolen, NULL, status ); frm = astAnnul( frm ); /* ... and change the coords in the parent Region structure. */ for( ic = 0; ic < ncb; ic++ ) { rptr[ ic ][ 0 ] = bc[ ic ]; rptr[ ic ][ 1 ] = corner[ ic ]; } /* Free resources */ if( ifrm == AST__CURRENT ) bc = astFree( bc ); corner = astFree( corner ); /* Indicate the cached info in the Box structure is out of date. */ astResetCache( this ); /* Any base Frame mesh or grid is now no good, so annul it. */ if( this_region->basemesh ) this_region->basemesh = astAnnul( this_region->basemesh ); if( this_region->basegrid ) this_region->basegrid = astAnnul( this_region->basegrid ); } } /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Box. * Type: * Private function. * Synopsis: * #include "box.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Box member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Box. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Box "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Box. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstBox *large_box; /* Box slightly larger than "this" */ AstBox *small_box; /* Box slightly smaller than "this" */ AstBox *this; /* Pointer to the Box structure. */ AstFrame *frm; /* Base Frame in supplied Box */ AstPointSet *ps1; /* Points masked by larger Box */ AstPointSet *ps2; /* Points masked by larger and smaller Boxes */ AstRegion *tunc; /* Uncertainity Region from "this" */ double **ptr; /* Pointer to axis values in "ps2" */ double *large; /* A corner position in the larger Box */ double *safe; /* An interior point in "this" */ double *lbnd_tunc; /* Lower bounds of "this" uncertainty Region */ double *lbnd_unc; /* Lower bounds of supplied uncertainty Region */ double *p; /* Pointer to next axis value */ double *small; /* A corner position in the smaller Box */ double *ubnd_tunc; /* Upper bounds of "this" uncertainty Region */ double *ubnd_unc; /* Upper bounds of supplied uncertainty Region */ double *wid; /* Widths of "this" border */ int i; /* Axis index */ int j; /* Point index */ int nc; /* No. of axes in Box base frame */ int np; /* No. of supplied points */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Box structure. */ this = (AstBox *) this_region; /* Ensure cached information is up to date. */ Cache( this, 0, status ); /* Get the number of base Frame axes in the Box, and check the supplied PointSet has the same number of axis values per point. */ frm = astGetFrame( this_region->frameset, AST__BASE ); nc = astGetNaxes( frm ); if( astGetNcoord( pset ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axis " "values per point (%d) in the supplied PointSet - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNcoord( pset ), nc ); } /* Get the number of axes in the uncertainty Region and check it is the same as above. */ if( unc && astGetNaxes( unc ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axes (%d) " "in the supplied uncertainty Region - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNaxes( unc ), nc ); } /* Get the centre of the region in the base Frame. We use this as a "safe" interior point within the region. */ safe = astRegCentre( this, NULL, NULL, 0, AST__BASE ); /* We now find the maximum distance on each axis that a point can be from the boundary of the Box for it still to be considered to be on the boundary. First get the Region which defines the uncertainty within the Box being checked (in its base Frame), re-centre it on the interior point found above (to avoid problems if the uncertainty region straddles a discontinuity), and get its bounding box. */ tunc = astGetUncFrm( this, AST__BASE ); if( safe ) astRegCentre( tunc, safe, NULL, 0, AST__CURRENT ); lbnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( tunc, lbnd_tunc, ubnd_tunc ); /* Also get the Region which defines the uncertainty of the supplied points and get its bounding box. First re-centre the uncertainty at the interior position to avoid problems from uncertainties that straddle a discontinuity. */ if( unc ) { if( safe ) astRegCentre( unc, safe, NULL, 0, AST__CURRENT ); lbnd_unc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_unc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); } else { lbnd_unc = NULL; ubnd_unc = NULL; } /* The required border width for each axis is half of the total width of the two bounding boxes. Use a zero sized box "unc" if no box was supplied. */ wid = astMalloc( sizeof( double )*(size_t) nc ); large = astMalloc( sizeof( double )*(size_t) nc ); small = astMalloc( sizeof( double )*(size_t) nc ); if( astOK ) { if( unc ) { for( i = 0; i < nc; i++ ) { wid[ i ] = 0.5*( fabs( astAxDistance( frm, i + 1, lbnd_tunc[ i ], ubnd_tunc[ i ] ) ) + fabs( astAxDistance( frm, i + 1, lbnd_unc[ i ], ubnd_unc[ i ] ) ) ); } } else { for( i = 0; i < nc; i++ ) { wid[ i ] = fabs( 0.5*astAxDistance( frm, i + 1, lbnd_tunc[ i ], ubnd_tunc[ i ] ) ); } } /* Create two new Boxes, one of which is larger than "this" by the widths found above, and the other of which is smaller than "this" by the widths found above. */ for( i = 0; i < nc; i++ ) { large[ i ] = this->centre[ i ] + this->extent[ i ] + wid[ i ]; small[ i ] = this->extent[ i ] - wid[ i ]; if( small[ i ] < 0.0 ) small[ i ] = 0.0; small[ i ] += this->centre[ i ]; } large_box = astBox( frm, 0, this->centre, large, NULL, "", status ); small_box = astBox( frm, 0, this->centre, small, NULL, "", status ); /* Negate the smaller region.*/ astNegate( small_box ); /* Points are on the boundary of "this" if they are inside both the large box and the negated smallbox. First transform the supplied PointSet using the large box, then transform them using the negated smaller Box. */ ps1 = astTransform( large_box, pset, 1, NULL ); ps2 = astTransform( small_box, ps1, 1, NULL ); /* Get a point to the resulting axis values, and the number of axis values per axis. */ ptr = astGetPoints( ps2 ); np = astGetNpoint( ps2 ); /* If a mask array is to be returned, create one. */ if( mask ) { *mask = astMalloc( sizeof(int)*(size_t) np ); /* Check all the resulting points, setting mask values for all of them. */ if( astOK ) { /* Initialise the mask elements on the basis of the first axis values */ result = 1; p = ptr[ 0 ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } else { (*mask)[ j ] = 1; } } /* Now check for bad values on other axes. */ for( i = 1; i < nc; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } } } } /* If no output mask is to be made, we can break out of the check as soon as the first bad value is found. */ } else if( astOK ) { result = 1; for( i = 0; i < nc && result; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; break; } } } } /* Free resources. */ large_box = astAnnul( large_box ); small_box = astAnnul( small_box ); ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } tunc = astAnnul( tunc ); frm = astAnnul( frm ); lbnd_tunc = astFree( lbnd_tunc ); ubnd_tunc = astFree( ubnd_tunc ); if( unc ) lbnd_unc = astFree( lbnd_unc ); if( unc ) ubnd_unc = astFree( ubnd_unc ); wid = astFree( wid ); large = astFree( large ); small = astFree( small ); safe = astFree( safe ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static int RegTrace( AstRegion *this_region, int n, double *dist, double **ptr, int *status ){ /* *+ * Name: * RegTrace * Purpose: * Return requested positions on the boundary of a 2D Region. * Type: * Private function. * Synopsis: * #include "box.h" * int astTraceRegion( AstRegion *this, int n, double *dist, double **ptr ); * Class Membership: * Box member function (overrides the astTraceRegion method * inherited from the parent Region class). * Description: * This function returns positions on the boundary of the supplied * Region, if possible. The required positions are indicated by a * supplied list of scalar parameter values in the range zero to one. * Zero corresponds to some arbitrary starting point on the boundary, * and one corresponds to the end (which for a closed region will be * the same place as the start). * Parameters: * this * Pointer to the Region. * n * The number of positions to return. If this is zero, the function * returns without action (but the returned function value still * indicates if the method is supported or not). * dist * Pointer to an array of "n" scalar parameter values in the range * 0 to 1.0. * ptr * A pointer to an array of pointers. The number of elements in * this array should equal tthe number of axes in the Frame spanned * by the Region. Each element of the array should be a pointer to * an array of "n" doubles, in which to return the "n" values for * the corresponding axis. The contents of the arrays are unchanged * if the supplied Region belongs to a class that does not * implement this method. * Returned Value: * Non-zero if the astTraceRegion method is implemented by the class * of Region supplied, and zero if not. *- */ /* Local Variables; */ AstMapping *map; AstPointSet *bpset; AstPointSet *cpset; double **bptr; double d; double lbnd[ 2 ]; double ubnd[ 2 ]; int i; int ncur; int result; /* Initialise */ result = 0; /* Check inherited status. */ if( ! astOK ) return result; /* Check it is 2-dimensional. */ if( astGetNin( this_region->frameset ) == 2 ) result = 1; /* Check we have some points to find. */ if( result && n > 0 ) { /* We first determine the required positions in the base Frame of the Region, and then transform them into the current Frame. Get the base->current Mapping, and the number of current Frame axes. */ map = astGetMapping( this_region->frameset, AST__BASE, AST__CURRENT ); /* If it's a UnitMap we do not need to do the transformation, so put the base Frame positions directly into the supplied arrays. */ if( astIsAUnitMap( map ) ) { bpset = NULL; bptr = ptr; ncur = 2; /* Otherwise, create a PointSet to hold the base Frame positions. */ } else { bpset = astPointSet( n, 2, " ", status ); bptr = astGetPoints( bpset ); ncur = astGetNout( map ); } /* Check the pointers can be used safely. */ if( astOK ) { /* Get the bounds of the Region in the base Frame. */ astRegBaseBox( this_region, lbnd, ubnd ); /* Loop round each point. Each edge of the box covers a parameteric distance of 0.25, regardless of the aspect ratio of the box. */ for( i = 0; i < n; i++ ) { /* The right hand edge starts at 0.75 (parameter increases top to bottom). */ d = 4*dist[ i ] - 3; if( d > 0 ) { bptr[ 0 ][ i ] = ubnd[ 0 ]; bptr[ 1 ][ i ] = ( 1.0 - d )*ubnd[ 1 ] + d*lbnd[ 1 ]; /* The top edge starts at 0.5 (parameter increases left to right). */ } else { d += 1.0; if( d > 0 ) { bptr[ 0 ][ i ] = ( 1.0 - d )*lbnd[ 0 ] + d*ubnd[ 0 ]; bptr[ 1 ][ i ] = ubnd[ 1 ]; /* The left hand edge starts at 0.25 (parameter increases bottom to top). */ } else { d += 1.0; if( d > 0 ) { bptr[ 0 ][ i ] = lbnd[ 0 ]; bptr[ 1 ][ i ] = ( 1.0 - d )*lbnd[ 1 ] + d*ubnd[ 1 ]; /* The bottom edge starts at 0.0 (parameter increases right to left). */ } else { d += 1.0; bptr[ 0 ][ i ] = ( 1.0 - d )*ubnd[ 0 ] + d*lbnd[ 0 ]; bptr[ 1 ][ i ] = lbnd[ 1 ]; } } } } } /* If required, transform the base frame positions into the current Frame, storing them in the supplied array. Then free resources. */ if( bpset ) { cpset = astPointSet( n, ncur, " ", status ); astSetPoints( cpset, ptr ); (void) astTransform( map, bpset, 1, cpset ); cpset = astAnnul( cpset ); bpset = astAnnul( bpset ); } /* Free remaining resources. */ map = astAnnul( map ); } /* Return the result. */ return result; } static void ResetCache( AstRegion *this, int *status ){ /* * Name: * ResetCache * Purpose: * Clear cached information within the supplied Region. * Type: * Private function. * Synopsis: * #include "box.h" * void ResetCache( AstRegion *this, int *status ) * Class Membership: * Region member function (overrides the astResetCache method * inherited from the parent Region class). * Description: * This function clears cached information from the supplied Region * structure. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ if( this ) { ((AstBox *) this )->stale = 1; (*parent_resetcache)( this, status ); } } static void SetClosed( AstRegion *this, int value, int *status ){ /* * Name: * SetClosed * Purpose: * Set a value for the Closed attribute of a Region. * Type: * Private function. * Synopsis: * #include "box.h" * void SetClosed( AstRegion *this, int value, int *status ) * Class Membership: * Box member function (over-rides the protected astSetClosed * method inherited from the Region class). * Description: * This function sets a new value for the Closed attribute of a Region. * Parameters: * this * Pointer to the Region. * value * The new attribute value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int old; /* Check the global error status. */ if ( !astOK ) return; /* Get the original attribute value */ old = astGetClosed( this ); /* Invoke the set method inherited from the parent Region class */ (*parent_setclosed)( this, value, status ); /* If the new value is not the same as the old value, indicate that we need to re-calculate the cached information in the Box. */ if( value != old ) astResetCache( this ); } static void SetNegated( AstRegion *this, int value, int *status ){ /* * Name: * SetNegated * Purpose: * Set a value for the Negated attribute of a Region. * Type: * Private function. * Synopsis: * #include "box.h" * void SetNegated( AstRegion *this, int value, int *status ) * Class Membership: * Box member function (over-rides the protected astSetNegated * method inherited from the Region class). * Description: * This function sets a new value for the Negated attribute of a Region. * Parameters: * this * Pointer to the Region. * value * The new attribute value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int old; /* Check the global error status. */ if ( !astOK ) return; /* Get the original attribute value */ old = astGetNegated( this ); /* Invoke the set method inherited from the parent Region class */ (*parent_setnegated)( this, value, status ); /* If the new value is not the same as the old value, indicate that we need to re-calculate the cached information in the Box. */ if( value != old ) astResetCache( this ); } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "box.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Box method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* Indicate that we need to re-calculate the cached information in the Box. */ astResetCache( this_region ); } static void SetUnc( AstRegion *this, AstRegion *unc, int *status ){ /* * Name: * SetUnc * Purpose: * Store uncertainty information in a Region. * Type: * Private function. * Synopsis: * #include "box.h" * void SetUnc( AstRegion *this, AstRegion *unc, int *status ) * Class Membership: * Box method (over-rides the astSetUnc method inherited from the * Region class). * Description: * Each Region (of any class) can have an "uncertainty" which specifies * the uncertainties associated with the boundary of the Region. This * information is supplied in the form of a second Region. The uncertainty * in any point on the boundary of a Region is found by shifting the * associated "uncertainty" Region so that it is centred at the boundary * point being considered. The area covered by the shifted uncertainty * Region then represents the uncertainty in the boundary position. * The uncertainty is assumed to be the same for all points. * * The uncertainty is usually specified when the Region is created, but * this function allows it to be changed at any time. * Parameters: * this * Pointer to the Region which is to be assigned a new uncertainty. * unc * Pointer to the new uncertainty Region. This must be either a Box, * a Circle or an Ellipse. A deep copy of the supplied Region will be * taken, so subsequent changes to the uncertainty Region using the * supplied pointer will have no effect on the Region "this". * status * Pointer to the inherited status variable. */ /* Check the inherited status. */ if( !astOK ) return; /* Invoke the astSetUnc method inherited from the parent Region class. */ (*parent_setunc)( this, unc, status ); /* Indicate that we need to re-calculate the cached information in the Box. */ astResetCache( this ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "box.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Box method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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: */ AstBox *box; /* Pointer to Box structure */ AstBox *newbox; /* Pointer to simpler Box */ AstFrame *frm; /* Pointer to current Frame */ AstMapping *map; /* Base -> current Mapping */ AstMapping *result; /* Result pointer to return */ AstPointSet *basemesh; /* Mesh of base Frame positions */ AstPointSet *mesh; /* Mesh of current Frame positions */ AstPointSet *ps1; /* Box corners in base Frame */ AstPointSet *ps2; /* Box corners in current Frame */ AstPolygon *newpoly; /* New Polygon to replace Box */ AstRegion *prism; /* Prism combining all axes */ AstRegion *new; /* Pointer to simplified Region */ AstRegion *this; /* Pointer to supplied Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr1; /* Pointers to axis values in ps1 */ double **ptr2; /* Pointers to axis values in ps2 */ double *constants; /* Axis constants array */ double *lbnd; /* Lower bounds for new Box */ double *ubnd; /* Upper bounds for new Box */ double corners[8]; /* Box corners in current Frame */ double k; /* Axis constant value */ double lb; /* Lower axis bound */ double ub; /* Upper axis bound */ int *inperm; /* Input axis permutation array */ int *outperm; /* Output axis permutation array */ int closed; /* Was original Region closed? */ int feed; /* Source of value for current axis */ int right_handed; /* Is the new Frame right handed? */ int ic; /* Axis index */ int isInterval; /* Is the simplified Box an Interval */ int isNull; /* Is the simplified Box a NullRegion? */ int neg; /* Was original Region negated? */ int nin; /* No. of base Frame axes (Mapping inputs) */ int nout; /* No. of current Frame axes (Mapping outputs) */ int simpler; /* Has some simplication taken place? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* Get the Mapping from base to current Frame. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); /* Get the number of inputs and outputs for the PermMap */ nin = astGetNin( map ); nout = astGetNout( map ); /* If the Mapping from base to current Frame is a PermMap, we now explicitly how to swap the axes of the Box to produce either a new Box or an Interval. */ if( astIsAPermMap( map ) ){ /* See if the new Box is Negated and/or Closed.*/ neg = astGetNegated( new ); closed = astGetClosed( new ); /* Get a pointer to the Box structure. */ newbox = (AstBox *) new; /* Ensure cached information is up to date. */ Cache( newbox, 0, status ); /* Get the input and output permutation arrays and the array of constants from the PermMap. */ inperm = astGetInPerm( map ); outperm = astGetOutPerm( map ); constants = astGetConstants( map ); /* Allocate memory to hold the axis bounds for the box in the current Frame. */ lbnd = astMalloc( sizeof( double )*(size_t) nout ); ubnd = astMalloc( sizeof( double )*(size_t) nout ); /* Check pointers can be used safely. */ if( astOK ) { /* Set flags indicating that the Box can be simplified, and does not result in a NullRegion or an Interval. */ simpler = 1; isNull = 0; isInterval = 0; /* Check each output (which corresponds to an axis in the current Frame of the Box). */ for( ic = 0; ic < nout; ic++ ) { /* Find the input (a base Frame axis) which feeds this output when the forward transformation of the PermMap is used. */ feed = outperm[ ic ]; /* If this output is fed a constant (i.e. does not depend on any of the inputs), then the output axis limits are equal to this constant. */ if( feed < 0 ) { lbnd[ ic ] = constants[ (-feed) - 1 ]; ubnd[ ic ] = constants[ (-feed) - 1 ]; /* If this output is fed the constant AST__BAD (i.e. does not depend on any of the inputs), then the output axis is unbounded and we will consequently create an Interval rather than a Box. */ } else if( feed >= nin ) { lbnd[ ic ] = AST__BAD; ubnd[ ic ] = AST__BAD; /* If this output is fed the value of an input, then the output limits are equal to the corresponding input limits. */ } else { lbnd[ ic ] = newbox->centre[ feed ] - newbox->extent[ feed ]; ubnd[ ic ] = newbox->centre[ feed ] + newbox->extent[ feed ]; } /* If either bound is missing we will produce an Interval rather than a Box. */ if( lbnd[ ic ] == AST__BAD || ubnd[ ic ] == AST__BAD ) { isInterval = 1; } } /* If any base Frame axes are not present in the current Frame, we need to check that the PermMap selects a slice which intersects the base Frame box. If the slice does not intersect the base Frame box, then the resulting Region willbe NullRegion. To do this, we check each element in the input axis permutation array, "inperm". */ for( ic = 0; ic < nin; ic++ ) { /* Find the output (a current Frame axis) which feeds this input when the inverse transformation of the PermMap is used. */ feed = inperm[ ic ]; /* If this input is fed a constant (i.e. does not depend on any of the outputs), then we must check that this constant is within the range of axis values covered by the Box. If not then the simplified Box represents a slice through the coordinate system which does not pass through the original Box. In this case the simplified Region is a NullRegion instead of a Box. */ if( feed < 0 ) { k = constants[ (-feed) - 1 ]; lb = newbox->centre[ ic ] - newbox->extent[ ic ]; ub = newbox->centre[ ic ] + newbox->extent[ ic ]; if( closed == neg ) { isNull = ( k <= lb || k >= ub ); } else { isNull = ( k < lb || k > ub ); } /* If this input is fed the constant AST__BAD (i.e. does not depend on any of the outputs), then the input axis is unbounded and will consequently extend beyond the Box. In this case the simplified Region will be a NullRegion. */ } else if( feed >= nout ) { isNull = 1; /* If this input is fed the value of an output, then check that the relationship is bi-directional. If it is not, we cannot simplify the Box. */ } else if( outperm[ feed ] != ic ) { simpler = 0; break; } } /* If the Box can be simplified, create a new Region of an appropriate class. */ if( simpler ) { /* Get any uncertainty from the supplied Box (it will already have been simplified by the parent Simplify method). */ unc = astTestUnc( new ) ? astGetUncFrm( new, AST__CURRENT ) : NULL; /* Get the Frame represented by the Region. */ frm = astGetFrame( new->frameset, AST__CURRENT ); /* We can now replace the original Region with the simplified Region so annul the original pointer. */ new = astAnnul( new ); /* Create a new Region of the required class. */ if( isNull ) { new = (AstRegion *) astNullRegion( frm, unc, "", status ); } else if( isInterval ){ new = (AstRegion *) astInterval( frm, lbnd, ubnd, unc, "", status ); } else { new = (AstRegion *) astBox( frm, 1, lbnd, ubnd, unc, "", status ); } /* If the original box was Negated. Negate the new one. */ if( neg ) astNegate( new ); /* Free resources */ if( unc ) unc = astAnnul( unc ); frm = astAnnul( frm ); } } /* Free resources */ inperm = astFree( inperm ); outperm = astFree( outperm ); constants = astFree( constants ); lbnd = astFree( lbnd ); ubnd = astFree( ubnd ); /* If the Mapping from base to current Frame is not a PermMap or a UnitMap, we attempt to simplify the Box by re-defining it within its current Frame. Transforming the box from its base to its current FRame may result in the region no longer being a box. We test this by transforming a set of bounds on the box boundary. */ } else if( !astIsAUnitMap( map ) ){ /* Get pointer to current Frame. */ frm = astGetFrame( new->frameset, AST__CURRENT ); /* Get a mesh of points covering the Box in its current Frame. */ mesh = astRegMesh( new ); /* Get the Region describing the positional uncertainty within the Box in its current Frame. */ unc = astGetUncFrm( new, AST__CURRENT ); /* Find the best fitting box (defined in the current Frame) through these points */ newbox = BestBox( frm, mesh, unc, status ); /* See if all points within this mesh fall on the boundary of the best fitting Box, to within the uncertainty of the Region. */ if( newbox && astRegPins( newbox, mesh, NULL, NULL ) ) { /* If so, check that the inverse is true (we need to transform the simplified boxes mesh into the base Frame of he original box for use by astRegPins). */ (void) astAnnul( mesh ); mesh = astRegMesh( newbox ); basemesh = astTransform( map, mesh, 0, NULL ); if( astRegPins( new, basemesh, NULL, NULL ) ) { /* If so, use the new Box in place of the original Box. */ (void) astAnnul( new ); new = astClone( newbox ); simpler = 1; } /* Free resources. */ basemesh = astAnnul( basemesh ); /* If the transformed Box is not itself a Box, see if it can be represented accurately by a Polygon. This is only possible for 2-dimensional Boxes. */ } else if( nin == 2 && nout == 2 ) { /* Create a PointSet holding the base Frame axis values at the four corners of the Box. */ ps1 = astPointSet( 4, 2, "", status ); ptr1 = astGetPoints( ps1 ); if( astOK ) { box = (AstBox *) new; Cache( box, 0, status ); /* The order in which the polygon vertices are stored determines whether the interior or exterior of the polygon forms the inside of the Region. We want the inside to be the interior. First create a Polygon in which the vertices are stored in clockwise order within the new coordinate Frame. If the new Polygon is not bounded, use anti-clockwise order. */ for( right_handed = 0; right_handed < 2; right_handed++ ) { if( right_handed ) { ptr1[ 0 ][ 0 ] = box->centre[ 0 ] - box->extent[ 0 ]; ptr1[ 1 ][ 0 ] = box->centre[ 1 ] + box->extent[ 1 ]; ptr1[ 0 ][ 1 ] = box->centre[ 0 ] - box->extent[ 0 ]; ptr1[ 1 ][ 1 ] = box->centre[ 1 ] - box->extent[ 1 ]; ptr1[ 0 ][ 2 ] = box->centre[ 0 ] + box->extent[ 0 ]; ptr1[ 1 ][ 2 ] = box->centre[ 1 ] - box->extent[ 1 ]; ptr1[ 0 ][ 3 ] = box->centre[ 0 ] + box->extent[ 0 ]; ptr1[ 1 ][ 3 ] = box->centre[ 1 ] + box->extent[ 1 ]; } else { ptr1[ 0 ][ 3 ] = box->centre[ 0 ] - box->extent[ 0 ]; ptr1[ 1 ][ 3 ] = box->centre[ 1 ] + box->extent[ 1 ]; ptr1[ 0 ][ 2 ] = box->centre[ 0 ] - box->extent[ 0 ]; ptr1[ 1 ][ 2 ] = box->centre[ 1 ] - box->extent[ 1 ]; ptr1[ 0 ][ 1 ] = box->centre[ 0 ] + box->extent[ 0 ]; ptr1[ 1 ][ 1 ] = box->centre[ 1 ] - box->extent[ 1 ]; ptr1[ 0 ][ 0 ] = box->centre[ 0 ] + box->extent[ 0 ]; ptr1[ 1 ][ 0 ] = box->centre[ 1 ] + box->extent[ 1 ]; } /* Transform the Box corners into the current Frame. */ ps2 = astTransform( map, ps1, 1, NULL ); ptr2 = astGetPoints( ps2 ); if( astOK ) { /* Create a Polygon from these points. */ for( ic = 0; ic < 4; ic++ ) { corners[ ic ] = ptr2[ 0 ][ ic ]; corners[ 4 + ic ] = ptr2[ 1 ][ ic ]; } newpoly = astPolygon( frm, 4, 4, corners, unc, "", status ); /* If the Polygon is bounded, break out of the loop. */ if( astGetBounded( newpoly ) ) break; } /* Free resources. */ newpoly = astAnnul( newpoly ); ps2 = astAnnul( ps2 ); } /* See if all points within the Box mesh fall on the boundary of this Polygon, to within the uncertainty of the Region. */ if( astRegPins( newpoly, mesh, NULL, NULL ) ) { /* If so, use the new Polygon in place of the original Box. */ (void) astAnnul( new ); new = astClone( newpoly ); simpler = 1; } /* Free resources. */ newpoly = astAnnul( newpoly ); } ps1 = astAnnul( ps1 ); } /* If we have yet been able to produce a simpler region, we now try splitting the Box into two separate Boxes defined in separate coordinate Frames. If either of these two Boxes can be simplified, create a Prism containing the two simplified Boxes, and attempt to simplify the Prism. Otherwise a clone of "new" is returned by astConvertToPrism. */ if( !simpler ) { prism = astConvertToPrism( new ); if( prism != new ) { simpler = 1; (void) astAnnul( new ); new = prism; } else { prism = astAnnul( prism ); } } frm = astAnnul( frm ); mesh = astAnnul( mesh ); unc = astAnnul( unc ); if( newbox ) newbox = astAnnul( newbox ); } map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Box to transform a set of points. * Type: * Private function. * Synopsis: * #include "box.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Box member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a Box and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the Box. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the Box. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstBox *box; /* Pointer to Box */ AstFrame *frm; /* Pointer to base Frame in FrameSet */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ AstRegion *reg; /* Pointer to Region */ double **ptr_out; /* Pointer to output coordinate data */ double **ptr_tmp; /* Pointer to base Frame coordinate data */ double axval; /* Input axis value */ int closed; /* Is the boundary part of the Region? */ int coord; /* Zero-based index for coordinates */ int ncoord_out; /* No. of coordinates per output point */ int ncoord_tmp; /* No. of coordinates per base Frame point */ int neg; /* Is the Box negated?*/ int npoint; /* No. of points */ int ok; /* Is the point inside the Region? */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain pointers to the Regionand to the Box. */ reg = (AstRegion *) this; box = (AstBox *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). This call also returns a pointer to the base Frame of the encapsulated FrameSet. Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( reg, in, 0, NULL, &frm ); /* Determine the numbers of points and coordinates per point from the base Frame PointSet and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( pset_tmp ); ncoord_tmp = astGetNcoord( pset_tmp ); ptr_tmp = astGetPoints( pset_tmp ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* See if the boundary is part of the Region. */ closed = astGetClosed( reg ); /* See if the Box is negated */ neg = astGetNegated( reg ); /* Ensire the cached information is up to date. */ Cache( box, 1, status ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* The logic used to combine axis values for negated and un-negated boxes is different. For negated boxes, a position is in the region if *any one* axis is not "close" to the box centre. */ if( neg ) { /* Loop round each point */ for ( point = 0; point < npoint; point++ ) { /* Assume the point is outside the Region (since the Region is negated, this means assuming it is within the box). */ ok = 0; /* Loop round each axis value at this point. We break as soon as we find a bad axis value or an axis value which is outside the box. */ for ( coord = 0; coord < ncoord_tmp; coord++ ) { /* The point is definiately not in the Region if any input axis value is bad. */ axval = ptr_tmp[ coord ][ point ]; if( axval == AST__BAD ) { break; /* Otherwise check the current axis value, depending on whether the boundary is included in the Region or not. Break as soon as an axis value is found which is outside the box limits (i.e. in the Region). */ } else if( !astAxIn( frm, coord, box->lo[ coord ], box->hi[ coord ], axval, !closed ) ) { ok = 1; break; } } /* If this point is not inside the Region store bad output axis values. */ if( !ok ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } /* For un-negated boxes, a position is in the region if *all* axes are "close" to the box centre. */ } else { /* Loop round each point */ for ( point = 0; point < npoint; point++ ) { /* Assume the point is within the Region (i.e.inside the box). */ ok = 1; /* Loop round each axis value at this point. We break when we find a bad input point or if any axis value is outside the box. */ for ( coord = 0; coord < ncoord_tmp; coord++ ) { /* The point is not in the Region if any input axis value is bad. */ axval = ptr_tmp[ coord ][ point ]; if( axval == AST__BAD ) { ok = 0; break; /* Otherwise check the current axis value, depending on whether the boundary is included in the Region or not. Break as soon as an axis value is found which is outside the box limits (i.e. outside the Region). */ } else if( !astAxIn( frm, coord, box->lo[ coord ], box->hi[ coord ], axval, closed ) ) { ok = 0; break; } } /* If this point is outside the Region store bad output axis values. */ if( !ok ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } } /* Free resources */ pset_tmp = astAnnul( pset_tmp ); frm = astAnnul( frm ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Region objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Region objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstBox *in; /* Pointer to input Box */ AstBox *out; /* Pointer to output Box */ int nax; /* Number of base Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Boxs. */ in = (AstBox *) objin; out = (AstBox *) objout; /* For safety, first clear any references to the input memory from the output Box. */ out->extent = NULL; out->centre = NULL; out->lo = NULL; out->hi = NULL; out->geolen = NULL; /* Copy dynamic memory contents */ nax = astGetNin( ((AstRegion *) in)->frameset ); out->extent = astStore( NULL, in->extent, sizeof( double )*(size_t)nax ); out->centre = astStore( NULL, in->centre, sizeof( double )*(size_t)nax ); out->lo = astStore( NULL, in->lo, sizeof( double )*(size_t)nax ); out->hi = astStore( NULL, in->hi, sizeof( double )*(size_t)nax ); out->geolen = astStore( NULL, in->geolen, sizeof( double )*(size_t)nax ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Box objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Box 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: */ AstBox *this; /* Pointer to Box */ /* Obtain a pointer to the Box structure. */ this = (AstBox *) obj; /* Annul all resources. */ this->extent = astFree( this->extent ); this->centre = astFree( this->centre ); this->lo = astFree( this->lo ); this->hi = astFree( this->hi ); this->geolen = astFree( this->geolen ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Box 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 Box class to an output Channel. * Parameters: * this * Pointer to the Box whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Write out values representing the instance variables for the Box 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsABox and astCheckBox functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Box,Region) astMAKE_CHECK(Box) AstBox *astBox_( void *frame_void, int form, const double point1[], const double point2[], AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astBox f AST_BOX * Purpose: * Create a Box. * Type: * Public function. * Synopsis: c #include "box.h" c AstBox *astBox( AstFrame *frame, int form, const double point1[], c const double point2[], AstRegion *unc, c const char *options, ... ) f RESULT = AST_BOX( FRAME, FORM, POINT1, POINT2, UNC, OPTIONS, STATUS ) * Class Membership: * Box constructor. * Description: * This function creates a new Box and optionally initialises its * attributes. * * The Box class implements a Region which represents a box with sides * parallel to the axes of a Frame (i.e. an area which encloses a given * range of values on each axis). A Box is similar to an Interval, the * only real difference being that the Interval class allows some axis * limits to be unspecified. Note, a Box will only look like a box if * the Frame geometry is approximately flat. For instance, a Box centred * close to a pole in a SkyFrame will look more like a fan than a box * (the Polygon class can be used to create a box-like region close to a * pole). * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. c form f FORM = INTEGER (Given) * Indicates how the box is described by the remaining parameters. * A value of zero indicates that the box is specified by a centre * position and a corner position. A value of one indicates that the * box is specified by a two opposite corner positions. c point1 f POINT1( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). If c "form" f FORM * is zero, this array should contain the coordinates at the centre of * the box. c If "form" f If FORM * is one, it should contain the coordinates at the corner of the box * which is diagonally opposite the corner specified by c "point2". f POINT2. c point2 f POINT2( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates at any corner of the * box. c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with the boundary of the Box being created. * The uncertainty in any point on the boundary of the Box is found by * shifting the supplied "uncertainty" Region so that it is centred at * the boundary point being considered. The area covered by the * shifted uncertainty Region then represents the uncertainty in the * boundary position. The uncertainty is assumed to be the same for * all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Box. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the Box being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 Box. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Box. The syntax used is identical to that for the f AST_SET routine. 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 astBox() f AST_BOX = INTEGER * A pointer to the new Box. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstBox *new; /* Pointer to new Box */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the Box, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitBox( NULL, sizeof( AstBox ), !class_init, &class_vtab, "Box", frame, form, point1, point2, unc ); /* 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 Box'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 Box. */ return new; } AstBox *astBoxId_( void *frame_void, int form, const double point1[], const double point2[], void *unc_void, const char *options, ... ) { /* * Name: * astBoxId_ * Purpose: * Create a Box. * Type: * Private function. * Synopsis: * #include "box.h" * AstBox *astBoxId_( AstFrame *frame, int form, const double point1[], * const double point2[], AstRegion *unc, * const char *options, ... ) * Class Membership: * Box constructor. * Description: * This function implements the external (public) interface to the * astBox constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astBox_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astBox_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astBox_. * Returned Value: * The ID value associated with the new Box. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstBox *new; /* Pointer to new Box */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* 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 NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the Box, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitBox( NULL, sizeof( AstBox ), !class_init, &class_vtab, "Box", frame, form, point1, point2, unc ); /* 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 Box'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 Box. */ return astMakeId( new ); } AstBox *astInitBox_( void *mem, size_t size, int init, AstBoxVtab *vtab, const char *name, AstFrame *frame, int form, const double point1[], const double point2[], AstRegion *unc, int *status ) { /* *+ * Name: * astInitBox * Purpose: * Initialise a Box. * Type: * Protected function. * Synopsis: * #include "box.h" * AstBox *astInitBox_( void *mem, size_t size, int init, AstBoxVtab *vtab, * const char *name, AstFrame *frame, int form, * const double point1[], const double point2[], * AstRegion *unc ) * Class Membership: * Box initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Box object. It allocates memory (if necessary) to accommodate * the Box plus any additional data associated with the derived class. * It then initialises a Box 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 Box at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Box is to be initialised. * This must be of sufficient size to accommodate the Box data * (sizeof(Box)) 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 Box (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 Box * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Box'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 Box. * 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 * A pointer to the Frame in which the region is defined. * form * Indicates how the box is described by the remaining parameters. * A value of zero indicates that the box is specified by a centre * position and a corner position. A value of one indicates that the * box is specified by a two opposite corner positions. * point1 * An array of double, with one element for each Frame axis (Naxes * attribute). If "form" is zero, this array should contain the * coordinates at the centre of the box. If "form" is one, it should * contain the coordinates at the corner of the box which is diagonally * opposite the corner specified by "point2". * point2 * An array of double, with one element for each Frame axis (Naxes * attribute) containing the coordinates at any of the corners of * the box. * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points on the boundary of the new Box * being initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal to * 1.0E-6 of the dimensions of the new Box's bounding box are used. * If an uncertainty Region is supplied, it must be either a Box, a * Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new Box. * 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: */ AstBox *new; /* Pointer to new Box */ AstPointSet *pset; /* PointSet to pass to Region initialiser */ double **ptr; /* Pointer to coords data in pset */ int i; /* axis index */ int nc; /* No. of axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitBoxVtab( vtab, name ); /* Initialise. */ new = NULL; /* Get the number of axis values required for each position. */ nc = astGetNaxes( frame ); /* Create a PointSet to hold the supplied values, and get points to the data arrays. */ pset = astPointSet( 2, nc, "", status ); ptr = astGetPoints( pset ); /* Copy the supplied coordinates into the PointSet, checking that no bad values have been supplied. */ for( i = 0; astOK && i < nc; i++ ) { if( point1[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitBox(%s): The value of axis %d is " "undefined at point 1 of the box.", status, name, i + 1 ); break; } if( point2[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitBox(%s): The value of axis %d is " "undefined at point 2 of the box.", status, name, i + 1 ); break; } ptr[ i ][ 0 ] = point1[ i ]; ptr[ i ][ 1 ] = point2[ i ]; } /* If two corners were supplied, find and store the centre. */ if( form == 1 ) { for( i = 0; i < nc; i++ ) { ptr[ i ][ 0 ] = 0.5*( point1[ i ] + point2[ i ] ); } } /* Check pointers can be used safely. */ if( astOK ) { /* Initialise a Region structure (the parent class) as the first component within the Box structure, allocating memory if necessary. */ new = (AstBox *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, pset, unc ); if ( astOK ) { /* Initialise the Box data. */ /* ------------------------ */ new->extent = NULL; new->centre = NULL; new->lo = NULL; new->hi = NULL; new->geolen = NULL; new->stale = 1; /* If an error occurred, clean up by deleting the new Box. */ if ( !astOK ) new = astDelete( new ); } } /* Free resources. */ pset = astAnnul( pset ); /* Return a pointer to the new Box. */ return new; } AstBox *astLoadBox_( void *mem, size_t size, AstBoxVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadBox * Purpose: * Load a Box. * Type: * Protected function. * Synopsis: * #include "box.h" * AstBox *astLoadBox( void *mem, size_t size, AstBoxVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Box loader. * Description: * This function is provided to load a new Box 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 * Box structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Box at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Box is to be * loaded. This must be of sufficient size to accommodate the * Box data (sizeof(Box)) 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 Box (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 Box 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(AstBox) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Box. If this is NULL, a pointer * to the (static) virtual function table for the Box 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 "Box" is used instead. * Returned Value: * A pointer to the new Box. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstBox *new; /* Pointer to the new Box */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Box. In this case the Box belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstBox ); vtab = &class_vtab; name = "Box"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitBoxVtab( 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 Box. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Box" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* Initialise Box data */ new->extent = NULL; new->centre = NULL; new->lo = NULL; new->hi = NULL; new->geolen = NULL; new->stale = 1; /* If an error occurred, clean up by deleting the new Box. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Box pointer. */ return new; } /* 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 astBoxPoints_( AstBox *this, double *centre, double *corner, int *status) { if ( !astOK ) return; (**astMEMBER(this,Box,BoxPoints))( this, centre, corner, status ); return; } ast-8.3.0/wcsmap.h0000664000175000017500000005066213004147321010703 00000000000000#if !defined( WCSMAP_INCLUDED ) /* Include this file only once */ #define WCSMAP_INCLUDED /* *+ * Name: * wcsmap.h * Type: * C include file. * Purpose: * Define the interface to the WcsMap class. * Invocation: * #include "wcsmap.h" * Description: * This include file defines the interface to the WcsMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The WcsMap class implements Mappings that transform a pair of * longitude/latitude values into a pair of projected Cartesian * coordinates. All the projections included in FITS WCS are included. * For more information about these projections, see the appropriate * FITS document. * Inheritance: * The WcsMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * NatLat (double) * This attribute gives the latitude of the reference point of * a FITS WCS projection, in the native coordinate system. The value * returned is in radians. A value of AST__BAD is returned if * no value is defined. This attribute is read only, and may change * if new values are assigned to the projection parameters. * NatLon (double) * This attribute gives the longitude of the reference point of * a FITS WCS projection, in the native coordinate system. The value * returned is in radians. A value of AST__BAD is returned if * no value is defined. This attribute is read only, and may change * if new values are assigned to the projection parameters. * ProjP(i) (double) * This attribute provides aliases for the PV attributes, which * specifies the projection parameter values to be used by a WcsMap * when implementing a FITS-WCS sky projection. ProjP is retained for * compatibility with previous versions of FITS-WCS and AST. New * applications should use the PV attibute instead. * PVj_m (double) * This attribute gives the parameter values used by a FITS WCS * projection. The index j is the axis index in the range 1 to 99, and * the index m is the parameter index in the range 0 to 99. They will * have the value AST__BAD if undefined. By default, no projection * parameters are defined. These should be assigned appropriate values * before using a WcsMap to transform points. * WcsAxis(lonlat) (int) * This attribute gives the indices of the longitude and latitude axes * of a FITS WCS projection within the coordinate system used by a * WcsMap. If "lonlat" is 1 then the index of the longitude axis is * returned. If it is 2 the index of the latitude axis is returned. * The first axis in the coordinate system is axis 1. This is a * read-only attribute. * WcsType (int) * This attribute gives the FITS WCS projection type implemented by a * WcsMap. Macros giving the integer value associated with supported * projections are defined. They have the general form "AST__xxx" where * "xxx" is the 3-character code used to represent the projection in the * FITS CTYPE keyword. * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a WcsMap. * astGetAttrib * Get an attribute value for a WcsMap. * astSetAttrib * Set an attribute value for a WcsMap. * astTestAttrib * Test if an attribute value has been set for a WcsMap. * astTransform * Apply a WcsMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astClearPV * Clear a PVi_j attribute value for a WcsMap. * astGetNatLat * Get the NatLat attribute value for a WcsMap. * astGetNatLon * Get the NatLon attribute value for a WcsMap. * astGetPV * Get a PVi_j attribute value for a WcsMap. * astGetWcsAxis * Get a WcsAxis attribute value for a WcsMap. * astGetWcsType * Get the WcsType attribute value for a WcsMap. * astIsZenithal * Is the projection zenithal? * astSetPV * Set a PVi_j attribute value for a WcsMap. * astTestPV * Test if a PVi_j attribute value has been set for a WcsMap. * astWcsPrjName * Return the FITS CTYPE keyword value for a given projection type. * astWcsPrjDesc * Return a textual description for a given projection type. * astWcsPrjType * Return the projection type given a FITS CTYPE keyword value. * Other Class Functions: * Public: * astIsAWcsMap * Test class membership. * astWcsMap * Create a WcsMap. * * Protected: * astCheckWcsMap * Validate class membership. * astInitWcsMap * Initialise a WcsMap. * astInitWcsMapVtab * Initialise the virtual function table for the WcsMap class. * astLoadWcsMap * Load a WcsMap. * Macros: * Public: * AST__WCSMX * Maximum number of parameters associated with a projection. * AST__DPI * 180 degrees in radians. * AST__DPIBY2 * 90 degrees in radians. * AST__DD2R * Factor for converting degrees to radians. * AST__DR2D * Factor for converting radians to degrees. * AST__AZP * An integer identifier for the FITS AZP projection. * AST__TAN * An integer identifier for the FITS TAN projection. * AST__SIN * An integer identifier for the FITS SIN projection. * AST__STG * An integer identifier for the FITS STG projection. * AST__ARC * An integer identifier for the FITS ARC projection. * AST__ZPN * An integer identifier for the FITS ZPN projection. * AST__ZEA * An integer identifier for the FITS ZEA projection. * AST__AIR * An integer identifier for the FITS AIR projection. * AST__CYP * An integer identifier for the FITS CYP projection. * AST__CAR * An integer identifier for the FITS CAR projection. * AST__MER * An integer identifier for the FITS MER projection. * AST__CEA * An integer identifier for the FITS CEA projection. * AST__COP * An integer identifier for the FITS COP projection. * AST__COD * An integer identifier for the FITS COD projection. * AST__COE * An integer identifier for the FITS COE projection. * AST__COO * An integer identifier for the FITS COO projection. * AST__BON * An integer identifier for the FITS BON projection. * AST__PCO * An integer identifier for the FITS PCO projection. * AST__GLS * A depracated integer identifier for the FITS SFL projection. * AST__SFL * An integer identifier for the FITS SFL projection. * AST__PAR * An integer identifier for the FITS PAR projection. * AST__AIT * An integer identifier for the FITS AIT projection. * AST__MOL * An integer identifier for the FITS MOL projection. * AST__CSC * An integer identifier for the FITS CSC projection. * AST__QSC * An integer identifier for the FITS QSC projection. * AST__TSC * An integer identifier for the FITS TSC projection * AST__HPX * An integer identifier for the FITS HPX projection. * AST__XPH * An integer identifier for the FITS XPH projection. * AST__TPN * An integer identifier for a "TAN with correction terms" projection. * AST__WCSBAD * An integer identifier for a "null" projection. * * Protected: * None. * Type Definitions: * Public: * AstWcsMap * WcsMap object type. * * Protected: * AstWcsMapVtab * WcsMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 15-Feb-1996 (DSB): * Original version. * 23-MAR-1996 (DSB): * Support for PointSets with more than 2 axes added. * 18-NOV-1996 (DSB): * Updated to include attributes, etc. * 26-SEP-1997 (DSB): * Included new protected function, astPrjDesc. * 11-FEB-2000 (DSB): * Replaced wcsmap component projp by pointers p and np. * 20-OCT-2002 (DSB): * Added astIsZenithal * 8-JAN-2003 (DSB): * Added protected astInitWcsMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "proj.h" /* Mark Calabretta's WCSLIB library header file */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ /* Max. number of parameters for a WCS projection */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__WCSMX 10 /* pi: 180 degrees in radians - from SLALIB file slamac.h. */ #define AST__DPI 3.1415926535897932384626433832795028841971693993751 /* pi/2: 90 degrees in radians - from SLALIB file slamac.h. */ #define AST__DPIBY2 1.5707963267948966192313216916397514420985846996876 /* pi/180: degrees to radians - from SLALIB file slamac.h. */ #define AST__DD2R 0.017453292519943295769236907684886127134428718885417 /* 180/pi: radians to degrees - from SLALIB file slamac.h. */ #define AST__DR2D 57.295779513082320876798154814105170332405472466564 /* Projection Types: (note, WCSBAD must be the last in this list) */ #define AST__AZP 1 #define AST__SZP 2 #define AST__TAN 3 #define AST__STG 4 #define AST__SIN 5 #define AST__ARC 6 #define AST__ZPN 7 #define AST__ZEA 8 #define AST__AIR 9 #define AST__CYP 10 #define AST__CEA 11 #define AST__CAR 12 #define AST__MER 13 #define AST__SFL 14 #define AST__PAR 15 #define AST__MOL 16 #define AST__AIT 17 #define AST__COP 18 #define AST__COE 19 #define AST__COD 20 #define AST__COO 21 #define AST__BON 22 #define AST__PCO 23 #define AST__TSC 24 #define AST__CSC 25 #define AST__QSC 26 #define AST__NCP 27 #define AST__GLS 28 #define AST__TPN 29 #define AST__HPX 30 #define AST__XPH 31 #define AST__WCSBAD 32 /* A bad projection type */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* WcsMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstWcsMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ int type; /* Projection type */ int wcsaxis[2]; /* Indices of lon and lat. axes */ double **p; /* Pointer to array of projection parameter arrays */ int *np; /* Pointer to array of projection parameter counts */ struct AstPrjPrm params; /* WCS structure holding projection parameters, etc. Defined in proj.h */ int fits_proj; /* Use as FITS-WCS projection? */ int tpn_tan; /* Include TAN projection in TPN transformation? */ } AstWcsMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstWcsMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (* GetNatLat)( AstWcsMap *, int * ); double (* GetNatLon)( AstWcsMap *, int * ); double (* GetPV)( AstWcsMap *, int, int, int * ); int (* GetWcsAxis)( AstWcsMap *, int, int * ); int (* GetWcsType)( AstWcsMap *, int * ); int (* GetPVMax)( AstWcsMap *, int, int * ); int (* TestPV)( AstWcsMap *, int, int, int * ); void (* ClearPV)( AstWcsMap *, int, int, int * ); void (* SetPV)( AstWcsMap *, int, int, double, int * ); int (* IsZenithal)( AstWcsMap *, int * ); int (* GetFITSProj)( AstWcsMap *, int * ); int (* TestFITSProj)( AstWcsMap *, int * ); void (* ClearFITSProj)( AstWcsMap *, int * ); void (* SetFITSProj)( AstWcsMap *, int, int * ); int (* GetTPNTan)( AstWcsMap *, int * ); int (* TestTPNTan)( AstWcsMap *, int * ); void (* ClearTPNTan)( AstWcsMap *, int * ); void (* SetTPNTan)( AstWcsMap *, int, int * ); } AstWcsMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstWcsMapGlobals { AstWcsMapVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstWcsMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(WcsMap) /* Check class membership */ astPROTO_ISA(WcsMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstWcsMap *astWcsMap_( int, int, int, int, const char *, int *, ...); #else AstWcsMap *astWcsMapId_( int, int, int, int, const char *, ... )__attribute__((format(printf,5,6))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstWcsMap *astInitWcsMap_( void *, size_t, int, AstWcsMapVtab *, const char *, int, int, int, int, int * ); /* Vtab initialiser. */ void astInitWcsMapVtab_( AstWcsMapVtab *, const char *, int * ); /* Loader. */ AstWcsMap *astLoadWcsMap_( void *, size_t, AstWcsMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitWcsMapGlobals_( AstWcsMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ const char *astWcsPrjDesc_( int, int * ); const char *astWcsPrjName_( int, int * ); double astGetNatLat_( AstWcsMap *, int * ); double astGetNatLon_( AstWcsMap *, int * ); double astGetPV_( AstWcsMap *, int, int, int * ); int astWcsPrjType_( const char *, int * ); int astGetWcsAxis_( AstWcsMap *, int, int * ); int astGetWcsType_( AstWcsMap *, int * ); int astGetPVMax_( AstWcsMap *, int, int * ); int astTestPV_( AstWcsMap *, int, int, int * ); int astIsZenithal_( AstWcsMap *, int * ); void astClearPV_( AstWcsMap *, int, int, int * ); void astSetPV_( AstWcsMap *, int, int, double, int * ); int astGetFITSProj_( AstWcsMap *, int * ); int astTestFITSProj_( AstWcsMap *, int * ); void astClearFITSProj_( AstWcsMap *, int * ); void astSetFITSProj_( AstWcsMap *, int, int * ); int astGetTPNTan_( AstWcsMap *, int * ); int astTestTPNTan_( AstWcsMap *, int * ); void astClearTPNTan_( AstWcsMap *, int * ); void astSetTPNTan_( AstWcsMap *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckWcsMap(this) astINVOKE_CHECK(WcsMap,this,0) #define astVerifyWcsMap(this) astINVOKE_CHECK(WcsMap,this,1) /* Test class membership. */ #define astIsAWcsMap(this) astINVOKE_ISA(WcsMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astWcsMap astINVOKE(F,astWcsMap_) #else #define astWcsMap astINVOKE(F,astWcsMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitWcsMap(mem,size,init,vtab,name,ncoord,type,lon,lat) \ astINVOKE(O,astInitWcsMap_(mem,size,init,vtab,name,ncoord,type,lon,lat,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitWcsMapVtab(vtab,name) astINVOKE(V,astInitWcsMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadWcsMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadWcsMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckWcsMap to validate WcsMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astWcsPrjType(ctype) astWcsPrjType_(ctype,STATUS_PTR) #define astWcsPrjName(type) astWcsPrjName_(type,STATUS_PTR) #define astWcsPrjDesc(type) astWcsPrjDesc_(type,STATUS_PTR) #define astClearPV(this,i,j) \ astINVOKE(V,astClearPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) #define astGetPV(this,i,j) \ astINVOKE(V,astGetPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) #define astSetPV(this,i,j,par) \ astINVOKE(V,astSetPV_(astCheckWcsMap(this),i,j,par,STATUS_PTR)) #define astTestPV(this,i,j) \ astINVOKE(V,astTestPV_(astCheckWcsMap(this),i,j,STATUS_PTR)) #define astClearFITSProj(this) \ astINVOKE(V,astClearFITSProj_(astCheckWcsMap(this),STATUS_PTR)) #define astGetFITSProj(this) \ astINVOKE(V,astGetFITSProj_(astCheckWcsMap(this),STATUS_PTR)) #define astSetFITSProj(this,value) \ astINVOKE(V,astSetFITSProj_(astCheckWcsMap(this),value,STATUS_PTR)) #define astTestFITSProj(this) \ astINVOKE(V,astTestFITSProj_(astCheckWcsMap(this),STATUS_PTR)) #define astClearTPNTan(this) \ astINVOKE(V,astClearTPNTan_(astCheckWcsMap(this),STATUS_PTR)) #define astGetTPNTan(this) \ astINVOKE(V,astGetTPNTan_(astCheckWcsMap(this),STATUS_PTR)) #define astSetTPNTan(this,value) \ astINVOKE(V,astSetTPNTan_(astCheckWcsMap(this),value,STATUS_PTR)) #define astTestTPNTan(this) \ astINVOKE(V,astTestTPNTan_(astCheckWcsMap(this),STATUS_PTR)) #define astGetWcsType(this) \ astINVOKE(V,astGetWcsType_(astCheckWcsMap(this),STATUS_PTR)) #define astGetPVMax(this,i) \ astINVOKE(V,astGetPVMax_(astCheckWcsMap(this),i,STATUS_PTR)) #define astGetNatLat(this) \ astINVOKE(V,astGetNatLat_(astCheckWcsMap(this),STATUS_PTR)) #define astGetNatLon(this) \ astINVOKE(V,astGetNatLon_(astCheckWcsMap(this),STATUS_PTR)) #define astGetWcsAxis(this,index) \ astINVOKE(V,astGetWcsAxis_(astCheckWcsMap(this),index,STATUS_PTR)) #define astIsZenithal(this) \ astINVOKE(V,astIsZenithal_(astCheckWcsMap(this),STATUS_PTR)) #endif #endif ast-8.3.0/specfluxframe.h0000664000175000017500000001512613004147321012251 00000000000000#if !defined( SPECFLUXFRAME_INCLUDED ) /* Include this file only once */ #define SPECFLUXFRAME_INCLUDED /* *+ * Name: * specfluxframe.h * Type: * C include file. * Purpose: * Define the interface to the SpecFluxFrame class. * Invocation: * #include "specfluxframe.h" * Description: * This include file defines the interface to the SpecFluxFrame class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * Inheritance: * The SpecFluxFrame class inherits from the Frame class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 8-DEC-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "cmpframe.h" /* Parent Frame class */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* SpecFluxFrame structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSpecFluxFrame { /* Attributes inherited from the parent class. */ AstCmpFrame cmpframe; /* Parent class structure */ } AstSpecFluxFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSpecFluxFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstCmpFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstSpecFluxFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstSpecFluxFrameGlobals { AstSpecFluxFrameVtab Class_Vtab; int Class_Init; char GetTitle_Buff[ 201 ]; } AstSpecFluxFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SpecFluxFrame) /* Check class membership */ astPROTO_ISA(SpecFluxFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSpecFluxFrame *astSpecFluxFrame_( void *, void *, const char *, int *, ...); #else AstSpecFluxFrame *astSpecFluxFrameId_( void *, void *, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSpecFluxFrame *astInitSpecFluxFrame_( void *, size_t, int, AstSpecFluxFrameVtab *, const char *, AstSpecFrame *, AstFluxFrame *, int * ); /* Vtab initialiser. */ void astInitSpecFluxFrameVtab_( AstSpecFluxFrameVtab *, const char *, int * ); /* Loader. */ AstSpecFluxFrame *astLoadSpecFluxFrame_( void *, size_t, AstSpecFluxFrameVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitSpecFluxFrameGlobals_( AstSpecFluxFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSpecFluxFrame(this) astINVOKE_CHECK(SpecFluxFrame,this,0) #define astVerifySpecFluxFrame(this) astINVOKE_CHECK(SpecFluxFrame,this,1) /* Test class membership. */ #define astIsASpecFluxFrame(this) astINVOKE_ISA(SpecFluxFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSpecFluxFrame astINVOKE(F,astSpecFluxFrame_) #else #define astSpecFluxFrame astINVOKE(F,astSpecFluxFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSpecFluxFrame(mem,size,init,vtab,name,frame1,frame2) \ astINVOKE(O,astInitSpecFluxFrame_(mem,size,init,vtab,name,astCheckSpecFrame(frame1),astCheckFluxFrame(frame2),STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSpecFluxFrameVtab(vtab,name) astINVOKE(V,astInitSpecFluxFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSpecFluxFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSpecFluxFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSpecFluxFrame to validate SpecFluxFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #endif ast-8.3.0/starabbrev.sty0000664000175000017500000002721312710127547012143 00000000000000% Shortcuts % --------- %% Handling angles \ifpdf \typeout{... Using standard SIunitx degrees} \else \sisetup{ math-degree=\HCode{°}, text-degree=\HCode{°}, text-arcminute=\HCode{′}, text-arcsecond=\HCode{′′} } \fi %% Symbol for degrees; \ifpdf \newcommand{\dgs}{\si{\degree}} \else \newcommand{\dgs}{\ifmmode \HCode{°} \else \HCode{°} \fi} \fi %% % arcminute symbol \newcommand{\arcm}{\si{\arcminute}} % arcsec symbol \newcommand{\arcsec}{\si{\arcsecond}} % hours symbol \newcommand{\hr}{\textsuperscript{h}} % minutes symbol \newcommand{\mn}{\textsuperscript{m}} % seconds symbol \newcommand{\rsec}{\textsuperscript{s}} % commands for ra and dec (These do not put the angle symbol over the % decimal. \newcommand{\dec}[1]{\ang[retain-explicit-plus]{#1}} \ifpdf \newcommand{\ra}[1]{% \ang[% math-degree=\textsuperscript{h}, math-arcminute=\textsuperscript{m}, math-arcsecond=\textsuperscript{s}, text-degree=\textsuperscript{h}, text-arcminute=\textsuperscript{m}, text-arcsecond=\textsuperscript{s}] {#1} } \else \newcommand{\ra}[1]{% \ifmmode \ang[% text-degree=\HCode{h}, math-degree=\HCode{h}, math-arcminute=\HCode{m}, math-arcsecond=\HCode{s}, text-arcminute=\HCode{m}, text-arcsecond=\HCode{s}, ]% {#1}% \else \ang[% text-degree=\textsuperscript{h}, text-arcminute=\textsuperscript{m}, text-arcsecond=\textsuperscript{s}] {#1} \fi } \fi %% Note that due to limitations in tex4ht, you need to use \sb for _ %% and \sp for ^ if the macro is defined before the \begin{document} %% command. % Typographical shortcuts \newcommand{\fcfbe}{\ensuremath{\mathrm{FCF\sb{beamequiv}}}} \newcommand{\fcfb}{\ensuremath{\mathrm{FCF\sb{beam}}}} \newcommand{\fcfa}{$\mathrm{FCF\sb{arcsec}}$} \newcommand{\fcfm}{$\mathrm{FCF\sb{match}}$} % Starlink Package name \newcommand{\starlink}{\href{http://www.starlink.ac.uk}{Starlink}} % Set up some common package names. \newcommand{\ccdpack}{\xref{\textsc{Ccdpack}}{sun139}{}} \newcommand{\convert}{\xref{\textsc{Convert}}{sun55}{}} \newcommand{\cupid}{\xref{\textsc{Cupid}}{sun255}{}} \newcommand{\datacube}{\xref{\textsc{Datacube}}{sun237}{}} \newcommand{\Figaro}{\xref{\textsc{Figaro}}{sun86}{}} \newcommand{\fluxes}{\xref{\textsc{Fluxes}}{sun213}{}} \newcommand{\gaia}{\xref{\textsc{Gaia}}{sun214}{}} \newcommand{\Kappa}{\xref{\textsc{Kappa}}{sun95}{}} \newcommand{\agi}{\xref{AGI}{sun48}{}} \newcommand{\ndf}{\xref{NDF}{sun33}{}} \newcommand{\surf}{\xref{\textsc{Surf}}{sun216}{}} \newcommand{\jcmtdr}{\xref{\textsc{JCMTdr}}{sun132}{}} \newcommand{\oracdr}{\href{http://www.oracdr.org/oracdr}{ORAC-DR}} \newcommand{\photom}{\xref{\textsc{Photom}}{sun45}{}} \newcommand{\picard}{\xref{\textsc{Picard}}{sun265}{}} \newcommand{\smurf}{\xref{\textsc{Smurf}}{sun258}{}} \newcommand{\splat}{\xref{\textsc{Splat}}{sun243}{}} \newcommand{\ssds}{\xref{\textsc{Starlink Standard Data Structures}}{sgp38}{}} \newcommand{\topcat}{\href{http://www.starlink.ac.uk/topcat}{\textsc{Topcat}}} % DR recipe names \newcommand{\drrecipe}[1]{\texttt{#1}} % Application tasks \newcommand{\task}[1]{\textsf{#1}} % ADAM parameters \newcommand{\param}[1]{\texttt{#1}} % Environment variables, filenames, URLs, and model names % These are the same at the moment but could be adjusted in one place. \newcommand{\envvar}[1]{\texttt{#1}} \newcommand{\file}[1]{\texttt{#1}} \newcommand{\model}[1]{\texttt{#1}} %\providecommand{\url}[1]{\texttt{#1}} % GAIA menu functions and buttons. Would like a bold texttt to mimic % their appearance in GAIA, but the founts are not in regular LaTeX. \newcommand{\gaiathing}[1]{\textbf{\textsf{#1}}} % SMURF tasks \newcommand{\calcnoise}{\xref{\task{calcnoise}}{sun258}{CALCNOISE}} \newcommand{\clean}{\xref{\task{sc2clean}}{sun258}{SC2CLEAN}} \newcommand{\concat}{\xref{\task{sc2concat}}{sun258}{SC2CONCAT}} \newcommand{\configmeld}{\xref{\task{configmeld}}{sun258}{CONFIGMELD}} \newcommand{\flatfield}{\xref{\task{flatfield}}{sun258}{FLATFIELD}} \newcommand{\jcmtstate}{\xref{\task{jcmtstate2cat}}{sun258}{JCMTSTATE2CAT}} \newcommand{\makemap}{\xref{\task{makemap}}{sun258}{MAKEMAP}} \newcommand{\skyloop}{\xref{\task{skyloop}}{sun258}{SKYLOOP}} \newcommand{\stackframes}{\xref{\task{stackframes}}{sun258}{STACKFRAMES}} % KAPPA \newcommand{\beamfit}{\xref{\task{beamfit}}{sun95}{BEAMFIT}} \newcommand{\block}{\xref{\task{block}}{sun95}{BLOCK}} \newcommand{\chpix}{\xref{\task{chpix}}{sun95}{CHPIX}} \newcommand{\cdiv}{\xref{\task{cdiv}}{sun95}{CDIV}} \newcommand{\cmult}{\xref{\task{cmult}}{sun95}{CMULT}} \newcommand{\compave}{\xref{\task{compave}}{sun95}{COMPAVE}} \newcommand{\configecho}{\xref{\task{configecho}}{sun95}{CONFIGECHO}} \newcommand{\fitslist}{\xref{\task{fitslist}}{sun95}{FITSLIST}} \newcommand{\fitsval}{\xref{\task{fitsval}}{sun95}{FITSVAL}} \newcommand{\gausmooth}{\xref{\task{gausmooth}}{sun95}{GAUSMOOTH}} \newcommand{\hislist}{\xref{\task{hislist}}{sun95}{HISLIST}} \newcommand{\histat}{\xref{\task{histat}}{sun95}{HISTAT}} \newcommand{\histogram}{\xref{\task{histogram}}{sun95}{HISTOGRAM}} \newcommand{\linplot}{\xref{\task{linplot}}{sun95}{LINPLOT}} \newcommand{\makesnr}{\xref{\task{makesnr}}{sun95}{MAKESNR}} \newcommand{\ndfcopy}{\xref{\task{ndfcopy}}{sun95}{NDFCOPY}} \newcommand{\ndftrace}{\xref{\task{ndftrace}}{sun95}{NDFTRACE}} \newcommand{\paste}{\xref{\task{paste}}{sun95}{PASTE}} \newcommand{\provshow}{\xref{\task{provshow}}{sun95}{PROVSHOW}} \newcommand{\showqual}{\xref{\task{showqual}}{sun95}{SHOWQUAL}} \newcommand{\setvar}{\xref{\task{setvar}}{sun95}{SETVAR}} \newcommand{\stats}{\xref{\task{stats}}{sun95}{STATS}} \newcommand{\sub}{\xref{\task{sub}}{sun95}{SUB}} \newcommand{\wcsattrib}{\xref{\task{wcsattrib}}{sun95}{WCSATTRIB}} \newcommand{\wcsframe}{\xref{\task{wcsframe}}{sun95}{WCSFRAME}} \newcommand{\wcsmosaic}{\xref{\task{wcsmosaic}}{sun95}{WCSMOSAIC}} % CCDPACK \newcommand{\makemos}{\xref{\task{makemos}}{sun139}{MAKEMOS}} % CUPID \newcommand{\findback}{\xref{\task{findback}}{sun255}{FINDBACK}} \newcommand{\findclumps}{\xref{\task{findclumps}}{sun255}{FINDCLUMPS}} % Misc \newcommand{\autophotom}{\xref{\task{autophotom}}{sun45}{AUTOPHOTOM}} \newcommand{\fitstondf}{\xref{\task{fits2ndf}}{sun55}{FITS2NDF}} \newcommand{\stardocs}[2]{\href{http://www.starlink.ac.uk/docs/#1#2.htx/#1#2.html}{\textbf{\uppercase{#1}/#2}}} % Documents \newcommand{\convertsun}{\xref{\textbf{SUN/55}}{sun55}{}} \newcommand{\cupidsun}{\xref{\textbf{SUN/255}}{sun255}{}} \newcommand{\gaiasun}{\xref{\textbf{SUN/214}}{sun214}{}} \newcommand{\hdstracesun}{\xref{\textbf{SUN/102}}{sun102}{}} \newcommand{\kappasun}{\xref{\textbf{SUN/95}}{sun95}{}} \newcommand{\oracdrsun}{\xref{\textbf{SUN/230}}{sun230}{}} \newcommand{\picardsun}{\stardocs{sun}{265}} \newcommand{\pipelinesun}{\xref{\textbf{SUN/264}}{sun264}{}} \newcommand{\smurfsun}{\xref{\textbf{SUN/258}}{sun258}{}} % Shorthand and HTML references for other Starlink tasks \providecommand{\CCDPACK}{\textsc{ccdpack}} \providecommand{\CCDPACKref}{\xref{\CCDPACK}{sun139}{}} \providecommand{\GAIA}{\textsc{gaia}} \providecommand{\GAIAref}{\xref{\GAIA}{sun214}{}} \providecommand{\HDSTRACE}{\textsc{hdstrace}} \providecommand{\HDSTRACEref}{\xref{\HDSTRACE}{sun102}{}} \providecommand{\KAPPA}{\textsc{kappa}} \providecommand{\CURSA}{\xref{\textsc{cursa}}{sun190}{}} \providecommand{\KAPPAref}{\xref{(SUN/95)}{sun95}{}} \providecommand{\SMURF}{\textsc{smurf}} \providecommand{\SMURFcook}{\xref{SC/21}{sc21}{}} \providecommand{\ADAMsgref}{\xref{SG/4}{sg4}{}} \providecommand{\ADAMsunref}{\xref{SUN/101}{sun101}{}} \providecommand{\astref}{\xref{SUN/211}{sun211}{}} \providecommand{\ndfref}{\xref{SUN/33}{sun33}{}} % Application tasks \providecommand{\task}[1]{\textsf{#1}} % SMURF tasks \providecommand{\badbolos}{\xref{\task{badbolos}}{sun258}{BADBOLOS}} \providecommand{\calcdark}{\xref{\task{calcdark}}{sun258}{CALCDARK}} \providecommand{\calcflat}{\xref{\task{calcflat}}{sun258}{CALCFLAT}} \providecommand{\calcnoise}{\xref{\task{calcnoise}}{sun258}{CALCNOISE}} \providecommand{\calcresp}{\xref{\task{calcresp}}{sun258}{CALCRESP}} \providecommand{\copyflat}{\xref{\task{copyflat}}{sun258}{COPYFLAT}} \providecommand{\dreamsolve}{\xref{\task{dreamsolve}}{sun258}{DREAMSOLVE}} \providecommand{\dreamweights}{\xref{\task{dreamweights}}{sun258}{DREAMWEIGHTS}} % ...use fitdd instead of fit1d because the 1 breaks the macro \providecommand{\fitdd}{\xref{\task{fit1d}}{sun258}{FIT1D}} \providecommand{\gsdtoacsis}{\xref{\task{gsd2acsis}}{sun258}{GSD2ACSIS}} \providecommand{\gsdshow}{\xref{\task{gsdshow}}{sun258}{GSDSHOW}} \providecommand{\smurfhelp}{\xref{\task{smurfhelp}}{sun258}{SMURFHELP}} \providecommand{\impaztec}{\xref{\task{impaztec}}{sun258}{IMPAZTEC}} \providecommand{\makecube}{\xref{\task{makecube}}{sun258}{MAKECUBE}} \providecommand{\rawunpress}{\xref{\task{rawunpress}}{sun258}{RAWUNPRESS}} \providecommand{\rawfixmeta}{\xref{\task{rawfixmeta}}{sun258}{RAWFIXMETA}} \providecommand{\sctwosim}{\xref{\task{sc2sim}}{sun258}{SC2SIM}} \providecommand{\sctwothreadtest}{\xref{\task{sc2threadtest}}{sun258}{SC2THREADTEST}} \providecommand{\scanfit}{\xref{\task{scanfit}}{sun258}{SCANFIT}} \providecommand{\skynoise}{\xref{\task{skynoise}}{sun258}{SKYNOISE}} \providecommand{\smurfcopy}{\xref{\task{smurfcopy}}{sun258}{SMURFCOPY}} \providecommand{\stackframes}{\xref{\task{stackframes}}{sun258}{STACKFRAMES}} \providecommand{\starecalc}{\xref{\task{starecalc}}{sun258}{STARECALC}} \providecommand{\timesort}{\xref{\task{timesort}}{sun258}{TIMESORT}} \providecommand{\unmakecube}{\xref{\task{unmakecube}}{sun258}{UNMAKECUBE}} \providecommand{\extinction}{\xref{\task{extinction}}{sun258}{EXTINCTION}} \providecommand{\flatfield}{\xref{\task{flatfield}}{sun258}{FLATFIELD}} \providecommand{\jcmtstate}{\xref{\task{jcmtstate2cat}}{sun258}{JCMTSTATE2CAT}} \providecommand{\dumpocscfg}{\xref{\task{dumpocscfg}}{sun258}{DUMPOCSCFG}} \providecommand{\makemap}{\xref{\task{makemap}}{sun258}{MAKEMAP}} \providecommand{\gettsys}{\xref{\task{gettsys}}{sun258}{GETTSYS}} \providecommand{\remsky}{\xref{\task{remsky}}{sun258}{REMSKY}} \providecommand{\clean}{\xref{\task{sc2clean}}{sun258}{SC2CLEAN}} \providecommand{\concat}{\xref{\task{sc2concat}}{sun258}{SC2CONCAT}} \providecommand{\fft}{\xref{\task{sc2fft}}{sun258}{SC2FFT}} \providecommand{\fts}{\xref{\task{sc2fts}}{sun258}{SC2FTS}} \providecommand{\rebin}{\texttt{rebin}} \providecommand{\iterate}{\texttt{iterate}} % Other tasks \providecommand{\makemos}{\xref{\task{makemos}}{sun139}{MAKEMOS}} \providecommand{\csub}{\xref{\task{csub}}{sun95}{CSUB}} \providecommand{\clinplot}{\xref{\task{clinplot}}{sun95}{CLINPLOT}} \providecommand{\mlinplot}{\xref{\task{mlinplot}}{sun95}{MLINPLOT}} \providecommand{\collapse}{\xref{\task{collapse}}{sun95}{COLLAPSE}} \providecommand{\fillbad}{\xref{\task{fillbad}}{sun95}{FILLBAD}} \providecommand{\fitsedit}{\xref{\task{fitsedit}}{sun95}{FITSEDIT}} \providecommand{\kapdiv}{\xref{\task{div}}{sun95}{DIV}} \providecommand{\ndfcopy}{\xref{\task{ndfcopy}}{sun95}{NDFCOPY}} \providecommand{\parget}{\xref{\task{parget}}{sun95}{PARGET}} \providecommand{\provshow}{\xref{\task{provshow}}{sun95}{PROVSHOW}} \providecommand{\thresh}{\xref{\task{thresh}}{sun95}{THRESH}} \providecommand{\wcsmosaic}{\xref{\task{wcsmosaic}}{sun95}{WCSMOSAIC}} \providecommand{\wcsalign}{\xref{\task{wcsalign}}{sun95}{WCSALIGN}} \providecommand{\wcsattrib}{\xref{\task{wcsattrib}}{sun95}{WCSATTRIB}} \providecommand{\fitslist}{\xref{\task{fitslist}}{sun95}{FITSLIST}} \providecommand{\display}{\xref{\task{display}}{sun95}{DISPLAY}} \providecommand{\ndfcompress}{\xref{\task{ndfcompress}}{sun95}{NDFCOMPRESS}} \providecommand{\topcat}{\xref{\textsc{Topcat}}{sun253}{}} % prevent issues if a pdf .aux file is still around \providecommand{\pgfsyspdfmark}[3]{} ast-8.3.0/wcstrig.c0000664000175000017500000001071513004147321011061 00000000000000/*============================================================================ * * WCSLIB - an implementation of the FITS WCS proposal. * Copyright (C) 1995-2002, Mark Calabretta * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published * by the Free Software Foundation; either version 2 of the License, or (at * your option) any later version. * * This library 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 Library * General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA * * Correspondence concerning WCSLIB may be directed to: * Internet email: mcalabre@atnf.csiro.au * Postal address: Dr. Mark Calabretta, * Australia Telescope National Facility, * P.O. Box 76, * Epping, NSW, 2121, * AUSTRALIA * *============================================================================= * * This version of wcstrig.c is based on the version in wcslib-2.9, but has * been modified in the following ways by the Starlink project (e-mail: * ussc@star.rl.ac.uk): * - Support for non-ANSI C "const" class removed * - Changed names of projection functions and degrees trig functions * to avoid clashes with wcslib. *============================================================================= * * The functions defined herein are trigonometric or inverse trigonometric * functions which take or return angular arguments in decimal degrees. * * $Id$ *---------------------------------------------------------------------------*/ #include #include "wcsmath.h" #include "wcstrig.h" double astCosd(angle) const double angle; { double resid; resid = fabs(fmod(angle,360.0)); if (resid == 0.0) { return 1.0; } else if (resid == 90.0) { return 0.0; } else if (resid == 180.0) { return -1.0; } else if (resid == 270.0) { return 0.0; } return cos(angle*D2R); } /*--------------------------------------------------------------------------*/ double astSind(angle) const double angle; { double resid; resid = fmod(angle-90.0,360.0); if (resid == 0.0) { return 1.0; } else if (resid == 90.0) { return 0.0; } else if (resid == 180.0) { return -1.0; } else if (resid == 270.0) { return 0.0; } return sin(angle*D2R); } /*--------------------------------------------------------------------------*/ double astTand(angle) const double angle; { double resid; resid = fmod(angle,360.0); if (resid == 0.0 || fabs(resid) == 180.0) { return 0.0; } else if (resid == 45.0 || resid == 225.0) { return 1.0; } else if (resid == -135.0 || resid == -315.0) { return -1.0; } return tan(angle*D2R); } /*--------------------------------------------------------------------------*/ double astACosd(v) const double v; { if (v >= 1.0) { if (v-1.0 < WCSTRIG_TOL) return 0.0; } else if (v == 0.0) { return 90.0; } else if (v <= -1.0) { if (v+1.0 > -WCSTRIG_TOL) return 180.0; } return acos(v)*R2D; } /*--------------------------------------------------------------------------*/ double astASind(v) const double v; { if (v <= -1.0) { if (v+1.0 > -WCSTRIG_TOL) return -90.0; } else if (v == 0.0) { return 0.0; } else if (v >= 1.0) { if (v-1.0 < WCSTRIG_TOL) return 90.0; } return asin(v)*R2D; } /*--------------------------------------------------------------------------*/ double astATand(v) const double v; { if (v == -1.0) { return -45.0; } else if (v == 0.0) { return 0.0; } else if (v == 1.0) { return 45.0; } return atan(v)*R2D; } /*--------------------------------------------------------------------------*/ double astATan2d(y, x) const double x, y; { if (y == 0.0) { if (x >= 0.0) { return 0.0; } else if (x < 0.0) { return 180.0; } } else if (x == 0.0) { if (y > 0.0) { return 90.0; } else if (y < 0.0) { return -90.0; } } return atan2(y,x)*R2D; } ast-8.3.0/timeframe.h0000664000175000017500000002660613004147321011363 00000000000000#if !defined( TIMEFRAME_INCLUDED ) /* Include this file only once */ #define TIMEFRAME_INCLUDED /* *+ * Name: * timeframe.h * Type: * C include file. * Purpose: * Define the interface to the TimeFrame class. * Invocation: * #include "timeframe.h" * Description: * This include file defines the interface to the TimeFrame class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 20-MAY-2005 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "frame.h" /* Parent Frame class */ #include "skyframe.h" /* Celestial coordinate systems */ /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* Values used to represent different System attribute values. */ #define AST__MJD 1 #define AST__JD 2 #define AST__JEPOCH 3 #define AST__BEPOCH 4 /* Values used to represent different TimeScale attribute values. */ #define AST__BADTS 0 #define AST__TAI 1 #define AST__UTC 2 #define AST__UT1 3 #define AST__GMST 4 #define AST__LAST 5 #define AST__LMST 6 #define AST__TT 7 #define AST__TDB 8 #define AST__TCB 9 #define AST__TCG 10 #define AST__LT 11 /* Define constants used to size global arrays in this module. */ #define AST__TIMEFRAME_FORMAT_BUFF_LEN 200 #define AST__TIMEFRAME_GETATTRIB_BUFF_LEN 50 #define AST__TIMEFRAME_GETLABEL_BUFF_LEN 200 #define AST__TIMEFRAME_GETSYMBOL_BUFF_LEN 20 #define AST__TIMEFRAME_GETTITLE_BUFF_LEN 200 #endif /* Type Definitions. */ /* ================= */ /* Integer type used to store the TimeScale attribute. */ typedef int AstTimeScaleType; /* TimeFrame structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstTimeFrame { /* Attributes inherited from the parent class. */ AstFrame frame; /* Parent class structure */ /* Attributes specific to objects in this class. */ double ltoffset; /* Offset from UTC to Local Time */ double timeorigin; /* Zero point for time axis */ AstTimeScaleType timescale; /* Time scale */ AstTimeScaleType aligntimescale; /* Alignment time scale */ } AstTimeFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstTimeFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (* CurrentTime)( AstTimeFrame *, int * ); double (* GetLTOffset)( AstTimeFrame *, int * ); int (* TestLTOffset)( AstTimeFrame *, int * ); void (* ClearLTOffset)( AstTimeFrame *, int * ); void (* SetLTOffset)( AstTimeFrame *, double, int * ); double (* GetTimeOrigin)( AstTimeFrame *, int * ); int (* TestTimeOrigin)( AstTimeFrame *, int * ); void (* ClearTimeOrigin)( AstTimeFrame *, int * ); void (* SetTimeOrigin)( AstTimeFrame *, double, int * ); AstTimeScaleType (* GetTimeScale)( AstTimeFrame *, int * ); int (* TestTimeScale)( AstTimeFrame *, int * ); void (* ClearTimeScale)( AstTimeFrame *, int * ); void (* SetTimeScale)( AstTimeFrame *, AstTimeScaleType, int * ); AstTimeScaleType (* GetAlignTimeScale)( AstTimeFrame *, int * ); int (* TestAlignTimeScale)( AstTimeFrame *, int * ); void (* ClearAlignTimeScale)( AstTimeFrame *, int * ); void (* SetAlignTimeScale)( AstTimeFrame *, AstTimeScaleType, int * ); } AstTimeFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstTimeFrameGlobals { AstTimeFrameVtab Class_Vtab; int Class_Init; char Format_Buff[ AST__TIMEFRAME_FORMAT_BUFF_LEN + 1 ]; char GetAttrib_Buff[ AST__TIMEFRAME_GETATTRIB_BUFF_LEN + 1 ]; char GetLabel_Buff[ AST__TIMEFRAME_GETLABEL_BUFF_LEN + 1 ]; char GetSymbol_Buff[ AST__TIMEFRAME_GETSYMBOL_BUFF_LEN + 1 ]; char GetTitle_Buff[ AST__TIMEFRAME_GETTITLE_BUFF_LEN + 1 ]; } AstTimeFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(TimeFrame) /* Check class membership */ astPROTO_ISA(TimeFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstTimeFrame *astTimeFrame_( const char *, int *, ...); #else AstTimeFrame *astTimeFrameId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstTimeFrame *astInitTimeFrame_( void *, size_t, int, AstTimeFrameVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitTimeFrameVtab_( AstTimeFrameVtab *, const char *, int * ); /* Loader. */ AstTimeFrame *astLoadTimeFrame_( void *, size_t, AstTimeFrameVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitTimeFrameGlobals_( AstTimeFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ double astCurrentTime_( AstTimeFrame *, int * ); #if defined(astCLASS) /* Protected */ double astGetLTOffset_( AstTimeFrame *, int * ); int astTestLTOffset_( AstTimeFrame *, int * ); void astClearLTOffset_( AstTimeFrame *, int * ); void astSetLTOffset_( AstTimeFrame *, double, int * ); double astGetTimeOrigin_( AstTimeFrame *, int * ); int astTestTimeOrigin_( AstTimeFrame *, int * ); void astClearTimeOrigin_( AstTimeFrame *, int * ); void astSetTimeOrigin_( AstTimeFrame *, double, int * ); AstTimeScaleType astGetTimeScale_( AstTimeFrame *, int * ); int astTestTimeScale_( AstTimeFrame *, int * ); void astClearTimeScale_( AstTimeFrame *, int * ); void astSetTimeScale_( AstTimeFrame *, AstTimeScaleType, int * ); AstTimeScaleType astGetAlignTimeScale_( AstTimeFrame *, int * ); int astTestAlignTimeScale_( AstTimeFrame *, int * ); void astClearAlignTimeScale_( AstTimeFrame *, int * ); void astSetAlignTimeScale_( AstTimeFrame *, AstTimeScaleType, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckTimeFrame(this) astINVOKE_CHECK(TimeFrame,this,0) #define astVerifyTimeFrame(this) astINVOKE_CHECK(TimeFrame,this,1) /* Test class membership. */ #define astIsATimeFrame(this) astINVOKE_ISA(TimeFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astTimeFrame astINVOKE(F,astTimeFrame_) #else #define astTimeFrame astINVOKE(F,astTimeFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitTimeFrame(mem,size,init,vtab,name) \ astINVOKE(O,astInitTimeFrame_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitTimeFrameVtab(vtab,name) astINVOKE(V,astInitTimeFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadTimeFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadTimeFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* None. */ /* Interfaces to protected member functions. */ /* ----------------------------------------- */ /* Here we make use of astCheckTimeFrame to validate TimeFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #define astCurrentTime(this) astINVOKE(V,astCurrentTime_(astCheckTimeFrame(this),STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astGetTimeOrigin(this) astINVOKE(V,astGetTimeOrigin_(astCheckTimeFrame(this),STATUS_PTR)) #define astTestTimeOrigin(this) astINVOKE(V,astTestTimeOrigin_(astCheckTimeFrame(this),STATUS_PTR)) #define astClearTimeOrigin(this) astINVOKE(V,astClearTimeOrigin_(astCheckTimeFrame(this),STATUS_PTR)) #define astSetTimeOrigin(this,value) astINVOKE(V,astSetTimeOrigin_(astCheckTimeFrame(this),value,STATUS_PTR)) #define astGetLTOffset(this) astINVOKE(V,astGetLTOffset_(astCheckTimeFrame(this),STATUS_PTR)) #define astTestLTOffset(this) astINVOKE(V,astTestLTOffset_(astCheckTimeFrame(this),STATUS_PTR)) #define astClearLTOffset(this) astINVOKE(V,astClearLTOffset_(astCheckTimeFrame(this),STATUS_PTR)) #define astSetLTOffset(this,value) astINVOKE(V,astSetLTOffset_(astCheckTimeFrame(this),value,STATUS_PTR)) #define astGetTimeScale(this) astINVOKE(V,astGetTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astTestTimeScale(this) astINVOKE(V,astTestTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astClearTimeScale(this) astINVOKE(V,astClearTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astSetTimeScale(this,value) astINVOKE(V,astSetTimeScale_(astCheckTimeFrame(this),value,STATUS_PTR)) #define astGetAlignTimeScale(this) astINVOKE(V,astGetAlignTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astTestAlignTimeScale(this) astINVOKE(V,astTestAlignTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astClearAlignTimeScale(this) astINVOKE(V,astClearAlignTimeScale_(astCheckTimeFrame(this),STATUS_PTR)) #define astSetAlignTimeScale(this,value) astINVOKE(V,astSetAlignTimeScale_(astCheckTimeFrame(this),value,STATUS_PTR)) #endif #endif ast-8.3.0/fzoommap.c0000664000175000017500000000617613004147321011235 00000000000000/* *+ * Name: * fzoommap.c * Purpose: * Define a FORTRAN 77 interface to the AST ZoomMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the ZoomMap class. * Routines Defined: * AST_ISAZOOMMAP * AST_ZOOMMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 18-JUL-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "zoommap.h" /* C interface to the ZoomMap class */ F77_LOGICAL_FUNCTION(ast_isazoommap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAZOOMMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAZoomMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_zoommap)( INTEGER(NAXES), DOUBLE(ZOOM), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NAXES) GENPTR_DOUBLE(ZOOM) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_ZOOMMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astZoomMap( *NAXES, *ZOOM, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/fslamap.c0000664000175000017500000000703013004147321011016 00000000000000/* *+ * Name: * fslamap.c * Purpose: * Define a FORTRAN 77 interface to the AST SlaMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the SlaMap class. * Routines Defined: * AST_ISASLAMAP * AST_SLAADD * AST_SLAMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 28-MAY-1997 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "slamap.h" /* C interface to the SlaMap class */ F77_LOGICAL_FUNCTION(ast_isaslamap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASLAMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsASlaMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_SUBROUTINE(ast_slaadd)( INTEGER(THIS), CHARACTER(CVT), DOUBLE_ARRAY(ARGS), INTEGER(STATUS) TRAIL(CVT) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(CVT) GENPTR_DOUBLE_ARRAY(ARGS) char *cvt; astAt( "AST_SLAADD", NULL, 0 ); astWatchSTATUS( cvt = astString( CVT, CVT_length ); astSlaAdd( astI2P( *THIS ), cvt, ARGS ); astFree( cvt ); ) } F77_INTEGER_FUNCTION(ast_slamap)( INTEGER(FLAGS), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FLAGS) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_SLAMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astSlaMap( *FLAGS, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/mathmap.h0000664000175000017500000003413113004147321011031 00000000000000#if !defined( MATHMAP_INCLUDED ) /* Include this file only once */ #define MATHMAP_INCLUDED /* *+ * Name: * mathmap.h * Type: * C include file. * Purpose: * Define the interface to the MathMap class. * Invocation: * #include "mathmap.h" * Description: * This include file defines the interface to the MathMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The MathMap class implements Mappings that are specified by a series * of arithmetic expressions that relate output variables to input * variables (and vice versa). * Inheritance: * The MathMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Seed * Random number seed. * SimpFI * Forward-inverse MathMap pairs simplify? * SimpIF * Inverse-forward MathMap pairs simplify? * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a Frame. * astGetAttrib * Get an attribute value for a Frame. * astMapMerge * Simplify a sequence of Mappings containing a MathMap. * astSetAttrib * Set an attribute value for a Frame. * astTestAttrib * Test if an attribute value has been set for a Frame. * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astClearSeed * Clear the Seed attribute for a MathMap. * astClearSimpFI * Clear the SimpFI attribute for a MathMap. * astClearSimpIF * Clear the SimpIF attribute for a MathMap. * astGetSeed * Get the value of the Seed attribute for a MathMap. * astGetSimpFI * Get the value of the SimpFI attribute for a MathMap. * astGetSimpIF * Get the value of the SimpIF attribute for a MathMap. * astSetSeed * Set the value of the Seed attribute for a MathMap. * astSetSimpFI * Set the value of the SimpFI attribute for a MathMap. * astSetSimpIF * Set the value of the SimpIF attribute for a MathMap. * astTestSeed * Test whether a value has been set for the Seed attribute of a * MathMap. * astTestSimpFI * Test whether a value has been set for the SimpFI attribute of a * MathMap. * astTestSimpIF * Test whether a value has been set for the SimpIF attribute of a * MathMap. * Other Class Functions: * Public: * astIsAMathMap * Test class membership. * astMathMap * Create a MathMap. * * Protected: * astCheckMathMap * Validate class membership. * astInitMathMap * Initialise a MathMap. * astInitMathMapVtab * Initialise the virtual function table for the MathMap class. * astLoadMathMap * Load a MathMap. * Macros: * None. * Type Definitions: * Public: * AstMathMap * MathMap object type. * * Protected: * AstMathMapVtab * MathMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 3-SEP-1999 (RFWS): * Original version. * 8-JAN-2003 (DSB): * Added protected astInitMathMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #include "pointset.h" /* Sets of points/coordinates */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ======= */ /* This value defines the size of an internal table in the AstMathMap data type. Since it will be publicly accessible (but of no external use), we give it an obscure name. */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST_MATHMAP_RAND_CONTEXT_NTAB_ (32) /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* Random number generator context. */ /* -------------------------------- */ /* This structure holds the context for the random number generator used by each MathMap. This ensures that the random number sequences used by different MathMaps are independent, and can be independently controlled by setting/clearing their Seed attributes. Random numbers are produced by combining the output of two internal generators. */ typedef struct AstMathMapRandContext_ { long int rand1; /* State of first internal generator */ long int rand2; /* State of second internal generator */ long int random_int; /* Last random integer produced */ long int table[ AST_MATHMAP_RAND_CONTEXT_NTAB_ ]; /* Shuffle table */ int active; /* Generator has been initialised? */ int seed; /* Seed to be used during initialisation */ int seed_set; /* Seed value set via "Seed" attribute? */ } AstMathMapRandContext_; /* MathMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstMathMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstMathMapRandContext_ rcontext; /* Random number generator context */ char **fwdfun; /* Array of forward functions */ char **invfun; /* Array of inverse functions */ double **fwdcon; /* Array of constants for forward functions */ double **invcon; /* Array of constants for inverse functions */ int **fwdcode; /* Array of opcodes for forward functions */ int **invcode; /* Array of opcodes for inverse functions */ int fwdstack; /* Stack size required by forward functions */ int invstack; /* Stack size required by inverse functions */ int nfwd; /* Number of forward functions */ int ninv; /* Number of inverse functions */ int simp_fi; /* Forward-inverse MathMap pairs simplify? */ int simp_if; /* Inverse-forward MathMap pairs simplify? */ } AstMathMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstMathMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetSeed)( AstMathMap *, int * ); int (* GetSimpFI)( AstMathMap *, int * ); int (* GetSimpIF)( AstMathMap *, int * ); int (* TestSeed)( AstMathMap *, int * ); int (* TestSimpFI)( AstMathMap *, int * ); int (* TestSimpIF)( AstMathMap *, int * ); void (* ClearSeed)( AstMathMap *, int * ); void (* ClearSimpFI)( AstMathMap *, int * ); void (* ClearSimpIF)( AstMathMap *, int * ); void (* SetSeed)( AstMathMap *, int, int * ); void (* SetSimpFI)( AstMathMap *, int, int * ); void (* SetSimpIF)( AstMathMap *, int, int * ); } AstMathMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstMathMapGlobals { AstMathMapVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 51 ]; } AstMathMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(MathMap) /* Check class membership */ astPROTO_ISA(MathMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstMathMap *astMathMap_( int, int, int, const char *[], int, const char *[], const char *, int *, ...); #else AstMathMap *astMathMapId_( int, int, int, const char *[], int, const char *[], const char *, ... )__attribute__((format(printf,7,8))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstMathMap *astInitMathMap_( void *, size_t, int, AstMathMapVtab *, const char *, int, int, int, const char *[], int, const char *[], int * ); /* Vtab initialiser. */ void astInitMathMapVtab_( AstMathMapVtab *, const char *, int * ); /* Loader. */ AstMathMap *astLoadMathMap_( void *, size_t, AstMathMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitMathMapGlobals_( AstMathMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ int astGetSeed_( AstMathMap *, int * ); int astGetSimpFI_( AstMathMap *, int * ); int astGetSimpIF_( AstMathMap *, int * ); int astTestSeed_( AstMathMap *, int * ); int astTestSimpFI_( AstMathMap *, int * ); int astTestSimpIF_( AstMathMap *, int * ); void astClearSeed_( AstMathMap *, int * ); void astClearSimpFI_( AstMathMap *, int * ); void astClearSimpIF_( AstMathMap *, int * ); void astSetSeed_( AstMathMap *, int, int * ); void astSetSimpFI_( AstMathMap *, int, int * ); void astSetSimpIF_( AstMathMap *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckMathMap(this) astINVOKE_CHECK(MathMap,this,0) #define astVerifyMathMap(this) astINVOKE_CHECK(MathMap,this,1) /* Test class membership. */ #define astIsAMathMap(this) astINVOKE_ISA(MathMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astMathMap astINVOKE(F,astMathMap_) #else #define astMathMap astINVOKE(F,astMathMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitMathMap(mem,size,init,vtab,name,nin,nout,nfwd,fwd,ninv,inv) \ astINVOKE(O,astInitMathMap_(mem,size,init,vtab,name,nin,nout,nfwd,fwd,ninv,inv,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitMathMapVtab(vtab,name) astINVOKE(V,astInitMathMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadMathMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadMathMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckMathMap to validate MathMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearSeed(this) \ astINVOKE(V,astClearSeed_(astCheckMathMap(this),STATUS_PTR)) #define astClearSimpFI(this) \ astINVOKE(V,astClearSimpFI_(astCheckMathMap(this),STATUS_PTR)) #define astClearSimpIF(this) \ astINVOKE(V,astClearSimpIF_(astCheckMathMap(this),STATUS_PTR)) #define astGetSeed(this) \ astINVOKE(V,astGetSeed_(astCheckMathMap(this),STATUS_PTR)) #define astGetSimpFI(this) \ astINVOKE(V,astGetSimpFI_(astCheckMathMap(this),STATUS_PTR)) #define astGetSimpIF(this) \ astINVOKE(V,astGetSimpIF_(astCheckMathMap(this),STATUS_PTR)) #define astSetSeed(this,value) \ astINVOKE(V,astSetSeed_(astCheckMathMap(this),value,STATUS_PTR)) #define astSetSimpFI(this,value) \ astINVOKE(V,astSetSimpFI_(astCheckMathMap(this),value,STATUS_PTR)) #define astSetSimpIF(this,value) \ astINVOKE(V,astSetSimpIF_(astCheckMathMap(this),value,STATUS_PTR)) #define astTestSeed(this) \ astINVOKE(V,astTestSeed_(astCheckMathMap(this),STATUS_PTR)) #define astTestSimpFI(this) \ astINVOKE(V,astTestSimpFI_(astCheckMathMap(this),STATUS_PTR)) #define astTestSimpIF(this) \ astINVOKE(V,astTestSimpIF_(astCheckMathMap(this),STATUS_PTR)) #endif #endif ast-8.3.0/fplot.c0000664000175000017500000005414713004147321010532 00000000000000/* *+ * Name: * fplot.c * Purpose: * Define a FORTRAN 77 interface to the AST Plot class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Plot class. * Routines Defined: * AST_BORDER * AST_BOUNDINGBOX * AST_CLIP * AST_CURVE * AST_GENCURVE * AST_GRID * AST_GRIDLINE * AST_ISAPLOT * AST_MARK * AST_PLOT * AST_POLYCURVE * AST_REGIONOUTLINE * AST_TEXT * AST_GRFSET * AST_GRFPUSH * AST_GRFPOP * AST_STRIPESCAPES * AST_GETGRFCONTEXT * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2007 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 23-OCT-1996 (DSB): * Original version. * 14-NOV-1996 (DSB): * Method names shortened. CrvBreak removed. * 21-NOV-1996 (DSB): * Method names changed, CLIP argument NBND removed. * 18-DEC-1996 (DSB): * Argument UP changed to single precision and NCOORD removed * in AST_TEXT. * 11-AUG-1998 (DSB): * Added AST_POLYCURVE. * 9-JAN-2001 (DSB): * Change argument "in" for astMark and astPolyCurve from type * "const double (*)[]" to "const double *". * 13-JUN-2001 (DSB): * Modified to add support for astGenCurve, astGrfSet, astGrfPop, * astGrfPush and EXTERNAL grf functions. * 14-AUG-2002 (DSB): * Added AST_BOUNDINGBOX. * 8-JAN-2003 (DSB): * Include "string.h". * 10-JUL-2006 (DSB): * Add AST_STRIPESCAPES * 21-JUN-2007 (DSB): * - Avoid use of protected astGetGrfContext function. * - Change data type of GrfContext from integer to AST Object pointer. * 29-JUN-2007 (DSB): * Added astGetGrfCOntext and removed astSetGrfContext. * 30-AUG-2007 (DSB): * Use astGrfConID to get the identifier for the graphics context * KeyMap. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 #define MXSTRLEN 80 /* String length at which truncation starts within pgqtxt and pgptxt. */ /* Header files. */ /* ============= */ #include "string.h" #include "ast_err.h" /* AST error codes */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "plot.h" /* C interface to the Plot class */ #include "grf.h" /* Low-level graphics interface */ /* Prototypes for external functions. */ /* ================================== */ /* This is the null function defined by the FORTRAN interface in fobject.c. */ F77_SUBROUTINE(ast_null)( void ); static int FGAttrWrapper( AstPlot *, int, double, double *, int ); static int FGBBufWrapper( AstPlot * ); static int FGEBufWrapper( AstPlot * ); static int FGFlushWrapper( AstPlot * ); static int FGLineWrapper( AstPlot *, int, const float *, const float * ); static int FGMarkWrapper( AstPlot *, int, const float *, const float *, int ); static int FGTextWrapper( AstPlot *, const char *, float, float, const char *, float, float ); static int FGTxExtWrapper( AstPlot *, const char *, float, float, const char *, float, float, float *, float * ); static int FGCapWrapper( AstPlot *, int, int ); static int FGQchWrapper( AstPlot *, float *, float * ); static int FGScalesWrapper( AstPlot *, float *, float * ); F77_LOGICAL_FUNCTION(ast_isaplot)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPLOT", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPlot( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_plot)( INTEGER(FRAME), REAL_ARRAY(GRAPHBOX), DOUBLE_ARRAY(BASEBOX), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_REAL_ARRAY(GRAPHBOX) GENPTR_DOUBLE_ARRAY(BASEBOX) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_PLOT", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPlot( astI2P( *FRAME ), GRAPHBOX, BASEBOX, "%s", options ) ); astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_border)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_BORDER", NULL, 0 ); astWatchSTATUS( RESULT = astBorder( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_SUBROUTINE(ast_boundingbox)( INTEGER(THIS), REAL_ARRAY(LBND), REAL_ARRAY(UBND), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) GENPTR_REAL_ARRAY(LBND) GENPTR_REAL_ARRAY(UBND) astAt( "AST_BOUNDINGBOX", NULL, 0 ); astWatchSTATUS( astBoundingBox( astI2P( *THIS ), LBND, UBND ); ) } F77_SUBROUTINE(ast_clip)( INTEGER(THIS), INTEGER(IFRAME), DOUBLE_ARRAY(LBND), DOUBLE_ARRAY(UBND), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) GENPTR_INTEGER(IFRAME) GENPTR_DOUBLE_ARRAY(LBND) GENPTR_DOUBLE_ARRAY(UBND) astAt( "AST_CLIP", NULL, 0 ); astWatchSTATUS( astClip( astI2P( *THIS ), *IFRAME, LBND, UBND ); ) } F77_SUBROUTINE(ast_gridline)( INTEGER(THIS), INTEGER(AXIS), DOUBLE_ARRAY(START), DOUBLE(LENGTH), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_DOUBLE_ARRAY(START) GENPTR_DOUBLE(LENGTH) astAt( "AST_GRIDLINE", NULL, 0 ); astWatchSTATUS( astGridLine( astI2P( *THIS ), *AXIS, START, *LENGTH ); ) } F77_SUBROUTINE(ast_curve)( INTEGER(THIS), DOUBLE_ARRAY(START), DOUBLE_ARRAY(FINISH), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(START) GENPTR_DOUBLE_ARRAY(FINISH) astAt( "AST_CURVE", NULL, 0 ); astWatchSTATUS( astCurve( astI2P( *THIS ), START, FINISH ); ) } F77_SUBROUTINE(ast_grid)( INTEGER(THIS), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) astAt( "AST_GRID", NULL, 0 ); astWatchSTATUS( astGrid( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_mark)( INTEGER(THIS), INTEGER(NMARK), INTEGER(NCOORD), INTEGER(INDIM), DOUBLE_ARRAY(IN), INTEGER(TYPE), INTEGER(STATUS) ){ GENPTR_INTEGER(THIS) GENPTR_INTEGER(NMARK) GENPTR_INTEGER(NCOORD) GENPTR_INTEGER(INDIM) GENPTR_DOUBLE_ARRAY(IN) GENPTR_INTEGER(TYPE) astAt( "AST_MARK", NULL, 0 ); astWatchSTATUS( astMark( astI2P( *THIS ), *NMARK, *NCOORD, *INDIM, (const double *)IN, *TYPE ); ) } F77_SUBROUTINE(ast_polycurve)( INTEGER(THIS), INTEGER(NPOINT), INTEGER(NCOORD), INTEGER(INDIM), DOUBLE_ARRAY(IN), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NPOINT) GENPTR_INTEGER(NCOORD) GENPTR_INTEGER(INDIM) GENPTR_DOUBLE_ARRAY(IN) astAt( "AST_POLYCURVE", NULL, 0 ); astWatchSTATUS( astPolyCurve( astI2P( *THIS ), *NPOINT, *NCOORD, *INDIM, (const double *)IN ); ) } F77_SUBROUTINE(ast_regionoutline)( INTEGER(THIS), INTEGER(REGION), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(REGION) astAt( "AST_REGIONOUTLINE", NULL, 0 ); astWatchSTATUS( astRegionOutline( astI2P( *THIS ), astI2P( *REGION ) ); ) } F77_SUBROUTINE(ast_gencurve)( INTEGER(THIS), INTEGER(MAP), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(MAP) astAt( "AST_GENCURVE", NULL, 0 ); astWatchSTATUS( astGenCurve( astI2P( *THIS ), astI2P( *MAP ) ); ) } F77_SUBROUTINE(ast_text)( INTEGER(THIS), CHARACTER(TEXT), DOUBLE_ARRAY(POS), REAL_ARRAY(UP), CHARACTER(JUST), INTEGER(STATUS) TRAIL(TEXT) TRAIL(JUST) ){ GENPTR_INTEGER(THIS) GENPTR_CHARACTER(TEXT) GENPTR_DOUBLE_ARRAY(POS) GENPTR_REAL_ARRAY(UP) GENPTR_CHARACTER(JUST) char *text, *just; astAt( "AST_TEXT", NULL, 0 ); astWatchSTATUS( text = astString( TEXT, TEXT_length ); just = astString( JUST, JUST_length ); astText( astI2P( *THIS ), text, POS, UP, just ); (void) astFree( (void *) text ); (void) astFree( (void *) just ); ) } F77_SUBROUTINE(ast_grfpush)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_GRFPUSH", NULL, 0 ); astWatchSTATUS( astGrfPush( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_grfpop)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_GRFPOP", NULL, 0 ); astWatchSTATUS( astGrfPop( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_bbuf)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_BBUF", NULL, 0 ); astWatchSTATUS( astBBuf( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_ebuf)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_EBUF", NULL, 0 ); astWatchSTATUS( astEBuf( astI2P( *THIS ) ); ) } F77_SUBROUTINE(ast_grfset)( INTEGER(THIS), CHARACTER(NAME), AstGrfFun FUN, INTEGER(STATUS) TRAIL(NAME) ) { GENPTR_INTEGER(THIS) GENPTR_CHARACTER(NAME) char *name; AstGrfFun fun; const char *class; /* Object class */ const char *method; /* Current method */ int ifun; /* Index into grf function list */ AstGrfWrap wrapper; /* Wrapper function for C Grf routine*/ method = "AST_GRFSET"; class = "Plot"; astAt( method, NULL, 0 ); astWatchSTATUS( /* Set the function pointer to NULL if a pointer to the null routine AST_NULL has been supplied. */ fun = FUN; if ( fun == (AstGrfFun) F77_EXTERNAL_NAME(ast_null) ) { fun = NULL; } name = astString( NAME, NAME_length ); astGrfSet( astI2P( *THIS ), name, fun ); ifun = astGrfFunID( name, method, class ); if( ifun == AST__GATTR ) { wrapper = (AstGrfWrap) FGAttrWrapper; } else if( ifun == AST__GBBUF ) { wrapper = (AstGrfWrap) FGBBufWrapper; } else if( ifun == AST__GEBUF ) { wrapper = (AstGrfWrap) FGEBufWrapper; } else if( ifun == AST__GFLUSH ) { wrapper = (AstGrfWrap) FGFlushWrapper; } else if( ifun == AST__GLINE ) { wrapper = (AstGrfWrap) FGLineWrapper; } else if( ifun == AST__GMARK ) { wrapper = (AstGrfWrap) FGMarkWrapper; } else if( ifun == AST__GTEXT ) { wrapper = (AstGrfWrap) FGTextWrapper; } else if( ifun == AST__GCAP ) { wrapper = (AstGrfWrap) FGCapWrapper; } else if( ifun == AST__GTXEXT ) { wrapper = (AstGrfWrap) FGTxExtWrapper; } else if( ifun == AST__GQCH ) { wrapper = (AstGrfWrap) FGQchWrapper; } else if( ifun == AST__GSCALES ) { wrapper = (AstGrfWrap) FGScalesWrapper; } else { wrapper = (AstGrfWrap) FGFlushWrapper; if( astOK ) astError( AST__INTER, "%s(%s): AST internal programming " "error - Grf function id %d not yet supported.", status, method, class, ifun ); } astGrfWrapper( astI2P( *THIS ), name, wrapper ); ) } static int FGAttrWrapper( AstPlot *this, int attr, double value, double *old_value, int prim ) { DECLARE_DOUBLE(OLDVAL); int ret; F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); ret = ( *(int (*)( INTEGER(grfcon), INTEGER(attr), DOUBLE(value), DOUBLE(old_value), INTEGER(prim) )) this->grffun[ AST__GATTR ])( INTEGER_ARG(&GRFCON), INTEGER_ARG(&attr), DOUBLE_ARG(&value), DOUBLE_ARG(&OLDVAL), INTEGER_ARG(&prim) ); if( old_value ) *old_value = OLDVAL; return ret; } static int FGBBufWrapper( AstPlot *this ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)(INTEGER(grfcon))) this->grffun[ AST__GBBUF ])(INTEGER_ARG(&GRFCON)); } static int FGEBufWrapper( AstPlot *this ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)(INTEGER(grfcon))) this->grffun[ AST__GEBUF ])(INTEGER_ARG(&GRFCON)); } static int FGFlushWrapper( AstPlot *this ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)(INTEGER(grfcon))) this->grffun[ AST__GFLUSH ])(INTEGER_ARG(&GRFCON)); } static int FGLineWrapper( AstPlot *this, int n, const float *x, const float *y ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)( INTEGER(grfcon), INTEGER(n), REAL_ARRAY(x), REAL_ARRAY(y) )) this->grffun[ AST__GLINE ])( INTEGER_ARG(&GRFCON), INTEGER_ARG(&n), REAL_ARRAY_ARG(x), REAL_ARRAY_ARG(y) ); } static int FGMarkWrapper( AstPlot *this, int n, const float *x, const float *y, int type ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)( INTEGER(grfcon), INTEGER(n), REAL_ARRAY(x), REAL_ARRAY(y), INTEGER(type) )) this->grffun[ AST__GMARK ])( INTEGER_ARG(&GRFCON), INTEGER_ARG(&n), REAL_ARRAY_ARG(x), REAL_ARRAY_ARG(y), INTEGER_ARG(&type) ); } static int FGTextWrapper( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy ) { DECLARE_CHARACTER(LTEXT,MXSTRLEN); DECLARE_CHARACTER(LJUST,MXSTRLEN); int ftext_length; int fjust_length; F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); ftext_length = strlen( text ); if( ftext_length > LTEXT_length ) ftext_length = LTEXT_length; astStringExport( text, LTEXT, ftext_length ); fjust_length = strlen( just ); if( fjust_length > LJUST_length ) fjust_length = LJUST_length; astStringExport( just, LJUST, fjust_length ); return ( *(int (*)( INTEGER(grfcon), CHARACTER(LTEXT), REAL(x), REAL(y), CHARACTER(LJUST), REAL(upx), REAL(upy) TRAIL(ftext) TRAIL(fjust) ) ) this->grffun[ AST__GTEXT ])( INTEGER_ARG(&GRFCON), CHARACTER_ARG(LTEXT), REAL_ARG(&x), REAL_ARG(&y), CHARACTER_ARG(LJUST), REAL_ARG(&upx), REAL_ARG(&upy) TRAIL_ARG(ftext) TRAIL_ARG(fjust) ); } static int FGCapWrapper( AstPlot *this, int cap, int value ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)( INTEGER(grfcon), INTEGER(cap), INTEGER(value) ) ) this->grffun[ AST__GCAP ])( INTEGER_ARG(&GRFCON), INTEGER_ARG(&cap), INTEGER_ARG(&value) ); } static int FGTxExtWrapper( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb ) { DECLARE_CHARACTER(LTEXT,MXSTRLEN); DECLARE_CHARACTER(LJUST,MXSTRLEN); int ftext_length; int fjust_length; F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); ftext_length = strlen( text ); if( ftext_length > LTEXT_length ) ftext_length = LTEXT_length; astStringExport( text, LTEXT, ftext_length ); fjust_length = strlen( just ); if( fjust_length > LJUST_length ) fjust_length = LJUST_length; astStringExport( just, LJUST, fjust_length ); return ( *(int (*)( INTEGER(grfcon), CHARACTER(LTEXT), REAL(x), REAL(y), CHARACTER(LJUST), REAL(upx), REAL(upy), REAL_ARRAY(xb), REAL_ARRAY(yb) TRAIL(ftext) TRAIL(fjust) ) ) this->grffun[ AST__GTXEXT ])( INTEGER_ARG(&GRFCON), CHARACTER_ARG(LTEXT), REAL_ARG(&x), REAL_ARG(&y), CHARACTER_ARG(LJUST), REAL_ARG(&upx), REAL_ARG(&upy), REAL_ARRAY_ARG(xb), REAL_ARRAY_ARG(yb) TRAIL_ARG(ftext) TRAIL_ARG(fjust) ); } static int FGQchWrapper( AstPlot *this, float *chv, float *chh ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)( INTEGER(grfcon), REAL(chv), REAL(chh) ) ) this->grffun[ AST__GQCH ])( INTEGER_ARG(&GRFCON), REAL_ARG(chv), REAL_ARG(chh) ); } static int FGScalesWrapper( AstPlot *this, float *alpha, float *beta ) { F77_INTEGER_TYPE(GRFCON); int *status = astGetStatusPtr; if ( !astOK ) return 0; GRFCON = astP2I( astGrfConID( this ) ); return ( *(int (*)( INTEGER(grfcon), REAL(alpha), REAL(beta) ) ) this->grffun[ AST__GSCALES ])( INTEGER_ARG(&GRFCON), REAL_ARG(alpha), REAL_ARG(beta) ); } /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file plot.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_stripescapes_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_stripescapes)( CHARACTER_RETURN_VALUE(RESULT), #endif CHARACTER(TEXT), INTEGER(STATUS) #if NO_CHAR_FUNCTION TRAIL(RESULT) #endif TRAIL(TEXT) ) { GENPTR_CHARACTER(RESULT) GENPTR_CHARACTER(TEXT) char *text; const char *result; int i; astAt( "AST_STRIPESCAPES", NULL, 0 ); astWatchSTATUS( text = astString( TEXT, TEXT_length ); result = astStripEscapes( text ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ astFree( text ); ) } F77_LOGICAL_FUNCTION(ast_getgrfcontext)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETGRFCONTEXT", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetGrfContext( astI2P( *THIS ) ) ); ) return RESULT; } ast-8.3.0/unitnormmap.c0000664000175000017500000016145113004147321011754 00000000000000/* *class++ * Name: * UnitNormMap * Purpose: * Convert a vector to a unit vector and its norm, relative to a specified centre. * Constructor Function: c astUnitNormMap f AST_UNITNORMMAP * Description: * The forward transformation of a UnitNormMap subtracts the specified centre * and then transforms the resulting vector to a unit vector and the vector norm. * The output contains one more coordinate than the input: the initial Nin outputs * are in the same order as the input; the final output is the norm. * * The inverse transformation of a UnitNormMap multiplies each component * of the provided vector by the provided norm and adds the specified centre. * The output contains one fewer coordinate than the input: the initial Nin inputs * are in the same order as the output; the final input is the norm. * * UnitNormMap enables radially symmetric transformations, as follows: * - apply a UnitNormMap to produce a unit vector and norm (radius) * - apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged * - apply the same UnitNormMap in the inverse direction to produce the result * Inheritance: * The UnitNormMap class inherits from the Mapping class. * Attributes: * The UnitNormMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The UnitNormMap class does not define any new functions beyond those f The UnitNormMap class does not define any new routines beyond those * which are applicable to all Mappings. * Copyright: * Copyright (C) 2016 University of Washington * 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 * . * Authors: * RO: Russell Owen (LSST) * History: * 20-APR-2016 (RO): * Original version. *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 UnitNormMap /* Macros which return the maximum and minimum of two values. */ #define MAX(aa,bb) ((aa)>(bb)?(aa):(bb)) #define MIN(aa,bb) ((aa)<(bb)?(aa):(bb)) /* Macro to check for equality of floating point values. We cannot compare bad values directory because of the danger of floating point exceptions, so bad values are dealt with explicitly. */ #define EQUAL(aa,bb) (((aa)==AST__BAD)?(((bb)==AST__BAD)?1:0):(((bb)==AST__BAD)?0:(fabs((aa)-(bb))<=1.0E9*MAX((fabs(aa)+fabs(bb))*DBL_EPSILON,DBL_MIN)))) /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "unitmap.h" /* Unit mappings */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "shiftmap.h" /* ShiftMap */ #include "winmap.h" /* ShiftMap */ #include "channel.h" /* I/O channels */ #include "unitnormmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(UnitNormMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(UnitNormMap,Class_Init) #define class_vtab astGLOBAL(UnitNormMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstUnitNormMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstUnitNormMap *astUnitNormMapId_( int, const double [], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int GetMappingType( AstMapping *, int * ); static AstMapping * MakeMergedMap( AstMapping *, AstMapping *, int * ); static int GetObjSize( AstObject *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int GetIsLinear( AstMapping *, int * ); /* Member functions. */ /* ================= */ static int GetMappingType( AstMapping *map, int *status ) { /* * * Name: * GetMappingType * Purpose: * Return a code describing the mapping type, to aid simplification. * Type: * Private function. * Synopsis: * #include "unitnormmap.h" * int MakeMergedMap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ) * Class Membership: * UnitNormMap internal utility function. * Description: * This function returns an integer code describing the type of a mapping, * to help with merging two mappings. The codes are: * 3 = WinMap * 2 = ShiftMap * 1 = UnitNormMap * 0 = other * Parameters: * map * A pointer to the mapping * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the merged mapping, or NULL if the Mappings cannot be merged */ const char *class = astGetClass( map ); int type = 0; if( strcmp( class, "UnitNormMap" ) == 0 ) { type = 1; } else if( strcmp( class, "ShiftMap" ) == 0 ) { type = 2; } else if( strcmp( class, "WinMap" ) == 0){ type = 3; } return type; } static AstMapping * MakeMergedMap( AstMapping *map1, AstMapping *map2, int *status ){ /* * * Name: * MakeMergedMap * Purpose: * Make a single Mapping that is equivalent to the merging of two other Mappings, * one of which must be a UnitNormMap. * Type: * Private function. * Synopsis: * #include "unitnormmap.h" * int MakeMergedMap( AstMapping *map1, AstMapping *map2, int inv1, int inv2, int *status ) * Class Membership: * UnitNormMap internal utility function. * Description: * This function returns a single Mapping that is the equivalent of the two supplied Mappings, * if they can be merged. One of the pair must be a UnitNormMap. * * Supported merges, which must be in series: * ShiftMap + UnitNormMap(forward) = UnitNormMap(forward) * WinMap with unit scale + UnitNormMap(forward) = UnitNormMap(forward) * UnitNormMap(inverted) + ShiftMap = UnitNormMap(inverted) * UnitNormMap(inverted) + WinMap with unit scale = UnitNormMap(inverted) * UnitNormMap(forward) + identical UnitNormMap(inverted) = UnitMap * UnitNormMap(inverted) + identical UnitNormMap(forward) = UnitMap * UnitNormMap(forward) + UnitNormMap(inverted) = ShiftMap * * * Notes: * - A UnitMap before or after a UnitNormMap = the UnitNormMap, but UnitMap takes care of that merge. * - The code that checks for ShiftMap + UnitNormMap probably never runs, because ShiftMap is * converted to WinMap during simplification before it gets here. * Parameters: * map1 * A pointer to the first mapping. * map2 * A pointer to the second mapping. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the merged mapping, or NULL if the Mappings cannot be merged */ /* Check the global error status. */ if( !astOK ) return NULL; /* Initialise returned mapping */ AstMapping *retmap = NULL; /* Set type to 1=UnitNormMap, 2=ShiftMap, 0=other for both maps */ int type1 = GetMappingType( map1, status ); int type2 = GetMappingType( map2, status ); if( !astOK ) return NULL; if( type1 == 0 || type2 == 0 ) return NULL; /* can only merge with UnitNormMap or ShiftMap */ if( !(type1 == 1 || type2 == 1) ) return NULL; /* one must be a UnitNormMap */ if( type1 == 2 ) { if( astGetInvert( map2 )) return NULL; /* ShiftMap + UnitNormMap(inverted) not supported */ /* ShiftMap + UnitNormMap(forward) = UnitNormMap(forward) */ AstShiftMap *shiftmap = (AstShiftMap *) map1; AstUnitNormMap *unm = (AstUnitNormMap *) map2; int nin = astGetNin( shiftmap ); double shiftmult = astGetInvert( shiftmap ) ? -1 : 1; double *newcentre = astMalloc( sizeof(double)*(size_t)nin ); int coord = 0; for( coord = 0; coord < nin; coord++ ){ newcentre[coord] = unm->centre[coord] - shiftmult*shiftmap->shift[coord]; } retmap = (AstMapping *) astUnitNormMap( nin, newcentre, "", status ); if( retmap == NULL ){ astFree( (void *) newcentre ); } } else if( type1 == 3 ) { if( astGetInvert( map2 )) return NULL; /* WinMap + UnitNormMap(inverted) not supported */ /* WinMap with unit scale + UnitNormMap(forward) = UnitNormMap(forward); abort if WinMap does not have unit scale */ AstWinMap *winmap = (AstWinMap *) map1; AstUnitNormMap *unm = (AstUnitNormMap *) map2; int nin = astGetNin( winmap ); double shiftmult = astGetInvert( winmap ) ? -1 : 1; double *newcentre = astMalloc( sizeof(double)*(size_t)nin ); int coord = 0; for( coord = 0; coord < nin; coord++ ){ if( !EQUAL( winmap->b[coord], 1.0 )) return NULL; newcentre[coord] = unm->centre[coord] - shiftmult*winmap->a[coord]; } retmap = (AstMapping *) astUnitNormMap( nin, newcentre, "", status ); if( retmap == NULL ){ astFree( (void *) newcentre ); } } else if( type2 == 2 ) { if( !astGetInvert( map1 )) return NULL; /* UnitNormMap(forward) + ShiftMap not supported */ /* UnitNormMap(inverted) + ShiftMap = UnitNormMap(inverted) */ AstShiftMap *shiftmap = (AstShiftMap *) map2; AstUnitNormMap *unm = (AstUnitNormMap *) map1; int nin = astGetNin( shiftmap ); double shiftmult = astGetInvert( shiftmap ) ? -1 : 1; double *newcentre = astMalloc( sizeof(double)*(size_t)nin ); int coord = 0; for( coord = 0; coord < nin; coord++ ){ newcentre[coord] = unm->centre[coord] + shiftmult*shiftmap->shift[coord]; } retmap = (AstMapping *) astUnitNormMap( nin, newcentre, "Invert=1", status ); if( retmap == NULL ){ astFree( (void *) newcentre ); } } else if( type2 == 3 ) { if( !astGetInvert( map1 )) return NULL; /* UnitNormMap(forward) + WinMap not supported */ /* UnitNormMap(inverted) + WinMap = UnitNormMap(inverted); abort if WinMap does not have unit scale */ AstWinMap *winmap = (AstWinMap *) map2; AstUnitNormMap *unm = (AstUnitNormMap *) map1; int nin = astGetNin( winmap ); double shiftmult = astGetInvert( winmap ) ? -1 : 1; double *newcentre = astMalloc( sizeof(double)*(size_t)nin ); int coord = 0; for( coord = 0; coord < nin; coord++ ){ if( !EQUAL( winmap->b[coord], 1.0 )) return NULL; newcentre[coord] = unm->centre[coord] + shiftmult*winmap->a[coord]; } retmap = (AstMapping *) astUnitNormMap( nin, newcentre, "Invert=1", status ); if( retmap == NULL ){ astFree( (void *) newcentre ); } } else { if( !astGetInvert( map1 ) == !astGetInvert( map2 )) return NULL; /* UNMs must have opposite dir. */ /* Two UnitNormMaps in opposite directions */ AstUnitNormMap *unm1 = (AstUnitNormMap *) map1; AstUnitNormMap *unm2 = (AstUnitNormMap *) map2; int ctrlen = MIN( astGetNin( map1 ), astGetNin( map2 ) ); int centres_equal = 1; int i = 0; for( i = 0; i < ctrlen; i++ ){ if( !EQUAL( unm1->centre[i], unm2->centre[i] )){ centres_equal = 0; break; } } if( centres_equal ) { /* Two UnitNormMap in opposite directions with identical centres = UnitMap */ retmap = (AstMapping *) astUnitMap( astGetNin( map1 ), "", status ); } else { if( astGetInvert( map2 )) { /* UnitNormMap(forward) + UnitNormMap(inverted) = ShiftMap */ int nin = astGetNin( map1 ); double *shift = astMalloc( sizeof(double)*(size_t)nin ); int coord = 0; for( coord = 0; coord < nin; coord++ ){ shift[coord] = unm2->centre[coord] - unm1->centre[coord]; } retmap = (AstMapping *) astShiftMap( nin, shift, "", status ); if( retmap == NULL ){ astFree( (void *) shift ); } } } } return astOK ? retmap : NULL; } static int GetIsLinear( AstMapping *this_mapping, int *status ){ /* * Name: * GetIsLinear * Purpose: * Return the value of the IsLinear attribute for a UnitNormMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * UnitNormMap member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one. * Parameters: * this * Pointer to the UnitNormMap. * status * Pointer to the inherited status variable. */ return 0; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "unitnormmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * UnitNormMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied UnitNormMap, * in bytes. * Parameters: * this * Pointer to the UnitNormMap. * 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. */ /* Initialise. */ int result = 0; /* Check the global error status. */ if( !astOK ) return result; /* Obtain a pointers to the UnitNormMap structure. */ AstUnitNormMap *this = (AstUnitNormMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->centre ); /* If an error occurred, clear the result value. */ if( !astOK ) result = 0; /* Return the result, */ return result; } void astInitUnitNormMapVtab_( AstUnitNormMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitUnitNormMapVtab * Purpose: * Initialise a virtual function table for a UnitNormMap. * Type: * Protected function. * Synopsis: * #include "unitnormmap.h" * void astInitUnitNormMapVtab( AstUnitNormMapVtab *vtab, const char *name ) * Class Membership: * UnitNormMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the UnitNormMap 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). *- */ /* Check the local error status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAUnitNormMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ AstObjectVtab *object = (AstObjectVtab *) vtab; AstMappingVtab *mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->MapMerge = MapMerge; mapping->GetIsLinear = GetIsLinear; /* Declare the class dump, copy and delete functions.*/ astSetDump( vtab, Dump, "UnitNormMap", "Compute unit vector and norm relative to a centre" ); astSetCopy( (AstObjectVtab *) vtab, Copy ); astSetDelete( (AstObjectVtab *) vtab, Delete ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a UnitNormMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * UnitNormMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated UnitNormMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated UnitNormMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated UnitNormMap which is to be merged with * its neighbours. This should be a cloned copy of the UnitNormMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * UnitNormMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated UnitNormMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Initialise. */ int result = -1; /* Check the global error status. */ if( !astOK ) return result; if( series ) { /* In series */ /* Try to merge UnitNormMap with either of its neighbours. */ AstMapping *map1 = NULL; /* The first Mapping to merge */ AstMapping *map2 = NULL; /* The second Mapping to merge */ AstMapping *newmap = NULL; /* The merged Mapping */ int i1 = MAX( where - 1, 0 ); int i2 = i1 + 1; for( ; i2 < *nmap; i1++, i2++ ){ map1 = ( *map_list )[ i1 ]; map2 = ( *map_list )[ i2 ]; int wasinverted1 = astGetInvert( map1 ); int wasinverted2 = astGetInvert( map2 ); astSetInvert( map1, ( *invert_list )[ i1 ] ); astSetInvert( map2, ( *invert_list )[ i2 ] ); newmap = MakeMergedMap( map1, map2, status ); astSetInvert( map1, wasinverted1 ); astSetInvert( map2, wasinverted2 ); if( newmap ) break; } if( !newmap ) return -1; if( !astOK ) { astAnnul( newmap ); return -1; } /* Annul the first of the two Mappings, and replace it with the merged Mapping. Also update the invert flag. */ (void) astAnnul( map1 ); ( *map_list )[ i1 ] = newmap; ( *invert_list )[ i1 ] = astGetInvert( newmap ); /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( map2 ); int i = 0; for( i = i2 + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } else { /* In parallel. */ /* UnitNormMaps cannot combine in parallel with any other Mappings. */ } /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a UnitNormMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "unitnormmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * UnitNormMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a UnitNormMap and a set of points encapsulated in a * PointSet and transforms the points so as to map them into the * required window. * Parameters: * this * Pointer to the UnitNormMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the UnitNormMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Check the global error status. */ if( !astOK ) return NULL; /* Obtain a pointer to the UnitNormMap. */ AstUnitNormMap *map = (AstUnitNormMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ AstPointSet *result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ int ncoord_in = astGetNcoord( in ); int ncoord_out = astGetNcoord( result ); int npoint = astGetNpoint(in); double **ptr_in = astGetPoints(in); double **ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if( astGetInvert(map) ){ forward = !forward; } /* Report an error if the UnitNormMap does not contain a centre. */ if( !map->centre && astOK ){ const char *class = astGetClass( this ); astError( AST__BADSM, "astTransform(%s): The supplied %s does not " "contain any centre information.", status, class, class ); } /* Perform coordinate arithmetic. */ /* ------------------------------ */ if( astOK ){ /* If any centre coordinate is bad then set all outputs bad */ int const ncoord_centre = forward ? ncoord_in : ncoord_out; int coord_ctr = 0; for( coord_ctr = 0; coord_ctr < ncoord_centre; coord_ctr++ ){ if( (map->centre)[coord_ctr] == AST__BAD ){ int coord_out = 0; for( coord_out = 0; coord_out < ncoord_out; coord_out++ ){ int point = 0; for( point = 0; point < npoint; point++ ){ ptr_out[point][coord_out] = AST__BAD; } } return result; } } if( forward ){ /* Forward transformation: vector to unit vector, norm */ int point = 0; for( point = 0; point < npoint; point++ ){ /* Compute max_relin: the maximum absolute input value relative to centre */ double max_relin = 0; int coord_in = 0; for( coord_in = 0; coord_in < ncoord_in; coord_in++ ){ double in = ptr_in[coord_in][point]; if( in == AST__BAD ){ /* An input coord is bad, so all output coords are bad */ int coord_out = 0; for( coord_out = 0; coord_out < ncoord_out; coord_out++ ){ ptr_out[coord_out][point] = AST__BAD; } goto forward_next_point; } double abs_relin = fabs(in - map->centre[coord_in]); if( abs_relin > max_relin ){ max_relin = abs_relin; } } if( max_relin == 0 ){ /* All inputs are 0, so all outputs are bad */ int coord = 0; for( coord = 0; coord < ncoord_out; coord++ ){ ptr_out[coord][point] = AST__BAD; } continue; } /* All is well; compute scaled_sum as the sum of (relin/max_relin)^2 for each input where relin = in - centre (the scaling avoids overflow), then compute norm = max_relin * sqrt(scaled_sum) and set all outputs */ double scaled_sum = 0; int coord = 0; for( coord = 0; coord < ncoord_in; coord++ ){ double scaled_in = (ptr_in[coord][point] - map->centre[coord])/max_relin; scaled_sum += scaled_in*scaled_in; } double norm = max_relin*sqrt(scaled_sum); for( coord = 0; coord < ncoord_in; coord++ ){ ptr_out[coord][point] = (ptr_in[coord][point] - map->centre[coord])/norm; } ptr_out[ncoord_out - 1][point] = norm; forward_next_point: ; } } else { /* Inverse transformation: unit vector, norm -> vector */ int point = 0; for( point = 0; point < npoint; point++ ){ double norm = ptr_in[ncoord_in-1][point]; if( norm == AST__BAD ){ /* Norm is bad for this point; set all output coords bad */ int coord = 0; for( coord = 0; coord < ncoord_out; coord++ ){ ptr_out[coord][point] = AST__BAD; } } else { int coord = 0; for( coord = 0; coord < ncoord_out; coord++ ){ double in = ptr_in[coord][point]; if( in == AST__BAD ){ ptr_out[coord][point] = AST__BAD; } else { ptr_out[coord][point] = in*norm + map->centre[coord]; } } } } } } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for UnitNormMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for UnitNormMap objects. * Parameters: * objin * Pointer to the UnitNormMap to be copied. * objout * Pointer to the UnitNormMap being constructed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstUnitNormMap *out; /* Pointer to output UnitNormMap */ AstUnitNormMap *in; /* Pointer to input UnitNormMap */ int ncoord; /* No. of axes for the mapping */ /* Check the global error status. */ if( !astOK ) return; /* Obtain a pointer to the input and output UnitNormMaps. */ in= (AstUnitNormMap *) objin; out = (AstUnitNormMap *) objout; /* Get the number of coordinates mapped by the UnitNormMap. */ ncoord = astGetNin( in ); /* Allocate memory holding copies of the centre defining the mapping. */ out->centre = (double *) astStore( NULL, (void *) in->centre, sizeof(double)*(size_t)ncoord ); /* If an error occurred, free any allocated memory. */ if( !astOK ) { out->centre = (double *) astFree( (void *) out->centre ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for UnitNormMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for UnitNormMap objects. * Parameters: * obj * Pointer to the UnitNormMap to be deleted. * status * Pointer to the inherited status variable. * Notes: * - This destructor does nothing and exists only to maintain a * one-to-one correspondence between destructors and copy * constructors. */ /* Local Variables: */ AstUnitNormMap *this; /* Pointer to UnitNormMap */ /* Obtain a pointer to the UnitNormMap structure. */ this = (AstUnitNormMap *) obj; /* Free the memory holding the centre. */ this->centre = (double *) astFree( (void *) this->centre ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for UnitNormMap 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 UnitNormMap class to an output Channel. * Parameters: * this * Pointer to the UnitNormMap 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 50 /* Maximum length of a comment string */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment string */ /* Check the global error status. */ if( !astOK ) return; /* Obtain a pointer to the UnitNormMap structure. */ AstUnitNormMap *this = (AstUnitNormMap *) this_object; /* Get the number of coordinates to be mapped. */ int ncoord = astGetNin( this ); /* Write out values representing the instance variables for the UnitNormMap class. Accompany these with appropriate comment strings, possibly depending on the values being written.*/ /* The centre. */ int axis = 0; for( axis = 0; axis < ncoord; axis++ ){ (void) sprintf( buff, "Ctr%d", axis + 1 ); (void) sprintf( comment, "Centre for axis %d", axis + 1 ); astWriteDouble( channel, buff, (this->centre)[ axis ] != 0.0, 0, (this->centre)[ axis ], comment ); } /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAUnitNormMap and astCheckUnitNormMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(UnitNormMap,Mapping) astMAKE_CHECK(UnitNormMap) AstUnitNormMap *astUnitNormMap_( int ncoord, const double centre[], const char *options, int *status, ...) { /* *++ * Name: c astUnitNormMap f AST_UNITNORMMAP * Purpose: * Create a UnitNormMap. * Type: * Public function. * Synopsis: c #include "unitnormmap.h" c AstUnitNormMap *astUnitNormMap( int ncoord, const double centre[], c const char *options, ... ) f RESULT = AST_UNITNORMMAP( NCOORD, CENTRE, OPTIONS, STATUS ) * Class Membership: * UnitNormMap constructor. * Description: * This function creates a new UnitNormMap and optionally initialises its * attributes. * * The forward transformation of a UnitNormMap subtracts the specified centre * and then transforms the resulting vector to a unit vector and the vector norm. * The output contains one more coordinate than the input: the initial Nin outputs * are in the same order as the input; the final output is the norm. * * The inverse transformation of a UnitNormMap multiplies each component * of the provided vector by the provided norm and adds the specified centre. * The output contains one fewer coordinate than the input: the initial Nin inputs * are in the same order as the output; the final input is the norm. * * UnitNormMap enables radially symmetric transformations, as follows: * - apply a UnitNormMap to produce a unit vector and norm (radius) * - apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged * - apply the same UnitNormMap in the inverse direction to produce the result * Parameters: c ncoord f NCOORD = INTEGER (Given) * The number of coordinate values for each point to be * transformed (i.e. the number of dimensions of the space in * which the points will reside). Output will include one additional coordinate. c centre f CENTRE( NCOORD ) = DOUBLE PRECISION (Given) * An array containing the values to be subtracted from the input * coordinates before computing unit vector and norm. A separate * value must be supplied for each coordinate. 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 UnitNormMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new UnitNormMap. The syntax used is identical to that for the f AST_SET routine. 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 astUnitNormMap() f AST_UNITNORMMAP = INTEGER * A pointer to the new UnitNormMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Get a pointer to the thread specific global data structure. */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ astGET_GLOBALS(NULL); /* Check the global status. */ if( !astOK ) return NULL; /* Initialise the UnitNormMap, allocating memory and initialising the virtual function table as well if necessary. */ AstUnitNormMap *new = astInitUnitNormMap( NULL, sizeof( AstUnitNormMap ), !class_init, &class_vtab, "UnitNormMap", ncoord, centre ); /* 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 UnitNormMap's attributes. */ va_list args; 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 UnitNormMap. */ return new; } AstUnitNormMap *astUnitNormMapId_( int ncoord, const double centre[], const char *options, ... ) { /* * Name: * astUnitNormMapId_ * Purpose: * Create a UnitNormMap. * Type: * Private function. * Synopsis: * #include "unitnormmap.h" * AstUnitNormMap *astUnitNormMapId_( int ncoord, const double centre[], * const char *options, ... ) * Class Membership: * UnitNormMap constructor. * Description: * This function implements the external (public) interface to the * astUnitNormMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astUnitNormMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astUnitNormMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astUnitNormMap_. * Returned Value: * The ID value associated with the new UnitNormMap. */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ astGET_GLOBALS(NULL); /* Check the global status. */ if( !astOK ) return NULL; /* Initialise the UnitNormMap, allocating memory and initialising the virtual function table as well if necessary. */ AstUnitNormMap *new = astInitUnitNormMap( NULL, sizeof( AstUnitNormMap ), !class_init, &class_vtab, "UnitNormMap", ncoord, centre ); /* 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 UnitNormMap's attributes. */ va_list args; /* Variable argument list */ 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 UnitNormMap. */ return astMakeId( new ); } AstUnitNormMap *astInitUnitNormMap_( void *mem, size_t size, int init, AstUnitNormMapVtab *vtab, const char *name, int ncoord, const double *centre, int *status ) { /* *+ * Name: * astInitUnitNormMap * Purpose: * Initialise a UnitNormMap. * Type: * Protected function. * Synopsis: * #include "unitnormmap.h" * AstUnitNormMap *astInitUnitNormMap( void *mem, size_t size, int init, * AstUnitNormMapVtab *vtab, const char *name, * int ncoord, const double *centre ) * Class Membership: * UnitNormMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new UnitNormMap object. It allocates memory (if necessary) to accommodate * the UnitNormMap plus any additional data associated with the derived class. * It then initialises a UnitNormMap 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 UnitNormMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the UnitNormMap is to be initialised. * This must be of sufficient size to accommodate the UnitNormMap data * (sizeof(UnitNormMap)) 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 UnitNormMap (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 UnitNormMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the UnitNormMap'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 UnitNormMap. * 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). * ncoord * The number of coordinate values per point. * centre * Pointer to an array of centres, one for each coordinate. * Returned Value: * A pointer to the new UnitNormMap. * 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: */ AstUnitNormMap *new; /* Pointer to new UnitNormMap */ /* Check the global status. */ if( !astOK ) return NULL; /* Check centre */ if( ncoord <= 0 ){ astError( AST__BADSM, "The centre must have at least one axis", status ); return NULL; } /* If necessary, initialise the virtual function table. */ if( init ) astInitUnitNormMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a Mapping structure (the parent class) as the first component within the UnitNormMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstUnitNormMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, ncoord, ncoord+1, 1, 1 ); if( astOK ) { /* Initialise the UnitNormMap data. */ /* ---------------------------- */ /* Allocate memory to hold the centre for each axis. */ new->centre = (double *) astMalloc( sizeof(double)*(size_t)ncoord ); /* Check the pointers can be used */ if( astOK ){ /* Store the centre for each axis. */ int axis = 0; for( axis = 0; axis < ncoord; axis++ ){ (new->centre)[ axis ] = centre ? centre[ axis ] : AST__BAD; } } /* If an error occurred, clean up by deleting the new UnitNormMap. */ if( !astOK ) new = astDelete( new ); } /* Return a pointer to the new UnitNormMap. */ return new; } AstUnitNormMap *astLoadUnitNormMap_( void *mem, size_t size, AstUnitNormMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadUnitNormMap * Purpose: * Load a UnitNormMap. * Type: * Protected function. * Synopsis: * #include "unitnormmap.h" * AstUnitNormMap *astLoadUnitNormMap( void *mem, size_t size, * AstUnitNormMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * UnitNormMap loader. * Description: * This function is provided to load a new UnitNormMap 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 * UnitNormMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a UnitNormMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the UnitNormMap is to be * loaded. This must be of sufficient size to accommodate the * UnitNormMap data (sizeof(UnitNormMap)) 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 UnitNormMap (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 UnitNormMap 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(AstUnitNormMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new UnitNormMap. If this is NULL, a pointer * to the (static) virtual function table for the UnitNormMap 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 "UnitNormMap" is used instead. * Returned Value: * A pointer to the new UnitNormMap. * 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. */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ /* Get a pointer to the thread specific global data structure. */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ astGET_GLOBALS(channel); /* Initialise. */ AstUnitNormMap *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 UnitNormMap. In this case the UnitNormMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if( !vtab ) { size = sizeof( AstUnitNormMap ); vtab = &class_vtab; name = "UnitNormMap"; /* If required, initialise the virtual function table for this class. */ if( !class_init ) { astInitUnitNormMapVtab( 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 UnitNormMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) vtab, name, channel ); if( astOK ) { /* Get the number of axis for the mapping. */ int ncoord = astGetNin( (AstMapping *) new ); /* Allocate memory to hold the centre. */ new->centre = (double *) astMalloc( sizeof(double)*(size_t)ncoord ); /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "UnitNormMap" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* The centre. */ int axis = 0; for( axis = 0; axis < ncoord; axis++ ){ (void) sprintf( buff, "ctr%d", axis + 1 ); (new->centre)[ axis ] = astReadDouble( channel, buff, 0.0 ); } } /* If an error occurred, clean up by deleting the new UnitNormMap. */ if( !astOK ) new = astDelete( new ); /* Return the new UnitNormMap 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. */ ast-8.3.0/selectormap.c0000664000175000017500000017341113004147321011720 00000000000000/* *class++ * Name: * SelectorMap * Purpose: * A Mapping that locates positions within one of a set of alternate * Regions. * Constructor Function: c astSelectorMap f AST_SELECTORMAP * Description: * A SelectorMap is a Mapping that identifies which Region contains * a given input position. * * A SelectorMap encapsulates a number of Regions that all have the same * number of axes and represent the same coordinate Frame. The number of * inputs (Nin attribute) of the SelectorMap equals the number of axes * spanned by one of the encapsulated Region. All SelectorMaps have only * a single output. SelectorMaps do not define an inverse transformation. * * For each input position, the forward transformation of a SelectorMap * searches through the encapsulated Regions (in the order supplied when * the SelectorMap was created) until a Region is found which contains * the input position. The index associated with this Region is * returned as the SelectorMap output value (the index value is the * position of the Region within the list of Regions supplied when the * SelectorMap was created, starting at 1 for the first Region). If an * input position is not contained within any Region, a value of zero is * returned by the forward transformation. * * If a compound Mapping contains a SelectorMap in series with its own * inverse, the combination of the two adjacent SelectorMaps will be * replaced by a UnitMap when the compound Mapping is simplified using c astSimplify. f AST_SIMPLIFY. * * In practice, SelectorMaps are often used in conjunction with SwitchMaps. * Inheritance: * The SelectorMap class inherits from the Mapping class. * Attributes: * The SelectorMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The SelectorMap class does not define any new functions beyond those f The SelectorMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 15-MAR-2006 (DSB): * Original version. * 18-MAY-2006 (DSB): * - Change logic for detecting interior points in function Transform. * - Added BADVAL to contructor argument list. *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 SelectorMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "unitmap.h" /* Unit Mappings */ #include "channel.h" /* I/O channels */ #include "selectormap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SelectorMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SelectorMap,Class_Init) #define class_vtab astGLOBAL(SelectorMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSelectorMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstSelectorMap *astSelectorMapId_( int, void **, double, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetObjSize( AstObject *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two SelectorMaps are equivalent. * Type: * Private function. * Synopsis: * #include "selectormap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * SelectorMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two SelectorMaps are equivalent. * Parameters: * this * Pointer to the first Object (a SelectorMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the SelectorMaps are equivalent, zero otherwise. * 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: */ AstSelectorMap *that; AstSelectorMap *this; int i; int nin; int nreg; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two SelectorMap structures. */ this = (AstSelectorMap *) this_object; that = (AstSelectorMap *) that_object; /* Check the second object is a SelectorMap. We know the first is a SelectorMap since we have arrived at this implementation of the virtual function. */ if( astIsASelectorMap( that ) ) { /* Check they have the same number of inputs. */ nin = astGetNin( this ); if( astGetNin( that ) == nin ) { /* Check they contain the same number of Regions, and have the same badval. */ nreg = this->nreg; if( that->nreg == nreg || astEQUAL( that->badval, this->badval) ) { /* Loop over the Regions, breaking as soon as two unequal Regions are found. */ result = 1; for( i = 0; i < nreg; i++ ) { if( !astEqual( this->reg[ i ], that->reg[ i ] ) ) { result = 0; break; } } } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "selectormap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SelectorMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SelectorMap, * in bytes. * Parameters: * this * Pointer to the SelectorMap. * 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: */ AstSelectorMap *this; int i; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SelectorMap structure. */ this = (AstSelectorMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); for( i = 0; i < this->nreg; i++ ) { result += astGetObjSize( this->reg[ i ] ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitSelectorMapVtab_( AstSelectorMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSelectorMapVtab * Purpose: * Initialise a virtual function table for a SelectorMap. * Type: * Protected function. * Synopsis: * #include "selectormap.h" * void astInitSelectorMapVtab( AstSelectorMapVtab *vtab, const char *name ) * Class Membership: * SelectorMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SelectorMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsASelectorMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "SelectorMap", "Region identification Mapping" ); /* 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) ); } } #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: * SelectorMap 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: */ AstSelectorMap *this; /* Pointer to SelectorMap 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 SelectorMap structure. */ this = (AstSelectorMap *) 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->nreg; i++ ) { if( !result ) result = astManageLock( this->reg[ i ], mode, extra, fail ); } return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a SelectorMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * SelectorMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated SelectorMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated SelectorMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated SelectorMap which is to be merged with * its neighbours. This should be a cloned copy of the SelectorMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * SelectorMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated SelectorMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *new; AstRegion **sreg; AstSelectorMap *map; AstSelectorMap *slneb; int equal; int i; int ilo; int nreg; int result; int simp; /* Initialise.*/ result = -1; /* Check the inherited status. */ if ( !astOK ) return result; /* Get a pointer to this SelectorMap, and note the number of Regions. */ map = (AstSelectorMap *) this; nreg = map->nreg; /* Attempt to simplify the SelectorMap on its own. */ /* ============================================= */ /* Try to simplify each of the encapsulated Regions, noting if any simplification takes place. */ simp = 0; sreg = astMalloc( sizeof( AstRegion * )*nreg ); if( astOK ) { for( i = 0; i < nreg; i++ ) { sreg[ i ] = astSimplify( map->reg[ i ] ); simp = simp || ( sreg[ i ] != map->reg[ i ] ); } /* If any simplification took place, construct a new SelectorMap from these simplified Mappings. */ if( simp ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) astSelectorMap( nreg, (void **) sreg, map->badval, "", status ); result = where; } /* Release resources. */ if( sreg ) { for( i = 0; i < nreg; i++ ) sreg[ i ] = astAnnul( sreg[ i ] ); sreg = astFree( sreg ); } } /* If possible, merge the SelectorMap with a neighbouring SelectorMap. */ /* =============================================================== */ /* Only do this if no change was made above, and we are combining the Mappings in series. */ if( result == -1 && series ) { /* Is the higher neighbour a SelectorMap? If so get a pointer to it, and note the index of the lower of the two adjacent SelectorMaps. */ if( where < ( *nmap - 1 ) && astIsASelectorMap( ( *map_list )[ where + 1 ] ) ){ slneb = (AstSelectorMap *) ( *map_list )[ where + 1 ]; ilo = where; /* If not, is the lower neighbour a SelectorMap? If so get a pointer to it, and note the index of the lower of the two adjacent SelectorMaps. */ } else if( where > 0 && astIsASelectorMap( ( *map_list )[ where - 1 ] ) ){ slneb = (AstSelectorMap *) ( *map_list )[ where - 1 ]; ilo = where - 1; } else { slneb = NULL; } /* If a neighbouring SelectorMap was found, we can replace the pair by a UnitMap if the two SelectorMaps are equal but have opposite values for their Invert flags. Temporarily invert the neighbour, then compare the two SelectorMaps for equality, then re-invert the neighbour. */ if( slneb ) { astInvert( slneb ); equal = astEqual( map, slneb ); astInvert( slneb ); /* If the two SelectorMaps are equal but opposite, annul the first of the two Mappings, and replace it with a UnitMap. Also set the invert flag. */ if( equal ) { new = (AstMapping *) astUnitMap( astGetNin( ( *map_list )[ ilo ] ), "", status ); (void) astAnnul( ( *map_list )[ ilo ] ); ( *map_list )[ ilo ] = new; ( *invert_list )[ ilo ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ ilo + 1 ] ); for ( i = ilo + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = where; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a SelectorMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "selectormap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * SelectorMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a SelectorMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Mapping. * This implies applying each of the SelectorMap's component Mappings in turn, * either in series or in parallel. * Parameters: * this * Pointer to the SelectorMap. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the SelectorMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *ps1; AstPointSet *ps2; AstPointSet *result; AstPointSet *tps; AstRegion *reg; AstSelectorMap *map; double **ptr_out; double **ptr1; double **ptr2; double **tptr; double *p2; double *pout; double badval; int bad; int closed; int icoord; int ipoint; int ireg; int ncoord; int npoint; /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SelectorMap. */ map = (AstSelectorMap *) this; /* Apply the parent Mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We now extend the parent astTransform method by applying the component Mappings of the SelectorMap to generate the output coordinate values. */ /* Check we are implementing the original forward transformation (the inverse transformation is not defined). */ if( forward != astGetInvert( this ) ) { /* Get the number of input axes and the number of points. */ ncoord = astGetNcoord( in ); npoint = astGetNpoint( in ); /* Create two temporary PointSets to hold copies of the input points. */ ps1 = astCopy( in ); ptr1 = astGetPoints( ps1 ); ps2 = astPointSet( npoint, ncoord, "", status ); ptr2 = astGetPoints( ps2 ); /* Get a pointer to the output data */ ptr_out = astGetPoints( result ); if( astOK ) { /* Initialise the output array to hold -1 at any points that have bad input axis values, and zero at all other points. */ pout = ptr_out[ 0 ]; for( ipoint = 0; ipoint < npoint; ipoint++ ) { bad = 0; for( icoord = 0; icoord < ncoord; icoord++ ) { if( ptr1[ icoord ][ ipoint ] == AST__BAD ) { bad = 1; break; } } *(pout++) = bad ? -1 : 0; } /* Loop round all Regions. */ for( ireg = 1; ireg <= map->nreg; ireg++ ) { reg = map->reg[ ireg - 1 ]; /* Temporarily Negate the Region. */ astNegate( reg ); closed = astGetClosed( reg ); astSetClosed( reg, !closed ); /* Transform the remaining input positions. Good input positions which are within the Region will be bad in the output. */ ps2 = astTransform( reg, ps1, 1, ps2 ); /* Loop round all positions. */ p2 = ptr2[ 0 ]; pout = ptr_out[ 0 ]; for( ipoint = 0; ipoint < npoint; ipoint++, p2++, pout++ ) { /* Any position that has not already been assigned to a Region and is bad in the output PointSet must be contained within the current Region, so assign the (one-based) index of the current Region to the output element. */ if( *pout == 0 && *p2 == AST__BAD ) *pout = ireg; } /* Negate the Region to get it back to its original state. */ astSetClosed( reg, closed ); astNegate( reg ); /* Swap the input and output PointSets. */ tps = ps1; ps1 = ps2; ps2 = tps; tptr = ptr1; ptr1 = ptr2; ptr2 = tptr; } /* Replace -1 values in the output (that indicate that the input position had at least one bad axis value) with the "badval".*/ badval = map->badval; pout = ptr_out[ 0 ]; for( ipoint = 0; ipoint < npoint; ipoint++, pout++ ) { if( *pout == -1 ) *pout = badval; } } /* Free resources. */ ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SelectorMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SelectorMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the * Regions within the SelectorMap. */ /* Local Variables: */ AstSelectorMap *in; /* Pointer to input SelectorMap */ AstSelectorMap *out; /* Pointer to output SelectorMap */ int i; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SelectorMaps. */ in = (AstSelectorMap *) objin; out = (AstSelectorMap *) objout; /* For safety, start by clearing any references to the input Regions. */ out->reg = NULL; out->nreg = 0; /* Make copies of the Regions, and store pointers to them in the output SelectorMap structure. */ out->reg = astMalloc( sizeof( AstRegion * )*( in->nreg ) ); if( astOK ) { for( i = 0; i < in->nreg; i++ ) { out->reg[ i ] = astCopy( in->reg[ i ] ); } out->nreg = in->nreg; } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SelectorMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SelectorMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstSelectorMap *this; /* Pointer to SelectorMap */ int i; /* Obtain a pointer to the SelectorMap structure. */ this = (AstSelectorMap *) obj; /* Free dynamically allocated resources. */ for( i = 0; i < this->nreg; i++ ) { this->reg[ i ] = astAnnul( this->reg[ i ] ); } this->reg = astFree( this->reg ); /* Clear the remaining SelectorMap variables. */ this->nreg = 0; } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SelectorMap 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 SelectorMap class to an output Channel. * Parameters: * this * Pointer to the SelectorMap 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 Variables: */ AstSelectorMap *this; int i; char buf[ 20 ]; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SelectorMap structure. */ this = (AstSelectorMap *) this_object; /* Write out values representing the instance variables for the SelectorMap 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. */ /* Loop to dump each Region. */ /* ------------------------- */ /* The coordinate Frame of the Regions is defined by the first Region. The Frame information is omitted from the second and subsequent Regions by setting the protected RegionFS attribute to zero. */ for( i = 0; i < this->nreg; i++ ) { sprintf( buf, "Reg%d", i + 1 ); if( i > 0 ) astSetRegionFS( this->reg[ i ], 0 ); astWriteObject( channel, buf, 1, 1, this->reg[ i ], "Region of input space" ); if( i > 0 ) astClearRegionFS( this->reg[ i ] ); } /* BadVal. */ /* ------- */ if( this->badval != AST__BAD ) { astWriteDouble( channel, "BadVal", 1, 1, this->badval, "Output value for bad input positions" ); } } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASelectorMap and astCheckSelectorMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SelectorMap,Mapping) astMAKE_CHECK(SelectorMap) AstSelectorMap *astSelectorMap_( int nreg, void **regs_void, double badval, const char *options, int *status, ...) { /* *+ * Name: * astSelectorMap * Purpose: * Create a SelectorMap. * Type: * Protected function. * Synopsis: * #include "selectormap.h" * AstSelectorMap *astSelectorMap( int nreg, AstRegion **regs, * double badval, const char *options, ... ) * Class Membership: * SelectorMap constructor. * Description: * This function creates a new SelectorMap and optionally initialises its * attributes. * Parameters: * nreg * The number of Regions supplied. * regs * An array of pointers to the Regions. Deep copies of these * Regions are taken. * badval * The value to be returned by the forward transformation of the * SelectorMap for any input positions that have a bad (AST__BAD) * value on any axis. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new SelectorMap. The syntax used is the same as for the * astSet method and may include "printf" format specifiers identified * by "%" symbols in the normal way. * ... * 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 SelectorMap. * 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 SelectorMap constructor which is * available via the protected interface to the SelectorMap class. A * public interface is provided by the astSelectorMapId_ 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 * "map1" and "map2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSelectorMap *new; /* Pointer to new SelectorMap */ AstRegion **regs; /* Array of Region pointers */ int i; /* Region index */ 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; /* Report an error if no Regions have been supplied. */ if( nreg <= 0 ) astError( AST__BDPAR, "astSelectorMap(SelectorMap): " "Bad number of Regions (%d) specified.", status, nreg ); /* Otherwise create an array to hold the Region pointers. */ regs = astMalloc( sizeof( AstRegion * )*nreg ); /* Obtain and validate pointers to the Region structures provided. */ if( astOK ) { for( i = 0; i < nreg; i++ ) { regs[ i ] = astCheckRegion( regs_void[ i ] ); } } if ( astOK ) { /* Initialise the SelectorMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSelectorMap( NULL, sizeof( AstSelectorMap ), !class_init, &class_vtab, "SelectorMap", nreg, regs, badval ); /* 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 SelectorMap'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 ); } } /* Free memory used to hold the Regions pointers. */ regs = astFree( regs ); /* Return a pointer to the new SelectorMap. */ return new; } AstSelectorMap *astSelectorMapId_( int nreg, void **regs_void, double badval, const char *options, ... ) { /* *++ * Name: c astSelectorMap f AST_SELECTORMAP * Purpose: * Create a SelectorMap. * Type: * Public function. * Synopsis: c #include "selectormap.h" c AstSelectorMap *astSelectorMap( int nreg, AstRegion *regs[], c double badval, const char *options, ... ) f RESULT = AST_SELECTORMAP( NREG, REGS, BADVAL, OPTIONS, STATUS ) * Class Membership: * SelectorMap constructor. * Description: * This function creates a new SelectorMap and optionally initialises * its attributes. * * A SelectorMap is a Mapping that identifies which Region contains * a given input position. * * A SelectorMap encapsulates a number of Regions that all have the same * number of axes and represent the same coordinate Frame. The number of * inputs (Nin attribute) of the SelectorMap equals the number of axes * spanned by one of the encapsulated Region. All SelectorMaps have only * a single output. SelectorMaps do not define an inverse transformation. * * For each input position, the forward transformation of a SelectorMap * searches through the encapsulated Regions (in the order supplied when * the SelectorMap was created) until a Region is found which contains * the input position. The index associated with this Region is * returned as the SelectorMap output value (the index value is the * position of the Region within the list of Regions supplied when the * SelectorMap was created, starting at 1 for the first Region). If an * input position is not contained within any Region, a value of zero is * returned by the forward transformation. * * If a compound Mapping contains a SelectorMap in series with its own * inverse, the combination of the two adjacent SelectorMaps will be * replaced by a UnitMap when the compound Mapping is simplified using c astSimplify. f AST_SIMPLIFY. * * In practice, SelectorMaps are often used in conjunction with SwitchMaps. * Parameters: c nreg f NREG = INTEGER (Given) * The number of supplied Regions. c regs f REGS( NREG ) = INTEGER (Given) * An array of pointers to the Regions. All the supplied Regions must * relate to the same coordinate Frame. The number of axes in this * coordinate Frame defines the number of inputs for the SelectorMap. c badval f BADVAL = DOUBLE PRECISION (Given) * The value to be returned by the forward transformation of the * SelectorMap for any input positions that have a bad (AST__BAD) * value on any axis. 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 SelectorMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new SelectorMap. The syntax used is identical to that for the f AST_SET routine. 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 astSelectorMap() f AST_SELECTORMAP = INTEGER * A pointer to the new SelectorMap. * Notes: * - Deep copies are taken of the supplied Regions. This means that * any subsequent changes made to the component Regions using the * supplied pointers will have no effect on the SelectorMap. * - 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 astSelectorMap constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astSelectorMap_ 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 "map1" and "map2" parameters * are of type (void *) and are converted from an ID value to a * pointer and validated within the function itself. * - The variable argument list also prevents this function from * invoking astSelectorMap_ 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 */ AstSelectorMap *new; /* Pointer to new SelectorMap */ AstRegion **regs; /* Array of Region pointers */ int i; /* Region index */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ new = NULL; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return new; /* Report an error if no Regions have been supplied. */ if( nreg <= 0 ) astError( AST__BDPAR, "astSelectorMap(SelectorMap): " "Bad number of Regions (%d) specified.", status, nreg ); /* Create an array to hold the Region pointers. */ regs = astMalloc( sizeof( AstRegion * )*nreg ); /* Obtain and validate pointers to the Region structures provided. */ if( astOK ) { for( i = 0; i < nreg; i++ ) { regs[ i ] = astVerifyRegion( astMakePointer(regs_void[ i ]) ); } } if ( astOK ) { /* Initialise the SelectorMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSelectorMap( NULL, sizeof( AstSelectorMap ), !class_init, &class_vtab, "SelectorMap", nreg, regs, badval ); /* 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 SelectorMap'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 ); } } /* Free memory used to hold the Regions pointers. */ regs = astFree( regs ); /* Return an ID value for the new SelectorMap. */ return astMakeId( new ); } AstSelectorMap *astInitSelectorMap_( void *mem, size_t size, int init, AstSelectorMapVtab *vtab, const char *name, int nreg, AstRegion **regs, double badval, int *status ) { /* *+ * Name: * astInitSelectorMap * Purpose: * Initialise a SelectorMap. * Type: * Protected function. * Synopsis: * #include "selectormap.h" * AstSelectorMap *astInitSelectorMap( void *mem, size_t size, int init, * AstSelectorMapVtab *vtab, const char *name, * int nreg, AstRegion **regs, double badval ) * Class Membership: * SelectorMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new SelectorMap object. It allocates memory (if necessary) to * accommodate the SelectorMap plus any additional data associated with the * derived class. It then initialises a SelectorMap 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 SelectorMap at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SelectorMap is to be initialised. * This must be of sufficient size to accommodate the SelectorMap data * (sizeof(SelectorMap)) 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 SelectorMap (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 * SelectorMap structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the SelectorMap'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 SelectorMap. * 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 Object * astClass function). * nreg * The number of Regions supplied. * regs * An array holdiong pointers to the Regions. Deep copies are taken * of these Regions. * badval * The value to be returned by the forward transformation of the * SelectorMap for any input positions that have a bad (AST__BAD) * value on any axis. * Returned Value: * A pointer to the new SelectorMap. * Notes: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. *- */ /* Local Variables: */ AstFrame *f0; /* Frame from first Region */ AstFrame *f1; /* Frame from current Region */ AstSelectorMap *new; /* Pointer to new SelectorMap */ int equal; /* Are Frames equal? */ int i; /* Loop count */ int nin; /* No. input coordinates for SelectorMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSelectorMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check that all Regions refer to the same Frame. */ f0 = astRegFrame( regs[ 0 ] ); for( i = 1; i < nreg; i++ ) { f1 = astRegFrame( regs[ i ] ); equal = astEqual( f1, f0 ); f1 = astAnnul( f1 ); if( !equal ) { if( astOK ) { astError( AST__BADNI, "astInitSelectorMap(%s): Region " "number %d does not refer to the same coordinate " "Frame as the first Region.", status, name, i + 1 ); } } } nin = astGetNin( regs[ 0 ] ); f0 = astAnnul( f0 ); /* Initialise a Mapping structure (the parent class) as the first component within the SelectorMap structure, allocating memory if necessary. Specify the number of input and output coordinates and in which directions the Mapping should be defined. */ if ( astOK ) { new = (AstSelectorMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, 1, 1, 0 ); if ( astOK ) { /* Initialise the SelectorMap data. */ /* -------------------------------- */ /* Create an array for the Region pointers. */ new->reg = astMalloc( sizeof( AstRegion * )*nreg ); /* Store pointers to deep copies of the Regions. */ if( astOK ) { new->nreg = nreg; for( i = 0; i < nreg; i++ ) { new->reg[ i ] = astCopy( regs[ i ] ); } } else { new->nreg = 0; } /* Store other items */ new->badval = badval; /* 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; } AstSelectorMap *astLoadSelectorMap_( void *mem, size_t size, AstSelectorMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSelectorMap * Purpose: * Load a SelectorMap. * Type: * Protected function. * Synopsis: * #include "selectormap.h" * AstSelectorMap *astLoadSelectorMap( void *mem, size_t size, * AstSelectorMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SelectorMap loader. * Description: * This function is provided to load a new SelectorMap 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 * SelectorMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a SelectorMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the SelectorMap is to be * loaded. This must be of sufficient size to accommodate the * SelectorMap data (sizeof(SelectorMap)) 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 SelectorMap (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 SelectorMap 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(AstSelectorMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SelectorMap. If this is NULL, a pointer to * the (static) virtual function table for the SelectorMap 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 "SelectorMap" is used instead. * Returned Value: * A pointer to the new SelectorMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSelectorMap *new; AstFrameSet *fs; AstRegion *reg; int i; char buf[ 20 ]; /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this SelectorMap. In this case the SelectorMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSelectorMap ); vtab = &class_vtab; name = "SelectorMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSelectorMapVtab( 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 SelectorMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "SelectorMap" ); /* 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. */ /* Loop to load each Region. */ /* ------------------------- */ new->reg = NULL; i = 0; fs = NULL; while( astOK ) { sprintf( buf, "reg%d", i + 1 ); reg = astReadObject( channel, buf, NULL ); if( reg ) { new->reg = astGrow( new->reg, i + 1, sizeof( AstRegion *) ); if( astOK ) { new->reg[ i ] = reg; /* All but the first Region may have a dummy FrameSet rather than the correct FrameSet. The correct FrameSet will be a copy of the FrameSet from the first Region. */ if( i == 0 ) { fs = astGetRegFS( reg ); } else if( astRegDummyFS( reg ) ){ astSetRegFS( reg, fs ); } i++; } } else { break; } } fs = astAnnul( fs ); /* Number of Regions. */ new->nreg = i; /* BadVal. */ /* ------- */ new->badval = astReadDouble( channel, "badval", AST__BAD ); /* If an error occurred, clean up by deleting the new SelectorMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SelectorMap pointer. */ return new; } /* 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. */ /* None. */ ast-8.3.0/grf_pgplot.c0000664000175000017500000013465213004147321011551 00000000000000/* * Name: * grf_pgplot.c * Purpose: * Implement the grf module using the PGPLOT graphics system. * Description: * This file implements the low level graphics functions required * by the rest of AST, by calling suitable PGPLOT functions (the * FORTRAN PGPLOT interface is used). * * This file can be used as a template for the development of * similar modules to support alternative graphics systems. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink) * History: * 27-JUN-1996 (DSB): * Original version. * 13-NOV-1996 (DSB): * Use C wrappers for PGPLOT functions. * 15-NOV-1996 (RFWS): * Merged the C interface to PGPLOT into this file so that the * interface functions can be static. * 7-OCT-1997 (DSB): * Corrected astGText and astGTxExt, by including a check for * reversed axes. Previously, the up-vector was used as supplied * even if the axes had been reversed. * 15-OCT-1997 (DSB): * o Corrected astGText and astGTxExt to take account of non-equal * scales on the two axes. * o Modified astGTxExt so that it includes any leading or trailing * spaces in the returned box. * o Added astGAxScale. * 28-OCT-1998 (DSB): * o Changed interpretation of the Width attribute from inches, to * a multiple of a small line width. * o Wrapper for pgplot F77 subroutine PGQVSZ added. * 30-JAN-2004 (DSB): * o Added GCap * o Renamed GAxScale as GScales * 4-MAR-2011 (DSB): * Added astGBBuf and astGEBuf. */ /* Macros */ /* ====== */ #define MXSTRLEN 80 /* String length at which truncation starts within pgqtxt and pgptxt. */ /* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* C to FORTRAN interface functions */ #include "pointset.h" /* Defines AST__BAD */ #include "memory.h" /* Memory allocation facilities */ #include "error.h" /* Error reporting facilities */ #include "grf.h" /* Interface to this module */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include /* Constants. */ /* ========== */ #define R2D 57.29578 /* Radians to degrees factor */ /* Function Prototypes. */ /* ==================== */ /* These define a local C interface to the PGPLOT library. */ static void ccpgline(int n, float xpts[], float ypts[] ); static void ccpgpt(int n, float xpts[], float ypts[], int symbol); static void ccpgptxt(float x, float y, float angle, float fjust, char *text ); static void ccpgqcf(int *cf); static void ccpgqch(float *ch); static void ccpgqci(int *ci); static void ccpglen(int units, char *text, float *xl, float *yl); static void ccpgqcs(int units, float *xch, float *ych); static void ccpgqls(int *ls); static void ccpgqlw(int *lw); static void ccpgqtbg(int *tbci); static void ccpgqtxt(float x, float y, float angle, float fjust, char *text, float xbox[], float ybox[]); static void ccpgqvp(int units, float *x1, float *x2, float *y1, float *y2); static void ccpgqvsz(int units, float *x1, float *x2, float *y1, float *y2); static void ccpgqwin(float *x1, float *x2, float *y1, float *y2); static void ccpgscf(int cf); static void ccpgsch(float ch); static void ccpgsci(int ci); static void ccpgsls(int ls); static void ccpgslw(int lw); static void ccpgstbg(int tbci); static void ccpgupdt( void ); static void ccpgbbuf( void ); static void ccpgebuf( void ); /* These describe the native Fortran interface to the PGPLOT library. The macros used come from the "f77.h" include file. */ F77_SUBROUTINE(pgline)( INTEGER(n), REAL_ARRAY(x), REAL_ARRAY(y) ); F77_SUBROUTINE(pgpt)( INTEGER(n), REAL_ARRAY(x), REAL_ARRAY(y), INTEGER(TYPE) ); F77_SUBROUTINE(pgptxt)( REAL(x), REAL(y), REAL(angle), REAL(fjust), CHARACTER(text) TRAIL(text) ); F77_SUBROUTINE(pgqcf)( INTEGER(ival) ); F77_SUBROUTINE(pgqch)( REAL(rval) ); F77_SUBROUTINE(pgqci)( INTEGER(ival) ); F77_SUBROUTINE(pgqcs)( INTEGER(units), REAL(chv), REAL(chh) ); F77_SUBROUTINE(pglen)( INTEGER(units), CHARACTER(text), REAL(xl), REAL(yl) TRAIL(text) ); F77_SUBROUTINE(pgqls)( INTEGER(ival) ); F77_SUBROUTINE(pgqlw)( INTEGER(ival) ); F77_SUBROUTINE(pgqtbg)( INTEGER(tbg) ); F77_SUBROUTINE(pgqtxt)( REAL(x), REAL(y), REAL(angle), REAL(fjust), CHARACTER(text), REAL_ARRAY(xbox), REAL_ARRAY(ybox) TRAIL(text) ); F77_SUBROUTINE(pgqvp)( INTEGER(units), REAL(vx1), REAL(vx2), REAL(vy1), REAL(vy2) ); F77_SUBROUTINE(pgqvsz)( INTEGER(units), REAL(x1), REAL(x2), REAL(y1), REAL(y2) ); F77_SUBROUTINE(pgqwin)( REAL(wx1), REAL(wx2), REAL(wy1), REAL(wy2) ); F77_SUBROUTINE(pgscf)( INTEGER(ival) ); F77_SUBROUTINE(pgsch)( REAL(rval) ); F77_SUBROUTINE(pgsci)( INTEGER(ival) ); F77_SUBROUTINE(pgsls)( INTEGER(ival) ); F77_SUBROUTINE(pgslw)( INTEGER(ival) ); F77_SUBROUTINE(pgstbg)( INTEGER(tbg) ); F77_SUBROUTINE(pgupdt)( ); F77_SUBROUTINE(pgbbuf)( ); F77_SUBROUTINE(pgebuf)( ); /* Externally visible functions. */ /* ============================= */ /* These implement the "grf" interface in terms of the local C interface to PGPLOT. */ int astGBBuf( void ){ /* *+ * Name: * astGBBuf * Purpose: * Start a new graphics buffering context. * Synopsis: * #include "grf.h" * int astGBBuf( void ) * Description: * This function begins saving graphical output commands in an * internal buffer; the commands are held until a matching astGEBuf * call (or until the buffer is emptied by astGFlush). This can * greatly improve the efficiency of some graphics systems. astGBBuf * increments an internal counter, while astGEBuf decrements this * counter and flushes the buffer to the output device when the * counter drops to zero. astGBBuf and astGEBuf calls should always * be paired. * Parameters: * None. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. *- */ ccpgbbuf(); return 1; } int astGEBuf( void ){ /* *+ * Name: * astGEBuf * Purpose: * End a graphics buffering context. * Synopsis: * #include "grf.h" * int astGEBuf( void ) * Description: * This function marks the end of a batch of graphical output begun * with the last call of astGBBuf. astGBBuf and astGEBUF calls should * always be paired. Each call to astGBBuf increments a counter, while * each call to astGEBuf decrements the counter. When the counter * reaches 0, the batch of output is written on the output device. * Parameters: * None. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. *- */ ccpgebuf(); return 1; } int astGFlush( void ){ /* *+ * Name: * astGFlush * Purpose: * Flush all pending graphics to the output device. * Synopsis: * #include "grf.h" * int astGFlush( void ) * Description: * This function ensures that the display device is up-to-date, * by flushing any pending graphics to the output device. * Parameters: * None. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. *- */ ccpgupdt(); return 1; } int astGCap( int cap, int value ){ /* *+ * Name: * astGCap * Purpose: * Indicate if this grf module has a given capability. * Synopsis: * #include "grf.h" * int astGCap( int cap, int value ) * Description: * This function is called by the AST Plot class to determine if the * grf module has a given capability, as indicated by the "cap" * argument. * Parameters: * cap * The capability being inquired about. This will be one of the * following constants defined in grf.h: * * GRF__SCALES: This function should return a non-zero value if * it implements the astGScales function, and zero otherwise. The * supplied "value" argument should be ignored. * * GRF__MJUST: This function should return a non-zero value if * the astGText and astGTxExt functions recognise "M" as a * character in the justification string. If the first character of * a justification string is "M", then the text should be justified * with the given reference point at the bottom of the bounding box. * This is different to "B" justification, which requests that the * reference point be put on the baseline of the text, since some * characters hang down below the baseline. If the astGText or * astGTxExt function cannot differentiate between "M" and "B", * then this function should return zero, in which case "M" * justification will never be requested by Plot. The supplied * "value" argument should be ignored. * * GRF__ESC: This function should return a non-zero value if the * astGText and astGTxExt functions can recognise and interpret * graphics escape sequences within the supplied string. These * escape sequences are described below. Zero should be returned * if escape sequences cannot be interpreted (in which case the * Plot class will interpret them itself if needed). The supplied * "value" argument should be ignored only if escape sequences cannot * be interpreted by astGText and astGTxExt. Otherwise, "value" * indicates whether astGText and astGTxExt should interpret escape * sequences in subsequent calls. If "value" is non-zero then * escape sequences should be interpreted by astGText and * astGTxExt. Otherwise, they should be drawn as literal text. * Returned Value: * The return value, as described above. Zero should be returned if * the supplied capability is not recognised. * Escape Sequences: * Escape sequences are introduced into the text string by a percent * "%" character. The following escape sequences are currently recognised * ("..." represents a string of one or more decimal digits): * * %% - Print a literal "%" character (type GRF__ESPER ). * * %^...+ - Draw subsequent characters as super-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the super-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text (type GRF__ESSUP ). * %^+ - Draw subsequent characters with the normal base-line. * * %v...+ - Draw subsequent characters as sub-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the sub-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text (type GRF__ESSUB ). * * %v+ - Draw subsequent characters with the normal base-line * (equivalent to %^+). * * %>...+ - Leave a gap before drawing subsequent characters. * The digits "..." give the size of the gap, scaled * so that a value of "100" corresponds to the height of * "normal" text (type GRF__ESGAP ). * * %<...+ - Move backwards before drawing subsequent characters. * The digits "..." give the size of the movement, scaled * so that a value of "100" corresponds to the height of * "normal" text (type GRF_ESBAC). * * %s...+ - Change the Size attribute for subsequent characters. The * digits "..." give the new Size as a fraction of the * "normal" Size, scaled so that a value of "100" corresponds * to 1.0 (type GRF__ESSIZ ). * * %s+ - Reset the Size attribute to its "normal" value. * * %w...+ - Change the Width attribute for subsequent characters. The * digits "..." give the new width as a fraction of the * "normal" Width, scaled so that a value of "100" corresponds * to 1.0 (type GRF__ESWID ). * * %w+ - Reset the Size attribute to its "normal" value. * * %f...+ - Change the Font attribute for subsequent characters. The * digits "..." give the new Font value (type GRF__ESFON ). * * %f+ - Reset the Font attribute to its "normal" value. * * %c...+ - Change the Colour attribute for subsequent characters. The * digits "..." give the new Colour value (type GRF__ESCOL ). * * %c+ - Reset the Colour attribute to its "normal" value. * * %t...+ - Change the Style attribute for subsequent characters. The * digits "..." give the new Style value (type GRF__ESSTY ). * * %t+ - Reset the Style attribute to its "normal" value. * * %- - Push the current graphics attribute values onto the top of * the stack - see "%+" (type GRF__ESPSH). * * %+ - Pop attributes values of the top the stack - see "%-". If * the stack is empty, "normal" attribute values are restored * (type GRF__ESPOP). * * The astFindEscape function (in libast.a) can be used to locate escape * sequences within a text string. It has the following signature: * * #include "plot.h" * int astFindEscape( const char *text, int *type, int *value, int *nc ) * * Parameters: * text * Pointer to the string to be checked. * type * Pointer to a location at which to return the type of escape * sequence. Each type is identified by a symbolic constant defined * in grf.h and is indicated in the above section. The returned value * is undefined if the supplied text does not begin with an escape * sequence. * value * Pointer to a lcation at which to return the integer value * associated with the escape sequence. All usable values will be * positive. Zero is returned if the escape sequence has no associated * integer. A value of -1 indicates that the attribute identified by * "type" should be reset to its "normal" value (as established using * the astGAttr function, etc). The returned value is undefined if * the supplied text does not begin with an escape sequence. * nc * Pointer to a location at which to return the number of * characters read by this call. If the text starts with an escape * sequence, the returned value will be the number of characters in * the escape sequence. Otherwise, the returned value will be the * number of characters prior to the first escape sequence, or the * length of the supplied text if no escape sequence is found. * Returned Value: * A non-zero value is returned if the supplied text starts with a * graphics escape sequence, and zero is returned otherwise. *- */ int result = 0; if( cap == GRF__SCALES ) result = 1; return result; } int astGLine( int n, const float *x, const float *y ){ /* *+ * Name: * astGLine * Purpose: * Draw a polyline (i.e. a set of connected lines). * Synopsis: * #include "grf.h" * int astGLine( int n, const float *x, const float *y ) * Description: * This function displays lines joining the given positions. * Parameters: * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. * Notes: * - Nothing is done if "n" is less than 2, or if a NULL pointer is * given for either "x" or "y". *- */ if( n > 1 && x && y ) ccpgline( n, (float *) x, (float *) y ); return 1; } int astGMark( int n, const float *x, const float *y, int type ){ /* *+ * Name: * astGMark * Purpose: * Draw a set of markers. * Synopsis: * #include "grf.h" * int astGMark( int n, const float *x, const float *y, int type ) * Description: * This function displays markers at the given positions. * Parameters: * n * The number of markers to draw. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * type * An integer which can be used to indicate the type of marker symbol * required. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. * Notes: * - Nothing is done if "n" is less than 1, or if a NULL pointer is * given for either "x" or "y". *- */ if( n > 0 && x && y ) ccpgpt( n, (float *) x, (float *) y, type ); return 1; } int astGText( const char *text, float x, float y, const char *just, float upx, float upy ){ /* *+ * Name: * astGText * Purpose: * Draw a character string. * Synopsis: * #include "grf.h" * int astGText( const char *text, float x, float y, const char *just, * float upx, float upy ) * Description: * This function displays a character string at a given position * using a specified justification and up-vector. * Parameters: * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. * Notes: * - Any graphics within the rotated box enclosing the text are erased. * - A NULL value for "just" causes a value of "CC" to be used. * - Both "upx" and "upy" being zero causes an error. * - Any unrecognised character in "just" causes an error. *- */ /* Local Variables: */ char lj[ 2 ]; float uplen, xbox[ 4 ], ybox[ 4 ]; float angle, fjust, hu, test, alpha, beta; int i, tbg; /* Check that there is something to draw. */ if( text && text[ 0 ] != 0 ){ /* Fill in any missing parts of the justification string. */ if( just ){ if( just[ 0 ] == 'T' || just[ 0 ] == 'C' || just[ 0 ] == 'B' ){ lj[ 0 ] = just[ 0 ]; } else { astError( AST__GRFER, "astGText: Justification string '%s' is " "invalid.", just ); return 0; } if( just[ 1 ] == 'L' || just[ 1 ] == 'C' || just[ 1 ] == 'R' ){ lj[ 1 ] = just[ 1 ]; } else { astError( AST__GRFER, "astGText: Justification string '%s' " "is invalid.", just ); return 0; } } else { lj[ 0 ] = 'C'; lj[ 1 ] = 'C'; } /* Find the conversion factors between increment in world coordinate axes, and the corresponding increments in millimetres ( Xmm = alpha*Xworld, Ymm = beta*Yworld ). */ if( !astGScales( &alpha, &beta ) ) return 0; /* If either axis is reversed, reverse the supplied up-vector components so that they refer to the world-coordinates axes. */ if( alpha < 0.0 ) upx = -upx; if( beta < 0.0 ) upy = -upy; /* Get the angle between the text base-line and horizontal. */ angle = atan2( -(double) upx*alpha, (double) upy*beta )*R2D; /* Get the fractional horizontal justification as needed by PGPLOT. */ if( lj[ 1 ] == 'L' ) { fjust = 0.0; } else if( lj[ 1 ] == 'R' ) { fjust = 1.0; } else { fjust = 0.5; } /* Unless the requested justification is "Bottom", we need to adjust the supplied reference position before we use it with PGPLOT because PGPLOT assumes "Bottom" justification. */ if( lj[0] != 'B' ) { /* Get the bounding box of the string. Note, only the size of the box is significant here, not its position. Also note, leading and trailing spaces are not included in the bounding box. */ ccpgqtxt( x, y, angle, fjust, (char *) text, xbox, ybox ); /* Normalise the up-vector in world coordinates. */ uplen = sqrt( (double) (upx*upx + upy*upy) ); if( uplen > 0.0 ){ upx /= uplen; upy /= uplen; } else { astError( AST__GRFER, "astGText: Zero length up-vector supplied."); return 0; } /* Find the height of the text above the base-line. Note, the PGPLOT manual is not clear about the order of the corners returned by pgqtxt, so we have to find the largest distance between the corners in the direction of the supplied up-vector. */ hu = 0.0; for( i = 0; i < 4; i++ ){ test = upx*( xbox[ i ] - x ) + upy*( ybox[ i ] - y ); if( test > hu ) hu = test; } /* Adjust the vertical position of the reference point, since PGPLOT requires it to be at the bottom of the text. */ if( lj[ 0 ] == 'T' ){ x -= upx*hu; y -= upy*hu; } else if( lj[ 0 ] == 'C' ){ x -= 0.5*upx*hu; y -= 0.5*upy*hu; } } /* Display the text, erasing any graphics. */ ccpgqtbg( &tbg ); ccpgstbg( 0 ); ccpgptxt( x, y, angle, fjust, (char *) text ); ccpgstbg( tbg ); } /* Return. */ return 1; } int astGScales( float *alpha, float *beta ){ /* *+ * Name: * astGScales * Purpose: * Get the axis scales. * Synopsis: * #include "grf.h" * int astGScales( float *alpha, float *beta ) * Description: * This function returns two values (one for each axis) which scale * increments on the corresponding axis into a "normal" coordinate * system in which: * 1 - The axes have equal scale in terms of (for instance) * millimetres per unit distance. * 2 - X values increase from left to right. * 3 - Y values increase from bottom to top. * Parameters: * alpha * A pointer to the location at which to return the scale for the * X axis (i.e. Xnorm = alpha*Xworld). * beta * A pointer to the location at which to return the scale for the * Y axis (i.e. Ynorm = beta*Yworld). * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. *- */ /* Local Variables: */ float nx1, nx2, ny1, ny2, wx1, wx2, wy1, wy2; int ret; /* Find the conversion factors between increment in world coordinate axes, and the corresponding increments in millimetres ( Xmm = alpha*Xworld, Ymm = beta*Yworld ). */ ccpgqvp( 2, &nx1, &nx2, &ny1, &ny2 ); ccpgqwin( &wx1, &wx2, &wy1, &wy2 ); if( wx2 != wx1 && wy2 != wy1 && nx2 != nx1 && ny2 != ny1 ) { *alpha= ( nx2 - nx1 ) / ( wx2 - wx1 ); *beta = ( ny2 - ny1 ) / ( wy2 - wy1 ); ret = 1; } else { astError( AST__GRFER, "astGScales: The graphics window or viewport has zero size." ); ret = 0; } return ret; } int astGTxExt( const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb ){ /* *+ * Name: * astGTxExt * Purpose: * Get the extent of a character string. * Synopsis: * #include "grf.h" * int astGTxExt( const char *text, float x, float y, const char *just, * float upx, float upy, float *xb, float *yb ) * Description: * This function returns the corners of a box which would enclose the * supplied character string if it were displayed using astGText. * * The returned box INCLUDES any leading or trailing spaces. * Parameters: * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * xb * An array of 4 elements in which to return the x coordinate of * each corner of the bounding box. * yb * An array of 4 elements in which to return the y coordinate of * each corner of the bounding box. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. * Notes: * - The order of the corners is anti-clockwise (in world coordinates) * starting at the bottom left. * - A NULL value for "just" causes a value of "CC" to be used. * - Both "upx" and "upy" being zero causes an error. * - Any unrecognised character in "just" causes an error. * - Zero is returned for all bounds of the box if an error occurs. *- */ /* Local Variables: */ char lj[ 2 ]; float udx, udy, vdx, vdy, vx, vy, uplen, xbox[ 4 ], ybox[ 4 ], uxu, uyu, uxd, uyd, ux, uy; float angle, width, test, xl, yl; float alpha, beta, xc, yc, hu, hd, a, b; int i; /* Initialise the returned values to indicate no box available. */ for( i = 0; i < 4; i++ ){ xb[ i ] = 0.0; yb[ i ] = 0.0; } /* Check that there is something to draw. */ if( text && text[ 0 ] != 0 ){ /* Fill in any missing parts of the justification string. */ if( just ){ if( just[ 0 ] == 'T' || just[ 0 ] == 'C' || just[ 0 ] == 'B' ){ lj[ 0 ] = just[ 0 ]; } else { astError( AST__GRFER, "astGTxExt: Justification string '%s' is " "invalid.", just ); return 0; } if( just[ 1 ] == 'L' || just[ 1 ] == 'C' || just[ 1 ] == 'R' ){ lj[ 1 ] = just[ 1 ]; } else { astError( AST__GRFER, "astGTxExt: Justification string '%s' is " "invalid.", just ); return 0; } } else { lj[ 0 ] = 'C'; lj[ 1 ] = 'C'; } /* Find the conversion factors between increment in world coordinate axes, and the corresponding increments in millimetres ( Xmm = alpha*Xworld, Ymm = beta*Yworld ). */ if( !astGScales( &alpha, &beta ) ) return 0; /* If either axis is reversed, reverse the supplied up-vector components so that they refer to the world-coordinates axes. */ if( alpha < 0.0 ) upx = -upx; if( beta < 0.0 ) upy = -upy; /* Convert the up-vector into millimetres. */ ux = alpha*upx; uy = beta*upy; /* Normalise the up-vector to a length of 1 millimetre. */ uplen = sqrt( (double) (ux*ux + uy*uy) ); if( uplen > 0.0 ){ ux /= uplen; uy /= uplen; } else { astError( AST__GRFER, "astGText: Zero length up-vector supplied."); return 0; } /* Form the base-line vector by rotating the up-vector by 90 degrees clockwise. */ vx = uy; vy = -ux; /* Get the angle between the text base-line and horizontal. */ angle = atan2( (double) vy, (double) vx )*R2D; /* Get the bounding box of the string drawn with its bottom left corner at the origin. */ ccpgqtxt( 0.0, 0.0, angle, 0.0, (char *) text, xbox, ybox ); /* Convert the returned bounding box world coordinates into millimetres. */ for( i = 0; i < 4; i++ ){ xbox[ i ] *= alpha; ybox[ i ] *= beta; } /* Find the height of the bounding box, in millimetres. Note, the PGPLOT manual is not clear about the order of the corners returned by pgqtxt, so we have to find the largest distance between the corners in the direction of the supplied up-vector. The reference point is on the text base-line which is not usually at the bottom of the bounding box (some letters - like "y" - extend below the base-line). Find the distance from the base-line to the top (hu) and bottom (hd) of the bounding box. */ hu = -FLT_MAX; hd = FLT_MAX; for( i = 0; i < 4; i++ ){ test = ux*xbox[ i ] + uy*ybox[ i ]; if( test > hu ) hu = test; if( test < hd ) hd = test; } /* Get an up and a down vector scaled to the height/depth of the bounding box above/below the text base-line . */ uxu = ux*hu; uyu = uy*hu; uxd = ux*hd; uyd = uy*hd; /* The bounding box returned by pgqtxt does not include any leading or trailing spaces. We need to include such spaces in the returned box. To do this we get the length of the text string in millimetres using pglen instead of using the bounding box returned by pgqtxt. */ ccpglen( 2, (char *) text, &xl, &yl ); /* The abolute width of the string in millimetres may depend on the up-vector. The values returned by pglen are for horizontal and vertical text. Find the width using the supplied up-vector. */ a = uy*xl; b = ux*yl; width = sqrt( a*a + b*b ); /* The pglen function returns a value which is slightly smaller than the area cleared to hold the text when written using pgptxt. Increase the text width so that it is about equal to the area cleared. */ width += 0.2*hu; /* Scale the base-line vector so that its length is equal to the width of the bounding box (including spaces). */ vx *= width; vy *= width; /* Convert the base-line vector back into world coordinates. */ vx /= alpha; vy /= beta; /* Convert the up and down vectors into world coordinates. */ uxu /= alpha; uyu /= beta; uxd /= alpha; uyd /= beta; /* Find the coordinates at the centre of the bounding box in world coordinates. */ xc = x; yc = y; if( lj[0] == 'B' ) { xc += 0.5*uxu; yc += 0.5*uyu; } else if( lj[0] == 'T' ) { xc -= 0.5*uxu; yc -= 0.5*uyu; } if( lj[1] == 'L' ) { xc += 0.5*vx; yc += 0.5*vy; } else if( lj[1] == 'R' ) { xc -= 0.5*vx; yc -= 0.5*vy; } /* Get the corners of the bounding box. */ vdx = 0.5*vx; vdy = 0.5*vy; udx = 0.5*uxu; udy = 0.5*uyu; /* Bottom left corner... */ xb[ 0 ] = xc - vdx - udx + uxd; yb[ 0 ] = yc - vdy - udy + uyd; /* Bottom right corner... */ xb[ 1 ] = xc + vdx - udx + uxd; yb[ 1 ] = yc + vdy - udy + uyd; /* Top right corner... */ xb[ 2 ] = xc + vdx + udx; yb[ 2 ] = yc + vdy + udy; /* Top left corner... */ xb[ 3 ] = xc - vdx + udx; yb[ 3 ] = yc - vdy + udy; } /* Return. */ return 1; } int astGQch( float *chv, float *chh ){ /* *+ * Name: * astGQch * Purpose: * Return the character height in world coordinates. * Synopsis: * #include "grf.h" * int astGQch( float *chv, float *chh ) * Description: * This function returns the heights of characters drawn vertically and * horizontally in world coordinates. * Parameters: * chv * A pointer to the double which is to receive the height of * characters drawn with a vertical baseline . This will be an * increment in the X axis. * chh * A pointer to the double which is to receive the height of * characters drawn with a horizontal baseline. This will be an * increment in the Y axis. * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. *- */ /* Local Variables: */ float vx1,vx2,vy1,vy2,wx1,wx2,wy1,wy2; /* Get the character height in normalised device coordinates */ ccpgqcs( 0, chv, chh ); /* Get the bounds of the PGPLOT viewport in normalised device coordinates. */ ccpgqvp( 0, &vx1, &vx2, &vy1, &vy2 ); /* Get the bounds of the PGPLOT window in world coordinates. */ ccpgqwin( &wx1, &wx2, &wy1, &wy2 ); /* Convert the text height from normalised device coordinates into world coordinates for vertical text. Print an error message if the viewport has zero size. */ if( vx1 != vx2 ){ *chv *= ( wx2 - wx1 )/( vx2 - vx1 ); } else { astError( AST__GRFER, "astGQch: The graphics viewport has zero size " "in the X direction."); return 0; } /* Convert the text height from normalised device coordinates into world coordinates for horizontal text. Print an error message if the viewport has zero size. */ if( vy1 != vy2 ){ *chh *= ( wy2 - wy1 )/( vy2 - vy1 ); } else { astError( AST__GRFER, "astGQch: The graphics viewport has zero size " "in the Y direction."); return 0; } /* Return. */ return 1; } int astGAttr( int attr, double value, double *old_value, int prim ){ /* *+ * Name: * astGAttr * Purpose: * Enquire or set a graphics attribute value. * Synopsis: * #include "grf.h" * int int astGAttr( int attr, double value, double *old_value, int prim ) * Description: * This function returns the current value of a specified graphics * attribute, and optionally establishes a new value. The supplied * value is converted to an integer value if necessary before use. * Parameters: * attr * An integer value identifying the required attribute. The * following symbolic values are defined in grf.h: * * GRF__STYLE - Line style. * GRF__WIDTH - Line width. * GRF__SIZE - Character and marker size scale factor. * GRF__FONT - Character font. * GRF__COLOUR - Colour index. * value * A new value to store for the attribute. If this is AST__BAD * no value is stored. * old_value * A pointer to a double in which to return the attribute value. * If this is NULL, no value is returned. * prim * The sort of graphics primitive to be drawn with the new attribute. * Identified by the following values defined in grf.h: * GRF__LINE * GRF__MARK * GRF__TEXT * Returned Value: * A value of 0 is returned if an error occurs, and 1 is returned * otherwise. * Notes: *- */ int ival; float rval, dx, dy, deflw, x1, x2, y1, y2; /* If required retrieve the current line style, and set a new line style. */ if( attr == GRF__STYLE ){ ccpgqls( &ival ); if( old_value ) *old_value = (double) ival; if( value != AST__BAD ){ ival = (int) ( value + 0.5 ); if( value < 0.0 ) ival -= 1; ival = ( ival - 1 ) % 5; ival += ( ival < 0 ) ? 6 : 1; ccpgsls( ival ); } /* If required retrieve the current line width, and set a new line width. Line width is stored in Plot as a scale factor (1.0 for the default line width which is a fixed fraction of the diagonal of the view surface), but pgplot stores it in units of 0.005 of an inch. */ } else if( attr == GRF__WIDTH ){ /* Get the bounds of the view surface in inches. */ ccpgqvsz( 1, &x1, &x2, &y1, &y2 ); /* Find the default line width in inches (i.e. 0.0005 of the length of the view surface diagonal). */ dx = ( x1 - x2 ); dy = ( y1 - y2 ); deflw = 0.0005*sqrt( (double )( dx*dx + dy*dy ) ); /* Get the current pgplot line width in units of 0.005 of an inch. */ ccpgqlw( &ival ); /* If required, return the factor by which this exceeds the default line width found above. */ if( old_value ) *old_value = (double)( ival )/( 200.0 * deflw ); /* If a new line width has been provided, the pgplot line width needs to be set to the corresponding absolute value. */ if( value != AST__BAD ){ ival = (int) ( 200.0*value*deflw ); if( ival < 1 ) { ival = 1; } else if( ival > 201 ){ ival = 201; } ccpgslw( ival ); } /* If required retrieve the current character size, and set a new size. The attribute value should be a factor by which to multiply the default character size. */ } else if( attr == GRF__SIZE ){ ccpgqch( &rval ); if( old_value ) *old_value = (double) rval; if( value != AST__BAD ){ ccpgsch( (float) value ); } /* If required retrieve the current character font, and set a new font. */ } else if( attr == GRF__FONT ){ ccpgqcf( &ival ); if( old_value ) *old_value = (double) ival; if( value != AST__BAD ){ ival = (int) ( value + 0.5 ); if( value < 0.0 ) ival -= 1; ival = ( ival - 1 ) % 4; ival += ( ival < 0 ) ? 5 : 1; ccpgscf( ival ); } /* If required retrieve the current colour index, and set a new colour index. */ } else if( attr == GRF__COLOUR ){ ccpgqci( &ival ); if( old_value ) *old_value = (double) ival; if( value != AST__BAD ){ ival = (int) ( value + 0.5 ); if( ival < 0 ) ival = 1; ccpgsci( ival ); } /* Give an error message for any other attribute value. */ } else { astError( AST__GRFER, "astGAttr: Unknown graphics attribute '%d' " "requested.", attr ); return 0; } /* Return. */ return 1; } /* Local Functions. */ /* ================ */ /* These implement the local C interface to PGPLOT in terms of its native Fortran interface. Only those PGPLOT functions used within this module are included. */ static void ccpgline(int n, float xpts[], float ypts[] ){ F77_INTEGER_TYPE N; F77_REAL_TYPE *XX; F77_REAL_TYPE *YY; int i; XX = (F77_REAL_TYPE *) astMalloc( sizeof( F77_REAL_TYPE )*(size_t) n ); YY = (F77_REAL_TYPE *) astMalloc( sizeof( F77_REAL_TYPE )*(size_t) n ); if( astOK ){ for( i = 0; i < n; i++ ){ XX[ i ] = (F77_REAL_TYPE) xpts[ i ]; YY[ i ] = (F77_REAL_TYPE) ypts[ i ]; } N = (F77_INTEGER_TYPE) n; F77_CALL(pgline)( INTEGER_ARG(&N), REAL_ARRAY_ARG(XX), REAL_ARRAY_ARG(YY) ); XX = (F77_REAL_TYPE *) astFree( (void *) XX ); YY = (F77_REAL_TYPE *) astFree( (void *) YY ); } } static void ccpgpt(int n, float xpts[], float ypts[], int symbol){ F77_INTEGER_TYPE N; F77_REAL_TYPE *XX; F77_REAL_TYPE *YY; F77_INTEGER_TYPE SYMBOL; int i; XX = (F77_REAL_TYPE *) astMalloc( sizeof( F77_REAL_TYPE )*(size_t) n ); YY = (F77_REAL_TYPE *) astMalloc( sizeof( F77_REAL_TYPE )*(size_t) n ); if( astOK ){ for( i = 0; i < n; i++ ){ XX[ i ] = (F77_REAL_TYPE) xpts[ i ]; YY[ i ] = (F77_REAL_TYPE) ypts[ i ]; } N = (F77_INTEGER_TYPE) n; SYMBOL = (F77_INTEGER_TYPE) symbol; F77_CALL(pgpt)( INTEGER_ARG(&N), REAL_ARRAY_ARG(XX), REAL_ARRAY_ARG(YY), INTEGER_ARG(&SYMBOL) ); XX = (F77_REAL_TYPE *) astFree( (void *) XX ); YY = (F77_REAL_TYPE *) astFree( (void *) YY ); } } static void ccpgptxt(float x, float y, float angle, float fjust, char *text ){ F77_REAL_TYPE X; F77_REAL_TYPE Y; F77_REAL_TYPE ANGLE; F77_REAL_TYPE FJUST; DECLARE_CHARACTER(LTEXT,MXSTRLEN); int ftext_length; X = (F77_REAL_TYPE) x; Y = (F77_REAL_TYPE) y; ANGLE = (F77_REAL_TYPE) angle; FJUST = (F77_REAL_TYPE) fjust; ftext_length = strlen( text ); if( ftext_length > LTEXT_length ) ftext_length = LTEXT_length; astStringExport( text, LTEXT, ftext_length ); F77_CALL(pgptxt)( REAL_ARG(&X), REAL_ARG(&Y), REAL_ARG(&ANGLE), REAL_ARG(&FJUST), CHARACTER_ARG(LTEXT) TRAIL_ARG(ftext) ); } static void ccpgqtxt(float x, float y, float angle, float fjust, char *text, float xbox[], float ybox[]){ F77_REAL_TYPE X; F77_REAL_TYPE Y; F77_REAL_TYPE ANGLE; F77_REAL_TYPE FJUST; DECLARE_CHARACTER(LTEXT,MXSTRLEN); F77_REAL_TYPE XBOX[ 4 ]; F77_REAL_TYPE YBOX[ 4 ]; int i; int ftext_length; X = (F77_REAL_TYPE) x; Y = (F77_REAL_TYPE) y; ANGLE = (F77_REAL_TYPE) angle; FJUST = (F77_REAL_TYPE) fjust; ftext_length = strlen( text ); if( ftext_length > LTEXT_length ) ftext_length = LTEXT_length; astStringExport( text, LTEXT, ftext_length ); F77_CALL(pgqtxt)( REAL_ARG(&X), REAL_ARG(&Y), REAL_ARG(&ANGLE), REAL_ARG(&FJUST), CHARACTER_ARG(LTEXT), REAL_ARRAY_ARG(XBOX), REAL_ARRAY_ARG(YBOX) TRAIL_ARG(ftext) ); for( i = 0; i < 4; i++ ){ xbox[ i ] = (float) XBOX[ i ]; ybox[ i ] = (float) YBOX[ i ]; } } static void ccpgqtbg(int *tbci){ F77_INTEGER_TYPE TBCI; F77_CALL(pgqtbg)( INTEGER_ARG(&TBCI) ); *tbci = (int) TBCI; } static void ccpgstbg(int tbci){ F77_INTEGER_TYPE TBCI; TBCI = (F77_INTEGER_TYPE) tbci; F77_CALL(pgstbg)( INTEGER_ARG(&TBCI) ); } static void ccpgqcs(int units, float *xch, float *ych){ F77_INTEGER_TYPE UNITS; F77_REAL_TYPE XCH; F77_REAL_TYPE YCH; UNITS = (F77_INTEGER_TYPE) units; F77_CALL(pgqcs)( INTEGER_ARG(&UNITS), REAL_ARG(&XCH), REAL_ARG(&YCH) ); *xch = (float) XCH; *ych = (float) YCH; } static void ccpglen(int units, char *text, float *xl, float *yl ){ F77_INTEGER_TYPE UNITS; F77_REAL_TYPE XL; F77_REAL_TYPE YL; DECLARE_CHARACTER(LTEXT,MXSTRLEN); int ftext_length; UNITS = (F77_INTEGER_TYPE) units; ftext_length = strlen( text ); if( ftext_length > LTEXT_length ) ftext_length = LTEXT_length; astStringExport( text, LTEXT, ftext_length ); F77_CALL(pglen)( INTEGER_ARG(&UNITS), CHARACTER_ARG(LTEXT), REAL_ARG(&XL), REAL_ARG(&YL) TRAIL_ARG(ftext) ); *xl = (float) XL; *yl = (float) YL; } static void ccpgqvp(int units, float *x1, float *x2, float *y1, float *y2){ F77_INTEGER_TYPE UNITS; F77_REAL_TYPE X1; F77_REAL_TYPE X2; F77_REAL_TYPE Y1; F77_REAL_TYPE Y2; UNITS = (F77_INTEGER_TYPE) units; F77_CALL(pgqvp)( INTEGER_ARG(&UNITS), REAL_ARG(&X1), REAL_ARG(&X2), REAL_ARG(&Y1), REAL_ARG(&Y2) ); *x1 = (float) X1; *x2 = (float) X2; *y1 = (float) Y1; *y2 = (float) Y2; } static void ccpgqvsz(int units, float *x1, float *x2, float *y1, float *y2){ F77_INTEGER_TYPE UNITS; F77_REAL_TYPE X1; F77_REAL_TYPE X2; F77_REAL_TYPE Y1; F77_REAL_TYPE Y2; UNITS = (F77_INTEGER_TYPE) units; F77_CALL(pgqvsz)( INTEGER_ARG(&UNITS), REAL_ARG(&X1), REAL_ARG(&X2), REAL_ARG(&Y1), REAL_ARG(&Y2) ); *x1 = (float) X1; *x2 = (float) X2; *y1 = (float) Y1; *y2 = (float) Y2; } static void ccpgqwin(float *x1, float *x2, float *y1, float *y2){ F77_REAL_TYPE X1; F77_REAL_TYPE X2; F77_REAL_TYPE Y1; F77_REAL_TYPE Y2; F77_CALL(pgqwin)( REAL_ARG(&X1), REAL_ARG(&X2), REAL_ARG(&Y1), REAL_ARG(&Y2) ); *x1 = (float) X1; *x2 = (float) X2; *y1 = (float) Y1; *y2 = (float) Y2; } static void ccpgqls(int *ls){ F77_INTEGER_TYPE LS; F77_CALL(pgqls)( INTEGER_ARG(&LS) ); *ls = (int) LS; } static void ccpgsls(int ls){ F77_INTEGER_TYPE LS; LS = (F77_INTEGER_TYPE) ls; F77_CALL(pgsls)( INTEGER_ARG(&LS) ); } static void ccpgqlw(int *lw){ F77_INTEGER_TYPE LW; F77_CALL(pgqlw)( INTEGER_ARG(&LW) ); *lw = (int) LW; } static void ccpgslw(int lw){ F77_INTEGER_TYPE LW; LW = (F77_INTEGER_TYPE) lw; F77_CALL(pgslw)( INTEGER_ARG(&LW) ); } static void ccpgqch(float *ch){ F77_REAL_TYPE CH; F77_CALL(pgqch)( REAL_ARG(&CH) ); *ch = (float) CH; } static void ccpgsch(float ch){ F77_REAL_TYPE CH; CH = (F77_REAL_TYPE) ch; F77_CALL(pgsch)( REAL_ARG(&CH) ); } static void ccpgqcf(int *cf){ F77_INTEGER_TYPE CF; F77_CALL(pgqcf)( INTEGER_ARG(&CF) ); *cf = (int) CF; } static void ccpgscf(int cf){ F77_INTEGER_TYPE CF; CF = (F77_INTEGER_TYPE) cf; F77_CALL(pgscf)( INTEGER_ARG(&CF) ); } static void ccpgqci(int *ci){ F77_INTEGER_TYPE CI; F77_CALL(pgqci)( INTEGER_ARG(&CI) ); *ci = (int) CI; } static void ccpgsci(int ci){ F77_INTEGER_TYPE CI; CI = (F77_INTEGER_TYPE) ci; F77_CALL(pgsci)( INTEGER_ARG(&ci) ); } static void ccpgupdt( void ){ F77_CALL(pgupdt)(); } static void ccpgbbuf( void ){ F77_CALL(pgbbuf)(); } static void ccpgebuf( void ){ F77_CALL(pgebuf)(); } ast-8.3.0/fitstable.h0000664000175000017500000001776513004147321011375 00000000000000#if !defined( FITSTABLE_INCLUDED ) /* Include this file only once */ #define FITSTABLE_INCLUDED /* *+ * Name: * fitstable.h * Type: * C include file. * Purpose: * Define the interface to the FitsTable class. * Invocation: * #include "fitstable.h" * Description: * This include file defines the interface to the FitsTable class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The FitsTable class inherits from the Table class. * Copyright: * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 25-NOV-2010 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "table.h" /* Parent class */ #include "fitschan.h" #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* FitsTable structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstFitsTable { /* Attributes inherited from the parent class. */ AstTable table; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstFitsChan *header; /* FitsChan containing table headers */ } AstFitsTable; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstFitsTableVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstTableVtab table_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstFitsChan *(* GetTableHeader)( AstFitsTable *, int * ); void (* PutTableHeader)( AstFitsTable *, AstFitsChan *, int * ); int (* ColumnNull)( AstFitsTable *, const char *, int, int, int *, int *, int * ); size_t (* ColumnSize)( AstFitsTable *, const char *, int * ); void (* GetColumnData)( AstFitsTable *, const char *, float, double, size_t, void *, int *, int * ); void (* PutColumnData)( AstFitsTable *, const char *, int, size_t, void *, int * ); } AstFitsTableVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstFitsTableGlobals { AstFitsTableVtab Class_Vtab; int Class_Init; } AstFitsTableGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitFitsTableGlobals_( AstFitsTableGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(FitsTable) /* Check class membership */ astPROTO_ISA(FitsTable) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstFitsTable *astFitsTable_( void *, const char *, int *, ...); #else AstFitsTable *astFitsTableId_( void *, const char *, ... )__attribute__((format(printf,2,3))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstFitsTable *astInitFitsTable_( void *, size_t, int, AstFitsTableVtab *, const char *, AstFitsChan *, int * ); /* Vtab initialiser. */ void astInitFitsTableVtab_( AstFitsTableVtab *, const char *, int * ); /* Loader. */ AstFitsTable *astLoadFitsTable_( void *, size_t, AstFitsTableVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstFitsChan *astGetTableHeader_( AstFitsTable *, int * ); void astPutTableHeader_( AstFitsTable *, AstFitsChan *, int * ); int astColumnNull_( AstFitsTable *, const char *, int, int, int *, int *, int * ); size_t astColumnSize_( AstFitsTable *, const char *, int * ); void astGetColumnData_( AstFitsTable *, const char *, float, double, size_t, void *, int *, int * ); void astPutColumnData_( AstFitsTable *, const char *, int, size_t, void *, int * ); /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckFitsTable(this) astINVOKE_CHECK(FitsTable,this,0) #define astVerifyFitsTable(this) astINVOKE_CHECK(FitsTable,this,1) /* Test class membership. */ #define astIsAFitsTable(this) astINVOKE_ISA(FitsTable,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astFitsTable astINVOKE(F,astFitsTable_) #else #define astFitsTable astINVOKE(F,astFitsTableId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitFitsTable(mem,size,init,vtab,name,header) \ astINVOKE(O,astInitFitsTable_(mem,size,init,vtab,name,header,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitFitsTableVtab(vtab,name) astINVOKE(V,astInitFitsTableVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadFitsTable(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadFitsTable_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckFitsTable to validate FitsTable pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astGetTableHeader(this) \ astINVOKE(O,astGetTableHeader_(astCheckFitsTable(this),STATUS_PTR)) #define astPutTableHeader(this,header) \ astINVOKE(V,astPutTableHeader_(astCheckFitsTable(this),astCheckFitsChan(header),STATUS_PTR)) #define astColumnNull(this,column,set,newval,wasset,hasnull) \ astINVOKE(V,astColumnNull_(astCheckFitsTable(this),column,set,newval,wasset,hasnull,STATUS_PTR)) #define astColumnSize(this,column) \ astINVOKE(V,astColumnSize_(astCheckFitsTable(this),column,STATUS_PTR)) #define astGetColumnData(this,column,fnull,dnull,mxsize,coldata,nelem) \ astINVOKE(V,astGetColumnData_(astCheckFitsTable(this),column,fnull,dnull,mxsize,coldata,nelem,STATUS_PTR)) #define astPutColumnData(this,column,clen,size,coldata) \ astINVOKE(V,astPutColumnData_(astCheckFitsTable(this),column,clen,size,coldata,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/err_null.c0000664000175000017500000000624113004147321011220 00000000000000/* * Name: * err_null.c * Purpose: * Implement the default "err" module. * Description: * This file implements the default "err" module for the AST * library. It is used to deliver error messages if no alternative * error delivery mechanism is provided. * * To provide an alternative mechanism, re-implement this module * and link your program against the resulting library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (STARLINK) * {enter_new_authors_here} * History: * 6-NOV-1996 (DSB): * Original version. * {enter_changes_here} */ /* Module Macros. */ /* ============== */ /* Define the astCLASS macro (even although this is not a class implementation). This indicates to header files that they should make "protected" symbols available. */ #define astCLASS /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "err.h" /* Interface to this module */ #include "error.h" /* Interface to the error module */ /* C header files. */ /* --------------- */ #include /* Function implementations. */ /* ========================= */ void astPutErr_( int status_value, const char *message ) { /* *+ * Name: * astPutErr * Purpose: * Deliver an error message. * Type: * Protected function. * Synopsis: * #include "err.h" * void astPutErr( int status_value, const char *message ) * Description: * This function delivers an error message and (optionally) an * accompanying status value to the user. It may be re-implemented * in order to deliver error messages in different ways, according * to the environment in which the AST library is being used. * Parameters: * status_value * The error status value. * message * A pointer to a null-terminated character string containing * the error message to be delivered. This should not contain * newline characters. * Notes: * - This function is documented as "protected" but, in fact, is * publicly accessible so that it may be re-implemented as * required. *- */ /* This is the default implementation. Simply write the message to standard error with a newline appended. Ignore the status value. */ int *status = astGetStatusPtr; (void) fprintf( stderr, "%s%s\n", astOK ? "!! " : "! ", message ); } ast-8.3.0/funitmap.c0000664000175000017500000000606213004147321011222 00000000000000/* *+ * Name: * funitmap.c * Purpose: * Define a FORTRAN 77 interface to the AST UnitMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the UnitMap class. * Routines Defined: * AST_ISAUNITMAP * AST_UNITMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 25-SEP-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "unitmap.h" /* C interface to the UnitMap class */ F77_LOGICAL_FUNCTION(ast_isaunitmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAUNITMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAUnitMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_unitmap)( INTEGER(NCOORD), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NCOORD) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_UNITMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astUnitMap( *NCOORD, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/funitnormmap.c0000664000175000017500000000640313004147321012115 00000000000000/* *+ * Name: * fshiftmap.c * Purpose: * Define a FORTRAN 77 interface to the AST UnitNormMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the UnitNormMap class. * Routines Defined: * AST_ISAUNITNORMMAP * AST_UNITNORMMAP * Copyright: * Copyright (C) 2016 AURA/LSST * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * TIMJ: Tim Jenness (LSST) * History: * 18-AUG-2003 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "unitnormmap.h" /* C interface to the UnitNormMap class */ F77_LOGICAL_FUNCTION(ast_isaunitnormmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAUNITNORMMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAUnitNormMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_unitnormmap)( INTEGER(NCOORDS), DOUBLE(CENTRE), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NCOORDS) GENPTR_DOUBLE(CENTRE) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_UNITNORMMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astUnitNormMap( *NCOORDS, CENTRE, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/stcschan.h0000664000175000017500000002513713004147321011216 00000000000000#if !defined( STCSCHAN_INCLUDED ) /* Include this file only once */ #define STCSCHAN_INCLUDED /* *+ * Name: * stcschan.h * Type: * C include file. * Purpose: * Define the interface to the StcsChan class. * Invocation: * #include "stcschan.h" * Description: * This include file defines the interface to the StcsChan class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The StcsChan class provides facilities for reading and writing AST * Objects in the form of STC-S text. * Inheritance: * The StcsChan class inherits from the Channel class. * Copyright: * Copyright (C) 2008 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (JAC, UCLan) * History: * 18-DEC-2008 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" /* I/O channels (parent class) */ /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ------- */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define constants used to size global arrays in this module. */ /* Define other numerical constants for use in this module. */ #define AST__STCSCHAN_GETATTRIB_BUFF_LEN 200 /* Type Definitions. */ /* ================= */ /* StcsChan structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStcsChan { /* Attributes inherited from the parent class. */ AstChannel channel; /* Parent class structure */ /* Attributes specific to objects in this class. */ int stcsarea; /* Read the STC CoordinatesArea? */ int stcscoords; /* Read the STC Coordinates? */ int stcsprops; /* Read the STC-S properties? */ int stcslength; /* Line length */ } AstStcsChan; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcsChanVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstChannelVtab channel_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ int (* GetStcsArea)( AstStcsChan *, int * ); int (* TestStcsArea)( AstStcsChan *, int * ); void (* ClearStcsArea)( AstStcsChan *, int * ); void (* SetStcsArea)( AstStcsChan *, int, int * ); int (* GetStcsCoords)( AstStcsChan *, int * ); int (* TestStcsCoords)( AstStcsChan *, int * ); void (* ClearStcsCoords)( AstStcsChan *, int * ); void (* SetStcsCoords)( AstStcsChan *, int, int * ); int (* GetStcsProps)( AstStcsChan *, int * ); int (* TestStcsProps)( AstStcsChan *, int * ); void (* ClearStcsProps)( AstStcsChan *, int * ); void (* SetStcsProps)( AstStcsChan *, int, int * ); int (* GetStcsLength)( AstStcsChan *, int * ); int (* TestStcsLength)( AstStcsChan *, int * ); void (* ClearStcsLength)( AstStcsChan *, int * ); void (* SetStcsLength)( AstStcsChan *, int, int * ); } AstStcsChanVtab; #if defined(THREAD_SAFE) typedef struct AstStcsChanGlobals { AstStcsChanVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__STCSCHAN_GETATTRIB_BUFF_LEN + 1 ]; } AstStcsChanGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(StcsChan) /* Check class membership */ astPROTO_ISA(StcsChan) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstStcsChan *astStcsChan_( const char *(*)( void ), void (*)( const char * ), const char *, int *, ...); #else AstStcsChan *astStcsChanId_( const char *(*)( void ), void (*)( const char * ), const char *, ... ); AstStcsChan *astStcsChanForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStcsChan *astInitStcsChan_( void *, size_t, int, AstStcsChanVtab *, const char *, const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), int * ); /* Vtab initialiser. */ void astInitStcsChanVtab_( AstStcsChanVtab *, const char *, int * ); /* Loader. */ AstStcsChan *astLoadStcsChan_( void *, size_t, AstStcsChanVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitStcsChanGlobals_( AstStcsChanGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ int astGetStcsArea_( AstStcsChan *, int * ); int astTestStcsArea_( AstStcsChan *, int * ); void astClearStcsArea_( AstStcsChan *, int * ); void astSetStcsArea_( AstStcsChan *, int, int * ); int astGetStcsCoords_( AstStcsChan *, int * ); int astTestStcsCoords_( AstStcsChan *, int * ); void astClearStcsCoords_( AstStcsChan *, int * ); void astSetStcsCoords_( AstStcsChan *, int, int * ); int astGetStcsProps_( AstStcsChan *, int * ); int astTestStcsProps_( AstStcsChan *, int * ); void astClearStcsProps_( AstStcsChan *, int * ); void astSetStcsProps_( AstStcsChan *, int, int * ); int astGetStcsLength_( AstStcsChan *, int * ); int astTestStcsLength_( AstStcsChan *, int * ); void astClearStcsLength_( AstStcsChan *, int * ); void astSetStcsLength_( AstStcsChan *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStcsChan(this) astINVOKE_CHECK(StcsChan,this,0) #define astVerifyStcsChan(this) astINVOKE_CHECK(StcsChan,this,1) /* Test class membership. */ #define astIsAStcsChan(this) astINVOKE_ISA(StcsChan,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astStcsChan astINVOKE(F,astStcsChan_) #else #define astStcsChan astINVOKE(F,astStcsChanId_) #define astStcsChanFor astINVOKE(F,astStcsChanForId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStcsChan(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap) \ astINVOKE(O,astInitStcsChan_(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcsChanVtab(vtab,name) astINVOKE(V,astInitStcsChanVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStcsChan(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStcsChan_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckStcsChan to validate StcsChan pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearStcsArea(this) \ astINVOKE(V,astClearStcsArea_(astCheckStcsChan(this),STATUS_PTR)) #define astGetStcsArea(this) \ astINVOKE(V,astGetStcsArea_(astCheckStcsChan(this),STATUS_PTR)) #define astSetStcsArea(this,value) \ astINVOKE(V,astSetStcsArea_(astCheckStcsChan(this),value,STATUS_PTR)) #define astTestStcsArea(this) \ astINVOKE(V,astTestStcsArea_(astCheckStcsChan(this),STATUS_PTR)) #define astClearStcsCoords(this) \ astINVOKE(V,astClearStcsCoords_(astCheckStcsChan(this),STATUS_PTR)) #define astGetStcsCoords(this) \ astINVOKE(V,astGetStcsCoords_(astCheckStcsChan(this),STATUS_PTR)) #define astSetStcsCoords(this,value) \ astINVOKE(V,astSetStcsCoords_(astCheckStcsChan(this),value,STATUS_PTR)) #define astTestStcsCoords(this) \ astINVOKE(V,astTestStcsCoords_(astCheckStcsChan(this),STATUS_PTR)) #define astClearStcsProps(this) \ astINVOKE(V,astClearStcsProps_(astCheckStcsChan(this),STATUS_PTR)) #define astGetStcsProps(this) \ astINVOKE(V,astGetStcsProps_(astCheckStcsChan(this),STATUS_PTR)) #define astSetStcsProps(this,value) \ astINVOKE(V,astSetStcsProps_(astCheckStcsChan(this),value,STATUS_PTR)) #define astTestStcsProps(this) \ astINVOKE(V,astTestStcsProps_(astCheckStcsChan(this),STATUS_PTR)) #define astClearStcsLength(this) astINVOKE(V,astClearStcsLength_(astCheckStcsChan(this),STATUS_PTR)) #define astGetStcsLength(this) astINVOKE(V,astGetStcsLength_(astCheckStcsChan(this),STATUS_PTR)) #define astSetStcsLength(this,stcslength) astINVOKE(V,astSetStcsLength_(astCheckStcsChan(this),stcslength,STATUS_PTR)) #define astTestStcsLength(this) astINVOKE(V,astTestStcsLength_(astCheckStcsChan(this),STATUS_PTR)) #endif #endif ast-8.3.0/sun211_figures/0000775000175000017500000000000013004147321012064 500000000000000ast-8.3.0/sun211_figures/frameset.pdf0000664000175000017500000006743313004147321014322 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí½]Ìÿ[vT‘ôåM¹âí¢}. 1†>³ß_Ú ­hQI± 5Ö—6^ <‡1¡X´-/¼5\€ $&BcZhazl¸öÊ85= C.$d2ãLÓãÌq>ŸµöÞ¿çj\psf2óÿ­ýìï~Y{­µ×^{­µÿèSxŽOÿµß¾÷æSÿzúüMx®­”šŸþÀ›F~îõ)Ôñï{»¤ÄPž'þRÇs\pÎë»×PîðÛ7µÕç\Ó.yy“Æú¤Œ]ÒÒúÿ0v›{¯oßxI‰_¾ì’”×'e>y›sõk{ò^~ûÆGæ%/o|ì^âsó6ö^ß¾ùýÿü›H´Ä¡É‚ÞÛ%%¶€’ÜgÁÔJEhY¿à…–0Ô‰•,´äôP‚B»M‡½×·o¼¤v|W^’æ`‰·¹*¬”'ïÕa E#ó’…»—øܼM‡½W¢e<ýÉ…šß¹þ÷‡Þ„§é½BѾùž›±bœ‰è™tºÐã%‹è*ˆ.ÆÅh½‘lgÓüöM™YŒe% è‡OÒ 65é°wúöÍ.¹£äå”ôÔ´~l2·Ì&¼O‡ß¾ñqyÉ˹—ì¹Z“¶N7[Ř$KBf…÷NI, ÿÆÁ¬O%eñ²„ƒ '¹‰@¬dáduJ$XIÊ[“¶NR¬$®&ÉÎJú`÷9I¸ä‚HV½:¼°¢yÁBŠÜK|fÞ䆭S!å„\! -2 Ï)Ä´Hî¾)mÕM‹)BO ;¹Öç§À— làªÁöŒ±füÌÏqØïšž×w‹ß”çú8³B¥<ö9®: NÏ­³ŸªÏ%ê7H³?Ç4íOe<À¿E`¶¬¶ÖHÐhA£«zÏk½WI™Ï}ÕDE,=ðÕ¸D-FŸëDõM*yYô³XªÆ…ò‰~VÏkSZ:åwBeñJY´XI £(3I‹’ý^ªAèÆÀî¢ ¶C` [MÌ,Š)«u±Àõ/f@êR=r¾JÖ@‚\ËO5£˜j¿k{îhWТ‡Î†´V«‚²êZHM*æçõo]’º#x}KzšWÊapº¥/¸?óÏkùwê5.lÈ ‘ºT²v­i] ÖÚWõÚ­ÂÒæ2ð:Ö~ƒqwR…´‚Ä]·.Ú°¥.h½¥Æð½†tj,IRYcñÍZ¹Ck:©S´,ÒhUÅ Ÿ³~o•tJ‡¹º!ma·v¤öÔÖ@f›‚à¥8¶¸á¥¸Öän5øWHû]#Ö5 -±£(B[k‰m´í餧-pø‚ׄ]¡¶’ÚÓ’V$Õˆ^¼(€Tç%‹BÖ õh ‰sŸ‰(^d”Ã답óÏ1N¹5ÅÓ‚Á«EÕ)é(u òŒl=ÔÙ´¢¹Eª¶(KÔÎ'ôWûpés«; Ö—N…Þˆ¤E#@RÀ x!8IñÔXL>DäëËqÁ.N*ᔩ¡bi¡cZ[ÑÀß—’´Ð_ÇÂL¤”mÏ…HëyÉ,j\”HbY‚1wû½(¦Y"£E Q}€,— àæTg´MGðØbÉ 4œO+tl·íR]ôÝ°?÷©5æ’¶ó´°d~{ìbñ@> ìZµ­=—§Ö°Å-äÀA«W‰Ÿ˜Á:k™´%-æ_8jK’TÒ’ mí mlPSj%î’E,&O£ý^þl\x@‹~—øÃ*7ÎR”k¨ÅÉѹº¯*«È~k ôéÿMä·îêD~ëSœ¸°¡ß.òj"_€°&z[æ{'G蟊ùÛãO—öÝÎ"RÊS}÷¢ß«{4`.$!?뛌ûb¶!ÙÀuÄ2.Æ[=‚Èh}M•|„½:-pI$ŠÁ«>öÓó÷\µM,âÐoJxü´Á½°F½T…¾”ŠfÏÚ"z*&‡5§DøèÑ0ð Ü(jÖâÚõÛ¿û;žâ›O}ç÷Å7áß~ó©ßñ©ïøŽß±Àïþ­¿õSÿÊÓ·®¿|ǧ_þÄ{ä¯O¾ýÛß|×w>ýæÿáÿý/Ïwü¿ðc?ñïÿ?ïôÿÿŸ¯¾ÿ_}Ë×þÍ?õ ¿øCßþ-ßô#¿ð‹¿ôCßòMÿéßú;¿ô~ÍŸùú7ÿâw=ýî³Ó:3gè¤0¿Ä^dTØ%i4Yâš 8¹ëÐ^ª,vÃnT3ïV›nyø&õ*{°µ¹aëuµá%!ó ÿ²KÒLúÆÚL#Ó^å½:¼NÛ62/Á™¿=|ãsó6÷\­×m|ÊuhJ)GYävI6KE‘Ñ/3å¡. ^SsÞ%˜Òê¬$õï67l½-VÝRâ%É4oo3M™Ë½W‡Zld^²Ðbc÷Ÿ›·¹çÝ`´´§?ù ^^áåc¬P‹¶VGK¬¥1–έIà˶ApU†êœ–š‘@§øpíK\°¨œv(±6¢ ,*Â`Š íi÷+-Q§$w]ºðÔùXÔ6ŒcUŸ¯íÁM}-l€Æ†&lGQ-5Í/ا8™¡©%F×.–°Má(±D¯¬QiúRªä唤¥àÐø´¿ºK`Z%ëhníQ P,mTö a ÑÇfÜ5Ú¤Œáu¥T;N0úÛ\ú÷ÀoZûÒ\]cYÍVÙ¤VÉÄie•ؤ%Ð(µF]¡$,V©Œ;Z¥©¨Ä6•4;l(  êyEàË&#Û„S4º´ÔóŽ‘q:«ó¥°4 SÆET“_ZÃk ò"㈨ ë(â¸A"Ú%¢û» ê£dÈ>:Z*ö‚ƒÑQu`)J]mÄfÛôiqÏO8Äq‚°à²fiÜ¢ãkY»kTŽ/@ý¤‘Š$A#U†µ”+½x”K452´e³K8Œ/@jñª‘hˆZð ùwÃKa¡¥ê”¤ªÍ-V'€Â.š(H0§#…¬yhëû®µtˆù2UåUqº†©j•ÈV—–J[Õ*‘± % ¼†2 „a­Úð[|‘Lx`HP¨Iæ*À$íU.„z TÛœ€çƒÕ†¥"Ûþ®‘Íë ÖÍvÁ ]¤Ã]ç€n·`œ KØ„ƒÕ†ñ(þ®QaŽºZ08…*{ÕU2¸Hai©8 $œÜ´$À Ë´–¦rzè°—O8ž³ˆk’5k!‰Tˆ„F£¢Ãø¢ÃduÕX›Ñ`‹Õ5`|a%‘÷tXô“UM£  Ô&ÉÞ`³‚(î2Y-ÌÂf…qK`õ&Fû«Hp T¤Q%Ênf««¨J0ª·dÂÄj,ù¾ñaÔt´¥ ÑzÆÅ%Ö 5Ècb‹9 ÀÄøÐE ²[y 9–m ¬gôœx…âì„n%•h¸ZƒêÚ¾ª¨6tY®0*ˆúÐdº2ئÕÊU«LXJ)W®&ašÀŠ7® \6’µPÇ|µ>…ÁÍ6†5þ%<}_Øo k–Rrm[XðW %óÚú¶`°Âfø¹¶ïgï » KÐôöê·okôò Z–¤rX7 Ó³M@ û²NŒ F,Œ>’¡8Äq3#®¼Ëæ½8‚X+òعàÌ FýŸëUÁ÷–:V¯ú_ZÃEÉ!q‰Cw„š¼D¸.;?ÜØâBÚÞI¶ÏYY„² ² - …¬Ò´•LÓh¡Ø¥¶%l¥¬Á‘‘ò´Ó±•°…”«F B˜S€ÐÅß]‚ìêmŒzÐÅîV5vag@l¾†¨¬.(@X©)èÙCÝà_O,­T䇥&Q/ùlB©ÒªumS^ÃV %†íZÄ„a¶Û¾³Iær ²“î. ‡çµB4L²Ilû{ ¸Ê¦TN²j­‚(–Zû3d2®¡›mÞ`”\šíõÃ%Zw,³V\Xèëßœd׊uÈ®•qÉO:o•*JN²l!b2åKî2mEi#¹'éÜk1€L$(jÈ-ÛædÜZShÒïA¾ø J Sëjš—KøSØË5a¾²>”KhììÌOü¾æ³w¬!P=»KræUÃÑÒŘºì[qmºfßZháÂ.ÓÚ~¤QØœµÝ½Áï9m Ú¸NRMÂ'2°›4P¹VÉà.ŠYC†®G´¦¸ÏÞý •”cåZbVV®5œB%zÇÌÕÍ\óÂÌÕš™¹þâÏþ3õŸýµ¿ùë¿ù×~Û×ýè7ÿÈßýúOÿ _û-_ßÿÒçÿÕoÿóïgþÇ?øKßûê{?ó¾öÍÿõáW?úðç>úé_þåŸûÜOüåû¹oøÃ?ö³¿åù¾ÿÏý×_øþÏ}ãü•ð“¿î7|ß÷ýз}ög>üà‹~ôÅð»ÿÞõó?ÿ…ÿðÏá/ÿäß 㟫ÿÓ>ýgò'?ó¹ßðoüÀ÷ÿìï-?ó5O¿êc­cÑìWcÈê½]G'X £Y´–¦!³h9Ì‹!^xÉË›ÚØ„»cò&öNß¾ñ’õŒnk^Ò²n”­ÉZÔ„÷éðÛ7>./yyã#÷Ÿ™7é°wz³–fBGIsëyo—ÄPè"±3ÐkGöšuBŽÛoš¹yÉB .SЭ•À9FhS›{¯oßxÉŦä%mêÜÛÄ9±e½: ´hd^´hì^âsó6ö^…–OPò€’1‹5:/§¹¤Ì{tÏ — †‡øƒàŽ$.ƒ›æÙ¸/ñ',‘Ž -ÈFç_=îW[®t QûƒÎ!t Ù%˜ ®£ë?Bô•Y›4&‰oqI^gb?pÁOõ‹èµ¡ó"m$Í(諶0Hž¦rÁØv‰Aw_8¼ì^”fÞ)ë“«`%á‘+.üÛÒð†nUÖa‹£óß6¼xýbР‹\-ÐQO &ÈŸòw€Cÿ°v8øcMQVF7¬Åd‹ð¨ôÇ‚ C¨Ñ¡¢À¤”àܲ(‡tZåÝb´ ‚¿›—ÏÇÌ…Wóg/HÃȺ-i†Ë&:®´EGs‘r„Ã~¯-Õ®åûÓXƒ{¿Að?@ fÒ.­‹ƒj⌼ ò"~Òçé5¤Ê¼cÇV "i g}H$U?[”‘‹À"N3   {T~ê¸lÆ|ÖšŽ¥Sà3uóƒ>»œÖ0S W¢üs‘} îµXKØ,qq?ukØyßØ×z¶¶ÁUÞžà9¯õj!<ÊÃÁ$Ô·‚i“¯/*g#ŠÔÿÿþ=r½öºÇ~µFQéXÚæûÞ*á1o,­ . /op!T; p:°‘-LK§Åå­Ã¸Áìâå]£­ßIÜÎßMö¬ÁûÖA‡¥A:Fáò¼ùTî¾+½¯ÆåwVèרº½ÇúÜ0ü¶’®¿­÷¼XY0ó)§™ÞuQë0úô¾Ú5FáPw ž”B𰸫dÔȼ\¹À dýFj}Ú‚LNÝÁ¹ÊÍ 4 •4Þ £;` T—ä!Ú‚C¦û•— )ÈwyᎿa/¾P æ ÁøÂ9MÁFUIœ¸€Xø‡ßܯp-\¸)õuvû/ª×y?ÈDü½díXŠ|6zã9hdn?½Û¾’íÜD׌²ÿŒË‚B”?†ÌêÕ G \T— «!6ôýX“owócÂò†AÏÚå"½8Ftc÷çaPÚDº7 ÕmÔ¢…œ¼éÀx(2&Mj:`÷]aÅ!<ñ)~¶J†BÅÁI²n-.H‰70˜†°Ö$‡¹yyjÄ’ìä¸9M´ohËvŒŸú°ÉöÑ Ù˜ÀOíŽh'd˜¼[¶{G¸Ÿ0ø ñá—KuÜ]aLÜûWó¶õ³ ü^‹þ÷ÚHåâÅ îX»ë ˜®`4Þ'‹×xÕ5oÍPÅ9™|A!ib0|DD­ÿ=îduUÖ/Û‹ 2© ß&]†»Ô¥ƒ–SÂ/k³é?BŽ9ó©9ͤš$üð÷Æ ƒAÉ4zµ=àM:Ða^èú²šäøiò­hò?=‘swÖ`tïS¿…"êŠÁÍ—zP2Gˆã7Žv uc:r½µ”¥²!Ô_pf/¶6~bï…4x1ÐÔÜ=c ¶ŸÀ›t‘ÿÙpþw[&ì®@l¡4„OØ&°VýÁ‡_þÒW¿òþ¿ÿéÏ° ñóÓ_üeëÏ_üü_úèKßöå¯|ùó_þüþOô§¿üK¿’ãU‚¿”Ò†B"w <¾á…ÒtÌOmQ5þ­Y!Y¿}“‚nx¼dóÔí—D¨ý´¹aëu¡ÚK~KóÔ.Á±mx›ˆÁBoÞ«Ák>2+yy³ÇîßøÜ¬Í [¯Û¸”Z—ÛâRc¼Kš£gÈÑÎÈœJWäšÁkJðÿŽ§Sj6 •D¨¸ý´¹aëuµá%yš5f—$³ôy›v»º{5x¡¥ØÂíû×=v+Ùs³67l½î`ÚOÐòˆ–󻂃vÎk°±‘ا–t"ørƒ|熸@ì,kK^%š†¥ÊïJ`QÄ‹ƒ™×W»K°-¸â’n÷Rè+KöòFD„~´þ.H]8BýÁ<ñ9´Ʋ£¯% Ð80,‚³Êï*Nx£ŸiŸv1i¼(‰pÉø{+29­…)D¶•¼œ°sЀ쫻„:©"Zq5Ûh_X`Â5¨Fe€²BéÑÇæµMÀçºâÓ œ7úpRÍþ·µê¿ q<'o6W³Ýü®à! 'ŸºÎUð»‚+OÙ…Ï~Rq1¿«M**q¿+l¬ð« ñ£ Þ;£|¹Àèn‹ôœFýH°óÏ™¾: Îw‰ê‚Õ«ò»”¹O³™µŸ’ˆàwå!S~W»$éëŽö]PõQ‚%¢#ø]­=Üè¨:P¦ù] \T"¿+ Z~×5A˜1B±³SÖÆ׋j»ktŽÇ’Å$’ö¬‘¹ÒEþê ¦¢ERX¼É[}‡ñŤä®ÄBn #Þ‡ü®N ãŽÐæ&t†Q`NcÀ‹pWXlYùýÔZ:a„z™¨Ò¢##|–~WK€Mºn–<åw•à`T»J–¹à͆p Ì»X‡1øYLx `§HPPd§2p6ù] ¬Š"Hpâi6§5\¹a|œ}O±‘w󫢎 5ˆOIÀ}c‚ãYèlÝža³ ¿«Sq9éjaÃ]~W»«‹EÂmj‹¢ ÐEÄgX ¼S´4ÓC‡u¸|: L/> èÔì.$‘ ‘w£¶a|låªÃ0k$ø]Xæ*)ÃüÐÙË ‹ÎbæÅüaÆÞ ü®¸3áb”ˆ[" ŠÑ,ñW5@‚k^ è‚–²›ÙêÊv(ÁDp1ab5ๆ¶ž” Z_%Œéd ò_gœùi`DÛÓv3h³ñ‹B!% Ž k[GPhÜì„n%•èw•pgÎí«ˆjÍËŒ£‚\?D¼Á6­V®%˜ÀÀ½I,FpM´e­xãÚÐ}ÈF²êø]¥g®½1,yòÜ÷¾àÐÞ’„ìm!a®àJ DÀÞîm!]Xa3½œmÁú9»‚hH ê‡ß{;€?òtµ-¹ZÁn¤VT±‡ DÏêKIqb¢åp&'¦*?õÃŒ© Mâ=8J‹µ`´`ùŒúð¦»*ô®;BgûÍ1¾8„ØU ¿k¯ÇÜ°¬“DÔA“—79j{ nlå5ß;×dr¨YY‚6²:²r W‘FÎ '3 Y4”¬žMÛ¶rÔÆàÈÈ)jçÜØ¢N¹jP3C¬Û0ÀХߎ.AYH@£tÁåAÕðÃN‡Ø| QYMy-oñ¦($¨dÓ°ñDW%Q†£&囩½ Áó(ô{›Úˆð¶bØœá aB˜M³“cP1HcSN æ’twP€yí„péŸÜ$Ň³¿÷ ¡@y±Rdåâ„%ÆŠÄ;©£DR4ʽ^0ŽBëà•ïº[p~&•ÃÑ-2X_á«À4„…¾gz=E,oð À¨ ù×|yÄbÔ¢1JÊ÷{J²­÷‚õû8MM‰üÐ1U`¨zÐ*ò,Ôör-I²õq@l}»ÎLOü¾æ³w”Èà†kw@ìóªáh—§×šÔÐœ—¼2ƒWB’µŠZ¦ÐL£°9évoð{N[@¶“ùPcš„/¶32 ”hÞaéšµxIj ¤aªK¥Éë*i—Í«o›Ô<`µ}œÑ«ÿýº½~êw~êÃ/|ñÃ/þµŸáÿ¾ü?ÿ/ÿÛ_÷Á7ýä‡ï}áÃOþ3Ÿÿ#_øìgþƒ?øàƒ/~úÓŸýìÏ|éCüúðƒ/~é£÷?øè‹}ø•?ö'?úù/~éoüðþé/ý¹¿õïüÜüØßÍß÷Í?÷…OîsŸûð×|ã{?ðcö×ý†ßò#ßûÛ~õ×ü¶·„!”GÙ‹UõÞ)îÇØ­Àcr ˜e2XŠ°Ül²9Y%wȲ’H÷ªÓ憃§¦ó’1ÝËÊKúK”·ÙÌSË{uxÃFæ%ˆ5ÒØ÷76·Ý¦ÁÞ뱄 º€ÀœëB/‰¼…MF=xr-J’ä0µ]}a%<Å* —•D:67l½-*A¸¥ÙUû2S¦Y“ã¦YG}œ(ªÏ ª§qû6­ÝžÁÖ!ò 2gù‚C|ÎH’Õi·¨Œa!ørƒ2c4ž¦q¸ŽôpFãÍ¡[Ä!AäAPÄ!À9uCÈ#2LúSWÆÞ ˜äbuJ¸éG&»z¢Í!†â[\€-¸±#eüö1ðd°v‹6Œ‰Ñ†«¤ñH™«H÷=™‡EÆ FŇ}¼$!%ó´:%ðÿ¥f³¿ºJmÈ«t£ìW‘v–êƒàƒ„¢ <§FeÀZè8È1Ú€hÌþ7\Hâ»&#Ge´a®dõ©à.$Z½¢R`ñv :Dd¬ûŠ¬^N&VâV¯¤è±U\xòR *‚/؇oâà†¬['ŒlòF§RÐìŠÞ@Ü Ê<‘¸®g^¥ÂšSwôÞ÷†­µ—p©³_½©6ÏNº§šrÁZ`UýŽˆó—ÉK ,`M_lRèZÙ5¦}Jæåï0¾Î 5¼j0Ô³ÆÁ3)éA&¯¤„X!dP¦’2b‘ŽÕK†:̃C O 弊\tàÌäuJ¤š$¦ÅâZvÁPC‡9 „€ ‰¡†¼™ÅBnªh·WÖšëPqÈfòÊf5gö9 „Ô®h“¹ò2p Ìs¸ÃPVïX‘@—uÌ5Ë@ã%uD}< àÌfsJ:s鶹¹¢,õÔH0eîLÈuàüôè%•.ö n0y-ò‘i1 ª»óô‘`ò:5&ÇzZØð4“×.iImÕ( âA[Øg¶¥áôØa[80Ù™~ð™Ý…$Rš*ÖÉaMá(wÕ€ý¹éž–ivÖ€íØÈ’â©CÑËÄ$p´ž&(•wÙ`ÿ´è ¾Ä´¡ o^GÌUIaF× ‚¹h„äHZ’(‚eãÐi/nÇt¦Kò¿ç4Á­ÞSyì"7Ù»r¢VGÔÅpóï3C`¯ö1çtþ^)¦yF$„…Ðã¸i¡S $Y»r´ ‚Àlg fxLô‹ „€dÖ®Ì\*§FƒuW À·ÙqXí´va±I[™FÉZ£ËÚ…RÙBFlÁÞÚÛAî6vÛÌ€þZìí@ otÉñíÍôr¶õsí^@ñ_b{ü¹·d˜œ¦Kèx|úÀî³NÒ]¾²Þ(,Ì“õD?^FDsDÙLX¢p$ž+Ê“E×bè0wñ¹^²í)u:À¼Ôö›c|„áZ‡•- Sãa¹±ní!¦Gaâ:˜‚ÑCû%ïcZ¾0Õò)BS SJ—ELÉ`ÍøBbJÖ˜Â|YU½j7pLè†èFÕ`|á©1ƒpÅ£6Ão\Mløòâb£\!FðUV@Ü %d~ 4Œ-D3Ù Bì>\’ÁQÍȯIZQUƬ½í¥Ìº6¦¯ÑMíQ¶ %ÍŠoLËͬ‘톺\ dÞ_ß]¤dMZ %ÍZpÐÝ„q}»=¹‚>0®h®\‰¹ùªvdèYu6 ”d ÝvwsæJHµžï9Zé G‹ogN†ˆ[Y¹j3ç+„MÀ–ÔŠôí¤{À{ U™¦DRá{¢ì‚\ `†q+˜˜hQÉ63¹êìj~00;!ƒf¾ôäà zÄ:ši×÷ j­ Ì~OºKì*º2M¥oµ3^ïl)ÙMvã 6àqµfdL·K× 1@lýÖšt›P“ ïç{B{ÇG¶Êy×ð°¶.ó2“ŠiÁ,\umèÜ7‚U\p=•0ù¼šS×))çÕ……ªâ‘_Ù­«ý#EþÔ_þâþgþ×ÿäë~ô›ÿãÿóÛ¾íëþöö|þWã/þÈýæ_þôþíÿýÿÂúÒ¯ÿÌŸÿÙÿæÿ£þÑç¿úÙ¯¾ÿã?ý÷ü§á[ÿ½¿þü ßÿSÿô¯ú©_õæ¤ßõ×þþ_ýå¿ÿWü¯ß¿õüëÍ÷ÿÔwãoü]¿é¿ý;¿÷ý/¿ÿÑŸúè ÿàßüw?ûÑg?zÿóïåý¯|æŸúš_+[ \ͳ¦w³oîU¿"h†)/¨b`„S0}s–×L÷,ìiØßóîUL¸iA~ïÁe[¹‚Ȇg“„úBSÄè–¼=scÖq&„i°¥¸­åCÖúTÝж/kÞ:ßó&"Ç(½’²Ùob«òù)ÃòDËOg•t%öO w´uË_Ÿå¦¶šBÄX®Ò1±Ód!r eÆÁMK¤çƒ9›­%K£-JÌ6Dú°ûl®KaxšrœèW-:1$•#"J[sC(6K†Ù¤”O*f¥#£M²s–˜ý{ä†*{Õ´iEó¿[’Ûð-r4m®àV°Ò΀ººYª/²ó-½„yûBåT[Ó;¿]3­í¡F¬öE¬ÚÍ[³÷ÊžB›* r6\ýöRT"Ÿ,i³w²»,!iõttÀ¶u›šaQ—M™YHÀY4‘å–y ªiú{ì{‘×öm©¥¶eù¡•xÎm€Uí1ÆÞ|5|f6é> 7=ÇÞ|@^2”pìW„÷û ÛmdF47Î(²è­)ÈQ3v9k` JRiäîs"¯‘’'CS‚ýh9ô4øÎË8–4…m@aZ¦¥Ô#‡6:.‡q˜“(Ú‹Ì·Ž¢òàLÁÄF:Ïû)a‹yN§×=€O3·aiy%É7’µºVsª¤û3k³‰žì€ê«™$òȾâI¶ÔŒàL3iY_£9ƒƒÉ3ÙWqjYOh¿N;QVÛ«¯Å¢Ê=žˆX¹‡1GÛkϼb³¾öÜc;~®:­ºß®·S§Kï«Žòj<&®1×ì-û¼Js¹ãs7n¼ðSJy…ÃSÇñ¼ÛÙk±ûÚëµÇ³×ty¯ûž×¦=w¿3©Áž(NFL¯ë×æ>cxÍq=mŠwçÝÎ^‹Ý×^¯=ž½¦GnøºïyÚؚλôóQ£JÈZ3,#`GRÆßÁ %‰†e¢…î£\‚1–¦8銺`–Â-Ç †N"«åÃo¦½ˆaîI­À\T­êþôÀfG½J¦"(p‘€" ù‚2³¼ö¥6«Ÿ™¿ %cxŸš½³¨ÒØWŠìc ÍWë@G³pDf%Ì×>"Ô3ŒڼиJŠ:á° ‚êÍ7£h¨ä©F‰ýïðÔ{bäI‡#øP×°RAGcGpŸ7\`ß{ûæ*IÏöV—±“³­˜#>HQk ÏQb¤G"–é-¹à¢E©¶:ƒí¥vPË‹æËxÔ‚÷4˜ m%4œèÞÈŽÒ"¬ÔÆæ%ôÚ‹ÌSA¸ ÿ§ ³i[I¯1²†éšÍÁpð©9Oቜ"^§tÀ+šJ–Þ$8ÄŸŠø9[ƒ I ¶UŠwXMºÅ§èd#ÿÁ7lüÚaŠöh1®žœÀÙ…*Ä hæÿyJp?Ï™TÍ,‹'õVúÏI 1ŠÆÌç7VµìÃèŠØë>âºñ-­F31Ù«i¯ÁÌÔ«qèÞdQÚ ½‹ÃßT1”ìte¸×ð;Yìz<¨š%K¡Šª'ƒù$#y,|§Œ<`Û.òòE›•$^\óÄ:2‘x».G6 Ó€…¼yI‹£¸´êpVÅ¢$ïQ+ß»,CNâÛê„sB”eyŶq@AØÚ±yXÀw@ò)ú€ ãæÜoÊM¸¿`&hûæ*©¢¸¢Tˆl#Ì\Hk¯rÛ±ƒnv,×ýjû``VÄ‚7Ç"}S8<¾Æ_ó¸ Š7#õæqµ^Žª-¥Í½"Ü:ÛFè”mg× Ë7§½¬Ià 4î†SoÑZ%~hd³g*Sôóxæ;ÇæË/[ËxëS´ WMª:Áà㶭ËEË°%;\;ý(QËd¢‡mr£Kj¾ÝÓ•<˜í¥‹oGqB!Ÿt™Éø˜äPœo¹É¿™þºÉ?ì^#G Ä p_åE< {++ÙÛp°æÑŸ¿ˆ²Î¾ŒH6|FO§)–oþÛsŸ9˜…‚õݘ’¿ ´ävºàtœÒAZOŠ=¦«1â››ôWI!½M #ć£­Ѷ)ŽíóKoe¸w7íØœ®Åú‹iZæpëaCO\Œ©Õµ™6³ôÄ]»æm÷ÓžÌâ ¶cLn©‹ú­€xýÖž—Š±[NêOHðVqíufå–ÎAhø®¶5䨕G::.5¨´ÚñYÑKVOþ§žD™q¡©›\Í͵ҧ˜múù >&0·3v6&-æª?ÅÄ\ÅiÇÌfNÞÉÕÚ47ijÓ?‡Jà0ˆh¸ˆT­‚+˜…çYh©ãѤ&»±6û©sÌäx`XÇ…ªð3‚xC4­¿‘ø¶ýž~H3°Êõ_iMI\ä […eˆd«š•åL(¦3ÊûG,PaŒ¿6™@HÐ5—Z%c°´æÄ*И¥'iI•‡Ô4_$<6ÖjGgj$cENCt!jÓKö· =‰’€@9YV'bz~’DÂM£{÷KÕ%£Ð,¼>ÓT˜°}ý®A“^ò˜ƒ]PÚ°énPÏ›³Dö- ­œ;ùW‘3Pûj/{dzøUZ–³ß3/:õ•Ã¾ªŽ ÖtG-8¶U]òî:3+@ö´3£99ù€íáà>‡Q¶{È­êå„3­^“•øÔ›eßvô\uFµ›áÝNŸæ.¸ûêÃ\Ûl8‰‡¨{Ä©gkØgµVm<Î<ñzæÆNjůf ƒWÃòÕŽ­ÄéËWëŒg¯èò^õ=­M{êþD•£$ß Ëú7Ç&"¹ùåPœˆ²|ø ˜ Ë{;™'ëyÝsYˆºQ,V⯈ÒsíLûjN'¯3º—x;šU¼úêæh¸‡IN¿Ø=ä:›SžM«M'"ŸzµD¬Žž»Ž;;y; ·†mï+âDŒˆ†-š8õi û¬R÷ü‹>óÔýþÚ±“ ÓåƒWÃòiÇWâôå«uÆã+z†ì«~¦u(#" ŸÑ'DôED¯©çúê” § ñG¢Y_Í),Û¼®¾äººÆlþò1u{o::Í™ôÒœ.-–<õí¦¹1æŽZsê•”SgXÍÝÌðW«½'=´µøh ½h‹ò·ì‹î³‚:.âñ™oRÙØ¡…îÞä½™rñMU]:õáäèþ½6b>Éد9ñÁ°xO›‘ÆGVëc³£ùkï:†âÓŽ/ÃéÊ—êŒÆ—ó¶ägV‡,¶zó.é¼C^ÛÇ7¦x¨ ‡äcƒè ”HHD ¯`Ò”uoÈRÂwƒ™º¾X}zV_ Ñ—W?‰U\„Ç©6”…Þš¤hƒÉîNºñŒKBnq€™/‘ðâ ú™é×Y2†õ¨aå &üðUÆ= ç9–‘¥q¶öRIr%>0è)ìW‰úа„¶?)ó¢ÜkmׇA…wAVÆ£#ª{$rÁ;c*¹ûÊU‚ó}€´´z~d…|Asš.e\Ø<å__ndO–½¢E™z—yÅm/o„a+ø‘͘…Ó–7 >6Ò†:IJæq xTóÛÊQà0ÒÉv}À×'`AŸî&5pÁ…ŒmSv`Þ‰ÚKxœ€6Í(]¦‘Ç5!BÔ˜Ìjs8e2ËòÈŠ°#ÿPÜé®Á¡˜„í·]Í‹©ÐŽu,ÚB2QÂ¥ÑZ1#×áÉý;_àcÔt«™vÐ4y€zá“BÍ WÒ"ÀA³ìlôªqIô“Ý*ðãʨFýV¦6¼Ö0ÅÿäƒÊW)øŽ82a 5&qÌà;‹­ UXGP\^[Sf²¢øˆ9+Œ¿‘å‰ÕÀüœDn³ „ùâ½q}B|°ÉÖÒÄv*ŒjbLˆ&A†;ÓðR4¬É Øܸh‚oÒëŸê {’`—èŽ4«Bþ›ÕùÏ ?“™€£h±0¢(š.ðV|ÀÓñçTÁq†ñè·¯!¹õ¡{F[bW]óÎæd@sR! å6pÙÂ_!f¿uÍ–‘ ²ýÃ` eÜi,"Æ¢ YÒÄpO†]ÒõÌDLzñîXŒÔ•- 0cŒ7lf°«$(N6ÒPœDO̶ƒ«Ý íEÇfÀëÁI;UÂ÷^H“EÍCFFc}¦Ð8`§³’ÃøõdöEÎ@¥ ˆ2æ ]^\p7GS"ÏÅ6V)$x}4=KeÄ;îÕ¤C¤–ó'sNp¡£û¹¡ò‹j)*.FA†ÜÃÉŒ…º+è’Çèp3ú)‘÷£jË–0LpÆ%ƒbÐ#®§FÖ­´DíóšQ·mugv½#ŸÍ‘§‘4T˜{nÓ4Ï0À¨{£Â<Ñ+8•Â4Ã3!¯DñbÚë£ h0ŸÒ}“1æšhQð[Ñø+M*N½`¾Eöäoeˆ¡ñgïÞWªi-KqêOS3”çLÈÊwÿ‚Y´Ð²9Òàš^%F-% ïýÌÿ©sy”[ãÅåQöÍÃå³.í5—{‰qùÌ\nvÿÍåÞ\¾KŒË•Ìêp¹²ªo.g²‚q19È`­Ää &¿¸<Ýy‹É7$¦æExy4Ÿõ‘Çg~äñ oÚ%ÆãäáñÙ_ñ¸tšÃã;Û%Êáñ(×ÑÍã1´úòâq<ËyW¨åÇ7¼y|—ˆÇ#Ÿ§<Œô_<õÚñ©¡ë”ÍãÑ®Éo§±ðÇ£Ý8G»ÌtüÈãŒå»x<òr}óx´tô‡Ç£90Ç£œý7 #¡Ü#ƒÆ]!>ðø†7Ÿ&¨K<Žöy<ÊÙy<*©ó8|Wy<ÆñÀãð_¸yüN7[Zë™7ª§m­Ù=NaGâàä#ã0µ< ^c0CpWàyŒïp;ÍÑß@&½Âg:ÌQk‹¸þå˜sôYÎnB¦èR.â—ÎZ»2Ÿ›HŠºw¾DÒ.‘HÂ]x¹À®mx²ó®«¨Úðv>ðÌ.ÁšYÄn‹@x÷mh³BcúØ} ]6?¹—~ò“¯q:y TÞ6Œ;]|îo˜×Ì[ŒaÄM>‰)؆£Ã¸nÊË›Q!% ÝF««(sä8à¡&ÉüŒ‹0éùŽ 5¢œ ×P/Øß®ùiÛ€OC  QdËÃX˜“å‘–MZÆ;ÑèQq36.ÂÄ›(Û)7YF¼]£™1©I pÒM×Ù•Î"Ú“ éåœ$"ªw£ÝêA 0*’ÞtQ¶`c`J=™¼(Ÿ6Õ˜=óØbáïéÌv«ÊyÚRõä# qñ+Î)•J“+OD¶B6P³wQtË^ÿì:Cñ#)Å­°hz×ÏêÓ ¸o¿è™f1$ó!³m7r÷>°ë§„L˜ì¹ z;FkÅ=¢“²p:Fd^0ä€C}v«ÛÃ*Nˆi“¶~›}=Am1™¹·Êdú³y+#›a7ì+­³o„¶`Ø°dùî´—5I1œ@ÛýpZ‹Ö*ñCÓ w°ü81]ú¾ht²­P{ˆL“ÚFì‡÷sÐÇm[—‰Üå–sl~”°XÌ'¾#\d†ÙâŽ#ÍRÌÖ2ó˜T'-Æ›!Á:wÿµ `.Ng"îœMÝ䟣 v¯Á×?¸¯¢*!é1©åhQÕs(L»R´äÉ*k$Y)Em,T-üwr”O³›ÌßgfZ¦A›Ññ~¹hñÑòÇóËÞpìçÜJ’Ç¿[ª+FôÙu¬e=?ub´’ÝNÐÅìékr`ñßß1ójE0Û¼fÖc½gî#({Tó[ÝS%úí§7Sëx¼!]%î7ãÃ);9¹L¿ôiánùqêÅ3%mô”0_¡ðÔq4Ÿv|)N_¾\g<¾¤{Ì{Ù÷¼iIJOOøÿ¡¹6éò<ö—¾’¢§¢ªãØY š¯þØnͨh;h!OdenûMEÖ×}_l«æ,Æn4³ë0»âC;!mï«éTäã™Ù–v¹[þ=¯Ñ»Ó•ÍÝ.Æ=W•Ö “»™Š¼«æi9öpêöˆò!×ê+ëÓ‚¯ÔãÔkίÐSö³«ŽÂSÇÑ|Úñ¥8}ùrñø’î1ïeßóÚ¤±çî®4ŸPÑ'TôNE¯Éçúê”4¡7¶í²Ñì•–v!›×éËw­¿¸ßU‘;Gj%ö CÝ„™•z-Ö.hcl»lD¹™\uB3©»Û –zn÷}Çö÷É©¶Mùq7®e÷iMyAž™oZÙØ¡ŽÊØân¦{Š!ïiÓéÌhãÕ€ÇÞJ|Rs£Ô'><3æᶼ½` §Ž#ù´ã qúòÅ:ãñ=2Ã}OkÆÑqÞ%žwìd¬ÁÝt.‹òåÅ”JÚ0oùÅ’[í­H n]‡pa¬{õÊ;r«<þj»ŽŒMöH¦1W«Í^ü0xxþ)Éê·Ód ÇÞÉÀwxÈ.꺌@m˜O ûäЦ3q=¯,"öEo&5øî‡NrÝì0ýcÜæ23â.±N8,‡ˆ¨7—¥Vnþw˜¡`"|,¦Á¥†ãbI#ÿL—š·áWÆ»9€–'‰+}ø!A1â"¢|dDjÓ\jpª€K ŽÎS‹‚ûûE%¸Ï·¥¾@úKÍl+ø‘Û֚ኞ-%øÈ”ÕxC¿¡a.5§€KNË8×- Ìš¤ Óžô‚‰ˆî3ªÅUĪÒ̆yù¹øíö¨áþSÚV®$2ì\tÛ°™Lø•‘Åa³‘ƒ"O ƒ>5¸aÁÀfMWë܈«ÑBpAu 1sª¡õ§*ð»rÕð™TT–WM„Ëé±D™Ññöcö¡—¬~«›+¦žò°71‘P7,”춮Jl^ÀðÍÜe¿pØ®ê¸^#Ó`ÄݯÙ`0xp¤qS‘í\Nziœ nÎ52&%ÿ7»†©²Pl«ï=š\ÃÕ—“‚çªA‹äÔ,÷^#RXî‹Æfê ˜{Í)IʸèÉÄÅ•½§NÎ=ùm[ ó°Û›Lsg,ìùˆ=û.*s»j8ê8'{-NåøG`pD¿›l¢¢ð+ÊAº2ÜkøÙRz@ϾÍ”kIVR,†*ùVt×e9WÖcw]^â·xB5²RAÅ{K×ïvãÂ)Ñõ{Ô«åÑâÜÌ«IÄ[JIÓª_¿GÛZÑÍmPMÇk,‚YD%(ë& È"û,Y“™òú=ÚZ0Ça»á}½»KdÃd¸ÜµØMÑØš_¿§`{µ]¨nX6xƯº_¿§`û¦›å-‹”sl’óèÅÓˆÛ¼+T“-•Ã–nv|+É´÷ \ð7ÈtM¶Ú‰—íª!#,S¸iLuç0óë÷$ prá™UÕÓ3%»± G¨_¿ÃnÑ)8^ÉÅf$”ˆÊ]ÉnfìÚ‰JÖ¨Œnz¶QrGqø­èa\‚íH]×ï~ý~Jp™¼{_)ÓT¶u4í,s\! ˆ(‰S ×2ÀqøÉJŒZäö-%Ékœî{ðGOýðxê¯y|—ˆßRäñÔyüÀûÚ¡?ò8CoOý§úŠÇáÞ~ñ8®¹nǵØáq‡Œ©Ç#g„îÅã|#éâñoê<žú+¯y|¼âññŠÇÇ;<>^ñø|Åãó5çøÀã9?òxίy|—d³é>òxN¯y¯AÝ<žÃ+ŸïòxŽ¯y<ÇGÏñ‘Ç?ò8¯.G›çðšÇs¸y|¾âñùG¯x|¼ÃããæññŠÇç;<>y|>òø|Íã9<ò8ž´ºyüN7Úþ©™ªGÐTwR7f oRWx— ÛÎÈïaÏÕ¨¤ç»B³\l p?…ìÕãý3:Î÷åqÇݯÁe2ûº®ëõÍŽ÷lrÓÓ3&’rM¦D»HÚ%6³š¥‡;8Lõiºâ"af)iÞƒÙ%ºíÁÙg®DÊÈJ(viZ¹Ò=äœJs±ù »B¡EdØ•î.6Úu##ï7Ÿ£«|øÞ`^’ ë5hê㜜òÆùiH\ׇäó0ä]&vX€ÕÀ‰T.6¸6/.ŠüŒ‹PéB“»Ž¹†U”hÇ#Sü´m`Oƒ )fÏúXÆêÄ Û]6M›´\”€Ç2¬^ëaâ'Q¶Sn1¼S#kIàæ`€“®Ú‹øX¹éá˜^çiº‹MQ枸tvÅÛ^¤7å*Zpcidw±XtøASýˆÙ=#v‹å¦Ü5Š¥ƒ-r±ÁÓéÑ´z¹Ø­Ýžb-¢ê.×ýX,§¨å/Å&iÀ‹r±ÙuŠdQ‘‹'‡ÍíešL.æb³ ²¹ØeæŽPÕ‚¶ívá”p¸E”‡1ŠAžB‚»Ød9í:F<†žÎ9=ëxJÓÛ&…šU«D_Qí=%ùzrg)R"ÏVY¤?w…zñ-šnÙW„[gÞ-Õ°á5LÜö\ÒˆáÚî‡gåkÑZ%~¨ÝÅ2òp,¦9w±)ÙT!åX°(sr »‹6*œŠË-x¡¢”[ø”êj†Õh2Ñt3Æ“¿æƒ‹M­–¸Ðņ‘‚"HsÑî_äbƒ+ÊEþH9L°N—›ü‡M¨Ds±d'¸‚M&T á"7@eÒPeŽÃÊ0–oû·»Ø´<ÂøNFQ¹Ø”©'ZÛ¾,Ç3MŽ4L½Ø»ÀM&¿X°wB9ÔòwGºtÀ‚×ÊðWO€»Ø܈(Úïó” ¿¤%cþ ê"<#À³ ØåbSõ&¬Ï´Æn"u×c[ý´gW³µ‚íÀ»5„Eýf–ÿ­Ê,›™Z‚J Õt›¤Éî¿:³ÊšAmT¶5ÈW~[V›ÆKæhªµœLðJaò?1¥¤ÄúÔUI1¸‹MUšC³í-ÐD>'*®u›êŠ/Pô¬1˜8óÃfòB¸pÉæbã¤ÙÝŦÓQÅ0 r¸e(­‘ä &ÞnÒŸEꕳ—½Ø›½c&—·éÄDœjVMºÕ¦i’+^÷ÄQ'úïa Xo4]lðpc²SPÚ­ª‚\lÊÔþÚäRùˆê1•L=û{¢kA‚‰‹I.6¸‹ÀärEöOq"E[Mt °Â€n:»P#+r¢ Q›¸C£Ý5ÈÅÆw±ˆû3OØæ‚í4zv?<ë£s‘F»Ç|¦7*>ÞÅf©Ôz^­y®åªv&ƒY?[fØýf07]ûòù‡¬Ý¡ž‹å\í:lxþ˜¥~g» ³›Á\¬¯áyhr–_Hœž«&ë3>Ôñ‡µN;ÑÞMÛ})hãaíøZœ¾|½Îx|M÷˜÷ºŸy9m´WÙj˜ w–žh$Ã6"¢Ùd侞7`¸ªÝÅn2òå÷ÌÙÞ9TRx•4##O’³õ5=‰HNÍÚñD#9N#š]Xñ¡ §O_ ¯Õ{äyå0:qŸ×H0f+‹žÆÆ@å±ýó IÓkŽÊƒë0›6ê×0‹›=?ÆÁÄvÙ 3mËÔL¬–(àTx.1ï Ï%Y3†­]øy2®R¼k˜-µ3õ˜!úd³a‹æ÷,°˜Ò®ûav¡ õÌÝæ”(›MFÔ´,ÝâÉh6ÿƘïL7»6FÈ0_ñø|ÅãÈ`ðÀãÈ+pñ8€nG(øáq‡ÄÔð_¸x|ƒÆãóÏW<>ßáñùŠÇç+Ÿ¯y|¾âñùŠÇçkGxèÍã9<òx¯y<çÏõ‘Ç7¼y|—ˆÇsyäq„P>ò8bnÏñ‘Çבá_ëôŠÇs~äñœyð##¸óæq´yñxN¯yÔ¾yNB7Ã;ç‘ÇAã®ðÈãÞ<~J2þüÈãhÿ‘DZVc@çøšÇs|äqDÃÞ<þ §›Ç§Ýäj»‘îžÑf•˜Î Œ69¹Uobfs$êž$g%:ò“.ÀûÌgÁA\Ùñ³fWü°Ý»‡ËŠ¹YùÕ]Æ 9ÝmS®ôôHÊ­›í"i—H$e»ËtÐò%uvÞí0¢›Í ÞƒÙ%P¼3ènCÏÜœÍÓühZ™—¥×Ù47÷ ЃUYJaÔ‚ùIÃÈS t4Œ;]|nN4Ý“J“ó––FËîýr æw2Ú,LÊÓdXF›ŒHY¾\ʬN¦t·qÀµyÌhÃÏ’Añ™ùøuËh³úšµþ^pÁ4”ÑÆŸ†@³\UùXÆêÄ\”цš6i¹(£ e±¥Ûd„Yº…0lÊ-m<Öhf¡hyNºå:ÍòÃi.`’¢Œ6¥Zþ¢Œ6îd·ÊÖyõС͵ÍÕ «Ñe¢Áù» 3àxðñ†²šËë’ýMÄã«ó*@Bªõc‰/v¶ïÕÿ õþª[äÜÏŒêÏöàÓù¦ïÜJ›sj0#÷Ç–èPt4àûˆÙ;%ç«wû~gx'b>É0°N0ÜHHéémò÷ÿ„]†ÏBá+à^pzèÕSâCËJÓp)L‰t€©>Áð7áQià 8:Þm˜hÁ³/ÈàdÐd¤ $ÝyBìÿÔCÜŒaŠ`Åyãäß‘ÒKFÄátÜù¬ÒR ^ûÉ-8)X53,¯ëitD N%c ÁŒ×σmѪ¥v0hXÞ62Fc¦w†¹€€àËŽ<€ú©¸>¾ÔÓ˜Á¯ ¾ö’¥ËÄQÈJþ„û3uJV‘Df“ÄAqM™#Ô)~¾UÞA<}É?àÕ¸ð+´†Eös‡Ñ[Ôà"\«Í$i0I"ß#·ð5™½4 ¿ç£xG`Ú `ÃdUæw£hy±y0ûŸ¹ˆ0>S¥Ð†lÉ#h€¨Õ3Ó`..›eºãïÈ2sÛ XBad\üS¤­óÅ~½µ”‚åü¹ϸküÚÞ¤Gº[°Å§’ËÖñNí|¯ÈŒ«}È¥´ÿ^e Rùð‚Áy•XZšÞ{Â-ªCŸ †àCÜ9<Üɬ†È½g°M¦¶«2—6Ë”!À÷ÀZZ¸ëÄ},¶rHƒÉq€u›ƒÞ0ïÀ"(ĤK~\%M"<‘NØ=(m›BˆzÙ0…ǵ»†ž)NÍR¼)Z,Ea.z’™™àR½>žå†ébiÆý”ó÷ÈvIN0.‰ŽBæc ¢ °eî"ŠHJ$ÇÙlÊ*jï•DˆÜj…¬SPÝ&yÍ´)E±É0 $‡¾‚$ þW{¡Jþ2Œ‡K™HSoõrUÝ/»¢GqN)=@Ø6HñðGÝ&jïbL vn<§ÆÏt`ˆ‘WC,d;DÉÊ Žƒ8.çi,ºxB+vx¦Øëþw¤cÆ5‡×ÅöÃI03*¿0«id„ƒ)Š;% ÃŽ–xæ “Ì NY qàMÓ;G.å°B¤Z—‚EFÿóâB(ë™$Ù¨Ûô±IG^Ý+ §Á¥"ýÂ$ïlvŒ´íÁõŠ1¸ Üâ ,ágGU@Ú¢:(W<†¦¦~þ3›6Glæ4žÓRá„„–ºåÌá äÕ¤ÂG»0Çè“EupHgxP#'3U¼?¾ªƒä#O¾I{W®ŠÁ×êˆïi;WV¿h¦À@ràœ^ç‚5iCo‰ñ·û|`ìóÁ†y"°T;¯ Ê::„&¶„Ð*FöpÓìöÛF€F+ßõ£&Ív²0%™®4ñ(Þ¸Ú¥o¶-"¦kî‚—]À4ØMüä*€Ñ<U“ Y¶0$ûíãCLDP뇨´U-Z”ÇkáOJ×ÆüÃ4«fç{l0ÑwPZùpŠk^°ŽDže!ìÎH\' ›V̤¸ÑÃ8ÇžzÛ†²m ¸•œô<ÂÕ³Td&Ò"³ó%@WH^ 4í‡VR¼‡Æ IéÉ;â“â\›]@&¾¦­‡‰bœ Ý¬Žrw`©¦—ÄŦvK€™áw¼H.¨ÍõȈoñþ÷8wè6FçNgÁˆ¤#ªêÒÜŠÙƆQ}=á5&=1y-O<«oo^âgÙ¯Ðì—=z‘¨¸*¨õü^Y¸±›Çª„ÄK<ˆ2ìMžsxcÖ͇ÃÛ`Ž*?¼òÃ^ý<‡7äôÃÛèíÞØámðá‡7B~xzðÎg0àtÏp`û>õáðæð9¼YÉ>záÂò>¼!’êñð†ôÎ÷á ~æ÷áÍàsxÛvxi<Þ”­‡ÃÛHõÞÐß}xÛð>¼y‰oèî:¼\o:ßõgÖíðFàÞŸ…݇7Îã:¼!ôuxƒ3ôÃá È÷ám„¼oú½oýð†'n¯ÃÛàÎtöí·£(Â1þ>¼!kåãám`s:‡7Ľ]‡·Ñêãámô|Þø‚¥ÞõÿõáXÒá ¸½o>™×ámäþêð†É܇·…ãsxà‡7B~xp®¼oÄ«Ã_tm.Б£–¼®µtÈú€ÛD=}šÅ„ó p:ÀK tŽvf=Ý::}P†Ã’:ß…\¤ó5)‘â—NW¦ó%@׎^4–Ã[$ô(Rdœf¼YI}Óµ¡#)yÍÔßÁ&xŽ®)Q¿0Îuÿ­ûag T£Nc|q0IRÏ¥jNN–j ŸÈ¨¦vpþ´1×~6¿ÙoLõGLõGLõS}é“™˜Â³¯é.s'¦ü뱎%ùÂÔè Å xÜÅSxbªzA !°5ˆPþÞÈ"xe ÷â?ÿxá FÙ›ªvà _‘û;Ð$¤œ÷ü¯Kš³5[Qit¦Ž,Дœ„œ{£Yc¥Ì:û£Á6"[/œ|î¦ðþN#ɘÔÁÓ3)r+†y/ÍëóJ[ÍÕ| ×ɉ¯ êcjïÎùÞ:åA h×y2áÍ´sžLx/ïœ'ÞҾϓ« Ÿ?ö~'X®ódBøÐužL¡sžLxä{Ÿ'Ãoü<™øPÜ>ObÌû<™ðß}žLH‘{'"™ÒY“Γ ¸Ûõw¤|ÙçIÏyÒ ì<ɯÏy2!,ì>O&óäÆ®'STœÃužLÁÇy’X¹Î“ wJû<¹'ãûø*¨×yrã>OçI–œódÂ[×y’ðÃyò”œó¤n™!—,Îа­â™è5?öûÞü~»JÌÓºf„Gb2çhYm2‡ålË|ã¸A‚d|p–ôÊÅ<\§F;lžf°À©k´ £~“Ñf×(Ó: Ï"R‘=fŽ/2ü{2ŸÀÆ ì,¿ƒŠ­f*AYWÒŒ¤¼à%Np²€uÊ!ÔÕÃyûσ¿ ZJ8Í­±¼1KǪ„ ö‚ÏulH8½-’[ñ1×0ÆIï|¥ÄYÉË.)x¬”GT~UÛCÉòHƒŒO8”[‡m`ã”$<+@Ú"Ì©Ôà’ø_0¾î:@îžF{7 Ds{eà˜l‹,(0íùlpχJl> ÀuLÑ|ød-=!2¾8P—pÀ&òxAã=Å,Õç”n C&†Wj£ Éùt*tuÁMA2 HÌÌ…– 6Š‘»ŽWx(ˆ|й'ìq7_Ãot\5FФùfo”˜Vn)Ôfªü 5¨ÙCiQüÏQÎ$.Œú“îm»†½Ã•í­¿ ¶¹S2k:Ø¿íÙˆÀ¦™¾½Â„KÉ®PÊŒ¯W¿8x9=àŸ¹ôHÙ!¾évÈdƒ›LøúüE&S¶·& l2¸ÉD ‘ ¹÷"“ÝÓ&“]"Â@‚üø´Éd*Íã&“uÜ9d"`“‰ÀM&L¦ô÷Mxùë‘LðïM&¸Xs2¡ü@&S&R'ü{‘ ÿ‘Lì¥ÚSC‘͇L6¼ÉÄKD&‡<'>kö@&œöE&x˜î&“Md’ƒÒNSŠ1aÞ†çLÍ =î[ܯ v#Î9ÇëÏ qæ×8´Q 3“2$ZºáԣΊwäŠǵ‰Ê §7’!¡ÿá™ ¼V÷hl ¦rü–Y§›¬àóÒ´Ù)ëå v%ôä`®ï9HÕ9ÄEžuXƒ/¨(V‘Ÿ§#ÍsÐ5å‘÷Z|¼k8¦íú&(Å%ÑeŠ9_È…ÓÕb .ÎÂÕÒ!¿¼“‘E!“Ã'•‰S#7 B. +ä (õú@.ô˜6—?O#›¨4ÙÔØ–¤_%ái°«Mød»úÞsèÂ'ã×%{ÐGß;®ývÉc KúÇFȲQn4»—<§„²†é´  ËžŒWÖ«L¼R)êmn@Wyoß($½lP‘‡1hGé"=¼N°šk-^ˆ Z˜2[‘†ñíX†­²ÿÙP¤Ðø)‰?÷(_ô R>nÉŠnè{{ðµK Ap†øðà«ú˜c ¶xø«Øª& ‹!P{ £À/ц1?ÉGt™BãpVé’t– '¾>.£ãVç&I¾?môˆßëä,U¼}¯hq0´ ž†a<ÖÒÌ?Çi÷K|0_ýNÔº7èÈMâZ©µ³=¥í0èã> ›Î&>èö’³íÕS”<’4yQv3Ù¬Pïbü1­Á¸‹z'šýÏ"ø¥£ç ¸'°@ÍÒñLÈ÷@ê<]Eâ^a~_.0) y-ídÇÈÛ µ@`‰&W`Ð)ø"q_{qЈ;Ù ç. ¬R'=Åwˆ9[ ÌkP¹O²r¤²µÆKã# ƹ‡ÁàÆ)ÚNŠùËrÇàÛñ0Óá•j ‘"»™Šg`Ôª¬#Vò²KJЫKÌécgì«$Kí|…Á­’ã…€F%ÀY°›p%ÅRÁp“à‰1·E¿ñU¡\±?Unp ˆŒ¤SÖŒ‚Kóh t¡)X¢‚ä‡ê ï2ßmÕ¶hÄ œrŠBRk³ÎdθÜIVM×bÜŽd°÷{/(-–€—{zÚ²q—ˆ`à&߶d„›Ó¥Å"ìɵX\‹5еX»E¥¥vk±ŠóºµØŒLÔ—»àúdZl†'Ôƒ›áZt´Ø ·²£Å2LìA‹e(Þ¥Å2 êÒb/سìj±î:’»<ŠzŽ¾ÞZlÆ3§—{èáQ‹…ËL4ã/†vEÅ'Ù¥VÉ6DÆKdÉÇhÁÙE‘˜Žk±&Ro‹Pn­žpÇëaeêÈÈ›¯] xçã\ݶöT-x À@¿áMÓÚ%ÊA¨šâËqn©  b)Áì¡k'ôÓ¬”Ö€ƒ=è‚ø*¡[_FFY1MQ\àZ†fGÁn“ZmÏ šÕ¶:p”¹ð*©Ð¬Ð_> kF~Úñté¯HŒW® •« %¿; ¡2ËA‘Í©`=ªüaÌGsF™^«°¹Î7ÑBåy lgd"¥üv¼d;Æ^FîâÊÅû2èu4ÄÇõcûÉÈý{™î'Ä…sÇVn¢º‚—Æur@´T{8[0@*]5LEr•aäLáöÖ"²¤*¼'$k?ש‚…]á÷U[HÍ'TO þ\”àÁÚ–¨@]˜m»V!_BxJ^F$wÛ"¿V3wX8žƒ[ä#ö ·z.òk3e’S!°E¾À-òšÈG;³‘¿{Ú"—HÈWÄï| ¸…~…7v~Úç‡:æÕÝ8š9Ú–eÔÏŠ +®¹ T‰8aÅ› +žÀºvÿ†bIG„†dýé:DàõU©¦VC¼4ü×>AÜ'‘á‚Ȧ8Ÿ¶ÂßUz#l—C Žý]p#¬áiƒ~vÉ–/„ ظf Öð‚IÂ0°"y|ÙÇpξª! HÄð…4üõªÁ…풯ʔ‰´q#ax¼p†øú"Û%†¤Ù5öW`Ì™q_Ÿ¯â&W³–-}ãkØF®#—@SŒøŠåÙ‰æœòloU^×w{kcGo?r­]cã&ŠFün²ó±oM]"Æio±ðxªëÊãtìWˆ‡¼íWx´õ¶_u…„_ö«^Úõg¾®±íWÈÞö+Æ÷^ö+æ¿ìWLþqìWp¹»ìWHpÙ¯:e‰ìWpí{´_!)Àm¿bR´ƒ„d>Ú¯¢Ý5B½ìWtûÕ.0û“¿\{ Ÿ!yØcYzÛ¯6¦Í~Õ•3âÁ~e¡ón¿~nû^&¹ìW{R{ÿïx‡ó²_!œõ¶_1ÃÃm¿BÁm¿bÊÀË~øÑ~uJ¶ý ·Ë ˆ¸ÉÑ•c•yq»¼„m×í2¢S“eZ]<ÂÛè÷d§Œ§äå”ð•åiM•ùNÉù*‡‡–a2P¨e†C[¼?ÿ“ÄëÞ™mSéþð2A|ø éã•Á,ù¡NRŠÚ)©q§¡×ƒäSr¾z§÷wG¸÷»ßü4¿¯Ûendstream endobj 6 0 obj 26045 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:01-07:00 2013-08-20T08:42:01-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000026349 00000 n 0000027919 00000 n 0000026290 00000 n 0000026151 00000 n 0000000015 00000 n 0000026130 00000 n 0000026413 00000 n 0000026454 00000 n 0000026483 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 28089 %%EOF ast-8.3.0/sun211_figures/fronta.pdf0000664000175000017500000005357213004147321014004 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P05°Ô3Q056TÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!ê1s endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 531 509.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 531 510 ] /Resources 7 0 R >> stream xœ+ä T(ä2P05bcC]SK=cK …¢T…p…<®B.¨‚$L@,=3…ä\.ýD…ôbý K—|®@ Q¿é endstream endobj 8 0 obj 72 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 590 /Height 566 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœí ˜Å™þÉ_…ᦑâøtD$1®ëÍ"*^/‰QcÖE£Á¸ 7Þ×DW!nÈê1jЬWtט\ F“uQ5*Ψ€¢8ÞõÿÎôÐSÓ·ÓçT_¾úêý=óÌsºO_ªê­ª÷«î:ÝJ;xì±Ç¦L™òþûï—P>Ÿ~úé7¿ùͻì„äÎo~óÊéºuëÊNàÂ_ÿúWªÿe§¢4-Z4qâÄÞ½{÷êÕ‹þå+_yöÙgËNT*Ff³Y³fm¹å–O<ñDÞ鱑”eÈL’ºbÅŠþýûOŸ>½È“†žÚo|ã”ÓW^y%ƒ;BVYŽ<ÎÓO?=jÔ¨Èí©¦~¸w'ÍÍÍ?øÁ6lØ o@Õøþáh÷>}úŒ;ö¤“Núøãýoi—^Ql±ÅÏ=÷\ä?ùä“ÆÆÆÀöcÆŒ1È4/–,Y2|øðûî»rJ‹T\7ÝtÓÈ‘#_{íµ²“VÒ"ÍfTIžþù¼c))ËY%•:ÿô‘­Eå£z¦–FsÚœ²­(2!«,‡ó»ßýnÇwŒ<>õ½ÔS?L½ñúõë—-[vØa‡~úéþï¾ûî¾ð…ù—!}i›^xï|prn¹å:NÜ·+W®ljjª%O–ñw÷w·Þzk`å%—\r '”’žšp°éeŽEeXJR-*•sjí*ŠLÈÉé–/_¾Ûn»ýæ7¿‰<þi§vÁèk^~ùe}THC¼ï}ï{úÌ''uãÆãÆK¸®õÒK/ÑØ09ö2oÞ¼‰'R!ÖôÑGwÜqGúãttt<üðÙ&-6½Ì±¨ ã’ºbÅŠ%K–|Ò:¨ÚLž~úiÃQ˜-N·iÓ¦|0ÜóäĪU«}ôÑ:vÌoL—°¾oß¾4ÂÒ׬^½º¡¡Á_Ù§OŸ¶¶¶ð¡*ÏwÞ¹Ç{$¤êÞž{î™°Õôïߟ¢‹ª›ýáØi§¶ÜrKïFÞ1Ç£ßæ¦oiØK‡ò¾>}ºw!Ôƒ*ó?ýÓ?‘4ÞUbtÿçþ§þí¹çž»ýöÛoÑÉ;ìpà 7øßRCùI“&ù÷iê«_‹Ö¯'Ó)Ž:ê(o½%')ðŽC‡Õ7 ŒP¨æz«­¶:è ƒÞ{ï==;^x¡žÙ9sæè»Sf÷Úk/?³t(ÚXß 2kÏ>û¬~Òƒ>XŸ{C'¥øP?éÂ… “ 0ÊŸÎâ§P¿,þ6þðÝ } Uª<^F¨²Q•>|¸ÿm\j© ‡ 2hÐ ÊŽJ8pü{ʾ¬ *T½) ´½ÿmú¾.|½!Tm&ßýîw?÷¹ÏÅÕI½òø!ë<âˆ#ô ¤VÏ)}þýﯧpæÌ™)Ë!®ðÃ5Ö¯ÔEPkL˜0Áo¿üå/i—+¯¼2MÁÎBŸ_ýuÿÛÏþózñå/™F@úîwß}÷¶ÛnKNAPã=ãŒ3t‡ ×:*ÿ[Z™\h)©Éé(‘z½DÒ–x‹T‹þú׿†õ³Ÿý,ò,”ß]vÙ…Ì.!…<òÈÖ[o=lØ0ª`~%¤¶“°‹E¤iÅK—.¥þœ yýúõªóFÞ‘G9kÖ,ý[ª Þ"}{ÒI'Qëów'#ûêW¿JM’>Ó/^L­ÕDÓ·ÔHµ¿uòÜsÏQ]Ò“GÍóÚk¯ýì³Ïh‘þ™~Z¸?Ø29I „w¤Ãú;R+¦ÅÛo¿Ý+(jé´ýW¾ò= ÔØ)îò3K¹ó/øá‡Ô‡üë¿þ«—Y:ŠvÑ£»pÖÞ|óM*ý¤§vš~IŸviiiñOú‹_üâðïZ†‘ÐÁ'NœH™òâ:#I3uêÔ¸o#Ó8¦¾†LÜÏíNU.¦†wÿÕ¯~EeèÅ·”;Ú˜Jøßþíßô]H\RÊ+ŸðqÂÕ›Ò o²|"C-Eÿ¶j3ñ¼Ï¯“=ö˜ž ¿òxk¨œ©ÏÿÞ÷¾—²Äè3ÙÍ<॒´ë®»¦/‡pQ„k¬^ÈË;ì0Lmè„>Ð/¹äïÛwÞyçä“Onoo¯Z°³Ðrüo}ë[zªôo)T¦ŒøG&Û¢’¤Üy‹Ôx©œu· ×:ÚÝ/ÃäBKOMN÷ÏÿüÏT7ô)(Ï<ó mé/~úÓŸî½÷Þz?°bÅ ÚàÝwß<Ëý÷ßOA£RHÞJç}ë­·¼óú•P÷}{IÓŠ¿ýío_~ùåú*Š:â¾¥žmäÈ‘þâøñãÿïÿþO߀ú%ª½qßÚf J©êtžâá™Õú–ÉIJ 2µþŽ8%÷äôùƒ>п¥¸Ý¿LÁÃñÇÞÝ?#³væ™gžwÞyúš·ß~ÛW‡j~ þSKïÛ·o\ “¹âŠ+ôÎYu^åöþ6þÈsék¨Ú.ÚзúÔ‘ðîTz±Ï“O>¹ï¾ûê»ÜtÓM ' WàÀ-”åyœ^x!î۪̈́œÂ7Jê£(ùË_ô â <®Ä¼á‰¿HŽéד¸ô'7·pÕëßÿüg’ÿéOò¿¥–òÆo¨ Ÿåý÷ß×ëpX þð‡Ô.¼ÏT†T’ú·TÎTÚþb¸Öé–’ -=59µq È‚©-Sü‘ÇIþ6¹™¬]»Ö߀ºâp2j-𪅟\áÅpã Ô½o¼qÇw¤^zÊ”)?þñW¯^­j§êYÂù"ƒð‹Ž>PIêßÜ*\ëtª6Ÿ”Äí·žF÷4Â"‰)©ä5÷ÜsžeÕiv4 8ôÐCiý´iÓhƒ¸CQ¿AãÐÀR¢WB«™3gÎy_Ø/·†††„*ù­^8ýúõK°•äoë륫®L>iá3t:*Éd§‹<íõÖ[o%¤9C§£¸(ܵ&[SùPñÖºû€ª:]8©úÊÈ \‡ÓeÞLL8µxráW-‡ðbd óúë¯ÓÐãôÓOÓßs)‘ú·)T†zÿF%L嘑¨u) …åÔ›C'¥cêuÒí¥—^>|8u^ÑQ“ÙsÏ=ÿã?þÃß`Íš5Ûm·Ý /¼@ßR@òöÛozè¡—]vYøP'N¼îºë"OM%CA²ˆRœóµ¯}ÎåéëWB3R<È÷©»ð¦Ñzól¿= L?>úè£Ó§¾ÕgæÓ6t¢»ï¾[ÿ–Ìn‡vØb‹-èÛÏþósçÎõ¿ÕØÈ5Ô öÞ{ï­¶ÚJŸùÞ+°29I „wÔÃrÕYoþõ_ÐÊ‹.º(.³ªs65õ]ú,}}º{\Ö¼Õ?é!‡¢Ÿ´jR ò’”æ‡td:¾žB}$þ6Ð;î8ý[ê ôÄPµ¡Ê£Ï÷¦"Òw§fØÒÒBèI¥2¤Íh{ï7TÂUK,°2\wÞyçä#D’_3‰KÕ ¹JLß«jMH.â'?ù Å*zU ×X¿>é32Äû•}  ÄÿÙ£÷+ƒþýû'èfô³Ðú¬_Ϥ•ú·Ô!~e ÷oTÂTÎ_jÞ·W-´8Èp½jéK`VõhÑ‘Ùy¿ ¢4âlpá…zZ]L™2En{—7.îÁ§d¾T\/¾ø¢·H›QóôNêWÂ{ï½7Mfk$Ç{éÁÁ,ƒ4lÚ´‰b’ä{d)A‹ƒ×Kâ:k×®]¼xq‘éb€Óp0Ë Ô755ù?…6u €‚Óp0Ë ­­­÷ß&‡B `’¯á§¿ã#³ u žôî­zõÂþð‡?ü1ý£^BÅù¹ ÍõŸó–jtig¿í65mZƧ†@n™Kv,)ör”šÓi©@y¨àu:]]Çç¼e‰›lŽÌ.ÛS§À EÊØÒRàtæèeØœZÜôµ:ý1ËÝ2}GšùÙ[ZTGGƧN*þ€52ÜÒRàtæÔY†òJ>‡&P&©Ck€@Ì&'àtæÀéd˜˜Ã)Ó™SgÊ‹ß8Uì '0Ðw1‡@ÍÍÝÓ/!(Ã.PÌA(”è¥ÍAvr`bÊ ôÒæø£ã1cjÙMXü¦x…p@Á 7Î 89˜‘"Ä„"Ìá$œÎÌH‘ šs s8 §3eا.„…"JíZv²E˜@J\ âÔ1¢—6eØÊ3·)•îÑ  4„µ N¡zisê,Cañ›âU±3@˜@Ó:Íp½qnÀéÌÁŒ™¨¥ó¦$„…" ±bŽÀéÌÓÉ11‡“@p:s0÷²§ø- sÐw1‡“@p:sP†PÌ‘'°P¤M©]ÊNC¶p½´9˜‘R‰9ˆ93:ÿ@>ÀéÌÁ}º œâ·lŠ@ æ´(Õ^vä§3N'ÄÄN¡ˆ§ÓßCxزþUÜC˜[[ÕÀ]ÛÐZL^¯ƒ)8Õêl&<¤ô]ba à÷ÓmÚ¤öß_Í›v½¹Ø¢E]Ÿé-F®ojRmmÁ}å•a= ˜ƒP„9(OäõÒs樨øZÊõrðëg̨ü%ïë((æ@ æ@ <‘×KSÉTccõõ4°õ/f¦tºövÕ§OðÈ•mš;+*ý¥E°ŽSü– ‰¸®˜òœÎ#._ƒ§º×çt)×Thîi|+¬ÃAÁmr@(ÂN¹æt‹©††êÛÇ9][[̘®šC‹pFVmr€@Ìá$kNG:§ctŸŽ›3rŠß²AXŒ ˜#O Næ"ÆéFkõD·³Ñ=ë>—RG¿ªéý² r}SSåV];Ê0og´¢\1Gž@œB;zé46vÿnbРn;Ó×'ÌHñ~Yàÿn.ð‹ƒðz™O«Õ9Õêl`.P­Hiéb@y"ÆéJÏH©Àíjª9ò†°På œÎ8]ÍD Œ²\È s8 §3O«küVŠ3B æ ïb'àtæ  +°*+ÆŒÃJ L@(ÂN¡—6G挔Z±º"¹àŒV ä(Oàtæà>]Nñ[6$„"6:£SÙˆ<8§3N'“ ²ÑùƒÄN¡œÎÌH©À©VgC‰ÁÓ€¾‹3­J ¬¾UÞ´´¨©SÕüùpº @V@!”ˆ›ÎˆX‘3•ŠzÎFÁtt¨ Ôôéè¥3eX…À] 7‘9hAy‚^ÚÿQccÒw Ââ7…›=&Á ]qžÀéÌ©§ QìÌ@&ÔêŒ-JMUj¾R©OP„9Ì‚Ó™SO «Õò@»(2¸JMWj×Íkª:c¯ ³§3eXYgŠ¼PD’@dp#ktÆZÇŒÅ#I §Ê° 9. 3Æ]\-×… Ä,VD/mN=e(,~Sì*¶)òBKOO­WS3™òNgf¤Dž@EŠ¤g„@y§3N'ÄaáEÆ9§3s/+0 áL@Ìq¼ãŠtFÜvŒNgÊ° 9ÂB(’ž:~ÄaîŒÌB/mf¤T@EbbJqƜәƒût˜…p¦È E s쨔©ª5§3N'ÄÄœšB‘üNgf¤TcËH踘“«@µ:ãD8]  + ˜ƒP„9(?¡—Δas s Pž —6‡ÊÐ{{Þ9" ]qžÀéÌ¡2ô^à¾ë®Õ7Þ¼OŽé˜ƒP„9Ì‚Ó™ƒ)A»`b3àtæ  +0 áL‘Š@ æˆY¯ˆ^Ú”as s„ Ä,A/mžVYÅ6Ež@héÌ@y§3ÏHˆ<Š0å œÎ8@ s s˜ §3s/¹Åo˜ƒŽ‹9Ì‚Ó™ƒ2äV«Ay E”¸h„™@è¥ÍÁŒ©0  QžÀéÌÁ}:nñ[ E äiÄ 89p:@ æ@ æ0 Eàtæ`F ·ZÂ’:.æ𨥥ëñûp:sP†Lj5ˆ¡s P>ttt=~½´9(C8w s PΠ—6ï§c¿e E‚~8gàtæàýt@ÌA(ÂfÁéÌÁŒ ]01‡™@p:sP†Üâ· Š@ æȈY¯ˆ^Ú”!·Z ‚@ æȈY(‚^Ú< Œ[­Îa¡™3å œÎ<#E ÂB(”3p:sàt@Ì@Ìa&œÎ̽ä¿eb:.æ0NgÊ[­Aä „P„9ÌB/mNÍeØ¡Túߘ[js s PÎÀéÌ©¹ oSjZ.)) fñ[‹±!sä Ä 895—á´N³œA»`b³PDŒÓ57WòâÿÓýUcc÷zúI[›4¨{ZL^¯Ss¶t^À”³Zˆ±™#¥ã 3Ä8ϦMjÿýÕܹ]‹­­jàÀîoãò;cFå/ýgyeX3(æ aÊ}$Œ9sÔTüÎcâDµhQ÷·qùíÓGµ·w}¦´¹žL3<¬“W†5ƒ`bÊy½ô˜1•ë4” CVÕ·o÷bc£5ªës üÅÀúÈa]e›¨ÓÅ‚ø9Œ¸~˜òœŽ A\CCÄú³ÎRgœÑ½8n\÷p/¥ÓéýïÞù©¹³ÆÒŸ—°¹çb‹RS;×»O' ‰BE˜ÃO ‘N§¢òõë_«Ï^½ùfªí㜮­-ÆéRB·@©›O—ÒçËEh£b?qº… ÕСjùò´Û×|õ2'5—¡½ež•32‡O(’ÂBÄ~‰qºqÈéjÅRgtG K@Ìá'œÎœšËPXü¦² á˜8#bz-æðNgÊ°´ŠÍÄù#¬Š"a?ÐK›cñŒ”¬°¥9댶ä,(gàtæà>ÃÎ?ãŒRƒ¼>p:sàtÒ¨[ 1ÎÈy-¡HÎÀéÌÁŒ†ÛˆÂœ±>Ðk1‡Ÿ@p:sP† +¶lC‘ºQX(ÂV º@ù øýtŃ2”ætbðѨª3 -(gÐK›ƒ¹—|B¸l€@þ^pÆb@?œ3p:sÂÏ«¶C¾é¦@ ú(ÌŠ0‡Ÿ@p:s0#EhÅÐåƒ Fé˜ÃO 89(C†!œòBùÎج-¦qFP0üºDôÒæ  VlÐ7ªuÌXÖ‹Œ•”Pć_¬ˆ^ÚÌHaX±AÐÌÓPë‹Œ3tF”3p:sðŒi a’±¦þC œÓ™§“bŽ¥¹óH~ÁéÌq}î%¿øÍÄGz­Z‘ÏÏù §3Çõ2t<ûü‘'°PDå”èŒür½—Î×g¤  1ñ‡ƒFµ:c‰SUkNgŽë÷éøÅo¦ E lìJœªZ;p:s\w:y@ æÈHX4Š”êŒp:s0#EhÌ@ÌÉD Z1ñ!9p:s\/CyÙG(ÂaulîÌÅÀA žÆçz/®—¡ãÙçbÎmJM+; Òq½—Î×ç^rˆß²"™Öiv OàtæàýtÒ€@ÌŠ´Ø1Q¿ø §3Çõ)ò@£`b?àtæ¸^†üâ7S„…" ¿.Ñõ^: \/CdzÏÄ„"ùãz/˜‘Xƒ6Δ?p:sðŒi ab?àtæÀ餘˜ÃO 89®Ï½ä¿™˜ƒ^‹9ü‚Ó™ãz:ž}þÈ¡sø äz/®ÏHAbbÊ89µ•a›R}òJI9ð‹ßLŠ@ æ Î89µ•áŒÎ?À4 æ¡HþÀéÌ©­ [”jÏ+%åÀ¯V›‚FÁÄ~ÁéÌq½ åe_XŒ-/@Ìa#Pss÷ø!®—¡ãÙçbÊ×{é,¨­ ¿1‚A'œ?p:sj{? œ9ˆ9mJíRv²E^(Â/\„Ó™S[Ê«ÕÂ@‹`f/ó‡_#‚Ó™ãzò‹ßŒŠHÞìeyðë]拾Àõ2t<ûü@ÌŠ(Žá¢ë½t`F ` Ú8s PþÀéÌ©­ QàÌA(ÂÄ–ÁéÌÓ‰11‡¥@p:s\Ÿ{É2„«ÄtYÌa)œÎ×ËÐñìóG˜@E˜ÃR ×{é,p}F ªs s PþÀéÌqý>Ë®~ä…"ˆ9òú~ÀéÌqÝ鄘#O „"ù#Æéô·3Ðßðá=¾mkS£FU9Bk«8°òGÒ¬÷ÁŒQHib@Ìa)§Ó™1£òX“œSr12ÇE‹*ôÁ7µ¸õ:"Ë°„e¡s s8 $øýt4|£ñW»öd<Êlcc•œÒ.äeô#×75UŽ@^Ö†ãÙçbÊy½tx@çÎé¨QÝc´À·þb`}äÁ]Ÿ{É)„Ë F\'ÌyN·ãŽ•LÑ .@8§C‡vß¼Két4TìÓ'êÈÞŸ÷~ºæž‹Ä¥ÎVj¥·u-™Å˜ƒP„9,’çtá|%ç4¥ÓµµÅ8]2«”š­ÔøÎÏÍ!+ ;#(¡-Bˆ9,‚ÓE~›ãÕË44÷4¾ÈE>ÎÈ2„«a¶‚@ XXzŠ§ݳ9×êt ÝSMô[`}`®Kš#çNØø vF)UH,ˆ9EòGŒÓéim­8TÂúŒ}°–æsò‘“(½VgîŒ,+6èFJ Ê1NçýŽÀû4¨û§>Í¡YŸ‘B#5ÚËÛåÜâÖëFJécÆ‚)=Éa¡bKÄ8]‰wºZ±ÝÅ d;ˆ9,‚Ó™ãôÓÀÌã7nÎ(L ¥v-; Ù‚.‹9,‚Ó™ãtŸwnÎȜ۔šVv²EX(¢˜^î«–9ÝKg„e3R²…ýqܧušà ÿFd?p:sœ¾OÇ2~3¢·,glé¼€) a±¢×'°NgŽÓN'Zr|ÌX<òZ°p‘e(§33RD‘w‹¨ÕiP6U©ùâ†fuƒ.‹9,‚Ó™ãtÊË;·P„ nRÓµ)”59£¼P„›@æÓˆ“@‚ßOWùä“Ï?ÿüìËÌH|Ó1BN×ÖÖ¶ÓN;Í;7ûC³¤†2D­fBæ@ æp}´oNWÞÈìÆ7oÞ¼\ŽÎ 8 s s¸>Ú7§knnÿŒ¿§« ,~SâblÄ8s¸>Ú×éÙátºœw+&Bæp}´¯Ó½tF8=#õ‡9ˆ9¨àtæ8}ŸNXŒ-/@Ì‘×'°$?§{çwÎ?ÿüþýûo½õÖÇwÜ¢E‹ò:SÙ8ít€@Ì‘'B‘BÈÉé–,Y2dÈÓO?ýí·ß~÷Ýw¯½öÚqãÆvØaëÖ­Ëå|¥‚)rב 1‡«@y8Ýòåˇ ¶páB}å† Ž9æ˜c=6ûó•ÓW€…å¡s s˜ ÔÜÜýþÌ9þø㯸âŠðúÏ>ûlâĉò~d§|@Ì@…Pð» h¸×ÐÐý)KÅé¹—ÌB8S (8]!ÿ.yo:Àûé䘃P„9\ÊÃvz÷î÷.ƒ?ýéO Èþ”¥âôŒaÀ阘ÃU <œî;ßùÎi§^ÿöÛoo¿ýöwÞygö§,qƒÔZàÂÕ‰¼P"áÚæÑK¯]»v÷Ýw¿à‚ ^zé¥õë×ÿíokooòÉ'wÛm·Ë.»,ûó•ÓNçrÞ­1¡H!äÔKÓðmÊ”)cÆŒÙrË-·Øb‹#FLš4éÒK/Íådeƒ)€/p:æ@ Bpz<’xFŠŠ01‡«@p:sàtr€@Ì@Ìá*œÎwç^rßêG˜@\_]?诘ÃU LœîÁÜ°aC²w£g3n \_]?ÂB%.\ä*y/}ã7öêÕkæÌ™þ¼s<aµNÇ®/€Ý ‚¹Ó-]º”¬­µµ5‹äX‰»÷é¸Æoõ#,áúèú&×'pÅÝ+oÙá®ÓÉ1Gž@ÂÂE®¡C§Û°AÍŸ_v"j3RäÀ¯9€@ æpˆ¡Ó]y¥ê×/¸²µU}á I{éï!Ò¶L;ؽ¾±1zw}3úà_‹[¯Ã° B^ÆŠ0G˜@JœFÌÊõýt£G'‰—üíÿ¨FŒ¦ŠRëÙM6mRûï¯æÎíZ¤-êþ¶OÕÖ±—¾} ÅÈõMM»ÃéS  Q!üÖžäw¼û®;VÝtªR&uÎuÀ¿‹ÜkÆŒÊ_Õƒû‹ivwwî%³ø- (8]!ætkÖ¬ùÅ/~1räÈ„wy¤úîwcS^Ic½ðOh~•2°W{{eXÞ=¥Óé»7nÉ?¡@­fbŽ°PD‰‹F¸ ”‰Ó%ÿ€Îcë­·>òÈ#y䑸ƒÌ›§öÜS}üqlªjJjœU¥ßû‹*3‚‚Ó11‡«@Å¿s<ŽÑ£{L) ¿Â;§kk‹”…7«i÷lÊÐFgä¿ÕlæH.9 ñ ߘ®äûtÂÁ¹ÖjÐbN›R»”†láŠðœ7X‡Óé3:[[UCC×çÁƒ{ü4€Fdíí»ë›y¿,ˆ\ßÔ±»3RòpF®µtÁ²uƒnftþüáét‘ƒÂðJ}JIcc÷eÏAƒ‚?ˆü=¾»¾Yøáõ:2Ÿ‘ÂaÌX<Â.÷É E„ Ô¢TTàm1\âétv!ÓéjE†3 Hˆ9\Êé>Þe°Û$~ã錈9\;RÐWòpºöööQ£FÝ|óÍúÊO?ýô€˜9ÄrÜ™qžÎÈy5¡s¸ ”G/}òÉ'Ïš5+¼þƒ> áÞ|»ßœ‚´eˆ@ œQñ(Ty8]ß¾}W¯^ùÕÒ¥Kžf)iË/€æŒHg”$‡°Aœ®(Šÿåx}¿+çLÚ áÐü©é–«˜`”‘È Eø” (gr}? ÜFŽy÷Ýwë+?þøãÉ“'Ÿzê©ÙŸ¯làt |2qFP0hAE‘S/½téR2»éÓ§¿þúë«W¯¾ôÒK‡ vÆglܸ1—ó•JÚ2DüÆy“c‚3rNWùG>üðÃýèGýúõÛf›mN9å”_|1¯3•MÜËBÛ”P'ò&Çfg. ‹_ܽò–iËP^­&ÇfH­Î8A©³•ZYí°è¯˜ÃU 89î–!×ø­N09¶DV)5[©ñ›㜱÷æ R:#(®¡»½tv¸[†ÎfÜ ”Òk3ŒE¡HJ¸^¹Ê©—noo?ûì³·Ùf<á¹ÔjP0‚®Vx:#*Š<œîÁ2dȬY³V­Z•ýÑù‘¶ Q«™ƒP„9E T«3Ö÷Ãa)¾(§;üðÃï¸ãŽìË8 s,ÈÙGâpÕ(§'Âbly©0 sê(gÌu6…È7„ÁŒ! abNaÕêŒÃÝ2t6㶘Ša‘ýtv¸;÷RXŒ @Á û-ŠLœnÆ ÅZ¨ §NUóç«*?—G­fbBæ0ÈÜé-ZÔÐÐp÷Ýwg‘+¡2\°@MŸ®vM~cµ°Z-8s s dît¿üå/{õêuÁøk0÷Ò‡põ /@ H÷„™ôÒÿõ_ÿåòLwÎÙŒÛbB‘¢p·—ÎÌHLAëf* 89xFŠŠ01‡±@p:sàtB€@Ì@Ìa,P&N—<3Rº@üÆa)q1îHAÆaLgŽ£eèf®íB˜FE˜ÃX G{éLqtF j s PQÀéÌqô>ãø­N„…"JœFòÖ'0NgŽ£N'Äy!)ŠœœnÉ’%ûí·Ÿ¾æ±Ç›2eʺuër9_©`FŠäu¤Â€@Ìa,PN·|ùòaÆ-\¸P_¹aÆcŽ9æØcÍþ|eãè¸X^®Š0G˜@JœFüjiézü~½ôñÇÅW„×öÙg'Nœ7o^ö§,8àâ4Ê™ŽŽ®ÇïçÑK÷íÛwÍš5‘_Ñp¯¡¡!ûS–Š£s/ùÅo¦@ P0pº¢ÈÃéz%4ù[Áû鄘#,Qâ¢Æåa;4j[½zuäWK—.0`@ö§,¼ŸNp:æ@ æ0(§;ùä“õ×Õù¼÷Þ{;ï¼ó|üÈBÜ 5Œã·:Š@ P0Œ{Â÷²:¨Õü‘V1ŘÃX 1N×Úª ªd‡þè-&¯ÐÖÖ½Ycce1y½Ž8ëN‡¼\ ‹Fä…"ˆ9ŒÊ£—ÞvÛmã®^>ðÀÌþ”•ÇJ«E‹º>ÓÿiÜú3fTþÒÖÓŽ@ æ@ üinî§äÑKßpà “&MZ»v­êétwÝu׈#žzê©ìOÙ™#ÿ´ Æå·OÕÞÞõ™>Ðbäzréð°Îѹ—Œã·zèP*ùUÖ!L yÀé $§ñȬY³ÆÓM7‘Ó}ôÑG=ôÐgœ±Ã;,[¶,—óõdéRÕ¯_×ç§klT£FUÙ,°>rXWÙ&梨¶Qµ @¹Ü¦Ô´²Ó’.Ê E ”ß•·ûî»ïè£Þf›múôé³ÿþû_}õÕþ%Í\¡¡ä.»¨ÛoïZlhèqÏNÏï¸qÝ6S:>Üë±ñ;MmLÏEúëݹآÔT¥æwŽ +¦ušà ÂEæ0HØ=¦ ÔäÉêÜs»×—é3Râò›ÒéÚÚbœ.%dp ”š®](‹sFo ggd¿ÕC ËB6A˜@Jâ HŒÝD˜Óu–š:UmÜ»¡ÓÅ^½Ì ÎÎ(«æ1¡HHrº«®R;í¤>ü°Çʉ{\½Œ›{9xpÍüù¡õMMÝT|ÍH)Ò×jPAPÓ– *l®££ãÖ[o=òÈ#ûöíÛ«“>}úLŸ>ý·¿ýí¦M›²?#…ó˜±``3“cùøeèt?ùÉO† òõ¯}þüùdyÞÊ5kÖÜxã»ï¾û®»îúàƒfv²cÇvÿn‚þÆŒéþÊ»UGŸÒg¤x›ÑPŽþ›Å­÷±ØéjE°3ÊH0˜ËÆ(+§›5kÖ{ìñâ‹/ÆmððÃ6láÂ…ÙœxX,9£›Y&ÇòGºÓ=ðÀ4d£á[òfK–,ill\¹re§ä„¤{5G®-rFþ«–˜ËÆáb&½ôôéÓo¾ùæ4[žvÚißÿþ÷38%'ÍH))œ1 Pdât}ûöõžýU•7Þx£Oøi–ãÐ}:Æñ[, Î8Z[”áŒ6 ”bE`@&NWÓë }k´L‹#R €3|P…†V;#säµ a¡H›R»”†xàtæ`FŠ2©•pÆüÖmˆcFçWàtæˆËP:„应P$WgŠ VdUÎÐS5ø§3G\†Òáf®Ë¥&gì…1#oЂò'Û÷ÓmµÕV½RÓ»wï NÉ Gç^ ‹±E Të˜1¼È8]8:ÉÌH‘ ÃÊE†"’à-œÎœÈGV«å†`N®Î˜Ã[ 89.–!ïÅõ /ácW¨Éå $ ÞÝ ‹½tÖ¸X†¼gƒ òª%««©æðEj‚w(âb/5.ÎHá=£T@Ó®Õ žª Ngf¤H@X(¢¸ÇØ5S€@µ>F•û+u¶Rõ=´œÎ8 sx ´J©ÙJß¼ÈjÌX0<Ú œÎŸÆ;~«a)q è©d¿zƒ·@p:s\,C³lÂ4r0©ãjj‰rx äb/5.ÎHAµá4bNqvÆbÓ™ãâ}:Þñ[= E”8ä Ä°O¨Õ'LÈ)89.:< sä $ Ñ'äŒf}ÛNgf¤H 9ˆ9U*uBœÎËP^–Š0G˜@JœF™ ”é„{é¬q± ̲]@ þ@£¼ÑœÑÅ^:k\œ{‰›9ò’úÞÓ™ƒ)€@ÌŠ(qÑoàtæàýt@C`boàtæ¸X†¼ã·zŠ@ P0¼»A{é¬q± ̲]@ þ‹Fx‡".öÒYƒ)€h×üF§33R$€P„9ÂRâ4â-œÎ8 s sx §3O“bz*æðNgŽ‹eè`–íBž@ÂB‘í!W2à-‹½tÖT/CØ ` snSjZÙip 89ÕËP^!óŽßêAX4˜3­Óì@QÀéÌqÑéä˜#L –r^Ó–#¼C89ÕË6И˜Ã[ 89.–¡¼, ‹Fä…"ˆ9¼r±—ÎËÐÁ,Ûb*„ææî'ðC\œ{É;~«LùƒŽ·Xàtæ`FŠõ`Ê7„…‹òBÞÁéÌ©þ~:2s0å›?hDÌá-œÎ̽´Lùæ¼F$ ÞV§3ÇÅ2t0Ëv˜ƒP¤X\쥳3R;Ю™ŠNgf¤XBþÓ œÎ8õ@ þ@#æðNgf¤Xâz*æðNgŽ‹eè`–íBž@¢y¡o\쥳ÆÅ2t0Ëv˜ŠÅÅ^:k0÷Òz sä „Ž·Xàtæ`FŠõ@ æÈHX(¢¸G#p:s0#ÅzÐ ˜øÃ[#IN×Úª ªüчÀú+9¥ÿ¯Â›…·‰[ï#© Ó",ËE˜øÃ[#1½tccÅŒ-ªüÑZôד÷ÑJÂû*r±áûv§¾©Å­×S†5à`–í1‚¼÷Ó5÷Œ(ü| ÜÞâò빤‡nˆõMMª­-¸/f¤X#¥ãµ1NÀÏ—>ó®CúŒÕm‚rðëg̨üÅ+>5)S J1¡sØ¿ËX¤Óýüç•+–äe ÝX=1thÅì—RŸ‘¢ÖÒ|Ö±oF ó1cñ °•¸Ë}˜!ÆéÆŒéžvBc6÷Òäkƒu¯÷g§zÎH¡‘š¿mãÜâÖëØçtµ"ÞmH<ˆ9ìC1NW"Î= ¬j­¶Î… ¤,èyjÝsØ §3ǹ2tmŽ«“E˜Ã^ çzép® KÏos”&¥ƒ”®H‹s½t”?÷²`ØÇoAtFë4JFX Rpº¢Ó™#FŠx9èŒÌ‘ׂŠ œÎÌH±ÃVgÌtSÌa/œÎçÊP^~ EjuÆ J­ÔÊÔÇÇãÚø#,\dß'8×Kç€seèZ~Kg•R³•¿y±ª36àqmìÖˆ¸†"òÞOW"˜‘b=ÂÚ"ç1#0o±ÀéÌÁŒëq\ ZÇŒÅ;£°PD‰ Ù §3'ü²Ð…¦Ô ª‰â1‡½@p:s0÷Òz P®˜;£0äÁÞGàtæ8W†®å×:l¨Vg´ñaqÜ¢C؇"ÎõÒ9€)€Ž7j+œÑq Ngf¤XBæä*P)Î(O#ÞÀéÌÓYb+¬3 ûXNgf¤X0äau7U«3¶(5U©ùJu”Ø:a/œÎçÊеüZBþ$hD·@©éJíÚ¹h…3²ȹ^:œ+C×òkˆ?jd£3Žs½tT)CØü¦âO‰o­Î(â¶#œÎœ*eˆæ4bŽ<ìF윧3§JÚ[¥ã@€ 1'A ràtæ8W†òò+,‘Š@ æ°¿íè\/Ε¡kùµÄy•Š¤sFçzéÀŒ»‘÷†n4jæ@ ÂÓ™ƒ)v3Cܺ……"J\¸ NgN•÷Ó¡„™ÓG©ö²Ó’A#b{àtæ`î¥Ý@ þÈÓHì}NgŽseèZ~­1¡Há8×Kçf¤^ Q3œÎÌH±„"ü¦‘<ا3Ng7ˆ?Ј9ìC89˜‘b7ò’º)æ°NgŽseèZ~­CX(¢ÄE#¨pœë¥sÀ¹2t-¿Ö˜ ǹ^:0÷Òn sä „^·pàtæ`FŠÝ@ æÈHX(¢,ˆFàtæ`FŠÝ  0ñ‡½Fp:sœ+CaùE(ÂÄö}‚s½t8W†®å×: sä Ä5inî~?03RìFž@hÔÌ@…§33RìFž@E˜#L eFp:sð~:»@Ì@üa¯œÎ·æ^¶)µKÙiÈa) ìÚ'<ØûœÎ·ÊpFçàŒSÒF„…"Ê‚hÄ­^:Üš‘Ò¢T{ÙiÉ Q3œÎÌH±a¡ˆ² À® ŒÓ™§³ÄÄB89nÍH±¡V׆0ä>Š96§3Ç­2t*³–",‘Š@ Âq«—ηÊЩÌZ 4b*·zé|pkî¥ ñ[mH‰ÓHž@èu Ngf¤Ø bŽ<ŠœÎÌH±4æ@ æØ kN·~½š??ãcºU†ò2+,éPjײÓ-ÂRâÂEú1½tcc÷“–é=ô÷y[o±{k«8°kú@‹ÉëuÄ”a*œÊ¬Ü¦Ô´²Ó’Öˆ‡"òÞOÈH\¾vÞY=ôPÄzr±E‹º>ÓZŒ\ßÔ¤ÚÚªœ:ˆ°øq­®aMë4;À)½®Eˆqºæž=pd¾yDM˜Ð½8jT÷-Î(ëg̨üÀŒ»&PKçLI E”¸pÑÄ8Î3Ϩ††ˆõ{ï­~ó›îÅ¡C+fç‘ÒéÚÛUŸ>ÁÃvmÓÜÙgÒ_à-uKXˆ9ˆ96$ÏéÈæFŽì¾äèCkÈ×6nŒÞ+¥Ó¥\Ó…ç}½{.úVçŒÌ±!~« ØÌ&,®€1£Êg´A 89n•¡S™µa¡ˆÄ d¯3Ú [½t>¸U†NeÖF s2¨ÖqLTª5‹óZ‹[½t>`î¥Å@ æˆy\›O)]î"¥eôóF;Ó™ƒ)˜ãìãÚÊ¥¦ 9£-pF89˜‘b1¨ÿÌÁãÚøÓË‚©ªp:sÜ*Ca™E(Â<®?ÞyÌÍÝê¥óÁ­2t*³6˜#O RÂÅÑ­^:0#Åbä „ÍTp:s0#Åbä „P„9ÂRvh§3‡ÊpêT5¾êßP@ñ21ñÇàtæP.X ¦OW»†ø#,~kSj—²Ó-ÂRvØ5 O yØ`"p:s*À3îÔFKŠ(;¢‡zéÜphFJ‹Ríe§$ƒÍTp:s0#Åb„…"ÊŽ» È89p:‹@Ì@̱äÞ=œÎ‡ž† :(æXrïNgŽCeèNNíEX4"/&%÷îê¥sá2t'§ö˜ÊÀ¡^:7š{‰›?Â4’'ºÜ2€Ó™ƒ)˜#O „"e§33R,õŸ9ˆ9–§3Ç¡2”—Sa¡H‡ö*LH‰ -éê¥sá2t'§–r[çKºg„5"Þ¡HKK×ã÷ê¥s3R,F˜@Ó:Íp]nttt=~Ngf¤XŒ0Z:/`JBX(¢Ä…‹–§3麟ÄÄK‚Ó™ãÐûé,‰ßj1G˜@ò°ÄAàtæ8T†îäÔR „E#–„"õÒ¹[†˜ò Í™?Ш àtæÄ–!¦|ó6s„ ¤$jdp:sbËS¾ùƒúÏÄKB89±eˆ)ßüA€ÍtP̱D 89•¡;9µ„"ü¦‘%9ÔKç†CeèNN-ñ•C½tnÄ–¡°àMY¿Õ€0 Ð喜ΜØ2DÙò1Gž@¢KB89±e(¬J+kju  þ31Çàtæ8T†òr*,‘ŠH‰ÓÈ’>AL/ÝÚª ªd‡þè-ú´µuÕؽ{`ZL^¯#¦ «ãNN-ñG˜F¼Cyï§khP‹u}¦´è3cFåÏ£9F}›4Ÿu0#ÅVä=®MJs– 4*yï§ X˜Ÿ/… ¨ÚÛ«ìÞ§O÷6ô#×Ó¡ÂÃ:ÌH±ykŠ(„‹ì±D 1N§³t©êׯë³7kmU#F¨³ÏV+WvoÖبFêú(1°>rXWÙæl¥V×Ã鸃ǵñˆ9–$ÏéÖ®U»ì¢n¿½k‘ewÜ¡†W÷Þ«fÏ®Ütó7®û‚gJ§Ó‡{=6ž­ÔøÎ…æNééoÌæà­yó¢G‹RS•šoçƒÂ,‰ß҂ǵñGØH–8ˆ0§Û°AMž¬Î=·{ elÎw´††“UôÍ"ëÛÚbœ.=Ôµ.Pjúæ;Dº3*m Og”U[˜ƒP¤$„9ÝYgUfÚlÜؽfð`uíµÝ‹ôy‡"v4½zI&µš•3ZR«ÝEVs* INwÕUj§Ô‡öXI£9Óùã8}Š¦¢¿ }80z}SSÄäó)£S{bõ-7;ãè­:Î6Ê jôÀ¨›Œfd™£·ìèP»¦œQY^"sÚ2}(bMŽÊ«é·tZ Ô”›N1Nw×]•9'Ë—G|å™Ý=÷¨Y³zܧÓg¤ø†HúÕθõ:æN—^…ì·\Õ¹åøÍ‹)œ1zúMÞéL½åm·©i)gTZ!P>Ôš•W=Òoé´@9x-¨ÆŽíú}·÷7fLoÉ¡FŽT眣V­ê^©ÏHñ¶¡¡ýì,n½ùÓÀ¬©£+ÎØ=ýFÅ:c÷1«9cæé¤Þ鶔3*å ”krT^õH¿%*ëì:]‰lµU“Åþð‡?ü±úûÜçÊö eóöÛêÿþ¯ìD@±47÷˜U»ãŽ]ëã#÷îZï1þqâÞ]‡¾;}П2J‡òø ÔĦMjï½+ðñI(vP0~=Ï°YçÒ+æ'“qï® üF¾OŸè7­Ç¡ïNššºv<Ûû=>¨ë®SS¦ôP6®ØAÁ…ù.–a³è„ŸZçtqï® l÷¦õ8âv'.a ™§žª<ønõêh¨ÈŠœš@g§‚—M¼Åðå'žè~wm Iê¯ä£–bTÿòË­·ªþýƒWcâv×ßÞØR¿ª‰«:ɼ÷^åÁw÷ÝWùœàt~±ãŠq‰¤iV¸ª @Ýè—M¨ùüô§ë}þüg5t¨Z¸°{ûÞêc郾٨Q•}{Åí·>ðU3^ ”ÈôéêÄ»>'8Š*vR÷ÝsMè&e³3¦ÇkÅPÿ¨ ÝGôöZܳÏVîé,X»èZß?út‘»“ÃnLø[R‡@¡ïÙg«•Y¿}hË%K–èÛ477ûSbÆøoÌM~|/%?þx %äÝ—^zé~ûí·ÕV[y›M™2åöÛoO“©ðŸzê©£>zë­·öæðœuÖYtüÀ6”€7ß|ó”SNñ6££x≯½öš¾ÍgŸ}võÕWxàT,^áLž<ùÆo Ü• —j{{û 'œ°Å[Ð^t|:òòåËà  ÿ/¼ð}Kg÷¶¤ô¬Zµ*±8@‘N·fÍš9sæ >ü駟Nؘá›ßüæßÿýß¿þúëªógóæÍ9rdø˜´æC™>}úÛo¿ímù£ýˆ'ezª²nÝ:rýø”’¡C‡Žöƒü€¬í¡‡úè£hñÃ?¼óÎ;›ššž}öÙª™úõ¯­jñâÅ´ãܹsiZ$ã +9è ƒöD ?÷ÜsßyçZ|÷ÝwO=õÔÓO?]ßæšk®ÙgŸ}î¿ÿ~?U÷ÜsÏÎ;ï|ï½÷&” %â‹/¾¸££Ã;òW\Aé|å•W{-]ºtØ°aW^y%mCk(%Çw\}shÀFÂ?1ð†ÇsÌ3Ï<ÞX_¼üòËÉ­h0¥¯¤~•6óÇãÓO?¥5dúu¶7Þxcìر‘é©#?üá¿ño®ã-Z´ˆŽ¶~ýzMCCòeËû’Ìž=»j¦È÷ýLQ$@‹ä˜ú6tv—Q„௡!%ࢋ.Ò7ûãÿ¸×^{ékÈ ÃcÆ; W_£— 9;íuýõ×ö¢³Oš4)°Ùº¾ò±ÇÛÿý¸AÀY,X@]( +Òl¼ï¾û>üðÃU7[±b­ Ø}"oÖçt_þò—ÿüç?W=Úgœqì±Ç~ðÁÍ6nÜèŽË”¾ÍÌ™3O;í´ð6¯¾úêÀýE ÂÙ!ç düÒK/¥¯7àŠ;c /äÎGuT8ííídÁ½h„ØŒb¬îÀÂ]ñ×¾öµ³Î:+ÍÆÔ[F>2%òêešÍâVV…R¢ÝâŽFƒ¬“N:ièСäw4vûïÿþoïÒ_àPUŸãÝP‹¤±±±jv+?ûì³sÎ9§©©iÚ´i_|ñý÷ßOcÆä½ ÐÖÖÞ†R°°¸òÄÌ€;„{<‚‘<õÔSU7Nß‹æít5õç/¿üò­·ÞJã²ý÷ß»í¶ûñ\k §’F®¤á ¨Ï?ÿüC=”Rõýïÿoû[Ü^ ¨[#JdwË-·´´´„§¯6¦‘ExLy̼ŽR²nݺ:Žöꫯî¹çžóæÍÓ™)m·Ý–vL“°úò¸råÊýöÛï§?ýiÜ^4r ßpôÀ˜Döx›6m:è ƒ®¼òÊäiôùØaÚ,à;é;ü~ýúÆ2i ÑÙ£>y }2äï~÷»ð6Ë—/ohhðã2õÈ#ø™š3gθ¦:¯Ž~:‘&ã‘©zíµ×ô[~½~þóŸñ‹_ L›QÃí·ß¾jÖ€<âz¼—_~™o¾ùfÂÆ>ø`SSS`Šæõ×_O›î4¥wºÝwß]ŸóŸò¦1cÆx¿ ð¹è¢‹s/¿ð…/,^¼8°ïã?®;]\¦h_?Säž|ð™gž©oóÞ{ïíµ×^—_~¹¾2MÆ÷ÙgŸ»ï¾;°ÍO y®ºê*ï×m+W®<ï¼ó¶Ûn»Àx02SôAßfíÚµ&L òñ’úâ‹/Ž?þ‚ .¨#ã¿ÿýïétd‘^ªV¯^}ñÅ2„<7a¯ 6PÂÈ%)&Q—ai4:eÊ”ÀÌ8Ä}E}橧žª÷œ‘/\¸ÆD½:ŸB]}GGG¸Ü1rå'Ÿ|rÉ%—СêxL 9Ô€ô”„OñÔSO}ë[ßòlrÎ9ç¼õÖ[i2•TÚŒ6¾ùæ›Sæ1¼òÿ÷ýç¨l³Í6gœqFàà‘{ÑÐrîܹ^–û÷ïÍ5ׄo­Æé› ;€dÖ­[‡ßjLkkëÞ{ï]v*€Ìðî.ylܸñÄOœ9sf‰é²eûí·÷žEüÊ+¯ì»ï¾‡zhøq[+øÿ©yÆ\ endstream endobj 10 0 obj 20713 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000021801 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000749 00000 n 0000000728 00000 n 0000000849 00000 n 0000021776 00000 n 0000021866 00000 n 0000021994 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 22047 %%EOF ast-8.3.0/sun211_figures/overgrid_bw.pdf0000664000175000017500000006241113004147321015014 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ¥½ØwWU'*mŒŸ„&ÚÀ Ãȗ³ë9G: ý#P„H`¾7„¦8 ‘Ž€”LèƒÒ¥Ë…iÒ/¡©!  p÷¯ì}þ$á:÷ÎãƒYßÿ=çì¶öÚ«üÖÚÝ›†½ ÿçÿÞÿÀ±w™÷øð=Öt0ä°—Öù`^–½ýyNõ`ã—Ãã—<çéà:·_ú[Û/'8~ïäÝË)§ƒye;7èÿàãÓŒÇZ¿ém{³CÇÞêÀ±Çï•pàØ[óÿßôN7Û[{ËcoyøÀ±7¿Óo|ìvâtÿG<äa{¡´7rø‘û'?¼={“›¸ÍÍ÷õ‚ïvôó¯ýæË¿úRWøòÏ_á¤Ë—SžyïûþÜ3××ÞìÙŸýãK^ã-—xô1ûÀ¹GÝô©ÇsÌÅ~æ6ý¸c¾ø{—ùÚ3Ž|îÅ·~÷AûW¾ó%žð¬SoþíÏ|÷úÚyçΧ}ý+Ÿ:î_>ÿªW<ö¡Çÿàó~ÙÓ®x÷‡½þOûÞoø‘o¿å+zËŸ<å+GžwÏsÎyÇ/Ÿüœ/ÜçmÏ|ð­ýÇ—ø‹›\ã±_;ó ŸûÁ÷žü[o¸Þï<æf?¸ïÛŸwÃ3ÞüÛwz÷UϽÿ)O8áK·;ûNß9áQqÎs~ùο˟|þ2ßzÈ;x—sîö ›sðW:÷—Þ{¥Oýý5ï~ÌçÏÓ§Ÿúðöü¯›üà¾þìoßþ¸þË]wâoŸyþ¯¼ç§qîù¿zäÑ×ÃÞ]oñÂ~Ú7Ž}ÈC¾õ¾û_ãêOzö;Öûÿð¿=÷÷Åëüð¥'çÑÏüÊ¥~ð;öïõ¹ßyÝk>‹O>éä;^çá>óü¯„/Ýô®ÿxêùõ–Þø×÷~äo~áE7|믞xÝûœðó—»Åû_þ×wOØé'þá}N}Ðýnô¹Co=ãRgÿò;ÿîùç<ñ¨‡ý÷g|üugý—þË#^üÕ¯~õO¾× ôöóü×üöý^uò«Ž¯ÇÝñ^gÜîƒ?|òyGœþÉéKüoüàO¾ÎúÍûýÑ¿}ò]o}ßy/øÒ‰Ïøðôo?xÅÿöG¾óG¾Æoœ|Öãyü½îýð;½æõ¯=ð÷ßþÑW=çßýâ‡Üóoø‘»Ÿxü¿žõø{ßäÏO?k~Ïð—]ñI§>øvGýóá‡\ñëwxÚþÓW>öò¿þùïåw¾áiïþî}O¾îQ|Ý/þÔ/½ñ¨k½íª8ù=ÿ¦Oø¹ý\ÿ¸ÿ·=zÿ Où‡ß8ø‚uýò¿æm?xúýËý¿s¯—|åÌòòŽùlºÊ}_qãõÊ·ës~ö½ç}òŒ}ÿ>Ç=ãI¿ôÔ/œú¡ÝôzÏù‰+}æYg|ûšñÝWÍŸûÈŸºö¾ÿo_úÚµùúo¼ô®—xöÍϸá_õè³ÂÅþéáwûŸ—>ꃗ½Âëÿé{qû#ßÿÕOÜâkÏù»\óN¸þÿýÊ[?õůøï·yÂ;ïûÃ[<úÉ9ëM§ùÕ‡¾ìu/{õß^ïo/ñêGÝûÓïyò™—ºòSsÆù÷øµ§\ýäw]ì·¸WýÚ]>÷¢}æõ/þâc®óìOü~~óÝŸuïóOøÐmïq×O]繟¾ÊÛ?¿òÆO_ïœ{.o¼Ú·^qÒ#nöÖ^übgþþû_û²ÿëä+ÜãðŸ?üЕ>üñýé*78ê£ï¸ínu·>ñÓ?ë™o¼ÚUO}ìsÃÃÎyÅ[¾ð‡G¾ëc÷ºê~î¿r£]þÜwqÞunõ ·Ù?êJó'·ûÈu.ûëç\ûIÇýÍQYÏùä•Î½ÌÁ¼ôÀ¯¼çkÿõçøÆ­—/öï÷ÑkýÂû.÷w¾ã×¾ñ¨7ßôÌS/ýŒïuü%þìöŸxìþœŸÿ7/}þ›O¿û›ßtËc_|ëÓ^»œt‡?úÞ¯>õÓÏû…ß;ýŠŸxoü÷¼ÅC§‡~ÿ~ëÒ/?­_x…ß¾ô_Þó‰Ÿøþ¿žþìSþå¸>õ„÷ÝòU_¼æ_^+Üôò»ò³ït“Ÿþä/}÷Io|îžÿÂwÝðæ'}ƒç½öåw|äáûÝþ›¯âÁϼäÈüýŸ>òæǿ±÷ g¿4ΧM?úê+¾qëzÇ?ëù¿ø´§øÂ)åü#t÷~óy¼Æï¼&½ègÏüöÝÏ~ß_qÜמX»Å«ó×þó+.ùþKúýW¾ÿc¿zÝÓ?þ´›<*]óv—ýOOÛånø™ï>ã³»þ þáC~îKμÆ/¾ý*åãwýÔ©¯ýÏÿÅÛ~öÀëXî˜oü #¯òÑ|ÿ-_~Üý¿ôç/;ã„çÞìox™w]óÖ÷¾êŸ~çÊÇ=à)W½þMO½å‰ÿñ ·|ñ3Ï97ñWï~óÿñÿÖ]1ýkáöO»Ì%ÿë¸ÔôÊýèq¯}Ó=.yòiŸ<úOÿõÏŸ^Ÿ®þÙ‹}êE7¸Ê¡ß¿ÝËN:xð&ûGÞä¤ß;áÖ/»áýžpÂþê5wù¹+ßç”g?àø‡¿õ«79ïÜ]ý]_½ô•þǯ}ÿÁq¿{ÌüÔÉw8ýÅï;ûß»ãÑ_~õzäÕNºòCO¹íëß{¿3Ï:â¶gxï·~¹Û|xºÅ}_~Ï¿ùÈ%Nþ×Ýõ§ÿê¼ÇqíË<ÿ¼¯ýó/÷‰_yÕ=^ò”—¾.ýìO¿Ö9/xßQwÿ©;ýðÒçžt¥ßàõîú¯vèþÌßýú™ç=ñ”wßü¬wŸýÊŸ~ͽÞpµå‹sÝküÛ³ÞuÅ—>äÏN¿ñ®ü3ów®ñÌ“¾uÌç¯÷ݳïwÂѧ¼ç”?¼ÃIÓ_>ï5—½Ô‡§O^òpñw|ñ£?õÊ‹ýÙÑןö´o^öwO»ÿS¿ùÚw?üˆã®tÒ•n<ÝíöôÀÃ/ó{þòµ¿þÁSoùôû]þ·úÒiýOÿÝ{| ^ác_¿Í#nüÉ[]÷ùçðŒ/Þýâ¯úé³_~ð½W»õgòì—üÓQW9ësw¾YzÓ‹~æ2W¯G^î’_yãÝïy«s¿yÎQÏýÑ%®õ‹;xà·Ù»órpÊ{¿y ìݶýïÁ¦½[ˆ!%síÐkdmgWl'Y yÚËë$2í•<‹¬{u*"×½Zõl {sÔ³%îÍó"2í-íƒ\s`-ãµ0…©-LU/¶¶Bˆz3çF/zµ›!f½›Ú3iÒ»­Ç!½Ûï9èÝØžo§-éPÚñÙF zZ½ÑÓ^¨­ñFOkûγÔö|]ôL›·8'~g‰ W¶µL^8ö0·!Åuâ»sY]Ù¼–¦PH·ÿ¤iæ7kë ‘¿×Ö| œ“FWÐYt½ìЫèÆpa.@j-Ô`VldÚËîO[B}^Ê^™Ô›µ‘¥j ¥q¥Æò^-šŽ˜öæ‰-.©1hÕd¤uo ã³¥jºÚç×PûÌ­U¯µÁ„)ê½Ì:ëŶ`fÐ6¼ö{ëŒèÆd1éù6î5K›¬¶ËÔÁ¶ BÒà—6„Æà~Œ»ú0h ƒî#Â3sˆ}áÍ úæÔ0ñâ~¶ùkœGßÖ%ö>7.UÿçÆ “û37æ îO{ll:˜)}³ý'¦Iý!ƒV}³íƒ˜ƒ™¬1P£,M.Äâ¹j<‹e™À ÉK Z}€ðˆ³ú0£³ú0·Š‹úº1+û0·áÅU}˜Ûº¦I}¨mÞ³¶a'¯—ÔÌWþ˜;ÖÌÚ:°—#ŸO=ôÔäR«¥¶ËJá`Së@YÙNjýªÚ멲Jäö…YÍm×ÏâÅœKçÛÜ–cçCº­”‚Vʪy+mc¯JÜ›(÷šäÁÂœžÒšm,Ìi+M‡Põ{z“›ú};ý¾TÈ[ýÖKYS5–<©mµ.kÚ"X{‘|H²WKÑÎ’öa½ ùoyo]}‰ÚZjgÈdmÒÚvyˆKÚ¾¿µÕV¤­Š–[j5›€Å¦)ˆnì3YÖMdùY,Àò¥³Ocy½ “³Þ… f϶ËbJf½öý´ÌƒöxùLIbá°€å·oÖdVÍϦ#ä³ûÙÞÓ¥±|R»”Õf[Èü5M]ÇÕ¿/Ïþ½ÍUÛ¥SŸÃ<ÿbù°Ãæå¢YþBìè@Y¢9¾÷1 µmÃÌocd¹b¤µñLæYˆ¨D<‡ÁŠà¹ý»P˜ãUŠ§¹±ZÕ_ÛW+ÿŠ£jæ»Kc‰ï¥u‚¿QmÞn¹µMÙÂv×Ö…½‚†±r¦×& WòöÚV¶÷œò©MÛ\º ì9Íú½@ÝÐQ2Í ³~Ç»AlÛ¶ ¶—³ÚTNUÛvøœNœòM-á4nIðÆ‚Ø.dHõDËÒبÑÚ‚±@UÑÑÁþElq¢xë$|§êXN*ŒX>5,Iú£ lB§ìQœRê´ß}?ñäÐ3Ô"³XFßV(ó³ªÿª™ÔŠ¡vŠÉ¡ÆÂU­¶ë¡æXTµµ¢öG©Uh•á–ÒVĨ­_pŠ$mñ’Aë,£š*¤çq*ä4DTÌZ;ðd´¼…v×æQÒpÅv\KWm JT`»W‰ÃŠ-‹½jÑg©?5aÛI„àµV¤ãvÔ7›ôˆ>e¡IFkX’vEÑíÔ™ŠE¶¦Äx¾mÍÝm/´í ^©÷îÈø­à÷ iÞú \Â9Ïd<|°L |‡0Åų޼ԠÙ4t¡ ®8 ådmóÙ&>r+Cšó€ž›.úf&Cr‡£ësK TÇw¡+4Í’[»M€s¡Êͽ±N¥kܘØ&£ðÚ aáXgŠ|mkhÞbÃ)@#×iÁm½®c[G+rXfâÛ¶-å MnkСPk'Ë4Í,¬-Þ†Ö4xÒ80©- –±âÉÐþM–i¬Í^t㜘¤¤5‰ÝXxJ}+7ÖöV†BUE°¹N¦4ƒµ£èele¹4¢ñ‹,p¬Y[¶-h뇷/”+‰º¼ÐBÐÇé‚%ä6ÝØ¿DžFÚjc£UghqÑœ”ºmpW\uBs;®V¢Z?¯ŠÍ·…¶Q„¦Ӵ¶ï7)àm45ºÄm»t… §šŸÿI'¶N„æ׶OzŽ1cj%ZF%Øó í—û²@D2~Ž¹IÊŒ׆‚LÑæ«püS‘8í£OÔ¨z$mXqiÖÙGãË8·ýÑT d¤S3ǽ”¥K9l’˜ÉÕ`›8ê¢4¬’R¶ÃŠU-ZÉ ‚¯hhŸÖ0Q¥3L´}˜Aߨd0óš®"BÙVU'ú€iÆ*Ôvrî³lÒÆÙÐgD·•iÜ´Œ°ˆS²dÑèÛ¢ƒ²?.Zal–¨ ßÄåÆe0õãªw¹¬k5§C/¢Û™–&é‡e-íº4ÐRÑðþOzjJãDÑ 8κå63ｋà YBÔ:ípeØ1)þß8tiÛÂ&Û™2 9t‰âPnAÊnîF®슸ð¼*œU®8v¿FP ýãm©hA»\É>3Z[)¡jÇ5Ëî6µØ$eæ—s€f¤»5À} Ñœ8ó$+d•”žÇ`ú»Oü×ÖƒÒ >—& £¤1×F TÆš™/ák˜Šy®Ž5kº:Ì=IÝÖŶ~Q|†w­MèƒM¯Tƺ&®‡ µ맓Öl£­øàùMÙI![Á¤Òi+·ÑµKÅÆRF ‹‡ÙÒÏHCanK[‘Fòôžð]îþ&ѳò~“ž,Â#qŠx£³äÒ z|ŸÌ ´NWÌq”¢ÑÙh¾˜ñMÉ4(Ж WÔI•*ž— e+EÉ4lÈ­(Ã…Í ˜ï(Ó¿$ôÇ65Ö-ŠÇaì´“]2<5FØ¼É ±×<ì¬ù.ý¿±þs”‚ØÆ"E67é”$ª¡’§ºJp´VnÏ‚6+ç ‰T)v¡æ6sA‡Xûn¥Ovr’í:#–YÉ+ó‚g9²Pftº$7¬±¦‚R€Û gv_©Së`*r@7«eÂÀ*O[ÑFÏVÇÚ3Y¾<¨`)ËxǤ}Ðà™àM^‡JÕ[VÏ^”†•ºÇ.ž§ZԘ͎”©¸¹£„PYÀ<É‹ËE×æ.ë¦ñÛ±ðã‹›.Ho š§ÆP[r#¹¹ýÿl¦øâUÌR,æÆÒ9­b{Mn<¸Æ› ¯U¬g JeY>ОÚñÀ½˜Á(Ô-qR§Uζ *ø"çЄ#cɺmö 0øÊ’Íhâ´r”+ölP°H­”,Ú ¢¥èðƒB×d€öd@¶W2 ëÝ S¶E¸wí HÛŠ¢ÿ>jLCH{—áZþÿ¯b]´×FÒ× Ã,WZ¥ÍN.œ×ÒØ7ie­‰fnq6ÆÏò ÃÝ廀ÎriÀÙå週•åAØ&ë¸ÂšäHjZ–Ón%Kp¸k“ímµÿÚ>h«/Uk¦œ°JÕVK®°€Ð[k[¿cIWسi±O `^¼Š8K’U'®´\Ü´:!´‹WÇeñÑ •-«oÔ>²Õ%ijK¸%»¯m%û\"æÝãrWEª?aEw}(^Q¸&ÂÙ§2ÏR‚1±•Ú$ä[[\`V”úï\¸ —‘»u X\ZlØPMqiÚ>Ì>Q¦6§mkkmðå˜í|hkãþµc K)ºb#û÷kiÿ_š­^¬¥¾Û3-ú~Â|-^'Ì—¤6i–Kšj­]ÏFM&¯Cf‡ ÚÉ»²¾Z3ì*GyàkHI*nÅN’ÿ•ª’zÈÏ®îк¨5K¤µN0N¼Nk[Œ»y7Ù§ý²îÐÿÎ*ú*e5dFŽÀ˜« Y( ]zcetŒq†šÀ–QÓ&$ûl†‘³gßt¸p_ÁP_,9*hK”+fIƒ=ìV\±—|–ƒ#&íxê›ä³›«—×1‹-`‹¤„&¸Hs$¯;†Z¡öÌ=àH;È3 Í4YbAëì§N´¼¹ûJJõjì7ëuè(¤cwUBÓÌ;A·®—¤½äÇ€s«#àS<˜F®«é6[UáÙ™JŠöæÙRažìøWøÝá_h’:ÜÛ|Önʼ–Ÿ¹Â’–ðΦ¢s^Í”µJ´š²ÑЃlq‚©’ãz„ÉØöÛDÏ`ÙRôjCÂG}þøîBPx¶ïí¼c{ä_Sm6¸F´tð×wÖ)3%3ù8RrêÄo4ö9¥£Y˜FCÐ*Ad®<]×Yš\؃!øv¶É" (*Už·«hp™ es´ Õ»ü²± ­)éJT%rÜ¢gO=9%]„"™ƒÀi:¹"o‘§Ï¤±Dôm(-ò¤Hz¾ð<ç÷aV$9”£41îžföPé]hA«pàÊ…;"l ;Òòz£i´¶ n[!³PÉ0 ›FÜÝF 㻃ÕðLø ÜÝk<•ÔO:W«Alà\iêiªÑ5ü.©›Šì?Z÷ Ø3¢–J¥Ñ*'·®Ü:•Vžn³qJÐAŒY¢ÇØ'ùeDc¼Iœƒ£ÉÍ:v¿ý23-c„楻ÃL¥ïHø\$æ¸é5ÜyQ¯v›Ïƒºã—Ñn‹Þaùßwºeº‰† ™É9qïäAò‹^(‰^‘QÚÆ›Å)ÕÏN{r‡ˆä’c›S±IV… `]Kì‹äžÊppW$’»:ƳñJ’šWÆ4ÖÞD#{yoîM¤½9l$Õ팭${Pd6öæâ>tè’ÈYdÓÛæÕáëeouNS¿mùБÜò!úñÆrŒü€nSØö ; ­“è$ÐUMA¤³‡R¦‰?`â(ÿòDàÏë ¨˜1qM„ʈGÄ ï@ä&Gîÿ\±'¶Q ­‡ír, .O‡vöG”¯2Ç3ûœÚ”Oõ%.Q‚=å™´Yi•·C/"0ÇoÎÊç’¸‘nÓD ”g H²¨Ùo"bA€‰m!žgpQǺqŒ©2èFYE³#J†51ÍŸ/ Àeѯ*” ï9 ”"R¤¤ÂP¶%z$_›ˆGÀGsBûgÒ|Ò+Ùœ2ƒE´nÛÛ(Ñ¢•¦Ÿè´dÌ”.fŒ¬‰Ø3ä~Æ#RÐ÷Á±Ínãw û ˆ¢è°  è°]D?~òºC]K ·O€ÖÚÑ/-DK¢üŽêC ß˜ÂD™µ.O}ñÉÄwyž¤‰ïrã0FæàE¤lŽ\Ç6Å¥;âJ+Agà 8êÜHØ22j?vŽÕÞ•XEJÔŸ#°T)é Yˆa[tñ‹·ãL/Î(@4S¢L=8"ébV (Öy„’"ýqÞOñõAÇ4ž);ßÉójE˜>¢#\ì}ˆ :5¤ö¨SdpÏcIŒ\MÒSBc'??aú§¨s;‚£@Ý‘bcØׄŠ<¿t¿Û\=ƒ±Dÿ×nÖÙ[F@*2(* f1EY¢«øD@q>/Kqƒ¯ýó¶/~ßØ^¬oÇ#³?qÓ˜£‚œ°4z  ó9–½³r_ØZvÎÉúï™ðŸÆꦟ9kïÃ]&‰´6Â)´M÷*•F¹>M.Î{Â$à¯KÂƱ 'Ô›äkij@®A²o!f{êòјí&‘` =?·¯é– 褠µl"˜*ía‚P“dP%~J]„| –ã¨@%$ø~ƒ,°&È5Á¤æR&¥3dŸU”‰AG†¹‚¢1 MrqAÔ»Jž&Ÿ,ã€:Tè=5! È¿IXÑ$ vnKœ%û‰¡ÙØè<ËÇH$L–¼›{¢B"àC€`b¢ç*+™HHU²¼«k‡»$$HDy<šô!‚o’\cb÷Ø €H¶\l©H÷Â3:y!«Xd,8k =™DHD§¦[.Ýü«ìž‹Ò"A½:;‰m‰³älþ¨¨±ºí pÆ,YLÔ¡jî¸Hî Fá3µ ç+Õ¢H¤äR%¿ˆ(\lÅ~¾¶i®Br ~Dƒ0ˆ‹k– Ây¿rˆ6‹ëlÙ”;¼ŠË–&ɵÀ3Uò”Y>SrÒ Ï]ÉÈ/E ˜Ä’œ„ƒ-ÔÄ¥IzòÊóUrÑœXx;ù„±éÞ AÆóã ÖÏ)/lm§qè¼áówAó]vdÍO’;ŒÞJ<‹„µ(<æœß–;pà[Á‚³¬r¬ ª›Õ(À¼ ¥ƒgÑ T×j½£ñ«œ<ÁÚ é äõíÆT‘¬í†­µ"óšÈf ædÐ1LŸÃ)«i¤g_DCi›$˜‡A)1ÒjÇm¦DºÅÜ«a–™ î ³Õ¨ãKò6$æRÛ“èJ™·€e9Q‰=Šf9X³Q*¡LQî ­‘ŠÑ¶ÿ¤­‡-¼õ¦Ò–YñÌ:ÛôÎ]¥\¥‘šTŽmជÃòø°œˆAä¬"º2¼ˆz~±kug»-Ûvë[/_€¾¨­ô ·œ€²‡)MJë5!#„áŸòAóŒð‘P´`Á 0‡Eœƒ0ç"†Â^³X\™¦%Ñ¿*P*3òï*M‹`Õ ).Ìqà8q^ —+dó4’ÌO3v«À! ÜB 6ž.Ý gaŽ:Bf˜¤ÚKT#„äIe\s$[`ÏtÁÓ, ~b°}DÆXô3ŽÛ u¡¥­2Ól­VsOߢ»­ï%¸Ò¢2:"U„l—ÁöÝí…#Yn»ô`™uœÀü­v]e·¯WçD2­+IÎuìšÔ‹ÂHcá"vî£RF•ï¨lŽ6MÀ~¡™8ÙmDŒ Žî‡ÙÎ['as ‡Äë;.¡Î÷ÿy=ÂÉáôYœiž·¹ÌNT$k­ ÜÇòÆáé£E$aÐe žF%7Dz—ÎN»ò<ÀVE °qr 9,•ÉzhëRëè­§l<,-»‹]xè£=0Ä¢Pˆqb’‡,¨cµÌ[i{Q7PÔÅiàh«ÚÅ—øÃóÎY"û9úI/¢áô Ũbé€õÄuv¬kø™INÏ$´¹Ç¥Öî%»+^0kö"E$j 8.…ÉÏòGDÙ²¹ "Ëûg! $€©ŠÍ0j)5=2ÚXå×Á(sYlÂÿ.[‹à·".#„ªˆq®ô˜öiVÜ‚øÜmQ ²b3Læ,³2^%¡¿oNֵǩÄOˆ™¥(}–¿- $ÿ(QZVú‘Ôöž¯ŒoI5jLbÌ_;²G|+ÁŸdàWB6bVª ͯ<ÉçÊRÊWO`ά”§¦ëMÚ‰˜.bù”H*ç*;?5˜dÀ„¥£%–LJΠ“”D÷&×4r¥•_nLc]’?ÓJB–É_@€þ‡eÈ2¨©Ê÷A^µQF$²ü H#<ô+Ž•í˜ŠÆBp¿}4H¸6Ö8 ¸Ø·²v|qÊÄ'‹À‹Ø Gø#퓦_³Ú_ŸbÖ»óÌ'¯¥dÒÜý»ˆ%Î ‰<öÉÉ_.ýD)h õ•“ ä{.ô[‹ÇЄj\Å èË_ ^»¨r©Ry“Š®€°FQÉÜ ÆGá”°„dDÛßÐ{¢ýeñÅ/ÉQÊvb‹p+‰ÉÜEs¥ÄkÍÂ"=Æ_´ãqf|FsÅšÙ>Ä<üS ö?ƒã¤aˆ.ò-â°q'&û1Ç‚XË@¾yÅjìãÇt8¹<Á pª}—ÝïÆ8O°W†tÈŠA©–Ÿ¥ÑLYÔ3PX¼îL×Q¶i‚'{L±^“œ 4pV­#Žð ;-,db,r:å“J “/µ. ñ0BÙaqßÊPúš8ˆýtM ³%÷ø(çâØ”GíGdŠt(ëk(G!AáBn®l+‚ Û&]{*¡x eÏ2Q¥â$€Âæ&ÕÝp[P³ÚB’”µŒFÇ® n„o ’>$ùyáÏîÎl‚ACqV¼‚¢ÓÆ&.Lï&_9hV›Bƒ¤•Ê»öâ‡Ág”“ÜO8›‚ûIZóß\=öCA|   ;´æg_˜ÄK ¥ ñix"ÃÚ?¨º"=6û4È<õΪ8Ç0{êYÝ£P—æཾ˜“Ú‡]tˆ3¨`/'VÆw‚X`c…z„¡î•0JI“ ¡_ÁA¹¬B³œiA&ÈæB ÀC#'™®3׳›º#º—Å2gªoÎ,|%êwµ«2 DÒ pô7±ÑßÊ)Z£…ýM…±† €ˆ$;-Æ,w$ÆήPij²¢Õîì¢ÊÄÕ9b‹ï8J[‰f’F‹þHúGx’òd×,ú#3“n¯¬ôÊÈ]àÈaÖv)¬dm»‰®œí†v(^Z‰„²Û¸ŒÜ¢ˆ?'E¥èBN*ÅA3#9â3ÉaŽhZ´Öðj¶cHš.±}Ñ‘¢©gž0Áãò°4é$WZ‚I攤D”“µI ;©¬ K/¤YRxb^ƒ$ÑRú[uäÈ„ÚÝ–Ð,u"2‚/äƒ ©n®÷$r£çŽ£§FnUÆ?•líÏHNÁ N%E0uDU£µ× {3åêPž‘¦‚LÒ®¡fËhÞQàÒZ¨Í'£˜ý)Mšš}’˜D]I»"¢-9*HÔ¸´^€œ;•Àî)5A4¹N£Èü*Y0nŒÀb¸#EIUl!G–SœG?“ë*ó¯TÚÌÝÕ Àw­¡•&‡Yà ”æ”˜:,mƒQ~ŸvIéÞ²ˆ*o%2IBWŒx#Á•i )eV™²¥ß5ÿªµÍ¡oÂݤ,ê”ä’UƒpÜü¹ÅEÇO’»Sýgâv¶e2õ„oBJ»& ‹…Bå°"S.DTŒ]R)³”柩ñÊùH,¡Óåâ¬ù‡…ã°c`ŽŽ’¥úHt%×<9QiO Ž"— ;Fe&ÐÑÑoF>u^á}Lgú4¤e´°¥„°‰€rv”Tf‰„Y}À\e÷á)¬ßÝ7„’²û†y6—W´Æ·‘]…©0¬¤¾±èEr$_®Eÿí_ó ­kö…>[h,Ql¹­=œ•0Ô¨®„ÊPQ%¶hÑÅnéÁW#w_‚ë'*§–^T ‚Ñ]˜$1$ ×b ‰õt.ÐðíVAërÒZ@$ÑßI:w¿VbmÉãÅM/ë­,F4ÀBC*òA$X;âdU"\©UÌîVŒò°ÚR]XJQ1–óï!•Ž!dÒd£*P·Hûý W‚³’åäËš ÊYc*Z³:ÐÖ¡íƒ&6P-@ç—G° óQ1‰¶p&€ðØࣲò’Z€Rê¢e‰…Ðj·ça§à€ÂeÒ¦vÕ¦„”›*=—ÆG"nBL%Ûפ³±&yØ2tð;ª&Z>c[ý}Ø8Æô‘®þ>œýeÚhÛï°l”­ NK‰®þ=ôJC¢£±21öE¦Å¹zFÊ=éP¶ïÛÎÃèC°ÿA¶ÌÖÿÉóOº,cŒSŸ«Ú à™îßæÔãj´¡Š˜ZË|̸’©¹(ær’îb[6…2¸š«'¬}Ó>2¬}‡O6–°· œb I¯E㥥øµf#Ø3Ò8oÙr±¤±¢ x‘}íUCƒ0¸ýkÀj*y‰›cÎsß3¹Pk1n;l¶`P·ïS"¼•^úŽ­Pm5|VV4,}Û×d)±îYi‚^TÝÄŒZ²¡‹‘â&ÚŒï@§ŠÑRõÕZk´x(¥(–…³‡0«S…`Ü¥_ö!€òtâ Ú9Ý…½"iÁHàÂP ]öª\Er¶¯ŽØ&©Hw²›‹JðP¡H§Ú0ÙÉE}q*ìW—ŸÀ8®fÞ%œG!7y€Ž6»úAcÙY! T/+@ó“‰É¤½ÕU“ÑC& VeP‰`xƒÒPÖ4Š@²´¨’ñÐ@HœC  ˜GŠ¼ÙÚƒãŒk+=5*†ê3L%»ºŠØe˜Ì®;G œŽœL,›på+sÉÀOý\<¤¨J· §ÊU5¾ ñ†8‚ÐyVx•y¡¶¦‰QF'ÆdýXmòC±†o®Æs.ŽÈŒª8"‹×€úß]X¢, Šy¹:Šî“6Õû8,q¹é± ׳¶I Œa(6¥9EÄPZ¢çñfURÓ# Ž\œã+ØqÀ—³6óZ²Ê5Fˆê¬< ?Ë•¡ágåÁ±V·è™Ûu‹©DZë ›³ñk Þu`w%<Ë‘;l¸dÐ ­~åaþå—!Ô°{fÉÂF¤eU€ ;6'yE˜?¤ü’˜¸‹eÂ)eEüÇÙnîü,?>#’YÚ`Lóæ1Hô<¯ÇloãŠaekÍÜ)…ʯ2˜¹Yªx™›é(!4óîU€û9;péȬä^LÃ+2Ûc¶v/ ¡°i.¦ñ»A-qÔûˆˆ£°æèDa‰Y—΀‡d5=ªÂЫ–z|^ËOxØìuiô<òÕÐEççFeoFljñ{0]zvœç³ƒb"c~šsfö81€rNÒض—†Øh¢–§.²¨òeâJoR4=w¯QTîÃd:÷lxyƒÛef¼Û%HÆí½àv „t»à¥àv—©£ˆ-tùIÆõíe"H6˜„ü/ç%E·“Ò:±À ½ˆÄYÓs/b'¯¦Âk–GÓ,¶/š9S“i 7VÓð,-¦£u»)u`sˆ\z“ÍÄÕíÒ£åvUµÖ4ò¶ÜnamuÓ¹ãÓíü ¨Nø÷‚èv÷‚%Ý âPÜ ø÷‚þ0÷ÐÁŽ Ö½ o̽€ïÇö=´¶(IFDDœ "…ÏÌTÆÂÐ_ÛýaÐìzÄ™å-gû_éK‹¦ñ¼ÔyèÉÑ6´¿¨š7¼ûjfwE{pÆj_/ °ÓŒ\Ë/ËRšÎCd¶Ú_«’œ¦¡œLÃg&û.~¹˜^G¤®Ñîc#ÉO£´¼£Ú%ÉÉüQ58˜‡ïïN¦YpÖô–­ˆMDÕ4áuÕ4àuÎ LOA‚ +vÿt%D{ø°£$]¾1ÛÎLJû¿á+5Ê"ê­5š™U"%(“ç|I½^4Ñ,1yÎ"Hžó>¼ÍGî⼄*Åd$ #ò=û¾=y{áé³iøù•‘Q m=öŒCÕʶÏÕjíkgôß>r´Õº³±2+Rd{ûòá¿”MÇ$/Cð™ÀH3æ°P=.|LaU"“q€èÌKS¢²A”d¯K$Ò@V3³PŒ6U§O(½N8ã L?' ߤ<˜šŽL€ð«û6¿£iõ×Õ}Ì{u±zHËY Z®býœµ!:¸-ø/½¢ÝÖ<¢ÇCÛv[@>Ô²ÑNóÀ5 –u¦õM¤|8Æ%Z¼wq°_ôìwa81EÚs‹ëqf ´êïT˽ûŒÇºì|әǢ{?áìý=ÕÑçì5"½Ä1Æìøé:9qÊŠé0æ0çm>s_#x)½_DOc]rGžÊXÇ´Î;ô4Ö݈ÑóÆ©÷×­;t<Öcbà=Õó2×Á«–'‘EÖÃàížÆczêü¢y .Ëì`d öTˆÛþbÝdï»`9û¤=)eÈqfÉǾßq×Ñè9„4z…0©]ViU”!!¸ŸðH÷3Œì|Ê"Ö€¦Œ‚‡Ö@8„B‘ókû×¾¤ZŽÂ_¼òð£;ªÁìàažˆ©KSð"–{>ö†s$ÿÈ«Vá+üÑþµ½–†òo?0z!&c ¶TífFÞs$ …wFÆ>3Ò 6‰£ˆäá‰Í§â\,î˜l¥'ìHc/ rXEêÅ‘lÓRGŽY)ê*c7Ö(¶š”uÈ V™ðø´ÒŠ¡*muŒ'Î[®SšwÖ¯¡Ò¯&.À‘ü‚]hdÌE{ ìXE0*ov¦ñˆÚ¾’õ%{"\{Vþ4®:”…-…^>i6`Žk½F¿²^ƒ‹ÜØÔØ“f%x^¯1¯I¤›×`¬l„Ã1ªN§-pëaÊc²á¾é•(åÌwõA>ec‡€æ·ÁM¡¾›èïÛën{Rq^NÈŠ„¸ÉùP¾w]™æqTÀóNÄ€Ò㜩‰›Š‚ÁEÐ/ûkÂÐLæ_†è‚e|ÆIP’¢ ¨œï¥Ä¥Œ 0as/-˜Û•} •¤~Çò³\öqæ•,L :$̨o(.êÉûW\ϸHafèZ9u°Ÿ‚ ‚2¡fvYlÞ¼¢M¼|È%õ¨Ì©lNà1îbm˜¾~ËJ`˜F¹KŒ± °´ðæ >3´ ôî‰ ÝáûKúÏÊôî¤U×eðSºb·Ô)E õ‰ #AhÔןÌ0ìjRD*ö›åö–#S—lù‚ªÜ•WFpˆ•"pÖ*}5ªÑ Wòí s]„òÌ#yJ¨VBQɲX]ß&éÆ0ä ¦ì"M¹—:g…‹–‘\ä| ˆ†õ‚€–d'þ„Y]H»Å·¾T¦ÝVóB<âatéB¦Ê¸%°J99áˆáßq‰°‹óH'–@-ѯ°@ª“ÃC,&©@ØÒK²Mà º»‹YªÅ®]–ú±–å€ì2U)¹s}gÂ’)ÌG7~°»>²|\útgÉMçË/ä6‡ïü[Þ˦Àxœ ‚’›t¦ÓÄns™¶¼ßh÷,óÚUb•.èèò;äÁè|`Ü~c`'i'Áñƒ0Qf'(O>­àëRgÞ=j×7‚µRJ"ª…ƒÁÔA:¯c .í62âÔagøñ=$ðWBŒ—«(xÇìp äXvxF”C-%ôò\ ñôÄ=¬Wˆ:$pêAŸ˜ éÐ\ÁVë¹Ù‹Aw¤Òg‚sôi h~`Ï'O»se„˜?ÁV(mœ ÜIð£Fhõû gÑ=ûØék8ðì~Q&²‹÷3ãÓ…pVÞù¤lN,Vô  osuú*¸ÐSñ\bž½äðf)Ëû-¬¹ãÝž†•r¢‹œc…£KÄR¥¾ã!,ûí¡a º”Èþàîä4>¸†WEp9Ÿ0L~Í‹‡\.G‰Ý@ø›‹¡Rç >3¯`sáØÊ qHÚIz†Ã~ÃJwSꨠz@ 5VßÔ¤!aa¦x%@œ}«*H"FB&U0' qÒ‡ûíCZ_»ñõv‘Žsft…©¨ 3R$ÿ:½ ¹uYaÂr'ßLRx;ÛEoòµwPTæ4° —˱OÛ"“ÂTµÐc—?çÍ'^ÓI%ÒÙg s™Ö‰åI]ÀŸåI5Ÿ„E»ð5‹Ky½X(þfàú!Ì>±Qð_îhÞ˜˜¤ác븞$Ûrˆ¯+Å9Á",¿šõ+jRúYËÚeÆ×$Ù„þ¦µ²l¦V•e°µG8Ê+Æž®¾>$ŒTEX’’uu•A¿ý-0­÷<ùºÀ|†Qav•eŨ<Õ¡»d'ÄN,ê{°¦< î2nŽc8œ+}(»$ìê,·/¿È¾K(°”¸ú@¸†ï‚ã'û^Rè^ë€vÿÚ¼KëðZ_V Ðs½X?i~½^ —Pßs”˜ñ¢ÕÎ Û €Ä¹êåÉK?ï™-•U&ˆ7Ä9T_èóÉÒϾשpµ“X{õýX!ûB^–¸Zb/¥yó%Q’/Þ`8¹_Œð°ïc‰!‹Â„_…Ì"Þýjã‘ @ü©o(ª¾c;2µÔú/6ÐÉ€¶„DãÞ¾º†zRò™ ÓWXðÊÙdsgbz¨m Ï7ßuùw`[ö·G¶ßËø]hAüfÛ¨û"åÌN¨L‘ž&3Žol/æñ¢d‡ËÔ¿ûI34ÝÞ®§Uœ¶c¼ˆ\Ìýíú½qÀKø½RÙZzºÔAÆ‹z®ò)ô?ÀiýÐIkÀk’ÓÎë|g¼¯ /øÞ_v¾•{+q¼{ß´êTe(;AÉ ~CåÇ—ü6¼55êíÔ«ªeè„A'¥[Èy£c›A’Éo³øˆÚà—¼az ;oèÞñ¶ÿûfñ_rOã͉ÊÄþö¼C·'…öM+í0'&Ë# ¯ºŒtoͨáSªI¨Y»JãPú±f„-¤ºÑq¼ koòÛðH-jƒ×«³¾jÎì­ñmt” Â~§9»¬MdI¸ßEØ[óÛH¨^ü6èê·G¥­‹lƒçîŸâµØ‘÷3‘‹U§Cîå¬Y0:nôÒ{[¸T¿z4#-—²&-âuŽö–—:÷¯fUßÛ7Ý+wÏLTחزÖuôÂo×ý6èä§bO%q *#>ZÓÛH¶÷}U¢="”¾©U=× ÍËFçþ6ÒùŠØ´Þ(,Wª7xg³K‚ƒV´!GÖ”wkôÂ_E(»ú« µ"½¹ü¤¶sºˆ§2Ó}ô¼¼‹Šycƒ¹à€èÙEÄY•J<¬¶im}ÒWÌÏú*iI=ç½ÞyÔlÛz¡·Yíjá5æÕH­Å¥Ï!UXÛ´¹ al]à–Ul|ôÈ-´à@O‚Ë«+µÇ­´ùè‘ÞFÈeòö;턱¼N™adiƒ¦“ŒÂ³Á–=½Gj:ÌF´¯„›™À”I•ïH^]k’lí’ìÂýóœýøSð” ´ßiïèT“÷ûóFOî!o(F˜l¿Ó:f åœ%SûS@Ø´K磠¬À{[/ôÕ… }•´öF²3F*“*Z::QÙQö•{´†^¬Y•sÐz©¼cÌ&ïZ‹Îþ=;¯Õ»T7:ö¨ÏNjA´Z`K®ÌÒ¿Š‰˜¦“u#z—¦îë2]ÄSôŠe=%ÚíM½,JÆÑk™é¨öè‹~~îÞµm j–Dòþ õFáÝìz£¤^aÔtU ÒèýüÒýq[¯Ý‚£ûƒÖ€X&÷ <Ù¦µO ÆKžcÞï9î½V ´\ªZ -yÁJv©ô~ôñ©aÓ˜ö\&–§q?è%œ7:öö¢axû¦ã#ÚŒ dÑ—0ˆæÞ̈·;Pã¾JÎ1¨…@mÕeì %a Ÿé|¥­¤ø¡éà–§^ËÏ=õ~Š<ˆ°Oó¢&†‰ô6Š7+•Þ´÷;¯[÷~ŸÖg4]Ü#r<¶Fû Á˜ýA³ –®gñ)øDu¢Š&ÇfBS•¨¦1ø®1}‰¥¯«ÚSlö¾ƒ>y{–¯7­kI඲=í¾J*Œ1¨ìx$íûBŒêþ¡¨‘ó¢Uê€÷çDŨè$‹ È›žÝ£©W ÝFàÖ&•æÞï´ø•öouÿè+ðµò(N¦:½~~íu·¨øîáç ¬€ç.z r@^Ó²3^d¦…ÞîÿÂÛÄ*.dº§£Dù>ž¼C÷/!ÍXýN»ç™Þ} ’CžÓ¾¤$çCîãYwèÞ“úÝWÒâdÂÅm–ÂD‹Jñ0]4jìR¤3aä¾ÍE´öèÄèiòósO£eúÞ-9Usí»qü‹õEϾ^@T!qx/Xœ%½¸ß±;èã\wèÞS/êisþD–Fˆ­ÊŒ˜–ö>ñb”èÞ±üBÞèÐ]"ð¡¦Ô~§]‰ˆ³áµ0‹ ‘×wDYó‰Q'ƒäE» ü8òin£QËŒ\&µLZ°>U‡v•$VÆQ´ ~@‚D㸠|up¿ieR.¬¶»ˆæ(ËÝ{ÁJ¡g„Ìé+‹]¸i—Áè_¾fXECÓD»dËÞÛ¾ˆqº†Ô?ß/ð6xªliÀ›$ƒˆWéðˆ°_ß Å7®J‰ÊŽu]]¿]ãÐxŒÙN1xR‹Zf©âLÔu”-Ø7/ºŸ\,³Þh¾àôN“‹‹qd.ÈÕG¹]¢¿ZŽŒ:©e]³l´kq©§˜#×¼"- 2Á3“-ú Œ­ŒËx.ð|äð7ï«W깸¼^Gø'ѽRš¤·¨³é^ÔkíW hœ.e8ÆÌ––~™Ù2“–zq<–)õí ëHôa·$*‹~¥ÐK}1H3£ŠÐj™#³'´R-óøØ2iåyµ™Á³LµŠ¾®d)ýZǤk|KÉ:õ¢¨¦“\Ö‘¶t¡q’ž/â)bŠúDZp<`,ULLÓeæŸf=Å^v¯ö+bLG¿»Ž‚=ÿ¼C›tÁ̪^”Ø/:´ó/þ%÷Ô°N«¯¼öH²ráEÁÚs¢%+y ½Ëe¢RB/4$Z«»ðzM­î˜õ‚W«&õ×Ã{¤Ø—†p›VËy\@”X]<õ⇥_ŽÄ|L_”|R´|v‡T‚1l¾ßií9\Œ™’¯øŠ,:m´Ë"ò*&%R,¼âH`yÑ^ÛÄø‘ÞÕ(—º÷bâå¤êÅÄ«›õ6 žJjšÖ—°s­;´ó/¼ÍQ’¡¦Õ'^£äµåí‚dŠvÉÇ8®÷Ûæ…- šWÞpÐì“6BÄK]ˆQ´ä)/1R^üRvqGÒ:™äé’@š ÉÙ1/êÅLü•zÁ‚ZaóÊAÅôLûÊ …×-¯¢e¯;´Þ… Ⱦzh)Ÿ¦]6”EºŠGã™P*côêi_\„G]ËÍØzR™=Ó."Š hï½MÅ—!‘–”eÄ´ØãñçQ€ìO°†ìêýAktØ×­ç¤ÚN«ˆ‚j;—A5-”:Mú¦ëW%—E'¿»ô„ÜmŽÔ;Ć}Cï°—t˽&£‹E÷Ò¯ŒéZšŽámà&|ñži} ;ËEJ˜ä\\ØU´æ;O£ð°çhÝ¡‹[ÃND,­M,g¬CvÒ hÏRD ·†Û59™P´gƒå’]‚•˜0íkqM›=_ëíÞ!_;!c|¿Ó¾à eƒÉÍñò¦]D{Ï…šgâF\Œ—´¤8“Î]ÐU3ᢸ}VÔ ¤¸cÊ÷Íyá•r³Ë)aê>JÓ.ƒÄëP]fiXCÓ.ùƒ¸¿0”¼ 1RozÒÈ°]þø¼üØ_ÂÁ±?hõ:»DR%fÞh—*"Á¥“€˜Å ¢³ße ¾ÞŽ¡ÓêëÌ‹õÍ>wê]fõN´zžtŠ­ è|3­^@7uê- ÌÒ¨E÷ ÑÐ {+·í«ôsr1.Óú/Q×Ù0æNoƒC¡ìZ¤Bk4QPÝ]Š‰e0RÜhTƒžºº€Ò:õ²¦%'x±½“ƒ KÄ÷l¤'Ñ(›!ý5­½Ì8iõÒ`ÔÅòœª×•Wêª×µv4—äZ\¢]ÆÚ® vÚùÞÆ~…éH»Uée=X‹Šä %o!´]àÔóèP}NÕʲÂ}±?h½Áâ%ž ¤=Lž Ñ®@ÅÂûú*aš Ó3vÆÚËø¡G.EÚeó »\™æÎõ¿ú<ª§‘×[«§,Å"]¡ËÜËÓvA@`Øz„cû×¾Êf§õŠÖ¹\ˆ°sYBæl¸¶˜hõ;¡x‹¹•²¤Ó˜vµ­Ü¯‡ßæW½˜ª®îÞ´ú"ÇŠ›$–¢qÊŸiõ4Œ’3TŒ²™E›ÃÂ(EÃÛ­³œEë´bI›É#9§.Öç—=%R?"ÃR•Fú%¢æ„Ä3-™”‰Œýíþ¯}´4~°Ó“èÜKî°ÚHö5¸¦ƒèµ—â¡ —ƒÎ:Óê7Š»|ü˜_õh¿0k ¢ÕovrʧŠ ét3­^ ›HÈ ÂO³bT¦]¶“ŇÄyP¤]öØ´d»ŠùÒ>Ω´ž1¿ê) ªõTUÙÔ‚J#åöULDšú8û¿ð6³•$­L«ß,¹¬s—ç—`­~Ýé !€$uI[ÓêweŸ·ùU/x-HÑD«ß(Píë‚]jÝ¡ÕSìBÅÏh eÛû¢uº|”¾ÉkG\x•´NC—•Ò79§’ÿc~ÕSpL”žlZ_XôJ_ÐkÉ*ѾXcbVIê_ò¿öU´ÖE¶MËž‚–uý1‹Ùf—ËWÉ,_܈=©Ü«N«ß‘…öôÍ>¿lU$Ú"^.ß‹½š4K¦'Ñ,úµˆF¡/—ÍKKnÇžu[a§£èQbœFuVN«×ؾ,f̵z ¤õñcÑIŒ´›dÑ.=P¶×€”èI q4Q¶†á¨qwà×pB‚û‹X™Ä¬Ë•3Ì\•¹“ÑHæ%:“D*ƒòEá”kŸ€À+ßô H“ÌvBSàV‘ãc$•Ä&'8!ˆ«Ö{¢ Çx®÷Æ0Wµ;Ù¤>@'©:Ï q i%Ý”õ)þ•2Î M~Yú\Ýb !bý•‰*L 'tDgk˜iÎDFg½öÁóÞ]¯T¯RV¨„d 㸪ôŒ¤.(äª= Âùȼ`B¬ÄjÊž3Þ~fÖ-;í¡C¾ HëŠ\;‹ñÎgd£% ‘T~ Py ”—3ë*WT½X§AòVõ˜à"fÐð6ã>…t k IjÔðßz.°½=C¬XšœÍ]™óx‘u¿V¶•Ø§hÌ3Ë'ò*–žÝ¶„*ºoKŸ[§ÑÈ:šæ°.(ºuSÁ?=Àœ¯UäøIõø^j.‚ZÈC}cž±ûF¼ú&RæÊ”ú°$¤ïº˜̤Y9¥Ît¸ï!Ò‹$ â#‡JÌG[;9;©v‘›u£ò‰fbéY·œÿU»pÍiœ›ìY'cÄí5àòü1AôÆn˜µgWG'Ë:ºŽIñ€æm˜ó6ø:))ÛÆœétBá2èÔPÈ…ƒú¾ºTûm²òãJeH{0…d·É§™+–a˜Âì‘òÖí¯ª[Á d³¿²¸vDíTkméy¿{¾é»é‹Ñ¬É=ÜGYd×Xó¯ý2¸Þë½™ü×ÅŠ{ˉ­HïŒBÙ2ûú˜¡q¥”¿Œ¿ ØÞèUÞ¢ç-<Ä1ÇÀP~äåB.“džZ;HVÕ@RÊûË:§*µ!2®ãákS“ÞÀúý–ðñ@ùTí|½Èu< ä|­l+[]°;®i3:©¥âè´V}tÌ•p1ô1:‘.ÅzÍT½æ“nŒ.iÌ“W ?Æk‰·=¥eö¤†õš+О£¿\;l•Êt·ÈRå]gx^¿÷Gú`ûïŒZÇÎ{¾»#LÂm‹œûl$yøšî¶äÇŒ¿Ø§èòi¼Æ«ÔŠ¯:›{|À—æÅÒ»Ãõ"q;gÙÕ@L"ÉzáŸhTÝÕçRÉ,®Œ€ì}[ ©:| ,ã5ÕkáÇh(ª‰`«°Züc_ßèÝ`q0w5{Ü6*@ºGøUÅ·ú³z¿ÇÔ_ô÷xʼn~&©JHÓ©E!Ú'ÆÆ4“bùyRÐÖ NŒÙϳ~Yê¯u’cÓ¬ª­ƒ[Œ–N©~þ¬ÊxGyúøPÍýë¦0EúkY÷…d¢“&‹ä³jp’YTB‡‰®$ui{õÑTJdÿZ+BÒõ©–Þ„h|UË:o/ÕܧA£¼r¼BÄ¿ƒìógM.|·îPbµUvi>&áHõð zrY—Nirñçyîï¸Rûº‹¯›jMöòHeLnSïSfaU=±ŽYDro'ë:¨cÁù«¯QAR`Ù[‡]ê‹LÂäy¥.ã¯u4éŽ.¡S(9Ú]FÅ+wyÓ«Ïý„¾ÞÉ<¦1ç¾Eiéú¢•Ô§vŸrŸF|È—›Ô¾þhÒ]ê蜾Ä;Fõ¾8®â4Ø÷’êv¿õ$Y†#º“L סô.»S¾$xùŽ:…©£øzMÖÑ¥Ñ嵋’Iù³¶oZROxÑ\¿¯dƒš¶ŒªÁ‚ì_›Yöw’ù=ÖªnìÈU'7ö‚GЯ{ÁǸú«Ù _]lȳ(Í þZG“šºÄN öB{}^à[´$˜s—Íô¸J•ˆíÏêÅ<&䘂mžQöÄ#\Ò#D"ʺtʃ™»ÄÄ;®*×W‰W˜ ]B„ä‹BböW@­ã¯nn C®ã;žüÞKv™×´«Ë ûHø³XwÎôÌc1yºÉuH\^Ž.Öé¯©Ì O2V9éÈãñ3)ã$zùüœzF¦ò11^ä“(‚¬*z,5÷¿ò^†è"Z¹GMª¼×në ó.aw‘¢>&Q°ÜUÇmêÖœ,S§¨¢ñ¯Tç‘ÓÙ¿ŒÚ”bßì» ãv(¹æÒ¿®\p«öb ™õ%ЪPÍ艰ˤBïq¦ZÉ>ÑþbŸ4_©SúøZ{“zÇ •iòõ†Ñ$_Ë=Ï&(OÒK›{ =M t”í¾PdÖúã¿Ib1¦ìy7Êö3‘2úÙ ºù3oŒeØŠ20XG:!ÿÊßXÆ‹ë0¯æ¬NbÁÔég&–>Å òÒ0Ý°z²u7&[ÐbL¶(Κþ̹Ô;j2NÕ¼=PÊx­nFÁæ­*ÞÀ‡çi°ú¼-ÝìôRö–¦L7üúk,œ¡¢§³×Ãw:Õû-§ñ¥™IÙjÀ™ÎüY—ݳâSßÂrò:F4yéŠ/¬ýÏÀ2öƒ¯()ä)XÂØÊÁ£‹,õï‹B›úk¯ÔqILïeï1nPò@–: ®ÒÏüZ|téü¥ZæLlãô3¹nk¹:¦‹ªe"ÿ°šêjdÉÎïp(”ž3¥ß™>„› ÊäìØïýyÄØúwÖzßS‚+tËD¨K/÷çYS×/Õ“fËÀ–~Ï#V9¶‰ßQ8VÃît.Û3¥ôŽÞ¬¨T:Ó.<ÃDåèùn(“ßtçØÖ XGײ®Ó^9DC¡Bd8W¼® ÷w ô~†uë?ªôgàÐè}f0Ï}½,ý™Þg¼ÛûÌ`¦û‰¶GŸÙ7¿‹ž¶C’½@Oçºõ´n½ˆ;3wfÏô^àÝѱn( A# ìgpÐôwQî¨S´Kf¢n¹û€w{ßðÍ>s£ÿ ”õ>¸èÆuçKe§…²ÓrÝéѼÓÓegë62Þ„ègëò»„où›¢Õžé}À»£oëÁÖŽ  azc«ä>üeglygÌyûVÈëî,®³6Z™w¿«¿ˆoy+m/}X¶>ÂC2è´µWvV«„mŽEk>ÊΪãÝ>Ïz^Ë6Röa<3×¾­ä¡rfõF¡ ÿ®ãy¿½Íl »3Pwæ¼– ÿeÒ_væ¹îÌ3ÊwÚ~·—î½}u™æÑè þEk1¯;ßZvÚÀ-îq{†7ñºT6 e^ ÑZ <Ó×ïöyÆ7ûü£­AágÔÓ¾ [ÓZ,ú*߀·w¼Q·/¡zÐÎ8ÓÎ lã{ Ps9 ö{kÝfÉÏýtXË6ˆ|ô™A–ù Ã6“kŸáÃ;m zYú3}–ðn¾ÙÇâÿ.ÛLªÏž%–@ôzÆ)žÆië]äí ½§;küüè)wè`kQß·,¿ï°]¯H§wž©£û0F³³æèÃÎh–±j˜ô1še¬GœÖ þî•å_øÝ}ýe´½ìô‰¿×ñ¥ñ;é²óŒÝŠ|׺w`©÷à¥Îoþˤ¿àê ÷…ªú:¤6蚶gêÒ9O·o_íÁW—7ÖíK# :l-£æNÿ*ï_%„S;@7ìz­sØú‘9{•¦¯®;­-;½˜·Þ%ŽÍ%ìËö}ÑâÂqÍ3x·¯AÇ^7‚M£ýõ¹óLéãß½SÑÞÈë6`7{¿ó¼!ï¬I.Ûà,s”·1ðVaöÞ¿y“:½ncPOÇòº!¯»cà_&»Ýòè/…w¿ö4õi;›¦<ÖôöU @: ^HèþÆÌìÉ©ÛWQ»³·Ñ ÓÖ;$MöÙm Z³‡gúìáÝ>3øfŸ±¹¬ Øe†}î³·Ômö>ì/Á^žm KÞÆ°¤m KÜÆ€Dî>ØQ} ¢}‡lØÆ°Äm KÚÆ°lëÉ>ŒgêîPw¤ae ¾ª&l_]ãöUÞÓé2mÏH{ö:¯µl_­eã€4L¡}_¾3ùJ£0L$ÿî›6ÓéPÿ ¿Kzç»yç/ùÂ:bªÃzá]žÞÎ4èuX/)°uß‚9í˜w¼«·ÊöU”ïòê%DFr¿FŒ´"‡!›EðK'Î…Í€À±Ó›M$€§ßÓ°^L»­µl}XvF3o£ýP6m£‰ËîìÅe›×˜vg 硳*QÅ…Z˜Ø¢“Ž˜ŸÞsYQ;ô´=#‹Äpôuû¦è^ÆA¶@OæíTZON`ZÃà­2 m9•¸C§gÒö®l‚¼C¬“† Á”½Îy³:” 7æ¨NÃ6Ie·G;½¶•²l´€,ЮÅwûÕikmGÛgJíx&oï"]¸StO£ÝúPwfÂvÆhkÛ}óÎhêÎhêÎhêÎhêÎhêÎhêÎhæÑÌ;£™wF3ïŒfÞͼ3šyg4óÎhæÑÌ?6Y$ÍLÝ®€ˆÛ—æykaž·–—¸õhÓæÒŽÍ“–°C§gòöî’·oŠîeN¶>àÝÞ·%Ìc4£ÿM×/Yg§µe§ëwÀ$»Cs![ÃÅ¢ÒÖÙêŸhJÛxÖM ç7{ËkÝ¡wzg-\¿¯;ß\wÚZwú°ìô­ns1ú/8øÿr¤F endstream endobj 6 0 obj 23467 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:03-07:00 2013-08-20T08:42:03-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000023771 00000 n 0000025341 00000 n 0000023712 00000 n 0000023573 00000 n 0000000015 00000 n 0000023552 00000 n 0000023835 00000 n 0000023876 00000 n 0000023905 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 25511 %%EOF ast-8.3.0/sun211_figures/overgrid.pdf0000664000175000017500000006452313004147321014332 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ¥}Ë®%¹rݼ¾âü€¯“Á÷܀ͤø<°aô±!x ß7×#˜»ªûZ²-ᢣöÉdò ÆcEð_¾ž¿•¯ÿïÿþ—ïÿñŸç×ý_?þåGõo¥•¯:æßÚZ_ß?Ú,ão#î/Ü_Ο¿íy~É·Þ_þÛÿüõ?~üËW«­þ­m~ç?ä?øø3ñxÑ×××úŸ?þéÇó·:¾þõGùúÇó¿ÿþCÝûçø¥Ttàtçã«=q¾%ž¯6‘õ«—)r|õÙEî¯Qõl-_cëÙóËlKdýZϸähùÀŽûÚ^O6Vžª÷bzëÅh_¥t½åëüO¯žîœçôîùé´ªwÏÈK]z÷9Ï·ÆwŸÝ¿J*é3Ñ¥"úù*£lÒó´3&ÇùŒúUfå@Ÿzó»O;ôêüîsUöÃï>gDe~÷)Ï×ùß*û,ØùH!½Ú×ó"=Ë¡9ƲûøŠèz¾ÅWÔò>sXÐh³ÆRÖ®‡V›kžgºÚ\}zë™vž]Ïœy;SÅvÖzð[ó4‹c/ó¬t¬ÉwgÝ_±+û0Ï<Ç^˜‡2ÎÖ§±Íqú_1© Ïr×Â99ôÝD7ÐëƒÞ¢¿•ñüFÿ<_Óæ8œxÈó÷ç4ç¡ÏÑcó«óü§ÇÐ@Éu;ËÔ¾Fh:ÎjÉ/®³fÕdœñÎU5/ókUM×ùÏ"×pævÕkg0{ëµ3•‹Oz$–uب”¦ÇOçήÑóãðXhÖ™«R=ÿgH¥jìëŒàll?sø¶ ?þŒréž+rÝÍŸjs.õ<¼ÜÏqöÔÚóöm÷È>Çó¨ÿüéþœ?ŸÍÔrèqVüòRˆŸ×áùˆ©þ?«Ú,‡÷ê2þiâ“õ€o5WóLetñÉ\àÏÇ+ Z}˜àá©>Lôaªó,P,õa‚Ÿ—ú¶>¼âÏ ^âÏõò*¬×ËüiÞëÿ¼#¥æ‘C§ÑÍçãðŸ‡^Xjâ´z¤[¶žôÁïÔÓ¯¡­^ŸI€ VgÛùã+¶ó¶Ù¶åXbüv:¿(אָ­yƒhØJƒØ{(öΠ!V§§á~X˜ÓÖÏì#@¿7ˆ[±Xï`çÐïG²aêw°^-l¿/Ð'ýtº´GÓö€µ»ÄÃéÕù¸–â¬àùˆ¦ùlÈbq5*ØÜËufè°¹–ñ°$מôþ¢Ìâ’žöWè[g¸HƒÍÅ&¢r–ôaŸG¢M–Wû`És¾\ö)  ÎDŸçÃ,pV9êcÖ;l[û¼tŽÏôG}ÞÉýms7]üiÓU0”Þïuß¿7ÈòhJƒø–hnŒ‡1‡ïð¦¸T6Ý¡±VêDÏ6NFdz޺Õ‡»J1ÖƽêJ!·(ãÈÕ‹ÏRTn<+õ ]ÈpØXÕΕÜ{] @Ó´¯'7Ƈ¢Ñe™ÁÖj ‰±‚…š\LZØ ‚ >^Žž•]4Dû”9 ISzèaf0Óº`ŠQãXt-X½‡±DWŠXјzm÷#»^&«Ð§¶ÞåªîjF‡î¢aÖné† &Ç–fùª6&¬>z·ƒÉ½ Á±ÚD¯òšx·è]Õb´çƒ)ˇ9ñbPIˆvÌ!¿…7&ù :·”;’››‘kÕ!O+œq±¸àÒLg¹Ž'º: Äcq?K³$÷ÀÔ:J²as>Å’;6MXÑg+“‹Ë/@RGÝÚ˜V æ™'Ù° C2zÞ5€Õ™îòß–0ƒ»å@ ì͵‘út>\­·c§ažwÍŽ‡©'¡[aêé…Ê^mÚ‚Ï-u¨ô»®ÃÕêJx^EÝx~[íÎüª:µ«7ÂI‚íY)£ B± ï=¼4 ?<# eùôCêT‚Ëχ¹ezþ™‡ŽzI!“7–x(@Š‡&Hò˜X$óC’‡VMr”•Ðh0¹z66!›õ‰ÙùZ·àª:épV’"êˆêC’[ÚåîßØ0AÎæ<ü¶(âãjá‡Ö™Î¯h ÈÑ}.£#šÊ‚)kÉì«Ù¢£M‰4hχֹYЦΩ ß©½•3%‘†ýXåuä¹Yì€é.²ú{Á²ù\㲉Åû„Y%Ñ5È"#ÌÝjmØK^>–ü“þw,? Hˆ ›Œ }±JRC¯cHnÀ|ãîÄÁPç©cƒRŠB¡# íÒ¹Êlg¦j'«ÌcTùÜöŸ,:(tUøgj—åfëœYx jçA¼O;gε¶èpÓÑBQ`}çÈ‹C7ëbxFN<è_µÉl?GüW­ÛÇÌy¦.oùó)»& OU˜AîCÙÌÍúï]ÄÃÎ>×Ïx¬ç&Ï~;R I4ḃóHžynr'`¶Î°–±I«€ë÷Hv-"ødkÁ]‹8’eľ¬èŠu³òUÁ—Y^ò²=P¿—¼BpžÙµÈ=³?%¾ðÝjÓs@+G©b§ÅŠTúàþ×–¨,]'´¹Úe„WŠ;(ô.tÜZíDØܺvÔwEÑã©WD{ׇhíÿï«8º¶â>$Ìí<Ò:-¿vwø†ÂaßÖµtÇ’hk;ã79ƒÇy¬Ém­¹É›élrr`¿5ù>®i:¬ fµBuŠY“·n“%8Ü}¶Þ1âµÿ \qÚsPa«ÝÏÙ&U>°‚ˆÛ™õÐ*bÕ%\q¦Õew÷÷*‚ëM\iéG´:´»W‡e÷Á }­©oT=šu%„« Kø#Ó̓o…Ý-æÏÃòS?gE?Ý'^Ñqö<£¢ßrLiÀ˜ØAU᧳¸×+Jíªvk\„ÅeÔù¶±¸´Öàm<"šKsºÙ| À;vZkƒ–£ØñpøÆý;'–RtÃFöï“nU» ä¼×k©v E]+åóµ¼N˜/ m: Îúi ÓÚç aT»vefÀmTí`€ç±6ë®ØUïà¨?2VÏ`‡äÿ ¢dƒžòÓÊm¡¿Z³ú;­u‚9âu‚›» m¬žÓ8h¯ìÓ~Ùô¿±Jà³\%hÅÍhËÍÁhÑGÅ5ÿçSzcetŒq†ZSOÛ‚ÔΆѪgm:ܱ¯dàZXr4¬’%Jm§;öp±KqbõìuG<ÚpÒÉg!VÏ<Ì¢Á FÍH 4Á)Í‘¼îà)âçud¤‘Vg«úXbA_ÉS«Z^÷¢WrHõjàä20‚fǽ¬‘nJ¬jùˆ¶¥^R?ô’_=îêÁÂ>«§Ðù€¦^S\ŽšÖµÀ¶ÍR“Ð:šØ'^I¸ÕÏžPx]RÑ¡yœ[ݸ‰­D€ê©á<Ï´Ÿ©iƳ.m_ Ÿñ»ÐÚhï¸nC¸’²à¬öáºqö¤û =¥ÝAÉé±`U%iáNLóPï\aµ¥GL†,å'‘hC¶ JQ†'Ò¤KZN™:±õþ"ˆ¬Ÿ&NŸÐƒlpâh­écÛC>=3¨×xµ!áÃpôÇÅeso·Û£ýÛšj@€škDK¸½›Nù¨”Ìäã äÔ‰•Z,¥ýÐM`€ÝšV•² ©Mpœ4¹€va LB“VG³DÆPè»ç­úCHH2„8Zt½KÉ/0W¥&üèJeépœ¼«4•Ô‚«É;Ç8âáJöѱ¦ [ðôy4xÚ#,<ÔMÑóˆÊó\í8—²)¤‰q÷DH Œ-hÿ®\”ص†´|Ûb×cPŒiî0¢ïê0­<5¹;0Œ:¤.Þ) /ÀO%õ‡_¯s¥©3^[û60 ;@RaC“ì²ÿhÜ+R_v£6o0­rr+†šýâéÖ P‚=g°Ý8=É-#ã­âtlêZ½Ë÷ë–Á¯Õà ¾ÒÏX0¹“&ÖÅÒh>z wžÑ˜ÿâó }¸e´ÛâÏ;¬ýÛ.·F"a$y€BRÎ ‘l±Á %Ñ+’{…vžœ`"«Ÿ}¾äÙÕØ™SůE*FëºÛ×rÛÃ0 (j÷¼bã•$5/n½‘Ÿ8d~¢}üDýë%©n7l¥é®ƒ,&Ë× ÷!1K"›ÈÃ,s¨ggA—û `‚<úGÁ+ ²8ê1Gzò¨}ì€ID€AtGL]ÖÔ<:µˆø!h"Š‡A9öˆ¡Íóú¨ w”Æ’È £‚ "Èvê&2ˆ:OŒ$‚+VáÁ6`ሄu9– ‡§Ãºû#䪬b1Òˆ¸I?b .Q…=:û@ƒ<­ò#"Q9¶ Ó!äs©ŒÚH·9z%âE”g< C³O¯pLÊZú‚*¢tØ’ïFÜ(«*tª «h…d]‡…*¦ÞÁ  }Ï! Êð°@"µ#-í»Ò ùJïn}4'´Í']°’ÍЄ*·EG}¸*-Ziú•.ûG éÊPñ£ç!W ¹ÿŒƈž É'Œ Eg e@…Õb»¨"Â_½î2Raa‚¦ªÂÿ þUY¬¡>ÃØ©Aý™1Å:C¦Â0üüâíódÏO`kÕ L ¸ z˜%ŠÑo)èKú:bë—¦üÖ3í£ÖoD+à÷9o±ô!*âU}–n™í±T†‚¦Îp®‹ÆN~t&àᯡs;h Ìôº>o*v2(~¥ÎÎm®‹ÎmŽEçÿõk ×Ž¢èIoôfØI–èŸ Îçe)îçòU¡{ÞöÅbûõr}Ÿ«…WͧBVÒŒû¦|Ç|N$c-¶w¾J°Òú8'Ç¿ufþýa넽J,Dk(îi~´ "8g.5miÕ^  å†4|WâúH1hÔÚhò›X´Ƽ+xD„­üž8®n1$ÆiÁ‡Pêœã–4„€v½¼õ -kË \»Ùòn©Q­2%i\ Ûân×ßW[ÉÜæöB r¬ R¯–Ì« nm|l·õn·Üzí7ú¯¶B#ÞzÏ,6‡ ÁRnc…“Bð#oŽÑI&äá‘h‚‡Øç ʹÄPÀ;X,B nIþ­ìA)ÌÈTh\¬«ì¬`¶•$‚·™ÀãÓÄé,‡A‹-áðv;+ ÃÓ 0ÐǶ\„EC%O µÇÖiÒaj+Q‹ô1SeJ-¤F ¢|ŒS>N-‚,2£Ä(û€$ ±á´-R&X ®ñ®«‘Î9gmÑÙ–[ Ž´P"GPC3ƒèVª<‘å´ƒ¾½ÉAã·Ûq´·1QV¿CŠúÔBðmA9TâHAڶ݂‰ˆbÅMß‹ü¯€Â{\ð­†â2T~B‰5—AH I+i6à~Šž ¡"Š[Ê¡í/H{%[n$7fé„âç¼Rl'%BŒ™$ eÏYhŒ:<Žv"R©Öz,u©üÄ‹öý‹Å¿Ç¢­ŽdQ’Úþþ(¨ˆgtñ%ä\÷qyúí­ 7ÿ°ù}†ä´n¬ò2ƒœc|9Fp¤”uT„òg¡_+`)aãZOØY6kQì’ ãª]™¿"ÌJew×\)ÛZs…È|ÆW& h®faÒ(ÇËBÍþøΩŠÄd½I#u¯Ë±ˆÀ–9ÃPŒ²N&‡i°€üòŠÓØ¿T‚3Êëd¶™ødÒÑæXt…bÇ%¬èRô TêÇ1¥*êè+^wæé(ÉôÐ0ì-…^¸åY y³µŽ@5Øu±x‰Ý¯Hå”CŠ°š²´.±Åþø´Š°lŒ]Yç« ºÝ´s—IÇ’{°rèdþCî]lI·ë eQ e'ÔX„Ú¨‹'¹ ÅŘŸöËBbµ²On/Ýó-£{€* §ªØ†d¬Šmø[Л¿³-cuˆ5J?>4·=.d§V9y¡0¤§g áê éPöBC±ð–€BÒÈë•wfÁÔ¤WJø犟ð7•â~ÂÓTÜOz<ÿˆ•>w-¾Šòh)—–ú-N)UˆH½#)»„ÍÍñ’ž€ sý¹dy²«ªÄ OÈ9Æáp'ª]xuÏŒôH¸Êç¯÷;­2¼+\ÂszÆÎù·î25s.Q--U8¶ŠØ‰ÅÖ´jkëY뵧s$¸½Ìx"Z¨M¨ÎÁ`L³9Þ7k½X¤ ìoØÕƒµPz½šF¿ÑxÅmÙíø)¡!6õ7ô;è:{A±ÍšâÔŒ´b÷TQçX-ô;Í'äk“CžùM²?€%h½²èlLº¼š²*» :(€=UíOÀ¾­Û`8íe!P®*ü›({ŒëM*:4uCýûtÙà ¯£ƒ0õ«¬‘PΉÖz+×Ð&ªo;HôdÎÉ¡ðÓ.&vIn4z|œ‹T‰o².ùÕ®J*U(ÉàGe¥¤_ '¥ß¡¯)Ó™¦x鱄¾©ó±{a¦ó¨ýõº×î¾Åèó‡ñ_!z*ÐýµëæxFr ±£?ð$–ªÌ\›ÎçBÜiuÏHOÇ*õÓÂ<™-ìñßÒY¨ËWá 3¥¤GS¯¯Ž o%ÝŠX¶p@ñeé¼Á8»tÒ`n¨ñÄ‘ë, fVÉΈz±WŒtÔ"©´u.E¿©û„/\<æ_´ ÃÛSÍP}ê¼Ø®gAa.ì 3†¥k0¾ï³®*Ë[vñ$Žõ@‡ÝÆ°À™x£Âiý¨ KÙÎÀïšÿZY}GmÂפäiÂØBUˆ*²‡ÿÐø]ÇO•«Söóµ‹í’'ó¼ke6½ôhØ+bü¡ ”+c—ŸÆ6ièך–P´¢Â¤¡ù‡}ãˆÃ_ŒzfÔ£Ò<ÊÅä„ž}võ€Šê¡¬Ï Q|3è©ó‚Øžð1ÝèÑ.ÖXÆÂv‹¸Lÿ¾.> ‡·‹ˆ„ë`qUdGŠ«6T÷h÷ óVÝ7èÔÖ×°åì'¬%÷ 6D•NÚäWôïˆ@iÞˆe²^s2ÂöK@Ø~ÂÜ*’U;ñc²¹áŽUÕ¢=içÁS#_ß¡ñ|õï,œãßg–#©Øí_YzCçBe L¹M›þgV) ^}4^œïöj1-¯è\¨@aŽÝ f€} †>PTÚƒ°²¥‡²žŒªRU¨iCR_–íÔÁâ‰N°‚—xŽ.Vã#°H1 ¾eí $y¸*`̬÷‡lÙ¢lµÊÊd“<óóã_ß?˜©\¦¿z•Ö-“DK¸ a±¤¾íß'²\§ŒÉe¤å<¯•ÒY^ÒV7P‡Ý3Aoºg‚~KíBAHÌM° ºQu¤‹a&íZ2ôî; &ZÕ_nŽ¹€´¹Ö‚ÐÛ¦·¿¯µ#ZR\©¶´IWÿ^²¼è0L扬KdZœËg¤%™Ž·}[¹¤{Cdɬ—îoÿÏ?éXwŒOÎÕÈšw¤w6Ù¿öÜ—wb-ñ1ßÛ ¹Q£t_²Ì\4E1¸–ËÓ…úc«äÊ'lò0„=eà#xHz%S¬ðkÇ.0ªòðÝ|ÙQ!2réô"OØaÞÇâ²ç°·}k0›¦'å¼2Ýõ³c¦»~„¦ñ¢Ø_Ãbét{ä.Âxá•ûuX<ïû¤è,aØsÓÇ2âXgž3ÝŸè([RˆtÆÓ‹™ê†I5LÔ×wµÍ°0Qì ƒVì-F”GKÙ'Óƒ"±™`åx«U&&ˆD°Úâ–))yU¡MŽ7³t/7ÄžKÚXTb‡*C2 É%gää*‹HNŒ=£s‰´394˜Äå²MÈŸ‹¼À%:]ôàŒl*<(‚Jdè}20™¬'ïNAø_¾Ùå}d)QåàÁßÇž 1RƒëmÜQq¿µŒoñ«=>@*nÅz¹¨$š+ͧó¸Pj%yQÒ+—‡âOTÒ|b¸Ií x<šÊg2ú܆âªLµ)Ml‚Ô!ýj­†É&T@µa'ЋŽì#ØÓ†CHÞ5P„®w×Fp¨I}bzG ÑÄVp Zošá@½gX£ÐÜV€ Ëæ¨4†Ö +Lú2à„I_®›ÌT[P\¡u—Y† ì M{ˆÞȦòŒ‡†¾ …ÃDsõ¾)ý-‚æ¹LZ¦Å&B ½á¸ü[SÜHÙÖŒ[x×!]¦È»?ès” *° 濺?{^óZZ3žV}SᇨLE”K„iCJ+‰Ê0ŽÌϪ/Ü]Ý™äƸ\“ ŸÁÈ&Uµ=Ó]€Ï4Ù„j81 R5C¬™2¥ƒPiU†3%K5ƒ)™B-O—4Úæ}£kBsUÜ‚$ŠaÒ‹] ˜î&Èz4‚¤¤ûHê%µê¦B4V7º/î_©°!˜Mjg ‡ü hû€x™c,@Ö䖎΄Àaw\ꤸÃSÑYÀ¢^øA“ë::݆.`\JÍ \¡&æð¶ &¼Sµ˜Œ»‡i¸2úuU9ÌÂUÀª€LªŽYw†¼´_”vZLÃ="~`™ úDïÐ/ ®’e0BUËî)˜ùª¨ é„Æ`‚¯q¡L”_† ˜*·z©²ì Ã¥°LrM¬CjÓ¸ü>Lãw¹ò†*¸˜F8®Ù]¶Ó…ÂìÆBHãw£Yž[æ#Ba¡!Ð…®¹Â =£N € e˜¾Å`èR«Ú…‹Ãòî5»\ Ê45NË ¢z,3Y®FÊt ˜]÷ËŸÝwptƒçβ#DlT‡ˆ `’áe»hX“®vñ<ëá4H,«ÌÕ€žVíÞ豪f7ë±9"óÐ욃KÊ EœGX0ã‹HYíö„§ÀÉ¥°I­vÙÁmbôÊjÔBܵ: Ž9©Í4ÜA:©®O¯v¢Ýèòwß„Uâ®3Cé$þîž7„à~˺͔§¨`_d ÝGaši ¢Y½ë1]3 –QH»ŒwvJ‚R]”/—cñw™ïïãï¸àï2ÍÇße­¿Ëâpþ.Ó‘üÝ1ÓÅD¯P5$ V±Ó‘Ñ4#Íö?Ç…ibªMÏ,\'—æãïÕæïnÖÖ—û‘©RÓ4ž¦ánꦞ•® ¨qÄ€ºÚ&?J“ö~;IujM#lëï2íËßeu~÷çÇ¿€æ„Sa¹Dµ»ˆ:(øÐæ^ÀÙ³Ü :ÃÜ `§{щ ·ó0÷Ž÷KEÓÀ bkDˬÿ,O`~{¾ôò·bp0A´¿5/èA´Ó;”‰åoQûK;½×*XÖ™V›HõP€Ë´x9¡Å~ÑÍïÂÁi°iÏ-²»¦ÇZewXu©8%úã™î±“þhÓ Ç¢³ŸÀ¹g?AÏqûܼF¤{Ü1ª0„é:ïœ8UÅt¹sØÊ;Ÿ-×@  D?w]j£@Ï~×±ŽùA?wÝ ÖÝ^Þ¨Ù7Þ´?è¸<–1ðžÊx‰VÑ ñªå yØ òv$?ß›‰Äÿa^‚‹Ä²{§ˆ=UâÝ_%jÍ}W,gx[€´'§ YÖí7‹±bÁ"ÛIÌ#o, L(ÅAB‚N,{™'1"e‹ä”9Nʧ,*¥YFí¯" ’òŠUµ¨5Ü}Kª•b"œå*ÍA)XÒàvð0½ÿÙ5¥)ë’†c8Ó°_ˆ $qIè#ü–^Üé0ÆØ/J÷"]R¿84!\Kt@‰6‰PÄã>‘wF°rOq*;N§[bþ¶eìÀÅV>šž¯„[žSÍ‚Ðíù>S½=Ýç8´~‡SrûÀïÅWXðLuÎ=VÅ’å¶ãmÞ8o[âqhè2;®q¸/÷÷4o6 F+µ‚–îl\Úåœ[èölCµX>©ŽN¹<Í÷ t# Ue9©-6²ÂsZxäªòCÕÇù¯8ج0BQšî:îs²:ñ wâjXÓ9tçmÑ 9±妬M‚å¦üþPä,wq\NÍ: UÎ=FÄmVGú‹“6h08K'kBoÏb…>wÿz^³ú‰›~t""z—Š(Jp(ôæV…çM…†bd,rü\üúñè¿0< Ã}Ã:ÐY3ã*^·â_«ïË¢¢žˆóö°úÞàŠö¯çµç*þvöC5p´ 9¤Fp¡´AO£}9ÕÁñcàŸ ñ‚=âÀv¡P-ºUðL³~z¥Ô_ö º€ÃÈê1êv8ˆ€*b½Þ¼²×¢êÆ`Ö趎„µÖ™`ø´ÐìÀ&w.2áÝFÀÀ&!¶~S* MwØ„v¥!n` ¼kÓ˜p_SJ8F|ùKJfòk5‰„ŸÕ(ôb| E'w ƒÐ+AÖõÜãõ°¬ž^c]&½Fÿ¡:©Ê‡"áõ³ÎZm"»$¼Ëž[„öÅÐWOI$’õö¾Ò`cøgó¡L„SÆYst½¤Ž^CÈ pg!žâëÿ „˜æ5BL2•6ACáq.Ã桦:`»ßƒ’9Fd¡9•µC”ªa̹,B0ç²øê£KV/‚²tk‚Í,'ÀÔ”R}å ¤¼O ñ\Wzì¼€…ù p:\¯ÿqO&#ºh5žq]Âʘµé`G•¬Z˜Œ¨ïYQU&^5ä*zR\•êÍ#ÜõÙ0ey©JaˆFK,ozð¢ >ƒNé¦{CóÉÌé>›Ëq'mÝŽp…®SãtJLC™ãGêÛN&³´E£"o‘#Æ[NL]¨å˨Z:% *‡†Ù[{0¹Ve™é¢ìè,P#xgÜ„u^ ¡úªX¢:GƒõÄÑ.¶aÕí`-VAVàòwqsµqxŸ•#»/΀@”4çû}9\;®t_òŸEëÕü†ø¦x˜õ]­2®;I”luž\ìát„\œ<úpï‡Ã_tá+$T—4U=“{)ˆüZY…í¹îg”£HW1«³Ø­Ëê>vÁ²Ý¥œKá Âw(À[ ⣠¿1ú°bÜÛµ¤«,|Ù…\æt 9é–)É·Iô“\¤“õvW|$û†]³ÌeWUUºŸÃwȃÅIÀ¼ÖS®tÒÎ}Ã3FÙ‹²éÛ*¾Y.ûÁœRƒLž(FCá(:ÐygOéG+âðóà'Žî¼Ï‰~+c?諲aÂu4‡J€b/­ÀHq˜¥–¬ÈÅðNæëa½Jèh¼2ÍÈe–Zqˆ FŠCR—gBve-Í?Ø‘w¨‘@k~8,žOžvåÊÑXX#ÁÙ¢÷\àN‚?5à?úþAoC8g’)ÇÎZÃg׋Ò]®Ÿyž®}³ènQ'â<á+p„ëËñž×Öaž«Ê³†—œÝ¬^‘®¶¬#Fl<AJáºæ“—£¹*ìÚy¿IQ󦿒…WXÛÔø6‚‘BØh&E† ¥ 'ç†9/¢Y%ÁUpánl~—×Ré4 –ΗyBJEÖŠmL ׉¤¤gæì°âÓ€9T@½@DÆðÍ,¼´VÅDX EA)¦UÄôµûÉ ¼PÅ ı$yÛÐòÍ/è/³ :Í}ší•…Tx1Ÿs£J¡Ó_§7±¶®$L<®ð¦ª¢þ¸ž4`¾ä®°è‰o@`í0W`_ï"sÁT©˜cW<çU'^ÓGUÑÙgÖseÖ‡9h®ÙÏŠ¤šO⡳Ö5ƒUZ/œºÆ³¤˜êç¨ò£Ê•£À¿üШT¥ÝcÛ¸|$QÚr„È­JØb0DV’Vëô³ û¾¨]¼&©&È7­§Í*™R…’™ ½¹j­ØI¥$±ëÊP#h¥*7W·ä%oå†ËCÌ/²G¡Õ`WµÏò=_¯ÎÒœÿú°R¨k¶3ìíÚú,`•Ä1.Î †ÆÍÃk ãðAà¨ækþÑðýApö4ß= Ë¡wÕÊÎß¡Å»ŒN0»@\”s+Y—Ÿ4Û:9kñ¾÷ñžqcS¨^;šaø¬DÞ󜧯¯¹$бÏÄr>!1ªïoRèÝu°±ŠÛ÷`!l컫ªZRag-WdÖÝ$!‰×’/T7¯üEHØw†±œD‡ÖéëŽ ÇÊë‹/ú¿,UUͪêËfUõm=ˆwèDÀ·>ãõ±yI ô£ê³ôaØ/XÑTçÿÃlP…üÖÉwÕVUµDIʾSJVp£SG^X?_aÅ¢û[]éʨô#¢üÃ}XÏó^Bß¡ۻ»aæfÖ¯Y·UÄÕ‹ÅçbJçb©©Ù7Ï`šž¡”–^TºTo ò{÷û»Ãó|Þp%¶£ê² :i~‚)÷ŸÁ+ç÷ãDh~þ½nZãrFƒγ‡v~PÑ°TßEώ½¬á €E™›†dÍ<‘yÿc„çsÎûçe.n²W¢½UiÂaì‡ú ag8é²N@‹¼^;"¼Õ\ùפ²\Zj)©É@¯y¾ŽõõÏÿàÛŸX‰¶Ö´Ž?ÈŸrÑÙ˜PJ¸S³&ùóýÇ÷m‘…nY–ùYj¾ÿö{»¿K=Îß×û{ûø½Çûûº¿?<~›TWt_a ½Xç%ããEH–ï·÷÷v×i–¿¯÷÷öñ;ÊÖ~¿è÷£BÀ|›$¿6 (T›H/’+o÷E D¾ß6ü;|¦þ½ØQÊ 5]Õ®U6Ûx_Üï‹=?J d~?»RyZ|D¦ì}ñÏOr–üNðâ?€~´¼ùù|{¾oë>ÂߟÁÛý£¥’ßx–PÝßI«–/nB*ÊYðª÷{[òÛðÃÔÐÛ5ë¨5lå¢óR­êŒ|¿¦JÍ´<¦ßfÅ}ƒ-y·äÞ7tÛîû¶ÿk¨û/-swÀ‰ÍäÛóƒ¾o? }'­,Ñ`F0Ï_·êºÑù5Wœ†G©V•œf¹*Ž#”s¼ôÆ“ùÇï×ü6l½é·Aw}ƒW»â²²šÇKÓÎý©’Ñ Ù}›šÅ¨‹ì·êZÑù5¿ b÷Û ]ëzÞâZõ A ~ áœÅßI?…ÀcÖ¯f…èxéž=%Ü«ß.þl˜üÒ]»š´Ü7¨Wá°h~y}Ð-[mª·÷´ûÑ™®–øe¯köÂo#û¤ømПŠÌ q«®ž_ÓÛÈ°×U¦="Ô»U=×mÌë¥K¾~"¾/­7* ”êÆŒ˜ñÒ‰ÏæÅΚýì…[E»ºUÐÞ ða»þWßV5Âߟbà{ê)øx§ªw+|ÏòÒæaV¢2óÛ´ˆÞ>©U†ñ‹Z%-™Gï‚k…ëË.xž½ÐÛÃìÿ¾´ú©µ\ë’Q•´M›»2xÖ—].>{ä/®à/€ž¯Âviöç­e~{Ä·ìÅ=¸ßIk'18,ŸScY:¡éÇ¿@áÙxzfs½=Òèžú¼0 n6†·JÝ‹îþPŒ”dîŸæì·§à'ªí[t`®1p,°û±ÛKÏì!¼P¶¾“ÖK€,: BÁ¦%ÍjÁöÞ^¨ÕA8Z%­=BˆÑã[Wá TaTÓ’ò…žÀá^´¬"õöT_ 7©ê ¢õôRùÆZ¡ç*ÖKÿ^ß ®s&Æ¥U!_hS¾«ïKë ,!¨Åb¿Šˆ˜¦5ÓtýyJÓ?÷µ?ñT]‚G}_Úß{²Jƒ;Ýþ1Ѫ«Þ+Ó½Aîë./=sD¼d½S·4­7*/b×µfMQÓU_^ïçWzãÞ^û ŽQ|_Zo\î w²(Lû&ç¸ù£îç8{­/Ð~©úiÉ V¯«‘ýÈñ©kÙ˜ö\Ò*ò\}„óÒŠ³ ¥Ç¼ï¤‡Þ í¤3•`żuá¹pèÆp˜Æ}•œ»cà™<{_- ó°Ú™ÎWZLŠŠ–5GŠë÷¹wÞOÏ… â ا­ë ôJê4‚Ï&”AoÚ·<ð¾tíwî d4G¾†ý‹˜ß—Öxl©gÝñ)ŒT'ªè©þAÖ(CÍcļãQK,v]õ=¾Voá3Ü“%¿|×»iÝC‡•­jõÕÜ1è ØñH9úö ÝýC%#…åMK—Bx/¡j,êÙ=ߤ›{ôdqÐwþÚ£bÜßI‹_i÷÷Xøy´*ªÌëçwÖj|G /Àsà¾À{껞‚ïÇ´ŒL b4[/÷_xPXE…Lk7=¼Oû ³%dwéñmz¸çAŸ‰Zb±Tq»hßJ-È9žýAçž&èówÒædúÈe“Â3Jî05v©àÑr_ß"Ú{”±ÓÇÏÏ„M£ž?=ï«èBT^]¿ò/þÿr+ ›L`wãpXgÓY¬¢½c±Ç•$˜ãÜtöƒåÓCý -ÀnEçѱª."ÚIµ›7¡l÷ŽUÚK/ûCÒbfÅwÒ‚C3tí:h¼f¹¾iáOà ™ò•1'ÃãE wBoŽ<›ïhôeì3äV|›6p•õ —ûŠ8¤îp5-pp a×f¬Û7ÖˆÖ¼ ØÕ\h”ýƒÎ^꽕9Ïø˜ . CÑDû¾Àýåx`žU˜&Z\(w±mÿyœ¾Uæ·§°“1Axª¾ ›õ8„ôía¿:±{³Â¥`R¢…±c-WWl×81¾cÖ—OÀæÄ—Y©U0!dVdEÑ|óZ{¥ªñòϪۺI‡ÐŒ.Ê_ WŽò½5â_~sÒ—uÎzi!¼¶ªwêËðJ«D´iA” ylÑÿ6¶~oßùõ)zÊqè~«ðV5Hsñ‚í&ÑY Œ0‰)zfùeÓYËkç%§P_wÌú2oi¾Ó±~ß2é_/ía^ P«•¬ðÅÔŸ!šE …»àÈä½£Ô—kÖT~™´ë°±6d“¬Šï'!­Ä‹J";ž¬„jZ É5oÂÒŸÆIzþÅSD>„úDZ`<¸Sämî5\|´À“U5²ÖÞÈ;aD—íw÷­ÓãñÏ:¹7Ê õ¢FÞ6ôóã_üKˤ°¤ÕWÞsäÚoˆlqbZ²’·Î»Fæjo}!Ñ^]ÞCäÕÍyQ/x—ê£þ±j§GŠ}ið¶i}9îCuÅÅ™˜vµD ×"o¢yò¦ w.ôeìQÀÌ¿“ÖžCȳV¹{X/ôyi×BDJuÊêâ­’®HÚk[EÒ»åú Ý „l*@_pá³Ê“¯ÂY¬ µ?håÒcç X÷óã_x›u¡$CM+`°Ç­ʨ›°M¦]çñ¹÷ù½ó¢/€§6ü¾´ú¾wòoýsõEÑ’§¼µHUy+®x©ºG]´@‡¼@±ºæBrö΋zщ¾R/XGKlÞ1¨Èži_4x¿²ÆÌû 56Óz2 ¹fç¸Éž¦]+tð^DÆ3¡5FèÕ#¦úª"¤66\¯êz¦]9;@1³ÊrôÍkNZR–qÓ6Ë_¿Ýºc¿=¸ò­¿/­ÑaoZ;y¸v¨iõÕy%—g½qTÓ¨CI}o H.‹~üîÊTÜwŽÔ;ÖW[êö’® `×jl±è¬÷ÊÈ®¥éýÞjÂ7í™VKØY®NÂôæîj®¢5ßñÜjÞ£ýAË—Wkûʄ롽£ :]P´f(®šõn±ßœF(Ú•tXŠÒugïPq Ñ_ó^6§z¾ö½c¬o¨w¤¥å2}ÜPr\Gà;ãMû†@ì=WgDŽ¸/i×â=™âÍ„«ç¬¨Ln{!ZóÒyg³ZÂ>Ô”¦%¹ï?•äºÓHCÓ®`Äè¿ÎîÁº~’è¦ kÒð×yùå/H^‡‡ùûÒê+8tzÔ€˜ùÒ’Lîw \ÞŸ6Í ¤‹ßeò½ÞíÍ´úÚyÓ±Ú̹Sï¦^êhõ<éäZ–$pŽ„iõ7À9é–¥ ¦4jÑyzaoåû¯oÕ{®®ÁeZ-UÖlTK9wz _ø÷¥ÅcÄx6xËwÖ†Y¡ªô‚«N—{“®hçŠðVðiŽ!œ\gƒiõŽˆssRÎ*‡sùNú­ä䂬õä—¦]Äè½¹úçÇ¿¾U_ª:Ðô#ºg…LÖ±2Ž6é"še"<þÈ›„ª¾ZE=B|õÜ]ƒ‰0\1Œ÷»¬kpºrÒ|² …iÉ ÞdïÔ 8ƒ\è"iõš¹ëƒwÐÍÚâ¤ÕkHƒ[Ësª^c7 íà[UŒébºšE¸H»ZK~TŸP÷_xûáÖ£#íT= z°UÝ®zFڕ ûnWmã<ºòSΩ¾†½ìŽïKë à“¶gƒIž Ñ.=żµŠÝà´~Ó3vÆÎê}è‘+c‘vµ<â®]§ŒsçÂ_9êéÃû¬ÕSa‘® `Ëšð¤]H¶’k’ÿÂÛ,Û"é#Zç20ÙÍip*çâ¢b¢ÕoØÅÛÜ[›¤]f«å}ðïü²È›á]Ýß—f¿YÛXq“ª"4®Å/º‰¾ÅfÚjNaí{e÷-BËޛS›Eë´R1VšS× ËùUOÇ/ÄÇ°B¥ñ~•Ø¹âj’ÄÑI&áò‰–±˜÷_ߪciaÒê7î¬x\‹åÃ|ï­iõ›È>I÷Æ;ÏuÖ™Ö\ É5ãïüªÀü•¦1ˆV¿QÒÉÉž*#äÛ D«¼]O3Óˆw”…#ÚÕ:YvHœ÷¶«›–lW9"_ÓÇ9•ÖsçW=ªâGߪIêL…ê¢Hí¥=¸_#ãDï¿ð6ª¯ ‡•´ú]Y:I³ ¥*¢%­~ãiΞԕlM«ßíV{~çW½à] ¡1ˆV¿Y—Z²Ê… ö­žb*~VQ;«ÙÞ­ÓÐ…£Ô&ïq½UÖ–Öiè‚Rj“s*ùç—=­¼Í\z²i¶ŠÀL‹¼&½v•[Ò¾Mc1§¤fKþ×·jÕº¶¶iÙSHká¹@¶ºF¾ŠeùªFìIe^%­~cOFÞÝáùÕ—Q~¬>«†»j/öjÕ,™ÖË}-ÑèµfÉ´z=™?·E£×âBÓêõ¼•ÅY±§©|NÒUsTî 1w®Õk kS¯‘v§[Å}ÆÍuœMë ,^æ:ÅÅÎÆ­/´…Ï~~üë[•Š[õM)¢5¥ ê ùBëƒÖP^Ï7ŸÜ¹ÖÀ‡ué à=Åö*lÕu—Eë ¸È%AÖl®cmZ_`!7ß ,ü6?hõºÞ{zxGg«¾;¸ê$ÕüJo»sÍ^#°Ë|©oU‘n.p–h¾5À´zÄêöž—‡%íÆ­#›o%Ç.wq–®STôçÇ¿¾U›º5ßWÚe0éM¥$=¿¾ä7çZc˜E·a €u6I@™:x1­‚àIß„–uI¿¤U¸`EVî'„¹¹®¬é*csìxW.g?ÑüúÆ œkõÙ‹z .TÌ’WûŽ¤õÜ‘Ô\’\h¯‰iõšÅ]Fb`.û!Z½V­ÚÄî÷Ý@ØŒ­OòÛœ’nñïRèzŠtsé Œ­Õ|ÊÿÂSàÖî9#íºÍJß`ÉHê·º60„b6iˆe%]lƒ·8¸h„hµÙÐ;ñçyõÝ·Æð°@¥¾€B…=K·ðþ—zA<¤]|Û³TF3ã¥³Ô ï›P›Ìft-wÞëeî„\è.#Ú¥FП,AâyçpÄ·!Ë€¥1ÛŽD—êLZ%XòSsÄÜŒ‘Å|H«ØoÕÈ9ºÿúVyŒæ{pŒ6—]ÁñÚFÞŸÅ¢ŸútÏ,Ç¢¹ît~Ü=¦Æ@Ú%.ÏáĨ md Þ⛫IðFµ~ËW4±‚ŠÓ\Õ×´‹=Y攥2ÚÈRèƒ Ph~ûm›ì‚ËÑkh[SRˆ›æ2¦õ…Ê¢­*Æ€œrWáf $Ý…R_Úe”À;; Å/šK'˜¾õ1ÚHýïþ‹sŠqºÄ¤Š+ãßyÇÿôãùÛ[ÿú£|ýãùßÿñ|ýª¿2€õõí,Õ`å0ÝÖÁâbª‚I²Ïû€Ñ7/8I,SyÕ±3 ö} Þ׈ŒÊÔ„ÈOð]ò5w‡7M(-!û‹178Ä.¨È(톀I=B2Œd`RЙ$RyDÌßPZ|´œ€Â{ÞÔd’*'²Ý×ÖÛHå$…®YW ]èd ¨´1ÐÌÙ7Ã\Víä×:«Æ1_‹ç„¸î¼.¬&E}Š¥Œí3'Ÿ×¥©FqÏN°„¾þZy55©ê5ú©Â°š3‘Û9¯9xâ—²¸ìÊy'"*Iø°ô@ã%¢[ämŒ¤¯/9P–\s62ï•+±Ž²çŒ)³nÿø‹ä© B Lîd1^uà|l°«—T– p=ÛÝ“u™)ê^0ß_dŸ÷]™F’…â<…ƒpN!I{Ýs1vr•j•>Îåî—„kALEÙIÖÛIM!ðuϘXMá`‚ò¹ë»%”ô­¾é.M§y?÷#óý4\_îÐÛMÿôÀâ$[ämŒ¤úÆ|»ºJ ²±Q²oÎ2–€ƒ¯F})s…WfÑÇð§™3f[Õ]’ìã>0žûÚx#Ž$î.LÃ[ÑýµìŠ5fß kXêd`ß$zã~Z8I? ½Ö#!iÃkß‘ ü——u””6´ý“¬w$¼Ä¯µÛÉ÷¾Ù| ï-ɾ!@›ˆ~”üÈ\·å™"G¤½39_K«gËŒt%YRÑÁè×xÛ‡Ð5å¿pYú’òŸåL¸¿FÔ\ Ö½ k¤ì&y‡JD!]øݨ`}»@Õâ@˜“Lÿ6>fÝ× /µ¹¤æž$6&7s‡v«—|¹“ÝÙ/li¾h&˜Õ ßþŒ„þÅSû% ãm·;7(’g™• ï1µÂ˜Úh/ÏÒ:_´ÊŠJêzr–E.§+u÷™9Tb>¦‘…³“ZŠ\Þm¦AµÊ{rö%ëû€“¿Z ×Vï¹Éž%ùôûÀs_Cþ’#éO<ï‡ya“Êâv’Wb·ûa¨¿ÃìïàÛ¼SR“ÛîœQ´Ê–A§†B.,ÔwW¡9¿-U\8ÚÓr6eÞºÄ ýÆ•¢ X2aöH¹4ýù«+” þØÌV”aŒ–ã~MÙ¿è+4ô¯e4k¸‡8Š+¬ "tÐ/ê5)WÞ¨~oøËü Ÿ;š±€O÷_aì¯Ô¾Ý )kªù5¼áðš’Ç-o[+LŸ- åïêV,¿¢øžƒ–¤jŠv§O…¼¿¬pªB$}74x²Tʉ¶lÌ5àÁ4&Q¯ÖÄÍà¦òÕõ"w>P|Uwɳ1U;U¿·gì¯2ãßNj©8:­UŸ¹*ƒÞïèDºàzÍj©|Í_ïè4æÇ+à°,·ÈêÌÆDº àý0_sw4ï+?Qœ„I0Ý­°HùÕã{þ~ÉÁæïPÂeOòZµîúø¼!y^²µû€ï5$H£¸'Y ýý8e[w¾ûZåÍviCæ'ô€ïÊë·;ll·û w¾è²‘  BæO?oÖáTf4«s™iQhFü€5*¹RÅð÷µò%•jAKK|sš_6x+]A,à°(˜;€Z=þêh·/ƒÙœ$ý¬^DÝÇšï¹9¦ñWRª¦*èˆé”ðúå|ðÇÄéÝ~Û`Gù¼ï—?/¨Þ0…©»g–5`„Ü\í 7¨îü«ª<Œ,g+ʺg5–½ó_a£[rΩ "yŠ ‡¨*#fåNâ®%™¨Gf™*ùWTöQÁ ÂZúj§Üù'é*T#{Â[%ÓΗZó,ñ«÷Óù”~•Ï‚Ölâ0ru„£6©{8ÌLVö_ÇÖlrDÇJJ•§èœù†+@WlÙ²(|-kõ;›P<Ý\¥¿Ïœ6@ñLµm^[þæ‹QPêÑﮯqíM_M‚ktKRê+­Ñû5÷p”¤€K¹_˾¶1ÜWØuëÚrê!”pS‘3Пú ÛÕwÙ–œ9üÕUÀ"gŽª|Ë–Mõœ9ôàöæ(kD02Å—€J,ƒ]Õ% >«7ˆA«‡i¦pY¯ÚÞ=ûº³=PîëöšÉ˜^ÙŠzÈèöýZ½}ɾk!N$ꢽ¿jË7á>îì`^¦Jþ°1T¶D™ÖH+?yyNCS—‡äòíº—‡€¿~w›‡Ðžë«a&JRš âºî×4~"´Z¶\ï×r&€µóöž‘â•&¼ ¼ñW_ÕQ^ñÊß5…„âyèóN,nu¹µž¨¤±’Ò@ðWuo¸\.Šn µSä GØw{eD­€÷¯þÚNáŒV4åëZÝWP9Ðb †òî\<àgLÍ”›k¦Ü$(Þç½h]FfýíWR*–u«ÜGÍôI%ORK‡!A7³ Þ±üâÌ¿Ò–å¼4³©¤T¶üùe¾½t6é²›IÁÄVÁ|O7•À.¯NUB"ãÊÞP·ë7ù2[>ýªI±_üë¾o0ÅPõ¤V¶¼ï×ð†úò“m7•€@áÓ²Nú»)‰,ªÖÜA¦9:ÍRMŠmërµû†kRly߯áæ$¬Tc*& Â_’*=oqÐoëøõ§ÌÓ¯n(3Úeê×n´EŸù+3ñœej'¥ÎçYÔÖ/úç#鯩¼'«<+Ëk³cƒB}éèùHòï^Þi¨T6Ó.ûÇgTäLïÖú¶éš~ý’ìÀG·xlmŽÎ@¤|“ÓT|toÊ~{É°_Òãí1Ãdî1Ciî±è¾ÞgÔc½««ÍXï·D«zF}sÀœurØ ô´Û 6Ù‹ø˜·ø˜7=Ó¢ïئ¿ NÒPeü `ù.ªêd›¢]®’ϸ|×}c›š¹ÛŽ*uŽ†p¿R¨ÙÁ*ù…úñåöÑ£þÑÓñŽ€Ð£¤×;b‚ªü.ÁSnS´¿Åg܇õδÚtIÁQ>FC`œG#:~ùËÐ_>ÆÖ>ÆÜÞ¶xÍÈÛ./ŠÕ#ý¶«‰o¯È¶z}ûˆÓêÒåý^ÿX­¶ß9­ùè«®w5jSóÚß‘º~¦ß9FO¡ ç6Æ£7PáÇBÿ«Èâ}Þo¿3+:g`|Ìù¨þËÔ_>æy|Ì3"à—f½z?Êö*o):[kÞï‰þõ/Z‹9߶p0ä7P=ðÒ-Þgjܵ@úP®…h—Tç3.ŠËw5kjS³©o™fü û–kÅ\‹¥Vù0÷ùÒ ³% ýßq"!g`½ãÁ_$1—³X¾G!Z³Érù¾}w×wwÈ™ÒæubÙC”‰rYµæÒ­¾ÏæâÛPEg«÷/hu|¼1?ZZ_Øï—yç®[­@© ›m½Ö¢ýÇcgÕúhu¾_«ãí°™÷ŽÍƒúÑ>iñžÏèÝZß6µnúV|ôÁÏ°ŸÉ3-ÇÿtŽSÿÒÞhóáýîwëïÚÇšð¦^Ž­ƒhAÏøvÞöŽAm&1Þ1¨~f}Ž÷—{ ¢s ú×´‹¬ÝþÁVË~#3òÒT¥ý `ryË.élŒä˜9:ÑÓt»€äÔlsù5¸|.]ÞÞ!e1gï~ëÒš==ã¢ø|×EúãöÔߊ>øö3goµwöH¯ýË_–ý5ïV¼cXåÃz>Æ°ß1 ûÎÑúÃ~Ç wÕ?µé»[ßõtüLûe ëc ¤}#ì~[ÝÏÛ*ò¢.]Ÿ÷iÏ^gýK­ŠN¸fз.¾±¦Ã«q¬ÑøwÉʳ駯ÊÉv×G»ÕV¢ý‹° ²“dQo'=£¿ôìï3´Ž–Z–«Lä÷`ô%ž\½ŠhEË+¼H :­g|]×;‡nÓÔÞ_úµ‰¯Ìw×󶹞÷[³¿}xm1·iàd»£ÿ©[ër41>g/Æ;¯Q>g¸v¯¤ÒD\&…i%:鈸ɞËzЈêþ ×ûŒ¬§'Ì·MÑYD¶@2• ´]5gѳ$o1¹É<Äd­K—÷d˜ç»=Þ6E*S® ¡„9sF{­¦§½stÎQÿèQÿèµ­”õÒ ÛwjâÞöùÎQ__{µ}&´æ3#ÞwG¼mŠÎ$Ö·ãs&öxghw÷±œŽf|Œf|Œf|Œf|Œf|Œf|Œf|Œf|Œf~Œf~Œf~Œf~Œf~Œf~Œf|Œfü2hý9”YÈ7àÙ¿-õù~¡Ï÷Ë#Þ½Ú\ý°y˜Oœô*ï3+ÞwW¼mŠÎ"#oðîíÛžw4·ÿ‚k¥~Éb4_½˜¿ÿî|,y”s±ãýÞ.o?d#¨¢]š§¼ãÙ¯^eËdɧú£wÖÂõûühs~|k~ôa|ô­½sqû/0öÿØ[endstream endobj 6 0 obj 20943 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 9 0 obj <> endobj 10 0 obj <> endobj 8 0 obj <>/Length 3336>>stream xœ•ÙÇ‹U[ðnsÎ9çœsFQ"Š8q uæÿàD"8pà@ˆˆˆ¢¢‚Ì9眳Ïøýú.èϾ¶ïµgp8÷œÚU«VÕ®]{ßÒ#GŽüøñ£C‡gÎœiß¾ý³gϾÿÞ¹sç§OŸ–””Ü¿¿Aƒïß¿÷îÝëׯ›4iòñãÇ­[·=zÔ׎;Þ»w¯¤â5f̘.]ºPâÓرc?|øпÿæÍ›wëÖªjÕªµiÓ†Ø?…«S§N'NœpôèÑСCÕSºgÏžOŸ>}ýúµqãƆU¯^½fÍšŸ?þùó'¥>ݺu«aÆ@:tèöíÛ;vìð|íÚµåË—SzðàÁ"d ,åÛ·o«W¯ž?>…äûöíK?ÏÝï޽땺uëò¶uëÖ.\¨]»v=* Û¹s'bZ¶lI¨^½z^½zU¿~}wàtóæM@ëÔ©sìرÇïÛ·¯V­Z_¾|™1cÆîÝ»©`€yéç’%KºwïþòåËõë×Ïš5kÚ´i†>|xÍÂÕ¬Y³ÒÒRʽlÚ´é›7ox_ŒlåÊ•T?þ\Â0ü¸xñ"òs"+F‹-òçW®\ñ¦U«V‰xѵtéR$ñsÓ¦Mž‡ ó#FŒÜÔ¨QƒZ2yC?Þ 8°²U«V%jàs¥mÛ¶H‚‡º£sÛ¶mêÙ³'Â0á%Iž”«`Œ?쉠Ÿ\½sçŽx­]»vÙ²e“&Mò•wh$tœoÔ¨Ǥ£O¬KM«€lÆ ׯ_{8˜è•õÌ‹“#GŽDçÞ½{aå_ÇûJ»u'3wî\ÚµkÇöùóçñ4xð`j½iÑ¢…±$MÓˆ9Óƒ¯lÉA¨€lÍš5™Gø$ÄcŸ —Ä$%íP>yò„£çÎsÇܯ'NœÈ¶ »páBò8£Ç¼Æ' å–Ùã^“Ó ‚(×(\„F¾²aÆk® 6c<ðÖ`å#3gÎôÞT.ÃOR8d$Ü"‚ Éô®]»/^lBŒ=Úð'IŒ%@žW0½}û–_¼x‘àsÖ¯_?uC¿çr®Ù³g㟯—/_)’4ʘ+VPg†JAHŠŽ¸@,—k„ ‚`bä(Ɔð+…–ÞHÁ ÈþÈEi¯^½¦©Œõ*\"+ô°ÊH nÞ‰¸œÄ%aE‹aw%”W7nÜ  %æ–;É3°wïÞ"'ñZ%dS§N•‚b˜Ÿj4wÅ‘1‘åâþýû§OŸ.GUQ%+Ìœ={VxSDn· yÞchìz)šòµ“”ÅÈÆO©|WKóvÞ¼yÖæ¹E»p£ É$—•Di‹0XM‹‚Çûi> *e’Š&’|>}ß*²yh` ìJ5þÈø ÈTN©Š–NÉ'z±M Ú<ôéÓÇWÍíú…Ë<¼§ÅÂÀá5eOŒ5Êd$fé”IƲ! 9 «P€(+Ì L‹²Q™çqÅHô"C9½zõê¸qãL"< “¯™ù´ vïá)ÔŠ>Àr—ÐfÞ{@Ð@9^é ÜÀRÁ{Î HñÜܼy3(F2À6LJ3ò3}@/e1<øD/|>'”8fRºÄˆd1³’NqŸ¼Ç:Ú|•‚0`·2« r´#Ãx¹É6W¸%"r¯€«Äü”ÈpÀDž=pK ­bðM’·±7XA’ôò&žgi7£­ES°tûöí&s¬Òˆ•ãdz$p ã£ÜK™YÌÈ_abXÔ²ìŠ ²ùf~CƒiŠ-®r£`Ñ“÷èÀ"ÒtH12Ñ4Rh8mn80eÊ°ÐÆuââNµØ™Œ%é«@£ÄÜcP.á\Ï¢q–0Ð3ç9†0ÈRuÁùbd[¶l1@cƒdá`ÏT0`¿ÕÚy³R víÚ5~ëÀ† ¤>ɪ®fÍ?‰¥•2Ç’ &ÎcÐt¬˜–¯Ee¶ ÙºuëÒÁÄ!˜è2,½] Ÿø*¬§wšS§NeÕ‚€“ÊO„‰¼ÌRF•<ƒÏƒQ≮iMbdú»Nij•·x¯´\$Yºø†?Ë]’,°êAh0V§%šò£(áIª— €ŽHÚhNgÁ+©BmÉoWéÆÂø´Šj/é?}R/ðWÎ1™íLÊíÞÙ±Ò@ÑÆàË*„oC`â ò¨•Öò’«R·peÏRŒLWmÒrÃ~³ÄƒZ… ²žá c^8²?JÆ'Û»téÚ`rOÝ. ¬»gã¥pÓýB¬8ãò÷ô/Cf½#ÊpI¡I”õˆ¡4å Ÿ.µ>UÛRÁòt?YªV¸àV,ÄK ÃéÅ™€‰Zd{V <ЩXz Y 2Kž  w¯€†mñÊ>‡ÆôpÝC2‰0&ÐÉXÂj ÛxÂ4žèÌ*î%Üõ“3àšÂˆP>çÌ™S 2uφ%3äׇŒ˜àP5Ì\Ïdt&(d {PâI”³¤ú}¶!^~à“æŒoŠNl)¼F!ÉÚeªÒV±™2&(éRèå(uaZ(Å ½RÍ]A–[ŒÉžÀ‘=³Q¡3mÄq Ø°úi(+*í+AÆéÌD¨‹1ø”&;.2É^ê‹Z#µ=s E$»ÀT윇 =@¦×p7 VR%dÒ“íòŽ>?)¢½xö[r.­ïE™?Á«y†ƒà˜ç ¾³×M îSa•!3¸¼}KíÈù>K‚›ŠŸâ™R4¸—‚›#ôˆ> ÒðågΡr‘c˜ª"{f8ÿ$dý,\8HÃÓ”læHŠ‹X9Ò=§¯bÇ0XR¢üT¶œ¢á/}”-LU‘e³ KÜ­ =-TÓ+ Ù¡ä/Vӵ柇l@Lغˆ¡';rîVrƒÎŒ3¦Š°Ê匬ä2“m9vSÄMC´I¸~ýú‰™TcéÑ,‰éÑsL.îÙf£­è°ó¿‘åo¶œK#È,ØåBÙÚ§¦Dž³ŸK-…Æiçž•ìLýÌ¿G”ÿ²¬èê‚°r+û³hÉR“æB…”%æiŠ7Ò‰è—4&$¹„­ì+ùž,GëIÖ¿‚U†L³š5„®’Âát ºEEK2e[–¦Ò&@œÈµhæÄ*§é|ÒB¢–Ï–Ý!C†ü52rP“í!“9$ËuÖM±Ô,%¬J1èY¤Ét¹‘ÿI¡É44g?ª²Ì¬Œ§=Nó^¥P™®JebáÇ¥\LÑÊ!·Qé¼³ÿæIÈ6ß‹`«xýǯ@ endstream endobj 11 0 obj <>stream 2013-08-20T08:42:03-07:00 2013-08-20T08:42:03-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 12 0000000000 65535 f 0000021263 00000 n 0000026399 00000 n 0000021204 00000 n 0000021049 00000 n 0000000015 00000 n 0000021028 00000 n 0000021328 00000 n 0000021428 00000 n 0000021369 00000 n 0000021398 00000 n 0000024962 00000 n trailer << /Size 12 /Root 1 0 R /Info 2 0 R /ID [<06782583E7D4045D7C8DF36BB0A4E66B><06782583E7D4045D7C8DF36BB0A4E66B>] >> startxref 26569 %%EOF ast-8.3.0/sun211_figures/fsalign.pdf0000664000175000017500000014432513004147321014133 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœì½ËÏ÷[VHL‹G Œ Ýêb:òž}¿$@l iñ’@“ˆ ±y½”Ís¬€Ò˜€ÁÑ‘êÀv"#b:U¦ªšø'tR•Pƒ’Ä ƒJ¡p„êýù|ÖÚ{ÿž÷hb3prN¥ò>ŸýÛß}Y{­}Y{íµ~ä9¼‰Ïÿ³ß¾ÿôÞÿÒŸÿÂ_~ oj+¥æç¿ðTÓ,ob}Nc¦7µ>¿¿SrŒ ÿÖ뛼pšáͬÏeÌú¦üö)öÈ¿<åå)–ïobŽ,ÝËtìµ®2,¥ñ&–2,¥´±þ‰Ï^æúÕ{¥ß>y»,áåÉn Þ//ϱ×øöéÏÿO‘$I“ßÍÒñáû;%ÇÖño 5’¹‘$³[ŽWwZ­w$·;OLuˆ$*ӱ׺ʰ”®Ê^vBEm«Å»ÈZD!¯Ô0hb ³”Eoº¥x×¼LÇV)‰2ž|æ­ÿÿoOáùþˆ@úäÓ÷ÝUR[…Iî{ÿ¤äHŒتVºÄfL¶ÚñÛ§>ÙCOXZb„Ê=¥$5féØ*]³”< S^NJË,ÝËÌ¥Q>¬R‡oŸ¼]ž²Š°–{Š÷Ì‹ÜØ*Ý"UR ÑZÕÞ?)y ¤2ÉMEDÑÐ9^D)ÿ´SUòú£ÌóMF•¹qô±ò”ÍEKyY‚õðI__@ƽȭÒEaO ¥KŒ<¥Î¬2Td˯½NÇk–²vyÊš¦¬åžâ=ó"wO­Ò-F±fŽbK…Þ?)«N.¬¥ˆ‡J±…7ÛTRln¥‰C,eõhÕÊ>ZJ+†­Ì­Ö·O;%†¡ñö”:§fÇ\E†A®g¯Õ1|Ÿ†”‚@m÷ï›—¹ûjµŠ,‘ä$£Å*áM 1-)þ‹O£¯¼iÉ|iѧ·ú&Å)ørÁÞWæÛ›ôÜGÆŸùMöwKoz‚d­uψ֒9VGÇâ÷•gáô¦•ç]æœñíN)m}[‹ø··oµ¶óK"v®|køðÙý‘Æ›õ7x³¿‰iÚOk¿EPv¬²BÆ­ Ð•}-Ìkq^)u­Ð«=Ȉ¡½ú‚k6Fëã›:‘}³†R^ÿ,¡šk‹'êY…¿ÿ4ÖNa¡— e ËX¼X Y[¤ÕŠГ¼˜ Ùßkç:'dPwqÊXíj«c«ˆ™Å1eõ˪ˆuý †Ù d¹6ˆ¹Çw¡²¯”Õ` ×òóÌÁ8¦Úß­½é(—üÐYÑ:4$|S­S)¿YÿÎE Ά׷ä§yå¨jº[ú3¶©üy âr´ZÃ<2WƒJî1kÀZÛpe_Û^I¢eèéMÝcÇØo˜V{1–;A+î\¼aC]Pz3NFó¿rt,ÇšI*s`-_ÍÛ<°º“:§Ì·¡!ôèõûHé˜VJ{30‡¬”5õu¥¤ö¼p}3 âµ£h¿ÅšWOŽ'&-bL™×ˆØ’*‹b·5¢1¬AhÖ§´`Z17^½ž¶ÿ±”9Òš²È¯¼Ø€¬wRÖN%¯a«Q¤Kàg®­Ã,£k0çNYx¾i§„ƒãbɤ/<¥cZYx¼Q/É 7 9oÁÂ1Hk“·ºÇ ëð9è‚«>oV'kV$¤EdŠ'Çø"NWŽ%ìƒmX_Ž «ÁøÂSV§¹Qb- T\b«uÁEùEGœü#gÛö¦P>F^sw_Ù‘{M¹Ûß‹m*G‘hÍiÉÁ:¾'ðVá"µª‰kõÙ-[ò£ÉÃrà رP°áü`qù|¥TŒsæ˜X@NkòoU,aàZâ9ÐÒÆ ê †³sMòÙ¢„j5ÅL!ZcU)SCº&®E«U2°Vˆ66¶nµråÃ&×è‡E‰áâä–5Ú$3&U¥)Ç-å1¢á6ÿ¯ö¯}‰ÏÿÙü¿öm·ùá)‰Ìɯ‚¾UXL/{ðzö"°8ëǘګ¿}ú_­:;`Ç°JŠ_U#°ZÀ2‰RÄì¨/û‘¸¤o¯YRÁ8ãÄU/É$¹‹«ËZï…fíçP£cäÇ2{e(UËÇZ' Ĩ|ÕÛøâh5? ùkÃÑl7´–U 7]™vŠÑfífæ‡ÀC­µ)ðŽîù"Á&VÏÄ4bõú†x«€Xk°¦-þMÄœ6µ†…MŒ1µ^jÍ ß9R"&Q‘‹or Õ "°ŒQ/r-¦/Ô²Q'­U0¿ƒ¸àèâE­¤¡júpàt"²=ô!¡6Dôâ²oKÔÚ¦C4Îua9|Ä°0c‹()a”]ëk)Ê‘Aû5•«3ÓCÙŽÒžc5ÙÈÊéÃÅßkФ—gï¶Öï5‰¥ÎÍRƒÎor]Yû^Ò \ZAöÎÝ7ékŠ%œÍ8ÓåÕdòìäæÅ}ZÎ)ƒ.Å yí"’-k‘”É¡iŸÙôÕ…ŽÏp­I*Ü;Š54õäXÛÑ­Ž±ìiÒØ)‹] Ö\ß×|ÖŽ´ä¢Ì{uÉ‹EúI9d_ëjÌk 9ØryIðÀµeý­ÝD²>áh—Ïâ¾û´—ÿ´;ïkuÐ %|‹*<¾$¶•_ ®¢è5ölÀõL­Ä”öÅ"½ûJÉ~îø‘ç5¸ªø–õCÌâÙŒ‹‹ïøî§÷¾ûO>ÿ•ý±?÷ôÞ÷¯lOïýѵ)xzï;¾çÏñé½ïüøþÌÓ{ßõÞ'>ñ] ~Ï·~ë{üù[Ö/ŸøÔ˽ÿ—þòúäÛ¿ý黿óù›ÿÉú;êû—æÓŸþÜüÜWÿËÿýöçþîÇ¿öçâ—õ'¿ýã_ÿÓ¿ü«¿ñ“ÿú¿õoþíoüÕ¯ùë{ú#ßýü½*«uÖ.ØÈB•“G‘:b§”ÉU2Ï.åOÒ·Ž&õá·O9·ÌC¿¥¼<åT¿¸Ô«LÇVë*ÃSR¡‚àå¤Ä¬o¼Ì ]í®5¸îv·,¸ y·ÝRv̭֭߬¸ÊsªðBÝá"ËN©Å<¶Ô&XîÒd;Y¤2ôÅ4kþÍš·Êtlµ‚,–’]òSl³¾Ë\³&ËôZ ¯2¼e–²XÛýï›—é8»¦diÏ?þ]^ÑåC´W9¯Ý÷Ú¡Ö20™ežw“àËû \™×ž`ÁµuX.ø—ÃÁârê¯skR`¬»… ÂÎØíZ þ£뤔ί'ªïÀª²¡T«ú|m nªkÍÂÔ X°.E•ÔÔ?í&Ù³$Í£k]ÊX¯2Ú±6WÔbåìC©”—“RÖ¦‡J«ýÕ=ÖJYç´pRµ`À®ÓZ%°Ùš4Y;¥ P—µðj^TfU;Î;ú-¯]úÀß<Çä5!¡-«Ø*]ÖJ™8Ù¬”]Öâ*³V«+6 C›µ¸8I›uXE)¶ªä<¨²XÉ”+•I„/ÌζyÁ ˜-kÿÞѲ†î¬Ê×ÁÀÚeð<#ˆ©sòK¢Õ¼ ©Tj‘‰ Š±Š2N%d¢"®)PLöw¡ò£øI½ùhäÆGÕÁÚ7u• .¡jË`ä¿@U¡?À `ˆZ¢„ߢîŒÝÕ•£²-èøjÝÂTn‘%¨ÜÊ%Fô’õÅ9ÿRà"÷g S•á_€Õâ•#Sµð Cl¼¶-Ôp”\u1™ª3@aM$Ìn਱3dlJø}×X:c¤|©¸u•Œ¤Šk¥p»ºRºT\+…*.¦¬äÂ<Íbª¸¿ÅÉ&Ï& -IÅ% RÅep1àÚÅ3Pq©O ó ŠË1:­«¾“£@ƒ…+Þx‘K|¸SÂÀöna踀³è\¡ãÚ_4ª¸NŽFÖ)Áq¬Rq])ƒ”a†Ñ¢8¨¡UdW®.Xlh*ºÇ ëØóÓãMö1auríÆX]Hb¡SÅå_ÐîãÊ1©ÀZ8@Åu°Œ/<…w|ÑFWͳ©UTqUÈ)oÖ+t\˜Š»T\‹²Ðq!%Še3²w ºèmÕ@Â5y$«PÍUaIà¨JÙ{²ÉÄr ¨¹XJØx-iC¼¾R¨æbÊߤškPô5Í«¨qh±ñ‰j.LX먓a"!¦®®æBµš•¨æZUumT[аª¹Ø*Î+j.ÇÖ­V®üì¬M)W‘˜1âc5…±%k Žšk‰"ι¾0T\¿íuÁÑ^*/ôβPµFDÄÀ^÷² dËŠéå, VÏYRë šëÆ:D&É G(Z‰ÇÏ…©ær “‚ßœ„mmY+†hùª·ñÅÑj>6¸#$,#«*µn2yŠhÓŠÖ°×pS«a mí,0YɇXN,¢C,ƒ"VËTs‘XKiù2mG@Uɪ9i·%jµ¢…a£L[97µ*Õ\'G "&R#W 7¹ˆtåÊ2F=äjZ­‹Zž`Ô™˜6_#mVÛ¤šKEÁ`d¨š>l:aõ¦šË m“ZïZþmjj®k™Ú„ð6bXœ±ÎµL5)a”MTs1ö¾-Ž7å* PÍuUQ§½-GTsU˜…aúpñ÷4)à œ³r’šk%PßÂõyMï××ÍoLƒ½6[ë‡M”½PÍur”¬Ù{Qa‰^î™j® Sª¹2¬xé[”…©æâ.~M±Ä³ç—>¨æ"|LÚs¯Áeв ¸¡÷l‹_šku¡iöÅ•$Ý”ê…*¡‹–=íkG/ÚƒžÕ¥7ª¹N';X5Ž¢>¯E×Ô\‹,ÜtSN¶£°>eîv÷¿û´·°á›wŽZm†O>P%6í@©æZ)Ts±×Ø·×3µSÚ×ƳwÿB)娹Ö4+5×â¦AÙ_|ý®š«5ª¹æ…š«5Ssý£_ü½õ|Ã7웾áÛ~÷ßø¦ŸþwûÔÿôµÿXÿÇ_úßþ~å³ÿü/þÆ÷ú'¾ÿçþá×>ýû~û«|á«ÿê7ó ŸÿôÏþ̾î‡æÿЛ¯ûÁ¿÷÷¿üƒŸÿ}?ôOÃg~ÿ7þÀüä·ýÂg?øâW>øêWþÃ÷þÊ?ûí/ýÒ—?øá_úòÏ~æçÿþƒõ_|ùSó3Ÿù¹ÏãŸþ¡üÅ?[>û5Ï¿ëCµcW4ÁíÜ¢¾Rú­aAMeŒyg–½˜á·O ƒÕOÊËS‚þ3^ß$i·½Ì­ÖU†§Ô¤Û)˜„Q†—™³ÊðZ ¯2¼e–²¤ÐÛn)»oVæÆVëÑŽ…*+Ù.cÔ÷OÊÈ2až4Z~.3Êòv4*â¯æd]Ây º$rìo¢´-»LÇVë*ÃSZ°=ÏN©!Š´V&ød²Z ¯2¼e–²Êð¶[Ê¹±ÕJ²,±þñèòŠ.¢K˜ˆÖþ¤tš¦¼Î_ë¼Eørà AI8q¯ñZ~Àã 7̶j•vL°éZûÅaá&#áŽeM‚[›µ•Úµ4]l¼=õ6Þ/jÌ–ïÀReûÁÏ×N"­e[u­ÉÛ€Ú‚{¨ÒŽ¥Œë"ô/اFö¦[›„~F;Ö +¨€µkäP*åå¤ô%½A ²¯îêQJ‡-Ú*vM$`™S­‘v#W›»>&™çʺؠâÓšwž ض€c’~ƒNfàïBã`½ÚR°$Q;– \û·•’ KTà‹B;†¶"iÇ«(Å£Tp7Éîà ¬}£¾\0™r9Ai\?QO—°t-±³0°ý< Âè~êË¢m˜P ×^2QA1VQ[[%nYOŠ¸¦¬±Íý]¨üHÁNñÑ:.œŒªÅ©lBX¼7}J&d9èŽÙAèG0#kÆ׋j»st¶/ ½npÉI‹Öš/8Òº^L¸¸)Y¬¼¶u 2ßÚÆë œ¾)«žc o&qâà!íØI‘)É*a3@Lã avc­‡W†%–•ßO¥3F¬—v,µ¨äV£´c©¡©´žÒŽ­n‹˜²fŽ…;6AĘ;fÇoñ…í vðFåDá H;&JR;fP÷¾ 7dÍú´úP×Ü2æÆ ’ß“#ñµ (¬xãÕñáI Ø&¨ KÑ„óú,³Ž íØÉÓŠt•°q—vì¤D*äØË’ƒZU†B ‚†¦£{¬°Ž=?m¸öÜÙ¤„‚M8« I¬B"@)Ô6ƯC®ë\2˜#A;v°Ì/”Ҧݲ–uÌ*|a…Vñø´`ÁÁ.ñi~^“xÝpÀCÒ’ ÷,­QÐ ¬é¯ª„«_ äZ›Ä¹A‹Y-¶B “ÀÅ&Ëý" XJØx~Pƒx}¥ÐX9(ƒVħ€mMó*ZZl,˜³Äš°Ö iÉMy£6w׎¡ZÍJÔŽ­FM-_5iX¥ d«0¯Ô8Ŷnµrå¨Á&ÜèJ¨¦¼€«£-kÄdžJkɨ£Kf$¾0´Å[}¯ Žö²Ð’v3¾,¬ã»¤rå7°—½,Ù²€bz9Ë‚ÕsVOÐ*ÐHŽûï½´¦§RÜV $ßV°m+ªÄ£iW1¥ð1h’ÅÅàÜž)‰­ñtz 㪗d’쵞L´h’Hðº1òCçyePé +† ÿV_Á"ÍZëÑ·µŒ¬J§¨‹Lž"Ú` æ‡ÀM-4À×ÎÕ뮹XÄpbb ±0õ,b-AN ÉL"–ö8˜¸Ûµ0½Ì~ˆÑsÔʹ©EUI¹r”$ra"¹ø÷&—P!Xƨ‡\ØÙ?l5<Á¨30m¾FÚ¬ö5¼Å‹Z%õ júp°é„Õ›Ú1ƒ¶Mê¸aÌg‚~(ô{™Ú„ð6bXœ±Î‘ÂC”0ʮŤØò½/›r h0IwØÏk%l°Òæ"18}¸ø{ š•Ú…bíXÒ¡r}^Ó{°Žš’0 Ž´Ö ã(”ó›|çH]³7Œé:pƶ©4YVá‹(zµÖ±EY¸sŽ.¬)–8p6›:k‰ _›öܺ3gȂ↡+<.mÔŽ­” ýý"åÄ°“¸vWD»Š3ÚEm¨¸-‰bƒ[M;*§g~_óY;Fâôµºð­Ø¼r8Ù¥[êóš¯L;–ðÄd­Ç&YýRðØ'ÜÜæ³Àï>í-ÎÃó!Ç´žªiR%6í@‹è¾Ú»z}pí{¶ æ6pmE©»RÚ¥ëÛ,Í@º·ÓŽõÿj#°ÖM;öý±÷>øòW>øÊ¿ü,ÿÿëÿçÿýÿ|ñwñë?óÁû_þàS_ú¹/ý¥/ÿÂÏýï|ñ‹_üʧ>õ ¿ðÙ_û}ðůüÚW?÷ů~å«üÖþøWé+¿ö¯ê‡ÿÕ¯ý½ó¿~á‡~æßåø¦/|ùSŸÿüç?ø=¿ïýú™¿ùû¿ñýô÷ÿáÿîkþ°Ta´÷,mÕ1‚^Ü_)¼Ðù/`)æ)ÝÞJÃô˜?‘Ûèõ®~íÀÌJèû`¬lFd©Y½°¡dJ± ͘ô}­³I1ãè:ízøèn¸ ¥Ù£;ŸLFàî/]–‘YðJ?TÓÁMÓŸ}ßS zMÌù“¥¤õä¿û k QïG»”T½;ãGå±ê)Ê8­%e@qz¦Ü²^ú/¢=´–é[ìÝ^÷ùc؈ÍæÛDâ¤náR_ä^œ® ¢iL+uãª7JsÓ²5h´®êZ.®´Lö¸7yW1¹Vm§*DJEµXmˆØ®F¼Ü¦íú=Ó)~ßÖL®ýµ1XÂóÙÚ°¦©òxbÚËaoç›=S] ºô·«&™Œi– /êø\1Û³ÉU³\-à‘ŒÆ¯«Æ:§•šð¾ïã›Õ¼–&¶s½uØ´bàbôíeU] O)ô ød(ûWYLåIúë*'Õòª®ªJÞíqøC›ã4q;ý &`»ï4ž‡>W³£¼Ê!5¼®>Ëc{jOÅ{¡6»°Ÿ~Ul6çÝwçœCŸÚjy¤á•Çè|•ccqÕeãuµÇÇô´ÙÇýôËyc÷ÝtÝiF{ÁZx—Er;™"ÿ<ºN8giª³Q÷áO›’ØÈœH3 6ê[y5,%o6 VÎÜl”ivžd¾IN96 ]u½å¾Úfxlsœ¶«_6á¾Ç1ÅFsÛΓ6ec£æ䶺ê¨å±=·fõns[‹mýª=o6²ºzô©Ýç§á•Çè|•ccqÕeãuµÇÆôj³ûÕ¯Íé°Qøˆ>b£ß!½æŸë«“ÂKq~uf5«Ë³¤nýºê*²Ê1*Ô•ÈÌyD纺·o>‚ŶY}ø5Õ¦ØV±d™"]y’vW9)˜k‰]ÖµøÐÛ°œ6ÇÙë~áEã¼û¾¹åâ¨ÚW{/gq¦ÓÙ7G¯ª=kMÎmna¯'Ö¯7U­ïK.Âk‰isT”G•Çè|•ccqÕeãuµÇÆôj³ûÕ¯Í{Gð.ÿ¼ÃcÜQ%\Û%6l;Ïg)2¥âí: qž Ó_„ì°Þ©Ã f&>Ô£ a]RŒTÁ'XÊ<ü­+3<ééI¥@ ‹‹o•Jð w;ªž”ÉzÙP¼oJx óo<˜–?Ó$ )cxêU ÜÒ𫆇ÎÖÛµ}“"¼N…ºŽ®œˆùâ8%X›§…“+œOJQ%h–£ˆ‡e«ÆBÛ*îÀõ$ׇZé]ÄkR¼«Â“=T½Ç=+‚Áú¼qÆåíÓ•’ÞØ]^$®ßÁ…µµ‹ÔÅÆ5¶Ps’"q0"Ç…ª½…‹e¢€HÍÅj‡^_Æ»Póxãe%œ©‹cEé‚xAomóª˜6Ø,/wÃC¤¶¿Õyg°¿ÅF/Ù@2Éoìí)Ò&Á¤ŸÌ “.ª™³,ÎWóȼ³Vox›²TŠŽqm*{ñ+³7ÜF8vk (cQª\,†{mb¼,gn¼¤…ŒSe‚YH]+]îFêÁêÄ%†’¨KW4 L2â:­²b†xîêÐÒº¾ªgE2Éç‡ìû€X€Z³¨Íxç‹h û0¾"õ†·¸núFKËÑmš”IÈÝ#ƒ…ÖÜ Ï^ ŠªSû.6sÅÔûð•Ñ^ÍE¼û@WÎæÞ”Š} ¨Öü»!‹ˆZÄ›´bìó^ ÿN‘iDM’ÅÕÏ6ù±˜wИó`¨Ì>ÃSššYãzШC³ŠAI^£<îÎ$bxæРëZÔgŠÿÄq: œ²R1´ I0€ï@Y誌G”$ÿuˆö曯·OWJÇÕ¬á&>•æ£3ÚËÞ”«­Ø‘f4¦|%šƒR†w¿Ù꫆¹=J,lÑq3¹2˜Å'9‹¦Ž;ŸGÓNÄRÀs0$iÓ ,â)V{B¢s´våè6ãqyî8œ©.­£kõ»‚ñÖ×i(,žgVϺõtzCƒÓbÚÌ©g7,“=+"ÞˆǼǧ7[*ªliDÉi”Ó7ÃoÅãÎ`+6>õÆÍ&„“b†;ªÞGªi,kpÞÇ 2w|cÆ=$ÉRB½t˜mÚª™»qG7nÁFÖDÞûÑÔe¼ÔþJÆaJsËxñ)†;µW2~RÌÀ'?È8 oßxËøI‘Œã…Ä-ã0q<zq˜.]2Χc—Œã}Í‘ñ(Ôx@sÉø2 ÊõAÆѹ[Æv:)’qtæ–qH?ÈxÉãAÆ–Œ¼@}ñRʃŒ—ÒdÜa^2Ë›;Ã,2îøȸ§˜Œþ ã°hz”ñÒúƒŒãåÒ-ãп–q*dosn‡Ö-ãÀ2^z~q¾;2^Zz%ãàö-ãxOuË8Þ©=Ê8øaÜ⃌ì2~RÀû%=È8Ê”qŒÕ%ãhÐ%㥖W2Ž·x·ŒYclES—ñšmÏNjË°«rñ³m¶=ƒŒúywP¬oÕ ™ÂÁ4™Ñ¸3p3Óyçj`ÚùDp•¬||¹‡½L'Îj³ÎÈ }cOIh\¢a&¶Î0U£u‘OI54ÛDû”tRô±n²7ŒÉ¦7ô2Võrh“¶qßÙ)p`H«¸/ŒðèË‹Bűúù:›ÖàýK²ÅÂ+;;¨Æž‚Q{4´;9¯¾ð ÛÌk&¨issf¤mZ°“V6©Ã£:ž­èjœHKÀhào¾F2}7/8Éâ³dgPZLqcfcH«¿ý;«À§ÍÁ醪fÅ5O[ں͈’í’3dwZ¶·M|ì·°m31[4ÎÞœ {‡Á40e2à¬+¨Ó,?œE¼ !ñ"ç¹’mø[4Þ…{ŒäJGò[²J&À˜( ›oGSe°~9ÓìéÇžva嘮‰y}jÜ< b oÚ¢íê³h=ìô¾ª¤ð­ š-ÐÒP»é„êtv¦ß™ÁŒ[wž¡umqo XFõë’Šy&9”Pí <ø"‡%h¹ *ÁñÞ#œ a6OÒfkÏ<‰™Õ°'·Fó=™íœëÅ`Ú,–-•¶£vQéM`·ÇÞÁÀÍíA¯¥²Úþ¹k½¯³jIés—Î>÷˜QÃr4Š|wÞËꤙl VcÒÄ×æ«ÄmÙÍ#Vª~/t¹ø¢ÖI×24½)ÞƑՀ룷ۖ.ŸZ¦ Ù–ZXé†+n–M¥´ØØ”.¹ùrÉ…õ©8Gr;‹3 ådL­þ°v2J+7ûwÛ¿ö¯6±{ŽÅ4´i#ຊ¬Dr¿‘šÜÍP›‡AÕfÑ'ˬ–déa¹E‘oþ·fšš…$X߉¦”ý…M'a»éDë4d¬Fæ"óDm?¢æЖŒè“Œªl ¢-S„à ¡u~ ;m»íŽ«Ì%ú Í\·Õ¼éd¶5(íêi7MÏÖ„áê×õ~Z³›4®;¬FM÷Û¢¢þ–õ¦þÖš‡Æ²˜"í"_¥x+#̇_]X¹¤³ÞÍ–†"7ì1¤µ—6;>Ë|–•ÉI‘aÄ”`ÈJV,Í'jÙú›n/u j f)G0ÍNVPÏΠ+ qæ‡vÌ”ýÒ–:OþäÓfM­ÁšêçPM8´bb7—ÐF€n»¸`¬Ž‘SzcÖû©sÌä<0¬cM[9õP6ÄÓú J§Aœú{?¤äÞ)Á2’Æ“@…M‰RÕ+3ð­¶gŠœï©À} RµÈ½AC­L‰Ïdzsf4aI»¤ÆÃÌǹÔT߶~öì"æX±Ó_ˆÛ’8^¿­Iœ ê1ñlÎĉïTÁ"áæѽúµæ3£µÐ4¼ÞÓRØdûê©d r¡Uƒ<}¿ÿAk\0ż¯†ƒ®œâô£ê²/3ŽŠâÀ¿Ú‹½šk°ê^Æñ¸˜FDÉ®ªc³º’_UoÏãfTßäM—¼'O–MÓUN–ÑÈUW4ƒ¥Óž¤KÙ«ÍfŠsõ+Z]»ï1˜©”ÑçÊZñeTÿÊhxå1:_åØX\uÙx]í±1=mÞã~úå¼±ûî°é£Û®êl4ª±ÑtRÎbrv•>Úf#þmï?ìí¬Ï6d‹æÃ_­®ì®Éb1+²6cš' KÙå$uëª+š]ÜiO4ou§Í¸\­ýŠV×îûlæ„?îaÛyÒf#+'4'·×êf£hl4}ؼÍ!xÉÖ¯2óxì{™~‡íô9ÏU†W£óUŽÅ©ËÆëjéi³ûé×ætØ(|ÄF±Ñï^óg,¼œ”,ÞXÞ«™`#ªûßûæ1«=šAGÄòÊæä)ª£ÌæåT3» Áª6Åv”–Ú«<&æ*'™9î©+š©íiO”AèÕæ`~úe¼tõ=Èóæ(Ï3œÎ^NrØ]WÚÝÞž|zamN².?ýª¹z9Þ÷¼{á—»§8 O£óUŽÅ©ËÇë´ÇÇô´ÙÇýôkóÆ8+Þkþy‡Ç¶¹MÄí)¶Œ0²¡¹ ‰€”¨/ˆ`×1Qš¾˜Lm¥ì£ áç·O¤ç WbkëtfF)ˆH†+w•JÑÁÙÝŸ~‰ ¡—‹ðÿˆím̦Ÿ` ÎTHÃëdÓJJS^‘úoÆE+E×WØÁEzN:ü%DL£h7B ÈÁÿI±JØ,C°çAj”¹ «<ý.+ˆ×HY£vËI.ï¹GSE|y°ß¨\)8mjty‰Èˆ“E ¦¤“mŽm™2·‰ JÀq¡f‚£A™I®Éq¤°¡>Pî¼ã°!|%KA »¨+†‡Çm¨¢tÁl†W Ï/ ë_ñÂ2·±¶³ûÒÖ$7žŠðÛJDò{{ŠôÂǫ̃®Z)áè‹kaöÞWpÊW„sPsJÞ}3Vº±‹%?Jl1uï‘é"æÎ0¬MÒDÜMÍ~RxÙÉc÷t§É«=!ó·s›q5óF„ #3÷­›¸çê%vã5©Ài÷ŠzM½»õ´yC‹Ó¢ÙÌÙ²ºRySëQO±S¸,Ùø)ÏŽ,âÞœ”LÙ('5§á·â‡qg° ŸzaHŒ±S2~öê}¤´_á&ØÊ—¹MäÝ;D’´)(sÄÒª‰Ë|¥·Ô´EÞûÑÔe¼Êøñ’ñ*-è–ñê‘ñÙ^˸§HÆq¹|ËxÕíÀ–ñƒ]ÆOŠd÷Õ·ŒW: ºe|ÔW2>ÒƒŒø ã…7ã.ãŽ$Ô¼./ïBÉ8]_2ŽÎÝ2~°óÐI‘ŒW5rË8¯þo¯ÚãlßØd¼jwÉxåAÆkl2^õå%ãµÄ[Æq¿xËøÆ[ÆwŠd¼Öþ ãµôW2^åfñäХ˖ñªËô§BñAÆ«ÖÎ-ãUWž[Æeœ/þ.¯¼‚ß2^åaé’ñªÃd¼êIÀáUð+?Œ;C|ñ·ŒŸ”ŒŸÓƒŒ£üG¯2Tv¯z¡ï2N÷Ã2^ÓxqX9Ü2þŠ¦.ãæ©…;S‘õìj1›µˆk`6N–OKŠõ·ç†Ñ˜i7ÏÀC€:Èv>1ˆ«6~Ö’ö2”ï©«;à‘rè6É]ÝEÜö&nsAÖ!s›’ªn§¯)i§Ø”Ôu+ëp$Ûú ò!cš8´I;ØsRpÖŽ4?ˆÎ!¾ mQè¼:gÓÚ­2B~öã°4=µG«ŒñpäÜÞ8¯˜÷L0‡17å$6{rc§!J.íy¶‚Ý1…nŠ:JÀhàdJ?E|7/H‘àgÉΠ}µ1äÊ"‡ʀŸ¶ ¼‚¦?hð`jmylëfæi»d #/ÛÛfÚDÜŸ‹1q'ÎvÎ…£Ì‡Ý4gÀY× Ö"|ȃ´äl­ûÞ¨Ù‡ñn³§"T:’ßt¶° 0&J‘l¾”e ‹êgš=ýØÓ.œ¤kbö»×(‹æÄ„»ú¬ÞT;½kÉdÀx6GK½¾ ͧVE5ýδ ¢'ÏÔ‰ºYÔŠ(ã¸Ø’ŸXÃÕé \·Q‚™pPU‚–›¢6ö=ÂI¡6ypãa¬ÛILR'ŸÜÈQgf;§Ã0$˜6‹eK`¥í —æ¤%„ßOp[l¶‰ÜK¥DÙ;Fø˜é6!ûˆpé› =5,E~8ïeuR'h«nYkÑX%~h;H›ŸÇu5ü¢Öé ¨ƒðüDÞÆ‘UÀíÊz»m鲩7¾å`¶Í–cHEƒóws¥K —¹M„gqÜÑG¸~4F¡š´JMõH]MèÕùLÌÝ‹í_7û÷d»ç@´ 0 â p]EV"íc"¼5IµªI/ÿ‹†Œa……‘*ƒ‚[›ìÒ*'ÝÂx™½\9¸„ÀTg:èTI1'#œG¸ˆÍ¸ çÄC/”œ5°¸WîV5š…+Ïj,§çÆ„ä›Ü\¾¢àÆyªEUd†Wܹ ç£ý»®8§6ô9S Ðp ÏÖîÎD /'AžÕ‘Ó#T,tÆ@/êk`•}Õ%ƒ$bךä¿O›eØK#-¹4 däú˜Àó ·Kpt::9¸ÙHŠM+§í"5Ëf¼™§¤F×þŒñL¡k]5† çÈÖ6Mæmƒ=‹œñ "Ù”—«M{R¤÷…+Ö}~@Œº¤c ç^œ78mÓ_÷ÂAM­”¾ÅÍ¥°4[1 /ˆ»Ô¡Å¯1c´ý‚¶I|\6fÅ~ý U-ˆ ÈçbãÆvC< [bgHF#M’£Åë>*²y&ãYmPOµyqX`+ŽtÑgU|é´å´èâ’d<¡oWxu0ßX9Xí=ÆN°->¿X.ãž¼>Ì݈?ïNiÄÅkÎÓÈ55B1ò*WvnÁ@Ÿ` -n“ÌáïÔa!Üðærå€þк¬À¦Å8¦½Q¸×R´DÙ.¬`ó1C©9Vƒ†íVNÊö?œñ^•› (ª4 „/7ThV<–:Œ vÄ6(ü€QÅ©~À”§Œ{ªRž÷ Ã+Ù'Œ“ óü¿¿“"WêQ9KkhT«¶®vÙ¬p v®],)¿¹æý G¿3>û¶7*šè=\5®ÁæIy9)8SĦ}u¥(ðîÞƒUiø¹…ä©V x#±—ê^Á¹µq Çxù.`*6¸—ÊM*ž£[<Ö HEˆi†í±3 ›xq<60asŽT‹A¹%h r|¹a¶¥Ïþ¸g™dl„Ž|æÖ[z‘Mb³i® j¯”£‚äL¼95E3»Rt ÇUÉ»hÚB›í Ä —­«2E¤À¡vj«õâ°“²ÅBà”ŽÈ¢x:ËÆø·Æ•cDuš‘'“¦×K­”æ‡^ežlw/jå¢+'Ün&«™.ðËÉu2û¥Û¥ƒ‡yt:):·9ÏœJëø‡Ã®·x>ö½èÐ>èð¤jëù×Z–_ûŒ¯‚}†û ¸‚ôÿx‚pÇ»‚}ØŽ·`A¡}´ƒ`—iâî ´|Aè9ï ±>7ÞÁ¢s\Oáá HMöÃAÊèû Ȩ ç ¸á>ž”a13ÇÃAšÂǃ`§{H;ÒWÿu<Ø‚;EAÔw¡8"è}ìÒè (°‚‚~dW®ƒ 4÷÷A°+Òòu„’ø>öƳƒ ? ÚA4îƒ`× v–zèOïƒ`W° }ì-¼:‚ÿ[ôÚ*ô^_ûÈÁ>ìkÆ.õƒ ˆ¥ƒ`¯íá ýô}Ä=ØãAº‚º?ðƒ  ¡9¾‚jÆÃAAÄ"œòG0µ¦ü}Êë ÌÅͦüáêtE`Où‚{Ê´)å¸?T4u×´§ü“ÂI¹ç‡AŸôG¦K–˜Ðß °:i¢*¨]Õˆ’B<ªìG$cB¯[ã-…£0RȼË<Ô,›å Í´6ÿà !:ú¼rH°Šÿ¥Ó 2J'Èv¾lˆ[•UÆ“rÒX0"&ÌM°" Á ½Üƒ)C?«ä7ÁÆ#ÁÆ#Áîi n¯JÁаŠäç‘ýcxwʽ։¿údøªÒºéôÂëqm¡,G *Ú_M2ÁM2ƒ\¸3ÞÇC3x/¨LvRH$xdÈýC @tkã$_3┳^öÚþvz v³©0h#zß9+a>;K•ÓÃs졃«»‚—7Æ@6!ÁwoŠZ¸A¢eÒ]B“FèÔ½Î[ˆcâà°§¯‚³E rô³¬c¯k ¡?Xñæ÷ñÀ:¥*·ŸéÝdX'³î+ܳÜVx0¹¬x°~¬«qù:°.˜®+šþlÖBÇ·÷µà%òu`]ø<|>øp`…'˜ûÀ ¿ ×Õá>°z‚Xñù}`5$g)¼;9¥u`]ý)ïX§ž€ù•žI®+Üß\VïÔYÿ0â>°N;9VRå>°2á:°.ï+ñÃõJÙVEVŽû‚÷}ðO²ÚûŒa5åGÿÜÓŸwßÓ|ìÂ%ƒcÅx%R%a饻â®ýÓä>ŠÞ‘qÆïÃöv ÛÿÁ &Žð KñT€îJ×ʼnӅa:,¦ºhçÀ¸* ƒa®åÓ®€S€s´‘ºÌ;"eÓw‡þ. ¥Èœ€"X‚­FÊš";ü&C÷jíHC]·Ÿ3ÿV8#˜Xhæîæ{)Ê ^:€$nÆ8;0¨S”3“Œ šKì“òrRfÈ:úò«ÚRÖÂÄI1A®ƒ5 .V|t [ÃF¹ràš°ÊÃsÑNjL³ºKfuÂé-Çã?5Dâ°$EÉcþ{€¶ytîÊ d{fd0ÐÂßáb>òA´}y¯ÎzZur…ûˆâ4¸Ðl*qwx)O‹ßÞ4yKWÈ5º‡ —¤=jîzÖ™.ŒUn–çäÎX† ©~ä"]ΔÉãš´àåIweòÍËÑPðQèÞE0¤R-𼇳t¬ 0Jwwæ€|]ýìÞÌMáú%%#<Û$<–<ŸGqÚÎÀ +½Ç¢ý¡ÜÛª½f–÷ÜíÇÔGD`Xšÿ½Û/(Vx1ˆùaÐU=ã”rÕ¸$ùF«RÒ‘ÉsÈ:ê p>ýχ3xAjx_™¹wµápxÆcðˆÈþ€ÓŒê¼0LJdŒF8x—MßÐѦ°ÉÁÛ±«§ˆM 7ÙÆxåøÈ&¸Ï¸ÙÏØÄùá‘Mð¸(ÛòØB5ؾe&yž¦šrG»£lü–1H®Ÿ¡ùÐ×Õ’/0´=§ïWªôŠ>y97¯Q/pV뻉¤ÎÑÎÓ‰N+\<óÔ>ác5°; Û±’>ÄÛ[Ñ{6­«æñ¬ðë!0GÓ®¦s,Ù«4¸S.+{Ô|¤Ùõµ®íÿ¤Ov›ÙU`Ü@>/Iæý³>!~´?ºŠ‚ÖK£3‘PF°ž®"ÃÖ)ºáËCgp…Áã,ÕJ©— ±À©D€weðD Ôµ®½84æî¹Û}&¯¤3ùÛS«136ÙíCàØ!°}‚ˆ½™Á¸Àt÷ê„àm^/'œ®8®A, ÜtãúÐV¼Lè†$žòr¥ôhççýÕ•’¹íÂDN'ž¢'\¬‘v#‡¼„¦¢aáý AÇ´Ø«Eã«iËõdüf-ppèŠÐÈz‘² ­òP‹Õœ¦h’ËxÖ趪GŠ{µeÙÎ#JØœÓý‹¹Ý»Ø ÷BBÿµ‹¥™E`¯%„g-´],çêkë5¹q§ˆa `ï =3½øÜâ>z<»X½‹%<»XAÛÅÝî=êñÕ.ÒqïbáC×w±ðÇ],4ï×.jãkKÑÃ.v†ò°‹zÓ¹w±û.v§h;C>3÷xœêÙúú°‹…ÛÈ{»ùáq‹ ³Ñ”k¼^N0¿ÏE‡gé¥æÜêäü8’.â4MMyö›Nõ<äÀæÖò‰v¼^6hª¸ÄŽ×*mî|è+œß¢í¼:¯_Xæ¯oŸN ÌõV†Ä7ñyè !1vAÚ˜5t­„ž£HKé8,A×ËW m |Sœ _ï1èm³£`·N 6v` ÐÎ$tp4uáIa xԗφuáAååÞ¿ÂÉ{¹3p§‰M~w ¦"o3bpÊfW0O^ x;ò¥@²_Q#¥ãb\/…¦FÃnF»§­6GÙ›V.ô³±G,|ïüé`¯\jyPÝÁ­/¯À‡{`Gt)Uªé2jß}±Ú5 S…yŽ™Ž" :ùQöäƃÅ4ýžBeOÙŠHgŸà˜×÷Øû“uÃÞ ¤æªíÊQŽB@çÉì<*óQ[¢³á®QÀÄÆ,_×Ë! §ü‚©;8åèS~‘ú}Ê_Ø6“¨WÀ§|Á=åUXά{Êß5í)ÿ¤p’ψ§=?ú¤Ÿ:³å}~X=›WuùìÌQ¶4£v~pHÖ^åD\'óÄ€é8àed¼¤0#lg:«xè”÷aáLK¸}ˆÈúúyå, ÿËO‚ûapÐ<;à6`oøW%—É7Á<Å(3¹þ.<Ãûð¾WÉÆM°ñH°ñH°q ŒœE04lr¾Ð¥»>^ [·^1øBÔˆpYozá:G\f9bV˜_6ÉÉuÊxuÍà¦>0ÙN‘p1•û»pdÁÕ½>ǃ%Øký½éE¸\µ1⓱³eXic>ÛKÕ¡‡åð¡ƒr×Ëaèè½\+…·Ã\¸A¢€Hw Øæ=ÔèOñd€!«ÖÞÓÂé.'yÌÚú«œ`‘sôWzvôW|6ö ¿ÊÑç6ü,®¿ÊqôK•Í@ÁõWÙž;¹þ*»í¶ôWÊŽþ*áÅÑ_¡éϦ¿Z­ìú« ;ÌKµÚý@ž()÷õpë¯räëú« ]å ¦¿Ò›°³Æd·ÖÙkL6[ÖcSZú«œôPûÖ_e3d4ýésé¯ø^îè¯N§|ý_)ãÖ_éyÞÑ_‘*·þŠ —þJ/þŠøAu¥lý•y£ç³ÍÜ rFÚ5àv™‘x»ŒµtüiZõuuè]¸D÷ ¿N£ò¢ûnJê½*ô‡¤œ¯Š®êNŠÇ†ÿoڈ׵ß);fy5×ð˜-"¸îí?$%5w÷o‘Î?$å|E}ÆCÊ»µ¿ÓÂÇð ¯m'ÐÕèç)UÎò ÿÂÀuZìÄxðÛ§ˆØâù¤ÐÅÃ7ô½QO™[­æ;)x±c.õ-—“~T&ìaP†×jøíÓn™¥¼<í¶[Ê¹±ÕúÖ_‹§¢‡ÓŠâE²xJ“÷g]š@Q‚ŠTÈuÇ ‹Â¡{ Ýßp0=E¾¨N™[­oŸv \|šßnKIõ¯2«È Þ»VüÛTË,ååi·ÝRvַ̭߬ŠEùIn’|òéû8­Å#Ä55Àõ4Nĸ2©ÜÁÛ‡ÔçÍœ€¬0»ÖVn3` nJÒáQÏW² "ÌÜb.°˜ž±;“¼jX-xßèåo§$ú,‚¾¥õwa¦Ï8–pÊWŠòY`ic XPhƒ“ûóÏz¦>Å ’¤T€3CæÝMÔ©;ùõö”—“‚˜‚Ný«;Eú:DD eÇ·ªrv£Vx#k1ݳÁšå £[”4p )¢Yu-úÙ~Ú‚‹«Êµ4Be8OçÊÈÓwg„<\-Ä!GP ågÃ#C¹—àûx‡U”âëï­.lxe _n˜M|¨šºBëh#Ë)Â\ÿvMÓIa/UV³p®ð:…bfÁ÷ŽW„»ÛA&Ú)â¨Ãr*?Š_l¦øÞœ’ˆ|T*þQ6áp§Z‚Ђó»ªÊ—f„Ugná·¨;[DFÏÁC¼nF;p…ÉòñÍ^)¼/‰ ð•ÅÊkS¡imc|±Ö‡¯°£5äìrc8ÉLßµ‰‚!«1@aŠ k˜Ý7ï  Sù}ÓX:cÀùCßú¿”ŒÈ´ƒ¡–B¢éR‚U™;!zNíJÎ"@ál8Ó1cXz%›ÐwŽ¨è¸˜(Ju*¯QRšiBÞW/‚"šB³>Îx«17F§«¯)–º+àÈíòÆàñáNÁ^ £ Ÿd €ÂD¨pfÙ_4µžª¼S‚ãY¤Y½R¨>‰Ù¢8¨¡U­i Œ[±¡áVXÇžŸìo²7ˆ ‘öÔ¬.XôR¡kœ ¿µhåÊ1uÓ‡¨ðzãØŒ/<6¶Š˜Ðøºv lUà-vHpKD›Ûh†¢[ÉŒ3 ¯ÈdÙŒìÒ@pmºÁÌû¸]fê2‰$pÔ %Œì=Ùdb9pšìXJØx-i]¼il;”ƒò‡ ¸¸ `¤vW±Öä¡ÅÆsèQM’cé„bjN€t£49Â_Vf®Å\¾ô\'"À—B`wÍ+ÒE:¶nÑTÀsðçBórÕ,ó 6ÞîqÄÉ`=h cKÖ@åx$½ËD€ Ãj?Zµ.dËB ÅvMZž’JDÀ—A_ ‰*,¦—½,x={UØ \RíÕß¾¬Ö3äêyá~UC8Ë$‚ù¾}Ù7c'X<. !”-q\ˆz=îp„‰phÉE‚BŒAM…aÉHõÉÎ`\I°b¬ÝŒòUoã‹#ÄBÇ–1˜ÁP¦òÎœ¢™P«v™*xŽD.U·pÈÅ¿7¹ˆ`G^eò<ê!ÉÝ[`Ô"äÄÍ*7ëÅ‹‚‘êP5¸ÄØtR,õôfèC†ƒÕ6)ñcÞ‹­¶C¿–©CÏa#†ÅÆë;6e§¬^e2n"èÃâ* (Ä詺çY Ó3#\cÚvñ·SžN8+ó6F±]Q{±>cz‡©s³Å‚’ä€Þ1ŽBðñvçXÓ>gï‡Y4Æe<öB³A/Wm—*/1ÎÚ€ËÚ8p6“ òàå!­rè·èæ‘] Š`ªliS€Eh@ \M§3›³« yx¸w)éeýÉèÔIuˆ¥O“ÆNý™ßÓ†ÏÖø5â´¸W¸êóÊádOzÂFQŸËVó“´òÆzœ9L8¬E û„­YÞ üé“ohô>ïµÚ )|  m‚ÛÊ/WQôk#p=S+1·rÁe_(%ûäGž×4Öÿ¾?ädAÈß¾ÿôßýôÞwÿÉç¿ò£?öçžÞûþ•íé½?ú<ûÓ{ßñ=ŸxŽOï}çħðgžÞû®÷>ñ‰ïZð{¾õ[ßûãÏß²~ùħ^~ìý¿ô—×'ßþíOßýÏßüüÓïü=_õÿþßÿá§øï·þ÷ÿøÿË~í·>÷[ŸûÔW?õÅ~ý×~û·>÷SŸûÔ—¾¸ñ秾òE¤­Ÿ¿ò¥/þÚWíÛ~ý·~ýK¿þ¥ŸúÒ_ûê_ûõßøš¿þ±§?òÝÏßû:Öf™¦ò‰Š¹õþIIŠžU†)r¡’ tS+~ûT’©ž,åå©ÄúøMpå••éØjÅãKÙq=%©D¼Ìu¥:Ãku¼Ê°–yÊ*ÃÚ¾¿±¾í2½¯VëVx@ð-D0=êNÉÒŒ¨þ©w™Ô¦ײYL‡b) K0ÒÙ7ÁŽ÷^¦c«d±”ÐM3ã)qZN+3âeÊ´Z¯2¬ež²¨íûëÛ.ÓûjµŠ,íùÇ?¢Ë+º|ˆÖ«$Se¬•ô‰¦n|¹`„¦õJØÛ¯FsÎÏt|` ei½c2_#á35­WTŠ] žÆQëuRBçצæz £Ê6­>_;„…›êZsd^P b™Š*É^Ët}šLë…çþx™L…½µ^%ÙPZÊËIÁ•u\û«;EZ/¼ÒA MëEÙÕ)àä-\Qÿš‘y"«´^ Í‹¦õJ|hS’i½ø[’Ö+I³X’i½x›Ç— É´^t`‰¾›Ö dkQ’´^Iqµß^¬¢[dŠ½°Yɸ,+ÉtM€/Z¼C¦Hë…k³Ž–á´Ž‡—k4 àa}×\ Ï‘ü’(Ò×:‹™YLTPŒWO0d¢"®É¦æz •ś֋Æë$¨²ÈGÕ ¾U6¡|¤¿8ìÜ”dZ/úÇZ’‘Mëeø-ê–ÖëäÖ‹þT:°´^ôO–ȦõÂKëÅ9%›Ö ¬¼¶k Këe_˜Ökç0 ±1¬"8¾;erw²J¨Î…UHëe˜ÝàÉÃ3$ÓzA<9–Ætª²µ^¥˜ÖË?¿í^ñ¾‘Z¯RLë…”µ¡,Å´^ÀXZ/ÃoñE²IÀsDmÜ×Da %i½ ö"­—AD°^ƒW¤õJz™Q²i½ £Ó¦õÚ9L§…›gT¼1 žÉ+;E¦Ï%›Ö‹>RAgÓzƦõÚ9L§µKpÜ«´^W -K6­㾡UdŽ‘MëÅHó™ò™§æ§Ç›ì b‚ X]HbÁ´^†ñ…i½vÓi™s烻iž”fÑEY ŽOx\ÎVIëŸyx(žMëë’"º™Ö‹XÈóÈž)èR•ÖË`¤1âúPZ/˜±DXZ/ÃÈnZ¯CZ¯ˆ ’QÝÑ’6Äë%›Ö 9(¦õòŠi½NÅ´^;‡i½"C-•bZ/›!N¨V³µ^%›Ö Ž.8¬¦õâ$0­—a뵞ƒ?'{ÈQZ/ƒ‹Ä˜³i½,ô€µd ÔÑz•¢c¯- Eê&[ e¡˜ÖË—…¢5‚öxö² èË‚- Å´^¾,x={Uð­e´Wïå ˜Ö+*øÑÂýª†V<,“¨w)rJ‹i½è4“i½Ž0i½LöŠi½à²‚SLëexå¯Òzy†lmY+†nùª·ñÅ"†TdKÆ ËH)¦ãºÈä)¢M5¥Ék¸©U¥õŠz/¼`>Äpb mb±ªi½h‘Ô€¥õŠÃ4'¥šÖ˨UM뵉aÊž‹Z¦õÚ9 Î¢Ïp`äâß›\D‘D`£rU)¹µ<Á¨#=×+¤Íj5­‹Z%ñ1}¤ñµM'¢ž¥õ2hÛ¤jZ/_„ªi½Î2å„Ø9|Ä&·0‹²ÒzEy$ĦõBl «´^»Óz*Ši½Lüw šš´^plH­Wi¦~¡÷ŸÅÂÍ´^˜’0 6ÓzÆQÈ´^;‡i½à¡f‰^i¦õŠò"Ž/Lë­êÚ¢,,­W”Ã)âÀÙŒóK3­Wäei¦õÂ`€2MZ/˜Ñši½¢ÜŒà{ÓzE…¡(Í´^N©f¢CËfZ¯Ã”Z¬ã‚ÕTå'1¶žù}Ígíh¦õ:«K3­×ÎádA5šÖ‹ql¥õZdᦣp˜LëÁcŸLëå ¼÷élši½vÓz1ãU"·%MZ¯ÒLëE/+HÓzÙlALioMZ¯+e¿Ûú‘ç5®õ*=K‡ø!Z¯Zþ«µ^µ˜ÖëŸü§¿ó§>ñ·ùg>ýéÏýÇÏ}õ¿üßoîï~ükþ'~ùWòÛ?þõ?ýË¿ú?ùñ¯ÿ[ÿæßþÆ_ýÏ©¹hš0z“{Í÷OJ-C÷ZUÁtÁêR]™Å0î嵞zÊ‹Å9)bÓO™[­°Ö±”,íÄËI¡wa†žQ™pçB]„Õj˜ŽÔ2KµŽµÝRv̭߬ÖË®«Éx¬Ètîý“R]mãFDfø_ãõà·²˜¹rXX³+# ÆSæÆVëÛ§ÂXÄfĤª–iĤ2Á¸$“Õj˜nNÒƒþæg÷ÍÊÜØj}+Câçÿˆ.¯èò¡Æ]‰îªb¥0öÀ‡Ž„/7T/œ%#ÂVNíAApŠQDó,„¼ÕÆýÅaè2îJ<Ä,f“ÕR4u¿=õ®³¿|HðYNÁwcô˜à‘‘¬T»ÔÆlÕ»úTÍÍ>’Ò¢u)ÒO)Cÿ3îÂk“\wÊËIáݳd_Ý)UѬ»")u>6^Ð"™±UÞHì2̸‹0Yœ£C—…ºÌjªÅÎÂ:›í7: R„Qw ˜»wEYñ6¶9ñ°¥qW„‡·ˆý®w«XÊ6î£ÕIv§qW¶˜¼Š¶áp+Z>€CþQeÜUŠ¢PÓ ˆ W7î*u\Æ]Dr Èb+LDã.¯S2ÀÊ\_ãyfZ~¤ÀÇîѸ‹1–AêT¶â/w7î"lCÆ]؃NΆÝžprÑÆ×òßzåèjK§×]šE9Kȸ *kŒtÑ*š§-²2MGQŽiyE•ôÉù‚2ƒÆ]7îò–eb¦ávÛ-†Õf7àKçdtbáA‚céŒÑëƒqW´d,ƒÙG g¤ˆ“¿wîo˜Bã.xw1LÓ-Ý0:ÆM³Oº;¨ƒŒ»Šw¶æÆ]„ÚÙFù#TŸ’® ÆܘDÁfwË‘d± K?w9†CYFí” Ó,ø!F™ÚöE<¢œecÖQ¡æ:9*_WŸ6înÜå)]A¥ñƯEq»` …0ã®Òlhº¬€ ½Âøü´áfܵŠŒ»ä¬Œ¬B"Tz¥sL«¡À€Ú;êfŽ$ã.ÇÝCaî”Zݸ ûdt¢ µŠç Xž4â h yoÆ]ÕÖ4î‚ÝT¦4î"ˆÝ»C•qÂ;snÐb+±x0 \l2±P¢€ ã.ØŸuqœwuâ!åoÈ~x0£­iÍ»-™<…LŽY 2X -þU›û1îâî/eÜÕ¦–¯˜ÌfJ=¶J¦[ —jغÕÊ•튬3 $s(¸Š4îªC VÌ>•-aÀeÜ…¨¾0¬ö#†­ ù²°ÎwÚ(Û²BŽ’Jwø²`ЖC¢ ‹ée/ »_ëjOÐÜ~ÚLßXý¡_A;…Ó÷dëÚEË“BʾNš¤lËa¯ËeöÐêé¡Í²%¸ûuÞÌ{ßù<¦?J\ð£á•Çè|•ccqÕeãuµÇÆôj³ûÕ/ãÓ÷áŸwxìŠ./»2½zS ñLÇÛ{¡Q+Æ7œp¢‰øÅÞ8ÒŸœ ?¿}:Vð¸òêïÆ(‡0aêI¥¸ •šä¢fcÝ~R䃘 Å º“Á% tmÁòÓ;ŒT‡ÃëTßš¼ø¯-:‡2¬·˜q½*=¯"`<¡*¦ Œyžuß:'EaáÙ¬`d!ÅqR‚*íwD Iï"ƹŒî˜Yu¥;© ŠPcÞ¸XŒÙ“ÂP€]^9eÕMö¶º¦© £9|§Û\§ú0ÑÙSäX2Äi¡×{+˜ëÃÔÄZp‘:ZrÝ©G;/²iÜ9`éÊ8G]€‚”Ì_•½ù–DèªÚbyÏU”fÑ6’ž£f{d䷩Ѫ‰ri2Õ‚1‹9òZÁ©@] ¢²Ç6„ÎK±ì9 Ôbc`÷YÂ6JñÎ1ªÍnñÙ½Úa-ÿ¤BØWó ÆhCBe>…QE5‡DSk”Ððv© kàÌhìû°µÉ´î¸_…Êk_‘zÅ[\7}£‰¥åð7þkE0Ð÷XyÅÃG=®Wܨ¦ÄE›+ªLÆÁWF{Úòmyz~Ež>>ËK;÷¤ZNþBäXÄ›«VØñ3¾Nj+{§PŠsL’køžüXÌ«P+Ê Ø)TÎ-œ%0Qá×äD‰ Éjô‘W(±Íä¤ÄK ˆ¼ž“{MLº­ã׎(zK"4€¯áTgŠC…$iß21´õÆ|æóöéJáBÆÎp¸‹Ä'3:/Ä´Ræh+v¥ÁÅ…)_™ÑXš®iŒàÉVÏ*_ŸxÄpKl–'šK¦!ýÎЭM²ÏuLNRÎ’ý6·ö0ÝäÚ$V{BBy²žçÈò˜O_¨2sH`­¢Yõ“ø†(œ]Áx5jbñ\³X+ZO«748-jÒº"ç,“=“ŸÊ\¢Ä±ïñÉÍ–ŠŠVßÔi”ã«&ÇoÅãÎ`+6>õÆædüJï'¯ÞGªi,ÝŒ’cÅÒƃ "IB”q;®ÕµjæÜ•[ 55‘÷þ_4ÝÁéc%ã%ÄGŸõÈøh¯e|§HÆg~”ñYeÜñ‘ñb2>Ë£ŒËWù‘ñŒà-ã0ã¿d<»_“q<ß82¾…·;—Œ(ŸõQÆg~”ñ7í“ñYe|öW2>Ç£Œol2>ç+g˜KÆq±tËx‰á•ŒÓsÅ•¡–7|ÉøN‘Œãýü-ãxDð(ã¸r¹eœ—2—ŒÃ 䵌S¡ø ãEáÞ·ŒÓoÄ%ãÀ2N —Œ:EÝ2ŽgQ2nß2Žô[Æq•ù(ã¼ü»3Ä?Øeü¤Lüœd¼Èç%ã´]92Ž]2ŽË²G‡Û-ãvo¿eüM·ŒO`gj¤žE]íÍ„¨(‚›l:Pô°mzkjü(»¯Æ%¶Zî I{;8-60í|"Ø馟µ¤½L'–U˜{vQES7h‡­óú sÅ)‰ñuÊ=%}ܺ¬ ödÓz©8ã O±IÛ8îÆìúOÆ­Uǽg¤gz^ø{§+Ãò|MKóþ%1%-+tvP=eu¡= .9÷¥¹Ökæ=ŒaÌ-÷³ðžÆ> Iê¦íÁà,‰œ0Œ:LÀh<Óœ¡4;¸©`á$[qgP|6mcFÈ1œâDý^õ£\¢ ìnT· À ¡à>ÏÛòÐVgæ:l—ŒszP{š<¬×žŒ bLzCm7ç"ÍCŽf xþ6à¬[¯Ó,?œE¼ !©=êŒ4² ?Þ¦H¢ƒ]¡t$¿É8sa`L”,ÁÔTYg$‡=©Z?®i·6ÉØ9ê0n¦óã…í4™Š¢fX»ó‹8TGa(U˜a‚ÃÅ…~N¯¢?s0/Ô–G¶<ø&Ž%`ÑO¬KXÄNÀ$‡â4”x” åF1S6Þ{„“B!Dš'i®°°Ä$Eæ-Êe0Ã!‹ ê×f±l ¬´x¤•Þo°È“î¶+7‘×RY«N Që=ÂFu›}DZÙ˜cfºÏ9˜nÄ{Y”À¬Æ¤Šï@1~hþ¨¢ùDÊÕÏ㣙³|¾Ì’LoµLñ6Ž¬\‡$X½Ý¶tÙÔR«é6ŽÔ6?JXŽ. ÎßÕ•.½ùrÉm=çPnáß×…*Ðbj2¾XØø̘»eÛ¿nöoѦ.Ï¢˜&T\W‘5˜s6h›<ŒP›‡AkQ0töEf´„ÍDzÎ)‘oþ·fPaº×¼Æ*Í"O´[0@Ý|<Ñȸ³™¢¥Já5‡ÖaD/œŒr%MåÃÔA´eJÐç9µÞ'"vÛWv®˜pð7æÊÅu[‚•ê N»zšMÓ³5a¸úõ™Rkv“Æ•b‡Õ¨Qw-*Úß]£X÷΄mæVõ¦°kÑiuÿêÂÊ%0­U¶4X¨à¶æ$im"€Ÿµ x%—ü§’Äæ. š TšH#*u{ëœ5å³£S•-’lkI&|Rld¾Kã|!Z¸„ÄNæfM­ÁšèçPM8èD1ka¢~ô &Þ©ó5ÉìÙ cÛÀz?uŽ™üAÄ\Eh4.· P6Œ§ùlqÔ‰þwñCšAÅo!«Ñ…ñáô8Ù)(/U Ï"K´= ¿¢÷1è˜-:a0² óLÏò:ÄæÌ*h³FI:Ívð>Œý¾lùìÙEͱb§!¾·%q¼~ Z“8L3%äVLœø4,^«_K>3Z MÃë=} …M¶¯Õí‹é¡÷DØ6M]®Í¸ gìêjöè^º~Ns_V]Bñj×.^-ÖmÈ~™Uä6>û _·)%\†3*õí"¸$•³ó9«¿Ê rúsêJ*Ðïö$39mNÝ®w¿ÒP]§ï©›£íá/ÀvžQÜ!½—c&,W]½O/YíI=†}å­Kùžöe¨ú•Ú6œ±¾¯V¤Gú$²ãMÃ+Ñù*ÇÆâªËÆëjénó÷ݯÍ»ïnnÓì–tæÍFÙبo6JÒXcY¶›TÙT1(Ž5ˇ?:ånl´ïVs56jÇþÊR.‹+gœbcÏ“Ì#Ô)'ÍRëJ]Ö§=ièö÷´95½;ýJ}yßÞÏCŸ;OØq TNBT”xו†¿Võö¬AÚ¶^ÅØhxÉ֯ԷŃõ=õ–é“Ú¾Ñ7^yŒÎW96§.¯ÓÓÓf÷Ó¯Ãá°Qøˆ>b£ß!½æÎX2h=)´Ôæ¿W3ëéhÇhÈRjßÐèê]ÞÄNÒvQE'#Š¹Œ£äcjô¢AaX{RbC}`T{‡ á+(yRØ¡,œ𪘡0C³nÍ0âJáù…ñcY^Š†‡:›¦Ç¡ (t çÝH7pCZ@’_$Ù)öqDEXMÑÌmð\ˆeé¢'‡îü9 ±éò×0ø ICvrðó ð„픥¼[ÄX”*7ëY®Y˜{ÐÜ—?2· Mæ6æß)ǵå7– ]%Ž ä·Js³F£ ~>•ØalçS² s›ÿ¯½¯iÙ­ÉÎr GÄ™8’gäÈœ®ï!$1ØŠAA!;øœ4i:øüAQIü Bö §MÏÚÁ‹´u]×ZUµïçuâ$“ðòžg¯ºkï]»j­Uk­Ztš…¾Í„G8Å° Ÿ££2‡ùh­äîQ²Õï5—.«%?wy8(AD–h®V5ˆèS‚fÙë<¤FªULžÃÖ@µ` ¶UŠw^¸È{5ÑnÆþžªH²º,Âå‰uXÙT"˜1˜ê ³«í–m⫾,Ë@G?ÒdrӜŸQ¦´U_ÌÙË>â¹ç7Zdl’ûIº¿ÈÀDï¿ucVÍÕ"÷Ô U¹àEî6n/Û c^hÏéqû(µ²U^>_å˜ c³JO 7Ëö´Kæ_t<íÒT‘ըʬK‹ãHä>"ò6†Ø^°›ËN‹ ˜(!É7š“¢ñÀâ'm¶òCe’ÞňIÇcaÈ·cˆâȲԢCÍJnŠ’^Á®ª™sÊ¢ÜE6ÖïV9qÃÝNN‹ÎFñ1Xîa–}èÇÝ*ƒØÈšÄä:¿¾ï $¹]r™·'B4·Ó!{kfÊ·‹bÙÊMÓHþ{wh0K>¹o3ûni<ìDäÑÍnàéO²:î²Yî6»G2Ž+ÎKƒ‹êoÛ|ŽfZ7tâ¹Û …ÕF‹Î9ýl°º}V‹qÎbîÅ™'%pÂàäYõ lK¶>2žü0*«5l¥ £Ìœ>Œ»ƒmÒ|êÇ` á´d•pÕë}¥ä Û·á¾×˜.<{Ç€Ty 4a¢fwRM†Õ°%§MòþýלîÚ§¡¿ÒøŒOuÓxÔ ÖEã»Åh\>‡ÆG}Òø†7ï£q«n¿i|Ä'#ÏïƒÆ£\»Æc‹5_4îµN`>€Fã£>i\î‡Æ7¼qh·k‡Æq¸ý qÉ8‡Æ Þ4.ï¦ñYž4>ۃƓî¼h<ñœót(åAãÞ4¾[DãÈ/~Ó8"ŸŸ4ŽHæ›Æ‘jû¦qä^¥ñ$sòEãI{ç¦ñ”ʃÆS*/4n Î7ã™'å ½h<¹ò÷4à›„g¥ñ™4>ã“Æ>4¾[²Ü4>û c­.Ç€.gxõƒÆSG˜ÁMã/sºi|Ø>žöTÛXÓöK&3Dy$/ƒ&¿—ý­†%Ý7ï$ÛÁÝÆ€lG¹ò¨ ·µ$YF®ÔÊ.`úznL¦ØÑ]RÆ,ˆÎot”f½x±¤¤C˜‹%í±$DÊ— lÉDŸ&¯i~e“và=˜Ý][ŽàñÚ4½®}Ú¤P;tS8¥óûtŠøÍÕa‚; (þ‡Î“m¼ÛÌ‹À]È­ÂÒÉ‚pLÕ$q.kÄ„Þ%ž²«ñÆ ¸Ò6°RÂÕÐÞx[2´(´€SNk(ÿ&¥”v`Æ,öJÆ(Ì3–ÇX·x7)îÏôÄm&ÛÊï`Á&fb²”m»1IÃ=ªY(àò`€£®Ú‹p#/:ËHLM>'ŽHoNÃÝ*£#ñ­ê8-w#`úwÛ Í…Wªžù™6¹Û8SÝß±ÙnVéõÓ£˜ª.[°k“ÃÜmr6íÝ¢¡2ϘNÕå3l6¡âîC9›}§[IÉÓǼW ßE>#¸Æän³¸oã ÁåÆd|‚¶óùް˧…D˜ƒ!—1ç`š˜ù¼*¥‘ÓàB0é̦§£ @0kÖùÍoÛÝ µ¢òÝÊÉ×ØFŸæÇV™%?c=åÓ,waÁŠpël{B«Ùv¼I¾9îe}d0ñ|v?FÀ­Uâ&AV É®ç`î6l-”2³¬·sr ¸_™>nm]ÎZrÑ’æ“««Ö£ÑDCý;»Ñ%…ÛÝ%ú„9¬ã^Š££ÒP+™y¤9×– ýY–àaê(Á»£?ò¿i8ÜW1ZB’cäàMCª˜°eÅÁ’›¸éI¶ÃL+E ¿v'¡å>Å«¹NO“Ý Ç™4"î¨6Ír‡Ê#I84¿rŸô,ïîN±WÎRxˆš@ŸˆÁ5YÛþ”“o7à‹NdiDäo…bóï.é¶-‚Ó|°8í|)Ë;˵Þ1o»Ÿ¹ÈÊâJ²Ët6®{u¢V±nÉ„ƒåcRÓ{cØÀ¹'?~ubmòÏŽ²Ò¦¶Ý™mkHä3r€ý%z[›ú,?$µHþ3+‰­cš²ñUùÿrr4©²íåBB•Ôl@µf6  ÊÝDœy£©™ |ÜÂÐÆï}Ú¨©=˜±ÍlÀæ`54 °ù£ ˜,ÑÉŸ Õ‘ëhH§pÀ¾~J™üA CLjƒ3nñÂiþ–idN,»; C ¢ìò6\Ó9 É€’iAi?Uº¦%˜ÌÈ`Îúí³m:r·^K  î6GV‚ÕøJ–» <’袯ï=žl%™]S#+t a[Æë· =©¦ LSúGb¹Ûx€ÅÆѽû!Õ^2S¥´r}éc*ŒÙF¯ÑV쌱TK^]šyÞ4?‹+ÕüH>¶ìÓÔ’ýòC˹+Í—'Ûñú_ì ^ß~·xu8—Z°ƒÎ’uHü--8–TI”šíÀôC˹˒._-ßþa„ûh¯˜#ï’a:æ퀬_À(@,Q¹È†"÷@²7ºrA$@ÖˆH‡Õ1)A?R©.év¿c0±þ—OWG‹ƒ îZa MMàBæ¢#¿Æ¹ÐàFU#‚ÕêD¢"ZXtá‡@Ì=Ï oÐ 7¸ƒ™©> ·Œ­g°s4ã|ažÚÛùæ¾ö`Á¦ðJwTÍíú*ÖñÀ5³í‡Åß;îÅÀz ¦aéÐ¥í–Å(³¶Œä×Á¥ 7\¼¾‰Ä¡Ý~ë Ëçz‰ ûè' €i|§ˆ-÷ðp–Ú4¼¨•çBUœB’\ÿ˜Ê0££¸2˜Û%¨eÇ)¦ØÙ1“¤äc¯Câ´­˜±ÄY,Újbñ1lýEÖ¯nÕÙ¶íUXÜLæ1ÛVöf¥ÝFÙ¿E“v0„œ„ OÞ„ ´q‹‹T§‚*S³lø€ è«C1ü÷ú£ µnðbjA_“(°r%!ZÚ0ß0Y}b÷@Öïvà êë(Þna¯‹;w¶ÂŠÖöÍfF¯®1µ YÅ3˜¥Ñˆåü6ܽ ·ÔH2mf RpFA¦Ž±Aô·$–»G‡ÜÝ •}MÜR­¼V>»ð |Ãiê¦MK¦Œ­.kEIÐ f;å-°Pá!ÅG5Ö\:à-(œ7ÈIê:ßô¾`žX{§`ÝÚ’ª±P¡Ú¹ßmwç É*9ïQLRµ ¥L¬Ç§MÃœ¬%ݳÔãšdªÊ[X_?w 'qUÌØ#Ø>¨¶«‡NHƒø«€î…u¢M¡u=*²ŽV!_B„°ZFèA’ÓXn·IhÃíÞÐÍT]i )0G3ú¢þ\×ù²@L\ïÛõ»Ÿí©¼jêa?®ˆ#4‰U¥ƒ˜2à¢]˜ýbº‰¹{¹zp ÁIít Ó$Åú‹f)›úb'ÙέQ{±ÚùêBJß‚Up˜H ¢Kì¹±æœÊbmÎð`³&Bç"Š˜O zò£ý{6q-&Æã{Óg«2‰cŸÝð¾†rp£!§'¨º@À{rÓõ­¡Iøïz£Ðºks…õ¿Žë÷idÓ1E‰R‡‘‘6\¶S’ÂuQõÐM¶náôfç,ÖƒÂÆP9Rsš‘Ü›ƒÓ±ˆ†.Q‰IàYÖ7šâ¦í™'¦Ö9r´íÍíl.jàÔŠN’³<¬S/7S„¹]ÉèàUu”áØ å_ÿ”C§YÊÖEÉ42^=.«Ú ò=PÍ\äÂíÊ&+xðnêâÝÃgL¬YG›®©*°ÊëŠ"æ'ØFË‹©R67 ÙµQˆî„åêGÁ¡}Yµ,‹aLû¬ Ÿ¥Hö0) ÖFq1!4àf–,I+§egª-ˆ]”žE‘_Á÷T5NT!= F¡j ì˸‚Qr» ƒ–íÂÔøåhþ’­aœéC:.ý+l:åÂÓÕªí«Ýi^8¡¼'}Žø°óýÂ\Éq‹íð£÷ ňTŸ§åýji”-ß?»N‹ÕZu¬h(ÂijTö YÂò}C<+ˆ¹¦pv•pÃ5‡fô‰Ÿû”¸ƒB€¶/©tÑ,*dZP2ŸÝ)cÔgqòâzlaÃÆ¥€õ ˜S‘A§R}̶ÕÔ¬¬Í`ŠÑj1ÑE>«{,‰b šôòî d¥N'¼³a²ŜǮiá8ÌüM[B„Š:±Îaëz™Šv™\%ÐœJvõî`& ”ª¬ùdé(&‰iΚ`ÜwŽ«ÇˆúhLÚcŠÙ¥VKs¥W™mØËQ"fl˜Uç‚yªâH¹È™§K.–Ñé´H9F´è橨…XÊ"Û©{®¢t0¡<éÆøm;i†˜Gl3¾(‚(=u)‚·"Ø,¼)‚ˆ+ØŠ`í(‚˜"ؤ‰¸"(ÐAÄ1ÞŠ ÂGŸŠ ¼üï±>Á oEp·Hk–ˆÊÕ¼–ú‹"Øry(‚ˆ¤ºÁ nEð´ +“8Š â잊`㱆)‚xß­ØÁÝ"E¡]—ž×xzrmXHß}+‚MV)‚¶"(ÐA~Ê¥"jñV›×=Š âJoE°¡”º+‚¸"(ÐÁ¦Ä>{'oÚÁÎVøÊ[l*+³ÁÖ‹"ˆ Ù£6¥Þ;÷÷ú¢¢`å­¶1"Øfý 6Yw¨6ó^pEÙ:oE°•þ¢6•Í<=`ûqEÐW[¶«ÞT$òVµfEy×…"dù=˜ÙN,ÿ€ÎòQCû—±üîæ|Š€Íò –/ÐX>ž3ëaùþ¦ÃòO ™õÁƒ/‰¬"rMØnÑ !iÿpOÜpúÙ%û¸'l<'l<'ìf[ˆâ,Y†A1îš/»¹ò5_PwÎü”/ßxÏ×°/»‡TXEÖ€=eϔȻ >]_#›XJŸ M0©Þ;шâgg«Úóa=|éx‚1áå³!1$VŒÚ¸1EÌ@}?¡™Eh¿8zé[½¤ýè›-ø+Ä-Ìì(¬PÔo…•È—Âjzý¥°™ÊígÖEÛ ëÐY¹+¬Æñ·ÂÊ“ÈKa¥å(¬8c¾VøD\ ëLD!*¬tÙ(¬ £¹VLž5»×¨õ‡Â:À߶ÂêàVX­ÁVÜ~+¬†9×'ƒ[aÝ3m ë4çÉ[a…ÍæRX­ëVXª—º?jïÿ8°½V¸-Ü +ho… ·Â:C|(¬, øPXOËVX£ŽÁ,0Ra™¬ˆ²?‹TÂÊ~ëÓoÛ‰Yd¢ö†´¹NT(CšõPHlùQª’O4x : ô”5 þ$<ˆˆð\ÈÆÄ,µ.a ÆQ^í¬o™À0Æ ‘£Ýé¦øJlRc—ØAò ¼rÝÁbo;KRQ»7lä $Íò® D2cœ,øØ¡²ñcðÈ b(‰þ‘§CPø°õéü»#³œ lÖʃî®üP ƒ⢪†&X.n ûpÔ R ·¼ïVXmj hv5ÀãÃPITpUeQ-Ã6ªQ®8)X XBa ßl2m#¾Ž7œ@8›%ÊísR‰i»GYèe²™®QF ²Jñ¶Å ‘(G¨¹Ë9Ì‘0¾êôÐ3—yÆ8ø±ÂrˆÈKô­pçyFHg “KMN…Ò‡oŽLÝÂÇ’GŦZo8gn*»[:¡F|ãÒ'Ü`å àl–Ÿ@hèLj÷àîÎee6—/u¨ á²AG À-sº "ÈÁ†–““ RÞ€ "æHÉc7gC¸9 åüçˆÁ&»@’.Q-A´Êÿگʇ‘3çôRµ9rf‰!pFNP«ÿnPšÔÉB–Õˆ7EˆñÈMjÿžèu4ïÎ"É9t`ð-í0è¬À Nˆ!²-M›ÂtÌ®%H÷n–!&Ovv•Åª1—'fÖ^¤D9_ö›«CÆz=ë XÞ±…•Q=86¾ˆ ˆR¼jL¡~V= õ/VzÂ7æ Ý@V{0®ìßsà×’ü{æINkÅ*oRbY¯šÖ‚H\#„J86Œîrx<=*­· ^›˜ç OŽ•õ“Õ‚ü&“ÏÄr£\¯›`r4ÌD°O¬‹ÚÞ¥q’„â…³]˜'˜ƒmÌèm>0cÉ|3Ì x0ƒ cS#\˜á/Ú˜a † ý.ÌPƃKl=˜à €fÌ~0c„tcÔfŒ0oÌX"ôÁŒ!Aé`Æ`škÇŒAõw¯ûÐxaÆÈá#×flxc†·8fŒÅp}å‡N®f@Ü¿0c„òÄ CÌ€|šµ§°¢:/°WÊ]‚[äöÅ*?â k*Çó#óæáΊr‡ƒ¨ôª¾Ü(ò5ÄœªÃ®ËI!,N]TÁ7RG„ʺ†Þ©l2IUÀw4 XS±ci7Ú!eèEˆ;?ÓÒÅbδ™Øâ¿C)×ÓY–\àú×Q —>UZNœQSN#ÇyÂÅÈ}v…›ùcšLÔŽCEp[ ,OÞx2ܱBüEÆC!Äõ1}øÇ ÎÂþvTì^ÕîFFôÜM­&6„´¦ÌËÌ?€É‡2QÂ’dòín [ʆ g$g.°õ½:´™ â¼…4…ôÔ{û$px ÁÃ[²&FÒH~@Âß³y‹5;Ï<—á†w¡ç¦: +fÓeÿH¼^²´ ú”KÃh§¹%`q‘ÞêOÄtGéIU ¢î–ÀMõš¨#8ùP³¦êÃ.²z²êÁ ‰â±o­ûK€‰ÌBbpõúÅ4=¡vª›6-IVâJ·k 3ÑžC/ ±Ÿ¥œ"Å ìÌ ±´Ø…#Á ¹4`XÃûi˜ñ³ÍŽÝr5dÊK¬ƒÑ)G'ø l'‘®m|Èô'­H “ÀcÂ:Ãö:Ëy!o/qÓäžÛUŒ[U‡³$Ì&®õ S«Óãú=ô\V%Ž®é&ÄÛ¾ÉgZÞ¸ÒÑ;YpËò­!¡öË%w&¸Õ8ß°÷{ohrg‚'Ô%wî9ÓóCø§Å'pXžÅ˜nzN=n¹SÀ–;n¹S É)ÉgÐäÊ÷£[îLƒ=ŠÌ„û · ÞÓˆ} 5`@;p›jÂC¨IS“)jµ .1°“ï#u«Ùp4[Ýia½n¼.oA3Áçi±3e9VîŸ! B‡#&º6M„íÀüŽIû%é¾Nk@0p4ÎÝ'ÐXeÁs¤23ëqé°n‰QîºFŠñª7ÅcgMpQ Ýåð„èÕ|ÄôÄèËr~®å6˜%TZÁ‚.Ä ¶`ëhÑú4žíû»íAûùŠØ¿Ï´9 !L£löÅJæYF5Ò…Â%”­¼¶ñÜ9–ÔßÖ“­´ŽñOrttÖ-ˆõØoRØ‚q©øÊ-ž,UAdË€¶æ ÑV u1t‡6CG”]«‡¡—(AßAà0t‚‡¡t†Îh½zº¿h3tk0^rò:,Å0[ÞÒþú¤y½*Ï[’%¸¥}ä‹Áñ-£@E”m­ñ&9Äú¥kC/k©jv™~’Ç–ù×&p˜»'å »Ø¿À-ð „$N]`t?B:Êß`+93¥ŸH¾ýºfjí3­ŸÍ¯Œ{¦Æs¦Æs¦Æ=S¨e˜9SÐóüÏ€ÂpC·»áfÏL¡ÞGÝS“à£CÞ)š³ì÷˜ù4ˆí¼>“EðLAÓZ*\FÎ\UðŠ«¬ÁfG?¹¿@«³ Øt+x^¥ o_KàLÁ£t!§²èo45’g}ȧÁ~÷õÂ);ŽÛPÈ¿+G ΃)r+ÆÌ þ˼n‡JômÚæ£Äí}›Év›R5Î…áEvÌG©âèj›˜oóQ‚Üe>JU¡&2%ámóÑ‚êe>˜·ù(±òÂe>bôße>JXÔ3+p¥»ÍG ¥LÚõ;âû·ùÈÁm>ò3ñîc>ZOOóQjª³ä¿ûìšù(5å¸ÌG‰…¡Ý|ÄY¹ÌG å,¶ùhÌÞÇ+¢i·ù(á„è2q*æ#¶óQ"O=æ#ÂóÑi9æ#œ¼ÙúbK@ÉÅC#²á˜äsEižÑ".•…e—òOXuŠH׉Y¼ÒrT准¼Ø° C}[˾‰†Îû±ú7€×7Ÿ–®SÍÚƳî‰^eš5ˆƒùЄ¨Ô¸H_¿­åÜ•¢ª:_-Þþq„ŠE]¼iA¿ƒ¨«&ß™_³°N"ô~ DWr$Å8ƒÕ®¶`·Âá“×Ðtå›daɲŒŠÐCÔì:Ö,‹Œ¦.šÈŠšŒ¦Ò—&ÀVÐ_ Æ쌅Œ:3Q•ÚS¶ëhÅ_á`#êÆÁPN„nœÌüŒŠ1`/ ¦ƒ„0 âC¬‡0¡ŸHýOÀPT‡(æ´B.]–˜ž\³Ô%‚Bà|7Ðå T”-ùl9°IÁÈp6%Ÿ†ÝÃlPL)EY—[Ï>­JSŽß)Ñ2¹Ú¹výžîä!Ùe÷èò«4O8Å÷G@sÕ1dâY"›Ðṋ”ZÅJ÷þRêb ƒ¸~ÏCéd‹p´õ‰©ò,GEä œ@1Mˆ.r¡´æ˜ó2áÖeÁzB½¢H?c˜æÀ±Wéà¡or2†4“ô®*ã?Žy€¸¨lš/¹…;ÃCn€åj^s\˜0óBƒKt.á-< áý´le›áòl"¨™Ùçù]“ ‹µ„SéL³C¶8¤ ›JeR…_l”o'?²ùlÞþ9g{¯°þß=”¾ )­*XƒvˆaË9¹M®¦HVÍtm¬0½À˜0Çn`CÞÊù@s•ãën€¿ŸN} xÉ’¡ïù'ÀqB3M˜KåMÆ μa‹Ã!êî¼¼Ÿm ˆ„W-WŒ¬¢Z,«$ãß–ˆƒ! à ~Q’¨ÚöïÓ§ä¨A-HtйR%¬C;$_‚í-t\Ñw7]Seø§ Ç‘(…»|¥B>±Š1UÕä'ùÆ/X[?fR@ŠvV#ÐåkÔ¨LB·hax³8È€Ë(£™ýƒø-ØMR&6ÉV-˜¹8ŠßŠ³šÎ8cJpwÑ ‚i¡—XËûny.*bY7Ý ¬¯ 1 {¦¶b-ÊdR 9¢i–e-jˆ:}r5¿o™Ïbƒ–«¡/{½³ƒéöïCgWpm€rôbtÍŽÁÚ›©ð1Y6•^êcSÁ„<7•ŽmæÚTß› àǦ²Φ‚(#ªÜQF ®­àÑ ŒD…»%lÿ¾¨wS„0‚öŒáèóy Kœ¶,‚.\\ûa‡¯ P+1Fuÿž›À¾Á¸Eœ@Åæx6´?Ù²)"Q.k>V fâ! Ÿ×ûè ߘ\ÔïÁ+ví‘tšÌ wØ,‡3ñnJn\vHæd˜ÅosòÄ<' º>æäi>2'Bõ:-Nî2'Û;.s²µ˜øÎ<Í3—h_ÃùF]c³§6 °h/ búô1[/¬®1ÛrƒÞAgUf~*p®Ò¨»Níç°Üèü¥²j™¬3PÖ;ò6Ï ð|I„zâ9,¼8f·À'FaK _&´éÈ‘›°õÝ‚O‡§ÌnXƒºÌßr2¾OHÜ„ž«<ÝoÄ5:Uù¹ó—2ŽY€áýÇtR# %bf$7D<ÖÉ <¼3]¡šGàz#ИlYñ‰Í¤Å›R>ŒƒéQÆ¢'¹r¶¢Á×OÕœ¡¾_ #…ph‘‰ia ^2Ý…®kVB£Z~Aȼ°¸*NG‘ÕwÆÇí7 0§ñ´dÐnxà Xðhn‘ȲŒÛIÿC¯JÙ®«¥½!„\à´†"ïDB•C8é߀i™ñ  q‹’nЪN“¼åý´ w½8ý¦«A&óÌ¡8!È®Ÿ]ûøªeâÔdÀTÊñŒêfóãõº‡N»Ó~Z¸É<Íèeæ‡ çofeàžÜØH¯Òd3²k$¹¾cFr<¨¡chÐp“‘øë'ìÊÈ(èý@ÉÎᣉ],3TQš×Qþ›¸†/7БЀM˜·e­c«tóœYS$àÛ=f7A°›ÂúT÷Õ’UpÓ °DØj×H\€ç šUí„X!÷4û¨È¬ðˆµ‚©ÏáuoQçéÑ4 –[f¡)ƒËÏCŽ“h¾Œ^ÉBص¦½ÑÈæàêŽ|Qø ï /Ì îr@#b-wC¢¬ÑÛ^j0Ìê˜"Ãï´DíYŠ[žÊXp æëÌctk…Á‰_?!¶F$Ùa,|ÿ4èZ£†ÅÊE_E°$x‡¿¬2ÙäéAâ種kÒ!îK|Q¢­µÈ°?'½ Ä© … ¯†ÊVÆnéCF²<•íÀ8¼!vx öÖµå#%Dã·CBÁa³"H^ホ8°ÆZI†ÍÑŸ°a䇡¨xµ°úbÀZ0´Yø0P~ K@œtæ¢Tç s14îsƒiOj¥g¾Ÿ“e`MRìܽ^7$ùßíÈþC,VéÊk¸ëoÁ'3›4^ÂYÂáÙÛRhòPU¤}€š”®THÌHŒ:ßúÚÞ2ŠðBKãu­:ì¤r¨†Œâ¬¿»|ÓŒ™ÍÆ3Ô!É™pÁØø%¶K á7äMÈ6ì±ÑVƒlÄžPƒoSþŠªªÞ¡Éÿ|éóZJìÌ1n&  P°Ÿˆ­˜/·¤ÊÓ¹‘T‚CZd¨–šƒú¤F„³]e4€®[TªOA`þ™«L”B¦„Á5Ôâä0è=Ë>B» 9Ç? ³|8ˆpàÆòÇ ¢Ä5ºv–OÈY¾Í“çùû%›éŸ²ù©Õ>—ÎímEÖäSsZ4Ã6§WpOQ¯¸‘é•ÊåúAÈe(»åýjÉYG箫¥H烫8¼xáÕ«QryŠjÅÌ ¢KïQ™#.þGªƒ”Ö·4ˆ;¨n‹Nrº å ‚s•ó†/<ô‰?W¥Ыê¿8i4‹(Šô„˜á¤¾$êQŒ/5•e(0KÚ-˜Ú-j0K8?ÄlZ¿)zkó‰êmúLÁßožI \3bÈŤòW塨‘"1·4—E ¿ ç!ràŽ¤‚›Û!ö_7 ü²å— (}Ø€ÒË”^6 ôaJ/PzÙ€ÒsÊÏ (¿l@ù¹åP~Ù€ÒË”>l@éeJÏ (}Ø€ÒsJ/Pú°å— (¿l@ù[6 tm@éeJ/Pú°¥— (½l@éÔ_6 ü²åPþ– þGyë9Qö*9vÝ8å«r·(\fMgÌòÅñþ®YÊÙ”ëf|ù´)ç’Ÿ×Pl™XØ@ çÑj$n>“[»ùŒ äñê1Tá †Ì ¨8ÌÐehgš-!^‰M£‰2ŸÁäѤ>³ÏMIþÖ¼õQõˆon›1 Yrp›MûVŸô÷B ¤™Q7d¦»ë6fµÄ*¿0õ#A¨}w”-cj4¤E®Èqé^xµ yuÒæ.Q*3úfš‹R¦uJC%"¢æ®A ‹š·Hc(chÜ/ ú£zÒQFcQ˜˜«v®V}ùjA¾Þf™Ï*¿àᛥå ²žð›“öRƒ”>”ËÀzQÀÖJ¸L{õi±9–»§# qõonGå¬OÉû{w‹&d¯+ÁïaÀÅvs¦ø©5Ð2T”¢/`n{þþî•Ÿßþ€¡9ÕT£ÚyJ¤ "µÐÁG(™Ä‘Q#fÍ[Z—¬Åëgâ¥Î*3A*‚˺á×>Á‚/7'_‹Ì€ÐmkßÅØüܪ«¼Úû§åä\yVgq;>¯Èx€"3€‚¸¬š6ìQáÎRª¬¶p_5äP3À…’-eÿoø nFY•é¬¥È†^V¶ªæ©” ¨ƒ¿|ÒŽuZÞ?-‚Ü“™\ñ(Í,˜[þ~ ÄWî;§e°~5LÊ”œ_@ª{™éߪnçf›Þ)Œ€«I°&’æ¡|$:¢X?—ÎêÂbr’`ô€Å9“E‰ ~ÿtîºZX»›Â ·SnÒ‘ªR€²„ª£R#SÔ,`0çk¦Á„Îü²ÑP•¦uû é[qÍ”©”°©¡.«ÊÂ"¡˜ŒÂÆvLdp¦ÒБO&Âg˜ÐFkñý ª}”È ‚‡­?Sn¼ÀläÂì/•vΈŠë´Yh.` ¸î$„…¥x>,F$*åm¿)Zhü<-š©Ìß@õGK–0”<~Ýß´–Ží7†0Ç8¥¾ò Q¦Ð6¢®Ʊ!¬äip \Ll:E-04Š x(ŪurðÀ1È_¬ÐU‚]‘cJº}Â9ϦÆGOßSØ’aÁ†ôˆøÐ.¸VÃÃÝG@¬öèÒ9JÒ/“*m(:&ÌUÈQº)‘7X¨sˆÚ¡†ûP"™¹˜‰õ€h+sü¿0xmi>r•2?:3üã´eÄëeÚž¶_¡ã§G+²Á°ÄP »–3@U”%?†ôO_ͺä fÇÁ ÁQ¡øNgÚØ°}V+W0ŒáFb°Šµ!®8,«°F‚o>…H"³´ÚÆP‹Ú¾p Û8Í­WÛkÙ’*srÀ·m[d³ÂÇô²·ÏÞvÃPÐpj/×¾ ì0Ùv’ûÍ‚ûy Œ@áÄj“Vè (12¹ß5P"±ifÚĈŽ²iñØÚ‡ŠŠfš£þ¢z«õêPlo©Ó¹fëšc|7þ’ûóÛàųTà3M»ÅæF‘CÀ3[t5ÔÞ‰¯îùš¬žïÉ"t&K M–â[8Y¥©¢ê4‰ Y×$iËfkhcØ“¢ ó1[ Èrz¤4]y8`Ẽöé"CݨŠàõš.¦»gˆ•ë„Ê+¤ØŒ7”*šò5 ¦Mãš'A5é˜Õ@‰I /ùlSˆ(ýÚ¦ÎDX_±¬“l”¥¯y4LèŶïÌ¢Äãs¹Ph®»_‘M÷‰UJcV¶›MþíY çY`+îûŸ•«Šû3bS!¬ûæ­@Ûf{½{ÿ#7ß=Ï„hó„ÿ?*s&>±ËÌÍBž²HíYxŠV –^f‹ÖT‚Q¹½ ¾«JdMZ –¾D˜>Ì¢0cÖæ§u nz<æñ ]öq_®Ñd6Üs‰«óšmdR¤a· MÌјÆn tÚÅý5Ÿ½#)kÁµ»`zûiÙÓŽÉTéË¢o' qÁKVprÃoöM®‚{ƒßß´E ø¼{Ìj>ŠøT雨~OÆð«!·®‡µ&µ8-;à÷ÞÖ­aý÷3(—iS•~ýô ßýôïþã·ùƒßÿ­OßùõÕíÓwþÁÛ\ÿþ¯üâ[üô_úø)ü“Oßùåïüâ/þòågö;ÿèígÖ/¿øý÷ßÿú»ÿbÝòs?÷黿ôöwÿÓ?üÎ7?úñ7?þÂÿÿ÷¿ÿoÿã‡í‡ó?|óõGß|ÿÏÿèÏ÷GüGÿê›þð‡?þþ÷ÿøÿä'ßàê›þø'?ý¯?üéúÍÿùÁüôþø'ÿå_ÿóÿü“÷ßÿéŸýæþ¯üçÏ~ôý?ýÓ?ýæ¯ÿ¯¿ù‡ÿöoýí¿÷o~ýçÿê_ùùOÿ»o¿z[À`ÌÌÎí?NYÁ2l§²4³2 leVZ-ÐÜi#HÑlV¥šÕ`º};>mÝ, ™ Š–„d-Ñޅĺ+˜\œšß©Þ}Xñ¸ÞÏa1ÁÇ»R·œ={<‰æ‚{ÌL2UïïJÝÞµ¿=!rlžù9}¦/Ïs&eÕq½‹9¬ïáÀ`m]lÈÌ®ô;öY}{°ú(ž´Ç§ÝåSxõ±i¾žcKqÞåËuÆãKº‡ì«~¾Ê1ã|¹Ù s-†D}#Q´…‰‚!Qw$9rA†#QöůŽDIF©˜òF¢¬'ç°‘ÈÞ…*à†Dn°KŽ8¨­wŸ4„<ç9‰žƒ÷»b‹ú=ž„xŠÇ˜*àÔû»R³wíoOf öù¹ú:@_Ï áH¤wY¾§3xµ:iÈP‘ ‰ì³FõÅ÷Ov9iz„cH¤)¼úØ4ŸçøRœwùrñø’î!ûªŸ¯Ú˜±¿Ü2sý%ý%ýÿ#Ñ+ö[É zZ²wBÝû˜­ ¶kwŸ}#˜%`+þrdŸÆøPïÝZ´9€¥Û—ǨiOv$³§«YC‚GâÝ#ñ û~H¢wÐý¢Ô… g0 µgæ5ÞÔ µ÷'%$õz|6“ø=QÉûÄ`jû9Q«q^µ02ï»ì@â|„†SN"ÕпûsìˉXººMjÐôb½æïêcs|žãëpÞåkuÆãËyƼ—|×F‹ýíß‚:ÐK©ñ–•pPè“Æz¥_5 h¡!‚Ê,¿·ðµ«Øy¦×S V¤$/qôI|£—×kMmcf>Ù%áó£§Ò+áÀÕÄý«%ë½°DÆŽ„/„:Uþ–-PœÑ2†¿“CƒÂÝ=ξvÐ×.Zš5q$ÌؼD÷ú“Y9ë«Å^Âa9ÅS¡£A)üwDR§»²üåЫQÿ‚™^ĴՆLJrZp8EP«Ë¬²ëô–ZRä´œ›¬ ‰ñ5ÏMŽ¨$z1ÚÉ@8ZDìª_çK}À¨ñ[ÂPôÖx²“v á‹Ò2Ææ-‚€&>¯Eƒ‡0¨yBWx  DOLÃV³3 ݼƒÖ#z{‹2É¢: <›A¼,9øö¤â“Õñ“¥.Yd“Ø%x½U][¹{ LŽ$K¢o`Ó£•a`½\(†KÂP/Ù&j¹ÓÕ¥/qe‘e‹j–À•Ø’P!F•¨ÎB­XõŽÌœêã%fõ&EdåLÝÊ @y‚)‚§tŒU3CÕÌæ£m%½G’w vÀfƒÁàA—¢©™ƒ¥*»:—À ô)A³¬LÉæÏeצ固ÕoeöJñî¡Ø"b©O4¬ÐSÆ|"é5Mpò…C¯P‡zAŸÝÇxM|Õ—uÑ$Túlã„Hw¤¢1W¦6beëaxÅÙ‹>â¹ç7Z`lN%ìµìªú³9ˆg«¯º†an¬H:e^ÙÜsø˜âîczÌÀ•Chj¬n‰Y›v_¤ý(M:¥"”d]«yľ)>¶[‚Ð]ž˜bœáf!/¢ãû 'YŸ®– aøY´ê‹3Ò¿ùmå½ßňIˆRA\Ò¬(Žì€ 3>;$3u¦ÿŒYSTÙß‘„QIœÜå|µLaÜ«i°Z¹“‡#§-Ú)qºF §9¿ÞwpÒW¢0J|IþùÓvObó…bçÔü9Mgž î† ú㘩âÀ³ÊË|·DfèʨMt±›õ¼&²r†”q¼BÔóA7êoÁ–d6qÕïáú;:º~Å8£6Ñ@Ï8jáÏ·| EsAÃE7¢à§`!ðe ƒZ`9V[bûÐÖ€QÞ”l3'Gƒ¿ÆÝÁv¤ÒD¯»àÕ‚2ÇÓ_ï+%y1 †ûsê Ç ˆ:r7Ôy"@Šæ9vLbKŠ;Éû÷_sºi\.§‡Æ³ 9Nã9´ê4žƒ²æ?-¤ñäà4Ž›o¿`£ñ«E±ó8+¼h4~@Ò8‡vÑ8?î¢ñ Þ8´[¦&½•›Æ3èê¦ñ t¼hüÀ¢ñLƒ›Æ30ä¢ñ ñ¢Ý$< Ço©ÇƒÆgz¥ñÑ/é¦ñŒóÔÆÝ!Þ4~`§ñ«%ãçtÓ8Ÿÿ q®ÕMã#=h|”WãIã3?iü9§Nã±ivÚT7m¬ÕDD±™Ì B²º©K¾œüZö·–Øn¹;$Év1 K?q°|V?úwÖ¯œõÑÒлuc2dIDVŠ¹kZ”ÚfIP’$D;KÚ-bIVúmƒ%™èƒ—KmQå­.xf·@×ÎÐ{|c¤H¡ø6䤀ÓæòvtÓ ­ß'§#Ào®P¦¡§Yšûçtè<úV,Ø`^œÇœBn¹üá$"˜¦e‰vrl&ƒUóªÍ°Š¹*m&ÍHþÉÛ’é ¸­I0È5œÂDû½»µm`AM3î;cyŒÕ‘ɳIÚÄeœr*OÖsRLÙFÌT³sqŽýè‘ÍB_9u Ô^„gî‚HR‰Ò‘Z·åO¥Eé®47rKXÌ럜€Á( €ï‰ßŒA/+,¶™ªÇa»°L¥‹1§$U=²@"`×&™ wÄaÈŸôÄ5½)7³ 쯈ÅôOwô>x öë¨D¾6·—ákø¬õõÄÀ‘"Æ4‚dà:Ÿ í¦è vá´ˆ‡ ÊX'lš˜Q‘ò5; f$}7ä€{5µ5êÙ"Ø"ãpðB¦àëÉèÈdBäÞ*“ÉÏSû=­~Æ}E¸u†=¡Ùl;Þ#g±áž…àŠàúî—”k•x£I³IG]/3íH®ïl-ò,eeZà6²](Ó] Û¶.c-)™mcSmÊ®JXyBÿÎÉ.-øvÊ…;œ0A[™ÇôBš@£™É"ô2Ê…þpˆéþÃX—£?sd]´¯¢+¡.Q¸PÈ´*&œ†±lé¾èÌ‘`ø S›"ù¶¯“Oy3 §Ï›â¿@´dv:ÈnÂãÔΤqS«6ÍCëѵâÉ |ÒÉŒ2òž#GVO@µmJ OD›Ú﬇Yê|Ñ9,‰¿åD±™8²Ù¶ ,ɸ8í|)Κ¢±\õƯÛý´g'³¸‚ì°¡åžE^3›œ_kÏÃ`ù˜Ö„ä3l€oµí_X™b›ƒ0Ðæ{ÚÖ A>Ó —K ™¦>Ó1ÃY'ÙOÙr4fΨÅH2êÁ5j rRiÛË™„:´í d†®©&ç¬@YqæÑøçbSHP„ÝFMíÁØì†é¡Ùδ¡åªE üÑL¸ïèg¡:²Ù…bÛ€}=®÷™³) Ðyè¡Ô6 §ùeoVtµëäJš4éæ$#‘‹ta« š=Uº{˜ÌTÈ@9†~IÚd 7‘s§·€}PÆc¨ÁQ;–-²q­)% *;([Êï.æpdvMx¬Ði/„mžê"8æ*‹·Ó”>јy²‰"áÂѳûÁ6­Žåà^ûÒÇTx v³Ø»œåkÒ³Bß0UƒGTMqüÞP@$YÞ—ÚÇ Q°L¿zÐJ ïŽdÙƒŠî…he»%*|lÃÙŽ§ EëåÌb–È É§b …'µ¬2¤c2µvŽw ÕƒÌn´hLYáwt'¶ð½jñkò…a@†˜è×a|³Â˜v¦ ö©¨=WF³.k·/¨ÙÚÔ¶¾ ê¤›¥Uõ (‚çäì'}5°wŠ~òˆ½²4íQCqx—OT—3o®v€Ú4¹V‹ú“STÌ' Kª§Te­ˆ-øÑ£b"WKóóçfG˜Å½X¤/›Z‡ù(ÜÙûÝŠ´ø;TŒ¥žñûЩ)´$Í*Zô”T¬—îF9WaQBZ6¹˜Âb#}WR+I¸ŠŽg±ÈÌ\¤r|ÊÌ1t›!z—ÏDb€®ÍÐH6 áólÈž/BçúÈ*Œûz÷èHLF¦QþqÛçœE‹‹¾“å‚ü*¨°t¤.›ÎlàeÈàÐ*–ŠùG‘âRö~À@·Š®¢¼ÀÎ9kV]‡¤X ½føµ,,É‹Šz~&L(©î´MÔlrƒßo`ºuZÜ-Œ£äÕe꘩JJ{ÿ+…ì¿C–[Ò÷€|:ª}®­5N½QlÚ%7dXE1•ÓÎÆô‘(Bø¹hªx²cM{&/Py/?³ÌÊGñ:Ø/ƒ­JC%/•NåßQȲ„ÑR¦Òs/î•“|B-ørÊf–Mdì@RéKBï”ì¼b(3h‚çÏ­3®5Ó¼®U©u í/ï5j˜HX«SÈ`ï(µiô§ArwU…ð`SND «âª+½i¿J×^F=+Á ¦¤£ $!ŒÜñd$Ã.YúÃBSGi`¬ÉÍ?$¯¡$ž+Ù•ÿŒó.Þ9íÚŸ)(+ÕAd™RÆË(·;wWuãZ(þ½Zpï…¹Df»!YýåªzÅEµ4S¥Xˆb2ên'À%%ïÎßu"H¨³Öœÿ:$• ŠK|ÓÕN¦ÜdáR%᱘Ï>@uXkºÐ‡ù¹u]¢éo„’´=‹ŠgE\¦Éä:”i%= 3•’x$^XÚU,E×4“Òñ~ó"Å™;n`R+.\]}ë¯Ô£%£#Ø¥1öÆÙ)Óå27ônPif¾¬íM§E¡&2‹>#Ê {9ËȨf«~nB"8Ã÷”õ4ˆ4´bÙM’ðà·Ú2Ì’Uª&o-¥\é ë1„µ„ªNe ÷Iô‰Šh¡‘’¥“¯ç²>pQ*TÈFÝš}]›©!„µ•³ 9RAðÌfÄ—•VK‰Ø²•šâv»£ÃÔd$U+?¤$ֱͪ›´ôFXFo(Ðò¤·ÓbäU­æíi@ÊEo(:sè i3ôV)óîTF¾è­î2ÀNo5Ö½anzCÒ‹½Aºé­ðq¢7];½ ½„‚z+Ò½ÕØôVSÝô¦k£7¢·ÛMo•a‘7½a÷ºé f7½Ù"½-~Ñ› §°Õù½PÌ¡7lz+J@³®z[¢Ò ½•Ñnz«< =Ô´—iÓJ3ÝôVkÚô¦k§7BFoX¬›Þ*Ü*ôV`+¼è­Œ¾éM×No‚Ho…±c‡š*ŽBô†Œ77½UžzƒÛí“Þ€Ù7½Uª*¢7ˆøßBoÈSnBs„™ú¸…ts!D×.„ÚBˆ I ÐKñwl!ä4PËñB.Єîê—±Wéú!uŽ§Re31¸öîBˆ.]`$!·\BkZßB+Sl!d‰ú[ѵ?S„Ö1ßBÈË(}‘¦r€ÚBµ¢}¶RhK…:"ZkT¬CMx­T³K_(B{¡É3†•HâÜÂó~Ç^ª«‹ƒ-œ‹ ­Uá¬Óì[áѵ¯!#w‡h1díŸ@4£Õ¿[¹º[ÁôW±ZŠ—ð&ƒ©:nïé\a|’Ÿý(Ri02ëºØÁ!!à»A:Œ'â'•;?âoÄ|’®ÎÊèÎÓ^@Ÿ$©4§.ýo¢mQ×>I„XÙŒyí 5ú v¬V{çA&Ûºloê¦~{‡%KNéu*½1­ŽËn¤tvœ>˜`Èß1£M¼À¾Ar=>·da§j¤fl=?É2_ã:wëI(qº”J²(D}¿Í—uR†„ÚÓh óÈ 6™d½Y |ý:w³òY9Å«ír©B>v18S\ 8Œ¶;ƒÂ’!7:Êv$Ç`&eó[fŠv¾SåoÈP¡/ìëhó.HvE¤»G*ú´dÊ7e}3àË'æ)ÆÜœð½…~к]#w5z%㛋RÐÐ)iÎ7¤¤”Ñ”€¿º6&ô.[X=³‰aS]^ð79-ƒˆ°žʤÝþöT®€¤ë ãê‘ÔŽ¯Ÿ–BÙµiAgˆ”7tÍÀN]–­£äÐ.¸æ€™ù‡!2S¶ÃG\K;ÏP…1B3`°™QíºNQ,AP _Â(õH*ß².0¶9°=ñ¦|Óu2£µA °^ó–%’"ïz¶Á–lùåQh8‰¹Ü³K«l¡âB´ëM9„sV¹ë‘„0oŠ – aÐQ?%»yíl[„(š[-h0/Ãõ¿j‚,‚ßåxRXÞ Æ­Í"V;¼åóA~KÌc;Wˆ #È ¦£ºqé»_˜aŽÄßjÁ3±è:Û‰8!Õ–…ÐŒÚ/à*Ô ›Q* ²> ô M°–¬zrV}’\½ƒ­O¤Þ\ˆaèÂòº7Ù·¿?X¤!ØçÞxꎎ–ï ZŠL³THýɸIH Îò³'ô~ ìº3T-̧T¼ײ?ð:Zq'BQQ%ï%a`b† v¼ù;b –RË8Àâ[×+¨î°²¨&Hb –8߯Òun.üAu%&⸘§3Úªtê¾\úîðrXÚ^A:§Â-þR£~²×®™ú"?xÿJïœvíÏ4»ìˆ•È§a¼ŒÒ5â`J m‡­•:`ÞjW1'úQ'ÃJ5»ô…"´JüŠÛ\°PPÜü{©N §²”Õ·€¾VŽÜ¶N5Jd¿öu"„\Èþ ¢¢ åhDÌ}¬R–†°ž+¦«^O‚w žLÏ` l"MWl€v E‰Ÿ½,¼þtÌ— ðÝ :ç3’{tM*x&é´hV¦™î_Á=I¢šêà“xj®ë=Iü¨`y¡eòeê•™4ÜôUÆ ƈä…ìr2Hæ<Ô8˜–Ò%üõ¢²tÀ8«²º¡¤mN‹<¿Ñ2%ŽápGúÅlÞBŽŽzpoNªãìp2iéjiÒü ‰Ì¸M§ÁhARÔa"½rL¡ßµ"³/x6÷›fÖc0uŒ„_2ƒª½âZ¾CÐðæE4‚ȉùØú+66쮾 Æ #C«¦F+bÈ“®®5ÿä6Me‚Ôܸ¹’ÝcÚƒ(»›–fšÇ3(4† 2B8:]p“”rµh4>ñÀoŽäî½?Õøm(ÎÉýðd†Â^L•Øy^«ßXš¸ï[äb¬k¢5•šfw¤Òòª³¾ƒ¸BJÃg:ÞýJQO¥k…™3 „ßî 4Md¹[èÒ[àÁÌŒ”ˆ È,> ,ös×pY{Óî‘©N—¨2_ªŽ7~±Äuä;ɼa{DÍN †ÄÐô8‚¬Çžïß r¿À •õØ ´f U T6+ØØ`—% @3ÀþS£å*ƒã„ Œµ¥kÏKJcDãrdiŸ*U†&4ÓvSmÞÄKT曆] G ÎY’˜%t%Wx ž6Ì¢æîPTõˆù—Ø_ $w«&a¦óF/jmÃz^Ìémʧ¨À$‘™@ÎñJeJkx÷&1$ù=úf#‹!Ú䂈QbYšU“ È1uex³ß=9dÕ! lŸEOÓˆ†•Ñ(‰¸¼T„|è8?3‚¸ávÆPº'ÝϺ2Õ& ##çèHþ¯¬¸-q¿Šéu†x¯ÅmÅCâR»1©(Aã£Ö“;k’XÅЂ2“eƒ¬Œ-_öÝÙWu—ÝÒÅÜC–áéx>!ŠÓE,9í×çž1µTïVúj³n9SÊqtÎ.òAmËÙ¯õÎ ;(€£ÆPbz~ª6çn´£uupë­ ¥F}(QÀþ Aï¶$_ج«×­Ú^ìMªáª# Ý‚Ó3h£|¬hiÎúe".Cez©ÃÐ+ 2b•r|w0S*ƒ•ÒðÚb†|ûÆ!Vðãdõ˜«yVŒãº5©LRËŽÉRzoLŠÊ2Å2o9ŒþÉÞç=2ÅafÅ|o¸;gÜ-•¢Í$1Vˆ(iò g…-2Êîˆ[]ÛTåT>³p¹nmô.iù+Êdq5!¦(iBäSJö½ ›á\™¬+5˜e›€RǪ/A ©±Y|Äcýíq8Þ‚«m»üŽja©dTXÃ;XÞUªÈÿ/8Á³%§Í§kˆÚ:p¶¤a@WôSîš¼œ­Éi©iÏ¡¯LEdïµk׶;‹‰5;  Vž³–MxâLn‡1Ìù€Uf\µŒÕRí;Éíuäæ^<¶dP‚DÙl ¡"T‰é¤•á¢BRy$•¿FÀ‹Š‘Y É’…óùþÄC,w :Ë» Ù0B…¯a겫7߀ô/rÒ¯–•„ ¬,PoDQ#A™Ÿ; o…fÇ;‹¥l¬4ºaèçÅqß«¢’ýê§ 6>$y†³¬h˜RÚÎQe-yxÎ3Kð·Äí¹pM¹^È ª‚ù ‡*oÖ8T^«VQ|E•|ú„íŠVè1Yt†-µ;øCó’Æ5Âu˜É 6„øL8ùj¢«öÙ*«X RÏbxët~­8ýŒØƒ·4d‹ ~*²HE²ÕœuhÅV3ÓÚN•Š¦çø|SÉC…) /£˜jvo³3YKß` œl ©èᨤËk0ÔÈŽÖN­CRª$òJ~¹¼–ï+ç->³à¦U?ŠÐ¼ï;¾‡äIB²Ódx݇“#¤:®õñ!2a§À[pbA!ø˜eíƒ=¾£7eúDKPaàh³.v ™Ü…J识ÃKK’C­”™êž·4Yº™~š^ôWC´šK¢ˆÈ$m\*8-âuŒãKª2Š¦ˆ6÷ó¦•&ÐyKlbY‘—¾Æ<6ºqÇ\ùàHf0+t¬ ÇaĸjY0á;{Å1± ªMWÅ tr?lÉKD¥õë:`>(….¨q꙳ßEˆ3åqæ°Üq±~»»-ÆÌƨGYeu¢a;ôNÊyS¸7„$Èx{”?pÉS²öEîÈÆÔÉþzèŒú<ôâ.^ ¡V>¹k¢Ey1c6©h±-•Ÿñ†’áIö¹FÖN‘¼Þ„|ÓLB)!«ƒQ¦z™BÊbÆóLT(’h³Ï(UihË-n”À´%ÖF¶ l ±"¶8 „×é “Q¸ê¼¡tÇSØ2H€"ÝÂúâhpÔu¦‡)?²°¡6•h”ªþ¼®|ÿR±4šÙOKÜšøèÄJÌû³GˆµÙ윪Àȇ½¯|ÿ8Ò„šŒ°:h50‚x@ª6üoAžNœÑ= ž” Ç ”Úè†ç¼玃Šê‚Xv:fÂ…o½#v(4a_SM%ÃòL v40A\cKÅçÑôñÃö´žXÚ|–«ÅXs¢¨bðpuÎƘuÞVYÛK3ÍëlDM‰EœÑB¯ç3Ö‡ ñ{ M±ó˜P ëG Û€u…s§üèà ×Íó\sO7¾ZœCÔñ\»ÍqÌZྒྷè%3y²Úh a îjuìâÐ8¦!KîÎÃ+müñô@œ7îÆsq}ž /Û»pWkg0/Ãu_LD›AôÒjM9{Ør9´× í$:iÉë.*š§©\•­ ³^€ZÿnÜ`ÖzuñI˵`ÞB7Y;›{ÅÈqmµ`©f6óÑt½W ±¨wè™ÛpÀ´ý¢‘b{m ˜ÐVx²‹ŽãÜ®p{Q”X#êÆÃZSêÿ±³Ô×gÄ»ó:ùç|lï‚|Ô­[1Gq)‚¿Ÿ¹Ù-rK|{nzè[3YZÚ[5y¿KS±¹D•þ AHOV9{úÎŽC]qOßú[U‰;ï€]¦K®&‡qÔ²sKø¡u`è'+òŽ,OwB+Â$ÁZ’,=4¼DŠþv©Ú}p…|ã‘ön\Ó•‹eDäÎö.ÈkáèXóù”nÎùçÓz‘cÕî‘M܃á²¹Ã9¦ì–$Ò ¯*>Qc/–ªUàêÏuº:XÆX¿Ý@ îXý½A2u— Šê Rræï{oGˆv¡ôô†7±«ŒÑ”{›†ÂüJ‡é³3÷¢óê=ŠM…õÀF£¶–r©Ÿ²qÅ4å±âý89ç[ƒü*»é`Ó(L©zL“ïúÚ#á ×ò2à,ˆ)~F#~‹ì2Oã›·PD›ûŠñ:ßx¦‚˜‡#)D"S‹R)$fü/ç‰ð‚åö¼ß0’K ÖƒöHQâ°€;ßW@ë•Ø¾¿®É•ËS¬„ú59 &Bwêݶçì:-¾³¶{´¸ù.¯§s@s?'H')vEê›f#釨4¶¨4¢Òø *KT/¢Òø *‡¨4¶¨4¢Ò¸D¥ÑXHÇ¡ñ*)ÍIi>%¥yIJóURš/’Ò|‘”æCR/’Ò¸$¥ñ”Æ–”æGIibÂÌ =Iɽó"wé-)M(ò&)ñz３~ð¾órLÓ3â–”ì%gsñŽuÄ#)m`ï-<û$%|Ç~®/I ”OIin«”Z&ÂLRÂõ‘h™¤„»P4ÑÄ º<¥)’==zÚ‚¯ÏcáXk‚mÛGPz­çš Õòh¾_?1M:ªñdå+°']oóyFÔ~§ü5e³<÷âÌßS®Ÿ—RvîÀRäÛ³eA,ÒÞëpi´³jçÜøž°zóÂDž®Güt‹ K~ Ñ­œo Q¹œÏP4Ùé‘úÏÖ™ëÕŸ,¾ }YʯÛnTÚÏ¢¢¹n`·’*ÇÄ/3D Ñœ9ÎG<¿Ò×lÝHlÌ«œÚ6´ÉÅkÚ–s#ü«]аéà!8‚.ëò1˜(“uýE‡äv‹ÂêÛ½ÿ6Í­–° n}Oßr£€Mr·¼k%šBBÂ#ñ®GâÐè¼1Zær“xÁÛ8›&Ô.x\"oŒ–‚~ÿLK­„^.õ:b¯À=~Uÿq6·{ïy²N 3l¼gžÄ·' ¦I¾®y¸e_A~±y09“’³Ýb„Câ%üF”cC}H~7º=…_ ¨2E´ú*8£|9:é:ˆ€A [íÈÅ[Þw “Sñ,¥ïjRÖpœìN+ë^òKg›D+Píe0Ð/Z!d‡$¬hö¸3Öjõ+Æ96ùÕOÿ׿)Ýendstream endobj 6 0 obj 49015 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:02-07:00 2013-08-20T08:42:02-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000049319 00000 n 0000050889 00000 n 0000049260 00000 n 0000049121 00000 n 0000000015 00000 n 0000049100 00000 n 0000049383 00000 n 0000049424 00000 n 0000049453 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 51059 %%EOF ast-8.3.0/sun211_figures/fsconvert.pdf0000664000175000017500000004440513004147321014517 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}Ë«·KvV¢²E2Gö9fŸº_ 4!£fÂ&I·î/M:ÆBtäÀþNÅKÒBþ!Ï œ6‰mà¨ízžgÕå·¿AdÒçð±ßU¿÷Rµjպת_x/ñ9àÿûúáé“¿ÑŸîŸÂKm¥ÔüüsO%§üÒës¬£¾äúüá´ôhOÖç’Rz™ƒío s }Á¯OiXC»åí)¶l/K»¥¥—ZÃØïÜ°õõiµ¤\ùäÛn‰öH­ñy½s¢së“^ŸVŸ¾=­.Üãñ÷,x}éõég¿ï)©´•ˆ>œ–ÞØÍëÄß8Z*r±wnØP‘íÃeîCEXÈQËÀ¨úØïÜ°õõiµ¤Ù5œóHÑ«ü•½,œé£ >Ô±Õb(ñ®¯–34½sÁþQ"e<ÿ²!æGíßßy Ïå»z@ÐWž~â^H1G-“Ø|!í–Ô+ 0% æÖt§­WE$¹ZÞžrÎ÷#©$­å†ý£†ßÕRGËÛn™± þÊ‘ø†õI_ŸV¯¼ÁæÇ»í kTëu{”þÁ½œb*™´àÏ8-9 RE¬¢Žbï";³áק<}4Þb£IS¼ž™ÎiÖ;ì_µ­–0œ=¬–9Dëc ë« ¶w„Rˆ”¹¸ÓêûjYc[ïÜcõ¯ - +ê»xyÀ בÑKxIÁ~Ï_}Êö›á*¦_ê4 ­†l4˜ð™<ì-=>´Ä—ÙÐçË°Î9Ž—bp7zÍ4ÚŠé¾!½´9õ‚Ÿs³æ8…—’ñ„qˆÙ’_F{¶ñ½ôáöC?!ЈÝú0Ï 7‡ùR‹®Ó(/ö×î$Ôà ü"vaœÇþæ_B^:»úK@e /Áºaý'¶jx1ÈÄZÂí¶ì¹szý0#0e¼¤SÉVl±':¯ð¨ëhhoDX‹1¼Ö ñ%61ÖI#ÉYâ†íf㨩¥sG*/-6²²îf0 ~Ö”9hûg ËáHÇ‹ax³~…ò2:Æ™ãËÀ'ÒÄÌœ–·ÓA«hÙO]-í%°Á†Ÿ>Î3ú‰IŠ’Ò†Ñ/£ó¯;l"24‘!J1‰=éš¾„nð‰ ŠÍÙPŸØ—lvŠ-Ãá(]B[‹+cqÊäHÅ_òGPÄ„Pá(\¨X¶,Jäµfúu¨àö@)$­^BѸ«­|¼Âx&àˆ—¯oÄ@¯û£¦[áÑZ]?‚ºod5Ñ}*Ï Vo©ºöN¬1SÄx±Ùž@Q˜vÎÁËÀšÃZï춡_]¸XmdÓæ¸Ý°u¡Ó¢Î8Þ1TãÎÅž8ã=ÖÝÂÑU[Äi|H,V[ôœ`5Ž¼€—Ú îbu`\ì‹ 'N ¯îdg+ˆ+dc¯(v+9=ÈÌfí"Ý"‘MŠn¶¾ÈS‡X«FîÆl¾Ý`–úW ½6óµÓGÏÄ|ÁÍ”/ûÊÕPÀt«H<Ô¨×8R5lQ˜˜2›Ð­j 3ócj¨1ÂœÍÚÀ%¬¥v{‰ÅÐõG‚¾‚N‹­1c[Õä”÷š«²BY >ª¯öhÍ#?-DMï.×}&·j?¯†dN{µWÈ]á/_ö¥Ôz[Mje<`²|x ¥'µ“ Î6†8{ÄÆÐ"¾‘ØRû~ìæÖ #¦0P¢˜­ÆûI[”¨Õø3UýÄ{:û¡ë)¦¿!ÿ®B^‹1~'Ç1k•7ô®žŒvÓíj0%ÄFÛ]ˆwŠ C¸ä‰Ã@Wö¡ù@~4Ô¥¹®ƒw™P¥ü’#ß[ôIÏB„š,©ÝÁƒ)[X ç ©ç/Ê“´´°mÔhò ó1&?\À« Äõå K`RX%܉ ka©¾bù-@5uò‹åùZ”Yv×j7£‘Küûƒ-ݱ”?z'6hüØ@»9†)nžž[nÎ̇_ÒÊë¡„ð-€ÀòlêZvI†×Ð-ÿ‚s¼×óM±´fk¹I yÉáZwƒŵ6õ)“ó¼öNØk ýS,µáJnªzδLN›8뮩NZ0fGPè¦pmË"`T§úSaßü¡Ó`ÆdK²ö($\…àÄÞ?]{ÿ ;Ÿ$$9ÙlBiãÀ¥dÌSHe§ÌˆMS`· T½1ÓÅà!5 º"ùO7.B]ú¤Q[‡ö5¤ž˜Œî¦DÕK;Ù¤á-oN1Q‰»w[k£,¶u ç\ÝðKÎ⼪×"%ߺ®€©a‚ìåceKI¼bfQL±7ø'¶HÜ $>›3wàÿ*¢\ËÏ]â¶@Pð:™P£"Èè¡óEš¹ Êêб9(ã8ö·›\”Ù'Øžµ™—¤\wtuÃ5Õ±Û TŸ~J¨aË·P‘µë ¬ÍéÀ”¶ ÚíPÎÃ<7ØT’£Ÿµ¹ß É „¹Ü ]vkÜSmÁ)Åat¸Ê­–nÈ«¼Ã)fnÓ€ ‡*9Ic¦¸Ô•Qxš‘V 2*ÉÉ¥MëÈÔšm`ts™O¿Úe­p¿#ok×fOc>qgþZâ‡ò¶&nßÃ1ìöäÂ_°áÇX4¿²îÈàVÎMí«6 ÕcêÆøG^ê!=QÏ£¸Ôqߨ2'Ö&Ì CÆM>$öê´tp”1œlŒF[àýmM µ"|2HÜç¥E0˜Ìï·1€È¿v`{` ¼uǨ®·™x ã‚Õ]<±Zd§¿qHR¢+û”ÜÈÏ`†4#ÏH.Û^(H‡Ýçf| ­R[Šð‹øµq7 ñ‘=J ÕuÆÈoÔ%t³Åy†n€þÜÖ5„£ß.¥ºè{Œ. Ò­áy#{›o˜F…íáÓ”ï|@ÙäÆ—^Êó´I-x›_¶Ä~Œt?<™Bë^Oã˜N³ØªwÉ8Èè´B¨!¹)¡ZضŒ®áh¼ ƒ–9Ë")³jçpÛykUÛìæ9ß0h&ã_ ³ü™çrß’åÏ’´ º^,_³|ŽIOÀØ<d3ýÓB6?û»ËÅí§Ñ6Y3{Sç+Ý1Ä€ú¥ÇÂ&ã n!Þ°ê&¼÷³/:‚¸Ð¦M¸Üô£L›oj{Ûýöùz~Ÿ.HŒ8t]#o«soÐkS¦‰–6¶5<‡èb¡f·A:^Þ Eôi/XàânEŽZHZ ±dÀ¯%–Šµ‡ “ÐÔŸÎrð MšQÙ7b[œžb¨´Î5 U Ä•_;²¹YËwŒºÑe_1A{ak78vì¶üD]3†A'^ßnÔgúpàà‰Œ­·J鉡‰vIë`‘±ºdÑAĺÃg ÂÆ;ŠcÎÝ¢; l‡Èú &œ_q^Ÿ˜£ºÂâwÀmÌNïéYñë d´iDG¸b?<Ñù„ÑñeŠµBض®ˆ×&˜îÔÜx»# õÎ514Cà¹x¦_‹ŽšF5„,ù´G“PÉ®ýäv&#k 7.£5¡«gºlh!û7.pùwOK`_ð<)V‚Â@ð‘,¯Š6ôyÝáh‡ç–}ê]c´ë1]† ³dNSªœúúˆ²ùB¯¨äøÓ’ô6Mò…î;Šâ+4.‡°Bo¼)˜eªF]£n]¶-]ℹÚKÅDûjÉ˶ø³åÅÿ~û¡£K†+„ôèËOŸ|ù¯?ÿ½¯ÿÒÏ<}ò“v×Ó'Õ¨öé“ú±/=ǧO~ø§âSø[OŸüÈ'_úÒøc?ðŸüµçï·_¾ôµ·_úðó¿h|ñ‹O_þáç¿ø¯þç?ÿ›_úg¿ÿk¿ñßøïßøÎÿý¿ÿýñ…?ùÿáïÿÁ¯|ñ ßû«¿ÿø+_øÞúÛÿõÿÁ÷üã?ýô—¿üüã±Ñç¯>ð†á+CõN ˜˜¡0OÆ—Ì,«tghUóÀŒ§´ûúöË}Ošýáö¯"†à-!yË ú¬¿r@‡«Ú?º`ë†wlµX7¼ë«e Í_¹Gêß<)!Ò=¨%,¤xK¶Eœ”䱿Àðsßs˜Ñ ½Ü[€”˜ïgTªzÞ¹aÿ*â-apo»e*м^9<ïb}tÁ@JÚ¼HQ×WËš¿rÔ¿I¤|!7B>/4 1@þ{•±ÑÕ‚XŒB¡`ü¹?¶ò7„¶Eo‰€ÑŠÓ#<λíbP(Ÿ;¬“z‚£Í±PpÔˆ£ ÁÑÏ" ¦|=‘B ”SûjxÊ•Ô^6£¤¥ø"ïš [@({ˆúєыihQX3•`’­ÙÓ&2ôåh ’ƒ¥¶Fó QÖˆD†›€Õ„,WœË2-Å#¥ í›îY6Ìn§lÝw4Ä;iÿ PêÒ šJ¡ Ñø Y®Ô¾`·0NÚ_h=Û$}Àt hžÞòvZ¢Tt¶è©»ez 4(PjHìê%§A¿´av«º|^wt˜5‹f‚)¸ WÙ }{’ÌOÅPÍ@(§ÄUξèpÝ—ñ“Àh1C¥m9 V QN`œ¤XêÖt!0à ÝÕ­ÅJ¡€¦´ÉÎúïê ‚¥@&¢Ý&ÿ!{mkQë-¾#õ¸0eS©Ü‚è1çú"j§EjÍɦÁ¦X‘ÔÝY‚JI:ŽÇgÈT|ÀÑœ–a€Ð üLú"Õµ¼]-ˆß?¦è®XÆL30*=N׌ØPàz+˜ ŽŠøœîóy©8˜'ðUy ‹ì[[òS‹-k± ÷ÕâºF”¾ƒ<Ô²œ‘ÓÀ•1–áãqAí*’Ò½R‘1oÂÞ|a ÊäO[-4è3ü õs@ÝÏ…×¢Y6 ÝuêÊÆ€Q÷Ð0mžéNY1TLÊËp‡c¨ÖÒ<ˆqOvʧ¶küä‚»<'W‹:´&CO†Â8ï!ïÑgð#pˆP*ƒ0³óZ¾ÛôÛŒ‚ø`S•#¢_0,J„#Ý ‚Éä„N‰Â«|å2sûEÍH? D`&#'É©ÂŒ¹^9t‰-x+3U†¾ó ©§LfÌe1ØÊ´“GQ£|Ô"L¼()Šš‘¶Ã.óÅ‘oU×g0Ö? Ükj·24HÆ4ö:ÍàÙÊ(FÆ‘#`}µ7‰þ­ûz߉¯Ð*ñ·9Êsp`SšzE)òŸgšØIvÌl\Ÿžõì©…üRÁĦXj¿ŒGÖï|tTØ+\J'·³ÀWŒ°é)¤ee T ÿ­Èúb_$ $ ÈZC¬ðX÷Ê_–#LûþívÃM1ÕÓ‚”eàaJÞ7Ê—Ì0㉸ª!®0হ¸zC°HÎãÔ4òÐgº섽l¬ß6Ò)< ¡YŒÞÔT8â!óã3§†n Îr†œš®.LÏîR¬‰n~Í]YN+I… g½/³úôUº²[µv‘^“»cñbØi3û‚úž3gˆ¢›™Œ~8fU\U ¢+Y\`y¤1…È>ŠÎ–zæ_q.øz¾ël®Ø‚§©þÔB.¦ƪÇAè%.ÿx^€ú|¬è+B¢«d)ÉžñQz„±Fˆ»\àJ2D¤9”Ò…eµ¼]-#)˜zž:-y 8GyÌÏD—¿ bÚ{%`w¾0_:ò9FŒ±ä±Á¿°oäå¿a½H'Ž b&Xý³;wB‚L'ÖhÖ;¤Ñ˜8ÏÈð©—B³IÅ[Ü’«u"ÎÍþ ")e³µ nÎV¦¸Îâdeº©ÓŒ¦¥–¤ŒÖ“} S¾†ÁÖAÕmèˆÎÝ"ª©6·¹ nm¡¦îúvAÀÁàêtT0§4A% ¹:XI®æ "agV~¹ÃL×’«ëã Ùõ³.¿jM.Ъ™TŠÑѧhð”¯ÑHü‚™mÃxÊ~¼î@0Wfˆ\ðPäõ´4f fä 9~Â)H0;_âuCfRÔrQ¨õ ½æÖÔÌ8UâÖ’¼…c*öj-òÉ-MªYW¦Ãà‡m™d‚­/­vgëŽvL@ŠÂ¯IÆ_”­š[ /nÎÃdjÆ[ÆípÌÕÃXϵ“©‘íâÃ6jž–1›ëHR-sž­—³l˜ß4OÖ ‹87¸+þzZlvm’2’lš»ö!¶Ï’üÀô©‘F…2D+þ´Á¥†ý…ŸSä¨;š¢{§»£©%&óœ;̶җ=°:Ì'¼EN€7 Š!Xû…½ªr"(ª`xì/ŒÞ™±S„·>ä#ˆYÙé ÷E¼ù’ú]¯Æ†ífuº„Lwg&º£ÅN-bÐ bç• Üœm9È-cÛà"óa½ —iû& ‡]wØdpa”c 0â{¬‰¯gâJ Ä(-ìqL+2”VÄiÀ1{D.(ËaµrÝAo€Œ"ðqL-1‚¶ À™¥e Íç6 ×JïÜ‘`@TßraA[, aˆ¢×ÅB“Ô JØb¡)­ÆÅ‚  xÍšYˆÿΑ «AR £÷õ=fF2op:Ÿ€MÏÌËO²,‚?y­Ä¼9+žt£}—hÒÚëÚ›   ·A E®Úrv“'õº¡x<… Š×êãÛ‚€îgÉúej÷4{ÜhÚ-Ž›î{¤Þ[HüsÙ‰QëíŽ,ÑÜB•Œƒ,‚ YJƒ!²¸q;Ý'Ñ÷Ôb{‚”¾ã=•\ þžV(z…Ó xGWBòøž±žB4¯>Ü¢·¬÷D¦IÝß²qûã½ÌðØçH1~Ëĉ޼Ç‘í=~î{Bñ{ü=³¬¸æúsÓîî Ïoñ.1}£èÖ ¢¯¡–|:zìO9 ¯{Í×{|*®oùtþ¬)Ý]^³~Fu(c܃ö¦0:ÍMD«Ä@ÞDˆæ"¢ÒDDäw"¢5ù}Qn""¨'zO.¾ô™68zF=D$^÷8š¯÷øTœo­é:ýYSº»¼g}jSÆ9Òw‰è»DôÿEDï©ç~j·”)Ë%´ýžáõ⢰â³~¾…(ïPÒê üø©-®AdÍÒØd™”GÔ¾ÃWO§”ÞçÃ;»¼_c 9¯Î—"v{Ä»7&Zœ.öœ{M™3ªˆMóù¡”CMªãqIÃõÆ/ëý­C§ÞŸèÅ@NŸµE»^ÂWÜqêCWdäqµ©:ÃAáucùzÏÄùÖš­ÓŸ=£‡g¬YßãÚ”q4œ©ç# £&• N[ÚÁS;³]gU  ­©B¿WDj B§³(374†`¸ ƒàçק dZð„‡åñZ¨EI„¤·àmH@×[Ãî+£ô´d})ëi?3óYÁÛ4x¿’\Ð2Æú&»6|s³é2z E-ÜwhѶ̈¼bzÒÌ|Fý™€SÜÆYä|¼Zü#ìÖ‚Â~fŽu*lÙ¸~§ýù1Ä[¡õÐI×T º™>DÝ+£_Ÿ®l]$¨Ù•wÙj4‡ kpàßv‡¾(IOZpM¥|4)@%vÓ0õZS}À¨þŸÂw Öµü],í6ô¡t{ÑØ·ÕÒùžÑåv#:È„aÄÅE•Èù ÝPo ÈquZ.Æ‘TlrM&niÊMz"õþŒ)1í„#&öÒêñÜø¾ýŽèliÔì¹ ˆÈ$_•\²à¬Œwdˆ†Ý™étå¸g÷ÒîzÜQ— ÇV9ˆ–$rŸIët4ù°ˆ7Ñ«ÁîE»Z‚º9Eq1Í:vÆ`Üm}Ñg^;£ßÄHIHe-­8²‚™O;”¨e!}V{ŒÁœ5˜²@D¹88Dæ ¾`Ï…¼Z¦(Î]‚è,—Ïl܃±¢)L—ØP_8ú%Á¹¾Kì‘^’ÐQbš‘Ôx¯XdІ³ÆñD&÷ Õû4´* JbbíiA©"»1ÔÃnÌ.«ÍIÒ[wDq\dƒò“QSBbóÕŠ—3¼"ráQˆ&‘8˜(I+úHóêhY¸ÈÎ9CÖPSz‘Ï äŵûšt`H4 WN7-;æ”Jåð«èaÜ7¸D‚âS/¬BÄnÉøy}~Í”ôUô÷«bæp¨CD‰5”2¿E¯Ý[D-XEkɯñ_8Ýk|ö÷k|ć5—R¬µönï­qT¥¸×8Ò•î5~àµÆO‹Ö8ÊûÝkÓãǾéÇ5>òÃñq/ø¬ñÝ‚5>Òã·÷¿[ã3<¬ñ™Öø,ï×økÜ#ó{¿ÃéZãðÕ&ÍÔQÝ%X¡ªiqËg“ºñjblD~+{¬N%.-÷ Iº]ïȲOhÓÉŸ^Jsó€æ²pw÷дX:g“m]&¦+µÍ’Å#%z±¤Ý"–„™r5¹êƒW™­Ø%íÀ»3»¶vB\Š%:l áu‰¡½`V_¶iÂí¥m"Jîì•9ì@ó"C ”ŽÆÔž³ÎÓÍ‚}æÅ ˜þ;¤ƒq#„ƶ†´êºë`P„H ͱÃÌÆ3sKÛÀÒæV2Y<–ÜÅcÝ3‚œÃ)JôßW†ïhØà (ÿž;}yèë"f$†f×´I˹J·…YÖX¯8¹É'ÂÌuQö¢\`|¸cy(l€ X¤ë dœE´‹E’±-4‰•júsuÚU©÷8’Þ"SA öÌ2¸Íe¡øÀô±Ú•KíLuã°]TLcÎY¦:$wC÷ò²&ÇKÖhÒpâOúŠu¢; ,8ÄOý©¸ýéµeÎ=Y5Šc.•€âe.‹it˜ßÕ€êt\sú‚¬ˆ?ó 7E½ØðÒN‹átâ‚’FØ-1_E3læ‚@£tìtä¨÷fñÝZ°Mþá¸ftˆ˜âšOP[ÊR"¨ÌÒŸ1Ÿƒ3PåˆJyÏEgÚõ$Š}·¤E{YƒÔ‚èÒ/—¤=åØBÈ¥AB¦ÊFÍ˟ܽÿ¦ÞÉ×BíÁº?EÛ0Y´¹]àê·‹.g-9»oc¯Ú\–)áwT¹h8¡Ëé2Â÷X¹¥&§œ€u[ò"­@hr7rH )/:q—èúë!ÿé¬k‘?“ës¨ \Å­€`?5`A%ÎéÍã¤MgÙ²}q3{‚îCdæ:–|Û×i¡¼»…(À¾´)þË•á~ºÐ6÷ƒ4.²é‡ëjœ: qÄ ÒÉŒ ¦Ú;5{ª‹) R8Œfç3±ÔxU(–‹¿2ÒLœuù¶6ªdœœvFZ¢{z¶' 1ßå÷“ÌÎîq ªóX6ua‘×CëO×’yè,_3š¾ÂøY«û×µXFtÂÁè½rÑ m7©ç•ºƒ›ÏCeºcÕÃ,âDL7Ð] 38£.Ù‘JßžÉü,– ˆž3¹À¦xZ7qæƒÑùq±W÷&|åi“¦d0„Ýt;´Šá`ìZ­šDªu)˜¨=­ŸEê)¿A~ãøè§ì˜Éd0d䜷Y4¹hš¿!à ¦N\×eiÒ¥›X:‰¸¸.|j•#’oÕ ]Ä=]gjä÷X ƒ¹Ð ƒÜ$7A‚Ø…ëxHr^@XÄ*yì|%%Y3ÆŽ!B¢&, °\:»PãùD$§!ºµ%Q¼~ ’IàL7ú 'eeE釋Fô+Á9cò.¯ô«þ‰y`eÏÊú‡Œ×}xjEeâWËÛn)c= 裆ó̪&~ZzVªP_ÅË=®þÇ؃÷ŸVùV¶¯¥¿Ÿé+?i¥¤ì[F(ŸßPüA6½hca*’hOp ˆr–µ…’×ØÆÑX›×Ð=)WÁe€íc°Ôj,ç ¿Â²…;iŸ ݤ³á«~ƒÝ×Æ7ñ‚DBd ŠËH²@]V¼~µÉ-õîï,JÎkÒoYð& ©†‘·$«–FA `B ^«˜ýú=«f|¦×s˜5#X!{·ˆþ ÊògYRAR%] ~em»Ø7pûé!à{ùŒÝU² <·Ã'g©*‘˜£J­â‰ð¼Ž$À×Hrq°6Þ5qê[àÝáçsÒ*~§ÄATëŽZþ{çntöäµ÷76+ñMc˜À‚°U´ëŒ5€³É¾¦Uî ÛÑ%¸l8ih’“—ME¸íF@Ð-ÈÌTõ¤nžARTžxýÞЛ¯K,?ÉÍ:a  s>XVó5ôçåc;¯ŸbÞP)s;‰5ÈI®e¯Ib§±ì ªkfPöäóØ, l¢# þBoÌ5bkÝQÁ2“x#¯=öIÙŽ| ÷½áX„š^ë³òž¬à·ÓUU×ÖQwqZdçñXÃÒ/É’ê¨Cõ|`”Ù.Úí½nȽÒc"+ˆûûJQ‰ñ"fžEw($AûúD2ƽ×oM*›¸~çnê@¾Èë jœ*c’s°x8´yô Õð0“½ó¯¬û dŽ: >3Xp\׉¤†Ñ‰ CÞTyø0z@Ýë9h·f1šõ{¢4sÄZfµsPEßCQ¯vÁo .D'Ë£ßÇÚ&_ôâè‰åû'¿EÒ.±?•’dß0µ6&K­gäÇÛÄ÷±í”$[t¾Hå®ç½2Öí¥QË){)JfU6ñºG/qÛ|€Ôqú¦Qa¬â(ú͉ØÚ:¦¦¿ÔÌZDzmn;$W'7°²ØfEôéì­bWcØì î©;pÃ)È3j Tè³éÀ—Èú•[D>XRLêµK¥Ud¬ËîJë ØjУ‹tJ.T 'ãèBdK}ÿ”TËœòÎ$s9Ïœ¡U{‹¯a{±‡mŒP‘±Ëà %Ô*G$³í~cÙ4lkAˆÄ(¼×€’oåh%­åÌïÀ3ˆgµúÐv¯Î\TùêD)½Üh_Ž, ª/Ø• õ³£µêôä¸5!hj*°Ë&Ô¤åj•2ƒáaon>RocQIKÓKgðgx,Éô4ñ@Ib8{m 8¤¥µ,±ˆp£Æ\§X-iî¤Á: ѵ÷æÖåß.º ÄO›Ø4§‘¥á¦â×ðap ZºÅ› ×b˜€=5µ@ÅúH„“²H4Czéfk¨s ¾< «€Uv¿F–zhJ_|#ES‡­"ΊQ¼©ø¸ƒ(ù<_d±è÷.s†äå)³Pu´{Û$oš ¹7†ÎöX°=0%öS§>± ¼áîÒk·¸µ9Ææš(:‰±n®É4̺¹æð2A<Ô èñ™ÕmG•¬v ÜæÖñÑÜš#ÜæÀen±œó6·P×Í­ ½ÑÍ-^»¹…ëmnpsk¶t™[Ø…ó`na?äen!!ó6·6¼Í­Ó"k ›·¹…júæÊ9^æÖLóÁÜ:°›[»ÁM™‰B—¹…-gæÖD7·ðµÛÜ:ð2·v Í-|í˜[3×GskBÅ:æÖ¸¹Åëmn:æÇp™[8•à˜[L2¾Í­Úƒ¹5C^æ/·¹EÈÍ­ãenM—:[OVçÛÙó—¹…<òGs {3nsk¢‚É1·f«æÒ·/skJ‘h§ª³Üæ±Cs ½Í­éí,cjæþÎÜš9=˜[g‰ºvs‹€›[)ýÇÜÒì<˜[‰šØ‰N†=gðÒ_˜=»F’9ʧ/vƒû3x¢Í° Ž-Ð1÷ð¸GgÙþͱLÍì¤ù´6+¦7QO‘ ®>tÖ¦f}\ÚŽ×L_”Ëšé¤d?/ I¦õ^]L‹Js¯(†*KÚ)ÎRX6ÛAÖç~äý;߶.ÜX`Áô¸ûøæ`•ú‘Å+QÆ£Bá™KQ»Áqcëhö÷ÐÁTg!Ç%Ú¹º0Õ1Õ1ÕoLõ¡ê…Y'y0ɦSëé¡]S¨cÒ&ÖoLM•QðßXø6Ö ÄõAÀ Y«*µ0]ôÂÕäI®¼AØAÀ?÷÷Û DdG3“aèNöÑ8ˆiÛ›:Ð5†`¶ÈaÄÅøÔ9 y¥•s¾`„¸ò‰¤7hßbÙ”Ô˜Aìr^«È÷õzä@ŸŸsZó”µê×ÛÅ °›1>7 u Ķ U[f[…ªft™…(q~µm³ÐÀrÙ…Ìy©Ç.äñ`p­»]ȿʲ Yí†Ç/szG×·Yˆ>o»EÊeêø¿cª|Í™“ÁT‚ƒ4”£k×ï%]†¡ƒÇ2\ nòé´m?–µ©—¬`ˆcnìºq=!ð² ý˜‡Ä ëˆN?Ä %à—LÞƒY2›bŽyÈ*¤õ˜‡DŃ}È–¹íCîèB1UçëTŠc®–Ë>ŒŒðh^Šë hùÎÀ ¦±È¯ÿÌÓÏî`¥4”˜¡”U]:&ºàü:ª¦r‘ÀGSoªþ»”âtØd-›úC4XÉI ¦[0hAd½î(SŸ d†‰{Ç…¨¢. cbäGî ð;¥:˜ÅÚòº•¥˜ÜpöŠi]GÀ&ç06ÈâðÌö;7 âc—Á‘¸ï‹%~ÜùfÈ¡6ÄmžP>áÓa±4·”ÞÃ$…o°G±œ–·Ó2²,P>Ä!»!°NŠ‚χ ]ÚÚš {¯ÆiIØZZ.JtçLUéKDzQ2%èw‚fÙÇ’Î v˜Héí;Pãǽ¡¼ŽÃÅ4A”Pnô«â€Kzù4ÑezÌžp·ÐjYÆ’¦+#Dï”Üé¾j¼9œT’óƒê-Óa&ƒ%“ÛË-Xÿ<.N‘U&8±X³EƒWL÷†"Yý¼ÊyvŒr¨7j d•}¬Fq@¾ƒ›ÐÞ¹K{cùiÖ¢ô¸(-½â$ƒ­ÝùAž/¦®!¿Ê—`lª¡M7s32®6¤JÕ\=ëg®¬ä¨fÔT™»ž&¦¼ƒNÇ3Ù*z®À@VÏi°ÉkzZ³ÿæP«*§M…þy•Ô…øle^)Ìyýޙ߳'tÍx¾EHìLê:+㳪§dA{ Q»¨¸Ï–DA´P[p"7iqýY ëîâÖÌâv¬ÓÛóC^Kìu9U•îLayt+ T+×ùÏ™^‰Æ¹‹¢‘Ъ÷©±,½û<&;BÑa-y‹"<³,'i°`ñþ}Ž–l iåÓí õŸÕ¦²Ö^†à’%«"árløUu±K9w°ôR¢¤ãâÛðòÙï–¬ð½aðÐéÈÏé¼tì 7Õïß» )"g°I"?øzF/í¢ &ÿoÊXЦ Tø»)#ñW§ ‡2=Œ›2.ÊÀÙ7eø‡e¬Í JA?›2v¹)ºò¦ ‡2’jÊ/Ê ¸(ƒÇ¡ (ˆ”Á%v(#µx(ƒ9à7e0oS q^óÞó;Ê¿y ŒQ)cÁ‡2¼eQ2¶×̃>P C´¦.ÊX$ðŽ2¿‘%ST’¸JQÚ%ËCmlÓkwi7¾ÕÅÏ°ÍÌ´ä|ö¼ »*–EçP¤ÄTFMvUà”$öTµŽ®e9 !©sUtŠ}¤ ã¹œ]šåB9-CÊÈ5]ha5]hË®¶,´¡ªÞN”@l'óId'—º9ó16£vë¸y.Œ|a·yl%ë4 ÉµìLÓ•‡$p:bó’ÔîªGÊœâŒ@NGVutÿKŸõ§³ÎÉÁµl¶Lééœî<ýÈE_C4"4&I¹[ÂÒ²3RAGZÌ™´}ËÏmæÅ«“·(‚Ý/ñ©Å¼y ÕÎÃ[6–È×0ʼRUôÃ[Vƒx@‰Jë}„6wA G^Xõ9È>$Ç €óŸ‡*R‡²Ñó¶@ŽPR$QŸ§ÃÊ• ä3æ¶×7+i·•7„…cüÔ.kÐ@¡†¥¢©vuwC\|spw>ñô„Í6‘¹Ùo¼1G¾ƒšªFO°²*˜/¢ë Gµl%øÍÁ%?KtØzû2¯ÕX¢´’õ3ü<]ª@ ‹ÔÒ¸<Æ_¢ü²°U9^ª§I˜ËŸºZ`…2‘KØ4aË9CÃ}ÖÑ°¼AeÂE¸ë¢§³ÜMîDF Ø…˜ˆtµ—îŽß«NRàñ¹,wœ¸Ç!©ü^M¬ûëÜŒ\V¬HÇÔ5ìã·ÖÛâºÆÓpR´ócPòc[–…)ÄipŽ[^QYA0”9§M¨Y© ò:Ý0¤ÝôbÙã@äÓl Êš^"9PÉ÷J‚‹ˆQyûk­ûGè糋jónAÊèlÊóÅ›Sü¢ÖJï~í=@áÚ(廒¯öž®3wº¨¿•L‡¦o–¡í0,/¬-:jxÛ ˆ4˲õGîžë îÜ&mâÍ<£Y=Òõê_ÛVÁ.vFDfŠä3 #^â¡B™«*EUîJ[²w‘)æV=ËÈQ9¯Ì}hRpdéf?îrSïv² ¼h¥§pé Éè[ï\Ð mæ½³p¾AàÈ€—l ¸ôÎ6˃Þé:Lo5ˆD:ò3Þ›å!èë¨Z¼õNGïìÜt½“àÒ;{j·ÞÙs|Ô;{ηÞÙs=z'J>è({ôβ9Ze/ýÞÙkyÐ;{z熷޹Z–ÞÙZp–Ü8»^o½³ë¼×­w.x§w¢ºT”›‹‘ØŒ3žŠmc9‡FY¶ŒÛ÷›T&–ù˜NqéH«%f%cuíT‡ï’„2Ê-m˜_ ýÜ1é&²LΧƼ5Yf m_ /9XŽTðÅEü¬º³äP:]}žGµtúT@{ëüÈÛèóüΕ3üâ(ü3–[á'Ø”1“‘€0’>q:˜Z  ÿ Ë>@S³ð@-üf¾0Eà`jæL tL!Ï¡xìBp–Ì mêûi¤)ä S5\DóÄýÐIêù½åŠÔõ…,Lõ…,μd1*-Æ W•§m\¸òÇIú{¨eAAÚæ*<ät»JÐ!dÛ}dÖs;?ò,˜å>2K¯_î£|«²» bÈ—ûÈàxÜGa·û¨ Þáq¡ÏÛ}T‚—K_ÃR/÷QÁŽà•J~pjÜ®ßC½ÜG Üî#oXî#>}ÜG…'¼_r£`“f¼~wìºû¨Uï¸ÜG…©"Ë}D¬\´‘í>ÚƒYr¼ Å㸠ÃøÇ}DT<¸ŠŸŠêͰ—ûˆðƒûè´l÷‚´ Ć*/É+¤ë¼†‡-vYæªZëØÝ£²èf”°†h «Ôª™‹|×Ç-½®ýt{ÄÏk¹žÞì›,ÿx;ñþëWK+û©Æ œuUA¥›åóziû½…R?n9!±ý¡áã/Ô;mµÜ8sGýxŽÚ ˆÃ‡˜(%×É3âŽôù‚Üù`'Åá×)éø;B-U‰-AÑåœ!ý›6òî/ Õ¬â´?×D^úŒ,Y¸²%ð8¢É8A ŸJÙ¯Õ {-¡žüä;ÏâŽ0š‡»HçMåcàåENG+ëÈÜ$ü­–·ÓÒ¥2äŇ®Ùÿö­'Šê<Ö{4uê!~ÃCïeºQÂïðhðÁsÐzöè]LðÄîÑð¬l;{iYrÊŒižpæ1“Gô¤îŽë}\Þ-ÒPËr!Lå¤G¸ °ÔTcÐÛåu®d &q9zÿp­\^ä§BJ­luÍ#Ï4ÒaàÜ¢- üö«éH#o à€@æe½u;„êà Nù™ÛÑI1Õ¯SÓ!w‚š—~Ïž©>¨AGWa®ûÜ0v+õÜQ½HñÇbŠéç wE¹¯Ö@*ëd,„b¢gaØzص× …» d• ŽªÃívƒÎ=(4"9± ©9¥F÷åÇÚw„¡ì>È@ÍfÑ*~î³íj^Íqèl»šuÚSÃÎ#°ª”S6˜œ­¹Òf':çŒmQi­p¿ƒ¿2YQ׆9žk'…•?Eh6—5JóÓpwE"ñxÁ6àæg‡¬; q¹OÊë£h ©c· b;]˜±é\ /9˱UûÝƹÛ¼SœìÐç>K ǽZ´áÉŒºÎÆpÓ3ùNß›yƒ¯O8žë}C×®U¾Àº:Xㆆnm`çå6}Y©ÇÉq¯:aüœ§Áå bë¨ëøë.èÄô@]#h6E¨Mú„°O5¥rœ6[±?/Mõ•¥ž¤¡€©uCÉ+†b8ㆭ.éSØhZôºÊUŒM«i)LŒÞ%ì±÷”×:L6ûóÒ¤±•k00uÔèÊ«`»¹_;~ÔrŒˆqc­V½a…ºÃ q¥wðD4߅Ƚõ+*cÿ¬ÄQh†xËÛÕ(rQk=uZÜœCrOä~®P›±¹(Œ~µu~ä ¥ öØ]ÔôÑ’öUkŽ`§–dZÈ¢ìðE|Þ2ƒ«qi]—¢r‚*ÛÄAŸ-êø罡—‹J(Ž”QRuˆÎVÍŠÔá+]ïMZr p꺯.%ŸmÂξ·Ûœi¨¬š*tDÄâM³\‡šàTZ6X}D)B˶*‡ºîâBl°_žmýád™Ô`dAÞÿ-Yøÿ(Yu¸% —dAÐâA²p£ê‘,ØÉqI€—d™‹ÕVmoÌ·d™Ì:\’;% v™\’ezbø³öGÉ2s|,3Ö[²p­–ÓBÉ‚çoÉ2é ¾% 6ºÜ’å`[’û0ÞI–I\Q² BtKć.ɲƳ% vT_’e¶ö Y€É‚­/·d|I–É“doÉrµlÉÂ"‰y[*ØùìfŠ®{f¹Aî%\-Îh{TÍk섉œFŠ#6¶_|d½WKà b~w­òÁ”zƒ¾àÜ„]¡Õ%˜›ó&OvßwTS€™bõðÆS‘e+jû"òqÇž<îÕTX mªŽj-Z)Õë`.WÊújÞ¥ï'}^Þ•Lß8ç˜ÕX7Ò?7„á¼Ò‘‚à4°dJáß„¼Áôk§ŽB†y”»…¥GQ½6ëµ”§wÆÍEÏ8©5 óä‘ønWÍ[ï Ü«]Ï•áÇrkß<üÀ3Æ?ýÃðqendstream endobj 6 0 obj 16295 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:02-07:00 2013-08-20T08:42:02-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000016599 00000 n 0000018169 00000 n 0000016540 00000 n 0000016401 00000 n 0000000015 00000 n 0000016380 00000 n 0000016663 00000 n 0000016704 00000 n 0000016733 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 18339 %%EOF ast-8.3.0/sun211_figures/complex.pdf0000664000175000017500000003573313004147321014161 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}K®e¹®\ÿŒâ´ÝH/ý¥pïù5<€ü®S.Üðô­ˆ )­à¢PÈZúRE‘¢Î?¿Ÿ_éûÁöï￾þóßÿñ¾ž_­×ÚÊ÷|ÕÕʯѾójϯվÿŠ”’fþÕÚw½ý*—Á»œ¾þýµ 2¦HùùÏþQW¤´d9¬NÇÞêï/O©y¡òŸHHkþJu~{•üì-üþò.YQï1¡Çëql ýþúÿé+sNt¥0«Ñ¡7I’Ìïÿ»Éò_÷ÿÿëëùþ/ÿ"ÏEž|ýûk ÷å&Îúë¤ õ»ÖG5΢%”[Ç2püû+·Ivô”Ÿ¯\ º)¹pAD­Õ]‡¥´Ü¹R~"¥ph›F^gUcÞhõuäýª¾’¼ãJˆ¥oõ9öÏbªÝH¨ò”±©º»PKmÞÔÔ§•E¢Y$¥ŠHÓ¸%—-=ÒIÉ™su¶Vw–ÒÖÃÿDJ-^gIF"kÕñ&ŠõÌS6U¬ïžâcó:{«$Ë¿Hò&Éç"JIbúI¬è¯+¥‘i7+rá¦gi=¨ûà=´ù¼RöÐFïwJÜ8¢ÎƒÕê®ÃR·Ì:,%ký{ÕW¬5¸‰cý²„Më¸%ø¸¼¾ÀÖâYDO%ÍÒ3’ÉOIZ×õI\¯)UÎ~Y\˜1œ–U¢:ÇŒôÜ)¹©2&O[«»Kéyh@žÐ¦–½WÙš1Œ5êø÷—wÌS@uÝS|h^§ckTKè_¹‚ôϯÚÅEivöö¯¯1Mq²”Ÿ+e3®Ržò¯ÿþý¿wº”¬nÚàÍsÚšú÷¯ÛÁ|µ'{Þ,à¤,©XIÀ+i'õV c3~LɳÙ{j5VØ¢<¥=œq¯aj•ž‘ ïÞ K9½T Ÿã «âÕäl„hÑWrK g*eN*'Ë®é’qùÑJÏO1)[@II5m<©ŸÇ¿¿ÒÓ_)?_k½Š¸jìU¶Fºž’Ô䟓bbÒªLtdoÓñî…õËS~¾¼çžâ# ÉëØ )—–ø:?Ëu¤¤^E„Eù™s6œHfÇ ŠØÇS0"Ó -eÃVg`kÊ©RRöU)‰KòÛëÜCª¶i$b«yÏòžÒóÙ:|ý;X5„ôËJB9o-5ê;µØGçSéè¿rLá?(î28UoŽßü°™çÿ†„çWÙ2¶.Z˜Þ n ¸ÛËy2»}ÞTÜE÷2›Ö¯¥Œ@bH¿·–˜­‹cWÁ:6µÑëYÐ}~=ht=ld/1vï”(þ$2Ž øcRï[÷`÷ÚÇĦ-FIÙ9 ù7•Vö6ÆöþC™Ì§´Ã]·f.Àää-ÃœªAþ·,08€ EÅê¿÷Zè^7`#«'ˆALÀ>¡^–éä~ƯÀ 6~ï±ПÙÁ- ›$ÌÎ5ÐЖbìƒ6¤AÕE0d+ûI‚ö 4Uµ†wÕ\ô}ŸzëótyÊ,h;mڠƇÜzŒ9÷~ö«ÎøV!!6- â Ì_l@E4Çdè"•ß»w¹ëÏ[¤Ýõïng-b­_\*ÜLb¥˜„Ü›-²å],ƒ±³$/æ­ï¡u°e†è‘Ä{æzŽÅ‡ÑÎ{mîíß7C²·»~*Ž Vˆq¬*VâÏ•RUuÚ+œÓ´æÔý¶ V~‡DÉêf_ƒÜ…)wv b}W ÄF»º¿sVu¿Ï«2RxI?YnYÒ´“Â>ùU{ý?¼ÂMÀ={ì,—w³“¢HëmÇ’"‰¢^ŸKz$?³ÿÞêj=%'XŠ iï—$ó ]Eü5\ùÑwökjè`wgéR>Yº”7K—òbéR>YºÔ7K—z±´@°4áaiAcéRß,]ÊÍÒTp¼Xú@²téo–.ýbi`iÂÃÒ¥_, 7Óaé2>Xz½Xº¦‹¥‚¥¥¡_,]æKc0K—þbiõ7XZ0Xº´–.õbiPøfé3ù‡¥­~giƒbéÒ_, ‚¼YzÝ,]ŸÃÒú,-è,½^,]ÆK³ÕÃÒꑱ´KãäÝC€Èt x/ÞÍ w©`;¡L¥Ì_gMèœc sÖM¶Ôc<¥k/‰КV€dŠ øäÇáæ?6´•žôíªôîG±‘ï­›e#ZoÝÌÚêß@dGÂ>úvS®Á”­œ¦ø[½@ÅÍ´Nž+6ÔÊ}r+ )¸AÃÁaÏJ @툣Ü›rcF©_ÔB 32Öžµo­ª×Á©Q  AF«Wcî‡hR—GÏ!ª¦#¨›—Ç¥×=K£FƒûטWŽiò¬Ø“I†3¸•q‘d «yÖ5™ÃäjLf$pöà™þdSÙ¶~¤C®jk‰­- lÞx8A)ö,:©Ø7£æÕ4<”ÝTºC”Þ£™ó|çd »²Àf³ÊÑ f~nõK¡Á`wõwŸs¤ŸÚèO‚Æ»Wùùè«„Ÿ1r«Cƒ ÷©û„»‹S‡F‚UÙ e‘ÉUx±Í„Üm°œÃUÛ*벓¥À÷õœå0žâ†ŒM#pDd­_¬59q‡]©"&†³Yâ ˆö’Œ]ó4î6å·V«]2’:óîƒv_Ú,8ä-ŒX|øa3» ŸS ôÇ4ä ÛŒB»÷”^{mÌzá^mß‹”­õBàV©'VøíØà>Mè”Ý€“°Õ 9Û¦ŒÎMlµv=ç ¶a²wóíbûX©Ç|LV{‚³Ïè±L(ÜqÐIõx4©8b¡FȶQR`:KnéSÿ2™o ÊŸ¦^ôôpâø­›Y}áNX$«Ð—Ì>t;n¡¥GçLTYµÿrÒ·V‘,¯ î¢ÐÞŠÆQîã`kØör¦j€%3—Nz2›l\µ6AÛ ¦–Sf)¸Q`“J.ÛS¨Inf¶š>Kf+¤hDï•#©2(Ÿh&ãˆvÌ%ÓÈ& × ö âj¢+… ¦=°¯u½Yiÿ(bÔnš# {¶©Qw¥Øzlƒi{14Ó ÕcSM„u©X„l«œ…‹®k €2Uƒ%ôéÞ+»ùEÊñ)ZÂìmŸ6ÃI» lÚ'[ŠV=ë¡áTÿþ‘rŠNÚèþºR°þÈÿå—‰š©¥Ñ§Cô~!÷óÝe)䜩z²ƒ=F˜8 íóí¦%ý†V«™Ê¦GvÛ ©ŽÒ¹É¸ô›fd6“:F¸U¯ Ö9¶°kÌ°â^]2#fFO*š|h%ÈyŸ¸KÒñÓmÄÈJ´+^¬ˆÿ–´G€»Bg§€ìù‚”Œ  ˆ vVÓ®0I“Ø){ú‘PA›Q« R²:klª€-î]¬õÀh.†~åè<Àø—ú1˜¾ë£M%¶ª6»Ú"Ï2ð“ƒ`~¸¦YÕ!s·”EÓ†9þBn± eï—…‘ P3Ìk ¥Äômì¸h6žì<ì¬` (Æ¿aˉýì´S–F¨³S.{ºwbL?-6ÑjìÆÉÀϦŒ  ¸ù¥prˆ’ñq¥½¡à ÓÞçâ.8XÔ1Ñmæ>`%ìƒkdC^Í*½ª¡<øÁÉà(œ«Æ¾WÂÞV Íò è>bt43¸  ô þS .®xxû;’Ad_ň«ï,Šs–ÿîM®ƒÀ?yŒß¿7VòM)Ç$M÷ü I©ºY&‹pqM¬X²D§ T+$÷KÒ³è#‡•b¥Í%ó9ü굞ïdDèÊÍÁ^iTE f’úÇ¡†Žã¿õžë«–B‘áC¬±žŸÿ„:aæ*[0k{ÔV/ZFÚÚ“ÈÑ»’4"B\ìµ¢ý^—µ)xbÊ0£pÙ‰*ãº8™À¾cÓCQî›®–Ó˜Þtƒ÷Ç`Ž 3Liíª¾`žæaZk‰‹«ópѼmâK‚EŠiwJV‹v¤Í¥Ñ»K©^¸X‡Äâî82¤Èu¤Í°uô,¡™9Wyl™²0Ö1Øõ€Ú “›™s+ßælIÜÌ,ø¸™Ù ÌÌY×€yþ'+,@ÊÍ@,“XîÈëy°É,A.˜9óÈÌlÀÍÌ‚ÉÍÌ6R5á",m=%ÑŽœa™ŽP²ÚÛgN  wÜÌlPfæ]®ÂÌìs³N«oÐÜqx£=jVff믛™ S´ç¹*…ÅäÚçAa®L™™¯É3³×off‡û–MnfÏ6A$W³õ÷FÎgè©‹8üíffƒ23³T6Q‰¬ù±¨Fg´:ÏwöHff·™9÷YµßÒÝ)˜LË5d–7ÕÌû#¹wÓU\£¿R’®ŽîxA»’Çcb]ŽÇ$5ÔF¿"˜ýBŠA]HQ5KZ:ê e¿rRx£$ãô×ò[sOó )AiÌ€ËÇWþ€¼’q ÍSÍ‘ÊÓú6ø…ÁäR êB ë©Eä@øAoPAÞ“’ÔI-ã? x{•_VšU#gëBŠ¿"˜“hQhMˆJË”´:Rò|Š4¿²S =u¶úíMn{sï1&Þýó#Åj7  )†ºî!ó·i18K%Ûn3êØdzy4:…Ùºj1#ÃàÀ„Äè4ª!‚£Pªç;7í/™Ð´L¿²UjSÛMA®.¤8° )y\Ø¿mŽh`Åì¶]HaÃ쇷}ÖJ;ô )WŠÑ‘(lRˆ›iw:N %KºBÛRfq!Å~û…‡RÔG«¸B¹:?±¦CdÞJã<Ÿ Ç )üBŠA¿²[:ðBʆUÑuvÚ¾ û…”·kíÖs8äU}Çv!åJ° )'E&Ì]cáVR¬û¯ ){ПjlR·–4Ÿ—Z5ŸOµ i_Ò¥V „ZExÔ*AS«h,»Ô*ÌÇQ«©`}©UR`ÍòV«f¹Ô*P«Z5Ë¥VÍz«U³¾Õª9^jÕœ—Z%j• ©Us¼ÔªÙ>Ô* æR«fy©Uêo¨U³¼ÔªY>Ôª™/µ ¾Õª3ùG­²ú]­2(µjÖ—Z‚¼ÔªÙoµjŽ£Véw¨U‚¦V¡Ô¥V!úá¥V±Õ£V©G¦V¸Õª~U\ †w BOJÿ =9)z¥Þ¡'éû~UÞÉÎWøIi~‚¼3G^»”}R¾Ð«a.ñ–#ü·vñé)èëK¤Õp°‡†œD ~£óð“è…¥œ^ª†ÏqðRvIŸá'¥!‘'ÂOjÿÿ†Ÿx Ù>¦wˆ]Æ…qD¨=M±¥U5”µ9öÂä½|§Hm¹S<\Îë l­ž»ÔœK"¥.QÕêäF@ªULjŸRÏ<ñS껧Dø ÕØZý#ÌnŸÉ»Ø8Rjg”`YËBm³E•åçÆ¿%Í×Iù‘•NŠ‡ˆy­ÕUFÙºÃʶ€k­hC\ÃBÙªcE=ó”Í%k‘ìžsVgàîc¹íþEÅP|mGJH·@9)íSÞ} ¸¬‹”u „Œˆ”“2Þ²ÎÃK¢Õõ)ë,%$™Õppû”u>rjHoY(§é-묆Ïq¼e] „¬ Bœ<ëCÖÝ(ÿ„¤-Ÿ¢Üµé)?'%é©€ŸS*R4E§6Ÿ¢}@µœ |²)¢‘ŸñZ>='ň›-<Ûb«NÍ1=¼§}çÈZ`Qƒã˜žH±é‰,n5Úðé9½°ÑK«ácœžŒË8¬fúàšÅ©§$MÕ‚³x¯j}›†ÛËw;n/²—¡܃9öô£ê¯NÞ+…¶¬5tÇæÈCËjpƱ4ìe«Uk©9Xn/DYÌ®Êùœ=tIü‡$xWÌËšf/“ù lÝ'Z¶™½ö€{6úy}Ƙ'íed/#ÊOÖžÀߥÊXÒ²æ§,qŠÄŒT³—í^; 0Gœ@ä|‚Ÿ<;Dî$S—çÍ’¼./ÎíÚÍ^VžÍ)«G{cñõ‹f/3˜åÕ~Õó†*f·s³?Ký°ï0ÒäSÚa1{Ù•btI´ü2úû1ÜH'³—1…†ù鳨Xýw5{™C÷EØË6Ö¹9ó ŽAd¦W/>þ¦½Ì@1{™Álö²]ñCŸüãΖañä]bæ $çì Óªf/3Xh/“!ã/]ô꼿¶ŠFëˆá¡Äý„X‹6u@­Mìå«Ð^f š½Ìà0{Ya€©IÝ ÚůYa‚ÁNYvÊøÜÉOð@Æ[7Z‚…ö2¾¹Õ[H<Ä»¶€¿5˜žÎ÷'ûú®6ŠÝgNÚËh';•‘Â&‰3Õs÷¬´—]“ö2¯ßìeuû—sæŠ?E‰¢l=çÝ•øLe6‹8üý˜½ŒÐåKq!ÁZKè*¢óãÊ¿kÂ&íen{Ù&ö'KçöféÜ_,û'K#îU`\,-,ͲÃÒ‚ÆÒ¹¿Y·šKbÁò¼Xú@²tžo–Îóbi`iÁÃÒëféu³tyÞ,bK—z±4ÀÅÒ‚ÆÒ¸kv±tI,ÁÜ,½^,þ^,-,çKçq±4(|³ô™üÃÒV¿³´Acéõbi*þ7KãVÝaib:Këw°4c4¥yQñ°ôÖÎ?Xz½XZf,màÅÒ…WAŒ8·oÊ™´È,ŽÀU n%ÿ2€«àŽÊY&f`».›l©Æx¶&ɽÄsô"=k®ÀEè|òã@¿Y ¸L•Þ=6r]Jº¨õò¾Ný¨[IwȺ)× ô˜§)þžÀEHŠYWAÔ\æQ‚B¡t9: ¢æöÁ\,ÜÊà`Æ&§5’Ì–c¬þm,•âú 85 Raã+ºqºs¿H ² /!î•gšY•ÿWžÆ¥קH •¯ ’ž#=¡o(v ‘J9IH²„Õ 2$&s-;¢ødFg¯ þ ²©dLa>µÕlb ¼¦ÝC$tÅžUñΦs3jæ>U)^W×¢tËFB}ovdÈÍA¶.B.ã©á7;…W–ÃýÙÓ_Ým=£? /ÎÈ"ýÐkÆÈU'?^Ý50-€‹]œ*h§-¬ÊÚéC2¹ZuùÈÝ*ž‰ï…óHáIºe;]‹Ö9)!~quqD䈊 ¨£õÀu±ëuÛ­ bHâ…öWG¬°µnìj°wïÚÚn¥V«}ÃJ±ÈC»o«6µM\[ÎMúaZÛ’ wœR ´¬ËÒA!Üq…pßdjm@ƒœ-€ë¤$ÆÅ\y{ÀB¸v…M >ÀUp™­Û©W4ZR øZ àÚ5PwðsJ<ÉTp„Õñ^Ý5 h\‘`ìƒâ¾L fÀƒN_¬&SC×­\VÛª¸ Ô` ®]•m\èG˼ÆJ€^Å•ê[Õ)Ð|à Eü"óV à*¼úÔÕ®×´Ž.7žn t à28¸‹nðü’­âá ×AKÖ´®Ò²Ä,Ž ÀjšÙ¤àfÕ2\Ë»¡p”¥;˜T{ Mr~Ìle\®ˆ–p\/Täçå%éi6(˜^«L#Òü B<¹ò àâJaÂÒ0¸o$†“ÈÍûCˆ›®¤ÉKíaצöÂQ>@ˆ1<2)s•ô-³¥ÔáS§ò¸°2 l¥æ©÷XK7K¶ îªI¤ƒë¦LïI{*´s¼@e.6¸7µ6Qn-³AŒë›rA›&KáWÁx‹9øºÚCKÀ0•mŠMzk¨Äxk³½mh]r¸se‘í„YR-…cM•ôO¤ÜHáã^[Ú=ÌSÃß\•IÇþ;)[Š¨Ü†æ¨aë{šŸÆ™pÓhËóùeðàfkCO§—fÐI#÷‘¶»i^E0~ IrÜdK2[MbŸæJ¬¿ ÊƒÑÀ5b  >ôÐ sÐLºcEOŠŠn¡ŸHþ+ij(Äö^jWT ¬èφsˆ½WØéš—g†‡»Zhût3 í;a/œ¶—ÆiÝBw-Eöƒi÷ƒ6reØÃ¥o&9Ø{Ã2aùžrÎð§ù `ì@§]èáž4y@m<ôÍàJÁ£b»<”ß'é"ÝæÇfÜ"ïOºg)À&Ý3*ÐèŸñ67Þ«†î™äB×ònh–Î9ÚƒâY1ºnø·ìÒèIätÀxyCôÏXÏ-Åü3ƒþ™ ÷Ì0Ü@«pÏ ¸g&½3‰ßIH‹BÃ=CdÞ™Aï ïR>áµK8þýeWO~Õ–øg´Á6MëwÐA3ä¿Ì\;6ñé I¢(BMrÇì4Mj•cU«À0­TV@)tÐXÄÖfÊn¶ˆ“cÒI3ÜG³(_ÇqÑ,ªvøÎágØ¢<ŒÝåÕBVpéÉ‘é¦ðÒh!i¥1Yâ"ÜàñI¢n2à¢ò8覱k¨ü^(º9¦%²$c ]•˜ôšÇµTíúÉÑ©ãºjòÁáªq\¹0"eº§G·=³æ¨ÀOSÎîƒã¾K”Ø04¶LÚ¨R‚¥y •Ç´ºÏwú«9óǨ½Ñ M[Fm@¬9…Fm\#¹0!kÃæ.·…Sð~ É­Fl¸={¡Ï€c΢"Dá›{ì–ÁØ»fúo^’k,2àá8ˆQ2À¤=;ÉÒûpõKÞ.´Cìá)¿VoÁˆÑì‚'G϶̫ Ò£¤IEChå®–P¦I»Ð¤=Ý¢í_m›ÿ‡ÕGók’£QÑ ÝiÐÆUoõK+Óño¹Ê•ORg§ mÚf§n!-X *¨]\QqrwÓ{<fÎÍÚüý¶j§O–.éÍÒx Ýð“¥K~³t)KK],Mè,m±òÁÒŒ¥w–v býfé@MVøKã)¿`i‚`i¢ÃÒ0×;KÃ2±té,]曥ñp\°4ÀÅÒ„ÎÒe¾YºŒO–Æhn–.ífiôùbiÂÃÒxòðÍÒ¥–}/–Ž‰¿XZÕK Š¥÷ùÅÒ É›¥á~±t™K– –.ãÍÒ°î¿Yšm_,Í™3–ÖïKW¾§ìT ­žhCPZ~NBb}´§ÒWƒø˜_/‹‚(ô¦ Z]MôÕ8¦Õ–ö“#ê\T²’«5—à—ƒ Þ¢ÑÎW«iÛåà÷V)rDŠlÚŠðùDÊM3½6V˜¸ÁxÙï4`AÍNzk²Ü5Ï8TÈç‘©ÆMº!òfkúj²xVÌ€½!NœEt £Ð¦žiwšòÀÔBW¾ì¬“Žšd઎ÐT7Úµ>Dïbîi3is×䛂æ~…ÇjŒxúQoõ1÷c^9Æãz§~/Íx¨â8š@a-›?Ï4Êý}O£§hâpäùg'Ý4§¶)Ù9 /õkÍô{ÖgÇaäE7 è còÓ›©|Î+GÒáŽþ¦ŸÆ²®ãi^¾iO‡Áãô–Aj¨1úH‘ÃÄþ1züI¦: ãE?†éuÐù†[ÙC€„ðÓ`IÂ>|Vt;<ó¾ø›ý:hÕEÓ$¨ˆ7uÒ²³‰­”#„«žõ»„0¼Lë[0ëûð×´és–mF³"ÎóF»ŒJ/>1T*âoØL=5SŽ¼=5+÷í¾xÎ -ÁM#ƒ ÞY{ÐÙ¬ó¢ŒS¿H4骹I4è«99]1Ó|5éªIf˜f ]5(Ðé«aD ;_Ãí<.™«fp†{j=5Ã5Ž?hТ¤÷©›È¿¶ü4?£Çå´%ûôä딲§uê#Ü40ÕÃê`^\ÕGx1 5˜Ð4¦†±“&Éa.šE ¿àŵ]ë0 Þ’BFúg’̶tР‘Ò´çÝWóÏðw¸gˆÌ;ƒWªZá¨9­|÷Œ[¦/Üiç¯ðÎ zgÜtg•1sÎ8Üå bŠûf}3Œ~%õ7!9îdŸ4V1–\»_xC²Ó5£ß{¿æ˜Y0n€Ó9é–IÀ´äÎpË`Q/õ¿ïV'¼2ͼ2ê !¼2$w¦9"qõÐ.7Ã'3²LVï%x(²I,¤Ò’b¸Çô°StÊ8fS÷gH{ze„W†(æÇñ ³:šO†¯€èVˆ{dðû8dº*f“ôïµoqú{86Dº,æñÇXÝ1\ðÇ@ ˜< CÆ1爙“ÃD¦{d–Y¿ž ÉC—Ì$Ÿ>íØ’Â#CD‡L²Z 3X#2Óü1â3}°®»7æ M-K¬ÒZ ‡ÑûÎåË€¯¶½p'‡LZT vÙ,‹-^6,°=`t†aѨ'l¥JƒO[£>Ó6F§eŠMÃk¡µm=(|@ ;Dö‚Ç&ã3žÏš¬žŒŽ7úÿ¶‘ _¾»ÛëfZê³Çy€¿³ž=#ihÓÂË8Cu ÿ݉f\.fŸÏ“Ñ!Qa`¡h°'Ï ~ Ú]°ßýˆHT<“xJŸa}-ɶԽ½J\|/ÔÕAû¾è±*n÷Y’nŒLnêö7Ø„ GÔMKAM[™ÓÜIðýv‡8.ÓÇg9fçä[geèÒ œ¤¨™ß&v{ά¼.LÆ6_tþ!'çÞæË›IäÛÐ-'˜›¹7øøÅIÀ=|Ä?âO\‡»›+î<‹oó9¦Ó#)jÛsðQ^Æã+Šžoó±BÝZzä†U,3,eÜ*p°¥ø·‚KÊ•¡$ ¼×à O¦Sû€ÝOø6_VÀXÖZz÷à Pím>¡¤7ùà_[|ÆFlH¯R@ö\Á‘ÁŽp¬ñ‰Šgè…äŒ —^¸Hö6©…{&ø›¹¨a0.°Âηù£ÉÆ·ùN=.¾1ßæ+dç 7KÑ™j0Û"½XšóªàÔÅ'T5𜀜D»3|›Ï1ÇÏÛ†‘aòm¾Å¯¸úÖøD‹1ì³ø6_æC–d&¾ÍǧW†Å wæ¡'Rº_‹Ã;a·g=2ßæ#.öÈÌ HwÙP7"??öLź øèm>!Pšo‘e½&À7 §nÝwA^ ,÷^ë6sP÷·+ßæ´¿òZÕPà«},ÎÆžÄÐÈ y;*ßæãk4|X®v½gÔÌ¥©gQìº –=êAh’ÇÏ -Þň«ï|a§M=ÃçašG™>ö6Ÿ ™ò›oɬ¢Ñé*<ÚtQʱl¢âž?¡ÝtçÛ|¬KwüY±d ¼þâ^ÖÔ[<9Þ\)FFÚ¼FŽèÂZÏ÷L2òm>ÕÞæ3øØÛ|‚6tü5!ë=×n¹ÏkèÃ@œóß@»<˜+ßæcmÚªº5ç¤Í¸¿rÀt@0žêuÂjoóì|ÔÔH1tM;-- á‘ _âßqnBQ{Ae=ZN-b+æвîS!23é%•Ç«íª±lå4àµÆWìÍ$ öñ%Á"eDüCÍjqxüƒÝÿƒT×S§C’¥ëéž"÷mÅÜè"‡xv7¾V”uͼÝP›¡ašÂÛ»@’-)@ g `ïA@Ø<‚€MÆ;ÝŠ €¾¡ERA…þ ›ß£_‚AŽjAÀWØNAçZþ¦Ù‘—÷¹µ)°c-m}A )¶Ï¥`¤E”ˆ lAÀGd|îËÃGd.Ö[|D&XÏò‚,¾h§û‡)Ìys˜"û<)¬¿6í>ùwAÖ„yA–(U‘áF4EÉÕˆ (Z%A`/EeÿOA–ÐR¯äp=3‚ై^ñïêÑãYbè6Lã0ö[E² &‹5&ra+¥jÖ}“Z¥«˜dá)RÌÊw¸ã=Ö˜ïT^N“Ô¼` €ÛVfo%\kLˆ—’TŽoóQ«`G­!蓺ö)|€nDo4;ÌŠÐÄ_UÉ T˜É4ÈG>Œvçø ÷õä©æ@ß" ÂúýûË`²XcA¼Q¾HÁ·ùHŽF'ûpÈ{RäG™¶Œ?!)T`ªTihVe$k©°^ÐIBåW´H´,Åœé±yƒve{½ öx¬1ÉG‚bÛð‰&7ÃÓš¹®]Ÿq(o$ X¬±Pm2=G‹¥'ÙvKóZçÛ|— G‹ž=V–u·µ„ð µ!Dì†r|‡â¦ýE—zMËìkÜô¤v(ˆ…›b ø BAŠ½ŠJ¥h©bv»Z¬1Vvûnû¬•vØ<Öø¤]t_–ÚÝc¸™vg†Ìo²AÛhRfkÜ\Ëí^·¶¿Fƒ6ßæ£\ºé»¦CZŸ_ó|æ B]±ÆÍc«Çã2ôà#|Y}àÛ|qÚh¾ g5núË;EWYpi¾Ûa¥^ðñ³œ§PÌq›×ö!§PìS¸x]çù^ù6_æŸ}±KÒz:Ô/²x”B§Ý¦Üu•ïzþýÔoú²ôUÅûâÂRµ=FKk,ø(Ö«žê¼oœNÌc±ÆÍõûG±ÆvG;_ÑK¨gm–d ¤‘çk8Ù–“à±Æ‘’uƒ¥)$Ù¾9½¯Xã6?Õ*Øôn- vÙvÃOµ ìWu©U¡VµJÐÔª¶ÞjÒ¡VÒeçüR«lî¹Õªž.µJ Ô*ÁP«zºÔ*<Ërøµç·Z…¿Áy©U½_j•@¨U‚¦Vá|\jþÍK­Â`.µª§—ZÅþµJ0Ôªž>Ôªþ\j(|«UgòZeõ»ZePjÿüÆQ«ø—…oµª×[­êí¨Uúj• ©U(u©Uðm½Ô*¶zÔ*õÈÔ*oó=ö,Í3ì¡Zæ+åç¤à–—¿¡ö‘r¿Íçßôb jÔc;îúõ6_…•MïÙÃ<'EOÛT¾/ƒGpô´M}š=Š#ü{—У>'‡þÚ©Á±¿MwRêÒ;^VÿÔÄÕ†a”°^Dï¥×ð‡G+YϘÁ”¥Á=¸Ãçf†HÛ’=‘4ôQ­úæoIý¼ç‰¸Í*[þô?uå)ñVO”ŠSìÎY·‡æ8"ù¸Î;‹'å=?i½çÇñ™Ÿ“Ãþ\Ý|Ï·qæ'Í÷ü¤ùžÇg~Nïå{~NšŸ%’ê}%¡óéµÝÖægð‰¹DoÂ=?þ–TþX<¼£ÄºjÑdxÊO¤¤Tº‰=_$‘ò^<Ö׎ÞÑŠŒ÷ÚÏ·óÏÚ™CÏÖ9×N><™‚¯Ÿµsrˆö§ÃÖÆY;ðNa`QCJ†­ ÃgíœÖ˨á=[;¢|²Âòúê0SÛƒ†ÙÈrÖÎø`xMc‹ïÇøª½Hvã;)ñ^b”úx/±j—9ñU\€(·Håü´üñßIQ7+.ø\ñý1¾ŠRíÎQ_ñìå=¥wj°·£ ŒïôÂrD/­†qh~pøÒ›%Ù‰0¼+F„“'ÞJ\Ïßî=Ö§óŸÏÆyŒï¤”ù9)ïù9ñùü‘zÏÏyŒï¤´×üøS{§Åñ1?'G}=Æwpù˜J/j°§ö¢xŒ/zá9¢—éyãòçüð¯_¾æç!òœ Þæçcï‰>åçs~òó9?ˆÛyÏO¤|ÌOì*1?–ò1?9}Îìð÷üàŒÝócøšŸÈaÔ÷§ÏùIë=?i¼çÇð5?žÃ{é5|Œã=?©ÎO!òìmèc~"ç'-×±ý=åÌЗ“òs¥¸4;¥ÞòíªÍµƒÔÒ{ÙR¿^¦“†<)6”eZí#JìšMD,ÓÒ2Í8r$—ù›íÜ'…ÛÇ÷©!é-Ýh#™vpzá9¼—^Ã{ÒRúoþÈè!ÂÉãòüîOùæåŸL|ͧü\)åc~>åÛUÛÇü¼å›ëÈÁ“Ò^ó“¢zhçøÌÏÉá ºå7.ó£?nzæ'µõšÇg~Nïå³Þ¸ü9?G¾ùü"Džo>?ò-(ÊÇÍ^óc)×ü„4;¥ÒßÏÏÑ®}~^ò-Ærð¤”÷ü˜î´ í:¨9ÞÚõÁés~L7ŽLwŽ6B»Ž^DŽ·vý9Ž÷ü„|‹ù "Džo1?où¶ÅÞ‡þÖâÉa×ßNJèoQêC[χþÖrú;ýmÕOý-RLûZù­¿E‹¡¿ÍùÖßìïD C‹Ó¾¢Ó΢Ðߢž£¾õ·qp~î+¼ä[3sÆ!ÂÉãò­á/”þþf}:ú[‹'‡óÇü\ú[”*;?Gnùü|èo6®K‹”öšŸÐ΢Åñ1?‘è5.óÚ—×àÚ™·qô7ïEä¨oýíc¯ù9òÍçç!ò„|óùùÔß¼O¡¿Ål„þvRÒçü|êo>?!·b~Þú›ëèo‘RÞóãÚY´Ø>çÇs8õ½†Àés~\ûò\;ó6Žþ潈õ­¿}Œã=?!ßb~‚‘'ä[ÌÏ-ßþíëÿì]&endstream endobj 6 0 obj 12933 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000013229 00000 n 0000014799 00000 n 0000013170 00000 n 0000013039 00000 n 0000000015 00000 n 0000013018 00000 n 0000013293 00000 n 0000013334 00000 n 0000013363 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<471325E26F9A6D59DE1359AF85564321><471325E26F9A6D59DE1359AF85564321>] >> startxref 14969 %%EOF ast-8.3.0/sun211_figures/gridplot.pdf0000664000175000017500000014255013004147321014332 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœœ½K®î8“-ÖÏQì¶eñ-Ž ÷\»áðŒ_ nxúæz)ÌÂõ5 åÚ:ü$Šâ3"ÖŠÿü¹þ-ý\ø?ÿ÷þúŸÿcüü·ÿû¯ëßJÿùþJ?ÿËúßÿùþ9ýüÇ¿ÿ•¯T~RJãç®ÂÿnÀ·pžÂã…ï…óE¼þspNÄ÷É*ßP¦èžϪzÖ˜ ·NmÕÿ.SeÔÇZC×}æv}ÐæSíßú*?³î¹>[šz¯Ö×o§úL[Ý%Í¡òhŸ©ï¼:x‹2ùºKÜgujÕ¿…5¾ÐÜ«S÷¨ÏêÂ5ê¹:rŽúçäz®÷ZyÄû®Îëw_÷Y_Vx=7w=«àúP ®O·yýYTÏZUY3Å7ZSå/”éCßtÕß}=·ê]êêÊ«ÓÝê«þUï‚þ³:TQ¿ÖøªøV™²p»Tf}¶ýuhºOY}i½´ÆÔklH‹ÜTŸ²^5÷ëÒ˜ZïÒ5”5lr×{•5m­1¬{â½zטŻôáq½êÓoÍ m=k¨ní9<Þó*3tOL=yÔªyåÕǾõèSsÔºÿÐxOhÿ¡ù$­!”ï‹¿½P‡[u¾ðÛ[ßôZc3ߧ׺”ï*¼ª•oö“4Ñþw/Ä ¿åIï~›˜Ïâü¹¦Ã՗ÑßîÉ2÷_yò}Ó½æ…y} üL,?V“-Ìû Ü&•YEóä·[¯ž€Y‡ÞP†ãqMcã†oê2 }Æ¿m•÷Ä åÙ?ûÛ䜳¦<ÜŸóFbÿ™—®ã[܃© ´ÛÍû +¯v˜ÄècnŸ<Ñ>]ãñnƸçÃ…Ë £9.¸l,| ã·\Sæ7êÂåŸðn9+'W`¯œÂê\‹Wf¬ÆÍe°Bv—Áj<¼bcEåÖÊœ5ËreίU:kU¹0ûf­*ÄE3Ë”q~[æYí«f\>«¾v^©„ëÙATöP½Kzbs=Ñíò;f¬T¾ŽUK3ÁµzÙZ©T7ì0M·½RadÄJuaµ×Jµ&g¬HU ¯ßv® cuòHÂî£w_Çoo0¬xS××hH#i´­‰}MÐaëñiT]Ç 9š®c'28‹/ÌU‹=eb%¹/]Çjs§.ÌUK#˜+•zÐä Öõ.\Ù†Þ…+Þ­ºa%œ—êŒr&]/XÁJ‰Yaý£ê€ÁìªVÝ9ô¬5ñ8s¬‘}]zÖú^üà1£\¾çê^œªˆ¹úivÁŠq鞘pÖöîÒ Ä•° ¬„ü-&«5E&a\¯š±¸rrÕM˜è¼*®×oÝ_«¢î ëÝ«²v‚šá0•ãzS™õÏ«ˆÊä+VË„ y­–zÖµF¼v ¬œšù¸*ªÎcrå,š5×o WƒõùñÛ®òx/íþÖlŠßβgV©Õu*VT¶ÉÀ P¹ƒ^+mM{öÕêºZe8,Œ2jóïUÕßÆ…2êÃc5ÓZæ5[O®ºš­Qgl¹€ñ-šÞ¥cGÓô¬ŽöozVÇ®¤ a´yÓ Ó±Zj ®a–±2 cÇ¡•y Ëõ[ÇŽÕ£Ýuë\Q×Çoõ\,ôëiõX]?wÍâÜIõ[«úCç®0qgÔ§V®ÞªC[Ÿ*{übŠÉëPª®væ®gp¾]ÓS>a·»Vx–¯ƒ˜ÏªX1w| ;èìñ^+±Ê`64ŸT´ÃÐX¨‰X«WuîªÖT‹•J«\á Ÿt;JÏ…«½V΂ڳàY·æ¥‚ÝÊ­oZ°«Ònb­~ømÑ Æúw@·¾{FŸÔŽ#V6ãú?¼Êå×Ù2³å5_ø>gËëuμz¬š¡“gñ›çÉ´gPí¡5;¦ªY­¢ŒÖ陹rz&ã9S¿½PF£[†UMÍL8w%TlRRÏÂ첪æçLŠjTa¶XØ3D³hBðªË£ÌZuµ¯j8£jŸ10‹gõ¬±&XnN<²×çÑ ¶ÊêM÷×,‚kí1=‚±’«×`«»ºÂ#uá©Ñ‰s¬VBŒÎTÔVß«¨‘Ig€5 q¾Âç^Í.8ì.+¬s¬G!Î¥jŒ¼õY„¹ƒ(mØAh_U'v Zå0q¥:<Ú°ƒ¸5ªð­«ÞWçU­$mkkb•kjsŒ¶Ô<š±ãh~w z&anD9Úxî-m5v‰gò~iO‰wìZ ž«3GÞj`ýý­«¿ÁT°>‚~‹o×µÂÐ^е¬},ÎÃU#;rŒÈä™ {ÓÕAT;‚¡ 6o\Nˆq͈™çgßí sòêš;~´¿wkk‡ï ËZVyOÚPnžß8$¸l£}n…õN?É{t -n#€ñ¦Æ&í5SýXl`|&_»ÍfbÏÏóê'°me4*1w¬ÿ…3CV?¼pfÈZI.̬Y«Ç…™Õ»«á·Ó¿ÅÎâòo×s‹V­ «\ÑŒN\ÕXÆ㎿­ZxϪٚÏòX»°’×áßÞØ5è·8ó4Í'W~õÉ«cå/×n‡VÝ>8“7·vnÿ;ïÝÁÅ3¼ÛŸ+¼Vã +‰üv8‡«ýù}½COÜ5¨ýwjô™µÚ7aœ·5ÿÀĘeW¢‰q%•Aý‡æ„ï;´³Àfr­Ø*ƒlL«ëÝ{eÆj­Àw8ÞÙ㫨æ´ÌÕXõÇØÜ«+Ï¢1~¯³Ò6ž-uO|£½Òþ?C¦svJIç"­´ÆXålaЪkÌUWg6­º:§qÕõ9g¡ä3fâkú skeÆ,xÝ>K¬û_cŸÒåÕ³{œ 0Ã]ÚߘÑ/Í 8l'æ³ø¥= &«äóŽMéʶNà¹Ù{hë5™`Hªÿ•OwTWæ æé=qn›t#°6“Þžx<–‰„'ßÄ5fÒ@ÂÖwp¨ìÀkeÄîÁ=^á¦[Ú;¿LK¤6~<2jßÇyHÛ>.‡Üõi÷5°¡(œ$¸çÓ qàp_x¨Ü‘±f8u$ ^¹ê4šp €cLªW«ÏXˆ¯Ÿ[»Cœ~ïÛáüsÛ‚¹¾–·ï¸ý¶#®Ÿ›ÛÏ­•s®¯pkŒ‘vk™ë͆M‹k2²%¦z5à ~ÄjºáG¬){[ýÆÏÐ*r¯ñ7’=ëg6¥­{zß³|·‹bMØÝvÃuûnÓÜúþ]OC¯éÕn‹òc[.Ì]m†®×µG¾W÷ös¬ H×ïÕæ6Ï5uaì šs«77urÌÏ25'ÌÏM–H¼—ÜR4´µê“yúi>PãÅ´UVÛDL%ÍÜW¶¯r-íÍ… á 3›¼cœ¥›> œUU‡1¼jµÄ“äõ¥-«Þ>P×ïå1·ØXñ3Ã5IDõIª÷7î«}ÆškªOÀ«l‹½ÅzMŸ%ׄèªÃšÑ¼X£«eo°× i˜cºmÞʯWlê©ešÂ8ÿhÂ`ñ ¶º¬ÎÑðHÉ&"–ŽÁ=ÌÁÚëß«´&±{} Á†Gïì ƒ{L8:`ß.‹¦ÙQ5á®~¬ùvýnðûb¯?Øñ0rd „Nçð{ÕH@œû ìv:]Üë½´(Âë7¸'Æ™B>môÍÁØX­=´À˜ZÖ¿rw ïà0ÁßšzQfðÛãì2Ø!`ƒôì¡Sëì‚åFGÔèf;£–wÒº´þ5ioR~î¤]Ó¿(·f ´ÉÍs2Úéf›¢ínöu˜¬î¢½Ìúתupý«v=3ï¼F§ØSn¶F ö˜Xäçïë_ä%„ æžZÓ×Ìê{‚í«SNžâ1ýLm/°k×æ»om V})€3êdÅKþ ñÉ~…½ÖÔîhýÿÉÞÔ×Ùfriæá¢i/²‰¦ ÖíZV ´•Y_`rQêë«Lö—¾j497cc6omÑÒOìŽpVÑ® ¶†>¸ ÷Qû7e×¥­¶íÞª]±®aŒ¦‹# g¹»÷"ØƧØè×2©«x_˜ñ:é5út7ãhi0]üÜGÎ &¤kè*nÆïÌ`­Ö 1,Ç6¹éâÂø{þxþ DÃ*˜ð,.¨«%Ž°lØ,Ý2£œx53˜IW±(ººÃšÑ¢e£Ë¶êjŽÓMrdµkûn±YOÚ}ÂÔbû3Ch_[AG?UxØ‘o£jåÉ…˜VSù{œ““®ÂŽÌž[a6ÏüˆŒäÉ|!X3_ëÄ‚ºJ5«ƒ/—ÙW+ }™_ž¤8“ÊsWI•¸,,HÃ6 ÆGÄÌÏUa>Íü\UV|Žþ…½²òDÄqˆã±R_SQWgâ·¨´mófø°…»›Êƒg¸^h¥ÄQŒ³v…™±p a \çiÖ Ÿ»ð[Tœ¿Š¾Mã4©Vh ç”*—8ë€NPع*ßP•~o¨Ê·?QÅv)T‹£=†3,Hƒ8÷0£Ó° ˆ›©ê<ªêW ׺bÀTuìKëÐÏ`iç–4IË~¡ƒVû$Ç`™-¢Å\Ö’~{xÒÏè˜×ÏpŠÌúÙÁdåæ13ÈŸÝôÛóg7ƒÍø3X\tˆ)è©22­±á­ŸÑ&¯Ÿå0ÉöK?Kq|ÅwJÚðògcûÿ9aƲq~äà…•%éÈ$ØU¶‡ _p¨,þw (Ã#ýƒÖ'AÿŒ±eCNƼ™ŽM‚i?øv}GèYÉûÔW!(|!­ †3^þvûŽÝP7wl>-”†#šZ ~E*´€K+#?¡Â¹Sà7ž¹Ç—Ÿe÷-…ì0:çÞÑ£´²ŸÍvG'Ù'gß=U«_Áª596Ù•eJc—ÑŒÝ~Î <´iˆð\HûAòb¸ŠF£^4Þò•uu„ãc3k±ÃˆÍ²„Uy#bHç«eù¬$¾2‚VÚ%úðTagEeÄ¿âjòÅÁ[éýð¼“ÃœÙ(_³{Žrx!f®,{-&—¬“.f¹,«/BA³\ª˜³âŒL¥`]øÏròDŠ›i9@ü„Ö7LOYëæßœôš•á‹š é)Ñ´Më + y1Åg…÷bâÏ^êp®O·–Ü‹Äïùãáâ‘ÝT©Õ1z}:Zôiá¿O–áˆ9i-ƒ—…Ë;ÌgvÐTD™dMÆ®Þ ±™“Æ,K ½ÿŠµÄÊ™<…õ4Ë>ˆU6ç¦e#úY* FìÌŒ%ÈÜÍbJÎZ.…P8êqˆ´íˆ15k»F§ 7·Œ—Ô® ¨ ©>!)S!œ1:Ð?"“¬:2éÑäÔ‡Î&0Mv`êáp INØZ;‚!>²MÆBò{N„î)Ìq2‚”v&;N.èÙ1†ÞjûNVÐîÚï]ÛVD’C.Ø×4ñ¥D{’CùÞö¡Të¶ %….¨üh;X[§¸wÕЗ^}têÓ©ó?ÐΘúrÀôÇ“^Îî%íŒávôR¶·É¡¢rºè:-çv»i9W˜)íR ±Å­í˜áàöæ™ãØNš,ë½B1:í°á@LeNrÞ(û–Ëá³ô8(Ô;Ë?c«ècÆŽQ3aÎ<.4‡Ë·ðäBÛ›CÛé5P˜>ãJ›œÊp÷åßr‡w)0°òT g1„Ýu¨cl^¥7ÄaÜØLi>ÎÎ!‡n—Ç…˜_2Nυþé¹PØ4Û_m®ó•èöEZÖýi{· gÈè3ˆkŠÀOšõåÞÈ8é®®Ág )ô½Ë(3BY2`šTó`xŒÂša+ðY!#2 )P.ßt„(ì˜Î626vzÐøêp”|k;¯ë<L•Ç÷uX9¶©¨þt´È,ž'ÚD»ìÌÀâP~*jÜ鹩 ³f ¤CÉ8YÕþôùh Ì Ò”-ã”NÚkeÓ+´õvm] *Ãaÿ0uNc~Ť°ïr1|‚ój!•E¦š…±#»úÁÚE±ŒÌåbƒvŽØ;8Œ¡\\Ó9K•‹›}سŽ”'÷ì`Þ9vÁj.*‡BѼÁÀLíÂÊ‘M#Ý$Bðo: ü¸2ˆÒ0Ü'j ^Õ.øŒxW»Ú36ÀödØ"ä½qQj-þ¦䘕I/É÷0Me‡›g½ž˜6«ç „›{žÁ³¦Cç±ÎÊ|ÁÑryn\ß½\j^ͺ°ÃÆÊ [ûØS‰G.,‹òšßÊe;òºTìÁÄ"6¹âàVػʆެðªçjuꬃƒ(ë#SíòrNãTì…Ù¡ØKÛF/ckE8J8ƒv?òŽ2ÝáLhC9ѱÎSïUØV up;ËQ\æåg(üt°!Üf"Î\!‡=ÅX9ì©`ÀæÐ…yÂå„èy…Â;D¾¿BäÛ+D¾¾ðµ¢n’ÔóaŠ§vÍ:_Œ¸<7…ÇyC>g{õô/q¤ÿ÷pãž,f©/¦e@+gµi‚ NÕ&ð°6Ù$UI0{Õlrٌผ9Û)Œž]²0v(Õê‘Ñwx}¦m¡™{@óŠ ëBóJ3€f,ŽÏ•¿z…¯5üÉa©zÀÍ:—~kB_Ûeè«÷o1㞟ÐÙ*ì-KQ7…ËWfv¾‹F*V0‹iCˆBÕÍð’êQŽU×N7Û9;¬|„Á…çáTÓ÷w¡CÉV›uêž;˜VðT¦I=úR‚>!Ô©ÕŒ§û…M–¡±Iåñ.E=}Ðv¥Ù‚žÆ4-e‡©Ô¼I—u~‚=ï0¨¥N«Þ°³‰–8­Ð@×®òén)ì}œ±’ƒÔ:ÉvD!`B;…[ôêÆ ŒUø w¬z÷.jŠHK<ÉÀH©8Ô{Äî&Á16P¿# YW„×”&Ôåyõ}“âûÜ;¨Ó›Ž4”wý_;y{a±ÔMW~µÅtÝWLÇÁ"6GHˆCŸ:˜`94µ‚¡BŽ¤_ÝØó)¾ŒVtP¸ÏÀ“‘ùÓ®Œ„£™YHt¬Dé?ž<é¾q˜ð¾ò´‰E×1hpËØ¥‹Ÿ86Ž±;(õDZkØ(ÜðZ_%Ü¿pШ߽¼ƒI,-î€hìû„—ÝŽ×^d æE³ ôâúfWÞfôà-´Á±GK'“5abДa,÷>ïö¶`†c'ÃÔ-.%Ó3n O $S»Qì2bñú‚ÖÐŒ(©ivá…-­9ðªL/-ìRšâK‰p© ʯ£Ó2ÌËûð"†ÊôíÄX3yE¦yO]?Óçà ÍhæNÓL&Ë‹DæKÓø%{J.ò¸ÌŒuáìÖäƾíò9Yms¡i|ËâÙÒhçM>-|Ù\eÔÓ\hÖßQ¾WÑGÈøšæŒS˜àÅs^4¶Eß·ÐŽ?¼œï%ÿW¬Ua°V§ð¿þÄضkADàwf°b±:v *Ég›aÅ>˜,c³ñ,m™ym3d‡•œ…Ý…yÕ'•á¬Oò÷Š==t|¡Ÿd˜ KF³Z—>Y„Ј™ým–({Ó½¯…­X›ùdIWJ·7ü­8„d²Ë€B#VòD'qô·˜òf›2:;06.s1^K¿…õ )˜'ã$žn3ý3£ËkJC¶ã[`ê6wŽõÉJ)açI*Å\?†ÚA#Áƒ»Ø†ô„Iűfl¦4ÊzÊ·®z8˜£åøFœ†ÝŒ_i8ˆGßóh><ñãÇ嵃¬öÃœèŽ%ŸP3>M]‹2Ùè]›²Ú¿ÂþÖ}\ÀfÆa+8 ¤n–+FU󱀑|æáèéÈk˜“¹[b9˜ Ä#r2³›ré¶b_Òæ'÷Ø€nÍ#âæÖA£ÜMóˆjŒZ±äS#‹Ö£Ÿ{C2Ð+µ!7·y:øt†ÿW2O/§í¤¤_3eGa3Vy:X5‡jĺ47ã'q¦tô7¨Éx›ÐŒGÝå/‡ªÌ{Ìq!Ï8…'Úótâ¹*^#ˆ L o%‡-ZôM툣LøXU²Éz&¡ýdŠàžRS×jmĵÔøÒ¦ÀÇhî*öÉ]ûElÉÍG1,Hvk>‰¾¸Þ ºâúIWKc‹ç*ôßàø­§9~‡AQÁn¬?rä%ØÌÄÔá°*Df4G‰¯Ú^Æ` V37SŽ×i6z"ˆKk;Ìa]¦2,|Ýç¤u¥{Aßd\ÐÅäj=ŽòžŠ2΃\-—c[÷!;mcQjšñ9cÊÅKzFj2Á¾–äŽÈ Gîª[¯œeð$J«2Â÷ìoÍ<6tíC4«Z«i²~5D´rÃ`«È®³{Ð^"T5°— 86Þ˜^*Ý ¦ EdHycãî«Üä¿–[«G-æ}´7 o,pÚ¦>òT—;|bìmY.î+(5Á}ÊkgJGVÒ¡ï-_îÕt†iÿ0é÷Ò ¬«å`±?ŒÄ¢lD²;:gúÁ´‹¤SÄ&ɬò2&¨üv#Äo•ItO²¸ü¬KõÑÞ€Þ·äcC ]%9G(m c^³Y˜“í|uxCébF~yãl[•&º,Í%A;7Ï^)|´ÛʽA6œ‘,—Ï„9‰¯ Ve6G¦Ó |o`ðá©ô"WÎzEMÁtë¸Çï+s&m+Á~ã÷½ÌzÄè4W_þoM£ ;ß|­zy³îh3ë¸U82ý÷&ˆp?6w`¶ã´[ƒàÃdô€öTaò’.&íiyæ÷¾—]Rt$Ù`Áh„·Å#˜œä ašÕ½§¢»Ì 0j=8´·q¸èÈaäDZ5i™¤:(ö“žH ˆ“÷î" ¸©¬Äožcµþ掉5EgJrÈÞÜÏpV»©4"œ”Í.wª-<7‹—âHi„Ζ¦hLå MÅùA*?7½=wÞЦ8* •Áf—"Pgx§nžU›"Y¯ÜCßmæ…)ËúŠÌÀùZ²/ÐhP8%7Ú˜ ÌQ[sHh£=×¼`_ðš|j»>ØÚGL3× ¬nŽ3n÷l} ‹ÀHÔÍðD ¯†7âå´V$Ä´ ˜®½ûSGq z÷6Ga‡rcþö>S°„‚h¶j·) (`JkíÄ-¶%¶*ˆ10•\!Ç-cŠm&Ý2šY;ÐÕù›7¾ëÃ4+Ì ª[]èéÔ‘C®Ÿ!¸Úû\ƒ{‰xsï ×,×l7¯;Þâ$ÂqÖ0¾; §z³Ÿ±o¦ÿ¯j7Íh˜Ù-ú{¿Y؃úØ£¹ÔØZˆPDF™ãØqpØ7Â÷šHÐXrt;˜hff—„hqAÖÌÙ¬jN®m.šDç<Å›kªZu5Ï»ÄÇkÇ‹xókëXÞ¢0(Þ'›¼¾úŽCåqvŽèvÆÒ_1c:j»BÇÇç b7ÕUÝ6ÓÑ1éúì÷Vå˜ù=<€«Ã›U7;r®zÇUmÌ3®êvëKH3‹§;YÚÂmªwîW}ÄUݬáªwù¸ª›áM¬_÷¬êŠ¨Š yþ«2´bê³=‡«ŒÀŠaË<š_ΘUK ]}ZÄw×ö‘á‚f£?Ù†¾W­ò±ú©¼$¨i†%mÒ6~ ZM}XÕñeµA•iGàª.ŽQlwU½‘ƒr¨0r°Úî½zΆëÝÂg‡›m£q-6—×ÍB>aÝÌ6áUWû°¡ ¸š®jè`ËßÂ[ˆ‘ÄÏt¶BÕâgÚ†\é@”5÷dnˆ¾c?ÇÚFDçÊÞøÔ Ñl)f%Ñaô`r‚9bÏ}Øã…àçgËœ±¢ºu>ï6ƒáÜ-‰A75¢å7œñ-p˜òB` ?!¢üa±~…÷•T'@4 { ÌLî;0áV¨ðåm·BKÚœ…JÖˆ£N›ä:V촎ȹ<œ£q‘a/¨Ía:Écˆ[Ûjòæ˜f¿uò€¤ ÛBŽ°DTÛ»ñ¹í»îŸíŒkž2(°ÕqŒ,L`ã°$Ø°–ÚB°HÕ ‘êx ž=£‘ý¨)'M„»KI"|Ä'?l»E@ÊØ:¨vÇbÀbU?.v2˜s…»ìÊlžú39CÉÎÎé#ÃcÜäOÈ›0Åx¹¦Ã8—*ûKo,`º,6x®ºjÝË$+U›D‡—Kšõ›åóåU–Nßä2¬RÁâ¬RÅš®Xp»Ú ˆ©íû¥Í­äÚbä‡mêà›ÙˉÎo¨ï´ù76?´OX⇺ª‰Í„©ŒñÓÕ¨2Ùð0Ø­ÎZ]3t;{2Ñ*c]éòb c)0š&뮃ÎÒ5D°jv‡_­ªw›Ì¯dŽ^ÆWï– „ ÊaU«*ÝQUkÎ ]ÐõüßõŸôW«÷{ŸC7»DKmâ-tæÅÊ`±F0K¬‚=›Bì6‰e¨lÿÁqؼ3aÒÍ@[T; ”Ëb¤hfT~Ïl=ëv²•À¤1ŽùÂ~4ôÐP‡©X°ŒS¢%"¡t!ûtFëŽÖ‹YÂ@-’pM'áek•—é›: ³d@§b“2–”Û!f7œyz0¸Pz}4éíX3XõúôYyÖÍôújuLÙYÕ–¨u3:5›mF°kê*¸_}[¤î0<5ûB3Z×μA˨®‚n¦Nš‚ေ‹v{1µ2Îê HÏ0:J32Ãá"/-õ¸Cq¹q¸$–V•nú5WëL¿&Hº6‚ºëלÍ­ÁÐRÜj(¦I7õšpX(n‡ú]v(Þ¤i9ÒnØ/±N+ö'ߌ¼|¹A+32Á¦Dž+/ÇÙ1þ1ùúö†“\m¡ †c…‹’'ÕËñ}Œ—Ôbx¿\—<Ø:Ž’Nyá3‹Ô…Ôu™3UgÆ{jâcl॥ç–ÛSuVì¤ê,Q_ŸÁÓR,¡ˆZ™'ñä¸6ÆEÊX„ƒjÄNRÁÁš7ͨšâx ×Y9ßÇÀP4ÊUüë¯,0íI¢èö<¯-&AÕQG8P•Ö`F8¨&èúü’ŽÑk5A…Ó¤(÷l- ÇBâ>2èMRÌÔè»´¸·-èÉH1¼2EWlL£°cNŽ„¥ARN,;ÖrÛ2ìAIÒDyÒ£éžQ7Yó=¥Ô²ã7kŽ¨’L‡ÍÏSñ¡º'eÌ4ð1ˆÂ¥<)¢á6©tô¨ž`)š%3ò';&Q:aÌ“¼1Íxˆ…4[Œ!p:‰•)‚$º>ýŸÁð§2Þ¢Ó÷ÀNA¹#…—`¿lEeœ\’M:c„¤’Ä°)þ\5"~0ˆ“d Èj—6,…þ•¨€äCp I]œôzE¶Š\ŠEʨ"Ó30HG³F7ƒ{tšÞ›Ë­!KÖ¶£•ô±ðI¸¼JU§K”5ø!Ì£&-Bìê±µŒ‘q”j­¤TWQáH©žºš#$f»ˆÅ®‘íE´®›ä¡Ÿ™µMZwG(•„Å–‰ì->9>w.bæåå ËÜœö±÷B¤¡Ë¿'x«urˆx±u$]¥ÚªŸµp%½Ý C†Û‰^9¨™Î²“1‘›N±2¹ç»úÞ4RìµrÔ¹õe+ÃòØ•«¶•ìW ­²ÆM¢¤È]’(V[û@ì©=JÑ'Lu!n“Ô $*@¹=i*Pû@J ÜËK‹€: ì;dµ@‰^ê“ÜÇKØ€¢ ì\’bà·hÜÄsrHϨ}4i£«,«ƒ1crJÇb§£<6Š²…GGç% :‰1R‚Ó Æ¤aT¹Ùê!Ê1@­ ¶ì«Ò…¥Aa<ÿòóýnüü…¨h’òt+-DqHÇ$o5Ñ°Ï`JÐQ*,Ò†Áñ]N±U÷Î- NžR©ÆDfÅš~98ûE9²ðÞòcÁ>©qMPcÇFKÙ= 'JLËrV͹ciÐàvP]Œ¥Ñ$m‰"|²fi½õ!í•ËÒZÝp#·XêOhtÒ®¥›Á§$ó>œ†Më,büíiBk Gív/!îÏ{ìA¬w„ýYȃÂÄe· ýDòÃÁÄ%—…€BÖµÚHµWï%pˆ³Gƒª…ßð²¹1aƒTÃYXÂá“èð±‡p„k'ÑË£÷vâи©@7íï^Mm· "ª½~° {å†ÙÕ®¾Õö¯`‚ó–.¹j‰^„µ€­Õž<ø+,ivðxàˆcßÜÅ6vc¾¼¼íé°RÚ w˜ ù8|x6‚¥`q¬pÜýZfÁ0îÜkºwŒëCƒU‡Ëa†ý§8šl½YXlŠiK«Jƒ¥b•óõˆb•ÌõBÅñë«›O ¨< }¬„ {ý)êöèÑ!<½þQnvFXï×ÂZL€X#@«åç½¥C,¿YPï z—ÉDD5„G¸DdxÀvhäžK†UçÙA_¿÷‰©*„ͨil8£öàÔe¯öì>õ">rYÁ÷nÞá1äcTIè;ÃÃécR1§2U‹˜*LØ;„»G~*ØÓàµfy[ŒW÷ì2ƒå¼: 0äʪf»7¢œdÖx)†06Pòw™³œ ‹Ö^ÇÁ–mBæ–(£p£cÝ‘Ëa8ø¢Ý1Pî“gRa^5ówµŒÉš°žÞû[_è‹(Ä»d2…‘X/ƒçVÎ\l´%’aL6Á7 ›@  É"ƒxV ±°0YõŠÉ‹ÂÊ}Å6ì)êVö»Ëv1ò¸më! (cc;NÞŠµ²—Ù¾@[Øv+ò»m«êÁïþ}ýõÀZ’6Ûž–“tk’YûJJ`+w³¶,“ÎǪµ¶ðÔW–UÇ©}&-™r”ÙœÌ6¦Å’uËYá…aö ùã9³/ªˆá-ö³B©‹RI´ç¢¥QÒ7­‹\ÈÊE‹¢Äd¨L ½= ¶Žc*—çé·´JßæâCÚ1T2EŽ[Æ•·M)Cª\7Zö\7Zó¤C‘HÊE«]×=ûæâ•«ïx¬BÞbq»ÑòæzÒÂ&5¡‹^—Ë´HbP®±ÃÝËE®¢޲ȩ}î-ßT.ÆŒ™Y®„}úí½yš…aoÕm{o>f¹î͵,ÔH®®?ù’R¹¹Èë¼ÕV Us ðÔ=É€÷»ÌÙV`,3 ÀÈž¬S.žE¥ì„®ì ¸B% mê â·äk\}gÓêëu3ï}‰³0…ŸÆÁÃ×i½ìÂ÷fí7á}Ù¯ÓD©ÿË=ZHWéÍ×™pPÏ%§¾®ß¾~˜°Mw”É‘rI÷·,ë<]þ¢PñiÙ8Ôž"¨ýg|;”÷˜ÊñݳNfìYǸ‚(R':`¿rÈh¡6ïåþ3éÁ}5+}8ËóÂqdÁáX°ààè´I$°g˜sȯùÁ‰ 8odYþ9Ÿä˜ e”]‡Ä„znÊaÿâ¼”³Ç#lRYß—ZIJüs³í¬Ðv)Þk¡ŽLö˜…WÊ$ÑgY" úý‰SØã·˜?TAê á5@"‚"K²±æy¦zJ{Žä‰Æš·©|Ïi¢k-˜%8pnÏÅ+•°ïŸBO:ÓP'Q À^/Pg¯)ÂÛ#ÔXÏBß0 ªR¿£§#‡ÂÝ‹½TuÛIéÊ5jŽT“i-œä>ÑÜàþ_`h:8á•”þ CÓÁÊÔÔþ õnŸx^1çÙ‰íp)›…ÿ„Å-½ ]§:““¸1Ý¥µ)Õª ¼=&¼"}©ïô0ô’4{O8RÅÍ‘êtAL9Ów¨¸½]4ÅFÒ:XÂÕäÕ’u ³²fÊbåfòÁ;Õ G­UË”®Vå±â9 ˜+¢ç8k£†}¾ý'³ûqªà¬*K¼¤–çÁ"Ë&ÄA¦©ó¦WLFÈûŠ<€·äàð3ËœççfZ]e¯€Ú[5w€IX–y $Ç•L^•›“<-žô‹ñ-貓i1Lö1a‘5æSÙc†Üftçœ|” X¢,ú™ïÐéU“Ló`fa–UzDÀ W%9–”<¡SÒHy*˜`˜=ù­ª«_fÙzî Sðà·à#¸I0™í«\LP$çѤۓí ï)ÄLÊÀKo´hCy‡Ù¾ÀS*læ‹íï{üšÂz,ÀáÊÍÒä Æõ–K²"³¸CA›ý˜‹™–Êéz™K*RÁ›æ`NÍ­L1ää1Ø<…Q©G¯ qò„†N­zVä€1·8» Âry^ƒ¡ì ³ôls_‡†Y¹¬šÂ2&e¼ï sC¹<×g”i&‘¾´šø\ÏõwÛuƺ:LÐ+Îfƒsè0ÁóXLæ…ù¡HÚÆÅYtH4s[Á‘âgRcÉëæ·-Ó1[T„^v§8v²–i¯ßZÙ†÷t¸2¿©#ž;Ó+ë½Ð¿ZžûH ‚µ¨Åh2×TZg=‹j‰&Í1Uævzèß¿®Ÿ÷~GOÐ ‹­ …ITÓ͈ }i_þ¾¨€-…ù ;#µ7;õ1(¦èW/H[ÄÎDJgº[+—ÊTrÖÏý&n‘¨·Òˆ*âë÷Ež{þ¢,\Vÿ"Ñ'7ƒžåØúc%Mj7šÇ ã÷/& a›ç/ ø9‘Þ¯œ)”Üyäy±wø÷Ξ¿#%›áï_wè-?1¦M§î_¦'`Våuq65Ê“ëËG&ߺE_U0`… ê¦NW‚·õ0ÍÁt¢«`k³*Sn' øU5X0å¿ë%Z–ØÌÆëŒø¿üõàa(ŸÑ$ògüžðÜÇæÏé~€Íɳ}#‡x±S)¼jÿKw¡ÇAO#:Íw7[Âx6?&ŠðHˆ*½Õï_Ô&¥àÌÜÔYµKhf¹­—žt!·]Ôá‚¿ÊÙN3Þ¿¥;¿P`}}·G†pK)þZª+³ƒPúÕþoü ºÆÍcÉKé``ÑäTX7Iu'¿OëšïS)„5\kúÖ±(á_ð{kð/’¾ÖבE¡ãølâR³nXÚR÷Àâ…ÂøÜM Я¢«©–‡‰êû_Ì¡ßиQ£{0€+óû0«ïïƒÝ30ú7Ž7a ª&‡Gâš9»srgƃõc¶Œˆ¿Š>Ï…ÒÀ<íy'ñ+}• ßÔc®t¯Mἦ~@!bñÛ~-E<¾B%v­ÉzFæ`|Sæ Œ÷m–›ì%¶ú¿žìný&å-sû«œå<º<’zõñæ×™¦5˜)œbñ>Pƈ>Îù<‹§78÷Hö*OÇ©Óf˜qæ{”]5+4ïWrYß”ÚöYé¶þäÈ¿ùæoŽù›Wþæ’¿ùãoÎø›'þ憿ùàoø›÷ýæz¿ù݇ÓýûúëùƒÕýfr¿ÙÛoÆö›¥ýff¿ÙØoö›uýfZ¿ØÕFõ›E}˜Ó¿¯¿ž?¸Ó/¾ô‡#ýæE.ô›ÿü"=¿˜Î/zó‹Óü"2ãáu§Ôq|£½åÆÁ;ùTÑF¨åQVþÆ7A»Ú»{‰S‰Ló¨Êt0nz†Ž3‡LM™ÉTÓ•Ðã¼C&§ÒøØÀˆw%.¾ëv|èØt"pç­*@7ƒ àiÊ÷WèˆP ü&tS>CiUÖ¡ŒR‚IQ$;Ù<ðûÀ3I2YÞŒñVKÒ!3Û*P"@ÚLòz`òVÁ¬=2G‹NÀz oG9‘>—>¢~mhŽúAC€HQ‚*ÐvîÄ7µ½Fº¡êÀ%÷†‡û®Û<–aõí”®]Àäxj¨Ô¸YðäŒUâÁòͦ¨¤B´>œúíß»%æÜãå¥ñ,xÏh(%6ÜíkV¾`‰ *¿æÃßSÒÚb„(ÉÔ‹×Oímµº`ŽŽ¤S»—Üì—Ú®O®xeFÝÑÅÆŽ¯œ6sWñâÏ‚(°ûç#-EÎ@ôüJI¡fG†aOòæFîÊkô’%¨Á®ÁÄ!qFÌ&ŠÃl#—±üÈÝó’V¾—¤A\L˜ì¦-(Í9›pz”ÆMºÌOÜɽäˆG|.sEñ¹Ì%•ˆd½GÌ­r…ã8¥ãù‘R ä¢æ4ä¨ÒûBÀPï 1D¾/îKTü+YˆŽ t$9máÜ&Í5ÔWšŠ8ë*6%©r€K"ÿKÂ2œ™°Jˆ%†ã¦¨ch;›ÀM£©L¡¸µ#ÿ@ŽšâàŠCpÈUe˜½¤S…õQFOœe•í%¬ezKd2³¢GqÎ5¬mÊȆWrÜ“Ñy¼óKv‰mÁ» €%#ßš ”Š%Á35"AŠ„0 Ø0ú®(àjÍåAG€p….`SFªnÈLé Wùv¤/0Ê»£ïF‹,†#Eôˆ»EBC¸z»Ói¯ªXë-ž,x‘û¼†J6RÝ™®×¢(o9äð,ÊG~ã­¹ñÚ8êoI—ŽÆÏx+f¼d2Ž6Æ[㥂q¤/^zo‘‹—²Å‘³xiX¼…+^j/‰Š—.Å£x)P¼e'^Z/‰—ªDHIüž?ž¯˜ÄKAâ%q´"Ž@ÄGâ¥þð’|xé<¼Ä^Š/‡—vÃlx«4¼¤^z /†·òÂKnᥱðVØj o …—nÂK,á­ð’E8Z/„—êÁlÿ©ƒ²ãaVýïHŒÒ7x‹¼” Ž|ÁK³à-TpÔ ^’/‚—øÀ[qàÈ ¼´Þ‚GEà%ðÖ Ø"oe€·ÀÑxÿßlÿCññúßdþÃàÑöß\ýCбòßTüÍ¿“îßLû½þpê_Dú7{þE™ß<ù79þňÓà_Ü÷Cx±Ü_Ôö7ŸýEb1×_tõGýÓ_lôýÅ;‘ÍÃüM+ÑÇ_œñQüÅSÂ_<ðùûÅø~Ѽ7·ûMè~³¸_Ôí_û´_Ìì7ûÅÁ>Äë7ÛúE±>¼ê7™úÅ >´é7WúE~³¢ßLèûùÃx~±œ?Ìæ›ùÃ`~±–?Lå;ùÃH~±?Ìã7ÛøÍ0~³Š_Lâ{øÍ~±„?Ìà7øÅþ°~ßLß7»÷Íè}³xßÌÝ7[÷ÍÐ}³rßLÜ7ûöŸý°lßÌÚ7›öÍ }³fßLÙ7;öň”›U›ŒV&Ê0§)OÆî™-ÍØ=Çì(÷ÂŽ‹9ÌÚù2N+‘oaÒfbö3cúü툻c6aÀ ö훡Û#Ù¢ºŽ½w,^°x¯¶qqÿõŽ§½¹¾®ûiŽ!¶PˆøÀŽLýpƒaŽ–¨!@¬7e¢Årì/Ƭ‹uîVÜãYÕ꽟/ÐƒÛ ‹UäñA=__²»—½¹Êƒ²Ÿs÷‚á'vÞܽf¤Ó›†GFöŽ÷‹óŒžh™P:$F=½uD¯L[Lœr‹€³§KÄðËûÎbßä®GîÒpçœ>Âßy0k{päyRÿp°+EÀÓµ÷åLnãÜ#ûö»S°;Ño=þ—g|+òsæ°H÷”`÷ܳ‹5?¨; ¼-Š£Vþ—/'<íì“á¸Ño)n-€T"¥â´oÏv× zç‡[θn/=ˆ'JV™(÷¬ wÉm>9—gb¦ªÔŒþæ¨3ëäK?¾·òYj%aÆËì292ZJŸ""Øß\÷ÑÂô›))ã|Æ)?yáƒ!Y!gþ¤äÏ™fX¯ˆÎ|£seG˧X*MΪscž)¯x3H¶L±ã™_î=úÏ´úÌt¤]Ù‘©™†Ïimô“ˆ·Ï;•æ—Ã(½½2çÈu•}ât XÈs¬Ø4«§½ÖçÐ1yiÀ‘cUW.NoèV2á–‹‰˜ddM[¼Ãxi (šVå˜qi¼3ìŠ|X;?WŒšµÌ +@›¨·6Yš6㲿dç˜Cˆ—éÓÜ3eçÑ“s²{[õÒ8¨3¢x)„“›oPøUß”±iבÐÉÎë‡éÌ9C¿Z ™¹Dõ^ÌGf™h¦un8&Õ*Jv¾§”}ÎÎ3øÖ\ü^ÓËùG3UÞ% ’#çœ}É$—É|¥Ú¿µð¼«Â6;"ã…œf—¼óåõ ±+jÓ»°"¦"§‚‚¬ #é5t{wΣš;™ôÎÁ÷Ö’  sÙÜlF#D“·öVëŒa°ô·ùÚÇ¿5)2˨ny³ö32¼gçû£{/i'B·•"¹3²àdëÔ¼µ-`ܱ››É@Ÿ•AKv‘ñ`’eDgÀ©•˜.[ã棑Áö· Û_}˜J ¢NÓ1œ-]ÞúNûJ½ôl}ºÚþŽ_=:WRo|ÉîƒÿÌÇÉœˆÅ'ëY‰ès6·›],´y“ë'1ÓùžÛÙÿ¯¿è÷´$ç²3/1àÅÙ™² XØNyuN%1¾^Of ¥¾à>`;¦Ƥ|‰µJ``sŒb·Ýî½Í½‚­N„óŽÝþ*Ð <¢§M–Ì]sú‡3öÐÒ#.˜¾ôÈÛ¸€±Žxÿ™”¡WãC1Ñ2C•OíDÅ¢aͺeºüÄ}"Îï~¢Î¸SÐŽ, Èʇèmý¹ùÏ–%‡íÃY"Oƒí•ùV™ùPnsf›œŠÒ†+:+“9=¾Y»KúXwVÃwÖÁëguåŸÿø÷MiBD‡©KŽG:í1)Hä%“šfd=0¾÷¯ý×c¬C˜èE=™‚ÄCØõÂÓ¿Ž¿žÀýó/ýõ/¢ÙΤ€nQž¤¬húÓµí¿ž1ê÷õ×þ—ûó/÷ù©­êÞµ¿E–vLÕù+êÚ ç¯ó//VÂf„gº^í‹¿žçþ:NÌ*šV®·ýë¢ ôÏŸÿbŠ!ÿ墘©NĦ7QLô5*ÙSˆÀwþzOSDL¦u.&OŽ»½TM;ÆŒ %Æâ¯'(ŠE¿-1ü¦%šV)ZâupwÏÝ=AR4Á‹ÄÄ ·›L&b¢¯÷ÈdĸküõN¦)Þ!wtÄtpõ·óý‡owÅòä»sW¥þÓÓæ}ê§hžß×_®“3-ð|˜á›æËôPbSWÁ}™6Çl%öã_O`“ly Rhy‘ú¨¸d‚衬Aê‹»Æ_O`SüÆÞà³yƒ/œ®Ýã,úÄž˜“)¢Ä)žÀ£ÙÛ½ý56™XÛë|~­Ùë;1 …Á¹A3ÖˆýÖ¢ë®44½0ï•ß×_¸ÓS»mDLN/¬¯B¨Gc¹™y°~KyC“ ëÞÆ ·˜òU©v Uº¢Fñ×Ø”kQœõdF?¹e„õdÆJSœaºt ‹úlô¡J¦>×=Ÿø¯'pwÛ{ÆÚ¥¼ú.w”ÊÊ5ôg)‘DwM|„0öìÇ|8»½±ð&·we›r°79ç¯G­œ“g ¬‚Fž#"_+g÷WÑVßÖ;¾º£ Ù}Ø¿ET¢çG³—¨ÚZÞšsÛ½ÕáëAŒ-ç×A’}ÝIÓ¤HÏ/Å¿îÄí4Ô†˜(f× þ ›BšŽ°(#”C€Ø”Ó:W¤®:^*°c\÷_Ï_Âm~ 0ðÊdÚípqúÂþí GDˆ”Vk3®Ë#€ñ`ž3„£Æ_O`dFkiWCÏ1ûN9w¢~¸ï´ÉÊŒ?íåà6ãNüþÿÅÆ~£œ½¢ˆÒœ^¸GËüAi¾^¸F /<¢åž—háëOZò«‡1‰“{X‡ qÙ=ÌÂ…& ÛÜ+|EÛ„b‘”û §èa‡È|¿ÈΟQ´LG-¯m´2Ö¯¸†Dam¨2¶¡yØö7NÑ“r Y`PíÎÑ“r9=)—èaŸafDø>jDŽ%ˆíúdzj;c˜žÚÂÃJUmçǵ…ºé‘Qû÷õ×c׉MÜ–²¹^XO`L©–Œ ÷MÝÙ§˜Cå…Õ u¯bhHâÛUTB£0¤rÒ G­ã/Ôšª†^·(kèþóÂþ©šþE®áŽšÁu=ßÿ~A¼k˜kÝo‘ÝøǛfGÛ rmé…[´X×nÎAÔÍ¢ç†Ø7jêq!l‡é¾)¾§©¿î1ÙüÒãz#l×Y¿÷î1Æ5;P D¾O`«lp”R ·RÿÙ^¥Ûq³†ò!Òµ[˜úõÛ“Î%H~ÚP¿¥Þ¢¥CIœ”ò>Ûk+àse©$ù«S‹ÎŸ=;:ß=w+ýâþû¯‘O[\¥Œ(4GÀ“zÛ1ŠPwM«RÛñ^[@nÁn'mÝ9BVç þÛþã ¹9»ƒ“3%S„ãŽüˆPÓ *>ôèf¯ú'Ä­©W?”.‰¡î›†“1Ó[}[jƃcW(÷²k”COtwœ<žÝ]VŠ-jE·ž«eõ ÖËbò†;®qŽªeg:¦'Ýþšý ÷7 Â">JîöKSx ]ñY˜g×ß%;æ_ÚÆÚ8àÓX¿ã¼½ž¶z%Ä´9£¤qúRÒ¥’³Ï0PÐiY(7hÿ÷jûd÷wœ4¤¹€z„×ñhÿñÈ·.é–ŒÉm\=Å-ÈãB†H‡)êŽ}ÝzÀtø;‰}ôïý¼Œ¨~?0;pIâvÎÃòÕí´ÇTnµÇAq;ùass0%6ºƒ0};Oõþˆ»‘™RÙ­œ·ÍlÙ¶s? {$Ë¡„ËM­4I‡X¡±™è_û-ç G-¨,©J€X᡺ú#™m'œ#ÒTgs>6àè'ÈYŠ’áE±Q2•~v}DãŽZøG‘©Ã1¨ë‹¿äŒÃ! «—G, ¹’À}TïÝw¦PŽoÍšûÞÙ9¥@!Þ=[¡“ëËà‹áÀ‡ør»×?ï&Ì#D§¶Œ‘q+f‡¦¡2–÷QøÅpOté•hÉpïQzÅán éMñ–濯oª1„ž:"$b5lDD€M£àÄ0«2è‘ i´õ€Üé!Hºî«¹£“·£0‡ÕõF §ø&¡GÏ»g(™"d´¯<Ê0‘QKÏ[KÒp²ûæ¾3Ci|ë?¥œJÜ1…¢’"OâùTorôL®úþt»Ù˜9Êí–Ý•WâN¹çïÔlêw´]øZ«âуÖãˆsóåÑvûe¿æ~3Õ ñÜÔîß‘íÞqàˆP7D.8 Ë–øSºC(ÍéNËøò+üÇóU¤EV2Çê€ûåPµè{Ð Jf88D0Çæ4ä\sHÍzž#sÜ ÷ó˜RËÌÀ ¯±n-™=ÜñÌìY€¡9š)øÔì µôŸ›=Ýìϸ›“ÑgnO®ÕnÐ Ô0¦ÜLdì_9•û·ª…ÁΛ)ø€\/EI€tà œõ"^°u Ò`6Ýï?žv$Oûñºƒš—#° 6%Í‘AÃì´Œø_ÇÜ"vÈó>b^àö*!™â‹ÔíÃf…sïe/´íˆ«)Ðèöï`4HIXL fï1<É)óâ-B^6œ[?z$S©1å-\#mPOC>ÆH\týlŠFµºQ¢öÙ›dÆJxïL ÂÀq=Þ GT§„7쌱º1ÖÒâ5ž¡È§hŸð&Ù‡¼Šc.ø.Ù:ÓûÓYÖC™¨_RDAÔM[pûôÅîP#r‚ôiÓ8p5¯ãƒ0ujÒMÐL¡FʤªÄ4š†È©Jƒªù +ÚÒÿÑc>×qL»‡»Òa2~1f›ó›e²)ÜwÇkîÉCê0"5ŸQðzSÔqÆ fŸn˜I¢Ž|E 3ò.!ÀÈ·ÌwœFˆ1¢ÖH#.ƒ>¨T>°V²µ†Ü¬†/eu¤‡ÐÔ‚Ä+‚Îíá?EPÍkU:$ÙïÈïN— Ëæç©m1ä#_êŒÔ~Hž’Ãaœ–âŽøÇñ9Ù6 ÊÅl\BMKñ^"‚óY4ýëõQwc1xÞ­•m×@s9š‰íµñ¸$ìâs$›ì`¿l&3Öâ«ËÙâôÖ¼Ï`Úªž%Ò­š™åÄ}ü€eKå×nÚ.#ØlÒ@pˆ-°™n8¶¬¾;Ê®&®gž§¢Ù©5QS  ±ª·Ð±ae-ŒÆÚL‘´;ê›m bÈóQãl»ª|0î™w¥ó ÊMJYò8W¯Ó I€ŠÒy„ïlX7ùÝÐU_1 ¸ËªìÕ‚‰àž ³)Ï¿çGP6ÂÍa›bô]š<϶öRéHRsçkì·¤3ǯ™MÀ{ZÀŽ/šmÆ›Œ'˜±ÉaàŽr¥Æ=Ý—(>è.–®v­{3»‹¥—lœE„m¶ˆsøÊ Ñvið²7WUÁ•˜°4Š·µá0;\yšu¦B0׆=²MGØÕ¤"`HDÙb]Øï]ÓÙ5—*/:ãsë/Œ¡Wጡ õ=÷4!–3†¦[Tù`ÜS“óþÀ’¯ZSa•*›Rn¨>H/ãj‚¢l%ᔬ?æ®!¦%Òs€h°Dp(áØr.:½ ¦Ÿ{b¤!Ò¢ýGŠSö(cñÅÓìûu¨(î÷)ö¼JO^ûŠ½s…r“![éGSÒ™FrzaÜS; &xœñŽó਩j„\) Á$9Ú^!„ÔˆÌæù;Ša|íW²«J–HÝ‘tû…8°a·ÖÀþÈ»BLÜà»Q¥b—"êdeLVê`4Q.Q­b§%êu0›ýŽš;9QµƒñÛˆ‚¿ã3¡vë‡U‡vãDæ˜Õ¼ö¿!ìÃî·L-Ãlüïù÷¨Í d©lÉ" Œß‰oâ/µïÁX!ߤةŠ»lܶ–(ï³[2Zx¿•HýJV%å;»añRÅîY¼ÕÁ®ï”(¶À½/B§ìØ$i_ë!‚t6,¡,€ÄyÒÎL]ð¤è¹¦!¨ó¿a·dÄþ(»®^WÃJ¬¬‡`Y‘ƒ·B+«RìJF]F»èHƒÚGó£:SѵE…ÜŽ”b”ox¶.·°Ô´0#xmÃbÍi 8‹Q¯vgÖ’2‚s¹é÷ó3éó°¿–eØ7SÇöŽ‡9ÇùÔƒ{èÛò¹ÅÎôÝÚb°¬EµÊ6‰ 4(_“Bõ¡¢Õ+QC0g«^üÑZ¹Z÷â"™/2¢LqœÎ~ñ]¤º6Å‘:¨NqêSÙƒ mOÐÖž«*Mæ ÈaErªuÞpÄ/ ‘pJö‹ÉÊÄJpí;33Šo])„{GáæÅ‘EøÏÆHñejÜÅN|—x€ñ¯ ±×!§¨9õÙ„R¦&ÓÈ‘$èí6çQÛon‡P¥¸ŸÃ–.6½ÌI¸cq˜ny0^dî›úe¥ ,-Ì—úN–4ÌùÃôzXV'pÛ¯yn—O¯û)RJ7T•îhRo¹1¯—}S½ îÊŒiÒü-·ó¾ýž?+3;A/îÜq`¼ÆÛùÏ=DýÒMDÔ]6Fs[*¹ßç­âmO-Ñ•Ÿ×]ù/8˜—ál -rÑá„è u88*úi¿ëßo‰2É:Ôø©x‹ºc²\ ”lRH`î×)ˆû‰æ08{‚«x~ˆØ´ø¥âÔôÓdáüöŸ›Îc]ƒs=îOà¿({^ç?¬A ¸±ÓéN¤7võÓë–ü!¸zñKñöôÓäìÓj«{ÿø<¶ìÇF Îußu?ÿ yü¢¼~Áëñ‹òùEkÑ ’F–AÌéN"ˆþ¤Ž»ŸºµøK¿êWãoýÊ» úuªû±­ãõ¸kk¯Æ€Æ}ö2w ØË"IâÕwõS=·äS.û—îü©; /êû±¥ÆÐUÓƒf„HÞØ÷€‰*žzhð—ü©‡Fëghìjú×9fŽ¨¯ƒtâéÙÿ!åuRP2 £a>³ïá97ñlÁ»xám<»ð>ç×¼ñyÇÏ¿@S[k ssD.M¦Õäëâ„°á“9Ž~§xÓs;­-ºŸ¦aÝÐ’·¼ãÆ÷žÎyO¿â~uÝ[F.Þ ö[ÆHš,^2TL=¿æ¾WlÞÏ oè…Žw<¸Ä¨{¦HfR_k z·6Nä_íl§±`8'…G3ox{ ’Píêvñï;{Ä[{gÀ{{÷À›{WÁ»|Ç.„÷÷‚}Ú@O¨3ØK‹í fïÿsãåFÙû §ƒ•¨3ÒâJì,xWË2Þè±ÐÞª¿\oèXƒslY¡Ý$£œÓ§Jè!Î/¹2§°…"ša¡´Ù\kËlÖúvR§Y'víüÃç–ñ®š?Ì…ÛXg´Ií…GìàY­ÈVÚnÌNÉ“ÀiK=™é~Ùù˜÷T:|ÐÍÝ™_I€CûmÁ~ò·ÇN FDÎ'PÊÛàÏÚá·Óò¹Ñ TëvÛ§“@¶”Û‡¤‰ ÇO$'[RŽ#²§6ìv2%~#yÜTÃMżÍÒÈŸ¶kÉÎC*[o³¸œL»š»´}x,‰‹È•—‰?Ø~œó—_ÓÞ¾çÁ#¼C|ÓH“D†òÆ=¼L|Y{Ÿø¶ooß×Ó?T#H+5({ÍåSbPÿ6 1Rrp¬\Œ‰©¹º9„K™nÃn×*5'›¦æ›³¢”çn‹]MûYO»'YQ»-YÓƒs¸9YW»?YY»EYÛÈ)EêëÆ=Ü«¬pä "ÍvãnZÖÙÎÃÓ%Pk°å¿OP~Ì\BìT0ãµSÒ†Óáû3ñ¶Pwfüˆhò郞&G?F²¼ÿ»Îv£áๅc£šqo‡`(Í–”ÎÇöíOö¶køþŽ Ÿ2àˆ¸2(N@eøè÷jûñÉ“´Ð rû³mBè„ÌÐg„œîÁÛ#6…Çô¹CS&¥oY?„¥°" ÊêwÁ§S Ʋc@„S´ F¨Q¸õl:Ÿ"p@òS€E|+Õ+9 &jW›D®VÄ•ì?ôŽ=!L!)“±3Üþò°G\ˤ²‹>6š¬K¿e˜$Í°ïP²aC‚¢o”ì‰ÝGþx©µñëÕïç t9& Ì0…„Ö-Í_†ž£x0𻆞(; ¤#Å‚Š¤P°{F$ÞD` 6EINŠ€#ÇIÑU¤5)芬&Åb‘Ô¤-ågmQt)+¬ ãò¤×Ï0$å°L;XŒd8Å)¹œò]2‰.™vïˆOÛ]ƒ•ÓÑŽøЊ‡¼/Éê2\rüùÂ-âbQ}…,¢ÊŠcgGÁw Á~0|‰ê*6µUÀ$øYŠ¢D­E¼%X ÂŒºFLz·±‰ä)d‘Ô!E2’Qt;éNŠ¸G2ÇI☢$¥¤\) ¡3Ü¡–$„)“|°eܨ%îx+"òr[:Ún÷þ°D0E ¾™ -‡†öp’a ¦’ÂŽÑ¿ÝPŽ¯Ã{§?ÿe8ïKsŒ0ZGÃ`» gÍI1[IqÇh™áì9·#”£ÖñGk“f3œx¥EP0‰5Ùdf„“V£Èb2£†ÓëôˆC&j8ç+¶wÿñ8¯§Û§EX0)[·³¥Ì"&ÁK±ÅÊclxG$òîSxÈØáó¨—¢ÔQ-Ũƒ¼£P|PwŸj(hµP$?(K ï¿™+ƒO\ÏU8v|>oû\Å£ƒÉ¢ht4©¢ìÑ¢Š±‡Eöƒ€þó¯]븣Ù¤ÇøÏ"TÛôïÆŒp}Rcâ %‚ûÇ;2~™N®íÜAõä6)ÖžÔ&…à3 ®"óIëRÀ>Y]Šã¿O.7ª‘*t|w/>º=e0' ¾1*«Ž2Žz¨8ú ˆ8º'ê&¦ ª¦§¦ld•zmÆΘ…O.—™XbÀð)$Àð)ä¿ð)ešƒW§©H==êw4íȼ—ä{šêbÖK÷]MŒ!çE#“d% Wr•‚w²ÿP3™›BÚ’†>YKšHZÁ…œ%uRR–ÔsÉRRw&-Kä²²Üñ1gz4DŸc-®i™ï~ jN ë Šæol4Q7qÙP5 UPk4”©™Ïñ_ÏÿDlỈš_©ÄÏùÌ‘ÑÀ;Ñ´×\Ž×²n  iUˆ7‰§˜ÿ×IáS’c2øØUHqÑJJ†‹–¬Aòbo~–Ild&iÅ#1I "yIÁ Û<§ÛÑ”2²•´ö’¬$¹JZHUÒâ@¦’V •Dn#«»G_‡P…§Š "6 Ñh'BÄtídP moú&©‚"$æj| Þ»NÓ¡Á*Ñv­ªí$U{L!>ym…´G¯DW´­H¨hZmj@ÒN¡Û‰§³‰­ñNQ“sImÑ&œb´Ú£“Ø¢»awEÌ%%ÃEg¦:Õö›”%RÉXO•„%m[;éŠ%»>›î¹ÿP‹›Jæ’ö±‚µ¸ÑÍ+%…©»‰7 •Ô,m\wŸÕ[góÉ…X„RîÈqmÓã ýù›  ƒ{£Ãª©³Y/‘•ìÌÀéÑŒˆ›/´ˆYh&±À Òù ¸ÑÊâ£éuÚ&Ò^“†Hçà°·ÜQÎÿ¼jÑ^Z´Füñðvf›3ͱ ‚½¸6¦š“#¹L²pàeÌ3ÇšfNR“ß‚êÄ%Ǽ‹VÞÜ”f˜“Û$‚9©M:~“³ñýÇðöÇ4·œL.#wgÿ£®aù p…¤^‘ MB¼éÒxˆ F0È\^’ DDl0}d$ÄKÈ,ˆ7“Q\!IV©^¢•Ö uhem™Å"à²ÈL+ÄÛÛ"hY)[@=YVÃ?ooa’ed¡&W¦î›ZŒÂ0`é rfd¥@³¬±$>…ÒÃþã xûÍ-A:”´#Ȇ’¹•Ô.™ 9ÐÄÖ¥ ÇKVI¦÷•Ù’l/3 ›¿¥¥0HûjþÂó-PX¢7°³Y‡ Ár"rC(×ò:” –ñZPÍßíÏ;·­¦Ó(!ÅéÏ·£à_ u´’µŒåÉiT°â 7dkR׆ÓÞÝ":†|q¸·£ ÓÞ:)mh¤lßá2ܨ½ÃÅùo¥­‹D2ü§äòÈÚB*‡¥nN;²9døȃHŠ’üŠ†Ý¯eÉ’Èäº4lnëå ¹,—Cb™œnä•ÉgÈ›µ-•ƒ³ulöêÖº!×L.Á;»X0‡4ùfgrØ"-Šà ^0d‘´¥ÃšÒyŽù¦èÔ¦°70†ì”XÒ¼AU%î† Y·øª«E 2½,AfÈ·f† nM1ê­?&È­_£Z÷ƒ`Y|LŸü$KÕ¹•ÇÙ—+•¹ª´TXEJ )ê:;öߊXr®R5®Þ.B‰1‰?>ÈrcÌncÞ\Uk‘I¥°)A  á±›3§¸!Ãéæ²Ê˜ô¹Õ3ÙÊXX7C]yõ þñî–#ÏNa-†Ý=Ãzb$Ü)ŽÄ°¹gX”ŒÌ;…pFÏØÊV•2q”d4Äó˜Ò]rŽ•q Â,ßË Rï5äó°TH»£ÞÒ½‚Ü#€àfá^ðÞ¶n/f Šëz¿þ©ˆ•—I™“d¯ ÷Lû‡²^/o¹^Aumæម<@iõ ªEq,—R/©šêt„ÚþãaCZ¥—N‰ôJ£—™$ÑKV§z oLëó’Þ)y^Cýl†8/9Ÿ¡¨»ÿx µ˜Õb¼d‚J£W°E¯ÛŠ® *Z†]PMqI¸c–·²» 1>Û?ÞCjçsn!w,ÀÖq´Œ;•Ñ¥â>óq' ÷øãù ‰!BÁSµÜ ¥Bü’o?IêC¼=þX·c~;I·3ž”Û %KË„yzJÏëM·j;'GG}™v¤g³z;(ùß¿ÝÃrí㨵#ÖŽ{X«}Ô-ÕNJíñÇC:íÌÙ$™v¦r’z.¡DÚï´5Ú)²íñÇc(ö—>;³GI¨œPÊ×óˆ³Ãþ¶µÙãÇPÊì‘—0;ö<ÖeW^¤è>Ve'™V¢ì‚vì?CÍJ̹¤%”©˜rÛP³RÌ'jÿ“Æ">çß®ŸìÌ£ï‚Uݹ-#µEüñ:±E›;¯äÌÖBPF½ýÇcØß×û¹.=qd>sB $•q> æÖ‹tñÇcXß×ë¹~¿¯ßûºYàAÎcÑúNcAY,â×pç°ˆ?öõMáh ç¯`¶·H_<g4¾sWô“º¢¿óS¼FÓûúþ¥´zEde%çmȘ”—!fâÓ"=žOáþ*#\ºðó-c<^e¾øù–!®!ÙÿŽY~žžÄåÔaã!ü|Ë‹dª2àÐ…%XbË2²Là[øù–Ž6¹ÿŽY>íëÄÍBå~á)ü|Ë—qÊüëWûº°ˆ–*c ›ðó-#lÑD–ù³|Ù×…ïW™À{ø”!î¯$½âGJÑq]Ø)Y&p~¾e„E¥T™?ðó-cœ_e¾ø±~²¯—W™/~$¼º¯ ×Wàÿíçÿú+ýü7jJÿSÖ–“é{ŒÔ²ûªóÿñ?ýõ¿®#KÑüû_Jielø="õì­½A?Ø"¥“»]çvÄšÌ×<½8Ý—ë”a/vËÕc0ŽëYÃjUý%‘8tó4™Æ²¹Ö3N€Ë”™í•ª3’ä^Ìã;1y®žÀ>gmo8ÚÑ'¹†}ÑÉŽqp"4¦ éV˜Cs‡âyãí•0:Äx£þ~›©¤º|Œ AÜcD0¯M$3½ÎÌ5v;6Ï´õ¤fcBØHÔË^)‘¦Í#‡‹Kñ»vÙ¶ÚI{™`4¤Jµ&ß{áüÏ¿˜¥ØÁè0É8ôYÐ4£ràEøüQ`Dð´ 2p}ªì} ,hRÌý‚ðù L§€¡¢¶ŸoÂ| ^„,;÷UÂr lŽ•ìòŸ„õ0l„¤‡]qU°†™ðù지¡®>Ÿ‚ã„´„øcíJqUð> áó) 8OÃLȲ9®:Ú6¼ŸOÁt ˜³5ŸOÁ| ÖˆøÇØ÷UÁr fÂçS@°ž‚u>Ÿ‚í0O1²Ëß °Ÿ†ºú| ŽSÀ0>¢úªà} ’]pŸ²÷);OÍkן‚ó0L„ϧ¡Â„YÀ5ËúnÒUÁt vÂçS@0Ÿ†…ðù,§€¡8,»é‚õ½1ᢾ ¶SÀ°²lŽ«‚ý0,?ÚP¼ ŽSÀð²²×»€à} BäKÔjôG_œ§€¡Hϧ¡HL,PWY¶ÆUÁt ^„ϧ€`>¡¯Wò)›OÙr 6B–mqU°ž†™ðùl§€áEȲ=® öS@°K#íù§€aûÑ!ç]@ð> 3!Ën6à<!Væ);wY±$X  ®>Ÿ‚é0¬„,{ÇUÁ| fÂçS@°œ‚X’ª¿ÛŒ«‚õ0„ϧ€`; %0÷| öSÀ0ýÈú—0çøªà8±$ÕqÊŽSö> û,O4#úªà< k0˜^Ûµ ÔÕçS@0‚¤ö軤«‚ù0”Øâó) XNÃJȲ%® ÖSÀ0ý(è]@°¦+߄ϧ€`? EPbÙWÇ)`XŸOÁû0”zäó) 8OA,IÍß­ÅUBq«X `'|>Ó)`XYv_̧€áEø| –S@tY,I½œ²å”­§€a#dÙWÛ)`XŸOÁ~ lZuëþnw\§€à­«Ï§€à} 6ÂçS@pž†™eg\%'ž^„ϧ€`:±$‰Ä‰uÐWó)°éèæð½ –SÀ0>Ÿ‚õ0ÔU– e[Ãv bI’ªÊ«€`? ¥û| ŽSÀ0ZÄWïS@«÷){Ÿ²ó0„,[â*¡(¯,°>Ÿ‚é0”¬ïó) ˜OA,IG›ÅWË)`8Ì%|¬§À²l‹«‚ã0¼ Y¶ÇUÁy | ËŽ¸J(S œ„ϧ€àyyC(–N·C° Û)`˜YvÆUÁq ŒÝÔ>û×+®R—úº¢À†…ðùL§Àº¾¾*˜O]£ûŒ®Ïè„åø@÷_¬§Àzûª`; ÛO÷$=ŸÑ û)ð^[|UpœèuÞWïSÀ°z¿ã«‚óø@ï'}•0]»@ÚôûŒ:¡Ïè„éø@Ÿq|U0Ÿ賞¯ –SÀð&ô¹»Ÿ3ºH¥.ð¶ô8£¶S ÅtÕ㌞ãª`?>Ðv9_§ÀÚ>é«‚÷)àéõ"|¤yä«‚óø@–Íq•PGp˜Qù|r'L§À²ìˆ«‚ùø@–­qU°œ%–…”Ï}U°žˆ²`7úOØN|¤%å«‚ý0,?rÚлૂãø@–MqUð>îXB»Îèˆ,õUÁy | Ëö¸Jh¡‘^ÿ„,[âª`: !˦¸*˜ODYŒ€b '`9 ;!Ëö¸*XOdÙÈEaØNdÙWû)°·3]gôÊ̶pŽSàY¶ÅUÁû0¼ Y¶ÄUÁy | Ë^q•ÐâG(ð…([öUÁt NB–mqU0ŸȲ%® –SàYöŠ«‚õØ{Ï®3:Â}|U°Ȳ-® öSÀ0²lŽ«‚ãø@–½âªà} | Êb¡ª¶pÎSÀ0²l‹«„ÖšB/dÙ}U0†…e¯¸*˜ODY,TÍNÀr | ËÖ¸*XOC]eÙWÛ)ð¬‹3® öSÀ°²ìˆ«‚ãø@–ŒB†÷)ð,›ãªà< •“e±PùäÎôD×.ð…,»¯ ¦SàY¶ÆUÁ| ìcŸœð áZ¾*XNDÙÍÈ7¬§€áMȲ=® ¶SàY¶ÆUÁ~ | ˦¸*8NÃIˆ²}_¼OdÙWç)à3úõ£x)F(ú*á9˜ÿY6ÅUÁt | Êb¡¶pÞ–KpÃDȲ¡§`XNdÙWë)`˜º Û¾*ØNDY,TÃNÀ~ | ˶¸*8NÃBȲ%® Þ§À²ìWç)ð(‹…ÊÒŠ€>˜£@ÀJȲ-® ¦SàY6|æSÀ°²ìWË)ð(‹…Ê’„õø@–ÝWÛ)`Ø Y6ÇUÁ~ | Ë^qUpœ†ƒeÓˆ«‚÷)ð,Ûâªà<>es\%´qJe‘‚mÚ ˜NdÙWó)`¨Œ,y Ë)ð,›ãª`=>p•%!®ÎüpÛ2/B–ç*`?>eë¹Z-*â€)«Ç¿Í°ZTæºx™w\±ä_)FŠ£¼%§gÎGˆã…ùÏ·^¶§¶ÞÛo †wòeë°a#i‡r&•ý³~b lH…ãÍ1&=ÎÓ¿š¼m†§S[ÍÅé?Ý+ŸhaO|W[èÐ}m¡£KÂJ,יÒ¯ÎØ5ƒ¸á ' ¯«y/zH«w3c·¯wãXùÌ×aæ‚vŸç×WÁE„K‰_…ÁŒ‰ÍkˆŸº€ ¯>jŠ«‚å ¬]ðù¬§€à%ø| ¶S€°4ÁçS@°Ÿ‚—àó) 8NÂl.Þó) xŸ‚— Ê–}Upž„© >Ÿ„<©€ bþJï‚鬂ϧ€`>(oCöaͧl>eË) X*pùªa=ÉR«õ”­§l;‹àó.`ØOÂq >ï†ã,‚Ï»€á} ’2WõÝZ\5œ§€`|Þ%øÅ‚ˆDLíÚeÛuʦS@0 >ï†ù ¬Cðy0,§€`v(äÒ|Õ°žø¼ ÎSàQvÄUAή*`XŸwÃz | ÊÞqÕ°‚Uðy0œ§À¢ìŒ«ÿ/[÷r%;$ízÞR¤µˆ; Á Ôhè?=næCô?©z–ïÎ[dIÁqû Èn Èvƒ‡çæ„ŸOÉ~°ƒ[p~¼Üvo;NÉtƒ·í ^ž6ù”¬7¨þ´±_rrÞàái³OÁ ç·d¹ÁÃÓŸ’íà·ä¼ÁÃm7PåäFmÏ+2¶o7 ë ž¶ù”ì7¸5 × ž¶ûÄý(- 3¸5 ë n»{,§d¿XÀ­ˆ Š/O;}Jæ€Üí·Ýâ–SrÜlàÖÄÆÇ‚—羸ŸOÉ|°ƒ[²Ýàá¶[ïrJŽ€Ü€+Eðò´Ù§d¹Èo È~ƒ‡¸?0§ä¼¸À­±`ãs‚ž¶ú”,70ž=…ò•Û–ÛŽ<¼Üv3gNÉv°‚[rÞàái—OAܼÓ²[²ÜàáƧ9v·›€ÜOáž7yhuò1mŠHÈî§p×›<ܸ;6Çî~“8’à i´p¯›<´ºø˜Æá“%ä÷S¸ëMZ]}ì71ž}‡‚Ó8R¸×MZÝ|LÛj2û)Üí&­Ž[¸ÇMÀ ±a²äåÆÝÍ9v—›€ÜOán7yhõô±{Þ¬à~ ?–¼ÜOáÎ7y¿'3ßßÜ Ø@n˜%žpCbùü)ÙnðÛxLÉ~ƒ‡ÜÔ7xÈcLÉyƒ‡<ÎÔ\7;ÈcyLAZð’kg˜’éÿµmø”Ì7xxÚìS²ÜàáÆÊ"¦d½8þøê{{1*¦d»ÁÃs+üîÓ寯àá¶Û§sJŽ<ÜvvNÉyƒ‡§M>%× À n» <§F¼ó^|üò´ŸOÉtƒ‡ÿÚ¯ù”Ì7xxÚϧd¹ÁÃm7Ã÷)Xo /Ó^ýûOÇÕÒìŽú²¶uönù&xòÜ`g °lh'nmû—F쀦û«•xiÛà(žayÜ4ï¡Ù²#:üâ6Jç§v!èái{,/g¾B‹Ý`»'ß%!v™Ž âï»ø¶ßÙcµwv”†ãR;ÐÆ.Gµcc|¶Sûøž+>¹Y¦Òù°Xuî‰Ç/Ǿ7ü¡/Û÷ÍþsÎ|ªÈþ½ÅÏ oy`ûöã¶}6,ÕÛƒ‚#»ßãl±ßØcÇÒ–^p{';:Æ=ðDˆut›b©ÓöG{œ†(|ƒå*ûFIÛŒc‹i_GýëåË®Ï2MâuKg&ùåL0N ¢ym}¹s8KCóeáÖ×;‡‹4t‡­ïwWiè[?înÒж~Þ9Ü¥ymýºsxHCøôçÉËçð”†Î°õùÎá% `ëË›yI“5Þ9œ¤ym}¿s8Kc>o©–xÓY¾Š.Òж~Æœ®Òж~ÅœnÒÐ>}I1§»4¯­Ï1§‡4tƒ­/1§§4t…­¯1§—4t­ï1‡qª;ÃÖ˜ÓIš×ÖϘÓY:ùMIì}NièÏoJb› ŸÓUx.Øú¸Y‰»ICOØúsºKóÚúszHCØúszJCs¾qY€Ïé% Ýþxo)ÛØúÆ¡ w…­_1§“4¯O6~)œ¥¡ l}Ž9]¤¡9·þÎé* `ëkÌé& ýÁÖ÷˜Ó]š×Ö˜ÓCx,ØúszJCsnýÓKzÀ§·»‘ñR+3ßìÏw‡­Ï1§“4¯­/1§³4tƒ­¯1§‹44çÖ÷˜ÓUºÀÖ˜ÓMš×ÖϘÓ]:ÃÖ¯˜ÓC:Á§wÿoxJC°õ9æô’ÆçÅ㋯“WCãâ*4?¶¾ÆœNÒж¾ÇœÎÒж~Äœ.Òж~Æœ®ÒÐ ¶~ÅœnÒ¼>½ý]ûU[æ. ]aësÌé! ]`ëKÌé) aëkÌé% `ë{Ì̓ïózš_[?bN'iè¶~ÆœÎÒÀçyfàõmçHÄçt‘†ž°]ç–bNWiè[ŸcN7i^[_bNwièóº;ŸÓCºÁÖß9=¥¡+Ìk}N/ièâ·h´S>‡ñâ64?æõˆ>§“4t†íZÇs:KCsÎk#}NièÞxe¹Ïé* \Ìë4}N7i^o¼ÊÝçt—†ž0¯õ9=¤¡9ßxŽÏé) Ýa^¿êszIC7xãÕÿ>‡ùv¿Öü˜×ÒúœNÒÐÞ¸Ïé, ÍùÆŽ>§‹4t†­ï1§«4t‚ye¦Ïé&ÍkëgÌé. ýÁÖ¯˜ÓC¸pn×G§˜ÓSz¼öÚçô’†°õ%æ0^,‡æÇÖטÓIºÃÖ÷˜ÓYºÁ¢ûœ.ÒÐÞ¸øÕçt•æõÆå¶>§›4¯OŽy9§»4]¾6<¾ç˜—szH3ä{Çã[JÌé)Í”Ÿ-_|^ÞrÅ,©{ÁÖ÷˜Ãõ» m¿{•¯K1§“4éþnW¾6aÆœÎÒäû·Vùú„sZþfÝÞ¸&Úçt•¦Þç¬_|ÞBÇܤi÷¹®ò5&%æt—¦ßçÒÊ×™Ô˜Óòœì^ðÆ%Û>§§4ónk*_o2bN/iÖÝ–aýªØv·Õ1·ï6î o\MîsZ¶¹î Ÿ‡/2giè[ŸcNiè[_bNWidÿªñõC5æ´ìS¹l}9Ý¥áþó[?bNiè[?cNOiîþóàë÷ðyñøÂKºÂ§ÇÇá‹ÁŽ¹fe»ÁÖç˜ÓIºÃÖ—˜ÓYš{¬4øz>|^<¾p‘†^ðÆ‹!|NWixüûÁÖ˜ÓM:Á¯¼ð9Ý¥¹Çƒ¯ïÃçå-ÌÌCºÂ§ÇÇÁã Oiè[ŸcN/iè[_b»¦ž°õ5æt’†^°õ=æt–†ëWlýˆ9]¤¡lýŒ9]¥¡ lýŠ9ݤ¡+|z|<¾p—†n°õ9æô†î°õ%æô”†ž°õ5æô’†^°õ=æ0׬¬¡ÏZîà+ƒì˜—/ ‚“4t‚­Ÿ1§³4t­_1§‹4t…OƒÇ®ÒÐ ¶>ÇœnÒÜó ƒ¯Äç勪Í]zÂÖטÓCzÁÖ÷˜ÓSž?ú`ëGÌé%Í=—4øÚA|^<¾f®MYã.°õ+æt’†®ðÆ8}Ngièo¼ˆÝçt‘æž+¼?2>/_,o®ÒÐÞxA½Ïé& ½à;“úœîÒð<ào¼¸ßçô†ÎðÆ]R}NOiè[¿bN/iè ï·1O®M&Üàý6t’†°ýœÓYšsÿùpNièûÏŸsºJÃó€l}‹9ݤ¡3¼ß†îÒÐößÎé! ͹ÿ~rNOièûï?çô’†°ÿ}qsmÊ÷„÷ÛÐIzÁÖ1§³4<ȹ??pNiè ûóçt•†.°?¿qN7iè ï·¡»4t‡ýù–szHCØúszJCOØŸÿ9§—4ô‚}ûÂ9Ì[;YCŸãÊÉõ+iè$ aßÞqNgièûö”sºHCWØú/æt•†î°oß9§›4ô€}ÿsºKCs¾ß†ÒÐ öýÎé) Ï&Ø÷—¦ßÂÙ¼¤¡3l}‹9Ì[@Yã.þN?Øg›~+gs’†æ|¿ ¥¡;ìû“Óïîl.ÒÐöýUÎé* =aßæœnÒÐ ¶þ‹9Ý¥áyÀï·¡‡4t†}žszJwü2ûñçô’&nõeöãÎa¿UTwØw8§“4ô€÷ÛÐYzÂÖ·˜ÓEžü`?^㜮ÒÐ öãAÎé& a?ÞäœîÒÐöãYÎé!Mܚȼ߆žÒжþ‹9½¤¡ìÇãœÃ~K©!ž°ïsN'iâ–7f_OàœÎÒÄmoÌûmè" a_ßàœ®Òж¾ÅœnÒÄ]U̾ÞÂ9Ý¥‰Û7˜}=‡szH·T1ï·¡§4ô„}}‰szIÃó€ìëWSÖ¯&¯­²Æ͹õwN'iè ûzçt–†.ð~ºHC7Ø×÷8§«4t‡}ýsºI7W1ûú$çt—†ž°õ-æô†ç?x¿ =¥¡ìë«>‡—4t†}ýÖçf®MYã®|G=¬ ûNÒÐ öõgŸÃYºÃÖwièÒÐ öõsŸÃMžü`_Ÿ÷9Ü¥¡ìëÿ>‡‡4t†­ïwOiè ïŸ^ÒÐ ¶¾Ý¹™kSIÝaëëÃIzÀÖ—;‡³4ô‚­Ïwixðƒ÷OWiè[ŸînÒжþ»s¸KCWøôvÜÁ9<¤¡lý¼sxJCwxÿ4ð’†°õãÎÍ\›Êê[ßïNÒð<à[ßdnÎÒÐ ¶¾ÊÜ\¤9Ž[Kåoýç\qUÎÿí÷®K¾®k8¸ÁNà óå^TÈ“u¸xÙ~ñÿËÃcžr°Cq.ñÛa?—ížK¥èý&â¶ìÂC…»¼‚]j.ÙtYZ²Tg_/´åu¿q ]–ñÅŸÊàÛNó‰ºÞ‹…ü À6@<°ýîb.ºàܾr¨wa¿ÝÅpœ$â””YÜ™±ï`Ý +âìIÛOXÛNK¾€ÜQ±…/οØAµWœcw¾M°§òýƒÝöoؼ¶^æp‘æõéÏcîs¸JóÚú~çp“†žðéÏ„Ïá.ÍkëëÃCš×Ö;‡§4¯OŸÃKzÀÖ·;oç•ñ{šÿcë×ÃIš×§ïåÎá, ÝaëûÃEš×§ßÃUš×Ö×;‡›4¯­ŸwwièŸÞÞËšsxHóÚz™ÃSš×Ö¯;‡—4¯O¿Ê›Óww…­ïw'i^ÿëÏ+û|Ngi^[çt‘æµõ3æt•†.ðéSŽ9ݤym}‹9Ý¥ymýŠ9=¤¡3|ú|çô”æµõ#æô’æõéËs8·ù±õ5æt’†N°õ3æt–æõékŽ9]¤ym}‹9]¥ymýŠ9ݤ¡?øô­ÄœîÒ¼¶~ĜҼ>}O1§§4¯­¯1§—4ð·`ëgÌaì× ùñéGŽ9¤ym}9¥¡'lýÓEš×§Ÿ%æt•æµõ#æt“æõéWŠ9Ý¥¡l}9=¤y½ß®ßmÜÞoC'i^[_bNWièï·¡›4¯­Ï1§‡4t…÷ÛÐKš×ñóÇné6îï·¡‹4¯­ÿbN7iè ï·¡»4¯í÷mÅœ^ÒÐ Þo÷ï6?¶~ÆœÎÒм߆®Ò¼Ž¿—./½Kc>ÇIæý6ô”æµõ=æ0zи'¼ß†NÒ¼¶¾Åœ®ÒÐÞoC7i^[_cNièï·¡—4¯ãùm¬ûü6ÓmÜ ÞoCi^[ŸcN7iè ï·¡‡4¯­O1§—4t÷ÛÀë»Í­ÿbNgiè ï·¡«4¯c{„9Ý¥¡¼ß†žÒ¼¶~ÆÜœ¾/šðï·¡³4¯­1§«4ðyžI_•¾JߤyíÛwÎé!Íëý6ô”æõ~zI³â±H89·uð9œ¾Û¸;¼ß†NÒ¤x®K<‘†ÎÒäØ6%HCiJlëGÆÓUš»¿šx<" ݤ¡¼ß†îÒÐ ÞoCiàsÜ‘x<2JÌé) Ýáý6ô’.¼ßæ1ˆ5î ï·¡“4ô„}ÿ–s:K×ï·¡‹4tƒ÷ÛÐUzÁÖ§˜ÓM¸x¿ Ý¥¡¼ß†ÒÀýƒ÷ÛÐSºÂÖß9½¤¡'¼ßæ1ˆ5´ýÜüxä6t’†îð~:KC/ØŽVÌé" |¶³‰Ç#ÒÐUzÀûmè& lÛHCwiè ûñçô†æ|¿ =¥Áãøex¿ ½¤¡;lý¸s3e¬¡Ï±jâñŽ6p’†.ðþià, Íùþià" œl}¿s¸JC7xÿ4p“†žðþià. \2¼xHCsn}»sxJ×Þ? ¼¤¡+¼3.¼@ãðþià$ Üìë>‡³4tƒ÷OièÒÇɤ™¿ÿØŠÿ÷ûÞuæÜh+þí=ÆÇÉ$,<û‚úݱ:ç0þ¹ß ’m¡Ž‹úÙvºslT¿Î“ë.”»Ètõc¡®ßżÙïBÝ9Ù‹O¶ÓÍ'ÛÁǃƒy“…mÚÇÁÙósB lŸwðëé÷àÒùqî×üßÿÁò¨oö>ÙÕXöâ’îwoì'·ìÏ›_éʲDb? >ÝØòŸš-ð¡²Ce>äöñùߟ:~¹Ûd*ÜÄæ»Y¯§¡rk\îÝDZ¬ëpDzîOcžÒÀ•óÓã‘Åü>ÊÞÐý˺oÓcY—»üqY÷mà$ ͹õéÎ{,åzã·4KŸ¥/ÒÐõ˺oÓc)×:ÿqY7Ÿ÷|9ܤ3—{÷OwièþÇeÝ·‡4tùã²nn½Ü9<¥¡cY÷mà% l§¼ò’~ݾ|·q×?.ëæÖëÃI:ýqY÷mà, ìK¼û§‹4tÿã²î¿¦Ý9\¥¡¹Ü»¸IC\Öý×ô;‡»4æºbY÷mà! ͧùý6ô”†N°õ#æô’¶åº²¤_··ç;6îX6~:ICs©Øús:KCð~ºHï·¡«4týã²ô¿fÅœnÒÐéËÒOCwi`|Þ.}—~HCsIûôv*szJCx¿ ½¤y½ßnßm~l}Š9¥¡+¼ß†.Ò¼¶>ÇœnÒ´û½7üüG,Ÿ»åçãî°õ5æpO·qØúsºJSïc×ñû3bÄ-¯{ÁÖ˜ÓKØ—¾¤_·ßm~lýŒ9¥É÷wudé³ôEš×Ö¯˜Óò7âÎ\ÆÎÍþN1§§4t­O1‡gº»þqYú_“cNË߸»ÁÖ—˜ÓCºÿq™9·ËÏî%ͺÏ-sI¿n¿¾ÛüØús:KCÏ?.3? ]¤ym}9ݤ¡lýˆ9=¥™÷¹wññŠef8})šp‚­_1o¾<|:ÿqÙ8·»œìîÒôØv¤¯KߥÒ¼¶>Åœ^ÒÐõËÀO§ï6?¶>–‡ÝYšK¹Ö—˜ÓMšÛV,»þkbÙÕ=¥¡Ç—Eóy“HŸÃ9ÝÆË–ÿšsºJCDzâ¿fÄœîÒpÿçûã2áÓÐCš×ÖϘÓKš»o“¸¿* Œ}Q4?¶~ÅœNÒ¼ŽŸO‘ŸöEÙÐùË~|L‹<¾Øeó:~Ÿ¹¿ Wi^ûß/çí.õyC—?.ûá9ŠsºKóÚŸŸ9§‡4¯}{Á9=¥¹û®‰û«X.±=M¾¿Zÿ¯}€s˜û¨ÖüØ÷8§“4tûã²öi“ï¯Æ’ž7¯ýx$Õ{<’¸Šæµo¦z7÷QWs©ÏŽßgÌé&Íkëc9ÐÝ¥¹Ç#‰û«¶œÏýUxHóÚú/æô”æõéëÓKzþqÙï_ScÞîR›[ŸbN'i^Ÿ¾Ü9¥¡×—ýþ5-æt‘æµõ9æt•æõéóÓMš{¼™¸?œÇÃ]š×Ö×;‡‡4¯­OwOihÎOŸæÃKš×Ö·;7÷ï6?¶>ß9œ¤¡9?ýYˆ¹9KóÚú.ss‘F¯ùíÉRüer%N¾l¥ÿÒi¹´Â?ŸRîá¡-#ò¡±eÄÁÃR[:ä!äÝi83Æ%2Û¼®ûkÏMŒ­îûŠm¾ùíØÙì?:ßu\r8€+‰Fü¨ýò¯ß¯Š?¯àU1ö6J¾8 óÌWû¿Þ8Ûuçæ" ]a^¥s¸JCxãìXÌá&Ík^Õs¸KCgØú~çðæµõóÎá) `»ªù»sxIóÚú|çæùÝÆýÁgëb'i^[ßîÎÒðê÷[?î.ÒÐÞX’9\¥ymËù)æt“†ðÆÒ¾Ïé.Íkž.ð9=¤¡;¼q¶Ñçô”æ5¯÷9½¤¡¼qvÒçðúnócësÌé$ ]áÓ>§³4¯7NMøœ.ÒÐÞ8ûésºJCgØúsºIózãl©Ïé. ͹õwNi^oœò9=¥‰+’_…u^êæWaÁKš×gc}næYÖ¤ûê•äWm•;§“4¯7ÎÞúœÎÒж¾Äœ.Òж¾Åœ®Ò¼Þ8æsºICwØúsºKóúôçe“œÓCºÁÖç˜ÓSš×gŸ}N/ihέï1‡ùŠk~lýŒ9¤¡ |z{—i^Egiè oœÝö9]¤ym}‰9]¥¡¼q6Üçt“æõÆ©QŸÓ]úƒ7ΞûœÒ¼Þ8 ëszJÛ›vó*²žcN/i^ó,¿Ïaž·Æ=a^eás:IC˜WÅøœÎÒ¼æU=>§‹4t‡yVŠ«ÈÌUš×¼ .ÅUdæ& Ý`^µ˜â*2s—æ5¯Mq™yHCW˜Wɦ¸ŠÌ<¥yÍ«v}N/ièó*eŸÃ¼rÌ7ç¼*Ûçt’æµõ=æt–&®L~ÙÙ‡ô«Èà"ÍkëWÌé* ýÁ§_wN7i^[_bNwixÊ‚­o1§‡4¯­1§§4ô„­Ÿ1§—4¯ÿÙ{Ór9 æ+e¬qØúìsw’&.RI\N²÷bår¥ym}ÌÝEºÁÖŸ»«4¯­_>w7iè ŸþÜúËIt—æµõÅçî! ͹õÍçî)Íkë»ÏÝK:ÃÖOŸÓ¼Éw‚O^Îå$:IóÚúìsw–†þ`ë«ÏÝEš×Ö7Ÿ»«4qñSârÒ¹„sw“æµõ1wwiè Ÿß_xHóÚúâs÷”†°õÍçî%M\Ѹœô•îsš¯lÊÿ[?}îNÒÜW÷s9é³ç1,'ÑYš×ÖgŸ»‹4t…­¯>wWi^[ß|înÒж~øÜÝ¥ymýò¹{HCgøô¶Ÿ†ÓÛô”†æÜúâs÷’æµõÕçôønãþ`ë»ÏÝIš×ÖOŸ»³4÷® §Ï¿sw‘æµõÙçî* =aë‹ÏÝMš×Ö7Ÿ»»4ô€­>wi^[¿|îžÒ¼>½íCât>½¤YòµáñÙç4צ¬™òøN<¾gÝs·<¦î [ß}îÎÒäû·3ñøÚ»ïN<¾°üͺ;|zÛ‡œx|á*M\tk¶>ûÜݤ‘çç‰Ç÷¬abî–çgÚž‡'ß³†‰¹{H#Û_\îp–®8wË6×Ý`ë—ÏÝKºÃ§·}H\sÍÊš%ûZ¸<â,-qîNÒpÿùƒ­¯>wgid_—Sœ¥ÎÝEºÂÖOŸ»«4r|dëWö‚:ÎÝr|ä°õÉçî. ½`ë‹ÏÝCÿ&Øúæs÷”†.°õÃçî%¬uØú•]Á9œ}ͪ‰;|ú³†‰¹;ICOØúìsw–†ë“l}õ¹»HCgØúîsw•†®°õÓçî& Ý`ë—ÏÝ]š»þœq9Ë9ÔçÜ=¤¡l}ñ¹{JsÏ/䯽½ö‡Ç^Òж~øœæš•5î[?}îNÒÄ«¨ÌÖ/Ÿ»³4ô„ïÇÏòñ‹4ûÜ]¤¡'¼ŸÆ]¥áy¢Ž¿¯\ïßצÐÐÞOãîÒÜóD9óñý|îÒÐ ÞOãžÒÐŽç\¾O/ihÎãù ç‰a®MYCŸãú\¾Û—Oú$Í=O” ŸŸ‡ÏÝYºÂûiÜEºÃñü\äù™kS'¼ŸÆݤáy¢¶¾ùÜÝ¥¹ç‰2.‡’Æ=¤‰»'™c{„Ë¡è) Ý`ëcî^ÒÐÞOCóåJÖ¸ÛÓúÝí)_Æ„†ç‰¼ŸÆ¥¹ç‰råãsw‘†®ð~w•†îpì?T>¾æ& =áý4î. Ïqîû3˜»‡4÷wOièï§q/iâåefßÃœöW>61çûiÜIzÁÖwŸ»³4÷és¸IsÏåÕ¤oÒwixžèƒ­Owiè ÒÐöõXŸÃKš{ž(¯%ýŠ¾|_4á Ûúðºs8ICsîëÉ>‡³4IŸ¥¡l}¾s¸HÃóD Þ? \¥¹ç‰Jâã+s¸IsÏ•Ô¤oÒwiîy¢’øø~wiŽï]MFû]áþƒk­ï9#œK*¾®ë„~W»Ð‰· ¶€çþ——€d^Š´bé›s^i§1ÖݵâiŒs“&?e‚KÇxY-–Îy¨fË<²å3ì²T[F῵ÃoÞ(Ç–Eøñí•ŸW–ükŽÍê'—GÈ&ÐOCÚ²~¿ßO«ã{á!“]Je‡ÿõ'Oî Ù†ƒ;À¶Ññ‹l1$Ý'O,â×"ø‚¶ýòdNÆÉ#ɱSÁ_È VÜxñÂŒa›ø·½Þ¶öÝ2îŽý¼ß‰½ß#7Øö^ŽÜ`Ó þ®m! l{/ÇhJlŒÑ¸Gl°í½}žïƘ ÝcƒóݨÓYºÅ;g™ÃEºÆ;cC‹¹o˜oC—Ø`?l¤ÙÐ)6Øö¦>‡»4ôÝ`gÙÓCø[±Áβ!§§4ôŒ v.w£N/iè»ÁÎØðc^rlŒ­ ·Ø`? œ¤¡kl°íÍ3|gièl{/JŸÃE:Çû¬5Ƽ´Ø³¡¿Ø`gìˆ`^îƘ >ÖŠ ¶½w¥7ån¤ÙÐ36ØÚÐCzÄ;—;§§4t vÆŽßc6ôÝ`Ÿ'PŸÃ<™´ª¸ÄÛÞ“s:ICçØ`Û{crNgièlmè" ÇœnÒÐ ¶¾ÄœîÒж¾ÆœÒж¾ÅœžÒÐ ¶¾Çœ^ÒмßæÉ$khÛùà '{¯QÎé$ =aëgÌé, ÝaëWÌé" ÝàÓ÷/æt•†®°õ)æt“†.ð~ºKCgØúszHC°õ%æô”ÆÏ/¾N<¾ð’†ž°õ-æ0O&Yã°õ=æt’†nð~:KCWØúsºHCØúsºJCgØúsºIC'øôö{Ž9Ý¥íy 'œ´¡‡4ô„­O1§§4ô€­Ï1§—4t‡­/1‡y2Éwƒ­¯1§“4t­¿s:KCgx¿ ]¤¡l}9]¥¡?ØúsºIÛ~Nãã;cNwiè[¿bNièŸÞ¶S˜ÓSºÁûmè% ]aëSÌažL²ÆaësÌé$ `ëKÌé, ýÁÖטÓE^ر`ë[Ìé* =áý6t“æµõ=æt—æµõ#æôfÈ×ÆÇ÷Îé)Í”ïïÓKš%?[<¾ëÎáñÝfÈã‹NÚÐòøþØús:KCØú;§‹4åþîá„“½.çt•¦Þßmœp²·äœnÒ´û·ƒNöÞ¹œÓ]ùûÅzŠ6´üýþØúszJ3ïsN8Ù{írN/iè[çðünCÛs×äã{çt’&ÝçÆ™¤OÒgi^ÿëí½|9§å9yÊs5N8Ù[,rNWiêÝà„“½—/çt“†®°õwNwiúÝ6á„“½÷/çôfÜmN8iCOi^[ßbNË6wʶëWö^ÁœÃë»{ÂÖß9¤¡lýÓYî_}°õwNWièŸ>Ý9-ûHKö°eï-Ì9Ý¥¡ lýÓCºÂÖß9=¥¡lý›+/V>M¸ÃÖß9¤¹ûºëKö^ÄœÓYzÂÖß9]¤¡lýÓU¿|°õwNwièŸ>ß9=¤¹Ç&ëEöÞÅœÓSºÀÖß9½¤¡+lýÃ\#²æÇÖß9¤¡¼ß†ÎÒÜãÍŠõ"{odÎé" =`ëÒжþÎé& ½`ëïœÒp}àƒ­¿szJs×*Öì½”9§—4t†­¿s˜k>Ö¸ lýÓIš×Öß9¥¡+¼ß†.ÒÐ ¶þÎé*Í]ÿ©Xÿ±·æœnÒжþÎé. =aëïœÒ¼¶þÎé) ½àý6ô’†ë{lýÃ\ó±ÆàÓ×;§“4t†­¿s:KóÚú;§‹4t­/1§«4t…÷ÛÐMºÁÖß9Ý¥¹ë·ë?ö¾÷œÓCzÀÖß9=¥ymýÓKzÂÖϘÃ\ó™êï·¡“4\Ÿÿ`ëïœÎÒÜõùŠõŸ³ôàsºHCgØú;§«4¯­¿sºICx¿ Ý¥¡+lýÓCºÁÖß9=¥¹ç_*ÖJ»szIóÚú;‡¹æ³Ô¶~ÄœNÒÐÞoCgiè[çt‘†ç×>Øú;§«4t‚OßïœnÒ¼¶þÎé. aësÌé! ]àý6ô”†®°õwN/iè[çp¿çLmýÓIºÃÖ÷˜ÓYzÀÖ˜ÓEzÂûmè* ½`ëïœnÒðüø[çt—æõéÇÓC:ÁÖ§˜ÓS:ÃÖç˜ÓKºÀûm`®íXã®°õwN'i^[çt–æ^ÿP±þSF‹9]¤¡;l}9]¥¡lýˆ9ݤ¡'¼ß†îÒÐ ¶þÎé!ÍkëÒð:–>ýübN/iè[Ÿbsm'«3¼ß†NÒжþÎé, ]aëïœ.Ò¼¶þÎé* Ý`ë[Ìé& Ýaë{Ìé. =àý6ô†ž°õwNOi^[çô’†^°õ+æ°_›$¶ã,®ÿ¬/æt’†N°õ)æt–†Îð~ºHCØú;§«4¯­¿sºICWØúsºKC7ØúszHCwØúszJCx¿ ½¤ymý››_›¤ž°õ3æt’†^°õ+æt–†×±|ð¿þ,]ùœ.ÒÐ ¶>Åœ®ÒÐÞoC7i^[çt—†.°õ%æô†®°õ5æô”†n°õ-æô’†îð~دMêÿ×ûmè$ =àøú1§³4ô„ãçÃ÷€‹4ô‚ãçŸÊýùûµIëúgµ$o’Ç—×&¡¡9ßO®GÁ]š×ñûŸúýýçµIhè ûßçô”†.°ÿýrN/iè ûó ç0¯M²Æ͹?¿qN'ièûó'çt–æµ??sNièûö‚sºJCOØ·GœÓMšsß>rNwixËûö—szHóÚ÷8§§4t‚}ƒszICgØ÷g8‡ym’5nÎ}ÿŠs:ICWØ÷÷8§³4tƒ}’sºHóÚ÷W9§«4t‡}˜sºICsîûóœÓ]zÂ~¼À9=¤¡ìÇ#œÓSš×~¼Ã9½¤áu,ìÇ_œÃ¼6É7ç~<È9¤¡3ìÇ›œÓYºÀ~<Ë9]¤¡+ìÇלÓUš×~üÎ9ݤ¡9÷õÎé. Ýa_¯àœÒÐöõÎé) =a_Ÿáœ^Ò¼öõ¢æëWÇ~m’zÁ¾ÕdýªùµIëÚþN}ýªÇœÎÒÐ öõ·æëWæ" a_ßk¾~e®ÒÐöõFÎé&Ík_ÿäœîÒÐöõUÎé! Ý`_¿åœžÒÐöõaÎé% =`_ßæök“†x¾~Î9¤yíëóœÓYzÁ¾þÏ9]¤áu,l}Ž9]¥¡lýÓM:ç·ý|®_Á]š×ÖϘÓCºÀÖ˜ÓSºÂÖ÷˜ÓKºÁÖß9ì×&5q‡­/1§“4ô€­Ï1§³4¯­O1§‹4ô„­ÿbNWièŸ>ß9ݤáu,lý¸s¸KC'Øú~çðæµõíÎá) aëëÃKºÀÖËÜ̵)kܶ>Ý9œ¤¡lýwçp–†îðéϺœÏá"ÍkëçÃUzÀÖËnÒж¾Ý9Ü¥¡l}½sxHÃë^>Øú"só”æ8Þï(çô{5ÝüϽù¯´kuøoåïx„ßð‚q»ÌTþËÝP.ÕÙ!Š/±Ù©P._Úicþ©Ø²N¿K<õe‡sÕw¯ïe ¶Yâåöà—nØéæÙÒ?±OåúÃOÝÙé nÆ>9­bKl|š¶åÝ~/%÷Ó?ö=¶û‚ê—¿Ûåëçkþ¯?ùó8¨‘/†±¯‚ q¶øÏ_*[¸ãˆðå“•\ãšâ/IwÁªßÅlÜyàcšr/Úñ6û%¯ò¤ÍZÿúùÎsþ'u`Ÿ–ùÃXAŸ¯µãûœ{¹Í1žÑ¸+¼8IC'xÿ4p–®¶¾ß9\¤¡+¼¸JC'xÿ4p“.¶~Ü9Ü¥¡+¼xHC'xÿ4ð”ÎœïŸ^Òж~Þ¹™oÊi;Áû§“4ð9ÙÓK’>IŸ¥¡+lýºs¸HC'xÿ4p•† aÞ? ܤ¡+|ús ês¸KC'xÿ4ðæ.„u`? <¥¡+¼ß†^ÒÐ ¶>ÅæÁóŸõŽlmè$ ]áý6t–†æÜúsºHÃ…’ï·¡«4t…÷ÛÐM:Áûmè.Í}Žî•o‰9=¤¡+¼ß†žÒÐ ÞoC/iVlKzåã[cËÁs˜óý6t’†Nð~:Kí [ßbNi^ï·¡»4¯­ï1§‡4÷@··!ý~IóÚúsØV×õÙ6÷þݾÒgi^[?cNWiêýÙö*}•¾KóÚúszHCgx¿ ½¤y}úùÅæÁž5îï·¡³4¯­O1§«4õþ®â€MºKóÚúszHC7x¿ ½¤ym}‰9̃%kÜÞoCgi^[_cNWiêýÛŸUú*}—æµõ-æô†žð~zIóÚús˜'¿­q/x¿ ¥ymýˆ9]¥¹–õU¥¯Òwi^[?cNiîBj_Cú!½<ŸÿØúsóàÉãÓ„3¼ß†ÎÒ¼>ý96àœ®ÒÐÞoCwi^[ŸbNiîöqð°4ô’æµõ9æ0(­q7x¿ ]¤ym}‰9]¥¡;¼ß†îÒ¼¶¾ÆœÒÜ}‰‘†ôCú%Íkë[ÌaY[ãžð~ºHóÚúsºJC/x¿ Ý¥ymýˆ9=¥á‰¥ÞoC/i^[?cóäŸ5îï·¡‹4¯­_1§«4t†÷ÛÐ]š×oüíszJCx¿ ½¤y½ñnÔ>‡¹Ïo»Âûmè"Íëwµö9]¥¡¼ß†îÒ¼Þx»oŸÓSºÃûmè%ÍkëkÌaî3[ãð~ºHózãÁ}NWiè ï·¡»4¯7ÞTÝçô”†^ð~zIóÚús˜'o¬é÷Dûð7ˆ¿ ]¤ymýŒ9ݤ¡¼ß†îÒ¼Þx“zŸÓS:Ãûm`î[óãÓŸ…]Îé$ ]àý6t‘æµõ)æt“†®ð~ºKózãè}NOièï·ýâ×öm}‰9¤¡;¼ß†.Ò¼¶¾ÆœnÒÜ eÆlÒ7é»4¯­o1§§4÷ÂÓ1§ôóö¼xÔš[ßcN'ièï·¡‹4¯­1§›4¼Pìƒ÷ÛÐ]š×ÖϘÓS:ÁûmÌó»ëW¿¶~ÅœÎÒÐÞoCi^ŸþœÄâœnÒÐÞoCwi^[ŸbNOiîzàÄ‘ÚÀ|1­5?¶>ÇœÎÒÐ ÞoCi^[_bN7ièï·¡»4¯­¯1§§4wít¦)ý¼½_ü7þ¯­o1§³4ô„÷ÛÐEš×Ö÷˜ÓMš{!æÌMú&}—æµõ#æô’†Â~ð~˜kûÖüØús:KC'x¿ ]¤ymýŠ9ݤ¹"ÏÒ¤oÒi^Ÿ¾|1§—4t÷ÛÀ\·æÇÖ§˜ÓYºÂûmè"ÍkësÌé& Ýàý6ôæµõ%æô’†îð~˜kËÖüØús:KCx¿ ]¤ym}‹9ݤ¡'¼ß†Ò¼¶¾Çœ^ÒÐ Þos­Øš[?bNgix¾ìƒ÷ÛÐEš×ÖϘÓ]:Áûmè!ÍkëWÌé% áý60׊­ùñéϹpÎé, ]àý6t‘æµõ)æt—†®ð~zHóÚúszIC7x¿ ̵bk~l}‰9¥¡;¼ß†.Ò¼¶¾ÆœîÒÐÞoCi^[ßbN/iè ï·×w›[ßcNgièï·¡‹4¯­1§«4¯ïǯòñ›4¯ãñâþ6Ü¥m?“ûÛõ‹9=¤yÏ'kÜç“5¥yÏÿÜ?‡—4t‚c{ºîöt}÷ƒ_ûþ çt’æµïOrNgi^ûþ9çt‘†Î°ïpNWi^ûñ)çt“æµïsNwièûú çô浯wqNOi^ûú!çô’æ^O²|}~ܹ9ÝëI~íëç>‡“4¯­ÿîÎÒ¼>ýwiè[/s¸JóÚúïÎá&ÍëÓqçp—†î°õõÎá!Íkë¿;‡§4¯OßÇÃKš{íÐòëÁê›y­—5?¶þ»s8IóúôMæp–æµõõÎá" =aë¿;‡«4¯O_ÇÃMš×Ö×;‡»4ô‚­ÿîÒ¼>}wOi^[_ï^ÒǦµ—ÿØ•¼ÀT¯Ù¨ö\ÍãĻͦ¶ñìX>7£á œÿþ«¸tˆ]þ*œoupó~Lƒ›Šv—KÎm=|iÃ.›|Z9Kí\"±?iÿ·vú×À®»Ü‰Ó–ܶeV¿Åæ«ô¬qgØús:IóÚús:KC'ØúsºH¯èÊ~Ç©ÚcNWiøŠ½[?bN7iè s£èsºKCøôí‹9=¤ym}Š9=¥‰Wìe¿ãTË1§—4tƒ­/1‡ýUzM\aëkÌé$ ]`ë{Ìé, aëGÌé"ÍkëgÌé* `ëWÌé& ýÁ§ï_Ìé. _q»`ësÌé! =aëKÌé)M¼ú6û§z9½¤ym}‹9ÌWéYãî°õ=æt’†n°õ3æt–†®°õ+æt‘&^]ãŽS_Ìé* aëSÌé& ͹õwNwi^[_cNi趾ŜžÒÄ+æ³ßq ?ç¸0%û]¦ÐÄË“²ßq #/¼8æË´¬qsnýÓIºÃ§·ßs?ÑnÎÒ¼¶>Åœ.ÒÄrÜq*Çœ®Òж¾ÄœnÒÐœ[çt—†Î°õ=æô†N°õ#æô”æµõ3æô’†þ`ëWÌaÞeʺq~úuçt’†ž°õ9æt–†°õ%æt‘&în’ãŽS5æt•æµõ-æt“†æÜú;§»4t…­Ÿ1§‡4t­_1§§4q÷šÌ;NUÛ/åÂ(¼¤¡l}Š¹Ùï2ÕþÞ8‚ö9¤¡?Øús:KÃ;-ØúsºHCOØúsºJCx¿ ݤ¡9ßoCwi^߯¿Ë×?¤¡9¿?Ÿ!?Ÿ)MÜ}*ǧJÌé% Íù}¼Ö}¼ü.SEÌù~:IC'ØâŽSæ,ÍkÿýŒ;N™‹44çþûßüÂs•†/æÜÿ¾8§›44çÖ˜Ó]šóý6ô&î—ãŽS=æô”æµ?ÿħÌKšs~‹;Nó.SÖ¸9÷çO¹ãTö»L¡¡9÷çg¹ãTö»L¡¡9ßoCiè[ŸbNWièöí‹ßq nÒ¼öíWÜqÊÜ¥3ç¾}Œ;N™‡44çûmè) =`ß^ǧÌKºÃ¾?wœ:æ]¦²ºÁÖ·˜ÓIš×¾wœ2gihÎ}ÿÇï8ihÎ÷ÛÐU:þ?æwœ‚›4t‚}Ïï8wièöýI¿ã<¤ymû«+æô”NœûþmÜqʼ¤¡9ßoóvI=`ßßö;NÁIºÃ¾?ïwœ‚³4tƒýxÁï8i^ûñH»Ög¿Ëšóý6t“†.°õ%æt—†Î°Où§à! `?^óÀSúƒýxÐï8/i^ûñ¦ßqÊÌ5+kèóý6t’†ž°ÿú§à, =`ëGÌé" Ýa?÷;NÁUºÁ~¼ïwœ‚›4¯}=Áï8wihÎ÷ÛÐCºÀ¾¾áwœ‚§4t†}ýÄï8/iè[Ÿbû]ÒÕìë9~Ç)8KcN¶ŸãëQ+æt‘†ž°¯G5YâÝ¡ØÐöõ.¿ƒܤ¡;ìëi~)¸KC7ØúszHóz¿ =¥yíë~)xI³äk»ë~)3ßõÎ÷€}=³ÝgÞŠMº?[®GÙqЈ®gÞŠ<¾#Þ¡Âç´<¾\²ß%®GICWiêý]åz”7ù `ÌMšvÿÆ]Oö;HÁ]ù{äz”7q= –¿Gwƒ}=Üï Oiæ}.âz”4ô’fÝç:®GÙq×£Ì\ƒ²fÊó-ף츉ëQ°<ßÒö\Íõ(;nâzœ¥ÉwÛ1ãf|NiÊÝ–q=ªÞ9]¥‘í)×£¤¡e{ên°õ_Ìé. ÝáÓÛq×£à! =`ëgÌé)ì/q=ªÜ9-ûK~ô¶¾Çö; âï·¡“4t†­o1§³4t­¯1§eØÝ`ëÒж>ÇœnÒÐÞoCwiè [ŸbNË1Î’c®GÙq×£à) g|z™ÓK:ÃÖϘ›»ßõ<‹ lýˆ9¤¹Ç¶w@—†ÎÒÐ ¶¾Çœ.ÒжþÎé* =aëkÌé&Í]»èÏ×—˜Ó]®G}°õ9æô†æ|¿ =¥¡ l}Š9½¤¹kSÝß‘ï‹9ìkPUÜàÓŸçÎé$ ÝaëgÌé, Íù~ºHs×;×£Îóçt•†ëÉl}9ݤ¡l}‹9Ý¥¡3l}9=¤¹kË=Åþ|NOièï·¡—4t‡­Ï1‡ý®ç]<`ëSÌé$Í=_À´Ùu;ÝoÏgÎÒð|ç§?ÛqÎé" `ëgÌé* áý6t“æžâ ÚìºÎé. ]aë{Ìé! ͹õ-æô”†°õ5æô’æžïã Ú´ý®çS¼`ëKÌé$ Ïç~°õ9æt–†æÜúsºHsÏçòmvÝN÷ë¬ÌUºÂÿz»nÇçp“†nðþià. ÝaëçÃCš{¾ž7h³ëv|Oiè[ßï^ÒðzŒ¶¾Ý¹™kPÖ¸l}½s8ICgxÿ4p–†æÜúrçp‘†n°õùÎá* ÝaëÓÃMzÀÖwwiŽï¬_ûÎBñÖóüéïº)dzvmþ-.`ÅÅ}X0À…þÈ÷ =YòÄ‘=±ùI ;ážítûѶàÊ绘‡ƒ6‹D[ŒäbŒ-HOC/ièï·Ûww‚­¯1§“4ð9Ç}“ž†ÎÒМ﷡‹4t‚­o1§«4ðY®À}–ž†nÒÐÞoCwièÞoCià4`ë{Ìé) ]àý6ô’†þàý6pÿnCœ[?bN'ièï·¡³4æóºó~ºHCwx¿ ]¥¡3lýŒ9ݤç‚÷ÛÐ]ºÁûmè! aëWÌé)Íëý6°aóãÓŸÃ;Îé, ]àý6t•æµõ)æt—†®ð~zJóÚúszI³îÏv,é×ígºÍ­/1§‹4t‡÷ÛÐMš×ÖטÓ]zÀûmè)Íkë[Ìa[’gãžð~:KóÚúsºHSîßÂ*ÒéåoêÇÖ˜ÓCØömÖ~H¿¤ymýŒ¹÷ŒBNð~:KóÚúsºJsŸæW¥¯Òwi^Ÿ~~1§‡4t÷ÛÐKš×Ö§˜Ã)ÝÆ]áý6t‘æµõ9æt“†nð~ºKóÚúszJ3c[€ûD= œ¿ÛüØús:KCx¿ ]¤ym}‹9ݤ¡'¼ß†îÒ¼¶¾Çœ^ҬضN¯I—ï6?¶~ÄœÎÒp[ÿÁûmè"ÍkëgÌé&Íëý6t—†Nðýzº|=Cš×ñûÃã)xJó:þy</iè ûó'ç0¡¬ù±o8§“4¯}ÿaúñ”9KóÚ÷§O™‹4týxgÊñÔä1š×~üË9ݤyíë9œÓ]ºÂÖç˜ÓCš×§?ÇAœÓSš×Ö·˜ÓKš×Ö§˜Ã<†²ÆÝàÓŸã Îé$ÍkëkÌé,ÍkëSÌé"ÍëÓŸã Îé* ÝaëkÌé&Ík뿘Ó]š×§O#æô†æÜúszJóÚú/æô’æõéñyñøšýjü_[_bN'iè ïÿ±[êÄÎÒ¼¶¾ß9\¤ym}¾s¸JC/øôsÝ9ܤym}»s¸KóÚú|çðæõémŸsxJÃã嶾Ý9¼¤ym}ºsó¸ÇË¿>ý9ô9œ¤¡l}½s8KóÚz™ÃEš×§?k¶>‡«4¯­¯w7iè [ÿÝ9Ü¥y}ú:îÒ¼¶¾Ü9<¥¹ë!ÇgÓsxIóúôgÝÞçæùÝæÇÖËNÒ¼>ýY·÷9œ¥¡+l}¿s¸HóÚú|çp•æõéÓ’¹¹Isì§ÝÎþÑÎ_Hiÿṃs|šx ~×+Îî;ÿ­vãb6ÿ@—,P}¶ˆ%'¸!ÍóÚN¼°¯¶à1bã#¸qd?©rwBW±/®|m¿È<baLØ“qÊa?ˆÝØaLºOmå.…û®ír5ùså&»ð¹ºÌ{ÛÄæ»ìÈC/{Ǻ¿Ãÿ$îòP|ý<­gW¶áí•®ÃfÆ&Í­ow'iè[/s8KóúôvUçp‘†î°õåÎá*ÍkëÛÃMš×ÖÏ;‡»4tƒOoW5qi^[_îžÒж^æð’æµõóÎÍã»ÍOoWq'iè[_îÎÒ¼¶¾Ý9\¤¡3lý¼s¸Jóúôv• çp“æµõåÎá. `ëÛÃCš×ÖÏ;‡§4ôŸ~~w/i^[_îÜ<¿ÛüØúvçp’¶« ±´Ë|gi^ŸÞ®á.Òж¾Ü9\¥ym}»s¸IóÚz™Ã]zÀÿz\…9=¤ym}‰9=¥¡;l}‹9½¤ymýŒ9Œ%a4?>½]ˆ9¤¡l}‰9¥ymýÓEºÂÖϘÓUš×§·ßCÌé&ÍkëKÌé. ͹õ-æôæµõ3æô”†ÎðéËszIóÚúsóø¾h~m}‹9¤¡lýŒ9¥y}ú³Íåœ.ÒÐœ[_bNWi^[ßbN7i^[?cNwi`ÛÓÃ2¼½"ˆszHóÚúszJCOØúszIóÚú;‡Ów›ŸÞ.åÀœNÒж¾ÄœÎÒ¼¶¾Åœ.Òж~Æœ®Ò¼>½ŠÄœnÒ¼¶¾ÄœîÒÐ ¶¾ÅœÒ¼¶~ÆœžÒÐ>½]ƒ9½¤ym}‰9œ¿ÛüØú{Y¤¡ïeqöŠzÎé,ÍëÓÛ)5Ìé" ÿü²8»çt•æµõ-æt“æµõ3æt—†N~YœÝƒszHóz¿ =¥¡9ßo—ï6?¶¯ÅœNÒ˜“Ï÷ÛÐYš×ñó)ùþ|p´Ë†æ|¿ ݤymý½œîÒМ﷡‡4¯­ï1§§44çûm`œIÿ/Çï[ýîï[MÒМ﷡³4¯­¯1§‹44çûmè&Íëøûªíþ}Õ. Íù~zHóÚúszJCs¾ßnßm~l}Š9¤¡9ßoCgi^ÇóU“ç«V¤¡9ßoC7i^ÛóçŠ9Ý¥}¾ß†Ò¼ŽçgÌé) Íù~zIóÚúsk)hܜ﷡³4¯­ï1§‹4ô½ŒKºJó:¶w˜¿üê6ô½,K›"—b¥ÿ—­¯1§§44çûmè%ÍëؾwÙ¾t›ï·)~¹ÖmòýÞþ÷ò.Z~æî ï·¡«4õþí þüïe_t“¦ÝçŠÑ¤oÒËs”»ÿùebÚÐCšq·5cÜý«ÁÇË<¥‘m÷ý±!ûc\ë@C—?¿¬ÌîPÃ9̵Ž¯ˆ;¼ß†NÒȾ7ÖC´¡³4r<…õìsbNËñ”›—ªí·¡«4t‡­1§›4w=„—¹iCwi¸ÞõýùenvÇÎé! ]àý6ô”æ®mò²8mè% =áØÿçzˆ\"‡†¶µo®‡HC'iè[_cNgih^Ž·ß†.Òмo¿ ]¥áºôÇñ×Cà& Íù~ºKC7ØúszHCÏ?¿¬OzJÃuéÞoC/ihέO17ó?kÂíÏ/Ô†NÒÐöãSÎé, ×¥9ßoCiè ï·¡«4tûóË íGœÓMzÀûmè. ×¥y)¢¿sNih^¢¸ß†žÒÐ ÞoC/ièñç—1–>bs dˆíò+_¹s:ICç?¿ìÑ^´7}=¤Ç™A6tƒ÷ÛÐEzüùe’¶f2}=äžÍdC/x¿ ݤáº4/¥ÜoCwihžý´þž ¥‡4ô€÷ÛÐSzýùe˜¶¦Ä9½¤áºt†÷ÛÀ\ë°ÆÍK5÷O'iè[ŸïÎÒÐëÏ/ó|¸HÃuiέOwWiè ïŸnÒмDtÿ4p—†^~Y¨­ú¼ßsÀl¸.Í3ãû§§4t…m}rÝyã奷¡y©éþiÚ½Ôû^vú4p’†ëÒ öõRŸ·{îœ ]ÿü2Õ§i÷T6tÿóËTí_>‡«4ô‚÷O7i¸.þü²Ö§i÷’U6týóËZíb>‡‡44çû§§4ôúóËZmÚçð’†#/qÝ? .ÛüncŽËLìŽ7½ÍÿØgÒ#"»ÿ¥¬Ðá"»Q;Ÿm³ÂåÛ„q),ã«x:m²ÔYïòf–WÖbw´pWÖ^±ÇS'v(}O1óP»s<­lð”±í–ðt°½*‘§Âýk6ÛÒ܈͊/SÛœ»vs‡uwüT]½§ó솿8uõßÿÁÉ:ß)ødçnÝKTìö|M—Ý Ãrì5fü#+²,¯¶pøÉ}M¬møºAœp_<øþyk½;eö‡È ~’…;;ç"“úÇ«&ÿxÅä_Á=ª«#~æúÏy¿ÂÓW«#‘f¿:ßßÿ÷?vÇ%ü¦þeüì|ôïÿ.r™œüûÿî?ßvÿÝ­’õž·e³îßÿ¤æ°ß óŸì{bÛL÷ÍÆöù eÿ§MþlÇaâ ”"ûã~ùÜyi&ÚŠ îtüofߥ½d_'¶Røßÿé˜ù%ÅG5ggo¥øÑØð߬Ø/뿬$‡ý‚œÿdKÿâbŸáß7]°¨÷…²ÿÇóm ã‡0q7Ì?Ñùþeœ!¾¶?Á²"\þëJñ=[tègoSt:ûbÎ7ÕIŸHå:«ÿWû‰àV±ÿ¾mÜø_†>|ü‰à–õÿb¼7Á¿ŸÞ”áüDª/ð?žo¥Æ·Òâ[i¾CÃOtþE«ñÀàÝ¿Ï…°ÿ>;δØ’É¿ÿ„k…ì{àËèX=ýBÙÿãùD¼¶¨ø‡0ñxÕ?Ñù8'h?",­/£ñsaùßçâJùÊþí£5ÿ #>«¯}üû¯Ëÿ§þ}§ýWÛ]±aû‘gƒ±ý]æøïöSË5¾”Ü.{üXó¸ÿlÞkÁnëy¯Âr?Zñº?»(ÂÙîÏ°Øᛩÿí³ém®ÍÐ8*þ#ÄÛíÙF0‡>ÿ¯Å«ó(ö•úGæ€Ìñßñ%¯ø:ëw™ã{Âç´†/ î?L•_ ÞÍÁ¾([³/ÙÖ|§éÌVÌìÛÅ.×y¿\¼5‚}¥øˆöÃÅ æí³“%>%6à~ ‡R|Ñ#þ>-~ú¸Õ®}Ѷ¿ùÿwu-Ér„0lŸÓ€ù#õ®‘Ü›±dËSÙ© 62=¯žLÓpÂFª<ŒvËöƒÅŠ½ì´†`ýÏJ¹: ®¦k¥ÙäÖª€ù÷D³:šOîd9³?Hr·P¹üœú[ðç—Wû¢ÚW@¨E'{aôĨ7РnôR²q¢Ôs圷ÐQëuÜtù ¨ºáÓSâw4¼R„c#&˜·±þi‰PH¶©‡ƒÞŠÿrò>ÕéH·â±:ÔÛY‰VËV´#3Gœd™Œ;$$zbm Þ{dDè3ŒCV6“ÐIa8ú½‚/5Ô°blblblblblbÜS‚Gp261616161¶blÅØŠ±c+Æ£1b<ÄxˆñcãTÄþC#vr`ÑAã]ƒÆºž¬L•÷+{_ªNvöL•¢Ôé…> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:03-07:00 2013-08-20T08:42:03-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000048442 00000 n 0000050012 00000 n 0000048383 00000 n 0000048252 00000 n 0000000015 00000 n 0000048231 00000 n 0000048506 00000 n 0000048547 00000 n 0000048576 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 50182 %%EOF ast-8.3.0/sun211_figures/frontc_bw.pdf0000664000175000017500000012426213004147321014471 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœŒ½K®$»–ØQx»€sËø§@€z©hä•!\À«jhúâúlÒì¾Ì,!ñò®Ø¾ÜŽ9Fî?ÿñ¹þJŸ ÿçÿþ×ï¯ÿû¿ŒÏÿÿ~ýãWI寜 ¯¥–¿fú”û¾>ÿïûüëçþºþ*ýó¿~¥Ï^ÿû¿®ÏúU{Ÿt•òùþªµæOJi~þüª©´OÊõZ¸Ì“6×ó̼î'µÆç–Ö§™c9êËa9žÏxŒë˜g\‡ÇÏj¦3ÆScÓñÜf9ã=ÛïkêwwüÝ9öØ_óÞcÝ×û˜Gmœ¹Óú™#í1GZ=ó¢•óü[>ϼ=ž³žO~<Ýsçþ{ÏjÍøý¬¾Î…oÞ.~9¯o¬4Öö34iHòµþlª)¯—F¹Ï-÷vð¸öí_#?ð½Ê5¯îûgÅ0{ëË{ÌŽ¸g†Fü~Œø<#î§Î×;=滟t} ?E> ?9-¿ó?|*kñÜ%õµ†—¡s¬m´T½ùc­MÅ¿~â/L½Õs­q¹zãâÖqî´öNç®ý”„ëùåñk<ºü5]áÇÆâ‘~l,)ÿÓ¯Ìc ¹eî7ì.áKOÅôãv‘ëR(Já¯ÉeýÑruê óop â’«×=è‚Pˆù+­;r$ò[ÁÁs-óõ+©«{^RW÷¨Ý1æ%uxÏKa_ó1Z¾Îc.RÏ÷( -æõK¯@í9ÿî³¢¥lϹñX!Æ¿5çÞO¦Ö5qcY(ë‹å¦bS¯õ—Ëà PžX£•VÚR:~YY+øš—|2åÂ:{S[ OL^]{inU:.Þ²âQ÷ÝñxëGZ¿f½Àµ°ßü˜£éÀéüzŽèõx¯®cŒüJ]ëe]¨rö-˜—YÕ ×TΫ—±Åé°àZ¤’k9¨—/ˆkÊ•[„5›ÊaM”2EXÃU†‰+ắÒuß$Àvc¿3v^‰EP„¥!¾ê^É"¬'[8+Ï$BÇzY×0Þ"`vP'^p ôófyÅ{™‡Øõ¨n-¸¼‰€½–ËíZt1¥tgë•ÉE·N%@w ,‹•4ëÎ.®Ò€\ øì„.Ë?\aÅQ¯p%êùµ®LÔºV™¤A­k@Žë2@ø‡×ø}RÓu×\IM×¥¬ë®g¬…M…%-º.}Xºîú™Zj…Æíû¥¤¯­=ù~׈ûv×Ƥ)P—ºDÛf]~ìCèúhhËR·4²e­­\.kY±éë7U}cý¤ªo,RÑ70ùõ L}}?GßÀ¯Ñ7Ö3ÐÖù#Ñbÿˆ– Ów×;û“tÁõ(~¸@.¸¤šj˜:?š€˜:?ÜGk^VÙô—”+W™ŸægÙðú‘kY—·ÃñGñö€eäëbëB?zÌPên]lí ?2cÆ]^ºÜzD?ZRNÀºàz$?ZȾ€uÉõüHµ¬ Î)< ¯?å ±¬Õ…Û%Œ¿¥wÓìGËÝÂø[TAÖ¢€¿EÿIÅ~·°Ü øQIO>áW%Íh?I¿ ZÆOÖïÂ÷“õ»°Oýdý®D§–L¾Ÿœ%_³oaÝžQÖÔ…±ú“¹‘Ö‹N$­0¤²žœ?Ys ŽŽYñZÕOæÎ}aɾ;$¯tRI¨]ž© ­mu¡Ruõ‹·^Å…õ†tÈk—·^e¿Ó ëå[£¾VU½}ëiÔK“ ÃÂ%Ö‹õfi)»° _W¬.åÖèbÑY*‹«³f¦X¢Ê=Z¬\åîâd¨8=Ç:Wn¯ÆëËíåx f¹½C ¿½ ¯…°Ü^‘îÁKrÇ=xMîø[^”±>ß^•×À®ýÂëö ¬ûœØG¼0cíŸ^™±%L/ÍPÿ§^.n S‹3|ë 'a\S³›»ÐÔ˜ks*Þ¾pÍ,ì)g>v¸…Å)¸¦fh/0Gnq0&ãö>9`¦ˆƒ1ºgìµ ë~8œYØ×H§k½ßÅ*åo¸xÏÍáŽÜãN7^Or½wüš…ý+qoãükoÓ k^3åöF¾~÷ùZÙ§÷éñ¹½‘¯xÇFž>·öøhbê¬ ÝZKÚZcbâ¬×òÖÚÖüŽi³žtÌš5QcÒ¬ñÛsfÝYL™ü‰³þ~L˜µÓÇ|Y·Óei©1[ÖÈ{²´µx¦´õ’Noäë)Loäkà§7ò5¦7òõ¦^̶VÚé÷rM§é×rÿˆ·òþŒóR¿“k¨‡_ÉõL4;ø6¿k‰Tè±£zIXW¨%V‡¡A­ë™b b´‘aYi¯6#YƒXÍ麩KGÆ2%Ï•‰>½-‚V¾õ>] "ôŠ®dÝ傺îzz³ŠQ>Ý÷»´û~×Tí¾ß5|Ý÷»†¯û~×ðußïš«Ý÷»¦E¿4ë]î_(Mã»VàO³¢´Æ¬i_]kâ§i|¡†È`[0}š&íZP>MëõZ>MKÇz­?Móºk+VPÖu‹5”ùiy«(M{SYS®%+)ëkzËÊšcí²š²–{Í_h,Uó·@ÉÖÚ=·}mNúÚªm·¬Aªê‚¦FYïvÕûV`¼V«0k³ÐŠQÖ߯Zòm©ÙÚÌÚ¹tëPlªnŠýÌ-‰÷õ¸èÖ±#­{Ø(ËÔÅ:—IÁµzj–À€*š%Pš­óc?.õ¼îµhÔ¡?©Óknµâ³.Vt1¬ÐZÞ2n­yM ¬oÝÙÒdÉQý)Ö6ÖÏRU¡`gë&ka²%Ö±%`Äé Η­÷Àж: ÑZLe+O°‚­SASµªEUUî¡léúÃú‰n8G’i¿ÒŸ¯?ÌP€u£Ž± ¢ÅÖŒŒÔ^o@²®‚™Þøü“5XVx`aX‚…qÔ£d­©#¦$éú™É:VÛVÂ"r=PK² mÇzéE< b«ã­_Ü­$ÍØPˆÖ2©Ÿï‰fv+ÿ˜õ$å¹±^BU¦h]²õ0›dx“%[²JFeL¨È¨(ð]Éà›’Œá’­Ñï€ßÖ(èÃ5?úB¢/õYÒ«ÛæX0Ùæ(p7ÿpf,¸TØ")4Ø")‚UÒõsd~¬÷o©¦|l .­¶IºþóÓ%]þpú.}hݵö³-‘µòu[" ®Ûá¸lx?|ÞÏ-)ŒKy×FÉÂPü¹nPCú‘ÉX ýÖA#ƒžN](KCÂpp6Q[úÑ$[k/þ•¡2hdpyX¸†±R =mì‰?ö¾ OòÊaWüI]‹ÆÓÐ=àg%ÁH4\ô·ø»4 ãÂ5R[v)®Éõca4ü[¶`æBY°SþdÚÈ[å^åÒû6h†ñ¡¹µpa]³a.htE׬W7ÊâO®ö]ÁÒ˜@•ýÑTzÂwåÓê˜uò]¨Ç˸áw£î½ ã~ô>A5ûÉzË -,/',Ûmô FÏE#¦ë åŽ!à¢Ó¼ A^[,IÕj-V*. ÄØxd²&ú`½4bw»¼6fÈcqlÛ‚{táKi±. Kwa-Øjn¯õøu±äqyðê]¬ÛbQ/Vnaõr‘ðàXÍãrËY‘˜=$Õ=1ž$µ“'Œ$XÀåÎÞp2ò0yÊ-]’[×-/ &ÏÂ6éŒ$íi9mƒ‰ÛâÔïÊëÏp™ †Ñã}¸p£Þ†…·ãa­öGäm{ `AÚ[°6ÇÐM.äùÙ[°î÷²¶6Â}‡øÈoÁõö¬¡á-Xöhx áx Fx jxò¤á-X„fÂ"Ø[°”5„â5¨ÖK`ðX-d§^&;õàN¡/‚½kŠwkÃëB]"< ݺðIû÷ð¦Ù¿‡@¾¬?ÖK~éVƒ/Þ–.Buìe|zuH¦„«»úÍhå+S×ÞŽÐL×ÖŽ5ªk—Á‹©tyÆhìõ»àq»­¹>ÖP.xÜôXØ4¹°€5=XM“ þu;¯ ¤Úý‘áÔ­¯{mþA@I×à7»?R _à¤ÝðGÚýdRâÁÚqçýí²t/²®o8ßds#¡ Ê½aaÉ4¥cXº¾6$]ï{•-‡HNUb;ìy ^ýH~XÓ¨ÊfDŽ@­N‰HN CÉÖIcÒd òÍä,¤ý¢¬€‚,·êßF3mf'ÐŽ‘ßqù —åÓA¾hö=ÜTì ¡;ÈHŸ0!d»Ãµ_ìÓ€²mÿG ÿGsÁ‚Ъä+1c ö\ûU¨:ÉÍU&8|ÿE–ùäž/§̪dWH³cqÁõ'ô3'‚þú™XR²&rO§nr-6²žé‘± 8 cÁꢸ#IJ¼'Y?`Ë»õ÷v~ëï]È‚Ößþ6å@žô´?%9.”¤É 3IQæe% §4,ˆº ¹1Ö‡ÉÞév¤Ø?DHóšj='Ð ìP),è,Ÿd÷ 6}{e°ÏÛYƒ­Ý>d$ÛµsM',©œ'ˆm—Š&¢šê°Ÿ4 >‡[¥Ø¥‰µI€¥I¿+“~>&9¶¬’» QY͘ šX”ª¾ÁÔ!¼AD0ûtW˜¥ü%È•ÒL`b Ge.»Ðzª˜YOh $z> Ö¡$o%îá›e)“!þîÍËó RЃ[ý<Ÿ'΋ÉKsº`ÓÿQômrè-˜#þžÉ!ââ89BÜ$§ˆiüÜçäðÐøa¤Cn…ÉÁáÖ©bA>‡É[ç«2™uÄ7h*éÌ9â*:T·†‹ Þ:gÄà p¢ æñýL7âk=˜mÄ·¶ã£]‘5¸Hr“Å>í€Ã(ŒIàgŽÌÿSÁ¸¡á'q×LãÖ;®âè÷NÙê\Mø:_:nBk çEW  |ã8ê G½34ÃQïŠÌ U„&qw®!œÛQuç ¾sá²ß¹~¨$†Ë_­Î€ Ç·qñàø6®ܳÁŸ€ %Ù6þ ¾ð¿‚ëÜ•?SxÆâBŽÈ÷î†ÝŠ ¶Z-óØj+ÃVûÃÕ [íG[­¶¤þpü ûÿpÒ“øCݼ­éG6-æ¿ sL…K0…ä$Å ’Ž ä\ ì‹vÒ,$‡ß-¢9Œ\îœ_çú¡Óåä=®_ù¡a¿nŠ“ñCKó£ÿ.«íCƒê#kj©v\•Ö='kïíC³:jŠ$v«˜+[pËTÇ]×|ÑN³^ÏjâÓ¬ |¤ã®aîÞK?έ_’3Lâ7†Ïð ®ñoh„5"S Ã$‘ÚÔGŠÈTÁŒvjµMfôý‘Z/ÇÖ`”)ájaDš¬D_û'^ûw'Ê¥G'܃¨±G¬¨<;bµ0¢fÚŒð>Ó6ü#uÜ©|k³êщGD¯¨Ó;­¯ ¦ÝiÓî460 Ê-5r0íN›2ÌG² Ö§¢ …‚eËé~´EÊ]wü¶Üzn°\Ê]ïeêŸ>¼²wv|÷àI‘z¤2„LÃðm(•ó•ÉôC-®©q@¶ÞÂ’c¦, šmJ÷b°ªÈ$#O%—e2b¥l"š ì/YŠSÓj2b¥ù0LjȗÌÍ©ù0±’!ˆ<åÂfõo§)›máî(ž£`üÙN'¤™\¦ídŒÉ´¡œ³|Fj!MpGÄh™/¬W°¦H3,¨8*ò>ñ®‡/9¢£û•£  =w¸Š*SèQ(J,££“ñüœ¤ä–àäý#o…#eœ¦Ž”qú–áß‹9c¯ëš•S‡}žÎ‰€wZ±G­ätN ÚœÓ,ÆéœÖžÞ;ç"çD4ú¡î½®3œ?²‹° çᜎΪc]‹Î¯=’_O`v ±‰<|ÿ×ñý£ rDNòm}ÿȲ¾˜#r:àœ¤ßzüQùÜ}ÿt™ûþ‘ÃÛ=þ¨ÐìzØ}ÿ7«ö÷kzüo\Óãç|÷ýcÞFN æmäÔÜl#äb>\?Šsè·WŽܪív–?²KÓq±¨Ðy%pîS*Ø¢€9ÆÊÅX«]önÏ®ÞíYeØªË ð·\džê³0þVvÞ þVr-þ–v 8‡s»Ì™»r¥ ¹Þ®s¸Ð¹- xW:¸î¾B‘ÈÎWoxŽ2næ t²Ú`EC»,é\‹‹”pZ ¨d¥ 'Wcà~œ“‚wÐéê°Í³wocs #ίAz¶sR„wŽûl,ŒbΨü$v¡,Î"vê¹ÍAÎwTëõ]\7Bì9ƒuÀ»4±wiDsžã`3c8}>°«Y**—ÛÁ[&ž;߇Øcˆµ%{ Y5ìüVG…,ð©–q—á+îŬqÀ~v¸¦wà¥q¸‡tÇߎÜúaûÆmÿÆtÇ=Ç= >jv€=æÈÿ¸óuðs7“ |Å3J3r¯€=æMç^!ÿ{Žvpßs#Í(¢öø£¢v:÷ Y4ÓÏ‚ØϨYvIQrª‚pÚ9bìèä9Ÿ¦s¯Dï‚4ãïNrAÞ©ä4¼k çxÓèýàvÇ{šdþ~üë«7;¨xÎÀW¬É ìwç•+GòJ%y¥ÇJ“¼ÒcJ^é±2¥î•2¡šyÞ±’%ÛX¬R÷J™R´\⊘úY)“³'±‚&¯ôXY“³'±Ð%gOb%NÎžÄ lïaåN¶÷«O=Ê0q}—#¡5QÔ#¡Ø" ’à#k® ºQƒ=½Û –`x·Aô²ïiaïxwô˜ã–šë¨$muïx©Eå®Y¼ãášQû…k¦½£¦Õ_¸f”­kz¥Çž¼ÒWU€xWOÀÞÕÑÏКKCúÖ’Wzh ©º _Õ÷h­{@ãH¶Ù ‰$Ûl•a\ß?ÚhÕ´5š¤Tj:©úþœ’¾d…•{kL©xü±ºØN«Œûþ±*ØNS¼Ço¶³'Y_¢Ž ßB¶Œh²³`q§”-)™€šc*¡i¢âÞãwǶKêKÔ³1,mMv}7ϭɦlMó?[ÓÄœÏÖt0ϳËÿ1·³Ë/Æ·uo˜ÃΤÄ%W'a£LîY@ß® ¬1”É…×Ø@Svuû!º¼ s2_ÛNHÉnˆâ{']‘ÂÃÜ {l°FHöâûaaŽ…=†yöXdªAjìsßå]á/xa× ÔÎ{$.þ²r £\¨uñ—eËñÝlï FQ³òb3¸äš)Œ¢=]מ.¼I•‹¿Ìž.¼=É5N˜eÉÎu<™Ëi9ë…ºã³&Š,ú+e°yØË‹l4çc¬_ -–î³&7!òZrÚÁÎjtV+¶Þ˜y £­è¯Áé ŽÌÔU`ªà9æ ÷‘rWixFppªuCFÓ;\>+‡{ÍŒ¹¹ "7œYî ™q²r ø²ÿ¦ƒÊ™M”K’ñp fÛ#‡ÊòÅZ÷jcðÕ½RÇž¬g¨Qî!!»Äµ„ä §Sc MØP¯ú£9¹–†5M|-oJˆKÿ¨ ãÈœÍébl~W†/ÑŒAÆ5J|Ýan© [¡Ê™:›ÿ1îÔv"<®—K\[‰ü)çf­quzØšbZ°Õ|® 6…Qiƒø­™ ºÝÃbM wËƲN[Äݾ@áž|åYvoVIÐ85y”eᲘÂò•­¦çÛ¡ŽzÜ"u…7eœ*—GPä’=šó»˜’A¦ØS~ã´p3®8úØJ¤„#Ó¯¸ ÁNÿÅò. $cäÛ+h¶çíÈ Ó‰ Ù¥™fŠ0—¼1# »N+R.îÒ¨êCý¾f{G+&:ö²»Àÿª22ÂÒ´ê«UÄLõÏߥò@  D— ‹éÐMÕ‰±P]"°—^5ÛvÇh¶ eÓ­…~›Ü °'ìð¶Åæ°¶E5r[T(MRQ(!¥TÎNÅ“P‹ë(ñË"‰ª`IYá~œÆ‡-2òø°Ez±Ø’\j7ØÞÙéykX51Bj5Y&;Ñ IÚº3¶Т U =“£TâÏ,&Kðt­àhªö^Vyÿ <ÎJ0-p¤WžÐÝ´:G¤2„©U—QB8;ùnÒ锵2ãžÍ&•éñ"+#A½¨¹äe ¼ßÌÞB^€ïî4ºŒÊ*ÍÄŒ™¨Õ.cÒßBë3uµ»Øaëî˜7@½!Ö§†§\i½íH¥ãêÌ´<-Ô¨(rG2êËjKGuŠN‚çTí¨;i§M|ÝÔ¤ )K²‡t9¶Ù4C™œˆ˜úP£[x)„•ÙŠÊEI©úrvv`ÎòƒGdt¥(0£š/À]!W>#²>?ª Ã”žŠì­™¬8©—hÌÌï/V·%)u†’ÚQ \”{ÀžZúûXA5‘8áZ0ö%QÐl°šŽ×Ŧ\”˜Î­lIÄZ‹Ö6ÆKMŒßMµØ½´”kƒc,›ŠAJŒ»{)ãòêVX­©þ‚…Õ Í{i:›HÆo‰‰Fqõ:1Úét3ÖÖžæèeaF¾ÄšEõ©`@gÎIDÔ.ògD· ÷jù¬ ü ®Ó*®£òÎ9YÏ Qˆé\ ö½tÖ<ôÝiÀ%üí çˆÒÃ_§6(,çÌóÚ‘ð<¢ª~˱ӵs÷F ]s}<üZ‘aÎ^ŽTce)Ž~÷óŠz :j=v¿À¢èÎ>Gãjg.`°m/¯™Ã7Â(w²~‹¨8—FÑi¥ëþii{ËÞ]ogÀJÌÞfvGþß¿X˜˜`°~•b›êI·Mª,MéÄÆ°‘¥ìbiOΪo´IµàEKòh–ÆFkNqMZ÷›ÔYöôlU'ãÂ&­NÇÅ/®NÈ…MªêA¦ø&gÝÓâM–>y mg'â‡ÛaAaJVì1ÒÉrU6)Y~†KOá»ÛùœñHuDŸ%@%uþ¬-Ì7”â“ñŽ¤ŒAØ"Òѱ”¨N„q |dôÂiêâ¿Q³Y0¢ÙyÆ–¨Ès†ƒD`†3GχŽdeÒÏ+Ÿ1Ý°*·Ì™=·xgìÂm!ê”/˜=°å ΨF/nƒÎ.k7•eÂɬ  7“3±îi‹ëlÂ+tW„­EÕDb/5ô„ÛAíËF¯ýò½$$AªÐ5a‡VÇÍ‹ìEXº'ý!]¬Îa®%õpõ€²:’ò$‡‹‘ +©EtçÉ·Še!9JT,´·Ì8Å.åÔuÎZ´¥)â}tû88"p[¢m:t»B0xk&kVó%pæ3|LRyàÚÊrF²]6 !˜ܼ•3^#^_Nž.XAô̱y.ˆvOBç½!i@º3|EíÔ¹_*´ËæcJ;f‰¨2x±k:6f‘ž9T{Ë4L–s EQZ‘’Æ‚¹ÐneUàhs¨é«]bp/N.I‰É+jä‹ÞÅ=æø—³” ©‹ôz® .q§ï¬È­›àès }bŸ7%%䤸,?±$uj’R1ÐX&n§ò8¤ÉÞhjÌŠéVÊü.·¬|1áIºåE+’#Êî¶î½–“ì<½ŸLäÒr€ cªäÀÌ” YYƯfÈ,íÖÎpù¯÷U˜ÉFºjÓXaBÕ`†¾“™$'Ç/#§NÜÉ“¶£´)µ¢0AÊõ[LN’ó“™ÙN:a¸“E “`¼¥3éD¡žÂ$Wø(©";ûŸeÆ2˜ m ËA¹lÖuÒ!CÁ •°#Kµ) -z«gˆÌÉgìs:ìëaèU*@£%  «3l¨UêvnÑx$EX¯`<³zDÑþÎ%’)ÑÄHö7ta‡˜†ª„¼®†¸Æ(Šï„€ŒÆñõ÷ù Ìáò!+QÚ¤çÎnI dëþGزllbgûz®p†Ç¦oßG¦»}ÐùaìmSó»Îb†«¾dºá#)õ(H}IÍJ¡Ž‰1'»×Ô¨gö[’r™é’¯æеo®YÌÁ5]ÓAåF…'ðQ&×ñeÚµzðŒ%WÆ!+l_Zòž‰rºNEÛJ³Ä^ždTñTœ¤:”Œ,Òtù-aA5²†é]a ê’ý‚-¨I¨·ŒE¤NÙ˜¨AU~DF–¸Rè&ñr€é«æ Üñ•åHàz‡¸ò´•‰•Q¸§C¤JÈðÚö)Ûf·n2m-_4ƻְÛ]íØ«¹k·½)•Ð7a¦øZ=.–FŠ?Á •’*^5m9φZ@c’ªcjŸ^MFÓÚÁðñ(îÕÂV zÏ ­µ³²Y·ƒÖ­²wXF¯ÄÜt±œx”JœÐL4©Ó¨3šZ%_‚îúIšüdÁ~SõêïïØû’öI$$ †Sø8Y(מ|ª |`@“8¶ PÓÞ<õ_KJ•Àÿ·æÏ“o”ôY’B†tµOP)‘UÇ°ätf>bÇY†2ÖÛÌpm[šãl XÒîÎõ5YŠeNR¶xöu‘ )RŠ¤ÈZÃ`¹<’lI- <YÉÙ'Iµ ‰+ä5ŒK倬2iY²x9Õ* ÀS–½ 6n—¯㜫 ?sˆT¡ Ÿ„ËÊa²Å?0æÔ£HÚòk‚åwŽs$¿‚?‡¯…îŽëß‘‡R`N¦i~g®ðïÇ¿¾ò(¥áUºòí6†ã¼»`•9. ņWBÖ|‚Æõ ,Å…*cí~~pµw©B•*—Âín/õÅ,(ä]xÀ'ãrCfi¸ ‘—'*3C|޵˱++?#%(©ÄÒsKüš|³“½Þ+TE0 Ç9 UhØÀíCÆÆd‚8X“¬z*ý©ÈPAaE’‚ÎU’úÑ7žZ˨ø±ŠÄ÷*)R˜YD®ˆ §žmÞÜÉÖûÆ!½'™™%:„‹éqé²1þ3Íï?;íð·ž4™mQ½âº€%V¯3»Ôê;cÏ·Ò…¹yk<;kòVÐ ýöÁyµ¹LÆVpkýÆa¥Û†!|6&à }éGºç¦<Ü€­NвèKðø¨yMRÕ¼æ‚Ü-p# ê}žè>Pø;11Dyù}¨b¡³Jç–!xdí4± ®¡f®Ž<(,©ò1açJ9³Wè+t©œsÝâ—&1:¤cMp ^RÚ_º˜x"{O))DÀî=vøa’šøb°’œXì!ª–"Ї“ >î“_„!OrÞ@ÇLR'CY;7´>ÖÉÄ°K>{öXˆÒÕ¤Â(´µIÊvÆf—´SQÓ$¢»XíǽBDŽ°¡4ùkè á¯aE,ºn‰H%ôý¬ŒDíœ:‰@ =Æ“ŽdZˆØom\bt*ÂfY»*rñÖGG Ôνœ‡]ÉõΓbÔm‡Þ(í ©æ6xÙõ<Ë¿Å9•Õì=¡Ä:OiÖ¨ºÉÊõKIùàzððs+¯œ¯yöÔFì=+‡‘¾iTv‹|ÛŒ,uØJì-èƒø˜yïÓ`Ø›/ó‹l \®LHO\6ØW÷Q&™U '¤(‡>#ºdéNtàè %ú§´¿§ÁJ Yˆ•ÁªŸl“ˆåmÌïvéBün·“g_‡‡Ú%Œä¤¿Ë5,±œÖfV¨t:«òD–!Yz9³*(dú±Ák-Zj1Àtâ¢Êâ «Ág‚1Õ¹D& ôFœ˜éìºúÑ—TíÉùTÔ›‹F×+d˜pYU”yp>È@Eª|¾µÃwæ:€Gª #»³V÷\]Ò¯p§Í{¾…öÚ3—Y×·;ÓÔæLA?»u ¢ÍÙm]ϯÑž®}vŸä—+s‘ÿ~¹åÁM'qŽÞÂü*W„2JÁ…ßAkÁ6¡–^t¹%Y¾l€® ¸NÖcˆH\MØä¿¿˜“‘TIXz05,Ç ±¨«9¿±OFDGõ<Æ+ÉϨÊMöI 16ÉUý~`·†6—QhéU<­èú.teÓæ¡ìX}—Ù¨Ón“:KlÓé™zè'pS™]Χ7f©Z?¡ÛIóXQ.ŸB‡üdUæq]v'íäøŠ²<“m•+2/é#L¦0kP‘ªÌž€ªrã‘gÉÙ …>$…fîÌÈÌ„ukÏL\Éz^Ì<³Ý‚Éù ¨PL^3#­âÀ ¦¶™›¶×#êÀθ©øT¼¾óy²âÆ×á`­ŒïR·Ì¶!õwµþòïú¼BÌ1¯­xÝ}Ï©3ÃRê¢L%”>;9U¥4­õth*ä}”]—˜ã]Gb¦²2Yú¤&G¨œ)ëH;žµÎdC`,©áW¢}b{›}¥W'¤D¤ê=,ñD)Ùð÷vO&¹*Cáêá°IL@R¶4“I“:Á%º*}r&1E©|ÆI ½&’œû‰ÉHêõ›’’š¤¸eŒ%_*åÛ'ÎeáH‰»­ !E½™Ö»¤n‰IëÑmŒ»l ­ÈºÂ몬ÓÀ¦Ší„ðÿZ¨ø· ORsfU²æ,èdRÞÑ{8Ë¥›Tûf}ˆ:YvvÏ®‰Kô«©j?±žÅ+7úùDàÇõz ûzÖ¾Â%2ëxÐp´n”Õ«›E YœÔ®1Lƒ5‰öõfbÊ‘2’e_%æNÜ>F<íFÊXº£Œ°kó©sgõ§ßÙ:ž[í¿Ëã³óXx²„w2µ"«+Ëx²²o2}%ròr æYÙ:L×ÈS^p¦&·hF‚¼ë3\JÙÁ<Õ6féXÔi¤W±.o8Uì*ƒÍt~:@'ëéÞø¼äîÎõwÒ‡:OÐÕoÇ6–»u2økºu2Ú_LR(†e¹Ù–g\’ÍÎú2íeC¹+âà¹Tï­ùoâãÞ¼gaËÏÊø§Àu[JËú½“ïl?úŸª™94YÕÉœÖYÝtòäùËոƉ’˹žÙ8ð²îˆyreãuR<æ6yn ­c¡éÄ¿ éLæðÙÑB³ÊPThÅó×—«-IyW0?3øn¬yÀ³_X{?öl‡s„§çGŠªÀ=æMRÀÒ¨õI6Ö5yð¡uÿ1bM¬kÂNŽ¹‹ýÛÁgîyêÈ!EnªÄÉú8«.”dÌ鬛³úaØ3YÕÄ{fE°ï–ú–tzç|r/ûëx¤,‰Æ©ûìW8ºß[øžº}ÃДFa|jvö\¬.’~3w3c­wø’jyR0‡I'õ`§‹2©¹)s]’º›fÖ)øýAL6ük¬Gоžéûk>—öîQiÄÔ­ÔâÔ_b®Å7¿kœÚæ(O«Xjûš“ßÕž1©³Ú7ŸvµSÔY•e?¨³j_d~¼~cBÌÌ¿Egö²¸,t‘έô¶‘TåÝö9&–(ëô{'JÜQ=Æj€¤î"Œ Û+L•jüIǤú:ís¬ZáìÂܳ³‹-0¥±KvEbÖY&›%uIˆ¤é˜!k¥²ÒÈû%uqë@¬RWæÄJ ;yo®xO…+‡||¬æѾÅâ©$›˜>/û¶éRÍꌤý^9š‰>õËß%öwû9žòß…þÔŒ©?·°;©Ææìïb/·ãÎÀœýwo&ÍKO¥‡Êã†5ZÙ³Œ)å’íTĺ/ýkBÖ9Ω²ŽWϱê´àƒÊ5ù]±—$¬o9âTwÝz#…ÕþÖN{> Ùq*ÍNIiþ7zÂÚNÒÉJ9à4u­¸tgaYÉZ+è†ÏZCèæϪbätÌ]¿Ř4ÿ({-{nÃVqm¼ô¡8Ýž{¶ü@ÜŸ´¾I7RÌ ¡ë^Vu&Kcs—x²âä}»n_'Úwg†ó»ÊgþhÈçæçKßUü-ïë3¿Ü—åÈÎgÍ—êÿå—ºˆå—Êô¯h¬Œ#i]íu뉽´fÖóçD@ƒÑ]ÕüçÌ“£naŒ›\—™z³c…½ºíÞ5ü¹p>È7V4œE¿Žö¼wÊmÍŒ/Uï‰ð UûÃðL'¬Ô´¿TF¡“³%{xc¥Ï•±íùl[=T~Á==«¢‘*Uœ]é²_ ¿Ëv8ʪLVx<ÛÐö)Úì)ìkÈŒ§SO2®qÖ9_ŸŠ-ù5ÿŠïBªçúWü]¬WñwarMøýø3ÌQ.0¶6›ôàiíÖ²2›áʲ8Z¯D[ ¯pŠ ö]uv ì9T"ñ)°áxž›ô\céLTn”ywÞï±(úÂe2Ým×`$'Þ`»>žfiüê ²2Ü©Þ2ìȤžþôß&ÙU9q¿Ñ}&ÖµëÙ£ã¬ëã1pâU\&Éð݃¾Øþa] ö1j©‹à:š7¬´¦ŠøOès<`N¹áù¢>'?ÖÅšxÅÙé×QYfìÑI† ÌLŸsË×MÝÔçÜ3&çÜ?pKQ‹Ÿ˜“¸<8ùÓãš×ù[ó>÷0ùwµîÃó=³€KšÊ…÷ÚZâ·Ó!ê1áÏóXQ¡ÿÇÔ€ÖŸfŒy¢u0±›û%YÃu8-ž)UëôŒ#x$ú/msÃE³°®“ã¶Æ~ âóØBíÙê®ûg›pÙµ©³úHzU§^¢jV?Úžfâê<¨nÛ·ÌL |Ù€õërÈ`ŸrévsÆxg«1Ö‘fÌ8¾ñëKB›SGÇRgლð»\÷ÁÉz$8)?°ÿ. øêù[)þnŽ8}^©§fWžö¾×MÆzrTª2ñÒñ دj5K—ZVKâԙà =¯SOÒœA2Zv×ÑÛ&_ìUc=‰û½lfØxYÅ LUɪp£ªž‹çÏÌxPq\:Pq\ïš¡7ÓšÕ±.ËOY¼Gl=›Ó}aï#œÞkÀ÷^ÓwÿúõsÖ>ˆ ̾øœä/Ï<«5{aÜʾê%Í{%䶷™µW¼Ïâ:Ùûo^8ÒídR²>G]dó}4Æû(½‡>T%Ð4ÉΕÊeŠÍž`…Á Å¢õá»uMnvWõüÖ*SØrœŒb¿•X‹‚Ëï/¦NW÷µaD QõcР»»´;ø²¿¿°µ+¯ø÷/,g°¨¿ìØ-zãLµÄø²csÊe×—}èåF=t‰xÙo¶\fÓº/¿ê½ßl8͆ôß_8¶Æõ}¿™×ÉÑý²$§dk›L*è(öýÅëJó±ò‰;‡ŸÜ%õ7¬U–Òó;ðºùDÄßò[³ˆCÊŽ´>oŒ ž}ò•öW¦çÌ)ÌøÊF)£ûft8þ.Íÿý‹uó¥IGfÚ:\@žtZçKDJŒ$ûçAÆ ¼X|Ÿ=Æ°ÐáôD ÞfÉ„ÐÉ}ÕðÉla{ývéÂ'è Ý®ð>üÖé¬\ÐñI¡þâ;`õ1,ѯK TR‚§Ï®~óqÂ_yù—ª?ÐÅç£~EñDÕ5ùÄ_w¥‘­ó[½/úúê„K÷Tù­N¡¬äûª ¨sÑ~ëô¨„,Š¯N"uÆÚo®ŒD1ôF©Œ©ê;ìýËh"Î+ft°øm§{ðWÝ‹CÄQ0ð¨"gÁ°=@òw¿¬ÊTDŠrª~y%Ã;1¢Õs” è$Áˆ¢L9ºø„ÞÎœ´Þì¾GXošýXoäïôÜÉô´^n5o]ž1«ø/>SƉ{4,¸ØK£ñó®<«”c88˜ö‘†ßQ&1*O®+¢õø„¯¸:0}Õ~åß*np'“V“ò󫤑ú;>¡ á”Ì:ÒÉÚT:|’:ObED /è×þë;ö‚B+­Žx­)ÿv<ýf&CŒÖùnCƒåèhçU‹‹ß¿²ãüs£®È¦@¶'Ãéø$s§±â¹¸Ï”¹:&‡ ö>‘‰þz É"&÷Ùá1.Σ,ðqø쿳ÇüQurwu¬q­[™üÊòt7øgujýèqœÂ7ªï7þ‡‰" ypXÜáDÒeté ðu©•#£ZMX'ª×Ù[<…›v5TïZ›Ž2ÏúÔ5øÚ¦²ŠãåýGÆx8(â_YÜ¡Ðq)—®Æ&2iÙ\ÚîØR(ÇNRŒÒfµØÎþôr2>+T×ËTC&~d¬1Ž„€õ|kìGñl:èä/fŠSë‘å¦7–œN`…%1Úü<ö_䢚˜èQ£Š”pu“ŠÁ R•Û˜ê…`ÿãË Œ¤š:záµþ3I"¹UûBQÊ.">è<ïæ%±·ÿù?ªR-L]÷²ÿàNò(ÅßbÕ¤6ó>FùñH[‘ýªSµÎ€ª‘ç—b&ºm@gf‚Öò*À`!§ìx'¸â*Ë´Ècýûüc©@è¹®¬2ª]Æ\<XÆ ’ÇÜüào•ª¨NurA(%”¡[\èÄvÃÃÎwÀNsVU+ÐÂöô6®Ñ¥c:°ÏªUøù×Wî 7秧ŵ§4ãþíZÕqjUçn~t”› eFXUãÉnÛMû!(Nƒ7Ö÷é®tSýÜX·*ñþ6$€:ˆsZŠƒ‡ïjUŒ£–*çóyø<ä<ÞJ–“‹Û°ý|õùEHÜ,.ºûà_]¸xQkp-ÐLfM¡^íqz³¶ËžõªH§ô‰^'ȱZèJvù]Ã>€a+stúYn’ ¶¾ªýDG ÒÔ/³+*;ÃûZãµÈnž@wJ±Zzþõý7+Vu%ª‡*FWŪzÑ¡rEUk‹Š±£43ùÚU³w$²?PrzgÑ…û1(©£=šZ6jyyV¬²VÔ픨§ÑbðTµœIWº¨-?ÏäN*Š¢uM1¨´j‡â‰I-úÙ³$ùŒÉÆ6ÃO×ÑïmlÙøº·¶Õ»w•­)Fx£üAUøï…÷¿¾:¼9]nlÌJ·ñ„bàçlÍq¹‰iÙ+ºÚ^n™*ø·ÁÔy?û 6ŒY½ºÞM©©å%ìn%y1‘R›’$ÕH–õ¡2ByúLìŽÛ¤f{Í8 Ÿ>„=|dÊl§ŸWï‘Ê£]RQ¡Ð»aË«ÃÓ!ã¤Ì;j0xÈM’û‹MŒ’ÏlÔéÖ8Leõ¦ ßjÌ~)’;¼VD¾½Õ§¥Eª…)´ÑøeÌGs˜gùK)®|_ômŒiõI¬±R<ó~gôwB7:É8áò˜HÀ×N®à¡†©i*:Skw»ö¾V'K°“Tj*èz—Œ½*㱊(uBçÍ%yL-Qí=ÃW=šB¢rÅéàX¥ºOÉ SŒ»kõÅg‰™SØÙHW' 2Ü하ôåf5ò´g¢÷ùRÆ•(íBÅIq2z¸ëNÈ`…¤Æ(ùf½Ûä£=°5òäú®@ãd"‘¤LþU‚j<ÚTAhüg'’¿R­^éé¥Dr;;â'µïÏP Üú™n‡ž•wø(w¶¢V(l›–ÜÌÍ!5î,Úo3Wu‡ãØ2{Fê^ÞéU ‚î”­g°ó• †UÐBu e&+”+ƒ—Nžb`²8!üÞÉmÂR«º" %Ó¢ ”<å„IÛ¤ÛNXv>”ƒ*‹Bo7ç+DK±Û†%†Â=£U9=¶1¬V•6T»Êm*Ógk·Ë=oîÅu˜k4 íÞÇý8”€ÔW‡^.Øß9û/¿þátC«Á»'}'°´q¬áœuôÍ©áî Žqþê´-.Žqþþ#\ã$üõ¹À!nŽ{„Láïß8ÂýÁÙÚñ÷oáñàaòÇ‘ ÏÇØ ¤¿ãߎp÷ÞEþÙÇ„¥M‰¸ ÿÆNŽqþþ#œã$Lþ}äÂåÁnSøû7Žp}pŒ»ðWç…ܸ=8ÆEøûæ÷Ç8 ßãñà³Aøâ¹ñ|pŒ»ð÷Í1¾ã"L~ÞrazMNà$ü}sŒÓƒ³mâï›cœã.L~Ùrãòà[þ}sŒëƒcœ„ɯGÿnŽ- )ü}sŒûƒcÜ…¿oŽñxpŒ‹ðק[n<ãôÙŽíÇø~p„Ù‰vÞÛÝ]âxs`Ysâ¶üûæ§Ǹßãüà[Ï%l¹qyp„/7Èÿ¾9ÆõÁ1îÂß7Ǹ=8ÆE˜ü¹åÆýÁ1NÂß7Çx<8²poË¿îÈk¹ñ|pŒ»ð÷Í1¾ã"ü}sˆkœñ^8 }ð½åÆéÁÆÞZ¬xrŒóƒcÜ…ÉO[n\ã"ü}sŒëƒclù÷Í1nη-¥çû°«ÌycòË–ÏÇ8 ßát¼%Ç_ºrãôà¤óÛSzðÓƒŸœ7&¿m¹ñcÌWáï›cÜœ7þªyÈûƒ³ýaÄß7Çx<8oLþØrãùàÌ3—Ò|ðçáÛEÎß0ùsËÓƒc<„¿oŽq~pÞø«ƒtCn\œrÞ\üòà·çÁ§UîÃ|…ûƒc| ßãñà¼1ùiËçƒãõêþ¾9Âå:œ¿aòó–§ç±•ôà§??8oL~Ùrãòàgáï›cÜœ7&¿n¹qpúY{Kðûƒ?œ7&¿m¹ñ|pŒ«ð÷͎ëë?còû–~ŽqûDPüÉ1ÎΓ?¶Ü¸<8eïeÀß7Ǹ=8oLþÜrãþàáï›c<œ7&ÿÞrãùàœ½»ÖùàÏÃo×áü ƒÏpœäÆéÁ1¾…¿oŽq~pÞøûæ—Çú•åß7Ǹ>8o¼ÇSrãöà¼ñž?­ù㾘âý x¿­Ÿ÷±ç÷úÓë•üqæg὞û`qáûÁyã½µûì_ö]ó7¼õîý…8=8Æ–o}ÆíÑ…óƒóÆ¡Zn\ã*¼Ó]|¨ºp}pÞ8ì)ËÛƒóÆaoZnÜã&ö~ÈïÓÔÜœ7HÈ…çƒcl9ùåÈ…ïçÉOGNlßÅÕÿƒÏ}Öráôàaòráüà¼1ùåȅ˃sì£jÿõRË…ëƒóÆŒ*>äÂíÁycòû‘ ÷Çø&¿¹ðxpÞ˜ütäÂóÁ¦Ý!ÿýN!¾œ7&¿¹"‰×áü “_Ž\8=8ÆI˜ütäÂùÁycðÙ¼ßráòàgaòû‘ ×çÉ/G.Üœ7&?¹ppŒ‹0ø<(Àráñà¼1ùýÈ…çƒc\…ÉÈ…ïçÉOGN>úÏ|P`¹pzpŒÝF„ü~äÂùÁycòË‘ —Ǹ “ŸŽ\¸>8o >÷\Ë…ÛƒóÆä?äÂýÁ1Âä—#ΓŸŽ<Ÿh¾9ÀÿúùŸ¿Òç¿s=þ À~ýå´×c³Óåï>t’ÿçÿúõ/¿®¿ÖÀÿ¯uÿ¼þ÷?~]ŸÿóG:§æj>¾2Û›Jè¼ü.¿‡|ÝþóøUèÿ¯×ñuÛ¥ß8b­´S|äÉ žà<Þ³ç!°÷bêä–+6{ŸùïÜ‚ ó¥}š^1ä¨(Óp¶+áW9¢[zû„^Üuë!%¼Á°~Õa+¤€÷µ ³Ó ²/CJ˜Á0’[·”0‚áEøUÓï–CxÁ¯ºw…”°‚àÚš^!„pCJØÁPÒ¯:Š…”°‚á üª›˜¥‚ã ;áW]È,œ‡ð‚_u/³Tð>ÃFHn )`wŠ³ %%wKÓ!–s–‘Bk©`>ÃLHî ©`9„$÷©`=ÃDnJ!l‡`x’›C*ØA Ð/=·TB*8Áp~Õ!ØRÁy/Hn©à}†ƒð«K å $!`'$w†T0‚a#7_!̇`X ÉM!,‡ð‚_%/[*XÁ°’[B*ØÁ0~ÕôßRÁ~†‰ÜRÁq/Hî©à<„¿ÑåRDá“¥‚÷!®åð«$EK åX$!à$$7…T0‚á üª¾ÄRÁ|/Hn ©`9ÃþQ­ O ³T°‚¡¤än©`;ÃJøUºŒ¥‚ý !¹wHÇ!¼ ¸õ ©à<ÃLHn ©à}†’~ÕÝÛRÂrmBÀ‹ÜRÁt‚kKïrW¢Kƒ¥‚ù^ÜRÁr†“ÜRÁz†ƒÜ;¤‚í ;áWÇÀD–a?ÃFHn ©à8„üªVÊRÁy†•ÜRÁû !¹-¤„rd’0’;B*˜Á0’;C*˜áɽC*XÁð"·_!¬‡ ˆ7@§Û¢‹ ¥‚í '!¹%¤‚ý !¹5¤‚ã^ÜRÁy†ðû"Þ‡`(é÷E t]y@÷+©`:„ŒqT0‚¡¤1¾nKXÁPÒï‹ XÁ0}¢6«§ ¶C0¼c>´¶çCt†ý'óÌ'4ŽCÌ’ÆümcÏ_'%’`(é÷E¼ÁpÆ;䦟°’ÛC*˜áã=îi¿ÇîÍO‚¡¤±>ô¼×‡^ÁPÒï‹ XÁ°Æ%©`;ÃLHn©`?„Œu²ŸuÒç`(i¬¿}ìõ×ýI0”ôû"Þ‡ Èó}î½ô{ïq>ÂNÂØ[Ƶ÷9+ExArGHó!Jú}Ë!vÂØ }j#a=ÃF{ìðþY&VÂØ»]CBØáC'pmá8CI¿/‚à<ÃLHn©à}†‰0t˜áç–|"¥oºÑôsL‡ð‚¡sMë“€ùò¾™7n9„²æ´>9C*X¡îá›uëˆÓú$àyX;aèžq¸m÷iX&ô=fß:í´>Ù|€• cOOùKÁys¿"ò—P™ž®Ev€Ý!$œuòÎÛ¾¸ýÜÏ:°†ÝâFé„õê^âoÛowHÛ!´½uÜmÛN·í·8ÐÌ„³¿Ù_r¤‚g ¨3ÈÂ~»ýf' †™0ìBûKïC0,Ÿn GGÏmÁ%iå@IÉ­!L‡`Ø ¿/‚`>ÃAhûØRÁr†7¡ínKë!lÕrØ_²fŸ¥‚ív°¿$o©`?ÃLø}Ç!ÖÏÉRÁyÛ$á/™!¼Á°Ú_2Ž¿dØIB@I¿/‚`:„m¿ ûKp Ÿý%„ùlw_„ä¶ –C0LîÒAg‘¥‚õ ¡ýQ– ¶CØv÷°¿äû!6BûÄ,‡`Ø ík³Tp‚á$$÷ ©à}Û_2ì/¹îI@™hÉ!¦C0L„ö9Z*˜Á°Ú—i©`9„íçö—à0GûKë!6BûS-l‡`8¿/‚`?ÃIhŸ®¥‚㶫rØ_r• ÎC°_ù"$7‡Tð>CI¿/¡$ã !¹)¤‚éN»ûKÖzj©`>ÃF¸¸pÀ‡”°‚á $wn)a=CI¿oa;„Åñ€±¥„ý±I„äö-%‡`˜ Ém[J8Á°’[·”ð>„Òå>Ü{sí$™Ø É-[J˜Áp’›·”0‚á$$7m)a9À\ꯌÐ×_E»èS—] ÓGJø”—Qæ}ãøçæñåÍã‘´†ƒ—í:óÂûÜÌâf½[ß}+;÷Ü»ïý×î¼}çt¨#Ì?~±EpVõ|š‚² K„dí×µ¥„ù^ð«£FBJXá¿jËi©`=„üFû±G'²v†™ÜñÙÊû!¼à×mÊÜ¥–p ~Ý@LRÁy/Hî©à}/øõ’º‚„7üêÜï§c¦C0””ÜRÁ|/øU?KË!¼ ¸G*XáÉ!l‡ð‚äÎ öCxÁ}Ý~®;Áð"ü¾„µlÂ~Õb>ºß¶CD?ÉÚ·mn4D¾ÿÉm!̇`ÈƇ›w ~Õ[ÃRÁy†ƒðû"º ®,y¯ªE-l‡`È~ЇÛ6W•±$¼á×Gl ·̇`Ø¿/‚à<„Œ9én€„÷!VÂï‹@èF‰ ,„_·¥v¡,O:É›0òºC*x‚a"$w†Ð ¢AØð"üú¸7wXLy {àmnʇ[áÉí!¼Áp~_Bo ¼!¹-¤‚ý á÷E‡ð‚^£,%ôÂB@¶fÙ\¯Q„õ^ÜRB7æá ¿/‚`:„»TÍuÃ?ó!ì׿Ô|¸ùpË!xê„ßA°‚ šUÕz¸õpÛ!¢û ×³Cì‡`8¿/‚à8=!´ä©ãpÇáÎCĹ‹nÌÙÓ–Þ‡`8 ¿oBgߥM0Ä™†^Ât‚hýÓÒá¦Ã͇`x~ßÂr‚hŠÔÊá–í‡ ˆ®Ž­n=Üv€¡¨Bú ’ï¿äFzÎ[´woîÍ—Š*[µmýI§èúh éV  ¬º)×?~±£I)j™‰'®ÓÕ¤™„€—ß7aøÕ0Açž«­&š;nÂô«a‚aó»ó"–C0,~w^Âz†—ßÄ#Ç-%l‡ 8¦ß°‚aó»Ã&0%N=½üj˜`Xüî< ‚ó /¿;O‚à}‚=Þ«ÆRBµ«#!`¼;O‚`:ÃxwŽk°T0‚áåwçI,‡ ˆ¥ïΓ XÁ°ùÝIå*!l‡`˜ ¿/‚`?ËÜRÁq‚èØÆáŽÃ‡`Ø¿/‚à}†™Ü-%TÓu^õ·xÓ!¢[÷së!̇`X?êkñ$–C0Ìõ´xë!¢E]÷s!l‡`(é÷Eì‡`È–pâÎ ŽC0Ìõ°xç!¢ `Ÿ‡;÷>ÃñQï v“-q šø]›°~Ô·âIL‡`˜££3ŽµT0‚ ¯7n9ÃñQ¯Š'A° ’›B*ØáÉÝÝ5Ç!ÎúM< ‚÷!¼ ¹%¤„óÚ„€÷G}#žÁt/øÕÑ– žA5T£ÃÃ͇[áÉm!l‡`˜>êûð$öCxAr{HÇ!Œ=5æ8Üq¸÷!¼ ¹#¤„÷µ ‹¯> ‚é^ðëî–qJ*`>„¼§ý7n=„$÷©`;ÃöQß…'A° ‚‹vß’ ŽC0ìõ[xïCxArSH}xŽú&< ‚é^ÜRÁ|†ó£~ O‚`=„$·„T°B‹eP}žÁ~/Hn ©à8¯Õ×GýžÁû^ÜRB8BBÀôQ_„'A0 ’ÛC*˜!ÇÖ¡~O‚`=„$w„T°‚aù¨“ ØáÉ!‡°·Eõ?xïCxArïæk¶ú< ‚é^\ôR–T0‚aÿ¨ßÁ“ XáÉM!l‡°u õ9xû!¼ ¹9¤‚ã çGý žÁû^ÜRÂrmBÀû£¾O‚`:„$·†T0‚õ¾ë£~O‚`=„$·…T°‚aú¨Á“ ØáÉí!‡`˜?ê_ð$Þ‡ð‚äŽÚL!`ù¨oÁ“ ˜áÉ!̇°õjÕŽ= ‚õ^Ü;¤‚í ÛG} žÁ~/îú]– ŽC0ìŸjÛôïCxArSH md‚p|ªíÍCL‡ð‚ßA0‚áüTÛ›øñ¶7 Ë!¼`ÌÛ›„õ^0Þ Û›„í ïOmg-ig-±‘I Æ:i{“p‚íÍëSmobå²½I8ácß´½Ix †®ÑŽ^rŒÌ %µe©`:„´Žh©`>Ãü©}ëÕ– –CxAÛ – ÖCxAÛY5ìMÀv†åS½Y½éÃJExAÛó5ìÍ8ÒÀCIíרaoÎCxAû˜BJx Ú×R@™ lõH8,¤„é^ܼ¥„ù ûGýRž÷––CxArÇ–ÖCxArÛ–¶C0õ H8Î#¤„ý^ÜkK Ç!Îzð\§ÎCxArÛ–Þ‡ð‚äæ-´ñ BÀû£þôì…”0 ‚»æXH ó!¶ë£¾ôì…”° ’›·”° ’{¤„í ÓG½èÙÛRÀ~/Hn;RÀq€á+Ç.õ×Þ9ÐÎ><×·FËþýä\‘l~ÒÉÏŽ‡^Y¿G<¨à¸Åïí å‹HÙþÌØàñJy/šg«Á¤ñN‚cO¼aâ§Z7iu«J88%û&ç6Bú±áƱñòØb¼û6»öMÂ×nÛ“¹¬8xh2•Uè&J]>Ĭ-K/dísÓNŧBè2ÓŒE«îø(íO…&xÓ2¡¼?}"ðnË„ÊþTh-^º,ªûS¡Nôåq'’ µý©P#¯X&Ô÷§B•¼j™ÐØŸ>xÍ2¡¹?*Dà Ë„îý©P&oZF¤FþøÔ(w[&”ö§BÑâåË2¡¼?}"ð²eBeJ4o"ðŠeBu*4‰À«– µý©Ð ¯[&Ô÷§B’2¡±?}"ð¦eBs*ÔˆÀ»-º÷§B•hñJ²Œˆv0?5*XÕ–í!™PÚŸ I^È„òþô‰À‹“Ÿ„ÊþT(×-ªûS¡‹¼a™PÛŸ­Åï¦ùŒó&$êûS!ÉpÒÐe™ÐØŸ>xÉ2¡¹?DàeË„îý©P'¯XFD»™Ÿ5"ðšeBi*T‰Àë– åýé7,*ûS¡BÞm™PÝŸ e¢Å[Û‚dBm*”ˆÀK– õýé—-ûS¡‹èËs•$šûS¢~×,º÷§B“¼n‘ŽçÀ§Fƒ¼ ¥ýéw[&”÷§Bhñ–J"™PÙŸ 5"ð’eBu*T‰À+– µý©dà…L¨ïOŸ¼f™ÐØŸ åγk¼g>¢¹?JDàMË„îý©ÐEÞm‘šÁ§qäÌGtâ”7É„Òþô‰ÀË– åý©Ð$¯X&Tö§Bƒ¼j™PÝŸ u"ðšeBm*$xÃ2¡¾?}"ð¦eBc*T‰t@©dBs*Tˆk,eB÷þT(—-#êW|j”ˆÀ+– ¥ýéW-ÊûS¡‹¼n™PÙŸam¢ Ž@’ Õý©Ð$oZ&Ôö§Bƒ¼Û2¡¾?}¢Åƒ®B™ÐØŸ u"ð²eBs*ÔˆÀ+– ÝûS¡J^Ȉt >5*DàuË„Òþô‰À– åý©P&oZ&Tö§Bé£S,u•²¯W÷§BÑ÷ñ©PÛŸ>QüŽ¶Gߟ>‘Çeô=.c:öèyTË„æþtî_´ŸÇØÏCÇBñÓ{нywðæ~ FÈó@¥ýiŠ1SÌ«™b^ͼ?Í1æžÇe™PÙŸ–˜Ù³Ä|ž%æóÜo…Þ¨Y7¯n^ÛŸ¶xCg‹÷h¶xtD?í±2ÐLæÛH™ÐØŸŽXiæÛM™Ð^¥ŒxÍ2¡{zÇÊ:ïÍ»ƒw_ñ©Ñ ò:t_±Ýiº÷;źv§X×î½agºs¬“wŽuò.ûS¡Dô}|*T÷§B’y}¾k¬Ï:(ŸîýÖó¸,êûS¡Fä}áî±/Üc*Ô‰¼ÏÜ#ö™{îO…ÆG§=ŸO…îýéÖ´dŸñ„<öƒâT0ú£#äd£ ¦CL‚Ú^-5̇ ˜µe[jX!ô`Âï“`XA° Je°Ô°‚`”b©a?„°LÁM!5‡ x J ²Ôp‚,FK¿O‚á}‚IPj˜¥‚2ßIHa9Jµ³Ô0‚`w„Ô0‚`”ji©a9AK¿O‚a=„°ì ¥ÚZjØAð”ºl©a?y\.A©à–ŽCL‚àæÎCÏ á÷I0¼A° Ê\°TPf> †MP&ˆ¥†é‡ ÌK ó!„gŒðû$–C´Tf•¥†õø„®Kܱ¥‚í³ Ìº öC,‚2C*8A° ~_Áy‚mfÜŽTð>Á!nÙRÃym‚ᔩRÁt‚· Ìï æC DwßK.‚A°‚`þø´Pý!¬‡ èÓDåR©`;Á*øõÐ’ öCì‚ri„Tp‚ ¥ßAp‚à”K%¤‚÷!Þ‚rÓ„”°^› ˆ®¬—\µn©`:Á,(7QHó!Zú}Ë!VA¹©B*XA° ÊõRÁv‚CPî´ öCœ‚pÑÝ[*8AÐÒï‹ 8°$A¹þ¶”ð>Á,(wâ–¶k ‹ \”[J˜0">Ë’aýþâ ¬åF1Œc±´Òâk ùÐ÷¬GŽ¨Å~åì3Ká“¢÷»n¿º,÷v kÛ×ÖËÒÖ34o´ãq8´Iñ‡§ó®I5€ÓC %Ü=2 xÊh§2Si<_~0vÀµ-Yêaö^aH1¬0c“·et„Þd#›Ž‹í˜çK€à“-:üc°âCÍ âÏ› 8Á­[JÈñÁp‚Û¶T0‚`÷Hó!¼ ¸sKË!6Apï-¬‡ X¿¿& /(5l‡ XÁÍ!5ì‡ h)¸[j8áÁ­!5œ‡ ˜Ám!5¼Aðw„T°]› 8nApgH Ó!Z î–æCxÁÅMWH Ë!ApsH ë!vApKH Û!6ApkH û!Z î–ŽCxApGH ç!ApgH ïCÌ‚àÞ!ì×&&ÁÅÍWH Ó!Z n©a>„·„Ô°!KéAœ¨ÌÔ°‚à·…Ô°‚àw„Ô°‚`w†Ôp ‚{‡Ôp‚`\Ür…Ôð>Á*n© ½‡"ApKH Ó!fApkH ó!¼ ¸-¤†å“ ¸#¤†õ/ApgH Û!"¯BI<³Ü!5ì‡ 8·¦ŽCxApsH ç!ApKH ïCì‚àÖ rcÁ° ‚»¥†é« ¸#¤†ù^ÜRÃr‚EÜ;¤†õ³àâ¶RÃv‚–‚»¥†ý/ApKH Ç!¼ ¸5¤†óõ+øÜ4ê|n‚÷!NApGHéÁÐRp·Ô0‚`÷©a>„\\Õ4ó¹ –Cl‚àæÖC¬‚à–¶C´Ü-5ì‡ ˜Áí!5‡ð‚àŽÎCL‚àÎÞ‡ x ‚{‡”°]W ‹¥‹;RH Ó!NApsH ó!¼ ¸%¤†å‡ ¸5¤†õ» ¸=¤†í› ¸#¤†ý« ¸3¤†ã^Ü;¤†ó‹àâÎRÃû³ ¸9¤‚éÚÃ$n ©a:ÁKÜRÃ|/n©a9Bìè.Í «CRÃz‚SÜRÃv‚Cpqï+¤†ý» ¸)¤†ã^ÜRÃy‚MÜRÃû« ¸[*H¥†EÜRÃt‚YÜRÃ|/î ©a9Á$øý…,CK ë!Z î–¶ÿÝÖ½\¹’I˜Þ·W‚:7 G«ÑXŒþ›I¸™æœYÕw¼þ¼ù “ "ÉÓO›}Jö€ÛÒ\ølv»ïÆ*ï&´-Í…Ïf·8^0îÝȶ4>›Ýnà|Á¼wOÛ/Yølv»ëëþŠØ~ɲ{ŸMÁú~ÉêûÕ³ý’eŸÍ¦dzAº¿þ¶_²ì³Ù”Ì/È÷!ÈöK>›Ýn`yA¹m¶_²ìQæä{p¬ï!ÓöK>›Ýn`{A»ñ¶_²ðÙìvû ú}ê°ý’…Ïf·8^0îS’í—H@¾'µúžêl¿Dr½ìàýz×ýz±IbÉ©ÿÚwØ$AðŽKZº?ß–îÏ·½ƒr§­>%Ë p<™À­Y_fÐï­Þû6IÜãÉÖÚ½Ÿµvïg­¿¬ ß[¿÷_l’ ;è¿mÜß l’ ¸5 × î: Ù~ɲßn›‚ý®œœúï±MÉô¬ßè=ÝÇl’ 3è;=ßÇl’ ¸ë·ÖËkËkë À úc_¯÷±›$ÀžöNÉþp€þøÛû}üÅ& ‚»în}ÜÇõ>îãzŸ/¸5 × °_’@néë>·p“D˜AÎß}Îz›$ím4Û/9WÏsJæ€ôçM›’å`·d}8@î8.1¶Ü-¯6Ú=&8.1ö€ ôcããxö'xÚêSr¾ÌàÖ€\/¸[•m¬{l4p\rˆM’!¬ sM—Ó Àú±ÜÄífÌ/èLj·›±¼àn1·ùŽ'ç;žÄ& pç8uù”l/Àù€ú1-öKÀþ‚{>ï̈dì—€ã`ýû%à|XÁ­¹^6Ð×ó­°I2…}Oo7i¢­owi¢O?ê›ÃCšèÓÏôæð”&Úúñæ𒆞ðéW}s3^oÍÿúóÖR>§“4ÑÖ;§³4ѧ·—RÄœ.ÒDŸÞîØÓUšhëÇÓMšóÓÛ}sºK}z»cNi¢­szJ}z»cN/i¢Oo÷aÌáþ½æÇÖ¿9¤‰>½Ý‡1§³4t‡O{9§‹4Ñ;6ô’†nðŽ <¾×üؾþuçt—†®ðŽ =¤‰¶~Þ9<ókÜÞ±¡‹4ÑÖ;§—4t†wlàõ½æÇÖ÷;§»4t‚wlè!M´õíÎÍx±4×ì÷7Îé%ù,v ^#40^êÍ­/wNwiè ïØÐCšhëóÃxù4î[Ÿî.ßkܶþ»sºKC7xdžÒDÛãús¸–׸+¼cCWi¢­Ÿw·ï5îûãçô&Úú~çô”f¾Ûš·ÒÐrkï±hùãík`ŒÛëèúãí›ÓIzÁ;6t–Î Þ±¡‹4pÉðŽ ]¥¡'l}»sºIWÎwlè. |ΑàϼCCiè ïØÐSø,ñgß¡¡—4°ýÞñùE˜Ï)Ö¸l}½s:IOÎwlè, ¼>xdž.ÒÐÞ±¡«4¸ÏsþL<4t“N¼¸KCwxÿ4ðζ¾¼9<¥¡¼xI—ïŸÆŒ—\CCŸu3þ¬<6p’†^ðþià, |–±‹ÇÚÀEšãû‚gk¦ÿlµ†…hx ´s]þ±ï˜ /{ÖñRÛXpd{¢àÃ1ç Äáÿú·Ç‡à"‘v3ðá ¯¹½ÞÝ¥ÉÝ‘KJ{ZJøµ<©~(`‡_ü1Ù« ó.˜íp ?Žb¯mŽo©Ú!>×yh˜“‡Èö:åIŒ»æ9Ôö§ábO·ü÷Ï]¯èk—¹?û ½eäk¶÷Ü;ï:^ð“ù¼£wÁ[Lº3œŸû‚÷oc.Òж~¼9\¥¡+¼¸ICgxÿ4p—¶×ÃÛ´w¿sxHCxÿ4𔆮°õëÍá% áýÓ˜ñ>9hèÊùþià$ =àÓÏïÍá, ]áýÓÀE:ÁÖ§7‡«4pYðþià& ÝáýÓÀ]ºÂÖç7‡‡4t‚÷OOià¼`ëË›ÃKºÃû§1ãŸÐ¸+¼8IC'Øz™ÃYøv–¥ÏÒièÒÐœ[ßÞnÒÐ Þ? Ü¥í=5oßþæð†æ|ÿ4ð”†.ðþià% `ëÇ››û÷Ø–M£¯g'iè[ÿæt–†.ðŽ ]¤¡¼cCWi`Ÿ[¿îœnÒÐÞ±¡»4tO 9§‡4t‚wlè) lÛ}J?¥_ÒÐ ¶>Ý9<¾×¸ ¼cC'ièÞ±¡³4ðYb¼e?§û9§‹4tƒwlè* ]`ëËÓMúƒwlè. Ü&¼cCiè[_ÒÐÞ±¡—4ô[ßîžßkèsšfÌïõó“>ICs¾cCgiè [ßïœ.ÒмcCWiàsì8&oßqçt“†nðŽ Ý¥¡3¼cCiè¶~Þ9=¥ó€wlè% Ýàx}¯qgØúuçt’†þà:KÛ[já YÇ÷æt‘†nðŽ ]¥‰Þ±¡›4ÑÖ§;§‡4t‡­Ïwnžßw›ë[_îœÎÒж¾Þ9ݤ¡l}»szH3îm1?~ýýÎáô½Æ`ëÇÓYš|ï3eé³ôEšhëçÓMºÀÖ¯;§‡4t…wlè)Môéí”&æpþ^“ßïÎÄë{/Ìé, ÝáºHm}¾sºIÓîïþÄ­{÷4Ìé! =ázJm}½s¸|¯q/xdžNÒD[ßîœÎÒäûØ8K–>K_¤‰¶¾ß9ݤ¡¼cCwi¢­wNiÞsÁ,Cú!ý”&Úúyç0ÖÂhÜåOõ‡†NÒD[¿îœÎÒÐõOõ‡†.ÒDïØÐUšèºIóž¯qªŸ?ÃÚÞϳvi¢ïý³öwÿ¬Cºÿã©~þÖñ~ë”&ú>þ`>Þé}o¢ïã'æ<ÿ½ÆÍù}¾hß{¾hIšhþâœÎÒÐ÷T?žÓ9§‹4Ñ~üÃ9]¥‰öãUÎé& ½þñT?Žá9§»4Ѿþš¾^6iàs¬8e½¹^ÎåÎé"M´õéÎé*Môéí˜ëe¸IC'Øú~çt—&Úúrçô†Î°õoNOi¢Ook ®—á%M´õýÎa®‘[—¼ôû¢œÓIšhëÓÓYºÂ½í‹ú.ÒD[ßß®ÒD[_ÞnÒÐ ¶>½ùâ%E¯‰>ýœoih^‚d}sxJm}ysxIm}zói—/}·¹ðéϾ¨Ïá$M´õýÍá, =aëË›ÃEšhëÓ›ÃUšèÓw™ÃMzÁÖ÷7‡»4ÑÖ—7‡‡4Ç~êûûÿÇ3g‡…+@ÝÍ韤øæ©Rº|ÛÔݶõÐ¥âjjüà¹aÖlÓ$¶AèwvÛ y'f¢mãámœû"¸ÛÂë}£¾8èrŠk1ù±ï‰±½ëùïwbÇŸüíÁ•n¶ÃV{æ =,ùàj›ë}/¹¾_n ØW~7ÈÌý=˜ey²JòÄÂ;W—Í6ÿyâz9ï¶]’-0Ëy‡lóÿ]'¸‹üןwÉö9¥¡+l}ºsºHCØúrçt•†Î°õõÎé&M´õíÎé. `ëûÓCúƒ­ŸwNOià¹`ë×ÓKz§OßÃí{Í­OwN'iè[_îœÎÒж¾Þ9]¤¡l}»sºJCWØú~çt“&Úúyçt—†.°õëÎé! áÓçïÎé) `ëÓÓKúƒ­/w÷ï5?¶¾Þ9¤ÏãWê¸}ÏÆ&çt–†ž°õãÎé" ͹õoNWiè[¿îœnÒDŸ¾|wNwiè[ŸïœÒж¾Ü9=¥¡9·þÍé% aëÛÃã{Í­wN'iè[?ïœÎÒÐlýºsºHwÎO_ßœ®Òж>ß9ݤ‰¶¾Ü9Ý¥¡l}½szHCwØúvçô”†æÜúqçô’†®°õóÎáù½æÇÖ¯;§“4tOžã9§³4t†­ÏwNiè[_ÒÐl}½sºIm}¿sºK·[?îœÒж~Þ9=¥¡lýºszICwøôø9àö5¯ï5î[ŸïœNÒD[_îœÎÒж¾Þ9]¤¡ l}¿sºJCgØúqçt“†N°õóÎé.M´õëÎé! ýÁ§oNOi`û=Z¸}íqszICOØúrçæü}·¹°õõÎé$M´õýÎé, ͹õoNiè[?Òж~Ý9ݤ¡ |úsÜÂ9Ý¥‰¶>ß9=¤¡9·þÍé) `ëÛÓKúƒ­ïw§ï5ôyÌ ·ï9îåœNÒD[?ïœÎÒÐœŸ~}wNiè[Ÿîœ®Òж>ß9ݤ¡¼cCwi¢ß×ÓåëÒÐÞ±¡§4tßÏgÊÏgICgØ~þëÎáü½Æà{{åïÝ^9I}ï9½ûCÎÒмcCià¼à{ÿÄœ®Òо÷Ìé& =`ëëÓ]šèûû˜ûû}ÌCºÃ;6ô”†nð}|Èó=>ä% ]áûø“×{ü)ßkܶþ»s:I}Kz‡%KCgxdž.ÒÐ ¾ÏEŸK•†þàûø_ê{ü/M8-ø>¿`Nwiè [ßÒоÏwe¾ç»²¤¡;ìϧœÃÜk²ÆÝ`¾æœNÒÐöãÎé" ]`ë¿;§«4t†ýø„sºIC'Ø8§»4ôûñçô”þìÇoœÓKzÂÖ·;‡¹Gd{À~<É9¤¡;ìÇ«œÓEºÁ~<Ì9]¥¡+ìÇÛœÓMºÀÖwNwiè ûñ?çô”†N°¯/8§—4ôûú…s˜{8ÖÀùì»fîçœuçt’†ž°õíÎé" =`_¯qNWièûzsºIC7Ø×›œÓ]ºÂ;6ô&Úútçô”†.°¯—9§—4t†}=Î9<¾×¸ìë}Îé$ ýÁ;6t–&Ú÷8§‹4°çøþL¿sºJCOØ÷C²ïϘ›4ô€}¿%ûþŒ¹KCwxdžÒDûþOöýó”†n°ï/eߟ1/iè [ŸîÆÞ w}¿+ûþŒ9ICgxdžÎÒDûþçt‘&Ú÷÷8§«4U¾¶z÷9§›4M¾wî¯ö;§»4ýýl¹?# =¤ï¾Áý™òæô”f¾ûÞ|û«œÓKšõîÛÜŸ±u÷gÌë{ m¿;ÜŸ±u÷g`ùus¾cCgiò{láþŒ­ ¸?iÊ{ìâþŒ­ ¸?Wiê{,]oÿœsZ“ÝöýyÎé.MÏÜŸ‘†ÒŒ÷ÜÄý[pžÒÌ÷ÜÇý[p–çPw†­own.Ü“9Íu­¯wN'ihÎwlè, Ý`ëËÓEzÀÖç;§«4ô„­OwN7iè[ÿÝ9Ý¥yÇŸ…û3ÒÐC:çOëÎé) ]`ëçÓKºÂÖ;‡¹'cMzë…Âý™³ŽàœNÒÐÞ±¡³4ô„­owNiè[_Ҽõ]áþŒý¸?7iè ïØÐ]šsëßœÒж>Ý9=¥yë÷Âý»Ÿp^ÒÐ>½Ý¹?c枌5î ïØÐIšsëßœÎÒ¼ý™Âýû½ãþ \¤¡l}¿sºJCØúvçt“†®ðŽ Ý¥yûo…û3ß›ÓCºÃÖ—;§§4ô„­ÏwN/iè[Ÿî.oOÕ}Ž‹ ÷g¤¡“44çÖ¿9¥¡ ü×Û5->‡‹4t…­ŸoWiÞ^zÁþL9Ï›>‡›4t‡÷Owiè [/sxHC/Øúöæð”æ+)Øϱëp|/iè[_ÞÜÌ=kÜœïŸNÒж>¿9œ¥yçÂJåí›Þ.Òжþ{s¸JCOøôç¸Ñçp“†æ|ÿ4p—æë,Øÿ±ëp|iè[?ÞžÒж¾¿9¼¤yç¯ ö‹ì:Ÿ›Û;g}Íùþià$ Ýaëë›ÃYzÂÖ—7‡‹4ïú„‚ý%»Ççp•†×Ÿ|°õéÍá& Íùþià. ]`ë¿7‡‡4ïú“‚ë‹ì:œ;7Oiè[?en^Òûœç|Ë<ëãD¼òOW›v¥>Ò.àäec\~~ã]Æ°æ»dÂ.Ÿãåv©•ÿcåöµí\²šyxfÛÔ Ù6&ŸâmÉÓñÚ@}+o'i¢Oß¿7‡³4ô€­oi¢Oÿw?¸s¸J}ú¿/åÎá&M´õ2‡»4ѧ_õÍá!Mô_®}ö9=¥¡;lý¼szI}ú¿G ŸÃë{ÍOŸÓÓIšhëçÓYšèÓ—vçt‘&Úúuçt•&zdžnÒÐ Þ±¡‡4ÑÖÏ;7óqÁšë ïØÐUšhëÇÓSºÀ;6pJ¯ù±õýÎé* ázHí·/çpN¯q'xdž®ÒD[_ïœÒмc—ï5?¶¾Ü9]¥ÿž2ÚÐCšhëóÃxêFãžðŽ ]¥‰¶>Ý9=¤¡¼c·ï5?¶þ»sºHCwxdžÒDÛãɺs¸¯q7xdž.ÒDûãçt—†®ðŽ <¾×üØúqçt–†.ðŽ =¤‰¶¾ß9½¤¡3¼có¹Òš[ßîœnÒÐ Þ±ùœbÍ­¯wNgièÞ±¡»4ÑÖ—;§§4æóôæsŦ®5¿¶>ß9ݤ¡'¼cc“Íýù—s:ICxdžîÒD[ÿÝ9=¥¡;¼cçòšÛñƺsºJC7xdž^ÒD[?ï.é5î ïØÐ]šhëÇÓCºÀ;6p-¯ù±õýÎé* ázIíÇ{œÃí{;Á;6t—&Úúzçô&zdžžÒÈ} amè%ͺ¥µ-é×ëû{LvŸcƒÊç iè$ =à:Kgέ/wNià’àºJCxdžnÒÀµÂ;6t—n Þ±¡‡4ô€wlè) Ü+¼cC/ià‘`ëóÃ|εÆ=à:IÏ ïØÐYØî«|¾–†.ÒÐÞ±¡«4¸í¾:ªôUú&ÍñÝú[Oü‡ÔX{žÇOî-èïã´û¶},¶‚Î+¯fž9<¯"›y¦ñ¼ð]dØÁrâü̱µ3ì ¥ô7¯üØò«HòÎht¼£Íw8äÀ3­û¹¦hóš°…Q°”¶üà’ؾ .GÏÓjYo©_?þŠÖûÔ…9—ö4YøÍûðmÿ~-Ü i÷i༮ê}ʱÃP~.{J¶=M{Aëïï^‘øôßß­øôô„óóß½:ñècc^Òж~¼ù1ÿ8Þšë ïŸNÒÐÞ? œ¥ÿ~.‰@ÿùæp‘†ðþià* ]aë×›ÃM:Ãû§»4på|ÿ4ð†ðéç÷æ𔆮ðþià% aëÓ››ñâhè²àýÓÀIºÃû§³4t…­ÏoièÒÀyÁÖ—7‡›4t‡÷Owiè ïŸÒÐ ¶^æð”N Þ? ¼¤¡;l}{s3^»Âû§“4t‚÷OgiàoÁÖ÷7‡‹44çû§«4t…­o7ièïŸîÒ§µ&¼xHCwØú;wOièïи—4t‚whh¼ÏÚçÖ/Ÿ»“4t‡whÜYºÀ§_ŸÏÝE:Á;4î* lÛxÃiÜMºÃÖ'Ÿ»»4twhÜCšsë³ÏÝS¸Ox‡Æ½¤¡;¼CCã}Ѹ l}ñ¹;ICð;K· [_}î.ÒÐ Þ¡qWièïи›4ô[ß|îîÒÀuÂ;4î! ͹õÝçî) ]à÷’†þàï›…†.¶~øܤ¡¼CãÎÒж~úÜ]¤¡?x‡Æ]¥ó€whÜMºÁÖ/Ÿ»»4t†whÜCúƒÿúô}>wOià4à÷’†nð 7âAãΰõÉçî$ ýÁ;4î, ü x‡Æ]¤¡l}ö¹»JCs¾CãnÒÐl}ñ¹»Kcžv¿Å @JãÒÐ Þ¡qOiè [_}î^ÒÀö<Ø—ôëõx_14î[ß|îNÒÐÞ¡qgiè ïи‹4°­;oßîsw•†ð»ICWØú;wwiè ïи‡4p_ð{JCsnýô¹{ICWx‡†ÆûŠ¡qgØúåsw’nœïи³4ô€whÜEºÂ§·Ç¼$]¥¡¼CãnÒÀ¶VÅ @¦tçî. Ýá÷†®ð{JCsn}ö¹{IÛZ/) ÷UEãî°õÅçî$ ]áw–†Nð»HÛZuñö­>wWièïи›44ç;4î. `ë›ÏÝC8Mx‡Æ=¥¡;l}÷¹{ICx‡Æü·°û¼yNð;IŸSÜßÇÛwøÜ¥¡;¼Cã.Òж~úÜ]¥¡¼CãnÒ˜m?ñûšôMú. Ýaë—ÏÝCºÀ;4î) àÓŸS˜»—4ðœð Í÷ ¶ÆÝáûý¦ï}¿¶7å ]`Þ?9wgièæï/çî" <&ÌÇ[ÎÝUºÁ|>âÜݤ¡ ÌãÎÝ]úƒy¼Ä¹{H÷ óø–s÷”†n0ÿ9w/iès½Æ9Í7|´ÆýÁ\/sîNÒÀçìÀÇý«uçî, Ý`îÿpî.ÒÐæþçî* ýÁÜÏäÜݤ넹ß˹»KC7˜û휻‡4t†­¿s÷”†þ`ëïܽ¤Ë€­¿sšï“m»Á§ïwîNÒжþÎÝYúƒ­¿sw‘ζþÎÝUºÁ§owînÒжþÎÝ]úƒ­¿s÷¶çî_µ;wOi蟾޹{ICgØú;§±g…ÆýÁÖß¹;I}ús&ñ«÷„}Ðk¢­>wi¢­¯>wWiè[Ÿ}înÒDŸ>/Ÿ»»4ÑÖŸ»‡4C~¶¸}sõ¹{Jmý»å6uøôöœ^ï9»ÝæÇÖŸ»“4ÑÖWŸ»³44çÖgŸ»‹4ѧÿ–ÏÝUšúîÛÜ¿ú†ÏÝMšhë«ÏÝ]šhë³ÏÝCºÃûìÐÖçô”&Úúqçô’f½ß}Û¿²¥‚Ïa#éñÿµõùÎé$Môéçºs:KCOØú7§‹4ÑÖ×;§«4Ñç|N7ièŸ~¬;§»4Ñç|Ni䱺ãöõÎé)MôÆyŸÓKšèÓ÷uç0ö¬Ð¸¼qÞÁçt’&Úúzçt–&¿ç²Û·¿9]¤‰>}[wNWi¢­ïwNËs®»ÀÖ×;§»4ÑÖ§;§‡4t…O_×ÓSšhëûÓKšhëßžßkÜ ¶>Ý9¤‰>½=çNžw0gi¢­ïwNihέ¯wNWi¢­OwN7ièŸÞžs'Ï;˜»4ÑÖ÷;§‡4ÑÖ—;§§4ô„­OwN/i¢OŸÞ^ßkÜ ¶¾ß9¤‰¶¾Ü9¥‰¶>Ý9]¤‘cé…Û×Ö°‹çÌUšhëûÓM:ÁÖ—;§»4ÑÖ¿9=¤‰Þÿc—RùœžÒж¾ß9½¤‰¶¾Ü¹9}ßm~m}ºs:ICøôgŸ„s:Km}¿sºHCWØú7§«4ÑÖ§;§›4ѧóÎé. Ý`ëûÓCšhëËÓSºÃÖ§;§—4ѧïóÎaîYYócëÛÓIzÀÖ—;§³4ÑÖwNiè Ÿ¾Í;§«4ÑÖ·;§›4ÑÖ—;§»4ô‚­ÿîœÒDŸ¾Î;§§4ÑÖ·;§—4o¯#%ܾµÜ9Ì=+k~lý›ÓI:Á§·ŸCæys–&Úúvçt‘&Úúrçt•†Î°õßÓMšèÓçyçt—†.°õíÎé!M´õoNOi¢­ÿîœ^ÒÐÞ8Oás˜{VÖüØúvçt’†æ|ó<çt–&ÚúïÎé"MôéÏ–sºJCwØú7§›4ÑÖç;§»4ÑÖwNièÿõvy»Ïá)M´õíÍá% =aëó››¹geÍ­ÿÞNÒDŸþ¬a}giè[ßÞ.ÒD[Ÿß®Ò¼ýg¼?ÎSønÒDŸ~Œ7‡»4ÑÖ·7‡‡4t‚­ÏoOi¢­ÿÞ^ÒÐ>}onæž•5?¶¾½9œ¤‰¶^æp–†.°õß›ÃEšèÓ·!ss•æø¾!ÛßÓÐçÈò;ÿáÞ>ÿv u.>oÉöÙÅS¸ æ³ »/TO÷b\ ¾v/”°½¿€å³‹(;ÿ8À.f䉅óïp“Õ.”à†º]tÀ“ E.tµ“çÜÔ·ÑE.‚ææ¢ÍÜXõ‹¾Ê“¥öïßt¶'ã'î>Ûhñ‹âÍróÂëmðIn{Ùå,Ü&³KcûÝb»ŸÙ.âŸjØÒ…§ÁlYÂKcípŸ—iÚé"^"9ÞV2¶9ʽlÑO› Ÿ‚]å]~±ìR~nÁØe”Üë÷r´óÝØægâ"î|Ï8H[¶‰ÊÏ`ž8Xº=>:s[qãRÁ»¥g˲~/Ù»[kÞÛGOÛ˜àºá½mH¥·à p³~bÓ°¾9/â±Í5^ b'#yq†D¡í'6ﾑ7ñÕñb‹ò>o¾·š]ðá'¤ï×oßÍ°{ŸžlKOsë݆8}ßåR^je?m^†ñÙ!%ŸJäÐtñðÏâäËr…}ykÛJó=­û6©Ýwü!Ô̇µî÷/ûs£v.‹8ýÙÎå§?éççsYÒÀéÏؘ«4ô€­o7iè ïŸîÒÐÞ? <¤1×µ`ëçkà) =àzICWØúuç0Nm¢qgxdžNÒÀ“ó:KCøôç²WÎé" ]áºJCgØútçt“ Þ±¡»4ô€wlè! ]aëóÓSšózI÷[_îÆ©M4îïØÐIºÂ;6t–†Î°õoNià¶àºJCØúvçt“†®ðŽ Ý¥¡3¼cCiàº`ëûÓSzÀ;6ô’†®°õoãè;Ã;6t’>ÏÝ£%é“ôYšsëçÓEºÂ;6t•†Î°õëÎé& ìóºKCwxdžÒÐ>ý9圞ÒÐ Þ±¡—4°=Nâò}m`½¢qwØútçt’†®ðŽ ¥¡9·>ß9]¤í¹—ïkCWièïØÐMºÂÖ—;§»4t‚wlè!¹Øskçí[ÒÐÞ±¡—44ç;60.ÍGãN°õíÎé$ lÏ­#IŸ¤ÏÒж¾ß9]¤¡+¼cCWièïØÐMØž[oßqçt—†îðŽ =¤¡+lý¼szJC'xdž^ÒÀöÜ:–ôëõX•¢qwØú7§“4t…wlè, àÓŸ?ëâœ.ÒÀöÜŠË÷µ¡«4t‡wlè& ]aëÓÓ]šózHÛs+.ßoö¼Æ·c‡§4t‡wlè% ]á—æ£ù±õåÎé,M´õoNièïØÐMšö¾—ÅŸÿ›Óò3qØú77Ïï»Íõ„­sºHSîm1?~ýoN7ixÿù`ëßœžÒÌ{ߘ¸¼»ÉÆ¥ØhܶþÍé" ]`ëßœnÒ¼ûÿÄåÑMæô”†n°õoçï5î[ÿæt‘†°õoN7iè [ÿæô”fÞÇŠÉõ©Ìáò½†>ûB“ëM™ÓEš÷Ø5¹”9]¥‰Þ±¡›4t†ß×ÓäëéÒDߟ׃ð&úÞ¾\ÂSºÀ÷þÆõ ¼¤‰¾¿/\šë÷w…ïïo•ßßš¤‰öÇÎé,M´?~rNièûóçt•&Ú8§›4í>·N®K½sºKíÇ«œÓCšh__L_š§4ô€}ý5}=h^ÒDûzyúzð¸}¯qOØ÷+¦¯ÍIšhßÏáœÎÒDûþçt‘†^°õõÎé*M´õéÎé& '?øôß›Ó]šhëûÓCšhëëÓSšw<9¹üÒÓKšèÍ}?Îa¬õи3l}¿s:I½¹ïÇ9¥‰¶>Ý9]¤¡ |úó2œÓUšhëûÓMºÂÖ¿9Ý¥‰¶>Ý9=¤‰>ý˜wNOiè[ßïœ^ÒD[_îæÐw‡­OwN'i¢Oo¿wƒûxæ,M´õoNiè[_ÒD[ŸîœnÒÐ>}›wNwi¢­owNi¢­/wNOiè[ÿÝ9½¤‰>½Óîãs h }^6kb=xÞâÐçt’&Úúrçt–&Úú7§‹4t‚O_æÓUšhëÛÓM:ÃÖ—;§»4ÑÖwNi¢OŸçÓSºÀÖ·;§—4ÑÖç;‡¹´Æ]aë¿;§“4ѧOãÎé,M´õíÎé" ͹õùÎé*M´õßÓMºÃ§ÿÆÓ]šhëÛÓCšhëóÓSzüó—#ËÄ–yûÎ7‡³4ô€÷Oiè Òж~½9ܤ?Î÷OwièŸþl)ùÒÐÞ? <¥¡3¼xIc}ç¯2Í֧ט±µ†Æ=àw’†®°õÙçî, Íù»HÏïи«4ô€­/>w7iè ïи»4t†­¿s÷ Þ¡qOièïи—44çÖ7ŸÓx†EãÎð;IŸ­”VyûvŸ»³4ô€whÜEºÂ;4î* aë‡ÏÝMØ~Ok“¾Iߥ¡9·~úÜ=¤¡+¼CãžÒÐÞ¡q/i`{n­¼}—ÏilÝ¡qx‡Æ¤¡+|ús´†¹;KCgx‡Æ]¤í¹o’#»JCØúäsw“†®ð»KCgØúìs÷¶çV¼Éƒ4î) =à÷’†®°õÅç4¶îи3¼CãNÒÀöÜÚyûVŸ»³4ô€whÜEšów•†Î°õÍçî& lÏ­½IߤïÒж¾ûÜ=¤¡+¼CãžÒÐÞ¡q/iÌÓž[;oßásk4nÎwhÜIºÂÖOŸ»³4t†whÜEØž[G‘¾H_¥¡lý»›4t…whÜ]:ç?ÛT˜»‡4Ñ;4î%M´õÉç4VÁhÜÞ¡q'i¢­Ï>wiÊûÞñ¦UÒ¸«4ÑÖŸ»ågînð»Km}õ¹{JCwx‡Æ½¤‰¶¾ùœ^ßkÜÞ¡q'i¢­ï>wiè ïи«4ÑÖŸ»›4íýî¬&}“¾Kmýô¹{JŸ–¶¦ôSú%M´õËçpÿÒm®|ú7wiÞcKÇ›ŒIã®ÒD[Ÿ|îîÒжþÎÝSšy;ÞdR÷’&Úúâs:½Çäë[çî" Ýáw•&Úúæsw—¦ßçŽÎý‡7w/iè [çtN¯q/x‡Æ¥‰Þ¡qi¢ï÷Ëõ>\¥ÁñÆÙÖí\ïÛmÊõ>ܤ‰¾÷O®÷á. `ÿýí\ïÃCšh¼ê\ïÃSšhüï\ïÃKšwìѹޟŸÏi®ñ­ù±oôòŽ7:×øhèûñXçzÎÒDûñpçz.ÒDûz¡—·^è\㣡+ìë»^Þz°s&Ú׿Ý×ûæ.M´ï?t_4tƒ}¦—·ŸÓ¹ÆGíûië}xICwØ÷;×ûf®ñ­ù±õÙçî$M´õŸÏÝYzÀ§¯Ãçî"M´õÍçî* =aë³ÏÝMšèÓŸueçzîÒD[?|îÒÐ ¶¾úÜ=¥‰¶>ûܽ¤ÓŸ>ß9Í5¾5?¶~øܤ‰¶¾úÜ¥¡l}ö¹»H}ú´|î®ÒD[?|înÒ¼µaçz?UŸ»»4ÑÖß¹{HCøôv»p½Oi¢­>w/i¢­¯>§¹Æ·Æ͹õÙçî$MôþìëúÎÒÐ ¶~¼9\¤‰¶¾¾9\¥‰¶>¿9ܤ¡;|z;æäîÒD[?ÞÒÐœ[_ßžÒD[Ÿß^ÒDŸ~¬77ï5î [/s8Im}}s8Km}~s¸HC/øô}½9\¥‰¶~¼9ܤÏe—óؾ®Ïá.M´õùÍá!MôéÛzsxJC'Øúñæð’&Úúúææù½f¾ýºŽËyl_×çp’&úôg_×çp–&Úúñæp‘†.°õõÍá*M´õùÍá& ]áÓÛs.çp—&Úúñæð&Úz™ÃSºÁÖç7‡—4ѧ·ç\Ÿ¯ï5æû&¥¾ÖùoÝ#­ö鎿ú1ìÕ|û½Ø)6<=Õõ¶ k}Û’ç*'·mÛrûζ@¹õdÛ•ÜÖ°Cǧ2m)ÇÓ¬ç áR+ߥJ9„—0vÍïôœ/E;—Ì÷´‘mü/h±™Aû<ÞÀ6ãù a'"üæ|g¼ó[Üï‹Q{[6?0r€f6|Âï|·_2;™ïè'%ì «¼–×yþ» »b zÜy«-ôÇûÅúÚýš¹QÁ¯yý|Íç"Šz^‘*á%"ëyu§„×Cp7¸Š¼s—>÷¼Dd=¯õó†îðþià) ]áÓŸŸÏá% àýÓ˜íîφ>÷^¼Ddlà$ ÝaëÓ›ÃYºÂû§‹44çÖç7‡«4f{«/¼Ddlà& ÝáºKCWØúrçô†NðŽ =¥Ïf ^"²žW×ò9½¤¡;¼ccÆË?¢¹.ðŽ ¤¡l}»s:KŸ“x‰ÈÐÐEºÃÖ÷;§«4twlè& àºK÷ [?îœÒÐÞ±¡§4t­ŸwN/ièïØÀé{ Ý8ß±¡“4tƒ­_wNgièïØÐEúƒO_¿;§«4pðŽ ݤ¡¼cCwiè[ŸîœÒмcCOi`üœqûž3Îé% Ýà8¯qxdžNÒÐlý›ÓYø<¯á%"CCiè[_ÒÐÞ±¡›4ôïØÐ]ø,èð‘5Ùížyûš‡44ç;6ô”†Î°õýÎé% ýÁ;6pù^CŸÍ ¼Ddhè$ Ý`ëßœÎÒÐÞ±¡‹4ô[?ÒØf‘mVà%"CC7ièïи»4t†­_>wiàÉù{JCøôö¸TpûÂKºÂ;446xѸ3¼CãNÒÀçø/YÏ«rîÎÒÐÞ¡qiè [Ÿ}î®ÒÐœïи›4p_ð»KCØúâs÷†®ð{JCgØú;w/ià¶à¼hÜÞ¡q'i¢­o>wi¢­ï>wWiè ïи»4ÑÖŸ»‡4C¾÷!ý~Jmýô¹[~æôY×¥¶¤_¯ÇTh~lýò¹;KC'x‡Æ]¤‰>=þüüá*M}÷¥^¥¯Òwi¢­O>wièïи§4ÑÖgŸ»—4ëýîô%ýzýH¯ù±õÅçî, Ýàw‘&Úúêsw“†îð»Km}ó¹{H#EcH?¤ŸÒD[ß}Nc×{Â;4î$M´õÃçî,M~½3KŸ¥/ÒD[?}î–Ç|úœ,NÜ?y»Kmýò¹{HC'x‡Æ=¥‰>=þüü͸` ;Ã;4î$M´õÉçî" ]`ëïÜݤi﹘û¯qwi¢whÜCšè÷ýù~§4tƒïíËý xI}_¸_qœ¿ï6×öLJÌý 8Ií·™ûp–&ÚŸ_2÷+à"Í;vÊܯhÍçî*M´ŸdîWÀMzÂ~|˜¹_wi¢ýø9s¿ÒDûz'o½“¿) ½`_fîWÀKšh_gîW˜Ó÷šûþIöý s’†ÇÆìûKÙ÷+ÌYšhßß˾_a.ÒÐ öýÏÌý ¸Jmû·Ãçî&M´õÍçî. aë³ÏÝCšhë?Ÿ»§4tOŸ†ÏÝKšhë›Ïéü½æÇÖgŸ»“4t…­ÿ|îÎÒDŸþ¬‹3÷+à" Ý`ë›ÏÝUšhë³ÏÝMšhë?Ÿ»»4t‡÷Ù>wi¢­o>wOi¢­Ï>w/iÞÚ6c¿Â.´ËÜÇ0—ï5?>ý›»“4ô„­o>wgi¢­Ï>wi¢­ÿ|î®ÒÐ >½=sOnÒD[ß|îîÒp¿âƒ­Ï>wi¢Oß—ÏÝSšhë‡ÏÝK:ÁÖWŸÓÜ£°æÇÖgŸ»“44ç§?k(ÌÝYšhë‡ÏÝEšhë«ÏÝUºÀÖß¹»I}úº|îîÒD[?|îÒж¾úÜ=¥‰¶>ûܽ¤¡|ú²|Nsš[?|îNÒD[_}îÎÒж>ûÜ]¤‰>}^>wWiÞ~cÆþ†=ÇÜݤ‰¶¾úÜÝ¥‰ÞÜ—ÆÜ=¤¡'|ú´|îžÒDoîKcî^ÒÐ ¶¾úœîßk~¼¹/¹;I}úïÎÝYî'ðæ¾ô›‹4ÑÖW™›«4Ç~QÇ]»ü—î‘ÎÜënZ=oÏÁ´‹:xªÎŸŽÏ’™‡—™ÛžvhÁ-V? à–©Æåö£ýLâ]Ŷ[{¿O+iðTl¹ËO;¥ëK';Tà2Ä“èóMørÌNréZÖ[†Û©%Ûâø_?ÑÄ;‹UüŠ 75íŽÙßWm':øv~4I~‰}CnÙfÏ{àôk&¬ù}gv2„'ÃíI)É°âµ@þŸÿ©çº¼U=—}à¥¨È ŽÇú¯CƒÃö2ÿÃkPÅà°¿ü{ìÃëOÅàp¼€ÿðÚS!0Îõ^w*Æõ2ÿÃkN…à;9·)^o*Æô²ÿÃkM…À˜_@Öx©Ë Èô¯1c}˜×?¼¾TŒídÿ‡×– ±¿€¬ÿðºR!0Žé^S*Æù0­x=©× Èþ¯%‚CìYà,ÿð:R!0¦é^C*ÆüðÃtÇÀX^@öxí¨ë Èò¯c{™þá5£B`ì/0ž?hÃëE…À8^@öx­( Àù²üÃëDi®ß?¼F”‡xõ' œÓ0½€lÿðÚP€ùd1î€åägÜ!ë ÀéØ^@6ãØ_@ã8^@~Æp¾ì˜î€ëd3îñ”m3wÀôò3î€ùàßSÒJïvKïvÃ.²wÀú2wÀöò3î€ý`Æp¼€lÆp¾€ÌÆp½ü{JZéÝnéÝnØé±À9Œ;`zY;`~™;`y˜—q‡¬/ ‡q‡l/ «q‡ì/ ³q‡/Ó2î€ód7î€ëd5c3wÀôðïw•w»•w»açÙ;`yY;`}™Œ;`{ñ¼xï*ïv+ïvÃN ²wÀñ²wÀù‚Àp½ p‡Àˆ%ŒÎfÜ!ë êýÒëû™Õ÷3«ï›wã¸^@bºC`léÎeÜ!ë xÆ°¿ ß›»½¯·½¯«gd6î{º³wÀú‚w÷ìïëíïëíýd3î€ëëþŠô÷õö÷õŽtç0î€õ$¦;`A¿¿ÒoµÞ:kõ>î|ÆãL7˜ïaå­qÖ[ã,,Kî€õd6î€í;`YŒ;àxAà8_¸C®¼Çõ·nYoݲÖ{\Ü!Ó ÈfÜ!ó wÀò‚À°¾ Þ§¯·nYoݲV{AàØ_@ã8^¸CÎî€ë$¦;‡éãj%ýÿxdžNÒÐ Þ±¡³4Ñ;6t‘&zdž®ÒðÈêƒwlè&M´õíÎé. `ëËÓCšhë¿;§§4ѧ¯óÎé% aëÛÃ\ÕXócëËÓIšsë¿;§³4ѧ?—£sNi¢­owNWiè [ÿæt“&ÚúïÎé. ÝàÓÛŸbqíi¢­szJm}¾szICwØúïÎa®~¬ùñéÏ.-çt’†æÜúvçt–&Úú|çt‘&ÚúïÎé* =áÓoN7i¢­owNwiè[ŸïœÒD[ÿÝ9=¥‰þëÛo/i¸Êý`ëÛ››¹J²æÇÖç7‡“4t‚­—9œ¥‰>ý9½îs¸Hm}{s¸JCgØúüæp“&ÚúïÍá. ]àÓñæð&Úúöæð”&Úúüæ𒆮°õß››ë÷šŸþœj÷9œ¤¡l}{s8Km}~s¸Hmý÷æp•†îðéÛxs¸Im}{s¸KCØúüæð&ÚúïÍá)Môé«Ìá% =aëÛ››Û÷š[ŸßNÒßÓ”ã;oð·øø×8ž×ÌÀÛ¼è‚ßÞ1 Šó”çqÐwϹ#UžmLßléw?çï¦õíš’îNÈߪ|ÿk[ñç_>æï®âÎ=õ{뉻à8¯ â+¨³MÌ“lcÜõåÙh¶3Éÿ{n¤»Ýr^BÔ7lF÷/ȶÑû}ôÕèÙPà‚aÉaÙ”C„!OÉ]žzÛ;Ä97ƒ¯%J¹KÇ¿›Ê3åÝõüèøÈÁ/ú|·c±KÎ…¥•8üCµ/íÿç|Z M¶¾³²ÚSÉùðj7†¶<><ÄUí^héûx¼,ìþñÕëíõ{q)Ýù¿¸(ê¨Þÿk4{1‚óïÙ«eÛ+—Øëîšì$íÿ®û«û¿b²yÝÏf¯Ih_½ú'ßãá|f¼Â‹]¯ˆxÁc{) ¼ÌèôÀ0-ÿr‡- ÎG ;ä<_î°ƒ7{ Ó,þ×ý{Q¼å_.þåu?Û,﫱wwÅ ç£Ûý|öÍÚç³_û|&û|øQÜÀûg—}û¿öka±î¿²î¿l²Ï†òý¼ÿ¬ÿdð/ÛM?í(ÊÞÃ"×û à4Ï™â,~È<ù“ý­[ðÆ?Ã5ü‡Œ7Ò²÷°h“_Þœ oaæ?2üßu?¾Šá?düËë~¶óþÕØ×hÏÇö5ü~œÏƒ©}µÕ«ù=xÙg4{ŸÊç/’í_2ñ_âôïCó‡‹DòŸðg&çcðj°G+ßÁŸJ›lçîï[¥þ~§2ÿø)ñ+Êüù#<¨žÿkG×ç3ãÏ•ý_¶Ÿ5‹ÿßu?â|øWL5ûÿmŸD[÷»Æe‡çØ3®:<Ýf\@yþ½ŒkGϯZÆe¼à×<Àuvßà¿v¾z^Š:ý£L_óïmuÿÞæôïmVÿÞfõ¯tNÿêïüWL‰÷ ~¶óù>œf\á“Îÿ¶¿G:#<ê뤗÷³è¼/ñcZ°bûûgŠýÌÏW]lçâ|Õyñaƒ:_þïºqþÅ’†Ë~¶öí‰Ø>ÂŽ4οRšÿË}6‡Ü°¯ªø}ÿ2¿V»pÃ>ËÄã¹ïaj¿ø0`ïqN%¿_W[Ÿ¨ÙÚÐÿþü¿ Ý Õendstream endobj 6 0 obj 40796 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:02-07:00 2013-08-20T08:42:02-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000041092 00000 n 0000042662 00000 n 0000041033 00000 n 0000040902 00000 n 0000000015 00000 n 0000040881 00000 n 0000041156 00000 n 0000041197 00000 n 0000041226 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<3B15257BAB35E62C3370EBC11AEC7072><3B15257BAB35E62C3370EBC11AEC7072>] >> startxref 42832 %%EOF ast-8.3.0/sun211_figures/gridplot_bw.pdf0000664000175000017500000004770513004147321015030 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P064Ô3Q065TÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!æxa endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 351 311.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 351 312 ] /Resources 7 0 R >> stream xœ+ä T(ä2P064R065TÐ564Ô3¶´P(JUWÈã*ä‰(€TꙀXzf ɹ\ú‰ éÅ ú– .ù\@N¢× endstream endobj 8 0 obj 75 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 390 /Height 346 /ColorSpace /DeviceGray /Interpolate true /BitsPerComponent 8 >> stream xœí]|EßkÉ¥çÒ.•’ Ò«€Ti‚€€ M”"E„”"J/VzQ" MAjIDAªÒk(zéÉÍ·3»{·evw6¹ òÿý²ÙÛÝ·3¯Ì{o(A J ‚é1o÷¹îœÚ/vN=ÎǾò [Ejº}7ûž}7ï–|1…#8 À¯j@| €•ÔÌÂ6‘©),,GéôcD{·³Ú.@í=ÙÖL™_¹w“;¸Sî/†»ùC<ÜïFÅƇº»5Øภ3·½Äü pÃÿܶ…þP˜šÎžS<ýñà/ öVžý¤Mh w»¼ }óˆÞÕìH_o…`}Å‹ }Wèyûe°ØÃ) óu`+&8V0¨Ôô˜© ¨½î¹ô&ÓLoöWÌ‚ºM§Çïà«p÷ý¡äDü wç½Æ]ų5ÿÎQ¶b‚cX¤^²ïžÉ$­ätÞ)Ò&8yÿ2ÿóÏ 'ÅçQ{ãà&Raâ$ttý¾—õD»¿7`k´{äyî*¶Ø’wu0¸ÚÜòè™ÎDÃ]©Ý(3<ÇòttS “©²½:ýâÍî¥wÑQnÍÑçý®;¼ÞÁ½½öèÍðªï×G;nôOå1”î¯IôŽ±ÜúÐãü[FOó LµN,¬l2Õˆ‡WæÚ`¯ D'Ô¢ëY!ÓÖ„Ú&S¥Ñ\{ØVÁ¿ãô]ݧÁŸÿ”§ßÊ»yÜ‹ø“þ¹²– û๦ûÐþéª4‹aØÀõrt]Šv“£¸²l±c Y¼ùNÙ©@Z¯—ØŠá_…µpÜ n·‡ïÉÊ>³š×Ç¡íáÿfÏÖ²Wx4µìxÙKw¹;<Aå°µQðªÅ-×Sö]Žø&ÜmNËÃÞIÙg*üF?d»û‚§¯• 2ÆÔ)óWvÖçéß«cdgÿYjµ 6*äÇ °¯·•;¶%#ûŸ:ÜÓr­‚Ö¥éàHÔºàÝ—Þ¢ww”¾ Ž†\”¥BV(VšÑ€rÝé݇h×w0eÌ\a¶XŽYXøß`¸Íû…G…lt6Ïñrжõ¸wã_^K‡˜½½t'œÿbÜü?ú Òw°Q6îyÓ›GfÇõŽ øn¯ù0µ|€’ÅŽ‚Bà9]"½}ëhº>æ#¨‚Ÿ\¶™!s–ë¶î=ÀQaû"Ù†$EÂíì†ÿEKåwû|«ÿ'%·+Ü¡„‡»C°·KÔ8fË’˜Ç!f/‹~nŸËèÀuúY¶Qü;`jg¯w53´…¦R/¿Æ#wØ$·´Ÿ\«MüÂr÷qå„?Í ùm]£F˵€™uÑm}™›CÊûÞF»š¾ÿ¡Ý|û÷ÀË÷ßAÅòTðqh‡˜=ØÑ|*¤˜í³wÀÔÎ^ï8ê{×QùÝŸ§Uï ÷ô¼:ì¯6 mõMÕþd¼¬I^ߚͫ|:zè°ýÛOø½?C»g*0ˆ!ß•òÜ¥l±_›‹8˜áÚ·ž >Ün³Ÿà^Î^s‡˜½ƒ/ÐÌ´ÓòÁözØ;`jg¯GLpóú,®1÷ถí$Sá…ƒÂ6äÈPÁÑÖWÖ½|ô²áð–G]b*0 I ‡Ûí¥÷[ñ«2ÓÒC:C …¥/0ÇV0ÌÄwø3&î.ëÀE ¢æö¹KÙbæ‹x)h½U×;:„˜7££ókÐ=9£%_‹vb÷&ð0>Àž Kö»0wXëàÎ@T%:à¿©ƒ4“`tkú.€ï RáÊ—ü7 ¡Âä–Â6ÈPÁÑÖ­å¯Ñ¯¾<Ûfy½©, ˜†|ßÞ™°¿ÁæÒi¼ªJŸ ER(΀աœšYa3lkÐizûÚxøál5J­ ÿ>1Ï^ìpÄ-q÷†ìëË^æ7„²3«ŸãŽŽ­pü\­Þ-Úqȱw¹ì:°/d/ï.ðÛ­¸žÆ\…vë­‚ÛÁûÁ×5èèHÐ~p嵆ô¡Ô.%*ä÷®uNÐ*ðZ¸0òÐŦHrþ-œÞk‘ IJ›£_ãÕD_uí­Gìãé¯0îÞŽzëÚ¹šÿƒ»é{\¹Øäu¸ÛJwš-v(rsÏŽïGùž€;qì âý)tØûÄ°GÁJoŸÅ"~é8äØ;áKù!Iž½ ÝÁg¿½ö8Þ9tUsjÌO¾”å»ã9Žå)Âa)N¼¥[(hCœ¨¦­||æ ‰Ù³·Š× 4~å®à×´ÁÇ?þ¡x¯‘¾À{%sþÞûžÜ­Ò'xÑw€{×7sõúl$ Ô‹vUpM½Åê!q(V œû»kê-V‰Cœz‘'ÏÄC– %(A JP‚” %(A JP‚” %(A JP‚” %(A JPŒ`A‘x&öO¼cyÜÍ{Ê¡g_µò{¶²ä0Q«žXЋå½ýxJ ÿxþ5VH á¡þ(cá^¸_¦h‚Ÿ„ô!UBŠBÁb'ûí“Žù =¸·IQB‰ÁNDì·¯D öõ—PB;L” QÀRP8Ia§]oá÷lÀÂŒ<°8Iê„”`«²:­Ò§¦X ÝÄ°ÚÙŠµD§Pêɽt¥.‰«uìÁZ"7ÉÀĉ™î[Hë…ö½M îý'¸Sî%„áž—^À±hj8›4f ág*™xH1Sn«Nýæ¯a·ðxeÅ]Ì©‚‚æÖÜÈTB4p¿Awvœ¶º³¥ýOyN¼)72YKú„¥CR©ÚËx´¤NÔTqƳ€ë%ýá´7EÑ=ÀB&•0ð¼z1r¿GYŸiûëµN:Ï’~`ÇIÖvNT#nýÂ:˜;ãÙí÷»èÜ·Ð4Ц¥/)×êz1RäÿØ<âÓTð¬Ò!}¨Îð“f@ä,Šêx̉-9ÝÃúÌ+àöÌÑ!¥¯Î´¼@4€ÈšÜÇ™:ÄÙÎá aêAë3fëÓV˜÷þ4Ï Eí8ܪ<ÊÝ÷,É­:(œZÜ ÅfO6­wÂYíø¥RK”ÊöYáóuHA(ìÃÚV†‘f,+8²? œ‚RYŸ2X(jA¡#n÷*óSákqàj‡*(©ðÓϦ}à*iêø5z6inA±.üm”Íð馃…Ò%8a0ràA·ÊGÔK‘ãîÀ&”õé•–|tÎì Ö…Lw¦°öUìA>­\Ú×ÙÁõ†UÚ™1.b,Ìí¿MS¯„‡¬ÁQ¿¡§’K¨ŸœÝ’¿íL¿ ?Ë—I[ßŃ¢Ü_üü,&+.;Ã?D6t«®ðM,^¸çf8íÌŽ{`N÷²¯2ßùŽÐ)*¯øá–¥ƒ:|qŒŒ)/7D93Ÿ¶Qɇ2g9¯#Ü_ÚÑRc𷎯ûZ‹vÒ”ÓbÜX7¸|hïå7 n`›ÌÈÀOÓ¨dóÐÿì´ŽpoÉ‹þ=¿KÌ^󾸗¾êTõÃÃê]â×Ð)èÿÓC†T“.‘fÎÎè·—¼äßmó#Ì™¹‘ûɪÈÿcl\ôûªFÙkuz Íüi±,ùQú\çô„í]}{~#ÄŽàUÄû°L¥/ï(—É|­&³Î‚ÛÓ@Oý"§ÈF™ «Öœw_¡À©²‹A ï–.Û…îÈ-Ùá-f›²í<£’A·“&B¡ŸãÔà WäQ„äzæj¨òÁ’zQÿ³ÿdm[Ð¥ÕsØ5tèçàeèÿ“®Hç¹®;a4:Ü1tÒõb™¯¿¤MC;6( gçñ­”÷^Gëÿœ‹ž€<Ù"kšÞ”VøÑèô«s2ˆJÚz×¹­­îû3";E{‚$Ïæ”k “Iߨ5˜åž`ælpÏ-ôht½¿õ32а ­üŸz)²¾Šxù˜tÐÌ]^®åß´|×ø f”{b™ÃfG¡YBÚø qÔ‹9016Ië=2•êp@šï<çë¨7n‚ŒfÝ™¥¤žPæ°Ò0¦ÐDXÖGëK“¨ù6Ys")ÌÒéÍÎKoþ2#J=‘½ásýôÂádó*p=šW6QûETàÛä³MjKoßý‰%ÃTÝ…$Bæ˜àY²«Þ*á«R’%Õá»å=ë\© k[4=£yoæÄÇ¢§ë’ ±Ý ês´.â‚öÛùÓm+a³½Ú¼Ñ™ÆÝIé ã 3ôË G„ƒ#,øÕ_—½¦ùÈž7D •Šc¶¹¡ß4Êì?QƒÒ$}!{¡˜~JÆ UÌ‹¹ªõ$$Ýëû§ôԿϽ;Ù}‚Èð…nQáˆ0Ïú}!›0¯ìuõBø2¤­‘c²%çÒߊ ÛÂì>1ƒÒ§ú%…"ÂÃn5/ºŸÇiŒ8¡­n5þ•žý:ЗQ±Ÿ”Þ°H7W#– ûRµÎp2ú¨–úô›v½mYð\©qö€¿…Gz"zÃ2ýí„VÕ-Öo$çïùUaåØb®¾å˜ÜáJJE²~ö@o¼á*É\ÀnDóf7 ¤ÕýHKq_~.€s•†H´ÓæZ¬e1¨X§ p×çƒø0ùù„[#Œôkžw5;d§½ÔéÁÙMÐÑÎü'L¾ø°p͹»DCé„þÐø°kc‰ê·& &S$Á³“ÁÃðHÆÙ"›þˆ2Æ)·Éò1ü÷êöeòüƒ4%Üw&u|¾°ë¥ß4”È_¯Ø>Œº$.ñf*ŒY%Á·p s!¦é’d˜Bn›É¸S¦ JÂã£ÃyÃøUzt2ü]è&íÑ }!Lèà±"LìžZ¶,£[yu±¼ñh`)å!ë·eƒú‚í¯m"^z̃2´%˜nVļX ¦ž …¿Wî•HˆœË JÅTPº£ŸH¿9Ì™l7Ê8[þ‹MÂdÎä-24ÁL¿hÁàVäjC|Œ(ÕÆ®-¢"ã:XÑŠ%òõfîF'=1AoRã|ÚµB;nYt>~® Ca„&0)L΋£É ׯ<þo¸ˆ¿çÔ^Ñïe†®æbÈ¡ Æ\ÿÒû’ã‹ †ù*—Ž ·ñ¾ —ŒáàsºF‰¿Wè›UÀ†Ý‰ÏòØX[|ätôRá“¡×ÛõG{ nl‘ëà­§‡ý[‰“ç\rÓOUU^úncfÁ-Tâý(Ÿù¼«ÅêÌk Þ´ãáÄ“>ùå$½özô,á_M¯7 í»1éµ€ʉF\ʃ 6±àë Fã;ö¸Xw2¿ÄÒÓoÜê*rέ,j-9t­ÌW‚ß™1ûn—_Žv‹Üh¦p=è ðà7#ɜו`æÿ6yêèOéÝ……&ºl/pëÞëNZ2Óz\rìb¤Ðyýó¶‹á»Ñnñ"ƒ—!ØZ~,8fóÐ$²ãüÐn¿¸ë‹@èÚMw‰„2Úë4k[Nã/I‹Né'=v*t3ÿ§­î÷à`8£‡Hݘü(z0™_—'f^ºe"ê4ÆŽ‡[ŸµôØuŠVIãƒÑd—ôùŽEºM/`“£v–LñÃúpˆÀSù—Jù`Me¤£Ø7E!ç‚Ïñ¨¯7“¦¹k‰æù™·NoY·VÜWö‘1öÛ^ÕÞÄ¡¤Æc&XÿàÿlBËã#º¢Ž^|Æ$Oc>°5âë¿êôÄc(…úŒ ÌN²Wô¿ †Q¯–'ŒÚàÃæ„Å+NÙÞdMäýÚS9ä6e:fq!ƒþ"KêðžòŠÎ aÖ—™Q° •&%þüø-|áÏuAZýòš“ YoŠ;º$ŽJW›–­“ƒ™aª˜°˜09˜)¶Vo"uªËm³‰ÛMðg2aÑ’îêY!rþu‰eÌbãn—ÞJVðt8vÚ{pcÞÌÝƪt·2£\ñ°ëÁD; ç(Ç•ú©ÄOj+£rk,`¦ÂØßKºUq0œÐ9¦ Öæ•ÛaŒãG~hêֺذH„]ezÑL9K8ž"=xÆBQJ®ÚM5ˆÕ0&5'›‡>ŠíÉ+ðld?@SGVõÏÐb0&Áñ(ï¹möߣ ‹ˆ¯Ík°¢@÷¼nõ-@¢°Üf3Õ A´û{øŒÕ¡•æGAíî¬éxGK_´ÿm”ZUeñIsMÓóä66®Ö~ÕÕ0²Ü“GËàÙÚOŽ)’ Ãàvadc|ÜÁ6 #Êî7â©_K~qRÐÅßø}èqóK+m®õ*‘Í5´\Ž?>©…}L»‚tKcD~Ü ŽG`f7^Ë{}c\!î¼ÉЬ]ŒViéõÕËÐØ‹ç y >±ï7G†à›Áûà¿ÇË Ñxt7„³×k ø-R[\¬ûŒ} xATkþø¥ûLôræÓÛóøÇ$tó÷ßeÍ1¬×pmvùBD(@$Y"ˆƒ?9üPUê‘Áö*2šö7U¸É¦{æè„Ò–<ÎÎó¢‚ëÁ¬‰f±þ+ÅÒ"|Ѿ°·P&Ds¸Ïkãù¿¤ Qz1+Ÿ4þVæúŽöQôuF¸˜ÿ=>΀X3èÏŽµkô„‚ ƒ´ BNëÓÈ+ç­5ZäV3[̼i@|ÊXoH‹W*Èè·"ö²{‰ì È”Žpûø4bÍgB™Ñ}§a¢¦‹gϼ( ¿žç?/Yáë)»¨)cõön!ÂæhÎÀÁò‚¬ò;à¿Ç5&!­ôž€~ØLÚÞjZ¨sÖ³hfÒ’>yŒ—w%Ì<Ž߶ƒÝGˆœ‡ƒ/kÙ‹äåÇÄ QW¸èfE¾w7j[5gâëNjE7Óïdáä="Ü ÅDrJ]*Ê)c-µÆ‹„ïÔpÖ²þ.'•´Aþ§3Ä3\ŒÓuzmŽÖœæ!ßÖx ØÖªÈ[4 ìcЪê$̲æè_Æ#CÛü(PöÖ°×'qSãg‚‘»Þcá :è†wÍ™ã¦Rg^¦½æ¼†´uŸS£ž‚±¾sù°5™GPkniÎT•µ²aä<žLlkÂ:XÙÇ aCàöqt¦+Œcz¥Î]±¬¹‘GØ”Êú¥²çl l¹â”@K8A4QôoÌ<Ü)ä#‡Šy"„™›¶SánÈiÁï¢ê YÖ3p‰N£ãÜÚœÙ[-ÿ{ø3ÉGÇM•N+Œé†)+ÆÃ`¾Ýöü‘ßÚÇ¥w˜oÏñÖ'¡ ‹¾30]a <3MV.,†­ÊNmL~épœJ|´oà»Ø>—G²dÀÔ7?÷¿Xa»{7äüçk§o*C±"ç rÎ~½Ms=ÿ\Ù©Êéï6°²øPÖ75£¦Ëå‰ü#øY{>ž-A<ߧë]Ê}f«áê‘}ÕË$”Å‹»»B~\ô’èé[" "ÓÜ15Õ’M.¥þ3(ðåEL<ÃTŒcÎÃý“Ÿ÷íµM“u<bͯœ’ë!¿>-â z¡ç…Séñþ”[ƒ•ôÎÁàU!'…TØ„¤×"ë ÌÍ7u •RsVT/5Ónù®)wÍí…/„OÖ'»{ .LÅBùÇg¡+ß0kÈD¼¼…z™ ¨Oß¾ å“û'¼k!raµˆ:Û-$ã ¹‹K·ÞíøÈý<³ŽõìGUqz™˜½ÜîÅiìø—Üž2‰Æã h®¥ˆòÅ° æb< WØÛZ ¶ U¿ýIdË‚<—ä–ÛPò‹6ÔR·g-´»ŠøÍc©ÀF¸$èDÏŸžŠ,Q sïÄÒ,PÄùÖ•1«Ùö³—D·$°ñ­¢ùƒž\—·5æ¢#=èï^p6iìæ€%R|Z çç"’Øé›~êRÞ§ÖÙâñ‡ ÿä,)ÕY’‹”£œE;Þþ¾æC>Ùñw¸z8öxÎ[f±Úy"gLiÖzO ’a2ô f¤Þ«U¤«^„y^'š•Ëø,x<É»ÜH¹×¸øàµ1ÞþöÚ”ä z©ûP¥ø±z!â=+¼( g/÷-çÝVà®üÈÙNŠ@sã˜ATCŽëнÊûsŒŒ¹Ùú¥ô(Ï&¯ˆ«¯UP[‡‡†mÐ+.è_+`_;gXr©3^ˆ‹Vu™ª/gÓC1_>‹ìß?õ‹¾uAÑ~ˆ¨E@fz\*Ï Hèµ&¶«q@T.od4ntw'^OaK©*ÞÀºÎήï`öñ³f;Åí˘6çä®b 4ŠGðf ø¶Þ®-˜òN¨·Eà§ÇzekvÇ̼ÖM¥…0©m›b#õ5|'i}Ë+& ‹/óN¸Q–ñžÿ÷íZß5Ìœ õ$ë 4.ÉMYóðR*}4t¡ôÛ‡rv¼|5’/YÛ¢‘IÝåÞã$îŽÛšñ‹Ý¬:à¡©?†Ë/Þœ7)y&E9Ùþ ™¹?Üfeõ«Frcõ9ó}å­Xý6òöøä@ .Ywq})þ×öªÍåTà^~cîN–3Ìÿt~˜ø…˜ÏÚø_ë†2#Ø&MX¦ù ý¥ž c˜È÷!̱ÏMÄñÖ—BÔ;Cu{´ÊÂ86'= ̦ÿ…÷ý:óJþUn].%±o1ÏÌ H‹*]œ8*ÜF&"9`›‰Ï5¼;lóçW`Ó'Ùy\Eâ[¼3FµÈRû‹öæ}s# é7òZŽ¤Xwn@ÚIÙûüçH7æå²=µNîzRÉ=aOºYaûeª1ÿq='Éðé nú«¬èI Ρ\½Üëý‰¡ç¢î.8ÉëMCÐ}]ÌžY 4çQ{‡Ðýt¸\†ÉŽK•Þi~iÝ« ½>÷DÿR¢ŸC݉ åýÔ]þíÞìcÿ`—Eè‹G÷v”ü)+.N©Ç½|Ê[¶HRi…ìj骩­Û4ÜË•ŠÞð¨î-ÅKèl³¶#­ÿb¨j|œÝ±ÿË/×´ áªYq‡½d–Šµ.¶%QÂÿßEÉÖÖóãaÕÏ ®×„Ü¡õxÌ6>Tš!av…ã‰=£è0k»àÑG=cç[etÔÌÓ.=-ì*ïPô["9Á¥Œc Üÿσ^Ú˜•Æû˜lßTª €­›Y– µÍ Æ…×®ôö+ÊÊÐ*”´öDu1étŒHdÎõeÇVCé†@§iŽ¦"fïRÆÀÉ©v›î+#W6nÙÃQbâóJã±r:z,Œdâ²{Õ!u|`¥^ˆÁ;ê¹énþŽ¯Åî<×}yp9ÈÞYÿ®·.•Uí·s#ì(8k za%kÛÜ)›Ç¢àËίEdHmÑž|vzšñÎÕÁ¯”¼¢y½òEáïŽ{·Ã‡q'ò| ¬ ‡¤ëlÝóíTªÛöÄånnÇÌ߉܅½C!Ú¶1òp¥òH-«¼” M6ƒÚCNÉ´#§Œ`®êl0g[º¤ƒ{·ƒíÓ&õÐÔ· ©ð.[·nã&twX‡;ª¨…iÛ†ðߢ²ucð§n›z!„ÃQª~ {ð š`ß5¡U͆ä~wµƒb™Å»ÉÍÐû˜¸¶¢J0~¡Ú6Ú0Cã/„“–l"“rÁ‡¼¹’ÁãQ™>p{…‹½ëÛ­ ]%9…O°Àî,};Lm¦²0TØ2(–À‹ãbÂ’?¾¨ZdÏ×é%ž>ÿ*²fƒ÷9ŸkhÂu­ÙíU&¶¿¿PE|M5ÇK!š¶*ô0˜X‡ _4ü ÃUòË©®¸q.Ä®l¯ÀcO_2Úm{gˆ@S.£Çœ©$xKÖ„„ þ@ýkYUù¥àM[j…Ke è¨-(ß›4ÅÞ‚NªEZs^Þ™åvðÇëùp$7%×Y÷\Fw=óŸIz:`<-â•‚1-ihÄÌ%V+pÓæ—Fž¹­HbpxXb$Ì ý(X5ÁOܨõ‘@ü½fd‚%ÎG³_ÈX¤}¸Ì”D1ê"t–§_§öÀuõèApÊG2G}h-0æT`5ÕÔ*ÚÄ$Õ’°à8Uúæ—e2¡¶ â#2ŒË™lÈâZÔ­\fJ²Ë©ŽÀye¶‚+üŒ2B œˆ H…*Øå“«a„iQYìÒæÛ¸¢Êsf ièQ¬HžŠe»ÆfIp2ýsÕD9þ5à™û²øsg¿D^ƒF|T'ý¤-It}‚½ð™#y¸íuÀbWï× Œã[v(ãqcFf5Qá: Ëè.‡¦VRƒÛÂå ²ÂIr0¨eÅ ¦aÕÔâþ‹žÌÁ 쫪Z¤Ï'ô'Ò= ‹ø §°³vuPjtQá]†9ÿ«w¤á™Ð5ªj_¿iÙˆXQ¢“®ÃðeP«Hz$ LÜ>µ‡cm‰Òe2r¨KM‘Õât£Fó.2«RŒAÔ &_v¼ÎdLÅ‘óþ"QÚï:¶º8ÛÌý˜ÍØ’28©ë<ž$OâÜ.ªEª¯{“³×žŠåy&zb)òcuQ_ph ‚[L…2äZ‚PP–ͪ$>®‰5DxY@¤ZTcC§áSû÷gŒñ1óàb*ànQŸ,†FsËæFãÞÌu´d³=¦“Ë_/»jÓ ùÜq‹3Ôà\±.!:9=U žÕڲͥ¯àÛÚhZ28¶Y¹³‘*vó¡ÍzâBo§ûs{l˜zL×,ÃÎr2΢×ù†Ò\3©p Xƺs+Bì«„ºD²‚­”µÿ5Óö㢠ïÚkc0¡x['é• pv ÷Õ]zhkØÉ°r§~ª Å®Wº™zˆ••ÎÎ*sƒfÀßcÎØë¾Âæ*°‹;2u ½»“d}r\LˆÓ .5ýµ¬„±™0«ßCÝbM8:®Â9Ø8+†gOu øÿ’žŽõe¿Y|DH)«îô ´–L}!ÕË@¼9AöÔüHÄãÓqës8ëäÞ탌Ë.Q(Ü?„sá¤qʨÓH9 qG%¢ŒÙ >#\øto9Ëù—±¬;î{˜´õŽÇÚú2Ü6ý]xÔ‰§ÂLbs3yÃl}:«L%ô _ýØ—.¤Â*Ôÿ][$ßHý^ÂJ±x¼AVn¸£é]:¦)êHëS í”imû}Ó%ÏÌtcòuÜâ¿`âÄ Z6˜̺Ú;#Õ¦vT-bÇ=‰% €KÞŸÕ[u{ó¼æ·• †¶âÈð1ôÀÈBj›KfXÆÏöÌ„`»úºìMÒ*âé÷î/p KðÇÒáTªe~Ö˜_Õ q¨ÞàÞÌX‚4ªM–Kx+Ýõ”ø P¶aÜp°Y5™wå ö,¿êÙsdö^…)Á™®Á¯Jý•ü)ïI¢@Ë´ K$å0ØT•<{É/:Ë[§Ô‹å•aE h(‰Îå ´×\ÀâE5µó»(¢ÕèÒ††ÌJK†ò\}=xßàfë:¬MM—‘•ƒð“¨˜XeÈ#6eŸÿº­— ©à'ªy÷Ñ\*Grùroݲ »0Ð:ËaÙY—p¥—ƒ¥È—„yŸp”~sÿWò‹m¤Ù[DøOÕv#p!X¿<{Í9¬ˆ²¼?¶¼ŸDn^.ƙֵ¹µIʯ—Ú•<©ñ#ÂÔI?×àÿÿ3è­¯eêq ùå+ºáÖÿfzF¼!ÕXWnùÏö8pê·ËM!œÀYšñ¨E–Û;×!g ÂòÿGâ|°ü§Zß ¸²/ Ù&ÚQóQÖš]MÕzŸ×»97Wë®ÀC®´j˜­ÖZ–÷é6I½ ‹M2e{'©ÞEfz¨Ÿ¨‰ü×}ºp%˜-¯f& øQ€ª»ÜÛ/Ùçëc©——¨‘ §ƒˆWÜžD¦2Üö Ý Æ›ú ø3xÆñ£éïÀÌðÁ¢¡ø¦FpWž1Ÿ/šlôU24ž <@bY"ó…íæ“–ÌÔX§2> y^}­Ý¿‘·ÔÚŠ§z8ÂØlM©ÜêVˆ¨«$(ÄÚæÖC ^ ß®¥a{ ý?hTo~bx%e'š­åºßø³ŽzU5x!s÷)ð³£ ûšrï¤hø'ÃS”©ðŽdH¡üÔ—™gùÛJœ²¢ñ*Ï+t¡ã9tB£Xú È·*† #,kåØÿR0Òe™‹¸/0¡›â­Rü$Ï#¯· ã,[#´,’º´ qQ“¢ž²kÔ*d°è‡qƒ!3Ä‘îùº‚ST‘S!3VñVI×Ì”ÕÛòj8$ÏiˆkÎPÃáм¦ü¹[o…Lgý–VòÅ8ŒtL‹G Î=ÀQ%÷ÃŒ`é:‘²zÛ¼&Ž±ÕÖNKäÔb'r<$ùƒà÷ìöŠ ‹ºwñ?¥íü™Z!8C¥±iÓŠŽ ¿ÇV—·.cÇ ™¶%ñ×ÒIÒ«áJqDƒ ï}wmHà0¾‡Ë+8ß/ZØ=Ç)ál*µ†Š-*î å²7{ÊÊ(­Å†x3~FY¦»­,™£5‹ċðUÃù–Ÿé8^è\¸¤zU«›°;y”P}§:²ŠlÑõ…¦û2”fpÝçGÑGºðuUDÏ–^©&Ëb†Tq;Ö-dªØ>ž¬Ñ›SnÏŠ^ åËŽg® ‚[1­&Þ¯"£íâñA\bÁTI@VZù‚©RËjªN(¢Ùv·,õ9† T&Hq•Ï  ÄTà’/¸l®MR1<_hŸ$ÏyVzp„tØ\Ž‘Þµe6¶¢c>ª‰ºÈ$÷¤+>,$÷Aq£I”pÍô±ù.¥^y>^WZòÞA£þSnÅäÜ^c%.¨aÙŒ|?Iä{ò/ï¹ÀŸ‹r`çÈë¾LTá'2iº)VyNEs9ï[ʌ͖嘼òœkÆÿ èû«R+nùs2êß1ŠF;—JZðÇ6šåÍ,ãæh³÷>Y2ú_dLIA¿ñYdlÏÞüœû#²qúƒK¨ÀÔªO¨xâ²îÎl@)ñËAö¶ÿ¬<$?‹ƒ1 >àÕ¹RÇ1L戎(ë7^êŠæW¼¹¿¿|Ãþë¼Õiò›ÌKYáÊ¢'m¹& §yU¿%kG£ð‘ƒ Î…òfVâý)Ê_¦,1cØÙš«Ë[°”!Z™L¿Ï”q}؈z2qªò¿øã·Þs§f&6ƒ¹†×Ð]uW¸},œÒ"¼Íúy¸¦+0Õ&‰+¯~D¾|‚¿l(-xÛ‘02;Ù¸TbÆp) C~’ ëãõƒõåõŽ=`-DnrPˆËåÎÜáMyO‚ªL=è@6²ûE ¤?ɺ¬yÃETÐûà*o)›ë•„k_b)q!€±Näs«2È´šŒ1 x ËÃݨHݪîÐ÷µDü“ ×Ǧ¼÷EpGý.2üØÌETHÀ²ç~² Åí%ü½G&KNw¢5·ÓôÚ¬ù¢ö4vFLÜkFôö]}"ó‹ÙŒl’HYhÂN7Üã¬G®ZKù$¼’)£¼(1%þ O»FËŒæûÀ;˹%»å©Ù åàÄâÔÝ’P•l/ÕҘܞ… §¿ÆqQ_À I›e³ÙŠš)AñiÑoô°™R a³JËeÚÁxy£Ï_ÊHŸ;[G¶j\mµä?WtÒ)ôKÑ[£X!éL4®¨l3Z NqŦ권LÎ:øÕB60Ÿïå;~o< ~nÿ DŪ%’i$=öoœÖÖhêb!)Ç]®ßúÊ˘h½jÿë4YÜj¼¥ävM1¯^áõsΠФQ1Uß07L¤Ü:Ö7Ê%³ ¯àVü¬Õäú­·Ì6ëw$”áԆ̔Ïz0’‚Pô!§ÂTQ±c*ìùSEivÅYåÑe+¶ámäú­·ü³v—@N^LnZõë{à°·œñË%Vð6“U™£òÑm>{Kr°»’¬«$Î@$Ì,é©X\£Gf¸³³Se'"«36Ò‡ø勪'_‘r±¿tHW;(w‚äÚ€ÑÃDõ//WÜW9scÜAð…IL…²É}îâlƒÄ/—XTͤÈRú(¿Éê¸À«Tl’k Sn€Ü°=T1ÿàuh-+ƒ¦{"¹ K³p.ÂäfUâ'§È"Ÿ{áIÝQÌÑ=¬EÕ井ÂðS ݤ‰ä$ú+y¼ Oü_ýZàøÚÁ®gBþrI êq.ýR(öºØåÔ?yWcS´# «·-„+ QS)¹+¥øzäs_{ê˜CؒΧBi)WÅA©ž×íÅ~u¥Æ¦X½í|¹âSß“;ÃÖu.v¢ } Š·§‡¿)“fÇùTè§^F¥ÂÆxmµôiM)tP†‘·#å†Ï‹aòCR<´d×™Vë¡Å«=ûKùàà|*,1lëÝ°P^§°ãð &üÄe:ÄX4D‰ÞzßråÊ/(…Œ@°É-ÕçSa=Õp‰*(Ïž›x¯ÀÞÀ:§¹t•í‡0„«º»(kõÖ&rå×Ê/¯lcÙ~d ‰Šª¸à5Â’²ìù¨n 6ŠkÐl-)ôÓ’Ÿè™~rî¦Ùaró¡ñŽ©µ}úï”oê|åÙFX¥,{Ž­ŸjÁÍP° '](§Büvµu”Ð!¼&›d¤\ö$¾UºAqù¹8)ˆõ;bÂÊ”[§¿pNÇ—ÙÄi®í ™‚_€›È£gìê—ä2ªñÚ¹-8+zs ·Î×ïðåò}zá‹/b³W¹”-Р~§7›D{è-ëˆÑGÆÑÔQÃÎÐ)îJ/Z6B©V'Ä—ëë-3_Ú±´ofý%ÑÜCvòsÁ؈ Þ(óÇI¶è“¿¥†G**ÑˤÈñc"ê]*§¢ v™ERҶʲôÄ.“ eÞ4ËðÅŽ aró¿?¯±…‚ñŒâ!)'XV庄Ì%£L•YÏ%T Œ¥ÆUØO'§jŒž¢±†%”Hª.ï·> 7o(ig¦—œ$žØy^ Ž©—‘©ð„ÞKêÖà š™[°¸š9p’‚˜ûPáÑK‘²Wj&c³äévÞ±ÿ˜ÈÏœç«!; 9Äa20K³3„7j÷#¾ðÁç4¶¢  ásxæ¶Í:Ù Ö>' …Ž»Cî Þ¿Ag+8]®Ÿãlò<È5 £J@‡n’<¥ƒ=Ò?‹+J+GLºiÉù^Œ”$úB·(ÇÚJ†+‰3éÜ=|l°[î¶k¨¾"ŒäšEwëáI"¯ŠíñúÍàá5lY[ã$õ”uÎRz‹ÌÛy¥p3O ®[Å‹âàûl£Ýó8ÿed<¦•@®Y,¥ÊÆ$E‘BDª{^Ýñåhì«Îüw=W€pƒ¡UÉ”(naºÂêÈ›Å)§dFÎÖŽ™È•A¬RÆ!õ\EÊÕbðiQ‘Sq¹ù¢o0)Y\®,0`ÄT7‘…(5ð®0ƒÁå“´óQÖäp ýÓ 9hÆ ÿre¿4¢XÔÆà/Ey‹–œéá&ŸÀäÿm(²(˜Mäs1ž¤°˜gÖ Â|l2-][*:ÜÁ–/oàFí^·À¯¡2B‰ä/àc£j‘ö´°ðOì`þç3‡RXkcCŠ'– O8×c£DŒàA€ÂP)eù“"2RÄžÐS™¥øK>¨„L#ó#ÉFN…Ï«1Ã!÷a}žmf›^é5~FÿÜ‹‚7C\¡à›ò¯î:¹«Â5gÃxn2RÄöƒÜ(í÷ÏmAQ0ÿYmÂ'#§‚ŸzJu¦²ä`;Ç¿`|Cá‡Ê‰Q›wOz³K'šÛÉ,%³&6Âá½ö}¥–Þ ˆ´;|Ù$E%?ºäo€R_ÏÇ7ýÅé§ÿù¶ NlRÆ"âÍ{‘þì!6²/SÌ0ñ{èïÜ®âÛºîÁe±òIœ×dò˜°Ÿd/a‘†úÅB±¶¯JÑÛ±ÌãÝd+Í V\í–_‘òfæ^0˜m‹N4ƒ“WI1ïøž NÖQnêŽ ŽP«ÕA#v†Éæc±†|aO¥ÜhSž~Xn9üuŸ¡BnL¨bâ†i}Ñ¿"Ñ›9ø!_ ³8mÊ–jŠî³žŠTØh½ÚÄÄÈ"(É´æM(M‹IUæ§;ª,‹ÂƒB ¾ žœƒNŸ-×ñ ­Õ#Ñ/·‚E1oYn$£po†È¦`Æ‘5z±¨‰l¨!±0F±Q¤BÄ>zh‘*ýn‚ud2 Ã]X Ù3–©ˆJÓ›ä[p§5ÍÝ(9#dÓÐ(h}µ™}”-*ë˜DEÚh IÅnâÀáãVå¼Ìª¾ ûµ"¨1E?ŒRFyÓòÔí ¤+¥«|häcr†JÑ !Œîˆ £àpo«nóÅeQƒñ-’Ih‚a™^<5ó¶Š=-£_Ù]D¯kƒÑháŒf#GØ­*ë,< gÎÉÔ•¯{\P.ãƒÏ©ì9t¢bÙ]•Ð·SÄ]=â nâ¼wBÔŒpÛ¢†¥Páa#*Œ‰ÝrôSY€g™’¾"ÄyÊÚë[éÊñB VÒZûÃhï«Ìêå²h¶ýÓmWàÊEzñ£,¨«–òþeÕ©p¥Vÿ[1^ì4jò5ئâÓØv³òyQê¡ÿWР«)A!) K~bÆ$•yW µÔÿÝ‹ç7’uÇ°cÕJÞ ŽðcØ°½d˜†~ÍhñH쥲ÈjÁÒ~!è=ÆÀ-uÄ«šZ§˜¹Á"æ WgøN2~AɜĂZÕªÀTýz£…flß@öèÐYÁcÕò¬®­R€‡ïU©ðßëQžÊÐVµ¶¿Ê Yñ1t>GuL¢Gܬù¥-ÂZÒ}Ó2† ¡>àŽòÿ'”Rÿ̦“ezaÚ¨jGyF=à]J6vÒ¦Œ/Øcè P΀v®5:± ßTfZÖø%foíâ7TêeØ`&Ï¿ãýý0ÂåتZ8h+— Rˆ¬&‚¡kgF@**“¶ž(†Gkññ$«|ÔöÑ’Gy ²S%ôå¶Xuo£[)¢eÃR|ˆóªddÇQ¿ÐKêTȯÎ<îcé 4‹ÓÁٵ݆¯Ä'v…Ê9ì°à?Z‚Ÿ=Æß{”˜ÉDÑüáVeÖ½‡´QÛ2~JÁR#`Š¡u>j³ú±¨Íx£ûÏH«`v åðb%—1ÙÏt Ý£X,ûÓÆ>í)çìæ#R͹Òê`DˆjSÓ£˜ ©+°‡BiÝ$“6Ö Õü›ì©ë$zo{¬ä8º·ÄM6ÔT‚Ä™ó¥øN‰T›:qÊ0çþ(mÔIBhR¢×îÒJ…·ßÜéo^.¼ÃÒNþõ§µsîkÕû“/ãóžU¥À½ºÜä¦ZS¯±« 异òQðç•à`’Ö ±É¿DÞ¶ú8Qfôì_GĆ bXÉ¡ˆOèmæ‡Ò”d8ľ‡Ì‰¦2'©Ðócô¯§Ø¤ÐÉž Ã'’3KãDT8†4¼ËµuU%øÒ|† å½ ¨µ¢ÞU2Ê_­¾ cßÎþòës›io£JS¢[ÖccÍ ÌÈ‚6_/åvï´‘Wނȧ’ùø¤o'7_Œ, ýY•Æ)ºŽ«eçÝn¡o_Ø)fåʲžc?6ÖÌ`‡e®p—š3ó^‘Ïr —;U™1Û·†ºÉ¬æBÁ¬¿Ù=eü¥—UsL)V¹² Lö”"p•W†¿Ž°Û s$gÒëM–½ª@¼l žþÖjè(I£¹*Ù/Rµò÷åV`Èkö}K8y­XÙÉð[dwt5lz¤†.ÐK'Ùn•—]{¥@ÍÞɤ[ú>‚ª/ˆB®2g|I‡rª6ÇÎaö˜hM^+U–_Ÿ™Gwqt3 Ö0ëÒxHå$p9j¶ÌE…úxú¼VUÃ[CÎNŽ\ÎÕú\bV;Üb¦õ4y§ûuu¡}\©¥³ÙÌÞ—53ðÕAA=Ó8Nzêl”ŒWDa¨°?<\hçæÙÃ.0¥ŒòòÙÈÕz¿Ü*É%Éc¼yi¦O`#9ÐPoÄö\…–^¶&¢ÿEêw!››ü÷­.Qzî¬ï¼R@! a8Zb/jUj2ãLù-›Ç<„V.Ô—Î|Ç[G¤€„ྫྷ—ÓPqÔ£¬úZc±ÎL Žf¹ r?VUÁKÔ9øÏۈфN•Âõþ IBÌmÒÅÛPc~6ýXãzÊ(oÊgTþa¸öíáLîšXA悼qú€Áweœ™Í&0§Š ð1B«[¾.Ž$±<6.­ðRÅ}+Ív·ðÔ—¦Ô,ßÜÍ®"_Ë,ƒc½Êìµ º¶h-ÔêØùRyG³ŸÃŠÞ%RùnÈ!c·—â¿j#0±8…’,fóòÿá«ÓtøM)Þ'€K‚ÞØ6Ö—-ûeôžÍ¦6Pº‹¬£ÙHF_+ò‡²r£I'fD=âþ$þ= ìW´ÃhT ùû6ú†Kò©A» ½;ã4ðgä8f`=QÜmGr°yssÐùÞz¥„=3«$Ï?)æë—¨áD råøŠK&¡Û¹¸Ã¨ãÜÁæéÝ&(GÕRË»SpœÒ}¦ý¢ApA‹Ì¾UXÅ-Þó &ÍÑt¬S/Èô0ȧ¶ oS`û .ê5‹G´Ä`¡ÇÈ35{°B¶ÉÿIŽXl0½ÌY2ýõÝd§~l_/´b†Å½Vbà@VsjÛ) ±ßdäBŸ¶¹éÄŽ’vd¶éíg= þ-N†=¸ß­"ëCï÷äòhÊî+ìMåtá¬vµN6¨c‰®Ã]gþ\jËÆâ=ŸðшCeÿ èt#d :9Ýš©'‚׆OõrA¦Šø9ª—ÜRìg7‰qÆèÆåF½2Òhœ‹/•7ì9ùõV [oCûF ¹úåÕ›õÖ±POÃhÄ!ËKo•òÇéM2¦µ9ÁŠIëµá¡›.vÜnípj-3—˜õ)`ËBX(½]ÊöÒuÇçãÞc)¯P$Bizç´EYPˆB¼Iò°ÊàV v¿>̃3¨èŸ6"pÕdtŒ7?¸éq!pô€e—Ñí€IçAf•e¬OÄOÖ‚ä;ù:L¼:Ž·¨Çdk~ÊF#ù>”§ãCÿT§Ã¦ÍÎè[QØ€ˆVÀå$¿ëàL0ÔýÜUâ±Æóhâ¾Aó†u`öŸºÑˆÃ“ŽÇ~è(lÆŠUAó-°åQ²&óÝÞÏî( Ûƒò,€˜ù‘eÔÝu1HŽ°}0ÁÀB§R"=~æ+:JO=óú™6$xQ²zµvкeôsVmÏtΠD¼Sjy¶(Q@Á>y º¸„Ε•@ɉ‘Ü eÜVuâ+Vpj¡óGkÿŪÍië^µR[dºXáÿµº¦ˆ endstream endobj 10 0 obj 18736 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000019828 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000752 00000 n 0000000731 00000 n 0000000852 00000 n 0000019803 00000 n 0000019893 00000 n 0000020021 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 20074 %%EOF ast-8.3.0/sun211_figures/frontb.pdf0000664000175000017500000015767113004147321014012 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P011Ó3Q014QÐ2ŠRÂò¸ ¹  €Dêè™)$çré'(¤+èW˜*¸äs!ê1s endstream endobj 4 0 obj 69 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 414 446.4 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 414 447 ] /Resources 7 0 R >> stream xœ+ä T(ä2P011W014QÐ511Ó3¶´P(JUWÈã*ä‰(€T˜éYzf ɹ\ú‰ éÅ ú– .ù\@Tò endstream endobj 8 0 obj 74 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 460 /Height 496 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœì|ÅÛÇ“K¥%9RIBï]¤wR”¢4iJ‘¦R¥+ Hï ‚4©ÒKB/ Ò¤Jï„$üÞßeÿïy\Ùìíµ½d¿æƒw·»3³»3Ï<ÏÌ3ÏÎÆÇÇÇÄܹsK¼]°`App°¥LS+|Dv¹üÒ¥KµjÕ:uê”ì¬ùÒ?üðÃ/^ØRå ¿»4hÐ`×®]vOYÅù$%%uïÞ}Ê”)®.ÈV‰{÷îQGš?¾ð•¢,K–,‡6<¿K—.ì&fÍšuíÚµü122rÓ¦M†'Œ3¦H‘"“&Mb»ž>}zÎœ9çÍ›gx¿fÏž§ÝºuëÂ… åÊ•ãgñBÖ­[·F .¼sçŽÙLS+ö’±ÎÏZá8îîR÷sS‘a•è۷履~jxtÚ´iÔõ_)Ù(ŸX>áçÏŸK)*á…B©x¡Ñ”ÑQÚ¦wjéÓBòi󩲄LoÁH7ã«ùòË/™é«Yºtéøñã Oæ㥅.ñõˆ·bÞ,³Ö-Y²¤ÑЙ?~Æ …ÏUªT‰5:aÍš5‰Âg~àW£x /´TÖ[Ó©ÃLS1âoçÞ½{ì;tèÀŠqçÎaÆEGGŸ8qÂìåFŸõÒ²èÝ»7«¢Q÷jšµá/Û·o DÜ¥K—ªU«Ö¦M›¤¤¤ïHüB¥™3}úô„„Ó£”üZ±bŃ"Y0)^bXÂ~ýú±–V6|ÖºÆ_¾|Yÿ”,=ákTT”PY†2eÊüðÃ"åçù†7núÜ _Ÿv¯^½ø´?.­_¿~§NCÿòs³fÍô×æNÆЈ³ó0aOR濼MæÅçÉ.CʽT¯^Bƪ;e+V¬àg>Û5jP‚¥XNÂ*jx!rÓ¦M-å‹cF†Ò[¼fš¾Í9rð9ðÙòù3µ.]ºè ¯†ªãµk×LÂÝ»w)Þ—/_.|ý믿ø@Ξ=+å-ψøøxÊ·%K–è¡NkúºÙ/èu]~0yöì™á üjt/1Ô–ðóó3Õ‘ 3Mň»ôíÛ—MÒð—U«V±ß7¼ÜÒg#íhĈ†ƒBH©&,Xа¯dUiݺõéÓ§S¼#ñ ytݺu†GË•+§¯üÀ¯üQ“ÊŸ?¿a ù”âââ s¤Ta6|J–ž E¿nݺUÿË… ¨ª‰”ŸçÞ¸és3}MT‡¨8 Ÿ©_;wNˆm2GßÊnݺ¥g‡ùæÉ“Ç°£¤Íèééi8.'~/FF«øR^ñë²eËô'P³©J)jíÚµgÍše˜²á…FGùâ˜ÑÎ; ïÔôÞÍ~~üø1¿ꢴ ó2}5F JfDDÄÉ“')p(~MõC)ˆÈØ=z°ó•r²þwÛO~(- |‰ßcùòåM?,].Ò×#Yy(Z´¨xÖ†¿Ðü¤‘%’µ%Ä/4=ºpáÂ&MšŸù_ ²¥SO3,¡éüi­Zµþøã£-= 4koÜTq2ºÜìkÒŸF½:_¾|ì¨1ÎtX ¼~ýºá/Tæm¹ñ£‚øI\ÞïÅ‹-](~Ôl.–Þ&­!ñ“M_iCX´hûñ *ÀVaé±L:µP¡BF*AÆŒ_½zet&+†¾ûã{1UtÙOž`¨‡ð¥4C† ¦F¨a¦©ñJkÖj°t¹¸Œåk5RB¬²È¤#~¡éQ¶eC#ˆ_ V-árS­'˜V9qëRúÉR.g)ˆ_hzÔÐåýò«áQžlØ"Ì>.^e8‘az¦U­Ò´„)^žâkÒÃöþùçŸ7nÜXÊÉ"…ùQúK”q§e,U5‘fÓ£Ž“±¦¯Æ´!lØ°![¶l¥K—þöÛo-•Ù^nØÑß¿ßT\¼xqTT”ÙÎô£>2ÍoÕª•Þm oß¾?þø£Ñ _|ñÅwß}'|æ~5:—ðBKe¦­g*– 3MňWÚvíÚ1Âð—ØØØï¿ÿÞìåFŸgÎœixáôéÓæÅ›XÎœ9÷íÛ§ÿš˜˜È×j8®h ñ M6iÒdÀ€Â×þýûó«áàùäÃ4'L˜@±ixÂÚµk£££M•U¹sçò 6½þù‡Z4 |ݾ}{ M³[·n±,ªa™ù£þafÍpvøádžÙèÑ£ §M3MňWÚ+W®äÎ{ðàÁwïÞewÉN‡ÏÖЯCDÆê/¼wïÞ˜1c"##f¬²gÏ~èÐ!K…¡Á*'8™Ü¼y³Y³f4+¤¬¿Pü¨à!Àï&žÆ“y‰øãbu¢BQÆZ§J²[¥i yÔðÆù0i¬ú_¾&ýÓÖ¯¹«T©¥Gò4w=Þ{ï=ýµ%K–dU—èW åGé/1Å;•-cYEõ•/…¯†/H?ökz”ÉŽ ³Â4¨p”HöÛ5Ôi‹)¢Ÿ€Ûµkˆ©MdÄ… BBB„I:¡Š n0;vì`–,yýúµààÁ"=~üxõêÕ¼A#}²C‡­[·æí?yòdݺu•+W8p á üJÕT¨„<'ά1YÞuýúõõ¿$$$*ThÈ!|–2M­øúúšš:°£éÔ©SúôéÓ¥K÷Á^:zØy™ýÌD„ y ™¶mÛ²Û2Êú—_~¡%e˜—a HVÆÇKw”¦cž–¿Pü(¿ Ž¦É ±y²¥û5„-´W¯^ÔÌõOÉÒ“1›ˆø:6 ¹º %4ûšˆÑÓ¦âÊ_„1[á]°‘ê²iðw¶;³÷•â½[{/âïÂèNSL\„˜˜Á±–/…¯ÆhrÍ訑œÜ³gѵ¶¼M‘WC[ãóÏ?7<ù›dR¼; XÁ¿Ú´ŠæÍ›W¼E#¹GŠÄúÀþzÆŒF@_ŸýüüªU«6nÜ8#õ†_õÍÄô ³Š6jÔhРA†—œ={–·/’©ŠUHÔ7T\Οþiè ž6Q««ŠÛ¡VZw–¦‘"”Q««ŠÛ¡VZwáîÝ»®.‚ëQ««ŠÛ!}ÜLEÅå¨ÕUEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEœ˜ÁÇÿû3ülôU«uuqUTTT\ %aŠÒRÿ90±±RSöõM9AýWU «¨¨¸/‚þ©dán^üúùé ¯¢¢¢¢ôbJøÀ­Ò?‹Í ·£Ñ¨£***ÎF0öÓÔ@(•^#u7Õß²ŠŠŠÓ0AUÅ ÞûUˆŠŠŠµ*«ª Çh®M}\***fѦª‚ E.¦ŠŠJZ†²T?Ò¨ÊU»£)¨¨¤MôC¬ oøZh=Þ0Ä-þñLW6ôg æ***òÐËU×Ú°1ˆ B¡xôí’3á¥1sgz)5\“QQI=èg¯œÜœMe©ðˆÀX¸Òw–¹³ ‘½ú¥ª°UQq/Øfzç4^S‰êrYj-¦²×™R××Wש«ÌTT~«£E«ÑH©ÛIT)˜J]Gú «ÌTa«¢¢4ôñ©·ˆÕH¨*ŽÉŽú:TËÕ/éU…­ŠŠk†[ÙWÇÞ€‘QâÔá¯êÞ·pË8q¹š6…ªFZ®ƒž…­ŸŸ:`«¢âlþ[>ïóRødèƒ>·q[Fj¼j 2!)OxªrÕZô*®ƒô[avL£QÕZ‡8/Ÿ$¶5OíƒÒ(=îã¾]RÖ«¬ÔÍÖ`^äúÀ§$J~†Ï–aÙ=ܳK^©ê·!)‹²_à >Iû>4ý‚ªÖª¨Ø‹gx¶Û;ÄÌóz¢óÂÒ>ù?_ÇuÛS6t°¤²Æ#~7vøh@ñ[•Gbä!z׶ µÂW¶;ù j¡VŠ¡Xwt_‚%¦£1²ÔZ5Ú­ŠŠíPeõôyåøüûØýl¼¶'h¨²Zå €„MØÔý)4¢Õ}Žâ¨íåIݼ«8ÀNªñÉW@Z—qÙ.‰«j­ŠŠl¦Äó z( Ø%A½hµË(ë?øg†åFnþ}‰/á˜íi¦zØIý?>ÆÇ!)òã1Þ^ÂVX¨«JZ)P¨êf²ü^LµƒàÒ8hë8ŽÅÐlÈVeb¡]4íTÏK¼4¶“0IÞd¥jHq2i_ÙKqÕ‹Vç¬HDâl¨‡z_à‹ó8ïèS‚°mÖ|YïãýÍØœ„$Û“UÕZC.à‚ŸöuWJWåá+¼Zƒ5l­ÁvÉÂ+¿”±acáó à¦<ÄÃɘüÞʉœ£1ú®Ùž¦0/¦JZ•´L€6Qpsõ×ÆÛh-R }†Ï"AÛs*¦Æ!Î^…”Á3<›‚)9£*¬Æj»èfi„ƒ8صÐ6EÓMØdû£SuZ•´É¿øWã“HÝu Æ<ÁÙéP2Sí)‚"¹‘{†Á;ÒF¨T/Á’â(^`A"]]"·Ub:¦—DɼÈ; “¨åÚ˜ *iUÒwq—Z« »>Â#ÙéÇñèˆÀ®èº{ë°Ê‚mÁ–š¨™ùçaž*i­b7v·B«ÌÈÜ=Nã´©éCת¨¤J¨×yùêViùiŸÝÁÙéЄ¬ÚaŽávtkw4[±õ¼CÅl>æ«£Vq7G`DVd­‹º±ÑÆÔÔqZ•T‰à3à£}rçä¥ð/faMï"(2sŸã¹}Kè¶c{5Tã]¬ÁÅêÞÊ„}4»'¾ý²(»ëm|zªN«’jø-æ¦Oà3öá2,“—Åé$LŠFtC4܌ͩ@4­ÆêB(TUÎ⬫ËâfÐø ¿±“zoÛÞOQÒªáUÜV]ÝZ-MRûØ9OñTF ¼ê;|…¨fhö7þ¶{ ]ÈK¼œ‚)áï…^®õ‚pG(ZWaUi”.”´¶Œ½áUI«âvè–k>Ì[WÞå÷po8†SµFëT&] ¹ƒ;=Ñ3 a“1™R×ÕÅq?ÖaÚb(¶lIG´ê ­Š[ [ kÃr-ꮃ1832·Gûð}˦L؉TCµ"(r]]÷CÐi £p%TÚ‰¶$¥¨(] —ÀG²¥k"gaV¢>ÆÇöŠâ.PPüŠ_³ ËçøÜM§ó\ +Ï|ÌÏ…\õQÿNÈNGˆå¥JZ¢[ ôPv }Tä¨ÎÆaû̸ûâÂ(x\]·ä%^NÆäDØØMSÒj4êЊR úêá÷B¶úºûk FQµqH-Õ°+#Ù½ãï겸%ñx… d†É›lP‡T\ÎĘ#Ô]=ÉS_©¶uFçìÈ>sÕP†ÜÅÝvh—ùSß–âN㮵FëhD/ÀÙ.^ÂЪЪ8Ÿ$¤Ó>§t+g/JTÁ¦û_¨1W-±«£Õm_°ŸfÙ‡}eP¦<ÊÛ2üâë«. Sq*¿Æ\óôKðÑ>ùÿʸ|ö¼…·j¢¦º}@ŠÄ!®+ºfC¶-Øâ겸+Tbç`NdaoeË"nuè@Å PÿL¯}áéŸÐ;v¹ û‹5¼:Ð|[‚%Ž(^je-ÖR¡ý _½Â+W—Å]y€½Ð+á³1[öšÁV]«â Å\ñ |â­},/æÀr,§.Ñ}ã±ÝË–êa÷T µ*£òE\”~ÕS<ÝŠ­μоŽfFü¦ô@ ܈¶Ì¹ãoÞl”±Å¿‹ ­:n b_ôêkßØ•2.§|hˆ†P -ûeÙµ¯¯ñu ‰ò³*  MØdiÜ›¿oö¡ZU,¥“šD1ãLÌ E(‹lÏ uÜ@ÅŽ\Áê®òÔ××xMÓŒêë(ŒR]ëåq ×(!Ça\[´}oG"Ò ^>ðñƒ_ŠòÓŽŠbø ²C1~mõ ±}¨»ˆß[¸õ>Þ/ˆ‚²×Ö©.*vaxÌ6ª¯é´Ïe aѪ­åPîŽ8¢l©•{¸·ë(ͨü³{¢âÊÇؽçb.Ÿêiœn„F°ìþ\RBV†‡xx —ŽâèNì\€C0„"«(Šf@†B(Ôí&còPxǺ «ØgÄHÙÁ"|}u#´ªB«"ƒx¡ñIô z<7VÎ.ÔjÂ>ãUÇW)Prά–h™¹ƒô.ÞŒÁ˱œrÌìù4Æb,%0¥„“‹*…ïÌùŸ”@‰ŒÈXû£ÿ¬±eNßq°T Ѐ‚ìÈƪB«"ƒ¥GÎQºújŸÊ˜Ÿº‹»MÑ´0 §‘ˆ.²y„G+°¢:åB.jSmÑ– !uTé&C br"'Õ0ÅvdOñt;¶Â¨:¨Ã¾£ tDÇy˜'[ 9v ´h)ÈNAS‘ΘMš¨b×ɸv#6fEVZŽ 7]õÏÃ8<£+£rê¢î$L:²"ÝÇýr(WµmÙzÒ9°ï8†cÓ0íC|H œõ¤+ºRWHÉOáTQ¥zp÷ä¥@1«Ž¨ˆ“€?í3Màã[­V3âß=iêîÆnG”ͭქ±LÙŽðB(Ô}7a“½Â°;£°*‚"pÁ. :ö)ãïïðÝ;x'#2ÒZÿ¿Ø²‡¦]àé…^þԽ奠Ž¨ˆ°áÈ-¯ ÇžIT¬½–úI>ä뀪ï«!4á×a]´ FpT™Žé–ÆWmg<ÆS€»ãr°‡xHK1ˆÀh±+]뜰"ù-¾•½TÁ×W³*ÆLŒ9âu³[ìbFë\Ì CØb,vDÁÜ”}Ø×½#Q&cò5\sB¦´Áç`Žòrqˆ›‰™5PƒÂö|° Ë\yìnUB¥:¨s7䥠Ž¨è¡PM§}® |<~«ÕÑ^àu×Â(|§Q6·ãîLÀ>jõÃ0Ìù³~p!7rwC7Å΂IáîÍÆìwñnfdn‹¶›°Éù·Ã`@¢d‡>‹E@€} ¥â~<Â#o¢·öñu\·öÚ38S%ÙÜÅíÜq°ŸÚŽíïã}A&ìÂ.æ>îÓz© Z×MÜœ„IeQVØ!Âù;»mÆff=Så].ì0®Ž¤Y.⢧Ï+?í3Ø4KC:SQ07âŒÅXj­ÅPlf)d8: I=ѳ ZÜ@ɜùAhšð‹°( ²“¢ B¥%áúÝÂ-ýù—p‰ºDk´–í*£ϦMhi´Ók_ȸvFІJã«·ŽâhWtövTæÖ0£1šB‰æ†« b7^áÕ ¬¨‰šˆŒÁ2zšY‘•RÚÒ ·q› sBò6Þf.‡q8ñããÒ(-{ÿ*´j´®4ÅZ¬õÔ>ȨµZ}¥þÐ l©l©JÔ†hHñ5#i̺º8b,ÆâHD¦>oºS8Õ=(› ‰ô½hy&¯Ø˜â™‰H¤°Ý‡}TžiäAž1CÕ‚/}/öÊ+³ºH!í Û¿À÷U€ÖêI„ë¸^UY«Óì>Sl¤ïàlÈ6S_@Ž à|VcµDÁâv<óé˜NH…“ªiŠÁu©Ê*§\퀴Yê û/øEVyU1›úy×þÚxoíc±DþÄŸìÄÙ­ËvtkØÊj¡V!b[–?ÄUPñ¶E2(ÖêõXÏÞ?'rŠ÷}üÏâ÷5¾f‡•>Á'ò–橳`©vú¾Ú§ßDqðv`«ÖoøÍS8”®ïâ]Z‹ °À}ûv‘Yå[|ëê‚8ýØß ¢5L+y bh{.ÏñœÑ¾4gŽBÎfvDÝX<õ±.æ‘Wà?í3›•LôDìÁGLÉìÆî¨!H×T°ÉË\ Y=CeÇFp áÐ{xÊDL4Ôi`ÇM~ïáJÚöh/Ãïê¸Aêbå‘Kžéâ»ÅZ½‹jÛ ɇ|im‰Á5\k‡vY‘u!¦éªç>î—B)Ùv®A½½QÕ¤† 8zÙ8P` +FWt¥0×B;ƒdD¶6SØâ~«ŸUÞ`JÌ1¯¨›2‚hÑ&jŽæl’²Ã¹#l8ßá»`ŽÏSåÚŠ‡xXÕ?ÆÇn½L"û±¿.êæ@Žù˜ow+0ƒs!W34‹F´ŒïØXDE©KnݘyGŽz¦·õOk/d§L3¹%Z¦J9c‰ØXEÙ*Ï⬫Ëâ@â_ ÕørÝÅ5ÂFvc7ï—2öüáˆô§`Jä¡€-Òl5ÖF?;r^^ª6ë–Œ‰Ù­‰º1#Öêý7ãWå» ‹ûNñXËMÜlŠ¦TH–c¹«Ëâ žá¥A=ÔK#bÉc¹‘›:¼#ÖÎ̬HDÆáðC(B'a’UmGÐfU1ë^Œ9²‰¬Œ0/·p«8Š÷AŸT?d'@“y"&†!l8†§©¸âÔf¡QÚ³؆m?âGÊÀOñé]ܵoú«°*áqðÎUEÕʨlÕ^ÔfU1ëFŒŠÙI v^¬Õïe\·|C0Ä¥R Çp¬ŠÕEÝ´6©'€ŠYÞ~Z³±ˆ|·h¦uG÷DÌÁû*B™}ØG%v ¦PäÎÄLé— bV›U>Þ¾¯5Aælý×Ú ¯àJNäƒ1(”â Tˆ!ù ?¥Ý,iJÌN{Á‘Š¨HmÓ¾cï{°‡¢Up£[å a„qÔ±Yå“^ûB£}xVÁ^Çõ<Èó=¾wD©”ÆQ-ŒÂïãý«¸ê겸ž´#f\ ¨mRϤB;Cí8·»[Ã&ø“¿Â«‘‰Héãüêج’ñòI¢€•aöÞÄÍ(ð ¾qD©›ÕWø*¡¿âWW—EAPÌ6FcŠY·[&lˆ±)~ ×ê¡^ä ¥o¯ŒVc5µÙýØ/|=ˆƒ¹‘»;ºKìÅÔ±Ye’A›@+#ÁÜ¡R7ÃQ*EÁ‡S Õj£¶ã6Õr_1ÛÍS±˜ÕÉšB=3ÑÑùØ%¯µXKmV¿ÆC<ä³}oKœSŬÒìyœ·öÂ8ÄGñèˆR)ŠŸñ3ëüXŒMË£¯âPÌÖB­h‘Š‘ÈJŠÁöhŸÙ7`ƒ]òZ‚%Ùí_ü«ÿe ¦Ð†Zƒ5R.W§À”Ã×GþðôOžâ)žV@…¾èëˆR)Þft¡®®ÌHÚŠ‚Ϫ&j~†Ï\]GáqM•ú'cOô´‹#ßdL·|†;fÆaŠñ‘)¥#S§À”À˜˜ÝžQ×gÆž´öÂD$Òjþ§b¥…œÄÉB(DÝLF´±´ Åì[x+µŽ±&LÇtñs(„[¢e‘V˯ð“2Ü[í6nWA•¦h*%Ä:æZ¦Ùç™>~ÚV«7¡€¥tå[NÝ‹ÖwaM³y˜çꂸù‘?UnÖF5µ*I9“Õ†•ç;|g{ùŸWEUÃ=È^âewt§ì5I°„:6ë*&ÇÕDݘkõJ.*®Ñ¹2*§n_ñŸ6C2Ú…K¸D“Ydß+7…u>A}ö.àBuT§x”îàj¶¸VhEÝØh>q6fG#ZÊ–:6ë|æ9./Ø ’w<,…R®Ý:))ióf»¹ÊÁvÔ]K£´µÑ9T 9…SYe–¹º v¦úQ;•xr’Æ`L¢¶b«-™R‰­‚*]ÐÅè÷ØŽð•X™b êج3Yzä5ر±rön[ŒÅ¬0®õ½OHHhݺu“&M‘øu\/‡rïá½4»é˜¡ŠE1›Ê¶\ügEV«ÂÇ"–­f†Ø2n „õ6ÝŠâ(Ž²ìcÛ##oLïf*;¨lŸ•}b¯Ømç&ò¾+‰’©&`û#<ʌ̷q[Ƶ+°‚Æ {Ù¹ÏÀŒ(a:!øhÐRtÍUŬ#`*ì*+Ã5‰uQ·+º:¢`HÞ•ÆÈÞçgÚb×qÝ9ηc16+²®¹¹fÔºQ5‡×ÌÒ0‹W/M¸&²qäû“ßßp~Cêöv¬?µQ;ÕŒrwDGÙ!æþÂ_y§7zË’ê†nõPÏ´ZR ‚]UÙ ˆ§àë y™«˜‡ê+•XyÞV_âË*¨b÷uè×pí³˜Ï¼½õr•vóýÁb`!2 Ô°çÚžO}’·]^¯p/ïÞ…ú²cÈíWrT$7ÊØháê‚؇?ñg.ä’-$ïã~ Ô¨úqˆ“q9ã»x׬§àí…^eP&EÏŸÕÍÀn Ù¢ x"ÏÛj!æ@Ž;¸c¯ÂœÇùOc>õ ô¢\õ òý6ö[W¹±6À€²(Ë /rZRRÒšCkh¤-£õ õŒnÝ{]ï/RÏè¢Óà‹.‰’NqrQÑ–¾ØétB§‚((#N’¥tNä´4õÖýY±Å[–ºÌ^Ì9ë™>~Qìeס`Ó´±½Ïñ|hÌPAk¥h;Þùš ýf(`W`E?ô³jÏå³×Ïv˜Ú!¤ZˆgfϨ6Q½×ö¾ýBÕl­€ÆK8Âùä]];ð+~mŒÆ6&2“#±ûd\K]: Q–"qI³êÚÛYóÐ3]ü˜X938ð€åoøMƵ÷ïßOLüŸH;Š£Âä¾w÷¨ØQ.‰}wèd·_‚n] ° ®LÍ6o÷¼ÓNWÇl%‹ØP„ʈ¯4@§?(›Ø˜Y¬u˜‡y%PÂR›¢™–â Ŭ¯¯ŒœUtÐñ|Ú.v¶Œk)1š I/ô’qíõë×#""Nœ:‘Q›Qï eaµƒ(djeø©«§näWÀϯ_Ãïþs˸Å:tèÖ-›–R¦>¨ÇæFn»o;è|FbdGt´=“8Iõþü ãÚÏð™Hì;ŠÙR(%+Lu3¿6ÞGûDÞ°üDL,Ò†a($òäÉ“ReJù¤óÑ)®Zï…X¨ Í?Âd!" ÕEÕýeÔ­‘´iUùô=ÓóvÉëì™ë£\ Ž,à/ÏŸ?ÇóB($â¸Þý*£²¸GUYUÌZ‹v[|6Çq0 aqÑÚ ™—oòd–ÖWiÑV;ÓÞü%/ôÿŸoë¢ý÷U º¨÷¿ $çr>î|ƒïxg÷ÎX>cHÖFÝ¿/ç¤zh(5Gsy†’¢hö£0Ê.I]Çõ·ðÖ0 ³ö¿ñw0‚-ZðQ·A›Æh,¾’×Ãbôq3L‰9æðX^øÊGx” ¹¤D™0ä®ýoÐ5½÷ßOÿ–‘¯£yÆ!´bÝU¨7uM>çh²4N!f蛼xõ¢ã¤Žéò§ó+ì×eA—' VL«¥žàIQý?»º 6ÁV{ù ®}ÐÇZósFT@K“´%ë¢n't™5GP:ÿ% >%¯DA Z£uô~>maµ”¿ÖŸ±¼LÍK]{3½’i—;,øoøp %þ.\T—•ï÷Û¿×ÖÔzeój5½Õ£ç)¸…§A.àBdYõ®.ˆMÔD͹˜k¯Ô¨äдÿZ5“«¢ªÈò±§xZec°H"±±êü—$<eŠ­+ïZ*ÅPLâ6|­ýcúk5¾Z_Ãí0û›äßÇAÿJOíþÉ»–õœïè$$í;3>f¼W —w÷lY~ Nfðþ›¿°õHПPóÿ?Ç$u3¶V-þsqxãp¯¬^ævHH´z21³‹Ùöå­xR”®”±öÚ*Q ‰Ð~Š«b ùß×Fm‘q†S8ŠPq?1ŠYu™­%b#{àšJi)”š)žù{Ìï>>š ͸Øq23s:ý€Ñoþbôœâ°déŠäQYSb{MÌÛ?O[CëWÌoð¦ÁªK­žèQõÝ÷Ìü*¨bß4ù4>ćLVzJ× ¨`cÖØ™™ã°È9!!êÀ¬tÖçe&­Lg¾—¨!~NÒiÓyy¶mï^ÍÔÐíÄô¦2smáÐ=ÛÆ Lºz¨aÿ :A«N¯²kÂî ⊨8#]]™°üÙÍîÑÈ©ù´C»:¨#}Ðà ÎÐ5¿a ‡,Èb Q:0k[ìYœe×fiQžÀ‚# 4­í [œÏd;±i“õUþZ¯¾šÊXêëVG M‰¯^´œÒR¦)ЩÀé;§í¼ûq×Ùð7b£« "“‰˜øÞ³{²‰Hl†f-ÑRú 31³6j‹c0¦ ‰ŒÏ¨³FØ2 ËwQUÇÁ¢áO¤SL'¯(¯Ñ±£-£@æ`Î ©™±É±ú9/}… ySö¾NöÝ’³1Îß?_¼gqJÚ¦}ô2Q‹5\ÈìGø)œ’~É-Ü€ÁCçà™òÏìÞ6nbh–'xBEÅ“w´«£z't’èÐÅ]¦ûƒÓ]hºŠx/¨bVà +ûò˜Q ¥,=ê¥1K½½½ƒ¼Wlu§8‹°( Q"s¬"Ä&ûqéÅì”d7‡²êøª€ªKd\t(µmäj-c1¶ êG¢ãñ,¡"ç³23#2öAéá²yæ@ äUfSc. Ñp0_…ïþ¦ÛÚ ðr('=†óqE¨øca“¯…ZâË@T1+àøH¶7, ´„XZ­^›^¤ù<ös÷šŒÂ…íÇ~Ù)Ä&èõ['lO›ø:±Ý‚všMù~åï=¹çø Ê#<¢Î–9¡šé¡Ñ/øEžÐ³æ²K›£9ó•¡÷ÞÄÍ@:ÈKœv=ŬôU`ìzÚ£}ŠiæE^ñe ª§ö‡|“M-Óßãï«õõÖzŸÁJ焸šòÂ…¹œ3qg²}”Í7—ï¤]“\]g@EkV|‰/+¡R|á›é Ad‘¾¿¶Cô^–- aÅP¬êñëJ¬¼ùŸßß|ŠO)“TŠÄüÈ/1t {«HDî1^ÝhÌiœG¸ÈÊ÷4Ê “ö•ìaX²«s#·©gȪ#«¼½ü´~îå<€ä‘(¶P³½†1tóPïìÞ%ú”xðâ—{÷®ÛªJDâ>웈‰-Ñ2²ÑÜ m> £¶aÛÔÉ[ Å^û­|Žç¥Pêü"~ÚÜ¡F-eü–&!Õ•~º(JæIõ³Â(l_ò~*‡rÂgO­§gç°­ÃìS8WÀ.£JÌÄLWÄI¼~ýºùÍ5áš/V~áª2\ÄůðUd¡ªFIâ/Ž»¸›9l©ö.¡"*ÎÁÃ_ãñ8ŒËŽìÕPm%VÚåÑ]Ávs)šƒ0¨5ZKIð:®‡!L$TcêVe=4I¶Œ°W¥M'(±:«õ´_Ñ\Ã7ø&Õ˜òëÁ_}rù”PúÙ+9sIòàCÞ‚-õQŸÊU2‘Q;GƒJ÷˜ÝŠ­TeM)ƒ…XXås"çtL—7!hÈ:¬cRâ>qˆ£¹GuZJ‚뱞Oû̯7LÅ«l ü"À^•}+R‹€e…aµ9ó®.ˆ ¸òàJhРZAâ.ë¨}MôüÈ_…çb®ôp¦ö¥z½‹wÝ«?esYr¸{ A4¢)rmœ ŽáÚâ3k#0âC|(1Ánèö>°t4UŽØ[  4¸Öǯ÷mîëdFÀ&Â"Ñ áˆ ½#Ò ‰ åú—óÍï»þŒ£öú…[ƒ1˜Y4Ù…]®•o”íoã퉘èÂ2X -î’()þÜàÅ#O³ÅKÍá}¼ÿ>9çIôªEò~7ìUc±¥R߈5XÙáaf`FÅøŠÞ5¼}Ûú>{flž¼Ö¹|ãS[2p.S1µÊ¥‚%]6Òñ玚ÍÈ­vŽnM«¼;º#¸zˆ|v&'q2!îµùW”Y…"±S¯ÅZÖgž¬Ÿ¶–'x’y~ů"çŒÁ˜vh'1ÁC8D™li«¾T¦ÊN‰9æágSè*±ÙžeózÇË·½ob¢±\z¼Cku¸È´ž8Ä…#üo(q“qç39v²W¤WÛ¹mí’Úyœg3¤(‚! \473E6¹V ”™EQT¢ì ¬È‰œõPOÞØŸø3¡">Oñ4ÒWÛÂ(‘pßMêÙ’ÆÆe³dÒóIž5=}Ûø&%™öé¼mnklÅB›èSwRºNÌÅŸÜ>e¿,û2Iþz[ê-MÑ”ª µÅî`Èö^ÕS @­(*¢¢Èú)#âÏ矙¿ÀO¬o”?à‡Â(,²7Í „ASc×På-me‹€k ¨Dltˆ%wÞñ,íéÓÖÇTƒ%ó“÷±ô•{ЭXNøe¡ÐuSì¦)¨b¹–nÿP) òƒÈÇ/¬µz§›¡Y4¢§`ŠŒvíd.ã2+€øÖHŠB°ê’+¸Òm¢µ ˬº}P#4¢|¶tmÿ,È"}â’5Ï·4b:vWôð€žÞ­¼)cÍ X$ËÕ¼º=uA‹ëæu¿ÄëV£ `[2vÂÎ8St»¨÷<.{óìAU‚®=2ß"Ì\‚8áÿß»Êa@Ô¬(µÜeé7+m!’±ô 1TJ¢áÜ‘~ÕöA";£}ˆ­r)ÿßÒÀ1{(¨²Tbm ÁýìÙ3O­§‡Öc퓵"§Q!Èš¼ykË7¿œ¼€¢X„E%PBê²DbRbñÞÅÓOwàºÅ¨Ë”¨c1–Òµz)vdÀ”ZµQ[ú¦.gfÉÛQñ^ ÅPj’+±RúUë±^DùÜýÅPLzj/ñ²ŠXr{pëÉ/#Ä’t£Òy7ð.ˆ‚)βÃÌfÀŠrÐxŽçÙ-ÅÐî*µÇÔöÎá½ò¨ùVÉÊ°K³"+•÷š£7ä*®† Ä]"­±G EèIœ”wùAÌü-ÑRz ¯¾èûÞ±ÔðßÂ[;±Sz(…Øô,íøãïï®#6Nu¥Ÿž^“GSÿz}SËúHò–¬AonÀjÊU>=ÙÙ;€ïð]34su)܃îó»kÂ4SbŒ_ý!ªŠª´@SAWµ  €bãx1ãßÇû²/†g´8¢½’v/M@B%Tš¬Û÷Þ 30ÃÚÂtB'Kþ·n:b`ãn³ãVŒóŒðÜqf‡Z£Þ‡r5*y[@ag@Kjþ3à@9Û!ÜÇ}jî«w9ŸqÛÇi"4ý–ÿ/¾Çœ&¶¦cºÈ¼³{Á;êþ®.…$ØÐv°´?©DþÀ¹‘»:H‰ó|WÂö'þ4=D™@É`UÈt6ÀDP£6{ÔUY[”Ø™fjB4óþšÇêgÚõèVRÿ‡éh@.]{DIÝظ‚Æ=û OOôtu)Dÿß97‡ås[ìåÕeA—ÁjƹÑÄ–îàN$"-5|¥1S[ …‰<ÅÓŽè˜y¤X"³0«J˜1芮R¶¡1d>æ35³Ë~ÝN•õöy-Û_ëÆšlš¡Ë† C@¦ŠŸ‡èW$k¶™tÖ„‚ü¼/àïEõ×2â$%ÙD„Ùf{x„ w¯€*ÒY‰•ÅPÌ-4sÚûT,íNg–Q«œ‚)âS-<úÞ3ëàzG è:j+`j•Pi.æš=ê^¼mñ×òiè“î›tHŽSuÍ$.úU™Ð8ú߸ºÊâ/ ›.N©EØ¢©ü³%~sùŸ¼>õÆÔs^áœKS4Ñ®.…$`€½–Ï\Á•·ñ6E¨xä®ë¸Î:`¶‡-…RÖËÂ!–&¿Ü%ˆìEÏŸ?÷ÌìÉ?!AY”5Ò¨ë2|*‰»XÚ‘\ÆeVåûÆ;“3@$ÄÜÓ—cyähö®m»¯îö-ìûÁ7#)¹5×pfŽÄh'®å&nj¡½…[vIí9ž‚OŠ£¸øÚÛq×MŸ€ ƒÊÒíZ˜¨q?.Ÿ—ò”ØÁ3{×ð>ŸÀ 61)Óô26^§(qÚ¾zŒÀW—BA\Jög¶2¯“.^–n{ˆÝØmøû¡Û‡¼‹xwšbqïQ·f"&VA·pœî…^Ôfí˜àtL_tð/ò!ß|ÝšÎ7 r€k‡è©‡ ä".š=ª|UV¶;sûL¯¯Eÿ,¾öE_aÁ«ÉΖ=µ„GrO·ªZzKi+g¨¢°þ¸“¼ã ¾’û_ý8sd¸:PõÍŽì1üë•<ó%Û_Ë·‹oëAÿ«,ÅRaçe>‚0ü· .f¾=’Ýe”S^‡s7¨ÄÞÇ}WD)¬ÓyãHbRr¿iv-冓(fûþÖמ%S"+ë…à¹j¯QY=÷p¯:ª·Fk³‘¨9S>F—!HÆ:Ž%XRV8Ê ŠUee/:¶>¼wï¿Íwô[Ûç|SçÑë´†äõ¦‚³ø_¸‹‡¹BøI§ù£f²O—ÖrHŸU'Vi²h¾Úø•3Ëæh»åA·ØC³:Yš9²Ú°á£Ú¨mV3™ŒÉ5tIÞ 2*¯…X<³P[.…R«±ÚìQeª²ò”Øéû¦{F¼±qÌC<Ô;àžÔ…ZŸMet*ìvƒl)®…Š@®7¿„Î]o³ ÖÙûgkB5sÿ´8‚ç¦lÇö„HYåZÎàLfd~„GvO™Ò¯=ÚAÁ¥Äê·EQÔhö;|÷1>–‘ÑFldjf'Ö¨ÊÆÄ@ÆN7oÞÔdÓ|»æqþ¹˜kè!⩵ZW!•ËXŒmƒ6®.…Ò1šÅ=d09'æw‹ùvý·šHÍÒcKR2×AÛ§ º¸º)ÓÍÀŽH™bvFäC¾Ëº!ü7`”9 } hö†!LÞ¦UQu!š=¤4U6]`B†ØÚÖ^åû¯ÿã¨-õPOdzQß$ÿ"`yS P …}i¶ ý€›Þh/MÂø,L7ˆ‚ùå¦=çöôŠöÚwÅ=¢WIäžeA£.;}ØGqç8³É˜œ¹MÅ,e»‘3$‹q‡ed±»ó ÙEvŠReYOßWÖîN5%fŠg¨ç“'oxæÓôÈ„L"“D‚ŒÝÉ's¡"Ãìy[·ŽŠ1—p©j  aú8ÞX¨³ÿ=µ À»@ ÝÚ]èÏH Î{MúÈ·ï黧]rg²Kh,+my”_ ÚS15r]z3j)¿9¸vEWÙ åê£þ ÝÊ{3(ÇW–% E¨UÛÀ]ºtÉ3ÌsjìT£ßYµ¨ÇŠå•u}Ò}ÎôwŠ¦ŸtsË–óJ"Pò0,ùÿ†!L|vZƒ]ðp D¤é–%g’w½Ld„ñÎ|‡“7kÓï/¸Wçsn.ñׯ v.Þ,üe¢Ò?éœÇù`_2x^A°¯Ì‡|"K´ìÂDL̆l†ƒqˆc]Ò ÞÇxœée·¸ha)œˆFee,ìÒ„xÆÇw|_Mâ[ÿP·ÙfuMoô6u–NË°E4GówðŽ /‹+ÉëÂÌOKð"ñEh­Ðb‹QÞÊ+¤-7PRs1·šù®ÏžÌüÜÈmf&f~€ÿâWTB¥Íb†Ä8†c”<ÊTeï⮵!¶®_¿îjf”É»«¿…·ìW:×ð/ù¾¨Êºº Já.äAö;'Gr™üò·9gSn=¾å_Ô¿þ°úÖ–P±P1£«ðýhXáiËïÇ~GgDm¶ ÝÃ=}¾|8Gt›¢è`$}OpSꢮ¥ Ù];*ë¯÷Õ¯ ǯ‹Ÿ_ó;ÀŒÃ¸Ïñ¹=ÊåJÖ`MUTuu)”Âlˆ@•é—ø› V ±šï½´×+»Wÿ©gÝÇ,(òVMv8ª”òvT´JѲ(«aÇ|õáO÷`OE]Ì™lÇvêÉfÕ__Wª²”ðâAÉŒ˜ûç\O­çÍ›7Í­Úèæ@Ü›h1û¿y›4ÍÌ¡€Ýúƶ)ÓÆã,Ví/¼øØbMͪ«¬ÊT±$!©JYòáT H JéOEö5]Ñ•‚‚9âÿUhÁŽ~™É–m2J£´% W©²Öîëý×_i²j†.jöès<×BëîóDð(AÒ7ßL­P2tFçüÈo)‚œדýf%ïÈö,ÙO¯ŒåEµf½a´wnï“wen¢ª4¨¡E"Ò+ªìÈxŒo€NȈª&ufý®¹˜«÷((‡rVmVkÄ2,cwfö«TYkGb=<3,±8®¶[LW"»4ŠÕgŸâ)B}Ô—þîhr¤J_ÀGª=å8]¦ÔQ+ ZÀƒøTÒÙµGû>èãêRˆAû=ÑFV‚¬,ÊN…nNç^ÑÆz£÷(Œ’,ƒ<ȳͤºóUYJu­-há? )cENø_(ß0EÞÁ;«J¬TyÜÁÖª® 7ýúõëìïgÏÙ*§ð5>>~ÆŒF ^܈۸ŠÐãŠ^ר›“’7@7q3+² ¢õ'ü$86,Â"‡…§cº%ÿ|ç;xû¾Î¤Û™P*¾í|»‹ùɆyH· Ç9ƒ3„AQѾº®OêŸ?ük£ö4Ls‹ð¡–8óùoƹº :î?½Ÿ©l¦w½3iÒ¤èèèV­Z¹¯Œ…n´dkˆ’'¿ãq‚L—¾:ˆý؆0ö;/ñ2;²óë?ø'«n‡ ùû´*a‹„ßñ»‡ÏKéCÜ™´™<ƒ<<°h¸ñÖ(±•¿rP€õüŽýˆ; Ã[xË>‚œô‚W"(c·`‹µË4µ¨Ó$ä+f"µP«/úÎÇ|_JnV†°>„#|1»º ÿqôúQOÏe üù§’^K‚­£ üfq‹E@kõÖiÙQqÍÔi§bj4¡±€Óh]V!Ô™ë<µ2i¥nêãà)>rË£–âå*‡xð3~nÖ”$Qð|23©{¿ÀÿŽ•DI»Äñ *K#h,ƶB+vÐ!aý¡ã4 A»°‹JÅﺸÊbúîéš0MÌYóïÝ‹µX›yõõM\ÅUVWgNÏ f£°ì‹zl Ô°V"TbÙÀÍ>d§ ð1Z¥3{zdŠMaTò¤‡™ðÛŠ€½$Í´j¨ˆÀ¦hú~2» ñ\¡þ)/Àš87pc!¶A›`Fá~è·;ÌŠwìxï¶Lé:”6SÚ¤/šþÎC±õƒîÂûx_áÓÑ‘ÍÙiÙ±ÅÕC=¶Ž‘ɬG`„íK,¢¡%g9ç øiŸñOâÉTb=R.VK´‰gèîãþø±*ª!ˆ&üz¬7ÿ'crgtvh‘‘¸{‡cxi”E(i%ÄN\‰•Yå ùЃJ!k›¬¹šš. s?Îà µ,%ûqQ™d‡ëL'L6ÕB(DEˆMu+¶VB%¤ÎPÌrŽ*KI.}Õ¹g gŠJ,tÑï ê×Ĺœ8Ñ]3#3;Ç5X#q« Ú¨½N·]•“¸ŒËÔgò#?ÝhŒ6«Z;9˜CíälâæLn>»é_Ö¿áĆ®.ˆèþ ßÀ¨š9(v·%Nã4»ž’(¹Kü#[Ík¼Î‡|Gu.„fp´*ƒéët±_DýµØåñ± 7\ì6l£¨¤Ð ÝaÕÈ9oÁU (öa_wtAHÔYŽåÎCñY‘õŒ.n–°ùòfMÍo'=g$ªm|ÝJˆq‡ØˆìÞ¢c€ äUÕÉŒFØ'`B.ä¢x÷ºðZŒ‰˜HEËì!Ï”EšMX5ÛE%Ölì#(·] †Òu!C1ª…?ãguc=ÖSÄ9¢l¡²ý~ªˆŠÑˆþ_Û}ÃPSX Y¥•ÜÒMºn¨o!ßËO”;u(Z.26¼v&ÕPm>æÛ1Á˜ä8ÃúåØä]ª IBÛ`&d²‹Œ}ˆ‡TŒõ qôpt=Y¢‹ä€9ýÐO~™lc/öV@J§MØ${ƪ'zR©³oÁäñ'þ숎™‘ù|â8 “7KcÊU¶P¬g±È&‘IIöŸšt&ñˆÏ†l¦‘x•Ã¬)Žâ¶§³ ø9ùC´ÉöÓ¦¢èn#Ø.2–´E[K“DŽ.°*T¬D%É]å› å’É9œk„F9‘óWüjcR8é¢ø+š“Ã1< aíÑÞî‹Fbd!rÓµqñq銦k:¬©« b+¿à—r(§Xßi!v÷.ì²1 øß6]=`ìxdVÎÅ"Ö^2v'vò ›=ä8UVú~Ý üáoK´<Æã/ñ%Eõ1Û½ i/Sot„×–<Àƒ¯ð{vÞ¬½F`@ ”£®p6œÞ  ÕüëÞ³”®¥QÚ¾ö¸}™„I†ÛÁÈC/D®!c°7Íÿ>…So¬š,àá¡5³”21æw„3Ÿpä±´~Ùë¬r‹•èN `¯~G"ë±> QTðì%vfc¶a?+:``ŠP>Ð(“èÂí|®àJ0‚Í®˜0ª‚¬3;y-Y®z$Ì~©þ”º4=<žâ“a¦,as4·4%Tõ³æKç+-Ažéè+uÙþc<¶ÝgXœ§xÚ Ýò #VEÅÑ‚(h÷dÊ/ø…óS|ú¥œ¿ r#·U^¸³OÏÖD¸}(ƒZ¨5]] ‹´A}6a@¯@Ú%¸‡Y[5¥¬CÜ,Ì*Š¢eQÖt¹â ¬`:æs±«Œõðy)Ñ-6CL† R6¸û¶‡|çoüMØ Í(Ì‘þlÌŽHÙ¡Pµè‘ˆäó?s;¶Sÿÿÿ8§`N¦ê÷Uƒ*¹µ+Å‚“×®Z`4¢¿Ä—­†ƒò õ•éÿ—!èÿ“wÕ4„2ÖGëã¯õÏ׿ÆëŸð«z_ô5œög¹ 3C÷öÝÁAJ,¡€M±™Ë†)‡!Ì¡s¯]ÐŪ Åì)µQûŠn‡m3Póç´j6Ö½ˆOŠªÔô[÷våjŠ¦ ‰Ù+pçz¢gz¤×Çü¬‹º6†„Α0aò­!ÌtÖQ•íŽîŸàéYÜý†hH…Ö°E´DËYº½Ì`GUVbRÖ*±HvÜr„†ù/?ÃgùÏÑ¡ã‹£¸¥uÍnÁ+¼Žá!1¶£Žpgap {.íÑ?¼äÆýÈ)œ¢*k߉k‰Gü^쥨¯„Jì—‡`ˆÞÁovC1]yÙ`q/Rã¯IH¢ŒÝ‡}Y‘•¶˜ôŒXÎoðM(B·`‹ðËoø­j™Ï×N2Vº×–G ‡UJ,3áÅ×ÍgB ÙÑ቞â);kw -.Â!*Š¢­ÑZ?BK­#rYÚ¦3•Ñv~[í;ÚW‰ i-mÑ–’ÁU¹ÓÒÉŒÌoãm*6ë±ÞÔ¬$J®ÅZ[²ˆÖy¶˜ç*Œgt©â¯õçßj¬Î‹¼Ö6RÞ»-!":;¯LÈdÖeÑ^ßD)Á ¥/ž5Äî2ö>îWA•®èê„ý¤bËÊãè\œÃs<çCËÛ°Ÿ+¢¢ Û¬“¡êT5¨É·M\]ùœÇygÆ<¤ùÃzÒ}Ù5ÓÒB+>µ‹«¢ª-9š®óx­‹Xkì&H•ƒ8HU–/·>êO°~ãÍ“8‰È_ð ?7FãÙ”h»,Fèµ%}ñì‰ÛUÆ^ÇõÂ(Ü=œ³Æp ¦¸ã„—¿ãwÖ«‚(Øm\]§²ãÂM¤fû)+ŒJ¥Áª8#šeø",jª¥Pj8†Áš<)ê3T#£u§eg-8q9g_Þ….žÔý7×KM€fzÌôS8†°ûÆg¥Ì1c±'cò|̯Úfϱ}¸@â@<%v•±ìò Ï÷øÞ^ ¦Hgtž„INËÎ9|ŒƒL[À½bjÙN»ßÚ– |•ä®#|_”$²÷[ZëflþR´6DÃy˜'#ZÅ(Œ²qûr#Uv Ý2ÓQ½TiÛÚ/к£{oô–‘)Ÿ*Åì¯ø5=Ò›•Ò¶/F¸ë<%ö“±çpŽv&fÚ%5‰TGuýÀxê€]•Xª+_ãkÚž.‰Õã*¨Œe~/s“ n€öJÊç*¬¢"ÁšP¥iµÙ²Œún± è’m–kñc=’cZáÕK•8 ¬9½‹»¡½€ 2ò=ŒÃ|åPÎRð(UY)ßÿ½U‹gßHß2ö$NfEÖé˜n{RVAqt'œœ©ã De+8‹³ÂWÖÏ,È’vFeIì­XM¸f÷™Ý®.ˆL®àJfd¾¶$ò¯÷c7tcexïŒÇx{­ï£‰äœê¤—*¼Š¦S8ÅÏc0¦%ZÊKp)–R‡o…Væ³³A†é $ìzê™QfppÛeìiœ¦(pɞȔ1È£LøÙÑo{s!ø%\*ƒ2ÑQ±GìÎG3?Ê\9sB¢î~?>zôhW—È:z¢'Å£¼k)‹¨çDμÈKCFžÖ'Âq§Bè„ {†RÅOë—N›ÉîFÔÄá¼4Ù üáov¢Çï)qqqž“wN–—…2–B ²-ÐEâq6ì€ütaRqˆc³2k<ÇóðAuT·Ý‡Ü-x•ø*}©ô•{T~ï½÷ÂÂÂf̘áêYÇu\g×oiQ‰Yžâé",¢ÊJ]¥?ú;4rÔq€ž¡TÙŒÍz+{æñ6å¥ù/|á;#Ìç(WŒI(è9¡§‡—|9i‹Œe«Ï‡|®šuêŠÝ¯Ü*„Ý“Eî…}÷ Ê…\©/dY¦mŸÆ*Ýï«~Ož¸Ò«_6Ÿá³îèžâiÔëVb%íß ±,Çr'xzoÁ–üÈïè`ˆR…7E+Œ'"± mK!j—E¨ldB¦›ºàµ&9Êc= <3yv-ÏkÙ2öž•Fé¯ð•ì¬m„J¬ôýy• ŸaeTN±}QÕ‰@„lS˽¨:¬j¶Ù\] ™°ZR•™ú¿€ ýÐ/!µQ{.æš]Œï8Š£¸£IïïÑ1ÿóù ¿YÚ×;EXìÜÈm6¾JHb¬_)HÅFJÀXÙ³]ÿ»\–Œe?ØMZ¢¥ ÷Úprhq±K£e¶k6e Ö„!L¶àFÜ‹¿çßûÇ­?ºº 2é†n¦®Jqˆ£±\U(]¿Àvn•Ëàè FÚf‡å4¾šcÇt;ÔSb¼…·6`ƒŒd©×Qç/ˆ‚K°ÄèPl¬nTÖêrjãµ)¨ô²ÝbÿËE–¤ê‹¾UQÕömbl!ÈØÃ8Œ`«TÓÄ„#œ6¦ãJ¥†ìâ—×ïéó§®.ˆ.ã²ZaB–Rev|„(¨™ðݹ¶á<ÇóP„:tËx£¶yøùaª‚Ù³goÚ´éñãÇ©*Ж—ò»xwÆQ›5–¡lJ(ëû_.ÖK*Z7…QؾÖÒqBØ[GØ9M{ä9Š£T}]2ÏèL(šBÞ ©7¼ž« "“èÐýGaT^ä-†bS0ÅßTû2>ŧŽKßHª\'^ž˜6mÚ÷ßëÖ(•@ y¾ßßá»Ïñy#4š ãY~ke¬Ä Ü6Àzûþ‰Dä%\²1_qtØ[GÃZ×e;ùœÅÙÈ1 Óì[*¥±ùòfM°f×q[7Wu2IHÚˆµPK _ñqu‰Œ¹†kTª·1œ©TñÕú¦×¦×ý¿VA)ÄAÊç8A)d³×Ú!Ù@¦(>m(€•2öEÑßñ»™ÚŽCÃÞ: ˜À'i‹§"­Ñ|È7ÃíX*Rel•°Êa®.…T.ââ0 ËŽì”30ƒµÔù s$ÒmFÃ!¾ÇfmÌù˜o¨&"1rÉŒÌ Ù;ÜÅÝÖh=c ÅÆ" ÀŠ¤<´q)Æ“±} ÖÈXª^ÍÐL!±JöÖ9ü‰?ƒlûÖ7pãm¼=ƒíR*eòàå¿2~èꂤÀ.ìbëAˆ¡âÊ47”{ó/üèW°t³6&ë*e¬¡Ï­°º¨+#ý†h¸KiÊeA–§xc¸^£±t‘RTbcbb<ì0é#]ƲG.Ò ÙSÃ}'¼X+ò#ÿb,¶Kjð€úðøÂ.©)“ÉG&{E{Ý|,ÉõÂÉÜÆmjƒEP¤ MÁSÃDðÎrIÙR¤2*;by¦%“2Ö0œþs<G¸ Mc<ÆwA$«â?à‡7³°"OΘ!C¬u[˜ÏHš°º„Ka;‡s¶çhÜWÆ~ŒùgÇïáÅìçº]CS-¹Úå*ý¹Ì™hA•m<]Ñu/öZ:m'væFnG¨‹¶CmÐÆ ²f±dcúiý ‡dÉp —1%A œÿ?7d¨ÊJÁ%e‹‚]¶•”btÓØa—§¨îØMe,û÷(`dàØÎ-Ü*†b©8z̉Û'4¡šMÇ]…ì žÌÆìâ(ž9¿Å·R›Ë£¼½Ìûb{PY³Xj›Ô™æèïàNBh‹Y•~’2#³0íNÙh»@©[ÆHØ…Öv)“GýÑßÒ~:®Âe,+s0‚´FkäI}ÑtõÔüºfDÍàõ@¾Á&h² »¤¯¾YŽåePÆ¡e“íAeqª¼‚+¦R‹V¿Œ-ꣾ0ʱëj †á!‰Û"8Ç£@ E'(*ÕTÈeÄv(n'c_àU͉˜è¸,سgGö9·]roîÆßõÎí=¿÷86Ës<Ÿ‡yåP.r ÅP«‚½$"‘Jïn(1`#- Dðí• ¸<¡Œ5 mô7þ.„BÖæ2 þėH~¶Ùí²nC})_.%L]< ÄùiMFa~òŽÆíd,«D4pôÒã38CëoV84WÑcM ÊANËî&n²-‡#¼ê­Æj[â¨PUkŽæv,›¡ZnÇõ,âv±O€Ï˜˜1F?²ÿ²¶Zƒ5úø]C0„úCR¼diHŒµªH)¤fY^Á˜wu;ö(÷’±±ˆ¥èÓïÅìPŽá5“}Ø焼œ •ÿþCWutFû±ÿ#|”™?ŧvYsú´Ð*só µX+;H‹)âó;Å~$l=c-¯öhoU.7p#‚Ærhhëä¤xɦ¦ yFÌ2–U‚ÕL9¾†¸‘Œe•Ë…\à§å¸[Xë”ùâldÔÖQ~ùýž=wˆaæc~)”ʇ|?âGû.}íƒ>}·oUì¹²"«½£‰7ÌeXf*»žà µkQiÑïRÕ m·”uÔ”6>È“!C€¼¶þËÑÂc¡uc)"®Ëq#Ûíë¬%…Y˜•y·XÒ…hkk?øöû¦ywGb$;¦Ú¨½1¤s©Ê*sáÌ7ø¦:Ø%)ñ†É‡`V?|ïÇx«2jŒÆzoŸðSÐJqÚ+e!èk¯­ÿ4÷X¨-ç@;†Ûw‘±»±;ÑÖz§ØjM•QÙµ!žÁü#ó½Â½®?²Ï$ìiœö{í‚.ÇqÜ.iZ¢š9tÒS6wp'A¶o´!%ReìUã-Äuã«4¬ÊkFéí¶/–_ïi»kߘBIBRI”TàT—·±ì¡  ëKrçKü(dí³}ÉÙ%gÅþmIšêvlo€a‡qÎÙ.±¹‹¶¹ò²šZÃtûxÛÄB,l‚¶¦ø2m/ñ’/ª5_«±šF‡þ+_¥^^‰¯DHqõÁŠ«+<üì,^L§©{WDEÆßN·±¬´õQß… [¬µÂ”϶+Û4!šü+ãÚ$,À‚‚(X…çbî8u;jkÊôú O)gãvŠ°)*fú-èÞCaÅl朡¡­ÿ:ó 7½‘¢žÚÞ>b’Í·‡o³ͤ—D F.ml˜Qˆ:ˆƒöÍž(_ÆÅÑP„ššENæ:®G#Z ¡ÒìK¹þåÊ*oÕ%´ˆ¿Å·|µPk'vºD…`[«ŒÊÎÏW T Æϲ/§~Œà' §cºYKüŽäG~éÙQõõƒŸ~0“/—ÍMo#ˆ ɦ<’àçqíš7±zŒÇлÿñ!(Ó_Kòt³Ÿ*‰’NØT 4QÃ~]]{ræÞÏ@ÏcWI9ùÎ}‚O(:¢ã1HºÄAËWQ–¬ÂªJ¨$ûò8 e9Ûê{«)c4£ÂåE^à1)B™lø6™»ÞeQD:Ù3VïNX+Á:@ \™kRô(?@÷ ª‚*Êlù¿Gq…ÄL³¥;–.Ö¥˜È ÔjÖc= Xj8|#NÞšÐ_ãk |W— lûˆ¾€÷5)‡ ¼…[baaacÇŽMJzÃI•ïˆÒslŒÆË°Lÿu(†þ{×EÕµw7„$›BÐ{ïEªt¤ƒ"M@‘&UDiz•"]ADHD)"EB/i@B õýÏìâ²ìÎÎÎìN[ÿï5O˜¹s2;÷½çœ{ŠÉ¥ì0ÇŠ˜Bkh`ìÄGÆB#4’â"BåºOã4©L’öKr=У3:«‡öÇÙkgI•=vû˜õGÈX‚%…P¨ªÑ/¢áqD2!Q•H&Åqô çF=ÔÛý|ÎdôØ[¿7lØpÒ¤IæÇI‰Cÿ;~ˆÍËŒÆáê¨nüÝV¶—Ý,ZSh-0ƒgbfrHý¥œ—¤Psn"1zÙæažÒ‚X"éQÑ…ö¿î0m§àËøÞ™Ÿ@°ͯ5ªVñ÷‹›IEêlÌŽFts4?•6©é‚.˱\i)X@„ Çx,ôBº$Ö} YAû-¾¥_,ôXÌÿ8Áó¦K±Ôð1÷lœÁ‰9À±Ò9c ÌUr‚Ô¹çuçiUu>!Qjd!‹,¬é˜®´ ìð‹¾,z&.ñʱÇÌWìÅX\ ¥ÈòZ‡uW(Ú½¨²:çxžùŒÅüÕÒ;A@Eˆïñ½Ð _ŽŽáüæ–Fi ÿm0‚¶ ;ÇrfÑJç(€aK. aü=*ÊB±[-Тƒ›jq—ƒ¤Îú‡¦·œÖª1@8ãvc"ã#ðR\âØwñî^ì5þódÒImˆö¯{É/­3 ƒâ| ´,HAJ ùë¥=ÑSh6K@ÿZ‹á[„×ñú&l‚¡G­EhÝ I9¶ºMÁZÔ¹Ycæ ì®"(Âs_U XÕqˆSa‘ÿ¿ñÏ™Z¸LÁ2A§å.×RmBµjãTº‹d dØÒŒSggð¾èËS™$Bö‡ÿmÜ4>›‘e^à…Ã0l¦™ñ£0 l¡vKsKDZƪ;ñ°*ªÅQ‰î".Tµíõ ψ¯~ÀJ " ÑQ…Áð †0-úv=RÀ›øW[åÄ_wÿ҅ꮈƒÍÑ<±¦æ’?3: {¤>ë׿úðj·‚nOs\)Pö8ŽAu†+¿÷9lvRÉ¢åX ™Ñ £=<9Nh†f|<Õ¤ —C9‹ƒ0Á¸í%ÈW Ç>Ã3‹ úÆ ¢ :¿qs¨„cIƒí‡~JKá,È–)Š¢JÅðÓTÝŠ­ÕQ½0 ¯Íc3º0•6Y›a%¡-Cl …œÒ41>žOùAüÉá ØŽígÿ‰?¹9m:¦›2¶8p— ¡ÅÁmØft ¨c7cs=Ô³8XeÔ ÕpC {WÃÆ?ŒPÍèƒ>C˜YA&á7ø†è½*mÄƬÉ/á öFh3˜ÌtvLÿiºOM>âêÁ",r`k^ÔAZY?"êX…UŽ Kß57§ý†ßJ1q%vp÷ƒlqð:®slÍ›Î0Á±¶ý±ÒeÑvDGë QÓ0mÔ® ¨c{¡×§øTi)ÄÑc [½±á ÙȵP‹cA·þŽŸ0E™¹gË@ÍÍÍõŒõœþ«J³ØX‘Œd_øªsÛ”X”µ_ÒQ͇|΄ss,‘p^äµë…KGz¬£ú‰x-HL.YîàX‰²hS‘J߬õ_A«@Bœìì#5çØD$’¥òyAXõ2T {†g ±° 4Fc»µM‘ZO ¾Ù|@Øqj¼9ëÍÐv¡œ§¨ÐÉù–…Rà)ž!ȺeR34s²N¦]Û¼ñé‘Tå/à‚ÅAR¿%L7᎕ÈQ°[leÓ\Š¥RÜT,(αÝÐís|®¬ â"¹õQ_ºÊ·Ä®³0‹”Ÿ×ñ:Ïnqw ‘Z~†|„ZLü6ø¤Ë>xò@¤ûîÌwöOU va—j+2‘U; ¯Ó6*±Î¨a< Z;xk‘Ñã1ÞîP]Ñ•¨ÌâàÛxÛèÇxɱJ8cû£¿­Â »±Ûz·NUP¶ôÖiœŽB”kzâƒ38#EYzPÄ®ôÄZ£µ<­¬j­×]@E}ÅAæCaV¶×˜-œÀ‰hD›8ô=:PcÖDkÁÁÁ‡ÛtO}‡ïø¸©?Ãgôcqð|2aαJTƒ‰AÌiYà¤ÒEQAõÍd†ué­xÄ @Ãê¯ÅZçÇ4ÒÚÅ‹Ÿ={fëVW°.àBy”·8HT`XA_ÁWøŠ;;‰,q=ô×_ÔKV²µ››¢©ZøOŠbÛÒ £0Š¾Óh±[9(”ÖôÕXíüU Z¿è¥u8ü) iS0…è¢#:*hü®=¾Ö½ˆ{fŽ+-…5Pcv)- Œ÷Äfû±?q¢,|h­ìÆnîsH/XÖHBYâàDZ›on–¢ÌëxÝî·9ƒé*A.r7aS1«‰šd ò)ú¢Oü°kh¥CØHŒ´.¡ø(àB5 =ç:¨ãÀ:Bëò§ø”ì;²ÝÔÐQË·‚ïøìoš¨ ±PµÆãTL%›±ª­a©áøpì šÁDCÛÊjœÞa#ñòáXÏAží‰üØII @@*R¹O£e+Á4©”û°¯ ªTB%SFŒ¤¡Wqu4F‡"””1óBëÍÐì¿ê‰5Ça.ˆ‚ü—cÌé®ÝÑÝ–“_~ôþºwhW âzˆ‡y‘W­4H*²ò*¢¢XI |8vñÙ`¥ãA>{^RTƒI@‚E?G[è„NŸàqï.—q¹1“æÿ-¾5ÿ~eߢehæD#ºZÇqcj!ñ‰Ô÷UÚ¢-ŸâöÉHž„IôXÚ zØÕˆ©LW|’uÏpõ‚Ötu–ˆyŽç~ð‡qb ȇc‰©*£²ý¡ls¬§ç‹T/Ž»Iገ‰dó9ó,ÎÒâ¥`µü¥XJf;u¢¥l!²ôv‘‘ˆ,"¾c*Ç9œ£'ÏQvï>îÇxRõû¢¯c…Ad@…j|«JžJ°;ùäÊɘ\5M;_΃³‘bï _»š3+øÃ?ÞÐRÃx™9¶êñw­“õÇ¿…™ˆHAJt(òÄó¬'Èœ†ˆDø¥,ÄBunþŠŽ÷ñ>kÙÃGxDËt0‚û¡ŸÝm_eñýŸßëòëžf»L$3é!ù‹W²…|¸Š«ôu_ÁãΗ(còd6Òmìv–d¥Ò=™ä8ö)žæAþ^Vz¼D,¤´ˆ+7Nâdâ†b(‡KPæ4„á>CþÄŸµQ»*Éí©H‹G¸¹€^›©˜JïÃÛx[=U­á_ÝÿÃí*-…¼‹wÕf.µAcª—qçK”1y2ÛkxmÓ”˜s(ê–É%Ë]FtŽ%ýÙT”›'>ÀreÚ†md¥Z´›´†œÀ‘lFV!ËeVE!j:¦ÿçÚ¹˜ûÞ€á ÐßKìÚ]ŒEæ]ï®x7¤eˆÒRÀ/ø¥0 +-ÅKlÆf’Ǹ AdE6¸(Ž<™­?úÏÁ;Cqr¬‡‡‚0¢sìl̶è2f÷pì²Ä•„‹°(1|2.åì¾ Û¡ù‘Û¸ÝI§å.ïêxŽçù Rh‰]UëwåÀçuAºƒ—íÔŸQrCÏ\%†°ˆ Ú7!ÅrÖ9?2Of³Éz¬¼ääØžè¹ „^5Sd 4¢ÍhDó4Båì^e­«(Ó\˜†iô~ÏtDù" Y‹±8¤´»–îj2}ÊÔUKi)€,ÇL9åA «…O~5V7ƒ }x2ÛøÁîF›]ŽÕÄ×±èî€$üQåŽàˆÐ«HŸ)‚"’ö0ÝÄW¶v¸X!϶×!âè’€„(03ÔßCӞǭ<¼<ò&åå) ,Çrë:`üqWƒ$Èœ· Òýˆöù¤YC†m¯É˜LäÉóäÏðYQUyÈ(+öa_C4,‚"k°†ÕD‰™¢xá”ÂÅä‹Úí?.Ó|lºXÄ*u÷¹˜[e9ŒÖh°ë¹Žý _qÄ5ÄI[­_걜^â¶/Öõla6f“iuå0: ³ñ³?ü¥s[ÑŸ…(úù_B/gâTX¯ÌŽâh}Ô/†b´þr|­4ÝHu!FNÙÄEÈk!ƒv RZ (ˆ‚Š.;‡sÁæV¥6bãkxÍá[\¿~È-7—×Ì=‚#5`3Yo)–Ú <àɱ|dàRE¬û2Brê ÎTLEš×•P‰ m‡G B“.zj36×DM¡WÍB!õ‡9ÑÚÑm¢½ ËøúNÂ$»Q4jÆ€%ºÚÙ=Q†a˜E“‚”â(N¯÷iÈE¨Ãy(ž="r›2e Ÿ“é^D0À–´|ü±¢sl bœO…»ˆ‹A:ƒ3NŽsWI5r’‹H“®_Cc4v¬’Ñl$"ÕÙi†o°ÚÑË°‹ø{Õîã~Â’‘,©lÒáŸä´zíµ§®‘žC@ i rÞ‘4(RÃú3})íc9¼;Cs–È­@;wòڅሠ"³ÚV!M>þXq9ÖP*JjÒÌ)òÎ8½éÛ¬‹ºv38ì‚Þ" 'a­Ñd19¬cÓÚ‹Ø$ˆ\3ÍICŽÀZ"'c²!"4­ø´±S-ò·ÌÿÎúw”–‚/hŽ"§{ŸÞŠz¨Ç³ÇÙAQˆr¬!È'ø„Èíøñã½{óòrp,qš-—ü¾‚£8jÝ”Á1ä"·Z8SÁ{!6@ç]©+°¢z89+è5è‡~ÎŒ0óŠ ˆJòúá±+­ïã}‡ƒŒëÎC<W6Ù0lí°ÐÖ®TQö¼ã@Æcø¿@ `[°êlÀîå®wÏ«°›ÏÁ±v?’“c×a]'tk4²ó#ÿA8’¢˜‚”DˆâÏÿ ›Jˆ "ÒBûëÌ13‹¡˜²¤DúêL!3 ::N+ÚÇøXÁäÇýÔûÚ@핇rd…‹‚ØÑMd¸ÑyœD¤Ðöoñ-é½ÜŽ˜M…è*û%¾«fŽ{±· :@ ã0ÎIÑ2üà'zY°_ñk!%ba4DC#1øƒnºKH9é‚.b5.¤qh}tÝ–‘:豬‡ÒRðE:ÒH6ˆ¤w¹Û…QØNˆÄ“Ar ÚD(³9˱ríy ÁÙ˜-â€0TükŒÆ‚|¼ÉHE¨ˆ±ú´Ð;¿À RùÄÚÒ%¢k„F2·u¦Õa36GqºõaØlaïꣾݪhªÅ¸-ã›*-…¼7$íÑIËemÔv¸ÝÉ` þ ½JNŽ•sÏ«3:[äï8b×æh.H=&%ö}¼/¢ D†âZ¯ôG…#\D?ê<ˆEì×øZ¬¹AöEUT­€ v o:†uXG «#Ë€Ôg©º Ý÷TQÕŠV`E´‘hpZ‹ßÆÛÐÁa“í".æG~¡fšXËÚ”Öc+9}´ZIQ0í ž”@‰MØÄçdÑ•Xâ@ ˆþ„Ÿxö;ã38‚ÖìoqïBìGê«Eï3qA"}‰—pI¢ñ¥F‰·K´XÐBi)øâ>îûÂ×n‡SÇ0ƒê Ž“õ`É®á9ýM‹c‘Xem]•€„Èɱ¤JÝÁ4áN…!ŒOË<Ò9ÅUbaðYé¡ÑCؽgb¦X£™ð#~Œ@„DaÿàŸHÔ7ód¨> Ãœ¯ ¢fÿ0Û·®¯ÒRÑ è(a&TDŤ89ÎZ¬mŠ¦üÏ'¥W,Ž%nÜÊé•´Ú*)NQð6nsœCÏ–Ì )ªäÕB-±Š¥!Ö>‰J»ÌÀŒš¨).>ÄCÒFHIƒ1vk׈…ó8Oë…“UA”BFf†.Tw4é¨Ò‚ðÅ4L=Ãn.æEQQúŒ?ó`óÏ'kK,Žˆ‰ÞàxÄÓ\–Ó+uµU"ʨÌÑÄö;|Gf…·&õ˜F”¡VbeC4e(kýþ:^§)#Êh¤º…¯Â>C$²P8Põ\wç«xßâf‹Ç(5þÂ_qˆqÀÕX諸*Ö€ƒ1˜´bž'ƒoÄâXRb9*ïùÃ? rú d¨hÝý[£µ-=M¬.Ö8¥QZ”¡Z ÅRHXÃ9 I¤:™‰œƒœUXEó®ZÙJ$”ôn‹Ø ZfŒß=>¸~°ÒR@+5›æ ½bÅòAvM bèµäs²·ÞÛGï#h|[ÜUe9JnÊ+Çf!‹ô4ֆщHt¾æ$¢弫3©~ð“Úâ^ƒ5•PÉaò¯øµªÕDÍŸñ³¸‚ ‚Kï|=Èx  ÒÞ¸ï2½ØÞÅ»Î'ž`ѵ¸åIh‚&±‘Ï™DkÛ°MÐà¬ÜE”î/ŽÂø/9Ö3C¯·)Œ I¸!Og¢©Ê¨<“-Ž‚OÄÍ€°@ôXˆ…NB/‰<ºY[´u "ñ4Nw@RlUy•Ã0Ì™|jeÑ5bÐr—)u¸ »œOø2ÖÐh×uöU@>g­ ­LÅÊ]¤ØçG~»W‰úÃßÃÓ¦0‚$á†< Cï2c-¶æK „¤…ô‰vÈpvrnè&Q… ÜÁHDò¥»Š«ÝÑL¼˜!Q»ð7þ&ó§…¨6ôÞØ;+®ª*З®‡Þ™fFD°¤ÁJÚ]º Êüˆ¹ÏICÑšàxZ6îÚÝÜ['|z‹È±F½Z¬Ñìâ&nÍÎÅ\ã?‘X…$½#±–“a„d¼#X”V>X…UÕQÝ®:ú>À!!½W¢ IgPUHQZ Gp6õ¬6P›’ælä’lhƒ6BÃPM˜ƒ9dþHíØùŸ¿·¹Ïù#ûh•c§aw ¨IMB’ K‚3¼À Ü(ˆ‚Æò¹¤ÓŠk ZԾŷ_¾{k£¶ˆòpƒV½Ê¨LLkë„ dÌÇ|Rwû£¿lÌ/³0«'z*-…ƒÈÛ2ï„M”–‚/ÈÂr¬cÈL)Š¢2T3þÿ²Íp;ãïDkééé‚FfåØöhÏ1}`Ʊ¦ÿ³œ#Ç’²!]Fž-úJAÏ¡9šïÂ.©oG|îLa±èd#¡ø ¿…#œµ Íz¬E,=7Eºð™ARûBš-jV¦O¥¥à "ÉDòÃÓ:>CälåÙÝ¿Ä—'xë½Ý<ÝÆŒiÉʱ¤™sGG¼Â±6ÒDäXZG`„X£ñÇiœÎü~ð{ŒÇRßë!Ò2šaK¤ PàNˆ+’] Æà`~„^›FhTåÄmå&š ‰YH2`ëå­îQîJK!qˆã¿©‘†4Òôꢮœ-éi¾“nÀán%N[ykeHHÈ™3­9–,»¼È˽`òÇB=v8†Ë³›c R¡=á9Óe¸Íw¡a!Fü¿I¥”³žÖ…0„e7p£ú31S‘ZˆŽa)–:ÓìXAÐ×íç¾ë”ä–X SëS|ÊçLz—*£rgtv¦YžchŒÆyÄi$Ûºuë¶m0O­9vvØmÚÈËW௹ySœNmÐF©½‰y˜GD”!EZê=èÅXü&ÞtàÂ9˜ãØ…Îc¦uB§‰˜HF÷XŒu>\f$#ÙóAY”XªítiÛÇ‹ˆ-ØÂ'S’, HDNÆdEB>‘øÞbýè&n:¦7Zs쌇qv¯ÒÓ«iˆŒµÉ±ƒ4ƒ‰ÂW%•jzò:^§E‡f"™-ÐAÒÉHD¨#Ô­Wb¥"Ù=7¸‘.gç&qAÂoÆf¥¥p£¶ ©¢´|A“(òpÏ MØD¦è•…‚Õ£5B,Ž%2±û7jÌ<¶n”äáåá€HÖ·2• xÃÛHzd¶®H ±¤¾Y=Ö º$ÙÄÌòSÜœi´ü}ˆé™ï."`‹º ®>¾ªõÑ&?q™f»QÑ–Aš‹\²‰b˧žˆX¦´¨Ãi`*±ØÄ›ñoz8AjÁ±¤ŸÓ„µ›ù ÇÚØó24Ç%[åïúíÌŸ½àƒÊ¨Ì¿JPÌÇüæh.è’ßð›MÁ8pwº¡és1—Ö>ú‰Cœ«lrY# IþðwÑèßZ¾Óv1UzŽ?¾n$õ4DÄŒ`µ‘áQ´©‰š²…AÏ«8…ÒX ŠÞà`0Å—Ç0{–p÷wŸš0Õ»XpìQ-‡r|®òøWE•¡d©¤¨‹2”PXëù“0)òIQ0ÿÚS‚Þ´)˜b±¹/Ȇú_† ä#|d¾á»k\·Ä É;°Ci)AÕÑU 5)T±bÅØØØÅ‹+-ŽìÂ."R‹ƒ¿ã÷B(DÚ‹ü¶j^X*ÍO™²ù „‡ÌŽ“òIl&¨ï­ 2øDIññ@<Žý ŸÉüià¬ùe?à‡`;Ц: ƒ 0††h(O™¾MØT%[¡•uÔ+qo bDï½%迃w”– _;Ü#ÌcÏž=99.œŠTox›gü‘)D‘r”Mìfª ¾½ó³™Ç’!l7iVk+†M,Ž¥¯@Ù ¢ÖNâdA‰‘¢×í߉ü“ÚÒ‘Nz¯Ôµ¶NàD4)ƒ2=¶fb&­’Š!.ãrÂ\±vÁ­´[?Í£gÒö~¤Ç3zÒF“º"*ÊÃe Á°°opÏš0sDáØ+¸ÂÓ1eα^áÜ<Ø_N±8ö.”GyQ†Rb“dëÓû¸OÌSõÄu"‘Nˆ£àUèžD²sE¼»îâî` æõúõÐ+þáÁV*½{÷®ˆ©^²Õ6tà¦ôЈ‹ŒdDÁœ!Ïÿ^“"…––ŒÒ(ÝÙq·q;¡à2v«9öc5TSZ G0þÇñÁÍ\£-ÂYœ-np;óJËò îb ü Ôjü1VÅ&•û:®“ØÎP™‰FÈÊ D Ÿymj4ór¶ûÏ™ã¸ÃjæXòôK¡Tôp²± ´ÞÙ-ÌNZ´èæí%\j‰–±ˆul‚¬¿ù˜/®Hò€Þ|_øÊÖ·QD\K½¦ÕkÓ³Uª–‹Ü)˜Œà5XÓM„+…‰˜HFå,…cÉ0ì…^ûïDËõPÏÖ§³`3¦“´ßɘL:ÆøBæâœ{°ÇnW8u‚žÕp WZ Gàçµñ/9VÒèæc~¢Z£õqwlXГqˆª]w‰hfGDDö ŸÀuÒ]ë ŽVú¨=ØäX{^íµ÷ä)ô.Ö C;±Î#’ŒÅYb!²#6c3· ‹è‘,몭Fd€iôÂúô‰cßÅ»òïÂP¹Î¾2ôLû°cES3b;Äv_Ó]Ò[o±L3±9šóoäÍŠÃ8\ÄL Ô¸šeëÖøŒí˜9@¶j ÔàÓ&Ò¬^møÝ=‹ÏP¬Yâ/xÉÜ X† \Ò÷èM«ŠªÜIv´èóô·ëÿ-jÈÙœHР⊩©wp'ò7Rw­>mUzxi‰§BÊ@”!ÝL”lqc½î FGP#~Oú]뫽óäë§+±’Ôžƒ8Èúé3<ë…^uQwf9cK%ãWj—lQµ¥ËIøÛ*?."èíýß’BKKÞ¡W\¼-1…PÈÔ3ËVT€yaá„W ¹Ë¥XÚ.Ó™Úd ÚÕRTˆßÏÈÛ0¯ýó‚›ù˜_%I+ûÞrSÈ)ИN*ÃÒ¡Õ—­¢;Fsœ@öN$"û£¿ELæyœ'­©ºÑ$‰‘B¸Ø *€1DVbŽmƒ62oFEȦ‰‘¶+ ¢`K´dÝœZŽå&–51®‰Ä+ H3C RHQQTÑ-\qÛë|ÒymVDÇ;±ë̉Ftk´ºqÃ=Ñs‰>¬(ÈS)Ϩ­£¸ÏIFòhŒöƒ±âLÌd¸RÌ–`‰ñ„è ´Â]žWŸeT`„Í4ÍÍ›"t¦¦Ea2&;?Áʬ‰‘éDo­ï¤ÓZtI¦È<134w¤oþ2üËT5yÊr,Ê€vã0N¢ÊçRÃ-ÔíÇë"d{ÝÅÝñˆVh%]…ŸX Î6j;wjµŸóÝM “´#ëÖ̤Р}z¶œ±/>µ1Ÿ¼y·ÔNÐX± Ëd.‹ôOÑÄrC:m©Úæ¥ZæbnC4ÌE®9w‘qxÕðK«ˆ Žõ‚k! •ã;|ׂÙHt=„7²Ý©VdêöC¿  À©]sÇpLñ\¬¨óYRï”rr,dùÀG趯-g¬Úð»z–‚-I[DÙö:„C•QÙùqAAM,Ù¤HWB¥Š¨¸ ÓFÜK¬ËT 6HeÜ—1—Ïÿß}®gLyaKÊ•M'ÕŒK¸…(¥¥puFÖ©ù‰esmž »©5Z‡#|"&Ê“¨’‰Ì¼È«lK/kмs/ê¾õÌV'Ç9ƒ3…íW¨µ7ǶG{I]²ÉHÎ ñ]úÜPƒµKªl[´%Õb ÆüŽßnŸ©˜:Cñ*Ç& LÍ2®*$° IHR¤›“ Å+‘ŠÄ¼ÙÂ%ðj)ôáºCß4ò]ÜŽé%Q² ÊÌÃSažñÊ6€Š¬ªa‘rýÑ_þÜm|Ev¢¡»wáÅþüÁ½¸;ŸI[ÛŽí-ÑÒþ=ÑÓÚ—(è•VÕs&DtŒðÕû:ßÀe$FN„°ñˆ×xdÚÚð‚¡ò ÀÂ*Ö¶W´YË´ê•Јg{@úÕ\ÌÕÓh h|û Á'`2ýF ¹û0¥ùpòß“s õ;Ó;£h ¬‹rììx¯+-ÅKlËNLÅŒ6ý¤iÏÒ4^šÔL®ò×7qóc|誨ºK•íqIÓ¹3ó’ª 7tºÊU*oÝ꬯ 1o¥ÀŒ}ÐzgW¥X5±¶½¦`ŠÌU ÈŒúÊyG[¸€ ¯áµº¨K¬åÙѳó¨ÎïâÝ ýõ"¬àl7Tw/ÌvªevR¡KD¸(ǒ ªÀ³sLýpÏ€Ï ëf7°÷ vuÿ1‘%´€þ¢uXG¯P(Biu–¢± ·7îÅ_¦ Tÿ¨z¥~•æÍ›×¢…³›žaênâv‘'üI=‹+Ö¶×~ì§Å×ùqøãTGu9ïh,dÑâ‚™˜™ƒú"¾¸ô…[°ÛÕ{WoáÖl0¯Ê•Ë4©aÞZóBɆY)8qZ ¸(ÇBe’?7ÔçÏd’”SeÐÐpÄ:á?øõà·}lú'½<»±»úè¡o€ô¶Èœ,ÉLdÒZ&V7g'‘œ‘¬‹ÒÅŸOMM]¿Þ©Î¹IH±R9¾Á7’n{ƒ©ä܈LAJ䑹 Š9H}­†jMÑÔ´&ç~Å K¼WÂúü>Lö]aE(CUL%*‘|Ÿ!ìy€ÁD e ŒÁ]0†)FÇb4–R¦íô¶´ìî®wði­uP‡Vgšõ HÏeQV%ý}º.ëZ ]Q†Ú ™ePnâ¦G|{É™çq^ë)í¶W”9,ï–NqWÄ°ÊFöWøÊXžË<}Þ8÷ï¤ÝÑ…é¾þí•ŽÏ˘7–}‹îšU£"yà¢!²P Çvã›Ë”äÅr{2‰ZëϪØ*0ѵP‹¨•,™uÝÐm)–*-3Ý<Šy,?¼\”Ñ>Á'B}Œƒ0ÈÍ++ÁÞÞ#cÉjðÓyÌb9¤¥y¦e>“´è…^Ë^éG!ŽãxT!ã΢§'Ìæ~ï…½}Êûdå¾\Ôb™j,ÈZ£¥– ."K ‹I†jü1Ð*ϲ³HkíÞáÞìYÌóãÁu LÅÔ!p*oBLL˜è_G´ ­Ñz6º„´žz¨gøC?=‹e-V‘ÃXá@Ô™3øßÊÙãé9žÆèHD®ÄJÖêO&ŽÍÎÉÖ7Òwûº›é#Ö:0)ß]'(ã†sÑYÈ[­‚NÀf©ÖY˜õ^›‡y×píÀåѶ³1Õ‡Ø)Ô¬–yå½C45$?òó©1k>ÎX#ˆ؋ƈTäð.‘ùìü8üñƒ,K–Ô²(Û 8mÌmØ]véÂtçî½TZBþÔJgzØ1­ò|w¹/¦O¤j¨F¶Ì‘§¡’JŒn¡¿Z…Ã09Ÿg>×xj23ÛAŠë¸.óŒ¶ÆÔ½S=b=²sÅé@wwüá/¨<æMÜä¯ÇÒª$u&B>ä“Ùª‹ºRGÉÒ72óCj*Úc ”UqHÅý_n~«h 7+ƒaÙ3‰xõuV%É´ì†n«°ê2{8pQŽUªZ+>ÆË×¢ø¿©|Æl>kóDS@sé’+Õfô…¯²aºúú.³ºˆ5Úfln„F‚.„A:lŽìs<Æc¢RÖ` ]ˆn^¼9]ÐEæ’h_âKI›Y_Á²õê N"ížlAY·ŸÜv‹t¼`°÷½Š«Ë°¬#:F"2ÑÝÑ}%V:Уœ.ʱPTrZsOã4ýÀ@¤z¼²qh«[‚‰¦žfß¾}V‡Õ‹r(§`‡Í…ñ Ý¢Ü=äßÇûS0EÐ%ü•X#<“Y]²óækýµ‚nÍŠX s.Ró¢%…eMSiæûqóßbâoÚ´)oP^zIî>w*Éà<Î/ÆâNè„ Â(ܽI¿¥ƒÎwøÇòér{°ç|ÒMõÐA‘•†=Lk!L!Òo­Ë}jzh–.U~§ž?Ú£½Ð:«""¸~pÇ…E°4JÅQA—p—4´ÆŒ4Jö ÎäG~çÇ„²(+J‹ s\Çõú¨_µù»Ç- ØI“&EGGŸ?¾äà’•ÆUE*¢ú¿ð×\Ì튮±ˆ EhK´œŠ©ßã{¢\šƒücmá9žÇqZÚú¡ér~ð#[fFmÃ6óN¯ÖBl2ô#&ü–N¢îÜÇ~ìJõoéOþŸ*rëUGV¹rKÉLkÀ{¸G룠fß²áeÄNì””cI³ AˆÌÝ@Æcü`8bÛÂl!õõs|.H=¶ØˆéÓ§Ï7è—ë)×I•]uBXów>¸…[$êp o†f¤Y `†Ü{Ÿ#Vüc-@ ål åÍþ´v÷DO²eÈX¶µ¯êg•6;/âáÒ n‹ý"s‹¼ñÞRH.¾Æ×oãmEnÑ$¢ãj1•ØMØ$t«4ñZý#žÎX#R‘ªñÈ|ˆ‡Ö‰µíÕ]dnÎNúF"ø´ê¶ šb}Ч 9PÕ# häÆ‘Þe¼¦±­Ñz ÖðŒ¿ý LùÕC1_¿/³¶~†¥7§ýºö¥;KÕ÷|NóOK<¿Ã„As˜2!@K­»‡`œWø#_=‹Q)ֶ׷øVþ˜º’(é|Ï8âê(Ñ ½‹oçŒéS±_E'¤ Êe%ÞÿWKõhŒfJPš=¡¤jlC_ƒÓÀÛÐê{Cë«Ÿ¾Ò7P¤:…ƒ¸ÛÁ–ù¦¹¹¹þUüó•Ê·mÛ6‡¥Ù}g]"ÔQ`Ä,a½J¬m/zWi^Ëï13:Âq³"“19 aÎôããžõ‰É‰îqîbå: Vâ¥Õ¡Z­ÆjU%Oqƒãi[¨¦¦ú«‡bè]eŠœ½ÀÑ“GµeE˜er"¢´pcôw£}*ûÌ[0¯W¯^b™„$¡4âïÿºÝ2Ö ÇE/«§Q,wAs4—y/ò>îC¦À÷øßø»*¼†×nà†32ØÕ¬>MøÔ³¨gÒC1ÊL¤d̘#¥ÎU¸÷Ei TSIqóæMM”‹Ù4·`‹l·ËÊÉòˆó˜¾ú­[·J•r¶u— +°¢zºÄþ¾öË°Bë‘u‡XŽ‹T¸àk|Ý¢… óÙøTKX…Uá'Ý^ž8¨¸¾q;tòF"‚[f[ÜËúã$!³²¥Ý5¨¦‚žž® ÐääÈ‘Ä'¦`ʦؼLè·ª_x«pãï">¨7ñ&-»‚.µe7Ïlo=K (± Ð;„ ™«Á‘8ÄñHCZô)‰’¤ÇŠ"Ž½•v˳¼g¿ÅýD¹£óÑ+ˆgKö$—Ô\»vMi)àWüZ µä¹×ÕGWuùt?œûÁþ©B@T"X+bqÀ1g¬¿ãw›… ü5Ožˆ`aÕFí=¯Ô¢–UQu3xéáÇq¼Š‘ê›Æ„؈ž³~ü7ã5šßn¨¢ 3•ËJ®k£ûaŸÈ")2![ærÅc:ƈ>ì)œ*Ã÷þ¡ ¨-s랧ÿ¬àÙÖóão>¶>.s0§'K%xi±[í.¸ô·†Ï"I'‹{w>³~ëÖ­¡¡¡õÆ× ªôZ÷‘’ð)±ªírbj+ÓÍ_íû*¤MˆÒRƒ ûþÆ÷}kø>Ë_+»‚+ùOhIþ¡Ã^FÐûI,ÎÖüD£Ñp¨‚ü±+Ú3Ýd=É(a-ÿB, Gø&&›\*}WŸ\­ Óí¹(·×Ú×U¡¾2ÝüqáÚmI ‘•úUa¶º"ußœ–ä ýŸ¿‡÷]òþ%ŽÕV[„¼ú¼~‰~ÎO†y ã±óC Âz¬¯‹º¦Ò:ÒÝ+ ‚ÔUx{¯îíUÖëú£ëRÈc.ͱ.T¦Û999¢”Ä—R¿*%ú•(3XðžOTGõýØÏÿ|bŒüÈ/ ÇÎÅ\Öq–,Y¢©¬ÉÊÁ n‡v+ÙÛXIReË Ì`Ù_ÄÅò(O˪±‹ ÇÞÃRÝK…5ËÊ‘Ä}Á —æXc %¥¥pb%ûÈI_•Ï¶|æë–”*‰Ûên+¨ÖÖVl­?Üô.k\Ã5G&ëÝ5Õ5¢d oÆæzL­b¹±Û+¢â.ì¢Ç+[ÍpÇÞôgiúúúê£ä.»áÒA0Ô*©úJKá \Žc½á-Ñþõýg÷µy´m•jcâ+|ÕÂÂÑI%ÓêrKï²}Õ?1u.-á·Â¯Vk¢Ž3‘±‚ü¡ !èŽÉvGø;ÖJ;ñ^¢{ŒûÔ]SE‰.TCgúQZ árKË-jRŒ\~Tyï0ïŸþYŠÁ UPeŸ:=¯€–’@Šøýø†¤·ˆŸf}|oê^m 655Õù[ŒÆh¡‘iN"é½Ñ»J‘+çÖ³3¬µ`Ï­—ö‡“ò…¦»tP ³þ *-…ƒp9Ž•hEûâ×/ÜcÝûê;aÂÑ'\À…0„ r \2¾¿(Ž‚&$kýŸ°vøòl-N2Â%\ Eès¹º[_õ²(ûÞ"¦íƒ>c˜¾¯2ÁáVÚ‰‰‰… ®Ö­šgaÏË÷$ìh—vÆÂ`½ÊöR‰—ãXZÎD÷Ì\xpÁ=Î}ÚþiÛ¶mkЀ=ÞÒIL¤ è’žèé!–£Àú¶WÓV»b¬{K’ÑXž0›S8…(S…ðû¸ˆã?mÄ ®K—.EEE-^¼˜~¯2¡JPÝ ŒÁ-c„" iêéëê\zp9Ž¥åLô&ºSté~L¹ò´´´õë%)ÓW%~Á/üÏÏBVBDÿr<¼³+ǵ>žššª‰Ð`íïòÞÉO“EÓ'q’APêÁnìv×?q2õÀûžk<3X]sÞ½ûOëïü-Œ;_çpÎù¡la&f@ë®\ä¶@ q»}qÀù÷ðnê]ïbÞ­¿n-Š<¶Ð=>gê÷»0þDZ2CÄ~ðúA]˜nËikÒ~„†‚E{ä@t‘蛡aY+¯Î;8OW\'Ê-èï}ïˆ2”Œ)UPÅV©ö»¸K OZ®w·€(ïáï—~wrï¿^„ÕÙÈE¨Ì}-E‡«sì©S§ÆŽ[´hÑ3gÎ(-/ˆõÀÓ²Òüjúu]ÔU”Ñl^ò‚(xù_òÄ(0GPx&iÈÖÇsssÝŠ¸-<²Ðù[ÜÁ­ßh)H©‹ºÑ™;Å€–hVPÃVÇ Ö{¸ýÄv·|nŸ”DÕ<„CeQVŠ‘å„«slFŽùçŸ*- _ˆõÀ«M¨–¯u>Q†âÀNì´U·Äa‘§>Íáb†v¡õÈ:…SÖÇLàÑK÷D?ôw—? IåPn0óiað>hŽæÎ7;à†ˆùÑåºpÝŠ?Wˆ5  Ã1ücˆ1¢,\cIQZ aåÙ4Æ=ÆýJòç‡âF+´Z‡u‚.©îž~)~áiÄáÖÇïÞ½« Ô¤¤8Ò'ˉH Fp*Dˆ¹…¡ W˜ˆ‰<φg•Qy)–Šrw[wâÝ4–hvÕþU"ŽIÏ?A‚l(uÂÕ9ViÃùþÓ¥Ÿtaºe¿.EÜÀP„ Úé&>ÑéS¤Sb —q™¾vVôêä5tž0×±-¼7h¹e R¹#¹K]u×ó#ÿiœv^[wâgffÆ–Õúj·žâ*'žÈ$³€§Soз ŠxÊâ+3œ,&ù íWI¯Ös¤ÝÌ5‚Ì4²[]2£eøNè«À¢2ÍÚ7Ë­¬›(·8„C1ˆq²|ëoøÍá*…;°£ŠÜÇ}gà€ˆ?;;»cÇŽ­[·îñM·|n?_äJ6œ„€-)Ú UQÕX-ÇÕñ?Ž•Î“ÌÊÍòð÷ˆë'µ³†×(D R¥2‘™ùÜ=$—-0ü¹‡žEev¾âÄÙù"ÔB­Xáð屑¬g‚Æc|MÔ”(bÖþbeïŽ3¦qãÆÏŸ3©LýÖõsq?p+a<ˆæsŽ™ƒœ!(µP ‡ìÒ9®È±Î“¬1¡†›¿Ûî}»Å‰¤}ÕAA—«¸ëŸHê(0‚ø_ë™Å(Ëì|õgçk/öB!ÇZÖnÀZnÎð5‹ÙA+iGtìŒÎBë¢óˆ…£/_¾œžþ2X¢í¬¶1¿_þã’«`Ú½iÚ<¨ ®[<ÖWäX‡×µn‹º¹çwøáÀO>‘£†O4 ÎtI]Ô•t·Ë¾á©¬=Áïß¿¯ Ònº!Nú‹Ø{¢å)‘B„X—§xJ2ôGÑ-Iç~³yÍCÄÐ4¬¤6liu|Êû\LæŠ í|P 0OSÜø1s„ùÑ3Û® ×mæe„‹r¬Ð¤í—·ë"t ~Z@¿?þ¼téÒÒÈõƒ1x2& ºdÈümè<³—%¸âÖ­[š(MF†8åJš  ÿ¨âdÒ`ã°(·6á•C9Ñ+¶I½SeTŸ2>\ûƒû´Ÿñb¥$Ê Ä0éÛ/ð)ÐWJ e€KoxÁe9V'ÿäí“îqî£6Œ’N ¤!- awq—ÿ%)H F°Ì߆>¦þ%' ÿäÙ&959oå¼åK^>ΙȤ‰|‚‘”/ˆëŠ¢¨"_…x:kASS³}ûvQîr§I±ç¨!@ìhI»uqWéÛù _‰2š »fÍš˜˜˜A˹ås[˜ÀSׇ—ŽKµOl~8‡så ëüêçØ(XÆGÞcú7Án™×ÔŒÔÐú¡EÉΕ5Dp–5C3A—üŒŸÝôeVbx†gô °ÖeÊ»:o™Z¢µè}ïÙÒíá-1ó0O¬{qãnU@…Qå|¤ˆ!²¬8|øpDDÄÙ³gé÷;fèÂtvM°u²÷«þ°4 èŸù€±p¥ ¤oñmgtVZ Ça˜_jçØA`i›tcæ¦M<Ë|Õ6*üÍðç9²¶¨ Ó&qB=Š]ÑUÁïÁV×/™¿è ëVî§÷<ˆD¤u¼+]+´ˆ¢Ü…'ˆ£±Ý^v!uXÑÉ“'ÿýe”ìòß—»E¹ ß0œõd‹7h&ýïïDªc€P¦‚:Þ 2Q%®±Ë¿N… qTȱôJÅâe¬O#³ð¡Ò3Òc:Ä„4y”ÅAÃ’` ÖÔE]A—\ÇuGf ^±Ê<ÿàà!Z°" ´q¨X7Z…UÄliÕG}Çòœݱ/úVAgš Ê¿÷â^·h·f³šY+á3Ù/Vú߀fǵ?í:Á]Ðå;fepULÈ™àî%N'±p7üœ4;Ø×àh²À5°»ÂŸg=/о€[·”g"Ô„ä”@‰Ý–Dö>pó? Iò„?aUeïeÞÓÔž8!À·Ìz>¥Pj¶™ŽlÆæÄHWRÀ.faV¢îtLúpdnç÷ëµ_}JùêYèÑó*Ä_ø‹(—fM °Õ@¡¾ÿîy=0ì_XT™¹ã:Á…PèÚËÅÁõPýjõ˜1JKñ7"`v#Èn4O ºlXˆ-Úf³rlVvVN‚_VD?_õQQÐ%ÉHÖêèæظAŒuOÊo®_Í–5źÑ^ì-ŒÂFæ1 G¸ ÍA)ð ~!šŽéŽ¹gk †¤±¬¸“r'ªM”ÿ«)WwaW"n2³‡Q\£ !²¦¨Áa†|[ \wŽ½‹»¡ÍŒRž{<›·l®´/@KriCÒ ˜m#Ë®‡ E0L^Îl £a½6GzFzᎅƒš%§'ËϱÙÈ&%v«¥Ê`“0I%ÞƒµªöOOÒFhûí7±nÔíú¡_ÒŠ¡ØHÛå‡'ˆ j¢f ´xÁ]#‡`ȧL¤¿ÜÈÎÉ®2¬Š{awÿcþ‡pÈÖi^ÕÅ=‘’ 'v`Gs¨… ƒfžæƒ„%LI‡ãÀgÿþþ§Á]O†ÁEÖp0ÞàCSi¥ ^©šú45_Ó|A­ƒR2AñârG®ÁšJ¨$HzŠ§¤ÄúëUQ)$<[£Í}Ì–ûî;Û·jÓªbÝ( Iaë„Nõür ™Èü’B+”öÉxiÁ„M)€ïñ½Ç»Úí'[mæ¯Y/àæ‘Ü~4‡0ã&`‚ÒR8Íûš9sæ(- ² Û^ oÒxÆ{²€Fü[ÕÍœËnÞ½R+$_÷|òor‘…¬"(²;]5 ³tžª X#H•eÍÿýùÙϺüºcÇ,ûÀ:Œ±ë ïõMôÃ8LÆñÿMí×p-„©ç*7fbf"Žáج_g¹r«?ª~F6K&]^f)‰{Lz&©Ç%Ð …Î)µAÓT³k×.¥¥°ƒLC˜–…ÃË\]Ù!BM•8ÃÏàL0‚ù«‹2ã.ÔEÝâ(Î'J„ôÞõösbÄÁ!"Mûm¼mÙ›‘›QgB÷îó¼’ÊqÄ`÷53¥6Å œ(q–u¡ñÖ<}úÔþyJã´¡L9Œ9ŒëŽ®s wë¾±» M 8@Jl-Ôt )±‘ˆT!dž„g“*Ëê•ýxÛÇÞå½³rª mLª5Æâ~„Z¡•3£I]ØU%ë£þQå8m6f‹^8Ѥ`ÄHÒ™73ùåì÷Ã8]¤®Ë]̦3›Ì^¬Sé²c&ÉðT%Ž{÷4Aê›äV S¡˜•‰8vü·ãuºá?²ç¼ÈbË(ð+~t)±Z,E’gíBç‘ͺћ›ë_ÅÀw¬?â Z ë¡ž)göž‘¢"u÷X'AöÑ2,‹FtS4ýÉF­S8%iN==·-ØBJ5™o¬©"æ8pó€wmï¸nq·“oK'’ ¨‚*BCÍÕ†“'Ojʨ—c+ƒqv/2l~M²úÔ§Ÿ[”ÛÒãÊOO¢£.èbÿ<3–¨Ó§ÈдË1½²¬syñþÅî…Ý“Ÿ'[Äßà› ¨`îÕ9†cAº¢úÌÎ d¬ÄÊ2(S ¥fbæ£WÓ¸ ñÿá÷^©)(öa_5T£çÆ¿ûáýÌûEúñÈç1÷[5z¼ù€f^䕨›lغc«®…Ni)l"ÁwЖu÷f>,Ô·¶ v÷ å׸븂¸!èªOñ© ½æ ñlÅÌx£@ƒÉ “ˆˆ8Êz›˜LÂ:¨ã­ýèOØýoãí@¶FëõXorŠvFgq]²©Hƒ9¥QšT}Yh?²‡Fêôºö“Úçä(œáâÖa]´QZ g1jþ¨°þaJK! ¿ýó›oßüMókRUAR4³„–Ö'%–´Ä¼zUwºcbeÝ3“Á¢¯¹vD =sWp+ÃíØ^Õ­¹" Y¤§MÇteU¤Ç®Âª×ñºúîèþ¾›…Y½ÐËÉaéQÜÂ-ÒWßÅ»a£·‹”Xö²³³_ýõ1cÆü’ôKÞ†yƹtÄIÙd-d_ãk¥¥pMF5©òi¥¥€9¿Îq‹vk0®½Bj(ž€„(ðÂ6 Õ¯Äáæ•ÍZÁ€P¶oÙ²ÃË °Z¹ÍúÑ\ ²:…SBÇTwpgæÑŸF†­¼–`‰]©­qFc´?ü#Yug`†3•jæ̙ӠAc}õôœô:ëè‚uï~ýnn®JÝS µ&¡ÿà¥qQÍ£ê¬ß¯_¿âÅ‹/]ª¼c“Ù¹Ù-¾lAïÉØ cGçX²m+ ‚Pó0)¤ÄzxJ$”˜¸‡{´\gk¸wöÆY]ˆîÇk|݃04‘¡Yî`ÄB,¤ç)sq‘Œ(D5ESøh_ óã ßánáIGè8}j:Ó~C1TPs"ܸqãñãWõ–³[|*û„6 =}W´N”Òá'üT›é™ãòp r«Þ¤úܹsO:¥æîüÃó¡mBýªû¹üÒÞQœcçbn=ÔjÇÇx—Pbð OóÔ§±~Ôzrëà6Áü‡ @€Ýšº=Ѓldò© 0`˜!ÎÄŸ&.51*‹Qy"-+­Þ'õt‘º÷7¼/ç}½b5ªPL#'_MÒ#Çíy0ûàl··Ãk<Í|Å$W–c倄6§ND¢JlñGÒˆN¾Rfòßž¥yÅyÜÉ·²Ÿï+éåPŽ5Â%°[”*\ÀëþXçSÖ'âõˆ?.Ûéu«È"AˆK×34âØ­cdî)-že=«2¢Š.B÷Ù÷ŸYª,ÇöDÏaLÑ8ah€.¤Äážî®gïLòåî/ÝcÜï§Ú/ýz7y¶½»ˆ‹dqg’>]OñT½ ‹0X =3½ÖGµ4îš®óºæäªnÅߎí5^V(qa~˜·F^¥¥°‰­nõ­ä›¯c¾“·Y”((ʱ‡pˆx€ÃµÈŠ½Ø«Ú¤d!‹Ä¶UŠ*ú­èêCªÛd béÄŽŸñs,bYCÔè° «”–Ârss›6mÚíƒnþµüý«ù/_®´D¯€žálÌVZ ðÖ’·Š¾]Ti)X™•Ù|bs›¦çšž§)űÙÈ.òB[8å"—–fwOõ:½9 ÏÐéSXw£þ¼û§.T·õ/;%sI‰TÙc$F6ESù»Ï8ØH’+-…|ùå—µk×ÎÎÎÎÊÉ꺬«[”[©·K]¹«Š4²Âæ@_¢Ä€]¾–$6žÜèWÙ/°Q Ý ÛJqìçø¼>ê Ýê"NVªí¬(ð y< ~ëGÝt#](+›+Ü×<.ÞÐú„»m)ϯáµ>è〨Êâž!HåAGo½õÖõë/ÃEn<¹QvDYZ+»Íêöì¹ÂyU¢„«yªçY¾_E6BjFjýIõµ¡ÚŽ‹:fçf«“coáÍ  ¸ èª'xBz Ê“¸±>á¦Ö+“u<+7Ë·Žo諒m]kN8Å í/gý[kCµMF2Ù Ûô.žèù%¾TZ ÁØpfC@£ïXïO7}ªT”©.%Pâ\,]‚)Ù)Ú<ÚÔ¢OŸêYÒ3_ó|Ço½Øì°ÛÅ@~Ž¥ -Ú:°ëíZñZ¶àæ™m+ŽkÃßt‘º“IìžsVk­sëõIHŠ@Ä^Ë\jµã'üT ¥”–ÂÐ>úçÑže<ƒko;¶Íþb`!ÐXþï‚+t›CµXyv%-XJKÁàÄÝQoG¹çs·Åºñ,äçØ%XBs‡gÑfÎâ,)± %R‘ª Iþ*ž=à§ÆÄÑm¢…Ži÷+L@B8ÂÏÁJ›ìHDþ•FFÙEzvzãOktšb=Š¸î`;Ëlðý}d(©×ÙPÛ¶ª¡úÓƒd»®í×.NYg>n4³‘6X[wDÝ{)‚ É̱·p+!B­˜äïëãïz{7¬˜žpH矚ÎV…ô᳇žqž£¾Å´x«ºë¬X‹µqˆS°9¸Žá#=Ý%‘™™YµjÕ‰ŸO¬9¾¦.TWmDµëXrý¸qÉл¤jÒ8$;÷­æ‚sÆÛs±!z–ÛŠÔÒ(ý¾.²xïÅX¥¥?þøctLtóÍÝ »7 þhçG™Ù‚wu ±4Í/X¾[®¥ÇúÕñ›/y:ð¾n¬ ×µ˜Þâö‘{·yÛôqÇ´ÆÏø9?òÛbÞë¡Ouݬ.>ð Oµ.›•X7°Ý¬–ò*¬"Ó%¿=5•Ð°™Éð/’TE&c²@yÀyœC˜ ùùàÁƒQQQûö1[Õ©Ù©ï®yׯŠŸ{÷æSš_ºs‰ÿ8þ°l?yÎLµVO¼àDÉry‘ô4I«×>|îH©v>ÈÈÎúÝPßʾž±ž=ôLI—¤‘ ^)H!‚ÝÁa§pJ§OùOz ÌA–»ÖûùÄøý¬Ÿî¿¶Ÿ–×=çöÀPBçŽ=´ç.€Á1[°'M«^”ù —Zn4Góÿ@Ãs,_¾|ÄKwÍê“«ãúıĽ7sßÌìûÛ G½É{(m°eŒ°žÞ.dŽÝ56¨q#ŸùçL“IMÜcÜu>º1›ÇdfI*5Çæ"·:|„„^˜‰ÌŠ¨è桺zqR`aÂi­?™(ìFÊ[+Þò­ä›š‘J¿ ÿØeØ8^dÐ`Ën T¯"÷q¿*9à'—p 4J»Ê>“øûÑß-?oé]ÖÛ#Æ£Ü[åŽ\·L~Ü°±e 2É|hö‘EÊÎUC—« Ìà2M§‹Y(+7kêS£ßˆÖiK ,±á¯ NîgñÔ; ³*£²RÇc¼‡>õ?ÕÅ~áiô÷²~DÄ’¯}¾rƒËáÕïë&Ór”ÙѨe˜8¥ þ…†'hU~„GD_£™LU£*ªîÁ¥¥C¾âà© Ô7 îýuï ®c>½i}j W*áQÜcÕqqê[ž¸¢á´†îEÜ}ÊûtYÔåæã[¨®Î±¤{„"ô2{Œ Žàˆkµ9p´ ¹‡<ÏÞØëÚ£k…<†nêÓ{?¦@(Óƒö§³&ïá^Y”Š¡jV×c}C4TZ ùðìٳ… ïÚµëáӇþÙ>’ȶ@»c·}”nža€ßð›­(‘8C‚ó ùbÊTŠ"˜­vf£{è—k¿è‚uY9NÉ›–™6jרÐv¡ôèŠ÷,¾ê%c;3ÀÒqì]ÜÍüßá;¡f £Jý‡c laYB¢F—ckgpõï«uaºVWZñ¬Ñ½ÈkPc€ƒ<οûQ±ú¨¶Ø, …¨£8ª´ 2á³Ï>kÓ¦ù‘Äljo.}3°^ 6@[°kÁQ›FÝOcrº£û\Ìeä¤aÿË”«ò7ëIr!Þ»û£Áþzð1Ø_“mÐ~ÇÅc;Æ:v£ä§Éã6‹j¥õÕêëéû,ìsë¡à wQ ]©C¤rŒ³¿ë‚ɘ¬óÌþoÇØ‚oxª‡>Õ–2Ùk~/¯ª^^™vzÍ<hfVƋ‘ûP¡0äÓÕC½Vh¥ÚüåXÞM”–B&ìÞ½ûömvý©;§º-èÔ0Hë¯ÕUÐy.õÜ{ËRᬓ¾/’˃¥’xp³àÁË ÿüÝó½–õ oNkP`“À¢M‹öÞׇt Ó0­ ­¬fÙ=©Ó§ü¿ò˜ƒT5÷GƒÚaë„"Ý‹¸ uã(nŸDƒ©a®Œ.ß„éHï„N¯áµ§xjÿlÙAoTQwÉ´{I0ðþÀ°Ãb;Ç’YíUÞ«ÒèJSL½—.¸0”<°e›öeK¿ë)×I½•ÌKùüþ¯ï[Loá_Ë_«×æï˜ÿ½oÞ»ÌèÍš5Û¼y³s"; ‰v`G~äw ÉÍk7ýc_}†ýSÿ»XŸpSu{U<{¿’i´Ú¦«Ø7[S Ùó­Ž?7ø xK9Èé‡~uPG- ×a]=&_ÿÀnìŽ@„±r{VvÖêëMhP#@›W«¯£¯7¾Þû¾HNWQ77ÆóÏ‚›°ìúîÚw#šEp uàì7?³È›EÜ£þ¯½ólª\ÿøÉÉêN´¤ƒ²K)Ã Ü *K *C”eY²D”+Êeh™ ÈF„ *”a÷Ç°"Ó–!—] Ý¥+-ßß“KiÓ4Ínú~èm89y“œó}ŸçyŸ÷y$’ú’fcšÍÛ7/#ï‰o:u._®@¦±-°Å}ºø13ã¹c1Ö%ëT”Oãv—Uùèw¶Ÿ¨¦hýE•ˆFQ†žrFW¯ÉôOö!ŽÃ¸&hrçL~’ ) )šî/™w_åHD¢ÊŸa`‘4éAÒìý³ÛÎhëÝÞ[ä%’ב7îßøÃ-ž¸eN+2eîx)aâö¹zdñG²ó²7ßØÿßýëª/­+¥÷åÝØ»oLß½Wö–[Û°aCAƒõÄê ^wq·­Â*3žû#~$#Öåw˜/ÓÈÃÞú%\òZë%i(IHN(þx–.ÞUz O®®LS…{NèòîüàgÆæ[³Û#QÑ}Ù®©JwtŸüD&¬aâ¯Ç{x{´ÿ°}ž5øj<_‹ìØkj¯UV={6?ß®ë›gusým½ý'bYª'K(deeq îhâÑ5qkÇ ~jäSÞ­t“E y؈°A+í¼°³{î;wÚ©Á„%XWc5Ð<‡çÞÕ¦U˜ÿáÚ2+§r“Žt‘[îÔý†õíE¼Ø`L¡“ð@óX‡É!©Ž’}¾I`ûo™VÛ¹4j¨É+)kÍÚQÂ<…§¶•S`Ì•Y‚%­Ð*åGÕ¦M›6bÄýï>üï_ÿ·k\ã9ÅýÅ\cŽsçDa"eOeóÍ—­^{üøñ .ܼy3==½°Ðú³X&´» ëéDu¢Nu§êêvªÉC),\¹neï½EbGÿR"À Îù)œ"ý?šñÜ|äwFg†-?eHH-ÝÉ7ÑúMO㶓„HÎÜ®p3HEjoô~Ï™Q Øê¤!Lë?ð‡£bshR£½/ú:¤ Ä˜1cöí+gÙ¼yóÆŽ-g[ÖŠ+æÎ5Ø…ìj¨íP¤Å>\ÅÕÚÚFj–ž„L©Í0³M™C._ÛZHd…¼V"šƒ½)K¿wø¨ƒ×3^÷³+¼ïà è6Ÿƒ9ÁÞ‚-vx9ã¬ÀŠöhïÚy\(èþ4ŸV´Ù¨=9{ö¬… ýiii2Aæ!xXkHŽå.4Жä1ŸÛ¸]õÍ ÑíÉ°ÂK™EŸX‰J ±ð%¼D¿>,¬ùFÍšjæ?´SÆã1k†fïà;ôÑ0 þ x>ŽÁ¦Ðô1ƒº¢«Ó‘°ÿ^õoùòtKkÈ9 ë°®z™ýtò› É,0ïéäÜ‘Uæ#TÅijÑ6X,µ1áÐ\¹ÚEáäìd¡½>1Ünîd.rßÇûõPϱ.âbuT¿„KƒÐ@3«‚ÀõŸ¯ßmg7GÂj¼‡÷>×V5‡$$…#| ¦˜÷ôD$’ÀJdÌ‚­04ÅsVÒ¿bìÅ^’Yý=˜˜šèáÑ~N{{ŽjöÕB­qç@ƒv>æw@g.~k4…õFïWðJ®v+‰‹ó׿x?þtÞiGÄjD ⎘ñÄ4¤5GsóŠBBl‹¶b™+GÏlJu¥F$¤þúdEØWñjQO®„; òúò_õ°ç¨R2 ÃHiÍ(lÈ¡þþQ:û¢òr÷hÖèþN[Î׺ôû¼_ÈÈGÂjä!Ï nf¯#}ÏL(Y‡ÌTÈÌxo²íâ«Ìå$ùñxœ¬x×ýàwò N\=!©-´vv‡iî~ /ÝtDãÓ˸¬„Ò”ÝOÎÏyœ¯úâÃ*²‘¦Hycùü#ó=«ñ;~C…w¢év8̯yû>’L`-G¡ÌI5‰x¼Œ»«[£uÑ-y áÄOÙif<Çl4ÐÌÁø/Â"û{¸_ãkò’*».mÁš,¾×ö ¨*LÛ5ͳ½gáC×qoWaÕÛx»BO!Ï¥ ÚÀšòZ‰•"™†%X /eMXÅ—Bº£ûlÌ.úsÓï›x%?sŸ•SÖMlìNèTõþƒÿØóuõÕ¨Ìd9š•Fct4ø]Ûd¸ª—Ÿ'•Ï;bFe8çe†T(犖|@Kö Š„T–H`Eè»+SeBVÑ—rw‚T|«ÂzõzÞŸ¼µü x¶à„#üy<ÿ›vƒ¯Ðw‘3XUÕɹ€ -Т/úºLò’‰Œþf´O'[¯¬úWµÖM" IÑx&˜ý!\ÄEX–H`u²%U&» óÒwc7}¹Å×÷µÖl?7ÖØæÛ¡†üwRþa^9 38ŒÃøÓÁí+Ær,÷ƒß×Úr>U‹{É÷$’è“ÑŽˆ5!u ©ëw7p£ÍÂ,³_.ɼæ!¸~ò‰C Wä–;\õ]Ñ#£0j?fÅÑ$³_þú¥ÝG÷Òü)˜R Õ†a˜}Ö¤¾ÀtÝ–®Wæ„Ð-Ö ½È‚½`R[KW£ÛÄnþoø;zVf1Ó¥nÊ‘—p©.êšF ]†|3Õ(¹X²S}_äž=yÿ/ú?sˆQôáhÞŸ_pÀÌ=#Váî}„ª£úP 5Ý2›(DõC?[¿Š% `Õ@OðIUÈ€- ]«"¹hk‚còýlGtÙ„Måv'‚ƒ³_(y‘qãÄî¹juù3,a£ú†8øμýž Hð‡‰J)K.á«ñ˜èˆ>&©31“”¶?ú—®rcEèòsæ³'q’¦Â—ñòmûë*Š»à.\­è^6²=áYnÇØ}ا„Ò’Šñ°“êS·àû‡ÔNQÏåYw†¾½|ÿ£ý¤ßãûP„–h,»þøz>ˆ·yœ#ø¤´dÂ5Dçñôl°Q¥Ä$$ÕDÍû5Îu\ˆµQÛ¼ju.C R8ŽK€±Z²•‘ýØß팳›I`Õ°Èú·€wÏÙ[= GñeÜ!²f·¨îèÿ|ï÷Fï+•?œýA¬X9ÀÐ ì m7vwB'R˜ñ ·;·ºŒè$¥ nâæhŒ&þS|Z)bÅ6ÅMp“ òò«lLÁ”ÏÊ쾫ås|N¼…k²ÃTk¤ÁwR›Ów†a Óâ¶r¢ÂÛ¸ ]yÞöhÿ¾(qÌÁó%µ%=æÚu³­qNãôXŒõƒ_7tÛÖ5kcCs¹¾›M¡j$FúæÝÃ=ŽÄI ù”ŒØ;¸ãèXŸp„ŸÂ)ƒÿEöŒi‚&ölú0n“È={Klrù‡2l€¾¢^RHlCr‡Jsìæ1ycyÛImí?<#d#{-Ö’ŸEc&càÎYëÌt6:­ý‹¯’¡‹Ø—ñr Ô˜…YŽÕy§B*HÝwGÂú$ ¡.êü¯ä ÑS‘jÉKLQý‡ÜÕ­jœž*žÊL’Y}Ñr–PZ¯.Ý¿äÑÒ£éMs œ®h™µS1•ü©fh6ón Ì¶ª&BZ7ƒû Ý¶ÙÒ‡O.a(BŸÂS˱ܙkkÛŸOUŸŠb—¬u3óÇÁÀz®­ÑzFX˜@²xEÆÚXKï†åx+ðBš¾ Á&lªƒ:¥[Ã\O¹î×Ù¯z·ê·2ß5¦4…(TAE—¥üZ ÅLÌ<‰“f÷; ;º º Ã0›î'Ê@Æz¬ïŒÎ„wðÎ œ°ÝkURÒÆûð+Ô+ Œ7j¬ŒD"ò'üTâÁ#8„ hXºÏb+¶ÒMͺ:ú A R ËÉ@DéMšyy†5ò|Ú3îJœ#Æhhè*†iјœî¡ºëÌ0n³ÕíÆ¢œžSfŒd’Ö¾èë ßîè¾›™áZO‰X&nÞ¼¹‡‡ÇÊ•+ËBåá>î{³x=CšÐIZx-<ù,a} œÿ°HfI[^Ä‹]•ŽŸu×o>bf_6{r ×èb{¯“ØÖE]²×`ÍïøÝDÇ3©-ÑÒ*Ec’ô3~žÙÑ‘¤µú¬ÅZq5Ž§àÉ{ò1kcNœ8‘•åj™˱œfØ¢?sÓý›£¹å 3+±’Y°N‹‡2ƒdöî‘—M†Ö+xÅàªý¤}“x?~ÜwŽO5²â¿ ËÞÄ›MÑÔ-Ðb†|ŽÏ7b£jRcƒïTßÅc*\å‰>Ã}Ø7sHák£¶æ,²®÷boÕÜ¥UQ®ã:ÇqÇqÜѱ‘ˆÜ†múß/â"©ë»x׌2Ý%Ð ¬BpÂ.i‘~ Œ®ð<佄—ÞÂ[£š›Ïm×÷üWÏÊ%#ßüN¬ÂªI˜ÔýôÉ îp@D¢ÈÀ [»H oáV=Ô3¥Íb&2÷`ÏDL$W@Ñèü°á.¹X([S€‰ qÜ=[qWüáO·t[ ÈÏZ–ŸvfÜ"·<"p~¼”Y4^ÅUšUŸÃs£0ÊàaÇo—·–‡¾š™ë ¹Í$ªqˆû_ÇðVh%ƒŒW¡zJGtœÙÇp¬²—þv,î‚;i¬6ô930ã|@s=Ý\Öªü¾j³8øÎzµ Ö1,Ä[ù€ã ×ïOLGúÓxúC|hð°ÄìÄÀ^ŠŽŠßïºx™èk¸F÷‚%%&²TµT¤ÙbŸ“@sG‚va×Sxê ¼Qb»y¼·Zäž½:öšå§bØÔÛhZ\±ÿj2’ŸÁ3euÎ×ä¿8íEq°ø«_¿²óíÌMÜlŠ¦dx0Õvd"“÷á?QâèØ-ØŠP?øYRD«ˆB¾®Š–'²•‘qøàÛ_ìÿCßÍH÷9{æð~üÐeCí9<û“‚”HD’íÁ²­lxRAêÂaXè&R×`ŸÇyËÏFÓ}׸i¼GÎöX+à ‡°".Ždv®êH¹2»ûÂny¸¼Á·3oÛs„v&ùC1´5Zëë<0¬ˆ\“Æš½sÄùQC] µ¤Z%>ŒŽqÜ‚ïïS³¿r³!îO‘GöDÕÎre6)3)lX˜´ôÛß*Ю22sBbÓ’¶UIq“x¯OÏv=ò7SÐ?"!éHo¨z‡öçX—]¬RlRßÉóÜ„lºHfÇ$'ošÌ×à£VEÙs„ög6‘Ó·{=Wà+ÕW|0¿Q½Ñѱ §pªšõC¿+¸"@Ð×±„‹¸(ÒÅr;X—µù« ÉH–)S¤B&]!4¿‚WŒäKï:·K.¯?°~BŠ«U.NâÈ2™Ù,ýÕècùˆÅ.rô@¬O6²§c:]$ún2‹±ø5¼fá9UPqÒ|ÖôÐ%ÉE®T™Lh"aгx6 Ieœø ±éˆ¦|ÿÓO%«^¸Wqµ Ú À¶ fº6©¼‡àáèXÃ0„½7ôÕ– QØ ã°%çÜŠ­"!ÕKpÁ*d =ú`"yÞÕõ˜ŠÐ˸läxá µ›Ñ.#7ÃÈa•šäôEß–hy§=–J ¬D¸^mØ4¤Àˆ„ïDòØ-,9íPÕj^‘Á¶qU¦ªÿ#òÈ^²?þk|ˆ@#›ÊI“OÝ:ðJ€{3÷]gvÙsvf–ùà Ö8z •†Ld’Àº^™õX_5Ç`LÛt#Àî‚™·yIÝUó´9Zê»V&ÃÙY¢þC|g†êçÝØí ïr¼z0¯äÇ/_Pಳð%\j‚&¯ãõâ7à $zu¥L­ó8ß Z¡Ui«c;¶·Fkóâö7q³‘j¸Ø#7VÍb°U‹qÿ#ÏE.Êl‘ MÏ®ÌB¬À=ÍIÚIÿßbÛ ÏÐ]L¾dc4¦ùØiÀ—¥ ,‚¶‚ÉDÀð–˜eÐÎRÍ‹?Uj…Ú’Óoð ùøOãé-Øb^ßÆØiJ”à ®ˆ¤Ú•b`X‚Ÿ²€®"2h½ámJZW………SWM×·|¡åÙ³gm7BR€‚µX†°®èjç­aó(Qzr(IÀ]hËý´fWä´YÈ’ 2^Á¯Œ]iÍáÚžÛ¸=ÓÉè…^¿âW³ÏswŒñ€n†]…Ud~x¹N2bT:è*òRfq|¡—ê%\…”ödÁI÷eî\ NúªôäÉ“¶¤!¥]Žåä–’M»{m‘>úž0ª®@K28Ÿ<ìPWŒ-â².Bk¢²LµL°J/»q_ÇëtYŽÅØ ¸`É©èRï‚.ÿÄ?s ×Z©Æ‹äylú,SŸá2!Ëþ&æ‘ííÍsÒW¤ËŽ.³Ý )íVlm‰–MÑÔ¼`iÎ3P€Ã…'K¡MØmlÂIHr}Ê;&Ù$­"…è3õgæ×¾¤ eѧM~ý,1=aÀ¤®С¬: Eæ«›oÎA5 À2¬݉ڷ¾é#T[Ó“››;qÙD¾./é Y¢Zb£A:œXÄöDÏ ÍÆl³óiÉ×jê"«Û€`CaÕ|5«6ðì'¸(Œ íãËËÙ]T‚Ê{yÈÛ}Ї&úx‡¬å8Æaºªoá–Áÿý µPûfHeVy5£L–«Ï’£$2|àSQƒ–(((˜¹~&ß—t–l¼ìš ˆs87#«£:¹±¤-QuYçàë#}d²¾[ÆaS€±¥,ñJ}tÁ[ƒ\Çu}ôõKué4ç‚„”>ÆáNnÔ xa5V[7 ‘„¤Z¨epùò±ùªÈ=¤f-ö€ ZOe&´QªoÍ0h F3vÑX‘·Hä%Šúg”«fye!+1ÍÑ<ÁÓ0-¡ä"•I¼„båøŸäPëÉGèB´;:ña ²ÝwŽãÜ7¤£²¤oÇq|&¶@‹X@ó‚Õ_%™mÐæ_ÚÝ%¹ƒ;­UÈ|eÑW†ýY¡þSoÐzÃÛ ƒVÏ”•S8žã$œç&O«Ðy8óS0%A-Ñ’„¢,‡Ô µuñXúñ5´z†’E£¶@[u]ÿ(‘ÒAª5K5K0ÞiÈÐ áØ$LªÚa›…Yç­–ù[2:¡Ó»x·DÌ!ù ±ÌWÿE_Ž"¹Úanyo¨›gÐùùù£GæDçÎÉ?'&&Z}œNB ÈBT5T£û:Ѫ7bpõjLÞQ¯ ½J|%b…x‰ÚãáhâàŒ AH34›ÙgpƦ¯HºÚý^Ãk%‚9d<‹…tŽ3_ÎÀFõ ‰"‹÷MwWuñ‚×:¬3cU=99ùöíÛžÓ<9/Nä+ráE1è5îÄÎwðN Ô Ëöc||'MY»áJ=rMgè–ûÌùªù¤®¼‚ÿDý‰S'¤ÁœÃ¹ÅXܽiêyÏÌüxÄÛçÕ§bj{´/¾Ýà>î÷R- ³ÁSȳÏ S ;å#õÏ"EºTÈlŽæÕQÝ’êÖKÕKE ²kµb«R¹r•l2Ÿá9Å ÑQEÚkd‡Qi…®LY®,ÿcÕÇb_1Ù®³Ô³œ¤; ]-äû/Çò¾è€€h0ÿÇ÷ú.Ûvã |ÑIT‹Yõ¼&÷ÍÞ«f=ÝÎH*RŲ²ºª># ®a oêjêjœ‚ã|9oUù+;d¼ÍÇünèŽpƒ»‡þ4!Óµˆ¤¼§z÷å% É|õ|‡Û®™ÈTCý%¾ìƒ>tmÐœ…(Ò´kZKÜÞЧA,iû mj›Ò|ýÆX`8?ÛÕw¥Š"ß´:ª·?À–ŸP­V™µ®CГ‡¼{¸G¿|üð÷ƒ¿éRÖ˜ðôßñ»\ÓÇ%SÈbÔ16f9Ð[8€4k À€0„yÀ£ ÚŒÁ˜MØT¡%?«“üØíô2MF¯«¢É0ðrÄÎg0L!F}A¬Èä¤ù2Èè.«hG$ƒÅªBº°Š¿3¼‹ep‘8Á‘XÄžÆé¢Nåd(Æ F"HèÃqÜïàŽ=‡J.ÌQ]…U0¡ º  ªuDGšd×bíœ)·é€}ÈFvôx¯æ ‡æ²÷Tß“1 Wäü¤vÙ–I †<2…2G_RF å` ¶âÿ(ŒÀq^¾^./¶Eh I@Â:¬#W·'z6AOx 8©~æѪ«­Kˆ“4Å#þGü¸ †cx$"éËõÏ3xf†Ðƒ?á'çlqwŸÅ³ƒ0ˆÞÂFlä…4r¸6ªo8z\ †Ed!ËS™IJ+2üà· ­X’T µ§ÚS/¶UÁ²-‚ÌB’2}L€ _>ÇçQˆj‰–ä8pà þÐE b†-ÅÒã8nä‹ oì䙘IZâ„H ÁËx™lT:Ï ßßáñÞr¹„K4ì˜AŸ›>/K"uö13¦s—y™†“ä‡#¼&j~¯­û*²l]Xo¯áÚTÕT©¯´Èj½‚+¦?D5q1ˆ­Ðʸ·C»é˜þ ~qæÞ:&Bo¹jLÁšèE2—ïü“ƒaúj´"!5 aô³[mt©—ÐÛJ½RFV"9¶E&«T!¦žfçpkåå>î÷Fïú¨OsŠ¶#Œ´Ð¼ÂÝ F%¢ºRÃË è‚¯ƒ:äÛÚº­vñ•²Jaâf"SÕ(Õ¨"{Uo²žÆif}UˆØéò›X?nFDPæémÚ„ÒîÀû””/nâ:ƒêf!ë$N~‡ïÞR½U\Tå ùÇ궤€““ˆÄHDºÃ]$Ó0ueTeȦՆÿDk¡V(B¿Å·y°÷ÆÒª«Åè­% ìöѪÑr_y‰tS¸ÍQÏù2gÖr‘;ƒ$pÒ|¦® †žGJË|ºÌÇ|‡·;)Úø` ÈF¯¿û®áke-ò‘?c9!…©+ƒa¸¡Íò’æ“ÒúÂ÷C|èØ A¦™™¹jÕªaÆ…††vëÖÍÑé¢Ä#¾+ºjÕ•ƒ»Ã¦-ÃwqWŸO«o†ÛýŽâ¨£el'¦½¹‚+}ÐGo¸²JY †éd ÃG™­KyÏ÷ƒ_[´Ý€ öÕ2œ“|äï®àzÛÕKpŠº Fe¤š2Ÿ—è·‰"pféKy0ª&äæÌÄÌGAWi>SWÃ*|‹oEÊ»úP­<ú¡Ÿ’2*Gp¤3:ë W‘êèá0.H&2õEfô Ð`.æ:gù†µ ïw<Æ“¨êƒ®Ìpe0ì€j½Y+ÒP¼ˆ×a]6²=.†ÕHCÚ", E¨Þp• ’äèA1U‹¢ í4ß>C0dö¹@ “* }w4]¶B+½Õ*’²ú- †S •=|$¶BŠ¼>ÀvnÅ° 4[±5‘z«UŸˆÅà ©¦ÔÚ?œ<×CÕ5áQˆÚƒ=V¬XË°"÷qÿ3|ˆ"iË YÞƒáü,UŸ)´u˜9ßT±ª#Y¶0`#6ufa8ú¶`Ëóx^¤zNä›ÆË ÈjeUŒÊˆZ ™Ûã0‚ 2Ox²H‚CˆGüb,~Ïêc­Ú€€BC_ƒÁp ´a]âºHHu‡;ÝåLomÍ\YÕ]Ñ•WuàiúÕI–Å`¸6b¶ºûŒ[)¤Lo­HÒv`Çûx?!EV©¼™¬ FÄ_Yø¸‹™¸iƒ¸ðUÁ©{%8×q}¶õE_1ÄtUðX”•Á`4V¸•Á`”‹jœ2ñ‘tü-¹U3ž æÎmÄÆ©˜*’jŠäTÜŽBÔ]Üuô F%¦¤äþ¨àÚQÜÛ¸í&dë[bý¨Ã0W}Ë Ãx,¹Ez[lMy%Þ dl¦×ðšÜŠ–¨ŠÞ)êP ½„KŽ&ƒÁ¨ê> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000056680 00000 n 0000000182 00000 n 0000000015 00000 n 0000000161 00000 n 0000000498 00000 n 0000000282 00000 n 0000000751 00000 n 0000000730 00000 n 0000000851 00000 n 0000056655 00000 n 0000056745 00000 n 0000056873 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 56926 %%EOF ast-8.3.0/sun211_figures/simpexamp.pdf0000664000175000017500000001724213004147321014510 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\}tUÕ•GŠ^ˆÄª€ ø´J;UȽçžû¥ò@GÌbкր"Bfy!¶¥â I( 0ËÚ)]¸l««õ Ð>’å"aÔ&¯„Î º¦3 X‚dÊ3]:Ë4al>Xy¾Ü9÷ž½÷¹÷òÒiþ$±yîs÷Ù{ÿÎÞgï}S¿™ÔféIÍÿ†ÏÕ‰’oØÉG¿Ðf™禑|4Á͘e›IÝѵY®™¬q¸1Ë0“̶­YºOÛÁ fsø½¤W'˜ÆØ,SqR Ýuµð3ºkÁ )SÑ:È ç®/=âè¶|dN°‚vZèš'• Ýñ´ d*šƒŒ¿ùzB÷ÝbN ¸c*B×ñ·e¶.·wÜb9R= “@qÉñM2¸tƒOÍ‘n2-wõeÇÔÇ¥‡;àZÉM.eÀ®@ · fÀñݺ‡l™Dî[œä&áš{ÅÿKhÉ?¿ä¢˜‹Ö&ˆ³‚£e‹Sër×wpæ?Á’ŒŽ)W0&#ÒÂ4‡J G˜æŒ®8ºíÈ iÜUÈŽŽ1A Ó–€H¹öò× £ Ô†p è 4 åíÄBJw9\Çß!ȱ}¸ô$ÓíàIWãÒ!:4C:0&Ø9¾5f€-rt›Ø£L¢aW_†ä0Sº,¥8 jÂÙã ÃS*iáÐ 9Â)Bˆ<[l‘¶¡L¢a×À-—\uI,„ ÇB9xÜ M†ëÄBˆY,BÌt#!ÄL+BH«B…1ðȃHŒØS…¨E!„zÍByDÇCȵãç9x^\3z^\;/B÷Øyþœfj‘óB4ä¨óBÄÖ4"çw Ð,t^\3z^À6’‰t$„.¹ä…n@2vÅu\ÒÈaš¦ÉòI^`L3åeÉä'Ò«¦mÊSœTÂwc°=px:ÉDw] c`r,Í÷ O¢ÌàÄã–püQ'¼Á@ey_=(‡,†(xD¬ÉÛuƒ§+ˆ#Ìu“U Ó5‰”îH®ÐH]Ô+\„lè®Á‘Hã¦ÂÈqäÑI) ‰¶ÿ¼æ$qK¤…7@-䇀âÈ!S¦¬Ôà´ú.¹är‡4ßL@ε˜.ýá/óœTˆcX`/<ƒôÚÄÒä†÷×ë–ÿd ˆ/ îQ ¯€÷‹2úÑ„(Æä¹µ hÀG¿Å‘¶et10 h¿ó…3â‘ÄIP´-q4WF?H0ÝÀVÚèÕ Ò8JK)!n‡ÌΦ.kLÓÑÁ–+9äZcÙ¶äp ‘€%BÁ£9qx€‚Gs£ðƒGsâðhN2IsãÐèz݈BtàãAÑ°GÍŠB£™Qh€A¥·…†öC£ñ84š‡F7bÐÐ’4&—«4ÈQИ¦W,|lׇZÜ 1RÄPÑF('†e4¡·ìŒ4÷jÊhÄ|D~|Ež£ŒF¾Åè{”€4eű¢è@¾¢=(£‘´õ¶¢è„3šèž“m×€<t¿Ômìk-CîºEà$a`ùÀáÃ,YÁ8’¡2>ÏiÄç„”Å\χJjÄ”„^Á”…~SI =K+Àó$i5bB¤$’)‹ö ¤FZÐ Ð%Äìl,¿¢OŽ(â;Aƒë ;Á ¶â6£I†ÄÆ°"· œu8ø…«ªä¤‡Jˆ j ¸o.ÈjL³äyçŽ hÎ~7Š#sgh(Ò4ð8e5ÃÁPr ‹-%(3ŽâÈœD°HÃ=(«‘¸‚´”âvHl|S÷1 ’”Ôº¨ÛÀ¡º,¡„{À-¦¢8T¦T¦Ç?•zbDÁQI Á¡…p(©R¹Ë4t%5r-pÈõ hJ8ŠcEÁÁ2 ÷ ¤FZà ÒÛŠ‚IjèxßÏ8¦…EM—ÅÀ‰•ÐZ¬PÒƒ­U¡FU¨åÏj\ÓÃUI KÆ}¸R'(P’Š]·`G¼Òp3±t¨šh/Å&È¡éƒaG&ÜÐc Ã2ÌðŠTÂðOTh°L–ç i5Ñ å/äà$eÊl  Ô ³¨hÊ!‹ã n˜±9ÔoZ¤…G0Ö %åÔ‹ú;ÒÃÜ’Ï€L¤UOêá‰ùDbCŽ›ª&SM<ªŽ2ÆH†g—ráTƒ^ŠÒÕe¦.ŸS!6Êê©hë¬ø˜“ C**¤¹2ádƒù/š‚jó2qàå³-YæÙÐÛðîɦöÙf²T¤š,%IеÏÄö%X2ÏÐæeÒ‚V Þ(!jGpÔ C“e¾ért+ƒ^Šk2 †í^‘âäËËø~Àf˜˜ ÃvÃœqtxíRoˆ‘4‚È–U4-ô!24Ù øžÅ·+À1e¢14-pŒìqüé3¼\´©‰v­À%jœˆ6¨‰FŽM4H°\h¹Ò"˜@ ä– !nÀcË!¿¥¥8Qx ¨Ušù7¼jÐ,ß(<†…‡ëQxVð¨Òù(h;Á£ð_EàAZÁƒÒ’GáQ{ðÈ7•Gåût(|‡J¹&×TÍ3æà…TœÜ²ccÅQs[|*6¹•ˆ†ñ,DxrËýò.2æPh '2æà†spƒGÆÜ`‘1‡¢±XW(çQ–û¸‡jP jPKl¢vÈkÔ2¤hjË-î†Ý’RkÔÔÖvòm­XG@hPG 8nŸøèñ¡ž€ð‰ŒnÉ®PO Eäì ÐwÔwi‹ :ˆ¦z]q¬(>Xñãª'@-¨'@½­(>ក|O£[‡œ@kÔèñ‰Ïn­XS€h¨¦€8¡é­•¿+|¨+@x"]Z¥FÄAú…æ·à95ê@ߪ,2ê šÆÄAIÀù-îA£ÒW –(!fGjyr­pcÐD3ÝF4èà¢x‰:ˆCAwa‰!‘‰ó}iVžQ‡aÆ3›âÀ ‚G3›Áã™ÍàÑÌfðhfS4:x4³‘È[´e6ÒW˜ÑÌ·Cbã/"£¬³Õ¨ƒ336ꥰ¼ø¨Ì†h¨Ì†šXÐS±aG¼öá™v]”Ùˆƒ³ Ílä;5íàÑÌFÞ' ñ̦8VÈ[´e6ÒW˜ÑÌ·ð1cÓ‡¦„!M;B%@>|B™™ñ̆ÊcôT,³ ~,³13Ofcz,ø‹?® à7ò•5øWwª%`†œPÕÇ@Ué)#ª¼à›RK •…{¸¨aŒÇ:â`=ÏX´#`Z¼#ÐhG [ÑŽiÕ ;@ì¡:ÔB­à‘Ž n‡|­fÈshÑ›hCDr®°±¢a¦n¤bȨnqPÝqì82ŠE†ºD†fÞadT3@7Š •úàµP3~¥àw’€´G†š@Íì¡šÔB­à‘f nGƒÅ!à ®Ç‰¼H:nðwî3EŠè&uW·ü¿zŸ¿(Q²hqrã·¾ó׉’¥bY¢ä?%Jæß· ©'J.×ÚŠDÉÝ% Ü-Èûî¼³¤LÈI”,¨L}§b÷Å3sæ$-LÎØ]¶`åÐüñ]÷³©§—÷y^üëãÉ¿ýFÁ_Î?Ò2qÇÑV9O_Y´åóiç2ÛséÊöþÜÿíy™¹º«ËËU7W7W•¬,;ÑÛ8þÉ[öŽ›ulã ×l½ü‡æ½õЄýÿP»lÔ–q‰»%ï6ÚòoùgÚÂD×IêŽÃó˜h뾉öH,´u°ð•ÝON]c\õáw;ÆÖM¯=Ùºybóì«·÷Î/¸3YYZÐ{UÕØÎæƒUË»:›Wîõ:[ÚÔ÷y¹aLÏç{2¼]µKk¼鶚·3}íÚÞn/«l/KÝÒp⃢ýúò ·MY¦=X”Ú2nÔ4Ê´Á(žÃpF™v`Q¦ FíÿÞö¹7•¾ºpimáúõ] æe‡¼t²eí•÷׬߷îã¿ß¯ý<¥¥'_qnSmcmËõçžhè^Õ±ÿ½ø²QŨ¹Î”ê6ãé.–Xwñ (¿÷®»ïºËÛ>ï»ÇŠ“^ñpíãkø—Ž–ÖMí*ÚÐÖ¶üÀ÷òW[}³·©ÿ§ëÎüáÕ¢ëȽ]¾g_Áƒ÷$Ëë~\^²æ™kd¯þç5É_œ\vÇŽ#G¯ê¨›²ìŽÒý×M™×úË­ß»±þñ°õ\Wçp{¸ˆëFrâ!²ÿomy/;øYrRéËK“Û~_ûà³ÚsZÓm‡ê+6g3'½Î¬·ÈójêůÓzf£—é­Ïyûr+½Ü Ï;‘ÈÝêÕø%CÞë¹Êœw¯\q¯øeM6÷U/Xá-J{½/ i=þÇÊÁJù¸XQ’KŸðÚý¶!ñ«2¯²7Ý?tk.]ïõÏIW§+Ë~××ûã'—ým¢|çWgÜrSiºjÕèQIt—eQ캮=ÜY±¬Ç®e§^~«áWÖøŒ¹ïæäÚÙµ­E³ï8¾n`óŸ=²ö×k¯ûØã^*}ööÒƒµY爐ޗÍe³ÕC™ÃÝç+OWO;w¾ËÏ—Ÿ×ª§œ;?熚cÍs—ôøÔx¿)8ض±©+5kÊÚ™?zôšÚ‚Âr9/7¶cì';3¯ÍëøŸqvke]fqofq¶¯:3”ɤ3^¶&çyâSdãà©•2×ô¦û»Ÿ*kìžYм§ný¼Ö÷­ÙÞüÌoö_|_gî(_Õ±­¶¶°¨øƒ!£Ã×aZýýcXæEx¢jüÿz¶ó…¾‚Dé|éú“ï ®™_˜Kˆëì‹q 麅V;IÑsrÿÕiÞxÐ-i¶3’xÐ äÝ GÚúÆôÒCËÇM/~²´³ãšË¶ô–mÝñò¼³[‹: zk«ì݃‹{ÏîÊõnÛ—ëQàµy-‡G’)¼®o0÷úÐ Õ?+^×Q0núÂÉ7î5w]>f¢7ªø2ºxuÊ€LþÏjZ>œ}Ä ÐÁðß½ð_s{ß¼îÚÑ£SÉÖ3ë7umþ¿•ïûôlvÅí¿¿èà+Û¿üî×Öôü~i˧Jo]?¶hU·ßöISNû¯QóÆ -ÜP‡–1ÿ*² 71Üù¡åX³§ÿÍq¯M˜y ¾«f8Ýs57ßþ‡Ì&Ö~(Boì‘sO+ÙÏÏž=§Wüëúþ¦¦«ÃŠC´ù:ÁlÿØ1#ŸÞA°¹æHÔÆX{å¹Ô¸¦×¶N,xýõc¿:7ïìÎê;[N½öGîŸÞ›[u.ûgGïÈT‰<ñ=øݨäè¼W3˜6lÈ\ºBbWã–3\¸]lW3 6œ­Õâ:*tW¾8È®3òhpÉèÉ=Ùžc[–>µóæúÔ ©¹-íÝéŠO³•‡³ÝÙÊ¡ö'²5OU¥›žè÷*+ûûåÏžZ=íéë?{ØÊNÎÔ„/ [S§X³DÌëù‘ÕFÞÈhxŠß|êGlß‘kF½:îÎdï ç¾_zvë„Ùc¦µ.î´wgw>²««Ê®?¹ÙÛ¼d þ×Þ¾¾œ÷ùRÿšìûü…ú®6o 7+ç•åºϾ³¢«¢d…èe66M]^>óPÃÑ1“þý@ùß-+/߶ó½%;û$ܤ…lÓùÅe[¸ßaLgÃ÷Eèw˜!s˜è¼tY]xY9öp§å⻬‚?^¿ø/+kÿ?»`øæ+;MYû¤ì4uUvZ‹Ç|¹þ¦7~{Ã-§Ÿ~ÿŠó¥-Å•{[^ôö zÙ¶¶•4ol¾mia]c벇oÙS×ðüóÅ=TXZ>óòÖÇ*ܶ§µcÝÆ_¿}ð‘tn³3·)»Â[Ñؾbûäòm§Ï½;wûøs«¶‡ŠR‡I»¬ E7’¦èÕó´4Ì7˲GÒÒ0Dr×莵¼o‰wèÔÉ'Õ]»¤éyq´5h/«Œ¯ØÓâÝfm=}@|ÕŸ_ÿ¹·÷Å•‹~~óÑE"ëŸÝµy|óŒ€ú8öʸ¯­k(Ð^«½ŽM¬ŸÅ]q|-MË›fp^u6’à4¼{ÿ‡»Z¿Rþ“ÒŽ/u|²ïÊ_&Ë[‹ZËo¸ê[ízúÖÓ‹?ü·‚ô¤l{.ÝSÓ3Ð#§HØâ\¶õ¦WÔ”­xüù·¢u ÿT6æÍ¢ùlLbMñk3 Oµ-/<8©õæ­üÅÔ·&XûÏßšËfÒBJ{®åÞ•ÙL³W)ª–äƒOuŸ OC¸2K»8qµq®kÂHW ÞTæÉCr®k#ÉC8åNßôð„Ò±uÓ¯L~åxéŽÝþÜAèzX¨[ÓièÌ .öôz]5½gÓÞæÜ\o³Põlz‰ø9°2”¹šk¼\½×#XÙ¶õC^[î`ßP_¦«¹¦éGÙu•+»÷øŸ{Þ^¾.Å›Ž/+ߺ¼¸áÔ„IÂí/ã`³ãÿÓܤ©å»”LÉÈ…q´ø?®NööözK„²gÎœ9še ›Š±½£;Ãy\ùȇÆò5gñ™ªæþL壵•MÓÚ'6e7µwnÊVw·­T_ÍþWË@{»(Ñ›Ó⣺ߟC"¸šEtõü÷‘¥ïþc}.›«¯îÜ4Ø]¿®¢~}ÓÊŸ˜R¶êÈ̬?°ßllh8Õz´°`Ò„OŠ’t²îOü/Øendstream endobj 6 0 obj 5446 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:04-07:00 2013-08-20T08:42:04-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005749 00000 n 0000007319 00000 n 0000005690 00000 n 0000005551 00000 n 0000000015 00000 n 0000005531 00000 n 0000005813 00000 n 0000005854 00000 n 0000005883 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<1FC8E5948139FE4AC005C78D3B94E2D1><1FC8E5948139FE4AC005C78D3B94E2D1>] >> startxref 7489 %%EOF ast-8.3.0/sun211_figures/parallel.pdf0000664000175000017500000002431113004147321014274 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí|KŽe;ŒÜ”’)\¿¢Î”$¥Ñj`“_ïY¤˜üzß#%Æunì­Í—«&q’ýû¤ä<8“hžóÔ´Nù¹1Èòt•˜>­WéN¥ÌáÓØëÜØ[ýý)©D'%qjF6¤Á¡x«Aõ,RŒ,i‘ì‘c‹:Ž±Yþ“$o’@ÓýÃDCsòL¤™|åÏó0N“=Ln›óÆ$Ï+ÅÈÓ5”H‰IuŽVÏD*Y)g"å)5u溜:lÔ¡Çûå ˜Eê¸'láõŽÿ˜D³$7£"axr’‘òHšz¨7¶Ñ4)ÂH±Ñ¤ç•Ì:7.®Ï#¡LgõN¨2w¢Æ’´ F›!.êW¤€$êy¤ÄȢΧKÜ5þ“˜ e†™0]ÏXÐ<¡ d½Í„òa&”f‚ω“ó3ÏÛL¨ém&Ôò6jù4"GQC`oã2Êx› VñËLp|™ žrú=ÞfÂnfBo¢X˜@£ §CßV‚ôb[[ƒŠÊýe$ä_ÿþ•r…}Q`VX]‚úÓ-—#Û…ônšÓì“9î–n‹¯õ¸~W¨…+%±ôèßåŸ ó#Å(’¯ {Rk³0µØUu§…fd©* X‹—³j`L™¹ÄŽzCÓ¤sT–Ž”öhXVO>ðyÏZ[ß™ã6Ê}§¾3ØÐïüÖAhê4O5÷X7LBÔ·¹úm!êÚ!´ò˪C=µˆ0i¬ôá÷¤žÉ¡þ¬BúöÒ£ Ë[jÔ vŠö³Æ¶LRò©tõï¼Yø5éX-ÍÌT“šbU5$<ߥCš›3z}»¸÷ ­½bÊ¢ÏFE+j“ln°¾—2M¬ÿ6NÌÖE‰eU°£6·#=`Ñçû©ÚT ƒ­‘ÈòÁLAäÆ\ªç»Uƒ½LJdl¶m(;Ÿ\'£Òê»=ÃÜLVâ `ÐÌ h›wÖòhÚDQÅè¶ úaõ¡ ÿ^`×ä]zC«[œ;)N—§K’Wû~“U‹òï%X`pEÅ꿧ͅu6Šz1RŒ¼H d‚4"³Ysó|&qmÅÏÐAÍAÓú3 X®ÑµQb´k¦WÁHn¥°M€êšÃyJ;VQÁ†u:vŠ)–„FÔ˜%}A¡ÂiKlËøn¢2Y:sÄ$¨'¿SÛƪÌЙ1ÊÛ¿¼ê7•v×oÝΚĚ;1¹ T¸:ÅZq -X³+–¡3ª4/øÀÖmBˆ‹¦3D$‰0Îõ|&Ÿv¾æ¦‹íš»&ì­ÕÏ¥,pà q‰UBÅLü¹Rºª.61u‡æœº?ÔÊï­Q2;5Á} Ò Cï ^:uââ¥côÃV¸W9#f#¶pÉ&´É¬Uˆ°ÛT„À—‘IÈn3†ôê 3±k{³ ÖG÷(…eí-AÍÍõXÇ—ƒa´îš>„œª¢gá´jŸK^ëɶũfiÀø\›ô'dI`4Ÿ‚Ö(ÚjÒÚÛÖxÕvA­^ƒáëqíù]c,Pít9«º?çU)¼¤‰Ÿ, Ëu40ú‹ùUký_A#`Ê”Á.UdÍÎ!OÓA¤Š²÷Êý|.ôgŽß}bÂ!#¡ôKq"ÙzI2Ïm«H¾V?ü®aNmfÚ’4H×ö)Òµ½Eº¶—H×ö)Ò°_ú%ÒG¤·H†H×þéÚn‘ÞH×[¤×K¤ë|‹t—H‘Ü"]ç-Òë%Òë-Ò-½Dº•K¤¶H ºH·üéö|Šôz‰t/‘V·H‘®ãC¤k¿D¾Eú0ÿˆ´×"íP"]ç[¤×‡H·t‹tËG¤õ{‹´ ‹4JÝ"½>Dš­‘V\¤¼Dºaâ lÍ–6·°S=Øšî2ÁàœJÁ¢s"µöˆ¨ÀŒ‘-õ1žÖÉœ“cÊ΂ií ¹a (9ù hòdžÌèIÛ”¶~¹-Ý,»hõ6ÖVÿ";lÜݸîÜž¦ø[½@ÅíNî+L Zç:i[ *…†Æ4òZÙY6 uÄÑÚ¢¬Œn~qJX$³·ØdÖ¿ªRœ§FAl(ÔVtãêâæý ‚]=‡¨b?FÐL–Çe7ãÒ¨·IÞíט'GÚ¶7ÀL œC3r(IBÒ%¬æY3Wõ-J0s'{½Ð²üDÎÊnö•×Ö³«-ˆ€ÉƣʰgÑù=Ž4£æÕ4<”5ª?= JÛhæ<ß00"åÀĬjô„•›ƒŸ€f¾b*t8é®þÚ>Gö©þ$h¼¦¸ÊŸ(Fߥü\{üØvŸºOh]œ*84ÌÊÞ¨‹\¯öªefë]D1ûÙ\u3Y—ïÌH7S÷õìåPÀSŽúífµŽÝ%[DÖÑú¯K´&wĵ‘*bxN¤^ À±ÂÑ’‹«`.ÝnüÖêµKGΪ•C«/}SFÒ~²Â;U“”Ô7F–…¼)4|Û²Þ—©¹1ëÁcV_÷vŠY½°¸Ôƒ?½sÇ:Œ.ÜÛnB»ØÜ„›™Á-§Q&q_Ñ$6±ëÙg°î¦ÿ ùѱ¬´ã7|\WGBˆÏê{š6P¸6b£“$ë‘«[,ÔH±5C¤x¶HLV¹XEw[¬së›õO—Ñ4ÊCÆ電Ю„Mº }É¢|l·¬¥GûLTYµ‰"0«"y^W\Ea½£´í`–hh ß!ã½ôÌq›®r–AÛ XK–y bÎT4ŠÉÍÝVÓY0’ÜVHÑ*ˆÞ+ FRå,P>ьΥ#™%9œ•X/ˆ««fÌ&¸õÀ•þµ`¶è!ýM‚:Ür¤cÏç"Í#Ú®T[/0Ã&Cs»²žÝLtÖµ%d[å|lœt]®‚DEÇ|ëb7¬~‘‡ä|Ôw¨ðO&p¿ØC‘€Ñ>ùTôêY¢Nƒ+Ê{D>Ê):i¡ûû¤`aenè<©š©©Ñg@ôʈûùºzÎM=ùÁ§ ÜdGûü ×’~êÕh«Û‘Ý×ÂImRDƥߔ0—9~ŠÑ˜9ToŒPÛÖº ëçÜ+–yŸ_øÛËöiéªcY“Ó…„ÒœY‹©,DlD5ê;¦+³øžcæ%?£@Çzši^+)Z‰êp3nïõÕ—e¸›ÇEsDíÕÚSÄbÁʻ簺S´º…kéœ-ZõQ I-ŽAÇ,ÎBh‚ë‰ç®úõ—Û3´Y}n¾\øq{l§Yj¨áZÿ×3Ü3E3žÚw:}=e[Á$ÀÎÆCØ)$á‘9“IS2z ÈÅ46ŒQìÝ5+Æ8îg[è:ã\Ʊqè{Ÿ :Ãá[´ê[„8ªÁïíKdJ’‡9ßH¹‘’±{‰ÚŠÑ¦y¬‚¿ªHò¹uë¡©‚²TΠ‡*XÇ2¨H…7“iHéGŠ" EîWG¹sò5†)@1eÒïßÓœWî@ Rd-yÝcùQŸ&”3÷Ty0(/…m¢ áÜ+$â“vÍEÑ¢¢…‹È'R'™gQ(®œªA(‚À;€þìŠNd-uQaOPníŠMÔLwnÃ;7ÚÖX‚I=4?½C(c+åb HK`º,ižØ°D€‚–ag€BLHVßm"Dó«1@‘`ãy zˆA˾ ŠcdÅÖõÀt.ôää€Ã4ïòŽ¡ðž{ŠG( B† o hµ–Tc|‚±ÔLBoËF´DŸñ l œ‚\bÓÛúdàWPMäg}"BÑ4Çu÷‡zÑ]m Q$Ñ aˆÂ Ú1Øæ!ŠÒ¨(VVà˜~/ †(’¼ÎVcv "å-¤e2ŠprÀ™… ÛÒvå°1RÄ8S€ÃDÛYAáìÚ¦tW›°»öþº}ÿ#oñ¸¶uÓd=ág|úÆôòd‘0r$mªàoF*<ëà<–K„Èð¢ŽÓ_8œi¡îÑï¹Ì±Cþ{ôtÒÌ#£dŽ~ô T¸ 8³‡®HKN¾³±²>òTÌ¥|‡\;\ÇKTÄ“>öv$¶ö^G ÷ɸȥ„»ª‹•4IœË×tö…È6§$Ç©`èq@í5S—È:*’煮H­ª~@ªÅ¾# !On“&A=èlÖ~ñ­Ô/™ÜÕ7‰C%'¼Í“dÖ É¢žÂ`E’‡n+x†ÎÔv‚ƒLh«<óÐ"TÑyÌ!6ôÌ'ÙýCæršþôHE 'ô´'lñé)æ)uÝ T®áøoth7SŒf…¦ËÁ³…°z˜bÈ «:ÁÇ(Bõ …b§üBOn¦Í“‹œ’Ø:Ò]ÃÁÍܸтËÚtfë«G(ø{(ˆ<>1a²Žzê,b©ñ ÑlúþkÇ'O¢…ë„~8Ç<<hpy$Ñ•щÁÀMcp‚róÈY57Ù'UHñUoL*9zùÍN€›ÀcúüAJ (z²S¶^Rø \Ù L à¥þOk•I €¸„ºB¸’“;ÓÁ0|¢_®ï¨ÄÈrY=±–Ðe.K§šÆ’ahcz’‚Áس:–Sùú mϸD€— Ú<ÆvÇ¿EÐÑ£‡-ô3Äcü½CBKM"Ì ›Ÿóâ="£ñíD$”ÐH H¡¸>èîÀäQ†àœ®2#&±Üûõl’<<ØÔ¥ óäWnEg2®¹X@ʃ£öWBÆdBJŸºÒ¡Ë ?4z†îÌ3 ÃÞÉ YØ°A»²Bm p±ƒ`$ å>îN¥¬{Q€ß“¡Ðd <ÈŸ!èk”Ÿ7 ª¢Éªã™0ô3è³Á³ä]$¢Ÿ‡ño®•æ#sCöœ~ô“auh ¿•‡¾«0í£û0¨-¡‚6?¢VA¥1FÖèO°B[[ßM›G¿rTž3l“ q—Âô wÞÒÝ…Lm‘·ýl>NÏ Xu, U ²K!ؤdÓŽ9þBi‰ 6U ‘š<‰™±ño ^*ÉØlŒª»167¼8P]:·À&Þ×È<ªcåZn-E[Ábì^Y˜§ïÁµ ë^C›w~Ö~MB¼öPõ[þlsÒ…’áqDÀ³0øEÈC[+ôغsîV¿Ã9‚óÄ…?’Ð17ð›ÀDf@ÈQõ+^¨äË-]écÑÑR¤Î oÙW¶’ðÓÌG‰àòuªç; 7­/ÙÏcÒÊÌqx$™ía N:=î n >:”˜Ä#EëWœvˆ¼:½z¾û:륦¸ |Rœ.yÉ:Kº Üܺs'+¯WQ».]PküÎqÐÆ¡ užþÒ«Sç× Hèó=Ïg>š–uX ÅM`Á'nãh+w'KG–q·ÝÆðeo&$?íL#>Swó$8;ÌÍJ½`½ÜNñ«v8£}–© Ð^§üÆÅþn¢Â½PÓÒ¬~§hëÒ ØÒͼ®òÚb^õ»½ßÇpkU7÷äjû&0)†x¿4´`×yO^À-{ó§Æ¹ÐèݾçàœëùL>e¼æfIn@:yÎæo_~¸æ$ÄMà2ã’qáv%÷Ë“½¯›Àc~šUð7ÞV|Æ톟fœë¯ë2«¶YExÌ*A7«peý6«è0ßfÕF: œ_fÕ-â3·Y5ÓeV l³Jp›UðOo³jæÛ¬šùmVá¼ðeVÍ~™UÛ¬šý2«p÷2«fù0«0˜Ë¬šéeV±¿Ç¬ÜfïçÜfÜM۬⣗Yu˜Ì*¯?Ì*‡2«f~™U Èˬâû çs;f³JÐÍ*”ºÌ*ÄÝ^f[=f•æf•ƒÛ¬úxþý©W*^¤ÒëIã'ú£À!@xœIÿû¤,½ò„eŽÐ=I¯=5ýÉñï/åyöÈ‘üq¯¨!ðˆ÷ávJÕKQÃâ¡Û¼Ûl%¼;Gô2jø‡^Ê>äQü);¬³¯áoÊ!ê¯ÇCƒ*þ„¸=þ˜2<5¥GñšsÅS~v îrÄkb*uRÞSÆÛàŒÑ#;ã=cz Þì”x Ïeµû³¥!Í}?cò~rh>œ§ [¤ ¥×þTƒpÄþ†×ÞD/NõòÔð‡ÏRþ—^äšRídÎô÷]AQ½ˆ;@žÒÇ[ÖÅ>¥¬ö+­åy\íÆ3­'%Í=û¼T¤8wútï´æµ|ÑI×¢“qçPùü²“âïiëxõ´o´fÙjwŽê½ô6Ž÷SwŠ¿°ºkðXwûÖ݋ȽŒ>Æ!ö TÆjz"ŒèŠaç™ÍW’ž\p¢Oûy¼Íý>ÞIYŸüÙ)üÙämþl=úâÏ~o§øÓv›2þôÝnq?Ž·©»s8õ£†Àûẓ2Þüñ§ïΨÚ'"Çî÷xóç~oÓ^Þ76vž½ªoþ¼œèÓêR ‡?‘rø³ÆÜsÑKí”7Î’ü‰”7Ðoב²ÞìyÒ›=Ž/öì"~TÐ[8ÜY¡½‚ý´hŒÉñáÎÎ}Œ>FñâäA‚á] lî<éƒ;'ÌdKýÖn=^nÞÚm§„.;¥ÞÚ­²î|i7¾bw½K-î̼óùì9)ÒMôÆûûһŭÝ@"ÖsíÈ­˜k··v‹”ÐMQC¼@mlí¶{á)»—^Ãç8È<ôª‡¬C»•² ø7öƒÚΟÚÿI¹í.åÌ8Êm§¬Oö|(·Íž­Ü6{^Êmk+·âªi&ÞõŒr â†r â‡r |”ÛNoöÄËŸ{Tí“=žrú=Þ칕Û&ýVn›=›;ÏVnÁžcÚ»té6ÿué¶HÙšl—úÐmÁž£Û‚=oÝÃ:ºm§¬7w\smÊÝ´ Ýæ´Ýðè¶H Íä„æÚcÚº-:±cŽ>z Ÿ£x1çè¶`Î!ÁfÎÖmÎœ—jû—¯ÿŸ7 ’endstream endobj 6 0 obj 8052 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:04-07:00 2013-08-20T08:42:04-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000008347 00000 n 0000009917 00000 n 0000008288 00000 n 0000008157 00000 n 0000000015 00000 n 0000008137 00000 n 0000008411 00000 n 0000008452 00000 n 0000008481 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<2AE6C2B6235B8E63EA42ADDA62FF98C1><2AE6C2B6235B8E63EA42ADDA62FF98C1>] >> startxref 10087 %%EOF ast-8.3.0/sun211_figures/mapping.pdf0000664000175000017500000001751513004147321014143 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\}p]Åu7ØØæǦ¬!Pn;Ó¦CñÓݽw¿‚嘦q]0”´fld! Ç;6 ¶‚-LÒISR7Î4I‹hdb@&#Z°U™¦IÚ™AÁbp°¬h¯TšV²@²t{ÎÙÝ{ï{’ÒªIi-{üÎyûq>~çìÙ½{u_YâûKc¡úTp÷ç aQÈ8Qpw«8**0.dш 1ãD+F"àR;Úð¢@:ÔE–Ñ[ Œ™2NpxYJû¿3¥Ý¬0†ãÄ10bƒc8N¤ð?ø1#†CðÀÏêé-/™ç4¼ìžãuóczÚϺ¥ðé« Í"•FÁXÄ"¸1ÇÑÒšYû"-bA*;Íó| RI“ÚŽÃÂÐÒnÌŒ¶³¢Y,G„Æ©ä9q$‹,Ö3RŽf1³*ZÌâ$ó4‹•Ýs¼n~LOûYÉ,:ئù=ø÷™Büîÿ›¨ÂD÷n)Ü—"ŽñÛxŠÂå9 9ÓV묗çÜSØÜ‹|/œŒ66&¶‘c9 0ëÍàŒdÎ) ³¶)'Šñ®ÂØÒ‚ø0ºB¢1‚dHþH[8ÿøRÚÎ=‡iƒ¤#0Å,íæp4ôðRø^J?B…>n„5“lFy#:C¤m¸ 4†Ïç‡jÀ¡2tD=Yݘr29„å|”qÊ}d\Ž¡ÑH“æ!ô‘×+×Îsиˆ)gƒÆ'ŒYÛy:óOÖÂZ?ÁÓ¹œh9ºÜ=ºÜ;ºÒ9ºÜ7ºÜ5ÙðÖ5¤¿&ÏXý¥É[¤!mcÐ3_àgMߦÌ52u™º&åLrœÆ52ï 9¥kä$×È ×È ×ÈI®‘®‘®‘“\#Ê]#Ê]#*]#Ê]#Ê]#+\Cv9×(g»œk¬íò®‘ù¡œkDeb3•yÍT¦51uVÚ­ài¦ÒäV‘Õ$·¦ÌÚe›d;Z8c¸Z!Íh °I[ÄÜÑv„ŒöÙ&å¸|”ŽàòU:GšÑR)'•ÒP©‡]N+š®Ìgº2Áº6U:•!c*#ÆTŒ˜:^¼c²8ðŽ)¯PÖ.å8´{“øhðFËâÅ›5máÌîGHéО#Êý"ÊÝ"*½"Ê"Ê}R/º2\te´èÊ`ñ>)((©ä^i¢€ƒHŒõ÷Çת×Þìøìλ Õ U¡ú“¼ Õ¿iMÀ Õ×ob…°¶Pý‰ê5k>äM×^[½.X ߬ÙÞ°³ñÞÏA—ë®+¬½>øÍŽ÷oY¸®åèÑžžäð§âÑÝëýÁ½úܼš…ßYÜ bJmÅéxŒÅ¢s’˜R£˜2ž˜R;1Ÿ=ÿªÁ®…K.®ZÙròÝ›±”ãí;{_[¼—þ¨ê¶·^k_öð¶Eø³ôö¾§®o:oÞòTté,Cu?½è’,<#Ñ¥ý;_Þ¿¾kðÎç·Ýºò™ŽR&ã{¯æ\0¾¨ïò˾ô^xü[ýô79562–œJ’Îñ h6AëÀòÍI{²ùø±žm¯×>óÍ ^ù§b×¾±K_¸õ£ð£·-ª¿½ï¡‡^’÷‹JýiRn*øH5s¿(§ÜcGùÀíU-W\œºâW¿ýÎŽ3C}ÝÿyÓWw^üleðÆŽªñ§?œ<ùß`ª®§îOì{kEp&ùâây_ôÒGÆJ¯ySÉŽñ5IúÈ ôšÏ@úÈ8é[»j6.[ü±ë†Æ~òòöÖÞŽ'oþXóÔ2þüƒãƒcbþŠÞ=#½{’=#ã#½gΟxYµ‹£h£§Tüš ÚÃÿ±çv.üòÒ»î_úk×,ß]3¸ÿÄÕóþëàC/>ܺúØ‚ªÝŸT­ßzei¿zyûÚ¿[¿vl㚶Ѻ¶Úë’Ña§Dçü{dcçØHÝÙ¤¶³´sàTmÏöwwÕ=E_Ûv §þ¡—.`õ}íÁÝw|æù;o»ñ¢?™?xWÍÝo^ç5ö# WP¶©iãFŠÿMÜ°l±Þ}ã²—]ØÕßõöW,¨ê_xËW.yò•§?\*õ”’ºöd¨l'©€qßÜ9ž@æíxãóÉÙžÆ]g{êŸy­öÀÅßìûÒæž+ö/ùa¦rÏmžm>wàÕû/¸}ð«uåcÖ«#lü…ž&D‚tœ ª"átìüñtýئº“S'«ö‰†%?|¸ äZ¶ÿÌ{Èy“½ÞÔÔ ‰øèñ“'Ê [º#sš˜•+7OC7©§‘œÏÿB϶cm÷z£±íȉM[ÛT­Æø¨¿à{ß®9ò×TÝZ§8qç¥óËÒV®²Í\.m#!gym›ß"Ánø—x$U<—‘¤âhv#)·KŠ¸ÿÏm”¢(Žçê#¯FÌæì†/Î/z:o̾½RD5á/ýfÉLwz2ûvKRïÜÜ.E*œVô9¹_Š”bseÃéi?7vL‘žö lvo™Â"u°µÀDÄŠ!ì\E\Ôø„† ΋xŒ)D«(ÁÃb˜ªÇ hÆ‹…AõbÄñ¹‹%/j-‹1§ë"±ÐE•q˜¤^ZÁ,ô˜'ã"úšÆø00YwÐnZ¼çr/Ì’2õ©µšDAãÐr@ ÎR̯‹L[-@¢”–Q1T¤„gÀôPœ­žº…(3D«°h8 sS $iz’kVT:¥LH6TÂ?ÕŠA|*yL,㙨¨ñ\Ä™)ÉŠ±d4¼ãS”¶‡™bì›dQrC=´†dAŒÁÖaÞ 4)<‡L–Á>¾£‚Ä*00I#ºTA0¼o ºMã}Ißc{¼ç¥À‚FJvA*g"½·ƒáÉŠx`* ‹Q”swÊ Ùj©'QÔ1+âz™ŽY`‘áˆPø¤“”FÒbñȵÁ‘J…¦0ØØ€]è!£›ÈhÅÖSNlU*ò”Tîj8*$¹$'-Ý÷B£x“¨Z†N43tRT¤Nâ-"5H„78@¢õ"Œ0Xa’8E)ƒ )ÁŸ^TPaÉ” aá#¢×ÂN HЕÆ Ž²a¥*2žâ q¢cCwf × ±¢ñrZäð–×ql;AC G ža) SêH":³ta†SpZ½aCû«3Š"’£§61J m’¬ÈAL(ÖãšS™ÈØK C°±ÎJ O#FŒõ¬o¡ 2ìÁ¬S¾Ç‹oV@QQág¾æS“ûl»RS v(;v3 ,däH;°á)­µ°w‚Òh®lGBŠ×6—§g¤Ò<£Ò ›`¾†=@œA-ÈšäFKÀbàÅ1t³*B«JôhWgÇú¤4Z/$æ[0ì [;‚V*ëb$CLg6!à:p2Š¢h˜ jÑK†ñ4$ÌÔ¬àwI•SócB·e$y Û:dbjŽík Dg!O4jš¶@ÄPúŠ À¢ ‘âZ$µS†Kh`çQL› €8‰óSèHÓi ¼ÙAhãÕœ0Îm÷X“azV‚)¿8iˆ}ŠOfÂhOPt \²q¾VGŠ7 p]();X€Â:Ni2³«©o!¡Ý,£E !%e@b±.µð™Íñ&ƘÑFæ5…‰H=J3 ¾ÆÐ QlT,*91˜ÜÂ(OKÜÓ¨(:ÅäZHA€Æ´e ¦]jEJC\`œ48’AShP,‘€d¤ †K3 íÍš”RJ‡Í-%ârŠ²¡¸K“ã4\¸Ï˜6ld õ0yLyÆŒ¨`òx1vùÉ! ÓÏ·Àâ‚D`CÂÀ­MD$.u-h)–K†…”P²ôèôÉ(ÔJZØ0N#L .(“FdFR"D !G(b@X2N½éYZSrUQA ¢2··qfAAó9 ‚]@k+¡•ì"¢”F]V¹ØÒ©pŸ5–iÒZPù¤A½¸ u8µ·‰Rš¬Ùõ̵ ç.v5$B;{[p–ƒ¯°æÁm`¨<¸ ®äeàÆ¢"nƒµ7)¸‘Ê›Hn\ùsàFÁÊÀíÎÆè¸=eÁmtTn£Y núœ›È Ü`³ÜxY8nŽ·[ËÀÍC+Ï·ÀôìÀMDnKZpC?“7Œl*ÀíôÉà¯M¸Qì ÜDeàÆê¯ Üxí7n²tî9pÓ¸í|΂†çÁMv)7l eÜ ¯ôà¦Ï)¸-eÁM½rà¦qËÁ3çÁMÎóà¶D¸yu çÞÀ@0[Éa%å€KpÃFAÕ;pl! Ü­øá!,?XŽC,i9¾ë”Fµ`AŠX¾…¡B e³„3-µ5)h €Ä‚ÇñE7¡.ÚÊ‹=ƒú±Š¶JŠã°PÉH»q0-s³ á$ÀqqŽ ¿4TióëCܘÓüPÑŽ )Oà>ÀÅ›9 9Ò In_ï­jF¢_±Xô™fè·_àÄØäD6 DÖÐw”$A&›w:ƒ¢Õ én5ƒøÂýUĨj‰á&Ú×É@C¾¹j8°È™\ ÎÒÔÌ87 …LB–çYBat1Ý`’`2ïÁ”a}k 7“(ïA|7&;Éà,²Ç<ÒŽ°G8l¤ÓRŸ:*[[ô2Èï¡«€18a/G®q4öÇ·rò-ðk@¯¤îHàÙJEéYFƒ#a<+ðã ¿°©ÄDžÓÞ3HJ¼¬.Ù$*ÕB_Å)~aåK0,gƒIƒ5¿ ^"!Þñ[åå.ŸyaWIû4ó‚9í Ó‚Ù}$)44Ìéwydj¢ÓÜ Giî<@½iwx):C–«ë Ck\to+!†97èN!穈Fä:¶tTˆû;¤8‡-å)E;j #›í´{‰ŽsçZÔ†Ž_€Ùµˆ£Àœ Ehðêãí|‘·T(k€úJuxŽ—Ò¸l“‰ˆàÇaA´BµFÎã ,n˜"Ÿ;ñþ?ÖøÚÖø@3{P¨iã hû¢Œp¯_À:&€DÚmÔ)†åh<ܳS8ŽŽÀŒ?ñ‚CÜšc͇Ç7¤ƒ°¥@h†û-Üñc~±·‡,Ô‹ ãJ:} Ѳ± í^h­‚±ûTÁ¢ƒ1›_8î¶aÈ0µ9u¨2Œ†§^@ƒ1:ýg<Õˆ­jÆî%fd®íÖ';ODH,×”ئÜą̀ dz¢BÆW¸C“v2OW)¤:Š±Æt^Dª@àÂÎÕL8%®jÀqt‰N3Êõ@Ǹ¦ÙÁ!‘ýLØåäúr w¨Ái`‡Ô´aĶð íêb*€ÆF•ykC+QÊ LÏì9… –vÀíêBØÄM9LÒ.-LO›rã¥W¶HTxheà]C·Xw1ã¾àvãH®ÆÏ€[¡;Rùø°ƒÅ!eV*å”'ì*ט1 4hAD½yD©Åå‰j GÂažkñçÞˆ#u!<™¢EÕÅ ÕHÌE$¿î´ÉøÒ·Ê`¡’‡`TœH3¢íµ´@sÐÃo¬ô¸e´0vÚi:ÅwI÷¾@ù{9ø¼Ëlŧz¦äŒßQþ‘üßþÖÒUï_ò}ã‚uµ{ó/ˆ<òÓ?oN’ñæá¤çÄ{ÕW%ÉGÖuß$éM’‘Ÿþž[1Žê놿;üÄe±ð/ïùì¦þ³ÍŸ»úLšéïÍkŒ¦Öc–Ü+0*³ºÑAÚ©cÔŒ­n¼´­?½íò>p×ö£'Çꎭê¹qü ÇöölJj岉·–t·5õŽ;>¾qCûÄéÑÞ8Ùqxgrü`[óÆžî¯]Õ9|eiý@ÿ-{“‘Ç»“þÆѺ‘¶õ¥RÇ«{;Ú&–z'ï=ÞÑTþÕƒ-ŸZ¸«¥juKÙÕ¨ÜoYÁZ¬~ÁõÌqz=ó‰Û.ÿíÓÇ&-õöO+õ–~|aÿÞÞÍmãý«&`x<kª;}0yz(iZ?ÑÑ´íí]ßþê;IS]GûHûw›¶ö-\¾»¦kÑ`NîÜ|œ6µÅgó•\²ÑP˜M)ÿ,I5¹ë)Ì@Õ=µ¬³úvJ9` Tçs 0EöMsÑïX¡:<¤7ͧ!Ç‘ôJtC®—çØ—Èa—¿(fk!ýe?"6ö±ì ì;îŽcß&Ƕ°{·¿D„Ê·…OQ¾mÖƸ iÇZ6½ÏâP8Éè!8 …‘Lú_á9Ú«ã;éÉÚÀ<öÅ{éƶ·ÌëGÄÄ·ó]+æº5¤-W6”™ü7þ £ËÉendstream endobj 6 0 obj 5617 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:03-07:00 2013-08-20T08:42:03-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005920 00000 n 0000007490 00000 n 0000005861 00000 n 0000005722 00000 n 0000000015 00000 n 0000005702 00000 n 0000005984 00000 n 0000006025 00000 n 0000006054 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 7660 %%EOF ast-8.3.0/sun211_figures/frontb_bw.pdf0000664000175000017500000020130713004147321014464 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœœ½YŽ-¹²%öŸ£ˆ<‘46ÎЧâC('”ô¡é‹«1úŽÌ¬*àáâ"-öñ†ÎÖšeËþÛWùúUð?ÿ÷¿üüõ¿üïëëÿüÿúoµˆÿh¿÷ó?Öþêµ—¯ÿç¿~ý_ÿ÷_å?b~ýÕ¯ÿíüÿÿú«|ý¯µ§ì¯ZÛüúùÿù<åÈKrƒüHî·äyä(’ä*y¿r+åŽçôAyâ9CÏ|ðœÅëwÁs^³ž³ù®=ÎsZ Ê ²Ú¶÷igëx~´¹E9 ¯ < ?›òyÍiò ¼Ïs¢á½Qñíåó©5¯©ý´'Ÿ_ç8ò.”Ÿø:]ËwµržÙ¯oõÜÛ{§|º»öÉ6´ë¾«Íó®Q$ãÛGã3£œþ]2úsLÉqîä~ž?‹äóè:ÕþXçú©~ôÉÔ{ûùÔ:¶§c\V™”ÏÔÅ1~†¤®ÁgöÓ}ué{;Ú¹¶î=M¯dÈûÜû¨£œ6Ÿ§ûÎçj,ö!ÇÎql{jìð]X”÷úu¥žæ^”®{Ï+O×nÍ¥~äœcåë,>ÍÃ9̽âÌÉóœ3q5oñûÖïçÒh¾þ|K4­»8Û×Èy×ih®³°ø-ç·#{­È^§®Ñ÷6´¡ö3}^ÎëÛ†Ó(í û<¿kŸ©ç?ü îç9ß³W9¼çœgºàtªö¨3üg¼ë'çRÛgŸ9ƒ©½îÜv&H×ވߧöØë—öí3l1·÷ÞÓ†Å5ÕÖé²X•{é:·ÅÒž¼ÎvKÏœxÎâ¾×æÀï“ÏÄ\:û hÏâœ?S×°Ím¼K{u?CÞ‹}&}Kœa e~WTʼ[v<ÓvÖÜ•ën÷šŠùà{kÅ»t.”³l‡äÓeGÆïg‹Á·ïI¹³ýå‚ï]¸¾²ß×]ÅkN?àùg+\Ù?gxñ½œuª?‡d<‡m8[-î­M2®¯Ur‡¬{ô?ÛYçâ=’ñL®ÇOùûtJ—“¹|œÌõã4nï ,9$äñ!ë™ × Ëx×’8™·dœ8ê co¡÷Žs}›ÒÎä9MSÎÎQq¼QÆIÛÔ†'ªf߃S+4ãž3X5ÍzœŠ]£Jí@«ðlDø«ðÈø}yeàwŽö‘qºªûÜæÓõȧ«î=»ì9]¥q@C™EïÅ7Nõçæ©ëwA›˜~×Y‘gø½:qrj¶nôÃêºþ¬¶º¦ž[³fõÊØè«Gã²Ï$< ÚøYj´ž­>”ÜôLh4»?)·÷ú³$Z>§ãÄiY܆sšyž  gié»&NQ;Ú|6Ù’ßrNÎÈolçh“|îmóÉ>9‡k;:Ë»gž}ûöl;ûüœ¢w,Z/=Çè(v+ÇîìÀ;Çôl1-ǺiÇå8'ê̹q4®;gÚ˜5ç·0αóûÔ.…¹×¼Ëâ°óézä‚ÓUóùìLÜ"9·Ï½ZñÜqÏ®¥çàÛ—×Î隶ríàÔÝz&Noïd´iRÔ¦Ïô^ N`¯ÓõÍãŽÍ– ù|;ò™Žgp$ŸyuŽ Ég3â{±[ß‹¬PãÐ P´fW…üH.¸W;:w»ª—;™÷Š‰ÝÚsfž×óäé“\sZÌQ‘õ¼«iïšgZøÄ>ÃÐpbóú´Qk;º<®ß:yÎ<<§·N›Ž[ûÞÀ·x8iCßÂ)t*vœ<¡öt츽è÷‰S½éwœØÒÚΩ…“œñQêpÂkýö‚“_m£–Ñ5'ÏÐ\:ª/N~]sæ0Õ ÈxΠt–N~´Ø":žmøÆ¡çSãNEôÛÐXœ5ýE5îÈgo€¦ šŽ÷+X-T!ãÞ©uZ1¦SãU0ŽSsÛÄ‘urörµ‰r>ã|O³90}r.\¿uº¢ß´ž- §5гU•Ô>N3Ç=åÌ Ÿ„¯× ‰å‘'çêã•Ño÷äÜïiùŒ9þíäüŸŸ¢+WÛ=9iÚ¦-ó=E%kõæÊS´ÀŽ¥ÞÜ`*U('^µjTׂ,iMœ–ÚMON­ªÕa£ú9´]ýØÏÞYÑ çD•~¶÷=QÑ+§iE+¶«vÙ9¯{V$íX­NÚ´[×ÓFÕi€ÕyìX¯Î‘v,7É*†æˆíØ{윴[+6ª¾+µ­$ÚxÒwiâTé» ‹¢ëŽøFë»ßèYŒGWïÄ0›ŽM»´‚!?^ÁlZ­Î¹u­fœÆZmšËš’ñK»c‡ÿâ)Zý_ëš±GÚ·\åõÑIutÂ{üvô´u%wÚº+W¿mÝ´‡µªp žå$6XÑ©3åœÞÞ {‡ÀÉS¤c‡h²—| Gî¹[4ÏCL#ÛÀgçàI.¹BÞ’a'ÛŸsêÜÔ´£@–¦Sd´ÚOu(‡ç#jî4çC%ãôíšPJO‡I®´“µ3Á&·6Wq²uuÁ Ü5Öå¡ÍÌ~+‹6³dh%C;7ºæ4S2Ú0äW*´™§v8ØÆ>íKà _$C;˜: úaöš;ÜY4Üiöí@¶Á>kê,8ï|8í«v;ØÀ:ùëÖÉßµ#òä×îˆö¬­çC‹‘ÆWa¿Ñ@ƒ ûüéz&Oþ9r=ZŸó`nH ¨Ðš mÛ¡ÚߦöQá_;* î=SÐ6¹vß"ÛãÁ Sš®Øä²sžÀ5³ÞºØFÂiPdGÁÂ8S@ÏÇ©¢=³Â¤ÓŒ2´®;*½Q]ó@Sض¯pÂë9ë´?ä—©0=CÚe¥½Ú¦Nh4ÒŽŒß·l3h7¡¾Å^z´öá’v ¶h¨àú:Û¤~Ç7ÊÚ ´Ÿ<°ÿ5Ö8ŒŽv ëá/èn¾½OÿŽk–mB\óÈÆ£Í/[‡¦µƒ 3ÝÚAÅÁšÃ²Çн8¥Ç²= Í‚ûÞ‘KjÓôhºÚÍÔ·Ïuµ€ŠýœüzNEùÿ‡'äóÚ™<ýtZb„_ù¹ö'yZòdËS‘6¤t‘ÅçtŸZ8¥—`ÑåÉ9igŽ«#žST§ ¼Ž>Qá!¬ÞÕà…8²N!ì²öÃÁZ«Nžö$ÓÃÙ¬ÿíX°'›vŽç4Ö €¦…wwØ´Ý;:îw?]uõ¹Ó=Ú‰'OlïÊxŽwnØ«!;§ÒÖ¥';î9É¥«áTñIe£†vÇŠvÚv*èÍâ&϶w;ب±½#ÖôT7zÈ»vzÎ{h—½žÑ{ЮÖÎ/q÷NVéÁ^Úzz°©ÛUyºh¶Ö¡üЮöŽϳg4Ü£hÕ>ôl{ÅÃÞ–¾¸pzOµ—:cæ*´NL•ÎÊYO…24¬¥<éÙ®ºópé9ß²xB%„o¾k`ìì´ÉÕžþ|š®‡ÆôhG ¿ëÄ€W“Ûñ‘aoÔG;çÞæ _aFÔÍuA× Èè+ïÖ$œÁaû{¥v §Aá)}†ùùâ C¦‡\;DÀö+ºZ ' dxž«ï…ý)íàüYcӪɳJÅòLR¶™ZIã<äT>Ú¿±Q;ÐŽOéYlþ¹É¿C%ö,>³¡ 1õœ˜©p™Å§{q*zNbœÅª{Ñ6Ù]géâ´÷»hÏë]8P¸PŽ/n”áQWŸTžêš«PÈ›wÇ3AqòWÉ°ù5—ê[D‹š´Å#Ï´áÕ¶­Óò¨ _tàPÆ©®±€¦vºV}U®ýô ìsy,±m…ÇýyNflïÚ5F° «4 l[ç4Þ9vy7œw¬Ÿ{êbhªâ<‰{Ò¼¬¡ùlCîGĺÓNÃ¥¿Øm ½¶ØSð2×ÅãbQkẄ©t424ÖÑÙîÑ3 굎Ø@UKj¡½š) ^Íœ|GÍàè§`?`_lr—aël:S&Õ.v8É›4f˜8­­‘¿ÊËkÕÙ|‚l/>W0 ¾­ëÛ°Ürnsœ|AQ$b1Îîƒáw´p¶1iy%é—™¾xžóL¦+]CyÛ¹ÐägG=ŒdsvÀ+Ïø†1mŽÇr¢#B&Ð*§Ì–w¼pîÐüå*¸Xaë3í¶–·Gxšbʆ\z´—"†šª:¬y€V/˜­V S)‡ú0Åzユ¤ÀBÎíå 'õ¶‹C³IÑ ˆ]뺎ãJ'þ|jî;÷ÅsîZ>ÐxP(Ëf±V¦í?w˜ú}>ÊõqP®{8êuF²B3tìʇxq•³£Á"8»…d¨óEN½3´„el’ÕîÙvem.œ¨`3–- “$C7§½»9þ~6y¦p<Šâ³9ÒÐ{š§ ¦ü££0GÃáÁ}ä\†‰ã8=àBˆóYiKv6±ÚI,3c `iL袕¿Ÿaµ¹è?¿ûdϯv±ž¦×öÌf©Ø fÍôùæÑÐÃß“ýÇ…ï0ì™-_C¾8 éB/MÙyØÙy†Eþ”³·Ì/a€üêòìB…uˆVŒ¶g7]j ÖQ—Çðq_=Ílçì›|Ž(áY¶Úöœbù4 »#•±æú†Ò,½ª@¤ã`ûú€]± ×Î#­ËÅŽ>Stzc³÷¯@dùZ„•ÓY…]b¿˜¹Â|óÒ;óѪ7üFÝšñÙtº×õuÅÓÏÁu>Sf-"_©™Ÿ—+öœˆÛý{¶’ÓgZéÀÒÉïãMé6ðâ ÙŽÇtûRt½Âu8¥^ÀÅ;e—”3µiïó-‹ÚLd3öi‹àJð9*ÑÔ!j£}ª<©šÔºØH˜>“\`\K ÿ`sà=”§€ª°BRpSTmX7ô¼BÄs9B ŽW\ª@4T’}8Ž¥Ðw¸ä膆WW-Âru5ý G§¦X]œrXÆ~õóYGä‹ #÷?ú›ýqŽñÅÐÏå £ctiXÅRÄ ž™#®+rž Jºõ øÊ^Q¾ªÀXØRëÃE&‘§pÇ’¦ŠåS}…D¾¢ÑÑÆW4Fäž+ê+°Þä}ë0ÔqEM.¬ÂG_AQ_A§ÆkSÛ‡E¶Ëtë+êuÞuX³›ðýþñ“"[ŒE- «E¾aÆ­EBQ+«^ê€Ä¥kÔ”¡ÎÃ\nÀ2S”O€(ì"±/?ŒgZŠsûÅô.§¨µ›\ä—?ô¨§qÅš=ѤµZîµsÚÖWœîá&P¶Åå!`ÌRctÄ}Å™ãI+þŠÃÞ„#ÃŒhrCIÜ9eŽ¸<§èŒ¿âãIgfå·çjS”H¢z’¸_}EÐJ©^G\^MÚx§s<^EMR‹—ÙQEº_‹µ½$›t,Ô¦¼µ‡5¡&ZêM`lM'¶…¦“›EÓI„-¤u,ØXìGÅvCEL›PSL»”UЈšÔ"lcÇì*ÞÜšP/Øò¨ài#lŠpá²& 6M*ƒÚJ[ßÕlϱ ‡Í¸ âØ¢f©_µÕ!À*—6ù6ôA‹€.~°NC´hêWzõ+¦y“R[?ÙYÁeM»Ìž&Ç>$í¡Ž…hC“?Š&]&L>—QÅZd{#*ãYåFˆm+ç0d¡ù ˆš­:by…Í@ &ì /K:@Sà„ìvgx$Õ)6zíA…Áƒ`—CNÔaç0C…é¼…½&›‹ph‘²g8è@[Oö Dv÷0Ì8å6‚+ïD…Ë/tÌÕ!`TÒÒ^çj´°¾öÝ2­º^UËÿIX¬¡­õu¢J6üµ½¶!᯶ r´m(Y¶!Îj+NÇò\˜ßQau¯œcNplX,œ±Åm *)"DÛèÅóMö„b–ìi,ë1 { x,R…Éh€å“&#Ï6<ôˆ~Ø9çƒOÏÌTl"ÊÙ%»Àd}”»‚É÷TAÐÏ? Íå¼m W¼' <,¥5Àﱺ®=o[~îy›t”€-µª`ñçÛd^BÈ‚SÆ1-¾äD t@€Ë³¨Ž¨, O¦^qt•¯©¼bRæATÅ ¡]‰ŠýtžÍùDÃëÏ–ý%TH`™Èóq‚#NåóœþR°2Ç•›$ûNì9c&5Äá”#6e´4ŠŽ Q9:x›R\€B™Å V¿žÞ•_ O[jÄéIÙ]àŒÂ`D-j'f.OwÊÎi`w¦Äù ®DüG¦s,úT:G™W„¨ °ÉvåN`/‘)龚ðÄžI8çsmNœÚ+z;ûeçÃÓù.°550-œñ„y3†~wX b= ³Ô0d Ì€Š X"Ni‚ %dɳÔÈ}úVêkоTš ¼âržv+4í;||Šðu®ipk‰t8Íi†ˆÎ=RÍË™Vjy¤T”óyk:L\aË:Ù£ã6ê£ã¸œ Åúm9¿{ÖqîX¿…óI¡Ä£ã§Åóø×s›ŽcØÖŽc,S…¤;<Û߆x„¿íôΖ–€™Fà­Bº•‚&G\Ž]ôŠà†,&¸ÎöJËTÚ†pŽ.8«U!Îßê¼ØÚ¤1c…´/;Ñ:Ž×³gZ½e°ÉÚ4UÒ*÷[™vȲ_®RQÜ>2†5[üný­öðŽ Q-n Eö°ööƳFBÓ!•“‰M2¡(¶i±>$Ú‘5axK€ÏIGÆïVy±ŽÞ˜^!= *³"; ›ŒìXµi®Á›Q¢êؾªB÷G:ö²šê5+6êàSP\‡ù¨¶ðð»4~¨2ö“tÂabØ6,@éØÿª\WùV5l)žµ:‹P€}(`Ên­ßÛewp©]®ÃWh(J:Š5o8¬Ý?ð]¨‚n õ9“#‡Õsz=¬‰ºl3÷„Ÿt`c«`½ ~b{d|¦ÓJL“æ§RºÀ¦ay'ä¤Ëb^–GÒßý@†¬™N‹Þ;mþÇ­è#A'~ƒ-ƒ‘ž…­™H߃W¨@'úzz* ì4´¬ÅM‹ Ìxåç¹×T#”íx $uÞ÷CÓ×—kHÒNi½dû[›+¿«yöÉFòÐÌ’ñ%ól¹§™,Ò²× %í4Z{Žá£aÚá›rÙá65X¤#ó¯ ÏÐEãA³o1²d/ , ÙèHck+g1d}üÖ pe@ÖÎKχ ¼ÓžŒÀ»'¬ùaœaÇGÉ(T‡ƒ»m;. XZ͉›w²(¶ù¡»K{ížh›¬8:°{†höÊä ¹£à4 Ûø…ÆŒV$¦E49°7hëL½SXµ¦VŸ³K*8Žb££ ½ê°fâ…Raq…Sg$XÕ`2VüQ‘3,s(²ÀÌ¿_17l2§sô¶¼Aاµ B7§Óq ¡tº/ïÝÖw˜æ§ßqïrêò¾©•ÁD–¥´áÁÔJëUˆ (Lƒ‰êxi6É|“xšô»è€R©±FâqŠlcXA©Ý°»)vÁÃ’& [ë‘úƒåDÕ)Sa·õRØuR˜5ÚC‚1EýC$äiÆ•|œ‡rnQ ¡ˆ3Š=­½ãš%³ý _1J!Ÿ}ÀX Ÿh:tAHˆoêÒδFôŶÊÄïG(O])8iåàzµùPG–ÑôàùJ„B¸¶KS`rÕ/š[x¦àôè‚^œœÇàŠ’Ð}]û$Óq{q"#b&iBÑ/‚¸<Áz,a—ÆADøYdNÜÄõÏM3é¶8Ÿ¯X2¹©¸9Ùk˜jÝi‹íw$3ÐN¥-öÜà…éÛ«Bu°ÏºRë™ïÖ¥é4À{Uª|ÝTÿ(ñ«j„ÐJ¯NöB¨V§™PÀ·áùJ䂳¾K{jHÝïNg eQEŒ¿)‡uteX5NJƒ¹Öm©#qeµÁààñʘ¶ø'IÁn8 ¨”;¯˜¸ÍW†áäk»rÜgB£¹rnàe|å·ÍP´^9î7žIÿ!×Ûgò½òóö¶æ+¯qûŠß+÷ÛÿM}(Mäýëç/ò#äˆA7}å~Gºì+;ò_æ„Ž˜fÖ‹J g®f}á X†(·\aGi)¹"«V¡ ›ð~ô"¼wÞ ÈIÑ rb¢ÃvâN§í,ã§òb1ýLfJ]H-34wqÇr8Cº‚B•óîXŸï$œNÔ`’|2 Ý„R:+€,ñ8ù€ ìúF Bfà‘ñ»Áû8I 1J„wÀÎD{'›;¬$}!+˜l¾ üÊBïRâywrNC£yReÁxÛÿûž7QÂÌܳ®ç-Ë´nìm›H „½0÷üÞ„Š9™—²jÕ~e†qEçP˜|à3€0H®Ÿ¨jƒœHo¢ª òI± :'šáåða¤ÐòRÃÑlHc#G!š:ÿ†­¦AÔ‘yž=¦ $´8då1³¤šž„±9e˜MB40Ý5=->úkj“+ià]¦¾jÂÉ  jm¦fAô¶Y©„Ãñ9“I¢€SQ‰I(Ý–®P¼R¼Î@¡\„pÒëÏúÓ ¥31íPŽ'ÂPM¡AZ éèÔϪõ<èmŽÇC0ô†‡;눌€«à­BÎc[vÁ„z{¶¢ÊÒ#Ú–ëjBUJ 7Š:ÓÑ™Èß Se;KŸáU¹iµá¨¬¢Náèäý^†´3}û8ä†vÚ£×"}'ðT¤Cdì/]ioÅ×l&ï˃AƒZ°[èîбœ¤O½ß€ýŽ)ÒšlÌç¦jÉaÏ@¥õÞ«qÑ3¥së]òÞÑ–h‚çô*I6Â.3EpÚÃt8 “ßúªJ{³; ï뺡ڶ ì²Qá‹’^6ÒÆhl‚Üe'LF`ä÷ø]vK<´[ì%¸[1ÂÀë#D•o`Ò½ éÄàôPZ—Ö)áŠSÑ\0n’ ÚĨ;íŠl0aÇuo7Q:°LÉÓ15áAÒq©ËŒÿúEק³úΩâN­â(ôé7r†5#ºrÜ)ÙgNBCË`³iM[E~¼3pÊ ƒ¼âþNêéýÔuB.@²'…üÔ&Bv,³N#×Hœw,£²FW!¥h|#5Žü™Œ‡Ç£dŽ»ð­tuÄc5ÆÔ§å#ª¥JÖKWChu,'!áš•iå= Eå¢S÷Y/Ý ÏëÇI›t/õ¥{áI›/ëNñòý@†_ªÝ°CU<4Ñ4i‘ÕäètRjD ÖnðM4‡éäÁaá´+ZgÕ!J˜<áSÛ:®ň‹;™Ò*˜çi´2a®FÖèÔu4ªœ±5\°öŸEaZ—¬ûÂçÈ:Ö-?óÞ¡ Å*Kœ‘®KÁBÿœdRÈøj¾÷!e‹žI›Ùßxà4ö'äôjXl§#çq*c0MÖS}’p­-ú «Ñší&°OâŠl1Á;'ÀÙEêpÒ=ü©ÂÄ)­ÑpÈAØÓôÊÉ7œT1RúAf¦6!ld²|Mßg|JâôF1öo¿)eU¤F_¦A’ôƒv¯`ÌIÁÜiÑ$9Aý]V< ÌMûã„wÓö µ,  HdÊ"¼^5¼+¸@;}Õa+þ{¥“5°‚XCa^zmÚùè/oNǵ~í û™ü~´'ï:ÏM•–'<¯|ù²âñ¿JvÒ•©­I6²yß?挠£› 4²mˆN )~ïë½ÞßXJÆ.ø|üdô0a børñÑ[êk×±_0ì¤Ç:ÈÖF¨õ/á“\Gà=ú8MærXß9˜ÌDƒÍZçÝ®2$8 &K€^Ø°GÒòhž‡Éˆh€œ*öKhÊò´<Í6)Tºˆ£­\áùVØp¼­ùªB:-ÙLÞâ¦Úi:–£¾óÒbÒ—2‚•y N¼&ÂaL¦ÅEÔ–=_q+«žâf‚·‡mu‚<’&ï­h4mªàR/é/›ó ±Çµe<$/yа­·eR·ò3ºØ„v¦£Ô„ad8hB ¹M“ÀmR‹ê˜}ª×dKq skÏKK {·É7CçnS¢T#µˆ)Mqb$ù¢Íþ¤«]OZë¦*DósŸÞ$W3ÕO'Ūv_zE»Áþ4!ÖÃt…LNDBƒy ž&É©]MÝSI+Ï©cL»1"I׫Øóhì©ÆÑmÕDšXU®¤ÙZ&P±M^àjt’~oT•ÖX.©^>¬=_¤}ŠÇ¯æxuYI¤»±TÛ¼iE¬7Pÿ$&xLŸ‚c^hR¾8ÛŠÁ2Xd¬á&êgðªµ8ÕªbFòcLM¬ÈìãÞÈÕQû%Ô±v_7úBD5ýN!VOï*$˜±<ìU4¬µP•Q›)W(0j%¥¡0ºVýâàu=‰!œÝy¦…C¯ØÉOÌÖoú0M“ëåqœÕ°”G€PÛ2GÎYXÖ<`#š±nÎéÔÓ fKC„Ë@˜vÖ<  õ8âxJM$©¦|mä‰PòÏ*e4Òªj“^R ²Š¤#A šæÄ9“Õo@~)—…Êbæ០Æü6P*L ²HëDÐ/†Iœ ?I‡ƒ_f$©Æã\h2ðÜ\ÿn 6Ó<ºÉ8F5¾œÓßd^Ð’º&m ¿Ù$ÐÀ´M ™©›$ ¸S ¬TÑ”¬Ð9ìnÓáAÁêæDA#´ò^+ð_VºÇ3ÿò••.KÖo¹‰õ¬†z`Ž(dÊdú2Ð,Z¶vÍ\BãµuÂ-tA&A ‘Øm&-󦡀x Á•ÄDê_löaº.’×먉ÏÝ¥œÆM#õ/ÆA8ê5ÂÅ‘MÕÌ#T¥‘‰îHý;X@ÆcQ|ÃOêßAª`]@Ÿú—ü êßAªeëjIÛ*•eX05I/Â6Þ›A•lk_¬ùK.ÍßAˆ¡Þö„•hZ,¡ÝqRoÃg:"Bz+YO/ÊÚÀÉ‘9ìáÀ/h?÷š×°cš“Žžg 'šæ5ñ-Y* +èÉÈqK"(RyJ¤òD‘”ßÖ€Ô1‡]£(M<˜í"1pjS‰§0Er˜=‰P¥ØÈrN‘Dh:8 y•-Å3WƹVu-OPEÈîãÌL˘ž‰p^èZ4]ƒÍ5y7`æµOKi QŠÐµÇ@Ño&þ#}Œ® ú(Ò¥Ð%â];x’RœäÌ“ˆd_] åÝšIøtíCµœ"ÌuYš[$8·§H@¶£™¶I¯ÅvWk“˜Àäæºœçº ;뛬™K…Ç\}a3Ô q“XC0`®\{èFØ»ñÀŒð2ܽ‘°|†YkÉædNX6X±eÈÛ€Ku ²’ÊnÍ{`P™~Œü€hð[õ†J¦æº¯Ý®x õG)é‚›:+ž¥¾nŸÌ %}ÎÛÕÑpòdì ¢Àudý*Ö¦*^‘AÜÁ©Ý}ÎùÆåÏ I09ðVº`[EÒxÉÿ5Šãï÷!õœU:y¡uâÍh¹È /dTFºP@Ì„.Ži!ÂPSë×^íó#š/ÿ¬NAØ}>¹pB(T¼¬Ã†[ ÌÉMVyR*`%PLÖp¶&ÜŠË@Vô+2\Çm¦šHˆr¤Š™ ½ôë=›Ø2íëSô¬Æ ù‡Gê„…u[Þ¡Ó†n!àãòàA3tÝ+äVtç3½;æ°2ý”¨mMf(~N`$OD5ÿ¸Ñ}ð¯8ZÝȲkõ+aW±Ó ŠJ2žXÈBÖ+a9#~gË:ìû<¤q‚pØ85gÙˆ$˜ӚŒEÄ>ÚÓº˜A|½|Î+†ÿPä3ÏÇ”£ ìsNU…z6í@<êY昜q›Î{E@¹ÛÃx.°ƒñlüÆa#Í ]®.ö†¨ð|ì°Dú´±mÇV§ô"?U@=³;꙽Ø)WæÓ"f­ À¦F"ßÔ^AøkíÄþiŸ <±Kkšš#ÙÀpÚyÊ[áL[š´D¨W`ƒ}´ j_L`¯Ä™81ñ3¶]Ãá6Ý×ÊBº¬ë@K(œAøšÃâ›(]€YúÀ㯼9Àíª€ ¯Ø­ÅØ˼ûw±qoÍIÄ[¶P“È(qŽlab¬0dýÔHŒUfab¬.8s}‹mqQž2Ke• %(¬ÎÔñQîcâáÍ°Ú‹’d›üH’¥îXZÙ3fÔ©H'%S‹S:\Q¬®Ù®¡N h(a±ÅM%Ï:U *„ÒØ 1Jÿ£"*Ð 3Kj¦¢•ËRËC»¯Õáߥ®:] µYÐnµ¹’œÁio‚a;¥­Ü[2‚VCj í^¾f'ú WV(U7 .®;ªÁ-¡¼%ù㕘ì$\±jB@¨fÈ©ÔÝú‰bèt 6'&C=iÎœfuÓáäe<j tƒ“” Õ±Õî¦>¯Ï­tÚé€4ô—ÉÎTuêæádj°Ü~2£&ÁO$}§ K^Y%UÉÑNþeTUþè0«ª,tª"áÄл4g`bV§q6&«ÿi„ ~  …Ÿ™t,˜4ì×Ú3ùF–S%I®ft«ÉÏÖ©Ø4šÚœ69ÜÖQL¶Š°7r»9A› 9e &/¾¿%.d]ÉÝ]PçFTˆàЪ«T[Ö0/ÀMŒ©ÃAß¿~ _2ÙN׳SœÉk¦6ÂáDDÑ•R½ –×*±¬7 &ê7_¨¡Rχ¿’¦±¿rÜÚ=)« ¬ï£ônÖ¸ Úòöï=ÝÙ½ËòoÙ£'ÜñÊNh~Ù! &›’ìßwû,û»øówQöw‘äm®W6žW'áR6©«öeÚ}\6¦à;Q@²G•¡‚R?äqÛðø½L¾6‡V¿¡Φ³‚éfg³ÚÔo¤6¸h"U ð L«²½Ó4YÜNPjÖ¶{Ä.GÏ t܃úÌ ­dÖFWb ÅÈS…;é8ûÂÝȪê$5fRˆ…Þ¥w’óDªkÉk?Ÿ<Þy\Ì›4BžS•K!ÏéKÙWÍôÇ_Í~Yˆ•jäN •ª4ÂvtÁ³ºmÝúƒp\±ö0ýÐTµ-‰ù%r#U­°AH-ªªJ.[1ç)ᑳ˜}ÖÜ}OVJ$1®¶=ÒåÊ/5TÈid¯k/$Ë®J“{פ¿âÿÕ`]½žã¦(Ç e±õ+3x-åâÞ ftòaôyN‰#Îy¡WÙ¬aª‡èˆYRQ0êA›I†y4½8' w#¬{g@÷™Ø³ÂæQ‡¢>b–‰T‰)wû¦ˆ³w&ëspܦœð“"ÝÀ5—ˆr¨g»–& ¨ˆžú×f‡LÒœwJÉë„MTdOÐÇ1ÇRT xl¶V*êkˆ£ùœ<2ž'Þ|ÇyªXá·×ð÷ÊØîÜ&*ÐïÁ­¡})¡~-Uf+錇ӥ´d±ZÛÀ$`ŽÅÞnQ€~œÓÛÚøš|”¥!½SþXò*Nð}埿È`5´¡#¶ãF¤¸Pàf¯waøÃÇ„qlv®cãä*÷=cã0f½wcß—ÙCËX…˜Ÿlîo©ÝçÀ‡.¨¡}Š$Äð¤o®wô\¶óú²“lÆE–ÜX¤•KqNvJ×ò@ú»â®0ÔÂx $æ›±’%zt4<ƒ4XW·Á!;|ÂߪÛ&Éc$îŒl“ºÄ¬äO³ÇÖÕtÂïÍx–1lhwFõâ?J%`Á,ÙÎL(p´:È*¤N[…?¶ÎÇÜ'ne…s‡¢ƒP54pÀ»†×.t†Å+-°v’N¨ÌÅ¥¨ú×£fL™äIúxþ ›À9*µŠ$¬ÆJ°Š—Ð §ë»gpxðtUÜŸ4ÄR„.7´ sàáS³S8TÁÓIdf„ (ÂÁãKšfå®ç0{Y£åî¤/ææ£uÁÜ@í¶’FÔe®˜ÅFuo‡‚’¯’ëL Ø¦Oĺœ%‹ gÃj*VWÆ&ÉÏå`wq4Žà÷çÆ“ÕMJá^mU_€¶ÃÕ`J 8TXú|§IØ.3MƒÒÈ/hË ¿>Ý€Y¡Ë@ÿ ³¢Â°Kf ñ/Æ„¡yR…²¾P¼(aØt¡l_œç<4Œ%œzŠä2ºG‰D{_”)Ü»_Ž° yN gò ‡]R8Qøå(¾l±(È BÓ¯?®¬8)4.Ù>¬™H Q>¶§§¬'¹ùr$TÑŠbÝ)Œ ËÍo€i(1™N†”ž¾W Ølý†]¿‘¨ô‹Åò¥ÚÚ(ô¡Ü<”xrÍû•Ñ`8uå/<™ Ãd*Š3÷A§«ì[׃¤H—“2nF.™¨ÌN(·ä¢‹&úuŠãUjX±9¢Bø° ¸à¾$fc#ƒÏÎÈêÆÁ°²z3ÁE»á8¢Š·aê°étí®W#¡°¾é= ;9@FfaE)Pä¨Õç’hGÞ‚îÜ ¤Æq&÷rùMc°Çä©Ð̹Š=Àl¥0:†!ïXujÙº€@æè;³á‰áH Àxf+eÐwbô¡«È¦cvûtˆÅ0ñòTuäØ‘\4*Ðòýþñƒ€øvº¨‰óGÂŒþØLY9eéH«~E$Eö)FER‰8 ËÏØëeK¿|ðúð•6$þO{Š?èvE¯$º§r(—ô뎩æ¥\V-ö¢¯'X’N8¥Ö¦Í$&ÁDñÜLìO˜ª}v¤â´g˜š{³‡öyi9éí·×z07Ñ~L<'}‚ˆ ˜Lƒ”›¦—‡.ß²¨ë¸Ëg÷ÌëáoDå˜~“@®³@{ÈÕhïÈg§”é¤ßœ/ý&)7Õ~QnšÄGdÒÒ³Z¬Éèã&Wt\šÞuÒo†I I¿©oaîf÷»XÚÌï"§¼åA3QÞ~ætÚ-§¿k½¶&ë¦Ûû-ŠNÙ•ÌËÕrd$IÓ—ÅFDÝ™µ,Hüb×˯û­'ÂTöKïÙ®?ZôžIõI¿s•ü¼´ŸozÓ~fe~ „°šƒâµd>ö/‹TýÀ²Ó„¥©ÿIz)C±+›ïŸ”¡*›Á Ë4ÿ¤•¯Ÿ¥5²èGÔLb1­¨ªv¸m$ÕzQ€²ô‡)LYäñ3It£g²~ˆË„Ô„›’}M»õ=DNêz˜>½‹D¥I`:2s°³ÂÉcrOÄ$S¤JöóŸ[ÜCòò½ÈR”ïžUU”Æ”²îNF÷’„Çã2žL °lâQy›Ôocd–+‰S›H–øÞ&€Š L÷í‡æµ©ÒãŽ3å=^­{îQëò˜ê÷·Õ=^¬‚ëùS‰¡Ñ½LõКżmÃ¥a'p¦> ÏU¸ä†©tY)7× ®_–áÇ÷þ ª¹Ú7oðz!Aª× OýùÒí^²TVÐÕÈ”‹éõ»˜þ¢gÂö™¦ä%ÌÖÔÁëÆ:sœFÓa6‘(¼æ˜ ³•³Éؼ¾DÒê=§3ÕI×1¿ÞK‘B¤3ˆ•E€Ðúi.Rô›îú²‰ž‚äE®‚~6‘+¢ÍóÓ¢eQôù“”Ë㱺²çpcI¤b.Y"Éau qMÛg Ú`XoãOôR;ZŠqÙ‹ÚYÑçZSiÆ“p Ž5{Ö»ª ›xª–¬BÌ(pÍ1zŠ‰¡¨Ù9Z=nEÄNrOQýQ/ˆjR)šØÕXÞŽQÁb÷¹\ÆKPK»F¸^Â(ÂäWpKE5¯;Hxªqˆ`èŒ&_iØ^¤dúû㯟¤Œ’Bõ(Ö¢èôÐ&ä6´°²û0î"¨Ú"5®´8RË6§Æ­,Z©&bRŒS6"ùg*FNí¬µ,8œÈWH$–kfQ‘褳JªXÆƤ~·7|fBØö™E\ùQ ÏÈD@ÞãBIäè+ƒüÈ5ƒis:JWU„™”S혠”Ã&BܬŒTˆ—°3–í:>G0ÔÁ Ί¦ñ+§ñµáé|mMAÃÙé"•­+}‚÷ïU:1t—˜.4ˆ¨œ+8M؉¹5mÕ²ŠÌ*”) 8à˜R¦}ºOV5¤Lçƒi¦óa´Ñt>•Å7'Qq¦ï‘tLrgÁÉè“îÌ|…‘¿T#!äA¼(ÄAÁœêÈ?xãìT$A˜ý‡]h¦Ð¤ñU€{åí‚{4œñ‚à–IÓDwÎgÑÒL’Àì³Ïf2¡ÄþÜö𬌺*9$³CÁ´w ¤l.ŠÊù ˆ#^y•Éν L2ý`p#:wúŠél{nÅsœ%ál|ΕsÀ ò :õï¹QQfÊ…SH„\3%²ýŒˆºÚÝTy¯Þ[y¯SÙHrg?*¾ÑÙþ°¬BôB4kï…¬}Ö©Øõíà4ö^L*ŠÍŸŠð˜õ)EÁê´  ° €éÔWré‰cøPÑN"±0ƒa&Wãt’ ‡CΧÆÃçê×þÜkcß'`o,õ‡ \no$jS)Õ‡Ç71 3Û¾¨Ö#Ï¢®ðaÏ€2<Þ&׫lÊ¢NŠP" -W%[&g'ÂÀžEü Å´¡sby`XX>h–¤Å­Åà¶T>–™™KUËÝ5 ò ÚÍ_nm^‚ĪÆP—·ÀÚÈê*—&ÌÀX™u×.÷¹ûÌÇÃÃ쳈#dzoÜüb«M\xзI´7“î&›¯–Ñ&YnBplvM²F²™óÌ 1ƒ/+´'7|à]Ó–ÛpþU°»šK’º =9šM„§uw•%B™³$=’‹”]²"upMz¸•ý-æBÔ®²ªíO2»ò/9 MNÞB;ÉþqôËmHŽÁí$r*:¥[écžîI ¹ ñ60„¿+›\× 4±X4vø™¬«çÛ]É‹ñvkÇ]÷b›yܲ ÀBe9qËEf 5lsT6Õj61Nª ‚ã°¼ö$BŸŠ¼”ëo¤8ÓÿK¨¶E÷Ý›PˆŸ¿ˆ"ÿ%ª÷4ªÞ:¶¿„Ìà!Õ üÆ1bR ƒ5¶üþ‹cžn?1 ì ßØf—Ø ¢°T‚ïÌo&¯2µKŽ#ß‹ÿp4`¶ß™ß ¥ECDujñgâžÜ+ O-¬"Ùg2'œ,ÂÿÎÓÁ7â"HÆœwOæìKIm€ßýÛmÓ lÍdD^|ÿ&„v¸÷·hµ8.…‘÷ª !„Œâ_ž•¥q¿Í£ ÍñG) UÎZ$hðª7fhÀq &f+r”C[hªÿEý‚Ú YÙq‚A8É‹øF‹¦ÿ…h8~ä-6+þ…5PæSîQ5M>I¢5¹Ø¶I¨á/*Úȧ1P $\ü K4žÎÿ`¦ Ê{`Œïvï¹_ŠÏ'q6[@Ù½…‡Vø—B9ÿ¥=:ÿð=ï)ÞYSU<~Ä mþ…À³à*ì’yÖF£bȪ¥D …œßæš…;áGeÕÌwû-Šº@ÖÙ*½YéýVqº@)pÌ*Ö{÷%*Š =ØÁÛ­ˆñ-– ’ªü¨¾¸™Ì¿Å#Wû"÷¹ŸV™?M‡7Ë’Æã¯ÂÛç(Ó)ãi¹Ct›&?VoEhôý ô 1ÇGÂ¥ ËQ.WÖøä@!œË„qŒs˜÷„‰I=Â?|¹NÄBS«ñ›™$nÑÌÖÕ´Éw‰ÀfäEkiÎ :4œ³ ÌȽýþ…ñ!¨4 æ? Ê÷É5‚ÕçšéP÷š#ÿøð&“µ"ÅÀÖŠ™–ù×äQ)=’Uxšù*~ñ… %‘8'3ï|üõó±ëu›2nÚm¨Á³“󇓢‘0£>Ò¿¢7óþ/Ø 9f¾C2½˜<1¬î³êµ'¡®g4ÐP讲õýñ×Ï߸>$ËXP@ohOÂôS–±ÐVîèâô0¢Â²´Rñ‡ÌÙ÷âdp«%ûÞH€˜eõ³Í ¹¸m ~ŒYšñ'W åç;Õø ˺žÉ¢î9Ê.3ÿ‹ç„ܱ~ΠؘóÄ}È`’ûð“ÿ„g© 9’¥‘³ Ê<µìk%ñ_–³>yTj¦Ä¨Ol$Z~ûУåzûÜÆ£åvÇHθß<-íÖ.Õ¸÷æCqÿ´—rŽó§xž`^ÏæýzžˆûeÈž­h§Ððòå”G’‹Ò€­2üÄ]S<7œ(ž±3XXaÖâ>ùà™é Öµ-N›"Tn»?Îmwª ._Ÿd΃A)ÀZE¢­P¢¿øk½ÔŒÞìð/”kõúÝFµUX§bc&Õöò˜Ý™d¿xqÎÜ:3­„|ãhm¯†Õ\бªÌ£^Ìl6½øÌ|…DHRüø‹?øv åì_è®/ɶ6 áuxüÅ»¸z,‘Ãg=ÒÛ»ÎÉûÅãS2¾\hP*_…ø1ôŒš´1o™ÈÅðØ;R»krr¹,ûI>ø@v÷\ïÉ2ú¼TÇ-µö܇‹†Êä6#êÒ‡¯z è^Þ¡óµK,`éDsÌ*Ž¦D„2¹ ¶ËpAªö Ûs÷X‰°;óg~ð­0¶Æ}2D‘mXŸ ”Œ?…oÿz á¹2_&ËáNÿúò$ÛØ:Ð'Ûs…DR&àÊ£¡‰4ãbô”uCWÃtµi0?j+ûä_B%_mdÀðN9±¥Îâ_÷—Ñ+´Q•äeºÛÐ2Eâ’o+Ü{ MýæuÊB½&s2ž…z}608¶É(¿å´`úóäreœ¨4-Wò%àï²2_í5<Óh˜Gì|ñå_”Äöfþ%Å£’©9ÿù7íªë )ˆdêäZê®ÄKôµR¬+H$íÏ…¦ÔÍZöI¥t¦½øÒpnweåà$MZ …³ô2%¡”“¡„#Ñ ¿8‘§šÿ"BZôqH|^ö#z(Â_¨%ÉúvÉsD÷ÅOr£í,ùߌF‘`Oä´]£Çä›,|ÜEôÊɉL‡²~¥¯Øþ®™Ïj¢É*ïS"•l$5mi@hÚ"™Û¾i€zš+.Ñ0D‘dŠ?i…¦ù Ì%¤Wì0sÍ’@ˆj³üp }÷Ktž¿ø’¥F;¾•U!d#ÁžrÛ3íâUºMÿCÎáaLh¸ý £Æ¨·_vŸ‘¸OmhäI´¡ã'–o·!(²²‚ðŽŒ=½˜Gƒv|5 :¹¦ý¦+Á©BÝT•Å’g½,ØpVrà<%9p€%4óͺ|7—冥(Aé‘4Û¿pÛÄå¶Y—Ûæ±4î¿"£ÂR´Ëh3/M½<6ã²×”Ë^3’½¦eë?9kvrÖ°ï”îF,®œ¸Ä‚Ùw¹_NšþrÒlã'Ûb)eû]_ö™çŽÙ^M9Ãt%ï±¢[Ã9or™Y’³‰ Öf”Ù䯅øI#Ó´¬Âf掹SšU]Ñl›?lÙÞ¹>T!%p~ úɳ̵ŸG5Ž”ùPJkÄžbvdue5—jÌ7‹¼4WDcb(_ñIìH‚ˆ5˜šl.Û¼g µ¹Æ¶¬fçÉVuxBÍ Új.à_¤,ÛdpÁèE2±,ïÙÁ¤DÇ«‰ë×µ´ªe,~ªúLu\ÿ`Wa€YHTX’—‡$~zÊ\*ßwž~ô¹vB3Š–Î#W1ûE“ò˜íž½äFnX>"V·L·`þñ#e¾Ûa@À‰!$)N×úE~2LCù›ñä1½% Õš$¡uƒUqžŒD¾BW“Ø‘Å"ñƒÅä ¢t@zþͬ (´ å"ÌæÔ]–ÐÈŠýtÕކ܉PÂ]¿÷ƒŽä4ÛÜÄâ  WóG£šFÒAÚ”(ÈØ‘‹ 1•eì,²wÄ~ô‹Wä1Éy` ÖÃÐÖã’Ãç‹]e …®¹úàO~ Ï]ÝùF[RÀ²ß!ÓéJ1Ðmh-ʺ„ų›]üc‚0âD’íÉÊ´—ô£%Fö7ÓÇÈ -æpÛ|fÍÙêrÜŠ’ q´æÎÒ3wHæ>*¬äo¶쎉×ÙG[ߢ¬aZužª^5ð·ÝPÃßØ7XøPò/Æ ŸÂ¤šeÃ2KÝ[&³†dŠ‡eºn$ÿbÐ`áCµá“5ã)YV(™2,¯t=±Ÿ™ý“CØ&èaü“X0œ£O$þÍ×™/ˆÁ•,¶ á±Äp!,—.„Ç"«…°•dÇ3×L‰ÉÂ8­Oö 2V75Ë:%K…Ú@–ŠäÀ)õ¼xènÜØËF‘üz×?9'ÌKñÉ3An }—¸%Œ9+§k µYæ– o„ÚùOÞ?gfé­ä‡P{Ä Ñ^Ù…Å¡{Å 1_YkÁ<í•ÍH"Nˆõʉÿ&'D¼²ÇHœã•ÝŸ¿x ›Ãc2‡x¾²ÛL–̾^ÙóJåC^÷S8.9}ÊëöUâÇ[œÒò¼ý¼Í5BŠl·ó“¯b´[ÌR¹#oúºÍƒýjÌí>W€î3ÞõÈYâÔ€_|L)sû;ñqç¤ g"E¸9€´óÅœ"¬˜’¸䀷;ÿ[ñ:úäÛàôZ@ÀßB:qKc†¹×žé<ÚH йÏ%æ©ßùÉç ÉG®BâÍ®ÜP¥&™nºðžPYÝG¿#ü]{À‚ £¾ø}šY“> ˆ~üõ£¬Uó!v-'·ËÿÞ“ˆ½³¾Ow§lΘøÅNò°D©ïIè®R§5yŠp¯y–DU+ÔèbÿÞ³~9‘\è7û iÍœQ´y}:Í~‘ÛTl›wnòæºl+Íeíâ•!`sI‰¨^ïúdWaí¡ÌiÁ»ÜÌ+Ëò¯¸^+’%P›Ñ°AÓ\ÏD :O!ÖErFÌ'{ ÃÓîøÂy7˜eÎ!¼"\Ž3K8Qrg5gŽT–Õ `¡€äwú`‡aIÖ<Ù ËŪÏKM‚Vo*§Ò¡$´p9]ø/œBÆI£ß1ÉÈûÍ>ƒÐb˜ó s@þ ^XLÀZ ²SE€H&Qô(ÞÂÚ óæÃX›3ê» ÆÚ§+¯ 0婉)±ÃÑß|ê X¡9†¸A3¯²,•[˜ekÍë“='Èèl]îriâåð(£ qµÀÖv–‹G×ùoM‘Èÿá<®ËÎÓA÷ÖÌOUh“¹Ÿ1v>ùaú$µS×X?ô$ %à\. ÔXäD÷6^£{ ùÒ¸#ŠÞ2ƒòƒ=ê!/Žæ›M¡"Ø y"¤Mçob΋;'€5´ÉœÎXaè6]ùè“J™,º—¥®“¾“×è^ìɦêD$ÆÙ(,óÓlü²~œ‚71ß,Ò–6Swþb¹"Çúœîäi¯@'”CÏÄœ7×'JSýfî!˜ÑtIwf»$ËêúçG¾L[¿Y·ˆa¢í÷ã2»¦H¦—·º”%Êm7–+ð"c_sŸÛwˆÿŒ[|ˆÿª ]¼—t½FÂç‹…ˆ}‡GT(–ÏcìÈÎâï†s£ Ž60sÈñf)%‡~MÈㆾ³v¨^]t¸Î1)„,8*ºhceuâçCæïjCáïjùnŠáè[àÄ?‚¦_ùáïÊLz‡ Éå°¡Š½2Ü}ò÷)ðIEäÉN™¿;#j~Èü]ú ØRídùDË¿«­½r].Nþò” WûK»2ðØ<´)Ç+?ü}HŽWf¼¸:+ëSæ5ÊÐre,ëSAE!×cdè{›Ÿ2!ñJ=à3S~¡òßåXß^÷™–úGÁ¼l3{Ræ¸Tg}}ÊúJÃü•ËífJ^¹Ü>¬„ë§\nŸWÎ=É…sÏÅßö õ/œ{Ó¢À¼äµï(,bd™}åÌ3ö•æÐM¯wî‚xˬæ¼-œo)·;· ç›æ?€o¹. ÓRR®wí€Î"×³ß Ú¬ ´ý-¹NYþÖkY\’FÁÑäµO”÷–}É4¼‡°6œ÷– Ä{ëÈx/¢Ì{TÝL½‚0iã“XÔâ€÷öH>Kï“ŒŠGÖÌå^êZ8ÜK3ˆÎ½WqøgæþÌÒ9Þ·~÷~N¬¼÷|Fè}Бè3‚A|Ÿd.ò Ã8¿³<+S·P®Ì…«@}xv3öðì0+TϬo:3 ]Æ\-ÂB\/‰Ù¢Ýh…{ú)I!!ŒeL b\Ji®Ì:­LŸ‘¾FXD¸î0Sfe"iB¬¬²„¾2Œ‚§qhAª2C1nö*É€ÃÐÞUù»îåùèBˆL«1ò¢”›¢59o];˜óVø¢Éy+LÆä¼uí^ÎÛ䈟Áƒ,”͇e˜ÿHnÅÉï_?)_ÿ2>þeÿú—ýþËõâD4¼ÿ²ï;ß«ÄŒ¡–Ú1²Íù×ýóO´—‡YÜòš'#ïο~,›•Ù ]2¢æòéHþdÍFLÉÔвõ÷Ç_?)Ëói> õ¯84Ê+¯'ïž™²bYžk³kè}¬‰­lx±hÔ¼;ÿú¹<zù2’Sƒøš{‡ÿúIÆ ·Š óƒ cçù×å-¯j§5R}7ýþí•ãÎ ÿõ“òúõ/ëã_’‹cfr_Åúê?){U«NÕùçU­•iíó_F¶¾9*ˆ¯jÍcKy–÷Ûù×OÊæÕ`u›çöukn;ÉmK}ûº)!ÊrõÝ‘¼·Á&Ni˽¾cË¿~R%gFzM;«¾%gËLoç÷Ç_?—M$r²Y|z”äí5ˈGSŒ#ùÔüë'eó¡Àzëq×b3ïä±r½ºt,×±ùJ¼ö@?ù/ë_® ò³m$舨»ÄßûWþ‹(¹È*’I±ýb2; k½ûzD!ÛzåÈ7ä_?)›C‰\CŠÀ‰\Í"Yߊš>U¶pòÅ+/ï"÷¯ŸËH¤> á0 åd$bÔS=‹Èñ0£LJM¤¼.C>ÜÔU~¯ï¿~Rö8þƒ·ÈãHÙ+/wj}³»žþÞwLÿ媖\¾Û\ËÞy ½°3¿È^XË=Ÿšý\æšžýÔ\µ@²Ù¦Äwݲ÷›Y%kec´šà.ÉnÓr„ü×OÊŠÿ‡*:>9kì½´\ï,kŽ?½…æË¢Üò b»Y9_æ2âÔœÓÍ,S¾{ýË“bfÂe– T¤ÄòÈ«ü×½Êß݉8P?í¨1•¬¸›ÙÀôE, æè, ¬6‰%Lm„¹Õ9×Vþõ“²ytX¢Xg˜yÅÆ++âDtb0ªŽH6׹ǤsY?Í!$9[‘ý¤œ eë""ÄV¦¸™Ëô6¤Û^æ2"%â•[º»—߶•H÷sù‹JÞѦ9Ê(»Ý93þy÷¼U’åèɯkF$XÞÙö ³—ì–,tÂ÷Ç_?êcfy»ïÛòèRöœf²arÀÕd­·l^6–‰–³Ä%Ô-÷|3Ù–VË9Ù–Ùá({…wqyw…×q™¥Š²Gç½~~½\JÄ÷ QšÍc´oêWÂ:µÿæÛkd —þÌàÍÜQ’så_?–ûv]ÇeÍÜ×?d=•h¯1úÅ+{e£¬]ÓLó•½g0QÎìZJ¾ËÖå_?)w?‰)}~ñJû•=?™>èy+þÀö!«sòÛ0Í*x‚Í3‰;\ !åžw7ùÿ~7eÏbF&<‹éE6G!äÇ|ˆâêz²gÚcM@rÏžlò¶°‡›ñ6’[ÎÏüëçÊw¬Ú㙎xÓíC^9æ/€­½¾²Ùá¥ÆmMÉT)ïœí1ŠgšŠ•}_ž°‘sûå ûuë²J×[eVæYÉQ/¤P}^”Q5ò„rV¹a½+£’fà§ì{?Y/kRç§ìyxÿ"yA\ìžx2'g¦0,‹˜>½¸sSqÜÂÈhË3ÇÙŒRÓh¤œ« žõ"4f[”¸ø¼ø¨Ée*ó#šK˜¼]‰Íý|j].¸ñc²¯’¬'©tv2*2iz¾²Ö s‰è6òø/öŽËŒ^.&9yÿú1–ÙF—ç~^YÚ1ãë%Ñ}L¬Y¯ll£¸—CD뤹J6~“¥I²†Ùs1æ–gdÙh㣙Î~׿ÿú¹²GÄû‚QŒ$þÒŽ^. ßþ6¼/·)¹æ»“¿osL[nù6Óýãm˜oÏ8&mÙH2”­ÛÛ—SÄd%Ç*ÜK–WŽg”ÄIâkÔK–g΋p¿0&U]§RòÇ,$U¼gaKŠ™5«Aþºƒ´ÝºuHÍë; •b‡Û/ÖQ›Â÷ûÇOò}2™9÷DOzkÁèG¢AþíË»ИÞ$$êaÕá ÑÜÉ@xgõ¡T;ù%ëL’¨†‰>É1ðýñ×Ï• D-Y&Gé†ß…­»IKµÌIZšpRt°Ë”RöÒ& —<ÂN5K„ÎK„ŠVDÍdÊ‘-Š,Šp]Í–FB!Þ¿ƒb€âhšÚŽÃ ÖUÁëöÊÓÃ…Ö%À­óAyìÒÈT²+‚,5´#‹È½½%N+$+QZÕb•J¢0• 6jMA2¡> 6.^JúqEVA!#^‹éX\vgæJ7ƒÄÈ©à?Ð[È×qÅÙºÍéÀâ³Öƒ0&Vƒ$‘ *=µ}½'Ç-þ‹áÞFUC4¨Ú‹Îƒ†ÎS|ÇrÍ‹¢¦çý÷UèúçÉ×F5ž˜õûöm$+³¿òÎO2^†_‰½®Ì¾»ýeF]ËÆa#~Ùs|™vÅð›5q±'>[ò|‡ŸEß=þaTvyÙx9"«è’û3Ë$¸zþå©(ôÔéÀ¾ÿI‹´.ÍA„•Uñýþ«Ïô¶†m>ë @tõã³.ƒ˜QFڌĠãpIdd‰I#Çr88Æ+ê#AÇáŠÉ`’{ Ž‹ÇÅO?†7CÜÙbÿñ#¸µí rsÈ ËU¥«Éf,?Ia¥Éüô«ôJ4ÅÌÆlKØ2Bc¢eè'™-»_7Sìg¶!Œ¦¿c{Ç$ì?)äH–·Q cß‹R<çŽäNæDs÷Pvbc´§‡Ì¨-û¸%³¿>G¤'sì·Õ‹lm,Òm¦{ÕÊÐ#ÏŒ]FŽŸÕâ²®Øö…[°h(7¸Lô–ØðBÎ?ðäGk£‚¾gÔ=;(ò¸Z7EÏA£¢—ôptBÓG=/”r²!ò½˜ Ê”+Cmd#Š×É-eÊëMI-¹¹?rÿy7€vvT}KŒ„]¤ðŽü~Ê7éÑÄÕìW³»L\Í^4X=vˆ²«F|È+‡Ë¬Åƒìä²kŒ@“è“T…?ûæ}Âçø#¼»¹á Ï,#¾QB΀ï³t–“HÏÊYYH79f˜.*‡§Dg™îæª-„æ •Á|R9MYp>ýg÷´ôLIûØ€û_IŠŽ¼XuîQï²ÌQ‚„9éH)_^ZÌ–UGy=üK`$Æ}ŠÉùð#WΖ]k٬ȴ–éÍtŒD¦#Hºæ÷›/—Ýb‚iöVD¦&@~ZömD¦åâ½ÏzÇ-‚án\ľ#NøVß]sìµ…þö$ÜÐaî°ÁÖPŒ¯†:`¸´Dg) ×ÙI gDªsΈ¼) ΀†’ üGÁŸ@âœðL‘µP@_XNlµøÜ÷™?Ëi GI_‘³Åü¤¨—€}H`dXñË9Оêº`'ĆÔ<3F²}Ñd!úð’-4}8›ÝßÃÒ|5²‘¡à[݉’{6-œ…¶…èfÞñ¼c½¯”è^—’KŽPô¸CÝxZwÚv®žÙàh…Àç÷ëù6¶“4s7¦SÑOcã Öùš7éÃØq¸é¦×õ™"É Ö|óÌ?]á|y‚RœŽsýkdŸLÏúÓÍÓù8H¨œ¶2L åúQzš<•‘ß¿Û×?gòçï•´ñêMì~Ý­Æ~©Â÷|t#ÜÝŸŽ}Wá76!²|8€a Ññe¦ŸGîö,k¸kI÷ê¾îolª?·w#S”HjïŽ*$ÁïÙÁѽŸÀÈÏ´§üJ½ùlbS”¬Pù”nòýþÁß—õdºŒâ¾UPa_&Ô8ת SMTôKŸqZ¡À.tï –Õœ3›3KÙãÄh…¢øvÙ0§Vö2…TQ”8Ú¿ÌÙÏßa)Ž¢‡¥èºg^ÍÍ€}q8y®'p¡1Ñ샷; ˆ,N@QiåïèÞ'i¯»<œ†E®øá^š,ï9²£Cðöt˜ÿâaA…Ey`°[ ¿²¶W.ÙŠ3 }„äŽeŽ °Œ9©} DÀ¥¬ïv4AHª=tä ³)“¥µàôÙG:U  s_ôr+ÄÌÃ]z´‘L“:*GfIµ2=.#ÉÔî”ÕwÀ–Úñèp2ÚÃtOÖMÕ控»ÜÃs {ûð̺=ÅüvÆËéh0 ~a¿…DÐqf¬gÏÅð>ÙÞ¤–P.§‚]!‹êÁ°½²¿Œ­P>Ž ®Yo-¹$ë=D…*!ÔV0¢q…"!`whRE¿Ë`â4=X΂à$=X™£¹d;9¯à “™ W@¾â<6Tò¬_ÿœw¿ì:Ä‚·»œ_NÐÃû#÷Hsã„>ì€9mag ŒïL Äh ˜;¢·gcŠù]žq„ÖŠù—*9ÏÞ Á“ؽ!Øû×ÜÐìàpš z8’f&¿Ro0äqb†ëf‘OO·²£žˆr¨ÊÜש¡€íšj¸Èùj¸3—(•’gVtdqG½âLÔá|À3ˆW<ÏufàQÃU’…˜i1îü}B~þÎ4Ê!BC"3 kÊD6%’X‡ÄÙÒôXcÔÙŒG„´,„c{® k7¹zro×2ÍëGB~±G]ñ†]Ó [Dæ923Éùù5Êê:#Ú•Šý¡ËB×ç,x†º+ Ù’6Q&5ÅçKLÆ$"20  \F,´3ª‘v"4a±&4áž\Þù¾Å"´Åãë¼cÀµ»ç§g›¿ý 2øÅ ?®áÄ*C)³‚PÏÆÆtíP’ŽÍ ñD{cz×€ÿL‡-É$Î?j¥³¾ØLW"b;ç:ô÷H‚¥ÇÛÿL1õ„k†b\÷èý2ÝÎÆÐ £'U4WA:ùMWo¤ÆqSHþªŸ .+µêª @~¿ ¿»€9Ë[¥øÔäÂÂ*iÌKdIª*+˜@Á›0+§Ûý?%\UÙo&Êš¹2zzïüœÈŒX®ÍŽÉõãlZx‹2ãF†‹°NnƒÎÖå6¨Ù‰ye<_3ë »ÎÇÅtžeŽ¾3¾ˆó‹ÕLôü£Á8ͪ¥ð»ßï¸3¾:»s¼â2aç¯*¸˜ñÚY \:YÊ¥8L,‘pî]q$½4J1…rÛZÊIåqav‚Ê*äÝo !éù‘εàWº ¿Œäcôiί෽òÊ\ ~s-øyεå1æ·Î̯U%Ë,ÖøGæZ„ò$ͯ–_Ã/PÉa×’`2 ®!ƒ¨x0eO¼Ìfsï0ùi æ[IdÑbe²bíjªA_+ûØ;ARÏW¸N<ËzE–·Q6W@þöã°iÿøy¦Nã—W4ómœ!Ì\£”Y©­äC#s"ܳ¿aF;ö„Ë33Ke–Ûöu±3\>:2Âìeú¨?®ì/Л©ræ–âÖóã1!l é¼›c©;g|PÉuÂ5T‰<ï$rË—ø$K ÉcSdÎä?~”³-R¯Pzªû¤y¢|»¡KYØÒå¹@§߶*-VM™)¬2;Ø\§™³½Ë…°Ç“)^jñ•G¦{¹™REÕNlêÛÑk×ÛÓJPy¿€W©^7·-ØJt Y2֠Ùžq°üUv›ÿ`­zwuɾ"Ë«C*…鱓HÇEú,Ž$~ò:HÜ·€¸'Ð??²Ý¬¿pÆï¸O\ÎÖg¬ÔR¾ÿÊ7;Q­U6£>B™ú6Ó:+xßnQÖ¥zK›êÏ+Gf„ªË3Cˆž”ÆÔˆèÜ(Óµ6•è>Ë+› B”Z5ÔDr^J{ì+^q$ï&YœXOh€E†ƒ%"’ì,|Dpêm²–zÒü<‘Á‡²ÛûðÇU+ñÈ+ï̼ý—~ˆ‡ÁöP93íaì s °þå#ëÝ¢’XêŒ+£×#nw˜’ýqeÞÌ-Ü áÎ4±©ŠÄèU¬te(O=$':à[L1X,V"±~׉…òôÍ?~Db*jSi Dcx'Êm3)`ÜèÑ?[Ši²Ù¯Ì‚c%°fRfñ™ö¬³¨LÑ™ÍlVfýÊÐ&íê•ñ̾²ÍÉ?£ÊV³ú︣Ú0{ÃHºYÂ)>ÌæH:‰Ï±tážÍjÃ×+yÏf”–ܵPÌ®ȺúÇs@ËÅ­jXéÉ~Jvúý:Èü5ñ˜€‚“KS ˜„m™KB³$˜¨ýÜOº2—„¦š’ì5ƒIê)ã™:š” ¿LˆáV«u¢cã˜QÆk‚”!êu2†HdòšÞ™‰&ñ¹" ”©…¤×ÒGŒõŠ ÒgNòNIì¦þÛØrªÃþ÷%P·<˜hi(‘‘Á¿ØÉ!¼³ÒûʬÀW²åazQ ¤Œ‘Ñj VÚÓ"#ñ•Ñ‹:)YLVEÇßÑfKYÊY¾äFþ<^Ï‚ÐÚQY'Z;*KI§8“šAÕfdä[¥ˆTEõ ¸’t³j^Š`¯S¯€ØGnŒlõ" Ï]<ô%{Ñ­¦ûžÍFED=©QyÕ Ðð”Y(wK# yŠ*²Á¯<²ª$›ÛŸÚꇌ{Õ1hµ«&¾-U똺JMD,•|¯ˆ,§DæCSœñŠÃLö<Õ}-uŠÛEû¢‘yGߌ„¯Y+þŸ#ûëw˜[^Y4/T†íc°É $o™[øʬ¶Y³!ÄQ`ïyeÉWžc©±ð¨TþÛ·©Œº­”ÝØ£([KR967>dt€Ì2øìd,Ÿ2D§Lc9Pí:hô+»ul/ëPÍ<Öëb‘Ø_§úP´îAŽá‡ °h¹H‘ƒ¤Â)â6Pþ¯FƨöoÒ §ˆw~ñºuŒg³y˜å•#+Ãò9¡Äö·{六]ñG_AÙŸA8ƒ¿ƒpÈ+»|I¹U¾( ×Ò¦yJä¼äqAü_q¸¨¡½¢~%íÿW,`eVñ6Üñ¹í „oaݦ–DVÓå+_™€Ÿ|iö–o}eÖ‰|o/&|kãC¦—cgƒÜ“¬DIšq6ˆ9 |ÉÐåÕÔ[Ոɾâv©ÖÏV-n¯¯Ø\ê! ³‰Ôã‡ûjxúÝ”ýò^|‹âèÄë_™÷Öl@3G€Ûô•Ÿ,WÌ–uÂ~A­(*‚F ¯ºuB‚µéd‹ª´›Å¬‹!Æ=¢ªf±¹@I”ÞoǺ»ÝMu–tÍí€ì˜Û@½Øš›ÙZr¤ºa¯¼³’3›ÖE^϶½rË Ïߪ–ùê »#I)ó×p© ÊSÊR(ûÜjJBŠõÞÓuZ«¥ôÛ§% ®ø„Æýè©]TÐ|nW<>¹:ÛȈ^¡G¾Óõ¬ßžÒÀ\|>*‘-^(pF‰Ø?Jgº¥´¾D™¦:”Ô7÷‰dÃå3›d>m›ê—@Û†Þ÷î•1Z.L >Ôg³Èø^Õž¾ýÃ7ª:5gA‹~Ž…ôÎ3]÷Ü$a©§¢|›Þ«Ñ·  UYêÄ’ŠŸÊºá–á/.›Òúû½Ù·mÄ…ºu]‰,ïtB‰P3˜Å©~@§z¶sJçKy?°¾zL¶”P‚MÒóå€Ì¯<œ3úrÜ×EΧ]™}»î›»ÒjØFË$ä<#):NDÕò]’ù+Ê•ñ¾6®„Ø9%ÔùT§Iê™…g#ï¢ìûºˆËyg/š}+½§Ì–ö¶ÄL¤xh`ÄRa&pä¸r9¶;=A_ôÞ#2"æwÑ1{˜ñ?~šJV´‡£™2ûÌâs¶-"HùLbOù:–)Ñ[K‰>VJÔ $E¶]ßsŸHÄ;ŸY%ó©ý«ga"D_²^Ñè2oùÆûùí|Ãd2)Ÿ² =T˜’v~‡¾M­Â]=â]·UÙÚûä®Ã•ü¯=ë$åݺ &î)“DϸB”·’·ÉíüÇ“qW>U³»nV”ï:®ùËß"–TåçIò]#:¯uk^Ùq¢³ÆzHþ£RRÌgø#êËj$3a™ô•nÎ]«VÜ+»ÉoééRËø¸b ÷ýÙ.ÝÍc™÷B…á¸i"z>Tֻݞ{O‡fÇšÙ[ò‘YvW)Èå¶$[ø·7v& êWÈ÷™ù|ý j5òò³ñyˆÒ?ïmù°êæþ3«2ÞL†ò.u“œAÝUÖòÍ/¸­ÐÝ%ßÌ&ÜßîóéüÐ`èêr¯Æo÷êòëêæ«uÛý-ûÙªàÚUk#Þ¯¸O×ÝG+S±r5ùïí>šYéEÿšý¤î?¿o}ðÞÈD`VËÑåïóŽ:œaÙêûÌ{G>§¸,ïÒ$ Ï3¦jú‹ ¿oésˆùs\…LHåZb:ê’4ÿåi¸'×# ý\Uk¦KwÖÞ·ënø˹ӰŒ‚®¾ëž…‚Ô µìÞûF¹+ö`î0oK²…¼›å8 ØîÔ¿HkRëXHA­PËî=¹ãÎå±ûÿå¹»žóÊëî€hÞmo~‡žÄ°5ŸÃð:®`Æä^ž’à*’âîÃxO›Ý•'Oáz4eç|O­ûmºgªê¸c]éÎ⳯!ë"¥õõÖXtkõïs €ô$Ÿß¥ÜsŽw¾r»çb‰÷¼¼_ƒ§’kŽš™æ¤A¸Åú÷s^S'߶jwûžûïÔ]p…´¬‡×Ì«1ðÎWŽÔ*ôFkåÕ<~¿uéZøxQ`‹né¬KW¶<ÚJ»[mšFÊÔñ$jbË׬Ԭø´WŽÔ¾ê–&6õ5WCûUhû"±ÏkjP`‹õ倲[jÒcYîÞu9H—±‹“÷Ûbå%ÛL$Iµ=Á§\y]ûƒU˜l—¼=¡7¨L&ž¢tºú,Ú”†lºúÿ³õ.¹²#K°]ÿŽb·Õ(0þŒPïá64 ¼–¦¯ãfæá»^£€µ­ÖÉdf2™d0ÂÝîZú+ª?*YVìŽ3¾9Åî7sï{±îõGýZ–_ãßàZTÿJ׫øwºföW¿®C!W]ïa+ƒ‡_bKÏûäïžÙæ…ðpSl&‚ºØ/®Ÿ&]c´àtœ¼GÍWVëÕ ?‹¡{\\ª‚ë<à xäàåÃŦ±ê¢~Ã[ì%¼0¼Åê²çÍã3[…Rüº›¢ÇtY¨ÂM` àFAiY®›ÖÂ!¢=èÃ3ç=;Ï×Y·%L5†„¦[ÂS/‹B{ ËàYã2_ƒ)÷{‰Ü›gËf®q´åj‹žáiSãgŦN/»}|d;‡ÄÙZ±ét<å*6ÙŽç1(‰{°žPüCŒ)ê_jÜÿTã‘ØÖ`{kØ–sT9¤†Í=\0ìÆsªT®·ž!;{æÎh{b»™ÁòÄ6£“ƒÕhþÌ!ì2Gô6Äh ÍAÖbs×£Y4¡ãYæyƒÎScÈXÏ­ác<¹†˜ñì0ÅžÅUÑÒBƒ­Ø‚Ãv`'sLéä m¼ÙÜŠuz±¶ ðð7Q§’›c÷ «î„›Èa÷b“  Ñ›dÌ{tð;èƒüe¢Q¡Þn¿   Âí m‘na`“tkÏ<ýVH±y×ÃÇfódžé^¶!xǨýýá\ÿǦ¾óþ ڪɵ¿TÐÇ{ó@k@¼{´â>h{‹€Û4ÞíAWsGÛgøãfóðÔ_Û¦Þ9jƒÎS㘞[7Éðäºy†g?ŒI,Ž ¼¹Ã¶êθ ©Žî¼ÁÄMç$ñ¹‘T8R]ÒýÓäÖ¡aÞÔžzü·¶×°Ö»Íâr´¡mVz·u,¼¡Xlþš£]ñr ¸2_(ª& ýžeAo~þþᜠÂMXm‘nÔb“tÛtØfÉð†/¶Jw3±Y‡q‹høîâ}ÜLÝyÄw¿SY0w0ãÃä#Y]¹‡;Þéý\lŽÚÁ®{ÝhîÉ;àç=ÇcØ,-–[.-ûLéè?‰ûà.šÐP:ÕâëètÓ>>ž¦Ìÿâ4<¸¦à!ƒ§OGÀãëv6^fððÛß(¬ÛâxýÁç6:ÞÝ^O™[jÓ®ø‘÷3áåH9 ÕH99MˆM¤)63.ŠMÊ;Ø5;£ØrĪ׶J`ÓüŽÒÙ ‘oÊóãõ°±mÕ¼ fXqR 6T“]°y‡qÛ‘Ÿ9æÍqº¶ð0ö¢ó9ù_7^Ó1°ÉÁö úèיʭ¶gðýçñÏÛž¡rV=Úâq+Z lš/Tlvg¡6,§Oˆ‡Ö_ÜeŸ V0‘‹?:¬LÌ*-phŠY±éóœq„‚µcòžÓ°ô,š’U8Œ?"ý9Ó¹ gÝ9ŸþUØW…‡κs>‹ð¦hÂQá¬;çæ” gÝí×ßæõÞÑ:«b@Áô)n&Uñ7Ðf9s¾bÁ4;Ç¡¹Åf3s¶ªìšWl‚;'ÉθÃK㌻AKóðÎu6S±Õ§ΰâÇVü<Ù$†§œOç<|z#6\3ð çÓ9§¹oñ×ÇW¢rE³ëÄÍgÑáÅhv]ÑL»×_Žv¼ž¦¹šÅ&’q:gÁ$8îþ¹Ð.œ‰k¶M…â±UŸµ[0ùIØMëEXNöEÕWÎ.6ŽS? Jè:ú4QT‚åäÑ‚¹zŽíL5å½ äqŽ,7‰sg¹MÎè[ÓÞ³Uœƒ‹m Þ>O¦™žØ2ÍŦi–(¶-¸ù¬Ò‰yüªžÝ[m…b8Ë•|9½`¨˜ÇÆß–ÊÚBDŸºŒtœÐ\lúÝÁW3ž‹}Jœ]0±@Ìk㥆”Ü Å îØ ¦¹îg3CyyŒé[œ?NŸsÆù8gœ/ŒóÄùrŸ.B|mœ+ÍÇ9Ô|uœ[Í—wøõ¹Ø|œ£Í—uxÅ,è{ÿ¸þO~Éöýã!&¬qWÁ<6^[ANä/l±&lšÓ_¬.çô£0+çô£^+çô;6|´(%`¹(¤`ò‡*ÐÓ‰g·˜êåøcq(©²ŸO=ÿT½zðˆêçƒ'ò%ñק­QÇ läáè0„—¤.Dx¥êZ„7€ë ø¾Æ„zÞE®5ˆý†[¾BÜóëÐÊ•R±’PXµÊ¥Øù ×¾Lã‰ýõ– |!^û ãÁq–h{ƒ-À€åÑʨR‹/ƒ)˜ŸçèëdJåj/b; løÔ ýeøÜ\/Ä'W÷ <»º áéÕyˆOêÜ}m’¶€WªÜ½Øþrám;|:äñ=T%¼‰ê´TÛY’÷Q›ÎÞÄWƒ›x# .©áÛ <.ù+vÑÆÕ[¥pWP›81)ˆIœƒˆ“^¢¯+;Ÿ ·Ân(säª`„Ÿÿp6­,v%zpŸ…‡ø‡Xn÷Q÷6G˜§öG…Ë ^ÿÇZ·׫e~xÁÞj ­ÒÔ‚ ¯ópóåg|Ñjå„W­OxÙjý„×í ŮݦÄr²ß–Í?ãL?Ó#ÙÒa= ¯ó0dóи2¶ØÔA_E[¬Žc×k²QP½Tˆgè‚5•|c°¦’ÏÖ÷A[H©wtøÍR0€Ï¦îl¾&ïFUúH¼|%^–w²BÑGu¸ÂäÆå/'ºc]K¯mj ñùŒc^ªVL‹ãaÄ&ìqAy±:©}ñyÁ|E~1]‘Ç@›6ÉõÄ(#ËUÆÅƹö¸`:#!0›‘G¦u,¾…¥¹¼ùlüÙb,Dþ¸Z5Ž²·ZMŽÖ*slõY¯}|ZÕW¡ÕÞxZIŒ×¡Æx!ZyŒÍ^¾:¯E«–ñb´²¯F+žñr´:ö9n&6_Úôùsù0Ö:«÷Q ˜kúχÈÇ°›]˜iºÆ,ÙPl’ 9”ç”w(V\ŽEPߘ¥ PÞ˜"ŠMÅdÙˆ‚™˜Üñ­úïÁªRÅnÔ°@ÀygƒP¤A[tÊÄ_7PE°…*–€MTlXpóB Ø4-âG¥e-îÇvjÑ?6TÅ°¥*€MUñ¼ç**€7]Åð®«Þv'ˆ]‘¯æïG9xÆfµlYÓ¢X?݃^ô¢Ø¼L–Â@jÖÊ(V›4ŠÝta]óÚ“lKásüýXXcy‡^ÚãõXŠµrd•TæeíæeETâz7Ëøa‡öó2üéPZDϧ’#xB•"Á3ªD žR¥Kðœ*i‚'U©Zm:Ö‘±™§,ÚbóNYqÆf² J³6KfÁš‚64TÚÆ?!<‹•AÁ×Ù}YµÈjϲ”‘Íöd}#›ëÉ¢G6Ó“•¬&Ë#ÙŒ[Ÿ± ñ,¤äÛïÏ‚š>|•ýÙ¨ê4ºžHE‚6j:­§RI!Ôc¥¡"N¸¼G O½!v¡Áâ6¨åÇš7…jV×;¦ 9ejÖÖ{¦z:ö¦©ÌÎfÛN¹š´³Ý¹USà ›[ËÂL6³–Õšl/÷ «7ǺNû{²ZÁ¬µmæ%®Ômì—µ¢l. Hù'…çû»OMä³ù¯¬0fci,;fs_Y‹Ì*³@™Íeղݕ2ó­öGÄze>¤ fÙcªŽÖF'>B=U·ÐהŸìqU£ …ÝXºk£šS]zCTèkãB£U½%*:µQ£ Wˆ;JTm^Ƚ-*hµQŸ —…Ä´BèÚÓRnåp'Zö`ÂÜdü”çãƒý=<ðpl¥¦YnÍ:"²›u²0›Õ™fµ6Žžþ©àùlâ¦øZ‰_ù³Æ¬¬ü‡Â؃9C¸^´î ¬&hMÁYbÐ*û²Ëº¿¬YæÓ¨ÔÀ²ž=‘ ã¡E,ëåÙS©Œž=—ªë¡9‹îÙ³©Z:βˆ›½sªífoJ¾±öw[;¶²@ÜFÝ©Çß>•“C‹[V™Û(#¦…†×Þ—r+»x›oneV&—u8­‹sÚœfVì´±*–ñ´ù̬íi³ÃÙcËf‡³ô§KƒÚ¨»qù+ñçÚj>á).yþøðô*@iϯº”/KT6mªX¢O/‹[Ú3«æå‹âœømµçVUÌ#(}é}T%F"÷. ¼p—Ãp ÷ÃùzÅÇã5ø½±÷Uõ!Q>Ð *^{eÎëPR^µUc S›Gκ¦Ög‰ÅN­½0¯ü3²Ç±^Î k­+ç‚ð£aÅ™9.`sÀYx×f€³¯¬±D¯ÍŒçE¡ÍŒg1_ëŲ§6ŠÆZ¨oñ©V‘™US­[{ùkòíjl¾‡2m,Rû¢Ö-¿l(ûÖ@½1þLJ-UíÙ…twѶªR틼۷VuP_”ê|m¯ª¦Ú«˜ªmqc¿õ2ž­w_UXííWqVá«Be]Ñê™Õ^ÏÌWý¨±• f™âujûgõË´:ÈøÚœ}+¶™ü¬UlóûYª˜d︲°Ç¶u¼fb{–)¶GåxšÞ°h·ÍšgÍn{~–ì¶}…»Ix<+úŽï·Í¹÷rÝ6ÿÅ%Êï ’«5Ê´±µ=¬ÊPÛ³6¶eC'j¤&âki›ªÔh[íu¦Ï^ac£¶…ÂÅ8k[¨[ŒS9{ƒTxyapy,½©*Á,ä[½¼è2êñ±æòbiå¢OM—Ï®üû½ðjåömb±rëÎÍZå$<>fãá½Aurl J–ãÁû£2å¶Ö‚UÊí{Å"å ¾+ÍK”Ûpk÷[¿f–î·ã‡Wî·#Ë+fëXÈZü ³ëð8V²G,ß"+ØÎ÷í×ã \<HUäí‘T\µÛXsÞ¡ñþ–Z°*½Ð7UõìÑ6œeîíE©t:Öœ°¢:Tî­ýñšëBíþLJ·REÖê­—¢7]%Öí“P…ut8oú̺×Z'â|öi<É󨟈¯ãﶰ ýä±7ý ²a-8ab£2û e“Þ}Dö,öc¼ñ-²hvä°Æ–lÓ1mÑ9 ¼ û™g—ûégë;`?ù÷ É&!$<Êi|`?Åì†`EºÙ"Á_§o “ssÔ¶×ÙµÂ6CM+„|³Î¶O(lÕ˜b¾§_Åd=œ¡-kì\7Y@iÄoÏD-%îø¨¥Ôýchlf‡Nò¼%-\úLÔ¹«€ØÐèÙça•Ôôàüñ ϧ¤~ öÆ45@álÄ?ºßÿ¿¨?ŠérÖ„é²;Šx±9 Ôßï#[£Ø9/;£Ø9/£Ø9/û¢€p$³^ÅìŠ2GQ'"åïc± ™Ñ{"ˆÙ¸/cçïl,dçô;±­&bß!~­çiVôûqZA-{ 5°v=¨ZßØc©#ç'3úç ÖÛêØV76k³—¢Æ;©­./(rÈæ/öF5vu´w¯ùÔ¤óÇ'ÜÞjõ}™è1„RáÖ'¥¦/öñ©ç‹}¦jùb´:¾ñsx¾7xj[AξIvªæJ³žžKKp2±§ÏB¾›Eíœlå{<‘ðHú$ÿõ\·h²ë\uhš\ ]ñ´X.ͽ rð‹më꺆^lºFäÞûœ–kXÆŽkB<Øóx¿µ†iº=ØIÍ.E•¿ÿ+k½©¨û—pé±Õûk¢Í?FâÔÖ©ñ×ÄÍj¾—n@7½ÔÓÏëüñ9n½1ê5qŸ©ÐßZµš²7\¨ìsnì•hŸ³zTyÌCÃ!¾µõ4½"ö¢\-²ì“>½ ®¯[Êf‹£jý@ã<¼6¥.r¬Þsn¼§_­el8 蘷êA\°Ø`‹ºß 4Ë›üpô©þkƒ†w¦³ñ/5¦³0õ«â‘mÎ/— aß{!¶ mXñã3Ðï½dˆù†c½ {… µo¡&Üÿ+Ç2wæê HÄ—Ö»±!Ú@ù8mRõŽ‰•äªoóérxþø·^¬š%Ú[ ŠB»ÔYÏÞD5ÜbÛìz’ß5T˜Ôw8õY«ÇßxOë?¡¶ÍÿøðÁ«_ß@k=ü€Ø§Ò ü´Õ¸OøêƒW«¾_onó¦Ÿ}8±k› Î][ˆÇ`3Ol]ôû$Nþ3ûˆ¹£µÓà“ˆŸ‰¶¢ÜU±Ô@ÓdÏŸ#6 ¸çc¹¿DlzŸâgkDù3!Ä;TOC`æS?`!ÞûrºÌöçnMÔ{_Ûÿ~ÿαPŸ¹zй¿”ÓÖžQ h‰Ü_êi?kÛ|zÆž?>Ç­«v³ö¨ ­péíª<Û˜K5kàÔ»_yÂaŸ‰úž ‡>¿Ê3‰Á6§O ¶-Z¡öZ]ÚIÔ•ˆ“Ó ~›ßøæQ Õõ|™ÿõ>7ï²LÄ9ö(÷X\¤ñÄùèÀ*îËè…Î}ù9핇MYW·¯Í•wî­ì|ÿ±pÞY«FØVŒ Hø¶ ƒ-¹6ú³·@ü³÷=]Ûíx­¦í@6„´éíj f“ÞOS*;7 ÉÛ cï¿NìÀèÖŽìùû1ê‹ó{û‡ÞÈîR+º[¡05ÿ&Nm]UÓ9› ©¦sÄ­×ç}¿÷“zûŸ£¿]U=åØ ºäc3+Õ=nGoé}ZNÛç§NÔã9 ª…[{€ÚYÛ~þÒØ·üÏñÕUy5f»™:Pùûà_q¼(ûÙSkz [zaÕ ;}aÕ €Ù/Ì?Ê=†­âa+&Ô勈‡³N jy?¢ãýˆ†÷ö»¨VU¶NGª€ìhlK8"b7÷‹ˆœ?>!ßòŽ‚JØ [Äa<"÷P[rÐؽԖ¯pìÈ¡9›`R84gL ‡æ„¼èꨔ…%ÕÌÙåò·R.hQF”ã¦D¶¶¶Ç_íÉ+»E ·6´røÓ6¿z+¨óÇ'd@;`q ÕÞ Ô±pdÇÐaS†¹ Û¶õn}UÝÉlNìÒ¤ØóÇ'd÷J+¹Ø¼rÚ†nߪ:óaf3;óÙÌæ—+ìOi¥%Õvo¡>ë>¨¢µ×—?ç¶r©c±L·5(6·)>¥«›°!;„Ú-é»­gêìô Ô¡ó_l¨æÞ¶wxwáŸÒ½¹ðOéê¤kk¢ÔÔN„ UüõüaÝAQGÿÐʤ©×§¡šÚ,vô´]¼ûGäc+¾†zÃÈçkÛVlaþ‹ííE`€jÎeØÔÒþ!wµßQ.ìÖ¡étçÏÕ³ÍæóoÀÊÛ¨@Þµ­®S½m&ºZúûï|ŽKïGjk“Õ[9è½_P˜„ozêÈm8üªS­]­ÀìÔžä|B5Q·mV?mÛfµÓ6T×lÛ6eì„fª¶áö½®òN”íju©0üùãòCöƒß\[uÇj÷@u/ÓÇù/ÅöõŸ±¢%jKc¨nP¶×°°–ýN«c ª jFÛùÍp~ŠwAAÍÄrPJ¬:¢7.ù)ÞÏÄpèáütù)Þ¢ÃV»©s‡¡Z3XÝE°´evÞÈÁðôÑq©Gƒ-©ó ¶¤®d}M«A§ŽV–Pˆzäu{Ø‘«jþ/¥¶µ¥Ô¦úIçåœ:jÏYO Ã÷ VÙœ?>¡º: >¯¿ µ«Cƒ¡štXÕÞóFÖî{‚ÿñ ÕÈåï®å\lµŒ¹`áÌÒ§X»÷úûUÕ:³óÇ'T75û6«›š-Ôa> ÷„kvíyu¨ÓùãzO>C<œL©iP­ätØá;më,;)ªå>ºÿ¥ÂÑ­"Tay[[¸TÛ–žòåúãª$º­÷äN„õ‰*?nè+ýOè« ׳4[îø²>'Ð;%úÑëñZ•ìµ%“ªä‹Õ“[ÿP|•óåy}¸÷Ù±E5 ­Ê¹JCõýO8r>"ß9ß'W…K{"U¸´§WYK °ô?´…åÍù{r¯¶l ìT™ØVëÕç¼q•+ ‰3ç3å[ŸDõ"ᨽܹNç¿ñÇç¸õÙ×Suÿ§z©}ÃîÿP|ŽC{[m¬“jgZÞ!ÃPíJt$±ÇøÿùŸÖOž¬o#vU¿ËbEè舲Èßo¼’#Vþ±ËÉÉorÄ…üýrÈ;9dûUX0x;`¾~:ÎÊáÏÈÉ%9âFþ~9äšñCþ~9ä–¬íBm 6ÿ©+rOŽ¸“¿Ûäˆ ù»ñLù}Éðß“‹WrăüÝŽøMŽ¸‘¿Ûïäˆ2ü}r²w˜y‚—ñßíˆKrÄüÝŽ¸&G\Èûy.nÉÑOýKþnGÜ“#ždøåäâ‘q#·#žÉ?äïvÄ+9ä±È{,y.~“#îäïvÄ;9âBþn‡ÌÒtÄv‰9ØsÇn x..ÉOòw;âš±òïvÄ-9â‡ü±ï”çâž²]|Õ“ß“?’#VþÝŽx&G\ÈðÇÉÅ+9ú™ØäïvÄornþnG¼“sóÇ^\ž“Õ- Žß‹WŸ×:¹¸'§Çkyõ~¾'§×ë\ÉûyNV.8Îl>>Gu…#·ä´ø,Ø‹Àfö{.NŸ—ó ï'¿ÉOòw;✛ᷓƒÕÄÎáE†ßO.îÉ¿døãäâ•ñ&ß''—'±½ÏSíîìLG¹¸%G\Èðß“‹grÄ• Ÿ\ü&ç=ßýYÔáî99¹–pœ;~9¹¸'G<ÈðëÉÅ+9ë»8¼ÙÏÉí Çy‘á÷“‹[rÚ9–N¶6µ&ž‹Grn†?O.žÉoòw;â79ú}yÈð×ÉÉêǹá¿'÷äˆ+þ>¹x%GÜÈæÏçädÃqîdøåäâ–ñ ï'äˆ'~;¹øMNüvOÍ3T弓sów;dƒÁùÅçõÎôz½ÿÞJü’Ïç5Óç¥s°ÿŸýSçcä–œ›Ï÷Kçcäžñ&ŸãƒÎÇÈ#97Ÿã›ÎÇÈ397Ÿã­ÎÇÈ+9qn6u>†ã˜ÎÇÈornößÇéçcàœ›ý÷}úù˜±ÎÁà8²Ÿ¿yçYrIÎÍ~¾­\\“s³_¿(·äˆ+Ù¯O½+.¹'çføgÄÕy$'η½ënyO.žÉ¹þ8¹x%çføõäâ79âN6ÿÙ'ïäÜ œ¬“p~1üÈÅ%9âA†_N.®É¹Ù†Íö9¹%çfø)'÷äÄõÔäù¡-<9y$çf󭜕ç䙜›á¯ÈÉ+9båð{ää797Ã/‘“wrn6½‘ƒuN ÇY9ü9¹$çfø5rrMŽñÿùóÿþ§üüßøýù¿pº’G ?¾³ùêbnÿ—ÿ×ÿöŸÿñŸçŸ¿gÿßßGø?þþ÷ÿüçùùßÿ£Ñ~£îöø7gù#¾½¾ù8³Tg!ò_ß’~ùÐåO¿Fè(Æ;®F³ g!i«5¾™:“ž¸báÞ€‡•FCÔ—é²YîoU[º Agçòóç87[+†§ž\\“s3ü}rqKÎÍh1O.îɹ­!ÚÉÅ#97lá¹x&çføç=u^Éw¿Â«¶|Àsñ›œ›ÕâÃsñNÎÍð×ÉÉl‹Aç›?#—äÜl>F’˜‹krn†ÿž\Ü’s3šŽŒ“‹{rÄl>î0äÜ Ÿ\<“s³ºx.^ɹÙü¹øMÎÍæc$›¹x'çføëä`®Ô¥ó›Ñ\§Ÿ\\’#®?ºÂF3ÏÅ597ÃO.nɹùcÃÏÅ=97›?#äÜü±Ùç♜›áï“‹WrnŽÇ_éñßäˆ ù»réáübøëäâ‘ñCþn‡\K8¿øcc$ÏwüN¸C¶¹cœmp9â797Ã'ïäˆ5oỲܬ÷ßü±É“çâ™ñúÑüåÕÎ/†ßN.nÉOòw;✛ÏþÜwìÏlwDÇYçßíˆgrn†_N.^Éwòw;äÙÂùÅ📋{rÄíGW¨—³ã*MÎ/þØ.ÌsqIŽXWrßíˆWrn†ÿž\ü&G\~ts9dcÀùÅŸy.É??:£¿²~sáübøóäâš²Ÿ³~·#~“só9>ë÷Èxé7ÅœßüÝŽ¸$§œ}{é÷%9âšœz~›–~_’#nÉ!ïÇg]Ž¸'G¼ÈßíˆGrxž`W–K¿/£Ÿ\<“CFÿmý¾$G¼’#~Éßíˆßäë ·#ÞÉ!svÕNþŸÍwè8oòw;â’²$­R’_’_“C¶ÑGãÍü<·äí¸±JK~K~OŽxù$ÓËäW'·#žÉ!Ûo1«2\Žx%Gü’¿Û¿É!ÛuÖ*oòßäïäðs|*~\Ÿpœ7ùûåKrÈvµtþrMÙ®³–βCnÉ!cV`mÉoÉïÉ/ò÷Ë!ä{'¿òLŽ±ü=ÆÌp_rÿævéhk5οóLŒT[Kîàe„yBôâÜ{ ]oC•u—3”X7”ãäê Á­¾ÉýÜj@OOÍ"EWÎsâWq©‹ 8‰ÅN8µ“o¼N@Þsˆ…“|¸CÛZ(ðŸÃ›ÜÿÍæÛÛs0ŸƒŽs#ï‘“Krn†ß#'×äˆ+þŒœÜ’s3ü7rrOŽ¸Í_Oää‘œ›á×ÈÉ39⇠¿GN^ɹþŒœü&‡ŒY^¼°i''ïäÜŒîcOä`õƒãü’á×ÈÉ%97Ãï‘“krÄ‹¬>i''·äܬîi''÷äˆ'ÙüýDNɹ~œ<“#dø=ròJÎÍðgää79âN†ÿFNÞɹٺÕ=ÏÉÉý ǹ‘áד‹Krn†ßO.®ÉW2üyrqKÎÍðß“‹{rÄ…ìÝù”‹GrnþÔÃO¹x&Güá÷“‹Wrn†?O.~“Cn› ÿ=¹x'çfóësr2/Vé8¿døg¨sIÎÍŸú*×äˆþ<¹¸%çføïÉÅ=9âI6¿='äÜ ¿ž\<“#døýäâ•œ›áÏ“‹ßäˆ;þ{rñNÎÍæc?aNžO8Î ¿ž\\’s󧮙ÊÅ59âJþØ[ÓsqKÎÍðß“‹{rÄ…ü±3§çâ‘œ›áד‹grÄ~?¹x%çføóäâ79d»aÕØÕ¼àœŠ¹x'çfóqNÅœÌÁ:Î/~=¹¸$çæ]L=×äˆþ<¹¸%çføïÉÅ=9âI6çTÌÅ#97ï'Ïäˆ~?¹x%çføóäâ79âN†ÿž\¼“s³ù8§bN~Ÿpœùc]ÏÅ%97ì³ë¹¸&G\É»ñz.nɹþ{rqOŽ¸ÍÇ9sñHÎÍðëÉÅ39⇠¿Ÿ\¼’s3üyrñ›²­±k¼áWpNÅ\¼“sóg}‰Ÿ““y3ŽóK†_O..ɹùcßcÏÅ59âE†?O.nɹþ{rqOŽx’ÍÇ9sñHÎÍðëÉÅ39âA†ßO.^ɹþ<¹øMŽ¸“á¿'ïäÜl>öæ`–R¤s¸‘¿Û×äˆ+Û³O.îɲo¿rñLŽø!Ã_'¿É!?›ìï§r2é8¿døãäâšñ"ûç«\Ü“#ždøíäâ™ñ ûþ¦\ü&GÜÉðËÉÉ»€ãÜȾÿ+×äˆ+߯}rqOŽ¸ýû¨\<“sów;â•œ•¶ß¼ÏÌÅorÒ{ÅñC”‹wrv|vu'‡¯±8-íKMÇÃqrqIN‰}»•ä—ä×ä¤ïZ«çø©\Ü’Óα¢·–ü–üžœ86ö¦Ï«\<’3ÎoAçxBvÄ39ñÛ×Û<¿ÊÅ+9ëüÖ÷¶’¿’ÿ&'ÎmzÓç[N.ÞÉ/òw;d!ÀéqîÚûs~•‹Krt=RÈßíˆkrâÚ¤kþà9¹$‡Œs'OH¹&GÜÈÙ‘“[răüýrÈ=9âEöñÏÉ#9âMþ~9ä™2Î4ž€ã€ròJŽ¸‘¿_ùMŽx}|ÉsòNŽx‘¿_ë¡<á8o2ü9¹$‡Œs'Ž'\¹&GÜÈ>žæ9¹%G<Èß/‡Ü“#^dø-ròHŽx“¿_y&‡Œs§=Ïø¡çä•q#¿ò›ñ Ã/‘“wrÄ‹üýr0ûyŽsx“}¼ÔsrIË្ü’üšqûQ=j=ONnÉò÷Ë!÷äˆÙLJ='äˆ7ùûågrȳᯔƒWrÄüývÀorŒÏ”¿çŒÿØ(ªfN¤+pŒŒë_¦N?áO§¦Oì4,ó®"Ãб†C1L­¡×YbØv¤áSÜŽÜq¹áC[øš”rœîS l£t9<Òe,Nót™‰Ã£ßj×6ã§ðõ¤[ºþ³·Zðóí·Û^ÜêÒ©]Ü^Ä)hSíOðt’‚ƒ½N*ñCÑÓœƒô‹0ïÄŽ¬WÞÐðƒY9“üa|ÒIAÙqÀnñåó TÈÒI¾¸+núÉH='\6©ýÕËËvÒö†ö²p.ä–¸’ᯔƒkrÄ…ü±™}äà–ñC†¿SîÉ!Wå{Ÿœ<’#~ÉðKää™ñ"ï‘“WrÄ“üýrÈoră ¿ENÞÉ+‡ß#³½ çJ†?"'—äˆ þŒœ\“#~ÈðWää–²Õu|;?_+'ê9¹'G¬~ÊÉ#9âE6<‘“grÄ“ ¿DN^É2ü9ùMŽ¸“á·ÈÉ;9båðSf‹L:Ε DN.É2ü9¹&Güá¯ÈÉ-9dë6ð~¾V%ÐsrOŽX9ü”“GrÄ‹lþ|"'Ïäˆ'~‰œ¼’#dø5rò›q÷bu•y='ï䈕ÃO9˜]½é8W2ü9¹$G\ÈðgääšñC†¿"'·ä€QØôü|­T±;äžñ"Ã\<’#ždó×srñLŽxá—“‹WrÄ ¿ž\ü&GÜÈðÛÉÅ;9âJ†ßONfŸc:Î… œ\\’#~ÈðçÉÅ59äw“¿Û·äˆ_2üurqOŽX9üÈÅ#9âI†¿O.žÉ²ùïsrñJŽ¸“á—“‹ßäˆ~=¹x'G¬~ää÷ ǹá÷“‹KrÄþ8¹¸&‡Œ÷íåç‹÷¹¸%Gü’ᯓ‹{rÄÊáG.ÉO2ü}rñLŽxÍÇ~Ë\¼’#îdøåäâ79âF†_O.ÞÉ2üÈÉìNÇù!Ãï'—äqÜc{qô P.®É¿døóäâ–ñ"Ã_'÷äˆ'þ{rñHŽxáï“‹grÄü×øa.^É72ürrñ›qýQÍ×2žzrñNŽ¸á·“ƒÙNÎᇠ¿Ÿ\\’C¶ó–AŒb×ÿž‹krÄ/þ<¹¸%G¼Èð×ÉÅ=9âI†ÿž\<’#døûäâ™q'›_ž“‹WrÄüÝŽøMŽ¸’á—“‹wrÄÊáGNf7s:Î~;¹¸$‡l×»ðóµóvåâšñK†?N.nÉ/2üyrqOÎÍð#äÜ ÿ=¹x&g¦mÓç»O.^ÉYéµóó­ÏÉÅorÞôÞòó­åäâœôù~¾µžœ\Óçë¬~;¹¸$§Ä¾WùùÖ~rqMN}»òóµëtåâ–œßÊÏ·žÊÔÎ=9éû[ùùÚ8ƒrqúþ:+‡ÿž\<“3ãØRùùÚ8‰rñJΊcWåçkã0ÊÅorÞ86V~¾­œ\¼“Çç]ùù¶zrrKÇggåðÛÉÅ%9åüvlŽ_ –ýæçK®É©ç·isü }§”‹[rÚùícÏHtzð\Ü“¿¿›ãWh}¥\<’3Îo÷æøÕ@‘sæâ™±røûä╱róm M¹øMŽÎ¯”Ã/'ïäÄùK­ôSNîq~uX9üvrqIŽX9ü~rqMŽXùw;â–ñ Ã'÷äˆ'þ<¹x$'Î¥7ǯF_'Ïäˆ_2ü÷äâ•ñ&Ãß'¿ÉÑõÑC6<'ïäˆ ~99yÄ5ÑáJ†_O..ɹ~;¹¸&G¬~?¹¸%G¬þ8¹¸'G¬þ<¹x$'®7ǯеP¹x&G¬þ{rñJŽX9ü}rñ›±róqf.ÞÉÑø†røåääù„3c|csü í•‹KrÄÊá·“‹krÄÊá÷“‹[rÄÊá“‹{rÄÊáÏ“‹Grbüjsüjà8Ì\<“#Vÿ=¹x%G¬þ>¹øMŽX¹ù83ïäh|R9ürr²Æ¦à8+‡_O..ɉ±ÊÍñ+´U.®É+‡ßO.nÉ+‡?N.îÉ+‡?O.É+‡¿N.žÉ‰±èÍñ«ã0sñJŽXùw;â79âM†¿O.ÞÉÑý…çG-M šÉ*'klªd.døåäâ’œ¸×°9~…µÊÅ59âF†ßN.nÉw2ü~rqOŽxá“‹GrÄ“ ž\<“÷’6ǯƻN.^É¿døïÉÅorn†¿O.ÞÉ+7ÇaædMÁWåðËÉÅ%9qpsüjà8Ì\\“#V¿\Ü’#V¿Ÿ\Ü“#Vœ\<’#Vž\<“#V\¼’÷‚·Æ¯pÖøùMŽX9ü}rñNŽXù_}¹•£÷ ûŒÃ9Ü”Ã/'—䈕ï'×äœ{ý`øíäâ–±røýäâž±røãä⑱røóäâ™±røëä╱røïÉÅorÄÊáï“‹wrÄÊÍ/ÏÉÉå GÜ•Ã/'—䈕ï'×䈕Ão'·äˆ•Çã·ôø=9âNŽíïiûGră|Þæâ™ñ$Ÿ÷¿ÌxÿËJŽx‘Ïç[Òç[Þ䈕Ÿý§¼±ÿ”ñöÎ`Ú'ËŽý³>áˆmÔSŸØÿëû-Éòù~Õ߯Z“#®äóý­éû[[rÄÊÏñ¡¶8>Ôžœ›Ïñ§ö8þÔ‘q'~L«#Žou&G<È:~z.^ÉO²ŽÏž‹ßäˆYÇÏÅ;9â—¬ßÏÉš[Çy“õû幸$G÷ñ²~=×äˆ Y¿¿ž‹[rÄ•¬ßwÏÅ=9âFÖùƒçâ‘q'ëüÄsñLŽxuþã¹x%G<É:¿ò\ü&G¼È:ó\¼“#~É:?ôœ¬¹Upœ7Y矞‹Krtÿ!ë|ØsqMŽ¸u¾í¹¸%G¬\çóž‹{rĬëÏÅ#9âNÖõˆçâ™ñ ëzÇsñJŽx’uýå¹øMŽX¹®ï<ïäˆ_²®='knçMÖõ©çâ’ÝÇȺþõ\\“#.d]_{.nÉ+×õ»çâžq#k|ÀsñHŽ¸“5þà¹x&G<Èßð\¼’#ždŸx.~“#V®ñÏÅ;9â÷G81æã9Ys«à8o²Æ—<—äܬñ+ÏÅ59ºÿ5>湸%G\Èó\Ü“#®dïy.É7²Æ=Ïäˆ;Yã“ž‹Wră¬ñOÏÅorÄ“¬ñUÏÅ;9âEÖx¯çdYÁq~ÉOö\\’#ÞdW{.®ÉÑ}ü‡¬ñð““[rÄÊ5Þ~rrOŽ¸’5žròHŽ¸‘á¿‘“grÄ EN^É2ü9ùMŽX9ü”“wrÄ‹ ¿GÖØç— ¿EN.Éo2ü9¹&G÷ñ2ü9¹%G¬~ÊÉ=9âJ6×}ÊÉ#9âF†ÿFNžÉw2ü9y%G<Èðgää79båðSNÞÉ/2ü9XcSpœ_2ü9¹$G¼ÉðkääšÝÇÈðKää–±rø)'÷äˆ+Ù|vVÉ72ü7åà™q'Ã_)¯äû¢!Sù‡+CþÁ{•çœØÜÿ·éˆtóŠ*¼q¤‰'àÔE&×ã@øßÿhHKSBñ3¦¡“t;¤çáx Ýj8Ô~hˆÛœ®4Ï.{n³•¸5KG—C¸E¡KÜ7¦¶`Z§3n9¨Ã·vZMTæň/¯O‚ŠAî´1Ùã\ˆµtуv;7ÔÎÅN~t¡ŠEMÚY1PÆFÚ9q³Ï,qs7åuÇ„ŠuÙ*²R9p`‹ŠÀãqåˆ+ùûå[rÈvC´rààrÈ=9båß/‡<’Cî“ ¿FNžÉò÷Ë!¯ämÂGåÀÁåßäˆò÷Ë!ïäë ¿0èˆm¿rààrÈ%9âN†ß"'×äŸMþ~9ä–±òï—CîÉÛò<ð÷Ë!䈕·#žÉ!¿/~?¹x%G\Éßíˆßäí†_moòßäïäˆ+ù»2èˆísíOøýI~IŽ¸á“‹krÈø®õšüšü–q!·#îɹù»ñJÎÍðçÉɼ¨¦ã\Éßíˆkrn†¿N.É7òw;â•œ›á¿''Ï'çNþnGÜ’s3ü}rñLŽx¿Û¿É¹Ù|»¬œÌ‹:ΓüÝŽ8í?¿~9¹x&G¼Èßíˆwrn†_ON~k8Î/ù»qOÎÍðÛÉÅ+9âMþn‡¼Ÿp~1ü~rqMŽ¾Ëù»ñHÎÍðÇÉÅorÞ8Vì7ùïñÛóç7ß'·äˆ+ù»ñLÎÍð×ÉÅorÄüݹ”p~1ü÷äâžq'·#žÉ¹þ>¹x'G<Èßík ç›o7û•‹{rúùíh:¿JŽx%çføåää¿Y‡ù»qMÎÍðëÉÅ#9â—üÝŽøMÎÍðÛÉÉþ›û&ÞäïvÄ-97Ãï'Ïäm«±_ŽøMÎÍðÇÉÉD¦ã\Èßíˆ{rn†?O.žÉWòw;✛ᯓ“9èIǹ‘¿Û÷äÜ ÿ=¹x%GÜÉßí×Î/†¿O.®Éòw;â‘œ›ÿúV1ÐsñJŽx’¿Û!¿%œ_ ¿œ\Ü’#^äïvÄ397ï'¿É¿äïvÈ»„ó‹á·“‹[rÄ›üÝŽx%çføýäâ²ç°ºîå€Y —Îo†?N.îÉòw;â•œ›áÏ“‹wrÄ•üÝ™“6èübøëäâ‘q#·#~“s3ü÷ädNz ãÜÉßíˆ[rn†¿O.Éòw;✛ͷ ”Êɼ֦ã<Éßíˆ{rn†_N.žÉ/òw;✛áד“u Çù%·#ɹ~;¹x%G¼Éßíu çÃï'×äí<‡Õ9/G<’s3üqrñJŽ¸¿Û!ó¦ _ ž\Ü’#®äïvÄ397Ã_'¿É7òw;dýÆÁùÅðß“‹[rÄ|öŸÕbÿY=97ŸãÉêq<Ño(›ý÷«ûï)x&çf?ŸQ.^ɹÙÏŸ•‹ßäÜì×SÊÅ;9bå~}ÝýzÖ˜7±èüb/R..ɹÙ|;/U.®É¹~;¹¸%çfóíºX¹¸'G<ÉðÛÉÅ#97›ocÜÊÅ397ï'¯äÜl~‹\ü&çføåäâñ"›_#'kLÎ/†ÿœ\\’s³ù8ælƒkrn6¿q;ƻΩèÜ ¿Ÿ\Ü“c|n,•õüƒÑíò>»kÌÐνõoÓq†7–8XË™ø!­3NŠ}ð7p`û¯÷lèÄCsÓONñ}Ø—¬ñÖ4 CÛö¦!T›Ý4œ×pÙÀª÷sšŽÝ´é+=ã´ÃÓ~©€Óë©üå¶G\¾âT—ânÐm˜¡÷ì²lNÈ[M·.°æ¶Ýˆ µxÛ iø¯¶Ø6¼^}휚×xü°‚K²÷ü|r›ÿkÿ'3ÜáqÖ |p ±U¬]5¶ÂP'±¸‰ãŒ`‰ÁîöÅOƒ]Ô8Ý`zÎ¥µe*]}uó„á=Ÿv×…¶o¿WÂûûunûûùvŸOhx¦ ?zé6ÏSàáTvÒy•MÄóÔЧöÀöÓU¬íï®ï)°„ dúqž§À™ÚU¤mõ“[Â秫@ÛßýÄS`áTéê*Îöwçö8B¾?:ÿ³ŸJO3!Ó“í<®ÎŒ^'ÚO¤§À7áøé*Æö>'îNŵ®Blo9©¡—XëíGçžö³è)°„ dúñÀ™©­sTû9ôØB>?]…×þ~¥<ö4ë~ÿt]ûû3è)p„ |tÞk?žgB¦'Ñy \!œY÷:?¶Ÿ>OoÂñÓUdm?'îN%Ä®k»œÔPSúLpl?]ÅÕþè<–„L?N€óXC8+(ºŠªí~R` A+böÎãm⛧À‚ðýé*¦ö÷\ÂSàA¸~ºæ'$8C8«`tm`“ã<®„㧫€Ú~O |Cö]Cؤ8O;aû隸÷<ž5UÏÇúÓ5iïïù¼Rb á¬hêš°÷œ”XC>?º†±Ù$Ýçð¶´RmÿèúÅ&ÀuŸxbØC¾?ºv±ÉoÝçëG×-6ñ­û¼=ÃÂY¦k›ôÖ}Ξá A8~t½bÞºÏ×3|Cö]«Ø,™îsõ wÂö£ë›è¦¨%¤&8Ö]£ØÜ¥ÄÂYi¨ë›à¦”XC>?º6±ÉmÝç涴‚tÿèºÄ&¶uŸ—gØC¾?º&±™CÝç䎄ëG×#67¨û|<ÃÂYAªk‘)q… ?ºx6Mj2|Cö]ƒ ¼ ÍÁ3Ü!ë®?ÞÕÑù‹¾L´–]{Øä5¥Ä‚ðùÑu‡M\SJ¬!hu÷þÑ5‡MZë>çΰ… |t½‘bA¸~ºOªëžGgEw÷ uÃSâ AÈôã®îsé WÂþÓµÔ¾±>×Îð AØ~ºÚ‘@k@;aýé*`fGÕ/û‹CK>ÿ ËÏPñ²¿G.¥Ä‚éÇÉJ‰5U]Ø?CEËZõ”ØB¾?CËþÁ•{Âõ3T¬ìï/ƒRâáTZ*Tö÷G)q† d ÷¤Ä‚°ÿ (kËSâ‚°ᾞw „»=ª™ Žhîßk¥Ä‚éÇù}J‰5UCÙ@¸ÕSb Aøá6O‰=áÂížG§ÊP²¿gmJ‰3aÂ=)q… lÀs•ß„÷õ”¸C8m† Žõí)°žr6 ¹ãñ”XBP¥¢ ü.XC¾@¸ÅSb A¸€p«§Ä©N4T\ìïõ‚RâA8€çqG<î AØg{glï AØ€ç}Xñ>¼!+Ð?‹úÆg±C8•¦†bÚ«u˜†í”™:ø}ßÑL` AÄ6Ð÷I­¿Ö„/Ð÷uMù¶„ èß!MýöNÕ°¡E—ö…ÔšKàA8€þ×4eà AØ~,ÑZKà AØ€~ŒŠ:aÃË„µÀ ôcŸ¦;w§ÜÐK;j:´a?åß>@?Vkm%°„ Ê~è¿ZW ¬!Ð[´¦ØBN ÿfi=%°‡ @ÿ-ÔDtàAØþ«u”À‚°ý·[k(+aú9ÖOß„¨s ¥Ä‚ðê|G)P¥¾LÚ7V‹&ÿ”K¨ó3¥Ä‚puÞ§”ØBN Î'•{ÂÔ9­RâAØ:WVJœ!PçàJ‰+aêÜ^)ñ AX€ºfPJÜ! ®E”UÂË¡}cµòïo±Rb Aøuí¤”XC. ®É”[ ԵžRbA8€º†TJ!;PצJ‰3aêšW)q… ¬@]K+%¾! P×èJ‰;¢} }¼dy Tiy_ Æ†—–„ ¨±Šáã%†5áj døx‰a A8€[>^bØCv ÆlF¬u*#AØ€ >^b8CV Æ£”WÂÔ8—Râ‚ðjüL)q‡@´o¬ ÈÛŠ/dú‹*o‚ã ÔØ Rb A¸€sTJ¬!'Pc™J‰-ájŒT)±‡ ì@½*%Ž„ ¨1]¥Ä‚°͵+¢W„ûzJ|C>@¸ËSâhßX†·+¢ª¼ Ž/îð”XB. Üî)±† œ@¸ÍSb A8€p«§Ä‚°áO‰#aÂ}<%΄h®]Íh¸B>@¸¯§Ä7NB±oìÖý·å)q‡ |p§§†“Ã!&\@¸ÃSb A8p»§Ä‚pá6O‰-aÂ-ž{„ûxJ!+ÐÜ¿¿J‰3aÂ}=%®„îò”ø†@|7îô”¸C¾@¸ÃS ‡C 8. Üî)±„ œ@¸ÍSb A8€p«§Ä‚°áO‰=aÂ}<%Ž„hîßs3¥Ä‚°á¾žWÂwyJ|C ® „;=%î„/îð¨š&8. Üî)±„ œ@¸ÍSb áB¸ÕSb áB¸ÅSb¡Çæ¨YÕã)q„0âeªÑÜö”8C˜çí«j2wRâ !>·ªsËSb|nŽwzJÜ!ì³U5–žÛsÇ„Û<%–ÊÙíÕ0°WO‰5„ø¾©Yàß+¥Äø¾9N ÜÇSb¡Ÿ¯¿šþ½B™ÞGÐp„0ÎaE Ûë)q†0ÏáJÍÛò”¸Bˆã¤æ—´é)1Ž“ŽwxJÜ!ìsØÖü’Ö=öçŽ ·yJ,!”ó3£ù%­zJ¬!Äï›æ—üý|•ã÷Íqá>ž{Â4÷ïþ¨”8B¸îë)q† d ÷¤Ä‚páNO‰oçej~Ižw„Û=jÄÇ „Û<%–„Láž”XCv Üâ)±…pÎ'§æ—ü=N+%ö„hîßã¿RâA¸€p_O‰3!S¸'%®„wxJ|C8×SóKJ÷”¸C Üæ)Pƒ$&8V Üê)±„ l@¸ÅSb AØpO‰-„sý65¿Ä^±÷ô3ì!'îë)q„ \@¸ËSâ AøáNO‰+„ áO‰o „Û=%îÎ%øTc>ûx½ó¿èƒ$O`­žKB¦pOJ¬!îã)±… ìÀ¿®ÝMõØC8C'“ã%v7ÕSàA8p×I3!S¸‘WÂwœø† Ü@¸ý¤À‚†¼ ÜvRC ’˜àX€pëI%!S¸‘k„ûœØBv ¹öëÿž«Sƒ$Îøääx‰Ý!õ8BN ÜyRà A¸€pÇI+á „ÛO |Cn ÜvRàáB¸õ¤†û &;ÚYÇKìnª§À‚)ÜH5aškgÐûÜX$ l@¸ïI=aÂ]'ŽέÉñ»›ê)p† d 7Rà A¸€pûIo·¸Cn ÜzÒ¿¸žsóÆñï‰Èâx‰ÝMõXB2…)°† ¬@sç>)°… l@¸ïI=aÂ]'Žέ¸Åñ»›ê)p† d 7Rà A¸€pûIo·¸Cn ÜzRCou·…g1Æõ»ßÿ>Ö£yïébÚî¡òßq!¦w¿1™|ÅŒ÷“¾Ÿ3§Ð¦¦j ÔfˆîsM3¼ÔûòY&³L4pP}¾ƒ)ùT»¯ +_)ÅI‚Õ³qëvNÎtÛNü.» :>ç¾·2zó£¸;·Î­(Ì™Ðｶú[=cò6ðªán»Ÿ®Ñlû9Ç…ÿßmù)}pëKp ”ÏÊqœ¡ Îjür´s·J—"86ú½¼8=³œuf,8Ú!Õ;Ï<çTW\gV•.!ñsŒ«u[Ñ°bã$ ;ÆI„X Ü©áh+,0NÒ°ÀÃÂ…pß“WB¦p#¾!Ð\›à¯¸Cήóm˜à¯Ôà n„ÛN ,!Ç×7LÚW ¬!;î<)°… l@¸ë¤ÀÂ…p÷I#aškñ•gÂòÃµÈ ñ•WÂGëp&â+¾!\·Ÿtw-³‘@´£Rãç¶ÇI ûsÇWëp&Ì+–„Këp&Á+Ö„Sëp&Á+¶.üëbïƒILp,Z‡Ã7•)±„ ¬Z‡“b AØ´§M,|Ñçöh™¡¯ÃáNÀ”ØCN­ÃáεûÙÏ4HA¸´' Ä‚pkwð=Ͼ®A’íKrp‡‰ëpÚÄz}ߦ–ÙH­Ãá—lÇ÷MÃ!„Mëp²0Ï2»Öáà‹®tže6„CëppQ:Ï2 ©u880)%¶„¯ÖádØCn­Ãió,ÔŽtÇæÑ:H•gªu88@+%®„Mëp²@|Cv­ÃÁ„RâA8µ§Í3W¨á}~¨”KÂWëpð¨”XCn­Ãɱ… ;6Eëpð#¬”ØCVMÉhs6O‰#aÓ:œ(%΄Cëp²@\!§ÖáàdD)ñ A¸´'9J‰;áÖ:œ<)ÖçB›B©ñ’ˆ%aÑ:œfó¤•kªu88ÙSJl!»Öáà$R)±‡ Z‡“âA8µ'²J‰3á«u8mb?7à A¸µ'ÓJ‰oºcóhNˆ;¡¯ÃÁ ½R`{Žàèëpp¡ ”XBú:œfë”kB_‡“b A¸´6J‰=á«u8¸`RJ!·ÖáàBL)q† ;6Eëpp§”¸BV­ÃÉñ AØ´§Íîëp„;áÐ:\*r8‚ãÔ:\è*%–„Këp²@¬!_­ÃÁŶRb Awl­Ãiö˜J‰=aÑ:\ð+%Ž„Uëp²@œ!»Öá`ÐaúxÉÖÜ6 ¡u8̘>^òj™áÔ:œfŸïôñ’¥e6„¯Öád¨é#&8n­ÃÁàËôñ’©e6tÇæÑ: ê(%Ö„Eëp0X¤”ØB6­Ãɱ‡ ìZ‡ƒ+¥Ä‚phN³ï»Râ A¸´ƒfJ‰+á«u8Y ¾!·Öá`àN)q‡ ;6¾‚Jš>ò–@_‡ÓìØ«”XBú: J*%Ö„¾' Ä‚pjF•{Â¥u8pUJ!_­Ãiö;¨”8CЛGëp²@\!‹Öá`€X)ñ AXµÏJ‰;a×: h+Zqã‚ãÐ:œ,̳øF‚pjÕ•kÂ¥u8Í΋”[­u8ØWJì!èŽÍ£u8Y Ž„EëppsÁÓâëp$›Öáঅ§Å×áHv­ÃivŽêiñu8„Cëp.¸C.­ÃÁMO 5b‚ã«u8¸yã)°„ ÜZ‡ƒ›Bž_|#ÁÐç­·¾ê?í§×úÏË«ÏtŸÐ.$ü_ž1 Ì\ç¨3/Ó0°ýœÉQ~³½çö ¤iuœ›³Ÿû 6ôÕcDGwXÞ¸éd·Ÿë™™ë·µQ˜\gè>Áå¿:³ÔmtàÄ¥Ó5êàÓ±^].þWGMžá‡D'Ƹä<ÇG xà&´2ã “¯ÕÄ;J›WÂyŽIÙ¸ú>w(ü‚Æt:G¶w]'7gM.îÀ{ºüÌÎf“wTßß8lõÂfÝöÿœ'yü›Í·1ž“WrÄ ?åä797Ã#'ïäÜl¾õŠðŒã”çF†ŸrrIÎÍðWääšœ›áïÈÉ-9âJ6¿ÕÈÉ=97Ñ“Grn†ÿFNžÉ«5¹ùѦÜy%çfø=rò›œ›á¯ÈÉ;9⇠G~Ÿp~±ùÖFØsrIøÙ› „C®É¹þ{rqKÎÍæ[ÛUåâžñK†ßO.ɹþ:¹x&çføûäâ•ñ"›¿êÉÅorn†?N.Þɹþ{r2›rœ'Ù|k£§\\’s3ü~rqMÎÍð×ÉÅ-9âA†¿O.îɹÙ|ëé¢\<’s3üÈÅ39âN†ÿž\¼’só_-¹”‹ßäˆ~ä✛ᯓ×çyÜùÃß'—äˆ+ÙüRO.®É¹þ8¹¸%çføïÉÅ=9âB6¿–“‹GrnþnG¼’#~È📋wrnÆöï““ËŽøUþÝŽ¸&çæóþ”ïOiÉ+ÿnG<’#^døëäâ79âI†?ON®%çA>ûC-±?Ôžq'Ãï'¯äˆ~;¹x'çæ³?×ûs{ÂqVþÝŽ¸&G\ÈðËÉÅ#9⇠ÿ9¹øMymòùþ¶7¾¿½„ãü’á¿'÷äˆùócsñJŽx’áÏ“‹wră œœü¿Û!ëšN±âªë#;W..ɉ±ñªë£äˆkrÄÊ¿Û·äè~J!Ã_'÷äˆ;ù»ñHŽXùw;â™Ýï~Èðgää•q#¿ò›±òï—CÞÉo2ü9x<áˆmܾŽ'|åä’q'¿rMŽx‘᧜ܒCÆoýhÉoÉïÉ7ò÷Ë!äˆ'~ÊÉ39âMþ~9ä•cŸÙd÷Óþ±X =vÇwæ_t}êÕÿ%f6i Oÿ°›=þõYçVžúñ¯!n q ·Ò儱ŸÚÚ^-é0QÏó3_ð“–v¾àA§’¸üÖmo°.±xüž]„—¾6 ªÚ,ÅÂaûj³ ‡í+¹$~ÈðgÊÁ-97ÃSîÉ!Ût óW›µwròHÎÍðkää™ñK†ß#'¯äÜ DN~“#^dø+ròNŽx’áïÈÁ˜âñÿ·õvY®ƒJåû7Š3‚»Ä? £×Æeþ¯]d™»ßvEmÛX¶%HD燿Räà$¹Í/‘ƒ³8/›_#qÈÌÍ«8/›?#7qÈü矫;ßœÜÅyÙüì9yˆCfn~ää)9Íož“—8/›?<7ÆŽó6yNNâ¼|ü”<'gqÀmÍ/ž“‹8/›_='WqÈl~÷œÜÄyÙüÈÉ]ò?ž“‡8ä6?{Nžâ¼l~ñœ¼Ä!7°ùÍspúÂùaó‡çä$¹‚Í_ž“³8/¿$ÏÉEr›Ÿ='Wq^6¿zNnâ3Øüî9¹‹CN`ó§çä!ÎËǯŸçä)™¹ùÙsòçeó‹çàü…C>Ë31M÷ç4ÏÉIœ—Íž“³8ä 6?rrçåãÛv@N®âØüì9¹‰Cî`ó«çä.ÎËæGNâØüé9yŠóòñm¿‡œ¼Ä!W°ùÉspùÂùaó‹çä$™¹ùÍsrçeó‡çä"9ƒÍ_ž“«8ä>þHž“›8/›Ÿ='wqÈØüê9yˆó²ùÝsò\Øüé9y‰óòñçç9¸~á\ž`ó“çä$ÎËæÏÉYò›ß<'qÈl~ää*ÎËæ/ÏÉMr}ž“»8/›Ÿ='qÈl~õœ<ÅyÙüî9y‰C.`ó§çàö…óÃæ/ÏÉIrÿùó, fNÎâ™›_<'q^6¿yN®â?°ùÃsrçeó—çä.83?~Šœ<ÄyÙüì9yŠCž`ó«çä%ÎËæwÏÁý çò›99‰Cî`ó—çä,ÎËÇ?§Ú0'qÈ l~ñœ\ÅyÙüÈÉMr›?<'wq^6zNâ øøö=ANžâ¼l~öœ¼Ä!37¿z_8—Øüî99‰ó²ùÓsr‡üÍ_ž“‹8/ߎƒÈÉU°}¯>_;Ž#'7q^6¿yNîâ'Øüá9yˆó²ù‘“§8ä>¾õ{‘“—8ä6?{ž_8?l~õœœÄ!7°ù‘“³8/›?<'qÈlþòœ\ÅyùøÖ‡DNnâ Øüâ9¹‹ó²ùÍsòçeó‡çä)Δ¶áó=u-æä%Ž|¾¨_ÍSÇc^ò™^ž`ó³çä$NŠßêWÓúÈÉò›½œÁæwÏÉEœû"ԯ枓«8²FýjŽå9YöÏ—øøÖ‡DNîâÈñõ«i}Häd9æ’­o€úÕ´>$rò‡\ÀæwÏÉÒ§ZÒ×BýjÎé¹qfÍê8Î|üÓ‡dNNâDÿ9£~5O’99‹ÃñÑ6¿zN.âÄøË@þœî9¹ŠC.`ó‡çä&¹Í_ž“»8äþó×éC2'qÈ l~ñœ<ʼnZ–™ü9Ísò‡\ÀæwÏÁ·fU„+Øüé99‰CîàãŸ>$sr‡<ÁægÏÉEÖŸ?°ùÕsr‡œÁæ7ÏÉMœ¨?cËŸ3<'wqÈ lþòœ<Ä!ðñO?„9yŠC^`ó‹çä%x$°ùÕs0kVæ\.àý:ä$NÌaÙËã³81O„e/l3rr'扰ìåqÈUœ˜'²—?'{NnâÄ<–½<¹‹C.`ÿ¼“‡81O„e/CžâÄ<–½ü9Ÿçä%NÌaÙËã€Y³2§Ä<–½ð;‰œœÄ‰y",{ùs¦çä,NÌaÙËã‹81O„e/üM•¿/Ö¬àÄ<–½<¹‰óDXöòçtÏÉ]œ˜'²—Ç!qÈìûää)NÌaÙËã—81O„e/ܧ!³6eÎåÞ¯CNâÄ<–½ü9Åsr'扰ì…ûä*ûgÖ¦àÄ<–½<¹ŠóDXöòç$ÏÉMœ˜'²—Ç!wqbžË^x ª=ŽG¬Meå Þ¯Cžâ+ØŽËsò'扰ìåqÀ¬M™sy€ýøÛäøÛ’81O„e/CÎâÄ<–½ü9Ãsr‡\ÀÞ@N®âÄ<–½<¹‰óDXöÂ> rr'扰ìåqÈCœ˜'Êý«ê9yŠóD¹Mñ§øK2sï¿5~¾‡ûÎåÞ¯CNâľ`ý œÄ‰y¢Ìú•8ä,NÌeÖ¯ì¸Éú¸ˆóD™õ«Õ<'Wqbž(³~%¹‰C.`¯±~îâÄþrÝÜÄ!gðþqÀ]r›Ÿ"qÀuÍÏ‘ƒ§8ä 6¿D^âØü¹1îVçrïœÄ!7°ù-rp‡\Àæ÷ÈÁEr›?"WqÈ lþŒÜÄ!`óWäà.¸LðþqÀCòÿùç@{sò‡ÜÁæ'ÏÉKr›Ÿ=ã®p.W°ùÅsr‡œÁæGNÎâx¿¹ˆCþÀæ7ÏÉUðÊTÜá~oNnâ'Øüá9¹‹Cî`ó#'qÈ ¼_‡<Å!W°ùËsò‡\ÀÇOŸç`ÜýÎå 6?yNNâ?°ù‘“³8à3-Yq£„Ó͹9¹ˆCžàý:ä*y€Í¯ž“›8ä6¿yNîâ+ØüÈÉCr›?<'OqÈlþôœ¼Ä!'ð~0®Ð‡lß“ÉÏwyNNâ'øøö9"'gqÈl~òœ\Ä!w°ùÙsr‡ÜÀûuÈMr›_<'wqÈl~õœ<Ä!'°ùÍsò‡üÍïž“—8ÆvEõŠ›Sž•7ãf p.3߯CNâ;Øüé99‹Cn`ó—çä"¹‚oûaää*¹€ÍOž“›8dæægÏÉ]òÞ¯C‭ˆ›Wž• 7'OqÈl~õœ¼Ä!°ùÍsㆻTšãÌÜüî99‰C®`ó‡çä,¹€÷ë‹8ä 6zN®âØüå9¹‰óòñO?Š9¹‹ó²ù‘“‡8CÚ6ÄâOq¦¼w|¾5rògɶÅç[#§/œ$Ÿ/nxyVJÜœ,Ÿï›99‹Cî`ó»çä"N‰ïn~©¹ŠSý»ÝpÌS¬¹9¹‰Óü·Ó?ßÈÉ]œøý¶ÄÏ7ròçåã·ÈÉSœéûŠ†bž•7'/qȼ_œ¿p.°ù‘““8É÷ 7Ç<+1nNÎâÄþ¹á™g%ÆÍÉEœ—Íœ\Å©~,h¸Q¦:ä&NócMÃÍ2ÏÊ›“»8ä 6?rògø±¯e~¾‘“§8qüm™Ÿoää%ÎËÇY›ú”x¿9‰CÎ`ó#'gqÈl~ää"¹‚Íœ\ʼnþUCýê¬ô¸9¹‰ó²ù‘“»8äÞ¯CâØüÈÉSò›9y‰C^`ó#×è3_>ã¦VùùFNÎâøø#rr‡œÁæGN®â ØüÈÉMr›9¹‹ó²ù‘“‡8äÞ¯Cžâ;ØüÈÉKò›9˜µ&s.O°ù‘““8ä6?rrçeó#'qÀgÜÔZ¿ˆ_Å!'ðñgää&9ƒÍœÜÅ!°ù‘“‡8ä 6?rò‡ÜÀæGfMÉœËl~ää$y€ÍœœÅ!O°ù‘“‹8ä6?rr|Æ5õ¢9¹‹CNàã¯ÈÉCr›9yŠC.`ó#'/qÈl~äàõ=ç6?rr‡ÜÁæGN.âØüÈÉUò›9¹‰C^`ó#'qXoÿÀæGNžâøÏ/_ää%9ƒÍÌŽ9— ØüÈÉYr›9¹ˆCn`ó#'WqÈl~ää&y€ÍœÜÅ!O°ù‘“§81÷Ñ&·ää%ç³>°ù‘ƒ×Îå>~ŠœœÄ!g°ù‘“³8ä6?rr'æªê'%ENnâØüÈÉ]r›9yˆC`ó#'Oqȼ_‡¼ÄyÙüá¹qÿbÎÑyÍœœÄáüò6?rr‡œÀÇÏ‘“‹8ä 6?rr‡\ÀûuÈMœ—ÍÏž“»81×ÜQ?9+[nNâØüÈÉSr›9y‰C`ó#£6çòï×!'q^6xNÎâÄZ‚žøùFN.â€O?¿'~¾‘“«8ä>~‰œÜÄ!gð~r‡\Àæ'ÏÉCœ—ÍÏž“§8ä 6?rò‡ÜÀæGÎ_8—;ØüÈÉIòï×!gq^6¿{N.â'ØüÈÉUò›9¹‰Ãu ØüÈÉ]r¿FNâ3x¿yŠó²ùÉsò‡\ÀæGfÍÄœËl~ää$¹ÍœœÅ!wð~r‡<Àæ7ÏÉUœ—Íïž“›8ä 6?rr‡¼ÀæGNâpÈ6?rò‡œÀûuÈKr¿}žƒY31ç‡ÍOž““8ä6?rr‡\ÁæGN.âØüÈÉUrï×!7qÈl~óœÜÅyÙüî9yˆCž`ó#'OqÈ l~ää%×|àý:`ÖR̹œÀæ/ÏÉIr{û[Šö³–çeß>-Çöa-¹€}û·ÛŸµ8ä öÏ·ÉçËZʧÜÀþýl-¾Ÿ¬¥À!w°ÿ[ïÿ]ÛÓÿ¿ì¿¯6â÷u×ötáößo“ßï]Û3„'Ø÷'mÅþä®íQ^`ß¿õ/öowmÏ >ã ÞSì?{Šý'k/pÈ ìûç.ûgÖ^à¼ìÇ‹^âxÁµ=pÈìÇ£^ãxÄZMR.`?>öÇGÖjà+Ø×½Çñšµ8äöþ@gÿÊxŠCî`ïotö¯Œ—8/{¦³uø®íQ`ï ö¯Œ“8ä öþÞ`ÿÊ8‹C^`ïOö¯Œ‹8\ò½¿:Ø¿2®â™{xHÿ™µ8/{~p|dÜÅ!g°ÇGÆCrûxdp|d<Å!W°†Œ¸¶™¹×X/2æÚs.w°Y/'q^öñæäøÈ8‹C`ÿNÿÞµ=Cx‚}|Íú¸ŠCf~ÇûÌÉM®ùÀ·žÀœÜÅ!'ð­o0'q^¾õæä)9ƒo}†9y‰Cf~ëEÌÁ\ÛcÎå ¾õ¨.õ¨Îµ=pÈ |ë]ÌÉYœ—o=9¹ˆCîà[¯cN®â™ßú!sr‡<Á·>ÉœÜÅ!/ð­2'q¸äßú*sòçå[¿eN^â™ßzòÍ®í9ŽsßzõÍÁIrßzøÍÁYrßzûÍÁErßúÿÍÁUœ—Í/‘ƒ›8ä6?GîâØü9xˆCž`ó¿ÈÁSòJ^âpÈ6Dn̵=æü°ù=rp‡œÀæ·ÈÁYr›_#qÈl¾äà*¹‚ÍO‘ƒ›8ä6ÿ‹ÜÅyùø§Nrsð‡ÜÁæÏÈÁSò›/9x‰Cž`ó[äÆwmÏ^`ókäà$×|`óKäà,ÎËæçÈÁEr›/9¸ŠCÎàã÷%¹q‡\ÀæOÉ»8ä 6Hn<Ä9|O<5ÅÿàìµÿØkéB[[ÂÇʸÕN€äÉ(ƒ'ÄØ"—ó‚ÿý?v[Ùt;frg)g°Ô;e Á¦Wg ÿ»×9¦Õ±¤²Æ.ã.M°¥Btl™‡R}Äôg©2,]âá­Å”‰í¦û]ŽiåþXŠÍi{œR²aL»ËÁ[LG›ÿ˃;Ø8°ràf¨?¨~2EáÔv2ÜZ8رxn~­cÆ"§u2KLÝÁ¾¬ïDv‰Î¹–¹Õ­à0c~;´·ý<ò¬ÇL ¯³öÐøÎÖ&:ä6¿GnŒbœË¼pÇø¬ÿ5Þ?8‹Cf¾_‡\Ä!°ùÃsr<x¿¹‰Cîàý:ä.9ƒÍŸž“‡8à±ÀûuÈSrï×!/qÈlþòŒ_(rg¾_‡œÄ!7ð~r‡œÁûuÈEpc~ü3èbN®âx¿¹‰CÎàý:ä.øüö ^gíêÍÉCrï×!Oqȼ_‡¼Ä— 6?r0ŠYp.7ð~r‡œÀûuÈYpžàý:ä"¹Í/ž“«8äÞ¯Cnâ€íwÑ›øMü.¹‚ͯž“‡8äÞ¯Cžâ€¿ Þ¯C^â™›ß<ã( çrï×!'q00>Gÿ5’øIü,ÎËûuÈEœ—Íïž“»8ä6xN^âpû|`ó§ç`_à\N`ó—çä.9ƒ_>ÏÉKr›Ÿ<¯Îå 6?{NîâØüâ9y‰Cî`ó«çÍîoù•ë°ùÍsr§ß缾ùÝsò‡¼ÀæÏÁ©„Cþ/›?='wqúý­›¿<'/qÈ|üúyÎ%œËl~òœÜÅñý‰±ùÙsò‡ÜÀûuÀ˜<†óÃæÏÉEr›_='wqÈl~óœ¼ÄYw_j¼_\¿p~Øüî9¹ˆC^`ó‡çä.øÜÒöc¬NÏÉKœuÆûuÀì#™óÃæ/ÏÉEr¿}ž“»8ä6?yN^â+x¿˜}s~Øüì9¹ˆãÇkcó‹çä.¹ƒÍ¯ž“—8äÞ¯æ1Îœ6¿yN.âxßÃØüî9¹‹C^`ó‡çä%ûcx¿x~áü°ùÓsr‡œÀæ/ÏÉ]r¾w.gíùÍÉKrïׯ/œ6?yN.â+Ø|¿£ñå.¹Í/ž“—8äÞ¯cŒ{•Âùeó«çä"y€Íož“»8ä 6¿{N^âx¿8}áü°ùÃsr|Žk‰ÇÓsÏjæä.9Í_ž“—8>6ɉÇSqÀ¨2ÁùáãÏsr‡\Àæ'ÏÉ]rï×!q^6?{N^âx¿˜Çhs~Øüâ9¹ˆCî`ó«çä.y€÷ë‡8/›ß<'/qȼ_Ìcº9?l~÷œ\Ä!/°ùÃsr‡có¼_‡<ÄyÙüé9y‰CNàý:`öÌùaó—çä"9ƒo÷bgÜÅ!ð~òçeó“çä%¹‚÷ë€Ùg0ç‡ÍÏž“‹8ä6¿xNîâ;x¿yˆó²ùÕsò‡<ÀûuÀìc˜óÃæ7ÏÉEò›ß='wqÈ ¼_‡<ÄyÙüá9y‰>ÇñÄþ‰8`öIÌùaó§çä"9Í_ž“»8ä Þ¯Câ¼|üõyN^â x¿˜}s~Øüä9¹ˆC®`ó³çä.¹÷ë‡8/›_<'/qȼ_Ç8³Ïsœ_6¿zN.âØüæ9¹‹Cžàý:ä!ÎËæwÏÉKòïק/œ6xN.â€O?$³¿$¹Šóò~rçeßþÈÉ]rßï'sòçåûûeNžâ¼|÷‡ÌÉKŸ_È9Åñ‚98áüð=žæÛß3Nâ¼|û3ÌÉYœ—o9¹ˆC.àÛfN®â¼|Ç ÌÉMœ—ïøˆ9¹‹C®à;dNâ¼|ÇËÌÉSœ—o}€9y‰Cnà[É·u˜}Zs~øÖ—ò­G'q^¾õ4æä,ÎË·Èœ\Ä!wð­g2'Wq^fýöæä&Îˬ?ßœÜÅ!0ëç7'q^6?yNžâ¼|ü4='/qÈÌÍožƒÙ‡7ç‡ÍOž““8/ÿ‹œœÅyÙüæ9¹ˆC^`ó“çä*ÎËþ¹–•çà&ÎËæ·ÈÁ]Îÿ~`óSäà!ÎËÇ·}òͧ8/›ß$7^âö%-ÕÿœêÿÁâ?™Ó©¶¯æ¸&ŽYXPr¶wç\|-W[Æ°¥t;ø±®ÿç0–xùlÈŸÇ™rHÜõ¤|Juwˆne>Ö†ôßô]ɇ(Ó³‹ie¦;5¢thåãÎöfqV›ˆ÷Ž±µšƒ…ƒ©3qéƒ2k'¸­ÓÎÁ—uÀøX+¤ îä­S=ÿ“/ì´Ü–ÞNÅg–_¬~«3:fÞ~.ø8+×JºWthàÿ9sµZNàUx‘7q|åZI÷ Crã.Ž¯\+°U„áq|åZIÝW,zžâ¼l~Š¼Ä!°ù9rc.c2çro,ÆñœÄ!7°ù5rp‡ÌÜü9¸ˆC.`óGäà*ÎËæÏÈÁMro,bòÜÅ!'ðÙ‰|Ÿçä!™ùÆ*㛓§8¼²Ño,Œº9y‰CžàUÒ7sù—9?¼± ûæä$Ž/S+‰g |Ãsr‡ÜÁ«ÈoN.âxc•úÍÉU¿rUI÷ŒÏsrÇW,–tÏHž“»8/o¬â¿9yˆCÎà³nNžâxã,„›“—8ä¼±hîæàõ…³|EjI÷Œá99‰Cžà³4nNÎâ¼¼qÈÍÉEòo,¼9¹ŠCîà³XnNnâøŠã’xÆ@®ž“»8dægáÜœ<Ä!ðÆY>7'Oq^Þ8‹èæä%9ƒ7ÎRº¹1yæ8'ðÆYP7''q|uyɼâE‰œœÅáÂÏÞ8‹ëæä"y‚7λ9¹ŠóòÆYh7'7qÈl~÷œÜÅñ³ .ç,º›“‡8ä6zNžâø2Ü’yÅ‹²<'/q^>~Mžƒãj Ál~öœœÄñ³CJæ/$'gqÈ l~õœ\Ä!`ó›çä*Ž_ùµ°Tìsá/ÀMœ—ÍŸž“»8dææGNâø²ìÂP±ïyò3n ‹;tÈl~òœ¼Ä!7°ùÅs0Ï0çr›_=''q^6¿yNÎâ Øüî9¹ˆãKÉ @g5ýÍÉU¿rsaèœ~srÇÏØ+,•þyNîâ€ó›Ÿ<'q^6?{Nžâ'Øüê9y‰C`ó›ç`^ ÔœËl~÷œœÄ!7°ùÃsr‡\ÁæOÏÉEœ—ú™ÌÉUr›Ÿ<'7qÈl~öœÜÅ!'°ùÅsò‡üÍož“§8<£zÍïž“—8/›?<ój æ\žàý:ä$ŽŸ]]XBxÅ p‡Ì|¿¹ˆCn`ß>¼â¸ŠãwN(,•Q='7q^öÏ‹W¼wqÈÌýûÀ+^€‡8dæþ}ã/ÀS2óý:ä%ùû÷ŸW¼0æ):IøŒ;2¯xÑ—çä$ÎËþ{ä/ÀY2sÿ½ó$p‡ÌÜ÷'¼â¸Šãw>)™W¼‡ÜÄñ+^”Ì+^ôæ9¹‹ó²ï?yÅ ð‡ÌÜüâ9yŠCfîûs^ñ¼Ä!3÷ã¯xa|¯r‘…™ï×!'qÈØ_¼â8‹ó²yÅ pÇøt÷Kîrüírüå]nà™›?<'7qüŠ5%óŠÖà/À]2óý:ä!¹½Â+^€§8/{ÿ‡W¼/qÈ̽Õ¥Żܘs™¹ùÙsrÇOí+™W¼°>O gqÈÌ÷ë‹8äìýOž®â¼ìý[^ñÜÄ᧘{ÿyHÿ™w¹CfîýsÖ¯ÀC2óý:ä)¹ƒÍïž“—8äöñëWƼ*êüÿa¿°~NâøÕÅJž2>š2>âUTá™ûø‹õ+p‡Ì|¿¹ŠCN`²~nâøãJž~Åš›“»8/ûø”õ+ð<˜ûøwÊø—W]…CfîãëéW¬)™W]…Cf¾_Ì«®åöñ>ëWà$¹Íož“³8/{ýõ+p‡ÌÜëKê¼J+2s¯Ÿ°~nâøKfýJr‡œÀ^Ïaý <Ä!`¯±~žâ¼lõ¨å9y‰îÌoý*Kýªð*­Çqf~ëcÌÉI2óý:ä,¹ƒo½®Ü+¶q^¾õÀr¯Øj\ÅyùÖ˽b«q§IÛXŸ,ž“»8]Þ{÷úg¹Wl5â Ù¶Cü!þ'>ßr¯Øš<'/q–—ʽbkä`^¥ÕœË|ëÉÌÉIœä¿ÂúÕ71'gqâ÷[X¿‡\Ä)¾¯(¬_qsr§ú¾¨°~•"'7qüꞥ°~•šçä.NìŸ ëW©zNâ ?Ö¯Rñœ<Åñ+z–’¦øSü%ÎòcYaý*EæeÌÉqü-¬_qsr'ù±¾°~uÆYÌÉYòÿŒ›˜“‹8ä 6zN®âx¿¹‰Ã¾V›?<'wqÈl~÷œ<Ä!°ùÍsò‡\ÁæWÏÉKœèKÖ¯¾â9˜Wi5çrï×!'qÈl~öœœÅ!/°ùÉsr'ÆJ…õ«Ëÿs®âøÏÏxÎÿ7qÈlþŒÜÅ!WðþqÀCœ Þñ挳nžâøÕÍ—8ä6¿EnÌš•9—'Øü98‰ãW|46¿DÎâø÷.â3Øü9¸ŠC.`óSäà&NÔ¯ ï³¾ÈÁ]rßöÌÁCòï<Å!O°ù3rð'ê“¥ú§<7¾õ«lÇåæWœòœÄ!g°ù-rp‡\Àæ×ÈÁEœ¨?Þ!Gp‡ÜÀæ—ÈÁMr›Ÿ#wqÈl~Š<ĉù…rïóEžâpþˆùñ‡äà%9÷cÌš•9—3Øü98‰C.`óGäà,Ž_ÐØü9¸ˆCfn¾äà*Ž_ÐØü9¸‰ãW4Þ?¸‹s……믬Ÿy×eq8ÿ›ÀæçÈÁS2só%/qÈlþ¹ñˆ9_ç >¾õÛ™ƒ“8äÞ?8‹C`ógäà"NÌ﮿ꒃ«8ä6¿GnâpýÆ6¿EîâØü9xˆë7 ïð£xŠCfn¾äà%¹ÍÏ‘sÍ•9—;Øü98‰C`ó¿ÈÁYœÃ¾àõo³üÇf‰¾ÿ$ß—rm¤Žgm-‹¯X<È[êZ‘•+&mçz' ¬˜tÆÓPù.6¬Q˜ü¢øgƒ¶[ ´ýܰ=V oUMp‚Ë T…‹q1ů©M—ògoe2þD­?Îé¥1*¸üÅ“\:`‡NÛî/nnèÝ”Æî‘ï¦ï´®=6¦s8ŒÇTÇ’© {…¶zKÃgYk>×1-¸±M>×ø,¸±Íåó×!gð~r|º'¸±Íã‹8ä6?{N®â™ï×!7qÀç[‡Û<¹‹Cnàý:ä!9Í/ž“§8à>ÁûuÈKrï×[ „Îå6?rr|~⸱Íã³8dæûuÈEòÞ¯C®â€ë›ß<'7qȼ_‡ÜÅŸC4nló8ä!¹ƒÍïž“§8ä Þ¯C^â€óï×ç/œË ¼_‡œÄ!g°ùÃsr|öœ¸±Íã‹8äÞ¯C®âØüé9¹‰¾ù~r‡\ÁûuÈCrï×!OqŒÏy7¶Éç½7'/qȼ_l%:—?ð~r|Ž†¸±M>×¾99‹C.àý:ä"x,ð~r‡ÜÁûuÈMr›Ÿ<'wqÀ}÷ë‡8äÞ¯Cžâ3Øüì9y‰>Ó鸱Íã€ëÎåÞ¯CNâx¿9‹®l~ñœ\Ä!Wð~r‡œÀûuÈMðéqáÆ6ù\ãùæä.™ù~ò‡ü÷ë§8à<ÀûuÈKœ—ÍožƒÛÎï×!gq^6¿{N.â'x¿¹‹ó²ùÃsò‡¼ÀûuÈKœ—ÍŸžƒûÙ>‹þ…ß?ñ‹8/›¿<'WqÈ ¼_‡ÜÅyùøùóœ<Ä!gð~ðøÂùaó“çä$¹€÷ë‹8/›Ÿ='WqjüvF¿Š/¿¯6¿xNžâx¿x~áü°ùÕsr‡ÜÁûuÈUœ—Íož“›8²¿šMü&þçeó»çä)y‚÷ë€W ç‡Íž“³8äÞ¯C®â¼lþôœÜÄá¾ýï×!Oq^6yN^â¬8v¬%þr7¥€óËÇ?ûæä,9ƒ÷ë›8/›Ÿ<'wqȼ_‡<ÅyÙüì9y‰³üX<8œr8?l~ñœ\Ä!7ð~rçeó«çä.¹ƒ÷ë‡8/ûçÅñxŠóòýþ3'/q^¾û+æ`Œ­à\à»ÿgNNâ¼|×ÌÉYœ—oÿŠ9¹ˆ}¹qÇ_Ësrçå;~wüeÜÄyùÖCFŽú nºp—÷© -ÏÉC2só›çä)ÎËæ'ÏÉKœ—?§ç`Ž¹Ì!ŸZÄÀøë*nNNâ¼l~òœœÅyùøgª„9¹ˆó²ùÕsr‡œÀæGNnâ¼|ü><'wq^6¿xNâ3ØüÏsòçåãŸr5sòçeó‹çà;æÊÿ_>¾}îÈÉIr›ß<'gq^6?{N.â¼|üsgN®â+Øüæ9¹‰ó²ùÉsrçåãçé9yˆó²ù‘“§8ä6?yN^â¼|ü3an1¦þeó«çä$¹ƒÍÿ<'gq^>þ7<'q^6¿xN®â¼üç7Ûg27qÈl¾äà.ÎËæçÈÁCœ—?Wäà)y‚Ío‘ƒ—8/›Ÿ#7îQ?ùåãÉÁIœ—Ío‘ƒ³8ä6?E.â¼|ü>#Wq^6¿Fnâ¾Ón§ÿõŸÓ‚ÔÿÃZîé3RsàïÅö«öX›v˽F¤×(z:Ã-ÚÎø;Ï|v¿I+Œ-? ã.±|qì¬8ŠAÚw&:•gLW üv`¹“‡9‘R­³Ï‚} hîÔO:'FŒÙþ(0t+^2_%èÑæÿž¯×.b7r-öŸ<“•$øÊ6<^,©G·øTë½ËòY—ïò‹C•_ïáÓ¾vì*ÙR¾{”9IJOƒÃu¼K~Å£<äíÇ´žÝªÊî­²ÿÏn-lü?çþ‚ÏVmÖ-µ[‡cœÅyùøý‹\Ä!O°ù9rpçeó[äà&ÎËæÈÁ]2óã/rðçeósäà)¹ƒÍo‘ƒ—8/›?"7._8?|üókº98‰Cn`ósäà,ÎËæK.â+Øü9¸Šóòñ×9¸‰ó²ù9rp‡\Àæ·ÈÁCœ—Í‘ƒ§8ä þómOÂœ¼ÄyÙüÈÁõ ç‡Í¯ž““8ä6xNÎâ¼lþòœ\Ä!àã§ì9¹Šó²ùÕsrçeó‡çä.¸,°ùËsòçåãçì9yŠó²ùÕsò‡<ÁæÏÁí ç‡Í_ž““8ä>þ)í0'gq^6¿zN.â¼l~ää*¹ƒÍ_ž“›8/ß¾·ÈÉ]r›_='q^6xNžâ¼lþòœ¼Ä!Wðñ[öÜ¿p~ØüÈÉIr›?<'gq^6yN.â¼||;æ"'WqÈÌͯž“›8/›?<'wqÈ lþòœ<ÄyùøvÌENžâ¼l~õœ¼Ä!`ó‡çàñ…óÃæ/ÏÉIpf~|;æ"'gq^6¿zN.â¼lþðœ\Å!O°ù‘“›8/ߎ¹ÈÉ]ò›_='q^6?ròçeó—çä%¹ƒÿüiÇ\äàù…óÃæWÏÉIr›?<'gq^6yN.â¼||;æ"'WqÈl~õœÜÄyÙüá9¹‹C.`ó—çä!ÎËÇ·c.ròçeó“çä%9ƒ÷ë€W ç2só?ÏÉEœ—ýý®ïwUqÈx¿¹‹¾¹ùÓsòçeÿ¼“—8ä Þ¯cŒ%œpœ™›ïË?/q^6¿yN®âû?.Û|r‡ìË0ñfNžâ¼l¾/«¼¼Ä!û²ÊǧÎeæ÷÷Èœ\ÄyÙüä9¹ŠCÎÿ¸ìñqÈ]2só?ÏÉSœ—ïþ‡9y‰CþþqYâã€Y+0‡|só§çä"ÎËwÿÉ|ƲÁë¹Tp¿¹‹Cfn~÷œ<ÅyÙüæ9y‰Cîÿ¸¬ïqÀk›óÃ÷øÂœœÅyy¿¹ˆSâ½nO_¾wY¶!ËߪøUü&N‹ï*Æãê»8ò[.Ý¿ÌÉCœû"ŒÇÕ!Oq¦ï{±LïÏñªæå%N;°LïqÀƒ›S£?€ezCNâç?.Óûs>ÏÉYöç¹do¿¹ˆýùÎñøéó0'Wqb¼Ö9‡ÜÄ!Ï\¦÷8ä.Çæé—éý9‘“‡8Qoé‹CžâD=­s<¾†çä%yþã2½Çs nÙ–Lr<.ΈZðuÈl~÷œœÅ!3߯C.â}YߟÓ<'WqXMàý:ä&¹€÷ë»8d.'¼ýyæä!™K÷ë§8¬‹&°ùÅsò‡Ì|¿˜cð¡Üÿq™áã“8ä ¾ãæä,ë¢ ¼_‡\Ä!—\ÆøçDN®âû?.c|r‡<ÁûuÈ]ÖE}ÙãŸãË/qÈœIÙ¯Cžâ;øŽ7™“—8ä Þ¯æÜŽ»?.¥Ü¯CNâ}YåŸ3#gqȼp‡ÌüŽÇ»ŒÇ;ÇÚpXMÿ¸ óuÀMrïÜÅ!w°ù=rð‡<ÿq™ç뀧8¬‹¦\æùç´ÈÁKrïgúRÐ$KD—F~á3Ÿ¾ô:äùËBQ3¹98‹Ãºhï\Ä!°ù%rp‡ìËN_ÜÄ!Ï\vú:à.ë¢ |ëK7qÈå—©¾xŠCæÒTóSäà%y‚÷c¼¾pÈùþqÀIrùÇe°Î98‹Cîÿ¸ öuÀEòßúÞ͇/•½ë¢é—;Îð¥²×!—\6û:Ãg½¯Cî`ógäà!™ùþq†/˽ë¢é—å¢æé¹ñ‡\þqYîc3øŸ;à»láÌ9ÿçTÒúæædŒ3F÷ÇJÍÇ–-ð`’8Agt£Ó­øÊ‚Ö♹Yxk)ŠR6ù°¤sÊâGõó1©Ø9™lË Št¾8Šó‘0¡zy·Í¶³ÿ¼HƒI<îP?+Bg?ÀÞ –óC¿“?6)ÍŽj·ü¼ÖÿÓ?÷0oKZLƒqÈÝhænÔJ0ø¨lªæþœb [åõ»+9¯Ì¯©Ò» ¼c|j<ÏífÙO‘‡ð]oÿy7ÅâÔ5j²ñ¯Zå¿ÿ×nt`r;ðx¬˜Õ~C‹jŸø_Ãê¸`ÛüüË6ò‘m{ý½ãjå¼°î¿Òwm{|hé>§ý×^fá…Ñ~N¢ÿi˜B· §¿ÈzN¢ˆ¿y¥Šˆù†8áöÜR§ÛÚ›Ex2[‹q´rÁFWç_Ö ?²½Âß3¢#3/¬û¯óvØiO÷ ŒðcýîˬhÃø‡…å»V¬*?ÖgŸGbYŒQñ·‡}T=™? ºÑÚøoXËäïîb`KºlbvnˆÙøþg½¹!f↘7Äü¸!ëþ뼉éobú›ÀsÚÛ}@÷#}V|©‡¬”õg§/‘–íþþ¹l÷ç/ë/ý5cYGq^X÷_ç…`ŸÇâ“žó•_›(}vض– ¾Zú:_îøz¤åÿÅSŽx!õ„›±›€ûšŸGááç™p“±áÔü¿ÕQýiª?7Ú‹›ô˜i›Àmm³g´átZþ_4ýìÄ繸ü á6çQ¸áÂy&ÜŠ`85ÿoõGTšêÏöâ"Òö:¸$ÅñTÛSõûÖqá{õÿŒìÈy¾ø —÷°gÂÕ=ðUB|kºœGáê=FVɱÿÚ¡ÉaÕÐÓ \eo:-ÿ¯m <¯X1˜þü׈ýaEa:Zö“L§ hbPl¢šüáÿŒ[Ä q÷ø¼£:îVª¾½ªm¯óßf²óˆ–¼íM^–ýD¼Û±=ú[óEFãnOÌyŸGà |¶'ÖuL§åÿµÍÅiòäÏœ¾=ñŠkD‹ZáfeMV4¬ñ=pÄæCýÒhTÿÞáä$#;°v§fôñÝaaðy4–€ÿ¯uÎ{v˜¿ÏŒ÷Zþ_k0b­ÄóQ8üüíQ<äŸçŸVu;¯9½í8d§Ù?o‘uBºgÃ<£“•ÛJ<ßÙ¬Ó:Ok\²æàßÖÈíÅ Bøî£ðŠØêsy{çݪsÝí6—¿‡…Õ˜x*tõ“çHÑWý~Rô±R`.”|f­É_ºOlÈŸãznÎx7eþªSãFÍßýŠäoÜM@ü¯Ç|¢ÙîÃï{Ì)ñ}çdó;vCp̬$GûZædÅ´¸ãpwjvgãÎ'Âm…ΓãR5ß{•ÛËXÙ÷’ïøèí™í'-ÿïÙœ|Ú3ñä&àí~œ9ù†Å¥bÍ-Ñ¡d|šR¼y¸´Ñð·ÑoCqß{ãí6´ü¿hGÖE›ñä&à׈YC[4´%ÿà[CíyMNhòßëw?úù‹ñÁaU°‘ ºÓùàÐs=O„îéyr gŒªÿ·°¿•±rö>3¶hùíír fòçöìÂí±²=جÒíÃûcŒ-õæõæTnCq½{Dº Ew:-ÿ¯µ£{ŸÏlÞP¼â’×ôÎrŽÞrŽîrŽþr5t6Oƒ„ý`ÿÜù±'ÙËýœî©ÉMšŸ? þϸF\‡ÅŸ6}“NÿÌy7é´ÁÐyÄúˆç_=¾¼û_yUöÉò²m:–ÿ×6‚çìÞiÎè5Û£{|åûøì¤æÿ­þˆêOSý¹­½}{uJǵ £˜ýïñ÷Ì™ã^P,ÙMBÊm/ufBïè½zÞèΆ¨ÝÖJÃé\šìÞÀîÅü½n¾='ó—÷ÂavÕÓrý œø¥Çœªÿ×®9—§7Ö ¼Ê(îè}çŸ ÀUì8xù:\ÜoáÍÿÚ›ÆC0°ÿ–cº©¿U>ªZÇõóÿïÿù¿ÿö&ŽSendstream endobj 6 0 obj 63857 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:01-07:00 2013-08-20T08:42:01-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000064153 00000 n 0000065723 00000 n 0000064094 00000 n 0000063963 00000 n 0000000015 00000 n 0000063942 00000 n 0000064217 00000 n 0000064258 00000 n 0000064287 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<63157AE85A79053A385445DF480CCDD8><63157AE85A79053A385445DF480CCDD8>] >> startxref 65893 %%EOF ast-8.3.0/sun211_figures/fsexample.pdf0000664000175000017500000004246413004147321014475 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí}_¬·ÛQ!¦”m D#!\´ûÂb`Ÿwý_oB¤ˆ1€$Ö¤ÑÐ|ò§v4€ˆQˆÄZLL¼ðB¼àBH.­jÚ Üxi iM{QI¸°ǃ¦ÂŽó<ÏÌz×o'&„ SHÏ÷›µ×»þÌš5kfÖÌšï½?Òýÿ÷Ÿ=¿{é/ûïúþ»ã¡õZ[¹ÿ®»2g}Hí>÷žJ»~•Ìqàß2R}8íߣÚwöo;nàgwµâÓ¼JïrÉö#­’žRuµ¹`ïõÙ]”Xïüòq•¤¡’hó´Rë÷ÑkÀÏîbdQòxc’˜[´pôúìî;ÿÌ]"Z¾¹Ï#‡!´xÉ™þ-½ =ÇY‰–Z3ÿu؆3;f°JïÒŽ(•Lΰ®6ì½>»‹’jõ´6VZØV´9j P½lã¦V‰¡ÅÇ~}ãsó6Ž^‰–yÿƒ†šo´ÿýÍ»ãþÏEOPôÝw߶o¬”réåC~•¤Ò0ôt”„sÎDš+`ÛXYE‰ +Ý|’ó¡½áM.Ø;}v%iN {3JÆ`Þdê“MDŸ?»‹qE‰-’¥(™U‹äm¦Ñœ–O§¥æ˜‘EÉã]Œ=JbnÑ悽W¡¥c_}/7xá^2z9ò‘²u÷ž»rZGÙ&c´eøÉFy970 €V9û˜IÁÏò¦ÿ>òÃÈ@ ã°a¡@é4Æ3Á¤l¢¨8óCÇÑ¥ NVïÙÝU2yÖ´ñÐùÁðÄiVÊ)¼áói'Oéê*þŽAصlm³™®‰Mßõâ;¼Ö«YzÇg¶ámTü|-ªJ·’y>bnþÑU`øè(±¿X'¶NP³¿7Ÿ~ûølÉ¿$ÔžVÏÈ äž_çCMú Ú)Ÿþ';|çÁ¿%`¶‚?Úñ=ÈŽm\µcÒ¶ŽÃÆc8ë ákhô$ªm་4¼äÑèÇvV5jJ'P5N£˜šŽˆ€7¨ˆ³Vãçu¢‘‘1Ššˆ+ÙŽŽA® È(ˆíä¬uìÆ:­‰³ˆbp © í_Ì* TÛ¶4/‚ªn%F‡\/8iœbxê`ýa°]BFƒ ²Ìø¦ù¤ŒlìßjâN«€í[ÒÓ¹Õh§[‡Áã¶åÏ<“Œš°°Ø³F#ÕÈZD°¶¦uœ½/ÐªÛ À 7xÇö¨hÝf¬å*<þ«Ñ†/uEë]”â0†oôzä«F3d °<Þ¢›Nd-FmªØð91ëçV2À¬ ?L°fBB*Èý¾Ù@Î~ >›`ÙÓ‚ŸÙ9v¸×à_ÁøÛÖ+a=QÓñ×3;J"4[Ëfhèk:ù¾™ø<9|ÁömšâéQÃèprsÛº ×cƒ:®’j‡ñ´6$¶)iÌc£‰ ¶/L8I5^#Û¢ætµ°àfÔÈQ]%¥åióp²1zh¹k Hs-×Xcµç=úkc÷Ù@ëÎÇ£›£ WèHí Vè‚íƒ $¥«hUDn_Î Öpí‹UbSæ¡…N8F“¬0&;Š&þn’¡¿%ÃL"—í•H;Šñ,Š^)ñDmcŒeøoãn-“ÄOñˆlˆ:&ÈÒx§f<[‡Ž`kÖ´ñ U°áÞ 8 0n?¥†è»áŒ§j¨q·=¯ ý¶ ãÇå*eƒ#€/=Ø1Д“Ã²^Å~RÁÖ1ªàñ~ÆršˆÜ|HÆAš }.PSê5]ȺÁO“ÿ6>yrK2YÒØVY$U‘Æ`‹SRìênUÊ9ƒá7ì=bžåw›ÎR±|5o;Ñ°¡ßÁò9ËïbÊÄF'ž‹çG'Ó¿JÈæ{í·?ƒÛwCX³LW/ö›Ý£A œŸEÆÝdŒ)Þ}`×uËÜ6žõèâFƒŠÃ}Ô'vIG"klõí¸h×ß{Ó1aÄ¡ßÔ˜õ“ƒ{$ÀQ›¨Ð­Ûî½Uò¡ 5W ñ1Žäx.A2;½E;<úY.eC…"ABÑÙÀg‰!C·Å9ãpï@Ñ@mIBãÛŒãÔq(‚šË…´‘!ÉÊô›HÒOG78Î=¾w¬KÃh¿hŽŽ¥«Dh±®éEbæ°%­AEմשžÆäï…!v$O~EH²Î(CºÎ—)rlЀÿý‰bPé'ù#Q@„BE¬âÅk·9¯Ì(ÆD¼së¡Û°Ô¤×¨8ŽÐ@‹¸vytÁÍ?Aü,6©Ò”ªçV’œžmŒ&\ÌÜ|ïò¬Ÿ¦ø>Ä O2·ÆÓ3·žÎã~œ” 4ªÁ©1Œšˆ«d,Ó°}‰Í†³Ö <# ˜Ù´iô Ö ªŽé ¬`ôÜ]$‚YŠŸhƬp2í˜aÓP°­z‚^}¡h:vŽyø¡îËd'­]ÞÃŽÈ®£#Kû¾•´…yH¼Ni“ó:WÛŸäQîÉ «4NJ!83”*±XNh@Ê*ëÀ^ó‰}Ú¢žÛßMfqΰӀÔ%FÒ3!&¬ùš¸]| ¶umXY}à%%ˆïµ£Œ–Ó¯>­;òùÝ×½ãî¥wü¥û¿õ}?ðw/½ÓjݽôîÏq÷Ò×}ËÛïÓÝK_ÿ®twüµ»—¾á¥·¿ý ü–¯ùš—þâýWÛ_Þþ¾Çxþ=ßoŸ¼ímwïøúû¯øWÿçŸþ•·ÿ“ßøÀÏÿüGÿ÷G_ûÿßïôŸ½å ¿ô÷~ã·~èmoùâ÷ÿÆoýνå‹ÿѯþ·ßù;Ÿ÷#o¼ûsï¸ÿÖûtfȤP°s¦ôùUbz›Lr§,95Óœf*Í^CËRνĔë1n¾É}ÒÈm.Ø{µ6¢ä˜3L*9‡ÁÞæœnÖð^†Ú©‘E‰©ž>ö(‰¹E›k®ÞëeÜmISÊ3lÞQÍVš©~¤ê6²’d¹phÉç^´dGJr/iosÁÞ+Ðâ%©…ÝQ•æ(ƒ1¼ƒö($ÕåÅÿf¢÷Äo7ôÙŒl,Öl“9ÊJN(* 6AÈ׳Ñe£n”fƒAʨ8Ë µHÅKü<±IÂì€âƒ&Ì!{ÀÇ Õ·Ï'Ž3+)‰1E`Â8eʘ D ÅA#ª“_ά…í¼È“] DTý%h²dF‰¨æÌ°E½ª>J’LS ##Wƒ§£æ€Ì2N9ˆs¶ëS€MÇý™š&CÀÄ%OÒy%_ƒÌú^£q,˜¸-‰Á´O‘$hŸÊg¡%Èú¨™ÎB IVdzÐ$0¾06¥­F£ ÊàI‚X°É*4R]%£‘'µTvÑIAsÐ&® GøýàZ.Âèe³R•£ª8A±†•ªÀ3U2•‹c%²S¡$wܸš”ìðA†ªÃä µ°í5€ F!À$XYª4LvÙÇ â¨.Vò´Ï 6ö¶ªcÒƒçn”äz(`S·­ã 6j®’:!Ö åpž¡Ôã “νƄ%jk!àÖdªÚJ&É`›yÁt ½Š á8«/MÃôØa›‹?]à|(1 Ø$a¢@wG© ²' °V­’£Ç`›ò˜¬ã‹(áe$wÕ¤µ*åÒ5ª”špg èÄ`ðgÛ-UxÃþAYæÜ“›(q£;`ì¯ cíóÈ@W—Å*MfçL:¡£ú™™T]¸5 Ï9i::Ò¦hÝJÖŠ5Ö8qÄ\ Àº¸wag§LV«†9¸„1,ÓnŠßžÄvB·âJ´Yèp<¾DµËh…Q‘¯œ²Z9ìÓêu«uˆ 7%¥‹ë"s´'I×ò‘@‹M×N?akóƒ¡ÀX1â\XP :Ç®cÁàS»²äâXpÐAŽ63ê:¢Ÿu*¬1štô'¿ã8°ÑO]ûjå [70µIÆÿr,Â.¸í™äí ;±à–.Ím3¢_¢‰{¯¤thkujœ×P½-õ¡‰o²Ÿ-FÐ4¯×bŒaø¸ûÂU¶!ã±Nx=¸¡i•8nºÎ°§àÂV‚êg§Í:µr!‹ÀB– …,…¬ÔhÉ"²*Õ`ʲºÕ³¤-ÇV×Á°ÑO?9¶ì4Êu«1¡Ë6§Ž.þ^èš<üukŠ6fÛÐeL¬Þ`Ë „œÀ6ŸBV :À¬ÔÔ}1å[ÝŒéÀ“ ˜ðye*PbRÁ)WËuL¥IƒÖuL]ˆˆ¾b8œqÎ¥F“1ᘭ°i©î`MŸy¨[v0¾u‘\MZ ó'8žoÿèAL·ØäÊY-+H"pÛÆÞ n »Þ`ƒYÖ¡€\Ïï5$`X v’u­gð”I«à $¾`bÚuÏG)T.$#¡Sâ6ø Y‹‹Ì` $AQCÆ!âGíZ6…®æ •'>J¦ s»TQr=$D Ë•÷±ÅÞW Xü=¿ç–ó³#Ëf´.ÐFǹÕp´'SRÐc9ªæ s¡L[%sÖFÏùÛ% Ÿ“¤ÝuÀ¯9-Äzî5$WRˆ(SXI]¨tÜ ÙjhÖÛ·‹µæn7ñ®­¤^.c³2páöž$ ¨,\½ÓÂuþ,\½»…ë'~ùMíOÉW¼ñÍ_òÖ/ø‡o~ÿo¾ñ}ö oyãø—Ÿú¦·ýø§?òoßó;ïüù¿÷Îþ‹7ÜýÏWÿµW?þÚ/üîï~üc?ÿSøø¾÷¿üU_øí?öÏ_þö}Ñ»ÿõñ¡/ý²w½ë‡Þúá¼úÉW^}í•ÿõ­Ÿþ7¿ÿ©O¼üê{?ñòO}è—Ž_üÊöï^~ß~èCüØ—ýÕwû/ÿú‘Ï»ÿü×5Œy˜ÆmêóUÒ³{6®°ÏÓ%ÅÐH¡ÙÁgwéÔ!ìw J๠’©ñø7Ú 8z„¯Jhת“¾6*Á¦EÞb8+F—›œá£Š}ØËiÒ§åM}.“˜ ¿´ª´Ñä}º™¥%yÈ©}ÛDg+øHò—S&sÒÉhÄ€Ž Ú Ø;:Tn«¤¿X÷—[Ÿw°áž ã*>4ì(‰iE›G¯ËÓñs „¼Ž)ÌNá ûFOtU›Fã¦[õ¤}ÐAÊfÂuªiQ'\¾:/M!×áw;uýóìŽ`=§Ì`‚¦_Žáîĸ¼Axsì}Ô©K‹g«×Ê«^cԸ∎¦dpÏà[Þ‹O«„ŽÀ¡ù[C@›—Ù×ßø×?ðÉðO^ß·¢»˜%Þ>l&ÒfËQj/x¼ f¦ ‡¦oöZJpmÏ‹þ ¸0X úqbPÄ­ .¡½']>ãqhžÔóð;h³è/°¹LûYýR>S¾Äµ5ÚDåBO 8 :J)ð˜¡ë‚Íd[eû Úð?ixiËÜœ÷ì'¶€/WAUH€P{ÒF·ë6ÈÉ“R¨àª°–žS_V®¦®¢:ÕêWÑQ5}j‰£„„B—†2žB^ãbû$éô,'‘NóßØm…íž™„1ºº™¤1z=` áhD·º#ü쎮€­ï5‚9Ë+NW° ™¼ RÛüZõKÂÔ!mtuÿ˜©OŒ2­ÓW [Ò¬$‚ žôzÁ^ÒG8Ǫ³~Ñä&¼fâ϶[¥ë‰VЉ¡µÍÚ•Sa)nu&8Lð=Á(ê”_Ã#J(æ „¤&!A¨|4zƒRø¾¨ÚÄyÐÆ*c!à°gï«èF¤4º Ø~…§‹Ã˜p÷ã"jTêC תò+lD Ò»Júëdûlu[‰«ÍÆ[æ€ÙGƒ­ëªaRcÏ[ ºŒâ /£Gqç–žH9ôÒÃ6†Ÿ˜Ó\°,Ãά¿6+Z°MµkD,©¼-–Z&•¸ÿä¤óœÃøâ„ä±ÕÀÖE ãhsƒ}ÄüB%%îýØ‹|…b\T‡àV&·† cWƒCgUÐ׬ m“ +fãæv Ú–l¾(‰ìB.6ˆ<èu˜Üß -Ø­bþw¨ öõÁƒãFõó‘[½çP›.ôèÏé »7oúΆõw#m„½ŒSîÉvdN‹Ùa¡O2!øÚÚþ/œ(a–‘!Mz’‰ ÅH `ŸjÔ¹«Üh{x¹Ág‚Uú‚r¡»\÷IJÀÑò¤7ÅÚßZ²N½±J?Xü?›$£Õù¿é¢‰[NËüìŸÐÅþ:FØ Xæ Ë6Ÿk—Ûþƒý³^Ûw|ØLI[ÅmD3¶íª`«ÀCü†¿kU­±†øè |Mpð,ÇÔàÈ’àýÚnPä%B ¤Æó謚~>á2)¦n˜"˜Ê…–`Š.•&ƶTÑû*~½úÉW>ûÚG?ùÚ+¯½ú{ß÷ƒ¯}â•Ïþâßï/|öÇ~õ¯üÝøÍò®7üå÷}ìc{õÑówàG¿ô˾êýïüÚ?öy_+“ìTÝcóFžòßê©Jõ×¥S-­5ÑÃfdäHè”ómw="´JbØó»‘Ü Tä:Po¦„µbç…[,–Ð"XµvzdÚ™Õ^Âf†l˜î=ºÊ4溿Ç›~„ËűÕH JOÕ•1o­çXôÅ·Ý%îxôËp2öÛ5œb2> °ƒíÎOZô…[ŸÇn ¯‚;Q–¬ÕZ8ãp#C«ùÜ6­¤xDÝ¡¸Q+©I#Ç¥¯éhä¦ÓÛé®L´Š3\²g/IÅK’»L¥Ã1¦uNÅ=_uf’hΖ,Y}ÑÑyΨ¾ kÈŒpáG1­î]]S‡:ÂôluŽu¼Y§2£/xµŽm4c„©3z»€#§ŸñU p«ãH¾Ú‰…¸úŠÅºÆ ºFk~MjÑÅšxµ"ˆ$t.òmd˜í¾ÐÕmºÇ¹HHÛ1A  •Xú±H(‰„–7/k‡;U©äð¾RxÝáêZ[7ÂñÏuæá%«1„V_ÝÔ×pº[¯!·$ÓêÑÕš:D’ÐZ´¨q¡W;çØŽ¾æ$¤ÑÌK†s–“Oj,sxLNe"@üóœW@òÕN,ÄÕW,Ö5žXÐ5âXókRA×ÄÁŒ>GBŸ#¡? =¥í««¤èd†óÎâfìêLë”˧ÚÙú*<ÇiÃW ¯Ü­¤¯;‰4u¶ˆ’.ù˜U}Š¯‘Nõ·«ÎÔÍÆjÅ\ýô¦7®±ôÓ‰b·ylú5'SÅ âSâÕzjÛ¬íØvQäÚf¼%Ü°wÕ _íÄ"\]ÅB]£‰Åܘ…/ø5« ŠM¬y‘p^ .ÊÛvKàÇý„·oa^¸­$îqü$nûÆEîŸ|Ç|Ï7}þo½ÿo}Ãûý›_ùè+}í·øS¿÷Óü/ï}Óý¯üç/ùÉð_ßóîŸûЯñ¿_þ.ý÷Oýè‡>h"õ—â¿ú®Oú¿¿õ­_ð3?óŸùÌ›ÿñ‡?}|æÇí‹ì¿ïÿ»ßô5âMoþ“_û™W~îÕo~×+¯ýàÿxù‡öSïùÙŸþ௼é+·XŠŒ«.8£Az>h çË ™6,ÇÍ!Ã\b„<Ê᮶Àgx-£ÞV(rÓ€…^l\üƒ('`¸žá ù]=åo–àAg)·‰!ÁÉ.ß÷k‰Q8€±”á÷'=ã.(IÀÊ·?ý¹j¬A¾1lØg]ö“ìFÛ«¤èVÉgpâ9•L–SöGÔ‡íSˆ³eŸx@}ÁK­ë 8'ò‘áº7ÝîtÏ„ â U¾º ¨JÄðÎ9Ü #¹ç–s›s ݵÝœb*8†Â*pÈC ÖÖTîO¶WBs‡ŸÝ±kÓz¯ih•Üû: D3‚ ŽUp§ãô8€m«v5þFêJÆ!áæ·æ{‹ e@@ •,zS‰Á]ˆ…£”€Vå°àAÒdz3ðf¤}›ˆÌ-QNõ•p©ã{„ÏD6]"§Ô>›*#i­Ip¦k µ“di£éÔòpX“”‡á™T?“ãZ,€Sj6T³èˆT‘D€•kÁ‘pq‚.| 9·@҆à¾p/9]ìRÇžÃ{T§Am•´âJxIîßñbÉúªÀ¯9Ý”T“pG^/.¤ƒxÚ;Jä­œFˆ~×WÅÅCúj¥›:ôs|Ý’¦šÐΡÀ£KÖW/öþâiÈt2~š¨ÍèLzðb$ôœ›Þ KÂâWðܪŸÝå¦ÛÞA¸Møòa«·)ï¢ÙŒúàcs«Á»Xõ€ØØ A¯p—å ÷~ ž–cySú|ðß¼.ª©Û,…Á²¦PKÛ2‰|@¨;pµzýy‰ç,ù@‹â›9Ë~d¿sãÉ“á{ÀÀUÄ!¿GEÀz°SOƒ£õ’Ç­Ä:N]%t5ÜKl9gW >,¯6Ю¡¦¯NÀ>°Y÷l±|œ ƒ‘9ËC8‚éšÃ€ ¹¡îý°€àî 1š½Cýƒi Üw U&mÕ_°Áw¼‡e0|Oë‚QýÛŽŽaƒ)­g†)°Å¹Î½Üe§CCŃƒ% ÐBd;_Ž@,¢ÐlÙl—¦ßVÐ×/yϲâ6z=7ñ"¸Æ_¦6 –[ úzü¾Æ_E vQ T†S·ìƒ+Úÿ‚ñ5°Û·F{­_ ¼H WíNQÆèó…R%çÚ®¤JÖ„†8yì|L#Óè,o€þÔ“ ÷ŒÃU¢`Q¬ß‹Ð¹â" Ïö·3‚ÎÊ ÀÔ4®>ä6Ó4%‚0Ÿ"sd½z!ê6˜~ãk\±Ï­_èÉíwÖc0Xk|&%CWå“ŒN_¨¯ÇF¬Ýq0 /j ´ž>8‰ÚÁg2$~á%¸ñG“ô¡äd]kæxMé«Æð@|“Õ·²èÁ&”ó"“‰{´‹Lf*;™\`ÉÌÇ ™Lž)N&™Lú=-2èd‚wv2ñž62¹J‰+¤¡ “ÙŽ2™r™Xd2õ:D‰@'“ ?÷Lf›OÈdöã†LfÏ‹Lf/OÈdö±“ B݈`Ô§d‚‡v2™ý–L¾È$JD&sL¼œtC&²·o5Z»!“E·dBDûñ#™²…Ü€)“³:ãßp00ô ÁµuÁ ÐÌÛŸM1èúšÑr¢Æ2vôTcÆ Àâ(²Ušˆ¡¦ÎÑO…e‚¦¦@xFÜø d_B?­HèÈîÂÏ PúDI¸ñÈzÎ| ¹ gˆ:ÀSådº?:¨ÇÀ´ ^ <Ü~—mîüëÎï¦ÛôðIÙ!€®Ó€húâót”€J#Y2žò,¢›I æÚT=¿5àÜI®Ô@ñ§·ÏÊN‰M “²A"éË„)(Óã«d]à¼5ób>`ã:s/0˜"K‡x#8¯W¿ç¸q]âå)Ÿ%r ìlïfãìW^ö«U û?ßìW¯ôÞدls·_]˜–ýªà&è‰ýªà±ÇË~Eülö«¾Ë~uMjÿ½ž»ýªà-áÍ~E¬ìö+lö+ƒÛn¿"|c¿ÚJ–ýŠwþ @žþâ»l©ñæ°äû¾ãî;Ã¥È]òyÐÓ3ÀyB½EÀ‚ ìâÑ~Ú;ù›í2Ææÿ!mV:½çKp¸Ÿ›z,-Ú§·ãý³»­€ïV]@9½d0ó¾äÄ=!Â?eW”³?DÈ–ïp²XϬӹO—1 e™U†ºø`‚•÷â4]áÍÅ¡Û Eåà‰Eˆ¢“¦išbùsø«.‚NY%Á´pÀ¡Y/)Ÿ‡¤ý ÎJ #ZôÞ·—à=„¬3/Éü‹)ÿ™²¿×ù^&ù!]Ìq•‚A¨¿Á»X<ñÅLüK>µ$ÀK¬»†5)©?wè”À72Ï$r€VÎPT¼KæRñOà†QÍÅ+Ö—WøÀ3Ü ìSæü>ïC'X"³aqrÉ•¡)#0®²¤ b@“¼Ü²]2K‰ñ%Ø·Ú)ùgN''û©ìä}—ÿ.Ò„HG‡š¤h7 Lý[!ƒ›áU°Q|Õ@¤ —´ñ}« Æ¡.`”" ®“ˆÓ"qê9-˜¶ÑžWÀKBmQôÖH¹s•©AIñR êI«‚÷PÝÅŒÙjpSÅ•†S`S:œ Ž$EWIÐSÜhí”äét¦x§è«¨ÑªÞ(å‘_×8)ØhšR'`Ò©·*Ö@þ[sãc5#s“3¨!×N²LDCKUGC®EÑ™? ‚£Zy\_oöHáHeS<ÄQ3æ¨m‡€·‡Œþ<|{ðMÚzȆ3¦0ˆf%b$ø#¡8õ¯…Zû¦.ÆoGÖ…*¼ Ð|SQÉS-UzÐJWñœGõÓôÔH¦ö)6!AV›îë·óGAPŸïñ¿/ÃÚˆh‚ÛU\ü·«P(_˜l÷D`P×ÅIµêjÊÎQ!YÍÚIµu„ô2· eh'<ã‚Ü2¹iÅNÞÁ"=–ä<"=¹ˆ@dê×0OCDò:uøržì\:oMGØøO¿S¤Åz<¯d¬ñó­¢ó!Ä#N…*¡é]né¢ç1Hö¾ñÖÓ;ã¨ô=ÝEåh¿,('i »ÌÄw162CZ*¡,È®y‡¨(¶-‡ÄVE åÚB™+ $0@äå“èHÞ «GÙÎÅk:A9M©)V…äÂŽYdJN&-‘ñvÉ‚CA¹ ²$aÀ]ïN [I ] R(ÑHúo|ÛÆ•Ç ”2ç¿]èQݦÌ.Ðf®7ªP³«nH4r«ºMì^ªÛäÔÅ1ù{©n‚¤ºM0]ª›–iWÝÎH)–>»›ÏÈÑ ÇŸOr†>ÃV‚)ˆÛ9C× ÝOtbmðÉRgèÑÉâçWø÷鹶žBÎÌñ@eÏÞš-Åy\8×ï³j3žÇ%ß?DòåÓ™´âyâÉ^‡}›!ßò­…L!|bRÒÑõeYâ ¢2÷Ó7ñÜ—qü\Èð ±b8FÛ<'Óý»|I1é‚`Þ¹N4¸Ï¶›àž¼iPxfu}Ÿª[?zÐõN)ê¸v™ð0ߦ^&¤>l—z™èCµë—ˆÖÜþ Ê[ú%#y/“‘µíR0Ó!sp(˜é*ì ¦"Èç½+˜|af܇~‰¡ß»‚™Ïó²Ì„t…›†™à3v­žsÉnïú^#›†¹ÀP1£ÀuL~ž/’Öm??Ò!m᪘––iÓËOÕLF·^z&ñCÝKz&ðË:±¯IÅ™ÎàæMÏdäq»ôLbeW4Yp^ŠfBHZŒÅ"3SU(š[ÉR4¯šçüU)Ñìpªð$± !ª˜·RˆZíÅŸƒ¦“DJîWõÊT=yð:%½6:Á·x’õ2Šß4ìñª”CxÚ÷^Ò<¢öu>ý½“x(âuJzñçFä~±d}c\%/öþâ­º²Ó`iìiÌN×u8|ÜÀªÈ³“ïÿ*Èèƒl´zv:±Ø•Ž ¸¬ìt³g§;˜Î`…–F/#GvºU’˜Il4¦£{Ìj»0;?§ÔIÕ0{v:ee§“ ÙéFëêgú§]é ÆðàÇÞe°m‘nè¡(y¼J ¹)]|µ—d³ …9Cžm1Èse§“6»²ÓIõìteŠ©ÀIº«”Y…pu¦)ò¿ d§‹½„5Ùé •3b§(;Òn‡ÍÃOOɧzy‘JºÉN7•m *"Àü²1);]€ÇÊN—øÖ`F–\Erñ:óÓe7pzv:‚%²Ó‰H<;]:%`fÏNç!ó°g§‹QÍìrÏy æÈNÆŒs|(s8´5§£@‰ìtGd§8•Žb¶‹‹ÓoFζ`^B3;ÝV£i,§²Ó!èkiÊ‘9”o‹¢ÍAzK’ç(`œFÙéh£J[3»Š¯ìt >#;]”ð „V®@"]”";Ýd®ë«B£5†·ÉM.Éoo·÷º‘sŒÅÙ³Óexí‘…dÏN‡dj‘P’žCMŸ0c˜¦ü¯fÄNv&50÷ÌìtÏNçàôìtA€Ðe˜ìsÊŠC¢vVv:…ÿ_5枣ÆŽ5xvº(ž[î`vºŒŒÌ=—ha ø™²ž{ Þo-œÉ<‡Ú‘âÊ(1@ì!îA•!íô“se§KCOD|]ÌNG`z2¿cC— ìÙéÒpôD2?>Sra+ ;¡eO ÅiáÃMÁ©eª›1<¥p-Pv:Ý‘ž® ÙwR¤ŽKaLôi;"V _±©»êyuK0{LÅܸóA9ôâF4€'‹FÞ»`¤bÛjT¯ÓJ.N×·Ùéù ¶²²Ó¹<óY½5q–ì¹çR÷³~e§;˜îªqqï¢ìtÈ{KOÆÙéð>Å%E<³8]®‡/`Z¤»ržù5 @½e±ÑéÙéÜwÏsÂ;0ûÑæÙé²2ª•Ìä–† 5Ž)dË>Î›åš &^ËÕ™|N}l`ìt«¤0;Ÿý-ëì(x(™2hœ.¾£'þªhÏ aÀÛøœs¹²Ó%=|ÁìtÌ;™´ñN¢Ì¥Ý£ÝÎéXÙéܼj$—+ÏN÷çÊN—¦NÑÓ³Ó¥)1pzvº4µÛÇÊN·JVv:†{¥¾ô”ç[‰Ô=FÎ ¶΋w4ð$1Úܲ‡À•3ˆ,-9—52£Ë'ÓÜ3Â<„îh$˜O xåÃÃ0&<ÔE‹@)„/¶~Õf=<Å"w|“ÀïàAûš*¦Ìf¥î’4¥t<Åjº*tŸ@J^È=5ü%m¥/l:äÏ$Ç¿ìâœ5(!çjŽH¦ìÒÖ•Ùíö@‹Ì©.˜A“‡,r^#OF;“!ƒG Œ D!jö]JÄNêÝ=5d̦ëùkÿ _¥žƒaÉãV’øJâ«­ÄUÄDÅ›Håá¹esXz bÕÀÓìä\%hÎXF(꾓q¢3íÃ5⪔ot¸jP(.|PÁùžÓ­÷nÏxÉn˜EQI»O–™†3;GWàëÔƒ.Nv6þSª¸‚myi¥·®’´Ã0Vî·zÞ’º`’×IgÕŠy£!™Mæ‰2¥%qG6ôFÃ’æQ_ÀÞ?6 Fq·\÷!•ûTÓxr!’m?€àj·@pì»=€ɶ@å¬7àíªÁŒuÕãýªõØ Zꓨ†+²@5Í›ˆÎ7¢:÷ÕÛ´ÀµV‰ |¿@î»=€ªq‹ýZh÷¡´O BáP"-÷¨œãæZsZÜ/÷¨¦~sñ9÷›¨%ïàý|{]%×Ô’^ø‘âƒø¼P{ü7Ä ª.x¡Z÷t«ÄÙ0ÜVéÄ Ý—ß{Ф¿/„-)¾|•)Wš®¶ßPy=4¹—KB¯#-…¶1ð©ï|‡îà§ôk¯Ñ+ÎëY±U2¬ '»&¯€XBÄÝ_ñJ|ÑÞtÍõMöz^¢\ôZ–Žª—íÆÏ ›šëBú±®2“×ñÎö¡—”ñt©ÌáÝsG¥Â4aÌÉÂ7Äùî"’4 f" DŸ!%Ü)Ÿ&’8Tk¬wõ*tä6°ä0@Ë9JnId¤JàÓ•âk¦(×#²³Æ˜M7iªud˜Ñø“\qX2õõYü-眕¦#ɯrö$žÇá^æcêùé³F;È+8šïó_æTýÑ5¯ÔÏ\sOUoS~¶:ýŒ–£¾^¤Ž¾zÎOÆÓâiú5æÖWÒâžÉÒnæBH;~b\¯:Žç«µ«¯µ^kà•ÃKø>‹\u|>+À¹Õððr¾ÎO³@&+Æj o0‡Þ·wp=F}*”ôÃߣN0`Ojå[ ÖI¸|fm mÐ! õÞõ§(×õä úzÖý1†~ÁLû­¹®°ÿUŽpúÕê*i§¿­”£ùK:Hå¸Àg’¯¿ó¥íõœÃßÌ$8•ÈOŠ ûL)ÍŸNâ š©GË•%çÃôÇl°H”ÀE«ZÄR­öÝWæ=øùàA4½~ÏÍçY²)È&¨YÛ;¿ˆƒÙƒ‰hZœ€L“É2—xàOƒäŒº(ÓSB–G1‡~ˆ®ŒO6²o½û¿J /_endstream endobj 6 0 obj 15318 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:02-07:00 2013-08-20T08:42:02-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000015622 00000 n 0000017192 00000 n 0000015563 00000 n 0000015424 00000 n 0000000015 00000 n 0000015403 00000 n 0000015686 00000 n 0000015727 00000 n 0000015756 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<9DF078A1C5B07E4B0EFF6130F3FD014A><9DF078A1C5B07E4B0EFF6130F3FD014A>] >> startxref 17362 %%EOF ast-8.3.0/sun211_figures/frames.pdf0000664000175000017500000001603413004147321013760 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\tTU~ÇL’B"Yõ±§Úm%™÷û¾çQBµ‹SV·‚`"þ f¨ Â’(!àÚžÓØžE·î)Ù]"mù1q$€;™&©gÙž¶âD3œ¤0DiKÇd=3œaæõ¾wï÷¾™qrΦý‡P'8É÷3÷}ï÷×ýñ>ïŽÏs|™Àñæý½¥Þá|qÏüÐÁ—)ª,+÷ŒCSÔ2E8Qäå2]áê3•!…Ó©LRDN”x±LP8¤èYò‡€DrEÜAÐÍKíKð‚ÊTÚ2ét‹AQ4¢ÂFxó/Žªd•7/>A6U»q;Àr@À3PiˤÓ-Ž§ÿÄ!à  ]°Ìñu‚$A4!™º‡àÏU]Éq@DCD·C•qO¼ÆQ  ™L»ÜâDPE«o·(ªf^:E´ú‡^AÞâ †€ƒ*kÔc‚P¿@#ˆ´K+·Çä!üß³žûÓ¯c±ÙêxÄñ¼CåiÕ)‚iŽ‡*âš–u†¸"JP™p•lu¬ç¶9TŽ=I•¨6jT0ÍÃ-q|ßìp]7‚9ny=Ycˆ›!"ÏÓAÅô3ú•¡%Of¤kÄfŠ~y<8TE†ODR6"JflTI¥²lÅJâ-•·8ÎQLe¢Á–aŽDÐ5Þô4ºjy }€ŒL­`-¨• !×RíR®s6BLÓ„lçžëBÙÎ!%Û9[†ŽÓ@˜}Ø΀€• !×˹ŒªAJnÕPĨ9Uc#ÙUƒñœª„T ‹@“öSl¶ ¤7 :"·Þn(Cuj*ei¯ oq€e€¸`; àèd2핱ޢ¢j]U)•É$X*EE"\<²øUN”‘Åçƒlº„¤LÄtIPI "(ˆ„‡êd2íë„—!PÑy@Uê’ Q²:G…ˆb: àUÉ<¥}ZAù: ™!|·(é©P«‰l²€ p3û§ká!ü¡(ódÔ!$€2‚è¢JGa»YKøi\媥S~ÚF,ºÒ²®„õk±ëøZåÕb6±ÙnϤ-ÕõˆdieYˆ ½*4¢¤Y2X I•‰L50f†H©3Ð !Ë[Ö•ÍS+X j%hÈñƒ¸*æ:ÇjšÊg;§h¹Î)j¶sŠœí“™s€€i L‡>lçÀ hV‚†?(ÛÍ¢$¨¹U#¨¹Uƒ‹3§j’S5‚š[5‚šQ5,ÒÊ­AÏ®QÈ®*gT ´€z LF¹ƒÇrVÅRvÅP9£bX °RήÖGfÅØÎ1DÏ®0²i;ùf-äl瘌r+L `:ôa;V@ f¥œ]1™Î=Ï!Êv cí¬fÍÉr*󹌆ïí&IÓt|0#èH2“”oà]Ofxs™ÄÜáÑŒ(ð“:xC<›EQ˜4ƒ×ûØL6ß©›gòqXd˜ Ñ£³yàÛEï'ÎþÃÍe—z¹MóJÇ}¥‡{|NW0ˆúœÕ^W€ÌÝæ$îsz]Ön}üñ™Ë¯¼0·xמ+ îhÛìoi**/N6•L¤ÒøÇ0†!‘.#åL5ae®u¯×̾t°eYïˆã·ËŸyìÒiGqgƸË`ìD³F±»ù8ÕiIÙÁ”ŽdND"2wÐù˜2¥£©¬SlJo¼}éû…ËÚ7W\jY;WŽ.¹íÁs®Ü5ðêwlKüè—£+bÛq Ž¦’µñßUVÔüéeyi"nx/–û Ÿç÷*ã´R}2ùå<ñÏý›BÍÞzOüÂÝcñÕÉMœžÆΟD'kœ›ûÖ¿½v¿·xWÍŠ%ëÛøç³xe¶Û“ ’°Ç¢”—!§»­)Íú.‹—墾ùsÍõùö›¿‡Ú_öÍ* xÞŠ¾ð¤îŠzCcxáMøS§ o¯bÊŸÆ6ßN#²óxп½Ëpy†]õ/úkë“ÅËù@ÁÁ%Ç–öoPÜ0ÙµŠÚ­Ë¹wL®-v¹Ž—½òtº­"=äůºÑúÖHiçÁÞ}]ËêÝËù ›嘙5~ÕŒñËã‚E%_A«S¿°Ý:ýðìÇô<ÜÿÐýõÏÙÿà̯ çeqÿöâÏ—4•Œ÷O¤üxT†üÝñ±Þ¸4§ðöňþ¹Š‡èáå>‘jAoúuó§#m¨êy½cÄé:Wµp|ï‡wžçNÎZܽ]ödݧ7ïiÝÛ9㥹à¬b¤dQô|s®2u†TÑÛþŸ_zydNûxËÀÀ¹††/¸›¯pž}%çÖDø_÷@4Ôó“ø@UyÐÜ¿àã_ï ÙþôNã⻩áà6<ÐëKO»jöu¾‡ÖÙ×Ûš±j(Z†æ^e´©{ë~{û•{°/zûß-[{ÿ©í+Có¢-èp ­ã_#ÛïÁ;0¼pàå?O¶=ûþ¼È‘ø™øî¡îêȉ õƒ%®šŽÎÚšWû ‹–/ù6KB *ˆäÈÞåö…:= )’{FM¦‡‰ðlk1‹TÞâè‰)@ðÝ3Ò,: Q¬ß “ɤSóÆ•üÞT5PM%Ëô ²y¤”؈ۖžNi§ŒPÖ WZÏM!4ž [§£4²¼f‘x c¬xC°C¢H‚× rTRú4¹e‡·(YǤ*Uƈv 2ÖA Ä<“ML<L¦½’ |Œ€ ßö[ÜBÏã˜ð¢Å2âfˆÎß WÙ¡•^°JQç…PéÑf€*ñÄ13ºÅüâfˆÉ–@§ä*Éîp+­V¯e0¯&Š'jêÑõ6¢’‘)ð’EÇ(}jÁbä-]#£›A“ÙÌÂrf–) ,ôÀÓÓÜÌøœZH®Îu”¶hg×ÛˆDŽz‹„ð“ȉv!™Î‚ X\û\¶:«A¤ê­iŠpQÔ®B¹(: h"{¸°Ô@¦!ÇÊ{BvErÄÝ*‹?£€›ŠŒ(À ‚Ùu"ñu¢f54Ëâ+ñ¹%"‰Ù%"ÉÙ%²]"€@€&ó¹%"jY%"ªY%BE»DØç ÍFV‰ØêI‰d†©Þh×8A*©| ¦ 25PÙL:9 m·­iˆi™taU D)PÀÓHBT¶ª„-ÀHÐíEªÓ<\ªá{àÿ¯D§$›§´óÝlMOšÓ|n´¼í§+É)c·ò§h:Rœ ÒÌ/M‚S•…ÉŒ½èM$LæÞ Anj⤥6}¨MUTñ-~^bäÆ#6‘Ècgó×›–´f&Ë'Høf\åóE¼I¾ fW$ ß"Lþ¬îF v3HM•×9)ÿ#‰Ò4óÛÓ•ÐDHžÌþë–ÎÌÚ¨Hœ¨ÜXaeºŽ›_½D¦{yO£ÈÖBŽÛLåH1¬äÇNÕzô÷ïžï)Ž|vŸÏçKyð[zÂð5þž’FosÓtÔà­I“?ˆ7ÆuAcc,UÛ¼±zðõÑÚx¶\xnãWEís§*3¿ m'2ÿg ¼ùõ|_úA’5%Le @ä©ðå^ú—þY´4î34ÿ‚Æ_¼°G^À'ç¡÷Ð@sS¨º;ŽÝ)œ(ìF–èQ¼E©N±p,4ú¢/Xûâ-ûç½°Ì1áóÖìª;_µÄÉ¥>a›²DúÔãÿUžž$EøVÝ<¾w£rý')cÓ( ìŒÀ罃ü¿ìßXWò‡…Ù;³oþ¼+÷ÝûGíÑ?s˜»ÆmžÕ=o®yö>l(ξû Z¾œž}ÛÈÌh|­ d4{ð¿‹ïÆ¡HGg ¿èηñimûW/ÏØIe&DÄ‹­ ä}Œz½çãûŽÿ@Дwendstream endobj 6 0 obj 4800 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005103 00000 n 0000006673 00000 n 0000005044 00000 n 0000004905 00000 n 0000000015 00000 n 0000004885 00000 n 0000005167 00000 n 0000005208 00000 n 0000005237 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 6843 %%EOF ast-8.3.0/sun211_figures/fsmerge.pdf0000664000175000017500000013401313004147321014131 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœì½Ï¯ïKVLŒf+aDï!æ ì[¿$ÐAym$ðvb›t4tŽh#ûpŠ˜@¢ 6Ž8t #¶1ÝF »%ü &Ý wÐ’0apsÑÄ–p”ûÖóôz_û¨ø÷åNi1ðßRi¹gâ8â‰_ܵºª(c§<ÞåÔnRZ,»LÇ^ë*ÃSæà—;%õÂ/3®ÊjÊ÷^«ãwÞ2Oy¼ó¶{Š÷ÍËܽ·Z_Üýÿç.’,¡<ÌõÃ(ÿ¾Ü)-6þ[JY \¸¤.²Äqâwu®Œeî”Ç»ÔÃM +-e—éØk}q·s´¨"÷Õk ª²˜xcåÜ&>WPµªj¶~ô¦=´ë*öÕ˜m‡¶#Ò±gZ®½ÓBÈá(ùfÛÕ¢'i/Ÿýìõ“âA막ÏÕÅiø° Ò +Í,*%ä%Ù^Ñœá\HJÍ9Â)?GÝHWžøòÙ_OQOžu›ø\Q.P¦:vŠ¶àÔšøòÙ-åöÃÛlí~>ÔÙ[³&†^Îß}‘z’+EÊæžË¼'¹2嫳,.žOr•ù&5JÿÃjìýMj„ñ‡Ö˜B}ƒSœoP㒞ߤÆÒߤÆߤFȶxc¾A9ä7¨qMÚ7¨1ç7áœ\Þ„sr}ÎÉýM8'7áœÞ„sJ¬:7w;g¬5¡ù–Q¢U·'þJá ëfÅxšøòù_OIªÿ¶¨›Äg‹²S^¾á¬žº£ì¬,éW ~²µu¥`Á^«´ 2ÎÅ{Ý^),ûfÁšøòù_Oa£žu“ølQ¹*Oñí«ðÏ•R(êIâËg?|¦(‘eïº*ê&ñ«Å‘ÉÅ»óUZ5xÖÜDÉš¼yÌý~Û’ÀJÀþy+A÷ÕëÅPÆ/eÄ~’ø|AÔa}1ê—Ì´´“DE3¸ÆÝ¢–%›nZ—ÎÎ×½»®<,»öCÊzšøòÙ¿jQí¦{·‰_¥(jêؼTL<ÆÙ*Mýf,÷üñÆsõÑÏ3ÐíéÆ3MS‰<ºñ\1P¶þC*Œ)¼A³d~µÜÎUÆ›ÔØÒ›ÔØÛ›Ô8ÃÔ˜ByƒSoPcÊéMj,íMjláMjìåMjƒ’Šcí€ctŸ‰âÝ4]#éüf¹tvO_>ûá×(ªËÌmâW)J-Ÿi¥-r›ô¢ŠV¾§Uµò-ZI÷åkO=éC_Ÿrhgo_>ûá×(ª­ºM|¾(©]ÛΔ`Ûä¥à,Yú˜söÝfØV·½úŽ›Œz¾ÛÅÖŽ¢n_>ûá3E©å±åkŸ$>_T²vNSB‰8×^*ÀÂSÔÊ{‰7q-§ä¦ly²3C’$¼òŒ‹ìO_>ÿáë)®kï[Yú4ñÙ¢âTw’óv‰’ƒ³å5y/ßdƒ¼—ír¦ZÅ..¯Û‹ë§†£¨ÛÄ—Ïè)LJ¡Žó¾díï-D9×?u‹Þ3ú s]úM®Þoq è7¹Z¾©ñÐor•ù&5æú&5¦ø&5†þ5¦™ß ÆÔçÔ˜Z}“k|“s“Á~xa¾AqÖ7¨1Ž7áœØÞ„sb}ΉùM8'¦7áœß„sŽFÉ©ÏÖxØ>Ħ•}HíÖÖSZ]B\_Ò^!vmõe²hÇ/îæ4M°¥l%›'ô)qÖ‹t앾¸Û)#Ûj³Sx{¶ú«"«ÝâxŽ_Üy»<åñÎ[î)»¯VäÆVé¶|Xò.êC¶Ÿu1¥¾¾ovâv(q¼ˆbêlOSºAOéÙ°•¹±Õº¨b)uLÛ@vJç1îÞu ëÀÀSš×êdQË<åñÎÛî)Þ7/sc«Udù:InH‹\ò‡‡bZ§©¿›8i¥±Û©Œ®õ!Å)øxÀÖWæµ ¶Ü eü™â°¿×)¿Ã˜¨Nh„X Ñ’kÆêè:$.A8=´rï5,Œ®”Ü f^Ýnüà ,TB¯-™wø|ÄûšªÂ"ÿՈ5Ž µÒ*›Å4ëXÐwKÔä^rƪôϨe LŸÝF{ÊãNYÃ<BAŠ>:=Rpq°Îõa­F‡zo-âßÞ>\7òK"v®|køðY[߬õ´Dý Þì1MûiÉë#ð·Ê¢ç«%(´ Ð•}I2먼RpU¾ÚƒŒzЫßSúGëãCȾYC)‹¤—Çú¼’ô!s­é0z`aÀ%ÿÀç"· a| ®jgŽŠ¶°Ï¥w–LdJ´ÚÄñ ¬14%‹qn_×ȵ¶1¾X’nŒGŽ–2F`Ð\8®VO~á)Éô‹QlÜ «hà^Çì¸÷Ê€3¿oÅ‹V¯Rç2í¿2¹’/y}ÑTÎÕö0°žð‚ºv¥¤† ëú0 â%õ·_à ®±GLÚ‚EÁÁÁÃT^£dKª,ŠõÖÐƸ†¢YŸpS¾ˆcnŒNß:”Ç˼ŽN¨xãÅ C¼¢”Å.kcÆh÷Õ*`&ÑyɳlŒ/–<0Ïs¢­W «ŽÅœjÕNé¤I³EqPC«fÓ@Ât†CSÐ=VX‡¯G\õyƒ˜°:Y³’X…d 'Ç/LÀ+GŽ5ñÛ°¾Vƒñ…RØi M¬ebäتN]pQTÀ5(å®öPD·ž×B†” Ž$™×j™»¨•E1µt$k‰É‰k7­UU\»ÑÆhÝšFZL”#â °cã`ãùÁâ8òúJ©+æÌ1±¡\¬Í ÝV±&÷϶6.X«kÛFU¾úa:¡Z­J1s"­ñªœ“ú*yàÞ´Z…u‡Ù66¶nµråX|c‹mtSÅ&&\ÌŒÅ#Þ86K˜ZMWÜ3=4ÜöƒÕþ%§ø~p!ÛbäuõÞžš•99ðpo †DÓËÞ¬žkSØ ÚRlOþÞÛAÒáCD¡böªF`µ€e-NnT7ÔL„¥ÞàÚ8gœ“qÕK2iî¥ÕeN-ìè°èYjucäǶ{dȶ·¬Àvümm|t´šÐü%€4“ŽÖ6aôÈ%j“i§mz1žÀ‹ZPÚÞ‰^·|‹`«åb ±`“E¬b­Ára ‰X«Ã¦VçÆp£O휵FÇ¿rÌ ra!0rÍp’‹¨deŒz çÕjY‚¨³„£‡ü¢\ºPÀb¥¢îcÖ¾—úpàtÊä,;úPRÌ‹^ÜþmJk½"ÓímjÂstBE˜EY.¢¤„Qví±Å¶ï Ú¯å¨àØ™nªHv´ö«¨ÉFV.>ý½- eÍ®Êk…mXÊ’´[Õþ¼Ö†ˆ«½f›7–ÁŒk€¶1(ƒ‹ž3ÇZö¹z×µ‡¯E,7ŠM wl¬øbñUÁ @”ÙÅ( ík‰%\͸Ò˜gfÁGÀ$A{ (ƒ.Å eIɶ¶HÊäÙ$Ð'6}u¡ãÃM)h˜ÃTA]îAmM„lulÈ­O‹ÆNYì‚û õ}Í×Þ‘;eÐcwá½ä•r‘}íC¨±,Q@§³)ÛK–ÐÁ½eý-‰"ZŸpÔË׿û´E€¼;Ïkw¨&)å!ªÄ& ´L}1°‹²×ۀ뵴S „M^÷/”’ýòS÷k„ñ<æ{Ö±P*Êe~à#wo}ä/ÝÿŸþ™»{ëc+ÛÝ[î~ö»·~à‡?|ïÞúÁÇ»ðWïÞú¡·>üáZð‡¿÷{ßú ÷ß³~ùðÛ?óò'ÿöúäCºûÈÞ׿þ_ÿä/øÿÖ§>ó™/ü/¼ÿµÿ÷_ø§üÆ_û¹ßúÝŸÿпõ~ëwïç?ø­ÿè7þëïý½oø¸û³¹ÿ‘Ö:{³X^ͬäå•’t«T‚ì¹kîvélZfÃ/`F»Oy¼[sû ´jõ*sc«u•á)Á•ëžR¦]·X™eÈÐÄku¼Ê°–yÊã·ÝS¼o^æî«Õz=á º†©ØuCà)Y_eb·mú4€‰¸ñg˜5°ƒÐ!¬™Q¦Î†ñõ¤šëÈA5;^@úI5Y‚j®%ÅDôšëVÜj.²ò’Ïr•:Ã1¾ˆ]sÕs$*±*No`ˆ—ØB5ו’(Ž¬ª3@aM$Ìn਱3”A5WÅ=5ÇÒ#æCÍ•›´_‹²Sj®•"5W\b+Õ\+Ej.¤, ra©¹€±Ô\†_à‹d‹€çˆ …š¤æ%©æ2¸p mÆ«†f};Õ\ŽA%Yy\9²”XúQñÆ‹\âCO‰s@¼[Xj®¨Åf•(5—a|Q¥æÚ9ªÔ\»Ã)T©¹Ž”AZ˜j.rVƒ*v3=ë‚ņ¦¢{¬°Ž½>]pÔ#ƒï-kÇ0,_õ6>:Z͇À+q1BÂ6’ñʉKÔE&Omº®j^ƒ›Z=QÍuI¹`¾ˆ%àÄ"ºˆePÄê‰j.kMä…©æ"±¨*Y5'I[¢ìøg¿ˆÑó´Ó©£ÄTŽ5ˆ\XHD.þ½É%¤+X–1êE®^¨Õº¨å FAÅÖ$aµ©¹XÔ= ˜TM6€°{SÍeÐÄ$¼Ý*ùÚ„z¥šëئ6!<‡6gìs=QÍEJe#Õ\ÌÙ·‡ñP®øx5U´aGoÏÑ©æZ4.>ý½- ¸窜¤æZ Ò·`^krÆuv³ÍËà(Íöúa åÈRsíYj.¾á^‹ØHRsEX;qoµè[…ˆ²°Ô\â×K¸šq}]j®(iÞ)—®Áeв ¸a´l›_šku¡I¾ûâƒB’nJá¥p¸‘*F¤šë®)-ë¸ ¶>-;;ó=¿¯ùÚ; B€ zí.£J͵s8ÙÁºhS—š ·¦æZd¡ÐQ8L)™Da}J”v÷¿û´E€Q¨æºr”j+|âäUb“J5×J¡š‹½†Ü\¯¥•˜bà<{÷/”R.5×Zf¥æâûGRµ<£æjj®ùGPsµfj®ùë²þ©oû®|ç·}ß7ýÃïü…ßþÀÛæ?øþ¯¾ü?ôÏçóÿîÇïcŸù¹}ú_|ãÝ{õï¿úÒû¿òû¿ÿ¥/~æ—?õ¥oþ‰Oýúw?|óþÒ?{÷G¿ø-Ÿø7á³ßþÿøÏßç>ÿê÷^½ÿÞÿ‘ßù·ðåß|÷ÕOü滿üÙ_ ¿ú§ë¿÷í_üìg?ýÅïø+ŸøÑ_ÿëåóßpÿÇžÕŽÑC”¥™‚RÍÚ-ÊÀ¦4Ùÿç ³VÇ/îRÕËOOy¼KE/ë=eq¨Ê°27¶ZWž’³™}î”$Óè]fLæƒÃj5¼Ö[ݨv·ÝRv̭֭߬Ëäh4ص-¡¥¼ë)ëÕ¨\?8^]*M_X ºTÍIŠ}“$.x™[­« OÉn„¼Sðn&ç^¦‰À»VëŒ)Îr ÉÞö详¬oVæÆVëvróu²Ü’ååXªkÊy5¶> vžkE$|§Z# x#qïú˜dž+ëÚã*>­ yã!€m 8%ÙokÔþ.¤1L¿W[V±]ʱ„úÖy¨àŒÙW£ oiø"ÓŒaáuÒ)Ç.VQŠíE©â6-L0LP±Œ"øxÀhºåTqÍ…ü‘jº…ùs†`a`ùy Ä+¶©/‹¶a=ÍÜzÉDÅXEkq”Äz¥ˆkàj#÷סò#C:ÅGëü·p2>ª`#§² ñ¨§éS2Ñ ËUH®ÐI&áˆÊõ@_/v¨íÌÑÙt¼€ôºÀ%K$íY누‘.º]\¸A0#+ ÞäÑË1¾˜Tdïm ¯ˆÈRŽ])²$Y%l(¨b ³k;<2`=â÷ScéŒê¡K=(¹”(åXjhê­§”c+…RS–ܹp‡ Dˆ)0;F㧠;¨S¸P8(RŽ\EP9&Xuí› ´¬Oðg³Ö–17ÆÇönrçˆ<@­Š*6 n^)Ba‚vNŠîDŽë³lÌ:*”cWXV¤£„»”c;£0ºèy5´* „* MG÷Xa{}Úp‰ÜÙ¤„œÕ…$V! jã ¾+=r¬cÉ`ŽåØ…Õ`~¡{2÷¨NM°0ù,Á?KU–OçX‡ðóZÄ‹è†óŠhœ-©qTNtkù«j áêW¹Ö¹&qmÐf—0ñÂ$p±ÅÄr@½xÏW´)ª;ü ñúJ¡½spþu_Œh{Ú®bm6žþ|¬xN„Á_Ü ¦ªÕªDåØjÔÔöU’†Uª@¶ ë ¼,b‰7lÝjåÈQ‚-¸ÑtPšb„«£-kÄdž:kɨK9–:­H|cèx)µ÷G{[èÑ^(Û¶ÐÑWÌÊœìmpo ý  ‹éåÚ¬žkWðí\}ó÷ÞºžØI¬ çÊyT#±¢jzÁ.R_jõ×L„ÞbpmÏœ‰pPo&㪗dÒÜë-ÙÔ¢5ÈÂÔ09F~¨< ½k'Y;†@¡FÀþfÁ ÍïÚëÑ·µ$<ðåu‘ÉSDxÍ™ÏÀM­ç³¶wxR¨±œXB›X„N,øâéYÄZyá å‰E˪٤-QkDm NŒ‘¢vÎM-jJÊ‘ƒ’Ùj-R#—þvr eeŒz‘ Š‚QÃŒ:ËæS$au¬á-^Ô*©UÓ‡ƒM'¢µ{S9&èbÒÀc¾6!¨‡B?·©MÏa#†ÍûÜ…‡(!Êöµ™Û¾!ûâÝR¹ è°IgÝœƒî0Ôæ&1¸|øô÷´(Lê´åiʱ4¥Båþ¼(–`”Ä•e-IXé±±mŒ£žºž9b×ê [ºœ!6­:‚”c OB(.­cÖQžª“ë×K¸šMµÄ†€€M˨®ÌÙ² ¸aê[•c‰ÆI¤œøf‡T1qCt#U ú2=†k­¤![ÄÖ§Ec§@ãtÏïk¾öŽy}ì.t5Nv©ãx¾dŸ×zeʱ„'k?Ö0Éè—}ÂÅm¾6øݧ-ài˼É1m…§fšTá¡ZXÑþM»z ¹ ˜b V bŠK¥rìHi‡r¬o°4'éÞžSŽõ?² Xë¦ûOþ­Wï¾÷ê½ÿøyþ÷?ÿÃþ/ï|Ó;ßúÙW/ß}õö—?ýåŸ|÷sŸþ»¯Þyç÷Þ~ûsŸûüW^á¯Wï¼÷•÷¿ðÎûï½ÿêÿôϾÿ›ï}åWÿþOüÊW~é7þÚ—>ñ©ßÎÿÎ/½ûö¿øÅWâ[^~âS¿øíßñÝ¿ð±ïÿãßðýÒ„Aý£¿ÔÑÿå™BõÀ×ÀþfÌSªVÑÞ}W˜ìá…˜ù¦©°kå…q9ÍÅ^ÂêUŽAàû† °˜Íf:ûû옻¬ˆ’»ïÔ«T­éPÔ^GÌçÃ, LÑôe˜ã£w õÜkzÀÍ8æîÛRÔcIÕ²ÖM•Ô/ï)É$­…a J±šÏlóäyjÉ›òH=̃¯áEÓ.‡–;G«ö…¼>Å*· îûX]›žº=ŸOIÏüÛvnêj¢¶¤œ“Ìü] $×X,ªÖàEu¹Ê®Ù\X=¦5Ÿƒ±›&ñ£[¹öc®J3«@ókà.±xb:K5Ÿ×Îî°àÐÚÒ¿ƒ|µ˜=cšò­PéÀO¥&s[ÞíÍlªÑ]ŠcŽöp±ZÍkG’…¢9%¥È¦’gp©²Y]£™#ˆTõºÂâP_•!’^yr3"ïràᶮ(ßG{` uÛæ érô+Z]»ï)È›‹ÓçÈÓÜ¥À.§N×Az]Õ½´îöÔX¼Öæš½dï|?Λ¾çô)¥<¡á•Çé|•ãcqÕåãuµÇÇt·yûÕ/çÝw×pã98‰ë>~ÓèÆFÃI9ÝåOÞl$²u¸#¤4|øãf£hläN”¡µ­³²ºfr)ÓÊ›’1Í΃µ±Þ”c ÐQ—-RG{âOÚ4ÙŽ~E«k÷=N-žNŸ3OÜldå4w½ë¢SÔ›öÔîÃæm6¯sG¿l9ú^ÛxBŸê¶œ›†W§óUŽÅU—×ÕÓ«Í>îW¿6o¾Ã×ÙèëlôÈFOùçøêJòµ¾ºV5«Ëƒ¸/“³.y©Õ=E­=\‚X >‚Í÷=‚«æ©Ý\«_Ûš•"¤#O¶îîrÒ41q×e~¢ö˜Àr´9´ð¤_Q¾;·en’¯]ÑËû6Õë:xÕÚ3C~Òæí©|÷kîzßg Og\O›£DÃ+Óù*ÇÇâªËÇëjéÕf÷«_›7vß_ãŸ×yŒUÂm]–iáɆ›\ØKI4à Y¨âä@3·Nz4ƒï|¨f0ƒ0ï&jÞ3ÌcoþŽT?äEÈžT ”¯¸îV©4û>p·ê•2uˇë4¯šÜUÁ æPÁògB!e ¯S}£"}5‡õ–.#W ôOÐÒeØSó­qÊ°1_¥ÂzDzæ+¥¨6ËPÂs²U~¦E¤!Ø¿C›ô:âí("J¤¡ªé™~Éh¬fêóÄŠ–wGJz°4º¼?”c!ö¶¢ø E-´›¤N‘ãBÞÂEƒ2Q@ ÂbµC /Š/ãu¨‡W¯de%œ¨‚cEé€x;omój–Ž,/uÃC¤¶¿Ðyg°¿Åy·Ò4§— î5#‰§H‰C~r¡ìLír‰VV$gðªZ½áÍk*Ò$:Æm©¬ÄÌÞp á`ØeA9¦‹Råb1\gãA9sãý,æ85%Xsôĵ—×Ðn ú«"d‘%$Qö­˜O“¬Õ×™—lŒ‡ñw™µîô Syý` ñry a[ÊA{eè›Õ¼$e„Y´¤çXg}6?òú€aãSó9…çùEs«^Ðb)PW‚¨¬+xÁÀ;,/¬IcÔ)a¥xæˆÕV7Ü£¡“µü“w,óîä =»¨@ÊÐ\ ºSj7ÂWõ,kNòÑ!û>0-ПQÔf¼îEŸÖ°ã+R¯{‹ë¦o´ii9š-“´=jg fÚp'lÖæÒ§—lý*Ýß {ßK÷;l§OéÞixä1:åØXuÙxí±1½Úìã~ôkóF¼Ø(|¾ÎFÿ‡lô”Ž¯.ŠM…¹*fpÈUÍêò aqX¿Žºd­\ ¨)¥ws_}»ï{[‘‘qwcÍ‹biï]Ó œwÜö›r²»ÁÜu¥d«õnOj¶Sí6G{zxõ+)ÐÕ÷Í-}àÍâv··rªó^u¼jí©1 ï…¹ {´~Ñ I<û^c4ôkÆõ±g¥™ïòC°µ"€“Ëí— kŽÃ)Í͇ÿ×cŽÃLþœã•7ã>ÇiR󺼼mŽÏz;Çg¾ãoÚ)6ÇÕÈkŽãêÿfŽKƹæ¸cŸã’ñŽ9ÞB¹™ã-´›9Þôå1Ç[ŽçÇýâ9Ç7Þs|§hŽ# ý9Ç[îOæx“sÅ+‡.]öoºL¿™ãT(ÞÌñ¦½sÏñ¦+Ï=Çoç8_üs¼ñ ~ÏñfŽ•®9ÞtøÑoz°§p ýÉ?Œ3C¼™ãï9~¥düœnæ8Ê¿ãM†Ê>Ç›æû§Óá›9Þ⸙ã°r8çøšî9nZfÞ¤ž¶±f³Y‹¸fãdIñ´¤XßØøQv_K†Ü<itûé ÛùÄ ®ÚøYK’e:qV›sô^În‹LÑÕ]Ämo¢˜ ²vùð±%©évúX’vŠ–$ܘ—öd¢*ïU½ìÒ.¼³SpÖæ«ð1CÔ}ÚSÌyœM[³þÉøÞÃâtö”ŒÖÙášç¾ñ†y À¸6‹ekÂJÛAßÌI[¿Í>žà¶ØMˆÜ[e7ùYöŽ†’Ýdn}´£†åà”ïÎ{YÔ„´Ý¦ªEc•ø¡Iþ$$v?ëjøQ­“®Eéð‰^i’·+sèí¶­Ë–Z|^˜mó£„åèRÑàüÝ]é’Ãaná»Yœ'ôwyÆ(T“–©Ý0¾ÁÂÎgbî‘M~Ýì?¢-ìžžqÀ4ˆ(À}Y‰$ÇDXúQÙ*Ç~®šŠ†ÓWK„›îä?Ñ#¼–u©ØºZ‚-Ô£Š¨ÒíÅÁ‰*©Ù@3ot›ÐhnÃIœù¡3»há3¤Gê47kjƤ‰v ZpÐ ~!®8ô£ ˜p¢ŸÕó Ŷõ~ê3ùCÔ‰ -–—-Î ñ´~ƒÿ7u¢ÿ=ýf*Ý8¤¸&sq^Ø({÷ÇR•¡‹,Ñd¦Èõþ– ”cÐ1ÛthnC¾Ö$h10‘æ6‚3+a³U£$II•‡:´G9Õ%À‘/™]¤Ñ+vâ q[Çë· =‰+À´CŸ`u&¦¹ Y$œ<ºw?z†3UeÑäkåèé )|±uGäͬXŠÛÙäaOšÛ¬änñ>^Oéîá'WþýZÊõUOJvoÿWñ´ö#¥{7Ÿ©ŒÃWÙ}ý˜‚gRú(ÞByÎ~&åúª»Ç‚òzí¯µp_íå$UÁ:Kvz‘ß!,ˆÑ*¯!%Ê[ äDôÕ‘>NÓleŒŠT¼ŽÊ­ßî¶6A…R.£ï&˜3žuã.hÿùè‰ä,†3¢fðŠ++Ö5¢Êdh5‘UNF¼À$E|¡4õg­› t=DÄfäloa1Ý ï£<쿧=ö'dxPDAàµYm3ÜkÙß ¸¶»1„ _õúØRÐoœÛNÉid…sMþw6¯·u¡”qÝÖÑ×½Ö*Y4'‹í¤ŸØ€ÈðSpº.Wór¸45/jä9€P†N1INRõ ŠNÉÎ~ë_#¯ÊÛ03Ê™bN’VY{xs°B탣Üiô)g#þ¼W2…’ôñ©ø¬5.è5ÕŒŠ‰dØh¿‘Uá冘S¨™Ÿƒ8B!¢¢·®^ñè”qç­(öARo†ï©3CÖ;1fú¡CОBN]PÏ®!iVÔXô˜È0k˜ ãë9Ç3„¼àË¿â"îÆp[XoªÀîƒDUѳ.ÃV â@ËW7ë+6Ñqãîñ =wŠjCºK«¹ˆD›fƒÈßé‘ôÊÐYÜd(/5•y›ºªp‰è #nó|™á£0(2ï%2Âtrâ.I\¡QrŽjüò g}¢áÀž:„m;‹j »3e±œáÝ/oH"u]÷ "8}§! Zî6Á£/2bÐN®k(D×jÇ÷zAyÖ0‡èd9`'Á¯¨¦È¡B¢ö9,b%EûÄ{TþN'”湫9‰£¢·U†­Cµ9ðc굜ƒî±6 3…Ö ™Ú5 ˜\jž°\sÏîÉ÷ë_)Ðls¢u=#ºš^†ÎAeH¶VºŒBÂ&w‚˜¸xMÙŽßõXÄŒÎ2®(½¸¢AcPaa|Ê ÅÃæ.ž«ÃFûšÜpHÝË‘ƒ±Ëápr:hTI1' ì÷Ñt<ænµ¦J–;0¥â¯á;G3sçYåòÜvЀ\’‚§W\õxoʨ"ã}Ú¹³Ö#ÿ]×N\SúœôæúlíîÜ@”ðx%È¡:Rº… ¾çj Ç6¬²³¯z£dDìÚ“ü÷iÓ¦ƒDnÇM#mð,Îçþ˜qÑÎiáã¶'NÑéèÊчHÆh©ÝVI‚Ze3ÞÌÓGR¥GFvæT»j <:5ÎÜG¸Á´®’ ö*jpjăˆdK^)¶xìE‘ÞŽ Ø÷ù ü1êš}8÷â¼Áe›nºÆÔÒʹÓ÷tóYX«íˆÄ]êÐæ×v1š¼ 1‰ÏƒËÆ ­ØŸ¡ª³­qÉò©Ø¸ÑâOcÅ¢gòZ£<‰ûkΈÂk#ÿáâ×z0Å’_LyÏ0ü°[8+†‹ô©ÏªøÒiÏÓª;ˆc&ã };rÀ«ƒùÆÊù‚ÅÞcì¹ðùÁr÷äõfíFÔÉxæpJ#^³ žF®©ÊðÔ]¹³ScÄÛhfžd.ÙÚ,„Þ\Ž0ÃÚ—δÇ´Å‘ÍE[”IaÂǸºJÍQá"YÒÊ•²Ýg¼WeŸ(š4 „'T@V<–ºmQ‘b&âN ø£‘Àû€!(ÿN÷T¥Üï†Ur0®‡äöý5¯Ò•£´†FÑöÕî ™ŽÁƽ‹%e£×ý G kjb;nT´Ð{j\ƒÍ+åñH™”-ﮯ® ·ë2X“†Ÿ"MµJÀIY>ª{U4ç¶Ê-àQüø7›Æùi?Mrôú÷RÙ^è-µÙâ±FäyÓ4CŽƒdìÌGÂ6½8Æ#–°9G*‹Å  `J,‘`èèë0ÛVƒGt”Y;÷l¢5â¼ ôl3V0™æÚ d¥‚Èy3rÕÌxìHÑ™W%¯£iCm¶3C]RŠÉâP`P»%j=:ldl!¸¤#ž(^„’jÂø·Æ‘£Gušñ&“–×Kå®è£8Ì(ód»[Q+áÉzlÌÀƒAÓÊsLùX³Û¥ wóèt¥èpÜ)œÛšJëø›Ã®·È©ž£).!îˆP»ù³jëù³™KÁ1ⓃàÐ3e?îƒàèó<Âï>Žno¹€…öAPЂÃÞ‡zO å»=BÏyfõæ ¸ñ>îㆽª÷c5Ù7A(£Ïƒ ƒ5\Á ÷AðJ)sÜ¡)¼=ªqì ˆú΃à…ý ¸StD}çAñ›ƒ žÁ!-€‚û (èAvå8Bs‡ÅW¾‚PŸÁ›~4àAA;â©ÂyÜÁŽ­úÓó 8#h‡ùŠ¹‚cÉz×AEQa´úä 8ÌýÙÎÑíkF,õµƒ ˆ¥ƒà(íæ ýôyÄ=ØíA:‚oÀý hÀ‚‚v„æø<ª7Ašå·½äij;-ùô%¬30B™ú’?]ƒ®ì%_p/ù‚¶ä£÷‡Ê¦zM{É¿R¸Èãi>}ѧñ t_ÓTg`ÚT”Tõ¸¡f!®°Ä÷‘ŒÉ#`èµNüµÔX#=â ½f—™xAÂ~BÀIfÐIæwÆ ƒxÐ úà&»R*?ÎEm 'a’Ï\~ÞWC¤TG¯ýo£—Áf6ÍP¦0×NT £q=Û[Õ¦‡íU{èàê.‚à…á§Và ¼ˆÚ¸¡ ‡-Ê°*žrðؼۄAínsîúÇîþ†ûžÆË»Á3Pø™BçÈ{J §ÆÆàªäêÅà¢]ˆèÀòZ±ŠîÔ~áTÈ]9+Û?'€M¦Âž š$,xv…ð—p7?²`HÆf™"<³\]xÒIº @ë ãuqì‡2{l`¼ §‰Ê vÞ}±˜B &ÚIèH}ï•Ðèr’—Ãíu(ßuˆß‹ ëðãÝT¸G`˜)Š üU9Ì–S¦è¡‡‚ÙÌXþÊÃñER‹q,J'Y çJsY8RÆ[å!Vá*r¥ÐÒ,eY›ð>A[³..‰³6>«rüBÎëÉ[–#qQò(j`í ~êRèègÂ[ᣟˆP%>P?ŒJÛÑÏ#Åy'I…ଓ´ ¸Jï6Ìò7%“ÇwRÖxÚ€Ýæ, ˺¡:·bïI=’H8ÉŽÌYz»~Å­GÓ¥žž¢è‡}h‰À$D@*±Y§×öµ  b½~ÇÕTË8 [l8½ÈÉ‹úOz‚be¿Ü‹¨¿¹t„Ñ(#›lÍ3"#_’OÞJŠ ‡Cä‡ æñ{Aá8¨t.)2eêE×g‘QÞ[iNRA3šÚ‘ÞçrQdÀ—6ó“w‹\ºéª¸ m.Ó]òõâm @å&]Ôêú‚<È Ý•qÓ0ÕGŽ¬åñeé[¸YrFÄ0ÊH0É9¢£ìØŽ -õÝòl¶*¸a¦›'î]’]SscôVN4ÓÅR:+/—É‚x Þ[8.ÈnöxxÖŽÇâL[èèôRBÙ;Ï …k79@«½5[@äX¼ÚJɧöK—¦S1õïÎh8šéùÞšåR8#ÜöÜžíq†A]äÑþ<7ð;4ƒMñQT׆†û>jž}CK…†±W†Â€Á\=¡ײ\Zºíö¸¹å*Ød7»® Á­=˜`±¶6ÞbžÉñn±ZKk³ÞÓ¥¬Íõ¹Á6ñ Q®ûJN¯ÃB·ŠU¡L9£ ]áN­y Ù€«š)fÅ[r_ˆ[£ÀaðñURËÞõªlˆ}àÑ ­'\Æw“9Ý–9Ü!µã÷Ð5Æuƒé+:¡uNÓ¾n(—aLѶîNº NênÚÀï¶19䯞Èä¶*Ç2¾ W½T¹Vi>N×ïÉ7Ò /Ì0Þ’ˆHû0µÞšoZK𵛉½Š¬,Å'K0pæøv±R=Ž¦ úN Ð÷&x "ËPÇSM®•%=8¦jŠšWŽÁ¼Ë‰.Á>EÔcWytص.¡œ%Ú6X}v̱.mO‘{¶9™—á wX5ÝÎë,”k-ŒÙžyìÊt(Ì¥2˜“ÝðpAºÙÕbse`#šŒwÌœ ³´Š/ä—òJ®jÞΙk<ýèJ.(îëªì3Ã|0â¦tAø6´ì–@÷}èV½ÔVͧxl?]Þ`rŒrï´ðxµ‚•~$åºyú·I {_©Cºø¦ð¶›ËdT¼ý]ç'̇§Ž'óµ|Ã|-?e>²?˜¯•ƒù6ó^Ì'ḣrNæÃW'ó96vë7Ì×o˜¯Ý2_«ó 8ómærækO˜¯?e¾þ„ùú-óõט¯?a¾þ„ùÆkÌ7n™oÜ2ßxÊ|ã†ùÆ-óõ'Ì×o™¯Ý2ŸÑ™Op3_«·Ì‡¯NæMæÛ\vË|¸¥äá[O‹_Ê7ªíR ßLhò†©ó° Ä™ØïrÂÏq4ÉÃÏ+]ѳ½†Mð“Ié1(Àr&Dº©B¢¢Û· ñz+Ë¡h³ñÉâÒ³—QWMtìÚ²À5f›æ]/ç¯1Aó®Ÿys.Qü@¡›ðc ¶Eí¦ÛOæ7çz-×ïz'ÂýœoU‚Íìâ&xuê$9TµÖev›®‹}³rÐ;ÑQi3ÐÏ8F]Ë Ü–R$J‡»òîLCŸ*ôT*ÝJÓå[êvÈiòG’ð´«—ém6˜ôd9Ø~o±:ãÂ&¡–‚GG¦Š@1aj Qèöhò‚­F;A Р­ÉSÄÌÄ&|xi¸·eÅá`+‹›œðòS¬M›l(YÇ1rÞÜ„æ^qS1êwZÆà Ru õªÏÚ”ÉϬ[Å^\õj¡ÊAþø_ƒÝh} 좞êaÑcèºÏÈ,ëÂ=6e)Cx jRž=ìb ·lµÞÈä9È Õw…ç!“ç  —LžáúÉA~Ëä\&Ü2¹AÉä,çÉWÅå”É76òÎú)’UoE.™<‡}îìL&r™ÜdòdVæ"÷ÂõF&ÏA.üŽ ãÉs”߉K&ϼœ¼dòŒ ÖC&ϸD¹‘Ésäµù•÷}{cÙÐeò+šª¨x¶Ç°¶C&gó/™<ãÊñÉ&“ôý+ãvèÉ3®™| f=dò‹Ëndò§iN´”¾DJJ®2.?rqEЂÕDp-Õ9š¦ÚÏÁ¿Pj*#g tWöwÖÅ"®Ÿb;hj綔·RLogT=ý9ÚýMÕhFDþ;Ž°÷¼4H„â-ÛÁ?5ñ„ê[¸HŠB!¢<:¤övýÝUÞ1¨à‘"¯±Ÿ¶èk‡jó{ŠÑŦ“Gâj¬(sÝÈÃ5f€¢bÙ3ÿÔ#àE ¢¡tPoM‘™ï®öÏ­Šk`h)“ÙÖ Êü Ãjæ\¦¸‰ˆÇv)I0$؃âŒ{`^[èD˜áºÙ^[8šÓÈSlÅŠxuîr¦Ë9Jï¸׃6×Ø‘‘tãÐÑžPê:gÁi×ìú¾ëØ{•o7fþ»|Ñð-09É'— Ÿ4ŠAwÊ»Xƒ&FX‡ç{×¥s¤;Óýo†›ýfçã`#×Ò5ùlݸæ¦N¦û÷ܶ®¾ÆO]ì ÉÌÔ=ÅdÒTh£—;%‡D’Ó/+ºŒ£&Š*ƒÁ+¿¸ƒ# X{Êê¶ÇÒ§a+Ó±×úân§tJ±SÀ0«~è4sµ{È•ÃkuL§Ö]D;°•Úî)»·VæÆV«Èòu’Üä“wåú³6ð°N§Q8 …Ê*1ì‘|ƒXo“&V¤ ^2Å@¡qò»Âc™þÎI´ˆð‹2„ º_ëH*í%píð¸*À÷À•Âg©xWÑøÁ˜ Žœ´žú|ÄûIµäfý­F¬b‰_ ˜f• }‡Ó'·‚¼‚þÐæµ¹G¼hÈu§<^)0\ü£#;45Èbí!C‚ó±%UZ‹ø·µïÆø%H;ïù$Å–õM§,ÿoBh›‚1ð.aÍ×6hqÏŽ‡=|²©Éí+&âÊ!'˜ Öö´ ¼TºÝÛ¼¡7mz(œð‚dM)„‘ì”0[,™ÙoJ5ßÑ2éåi¨/0`{Þµ*óBO×%8±˜™Å9ð;èÑ¿Ýdï²JÄkƒÜ_‡Ê”ÅÁxž,Â1’{ªX\©lÂîE!vð»ÊùTÎÕñµN÷GŽª¶LêJ"Ÿ˜L±Cât y½³˜&R˜ÅÂ!Ïgé@?|´OGŽÄƒdŽ¾/è¹rÔ©Ë8/Áñ(ºö;R¨ºïÔ¢8¨¡Ub·d u–††ÎX!ïï8¢ìÙ„t²f5 $± ‰Ð8NŽñE§Aú•cÈX‡—iãÀj0¾ðéIÕ©‰NÀ•»ITÔ¾[¡Æ·R¤4‡$^dYfGx“î s (˜èH;"’gâÚÀí+B=/Œì-Ùbb9 £Ð…wŠê?€¹`Ww*í ‘ƒóÏÄâQÀ"D»©"ɦçHzPœª=òd÷H’«Z­Jïn#ßgè_ÃÚev‰Va]‰MÑÜ [·Z9rpØ3uä”’LŸ1Y#Nk< C5ÕLNZÛBki‰ºÈä)¢ |šÍgà¦VÆ=Û;-å‹XN,¡M,ƒ"‚dÁÄ‚÷v(ŦIòV ½/Q ¾ë¸11èmžÔ‚µTŽ5ˆ\XHD.ýíä‚=:Pº‘Gäʸ4<©å F\|½†’B‘á¹µJêf£Ò‡ƒM'"X%èÃ>.1 žÕJ¾6!øÓ ýܦœ;‡6gìs9EðÌ씕G æ€`M» H2z9ª –õØ ñ°d²‘•Ë‡Mÿ]ƒÅ7£î&ÁcAlŠbÅà™þy"ü‹5Û¼± ßqŒ³üÛž9Ö²ÏÕ;Ón!â-í˜\«ÈÀ`— í#ßG˜@ÏXR°âjf‘¹²Ø°YŒ³¤eԢɠ dAqÞ$ÛÚäíO%F)ጸÈèqSŠîÅn¤Š"¯B×pM:´TlWBKÁÚ=¿¯ùÚ;ùŒ2èÞ]ÊêjŸG'» :¶}ÎC7Zˆ8F£Î½nÛ8,ÓúÑ,_üîÓðZfž9pl’R¢J$ÝØV~1´‹â-U×ÒJÌÙ.÷£ö…R²H~ê~pXÿÿž‰`=‰<»fÔË»øÈÝ[ùK÷ç§æÇîÞúØÊv÷ÖŸ[g¨»·~à‡?|ïÞúÁÇ»ðWïÞú¡·>üáZð‡¿÷{ßú ÷ß³~ùðÛ?óò'ÿöúäCºûÈÞ׿þ_ÿä/øÿÖ§>ó™/ü/¼ÿµÿ÷_ø§üÆ_û¹ßúÝŸÿпõ~ëwïç?ø­ÿè7þëïý½oø¸û³¹ÿ‘§ÅK’ª Ñj‚Ð=%*i‰Ij¡Tp4(h¶ãÛ°§È­èù ý×Ö«Ì­VèU•wÈÓ×&ôp¨2cÔ‚y­ŽñZ-ó¼ZO7ßx߼̭֭Ò*.z[ìò—W d£IM£t x-Iíd‘–Ä0}ÞQoæ)èR‘àáß$i+½Ì­V^‡5‘¥»3fO’V™UdPL^¯Õ±»Ë¸Rà@Am÷ï›—¹±ÕúBÞ ¾N’“$Ϩ´2Rg¼O7'¥|[Cøx@]mfx‚€ºÙÀú£\ (\/\ Û§š ^¸W]&a! »kNj­+%òök!¤Æ§PwéØÐ0¦ø†vÛ êÂ}°Àöö&¸„FÊô(Êz†}Š“ŠêæÓµJKj²{«"-»§<^)0¡ &ku¦èÍTQ3ŸšœÖ*odÌî†Z°¹LRpñu>Þí•(@Ví8êØo®¨h¡KF“†+Jk†Ü].Ä`†qZÒpá)?.ßXÕ¹XwpÎ*JqÃL¼èÂiþ5à$1H¯åÊoÃPÜÉz†+âÖ×`t~dÂO2áé‡_%Æ”a1b*]ø{EPÔQì¼RÄ5ôµÙ_‡Êÿ(Ÿ•Ø£ÁG^-ƒñQu;•M(‡G“™I‘tmgõö×1¾®Òp]9¤áBÇa Ï›uŠ%’ö«& Wt1–ñ~"X9ÈX.Ãø¢Kõs 鯠‡âM­ã%±$ùû´”ªÞöê @w _àø…<‚Æ#C‘† ¶~Kc ôêÒp¹ëÄî*»4\p¯3䣲KÃ…Þwd€i©ˆPŽá+±'[<úŽ`$ÝANÒpE.A0`§ñ5\1Úø, —a|®=…vÍSú+X@†vapƒñ¡§tÝÈãb.8-©¼H–†Ë0êOø+G”þÊKØxTó?¥ ÝöGi¸‚ÎÕ 7 „ç44Ýc…uìõé‚C.Ž=¬Y I¬B2Ié_di¸vŽ"ýÕ65l Æž¢ˆëê4\¼±•õÔR¡¥m; Ìz‹fÉ”† †ÔäH ](œèrµK{Á”õüdJÃÌ[!^Æ ¿›T-&–ƒ/]¼xÒ;gɶ¥ ñ:í ¡áBŽeÔ1âQ@¶§í*2æÊÑ¥á‚ÇOÚ€KÃe í׀ܥᢡ·/q- èÒÖ|橦­[­98±àF%šKlA„e•kX1˜Î\Ö˜¿\®åzâ×6x¿è{_p´·†0¬×¶€8qœ•´AóÜ}[²mÅôrm Vϵ+x‚vžÛ“¿÷vГ4\A#¿p¿ªÈYÓCZû²_3.R×ö(ŸŸ2X;&#^x•=÷ð¶-pÔS¼ðjucä¯Ôpí Õö–µc–¯zÁ8š_“1BÂ6’ñ¨KÔ&ÓN1ÚØ-ÍSxQkPÃÄOpez‹`‹è"– kHÃbAˆéC®àZ’U³4\N­iƒcNÛ9ZC¾^vŽƒÈ……T@äÒßN.!ÝòŒQ/rá!Ú¨á ¢¢IåׄU(Œ‹CÕÐf„ ö§¨JèbÒùÚ„Ì%æ±M9!<‡6gìs²(·KÅ)Û¥áBȾ…XŽª4\GÅNÝž#KÃ…«0,6ýw îo’.¸C£†+3,cÕþLÏsQ.,IXMM䘎!¥áòCÆ*±I³] .<Ìn×M\  dÙuQH)žžT%$­Œë |K’ GWõ\Ft² dAq\ 'ÛÚd~ ¿¸Ã\GÁöqŠ¤×pMiƒ.ZŽ. ×ÎQ¥À 2ØÞ°™ZüJÉ|½Šïk¾öÓ» tgýJ¹ÈžÌug–† o–²{-%ê=IêÓ´»7øݧ-ð¥Ø‘cJ®¤‘‡¨"±¤IÕaØÅ] í~O\¯¥•˜³¬º¡”ri¸Ö2+ פ«DPµ<£áj®ùGÐpµf®ùë²þ©oû®|ç·}ß7ýÃïü…ßþÀÛæ?øþ¯¾ü?ôÏçóÿîÇïcŸù¹}ú_|ãÝ{õï¿úÒû¿òû¿ÿ¥/~æ—?õ¥oþ‰Oýúw?|óþÒ?{÷G¿ø-Ÿø7á³ßþÿøÏßç>ÿê÷^½ÿÞÿ‘ßù·ðåß|÷ÕOü滿üÙ_ ¿ú§ë¿÷í_üìg?ýÅïø+ŸøÑ_ÿëåóßpÿÇžUŒ1NÓ¤Bž"êË+¥TÙµ%YªE¸Ø ùÖ4Ëár‡P¯zQ–’§° +sc«•žj”’¢©*v a”áeYòíZ ó Zf)4A·2ÌúÏûfenlµnÅMÁ¡')º¹y¥À¿? š²uZ>i³ùùt ²”tæYr>ó$ĪW™[­ ‹¥¤îÆ…že5·Ë„œOC7«Õ0Èb-³{IpäÙ}³27N~N[¯ûŸý:]žÐåí]ÈdªÖix –OÒÕ³«Ê)Ž ñž0ð¢„ð»ÐûCÚHUÚ1Áœ†´c£„ \¯¬E7Nͽ–¬(^/®z3/‹é÷O¡ÉU™~ðsœ?*â]¢.,Þj=ö*íXBø ÖÓíS#)#É¥ïŸ1\ò QqÖª;åñJ)1I¶¿:S¨G‰T/©РO ôj­ðFB fþƒ3Ã@& ر0]1Éòà… Åì¿Ñ°;2\ÄTÅ“§k,9.j26ÂÅôP¸ \0‚ï@Ö€ñ¶s1}\lVQÊ£;†Y@€Êä“hð0AøxA¸>ÓôÁ›¡‚þNs85ù³\„ ¬üM»Ö¸Å.W“{ﾶÜ­ƒLô|ÀµA›<æÄ “ÀÅå€O¨²BãùA âuºÕ¡‰ \ÏG¹ðñ( DÛÓvUÆN;GmZ%è$&!rIŠ{”ßTµ*Q;–TžÛW"×&Ü°Ö¤Va]ATy,ñ†­[²×±!Ø‚d‹mÑ.²Fœ V©ä±–¬º´cô­RöÆÐéPÒ÷C׶`fé{[è$Ö”‡½-ú¶ dÛŠéåÚ¼ž½+x‚vÁuçü{oÃÞP¬G«X(SOkõ¥¶sÍD(.×v9¬:“q„Ëž{0\ÓÔ2.R19F~ˆ¯ Ú9šìž´Áëo¶ñÑŒ«Ì ÉÑ̈ay[O2í£M·=ì ¼¨¯`¶wÒ»K=ˆ%#0'ÑE,B'Vë²NfÈÙøÞ—ÄjÛ] å/£V·Á‰1¢v΋ZrÖzåPyr)`äâß›\D±™-ï4ò\V×7¢†'ˆ:tæÿ’°Š°^Å‹‚±}P5´îJá “ÐZѨ3hbÂ3”|mBCŠãc›rBì>bsšiߟ“FÙJ/à݈̑ö( ÓiøYE²£·ç€‘67‰!³Ý`|ÝNíXÀÍ–•bÚ1xSƒ0äHš0ŒZ’° Nù¸u Ê@Kuæè]«7ìè`oH(1sÒ‰‡!—r—‰zëÀ‹. €W3jipA6¬rP¢ P hÇв ¹au ÛæçÎ B*~2x=ÄäCª˜rvÐ1¤çAm„œÙê8`u7{;%ÉH¿rcÞ{,"(ƒîÝeb]½R.²›>ŽÑÚH¢èÚ±4)R6:œž2øåÄcŸà&2_¼÷éðÀeÞä°ÝIªiR%RÒŽ%¼á.Š›K $œ÷½Zs¶·!íØ‘²c-üÔýúÔí¿ð|TmÏiÇúÙþ«uÓŽý§?ÿÖ«wß{õÞü<ÿûŸÿá?ÿ—w¾éoýì«—ï¾zûËŸþòO¾û¹OÿÝWï¼óÎ{o¿ý¹Ï}þ+¯ð׫wÞûÊû_xçý÷Þõ¿úgßÿÍ÷¾ò«ÿ'~å+¿ôíKŸøÔoçç—Þ}û‹_üâ«?ñ-/?ñ©_üöïøî_øØ÷ÿñoø~©ÂÆýÏR“¿"äëBZVï”!ýÐWÅþzÌSð¬˜9†TI–ÜÕiñÑì‹Â€¸œæb/ï(f¡”¨7œ0R5›iY3±UykíF=PÎÀ=#nÃô2q¯%M¶HÉH•›Ù˜¦ì`eéóQ°<Ñ”)Ek~³;7:äïv8Ÿ7š—ìR!©d3§C8›jE™þ°µ_¯Q³¯!æÓ¼ð¢)ÌôÏk•ë!¾¿KM*¦bæu…¯uuwJÓÏÿº.LˆJcšÅdª©èúJ,44ó÷{dûYq /ª›n)©!܈4êZÔ⪩?*×@¼|ŠÆ\9Ê*/á¬ôNÁ!4W\æa·²ölõö.}­P«ÕÌž1M©KéþW·£Ö*ž:ÍCYnö€ÑJMÓ´c=ïÅâ‹%Ùú“gØ·¢úäÓÃd««×¾5qL‚Å¡¾2}Û‘‡aŠoÊ1}ÞQWª¢àÕDY¸ms4[º«_ÉêÚ}×}ÒEŸ#OÍ®`örh›|SWiåI{òô§ÓÞæ½dïW.>#¼ïÆ9}r*Ohxåq:_åøX\uùx]íñ1ÝmÞã~õËyc÷ÝÕÜöCâ¦ÍFÙبm6J*n?¦Ç@2MÚldÝÓ³[>Œº-üË¢ø¤4X]#ì·ôÕØh¿·/Ãfæ΃˜çõ¦[€Žºl‘:Ú“JxÒæ âG¿¢Õµûž‚êpúyêt6òrjvr{] î{ÓzÅ¿i3ŒÄçM¿l9úN£íúäQžÐðÊãt¾Êñ±¸êòñºÚãcºÛ¼Çýê—óÆ[ø:}þOØè)ÿ_]ã}8¿ºV5««8‡õëªË"F®Õ±»3Œ&A¬ ÁîûÀA¸Abžj¶×ŶvÅ®#<¹Ùº»ËÁ#¢~SWŠ¾Z{{\`¹Ú àÛ~áã¼é»sËE]ºÙ½œ¾¯T½®‹W½=#|Ûæ¾÷@ï×Ø-ô¾#Ôð“WÓæ(ÑðÊãt¾Êñ±¸êòñºÚãczµÙÇýê—óÆîûëüó:Q¢bl8êJ¨Fn¸}€ÌØ,%$‹…“kW¼ ™`%W™V…¦ãD Â~?I(í{žåÉß“*LÀžT Jƒp®R=^‹ãn§Ô+eª^\É ¡xÕ” åé½!Xþ¬ÐrÊku y ø%ØW}xäˆqôzo‘‚ü0ÃË=¾-Я Ôéºæ+¥¨5Ëž“Ý'sNG \Z‚v¿J¯#Þ®á¦å¦XZŠºEûƒÙ »wí+!P ƒ]04ÒTø¨¶£E†’+ã-L4C+ÙåmÞ’®ÕèBV±­Úê 5¼Iö^ƒp8KVVbÐ&ªáXQº`Sh1¶ÍSò. …¢Ï+â¡Îz¬LžwxÖ‹ó.c‡&¸6 bd¡W<ÅD zcÙ™f,õƒÍÓ \W«7UAŽšE=~¡°R¼Ý9†L5Ɔ‡j×cQªÜX¬+ Â0÷ 3{ÆFTšf.*CÂ=ZÀ* -î/”D…jçb (Wc O,ò…QINv—g9`žÄ ÝA¨ò°(ˆõ@3Âî^x.áÞ^ñ`Š¹ùÆBößs”¬ 1“Wl šÏ©ŒY¦â=á-–u%ˆÊº†¼×ÀvÜ›jÒè‚Ò°R5Ðrž?-fO°{ÈõÂz“RƒÏaÝÇSËn %ÂÎ[åwè˜ÓÑÎ Mmg±Ž‹¥¿Rjfkk»YnjišV{A‚ý YÏs$ õSm}I8Þô¯ÿ{_ŽlIÏ[é×*î *8Ëèè%TH!E¼räôö›ç€dæýätr~ë=ð239Ä@ 5w+ëCtâ•(&Z„âµd¡V±™hðµ(vr*â†ïäÌŠ– G•ª {R3VQåF£•4þÝfðáø;G‚àSo¸ÙpZÌgGŸ÷2y%Ç}Q£j~=\d{¨ ¸…ˆkV]csEˆ-9m’÷ù_kºk8…þ¦ñŸ4>ê¦qä~Òøiñ’`OõIãß-Fã£ÛƒÆÁož4§›»C)ßð¦ñÝ"Ï»iÎLO·Êh§G oªëø q4nõÓ6Cѹið“Æ‘Žø¦q€o1½hؾi‚ÛƒÆgÓøÌŸñIãÞ4¾[¦º=h|öc¯.·TæNãàöO‡tqÓ8Cæ.­é¦ña|<ì¥ÆX•ØÚî0™AþüT%‹Í­šS80½et½o`z)²nˆ©~ ÚÃ줳éþÚôôF:²±$ ®O-ƒ?"ÆRÛGRS¡ÄëH:-zX—ØlÉŽ7ÊͪY„jàìãpÙƒÙ-M‚w¡g$ãö:Ú¤Py;{tS‘æ—lTùãê°ÕÑ“à°pUÕ&Λ1^ƒmæu@ûrÑÉt@—Œ ª&ƒ!ü€˜ÐmuØ€ÝÀÿÑ‹Ò}ˆ<’æªâ'K¦ƒÒYÊ3‚TMNh¤ßg±G›gÍ~Ðäz¦±<Æz }IJ-4ÝiI¶…ZÆZf ÙˆÙý´Þ˜ WÂGj +Ìv£.AÓfù GTX™%ÞŒµý½îf¯A £#ñ-¹áu#`º¼uã…:oÖ¦5nÙ‡ªÏã»ppL×ÁŒŠqÂf—aÕ¶hR½U8ËÒÞ›jË-¸þ6–0é‘gntiú'²ì; Eùµî>Ugêä¹HÀw×XÛoóó/LQ® ÆÁÄnÄ56¼e„ÓB"Ä tNÒÿkjb¢¢® aNƒ ¤3›žÇÅ`Ö,¾»ü>¶­ž|GÅ{à²Çw$r–nBäf•]ò3ö“.oEFÀ¾#de/h5ÛŽ÷`‘É⸗5IsX IY'ƒ{•ø IÅò`±,žV¢YL+HZ¡ç[žÂm:Ð p’Àáãëò£¥—iÕuÓ«Ö£ÉDC'A3º`êQ'‡B˜,pVŠ# ͤÙÌdu*Ñ`6<3äff§‡©ŠåFÿé.ÉÕìµ )ókµÑØu #;+v8MײvžIÐ÷ì;ièuh.ÁzN°J{w³ÓAv3<gш¸£Ú2íÏHµýÝ]%màÇ@â²ÑØ”@_ã UFݤcUË"ŽjWGÞ03_.î¶-ÃJÀ­Íig¦pHŒväZÝO<{¸Å5$ùŽ…ºWÑþW9@ý¯c°|M”(È€TþÈÿòñ««X:a`´Q™Ù#ÊÆ  Ym˜uQê3€?Êžü'(v¬Oå¿"*ÆæïŠU¶½4H¨9˜“i.²‹åT¬Ì"" ;)٘Π­…S“)ÿÇ/GMÓ@4ÁõP8tBKšüaºg[€dR\7T‡7]•ÝØ›ý”£´jRZ W«ÄŽD†Óø­Ëd€Lœöw%Í@ÉNÝ\v\I—‘É´ Tü­š•:Ž`¡Cåó«@9†¾¨&ü1`xÍ­V ŽÊxÊiJ 4GVv®dyŸ³† E¬&¹8Ò‘Ù=ócbj  “ÄnítLV9ºmÌ•É_@:Þ½³#qbˆ*KiÝ8º¹Ò±éd´š…×gúX ;l_Q’ Us˜rK™¿×‚…¦ÈÂá.; ¹UÙÒ<ï~3LÝëO¯äW{qK–<ë8âŠé5íª:vûÖô«êyÜœŠÐ¢ÄQWŸ2­e¿§ÈãêúVÖ5ö5D<ƬÌÁ÷¼èàXï¹ÇØ-õT³ËÐ݇uƒïin·¿eu®ñ´`W{{Ì´?æUýªzÏ4÷úDXËòc O_çóß‹ý­½_{<{O÷˜÷¾ïymÜØs7w›„¤¸\Ü´ÑÈTGs4²ÐÔ8“/7¶”H“}K¦o¿û;E¤àÖîäõLY-\]K¬%l42/²ÐwÊ{õ¾úàF¤>ÞSby}+™_ÜO¶ugÌÑó™íy¥jhÔ6E¡ÑØÛæ}ºû;í÷ô¼ÑÈóá%G£´‹Tl4²1·¾ÑHóŠÍƒ…}î±Õô\Ÿ¹.ßkxõ±u¾Þã{q¾eûuÇ÷tyïûž×Æ=w¯nò/4úý Ñ®§ÎŠ!€‰ç9Õì[Å×yÚ¼ÎNy+Gˬ…YX6,zóp>°w°«ÐClW¬¹»V¬J¡yõÁ`¼§˜ŸðùnËãc<9§ÚcŽ~xæµ4õ™»§^<Õû“Ûï÷Ìè8æߺpÕƃœ1ÏÍm^ÌDs7Ç—›âêØT©5<}l¯÷ø^œoù~ñøžî1ï}?órܸ$7þ|ãØv·‰¸=EÂzTÎîJXœ­E/—…×1k (y/˜êlì2ö‘ƒàÏŸ_ÈÌÎ]žÿki+u5¾o+ª×!R3ØÞà<)ðiÉú.«hE”†'Ä Ã8‚Ù'Ø‚8'´Ð݆ßäÜ)øc¹ñÔH>ÛÎ뫈$ÝŒôîTþâsA,ƒÎ5Å”Úÿ´ØG4,ƒ¹a›î6 2mû÷L/ˆ/H]¥e~ºZ€¬>¤°Ý ûÊÕmƒ v7+ö²QåY¥Ù™Z¯fžd ¡Ð݆Ç ºR´) Ëô¯ñ­> ’x«zõ7( ¬4Øñ]‰ÙÉy£Ë¥Ž`ŽWKW0WmÚÿ šl´K%:@wžRhR¬N9×0è—Øé-ÊÛ]U僚MDâ¾K¶¶ˆKX͆ecUUZ‡QÞ*ÓBvõàã,Iï€]9¨È+¼JŠá˜pRyT:è/¥§jXÇ¡º l)B[jVlHZUŦøM°ê‰î6ã#ÊØîQOÓ‚Ï„)-W ÎQÝmÖ’Òø‹œ>æ«m«­.÷Cl6>š [ÄU:eÈÕ °ŽM%h•s²¾1ï_×Þô%íAО¶]ŠwRítƒT` †»Ûð¤W /# UÕqˆO¨C½`‰çw‹”ôõxÕÌ’h²F£I7 ­E-ÓV€9ºÛpÆ\½à#ž{}£Ñá´°c|Àß òþ‹pÜ@òrp#Â1h#ÊÆ ÙˆW¶ö¾læ¯åñ4øv±p©è*>“ c1ÔÚ‹p_mFèÍnCOKº÷$Zĉ0ù°·2fú‚Í\vµ S•²#-µü|àFçæ_ÔÎw•Äúщ@Lj¸cí:’¿(ŽÇAV3p¨òŒa!Éò ¶¬É™C“ã¹(‡¹ Z¦0®gmw7òa‰Ø=æ:ÂFF Aô gïœôa½" ÌäÓ—³j4{k¬ãE±2÷^4ÝhÀÜ`sÊM˜…1n¸˜™ý´ð²“c÷q‹$ÉjHÍê ì#Ë°{T£ƒ©-eÛæcSîZGWÁ‹QL´ ś̻ë)Í°j>«4at# N%0iì“XxŒ"¶dû3i<ùaT†73ÛÊÑÌéðáø;G‚àS ÎaÂnÉøÙ?ï;eòJ*Žûcj†¼{瀸$ðÚ(a…ƒÄ5éŘ´"˜7}'yŸÿµ¦Nã¸7}Ò8n/nonªÂªÉÿð¢ñÝ"7ïÅMãp¸¸iüÀNã§E4Ž»Á›ÆuKwѸœ.‡áò¢qV\¾h·,‡ÆQ79Ê|¢qf!¾h¼ò9Øqè´ˆÆí¢sÓ¸\.·KËMã6g†œóÂÿ¢ñÖÚƒÆ[oŸñ¦qÜ/Þ4¾áMã»ÅF+94nÃEã£?h¾77] =i\—P7˃ûиÉ›ÆgyÓøÌOGVí‹Æ-¹Ò¡ñÖû¡q¨°7·Ö_4Þ„Q§C|иÇÆOKÆÏéAãxÿ“Æ›¼°œÆ©S7wó‹Æ-œàÐøÈO®©Ó¸'idª¥ÆE=‰.šÏZÄ50'OêîÅæ†g{){®†%Å7ï$Û¡ºÙôËoõc È2\ý’5æhW‡‰”tÈ]ÝEÜö&Š¹Yv†Ôö‘„ü¦¢ýHÚ-:’pc^.0'}ðñ,µy<©!mxf·@צIypßLÈΆœèð¹tÓžl~rBüquX@Ÿæ(à d4Œ;:ïÆx ¶ ˜×I€»}!·:ÍŽ´!R.íÑg2U.0¡huÔ€ÝXL¥(2À¥yC$Q”O:(ÏOÌr§fm¿óüPñ<ö4šý #ˆå1VGfHàÙ$mâ2”AHFL&fbâ"N˜í˜kUOd  —ŽºêÌŃ³wE¨Qç\ì¶ýÈ@¢AX¨ŽÄ7]§á¯˜[SŒê¼(ϾªŸcöÌc»¬ûyÌv÷JÎM‹®M¹ÛpàBþdf–Ju²k˜² á<µO„bú§—Ý}Z2ηHÀwt×XÃoí¯7 ú<ßÐMQ®Êî7ˆÝÓ8vá´ˆ»!W‰2>uÓÄŒŠz؇9c“Îlz:C‚Y³øn¬Y;˜ 9i)eÖè©šq’›UÊ€ûIŒŠÊ¡ˆØw„è]÷‚&³íxÕq/k’"8ÆýpËZ‹öŠ8i%ÿ†‡„ÈðÀ•r·áèdkQ¡A&}nçd@w¿2}Üb]~´Ð8SîÃVÈp÷È2Ñð–À.1\î6 œ…9ÈDOë§! M ÁÌdE"+rÝè?M~=èßí`÷Hý¤ ÕòUt%”ŽCc«’ûE¤k*Ú«d5’(Ûá¨S$ßöÿ^é`Ÿ.BÓÝFשlÝsîPòEÛ$a²š("I8Ôö_ôlêüîç´ Q3ТCà`{ŸUd¯V©ƒ–¢e“NÀpÛÖt±3q3¦v×f:ÍÒ³-a¬Tk'¥xöp‹«•êºÛ×*òº¹øÿây,_e]#l€_µí_X›Nµ!+­ÜÍØßXƒ’¸Ê Ê­Æ7Ç0s•R£L…4̇$ŒèL„ôÖDÅì ž±C …v’P³Ø®€b锚ŒÌZÜ”BÿÝ ­¸›Bj¤MÓQÓ´0»nzè°g˜uV\qèuéÀõ³¡:äÞ.»±6û)=†Ëe C3Žži“6 §EHI§kôÿ»+iN#álƒN2^j0æ´ßª’À‡\°9ïôy­åL̘Ýmˆ×RA$ôL“™BÒ€à¨->\­c2öJeg(³Y»‘Ö<2»–Fg¬Ði/„mÉNêà˜›LK0M阉énC 7ŽnîÇìpÄ ¡[xM¼{,…¶ž¼GKœÒ<ùðôÍ~•-Ã?´Ð£›-Íÿ¿ZÎSµ¼ÞìÙ,þGñþúÝ2ì24W¥)ò<ÍxsžÿMKk^§+ Á?´œ§†’¾^-ß_ÿá¾ÚË)°v1ËtÖÄdG¸C?-9ªæzdºüùóËÀ ²úÔ¤S'+÷ ºóF…¼ÌÒ£»GbºF{\²c¨/ÁFª[@fÁTˆZ¼·‡Jb2M_¬‚”Ü2ª©_SxM’U0:8›âMùænȨ·Îü‹“ù"s‚§4@M ~T¾ÊÓˆP–¿d8€<¡M]é·Æì¸ È*ÍÊÜ€ë½îM»;G¹ù² ÞÌvL­Z7Œm˜QÞØÖ#‶7 *jbÓ±wz!­¨´ÍpFÅ.˜¾~ùŠÝ°á£á·Æ-agP^Þ…¨^¬Þ#¨œ)qG‚È^Ó×¢{>D”™V ÇŽqc/¼¼,^«{­^á…vé` ‘ â b‡ÊÂùï,Í=‰7 ÃKhý^0±9ƒUÔS§å‡í\h”úóëj ¡¡X$s5¿AVDb¥u]¡”ÁЇˆ=Dè][$©ˆpÿ]íIΣej=,fh*wÀž/Š‰£ò–/)øV8+ŒÏ 9 (óQ³Ò)O2—Ÿ»Å@ùOãEÚGs*,©à5ƒYRaf§GêµiÀ^Ÿ‹à™'î]5jŸg†Ÿï5Ïl.¶>Ïl.¼{ž»åà²)—ƒ:¹µ*!…ùLfaÊ"—|ïAR1œ0XøŒ}›Î©Ðô­ÉèP8ùf‰A‘msÈwâžÎþáökíÀbÒÀ¡ÃŽ)èˆ2;Gó]ÌÈT7hKà9b8QD·a°íô  §W±)Xûïqèaõ7–.)@Ý—™o Öä1Ïu×·’†¡T¥Ñ"Òõ;kšVö2YµLtÞçá‘‘rq2WTò%%¥äìáë¿sü2HàG›h (Ä£ç€*Ú†²‰æöÌ¥ó|¸n0`pº,¶ä¼­’ƒ¡ñ£B)\;Hfûì¯P5SÍÑÝ"‰A5ª7ˆÚ“øe#EN¬KÈÒÐ,ÇR€/6¸ ZÆ®ëN”Ä­ŒNdf(HÑŒY22Z’^,ox~ÎvXõaN&ø$”Uÿ—aU-Þ=IUUé¾ËNI±^¹¶ ?’â9•Y2ï#›Å@#Yžý‡ôª>ÝòtGc ¸º%áè{ Ʊ}«8pHJ Ë{UÏø §!½˜Ã&h%F9ûÝÒ¦øÓäxØß[´.ÕÒÊ›u˜0éI÷‹?aQ:“UN«V±ìÿ‹I´Š¬.Š£‡÷YWÁg²¦$#6üç…S*V5@ s7Y„éÓHMcÊk–ŠÆ7²$ZèHfèƒLŠdkh[Ö>`ò5²–>­4±’MçôڜՓ:Ùïtohâ¬SS3AÛLIækš{5È°[1Îçý }ß¿gôÕhlj+™­XpÁÙ@º@eñ¤¬ód²^lÓק ëpbhF`ÁvŽ´F|k¶ã¦M:ÚB*Þi¢ ņu`ƪµŒ~®–Èd™é~Ó²ýÏ2ÜXÑ@­%Á/M­‡&¥C{÷ÿÙ“ïã/[XL€´uªË3Ãi¿«Ø¢(xÂãl˜Š È5*‚‹…šO‰éÿ3.I³ /žO˜%`§½ÂzPÕU ³Å ¯â’pýÔT¡ ¼Š‚å-Åx©jCQ~F'ªìñÔ–ÓiŽÓ¥ˆR¡€Øÿ®s4Y wáB<Ö€GðztÈê0·q~nÍT¯Êžrf~;p«ÓeÒ…ðn11QøÇåv6èí;-ù`V}mÕâUÍ,˜›rÚ_=¼¿_Ð-Œ}¨³Ç™*ã^nVžÂ‰o˜îÄé¨b¿÷˜E ,…³„W"®ª¬’»®¢)Ì“?É•†¾ÍêZ‹Í㢰\µb›y­ÇJ×äM8H F¯Â,Lù¨q·¼±ï€D‘bìÊ:L%)³‚‚&b©m œÊìf§ê_‚5…•Us{7Q¨reZµc¢þö"µ;™ÕnmºÁWým#)«å‰èæ3#}˜‰BUHé2:ëÅŠN>V·–?Â*Î*¨*›ŽƒN†Ó4Ú”Åv`I–W4 ·6ˆãÃÕ'ÞA§ÅþÞb«$Û,ëדÚ8Cw,ªã©¼y…Vÿ}Xæ‚™5ø©€XÆþJ‰9«SXƒÙG'f£O1 Žy Â÷š…ÊÚÏÝ"|)+dxÑÞSÂFÄö¤$®\)âí–ƳÕT-gÎÝRLÈdF,MÊaFU Mü±’¤º¥°ÿ!0_éŒÕJ)wÌ®R¥²Ï©fhôZ'VÝUÇì:³Éd!•ŒBTº+cŒ÷´àEŒ|²š]†”Û?€Azt¦¿ˆ™$± ð-Ù[oˆì z2KÑcQv=>f_9Jãi‘1ØR ~Ck—uÀJÕáRR=M˜êº7 hã|o LQÄZ¸‰¶©JWv¶]¨±1¦ÓDA"L±74›,´B'ñTÅ^‡±!Õ„€Ýc •Bq`[¥»¥èòÞÓmIaJ™ ŽË ·a.àT…7ÄÕœ½™ì7PvD5hù™nÄ0 ¨Û™*T$+Ï´ ž¸JÜ~Ï¥ =Lç¦dš§%` lÁÓì_È@ƦËkÁ–â@ðŸ_%à¾y7TEÉמ8tÞìÊG R*V; ñµ­*Ùðiò³ŸG²³ˆ’¥­…k6ò]®”Žu> ØRù1=k³£ µÒ/,×UU £<5Ò‚ G#-¡ÏK#-¨;|k¤«!tAqk¤\#5ˆ©ý/Í« ÎòÒHK09ek¤56ŽÔYPibk¤­o´˜.Êù=õK#-¬:~k¤%X¾2ûÞ‚-óóúÙ×H„NYPçh¤|ñ­‘òÃG#]à —Fz¦‘^-¶.9Ü)á‡FÊ–£‘ü˜Fêÿ›Fê 5ÒÂ*[#-¨C~k¤k}ãÑH±Ú×H pÔ@×H ª‘tõÖH¹`´X%n—/ô“¯‘µØ‰UPód‹{…\\(Áruøï¥Þ)é¡‘®–~i¤ ñÂ¥‘$ÝÎ÷÷òx·Fz—k¤¶b®‘:HtõÖH¹·FºÆßo”;w4RÎv»N¿QP4!»öϹÅèS×Í•ß=”(åíLÝaÎ5Áë3ýØ)¾T…ªv‹É;¯‚âJ±œ¥M1mÖK %p¨ôƒu-[ å b³çÍò¢e2öß»™léɳÖ59™ë\‰ÕÍ0‰'M¤ó|1#®¿ÞU×çÓüÍËYyÛ·¬rz§Å¥•Õ’·áGh”ŽÎ,O¤ù`CÂA³O‘ù{—.L?ëÚÙõ®½ÀtéÚ%õðеK²Üáþ»A]×. D{ëÚî—®]PwéÒµ ]»à.zëÚ j·®]P!íÒµžºö¹uí5voljý¡ksx×Ïi]{C®k{ƒáÛº1¯Ôž¥…×û‡¹&37›®]rˆo]û¬uí=:‰!kµÃ¥kÔ’»tí’¢¸îýÒµ8ߺvBÌõiÄ›£#«£ÑâT† î6I÷HØ>W è²ð£À›«©ÞÁ °îexñÙ%­!:t0ªm˜(œeê“KZË„y©ø$ž€½frø ²”E㶂\BF³w] ¥M ¥°^8ê¬7ö¥ÁÎAô–¼q: …/Kܯò©,"ÂîY‰w«|ñX!=°<=NV5DÛö¨³*§åç´tâ (»\ ×ðµ±þøÉ+ëæ±¾7ÈaÕ8-¬Q?•â:aR–ƒm€R#ÝÇ ‰­ù‰Ã\TÞ¢a½_„þ§ ’Ùµ–.Û KKL‚¿97ºQìuø•ö8-¾Àä-@­q þzáàd m ™¥ðvX;Yßµ”É­JEÕ³™YïEqÂÊ×f%¶O´Å"MBSµäݼ•V½¡pë ®}P+¢!¯Ö­ê' ÜcbçàÒýd„e”Ff¤÷¹ùa øpçcÖ†.e£†–•¸µXÂÒ¬K(T\`‰˜N%CnD°ý3)+Ù?o*HÓÎHåÚù‚ÎÀ3ƒe0ò„ìo9käX8×È×Ûýƒä$žraô¢À,V¥Â€âÉN§ìý»ü¯÷†úŽƒí^ˆP¤“V«N";¡MÄ¡=‘’) ° ‘bí&B÷9g"Y=$±L A$’eW˜ÑuÂéýCð°È»ò )ÇV|êúc…7ß…//¸ñC<€ÀÝÄÆ´@DÙ[:u‚Ì Ž1t"<ùÁq /AÂ@Öbà¥Îþ}Ζ䢿¯ÃB~„ü«/jÃÄ5ÂI·‡Y—‚’øîQ„Ç Ì£éðäX­Z[fòØC‰3eMÈÑ0ïÑþÙRÖ™¾Ð´4.’PNñ`*'Ì€¯ÄÁ ‡6fphfTþj˜Aà`À 3:fÀäÆ ûÐÁ o20ñý ؘQË|`F…õÀ1ƒÀÁ €ftÌ@ú© 3À͘lüfÔf À3È”6fT:ÏŸ}ïù…UÐé1ê3>˜a-ŽuÍÖw¾J=˜­f }ÂŽ/Ì°B  æJcžd¯é¤Ç<í™;4wI7;i|ŽçGTŽç“tùiD \´òˆEúx¼‰õÔ§ä‚upQ¦òŸâ¤ž,FÎûÉAˆiÕ—Äð©tuÌýaÍ XHBþ´,0@>)CBŒé^æ†Jײ5[|Ù ìëíªÞ>¾‰j@C%š§kŸÔHìYÇu#ñæuûê2°‰éæ¹ÌX¦)#*KU-ôª!p;ƒ´%ì1ù¢⚌À?*T˜Ëù=ófÎSz:Óê@ *-ˆù*³ø’D‰Œ€Ái0Ó6zKøxa,¸Œä‡ S?nþéÐ>\µÝy¶¦Z¿Ø's¶¼Î‚Ì4†…CpQäy@¾sÎoÐqÒcÖ6< }ºÀÇ¡òeä鸖-Ì8ž @›d4€¾—· ™a\Gì\+6%ƒëçˆ3ò8œÜ Ø0Ñ5j!Ä5Iû¥è.Á‹ª”0k­oÍ ‚G-ê 6?¹uö0ú ëxÃUÍ ;kÆÍjè.‡¯ÏÀ­b‹ék²pÙϸL¸ f· 8Ìò¯ ‹ëháþÄH—ý|2äïÇ…WIçwþ/cÎtjÇ—&eT#]ºÏ—& `ÁkècIpp¶žl§åH½{„yttÝ’ÈbKöã= Ö>Û¹¥€™ª`d;褠=Ç*ëƒÎJ‡ü@ϸ(Z¬Æt­’l4û@'xt¶"|Ϭû@÷í}7è “·/hé¸íÂí‰Iûˆ›¼>5æ%É<Ò¾Fr­‘¾ND•Ä›äâ\gÞaè &ÅI*™~’Ç–ùsZäM±Ò~'å ûg üÀ/Áñ×…Ñ} é}¸¿Ü+å Z›É·¿¡½Riñ™ÖóKùZ)g¥R~¬”@[©´Dœ’¹RÐóŒ³+åO/¦•óµRÕä~[ Ì'Þ+…{·z~o™oƒÏ&ÿ¿ [}-wž¼8ãÂ(^k…³âÆ*o°Õ;aC5 ¼Å¯væ%Š§>[Z«ÏBq)GMÈɸ€9Œ&5žY‡ù2øïÚ/:±3uâ­)h:’seq=yâñz&FÞ\WšzÒû¦ü‡êŸÄË|Ä0Äc>bâ1å\ÓÃ|”siçG`Û6åŒåÝæ#†a^棦Û|´àxÌG ½Ýæ#ƱóƼÍG `¼ÍG«!Þæ#|žUÉÊpv ÅÂÛõ;¢m·ùÈÀc>ò3ñéc>ZoOóã-ãõ»­®™rVŠ•Ë|´Ö!óWå2-¸óÑžÌæ㹌Ë|”™Šú˜¸ó[Žùhå6~˜NË6Yºv©€@üĨDNk­æ:!ÿëß~ý»J„0']ý Hçb›Ô)s¼ãYÉÖ‡²6|5LFZÊ°‘˜‹þ»å<»ØýZ/.ñ?6€÷—¯œ:^~’½‘òa¿wþsËÂÚ{:SØ·\OA7Í–ï¯P™/ÖÙ´ ÿü¡¶¬C¾ÈÓ.Ð=¾7”qáˆz;0÷À| ®¶ÖéËæâ…üa^”RUùŽý€ü»F3¡T÷ôQ]íøñ÷3—î…G½…n5ðÓEÑÁËPóaUå5*`$¾“²þMVdžúõÔ”¾ƒke¦ã xŸ^ Ó=ê?i)š½ág7 |Y Ÿ«?óh¡Sή§Pßö±%‡EG’þ×a£—Šu¢=9Ûú\ž×‚5úŸ¬×¯“ ŠðŸ–EÛ1(3#êæJlp—,륫_è‘ÉXú®ÄчøNe¯rtPƒŸP\°lþKÖ¥ Ÿ ʆ„ŠjAïÄAÄ€£^0)žÎÏ5YS-¯?A¦õÆc•Aû•©Õð¤}‡ÊVå-Äý̲Þx9r˜<”°×0vaªýŸhÄ{i+& ìtÛŒã178” ©ÐÚHÁÿÁ‡Ï}õ j€9Cõ^pÇÒ·3BG•oÃÂ’·*Èe=Q€ˆQþãøÇ«ÇÚR0ˆ.—’ ™øð„µL?É“ï:ûG!@NÎþ35ñp³4d@®©íµáwDZœö_´ÐÿlhйZ…¸G"}eÁàœ1ɇØá?x‚9}®’åqXL4XWóIö­H¤[;n“4$9…#ÝZ‡1áÊ´@§\œÖgZ€Ï:Ü«£ž· £-w¹0x Ö>­p•áÍ`<¬w&cÀ~ƒÁ½˜Iæ´H[ð (Ù‰ lÜÇ»V´-ë°|?e3?„Ü)cوЕ)Ûˆ IÌb«Ðéäé0žÃÞé1™p”YÏ‘IÓáîäny_é:ñ¼0ij\ú˜ÂFx)BaƒpUôŠÂ ðZ‚°JL–LÝb¤´cÑôˆí|ê´ÖD€Î©¢³Bü÷ï#Ñ`×É*8îØýv‡©´ÂÕ‰D‡¨Á¸GŠ¢v¿>E&Ù¿+ÿ ºb‹®ØaÇ”k§o˜H?qíxNxnè †¤ƒ¤Óžá°MÉxõ°‹,¡Ã ø¬k/Efn4«;²0úÊÍCß,ël ÁAÙ€ûüOE¶G?ÿ!i°Bu²ÿ÷ñOèÿýøÇ[z9Ç¿}æœþÖ ã>¯ϱO_¿*AaI¯©·ëPáCAp­„‘ø ãô/^áÑEI)NntB«"•„tuÃëx©í2®w°ÅÓþg™NýkCü1•ƒp„À­IBæ`8^sǘ¬E “U1ñ•‚6wì ¼˜1³RÏJ ´•‚:eJ`ã{tc2<§g.¬û´—*Câî×J ôd>–ª2Üñô¨bÁ<8 ØbÕùX,€1Søä;FÝ‹•á›¯•5ØâÀ’ð¢Þ QL¯!!g Ó­D®U>!jþèr”á’ËR¾ˆâbJ¶ §‡mؤ˜¡S’˜²/kÒ”£lÌLŠsW¢áëiRvÙ=àW+I‹„S¼¿_ÇT{œ¿¼C¬.´f:•õQ\Ö™{Ž=x'ÚQ´bS^æû÷B1Ê+²š䧩4VN‰"%s™xä*H‹#eÂGS–!ÔS"òbf—'Ç´Àh‘Ä»bÒ·“†Ä)‹¼pöú”Âl¥× eÄ;=– 2?AäpØ|Eñ„µ “̇ÏÃöhL‚…y1Ø]ú<¿Ûb‡iŸƒ+ËA¶´»–U¡,s+†O·¥ù0o›ÎÅÞa˜w•ƒ€@J+ŠÔ†`Y¼ÖØ$›DŠêÎ'h­ö£0H»1Í`CÞÊ…Uæ0•ãïi(Õ.zYÙcÉÐw‹²ïÁñB3+·,TÎv@@œyÃT&¦«\Qø<ŠBM‚¡R5•×‘È?ÂÄðu["†€3 ˆü£@µíßá.ˆ;BZ¸½ˆ»´êhCÖß^¹ä,jx ˜àŠ×®Ç ¡´ ‡u+†ºG¦îòž(4l€+ã6jðɱóò 6×JÇŽn3QÆþ›V&õoù9-ˆ-RÍ {èj`oˆiàaX¾Îê]W€Ó7 …#òù}ê]w²Âä9î[æÃЯE°ÜÌK.û™Ø{RÆfßòU†:X­úµ0Ë~ý KœXA®{ ®}2Ã}ª×¹‚¢ °4Çó»òÞлÒ#ÊËðî­9žõb>–m$"éI7oœÇH1S¥òëF3þÅäê¤~n\±ÿ§ðÁS3ôU>V,{ò†hAf…¬¥Y‘Ü+ÏR{øÛ n#² µ!dx ­F²"û7Žy·H|‡'ZØry‰öKÍ=säÿ`öÒÖ¬ŸìÐg2ˆ<þÌè–f«×õ”™ŸXZaHC¢î:ÄÏa¹Ñ• k3Yg ,0‰ý6ÏhÁ\e^½òÅYöù5/DZ±Ê3¶dΑK{Pß-?–¬7 ÿ1|(ÉÎ}B:M†|%7ß_ÄÿVÅö –ÔǬGÀð~ uìt9#œ•U}@rcjy^/|¬ÜAּР<&3Óûg+:Êé±h&-•'Èçàà@¶™© ¼]GMe:•%E…ª™ÿF‡‘Û¯V%°"ÉÅK^~²5îšSÙeœuwTìíG¦0\§åêO…È’ªõ™A7nÙ+"#AVíti,‘¯×P¥dм*³¨y¼†S²Ž«3äÄ¢ÝñšV®zÏ5u°ÜãŽ~Ýûô÷{2Âêý-æî{Œ'¯ÙìcÎ5Û›}^¼¼î÷ÜséÖÇ–‡×Ìó^ÁÓÅWù¼Æwâ|Êwë Çwô ÙwýLkcÆžºW¨ª¹gÚH´ùVÇüÇD6 CÚH…Dq×ðΪQ­ [MFŸ<»—ÚO )ÑžBî~ŽÖgH(t?áBÚâéR«!Ñ~ „ò'¢¡¶¼͇ƒ{"Ñr1$ÚÓJŽŒ{êÌ#΄EÉÖßûäñ~OÆk½¿•»¿ÇÇÃúó3“dæ{^¹dG"›ûÙ}[&éž÷ ^b«|^ã;q>å»u†ã;z†ì»~¦å˜q¦nwØÿB¢!Ñÿ;½±‡ª²ñ±T3ô_f¶õ)jA8}=U§çƒaIç`ˆ>‹ÅŠ{UÞb›i°™:ۚŖ·Qó^0µ¦:iO:|Ùý-~Uv¾£©Z|4ˆcí÷€S)†u—0±–=qÖ §óÅÙ}æ Ï÷”àñO•7z5g³ÝPÇF\À³*Ù‡c/p$‹7©—ê½z§‹¯ðy‹ïÂù’ïÔïæ±ïø™ÔÆŠ=ñÀœ/ìzútêg–æﯩ)ú9²»’–(C.yyX+aîûsÁ—÷©Ì–ø,Ø“˜Œ¹vzç£?­w)Ì ––âŒûÌ®4F’ênH“ÈÐøÞ:¯˜d¹ï™Uì:þ™S,3ÛË lán¡ùÑR¸OU ³þéIR”Ï`=Q¯Ä™r§tÊ:,[ÅlZ¼ CþŽ”¯¤J Lô²þa<Î`†x®³«°›à « rîpZú?¿Nw¡G0ã|¶SˆcÒIÍ­BœVÑ¿æ`1¯‰ÓÀ GÖÈkšâZ6¼Œ‹`Ã_ýaº£HŠzºÀ*JèñúÂ,]Ì­‰\—•ûìök^S¡/kG¨}"fÐŽ^¯†ÒéÑø4kŸèÿj¦ƒ׫I;[ûC&”¨w ¬¿YÚ)8aÊ,ðwoõ3ƒü™˜!l)+йgÃÜ¡("u<&}L&¾›Ì¬Ïÿá£R:ýž’2쬕œQî?̵Ô)ÕÝšÆô"Þ2ˆÀC“àÿ•~ØñlÃÖ|å€óIÌUŒEÊL&xõ^¯©Y©À«Ìs¦ v%*Ì RøÆ£žY –)4Þš8ÚÈÜšHÉ)Lˆ–ksª¦­7ÌE‡ë^eë¨{ô,T̃Ãa_!÷ã$A°WÛ~P;lÜ.–Î~ÝTDxÜéHB˜Té)¢7ÀNtÏpÀÉ' øÏo"(üh€ÅRò Zºs£Ma@ç¥d-Dp^¡Ÿ†¤Ð˜»a5T’`€Ùrþ1 ôù„v/¨v¬í$[I›ªà{¦l,NyÊT©| a8¡õ.ôfù „tåùx'œ"Ò¸ZãbnRÑ€¢RƒŽ;X6ùµŠ AZ¤1`89ó› "ûzõÈJ¨¥8(WãÕ ªrAå,H†î ǯjg>Ùeâ'¦2Ùµýÿvœ#8hÛä›G¦Á€¢§Ò«V >|cìÁ›Ó`©WËtÑ«µ–bâXáâ"o!üåp¼–¶é€Bô_)gX³ã¦HkÛ?—\v²Ð5yš'sÄaÝ?Š†ä2/øE ÍÁ‹BhQnÌYŒ¸†¿¿`q¦ß6 oôòAé0­!.D{Jý€q›•p²åK_<Úh„UÞóù ²$,Êüžn°€Ñû‰¡izÈ"¢Ø›Óû Fc1Aãzºª¬ÍÐåÏꎸƒ-Él.ÈÍ 'u¤ÁR Ý!A"MHdËÐ aÙƒ ·5ˆ@™º†ŸÑÌ(f|Å»G%b£¾˜X÷jµàÐJ§.KL„}€´5»!“_Ct;ê°L7•8ÿ´æFÆÍÓÓ%»(“2N]ºÒy]4± ÷} ðcê1EÁp[à1x½s¶|7 9Yjò4M,ƒùyêíL¤NgÍ8õµÐÌj¨‘#Ü-Ó# :¦™} zŸ´‚dR™ÜŸ¢&Åy‹k É‡ã‚óÚW ))ÃQ7nèxÉÀˆá·y¢÷F#dÂrÔ_‡èãð’qÛœÇÕ™¯c™ìÿ,héŒuÜFFK#I;QŽÉ:ÁÐP.´238¯Â–XYÉɳE.’iâëâ=,rNbîÔ0€ñ3¨€¸õÚáIì0`¹•yKã ¯—ôŒÊHø€#aXØ#–rMb<î Æ{-Ô{$ ybÉÌ‘ð ê 4—"’úZœu ,RàÿL6ÐÕñÃœùŠÄg°ö¥ÙQÔ|sŒ6¼C“‹¥cç^e“NIª£™‹˜J«ZòÖ²ÝK³Íb¡¿ ,FN .Р¡_FE°µz=;ýEe‘U"¡¨Áp ‹-èÒàõÄ•zõM/ö«ÿ}>‚ÖÑŠ2š<@%óŒAAnCÞ`d ¬ìAû†È!ã½.ÆQPσqÉCyž–t[Ë:¦‹\‡rô`AƒDØ8ÓÕMBð ¤ø…d,D¯µ^‹µ¡ªt¬¦¯*kÌM.|#ÂÃé ËÚÂJÆAõØÿÆ"h?¤r‚¾Ö)ŽéÂeÄV-„ ¢÷^qðºßpòyƒ ccÒKb'BžÖ¶"Ù!>D8ð4rÜ-EÉôägnÁì39rW9]Ì_µ‚X‹uÀ°*n ÉT¥º!¢GõXGìx*ʱ„)cíï=ºEâ2o=y`iT¶vKç…;jËHÆÐ!3ötN!Vì¨WÜgN"³oA!ü€ôDå¥ÈxdÈú—ÃÄZ£aáÒ¨ÿ³Bòm2rpÈ1ôƒ²Ðm È-ŒsµCÁДŠ<ÄaXÞ *µÈ ç— ¡UÄ:;ËÔï¡+Ê“'h:0“ÞRß;-ä?ür1Qf‘ ¾‰Ú9(ǶŠ«RX²}¤hTTƒ´|ùfhtjäù3´,Ð*³ Ì¢Ê>ø\QW©¾È{¾È{>É{|‘÷x’÷x’÷|÷|‘÷|÷x‘÷x“÷ø"ïñ"ïñ$ïñ$ïñ$ïù$ïù$ïù"ïñ"ïñEÞãEÞãEÞó‹¼ç“¼ç“¼çyÏyÏyÏ/òž/òž/òž_ä=_ä=_ä=ßä=_ä=_ä=¿É{¾É{>É{^ä=¿È{¾È{¾È{~‘÷|‘÷|’÷|“÷|’÷|‘÷ü"ïù"ïù"ïùEÞóIÞóEÞó‹¼ç“¼ç“¼ç?’wDv‘B¨ã­CÖ¹*…I¶è@YAF•F,%,²€<Âêzß0#ï´:§G0‡ÒìÐ7’}ƒ$F¸ÁµÆı̾ªg‚?º+¨G¼G¦+åbT˜G…tÎ#˜>¸Œ~…2¶`CF #ªƒt-àlX=Î褹@Õ“bñœµ£0vé°2 kŽ!ÂpU”õR(öѹqŽöqÕ—ÿ±G³;bÄÄ'ñ}ˆ¶õÏm·Dvøž ‡Kø«<ôó@^*‰ƒ°Œ@¼@€În@D¾}MÊfgǦ‚2ÊؽÞ[TåÆKÓ”†²{H‡fâ@L²(ôÓƒåÓsÈŽÑ1zÊô¯Ý·`cÍe ¡£îaè ›ÊaS †Gé¢ ”â€ão¼4W>)ÙÓoÁÌj•Á›¹”2Š•,ŽÌÝN2FXü›(8Ô 4ñB; DÔ˜çLÝ“ðC—Áˆ©^è kl;+ü±‰ó;Y ð‹m0²ò7~¤´á÷f'RÔ©ÉxBûh1z—n4Ó˜OÔ‡W†`ðäŸ Ý-QÖ’æ”|@«c Vv á²h"ÂÕbtXYñvÁÇ`•„p®Ù*K“&$2ŒA~ß®™Ãø»›‹¯g³nDäjâ$ð^Gê¡Qµ&’‚…1ßÜ2âÖ › ϵ(¿Àl¹/)n˜1œ3?=¢Í·– XNw“ £H FüÁ­yv²^tX&^Œ0B¶ñÒòå쌒zWûŸ:ˆÎ^f²Ué½}ÆD9î]§ˆ!Í«Gb0ª«Þ ?ŸÀ>Ôºé—YÕ‰!ŠDeI‚¸Ód :Û/8I,0$g ˜[ö`¨Ý<„£Ö¾ZÄâÜ –±¤qyÈ<£ŸÄ­ëET¯¹óòÛäm[р챚æ #xtÓÅ÷Õ&‹*B–£B-Tš0+:4KŠ³(ÞZÍ¢F±oÁ‘åí 7ŨD%ù§ÐÀ®äQ _§Ü‹N%IÄ–#Ä@Tä²XWÈ·x+ K]BŒ‚|ø[¢”Ù˜!פ|&N%—@Á°Ab56ÕÙÍ€kF°‡ÈJçFõJ4bÜåH¿ÖQ€ÝZ9Ha…#¦]ÄAç†ù±|·0F»Á&Úü±(Y †›ˆÜF[L é¨~'øÅDû ©†x<'’ cHyÚ&3ð3Êšâ™,|ˆà’¨Õ†m ¹öªlT¬»°ÀÂb׃¥S6¹4%”Ühj*Â_.…(´T›Æ¨R2à£É¬JÄ®`t‚j€£2fev6AFІ¾Š—37P7)^ïC€ÂV‰äµÝÁ²ZŠˆŠ™›Y¹1*ÂG!F2³ˆR6Ühal<íQÓ3ƒ;+Š“å>—ƒ² žÑ—–8eè ¹[p¬ˆ¥â€4PF«c‡)Z†`5xƱ¦XòµÌG®çjâlzQd´Ã|TɃüD’5úo#!Ó &—¹þ6ll·1vóG‹ãvumÁÃö²ÏÌk9<Qúü9ÚB(Œ—§©º˜’–TD¹PåçIQI~ læÖä0ôç×ÿþ®——¦®]Ü «tëbþAÃ=rH8ÍwUԛѿâMLkZ˜P©ÈmW%\‚Ö îrØb 'sÖl!Õs)‘G¯~ÓŸ±}úR˜Öm„;¶Ì á%ÜÝá}¨D¡–œ§õ©'ïÍq¿É ¥È,ž„ôB¥ÓÀàÏ*×VA‘&ܲòÊ«Š0AâÐÈýþüˆËE%¦BW¯ÄZO¡ªú¯% ³=íš=2âç¶ì VņH[õ8NþÊ{N•J3@ã@IíÄ[d |ÓÐü¢=ªø’¼(‘^‡î^‡y·ç*ofoù9-pxV9Sên¡úH:*9$Åüjƒ4`²5«…*°3CC®Ê…šZxùC©v%B¬bößzP¥'*½™Öt¬ªº©Ì ;bÅ-z"d Ö¥Ðb™ÞgVꉙ®6ª¨Å3Â2;½®˜ ª©Z ÁŸ ÌÅ=ê5Ó…#SY0Þ™U`TŒ$¬'J0 ù…ž4ÿXðš™…D,VmbmB"ÑnÖ v(÷oPýéÆÇ â Ë/¬ò^߀֥©–t•ã&¨Êm¹)wMC¬Â‡YÏ›zïÕƒÎ^œ8l! ZšB‰¤bÛ°×E¹¹Œ¤âÝ% •Áå[çáî°Å&­z9±NbÃH›ÄýÝ-JÿºÞ° ÐGß0H0§l> +[¬ç»öÒ#å+Ù ¹<}mêTAQJr,û‡«Mnù~WK"ëW"à:¶¬òÌ‚‘ÕJê­–l‡€÷HrÎjÝ–”íE 9 ý8Í,±´ÙœX);2›©Á,c>uÈ[6­ \¶RãÇæxè-Á ÏÃþLÇŠ,ÚÐTc-˜’qß6ïJI·ß°a”H·*ÙÞÂ"iž“- ƒXÅ:z ‘¨^[C~°Ž}>pÐ)é4 ^dÖè §!,Sâ>9l5¾c¹zÀ'€=‚J’;¬ã o /BçG÷¢Å¨"½xàÒB—U¥‰mE%ªÎÎ µÄH$‡ƒ´ ­ZÊe•y|YÆÎvEÌ w•ñÀ\àl‡‰õÀå$ÀAùƒKÂõŒ+X–­+’ÃqYN)A ÆÓö'Ú³ñ]Y_‘ÿ™$¹–€*]Ž,ê8•bVéòaÑFAÛš­jªŠ³æ. Àa›V+WRf“ÑH@7ÏÀ‘U>©\$Ž¡ýÔFÑB”ŵlÆÀÂÙ›/8´Ùô5²^c #QeNl¶@p³AÆðš^[°ï®à â#¿ÿßì—UÓÅ ŠÈã|F8?Ç#©¢ËÝÄAQ"èÑÍ5«IûbÕËMŒªË¦½QÌÑ,MÙ¼ ïrFÿÊb_»ƒsÚDë×|Œ?ÁT_eë"ø<%³k™v‹­b¾À³Zƒé“É;Y½\‹E`/Ö(ÅåZ,+®€ÅB¹n¸aΤÅjZ¬iÒ–­–ô½½¼®›÷jÁ')•«™b’ÍS€Õ=ñZ.A•¹uùŽQÏrÁwí!jxƒV÷Aù ’°Š[â¯ZoÊæ +‚_'BàÞtØ6ÐÄ$^ŠæÄ`°ýfS{!¬‡ï˜3=™FR±\Üâhepª2ûÎßåzÒ§û0Ì‹§|ZZÙœ ¯Ë•¦0Q¾üf°_`EoUü™Ç{´“¥šT†ñú¡ƒ’EÓóéÁªé<½}YÕ=YÐ%]‡TÞ|*¡ÏAó¥xּ‚ƒ5?™… jÛ1Ê¥,£E€É‚ª1¿°«VÉ÷¹kèaªL±o—à{»ºÕYõ•aÃúÆ™\]µÞ½yØ>|¾æÃ;pTæÅ]Ö˜òï~ZβW^n0‚snÓÝ5ײP,A`þ7‰‚sʸK¢¬1ø='€5O‚\—Õ$%rÆ0Í´É2W¨èwÍš¼QÅbü´ LjM~KWË.g"ù³m=åïÕ¢2(. ÆÒ-iZyß`º™xidUN¡1gÓídá¡Ä ŠÝ#¥Á2œ%R¿RzV¢våÚ%ÀœÆ½©gÒ'³®½D€Ýƒz…ê„PìòÕ@˜}<œ¤jí»Ô< $æ²yÝ>Ñò±nZ#˜ðÅçY¹ZÒkn7½j6%‡¡-qkX™_Ì XT^­äõÜò8½ª“ážê}g«g[‘ ²]= ÆÚlÑ0$¬V$p+pAqEnŸ¿P‰_ (½Pz1 ôÍ€pR:â©y1 Ÿ èÌi3 ôb@éÅ€ÒJ/”^ (}1 ô (Ë'֟¸©=öçJT"¿»¥©2A|IµÉŒSº•Ϧy7;—O åTóóðž( ŵ]¡Å9“z»Ï?ªœ^ãÕcªt 6¬±¾w•F«ªR4ñ>öZóÞDmªFx5}“ïsS’5oU=âÇm7 ¸ÎŠ¡Ç=×½èµEåÔÝ°¼öYï¦Ä–R”4Ó%ý‚,y4 /W¯u“ëZ˜{õjɺ£i“Kä6Å¥*ëVV$0{7–5®A`á¼…*CÉŠ‚øÕ-ГLÝ⇊Rš~w`q|a·ÀófY¶¦Ágò¹®ð’õAé Ö8^äÍm æ³R°Â×iŸ>-¶ÆÊÇåûAÎcv媫$ЙïnÑ‚ì}%øp1nÎ ™MÙAä‰fÉ Ãܱ¢ÿë×ÿËí4uendstream endobj 6 0 obj 44717 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:02-07:00 2013-08-20T08:42:02-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000045021 00000 n 0000046591 00000 n 0000044962 00000 n 0000044823 00000 n 0000000015 00000 n 0000044802 00000 n 0000045085 00000 n 0000045126 00000 n 0000045155 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [] >> startxref 46761 %%EOF ast-8.3.0/sun211_figures/series.pdf0000664000175000017500000002364513004147321014003 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí\KŽe9n¿UÄ؃ðÕ_ZÏÚ=èЕmD(xàí›çð#ée.¡P(ä; }IŠ¢H]ýùñ|¦ÿÙ¿_?_ÿþ_ããÿ}=Ÿ­×ÚÊǯÚVùí#µÙ>Kûø¹)#IÍöQëÊŸKð,ÿÖÒ'莿^£¡Î |¿z*ÒXJKù³µm¶^¿^NÉ¥±æwP’TÁ¿ÞæÂà¼K‚¯—‰ðûåC&ŒùX;Ž½§¯×?ÿí•ÈŠ<9Ñ^ üÜ”Ñ9ÌZó¿iöª¬xª´øëÕ§t\WPdÍ™cu++¬MÇÖ«LÆ(y ›NT©lÊ›èü™Þ©cðCæ°D‡î”=5mÓ±uJ¦ÌÿÆü§üÿ߯çã?þbÐÅ ¯¿¿þ|Õnšþd¨«ðdLÓ[£|”B-ý>j9åÇëÿ#ôG¹ó®im4/ikëﯿ‰4þxµ'{ÙŒ6~”F ¯³äÜîu8'ëc#³ÙGj-Ö>¤FP¸œ>¼…µ”î}8–6 §ìQj ïó êb͘ä„-†bŒð22ø©”)Ö+=ŠHK‡­“_¨I4‰¶.(9±ïœ—¶[È9—½Ò3©¥NùJÊ'e5“˜µØzýz9¥tÒwPòryh›¹8o´WÇ_/™S¾_>v§øܼMÇÞkؽœçä"M«« %÷Á&²Š&•¬ÃHý91Ø’il‚)MºQÖ“Œ-Úf`ëUØb”š«MÉ)ÅØãmÚôNcIú¸Â0ÈÀŸcÑú¼¼=ÇÞ#Yò;6;`ãNg!M5ç© Ûœ’Í9HÙ°.†ú´¤ ÌP^iKJF5k?ëä1ûÙf`ëUÚ0J)Ãœ§ä®ÖÚÛÌaëÕ±˜%™SÄ(ÛØâsó6{¯ÛqH6¥¤nÇÏMɽӇz:§âÒ/kŽS?dJØýÚ©1y,ekÙ(Ù´m¶^Á¥Ôçq›`”’UàÖdî¦8֩㯗Ì)ºS|jÖ¤Cï“Lù‹!'CnG¡?j~·£à”í(ô4]'½VPnG¡§Ç÷Gsœò«£Ð±IÛQèåòz»ÜƒÛKð¿› àµZóÛGh¶óxý6nÁñöœâôÞ§pù­¿û›^¦7Ÿù»ˆ´ô'L¼nëÏ47.÷lÎÄ47nS–9m»ÖºÜ8¡«&>Ëܸ •Žì#ê~<Ë\¸ ˆ±ÓÍüiŠK2“m‡™bÂÉ2,n>Q¢VÅÖ‚cë5œ2è€E Ù·û0,5|^"Æm-¼ÍC÷Ñ6l[ªfr[Î@7ý^&•é‹¼<6ÜíÃmùÔé«GÍ¥ê”ïMY¾V¢ÖºW˧._="nÃN¹åƒã¤®§´[<í–N{N»eÓnÑxó[4u˜Ïfõ«)¶wàx‹&Jø½…·)¸hº:ï¾rD4õäÈw”ie†íÔÐ.s‰fØÞKÇ){éÌçqaY­M¹E3–.ܽtœr‹fpÜéÍL]·|ãÌ,æïoéìÊýhÁ°÷±å3†ùØÖÂhÕ°öáxË'Jø¸½…·y\KgЉIÇÒÙLð2³¦ðtéì2”lHfzrW##b·åª”gìSlãI©ëú,U e­7EåSSëjKsWÑ)M—š­y1"ªÁI— c¸hn/¬ÄãÅZ¬} †S’®#ka­n.œöáXjØ(v ¥µð6õoŠ® ó dnE—ÏæÙÛG¢Ì%žnÎýS¶xºpÚœ¯”[<ýY6²ználï!(ŶhcKo¶…ãoáD c}´à8¹ä”6—l¬…6ì c}8ÞÂÙ%t”ÑÂÛ<.á´žná ¼Do?RÑD Æ òÇ¿^©<ùc2„eH8Ä”ŠÏ†£?¡ÌªwñB×úœóƒ~Îuâg¬*°~Š?„3aP«–þY~EZyŽÖJNìhVû-6¸gÈpÂÚ—¥õŠÒZÒÆú€ËƒZ'SŽJ£LÖ5Êzt6ÒJv”ÅÅ2$™–X9RijMÝÿž¤“]ÚÑD²áæÉž9óæGÇ4W2`ãWÌf|ÖNF"ž“yžŸµ ð¤éþàhP´ªì1õWTuèéS«Ž‚!,í¤.6Žgax¬„ XŽEײ ìÏ~5ãpü·},#Ñ’ñ‰ïý”¶EAU¬Â¸E,ª³±tWŸ‰ QàR[w&¢UkjÑñ13CNü‰]k¢T§TŠÈ)± a´H¢ŽŸÏG¤,+•Qà"PÊ ·e%h‹c¨Å€³p”‡]vqÿ3ÆUÄ™ÖÎ:¸,PAJ®} 3DŸ™¸•˜$ZdSDC"*Ì‘ cè†QXzÆH¢„õVŽú†¤q“^P”7€¢Sl÷3 7ðŠjoåQ|Èð9Qed±¾dF–Ž–Ô ä‘H .ãtiFiÙæQcª˜ì2€=@¡,ÔÖtýÊ tHW¢)6 š1&R8ÄVÉ)Ì@®S=) ®ÒÁ¡Ð ÏL2ŠØ4‘ÿ¥ì¦ƒÆ$ÇÔúÌT}Äe`\E†¥òï6ýŽ‚Q¿ÊàËÕC•é=TÙ}3ײ-$[iÂh­ñC_ÇM3 °½Qå\ŸÅrÐäRÇG ¦›*Ê–dª!M÷¼W"æ<¯¥ŠS;3tc–>ZÊ/,Ó]âÊ…ùÈŽ†\¬ hQJj¬¡ba3M³˜ŒAÁǃņ‘3ŽX!Ph"k†m< dœ•ÅqU€K,ZMÉÈÙDU¼2ý1|"”EüPŒ* îÊ®š¥=œ©­ÖÕð¾!µ[bB‘š®öÈo1ö‚*BPc4:¥ÇŠ±[&Ä>u­KíÔ%1™2ƒ(ОF3JE˜©ùR DX‘ö{Ûf¯bß©§aÄl¤â.Ñ|™W›¬G1”¬6…:ÏÖÈàE£üdå/öO,M²×_m›ÿa퉰 ¹Ÿ;×|mbh`lÁ'4H9F#]FT9 û¶yèÖ‚õ°à)·§;*Îîf~—€ä°ªâw‡¶»J#­{«tK·J·t©tKï*Ýò­Ò-*M* t¨4¡«tË·J·t¨´­ÖN•D•nõRéV•&•&Ú*ÝêVéÖ.•níM¥ÛxSéuªôºUz*Ýæ­Ò­¿«4fsªt«§JċJn•FlàVé–·Jƒ¿‡J‡à•ÖæC¥ªJ·z«4xr«4OGy¨4ÁViÀPiÔ;UÙâ[¥Ù÷¡Ò”œ©´þ¾TšGžà‚Ì£‹WoNË÷&$¶GB§K†Ãû0ÊüÜË"áHÓ´À€WÇÈg,ƒÄÑ›É.1ésÑÉVÜEt}ù6(šHÿíðt¡nµ ¤èäeTv…"îJÔ_–E\›®¾6¶ZÁåè À‚–‹ú¡zÀ…@/ãPQÉG8&‘üÃÆ^©ŽRÖé ”% “£¢ˆÅæÀæAcÐE;jµ¿àØ#U¸JŽæÍuC%¬Ža.dßÈhaW?¤Ë‚‚ƒ&Ò‡Aè²sÃ5F$zÔÓ=ïâŒy”èÍýNý-r¤¶ÁÅq%4ƒÂVx¬q1¶ªÇ•-F§¨àd³ûl!Šwƒ­Mµ]° ¤ÀcãÇZ3ÿžU'¼šPdMÆp1Ÿrž|z`©?ž¡,´Ö^97û; Š¦Ìup—mBÍpS}2ýš&>WÙf¼QMÆ‹Jì€Ö *UVÑ3U¿qeçi\QhˆŠŠ½Cw_«Ñ“x}I&pŽQiYÏsfꋦzÈ›EÃŽpQ·&|h‡¹úþç”TÔ!²àp\æóô:ÄëF—¢zZBà`³^;‚b­¦ŠÕeiìƒ;èê÷u?ÚM v—=n§êÓº¯SÚž!Òé4®0,ÿ0ê ç>®†˜ÔPBÑ l¯ÃÜ0Ž';ýM)<ÿ258ŸG¶ÀD&ážT!o¾ x=hI'¬é„Å@ìzÚo¼§–T‹!LLp?Zá¬)Öùd¯dËô…«'d&8UúâÏB'‚+1¤Ø4¸=RHJAîaª1[‘™ µi°jÛƒU Ø®‡¾XjV?yzäo–RN!0¢T1SŠˆ–ÐiÀ™ «Ln_º(€—ŽbIÈNJ >-daC!,ÉØŽHv]²ë’£7EdÈêñ½ümê riªc(sâZs5ά†ÙUÙ–Óä–£0våÖ!c¤(fe øXUsâ¶?´EGZÃßØåt‘7mXGÔ™TM¿§cSœ8ùÛ–ösdÿ$Ÿ1c5(f´Û1ºä~”0“)Ö ¡=œ¶ýzœ%Ðœ¨§Ï³cI£s®DϤoª­Àfꬩü¤VQÏô6t9¾ÔÊÔ´gšÕüÈŠ{fìL2嵸œ@aDg-]„n!¼ËIUtYÂ왋> ¨ò*Û1½°«Ò™/àÀ´NO¬¤ºûœØ4ÎPªXwÉ”vl:Pµ}w‰¾ Ç‚ò§§è¸ADˆ”ÿN(6ÛGC “FT`¡ÿ¨›:Š'Ú=Y쪩3gH”q£€_ò‹¸ÏêpéÂ;ÙøqoË)˜/¶X´pìî« 3$ì `d xˆüg¢à^•(H^Í£ìŒe DBad .‰áÀ83äÙ•†ö#!°œˆÀ‘Še ¤ÉtÄ¿œI;&ó»òÔ˜ >!¬3QpOcõeù—»‡ÑïdˆXiG‚ŒÛ…¶ g‚ò¸22‡uf (Ã#Á9Ï{©Bfçb¶sªe [bcÏ@8ÅÜXi°ï „êÁi;\+”uF_ ï—Ÿ0ßáZ¡Ì«B§eáZ®%ÚáZ…®-¸´|„k)×ÐjåÙáÚh· .LD¸V`‹p­×*ŠpmõÝR~Ÿ 3é!_áÚ‚Ý®-e<õ"ØáZ…®•Šã ×–RŸ;\ËÙáZé:ïp-Ǽõ #R °ÜáZi¬z¸–üÝáÚ-ø®µæ=\káÚ‚;¹G¸–<¹Âµ2—~„keª-µ "\KèÖ‚õŽp­´\îp­ö=œ†kí÷®Ž¿«t·J—y©t™ï*]æ›J¯S¥×¥ÒëVéu¨4³’‡Jã^J¨´V«ùTé@Ti\8Tº>‡J„Jm•®i«4n**]ó›J×z«tí‡J*Mè*]ë­Òµ¼«4fsª4.Il•®Ï¥Ò„[¥ëó‹J¯­Òàï¡Ò!øC¥µùPi…ªÒÈAŸ* žÜ*]Ë¥Òµ*M°U0Tº–[¥y½ëRéšn•¦äL¥õ÷¥Òk÷È@ˆÖ•‚g J•íÊ@¥ˆâÙOË/w¢ 7xd —È@ð áÎ@(´¤Û929Æ+±)1rs‘ØÈ÷Âuf Ï£³µS!hyÍ+Q,{¬ˆ‚‹é–ßOd xÊ@¡e 09Ï@°¹È@HoÕ3ed Íšë†J–8Gç²oiÞˆÒÌAÓ „Àtf Ò§W¢àúÛ‘(­<îwêoÏ@í „B3(låÈ@ÈÀÖØœlv¿€b«ud ·È@(ˆ áÎ@H[åÈ@°é#Qš“¯ DÁgGBðð „þŽ ad iB~×#¤Ri½2›ÂA"©VÞÁžýªgBpŽ…‚È@î „BË@”&:µV©Ï+QðñÄ‘fõ3!¬­w"(Û·Zî „èE=2[¿¦‰ÏUöÊ@”Ž‚e ÐzõÑwBPñ „ü~v¢ôÞ¯ „ò(È¿ˆ‚lÈ‘(]Zº2¥—tf Œ;02A± Dé²àŽ „4Ø® DAyg >GBª;!”tf ó¤žä'¸ú ö‘<¯ „”oGB`Š „‚È@(Ô Déæ†q 5ï D±”¨þ¥Ï#Q½º2¥C³wBðò „þö „"Í@ÈïçÌ@H7ãÊ@Ȉʕ(ÈSˆ‚Dod 6ò DP4A!iÿ¹3B©wB(Ã2òsyBØ“,Qp%¹µ×3QÕ;3\;!pEBAd –dìŽ „Àvf ¨ˆWB(óÌ@Èó‘A¥;Ž?ãüjžP2Æqœ‰2&2ߘ-ûvÍ@èoÏ@ZÖ%.Äiâ}:6Åre ‚`Îxg .8\²àÈ@”n&S3×(HÀZ¢0¡ï±$Ï@(² „¶¢èGd \Ïô6tÍ@œS;2eTÝïääñs# “‚mi‡IüpYb­ô÷Ž’zÌ÷Û ì|ä9R¬#EvÁû8â¤Aae†ŽÂƒbò 2«ÆG¸N†) 6i€Ðâpàgp®`§¶;´T†/¿† »'€1z*SƒGHûgÑuÁ dÚgÄʪºÆM=ïÓÂq³êŽ‚5¥¿W”„›‡í˜’oEAT¦ªX¨˜Ãî/uI‘ÚƒR)ÃÊ”3H #Ê°í€1áæ¬;ÎÄ-„Tu 'NšÉÔQË£bè‹lyúECȯì`8áí| þaИìFºjø/Š,~¢@̹fR|Žbù-VM‹¤[3!G040݉A{üf¸¿ÑÝJÌš‚öÈi1+Â|˜*)и g]xðãŠÅÎÜZŒ„Ìž=s—ÜÀí.¾ðpÿH}Ø"|#rÄ)†qMÜâêGƧü׆p¡zgæŒ ãýÅ´Ý.1y‘›W€ Ö• –Î #•>™ ÈIïyúrjLz;F…ŠÜî.Pè²i1'ôRRÕÄIA¾[•Ì%?¸ÿ‡ä ð,FÁu^lˆÿ¦¦î“Œd~΀9ãè»ÀêZAïG 7 Ñ[}YÆwø„ Þ|+·²Ã—=hað#€¦×12²_­F—8ô£Dåm0Á²¨˜¡9H8懲÷+›âƒÛev2XiØÔà-¬¦|'eôÀœ¡¶x,2 §à…Yò’–¾Ý°øéH‚?:¨L“ƒ‡3À®‰Q;CaqS–×ÔèNBi“^ã„šðA£ˆ{eņÔòU‘¡Ãˆü3ƒï‚„ )Y®¢¦zœ³]âÔ«F ‚®p°ªcý´u“ܬ„¢‰¼N*œ)úѬv”‡\}ÓáWÞ,zŠ1WÿλUi²*?  °äTNÙWÉ„PJ”Ý+:;(zÉ'§“5ø˜´ý*§De²2Ng¬ «-Q€g²Øì*ʨڵ&¿×ò™غ3+)ëUFŸ9‚εî¿g²qak3€û®U‹vzgG uêÛÚè¹¾žžÇÔë\o$þ Q½^ÏÖí«µ8ÆÚRíqïÄdt¯P> ”|;mɈ6“¥(+–. B~Þk+ÌþŽ3^…õdnÄÔB;Êz#áе ľ¢AQ‡Ä À›Ïx*awÔ¶¤É¢æ ›|¿ ˆN¯‚ æuJªÂâg¬éH+2­þÈ· /¥èX0eú÷ËAvÁ)TWŸUyi<é7ö¼>Ëk㘠>u$5ñuLÎñçZ0œ§ºƒÕl÷%ÄSb!2>õé¡ ¹ÊÙê©z¸¼Ô…4û__Í¡ÑT†¨]Í:òŠ§üâÏvë\™CF!»¢ü ìtNX+›©DQ Ÿ$? ¹ÿ]ÖëppÍe›©ºß&ê3!ÜZEf,èp°eÞ…ÉøFbmË"}o ­S[[;.XM¡ñîa>œf©á6*À™U›äWÖUk½Ò«õÚgÖ+ã:Pë¨ë¥Ù¯Ýuç…’Œp%k0óv‚~_ÂyWu»½@µ/ßa§ÍÅ—X46ÇGÁ6¶@Ç QvÎjØŽ£°ñÅvjQvÈ‚^R?Ù»)IiËø’CÈcXmxVU?°ÑÇûè(Ð.µ¾)/4ê2KLñ%œƒ[ñôL4ªˆ·)˜)¯d„WŠy˜°}ö€Ò_Wó~TC±Ú àæ6 >t 0ým^ ¢@ɶی6 ÓÛ£CUxCU3 4=¨‘€¿ZÎý‹±ÈºÿÇM÷—Lh^f枀òzt±³2_' PlïWÈãßWaKâ²,m˜Ã&DYkµªÇÂòN1¾ä¥Þ™Hñ1ÜÌ»Óã(Y­+¼®Îì–×ÝËíÞ¶n°eŽ¡v• LfË–1P4|î?·¦f²©Ú PøP…ø$ÊÐÓ 7>^ÃwXí´ÑmF?©òèem|̤#ÓëÃ<¬Ôv?Ë¥éYbÚÛ”s(ö©^†}ó¥Çi™µ™ö¤"ͪÊom]­c‚!«uÔ×#æѾùËþ÷1Ì[MªI¾¸Úü´=†kíÿéPšm(+_âðF9°wÜÏdwæßs 0Éõ¼_Ñ×öÚ,ÉHcÏ>b<ôrÍA`füû L†h3È‚D¶²á/¦À¾Â¢¼»U}ÞnUŸ—[Õç»[Õ×íVõu¸U ­"Ün•Bs«úºÝ*Èc»Uô¥™|¹UêNév«ðN¸U ­RnÕH‡[5òéV|»U£]nÕè‡[¥ ܪÑ· ¹„íÂU‰Ë­Âd· ßðnÇ»Ý*…áVôæVçp«ÀáÓ­ÚÂßn•µïn•Au«F¾Ü*0är«DÙnÕhÛ­âïíV)4·Š©—íVá¡Ë­b¯Û­R™[eàt«þ|1‹Œ=*žÄõ'G÷“¸›OâF­ûIÜôñ¯Wåó.û\ä¸÷,.ÊꃱùxwSôQ[Ö~w÷ìÏââ¼ìŒ•Ÿ[ û“µ›¢Úz ñ,®õ±ŸÅõQ8eR[xŸÇ—^·”÷gq½Ì~_­¿?‹»Å´$t¡ì ƒ²$ôZö“B.¢ûABŸÖ~Œ0(å’Ž?6èýµ7ÙÁoµÆCNñ§½~[ý}ÔrŠIfÓmAÔ©¼»OmÝ3䛉|ÝÛ)Í^æ®öÖÈŠ³= 8ìÁÍÚ{øÐJT{Ö[¬}àmI§$•·µ°–?t×ôÁ®âoëâï>D¯~OB_„šdü±jê´§Bƒ^æX5ë÷Ë&ÞŠŠ÷ºf»(ß›²—×z_6÷ËSlìч½ÎUS›¾|<Øån Ûàñ@Wmzkûx°«=õzÒ«ÎûÉ/ÇûÁ.£Äs[ÖB<Çe}vÙ(v ånážÇ%ž½t\<› ^æX:ë7kço¯ÿZÞÀ©endstream endobj 6 0 obj 7761 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:04-07:00 2013-08-20T08:42:04-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000008056 00000 n 0000009626 00000 n 0000007997 00000 n 0000007866 00000 n 0000000015 00000 n 0000007846 00000 n 0000008120 00000 n 0000008161 00000 n 0000008190 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<0A2F644D7D8433EC3CA163F3E2945A32><0A2F644D7D8433EC3CA163F3E2945A32>] >> startxref 9796 %%EOF ast-8.3.0/sun211_figures/fsremap.pdf0000664000175000017500000006060213004147321014140 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí½ÏëÿÏvDÒô­%]•®’÷BŠHû¾óû´¡6µšªÐ0BP>¶MÌûÛKSk„bêÊ… ëÂ….ìJш$bÛ$†þ B¹‹4ÐM—[cèWsÇãqÎÌ<ߟ«P»èæÞ˽Ÿ÷™×<çÇ™sÎœ9s朿øÞâkÀíßO_¼|å_ë¯þ/½„·ÚJ©ùõÏ¿”’Û[­¯©Îôë매Ïò6ëkI=àß4[@y m ¦ÃŸ^J^ÊÜ%ï/)­*eì’–Öÿ‡±ÛÜ°õúéÅKr×—ï»$öú–kzõ6ç[_ƒ°. ¬ؘ¾¿øUÕæãí8ì=}zùsÿÜK*rø µÒWM ÂKF h¾¤À_rˆE¨ü×áO/yuÒOÁûKì‰õ’Iõ±›Ü°uúéÅKJ‰šÍ®’›ò&{q”±O ËK€ ÜKöĬI‡­O¢d¼þôBËŸ^ÿûw^Âë¿ømô\èùñ—º™(ÆEÆ`‘ªP³Kzdï1CUh¤ÌÄ ¯QÍ,2·’÷—<Ÿ¤ VŠ»É [§Ÿ^vIiœÎû)É•mx“©±‰Ý§ÁŸ^ö¸¬d­ÜJöÌ¬É [§›bL’­±Â§¤wr} yâ“4šØ5uMX K“`±’…“Ô4!+IÙ`krÃÖéBŠ—Ô4L8yI‰ì>'09KÀy¯/¬ØÀ¬`!ÅGn%{fÖ䆭S!åÛ¹BZdÞRˆi‘ÜO¼”¶ê&ì!-ìäZßRœßØf¸*Ç@°½¥Ååæ·8ìï‘Þz¢ÌYPkJl…Ðbô`ûª³àôÖÊëî¡.vßî’Ö´¯¼5~ðì`˜â|>"6Ju•²ý­Ap»ZÌiµÍfšM,뻜mÉRyËè_Ÿ->_£âçK q}¬äý*YX %þÑ)Xøh()m)e­ñ´Ö-ÔWÿöñ­Ñv~I¨]’0¬åÃgP âx+Qƒ4û[LÓ~*ãmþÙ²ð¸(4ºª×ù¶Ö{•ôµK¯ñ´Urøê \¢£ou¢º“†•¼/úY,Uuʼn~VÙÚFxEÐûeñJ«ÏFjÂ(ÊÄL°Ñ$û»¤·Ð)Œ±ª‹‚Ø5®¶&¶š˜YSV ÖE]”4@0»€RóZÀ?U}•¤Õ¡\˯5£˜jöÖÑ.!ÐCgC„reÕµšTÉoëߺˆˆÌjðú–ô4¯UÃÀtK_pãÏkù–².jâ®ÔRÞJÁ®5­e¾µ¶ÁU½vãD«°$MÞW»kí7XÖx±–» r®‹6l© ZoF)‚1üE¯! ¬±6 µr‡ÖtR§hY¤±h@ÅuéykÖ_¬’é° ÚÛ€Aµ« µ×¶2Û/]µÅ /%uÑq¸Õà¯ö÷Ú_ÃdMÃ_Kì(ŠÐÖZbÙÚžNzmqч/xMx˜òl% µA¦«½x5Eª;%K"åµÂÛL‰(^¬<Ë׋'©Æj̵¨)ž6¼h6qT§¤C¢Ô9Ö<Œl=ÔÙ´¢¹¥çÛ¢,Q;_Ñ_•és«; Ö—N…Þˆ¤µ@RÀ x!8IñÔH‹VEäëËqÁ.N^²¦LípŒK¡Â˜ÖV4ð{\h_(Xì_#¥l{+DZÏKfQã ¤D t¨n/éV‰,‘ѢDž¨E TÖ¸9Õ%µé^ Éd ZL¢÷ºª…pŒÛv©.únØŸûT€sIÛyZÀŠ<»Xò8Ÿqž¶µ·ò Õ Å¸…8hõ*ñ3X'vÓ–´^8j1sÀ–ikWhcƒšR+q—,b1yíï…ìÙ¸ðXtTÏ\e‘x‚k¨ÅÉѹº¯*™ŸPà·BŸ.ñ/ÐD~ë®þHä·>ʼn úÛE>!ù„ 4ÑóØ2w²…þ)¡˜ï±=ÿti߃ŽRÊk}÷¢¿W÷h@Ë„ü¬o2îKÇ’Ý\×A,ãb¼Õ£!ˆŒÖS-X\Ò-5ŠÁ«þÚ.êù=Wm ú›¨çŸÜ»kÔKUèKâ7ÓxÖÑS‘Ú¨9%ÂG·Íé#¸QÔ .¬Åµyô–Šø·£¨åE‚„"œS²0T†ÖâÌd›{#Šz2eI(ê&ö‹Äë¼Q4ß僴>ƒ´Êô·4Ã…$çßV„¥¥#dÍѱ´Kˆ–±v¸âç Õ̱–´8•×¡--¿-é©¿ C°%~EHºÎX§]nèÚ_ú’H$1߀6ìw_%ì— ³½Q>BèÚ8‹dqƒÂÚ!mæÙÀÅ,oÞ=¤dMZˆí TˆˆÃåÞ™‚ø%=– m‹ÿgˆ¢gl¼K¹³J‚@î¬%Àl ï’„cÍ-ß5æ(×ôþ:u .ªÁ®15WØÐêÂvËR›Wǵ Ü#"„Ù\Ó éE¬Û\¼©m:+=¹‹D0C¶míW8ëæq®^M§ŠTŽ‡°hS· k§9Z¸¶3Š†]ÂíßW‚ÚF7ErïK-YTuö•ƒí…¥ÕãŒåM‡«…«48¥„=cýiÒ¼hBk¯¡@׆½çã;úXK8¯ß—Îb’;‚ӀؤF–ÉúCû"æ»0ÀõÈM€bëµ[önXIöÄ_\ '£d*'¿Dɧ/^þļ|åþÕ×÷§þòŸ}ùʯZ/_ù—^gùÊŸø3ßÿ_¾ò'$¾„óå+ê+ßÿýjæþѯü˯dýòý_}ÿË_ü…¿´>ù¾ï{ù?ùú‡þ›ÿë?ý׿ÿ?ù­Ÿû…_ø•ÿãW¾ùÿýŸßý•ÿì{¿óoý•ßúû?ó}ßûÝ?û[ÿw~æ{¿û?þÛçwþýïø¿ëå_ø×|˜Ö™y± ÏõKaÌ2=íh&0¶qŒ³×¤Ý“¦5‡×)7é[/Y§äØŸß„¡c½·é°õºÚð’\ª´«]’²Úð6cQÞ«Á8©ÛȬ&°ùüÆçæm:l½nãS+¢ñuRÀ‡_œ#Œ’#™…WSh‰lÂa %Í»hI ³ØéѦÃÖ+Ðb%%t›’—ä„k3i|»Wƒ™•-6vÿÆçæm:l½ -íõ§¿—xùV¨¼dý[Îk°#?çÖ$ðý5êˆcfX`…Š .B‡J@ f‡"X–(•!J`M´DÅSà@K”÷Rpš¡%ꔚý"OŸƒ“m¯“ p‡Ï×ö¿à¦¾–ä3@ã@ÃëÒ¸iŒZ-5Í/èÓ”²8?p[0 K±ô)kTN¾”*y?%µtŸöWw ìQ«d-º‰´G­t(–>ª.ƒ”kÌ´H4OT¥MjÁkr)Ð(E€¤Úq‚±ßòxhfÇiat%ÂA›Ô*™8­DX4:Ui”Z0- †UŠTL«Ô!•Ø¦’3,Å„Û¨Q¾ß`tîÂ\aý€‘,ɈéÀbš6tLX`ìå—„Öð8¤Ó8E"*hÆ:¢5NèØ%Dc†± pHÏ‹ ±I“Ž¹.8UZ‘…J ¨„&*¿%~W5ÁD]dõµE%ÓMVI†BuÕ¨ &¾–dÁ4R‘$h¤Ê«Q­4ô›…§œi¦")/myÁ´K8Œ/ñ‘W½F¥!jÁ•±á5ZªNI¦•$c›1(좉‚s8Rœ q@kŒ°üa-7a¬YSUzQ\–êGSÕ*¡vºJŠlU«„Æ*–¤Å‡Kx›°Vmø¾Ð¥Â©T ¦ÌUIÚ« \¶©¸ÙœÖJ€ÁjØt§m×ÈBm50Ùñ†5ˆw ®®°Ú“ Õ(‹÷Ñ76ª¨éhK«¢õUµbÀÜbNiÚ&æ]”<´ÙxEäøw‘’(nvB·’J4\eìôTT—HDz–@ËGE¹2iºrئÕÊUc ¸qCÆ+×"P8®oD> Î6˜ãáô ƒ›o Tßû†|[(MŽ ¾-²H"JðmàÞÙ¶€fz9Û‚õsv…]À] †öñoßÊBÖtµ-IY7ÖÔ& ‹ì3ŠË„ ð 'bÓˆãfÆ„&ñå57ÁFÆiuèŸâ[½*$Û[A 1Ç¿5Æw‡Öð¡p€ïIÐ2:áá…¦S"Ü´hÈø:¶*îlïäåb>ÈàÈ"te …ë‘ž…¬dUس„¬&dµ$mË°Õ´1ld´©ó` †ärÕAè‚ `èáF¡¥AaE£^èZšÅCÕØÄÌõùsh Vjê5·0ÔM8žhÒ2ÐÔ¤:»¶Û„xÓïmj#ÂkØŠasÆ>W+íZÄ„a¶Û¾¡ûÖ%ŽÊÕ, éÑE´£·×´kE\ÁA|8û{ ÷˜æ”U+óÖ´j^â=ã*¶Ùæ 1“´öúj‚×¼ù®Ñ²¤w0~d܆‰ö«ìZ¦6à«`ËÚ+-[Ôâ—ˆ%¸Ó°z4mÄ-zHÒ¹×b3˜wxQn‹“mm4n­)4é÷™jÊšBLJS­ÑtáöÛya·Ÿ![ÄÖ'¡±KàsöÊïÉe¶w´&ôì. Þ0óªáh_Êzì¡hÎklfßZh¡Ò¹L`æ(Æãœ*-\{ƒ?sr uÚ¸N^%áq¶ÂJlÒ@iäZ%ƒ»(f ½ p=¢•0¹ëÓý •ÄcåZbVV®EM$ }õ33Wk4sÍ3Wkfæú¯~õŸ®ÿÌïÿCßõ=¿ÿýžÿè{~öï~×WÿùïüÞïêÿõoþ+ß÷_ü½_þïâw~øþÊÿüù/ÿÛ—¿ûÍ/ý›ãüƒ_ÿµ_øë?÷ë¿÷'îWÿðÛïýÑ¿öŸýGí÷ýØ~ñüÁù‘Ÿùc¿ôË_~í_~óÿûþ½ÿîwó7¾þåOþÆ×ÿú/þ­ð7ÿÙú?|ý«õñçíþ?ö£¿úo—_þŽ×â[ZÇR—(†9äݸKpP¬vÛ Sš4M$,M<ð§—ÌÐJÞ_âLÖ†JâÈÖ†ÚÜ°õúéÅKà)ïF/EMX“½Y=­S‡×0l`^òþâCßßØÔ¬I½ÏmKàÞtÿÅ)IwÞo˘7nß.‡×„`x»j`B=ßubf‹Q›¶^W^tý¾K¦9ÍY“Ãd3°I³˜v~§óÝKhE&±SBÓKœKãÀñá#Ø Áj.v¸a\££«(ú‚Ä q`Xcª2‰Å‰K!Ì/Ù§F k"ÜÃ&î”0ŽYd[ëR„T•¼Ÿ’¸”µ ÙWwI¥I,®ݬc¶Ì˜©¡Ú¨ìA®1w}Lh^ÿNxQàSœO¦üfpl&1ý¶¶¼¿ q<FaЈk¢I,…@¡¯ZÜ;ÃwjrltFXpsžüÀIE%¶¥Ðh¬[ÅpíK 6œ¾_`1ß×k0gTè…¶à¢[ܶ ÈUg&}Y´°k+g3ØpADÍXG¡™)â”T}½Ö6÷ÏAÕG ÈoŠŽpëZ2:ªÀ£Mm•Ð$fàâÃÄïº&˜ióY=e¹Ó Æ×PÚ]£s,˜xêuMK’HÚ©FÖJ']%†EÐñ@ʸ@PpÚ†ñÅ”ùÚkĵ¼B.íÐôá‹ot Øƨ]yiUà ;bó#De5á~¤xSxÃÔ Ÿ9µpã vošÄ 45)Ë6·7¡¼ðú½MmDx [1lÎØçòâÛ2„ a6ÁÌfÛw¡ÎðVN Šcº»X§T5é5àâÅMbP|8û{ œ+E&±„;‰±ñž n÷¢DÄ ¶ ã$”hy?5b—ôî´”$ÜOÀ$7Ú¸p_at¨( wÃôú%b J3*4›gï›tnÜ¡vêZ2Á¨”lk£Il•é÷ •pž.¸5¿´ŠãþC«Èx=yao![¸ö /¡*ùÊïk>{.`(¢öîRàª7¯Žö–4¦Ê;Á…¢è&±„÷!kŸÔ2…f…Í ~ùlð{N[Àíâ|Ô˜&á ™XᡶWᆮYCo\û–„ÉíqÈ$v•´Ë$Ö·ã×ÅÄ{ûV&±þíùÕº™Äþç?ý•/¿þ/¿ñ?ý2ÿ÷þÿËÿúµßóµïþÅ/¿øú—_ýÍŸÿÍ¿ðõ_úùï˯}íkßøêWé—~ù·¿Ä__~í¿ýÍ_ùÚ7¿ñÍ/ÿïŸúéoþÆ7~ûoþ?ù7~û¯ýíë×ìçþnþ‘ïùõ¯õ×~í×¾ü§~ß?ösõüÁ?ü³?üÇÿÉïøã²éÑæO¼4{è—u]úÅU@cÄÿ+h÷­^Íf©dï‹B¤í¢ÛÃÁuH·~èæ&˜¡pŠWŸ}È 6e¹zæ½uóú]Æ©8¤0¿ë¡\—ÌÈÙì1Ñ¥¼SüŠ~aY÷ÖíٙƇñD¸ÅÓ ×ÌöéJÈZæçñ„¢Û±|Þ—ÅDM6 .¯4©E ê|šu¢¨ú% srËöÏàuîNµ=j˜Ù'b˜¦gžöDZS˜V&Ãâê·—¢’d¾Wkl2IõææÉ!oø9JGÆ%CeL=·¦^&s(Îk‘k¤ñ&ÕˆÝ^uV÷þšþ|°53gY»lS-èYxJm14ái:£Ëë,M½*³úSÕ‘´8³›mm>j1æ´—â2ð¦*ï2n¼t}¤¸Ñ#H[¼TíñlIö\8åJ¬HܪdÚø\Ít3ßØÚ ?pRI´¾j86 k§û«ÈiT²ë¬µ±o'ìôñ.ÞãY§‚þ³|¡îymŠÜs—¯ÂÁÏU'MííÀ7*>úJÉéÉÇ›ñèsìÞ²Ï+†ñaî&B.ü„1ýìf8* ÖWmN"f^Lm?®~7±ëÀE¿ßílµûŠ-ùxb«ý9f]ÝóŠÕúÚsça>ø¹êäºÉÈÚIÓÉÈûJc“‘'¥°E—=-ÏÞ²Ï+¶ñaî)¦ø¡ úÀ᮳ñ¼ÛÙk±ûÚëµÇ³×ty¯ûž×¦=w¥o“Ñ·Éè‘Œ>ÒÏõÕ)Éòo^_©¦¾²«+ëfã9}Å&Œ¹¶fT§:ÕEÛâ¦ÌP†Í«|ÄXsj™!ÙZx>4æÝÎZ í⻯ˆw±ùOl]´qÖ’óZj{î›ZE5ãÚ½ÒƼ¯C«>žº¯î|Ìuï>¯ºGès¯µy‰s\tjqî:Ï»½»¯½^{<{MÜðußóÚ´q4Ïéç3£F•Öaí®ôBä©´7ªš]%T(’ÐÂ÷­k :˜/Ã`cE˜ØÁˆA0¯37Èk´ãÇ¿ÅšP“ZÁQ Ïi­6^‡m¸™³ðU’Õ/ÊV˜Fà "D0à Kðˆ%cxŸZ§­“*¾‚׬f;ðð–y9MTe€gÌ°[~ž‰‹ŒÓW ›´a9ÇJ >ÂÒ„‚­=ýŽ7ΟCª §üa6…uì‚Ž¦Žtñ°aS8”S‚vjui*x:!›}Ž>ᨡȹ·`‹™dFªr‘ä‹rF}IxÄç¾ÔŒoµ%üŠ—‚ìéh+aÁƒ^‘¢£tá0™]ÒE!2K¥,úcƒýŒ_È<ÁÔhw²‰a8y{ íÜ(JQÛ9鶛oki”òL^î$}âPCê :XlFûæ®Ar ¼¹0Àœn”íM©s#±µÃXÅO:˜V¢¹D:è&¸JxÉ’$²] ‚H!‘Þâ€ûß+ /ì£óBÁa IPN \ôÂvó™€Fs)ê¬ýp† Á…é,j#f³é¬•ôEÛ`³Á`ðàKã)ø!ñ: ÍD§Òltoo`¦èIR`õÄ5XÇÊV6l«ï3›tÃ)Tˆ†4Gþã/l‘üA¦ ¹qráa{føG¿-ˆ´‚Í´ù@‹ã¢Ní+3k*RfgGpv.Ú–l}a'ñ%ÅÌF75Û(uMið'Ñø*$Û‘ øÔ Æõ±-§—Ài)y÷¾RÒWø’EíëRe¿‚r1 nèÔKÖ`É©h7åð‹•µøÍD<ó¿pê—5!•'§ÆÍãð":<>óG÷’(7™n§ ÒÅãì7)§D3 !>y|Ž<>Ò“ÇáŒuñ8l7×ìð¸Cdêb¸xü€IîB!Ý<ÎÉ]<~ÁFCW‰D&sñ8=°n_õæñ‹ÇÜžy|•Ô›ÇSÐÅ©óøGœ:ãN±6i¦Bu4¦ã͵wJg€ºB×®Yì˜4ø™ö\J¦³+év¸Ÿ5 ë|â 0>kIºLoòkã¤u —Z5!C‘ÄÁÑ ª³ãRs‘”èôU.‘tJL$uù‰88‚©>è|è0Rb‘‹á†}0§„'À0äJÉëe€N¢›hèõœMœà8¿¦½7às;P§“§@i]wºø|Û ¶˜·$˜Íˆ›’‘fø`'­l\]>7\ýƒé¦a‡X œLéd倻o Ä.ùÊÏ’AéjhB› ×°‹íwþ]ø"ÒŸ†@ÙðÝËs¬›˜°Ä4mÑ2bر k»†qfÔ»Œ‹ráÃü¬Qµ$t{à¤k ÷"~8‹h£†/ÏH²¶ ú(ÆÑEg×Ub*sHòÛƒÛ˜>r`²”ÇA3f ©~ÄìžÇ»p8K—`†‹iÏáè‘í4I”á‹ZøuÀÂÝ å‰æAš!yj]ÔhçO _¸ë È"xAºJÀ6â´/h}­QØBjÆôO` ÚnŠZذ맄LˆH4f|Š8…à$&.¢kwÚ<¸`šcìœz³c+]\c¦‘µ^”¶¢š½çˆZ ¢”ȳUFéÏXOùÈ ¯À¾"Ü:ãFh3ÛŽ×èAâF´4Ió—$h»_Ä.R´ViȬ=ŠöÔfM›‹Õ`¤¨wN¶j)V;Qæä@NèÕ¶BŽªÚÖU¼s-Ù>±ûQÂj ™hhcž’nX€º“)ÉÂÊ ·`sÒ 4“V3“%¾Í¦É¹\ä¿$†}“? ×å"ÿ¤ó|’ÿ[Øû*] ª¼"Ðe††™´‘`É“UæH².,ØŽÞmÿÜ£ŠàÂråoƒ>™¼€·”Ùé »Ekù SO=0Ëô7i)‡ZþéH×Ù Òœ§VO@õ=“àFDÓ~¸]IœK€ŽŒÆü­ÑÕmh0ŠÙ¶ ¬4gpqî™Êòx,a¼úu»ŸöìdW°ÍR:XLÚðµŠik&,›é"†D •ÖÕiuÿêÌÚ(Õ0 ßÙ¶†.6\“z®';>ë¥X*IWú~Š":Ã\%ÛœÀXs;Æ©´í­a‰|NT\ë>µʨ˜ôŒ•LL¯WS‚–PÝéêmš›4µƒi’C‹NÊ6´"+jʤ W0×þk?©Óld«g€Í¾é3›îÝyb¢“®–/›Ç©Ót’çí+:ÑÿÎvHsPÓI1Ø ‰âdú=Æ|ZU…nÎÀÁ¬×\Ð'¨Ç$©!tIã еŽ A< ˜Øt‚w 8± .W´çÉÃÎB„æ;]Lô•Î.ÔHÆŠœ†èBÔ)Q¨ßH¹C6>¦»Ë&ëD<áµG žÝ!¾ÓØÇ10_+×L¨0aûá-elÙÂ|D»àö ¸Xëv9±‘:§‹³b®?-ùõ_1—£6ýB9ë²Ù½¸P’Ôr/~Õ˜¬/s‰zßÁÓ×.²ƒË©æÔ™ôŠW;3š—Úî«[\û=œÍ'm™‚ù‘O«WkxO½EIwô\uÊ°;ºÝNIvû·ûÂ1·ßÃÉÕ®“÷ˆqÌYáºô9s°Ç;i»è8OÇòiÇWb÷µWkg¯èò^õ=­M{êž z¬˜îDTìn‹›ˆ²Qw"‚ŒTȺMD¾øÕ‰(Y¸¹¾ý’Û½ƒ‘…‘[_9™s ¯ÿD ÓIÆëа’ÝΨ¶$»/Þ@ÝÃÁ""rND>­æ]í©ƒšDD¾j»¢p×G;¶2W_¥;Ùp ¯âcÄÅ}Áö¬rfŽcÆ;y{V8OÇòng¯Äîk¯ÖÏ^Ñ=ä½ê{Z›2öÔÍÕæÛDôm"úÿOD©çúê”9AÆZŽD³¾¦SX¶y]}‹“ܱ%Ùp%h`Iµ—ä›.c±øyÛ+ycÌD'ÿçUghʧ™!'¨ÓSÇ — ê£éÍc¾aªã³êÑ\´÷Ì7©lìtóøÝ»án¦µâ›ªuµét§gójñwßG|N݇·§Ý‹ûØlVÛ~¦Ž¾SÇQ¼ÛÙË°»ÚKµG³—ó _ò=«MG½ùœt>#¯ícÇd*Š-› ®»YR«ùØŒÖX¥Ð²>ZQLšÂÓ8Põù”ñ¡ìÏP>üI¬.$vF6+ÔóáΠ&é^³Áêa‚w!ô~Ôtp¦Ä%ygXµjÞ5(™ÉJè]ƒ5¬fLFÆWˆ…Ìyâ‘î8¥e)Ó.S —BëÁ\ÔÂA#ö«D}Ø° Äù–ñẹ׌\¼ET€/+|²rÀµAT÷k|Pˬ3:Ø8›ƒÍU‚ã@[Z®øÒaðÆDÙæÂ6ó¯é†ö(N[XêŒ ©›ÍNµéë|Œå†­à"›!&B¶åMP^ÂooT͵æÐÊÓa.àÂEÃH§™c ž; <jÉkàÕ‚EA¢ žrhùóíY3éËÕ8=kÑ>½âVN3ᥠîäDXÅk&}8âUƒC§_ýmÆ„y1Ú±ŽE[0Ç+F¨¼j fDKÑÜjðvYH"céV3»îä[WÍd<„)Q°Nlˆ!‚Š<ÎÆÛW'E)vâuЩFWó©Tºø 2ù@¬2*N¼ù&N²]ÍÍb+h`}ËSû]Ó8Q¨ÙÁ·Ü"ÊsýÄ‹A0?'„[šú Â|'mÖ-l!ò8KÃ~¬Â¨&Æ문ÙÎ4³9w9Ó Ø…(PðMÏX¡Þ€9Óì„‚'º«Íª“ÿp×OþCp4~xwÏ!Wšü¦bØqºÀ[ñOÇktžSÇÙ’öö·¯¡F=Š¢ó>kZ¦“%•!! åxSf¥ˆq7>ùEw£ ‰wP¤P¸Ñ„XDŒxaªÛ¯ÈÈj¼ðÞ%×ÝÒ1ÊÆ®- ÃæÀîFsJäFƒ+cî1SWìºæŒÈÂÏ¢'»cÿ‹†pÓÈ xdvqoäY?âŽý€rÖC”ŽV>cÖtŠƒt¤ÁôàN·¥ìŽ§DŽ4˜N¶hÄ|ò-N£;Òàšµš”뜿ïÓr¤Áõ4º¸#MÀáÚ"œñ~z0jÄͲ‚Ǻ# üÏï ÝÆÔäH³áéŽ4^ž)zAÖÊ–0|ÄÆ%ƒbP(þS#˦٠j\sQæq¤ …×pN° ½%-ÒPIâƒæ¬™M›iõº# Ìݸ‚S)ŒŸQ›ip+O^¬{}ó̇QEaRî„ sLÚiÄå®@;–TœzÁÕiN ³&ïÞWJº bzõÃq‹äMG (r:S ¼r_Ž4!uL£–’„÷pæáÔ¹·NO.Ç¥èƒËg=\>ÚG.÷ãrs[Ú\>ë“Ë7¼¹|——Ïòär… Ú\·Åãbr•àZ‘ɾåâr=†w&ߘA".ß ñø¬O7GÅÍãÞ4´KŒÇe\?lŸ%ÄVM¥Z~#G›# ŠÜ&ý7¢r+LS`/”¼ƒ:Ãcö#f÷<ŽØÅunº3ãõ íÜ`1FôiÒë³fS†¿DòQp8Úâ†L?²w±h©'ñ"iv¦TS1)°0‡Í6b²/äHs ‚iVÁ4†T ´ í¦¨… »ŽpJÈ„I‡<ˆuÂÀo7Gšh÷¶Îƒ•Œ9à`98+.ÒãÕ ‘WïI[¿Í¾ž ¶˜L‰Ü[e2ýyj¿Ç•{7ì+­3l„*7Ë©šƒ¸íeMR GÐw?„_b^‡I7†ôäî2Í‘fufç£nŽ4l+Ô"ã?¶Åcè㶭ËD ’Ž”sl~”°]B("þj·#M¤;(| #ÚBËÔî•äÞå"ÿœMÝäKå"ÿL{JPäJÚWQ•P—“•¼œv; ‘›Š–$½,Gšˆ·¼B:…Ñ‚©ö*„§æHc Ë#„T'–ºŸtÛJæào¬éHc@öGb‹T2,N»fšÍÂSwí”·•O{6ó4±x7Ó@-,ê﵊uk&,›iz¦—SØ{·í_YéHÃAmT¶5X[9f­ûÆ„… ¤Í{¡/NÔ*«Dòã*‘¾SÑ âú3ü÷‘çÞàOÊêØÚ]ƒ'S^àW¤4KÁ[,–Ä*^#!&æy„´pž…ÆÓÍÒزËaùŽáIN°5X¾ÌRÇOë<!…ÜFnÖÉq6Od•Nf9dКï3£s–’×ØW•n”/ÀxgF1!ƒü×4¸ò4ÄU<ÛCÉÌ>j„¸÷‚÷]PˆXËÂyCœ`僌¨‰ôÔD“ni&;7žScŠg&0”cwˆ…l‡HÒOaû†œÌ8E§Ã¶b‡g ×´Ã“9"«)‰¥Ø^*!<@Kü)B­‚µŒ’1ëî»ì´$‹ˆ¬Ã™Cn†i‚BôÍ)If‹ ÙRŽË%‘x´Ÿºµ‘¢1*}(Ø‚Ï5mù+0H$¦[+ô Û…èÞñÎf;_Ô¶‡Ç[ ¯f¦ÊxFU@Ú™ø¯Ÿñ€S›#6ó ÇM¬–*#fÒ SDá™ %Å~Èc&¶+Ö¦’:Qem6ò©„‚…{fòÄ0´OX ^¦_4>WGØr¸V×ò­âõ;biªuhƒ‘Ø=h¯±סðõ¡0O†yœžûïŽ]¼¾ÀØðš° MÓÄ4+ð Q¸°´‰j ïzÓƒMæË §ìßA°ƒ®¾VlÑÀ,ZaZyÀœt³.qJ5=ÄJêÜþLLÝF'‚¢ØR€Þ/¨èP“îóA¶BKœóÀë|@f¤|¤ãÒ9X'û|à°NU7v …`fŠ‰-!ªÓ‚«6ÍnÛ˜Òn‘ŒR$aÿJG¦gØ>V [ñæÝh"yk[4¶êI~¼ é øÉU™wkT0Up±˜ŒW#Òß>>Øփͬ·¤ÒªWœ Ù9i៙P?TÒ.B£bÍUÏ‘ÿÎvЪ[£ùË9"Ã+\!k`˜2Fâ*8YvZi àµÎ² °¹Ñ3£¸CðÑüÃn@ÜQ᪦"'ægœRE/ºBòn i?šàÂ#VYèPG [+‰ð ýPU&iœN1èyÁåîÀBŠé¥¡mVËïØ©m“†1ÔHýÙ”ÕÄ@&ñc&¼ý{Žœ-¸#¥SçN%¬…漏¨ª ãhU#„ã÷Ø0SòVòÔ¨ u€»KêRî¾½y‰Ÿe[™[b2¿à}´Â„ìÿž˜=3D:ÖM±Ú©T”ÑEŠçð†°pÏÃ[‡ì>¼òÃ[—Ìo=·}xë¹Ã?¼8‡7B~xë)݇7æ¥|Ì°Ïëð†Ìa÷áÍásxÛ%vô›«ûð†t‡ÏÃ[ÃmÅuxk¸}¿oöÛøá­ñ8¼!ïäóðÖF=‡7ôwÞ6¼o^¢Ãº»oƒÏ>„¨}×á­ã°î‡7çðð:¼q×á />®ÃB0?oÈ-yÞ ÊüðÆ¿Ïá ÞàÝ~Þ·ïÚ·ñRä:¼õ‡·®{ÅëðÖxàÞ¨ð:¼uù¼ö{Î÷ámÑï9¼õR?;¼K:¼u=n܇7¼omö‡7>{¹o öÛ?¼òÞއ7-Õóðïm…:Ï€×%ÐÚ×$¶@ïf1ÑÛQˆR,{Ó€º’3xí ƒDökr4øïZ/œ|RAã陪™Ô¸´‰ÜŠ‰ìX×瑶š«yz6øÏÈs`S{wÎ÷Ö%¦¢ íó$üî¯ó$bä]çIs>?çÉ µÿj;çÉ eàœ'Ÿï>O"†Ü}žDT¸sžDl½sžä£…sž\c>çI8ž?Γp¡¿Ï“³ÞXAð¸Çyq¯ó$âg^çI×yÒ ü<‰¯¯óä„#ýoLyÏìß »~žœÊTuŸ'*ïœ'•û<9‘HaïÓ>™½ã5ÀužD ¿û< T<Ï“(¹Î“SÒû< øyž´’ë<uËÄ5ê%Þ~g&[ºBý©?ûòçvÀfÝø0¸BÊ ¢@Š«6]·á–e‚žÙô¤¬‡Pþtßßu‡/zeàe¢šiŸŠØÜGÛ0#ñÒn³k@mQžH=S¡¶ÄÐ"vß¡3"|¿@gJöV¼½êáoÈg2ƒy2é„ÀÉÀ¬¿AF8¦ëá©@@'’؉v%ñm¤cžÍP6ßh‚{¥ûĤøñén9%ï»$+.4 ølæ*@DH Cy7;ñhT|Óa ä°j”«÷bzŽÖ3sIåèúVì h ˜Æwta k»a"•„¶k´R_ÝÕ…Óõ“mt2¼£C2Ÿj¤€ç)eÉR¦íÔ +—!É”õ×â+'¥ñœ<à!Šnf^3\Oð½ÍPÖH9L&D¢…¤@³Ù+EÌ]Ê­»K:¡jcu‡»`Æ$£µEÀÂf´@Ç jC1@ïÒßÖ˜áF» ¦ð GGh;Z7¹&kbCKÉY^#ròÉžì¨@hü†ŽûgÆúJöLêâZ‚i—Éç´Žî]öäEàÈù`À9A­þ»AAdE¾Tö8p(¤¥O”’ÿnÎF{AÓžt¾aÚÜ0tÆRŽ Ïg `ÐYÎcãà“(FäDøtŠÀµƒY)Mƒ=ƒU;MK)Ø{6ïHN1ŸvÏOn8>« 8(‚[(zq7)[›œ25&‚¼ìVS›Žz«]|ã~ËôY'A3¡ùï)p¶d„†(#ÅÂ<5R½)ãÀN»Ä(¡H}åõ¦ Fµ½)c–'e <)ƒF³öe/›RG,HxL@Ìûö¡„Ù£8è±1ýÇÆ8¯P´rTænd…•–½$ßP9Ýù-¸3|o–WO ¦%>FÁAè]ñ1±¦Z6ÆüJ‡ eàVE¼P@ÌÁ}Z†:b¹6 yÐfj‹ÿŽÃ€ZÏiƒpͳET½¾ç×i j¦ ¯ãrF&×ï†]zñb[³4 !-{áAÑd+ÃññÁ!xQ7Ç 9‰³⚌@.±°' ¿ÂyY_wùèjDa+³)¬5ý¥€ÜH•‘0”QÄ9n–{ÜJ‚kÙ ±GF2Ღ4¹rC± ráÂ0²…<ãÙ>lÙ"pËÌ]ƒb訑ò`2ã´õã²Å LœD=xxB[º¤È«8%zfŸ…= ÐÉ~—žwupL‘1!°PåÁV¨ƒkXÍø›a?ô®ì±ÿ›a#Msÿ(Ô Fÿ®ÝÌm€ïîÁ#ÃmÜb“Á({ºÑdþúB ÊÃGèBÓÒ';…$.Ü|âh–­¿hû㧱Åø™óâÆX¥•øÏð'ìbÈ »I­ËR(ÝþRqUŽâÚ[a†h£'Î)ÇÆ+®þ‰-¾ÃXÓåŽ «Yɤ±0Ÿpáî?c5/:Žpœ%‘Ýu6­ÌzÚ!PAï\wçïUŠIÕ†I¨â–•uElÒ‚Ñ9»²Ì's\wIkµýoFÌS@ÿ‘t½ti†öSœK;a ´É ·,‘pd¸]¸‡|¡ŒÔtKQ²dƒÔ>ÙŽ^ <ˆ|€²¦Òê.0ñ:Gít"FDr¤ñzÞqµyýâ°Q­Åˆ}Bx„eI M‹°Ô;â•ÞíoˆôÑÚ¡¿NêÇõ —ÞYFÿ w=(>5ôxqëÞz§—¸ÞYfÞ"¹<8‡^/½sÍtÜzç&z'ÞD™¹xI›ø¾„ÁÞÍ8”ø왑óÉ~[ ʾ<(ö Ùò»åD  Z¤ AfpHô>8›¼'æ=ÚEÙ¶°Ü|—9Œ¾Úè½d©¸ÂKÕB«"(3^“‚íÌhG?5²Ì„»ƒ[Ð%í)YªS·)þSßÙIM¦¨U2¸ÄTŸ*¯Ð¨Ùp4[Ý)ašst—·¢™ªBÑnµnuåúô‚†êAÀ†‰ªUˆ°˜ó`xuñ " PöÑ>U9‹2(°ÖZŽ¿ ÏÊ¥ ŒŒKåšî[ÕS8vÖ„˜Ìf$=œy|/5ï‹Êù¹”Û`–ª§š˜f4Ltd§AFëSyg¾¿·ç•§ýNY¿ç±ZÆœþ([|ñPeT#_”©õv@̱Ìd¼‚eZQÛÖ“­t®–yÀjäsFìJPÖAâ[GÆÀ•6¡¥Ê÷%mÂÝð/ÇSðººC[ óÝg=½)‚œ#Ð NÐ:Ú™õtïh t+0–ù:"~8LbÚ>Õ‘ÝUš·&Kðhûå蜩à“ñþ»Æ›åZîoéÚÐéß’·NOwš~éüð¦¡\²ßÉ9Ãþ8 ?Á£ð r§Ið{›GIG¬·Q/LYã)8ûèÂÔÚgZ?›_ë7¦úSý‰©~c ž™˜jÚ3I¸õý5n9ó…©iz¿a΢ñÂ.MHYú½‡ÌÖF²¿²d´S \1â…+$‡¸©Ê ;¸úÉý´* Œ]LæuÈÚ`³%pEðŽº’ƒ ˜³Ñô@™uö!GƒýîëµV)pÿî:ûáhðž[1ÙGÑësÄ}4_òe(ix¾¨©½;ç?^CQž¶ùhð&t›pï{™pñû0õÑΠ¶c>ê`c>ê=?ÌGK™˜8u›Fl—ùhàpvÌGkÌÇ|Lj‡ùn ·ùN+]á<Òz ·ù—`—ùÈÀc>²7áëË|ÔGzšàÖq™»n>–©è2uew0ó°r›nö˜|2{‡ßÉe>b€ÅË|T<ÍGô€9æ#z¥\æ#ÀOóÑ.Ùæ# „nÃ-.¬åyGËÄòxɲêá,…ȧ8S(ji-ÙSý&6õYA³È§ï/žåþó’óìbw³ž’üÛ>ö|JppË–ÕF1ÂéÝëíÎo]‚kekÇ’#^r}ÅŒš’Ï{ÿl„zê–c-r¢£®ðy Ñå´iŽ­åæ“Ì=xHi7"|ãBCÉús$¿Q^PÕïб½A¹ZcèiÁ"ÒÚǹ ï?í‹=᎔>B{ÝA¿L<Ñز^áOõOó ñ“¢Ž¤º äÓô@ ¤]]€U½‘‘; ¤o$­àý EÖHŸ\:ðÃÿ;2 ý”$š¤¿mxãX©šPŠ AG«[ÓGrÚ‘i‰‡©S&ÈiO¬-÷:œÚ¤µú>ÈE­$\x㓺™è«D9h´`îÓM/uøMéE°½<£Ç®Ùs×Ð:=VÕ{$=ÄN6O¼´[ ‰XNò {3æi&ɧW]5Èr³…"Wæ†á[.ÿÓS£r tö‡·0¢&WœA`ÂZfšL™ð6“@éÑÕhþs—OŒ‰°Ÿ@¬±h`œÕ%¥ ÷âDÍ}à€…T\MŒ"£(KœƒšØ}Wˆê…4°þœî1¨Ùò±¸$%óŠÃ°&9lsž eºrTCfírÙ^,>¾ËöÂ_iHçŸ.ÚÑNÈ0ø¥Évïã÷]By^×æúkKõš»¿è5g%Xü{økY@5+øÀ»A"\XâÅtp‰ Üm^ÃWDñÃÀè@áK¢¬î ^ðqÚþÝ”D0þ¤rƒ¿|lï‚}ÓPڤ˽R¤GË.2¦6¡ÐAÞ–L5×ø¶"üà‘oü2üP'á´É›CO…€ >.ÅSYêAŽŸ)!¿0™¼ëà/qÀ¹^‚ÀøŽEøë ˆPÏœ:Ãe)Ä»ïtVgŽ‘íf]wßóJHŸ–ï¹Ë[àà窃¤ÈýÑNö,»¯47ÙxâØddcÆÕë|Ì ~÷ϹÇîKëøA>’'OÇóiÇ×âôåëuÆãkºÇ¼×}ÏkÓÆž»Gcý6}›ŒþÈè#ý02{]%ÃãçÖ¨:Á×´kG`ªuë=hÌðV;Mß3•¸fZ©=Á-Q½C‹D.­«Í4m‰n‹ù`uJÊî:öèùj'”üì+ “Ä{úªž{§µôaÌ-ïY4ß·=²ÏÎ/ù×…ÃSÇñ|Úñµ8}µ2Mkðñøšî1ïußóÊ œuÏý[ÐÏg4vb"ƒAèÇ)»ðþ¡ø~ƒŒºÉe·G@ŒÏn9óÓË.$E"Ïæ]¸_(p:Èt9‚… 2’o—‡"=Tp“:Ì3é.ÕÀ ›Fûdz8¦+ ^àAö”w(Þ\`Š ª~• ÌôeåX*SŒøàùXÏñ™BˆøH¼j‡ë¡èž¡^­ŸÞÇU%…¾½ŒxÅP©™v>'™Ëጕê%"¶È'ÛŸƒ¾@É0æ ”r²5±7ß,Z­Ír{ ¯w¼­gTÃ’¦À0©6)Ü0ìw9)‹R‚q¨+ˆñ”Û4 ì®âI+Âð kíð'ñR¼kУ7Y˜OSÙ TyôÁ§µX’N«Ò\0B'ŸåU%lðø›©Z ¸D»84Z\L{x&/DÎß‘²P DþÝ= &.Yå10æYE1‚9l-è®±N:rïM0Ž«?œ¢\vH\šb6fØس'—»†r¾‘!4¸¢õHX×ÇR8­/ÞU¾ûÍbó2åGB*MǼwŸŽr]5øsU”j†QA:1ðÓ`h§¡©\ùjSQ¿¸ðEíVÑäsÜ;o²Eï$Ý/Tô*aUR\g˜`ÆÞe¯WôÔh.Õ’iY9Ñàœ¬•Ç ·Üš?él#‘3ß,þ.a%`°Éd[ei°VÓ^F61ÌÉn—(‰œ³7¹om zA{ÆݪÍ#Ú¥3\2Ê£ÍnSÝ%E¾©ä¢Äð¥\1ÍC@g[ö·×Jtxv /¡»ºM OÈsl"ªé†“0Ú%|4‚Ó–‰„íuŒM·ìÃDIJïTFÛs +󭃢‰/ü&b# “i¼YäX“=1׸©‚–íe¾ábèŸCeEŽ!ZŹ(Q}‰y Øg;¶«ö‘è_ ? ,@r¶¶KÔVè’%âœ×ñlL_ž‘í% {Qph¤å”ø"#')P(ÓCb9IÓiÉAEþŒ@ÝãïĈj†£¤Vä U¬U¦l¹à¦´WÉP¿ÈGˇ|o„ôRV¿ê\.JbÎ>5·jL£¾Ij¶QY_ùœlX¼ÿJ˜Q¹©`Üt0)®“°„Ö@–CÌ–°^I‰%”öwÿŽdHŸA   X¶(-aÊô•Q˜I)6œm8%h‡ V—^:!q¶î=LsÇWìaÒÜ “eZpÓ¢ðí`§øµ¥> –Í—ñ9h ¨€°-Ìj* aRV¡ ´Ìà§$ójcÁCíIýbƒýŒÓ'­ð)¡ÑnBà­„`ž<>?ðøüÀãó3Ÿx|~àñùÇñ0ôÁã|€}xè›Ç•aÉy|Cdjœë/? x|~àñùÇçg<>?ðøüÀãó[ÔÃÍã#[æ“ÇsxòxOGø†'çüàñ\Ÿ<¾áÍã»D<žË“ÇqFyò8ö¸›Ç¡SÜ<žãç<…ÿÉãTL.‡wóxÎy<ç'£Í‹ÇsúÈã9^<žã“Çazò8Í>w…'Øyü” ÙenGûOÏñÁã9>xϧž<žÓ“ÇÑñÍãpºy|çjg:…±éOÓÒ”IeLS”«?úž«Q‰vËSÁLþHUaÀØY@ªZV=¾t¤¦éÎ1os,Nê)ÓMS!ßò°¬.©m‘”•b÷I§D‰™ºâ¥m°šxSJ#L)iöÁœš›!·:ƒªÐM Á¸5­Ü®éœMsóùEek¯~v 8y6#G"1ù/>÷W°-À¼%Á”±Ä’‘ÒÌ줕ëL>F#$%;*ÀjàïÀX¥¢kóƒL“/NyÅg&´š)³¶ß  óÓæÀž†@³¾?³±<ƺó =Î ÆŒü.ˆkB4ÊÎÇ{a{Ý}(—>ØAK‚¬#8騽¨ÐW´ &o"å\Ù&0jxâòl›IôŸ? ‚"¡Ùи½Hà¨Ö™b‘¹PÝóØb·(£ï©Ñì¨>ñ9—Úô…P†/ªÞ» R¥tÒ˜æ±ä¦Ù„êð.ŠÙwÆTfóSgèD]ÌÂ@jLÌ…d_TÝDœ‚ÀÌæë‹h É×÷lAŒ€vá” Ý _yëì’RuÁPéÂA3Ê>§ÃH¤ RÃSY³v”ì+šõmöõµå Ï×VYpªÓz2Tµƒk{E¸uöÐ&ÛΩQ%nH{œá w—¦€9X+šc›"DcOÕoÊ81™Óß5:ÙZºŒ¥ÕN”9m 8¡4óX©¶uEïÜ–ìpm†E«Ñe¢ÁùŽfà t'³9½D9¼”äÓ oN™›æ”b µ‹ü«bž]ä#y¹È¿"(ˆ&T¸¯¢*¡J5 × ›fXó°h°Ø-y²ÊI–í°;z7ÿ[’†U 2›¿c€2Ýäjv:ènÑZ>H#áÎnhÎZŸiÊ¡–Òåè¸`ˆ¢P´z½x CÒ2*C1gÑAw¦ø ÓP¥#ϧ—ÂûX:­0vV¿£ªßj@…1gQRÜ1À¼£w–|ùDpwÑendstream endobj 6 0 obj 22572 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:03-07:00 2013-08-20T08:42:03-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000022876 00000 n 0000024446 00000 n 0000022817 00000 n 0000022678 00000 n 0000000015 00000 n 0000022657 00000 n 0000022940 00000 n 0000022981 00000 n 0000023010 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [(6\007D\367d.\230O'E_n;\233Fs)(6\007D\367d.\230O'E_n;\233Fs)] >> startxref 24616 %%EOF ast-8.3.0/sun211_figures/cmpframe.pdf0000664000175000017500000001641013004147321014273 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœí[}pTU–G‰IètŠ(#D˜Ñf·Ä™%I¿÷ú}Z ‰(+vaü‚„¤‰øALBV‡’Vò¡ãnÕıftF2!îè¸ vz’ŒU™VL$Í&›4q˜•Ð¶©n»é¾{ß{÷ÞׯíìÚl¦ìÆ~œÃ}çœß9ç~{}ÁDÐ&Jþ¢çÖƒù1ÁôÜÏ Tdz,g1=g 9J(°p&š!—3Õhrhød¾@‚O‘WZÐFýwDo50,_@³"áThÈá8špx¥KdiÝj ‰RdUŽ$·  t,“RùD+¢·ˆeˆ#ÛlGŒÈÄX‘Ö­†gÿÁ@ËnaYF+X¸Aq æˆVq‹…·¨¯Ò¬Âg -h44 •X‰pª  ß ù¸wYX&¦‘V(qN^M4Ç*c‘+ëbLX)¦eªa˜e ÓÉ;’‰i¤TqŠhÚ óüïyeúÇï¤sÐ6ÃãºNE³jZq4ƒ:á´ò¤)µ3ñ´¨£XZq¢a§²èÐ(Q½…_aPþc‘„V•*ÀŽ(2JÏ©Ö8Œ $Rxå‰tbJ@fa”€ Ç KÄ$R©u(JD.äE¹GÖhžá•'eQû*­‚ø$A‚’BCkNÇ‘­T'© lj$4RºÕ€9Ë"@˜#Š‚*\)¢x •ˆÜjÀV!4™_@¨ˆ8Dc…ªC¾wr†Üq^0H…ÒRmW¥cF5f@pŠ‚jòŽÆÙf(1m‡|ûE6N–…8ò¢vƒÇ *Z±UÐ!j/¥$U âTk Mô¢·'A/â+1EÓ¶PÖKÁÎ ±X¨Ò“k4KÉ-%F¤…S"%Q¨g#z«AU(˜#òhnD4'„ÃH¼$¨D¢ap‘¸2½ŸAMkšAî.‘G IyªBiZTçe‘WÆ2DË#¯Žü¤«v,ÓH‡2F!‡žHeÕ'Òè­bnAìFp(àþßòeG\¾–r¾`GŸbrò‰#ñ(‰4âL@MÐjNŸ+È_Dñ(67`uþL€ ÏÒ4«Ï”ã$Ž¤H“(°BÓ‰¹‚²˜H@INt^@¬À-°•XB5Wà`«,¹ó¡åÅ t%V^€ß·Î`^·Þ´ãźg æØÌ`~j¥ æûYc¢ æûKiUf0¯5¯Y³’ÜsÙ åÌkj«ëj¶ÿ ¾³j•aÝý¦‡ª³~ÓTlúÓªþù—M[š>{¼mO—1£?ýjQߢa¤A8ðØÖƒ³Áh¸Cn[xº>èmw>uËÀÔ?°f5w—åÜ20]‘ŸŸwgGGû‰MYEÛ ïÚV°$«¥ýÄæ‚×+=YÓõáp¹«,¶”[¨Ü]/sÏê˜ê>žõÁÝ}·Ý²¨uÁÌ–[·ÿv^ašáu¦Geðª$y™$É`’9€— q©àçþ™Á6ªû™=oÅz­À:úœ f«×=À¿8ʇþ‚U§¼ofùv—ÇÜÇ}»#‘FO¯Oþ É¿žîXìŽök¦k¯Íàš͵\‹Ä k²Xd@|2@¼ bSÄ Ðï×ßPžs)?‘OŠë³#ÑHdwÌYïÛU±«7ê‡_狼t†ía»ÃÞ…Cï-o 7Øk­`C88­íEƒ}®†•!÷¥ Ýiö<®\Açã_Îüº8í´ &‘!Ab•íPÒ ‰LÊAq’ž|Âèo>0ó´qYMµy 9÷rö_Mv2ŸhCCÃsËå5"_gšû¯­vÉŸ~»°Ä@t÷µF°á¯»å_,þužièî—|ÊuþÆy&"u£›CÅJr§ã“u:ž–áÈúö!¢œÃÿœþ‹ÈF¦9œ8@âÇ?dŽ5ùV‹î._kù*ä/ vMÙnª›q½Êäh»a^±VDÖJ&ŽãgµVT¬•R±VÄ ÕTX°mqæ§ióÒ›ÎTN·~4Ý9q¦êçæ‚'–6¤ý°¾±) ÙÑ!¿ß§t)—qµquúM o_Ø6¼®éü×iÝ{rV…„ s6lðO•+5šzŒ¿ÙCgeWìíß;ôìcóL7bxp+@¢Á3Âlø`³”ÃßÁéuËmËÌ z¨ð·oR9uË4FwŒø¿˜Ù>QÏ„£Ò½3T5ÔüÉͧ®>?X¶±bE®õܹ`åá•ë·á|œ/ýCvàÏTQKۆϲæåÜ@âG‘ø ,3kü¨ÔãGáøí{$ûÂŒýÍ·7 ÔËŸŸ¤_5Õ¥Þ¹¸ê­¡«¾å¯`Ô•Ç­ËÝ.p™²8€€#îXÔ+k½W¼;z†Ç­[6>ճؘG=iô¼’9ïŒBÂC€ÅıòŠ¦å7QHê`I…D†€?ýëÍçûM¥ ò½ùûœf«Û;pšmë°:hË£·Óì°*c·òÏŸºð>÷bfö®=sîhÛâjj4®ÎŽ4.»Á/ã8ŒV5G¡0ë#û+n:¿¯iyÿ”á/yÏ=yþ¤!»;®ÏIðxe©%PÉÐJ)x’„ÑRÙöØ:é¦gr+Ò{º^êéòÚ‡Çc½«Ý½Ý5nû'»CVW}püèê±èÑ]K£ ²öÊi·£Î5V;]稽²txdjŸgz§_¦zÃew•ë£F·¯1J~>ŸŸÈ’CPjœ˜ Ö)8–í›Û™ ¬q`a¦•epû±=y¦—M#3ïŽÙwW†C»Ó¡åûw, …º&în€“t´œò7ùËàípybõ>8Æ–F‚Æ '6zm_Ø]¥10 \¾Fà*AئŸ¶‚ s¾]vìt¹»iAµ}4ZSS×Ú³8÷‘ø,æµ>ËÈkP‹%Yó©÷Y¼¶:ùØM›§÷=6øÐýOf´®ÿZ÷ë‚ùÓº#ûËÜÆe3ƒW¢.Ø=®Þß—)vˆ3BÀå‘'mê–A8»‡£v/p;bûåo‡78]_Þ·¿cÊl=S~ËÌÞOïýôÒ¡ñåi3Ÿ¯ü¬{ßkQ]ûÉ•C9Ïü§‘ÿ÷ £oßäääà¹gþþ©º›~'§»³/š2…ƒž’®z[IW°åI)àp\Šy=ÎzŸû½ÃBOÏèØx–ñáW>dÚÙ5YÆ‹·Æ­Ý,(áŠT Øãéd½EÉAy=úí{ ÉÁþÂM 3ï]ˆ|r¦¶ÝÓÛÙU~¯=yü>_‰pó—xBžÐŠ†<ºe¦H‚&°Â,[M·Ô‚†ÓíýWq•zµ¥é'ƒ…ù‡zÞõÓÿ{¾•{]­ÎkmoÛ²Z—œsØ•õæTËù¯´6îÍï¾…M¤™=·k“Ü7¨çÙœ¤^—ƒû†VîaN5áÐ’²ÿTJ&èœpÔ #ÍPè®C£ÛˆÃ£Ý¸ºMÕ®c°éX‡ŽÑß2Òìæô£¿¶…cW CùW ÃRø"o%”ÂpÆÄ•ÂPÆèKasº^„=ŽÑWùp¬ˆé(šqàP¼I ”š{øDp˜CLõà° £¯ó+±&I¥ï9¢‰³Ë%ÎJ„Cf%òV¬ÄP‰³Ë&›•æòÀ ½›Žpi,¯Dz‰àXFŽ¥ôàMÀa6 KÀ¦c8li!êÁ%àHȘ¸1†åÔÔÒÆÄá,äÀ ½¥qHƨҴ1†eZÆgÌœì†ØÓœ…€Ã™†bÅ ÈtMLk£µPóA“€h ‡942 I`%d:Òi-c´ÈJ"A#!cD11c0GËm-BÆJé=‘¯eŒ(%˘99ÕcO‹RbÆHŒ>c$‹>c0­eŒÖBÍM‚JcZƈ‚>cDNŸ1˜Ö2Fkìô£éÐÑòÿÒA‰òAÚ¬g4B*Õ 1îrÏÒ³–·o):ßTœÉ–NýhíÈ™¢×.®®®©Û~ùÓ›Š‚ÛtZG§£‘ŽÊ†ÐWe¶³öKØ¥ápL®v'pÅ@98ÉÙŽG¾þ˜¨ }é*õØ5µ¡‰•þкH鄹¶¡ûW¾ƒ‘ ó–’Š[Ù»*Vå–´Q/è.¦ñqW¨åX‹l2Àê-—Ô®P“k.ín[ú¢á÷Lö6šf gÞÍÙuÆ{í¹» _u¦ï•/6-H,ª/rÕ®s®Ö®ë}«|´-æ¬ ÃÀ Ü1—º«ŽrÅbEOE_¶íŠ;ê®±O¼äŽ‡?uãeÇÇ˺OWµ|A¨h®[•K0Þ·‡*Ͻk¨æýËƷÈd¼|Þœ øw÷ÌD° º §Ëlø‹R8I鎖×é–¤;®ý¼õ`nwü8pc£ÛŠ/¯èS±îèüó×W‹úrj…£}}ï¿Ç/_Œò9úAL>VqW=ceÑŽ¡f÷TG—ñή[[ßê¨:Wž»±uqÑãíq¡øcT^’S6YIè;yŽÊÍšˆ×áAªrýqkçÄIª|‘l® qG©"ÅÍ¿ëú,õQÃÿß÷­endstream endobj 6 0 obj 5036 endobj 4 0 obj <> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:00-07:00 2013-08-20T08:42:00-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000005339 00000 n 0000006909 00000 n 0000005280 00000 n 0000005141 00000 n 0000000015 00000 n 0000005121 00000 n 0000005403 00000 n 0000005444 00000 n 0000005473 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<1D7B26B1FD027103DBD147059559EB59><1D7B26B1FD027103DBD147059559EB59>] >> startxref 7079 %%EOF ast-8.3.0/sun211_figures/frontc.pdf0000664000175000017500000016043513004147321014003 00000000000000%PDF-1.5 %µí®û 3 0 obj << /Length 4 0 R /Filter /FlateDecode >> stream xœ+ä T(ä2P01³P0¶´PÐ1ŠRÂò¸ ¹ô Ò‹ô+L\ò¹ž × endstream endobj 4 0 obj 52 endobj 2 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x5 5 0 R >> >> endobj 6 0 obj << /Type /Page /Parent 1 0 R /MediaBox [ 0 0 398.7 468 ] /Contents 3 0 R /Group << /Type /Group /S /Transparency /I true /CS /DeviceRGB >> /Resources 2 0 R >> endobj 5 0 obj << /Length 8 0 R /Filter /FlateDecode /Type /XObject /Subtype /Form /BBox [ 0 0 399 468 ] /Resources 7 0 R >> stream xœ+ä T(ä2P01³P0¶´Ð3³´TÐqŠRÂò¸ ¹@¢æ  5@ZϘšY˜+$çré'(¤+èWX*¸äs!y^ endstream endobj 8 0 obj 78 endobj 7 0 obj << /ExtGState << /a0 << /CA 1 /ca 1 >> >> /XObject << /x9 9 0 R >> >> endobj 9 0 obj << /Length 10 0 R /Filter /FlateDecode /Type /XObject /Subtype /Image /Width 443 /Height 520 /ColorSpace /DeviceRGB /Interpolate true /BitsPerComponent 8 >> stream xœì]xTEÛ¥7é ˆ€¨TEQÔDAEª ¨(lØEEDl€‚…¢€¨té%!„PC'ôPBÐÂûŸ“7›Í–»»wæîúïyòð„ìîÌÝ{gÞ9o‰ Œ‘;·dË–é§bÅô—n¼ÑõÍß|#{öð—‹¥xq÷Ÿ²Y¯Áv„à%EAzYgò¥þý¥V-9uŠ¿¯Y#µk«½0·× Pt4DA¡“sÀ¹é&INNÿïÈ‘Ò¥‹Ú Ëz DAöÂŒÀ4HªV•¤¤Œ—^yEFR{a.×AD`;| L0ÉÊ•eß¾L/A7Ï™3ÀY´¨DEù˜¨|y¾Ííûñ{‘"é/áç—œ/¯X±Œñ;4pãüˆ1¸w})\8“ÑÕyjŒéö’ ”«¯ÎxÉÙ†9mZÆ€.W~íµR¨PÆK{÷ú¸?DAèËã>œâ¢}{×OÝr‹DGgü¿—,éC&`´#Ü¿òÄ1~)U*ã%‡ÀÄ_òæÍ C9^Â/Íùz¼\ÃÇgücB:>ÑçxΗ´v-?8gŽë%mØÀy—.͸r|ÊÀöí|ÛÔ©éÿ}í5þDAáï ³BYµJ®»N† ñ1ŽO™à2‘óûͼ”u|giF;Çw9âñš%žË%9ÿ×ñû /È—_ºÛîÝ™>~î,í#ˆ ‚0…'yô(_Ú¶¿ÇÄPáMHð6ΊÒÆÌDÎï7óh'þîv@üâb1p C`:cº„T9´r3³tiÙ¸Ñ÷ÛÜþ7‚"G˜ô’C¾ã†_È‹h†a¦¤¸ C9 L“ð2‘‡Ì*îŒx*ç—^]ºuó8~D`FÁæã0Û¶•=Òw6÷Iš‹¤dI4£9>îò~üî ¿€ø9^r\ƒ‹VÛ½»c^}uÆÔ'Òø` Η´l?¸d‰ë û÷Ë5×Ðïã¸rgŽ˜DðßCµjf_:yRÊ•“M›ø{tt†ËÛðzûô¹àm‡²Ëû ã¡Ã¡ìü’ó5@vÖ.*/_Áû7r™—·r¥û¿;‹;çA E]ឮܯ‹Œ ‚þHN–Ë—ülXS¬°¾ø"ˆ ìÖ2'¬/>‚";„NŠ Îê= ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ ‚"ˆ@-=žÿÿ\ÀС²l™ÇWSSå‹/dòd¤ ë†IT5Yÿ£ÖIÇŽ•¥KµÎúXr£,ì(ɉ™þøòËrá‚M°a´û"2cÓ&IJÒ1Q±b6wÚ[°@ŠÑ=é´iR¾¼ìÞíæ¥}û䡇¤~}Ù¿_÷UYˆ}1²ðAÙ™G¶å•EÍå´–µä@·nòÙgZg },ÿP–—“ãÙeÁuÝG.ž§Ø©QÃîË _-¥KˤIv_‡Æ—2e$>^í,«VÙ ¬œ1¾\sÄÄØ0u¯^rç®ç;X%VBÏžrù² —<Ο‘è×%¾ˆË!‹o“Mc칌”Ží™:Äqz·Äµ—meON™RR†¼a÷ h7Þ(ï½'/Ú})ÿâ—_(3ׯW5>¤eÙ²­j|Ÿ˜=›Òiùr{f¿r…›úÅ3þÛ£i§7$$.“ù÷IRY[Lbß“ó'í¼˜Å‹åî»í¼€ÐǦß$*gÚ¹VJæ()çì¾ ÿ‘œ,Í›Ë=÷„.öÛo”™»vY?rT¥å¼yÖlý%¥JI\œm¤¤dþþ»œ>-­[K½z!g™ñ‰+©÷™,)C]/º†ìžf÷¥áÀ)Q‚¦à‘’B@Õª²5 ØÝo½%÷ßÏ« öš.Aݯ½V¶o·gvg\¸ íÚñ~îÛÇÿ¦¦Ò†ép… vÇÊ›åx‰ýŸX’ùµ‘êö\•à åûi#°ö a;æãmW.˲÷d]AÙžWb^•Ëçµ\\Ð0"ŽfÌ°û:Òd&Ní-äÒ¥À±Ñt¹re¨Ø-!ŸìÜ9¥àÇm4]îÜIn9-|¸7J¥JLäÉŠ„Òïuë´_“l] Ó+RTÆ5Óáæ@‰‹£³2‚¬xôQY¸ÐïO­ùB6–„¼ý^(é»w3&œä¼ÝÄøÌ>}þy ŸµËtyð T©"#FØ0µ p¸Cn{Éyœ:•—šœ¬ñšÜáðV™[ƒÆÿ %%ô:fpü¸äÍ”6ôŸÄÞ½Œõ Ø›³¦·$ù%®¿¥—¥§OKÓ¦´za%Ø‹cÇóý÷~Ðe·ëÎ;™Vc/°D?þ˜ÜríZïùă¶+†ðô1™Õ(ÍOz‡œò¤€‡ À07l°û"B X]݃ôÐ]‘åïÐ%´¬˜¬þÕš«R—o¼!·Ü"{öØ|%Û¶ÑJðÛo¾ßi/@ÈëÕ“W_µù2._–§ž¢Ü>zÔ÷›!Z7zUû‹)2ë)Ù•SVV¤ùºgWèž ô8€uX¡‚5y(—Ïɲ§åPNÙ^BöÚ”+gýú‘Tû$*ªåºxqÛò Mâ™gh߶7œ5%EZµ’FèÖ1 ƒÃÿõ—ÊËÊŒµŸÉÖ¼²©ˆlýYߤªCÇ­­øÿ-æεØvñS9Z\Žæ… $Ån;’€Ú•*Eg½ÀŽ.[–¹*¡‰#hnµ×ê{ò$)îcù]DkÍúô7mRsYNH\ +JËÖÜûµ­ÿ°"‘EÎhÓÆRÊ YZd³ì“(h%¹dÅ«L• M,XÀ e»ÛwÈz£Ì´k¦y³gËu×Ùœ>³gԬɒƒ}÷qã…«.sáø~Ù|$g—%Å4û #€PÕ­k÷E„ öíc–„•É=DºdüoùP‰Ï/k KB¨šAÖ­£ËõG½¥Y³¢Kyøa~7h£ÐIµaëVž&öš @!±ƒ¬Ê¥ìÔú µ+²ä5Ù›S’ŠJÊÃV2رÃæR«! Ü=.ÀþÊÌ”.ž—…måp™‡œ>`é\a˺´ó.]¢W÷£<¾aóf¹é&º«ô¬²Z5Æ-Ûˆøx+‚¿ÜÛo¾AŠ¢ÝÚÌþÙXB¶ç“ÍÃDΈT™cŸ¡ܽüùAj*3‚õT#9¶Ub*Ëþœ²èíPÌFÓ¾ùfùôS;¯²J÷æè•%JÈ?hº’”Ú-õ»˜±v-k§L™bÉ`ÐæfHÂ!R´hpŒéâ™ß’!C³“KŽש"·Xp¡¡‰;ï ‰Ü.Ûa¹»Ç'Ö“]ùdÑÕ²m¡ÖyÍàÈ. mÎ- BJ8——4*âV¨ 5Xý駙ˆdc!DÜ܇ٳ­ïóÏY ×A ²e t uSeiAÙPXvg­á£Þµd,vs„-l¹—ÏJ\cÐsZËåË 0¼±¯½f'ž4)ÃÏrú4ŸÑÈáÃú.Ú«½nñ˜rÁ™3-²`ÁŒ¨Ûõë¥P!ÿ‡¸tAf5ãº]óŒ\ ±u«Ð5Ìç,œOkscøÖÁ@òäáùäå'wnZ¶¤=ê÷ßùxB³¡Øþý¬¹j×µí_ ë‹ÊjœÔöÕ¿u‹sç¤Ayþy;ÓÁ¾øBî»éÒÕ«³„”Î+Y½šN@£ø-˜>>¸²t½¢dÉtÓ%þ…JîجEŠ˜+ê¼}±Ä’MEåh¬µ>\y„)føúÎsϱÂí·ó\Ë™ÓUBBâ%ì ï¿§ÇÐçÉ{ñ"«?þÞ½¥m[ZÆ0ÂUWÑáX¹2$êק8}óMùê+ùóOÖR0“¹`9°+í ¯ºrY–´å‘½èqI ¥†))´T<ù¤m:)ø-Èüù姟´Î‹uxã µ² &PZ*hxMÙhlègžÉø;” üxÖÀ¬r(‡Ä´ÿÿB,ñ•¨{~ðÓ|ªVe:9„Øý÷Ë /Hß¾2j ál=p@IœÖÿ™3|ëVβhÅ)¤e×®òøãrÇÌõÀÍ ÁÁ{T+D†»'Êe5ÅdCrÎÐÁÙ³lÒÚ©“ 23öìI­ü†¸N´+¿Q#;=`•`,Š« åË—)#TÂÀ#v­–ù%egÙ3]éUÙÄDæqàð¨U‹ ¬½æÍIùþú‹R"))ä"‹pI³fIÿþÌ–½å2RpÑÎÉ!?-/"=w.Í !‚ÔK²¸ë_žl÷¥82óÁy¤ê”™ÉÉ .¼GŽ0Øéê«õj•?l©†îi©¾™š‹»ú¸ÇRyqŸÉ¾œ²êI=«úªlÎG趃Q .WŽ7¿uk²¸%KÜù,h//€Vˆ%ôý÷4Üz+¯ö¾ûäÃeÎ?ri½ M›¨ÓåŒíS$!Ÿ,¯ gí3 ¹2³A}†‹µkY‡çý÷3Ôœ_e ‘ϪÎÁcôhrZ ¹Å† ô‰ÿó†©À'FËsçhŠë×/Ë›.‘e5$)§$ ÓpIú€uµt){K=òcõê,¨2fŒ©ÀBð«0ªY~þ|¶ªWÂóž{h^˜7<€Í–,Iij8Bbj0›róh»/å_œ>Msb·nÊ'‚B„S>kÐĵ’,'@PƒÊÚÕ* GW´†a´ÄS<™Ù¨Ðç\yÓž’PPæ—•cÛô\’r@[T|â †òBoíÚ•Š¶¿Íøž~Zk  áÙ³'72„gãÆ$Ò~µ£²ÝÝã«ß‘KÙ$®I¨18~œFuƽK—¸†Á$Ýžà8q>ª+sñ"ý’veôlßÎ\ž‘#µM¸oupðÌFþýÒÎ¥9–¿K/äÜV¡˜[á/vîdøiíÚ´I6kFãÞî݆Ø?ä«Ýúö2Ä>¤ßõ׳’Õ;ï0l» ¯Þx#“ÎBíäL‰/(ËËÊ©ÐPÏÁÉ«VU’;‰ƒþþûÉ!½T‡HLdU%(S*Ы—tì¨ddŸ8x‹Ö^Ó®Ä~Ù2I=-ËïݹeÓ8;¯'x@NB²Ýuµ†.]üdÇ=P^xÁ‚qBPmúôáºæz‹fÎt¿Rî7øI¤’È)9Z¢n–ydWt.“4©uÝuÇù`ŸbL<5Ÿ®–)S˜ìc¹‹ÃZb÷gÏ2>$Ȫ–`Ú4iSR ÈÂR’³8p¿ÿž[rò¥—h¯³6|wåJÚÿ“ñ2DêÔáÑ ]Ï…L† »'^ijÉøßÒ.T‘bß±ïzœ°y3#«,9x Í|#K£äŽ…8|˜¥(/¶rL“¸|™~¶—p7ÿœÊ._±†‰iîäœ9Œ.Z”‡-—“$'s¹þ·±};#© €ßz« ÀÔžhø=}Úî+ó›ÇKbnùûv9^ª+,ðœ?O F ÿZ{c#Üs-Q–œ"Ë–¨KL¯ÙmÌUw`Γ J_ÚŸ¾€P6ìgÅÞ½4§”+ÇÝ=t(=;ª‘?¿©’­áŽ+W˜çЩEeµj4v[Õ©É;d] YVTl¶ûRþ­9p|uRcƒA ¨—•˜Hqm úõãeزÞz‹SÛ¤‘z‰õwå•ý ùßcÇH-þþÛæ«ò œ2 ”Í›3.èå—YR^pÄÿ¿ªY„Zª­ø·[7MUݬBêyYr—lÏ% !°¤ÇŒ¡o7!Áï.YB-xðàÀ§þùçÀ?ë2d¾_üÖ* HF¤³–ˆ[œÞ/Ë®‘Å䤓Ñ2>žçÑæ8”Ýû÷«¯˜ƒÁ5b„ –çV­Xãÿîž-[èOÇÚhÙÒþŽ6~aÅkl´ä}»¯C˜Q[©’zV;(«ËJø °J(¶P©©Sα¿ S;#q ÿλI.da¹?þÈ›c{CsìÛ'ï½Ç Û¾=…v¡G› ÆjÆÓOÓät¢ï¿goèGãÆ…hI¥¬Øø#»RÎmf÷u+gÖ­kê¾;ÇŠ¸Ï¦*ã(F¯^¬6£Û¶‘ÖÚ϶êW9Cf·õø†_dþ½-2X½š^Ú%ÈpvÚÝß|Ô(éÐÁækКŊ¹9:¯\á¹_¿>UEÈÏÀR‡4ã@\C¸Ù©ÞµÀžjÛ6Sí·Øµ‹ñ3;‡D*.øɵ×Ú`º?vŒG³íÂè¾r0‡¬êãí=xL>hsµyI•-Z0èëë¯vpó ÑÑ<ôÿŸ`ÄU^ËÚ eÊȷ߆A|Åɽ²¶„Ä––s¶jO¸Q ™x|Ãœ9¼¥ÚZKxNêU­júàBD-~‡¥Ld9BÓÁ¤Iê¯É —y„ºÃ†…–ÞwèIW(Ä6¨¸Põê´aúĪU¬–S¶,Bœm^<Å&A«ŠH²­ªÊÑ£¤“'»þÔ½O-—,±ã²Ü"ëé§m˜$¼U+›7ZTkÙ—KM÷SÆF(UJw¹‰•+™ö…CmäÈЕ)fÎâÀ0c"óX±‚ɧÐÝ ¤‡r Ò•T‰ºS¶ä“ý¶ö4Úu9:ÅbYuêØïàp`út:Xõ»V¿ü’á£6a‘,ºS6ä•}~æ–¥¢ô¨Ã[·RQùé§P1ŸºÅ]wÑ‚÷ŸG‹ToÀyפ ³}ÇŒ é‡ÛD¶æ‘m‹ì¼†±cYNÿøqþ¾e ËYtíB$4\W)õY³¨Ûý‰lAê%YPE6’#þÇ€IšÌA)7Æ‘úÜsô€c‡Ú›êO>©°LˆO¤X±À»`,ZD3Ým·™ÒèíÂÒ6’˜K¶›V¸T ï£Ò¯Qº´5Ñ’ñûÚc±öî%ñ†¶b.§HLÙ\LÎöyþ;Í>ú”ùßÿì<8.$ËÊ2²ìjþ öí£ØU¶Ó¦ÑVÙ°!•ñ0¸qºsëÇ7ZsÊC €—(Á,¡‰spAlw9‘CözöY«Âóœ 6×"[.0Ê]Z×àÛpÂvìÈâ¼váÔÙXT¢Ê³æUðˆŽ¦Ö`Uض2§bEÊÌ°Ãòå”'ÿa¬\ÉË >6µ×ÊøñVk ÆHJ1¦mÖÆÏõß³'-½Ø\™¡ãë2„†ÍèÝ›«Î®(‹c{eÓU2ófv· #FÐ*@ú¿3RS™{õÕì¤ A¹àøq_ý°Ã€eü»ï¬ vDÓ¦öä#»Ç/"׊씘On¯«Ëر¤Îíûôa"@(x|öîåöÔœ!2e LÁ÷gŽÉ²Â²¤†¤Zí¦|î9º<ÆêÕŒšÀÂص˲K²`˜ÿÕ'OÒ¤¬H}›úê+ƪ}úiHé ²6ý׸!¬¢¹VqEýK—äõ×i‰ré"ñÐCLœ´­[ÓJ¯‡ñøˆÕ:©ç˪²ªžõƒVÙ|ÄX'ï¿ÏÛ2rä¡ó] ˜tÃgvOð‡iÔˆÚÊÚµ¾ß¬높g® ¢.wÏÄضmýn:²èÞý?YT·®ŽX l“Q£x€ZiSë¾a¯ó•ßX?2ÔuױÔÂ`”¶+¨ÊEÙ²Öûv½tíÚö¬Kç%®‹¦^š/RJDYVãÂ…\êf 8ª>þ˜õF~S&Àmžò2²zb¹rúT€}ûȸ4°¿¦Š3V÷M³gúçºë.¯Eï† ã.˜9Ó÷@C†p,E-¼£[7yöY­3nØ`[MˆèÅe¥#ÞrHi‘ª¦¿iôîÒZ½šÁ Íš±ÇÁ à``bÿ=€9k.w€u Ò…ówÌ­ózÇŠiÏÜìG>Wt4£)³e#‹Ì„”yþy?ZKà´jÝšÞsÍÀáU²¤Ö­zú4o‹]Ï}j]Y_DN;ë¼*Y®ñX½då÷•‹ÿj­](MÅŠÙ}V[,1ц©Á4°w°¢léEèËß’½9åÐr“o‡.õÒK´Af*ÿ¿?mþíÛû—¿vây¾ùNg–{¹_?­3‚ͪ¶–{¢ֲ+/uDõꙪËHNf2øgÈæwhLùòaj˜8Ñ΀|Hœ®])qÀÕBKZÈŽ|rÒ÷2/«U‹í¼ð ¬XÁÂwàŸhNÔ–û¶|9§Óéëùûo–vq½_Zý²ìÍ%G5öµq`ëV×x€9sX·êwB#hD%î¼Ówd$ê¼yòÑGrß}’'6·?xéž{E0k–BÒÒv×ÿÌ™ŒoÿøãP)Ü1ënÙXXR¼%ÊÅÄzwæ‚îÝ50Üê:u´¶Q>y’·Ì–„ñ˜®4PïÒëØrÆôé,»m˜>úö¥ 7“wüÄZ£FdD½{³p_“&rûí<;ræt•„XŠ|À,3/J^š?ŸR¢^=W¹š;7cö\>üŽ³øxU4 !Ã_ƒ  Æ>ôKüièêWReÉ SZ.¸¹íƒñ±›qæø”.* &¾áÃi7Ðé§~ñE¶zÑUýÙ7a´ S;ã‹/(Ú¶%é²Å¦#k×2…$ðÑGiÖ/P€æ>è†?ýDjÍž–ó¢‹eÓ&–qþä¶\¿åN}óÍòÄä4`¤r~w`óöêÅû öf;.œ–¸â2ý –Ô¢EšBÿúõ òWŒ¥$Gç}ŽŠbÞ‡þD¹ýqtäÅ­{ެزEŠe¡Ñ¯¶í¶n•Ñ£É!ëÖ•‚i­…Œúì3æpíÚÅ­!ÀÛ- B×­#ñx÷]yàÞùJ•xmƒÓXåÞ ¸kB*¶GÒ*ƒ½Am±=Óáø^3g6qþÛ„ òöÛê—ü! tW‡wÞÑ ù\¥ õ)Í8sH6¨öºçÍ «’%)IªU#× kìÙÂÉÏ>ËŠ[åÊQ À ÓÓDG§÷Ÿµ&›7S¶wéÂܙ…٠tœÁ¼~=ujˆÖ_‚ ‡¶Øª•ýe.g!¸e¯òуA´ÔÆÑ|×]\–*°{7%é$Ï=gCóåK²´¬,«¨{Þ¬€„31v±mK” É /@ª@¶ôìIå ‹§ukD™iËntT 5@Qœ9SÞz‹Ê;.2²Ô§1TÙvw'€Ã=ù$+²&%Ù|%ÛGKrv‰÷Ø Lß­O/W®àZcmÜHGØ10;jí rUµª ‘cÓï“u…ä‚ö®—θ|™d_ßYûýwÚÂ"ÿ×?w®¼ð M@TB`Blúk÷†ªn;óñ‚½{i7€BÚÙ ·Äöí£»'¤»ð\a¤8ÿ;BAœ±üIÊ)‰qn_„T,S&Óa bBáW±{ôîm}½µ-[øܵEe`Ýx£ ÍÝ¿"I¹åˆÞÆd.iÒ„n⬫»w§3DbBÜ".N^y…ëºÞÀ*ù¦MÖ]™2€¤M™Bo~É’”œÐ œ _|Bî/˜0%i°¸Ä”si4iÖ,e{Ð F’âo/¿L3Õ¶mVLzá—«µŠ9ÔŠaºÊÙIÚ2þӌ-äPNÙckgsèw dï¾ëÞDQÙ°a(nÀÝ»™ÈpÓM,¼_,©ñŽ%—µSj(|øï¿¥eKjëO=ÅýŽ]¡B(¨ôŠ¨(’"{«_I•UåeV5f^ßpñ2£W/ʶ{ïe,ØI µÀøxÆï¹5§€ ¨ j‹"ÃvEÑ\rÿÌÙ[–¬uR`gA ÷ž¼‰Š…4ݾ>)΀@øóOÒª«¯æk¥Ë{ãË/-M'ŽåC¬]›·jd•'cÃNÏš_¦I r"» ¾ÆmL×Ò¥ŒüªUKoëÍ’‚™¸2Ètm‘ê Q< 50ž¸"ËÊË[ >à|/WN~ùÅ÷;W¯¦ö´Þ־Ϡ”~HiP¯9‰ŠÌ£‰¥sgë‡Õ‰ÆiZÁÿ`Ë¡lKq 1‘‘¨ï¿oO¸Ñš5´Åõ{‚]-v¸Öà:”LjÊZk¬?KÏcüÆR?;egÅ„ t¢i{Ö8Ýê××ý°âZÊê‚,àfÀÓJ—ö£VÞwßÑk˜ÕÈ©›6Ñ^W¼8Å[¶(œhåJlÃabâ47Ž§P À<­ÒûÔáØ1Òcïå¯Ëþ\r(ÃǾùÈ#éæ¤$ÆZ(n•+õ€ '1ÂâÅÖ]“WåsÍ„XˆøO™Ñ“¸Lë¤Îøë/ÚOü­Ý½;›âéL¹Z¸Þ(œñŸ}¦#¯ÇAÙ²ÊgQ‡/¾p Šƒjо=¥(´?[;ó€ÐhÚ”öX=2óâEFºV«–ÉÍ7ãV‰+i}#ïxì± |cÇò¬Ñ†ÇgS82‹=qz+/9ã?–ŸíXÉ èpíϘA;ûM7±©±Î¬«¼yÀ¹nZÅŠîAÐògŸeT-ÎP›bíÚQfª®ôrð ;-Z¸zqÎœ¸‚2»‘ÚÙ]°cM(—«^]ŸÁ诪µáÅE9’WNÑËi>œ^T—†Mæqø0?TØ®W`×CKºå&¹LœhC¡{,?°²p„ÏL%è–:Pl†2Û„‚ùÄLnR½t)Õ«þýÝ[á¶.‘CÙe»Þ·€ÛàêLOÃíºûnFeèIJ&²øjI,rµˆöÃdÌɪUTñ6(…Ž§b9ožméÆÐ8&L°gê eÜŒãOßÁ6C§º¯3pJB°ßwŸªÿí·´ðüó·÷Ì}—¡Ñg5†fZC™ò׉=òÀúá~ý•±:‘0œ¦Ë»ƒêt«Â–Y1~<ã7,IÈ=švf ŠP$6$Û··Åž¤Ùiûô±ù€Q£Æ|–‡Á6Ë–e¨sHõ,3pé@÷ßoe¾RJŠtêDÍÅŒò;µ’¬/gÙÔf0w.kÔûe¿1ƒ[Fµ8z”¾so–¹$ª›¾1}:í$º˜!Xš6µ`¯ä¼ómªÃ‡‡Dâ‘#v¬‰ÛêÕ¬Tyûí6T›ñ èæ­[óÇPb"K^àŒ0ÙZâøYŸGbÚZ0µy€.úUÎ]g•à.]¼õ¯±W$¾´,¨¬qF'@Z–,iñé€e|Ï=A9€ lú‰ ;‡I-:Z·Þ<À1@œ6½NœÈhÀ6m˜«R½„<Õ ò\Æq€ÙßÖ«Æȱì²KW¸Ž¤UË„š`²tÂ4õë‰(X·ŽÁWê˜ËÀš¬ÞvÖŽŠÓ Ò䨂BìßÏuø×_|6!Q‚µk[µk-fEÊ°ˆ÷v`Þ¼`-ÿçαtï¿- „ëäå—ü8Ž’þýiy,Lq^[YUXR5††‚<˜Ô6Ôב°qc. m8/ÇsH‚->-ÃÆÜ™ŠC÷_>wìÍ^½xUÐ&Bjo:P¬X˜µ{{â kT³íÛ©Þ}· %h¼àøq^Rß¾~ðôiv Àg®Çr%U6•EMüxHJ"½1Sà£R%MÛ'.ŽÙÓ: 6–“YM|¿ÍrìÚE/Ï”)jgÁV­RÅlþÌ™Œ|òI÷uÉBà½Sí8ÝÃÑ£Ôã,ôwEýëí·mh:à ÇŽqÙ îÇG¶n¥ÆÚ¥K°AƒG–’ílqM™T“!F5¯ 8Cuºb—½#›óÈEí){öБí× Ð#ðˆ½ŸwgÎP±*_žíÃB;2e&\0x°¼þºÅc9ÂòjÕBˆj‚ó—+gÖþ3meþH•ýÚgdK~9ïO#ò`páZ}V ÕS÷rî\¦ùk‹ñK^'‡sʪ4MçNä›nÒW“ ‡8/ÓÍšE†ðôÓºëA†Ï>³¡ê~ÀÀƒ^·NÉÈ“&QF½ûn¨P͘ÖX´ÈÛ{pjü1s+¬ì*ëJÉÌúÖ è '²vŠí¸|Yî¸Ckéþ5å$ªŽ¾é à80:Æê„áÊšpéûo‚Xæ²X!¡Ù'+V®äQ¥Ð÷Û·göSˆÔUÆ£ñ’Exü8‹e@… ¼ãŽXÊZF{uE!b ã´Ý.4j”ÚÕå‚-½ec>9¯½ñÔɇ²¡!5Ô·%2í¬„†5nlYëX=ˆgŒnXLXC£:PÍk®‘¯¿¶¿Û#ðô@‡rhvåÊòÞ{ªV~ìsWJÉÈnî]ØƶòP+®»N¡¿ØOÈ¡\²BcÅx¿üBåWCa·1‚5Cïþýw»Ì/œ;'ùóëë0NâÖs u·Þʲ¡Ðyù•W˜ä|%F­B¥9­ô˜eº7ìšš5µéuÎÇfÍôM·¤¡Ì¹NßtbcITdy›Ç /ÐÔ³'Ãü-:¸óNj»!Ž_ÕÚH’ù¹ç˜/c{|ûåË,úg$žÍûªTÑQÝzËXvæ=nE33˜2…ÆX[B‚/^dðª6—ßÆ¿YÀmŸ^qqèoïܹZ'ÍŠ¤$~—+çFi #@)êm!6´áq÷ëGcµí©”ÉÉ´¬~û-­O8 µ©T±Õei%Msd6hÀâ]úÅÿàƒšæº|Qâ Ë¢Ç5Mg÷JŠíýh6n¤A ];š¼Â«›˜ ºwžoÎÀ­®VÍsÇ?ÿP‘:Ô†©–3'­¸:ÓNî”ý9eý MÓEG“ù ôUþº#­ËÌI]†A浑Lðœzõ4íYÜÆC9äˆÆBÍ—.1˜öà%Οgõ­tÏ$ñ*Š0J3”´6>žë3Oºrç–lÙ<þäÏÏaÌV¾š?Ÿ9&Xlø ËÛðCœÎ™c8µÅÝã £FÑ£jef€”//¸nçýûédôžd9æÜ"KuQ£ X³TRSÉfçÍÓ1uÌxXÓ\zõâikNœ §©Y3o†¬½{éT åüq,HÈ!C¨`BÑ+P€‡O>É|^üÑ’°Ã³gÓÅé½÷²ÉZ®\”´%KòîuëÆB¿J‘lÜH›|Hñö)S˜€ƒ/¢_M+„§®Ð‹Sfê4fÞ*‡sÈ6-iƒ`Ñ8»5¨É“'“€éÁšäbv¹ «B¤­R,!»¢w -kÖ”7ßôŒEófHLÃ5ÇÆ’«€–(A9ùÒKlWºiS†±Èd‹œÀf‡ÆîáìÛ—'¤ NöçŸg3ñ¤$·×Ýã  øãÇ[?rJ ã?A±vîôö¶ž=u÷€ž÷¨¬*®i.¨<.éº]»Zq\SSª¬¹Jv€ìA>?(¢>†vÏš.µµ×tÁñãò¿ÿIïÞfßÉS£†ý¹3 rÆ1]¥X1út í'MòXGBI‡e,  ‹Xüß~K}¡xqÚ¬@GãâÜÐHÃÝ£ÙÏbø eÊ°Ñž…ؽ›Oêé§}S}а{îÑz”œ;![òÈ–:æ2|1ÎGÆûïSw«[—É}&ûnxǪUPOØÃÆwds!ö¡€äÐõ÷ð¡‡äƒ”Ïâ @àí½zù÷)„ví”\O€Ëa7h@YÔ±#™¤ÝÍ®Øøàä ‘7ßL5óÕWisHÎq÷xBB÷5ÔgK0o%°ùZß[·òý:u™Ø>²«@ÚÆW!C\Op¨*þɤ',ì×^ó]Î;žzJ>ÿ<¨LâÂ9˜[Ö[z°zv 4m‘γ…òøÙg~Ô¤T[ÕSIK ÿã*ÝE‹²ûÕßûWK|éÆ•]œ9lÞLϺ|y–Y[½:´Ü=n±k3΂,ÄŠ›·lY¿Ã§±5î½W«b¾ªkÞjÀ©S4z¸Ä®üè#Þ®»ï¦.€jÒP¾°MôÉYø¤,,­c"øjPÊâãõÍèVµjòÕW~|ï^>ñ9s,½&wHLdÕš%辇˜)Ò5o^«¯,P@zC¡€Æ”/w„Š†ÝbÛ6rãŸðãøv`ÑЯ+Ëߨ‘Ö”·•ÃdWnIÑýòË䙞Â9e E!ú^y…*¶y@Á¸q’_8“,I9eƒÆ›ÍšÙ“µwò$ &8È‚ÁŒ”öÞ­÷ÁÚk‹´îB`Bl 0LŸ.èÖMž}–%¡‚á †r›pcˆ÷Z@©¯^ fÀÆ4œËXÚê’ë iJ…^·ÎT{ÜÞ½ÉóﺋîŸÉ#à¸cöàö‚ÍY%XÆ£ý0È6% uýú4<Áš5­1S;pñbº_ {í§Ÿ,ó.á°Ö¹ï¼«ÚpQmÝJÛf‘"”ŸzÖyX»–Ñ~…G‚ á#ÁWø9’µ1µ“\ÑWöå”KZhÿ}÷™-žšJ§póæ$œ;{ ”ýí7úD4àÜ~9˜C¶ë¢—'NÐL¡¨\¹Âd–öí-[mÛÒ¨h ¿þšmµ±0æͳ8:LÞÆ‚„.Èê„:r$½ÿ&n¦_;µÒÐL•?ìî?äs\±Â‚y± \«Ç<¶¤Äµ×1Ñï¿ûí‹ç¡Ct⮂ÛR©Û^|Ñ}Ÿ©ß~SØZÓÕ¬éÍ­l-–|';òÈyõ-<ð”Ëí7ÁÞ™7ÚYŽL刊R»›Na¹u ÁÜ¢Kù5èo©”ÂᬬSǬ²î…HÔ§ŸêcÚyóÚïê ÃÝcÞé¿jãî¼3ØHf ÙõÈ#™šã/]»ò= ™;Ò¥ nî\+ƒÿS/Ê–\²m”ezh³ùì0KJS­C¾5àÔ)¶`þñGoÀžj׎&ÈLýÀùk{{hOîŸ8|˜[ lYÀC{÷òb°˜¯»Žj‚ž|œãÇI25´HR/ËÖ²æSåY•·iÅ#6»3°Ý¾ý–¦ P…¾}­á'+»ÉŽ‚ŒcÿX]:Ûƒœ<û,㢵aËr¡eËܼ4y2ão{ôp}¬Úðúë,jd#6oÖ‰¹x1Éù3Ï„D[:¬«9Òû˜h$@ƒš â­~[6Õ1QðøàÆgzÂòå|µX1ìMŸîb½í6Ó%–•ZêØ`›Ü|³îŽ8Vî¼Swù)Sx.8ºx‘%תVå~·ß}çmQi€%íØ@Hžžþ»ØX+®) àâNÞz+“Ån¿]ké*lvÌK÷©çe[.Y¯1õ/0€ÞcÇùLÕÇc9Rjצ›éã–&-Ë”aÛ.SX÷­ìÌÉÛ¢#FPÓY*vÎòu©‹^ЫË•–„† =ù¤õáLþ7äþûm›ýüyro«¢+gÎähŸ®µ6…¤$ú¡žx"]N⣫¸6@SÓÖ~qF;™ƒŽ‰‚Á¢ETºÍË–uëh Þ½”z¼!-ׯgð¬Ña P!ÁKËËÌ&V]µ7\¸@Ù¥ÓÑyò$Ï»’±˜zˆ ß羶ªDXؽ›§©]°¼ÄÜ޽̭kÒDkE͘’çš-'N° ”fãp›6šLg&KJv9²PÇ\£S§ÀêB@6:P¸0«Rg`|<°«ÌÜ»^Žg—£Z î^j>…ŸzÊæfÜû÷󠲫“[€ŒåËg[¹ø€Ý=^péKÓ@=×cë<Øý)¼aô¾}:®ÁÀ¦MüÖ–ôñˆ_DjˆT— åd‘ÅTM7¡H‘ÀÂ?J–ÌPÆ…§¤NlßL˜ÞH¢o èýÄ¡C,ö|½óøázÆõg9­í¶ÛÒ«¡êÏ—÷‚[oµ§åÊ•\Š¢@¡¢‚9VÙ»òÙgéoõ”øЯ5:ö'žP\ùí ‘y +Zÿ—$å’T›š¶ûÄøñw7 ˜Æ1^° ëòÌ$B/ž‘=9e§=¢KSщVg Ä”%u(åõק/æqã˜È“f^ ´liO ,¥„´¹bEÖ%VáàÛ½›eµ¼·–€¨¬WOkÖ9v»µ•²¦!eÁÿ$¦u¶mYÿìÓmfJðxá¿2 ì”Ûnc-À¢­ZÕ›c ·ÚöÒ¸²‡Nnô^ÔÌùß?(™¹e ‰â›oR7êa©Rú<}±± ØÓÐOvó<9žC.‡Œ5^Ò‚‹S^áÜiIÊ.¦ÿ÷èQ–øÃò¸õVÚN-tOíH´ù;~ý•š¯-èÖéá>í´à󪶗ÃÔYÔ½»|ò‰¾éèуI^Tñ<™zJÀ]Ï€Ÿ~¢ßVÛe?r¤Ž‰bŠÊZíuƼj˽÷*Ÿ%ê}ÙPÈÍß¡¬=õýËO?mMA¹wß ª4¨_س‡‹Ü–Ž0PÁlMs;S‡²×¤³¹-8€Fh7`æž ¨éõ×[ô{硇oHê/fÏæA¬aQ-|Q6W>‹y<ÿ¼Ž¡KÊÉâ'=¾zü8µË[ná#4(ð £ï°s>µR<þ¸k_x=€´¼ýv?: Ÿ?Oî¡ÍLá/¾¨¯íĉÌ"´XÃ+šjîUèá‡yšXÒZbçNZ`´5kê°Ÿ9"‡rHRh&Å¡á,>™('²Ë1ÙÒ¥l–Q¬ãcçÏ÷ûü–Ԗڃ¶R%2µÂ þö‹ß·F'\³]À£Ñ ùc{çµO?åòðîÜ\»–rõƒ¬LÐÆòÀÞуñãéYÓ€·Êì¦:&ò‰¸8š\Tcé3]Ö÷Ÿ8ÁŠwÜAÃW¿~fµ¬:¼_OèøÅ‹,A©¿¼$ä@åʲ‘¨(fÒÙ•¢}ÜÚœnOضm16žùÕW™uå)¦}Ü8r•ÚŽ{ÇÙ³ŒšðYBÇ`ÇAàkÈÝ8Z6äS>‹ôî­#amq‰ ( Ò´ë¿eKVpõ~C;¨S'° ô_}Ž ÏØbÁtñƒ¼½í6ÝÉ›ÒR “¾û¹ê*öb0iiéÕKk†—µP 1¹Xæ!BßxƒÖ'E­%~ÿdCÉú›o˜¯¢ûsÉ-}l½£vmBQŠ£$9»œ ÂK{ú4Ó´ÿ÷?Ðt×­K§¹`obYj(²°¶,Pï›öhvø²ª ÜE?!K®·f¨µk™.T¢ÓF¦LÉ´û ¾Ê”ÑÔlKg‹ÉÉÔÄ-©ó’Bc kMË;ƒÁAƒ!ß²zîn¼ÑN4o^zÄc‘"\  &&¿pô(K²UÑ–-cthß¾Ê ´._N“uFÞˆJ¼ýv`UÎüÆ_ekå³xÇر:ìÃñEe™¥ zçÎ1\ Ú7$ä‡2¯G4FíÚEzi‰OÓ$°¹~˜Z­Uؼ™_aþ|kFÛ¹“Zp…  kÖx”nÖVZ;~œMfÛ¶¥—°E ùûoiÕÊ~wOV`ÍÕ¶¯¹†%ˆõ੧4í(×^«<ˆ‹jo.Ùd«VÞ¡ƒòÞ ‡×Êièãj:¡lÚÄ´äFXæC;£cGšt¢_?iÚÔb“d x`0µï@æ±x6L¯`¦øC÷îl ¬ R8C¡üæÈ!/¿Ì…R8žÆÌ|ù4õ3°w/ž;œVºÀ,¼Cf×S>‹'`–*¥ª…®Qm%¶¼Ú) c¾þ:õtH€nÝÔvt'­Õ£éˆŽfH³ B Ùí5bpæ iqUã“&ùáB÷SêŽÁ7jßžC °Ùàí½–`ÏÆÞàÂÞxCw9klèËðÇt3©ÆÚa²!¯òY<{¿fMõ³•¥o*ŸÅh QiTýhЀššŠ&‰Ø†Ú¢¯%ÍÈ ¹´d‰’Á¡ã@õK‚%'ÓxqÔ¬Y u”F©Œ:ógÏÒ{{à Œd°±B)°`ÕUcÍ€“ß}·Ön†wRÉÄ¡ Æ¢ºÈê%9CvÚT¼±kWµSJsÙäLPUã|cËš°<”iüx–¡Æ¾~ë-+}ÙЧ°ü´µê3L—ŠtX§N±Œ©—†æ`³Ìèsgš@ÃŽ ›ûdu÷àš‡§ñð±Ç¿æ`0p =/Žú°@b"¯Gg÷m$üYCÖÛ¼jõ˜òYÜâñÇ™ï¯ ^‘u%ÕN!i© /»«±‰íÙ£ÍàŸ¿übAhèS½{;ˆyôíKWµ;´bÐ;]œ9“°Ê ÅÎ¥K´ã):qÚ´qïîÁIjˆúW^ÑW’åÜ9ºSk×v“C‡ÓÔWiyCg€db ìÞ­|"œ ™ªC|£zI|1µS¸¶!È’ê®ôó¯—¸Öj§À¹ñF&Tzçĉ¤jÅ‹Ó7±zu€-êwBbÀˆ‰á:×Ó—pÚ4׆æ9ÂF½•+[æÛ ²Ä„[ìßÏçëECT‚C;þûoëgwÁ®]4è½ø¢GéÑ¡MšÚð曚¢àðpÝ·‰µ§Ž²…âY]€vY£†Ú).^ƒ9ä°E±+žÁR¥Š©wâ¬7¢_îº+ ÆXrª-€ŸàKYž4çPü Í‚ݽ»•Ö`ð@Ë{8JÚõ›1ÆFE‘*ƒû©;‰æÌ¡XönåÀÚÃ)?nœªkpx±bÖTƒ÷Žo¾¡ÞªKKÉ í}ðÕT–ƒêM_}•õüÍ#5•î!Y¥8çK+hÀÃí×Êæ­·2HÆûÒíߟÁz€¯90ÞîhTª… é˜øà%a*:ÅÝ™ª %ݪpëS§rP·®qzД_xÁšÙ}_Ù²JZ[º Q#¨(Á‘{D>—ýã$)§š)<÷­xqåö±d§âÖrà‡AFFAäΟO3]Ñ¢+cOA€èq³^¾Ì”y3nkˆ'C(UJa¥ßèhëS=¹{¼"ŠF½zl„-[˜ ½À¯ÌÜ3gxBY•oåuêè°ßŽÅ:9ª±-ìTì°vö…I»_ÀHÚ.)ÙE»¡[Yå¶>z”¾ÔêÕ©‡˜‰'LœÈR zðÝw¬~¯Ú3îØ¿øšøú7Ü ÐÞ•œœÖwÙ:$%ñôL t(ÑÁXÆŽ¥ þ—_ùì´i”´z ŒM«‹jàù)¢<³cN ‰n¦v g€À¨6‘-ê)[ÕA«²¼sL ëù`S·mK¢•šÊÞ%³fY<‹[@)ÆÖ³¥ÒΑ#d¶X ÓÝ»³Ë¶ºâ`W]eeÞ±IwLJ‘;eŠßÄ-êÚ•‹pÕªÀgoÒDS*DJ #“5¤?ú¨reô‡²\£³sg2¥Xx›¬~HíЃÀ…ÁQÁÊ8v“žšÿ¯¿ÎÀ'ýÀ·Ïùè£tf{éÃþÕ54‡Jn•}" ZmðqJÑÑ&~µþÄéöðüQAÆvnÚDˆïÏÛo[YÂņg—v¥HNdÅÈ])$·ßÔ™hÇrIj^‘ûDzŠlW2Å€:â|žzŠáÇØMPW§OWX òG[œ§[·òÜ<8ÓA8ñGE&¯6m¡snàæ›­jýz8ÐÔ›Öo¼aÍzxí5MkÎeÊ(wý$&Òk©º|ñæ«dé÷j§0pö¬.¬ö¦L’SÙ%õpZ@/‘Jf¦L넧“ 4OOÊòðÔ¾}5åþ|û-3ëUã½÷X¤E)Võ”ê½$”¯wÞQ;ÅÂ{dñÃj§øë/Ͻqc÷Uþ.\`°Yƒ¬Û½{PMv Ô«'#G;ˆ_HH Àg,.´NËKL¯\É[<À-Ut“Bqà n"»Žåé ½FE<Þñãd­Á/$ŸÀùrÕU -PŠ ”'OÙu4o®<ß3¾ˆ¬UìTêÜY† S;UÑ¢>ø•QßZm£F$NQÄÅ‹iÓTìÀ¡Cô•|óïw‚ÃßsÅI"ÉÉ´l‰Ë—ÙÄVQ¼èöí|¦Î§ Ø8¤è»ï*|LŸ|¢)9¢eKS>€Q,¨¼ÖîŽ<²v’Ú)ôpò$M=jÅÿñëw©Æ#('fÑ•e¶â‚̧N±¾–R2³i´lʯp|IsöU«¦v ú×?ÿø÷‘={œrrß}Üef ÊAº^½¦Ðe;2³Ø¯Øøèh¦ ZxBAÖYò±Ç”'Gÿõm¼O?ͤ:ªÄ@¯^ÊzJZi¨NüiICó¡Cy+†%Ù=^0l–± k@r:·™PŠmÛxªË0€G©¡B&¸™êšŸë Éòá ÇðAVƒT‡ä ”ù©*wt´ò8RC&[ÞD )‰äZ^­ZŒZ9q‚Îqm a!™[µ v={èn  ý™ Àp4ð ¢òöÛƒ½O8ž%×p²@£t`ÎÊL š²úõ™Þ®X ªÝXÐúƒ9Í`Á­2ÏwO,·¿k©RAµ¢ö‰u_ÊŠÂ Ç—´&ݪÛÓƒNÜwŸªÁA8gÎda±‚¹ •2%°å!è,‰ñ^¸(ÈF„8&ªV ð³/¾H#¶ àDÃYÖ¬Ï2@7ôQ%“fů¿ê˜ ³Xaë‚U«”GcÎN¢*û|×îÝ´EùÍv± ®º*°ë2‹¥-e¾E¹½žÐ²¥ò²~|@+™jÔ­K$óŽ;¨ªëŠeyÝE£ŸE0É rùòÒ–îÜ9zaTô2‹‰á¦úä÷ß :ò]w)“1€ÛR¼¸ìÛ§v–£GivPªû_º$… ©m÷¶þGÙ\ÀËëXhÐþü“‡C¶l~R- i5™§ ùÂ`JJI²¤•ÓY¾\íÛ¶¥§v^¹"³g3‘ܯ–~áí·-ðÀ5·i,ÏŒ]Oœ¨Ä[1d¥Ç4¯¶÷5ke¤§>žWß¾ÊgV½Îq°ú›çN'IJ6¹˜¼±t)-o¼ÁÜeЄüùؼ9“5ü‘ùm~‹­E Ë/96’_)ÿÀÆ](N^ µV>ûÌ5ŸÚÑ2‡¹U$*>žÛÜróþéÓ4ô«P¿~ n5HKk{¨¥¤0¿›ÊŒ1ùµ×ø£qqÌcR=¸ä”¢[7«QŠ½¹ekÆ:|õUP|õí–[·rŽ›£6‹üŠœÉ.üÌsñ S§ÊCŠËlNšdsÄ' ££Ýüämî\Ö..Z”uŒ¡'Y}½iSUµOׯgÜH厣¢øí  ùüÁÛðf¶láŒùCU¢ aRm4S\†T¯®¼àVšêà¢ñã•w+ˆ+#1oòAŸý…XWDZ¯®Rà´R]õ•WÔÞ%IKU._Þ‡$„ê÷å—dq7ÝD…10 ¤ ˆŠº4¢ß皤¯9Y¤‹>}|×,ÂÛðf‡äìÞÝʲÆóæ1ö‹/ü;’ÖäýÁ…©93 ÂJK~mÞ¬°Ê·…÷ʺþ}z;NÞ‚}¼­AšËÔaíç²¢¨Âñ%­rÎ,¥¨ZÕOK‡ÿ4Èl¸öò‚é=ÚžzŠ¥ùÌ#5•~%Õ¡#Ø×^úY8“ICN:ðÛo~ÐCrfÏnÍ×Á]íߟ\qæL¿?‹Óg„3ïU„½{i}R3«ºpååË4#f:°Kß’¸küûNŠ={|”×]§¤¬1m”»ÈUW9p€JÕ¨WÏï2;P!f+W¦¦6p © c8Yn»M¹1Öhhž•ømÜHç"$±lòæ;†³ ºèéþâ̦Òרø^€¨àÀ/À<êÔñx÷¬ÂË/[VÌÙþ÷?ÖãR¬½}ûä¯ÏåP{ÌÊ0ïÍ´©R¥ü¨Œ‡ã£ti:PƒÇ?(8‘´æ ™JûµâæC†øø¡¶r%Í/Ÿ|BzP«õ¾bÅØ] ÿÅ¡=á ¯Í¾<².S)ìhiÆ[Þ}—Å'$-/‡ƒÙ;Üü{îñï²ý…êîê8§^P\ÖôRuYl4 ‡ØXÖÄÀZjÕŠ½€ôûñÇ•XvÁ˜1ÌúÄîƒ$7ihØЬiÂS/ÝM›È4À½7†€ýè#ÚùXÔ^ Zuèƒx²*¢ôCÄ[pv{)°Ÿ’Âp C<âçŸg†N^PCè “ ” óÞÃ_7^-ó3 ¤@í(R$ùj¹ƒXŠÕþøC확ÿ\6¹¨²[h—.®Í -GáÂÁ&ýy‡±,Ï}€¸€x¼ãš©ûô¡yǪêú$Î0$–i“&~|jß>³¨üž¬y]Øh7ßì17[l4ÕB€»¨nõ"ie?U{95RK Û–)Ã_°ø¡€Ì˜Á]Œ½Œã²B&|Ýt¿&îçˆL¼ÅªðW3Zq³ü“‘Qî-‹i…$tsS:Tm É„Er,§Âñ‡R[9O§­R€*U²pšBýÁ"¬\™y+ª‹ÞÀò~ë-4âh¿ûnëëúB³òÙKwÀ*øYƒÏ±C«W§XiS/½V݆t½cGµS¼÷žõå°$p~Í›Ç=¬œ9Þ†e‰gÔ¸1¾¢;¬Y¢±åŸZŽÿ•-ëZlÕ!$¡g*dnÌnÝÔ&[Å’-EŽ/i.r¥?ÿü£Üû a¢ÚF Æ…5ÙU®½J{y`Á?÷ã— ô“úÒ|£¢¨xAã7Ά2nFc,(ÝÎ…Üqd@qVT©CÒNðß~S5¸øRJ1vl°™‡“ÿÉé–-©(@±uÿý|vÆY6a‚ÂÃeù+²ð:Çÿ¦O§­ÚÈ»…z†^ä_É„SÝ,çzúi÷ ­Â¼Î’’²<í§¢õãƒ!€X+ K8Py5ªGáÁªX™ŽÖÀë×3«Bãá‡y誸{:‘38w[¼˜{ܳþ i  ·ÂæñÇÓþû 8A#†É î‰95X%Î'ŸP(+­cùÇÔgU›ßŒ-`lØà‡;øìYI¸Ï}úP¤Ô®Mã~‰iŸ}Æ—Ö¬q5)ã{™†ÊêLÄ2¬Ä2ãÁ3â—ý²kЀ5¾ÔaFcY¡RÙܼ™†,¥xþyå9>PùUWmmÓ†vrg@šÃàOð[ ]ƒÓç’•#ŽAÎéN 6¤¥³=29™Qä™ †ò«—.ÞË-Ä5kª•3òo^ÕNÐ?¥U’p¸@`:×ÿ4ÝaûvÆö’nr,_žÑ\¸½ ‘ï¿ÏbÔ11¦Î²îÝÕ6`:°Hvæ²xÌ›nò»›¡_˜RCâƒîéàP¯ür(°¥ôª±ê.'Þ·ð–-ôS€±MƒT‘ õn¸Á#“lÛÖ­_ÛS${b"ÃÒÝÐ;ïô¯šnBç¨\Ù²öCÞaŽÃH) ¯TWüÀ“!7Ôj·-h4ΗN™‡âì†Éq×®MŽß|CMG.o•V÷(7óf–‘m)ÿ»ï”§ÖÞ~{¦þ–\ð}‚¼ãŸ|ç‚øOEt÷½÷4 >Ì "/©šPÊ@EFrù3´7Oßë×g1ÈÚ¢ùM Ñ ª:h…¯êæ -q4(ÅâÅ D´gÎPkk5Ôj ~ÕU’;wºZÝ·/ëϬ[gå‰3e CÍb‡$æ¢)ÆB¨˜ ®’c*ã Kªn«ªºÒæ‡2®L)Þ~Û×ÞÎT¬ ã<Ä‹³Ò'žzŠsyð5׸T\üóO2\Oé­®!æ«m@¯ìÕ‹Ú¾a´Œ§ ;k<¿å0Êð*M Ãf=»Y€ ƒZmDò€oà”Ä"/P€~húxú?ÿLµzï^òIuXµŠ&…Ø%‡ò[\xUi[Òå9@Ž£Pu ,¤`2æ|¢yså%»ï¸Ãïìcì©¿þ¢W„³kW7¶¬¬Àƒ¸é&S ”j]æRK`fØÁÐæ%M±büÉÀùó¼$HuŸ8uŠÛ¿víL™’´ª{11‹U;îƒÏP#±zÁZqß}—‘xFƒP VãV@/ž=›jµ[χÙðÄ€pè/C!’ål^‹«¶NïÁ Wµ^¿¾Úì]ð+¥‡¬¨¯"iMÍÔåp GS`±c½õ€g¾X:ÆlÒÄ%ºN³f䃅 Óªjä ¸nY“ÅÕ·l¡Á­cGW“,…œÑPV¡„ÅMð£PD;tP8¾¤En[˜ýzà€|þ9Ï)¨ùß}—¡ž@ù«õŸ9öjÔÅ„ltPJoس‡bÁ‹Ö üÑG$©ÞK‡Aœª&™Û·³Ã…%0Zvöïϲ  ‹ø‚àóx ø"|nrTÑW(¼æ9I-$Õo²rHµö•áÃiÄIƒG`4ÙTŠð˜ÀÍR9eƒážðLýÀpæ7 Ri^0ÆWêQ2¦PWpãØ1níœ9éf0€‚ÏàҲʶի)$ÜÔJ{Ä ÎIŽÎز…î ˆS“ÏKùVõ5v3ÎaØX Q_µ*ïÈ 7¤G9J/˜ª‹M¸ 4åO¡¹íoªï?ج¿fO¿Ð¥‹Ý‘è¥ÚB ©rÞºGðÐCj»C`Λ§rüð8á>¾_ñê—.1iÜ|×oGÇ[¬¢ªUÓ™¤ÙûïSöZÒj÷œÌü,\±zuòF°GpH0IðÉ©S邬6»†°7¥µ=GR[ÜfëVš1ÕºG€E¨¶A6µe½%üN¸@¼zfxkBþÉ'éy> !F‰•ädò½€ñ=ÊÌÁ_eÁ“víhiÄý)UŠ¶Ç瞣yjÒ$Y»Ö[ú§¿P}ÿU'VÄÇ[\ÉE«úë†Kõ£–q`3„¹Àù?¾Çlc幑ø9xù˜P¡$š!{§Nñý¿ÿž)s°hQnÿ(dÆ£/;äï,^¬6uJA¸ÇÆ[(0ÃèRÝââÅ°š‘ñ3ãúëÿõÃüýwúøÆ™ RqΊsçXPʾKKÖÛn£ŸÈ‘9è¶üH¸ÝWD’}<¢Ú¿q"ó_¬YCæ áºZÂuüÒ¥ÿ­øY!iLG‰7pË„–ùê+ÚÖ6dáüù™ãÓ¼y -YÃíþØ0E¸˜ŒIM)Â}µ„ØøŽjÆ8ãÀî\ÍÛ·Köì’#‡Ü”MrfçïÆr墫ºI¶6øæöGع3¨T‘»?¡8E¸˜€cdiv`1Â}µ„Øø.qô»v1…ºfMY¶,óûºwçÈù²É¥lR.¦"„Øýñ§NETrŸX7Rø\ª[Ԫ屃U÷Õbã»­¶ñ×_Œ]w©„Þ"»Dÿ«’»©ŒiBìþø kk÷¹E¸ß¢ˆÀt xqµQ»þ«ÅÆñSS©/ϘA­û…è’öüöéÓÙð9†ÑòlòVÒKCTB™üqÖÙ°0Y/Üï¿ŠÚ}.÷[fÓñ£ {¸òÌýð_-ÚÆ?ž®ê‰<ùÄéÍ®¿ž©1o½Å¿§’Ïm;Ž³g4Ë Òp’ä?Î-ñ—Ù³™8vÏ=ém†,IÙ ÷û¯´vŸp¿Eá%0•®+ÏÜÿÕ¢hüãÇYSâçŸ9~³f ÌŸŸ92­[³à98ÏêÕnë|Æl ·]˜Ò¯ôÐ!êçË–É€|ò}ZœpÞ¼”§cÇÒ!nÔdÇ)ùÁLÆX<ØD¡vÏÓû¯m| SD¦ÓjS#•gî‡ÿj ~ü+WØeÏñ›oXüÒ»”ÕªÅZëfŸÎPÓm‰&L`vÏË/³Ù…–?ýÄV 'È‘"i­x!‡Þj½z1HÛá‡Ê?g£Ðq1Í›óè   Gèß{Ç×Ð0"0¸”S†{hDe ”gî‡ÿ‚÷wüÇ3êÜ‚.Ö¨AͺlYZ»t¡Ì„ätŽrŒŽ 9cé=Î2UÛÀ°F‚ÏÛwÊé éïnÑ"]£‡¨lÔÈMGò“'Ð~ï½,ÇñÆn´yA¨ÝÿP_u@ ¹'a$0—–O^V8¾†Ìýp_ð^ƇœY±‚åªz÷&O3êÜ/žQçvüxSun-ÿ à«ërË•–é šß}7=‘\ÒÚÈÞpƒkoYvî¤Aüõ–[X4Ùºx­êÎ>á¾~T窫Î=áù>óØ]Ò=k§ë !s?Ü<îÏÞ½éunÿüSúõ“N˜ !òÄ+ÉÃuôNt¾¢ Sùõ×™ßýe]Iª’é/X¢×\ÃöjÎÀ×Ä^sØ6Íã@»ìÔ‰â÷ÑGy÷,ðããÀÞþ a1>Ö¿éøŠ@0©‘Ä[×V¬jUß #³Ãüª®hív|°±¸8FöêEu×]¤pÐ+ëÔa$ÏgŸÑk¼v­« ñ Ó+É„Tƒ€w`ÇŽŒ÷nÛ–™å%'ËäÜr~ ë ºQ¨±t¯½6¡U½gOÖñÀ-}õUY¾ÜïL"$iûø“+Éæ®–ÅM©4$Ù¢þ„R Õ^BìÜ—_–?þ`@é³ÏÒXwõÕädwÞÉ|™?f±eË‚j;¨aÛzd°Z5=š¿C91üê«ô—\Õâ_¾’yE²øž@¡ÿÍÊ„… I>è`¸{ ÚpóÍÒ¿€UÜ=ACÀÌ HRõøó ÉAëRG±UUWû±°‘[Tª¤¶Ë†…­¡‚Bež:•¹Õ/½DUº\9jmW]ÅéîÝé1Ät>ƒaü…Û‚–ßÂmOÖ¯O¯Ÿw nR…´,S&³›úçR’äNIÙv ¼tï½~g—»ìÓ%K¤sg:¢š6¥W=°ö=.À1÷¿ÿY0Ž¨’¼r%ìV›²KêNËFéúÁ–ægÒÒÕ¡~}/ûÔVÑÚ¨;1{6Ý.o¼A&_±"Ç©\™[²kWùî;:kvïfÀØŽR3´N\ƒjL™BÙm´ˆPS98gÑ¢™¥åÊr<‡H!‘Î"3½ôҥǮ¹U«LqG>1m9¼Ûë7ŽñO¥Jщ¶aƒcfÅ!<•Bµú³w/W¬R¨˜çäD66Ž´ &0àC)öd—+ÖIø¬xúiömQ ŸÏªÎú~`ÄLóæÔïòçgâóƒ2júçôé ÆöÄ‚jÔðU<öì¡L>yRáÞ}×àÂw/]Ú”"óu+9\<-”èS‘2"s2^Z¹’6 O8uŠ×Ç7u‘Û·Óèçí=xX=zPþƒ»þúk€=ÑZ¶äg•Bu$V5Ö°R¨˜É’léøË—+×Öç“#®}¨­²_®Òe299ý÷£Gàm´lÛ–ßà*ØY:1,üÏ?"ÞhÇäf=F3©jœ8Á[¯o4bZ·¯(ML~t>Iv¤=ff¸ÿÞ‹anÞÌ©¡ù{èèÃg˜P½´êyãÆÌ~zýuÿŠ#a"ÐT¥Æ"\ÎA¥A’?ýÄfšêpæŒbl¢$Z*0¡@a1(E\ Ù8@áøÐmõM>}šÁ‚e‰­[3a÷ KGŒÑvð·ß˜Z)$zõr“m-À~ŸyFí¦N%ÁÆF8tˆyß ˜“GÉÉܤžÁë$CѨR%#ÜÓ-p¢5mêw(Ý®]<Ë–edˆÏ€y ŠƒR@+Q=λO>Q8þ† ž›†Z‚í²Ãj[ €ZemiE‰Q™N>m-„AÇôÆlSØ¿?#¢ë×çö¼ê*.HˆÊ¢Eù÷%K¼¦ó™P2²PUj)uàwøDÊ•£10ÿK5Ùî5‹¶aCßiŒ8wš5óØÙ¿áf£ܽɓ™€s³K¦^Å磜È$p”C7Q |YOiû–`Æ yè!…ãËJYiµÀ¬ZU­-ön™ÛTáøÐÅ*úSš[xûv™9“6ùW_åóºþzê¸ØkØìÇ3yïÞ ù9gŽ×Aƒ¤ˆ«Ú a '¾—jà[|ñ…äÎíŸ*·7Qvçó^5÷_dGHï€LÃÑãÖŸ¾?4N½àµ)*T ®êî¶8 h¶_E“À{ïyŒ° ×]§¶@÷°aä'ê#±V LH¥ûhE+™}«Âñ/\`äƒ[ŠQÈßÏåí·)!óççÆœ|í5:”’òÓ;õ‚\ Òª€mÜèûmÁ`à@Æy*DG«V#sç2<òÏ?Í~pÂ󲻤÷@›1\@ (_Þõ€ƒeað`³×cà±Ðn{ŒÆUó´éزåßVÁ*Q¯Ã0Ô!9™J–'ºn Þ_>ýTáøÆH”ÕaQ:¤‡+ÂÚeÉÕ Ç g%$ЖÇ0o¨BPUŒ ×^Ë¡sgùòKjÜJä9‚Øtì¨àº€ñ]S­xQá¦ìoaÝ:Ú£p¸nˆõë)3ͤE`K®É+§kfÊÏ /‘E.Äsßµ+ý¿çÎñ||þySŸ IIÜõÉßO#jÏžŒS ñxš&S½Ct4s ”¢}{5Õ2:ãœÏiñØÎÅU`÷_²%Åc‚UnÚ”nrÄFÀ_´hzvÌ“ORO7Ž(VÙf—-S^usüxrÕxäU¾ò±ci#u9y£¢øÇþññÙ¥³åVõ{"×àä-pÿ6ï‘E.ÀwÇ•8FëÖ¥}@)S’4±oÚ²%­+ÐbT7&¡Uß2j”ò8R<И…ãǶ”9Õ-zŠÒ¨æó‡å\¶ÀÝ P«÷ìa•ïï¾ã©ýðÃéàUª¤›±5š7§/O ç8f´$ûÃŒ°ÕNèȬ+D`”gVÕªîM àü {Ç{aܽ’`¬ê³"ƒ@UÝ¿ Ìͯ6»’­Z1 ÿ­·”Û‡1r$UžJ•äÖ[©5${öûƒÏ>£ S) —¹v>¶8bp²dâ±5d¶Õþ˜´Ü€ö—)CBågÏ’®@)ÈzèüÙS„"ajƆ )…|âÔ)éÖ®\¡ºbDY±n­ÎÁäGŽÐ~ŽïŽ3Úœ%‘iGÒãWr„¿Àéú§T«ÂÞ> Ð;öç–S-$‹* äÉCïî·ßúÊ6ˆ½Qf´ÊH¬nܘTÁÉóî»”E‹‘<v '&RØ*ÅW_ù—­–, øäòò^SûHÒì$ŸÎ@n3)<üþ;•HN箸“ÊÈ–fGðY-ï×_¹žŸ}–‘ó’éwýõÁ~_ó€²e9+pÇ.$(\˜‡/V{0„ßQmøbZkxÕ6RÕV…+)¬üsÊj“ÖdW@î6œ™?þH³b… ´g²ÀáøÀÝhÑ‚i“sȬ\‰ÕXÃÐ ý-/ãÐÜ•nŠÅ‹éDP ܾ%«6×_§7``©´iÃœ—Š¡á³à·Ø†¤Ý²JNäK;Ì~Ü{dT<è)uëÒªãò)¬QÕNI£—%KúЉ@±ªW'çá4¤º¿hÙ’îx¥øôSyóMµS´m+¿ü¢pü}se—šv·Üâ#mÁ{,=ä¨AÖ5‰H?9ñ@ûõãËXE ^’¸rV^pV@‘WênƒR©:%JÒ¢,~þYí’Â0ÉLHàf‡È FY‹Ž¦e/[6ù,—$ÜàÇ=EMÍ ¢g0+sÃ_pp«N>ÏôÒ-pÍxܸøFP¾ÌËó”ÒÕõú ,»-@j! /”6§XÓ[âÔä}?þ8­=Þa$VÏšåü7E<À™ÞþxÍ5Ìs-î²a¬ìT\Uï駕Ûï¿ŸÜX)ð°µ5 0’9e }F?ýdÍ5@änÏ&/¥µ$7©ÚoØ@…ÅCNBðºÖ‰Ëœt•*©MÐز… ‚¿Gê‰4iÕ¬I»H]b¢ï@wS ékm9eœ:EÅÖZ5ÓK›É\5¹öݺe:½$VãL¼rœñóÏK­6Œ‘M›Ò<9t¨;'Àé#4&\Ri£†vÓ¹³Âñ>}”³l7ì}¥°°»¡Ý>‹Mma¨@ô@Ù‘îáÄOîÜÞä'Îæª60,¯"s¬®]i$V¿ù& ¼&«Óìè?üÀ|Aœu¦ê+$æ’*é6Ži¥€Ê÷Ýj§Z·V^ߎHçF;^œüì]\Uå÷ÊÜ©9±eYijÎ\™šZj©åÈQi–#Ór¥ÙÒLÿfæʆå6Ór›DqâEY"¾ÿ÷¹‡ðr¹ûžï;çjÏ_?ÂËùç|ß»ßç…:|ñE•ã«k’Ÿ9ÿÚX~æÿ*XÐÄÍq¼™y¿ŠèuÚ¾Öƒëöß¿}ÞfìªMžŒ¨¬ ØÑc}!ˆ&l÷euS–máD>@~.¨0–x,÷Xúñ¶aIhÜXÍÒ’_ÕF`ÂÞû¡‡Èïc§ïÝ6b=¡ãù±”+'<ߺy3Lz `?‚ϸÍZ¾ÐP8³'ª<¨7î]ó TÇ+BÍNC³,Þ|Óù_7 ~’üˆø쨈ãÇaÆTª=µvíÝ2”•+qrEƒ5)/$ƒ#à,·)ÃΆ:ùÛJ8K7>Œìe³¯mÜXÍZE[ÔæÀ2ØÞ6ôƒMi`êæúõMÓ£ª£Gáìîl¥T®ŒÁŠpà껬H¬^ ¥ˆàÿÆ~VÅ™_d¿Õ•WÀ¾];•{ùj‚"Ï,'W­Â óñTFftîl;Ýà"øT³ J}̨Wçúèðýê+•Þ‘èj¥<3Îì[¼M›ªpK–€Ê¹éf¹;V8ï_.Øæ¯Q#GHÆÄ w¸V-4S(„r*‚÷žC \Nà“O°Á„"¸:3¹F;³B©'KÑáÅb—¨ZUl`„ µ§jõb[ÁªU22ò¹øôSH°„d1ÂJGh¹iRÒ=)_ÕçÃIä`£wF†jS¨†E™œÓ`3I™^$lZ³h …Pîõ×O<zÜu~Åìø‹önZ´P-$b …éŒHvevÊTQÜVpðIÚc_‹Ó`—|±`™ÌÛÒ¡‰ÎÍ OOtË^@]Ü3Ï LB(öõ¦@…£†O÷_DŽû•,®^UáNXö²Vr.tþ<Ìr›C*UDóæG‹ÆÇ#ûÄøš3Ç¥¢£ùó…N¼Ùx@lÓ\Z8%zˆm†MLD](m Ï Ú/8ï#!ŒÉoUp¨³å öƒ]­N„¯¢ :þiñâ»áGKR˜kîXãƘt¬ bc!÷íRB—ju<Ùƒ ¦mæ|Ùì0U¬o¼Î ‰ÁzSÝú¨üðóî=ž!ª)ÒÕª‰­f‰XK‘jS¯› <59¢i† Išh¤§ã8Õãï”sç¢2ŸŸžP]µ‘bŠÐ×<>Ö‰*Î5ðöF$‡-FûÁ6Ø[o©vö K»hô$'£ˆ5`:ÈÅY`°ÏÖ›¼D³XK 1ôoC{Äuìè|…=ÈJ£J>'p +bÑL¿¬Çy $Þß}SA(؃c+×÷ß°™…˜QË=K_võ"S§ºÄ¶”K– MÌNzÉ/¿DªEZè’ 9ýZµœi# „lgƒ³{wÚºÕvdòÿ„h4o.–'‡Z‚Ä›4¼ ¿ùFì>å)HmdŒícŒs`Qéé)ü¥“"‰6›E€åàA\›ˆÇ3@.b°BF2%{P‚… öcåJõçqbWµÒ?âÕ‹S(fÁ–Œ+Ä2ׯã×7†fdÓΊ-ݨ|¡à}U¡‚X#–õBf§.¡`Ëá]Wÿt¤‚;¾wî)¢h|ñ… ]̘5ËÞQ‰áÜ9˜IÆ™§~7yLKnò#xy@…ë°á¤:o@z:Êi¬'€Ö¬g²œ&¬\xyÁ³V…Õ'4›–åU×®fø=N‚DÎúóO{ œFØ_tNpèOÁ•+ÂËïüD‚Ë×Y<ø Ê•iùqáž• ¢y5 ™Æ3¯]Ç®]ZZ™oÅ&ôàÁèbVwBXYÊ`ùÑZ"l ¶RJ—VßJ‰ŽÆcÙ»×ü¿®['<Àk­[«L‘ÊïTá÷à}5eÊ]Æ*v0ÇWs!³`3Þþ`¬cøw?ìéMw*å¢n]Ðú‰CF*j𮞸:¾%d{_zI8A‚ï¿GÌ_°$üòKl¤Y‹#v{ùo´ÞQk?Îî¢Ëé+² D-ˆ\;5¬­Dôlîß1’Ÿ”rÙ2”§ fÛ¶®YPUä±cèŠeƒ³sg}׬)¼JŠmZ~q¢¨–&zšh$,OGˆY"úõKϨHþ‚¯–.IšhlØ Ã÷'ƒ·èé©ùmb"Šœ[¶´—Weæ;ï Ùª ¹·wcÚ¯^1Ióæ¢tâ’%å›Öß}‡îQA‘d+`9ÉÒRt‘ÿ¥¬ž~L¤“&™!”S»w£lIn¢;ÿIQ¬àªø\Ì›'|Ô×Þ—QÁ.첕)£šid ,O؃açäÇ_aK»bi°ãÀîÃG9 ›1i¾˜Ëo…Ç×.ºôÛ)”T.ì·õ9»1x°ÊŒCÆ`ÓZ©âÎ6Ø“O çÖ0‹ùó‘ƒáƒ°C‡ Dn9‰x¡8¹ŽNK `*IšP„-¥óEÄ.ÁxùeZ±Bø*S§bÈ{ÇNzoÜWÈißÅõCåLo2 5žœ"'½½!3ùÖJ—ÆÔ£O?5GJ6U OŸ.P³ß¸õ4g’#íÚ ‡›ÅåËxer:‰ââPz¤°C³œ\¹$•*¡ã[E»úÎT¬‰î#óêN»Ÿ»„123±é…îÛ™èZŠUÏØ0‹_N‡B†4AùòÂMY.@j9J°“ ?«jUWéØfuölåÿXuë–ó/11°3ÙÓŠŠÂ=²MdfŽÇñʴωœÓ`œ !qØ° B†BèÐ+`Z4eP.>ûÌ ù9‹Ê?Æ–kÛÌ®Ssûù¡ñV4ü+Ó±ÂW1FëÖÂÃ&>5ɯ¯á»+D› =Åj#1’_Â4jvßÄGaÞKûöÂWÉŤI8Å–ÀªœO\Íšä Ϥ³`—<7ñÅÒ²{wpQßÅѯèHnwÏq"—û"sÑ»·j•EçÎQÏžðò“ ñq`ƒS§úîÝPˆöÓe¸ÖÎõL=‹à ë—æÍQÅg³³~èP„8D#ª8yËŠã¹çTn-ÉÝ-è°x]0hð22¨i>k¢Iªs‘–«`½9S=JÖþì ˆÃj„ØXè%¥¸¨lYømy’`þÕé€bŸ T¨,â{22jút‹yðpDùÔ"”³‚„ø¼Ò˜öÉà¹2QŽÍª¿ÿΙ1j”Ef-~°åÊ ÷Ç/úQ¬‡Œæ»üøðC±ã*GRl1'§ºØö”E‹WÀ.°L#“]Q>Â&Å!!h:fóR¤wÀ«ÙYyÊ,ñr&S§.EcWš{iÉ—8ÖnÝB¡# ¨Áƒm'ŶlAH´áÇŽÃðáb—0ŸOOuÚˆØcƒ³V-H`¶ÆMêFV­ÂÏEcï´ÇSø*fÁÖ‹è(Êí[WˆâÕ‹h™Û~rh±%™d åhÝúîn_±Z^p—ÖéÓhyq€žá`Gò~BÔÝ°ŒvN²Á³x1þ’nÝ”–]`k¶U+UFJ·ëÕ;öã…T5ðÎ`Íòê«Pœï½w7ÂÜ¡XžDï"øPø*fqõªp &ÆÞ§)X\ŸÔ¿`‡ëC)Q²‘É›³cG¨u>Â#Fàø‹ït3>o¶' Èù*Så.vî4˜¡·éRa:-lˆvRR>‹Ö®]Cˆ†uhçηáÎpJ±Nç»rˆÄØE°yÉ{Fü¿t D|}Öh3f ÀOÐøÑ\$G×I–K»gŒ-„3ã™GñÅlÌEœ=‹•„Ȇ|#“…RÕª(f ž r§7o¢šHq^Yê~ Ê;9mút*UŠ&¥ÐbêWþƒW±³X‘oqäHXvœŽÏóZO<¶Au‘˜ˆùï›6©|YëPݼÌeFŠ¢E±]lò½¸ïä[Iàõm‚÷¼™† UÁ^ù™Bç2§„M° ]Àvæ#@¹/\(¤‘зí¤þeíGp0ÚiEcK#òsy`M(­  ™¢-sK– lÂÖ΂Ø“ªLQ´ ‰,žçÏÇ_™¿fܸ¸¸N×=èf<úƒø;uB½kWܶŠ|8½{›îÃw¶?Äc“&¸cv¢ýüT[‘ To|öùïRÇ#Ë,š¶×YY(”Ú¼YÆZ;wÞwÆÂs÷ntÆ•-Ko¿­fÕAò%i¤à.uëà¿îá‡Íª ¿Ÿ)¢¤Ø%ÈÐüÅG= g6{„î6 †…ÌíS›8ùñùu­[£À´—‡P¬ž‡.°‡iº‡í ï XW§ÌÎ+\½çiÓòøA,ÄøQ°ßÝ´)Hã½¼DÅáY7ðƒpÝBcõÃ>¾èøž -’G‚Ô¹3Ü.$$ eÉ6?›d?ü Â0”=ÐáÊ®^Äu¼û®ðß·oÓ¥B½Kì*d)£T%°V4-[ Œ]ºÙØ­[¿†eAôÚk¢˜fÀª`Þ<ÔÅãàAä}Œ?E‹Ò˃YÔó±åßÉÍñWéÒÈ*Ùi¹)²‘-]ã+”*…~g³eOê‚EeÇŽ®&€Øúª\Y,ÿd~°p–3$šqâŒ.Kj…7íÞ½Ô·/Ü A]êtñž*$·Ë,þúKøˆ†×säÝFø*ÑÑx/rØ F D„Ùàë‹ÈfU~ 63ÁrÆ í#TìcåÉ9Ÿ™C!%¾ ºI“ ôŒe ¥/E6îÚ%©Î6?®^…ìô´ßsç --Ç?4CL$¼ÐWv  ç'9gHGëÕCù·£„9ñ@¸‘®]~<7n@ÈÍr2Ž¯ ‹E„W°3zõ^Ÿ 6ÎUçæbç¥Bô²YBJ ¤Ç矫¼®x„v‹WµäTe‘Š8zoĉPTè5D6Èà`Hi9]`¬þX:dí³£òÖ[Ȳ»tà€½çæ¡Rݹ{T/¿ŒX¿hD¥ñ½ºü:yDRt÷I¥J òQéé’?þx…Žõuùcó竳®s¸q _ÂSì׋ÖéV°z56•CQ¸˜˜¦:vMÀ;_iу©S1ßÄ $'#èS¿>v2[ž6ÅûžòtT0»šýX²áÑØÓŽÅgä Êÿ ,€½ç:íÛ… ˜(ݽ»½ñþ|Íšf"íÒp²e"šA$%Ò²¥œ9"0aì ;q|<äÀ¿<ÌR±p!ž•BVal0¸Ø<îç‡añìAôëGûö™¿ó3;è†Ý6Õ˜¿þš —íÄÅáJˆÚC× R–xÞòµk!3¥qW¶háêXI//„ègÌpìžy£>ü° .P3¸CçJÓñÉDCˆ*-¾à°a2&„ZAV––ù|HLD!¢&1>Èê–Zû8¹Œü.âÚ5ˆz>¶=†ÜºIùœW3:fÚ{»q#>«Å°ÌduÜ8ļùKÝyÅæÁ§^Bhúx '|¥NRNØ0ªUs²B’%$Û!¬­œc¿ˆ@”L|.NΣcÅÿïˆD6w(˜9MÚ"!^¶Yþ¨\\¼HÏ>‹)9š o_yK³©àé©~5r` RåË£’s×.œåۙࣈ^jòÁW_½›‹cùÔSÈ…²i¯´Ÿ ×®,ÕG¼‘ÿäóðUÈ@œÒ¤‰Œ…°áÁï×Q¤¤€ž‘­W&Fñ }ôQ¤ÔeâhMÚ&‹üV€Áƒ¥®hJ>ÅRYa-ÑJ°³x©UË6e¥ZX³F 7œ?ý„#ÌÏsQ+:W,ÿ€›’%ïþ­,0ÙY†)l«ðÓÌŠ/HÑ;…/Äêíõ»mÏ‚‘™ »‚¥´ý¸t ¿2h ;œÕjƒpZÅ×g7"(Ń$2Há ´N²m+V`kå/'c)ʲTtI³%¤¥AoJóª'NB_ü±cäW‚~-ߟp£jÏÜù)Ë—C`š¤ó÷\¨6jÕ`ZPÀ³ÂW!Ck[Û¶2RÀo¶J{‰ß}}‘²QÑ•NNÍ[¹ ÿ> 0) 'D'`‡‚ϯqˆ%UÕª¦÷2Áêòµ×ä-·r%Ú¬$ !Š®xP|ÄbëÖ8bÿκʟR¦ :ŒCbQQø'áøüs´`ˆFœ%¤ ñ©U6·X ÊÌÌš…¼€M3oî\YöíSyuV¾"e/¶ï-AÇEM²†Ò¥Uh¯SYYà%ÉM}÷²o¬µÂúõØQâyrÀ;üñÇÑ0.ÛºÓžzwÿ7<ÜlûÒ€wKÎC¨€ß‰pœ9.š“áW|?ø÷DLnØ€Î9ér2ø)¬­„Ùob¼aCSuµÀé×_£bP\C}ü×t¹+~Q×·~nB©Ãk¥Zµ`R~ð\3>¥ZáÂØÞªë_+æ»e¦ÑéÂtÊ6ýøñã‡(:Û–,<åD§&’÷;2Ž—¦;±D_U%Öc΄-?ÿuýü8{oÎ,¿÷ùó¢ÄF 4cüþ;Ÿ pÖ‰G(®Q¢±D±¶?¯"úôqµ|K]ìÚÈV­$µâZïpÑó²ÁVAݺ’ÌéýQø¶?f€2)t½z¶?l'øÈ[!ýVÁUh»ø’ üü Ä5°Ë_·.ŠâŒm~ÞlÏ?Oß|#jQ'À÷ÉB€wËž=öþJÄä7ŽˆÿŠ‡ˆ¾ysVñÕW®Nرl©ôè´CŒ£Ê»'ÒÙ’©\™¶lu}KøòKys¥o¥Qla O¼œšŠreµ°~=b©púwºT2¤Ðé“ÁÞ”ýaÛ•-7³Eò11ð~ѢР¶n]CË–¶›D¢ÿ¤è”¥¤®n²÷#üÞ,aíZ¨r¡¸~õ«l~°”p¿æw-¨MòêU¼/v*%ãÜ9< ›SÔ‚ß»t¬B~n"õÁÛþ)õ’Îì¯ñ{—“ }˜u•±†;°Z9~\Íkò³9ÒÆh …šCfÿš=ÈÊB[§'&‰[´ô mo#ﮬàÈäVMŽ9s`±J={Öùë8€ £º9YÝ­ZA’ËNöÌ8SÙ0/C¤Ì×xí5•‡¼°k9uªš´„𕆠UñÑrË–©™ý‰ÇÕºw·=>20PÞäS‡Àÿ‡`³š_æg&QrAŠOceRR¨P!õ+HÙ°(æ'àâÀ|56ÝÕ*'ãÔ­ĸüHøæÍhe’Vwxù SˆÆàc[¾¼Ê‰³ `dÊyV;¢CCd,D†ìÏ /¨Óûãï–¶o¾±w'¯_S©C™I†øÛWl7mŠAE¹SPƒF_%Mï,/ž|RMBVs³g£Š’UžY§1h:áÖìlt¶¼úªÔö^W®@:$i¹ÔËW˜Â7ÊXkæLõç½’¡ëÇé‰ÌáÈJºX˜Òe‘œ9ÏËůE‹ ^M² Ì23"Â¥¥ÅOåŽè’Èå<^–|5¸`½{«@ÙÇ nï^¡”- ËM„ cÔ¸1‚®®€ïó½÷pQ—ÀNôï/)ŦàÀ‹t@Ê8†7üQлoJËäÀï!ÚÙ]ÒZdà0dSʹ†A޽＾tçžùêÕ°K]‰’I@¹r`~iU€’ Ða­ïÆ&¸”†¾|£oy¶-(Iµ죱rte$ÙäÉH»ó—mÛP .méĺZÂ¥(ƒ5á™g$¥*Nþéö1–»ŽÛ·Aö;ožÃ¿ÚÔ/Ú¦ˆåíºx1hË”AU̯¿ ÛaÙÙ`¬r(øñLjÙ¬»„ YÞèwÆ0Ñ~k5Ú݈öË¿ÅÊk©éÄ^•ÁºfÔ(±KäâÏÆù'¶ ‹Á.]l»x,QÙJiÖ ¼4ê‚]66YQù²ª ´ùµø¯áá0’Y(±øRsìÚ%É~+YÒ4¶Æï1, ƒY B{ sþfÍÍdŽ ø±<õýñ‡íOòÂÇ­E Íîœ]v»‚ƒ¥, ñ[å隥Jé EÞ_tåOL <9<¥qQhü ÿ[ÆZ Øö`{É ¯`Diß_óÀæͨϔLlhçw£Íÿ–1Þ~^^ CgÝÍ¢ŒåÿÀÈËlÙ‚sÇ¡êõ0Ï=‡‹ûø`®1»®;¢¥N–-R§Ru°~a÷ÄzˆmÑ÷Þƒ^Ö$ËC‚Ÿ­d¶mŸ*t¬±¤µØ4’1ÍPT&­Ë`kò—;P50ÇÜl”&K3Ñ]{÷biäöÀ·9íq<“˜š Ÿý·ßè“OÐ=Ô b%J )Ɇ+Wˆ›ØN[»ŒÛ… à jÞåO_}…|®Ðd·Z`ÍøØc“8¬wØ‹éÐAƒ(k.ØM`e'‡çѥ”.%±uâ ?9ʈõ#{^‚8M‘Fç‹RØx£‰çŒ:Is㸠«{Þ?µjQPðÕÉà,°lùwæ²Æ¸}n¤ó*ÍÔP¤ègŸÁs/ZÕJÎ}±à}õUpÈôÑÝ·î6¼»t1SÌÆv8Ûç,ÿ%°ÃY¦MpµdRÞ¹C!¥(x¸¤åØê=ZÒZŒ¾}å-wt:Å¡,Vµˆº½+|EvF^zéŒf´öí¥& Ø—¬[—FŒÐ’T\Áé”åAôÑïÄ,–-“7(A]°ˆèÔÉTÚ>Œ +{prž?{°Â' ^c(¼4ÝO#I†šX6/UÏAXAXV”æ/xU¡‹ž†q®3Ù]‘±bBê™wì@Ị́©”ߌvõ*üPÒZ¹6L¯cÔJ÷ K³?d Š,_eT.v´¹6/‡E]k(MpéÒ=iJX‰m‰C íDR’ÜáÓj#$­ü~§MCð\RJÚ2Þ{Ovè’±±Ö’´ÛBeʸ:ÓÊ (-ØÒ¢ÿ´£½KZ‹ ’jÜ8$_ê××2”¤`þ|ŒE<ŽAwúGJÏ…+xàmÚ«ÕÂÏ?S©R(M×jœh.V¯F“¯+mkN ôWôD$ʪg˜0‘.MЭ›¼ªƒ´DŠ/B;¦ÈX‹}áŽñ×%'£OüÍ7Õ™Kë üýQ3&§ "·Sér! ß!uQ'À.¹+=ÚÚ""éòƱߴ]âç AÂÄCcÜΤ%é°¬)®—/üÔJ1±ûÀ§XZUí©Ï(¤(Ý\uÀ.Rݺv£ÉÌL”ÁÈL¨YB\ŽUÏžN6#;° äû íiŽ·Þ’4BEuüñdÔªUˆ·k§Á@ó\\º„D¸®jKðéG¡ÒY 6/er.å[_2‹:ÂjÓÞç^ùrl`“9), <=Ñ÷§922PESµª¤±×a•h÷P ¹–3º“dXBŽ‹Äb.äB8¹s§7ÃûªIQ%#!Œ’ Ò9Y±¦ÈH˜—1²(},ÝCÅŠòlžk'Ábtb¹úW¾u‹†ÙÞöøøÏԉ߷oúD>ûLlW×ÙÍt«¥KŸ±åØ.zûm­oÂð©iÚ”úô1m½÷ñ6”Ìõwû6õ뇛‘|˜|Oe2Æ€›— $[¹SDqº©j¥ {»­ZÁÛµRÀ³f îä'×Ì‚­‘—^BïŒ8¾«z˜èQ¢ÖD*U­ ÂáàÍw dg#]¥ŠÅº%KðZe¦]F‚y)?k¶E¥Û²2ªJkõv9vW¯b8²œÆ5hCSÕ®æë WhölÛ–?óä“’úèm‚ïvñbؽ ªod\G5Ñé-†¾ªå#) ý#6Jþ²Î÷õÎ;0ùä`î\ç):]ÁåC >ý“¼_}¬uôè!åV A¤÷ß—´ãêIºRˆNýeû“61oÔ½ý£iÓPÖ+m”Mœ9ƒqçÎŽ1yÚ„Ï:êVÅ%Kê…ŒÈ,X£±éÈRϬ͊ ÑÍs±v-nI[cÜ¡JÜDÞ‚‡! aóØÖ¬)‰“öæMÔdÊd† K'KÒ-ÎoËÁƒáþ82âÿî»è Õ¼Ð(·oãòÎganaK<ˆ±‰2 ±…ùKOIwë:||ÌÙÊÒqæ 2­5j¨Æ8Ä›¶~}4›«…é}¹€2f‹"ú×À>¿Sº¢$V槥Aú9j±a?\-'{‚líË,1ʸAQÅÉœñVyòIt8ªëà\¾Œª UGŠ@bN’MvÃ+VÄLÑîÝï_•dPW§ýƒˆ6µ"6¯Yu\¹‚*; ¹CyÏÃ~Ö,•«(#"qòøqHKÉ#'À X•h#e%SD Ú7DêâÓ¦ÑÇW¼~]*[&[\ƒIZKAÔŸHR\ö²øM›°åQüñƒe1ôÕWB.®*NŸF¶ŠMJ–™,ZXZ²sæm\“~í4%yÐܪ<í¦+:ÞäJÜA2.\€¨¬PãÕènÙ«ÕéX(¤e•*Ò¥¥‚½Dµ)®2ùU—óŒ„Cåܼ~¡Ò3Ù fEæ-·7dgºP’2ò%v³²Ы][læ‹wr£F4E “’kà »`èÐXl§ÎsØ“¼êhsg®ãùçe3à±|6 §’E¥èÚo¶CZ·vrÜ­"-¥zâyqd,zÆoÈUg]º8ßÏJ‡´®ó5kô4WÑ,ØÉÜT›ÍóCvÓÚ·Çt ½9ÉÉ8°Ÿ~*|!G0{¶CѯlŠ-JóÅÝX  /žÌú·W/ˆÊI“$u~)ó,œHùûý҄LUÁ™íè;.—…[™1çŠ=Z^$“Ñ¡ƒlò“ÄKZ‚üßÌùßÐP–Ÿ./®uý:dæ;ïHÕ–Á:ÄÓ3‡Ý¿Ÿ;—J—†Ûj11ŸÂŠK¼AµñÕWÂ9 x/ñId\½:´‘ u†h$&âþíÈÜuëVÝ¡£iêeŠ(FH]”O"Ÿ}gU³ËP®œÊ tVÀ ñ›’Ì»rf¸ŒÎnA s~–6 ¸y#xÚ¶•}”ÌaçNœlŸ|‚(ö •‚eêwórl,)#‚êÒΞšÜª:X»jZ®]ƒÊayÕ¨Q}¥&8zïïÔ)»>¼h›]FeÑ +•;›=È!Cò&Y`–/@™è› šß¶óFKuAÁ<ø šæÕ¿¾£øé'¼ÎD[}XS§‚\Kšd¯QD)Ê”k¯Ï–¤ii:!ûgÚàY‚ŽÌÆ7¬Uç̓…üðÃôÁh#ÕÊýt¬ ],‡`!Þlûö°ºD\Có¹ðù‘™‰h‹Ù‘´4ð˜±ÐÙp—a[ÀÞvJz‘å[‹j/ñ£f#S&EÉÛo ªh:x2'…Á¶»c[·æü[üi:]„ô±®`ëºreúýw­Ö¿v §ªzuÓŸ‰¯»8ý+EEŸ¯1ÎC^ƒ·;8o½…ÖicèFïÞNN¥‰ŒDˆ²];ÈÉ~ýÐg­ù¨PëHH€ÇmÒOÄ?ä÷Å/KÛšq‘^„üeÍ5Ë{"8Óæχ’%c¥vUÃO ªÄFTÎ|6Lœ¦S[‘òýŸºë:Œ'ðçÏš¥ñmULÅŠyû?f-ÝÃeÅݵ+žx·n¨ã ÓëˆVö×f°:Ù²…ÆŒÅ+ös·mÓÓ©M(¹Ñ–Ó§!BÇ×øÕd¦‘w9:Ò@öºüW¿öšÊÞuëÒž=ê_ÙX¢ñ†´¦v ÞÞ–¹4GqéœË<.âÒ%°5²Þ·2ÿBXÑ”-›·^=#†R=èJ„í_¾yö;ùžž8ªo¼AÊV?ÑN¾ëiÍøxXŸ|‚Öú2e0æã›oàÅëSþÛÄÊ•èÌMN†/ÃŽ€v¾Ì]l­O§*Ðé•uK—"à,Hßñž‘\XΪ_X‚žÝqÞûæô:/A7%ö¶›ûw,g§ÞüùÕpø·.\À0“EðË/ƒ¸éï¿¥Òäk‚Fòü$%ÚtΈ÷ZµÐÀȦò×_ã‡ndLZŸ¬ÇƒþÚ·Oë[!:ÐczҤϽâ]Ç®¦Ðn>ÉCÓÓaÜxYn÷vÖ&*Áž¤ò”¦ƒù+V`cçZu‚èR<Ã¥+°Ù¶~=df‹øÙÔéеp ¹`Ñ*Í~»zqv´gÌ@(òÉ'Q¬ß¼9ZƒùáGD¸«%i 7n€éè½÷´¾¢“érAº(ÑuÍE§N¨dŠÐPäPe?ò÷GŒÅ©ÄÁk¯Aܲi0z4B°Û·cï+mµl)Øè\¿A>Õé@ ÊÖA¶÷èQØ9S¦8Ù¬:ÎÿAéDµˆ¾%R©^ŽÕ={ˆ³gã³^æ×ÃR«}{ð%±üT½d‚/ÈÆ{Öݺ!eãá涻XB;æN)~Gqü8¢¯|$bc'ׄ8‡—çį,½lF¾J(fàMõ–ÜL+úø=–µ¥JáL°k5|8"Oì.Œ‚vm‡cӯё ´_,âW®àD7m*¤Ô ŽÖ£-/²‘NÄï¥:‘1žœ »zÒ$lì¢EñÚTü*R©~ˆý‹á’K&~Ñ {.Ÿ{Y’‡j#Ú›b Ñáñ,}ö¬¼ŽBÞÆUªH-®NKƒ—ôý÷Nüê’%Õ8ßqx3žN— ý}œý}U‘ Œ-üµ¼Œ«”âA±¹³Ãt“»qlð^¹‡Ánø›oRƦñpž?®ÁèÌká¨IÛ«E _Fµléœ!-Zf ãÕ£s¾MM¦àò´ï)¤VåÃË OC~U?¶s$—vïŽ`µ=ˆˆ@›Þûï+EP hTr)Tsâ7äò&ºp UÁúñçŸauOœ(µA#nfnfÝ¥5Æ8|aŸ{ ¬OŸx‚ú÷·]Ì|ñ"jž8,%ªCI™7É÷!ò­EÙZ¤/¯]ß)¦êÆ6Ø~M$h|ü÷úùÙøØ–-ˆ²æm¥OJr9!vb9†1ùƵ«¨ V”=zàP¸8gÐ~}ž¶µ•´–Lðþ(VìÞ)bÃrüxÚîöõÅ©8­ã7äV¦à*tK‹R~¹½z¡èB+(=˜’½BÖlÙZÒ˜üL>ÿ8AABV]€*ˆS§¨ÛƒßGeõ„ ™²¯ÒmJËòEìBšÀÓS›á>ªcçND,ûöE}©CX²qeö¼êÈΠÓQ\IÊÔ¨síûïÁŤ-)ʲeÈ»I¾‡1crÊ¿hJ */ÛµËÍø­Af®1úÑy^[àŠö 6þ¬)vŠœFzj…”#êKT–_‘þy\A‡~w»`ƒÁ¢Ø´ÉÉ+ *„—,;“‚jSȃ”®‘ª=tHêÜpK`‹®}{© z2f¶lišÓ<}å¸cÇÊ(9öû9 Å†ÿ 'ªÂþŒðEíÁ–-YðžT%^|?6|w‰èÇ{M`&{'«>‰¿ýï£\232Ð/¯n7ßíL ¨CåP¤§ ®\ɽ}»6«› <¯ÉQãßE˜4)üý7ªerŒ‡yr QM¢ÕòÖµ‰ë×ÁŒ÷ðÃH ©kùGo£èÂtKƒ‡„€¥¥ä˜¼Z •eãƨ¾s|¸Xíªel³´ô­MAåè†F¼Ä¬J^~Y_5cÓ¦áJFPèÆØÆæGÁ>ˆ´¬G.ŽÌ¤[(¶‡ìuí; mÚ Zrà€j× z–þi£ÚÕtâ†ûBJ êFØÙüé'5 )}|0rݽF5)¸"ÝÂ9f¾üSW|Ω©˜ïï/{Ýï¾}or9KóãÄ,øæÇôÚ!²z5¢šo½¥Â¤’¬dJ)H礿b™ˆŠBÞÇ]ÀâqéR¸#G ™·d ®+-ü™×èHU ¨JÚñþóÞ©VòÁ ¶nEq‹L~{ö>êÖEW×È[4?Ž/A}¦¿Ž˜~ó€7üäÉ0ÅÙq…2åÈ ¹çº{L™™o‡^ÁŽÃóσOIP5ˆ‚wÞA §sH‰¡Ð ´¿&eiÇâH]h¨f7`ƒË ­\‰GñçŸ(Ÿ{ôQZ¼XÒºfqbâ™»¤SëÛ¸8”T¨€à‰sˆ)X7Í¡âÀÖHt´íiˆÈHt$±C·|¹ðªÑŒ ½8‘ºN'KҞǵlp`ÉÀ&Üo¿iv6qíú%ES²ßºĘSWeît…*ˆÚ@±…ig'-ïÁ&ΟéSµj˜Væ«•à ruªD4™ƒ°ûÓºuÓ¬ Ä&øõ gaÆ Q¥’ù ¯ï^~%ÎÎ%¯¶Zv°³ðÒKnÂóñqš»Ò.°SÙº5$MÊfvî¤òå5)® >˜ÂKÐÞçtÁŸi!!`Z¨ZÓ`íœØu¨hAC4ÚP NN˜0AcoÅ,ÎCR•wøÔ©wçÄKÃÁƒP²v†ÁÏ­§¸B´Çò¤'9`QÙ±£{šŠcËô÷G×ü7ߘ×\¿üJDôÛ~\¡ 2äW‹nIì ‚ƒaM±ñÀÏÍzñÎMJ.D1¹Žî 27KX²uŒúAx8Î>[•S¦h9.œK£F¶yoŽÏBlêà8)÷dsç¢$[¾fql´°c®b5‹‚E‹Ðèj½ô”e5ÛáÚª•‰äW+Йè4Á¡Cè;`Eóý÷vaÈçA¹·¥vï À^0{R¼ç¿üRgÈ®oŠ-H?Ⱥ! ص ÙÈHoÃ!øùá ªÕl’žŽlݳÏÚîóeK‰¿æÂÛ؀ΡpM᱄À@tÃUªDŸ~jÆŒ9Q…v ×ⶴÀÅ‹h Ñ·n¡ŒÍ¹§žBi¥~¦œó1lÒÉÖü¸“MÞMédQ:%ŽìÈ>?Žml“œG‡9gÐõ¨ot4^Sÿþö&)‘ûñGW×uAà åF® “‰sçPzT²$ÜäâÚaºZ†÷ŠÓfpR|<¦RÖ¨A/¾OJ‡¼I11fš4¥'ax¨oYJК·äÒ%T¯X¡ñm8ÖGO?íjg®—^Ðù|ð«W§5klR4Ž- ø‚ä­ãr#³`Y ¦(hj—Z¶ ²£5cüù7ÞeJl¬óKûù¡rÆÑ@"tžBËÓòw\ë[qgfQPéœC]»6NŠ+oÄ]0jýﯟ‘Ò˜W^ÁàR6,Y­ëÐû¶¾Û>}hn$ÄMÕún `‘Õ½»6”?ÿT™¨¿_?ǪŒòŽ–p ¼-ëÖ•:BÝn§“_SL=i29ŠHǖ籚´÷_N•€Œ ç3Þ¶--\¨‹§*óç )xæýÌþ,KÈråšüååÊBq+¶Ô§kh©>:¿fÎÙ£êcëíAL ˆÚÔ¥ýaßÓ“6o¶ëÃ[¶ $ ïh —0ctâìLA(øÝÿ?šè!L9Ñ'®…QrAº™7iž–†WÉ°|yä&øMiX(;w‚ƒZ-(rrð`<±V­¿xQµ‹ËÇÅ`:T–ªРÑ¡C&ÿ~æ F2Ž-kk7öa5©¾V&Ç-X þ•Ù8©TɆM’€­ˆÑ~šÉt–µ—Ž£#ÒÍ8¢6Dz¥ì`z•ö[ö5X°äd÷í¥&M0„ÏŽ{¹––pö,’†."1ñ¨Þ½sìI>VòǪŽ#ßÑ¥Bä÷rqô¶mÔ ‹Y½}Ê”ŽÖ¨ú>±œj+Và´êýŸ03-=Þ6–:XAt놈0Wø³/Ù¨‘ì—–O{êÒ•Ât£6cFíÂmŠ+B§ÖÚþà­[ˆÂ}ò "9Uª ƒoÕ*±#BDƒy±bÎÈ7ÞÞÞÞ˜±Õ¬j zõ‚ÌÔ!±˜¸}‹ö¼@— Ññ9y~ÎîpŸ>¹Š²mÛ»¬Ãl¡´iƒH­¨>’uëàJ®gÈÅÆàügÙò#íÞÝ|hèÔ),Í'N\‡›¯£FÁ!ÒOÔ(²+ê½^Cѯqf6=àðo±mÆ.'¿è²e©A¼Ó={¤2þ©…zõìågézäxYYã—)CÏ=Ãÿj×#ðúA :RŽŽ–§ËÁ¦ÿÄçÚÈs,^<ÏßÍ ¤kW EWJ;|^çÏ#¡ ¹½°4®_ß”m鯿°ôZ;,ÁovÈè<›ý°Ò·ŸBËRH%ºêTå•PÄ–‡Kî4X÷ùúÂOoÑ‚xbdäHXžš ²=z {ÚRSaI²ÓÔ¥ T›ÖÇÓè%ì£.'LcW'{ƈó«6iïc¯Ž›Ê¯ÝÇõŠü_Mpó&B|?ý$c-¶Ÿùñ;†ïY5³îyì1”kʯøÖ[Ô³§Ž8L²³È«Ê3üFk}+F¸Nét§ Ñ+D‡]½ûìl Ì™•ß~éÒ(™;ª“m3}Zbl€a#ùàAP: ˆŽÅ’%¶3†Ö¯wïàƒu\¿DÞRd ¶w ë™ü Û)SPó¢øET®¬>U…ý`"ˆ\È,ؤdüÂœöb$§·Xf¾ü2ª¶4)Ù²„ãËèl1òªAW4 Ș °y?a¨wúèq6…Õ¼8[[·‚rª_?ô‚•(ôúë .[½nŽ¶"”7ß!«òF´èÔ Ù ¶œš5±ÿÏ?ëWÈ«‹¹t®í­O)æ5BL ´ ÀÄ>ø/‘û­Z™~’]vvÕÕÁîÝ–‘sª‹ °$—0±kÌfûkš4¤§Ã“b]¨«mŸ‘DÏ Òïc­o%›.¥HZß{ëÖa?¼ñ*äÙ~kØÉ£… Q_!â5±‹Á>06l@ЕI–Þ-[B6+ A¾rå`oߎ€Õ½‘ý·×iÿs`ÃþÚʧFŽÄªVÍ‘™ü®š7GC¼1øù©3÷cçNx(Ú–¬+~;G&–/Ç_]·.âäZßkß¾0ÒuV4ö](B~žtí¬f÷pf…”Ôlu2h4e?þˆ!›yE‹ÂŽQ÷«P!ì|v«YoŽhäŠ8ó|¶•pÍÅ‹8ä÷•œT²ˆÎ#ŸG(ÙÚdeÂ_¹]_,3Ë”ÉùžX­º œ8ÑåcÕÆrCRq§9ð_R»¶Ônk>Ç£ÊôäI¤SùÏÿG;2(öÍû÷y¦®ìLÆÍË´¿ê7ü?ÑæŽxÒÎîÚ,­+xzÚ¦¼—Kûê£Ì2p’Íϲαòeüõ¸qô÷ß(Ë|÷]— %Ö¬Ael¾"yy`5Ú®ÔÉæqqàéÙón1äÞ½xšÒ2>ùÁ2sÀêÜYG”ƒ¹8< ¦æ~OÙ,Ä×ÎQ²%ÝO‚Â:t°·²Èýð‡!:mßÉt¾0ùÔðlOæÆ-ÉPµgât_¾Œ~¶âÙøtlü׬‰âC Á¢²[7y!D??D‡~øÁÔÇY´z\Ã<#ËÌ7Þ@¹­Z\Ç*"õ ù< dœ¼úvß7iomIkéÆY«,roœ'ª@tß^ ¦ƒÓù¢tÒ&FƒÏ>{÷Ùê)•o1 BZj[¶`Šy¤¥§y¹*UhÇóÿÊ¢»U+-sÖ,3F•µ3ž$ãØJ .N'*Ñ% ™Á;t³]}Žå¦øµt™3Ñ}Ïâ+ºó*íîNW=È· eºd0ðáîÑ#ç{¶‰–.U©Yáë¯QQsþ¼×rJ“œéŠöŒ–`yõÊ+OÃäw>E Ù¾êÞm)23‘5JÆZsæÀTs´ŸÅÿ–æãÞðâ×­Óø6¬àNí{Û>¡$E«W—å×›|jªvµ{laÊ ^‰Fö-ò}V¥_MŠq=om v[ë×·ð¨Øô|î9{ QØ(mÚ-Úê©;wPsس§ð´8?Ö4  ÌÒ ¬_™©ùP‰¸ß|£ëºå›±´·])HÞ (Éu;óE§ ù*Üؽ„t­:íDÈtŠ,A!e(TÔ(Õ+¬N¡yûm»š¯OžDeø—_ªw_ÎbÚ44,9Tmh\Ó¦Áâr(+äââ 3¿ýVøBö€í‘#цïFµyü²Ö,¡e)©8¥µ#Úh¢ô©E{itsî€Þ½õÈYtm,]ª‚Z\¿‡à¸—¾›> ¤Ù³µ¾bcq¢Õåæ5vÌSRèµ×P¤$­òçÒ%zäš7OÒr6±jê6oÖú>AZ}=…†%ÿSαOdo¦DÓ5-ÉŠõvp-Òú&þEVø†ö=Œ`ËÙêtN R&RS‘˜`£}þ|ªUKûú“«Wq3"|XEfž>ë¿ÿ¾ì°Ã¹s°™õP£¥ 4¯{Ê·ì› ^JË‹RRZÇ®\GòÿÌÍ*–,Aw´æˆ¤Í¯Ò±¢t®ù¿EéZ‹'À~Ksê´ÙoÓFËJ˜›7Dd›-ÙI”.M¨˜ÒJTvçNmVÏ+W0Ä߸»Ì5E2}Z‚¨(kV Gþ?˜ûã]ºh¶zf&íŸM[k«êH]ŠúU3ªºøñG¤<–-»û“;wЊ@¥eÛ¶ôé§B.ž 9\­šbz™8|Ï\?å=üX¦OG)‚%ªOãÔï]˜BçSjQHΛ…iï:Ú®°*yôQ Ö=³“v¶¤3…)º8éE©܃*HLDÈÓO›©o¼~˜ò›OÙÄm×K"”„¹´-Z`çØS™)ÂÎÜ´IË{0AP¡'Lp?QP¶·Éù>=v}F7 Óuú®'(¹4ïЊSàÚVÃ]lí~Cè®"ïFtþO•ÖÕ|`ùtŒi±/;4&‡Ì95,-Û·§¡C…dÊøÏaÀfs®4Ð\f¢Çjõj-ïÁ Ôµ+â!úäl7‹ŒK”èA1GM÷'¥•¤c¥inIú¾íÛúŸäD«—j„0-‰ÌM‰½z‚öõ¡Cå0PÉÿ1 ›MÙî¦MÀþ×—_¼ٺÕÆ'׬ /gKË_«¹ˆÚZJ*Я¿šþ\s™É¶=ËL­¢©fÁÚjÞ©“©j ÒóÏçIöŽ‰/Wwšö}DÇ«SDøìG¢}])ô{J½‡ ;Ïœ^¶Ù·Áå3ˆ|£è¢’¾åiç‹tdeh:¡F(XBN? ~ ±læ¨Ycow±±8ƒ'j/-èAfÆÅAƒôï¯åpsK`ƒ7k7­»ÀJ—FÜׇ©í"œ&Ÿ±t°!-áy¾8zœÞ Ó?Qºýü]úÔÈ~\±bæ½Þ¡Øý0†GÇ 2¦ùU£½/Ñ¡”äDÓjwU¯^˜Â£.SºÂë躔 @¯P:5§¡™Éæå AÚÏ2¶„cÇÀXÂ^qˆ9êWÁÈ/ùi±y)otRÆM:ñ'íF{QP9d‡=È¿4íö¤]mÉû}:¾„.¦Û·T˜®]êf,hEƒ?#¿>´§—¢K…)¥…–¤½uiWòÿšâó Ü`óï×_Qs8nœa¸¼/Ù/sEïÝ‹ÛÓUµ¶ ʔў‹ß#ÛrõëÛÈïk¶©Xß=ôúLåN,bó–pcb`–¸A?PÐòn‰Ù¯a¥)¡¥ [¨ßÞÿínM;úÒ?iÏÏäwÄ/üZc;±)0³(ëÅm¥“³(è]òy‰|êSÐC^O)tºùW&¯ú´ª:}ߘ¢¼(KaɆêoÕJýìŒ1”ž>ç†ÏnÙ¢òÄðö†RÐ\f2fÌÁsZèÍ7Qâ¾v­´@t~ ³G<'ÝáÖuŠÝMÇfSÀÛäÓ–=A§¢Ë%趇Aúåýº]€¢ ·ýUšVzÒÊv´þ}òú‰"ŽRZ(]ü™2ÊÒÑÖt²],iñ qèXò-G{ØÖmN{ûPÀd:µš®æu®YÓõî­ÑCÑ ØwûàÈ¢•+elÝ%K0°ÛÑ´sæ CÇêUÿ8rD/2sáBH$6Ëu Ö/Ï> wvÕŃ]œJ•î^²;Õ¨Ñ=ÐòÈÀ9ÊÚM—¿¥Èþt²)EV§ø”áAg=è@ Ú\“Ö·¢Ciߊ8áRNÐË ÉÖûìñ¦á3Ŝ̉ƒ#™k'Øû5 ,êÎ ýÈÌ­[áˆ._®õ}X¿ß¹s©bEº»2ÉÝ>(e³eË¢Á—Œ[h`!:šŠß¯ƒ<üý¡_Ù?šy@4ÒÓAÑ`OˆOP÷îÈüºÑú‘™§N¡züóÏu½ÏããÑQ« Äß'‹ÍêÕñßÿàøÕ°µã¯*âìY"jÔ õë5;D.@Á[÷Y5mŠÒ&7õšô#3•"ÿ7ßÔÅd:+`]‰&MÀ«&ÇÞ¡ ëE]ü>k¹‰±Çµmˆäd8>ìþLŸ.Áý±;²Äq#àë¯åÞ“ÚPd¦ö[õ€8Eç¶zv6Ò@O¶l9xz¢i­uk]Hx¡bMW2“Á›÷6h}Ž€­âQ£ð´8=Äa(@1â‰Æmy÷ ¦M£×^3óóeËPÍ­ój5Sܼ ÛŒeN›6ZêÜ7F|<¼Âöíá!òmwêDS¦h|KšÞdæéÓØ<ï¿oq¨>ÁbóÛoa!7o Áz$çtÚ)fþò}å/W ¤òåÁ¶è6ˆŽ†WU¹2¨&U/ZýûQiùùçwSüJjÔ@]—V`çTNy„ÞdfRšUë×K½"¼yþú sªUC»£Y‚¦˜ÝWnH`zÏáòe¨Óü£™xËÔªEßMŽ,X@ÌÍÎÕøhó¯PÆŒQ§âB&ؘüæ(­þ1ý'û+jSþ¤$²¥õËéMf’¥R%xY0¤ÑÉ5rq 9íh Å=¹=ø¤¾üržå¥K9-/,~Š_¬$jÇŽ˜Ï ;ÉútÃôk°pŸ359nö¤zô@ZÊm+Ûš5e÷«*ÒR\GžYèPf²ØyòIP»ãÖ"C±`Ù²(É}°Yit¹ …¹UV7øî;<È/¾@ùóϣʃÝY%!îå…^=¶-u8HNF ²n]jÙUÇî’Ó1, dzqš0„Òª5‘– t(3oÞÄñxôQ:áÎ4ÚJ Ÿðõ¯ÑÑ´¾wE¯^ ¿?¬f~~FV Ÿ_}æJø®öî‘ ë;}Ý/P™‹ìl4°³\Ú¶Íö‡Y´o/v y.4”– t(3k×½]´Hu Nƒ Îcô¿¢ôöÛ´oŸ{ÿ-ºëS½µ ž?„›” b„º>G´Ø‰³g‘ÁïØÑÚ9öÜk×ÞÁwð ÆÒR>e&»[ìδj…ùªnŠk§)Ƀ·oÉ爽›I“èøq­oËýÑ­­[§õMšJ¿ÿûŠõû‡j2+Jeüò X‰ØVqÔ†gÛ‚8¦–Ql·k.-èSf*ì¾üø%êÓ³ŽÀžä[ïîÿž8·¥F ÔþðƒÄág÷ø1j;¶•…Ý»QˆË§¦GdvܬÔââáÍé4±õòå0þ“„èP@éð–ðëkÚ‚‘ÞÙ[”ÂWäûq62|Ö*VD¯ÄÂ…¨þaÉ’<œ92ÁZoüxh½&M õî™wÇ{µjèp1‹Æº¬kW•£OºM|W>¨^#cdeÑW_!EêF=A‘ó(¬¸µdf¢Ñ£<ö—^‚-B5ß“à-Ú²¥ÔCCQgûôÓˆ«Lžì…öCX¿¾:aa>ªÍ›«–R0ô)-(\p:á52ÁÑ£T¯õëçÎlhMÚÚÇ®O¦§#ZÎÞP™2ô⋨Æv§ö-%ã±—½ctËÉÑ£q.î±ÌÝš50,'NT“tèâE\ó¯¿\½ŽäÒt§Á÷Y¶¬N¥:Ë…þ‚2=G5SŽP|AJ°Àço ׯÄ~ûmDÝY5ð_Ê»å;¡ª€Í˜%D7^ºšž=q ZµB“Ë=™§ã?“ÿÆgž¡C‡Ô¿¸Úš\iÜÓ¼|ÈQè6n@†úvöÈ^xA¿µšgšÐ¹²ì–;ùë,$hêTäÖ+WÆt_¥sçÔ¼CwG£Fj–O°}Ågó“O @X÷ïO+V¸ ÷ £`KcéR(å/¾ÈfÉ&Íã;9’Æí¤¥=ËL) @˜|þ9ÌN}á]*Jqí‰Ê½NäÚ0Ý °÷Þ|;ü±Ç@ÈÉVèý691?z÷6ÓaîXn;†ÄÍ+¯ä“_}ú©{Û¤Œõ+b C%Þy‡^}Õ™ò$w”– ô,3é_·‚™®Z*¤°b†}’Bô=‘Õá¤öƒ/Š’ή]qÀ›5“Ú5÷©å9aêÃEZâìew럑wÎðáP@÷Cº-5±J¶Ÿù¹Éi(ÍÈ@}Ë´iüŠ[KK:—™dZW­&ïèd¾^P]ÚþºØ%²²pðgÍÂP*Þ`liwïN3f /ïÆ ±Këluaûc¬e¢¢0OaìXdoK—Æ7)‰¸û‰Æ™k­Z5HN˜ÆÄàlîÜiׇ]oäa=¨è_f²…ðá‡Ðž³gk\BœE©tEnš;:yö?†_YªŠ‡ûôA/ð¶mzQ"ªÃÛ¥¹fqátèäÉø›‘5jÀ a«rÿ~í§{ËljðÁŸz ͹šàÀ„Û$µS¥‘‡]Þöz€Â&¡s±I]º`¦ =Œ‚àÓ—¼«i¶:ŒÏ°0Z¹ò³C(¶?;wFFã—_È×÷‰&%Ü-;‰íÛAžÆ.ë‹òåaÒ¼ú*2¼ î+3ÒüˆØg•ñÃÓ%±;ðì³àÕ1 ‹-Ù<¨]³:þMMÆ–-HŽtíê|‡—+8]’|ªÁºVÀnѦMpØÌaIc߶-Âw|”6oF«þ¥hf&â®]8}'„öð€9]½:ÊþGBû3Q:ùª-Xüú+Ç{ïéÅÅ<‰ËüP½Ø’(›LNÄ·Á-d&®™3a\M*•Zóüt¶0ÝÖ=ùal,šeæÏGÎý•W ýÙ0+Y Ÿ·ß¦Ï>CviéRÄúöîÅ Û³ga±Í ³ÄaHÊÅû Nô˜18el7²T,V \@l3³%ÉÂíZøÚþþïÇMáå…ÉæmÚ@êéé˜cg (Å ;óÇU¾¬Óp ™I†™M}ûæP¯ÈI FÕ¤Ì"D}‰Ü°uŽ=¦“'Ÿÿùgd6YX±UУlц áÿòK/ZßtìIË•y6ã-Õòñ3g1Ëò–/_pÐ œâZµ0¡µ@3_üs6}Yzwê„O˜€%V¯FìÂ3ü´Ýº¹S«¬ðëëÜZ ‚åXÕªw;¯…rµñÆã‹ÿñ‡‹;¥ë\Ÿ”&8v »ˆôõëÅ6eDQbAŠ šET•è;ki–ìoß_~ôh xôQ*\ؼäŸ×¬ ‚‘a²²“ÈÆOT”jñ´qã`…þ2D]Øðfq´`^9è Ø·:‘½f \maapLDStÚeƒ[˜šd˜y׬"x|f!¬7mªñïÿd9ÕãðìÇ’%4dˆÖ7¡5®]ƒ)^±"¨Vk«‘ŒQ£àJ°è€ÐP(‘5kd¬e'ÜÅ='CIÞÚµ³+gG—«È0ØPâÿúùÙ¾:Å• /}”4Ü'`s¥E ­oB;ܸtp¥JÈì¸ ý놷k‡n_98qA9½ÉL}’™;,óç£Ò¦O( HL„jRª“6mÂ÷ÑÑV/{~-E¦,{C÷.^DÍ̽ÝÉhiièY`9п¿6¥ Î!× gQ_¿¾< èÄ.”´œ=Ð3)œY¤¤äl9 bsÜ8Ä„r1{6x׌# Ë–åÍBzš6uv»ÿÁxÀýÆ|»•óæ!4׫—u¯G˜¸¢‘‘#ìU©kØ&ΞEãë¯%-gôL g 7oZ›ÅŠ!1› ¶bžyÕ. "" î ÌŒ8ºæAç‚¥Üô0B£FnãÚ¸ˆôtŒkám÷Ê+¨òr#°e¶.ý76ü.:Hè4bbÐîÄÏPWp/÷\±Øÿ\³á>Àœu3o»~ýÜ̪T`3#|çÚü?úHÖ âÞÏ='i„ºýpG÷\Ur†qãðõË/h7¹‹ [é|AÊL'ºEô;‘.k†ïU¬Y“÷eÜ+ˆˆ ÷ßÇ!>Ü-ç•XrÃó#%VߪUâïé_\»™¹d‰¼í„·Û‡3g í4È;;èúûyÍîé>«föUï%ð_ôæ›ØgãÇË‹ï© ënx~„„ $“Ò–u{‰£GëŽ{ܽŠÛ øãkŒ’]»¢·ïn/Ef<Ò=§H¹µÿüª BîØÝ‘•k¹E Ô /Z$•AE8Í;´r%˜dRK]¾ŒœE§NzÜ<îSÜž”„(¦ÉÊ0Ï4¼°wéŸòâïë?XÆ“Oº_*ÄW®`4‹‹—^¢­[ݸ¬T)JwšwhæLtÑÊìë¼}µƒMšè‘ÐMÜóyórh¼ããáÕ¯OEŠ Ù‡Íä<÷žû„/î"z/]-H7¬ ¡)S¨^=HÎqãP—ûŸä=Pp°œ\¶ ̼W^{ VŠ¥!‰n ¥ÆR¨ai ¶Ïùà¬_ïÀ¯lÙ¢ÎÒ±±`9–Cqìtij*hÜØÜñnJûÛ{ ÖYÓ¦!_½:4ûöÚÎ<½÷ðÖ[šuº]¼ˆ¨7û,'»w§+À•qïÁÅKçÀ"ºreLš°ìþ©Ûó¥ÿêq·}ÎÈN…yyæ‡1<ÞzÆ°ùû÷Gg‡üÈö=‰™3e»o§NaœP³fØ®ü*×­³ÖíàÖÈ5,…Îß±6Ú{ÌÆè ¶E¿øgÊ×WåÕùåÖ¨xœž¡o8ÛŸ’Š²À¢ÓÉ+\º¶8vßø/m׳#"T½Åû ,¯ºu¾Jf&oÙGxâ ĸÙkcbibæ½M K †—k¥Š…ùСyèkÕ/ºy3H;5øX‡Ž=tàl9:ñ2Q¢G‰\›I—–†ÀË{ïÁ[¯WFŽDm“[Œ²ÒØkóôuñ“'A¹Ùµ+´[óæ£s?”@(±{­ KcddÀ’·äAHpœÝ…¯RŸz‚ÅyPºâùm³ñy;Áððaô}t耜oË–{úøèzdª~žŠ|Á.ÀêÕôÎ;°$k׆F[¿}(÷rE¥¶†¥1bcŸü'oÌi¢'àF|•zóÐÚÐÆÇÅ.ÁÇ×.”$5h€¿½gOtÒùù鎊JW` Ó•‚pVX'N N2hø‚x×ñc_°àþ •H΃;¾%vsç7ñ­Êè? ¤@?zv&].L¾{]Y¬\‰²çF¨tijÚ]Elüœ=+ïÜl™³AîRS1¨wÆ ¸ÛåËÃ’ìßÔj¡¡nLä4ô®´Ž%KèÙgQ¬¥Üª&±7Á£=”ÝäÒš­ž–†ý<{6&V¯ŽŠ‹=Ü´ÉÖ àû£GÓ¯¿Úø ›è°‡ A—b©RŽ±Z·.ïÄ‘û ú WÚ¿¸¢E5¾Uw i*ÐÖC«J[úh³t~ðç“>iŠ«TAY[YìȯZ…<Åýf#±ù‘?/põ*¶ C‡¢š‹%$êï½×;8ø¿ø°ÕV D –7ÐÜÊèÄ絊‡._l^?B©”¤W_øÒ%ÔîNŸû³n]‡gžÏ”)´|9,«{»æ“½¤—_&//š?½ümÛÂç-ݲ%êR.Dê½Ô¢è"ÜKT’QÐ’©ªUua »‘{NZˆÍ—)¹˜a4äDº¯RNIÁ[³¥òýú¡a©LÈV­üå²»k °Ý®ƒïúu„7mBµÏG!.Ñ ¼l{´khvºYrêF['M¡:L‚–ûö!tþ¼¦÷d€âž»‹Ì$™b3›.%ÿŸ‰±W>JðrbÀV(o6vH§N×÷‹/¢‚mÑòåNïÖ îêĉ¨nb—ý}Þ ‡#5ÉÖ©4?3Ñ^wûvpÉòÍ|ü1 : Œ|«|ÃõëãnGŽ¤ÿý6l€jHH@e‘|~÷‚ŽÂ,—;{åÏ=§‹q<Šéë.!MÄæ™9äWêž-Wfi ›mñbdÇGÐ]ûôóôĦ-R„ªUùÝë¯#Q2{6­]‹Ä4+z'ZãùWØ·òõI ½1cpY¾8{[,÷ø¿,;vD“ø¸q™,9Y~òM^¹bñš5jÜ-;ù&pSQiéžù$òþäí¡(!M]U?Ú¡b3¼*ý5@ý˺XıáçïËó»ïhìX ÝkÞbªP!ll‡¾øWX/7k†mÏn5_/ËuÞJdƒyÇUÿæ{rÙÔ…=Eé7nÐSO!,£è§úÑ!ˆ¸í”Š+H ÿÅÄô÷ß×ÑñÑÜ.³£Àþ¢ôˆ3ýüÄß“Ýp¯LP.Ôu@Žv¤-©s©ÿ sç"?þÈmEåÿÛ;ÿ(ï8Žk£l„Ù ÊQ­"÷OíŸ ¤2AûÅ ˆÑB,ªE6‚¶þ]2úZPDŽXöÓÙn3¥ÂÊCf%¹œéºZbš¾÷ýöØwÏwÏÝ=Ï÷×}_ˆÜçÝçîž{?Ÿïçóù~>ÉïDåÌÞÍ£¢\&ˆál¢cêµ[4¸§ªŠ]“u¥ñÎê-)¡µRåûTÌ1,ÙŒ;¶yï;ô¦bh/ ZùM²qç4–œX:IŽsE¥2‘NCC´´LÈ<‹¨UÜJÜ)¡Æü¶XLöùcœÁ h†= ›ã)WWé ñmìÁ =WVTxg“GÈÖ;(Vb•Í`3ž¦¢Ë*‘mNøiœ!afÏVX7â@Åb!;ncoh Ó9>ôÂ,Oaš£bTÓÂz nŽ´ß?CmN”ûäaéRaÃ}xÂàêJ%|pŒËËé¦`9y©Õ²c4¢œ ‡Ð:õf®›7KËò¥s: ÿzÿ’Óev¶¤º¤zT“1ZVèÏ}hJÓvw–8@ûè‡ê9;~7Þ=ª'tpNå?~L[ü­\)ïXO=¢šŒátªVGl2@¤2;[íz$tìðœVf§·—&óó©xʉ6QM ¡= —~ ¬{7p¦ @É•ŽNQJ;bG‘%9Y˜“åyS“Ü ÁR¢åcG@ØRÝ(§ä*VYd}_ÒÒ´ÒIÈ4*¨¬Œ¦$ïd¥h׋«ï¢r”]Éîk8 B()Q£²H¿¥·Ù6‘w;;›¶g‘E£šÿ´áI*Ú£ÜÍ,Õ夢‚6c—]—Þ i˜wïÒFý«VIѧ}4TìE\ó9j²ÜÞ™9œF<%áömÚ"^6,ÑX'!.¹ã"•«Wcþ|ZM!3jõ"ŒÇ•oãùG³Z—¾>”dÊ°Þën;b“;1±g iÊïÛ°5¬ÌÍÀn ¦`pÀL:æNŸSÄÃ[Y” þ$CžäŽ{ȇB4sÇYN¬<°Y; u brÐqù™vLn]¨¬äý¤Ì™L’![rÇ=dUžŸO 5ƒAѦDCÚÀf_ºSÑÕüêÊcà²glB<),¤¹r>$•3ɰ•ªŸúûétÔ9shëiù‘0°ys%ªýÏñô›Ý»©fúIÕ#> WºáàAy…"Uƒ·Ð°“ë3ÚÅS’7A.]ò~¸Or®¸¨®tùffÒ“lW—hSÜ!CË£¶ Ü{ƒâÚ›$¹ßâ!­­ÞTÙE2©VÜ¡èч3Á Ö¬¡/Pâž¹ãõy8›/æ©C±‹§ÑÏXyñ‚VÅ]!HZh/•vÈmÖ,\¾,Ú׈’;cFÁlh  ‹FÐü&þ}8âK9gÎôÕHoÈ7±¨H´q䈴߾D)+£IwŽCNΈ[êêh óÔ)A ƒ"äæROÿüyÑv .üÓŸê endstream endobj 10 0 obj 55959 endobj 1 0 obj << /Type /Pages /Kids [ 6 0 R ] /Count 1 >> endobj 11 0 obj << /Creator (cairo 1.13.1 (http://cairographics.org)) /Producer (cairo 1.13.1 (http://cairographics.org)) >> endobj 12 0 obj << /Type /Catalog /Pages 1 0 R >> endobj xref 0 13 0000000000 65535 f 0000057036 00000 n 0000000165 00000 n 0000000015 00000 n 0000000144 00000 n 0000000481 00000 n 0000000265 00000 n 0000000738 00000 n 0000000717 00000 n 0000000838 00000 n 0000057011 00000 n 0000057101 00000 n 0000057229 00000 n trailer << /Size 13 /Root 12 0 R /Info 11 0 R >> startxref 57282 %%EOF ast-8.3.0/sun211_figures/fronta_bw.pdf0000664000175000017500000005415313004147321014470 00000000000000%PDF-1.4 %Çì¢ 5 0 obj <> stream xœ]½KÎ-¹ÎÚ¯Qì'I=G`À=Û à6î…qꆞ¾3"H檅]SJ=2–RIQAêýyþeü—ÿŸ¿ÿúOÿmÿùÿ÷_ÿ믈ø—›ýÙ{ÿ+üÏßõJW¿;ašÛ¿,Þ”*ó¥üý?ÿÿ_Ï¿býù?ÙŸÿòþûŸ=þ3 ÿËTó Éÿþë¿¿W~qÌy¦dæÌc¸È™sKVNÄ—ó°üTÎ8SWoÎûòʜغBŽ±üVNœ««7'˟̦+äË_åø ]½9¾PÞŸÌSWÈq”ÿÇ»[WoŽíøͬè˜OÉÊyXÑyˆ¡':QtbðCOt¢èÀ .1t¡—(úb1ô•9DÑAbèB'QôÃbè'sˆ¢r61t¡›(úe1Œ'sˆbXÄ0„A,¢Æbž9D‘£2&1 a“(F0‡ÆÈ¢ƒ9Ä0ƒAƒèŒéƒñ> ¯óŒŸœ8®ˆNÌ%Y9ÁˆAïÅÒÔ£Ãò‰Áûm×r‚åƒ÷‹§+¨G‡åƒ÷; +äË'ïì¨+¨G÷ùÉyk ÏpÉÊ1ÖÀO6$e©GD‘ ‚W‰Z’•C¹ ðC s©ðªQ¨ ‚W‰z$+‡(rAð*Q.YêQä‚àU¢†dåE.^%jI–zD¹ ðE sAà‹(f1ÌÁ õÒ'b˜ ŸD‘K…W‰bùÄ`E.^%ŠåƒA¹ ðA sAðªQCWPˆa.Þxé 9Ä0îD‘ ‚W‰bùÄÀ‰"¯Åò‰E.܈a.^5jè 9Ä°sˆ"¯å’¥8E.ü!†¹ ð‡(rA`—æ‚àýJ³~²/1ÌÁ«F¡.^%ê‘,ʼn(rAð*Q.Y9D‘ ‚W‰’¥Eªý¯µ$+‡(Rí·E sA`‹(f1Ì-¢ÈÁ«D±|*4“(rAð*Q,Ÿ Í$Š\¼JË'ƒ(rA`ƒæ‚àU£†®C Sí_Ú¥+(NÄ0Õ~ ¢ÈÁ«D¡|ªý¯õè Š1LµÿU£\WÈ!†•cXŽ>\¼+¬+Y9XŽ>\¼J”I–z„åèÃÁ«D…då Ö@ ð‚QVÎÀÁÝ["5§Éò@àú•Èt,çªü«ù'׋ù‡ ÿúðäJà`)ÿPÝßgJ¤æ´XO¾cKdºE¥CzE=6ôz^¼éz>V¤)¾·ØÖÅ«!½Tø'áãJ`»T÷'Áã:`¹Tö¡[RDX´Ì,Sø £è.3ÂÖ>R(šj>µõ÷ÓÂX]RVÎ[UQ|u%“,-ÚVÇWW ÉÊqÔ@$ßOÜ”,-èXç¼@N-æUwtEýˆåS‹y•]ýúQÅæRÆ]±uE“ïJæýxèŠ&'Ö•zË;¥ê 9Æò‰+Æ4¯ -–O<0¦yE“Ê'¶cšW49¡|¡ûQ.¯øшÈEU^A "ž¹ˆŠKD¹ˆŠK¿Ù‡(Rïu%–Ï/ó!ŠÔû_]‰åóË|ˆ"õþWWbùü2o¢H½ß71LíþÕ–†®hrbùÔ[Q¤Þï°@òGRPÔû_]iüäL 8¨÷¿ºÒ’¬c Ä`œ#YúÑb Ä`ŒG²rŒ5ÀGYúÑb Ä Æ¬g ÄÀï’,-h³bàãHVŽ³£žG²´ ÍˆM—¬ 8LÆ(`8Rï‡j vïø$RVQ4£ˆaêý¯¶Äøe¾Ä0õþw[_1L½ßQ¤ÞÿêJ,_Æ(¢H½ÿÕ•X>¿Ì›(RïåËE©÷¿º˧޲ˆ"õ~ƒyá•-♚¾-"Ê5€-âée˜"¢\¼zêJMÿÕœ\WÈ!ž^†)"Ê5À«7±|â1ˆ¨Ë0E<½ SD”k ♚¾u¦ˆ§—aŠˆRÓÐó“ãDÔe˜Â*~äàý`Ì?´—Óüd’¥+a?\†)¬â‡—a «øAMÿÕ›¦diDXÅa «øe˜Â*~PÓÇŠ›"u¢Íò@àN“ÈtgiZ¥žHˆ¿uü3§D¦ Ó*õl‰Ô‰ Óú4¯D¦ Ëúd©¦õi…D¦5¥²Tì'1£Æ? Xªõ“ˆQߟ„+•úA¼¨í‚5JÝغÀ—ŸEëãzu¯!‹–ÉÉt!“Ó+þ˜œhˆ§ÉÉ$+g0Gûso”¥½¼WÚ…{[¡¬œÉ¨ÄLß’•óDçŒÍòµ?7§®hrbùTo0Gñ *ÑaùÚŸ›WW43±|ª7ïKWæ ü¨ý¹º"d(ŸØ j^ÑÌ„ò…>5¯hfbùăšW43±|ýˆâÐþ1Ì߀+v^A%"†£váˆâÐþ1Ì%U\¢È%U\b8jŽ(íÏÃ\RÅ!Š\RÅ!†³Ôg¢È%Ulb˜KªØD‘KªØÄpÖ.Qä’*1Ì…S,¢È%U`S–v ¶WGà”¥Ws}å‡/˜¼BÎ;¯~9ã²íÂíG²rk ˜)K%º¬A»p{HVÎd Ä |IV΃–váö‘,ei¢.^Å鑬œ5,í—,ei²b`1$+ÇX1xÎ’,ei±b+eåEªú~‰áª]8¢HUÿUœ\²rˆ"UýWq’¥Eªú¯â´$+‡(RÕ÷M wíÂEªú(”•C©ê¿Š“K–JD©êû"†¹ðE©ê¿ŠÓ’,•ˆ(RÕ÷I SÕU'Ö 1LUÿÕ[Vç b˜ª¾¢ÈE€b˜ª¾Qä"Àƒ¦ªÿªN®+äÃTõ_ÕièŠf&”OUÿÕ•–®hfBùTõ݈"43ù¦ªÿÊ£dšœ]á.â™jÿ«F¹® ©|âñQ.ü!ž§ŒQD” ‚·y–ÏÏô%¢Tû_%ŠåËED©ö¿JËçgúQªývˆç-c¥Úo›x¦Úo›ˆRí·M•%tÁý+Ç[Ñ﫪 :ÔdOéQ¨Êø pU^¹¶áP™=Ú ,_Ûp>uE3Ë×6ÜÞºb‡QÞjø›å6Ê[m½á0ÓÖ~+¦4>^!çaùÚz;SW4-±|m½ÅÖMK,_[oçꊦ%–¯­·aºBŽ±|m°ÝÐt"bX¿Ç®‰iűkõpðš~Ž^Ë_!8|͵õF sQÀæÚz#†¹¨ asm½Ã\T±¹¶Þˆa.ª‚ÃØ<•é§r‚cÚŠ[ÅAmb]qT[q«8¬M¬+Žk+n¶‰uÅ‘mÅ­o…W43±Í[üÒå;ÏXq«À[áÍL(_Ü*¬0QS«?>%2ýAaêô°÷R¤æ4Q˜ýö+‘é SŸë"5§ÉÂ4EEHdúÃÂxäy¦DjN‹…iŠŠ-‘éÆÂTΕ(½†…er2‰úŠ³°LN!Q_3Öê~JT=oEgJ3{+:ùÛÐoíðG `Y[poÁ3µ77P´6àÜxA¦ŠÖöÛ^ } hm¾ùäEҽϬ­·½yA+ŠÖÆ›_^ÐÆô-–Õ;ÙóêÐ[Ý)ŽÕ;òé/æ§VP‘VX”âWÁ:pD¯‚Áê»ê9—´,¡hm¶,Ñ©Àâ=«¶ÚÖÒN ZµÑ°–öÙUý. G¿ èYµÉ°ÄDÃ=ÅPÃ=[ûh€j×ÀQ ôìb~,Ѥ0@Oñ§0@HR §ØS G) ÐS ) Ð#‚è)~è= ô; ôˆ…zŠ…zDÂ=ÅŒÂ="Fa€žâEÀ-ÊU±¢`‰5ø' |“#Jè&§QXû¢`v8Ň‚-숪É)6˜&Gd(MNq¡À39"¢9aîÿ ;ÁG$'PKN±ŸÀ,9¢8LrŠû.ÉÁ T’SÌ'0IŽèM ’œâ=a?"7Aƒ8Åz‚ÂzDmÂêç ’#bH·ØK`\Ñš@ ¹Å]äŠÔúÈ-æØ#W”&Gnñ–À¹"4½u¾b™ƒlñ‚6-®õ:¼ ÅEËä/ ‚\-žõv^¤O›ÒÔâ[Ä%ð߯MpʸOÑ­÷â>o-VÖ ·KÚÐÃkEµ~q»&ö‹Ú-ÂÒnÔŸ ;'·èJؾ»b+aOùY ä†+®ÒjEU‚7ÓS w·ˆJp ½â)x‹¦BâK Ÿ[$%h&W%(«W%èÇ·JXš]”@J¼ÅO+ñŠžöÐ-vHmWä$oq“ÀH¼¢&Žx‹™>â1 dÄ[¼$°¯hI "Þb%‹xEJ‚­äóº+J Å·xGؽ¸"$„x‹uâ Ä[œ#p/eðoªÉà^*ÉàÞT‘ñü— 2^ª›ê1&èKåœÃ›ª18‡—Š1öÿnªÅØ“¾TŠÁ“¸©ï·¿— ñ~߇›ê0Xd—Ê0¼KoªÂð¾T„׳)Q¹8(‡_ êÏM*÷…蜷ø-ïDwÅay¿’·¸-o™›ü•II;”Ó7gSÒÔrœC’ ¨YÉÅÚv‚O5Û|§IÀ¶ò8¤[¥É_–Nš¶šU=giÏ‹† Yf)éIÔ^ã[@ÐQ5¬ttýÌ(pˆµ¡¯?\¬xVt¼5‘ýèÆkEH¥»¯%56w‹~R˜4Bü ‘›·c 9¾Å…ÂbÀG›¯ÞºÝsGðí§?EI‡Š,&½ÍZuƒÂ­œ’éJ‡="³§Lf0o<'Ñ·ÏåH@—x{’™#J9dÑõ¾üñz–²……°ùð5c‘×¥#´òëòÉÁôÎß>ê+h랊1"ãCHûCdˆj;HóQ0}Ìr!Ц\\€žål5À¿å÷‚Ûnpy»\z ºzÔ„E’üÐwpà{4NšÝàXWÊÓÀ^ý8SÚ(<{7ÉþmG{õƒÎgÅ ˜Ï†¸LÃáƹ£T[x#líùʧ»ÌN÷PiÉ®XÕzéjÿÜ’1ˤÈhZ© úÿÖbxБeæ^,œ3Ú$NÛåðÖܼAìæWi’ÑN•p¿Iš?4ò\"LÕ#ŠèðQ E¦/Š?^æ¼íøVoàùê³#`¼í¸«7ð@ö§zw$Yí'£ö‚½›µC9è¢ÓûæN‡““Ç¿˜áqÊqk0¦B9ÒÈZΰX ¿*~ítƒ.{“HgØÚÏv8'H£ØÇŒÓîºz·‡ÓQ@@òe€Å’bä_Oî«»âvÀ`ó*ÑêˆÉå;Nþa(¾ÁO$*ÇÀ>H¬G=ït–Ùk¦Ð|Ø_Ÿ®ZÈÀøÊà€Ö ëdÆæZìñõ:0i%9{(¤å&0Àk*ç#-¿fX:äFîöÃÝÄk†…~žÎ'ïP ¯ûáša±‡Ön»ïkÚsâ0j÷s`%´ ?°öT@Ž~¶z¢o¹ L»!‡ÄA{9Íò±®6°yå·ÂÜ{”0`BóÒ'é@ãZ›ˆÚ‹[lÚùw•;SÅh¡?ÙT\Ç6Ço@Åi¶)9F5ïa³ÓÓ¿/ˆ¯vÚIÑ9>#þEÁvÓÔ¼GvÙÜÕìüÉ|Di/s%]€\æñÛGÍãØ÷!«ÙEâæV„Ëé`À`äåþ2 §yÈR€mè%ûÛÓxr+ã­Ùkc¦jw­þñ!t/Î/Hîb¤Hæ‚`-g½ÂLÍ{Æ=¹fìŠC¢_{¤OÍ{HtùŽ‰R”2  `åþMKûlÐ/-†;{3æý¢KS`,X-Œ8™VÖskÓ Ö¯ïhV`,ž£ý˜ØƒtZ·â±i“kuл‚hw­ +Ýßš ƒ\« QbLqjÍyK项*·“¸aRóÞCSar›ÏøŒðœŽsh@5±Ñ.bš˜æ=ðmt¼"èr¥¡ ¾•S× Ñ94ïaY÷Ž‘vÕk Í{à ™×¼Ç­.×¼G“¤Go‚ h_É1zûY›³t41èDiÅ[¡ ¦%g ê•=µOO“s$ýA­œvé]jr,§jÇ>€—ÜÕ¬ÇåhÂÇÊ5ÙNµrçN,Bôá=5áa!s2¾ÓÛh ù%™I{Úï0ŸOí¾Á°0Ÿ4.”¬"‰cn™OR˜ JV׿ٛuð½EøÆuÜ ïÜZÓê4Ò„]ºQVÄ ßù­Q”ÂÀÚgˆØ  ¦[3œ‹ˆÿü.Ž];TôQV¬X Ó1æŸ ¡¤0Rå»ÚĘÚé„õ|–U¨†²ä*µ?x{FîM‚ºEchæ@±…ž^ôåOC#Ý—W0àHû‚M›(s Lu _zZE™eª¬dX(Q c”©¢a1,–kÏ4QÜÀBiˆ¼BOÆÑ4*À4Dç‹Eéòé[ËÊa—»¨íOŠ  ˜X4u\ŽXŒw±rçÊT9“`Ù2Po‰²:}oËœ ¯¨SN p'‰“d8ø 6@k‰~šÊT¹Ð7sgÐ0xÔìÚ_ÅŒ \ \‰»Â‘Àð'–õ~ñ[÷':(Sš÷&wWkÞ›Ü6Ô¼‡µWïÕFrÔƒ‡|êy2ÚšA¢r¬‹©¨¾P¦Šq;®¥:ô0‹r…•ÇB´]~,:JÔ>×¼Ç=J¯y6Cz)0ÊTÍ{¸&Y€4eEO ЮLDÙÀÆ‚•;àpaæ=<–uÔ2±1„„¬¢ÚÐC^—ªä­™Œý«‰ìæ²súÕ®Co`ezä®gÀ3è|ÔèW— ”r× ðy§©",tæS5T8 $°è™±&ð™U ‹žq»6Ä0¹rCâg”a˜Äæq‹Ÿ“ò¿ÅÕµ7X“Ndˆ vjîIJgœŒb„ åz ê&‡°¯c”kb@E|ÁLÿý߸cø©2L^“¬0¤šæK(ôñÌèUš/¡)bü†¸-$mæR1~Ž8}%}<3çEJ¿øGù¡žf¬L3Cñ"‚ë*šG`9DOlïA3Œâ;a9Dks c•#ezÅa@të=Ä·n˨Ð ‹PX Q»_:VÍ ªøhîTl š;iÑÜù@3¬8Lñ0bŽæ·1ÞjîTL2ÍXEílª m˜ý¤{Ç ¢Ð–=Æ¡¡°äê Ü‹åãPü¢\͹! áŠåŠX(Qýç¦êý|œ±XéÌ/ô]Š…R¬Œ¦-qÞæ™AßÕñÖŠAŒ'".W<ô¯y“D Í£X,Ũyô£üØ›«£+Ä3¾ X0EÔ< çÊÍ££ZÔ< …&\ó(,éá52NkEªðšGÆ*Dæ¥m)Š4àHEº/0>Š5£Z¢ÌßI/žvõDœ™¿,Íø‰5ö~Ceþf, /ó·ÜCeþ„Có2ËBæo²ø¼y}®´’Ax7/“wÐ}P&oÚÇÚi2:kD„/“w`»LÞŽyÛËäít×É ¦äR—É›ñÒ\&oFñ2y;–Î.“·Ü]Ëä-ŽâB3,“·c{ÃGºÈB3,“·ÓrdŒ6hƒOQü\&okÍ£ƒÛ‚ø.3·Ó »ÌÜN—#™¹*×ËÌ͈o.37÷Úû¾äNË¥”»íò 7ñóîJ‡°Ìy{*37‰ ^fn§gÆ'Cg/3·#¡ÉÌíäÝ•™Û1•˜ÌÜGr»ÍÓĆVì×N;cCKfn.;ÁZ2sÓéØÚû‹&37}+3·Ø¡2s;¶œLÑ0ɳ°2y;öH-CúboÕÊäíØ•5™¼]<ÂrËÅÔ˜Ô2Ç^ðÇd¼dˆiÇ»ÍÍíf >“É›/‹•ÉÛ/™ÑŠG‚Ís‹f„@”ɛˋv,‚6(“7É"V&oÇgÝdòvP ¬LÞ‚‚ÉäídB–ÉÛ1¹›LÞÆ„É¥%årþ÷Âdþf(f+ó7c šÌß|õ­ÌßÒˆe<>K¬Ìßtsºò_ÆX¸å^ƒM@ív“øR” ­FìÀ‹½å í…Áã§ÌÞŽ”¬ÞæP;hc5”„ Í<ËÕÑA¼›šÀjhV83ÆÓ™k+£Yñ Aᥔ.P¯V\ÎãضÒ6¸ce”„)ÿ뤑¤¬’F±ºh/zƒ-¬S\bÆÇÜI´ÁV;¹c4v:aa k/k¦±+"ÐýBÿ*–b…§f áâøNÆÅ!†áîg9Ÿ3H±(”\rŽfå‚ <Ä' h”Ÿ‚ƒˆ<†fX†F¯À%Ž5ÓPg¼ÏŠòä Ö¦xcŽ5Óˆša±f¡ômîÔf´/Í°Œ é5ÃbÍÄ=2æØî()ú£\†¸l?Îkо2%ôG+ÖVP´/3Ç¿X}ÜϨx’ Ô[1O+¨¸r͇¢·\Ç]Et‡ÃC%ˆÁCô2‡g@?ѱ‚Š£–±œÊ)Ù±š 9Ã;œF¢C4`:  !‹îð+lJ1œ>dwð+Ë8îØ•mÜA¶ê()pÙšŠÌÀ zó©8-÷@É’O1¾„³CÃ";¾ÚÚÿvm`7]ùcn·\V°PÉöÄ2i‰Øx¦ˆXèÆÀاœLðŽŒ#¦&6IGÇ5ÁBi(ÚŽA÷‰«š¡Ød ¢¼Ÿ©lu]ž*ОݳÏr¡}¹Ï2žV0ù‹¦Q®$t)¢i” ›aÑ4ä>i鯠Ûõk3voa„Ñ¢ 0,›âÖ‰ P¬Êáê2Ø¿¨Ê`>GÑÞÆQþ%£Œg§© ‡Åÿ{ѱ{°œ Åš2’­¨g¤nǧ&â؇K¨Ès6@}: †srè¼"Ê;d™%Kgf` å°ÄÓNBns\OG9cQ!§à PùÅX>û¿,G…T¥s\‡ý5…Æ•ÓÚapR~j! £¸ß°€‡+f^¼ðòï‡gH¸œÑ` /7CªšâÁ?%ÚW?L(jOr‰Še€ä!ƒ¹&e07Ø­#ÃgCKŽ2˜3JBÈ`np ò2˜‹\sRë½ æ$Ëx’ñvèT°¹u2þ¶¶ÊHngÜ ôÊû'>UF=Ó/­­2’ÓÞá2’˜®^Frõ7gèXš;±£#ëA3yr4ÃÑÇ<àP› CŒÏâPhjãY([çk)˜»Ž‰ˆšG`Ÿq;þVdFíP´D×<Š¥)ò™}Kó(ªñšGáú4›…¤ÅÑñ°8ŠDe<®b¥GŒÕÁœŸètR‡u„Žš©Œ>Úˆ–gFêP¶³®œÈy\Àç~…í¬“q Az*÷OÆâ ù ˆSó(J‘‘Z¾â_’†ŠÄjP:¢b[÷®yk±¨Ó¿ ¥Ðùtïâ :VÍ£AÞ»æQ,”bÖ<Ê#¡äkÍc<¢]ùšZ¡#,o¹âJb­DJÀߊ,Ô‘-ÇY¾lÁ#*¤‚å+žv™¼éÈäeò6x¤¸LÞÆh§eò6x¤TMg$äŠöäŒû©ÐpøôÝŽ}ä½W4LèU¹‰ÑžVÀ‚­­2yósã2y“Úëeò6FäUtcĹ2ys…ï2yÓËËämð=,”:MŽ*H§Öy]d+ê§A8E…¬Ú< „“àæ±»üÏ¡*M…Ä9ß!›gepÜ>¿Ã6ÏÓáô‡•PjIˆ»‘á&µó æíðSG‰A[â,/“ðr'­]¢Ád¯x†XV‡biò8 ê “Zf”û!û5¼K¢Ì×p. Y¯’¾Œ×Œ²*Û5¨(^¦k¼}.Ëõ"{=§:|v\vëÅÀÑ9Õ1§¬Ö8m3ÝûIì9+Á»$ƒÅçI éçÏàê¡ÀCО:1î{œ•àJâe¹†ï¼ËpÍxúe·æ2[ƒ=ãeµ†‰Ëh '/›5ñɚѪËbÍP¢2XÃïÞË^ —¹& /k5üG\ÆjÆ1.[5ãOÊT=$w®kSL”aÑsNPð!qÏ j‘ªÎ JÁns‚ZŒ­Ì j1´sNPö²SÓžÌÔô°—•šöe¤¦½lÔt¯/³4V“U^"VFi†™“Ms·•IjŠÉ"½ÈJO# ¼ëMöhF¼¬Èa8²:§jNNP‹A¹8A-û‰‘¥ ‡œ –"÷åOúœ N¹K±b^A+eêM…Y‡&4>7V&h(V& 4Âñ[áøa²93Fg™œaì2Yœ±álep†Ó‡ÉÞ +s3Ã4ÊÚŒmF+có$ùœ¶<µ•©ËÓqŒpÆ°:1”Áütt-BãÜœ”  ^ÎI æWTxv(¨ <9Š‚ͨYœàÅQ–eóÊðóï«QVe²xfFMÇý¢,î™)¬'rF¹ÌœŒkÅœlÅœ<å†9}Ê s2È(s:È(sòèBæô…ÌñøÊxGÑ@NFŽgNGŽç±Ó£KnZåßÌœô>]ú¼ýt¥×QåÔ¶±r2œ*sÚÿœ9Ïòýr2>s:>§¿{ºŒ×¯«œŒPÆœQÆœõ|9ëùÁÍ3p,s:p,sb6nó·ŒÇW¦=N%}É‘c÷üæd´5æt6ESñÆÍ:šsÖÓ¸Ùz~ˈ@¡œ˜?¸™lÊ©©V9ö|eìùÁíî§ì’„!¡¢˜påýkP¦3Æ[{ůt,–ÚáûcJlœ}Ž ï·$Ó¡Au:¸ž™Ž'îthš™CQ§c-”éˆXÝéXÂd:”Â&Ý`øæÑ0°íw:f¥LÇlõ‘tÞÙ¾Ž’Á*¦Ã›ŽoU§c§?ÓñíéÕ vÌvn:" X¥CÏtL\BQ¦ƒuÔéغÉthÜ}VÇ-8q”T¥bËL©q• ÝC©ðçý~Á,£w¬¦ä#²†ÄJ7}‡ÄN?^÷7a’é³ëó·žñÕ3~뉯žø­'}ÕèÞZÎ,`íýùœS‘þõ'ê즯®'Öo=_?éß×é_"~ëÉ×HÿGòhZ¤??õg%}¿ÓW×ã¿ýñÙõx‚dúøêéßdÁûþ°Ÿû¿þøóS}ý±ûS®§IàLÿú™tîLÏ“æ´7õ“v+ý·?–!Ãi¥ø­çY} ŒôÓÕô‰-8@¯" A™hŽ Rå§/¯kåà-þrà6Q9p›èœÀ+;ë$‘µ~rðÒVÔ/ ëÊÁÛüåàÅ­¼Ïãxy‹}ïovÂ+¯õ—ƒ—¸rðj9Pê+¯÷—kpåÀ«áËשràˆö±†`óÈîŠ9XGUÆÆ—juå€ZýåÀ2\9N¢wåÀ-­rÌ~¹(3°˜ët,Ÿ2}œÁ±Îô?X‚\Vðߟûù-Ì)PJÿCÅS‰úU{vüÒËdUòß_•Hþ¯=ÿz?9ÿç/ûó_Þÿó¯çÏƙ׳¶N%‹¡66ÃYpY™2—t´+ÑÚ ™¦Ã¼j²”‘ÁMñ”=ïÁÊœ¯àÀ©J´Ù–l÷»GÌÉíýÜÊ0FYù‘gO¥n©¦R¸ž9ê7_aî7šˆL)ŸŸç¼zN–½_Ÿ:ÌÔf˜6©6[ÙTë Ÿ«zHæ`¨òG|ò<ß=k}e&EunÝÏò”Ñ»º‡ŠUkõNœ”+h[Óy­jMgÞªmSê7ÔIÁc3pJÊôôÕ=ü²,[Љ°)SMÌ{†}e¹ÖÌ:§m¥Ì>ä=ì[–eŸUg÷_OCjÎcPËzeÿœá@”ä“•%înYqëuÏÌ1ÌXÍþôóTôö/§j9¢YSÜOžÏWkþ¶Šý!VQŸõLfÏ-ªŽð˜×'mF ¿’ïí{ˆw–e Zæ”|úmf©ìŠÝuŠ¢¶JFêô­ÊªÏçG~~Ÿ¦f nŒ¯¦µ¿V|-§Ì­ïMϲz‚ógù¿ëž³C™wûgF*yÚw=Á²,û|¿÷qUð'ÎaûgíŸ9B‡d¦<¿7RG²fÙø~³JÇ\¸ë]€m&ç ë_ý|š}{Ž,™O¬{ˆDöAòüAEm©lüÌ‹<‚àoµì+ç#Êí÷.§¸*$¡^Õ{ó@Õœéy ,7׈·ïœUçÂz¨{mõ¨žç¡¼)ûî™ñ•]ÏWg!?™}È{ê°×WŸ¿™ä;xsk9gmGóþ=ÓzšòcõÛæA“*+ÊJö(Óÿã4ªÚ€áoÛõß«vó÷iOœ÷‰ìƒäçµÅ²E›ÚP@6mäx†É¹ýÇ}‹Pظ”ó·ä=9¯¡¬èŽªóæhÖîÄ)Túú‹××ý9=EtÍÖøP­íõµPßc¤ç/{ì“ïí{€E•U çkYÖuÞ“ÞU,;ëYg<Ö³QËÓ¾{â~eÙgÕÙýïQ42ô)°` ±9ŒúÕòœ…×xFkH ¡Õ=ÊtúíO«Q4žüÆ_ÿêçӜ֢ZæïF¢ú yþ ¢¶T¶¼FyšÜVƒÑéðûI,§…ß[ª/&ÄÑj DÞ-s<ï.˼“™"Ké+ThœŒö]©|¤¾—I3RAhPU¿-1ª`ÝÛýNB…,]ÕŒ6%ŽQýVBdž¼Œ 1‘Ùb|7À»’;Qìd—èß 6ªoR èR´Yöm&ŒØ|¼êC¾®îÛQ߸õë]Çù¹ ‹N’h^7hCŽÅ¤Ä°2Â&RDÃyº“Å\+Î+@:~)%¢á¼ÝÉbó{§g¿éØæd|HÔDœ›1‘¢E¹ï¡½Dt6¬{áØÏ7‡ž‘%Îïr ŽÄ“æ ‰þÝ`jb•.J³t{Ã⮓œI1”¦Ãk„³º:þ—vû™GÒ[Cv_#.SÕ%ûÆ!›¯‚ktÁuºà]p} ö$b­F"{­ñ©Æ¯êˆÑ⌾᭹Šõb_¢wÓ‰,¶ò7y+Ó¨e%>£n`wTŒTeÕ߯ó—wë:vÿðµj/Å}úv,.Šs¼a¿«Æ'+Ó¨e%>£n@EY Ìʪ¿¹³þÔ¦¨1‡·9€) ¸fäFð¹ºS±F-ÜNJÜß Œ›$ÞÀý»AË9€ÁíœñoÙM¯Õ išy,­|ŽámÕ šÙÅ&põÂk`à—8ž¾a–5@=–3Ä>טQ5êYpY•£^© >í‰[Ïì‚çvÁ3»àñŸ‚ïcåë‚ÇÊqÏgÑÛÀÆõŽÎ’âî÷ 5W±Ë½›Îqbù6 ²|GÐD‰>ûë·ŒÌʲ¿_çoŸ%œãžuìfùŽ°½w¿OìÛi°òu±o„ã†ý¢|HÏË0úÍAÃuƒõ[†NVeÙ_ÑG,ß…×ÃNù—DðKéM™«¾ ˆR©—ƒ:¤Ö¶¨lñ%J w„’w.ßÒûþMbu½ì éÙ4Š*ñ”Ä1Ì ‹ØèWÞwjOeMÒ­\´¬×fYV¿`ì_@ö‹o%û•¤YìÂç‘È«ÖÃìG²ÒØÃù-†Q“Ê°m–ùÔ$¥l±ÏX~ûªý×ÀF8Fv¶ÈW€l,I·^Ô¨«‡éê±ËܨçÒ(G-ú¨9¥±*7êÍa¯XKõ¯ûÊñÏ;9ŽYz×Èшg+’n½ìÍ)D4*WUäîÔ¨E#5§ô¶–¹Q/ z¥ZªTÎ`ntqò&¶Æ¼Hy¿9’];g0¿¹“J8.tÒ^!X„îâ 1VmÉŒ›÷쟲ǿ:ÿ¶Ì:)¨O^mö#gd?B«¥‹_¾¦Ï„QwƒÞbª7êè?æˆY9Ÿ’_¤Æ&e":8CþA†³ÜgRæÛ¢{"}NôªU(Œì![F²öŽyJ«lµù(–žZãÓ¥?÷À±YeõlÕ#ÊÙS:?ç„×S®:Ô)KÜÊáSßïçMýž‰2eÖ•÷ˆ›£ÎÜaV­å¸¤öGÆË \=T`•Xñ=Ѫ£ÝØÞÒA’û9VÈ  ž£ˆgZÎ>žñõýpvOÙ¾çPì=•Ý‰-caÓA¿EÉñsžBe³6?Y_Ý3V—ýgO带^ȵ_½»?½NF€îy¾Qs³×<åùz­8¸“ÀåÈ«'PýúhB=*=­{ð7{M9+Þ“mE÷!Ÿ†óóiBdr>A(ÎuÊ㩧 ’e;„ix²ø>_k}£€²,{—u¦<ïwÏ÷”ìgm¶ ßÓ”e¸:¤p×ü:‚N=µÓoCè•”g|÷ä“ñàÂì]µUOSrüÜ3f•Õ¨Î”·÷œñ•-"{áôXV ¯ã€ù<ÊQÿüçWðŸgðÛ³R„ø‰,O¿“Q'Œèé’ÉÃz¤F$z”÷ùj]2‘ˆ!К҅Rä“>é±Zˆ©~ŽÚ?è•Ì“l}=½û“÷‡pµ݇œŸê˜ÌËVOx`I~gþ™¾~¾3¡øôj¯"`*gþ`/Çm!0­gû (§'-9~îAÏUvæ¹ öÉëùîÙñ•=ó«óÚ×Öµ¯§g¿,›}^Ï'÷HÂÕŠþjPþƘrT—ü³ÄúFÃúioÝþj„„ªu×Ùs ç›N$ 4ÿC2îk“Þ¾¹Å ?éÜ7„Vþ§ö{‡1÷LáΙ…á š{ÅôµÒN*+çîÈoó Š®è͈{±¯t´ëh0ïRêFáP>s;JZ«rßÁ¹µ±ªšS²ÜôÞ§:wÈS¾U‘zÄÚKtï‘>wfá£PÇð¶V³m¾¯¬|3þ,Λыdì*#…Kd·vŸ{ËißÉ à…“uÚú¬?Õ2J¬¬Dgïõ§+Þ*ð÷LS€Šwî¡Æ±J˜†º˜î7%JðÊ’}ËØ| èwJ@§v?ÆîÇØýª”¹£KÔ®½¹†'d5UˆIµ?%°à­¦ÎS œnôx5%Wr”ÐI˜8OcfµVeͺ{T£ê„¯?”e“ŒSeKxª=^áäÏr¨ žØ“Ó½K{aÕ@ÉëÉÔJ”“ ¼ë3K¼^-1v]JàðäÎ’ÎÊMéÉÜ+«|Ënêä·SÝÕÍ›Và®B¢¥ù±ã)ʆ›í팄ôE·:™<ݵ[’Y=‚fFXJKg‹°tþ1±¹KRöÅöwïùÄûuËÒ1\'ìUª+œ§¥˜pg2¢7yc«xQ,4[Z_¿\ñäèf¥~ýaغ÷aþ‘t¾>ùm¨<;µçj&T:µyðhœ–fõHGä°{ɹ˜OqZâÏ£l¥2lRI\ý«ªIû骎âͳ‚­X%Ó¿Gëdúµ¤õ/rͲ«²rnz2­ìª$¶Ù» UFMú'–)¼šT±:Pw(®œŽ~ºz««µ+ gŸ–¢ººFuU‡”2Ö쬮Jb›ÊfOT†ý[ñ‰Ö]Íç§OlU‘ÛØl¹YZ%ÓÇGv*AÞm@Ì•]Ý„]ÝìÕiI§œîÉNüº"‰ÖÏ¢&õ„í²‰x,^à¤IJJFg÷—·zKOwõvWOwõtWÏ×ÕóuõvÿÎó‰îuƒšd±ê[=_WO…§ªdvš>ìtòþ0ÆyJþ•¹Š…88´¯¬–0ñÞ[õÜ[¬pÛ”Vçί˜HU³^ŸâæîO—áC¨"‰§^MÃ÷®a%¯'ý”’øè£WKYF½¿-Χ4¯l’ŪOLÖQ5¸Wa—­eþ3iµÚÈÔzºÕŠo¬§“;à^'Ó°í©îÆŠ–Fj“!-œ%V÷ý4»{¹û[®d2Mܵ\Ƀ˜)Õr%v-Wò<€ºj¹’ÑÙ½\‰R¡»"‰½\É&Ul~ ú• Úùù*ûôÝ8ö‰þ!¸3Dâ.Õ<Š< OfK}5%œ (—ÞÉOª~Œ–Ò.xÏJe=N¸jÖãŸ^Wd¶z¼¾nîO¼¥¯f“,v­qo*¦Ñ:tܽK¢ ÉÜ‘:tú_ïNãÓR©¤õI½:ë»KmTÓww‡ZÁÍ%®¯Çã+ö-/F«Òã‰D6nbÚȧøs²LÖ€Ìt¥ææ?¤J›öO ëbU1þâyä$·TÝSš”¿wJL‡Ý–Nåjw“TW>ÕL$SâañÖðd>RžCb];oP“,æEM^}°;5{ d2Sk]2rstéù|›aH[ßK’ÕUI:×¾•ù,Ãþ©"‰»ŸEMª«óû©c¥";¤š¯Î|êaçSûJ E?ì퇽ý°·ööÃÞzجERæfkt:¬‡e¯²/õ°™kÖTô³~Øù|{¿‡íøžm–ö×qòY]†Õ× LÅ!F–Ç+ ½mêÓné§Óe^:UÕy–{¥‘¦þ)#ôì4> /Contents 5 0 R >> endobj 3 0 obj << /Type /Pages /Kids [ 4 0 R ] /Count 1 >> endobj 1 0 obj <> endobj 7 0 obj <>endobj 8 0 obj <> endobj 9 0 obj <>stream 2013-08-20T08:42:01-07:00 2013-08-20T08:42:01-07:00 Aladdin Ghostscript 503 (epswrite) Untitled endstream endobj 2 0 obj <>endobj xref 0 10 0000000000 65535 f 0000020541 00000 n 0000022111 00000 n 0000020482 00000 n 0000020351 00000 n 0000000015 00000 n 0000020330 00000 n 0000020605 00000 n 0000020646 00000 n 0000020675 00000 n trailer << /Size 10 /Root 1 0 R /Info 2 0 R /ID [<955A173FDECFCFDB7839C9E2CC4D1104><955A173FDECFCFDB7839C9E2CC4D1104>] >> startxref 22281 %%EOF ast-8.3.0/stcresourceprofile.h0000664000175000017500000001631713004147321013332 00000000000000#if !defined( STCRESOURCEPROFILE_INCLUDED ) /* Include this file only once */ #define STCRESOURCEPROFILE_INCLUDED /* *+ * Name: * stcresourceprofile.h * Type: * C include file. * Purpose: * Define the interface to the StcResourceProfile class. * Invocation: * #include "stcresourceprofile.h" * Description: * This include file defines the interface to the StcResourceProfile class * and provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The StcResourceProfile class is a sub-class of Stc used to describe * the coverage of the datasets contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcResourceProfile class inherits from the Stc class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-NOV-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "stc.h" /* Coordinate stcs (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* StcResourceProfile structure. */ /* ----------------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStcResourceProfile { /* Attributes inherited from the parent class. */ AstStc stc; /* Parent class structure */ } AstStcResourceProfile; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcResourceProfileVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstStcVtab stc_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstStcResourceProfileVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstStcResourceProfileGlobals { AstStcResourceProfileVtab Class_Vtab; int Class_Init; } AstStcResourceProfileGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitStcResourceProfileGlobals_( AstStcResourceProfileGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(StcResourceProfile) /* Check class membership */ astPROTO_ISA(StcResourceProfile) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstStcResourceProfile *astStcResourceProfile_( void *, int, AstKeyMap **, const char *, int *, ...); #else AstStcResourceProfile *astStcResourceProfileId_( void *, int, AstKeyMap **, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStcResourceProfile *astInitStcResourceProfile_( void *, size_t, int, AstStcResourceProfileVtab *, const char *, AstRegion *, int, AstKeyMap **, int * ); /* Vtab initialiser. */ void astInitStcResourceProfileVtab_( AstStcResourceProfileVtab *, const char *, int * ); /* Loader. */ AstStcResourceProfile *astLoadStcResourceProfile_( void *, size_t, AstStcResourceProfileVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStcResourceProfile(this) astINVOKE_CHECK(StcResourceProfile,this,0) #define astVerifyStcResourceProfile(this) astINVOKE_CHECK(StcResourceProfile,this,1) /* Test class membership. */ #define astIsAStcResourceProfile(this) astINVOKE_ISA(StcResourceProfile,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astStcResourceProfile astINVOKE(F,astStcResourceProfile_) #else #define astStcResourceProfile astINVOKE(F,astStcResourceProfileId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStcResourceProfile(mem,size,init,vtab,name,region,ncoords,coords) \ astINVOKE(O,astInitStcResourceProfile_(mem,size,init,vtab,name,region,ncoords,coords,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcResourceProfileVtab(vtab,name) astINVOKE(V,astInitStcResourceProfileVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStcResourceProfile(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStcResourceProfile_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckStcResourceProfile to validate StcResourceProfile pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/fpolygon.c0000664000175000017500000001675513004147321011246 00000000000000/* *+ * Name: * fpolygon.c * Purpose: * Define a FORTRAN 77 interface to the AST Polygon class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Polygon class. * Routines Defined: * AST_ISAPOLYGON * AST_POLYGON * AST_DOWNSIZE * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 27-OCT-2004 (DSB): * Original version. * 28-MAY-2009 (DSB): * Added AST_DOWNSIZE. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "polygon.h" /* C interface to the Polygon class */ F77_LOGICAL_FUNCTION(ast_isapolygon)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAPOLYGON", NULL, 0 ); astWatchSTATUS( RESULT = astIsAPolygon( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_polygon)( INTEGER(FRAME), INTEGER(NPNT), INTEGER(INDIM), DOUBLE_ARRAY(POINTS), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_INTEGER(NPNT) GENPTR_INTEGER(INDIM) GENPTR_DOUBLE_ARRAY(POINTS) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_POLYGON", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astPolygon( astI2P( *FRAME ), *NPNT, *INDIM, POINTS, astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_downsize)( INTEGER(THIS), DOUBLE(MAXERR), INTEGER(MAXVERT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE(MAXERR) GENPTR_INTEGER(MAXVERT) F77_INTEGER_TYPE(RESULT); astAt( "AST_DOWNSIZE", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astDownsize( astI2P( *THIS ), *MAXERR, *MAXVERT ) ); ) return RESULT; } /* AST_OUTLINE requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_OUTLINE(f,F,Ftype,X,Xtype) \ F77_INTEGER_FUNCTION(ast_outline##f)( Ftype(VALUE), \ INTEGER(OPER), \ Ftype##_ARRAY(ARRAY), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ DOUBLE(MAXERR), \ INTEGER(MAXVERT), \ INTEGER_ARRAY(INSIDE), \ LOGICAL(STARPIX), \ INTEGER(STATUS) ) { \ GENPTR_##Ftype(VALUE) \ GENPTR_INTEGER(OPER) \ GENPTR_##Ftype##_ARRAY(ARRAY) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_DOUBLE(MAXERR) \ GENPTR_INTEGER(MAXVERT) \ GENPTR_INTEGER_ARRAY(INSIDE) \ GENPTR_LOGICAL(STARPIX) \ GENPTR_INTEGER(STATUS) \ \ F77_INTEGER_TYPE RESULT; \ \ astAt( "AST_OUTLINE"#F, NULL, 0 ); \ astWatchSTATUS( \ RESULT = astP2I( astOutline##X( *VALUE, *OPER, (Xtype *) ARRAY, LBND, \ UBND, *MAXERR, *MAXVERT, INSIDE, \ F77_ISTRUE( *STARPIX ) ? 1 : 0 ) ); \ ) \ return RESULT; \ } /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_OUTLINE(d,D,DOUBLE,D,double) MAKE_AST_OUTLINE(r,R,REAL,F,float) MAKE_AST_OUTLINE(i,I,INTEGER,I,int) MAKE_AST_OUTLINE(ui,UI,INTEGER,UI,unsigned int) MAKE_AST_OUTLINE(s,S,WORD,S,short int) MAKE_AST_OUTLINE(us,US,UWORD,US,unsigned short int) MAKE_AST_OUTLINE(w,W,WORD,S,short int) MAKE_AST_OUTLINE(uw,UW,UWORD,US,unsigned short int) MAKE_AST_OUTLINE(b,B,BYTE,B,signed char) MAKE_AST_OUTLINE(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_OUTLINE /* AST_CONVEX requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_CONVEX(f,F,Ftype,X,Xtype) \ F77_INTEGER_FUNCTION(ast_convex##f)( Ftype(VALUE), \ INTEGER(OPER), \ Ftype##_ARRAY(ARRAY), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ LOGICAL(STARPIX), \ INTEGER(STATUS) ) { \ GENPTR_##Ftype(VALUE) \ GENPTR_INTEGER(OPER) \ GENPTR_##Ftype##_ARRAY(ARRAY) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_LOGICAL(STARPIX) \ GENPTR_INTEGER(STATUS) \ \ F77_INTEGER_TYPE RESULT; \ \ astAt( "AST_CONVEX"#F, NULL, 0 ); \ astWatchSTATUS( \ RESULT = astP2I( astConvex##X( *VALUE, *OPER, (Xtype *) ARRAY, LBND, \ UBND, F77_ISTRUE( *STARPIX ) ? 1 : 0 ) ); \ ) \ return RESULT; \ } /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_CONVEX(d,D,DOUBLE,D,double) MAKE_AST_CONVEX(r,R,REAL,F,float) MAKE_AST_CONVEX(i,I,INTEGER,I,int) MAKE_AST_CONVEX(ui,UI,INTEGER,UI,unsigned int) MAKE_AST_CONVEX(s,S,WORD,S,short int) MAKE_AST_CONVEX(us,US,UWORD,US,unsigned short int) MAKE_AST_CONVEX(w,W,WORD,S,short int) MAKE_AST_CONVEX(uw,UW,UWORD,US,unsigned short int) MAKE_AST_CONVEX(b,B,BYTE,B,signed char) MAKE_AST_CONVEX(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_CONVEX ast-8.3.0/fnullregion.c0000664000175000017500000000623013004147321011720 00000000000000/* *+ * Name: * fnullregion.c * Purpose: * Define a FORTRAN 77 interface to the AST NullRegion class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the NullRegion class. * Routines Defined: * AST_ISANULLREGION * AST_NULLREGION * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 12-OCT-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "nullregion.h" /* C interface to the NullRegion class */ F77_LOGICAL_FUNCTION(ast_isanullregion)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISANULLREGION", NULL, 0 ); astWatchSTATUS( RESULT = astIsANullRegion( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_nullregion)( INTEGER(FRAME), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_NULLREGION", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astNullRegion( astI2P( *FRAME ), astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/ftimeframe.c0000664000175000017500000000651613004147321011522 00000000000000/* *+ * Name: * ftimeframe.c * Purpose: * Define a FORTRAN 77 interface to the AST TimeFrame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the TimeFrame class. * Routines Defined: * AST_ISATIMEFRAME * AST_TIMEFRAME * AST_CURRENTTIME * 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 * . * Authors: * NG: Norman Gray (Starlink) * History: * 02-AUG-2003 (NG): * Original version, heavily based on fspecframe.c. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "timeframe.h" /* C interface to the TimeFrame class */ F77_LOGICAL_FUNCTION(ast_isatimeframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISATIMEFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsATimeFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_timeframe)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_TIMEFRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astTimeFrame( "%s", options ) ); astFree( options ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_currenttime)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_DOUBLE_TYPE(RESULT); astAt( "AST_CURRENTTIME", NULL, 0 ); astWatchSTATUS( RESULT = astCurrentTime( astI2P( *THIS ) ); ) return RESULT; } ast-8.3.0/prism.c0000664000175000017500000046157713004147321010551 00000000000000/* *class++ * Name: * Prism * Purpose: * An extrusion of a region into higher dimensions. * Constructor Function: c astPrism f AST_PRISM * Description: * A Prism is a Region which represents an extrusion of an existing Region * into one or more orthogonal dimensions (specified by another Region). * If the Region to be extruded has N axes, and the Region defining the * extrusion has M axes, then the resulting Prism will have (M+N) axes. * A point is inside the Prism if the first N axis values correspond to * a point inside the Region being extruded, and the remaining M axis * values correspond to a point inside the Region defining the extrusion. * * As an example, a cylinder can be represented by extruding an existing * Circle, using an Interval to define the extrusion. Ih this case, the * Interval would have a single axis and would specify the upper and * lower limits of the cylinder along its length. * Inheritance: * The Prism class inherits from the Region class. * Attributes: * The Prism class does not define any new attributes beyond those * which are applicable to all Regions. * Functions: c The Prism class does not define any new functions beyond those f The Prism class does not define any new routines beyond those * which are applicable to all Regions. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 17-DEC-2004 (DSB): * Original version. * 11-MAY-2005 (DSB): * Overlap modified to allow testing of overlap between prisms and * intervals. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 9-OCT-2007 (DSB): * Guard against all axes being extrusion axes in EquivPrism. * 20-JAN-2009 (DSB): * Over-ride astRegBasePick. * 22-JAN-2009 (DSB): * - Allow any class of Region to be used to define the extrusion axes. * - Over-ride the astMapList method. * 19-MAR-2009 (DSB): * Over-ride the astDecompose method. * 14-AUG-2014 (DSB): * Over-ride the astGetRegionBounds method. * 9-SEP-2014 (DSB): * Record the pointer to the Prism implementation of RegBaseMesh * within the class virtual function table. *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 Prism /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Regions (parent class) */ #include "channel.h" /* I/O channels */ #include "prism.h" /* Interface definition for this class */ #include "cmpmap.h" /* Compound Mappings */ #include "cmpframe.h" /* Compound Frames */ #include "unitmap.h" /* Unit Mappings */ #include "interval.h" /* Axis intervals */ #include "pointlist.h" /* Points within Frames */ #include "permmap.h" /* Axis permutations */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstMapping *(* parent_simplify)( AstMapping *, int * ); static AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *(* parent_getdefunc)( AstRegion *, int * ); static double (*parent_getfillfactor)( AstRegion *, int * ); static int (* parent_equal)( AstObject *, AstObject *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_maplist)( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int (* parent_overlapx)( AstRegion *, AstRegion *, int * ); static void (* parent_clearclosed)( AstRegion *, int * ); static void (* parent_clearmeshsize)( AstRegion *, int * ); static void (* parent_setclosed)( AstRegion *, int, int * ); static void (* parent_setmeshsize)( AstRegion *, int, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (*parent_getregionbounds)( AstRegion *, double *, double *, int * ); static void (*parent_regclearattrib)( AstRegion *, const char *, char **, int * ); static void (*parent_regsetattrib)( AstRegion *, const char *, char **, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Prism) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Prism,Class_Init) #define class_vtab astGLOBAL(Prism,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPrismVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstPrism *astPrismId_( void *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *GetDefUnc( AstRegion *, int * ); static AstRegion *RegBasePick( AstRegion *this, int, const int *, int * ); static double *RegCentre( AstRegion *this, double *, double **, int, int, int * ); static double GetFillFactor( AstRegion *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetBounded( AstRegion *, int * ); static int GetObjSize( AstObject *, int * ); static int MapList( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int Overlap( AstRegion *, AstRegion *, int * ); static int OverlapX( AstRegion *, AstRegion *, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static void ClearClosed( AstRegion *, int * ); static void ClearMeshSize( AstRegion *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Decompose( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void GetRegions( AstPrism *, AstRegion **, AstRegion **, int *, int * ); static void GetRegionBounds( AstRegion *, double *, double *, int * ); static void RegBaseBox( AstRegion *, double *, double *, int * ); static void RegClearAttrib( AstRegion *, const char *, char **, int * ); static void RegSetAttrib( AstRegion *, const char *, char **, int * ); static void SetClosed( AstRegion *, int, int * ); static void SetMeshSize( AstRegion *, int, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ AstRegion *astConvertToPrism_( AstRegion *this, int *status ) { /* *+ * Name: * astConvertToPrism * Purpose: * Convert a supplied Region into a Prism if possible. * Type: * Protected function. * Synopsis: * #include "prism.h" * AstRegion *astConvertToPrism( AstRegion *this, int *status ) * Description: * This function attempts to split the supplied Region into two * regions defined within separate coordinate system. If this is * possible, and if either one of the two resulting Regions can be * simplified, then the two simplified Regions are joined into a Prism * equivalent to the supplied Region. The Prism is then simplified and * returned. * * If the supplied Region cannot be split into two components, or if * neither of the two components can eb simplified, then a clone of the * supplied Region pointer is returned. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the equivalent simplified Prism, or a clone of the * supplied Region pointer. * 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 *frm; /* Current Frame in supplied Region */ AstFrame *pickfrm1; /* Frame formed by picking current subset of axes */ AstFrame *pickfrm2; /* Frame formed by picking all other axes */ AstMapping *junk; /* Unused Mapping pointer */ AstMapping *map; /* Base -> current Mapping */ AstPrism *prism; /* Prism combining all axes */ AstPrism *newprism; /* Prism combining all axes, in original Frame */ AstRegion *result; /* Result pointer to return */ AstRegion *sp1; /* Simplified region spanning selected axes */ AstRegion *sp2; /* Simplified region spanning unselected axes */ AstUnitMap *um; /* A UnitMap */ int *ax; /* Pointer to array of selecte axis indices */ int *perm; /* Axis permutation array */ int axis; /* Axis index */ int bitmask; /* Integer with set bits for selected axes */ int i; /* Loop index */ int mask; /* Integer with a set bit at current axis */ int nax; /* Number of selected axes */ int nin; /* No. of base Frame axes (Mapping inputs) */ int nout; /* No. of current Frame axes (Mapping outputs) */ int topmask; /* Integer that selects all axes */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the Mapping from base to current Frame. */ map = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); /* Get the number of inputs and outputs for the Mapping. */ nin = astGetNin( map ); nout = astGetNout( map ); /* Allocate memory to hold the indices of the current Frame axes in the current subset */ ax = astMalloc( sizeof( int )* nout ); if( ax ) { /* We need to scan through all possible subsets of the current Frame axes, looking for a subset that results in the Region being split. We use the binary pattern of bits in "bitmask" to indicate if the corresponding axes should be included in the subset of axes. Loop round all possible combinations, until a combination is found that results in a Prism being formed. */ topmask = pow( 2, nout ); for( bitmask = 1; bitmask < topmask && !result; bitmask++ ) { /* Store the indices of the axes forming the current subset. */ nax = 0; mask = 1; for( axis = 0; axis < nout; axis++ ) { if( bitmask & mask ) ax[ nax++ ] = axis; mask <<= 1; } /* See if the current subset of current Frame axes can be split off from the Region. If it can, the Frame pointer returned by astPickAxes will identify a Region. */ pickfrm1 = astPickAxes( this, nax, ax, &junk ); junk = astAnnul( junk ); if( astIsARegion( pickfrm1 ) ) { /* Check that the remaining (unselected) axes can also be picked into a new Region. */ nax = 0; mask = 1; for( axis = 0; axis < nout; axis++ ) { if( ( bitmask & mask ) == 0 ) ax[ nax++ ] = axis; mask <<= 1; } pickfrm2 = astPickAxes( this, nax, ax, &junk ); junk = astAnnul( junk ); if( astIsARegion( pickfrm2 ) ) { /* See if either of these picked Regions can be simplified. */ sp1 = astSimplify( pickfrm1 ); sp2 = astSimplify( pickfrm2 ); if( (AstFrame *) sp1 != pickfrm1 || (AstFrame *) sp2 != pickfrm2 ) { /* If so form a Prism containing the simplified Regions. */ prism = astPrism( sp1, sp2, " ", status ); /* Permute the axes of the Prism so that they are in the same order as in the Box. */ perm = astMalloc( sizeof( int )*nout ); if( perm ) { for( i = 0; i < nout; i++ ) perm[ i ] = -1; for( i = 0; i < nax; i++ ) { perm[ ax[ i ] ] = i + ( nout - nax ); } nax = 0; for( i = 0; i < nout; i++ ) { if( perm[ i ] == -1 ) perm[ i ] = nax++; } astPermAxes( prism, perm ); perm = astFree( perm ); } /* Put the original current Frame back in (in place of the CmpFrame containined in the Prism). */ frm = astGetFrame( this->frameset, AST__CURRENT ); um = astUnitMap( nout, " ", status ); newprism = astMapRegion( prism, um, frm ); um = astAnnul( um ); frm = astAnnul( frm ); /* Attempt to simplify the Prism. */ result = astSimplify( newprism ); /* Free resources */ prism = astAnnul( prism ); newprism = astAnnul( newprism ); } sp1 = astAnnul( sp1 ); sp2 = astAnnul( sp2 ); } pickfrm2 = astAnnul( pickfrm2 ); } pickfrm1 = astAnnul( pickfrm1 ); } ax = astFree( ax ); } map = astAnnul( map ); /* If no Prism could be made, return a clone of the supplied Region pointer. */ if( !result ) result = astClone( this ); /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void Decompose( AstMapping *this_mapping, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { /* * * Name: * Decompose * Purpose: * Decompose a Prism into two component Regions. * Type: * Private function. * Synopsis: * #include "cmpregion.h" * void Decompose( AstMapping *this, AstMapping **map1, * AstMapping **map2, int *series, * int *invert1, int *invert2, int *status ) * Class Membership: * Prism member function (over-rides the protected astDecompose * method inherited from the Mapping class). * Description: * This function returns pointers to two Mappings which, when applied * either in series or parallel, are equivalent to the supplied Mapping. * * Since the Frame class inherits from the Mapping class, Frames can * be considered as special types of Mappings and so this method can * be used to decompose either CmpMaps, CmpFrames, CmpRegions or Prisms. * Parameters: * this * Pointer to the Mapping. * map1 * Address of a location to receive a pointer to first component * Mapping. * map2 * Address of a location to receive a pointer to second component * Mapping. * series * Address of a location to receive a value indicating if the * component Mappings are applied in series or parallel. A non-zero * value means that the supplied Mapping is equivalent to applying map1 * followed by map2 in series. A zero value means that the supplied * Mapping is equivalent to applying map1 to the lower numbered axes * and map2 to the higher numbered axes, in parallel. * invert1 * The value of the Invert attribute to be used with map1. * invert2 * The value of the Invert attribute to be used with map2. * status * Pointer to the inherited status variable. * Notes: * - Any changes made to the component rames using the returned * pointers will be reflected in the supplied CmpFrame. *- */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the CmpMap structure. */ this = (AstPrism *) this_mapping; /* The components Frames of a Prism are considered to be parallel Mappings. */ if( series ) *series = 0; /* The Frames are returned in their original order whether or not the Prism has been inverted. */ if( map1 ) *map1 = astClone( this->region1 ); if( map2 ) *map2 = astClone( this->region2 ); /* The invert flags dont mean anything for a Region, but we return them anyway. If the Prism has been inverted, return inverted Invert flags. */ if( astGetInvert( this ) ) { if( invert1 ) *invert1 = astGetInvert( this->region1 ) ? 0 : 1; if( invert2 ) *invert2 = astGetInvert( this->region2 ) ? 0 : 1; /* If the Prism has not been inverted, return the current Invert flags. */ } else { if( invert1 ) *invert1 = astGetInvert( this->region1 ); if( invert2 ) *invert2 = astGetInvert( this->region2 ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Objects are equivalent. * Type: * Private function. * Synopsis: * #include "prism.h" * int Equal( AstObject *this_object, AstObject *that_object, int *status ) * Class Membership: * Prism member function (over-rides the astEqual protected * method inherited from the Region class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Prisms are equivalent. * Parameters: * this * Pointer to the first Prism. * that * Pointer to the second Prism. * status * Pointer to the inherited status variable. * Returned Value: * One if the Prisms are equivalent, zero otherwise. * Notes: * - The Prisms are equivalent if their component Regions are * equivalent and if they have the same boolean operation, negation * and closed flags. * - 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: */ AstPrism *that; AstPrism *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the Equal method inherited from the parent Region class. This checks that the Objects are both of the same class, and have the same Negated and Closed flags (amongst other things). */ if( (*parent_equal)( this_object, that_object, status ) ) { /* Obtain pointers to the two Prism structures. */ this = (AstPrism *) this_object; that = (AstPrism *) that_object; /* Test their first component Regions for equality. */ if( astEqual( this->region1, that->region1 ) ) { /* Test their second component Regions for equality. */ if( astEqual( this->region2, that->region2 ) ) result = 1; } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } /* * Name: * MAKE_SET * Purpose: * Define a function to set an attribute value for a Prism. * Type: * Private macro. * Synopsis: * #include "prism.h" * MAKE_SET(attribute,lattribute,type) * Class Membership: * Defined by the Prism class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static void Set( AstRegion *this, value ) * * that sets the value of a specified Region attribute in the parent * Region structure and also in the component Regions. * Parameters: * attribute * Name of the attribute, as it appears in the function name. * lattribute * Name of the attribute, all in lower case. * type * The C type of the attribute. */ /* Define the macro. */ #define MAKE_SET(attribute,lattribute,type) \ static void Set##attribute( AstRegion *this_region, type value, int *status ) { \ \ /* Local Variables: */ \ AstPrism *this; /* Pointer to the Prism structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Use the parent method to set the value in the parent Region structure. */ \ (*parent_set##lattribute)( this_region, value, status ); \ \ /* Also set the value in the two component Regions. */ \ this = (AstPrism *) this_region; \ astSet##attribute( this->region1, value ); \ astSet##attribute( this->region2, value ); \ } /* Use the above macro to create accessors for the MeshSize and Closed attributes. */ MAKE_SET(MeshSize,meshsize,int) MAKE_SET(Closed,closed,int) /* Undefine the macro. */ #undef MAKE_SET /* * Name: * MAKE_CLEAR * Purpose: * Define a function to clear an attribute value for a Prism. * Type: * Private macro. * Synopsis: * #include "prism.h" * MAKE_CLEAR(attribute,lattribute) * Class Membership: * Defined by the Prism class. * Description: * This macro expands to an implementation of a private member function * of the form: * * static void Clear( AstRegion *this ) * * that sets the value of a specified Region attribute in the parent * Region structure and also in the component Regions. * Parameters: * attribute * Name of the attribute, as it appears in the function name. * lattribute * Name of the attribute, all in lower case. */ /* Define the macro. */ #define MAKE_CLEAR(attribute,lattribute) \ static void Clear##attribute( AstRegion *this_region, int *status ) { \ \ /* Local Variables: */ \ AstPrism *this; /* Pointer to the Prism structure */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Use the parent method to clear the value in the parent Region structure. */ \ (*parent_clear##lattribute)( this_region, status ); \ \ /* Also clear the value in the two component Regions. */ \ this = (AstPrism *) this_region; \ astClear##attribute( this->region1 ); \ astClear##attribute( this->region2 ); \ } /* Use the above macro to create accessors for the MeshSize and Closed attributes. */ MAKE_CLEAR(MeshSize,meshsize) MAKE_CLEAR(Closed,closed) /* Undefine the macro. */ #undef MAKE_CLEAR static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "prism.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Prism member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Prism, * in bytes. * Parameters: * this * Pointer to the Prism. * 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: */ AstPrism *this; /* Pointer to Prism structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the Prism structure. */ this = (AstPrism *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->region1 ); result += astGetObjSize( this->region2 ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetBounded( AstRegion *this_region, int *status ) { /* * Name: * GetBounded * Purpose: * Is the Region bounded? * Type: * Private function. * Synopsis: * #include "prism.h" * int GetBounded( AstRegion *this, int *status ) * Class Membership: * Prism method (over-rides the astGetBounded method inherited from * the Region class). * Description: * This function returns a flag indicating if the Region is bounded. * The implementation provided by the base Region class is suitable * for Region sub-classes representing the inside of a single closed * curve (e.g. Circle, Ellipse, Box, etc). Other sub-classes (such as * Prism, PointList, etc ) may need to provide their own * implementations. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Region is bounded. Zero otherwise. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ int neg; /* Negated flag to use with the Prism */ int reg1b; /* Is the first component Region bounded?*/ int reg2b; /* Is the second component Region bounded?*/ int result; /* Returned result */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Get the component Regions, and the Negated value for the Prism. The returned Regions represent a region within the base Frame of the FrameSet encapsulated by the parent Region structure. */ GetRegions( this, ®1, ®2, &neg, status ); /* If the Prism has been inverted, temporarily invert the components. */ if( neg ) { astNegate( reg1 ); astNegate( reg2 ); } /* See if either of the component Regions is bounded. */ reg1b = astGetBounded( reg1 ); reg2b = astGetBounded( reg2 ); /* If the Prism has been inverted, re-invert the components to bring them back to their original states. */ if( neg ) { astNegate( reg1 ); astNegate( reg2 ); } /* The Prism is bounded only if both of the component Regions are bounded. */ result = ( reg1b && reg2b ); /* Free resources. */ reg1 = astAnnul( reg1 ); reg2 = astAnnul( reg2 ); /* Return zero if an error occurred. */ if( !astOK ) result = 0; /* Return the required pointer. */ return result; } static double GetFillFactor( AstRegion *this_region, int *status ) { /* * Name: * GetFillFactor * Purpose: * Obtain the value of the FillFactor attribute for a Prism. * Type: * Private function. * Synopsis: * #include "prism.h" * double GetFillFactor( AstRegion *this, int *status ) * Class Membership: * Prism member function (over-rides the astGetFillFactor method inherited * from the Region class). * Description: * This function returns the value of the FillFactor attribute for a * Prism. A suitable default value is returned if no value has * previously been set. * Parameters: * this * Pointer to the Prism. * status * Pointer to the inherited status variable. * Returned Value: * The FillFactor value to use. */ /* Local Variables: */ AstPrism *this; double f1; double f2; double result; /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* Initialise. */ result = AST__BAD; /* Obtain a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* See if a FillFactor value has been set. If so, use the parent astGetFillFactor method to obtain it. */ if ( astTestFillFactor( this ) ) { result = (*parent_getfillfactor)( this_region, status ); /* Otherwise, we will generate a default value equal to the product of the FillFactor values of the two component Regions. */ } else { f1 = astGetFillFactor( this->region1 ); f2 = astGetFillFactor( this->region2 ); if( f1 != AST__BAD && f2 != AST__BAD ) result = f1*f2; } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = AST__BAD; /* Return the result. */ return result; } static void GetRegionBounds( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * * Name: * GetRegionBounds * Purpose: * Returns the bounding box of Prism. * Type: * Private function. * Synopsis: * #include "cmpregion.h" * void GetRegionBounds( AstRegion *this_region, double *lbnd, * double *ubnd, int *status ) * Class Membership: * Prism member function (over-rides the protected astGetRegionBounds * method inherited from the Region class). * Description: * This function returns the upper and lower limits of a box which just * encompasses the supplied Prism. The limits are returned as axis * values within the Frame represented by the Prism. The value of the * Negated attribute is ignored (i.e. it is assumed that the Prism has * not been negated). * Parameters: * this * Pointer to the Prism. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Prism. It should have at least as many elements as * there are axes in the Prism. If an axis has no lower limit, the * returned value will be the largest possible negative value. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Prism. It should have at least as many elements as * there are axes in the Prism. If an axis has no upper limit, the * returned value will be the largest possible positive value. * Notes: * - The value of the Negated attribute is ignored (i.e. it is assumed that * the Prism has not been negated). * - If an axis has no extent on an axis then the lower limit will be * returned larger than the upper limit. Note, this is different to an * axis which has a constant value (in which case both lower and upper * limit will be returned set to the constant value). * - If the bounds on an axis cannot be determined, AST__BAD is returned for * both upper and lower bounds * - The implementation of this method for Prisms attempts to split the Prism * into two separate Regions spanning indepenent sets of axes, and then uses * the astGetRegionBouinds method to get the bounds on these two Regions. Care * has to be taken because the Prism may have been remapped into a different * Frame since it was created. *- */ /* Local Variables: */ AstFrame *cfrm1; /* Frame spanning current axes for 1st component Region */ AstFrame *cfrm2; /* Frame spanning current axes for 2nd component Region */ AstFrame *cfrm; /* Current Frame for total Prism */ AstMapping *map1; /* Base->Current Mapping for axes of 1st component Region */ AstMapping *map2; /* Base->Current Mapping for axes of 2nd component Region */ AstMapping *map; /* Case->Current mapping for total Prism */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *reg1; /* 1st component Region Mapping into Prism's Frame */ AstRegion *reg2; /* 2nd component Region Mapping into Prism's Frame */ int *baxes; /* Indicies of Base Frame axes to be picked */ int *caxes; /* Indicies of Current Frame axes to be picked */ int iax; /* Axis index */ int nax1; /* Number of axes in first component Region */ int nax1_out; /* Number of current Frame axes in first component Region */ int nax2; /* Number of axes in second component Region */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Initialise */ cfrm1 = NULL; cfrm2 = NULL; map1 = NULL; map2 = NULL; nax1_out = 0; /* The number of base-frame axes spanned by the two component Regions. */ nax1 = astGetNaxes( this->region1 ); nax2 = astGetNaxes( this->region2 ); /* Work space to hold the base frame indices for a single component FrameSet. */ baxes = astMalloc( ( nax1 + nax2 )*sizeof( int ) ); if( astOK ) { /* Get the Mapping from Base to Current Frame from the Prism's FrameSet, and get a pointer to the current Frame. */ map = astGetMapping( this_region->frameset, AST__BASE, AST__CURRENT ); cfrm = astGetFrame( this_region->frameset, AST__CURRENT ); /* Attempt to split the FrameSet encapsulated within the Prism into two - one containing the axes spanned by the first component Region and another containing the axes spanned by the second component Region. First store the zero-based indices of the base Frame axes corresponding to the first component Region. */ for( iax = 0; iax < nax1; iax++ ) baxes[ iax ] = iax; /* Attempt to split these inputs from the total Mapping, thus creating a Mapping that converts just the axes spanned by the first component Region. */ caxes = astMapSplit( map, nax1, baxes, &map1 ); /* If the Mapping could be split, get a Frame spanning the current Frame axes corresponding to the first component Region. */ if( caxes ) { nax1_out = astGetNout( map1 ); cfrm1 = astPickAxes( cfrm, nax1_out, caxes, NULL ); caxes = astFree( caxes ); } /* Do the same thing for the second component Region. */ for( iax = 0; iax < nax2; iax++ ) baxes[ iax ] = iax + nax1; caxes = astMapSplit( map, nax2, baxes, &map2 ); if( caxes ) { cfrm2 = astPickAxes( cfrm, astGetNout( map2 ), caxes, NULL ); caxes = astFree( caxes ); } /* Free resources. */ cfrm = astAnnul( cfrm ); map = astAnnul( map ); } baxes = astFree( baxes ); /* If the Prism mapping could not be split, use the parent GetRegionBounds method. */ if( !map1 || !map2 ) { (*parent_getregionbounds)( this_region, lbnd, ubnd, status ); /* Otherwise, we get the bounds of the two component Regions separately. */ } else { /* Remap the first component Region using the FrameSet created above. */ reg1 = astMapRegion( this->region1, map1, cfrm1 ); /* Get the bounds of this Region, storing the results at the start of the returned lbnd/ubnd arrays. */ astGetRegionBounds( reg1, lbnd, ubnd ); reg1 = astAnnul( reg1 ); /* Do the same thing for the second component Region, storing the results at the end of the returned lbnd/ubnd arrays. */ reg2 = astMapRegion( this->region2, map2, cfrm2 ); astGetRegionBounds( reg2, lbnd + nax1_out, ubnd + nax1_out ); reg2 = astAnnul( reg2 ); /* What about the possibility that the axes of the Prism have been permuted? */ } /* Free resources. */ if( map1 ) map1 = astAnnul( map1 ); if( map2 ) map2 = astAnnul( map2 ); if( cfrm1 ) cfrm1 = astAnnul( cfrm1 ); if( cfrm2 ) cfrm2 = astAnnul( cfrm2 ); } static void GetRegions( AstPrism *this, AstRegion **reg1, AstRegion **reg2, int *neg, int *status ) { /* * * Name: * GetRegions * Purpose: * Get the component Regions of a Prism. * Type: * Private function. * Synopsis: * #include "region.h" * void GetRegions( AstPrism *this, AstRegion **reg1, AstRegion **reg2, * int *neg, int *status ) * Class Membership: * Prism member function * Description: * This function returns pointers to the two Regions in a Prism, together * with the Negated flag for the Prism. * * The current Frames in both the returned component Regions will be * equivalent to componets of the base Frame in the FrameSet encapsulated * by the parent Region structure. * Parameters: * this * Pointer to the Prism. * reg1 * Address of a location to receive a pointer to first component * Region. This is the region which is to be extruded. * reg2 * Address of a location to receive a pointer to second component * Region. This will be an Interval defining the axes along which * the first Region is to be extruded. * neg * Pointer to an int in which to return the value of the Negated * attribute of the Prism. * status * Pointer to the inherited status variable. * Notes: * - The returned pointers should be annuled using astAnnul when no * longer needed. * - The Frames represented by the returned Regions (that is, the * current Frames in their encapsulated FrameSets) are equivalent to the * base Frame in the FrameSet encapsulated within the parent Region. * - Any changes made to the component Regions using the returned * pointers will be reflected in the supplied Prism. *- */ /* Initialise */ if( reg1 ) *reg1 = NULL; if( reg2 ) *reg2 = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Store the required values.*/ *reg1 = astClone( this->region1 ); *reg2 = astClone( this->region2 ); *neg = astGetNegated( (AstRegion *) this ); } static AstRegion *GetDefUnc( AstRegion *this_region, int *status ) { /* * Name: * GetDefUnc * Purpose: * Obtain a pointer to the default uncertainty Region for a given Region. * Type: * Private function. * Synopsis: * #include "prism.h" * AstRegion *GetDefUnc( AstRegion *this ) * Class Membership: * Prism method (over-rides the astGetDefUnc method inherited from * the Region class). * This function returns a pointer to a Region which represents the * default uncertainty associated with a position on the boundary of the * given Region. The returned Region refers to the base Frame within the * FrameSet encapsulated by the supplied Region. * Parameters: * this * Pointer to the Region. * Returned Value: * A pointer to the Region. This should be annulled (using astAnnul) * when no longer needed. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *bunc1; /* Uncertainty Region for 1st component */ AstRegion *bunc2; /* Uncertainty Region for 2nd component */ AstRegion *result; /* Returned pointer */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Construct a default uncertainty Region from the uncertainty Regions in the two component Regions. The current Frames in the component Regions are equivalent to the base Frame in the parent Region structure. So we may need to map the component uncertainty into the current Region of the parent if required later on. */ bunc1 = astGetUncFrm( this->region1, AST__CURRENT ); bunc2 = astGetUncFrm( this->region2, AST__CURRENT ); /* Combine them into a Prism. */ result = (AstRegion *) astPrism( bunc1, bunc2, "", status ); /* Free resources. */ bunc1 = astAnnul( bunc1 ); bunc2 = astAnnul( bunc2 ); /* Return NULL if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the required pointer. */ return result; } void astInitPrismVtab_( AstPrismVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPrismVtab * Purpose: * Initialise a virtual function table for a Prism. * Type: * Protected function. * Synopsis: * #include "prism.h" * void astInitPrismVtab( AstPrismVtab *vtab, const char *name ) * Class Membership: * Prism vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Prism 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 */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPrism) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; frame = (AstFrameVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_maplist = mapping->MapList; mapping->MapList = MapList; parent_getdefunc = region->GetDefUnc; region->GetDefUnc = GetDefUnc; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_equal = object->Equal; object->Equal = Equal; parent_clearclosed = region->ClearClosed; region->ClearClosed = ClearClosed; parent_clearmeshsize = region->ClearMeshSize; region->ClearMeshSize = ClearMeshSize; parent_setclosed = region->SetClosed; region->SetClosed = SetClosed; parent_setmeshsize = region->SetMeshSize; region->SetMeshSize = SetMeshSize; parent_getfillfactor = region->GetFillFactor; region->GetFillFactor = GetFillFactor; parent_overlapx = region->OverlapX; region->OverlapX = OverlapX; parent_regsetattrib = region->RegSetAttrib; region->RegSetAttrib = RegSetAttrib; parent_regclearattrib = region->RegClearAttrib; region->RegClearAttrib = RegClearAttrib; parent_getregionbounds = region->GetRegionBounds; region->GetRegionBounds = GetRegionBounds; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->Decompose = Decompose; region->RegBaseBox = RegBaseBox; region->RegBaseMesh = RegBaseMesh; region->RegPins = RegPins; region->GetBounded = GetBounded; region->RegCentre = RegCentre; region->Overlap = Overlap; region->RegBasePick = RegBasePick; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "Prism", "Region extrusion into higher dimensions" ); /* 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) ); } } #if defined(THREAD_SAFE) static int ManageLock( AstObject *this_object, int mode, int extra, AstObject **fail, int *status ) { /* * Name: * ManageLock * Purpose: * Manage the thread lock on an Object. * Type: * Private function. * Synopsis: * #include "object.h" * AstObject *ManageLock( AstObject *this, int mode, int extra, * AstObject **fail, int *status ) * Class Membership: * CmpMap member function (over-rides the astManageLock protected * method inherited from the parent class). * Description: * This function manages the thread lock on the supplied Object. The * lock can be locked, unlocked or checked by this function as * deteremined by parameter "mode". See astLock for details of the way * these locks are used. * Parameters: * this * Pointer to the Object. * mode * An integer flag indicating what the function should do: * * AST__LOCK: Lock the Object for exclusive use by the calling * thread. The "extra" value indicates what should be done if the * Object is already locked (wait or report an error - see astLock). * * AST__UNLOCK: Unlock the Object for use by other threads. * * AST__CHECKLOCK: Check that the object is locked for use by the * calling thread (report an error if not). * extra * Extra mode-specific information. * fail * If a non-zero function value is returned, a pointer to the * Object that caused the failure is returned at "*fail". This may * be "this" or it may be an Object contained within "this". Note, * the Object's reference count is not incremented, and so the * returned pointer should not be annulled. A NULL pointer is * returned if this function returns a value of zero. * status * Pointer to the inherited status variable. * Returned Value: * A local status value: * 0 - Success * 1 - Could not lock or unlock the object because it was already * locked by another thread. * 2 - Failed to lock a POSIX mutex * 3 - Failed to unlock a POSIX mutex * 4 - Bad "mode" value supplied. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Prism structure. */ this = (AstPrism *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->region1, mode, extra, fail ); if( !result ) result = astManageLock( this->region2, mode, extra, fail ); return result; } #endif static int MapList( AstMapping *this_mapping, int series, int invert, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapList * Purpose: * Decompose a Prism into a sequence of simpler Regions. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapList( AstMapping *this, int series, int invert, int *nmap, * AstMapping ***map_list, int **invert_list ) * Class Membership: * Prism member function (over-rides the protected astMapList * method inherited from the Region class). * Description: * This function decomposes a Prism into a sequence of simpler * Regions which may be applied in parallel to achieve the same * effect. The Prism is decomposed as far as possible, but it is * not guaranteed that this will necessarily yield any more than * one Region, which may actually be the original Prism supplied. * Parameters: * this * Pointer to the Prism to be decomposed (the Prism is not * actually modified by this function). * series * Prisms always apply their component Regions in parallel, so this * value should always be zero. This function will return without * action if it is non-zero. * invert * Inverting a Region has no effect on the properties of the Region * and so this parameter is ignored. * nmap * The address of an int which holds a count of the number of * individual Regions in the decomposition. On entry, this * should count the number of Regions already in the * "*map_list" array (below). On exit, it is updated to include * any new Regions appended by this function. * map_list * Address of a pointer to an array of Region pointers. On * entry, this array pointer should either be NULL (if no * Regions have yet been obtained) or should point at a * dynamically allocated array containing Region pointers * ("*nmap" in number) which have been obtained from a previous * invocation of this function. * * On exit, the dynamic array will be enlarged to contain any * new Region pointers that result from the decomposition * requested. These pointers will be appended to any previously * present, and the array pointer will be updated as necessary * to refer to the enlarged array (any space released by the * original array will be freed automatically). * * The new Region pointers returned will identify a sequence of * Regions which, when applied (in parallel) in order, will be * equivalent to the original Prism. * * All the Region pointers returned by this function should be * annulled by the caller, using astAnnul, when no longer * required. The dynamic array holding these pointers should * also be freed, using astFree. * invert_list * Address of a pointer to an array of int. On entry, this array * pointer should either be NULL (if no Regions have yet been * obtained) or should point at a dynamically allocated array * containing Invert attribute values ("*nmap" in number) which * have been obtained from a previous invocation of this * function. * * On exit, the dynamic array will be enlarged to contain any * new Invert attribute values that result from the * decomposition requested. These values will be appended to any * previously present, and the array pointer will be updated as * necessary to refer to the enlarged array (any space released * by the original array will be freed automatically). * * The new Invert values returned will always be zero since a * Region is unaffected by its Invert setting. * * The dynamic array holding these values should be freed by the * caller, using astFree, when no longer required. * Returned Value: * Zero is always returned. * Notes: * - It is unspecified to what extent the original Prism and the * individual (decomposed) Regions are * inter-dependent. Consequently, the individual Regions cannot be * modified without risking modification of the original Prism. * - If this function is invoked with the global error status set, * or if it should fail for any reason, then the *nmap value, the * list of Region pointers and the list of Invert values will all * be returned unchanged. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the Prism structure. */ this = (AstPrism *) this_mapping; /* When considered as a CmpMap, a Prism always combines its component Mappings (Regions) in parallel. So check that a parallel decomposition was requested. */ if ( ! series ) { /* Concatenate the Mapping lists obtained from each component Region. */ (void) astMapList( (AstMapping *) this->region1, 0, 0, nmap, map_list, invert_list ); (void) astMapList( (AstMapping *) this->region2, 0, 0, nmap, map_list, invert_list ); /* If the Prism does not combine its components in the way required by the decomposition (series or parallel), then we cannot decompose it. In this case it must be appended to the Mapping list as a single entity. We can use the parent class method to do this. */ } else { (void) ( *parent_maplist )( this_mapping, series, invert, nmap, map_list, invert_list, status ); } return 0; } static int Overlap( AstRegion *this, AstRegion *that, int *status ){ /* * Name: * Overlap * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "prism.h" * int Overlap( AstRegion *this, AstRegion *that, int *status ) * Class Membership: * Prism member function (over-rides the astOverlap method inherited * from the Region class). * Description: * This function returns an integer value indicating if the two * supplied Regions overlap. The two Regions are converted to a commnon * coordinate system before performing the check. If this conversion is * not possible (for instance because the two Regions represent areas in * different domains), then the check cannot be performed and a zero value * is returned to indicate this. * Parameters: * this * Pointer to the first Region. * that * Pointer to the second Region. * status * Pointer to the inherited status variable. * Returned Value: * astOverlap() * A value indicating if there is any overlap between the two Regions. * Possible values are: * * 0 - The check could not be performed because the second Region * could not be mapped into the coordinate system of the first * Region. * * 1 - There is no overlap between the two Regions. * * 2 - The first Region is completely inside the second Region. * * 3 - The second Region is completely inside the first Region. * * 4 - There is partial overlap between the two Regions. * * 5 - The Regions are identical. * * 6 - The second Region is the negation of the first Region. * Notes: * - The returned values 5 and 6 do not check the value of the Closed * attribute in the two Regions. * - A value of zero will be returned if this function is invoked with the * AST error status set, or if it should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; AstFrame *efrm; AstFrameSet *fs; AstMapping *bmap; AstMapping *emap; AstMapping *map1; AstMapping *map2; AstMapping *map; AstMapping *smap; AstRegion *that_base2; AstRegion *that_base; AstRegion *that_ext2; AstRegion *that_ext; AstRegion *this_reg1; AstRegion *this_reg2; int *inax; int *outax; int i; int nbase; int next; int rbase; int result; int rext; int that_neg; int this_neg; /* A table indicating how to combine together the overlap state of the extrusion Regions with the overlap state of the other (base) Region. The first index represents the value returned by the astOverlap method when used to determine the overlap of the base Regions in the two supplied Prisms. The second index represents the value returned by the astOverlap method when used to determine the overlap of the extrusion Regions in the two supplied Prisms. The integer values stored in the array represent the astOverlap value describing the overlap of the two Prisms. */ static int rtable[ 7 ][ 7 ] = { { 0, 0, 0, 0, 0, 0, 0 }, { 0, 1, 1, 1, 1, 1, 1 }, { 0, 1, 2, 4, 4, 2, 1 }, { 0, 1, 4, 3, 4, 3, 1 }, { 0, 1, 4, 4, 4, 4, 1 }, { 0, 1, 2, 3, 4, 5, 1 }, { 0, 1, 1, 1, 1, 1, 6 } }; /* Initialise */ result = 0; /* Check the inherited status. */ if ( !astOK ) return result; /* Get pointers to the base and extrusion Regions within "this", and also the nagated flag. */ GetRegions( (AstPrism *) this, &this_reg1, &this_reg2, &this_neg, status ); /* Get the number of axes in the base and extrusion Regions of "this". */ nbase = astGetNaxes( this_reg1 ); next = astGetNaxes( this_reg2 ); /* Get a FrameSet which goes from the Frame represented by "this" to the Frame represented by "that". Check that the conection is defined. */ fs = astConvert( this, that, "" ); if( fs ) { /* Get the forward Mapping from the above FrameSet. */ map2 = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Get a pointer to the Mapping from base to current Frame in "this". */ map1 = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); /* Combine these Mappings to get the Mapping from the base Frame of "this" to the current Frame of "that". */ map = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); /* Simplify this Mapping. */ smap = astSimplify( map ); /* See if the extrusion axes in "this" correspond to a unique set of axes in the current Frame of "that". */ inax = astMalloc( sizeof(int)*(size_t)next ); for( i = 0; i < next; i++ ) inax[ i ] = nbase + i; outax = astMapSplit( smap, next, inax, &emap ); /* If they do, attempt to create a Region by picking the axes from "that" that correspond to the extrusion axes in "this". */ if( emap && astGetNout( emap ) == next ) { that_ext = (AstRegion *) astPickAxes( that, next, outax, NULL ); /* If the picked axes formed a Region, see if the base axes can also be picked in the same way. */ if( astIsARegion( that_ext ) ) { outax = astFree( outax ); inax = astGrow( inax, (size_t)nbase, sizeof( int ) ); for( i = 0; i < nbase; i++ ) inax[ i ] = i; outax = astMapSplit( smap, nbase, inax, &bmap ); if( bmap && astGetNout( bmap ) == nbase ) { that_base = (AstRegion *) astPickAxes( that, nbase, outax, NULL ); if( astIsARegion( that_base ) ) { /* Map the two Regions picked from "that" into the Frames of the two sub-regions within "this". */ astInvert( emap ); efrm = astGetFrame( this_reg2->frameset, AST__CURRENT ); that_ext2 = astMapRegion( that_ext, emap, efrm ); astInvert( bmap ); bfrm = astGetFrame( this_reg1->frameset, AST__CURRENT ); that_base2 = astMapRegion( that_base, bmap, bfrm ); /* We can test separately for overlap of the two extrusion Regions, and for overlap of the two base Regions, and then combine the returned flags to represent overlap of the whole Prism. */ rbase = astOverlap( this_reg1, that_base2 ); rext = astOverlap( this_reg2, that_ext2 ); result = rtable[ rbase ][ rext ]; /* The values in the rtable array assume that neither of the supplied Prisms have been negated. Modify the value obtained from rtable to take account of negation of either or both of the supplied Prisms. */ that_neg = astGetNegated( that ); if( this_neg ) { if( that_neg ) { if( result == 1 ) { result = 4; } else if( result == 2 ) { result = 3; } else if( result == 3 ) { result = 2; } } else { if( result == 1 ) { result = 3; } else if( result == 2 ) { result = 4; } else if( result == 3 ) { result = 1; } else if( result == 5 ) { result = 6; } else if( result == 6 ) { result = 5; } } } else if( that_neg ){ if( result == 1 ) { result = 2; } else if( result == 2 ) { result = 1; } else if( result == 3 ) { result = 4; } else if( result == 5 ) { result = 6; } else if( result == 6 ) { result = 5; } } /* Free resources */ efrm = astAnnul( efrm ); that_ext2 = astAnnul( that_ext2 ); bfrm = astAnnul( bfrm ); that_base2 = astAnnul( that_base2 ); } that_base = astAnnul( that_base ); bmap = astAnnul( bmap ); } } emap = astAnnul( emap ); that_ext = astAnnul( that_ext ); } outax = astFree( outax ); inax = astFree( inax ); smap = astAnnul( smap ); map = astAnnul( map ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); fs = astAnnul( fs ); } this_reg1 = astAnnul( this_reg1 ); this_reg2 = astAnnul( this_reg2 ); /* If overlap could not be determined using the above implementation, try using the implementation inherited from the parent Region class. Use OverlapX rather than Overlap since a) it is OverlapX that does the work, and b) calling Overlap could end us in an infinite loop. */ if( !result ) result = (*parent_overlapx)( this, that, status ); /* If not OK, return zero. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static int OverlapX( AstRegion *that, AstRegion *this, int *status ){ /* * Name: * OverlapX * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "prism.h" * int OverlapX( AstRegion *that, AstRegion *this ) * Class Membership: * Prism member function (over-rides the astOverlapX method inherited * from the Region class). * Description: * This function performs the processing for the public astOverlap * method and has exactly the same interface except that the order * of the two arguments is swapped. This is a trick to allow * the astOverlap method to be over-ridden by derived classes on * the basis of the class of either of its two arguments. * * See the astOverlap method for details of the interface. */ /* Local Variables; */ int result; /* Check the global error status. */ if ( !astOK ) return 0; /* We know that "that" is a Prism, so call the private Overlap method, and then modify the returned value to take account of the fact that the two Regions are swapped. */ result = Overlap( that, this, status ); if( result == 2 ){ result = 3; } else if( result == 3 ){ result = 2; } return result; } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "prism.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, * int *status ) * Class Membership: * Prism member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ int nax; /* Number of axes in Frame */ int neg; /* Negated flag for Prism */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Prism structure */ this = (AstPrism *) this_region; /* Get pointers to the component Regions. */ GetRegions( this, ®1, ®2, &neg, status ); /* The base Frame of the parent Region structure is equivalent to a CmpFrame containing the current Frames of the component Regions. Get the no. of axes in the first component Frame. */ nax = astGetNaxes( reg1 ); /* Get the bounding boxes of the component Regions in these Frame, storing the values in the supplied arrays. */ astGetRegionBounds( reg1, lbnd, ubnd ); astGetRegionBounds( reg2, lbnd + nax, ubnd + nax ); /* Free resources.*/ reg1 = astAnnul( reg1 ); reg2 = astAnnul( reg2 ); } static AstPointSet *RegBaseMesh( AstRegion *this_region, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "prism.h" * AstPointSet *RegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Prism member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. Annul the pointer using astAnnul when it * is no longer needed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstPointSet *grid1; /* PointSet holding grid for region1 */ AstPointSet *grid2; /* PointSet holding grid for region2 */ AstPointSet *mesh1; /* PointSet holding mesh for region1 */ AstPointSet *mesh2; /* PointSet holding mesh for region2 */ AstPointSet *result; /* Returned pointer */ AstPrism *this; /* The Prism structure */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ double **pg1; /* Pointer to grid1 arrays */ double **pg2; /* Pointer to grid2 arrays */ double **pm1; /* Pointer to mesh1 arrays */ double **pm2; /* Pointer to mesh2 arrays */ double **ptr; /* Pointer to returned mesh arrays */ int gsz1; /* Preferred grid size for region1 */ int gsz2; /* Preferred grid size for region2 */ int hasMesh1; /* Does 1st component Region have a mesh? */ int hasMesh2; /* Does 2nd component Region have a mesh? */ int i; /* Index of next mesh position */ int ii; /* Index of next results position */ int j; /* Index of next grid position */ int jc; /* Axis index */ int msz1; /* Preferred mesh size for region1 */ int msz2; /* Preferred mesh size for region2 */ int msz; /* Original MeshSize */ int mszp; /* MeshSize value for Prism */ int nax1; /* Number of axes in region1 */ int nax2; /* Number of axes in region2 */ int nax; /* Number of axes in Prism */ /* Initialise */ result= NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this_region->basemesh ) { result = astClone( this_region->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Get pointers to the component regions. */ reg1 = this->region1; reg2 = this->region2; /* A mesh can only be produced for a Region if it is bounded when either negated or un-negated. See if meshes can be produced for the component Regions. */ hasMesh1 = astGetBounded( reg1 ); if( !hasMesh1 ){ astNegate( reg1 ); hasMesh1 = astGetBounded( reg1 ); astNegate( reg1 ); } hasMesh2 = astGetBounded( reg2 ); if( !hasMesh2 ){ astNegate( reg2 ); hasMesh2 = astGetBounded( reg2 ); astNegate( reg2 ); } /* If either Region does not have a mesh we cannot produce a mesh for the Prism. */ if( !hasMesh1 || !hasMesh2 ) { if( astOK ) astError( AST__INTER, "astRegBaseMesh(%s): No mesh " "can be produced for the %s bacause one of its component " "Regions is unbounded.", status, astGetClass( this ), astGetClass( this ) ); /* Otherwise we can create a mesh for the Prism. */ } else { /* Determine the grid sizes and mesh sizes to use for the two components. This aims to produce a total number of points in the returned Prism mesh roughly equal to the MeshSize attribute of the Prism. It also aims to divide the mesh points equally between the end faces of the prism, and the side walls. We remember that the grid used to represent any 1-D region always has a size of 2, regardless of the setting of MeshSize. */ mszp = astGetMeshSize( this ); msz1 = ( astGetNaxes( reg1 ) == 1 ) ? 2 : sqrt( 0.5*mszp ); gsz2 = 0.5*mszp/msz1; msz2 = ( astGetNaxes( reg2 ) == 1 ) ? 2 : sqrt( 0.5*mszp ); gsz1 = 0.5*mszp/msz2; /* First, get a boundary mesh for the second component Region defining the prism extrusion. For instance, if the Region is 1-dimensional, this mesh will consist of the two values on the Region axis: the lower and upper bounds of the Region. */ msz = astTestMeshSize( reg2 ) ? astGetMeshSize( reg2 ) : -1; astSetMeshSize( reg2, msz2 ); mesh2 = astRegMesh( reg2 ); /* Also get a grid of points spread throughout the extent (i.e. not merely on the boundary) of the second Region. */ astSetMeshSize( reg2, gsz2 ); grid2 = astRegGrid( reg2 ); /* Re-instate the original MeshSize for the second Region. */ if( msz == -1 ) { astClearMeshSize( reg2 ); } else { astSetMeshSize( reg2, msz ); } /* Similarly, get a boundary mesh and a volume grid for the first Region. */ msz = astTestMeshSize( reg1 ) ? astGetMeshSize( reg1 ) : -1; astSetMeshSize( reg1, msz1 ); mesh1 = astRegMesh( reg1 ); astSetMeshSize( reg1, gsz1 ); grid1 = astRegGrid( reg1 ); if( msz == -1 ) { astClearMeshSize( reg1 ); } else { astSetMeshSize( reg1, msz ); } /* Note the number of axes in the two component Regions. */ nax1 = astGetNcoord( mesh1 ); nax2 = astGetNcoord( mesh2 ); /* The above mesh and grid sizes are only approximate. Find the values actually used. */ msz1 = astGetNpoint( mesh1 ); gsz1 = astGetNpoint( grid1 ); msz2 = astGetNpoint( mesh2 ); gsz2 = astGetNpoint( grid2 ); /* Create the returned PointSet. */ msz = gsz1*msz2 + msz1*gsz2; nax= astGetNaxes( this ); result = astPointSet( msz, nax, "", status ); /* Get pointers to the data in all 5 PointSets. */ ptr = astGetPoints( result ); pm1 = astGetPoints( mesh1 ); pg1 = astGetPoints( grid1 ); pm2 = astGetPoints( mesh2 ); pg2 = astGetPoints( grid2 ); /* Check pointers can be de-referenced safely. */ if( astOK ) { /* Initialise the index of the next point to be written to the results array. */ ii = 0; /* First, replicate the volume grid covering the first region at every point in the boundary mesh covering the second Region. */ for( i = 0; i < msz2; i++ ) { for( j = 0; j < gsz1; j++, ii++ ) { for( jc = 0; jc < nax1; jc++ ) { ptr[ jc ][ ii ] = pg1[ jc ][ j ]; } for( ; jc < nax; jc++ ) { ptr[ jc ][ ii ] = pm2[ jc - nax1 ][ i ]; } } } /* Now, replicate the volume grid covering the second region at every point in the boundary mesh covering the first Region. */ for( i = 0; i < msz1; i++ ) { for( j = 0; j < gsz2; j++, ii++ ) { for( jc = 0; jc < nax1; jc++ ) { ptr[ jc ][ ii ] = pm1[ jc ][ i ]; } for( ; jc < nax; jc++ ) { ptr[ jc ][ ii ] = pg2[ jc -nax1 ][ j ]; } } } } /* Free resources. */ mesh1 = astAnnul( mesh1 ); mesh2 = astAnnul( mesh2 ); grid1 = astAnnul( grid1 ); grid2 = astAnnul( grid2 ); } /* Save the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this_region->basemesh = astClone( result ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "prism.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * Prism member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *frm1; /* Axes picked from the 1st encapsulated Region */ AstFrame *frm2; /* Axes picked from the 2nd encapsulated Region */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *result; /* Returned Region */ int *axes1; /* Axes to pick from 1st input encapsulated Region */ int *axes2; /* Axes to pick from 2nd input encapsulated Region */ int i; /* Output axis index */ int j; /* Input axis index */ int nax1; /* No. of axes in 1st input encapsulated Region */ int nax2; /* No. of axes in 2nd input encapsulated Region */ int naxes1; /* No. of axes in 1st output encapsulated Region */ int naxes2; /* No. of axes in 2nd output encapsulated Region */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Prism information. */ this = (AstPrism *) this_region; /* Get the number of axes in each of the two encapsulated Regions. */ nax1 = astGetNaxes( this->region1 ); nax2 = astGetNaxes( this->region2 ); /* Allocate memory to hold the indices of the axes selected from each of the two encapsulated Regions. */ axes1 = astMalloc( sizeof( *axes1 )*nax1 ); axes2 = astMalloc( sizeof( *axes2 )*nax2 ); /* Check pointers can be used safely. */ if( astOK ) { /* Initialise the counters that count the number of axes selected from each of the two encapsulated Regions. */ naxes1 = 0; naxes2 = 0; /* For each of the axes to be selected from the prism... */ for( i = 0; i < naxes; i++ ) { j = axes[ i ]; /* ... if the current selected axis is part of the first encapsulated Region, add its index into the array that holds the axes to be selected from the first encapsulated region. Increment the number of axes selected from the first encapsulated region. */ if( j < nax1 ) { axes1[ naxes1++ ] = j; /* If the current selected axis is part of the second encapsulated Region, add its index into the array that holds the axes to be selected from the second encapsulated region. Note, the index is converted from a Prism axis index to a sub-region axis index by subtracting "nax1". Also increment the number of axes selected from the second encapsulated region. */ } else { axes2[ naxes2++ ] = j - nax1; } } /* Pick any required axes from the first sub-region. If the result of the selection is not a Region, we cannot pick the required axes, so annul the object holding the selected axes. */ if( naxes1 ) { frm1 = astPickAxes( this->region1, naxes1, axes1, NULL ); if( frm1 && !astIsARegion( frm1 ) ) frm1 = astAnnul( frm1 ); } else { frm1 = NULL; } /* Pick any required axes from the second sub-region. If the result of the selection is not a Region, we cannot pick the required axes, so annul the object holding the selected axes. */ if( naxes2 ) { frm2 = astPickAxes( this->region2, naxes2, axes2, NULL ); if( frm2 && !astIsARegion( frm2 ) ) frm2 = astAnnul( frm2 ); } else { frm2 = NULL; } /* If we are selecting axes only from the first sub-region, and the above selection was succesful, just return a clone of the Region holding the axes selected from the first sub-region. */ if( naxes1 > 0 && naxes2 == 0 && frm1 ) { result = astClone( frm1 ); /* If we are selecting axes only from the second sub-region, and the above selection was succesful, just return a clone of the Region holding the axes selected from the second sub-region. */ } else if( naxes1 == 0 && naxes2 > 0 && frm2 ) { result = astClone( frm2 ); /* If we are selecting axes from both sub-regions, and both the above selections were succesful, joing them together into a Prism. */ } else if( naxes1 > 0 && naxes2 > 0 && frm1 && frm2 ) { result = (AstRegion *) astPrism( (AstRegion *) frm1, (AstRegion *) frm2, "", status ); } /* Free resources */ if( frm1 ) frm1 = astAnnul( frm1 ); if( frm2 ) frm2 = astAnnul( frm2 ); } axes1 = astFree( axes1 ); axes2 = astFree( axes2 ); /* Return a NULL pointer if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static double *RegCentre( AstRegion *this_region, double *cen, double **ptr, int index, int ifrm, int *status ){ /* * Name: * RegCentre * Purpose: * Re-centre a Region. * Type: * Private function. * Synopsis: * #include "prism.h" * double *RegCentre( AstRegion *this, double *cen, double **ptr, * int index, int ifrm, int *status ) * Class Membership: * Prism member function (over-rides the astRegCentre protected * method inherited from the Region class). * Description: * This function shifts the centre of the supplied Region to a * specified position, or returns the current centre of the Region. * Parameters: * this * Pointer to the Region. * cen * Pointer to an array of axis values, giving the new centre. * Supply a NULL value for this in order to use "ptr" and "index" to * specify the new centre. * ptr * Pointer to an array of points, one for each axis in the Region. * Each pointer locates an array of axis values. This is the format * returned by the PointSet method astGetPoints. Only used if "cen" * is NULL. * index * The index of the point within the arrays identified by "ptr" at * which is stored the coords for the new centre position. Only used * if "cen" is NULL. * ifrm * Should be AST__BASE or AST__CURRENT. Indicates whether the centre * position is supplied and returned in the base or current Frame of * the FrameSet encapsulated within "this". * status * Pointer to the inherited status variable. * Returned Value: * If both "cen" and "ptr" are NULL then a pointer to a newly * allocated dynamic array is returned which contains the centre * coords of the Region. This array should be freed using astFree when * no longer needed. If either of "ptr" or "cen" is not NULL, then a * NULL pointer is returned. * Notes: * - Some Region sub-classes do not have a centre. Such classes will report * an AST__INTER error code if this method is called with either "ptr" or * "cen" not NULL. If "ptr" and "cen" are both NULL, then no error is * reported if this method is invoked on a Region of an unsuitable class, * but NULL is always returned. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism structure */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ double *bc; /* Base Frame centre position */ double *cen1; /* Centre of first component Region */ double *cen2; /* Centre of second component Region */ double *result; /* Returned pointer */ double *tmp; /* Temporary array pointer */ double *total; /* Pointer to total base Frame centre array */ int i; /* Coordinate index */ int nax1; /* Number of axes in first component Region */ int nax2; /* Number of axes in second component Region */ int ncb; /* Number of base frame coordinate values per point */ int ncc; /* Number of current frame coordinate values per point */ int neg; /* Prism negated flag */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Get the component Regions, and the Negated flag for the Prism. */ GetRegions( this, ®1, ®2, &neg, status ); /* Get the number of current Frame axes in each component Region. The sum of these will equal the number of base Frame axes in the parent Region structure. */ nax1 = astGetNaxes( reg1 ); nax2 = astGetNaxes( reg2 ); ncb = nax1 + nax2; /* If we are getting (not setting) the current centre... */ if( !ptr && !cen ) { /* Get the centre from the two component Regions in their current Frames. */ cen1 = astRegCentre( reg1, NULL, NULL, 0, AST__CURRENT ); cen2 = astRegCentre( reg2, NULL, NULL, 0, AST__CURRENT ); /* If both component regions are re-centerable, join the two centre arrays together into a single array. */ if( cen1 && cen2 ) { total = astMalloc( sizeof(double)*(size_t)ncb ); if( total ) { for( i = 0; i < nax1; i++ ) total[ i ] = cen1[ i ]; for( i = 0; i < nax2; i++ ) total[ i + nax1 ] = cen2[ i ]; /* The current Frames of the component Regions correspond to the base Frame of the parent Region structure. If the original centre is required in the current Frame, transform it using the base->current Mapping from the parent Region structure. */ if( ifrm == AST__CURRENT ) { result = astRegTranPoint( this_region, total, 1, 1 ); total = astFree( total ); } else { result = total; } } } /* Free the individual centre arrays. */ cen1 = astFree( cen1 ); cen2 = astFree( cen2 ); /* If we are setting a new centre... */ } else { /* If the new centre is supplied in the current Frame of the parent Region structure, transform it into the base Frame (i.e. the Frames represented by the component Regions). */ if( ifrm == AST__CURRENT ) { if( cen ) { bc = astRegTranPoint( this_region, cen, 1, 0 ); } else { ncc = astGetNaxes( this_region ); tmp = astMalloc( sizeof( double)*(size_t)ncc ); if( astOK ) { for( i = 0; i < ncc; i++ ) tmp[ i ] = ptr[ i ][ index ]; } bc = astRegTranPoint( this_region, tmp, 1, 0 ); tmp = astFree( tmp ); } } else { if( cen ) { bc = cen; } else { bc = astMalloc( sizeof( double)*(size_t)ncb ); if( astOK ) { for( i = 0; i < ncb; i++ ) bc[ i ] = ptr[ i ][ index ]; } } } /* Set the centre in the two component Regions in their current Frames. */ astRegCentre( reg1, bc, NULL, 0, AST__CURRENT ); astRegCentre( reg2, bc + nax1, NULL, 0, AST__CURRENT ); /* Free resources. */ if( bc != cen ) bc = astFree( bc ); } reg1 = astAnnul( reg1 ); reg2 = astAnnul( reg2 ); /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Prism. * Type: * Private function. * Synopsis: * #include "prism.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Prism member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Prism. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Prism "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Prism. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstPointSet *ps1; /* Points projected into 1st component Region */ AstPointSet *ps1b; /* "ps1" in base Frame of 1st component Region */ AstPointSet *ps1b2; /* "ps1b" transformed using 1st Region */ AstPointSet *ps2b2; /* "ps2b" transformed using 2nd Region */ AstPointSet *ps2; /* Points projected into 2nd component Region */ AstPointSet *ps2b; /* "ps2" in base Frame of 2nd component Region */ AstPrism *this; /* Pointer to the Prism structure. */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ AstRegion *unc1; /* Base Frame uncertainty in 1st component Region */ AstRegion *unc2; /* Base Frame uncertainty in 2nd component Region */ double **ptr1b2; /* Pointer to axis values in "ps1b2" */ double **ptr2b2; /* Pointer to axis values in "ps2b2" */ int *mask1; /* Mask for first component boundary */ int *mask2; /* Mask for second component boundary */ int cl1; /* Original Closed flag for reg1 */ int cl2; /* Original Closed flag for reg2 */ int i; /* Point index */ int j; /* Axis index */ int nax1; /* Number of axes in first component Region */ int nax2; /* Number of axes in second component Region */ int np; /* Number of points in supplied PointSet */ int on; /* Is this point on the Prism boundary? */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Get pointers to the two component Regions. */ reg1 = this->region1; reg2 = this->region2; /* Temporarily ensure the components are closed. */ cl1 = astTestClosed( reg1 ) ? astGetClosed( reg1 ) : INT_MAX; cl2 = astTestClosed( reg2 ) ? astGetClosed( reg2 ) : INT_MAX; astSetClosed( reg1, cl1 ); astSetClosed( reg2, cl2 ); /* A point in the coordinate system represented by the Prism is on the boundary of the Prism if: 1) it is on the boundary of one of the coomponent Regions AND 2) it is on or within the boundary of the other component Region. First look for points on the boundary of the first component Region. Create a PointSet holding just the axes from the supplied PointSet which relate to the first component Region. */ np = astGetNpoint( pset ); nax1 = astGetNaxes( reg1 ); ps1 = astPointSet( np, nax1, "", status ); astSetSubPoints( pset, 0, 0, ps1 ); /* Get a mask which indicates if each supplied point is on or off the boundary of the first component Region. astRegPins expects its "pset" argument to contain positions in the base Frame of the Region, so we must first transform the supplied points into the base Frame of "reg1". We must also get the uncertainty in the base Frame of the component Region. */ ps1b = astRegTransform( reg1, ps1, 0, NULL, NULL ); unc1 = astGetUncFrm( reg1, AST__BASE ); astRegPins( reg1, ps1b, unc1, &mask1 ); /* Also determine which of the points are on or in the boundary by using "reg1" as a Mapping to transform the supplied points. */ ps1b2 = astTransform( reg1, ps1b, 1, NULL ); /* Do the same for the second component Region */ nax2 = astGetNaxes( reg2 ); ps2 = astPointSet( np, nax2, "", status ); astSetSubPoints( pset, 0, nax1, ps2 ); ps2b = astRegTransform( reg2, ps2, 0, NULL, NULL ); unc2 = astGetUncFrm( reg2, AST__BASE ); astRegPins( reg2, ps2b, unc2, &mask2 ); ps2b2 = astTransform( reg2, ps2b, 1, NULL ); /* Get pointers to the data in all the relevant PointSets. */ ptr1b2 = astGetPoints( ps1b2 ); ptr2b2 = astGetPoints( ps2b2 ); /* Check pointers can be dereferenced safely. */ if( astOK ) { /* Assume all points are on the boundary of the Prism. */ result = 1; /* Check each point. */ for( i = 0; i < np; i++ ) { /* Assume this point is on the boundary of the Prism. */ on = 1; /* If this point is on the boundary of both component Regions, it is on the boundary of the Prism. If it is on the boundary of the first component Region but not on the boundary of the second, then it is still on the boundary of the Prism if it is within the volume reporesented by the second. */ if( mask1[ i ] ) { if( !mask2[ i ] ) { for( j = 0; j < nax2; j++ ) { if( ptr2b2[ j ][ i ] == AST__BAD ) { on = 0; break; } } } /* If this point is on the boundary of the second component Region but not the first, it is on the boundary of the Prism if it is within the volume reporesented by the first. */ } else { if( mask2[ i ] ) { for( j = 0; j < nax1; j++ ) { if( ptr1b2[ j ][ i ] == AST__BAD ) { on = 0; break; } } /* If this point is on the boundary of neither component Region, it is not on the boundary of the Prism. */ } else { on = 0; } } /* Use "mask1" to return the Prism's mask. Clear the returned flag if this point is not on the boundary of the Prism. */ mask1[ i ] = on; if( !on ) result = 0; } } /* Re-instate the original values of the Closed attribute for the component Regions. */ if( cl1 == INT_MAX ) { astClearClosed( reg1 ); } else { astSetClosed( reg1, cl1 ); } if( cl2 == INT_MAX ) { astClearClosed( reg2 ); } else { astSetClosed( reg2, cl2 ); } /* Return "mask1" as the Prism's mask if required. Otherwise free it. */ if( mask ) { *mask = mask1; } else { mask1 = astFree( mask1 ); } /* Free other resources */ mask2 = astFree( mask2 ); ps1 = astAnnul( ps1 ); ps1b = astAnnul( ps1b ); ps1b2 = astAnnul( ps1b2 ); ps2 = astAnnul( ps2 ); unc1 = astAnnul( unc1 ); ps2b = astAnnul( ps2b ); ps2b2 = astAnnul( ps2b2 ); unc2 = astAnnul( unc2 ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static void RegClearAttrib( AstRegion *this_region, const char *attrib, char **base_attrib, int *status ) { /* * Name: * RegClearAttrib * Purpose: * Clear an attribute value for a Region. * Type: * Private function. * Synopsis: * #include "prism.h" * void RegClearAttrib( AstRegion *this, const char *attrib, * char **base_attrib, int *status ) * Class Membership: * Prism member function (over-rides the astRegClearAttrib method * inherited from the Region class). * Description: * This function clears the value of a named attribute in both the base * and current Frame in the FrameSet encapsulated within a Region, without * remapping either Frame. * * No error is reported if the attribute is not recognised by the base * Frame. * Parameters: * this * Pointer to the Region. * attrib * Pointer to a null terminated string holding the attribute name. * NOTE, IT SHOULD BE ENTIRELY LOWER CASE. * base_attrib * Address of a location at which to return a pointer to the null * terminated string holding the attribute name which was cleared in * the base Frame of the encapsulated FrameSet. This may differ from * the supplied attribute if the supplied attribute contains an axis * index and the current->base Mapping in the FrameSet produces an * axis permutation. The returned pointer should be freed using * astFree when no longer needed. A NULL pointer may be supplied in * which case no pointer is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPrism *this; AstRegion *creg; char *batt; char buf1[ 100 ]; char buf2[ 255 ]; int axis; int len; int nax1; int nc; int rep; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Use the RegClearAttrib method inherited from the parent class to clear the attribute in the current and base Frames in the FrameSet encapsulated by the parent Region structure. */ (*parent_regclearattrib)( this_region, attrib, &batt, status ); /* We now propagate the setting down to the component Regions. The current Frames in the component Regions together form a CmpFrame which is equivalent to the base Frame in the parent FrameSet. Switch off error reporting whilst we apply the setting to the component Regions. */ rep = astReporting( 0 ); /* If the setting which was applied to the base Frame of the parent FrameSet is qualified by an axis index, modify the axis index to refer to component Region which defines the axis. First parse the base Frame attribute setting to locate any axis index. */ len = strlen( batt ); if( nc = 0, ( 2 == astSscanf( batt, "%[^(](%d) %n", buf1, &axis, &nc ) ) && ( nc >= len ) ) { /* If found, convert the axis index from one-based to zero-based. */ axis--; /* Get a pointer to the component Region containing the specified axis, and create a new setting with the same attribute name but with the axis index appropriate to the component Region which defines the axis. */ nax1 = astGetNaxes( this->region1 ); if( axis < nax1 ) { creg = this->region1; } else { creg = this->region2; axis -= nax1; } sprintf( buf2, "%s(%d)", buf1, axis + 1 ); /* Apply the setting to the relevant component Region. */ astRegClearAttrib( creg, buf2, NULL ); /* If the setting is not qualified by an axis index, apply it to both component Regions. */ } else { astRegClearAttrib( this->region1, batt, NULL ); astRegClearAttrib( this->region2, batt, NULL ); } /* Annul the error if the attribute was not recognised by the component Regions. Then switch error reporting back on. */ if( astStatus == AST__BADAT ) astClearStatus; astReporting( rep ); /* If required, return the base Frame setting string. Otherwise free it. */ if( base_attrib ) { *base_attrib = batt; } else { batt = astFree( batt ); } } static void RegSetAttrib( AstRegion *this_region, const char *setting, char **base_setting, int *status ) { /* * Name: * RegSetAttrib * Purpose: * Set an attribute value for a Region. * Type: * Private function. * Synopsis: * #include "prism.h" * void RegSetAttrib( AstRegion *this, const char *setting, * char **base_setting, int *status ) * Class Membership: * Prism method (over-rides the astRegSetAttrib method inherited from * the Region class). * Description: * This function assigns an attribute value to both the base and * current Frame in the FrameSet encapsulated within a Region, without * remapping either Frame. * * No error is reported if the attribute is not recognised by the base * Frame. * Parameters: * this * Pointer to the Region. * setting * Pointer to a null terminated attribute setting string. NOTE, IT * SHOULD BE ENTIRELY LOWER CASE. The supplied string will be * interpreted using the public interpretation implemented by * astSetAttrib. This can be different to the interpretation of the * protected accessor functions. For instance, the public * interpretation of an unqualified floating point value for the * Epoch attribute is to interpet the value as a gregorian year, * but the protected interpretation is to interpret the value as an * MJD. * base_setting * Address of a location at which to return a pointer to the null * terminated attribute setting string which was applied to the * base Frame of the encapsulated FrameSet. This may differ from * the supplied setting if the supplied setting contains an axis * index and the current->base Mapping in the FrameSet produces an * axis permutation. The returned pointer should be freed using * astFree when no longer needed. A NULL pointer may be supplied in * which case no pointer is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPrism *this; AstRegion *creg; char *bset; char buf1[ 100 ]; char buf2[ 255 ]; int axis; int len; int nax1; int nc; int rep; int value; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Prism structure. */ this = (AstPrism *) this_region; /* Use the RegSetAttrib method inherited from the parent class to apply the setting to the current and base Frames in the FrameSet encapsulated by the parent Region structure. */ (*parent_regsetattrib)( this_region, setting, &bset, status ); /* We now propagate the setting down to the component Regions. The current Frames in the component Regions together form a CmpFrame which is equivalent to the base Frame in the parent FrameSet. Switch off error reporting whilst we apply the setting to the component Regions. */ rep = astReporting( 0 ); /* If the setting which was applied to the base Frame of the parent FrameSet is qualified by an axis index, modify the axis index to refer to component Region which defines the axis. First parse the base Frame attribute setting to locate any axis index. */ len = strlen( bset ); if( nc = 0, ( 2 == astSscanf( bset, "%[^(](%d)= %n%*s %n", buf1, &axis, &value, &nc ) ) && ( nc >= len ) ) { /* If found, convert the axis index from one-based to zero-based. */ axis--; /* Get a pointer to the component Region containing the specified axis, and create a new setting with the same attribute name but with the axis index appropriate to the component Region which defines the axis. */ nax1 = astGetNaxes( this->region1 ); if( axis < nax1 ) { creg = this->region1; } else { creg = this->region2; axis -= nax1; } sprintf( buf2, "%s(%d)=%s", buf1, axis + 1, bset + value ); /* Apply the setting to the relevant component Region. */ astRegSetAttrib( creg, buf2, NULL ); /* If the setting is not qualified by an axis index, apply it to both component Regions. */ } else { astRegSetAttrib( this->region1, bset, NULL ); astRegSetAttrib( this->region2, bset, NULL ); } /* Annul the error if the attribute was not recognised by the component Regions. Then switch error reporting back on. */ if( astStatus == AST__BADAT ) astClearStatus; astReporting( rep ); /* If required, return the base Frame setting string. Otherwise free it. */ if( base_setting ) { *base_setting = bset; } else { bset = astFree( bset ); } } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "prism.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Prism method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *cfrm; /* Frame containing required axes */ AstRegion *creg; /* Pointer to component Region structure */ int *axes; /* Pointer to array of axis indices */ int i; /* Loop count */ int nax1; /* No.of axes in 1st component Frame */ int nax2; /* No.of axes in 2nd component Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* If either component Region has a dummy FrameSet use this method recursively to give them a FrameSet containing the corresponding axes from the supplied Frame. */ creg = ((AstPrism *) this_region )->region1; if( creg ) { nax1 = astGetNaxes( creg ); if( !astGetRegionFS( creg ) ) { axes = astMalloc( sizeof( int )*(size_t) nax1 ); if( astOK ) for( i = 0; i < nax1; i++ ) axes[ i ] = i; cfrm = astPickAxes( frm, nax1, axes, NULL ); astSetRegFS( creg, cfrm ); axes = astFree( axes ); cfrm = astAnnul( cfrm ); } } else { nax1 = 0; } creg = ((AstPrism *) this_region )->region2; if( creg && !astGetRegionFS( creg ) ) { nax2 = astGetNaxes( creg ); axes = astMalloc( sizeof( int )*(size_t) nax2 ); if( astOK ) for( i = 0; i < nax2; i++ ) axes[ i ] = nax1 + i; cfrm = astPickAxes( frm, nax2, axes, NULL ); astSetRegFS( creg, cfrm ); axes = astFree( axes ); cfrm = astAnnul( cfrm ); } } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify a Region. * Type: * Private function. * Synopsis: * #include "region.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Prism method (over-rides the astSimplify method inherited from * the Region class). * Description: * This function simplifies a Prism 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 Region. * status * Pointer to the inherited status variable. * Returned Value: * A new pointer to the (possibly simplified) Region. * 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. * Deficiencies: * - Currently, this function does not attempt to map the component * Regions into the current Frame of the parent Region structure. */ /* Local Variables: */ AstFrame *cfrm; /* Current Frame */ AstFrame *newfrm1; /* Current Frame axes for reg1 */ AstFrame *newfrm2; /* Current Frame axes for reg2 */ AstFrameSet *fs; /* Parent FrameSet */ AstMapping *bcmap; /* Base->current Mapping */ AstMapping *nmap1; /* Reg1->current Mapping */ AstMapping *map1; /* First component Region from a CmpMap */ AstMapping *map2; /* Second component Region from a CmpMap */ int series; /* Apply component Mappings in series? */ int invert1; /* Use inverted first component Mapping? */ int invert2; /* Use inverted second component Mapping? */ AstMapping *nmap2; /* Reg2->current Mapping */ AstMapping *result; /* Result pointer to return */ AstCmpMap *cmpmap; /* Result pointer to return */ AstMapping *smap; /* Simplified CmpMap */ AstRegion *new2; /* New simplified Region */ AstRegion *new; /* New Region */ AstRegion *newreg1; /* Reg1 mapped into current Frame */ AstRegion *newreg2; /* Reg2 mapped into current Frame */ AstRegion *reg1; /* First component Region */ AstRegion *reg2; /* Second component Region */ AstRegion *reg; /* This Region */ AstRegion *snewreg1; /* Simplified newreg1 */ AstRegion *snewreg2; /* Simplified newreg2 */ AstRegion *unc; /* Uncertainty Region from supplied Prism */ int *axin; /* Indices of Mapping inputs to use */ int *axout1; /* Indices of cfrm axes corresponding to reg1 */ int *axout2; /* Indices of cfrm axes corresponding to reg2 */ int *perm; /* Axis permutation array */ int i; /* Loop count */ int nax1; /* Number of axes in first component Region */ int nax2; /* Number of axes in second component Region */ int naxt; /* Total number of axes in current Frame */ int naxout1; /* Number of current axes for reg1 */ int naxout2; /* Number of current axes for reg2 */ int neg; /* Negated flag for supplied Prism */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the Region structure */ reg = (AstRegion *) this_mapping; /* Get the component Regions, and the Negated flag for the Prism. */ GetRegions( (AstPrism *) this_mapping, ®1, ®2, &neg, status ); /* The above Regions describe areas within the base Frame of the FrameSet encapsulated by the parent Region structure. Get the current Frame in this FrameSet and the base->current Mapping. */ fs = reg->frameset; cfrm = astGetFrame( fs, AST__CURRENT ); bcmap = astGetMapping( fs, AST__BASE, AST__CURRENT ); /* Combine the two Regions into a parallel CmpMap (this uses the fact that a Region is a type of Mapping). Then simplify the CmpMap. This will result in the astMapMerge methods defined by sub-classes of Regions being used to merge adjacent regions. */ cmpmap = astCmpMap( reg1, reg2, 0, "", status ); smap = astSimplify( cmpmap ); cmpmap = astAnnul( cmpmap ); /* Initially, assume we cannot form a new Region from the simplified CmpMap. */ new = NULL; /* If the result is a region, use it. */ if( astIsARegion( smap ) ) { new = astClone( smap ); /* If the result is a parallel CmpMap, get its two components and check they are Regions. If so, and if they are not the same as the original two component Regions, form a new Prism from them. */ } else if( astIsACmpMap( smap ) ) { astDecompose( smap, &map1, &map2, &series, &invert1, &invert2 ); if( ! series && astIsARegion( map1 ) && astIsARegion( map2 ) ) { if( (AstRegion *) map1 != reg1 || (AstRegion *) map2 != reg2 ) { new = (AstRegion *) astPrism( (AstRegion *) map1, (AstRegion *) map2, "", status ); } } /* Free resources */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } smap = astAnnul( smap ); /* If the above produced a simplified Region, map it into the current Frame of "this" and simplify it. */ if( new ) { new2 = astMapRegion( new, bcmap, cfrm ); (void) astAnnul( new ); new = astSimplify( new2 ); new2 = astAnnul( new2 ); /* If the above did not produced a result, try a different approach. */ } else { /* Get the number of axes in each component Region. */ nax1 = astGetNaxes( reg1 ); nax2 = astGetNaxes( reg2 ); /* Use astMapSplit to see if the axes of the first component Region correspond to a distinct set of axes within the current Frame. If this is the case, then a Mapping is returned by astMapSplit which maps the axes of the first component Region into the corresponding current Frame axes. Also returned is a list of the axes within the current Frame which correspnd to the axes of the first component Region. */ nmap1 = NULL; axout1 = NULL; axin = astMalloc( sizeof( int )*(size_t)nax1 ); if( astOK ) { for( i = 0; i < nax1; i++ ) axin[ i ] = i; axout1 = astMapSplit( bcmap, nax1, axin, &nmap1 ); axin = astFree( axin ); } /* Do the same for the second component. */ nmap2 = NULL; axout2 = NULL; axin = astMalloc( sizeof( int )*(size_t)nax2 ); if( astOK ) { for( i = 0; i < nax2; i++ ) axin[ i ] = i + nax1; axout2 = astMapSplit( bcmap, nax2, axin, &nmap2 ); axin = astFree( axin ); } /* Assume for the moment that the component Regions cannot be simplified. In this case we will use a clone of the supplied Prism. */ new = astClone( this_mapping ); /* Determine the number of outputs from these Mappings. */ if( nmap1 ){ naxout1 = astGetNout( nmap1 ); } else { naxout1 = 0; } if( nmap2 ){ naxout2 = astGetNout( nmap2 ); } else { naxout2 = 0; } /* Determine the number of axes in the current Frame of the Prism. */ naxt = astGetNout( bcmap ); /* If the second component does not contribute any axes to the total Prism, we can ignore it. */ if( naxout1 == naxt && naxout2 == 0 ) { newfrm1 = astPickAxes( cfrm, naxout1, axout1, NULL ); newreg1 = astMapRegion( reg1, nmap1, newfrm1 ); (void) astAnnul( new ); new = astSimplify( newreg1 ); if( neg ) astNegate( new ); perm = astMalloc( sizeof( int )*(size_t) ( naxout1 ) ); if( astOK ) { for( i = 0; i < naxout1; i++ ) perm[ i ] = axout1[ i ]; astPermAxes( new, perm ); perm = astFree( perm ); } newfrm1 = astAnnul( newfrm1 ); newreg1 = astAnnul( newreg1 ); /* If the first component does not contribute any axes to the total Prism, we can ignore it. */ } else if( naxout1 == 0 && naxout2 == naxt ) { newfrm2 = astPickAxes( cfrm, naxout2, axout2, NULL ); newreg2 = astMapRegion( reg2, nmap2, newfrm2 ); (void) astAnnul( new ); new = astSimplify( newreg2 ); if( neg ) astNegate( new ); perm = astMalloc( sizeof( int )*(size_t) ( naxout2 ) ); if( astOK ) { for( i = 0; i < naxout2; i++ ) perm[ i ] = axout2[ i ]; astPermAxes( new, perm ); perm = astFree( perm ); } newfrm2 = astAnnul( newfrm2 ); newreg2 = astAnnul( newreg2 ); /* If both component Regions correspond to a distinct subspace within the current Frame, then we can try to express each component Region within the current Frame. */ } else if( nmap1 && nmap2 ) { /* Create a Frame representing the subspace of the current Frame which corresponds to the axes of the first component Region. */ newfrm1 = astPickAxes( cfrm, naxout1, axout1, NULL ); /* Remap the first component Region so that it represents an area in this subspace. */ newreg1 = astMapRegion( reg1, nmap1, newfrm1 ); /* Attempt to simplify the remapped Region. */ snewreg1 = astSimplify( newreg1 ); /* Do the same for the second component Region. */ naxout2 = astGetNout( nmap2 ); newfrm2 = astPickAxes( cfrm, naxout2, axout2, NULL ); newreg2 = astMapRegion( reg2, nmap2, newfrm2 ); snewreg2 = astSimplify( newreg2 ); /* If either component Region was simplified, create a new Prism from the simplified Regions. */ if( snewreg1 != newreg1 || snewreg2 != newreg2 ) { (void) astAnnul( new ); new = (AstRegion *) astPrism( snewreg1, snewreg2, "", status ); /* Ensure the new Prism has the same Negated attribute as the original. */ if( neg ) astNegate( new ); /* Ensure that the new Prism has the same axis order as the original current Frame. */ perm = astMalloc( sizeof( int )*(size_t) ( naxout1 + naxout2 ) ); if( astOK ) { for( i = 0; i < naxout1; i++ ) perm[ i ] = axout1[ i ]; for( ; i < naxout1 + naxout2; i++ ) perm[ i ] = axout2[ i - naxout1 ]; astPermAxes( new, perm ); perm = astFree( perm ); } } /* Free resources. */ newfrm1 = astAnnul( newfrm1 ); newfrm2 = astAnnul( newfrm2 ); newreg1 = astAnnul( newreg1 ); newreg2 = astAnnul( newreg2 ); snewreg1 = astAnnul( snewreg1 ); snewreg2 = astAnnul( snewreg2 ); } /* Free resources. */ if( axout1 ) axout1 = astFree( axout1 ); if( axout2 ) axout2 = astFree( axout2 ); if( nmap1 ) nmap1 = astAnnul( nmap1 ); if( nmap2 ) nmap2 = astAnnul( nmap2 ); } /* If we have created a new Region, ensure any user-supplied uncertainty that has been stored explicitly with the supplied Prism is passed on to the new Region. */ if( new ) { if( astTestUnc( reg ) ) { unc = astGetUnc( reg, 0 ); astSetUnc( new, unc ); } /* Now invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ result = (*parent_simplify)( (AstMapping *) new, status ); new = astAnnul( new ); } /* Free resources. */ reg1 = astAnnul( reg1 ); reg2 = astAnnul( reg2 ); cfrm = astAnnul( cfrm ); bcmap = astAnnul( bcmap ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. */ if( result != this_mapping ) astRegOverlay( result, (AstRegion *) this_mapping, 0 ); /* If an error occurred, annul the returned Mapping. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Prism to transform a set of points. * Type: * Private function. * Synopsis: * #include "prism.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Prism member function (over-rides the astTransform method inherited * from the Region class). * Description: * This function takes a Prism and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Region. * This implies applying each of the Prism's component Regions in turn, * either in series or in parallel. * Parameters: * this * Pointer to the Prism. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Prism being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstCmpMap *map; /* CmpMap containing component Regions */ AstPointSet *psb; /* Pointer to base Frame PointSet */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ AstPrism *this; /* Pointer to the Prism structure */ AstRegion *reg1; /* Pointer to first component Region */ AstRegion *reg2; /* Pointer to second component Region */ double **ptr_out; /* Pointer to output coordinate data */ double **ptrb; /* Pointer to base Frame axis values */ int coord; /* Zero-based index for coordinates */ int good; /* Is the point inside the Prism? */ int ncoord_out; /* No. of coordinates per output point */ int ncoord_tmp; /* No. of coordinates per base Frame point */ int neg; /* Has Prism been negated? */ int npoint; /* No. of points */ int point; /* Loop counter for points */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a Pointer to the Prism structure */ this = (AstPrism *) this_mapping; /* Get the component Regions, and the Negated value for the Prism. */ GetRegions( this, ®1, ®2, &neg, status ); /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet in the parent Region structure to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Prism), to the base Frame (the Frame in which the component Regions are defined). Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( this, in, 0, NULL, NULL ); /* Form a parallel CmpMap from the two component Regions. */ map = astCmpMap( reg1, reg2, 0, "", status ); /* Apply the Mapping to the PointSet containing positions in the base Frame of the parent Region structure (which is the same as the combination of the current Frames of the component Regions). */ psb = astTransform( map, pset_tmp, 1, NULL ); /* Annul the Mapping pointer. */ map = astAnnul( map ); /* Determine the numbers of points and coordinates per point for these base Frame PointSets and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( pset_tmp ); ncoord_tmp = astGetNcoord( pset_tmp ); ptrb = astGetPoints( psb ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { for ( point = 0; point < npoint; point++ ) { good = 1; for ( coord = 0; coord < ncoord_tmp; coord++ ) { if( ptrb[ coord ][ point ] == AST__BAD ){ good = 0; break; } } if( good == neg ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Free resources. */ reg1 = astAnnul( reg1 ); reg2 = astAnnul( reg2 ); psb = astAnnul( psb ); pset_tmp = astAnnul( pset_tmp ); /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Prism objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Prism objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Regions within the Prism. */ /* Local Variables: */ AstPrism *in; /* Pointer to input Prism */ AstPrism *out; /* Pointer to output Prism */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Prisms. */ in = (AstPrism *) objin; out = (AstPrism *) objout; /* For safety, start by clearing any references to the input component Regions from the output Prism. */ out->region1 = NULL; out->region2 = NULL; /* Make copies of these Regions and store pointers to them in the output Prism structure. */ out->region1 = astCopy( in->region1 ); out->region2 = astCopy( in->region2 ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Prism objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Prism objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstPrism *this; /* Pointer to Prism */ /* Obtain a pointer to the Prism structure. */ this = (AstPrism *) obj; /* Annul the pointers to the component Regions. */ this->region1 = astAnnul( this->region1 ); this->region2 = astAnnul( this->region2 ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Prism 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 Prism class to an output Channel. * Parameters: * this * Pointer to the Prism 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 Variables: */ AstPrism *this; /* Pointer to the Prism structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Prism structure. */ this = (AstPrism *) this_object; /* Write out values representing the instance variables for the Prism 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. */ /* First Region. */ /* -------------- */ astWriteObject( channel, "RegionA", 1, 1, this->region1, "First component Region" ); /* Second Region. */ /* --------------- */ astWriteObject( channel, "RegionB", 1, 1, this->region2, "Second component Region" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPrism and astCheckPrism functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Prism,Region) astMAKE_CHECK(Prism) AstPrism *astPrism_( void *region1_void, void *region2_void, const char *options, int *status, ...) { /* *+ * Name: * astPrism * Purpose: * Create a Prism. * Type: * Protected function. * Synopsis: * #include "prism.h" * AstPrism *astPrism( AstRegion *region1, AstRegion *region2, * const char *options, ..., int *status ) * Class Membership: * Prism constructor. * Description: * This function creates a new Prism and optionally initialises its * attributes. * Parameters: * region1 * Pointer to the Region to be extruded. * region2 * Pointer to the Region defining the extent of the extrusion. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Prism. 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 Prism. * 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 Prism constructor which is * available via the protected interface to the Prism class. A * public interface is provided by the astPrismId_ 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 * "region1" and "region2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPrism *new; /* Pointer to new Prism */ AstRegion *region1; /* Pointer to first Region structure */ AstRegion *region2; /* Pointer to second Region structure */ 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 pointers to the Region structures provided. */ region1 = astCheckRegion( region1_void ); region2 = astCheckRegion( region2_void ); if ( astOK ) { /* Initialise the Prism, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPrism( NULL, sizeof( AstPrism ), !class_init, &class_vtab, "Prism", region1, region2 ); /* 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 Prism'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 Prism. */ return new; } AstPrism *astPrismId_( void *region1_void, void *region2_void, const char *options, ... ) { /* *++ * Name: c astPrism f AST_PRISM * Purpose: * Create a Prism. * Type: * Public function. * Synopsis: c #include "prism.h" c AstPrism *astPrism( AstRegion *region1, AstRegion *region2, c const char *options, ... ) f RESULT = AST_PRISM( REGION1, REGION2, OPTIONS, STATUS ) * Class Membership: * Prism constructor. * Description: * This function creates a new Prism and optionally initialises * its attributes. * * A Prism is a Region which represents an extrusion of an existing Region * into one or more orthogonal dimensions (specified by another Region). * If the Region to be extruded has N axes, and the Region defining the * extrusion has M axes, then the resulting Prism will have (M+N) axes. * A point is inside the Prism if the first N axis values correspond to * a point inside the Region being extruded, and the remaining M axis * values correspond to a point inside the Region defining the extrusion. * * As an example, a cylinder can be represented by extruding an existing * Circle, using an Interval to define the extrusion. Ih this case, the * Interval would have a single axis and would specify the upper and * lower limits of the cylinder along its length. * Parameters: c region1 f REGION1 = INTEGER (Given) * Pointer to the Region to be extruded. c region2 f REGION2 = INTEGER (Given) * Pointer to the Region defining the extent of the extrusion. 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 Prism. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Prism. The syntax used is identical to that for the f AST_SET routine. 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 astPrism() f AST_PRISM = INTEGER * A pointer to the new Prism. * Notes: * - Deep copies are taken of the supplied Regions. This means that * any subsequent changes made to the component Regions using the * supplied pointers will have no effect on the Prism. * - 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 astPrism constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astPrism_ 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 "region1" and "region2" parameters * are of type (void *) and are converted from an ID value to a * pointer and validated within the function itself. * - The variable argument list also prevents this function from * invoking astPrism_ 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 */ AstPrism *new; /* Pointer to new Prism */ AstRegion *region1; /* Pointer to first Region structure */ AstRegion *region2; /* Pointer to second Region structure */ int *status; /* Pointer to inherited status value */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ new = NULL; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return new; /* Obtain the Region pointers from the ID's supplied and validate the pointers to ensure they identify valid Regions. */ region1 = astVerifyRegion( astMakePointer( region1_void ) ); region2 = astVerifyRegion( astMakePointer( region2_void ) ); if ( astOK ) { /* Initialise the Prism, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPrism( NULL, sizeof( AstPrism ), !class_init, &class_vtab, "Prism", region1, region2 ); /* 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 Prism'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 Prism. */ return astMakeId( new ); } AstPrism *astInitPrism_( void *mem, size_t size, int init, AstPrismVtab *vtab, const char *name, AstRegion *region1, AstRegion *region2, int *status ) { /* *+ * Name: * astInitPrism * Purpose: * Initialise a Prism. * Type: * Protected function. * Synopsis: * #include "prism.h" * AstPrism *astInitPrism_( void *mem, size_t size, int init, * AstPrismVtab *vtab, const char *name, * AstRegion *region1, AstRegion *region2 ) * Class Membership: * Prism initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Prism object. It allocates memory (if necessary) to * accommodate the Prism plus any additional data associated with the * derived class. It then initialises a Prism 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 Prism at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Prism is to be initialised. * This must be of sufficient size to accommodate the Prism data * (sizeof(Prism)) 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 Prism (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 * Prism structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the Prism'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 Prism. * 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 Object * astClass function). * region1 * Pointer to the first Region. * region2 * Pointer to the second Region. * Returned Value: * A pointer to the new Prism. * 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: */ AstPrism *new; /* Pointer to new Prism */ AstFrame *frm1; /* Frame encapsulated by 1st Region */ AstFrame *frm2; /* Frame encapsulated by 2nd Region */ AstFrame *frm; /* CmpFrame formed from frm1 and frm2 */ AstMapping *map; /* Mapping between two supplied Regions */ AstRegion *reg1; /* Copy of first supplied Region */ AstRegion *reg2; /* Copy of second supplied Region */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPrismVtab( vtab, name ); /* Initialise. */ new = NULL; reg2 = NULL; /* Take a copy of the two supplied Regions. */ reg1 = astCopy( region1 ); reg2 = astCopy( region2 ); /* Form a CmpFrame representing the combined Frame of these two Regions. */ frm1 = astRegFrame( reg1 ); frm2 = astRegFrame( reg2 ); frm = (AstFrame *) astCmpFrame( frm1, frm2, "", status ); /* Initialise a Region structure (the parent class) as the first component within the Prism structure, allocating memory if necessary. A NULL PointSet is suppled as the two component Regions will perform the function of defining the Region shape. The base Frame of the FrameSet in the parent Region structure will be the CmpFrame formed from the two component Regions. */ if ( astOK ) { new = (AstPrism *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frm, NULL, NULL ); /* Initialise the Prism data. */ /* --------------------------- */ /* Store pointers to the component Regions. */ new->region1 = reg1; new->region2 = reg2; /* If the base->current Mapping in the FrameSet within a component Region is a UnitMap, then the FrameSet does not need to be included in the Dump of the new Prism. Set the RegionFS attribute of the component Region to zero to flag this. */ map = astGetMapping( reg1->frameset, AST__BASE, AST__CURRENT ); if( astIsAUnitMap( map ) ) astSetRegionFS( reg1, 0 ); map = astAnnul( map ); map = astGetMapping( reg2->frameset, AST__BASE, AST__CURRENT ); if( astIsAUnitMap( map ) ) astSetRegionFS( reg2, 0 ); map = astAnnul( map ); /* If an error occurred, clean up by annulling the Region pointers and deleting the new object. */ if ( !astOK ) { new->region1 = astAnnul( new->region1 ); new->region2 = astAnnul( new->region2 ); new = astDelete( new ); } } /* Free resources */ frm = astAnnul( frm ); frm1 = astAnnul( frm1 ); frm2 = astAnnul( frm2 ); /* Return a pointer to the new object. */ return new; } AstPrism *astLoadPrism_( void *mem, size_t size, AstPrismVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPrism * Purpose: * Load a Prism. * Type: * Protected function. * Synopsis: * #include "prism.h" * AstPrism *astLoadPrism( void *mem, size_t size, AstPrismVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Prism loader. * Description: * This function is provided to load a new Prism 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 * Prism structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Prism at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Prism is to be * loaded. This must be of sufficient size to accommodate the * Prism data (sizeof(Prism)) 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 Prism (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 Prism 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(AstPrism) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Prism. If this is NULL, a pointer to * the (static) virtual function table for the Prism 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 "Prism" is used instead. * Returned Value: * A pointer to the new Prism. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *cfrm; /* Frame containing required axes */ AstFrame *f1; /* Base Frame in parent Region */ AstPrism *new; /* Pointer to the new Prism */ AstRegion *creg; /* Pointer to component Region */ int *axes; /* Pointer to array of axis indices */ int i; /* Loop count */ int nax1; /* No.of axes in 1st component Frame */ int nax2; /* No.of axes in 2nd component Frame */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Prism. In this case the Prism belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPrism ); vtab = &class_vtab; name = "Prism"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPrismVtab( 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 Prism. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Prism" ); /* 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. */ /* First Region. */ /* -------------- */ new->region1 = astReadObject( channel, "regiona", NULL ); /* Second Region. */ /* --------------- */ new->region2 = astReadObject( channel, "regionb", NULL ); /* Either component Region may currently contain a dummy FrameSet rather than the correct FrameSet (see the Dump function for this class). In this case, the correct FrameSet will have copies of selected axes from the base Frame of the new Prism as both its current and base Frames, and these are connected by a UnitMap (this is equivalent to a FrameSet containing a single Frame). However if the new Prism being loaded has itself got a dummy FrameSet, then we do not do this since we do not yet know what the correct FrameSet is. In this case we wait until the parent Region invokes the astSetRegFS method on the new Prism. */ if( !astRegDummyFS( new ) ) { f1 = astGetFrame( ((AstRegion *) new)->frameset, AST__BASE ); creg = new->region1; nax1 = astGetNaxes( creg ); if( astRegDummyFS( creg ) ) { axes = astMalloc( sizeof( int )*(size_t) nax1 ); if( astOK ) for( i = 0; i < nax1; i++ ) axes[ i ] = i; cfrm = astPickAxes( f1, nax1, axes, NULL ); astSetRegFS( creg, cfrm ); axes = astFree( axes ); cfrm = astAnnul( cfrm ); } creg = new->region2; if( astRegDummyFS( creg ) ) { nax2 = astGetNaxes( creg ); axes = astMalloc( sizeof( int )*(size_t) nax2 ); if( astOK ) for( i = 0; i < nax2; i++ ) axes[ i ] = nax1 + i; cfrm = astPickAxes( f1, nax2, axes, NULL ); astSetRegFS( creg, cfrm ); axes = astFree( axes ); cfrm = astAnnul( cfrm ); } f1 = astAnnul( f1 ); } /* If an error occurred, clean up by deleting the new Prism. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Prism pointer. */ return new; } /* 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. */ /* None. */ ast-8.3.0/fmatrixmap.c0000664000175000017500000000666213004147321011555 00000000000000/* *+ * Name: * fmatrixmap.c * Purpose: * Define a FORTRAN 77 interface to the AST MatrixMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the MatrixMap class. * Routines Defined: * AST_ISAMATRIXMAP * AST_MATRIXMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 14-NOV-1996 (DSB): * Original version. * 3-JUN-1997 (DSB): * AST_MTRROT and AST_MTRMULT removed. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "matrixmap.h" /* C interface to the MatrixMap class */ F77_LOGICAL_FUNCTION(ast_isamatrixmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAMATRIXMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAMatrixMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_matrixmap)( INTEGER(NIN), INTEGER(NOUT), INTEGER(FORM), DOUBLE_ARRAY(MATRIX), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NIN) GENPTR_INTEGER(NOUT) GENPTR_INTEGER(FORM) GENPTR_DOUBLE_ARRAY(MATRIX) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_MATRIXMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astMatrixMap( *NIN, *NOUT, *FORM, MATRIX, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/selectormap.h0000664000175000017500000002020313004147321011713 00000000000000#if !defined( SELECTORMAP_INCLUDED ) /* Include this file only once */ #define SELECTORMAP_INCLUDED /* *+ * Name: * selectormap.h * Type: * C include file. * Purpose: * Define the interface to the SelectorMap class. * Invocation: * #include "selectormap.h" * Description: * This include file defines the interface to the SelectorMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The SelectorMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * astMapMerge * Merge a SelectorMap within a sequence of Mappings. * astTransform * Transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsASelectorMap * Test class membership. * astSelectorMap * Create a SelectorMap. * * Protected: * astCheckSelectorMap * Validate class membership. * astInitSelectorMap * Initialise a SelectorMap. * astInitSelectorMapVtab * Initialise the virtual function table for the SelectorMap class. * astLoadSelectorMap * Load a SelectorMap. * Macros: * None. * Type Definitions: * Public: * AstSelectorMap * SelectorMap object type. * * Protected: * AstSelectorMapVtab * SelectorMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 13-MAR-2006 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "region.h" /* Coordinate Regions (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* SelectorMap structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstSelectorMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ int nreg; /* The number of Regions in the SelectorMap */ AstRegion **reg; /* Array of Region pointers */ double badval; /* Output value for positions with bad axis values */ } AstSelectorMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstSelectorMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ /* None. */ } AstSelectorMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstSelectorMapGlobals { AstSelectorMapVtab Class_Vtab; int Class_Init; } AstSelectorMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitSelectorMapGlobals_( AstSelectorMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(SelectorMap) /* Check class membership */ astPROTO_ISA(SelectorMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstSelectorMap *astSelectorMap_( int, void **, double, const char *, int *, ...); #else AstSelectorMap *astSelectorMapId_( int, void **, double, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstSelectorMap *astInitSelectorMap_( void *, size_t, int, AstSelectorMapVtab *, const char *, int, AstRegion **, double, int * ); /* Vtab initialiser. */ void astInitSelectorMapVtab_( AstSelectorMapVtab *, const char *, int * ); /* Loader. */ AstSelectorMap *astLoadSelectorMap_( void *, size_t, AstSelectorMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* None. */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckSelectorMap(this) astINVOKE_CHECK(SelectorMap,this,0) #define astVerifySelectorMap(this) astINVOKE_CHECK(SelectorMap,this,1) /* Test class membership. */ #define astIsASelectorMap(this) astINVOKE_ISA(SelectorMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astSelectorMap astINVOKE(F,astSelectorMap_) #else #define astSelectorMap astINVOKE(F,astSelectorMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitSelectorMap(mem,size,init,vtab,name,nreg,regs,badval) \ astINVOKE(O,astInitSelectorMap_(mem,size,init,vtab,name,nreg,regs,badval,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitSelectorMapVtab(vtab,name) astINVOKE(V,astInitSelectorMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadSelectorMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadSelectorMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckSelectorMap to validate SelectorMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ /* None. */ #endif ast-8.3.0/grismmap.c0000664000175000017500000025450713004147321011227 00000000000000/* *class++ * Name: * GrismMap * Purpose: * Transform 1-dimensional coordinates using a grism dispersion equation. * Constructor Function: c astGrismMap f AST_GRISMMAP * Description: * A GrismMap is a specialised form of Mapping which transforms * 1-dimensional coordinates using the spectral dispersion equation * described in FITS-WCS paper III "Representation of spectral * coordinates in FITS". This describes the dispersion produced by * gratings, prisms and grisms. * * When initially created, the forward transformation of a GrismMap * transforms input "grism parameter" values into output wavelength * values. The "grism parameter" is a dimensionless value which is * linearly related to position on the detector. It is defined in FITS-WCS * paper III as "the offset on the detector from the point of intersection * of the camera axis, measured in units of the effective local length". * The units in which wavelength values are expected or returned is * determined by the values supplied for the GrismWaveR, GrismNRP and * GrismG attribute: whatever units are used for these attributes will * also be used for the wavelength values. * Inheritance: * The GrismMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * GrismMap also has the following attributes: * * - GrismNR: The refractive index at the reference wavelength * - GrismNRP: Rate of change of refractive index with wavelength * - GrismWaveR: The reference wavelength * - GrismAlpha: The angle of incidence of the incoming light * - GrismG: The grating ruling density * - GrismM: The interference order * - GrismEps: The angle between the normal and the dispersion plane * - GrismTheta: Angle between normal to detector plane and reference ray * Functions: c The GrismMap class does not define any new functions beyond those f The GrismMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 18-JUN-2003 (DSB): * Original version. * 10-MAY-2006 (DSB): * Override astEqual. *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 GrismMap /* * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear an attribute value for a GrismMap. * Type: * Private macro. * Synopsis: * #include "grismmap.h" * MAKE_CLEAR(class,attribute,component,assign) * Class Membership: * Defined by the GrismMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstGrismMap *this ) * * and an external interface function of the form: * * void astClear_( AstGrismMap *this ) * * which implement a method for clearing a specified attribute value for * a class. The derived constants stored in the GrismMap structure are * updated after the attribute has been cleared. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabel"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_CLEAR(class,attribute,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( Ast##class *this, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astClear(%s): The " #attribute "attribute of " \ "the supplied %s cannot be cleared because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, assign the "clear" value in the structure component. */ \ } else { \ this->component = (assign); \ } \ \ /* Update the derived constants. */ \ UpdateConstants( this, status ); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Clear##attribute))( this, status ); \ } /* * Name: * MAKE_SET * Purpose: * Implement a method to set an attribute value for a GrismMap. * Type: * Private macro. * Synopsis: * #include "grismmap.h" * astMAKE_SET(class,attribute,type,component,assign) * Class Membership: * Defined by the GrismMap class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstGrismMap *this, value ) * * and an external interface function of the form: * * void astSet_( AstGrismMap *this, value ) * * which implement a method for setting a specified attribute value for a * GrismMap. The derived constants stored in the GrismMap structure are * updated after the attribute has been cleared. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. */ /* Define the macro. */ #define MAKE_SET(class,attribute,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( Ast##class *this, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astSet(%s): The " #attribute "attribute of " \ "the supplied %s cannot be changed because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, store the new value in the structure component. */ \ } else { \ this->component = (assign); \ } \ \ /* Update the derived constants. */ \ UpdateConstants( this, status ); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( Ast##class *this, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Set##attribute))( this, value, status ); \ } /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "unitmap.h" /* Unit Mappings */ #include "channel.h" /* I/O channels */ #include "zoommap.h" /* ZoomMap interface */ #include "winmap.h" /* WinMap interface */ #include "grismmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include #include /* Macros which return the maximum and minimum of two values. */ #define MAX(aa,bb) ((aa)>(bb)?(aa):(bb)) #define MIN(aa,bb) ((aa)<(bb)?(aa):(bb)) /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(GrismMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(GrismMap,Class_Init) #define class_vtab astGLOBAL(GrismMap,Class_Vtab) #define getattrib_buff astGLOBAL(GrismMap,GetAttrib_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstGrismMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstGrismMap *astGrismMapId_( const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static AstMapping *CanMerge( AstMapping *, int, AstMapping *, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int Equal( AstObject *, AstObject *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void UpdateConstants( AstGrismMap *, int * ); static double GetGrismNR( AstGrismMap *, int * ); static int TestGrismNR( AstGrismMap *, int * ); static void ClearGrismNR( AstGrismMap *, int * ); static void SetGrismNR( AstGrismMap *, double, int * ); static double GetGrismNRP( AstGrismMap *, int * ); static int TestGrismNRP( AstGrismMap *, int * ); static void ClearGrismNRP( AstGrismMap *, int * ); static void SetGrismNRP( AstGrismMap *, double, int * ); static double GetGrismWaveR( AstGrismMap *, int * ); static int TestGrismWaveR( AstGrismMap *, int * ); static void ClearGrismWaveR( AstGrismMap *, int * ); static void SetGrismWaveR( AstGrismMap *, double, int * ); static double GetGrismAlpha( AstGrismMap *, int * ); static int TestGrismAlpha( AstGrismMap *, int * ); static void ClearGrismAlpha( AstGrismMap *, int * ); static void SetGrismAlpha( AstGrismMap *, double, int * ); static double GetGrismG( AstGrismMap *, int * ); static int TestGrismG( AstGrismMap *, int * ); static void ClearGrismG( AstGrismMap *, int * ); static void SetGrismG( AstGrismMap *, double, int * ); static int GetGrismM( AstGrismMap *, int * ); static int TestGrismM( AstGrismMap *, int * ); static void ClearGrismM( AstGrismMap *, int * ); static void SetGrismM( AstGrismMap *, int, int * ); static double GetGrismEps( AstGrismMap *, int * ); static int TestGrismEps( AstGrismMap *, int * ); static void ClearGrismEps( AstGrismMap *, int * ); static void SetGrismEps( AstGrismMap *, double, int * ); static double GetGrismTheta( AstGrismMap *, int * ); static int TestGrismTheta( AstGrismMap *, int * ); static void ClearGrismTheta( AstGrismMap *, int * ); static void SetGrismTheta( AstGrismMap *, double, int * ); /* Member functions. */ /* ================= */ static AstMapping *CanMerge( AstMapping *map1, int inv1, AstMapping *map2, int inv2, int *status ){ /* * * Name: * CanMerge * Purpose: * Checks if two GrismMaps can be merged. * Type: * Private function. * Synopsis: * #include "grismmap.h" * AstMapping *CanMerge( AstMapping *map1, int inv1, AstMapping *map2, * int inv2, int *status ) * Class Membership: * GrismMap internal utility function. * Description: * This function checks the two supplied Mappings to see if they can * be merged into a single Mapping. One of the two Mappings should be * a GrismMap. If they can be merged, the Merged Mapping is returned * as the function value. Otherwise NULL is returned. * Parameters: * map1 * A pointer to the first mapping. * map2 * A pointer to the second mapping. * inv1 * The invert flag to use with the first mapping. * inv2 * The invert flag to use with the second mapping. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the merged Mapping if the supplied Mappings can be merged, * NULL otherwise. */ /* Local Variables: */ AstGrismMap *gmap2; /* Pointer to second GrismMap */ AstGrismMap *gmap; /* Pointer to first GrismMap */ AstMapping *ret; /* Returned merged Mapping */ double g; /* The value of the GrismG attribute */ double nrp; /* The value of the GrismNRP attribute */ double waver; /* The value of the GrismWaveR attribute */ double z; /* Wavelength scaling */ int invert_result; /* Is "ret" the inverse of the required Mapping? */ /* Initialise the returned value. */ ret = NULL; /* Check the global error status. */ if ( !astOK ) return ret; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ gmap = NULL; invert_result = 0; /* Initialise the zoom factor of the adjacent ZoomMap to indicate that we have not yet found an adjacent ZoomMap. */ z = AST__BAD; /* If the first Mapping is a GrismMap... */ if( !strcmp( "GrismMap", astGetClass( map1 ) ) ) { gmap = (AstGrismMap *) map1; /* If the second Mapping is also a GrismMap, they can be merged into a UnitMap if one GrismMap is the inverse of the other. */ if( !strcmp( "GrismMap", astGetClass( map2 ) ) ) { gmap2 = (AstGrismMap *) map2; /* Check that the two GrismMaps have the same attribute values. */ if( astEQUAL( astGetGrismNR( gmap ), astGetGrismNR( gmap2 )) && astEQUAL( astGetGrismNRP( gmap ), astGetGrismNRP( gmap2 )) && astEQUAL( astGetGrismWaveR( gmap ), astGetGrismWaveR( gmap2 )) && astEQUAL( astGetGrismAlpha( gmap ), astGetGrismAlpha( gmap2 )) && astEQUAL( astGetGrismG( gmap ), astGetGrismG( gmap2 )) && astGetGrismM( gmap ) != astGetGrismM( gmap2 ) && astEQUAL( astGetGrismEps( gmap ), astGetGrismEps( gmap2 )) && astEQUAL( astGetGrismTheta( gmap ), astGetGrismTheta( gmap2 )) ){ /* If so, check that the GrismMaps are applied in opposite senses. If so we can cancel the two GrismMaps, so return a UnitMap. */ if( inv1 != inv2 ) ret = (AstMapping *) astUnitMap( 1, "", status ); } /* If the first Mapping is a GrismMap but the second one is not... */ } else { /* We can merge the GrismMap with the second Mapping if the GrismMap has not been inverted (i.e. if the wavelength output produced by the GrismMap is fed as input to the second Mapping), and if the second Mapping is a ZoomMap. */ if( !inv1 ) { /* Indicate that any merged Mapping to be created later will not need to be inverted. */ invert_result = 0; /* See if the second Mapping is a ZoomMap, and if so, get the zoom factor. If the Invert attribute in the ZoomMap is not set to the required value, invert the zoom factor. This gives us the required *forward* transformation. */ if( !strcmp( "ZoomMap", astGetClass( map2 ) ) ) { z = astGetZoom( (AstZoomMap *) map2 ); if( astGetInvert( map2 ) != inv2 && z != 0.0 ) z = 1.0/z; } } } /* If the first Mapping is not a GrismMap, but the second one is... */ } else if( !strcmp( "GrismMap", astGetClass( map2 ) ) ) { gmap = (AstGrismMap *) map2; /* We can merge the GrismMap with the first Mapping if the GrismMap has been inverted (i.e. if the wavelength output produced by the first Mapping is fed as input to the inverted GrismMap), and if the first Mapping is a ZoomMap. */ if( inv2 ) { /* It is easier to consider pairs of Mappings in which an un-inverted GrismMap is followed by a ZoomMap (as in the above case). For this reason, we invert the Mappings here, so that the merged Mapping created later will be in the inverse of the required Mapping. Indicate that the merged Mapping will therefore need to be inverted before being returned. */ invert_result = 1; /* See if the first Mapping is a ZoomMap. If so, get the zoom factor. If the Invert attribute in the ZoomMap is not set to the opposite of the required value, invert the zoom factor. This gives us the required *inverse* transformation. */ if( !strcmp( "ZoomMap", astGetClass( map1 ) ) ) { z = astGetZoom( (AstZoomMap *) map1 ); if( astGetInvert( map1 ) == inv1 && z != 0.0 ) z = 1.0/z; } } } /* If required, produce the merged Mapping by merging the forward GrismMap with the following ZoomMap (and then invert the resulting Mapping if it is in the wrong direction). */ if( !ret && z != AST__BAD && z != 0.0 ) { /* Ensure we have a forward GrismMap. */ ret = astCopy( gmap ); astSetInvert( ret, 0 ); /* Get the required GrismMap attribute values. */ g = astGetGrismG( ret ); nrp = astGetGrismNRP( ret ); waver = astGetGrismWaveR( ret ); /* The above code ensures that z is the zoom factor from the wavelength produced by the forward GrismMap to the final (modified) wavelength units. Set the new GrismMap attribute values. GrismG, GrismNRP and GrismWaveR have units of length and are scaled to represent new length units using the zoom factor found above. */ g /= z; nrp /= z; waver *= z; astSetGrismG( ret, g ); astSetGrismNRP( ret, nrp ); astSetGrismWaveR( ret, waver ); /* If required invert this GrismMap. */ if( invert_result ) astInvert( ret ); } /* Return the answer. */ return ret; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * GrismMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * GrismMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the GrismMap. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstGrismMap *this; /* Pointer to the GrismMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the GrismMap structure. */ this = (AstGrismMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ if ( !strcmp( attrib, "grismnr" ) ) { astClearGrismNR( this ); } else if ( !strcmp( attrib, "grismnrp" ) ) { astClearGrismNRP( this ); } else if ( !strcmp( attrib, "grismwaver" ) ) { astClearGrismWaveR( this ); } else if ( !strcmp( attrib, "grismalpha" ) ) { astClearGrismAlpha( this ); } else if ( !strcmp( attrib, "grismg" ) ) { astClearGrismG( this ); } else if ( !strcmp( attrib, "grismm" ) ) { astClearGrismM( this ); } else if ( !strcmp( attrib, "grismeps" ) ) { astClearGrismEps( this ); } else if ( !strcmp( attrib, "grismtheta" ) ) { astClearGrismTheta( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two GrismMaps are equivalent. * Type: * Private function. * Synopsis: * #include "grismmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * GrismMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two GrismMaps are equivalent. * Parameters: * this * Pointer to the first Object (a GrismMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the GrismMaps are equivalent, zero otherwise. * 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: */ AstGrismMap *that; AstGrismMap *this; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two GrismMap structures. */ this = (AstGrismMap *) this_object; that = (AstGrismMap *) that_object; /* Check the second object is a GrismMap. We know the first is a GrismMap since we have arrived at this implementation of the virtual function. */ if( astIsAGrismMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two GrismMaps differ, it may still be possible for them to be equivalent. First compare the GrismMaps if their Invert flags are the same. In this case all the attributes of the two GrismMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { if( astEQUAL( this->nr, that->nr ) && astEQUAL( this->nrp, that->nrp ) && astEQUAL( this->waver, that->waver ) && astEQUAL( this->alpha, that->alpha ) && astEQUAL( this->g, that->g ) && this->m == that->m && astEQUAL( this->eps, that->eps ) && astEQUAL( this->theta, that->theta ) && astEQUAL( this->k1, that->k1 ) && astEQUAL( this->k2, that->k2 ) && astEQUAL( this->k3, that->k3 ) ) { result = 1; } /* If the Invert flags for the two GrismMaps differ, the attributes of the two GrismMaps must be inversely related to each other. */ } else { /* In the specific case of a GrismMap, Invert flags must be equal. */ result = 0; } } } /* 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 GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * GrismMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a GrismMap, formatted as a character string. * Parameters: * this * Pointer to the GrismMap. * 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 GrismMap, 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 GrismMap. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstGrismMap *this; /* Pointer to the GrismMap structure */ const char *result; /* Pointer value to return */ double dval; /* Attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the GrismMap structure. */ this = (AstGrismMap *) 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. */ if ( !strcmp( attrib, "grismnr" ) ) { dval = astGetGrismNR( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismnrp" ) ) { dval = astGetGrismNRP( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismwaver" ) ) { dval = astGetGrismWaveR( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismalpha" ) ) { dval = astGetGrismAlpha( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismg" ) ) { dval = astGetGrismG( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismm" ) ) { dval = astGetGrismM( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismeps" ) ) { dval = astGetGrismEps( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } } else if ( !strcmp( attrib, "grismtheta" ) ) { dval = astGetGrismTheta( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } void astInitGrismMapVtab_( AstGrismMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitGrismMapVtab * Purpose: * Initialise a virtual function table for a GrismMap. * Type: * Protected function. * Synopsis: * #include "grismmap.h" * void astInitGrismMapVtab( AstGrismMapVtab *vtab, const char *name ) * Class Membership: * GrismMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the GrismMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAGrismMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearGrismNR = ClearGrismNR; vtab->GetGrismNR = GetGrismNR; vtab->SetGrismNR = SetGrismNR; vtab->TestGrismNR = TestGrismNR; vtab->ClearGrismNRP = ClearGrismNRP; vtab->GetGrismNRP = GetGrismNRP; vtab->SetGrismNRP = SetGrismNRP; vtab->TestGrismNRP = TestGrismNRP; vtab->ClearGrismWaveR = ClearGrismWaveR; vtab->GetGrismWaveR = GetGrismWaveR; vtab->SetGrismWaveR = SetGrismWaveR; vtab->TestGrismWaveR = TestGrismWaveR; vtab->ClearGrismAlpha = ClearGrismAlpha; vtab->GetGrismAlpha = GetGrismAlpha; vtab->SetGrismAlpha = SetGrismAlpha; vtab->TestGrismAlpha = TestGrismAlpha; vtab->ClearGrismG = ClearGrismG; vtab->GetGrismG = GetGrismG; vtab->SetGrismG = SetGrismG; vtab->TestGrismG = TestGrismG; vtab->ClearGrismM = ClearGrismM; vtab->GetGrismM = GetGrismM; vtab->SetGrismM = SetGrismM; vtab->TestGrismM = TestGrismM; vtab->ClearGrismEps = ClearGrismEps; vtab->GetGrismEps = GetGrismEps; vtab->SetGrismEps = SetGrismEps; vtab->TestGrismEps = TestGrismEps; vtab->ClearGrismTheta = ClearGrismTheta; vtab->GetGrismTheta = GetGrismTheta; vtab->SetGrismTheta = SetGrismTheta; vtab->TestGrismTheta = TestGrismTheta; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the class dump, copy and delete functions.*/ astSetDump( vtab, Dump, "GrismMap", "Map 1-d coordinates using a spectral disperser" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * GrismMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated GrismMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated GrismMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated GrismMap which is to be merged with * its neighbours. This should be a cloned copy of the GrismMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * GrismMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated GrismMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *merged_map; /* Merger of two Mappings */ int i1; /* Lower index of the two GrismMaps being merged */ int i2; /* Upper index of the two GrismMaps being merged */ int i; /* Mapping index */ int result; /* Result value to return */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ i1 = -1; i2 = -1; /* See if the GrismMap can be merged with the Mappings on either side of it in the list. This can only be done in series for a GrismMap. */ /* ===================================================================== */ if( series ) { /* Set a flag indicating that we have not yet found a neighbour with which the GrismMap can be merged. */ merged_map = NULL; /* First check the lower neighbour (if any). */ if( where > 0 ) { i1 = where - 1; i2 = where; merged_map = CanMerge( ( *map_list )[ i1 ], (* invert_list)[ i1 ], ( *map_list )[ i2 ], (* invert_list)[ i2 ], status ); } /* If the GrismMap can not be merged with its lower neighbour, check its upper neighbour (if any) in the same way. */ if( !merged_map && where < *nmap - 1 ) { i1 = where; i2 = where + 1; merged_map = CanMerge( ( *map_list )[ i1 ], (* invert_list)[ i1 ], ( *map_list )[ i2 ], (* invert_list)[ i2 ], status ); } /* If either neighbour has passed these checks, replace the pair of Mappings which have been merged with the single merged Mapping returned above. */ if( merged_map ) { /* Annul the two Mappings. */ (void) astAnnul( ( *map_list )[ i1 ] ); (void) astAnnul( ( *map_list )[ i2 ] ); /* Store a pointer for the merged Mapping in place of the first of the two replaced Mappings. */ ( *map_list )[ i1 ] = merged_map; ( *invert_list )[ i1 ] = astGetInvert( merged_map ); /* Shuffle down the remaining Mappings to fill the hole left by the second of the replaced Mappings. */ for ( i = i2 + 1; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ (*nmap)--; result = i1; } } /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * GrismMap member function (over-rides the astSetAttrib protected * method inherited from the Mapping class). * Description: * This function assigns an attribute value for a GrismMap, 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 GrismMap. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstGrismMap *this; /* Pointer to the GrismMap structure */ double dval; /* Attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the GrismMap structure. */ this = (AstGrismMap *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ if ( nc = 0, ( 1 == astSscanf( setting, "grismnr= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismNR( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismnrp= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismNRP( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismwaver= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismWaveR( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismalpha= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismAlpha( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismg= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismG( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismm= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismM( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismeps= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismEps( this, dval ); } else if ( nc = 0, ( 1 == astSscanf( setting, "grismtheta= %lf %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetGrismTheta( this, dval ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * GrismMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a GrismMap's attributes. * Parameters: * this * Pointer to the GrismMap. * 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: */ AstGrismMap *this; /* Pointer to the GrismMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the GrismMap structure. */ this = (AstGrismMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ if ( !strcmp( attrib, "grismnr" ) ) { result = astTestGrismNR( this ); } else if ( !strcmp( attrib, "grismnrp" ) ) { result = astTestGrismNRP( this ); } else if ( !strcmp( attrib, "grismwaver" ) ) { result = astTestGrismWaveR( this ); } else if ( !strcmp( attrib, "grismalpha" ) ) { result = astTestGrismAlpha( this ); } else if ( !strcmp( attrib, "grismg" ) ) { result = astTestGrismG( this ); } else if ( !strcmp( attrib, "grismm" ) ) { result = astTestGrismM( this ); } else if ( !strcmp( attrib, "grismeps" ) ) { result = astTestGrismEps( this ); } else if ( !strcmp( attrib, "grismtheta" ) ) { result = astTestGrismTheta( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a GrismMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "grismmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * GrismMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a GrismMap and a set of points encapsulated * in a PointSet and transforms the points so as to apply the * forward or inverse dispersal equation. * Parameters: * this * Pointer to the GrismMap. * 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: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * - The number of coordinate values per point in the input * PointSet must equal 1. * - If an output PointSet is supplied, it must have space for * sufficient number of points (with 1 coordinate value per point) * to accommodate the result. Any excess space will be ignored. */ /* Local Variables: */ AstGrismMap *map; /* Pointer to GrismMap to be applied */ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double sinbeta; /* Sin( beta ) (see FITS-WCS paper III) */ double value_in; /* Input coordinate value */ int npoint; /* Number of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the GrismMap. */ map = (AstGrismMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* If any of the parameters are undefined fill the output with bad values (if possible). */ if( map->k1 == AST__BAD || map->k2 == AST__BAD || map->k3 == AST__BAD ) { if( astOK ) { for ( point = 0; point < npoint; point++ ) { ptr_out[ 0 ][ point ] = AST__BAD; } } /* Otherwise... */ } else { /* Forward transformation. */ /* ----------------------- */ if ( forward ) { /* Loop to transform each input point. */ for ( point = 0; point < npoint; point++ ) { /* Extract the input grism parameter value. */ value_in = ptr_in[ 0 ][ point ]; /* Check for bad input coordinates and generate a bad result if necessary. */ if( value_in == AST__BAD || map->k2 == 0.0 ) { ptr_out[ 0 ][ point ] = AST__BAD; /* Otherwise, apply the algorithm described in FITS-WCS paper III. */ } else { ptr_out[ 0 ][ point ] = ( map->k1 + sin( atan( value_in ) + map->k3 ) )/map->k2; } } /* Inverse transformation. */ /* ----------------------- */ } else { /* Loop to transform each input point. */ for ( point = 0; point < npoint; point++ ) { /* Extract the input wavelength value. */ value_in = ptr_in[ 0 ][ point ]; /* Check for bad input coordinates and generate a bad result if necessary. */ if ( value_in == AST__BAD ) { ptr_out[ 0 ][ point ] = AST__BAD; /* Otherwise, apply the algorithm described in FITS-WCS paper III. */ } else { sinbeta = map->k2*value_in - map->k1; if( sinbeta < -1.0 || sinbeta > 1.0 ) { ptr_out[ 0 ][ point ] = AST__BAD; } else { ptr_out[ 0 ][ point ] = tan( asin( sinbeta ) - map->k3 ); } } } } } /* Return a pointer to the output PointSet. */ return result; } static void UpdateConstants( AstGrismMap *this, int *status ){ /* * Name: * UpdateConstants * Purpose: * Re-calculate the constants used within the transformation. * Type: * Private function. * Synopsis: * #include "grismmap.h" * void UpdateConstants( AstGrismMap *this, int *status ) * Class Membership: * GrismMap member function * Description: * This function re-calculates the constants used within the * transformation on the basis of the current values of the * GrismMap attributes. It should be called whenever a new value is * set for an attribute, or an attribute is cleared. * Parameters: * this * Pointer to the GrismMap. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double alpha; /* The current vaue of the GrismAlpha attribute */ double coseps; /* cos( eps ) */ double sinalpha; /* sin( alpha ) */ double eps; /* The current vaue of the GrismEps attribute */ double g; /* The current vaue of the GrismG attribute */ double nr; /* The current vaue of the GrismNR attribute */ double nrp; /* The current vaue of the GrismNRP attribute */ double sinbeta_r; /* sin( beta_r ) */ double theta; /* The current vaue of the GrismTheta attribute */ double wave_r; /* The current vaue of the GrismWaveR attribute */ int m; /* The current vaue of the GrismM attribute */ /* Check the global error status. */ if ( !astOK ) return; /* Get the current attribute values. */ nr = astGetGrismNR( this ); nrp = astGetGrismNRP( this ); wave_r = astGetGrismWaveR( this ); alpha = astGetGrismAlpha( this ); g = astGetGrismG( this ); m = astGetGrismM( this ); eps = astGetGrismEps( this ); theta = astGetGrismTheta( this ); /* Re-calculate the constants. */ coseps = cos( eps ); sinalpha = sin( alpha ); this->k1 = sinalpha*( nr - nrp*wave_r ); if( coseps != 0.0 ) { this->k2 = ( g*m/coseps ) - nrp*sinalpha; sinbeta_r = g*m*wave_r/coseps - nr*sinalpha; if( sinbeta_r < -1.0 || sinbeta_r > 1.0 ) { this->k3 = AST__BAD; } else { this->k3 = asin( sinbeta_r ) + theta; } } else { this->k2 = AST__BAD; this->k3 = AST__BAD; } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * GrismNR * Purpose: * The refractive index at the reference wavelength. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds refractive index of the grism material at the * reference wavelength (given by attribute GrismWaveR). The default * value is 1.0. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismNR,nr,(AST__BAD)) astMAKE_GET(GrismMap,GrismNR,double,1.0,( ( this->nr == AST__BAD ) ? 1.0 : this->nr )) MAKE_SET(GrismMap,GrismNR,double,nr,(value) ) astMAKE_TEST(GrismMap,GrismNR,( this->nr != AST__BAD )) /* *att++ * Name: * GrismNRP * Purpose: * The rate of change of refractive index with wavelength. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the rate of change of the refractive index of the * grism material with respect to wavelength at the reference wavelength * (given by attribute GrismWaveR). The default value is 0.0 (the * appropriate value for a pure grating disperser with no prism). The * units of this attribute should be consistent with those of attributes * GrismWaveR and GrismG. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismNRP,nrp,(AST__BAD)) astMAKE_GET(GrismMap,GrismNRP,double,0.0,( ( this->nrp == AST__BAD ) ? 0.0 : this->nrp )) MAKE_SET(GrismMap,GrismNRP,double,nrp,(value) ) astMAKE_TEST(GrismMap,GrismNRP,( this->nrp != AST__BAD )) /* *att++ * Name: * GrismWaveR * Purpose: * The reference wavelength. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds reference wavelength. The default value is * 5000 (Angstrom). The units of this attribute should be consistent with * those of attributes GrismNRP and GrismG. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismWaveR,waver,(AST__BAD)) astMAKE_GET(GrismMap,GrismWaveR,double,5000.0,( ( this->waver == AST__BAD ) ? 5000.0 : this->waver )) MAKE_SET(GrismMap,GrismWaveR,double,waver,(value) ) astMAKE_TEST(GrismMap,GrismWaveR,( this->waver != AST__BAD )) /* *att++ * Name: * GrismAlpha * Purpose: * The angle of incidence of the incoming light on the grating surface. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the angle between the incoming light and the * normal to the grating surface, in radians. The default value is 0. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismAlpha,alpha,(AST__BAD)) astMAKE_GET(GrismMap,GrismAlpha,double,0.0,( ( this->alpha == AST__BAD ) ? 0.0 : this->alpha )) MAKE_SET(GrismMap,GrismAlpha,double,alpha,(value) ) astMAKE_TEST(GrismMap,GrismAlpha,( this->alpha != AST__BAD )) /* *att++ * Name: * GrismG * Purpose: * The grating ruling density. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the number of grating rulings per unit length. * The unit of length used should be consistent with the units used * for attributes GrismWaveR and GrismNRP. The default value is 0.0. * (the appropriate value for a pure prism disperser with no grating). * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismG,g,(AST__BAD)) astMAKE_GET(GrismMap,GrismG,double,0.0,( ( this->g == AST__BAD ) ? 0.0 : this->g )) MAKE_SET(GrismMap,GrismG,double,g,(value) ) astMAKE_TEST(GrismMap,GrismG,( this->g != AST__BAD )) /* *att++ * Name: * GrismM * Purpose: * The interference order * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute holds the interference order being considered. * The default value is 0. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismM,m,(INT_MAX)) astMAKE_GET(GrismMap,GrismM,int,0,( ( this->m == INT_MAX ) ? 0 : this->m )) MAKE_SET(GrismMap,GrismM,int,m,(value) ) astMAKE_TEST(GrismMap,GrismM,( this->m != INT_MAX )) /* *att++ * Name: * GrismEps * Purpose: * The angle between the normal and the dispersion plane. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute holds the angle (in radians) between the normal to * the grating or exit prism face, and the dispersion plane. The * dispersion plane is the plane spanned by the incoming and outgoing * ray. The default value is 0.0. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismEps,eps,(AST__BAD)) astMAKE_GET(GrismMap,GrismEps,double,0.0,( ( this->eps == AST__BAD ) ? 0.0 : this->eps )) MAKE_SET(GrismMap,GrismEps,double,eps,(value) ) astMAKE_TEST(GrismMap,GrismEps,( this->eps != AST__BAD )) /* *att++ * Name: * GrismTheta * Purpose: * Angle between normal to detector plane and reference ray. * Type: * Public attribute. * Synopsis: * Double precision. * Description: * This attribute gives the angle of incidence of light of the * reference wavelength (given by attribute GrismWaveR) onto the * detector. Specifically, it holds the angle (in radians) between * the normal to the detector plane and an incident ray at the reference * wavelength. The default value is 0.0. * * Note, the value of this attribute may changed only if the GrismMap * has no more than one reference. That is, an error is reported if the * GrismMap has been cloned, either by including it within another object * such as a CmpMap or FrameSet or by calling the c astClone f AST_CLONE * function. * Applicability: * GrismMap * All GrismMaps have this attribute. *att-- */ MAKE_CLEAR(GrismMap,GrismTheta,theta,(AST__BAD)) astMAKE_GET(GrismMap,GrismTheta,double,0.0,( ( this->theta == AST__BAD ) ? 0.0 : this->theta )) MAKE_SET(GrismMap,GrismTheta,double,theta,(value) ) astMAKE_TEST(GrismMap,GrismTheta,( this->theta != AST__BAD )) /* Copy constructor. */ /* ----------------- */ /* No copy constructor is needed, as a byte-by-byte copy suffices. */ /* Destructor. */ /* ----------- */ /* No destructor is needed as no memory, etc. needs freeing. */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for GrismMap 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 GrismMap class to an output Channel. * Parameters: * this * Pointer to the GrismMap 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 Variables: */ AstGrismMap *this; /* Pointer to the GrismMap structure */ double dval; /* Double value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the GrismMap structure. */ this = (AstGrismMap *) this_object; /* Write out values representing the instance variables for the GrismMap 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. */ set = TestGrismNR( this, status ); dval = set ? GetGrismNR( this, status ) : astGetGrismNR( this ); astWriteDouble( channel, "GrmNR", set, 1, dval, "Refractive index at the ref. wavelength" ); set = TestGrismNRP( this, status ); dval = set ? GetGrismNRP( this, status ) : astGetGrismNRP( this ); astWriteDouble( channel, "GrmNRP", set, 1, dval, "Rate of change of refractive index" ); set = TestGrismWaveR( this, status ); dval = set ? GetGrismWaveR( this, status ) : astGetGrismWaveR( this ); astWriteDouble( channel, "GrmWR", set, 1, dval, "Ref. wavelength" ); set = TestGrismAlpha( this, status ); dval = set ? GetGrismAlpha( this, status ) : astGetGrismAlpha( this ); astWriteDouble( channel, "GrmAlp", set, 1, dval, "Angle of incidence of incoming light" ); set = TestGrismG( this, status ); dval = set ? GetGrismG( this, status ) : astGetGrismG( this ); astWriteDouble( channel, "GrmG", set, 1, dval, "Grating ruling density" ); set = TestGrismM( this, status ); dval = set ? GetGrismM( this, status ) : astGetGrismM( this ); astWriteDouble( channel, "GrmM", set, 1, dval, "The interference order" ); set = TestGrismEps( this, status ); dval = set ? GetGrismEps( this, status ) : astGetGrismEps( this ); astWriteDouble( channel, "GrmEps", set, 1, dval, "Angle between grating normal and dispersion plane" ); set = TestGrismTheta( this, status ); dval = set ? GetGrismTheta( this, status ) : astGetGrismTheta( this ); astWriteDouble( channel, "GrmTh", set, 1, dval, "Angle between detector normal and reference ray" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAGrismMap and astCheckGrismMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(GrismMap,Mapping) astMAKE_CHECK(GrismMap) AstGrismMap *astGrismMap_( const char *options, int *status, ...) { /* *++ * Name: c astGrismMap f AST_GRISMMAP * Purpose: * Create a GrismMap. * Type: * Public function. * Synopsis: c #include "grismmap.h" c AstGrismMap *astGrismMap( const char *options, ... ) f RESULT = AST_GRISMMAP( OPTIONS, STATUS ) * Class Membership: * GrismMap constructor. * Description: * This function creates a new GrismMap and optionally initialises * its attributes. * * A GrismMap is a specialised form of Mapping which transforms * 1-dimensional coordinates using the spectral dispersion equation * described in FITS-WCS paper III "Representation of spectral * coordinates in FITS". This describes the dispersion produced by * gratings, prisms and grisms. * * When initially created, the forward transformation of a GrismMap * transforms input "grism parameter" values into output wavelength * values. The "grism parameter" is a dimensionless value which is * linearly related to position on the detector. It is defined in FITS-WCS * paper III as "the offset on the detector from the point of intersection * of the camera axis, measured in units of the effective local length". * The units in which wavelength values are expected or returned is * determined by the values supplied for the GrismWaveR, GrismNRP and * GrismG attribute: whatever units are used for these attributes will * also be used for the wavelength values. * Parameters: 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 GrismMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new GrismMap. The syntax used is identical to that for the f AST_SET routine. 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 astGrismMap() f AST_GRISMMAP = INTEGER * A pointer to the new GrismMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstGrismMap *new; /* Pointer to new GrismMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the GrismMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitGrismMap( NULL, sizeof( AstGrismMap ), !class_init, &class_vtab, "GrismMap" ); /* 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 GrismMap'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 GrismMap. */ return new; } AstGrismMap *astGrismMapId_( const char *options, ... ) { /* * Name: * astGrismMapId_ * Purpose: * Create a GrismMap. * Type: * Private function. * Synopsis: * #include "grismmap.h" * AstGrismMap *astGrismMapId( const char *options, int *status, ... ) * Class Membership: * GrismMap constructor. * Description: * This function implements the external (public) interface to the * astGrismMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astGrismMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astGrismMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astGrismMap_. * status * Pointer to the inherited status variable. * Returned Value: * The ID value associated with the new GrismMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstGrismMap *new; /* Pointer to new GrismMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the GrismMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitGrismMap( NULL, sizeof( AstGrismMap ), !class_init, &class_vtab, "GrismMap" ); /* 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 GrismMap'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 GrismMap. */ return astMakeId( new ); } AstGrismMap *astInitGrismMap_( void *mem, size_t size, int init, AstGrismMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitGrismMap * Purpose: * Initialise a GrismMap. * Type: * Protected function. * Synopsis: * #include "grismmap.h" * AstGrismMap *astInitGrismMap( void *mem, size_t size, int init, * AstGrismMapVtab *vtab, const char *name ) * Class Membership: * GrismMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new GrismMap object. It allocates memory (if necessary) to accommodate * the GrismMap plus any additional data associated with the derived class. * It then initialises a GrismMap 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 GrismMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the GrismMap is to be initialised. * This must be of sufficient size to accommodate the GrismMap data * (sizeof(GrismMap)) 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 GrismMap (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 GrismMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the GrismMap'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 GrismMap. * 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). * Returned Value: * A pointer to the new GrismMap. * 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: */ AstGrismMap *new; /* Pointer to new GrismMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitGrismMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a Mapping structure (the parent class) as the first component within the GrismMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstGrismMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 1, 1, 1, 1 ); if ( astOK ) { /* Initialise the GrismMap data. */ /* ---------------------------- */ new->nr = AST__BAD; new->nrp = AST__BAD; new->waver = AST__BAD; new->alpha = AST__BAD; new->g = AST__BAD; new->m = INT_MAX; new->eps = AST__BAD; new->theta = AST__BAD; /* Set up the other required derived constants. */ UpdateConstants( new, status ); /* If an error occurred, clean up by deleting the new GrismMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new GrismMap. */ return new; } AstGrismMap *astLoadGrismMap_( void *mem, size_t size, AstGrismMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadGrismMap * Purpose: * Load a GrismMap. * Type: * Protected function. * Synopsis: * #include "grismmap.h" * AstGrismMap *astLoadGrismMap( void *mem, size_t size, * AstGrismMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * GrismMap loader. * Description: * This function is provided to load a new GrismMap 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 * GrismMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a GrismMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the GrismMap is to be * loaded. This must be of sufficient size to accommodate the * GrismMap data (sizeof(GrismMap)) 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 GrismMap (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 GrismMap 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(AstGrismMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new GrismMap. If this is NULL, a pointer * to the (static) virtual function table for the GrismMap 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 "GrismMap" is used instead. * Returned Value: * A pointer to the new GrismMap. * 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: */ AstGrismMap *new; /* Pointer to the new GrismMap */ /* Initialise. */ new = NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* 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 GrismMap. In this case the GrismMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstGrismMap ); vtab = &class_vtab; name = "GrismMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitGrismMapVtab( 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 GrismMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "GrismMap" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ new->nr = astReadDouble( channel, "grmnr", AST__BAD ); if ( TestGrismNR( new, status ) ) SetGrismNR( new, new->nr, status ); new->nrp = astReadDouble( channel, "grmnrp", AST__BAD ); if ( TestGrismNRP( new, status ) ) SetGrismNRP( new, new->nrp, status ); new->waver = astReadDouble( channel, "grmwr", AST__BAD ); if ( TestGrismWaveR( new, status ) ) SetGrismWaveR( new, new->waver, status ); new->alpha = astReadDouble( channel, "grmalp", AST__BAD ); if ( TestGrismAlpha( new, status ) ) SetGrismAlpha( new, new->alpha, status ); new->g = astReadDouble( channel, "grmg", AST__BAD ); if ( TestGrismG( new, status ) ) SetGrismG( new, new->g, status ); new->m = astReadInt( channel, "grmm", INT_MAX ); if ( TestGrismM( new, status ) ) SetGrismM( new, new->m, status ); new->eps = astReadDouble( channel, "grmeps", AST__BAD ); if ( TestGrismEps( new, status ) ) SetGrismEps( new, new->eps, status ); new->theta = astReadDouble( channel, "grmth", AST__BAD ); if ( TestGrismTheta( new, status ) ) SetGrismTheta( new, new->theta, status ); /* Set up the other required derived constants. */ UpdateConstants( new, status ); } /* If an error occurred, clean up by deleting the new GrismMap. */ if ( !astOK ) new = astDelete( new ); /* Return the new GrismMap 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. */ ast-8.3.0/unitnormmap.h0000664000175000017500000002232513004147321011755 00000000000000#if !defined( UNITNORMMAP_INCLUDED ) /* Include this file only once */ #define UNITNORMMAP_INCLUDED /* *+ * Name: * unitnormmap.h * Type: * C include file. * Purpose: * Define the interface to the UnitNormMap class. * Invocation: * #include "unitnormmap.h" * Description: * This include file defines the interface to the UnitNormMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * A UnitNormMap is a Mapping which, in the forward direction, * subtracts the specified centre and then transforms the resulting vector * to a unit vector and the vector norm. * The forward direction outputs one more coordinate than is input. * * The inverse transformation of a UnitNormMap multiplies each component * of the provided vector by the provided norm and adds the specified centre. * The forward direction outputs one fewer coordinate than is input. * * Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre; * the norm is 5, so the output is [0.8, 0.6, 5] * * UnitNormMap is intended for applying radially symmetric distortions, as follows: * - apply a UnitNormMap to produce a unit vector and norm (radius) * - apply some one-dimensional mapping to the norm (radius), while passing the unit vector unchanged * - apply the same UnitNormMap in the inverse direction to produce the result * * Inheritance: * The UnitNormMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * None. * Methods Over-Ridden: * Public: * None. * * Protected: * ClearAttrib * Clear an attribute value for a UnitNormMap. * GetAttrib * Get an attribute value for a UnitNormMap. * SetAttrib * Set an attribute value for a UnitNormMap. * TestAttrib * Test if an attribute value has been set for a UnitNormMap. * astMapMerge * Simplify a sequence of Mappings containing a UnitNormMap. * astTransform * Apply a UnitNormMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * None. * Other Class Functions: * Public: * astIsAUnitNormMap * Test class membership. * astUnitNormMap * Create a UnitNormMap. * * Protected: * astCheckUnitNormMap * Validate class membership. * astInitUnitNormMap * Initialise a UnitNormMap. * astInitUnitNormMapVtab * Initialise the virtual function table for the UnitNormMap class. * astLoadUnitNormMap * Load a UnitNormMap. * Macros: * None. * Type Definitions: * Public: * AstUnitNormMap * UnitNormMap object type. * * Protected: * AstUnitNormMapVtab * UnitNormMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * Copyright: * Copyright (C) 2016 University of Washington * 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 * . * Authors: * RO: Russell Owen (LSST) * History: * 20-APR-2016 (RO): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* UnitNormMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstUnitNormMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double *centre; /* Pointer to array of shifts */ } AstUnitNormMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstUnitNormMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstUnitNormMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstUnitNormMapGlobals { AstUnitNormMapVtab Class_Vtab; int Class_Init; } AstUnitNormMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitUnitNormMapGlobals_( AstUnitNormMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(UnitNormMap) /* Check class membership */ astPROTO_ISA(UnitNormMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstUnitNormMap *astUnitNormMap_( int, const double [], const char *, int *, ...); #else AstUnitNormMap *astUnitNormMapId_( int, const double [], const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstUnitNormMap *astInitUnitNormMap_( void *, size_t, int, AstUnitNormMapVtab *, const char *, int, const double *, int * ); /* Vtab initialiser. */ void astInitUnitNormMapVtab_( AstUnitNormMapVtab *, const char *, int * ); /* Loader. */ AstUnitNormMap *astLoadUnitNormMap_( void *, size_t, AstUnitNormMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckUnitNormMap(this) astINVOKE_CHECK(UnitNormMap,this,0) #define astVerifyUnitNormMap(this) astINVOKE_CHECK(UnitNormMap,this,1) /* Test class membership. */ #define astIsAUnitNormMap(this) astINVOKE_ISA(UnitNormMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astUnitNormMap astINVOKE(F,astUnitNormMap_) #else #define astUnitNormMap astINVOKE(F,astUnitNormMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define \ astInitUnitNormMap(mem,size,init,vtab,name,ncoord,centre) \ astINVOKE(O,astInitUnitNormMap_(mem,size,init,vtab,name,ncoord,centre,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitUnitNormMapVtab(vtab,name) astINVOKE(V,astInitUnitNormMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadUnitNormMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadUnitNormMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckUnitNormMap to validate UnitNormMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/fwcsmap.c0000664000175000017500000000644313004147321011042 00000000000000/* *+ * Name: * fwcsmap.c * Purpose: * Define a FORTRAN 77 interface to the AST WcsMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the WcsMap class. * Routines Defined: * AST_ISAWCSMAP * AST_WCSMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 18-NOV-1996 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "wcsmap.h" /* C interface to the WcsMap class */ F77_LOGICAL_FUNCTION(ast_isawcsmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAWCSMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAWcsMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_wcsmap)( INTEGER(NAXES), INTEGER(TYPE), INTEGER(LONAX), INTEGER(LATAX), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NAXES) GENPTR_INTEGER(TYPE) GENPTR_INTEGER(LONAX) GENPTR_INTEGER(LATAX) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_WCSMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astWcsMap( *NAXES, *TYPE, *LONAX, *LATAX, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/mapping.h0000664000175000017500000012157613004147321011047 00000000000000#if !defined( MAPPING_INCLUDED ) /* Include this file only once */ #define MAPPING_INCLUDED /* *++ * Name: * mapping.h * Type: * C include file. * Purpose: * Define the interface to the Mapping class. * Invocation: * #include "mapping.h" * Description: * This include file defines the interface to the Mapping class and * provides the type definitions, function prototypes and macros, etc. * needed to use this class. * * The Mapping class provides basic facilities for transforming a * set of points to give a new set of points and for resampling * grids of data. However, it does not have a constructor * function. This is because the class only forms a template for * deriving new classes which themselves implement specific forms * of coordinate transformation. They do this by extending the * protected astTransform method provided by this class. * Inheritance: * The Mapping class inherits from the Object class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Nin (integer) * A read-only attribute giving the number of input coordinate * values required per point by a Mapping (i.e. the number of * dimensions of the space in which input points reside). * Nout (integer) * A read-only attribute giving the number of output coordinate * values generated per point by a Mapping (i.e. the number of * dimensions of the space in which output points reside). * Invert (integer) * A boolean value (0 or 1) which controls which of a Mapping's * two possible coordinate transformations is considered the * "forward" transformation and which is the "inverse" * transformation. If this value is zero (the default), the * behaviour will be as defined when the Mapping was first * created. If it is non-zero, the transformations will be * inter-changed, so that the Mapping displays the inverse of * its original behaviour. * * Note that inverting the boolean sense of the Invert attribute * will cause the values of the Nin/Nout and * TranForward/TranInverse attributes to be interchanged. * Report (integer) * A boolean value (0 or 1) which controls whether to report * coordinate values when a Mapping is used to transform a set * of points. If this value is zero (the default), no report is * made. If it is non-zero, the coordinates of each point * (before and after transformation) are reported by writing * them to standard output. * * This attribute is intended as an aid to debugging and to save * having to report values explicitly in simple programs. * Unlike other attributes, the value of the Report attribute is * not inherited when a Mapping is copied (its value is * initially undefined, and therefore defaults to zero, in any * copy). * IsSimple (boolean) * A read-only attribute indicating if the Mapping has been * simpified. * TranForward (integer) * A read-only boolean value (0 or 1) which indicates whether a * Mapping is able to transform coordinates in the "forward" * direction (i.e. converting input coordinates into output * coordinates). * TranInverse (integer) * A read-only boolean value (0 or 1) which indicates whether a * Mapping is able to transform coordinates in the "inverse" * direction (i.e. converting output coordinates back into input * coordinates). * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a Mapping. * astGetAttrib * Get an attribute value for a Mapping. * astSetAttrib * Set an attribute value for a Mapping. * astTestAttrib * Test if an attribute value has been set for a Mapping. * New Methods Defined: * Public: * astDecompose * Decompose a Mapping into two component Mappings. * astInvert * Invert a Mapping. * astLinearApprox * Form a linear approximation to a Mapping * astMapBox * Find a bounding box for a Mapping. * astQuadApprox * Form a quadratic approximation to a Mapping * astRate * Find rate of change of a Mapping output * astRebin * Rebin a region of a data grid. * astRebinSeq * Rebin a region of a sequence of data grids. * astResample * Resample a region of a data grid. * astSimplify * Simplify a Mapping. * astTran1 * Transform 1-dimensional coordinates. * astTran2 * Transform 2-dimensional coordinates. * astTranGrid * Transform an N-dimensional regular grid of positions. * astTranN * Transform N-dimensional coordinates. * astTranP (C only) * Transform N-dimensional coordinates held in separate arrays. * * Protected: * astClearInvert * Clear the Invert attribute value for a Mapping. * astClearReport * Clear the Report attribute value for a Mapping. * astGetInvert * Get the Invert attribute value for a Mapping. * astGetIsSimple * Get the IsSimple attribute. * astGetNin * Get the number of input coordinates for a Mapping. * astGetNout * Get the number of output coordinates for a Mapping. * astGetReport * Get the Report attribute value for a Mapping. * astGetTranForward * Determine if a Mapping can perform a "forward" coordinate * transformation. * astGetTranInverse * Determine if a Mapping can perform an "inverse" coordinate * transformation. * astMapList * Decompose a Mapping into a sequence of simpler Mappings. * astMapSplit * Select a subset of Mapping inputs. * astMapMerge * Simplify a sequence of Mappings. * astReportPoints * Report the effect of transforming a set of points using a Mapping. * astSetInvert * Set the Invert attribute value for a Mapping. * astSetReport * Set the Report attribute value for a Mapping. * astTestInvert * Test if an Invert attribute value has been set for a Mapping. * astTestReport * Test if an Report attribute value has been set for a Mapping. * astTransform * Transform a set of points. * Other Class Functions: * Public: * astIsAMapping * Test class membership. * * Protected: * astCheckMapping * Validate class membership. * astInitMapping * Initialise a Mapping. * astInitMappingVtab * Initialise the virtual function table for the Mapping class. * astLoadMapping * Load a Mapping. * Macros: * Public: * AST__BLOCKAVE * Block averaging interpolation. * AST__GAUSS * Use exp(-k*x*x) spreading. * AST__LINEAR * Simple linear interpolation. * AST__NEAREST * Use nearest pixel centre. * AST__SINC * Use sinc(pi*x) interpolation. * AST__SINCCOS * Use sinc(pi*x)*cos(k*pi*x) interpolation. * AST__SINCGAUSS * Use sinc(pi*x)*exp(-k*x*x) interpolation. * AST__SINCSINC * Use sinc(pi*x)*sinc(k*pi*x) interpolation. * AST__SOMB * Use somb(pi*x) interpolation. * AST__SOMBCOS * Use somb(pi*x)*cos(k*pi*x) interpolation. * AST__UINTERP * Use general user-defined sub-pixel interpolation algorithm. * AST__UKERN1 * Use user-defined 1-d interpolation kernel. * AST__URESAMP1, 2, 3 & 4 * Flags reserved for user-defined purposes. * AST__USEBAD * Recognise bad pixels? * AST__CONSERVEFLUX * Conserve flux in astResample? * AST__REBININIT * Initialise a new sequnece of calls to astRebinSeq * AST__REBINEND * End a sequnece of calls to astRebinSeq * AST__NOBAD * Leave bad output pixels unchanged in calls to astResample * AST__USEVAR * Use variance arrays? * Type Definitions: * Public: * AstMapping * Mapping object type. * * Protected: * AstMappingVtab * Mapping virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * MBT: Mark Taylor (Starlink) * DSB: David S. Berry (Starlink) * History: * 30-JAN-1996 (RFWS): * Original version. * 12-JUL-1996 (RFWS): * Updated to support the external interface plus various other * additions. * 12-DEC-1996 (RFWS): * Added the astMapList method. * 13-DEC-1996 (RFWS): * Added the astMapMerge method. * 13-DEC-1996 (RFWS): * Added the astSimplify method. * 28-MAY-1998 (RFWS): * Added the astMapBox method. * 12-NOV-1998 (RFWS): * Added astResample and associated code. * 24-NOV-2000 (MBT): * Added AST__BLOCKAVE interpolation scheme. * 9-JAN-2001 (DSB): * Changed in and out arguments for TranN from type "double (*)[]" * to "double *". * 8-JAN-2003 (DSB): * Added protected astInitMappingVtab method. * 10-JUL-2003 (DSB): * Added method astRate. * 20-SEP-2004 (DSB): * Added method astLinearApprox. * 30-JUN-2005 (DSB): * Added method astRebin * 1-SEP-2005 (DSB): * Added method astRebinSeq * 31-JAN-2006 (DSB): * Added IsSimple attribute. * 2-MAR-2006 (DSB): * Use HAVE_LONG_DOUBLE in place of AST_LONG_DOUBLE * 8-MAR-2006 (DSB): * Add astTranGrid. * 5-MAY-2009 (DSB): * Add astRemoveRegions. * 26-FEB-2010 (DSB): * Added method astQuadApprox. *-- */ /* Include files. */ /* ============== */ /* Configuration results */ /* --------------------- */ #if HAVE_CONFIG_H #include #endif /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points/coordinates */ #include "channel.h" /* I/O channels */ /* C header files. */ /* --------------- */ #include #include /* Macros. */ /* ======= */ /* Sizes of global arrays */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__MAPPING_GETATTRIB_BUFF_LEN 50 #define AST__MAPPING_RATEFUN_MAX_CACHE 5 /* Resampling flags. */ /* ----------------- */ /* These macros define flag values which may be passed to astResample (via the "flags" argument) to provide control over resampling operations. */ #define AST__URESAMP1 (1) /* Flags reserved for user-defined purposes */ #define AST__URESAMP2 (2) #define AST__URESAMP3 (4) #define AST__URESAMP4 (8) #define AST__USEVAR (16) /* Use variance arrays? */ #define AST__USEBAD (32) /* Recognise bad pixels? */ #define AST__CONSERVEFLUX (64) /* Conserve flux? */ #define AST__REBININIT (128) /* Initialise a new sequence of calls to astRebinSeq? */ #define AST__REBINEND (256) /* End a sequence of calls to astRebinSeq? */ #define AST__GENVAR (512) /* Generate output variances when rebinning? */ #define AST__VARWGT (1024) /* Use input variances as weights? */ #define AST__NOBAD (2048) /* Leave bad output values unchanged? */ #define AST__DISVAR (4096) /* Generate distribution (not mean) variance? */ #define AST__NONORM (8192) /* No normalisation required at end? */ /* These macros identify standard sub-pixel interpolation algorithms for use by astResample. They are used by giving the macro's value for the "interp" argument. */ #define AST__UKERN1 (1) /* User-supplied 1-d interpolation kernel */ #if 0 /* Not yet implemented */ #define AST__UKERNN (2) /* User-supplied n-d interpolation kernel */ #endif #define AST__UINTERP (3) /* User-supplied interpolation function */ #define AST__NEAREST (4) /* Use pixel with nearest centre */ #define AST__LINEAR (5) /* Simple linear interpolation */ #define AST__SINC (6) /* sinc(pi*x) interpolation */ #define AST__SINCSINC (7) /* sinc(pi*x)*sinc(k*pi*x) interpolation */ #define AST__SINCCOS (8) /* sinc(pi*x)*cos(k*pi*x) interpolation */ #define AST__SINCGAUSS (9) /* sinc(pi*x)*exp(-k*x*x) interpolation */ #define AST__BLOCKAVE (10) /* Block averaging interpolation */ #define AST__GAUSS (11) /* exp(-k*x*x) spreading */ #define AST__SOMB (12) /* somp(pi*x) interpolation */ #define AST__SOMBCOS (13) /* somp(pi*x)*cos(k*pi*x) interpolation */ /* 64 bit types */ #if HAVE_INT64_T && HAVE_UINT64_T #include typedef int64_t INT_BIG; typedef uint64_t UINT_BIG; #elif SIZEOF_LONG == 8 typedef long int INT_BIG; typedef unsigned long int UINT_BIG; #elif SIZEOF_LONG_LONG == 8 typedef long long int INT_BIG; typedef unsigned long long int UINT_BIG; #else #define INT_BIG "no int64_t type available" #define UINT_BIG "no uint64_t type available" #endif /* Flags defining the meaning of each bit in the "flags" field of the Mapping structure. */ #if defined(astCLASS) /* Protected */ #define AST__ISSIMPLE_FLAG 1 /* Mapping has been simplified */ #define AST__FROZEN_FLAG 2 /* Mapping cannot be nominated for simplification */ #endif /* Type Definitions. */ /* ================= */ /* Mapping structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstMapping { /* Attributes inherited from the parent class. */ AstObject object; /* Parent class structure */ /* Attributes specific to objects in this class. */ char invert; /* Mapping inverted? */ char flags; /* Bit-wise flags describing the Mapping */ int nin; /* Number of input coordinates */ int nout; /* Number of output coordinates */ char report; /* Report when converting coordinates? */ char tran_forward; /* Forward transformation defined? */ char tran_inverse; /* Inverse transformation defined? */ } AstMapping; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstMappingVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstObjectVtab object_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstMapping *(* RemoveRegions)( AstMapping *, int * ); AstMapping *(* Simplify)( AstMapping *, int * ); AstPointSet *(* Transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); double (* Rate)( AstMapping *, double *, int, int, int * ); int (* DoNotSimplify)( AstMapping *, int * ); int (* GetInvert)( AstMapping *, int * ); int (* GetIsSimple)( AstMapping *, int * ); int (* GetNin)( AstMapping *, int * ); int (* GetNout)( AstMapping *, int * ); int (* GetReport)( AstMapping *, int * ); int (* GetTranForward)( AstMapping *, int * ); int (* GetTranInverse)( AstMapping *, int * ); int (* GetIsLinear)( AstMapping *, int * ); int (* LinearApprox)( AstMapping *, const double *, const double *, double, double *, int * ); int (* MapMerge)( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); int (* QuadApprox)( AstMapping *, const double[2], const double[2], int, int, double *, double *, int * ); int (* TestInvert)( AstMapping *, int * ); int (* TestReport)( AstMapping *, int * ); void (* ClearInvert)( AstMapping *, int * ); void (* ClearReport)( AstMapping *, int * ); void (* Decompose)( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); void (* Invert)( struct AstMapping *, int * ); void (* MapBox)( AstMapping *, const double [], const double [], int, int, double *, double *, double [], double [], int * ); int (* MapList)( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); int *(* MapSplit)( AstMapping *, int, const int *, AstMapping **, int * ); void (* ReportPoints)( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); void (* SetInvert)( AstMapping *, int, int * ); void (* SetReport)( AstMapping *, int, int * ); void (* Tran1)( AstMapping *, int, const double [], int, double [], int * ); void (* Tran2)( AstMapping *, int, const double [], const double [], int, double [], double [], int * ); void (* TranGrid)( AstMapping *, int, const int[], const int[], double, int, int, int, int, double *, int * ); void (* TranN)( AstMapping *, int, int, int, const double *, int, int, int, double *, int * ); void (* TranP)( AstMapping *, int, int, const double *[], int, int, double *[], int * ); #define DECLARE_GENERIC_ALL(X,Xtype) \ int (* Resample##X)( AstMapping *, int, const int [], const int [], \ const Xtype [], const Xtype [], int, \ void (*)( void ), const double [], int, double, int, \ Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ DECLARE_GENERIC_ALL(B,signed char) DECLARE_GENERIC_ALL(D,double) DECLARE_GENERIC_ALL(F,float) DECLARE_GENERIC_ALL(I,int) DECLARE_GENERIC_ALL(K,INT_BIG) DECLARE_GENERIC_ALL(L,long int) DECLARE_GENERIC_ALL(S,short int) DECLARE_GENERIC_ALL(UB,unsigned char) DECLARE_GENERIC_ALL(UI,unsigned int) DECLARE_GENERIC_ALL(UK,UINT_BIG) DECLARE_GENERIC_ALL(UL,unsigned long int) DECLARE_GENERIC_ALL(US,unsigned short int) #if HAVE_LONG_DOUBLE /* Not normally implemented */ DECLARE_GENERIC_ALL(LD,long double) #endif #undef DECLARE_GENERIC_ALL #define DECLARE_GENERIC_DFI(X,Xtype) \ void (* Rebin##X)( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], int, \ double, int, Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ void (* RebinSeq##X)( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], \ int, double, int, Xtype, int, const int [], \ const int [], const int [], const int [], Xtype [], \ Xtype [], double [], int64_t *, int * ); DECLARE_GENERIC_DFI(D,double) DECLARE_GENERIC_DFI(F,float) DECLARE_GENERIC_DFI(I,int) DECLARE_GENERIC_DFI(B,signed char) DECLARE_GENERIC_DFI(UB,unsigned char) #if HAVE_LONG_DOUBLE /* Not normally implemented */ DECLARE_GENERIC_DFI(LD,long double) #endif #undef DECLARE_GENERIC_DFI } AstMappingVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstMappingGlobals { AstMappingVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__MAPPING_GETATTRIB_BUFF_LEN + 1 ]; AstMapping *Unsimplified_Mapping; int Rate_Disabled; AstPointSet *RateFun_Pset1_Cache[ AST__MAPPING_RATEFUN_MAX_CACHE ]; AstPointSet *RateFun_Pset2_Cache[ AST__MAPPING_RATEFUN_MAX_CACHE ]; int RateFun_Next_Slot; int RateFun_Pset_Size[ AST__MAPPING_RATEFUN_MAX_CACHE ]; } AstMappingGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Mapping) /* Check class membership */ astPROTO_ISA(Mapping) /* Test class membership */ /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstMapping *astInitMapping_( void *, size_t, int, AstMappingVtab *, const char *, int, int, int, int, int * ); /* Vtab initialiser. */ void astInitMappingVtab_( AstMappingVtab *, const char *, int * ); /* Loader. */ AstMapping *astLoadMapping_( void *, size_t, AstMappingVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitMappingGlobals_( AstMappingGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ #define PROTO_GENERIC_ALL(X,Xtype) \ int astResample##X##_( AstMapping *, int, const int [], const int [], \ const Xtype [], const Xtype [], int, \ void (*)( void ), const double [], int, double, int, \ Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ PROTO_GENERIC_ALL(B,signed char) PROTO_GENERIC_ALL(D,double) PROTO_GENERIC_ALL(F,float) PROTO_GENERIC_ALL(I,int) PROTO_GENERIC_ALL(K,INT_BIG) PROTO_GENERIC_ALL(L,long int) PROTO_GENERIC_ALL(S,short int) PROTO_GENERIC_ALL(UB,unsigned char) PROTO_GENERIC_ALL(UI,unsigned int) PROTO_GENERIC_ALL(UK,UINT_BIG) PROTO_GENERIC_ALL(UL,unsigned long int) PROTO_GENERIC_ALL(US,unsigned short int) #if HAVE_LONG_DOUBLE /* Not normally implemented */ PROTO_GENERIC_ALL(LD,long double) #endif #undef PROTO_GENERIC_ALL #define PROTO_GENERIC_DFI(X,Xtype) \ void astRebin##X##_( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], int, \ double, int, Xtype, int, const int [], const int [], \ const int [], const int [], Xtype [], Xtype [], int * ); \ void astRebinSeq##X##_( AstMapping *, double, int, const int [], const int [], \ const Xtype [], const Xtype [], int, const double [], \ int, double, int, Xtype, int, const int [], \ const int [], const int [], const int [], Xtype [], \ Xtype [], double [], int64_t *, int * ); PROTO_GENERIC_DFI(D,double) PROTO_GENERIC_DFI(F,float) PROTO_GENERIC_DFI(I,int) PROTO_GENERIC_DFI(B,signed char) PROTO_GENERIC_DFI(UB,unsigned char) #if HAVE_LONG_DOUBLE /* Not normally implemented */ PROTO_GENERIC_DFI(LD,long double) #endif #undef PROTO_GENERIC_DFI AstMapping *astRemoveRegions_( AstMapping *, int * ); AstMapping *astSimplify_( AstMapping *, int * ); void astInvert_( AstMapping *, int * ); int astLinearApprox_( AstMapping *, const double *, const double *, double, double *, int * ); int astQuadApprox_( AstMapping *, const double[2], const double[2], int, int, double *, double *, int * ); void astTran1_( AstMapping *, int, const double [], int, double [], int * ); void astTran2_( AstMapping *, int, const double [], const double [], int, double [], double [], int * ); void astTranGrid_( AstMapping *, int, const int[], const int[], double, int, int, int, int, double *, int * ); void astTranN_( AstMapping *, int, int, int, const double *, int, int, int, double *, int * ); void astTranP_( AstMapping *, int, int, const double *[], int, int, double *[], int * ); #if defined(astCLASS) /* Protected */ void astDecompose_( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); void astMapBox_( AstMapping *, const double [], const double [], int, int, double *, double *, double [], double [], int * ); double astRate_( AstMapping *, double *, int, int, int * ); int *astMapSplit_( AstMapping *, int, const int *, AstMapping **, int * ); #else void astDecomposeId_( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); void astMapBoxId_( AstMapping *, const double [], const double [], int, int, double *, double *, double [], double [], int * ); double astRateId_( AstMapping *, double *, int, int, int * ); void astMapSplitId_( AstMapping *, int, const int *, int *, AstMapping **, int * ); #endif #if defined(astCLASS) /* Protected */ int astRateState_( int, int * ); AstPointSet *astTransform_( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); int astGetInvert_( AstMapping *, int * ); int astGetIsSimple_( AstMapping *, int * ); int astGetNin_( AstMapping *, int * ); int astGetNout_( AstMapping *, int * ); int astGetReport_( AstMapping *, int * ); int astGetTranForward_( AstMapping *, int * ); int astGetTranInverse_( AstMapping *, int * ); int astGetIsLinear_( AstMapping *, int * ); int astDoNotSimplify_( AstMapping *, int * ); int astMapMerge_( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); int astTestInvert_( AstMapping *, int * ); int astTestReport_( AstMapping *, int * ); void astClearInvert_( AstMapping *, int * ); void astClearReport_( AstMapping *, int * ); int astMapList_( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); void astReportPoints_( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); void astSetInvert_( AstMapping *, int, int * ); void astSetReport_( AstMapping *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckMapping(this) astINVOKE_CHECK(Mapping,this,0) #define astVerifyMapping(this) astINVOKE_CHECK(Mapping,this,1) /* Test class membership. */ #define astIsAMapping(this) astINVOKE_ISA(Mapping,this) /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitMapping(mem,size,init,vtab,name,nin,nout,tran_forward,tran_inverse) \ astINVOKE(O,astInitMapping_(mem,size,init,vtab,name,nin,nout,tran_forward,tran_inverse,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitMappingVtab(vtab,name) astINVOKE(V,astInitMappingVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadMapping(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadMapping_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckMapping (et al.) to validate Mapping pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #if HAVE_LONG_DOUBLE /* Not normally implemented */ #define astResampleLD(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleLD_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #endif #define astInvert(this) \ astINVOKE(V,astInvert_(astCheckMapping(this),STATUS_PTR)) #define astLinearApprox(this,lbnd,ubnd,tol,fit) \ astINVOKE(V,astLinearApprox_(astCheckMapping(this),lbnd,ubnd,tol,fit,STATUS_PTR)) #define astQuadApprox(this,lbnd,ubnd,nx,ny,fit,rms) \ astINVOKE(V,astQuadApprox_(astCheckMapping(this),lbnd,ubnd,nx,ny,fit,rms,STATUS_PTR)) #define astRebinD(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astRebinD_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRebinF(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astRebinF_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRebinI(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astRebinI_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRebinB(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astRebinB_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRebinUB(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astRebinUB_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRebinSeqD(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused) \ astINVOKE(V,astRebinSeqD_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused,STATUS_PTR)) #define astRebinSeqF(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused) \ astINVOKE(V,astRebinSeqF_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused,STATUS_PTR)) #define astRebinSeqI(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused) \ astINVOKE(V,astRebinSeqI_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused,STATUS_PTR)) #define astRebinSeqB(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused) \ astINVOKE(V,astRebinSeqB_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused,STATUS_PTR)) #define astRebinSeqUB(this,wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused) \ astINVOKE(V,astRebinSeqUB_(astCheckMapping(this),wlim,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,weights,nused,STATUS_PTR)) #define astResampleD(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleD_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleF(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleF_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleL(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleL_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleUL(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleUL_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleI(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleI_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleUI(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleUI_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleK(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleK_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleUK(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleUK_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleS(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleS_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleUS(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleUS_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleB(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleB_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astResampleUB(this,ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var) \ astINVOKE(V,astResampleUB_(astCheckMapping(this),ndim_in,lbnd_in,ubnd_in,in,in_var,interp,finterp,params,flags,tol,maxpix,badval,ndim_out,lbnd_out,ubnd_out,lbnd,ubnd,out,out_var,STATUS_PTR)) #define astRemoveRegions(this) astINVOKE(O,astRemoveRegions_(astCheckMapping(this),STATUS_PTR)) #define astSimplify(this) astINVOKE(O,astSimplify_(astCheckMapping(this),STATUS_PTR)) #define astTran1(this,npoint,xin,forward,xout) \ astINVOKE(V,astTran1_(astCheckMapping(this),npoint,xin,forward,xout,STATUS_PTR)) #define astTran2(this,npoint,xin,yin,forward,xout,yout) \ astINVOKE(V,astTran2_(astCheckMapping(this),npoint,xin,yin,forward,xout,yout,STATUS_PTR)) #define astTranGrid(this,ncoord_in,lbnd,ubnd,tol,maxpix,forward,ncoord_out,outdim,out) \ astINVOKE(V,astTranGrid_(astCheckMapping(this),ncoord_in,lbnd,ubnd,tol,maxpix,forward,ncoord_out,outdim,out,STATUS_PTR)) #define astTranN(this,npoint,ncoord_in,indim,in,forward,ncoord_out,outdim,out) \ astINVOKE(V,astTranN_(astCheckMapping(this),npoint,ncoord_in,indim,in,forward,ncoord_out,outdim,out,STATUS_PTR)) #define astTranP(this,npoint,ncoord_in,ptr_in,forward,ncoord_out,ptr_out) \ astINVOKE(V,astTranP_(astCheckMapping(this),npoint,ncoord_in,ptr_in,forward,ncoord_out,ptr_out,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astDecompose(this,map1,map2,series,inv1,inv2) \ astINVOKE(V,astDecompose_(astCheckMapping(this),(AstMapping **)(map1),(AstMapping **)(map2),series,inv1,inv2,STATUS_PTR)) #define astMapBox(this,lbnd_in,ubnd_in,forward,coord_out,lbnd_out,ubnd_out,xl,xu) \ astINVOKE(V,astMapBox_(astCheckMapping(this),lbnd_in,ubnd_in,forward,coord_out,lbnd_out,ubnd_out,xl,xu,STATUS_PTR)) #define astRate(this,at,ax1,ax2) \ astINVOKE(V,astRate_(astCheckMapping(this),at,ax1,ax2,STATUS_PTR)) #define astMapSplit(this,nin,in,map) \ astINVOKE(V,astMapSplit_(this,nin,in,map,STATUS_PTR)) #else #define astDecompose(this,map1,map2,series,inv1,inv2) \ astINVOKE(V,astDecomposeId_(astCheckMapping(this),(AstMapping **)(map1),(AstMapping **)(map2),series,inv1,inv2,STATUS_PTR)) #define astMapBox(this,lbnd_in,ubnd_in,forward,coord_out,lbnd_out,ubnd_out,xl,xu) \ astINVOKE(V,astMapBoxId_(astCheckMapping(this),lbnd_in,ubnd_in,forward,coord_out,lbnd_out,ubnd_out,xl,xu,STATUS_PTR)) #define astRate(this,at,ax1,ax2) \ astINVOKE(V,astRateId_(astCheckMapping(this),at,ax1,ax2,STATUS_PTR)) #define astMapSplit(this,nin,in,out,map) \ astINVOKE(V,astMapSplitId_(astCheckMapping(this),nin,in,out,map,STATUS_PTR)) #endif #if defined(astCLASS) /* Protected */ #define astRateState(disabled) astRateState_(disabled,STATUS_PTR) #define astClearInvert(this) \ astINVOKE(V,astClearInvert_(astCheckMapping(this),STATUS_PTR)) #define astClearReport(this) \ astINVOKE(V,astClearReport_(astCheckMapping(this),STATUS_PTR)) #define astGetInvert(this) \ astINVOKE(V,astGetInvert_(astCheckMapping(this),STATUS_PTR)) #define astGetIsSimple(this) \ astINVOKE(V,astGetIsSimple_(astCheckMapping(this),STATUS_PTR)) #define astGetNin(this) \ astINVOKE(V,astGetNin_(astCheckMapping(this),STATUS_PTR)) #define astGetNout(this) \ astINVOKE(V,astGetNout_(astCheckMapping(this),STATUS_PTR)) #define astGetReport(this) \ astINVOKE(V,astGetReport_(astCheckMapping(this),STATUS_PTR)) #define astGetTranForward(this) \ astINVOKE(V,astGetTranForward_(astCheckMapping(this),STATUS_PTR)) #define astGetTranInverse(this) \ astINVOKE(V,astGetTranInverse_(astCheckMapping(this),STATUS_PTR)) #define astGetIsLinear(this) \ astINVOKE(V,astGetIsLinear_(astCheckMapping(this),STATUS_PTR)) #define astMapList(this,series,invert,nmap,map_list,invert_list) \ astINVOKE(V,astMapList_(this,series,invert,nmap,map_list,invert_list,STATUS_PTR)) #define astMapMerge(this,where,series,nmap,map_list,invert_list) \ astINVOKE(V,astMapMerge_(astCheckMapping(this),where,series,nmap,map_list,invert_list,STATUS_PTR)) #define astReportPoints(this,forward,in_points,out_points) \ astINVOKE(V,astReportPoints_(astCheckMapping(this),forward,astCheckPointSet(in_points),astCheckPointSet(out_points),STATUS_PTR)) #define astSetInvert(this,value) \ astINVOKE(V,astSetInvert_(astCheckMapping(this),value,STATUS_PTR)) #define astSetReport(this,value) \ astINVOKE(V,astSetReport_(astCheckMapping(this),value,STATUS_PTR)) #define astTestInvert(this) \ astINVOKE(V,astTestInvert_(astCheckMapping(this),STATUS_PTR)) #define astTestReport(this) \ astINVOKE(V,astTestReport_(astCheckMapping(this),STATUS_PTR)) #define astDoNotSimplify(this) \ astINVOKE(V,astDoNotSimplify_(astCheckMapping(this),STATUS_PTR)) /* Since a NULL PointSet pointer is acceptable here, we must omit the argument checking in that case. (But unfortunately, "out" then gets evaluated twice - this is unlikely to matter, but is there a better way?) */ #define astTransform(this,in,forward,out) \ astINVOKE(O,astTransform_(astCheckMapping(this),astCheckPointSet(in),forward,(out)?astCheckPointSet(out):NULL,STATUS_PTR)) #endif #endif ast-8.3.0/configure.ac0000664000175000017500000001532213004147321011520 00000000000000dnl Process this file with autoconf to produce a configure script AC_REVISION($Revision$) dnl This configure file is known to work with autoconf-2.57, dnl automake versions 1.6.3 and 1.7.5, and libtool versions 1.4.2 and dnl 1.5. It should work with autoconf versions 2.50 or better, and dnl automake 1.6 or better. dnl Initialisation: package name and version number AC_INIT([ast],[8.3.0],[starlink@jiscmail.ac.uk]) AC_CONFIG_AUX_DIR([build-aux]) dnl Require autoconf-2.50 at least AC_PREREQ([2.69]) dnl Require Starlink automake AM_INIT_AUTOMAKE([1.8.2-starlink subdir-objects]) dnl Sanity-check: name a file in the source directory AC_CONFIG_SRCDIR([ast_link.in]) # Include defaults for Starlink configurations STAR_DEFAULTS # See if the --with-starmem option has been provided. This sets the # preprocesor macro HAVE_STAR_MEM_H. AC_ARG_WITH( [starmem], AS_HELP_STRING([--with-starmem],[use starmem library for memory management]), AC_DEFINE([HAVE_STAR_MEM_H],[1],[Use the starmem library for memory management]), ) # See if the --with-memdebug option has been provided. This sets the # preprocesor macro MEM_DEBUG which enables facilities used to track # down memory leaks, etc. AC_ARG_WITH( [memdebug], AS_HELP_STRING([--with-memdebug],[enable AST memory leak debugging functions]), AC_DEFINE([MEM_DEBUG],[1],[enable AST memory leak debugging functions in memory.c]), ) # See if the --with-external_pal option has been provided. This sets the # preprocesor macro EXTERNAL_PAL which prevents use of the PAL & ERFA # library functions that are included in the AST distribution. Suitable # link options are used within ast_link(_adam) scripts to pull in libpal. AC_ARG_WITH([external_pal], [ --with-external_pal Use external PAL and ERFA libraries], if test "$withval" = "yes"; then external_pal="1" else external_pal="0" fi, external_pal="0") AC_SUBST( EXTERNAL_PAL, $external_pal ) if test "$external_pal" = "1"; then AC_SUBST( LIBPAL, "-lpal" ) AC_DEFINE([EXTERNAL_PAL],[1],[use external PAL and ERFA libraries]), else AC_SUBST( LIBPAL, "" ) fi AM_CONDITIONAL(EXTERNAL_PAL, test x$external_pal = x1) # Checks for programs AC_PROG_CC AC_PROG_CPP LT_INIT AC_PROG_LN_S # If --with-pic=no is set we should honour that. AM_CONDITIONAL(NOPIC, test x$pic_mode = xno) # Conditional defining whether we build with POSIX thread support. AC_ARG_WITH([pthreads], [ --without-pthreads Build package without POSIX threads support], if test "$withval" = "yes"; then use_pthreads="1" else use_pthreads="0" fi, use_pthreads="1") if test "$use_pthreads" = "1"; then AC_CHECK_LIB([pthread], [pthread_create], ,[use_pthreads="0"]) fi AM_CONDITIONAL(NOTHREADS, test x$use_pthreads = x0) AC_SUBST(THREADS, $use_pthreads) # See which variadic function API to use AC_CHECK_HEADERS(stdarg.h varargs.h, break) # Can we use backtrace? AC_CHECK_HEADERS([execinfo.h]) AC_CHECK_FUNCS([backtrace]) # Do we have reentrant strerror and strtok? AC_CHECK_FUNCS([strerror_r strtok_r]) # Do we have vsnprintf? AC_CHECK_FUNCS([vsnprintf]) # See if we have long doubles (used by the Mapping and Region classes) AC_CHECK_TYPES([long double]) # See if we have 64 bit integers. AC_CHECK_TYPES([int64_t, uint64_t]) # Calculate alternative 64 bit integer sizes AC_CHECK_SIZEOF(long) AC_CHECK_SIZEOF(long long) # Conditional defining whether we want to support Fortran libraries # (e.g. pgplot) and applications. AC_ARG_WITH([fortran], [ --without-fortran Build package without Fortran support], if test "$withval" = "yes"; then use_fortran="1" else use_fortran="0" fi, use_fortran="1") AM_CONDITIONAL(NOFORTRAN, test x$use_fortran = x0) AC_SUBST(FORTRAN, $use_fortran) # ast_link needs to be able to link against the Fortran runtime if # necessary if test "$use_fortran" = "1"; then AC_PROG_FC AC_FC_LIBRARY_LDFLAGS fi # Find an absolute path to the Perl binary, augmenting the path with the # location of the Starlink Perl build. If this fails, then set @PERL@ # to the backup `/usr/bin/env perl', which will find Perl if it exists # in the path at runtime. AC_PATH_PROG(PERL, perl, [/usr/bin/env perl], [$STARLINK/Perl/bin:$PATH]) # Function and declaration checks AC_CHECK_FUNCS([isnan]) AC_CHECK_DECLS([isnan],,,[#include ]) AC_CHECK_FUNCS([isfinite]) AC_CHECK_DECLS([isfinite],,,[#include ]) STAR_DECLARE_DEPENDENCIES(sourceset, [sst htx]) # Perform the check that configures f77.h.in for the return type of REAL # Fortran functions. On 64-bit g77 with f2c compatibility this is double # not float. if test "$use_fortran" = "1"; then STAR_CNF_F2C_COMPATIBLE # Determine the type of Fortran character string lengths. STAR_CNF_TRAIL_TYPE fi # Declare the message file. STAR_MESSGEN(ast_err.msg) # Test for non-ANSI behaviour in sscanf on some platforms, reported by # Bill Joye. Also check for bad MINGW sscanf. That returns nc=0 in the # System test. AC_MSG_CHECKING([whether the sscanf function is ANSI-compatible]) AC_RUN_IFELSE([AC_LANG_SOURCE([[ #include #include int main() { char foo[] = " name 1111.1 "; char mingw[] = "system= FK4_NO_E"; char bar[8]; float ff; int system; int nc; int r; nc = 0; r = sscanf(foo, " %s %f %n", bar, &ff, &nc); if ( nc == 13 ) { nc = 0; r = sscanf( mingw, "system= %n%*s %n", &system, &nc ); if ( nc != 0 ) nc = 13; } exit( ( nc != 13 ) ? 0 : 1 ); } ]])],[ AC_MSG_RESULT([no]);AC_DEFINE([HAVE_NONANSI_SSCANF],[1],[The sscanf shows the non-ANSI behaviour reported by Bill Joye]) ],[AC_MSG_RESULT([yes])],[ AC_DEFINE([HAVE_NONANSI_SSCANF],[1],[The sscanf may show the non-ANSI behaviour reported by Bill Joye]) ]) # Declare the documentation. We need to do complicated things to # satisfy these targets, so give a non-null value # for the second argument, to suppress automatic generation of # rules. STAR_LATEX_DOCUMENTATION([sun210 sun211], [sun210.pdf sun210.tex sun211.pdf sun211.tex sun210.htx_tar sun211.htx_tar]) STAR_PREDIST_SOURCES(sun_master.tex) STAR_CHECK_PROGS(star2html) STAR_CHECK_PROGS(prolat, sst) # prolat is part of SST AC_CONFIG_HEADERS(config.h) AC_CONFIG_FILES(Makefile component.xml ast_link ast_link_adam object.h) if test "$use_fortran" = "1"; then AC_CONFIG_FILES(f77.h) fi AC_CONFIG_FILES([ast_cpp], [chmod +x ast_cpp]) # Following are files which are substituted by the Makefile at # distribution time, rather than by configure. They are not distributed. STAR_PREDIST_SOURCES(version.h.in builddocs.in addversion.in) AC_OUTPUT ast-8.3.0/circle.c0000664000175000017500000030164313004147321010643 00000000000000/* *class++ * Name: * Circle * Purpose: * A circular or spherical region within a Frame. * Constructor Function: c astCircle f AST_CIRCLE * Description: * The Circle class implements a Region which represents a circle or * sphere within a Frame. * Inheritance: * The Circle class inherits from the Region class. * Attributes: * The Circle class does not define any new attributes beyond * those which are applicable to all Regions. * Functions: c In addition to those functions applicable to all Regions, the c following functions may also be applied to all Circles: f In addition to those routines applicable to all Regions, the f following routines may also be applied to all Circles: * c - astCirclePars: Get the geometric parameters of the Circle f - AST_CIRCLEPARS: Get the geometric parameters of the Circle * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 31-AUG-2004 (DSB): * Original version. * 4-NOV-2013 (DSB): * Modify RegPins so that it can handle uncertainty regions that straddle * a discontinuity. Previously, such uncertainty Regions could have a huge * bounding box resulting in matching region being far too big. *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 Circle /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "box.h" /* Box Regions */ #include "wcsmap.h" /* Definitons of AST__DPI etc */ #include "circle.h" /* Interface definition for this class */ #include "ellipse.h" /* Interface definition for ellipse class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mapping */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (* parent_resetcache)( AstRegion *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Circle) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Circle,Class_Init) #define class_vtab astGLOBAL(Circle,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstCircleVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstCircle *astCircleId_( void *, int, const double[], const double[], void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double *CircumPoint( AstFrame *, int, const double *, double, int * ); static double *RegCentre( AstRegion *this, double *, double **, int, int, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static int RegTrace( AstRegion *, int, double *, double **, int * ); static void Cache( AstCircle *, int * ); static void CalcPars( AstFrame *, AstPointSet *, double *, double *, double *, int * ); static void CirclePars( AstCircle *, double *, double *, double *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void ResetCache( AstRegion *this, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); /* Member functions. */ /* ================= */ AstRegion *astBestCircle_( AstPointSet *mesh, double *cen, AstRegion *unc, int *status ){ /* *+ * Name: * astBestCircle * Purpose: * Find the best fitting Circle through a given mesh of points. * Type: * Protected function. * Synopsis: * #include "circle.h" * AstRegion *astBestCircle( AstPointSet *mesh, double *cen, AstRegion *unc ) * Class Membership: * Circle member function * Description: * This function finds the best fitting Circle through a given mesh of * points. * Parameters: * mesh * Pointer to a PointSet holding the mesh of points. They are * assumed to be in the Frame represented by "unc". * cen * Pointer to an array holding the coordinates of the new Circle * centre. * unc * A Region representing the uncertainty associated with each point * on the mesh. * Returned Value: * Pointer to the best fitting Circle. It will inherit the positional * uncertainty and Frame represented by "unc". * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. *- */ /* Local Variables: */ AstRegion *result; double *p; double rad; double **ptr; double d; double s2r; double p0; int ic; int ip; int n; int nc; int np; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get no. of points in the mesh, and the number of axis values per point. */ np = astGetNpoint( mesh ); nc = astGetNcoord( mesh ); /* Get pointers to the axis values. */ ptr = astGetPoints( mesh ); /* Check pointers can be used safely */ if( astOK ) { /* We find ther sum of the squared axis increments from the supplied centre to each of the supplied points. Initialise the sum to zero. */ s2r = 0.0; n = 0; /* Loop round all axes. */ for( ic = 0; ic < nc; ic++ ) { p = ptr[ ic ]; p0 = cen[ ic ]; /* Loop round all values for this axis. */ for( ip = 0; ip < np; ip++, p++ ) { if( *p != AST__BAD ) { /* Increment the sums */ d = *p - p0; s2r += d*d; n++; } } } /* Find the RMS distance of the points from the supplied centre. This is the radius of the best fitting circle. */ if( n > 0 ) { rad = sqrt( nc*s2r/n ); /* Create the returned Region. */ result = (AstRegion *) astCircle( unc, 1, cen, &rad, unc, "", status ); } } /* Return NULL if anything went wrong. */ if( !astOK ) result = astAnnul( result ); /* Return the result.*/ return result; } static void Cache( AstCircle *this, int *status ){ /* * Name: * Cache * Purpose: * Calculate intermediate values and cache them in the Circle structure. * Type: * Private function. * Synopsis: * #include "circle.h" * void Cache( AstCircle *this, int *status ) * Class Membership: * Circle member function * Description: * This function uses the PointSet stored in the parent Region to calculate * some intermediate values which are useful in other methods. These * values are stored within the Circle structure. * Parameters: * this * Pointer to the Circle. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; double *centre; double *lb; double *ub; double radius; int i; int nc; /* Check the global error status. */ if ( !astOK ) return; /* Do Nothing if the cached information is up to date. */ if( this->stale ) { /* Get a pointer to the base Frame and the number of base axes. */ frm = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); nc = astGetNaxes( frm ); /* Allocate memory to hold the centre coords. */ centre = astMalloc( sizeof( double )*astGetNaxes( frm ) ); /* Get the radius and centre of the Circle in the base Frame, using the centre and circumference positions stored in the parent Region structure. */ CalcPars( frm, ( (AstRegion *) this)->points, centre, &radius, NULL, status ); /* Allocate memory to store the base frame bounding box. This is just initialised here. It is set properly when the astRegBaseMesh function is called. This box should not be used unless the "basemesh" component of the parent Region structure is set to a non-null value. */ lb = (double *) astMalloc( sizeof( double )*(size_t) nc ); ub = (double *) astMalloc( sizeof( double )*(size_t) nc ); /* Initialise the bounding box. */ for( i = 0; astOK && i < nc; i++ ) { lb[ i ] = -DBL_MAX; ub[ i ] = DBL_MAX; } /* If everything went OK, store these values in the Circle structure. */ if( astOK ) { this->radius = radius; astFree( this->centre ); this->centre = centre; centre = NULL; astFree( this->lb ); this->lb = lb; lb = NULL; astFree( this->ub ); this->ub = ub; ub = NULL; } /* Free resources */ frm = astAnnul( frm ); if( centre ) centre = astFree( centre ); /* Indicate cached information is up to date. */ this->stale = 0; } } static void CalcPars( AstFrame *frm, AstPointSet *pset, double *centre, double *radius, double *p1, int *status ){ /* * Name: * CalcPars * Purpose: * Calculate the geometric parameters of the supplied Circle. * Type: * Private function. * Synopsis: * #include "circle.h" * double *CalcPars( AstFrame *frm, AstPointSet *pset, double *centre, * double *radius, double *p1, int *status ) * Class Membership: * Circle member function * Description: * This function uses the supplied PointSet to calculate the geometric * parameters that describe the a crcle. These values are returned in * a newly allocated dynamic array. * Parameters: * frm * Pointer to the Frame in which the circle is defined. * pset * Pointer to a PointSet. The first point should be the circle * centre, and the second point should be a point on the circle * circumference. * centre * An array in which to return the axis values at the circle centre. * The length of this array should be no less than the number of * axes in "frm". * radius * Pointer to a double in which to return the circle radius, * expressed as a geodesic distance in the supplied Frame. * p1 * An array in which to return the coordinates of a point on the * circumference of the circle. The length of this array should be * no less than the number of axes in "frm". Can be NULL if the * circumference position is not needed. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double **ptr; double *circum; int i; int nc; /* Check the global error status. */ if ( !astOK ) return; /* Get and the number of axes. */ nc = astGetNaxes( frm ); /* Get pointers to the coordinate data in the supplied PointSet. */ ptr = astGetPoints( pset ); /* If no p1 array was supplied, create a temporary work array to hold the circumference position. */ if( !p1 ) { circum = astMalloc( sizeof( double )*nc ); } else { circum = p1; } /* Check pointers can be used safely. */ if( ptr ) { /* Copy the two points in to the allocated memory. */ for( i = 0; i < nc; i++ ) { centre[ i ] = ptr[ i ][ 0 ]; circum[ i ] = ptr[ i ][ 1 ]; } /* Return the geodesic distance between these two points as the radius. */ *radius = astDistance( frm, centre, circum ); } /* Free any work array. */ if( !p1 ) circum = astFree( circum ); } static void CirclePars( AstCircle *this, double *centre, double *radius, double *p1, int *status ){ /* *++ * Name: c astCirclePars f AST_CIRCLEPARS * Purpose: * Returns the geometric parameters of an Circle. * Type: * Public virtual function. * Synopsis: c #include "circle.h" c void astCirclePars( AstCircle *this, double *centre, double *radius, c double *p1 ) f CALL AST_CIRCLEPARS( THIS, CENTRE, RADIUS, P1, STATUS ) * Class Membership: * Region method. * Description: c This function f This routine * returns the geometric parameters describing the supplied Circle. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Region. c centre f CENTRE( * ) = DOUBLE PRECISION (Returned) c Pointer to an array f An array * in which to return the coordinates of the Circle centre. * The length of this array should be no less than the number of * axes in the associated coordinate system. c radius f RADIUS = DOUBLE PRECISION (Returned) * Returned holding the radius of the Circle, as an geodesic * distance in the associated coordinate system. c p1 f P1( * ) = DOUBLE PRECISION (Returned) c Pointer to an array f An array * in which to return the coordinates of a point on the * circumference of the Circle. The length of this array should be * no less than the number of axes in the associated coordinate system. c A NULL pointer can be supplied if the circumference position is c not needed. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If the coordinate system represented by the Circle has been * changed since it was first created, the returned parameters refer * to the new (changed) coordinate system, rather than the original * coordinate system. Note however that if the transformation from * original to new coordinate system is non-linear, the shape * represented by the supplied Circle object may not be an accurate * circle. *-- */ /* Local Variables: */ AstRegion *this_region; /* Parent Region pointer */ AstFrame *frm; /* Current Frame represented by the Circle */ AstPointSet *pset; /* PointSet holding PointList axis values */ /* Check the inherited status. */ if( !astOK ) return; /* Store a pointer to the parent region structure. */ this_region = (AstRegion *) this; /* Transform the base Frame axis values into the current Frame. */ pset = astTransform( this_region->frameset, this_region->points, 1, NULL ); /* Get the Circle frame. */ frm = astGetFrame( this_region->frameset, AST__CURRENT ); /* Calculate the required parameters. */ CalcPars( frm, pset, centre, radius, p1, status ); /* Free resources */ frm = astAnnul( frm ); pset = astAnnul( pset ); } static double *CircumPoint( AstFrame *frm, int nax, const double *centre, double radius, int *status ){ /* * Name: * CircumPoint * Purpose: * Find a point on the circumference of the circle. * Type: * Private function. * Synopsis: * #include "circle.h" * double *CircumPoint( AstFrame *frm, int nax, const double *centre, * double radius, int *status ) * Class Membership: * Circle member function * Description: * This function returns a dynamically allocated array containing the * axis values at a point on the circumference of the circle specified * by a given centre and radius. The returned point is the point at * which the circle crosses the first axis. * Parameters: * frm * Pointer to the Frame in which the circle is defined. * nax * The number of axes in the Frame. * centre * An array holding the axis values at the circle centre. * radius * The circle radius, expressed as a geodesic distance in the * supplied Frame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a 1D array holding the axis values at the point where * the circle crosses the first frame axis. The length of this array * will equal the number of axes in the supsplied Frame. It should be * freed using astFree when no longer needed. */ /* Local Variables: */ double *circum; double *work; int i; /* Check the global error status. */ if ( !astOK ) return NULL; /* Allocate the returned array. */ circum = astMalloc( sizeof( double)*(size_t) nax ); /* Allocate work space */ work = astMalloc( sizeof( double)*(size_t) nax ); /* Check pointers can be used safely. */ if( astOK ) { /* Find the coords of a point that is offset away from the centre position along the first axis. We use the supplied radius value as a convenient offset length, but the actual length used is not critical. */ for( i = 0; i < nax; i++ ) work[ i ] = centre[ i ]; work[ 0 ] = astAxOffset( frm, 1, work[ 0 ], radius ); /* Offset away from the centre position, towards the position found above, going the distance specified by the supplied radius. */ astOffset( frm, centre, work, radius, (double *) circum ); } /* Free resources. */ work = astFree( work ); /* Return the result. */ return circum; } void astInitCircleVtab_( AstCircleVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitCircleVtab * Purpose: * Initialise a virtual function table for a Circle. * Type: * Protected function. * Synopsis: * #include "circle.h" * void astInitCircleVtab( AstCircleVtab *vtab, const char *name ) * Class Membership: * Circle vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Circle 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsACircle) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->CirclePars = CirclePars; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_resetcache = region->ResetCache; region->ResetCache = ResetCache; region->RegPins = RegPins; region->RegTrace = RegTrace; region->RegBaseMesh = RegBaseMesh; region->RegBaseBox = RegBaseBox; region->RegCentre = RegCentre; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump functions. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Circle", "Circular or spherical region" ); /* 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 RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "circle.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Circle member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstCircle *this; /* Pointer to Circle structure */ AstFrame *frm; /* Pointer to base Frame */ const char *class; /* Pointer to class name */ int i; /* Axis index */ int nb; /* No. of axes in base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Circle structure */ this = (AstCircle *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* Get a pointer to the base Frame in the Region, and get the number of axes. */ frm = astGetFrame( this_region->frameset, AST__BASE ); nb = astGetNaxes( frm ); /* If the Frame is a simple Frame, we can assume plane geometry. */ class = astGetClass( frm ); if( class && !strcmp( class, "Frame" ) ) { for( i = 0; i < nb; i++ ) { lbnd[ i ] = ( this->centre )[ i ] - this->radius; ubnd[ i ] = ( this->centre )[ i ] + this->radius; } /* If the Frame is not a simple Frame we cannot assume plane geometry. */ } else { /* The bounding box of the mesh returned by astRegBaseMesh is used as the bounding box of the Circle. These bounds are cached in the Circle structure by astRegBaseMesh. Ensure astRegBaseMesh has been invoked, so that it is safe to use the cached bounding box. */ if( !this_region->basemesh ) (void) astAnnul( astRegBaseMesh( this ) ); /* Store the bounding box. */ for( i = 0; i < nb; i++ ) { lbnd[ i ] = this->lb[ i ]; ubnd[ i ] = this->ub[ i ]; } } /* Free resources. */ frm = astAnnul( frm ); } static AstPointSet *RegBaseMesh( AstRegion *this_region, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "circle.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Circle member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. The axis values in this PointSet will have * associated accuracies derived from the accuracies which were * supplied when the Region was created. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Constants: */ #define NP_EDGE 50 /* No. of points for determining geodesic */ /* Local Variables: */ AstBox *box; /* Bounding box for this Circle */ AstCircle *this; /* The Circle structure */ AstRegion *reg; /* Copy of supplied Circle */ AstFrame *frm; /* Base Frame in encapsulated FrameSet */ AstPointSet *result; /* Returned pointer */ double **ptr; /* Pointers to data */ double *p1; /* Pointer to array holding a single point */ double *p2; /* Pointer to array holding a single point */ double angle; /* Angular position of point */ double delta; /* Angular separation of points */ double dist; /* Offset along an axis */ double lbx; /* Lower x bound of mesh bounding box */ double lby; /* Lower y bound of mesh bounding box */ double p[ 2 ]; /* Position in 2D Frame */ double ubx; /* Upper x bound of mesh bounding box */ double uby; /* Upper y bound of mesh bounding box */ int i; /* Point index */ int j; /* Axis index */ int naxes; /* No. of axes in base Frame */ int np; /* No. of points in returned PointSet */ /* Initialise */ result= NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this_region->basemesh ) { result = astClone( this_region->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Get a pointer to the Circle structure. */ this = (AstCircle *) this_region; /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Get the number of axes in the base Frame */ naxes = astGetNaxes( frm ); /* Get the requested number of points to put on the mesh. */ np = astGetMeshSize( this ); /* Ensure cached information is available. */ Cache( (AstCircle *) this, status ); /* First deal with 1-D "circles" (where we ignore MeshSize). */ if( naxes == 1 ) { /* The boundary of a 1-D circle consists of 2 points - the two extreme values. Create a PointSet to hold 2 1-D values, and store the extreme values. */ result = astPointSet( 2, 1, "", status ); ptr = astGetPoints( result ); if( astOK ) { ptr[ 0 ][ 0 ] = ( this->centre )[ 0 ] - this->radius; ptr[ 0 ][ 1 ] = ( this->centre )[ 0 ] + this->radius; } /* Store the bounding box in the Circle structure. */ this->lb[ 0 ] = ptr[ 0 ][ 0 ]; this->ub[ 0 ] = ptr[ 0 ][ 1 ]; /* Now deal with 2-D circles. */ } else if( naxes == 2 ){ /* Store the angular increment between points. */ delta = 2*AST__DPI/np; /* Create a suitable PointSet to hold the returned positions. */ result = astPointSet( np, 2, "", status ); ptr = astGetPoints( result ); if( astOK ) { /* Initialise the bounding box of the mesh points. */ lbx = DBL_MAX; ubx = -DBL_MAX; lby = DBL_MAX; uby = -DBL_MAX; /* Loop round each point. */ angle = 0.0; for( i = 0; i < np; i++ ) { /* Work out where the end of the radius vector at this angle is, and store in the returned PointSet. */ astOffset2( frm, this->centre, angle, this->radius, p ); ptr[ 0 ][ i ] = p[ 0 ]; ptr[ 1 ][ i ] = p[ 1 ]; /* Update the bounds of the mesh bounding box. The box is expressed in terms of axis offsets from the centre, in order to avoid problems with boxes that cross RA=0 or RA=12h */ if( p[ 0 ] != AST__BAD && p[ 1 ] != AST__BAD ){ dist = astAxDistance( frm, 1, this->centre[ 0 ], p[ 0 ] ); if( dist < lbx ) { lbx = dist; } else if( dist > ubx ) { ubx = dist; } dist = astAxDistance( frm, 2, this->centre[ 1 ], p[ 1 ] ); if( dist < lby ) { lby = dist; } else if( dist > uby ) { uby = dist; } } /* Increment the angular position of the next mesh point. */ angle += delta; } /* Store the bounding box in the Circle structure. */ this->lb[ 0 ] = this->centre[ 0 ] + lbx; this->lb[ 1 ] = this->centre[ 1 ] + lby; this->ub[ 0 ] = this->centre[ 0 ] + ubx; this->ub[ 1 ] = this->centre[ 1 ] + uby; } /* Now deal with circles with more than 2 dimensions. Producing an evenly spread mesh of points over a sphere is a complex task (see e.g. http://www.eso.org/science/healpix/ ). This implementation does not attempt to produce a genuinely even spread. Instead it simply uses the mesh for the bounding box of the sphere, and projects each point on to the surface of the sphere. */ } else { /* Allocate memory to hold an approximation of the circle bounding box. */ p1 = astMalloc( sizeof( double )*(size_t) naxes ); p2 = astMalloc( sizeof( double )*(size_t) naxes ); /* Get an approximation to the bounding box, and initialise the real bounding box of the mesh points. */ if( astOK ) { memcpy( p1, this->centre, sizeof( double )*(size_t) naxes ); for( j = 0; j < naxes; j++ ) { p1[ j ] += this->radius; astOffset( frm, this->centre, p1, this->radius, p2 ); p1[ j ] = this->centre[ j ]; this->ub[ j ] = p2[ j ]; } } /* Create a Box region which just encompasses the circle. */ box = astBox( frm, 0, this->centre, this->ub, NULL, "", status ); /* Get a mesh covering this box. */ astSetMeshSize( box, np ); result = astRegBaseMesh( box ); ptr = astGetPoints( result ); np = astGetNpoint( result ); /* Allocate memory for a single point */ if( astOK ) { /* Initialise the real bounding box of the mesh points. */ for( j = 0; j < naxes; j++ ) { this->lb[ j ] = DBL_MAX; this->ub[ j ] = -DBL_MAX; } /* Move each point in this mesh radially so that its distance from the centre equals the radius of this Circle. */ for( i = 0; i < np; i++ ) { for( j = 0; j < naxes; j++ ) p1[ j ] = ptr[ j ][ i ]; astOffset( frm, this->centre, p1, this->radius, p2 ); for( j = 0; j < naxes; j++ ) { ptr[ j ][ i ] = p2[ j ]; /* Update the bounds of the mesh bounding box. */ if( p2[ j ] != AST__BAD ){ if( p2[ j ] < this->lb[ j ] ) { this->lb[ j ] = p2[ j ]; } else if( p2[ j ] > this->ub[ j ] ) { this->ub[ j ] = p2[ j ]; } } } } } /* Same the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this_region->basemesh = astClone( result ); /* Free resources. */ p1 = astFree( p1 ); p2 = astFree( p2 ); box = astAnnul( box ); } /* Extend the bounding box if it contains any singularies. The astNormBox requires a Mapping which can be used to test points in the base Frame. Create a copy of the Circle and then set its FrameSet so that the current Frame in the copy is the same as the base Frame in the original. */ reg = astCopy( this ); astSetRegFS( reg, frm ); astSetNegated( reg, 0 ); /* Normalise this box. */ astNormBox( frm, this->lb, this->ub, reg ); /* Free resources. */ reg = astAnnul( reg ); frm = astAnnul( frm ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static double *RegCentre( AstRegion *this_region, double *cen, double **ptr, int index, int ifrm, int *status ){ /* * Name: * RegCentre * Purpose: * Re-centre a Region. * Type: * Private function. * Synopsis: * #include "circle.h" * double *RegCentre( AstRegion *this, double *cen, double **ptr, * int index, int ifrm, int *status ) * Class Membership: * Circle member function (over-rides the astRegCentre protected * method inherited from the Region class). * Description: * This function shifts the centre of the supplied Region to a * specified position, or returns the current centre of the Region. * Parameters: * this * Pointer to the Region. * cen * Pointer to an array of axis values, giving the new centre. * Supply a NULL value for this in order to use "ptr" and "index" to * specify the new centre. * ptr * Pointer to an array of pointers, one for each axis in the Region. * Each pointer locates an array of axis values. This is the format * returned by the PointSet method astGetPoints. Only used if "cen" * is NULL. * index * The index of the point within the arrays identified by "ptr" at * which is stored the coords for the new centre position. Only used * if "cen" is NULL. * ifrm * Should be AST__BASE or AST__CURRENT. Indicates whether the centre * position is supplied and returned in the base or current Frame of * the FrameSet encapsulated within "this". * status * Pointer to the inherited status variable. * Returned Value: * If both "cen" and "ptr" are NULL then a pointer to a newly * allocated dynamic array is returned which contains the centre * coords of the Region. This array should be freed using astFree when * no longer needed. If either of "ptr" or "cen" is not NULL, then a * NULL pointer is returned. * Notes: * - Some Region sub-classes do not have a centre. Such classes will report * an AST__INTER error code if this method is called. */ /* Local Variables: */ AstFrame *frm; /* Pointer to base Frame */ AstCircle *this; /* Pointer to Circle structure */ double **rptr; /* Data pointers for Region PointSet */ double *bc; /* Base Frame centre position */ double *circum; /* Base frame circumference position */ double *result; /* Returned pointer */ double *tmp; /* Temporary array pointer */ double axval; /* Axis value */ int ic; /* Coordinate index */ int ncb; /* Number of base frame coordinate values per point */ int ncc; /* Number of current frame coordinate values per point */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get a pointer to the Circle structure. */ this = (AstCircle *) this_region; /* Get the number of axis values per point in the base and current Frames. */ ncb = astGetNin( this_region->frameset ); ncc = astGetNout( this_region->frameset ); /* Ensure cached information is available. */ Cache( this, status ); /* If the centre coords are to be returned, return either a copy of the base Frame centre coords, or transform the base Frame centre coords into the current Frame. */ if( !ptr && !cen ) { if( ifrm == AST__CURRENT ) { result = astRegTranPoint( this_region, this->centre, 1, 1 ); } else { result = astStore( NULL, this->centre, sizeof( double )*ncb ); } /* Otherwise, we store the supplied new centre coords and return a NULL pointer. */ } else { /* Get a pointer to the base Frame in the Region's FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Get a pointer to the axis values stored in the Region structure. */ rptr = astGetPoints( this_region->points ); /* Check pointers can be used safely */ if( astOK ) { /* If the centre position was supplied in the current Frame, find the corresponding base Frame position... */ if( ifrm == AST__CURRENT ) { if( cen ) { bc = astRegTranPoint( this_region, cen, 1, 0 ); } else { tmp = astMalloc( sizeof( double)*(size_t)ncc ); if( astOK ) { for( ic = 0; ic < ncc; ic++ ) tmp[ ic ] = ptr[ ic ][ index ]; } bc = astRegTranPoint( this_region, tmp, 1, 0 ); tmp = astFree( tmp ); } /* Replace any bad centre values with their current values. */ for( ic = 0; ic < ncb; ic++ ) { if( bc[ ic ] == AST__BAD ) bc[ ic ] = this->centre[ ic ]; } /* ... and change the coords in the parent Region structure and the cached coords in the Circle structure. */ circum = CircumPoint( frm, ncb, bc, this->radius, status ); if( circum ) { for( ic = 0; ic < ncb; ic++ ) { rptr[ ic ][ 0 ] = bc[ ic ]; rptr[ ic ][ 1 ] = circum[ ic ]; this->centre[ ic ] = bc[ ic ]; } } /* Free resources */ circum = astFree( circum ); bc = astFree( bc ); /* If the centre position was supplied in the base Frame, use the supplied "cen" or "ptr" pointer directly to change the coords in the parent Region structure and the cached coords in the Circle structure. */ } else { for( ic = 0; ic < ncb; ic++ ) { axval = cen ? cen[ ic ] : ptr[ ic ][ index ]; if( axval != AST__BAD ) this->centre[ ic ] = axval; } circum = CircumPoint( frm, ncb, this->centre, this->radius, status ); if( circum ) { for( ic = 0; ic < ncb; ic++ ) { rptr[ ic ][ 0 ] = this->centre[ ic ]; rptr[ ic ][ 1 ] = circum[ ic ]; } circum = astFree( circum ); } } } /* Free resources */ frm = astAnnul( frm ); } /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Circle. * Type: * Private function. * Synopsis: * #include "circle.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ){ * Class Membership: * Circle member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Circle. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Circle "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Circle. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstCircle *large_circle; /* Circle slightly larger than "this" */ AstCircle *small_circle; /* Circle slightly smaller than "this" */ AstCircle *this; /* Pointer to the Circle structure. */ AstFrame *frm; /* Base Frame in supplied Circle */ AstPointSet *ps1; /* Points masked by larger Circle */ AstPointSet *ps2; /* Points masked by larger and smaller Circlees */ AstRegion *tunc; /* Uncertainity Region from "this" */ double **ptr; /* Pointer to axis values in "ps2" */ double *lbnd_tunc; /* Lower bounds of "this" uncertainty Region */ double *lbnd_unc; /* Lower bounds of supplied uncertainty Region */ double *p; /* Pointer to next axis value */ double *safe; /* An interior point in "this" */ double *ubnd_tunc; /* Upper bounds of "this" uncertainty Region */ double *ubnd_unc; /* Upper bounds of supplied uncertainty Region */ double drad; /* Radius increment corresponding to border width */ double l1; /* Length of bounding box diagonal */ double l2; /* Length of bounding box diagonal */ double rad; /* Radius of Circle */ int i; /* Axis index */ int j; /* Point index */ int nc; /* No. of axes in Circle base frame */ int np; /* No. of supplied points */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Circle structure. */ this = (AstCircle *) this_region; /* Get the number of base Frame axes in the Circle, and check the supplied PointSet has the same number of axis values per point. */ frm = astGetFrame( this_region->frameset, AST__BASE ); nc = astGetNaxes( frm ); if( astGetNcoord( pset ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axis " "values per point (%d) in the supplied PointSet - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNcoord( pset ), nc ); } /* Get the number of axes in the uncertainty Region and check it is the same as above. */ if( unc && astGetNaxes( unc ) != nc && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axes (%d) " "in the supplied uncertainty Region - should be " "%d (internal AST programming error).", status, astGetClass( this ), astGetNaxes( unc ), nc ); } /* Get the centre of the region in the base Frame. We use this as a "safe" interior point within the region. */ safe = astRegCentre( this, NULL, NULL, 0, AST__BASE ); /* We now find the maximum distance on each axis that a point can be from the boundary of the Circle for it still to be considered to be on the boundary. First get the Region which defines the uncertainty within the Circle being checked (in its base Frame), re-centre it on the interior point found above (to avoid problems if the uncertainty region straddles a discontinuity), and get its bounding box. */ tunc = astGetUncFrm( this, AST__BASE ); if( safe ) astRegCentre( tunc, safe, NULL, 0, AST__CURRENT ); lbnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_tunc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( tunc, lbnd_tunc, ubnd_tunc ); /* Find the geodesic length within the base Frame of "this" of the diagonal of the bounding box. */ l1 = astDistance( frm, lbnd_tunc, ubnd_tunc ); /* Also get the Region which defines the uncertainty of the supplied points and get its bounding box. First re-centre the uncertainty at the interior position to avoid problems from uncertainties that straddle a discontinuity. */ if( unc ) { if( safe ) astRegCentre( unc, safe, NULL, 0, AST__CURRENT ); lbnd_unc = astMalloc( sizeof( double )*(size_t) nc ); ubnd_unc = astMalloc( sizeof( double )*(size_t) nc ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); /* Find the geodesic length of the diagonal of this bounding box. */ l2 = astDistance( frm, lbnd_unc, ubnd_unc ); /* Use a zero sized box "unc" if no box was supplied. */ } else { lbnd_unc = NULL; ubnd_unc = NULL; l2 = 0.0; } /* Ensure cached information is available. */ Cache( this, status ); /* The required border width is half of the total diagonal of the two bounding boxes. */ if( astOK ) { drad = 0.5*( l1 + l2 ); /* Create two new Circle, one of which is larger than "this" by the amount found above, and the other of which is smaller than "this" by the amount found above. */ rad = this->radius + 0.5*drad; large_circle = astCircle( frm, 1, this->centre, &rad, NULL, "", status ); rad = this->radius - 0.5*drad; small_circle = astCircle( frm, 1, this->centre, &rad, NULL, "", status ); /* Negate the smaller region.*/ astNegate( small_circle ); /* Points are on the boundary of "this" if they are inside both the large Circle and the negated small Circle. First transform the supplied PointSet using the large Circle, then transform them using the negated smaller Circle. */ ps1 = astTransform( large_circle, pset, 1, NULL ); ps2 = astTransform( small_circle, ps1, 1, NULL ); /* Get a point to the resulting axis values, and the number of axis values per axis. */ ptr = astGetPoints( ps2 ); np = astGetNpoint( ps2 ); /* If a mask array is to be returned, create one. */ if( mask ) { *mask = astMalloc( sizeof(int)*(size_t) np ); /* Check all the resulting points, setting mask values for all of them. */ if( astOK ) { /* Initialise the mask elements on the basis of the first axis values */ result = 1; p = ptr[ 0 ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } else { (*mask)[ j ] = 1; } } /* Now check for bad values on other axes. */ for( i = 1; i < nc; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } } } } /* If no output mask is to be made, we can break out of the check as soon as the first bad value is found. */ } else if( astOK ) { result = 1; for( i = 0; i < nc && result; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; break; } } } } /* Free resources. */ large_circle = astAnnul( large_circle ); small_circle = astAnnul( small_circle ); ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } tunc = astAnnul( tunc ); frm = astAnnul( frm ); lbnd_tunc = astFree( lbnd_tunc ); ubnd_tunc = astFree( ubnd_tunc ); if( unc ) lbnd_unc = astFree( lbnd_unc ); if( unc ) ubnd_unc = astFree( ubnd_unc ); safe = astFree( safe ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static int RegTrace( AstRegion *this_region, int n, double *dist, double **ptr, int *status ){ /* *+ * Name: * RegTrace * Purpose: * Return requested positions on the boundary of a 2D Region. * Type: * Private function. * Synopsis: * #include "circle.h" * int astTraceRegion( AstRegion *this, int n, double *dist, double **ptr ); * Class Membership: * Circle member function (overrides the astTraceRegion method * inherited from the parent Region class). * Description: * This function returns positions on the boundary of the supplied * Region, if possible. The required positions are indicated by a * supplied list of scalar parameter values in the range zero to one. * Zero corresponds to some arbitrary starting point on the boundary, * and one corresponds to the end (which for a closed region will be * the same place as the start). * Parameters: * this * Pointer to the Region. * n * The number of positions to return. If this is zero, the function * returns without action (but the returned function value still * indicates if the method is supported or not). * dist * Pointer to an array of "n" scalar parameter values in the range * 0 to 1.0. * ptr * A pointer to an array of pointers. The number of elements in * this array should equal tthe number of axes in the Frame spanned * by the Region. Each element of the array should be a pointer to * an array of "n" doubles, in which to return the "n" values for * the corresponding axis. The contents of the arrays are unchanged * if the supplied Region belongs to a class that does not * implement this method. * Returned Value: * Non-zero if the astTraceRegion method is implemented by the class * of Region supplied, and zero if not. *- */ /* Local Variables; */ AstCircle *this; AstFrame *frm; AstMapping *map; AstPointSet *bpset; AstPointSet *cpset; double **bptr; double angle; double p[ 2 ]; int i; int ncur; int result; /* Initialise */ result = 0; /* Check inherited status. */ if( ! astOK ) return result; /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Check it is 2-dimensional. */ if( astGetNaxes( frm ) == 2 ) result = 1; /* Check we have some points to find. */ if( result && n > 0 ) { /* Get a pointer to the Circle structure. */ this = (AstCircle *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* We first determine the required positions in the base Frame of the Region, and then transform them into the current Frame. Get the base->current Mapping, and the number of current Frame axes. */ map = astGetMapping( this_region->frameset, AST__BASE, AST__CURRENT ); /* If it's a UnitMap we do not need to do the transformation, so put the base Frame positions directly into the supplied arrays. */ if( astIsAUnitMap( map ) ) { bpset = NULL; bptr = ptr; ncur = 2; /* Otherwise, create a PointSet to hold the base Frame positions. */ } else { bpset = astPointSet( n, 2, " ", status ); bptr = astGetPoints( bpset ); ncur = astGetNout( map ); } /* Check the pointers can be used safely. */ if( astOK ) { /* Loop round each point. Get the angle around the circle, and offset along that angle to find the point that is one radius away from the centre. Copy the results into the required arrays. */ for( i = 0; i < n; i++ ) { angle = dist[ i ]*2*AST__DPI; astOffset2( frm, this->centre, angle, this->radius, p ); bptr[ 0 ][ i ] = p[ 0 ]; bptr[ 1 ][ i ] = p[ 1 ]; } } /* If required, transform the base frame positions into the current Frame, storing them in the supplied array. Then free resources. */ if( bpset ) { cpset = astPointSet( n, ncur, " ", status ); astSetPoints( cpset, ptr ); (void) astTransform( map, bpset, 1, cpset ); cpset = astAnnul( cpset ); bpset = astAnnul( bpset ); } /* Free remaining resources. */ map = astAnnul( map ); } frm = astAnnul( frm ); /* Return the result. */ return result; } static void ResetCache( AstRegion *this, int *status ){ /* * Name: * ResetCache * Purpose: * Clear cached information within the supplied Region. * Type: * Private function. * Synopsis: * #include "circle.h" * void ResetCache( AstRegion *this, int *status ) * Class Membership: * Region member function (overrides the astResetCache method * inherited from the parent Region class). * Description: * This function clears cached information from the supplied Region * structure. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ if( this ) { ( (AstCircle *) this )->stale = 1; (*parent_resetcache)( this, status ); } } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "circle.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Circle method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* Re-calculate cached information. */ astResetCache( this_region ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "circle.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Circle method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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: */ AstMapping *map; /* Base -> current Mapping */ AstMapping *result; /* Result pointer to return */ AstPointSet *mesh; /* Mesh of current Frame positions */ AstPointSet *ps2; /* Circle PointSet in current Frame */ AstRegion *new; /* Pointer to simplified Region */ AstRegion *newreg; /* Equivalent circle or ellipse */ AstRegion *this; /* Pointer to supplied Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr2; /* Pointer axis values in "ps2" */ double *cen; /* Pointer to array holding new centre coords */ int ic; /* Axis index */ int nc; /* No. of axis values per point */ int ok; /* Was the new centre found OK? */ int simpler; /* Has some simplication taken place? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the supplied Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* If the Mapping from base to current Frame is not a UnitMap, we attempt to simplify the Circle by re-defining it within its current Frame. Transforming the Circle from its base to its current Frame may result in the region no longer being a circle. We test this by transforming a set of bounds on the Circle boundary. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); if( !astIsAUnitMap( map ) ){ /* Get a mesh of points covering the Circle in its current Frame. */ mesh = astRegMesh( new ); /* Get the Region describing the positional uncertainty within the Circle in its current Frame. */ unc = astGetUncFrm( new, AST__CURRENT ); /* Transform the PointSet holding the circle centre into the current Frame, and copy the axis values into a new array. */ ps2 = astRegTransform( this, this->points, 1, NULL, NULL ); nc = astGetNcoord( ps2 ); cen = astMalloc( sizeof( double )*(size_t) nc ); ptr2 = astGetPoints( ps2 ); if( astOK ) { ok = 1; for( ic = 0; ic < nc; ic++ ) { cen[ ic ] = ptr2[ ic ][ 0 ]; if( cen[ ic ] == AST__BAD ) ok = 0; } /* Find the best fitting Circle (defined in the current Frame) through these points */ newreg = ok ? astBestCircle( mesh, cen, unc ) : NULL; /* See if all points within this mesh fall on the boundary of the best fitting Circle, to within the uncertainty of the Region. */ if( newreg && astRegPins( newreg, mesh, NULL, NULL ) ) { /* If so, use the new Circle in place of the original. */ (void) astAnnul( new ); new = astClone( newreg ); /* Otherwise, if the region is 2-d we see if an Ellipse can represent the mesh. */ } else if( ok && nc == 2 ){ /* Find the best fitting Ellipse (defined in the current Frame) through these points */ if( newreg ) (void) astAnnul( newreg ); newreg = astBestEllipse( mesh, cen, unc ); /* See if all points within this mesh fall on the boundary of the best fitting Ellipse, to within the uncertainty of the Region. */ if( newreg && astRegPins( newreg, mesh, NULL, NULL ) ) { /* If so, use the new Ellipse in place of the original. */ (void) astAnnul( new ); new = astClone( newreg ); simpler = 1; } } /* Free resources. */ if( newreg ) newreg = astAnnul( newreg ); } ps2 = astAnnul( ps2 ); cen = astFree( cen ); mesh = astAnnul( mesh ); unc = astAnnul( unc ); } map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Circle to transform a set of points. * Type: * Private function. * Synopsis: * #include "circle.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Circle member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a Circle and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the Circle. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the Circle. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstCircle *this; /* Pointer to Circle */ AstFrame *frm; /* Pointer to base Frame in FrameSet */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_out; /* Pointer to output coordinate data */ double **ptr_tmp; /* Pointer to base Frame coordinate data */ double *work; /* Pointer to array holding single base point */ double d; /* Base-Frame distance from centre to point */ int closed; /* Is the boundary part of the Region? */ int coord; /* Zero-based index for coordinates */ int inside; /* Is the point inside the Region? */ int ncoord_out; /* No. of coordinates per output point */ int ncoord_tmp; /* No. of coordinates per base Frame point */ int neg; /* Has the Region been negated? */ int npoint; /* No. of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the Circle structure. */ this = (AstCircle *) this_mapping; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). This call also returns a pointer to the base Frame of the encapsulated FrameSet. Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( this, in, 0, NULL, &frm ); /* Determine the numbers of points and coordinates per point from the base Frame PointSet and obtain pointers for accessing the base Frame and output coordinate values. */ npoint = astGetNpoint( pset_tmp ); ncoord_tmp = astGetNcoord( pset_tmp ); ptr_tmp = astGetPoints( pset_tmp ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* Get work space for one base Frame position */ work = astMalloc( sizeof( double )*(size_t) ncoord_tmp ); /* See if the boundary is part of the Region. */ closed = astGetClosed( this ); /* See if the Region has been negated. */ neg = astGetNegated( this ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* Ensure cached information is available. */ Cache( this, status ); /* Loop round each point */ for ( point = 0; point < npoint; point++ ) { /* Copy the base Frame position into a work array. */ for ( coord = 0; coord < ncoord_tmp; coord++ ) { work[ coord ] = ptr_tmp[ coord ][ point ]; } /* Find the geodesic distance from the centre of the Circle in the base Frame. */ d = astDistance( frm, this->centre, work ); /* Now consider whether this radius value puts the point in or out of the Circle. */ if( d != AST__BAD ){ if( neg ) { if( closed ) { inside = ( d >= this->radius ); } else { inside = ( d > this->radius ); } } else { if( closed ) { inside = ( d <= this->radius ); } else { inside = ( d < this->radius ); } } } else { inside = 0; } /* If the point is outside, store bad output values. */ if( !inside ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Free resources */ work = astFree( work ); pset_tmp = astAnnul( pset_tmp ); frm = astAnnul( frm ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Region objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Region objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstCircle *in; /* Pointer to input Circle */ AstCircle *out; /* Pointer to output Circle */ int nax; /* Number of base Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Circles. */ in = (AstCircle *) objin; out = (AstCircle *) objout; /* For safety, first clear any references to the input memory from the output Circle. */ out->centre = NULL; out->lb = NULL; out->ub = NULL; /* Copy dynamic memory contents */ nax = astGetNin( ((AstRegion *) in)->frameset ); out->centre = astStore( NULL, in->centre, sizeof( double )*(size_t)nax ); out->lb = astStore( NULL, in->lb, sizeof( double )*(size_t)nax ); out->ub = astStore( NULL, in->ub, sizeof( double )*(size_t)nax ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Circle objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Circle 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: */ AstCircle *this; /* Pointer to Circle */ /* Obtain a pointer to the Circle structure. */ this = (AstCircle *) obj; /* Annul all resources. */ this->centre = astFree( this->centre ); this->lb = astFree( this->lb ); this->ub = astFree( this->ub ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Circle 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 Circle class to an output Channel. * Parameters: * this * Pointer to the Circle 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 Variables: */ AstCircle *this; /* Pointer to the Circle structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Circle structure. */ this = (AstCircle *) this_object; /* Write out values representing the instance variables for the Circle 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsACircle and astCheckCircle functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Circle,Region) astMAKE_CHECK(Circle) AstCircle *astCircle_( void *frame_void, int form, const double centre[], const double point[], AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astCircle f AST_CIRCLE * Purpose: * Create a Circle. * Type: * Public function. * Synopsis: c #include "circle.h" c AstCircle *astCircle( AstFrame *frame, int form, const double centre[], c const double point[], AstRegion *unc, c const char *options, ... ) f RESULT = AST_CIRCLE( FRAME, FORM, CENTRE, POINT, UNC, OPTIONS, STATUS ) * Class Membership: * Circle constructor. * Description: * This function creates a new Circle and optionally initialises its * attributes. * * A Circle is a Region which represents a circle or sphere within the * supplied Frame. * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. c form f FORM = INTEGER (Given) * Indicates how the circle is described by the remaining parameters. * A value of zero indicates that the circle is specified by a * centre position and a position on the circumference. A value of one * indicates that the circle is specified by a centre position and a * scalar radius. c centre f CENTRE( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates at the centre of * the circle or sphere. c point f POINT( * ) = DOUBLE PRECISION (Given) c If "form" f If FORM * is zero, then this array should have one element for each Frame * axis (Naxes attribute), and should be supplied holding the * coordinates at a point on the circumference of the circle or sphere. c If "form" f If FORM * is one, then this array should have one element only which should * be supplied holding the scalar radius of the circle or sphere, * as a geodesic distance within the Frame. c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with the boundary of the Circle being created. * The uncertainty in any point on the boundary of the Circle is found by * shifting the supplied "uncertainty" Region so that it is centred at * the boundary point being considered. The area covered by the * shifted uncertainty Region then represents the uncertainty in the * boundary position. The uncertainty is assumed to be the same for * all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Circle. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the Circle being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 Circle. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Circle. The syntax used is identical to that for the f AST_SET routine. 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 astCircle() f AST_CIRCLE = INTEGER * A pointer to the new Circle. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstCircle *new; /* Pointer to new Circle */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the Circle, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitCircle( NULL, sizeof( AstCircle ), !class_init, &class_vtab, "Circle", frame, form, centre, point, unc ); /* 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 Circle'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 Circle. */ return new; } AstCircle *astCircleId_( void *frame_void, int form, const double centre[], const double point[], void *unc_void, const char *options, ... ) { /* * Name: * astCircleId_ * Purpose: * Create a Circle. * Type: * Private function. * Synopsis: * #include "circle.h" * AstCircle *astCircleId_( AstFrame *frame, int form, const double centre[], * const double point[], AstRegion *unc, * const char *options, ... ) * Class Membership: * Circle constructor. * Description: * This function implements the external (public) interface to the * astCircle constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astCircle_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astCircle_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astCircle_. * Returned Value: * The ID value associated with the new Circle. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstCircle *new; /* Pointer to new Circle */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* 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 NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the Circle, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitCircle( NULL, sizeof( AstCircle ), !class_init, &class_vtab, "Circle", frame, form, centre, point, unc ); /* 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 Circle'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 Circle. */ return astMakeId( new ); } AstCircle *astInitCircle_( void *mem, size_t size, int init, AstCircleVtab *vtab, const char *name, AstFrame *frame, int form, const double centre[], const double point[], AstRegion *unc, int *status ) { /* *+ * Name: * astInitCircle * Purpose: * Initialise a Circle. * Type: * Protected function. * Synopsis: * #include "circle.h" * AstCircle *astInitCircle_( void *mem, size_t size, int init, AstCircleVtab *vtab, * const char *name, AstFrame *frame, int form, * const double centre[], const double point[], * AstRegion *unc ) * Class Membership: * Circle initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Circle object. It allocates memory (if necessary) to accommodate * the Circle plus any additional data associated with the derived class. * It then initialises a Circle 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 Circle at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Circle is to be initialised. * This must be of sufficient size to accommodate the Circle data * (sizeof(Circle)) 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 Circle (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 Circle * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Circle'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 Circle. * 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 * A pointer to the Frame in which the region is defined. * form * Indicates how the "point" parameter should be interpreted. * Should be either 0 or 1. * centre * An array of double, with one element for each Frame axis (Naxes * attribute) containing the coordinates of the circle centre. * point * If "form" is zero, this should be an array of double, with one * element for each Frame axis (Naxes attribute) containing the * coordinates at any point on the circumference. If "form" is one, * this should be the address of a double containing the scalar * radius of the circle or sphere. * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points on the boundary of the new Circle * being initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal to * 1.0E-6 of the dimensions of the new Circle's bounding box are used. * If an uncertainty Region is supplied, it must be either a Box, a * Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new Circle. * 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: */ AstCircle *new; /* Pointer to new Circle */ AstPointSet *pset; /* PointSet to pass to Region initialiser */ const double *circum; /* Pointer to circumference position */ double **ptr; /* Pointer to coords data in pset */ int i; /* Axis index */ int nc; /* No. of axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitCircleVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the supplied value for "form" is legal. */ if( form != 0 && form != 1 && astOK ) { astError( AST__BADIN, "astInitCircle(%s): The value supplied for " "parameter \"form\" (%d) is illegal - it should be 0 or 1 " "(programming error).", status, name, form ); } /* Get the number of axis values required for each position. */ nc = astGetNaxes( frame ); /* If the circle radius has been supplied, find a point on the circle circumference. */ if( form == 1 ) { circum = CircumPoint( frame, nc, centre, *point, status ); /* Otherwise, use the supplied circumference point. */ } else { circum = point; } /* Create a PointSet to hold the centre position, and a point on the circumference, and get points to the data arrays. */ pset = astPointSet( 2, nc, "", status ); ptr = astGetPoints( pset ); /* Copy the centre and circumference coordinates into the PointSet, checking that no bad values have been supplied. */ for( i = 0; astOK && i < nc; i++ ) { if( centre[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitCircle(%s): The value of axis %d is " "undefined at the circle centre.", status, name, i + 1 ); } if( astOK && circum[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitCircle(%s): The value of axis %d is " "undefined on the circumference of the circle.", status, name, i + 1 ); } ptr[ i ][ 0 ] = centre[ i ]; ptr[ i ][ 1 ] = circum[ i ]; } /* Check pointers can be used safely. */ if( astOK ) { /* Initialise a Region structure (the parent class) as the first component within the Circle structure, allocating memory if necessary. */ new = (AstCircle *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, pset, unc ); if ( astOK ) { /* Initialise the Circle data. */ /* ------------------------ */ new->stale = 1; new->centre = NULL; new->lb = NULL; new->ub = NULL; Cache( new, status ); /* If an error occurred, clean up by deleting the new Circle. */ if ( !astOK ) new = astDelete( new ); } } /* Free resources. */ pset = astAnnul( pset ); if( form == 1 ) circum = astFree( (void *) circum ); /* Return a pointer to the new Circle. */ return new; } AstCircle *astLoadCircle_( void *mem, size_t size, AstCircleVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadCircle * Purpose: * Load a Circle. * Type: * Protected function. * Synopsis: * #include "circle.h" * AstCircle *astLoadCircle( void *mem, size_t size, AstCircleVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Circle loader. * Description: * This function is provided to load a new Circle 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 * Circle structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Circle at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Circle is to be * loaded. This must be of sufficient size to accommodate the * Circle data (sizeof(Circle)) 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 Circle (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 Circle 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(AstCircle) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Circle. If this is NULL, a pointer * to the (static) virtual function table for the Circle 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 "Circle" is used instead. * Returned Value: * A pointer to the new Circle. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstCircle *new; /* Pointer to the new Circle */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Circle. In this case the Circle belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstCircle ); vtab = &class_vtab; name = "Circle"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitCircleVtab( 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 Circle. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Circle" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* Cache intermediate results in the Circle structure */ new->centre = NULL; new->lb = NULL; new->ub = NULL; new->stale = 1; Cache( new, status ); /* If an error occurred, clean up by deleting the new Circle. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Circle pointer. */ return new; } /* 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 astCirclePars_( AstCircle *this, double *centre, double *radius, double *p1, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Circle,CirclePars))( this, centre, radius, p1, status ); } ast-8.3.0/plot.c0000664000175000017500000432141113004147321010357 00000000000000/* *class++ * Name: * Plot * Purpose: * Provide facilities for 2D graphical output. * Constructor Function: c astPlot f AST_PLOT * Description: * This class provides facilities for producing 2D graphical output. * A Plot is a specialised form of FrameSet, in which the base * Frame describes a "graphical" coordinate system and is * associated with a rectangular plotting area in the underlying * graphics system. This plotting area is where graphical output * appears. It is defined when the Plot is created. * * The current Frame of a Plot describes a "physical" coordinate * system, which is the coordinate system in which plotting * operations are specified. The results of each plotting operation * are automatically transformed into graphical coordinates so as * to appear in the plotting area (subject to any clipping which * may be in effect). * * Because the Mapping between physical and graphical coordinates * may often be non-linear, or even discontinuous, most plotting * does not result in simple straight lines. The basic plotting * element is therefore not a straight line, but a geodesic curve c (see astCurve, astGenCurve and astPolyCurve). A Plot also provides facilities for c drawing markers or symbols (astMark), text (astText) and grid lines c (astGridLine). It is also possible to draw curvilinear axes with c optional coordinate grids (astGrid). f (see AST_CURVE, AST_GENCURVE and AST_POLYCURVE). A Plot also provides facilities f for drawing markers or symbols (AST_MARK), text (AST_TEXT) and grid f lines (AST_GRIDLINE). It is also possible to draw curvilinear axes f with optional coordinate grids (AST_GRID). * A range of Plot attributes is available to allow precise control * over the appearance of graphical output produced by these c functions. f routines. * * You may select different physical coordinate systems in which to * plot (including the native graphical coordinate system itself) * by selecting different Frames as the current Frame of a Plot, * using its Current attribute. You may also set up clipping (see c astClip) to limit the extent of any plotting you perform, and f AST_CLIP) to limit the extent of any plotting you perform, and * this may be done in any of the coordinate systems associated * with the Plot, not necessarily the one you are plotting in. * * Like any FrameSet, a Plot may also be used as a Frame. In this * case, it behaves like its current Frame, which describes the * physical coordinate system. * * When used as a Mapping, a Plot describes the inter-relation * between graphical coordinates (its base Frame) and physical * coordinates (its current Frame). It differs from a normal * FrameSet, however, in that an attempt to transform points which * lie in clipped areas of the Plot will result in bad coordinate * values (AST__BAD). * Inheritance: * The Plot class inherits from the FrameSet class. * Attributes: * In addition to those attributes common to all FrameSets, every * Plot also has the following attributes: * * - Abbrev: Abbreviate leading fields? * - Border: Draw a border around valid regions of a Plot? * - Clip: Clip lines and/or markers at the Plot boundary? * - ClipOp: Combine Plot clipping limits using a boolean OR? * - Colour(element): Colour index for a Plot element * - DrawAxes(axis): Draw axes for a Plot? * - DrawTitle: Draw a title for a Plot? * - Escape: Allow changes of character attributes within strings? * - Edge(axis): Which edges to label in a Plot * - Font(element): Character font for a Plot element * - Gap(axis): Interval between linearly spaced major axis values * - Grf: Select the graphics interface to use. * - Grid: Draw grid lines for a Plot? * - Invisible: Draw graphics in invisible ink? * - LabelAt(axis): Where to place numerical labels for a Plot * - LabelUnits(axis): Use axis unit descriptions in a Plot? * - LabelUp(axis): Draw numerical Plot labels upright? * - Labelling: Label and tick placement option for a Plot * - LogGap(axis): Interval between logarithmically spaced major axis values * - LogPlot(axis): Map the plot onto the screen logarithmically? * - LogTicks(axis): Space the major tick marks logarithmically? * - MajTickLen(axis): Length of major tick marks for a Plot * - MinTickLen(axis): Length of minor tick marks for a Plot * - MinTick(axis): Density of minor tick marks for a Plot * - NumLab(axis): Draw numerical axis labels for a Plot? * - NumLabGap(axis): Spacing of numerical axis labels for a Plot * - Size(element): Character size for a Plot element * - Style(element): Line style for a Plot element * - TextLab(axis): Draw descriptive axis labels for a Plot? * - TextLabGap(axis): Spacing of descriptive axis labels for a Plot * - TickAll: Draw tick marks on all edges of a Plot? * - TitleGap: Vertical spacing for a Plot title * - Tol: Plotting tolerance * - Width(element): Line width for a Plot element * Functions: c In addition to those functions applicable to all FrameSets, the c following functions may also be applied to all Plots: f In addition to those routines applicable to all FrameSets, the f following routines may also be applied to all Plots: * c - astBBuf: Begin a new graphical buffering context c - astBorder: Draw a border around valid regions of a Plot c - astBoundingBox: Returns a bounding box for previously drawn graphics c - astClip: Set up or remove clipping for a Plot c - astCurve: Draw a geodesic curve c - astEBuf: End the current graphical buffering context c - astGenCurve: Draw a generalized curve c - astGetGrfContext: Get the graphics context for a Plot c - astGrfPop: Retrieve previously saved graphics functions c - astGrfPush: Save the current graphics functions c - astGrfSet: Register a graphics routine for use by a Plot c - astGrid: Draw a set of labelled coordinate axes c - astGridLine: Draw a grid line (or axis) for a Plot c - astMark: Draw a set of markers for a Plot c - astPolyCurve: Draw a series of connected geodesic curves c - astRegionOutline: Draw the outline of an AST Region c - astText: Draw a text string for a Plot f - AST_BBUF: Begin a new graphical buffering context f - AST_BORDER: Draw a border around valid regions of a Plot f - AST_BOUNDINGBOX: Returns a bounding box for previously drawn graphics f - AST_CLIP: Set up or remove clipping for a Plot f - AST_CURVE: Draw a geodesic curve f - AST_EBUF: End the current graphical buffering context f - AST_GENCURVE: Draw a generalized curve f - AST_GETGRFCONTEXT: Get the graphics context for a Plot f - AST_GRFPOP: Retrieve previously saved graphics functions f - AST_GRFPUSH: Save the current graphics functions f - AST_GRFSET: Register a graphics routine for use by the Plot class f - AST_GRID: Draw a set of labelled coordinate axes f - AST_GRIDLINE: Draw a grid line (or axis) for a Plot f - AST_MARK: Draw a set of markers for a Plot f - AST_POLYCURVE: Draw a series of connected geodesic curves f - AST_REGIONOUTLINE: Draw the outline of an AST Region f - AST_TEXT: Draw a text string for a Plot * Graphical Elements: * The colour index, character font, character size, line style and * line width used for plotting can be set independently for * various elements of the graphical output produced by a Plot. * The different graphical elements are identified by appending the * strings listed below as subscripts to the Plot attributes * Colour(element), Font(element), Size(element), Style(element) * and Width(element). These strings are case-insensitive and * unambiguous abbreviations may be used. Elements of the graphical * output which relate to individual axes can be referred to either * independently (e.g. "(Grid1)" and "(Grid2)" ) or together (e.g. * "(Grid)"): * c - Axes: Axis lines drawn through tick marks using astGrid f - Axes: Axis lines drawn through tick marks using AST_GRID c - Axis1: Axis line drawn through tick marks on axis 1 using astGrid f - Axis1: Axis line drawn through tick marks on axis 1 using AST_GRID c - Axis2: Axis line drawn through tick marks on axis 2 using astGrid f - Axis2: Axis line drawn through tick marks on axis 2 using AST_GRID c - Border: The Plot border drawn using astBorder, astGrid or astRegionOutline f - Border: The Plot border drawn using AST_BORDER, AST_GRID or AST_REGIONOUTLINE c - Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve f - Curves: Geodesic curves drawn using AST_CURVE, AST_GENCURVE or AST_POLYCURVE c - Grid: Grid lines drawn using astGridLine or astGrid f - Grid: Grid lines drawn using AST_GRIDLINE or AST_GRID c - Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid f - Grid1: Grid lines which cross axis 1, drawn using AST_GRIDLINE or AST_GRID c - Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid f - Grid2: Grid lines which cross axis 2, drawn using AST_GRIDLINE or AST_GRID c - Markers: Graphical markers (symbols) drawn using astMark f - Markers: Graphical markers (symbols) drawn using AST_MARK c - NumLab: Numerical axis labels drawn using astGrid f - NumLab: Numerical axis labels drawn using AST_GRID c - NumLab1: Numerical labels for axis 1 drawn using astGrid f - NumLab1: Numerical labels for axis 1 drawn using AST_GRID c - NumLab2: Numerical labels for axis 2 drawn using astGrid f - NumLab2: Numerical labels for axis 2 drawn using AST_GRID c - Strings: Text strings drawn using astText f - Strings: Text strings drawn using AST_TEXT c - TextLab: Descriptive axis labels drawn using astGrid f - TextLab: Descriptive axis labels drawn using AST_GRID c - TextLab1: Descriptive label for axis 1 drawn using astGrid f - TextLab1: Descriptive label for axis 1 drawn using AST_GRID c - TextLab2: Descriptive label for axis 2 drawn using astGrid f - TextLab2: Descriptive label for axis 2 drawn using AST_GRID c - Ticks: Tick marks (both major and minor) drawn using astGrid f - Ticks: Tick marks (both major and minor) drawn using AST_GRID c - Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid f - Ticks1: Tick marks (both major and minor) for axis 1 drawn using AST_GRID c - Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid f - Ticks2: Tick marks (both major and minor) for axis 2 drawn using AST_GRID c - Title: The Plot title drawn using astGrid f - Title: The Plot title drawn using AST_GRID * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (Starlink) * RFWS: R.F. Warren-Smith (Starlink) * History: * 18-SEP-1996 (DSB): * Original version. * 25-FEB-1997 (RFWS): * Tidied all public prologues. * 18-AUG-1997 (DSB): * Changes made to ensure that the first label on each axis is * never abbreviated, and to avoid segmentation violation when NumLab * is set to zero. * 1-SEP-1997 (DSB): * astGetGap changed so that it returns the default value which will * be used (instead of AST__BAD) if no value has been set for Gap. * The Border attribute modified so that it is off (zero) by default. * 19-SEP-1997 (DSB): * o Check that something has been plotted before using the bounding * box to determine title and label positions. * o Fixed bug which caused a tick mark at the pole to be draw at * a random angle. * o The size of the increment used to determine the tangent to a grid * line at the position to a label has been reduced to make sure the * labls are drawn parallel to grid line. * o Correct the logic for catering with reversed axes when determining * the displacement of a label's reference point from the associated * axis. * o Corrected logic which determined if two numerical labels overlap. * o Corrected logic for determining when to abbreviate numerical * labels. * o Use of strtok replaced by local function FindWord. * o Correct logic which determines which side of the axis to draw * tick marks when using interior labelling. * o If the base Frame of the FrameSet supplied to astPlot has more * than 2 axes, then use a sub-frame formed from the first two axes, * instead of simply reporting an error. * o If the current Frame of the Plot supplied to astGrid or * astBorder has more than 2 axes, then use a sub-frame formed from * the first two axes, instead of simply reporting an error. * o Default for Border is now to draw the border if exterior * Labelling is used, but not to draw it if interior labelling is * used. * o Public astGet function now returns actual used values for all * attributes. Protected astGetXyz functions still return the requested * value (which may differ from the used value), or the "unset" value * if no value has been set for the attribute. * o The defaults for Edge now depend on Labelling. If exterior * labelling was requested but cannot be produced using defaults of * Edge(1)=Bottom and Edge(2)=Left, then these default Edge values * are swapped. If exterior labelling is still not possible, the * original default Edge values are re-instated. * o Unset attributes which use dynamic defaults are now flagged as * "unhelpful" in the dump function. * o Added attribute Escape which allows text strings to include * escape sequences (see function GrText). This attribute and * associated functionality is currently not available for use, search * for all occurences of ENABLE-ESCAPE for instructions on how to * enable the facilities. * o Strings now used instead of integers to represent "choice" * attributes externally (eg Edge and Labelling). * 24-NOV-1997 (DSB): * o Fixed bug in function Grid which caused units to be included in * SkyFrame axis labels by default. * o Replaced calls to DrawText by calls to astGText, and replaced * references to "U" and "D" justifications by "T" and "B". This * stops labels drifting to the bottom left when GAIA zooms. * 23-MAR-1998 (DSB): * Added extra checks on global status into routine Grid to avoid * segmentation violations occuring due to null pointers being used. * 10-JUN-1998 (DSB): * Modify DrawTicks so that ticks are drawn closer to singularities * than previously. Also normalise this constraint to the screen size * rather than the length of a major tick mark. * 28-OCT-1998 (DSB): * o Added method astPolyCurve. * o Extract the Current Frame from the Plot prior to using Frame * methods such as astOffset, astNorm, etc. * o PlotLabel modified to ensure labels are abbreviated even if * they are next to the "root" label (i.e. the label with most * trailing zeros). * o Modified description of Width attribute. Width no longer gives * the absolute line width in inches. Instead it is a scale factor, * where 1.0 corresponds to a "typical thin line" on the device. * o Modified LabelUnits attribute so that the default value is zero * for SkyAxes and non-zero for other Axes. * 10-DEC-1998 (DSB): * Modified all calls to the "pow" maths function to avoid using * literal constants as arguments. This seems to cause segmentation * violations on some systems. * 16-JUL-1999 (DSB): * Fixed memory leaks in EdgeCrossings and EdgeLabels. * 16-SEP-1999 (DSB): * Avoid writing out clipping limits if they are undefined. * 12-OCT-1999 (DSB): * o Modified use of the NumLab attribute so that setting it to zero * does not prevent exterior labels from being produced. * o Allow length of tick marks to be specified separately for * both axes. * 13-OCT-2000 (DSB): * o Purge zero length sections from CurveData structures. * o Increase tolerance for edge labels from 0.0005 to 0.005. * 9-JAN-2001 (DSB): * o Change argument "in" for astMark and astPolyCurve from type * "const double (*)[]" to "const double *". * o Check success of astReadString before using the returned * pointer. * o Change method for choosing default LabelAt values to ignore * values which produce no visible labels. * 10-JAN-2001 (DSB): * o Modified FindMajTick to choose the size of fillable holes in * the axis range on the basis of the number of ticks on the axis. * This avoids holes being visible in the displayed tick marks when * using very small gaps. * 22-MAY-2001 (DSB): * Added a check when using interior labelling, to ensure that the * most appropriate edges are used for text labels. * 13-JUN-2001 (DSB): * Added public method astGenCurve, astGrfSet, astGrfPop, astGrfPush. * Made DrawAxes attribute axis specific. * 4-JUL-2001 (DSB): * The Crv function used to have a restriction that if *any* * subsection was very short, then *none* of the subsections were * subdivided. This meant that long subsections which needed * subdividing were not subdivided if there was also a very short * subsection. To get round this problem the restriction was changed * to "if *all* subsections are very short then none are divided. * This was implemented by changing dl2_min to dl2_max, and adding * a check for very short segments (which are then not sub-divided). * 16-AUG-2001 (DSB): * Remove the check for very short segments introduced above, as it * caused south pole tan projection to include some spurious lines. * 20-SEP-2001 (DSB): * - Initialize baseframe to NULL in astInitPlot (prevents segvios). * - Modified astInitPlot to allow the "frame" argument to the astPlot * constructor to be a Plot. * 10-JAN-2002 (DSB): * - Added axis-specific graphical elements "axis1", "axis2", etc. * - FullForm returns a match without ambiguity if the test string * matches an option exactly, including length. * 31-JAN-2002 (DSB): * - Added RejectOOB to reject tick marks which are not in their primary * domain. * 14-FEB-2002 (DSB): * - Relaxed the conditions for equality within the EQUALS macro. * Guard aginst no ticks being found. * 18-FEB-2002 (DSB): * - Make a permanent copy of any old axis format string in TickMarks. * Previously a mere pointer into the astGet string buffer was stored, * which could be over-written after many calls to astGet. * - If a user specifies an axis format, use it whether or not it * results in any identical adjacent labels. * 4-MAR-2002 (DSB): * - Made fairly extesive changes to the creation and use of tick * mark values in order to circumvent problems with CAR projections, * and "1 to many" mappings (such as 2D cartesian->polar). The * policy now is that axis normalization is only performed when * necessary (i.e. to create labels for display, etc). Tick mark * values are stored and handled as non-normalized values as much as * possible. * 13-JUN-2002 (DSB): * Modified Norm1 to prevent major tick value from being removed if * the supplied reference value is out of bounds, resulting in the * Mapping producing bad values * 14-JUN-2002 (DSB): * Re-wrote PlotLabels to improve abbreviation of labels and the * choice of which labels not to print. * 14-AUG-2002 (DSB): * - Added method astBoundingBox. * - Added attribute Invisible. * - Correct handling of "axis specific" plot elements cuch as * (Axis1), (Axis2), etc. * 12-SEP-2002 (DSB): * - Modified Map1 to remove slow normalization method (it is now * faster but the changes result in some longer-than-needed grids * lines when (e.g.) plotting pixel coordins in Polar coords). * - Modified Axlot so that SkyFrames positions which are out of * their normal ranges are not rejected by Map1. * 10-OCT-2002 (DSB): * grfAttrs:Modified to test element attributes explicitly using the * relevant TestUse functions, instead of relying on the * "GetUse" function returning the NO constant if not set. * - Modified Axplot so that SkyFrames positions which are out of * their normal ranges are not rejected by Map1. * - Only use tick marks which are within the axis range given by the * Bottom and Top Axis attributes. * - Norm1: If the normalized current frame coords are bad, do not * reinstate the original unnormalized values. For instance, current * Frame values which are outside the valid domain of the projection * should result in bad values when normalized, not the original * good values. The original comment stated "If the normalization * produced bad coords (e.g. as may happen if the supplied refernce * value corresponds to a point on the line through the tick mark * which is outside the valid region of the mapping) leave the original * tick mark values unchanged". * - GetTicks: Limit maxticks to be no less than 8. * 8-JAN-2003 (DSB): * - Changed private InitVtab method to protected astInitPlotVtab * method. * - Use private IsASkyFrame method in place of astIsASkyFrame. * - Modify PlotLabels to excluding exponents when counting trailing * zeros, and also to pad trailing fields with trailing zeros up to * the max number of decimal places when estimating label priorities. * - Modified Overlap to ensure that axis labels are speced by at * least two spaces. * 22-JAN-2003 (DSB): * - Modified PlotLabels so that labels are rejected in a regular * pattern rather than semi-random. * - Modified the way PlotLabels abbreviates leading fields. * - Introdued the skipbad parameter for the Crv function, in order * to provide some degree of protection against the Crv algorithm * skipping over small sections of valid coordinates (such as when * a curve crosses the plot very close to a corner of the plot). * 25-MAR-2003 (DSB): * - Modified FindMajTicks to avoid losing tick marks when dealing * with high precision data. * 8-AUG-2003 (DSB): * - Modified PlotLabels to ensure that the root label for the * second axis is not omitted due to it overlapping a label from * the first axis (a different root label is now chosen if this would * be the case). * - Modify FindMajTicks to avoid tick marks which should be at * exactly zero being placed at some very small non-zero axis value. * 22-OCT-2003 (DSB): * - DrawTicks modified to correctly reset graphical attributes and * pass on to the next axis if an axis has zero length major and minor * tick marks. * 9-JAN-2004 (DSB): * DrawGrid: Report error if no grid curves can be drawn. * AxPlot: Initialise returned CDATA structure before checking argument * validity. * GetTicks: Calculate the reference value on the other axis using * function "Typical" rather than simply using the man of the supplied * values (the supplied values may be clustered around 0 and 2*PI if the * field is centred on the origin, resulting in the mean being at about * 1.PI and therefore inappropriate). * 13-JAN-2004 (DSB): * - Added LogPlot attribute, and the facility for mapping the base * coordinate system logarithmically onto the plotting area instead of * linearly. * - Added LogTicks attribute, and the facility for spacing the * major tick marks logarithmically instead of linearly. * - Added LogGap attribute, and the facility for storing separate * gap sizes for linear and log tick spacing. * 15-JAN-2004 (DSB): * - Added LogLabel attribute. * - Re-instated the inclusion of escape sequences in strings (see * function GrText). * 12-FEB-2004 (DSB): * - RightVector: Corrected usage of chh and chv. * - GQch and GScales: Check that values returned by grf module are * usable. * - DrawAxis: Extend axis section by one section (if possible) at * each end (overcomes problems where the axis does not reach a pole). * - DrawAxis: Check axis does not extend beyond a pole. * - Labels: Correct logic of loop which plots interior labels * (previously it missed out labels if there were only 3) * - Allow for some rounding error in FindMajTicks when comparing an * axis value with a loweror upper axis limit. * 19-FEB-2004 (DSB): * - Reduced the dynamic range restriction for log ticks from 2 decades * to 1. * - Temporarily clear any error status before re-instating the * original Format in TickMarks. * - Add LogTicks to the GetAttrib function so that the value of the * LogTicks attribute can be got by the public. * - Modify Crv to include a check that he vector scale has not * changed much between adjacent segments. * - Modify Crv so that a segment is only subdivided if at least * half of the subsegments are longer than the shortest significant * length. Also put a restriction on subdivision so that * subdivision only occurs if the bounding box of the segment being * sub-divided is smaller than the bounding box of its parent * segment. * 27-FEB-2004 (DSB): * - Reduce the default Tol value from 0.001 to 0.01 in order to * speed up curve drawing.. * - Use 0.1*Tol in Boundary because the boundary tracing algorithm * seems to produce much worse visible errors than it should do for a * given Tol. * 2-MAR-2004 (DSB): * - Corrected handling of bounding boxes in Crv so that * subdivision is allowed if the bounding box shrinks on only 1 axis * (previously required shrinkage on both axes but this fails if * all the points are on a horizontal or vertical line). * - Modified FindMajTicks to use a better algorithm for finding an * appropriate nfill value (previously logplot=1 axes could have * unfilled holes at the high end). * - Modified GetTicks so that FindMajTicks is not called * repeatedly with the same gap size. * - Modify AxPlot/Map1 so that the axis curve is sampled logarithmically * if the corresponding axis is mapped logarithmically. * 10-MAR-2004 (DSB): * - Modified Typical to give less weight to vaalues close to the * edges of the range covered by the plotting area. * - Increased minimum angle between curve and edge required to * create an edge label from 3 degs to 5 degs. * - Modified PlotLabels to ignore duplicate adjacent labels which * determining overlap of labels. * 17-MAR-2004 (DSB): * - Modified Typical to give normal weight to edge bins in * histogram if these bins contain all the counts. * - Modified DrawTicks to add extra minor ticks below first major * tick value and above last major tick value. * - Norm1 can reject usable tick mark values because of an * inappropriate value being used on the other axis (i.e. one for * which the position is undefined in grapics coords). Therfoer * Norm1 has been modified to use 3 different reference values * in an attempt to find one which gives good axis values. * 25-AUG-2004 (DSB): * - Correct handling of "fmt" pointer in TickMarks function (identified * and reported by Bill Joye). * 14-SEP-2004 (DSB): * - In EdgeLabels change definition of "distinct labels". Used to * be that labels were distinct if they had different formatted * labels. Now they are distinct if they have different floating * point numerical values. Fixes a bug reported by Micah Johnson. * - TickMarks re-structured to optimise the precision (no. of digits) * even if a value has been assigned for the Format attribute, but only * if the format specifier includes a wildcard precision specifier. For * instance, to get graphical separators a format must be specified * which included the "g" flag. As things were, this would prevent * the optimisation of the digits value. Can now use "dms.*g" to * allow the number of digits to be optimised. * 29-SEP-2004 (DSB): * - In FindMajTicks, begin the process of increasing "nfill" from * a value of zero rather than one (in many cases no filling is * needed). * - In GetTicks (linear tick marks section) ensure that 10 * *different* gap sizes are used before giving up. Previously, the * 10 tests could include duplicated gap values. * 8-NOV-2004 (DSB): * - In Norm1, try more alternative "other axis" values before * accepting that a tick mark value cannot be normalised. * 2-FEB-2005 (DSB): * - Avoid using astStore to allocate more storage than is supplied * in the "data" pointer. This can cause access violations since * astStore will then read beyond the end of the "data" area. * 15-MAR-2005 (DSB): * - Modified GridLines to use appropriate algorithm for choosing * start of grid lines in cases where one axis has logarithmic tick * spacing and the other has linear tick spacing. * 21-MAR-2005 (DSB): * - Added the Clip attribute. * 12-JUL-2005 (DSB): * - Modified AxPlot so that Map1 only normalises if neither axis * is a SkyAxis. Previously it normalised if either axis was not a * SkyAxis. * 7-DEC-2005 (DSB): * Free memory allocated by calls to astReadString. * 18-JAN-2006 (DSB) * Add Abbrev attribute. * 14-FEB-2006 (DSB) * Correct EdgeLabels to use gap size rather than EQUAL macro when * comparing label values. * 17-FEB-2006 (DSB) * Added escape sequences "%h+" and "%g+". * 21-MAR-2006 (DSB) * Added extra status checks in TickMarks. * 18-MAY-2006 (DSB) * Trans: use correct PointSet when tranforming to arbitrary * clipping frame. * 26-MAY-2006 (DSB) * Added LabelAt to TestAttrib. * 2-JUN-2006 (DSB) * - In MAKE_GET2, return the set value if a value has been set * without recalculating the defaults. * - Fix bug that could cause segvio in Grid if clipping is used. * 5-JUN-2006 (DSB) * Do not change the box returned by astBoundBox as a consequence * of calling astGetAttrib. * 19-JUN-2006 (DSB) * Changed the default line 0.0 from zero to 1.0. * 22-JUN-2006 (DSB) * Include axis textual labels and title in the bounding box * created by AST_GRID and returned by AST_BOUNDINGBOX. * 26-JUN-2006 (DSB) * Set the Direction attribute in the base Frame of a Plot if an * axis is reversed. * 29-JUN-2006 (DSB) * - Guard against astGap calls that reach a minimum gap size. * - Sort out splitting of long axis labels (such as date/time * strings produced by TimeFrames). * 30-JUN-2006 (DSB) * If abbreviating labels, display the last field for identical * neighbours rather than the whole value. * 10-JUL-2006 (DSB) * Make astStripEscapes public so it can be used by the NDF library. * 7-AUG-2006 (DSB) * Increase the number of attempts to find a new gap size from 5 to * 25 in GetTicks. * 24-OCT-2006 (DSB) * Add the ForceExterior attribute so that SPLAT can have external * axes even if there are no usable horizontal axis ticks (as requested * by PWD). Currently this attribute is not included in the public * documentation, as it may cause problems. If it seems to work OK * then it can be made public. * 25-JAN-2006 (DSB) * Do not draw ticks marks that start outside the bounds of the * axis they are labelling. * 27-FEB-2007 (DSB) * - Change nominal Crv_scerr value from 5.0 to 1.5 (this avoids gaps * in HPX grid plots being bridged by grid lines). * - Double the dimension of the grid used by GoodGrid to avoid * missing the pointy bits in a HPX projection. * 17-MAY-2007 (DSB) * Exclude corner positions when determining the range of axis * values covered by the plot. This gives better default gap sizes. * 11-JUN-2007 (DSB) * Plug memory leaks. * 20-JUN-2007 (DSB) * - Add attribute GrfContext. * - Pass the GrfContext attribute value to each external grf function. * External code that uses the astGrfSet function must be changed * so that the external grf functions registered using astGrfSet * accept this new parameter. * 21-JUN-2007 (DSB) * - Change GrfContext to be an Object rather than an integer. * 22-JUN-2007 (DSB) * - Do not dump the GrfContext Object since it may cause an * infinite dumping loop. * - Allow a NULL vtab to be supplied when initialising a Plot * structure. This causes the vtab defined locally within this * class to be used so that the new object behaves as a simple Plot. * 25-JUN-2007 (DSB) * - Free the graphics context object when then the Plot is deleted. * - Fix memory leak in FullForm. * - Since the grfcontext object is only used by external code, store * a public object identifier for it in the Plot structure rather * than a true C pointer. * 26-JUN-2007 (DSB) * Honour the LabelUp attribute value even if labels are drawn * around the edges of the plot. * 28-JUN-2007 (DSB) * - Make all axis attribute arrays 3 elements long rather than 2. * - Add the protected methods astCopyPlotDefaults and astMirror. * - Add public method astGetGrfContext, remove astSetGrfContext. * - Fix memory leak. * 6-SEP-2007 (DSB): * Dump and load any user-specified tick mark values. * 20-OCT-2009 (DSB): * - Modify SplitValue so that it only splits long values if * previous long values were split, or if the value contains a * space. * - Take account of zero height bounding boxes in UpdateConcat. * - Correct Dump so that it dumps attributes for all available * axes (2 for a Plot, 3 for a Plot3D). * 12-JAN-2010 (DSB): * Fix various memory leaks. * 4-MAR-2011 (DSB): * - Added grf functions BBuf and EBuf. * - Added public method astBBuf and astEBuf. * 23-AUG-2011 (DSB): * - If exterior labelling was requested but would produced too * few labels, only swap to interior labelling if doing so would * allow more labels to be drawn (i.e. do not swap to interior if * it does not gain us anything). * - Slightly decrease the dynamic range of an axis needed to produce * logarithmic ticks (this is to avoid problems with round errors). * 6-OCT-2011 (DSB): * - Prevent grf qch and scales functions being called lots of times * during each drawing operation (since the information returned by * these functions will not change during the course of a single drawing * operation). * 11-OCT-2011 (DSB): * - Combine multiple continuous polylines into a single polyline * before calling the grf polyline function. Reducing the number of * calls to the underlying graphics system can make a big difference * if the graphics system is written in an interpreted language * such as python. * - Take account of differing axis scales when rotating vectors by * 90 degrees. * 12-OCT-2011 (DSB): * - Fix the change made yesterday to correct rotation of numerical axis * rotations. I forgot that the astGText function in the grf module * expects the up vector in equally scaled coords, not graphics coords. * - Take account of unequal axis scales when working out the * length of each grid curve. * 15-OCT-2011 (DSB): * Always check that the grf module implements the scales function * before trying to invoke the scales function. * 21-MAY-2012 (DSB): * Correct text strings used to represent the "Labelling" attribute * within dumps of a Plot. Previously they were reversed. * 7-JUN-2012 (DSB): * Speed up plotting of CmpRegion boundaries by splitting the * CmpRegion up into a set of disjoint Regions, and plotting each * one separately. * 16-JUN-2014 (DSB): * - Prevent seg fault in PlotLabels caused by accessing * uninitialised "atext" field stored within purged labels. * - Choose a label with non-negative priority as the fall-back root label. * 17-APR-2015 (DSB): * Added method astRegionOutline. * 20-APR-2015 (DSB): * Draw Regions with higher accuracy, because Regions (i.e. Polygons) * can be very non-smooth. *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 Plot /* Values for constants used in this class. */ #define CRV_NSEG 14 /* No. of curve segments drawn by function Crv */ #define CRV_NPNT 15 /* CRV_NSEG plus one */ #define CRV_MXENT 10 /* Max. no. of recursive entries into function Crv */ #define MAJTICKS_OPT 10 /* Optimum number of major axiss or grid lines */ #define MAJTICKS_MAX 14 /* Max. number of major ticks or grid lines */ #define MAJTICKS_MIN 6 /* Min. number of major ticks or grid lines */ #define EDGETICKS_DIM 100 /* No. of edge samples used to find tick marks */ #define LEFT 0 /* Id for the left edge of the plotting area */ #define TOP 1 /* Id for the top edge of the plotting area */ #define RIGHT 2 /* Id for the right edge of the plotting area */ #define BOTTOM 3 /* Id for the bottom edge of the plotting area */ #define NOSTYLE -999 /* A value which represents a null Style value */ #define NOWIDTH -99.9 /* A value which represents a null Style value */ #define NOFONT -999 /* A value which represents a null Style value */ #define NOCOLOUR -999 /* A value which represents a null Style value */ #define NOSIZE -99.9 /* A value which represents a null Style value */ #if defined(THREAD_SAFE) #define GLOBALS_PROTO , AstGlobals * #define GLOBALS_ARG , AstGlobals *AST__GLOBALS #define GLOBALS_NAME , AST__GLOBALS #else #define GLOBALS_PROTO #define GLOBALS_ARG #define GLOBALS_NAME #endif /* * * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "plot.h" * MAKE_CLEAR(attr,component,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstPlot *this, int axis ) * * and an external interface function of the form: * * void astClear_( AstPlot *this, int axis ) * * which implement a method for clearing a single value in a specified * multi-valued attribute for an axis of a Plot. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. LabelAt in "astClearLabelAt"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR(attr,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstPlot *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astClear" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* Assign the "clear" value. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attr##_( AstPlot *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Plot,Clear##attr))( this, axis, status ); \ } /* * * Name: * MAKE_GET * Purpose: * Implement a method to get a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "plot.h" * MAKE_GET(attr,type,bad_value,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstPlot *this, int axis ) * * and an external interface function of the form: * * astGet_( AstPlot *this, int axis ) * * which implement a method for getting a single value from a specified * multi-valued attribute for an axis of a Plot. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. This can * use the string "axis" to represent the zero-based value index. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET(attr,type,bad_value,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attr( AstPlot *this, int axis, int *status ) { \ type result; /* Result to be returned */ \ \ /* Initialise */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astGet" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attr##_( AstPlot *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Plot,Get##attr))( this, axis, status ); \ } /* * * Name: * MAKE_SET * Purpose: * Implement a method to set a single value in a multi-valued attribute * for a Plot. * Type: * Private macro. * Synopsis: * #include "plot.h" * MAKE_SET(attr,type,component,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot *this, int axis, value ) * * and an external interface function of the form: * * void astSet_( AstPlot *this, int axis, value ) * * which implement a method for setting a single value in a specified * multi-valued attribute for a Plot. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. LabelAt in "astSetLabelAt"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET(attr,type,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstPlot *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astSet" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* Store the new value in the structure component. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attr##_( AstPlot *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Plot,Set##attr))( this, axis, value, status ); \ } /* * * Name: * MAKE_TEST * Purpose: * Implement a method to test if a single value has been set in a * multi-valued attribute for a class. * Type: * Private macro. * Synopsis: * #include "plot.h" * MAKE_TEST(attr,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( AstPlot *this, int axis ) * * and an external interface function of the form: * * int astTest_( AstPlot *this, int axis ) * * which implement a method for testing if a single value in a specified * multi-valued attribute has been set for a class. * Parameters: * attr * The name of the attribute to be tested, as it appears in the function * name (e.g. LabelAt in "astTestLabelAt"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. This can use the string "axis" to represent the zero-based * index of the value within the attribute. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_TEST(attr,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attr( AstPlot *this, int axis, int *status ) { \ int result; /* Value to return */ \ \ /* Initialise */ \ result = 0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astTest" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* Assign the result value. */ \ } else { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attr##_( AstPlot *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Plot,Test##attr))( this, axis, status ); \ } /* * * Name: * MAKE_GET3 * Purpose: * Implement a method to get a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * MAKE_GET3(attr,attr,type,bad_value,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstPlot *this, int axis ) * * which implements a method for getting a single value from a specified * multi-valued attribute for an axis of a Plot. Note, no public * interface function is created. * * The value returned is the value which would actually be used if * astGrid was called with the current set of Plot attributes. This * includes calculating any dynamic defaults which would be used, and is * consequently rather slow. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). The * string "Used" is added on to the front of the supplied value. * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. This can * use the string "axis" to represent the zero-based value index. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET3(attr,type,bad_value,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type GetUsed##attr( AstPlot *, int, int *status ); \ static type GetUsed##attr( AstPlot *this, int axis, int *status ) { \ type result; /* Result to be returned */ \ \ /* Initialise */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astGetUsed" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* If the attribute is set, use its normal accessor. */\ } else if( astTest##attr( this, axis ) ) {\ result = astGet##attr( this, axis );\ \ /* Otherwise, re-calculate dynamic defaults by going through the motions of \ drawing the grid. Nothing is actually drawn because we set the protected \ attribute Ink to zero first. The calculated values are stored in the \ Plot structure. */ \ } else { \ astSetInk( this, 0 ); \ astGrid( this ); \ astClearInk( this ); \ \ /* Assign the result value. */ \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } /* * * Name: * MAKE_SET3 * Purpose: * Implement a method to set a single value in a multi-valued attribute * for a Plot. This is identical to MAKE_SET except that no external * interface function is created. * Type: * Private macro. * Synopsis: * MAKE_SET3(attr,type,component,assign,nval) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstPlot *this, int axis, value ) * * which implements a method for setting a single value in a specified * multi-valued attribute for a Plot. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astSetLabel"). The * string "Used" is added on to the front of the supplied value. * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). If a value of 0 is supplied, the * value of the Plot's Nin attribute is used instead. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET3(attr,type,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void SetUsed##attr( AstPlot *, int, type, int *status ); \ static void SetUsed##attr( AstPlot *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index. */ \ if( axis < 0 || axis >= ( nval ? nval : astGetNin( this ) ) ){ \ astError( AST__AXIIN, "%s(%s): Index (%d) is invalid for attribute " \ #attr " - it should be in the range 1 to %d.", status, \ "astSetUsed" #attr, astGetClass( this ), \ axis + 1, ( nval ? nval : astGetNin( this ) ) ); \ \ /* Store the new value in the structure component. */ \ } else { \ this->component[ axis ] = (assign); \ } \ } /* *+ * Name: * MAKE_GET2 * Purpose: * Implement a method to get an attribute value for a class. * Type: * Protected macro. * Synopsis: * MAKE_GET2(class,attr,type,bad_value,assign) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static GetUsed( AstPlot *this ) * * which implement a method for getting a specified attribute value for a * class. Note, no public interface function is created. * * The value returned is the value which would actually be used if * astGrid was called with the current set of Plot attributes. This * includes calculating any dynamic defaults which would be used, and is * consequently rather slow. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). The * string "Used" is added on to the front of the supplied value. * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_GET2(class,attr,type,bad_value,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type GetUsed##attr( Ast##class *, int *status ); \ static type GetUsed##attr( Ast##class *this, int *status ) { \ type result; /* Result to be returned */ \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* If the attribute is set, use its normal accessor. */\ if( astTest##attr( this ) ) {\ result = astGet##attr( this );\ \ /* Otherwise, re-calculate dynamic defaults by going through the motions of \ drawing the grid. Nothing is actually drawn because we set the protected \ attribute Ink to zero first. The calculated values are stored in the \ Plot structure. */ \ } else { \ astSetInk( this, 0 ); \ astGrid( this ); \ astClearInk( this ); \ \ /* Assign the result value. */ \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } /* *+ * Name: * MAKE_SET2 * Purpose: * Implement a method to set an attribute value for a class. This * is identical to astMAKE_SET except that it does not create an * external interface function, and it does create a private function * prototype. * Type: * Protected macro. * Synopsis: * MAKE_SET2(class,attr,type,component,assign) * Class Membership: * Defined by the Plot class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void SetUsed( AstPlot *this, value ) * * which implements a method for setting a specified attribute value for a * class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attr * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). The string "Used" is added * to the front. * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET2(class,attr,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void SetUsed##attr( Ast##class *, type, int *status ); \ static void SetUsed##attr( Ast##class *this, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Store the new value in the structure component. */ \ this->component = (assign); \ } /* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" /* I/O channels */ #include "cmpmap.h" /* Compound mapping class */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "frame.h" /* Coordinate frame descriptions */ #include "frameset.h" /* Parent FrameSet class */ #include "grf.h" /* Low-level graphics interface */ #include "memory.h" /* Memory allocation facilities */ #include "object.h" /* Base Object class */ #include "plot.h" /* Interface definition for this class */ #include "pointset.h" /* Class holding lists of positions */ #include "keymap.h" /* Hash maps */ #include "skyaxis.h" /* Sky coordinate axes */ #include "skyframe.h" /* Sky coordinate frames */ #include "winmap.h" /* Scale and shift mappings */ #include "mathmap.h" /* Algebraic mappings */ #include "wcsmap.h" /* FITS-WCS projectsions */ #include "unitmap.h" /* Unit mappings */ #include "permmap.h" /* Axis permutations */ #include "region.h" /* Frame regions */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* Module Type Definitions */ /* ======================= */ typedef struct LabelList { double index; char *text; double x; double y; char *just; double upx; double upy; double val; int priority; const char *atext; int saved_prio; } LabelList; /* Structure to hold static data used internally within the Crv function. */ typedef struct CrvStatics { double *pdl2; /* Pointer to next squared segment length */ double *pdx; /* Pointer to next segment X increment */ double *pdy; /* Pointer to next segment Y increment */ double cosang; /* Cosine of angle between adjacent segments */ double d0; /* Distance to start of first sub-segment */ double delta; /* Distance between adjacent sub-segments */ double dl; /* Segment length in graphics coordinates */ double dll; /* Segment length for previous segment */ double last_x; /* Graphics X at the end of the previous segment */ double last_y; /* Graphics Y at the end of the previous segment */ double limit2; /* Shortest acceptable squared segment length */ double t1; /* Increment in X */ double t2; /* Increment in Y */ double t3; /* Squared segment length */ double vx; /* X component of unit vector for current segment */ double vxl; /* X component of unit vector for previous segment */ double vy; /* Y component of unit vector for current segment */ double vyl; /* Y component of unit vector for previous segment */ int *seg0; /* Pointer to current segment OK flag */ int *segm; /* Pointer to previous segment OK flag */ int *segp; /* Pointer to next segment OK flag */ int all_bad; /* Are all supplied positions bad or clipped? */ int el; /* Total sub-segment count */ int j; /* Sub-segment index */ int last_ok; /* Was the previous position defined? */ int nel; /* Total number of sub-segments */ int nlong; /* No.of segments longer than limit2 */ int nseg; /* Number of segments being sub-divided */ int nshort; /* No.of segments shorter than limit2 */ #ifdef CRV_TRACE int levels[100]; #endif } CrvStatics; /* Structure to hold static data used internally within the Crv function. */ typedef struct GetTicksStatics { AstFrame *frame; /* Pointer to the current Frame */ AstMapping *map; /* Pointer to Base->Current Mapping */ AstPointSet *pset; /* Pointer to a PointSet holding physical coords */ double **ptr; /* Pointer to physical coordinate values */ double defgaps[ 2 ]; /* Initial test gaps for each axis */ double typval[ 2 ]; /* Typical value on each axis */ double width[ 2 ]; /* Range of used axis values */ int maxticks; /* Max. number of ticks on each axis */ int mintick; /* Min. number of ticks on each axis */ int ngood[ 2 ]; /* No. of good physical values on each axis */ int bad; /* Were any bad pixels found? */ } GetTicksStatics; /* Structure to hold static data used internally within the EdgeCrossings function. */ typedef struct EdgeCrossingsStatics { AstFrame *frame; /* Pointer to current Frame in Plot */ AstPointSet *pset1; /* Graphics cooords at edge samples */ AstPointSet *pset2; /* Physical cooords at edge samples */ AstPointSet *pset4; /* Graphics cooords at offset edge samples */ double **ptr1; /* Pointer to graphics coord. data */ double **ptr2; /* Pointer to physical coord. data */ double **ptr4; /* Pointer to graphics coord. data */ double edgehi; /* High bound on varying graphics axis */ double edgelo; /* Low bound on varying graphics axis */ double edgeval; /* Constant graphics axis value along edge */ double limit; /* Three times the RMS step size */ int dim; /* Extended number of samples */ int edgeax; /* Graphics axis to which edgeval refers */ int paxis; /* Axis used in first invocation */ int pedge; /* Edge used in first invocation */ } EdgeCrossingsStatics; /* Structure to hold static data used internally within the Map1 function. */ typedef struct Map1Statics { AstPointSet *pset1; /* PointSet holding physical coords */ AstPointSet *pset2; /* PointSet holding graphics coords */ double **ptr1; /* Pointer to physical coord data */ double *pax; /* Pointer to start of axis data */ double *ptr2[ 2 ]; /* Pointers to graphics coord data */ double *work1; /* Pointer to work space */ double *work2; /* Pointer to work space */ double axorig; /* Distance offset */ double axscale; /* Distance scale */ int neg; /* Negate axis values? */ int nl; /* No. of points in pset1 and pset2 */ } Map1Statics; /* Structure to hold static data used internally within the Map2 function. */ typedef struct Map2Statics { AstPointSet *pset1; /* PointSet holding graphics coords */ AstPointSet *pset2; /* PointSet holding physical coords */ double **ptr2; /* Pointer to physical coord data */ double *ptr1[ 2 ]; /* Pointers to graphics coord data */ int nl; /* No. of points in pset1 and pset2 */ } Map2Statics; /* Structure to hold static data used internally within the Map3 function. */ typedef struct Map3Statics { AstPointSet *pset1; /* PointSet holding physical coords */ AstPointSet *pset2; /* PointSet holding graphics coords */ double **ptr1; /* Pointer to physical coord data */ double *ptr2[ 2 ]; /* Pointers to graphics coord data */ int nc; /* No. of physical axes */ int nl; /* No. of points in pset1 and pset2 */ double *pos; /* Pointer to memory for a single position */ } Map3Statics; /* Structure to hold static data used internally within the Map4 function. */ typedef struct Map4Statics { AstPointSet *pset1; /* PointSet holding distances */ AstPointSet *pset2; /* PointSet holding physical coords */ AstPointSet *pset3; /* PointSet holding graphics coords */ int nl; /* No. of points in pset1 and pset2 */ } Map4Statics; /* Structure to hold static data used internally within the Map5 function. */ typedef struct Map5Statics { AstPointSet *pset1; /* PointSet holding physical coords */ AstPointSet *pset2; /* PointSet holding graphics coords */ double **ptr1; /* Pointer to physical coord data */ double *ptr2[ 2 ]; /* Pointers to graphics coord data */ int nl; /* No. of points in pset1 and pset2 */ } Map5Statics; /* Structure to hold information about tick marks for a single axis. */ typedef struct TickInfo{ int nmajor; /* No. of major tick marks */ int nminor; /* No. of minor tick marks */ double *ticks; /* Pointer to array of major tick mark values */ double *minticks; /* Pointer to array of minor tick mark values */ char **labels; /* Pointer to array of major tick mark labels */ double *start; /* Start pos'n on other axis for each curve section */ double *length; /* Length on other axis of each curve section */ int nsect; /* No. of sections in curve */ char *fmt; /* Pointer to format string used to create labels */ double gap; /* The gap between major ticks */ } TickInfo; /* 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 void (* parent_removeframe)( AstFrameSet *, int, int * ); static AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* Strings giving the label for the graphics items corresponding to AST__BORDER_ID, AST__GRIDLINE_ID, etc. */ static char *GrfLabels = "Border Curves Title Markers Strings Axis1 Axis2 Axis3 " "NumLab1 NumLab2 NumLab3 TextLab1 TextLab2 TextLab3 " "Ticks1 Ticks2 Ticks3 Grid1 Grid2 Grid3 Axes NumLab " "TextLab Grid Ticks"; /* Text values used to represent edges externally. */ static const char *xedge[4] = { "left", "top", "right", "bottom" }; /* Text values used to represent Labelling externally. */ static const char *xlbling[2] = { "exterior", "interior" }; /* 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->GrfAttrs_nesting_t = 0; \ globals->Crv_nent_t = 0; \ globals->Box_lbnd_t[ 0 ] = FLT_MAX; \ globals->Box_ubnd_t[ 0 ] = FLT_MIN; \ globals->Boxp_lbnd_t[ 0 ] = FLT_MAX; \ globals->Boxp_ubnd_t[ 0 ] = FLT_MIN; \ globals->Box_lbnd_t[ 1 ] = FLT_MAX; \ globals->Box_ubnd_t[ 1 ] = FLT_MIN; \ globals->Boxp_lbnd_t[ 1 ] = FLT_MAX; \ globals->Boxp_ubnd_t[ 1 ] = FLT_MIN; \ globals->Boxp_freeze_t = 0; \ globals->Map1_plot_t = NULL; \ globals->Map1_map_t = NULL; \ globals->Map1_frame_t = NULL; \ globals->Map1_origin_t = NULL; \ globals->Map1_statics_t = NULL; \ globals->Map2_plot_t = NULL; \ globals->Map2_map_t = NULL; \ globals->Map2_statics_t = NULL; \ globals->Map3_plot_t = NULL; \ globals->Map3_map_t = NULL; \ globals->Map3_frame_t = NULL; \ globals->Map3_origin_t = NULL; \ globals->Map3_end_t = NULL; \ globals->Map3_statics_t = NULL; \ globals->Map4_plot_t = NULL; \ globals->Map4_map_t = NULL; \ globals->Map4_umap_t = NULL; \ globals->Map4_statics_t = NULL; \ globals->Map5_plot_t = NULL; \ globals->Map5_region_t = NULL; \ globals->Map5_map_t = NULL; \ globals->Map5_statics_t = NULL; \ globals->Poly_n_t = 0; \ globals->Poly_x_t = NULL; \ globals->Poly_y_t = NULL; \ globals->Poly_npoly_t = 0; \ globals->Poly_np_t = NULL; \ globals->Poly_xp_t = NULL; \ globals->Poly_yp_t = NULL; \ globals->Curve_data_t.nbrk = -1; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->SplitValue_Buff[ 0 ] = 0; \ globals->StripEscapes_Buff[ 0 ] = 0; \ globals->Grf_chv_t = AST__BAD; \ globals->Grf_chh_t = AST__BAD; \ globals->Grf_alpha_t = 0.0; \ globals->Grf_beta_t = 0.0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Plot) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Plot,Class_Init) #define class_vtab astGLOBAL(Plot,Class_Vtab) #define grfattrs_nesting astGLOBAL(Plot,GrfAttrs_nesting_t) #define grfattrs_attrs astGLOBAL(Plot,GrfAttrs_attrs_t) #define Crv_limit astGLOBAL(Plot,Crv_limit_t) #define Crv_scerr astGLOBAL(Plot,Crv_scerr_t) #define Crv_tol astGLOBAL(Plot,Crv_tol_t) #define Crv_ux0 astGLOBAL(Plot,Crv_ux0_t) #define Crv_uy0 astGLOBAL(Plot,Crv_uy0_t) #define Crv_vxl astGLOBAL(Plot,Crv_vxl_t) #define Crv_vyl astGLOBAL(Plot,Crv_vyl_t) #define Crv_xhi astGLOBAL(Plot,Crv_xhi_t) #define Crv_xl astGLOBAL(Plot,Crv_xl_t) #define Crv_xlo astGLOBAL(Plot,Crv_xlo_t) #define Crv_yhi astGLOBAL(Plot,Crv_yhi_t) #define Crv_yl astGLOBAL(Plot,Crv_yl_t) #define Crv_ylo astGLOBAL(Plot,Crv_ylo_t) #define Crv_vxbrk astGLOBAL(Plot,Crv_vxbrk_t) #define Crv_vybrk astGLOBAL(Plot,Crv_vybrk_t) #define Crv_xbrk astGLOBAL(Plot,Crv_xbrk_t) #define Crv_ybrk astGLOBAL(Plot,Crv_ybrk_t) #define Crv_len astGLOBAL(Plot,Crv_len_t) #define Crv_ink astGLOBAL(Plot,Crv_ink_t) #define Crv_nbrk astGLOBAL(Plot,Crv_nbrk_t) #define Crv_nent astGLOBAL(Plot,Crv_nent_t) #define Crv_out astGLOBAL(Plot,Crv_out_t) #define Crv_clip astGLOBAL(Plot,Crv_clip_t) #define Crv_map astGLOBAL(Plot,Crv_map_t) #define Box_lbnd astGLOBAL(Plot,Box_lbnd_t) #define Box_ubnd astGLOBAL(Plot,Box_ubnd_t) #define Boxp_lbnd astGLOBAL(Plot,Boxp_lbnd_t) #define Boxp_ubnd astGLOBAL(Plot,Boxp_ubnd_t) #define Boxp_freeze astGLOBAL(Plot,Boxp_freeze_t) #define Poly_x astGLOBAL(Plot,Poly_x_t) #define Poly_y astGLOBAL(Plot,Poly_y_t) #define Poly_n astGLOBAL(Plot,Poly_n_t) #define Poly_xp astGLOBAL(Plot,Poly_xp_t) #define Poly_yp astGLOBAL(Plot,Poly_yp_t) #define Poly_np astGLOBAL(Plot,Poly_np_t) #define Poly_npoly astGLOBAL(Plot,Poly_npoly_t) #define Map1_ncoord astGLOBAL(Plot,Map1_ncoord_t) #define Map1_plot astGLOBAL(Plot,Map1_plot_t) #define Map1_map astGLOBAL(Plot,Map1_map_t) #define Map1_frame astGLOBAL(Plot,Map1_frame_t) #define Map1_origin astGLOBAL(Plot,Map1_origin_t) #define Map1_length astGLOBAL(Plot,Map1_length_t) #define Map1_axis astGLOBAL(Plot,Map1_axis_t) #define Map1_statics astGLOBAL(Plot,Map1_statics_t) #define Map1_norm astGLOBAL(Plot,Map1_norm_t) #define Map1_log astGLOBAL(Plot,Map1_log_t) #define Map2_ncoord astGLOBAL(Plot,Map2_ncoord_t) #define Map2_plot astGLOBAL(Plot,Map2_plot_t) #define Map2_map astGLOBAL(Plot,Map2_map_t) #define Map2_x0 astGLOBAL(Plot,Map2_x0_t) #define Map2_y0 astGLOBAL(Plot,Map2_y0_t) #define Map2_deltax astGLOBAL(Plot,Map2_deltax_t) #define Map2_deltay astGLOBAL(Plot,Map2_deltay_t) #define Map2_statics astGLOBAL(Plot,Map1_statics_t) #define Map3_ncoord astGLOBAL(Plot,Map3_ncoord_t) #define Map3_plot astGLOBAL(Plot,Map3_plot_t) #define Map3_map astGLOBAL(Plot,Map3_map_t) #define Map3_frame astGLOBAL(Plot,Map3_frame_t) #define Map3_origin astGLOBAL(Plot,Map3_origin_t) #define Map3_end astGLOBAL(Plot,Map3_end_t) #define Map3_scale astGLOBAL(Plot,Map3_scale_t) #define Map3_statics astGLOBAL(Plot,Map3_statics_t) #define Map4_ncoord astGLOBAL(Plot,Map4_ncoord_t) #define Map4_plot astGLOBAL(Plot,Map4_plot_t) #define Map4_map astGLOBAL(Plot,Map4_map_t) #define Map4_umap astGLOBAL(Plot,Map4_umap_t) #define Map4_statics astGLOBAL(Plot,Map4_statics_t) #define Map5_plot astGLOBAL(Plot,Map5_plot_t) #define Map5_region astGLOBAL(Plot,Map5_region_t) #define Map5_map astGLOBAL(Plot,Map5_map_t) #define Map5_ncoord astGLOBAL(Plot,Map5_ncoord_t) #define Map5_statics astGLOBAL(Plot,Map5_statics_t) #define Curve_data astGLOBAL(Plot,Curve_data_t) #define getattrib_buff astGLOBAL(Plot,GetAttrib_Buff) #define splitvalue_buff astGLOBAL(Plot,SplitValue_Buff) #define stripescapes_buff astGLOBAL(Plot,StripEscapes_Buff) #define Grf_chv astGLOBAL(Plot,Grf_chv_t) #define Grf_chh astGLOBAL(Plot,Grf_chh_t) #define Grf_alpha astGLOBAL(Plot,Grf_alpha_t) #define Grf_beta astGLOBAL(Plot,Grf_beta_t) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Variables used within astGrfAttrs_ */ static double grfattrs_attrs[ GRF__NATTR ]; /* Saved attribute values */ static int grfattrs_nesting = 0; /* Nesting level. */ /* Variables used to pass information to the curve drawing functions. See the prologues of functions Crv and CrvLine for details. */ static double Crv_limit; static double Crv_scerr; static double Crv_tol; static double Crv_ux0; static double Crv_uy0; static double Crv_vxl; static double Crv_vyl; static double Crv_xhi; static double Crv_xl; static double Crv_xlo; static double Crv_yhi; static double Crv_yl; static double Crv_ylo; static float *Crv_vxbrk; static float *Crv_vybrk; static float *Crv_xbrk; static float *Crv_ybrk; static float Crv_len; static int Crv_ink; static int Crv_nbrk; static int Crv_nent = 0; static int Crv_out; static int Crv_clip; static void (*Crv_map)( int, double *, double *, double *, const char *, const char *, int * ); /* A cache of information calculated by the grf module. */ static double Grf_chv = AST__BAD; static double Grf_chh = AST__BAD; static float Grf_alpha = 0.0; static float Grf_beta = 0.0; /* The lower and upper bounds of the graphics coordinates enclosing all lines and numerical labels drawn by astGrid. */ static float Box_lbnd[ 2 ] = {FLT_MAX, FLT_MAX }; static float Box_ubnd[ 2 ] = {FLT_MIN, FLT_MIN }; /* The lower and upper bounds of the graphics coordinates enclosing all drawn graphics primatives, maintained by functions GLine, GMark and DrawText. */ static float Boxp_lbnd[ 2 ] = {FLT_MAX, FLT_MAX }; static float Boxp_ubnd[ 2 ] = {FLT_MIN, FLT_MIN }; static int Boxp_freeze = 0; /* Variables used to stored buffered poly lines (see functions Opoly, Bpoly and Apoly). */ static float *Poly_x = NULL; static float *Poly_y = NULL; static int Poly_n = 0; static float **Poly_xp = NULL; static float **Poly_yp = NULL; static int *Poly_np = NULL; static int Poly_npoly = 0; /* Variables used by function Map1. See the prologue of Map1 for details. */ static int Map1_ncoord; static AstPlot *Map1_plot = NULL; static AstMapping *Map1_map = NULL; static AstFrame *Map1_frame = NULL; static const double *Map1_origin = NULL; static double Map1_length; static void *Map1_statics = NULL; static int Map1_axis; static int Map1_norm; static int Map1_log; /* Variables used by function Map2. See the prologue of Map2 for details. */ static int Map2_ncoord; static AstPlot *Map2_plot = NULL; static AstMapping *Map2_map = NULL; static double Map2_x0; static double Map2_y0; static double Map2_deltax; static double Map2_deltay; static void *Map2_statics = NULL; /* Variables used by function Map3. See the prologue of Map3 for details. */ static int Map3_ncoord; static AstPlot *Map3_plot = NULL; static AstMapping *Map3_map = NULL; static AstFrame *Map3_frame = NULL; static const double *Map3_origin = NULL; static const double *Map3_end = NULL; static double Map3_scale; static void *Map3_statics = NULL; /* Variables used by function Map4. See the prologue of Map4 for details. */ static int Map4_ncoord; static AstPlot *Map4_plot = NULL; static AstMapping *Map4_map = NULL; static AstMapping *Map4_umap = NULL; static void *Map4_statics = NULL; /* Variables used by function Map5. See the prologue of Map5 for details. */ static AstPlot *Map5_plot = NULL; static AstMapping *Map5_map = NULL; static AstRegion *Map5_region = NULL; static void *Map5_statics = NULL; static int Map5_ncoord; /* A structure which stores information about the breaks in the last curve drawn using the public methods "astGridLine" and "astCurve". */ static AstPlotCurveData Curve_data; /* Buffers for strings returned by various functions. */ static char splitvalue_buff[ 200 ]; static char stripescapes_buff[ AST__PLOT_STRIPESCAPES_BUFF_LEN + 1 ]; static char getattrib_buff[ 200 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPlotVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #endif /* Macro to reset the cache of values caclulated by the grf module. */ #define RESET_GRF \ Grf_chh = AST__BAD; \ Grf_chv = AST__BAD; \ Grf_alpha = 0.0; \ Grf_beta = 0.0; /* Prototypes for Private Member Functions. */ /* ======================================== */ static double GetTol( AstPlot *, int * ); static int TestTol( AstPlot *, int * ); static void ClearTol( AstPlot *, int * ); static void SetTol( AstPlot *, double, int * ); static int GetGrid( AstPlot *, int * ); static int TestGrid( AstPlot *, int * ); static void ClearGrid( AstPlot *, int * ); static void SetGrid( AstPlot *, int, int * ); static int GetTickAll( AstPlot *, int * ); static int TestTickAll( AstPlot *, int * ); static void ClearTickAll( AstPlot *, int * ); static void SetTickAll( AstPlot *, int, int * ); static int GetForceExterior( AstPlot *, int * ); static int TestForceExterior( AstPlot *, int * ); static void ClearForceExterior( AstPlot *, int * ); static void SetForceExterior( AstPlot *, int, int * ); static int GetBorder( AstPlot *, int * ); static int TestBorder( AstPlot *, int * ); static void ClearBorder( AstPlot *, int * ); static void SetBorder( AstPlot *, int, int * ); static int GetInvisible( AstPlot *, int * ); static int TestInvisible( AstPlot *, int * ); static void ClearInvisible( AstPlot *, int * ); static void SetInvisible( AstPlot *, int, int * ); static int GetInk( AstPlot *, int * ); static int TestInk( AstPlot *, int * ); static void ClearInk( AstPlot *, int * ); static void SetInk( AstPlot *, int, int * ); static int GetClipOp( AstPlot *, int * ); static int TestClipOp( AstPlot *, int * ); static void ClearClipOp( AstPlot *, int * ); static void SetClipOp( AstPlot *, int, int * ); static int GetClip( AstPlot *, int * ); static int TestClip( AstPlot *, int * ); static void ClearClip( AstPlot *, int * ); static void SetClip( AstPlot *, int, int * ); static int GetGrf( AstPlot *, int * ); static int TestGrf( AstPlot *, int * ); static void ClearGrf( AstPlot *, int * ); static void SetGrf( AstPlot *, int, int * ); static int GetDrawTitle( AstPlot *, int * ); static int TestDrawTitle( AstPlot *, int * ); static void ClearDrawTitle( AstPlot *, int * ); static void SetDrawTitle( AstPlot *, int, int * ); static int GetDrawAxes( AstPlot *, int, int * ); static int TestDrawAxes( AstPlot *, int, int * ); static void ClearDrawAxes( AstPlot *, int, int * ); static void SetDrawAxes( AstPlot *, int, int, int * ); static int GetAbbrev( AstPlot *, int, int * ); static int TestAbbrev( AstPlot *, int, int * ); static void ClearAbbrev( AstPlot *, int, int * ); static void SetAbbrev( AstPlot *, int, int, int * ); static int GetEscape( AstPlot *, int * ); static int TestEscape( AstPlot *, int * ); static void ClearEscape( AstPlot *, int * ); static void SetEscape( AstPlot *, int, int * ); static double GetLabelAt( AstPlot *, int, int * ); static int TestLabelAt( AstPlot *, int, int * ); static void ClearLabelAt( AstPlot *, int, int * ); static void SetLabelAt( AstPlot *, int, double, int * ); static double GetNumLabGap( AstPlot *, int, int * ); static int TestNumLabGap( AstPlot *, int, int * ); static void ClearNumLabGap( AstPlot *, int, int * ); static void SetNumLabGap( AstPlot *, int, double, int * ); static double GetTextLabGap( AstPlot *, int, int * ); static int TestTextLabGap( AstPlot *, int, int * ); static void ClearTextLabGap( AstPlot *, int, int * ); static void SetTextLabGap( AstPlot *, int, double, int * ); static double GetCentre( AstPlot *, int, int * ); static int TestCentre( AstPlot *, int, int * ); static void ClearCentre( AstPlot *, int, int * ); static void SetCentre( AstPlot *, int, double, int * ); static double GetGap( AstPlot *, int, int * ); static int TestGap( AstPlot *, int, int * ); static void ClearGap( AstPlot *, int, int * ); static void SetGap( AstPlot *, int, double, int * ); static int GetLabelling( AstPlot *, int * ); static int TestLabelling( AstPlot *, int * ); static void ClearLabelling( AstPlot *, int * ); static void SetLabelling( AstPlot *, int, int * ); static double GetMajTickLen( AstPlot *, int, int * ); static int TestMajTickLen( AstPlot *, int, int * ); static void ClearMajTickLen( AstPlot *, int, int * ); static void SetMajTickLen( AstPlot *, int, double, int * ); static double GetLogGap( AstPlot *, int, int * ); static int TestLogGap( AstPlot *, int, int * ); static void ClearLogGap( AstPlot *, int, int * ); static void SetLogGap( AstPlot *, int, double, int * ); static double GetTitleGap( AstPlot *, int * ); static int TestTitleGap( AstPlot *, int * ); static void ClearTitleGap( AstPlot *, int * ); static void SetTitleGap( AstPlot *, double, int * ); static double GetMinTickLen( AstPlot *, int, int * ); static int TestMinTickLen( AstPlot *, int, int * ); static void ClearMinTickLen( AstPlot *, int, int * ); static void SetMinTickLen( AstPlot *, int, double, int * ); static int GetEdge( AstPlot *, int, int * ); static int TestEdge( AstPlot *, int, int * ); static void ClearEdge( AstPlot *, int, int * ); static void SetEdge( AstPlot *, int, int, int * ); static int GetLabelUp( AstPlot *, int, int * ); static int TestLabelUp( AstPlot *, int, int * ); static void ClearLabelUp( AstPlot *, int, int * ); static void SetLabelUp( AstPlot *, int, int, int * ); static int GetLogPlot( AstPlot *, int, int * ); static int TestLogPlot( AstPlot *, int, int * ); static void ClearLogPlot( AstPlot *, int, int * ); static void SetLogPlot( AstPlot *, int, int, int * ); static int GetLogTicks( AstPlot *, int, int * ); static int TestLogTicks( AstPlot *, int, int * ); static void ClearLogTicks( AstPlot *, int, int * ); static void SetLogTicks( AstPlot *, int, int, int * ); static int GetLogLabel( AstPlot *, int, int * ); static int TestLogLabel( AstPlot *, int, int * ); static void ClearLogLabel( AstPlot *, int, int * ); static void SetLogLabel( AstPlot *, int, int, int * ); static int GetNumLab( AstPlot *, int, int * ); static int TestNumLab( AstPlot *, int, int * ); static void ClearNumLab( AstPlot *, int, int * ); static void SetNumLab( AstPlot *, int, int, int * ); static int GetMinTick( AstPlot *, int, int * ); static int TestMinTick( AstPlot *, int, int * ); static void ClearMinTick( AstPlot *, int, int * ); static void SetMinTick( AstPlot *, int, int, int * ); static int GetTextLab( AstPlot *, int, int * ); static int TestTextLab( AstPlot *, int, int * ); static void ClearTextLab( AstPlot *, int, int * ); static void SetTextLab( AstPlot *, int, int, int * ); static int GetLabelUnits( AstPlot *, int, int * ); static int TestLabelUnits( AstPlot *, int, int * ); static void ClearLabelUnits( AstPlot *, int, int * ); static void SetLabelUnits( AstPlot *, int, int, int * ); static int GetStyle( AstPlot *, int, int * ); static int TestStyle( AstPlot *, int, int * ); static void ClearStyle( AstPlot *, int, int * ); static void SetStyle( AstPlot *, int, int, int * ); static int GetFont( AstPlot *, int, int * ); static int TestFont( AstPlot *, int, int * ); static void ClearFont( AstPlot *, int, int * ); static void SetFont( AstPlot *, int, int, int * ); static int GetColour( AstPlot *, int, int * ); static int TestColour( AstPlot *, int, int * ); static void ClearColour( AstPlot *, int, int * ); static void SetColour( AstPlot *, int, int, int * ); static double GetWidth( AstPlot *, int, int * ); static int TestWidth( AstPlot *, int, int * ); static void ClearWidth( AstPlot *, int, int * ); static void SetWidth( AstPlot *, int, double, int * ); static double GetSize( AstPlot *, int, int * ); static int TestSize( AstPlot *, int, int * ); static void ClearSize( AstPlot *, int, int * ); static void SetSize( AstPlot *, int, double, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static AstFrameSet *Fset2D( AstFrameSet *, int, int * ); static AstKeyMap *GetGrfContext( AstPlot *, int * ); static AstPlotCurveData **CleanCdata( AstPlotCurveData **, int * ); static AstPlotCurveData **DrawGrid( AstPlot *, TickInfo **, int, const char *, const char *, int * ); static AstPointSet *DefGap( AstPlot *, double *, int *, double *, int *, const char *, const char *, int * ); static AstPointSet *GetDrawnTicks( AstPlot *, int, int, int * ); static AstPointSet *Trans( AstPlot *, AstFrame *, AstMapping *, AstPointSet *, int, AstPointSet *, int, const char *, const char *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static TickInfo **CleanGrid( TickInfo **, int * ); static TickInfo **GridLines( AstPlot *, double *, double *, int *, const char *, const char *, int * ); static TickInfo *TickMarks( AstPlot *, int, double *, double *, int *, GetTicksStatics **, const char *, const char *, int * ); static char **CheckLabels2( AstPlot *, AstFrame *, int, double *, int, char **, double, int * ); static char *FindWord( char *, const char *, const char **, int * ); static char *GrfItem( int, const char *, int *, int * ); static const char *JustMB( AstPlot *, int, const char *, float *, float *, float, float, const char *, float, float, float, float, float *, float *, const char *, const char *, int * ); static const char *SplitValue( AstPlot *, const char *, int, int *, int * ); static double **MakeGrid( AstPlot *, AstFrame *, AstMapping *, int, int, double, double, double, double, int, AstPointSet **, AstPointSet**, int, const char *, const char *, int * ); static double GetTicks( AstPlot *, int, double *, double **, int *, double **, int *, int, int *, double *, GetTicksStatics **, const char *, const char *, int * ); static double GetUseSize( AstPlot *, int, int * ); static double GetUseWidth( AstPlot *, int, int * ); static double GoodGrid( AstPlot *, int *, AstPointSet **, AstPointSet **, const char *, const char *, int * ); static double Typical( int, double *, double, double, double *, int * ); static int Border( AstPlot *, int * ); static int Boundary( AstPlot *, const char *, const char *, int * ); static int BoxCheck( float *, float *, float *, float *, int * ); static int CGAttrWrapper( AstPlot *, int, double, double *, int, int * ); static int CGBBufWrapper( AstPlot *, int * ); static int CGCapWrapper( AstPlot *, int, int, int * ); static int CGEBufWrapper( AstPlot *, int * ); static int CGFlushWrapper( AstPlot *, int * ); static int CGLineWrapper( AstPlot *, int, const float *, const float *, int * ); static int CGMarkWrapper( AstPlot *, int, const float *, const float *, int, int * ); static int CGQchWrapper( AstPlot *, float *, float *, int * ); static int CGScalesWrapper( AstPlot *, float *, float *, int * ); static int CGTextWrapper( AstPlot *, const char *, float, float, const char *, float, float, int * ); static int CGTxExtWrapper( AstPlot *, const char *, float, float, const char *, float, float, float *, float *, int * ); static int CheckLabels( AstPlot *, AstFrame *, int, double *, int, int, char **, double, int * ); static int ChrLen( const char *, int * ); static int Compare_LL( const void *, const void * ); static int Compared( const void *, const void * ); static int CountGood( int, double *, int * ); static int Cross( float, float, float, float, float, float, float, float, int * ); static int CvBrk( AstPlot *, int, double *, double *, double *, int * ); static int DrawRegion( AstPlot *, AstFrame *, const char *, const char *, int * ); static int EdgeCrossings( AstPlot *, int, int, double, double *, double **, EdgeCrossingsStatics **, const char *, const char *, int * ); static int EdgeLabels( AstPlot *, int, TickInfo **, AstPlotCurveData **, int, const char *, const char *, int * ); static int FindDPTZ( AstFrame *, int, const char *, const char *, int *, int *, int * ); static int FindMajTicks( AstMapping *, AstFrame *, int, double, double, double , double *, int, double *, double **, int * ); static int FindMajTicks2( int, double, double, int, double *, double **, int * ); static int FindString( int, const char *[], const char *, const char *, const char *, const char *, int * ); static int Fpoly_ecmp( const void *, const void * ); static int Fpoly_scmp( const void *, const void * ); static int FullForm( const char *, const char *, const char *, const char *, const char *, int * ); static int GCap( AstPlot *, int, int, int * ); static int GVec( AstPlot *, AstMapping *, double *, int, double, AstPointSet **, AstPointSet **, double *, double *, double *, double *, int *, const char *, const char *, int * ); static int GetUseColour( AstPlot *, int, int * ); static int GetUseFont( AstPlot *, int, int * ); static int GetUseStyle( AstPlot *, int, int * ); static int GraphGrid( int, int, double, double, double, double, double **, int * ); static int HasEscapes( const char *, int * ); static int IdFind( int, int, int *, int *, int *, int * ); static int Inside( int, float *, float *, float, float, int * ); static int IsASkyAxis( AstFrame *, int, int * ); static int IsASkyFrame( AstObject *, int * ); static int Labelat( AstPlot *, TickInfo **, AstPlotCurveData **, double *, const char *, const char *, int * ); static int Overlap( AstPlot *, int, int, const char *, float, float, const char *, float, float, float **, const char *, const char *, int * ); static int PopGat( AstPlot *, float *, const char *, const char *, int * ); static int TestUseColour( AstPlot *, int, int * ); static int TestUseFont( AstPlot *, int, int * ); static int TestUseSize( AstPlot *, int, int * ); static int TestUseStyle( AstPlot *, int, int * ); static int TestUseWidth( AstPlot *, int, int * ); static int ToggleLogLin( AstPlot *, int, int, const char *, int * ); static int TraceBorder( AstPlot *, AstMapping *, double, double, double, double, int, double, int[ 4 ], const char *, const char *, int * ); static int Ustrcmp( const char *, const char *, int * ); static int Ustrncmp( const char *, const char *, size_t, int * ); static int swapEdges( AstPlot *, TickInfo **, AstPlotCurveData **, int * ); static void AddCdt( AstPlotCurveData *, AstPlotCurveData *, const char *, const char *, int * ); static void Apoly( AstPlot *, float, float, int * ); static void AxPlot( AstPlot *, int, const double *, double, int, AstPlotCurveData *, const char *, const char *, int * ); static void BBuf( AstPlot *, int * ); static void BoundingBox( AstPlot *, float[2], float[2], int * ); static void Bpoly( AstPlot *, float, float, int * ); static void Clip( AstPlot *, int, const double [], const double [], int * ); static void Copy( const AstObject *, AstObject *, int * ); static void CopyPlotDefaults( AstPlot *, int, AstPlot *, int, int * ); static void Crv( AstPlot *this, double *, double *, double *, int, double *, CrvStatics *, const char *, const char *, int * ); static void CrvLine( AstPlot *this, double, double, double, double, const char *, const char *, int * ); static void Curve( AstPlot *, const double [], const double [], int * ); static void CurvePlot( AstPlot *, const double *, const double *, int , AstPlotCurveData *, const char *, const char *, int * ); static void Delete( AstObject *, int * ); static void DrawAxis( AstPlot *, TickInfo **, double *, double *, const char *, const char *, int * ); static void DrawText( AstPlot *, int, int, const char *, float, float, const char *, float, float, float *, float *, float *, const char *, const char *, int * ); static void DrawTicks( AstPlot *, TickInfo **, int, double *, double *, const char *, const char *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void EBuf( AstPlot *, int * ); static void Fpoly( AstPlot *, const char *, const char *, int * ); static void GAttr( AstPlot *, int, double, double *, int, const char *, const char *, int * ); static void GBBuf( AstPlot *, const char *, const char *, int * )__attribute__((unused)); static void GEBuf( AstPlot *, const char *, const char *, int * )__attribute__((unused)); static void GFlush( AstPlot *, const char *, const char *, int * )__attribute__((unused)); static void GLine( AstPlot *, int, const float *, const float *, const char *, const char *, int * ); static void GMark( AstPlot *, int, const float *, const float *, int, const char *, const char *, int * ); static void GQch( AstPlot *, float *, float *, const char *, const char *, int * ); static void GScales( AstPlot *, float *, float *, const char *, const char *, int * ); static void GText( AstPlot *, const char *, float, float, const char *, float, float, const char *, const char *, int * ); static void GTxExt( AstPlot *, const char *, float , float, const char *, float, float, float *, float *, const char *, const char *, int * ); static void GenCurve( AstPlot *, AstMapping *, int * ); static void GrfPop( AstPlot *, int * ); static void GrfPush( AstPlot *, int * ); static void GrfSet( AstPlot *, const char *, AstGrfFun, int * ); static void GrfWrapper( AstPlot *, const char *, AstGrfWrap, int * ); static void Grid( AstPlot *, int * ); static void GridLine( AstPlot *, int, const double [], double, int * ); static void InterpEscape( AstPlot *, int, double, float *, float *, float, float, float, float, const char *, float *, double, double, double, double, double, const char *, const char *, int * ); static void Labels( AstPlot *, TickInfo **, AstPlotCurveData **, double *, double *, const char *, const char *, int * ); static void LinePlot( AstPlot *, double, double, double, double, int, AstPlotCurveData *, const char *, const char *, int * ); static void Map1( int, double *, double *, double *, const char *, const char *, int * GLOBALS_PROTO ); static void Map2( int, double *, double *, double *, const char *, const char *, int * GLOBALS_PROTO ); static void Map3( int, double *, double *, double *, const char *, const char *, int * GLOBALS_PROTO ); static void Map4( int, double *, double *, double *, const char *, const char *, int * GLOBALS_PROTO ); static void Map5( int, double *, double *, double *, const char *, const char *, int * GLOBALS_PROTO ); static void Mark( AstPlot *, int, int, int, const double *, int, int * ); static void Mirror( AstPlot *, int, int * ); static void Norm1( AstMapping *, int, int, double *, double, double, int * ); static void Opoly( AstPlot *, int * ); static void PlotLabels( AstPlot *, int, AstFrame *, int, LabelList *, char *, int, float **, const char *, const char *, int * ); static void PolyCurve( AstPlot *, int, int, int, const double *, int * ); static void PurgeCdata( AstPlotCurveData *, int * ); static void PushGat( AstPlot *, float, const char *, const char *, int * ); static void RegionOutline( AstPlot *, AstRegion *, int * ); static void RemoveFrame( AstFrameSet *, int, int * ); static void RightVector( AstPlot *, float *, float *, float *, float *, const char *, const char *, int * ); static void SaveTick( AstPlot *, int, double, double, int, int * ); static void SetTickValues( AstPlot *, int, int, double *, int, double *, int * ); static void Text( AstPlot *, const char *, const double [], const float [], const char *, int * ); static void TextLabels( AstPlot *, int, int *, const char *, const char *, int * ); static void Ticker( AstPlot *, int, int, double, double *, double, int, int, EdgeCrossingsStatics **, const char *, const char *, int * ); static void UpdateConcat( float *, float *, float, float, float, float, float *, float *, float, float, float *, float *, float *, float *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Functions which access class attributes. */ /* ======================================= */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Tol. */ /* ---- */ /* *att++ * Name: * Tol * Purpose: * Plotting tolerance. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute specifies the plotting tolerance (or resolution) * to be used for the graphical output produced by a Plot. Smaller * values will result in smoother and more accurate curves being * drawn, but may slow down the plotting process. Conversely, * larger values may speed up the plotting process in cases where * high resolution is not required. * * The Tol value should be given as a fraction of the minimum * dimension of the plotting area, and should lie in the range c from 1.0e-7 to 1.0. By default, a value of 0.01 is used. f from 1.0E-7 to 1.0. By default, a value of 0.01 is used. * Applicability: * Plot * All Plots have this attribute. *att-- */ /* The plotting tolerance. Has a value of -1.0 when not set yielding a default value of 0.01. Usable values are in the range 1.0E-7 to 1.0. */ astMAKE_CLEAR(Plot,Tol,tol,-1.0) astMAKE_GET(Plot,Tol,double,0.01,(this->tol == -1.0 ? 0.01 : this->tol)) astMAKE_SET(Plot,Tol,double,tol,astMIN(astMAX(value,1.0E-7),1.0)) astMAKE_TEST(Plot,Tol,( this->tol != -1.0 )) /* Grid. */ /* ----- */ /* *att++ * Name: * Grid * Purpose: * Draw grid lines for a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether grid lines (a grid of curves marking the "major" values * on each axis) are drawn across the plotting area. * * If the Grid value of a Plot is non-zero, then grid lines will be * drawn. Otherwise, short tick marks on the axes are used to mark * the major axis values. The default behaviour is to use tick * marks if the entire plotting area is filled by valid physical * coordinates, but to draw grid lines otherwise. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The spacing between major axis values, which determines the * spacing of grid lines, may be set using the Gap(axis) attribute. *att-- */ /* If non-zero use lines instead of tick marks in a coordinate grid. Has a value of -1 when not set yielding a default value of 0. */ astMAKE_CLEAR(Plot,Grid,grid,-1) astMAKE_GET(Plot,Grid,int,0,(this->grid == -1 ? 0 : this->grid)) astMAKE_SET(Plot,Grid,int,grid,( value ? 1 : 0 )) astMAKE_TEST(Plot,Grid,( this->grid != -1 )) MAKE_GET2(Plot,Grid,int,0,this->ugrid) MAKE_SET2(Plot,Grid,int,ugrid,( value ? 1 : 0 )) /* Invisible. */ /* ---------- */ /* *att++ * Name: * Invisible * Purpose: * Draw graphics using invisible ink? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of all graphics produced by * Plot methods by determining whether graphics should be visible or * invisible. * * If the Invisible value of a Plot is non-zero, then all the Plot * methods which normally generate graphical output do not do so (you * can think of them drawing with "invisible ink"). Such methods do, * however, continue to do all the calculations which would be needed to * produce the graphics. In particular, the bounding box enclosing the * graphics is still calculated and can be retrieved as normal using c astBoundingBox. The default value is zero, resulting in all methods f AST_BOUNDINGBOX. The default value is zero, resulting in all methods * drawing graphics as normal, using visible ink. * Applicability: * Plot * All Plots have this attribute. *att-- */ /* If non-zero use invisible ink. Has a value of -1 when not set yielding a default value of 0. */ astMAKE_CLEAR(Plot,Invisible,invisible,-1) astMAKE_GET(Plot,Invisible,int,0,(this->invisible == -1 ? 0 : this->invisible)) astMAKE_SET(Plot,Invisible,int,invisible,( value ? 1 : 0 )) astMAKE_TEST(Plot,Invisible,( this->invisible != -1 )) /* TickAll */ /* ------- */ /* *att++ * Name: * TickAll * Purpose: * Draw tick marks on all edges of a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether tick marks should be drawn on all edges of a Plot. * * If the TickAll value of a Plot is non-zero (the default), then * tick marks will be drawn on all edges of the Plot. Otherwise, * they will be drawn only on those edges where the numerical and * descriptive axis labels are drawn (see the Edge(axis) * attribute). * Applicability: * Plot * All Plots have this attribute. * Notes: * - In some circumstances, numerical labels and tick marks are * drawn along grid lines inside the plotting area, rather than * around its edges (see the Labelling attribute). In this case, * the value of the TickAll attribute is ignored. *att-- */ /* If non-zero put tick marks on opposite edges. Has a value of -1 when not set yielding a default value of 1. */ astMAKE_CLEAR(Plot,TickAll,tickall,-1) astMAKE_GET(Plot,TickAll,int,1,(this->tickall == -1 ? 1 : this->tickall)) astMAKE_SET(Plot,TickAll,int,tickall,( value ? 1 : 0 )) astMAKE_TEST(Plot,TickAll,( this->tickall != -1 )) /* ForceExterior */ /* ------------- */ /* *att+ * Name: * ForceExterior * Purpose: * Force the use of exterior labelling? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by forcing f coordinate grid (drawn with the AST_GRID routine) by forcing * labels and tick marks to be drawn round the edges of the plot * (rather than across the middle of the plot), even if there appear * to be insufficient edge crossings to justify the use of exterior * labelling. * * The default value of zero results in the decision about whether to * use interior or exterior labelling being made purely on the basis * of the value of the Labelling attribute. If ForceExterior is set to * a non-zero value, then the Labelling attribute is ignored and exterior * labelling will always be attempted, even if there appear to be * insufficient edge labels to justify their use. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The value of this attribute is currently under investigation, and * so this attribute prologue is currently marked as protected rather * than public (in order to prevent it being included in the public * documentation). *att- */ astMAKE_CLEAR(Plot,ForceExterior,forceexterior,-1) astMAKE_GET(Plot,ForceExterior,int,0,(this->forceexterior == -1 ? 0 : this->forceexterior)) astMAKE_SET(Plot,ForceExterior,int,forceexterior,( value ? 1 : 0 )) astMAKE_TEST(Plot,ForceExterior,( this->forceexterior != -1 )) /* *att++ * Name: * Border * Purpose: * Draw a border around valid regions of a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether a border is drawn around regions corresponding to the c valid physical coordinates of a Plot (c.f. astBorder). f valid physical coordinates of a Plot (c.f. AST_BORDER). * * If the Border value of a Plot is non-zero, then this border will * be drawn as part of the grid. Otherwise, the border is not drawn * (although axis labels and tick marks will still appear, unless * other relevant Plot attributes indicate that they should * not). The default behaviour is to draw the border if tick marks * and numerical labels will be drawn around the edges of the * plotting area (see the Labelling attribute), but to omit it * otherwise. * Applicability: * Plot * All Plots have this attribute. *att-- */ /* If non-zero draw the border. Has a value of -1 when not set, yeilding a default of 1. */ astMAKE_CLEAR(Plot,Border,border,-1) astMAKE_SET(Plot,Border,int,border,( value ? 1 : 0 )) astMAKE_TEST(Plot,Border,( this->border != -1 )) astMAKE_GET(Plot,Border,int,1,(this->border == -1 ? 1 : this->border)) MAKE_SET2(Plot,Border,int,uborder,( value ? 1 : 0 )) MAKE_GET2(Plot,Border,int,1,this->uborder) /* Clip */ /* ---- */ /* *att++ * Name: * Clip * Purpose: * Clip lines and/or markers at the Plot boundary? * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute controls whether curves and markers are clipped at the * boundary of the graphics box specified when the Plot was created. A * value of 3 implies both markers and curves are clipped at the Plot * boundary. A value of 2 implies markers are clipped, but not curves. A * value of 1 implies curves are clipped, but not markers. A value of * zero implies neither curves nor markers are clipped. The default * value is 1. Note, this attributes controls only the clipping * performed internally within AST. The underlying graphics system may * also apply clipping. In such cases, removing clipping using this * attribute does not guarantee that no clipping will be visible in the * final plot. * c The astClip function f The AST_CLIP routine * can be used to establish generalised clipping within arbitrary * regions of the Plot. * Applicability: * Plot * All Plots have this attribute. *att-- */ astMAKE_CLEAR(Plot,Clip,clip,-1) astMAKE_GET(Plot,Clip,int,0,(this->clip == -1 ? 1 : this->clip)) astMAKE_TEST(Plot,Clip,( this->clip != -1 )) astMAKE_SET(Plot,Clip,int,clip,((value>=0&&value<=3)?value:(astError( AST__ATTIN, "astSetClip(Plot): Invalid value %d supplied for Clip attribute", status, value ), this->clip))) /* ClipOp */ /* ------ */ /* *att++ * Name: * ClipOp * Purpose: * Combine Plot clipping limits using a boolean OR? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls how the clipping limits specified for c each axis of a Plot (using the astClip function) are f each axis of a Plot (using the AST_CLIP routine) are * combined. This, in turn, determines which parts of the graphical * output will be visible. * * If the ClipOp attribute of a Plot is zero (the default), * graphical output is visible only if it satisfies the clipping * limits on all the axes of the clipping Frame (a boolean * AND). Otherwise, if ClipOp is non-zero, output is visible if it * satisfies the clipping limits on one or more axes (a boolean * OR). * * An important use of this attribute is to allow areas of a Plot * to be left clear (e.g. as a background for some text). To * achieve this, the lower and upper clipping bounds supplied to c astClip should be reversed, and the ClipOp attribute of the f AST_CLIP should be reversed, and the ClipOp attribute of the * Plot should be set to a non-zero value. * Applicability: * Plot * All Plots have this attribute. *att-- */ /* If non-zero only 1axis need be within the clipping bounds to avoid a point being clipped. Otherwise, all axes must be within bounds. */ astMAKE_CLEAR(Plot,ClipOp,clipop,-1) astMAKE_GET(Plot,ClipOp,int,0,(this->clipop == -1 ? 0 : this->clipop)) astMAKE_SET(Plot,ClipOp,int,clipop,( value ? 1 : 0 )) astMAKE_TEST(Plot,ClipOp,( this->clipop != -1 )) /* Grf. */ /* ---- */ /* *att++ * Name: * Grf * Purpose: c Use Grf functions registered through astGrfSet? f Use Grf routines registered through AST_GRFSET? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: c This attribute selects the functions which are used to draw graphics by c the Plot class. If it is zero, then the functions in the graphics c interface selected at link-time are used (see the ast_link script). c Otherwise, functions registered using astGrfSet are used. In this c case, if a function is needed which has not been registered, c then the function in the graphics interface selected at link-time is c used. f This attribute selects the routines which are used to draw graphics by f the Plot class. If it is zero, then the routines in the graphics f interface selected at link-time are used (see the ast_link script). f Otherwise, routines registered using AST_GRFSET are used. In this f case, if a routine is needed which has not been registered, f then the routine in the graphics interface selected at link-time is f used. * The default is to use the graphics interface * Applicability: * Plot * All Plots have this attribute. * Plot3D * The Plot3D class ignores this attributes, assuming a value of * zero. * Notes: * - The value of this attribute is not saved when the Plot is written * out through a Channel to an external data store. On re-loading such c a Plot using astRead, the attribute will be cleared, resulting in the f a Plot using AST_READ, the attribute will be cleared, resulting in the * graphics interface selected at link-time being used. *att-- */ /* Use Grf routines registered using astGrfSet? Has a value of -1 when not set yielding a default of 0. */ astMAKE_CLEAR(Plot,Grf,grf,-1) astMAKE_GET(Plot,Grf,int,0,(this->grf == -1 ? 0 : this->grf)) astMAKE_SET(Plot,Grf,int,grf,( value ? 1 : 0 )) astMAKE_TEST(Plot,Grf,( this->grf != -1 )) /* DrawTitle */ /* --------- */ /* *att++ * Name: * DrawTitle * Purpose: * Draw a title for a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether a title is drawn. * * If the DrawTitle value of a Plot is non-zero (the default), then * the title will be drawn, otherwise it will be omitted. * Applicability: * Plot * All Plots have this attribute. * Plot3D * The Plot3D class ignores this attributes, assuming a value of * zero. * Notes: * - The text used for the title is obtained from the Plot's Title * attribute. * - The vertical placement of the title can be controlled using * the TitleGap attribute. *att-- */ /* If non-zero add a title to the grid. Has a value of -1 when not set yielding a default value of 1. */ astMAKE_CLEAR(Plot,DrawTitle,drawtitle,-1) astMAKE_GET(Plot,DrawTitle,int,1,(this->drawtitle == -1 ? 1 : this->drawtitle)) astMAKE_SET(Plot,DrawTitle,int,drawtitle,( value ? 1 : 0 )) astMAKE_TEST(Plot,DrawTitle,( this->drawtitle != -1 )) /* LabelUp. */ /* ------- */ /* *att++ * Name: * LabelUp(axis) * Purpose: * Draw numerical Plot labels upright? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether the numerical labels for each axis of a Plot should be * drawn upright or not. It takes a separate value for each * physical axis of a Plot so that, for instance, the setting * "LabelUp(2)=1" specifies that numerical labels for the second * axis should be drawn upright. * * If the LabelUp value of a Plot axis is non-zero, it causes * numerical labels for that axis to be plotted upright (i.e. as * normal, horizontal text), otherwise labels are drawn parallel to * the axis to which they apply. * * The default is to produce upright labels if the labels are placed * around the edge of the plot, and to produce labels that follow the * axes if the labels are placed within the interior of the plot (see * attribute Labelling). * Applicability: * Plot * All Plots have this attribute. * Notes: * - In some circumstances, numerical labels and tick marks are * drawn around the edges of the plotting area (see the Labelling * attribute). In this case, the value of the LabelUp attribute is * ignored. * - If no axis is specified, (e.g. "LabelUp" instead of * "LabelUp(2)"), then a "set" or "clear" operation will affect the * attribute value of all the Plot axes, while a "get" or "test" * operation will use just the LabelUp(1) value. *att-- */ /* Are numerical labels to be displayed on each axis? Has a value of -1 when not set yielding a value of 0 (no) for both axes. */ MAKE_CLEAR(LabelUp,labelup,-1,0) MAKE_GET(LabelUp,int,0,( this->labelup[axis] == -1 ? 0 : this->labelup[axis] ),0) MAKE_TEST(LabelUp,( this->labelup[axis] != -1 ),0) MAKE_SET(LabelUp,int,labelup,( value ? 1 : 0 ),0) /* DrawAxes */ /* -------- */ /* *att++ * Name: * DrawAxes(axis) * Purpose: * Draw axes for a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether curves representing coordinate axes should be drawn. * It takes a separate value for each physical axis of a * Plot so that, for instance, the setting "DrawAxes(2)=0" * specifies that no axis should be drawn for the second axis. * * If drawn, these axis lines will pass through any tick marks * associated with numerical labels drawn to mark values on the * axes. The location of these tick marks and labels (and hence the * axis lines) is determined by the Plot's LabelAt(axis) attribute. * * If the DrawAxes value of a Plot is non-zero (the default), then * axis lines will be drawn, otherwise they will be omitted. * Applicability: * Plot * All Plots have this attribute. * Notes: * - Axis lines are drawn independently of any coordinate grid * lines (see the Grid attribute) so grid lines may be used to * substitute for axis lines if required. * - In some circumstances, numerical labels and tick marks are * drawn around the edges of the plotting area (see the Labelling * attribute). In this case, the value of the DrawAxes attribute * is ignored. * - If no axis is specified, (e.g. "DrawAxes" instead of * "DrawAxes(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the DrawAxes(1) value. *att-- */ /* If non-zero draw a curve through the tick marks. Has a value of -1 when not set yielding a default value of 1. */ MAKE_CLEAR(DrawAxes,drawaxes,-1,0) MAKE_GET(DrawAxes,int,1,( this->drawaxes[axis] == -1 ? 1 : this->drawaxes[axis] ),0) MAKE_TEST(DrawAxes,( this->drawaxes[axis] != -1 ),0) MAKE_SET(DrawAxes,int,drawaxes,( value ? 1 : 0 ),0) /* Abbrev */ /* -------- */ /* *att++ * Name: * Abbrev(axis) * Purpose: * Abbreviate leading fields within numerical axis labels? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether matching leading fields should be removed from adjacent * numerical axis labels. It takes a separate value for each physical * axis of a Plot so that, for instance, the setting "Abbrev(2)=0" * specifies that matching leading fields should not be removed on * the second axis. * * If the Abbrev value of a Plot is non-zero (the default), then * leading fields will be removed from adjacent axis labels if they * are equal. * Applicability: * Plot * All Plots have this attribute. * Notes: * - If no axis is specified, (e.g. "Abbrev" instead of * "Abbrev(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the Abbrev(1) value. *att-- */ MAKE_CLEAR(Abbrev,abbrev,-1,0) MAKE_GET(Abbrev,int,1,( this->abbrev[axis] == -1 ? 1 : this->abbrev[axis] ),0) MAKE_TEST(Abbrev,( this->abbrev[axis] != -1 ),0) MAKE_SET(Abbrev,int,abbrev,( value ? 1 : 0 ),0) /* Escape. */ /* ------- */ /* *att++ * Name: * Escape * Purpose: * Allow changes of character attributes within strings? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of text strings and numerical c labels drawn by the astGrid and (for the Plot class) astText functions, f labels drawn by the AST_GRID and (for the Plot class) AST_TEXT routines, * by determining if any escape sequences contained within the strings * should be used to control the appearance of the text, or should * be printed literally. Note, the Plot3D class only interprets escape * sequences within the c astGrid function. f AST_GRID routine. * * If the Escape value of a Plot is one (the default), then any * escape sequences in text strings produce the effects described * below when printed. Otherwise, they are printed literally. * c See also the astEscapes function. f See also the AST_ESCAPES function. * Escape Sequences: * Escape sequences are introduced into the text string by a percent * "%" character. Any unrecognised, illegal or incomplete escape sequences * are printed literally. The following escape sequences are * currently recognised ("..." represents a string of one or more * decimal digits): * * %% - Print a literal "%" character. * * %^...+ - Draw subsequent characters as super-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the super-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text. * %^+ - Draw subsequent characters with the normal base-line. * * %v...+ - Draw subsequent characters as sub-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the sub-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %v+ - Draw subsequent characters with the normal base-line * (equivalent to %^+). * * %>...+ - Leave a gap before drawing subsequent characters. * The digits "..." give the size of the gap, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %<...+ - Move backwards before drawing subsequent characters. * The digits "..." give the size of the movement, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %s...+ - Change the Size attribute for subsequent characters. The * digits "..." give the new Size as a fraction of the * "normal" Size, scaled so that a value of "100" corresponds * to 1.0; * * %s+ - Reset the Size attribute to its "normal" value. * * %w...+ - Change the Width attribute for subsequent characters. The * digits "..." give the new width as a fraction of the * "normal" Width, scaled so that a value of "100" corresponds * to 1.0; * * %w+ - Reset the Size attribute to its "normal" value. * * %f...+ - Change the Font attribute for subsequent characters. The * digits "..." give the new Font value. * * %f+ - Reset the Font attribute to its "normal" value. * * %c...+ - Change the Colour attribute for subsequent characters. The * digits "..." give the new Colour value. * * %c+ - Reset the Colour attribute to its "normal" value. * * %t...+ - Change the Style attribute for subsequent characters. The * digits "..." give the new Style value. * * %t+ - Reset the Style attribute to its "normal" value. * * %h+ - Remember the current horizontal position (see "%g+") * * %g+ - Go to the horizontal position of the previous "%h+" (if any). * * %- - Push the current graphics attribute values onto the top of * the stack (see "%+"). * * %+ - Pop attributes values of the top the stack (see "%-"). If * the stack is empty, "normal" attribute values are restored. * Applicability: * Plot * All Plots have this attribute. *att-- */ /* Has a value of -1 when not set yeilding a default of 1. */ astMAKE_GET(Plot,Escape,int,1,(this->escape == -1 ? 1 : this->escape)) astMAKE_CLEAR(Plot,Escape,escape,-1) astMAKE_SET(Plot,Escape,int,escape,( value ? 1 : 0 )) astMAKE_TEST(Plot,Escape,( this->escape != -1 )) /* LabelAt(axis). */ /* -------------- */ /* *att++ * Name: * LabelAt(axis) * Purpose: * Where to place numerical labels for a Plot * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * where numerical axis labels and associated tick marks are * placed. It takes a separate value for each physical axis of a * Plot so that, for instance, the setting "LabelAt(2)=10.0" * specifies where the numerical labels and tick marks for the * second axis should be drawn. * * For each axis, the LabelAt value gives the value on the other * axis at which numerical labels and tick marks should be placed c (remember that Plots suitable for use with astGrid may only f (remember that Plots suitable for use with AST_GRID may only * have two axes). For example, in a celestial (RA,Dec) coordinate * system, LabelAt(1) gives a Dec value which defines a line (of * constant Dec) along which the numerical RA labels and their * associated tick marks will be drawn. Similarly, LabelAt(2) gives * the RA value at which the Dec labels and ticks will be drawn. * * The default bahaviour is for the Plot to generate its own * position for numerical labels and tick marks. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The LabelAt value should use the same units as are used * internally for storing coordinate values on the appropriate * axis. For example, with a celestial coordinate system, the * LabelAt value should be in radians, not hours or degrees. * - Normally, the LabelAt value also determines where the lines * representing coordinate axes will be drawn, so that the tick * marks will lie on these lines (but also see the DrawAxes * attribute). * - In some circumstances, numerical labels and tick marks are * drawn around the edges of the plotting area (see the Labelling * attribute). In this case, the value of the LabelAt attribute is * ignored. *att-- */ /* The constant value on the other axis at which to place labels for each axis. */ MAKE_CLEAR(LabelAt,labelat,AST__BAD,0) MAKE_GET(LabelAt,double,AST__BAD,this->labelat[axis],0) MAKE_SET(LabelAt,double,labelat,value,0) MAKE_TEST(LabelAt,( this->labelat[axis] != AST__BAD ),0) MAKE_GET3(LabelAt,double,AST__BAD,this->ulblat[axis],0) MAKE_SET3(LabelAt,double,ulblat,value,0) /* Centre(axis). */ /* ------------ */ /* A value at which to place a tick mark. Other ticks marks are spaced at regular distances from this one. AST__BAD is stored if no value is supplied, resulting in Plot choosing its own value. */ MAKE_CLEAR(Centre,centre,AST__BAD,0) MAKE_GET(Centre,double,AST__BAD,this->centre[axis],0) MAKE_SET(Centre,double,centre,value,0) MAKE_TEST(Centre,( this->centre[axis] != AST__BAD ),0) MAKE_GET3(Centre,double,AST__BAD,this->ucentre[axis],0) MAKE_SET3(Centre,double,ucentre,value,0) /* Ink */ /* --- */ /* A protected attribute indicating if astGrid should draw using visible ink. The unset value is -1, yeilding a default value of 1. */ astMAKE_CLEAR(Plot,Ink,ink,-1) astMAKE_GET(Plot,Ink,int,1,(this->ink == -1 ? 1 : this->ink)) astMAKE_SET(Plot,Ink,int,ink,( value ? 1 : 0 )) astMAKE_TEST(Plot,Ink,( this->ink != -1 )) /* Gap(axis). */ /* ---------- */ /* *att++ * Name: * Gap(axis) * Purpose: * Interval between linearly spaced major axis values of a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the linear interval between the "major" axis values of a Plot, at * which (for example) major tick marks are drawn. It takes a separate * value for each physical axis of the Plot so that, for instance, * the setting "Gap(2)=3.0" specifies the difference between adjacent major * values along the second axis. The Gap attribute is only used when * the LogTicks attribute indicates that the spacing between major axis * values is to be linear. If major axis values are logarithmically spaced * then the gap is specified using attribute LogGap. * * The Gap value supplied will usually be rounded to the nearest * "nice" value, suitable (e.g.) for generating axis labels, before * use. To avoid this "nicing" you should set an explicit format * for the axis using the Format(axis) or Digits/Digits(axis) * attribute. The default behaviour is for the Plot to generate its * own Gap value when required, based on the range of axis values * to be represented. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The Gap value should use the same units as are used internally * for storing coordinate values on the corresponding axis. For * example, with a celestial coordinate system, the Gap value * should be in radians, not hours or degrees. * - If no axis is specified, (e.g. "Gap" instead of "Gap(2)"), * then a "set" or "clear" operation will affect the attribute * value of all the Plot axes, while a "get" or "test" operation * will use just the Gap(1) value. *att-- */ /* The gap between tick marks on each axis. AST__BAD is stored if no value has been supplied, resulting in default values being found. */ MAKE_CLEAR(Gap,gap,AST__BAD,0) MAKE_SET(Gap,double,gap,value,0) MAKE_TEST(Gap,( this->gap[axis] != AST__BAD ),0) MAKE_GET(Gap,double,AST__BAD,this->gap[axis],0) MAKE_SET3(Gap,double,ugap,value,0) MAKE_GET3(Gap,double,AST__BAD,this->ugap[axis],0) /* LogGap(axis). */ /* ---------- */ /* *att++ * Name: * LogGap(axis) * Purpose: * Interval between major axis values of a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the logarithmic interval between the "major" axis values of a Plot, at * which (for example) major tick marks are drawn. It takes a separate * value for each physical axis of the Plot so that, for instance, * the setting "LogGap(2)=100.0" specifies the ratio between adjacent major * values along the second axis. The LogGap attribute is only used when * the LogTicks attribute indicates that the spacing between major axis * values is to be logarithmic. If major axis values are linearly spaced * then the gap is specified using attribute Gap. * * The LogGap value supplied will be rounded to the nearest power of 10. * The reciprocal of the supplied value may be used if this is necessary * to produce usable major axis values. If a zero or negative value is * supplied, an error will be reported when the grid is drawn. The default * behaviour is for the Plot to generate its own LogGap value when * required, based on the range of axis values to be represented. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The LogGap value is a ratio between axis values and is therefore * dimensionless. * - If no axis is specified, (e.g. "LogGap" instead of "LogGap(2)"), * then a "set" or "clear" operation will affect the attribute * value of all the Plot axes, while a "get" or "test" operation * will use just the LogGap(1) value. *att-- */ /* The logarithmic gap between tick marks on each axis. AST__BAD is stored if no value has been supplied, resulting in default values being found. */ MAKE_CLEAR(LogGap,loggap,AST__BAD,0) MAKE_SET(LogGap,double,loggap,value,0) MAKE_TEST(LogGap,( this->loggap[axis] != AST__BAD ),0) MAKE_GET(LogGap,double,AST__BAD,this->loggap[axis],0) MAKE_SET3(LogGap,double,uloggap,value,0) MAKE_GET3(LogGap,double,AST__BAD,this->uloggap[axis],0) /* LogPlot. */ /* ------- */ /* *att++ * Name: * LogPlot(axis) * Purpose: * Map the plot logarithmically onto the screen? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of all graphics produced by * the Plot, by determining whether the axes of the plotting surface * are mapped logarithmically or linearly onto the base Frame of the * FrameSet supplied when the Plot was constructed. It takes a separate * value for each axis of the graphics coordinate system (i.e. the * base Frame in the Plot) so that, for instance, the setting * "LogPlot(2)=1" specifies that the second axis of the graphics * coordinate system (usually the vertical axis) should be mapped * logarithmically onto the second axis of the base Frame of the * FrameSet supplied when the Plot was constructed. * * If the LogPlot value of a Plot axis is non-zero, it causes that * axis to be mapped logarithmically, otherwise (the default) the axis * is mapped linearly. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The setting of the LogPlot attribute provides the default value * for the related LogTicks attribute. By selecting suitable values for * LogPlot and LogTicks, it is possible to have tick marks which are evenly * spaced in value but which are mapped logarithmically onto the screen * (and vice-versa). * - An axis may only be mapped logarithmically if the visible part of * the axis does not include the value zero. The visible part of the * axis is that part which is mapped onto the plotting area, and is * measured within the base Frame of the FrameSet which was supplied when * the Plot was constructed. Any attempt to set LogPlot to a non-zero value * will be ignored (without error) if the visible part of the axis * includes the value zero * - If no axis is specified, (e.g. "LogPlot" instead of * "LogPlot(2)"), then a "set" or "clear" operation will affect the * attribute value of all the Plot axes, while a "get" or "test" * operation will use just the LogPlot(1) value. *att-- */ /* Are plot axes to be mapped logarithmically? Has a value of -1 when not set yielding a value of 0 (no) for both axes. */ MAKE_GET(LogPlot,int,0,( this->logplot[axis] == -1 ? 0 : this->logplot[axis] ),0) MAKE_TEST(LogPlot,( this->logplot[axis] != -1 ),0) /* LogTicks. */ /* ------- */ /* *att++ * Name: * LogTicks(axis) * Purpose: * Space the major tick marks logarithmically? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether the major tick marks should be spaced logarithmically or * linearly in axis value. It takes a separate value for each physical * axis of the Plot so that, for instance, the setting "LogTicks(2)=1" * specifies that the major tick marks on the second axis should be * spaced logarithmically. * * If the LogTicks value for a physical axis is non-zero, the major * tick marks on that axis will be spaced logarithmically (that is, * there will be a constant ratio between the axis values at adjacent * major tick marks). An error will be reported if the dynamic range of * the axis (the ratio of the largest to smallest displayed axis value) * is less than 10.0. If the LogTicks value is zero, the major tick marks * will be evenly spaced (that is, there will be a constant difference * between the axis values at adjacent major tick marks). The default is * to produce logarithmically spaced tick marks if the corresponding * LogPlot attribute is non-zero and the ratio of maximum axis value * to minimum axis value is 100 or more. If either of these conditions * is not met, the default is to produce linearly spaced tick marks. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The setting of the LogTicks attribute does not affect the mapping * of the plot onto the screen, which is controlled by attribute LogPlot. * By selecting suitable values for LogPlot and LogTicks, it is possible to * have tick marks which are evenly spaced in value but which are mapped * logarithmically onto the screen (and vica-versa). * - An error will be reported when drawing an annotated axis grid if * the visible part of the physical axis includes the value zero. * - If no axis is specified, (e.g. "LogTicks" instead of * "LogTicks(2)"), then a "set" or "clear" operation will affect the * attribute value of all the Plot axes, while a "get" or "test" * operation will use just the LogTicks(1) value. *att-- */ /* Are ticksto be spaced logarithmically? Has a value of -1 when not set, yeielding a default value equal to the corresponding LogPlot value. */ MAKE_CLEAR(LogTicks,logticks,-1,0) MAKE_GET(LogTicks,int,0,( this->logticks[axis] == -1 ? astGetLogPlot(this,axis) : this->logticks[axis] ),0) MAKE_TEST(LogTicks,( this->logticks[axis] != -1 ),0) MAKE_SET(LogTicks,int,logticks,( value ? 1 : 0 ),0) MAKE_SET3(LogTicks,int,ulgtk,value,0) MAKE_GET3(LogTicks,int,0,this->ulgtk[axis],0) /* LogLabel. */ /* -------- */ /* *att++ * Name: * LogLabel(axis) * Purpose: * Use exponential format for numerical axis labels? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether the numerical axis labels should be in normal decimal form * or should be represented as 10 raised to the appropriate power. * That is, an axis value of 1000.0 will be drawn as "1000.0" if * LogLabel is zero, but as "10^3" if LogLabel is non-zero. If * graphical escape sequences are supported (see attribute Escape), * the power in such exponential labels will be drawn as a small * superscript instead of using a "^" character to represent * exponentiation. * * The default is to produce exponential labels if the major tick * marks are logarithmically spaced (see the LogTicks attribute). * Applicability: * Plot * All Plots have this attribute. * Notes: * - If no axis is specified, (e.g. "LogLabel" instead of * "LogLabel(2)"), then a "set" or "clear" operation will affect the * attribute value of all the Plot axes, while a "get" or "test" * operation will use just the LogLabel(1) value. *att-- */ /* Are labels to be drawn as 10**x? Has a value of -1 when not set, yeielding a default value equal to the corresponding LogTicks value. */ MAKE_CLEAR(LogLabel,loglabel,-1,0) MAKE_GET(LogLabel,int,0,( this->loglabel[axis] == -1 ? astGetLogTicks(this,axis) : this->loglabel[axis] ),0) MAKE_TEST(LogLabel,( this->loglabel[axis] != -1 ),0) MAKE_SET(LogLabel,int,loglabel,( value ? 1 : 0 ),0) MAKE_SET3(LogLabel,int,ulglb,value,0) MAKE_GET3(LogLabel,int,0,this->ulglb[axis],0) /* MajTickLen. */ /* ----------- */ /* *att++ * Name: * MajTickLen(axis) * Purpose: * Length of major tick marks for a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the length of the major tick marks drawn on the axes of a Plot. * It takes a separate value for each physical axis of the Plot so * that, for instance, the setting "MajTickLen(2)=0" specifies the * length of the major tick marks drawn on the second axis. * * The MajTickLen value should be given as a fraction of the * minimum dimension of the plotting area. Negative values cause * major tick marks to be placed on the outside of the * corresponding grid line or axis (but subject to any clipping * imposed by the underlying graphics system), while positive * values cause them to be placed on the inside. * * The default behaviour depends on whether a coordinate grid is * drawn inside the plotting area (see the Grid attribute). If so, * the default MajTickLen value is zero (so that major ticks are * not drawn), otherwise the default is +0.015. * Applicability: * Plot * All Plots have this attribute. * Notes: * - If no axis is specified, (e.g. "MajTickLen" instead of * "MajTickLen(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or "test" * operation will use just the MajTickLen(1) value. *att-- */ /* Fractional length of major tick marks. Has a value of AST__BAD when not set yielding a default value of 0.015. */ MAKE_CLEAR(MajTickLen,majticklen,AST__BAD,0) MAKE_SET(MajTickLen,double,majticklen,value,0) MAKE_TEST(MajTickLen,( this->majticklen[axis] != AST__BAD ),0) MAKE_GET(MajTickLen,double,0.0,( this->majticklen[axis] == AST__BAD ? 0.015 : this->majticklen[axis]),0) MAKE_SET3(MajTickLen,double,umjtkln,value,0) MAKE_GET3(MajTickLen,double,0.0,this->umjtkln[axis],0) /* TitleGap. */ /* --------- */ /* *att++ * Name: * TitleGap * Purpose: * Vertical spacing for a Plot title. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * where the title of a Plot is drawn. * * Its value gives the spacing between the bottom edge of the title * and the top edge of a bounding box containing all the other parts * of the annotated grid. Positive values cause the title to be * drawn outside the box, while negative values cause it to be drawn * inside. * * The TitleGap value should be given as a fraction of the minimum * dimension of the plotting area, the default value being +0.05. * Applicability: * Plot * All Plots have this attribute. * Plot3D * The Plot3D class ignores this attributes since it does not draw * a Title. * Notes: * - The text used for the title is obtained from the Plot's Title * attribute. *att-- */ /* Fractional gap between titile and top edge. Has a value of AST__BAD when not set yielding a default value of 0.05. */ astMAKE_CLEAR(Plot,TitleGap,titlegap,AST__BAD) astMAKE_GET(Plot,TitleGap,double,0.0,( this->titlegap == AST__BAD ? 0.05 : this->titlegap)) astMAKE_SET(Plot,TitleGap,double,titlegap,value) astMAKE_TEST(Plot,TitleGap,( this->titlegap != AST__BAD )) /* MinTickLen. */ /* ----------- */ /* *att++ * Name: * MinTickLen(axis) * Purpose: * Length of minor tick marks for a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the length of the minor tick marks drawn on the axes of a Plot. * It takes a separate value for each physical axis of the Plot so * that, for instance, the setting "MinTickLen(2)=0" specifies the * length of the minor tick marks drawn on the second axis. * * The MinTickLen value should be given as a fraction of the * minimum dimension of the plotting area. Negative values cause * minor tick marks to be placed on the outside of the * corresponding grid line or axis (but subject to any clipping * imposed by the underlying graphics system), while positive * values cause them to be placed on the inside. * * The default value is +0.007. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The number of minor tick marks drawn is determined by the * Plot's MinTick(axis) attribute. * - If no axis is specified, (e.g. "MinTickLen" instead of * "MinTickLen(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or "test" * operation will use just the MinTickLen(1) value. *att-- */ /* Fractional length of minor tick marks. Has a value of AST__BAD when not set yielding a default value of 0.007. */ MAKE_CLEAR(MinTickLen,minticklen,AST__BAD,0) MAKE_SET(MinTickLen,double,minticklen,value,0) MAKE_TEST(MinTickLen,( this->minticklen[axis] != AST__BAD ),0) MAKE_GET(MinTickLen,double,0.0,( this->minticklen[axis] == AST__BAD ? 0.007 : this->minticklen[axis]),0) /* Labelling. */ /* ---------- */ /* *att++ * Name: * Labelling * Purpose: * Label and tick placement option for a Plot. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the strategy for placing numerical labels and tick marks for a Plot. * * If the Labelling value of a Plot is "exterior" (the default), then * numerical labels and their associated tick marks are placed * around the edges of the plotting area, if possible. If this is * not possible, or if the Labelling value is "interior", then they * are placed along grid lines inside the plotting area. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The LabelAt(axis) attribute may be used to determine the exact * placement of labels and tick marks that are drawn inside the * plotting area. *att-- */ astMAKE_CLEAR(Plot,Labelling,labelling,-9999) astMAKE_SET(Plot,Labelling,int,labelling,(value?1:0)) astMAKE_TEST(Plot,Labelling,( this->labelling != -9999 )) astMAKE_GET(Plot,Labelling,int,0,(this->labelling == -9999 ? 0 : this->labelling)) MAKE_SET2(Plot,Labelling,int,ulbling,(value?1:0)) MAKE_GET2(Plot,Labelling,int,0,this->ulbling) /* Edge. */ /* ----- */ /* *att++ * Name: * Edge(axis) * Purpose: * Which edges to label in a Plot * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * which edges of a Plot are used for displaying numerical and * descriptive axis labels. It takes a separate value for each * physical axis of the Plot so that, for instance, the setting * "Edge(2)=left" specifies which edge to use to display labels for * the second axis. * * The values "left", "top", "right" and "bottom" (or any * abbreviation) can be supplied for this attribute. The default is * usually "bottom" for the first axis and "left" for the second * axis. However, if exterior labelling was requested (see the * Labelling attribute) but cannot be produced using these default * Edge values, then the default values will be swapped if this * enables exterior labelling to be produced. * Applicability: * Plot * All Plots have this attribute. * Plot3D * The Plot3D class ignores this attributes. Instead it uses its * own RootCorner attribute to determine which edges of the 3D plot * to label. * Notes: * - In some circumstances, numerical labels will be drawn along * internal grid lines instead of at the edges of the plotting area * (see the Labelling attribute). In this case, the Edge attribute * only affects the placement of the descriptive labels (these are * drawn at the edges of the plotting area, rather than along the * axis lines). *att-- */ /* The edges of the plotting area on which to place numerical labels for axes 0 and 1. Has a value of -1 when not set yielding a value of 3 (the bottom edge) for axis 0 and 0 (the left-hand edge) for axis 1. */ MAKE_CLEAR(Edge,edge,-1,0) MAKE_GET(Edge,int,0,( this->edge[axis] == -1 ? (axis?LEFT:BOTTOM) : this->edge[axis] ),0) MAKE_SET(Edge,int,edge,(abs( value % 4 )),0) MAKE_TEST(Edge,( this->edge[axis] != -1 ),0) MAKE_GET3(Edge,int,0,this->uedge[axis],0) MAKE_SET3(Edge,int,uedge,(abs( value % 4 )),0) /* NumLab. */ /* -------- */ /* *att++ * Name: * NumLab(axis) * Purpose: * Draw numerical axis labels for a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether labels should be drawn to represent the numerical values * along each axis of a Plot. It takes a separate value for each * physical axis of a Plot so that, for instance, the setting * "NumLab(2)=1" specifies that numerical labels should be drawn * for the second axis. * * If the NumLab value of a Plot axis is non-zero (the default), * then numerical labels will be drawn for that axis, otherwise * they will be omitted. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The drawing of associated descriptive axis labels for a Plot * (describing the quantity being plotted along each axis) is * controlled by the TextLab(axis) attribute. * - If no axis is specified, (e.g. "NumLab" instead of * "NumLab(2)"), then a "set" or "clear" operation will affect the * attribute value of all the Plot axes, while a "get" or "test" * operation will use just the NumLab(1) value. *att-- */ /* Are numerical labels to be displayed on each axis? Has a value of -1 when not set yielding a value of 1 (yes) for both axes. */ MAKE_CLEAR(NumLab,numlab,-1,0) MAKE_GET(NumLab,int,1,( this->numlab[axis] == -1 ? 1 : this->numlab[axis] ),0) MAKE_TEST(NumLab,( this->numlab[axis] != -1 ),0) MAKE_SET(NumLab,int,numlab,( value ? 1 : 0 ),0) /* NumLabGap. */ /* --------- */ /* *att++ * Name: * NumLabGap(axis) * Purpose: * Spacing of numerical labels for a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * where numerical axis labels are placed relative to the axes they * describe. It takes a separate value for each physical axis of a * Plot so that, for instance, the setting "NumLabGap(2)=-0.01" * specifies where the numerical label for the second axis should * be drawn. * * For each axis, the NumLabGap value gives the spacing between the * axis line (or edge of the plotting area, if appropriate) and the * nearest edge of the corresponding numerical axis * labels. Positive values cause the descriptive label to be placed * on the opposite side of the line to the default tick marks, * while negative values cause it to be placed on the same side. * * The NumLabGap value should be given as a fraction of the minimum * dimension of the plotting area, the default value being +0.01. * Applicability: * Plot * All Plots have this attribute. * Notes: * - If no axis is specified, (e.g. "NumLabGap" instead of * "NumLabGap(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the NumLabGap(1) value. *att-- */ /* Fractional spacing between numeric labels and axes. Has a value of AST__BAD when not set yielding a default value of 0.01. */ MAKE_CLEAR(NumLabGap,numlabgap,AST__BAD,0) MAKE_GET(NumLabGap,double,0.0,( this->numlabgap[ axis ] == AST__BAD ? 0.01 : this->numlabgap[axis]),0) MAKE_SET(NumLabGap,double,numlabgap,value,0) MAKE_TEST(NumLabGap,( this->numlabgap[axis] != AST__BAD ),0) /* MinTick. */ /* -------- */ /* *att++ * Name: * MinTick(axis) * Purpose: * Density of minor tick marks for a Plot. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * the density of minor tick marks which appear between the major * axis values of a Plot. It takes a separate value for each * physical axis of a Plot so that, for instance, the setting * "MinTick(2)=2" specifies the density of minor tick marks along * the second axis. * * The value supplied should be the number of minor divisions * required between each pair of major axis values, this being one * more than the number of minor tick marks to be drawn. By * default, a value is chosen that depends on the gap between major * axis values and the nature of the axis. * Applicability: * Plot * All Plots have this attribute. * Notes: * - If no axis is specified, (e.g. "MinTick" instead of * "MinTick(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the MinTick(1) value. *att-- */ /* How many divisions are there between major tick marks? Has a value of -1 when not set yielding a value of 1 for both axes. */ MAKE_CLEAR(MinTick,mintick,-1,0) MAKE_GET(MinTick,int,1,( this->mintick[axis] == -1 ? 1 : this->mintick[axis] ),0) MAKE_TEST(MinTick,( this->mintick[axis] != -1 ),0) MAKE_SET(MinTick,int,mintick,( (value < 1)? 1 : value ),0) MAKE_GET3(MinTick,int,1,this->umintk[axis],0) MAKE_SET3(MinTick,int,umintk,( (value < 1)? 1 : value ),0) /* TextLab. */ /* --------- */ /* *att++ * Name: * TextLab(axis) * Purpose: * Draw descriptive axis labels for a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether textual labels should be drawn to describe the quantity * being represented on each axis of a Plot. It takes a separate * value for each physical axis of a Plot so that, for instance, * the setting "TextLab(2)=1" specifies that descriptive labels * should be drawn for the second axis. * * If the TextLab value of a Plot axis is non-zero, then * descriptive labels will be drawn for that axis, otherwise they * will be omitted. The default behaviour is to draw descriptive * labels if tick marks and numerical labels are being drawn around * the edges of the plotting area (see the Labelling attribute), * but to omit them otherwise. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The text used for the descriptive labels is derived from the * Plot's Label(axis) attribute, together with its Unit(axis) * attribute if appropriate (see the LabelUnits(axis) attribute). * - The drawing of numerical axis labels for a Plot (which * indicate values on the axis) is controlled by the NumLab(axis) * attribute. * - If no axis is specified, (e.g. "TextLab" instead of * "TextLab(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the TextLab(1) value. *att-- */ /* Are textual labels to be displayed on each axis? Has a value of -1 when not set yielding a value of 1 (yes) for both axes. */ MAKE_CLEAR(TextLab,textlab,-1,0) MAKE_GET(TextLab,int,1,( this->textlab[axis] == -1 ? 1 : this->textlab[axis] ),0) MAKE_TEST(TextLab,( this->textlab[axis] != -1 ),0) MAKE_SET(TextLab,int,textlab,( value ? 1 : 0 ),0) MAKE_GET3(TextLab,int,1,this->utxtlb[axis],0) MAKE_SET3(TextLab,int,utxtlb,( value ? 1 : 0 ),0) /* TextLabGap. */ /* ----------- */ /* *att++ * Name: * TextLabGap(axis) * Purpose: * Spacing of descriptive axis labels for a Plot. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * where descriptive axis labels are placed relative to the axes they * describe. It takes a separate value for each physical axis of a * Plot so that, for instance, the setting "TextLabGap(2)=0.01" * specifies where the descriptive label for the second axis should * be drawn. * * For each axis, the TextLabGap value gives the spacing between the * descriptive label and the edge of a box enclosing all other parts * of the annotated grid (excluding other descriptive labels). The gap * is measured to the nearest edge of the label (i.e. the top or the * bottom). Positive values cause the descriptive label to be placed * outside the bounding box, while negative values cause it to be placed * inside. * * The TextLabGap value should be given as a fraction of the minimum * dimension of the plotting area, the default value being +0.01. * Applicability: * Plot * All Plots have this attribute. * Notes: * - If drawn, descriptive labels are always placed at the edges of * the plotting area, even although the corresponding numerical * labels may be drawn along axis lines in the interior of the * plotting area (see the Labelling attribute). * - If no axis is specified, (e.g. "TextLabGap" instead of * "TextLabGap(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the TextLabGap(1) value. *att-- */ /* Fractional spacing between numeric labels and axes. Has a value of AST__BAD when not set yielding a default value of 0.01. */ MAKE_CLEAR(TextLabGap,textlabgap,AST__BAD,0) MAKE_GET(TextLabGap,double,0.0,( this->textlabgap[ axis ] == AST__BAD ? 0.01 : this->textlabgap[axis]),0) MAKE_SET(TextLabGap,double,textlabgap,value,0) MAKE_TEST(TextLabGap,( this->textlabgap[axis] != AST__BAD ),0) /* LabelUnits. */ /* ----------- */ /* *att++ * Name: * LabelUnits(axis) * Purpose: * Use axis unit descriptions in a Plot? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls the appearance of an annotated c coordinate grid (drawn with the astGrid function) by determining f coordinate grid (drawn with the AST_GRID routine) by determining * whether the descriptive labels drawn for each axis of a Plot * should include a description of the units being used on the * axis. It takes a separate value for each physical axis of a * Plot so that, for instance, the setting "LabelUnits(2)=1" * specifies that a unit description should be included in the * label for the second axis. * * If the LabelUnits value of a Plot axis is non-zero, a unit * description will be included in the descriptive label for that * axis, otherwise it will be omitted. The default behaviour is to * include a unit description unless the current Frame of the Plot * is a SkyFrame representing equatorial, ecliptic, galactic or * supergalactic coordinates, in which case it is omitted. * Applicability: * Plot * All Plots have this attribute. * Notes: * - The text used for the unit description is obtained from the * Plot's Unit(axis) attribute. * - If no axis is specified, (e.g. "LabelUnits" instead of * "LabelUnits(2)"), then a "set" or "clear" operation will affect * the attribute value of all the Plot axes, while a "get" or * "test" operation will use just the LabelUnits(1) value. * - If the current Frame of the Plot is not a SkyFrame, but includes * axes which were extracted from a SkyFrame, then the default behaviour * is to include a unit description only for those axes which were not * extracted from a SkyFrame. *att-- */ /* Are textual labels to include a string describing the axis units? Has a value of -1 when not set yielding a default of 1. */ MAKE_CLEAR(LabelUnits,labelunits,-1,0) MAKE_TEST(LabelUnits,( this->labelunits[axis] != -1 ),0) MAKE_SET(LabelUnits,int,labelunits,( value ? 1 : 0 ),0) MAKE_GET3(LabelUnits,int,1,this->ulbunit[axis],0) MAKE_SET3(LabelUnits,int,ulbunit,( value ? 1 : 0 ),0) /* Style. */ /* ------ */ /* *att++ * Name: * Style(element) * Purpose: * Line style for a Plot element. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute determines the line style used when drawing each * element of graphical output produced by a Plot. It takes a * separate value for each graphical element so that, for instance, * the setting "Style(border)=2" causes the Plot border to be drawn * using line style 2 (which might result in, say, a dashed line). * * The range of integer line styles available and their appearance * is determined by the underlying graphics system. The default * behaviour is for all graphical elements to be drawn using the * default line style supplied by this graphics system (normally, * this is likely to give a solid line). * Applicability: * Plot * All Plots have this attribute. * Notes: * - For a list of the graphical elements available, see the * description of the Plot class. * - If no graphical element is specified, (e.g. "Style" instead of * "Style(border)"), then a "set" or "clear" operation will affect * the attribute value of all graphical elements, while a "get" or * "test" operation will use just the Style(Border) value. *att-- */ /* Line styles. Has a value of -1 when not set yielding a default of 1. */ MAKE_CLEAR(Style,style,-1,AST__NPID) MAKE_GET(Style,int,1,( this->style[axis] == -1 ? 1 : this->style[axis] ),AST__NPID) MAKE_TEST(Style,( this->style[axis] != -1 ),AST__NPID) MAKE_SET(Style,int,style,value,AST__NPID) /* Font. */ /* ----- */ /* *att++ * Name: * Font(element) * Purpose: * Character font for a Plot element. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute determines the character font index used when * drawing each element of graphical output produced by a Plot. It * takes a separate value for each graphical element so that, for * instance, the setting "Font(title)=2" causes the Plot title to * be drawn using font number 2. * * The range of integer font indices available and the appearance * of the resulting text is determined by the underlying graphics * system. The default behaviour is for all graphical elements to * be drawn using the default font supplied by this graphics * system. * Applicability: * Plot * All Plots have this attribute. * Notes: * - For a list of the graphical elements available, see the * description of the Plot class. * - If no graphical element is specified, (e.g. "Font" instead * of "Font(title)"), then a "set" or "clear" operation will * affect the attribute value of all graphical elements, while a * "get" or "test" operation will use just the Font(TextLab) * value. *att-- */ /* Character fonts. Has a value of -1 when not set yielding a default of 1. */ MAKE_CLEAR(Font,font,-1,AST__NPID) MAKE_GET(Font,int,1,( this->font[axis] == -1 ? 1 : this->font[axis] ),AST__NPID) MAKE_TEST(Font,( this->font[axis] != -1 ),AST__NPID) MAKE_SET(Font,int,font,value,AST__NPID) /* Colour. */ /* ------- */ /* *att++ * Name: * Colour(element) * Purpose: * Colour index for a Plot element. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute determines the colour index used when drawing * each element of graphical output produced by a Plot. It takes a * separate value for each graphical element so that, for instance, * the setting "Colour(title)=2" causes the Plot title to be drawn * using colour index 2. The synonym "Color" may also be used. * * The range of integer colour indices available and their * appearance is determined by the underlying graphics system. The * default behaviour is for all graphical elements to be drawn * using the default colour index supplied by this graphics system * (normally, this is likely to result in white plotting on a black * background, or vice versa). d * Applicability: * Plot * All Plots have this attribute. * Notes: * - For a list of the graphical elements available, see the * description of the Plot class. * - If no graphical element is specified, (e.g. "Colour" instead * of "Colour(title)"), then a "set" or "clear" operation will * affect the attribute value of all graphical elements, while a * "get" or "test" operation will use just the Colour(TextLab) * value. *att-- */ /* Colours. Has a value of -1 when not set yielding a default of 1. */ MAKE_CLEAR(Colour,colour,-1,AST__NPID) MAKE_GET(Colour,int,1,( this->colour[axis] == -1 ? 1 : this->colour[axis] ),AST__NPID) MAKE_TEST(Colour,( this->colour[axis] != -1 ),AST__NPID) MAKE_SET(Colour,int,colour,value,AST__NPID) /* Width. */ /* ------ */ /* *att++ * Name: * Width(element) * Purpose: * Line width for a Plot element. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute determines the line width used when drawing each * element of graphical output produced by a Plot. It takes a * separate value for each graphical element so that, for instance, * the setting "Width(border)=2.0" causes the Plot border to be * drawn using a line width of 2.0. A value of 1.0 results in a * line thickness which is approximately 0.0005 times the length of * the diagonal of the entire display surface. * * The actual appearance of lines drawn with any particular width, * and the range of available widths, is determined by the * underlying graphics system. The default behaviour is for all * graphical elements to be drawn using the default line width * supplied by this graphics system. This will not necessarily * correspond to a Width value of 1.0. * Applicability: * Plot * All Plots have this attribute. * Notes: * - For a list of the graphical elements available, see the * description of the Plot class. * - If no graphical element is specified, (e.g. "Width" instead of * "Width(border)"), then a "set" or "clear" operation will affect * the attribute value of all graphical elements, while a "get" or * "test" operation will use just the Width(Border) value. *att-- */ /* Line widths. Has a value of AST__BAD when not set yielding a default of 1.0. */ MAKE_CLEAR(Width,width,AST__BAD,AST__NPID) MAKE_GET(Width,double,1.0,( this->width[axis] == AST__BAD ? 1.0 : this->width[axis] ),AST__NPID) MAKE_TEST(Width,( this->width[axis] != AST__BAD ),AST__NPID) MAKE_SET(Width,double,width,(value!=0.00)?value:(astError(AST__ATTIN,"astSetWidth(Plot):Invalid zero value supplied for Width(%s) attribute", status,GrfItem(axis,NULL,NULL, status )),this->width[axis]),AST__NPID) /* Size. */ /* ----- */ /* *att++ * Name: * Size(element) * Purpose: * Character size for a Plot element. * Type: * Public attribute. * Synopsis: * Floating Point. * Description: * This attribute determines the character size used when drawing * each element of graphical output produced by a Plot. It takes a * separate value for each graphical element so that, for instance, * the setting "Size(title)=2.0" causes the Plot title to be drawn * using twice the default character size. * * The range of character sizes available and the appearance of the * resulting text is determined by the underlying graphics system. * The default behaviour is for all graphical elements to be drawn * using the default character size supplied by this graphics * system. * Applicability: * Plot * All Plots have this attribute. * Notes: * - For a list of the graphical elements available, see the * description of the Plot class. * - If no graphical element is specified, (e.g. "Size" instead * of "Size(title)"), then a "set" or "clear" operation will * affect the attribute value of all graphical elements, while a * "get" or "test" operation will use just the Size(TextLab) * value. *att-- */ /* Character sizes. Has a value of AST__BAD when not set yielding a default of 1.0. */ MAKE_CLEAR(Size,size,AST__BAD,AST__NPID) MAKE_GET(Size,double,1.0,( this->size[axis] == AST__BAD ? 1.0 : this->size[axis] ),AST__NPID) MAKE_TEST(Size,( this->size[axis] != AST__BAD ),AST__NPID) MAKE_SET(Size,double,size,(value!=0.00)?value:(astError(AST__ATTIN,"astSetSize(Plot): Invalid zero value supplied for Size(%s) attribute", status,GrfItem(axis,NULL,NULL, status )),this->size[axis]),AST__NPID) /* Member functions. */ /* ================= */ static void AddCdt( AstPlotCurveData *cdt1, AstPlotCurveData *cdt2, const char *method, const char *class, int *status ){ /* * * Name: * AddCdt * Purpose: * Append one AstPlotCurveData structure to another. * Type: * Private function. * Synopsis: * #include "plot.h" * void AddCdt( AstPlotCurveData *cdt1, AstPlotCurveData *cdt2, const char *method, * const char *class, int *status ) * Class Membership: * Plot private function. * Description: * The contents of the structure pointed to by "cdt2" is appended * to the structure pointed to by "cdt1". * Parameters: * cdt1 * Pointer to the AstPlotCurveData structure to be modified. * cdt2 * Pointer to the AstPlotCurveData structure to be appended to cdt1. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - An error is reported if there is insufficient room in "cdt1" to * store the information in "cdt2". */ /* Local Variables: */ int nbrk, i, j; /* Check the global error status. */ if ( !astOK ) return; /* Get the total number of breaks described by both structures. */ nbrk = cdt1->nbrk + cdt2->nbrk; /* Report an error if this number of breaks cannot be stored in a AstPlotCurveData structure. */ if( nbrk > AST__MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__MXBRK ); /* Otherwise, append the information. */ } else { /* Store the index within "cdt1" of the next break to be added. */ j = cdt1->nbrk; /* Add each the position and direction information for each of the breaks in "cdt2". */ for( i = 0; i < cdt2->nbrk; i++ ){ cdt1->xbrk[ j ] = cdt2->xbrk[ i ]; cdt1->ybrk[ j ] = cdt2->ybrk[ i ]; cdt1->vxbrk[ j ] = cdt2->vxbrk[ i ]; cdt1->vybrk[ j ] = cdt2->vybrk[ i ]; /* Increment the index of the next break in "cdt1". */ j++; } /* Update the number of breaks in "cdt1". */ cdt1->nbrk = nbrk; /* Update the length of the curve described by "cdt1". */ cdt1->length += cdt2->length; /* Update the flag indicating if the entire curve is outside the plotting zone. */ if( !cdt2->out ) cdt1->out = 0; } /* Return. */ return; } static void Apoly( AstPlot *this, float x, float y, int *status ){ /* * Name: * Apoly * Purpose: * Append a another point to a poly line. * Type: * Private function. * Synopsis: * #include "plot.h" * void Apoly( AstPlot *this, float x, float y, int *status ) * Class Membership: * Plot member function. * Description: * This function appends the supplied point to the current poly line. * Parameters: * x * The graphics x coordinate. * y * The graphics y coordinate. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int ipoint; astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Extend the buffers, and add the supplied point to the end. */ ipoint = Poly_n++; Poly_x = astGrow( Poly_x, Poly_n, sizeof(*Poly_x) ); Poly_y = astGrow( Poly_y, Poly_n, sizeof(*Poly_y) ); if( astOK ) { Poly_x[ ipoint ] = x; Poly_y[ ipoint ] = y; } /* Update the box containing all plotted lines. */ Box_lbnd[ 0 ] = astMIN( x, Box_lbnd[ 0 ] ); Box_ubnd[ 0 ] = astMAX( x, Box_ubnd[ 0 ] ); Box_lbnd[ 1 ] = astMIN( y, Box_lbnd[ 1 ] ); Box_ubnd[ 1 ] = astMAX( y, Box_ubnd[ 1 ] ); } static void AxPlot( AstPlot *this, int axis, const double *start, double length, int ink, AstPlotCurveData *cdata, const char *method, const char *class, int *status ){ /* * * Name: * AxPlot * Purpose: * Draw a curve with constant axis value. * Type: * Private function. * Synopsis: * #include "plot.h" * void AxPlot( AstPlot *this, int axis, const double *start, double length, * int ink, AstPlotCurveData *cdata, const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws a section of a curve of the specified length * with constant value on a specified axis in the current Frame of the * Plot, starting at the specified position. The algorithm used can handle * discontinuities in the Mapping between the current Frame and graphics * coordinates, and information describing any breaks in the curve * (including the start and end of the curve) are returned in the supplied * AstPlotCurveData structure. * Parameters: * this * Pointer to the Plot. * axis * The zero-based index of an axis within the current Frame of the Plot. * The curve has a varying value on this axis. * start * A pointer to a an array holding the coordinates of the start of the * curve within the current Frame of the Plot. * length * The length of the section of the curve to be drawn, given as an * increment along the axis specified by parameter "axis". * ink * If zero, the curve is not actually drawn, but information about * the breaks is still returned. If non-zero, the curve is also drawn. * cdata * A pointer to a structure in which to return information about the * breaks in the curve. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - No curve is draw if the "start" array contains any bad values * (i.e. values equal to AST__BAD), or if the "length" value is bad, * or if a NULL pointer is supplied for "cdata". No errors are reported * in these cases. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ double tol; /* Absolute tolerance value */ int i; /* Loop count */ int naxes; /* No. of axes in the base Frame */ int ok; /* Are all start coords good? */ int gridid; /* Identifier value for element being drawn */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); #ifdef CRV_TRACE printf("AXPLOT: axis %d, start (%.*g,%.*g), length %.*g\n", axis, DBL_DIG, start[0], DBL_DIG, start[1], DBL_DIG, length ); getchar(); #endif /* Initialise any supplied cdata structure to hold safe values. */ if( cdata ){ cdata->length = 0.0; cdata->out = 1; cdata->nbrk = 0; } /* Get the number of axes in the current Frame. */ naxes = astGetNout( this ); /* Check the "start" parameter for bad values. */ ok = 1; for( i = 0; i < naxes; i++ ) { if( start[ i ] == AST__BAD ){ ok = 0; break; } } /* Check the "length" parameter for bad values. */ if( length == AST__BAD ) ok = 0; /* Check that the "cdata" pointer can be used. */ if( !cdata ) ok = 0; /* Only proceed if the parameters are OK, and there has been no error. */ if( ok && astOK ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ if( axis == 0 ) { gridid = AST__GRIDLINE2_ID; } else { gridid = AST__GRIDLINE1_ID; } astGrfAttrs( this, gridid, 1, GRF__LINE, method, class ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Set up the externals used to communicate with the Map1 function... The number of axes in the physical coordinate system (i.e. the current Frame). */ Map1_ncoord = naxes; /* See if tick marks are logarithmically or linearly spaced. */ Map1_log = astGetLogTicks( this, axis ); /* A pointer to the Plot, the Current Frame and the Mapping. */ Map1_plot = this; Map1_frame = astGetFrame( this, AST__CURRENT ); Map1_map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Physical coords at the start of the curve (dist=0). */ Map1_origin = start; /* Length of the curve. */ Map1_length = length; /* The index of the axis which the curve follows. */ Map1_axis = axis; /* Decide whether to omit points not in their normal ranges. */ Map1_norm = !IsASkyAxis( Map1_frame, 0, status ) && !IsASkyAxis( Map1_frame, 1, status ); /* Convert the tolerance from relative to absolute graphics coordinates. */ tol = astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Now set up the external variables used by the Crv and CrvLine function. */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_ux0 = AST__BAD; Crv_tol = tol; Crv_limit = 0.5*tol*tol; Crv_map = Map1; Crv_ink = ink; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_out = 1; Crv_xbrk = cdata->xbrk; Crv_ybrk = cdata->ybrk; Crv_vxbrk = cdata->vxbrk; Crv_vybrk = cdata->vybrk; Crv_clip = astGetClip( this ) & 1; /* Set up a list of points spread evenly over the curve. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Map these points into graphics coordinates. */ Map1( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map1 to draw the curve. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* End the current poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map1. */ Map1( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* If no part of the curve could be drawn, set the number of breaks and the length of the drawn curve to zero. */ if( Crv_out ) { Crv_nbrk = 0; Crv_len = 0.0F; /* Otherwise, add an extra break to the returned structure at the position of the last point to be plotted. */ } else { Crv_nbrk++; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; } } /* Store extra information about the curve in the returned structure, and purge any zero length sections. */ if( cdata ){ cdata->length = Crv_len; cdata->out = Crv_out; cdata->nbrk = Crv_nbrk; PurgeCdata( cdata, status ); } /* Annul the Frame and Mapping. */ Map1_frame = astAnnul( Map1_frame ); Map1_map = astAnnul( Map1_map ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gridid, 0, GRF__LINE, method, class ); } /* Return. */ return; } static void BBuf( AstPlot *this, int *status ) { /* *++ * Name: c astBBuf f AST_BBUF * Purpose: * Begin a new graphical buffering context. * Type: * Public function. * Synopsis: c #include "plot.h" c void astBBuf( AstPlot *this ) f CALL AST_BBUF( THIS STATUS ) * Class Membership: * Plot member function. * Description: c This function f This routine * starts a new graphics buffering context. A matching call to the c function astEBuf f routine AST_EBUF * should be used to end the context. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The nature of the buffering is determined by the underlying * graphics system (as defined by the current grf module). Each call c to this function f to this routine c to this function f to this routine * simply invokes the astGBBuf function in the grf module. *-- */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the active GRF BBuf function. */ GBBuf( this, "astBBuf", astGetClass( this ), status ); } static int Boundary( AstPlot *this, const char *method, const char *class, int *status ){ /* * Name: * Boundary * Purpose: * Draw a boundary around regions containing valid physical positions. * Type: * Private function. * Synopsis: * #include "plot.h" * int Boundary( AstPlot *this, const char *method, const char *class, int *status ) * Class Membership: * Plot method. * Description: * This function draws a boundary around the regions of the plotting * area which contain valid, unclipped, physical coordinates, but does * not include the intersections with the edges of the plotting area. * * Broadly, the algorithm is as follows: An initial coarse grid is * created covering the entire plotting area. This grid consists of a * regular square matrix of points in graphics coordinates, and the * corresponding physical coordinates. An array of flags is created, * one for each grid cell, indicating if the boundary passes through the * cell. This is assumed to be the case if the cell has a mix of good and * bad corners (i.e corners which have good or bad physical coordinates). * This assumption does not locate all boundary cells though, since if * the boundary passes into and out of a cell throught the same edge, * the corners of the cell will be either all good or all bad. But for * the moment, we just concentrate on the ones found using this simple * assumption. For each such cell, a finer grid is then created covering * the cell, and the boundary is drawn through this fine grid using * TraceBorder. TraceBorder returns a set of four flags indicating which * edges of the cell were intersected by the boundary. A check is then * made on any of the four neighbouring cells into which the curve * passes. If any of these cells were not flagged as boundary cells using * the simple assumption described earlier, then they are flagged now * (with a different flag value). Once all the cells located using the * simple assumption have been processed, any further cells flagged * with the new flag value are also processed using TraceBorder in the * same way. This process is repeated until no extra boundary cells are * found. * Parameters: * this * Pointer to a Plot. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A flag indicating if any regions containing invalid physical * coordinates were found within the plotting area. * Notes: * - This function assumes the physical coordinate Frame is * 2-dimensional, and it should not be used if this is not the case. * - A value of zero is returned if an error has already occurred, or * if this function should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; /* Pointer to base Plot Frame */ AstFrame *cfrm; /* Pointer to current Plot Frame */ AstMapping *map; /* Pointer to Plot mapping (graphics -> physical) */ AstMapping *rmap; /* Pointer to Plot mapping (graphics -> physical) */ AstRegion *breg; /* Region mapped into base Plot Frame */ double blbnd[ 2 ]; /* Lower grid bounds in base frame */ double bubnd[ 2 ]; /* Upper grid bounds in base frame */ double dx; /* Plotting area width */ double dy; /* Plotting area height */ double power; /* Exponent in pow call */ double rat; /* Ratio by which to reduce DIM */ double tol; /* Fractional plotting tolerance */ int dim; /* No. of points along each edge of coarse grid */ int edges[ 4 ]; /* Flags indicating edges bisected by boundary */ int rate_disabled; /* Was the astRate method initially disabled? */ int ret; /* Any regions containing bad physical coords? */ /* Check global status. */ if( !astOK ) return 0; /* Initialise the answer to indicate that no regions containing invalid physical coordinates have been found. */ ret = 0; /* Get the current Frame from the Plot. */ cfrm = astGetFrame( this, AST__CURRENT ); /* If it is a region, we use a special method, if possible, to trace the Region boundary. Otherwise, we use a grid tracing method that makes no assumptions about the nature of the Mapping or Frame. */ if( !DrawRegion( this, cfrm, method, class, status ) ) { /* Each basic element of the boundary drawn by the following algorithm will be drawn at a multiple of 45 degrees to the horizontal. This can cause noticable aliasing. For instance, if the border is a straight line at 50 degrees to the horizontal, it will be drawn at 45 degrees for long sections, followed by a vertical leap to catch up with where it should be. Because of this we use a finer tolerance than for other drawing. */ tol = 0.25*astGetTol( this ); /* Set up the dimension of a coarse grid in graphics coordinates to cover the whole plotting area. This is chosen to give a finer grid for smaller plotting tolerances. Note, putting the power as a literal constant in the call to pow seems to cause a segmentation violation on some systems. */ power = -0.666666666; dim = (int) 4*pow( tol, power ) + 10; if( dim > 400 ) dim = 400; if( dim < 3 ) dim = 3; /* Store the required plotting tolerance as a distance in graphics coords. */ dx = fabs( this->xhi - this->xlo ); dy = fabs( this->xhi - this->xlo ); tol *= ( ( dx > dy ) ? dx : dy ); /* Extract the Mapping from the Plot. */ map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Select the area covered by the coarse grid. If the current Frame is a Region, we use the bounding box of Region after being mapped into graphics coords. */ if( astIsARegion( cfrm ) ) { bfrm = astGetFrame( this, AST__BASE ); /* Get the Mapping from the current to the base Frame in the Plot, and remove the effects of any Regions. */ astInvert( map ); rmap = astRemoveRegions( map ); astInvert( map ); /* Map the Region into the GRAPHICS frame. */ breg = astMapRegion( cfrm, rmap, bfrm ); astGetRegionBounds( breg, blbnd, bubnd ); rmap = astAnnul( rmap ); bfrm = astAnnul( bfrm ); breg = astAnnul( breg ); rat = ( ( bubnd[ 0 ] - blbnd[ 0 ] )*( bubnd[ 1 ] - blbnd[ 1 ] ) )/ ( ( this->xhi - this->xlo )*( this->yhi - this->ylo ) ); rat = sqrt( rat ); dim = (int) ( rat*dim ); if( dim < 3 ) dim = 3; /* If the current Frame is not a Region, use the whole plot. */ } else { blbnd[ 0 ] = this->xlo; blbnd[ 1 ] = this->ylo; bubnd[ 0 ] = this->xhi; bubnd[ 1 ] = this->yhi; } /* Disable the astRate method in order to improve the speed of evaluating the Mapping in cases where the Mapping includes an AstRateMap. Note the original value of the flag so that it can be re-instated at the end. */ rate_disabled = astRateState( 1 ); /* Draw the boundary. */ ret = TraceBorder( this, map, blbnd[ 0 ], bubnd[ 0 ], blbnd[ 1 ], bubnd[ 1 ], dim, tol, edges, method, class, status ); /* Re-instate the original setting of the "astRate disabled" flag. */ astRateState( rate_disabled ); /* Release the remaining resources. */ map = astAnnul( map ); } cfrm = astAnnul( cfrm ); /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static int Border( AstPlot *this_nd, int *status ){ /* *++ * Name: c astBorder f AST_BORDER * Purpose: * Draw a border around valid regions of a Plot. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c int astBorder( AstPlot *this ) f RESULT = AST_BORDER( THIS, STATUS ) * Class Membership: * Plot method. * Description: * This function draws a (line) border around regions of the * plotting area of a Plot which correspond to valid, unclipped * physical coordinates. For example, when plotting using an * all-sky map projection, this function could be used to draw the * boundary of the celestial sphere when it is projected on to the * plotting surface. * * If the entire plotting area contains valid, unclipped physical * coordinates, then the boundary will just be a rectangular box * around the edges of the plotting area. * * If the Plot is a Plot3D, this method is applied individually to * each of the three 2D Plots encapsulated within the Plot3D (each of * these Plots corresponds to a single 2D plane in the 3D graphics * system). In addition, if the entire plotting volume has valid * coordinates in the 3D current Frame of the Plot3D, then additional * lines are drawn along the edges of the 3D plotting volume so that * the entire plotting volume is enclosed within a cuboid grid. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astBorder() f AST_BORDER = LOGICAL c Zero is returned if the plotting space is completely filled by f .FALSE. is returned if the plotting space is completely filled by * valid, unclipped physical coordinates (so that only a c rectangular box was drawn around the edge). Otherwise, one is f rectangular box was drawn around the edge). Otherwise, .TRUE. is * returned. * Notes: c - A value of zero will be returned if this function is invoked f - A value of .FALSE. will be returned if this function is invoked c with the AST error status set, or if it should fail for any f with STATUS set to an error value, or if it should fail for any * reason. * - An error results if either the current Frame or the base Frame * of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. * - An error also results if the transformation between the base * and current Frames of the Plot is not defined (i.e. the Plot's * TranForward attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPlot *this; /* Plot with no more than 2 current axes */ AstPlotCurveData cdata; /* Structure to receive break information */ const char *class; /* Object class */ const char *method; /* Current method */ int inval; /* Were any bad regions found? */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_nd); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astBorder"; class = astGetClass( this_nd ); /* Initialise the bounding box for primitives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this_nd ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Get a Plot with a 2D (or 1D) current Frame. */ this = (AstPlot *) Fset2D( (AstFrameSet *) this_nd, AST__CURRENT, status ); /* Check the current Frame of the Plot is 2-D. */ naxes = astGetNout( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the current " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__BORDER_ID, 1, GRF__LINE, method, class ); /* We first draw the intersections of the regions containing valid physical coordinates with the edges of the plotting area. First do the bottom edge. */ LinePlot( this, this->xlo, this->ylo, this->xhi, this->ylo, 1, &cdata, method, class, status ); /* Now do the right-hand edge. */ LinePlot( this, this->xhi, this->ylo, this->xhi, this->yhi, 1, &cdata, method, class, status ); /* Now do the top edge. */ LinePlot( this, this->xhi, this->yhi, this->xlo, this->yhi, 1, &cdata, method, class, status ); /* Now do the left-hand edge. */ LinePlot( this, this->xlo, this->yhi, this->xlo, this->ylo, 1, &cdata, method, class, status ); /* Now draw a curve following the boundary through the interior of the plotting area. If the current Frame in the Plot is a Region, we use a shorter method if possible. If this is not possible, we use a longer method. */ inval = Boundary( this, method, class, status ); /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__BORDER_ID, 0, GRF__LINE, method, class ); /* Annul the 2d plot. */ this = astAnnul( this ); /* Return. */ return inval; } static void BoundingBox( AstPlot *this, float lbnd[2], float ubnd[2], int *status ){ /* *++ * Name: c astBoundingBox f AST_BOUNDINGBOX * Purpose: * Return a bounding box for previously drawn graphics. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astBoundingBox( AstPlot *this, float lbnd[2], float ubnd[2] ) f CALL AST_BOUNDINGBOX( THIS, LBND, UBND, STATUS ) * Class Membership: * Plot method. * Description: c This function returns the bounds of a box which just encompasess the f This routine returns the bounds of a box which just encompasess the * graphics produced by the previous call to any of the Plot methods * which produce graphical output. If no such previous call has yet * been made, or if the call failed for any reason, then the bounding box c returned by this function is undefined. f returned by this routine is undefined. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c lbnd f LBND( 2 ) = REAL (Returned) * A two element array in which is returned the lower limits of the * bounding box on each of the two axes of the graphics coordinate * system (the base Frame of the Plot). c ubnd f UBND( 2 ) = REAL (Returned) * A two element array in which is returned the upper limits of the * bounding box on each of the two axes of the graphics coordinate * system (the base Frame of the Plot). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - An error results if the base Frame of the Plot is not * 2-dimensional. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrameSet *fset; /* Pointer to the Plot's FrameSet */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Get a pointer to the FrameSet at the start of the Plot. */ fset = (AstFrameSet *) this; /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( fset ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "astBoundingBox(%s): Number of axes (%d) in the " "base Frame of the supplied %s is invalid - this number " "should be 2.", status, astGetClass( this ), naxes, astGetClass( this ) ); } /* Return the bounding box. */ lbnd[ 0 ] = Boxp_lbnd[ 0 ]; lbnd[ 1 ] = Boxp_lbnd[ 1 ]; ubnd[ 0 ] = Boxp_ubnd[ 0 ]; ubnd[ 1 ] = Boxp_ubnd[ 1 ]; /* Return. */ return; } static int BoxCheck( float *bx, float *by, float *cx, float *cy, int *status ) { /* * Name: * BoxCheck * Purpose: * See if two boxes overlap. * Type: * Private function. * Synopsis: * #include "plot.h" * int BoxCheck( float *bx, float *by, float *cx, float *cy, int *status ) * Class Membership: * Plot method. * Description: * This function returns a flag indicating if two trapezoidal boxes * (box "b" and box "c") overlap or not. * Parameters: * bx * Pointer to an array holding the X coordinates at the 4 corners * of box "b". * by * Pointer to an array holding the Y coordinates at the 4 corners * of box "b". * cx * Pointer to an array holding the X coordinates at the 4 corners * of box "c". * cy * Pointer to an array holding the Y coordinates at the 4 corners * of box "c". * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the boxes do not overlap or an error has * already occurred. Otherwise, 1 is returned. */ /* Local Variables: */ float x2; float y2; int i; int ip; int j; int jp; int ret; /* Assume the boxes do not overlap. */ ret = 0; /* Check the inherited status. */ if( !astOK ) return ret; /* Check each corner of box b to see if it is inside box c. */ for( j = 0; j < 4 && ret == 0; j++ ){ if( Inside( 4, cx, cy, bx[ j ], by[ j ], status ) ) ret = 1; } /* Now check each corner of box c to see if it is inside box b. */ for( j = 0; j < 4 && ret == 0; j++ ){ if( Inside( 4, bx, by, cx[ j ], cy[ j ], status ) ) ret = 1; } /* If no overlap has yet been found, we need to see if any of the edges of the boxes intersect. For instance, in the case of a cross formed by a vertical rectangle crossing a horizontal rectangle, the above checks on the corners would not have revealed any overlap. */ if( !ret ) { /* The following code assumes that the corners with indices 0, 1, 2, 3 are adjacent round the edge of the box. This is the case if the line joining corners 0 and 1 does not cross the line joining corners 2 and 3 AND the line joining corners 1 and 2 does not cross the line joining corners 3 and 0. If either of these conditions is not met swap the corners around to correct it. First do box b. */ if( Cross( bx[0], by[0], bx[1], by[1], bx[2], by[2], bx[3], by[3], status ) ) { x2 = bx[2]; y2 = by[2]; bx[2] = bx[1]; by[2] = by[1]; bx[1] = x2; by[1] = y2; } else if( Cross( bx[1], by[1], bx[2], by[2], bx[3], by[3], bx[0], by[0], status ) ) { x2 = bx[2]; y2 = by[2]; bx[2] = bx[3]; by[2] = by[3]; bx[3] = x2; by[3] = y2; } /* Now do box c. */ if( Cross( cx[0], cy[0], cx[1], cy[1], cx[2], cy[2], cx[3], cy[3], status ) ) { x2 = cx[2]; y2 = cy[2]; cx[2] = cx[1]; cy[2] = cy[1]; cx[1] = x2; cy[1] = y2; } else if( Cross( cx[1], cy[1], cx[2], cy[2], cx[3], cy[3], cx[0], cy[0], status ) ) { x2 = cx[2]; y2 = cy[2]; cx[2] = cx[3]; cy[2] = cy[3]; cx[3] = x2; cy[3] = y2; } /* We now check each edge of box b to see if it overlaps any edge of box c. */ for( j = 0; j < 4 && ret == 0; j++ ) { /* This edge of box b starts at the corner with index j. Get the index of the corner at which the edge ends. */ jp = j + 1; if( jp == 4 ) jp = 0; /* Check to see if this edge of box b crosses each edge of box c in turn. */ for( i = 0; i < 4 && ret == 0; i++ ) { ip = i + 1; if( ip == 4 ) ip = 0; ret = Cross( bx[j], by[j], bx[jp], by[jp], cx[i], cy[i], cx[ip], cy[ip], status ); } } } return ret; } static void Bpoly( AstPlot *this, float x, float y, int *status ){ /* * Name: * Bpoly * Purpose: * Begin a new poly line. * Type: * Private function. * Synopsis: * #include "plot.h" * void Bpoly( AstPlot *this, float x, float y, int *status ) * Class Membership: * Plot member function. * Description: * This function draws any current poly line, and then starts a new one * at the supplied position. * Parameters: * x * The graphics x coordinate. * y * The graphics y coordinate. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int ignore; /* Is the new point the end of the current polyline? */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* See if the new point is co-incident with the end of the current polyline. If so we assume the current polyline is to be re-started, rather than starting a new polyline. */ if( Poly_n > 0 ) { ignore = ( astEQUALS( Poly_x[ Poly_n - 1 ], x, 1.0E8 ) && astEQUALS( Poly_y[ Poly_n - 1 ], y, 1.0E8 ) ); } else { ignore = 0; } /* If the supplied point is not at the end of the current polyline, draw any existing poly line. This will empty the buffer. Then add the supplied point into the buffer. */ if( !ignore ) { Opoly( this, status ); Apoly( this, x, y, status ); } } static int CGCapWrapper( AstPlot *this, int cap, int value, int *status ) { /* * * Name: * CGCapWrapper * Purpose: * Call a C implementation of the GCap Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGCapWrapper( AstPlot *this, int cap, int value, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GCap * grf function to enquire or set a graphics attribute value. * Parameters: * this * The Plot. * cap * The capability to be inquired aboue. * value * The value ot assign to the capability. * status * Pointer to the inherited status value. * Returned Value: * Non-zero if the grf module is capabale of performing the action * requested by "cap". */ if( !astOK ) return 0; return ( (AstGCapFun) this->grffun[ AST__GCAP ] )( astGrfConID(this), cap, value ); } static int CGAttrWrapper( AstPlot *this, int attr, double value, double *old_value, int prim, int *status ) { /* * * Name: * CGAttrWrapper * Purpose: * Call a C implementation of the GAttr Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGAttrWrapper( AstPlot *this, int attr, double value, * double *old_value, int prim, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GAttr * grf function to enquire or set a graphics attribute value. * Parameters: * this * The Plot. * attr * An integer value identifying the required attribute. The * following symbolic values are defined in grf.h: * * GRF__STYLE - Line style. * GRF__WIDTH - Line width. * GRF__SIZE - Character and marker size scale factor. * GRF__FONT - Character font. * GRF__COLOUR - Colour index. * value * A new value to store for the attribute. If this is AST__BAD * no value is stored. * old_value * A pointer to a double in which to return the attribute value. * If this is NULL, no value is returned. * prim * The sort of graphics primitive to be drawn with the new attribute. * Identified by the following values defined in grf.h: * GRF__LINE * GRF__MARK * GRF__TEXT * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGAttrFun) this->grffun[ AST__GATTR ] )( astGrfConID(this), attr, value, old_value, prim ); } static int CGBBufWrapper( AstPlot *this, int *status ) { /* * * Name: * CGBBufWrapper * Purpose: * Call a C implementation of the GBBuf Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGBBufWrapper( AstPlot *this ) { * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GBBuf * grf function to start a new graphics context. * Parameters: * this * The Plot. * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGBBufFun) this->grffun[ AST__GBBUF ])( astGrfConID(this) ); } static int CGEBufWrapper( AstPlot *this, int *status ) { /* * * Name: * CGEBufWrapper * Purpose: * Call a C implementation of the GEBuf Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGEBufWrapper( AstPlot *this ) { * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GEBuf * grf function to start a new graphics context. * Parameters: * this * The Plot. * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGEBufFun) this->grffun[ AST__GEBUF ])( astGrfConID(this) ); } static int CGFlushWrapper( AstPlot *this, int *status ) { /* * * Name: * CGFlushWrapper * Purpose: * Call a C implementation of the GFlush Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGFlushWrapper( AstPlot *this ) { * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GFlush * grf function to flush graphics. * Parameters: * this * The Plot. * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGFlushFun) this->grffun[ AST__GFLUSH ])( astGrfConID(this) ); } static int CGLineWrapper( AstPlot *this, int n, const float *x, const float *y, int *status ) { /* * * Name: * CGLineWrapper * Purpose: * Call a C implementation of the GLine Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGLineWrapper( AstPlot *this, int n, const float *x, * const float *y, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GLine * grf function to draw a polyline. * Parameters: * this * The Plot. * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * status * Pointer to the inherited status variable. */ if( !astOK ) return 0; return ( (AstGLineFun) this->grffun[ AST__GLINE ])( astGrfConID(this), n, x, y ); } static int CGMarkWrapper( AstPlot *this, int n, const float *x, const float *y, int type, int *status ) { /* * * Name: * CGMarkWrapper * Purpose: * Call a C implementation of the GMark Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGMarkWrapper( AstPlot *this, int n, const float *x, * const float *y, int type, int *status ) { * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GMark grf * function to draw markers. * Parameters: * this * The Plot. * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * type * An integer which can be used to indicate the type of marker symbol * required. * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGMarkFun) this->grffun[ AST__GMARK ])( astGrfConID(this), n, x, y, type ); } static int CGTextWrapper( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy, int *status ) { /* * * Name: * CGTextWrapper * Purpose: * Call a C implementation of the GText Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGTextWrapper( AstPlot *this, const char *text, float x, float y, * const char *just, float upx, float upy, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GText grf * function to draw a text string. * Parameters: * this * The Plot. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGTextFun) this->grffun[ AST__GTEXT ])( astGrfConID(this), text, x, y, just, upx, upy ); } static int CGTxExtWrapper( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb, int *status ) { /* * * Name: * CGTxExtWrapper * Purpose: * Call a C implementation of the GTxExt Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGTxExtWrapper( AstPlot *this, const char *text, float x, float y, * const char *just, float upx, float upy, float *xb, * float *yb, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GTxExt * grf function to find the extent of a text string. * Parameters: * this * The Plot. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * xb * An array of 4 elements in which to return the x coordinate of * each corner of the bounding box. * yb * An array of 4 elements in which to return the y coordinate of * each corner of the bounding box. * status * Pointer to the inherited status variable. */ if( !astOK ) return 0; return ( (AstGTxExtFun) this->grffun[ AST__GTXEXT ])( astGrfConID(this), text, x, y, just, upx, upy, xb, yb ); } static int CGQchWrapper( AstPlot *this, float *chv, float *chh, int *status ) { /* * * Name: * CGQchWrapper * Purpose: * Call a C implementation of the GQch Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGQchWrapper( AstPlot *this, float *chv, float *chh, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GQch * grf function to find the extent of a text string. * Parameters: * this * The Plot. * chv * A pointer to the double which is to receive the height of * characters drawn vertically. This will be an increment in the X * axis * chh * A pointer to the double which is to receive the height of * characters drawn vertically. This will be an increment in the Y * axis * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGQchFun) this->grffun[ AST__GQCH ])( astGrfConID(this), chv, chh ); } static int CGScalesWrapper( AstPlot *this, float *alpha, float *beta, int *status ) { /* * * Name: * CGScalesWrapper * Purpose: * Call a C implementation of the GScales Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int CGScalesWrapper( AstPlot *this, float *alpha, float *beta, int *status ) * Class Membership: * Plot private function. * Description: * This function is a wrapper for a C implementation of the GScales * grf function to find the extent of a text string. * Parameters: * this * The Plot. * alpha * A pointer to the location at which to return the scale for the * X axis (i.e. Xnorm = alpha*Xworld). * beta * A pointer to the location at which to return the scale for the * Y axis (i.e. Ynorm = beta*Yworld). * status * Pointer to the inherited status value. */ if( !astOK ) return 0; return ( (AstGScalesFun) this->grffun[ AST__GSCALES ])( astGrfConID(this), alpha, beta ); } static int CheckLabels( AstPlot *this, AstFrame *frame, int axis, double *ticks, int nticks, int force, char **list, double refval, int *status ){ /* * Name: * CheckLabels * Purpose: * Create tick mark labels and check that adjacent labels are different. * Type: * Private function. * Synopsis: * #include "plot.h" * int CheckLabels( AstPlot *this, AstFrame *frame, int axis, double *ticks, * int nticks, int force, char **list, double refval, int *status ) * Class Membership: * Plot member function. * Description: * This function formats the supplied ticks mark values using the * astFormat method for the supplied Frame. Unless force is non-zero, it * then checks all pairs of adjacent labels. If a pair is found which are * identical then the memory holding the labels is released, and a value * of zero is returned. Otherwise, a value of one is returned, indicating * that adjacent labels are all different and the labels are returned. * Parameters: * this * Pointer to the Plot. * frame * Pointer to the Frame. * axis * The zero-based index of the axis to which the tick marks refer. * ticks * Pointer to an array holding the tick mark values. * nticks * The number of tick marks supplied by parameter "ticks". * force * If non-zero, then no check for identical adjacent labels is * performed, and the labels are always considered to be OK. * list * Pointer to the start of an array of pointers. Each of the * elements in this array receives a pointer to a string holding a * formatted label. Each of these strings should be freed using * astFree when no longer needed. * refval * A value to use for the other axis when normalizing. * status * Pointer to the inherited status variable. * Returned Value: * Zero if any pairs of identical adjacent labels were found. One * otherwise. * Notes: * - No error is reported if a pair of identical adjacent labels is * found. * - If an error has already occurred, or if this function should * fail for any reason, a value of zero is returned, and the array of * pointers identified by "list" is filled with NULL pointers. */ /* Local Variables: */ const char *label; /* Pointer to formatted tick value */ double val[ 2 ]; /* Workspace for normalizing */ int i; /* Tick index */ int len; /* Number of characters in curent label */ int ok; /* The returned flag */ /* Fill the supplied label list with NULL pointers. */ if( list ) { for( i = 0; i < nticks; i++ ) list[ i ] = NULL; } /* Check the global status. */ if( !astOK ) return 0; /* Initialise the returned flag to indicate that all adjacent labels are different. */ ok = 1; /* Normalize and format the first tick mark value. */ val[ axis ] = ticks[ 0 ]; val[ 1 - axis ] = refval; astNorm( frame, val ); label = astFormat( frame, axis, val[ axis ] ); /* Allocate memory holding a copy of the formatted value, and store a pointer to this copy in the list of labels. */ if( label ){ len = strlen( label ) + 1; list[ 0 ] = (char *) astStore( NULL, (void *) label, len ); } else { ok = 0; } /* Normalize and format each of the tick mark values in this batch. */ for( i = 1; i < nticks && astOK && ok; i++ ){ val[ axis ] = ticks[ i ]; val[ 1 - axis ] = refval; astNorm( frame, val ); label = astFormat( frame, axis, val[ axis ] ); if( label ){ /* Unless checks have been supressed, compare this label with the previous label. If they are identical clear the returned flag. */ if( !force && !strcmp( label, list[ i - 1 ] ) ) { ok = 0; /* Allocate memory holding a copy of the label, and store a pointer to this copy in the list of labels. */ } else { list[ i ] = (char *) astStore( NULL, (void *) label, strlen( label ) + 1 ); } } else { ok = 0; } } /* If two adjacent labels were identical, or an error occurred, release the memory used to store the labels. */ if( !ok || !astOK ){ for( i = 0; i < nticks; i++ ){ if( list[ i ] ) list[ i ] = (char *) astFree( (void *) list[ i ] ); } } /* Ensure a value of zero is returned if an error has occurred. */ if( !astOK ) ok = 0; /* Return the answer. */ return ok; } static char **CheckLabels2( AstPlot *this, AstFrame *frame, int axis, double *ticks, int nticks, char **old_list, double refval, int *status ){ /* * Name: * CheckLabels2 * Purpose: * Check that labels cannot be shortened. * Type: * Private function. * Synopsis: * #include "plot.h" * char **CheckLabels2( AstPlot *this, AstFrame *frame, int axis, * double *ticks, int nticks, char **old_list, * double refval, int *status ) * Class Membership: * Plot member function. * Description: * This function formats the supplied ticks mark values using the * astFormat method for the supplied Frame. It then compares the labels * with the corresponding labels supplied in "old_list". If all of the * new labels are shorter than, or equal in length to, the old labels, * then memory is allocated to hold the new (shorter) labels, and a * pointer to this memory is returned. If any new label is longer than * the corresponding old label, then a NULL pointer is returned. * * No check is performed on whether or not there are any identical * adjacent labels. * Parameters: * this * Pointer to the Plot. * frame * Pointer to the Frame. * axis * The zero-based index of the axis to which the tick marks refer. * ticks * Pointer to an array holding the tick mark values. * nticks * The number of tick marks supplied by parameter "ticks". * old_list * Pointer to the start of an array of pointers. Each of the * elements in this array should hold a pointer to a string holding a * formatted label. * refval * A value to use for the other axis when normalizing. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to an array of pointers. Each of these pointers points to * a text string holding a shortened label. If a complete set of * shortened labels could not be found (or if an error occurs), a NULL * pointer is returned. * Notes: * - The memory holding the returned shortened labels should be * freed by cthe caller, together with the memory holding the pointers to * the labels. * - No error is reported if a pair of identical adjacent labels is * found. * - If an error has already occurred, or if this function should * fail for any reason, a value of NULL is returned. */ /* Local Variables: */ char **list; /* The returned pointer */ const char *label; /* Pointer to formatted tick value */ double val[ 2 ]; /* Workspace for normalizing */ int i; /* Tick index */ int llen; /* Number of characters in curent label */ int ok; /* Are the old labels OK to be used? */ /* Check the global status. */ if( !astOK ) return NULL; /* Allocate memory to hold the pointers to the new labels. */ list = (char **) astMalloc( sizeof( char * )*(size_t) nticks ); if( list ) { /* Fill this array with NULLs for safety. */ for( i = 0; i < nticks; i++ ) list[ i ] = NULL; /* Initialise a flag to indicate that all the new labels are shorter than the old labels. */ ok = 0; /* Normalize and format each of the tick mark values in this batch. */ for( i = 0; i < nticks && astOK; i++ ){ val[ axis ] = ticks[ i ]; val[ 1 - axis ] = refval; astNorm( frame, val ); label = astFormat( frame, axis, val[ axis ] ); if( label ){ /* Get the length of the new label. */ llen = strlen( label ); /* Compare this label with the corresponding old label. If the new one is longer than the old one, set the flag and leave the loop. */ if( llen > strlen( old_list[ i ] ) ) { ok = 1; break; } /* Store the new label. */ list[ i ] = (char *) astStore( NULL, (void *) label, (size_t) (llen + 1) ); } } /* If the old labels are to be used, or an error occurred, release the memory used to store the new labels. */ if( ok || !astOK ){ for( i = 0; i < nticks; i++ ){ if( list[ i ] ) list[ i ] = (char *) astFree( (void *) list[ i ] ); } list = (char **) astFree( (void *) list ); } } /* Return the answer. */ return list; } static int ChrLen( const char *string, int *status ){ /* * Name: * ChrLen * Purpose: * Return the length of a string excluding any trailing white space. * Type: * Private function. * Synopsis: * int ChrLen( const char *string, int *status ) * Class Membership: * Plot * Description: * This function returns the length of a string excluding any trailing * white space. * Parameters: * string * Pointer to the string. * status * Pointer to the inherited status variable. * Returned Value: * The length of a string excluding any trailing white space. * Notes: * - A value of zero is returned if a NULL pointer is supplied, or if an * error has already occurred. */ /* Local Variables: */ const char *c; /* Pointer to the next character to check */ int ret; /* The returned string length */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise the returned string length. */ ret = 0; /* Check a string has been supplied. */ if( string ){ /* Check each character in turn, starting with the last one. */ ret = strlen( string ); c = string + ret - 1; while( ret ){ if( !isspace( (int) *c ) ) break; c--; ret--; } } /* Return the answer. */ return ret; } static AstPlotCurveData **CleanCdata( AstPlotCurveData **cdata, int *status ){ /* * Name: * CleanCdata * Purpose: * Release the structures holding curve break information. * Type: * Private function. * Synopsis: * #include "plot.h" * AstPlotCurveData **CleanCdata( AstPlotCurveData **cdata, int *status ) * Class Membership: * Plot member function. * Description: * This function releases the memory used to hold the curve break * information returned by function DrawGrid, and returns a NULL pointer. * Parameters: * cdata * Pointer to the information to be freed. * status * Pointer to the inherited status variable. * Returned Value: * A NULL pointer. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Return if a NULL pointer has been supplied. */ if( !cdata ) return NULL; /* Release each of the two structures in turn (if they exist). */ (void) astFree( (void *) cdata[ 0 ] ); (void) astFree( (void *) cdata[ 1 ] ); /* Release the memory used to hold the two AstPlotCurveData pointers. */ (void) astFree( (void *) cdata ); /* Return. */ return NULL; } static TickInfo **CleanGrid( TickInfo **grid, int *status ){ /* * Name: * CleanGrid * Purpose: * Release the structures holding grid information. * Type: * Private function. * Synopsis: * #include "plot.h" * TickInfo **CleanGrid( TickInfo **grid ) * Class Membership: * Plot member function. * Description: * This function releases the memory used to hold the grid information * returned by function GridLines, and returns a NULL pointer. * Parameters: * grid * Pointer to the information to be freed. * Returned Value: * A NULL pointer. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ TickInfo *info; /* Pointer to TickInfo structure being freed */ int i; /* Axis index */ int j; /* Tick mark index */ /* Return if a NULL pointer has been supplied. */ if( !grid ) return NULL; /* Release each of the TickInfo structures in turn (if they exist). */ for( i = 0; i < 2; i++ ){ if( ( info = grid[ i ] ) ){ /* Release the memory holding major tick mark values. */ (void) astFree( (void *) info->ticks ); /* Release the memory holding minor tick mark values. */ (void) astFree( (void *) info->minticks ); /* Release the memory holding curve section starting positions. */ (void) astFree( (void *) info->start ); /* Release the memory holding curve section lengths. */ (void) astFree( (void *) info->length ); /* If there are any tick mark labels in the structure... */ if( info->labels ){ /* Release the memory holding each tick mark label. */ for( j = 0; j < info->nmajor; j++ ){ (void) astFree( (void *) info->labels[ j ] ); } /* Release the memory holding the pointers to the tick mark labels. */ (void) astFree( (void *) info->labels ); /* Release the memory holding the format specification string. */ (void) astFree( (void *) info->fmt ); } /* Release the TickInfo structure. */ (void) astFree( (void *) info ); } } /* Release the memory used to hold the two TickInfo pointers. */ (void) astFree( (void *) grid ); /* Return. */ return NULL; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Plot. * Type: * Private function. * Synopsis: * #include "plot.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot member function (over-rides the astClearAttrib protected * method inherited from the FrameSet class). * Description: * This function clears the value of a specified attribute for a * Plot, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Plot. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot *this; /* Pointer to the Plot structure */ char label[21]; /* Graphics item label */ const char *class; /* Pointer to class string */ int axis; /* Axis number */ int id1; /* Plot object id */ int id2; /* Plot object id */ int id; /* Plot object id */ int len; /* Length of attrib string */ int nax; /* Number of base Frame axes */ int nc; /* No. characters read by astSscanf */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_object; /* Get the number of base Frame axis (2 for a Plot, 3 for a Plot3D). */ nax = astGetNin( this ); /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* Edge(axis). */ /* ------------ */ if ( nc = 0, ( 1 == astSscanf( attrib, "edge(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearEdge( this, axis - 1 ); /* Grid. */ /* ----- */ } else if ( !strcmp( attrib, "grid" ) ) { astClearGrid( this ); /* LabelUp */ /* ------- */ } else if ( !strcmp( attrib, "labelup" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLabelUp( this, axis ); /* LabelUp(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelup(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLabelUp( this, axis - 1 ); /* LogPlot */ /* ------- */ } else if ( !strcmp( attrib, "logplot" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLogPlot( this, axis ); /* LogPlot(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logplot(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLogPlot( this, axis - 1 ); /* LogTicks */ /* ------- */ } else if ( !strcmp( attrib, "logticks" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLogTicks( this, axis ); /* LogTicks(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logticks(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLogTicks( this, axis - 1 ); /* LogLabel */ /* ------- */ } else if ( !strcmp( attrib, "loglabel" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLogLabel( this, axis ); /* LogLabel(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loglabel(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLogLabel( this, axis - 1 ); /* NumLab. */ /* ---------- */ } else if ( !strcmp( attrib, "numlab" ) ) { for( axis = 0; axis < nax; axis++ ) astClearNumLab( this, axis ); /* NumLab(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearNumLab( this, axis - 1 ); /* MinTick. */ /* ---------- */ } else if ( !strcmp( attrib, "mintick" ) ) { for( axis = 0; axis < nax; axis++ ) astClearMinTick( this, axis ); /* MinTick(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "mintick(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearMinTick( this, axis - 1 ); /* TextLab. */ /* ---------- */ } else if ( !strcmp( attrib, "textlab" ) ) { for( axis = 0; axis < nax; axis++ ) astClearTextLab( this, axis ); /* TextLab(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearTextLab( this, axis - 1 ); /* LabelUnits. */ /* --------- */ } else if ( !strcmp( attrib, "labelunits" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLabelUnits( this, axis ); /* LabelUnits(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelunits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLabelUnits( this, axis - 1 ); /* Style. */ /* ------ */ } else if ( !strcmp( attrib, "style" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearStyle( this, id ); /* Style(label). */ /* --------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "style(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearStyle( this, id1 ); if( nid > 1 ) astClearStyle( this, id2 ); if( nid > 2 ) astClearStyle( this, id3 ); /* Font. */ /* ----- */ } else if ( !strcmp( attrib, "font" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearFont( this, id ); /* Font(label). */ /* -------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "font(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearFont( this, id1 ); if( nid > 1 ) astClearFont( this, id2 ); if( nid > 2 ) astClearFont( this, id3 ); /* Colour. */ /* ------- */ } else if ( !strcmp( attrib, "colour" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearColour( this, id ); /* Colour(label). */ /* ---------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "colour(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearColour( this, id1 ); if( nid > 1 ) astClearColour( this, id2 ); if( nid > 2 ) astClearColour( this, id3 ); /* Color. */ /* ------ */ } else if ( !strcmp( attrib, "color" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearColour( this, id ); /* Color(label). */ /* --------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "color(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearColour( this, id1 ); if( nid > 1 ) astClearColour( this, id2 ); if( nid > 2 ) astClearColour( this, id3 ); /* Width. */ /* ------ */ } else if ( !strcmp( attrib, "width" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearWidth( this, id ); /* Width(label). */ /* --------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "width(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearWidth( this, id1 ); if( nid > 1 ) astClearWidth( this, id2 ); if( nid > 2 ) astClearWidth( this, id3 ); /* Size. */ /* ----- */ } else if ( !strcmp( attrib, "size" ) ) { for( id = 0; id < AST__NPID; id++ ) astClearSize( this, id ); /* Size(label). */ /* -------------*/ } else if ( nc = 0, ( 1 == astSscanf( attrib, "size(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, attrib, "astClear", class, status ), nax, &id1, &id2, &id3, status ); astClearSize( this, id1 ); if( nid > 1 ) astClearSize( this, id2 ); if( nid > 2 ) astClearSize( this, id3 ); /* LabelAt(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelat(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLabelAt( this, axis - 1 ); /* Centre(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "centre(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearCentre( this, axis - 1 ); /* Gap. */ /* ---- */ } else if ( !strcmp( attrib, "gap" ) ) { for( axis = 0; axis < nax; axis++ ) astClearGap( this, axis ); /* Gap(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "gap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearGap( this, axis - 1 ); /* LogGap. */ /* ----------- */ } else if ( !strcmp( attrib, "loggap" ) ) { for( axis = 0; axis < nax; axis++ ) astClearLogGap( this, axis ); /* LogGap(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loggap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLogGap( this, axis - 1 ); /* NumLabGap. */ /* ---------- */ } else if ( !strcmp( attrib, "numlabgap" ) ) { for( axis = 0; axis < nax; axis++ ) astClearNumLabGap( this, axis ); /* NumLabGap(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearNumLabGap( this, axis - 1 ); /* TextLabGap. */ /* ----------- */ } else if ( !strcmp( attrib, "textlabgap" ) ) { for( axis = 0; axis < nax; axis++ ) astClearTextLabGap( this, axis ); /* TextLabGap(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearTextLabGap( this, axis - 1 ); /* TitleGap. */ /* --------- */ } else if ( !strcmp( attrib, "titlegap" ) ) { astClearTitleGap( this ); /* MajTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "majticklen" ) ) { for( axis = 0; axis < nax; axis++ ) astClearMajTickLen( this, axis ); /* MajTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "majticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearMajTickLen( this, axis - 1 ); /* MinTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "minticklen" ) ) { for( axis = 0; axis < nax; axis++ ) astClearMinTickLen( this, axis ); /* MinTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "minticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearMinTickLen( this, axis - 1 ); /* Labelling. */ /* -------- */ } else if ( !strcmp( attrib, "labelling" ) ) { astClearLabelling( this ); /* TickAll. */ /* -------- */ } else if ( !strcmp( attrib, "tickall" ) ) { astClearTickAll( this ); /* ForceExterior */ /* ------------- */ } else if ( !strcmp( attrib, "forceexterior" ) ) { astClearForceExterior( this ); /* Invisible. */ /* ---------- */ } else if ( !strcmp( attrib, "invisible" ) ) { astClearInvisible( this ); /* Border. */ /* ------- */ } else if ( !strcmp( attrib, "border" ) ) { astClearBorder( this ); /* ClipOp. */ /* ------- */ } else if ( !strcmp( attrib, "clipop" ) ) { astClearClipOp( this ); /* Clip. */ /* ----- */ } else if ( !strcmp( attrib, "clip" ) ) { astClearClip( this ); /* Grf. */ /* ---- */ } else if ( !strcmp( attrib, "grf" ) ) { astClearGrf( this ); /* DrawTitle. */ /* ---------- */ } else if ( !strcmp( attrib, "drawtitle" ) ) { astClearDrawTitle( this ); /* DrawAxes. */ /* --------- */ } else if ( !strcmp( attrib, "drawaxes" ) ) { for( axis = 0; axis < nax; axis++ ) astClearDrawAxes( this, axis ); /* Abbrev */ /* ------ */ } else if ( !strcmp( attrib, "abbrev" ) ) { for( axis = 0; axis < nax; axis++ ) astClearAbbrev( this, axis ); /* DrawAxes(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "drawaxes(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearDrawAxes( this, axis - 1 ); /* Abbrev(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "abbrev(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearAbbrev( this, axis - 1 ); /* Escape. */ /* ------- */ } else if ( !strcmp( attrib, "escape" ) ) { astClearEscape( this ); /* Tol. */ /* ---- */ } else if ( !strcmp( attrib, "tol" ) ) { astClearTol( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearLogPlot( AstPlot *this, int axis, int *status ){ /* * * Name: * ClearLogPlot * Purpose: * Clear the value for a LogPlot attribute * Type: * Private function. * Synopsis: * #include "plot.h" * void ClearLogPlot( AstPlot *this, int axis, int *status ) * Class Membership: * Plot member function * Description: * Assigns the default value to the LogPlot attribute of the specified * axis, and also re-maps the base Frame of the Plot if necessary. * Parameters: * this * The Plot. * axis * Zero based axis index. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int oldval; /* Original value of the attribute */ int newval; /* Cleared (default) value of the attribute */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index. */ if( axis < 0 || axis >= 2 ){ astError( AST__AXIIN, "astClearLogPlot(%s): Index (%d) is invalid for " "attribute LogPlot - it should be in the range 1 to 2.", status, astGetClass( this ), axis + 1 ); /* Do nothing if the attribute is not currently set. */ } else if( astTestLogPlot( this, axis ) ){ /* Get the original value of the attribute. clear the value, and then get the new (default) value. */ oldval = this->logplot[ axis ]; this->logplot[ axis ] = -1; newval = astGetLogPlot( this, axis ); /* If the effective value has changed, attempt to remap the axis. If this fails, re-instate the original value. */ if( ( oldval != 0 ) != ( newval != 0 ) ) { if( !ToggleLogLin( this, axis, oldval, "astClearLogPlot", status ) ) { this->logplot[ axis ] = oldval; } } } } static void Clip( AstPlot *this, int iframe, const double lbnd[], const double ubnd[], int *status ){ /* *++ * Name: c astClip f AST_CLIP * Purpose: * Set up or remove clipping for a Plot. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astClip( AstPlot *this, int iframe, const double lbnd[], c const double ubnd[] ) f CALL AST_CLIP( THIS, IFRAME, LBND, UBND, STATUS ) * Class Membership: * Plot method. * Description: c This function defines regions of a Plot which are to be clipped. f This routine defines regions of a Plot which are to be clipped. * Any subsequent graphical output created using the Plot will then * be visible only within the unclipped regions of the plotting * area. See also the Clip attribute. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c iframe f IFRAME = INTEGER (Given) * The index of the Frame within the Plot to which the clipping c limits supplied in "lbnd" and "ubnd" (below) refer. Clipping f limits supplied in LBND and UBND (below) refer. Clipping * may be applied to any of the coordinate systems associated * with a Plot (as defined by the Frames it contains), so this * index may take any value from 1 to the number of Frames in * the Plot (Nframe attribute). In addition, the values * AST__BASE and AST__CURRENT may be used to specify the base * and current Frames respectively. * * For example, a value of AST__CURRENT causes clipping to be * performed in physical coordinates, while a value of AST__BASE * would clip in graphical coordinates. Clipping may also be * removed completely by giving a value of AST__NOFRAME. In this * case any clipping bounds supplied (below) are ignored. c lbnd f LBND( * ) = DOUBLE PRECISION (Given) * An array with one element for each axis of the clipping Frame c (identified by the index "iframe"). This should contain the f (identified by the index IFRAME). This should contain the * lower bound, on each axis, of the region which is to remain * visible (unclipped). c ubnd f UBND( * ) = DOUBLE PRECISION (Given) * An array with one element for each axis of the clipping Frame c (identified by the index "iframe"). This should contain the f (identified by the index IFRAME). This should contain the * upper bound, on each axis, of the region which is to remain * visible (unclipped). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - Only one clipping Frame may be active at a time. This function f - Only one clipping Frame may be active at a time. This routine * will deactivate any previously-established clipping Frame before * setting up new clipping limits. c - The clipping produced by this function is in addition to that f - The clipping produced by this routine is in addition to that * specified by the Clip attribute which occurs at the edges of the * plotting area c established when the Plot is created (see astPlot). The f established when the Plot is created (see AST_PLOT). The * underlying graphics system may also impose further clipping. * - When testing a graphical position for clipping, it is first * transformed into the clipping Frame. The resulting coordinate on * each axis is then checked against the clipping limits (given by c "lbnd" and "ubnd"). By default, a position is clipped if any f LBND and UBND). By default, a position is clipped if any * coordinate lies outside these limits. However, if a non-zero * value is assigned to the Plot's ClipOp attribute, then a * position is only clipped if the coordinates on all axes lie * outside their clipping limits. * - If the lower clipping limit exceeds the upper limit for any * axis, then the sense of clipping for that axis is reversed (so * that coordinate values lying between the limits are clipped * instead of those lying outside the limits). To produce a "hole" * in a coordinate space (that is, an internal region where nothing * is plotted), you should supply all the bounds in reversed order, * and set the ClipOp attribute for the Plot to a non-zero value. * - Either clipping limit may be set to the value AST__BAD, which * is equivalent to setting it to infinity (or minus infinity for a * lower bound) so that it is not used. * - If a graphical position results in any bad coordinate values * (AST__BAD) when transformed into the clipping Frame, then it is * treated (for the purposes of producing graphical output) as if * it were clipped. * - When a Plot is used as a Mapping to transform points c (e.g. using astTran2), any clipped output points are assigned f (e.g. using AST_TRAN2), any clipped output points are assigned * coordinate values of AST__BAD. * - An error results if the base Frame of the Plot is not * 2-dimensional. *-- */ /* Local Variables: */ AstFrame *fr; /* Pointer to the clipping Frame */ AstFrameSet *fset; /* Pointer to the Plot's FrameSet */ int i; /* Axis index */ int ifrm; /* The validated frame index */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ ifrm = 0; /* Get a pointer to the FrameSet at the start of the Plot. */ fset = (AstFrameSet *) this; /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( fset ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "astClip(%s): Number of axes (%d) in the " "base Frame of the supplied %s is invalid - this number " "should be 2.", status, astGetClass( this ), naxes, astGetClass( this ) ); } /* If clipping is to be switched on, check the supplied frame index and bounds. */ if( iframe != AST__NOFRAME && astOK ) { /* Report an error if either of the bounds pointers is NULL.*/ if( !lbnd ){ astError( AST__CLPAX, "astClip(%s): A NULL pointer was " "supplied for the array holding the lower bounds of " "the clipping volume.", status, astGetClass( this ) ); } else if( !ubnd ){ astError( AST__CLPAX, "astClip(%s): A NULL pointer was " "supplied for the array holding the upper bounds of " "the clipping volume.", status, astGetClass( this ) ); } /* Validate the clipping frame index. */ ifrm = astValidateFrameIndex( fset, iframe, "astClip" ); /* Get the number of axes in the clipping frame. */ fr = astGetFrame( this, ifrm ); naxes = astGetNaxes( fr ); fr = astAnnul( fr ); } /* Leave the current clipping information unchanged if an error has occurred. */ if( astOK ){ /* Remove all clipping information from the Plot. */ this->clip_lbnd = (double *) astFree( (void *) this->clip_lbnd ); this->clip_ubnd = (double *) astFree( (void *) this->clip_ubnd ); this->clip_frame = AST__NOFRAME; this->clip_axes = 0; /* If bounds have been supplied, set up new clipping information. */ if( iframe != AST__NOFRAME ){ /* Store the information. */ this->clip_frame = ifrm; this->clip_lbnd = astStore( NULL, lbnd, sizeof(double)*(size_t)naxes ); this->clip_ubnd = astStore( NULL, ubnd, sizeof(double)*(size_t)naxes ); this->clip_axes = naxes; /* If an error has occurred, remove all clipping information. */ if( !astOK ){ this->clip_lbnd = (double *) astFree( (void *) this->clip_lbnd ); this->clip_ubnd = (double *) astFree( (void *) this->clip_ubnd ); this->clip_frame = AST__NOFRAME; this->clip_axes = 0; /* Otherwise, replace any bounds of AST__BAD with suitable default values. */ } else { for( i = 0; i < naxes; i++ ){ if( this->clip_lbnd[ i ] == AST__BAD ) this->clip_lbnd[ i ] = -DBL_MAX; if( this->clip_ubnd[ i ] == AST__BAD ) this->clip_ubnd[ i ] = DBL_MAX; } } } } /* Return. */ return; } static int Compared( const void *elem1, const void *elem2 ){ /* * Name: * Compared * Purpose: * Compare two "double" values. * Type: * Private function. * Synopsis: * #include "plot.h" * int Compared( const void *elem1, const void *elem2 ) * Class Membership: * Plot method. * Description: * This function compares the two "double" values to which pointers * are supplied, and returns an integer indicating which is larger, * checking for AST__BAD values. It is intended for use with the C * Run-Time-Library sorting function "qsort". * Parameters: * elem1 * Pointer to the first "double". * elem2 * Pointer to the second "double". * Returned Value: * Zero is returned if the values are equal. If the first is larger * than the second then +1 is returned. Otherwise, -1 is returned. * Notes: * - Values of AST__BAD are considered to be larger than any other * value (other than another value of AST__BAD). * - If both values are AST__BAD, then zero is returned. * - This function executes even if an error has occurred. */ /* Local Variables: */ double *delem1; /* Pointer to the first "double" value */ double *delem2; /* Pointer to the second "double" value */ int ret; /* The returned value */ /* Get pointers to the two "double" values. */ delem1 = (double *) elem1; delem2 = (double *) elem2; /* Check the values for equality (including both values being AST__BAD). */ if( *delem1 == *delem2 ){ ret = 0; /* If the first is bad, then it is considered to be larger than the second. */ } else if( *delem1 == AST__BAD ){ ret = 1; /* If the second is bad, then it is considered to be larger than the first. */ } else if( *delem2 == AST__BAD ){ ret = -1; /* If the first is larger than the second, return 1. */ } else if( *delem1 > *delem2 ){ ret = 1; /* If the first is smaller than the second, return -1. */ } else { ret = -1; } /* Return the answer. */ return ret; } static int Compare_LL( const void *elem1, const void *elem2 ){ /* * Name: * Compare_LL * Purpose: * Compare two LabelList structures as used by function PlotLabels. * Type: * Private function. * Synopsis: * #include "plot.h" * int Compare_LL( const void *elem1, const void *elem2 ) * Class Membership: * Plot method. * Description: * This function compares two "LabelList" structures as used by function * PlotLabels, and returns an integer indicating which has a larger * "index" value. This function is intended to be used with the C * Run-Time-Library sorting function "qsort". * Parameters: * elem1 * Pointer to the first LabelList. * elem2 * Pointer to the second LabelList. * status * Pointer to the inherited status variable. * Returned Value: * Zero is returned if the values are equal. If the first is larger * than the second then +1 is returned. Otherwise, -1 is returned. * Notes: * - This function executes even if an error has occurred. */ /* Local Variables: */ LabelList *ll1; /* Pointer to the first LabelList */ LabelList *ll2; /* Pointer to the second LabelList */ int ret; /* The returned value */ /* Get pointers to the two LabelList structures. */ ll1 = (LabelList *) elem1; ll2 = (LabelList *) elem2; /* Compare the indices for the two label's. */ if( ll1->index < ll2->index ){ ret = -1; } else if( ll1->index > ll2->index ){ ret = 1; } else { ret = 0; } /* Return the answer. */ return ret; } static void CopyPlotDefaults( AstPlot *this, int axis, AstPlot *dplot, int daxis, int *status ){ /* *+ * Name: * astCopyPlotDefaults * Purpose: * Copy used attribute defaults from one Plot to another. * Type: * Protected virtual function. * Synopsis: * #include "plot.h" * void astCopyPlotDefaults( AstPlot *this, int axis, AstPlot *dplot, * int daxis ) * Class Membership: * Plot method. * Description: * Some of the attributes used by the Plot class have dynamic default * values that are determined during the process of drawing an annotated * grid using astGrid. The dynamic default values are stored in a * separate set of components within the Plot structure. This function * copies these components from one Plot to another. * Parameters: * this * Pointer to a Plot containing the values ot be copied. * axis * The zero-based index of the axis within "this" for which the * used defaults are to be copied. * dplot * A pointer to another Plot into which the default attribute * values are to be copied. * daxis * The zero based index of the axis within "dplot" which is to * receive the new values. *- */ /* Check the global status. */ if( !astOK ) return; dplot->ulglb[ daxis ] = this->ulglb[ axis ]; dplot->ulgtk[ daxis ] = this->ulgtk[ axis ]; dplot->uloggap[ daxis ] = this->uloggap[ axis ]; dplot->ugap[ daxis ] = this->ugap[ axis ]; dplot->ucentre[ daxis ] = this->ucentre[ axis ]; dplot->uedge[ daxis ] = this->uedge[ axis ]; dplot->ulblat[ daxis ] = this->ulblat[ axis ]; dplot->ulbunit[ daxis ] = this->ulbunit[ axis ]; dplot->umintk[ daxis ] = this->umintk[ axis ]; dplot->utxtlb[ daxis ] = this->utxtlb[ axis ]; dplot->umjtkln[ daxis ] = this->umjtkln[ axis ]; dplot->ugrid = this->ugrid; dplot->ulbling = this->ulbling; dplot->uborder = this->uborder; } static int CountGood( int n, double *data, int *status ){ /* * Name: * CountGood * Purpose: * Coount the number of non-bad values in an array. * Type: * Private function. * Synopsis: * #include "plot.h" * int CountGood( int n, double *data, int *status ) * Class Membership: * Plot method. * Description: * This function returns the number of elements in the supplied array * which do not have the value AST__BAD. * Parameters: * n * The total number of elements in the array. * data * Pointer to the start of the array. * status * Pointer to the inherited status variable. * Returned Value: * The number of good points in the array. * Notes: * - A value of zero is returned if an error has already occurred. */ /* Local Variables: */ int i; int ngood; double *value; /* Check global status. */ if( !astOK ) return 0; /* Initialise a pointer to the next array element, and the number of good elements found so far. */ value = data; ngood = 0; /* Check each element. */ for( i = 0; i < n; i++ ){ if( *(value++) != AST__BAD ) ngood++; } /* Return the answer. */ return ngood; } static int Cross( float ax, float ay, float bx, float by, float cx, float cy, float dx, float dy, int *status ){ /* * Name: * Cross * Purpose: * See if two line segments intersect. * Type: * Private function. * Synopsis: * #include "plot.h" * int Cross( float ax, float ay, float bx, float by, * float cx, float cy, float dx, float dy, int *status ) * Class Membership: * Plot method. * Description: * This function sees if the line segment (A,B) intersects the line * segment (C,D). * Parameters: * ax, ay * The coordinates of A. * bx, by * The coordinates of B. * cx, cy * The coordinates of C. * dx, dy * The coordinates of D. * status * Pointer to the inherited status variable. * Returned Value: * Zero if the line segments do not cross or if an error has already * occurred, and 1 if they do. */ /* Local Variables: */ int ret; float m1, m2, denom, num, t1, t2; /* Check the inherited status. */ if( !astOK ) return 0; /* Get the fraction of the distance from A to B at which the line AB intersects the line CD. */ m1 = dx - cx; m2 = dy - cy; denom = (bx - ax)*m2 - (by-ay)*m1; num = (ay - cy)*m1 - (ax - cx)*m2; if( denom != 0.0 ) { t1 = num / denom; /* If the the intersection occurs within the segment of the line between A and B... */ if( t1 >= 0.0 && t1 <= 1.0 ){ /* ... then get the fraction of the distance from C to D at which the line CD intersects the line AB. */ m1 = bx - ax; m2 = by - ay; denom = (dx - cx)*m2 - (dy-cy)*m1; num = (cy - ay)*m1 - (cx - ax)*m2; if( denom != 0.0 ) { t2 = num / denom; /* If the the intersection occurs within the segment of the line between C and D then the line segments intersect. */ if( t2 >= 0.0 && t2 <= 1.0 ){ ret = 1; } else { ret = 0; } /* If the two lines are parallel, then they do not intersect. */ } else { ret = 0; } } else { ret = 0; } } else { ret = 0; } return ret; } static void Crv( AstPlot *this, double *d, double *x, double *y, int skipbad, double *box, CrvStatics *pstatics, const char *method, const char *class, int *status ){ /* * Name: * Crv * Purpose: * Draw a curve. * Type: * Private function. * Synopsis: * #include "plot.h" * void Crv( AstPlot *this, double *d, double *x, double *y, int skipbad, * double *box, CrvStatics *pstatics, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws a curve parameterised by the distance from some * starting point. The function pointed to by the external variable * Crv_map is used to transform distances along the curve into graphics * coordinates (X,Y). The supplied function parameters defined the * section of the curve to be drawn. * * The algorithm used needs no knowledge about the nature of the mapping * performed by Crv_map, and can handle discontinuities in the curve. It * first of all determines if any of the segments of the curve can be * adequately represented by simply drawing a straight line through the * supplied end points. This decision is based on several requirements such * as keeping the angle between adjacent sections low and both ends being * defined (i.e. X and Y not equal to AST__BAD). Any segments of the curve * which satisfy the requirements are draw as straight lines. If any of * the supplied curve segments cannot be drawn in this way, then they are * split up into a set of evenly-spaced sub-segments and the graphics * coordinates at the ends of these sub-segments are found using Crv_map. * This function is then called recursively to draw the sub-segments. This * recursion is limited in depth by the requirement that all the * sub-segments must be longer than a specified lower limit. If this is not * the case, then the curve is assumed to be dis-continuous and and the * sub-segments are ignored. * Parameters: * d * Pointer to an array of CRV_NPNT values giving the distance along * the curve from the starting point to each of CRV_NPNT points. They * should increase monotonically, and should be in whatever units are * used by the function pointed to by Crv_map. The curve is drawn from * d[0] to d[CRV_NPNT]. * x * Pointer to an array of CRV_NPNT values giving the graphics X * coordinate for the positions supplied in the array pointed to by * parameter "d". * y * Pointer to an array of CRV_NPNT values giving the graphics Y * coordinate for the positions supplied in the array pointed to by * parameter "d". * skipbad * Controls what happens if all the supplied points are bad or * outside the plotting area. If skipbad is non-zero, then it is * assumed that the supplied points represent an entirely bad (or * out of bounds) section of the curve, and this function will * return without attempt to sub-divide any of the supplied points. * If skipbad is zero, then it is assumed that we may be able to find * some good points between the supplied bad points, and therefore * this function will attempt to sub-divide the supplied points. * Should be supplied as zero on the initial invocation. * box * Pointer to an array of 4 doubles houlding a bounding box within * which the current segment must reside if it is to be sub-divided. * Supplied in the order xlo, xhi, ylo, yhi. May be NULL in which * case, no check is made on the bounding box. * pstatics * Pointer to a structure holding values for variables which were * statically defined within this function prior to the thread-safe * version of AST. If a NULL pointer is supplied, a new structure * is created in dynamic memory and initialised. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * External Variables: * Crv_nent = int (Read/Write) * The number of recursive entries which have been made into * this function. This should be set to zero before entering * this function for the first time. * Crv_ux0 = double (Read/Write) * The X component in graphics coordinates of the unit vector * along the previous segment of the curve. This should be set * to AST__BAD initially to indicate that the previous section * is not defined. * Crv_uy0 = double (Read/Write) * The Y component of the unit vector along the previous segment. * Crv_limit = double (Read) * The square of the maximum acceptable residual between the * drawn curve and the true curve, in graphics coordinates. * Crv_scerr = double (Read) * If the ratio of the lengths of adjacent sub-segments is larger * than Crv_scerr,then the seub-segments will be sub-divided. Note, * if either axis is mapped logarithmically onto the screen, then * there will naturally be large changes in scale. Crv_scerr should * always be larger than 1.0. * Crv_map = void (*)( int n, double *dd, double *xx, double *yy, * const char *method, const char *class ) (Read) * A pointer to a function which can be called to map "n" distances * along the curve (supplied in "dd") into graphics coordinates * (stored in "xx" and "yy"). See function "Map1" as an example. * Crv_clip = int (Read) * Should lines be clipped at the edge of the plotting area? * Notes: * - The CRV_TRACE conditional compilation blocks in this function * provide code which displays the recursive entries made to this * function (and also pauses on initial entry until return is pressed). * It is useful for investigating the details of the drawing of a * curve. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ CrvStatics *statics; /* Pointer to structure holding static values */ double *dd; /* Pointer to array holding sub-segment distances */ double *pd; /* Pointer to next sub-segment distance */ double *px; /* Pointer to next sub-segment x coord. */ double *py; /* Pointer to next sub-segment y coord. */ double *xx; /* Pointer to array holding sub-segment x coord.s */ double *yy; /* Pointer to array holding sub-segment x coord.s */ double bbox[4]; /* Bounding box for this segment */ double dl2[ CRV_NSEG ];/* Squred segment lengths */ double dx[ CRV_NSEG ]; /* X increment along each segment */ double dy[ CRV_NSEG ]; /* Y increment along each segment */ int i; /* Segment index */ int seg_ok[ CRV_NSEG ];/* Flags indicating which segments can be drawn */ int subdivide; /* Flag indicating if segments can be subdivided */ /* Check inherited status */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* If required, allocate memory for a structure to hold the static variables need by this function. */ if( ! pstatics ) { statics = astMalloc( sizeof( CrvStatics ) ); } else { statics = pstatics; } /* If this is the first entry, set up the minimum length for a sub-segment in graphics coordinates. If any segment is less than this minimum length, then recursion will stop and the curve will be assumed to be dis-continuous. */ if( !Crv_nent ) { statics->limit2 = 20.0*Crv_limit/(CRV_NSEG*CRV_NSEG); #ifdef CRV_TRACE statics->levels[ 0 ] = 0; #endif } /* Increment the number of entries into this function. */ Crv_nent++; #ifdef CRV_TRACE for( i = 0; i < Crv_nent; i++ ) { printf("%d ",statics->levels[ i ] ); } printf("\n"); if( getchar() == 'm' ) { float ffx,ffy; for( i = 0; i < CRV_NPNT; i++ ) { ffx = x[i]; ffy = y[i]; GMark( this, 1, &ffx, &ffy, 2, method, class, status ); GFlush( this, method, class, status ); } } #endif /* ====================================================================== The first section of this function sets up some arrays holding information which will be used later on. It looks at each of the segments joing adjacent tabulated points, and finds and stores the increments in X and Y along each segment, and the square of the segment length. It also checks to see if the tabulated points are all bad, or if they are all good. It also finds the lowest squared segment length. ======================================================================*/ /* Look at the first tabulated point. If it is good, set a flag to indicate that it can be used, store it as "the previous position" (i.e. the start of the current segment). Also set a flag ("all_bad") to indicate if all points looked at so far have been bad, or outside the plotting area. */ if( *x != AST__BAD && *y != AST__BAD ){ statics->last_ok = 1; statics->last_x = *x; statics->last_y = *y; statics->all_bad = ( *x < Crv_xlo || *x > Crv_xhi || *y < Crv_ylo || *y > Crv_yhi ) && Crv_clip; } else { statics->last_ok = 0; statics->all_bad = 1; } /* Initialise the bouding box for the this segment. */ bbox[ 0 ] = DBL_MAX; bbox[ 1 ] = -DBL_MAX; bbox[ 2 ] = DBL_MAX; bbox[ 3 ] = -DBL_MAX; /* Store pointers to the X and Y values for the "current position". This is the position at the end of the current segment. This is initially the second tabulated point. */ px = x + 1; py = y + 1; /* Store pointers to the increments and squared length for the current segment. */ statics->pdx = dx; statics->pdy = dy; statics->pdl2 = dl2; /* Initialise the number of long and short segments. */ statics->nlong = 0; statics->nshort = 0; /* Loop round each segment. */ for( i = 0; i < CRV_NSEG; i++ ){ /* If the tabulated point marking the end of the segment is good... */ if( *px != AST__BAD && *py != AST__BAD ){ /* Update the bounding box. */ if( *px < bbox[ 0 ] ) bbox[ 0 ] = *px; if( *px > bbox[ 1 ] ) bbox[ 1 ] = *px; if( *py < bbox[ 2 ] ) bbox[ 2 ] = *py; if( *py > bbox[ 3 ] ) bbox[ 3 ] = *py; /* If the point is within the plotting area, set the "statics->all_bad" flag to indicate that at least 1 point is within the plotting area. */ if( !Crv_clip || ( *px >= Crv_xlo && *px <= Crv_xhi && *py >= Crv_ylo && *py <= Crv_yhi ) ) statics->all_bad = 0; /* If the point marking the start of the segment was also good, find and store the increments and squared length for the segment, incrementing the pointers ready for the next segment. */ if( statics->last_ok ){ statics->t1 = *px - statics->last_x; statics->t2 = *py - statics->last_y; statics->t3 = statics->t1*statics->t1 + statics->t2*statics->t2; *(statics->pdx++) = statics->t1; *(statics->pdy++) = statics->t2; *(statics->pdl2++) = statics->t3; /* Count the number of segments which are, and are not, shorter than the minimum significant length. */ if( statics->t3 > statics->limit2 ) { statics->nlong++; } else { statics->nshort++; } /* If the start was bad, the length of the segment is not defined so store bad values. */ } else { *(statics->pdx++) = AST__BAD; *(statics->pdy++) = AST__BAD; *(statics->pdl2++) = AST__BAD; } /* The point at the end of the current segment becomes the point at the start of the next segment. */ statics->last_ok = 1; statics->last_x = *(px++); statics->last_y = *(py++); /* If the tabulated point marking the end of the current segment is bad, the segment length is undefined so store bad values. */ } else { *(statics->pdx++) = AST__BAD; *(statics->pdy++) = AST__BAD; *(statics->pdl2++) = AST__BAD; /* The point at the end of the current segment becomes the point at the start of the next segment. */ statics->last_ok = 0; px++; py++; } } /* ====================================================================== The next section of this function checks to see lines can be drawn directly through any of the tabulated points. The flags in "seg_ok" indicates if this is the case for each segment. ======================================================================*/ /* The unit vector along the previous segment is supplied in external variables Crv_ux0 and Crv_uy0. These will be AST__BAD if the direction of the previous segment is undefined. */ statics->vxl = Crv_ux0; statics->vyl = Crv_uy0; /* The length of the previous segment is initially bad. */ statics->dll = AST__BAD; /* Set up some pointers used to walk through the arrays holding the lengths of each segment. */ statics->pdl2 = dl2; statics->pdx = dx; statics->pdy = dy; /* Check each segment in turn to see if it can be drawn as a single straight line. */ for( i = 0; i < CRV_NSEG; i++ ){ /* A segment can only be drawn as a single line if both ends are good and the distance between them is not zero. */ if( *statics->pdl2 != AST__BAD && *statics->pdl2 > 0.0 ){ /* Get a unit vector in the direction of the current segment. */ statics->dl = sqrt( *statics->pdl2 ); statics->vx = *statics->pdx/statics->dl; statics->vy = *statics->pdy/statics->dl; /* If a unit vector in the direction of the previous segment is available, we check that the angle between the previous segment and the current segment is not too high. */ if( statics->vxl != AST__BAD ){ statics->cosang = statics->vxl*statics->vx + statics->vyl*statics->vy; /* If the angle is too high, set a flag to indicate that the segment cannot be drawn as a single line. Also, set the flag for the previous segment as well. */ if( statics->cosang < 0.8 || ( *statics->pdl2 )*( 1.0 - statics->cosang*statics->cosang ) > Crv_limit ) { seg_ok[ i ] = 0; if( i > 0 ) seg_ok[ i - 1 ] = 0; /* If the angle between this segment and the previous segment is not too high, check that the scale has not changed too much. */ } else { /* If the scale (=vector length) has changed a lot, set a flag to indicate that the segment cannot be drawn as a single line. Also, set the flag for the previous segment as well. */ if( statics->dll != AST__BAD && ( statics->dl < statics->dll/Crv_scerr || statics->dl > statics->dll*Crv_scerr ) ) { seg_ok[ i ] = 0; if( i > 0 ) seg_ok[ i - 1 ] = 0; /* If the orientation and scale of this segment has not changed much from the previous segment, the segment can be drawn as a straight line. */ } else { seg_ok[ i ] = 1; } } /* If no unit vector is available for the previous segment, then assume we are re-starting the curve after a discontinuity. In this case, we can draw it as a straight line. */ } else { seg_ok[ i ] = 1; } /* Save the unit vector along the current segment for use next time. */ statics->vxl = statics->vx; statics->vyl = statics->vy; /* Save the length if the current segment for use next time. */ statics->dll = statics->dl; /* If the length of the current segment is undefined, or zero, we cannot draw it as a single line. Also, there is no direction vector to pass on to the next time, so set them bad. */ } else { seg_ok[ i ] = 0; statics->vxl = AST__BAD; statics->vyl = AST__BAD; statics->dll = AST__BAD; } /* Point to the next segment. */ statics->pdl2++; statics->pdx++; statics->pdy++; } /* Do not allow isolated segments to be OK. If a segment is flagged as being OK, but both its neighbours are not OK, set the segment not OK as well. */ statics->seg0 = seg_ok + 1; statics->segm = seg_ok; statics->segp = seg_ok + 2; if( !(*statics->seg0) ) *statics->segm = 0; for( i = 1; i < CRV_NSEG - 1; i++ ){ if( !(*statics->segm) && !(*statics->segp) ) *statics->seg0 = 0; statics->seg0++; statics->segm++; statics->segp++; } if( !(*statics->segm) ) *statics->seg0 = 0; /* ====================================================================== The next section of this function draws the curve. Each segment is drawn as a straight line if the corresponding flag in "seg_ok" is set. Segments for which the flag is not set are drawn by calling this function recursivly. ======================================================================*/ /* Get the parametric length (i.e. the increment in "d") of the sub-segments within each subdivided segment. */ statics->delta = ( d[ CRV_NSEG ] - d[ 0 ] )/(double)( CRV_NSEG*CRV_NSEG ); /* If we have made the maximum number of recursive entries into this function, or if every supplied point was bad or outside the plotting area, or if most of the segments were very short in graphics space, we will not be attempting to subdivide any segments which cannot be drawn directly as a straight line. If "skipbad" was supplied as zero, we ignore the restriction which says that we must have some good points (since we may find some good poits by a further sub-division). */ subdivide = ( Crv_nent < CRV_MXENT && ( !statics->all_bad || !skipbad ) && statics->nlong > statics->nshort ); /* We do not sub-divide if the bounding box of the supplied points is not at least 10% smaller than the supplied bouding box on either axis. */ if( box && bbox[ 0 ] != DBL_MAX ) { if( bbox[ 1 ] - bbox[ 0 ] > 0.9*( box[ 1 ] - box[ 0 ] ) && bbox[ 3 ] - bbox[ 2 ] > 0.9*( box[ 3 ] - box[ 2 ] ) ) { subdivide = 0; } } /* Initialise some pointers to the data defineding the subsegments. */ dd = NULL; xx = NULL; yy = NULL; /* If we may be subdividing any segments, find which segments they are and set up the offset to each sub-segment. */ if( subdivide ){ /* Initialise the number of segments being subdivided. */ statics->nseg = 0; /* Loop round each segment. */ for( i = 0; i < CRV_NSEG; i++ ){ /* If the segment cannot be drawn directly as a straight line, we will subdivide it. */ if( !seg_ok[ i ] ){ /* Increment the number of segments being subdivided, and let the array of subsegment offsets grow to accomodate it. */ statics->nseg++; dd = (double *) astGrow( dd, statics->nseg, sizeof(double)*( CRV_NSEG + 1 ) ); if( !astOK ) break; /* Append the offset to each new subsegment to the "dd" array. */ statics->el = ( statics->nseg - 1 )*( CRV_NSEG + 1 ); statics->d0 = d[ i ]; for( statics->j = 0; statics->j <= CRV_NSEG; statics->j++ ){ dd[ statics->el++ ] = statics->d0; statics->d0 += statics->delta; } } } /* If any segments needed subdividing, get room to store the graphics coordinates at each point, and then fill these arrays by calling Crv_map to map the offsets in "dd" into graphics coordinates. */ if( statics->nseg > 0 ){ statics->nel = statics->nseg*( CRV_NSEG + 1 ); xx = (double *) astMalloc( sizeof(double)*(size_t)statics->nel ); yy = (double *) astMalloc( sizeof(double)*(size_t)statics->nel ); Crv_map( statics->nel, dd, xx, yy, method, class, status GLOBALS_NAME ); } } /* If all has gone OK, we will draw each segment. Initialise pointers used to walk through the "xx", "yy" and "dd" arrays. */ if( astOK ){ px = xx; py = yy; pd = dd; /* Draw each segment in turn. */ for( i = 0; i < CRV_NSEG; i++ ){ /* If possible, draw it as a single straight line, and then store the unit vector along the line in the appropriate external variables for use by the next invocation of this function. */ if( seg_ok[ i ] ){ CrvLine( this, x[ i ], y[ i ], x[ i + 1 ], y[ i + 1 ], method, class, status ); statics->dl = sqrt( dl2[ i ] ); Crv_ux0 = dx[ i ]/statics->dl; Crv_uy0 = dy[ i ]/statics->dl; /* Otherwise, if we are subdividing, and if the current segment is not very short, we call this function recursively to draw the segment. Increment pointers into the "xx", "yy" and "dd" arrays so that they point to the start of the subsegment information for the next segment to be subdivided. If all the graphics positions at this level were bad or outside the plot, tell the next invocation of Crv to do no further sub-divisions if it too finds all graphics positions to be bad or outside the plot. */ } else if( subdivide ) { #ifdef CRV_TRACE statics->levels[ Crv_nent ] = i; #endif Crv( this, pd, px, py, statics->all_bad, bbox, statics, method, class, status ); pd += CRV_NSEG + 1; px += CRV_NSEG + 1; py += CRV_NSEG + 1; /* Otherwise, we assume we have hit a discontinuity in the curve. Store bad values for the unit vector along the previous sgment, and do not draw anything. */ } else { Crv_ux0 = AST__BAD; Crv_uy0 = AST__BAD; } } } /* Free any memory used to store subsegment information. */ if( dd ) dd = (double *) astFree( (void *) dd ); if( xx ) xx = (double *) astFree( (void *) xx ); if( yy ) yy = (double *) astFree( (void *) yy ); /* Decrement the number of recursive entries into this function. */ Crv_nent--; /* Free the memory holding the static data values if we are leaving the final entry. */ if( ! pstatics ) statics = astFree( statics ); /* Return. */ return; } static int CvBrk( AstPlot *this, int ibrk, double *brk, double *vbrk, double *len, int *status ){ /* *+ * Name: * astCvBrk * Purpose: * Return information about breaks in the last curve drawn by astGridLine, * astCurve or astGenCurve. * Type: * Protected virtual function. * Synopsis: * #include "plot.h" * int CvBrk( AstPlot *this, int ibrk, double *brk, double *vbrk, * double *len ) * Class Membership: * Plot method. * Description: * Curves drawn by astGridLine, astCurve or astGenCurve may contain breaks * for several reasons (for instance, it may go outside the plotting area, * or the mapping between physical and graphics coordinates may be * discontinuous). This function returns information about such breaks. * Parameters: * this * Pointer to a Plot. * ibrk * The index of the break for which information is required. The first * break has index 1. An error is reported if no break with the * required index exists. The exception to this is that zero can be * supplied, in which case the "brk" and "vbrk" parameters * are ignored, but all other information is returned. * brk * A pointer to an array of 2 elements * in which to return the X and Y graphics coordinates of the break. * vbrk * A pointer to an array of 2 elements * in which to return the X and Y components of a unit vector in the * graphics coordinate system. The vector is tangential to the curve * at the requested break, and points back along the drawn section of * the curve. * len * A pointer to a "double" in which to return the * length of the drawn curve, in the graphics coordinate system. * Returned Value: * astCvBrk() * The number of breaks which occurred in the curve. * Notes: * - Currently, this function may not be used to return information * about curves drawn using astPolyCurve. * - All curves contain at least two breaks; one at the start and one * at the end. This is true even if the start and end of the curve are * coincident. However, if the entire curve was outside the plotting area * (i.e. if the length of the drawn curve is zero), then it will have no * breaks. * - If no curve has yet been drawn by astGridLine or astCurve, then -1 is * returned for the function value, and the function parameter values are * left unchanged. * - The returned information refers to the most recent curve drawn by * astGridLine or astCurve, even if that curve was drawn by a Plot other than * the one supplied to this function. * - NULL pointers may be supplied for "brk", "vbrk" or "len", in which * case the corresponding values are not returned. * - Zero is returned by this function if an error has already occurred, * or if this function should fail for any reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int ret; /* The number of breaks in the curve. */ /* Check the global status. */ if( !astOK ) return 0; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Information about the most recent curve drawn by astGridLine or astCurve is stored in the external structure "Curve_data". Get the number of breaks in the last curve. This is initialised to -1 in astInitPlot when the virtual function table for this class is initialised. */ ret = Curve_data.nbrk; /* If a curve has been drawn, store the length of the drawn curve if required. */ if( ret != -1 ){ if( len ) *len = (double) Curve_data.length; /* If a legal break index has been supplied, return the position and direction at the requested break (if required). */ if( ibrk > 0 && ibrk <= ret ){ if( brk ){ brk[ 0 ] = (double) Curve_data.xbrk[ ibrk - 1 ]; brk[ 1 ] = (double) Curve_data.ybrk[ ibrk - 1 ]; } if( vbrk ){ vbrk[ 0 ] = (double) Curve_data.vxbrk[ ibrk - 1 ]; vbrk[ 1 ] = (double) Curve_data.vybrk[ ibrk - 1 ]; } /* If an illegal break index has been supplied (other than zero), report an error, and set the number of breaks to zero. */ } else if( ibrk ){ if( ret > 0 ){ astError( AST__BDBRK, "astCvBrk(%s): The supplied break index " "(%d) should be in the range [1,%d].", status, astGetClass(this), ibrk, ret ); ret = 0; } else { astError( AST__BDBRK, "astCvBrk(%s): The most recent curve " "plotted by method astGridLine or astCurve had no breaks.", status, astGetClass(this) ); } } } /* If an error has occurred, return 0. */ if( !astOK ) ret = 0; /* Return the result. */ return ret; } static void CrvLine( AstPlot *this, double xa, double ya, double xb, double yb, const char *method, const char *class, int *status ){ /* * Name: * CrvLine * Purpose: * Draw a straight line between two points, with clipping. * Type: * Private function. * Synopsis: * #include "plot.h" * void CrvLine( AstPlot *this, double xa, double ya, double xb, double yb, * const char *method, const char *class ) * Class Membership: * Plot member function. * Description: * This functions draws a straight line from (xa,ya) to (xb,yb), breaking * the line at the edges of the plotting area defined by Crv_xlo, Crv_xhi, * Crv_ylo and Crv_yhi if Crv_clip is non-zero. If the line does not start * at the end of the previous line plotted by this function, then * information describing the break in the curve is stored in external * arrays. * Parameters: * xa * The graphics X coordinate at the start of the line. * ya * The graphics Y coordinate at the start of the line. * xb * The graphics X coordinate at the end of the line. * yb * The graphics Y coordinate at the end of the line. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * External Variables: * Crv_ink = int (Read) * If zero then no line is drawn even if the line intersects the * plotting space, but break information (etc) is still returned. * Crv_clip = double (Read) * Clip lines at boundary of plotting space? * Crv_xlo = double (Read) * Lower x limit of the plotting space. * Crv_xhi = double (Read) * Upper x limit of the plotting space. * Crv_ylo = double (Read) * Lower y limit of the plotting space. * Crv_yhi = double (Read) * Upper y limit of the plotting space. * Crv_tol = double (Read) * The tolerance for determining if 2 points are coincident. * Crv_out = int (Read/Write) * Returned as zero if the line intersects the plotting space. * Unchanged otherwise. * Crv_xbrk = float * (Read/Write) * Pointer to the next available element in an array of AST__PLOT_CRV_MXBRK * values containing the graphics X coordinates at which each break * in the plotted curve occurred. A break is recorded if the starting * point of the current line is not the same as the end point of * the previous line. * Crv_ybrk = float * (Read/Write) * Pointer to the next available element in an array of AST__PLOT_CRV_MXBRK * values containing the graphics Y coordinates at which each break * in the plotted curve occurred. * Crv_vxbrk = float * (Read/Write) * Pointer to the next available element in an array of AST__PLOT_CRV_MXBRK * values containing the X component of the unit vector (within the * graphics coordinate system) parallel to the tangent to the curve * at each break. The sense is such that the vector always points back * along the plotted section of the curve. * Crv_vybrk = float * (Read/Write) * Pointer to the next available element in an array of AST__PLOT_CRV_MXBRK * values containing the Y component of the unit vector parallel to * the tangent to the curve at each break. * Crv_nbrk = int (Write) * The number of breaks for which information is returned in Crv_xbrk, * etc. * Crv_len = float (Write) * The length of the section of the curve which has been drawn so far. * Crv_xl = double (Write) * The graphics X coordinate at the end of the last line drawn. * Crv_yl = double (Write) * The graphics Y coordinate at the end of the last line drawn. * Crv_vxl = double (Write) * The X component of the unit vector along the last line drawn. * Crv_vyl = double (Write) * The Y component of the unit vector along the last line drawn. * Grf_alpha = float (Read) * The factor for scaling graphics X axis values into equal scaled * X axis values. * Grf_beta = float (Read) * The factor for scaling graphics Y axis values into equal scaled * Y axis values. */ /* local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double a1; /* Distance from B to the lower x boundary */ double a2; /* Distance from B to the upper x boundary */ double a3; /* Distance from B to the lower y boundary */ double a4; /* Distance from B to the upper y boundary */ double aamax; /* Distance from supplied point B to the plotable point A */ double aamin; /* Distance from supplied point B to the plotable point B */ double dl; /* Length of plotted line segment */ double dx; /* Difference in x between supplied points */ double dy; /* Difference in y between supplied points */ double t; /* Temporary storage */ double xam; /* Modified xa position */ double xbm; /* Modified xb position */ double yam; /* Modified ya position */ double ybm; /* Modified yb position */ int plot; /* True if a line can be plotted */ /* Check inherited global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ dl = 0.0; xam = 0.0; xbm = 0.0; yam = 0.0; ybm = 0.0; /* Store the shifts in x and y. */ dx = xb - xa; dy = yb - ya; /* Do nothing if the line is of zero length. */ if( dx == 0.0 && dy == 0.0 ) return; /* If either end is outside the zone, replace the given coordinates with the end coordinates of the section of the line which lies within the zone. */ if( Crv_clip && ( xa < Crv_xlo || xa > Crv_xhi || xb < Crv_xlo || xb > Crv_xhi || ya < Crv_ylo || ya > Crv_yhi || yb < Crv_ylo || yb > Crv_yhi ) ){ /* Find the distance from point B towards point A at which the line cuts the two x bounds of the zone (distance at point B is 0.0, and at point A is 1.0). */ if( dx != 0.0 ){ a1 = ( xb - Crv_xlo )/dx; a2 = ( xb - Crv_xhi )/dx; /* Ensure that a1 represents the highest plottable offset, and a2 the lowest. */ if( a1 < a2 ){ t = a1; a1 = a2; a2 = t; } /* If the line joining A and B is vertical... */ } else { /* If the line is within the plottable x range, indicate that all offsets are plottable (as far as the x range is concerned at least). */ if( ( xa > Crv_xlo || astEQUALS( xa, Crv_xlo, 1.0E8 ) ) && ( xa < Crv_xhi || astEQUALS( xa, Crv_xhi, 1.0E8 ) ) ){ a1 = DBL_MAX; a2 = -DBL_MAX; /* If the line is ouside the plottable x range, indicate that no offsets are plottable. */ } else { a1 = 0.0; a2 = 0.0; } } /* Find the fractional distance from point A to point B at which the line cuts the two y bounds of the zone. */ if( dy != 0.0 ){ a3 = ( yb - Crv_ylo )/dy; a4 = ( yb - Crv_yhi )/dy; /* Ensure that a3 represents the highest plottable offset, and a4 the lowest. */ if( a3 < a4 ){ t = a3; a3 = a4; a4 = t; } /* If the line joining A and B is horizontal... */ } else { /* If the line is within the plottable y range, indicate that all offsets are plottable (as far as the y range is concerned at least). */ if( ( ya > Crv_ylo || astEQUALS( ya, Crv_ylo, 1.0E8 ) ) && ( ya < Crv_yhi || astEQUALS( ya, Crv_yhi, 1.0E8 ) ) ){ a3 = DBL_MAX; a4 = -DBL_MAX; /* If the line is ouside the plottable y range, indicate that no offsets are plottable. */ } else { a3 = 0.0; a4 = 0.0; } } /* Find the fractional distances from point A to point B at the ends of the plotable line. */ aamin = astMIN( 1.0, astMAX( 0.0, astMAX( a2, a4 ) ) ); aamax = astMAX( 0.0, astMIN( 1.0, astMIN( a1, a3 ) ) ); /* Store the end coordinates of the line joining the plotable points. */ if( aamax > aamin ){ xam = xb - aamax*dx; yam = yb - aamax*dy; xbm = xb - aamin*dx; ybm = yb - aamin*dy; plot = 1; /* Get the unit vector along the line and the length of the plotted section. */ dx *= Grf_alpha; dy *= Grf_beta; dl = sqrt( dx*dx + dy*dy ); dx /= dl; dy /= dl; dl *= astMAX( 0.0, aamax - aamin ); /* Clear the "plot" flag if the line does not intersect the plotting area. */ } else { plot = 0; } /* If both ends of the line are within the plotting zone, draw the whole line between the supplied end points. */ } else { xam = xa; yam = ya; xbm = xb; ybm = yb; plot = 1; /* Get the length of the line and the unit vector along the line. */ dx *= Grf_alpha; dy *= Grf_beta; dl = sqrt( dx*dx + dy*dy ); dx /= dl; dy /= dl; } /* If a line is to be plotted... */ if( plot ){ /* If this is the first line to be plotted in the current curve, save the start of the line as a break, and indicate that some of the curve falls within the plotting zone. */ if( Crv_out ){ Crv_nbrk = 1; *(Crv_xbrk++) = (float) xam; *(Crv_ybrk++) = (float) yam; *(Crv_vxbrk++) = (float) dx; *(Crv_vybrk++) = (float) dy; Crv_out = 0; /* Set the length of the curve plotted so far to the length of this first segment. */ Crv_len = (float) dl; /* Start a poly line. */ if( Crv_ink ) Bpoly( this, (float) xam, (float) yam, status ); /* If this is not the first line to be plotted... */ } else { /* ... increment the length of the curve plotted so far. */ Crv_len += (float) dl; /* If the start of this line is not coincident with the end of the previous line, save the previous and current positions as breaks in the curve. Note, the previous vector is reversed so that it points back towards the drawn section of the curve. Report an error if the arrays are full. */ if( fabs( xam - Crv_xl ) > Crv_tol || fabs( yam - Crv_yl ) > Crv_tol ){ Crv_nbrk += 2; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in plotted " "curve exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; *(Crv_xbrk++) = (float) xam; *(Crv_ybrk++) = (float) yam; *(Crv_vxbrk++) = (float) dx; *(Crv_vybrk++) = (float) dy; } /* Start a poly line. */ if( Crv_ink ) Bpoly( this, (float) xam, (float) yam, status ); } } /* Append a section to the current poly line. */ if( Crv_ink ) Apoly( this, (float) xbm, (float) ybm, status ); /* Save the position and vector at the end of the current line. */ Crv_xl = xbm; Crv_yl = ybm; Crv_vxl = dx; Crv_vyl = dy; } /* Return. */ return; } static void Curve( AstPlot *this, const double start[], const double finish[], int *status ){ /* *++ * Name: c astCurve f AST_CURVE * Purpose: * Draw a geodesic curve. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astCurve( AstPlot *this, const double start[], c const double finish[] ) f CALL AST_CURVE( THIS, START, FINISH, STATUS ) * Class Membership: * Plot method. * Description: c This function draws a geodesic curve between two points in the f This routine draws a geodesic curve between two points in the * physical coordinate system of a Plot. The curve drawn is the * path of shortest distance joining the two points (as defined by c the astDistance function for the current Frame of the Plot). f the AST_DISTANCE function for the current Frame of the Plot). * For example, if the current Frame is a basic Frame, then the * curve joining the two points will be a straight line in physical * coordinate space. If the current Frame is more specialised and * describes, for instance, a sky coordinate system, then the * geodesic curve would be a great circle in physical coordinate * space passing through the two sky positions given. * * Note that the geodesic curve is transformed into graphical * coordinate space for plotting, so that a straight line in * physical coordinates may result in a curved line being drawn if * the Mapping involved is non-linear. Any discontinuities in the * Mapping between physical and graphical coordinates are c catered for, as is any clipping established using astClip. f catered for, as is any clipping established using AST_CLIP. * c If you need to draw many geodesic curves end-to-end, then the c astPolyCurve function is equivalent to repeatedly using c astCurve, but will usually be more efficient. f If you need to draw many geodesic curves end-to-end, then the f AST_POLYCURVE routine is equivalent to repeatedly calling f AST_CURVE, but will usually be more efficient. * c If you need to draw curves which are not geodesics, see astGenCurve c or astGridLine. f If you need to draw curves which are not geodesics, see AST_GENCURVE f or AST_GRIDLINE. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c start f START( * ) = DOUBLE PRECISION (Given) * An array, with one element for each axis of the Plot, giving * the physical coordinates of the first point on the geodesic * curve. c finish f FINISH( * ) = DOUBLE PRECISION (Given) * An array, with one element for each axis of the Plot, giving * the physical coordinates of the second point on the geodesic * curve. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - No curve is drawn if either of the "start" or "finish" arrays c contains any coordinates with the value AST__BAD. f - No curve is drawn if either of the START or FINISH arrays f contains any coordinates with the value AST__BAD. * - An error results if the base Frame of the Plot is not 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *class; /* Object class */ const char *method; /* Current method */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astCurve"; class = astGetClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Initialise the bounding box for primitives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Draw the curve. The break information is stored in an external structure where it can be accessed by public methods which return information about the most recently drawn curve. */ CurvePlot( this, start, finish, 1, &Curve_data, method, class, status ); /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); /* Return. */ return; } static void CurvePlot( AstPlot *this, const double *start, const double *finish, int ink, AstPlotCurveData *cdata, const char *method, const char *class, int *status ){ /* * * Name: * CurvePlot * Purpose: * Draw a geodesic curve. * Type: * Private function. * Synopsis: * #include "plot.h" * void CurvePlot( AstPlot *this, const double *start, const double *finish, * int ink, AstPlotCurveData *cdata, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws a geodesic curve between the supplied starting and * finishing positions. The algorithm used can handle discontinuities in the * Mapping between the current Frame and graphics coordinates, and * information describing any breaks in the curve (including the start and * end of the curve) are returned in the supplied AstPlotCurveData structure. * Parameters: * this * Pointer to the Plot. * start * A pointer to a an array holding the coordinates of the start of the * curve within the current Frame of the Plot. * finish * A pointer to a an array holding the coordinates of the finish of the * curve within the current Frame of the Plot. * ink * If zero, the curve is not actually drawn, but information about * the breaks is still returned. If non-zero, the curve is also drawn. * cdata * A pointer to a structure in which to return information about the * breaks in the curve. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - No curve is draw if the "start" or "finish" arrays contains any bad * values, or if a NULL pointer is supplied for "cdata". No errors are * reported in these cases. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ double tol; /* Absolute tolerance value */ int i; /* Loop count */ int naxes; /* No. of axes in the base Frame */ int ok; /* Are all start coords good? */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Get the number of axes in the current Frame. */ naxes = astGetNout( this ); /* Check the "start" and "finish" parameter for bad values. */ ok = 1; for( i = 0; i < naxes; i++ ) { if( start[ i ] == AST__BAD || finish[ i ] == AST__BAD ){ ok = 0; break; } } /* Check that the "cdata" pointer can be used. */ if( !cdata ) ok = 0; /* Only proceed if the parameters are OK, and there has been no error. */ if( ok && astOK ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__CURVE_ID, 1, GRF__LINE, method, class ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Set up the externals used to communicate with the Map3 function... The number of axes in the physical coordinate system (i.e. the current Frame). */ Map3_ncoord = naxes; /* A pointer to the Plot, the Curretn Frame, and and Mapping. */ Map3_plot = this; Map3_frame = astGetFrame( this, AST__CURRENT ); Map3_map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* The physical coordinates at the start of the curve. */ Map3_origin = start; /* The physical coordinates at the end of the curve. */ Map3_end = finish; /* The scale factor to convert "dist" values into physical offset values. */ Map3_scale = astDistance( Map3_frame, start, finish ); /* Convert the tolerance from relative to absolute graphics coordinates. */ tol = astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Now set up the external variables used by the Crv and CrvLine function. */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_ux0 = AST__BAD; Crv_tol = tol; Crv_limit = 0.5*tol*tol; Crv_map = Map3; Crv_ink = ink; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_out = 1; Crv_xbrk = cdata->xbrk; Crv_ybrk = cdata->ybrk; Crv_vxbrk = cdata->vxbrk; Crv_vybrk = cdata->vybrk; Crv_clip = astGetClip( this ) & 1; /* Set up a list of points spread evenly over the curve. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Map these points into graphics coordinates. */ Map3( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map3 to draw the curve. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* End the current poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map3. */ Map3( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* If no part of the curve could be drawn, set the number of breaks and the length of the drawn curve to zero. */ if( Crv_out ) { Crv_nbrk = 0; Crv_len = 0.0F; /* Otherwise, add an extra break to the returned structure at the position of the last point to be plotted. */ } else { Crv_nbrk++; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; } } /* Store extra information about the curve in the returned structure, and purge any zero length sections. */ if( cdata ){ cdata->length = Crv_len; cdata->out = Crv_out; cdata->nbrk = Crv_nbrk; PurgeCdata( cdata, status ); } /* Annul the Frame and Mapping. */ Map3_frame = astAnnul( Map3_frame ); Map3_map = astAnnul( Map3_map ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__CURVE_ID, 0, GRF__LINE, method, class ); } /* Return. */ return; } static AstPointSet *DefGap( AstPlot *this, double *gaps, int *ngood, double *frac, int *inval, const char *method, const char *class, int *status ){ /* * Name: * DefGap * Purpose: * Find default gap sizes for the tick marks on the axes of a 2-D * physical coordinate system. * Type: * Private function. * Synopsis: * #include "plot.h" * AstPointSet *DefGap( AstPlot *this, double *gaps, int *ngood, * double *frac, int *inval, const char *method, * const char *class, int *status ) * Class Membership: * Plot method. * Description: * This function returns default gap sizes for each axis in a 2-D Frame. * The values are found by first obtaining a grid of points spread over * the region containing good physical coordinates. The physical * coordinate values (non-normalized) for each axis are sorted into * increasing order. * * For linearly spaced tick marks, a set of quantile axis values is then * found, and the median of the gaps between these quantiles is returned * as the default gap for the axis. * * For logarithmically spaced tick marks, the returned gap size is the * ratio between adjacent tick mark values, chosen to give an optimal * number of ticks between the maximum and minimum axis values found in * the grid. * Parameters: * this * Pointer to a Plot. * gaps * Pointer to an array in which to return the default gap value for * each axis. * ngood * Pointer to an array in which toi return the number of good * values in the returned PointSet for each axis. * frac * Pointer to a double in which to return the fraction of the * plotting area containing good physical coordinates. * inval * Pointer to a location at which to return a flag indicating if * any bad physical coordinates were encountered. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a PointSet holding the physical coordinate values at a * set of points spread across the plotting area. The values on each * axis are sorted into increasing order. The values will not have * been normalized. * Notes: * - The returned PointSet should be annulled when no longer needed. * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - Gap sizes of 1.0, zero good points, and a NULL pointer are returned * if an error has already occurred, or if this function should fail for * any reason. */ /* Local Variables: */ AstPointSet *pset1; /* Pointer to PointSet holding graphics coords */ AstPointSet *pset2; /* Pointer to PointSet holding physical coords */ double **ptr1; /* Pointer to graphics axis values */ double **ptr2; /* Pointer to physical axis values */ double dran; /* Dynamic range */ double maxv; /* Maximum axis value */ double minv; /* Minimum axis value */ double qgap[ MAJTICKS_OPT ];/* Gaps between physical coordinate quantiles */ int dim; /* Dimension of grid */ int dk; /* The number of points between quantiles */ int i; /* The quantile index */ int j; /* Axis index */ int k; /* Index into the sorted array of axis values */ int logticks; /* Logarithmically spaced tick marks? */ int n; /* Target number fo ticks */ int psize; /* Total number of axis value */ /* Initialise the returned values. */ gaps[ 0 ] = 1.0; gaps[ 1 ] = 1.0; ngood[ 0 ] = 0; ngood[ 1 ] = 0; *frac = 0.0; *inval = 0; /* Check global status. */ if( !astOK ) return NULL; /* Get two PointSets, one holding a grid of 2D graphics coordinates, and one holding the corresponding (non-normalized) physical coordinates. */ dim = 0; *frac = GoodGrid( this, &dim, &pset1, &pset2, method, class, status ); /* Get pointers to the data values in each PointSet. */ ptr1 = astGetPoints( pset1 ); ptr2 = astGetPoints( pset2 ); /* Store the number of elements in each PointSet. */ psize = astGetNpoint( pset1 ); /* For each axis... */ for( j = 0; j < 2 && astOK; j++ ){ /* Sort the axis values into increasing order. Any bad values are stored at the end of the array on return. */ qsort( (void *) ptr2[ j ], (size_t) psize, sizeof(double), Compared ); /* Count the number of non-bad values returned. */ ngood[ j ] = CountGood( psize, ptr2[ j ], status ); /* Set the returned flag to indicate if any bad values were found. */ if( ngood[ j ] < psize ) *inval = 1; /* Report an error if there are too few good points. */ if( ngood[ j ] < MAJTICKS_OPT ){ astError( AST__VSMAL, "%s(%s): The range of coordinate values " "covered by axis %d is too small to plot.", status, method, class, j + 1 ); break; } /* Get the maximum and minimum axis value */ minv = ptr2[ j ][ 0 ]; maxv = ptr2[ j ][ ngood[ j ] - 1 ]; /* See if ticks on this axis are spaced linearly or logarithmically. If a value has been set for LogTicks used it, otherwise find a default value. The default is 0 unless LogPlot is non-zero, the axis range does not encompass zero and and the dynamic range is 90 or more. Set this default value explicitly so that later functions will pick it up (it will be cleared at the end of the astGrid function). */ if( astTestLogTicks( this, j ) ) { logticks = astGetLogTicks( this, j ); } else { logticks = 0; if( astGetLogPlot( this, j ) && minv*maxv > 0.0 ) { dran = maxv/minv; if( dran >= 90.0 || dran <= 1.0/90.0 ) logticks = 1; } astSetLogTicks( this, j, logticks ); } /* If no value has been supplied for LogLabel use the value of LogTicks as the default. */ if( !astTestLogLabel( this, j ) ) astSetLogLabel( this, j, logticks ); /* For linear gaps, find the gaps between adjacent evenly spaced quantiles. The number of quantiles used equals the optimal number of major tick marks. */ if( !logticks ) { dk = (int)( (double)ngood[ j ]/MAJTICKS_OPT ); i = 0; for( k = dk; k < ngood[ j ] && i < MAJTICKS_OPT; k += dk ){ qgap[ i++ ] = ptr2[ j ][ k ] - ptr2[ j ][ k - dk ]; } /* Find the median of the gaps between adjacent quantiles. */ qsort( (void *) qgap, (size_t) i, sizeof(double), Compared ); gaps[ j ] = qgap[ i/2 ]; /* If the test gap size is zero, use a fraction of the total range. Report an error if the total range is zero. */ if( gaps[ j ] <= 0.0 ){ gaps[ j ] = ( ptr2[ j ][ ngood[ j ] - 1 ] - ptr2[ j ][ 0 ] )/MAJTICKS_OPT;; if( gaps[ j ] <= 0.0 ){ astError( AST__VSMAL, "%s(%s): The range of coordinate values " "covered by axis %d is too small to plot.", status, method, class, j + 1 ); } } /* For logarithmic gaps, use the Nth root of the ratio of the maximum and minimum data value found. */ } else if( astOK ) { /* Report an error if the max and min values are of opposite signs or zero or equal. */ if( maxv*minv <= 0.0 ) { astError( AST__ZERAX, "%s(%s): The range of coordinate values " "covered by axis %d includes the origin and so " "logarithmic ticks cannot be produced.", status, method, class, j + 1 ); } else if( maxv == minv ) { astError( AST__VSMAL, "%s(%s): The range of coordinate values " "covered by axis %d is too small to plot.", status, method, class, j + 1 ); /* Otherwise find the gap to use. */ } else { /* Store the maximum and minimum number of major tick marks along each axis. These numbers are reduced if only a small part of the plotting area contains valid coordinates, so that the tick marks do not end up to close together. */ n = (int) ( 0.5 + MAJTICKS_OPT*sqrt( *frac ) ); if( n < 5 ) n = 5; /* Choose a gap size which makes this many gaps. */ gaps[ j ] = pow( maxv/minv, 1.0/( n - 1.0 ) ); } } } /* Annul the PointSet holding Graphics coordinates. */ pset1 = astAnnul( pset1 ); /* If an error has occurred, annul the PointSet holding physical coordinates, and return gaps of 1.0. */ if( !astOK ) { pset2 = astAnnul( pset2 ); gaps[ 0 ] = 1.0; gaps[ 1 ] = 1.0; ngood[ 0 ] = 0; ngood[ 1 ] = 0; *frac = 0.0; *inval = 0; } /* Return the physical PointSet. */ return pset2; } static void DrawAxis( AstPlot *this, TickInfo **grid, double *labelat, double *gap, const char *method, const char *class, int *status ){ /* * * Name: * DrawAxis * Purpose: * Draw a curve joining the major tick marks. * Type: * Private function. * Synopsis: * #include "plot.h" * void DrawAxis( AstPlot *this, TickInfo **grid, double *labelat, * double *gap, const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws a curve through interior tick marks on both axes. * The curve is drawn even if it has already been drawn as part of a * grid of curves, because it may have been assigned different graphics * attributes to the grid curves. * Parameters: * this * A pointer to the Plot. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick marks on the axis. See function GridLines. * labelat * A pointer to a 2 element array giving the constant axis values at * which tick marks are put. Element 0 should give the axis 1 value at * which tick marks for axis 0 are placed. Element 1 should give the * axis 0 value at which tick marks for axis 1 are placed. * gap * Pointer to array of two values holding the gap between major * tick marks on the two axes. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This function assumes the current Frame of the Plot is 2 * dimensional, and it should not be called if this is not the case. */ /* Local Variables: */ AstFrame *frm; /* Pointer to current Frame */ AstPlotCurveData cdata;/* Somewhere to put the unneeded curve information */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ double *value; /* Current tick value */ double bot; /* Lowest axis value to be displayed */ double diff; /* Difference between adjacent tick marks */ double udiff; /* Used section length */ double start[ 2 ]; /* The start of the curve in physical coordinates */ double tmp; /* Temporary storage */ double top; /* Highest axis value to be displayed */ int axis; /* Current axis index */ int axisid; /* ID value for current axis plotting attributes */ int logticks; /* Are major ticks spaced logarithmically? */ int tick; /* Current tick index */ /* Check the global status. */ if( !astOK ) return; /* Not the id value for the first axis. */ axisid = AST__AXIS1_ID; /* Get a pointer to the current Frame. */ frm = astGetFrame( this, AST__CURRENT ); /* Consider drawing a curve parallel to each axis in turn. */ for( axis = 0; axis < 2; axis++ ){ /* Establish the correct graphical attributes for this axis as defined by attributes with the supplied Plot. */ astGrfAttrs( this, axisid, 1, GRF__LINE, method, class ); /* Check the axis is required. */ if( astGetDrawAxes( this, axis ) ){ /* If the tick marks have been placed round the edges of the plotting area, we do not need to draw the curves. */ if( labelat[ axis ] != AST__BAD ){ /* Get the max and min values allowed on this axis. */ bot = astGetBottom( frm, axis ); top = astGetTop( frm, axis ); if( bot > top ) { tmp = top; top = bot; bot = tmp; } /* Get a pointer to the structure containing information describing the positions of the major tick marks along the current axis. */ info = grid[ axis ]; /* Get a pointer to the axis value at the first major tick mark. */ value = info->ticks; /* See if the major tick marks are logarithmically spaced on this axis. */ logticks = astGetLogTicks( this, axis ); /* Initialise the difference between major tick marks. */ diff = logticks ? 0.0 : gap[ axis ]; /* Loop round all ticks. */ for( tick = 0; tick < info->nmajor; tick++, value++ ){ /* Update the difference between major tick marks if we are producing logarithmically spaced ticks (in which "gap" is a ratio, not a difference). */ if( logticks ) diff = (*value)*( gap[ axis ] - 1.0 ); /* Note the starting point for this section. */ start[ axis ] = *value; start[ 1 - axis ] = labelat[ axis ]; /* If this is the first tick, draw an axis section going "backwards" in case the first tick isn't at the lower visible bound. Limit the length of this backwards section so that it does not extend beyond the minimum axis value. */ if( tick == 0 ) { udiff = *value - bot; if( udiff > diff ) udiff = diff; if( udiff > 0.0 ) { AxPlot( this, axis, start, -udiff, 1, &cdata, method, class, status ); } } /* Limit the length of the section so that it does not extend beyond the maximum axis value. */ udiff = ( *value + diff > top ) ? top - *value : diff; /* Do not draw zero length sections. */ if( udiff > 0.0 ) { /* Draw a curve parallel to the current axis, starting at the tick mark, with length equal to the gap between tick marks. Do not draw sections of the curve which are outside the primary domains of the physical axes. */ AxPlot( this, axis, start, udiff, 1, &cdata, method, class, status ); } } /* Once the last section has been drawn, draw another axis section in case the last tick isn't at the upper visible bound. Limit the length of this section so that it does not extend beyond the maximum axis value. */ udiff = top - start[ axis ]; if( udiff > diff ) udiff = diff; if( udiff > 0.0 ) { AxPlot( this, axis, start, udiff, 1, &cdata, method, class, status ); } } } /* Re-establish the original graphical attributes. */ astGrfAttrs( this, axisid, 0, GRF__LINE, method, class ); /* Set up the id value for the next axis. */ axisid = AST__AXIS2_ID; } /* Free the pointer to the current Frame. */ frm = astAnnul( frm ); } static AstPlotCurveData **DrawGrid( AstPlot *this, TickInfo **grid, int drawgrid, const char *method, const char *class, int *status ){ /* * Name: * DrawGrid * Purpose: * Draw a grid of lines at the major tick mark positions on both axes. * Type: * Private function. * Synopsis: * #include "plot.h" * AstPlotCurveData **DrawGrid( AstPlot *this, TickInfo **grid, int drawgrid, * const char *method, const char *class ) * Class Membership: * Plot method. * Description: * This function draw a grid of curves at the major tick mark * positions on both axes, and returns information describing the * breaks in the curves. If short tick marks are required rather * than long curves (as specified by the Grid attribute of the supplied * Plot), then the curves are not drawn but the break information is * still returned. * Parameters: * this * Pointer to a Plot. * grid * A pointer to an array of two pointers (one for each axis), each * pointing to a TickInfo structure. These describe the positions * of the tick marks and should have been produced by function * GridLines. * drawgrid * If non-zero, draw a grid of curves marking the major axis * values. Otherwise, tick marks will be drawn at these values later. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * Returned Value: * A pointer to an array of two AstPlotCurveData pointers (one for each axis), * each pointing to an array of AstPlotCurveData structures (one for each tick * value). * Notes: * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned. */ /* Local Variables: */ AstPlotCurveData **cdata;/* The returned pointer */ AstPlotCurveData *cdt; /* Pointer to break info. for current tick mark */ AstPlotCurveData tcdt; /* Pointer to break info. for current curve section */ TickInfo *info; /* Tick mark information for a single axis */ double start[ 2 ]; /* Strting position for current curve section */ double total_length; /* Total curve length for all axis ticks */ int i; /* Axis index */ int j; /* Tick mark index */ int k; /* Curve section index */ /* Check the global status. */ if( !astOK ) return NULL; /* Allocate memory to hold two pointers, each pointing to an array of AstPlotCurveData structure. */ cdata = (AstPlotCurveData **) astMalloc( 2*sizeof( AstPlotCurveData *) ); /* If succesful, initialise the pointers. */ if( astOK ){ cdata[ 0 ] = NULL; cdata[ 1 ] = NULL; /* Draw the curves marking the major tick values on each axis. If no grid is required, we still do this in order to get information about the breaks in the curves which will be used later to decide where to put the labels, but we use "invisible ink". */ for( i = 0; i < 2; i++ ){ /* Get a pointer to the TickInfo structure for this axis holding information about where to put tick marks on this axis. */ info = grid[ i ]; /* Allocate memory to hold information describing the breaks in each tick mark curve. This takes the form of an array of AstPlotCurveData structures, one for each tick mark. */ cdata[ i ] = (AstPlotCurveData *) astMalloc( sizeof(AstPlotCurveData)* (size_t) info->nmajor ); /* Check the pointer can be used. */ if( astOK ){ /* Initialise a pointer to the first AstPlotCurveData structure for this axis. */ cdt = cdata[ i ]; total_length = 0.0; /* Do each tick mark. */ for( j = 0; j < info->nmajor; j++ ){ /* Store the starting point of the first section of the curve. */ start[ i ] = (info->ticks)[ j ]; start[ 1 - i ] = (info->start)[ 0 ]; /* Draw the first section of the curve parallel to the other axis, starting at the values in "start", and extending for a length given in the TickInfo structure. We use invisible ink if short tick marks are required instead of a grid of curves. */ AxPlot( this, 1 - i, start, (info->length)[ 0 ], drawgrid, cdt, method, class, status ); /* Now draw any other sections in the curve. */ for( k = 1; k < info->nsect; k++ ){ /* Modify the starting value on the other axis. The starting value on the current axis remains set to the tick mark value. */ start[ 1 - i ] = (info->start)[ k ]; /* Draw the curve, the information describing the breaks goes into temporary storage in the local structure "tcdt". */ AxPlot( this, 1 - i, start, (info->length)[ k ], drawgrid, &tcdt, method, class, status ); /* Concatenate the break information for this section with the break information describing the previous sections. */ AddCdt( cdt, &tcdt, method, class, status ); } /* Increment the total length of curves drawn for all ticks on this axis. */ total_length += cdt->length; /* Point to the AstPlotCurveData structure for the next tick mark. */ cdt++; } /* Report an error if the total length of all curves on this axis is zero. This can be caused for instance by bugs in the algorithm for finding major tick values (which may cause AST__BAD tick mark values). */ if( total_length == 0.0 && astOK ) { astError( AST__INTER, "%s(%s): No grid curves can be drawn for " "axis %d.", status, method, class, i + 1 ); } } } } /* If an error has occurred, clean up the returned structures. */ if( !astOK ) cdata = CleanCdata( cdata, status ); /* Return. */ return cdata; } static int DrawRegion( AstPlot *this, AstFrame *frm, const char *method, const char *class, int *status ){ /* * * Name: * DrawRegion * Purpose: * Draw the outline of a Region. * Type: * Private function. * Synopsis: * #include "plot.h" * int DrawRegion( AstPlot *this, AstFrame *frm, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * If the current Frame in the supplied Plot is a Region, this function * draws a curve marking the outline of the Region. It returns without * action otherwise. * Parameters: * this * Pointer to the Plot. * frm * Pointer to the current Frame in the Plot (possibly a Region). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if and only if a Region outline was drawn. */ /* Local Variables: */ AstMapping *map; /* Mapping with Region masking included */ AstPlotCurveData cdata; /* Stores information about curve breaks */ AstRegion **comps; /* List of component Regions */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double tol; /* Absolute tolerance value */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ int i; /* Loop count */ int icomp; /* Index of component Region */ int ncomp; /* Number of component Regions */ int result; /* The returned value */ /* Initialise */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Check the current Frame is a Region, and is of a class that implements the astRegTrace method. */ if( astIsARegion( frm ) && astRegTrace( (AstRegion *) frm, 0, NULL, NULL ) ){ /* Set up the externals used to communicate with the Map5 function... The number of axes in the physical coordinate system (i.e. the Region). */ Map5_ncoord = astGetNaxes( frm ); /* A pointer to the Plot, the Region, and the Mapping. */ Map5_plot = this; Map5_region = (AstRegion *) frm; /* Also store a pointer to the Mapping, ensuring that the Mapping does not contain any masking effects from the Region. */ map = astGetMapping( this, AST__BASE, AST__CURRENT ); Map5_map = astRemoveRegions( map ); map = astAnnul( map ); /* Convert the tolerance from relative to absolute graphics coordinates. Make the tolerance smaller by a factor of 10 because Regions (specifically Polygonsd) can have very crinkly edges. */ tol = 0.1* astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Now set up the external variables used by the Crv and CrvLine function. */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_ux0 = AST__BAD; Crv_tol = tol; Crv_limit = 0.5*tol*tol; Crv_map = Map5; Crv_ink = 1; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_out = 1; Crv_xbrk = cdata.xbrk; Crv_ybrk = cdata.ybrk; Crv_vxbrk = cdata.vxbrk; Crv_vybrk = cdata.vybrk; Crv_clip = astGetClip( this ) & 1; /* Attempt to split the Region into a set of disjoint component Regions. */ comps = astRegSplit( (AstRegion *) frm, &ncomp ); /* Draw each one. */ for( icomp = 0; icomp < ncomp; icomp++ ) { /* A pointer to the Region. */ Map5_region = comps[ icomp ]; /* Set up a list of points spread evenly over the curve. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Map these points into graphics coordinates. */ Map5( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map5 to draw the curve. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* End the current poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map5. */ Map5( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* Annul the component Region pointer. */ comps[ icomp ] = astAnnul( Map5_region ); } /* Free the memory holding the list of component Region pointers. */ comps = astFree( comps ); /* Annul the Mapping. */ Map5_map = astAnnul( Map5_map ); /* Indicate the outline was drawn. */ result = 1; } /* Return. */ return result; } static void DrawText( AstPlot *this, int ink, int esc, const char *text, float x, float y, const char *just, float upx, float upy, float *xbn, float *ybn, float *drop, const char *method, const char *class, int *status ){ /* * Name: * DrawText * Purpose: * Draw a character string, potentially including superscripts and * subscripts. * Synopsis: * #include "plot.h" * void DrawText( AstPlot *this, int ink, int esc, const char *text, * float x, float y, const char *just, float upx, * float upy, float *xbn, float *ybn, float *drop, * const char *method, const char *class, int *status ) * Description: * This function displays a character string at a given position * using a specified up-vector, optionally interpreting any Plot escape * sequences contained within the text. It also returns its bounding * box. * Parameters: * this * The plot. * ink * If zero, nothing is drawn but the bounding box is still returned. * esc * Should escape sequences be interpreted? They will be printed * literally otherwise. * text * Pointer to a null-terminated character string to be displayed. * x * The graphics X coordinate of the label's reference point. * y * The graphics Y coordinate of the label's reference point. * just * Pointer to a null-terminated character string identifying the * reference point for the text being drawn. The first character in * this string identifies the reference position in the "up" direction * and may be "M", "B", "C" or "T" (for bottom, baseline, centre or * top). The second character identifies the side-to-side reference * position and may be "L", "C" or "R" (for left, centre or right). The * string is case-insensitive, and only the first two characters are * significant. * upx * The x component of the up-vector for the text. Positive values * always refer to displacements from left to right on the screen, * even if the graphics x axis increases in the opposite sense. * upy * The y component of the up-vector for the text. Positive values * always refer to displacements from left to right on the screen, * even if the graphics y axis increases in the opposite sense. * xbn * An array in which is returned the x coordinates at the corners * of the bounding box. The order is: bottom left, top left, top * right, bottom right. * ybn * An array in which is returned the Y coordinates at the corners * of the bounding box (see xbn). * drop * Address of a float in which to return the distance between the * bottom of the bounding box and the baseline of normal text. May * be NULL. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - The "B" option for the justification in the "up" direction refers * to the base-line on which the text is written. Some characters * ("y", "p", "g", etc) descend below this line. In addition, if the * supplied text string includes any escape sequences which produce * sub-scripts, then these will also descend below the base-line. To * justify the bottom of the entire string (instead of just the * base-line), specify "M" instead of "B" in the justification string. * - See function astFindEscape for details of the supported escape * sequences. */ /* Local Variables: */ astDECLARE_GLOBALS char *a; char *lt; char cc; const char *lj; double ncol; double nfont; double nsize; double nstyle; double nwidth; float alpha_hi; float alpha_lo; float beta_lo; float beta_hi; float cy; float cx; float dy; float dx; float height; float hmx; float hmy; float ly; float lx; float rx; float rlen; float rise; float rxu; float ryu; float ry; float tdrop; float tybn[ 4 ]; float txbn[ 4 ]; float ulen; float uyu; float uxu; float uy; float ux; float width; float x0; float y0; int estype; int esval; int got_esc; int grfcap; int i; int nc; /* Check the global error status, and that we have something to plot, and the reference position is good, and that the up vector is not zero. */ if ( !astOK || !text || !text[ 0 ] || x == AST__BAD || y == AST__BAD || ( upx == 0.0 && upy == 0.0 ) ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Initialise variables to avoid compiler warnings. */ rx = 0.0f; ry = 0.0f; x0 = 0.0f; y0 = 0.0f; /* Get an up vector which refers to the graphics coordinates in their correct senses (the supplied values are reversed if the corresponding axis is reversed). */ ux = ( this->xrev ) ? -upx : upx; uy = ( this->yrev ) ? -upy : upy; /* Find a vector which points from left to right along the text baseline, taking account of any difference in the scales of the x and y axes (is possible). This also scales the up vector so that it has a length equal to the height of normal text, and scales the right vector to have the same length (on the screen) as the up vector. */ RightVector( this, &ux, &uy, &rx, &ry, method, class, status ); /* Create a unit right vector. */ rlen = sqrt( rx*rx + ry*ry ); rxu = rx/rlen; ryu = ry/rlen; /* Create a unit up vector. */ ulen = sqrt( ux*ux + uy*uy ); uxu = ux/ulen; uyu = uy/ulen; /* Some older GRF modules cannot plot strings with vertical justification of "M". Check the capabilities of the grf module, and, if necessary, modify the justification and the coords of the reference point to use "B" instead of "M". This call also returns us the coords at the left end of the baseline of normal text. */ lx = x; ly = y; lj = JustMB( this, esc, text, &lx, &ly, upx, upy, just, uxu, uyu, rxu, ryu, &x0, &y0, method, class, status ); /* Initialise the horizontal and verical limits of the total bounding box. */ alpha_lo = FLT_MAX; alpha_hi = -FLT_MAX; beta_lo = FLT_MAX; beta_hi = -FLT_MAX; /* Tell the grf module whether or not to interpret escape sequences,and also note if the grf module is capable of interpreting escape sequences. */ grfcap = GCap( this, GRF__ESC, esc, status ); /* Forget the horizontal position remembered by any "%h+" escape sequences from any previous string. */ this->hmarkx = FLT_MAX; this->hmarky = FLT_MAX; /* If escape sequences are being interpreted and the string contains some escape sequences, but the grf module cannot interpret escape sequences, split the supplied text up into sub-strings delimited by escape sequences and plot each sub-string individually, modifying the reference point and graphics attributes as indicated by the escape sequences. */ if( esc && HasEscapes( text, status ) && !grfcap ) { /* Take a copy of the supplied text so that we can temporarily terminate each sub-string by poking a null (0) character into it. */ lt = (char *) astStore( NULL, (void *) text, strlen( text ) + 1 ); /* Indicate that the current baseline is at its normal height. */ rise = 0.0; /* Get the graphical attribute values for normal text. */ GAttr( this, GRF__SIZE, AST__BAD, &nsize, GRF__TEXT, method, class, status ); GAttr( this, GRF__WIDTH, AST__BAD, &nwidth, GRF__TEXT, method, class, status ); GAttr( this, GRF__FONT, AST__BAD, &nfont, GRF__TEXT, method, class, status ); GAttr( this, GRF__STYLE, AST__BAD, &nstyle, GRF__TEXT, method, class, status ); GAttr( this, GRF__COLOUR, AST__BAD, &ncol, GRF__TEXT, method, class, status ); /* The "concatenation point" (cx,cy) is the point where the normal baseline crosses the left hand edge of the substring bounding box. Initialise this to the left edge of the first substring. */ cx = x0; cy = y0; /* Loop round the whole string, drawing each sub-string. */ a = lt; while( *a && astOK ) { /* Examine the start of the remaining string and note if it begins with an escape sequence. If so, the type and value of the escape sequnece is returned. In either case the number of characters to the next delimiter is returned. */ got_esc = astFindEscape( a, &estype, &esval, &nc ); /* If the string starts with an escaped percent sign, modify things so that we can draw the percent sign with the normal text drawing code below. */ if( got_esc && estype == GRF__ESPER ) { got_esc = 0; a++; nc = 1; } /* If the string starts with any other escape sequence, modify the graphics attributes and concatenation point as required by the escape sequence. */ if( got_esc ) { InterpEscape( this, estype, (double) esval, &cx, &cy, ux, uy, rx, ry, lj, &rise, nsize, nstyle, nwidth, ncol, nfont, method, class, status ); /* If the remaining string starts with normal text, draw it. */ } else { /* Temporarily terminate the sub-string which ends with the next escape sequence. */ cc = a[ nc ]; a[ nc ] = 0; /* We now have to decide on the reference point for this sub-string. If the justification is "BL" then the reference point is just the current concatenation point. */ if( lj[ 0 ] == 'B' && lj[ 1 ] == 'L' ) { lx = cx; ly = cy; /* Otherwise, the reference point is offset from the concatenation point. It would be simpler to draw all substrings with "BL" justification but this causes problems with some grf modules (such as GAIA) which zoom the display by modifying the position of text strings without also modifying the size of text strings. Using the correct reference point for all sub-strings minimises the drift which occurs when such a grf modules zooms the display. */ } else { /* Find the width and height of this substring, and the distance between the bottom of the bounding box and the baseline (the drop). We do this by calling this function recursively, using "BL" justification to avoid infinite recursion. */ /* Forget the horizontal position remembered by any "%h+" escape sequences from any previous string. Save and re-instate the position of the horizontal mark since the call to DrawText may change it. */ hmx = this->hmarkx; hmy = this->hmarky; DrawText( this, 0, esc, a, cx, cy, "BL", upx, upy, txbn, tybn, &tdrop, method, class, status ); this->hmarkx = hmx; this->hmarky = hmy; dx = txbn[ 0 ] - txbn[ 3 ]; dy = tybn[ 0 ] - tybn[ 3 ]; width = sqrt( dx*dx + dy*dy ); dx = txbn[ 0 ] - txbn[ 1 ]; dy = tybn[ 0 ] - tybn[ 1 ]; height = sqrt( dx*dx + dy*dy ); /* First move right from the concatenation point by a fraction of the width of the substring (0.5 for "C" and 1.0 for "R"). */ if( lj[ 1 ] == 'C' ) { width *= 0.5; } else if( lj[ 1 ] != 'R' ) { width = 0; } lx = cx + rxu*width; ly = cy + ryu*width; /* Now move vertically by an amount which produes the requested vertical justification. */ if( lj[ 0 ] == 'T' ) { height -= tdrop; lx += height*uxu; ly += height*uyu; } else if( lj[ 0 ] == 'C' ) { height = 0.5*height - tdrop; lx += height*uxu; ly += height*uyu; } else if( lj[ 0 ] == 'M' ) { lx -= tdrop*uxu; ly -= tdrop*uyu; } } /* Draw it, and then find its real bounding box (i.e. using the correct reference position found above). */ if( ink ) GText( this, a, lx, ly, lj, upx, upy, method, class, status ); GTxExt( this, a, lx, ly, lj, upx, upy, txbn, tybn, method, class, status ); /* Re-instate the orignal value of the terminator character.*/ a[ nc ] = cc; /* Move the concatenation point to the right (i.e. in the direction of the text baseline) by an amount equal to the width of the bounding box. Also update the total bounding box limits.*/ UpdateConcat( txbn, tybn, ux, uy, rx, ry, &cx, &cy, x0, y0, &alpha_lo, &alpha_hi, &beta_lo, &beta_hi, status ); } /* Move on to the next character. */ a += nc; } /* Free resources. */ lt = astFree( lt ); /* Reset all attributes to their normal values. */ GAttr( this, GRF__SIZE, nsize, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__WIDTH, nwidth, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__COLOUR, ncol, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__FONT, nfont, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__STYLE, nstyle, NULL, GRF__TEXT, method, class, status ); /* If any escape sequences can be interpreted by the grf module, just pass the text string on to the grf module. */ } else { if( ink ) GText( this, text, lx, ly, lj, upx, upy, method, class, status ); GTxExt( this, text, lx, ly, lj, upx, upy, txbn, tybn, method, class, status ); /* The corners in the bounding box returned by GTxExt are in no particular order. But this function is contracted to return them in a specified order. So we use UpdateConcat to find the verical and horizontal limits of the box in a form which can be used to produce the correct order. UpdateConcat will also update the concatenation point, but that is irrelevant in this context. */ UpdateConcat( txbn, tybn, ux, uy, rx, ry, &lx, &ly, x0, y0, &alpha_lo, &alpha_hi, &beta_lo, &beta_hi, status ); } /* Return the total bounding box,in the order bottom left, topleft, top right, bottom right. */ xbn[ 0 ] = x0 + alpha_lo*ux + beta_lo*rx; ybn[ 0 ] = y0 + alpha_lo*uy + beta_lo*ry; xbn[ 1 ] = x0 + alpha_hi*ux + beta_lo*rx; ybn[ 1 ] = y0 + alpha_hi*uy + beta_lo*ry; xbn[ 2 ] = x0 + alpha_hi*ux + beta_hi*rx; ybn[ 2 ] = y0 + alpha_hi*uy + beta_hi*ry; xbn[ 3 ] = x0 + alpha_lo*ux + beta_hi*rx; ybn[ 3 ] = y0 + alpha_lo*uy + beta_hi*ry; /* Return the drop. */ if( drop ) *drop = -alpha_lo*ulen; /* Free memory.*/ lj = astFree( (void *) lj ); /* If OK, update the box containing all drawn graphics primitives. */ if( ink && astOK && !Boxp_freeze ) { for( i = 0; i < 4; i++ ){ Boxp_lbnd[ 0 ] = astMIN( xbn[ i ], Boxp_lbnd[ 0 ] ); Boxp_ubnd[ 0 ] = astMAX( xbn[ i ], Boxp_ubnd[ 0 ] ); Boxp_lbnd[ 1 ] = astMIN( ybn[ i ], Boxp_lbnd[ 1 ] ); Boxp_ubnd[ 1 ] = astMAX( ybn[ i ], Boxp_ubnd[ 1 ] ); } } } static void DrawTicks( AstPlot *this, TickInfo **grid, int drawgrid, double *labelat, double *gap, const char *method, const char *class, int *status ){ /* * * Name: * DrawTicks * Purpose: * Draw tick marks for a 2-D annotated coordinate grid. * Type: * Private function. * Synopsis: * #include "plot.h" * void DrawTicks( AstPlot *this, TickInfo **grid, int drawgrid, * double *labelat, double *gap, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws major and minor tick marks. It uses a different * technique depending on whether the tick marks are to be put along the * edges of the plotting area, or along a curve through the middle of the * plotting area. The physical axis values at which to put tick marks * are supplied in parameter "grid". * * If the ticks are placed on the edges of the plotting area, The * EdgeCrossings function is used to find all points along the edge which * have a physical axis value correspoinding to a tick value (there can in * general be more than one point on an edge with a given physical axis * value). Ticks are put at all such crossings. * * If ticks are placed within the plotting area, then they are put * along a curve defined by the "other axis" values supplied in * parameter "labelat". * Parameters: * this * A pointer to the Plot. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick marks on the axis. See function GridLines. * drawgrid * If non-zero, then a grid of curves has been drawn to mark the * major axis values. * labelat * A pointer to a 2 element array in holding the constant axis * values at which tick marks are to be put. Element 0 should hold * the axis 1 value at which tick marks for axis 0 are placed. Element * 1 should hold the axis 0 value at which tick marks for axis * 1 are placed. If ticks are to be placed round the edges of the * plotting zone instead of within the plotting zone, then values of * AST__BAD should be supplied. * gap * Pointer to array of two values holding the gap between major * tick marks on the two axes. This will be the difference between, * or the ratio of, adjacent tick mark values, depending on the * setting of the LogTicks attribute. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This function assumes the current Frame of the Plot is 2 * dimensional, and it should not be called if this is not the case. */ /* Local Variables: */ AstFrame *frame; /* Pointer to current Frame in Plot */ AstMapping *mapping; /* Pointer to graphics->physical Mapping */ AstPointSet *pset1; /* Pointer to PointSet holding physical coords. */ AstPointSet *pset2; /* Pointer to PointSet holding graphics coords. */ AstPointSet *pset3; /* Pointer to PointSet holding clipped graphics coords. */ EdgeCrossingsStatics *ecstatics = NULL; /* For static data structure */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ double *ptr1[2]; /* Pointer to physical data */ double **ptr2; /* Pointer to graphics data */ double **ptr3; /* Pointer to clipped graphics data */ double *a; /* Pointer to next current axis value */ double *b; /* Pointer to next other axis value */ double *value; /* Current tick value */ double *x; /* Pointer to next X value */ double *xc; /* Pointer to next clipped X value */ double *y; /* Pointer to next Y value */ double *yc; /* Pointer to next clipped Y value */ double a0; /* Physical axis value at base of tick */ double axmax; /* Upper axis limit */ double axmin; /* Lower axis limit */ double delta1; /* Increment between minor ticks above major tick */ double delta2; /* Increment between minor ticks below major tick */ double diff; /* Difference between adjacent major ticks */ double dl2; /* Squared increment between points */ double dl2_limit; /* Minimum usable squared increment between points */ double dl; /* Increment between points */ double dx; /* X component of increment along tick mark */ double dy; /* Y component of increment along tick mark */ double ex; /* X component of increment between points */ double ey; /* Y component of increment between points */ double lblat2; /* Other axis value part way up each tick */ double lblat; /* Other axis value at base of each tick */ double mindim; /* Shortest dimension of plotting area */ double minval; /* Current axis value at next minor tick */ double mjsign; /* Sign of the major tick mark length */ double mjtklen; /* Length of major tick marks */ double mnsign; /* Sign of the minor tick mark length */ double mntklen; /* Length of minor tick marks */ double ux; /* X component of unit vector along tick mark */ double uy; /* Y component of unit vector along tick mark */ double val; /* Major axis value */ double x0; /* X at base of tick */ double x1; /* X at end of tick */ double x2; /* Clipped X at base of tick */ double y0; /* Y at base of tick */ double y1; /* Y at end of tick */ double y2; /* Clipped Y at base of tick */ int *majflag; /* Pointer to next major/minor flag */ int *majflags; /* Pointer to aray of major/minor flags */ int axis; /* Current axis index */ int ed; /* Doing a secondary edge? */ int edge; /* Index of edge being ticked */ int first; /* Is this the first tick to be drawn? */ int gelid; /* ID for next graphical element to be drawn */ int i; /* Minor tick mark index */ int logticks; /* Are major tick marks logarithmically spaced? */ int minhi; /* Highest minor tick mark index */ int minlo; /* Lowest minor tick mark index */ int nedge; /* No. of edges to be ticked for each axis */ int nel; /* Actual number of tick marks to draw */ int ntot; /* Maximum number of tick marks */ int tick; /* Tick index */ int lasttick; /* Index of last major tick mark */ /* Check the global status. */ if( !astOK ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ a = NULL; delta1 = 0.0; delta2 = 0.0; lblat2 = 0.0; uy = 0.0; logticks = 0; /* Get the minimum dimension of the plotting ares. */ mindim = astMIN( this->xhi - this->xlo, this->yhi - this->ylo ); /* Information about the drawn tick marks is saved in the Plot structure. Reset this information now so that we are ready to store information about the new ticks that will be drawn by this function invocation. */ SaveTick( this, -1, 0.0, 0.0, 0, status ); /* If ticks are to be put round the edges of the plotting area... */ /* ============================================================== */ if( labelat[ 0 ] == AST__BAD || labelat[ 1 ] == AST__BAD ){ /* Store the number of edges to be ticked for each axis. */ nedge = astGetTickAll( this )? 2 : 1; /* Do each required edge. */ for( ed = 0; ed < nedge; ed++ ){ /* Initialize the id value for graphical element being drawn. */ gelid = AST__TICKS1_ID; /* Do each axis. */ for( axis = 0; axis < 2; axis++ ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, gelid, 1, GRF__LINE, method, class ); /* Store the length in graphics coordinates of major tick marks for this axis. Use a default of zero if a grid has been drawn. */ if( astTestMajTickLen( this, axis ) || !drawgrid ){ mjtklen = astGetMajTickLen( this, axis )*mindim; } else { mjtklen = 0.0; } /* Store the length in graphics coordinates of minor tick marks. */ mntklen = astGetMinTickLen( this, axis )*mindim; /* Get the edge to be labelled with the axis values. Edge 0 is the left hand edge. Edge 1 is the top edge. Edge 2 is the right-hand edge. Edge 3 is the bottom edge. */ edge = ( astGetEdge( this, axis ) + ed*2 ) % 4; if( edge < 0 ) edge = -edge; /* Store a pointer to the structure containing information describing the positions of the major tick marks along this axis. */ info = grid[ axis ]; /* Store a pointer to the axis value at the first major tick mark. */ value = info->ticks; /* Minor tick marks are drawn on both sides of each major tick mark. They are identified by an index number relative to major tick mark at zero. Store the indices of the first and last minor tick marks. */ minlo = ( 1 - info->nminor )/2; minhi = info->nminor/2; /* If major ticks are linear, store the difference between minor tick marks. This value will be the same for all major ticks. */ logticks = astGetLogTicks( this, axis ); if( !logticks ) { delta1 = gap[ axis ]/(double)info->nminor; delta2 = delta1; } /* Loop round until all ticks have been done. */ for( tick = 0; tick < info->nmajor; tick++ ){ /* Draw tick marks at all occurrences of the current major tick value on the selected edge of the plotting area. */ Ticker( this, edge, axis, *value, gap, mjtklen, 1, ( ed == 0 ), &ecstatics, method, class, status ); /* If minor tick mark values were not supplied, calculate them as even intervals between the major tick values. */ if( !info->minticks ) { /* If major ticks are logarithmic, store the difference between minor tick marks. This value will be different for each major tick. Also, since the minor ticks are drawn on either side of the major tick, the minor tick spacing above the major tick will be different to that below the minor tick when using logarathmic ticks. "delta1" is the minor gap above the major value, and "delta2" is the minor gap below the major value. */ if( logticks ) { delta1 = (*value) * ( gap[ axis ] - 1.0 )/ (double)info->nminor; delta2 = delta1 / gap[ axis ]; } /* Extra minor tick marks are drawn below the first major tick mark and above the last major tick mark to fill in any gaps caused by axis limits being exceeded. */ if( tick == 0 ) { minlo = 1 - info->nminor; } if( tick == 1 ) { minlo = ( 1 - info->nminor )/2; } else if( tick == info->nmajor - 1 ) { minhi = info->nminor - 1; } /* Store the axis value at the first minor tick mark. */ minval = *value + minlo*delta2; /* Loop round all the minor tick marks, storing the physical coordinates defining the tick mark. */ for( i = minlo; i <= minhi; i++ ){ /* Draw tick marks at all occurrences of the current minor tick value on the selected edge of the plotting area. Do not do the minor tick mark with index zero, since this corresponds to the position of the major tick mark. */ if( i ) Ticker( this, edge, axis, minval, gap, mntklen, 0, ( ed == 0 ), &ecstatics, method, class, status ); /* Get the axis value at the next minor tick mark. */ minval += ( i < 0 ) ? delta2 : delta1; } } /* Point to the next major tick value. */ value++; } /* If minor tick mark values have been supplied, used them. */ if( info->minticks ) { value = info->minticks; for( tick = 0; tick < info->nminor; tick++, value++ ){ Ticker( this, edge, axis, *value, gap, mntklen, 0, ( ed == 0 ), &ecstatics, method, class, status ); } } /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gelid, 0, GRF__LINE, method, class ); /* Set up the id for the next graphical element to be drawn. */ gelid = AST__TICKS2_ID; } } /* Free the static resources allocated within EdgeCrossings (called by Ticker). */ (void) EdgeCrossings( NULL, 0, 0, 0.0, NULL, NULL, &ecstatics, method, class, status ); /* If ticks are to put within the interior of the plotting area... */ /* ============================================================== */ } else { /* Get the mapping from base Frame (graphics coords) to current Frame (physical coords). */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Get the current Frame from the Plot. */ frame = astGetFrame( this, AST__CURRENT ); /* Initialize the id value for graphical element being drawn. */ gelid = AST__TICKS1_ID; /* Do each axis. */ for( axis = 0; axis < 2; axis++ ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, gelid, 1, GRF__LINE, method, class ); /* Store the length in graphics coordinates of major tick marks for this axis. Use a default of zero if a grid has been drawn. */ if( astTestMajTickLen( this, axis ) || !drawgrid ){ mjtklen = astGetMajTickLen( this, axis )*mindim; } else { mjtklen = 0.0; } /* Store the length in graphics coordinates of minor tick marks. */ mntklen = astGetMinTickLen( this, axis )*mindim; /* Indicate that the tick mark lengths should not be negatated. */ mjsign = 1.0; mnsign = 1.0; /* Store the smallest squared distance in graphics coordinates which can reliably be used to determine the direction of a tick mark. */ dl2_limit = 0.0001*mindim; dl2_limit *= dl2_limit; /* Store a pointer to the structure containing information describing the positions of the major tick marks along this axis. */ info = grid[ axis ]; /* Store a pointer to the axis value at the first major tick mark. */ value = info->ticks; /* Get the maximum number of tick marks to be drawn on this axis. */ ntot = 0; ntot = info->nmajor; if( info->minticks ) { ntot += info->nmajor + info->nminor; } else { ntot += ( info->nmajor + 1 )*( info->nminor - 1 ); } /* Pass on to the next axis if no ticks are to be drawn. */ if( ntot ) { /* Allocate memory to hold the physical coordinates defining all the required tick marks. Each tick mark is defined by 2 points. */ ptr1[ 0 ] = (double *) astMalloc( sizeof(double)*(size_t)(2*ntot) ); ptr1[ 1 ] = (double *) astMalloc( sizeof(double)*(size_t)(2*ntot) ); /* Allocate memory to hold a set of flags indicating whether each tick mark is minor or major. */ majflags = (int *) astMalloc( sizeof(int)*(size_t)ntot ); /* Check the pointers can be used. */ if( astOK ){ /* If the tick values have been supplied using astSetTickValues, just copy them into the above arrays. */ if( info->minticks ) { a = ptr1[ axis ]; b = ptr1[ 1 - axis ]; majflag = majflags; for( tick = 0; tick <= info->nmajor; tick++ ){ val = info->ticks[ tick ]; if( logticks ) { diff = val * ( gap[ axis ] - 1.0 ); lblat2 = labelat[ axis ] + 0.2*diff; } else { lblat2 = labelat[ axis ] + 0.2*gap[ 1 - axis ]; } *(a++) = val; *(b++) = labelat[ axis ]; *(a++) = val; *(b++) = lblat2; *(majflag++) = 1; } for( tick = 0; tick <= info->nminor; tick++ ){ val = info->minticks[ tick ]; if( logticks ) { diff = val * ( gap[ axis ] - 1.0 ); lblat2 = labelat[ axis ] + 0.2*diff; } else { lblat2 = labelat[ axis ] + 0.2*gap[ 1 - axis ]; } *(a++) = val; *(b++) = labelat[ axis ]; *(a++) = val; *(b++) = lblat2; *(majflag++) = 0; } /* If the tick values were not supplied using astSetTickValues, then we need to calculate the minor tick positions explicitly. */ } else { /* Store pointers to the next point on each axis. "a" always refers to the current axis. Also store the value on the other axis at which the tick marks starts, and another value on the other axis which is used to defined the tick mark directions. */ a = ptr1[ axis ]; b = ptr1[ 1 - axis ]; majflag = majflags; lblat = labelat[ axis ]; /* Store another value on the other axis which is used to defined the tick mark directions, and the difference between minor tick marks. For linearly spaced tick marks these values will be the same for all major ticks. Minor ticks are always drawn above the correponding major value (i.e. minlo == 1 ) and so we do not need to set delta2. */ logticks = astGetLogTicks( this, axis ); if( !logticks ) { lblat2 = labelat[ axis ] + 0.2*gap[ 1 - axis ]; delta1 = gap[ axis ]/(double)info->nminor; } /* Store the indices of the first and last minor tick marks, relative to a major tick mark. */ minlo = 1; minhi = info->nminor - 1; /* Get the axis limits. */ axmin = astGetBottom( frame, axis ); axmax = astGetTop( frame, axis ); /* Loop round until all ticks have been done. We include a hypothetical tick at index -1 (i.e. one gap below the first listed tick value) in order to get minor tick marks below the first major tick. But the hypothetical major tick value is not included in the list of major tick values to draw. */ lasttick = info->nmajor - 1; for( tick = -1; tick <= lasttick; tick++ ){ /* Get the major tick value. */ if( tick == -1 ) { if( !logticks ) { val = (*value) - gap[ axis ]; }else { val = (*value)/gap[ axis ]; } } else { val = *(value++); } /* Now find the value on the other axis which is used to defined the tick mark directions, and the difference between minor tick marks, in the case of logarithmically spaced tick marks. These values will be different for every major tick. Minor ticks are always drawn above the correponding major value (i.e. minlo == 1 ) and so we do not need to set delta2. */ if( logticks ) { diff = val * ( gap[ axis ] - 1.0 ); lblat2 = labelat[ axis ] + 0.2*diff; delta1 = diff / (double)info->nminor; } /* If major tick marks are required, store the physical coordinates at the start of the major tick mark, and at a point a little way up the major tick mark. */ if( tick > -1 ){ *(a++) = val; *(b++) = lblat; *(a++) = val; *(b++) = lblat2; *(majflag++) = 1; } /* Store the points defining the minor tick marks on either side of this major tick mark. First store the axis value at the first minor tick mark. */ minval = val + minlo*delta1; /* Loop round all the minor tick marks, storing the physical coordinates defining the tick mark. */ for( i = minlo; i <= minhi; i++ ){ /* Do not do the minor tick mark with index zero, since this corresponds to the position of the major tick mark. Do not do any minor ticks that are outside the axis range. */ if( i && minval >= axmin && minval <= axmax ){ *(a++) = minval; *(b++) = lblat; *(a++) = minval; *(b++) = lblat2; *(majflag++) = 0; } /* Get the axis value at the next minor tick mark. */ minval += delta1; } } } } /* Adjust the size of the arrays to exclude any unused space. */ nel = a - ptr1[axis]; ptr1[axis] = (double *) astRealloc( (void *) ptr1[axis], sizeof(double)*nel ); ptr1[1-axis] = (double *) astRealloc( (void *) ptr1[1-axis], sizeof(double)*nel ); /* Create a pointset holding these coordinates. */ pset1 = astPointSet( nel, 2, "", status ); astSetPoints( pset1, ptr1 ); /* Transform these physical coordinates into graphics coordinates, without doing any clipping (this is so that tick marks are still drawn even if they extend into the area containing clipped physical coordinates). */ pset2 = astTransform( mapping, pset1, 0, NULL ); ptr2 = astGetPoints( pset2 ); /* Transform them again this time with clipping. */ pset3 = Trans( this, NULL, mapping, pset1, 0, NULL, 0, method, class, status ); ptr3 = astGetPoints( pset3 ); /* Check the pointers can be used.*/ if( astOK ){ /* Store pointers to the next point on each axis. */ a = ptr1[ axis ]; x = ptr2[ 0 ]; y = ptr2[ 1 ]; xc = ptr3[ 0 ]; yc = ptr3[ 1 ]; majflag = majflags; /* Loop round all ticks (major and minor). */ ux = AST__BAD; first = 1; for( tick = 0; tick < nel/2; tick++ ){ /* Store the physical axis value at the base of the tick mark (skip over the physical axis value at the point up the tick mark). */ a0 = *(a++); a++; /* Store the x and y coordinates at the base of the tick mark. */ x0 = *(x++); y0 = *(y++); /* Store the x and y coordinates at a point up the tick mark. */ x1 = *(x++); y1 = *(y++); /* Store the clipped x and y coordinates at the base of the tick mark. */ x2 = *(xc++); y2 = *(yc++); /* Skip over the clipped x and y coordinates at the point up the tick mark. */ xc++; yc++; /* Check they are all valid, and that the start of the tick mark is within the plotting area. */ if( x0 != AST__BAD && y0 != AST__BAD && x1 != AST__BAD && y1 != AST__BAD && x2 != AST__BAD && y2 != AST__BAD && x0 <= this->xhi && x0 >= this->xlo && y0 <= this->yhi && y0 >= this->ylo ){ /* Get the increments in X and Y beyween the two points, and the squared distance between the two points. */ dx = x1 - x0; dy = y1 - y0; dl2 = dx*dx + dy*dy; /* Check the two points are not co-incident. */ if( dl2 > dl2_limit ){ /* Store the distance between the two points. */ dl = sqrt( dl2 ); /* If this is the first tick to be drawn on this axis, decide which direction to draw the tick mark so that they will appear on the right hand side of the axis as seen by someone moving along the axis in the positive direction (the numerical labels are also drawn on the same side). */ if( first ){ first = 0; /* If the next tick mark is not defined, make an arbitrary decision by leaving the sign of the tick mark length unchanged. */ if( tick + 1 < nel/2 && *x != AST__BAD && *y != AST__BAD && a0 != AST__BAD && *a != AST__BAD ){ /* Form the vector joining this tick mark to the next. */ ex = *x - x0; ey = *y - y0; /* Ensure this vector is in the positive direction of the axis. */ if( *a < a0 ) { ex = -ex; ey = -ey; } /* If a positive tick mark length would put the marks on the wrong side, negate the tick mark length. */ if( ex*dy > ey*dx ){ mjsign = -1.0; mnsign = -1.0; } } } /* Store the unit vector in the direction of the tick mark. This is used as the default vector for the next tick mark if the direction of the next tick mark is indeterminate. */ ux = dx/dl; uy = dy/dl; } /* Only draw this tickmark if its direction is known. */ if( ux != AST__BAD ) { /* Get the position of the end of the tick mark. The length of the tick mark depends on whether it is a major or minor tick mark. */ if( *majflag ){ x1 = x0 + mjsign*mjtklen*ux; y1 = y0 + mjsign*mjtklen*uy; } else { x1 = x0 + mnsign*mntklen*ux; y1 = y0 + mnsign*mntklen*uy; } /* Save and draw the tick mark. */ SaveTick( this, axis, x0, y0, *majflag, status ); if( x0 != x1 || y0 != y1 ) { Bpoly( this, (float) x0, (float) y0, status ); Apoly( this, (float) x1, (float) y1, status ); Opoly( this, status ); } } } /* Point to the next major/minor flag. */ majflag++; } } /* Free the memory holding the physical coordinates. */ ptr1[ 0 ] = (double *) astFree( ( void *) ptr1[ 0 ] ); ptr1[ 1 ] = (double *) astFree( ( void *) ptr1[ 1 ] ); majflags = (int *) astFree( (void *) majflags ); /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); pset3 = astAnnul( pset3 ); } /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gelid, 0, GRF__LINE, method, class ); /* Set up the id for the next graphical element to be drawn. */ gelid = AST__TICKS2_ID; } /* Annul the pointers to the Mapping and Frame. */ mapping = astAnnul( mapping ); frame = astAnnul( frame ); } /* Return. */ return; } static void EBuf( AstPlot *this, int *status ) { /* *++ * Name: c astEBuf f AST_EBUF * Purpose: * End the current graphical buffering context. * Type: * Public function. * Synopsis: c #include "plot.h" c void astEBuf( AstPlot *this ) f CALL AST_EBUF( THIS STATUS ) * Class Membership: * Plot member function. * Description: c This function f This routine * ends the current graphics buffering context. It should match a * corresponding call to the c astBBuf function. f AST_EBUF routine. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The nature of the buffering is determined by the underlying * graphics system (as defined by the current grf module). Each call c to this function f to this routine * simply invokes the astGEBuf function in the grf module. *-- */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the active GRF EBuf function. */ GEBuf( this, "astEBuf", astGetClass( this ), status ); } static int EdgeLabels( AstPlot *this, int ink, TickInfo **grid, AstPlotCurveData **cdata, int force, const char *method, const char *class, int *status ){ /* * * Name: * EdgeLabels * Purpose: * Attempts to display labels for the major tick values around the edges * of the plotting area. * Type: * Private function. * Synopsis: * #include "plot.h" * int EdgeLabels( AstPlot *this, int ink, TickInfo **grid, * AstPlotCurveData **cdata, int force, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function determines how many major tick value labels could be * placed on the specified edges of the plotting area, and then if * requested, and if sufficient such labels are found (more than 3 on * each axis), they are drawn. To place a label on an edge, the curve * defining the major tick value must cross the edge at a reasonably * angle (at least 3 degrees). Labels are not drawn which would overlap * other, previously drawn, labels. A flag is returned indicating if * edge labels were (or could be) drawn. * Parameters: * this * A pointer to the Plot. * ink * If zero, then no labels are drawn, but the decision whether or * not to draw them is still made and indicated in the returned function * value. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick marks on the axis. See function GridLines. * cdata * A pointer to an array of two AstPlotCurveData pointers (one for each axis), * each pointing to an array of AstPlotCurveData structure (one for each * major tick value on the axis), holding information about breaks * in the curves drawn to mark the major tick values. See function * DrawGrid. * force * If non-zero, then an attempt is made to draw edge labels even if * it looks like insufficient edge labels can be produced. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * If edge labels were drawn, 1 is returned. Otherwise 0 is returned. * Notes: * - Zero is returned if an error has already occurred. */ /* Local Variables: */ AstFrame *frame; /* Pointer to current Frame */ AstPlotCurveData *cdt; /* Pointer to the AstPlotCurveData for the next tick */ LabelList *labellist; /* Pointer to a ingle list of labels to be plotted */ LabelList *ll; /* Pointer to next label to be plotted */ LabelList *llist[2]; /* Pointers to both lists of labels to be plotted */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ const char *just[ 2 ]; /* Justification string */ const char *text; /* Pointer to label text */ double edgeval; /* Axis value at the labelled edge */ double mindim; /* Minimum dimension of the plotting area */ double oppval; /* Axis value on the edge opposite to the labels */ double tol; /* Max. distance between a break and the edge */ double txtgap; /* Absolute gap between labels and edges */ float *box; /* Pointer to array of label bounding boxes */ float *vxbrk; /* X component of unit vector at current break */ float *vybrk; /* Y component of unit vector at current break */ float *xbrk; /* X coord. of current break */ float *ybrk; /* Y coord. of current break */ float xref; /* X coordinate at label's reference position */ float yref; /* Y coordinate at label's reference position */ int axis; /* Current axis index */ int brk; /* Current break index */ int edge; /* The edge to be labelled */ int edgeax; /* Index of axis parallel to the labelled edge */ int edgelabs; /* Can edge labels be produced? */ int esc; /* INterpret escape sequences? */ int gelid; /* ID for next graphical element to be drawn */ int ii; /* Index into existing labels */ int maxlab; /* Number of distinct edge labels */ int medge[2]; /* No. of distinct edge labels for each axis */ int naxlab; /* Number of edge labels */ int near; /* Draw a label on the near edge? */ int nedge[2]; /* No. of edge labels for each axis */ int ok; /* Can the current tick mark be labelled on the edge? */ int labfound; /* Label value has already been used? */ int tick; /* Tick index */ int upright; /* Draw all labels upright? */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ xref = 0.0; yref = 0.0; /* See if escape sequences in text strings are to be interpreted. */ esc = astGetEscape( this ); /* Initialise the returned flag to indicate that edge labels cannot be produced. */ edgelabs = 0; /* Get the minimum dimension of the plotting ares. */ mindim = astMIN( this->xhi - this->xlo, this->yhi - this->ylo ); /* Set up the tolerance for curve breaks occuring on an edge of the plotting zone. */ tol = 0.005*mindim; /* First, we get a list of all the labels which can be produced on each axis. The list includes the labels reference position in graphics coordinates, and the index of the major tick value which it represents. We do not yet know whether enough of the grid lines cross the required edge to make it feasable to use edge labelling, so we do not yet draw the labels. =====================================================================*/ /* Initialise pointers to arrays of structures holding information about the labels which can be draw round the edge for both axes. */ llist[ 0 ] = NULL; llist[ 1 ] = NULL; /* Indicate that no labels can yet be drawn on either axis. */ nedge[ 0 ] = 0; nedge[ 1 ] = 0; /* The "nedge" array counts the number of labels on each edge. But some of these labels may be for the same tick mark (if the tick mark curve has more than 1 intersection with the edge). The "medge" array counts the number of *distinct* tick mark labels (i.e. the number of tick mark values which have 1 or more interesections with the edge). */ medge[ 0 ] = 0; medge[ 1 ] = 0; /* For each axis, identify the the usable edge labels. */ for( axis = 0; axis < 2; axis++ ){ /* See if labels for this axis are to be drawn upright. */ if( astTestLabelUp( this, axis ) ) { upright = astGetLabelUp( this, axis ); } else { upright = 1; } /* Store the required gap between the label text and the axis. */ txtgap = astGetNumLabGap( this, axis )*mindim; /* Get the edge to be labelled with the axis values. Edge 0 is the left hand edge. Edge 1 is the top edge. Edge 2 is the right-hand edge. Edge 3 is the bottom edge. */ edge = astGetEdge( this, axis ) % 4; if( edge < 0 ) edge = -edge; /* If edge labels for the current axis are to go on the left hand edge of the plotting area... */ if( edge == 0 ){ /* Choose the justification based on the sign of the text gap. */ if( !upright ) { just[ axis ] = "BC"; } else if( txtgap > 0.0 ){ just[ axis ] = "CR"; } else if( txtgap < 0.0 ){ just[ axis ] = "CL"; } else { just[ axis ] = "CC"; } /* Store the constant X axis value at the edge being labelled. Also store the X value to use for the reference position for all labels. Take into account whether or not the X axis is displayed reversed (i.e. with high X values at the left hand side of the screen ). */ if( !this->xrev ){ edgeval = this->xlo; oppval = this->xhi; xref = (float)( edgeval - txtgap ); } else { edgeval = this->xhi; oppval = this->xlo; xref = (float)( edgeval + txtgap ); } /* Indicate that the "edgeval" value refers to axis 1 (the X axis). */ edgeax = 1; /* Do the same if the labels are to go on the top edge. */ } else if( edge == 1 ){ if( txtgap > 0.0 ){ just[ axis ] = "BC"; } else if( txtgap < 0.0 ){ just[ axis ] = "TC"; } else { just[ axis ] = "CC"; } if( !this->yrev ){ edgeval = this->yhi; oppval = this->ylo; yref = (float)( edgeval + txtgap ); } else { edgeval = this->ylo; oppval = this->yhi; yref = (float)( edgeval - txtgap ); } edgeax = 0; /* Do the same if the labels are to go on the right-hand edge. */ } else if( edge == 2 ){ if( !upright ) { just[ axis ] = "BC"; } else if( txtgap > 0.0 ){ just[ axis ] = "CL"; } else if( txtgap < 0.0 ){ just[ axis ] = "CR"; } else { just[ axis ] = "CC"; } if( !this->xrev ){ edgeval = this->xhi; oppval = this->xlo; xref = (float)( edgeval + txtgap ); } else { edgeval = this->xlo; oppval = this->xhi; xref = (float)( edgeval - txtgap ); } edgeax = 1; /* Do the same if the labels are to go on the bottom edge. */ } else { if( txtgap > 0.0 ){ just[ axis ] = "TC"; } else if( txtgap < 0.0 ){ just[ axis ] = "BC"; } else { just[ axis ] = "CC"; } if( !this->yrev ){ edgeval = this->ylo; oppval = this->yhi; yref = (float)( edgeval - txtgap ); } else { edgeval = this->yhi; oppval = this->ylo; yref = (float)( edgeval + txtgap ); } edgeax = 0; } /* Get a pointer to the structure containing information describing the positions of the major tick marks along this axis. */ info = grid[ axis ]; /* Get a pointer to the structure containing information describing the breaks in the curve which is parallel to the other axis and passes through the first major tick mark. */ cdt = cdata[ axis ]; /* Initialise the pointer to the list of text strings to be drawn. */ labellist = NULL; /* Initialise the number of labels which can be placed on the near edge of the plotting zone (some of which may be the same). */ naxlab = 0; /* Initialise the number of distinct labelled tick mark values. */ maxlab = 0; /* Loop round each of the major tick marks on the current axis. */ for( tick = 0; cdt && info && tick < info->nmajor; tick++ ){ /* Store pointers to the values giving the position and unit direction vector of the curve at the first break. */ xbrk = cdt->xbrk; ybrk = cdt->ybrk; vxbrk = cdt->vxbrk; vybrk = cdt->vybrk; /* Loop round each of the breaks in the curve which passes through the current major tick mark, and is parallel to the other axis. */ ok = 0; for( brk = 0; brk < cdt->nbrk; brk++ ){ /* A label can be produced on the near edge of the plotting zone if the current break occurs on, or close to, the edge, and the curve is not nearly parallel to the axis (limit is 5 degs). */ near = ( ( edgeax == 0 && fabs( (double) *ybrk - edgeval ) < tol && fabs( (double) *vybrk ) > 0.09 ) || ( edgeax == 1 && fabs( (double) *xbrk - edgeval ) < tol && fabs( (double) *vxbrk ) > 0.09 ) ); /* Get the label text. */ if( info->labels ) { text = (info->labels)[ tick ]; } else { text = NULL; } /* If a label can be produced, record the information needed to draw the label. */ if( near && text ){ labellist = (LabelList *) astGrow( (void *) labellist, naxlab + 1, sizeof(LabelList) ); if ( !astOK ) break; if( edgeax == 0 ){ (labellist + naxlab)->index = (double) *xbrk; (labellist + naxlab)->x = (double) *xbrk; (labellist + naxlab)->y = (double) yref; } else { (labellist + naxlab)->index = (double) *ybrk; (labellist + naxlab)->x = (double) xref; (labellist + naxlab)->y = (double) *ybrk; } (labellist + naxlab)->text = (char *) astStore( NULL, (void *) text, strlen(text) + 1 ); (labellist + naxlab)->just = (char *) astStore( NULL, (void *) just[ axis ], strlen(just[ axis ]) + 1 ); /* The up vector depends on which edge is being labelled and whether all labels are being drawn upright or not. */ if( edge == 1 || edge == 3 || upright ) { (labellist + naxlab)->upx = 0.0; (labellist + naxlab)->upy = 1.0; } else if( edge == 0 ) { (labellist + naxlab)->upx = -1.0; (labellist + naxlab)->upy = 0.0; } else { (labellist + naxlab)->upx = 1.0; (labellist + naxlab)->upy = 0.0; } (labellist + naxlab)->val = (info->ticks)[ tick ]; naxlab++; /* If this label has not already been included in the label list, indicate that we have found another usable label. */ labfound = 0; for( ii = 0; ii < naxlab-1; ii++ ) { if( fabs( (info->ticks)[ tick ] - (labellist + ii)->val ) < 0.2*info->gap ) { labfound = 1; break; } } if( !labfound ) ok = 1; } /* Increment the pointers to the values giving the position and unit direction vector of the next break. */ xbrk++; ybrk++; vxbrk++; vybrk++; } /* If an error has occurred, break out of the loop. */ if( !astOK ) break; /* If one or more labels could be produced for this tick mark value, increment the number of labeled tick marks found. */ if( ok ) maxlab++; /* Get a pointer to the curve through the next major tick mark. */ cdt++; } /* If an error has occurred, break out of the loop. */ if( !astOK ) break; /* Store the number of labels for this axis, and the pointer to the drawable labels. */ nedge[ axis ] = naxlab; medge[ axis ] = maxlab; llist[ axis ] = labellist; } /* We now know how many labels would be produced on each axis if edge labelling were to be used. We also know what those labelled values are, and where the labels would be drawn. We now take the decision as to whether there are enough of these labels to make edge labelling feasable. If so, we carry on and draw the labels. There need to be at least 3 labels on each axis for linear tick spacing and 2 for log tick spacing (or a non-zero value supplied for "force")... ================================================================= */ if( astOK && ( ( medge[ 0 ] > ( astGetLogTicks( this, 0 ) ? 1 : 2 ) && medge[ 1 ] > ( astGetLogTicks( this, 1 ) ? 1 : 2 ) ) || force ) ) { /* Set the returned flag to indicate that edge labelling is being used. */ edgelabs = 1; /* Initialise the pointer to the memory holding the bounding boxes for all labels (used by function Overlap). */ box = NULL; /* Get a pointer to the current Frame in the Plot. */ frame = astGetFrame( this, AST__CURRENT ); /* Initialize the id value for graphical element being drawn. */ gelid = AST__NUMLAB1_ID; /* If required, draw the labels for each axis in turn. */ for( axis = 0; axis < 2 && ink; axis++ ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, gelid, 1, GRF__TEXT, method, class ); /* Plot them. */ info = grid[ axis ]; PlotLabels( this, esc, frame, axis, llist[ axis ], info->fmt, nedge[ axis ], &box, method, class, status ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gelid, 0, GRF__TEXT, method, class ); /* Set up the id for the next graphical element to be drawn. */ gelid = AST__NUMLAB2_ID; } /* Free the memory used to hold the bounding boxes. */ box = (float *) astFree( (void *) box ); /* Annul the pointer to the Frame. */ frame = astAnnul( frame ); } /* Free the memory used to store the label information. */ for( axis = 0; axis < 2; axis++ ){ ll = llist[ axis ]; if( ll ) { for( tick = 0; tick < nedge[ axis ]; tick ++ ) { ll->text = (char *) astFree( (void *) ll->text ); ll->just = (char *) astFree( (void *) ll->just ); ll++; } llist[ axis ] = (LabelList *) astFree( (void *) llist[ axis ] ); } } /* Return the flag indicating if edge labels were produced. */ return edgelabs; } static int EdgeCrossings( AstPlot *this, int edge, int axis, double axval, double *gap, double **cross, EdgeCrossingsStatics **pstatics, const char *method, const char *class, int *status ){ /* * * Name: * EdgeCrossings * Purpose: * Find all occurrences of a given physical axis value on an edge of the * plotting area. * Type: * Private function. * Synopsis: * #include "plot.h" * int EdgeCrossings( AstPlot *this, int edge, int axis, double axval, * double *gap, double **cross, * EdgeCrossingsStatics **pstatics, * const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function finds all occurences of a given physical axis value * along a specified edge of the plotting area. Firstly, a set of evenly * spaced points ("edge samples") are placed along the edge and the * corresponding physical coordinates are found. These physical coordinates * are then offset slightly from their original positions in the direction * of the "other" axis (i.e. index [ 1 - axis ] ), and transformed back * into graphics coordinates. These coordinates give the tangent vector * at each of the edge samples. * * To find the crossings, the supplied axis value is compared with the axis * value at each sample in turn, starting from one end of the edge and * working through to the other end. When a crossing is found, linear * interpolation is used between the two adjacent edge samples to find a * more accurate estimate of the crossing. The vector at the crossing * is also estimated by linear interpolation between the vectors at the two * adjacent samples. * * This basic algorithm fails if there is a discontinuity in the axis * values along the edge. For instance, if the edge covers a range of * Right Ascension from 23h to 1h, there will be a discontinuity at 0h * at which the RA values suddenly jump from 2*PI to zero. This jump * encompasses all normalised RA values and so every axis value would be * given a crossing at this point. To avoid this, a bad sample is * interposed between the two samples on either side of the * discontinuity. This prevents any crossings from being placed at the * discontinuity. * * There is a second problem related to discontinuities. If the supplied * axis value is zero (using the above RA example again), then no * crossings will be found, not only because of the extra bad sample, * but also because the samples will not quite cover the range of axis * values covered by the discontinuity because of the discrete nature * of the samples). To get round this, the sections on either side * of the discontinity are extended by a single sample. These extra * samples are assumed to be conincident with the neighbouring sample, * except that the value for the searched axis is modified to be a * linear extension from the neighbouring samples. * Parameters: * this * A pointer to the Plot. Supply a NULL pointer to release resources. * edge * The edge of the plotting area to be used. Edge 0 is the left hand * edge. Edge 1 is the top edge. Edge 2 is the right-hand edge. Edge 3 * is the bottom edge. * axis * The index of the axis to which "axval" refers. * axval * The physical axis value to be searched for. * gap * Pointer to array of two values holding the gap between major * tick marks on the two axes. * cross * A pointer to the location at which to return a pointer to an * array of doubles holding the crossing information. Each crossing * is described by 4 doubles. The first pair are the graphiucs (x,y) * coordinates of the point on the edge at which the crossing occurs. * The second pair represents a unit vector in graphics coordinates * which is tangential to the curve of constant axis value at the * crossing. The memory allocated within this function to hold this * data should be freed using astFree when no longer needed. If no * crossings are found a NULL pointer is returned. * pstatics * Address of a pointer to a structure holding values for variables * which were statically defined within this function prior to the * thread-safe version of AST. If the pointer is supplied as NULL, * then a new structure is allocated and initialised. Any supplied * structure is freed if a NULL pointer is supplied for "this". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Return Value: * The number of crossings found. * Notes: * - This function allocates static resource on the first invocation * which should be freed when no more calls are to be made, by making a * final call with a NULL pointer supplied for "this". All other parameters * are then ignored. * - The static resources are re-initialised each time "edge" or * "axis" changes, and so the calling function should be structure in * order to minimise the number of times these parameter values change. * - If an error has already occurred, or if this function should * fail for any reason, zero is returned, and a NULL pointer is stored at * "cross". */ /* Local Variables: */ EdgeCrossingsStatics *statics; /* Structure holding static data */ AstMapping *mapping; /* Pointer to graphics->physical mapping */ AstPointSet *pset1a; /* Physical cooords at offset edge samples */ AstPointSet *pset2a; /* Physical cooords at offset edge samples */ AstPointSet *pset3; /* Physical cooords at offset edge samples */ AstPointSet *pset4a; /* Physical cooords at offset edge samples */ double **ptr1a; /* Pointer to physical coord. data */ double **ptr2a; /* Pointer to physical coord. data */ double **ptr3; /* Pointer to physical coord. data */ double **ptr4a; /* Pointer to physical coord. data */ double *data; /* Pointer to next item of crossing information */ double *p1; /* Pointer to graphics axis with constant value */ double *p1a; /* Pointer to graphics axis with constant value */ double *p2; /* Pointer to graphics axis with varying value */ double *p2a; /* Pointer to graphics axis with varying value */ double *q1; /* Pointer to physical axis being searched */ double *q1a; /* Pointer to physical axis being searched */ double *q2; /* Pointer to other physical axis */ double *q2a; /* Pointer to other physical axis */ double *v1; /* Pointer to vector component on axis 0 */ double *v2; /* Pointer to vector component on axis 1 */ double *v1a; /* Pointer to vector component on axis 0 */ double *v2a; /* Pointer to vector component on axis 1 */ double dd; /* The gap between edge samples */ double diff; /* Squared differences between adjacent edge samples */ double dl2; /* Squared vector length */ double dl; /* Vector length */ double dx; /* Vector X component */ double dy; /* Vector Y component */ double f; /* Weight for the current edge sample */ double offset; /* Physical offset */ double pp2; /* Varying graphics axis value at previous sample */ double pq1; /* Required physical axis value at previous sample */ double pv1; /* Previous vector component on axis 0 */ double pv2; /* Previous vector component on axis 1 */ double sum; /* Sum of squared differences between adjacent edge samples */ double value; /* The current graphics axis value */ double vx; /* Vector component on axis 0 at crossing */ double vy; /* Vector component on axis 1 at crossing */ double z; /* Varying graphics axis value at crossing */ int i; /* Edge sample index */ int iter; /* Iteration index */ int larger; /* Is current axis value larger than target? */ int logticks; /* Are major ticks logarithmically spaced? */ int ncross; /* No. of crossings */ int ndisc; /* No. of discontinuities along the edge */ int nsum; /* Number of values summed in "sum" */ int plarger; /* Was previous axis value larger than target? */ /* Get a pointer to the supplied statics object. */ statics = *pstatics; /* If a NULL Plot pointer has been supplied, release the static resources, and return. */ if( !this ){ if( statics ){ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); if( statics->pset4 ) statics->pset4 = astAnnul( statics->pset4 ); if( statics->frame ) statics->frame = astAnnul( statics->frame ); *pstatics = astFree( statics ); } return 0; } /* Initialise the number of crossings found, and the pointer to the place to store them. */ ncross = 0; *cross = NULL; /* Check the global status. */ if( !astOK ) return 0; /* If no statics structure was supplied, create one now and initialise it. */ if( !statics ) { statics = astMalloc( sizeof( EdgeCrossingsStatics ) ); if( statics ) { statics->frame = NULL; statics->pset1 = NULL; statics->pset2 = NULL; statics->pset4 = NULL; statics->ptr1 = NULL; statics->ptr2 = NULL; statics->ptr4 = NULL; statics->paxis = -1; statics->pedge = -1; *pstatics = statics; } } /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ pp2 = 0.0; pv1 = 0.0; pv2 = 0.0; plarger = 0; /* See if the major ticks on the other axis are logarithmically or linearly spaced. */ logticks = astGetLogTicks( this, 1 - axis ); /* Ensure that "edge" is in the range 0 - 3. */ edge = edge % 4; if( edge < 0 ) edge = -edge; /* If the edge or axis has changed since the last invocation, or if this is the first invocation, initialise some static data. */ /* ======================================================================*/ if( statics->pedge == -1 || statics->pedge != edge || statics->paxis != axis ){ /* Save the edge and axis. */ statics->pedge = edge; statics->paxis = axis; /* Annull any previous static data objects */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); if( statics->pset4 ) statics->pset4 = astAnnul( statics->pset4 ); if( statics->frame ) statics->frame = astAnnul( statics->frame ); /* Store some values so that the code does not need to consider each edge separately. First deal with the left hand edge. */ if( edge == 0 ){ statics->edgeax = 0; if( this->xrev ){ statics->edgeval = this->xhi; } else { statics->edgeval = this->xlo; } statics->edgehi = this->yhi; statics->edgelo = this->ylo; /* Now deal with the right hand edge. */ } else if( edge == 2 ){ statics->edgeax = 0; if( this->xrev ){ statics->edgeval = this->xlo; } else { statics->edgeval = this->xhi; } statics->edgehi = this->yhi; statics->edgelo = this->ylo; /* Now deal with the bottom edge. */ } else if( edge == 3 ){ statics->edgeax = 1; if( this->yrev ){ statics->edgeval = this->yhi; } else { statics->edgeval = this->ylo; } statics->edgehi = this->xhi; statics->edgelo = this->xlo; /* Finally deal with the top edge. */ } else { statics->edgeax = 1; if( this->yrev ){ statics->edgeval = this->ylo; } else { statics->edgeval = this->yhi; } statics->edgehi = this->xhi; statics->edgelo = this->xlo; } /* Get a pointer to the current Frame in the supplied Plot. */ statics->frame = astGetFrame( this, AST__CURRENT ); /* Get a pointer to the mapping from base to current Frame in the supplied Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Create a PointSet to hold the graphics coordinates at a set of regularly spaced points along the specified edge of the plotting area. */ pset1a = astPointSet( EDGETICKS_DIM, 2, "", status ); ptr1a = astGetPoints( pset1a ); /* Create a PointSet to hold the corresponding physical coordinates. */ pset2a = astPointSet( EDGETICKS_DIM, 2, "", status ); ptr2a = astGetPoints( pset2a ); /* Check they can be used. */ if( astOK ){ /* Set up the graphics coordinates. */ dd = ( statics->edgehi - statics->edgelo )/(double)( EDGETICKS_DIM - 1 ); value = statics->edgelo; p1 = ptr1a[ statics->edgeax ]; p2 = ptr1a[ 1 - statics->edgeax ]; for( i = 0; i < EDGETICKS_DIM; i++ ){ *(p1++) = statics->edgeval; *(p2++) = value; value += dd; } } /* Transform the graphics coordinates to physical coordinates, *without* normalising them into their normal ranges. */ (void) Trans( this, statics->frame, mapping, pset1a, 1, pset2a, 0, method, class, status ); /* Find the RMS step size along the axis. This is used to locate discontinuities along the edge. Do three rejection iterations. */ statics->limit = DBL_MAX; for( iter = 0; iter < 3; iter ++ ){ q1 = ptr2a[ axis ]; pq1 = AST__BAD; sum = 0.0; nsum = 0; for( i = 0; i < EDGETICKS_DIM; i++ ){ if( *q1 != AST__BAD && pq1 != AST__BAD ){ diff = *q1 - pq1; if( fabs( diff ) < statics->limit ){ sum += diff*diff; nsum++; } } pq1 = *(q1++); } if( nsum == 0 ) break; statics->limit = 3.0*sqrt( sum/(double)nsum ); } /* Now create another PointSet holding positions slightly offset from the physical coordinates at the edge samples. The offset is in the direction of the other physical axis. These positions are used to determine the vector at the crossings. */ if( nsum > 0 ){ pset3 = astPointSet( EDGETICKS_DIM, 2, "", status ); ptr3 = astGetPoints( pset3 ); /* Create a PointSet to hold the corresponding graphics coordinates. */ pset4a = astPointSet( EDGETICKS_DIM, 2, "", status ); ptr4a = astGetPoints( pset4a ); /* Check they can be used. */ if( astOK ){ /* Copy the physical coordinates from PointSet 2 to PointSet 3, offseting them slightly along the other axis. */ p1 = ptr2a[ axis ]; p2 = ptr2a[ 1 - axis ]; q1 = ptr3[ axis ]; q2 = ptr3[ 1 - axis ]; offset = 0.2*gap[ 1 - axis ]; pq1 = AST__BAD; for( i = 0; i < EDGETICKS_DIM; i++ ){ if( *p1 != AST__BAD && *p2 != AST__BAD ){ if( logticks ) offset = 0.2*(*p2)*( gap[ 1 -axis ] - 1.0 ); *(q2++) = *p2 + offset; } else { *(q2++) = AST__BAD; } pq1 = *(p1++); *(q1++) = pq1; p2++; } } /* Transform the physical coordinates to graphics coordinates. */ (void) Trans( this, NULL, mapping, pset3, 0, pset4a, 0, method, class, status ); /* Check they can be used. */ if( astOK ){ /* Modify the contents of PointSet 4 to represent the unit vector in graphics coordinates at each edge sample. */ p1 = ptr1a[ 0 ]; p2 = ptr1a[ 1 ]; q1 = ptr4a[ 0 ]; q2 = ptr4a[ 1 ]; for( i = 0; i < EDGETICKS_DIM; i++ ){ if( *p1 != AST__BAD && *p2 != AST__BAD && *q1 != AST__BAD && *q2 != AST__BAD ){ dx = *q1 - *p1; dy = *q2 - *p2; dl2 = dx*dx + dy*dy; if( dl2 > 0.0 ){ dl = sqrt( dl2 ); *q1 = dx/dl; *q2 = dy/dl; } else { *q1 = AST__BAD; *q2 = AST__BAD; } } else { *q1 = AST__BAD; *q2 = AST__BAD; } p1++; p2++; q1++; q2++; } } /* Annul the PointSet holding offset physical cooridnates. */ pset3 = astAnnul( pset3 ); /* Discontinuities in the axis values can cause problems. For instance, using the above PointSets, no tick mark could be put at 0 hours RA because of the discontinuity there. To get round this, 3 extra samples are added at each discontinuity, the first extends the continuous section which ends at the discontinuity, and the third extends the secion which starts at the discontinuity. This results in the two sections overlapping by one sample. The second is placed between these two and has a bad axis value. It prevents crossings from being found in between the values at the ends of the two sections. First count the number of discontinuities in the axis values. Discontinuites are defined as steps of more than 9 times the RMS step size. */ q1 = ptr2a[ axis ]; pq1 = AST__BAD; statics->limit *= 3.0; ndisc = 0; for( i = 0; i < EDGETICKS_DIM; i++ ){ if( *q1 != AST__BAD && pq1 != AST__BAD ){ if( fabs( *q1 - pq1 ) > statics->limit ) ndisc++; } pq1 = *(q1++); } /* Store the size of the new PointSets holding the extra samples. */ statics->dim = EDGETICKS_DIM + 3*ndisc; /* If there are no discontinuities, just clone the existing PointSets. */ if( !ndisc ){ statics->pset1 = astClone( pset1a ); statics->pset2 = astClone( pset2a ); statics->pset4 = astClone( pset4a ); statics->ptr1 = astGetPoints( statics->pset1 ); statics->ptr2 = astGetPoints( statics->pset2 ); statics->ptr4 = astGetPoints( statics->pset4 ); /* Otherwise, create new PointSets. */ } else { statics->pset1 = astPointSet( statics->dim, 2, "", status ); statics->ptr1 = astGetPoints( statics->pset1 ); statics->pset2 = astPointSet( statics->dim, 2, "", status ); statics->ptr2 = astGetPoints( statics->pset2 ); statics->pset4 = astPointSet( statics->dim, 2, "", status ); statics->ptr4 = astGetPoints( statics->pset4 ); /* Set up pointers used to walk through the arrays in the original PointSets and the new PointSets. */ p1 = statics->ptr1[ 0 ]; p2 = statics->ptr1[ 1 ]; q1 = statics->ptr2[ axis ]; q2 = statics->ptr2[ 1 - axis ]; v1 = statics->ptr4[ 0 ]; v2 = statics->ptr4[ 1 ]; p1a = ptr1a[ 0 ]; p2a = ptr1a[ 1 ]; q1a = ptr2a[ axis ]; q2a = ptr2a[ 1 - axis ]; v1a = ptr4a[ 0 ]; v2a = ptr4a[ 1 ]; /* Initialise the axis value at the previous sample. */ pq1 = AST__BAD; /* Check all samples in the original PointSets. */ for( i = 0; i < EDGETICKS_DIM; i++ ){ /* If this is the first point after a discontinuity... */ if( *q1a != AST__BAD && pq1 != AST__BAD ){ if( fabs( *q1a - pq1 ) > statics->limit ) { /* Insert an extra sample with the coordinates of the previous sample, but with an axis value which is linearly extrapolated from the previous samples. */ *(p1++) = p1a[ 0 ]; *(p2++) = p2a[ 0 ]; *(v1++) = v1a[ -1 ]; *(v2++) = v2a[ -1 ]; *(q2++) = q2a[ -1 ]; if( i > 1 && q1a[ -2 ] != AST__BAD ){ *(q1++) = 2.0*pq1 - q1a[ -2 ]; } else { *(q1++) = pq1; } /* Insert an extra sample with bad coordinates. */ *(p1++) = AST__BAD; *(p2++) = AST__BAD; *(v1++) = AST__BAD; *(v2++) = AST__BAD; *(q2++) = AST__BAD; *(q1++) = AST__BAD; /* Insert an extra sample with the cooridnates of the current sample, but with an axis value which is linearly extrapolated from the subsequent samples. */ *(p1++) = p1a[ -1 ]; *(p2++) = p2a[ -1 ]; *(v1++) = *v1a; *(v2++) = *v2a; *(q2++) = *q2a; if( i < EDGETICKS_DIM - 1 && q1a[ 1 ] != AST__BAD ){ *(q1++) = 2.0*(*q1a) - q1a[ 1 ]; } else { *(q1++) = pq1; } } } /* Save the current axis value. */ pq1 = *q1a; /* Copy the current input values to the new PointSets, and move on the next point in the original PointSets. */ *(p1++) = *(p1a++); *(p2++) = *(p2a++); *(q1++) = *(q1a++); *(q2++) = *(q2a++); *(v1++) = *(v1a++); *(v2++) = *(v2a++); } } /* Anull the original PointSets. */ pset4a = astAnnul( pset4a ); /* If all the physical coordinates are bad, indicate this by setting the limiting step size bad. */ } else { statics->limit = AST__BAD; } /* Anull the original PointSets. */ pset1a = astAnnul( pset1a ); pset2a = astAnnul( pset2a ); /* Annul the pointer to the mapping from base to current Frame. */ mapping = astAnnul( mapping ); } /* ======================================================================*/ /* The initialisation has now been done. Check the physical coordinate data can be used. */ if( astOK && statics->limit != AST__BAD ){ /* Store pointers to the graphics and physical coordinates at the first edge sample. */ p1 = statics->ptr1[ statics->edgeax ]; /* Graphics axis with constant value */ p2 = statics->ptr1[ 1 - statics->edgeax ]; /* Graphics axis with varying value */ q1 = statics->ptr2[ axis ]; /* Physical axis values to be searched */ q2 = statics->ptr2[ 1 - axis ]; /* The other physical axis */ /* Store pointers to the components of the unit vector at the first edge sample. */ v1 = statics->ptr4[ 0 ]; v2 = statics->ptr4[ 1 ]; /* Inidicate that there is currently no "previous sample". */ pq1 = AST__BAD; /* Check each point in turn... */ for( i = 0; i < statics->dim; i++ ){ /* Skip this point if the physical coordinates are undefined. */ if( *q1 != AST__BAD && *q2 != AST__BAD ){ /* Get a flag indicating if the required axis value has been exceeded at the current edge sample. */ larger = ( *q1 > axval ); /* If the state of this flag has changed since the previous edge sample, and if we know where the previous sample was, we have found a crossing. */ if( pq1 != AST__BAD && larger != plarger ){ /* Find the distance from the previous physical axis value to the required axis value, as a fraction of the distance from the previous axis value to the current axis value. Since the flag has changed, we know that the q1 value at this edge sample and the previous one must be different, so we know that the denominator is not zero. */ f = ( axval - pq1 )/( *q1 - pq1 ); /* Use linear interpolation to estimate the graphics axis value at the crossing. */ if( f != -1.0 ){ z = pp2 + f*( *p2 - pp2 ); /* Use linear interpolation to estimate the two components of the unit vector at the crossing. */ if( *v1 != AST__BAD && pv1 != AST__BAD && *v2 != AST__BAD && pv2 != AST__BAD ){ vx = pv1 + f*( *v1 - pv1 ); vy = pv2 + f*( *v2 - pv2 ); /* Normalise the vector. */ dl2 = vx*vx + vy*vy; if( dl2 > 0.0 ){ dl = sqrt( dl2 ); vx /= dl; vy /= dl; } else { vx = AST__BAD; vy = AST__BAD; } } else { vx = AST__BAD; vy = AST__BAD; } /* Grow the returned array to hold another crossing. */ ncross++; *cross = (double *) astGrow( (void *) *cross, ncross, 4*sizeof( double ) ); /* If succesful, store the crossing. */ if( astOK ) { data = *cross + 4*( ncross - 1 ); if( statics->edgeax ){ *(data++) = z; *(data++) = statics->edgeval; } else { *(data++) = statics->edgeval; *(data++) = z; } *(data++) = vx; *(data++) = vy; } } } /* Save the flag for use on the next pass through this loop. */ plarger = larger; } /* Save the varying graphics axis value and the required physical axis value at the current edge sample (also save the vector). */ pp2 = *p2; pq1 = *q1; pv1 = *v1; pv2 = *v2; /* Point to the next edge sample. */ p1++; p2++; q1++; q2++; v1++; v2++; } } /* If an error has occurred, free the array holding the crossings, and indicate that there are zero corssing. */ if( !astOK ) { *cross = (double *) astFree( (void *) *cross ); ncross = 0; } /* Return the answer. */ return ncross; } int astFindEscape_( const char *text, int *type, int *value, int *nc, int *status ){ /* *+ * Name: * astFindEscape * Purpose: * Check if a string starts with a graphics escape sequence. * Type: * Protected function. * Synopsis: * #include "plot.h" * int astFindEscape( const char *text, int *type, int *value, int *nc ) * Description: * This function returns a flag indiciating if the first character in * the supplied string is the start of a graphics escape sequence. If * so, the type and associated value (if any) of the escape sequence * are returned in "type" and "value", and the number of characters * occupied by the escape sequence is returned in "nc". If the * supplied text string does not begin with an escape sequence, the * number of characters before the first escape sequence is returned in * "nc" (the length of the string is returned in "nc" if the string * contains no escape sequences). * * This function can be used by grf modules which wish to implement * interpretation of escape sequences internally, rather than allowing the * Plot class to do the interpretation. * Parameters: * text * Pointer to the string to be checked. * type * Pointer to a location at which to return the type of escape * sequence. Each type is identified by a symbolic constant defined * in grf.h. The returned value is undefined if the supplied text * does not begin with an escape sequence. * value * Pointer to a lcation at which to return the integer value * associated with the escape sequence. All usable values will be * positive. Zero is returned if the escape sequence has no associated * integer. A value of -1 indicates that the attribute identified by * "type" should be reset to its "normal" value (as established using * the astGAttr function, etc). The returned value is undefined if the * supplied text does not begin with an escape sequence. * nc * Pointer to a location at which to return the number of * characters read by this call. If the text starts with an escape * sequence, the returned value will be the number of characters in * the escape sequence. Otherwise, the returned value will be the * number of characters prior to the first escape sequence, or the * length of the supplied text if no escape sequence is found. * Returned Value: * A non-zero value is returned if the supplied text starts with a * graphics escape sequence, and zero is returned otherwise. * Escape Sequences: * Escape sequences are introduced into the text string by a percent * "%" character. The following escape sequences are currently recognised * ("..." represents a string of one or more decimal digits): * * %% - Print a literal "%" character. * * %^...+ - Draw subsequent characters as super-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the super-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text. * %^+ - Draw subsequent characters with the normal base-line. * * %v...+ - Draw subsequent characters as sub-scripts. The digits * "..." give the distance from the base-line of "normal" * text to the base-line of the sub-script text, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %v+ - Draw subsequent characters with the normal base-line * (equivalent to %^+). * * %>...+ - Leave a gap before drawing subsequent characters. * The digits "..." give the size of the gap, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %<...+ - Move backwards before drawing subsequent characters. * The digits "..." give the size of the movement, scaled * so that a value of "100" corresponds to the height of * "normal" text. * * %s...+ - Change the Size attribute for subsequent characters. The * digits "..." give the new Size as a fraction of the * "normal" Size, scaled so that a value of "100" corresponds * to 1.0; * * %s+ - Reset the Size attribute to its "normal" value. * * %w...+ - Change the Width attribute for subsequent characters. The * digits "..." give the new width as a fraction of the * "normal" Width, scaled so that a value of "100" corresponds * to 1.0; * * %w+ - Reset the Size attribute to its "normal" value. * * %f...+ - Change the Font attribute for subsequent characters. The * digits "..." give the new Font value. * * %f+ - Reset the Font attribute to its "normal" value. * * %c...+ - Change the Colour attribute for subsequent characters. The * digits "..." give the new Colour value. * * %c+ - Reset the Colour attribute to its "normal" value. * * %t...+ - Change the Style attribute for subsequent characters. The * digits "..." give the new Style value. * * %t+ - Reset the Style attribute to its "normal" value. * * %h+ - Remember the current horizontal position (see "%g+") * * %g+ - Go to the horizontal position of the previous "%h+" (if any). * * %- - Push the current graphics attribute values onto the top of * the stack (see "%+"). * * %+ - Pop attributes values of the top the stack (see "%-"). If * the stack is empty, "normal" attribute values are restored. * Notes: * - Zero is returned if an error has already occurred. *- */ /* Local Variables: */ int result; const char *a; const char *b; int nd; const char *perc; /* Initialise */ result = 0; *type = GRF__ESPER; *value = 0; *nc = 0; perc = NULL; /* Check inherited status and supplied pointer. */ if( !astOK || !text ) return result; /* Loop round, looking for percent signs. Break out of the loop when a complete escape sequence has been found and read, leaving the "b" pointer pointing to the first character following the escape sequence. */ b = NULL; a = text; while( ( a = strchr( a, '%' ) ) ) { perc = a; /* Compare the following character to each known escape sequence type. */ a++; if( *a == '%') { *type = GRF__ESPER; b = a + 1; break; } else if( *a == '^') { *type = GRF__ESSUP; } else if( *a == 'v') { *type = GRF__ESSUB; } else if( *a == '>') { *type = GRF__ESGAP; } else if( *a == '<') { *type = GRF__ESBAC; } else if( *a == 's') { *type = GRF__ESSIZ; } else if( *a == 'w') { *type = GRF__ESWID; } else if( *a == 'f') { *type = GRF__ESFON; } else if( *a == 'c') { *type = GRF__ESCOL; } else if( *a == 'g') { *type = GRF__ESG; } else if( *a == 'h') { *type = GRF__ESH; } else if( *a == 't') { *type = GRF__ESSTY; } else if( *a == '-') { *type = GRF__ESPSH; b = a + 1; break; } else if( *a == '+') { *type = GRF__ESPOP; b = a + 1; break; /* If the next character is illegal, skip to the next percent sign. */ } else { continue; } /* The escape sequence looks legal so far, so move on to the next character (if any). */ if( *(++a) ){ /* If the next character is a "+" sign, the attribute needs to be reset to its "normal" value. Indicate this by returning a value of "-1" (all usable values will be positive). */ if( *a == '+' ) { *value = -1; b = a + 1; break; /* Otherwise, to be a legal escape sequence, this character must be the first in a sequence of digits, terminated by a "+" sign.*/ } else if( (nd = 0, astSscanf( a, "%d%n+", value, &nd ))) { b = a + nd + 1; break; } } } /* Was a usable escape sequence found at the start of the supplied text? If so, return a function value of 1 and store the number of characters in the escape sequence. */ if( b && perc == text ) { result = 1; *nc = b - perc; /* Otherwise, return the preset function value of zero. If an escape sequence was found later in the text, return the number of characters prior to the escape sequence. */ } else if( b ) { *nc = perc - text; /* Otherwise, if no escape sequence was found, return the length of the supplied text. */ } else { *nc = strlen( text ); } /* Return the result. */ return result; } static int FindMajTicks( AstMapping *map, AstFrame *frame, int axis, double refval, double width, double gap, double *cen, int ngood, double *data, double **tick_data, int *status ){ /* * Name: * FindMajTicks * Purpose: * Place the major tick marks for a physical coordinate axis. * Type: * Private function. * Synopsis: * #include "plot.h" * int FindMajTicks( AstMapping *map, AstFrame *frame, int axis, * double refval, double width, double gap, double *cen, int ngood, * double *data, double **tick_data ) * Class Membership: * Plot member function. * Description: * The caller supplies an array of axis values (non-normalized), sorted * into ascending order (with any bad values at the end), together with * the gap size for the axis. The array of axis values is assumed to cover * the entire range which the axis can take within the plotting zone. The * first tick mark is placed just below the smallest axis value, at a * position which is an integral number of gaps away from the value * supplied in "cen" (if a value of AST__BAD is supplied for "cen" then * "cen = 0.0" is assumed). Notionally, tick marks are then placed at * intervals given by "gap" all the way upto, and just beyond, the * largest axis value. However, it could be that large sections of the * axis are not actually present within the plotting zone. For instance, * an RA axis covering the two hour range from 23h to 1h (centred on * 0h), will have some values at zero and some at 23.999.., but there * will be a large range inbetween these limits which is not represented * in the plotting area (i.e. the 22h range from 1h to 23h centred on * 12h). For this reason, tick marks are removed if there are no axis * values inbetween the tick mark and either of its neighbours. However, * small "holes" in the axis coverage are allowed, and ticks marks are * returned covering such small holes. Extra tick marks are also placed * at each end of the range to guard against the supplied array of axis * values not entirely covering the range of axis values in the plotting * area. * * For SkyFrames, positions which have latitude values outside the * normal ranges are ignored. Longitude ranges are not checked to * avoid problems with CAR projections. * * The returned tick mark values are placed into their primary domain * using the Norm1 method, but are NOT normalised using the astNorm * method for the supplied Frame. Duplicate tick marks values are * removed from the returned list. * Parameters: * map * Mapping from the Plot Base Frame to Plot Current Frame. * frame * Pointer to the Frame. * axis * Zero-based index of the axis being used. * refval * Value to use for the other axis (index [1-axis]) when placing * the tick mark values into their primary domain. * width * Range of used values on the other axis (index [1-axis]). * gap * The supplied value for the gaps between ticks on the axis. * cen * Pointer to the supplied axis value at which to put a central tick. * Other ticks will be placed evenly on either side of this tick. If * AST__BAD is provided, a value will be used which would put a tick * at an axis value of zero. The used value is returned. * ngood * The number of good values in the array pointer to by "data" (i.e. * values not equal to AST__BAD). * data * A pointer to an array holding sorted axis values (non-normalized) * covering the entire plotting area. * tick_data * A pointer to a place at which to store a pointer to an array * holding the returned tick mark values for the axis. * Returned Value: * The number of major tick mark values stored in the array pointer to * by "*tick_data". * Notes: * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned in "tick_data", and zero * is returned for the function value. */ /* Local Variables: */ double *r; /* Pointer to next tick value to be read */ double *ticks; /* Pointer to the axis values at the major tick marks */ double *w; /* Pointer to last tick value to be written */ double bot; /* Lowest axis value to be displayed */ double centre; /* The axis value at the first tick mark */ double delta; /* A safe distance from an axis limit */ double f; /* The nearest acceptable tick mark index */ double tmp; /* Temporary storage */ double top; /* Highest axis value to be displayed */ int inc; /* This times increase in nticks */ int k; /* Tick mark index */ int linc; /* Last times increase in nticks */ int lnfill; /* Last used value for nfill */ int nfill; /* No of tick marks to extend by at edges of coverage */ int nsame; /* Number of equal inc values there have been */ int nticks; /* Number of major tick marks used */ int ntnew; /* This times new value of nticks */ int use_nfill; /* nfill value which started this run of equal inc values */ /* Initialise the returned pointer. */ *tick_data = NULL; /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ nsame = 0; use_nfill = 0; /* Decide where to put the first major tick. Use any value supplied by the caller. Otherwise put it an integral number of gaps away from the origin. This would result in the origin being at a major tick mark. */ if( cen && *cen != AST__BAD ) { centre = *cen; } else { centre = astCentre( frame, axis, data[ 0 ], gap ); if( cen ) *cen = centre; } /* Find the number of candidate tick marks assuming an nfill value of 0. */ nfill = 0; nticks = FindMajTicks2( nfill, gap, centre, ngood, data, &ticks, status ); /* Loop round increasing the nfill value until an unreasonably large value of nfill is reached. The loop will exit early via a break statement when all small holes in the axis coverage are filled in. */ lnfill = nfill; linc = -100000; while( nfill < 100 && astOK ){ /* Increment the number of ticks added as "padding" at the edges of any gaps in the coverage of axis values. */ nfill++; /* Form a new set of tick mark values using this new nfill value */ ticks = (double *) astFree( (void *) ticks ); ntnew = FindMajTicks2( nfill, gap, centre, ngood, data, &ticks, status ); /* We need to know if the rate of increase of nticks has settled down to a constant value. Inititially increasing nfill will cause the total number of ticks (nticks) to increase rapidly. But this rate of increase will get less as any small gaps in axis coverage are filled in. We break out of the while loop when the rate of increase has settled down to a constant value (indicating that only very large holes are left in the axis coverage). Find the increase in the number of ticks caused by the increase in the nfill value made in this loop. If this increase is the same as the increase caused by the previous loop, increment the number of equal increases there have been. If the increase is different to last time, reset the number of equal increases to zero. */ inc = ntnew - nticks; if( inc == linc ) { nsame++; } else { nsame = 0; use_nfill = nfill; } /* If the past 3 increases in nfill has not caused any change in the rate of increase of nticks, then re-create the ticks for the value of nfill which started the current run of equal increment values, and leave the loop. */ if( nsame == 3 ) { ticks = (double *) astFree( (void *) ticks ); nticks = FindMajTicks2( use_nfill, gap, centre, ngood, data, &ticks, status ); break; } /* Save this times values for use in the next loop. */ linc = inc; nticks = ntnew; } /* Remove ticks which are not within the axis ranges to be displayed. Ticks which are very close to the limit are moved to a safe (but visually negligable) distance away from the limit). */ bot = astGetBottom( frame, axis ); top = astGetTop( frame, axis ); if( bot > top ) { tmp = top; top = bot; bot = tmp; } delta = 0.05*gap; r = ticks; for( k = 0; k < nticks; k++ ){ if( *r != AST__BAD ) { if( fabs( *r - bot ) < delta ) { *r = bot + delta; } else if( fabs( *r - top ) < delta ) { *r = top - delta; } else if( *r < bot || *r > top ) { *r = AST__BAD; } } r++; } /* Use the Mapping to place each tick mark value in its primary domain. This is a sort of normalization, similar but different to that performed by the astNorm method. */ Norm1( map, axis, nticks, ticks, refval, width, status ); /* Check for success. */ if( astOK ){ /* Ensure that all ticks marks are offset from the "centre" value by an integer multiple of the gap size. This is done by changing each tick value to the closest acceptable value. Also ensure that values close to zero (i.e. less than 1E-10 of the gap size) are set exactly to zero. */ r = ticks; for( k = 0; k < nticks; k++ ){ if( *r != AST__BAD ) { f = floor( 0.5 + ( *r - centre )/gap ); *r = f*gap + centre; if( fabs( *r ) < 1.0E-10*gap ) *r = 0.0; r++; } else { r++; } } /* Sort the tick values into increasing order. */ qsort( (void *) ticks, (size_t) nticks, sizeof(double), Compared ); /* Remove any duplicate or BAD tick values by shuffling the higher unique values down to over-write them. We subtract the centre value of both tick values before comparing them for equality in order to avoid unnecessarily removing tick marks in high precsion data. */ r = ticks + 1; w = ticks; for( k = 1; k < nticks && astOK; k++ ){ if( *r != AST__BAD && !astEQUALS( *r-centre, *w-centre, 1.0E8 ) ){ w++; *w = *r; } r++; } /* Modify the number of ticks to exclude the duplicate ones. */ nticks = (int) ( w - ticks ) + 1; } /* If an error has occurred, free the memory holding the major tick mark values, and indicate that zero tick marks have been found. */ if( !astOK ){ ticks = (double *) astFree( (void *) ticks ); nticks = 0; } /* Store the pointer to the major tick mark values. */ *tick_data = ticks; /* Return the number of major ticks. */ return nticks; } static int FindMajTicks2( int nfill, double gap, double centre, int ngood, double *data, double **tick_data, int *status ){ /* * Name: * FindMajTicks2 * Purpose: * Find candidate major tick marks for FindMajTicks. * Type: * Private function. * Synopsis: * #include "plot.h" * int FindMajTicks2( int nfill, double gap, double centre, int ngood, * double *data, double **tick_data, int *status ) * Class Membership: * Plot member function. * Description: * A service routine for function FindMajTicks. * Parameters: * nfill * Number of tick marks to extend by at edges of coverage * gap * The supplied value for the gaps between ticks on the axis. * centre * The supplied axis value at which to put a central tick. * ngood * The number of good values in the array pointer to by "data" (i.e. * values not equal to AST__BAD). * data * A pointer to an array holding sorted axis values covering the * entire plotting area. * tick_data * A pointer to a place at which to store a pointer to an array * holding the returned tick mark values for the axis. * status * Pointer to the inherited status variable. * Returned Value: * The number of major tick mark values stored in the array pointer to * by "*tick_data". * Notes: * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned in "tick_data", and zero * is returned for the function value. */ /* Local Variables: */ double *ticks; /* Pointer to the axis values at the major tick marks */ int i; /* Index of current axis value */ int j; /* Index of filled in tick */ int k; /* Tick mark index */ int klast; /* Index of the previous tick mark */ int nticks; /* Number of major tick marks used */ /* Initialise the returned pointer. */ *tick_data = NULL; /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ nticks = 0; /* Reserve memory to hold a reasonable number of tick mark axis values. This memory is later extended as necessary. */ ticks = (double *) astMalloc( sizeof(double)*( 6*nfill + 14 ) ); /* Check that the pointer can be used. */ if( astOK ){ /* Put the first tick marks just below the lowest axis value (in case the grid did not sample the entire range of the axis). */ k = floor( ( data[ 0 ] - centre )/gap ); for ( i = 0; i < nfill; i++ ){ ticks[ i ] = gap*(double)( k - nfill + i ) + centre; } ticks[ nfill ] = gap*(double)( k ) + centre; /* Initialise the number of major tick marks found so far. */ nticks = nfill + 1; /* Loop round each of the remaining good ordered axis values. */ klast = k; for( i = 1; i < ngood && astOK; i++ ) { /* Find the tick marks enclosing the axis value. The tick mark placed at "centre" is called tick mark zero, and tick marks are indexed (positive or negative) from an origin at "centre". Find the index of the more negative of the two tick marks enclosing the axis value. */ k = floor( ( data[ i ] - centre )/gap ); /* Ensure that the tick marks enclosing the current axis value are used. Some extra tick marks are used at the start and end of any gaps in the axis coverage. This is done to "fill in" small holes caused by the grid of physical coordinate values not completely covering the plotting area. Large holes, such as occur on an RA axis covering the 2 hour range from 23 hours to 1 hour are left without any tick marks in them (the "hole" in this case is the 22 hours range from 1 hour to 23 hours). */ for( j = 0; j < nfill + 1; j++ ){ if( k - klast > nfill + 2 - j ) { ticks = (double *) astGrow( ticks, nticks + 1, sizeof( double ) ); if( astOK ) ticks[ nticks++ ] = gap*(double)( klast + nfill + 1 - j ) + centre; } if( k - klast > nfill - j ) { ticks = (double *) astGrow( ticks, nticks + 1, sizeof( double ) ); if( astOK ) ticks[ nticks++ ] = gap*(double)( k - nfill + j ) + centre; } } /* Save the index of the current tick mark. */ klast = k; } /* Add extra tick marks beyond the end in case the grid did not sample the entire range of the axis. */ ticks = (double *) astGrow( ticks, nticks + nfill + 1, sizeof( double ) ); for( i = 0; i < nfill && astOK; i++ ){ ticks[ nticks++ ] = gap*(double)( klast + i + 1 ) + centre; } } /* If an error has occurred, free the memory holding the major tick mark values, and indicate that zero tick marks have been found. */ if( !astOK ){ ticks = (double *) astFree( (void *) ticks ); nticks = 0; } /* Store the pointer to the major tick mark values. */ *tick_data = ticks; /* Return the number of major ticks. */ return nticks; } static int FindDPTZ( AstFrame *fr, int axis, const char *fmt, const char *text, int *ndp, int *ntz, int *status ) { /* * Name: * FindDPTZ * Purpose: * Find the number of decimal places and trailing zeros in a label. * Type: * Private function. * Synopsis: * #include "plot.h" * int FindDPTZ( AstFrame *fr, int axis, const char *fmt, * const char *text, int *ndp, int *ntz, int *status ) * Class Membership: * Plot member function. * Description: * The supplied label is split into fields using the astFields method of * the supplied frame. The number of decimal places in the last * field is returned in *ndp, and the total number of trailing zeros * (excluding exponents) is returned in *ntz. * Parameters: * fr * The frame. * axis * The axis index to which the label applies. * fmt * The format string used to format the label. * text * The text of the label. * ndp * Pointer to an int in which to return the number of decimal * places in the final field. * ntz * Pointer to an int in which to return the number of trailing zeros. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if and only if a non-zero digit is found in any field. */ /* Local Constants: */ #define MAXFLD 10 /* Local Variables: */ char *fields[ MAXFLD ]; const char *a; const char *dot; const char *ff; double junk; int fnc; int i; int j; int l; int mxnd; int nc[ MAXFLD ]; int nf; int result; /* Initialise */ *ndp = 0; *ntz = 0; result = 0; /* Check inherited status */ if( !astOK ) return result; /* Split the label up into fields. */ nf = astFields( fr, axis, fmt, text, MAXFLD, fields, nc, &junk ); if( nf > 0 ) { /* Search the last fields (assumed to be the least significant) for a decimal point. */ ff = fields[ nf - 1 ]; fnc = nc[ nf - 1 ]; dot = strchr( ff, '.' ); if( dot && ( ff - dot >= fnc ) ) dot = NULL; /* Find the number of digits following the decimal point. */ if( dot ) { *ndp = strspn( dot + 1, "0123456789" ); mxnd = fnc - ( dot - ff ) - 1; if( *ndp > mxnd ) *ndp = mxnd; } else { *ndp = 0; } /* Loop through all the fields, from least significant to most significant, counting the number of trailing zeros. */ *ntz = 0; for( i = nf - 1; i >= 0; i-- ) { l = strspn( fields[ i ], "-+0123456789." ); if( l > nc[ i ] ) l = nc[ i ]; a = fields[ i ] + l - 1; for( j = l - 1; j >= 0; j--,a-- ){ if( *a == '0' ) { (*ntz)++; } else if( isdigit( *a ) ) { result = 1; break; } } if( j >= 0 ) break; } } /* Return the result. */ return result; /* Undefine local constants: */ #undef MAXFLD } static int FindString( int n, const char *list[], const char *test, const char *text, const char *method, const char *class, int *status ){ /* * Name: * FindString * Purpose: * Find a given string within an array of character strings. * Type: * Private function. * Synopsis: * #include "plot.h" * int FindString( int n, const char *list[], const char *test, * const char *text, const char *method, const char *class, * int *status ) * Class Membership: * Plot method. * Description: * This function identifies a supplied string within a supplied * array of valid strings, and returns the index of the string within * the array. The test option may not be abbreviated, but case is * insignificant. * Parameters: * n * The number of strings in the array pointed to be "list". * list * A pointer to an array of legal character strings. * test * A candidate string. * text * A string giving a description of the object, parameter, * attribute, etc, to which the test value refers. * This is only for use in constructing error messages. It should * start with a lower case letter. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The index of the identified string within the supplied array, starting * at zero. * Notes: * - A value of -1 is returned if an error has already occurred, or * if this function should fail for any reason (for instance if the * supplied option is not specified in the supplied list). */ /* Local Variables: */ int ret; /* The returned index */ /* Check global status. */ if( !astOK ) return -1; /* Compare the test string with each element of the supplied list. Leave the loop when a match is found. */ for( ret = 0; ret < n; ret++ ) { if( !Ustrcmp( test, list[ ret ], status ) ) break; } /* Report an error if the supplied test string does not match any element in the supplied list. */ if( ret >= n ) { astError( AST__OPT, "%s(%s): Illegal value '%s' supplied for %s.", status, method, class, test, text ); ret = -1; } /* Return the answer. */ return ret; } static char *FindWord( char *ptr, const char *d, const char **p, int *status ) { /* * Name: * FindWord * Purpose: * Return a copy of the next word in a supplied string. * Type: * Private function. * Synopsis: * #include "plot.h" * char *FindWord( char *ptr, const char *d, const char **p, int *status ) * Class Membership: * Plot method. * Description: * This function locates the start and end of the first word in the * string pointed to by *p, and returns a copy of the word. The pointer * *p is modified to point to the start of the following word (if any). * The characters which delimit words are supplied in string "d". * Parameters: * ptr * A pointer to a character string in which to store the returned * word. The memory holding this string should have been allocated * using one of the functions in the AST "memory" module. The memory * area will be modified in size to fit the returned word. A NULL * pointer may be supplied if no memory has yet been allocated. * Any memory pointed to by ptr is freed if a NULL pointer is * returned by this function (i.e. if no word is found). * d * A string holding the characters which are to be used as word * delimiters. * p * The address of a character string pointer. On entry, this pointer * identifies the start of the string to be searched. On exit, it is * modified to point to the start of the following word. It is * returned NULL if there are no more words. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated character string holding the * next word, or NULL if no word could be found. */ /* Local Variables: */ const char *a, *b, *c; char *ret; int nc; /* Free any allocated memory and return if any of the supplied pointers (except ptr) is NULL, or if an error has occurred. */ if( !astOK || !d || !p || !*p ) { (void) astFree( (void *) ptr ); return NULL; } /* Get a pointer to the first character which is not in "d". Terminate the loop if a null character is encountered. */ a = *p; while( *a && strchr( d, (int) *a ) ) a++; /* Get a pointer to the next character which is in "d". Terminate the loop if a null character is encountered. */ b = a; while( *b && !strchr( d, (int) *b ) ) b++; /* Get a pointer to the next character which is not in "d". Terminate the loop if a null character is encountered. */ c = b; while( *c && strchr( d, (int) *c ) ) c++; /* Adjust the supplied pointer so that it points to the start of the next word. */ if( *c ){ *p = c; } else { *p = NULL; } /* Get a null-terminated copy of the word between a and b. */ nc = b - a; if( nc > 0 ) { ret = (char *) astStore( (void *) ptr, (void *) a, (size_t) (nc + 1) ); ret[ nc ] = 0; } else { ret = astFree( (void *) ptr ); } return ret; } static const char *SplitValue( AstPlot *this, const char *value, int axis, int *split, int *status ) { /* * Name: * FormatValue * Purpose: * Format a coordinate value for a Frame axis. * Type: * Private function. * Synopsis: * #include "plot.h" * const char *SplitValue( AstPlot *this, const char *value, * int axis, int *split ) * Class Membership: * Plot member function * Description: * This function splits long formatted values (such as the date/time * format produced by the TimeFrame class) if possible onto two lines * by inclusion of Plot escape sequences. * Parameters: * this * Pointer to the Plot. * value * The formatted coordinate value. * axis * Indicates whether or not short lines should be split by * including a blank first line. If zero, and if "*split" is non-zero, * then short lines are put onto the second line,and the first line * is blank. * split * Pointer to an integer that controls behaviour: * * 0 - Split the line if it is too long, and return a value of +1 * in *split. * 1 - Split the line even if it does not need splitting, making * the first line blank and the second line containing all the * supplied text (*split is unchanged on exit). * Returned Value: * A pointer to a static buffer containing a null-terminated string * holding the (possibly split) formatted value. This will be a copy of * the supplied pointer if the string does not need to be split. * 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: */ astDECLARE_GLOBALS char *d; const char *result; float rsp; int aft_end; int aft_start; int bef_end; int bef_start; int i; int id; int idmin; int imin; int l; int naft; int nbef; int nlong; int nshort; int nsp; /* Initialise */ result = value; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Do nothing more if the formatted value already contains graphical escape sequences, or if graphical escapes sequences are not being interpreted. */ if( value && astGetEscape( this ) && !HasEscapes( value, status ) ) { /* Attempt to find a space close to the centre of the formatted string. */ l = strlen( value ); idmin = 2*l; imin = -1; for( i = 0; i < l; i++ ) { if( isspace( value[ i ] ) ) { id = abs( i - l/2 ); if( id < idmin ) { idmin = id; imin = i; } } } /* We split the line if previous lines have been split (i.e. if *split was non-zero on entry) or if this line is long AND it contains a space. This means that a sequence of long labels will not be split unless they contain spaces. */ if( *split || ( l > 9 && imin != -1 ) ) { *split = 1; /* Initialse the pointer into the returned buffer at which the next character will be placed. */ d = splitvalue_buff; /* If no spaces were found... */ if( imin == -1 ) { /* If axis is zero, we add a blank first line. */ if( axis == 0 ) { /* Fill the first line with spaces. */ for( i = 0; i < l; i++ ) *(d++) = ' '; /* Add an escape sequence that moves down by one character height. */ d += sprintf( d, "%%v170+" ); } /* Add the whole of the supplied text. */ for( i = 0; i < l; i++ ) *(d++) = value[ i ]; /* If a space was found... */ } else { /* Find the first and last non-blank characters before the mid-space. */ bef_start = -1; bef_end = -1; for( i = 0; i < imin; i++ ) { if( !isspace( value[ i ] ) ) { if( bef_start == -1 ) bef_start = i; bef_end = i; } } /* Find the first and last non-blank characters after the mid-space. */ aft_start = -1; aft_end = -1; for( i = imin + 1; i < l; i++ ) { if( !isspace( value[ i ] ) ) { if( aft_start == -1 ) aft_start = i; aft_end = i; } } /* How many significant characters before and after the space? */ nbef = bef_end - bef_start + 1; naft = aft_end - aft_start + 1; /* Get the lengths of the longer and shorter line. */ if( nbef > naft ) { nlong = nbef; nshort = naft; } else { nlong = naft; nshort = nbef; } /* Find the fractional number of spaces before the significant text of the shorter line.*/ rsp = 0.5*( nlong - nshort + 1 ); /* If the top line is the shorter line, put some spaces in at the start. */ if( nbef < naft ) { nsp = (int) rsp; for( i = 0; i < nsp; i++ ) *(d++) = ' '; } /* Add the significant text from the top line. */ for( i = bef_start; i <= bef_end; i++ ) *(d++) = value[ i ]; /* Add an escape sequence that moves down by one character height. */ d += sprintf( d, "%%v100+" ); /* Add an escape sequence that moves to the left by the required amount. */ d += sprintf( d, "%%<%d+", (int) ( 60.0*( (float) nlong - rsp )) ); /* Add the significant text from the bottom line. */ for( i = aft_start; i <= aft_end; i++ ) *(d++) = value[ i ]; } /* Terminate it. */ *d = 0; /* Return a pointer to the buffer. */ result = splitvalue_buff; } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static void Fpoly( AstPlot *this, const char *method, const char *class, int *status ){ /* * Name: * Fpoly * Purpose: * Flush all stored poly lines to the graphics system. * Type: * Private function. * Synopsis: * #include "plot.h" * void Fpoly( AstPlot *this, const char *method, const char *class, * int *status ) * Class Membership: * Plot member function. * Description: * This function sends all previously drawn poly lines to the graphics * system for rendering, and frees the memory used to hold the poly * lines. It attempts to reduce the number of graphics calls by * concatenating continuous polylines together. * Parameters: * this * Pointer to the Plot. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS float xmid; float xt; float ymid; float *xnew; float *ynew; int polylen; float *xp1; float *xp2; float *yp1; float *yp2; float yt; int *ekey; int *p; int *skey; int *drawn; int ihi; int ikey; int ilo; int imid; int ipass; int ipoint; int ipoly; int jpoly; int kpoly; int *polylist; int npoly; int np; /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Output any pending polyline. */ Opoly( this, status ); /* If there is just one polyline to output, just draw it and then free the memory used to hold the polyline. */ if( Poly_npoly == 1 ) { GLine( this, Poly_np[ 0 ], Poly_xp[ 0 ], Poly_yp[ 0 ], method, class, status ); Poly_xp[ 0 ] = astFree( Poly_xp[ 0 ] ); Poly_yp[ 0 ] = astFree( Poly_yp[ 0 ] ); Poly_np[ 0 ] = 0; /* If there are multiple polylines to output, see if any of them can be combined before drawing them. */ } else if( Poly_npoly > 1 ) { /* No polyline buffer allocated yet. */ xnew = NULL; ynew = NULL; /* Allocate an array to hold the order in which polylines should be concatenated. Each value in this array will be the index of one of the original polylines. A positive index indicates that the polyline should be appended in its original order. A negative index indicates that the polyline should be appended in reversed order. Polyline zero is always appended in its original order. */ polylist = astMalloc( Poly_npoly*sizeof( int ) ); npoly = 0; /* Create an array of drawn, one for each individual polyline. The flag is zero if the corresponding polyline has not yet been drawn. */ drawn = astCalloc( Poly_npoly, sizeof( int ) ); /* Create two sorted keys for the polylines - one that sorts them into increasing x at the start of the polyline, and another that sorts them into increasing x at the end of the polyline. */ skey = astMalloc( Poly_npoly*sizeof( int ) ); ekey = astMalloc( Poly_npoly*sizeof( int ) ); if( astOK ) { p = skey; for( ipoly = 0; ipoly < Poly_npoly; ipoly++ ) *(p++) = ipoly; qsort( skey, Poly_npoly, sizeof(int), Fpoly_scmp ); p = ekey; for( ipoly = 0; ipoly < Poly_npoly; ipoly++ ) *(p++) = ipoly; qsort( ekey, Poly_npoly, sizeof(int), Fpoly_ecmp ); } /* Continue to search for separate polylines that can be combined together until we know there are no more. */ while( astOK ) { /* Search for the first polyline that has not already been drawn. */ for( ipoly = 0; ipoly < Poly_npoly; ipoly++ ) { if( !drawn[ ipoly ] ) break; } /* Leave the loop if no more polylines remain to be plotted. */ if( ipoly == Poly_npoly ) break; /* Initialise the list of polylines to hold the polyline found above, in its forward sense. */ polylist[ 0 ] = ipoly; npoly = 1; drawn[ 0 ] = 1; /* Initialise the concatenation point to be the end of the polyline found above. Also, initialise the total number of points in the combined polyline (polylen). */ ipoint = Poly_np[ ipoly ] - 1; xt = Poly_xp[ ipoly ][ ipoint ]; yt = Poly_yp[ ipoly ][ ipoint ]; polylen = ipoint + 1; /* Loop until we can find no more polylines to append to the list. A polyline can be appended if it starts or ends at the current concatenation point. */ while( astOK ) { /* On the first pass through the next loop, search for a polyline that starts at the concatenation point. If no such polyline is found, do a second pass in which we search for a polyline that ends at the concatenation point. Do not include any previously drawn polylines in the search. */ for( ipass = 0; ipass < 2; ipass++ ) { /* We use a binary chop to find a polyline which starts (or ends) at the x value of the concatenation point. */ jpoly = -1; ilo = 0; ihi = Poly_npoly - 1; while( 1 ) { imid = ( ilo + ihi )/2; if( ipass == 0 ) { jpoly = skey[ imid ]; xmid = Poly_xp[ jpoly ][ 0 ]; } else { jpoly = ekey[ imid ]; xmid = Poly_xp[ jpoly ][ Poly_np[ jpoly ] - 1 ]; } if( astEQUALS( xmid, xt, 1.0E8 ) ) { ikey = imid; break; } else if( xmid > xt ) { if( ihi == imid ) { if( ipass == 0 ) { jpoly = skey[ ilo ]; xmid = Poly_xp[ jpoly ][ 0 ]; } else { jpoly = ekey[ ilo ]; xmid = Poly_xp[ jpoly ][ Poly_np[ jpoly ] - 1 ]; } if( !astEQUALS( xmid, xt, 1.0E8 ) ) jpoly = -1; ikey = ilo; break; } ihi = imid; } else { if( ilo == imid ) { if( ipass == 0 ) { jpoly = skey[ ihi ]; xmid = Poly_xp[ jpoly ][ 0 ]; } else { jpoly = ekey[ ihi ]; xmid = Poly_xp[ jpoly ][ Poly_np[ jpoly ] - 1 ]; } if( !astEQUALS( xmid, xt, 1.0E8 ) ) jpoly = -1; ikey = ihi; break; } ilo = imid; } } /* If found, there may be more than one such polyline. So we now search for a polyline that also has the y value of the concatenation point. */ if( jpoly != -1 ) { /* If the polyline found above starts (or ends) at the same Y value as the concatenation point, then we have found the required polyline. */ if( ipass == 0 ) { ymid = Poly_yp[ jpoly ][ 0 ]; } else { ymid = Poly_yp[ jpoly ][ Poly_np[ jpoly ] - 1 ]; } if( astEQUALS( ymid, yt, 1.0E8 ) && !drawn[ jpoly ] ) break; jpoly = -1; /* Otherwise, search down the list, starting at the polyline found above. */ if( imid > 0 ) { for( ikey = imid - 1; ikey >= 0; ikey-- ) { if( ipass == 0 ) { kpoly = skey[ ikey ]; xmid = Poly_xp[ kpoly ][ 0 ]; ymid = Poly_yp[ kpoly ][ 0 ]; } else { kpoly = ekey[ ikey ]; xmid = Poly_xp[ kpoly ][ Poly_np[ kpoly ] - 1 ]; ymid = Poly_yp[ kpoly ][ Poly_np[ kpoly ] - 1 ]; } if( astEQUALS( xmid, xt, 1.0E8 ) ) { if( astEQUALS( ymid, yt, 1.0E8 ) && !drawn[ kpoly ] ) { jpoly = kpoly; break; } } else { break; } } if( jpoly != -1 ) break; } /* Now search up the list, starting at the polyline found above. */ if( imid < Poly_npoly - 1 ) { for( ikey = imid + 1; ikey < Poly_npoly; ikey++ ) { if( ipass == 0 ) { kpoly = skey[ ikey ]; xmid = Poly_xp[ kpoly ][ 0 ]; ymid = Poly_yp[ kpoly ][ 0 ]; } else { kpoly = ekey[ ikey ]; xmid = Poly_xp[ kpoly ][ Poly_np[ kpoly ] - 1 ]; ymid = Poly_yp[ kpoly ][ Poly_np[ kpoly ] - 1 ]; } if( astEQUALS( xmid, xt, 1.0E8 ) ) { if( astEQUALS( ymid, yt, 1.0E8 ) && !drawn[ kpoly ] ) { jpoly = kpoly; break; } } else { break; } } if( jpoly != -1 ) break; } } } /* If a polyline was found that can be combined with the total polyline, increment the total number of points in the total polyline, add it to the list, and update the concatenation point. Note, we can omit the start or end point of the new polyline since it will already be present in the total polyline, hence the " - 1 " below. */ if( ipass < 2 ) { ipoint = Poly_np[ jpoly ] - 1; if( ipass == 0 ) { polylist[ npoly++ ] = jpoly; xt = Poly_xp[ jpoly ][ ipoint ]; yt = Poly_yp[ jpoly ][ ipoint ]; } else { polylist[ npoly++ ] = -jpoly; xt = Poly_xp[ jpoly ][ 0 ]; yt = Poly_yp[ jpoly ][ 0 ]; } polylen += ipoint; /* Indicate the polyline has been drawn. */ drawn[ jpoly ] = 1; /* If we cannot find any polyline that starts or ends at the concatenation point, then we have completed the total polyline. So break out of the loop, and move on to draw the total polyline. */ } else { break; } } /* If a single polyline is to be drawn, just draw it. */ if( npoly == 1 ) { jpoly = polylist[ 0 ]; GLine( this, Poly_np[ jpoly ], Poly_xp[ jpoly ], Poly_yp[ jpoly ], method, class, status ); /* If more than one polyline is to be drawn, ensure we have arrays that are large enough to hold all the vertices in the combined polyline. */ } else { xnew = astRealloc( xnew, polylen*sizeof( float ) ); ynew = astRealloc( ynew, polylen*sizeof( float ) ); if( astOK ) { /* Loop round all the polylines that are to be combined to form the total polyline, and copy all the vertex coordinates into the above arrays. */ xp1 = xnew; yp1 = ynew; for( ipoly = 0; ipoly < npoly; ipoly++ ) { /* Index of the next polyline to include in the total polyline. */ jpoly = polylist[ ipoly ]; /* The jpoly value is positive if the polylline is to be inclued in its original direction. */ if( jpoly >= 0 ) { /* Use the whole of the first polyline. */ if( ipoly == 0 ) { np = Poly_np[ jpoly ]; xp2 = Poly_xp[ jpoly ]; yp2 = Poly_yp[ jpoly ]; /* Omit eh first point of subsequent polylines since it will be the same as the last pointy already in the total polyline. */ } else { np = Poly_np[ jpoly ] - 1; xp2 = Poly_xp[ jpoly ] + 1; yp2 = Poly_yp[ jpoly ] + 1; } /* Copy the vertex values in their original order, and update the pointers to the next element of the total polyline. */ memcpy( xp1, xp2, np*sizeof(float) ); memcpy( yp1, yp2, np*sizeof(float) ); xp1 += np; yp1 += np; /* The jpoly value is negative if the polyline is to be included in its reversed direction. */ } else { jpoly = -jpoly; /* Get the number of points to copy. Omit the last point if this is not the first polyline, since it is already in the total polyline. */ if( ipoly == 0 ) { np = Poly_np[ jpoly ]; } else { np = Poly_np[ jpoly ] - 1; } /* Copy the individual values in reversed order. */ xp2 = Poly_xp[ jpoly ] + np - 1; yp2 = Poly_yp[ jpoly ] + np - 1; for( ipoint = 0; ipoint < np; ipoint++ ) { *(xp1++) = *(xp2--); *(yp1++) = *(yp2--); } } } /* And finally, draw the total polyline. */ GLine( this, polylen, xnew, ynew, method, class, status ); } } } /* Free all the individual polylines. */ for( ipoly = 0; ipoly < Poly_npoly; ipoly++ ) { Poly_xp[ ipoly ] = astFree( Poly_xp[ ipoly ] ); Poly_yp[ ipoly ] = astFree( Poly_yp[ ipoly ] ); Poly_np[ ipoly ] = 0; } /* Free other resources. */ polylist = astFree( polylist ); drawn = astFree( drawn ); xnew = astFree( xnew ); ynew = astFree( ynew ); skey = astFree( skey ); ekey = astFree( ekey ); } /* Indicate that all polylines have been sent to the graphics system. */ Poly_npoly = 0; } static int Fpoly_ecmp( const void *a, const void *b ){ /* * Name: * Fpoly_ecmp * Purpose: * Compare two polylines ending X position * Type: * Private function. * Synopsis: * #include "plot.h" * int Fpoly_ecmp( const void *a, const void *b ) * Class Membership: * Plot member function. * Description: * This function is designed to be used as a comparison function with * the "qsort" function. It is used in function Fpoly. * * If orders the two polylines on the basis of the X coordinate at * their ends. * Parameters: * a * Pointer to an int holding the index of the first polyline. * b * Pointer to an int holding the index of the second polyline. * Returned Value: * -1 if the first polyline ends at a lower X than the second. * +1 if the first polyline ends at a higher X than the second. * 0 if the two polylines end at the same X. */ /* Local Variables: */ float xa; /* X at end of first polyline */ float xb; /* X at end of second polyline */ int result = 0; /* Returned value */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get the x coord at the end of the two polylines. */ xa = Poly_xp[ *( (int *) a) ][ Poly_np[ *( (int *) a) ] - 1 ]; xb = Poly_xp[ *( (int *) b) ][ Poly_np[ *( (int *) b) ] - 1 ]; /* Compare them. */ if( xa < xb ) { result = -1; } else if( xa > xb ){ result = 1; } return result; } static int Fpoly_scmp( const void *a, const void *b ){ /* * Name: * Fpoly_scmp * Purpose: * Compare two polylines starting X position * Type: * Private function. * Synopsis: * #include "plot.h" * int Fpoly_scmp( const void *a, const void *b ) * Class Membership: * Plot member function. * Description: * This function is designed to be used as a comparison function with * the "qsort" function. It is used in function Fpoly. * * If orders the two polylines on the basis of the X coordinate at * their starts. * Parameters: * a * Pointer to an int holding the index of the first polyline. * b * Pointer to an int holding the index of the second polyline. * Returned Value: * -1 if the first polyline starts at a lower X than the second. * +1 if the first polyline starts at a higher X than the second. * 0 if the two polylines starts at the same X. */ /* Local Variables: */ float xa; /* X at start of first polyline */ float xb; /* X at start of second polyline */ int result = 0; /* Returned value */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get the x coord at the start of the two polylines. */ xa = Poly_xp[ *( (int *) a) ][ 0 ]; xb = Poly_xp[ *( (int *) b) ][ 0 ]; /* Compare them. */ if( xa < xb ) { result = -1; } else if( xa > xb ){ result = 1; } return result; } static AstFrameSet *Fset2D( AstFrameSet *fset, int ifrm, int *status ) { /* * Name: * Fset2D * Purpose: * Create a FrameSet with no more than 2 dimensions for a given Frame. * Type: * Private function. * Synopsis: * #include "plot.h" * AstFrameSet *Fset2D( AstFrameSet *fset, int ifrm, int *status ) * Class Membership: * Plot method. * Description: * This function checks a specified Frame in the supplied FrameSet. * If the Frame has more than 2 dimensions, a new Frame is added to * the FrameSet containing just the first two axes of the specified * Frame. A PermMap is used to connect this Frame to the specified * Frame, which supplied bad values for any missing axes. If the * specified Frame is the base Frame in the supplied FrameSet, then the * new Frame becomes the base Frame in the returned FrameSet. Like-wise, * if the specified Frame is the current Frame, then the new Frame * will be the current Frame in the returned FrameSet. * * If the specified Frame does not have more than 2 axes, then a clone * of the FrameSet pointer is returned, otherwise the returned pointer * points to a copy of the supplied FrameSet with the new 2-D Frame * added. * Parameters: * fset * Pointer to the FrameSet. * ifrm * The index of the Frame to check. This should be AST__BASE or * AST_CURRENT. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a FrameSet in which the Frame with index given by ifrm * has no more than 2 axes. */ /* Local Variables: */ AstFrame *frm; AstFrame *newfrm; AstFrameSet *ret; AstPermMap *map; double zero; int *inperm; int axes[2]; int i; int ic; int nax; /* Check the inherited status. */ if( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ map = NULL; /* Get a pointer to the requested Frame in the supplied FrameSet. */ frm = astGetFrame( fset, ifrm ); /* See how many dimensions the specified Frame of the supplied FrameSet has. */ nax = astGetNaxes( frm ); /* If it is more than 2-dimensionbal, create a 2D Frame by picking axes 1 and 2 from the original Frame. */ if( nax > 2 ) { axes[ 0 ] = 0; axes[ 1 ] = 1; newfrm = astPickAxes( frm, 2, axes, NULL ); /* Create a PermMap to describe the mapping between the two Frames. Use zero as the value for unknown axes (the optional mapping which can be returned by astPickAxes uses AST__BAD for unknown axes). */ inperm = (int *) astMalloc( sizeof(int)*(size_t) nax ); if( astOK ){ inperm[ 0 ] = 0; inperm[ 1 ] = 1; for( i = 2; i < nax; i++ ) inperm[ i ] = -1; zero = 0.0; map = astPermMap( nax, inperm, 2, axes, &zero, "", status ); inperm = (int *) astFree( (void *) inperm ); } /* Get a copy of the supplied FrameSet. */ ret = astCopy( fset ); /* Add the new Frame to the FrameSet (it becomes the current Frame). */ ic = astGetCurrent( ret ); astAddFrame( ret, ifrm, map, newfrm ); newfrm = astAnnul( newfrm ); /* If the new Frame was derived from the base frame, set the new base Frame, and re-instate the original current Frame */ if( ifrm == AST__BASE ){ astSetBase( ret, astGetCurrent( ret ) ); astSetCurrent( ret, ic ); } /* If the specified Frame in the supplied FrameSet is 2-dimensional, just return a clone of it. */ } else { ret = astClone( fset ); } /* Annul the pointer to the original Frame. */ frm = astAnnul( frm ); return ret; } static int FullForm( const char *list, const char *test, const char *text, const char *method, const char *class, int *status ){ /* * Name: * FullForm * Purpose: * Identify the full form of an option string. * Type: * Private function. * Synopsis: * #include "plot.h" * int FullForm( const char *list, const char *test, const char *text, * const char *method, const char *class, int *status ) * Class Membership: * Plot method. * Description: * This function identifies a supplied test option within a supplied * list of valid options, and returns the index of the option within * the list. The test option may be abbreviated, and case is * insignificant. * Parameters: * list * A list of space separated option strings. * test * A candidate option string. * text * A string giving the context in which the supplied test option * was supplied. For instance, this may be an attribute setting string. * This is only for use in constructing error messages. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The index of the identified option within the supplied list, starting * at zero. * Notes: * - A value of -1 is returned if an error has already occurred, or * if this function should fail for any reason (for instance if the * supplied option is not uniquely specified in the supplied list). */ /* Local Variables: */ char *option; /* Pointer to a copy of the next option */ const char *p; /* Pointer to the start of the next word */ int i; /* Current option index */ int len; /* Length of supplied option */ int nmatch; /* Number of matching options */ int ret; /* The returned index */ /* Initialise the answer to indicate that the option has not been uniquely identified. */ ret = -1; /* Check global status. */ if( !astOK ) return ret; /* Save the number of characters in the supplied test option (excluding trailing spaces). */ len = ChrLen( test, status ); /* Compare the supplied test option against each of the known options in turn. Count the number of matches. */ nmatch = 0; p = list; option = FindWord( NULL, " ", &p, status ); i = 0; while( option ){ /* If the test string and the current option are identical (including length). use the current option. */ /* If every character in the supplied label matches the corresponding character in the current test label we have a match. Increment the number of matches and save the current item index. If the test string and the current option are identical (including length), use the current option. */ if( !Ustrncmp( test, option, len, status ) ) { ret = i; if( ChrLen( option, status ) == len ) { nmatch = 1; option = astFree( option ); break; } else { nmatch++; } } /* Get a pointer to the next option. */ option = FindWord( option, " ", &p, status ); i++; } /* Report an error if no match was found, and return -1. */ if( !nmatch ){ astError( AST__OPT, "%s(%s): Option '%.*s' is unknown in '%.*s'.", status, method, class, len, test, ChrLen( text, status ), text ); ret = -1; /* Report an error if the label was ambiguous, and return -1. */ } else if( nmatch > 1 ){ astError( AST__OPT, "%s(%s): Option '%.*s' is ambiguous in '%.*s'.", status, method, class, len, test, ChrLen( text, status ), text ); ret = -1; } /* Return the answer. */ return ret; } static void GAttr( AstPlot *this, int attr, double value, double *old_value, int prim, const char *method, const char *class, int *status ) { /* * * Name: * GAttr * Purpose: * Call the GAttr Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GAttr( AstPlot *this, int attr, double value, double *old_value, * int prim, const char *method, const char *class, int *status ) * Class Membership: * Plot private function. * Description: * This function calls the GAttr grf function to enquire or set a * graphics attribute value. It either calls the version registered using * astGrfSet, or the version in the linked grf module. The linked version * is used if the Grf attribute is zero, or if no function has been * registered for GAttr using astGrfSet. * Parameters: * this * The Plot. * attr * An integer value identifying the required attribute. The * following symbolic values are defined in grf.h: * * GRF__STYLE - Line style. * GRF__WIDTH - Line width. * GRF__SIZE - Character and marker size scale factor. * GRF__FONT - Character font. * GRF__COLOUR - Colour index. * value * A new value to store for the attribute. If this is AST__BAD * no value is stored. * old_value * A pointer to a double in which to return the attribute value. * If this is NULL, no value is returned. * prim * The sort of graphics primitive to be drawn with the new attribute. * Identified by the following values defined in grf.h: * GRF__LINE * GRF__MARK * GRF__TEXT * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. Also return if there is nothing to do. */ if ( !astOK || ( !old_value && value == AST__BAD ) ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GATTR ] ) { grf_status = ( *( this->GAttr ) )( this, attr, value, old_value, prim, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGAttr( attr, value, old_value, prim ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGAttr. ", status, method, class ); } } static AstKeyMap *GetGrfContext( AstPlot *this, int *status ){ /* *++ * Name: c astGetGrfContext f AST_GETGRFCONTEXT * Purpose: * Return the KeyMap that describes a Plot's graphics context. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c AstKeyMap *astGetGrfContext( AstPlot *this ) f RESULT = AST_GETGRFCONTEXT( THIS, STATUS ) * Class Membership: * Plot method. * Description: c This function f This routine * returns a reference to a KeyMap that will be passed to any drawing c functions registered using astGrfSet. f routines registered using AST_GRFSET. * This KeyMap can be used by an application to pass information to c the drawing functions f the drawing routines * about the context in which they are being called. The contents of * the KeyMap are never accessed byt the Plot class itself. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetGrfContext() f AST_GETGRFCONTEXT = INTEGER * A pointer to the graphics context KeyMap. The returned pointer * should be annulled when it is no longer needed. *-- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Ensure that a grfcon KeyMap exists. */ (void) astGrfConID(this); /* Return a cloned pointer to the KeyMap. */ return astClone( this->grfcontext ); } AstKeyMap *astGrfConID_( AstPlot *this, int *status ) { /* *+ * * Name: * astGrfConID * Purpose: * Ensure a GrfContext KeyMap exists and return an ID for it. * Type: * Protected function. * Synopsis: * #include "plot.h" * AstKeyMap *astGrfConID( AstPlot *this ) * Class Membership: * Plot private function. * Description: * This function creates a GrfContext KeyMap if the Plot does not * currently have one, and returns an ID for it. * Parameters: * this * The Plot. * Returned Value: * ID for the GrfContext KeyMap. *- */ if( !this->grfcontext ) { this->grfcontext = astKeyMap("", status ); this->grfcontextID = astMakeId( astClone( this->grfcontext ) ); astExempt( this->grfcontextID ); } return this->grfcontextID; } static void GScales( AstPlot *this, float *alpha, float *beta, const char *method, const char *class, int *status ) { /* * * Name: * GScales * Purpose: * Call the GScales Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GScales( AstPlot *this, float *alpha, float *beta, * const char *method, const char *class, int *status ) * Class Membership: * Plot private function. * Description: * This function calls the GScales grf function, either calling the * version registered using astGrfSet, or the version in the linked grf * module. The linked version is used if the Grf attribute is zero, or if * no function has been registered for GScales using astGrfSet. * Parameters: * this * The Plot. * alpha * A pointer to the location at which to return the scale for the * X axis (i.e. Xnorm = alpha*Xworld). * beta * A pointer to the location at which to return the scale for the * Y axis (i.e. Ynorm = beta*Yworld). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* if we already have the required values, return them. */ if( Grf_alpha != 0.0 && Grf_beta != 0.0 ) { if( alpha ) *alpha = Grf_alpha; if( beta ) *beta = Grf_beta; return; } /* Check that the grf mdoule can give us scales information. */ if( GCap( this, GRF__SCALES, 1, status ) ) { /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GSCALES ] ) { grf_status = ( *( this->GScales ) )( this, &Grf_alpha, &Grf_beta, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGScales( &Grf_alpha, &Grf_beta ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Check neither value is zero. */ if( grf_status && ( Grf_alpha == 0.0 || Grf_beta == 0.0 ) ) { astError( AST__GRFER, "astGScales: Returned axis scales are %g and %g " "but zero is illegal!", status, Grf_alpha, Grf_beta ); grf_status = 0; } /* Report an error if anything went wrong, and return safe values. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGScales. ", status, method, class ); Grf_alpha = 1.0; Grf_beta = 1.0; } /* If the grf module is not capable of giving us scale information, then just assume the the axes are equally scaled, except for any axis reversal indicated in the supplied Plot. */ } else { Grf_alpha = ( this->xrev ) ? -1.0 : 1.0; Grf_beta = ( this->yrev ) ? -1.0 : 1.0; } /* Store them for future use. */ if( alpha ) *alpha = Grf_alpha; if( beta ) *beta = Grf_beta; } static int GCap( AstPlot *this, int cap, int value, int *status ){ /* * * Name: * GCap * Purpose: * Call the GCap Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * int GCap( AstPlot *this, int cap, int value, int *status ) * Class Membership: * Plot private function. * Description: * This function calls the GCap grf function to inquire a capability * of the grf module, either calling the version registered using * astGrfSet, or the version in the linked grf module. The linked * version is used if the Grf attribute is zero, or if no function * has been registered for GCap using astGrfSet. * Parameters: * this * The Plot. * cap * The capability to be inquired aboue. * value * The value ot assign to the capability. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the grf module is capabale of performing the action * requested by "cap". */ /* Local Variables: */ int result; /* Value retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return 0; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GCAP ] ) { result = ( *( this->GCap ) )( this, cap, value, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { result = astGCap( cap, value ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Return the result. */ return result; } static void GenCurve( AstPlot *this, AstMapping *map, int *status ){ /* *++ * Name: c astGenCurve f AST_GENCURVE * Purpose: * Draw a generalized curve. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astGenCurve( AstPlot *this, astMapping *map ) f CALL AST_GENCURVE( THIS, MAP ) * Class Membership: * Plot method. * Description: c This function draws a general user-defined curve defined by the f This routine draws a general user-defined curve defined by the * supplied Mapping. Note that the curve is transformed into graphical * coordinate space for plotting, so that a straight line in * physical coordinates may result in a curved line being drawn if * the Mapping involved is non-linear. Any discontinuities in the * Mapping between physical and graphical coordinates are c catered for, as is any clipping established using astClip. f catered for, as is any clipping established using AST_CLIP. * c If you need to draw simple straight lines (geodesics), astCurve c or astPolyCurve will usually be easier to use and faster. f If you need to draw simple straight lines (geodesics), AST_CURVE f or AST_POLYCURVE will usually be easier to use and faster. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c map f MAP = INTEGER (Given) * Pointer to a Mapping. This Mapping should have 1 input * coordinate representing offset along the required curve, * normalized so that the start of the curve is at offset 0.0, * and the end of the curve is at offset 1.0. Note, this offset * does not need to be linearly related to distance along the curve. * The number of output coordinates should equal the number of axes * in the current Frame of the Plot. The Mapping should map a * specified offset along the curve, into the corresponding * coordinates in the current Frame of the Plot. The inverse * transformation need not be defined. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - An error results if the base Frame of the Plot is not 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *class; /* Object class */ const char *method; /* Current method */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double tol; /* Absolute tolerance value */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ int i; /* Loop count */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astGenCurve"; class = astGetClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Only proceed if there has been no error. */ if( astOK ){ /* Initialise the bounding box for primitives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__CURVE_ID, 1, GRF__LINE, method, class ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Set up the externals used to communicate with the Map4 function... */ Map4_ncoord = astGetNout( this ); Map4_plot = this; Map4_map = astGetMapping( this, AST__BASE, AST__CURRENT ); Map4_umap = map; /* Convert the tolerance from relative to absolute graphics coordinates. */ tol = astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Now set up the external variables used by the Crv and CrvLine function. */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_ux0 = AST__BAD; Crv_tol = tol; Crv_limit = 0.5*tol*tol; Crv_map = Map4; Crv_ink = 1; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_out = 1; Crv_xbrk = Curve_data.xbrk; Crv_ybrk = Curve_data.ybrk; Crv_vxbrk = Curve_data.vxbrk; Crv_vybrk = Curve_data.vybrk; Crv_clip = astGetClip( this ) & 1; /* Set up a list of points spread evenly over the curve. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Map these points into graphics coordinates. */ Map4( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map4 to draw the curve. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* End the current poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map4. */ Map4( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* If no part of the curve could be drawn, set the number of breaks and the length of the drawn curve to zero. */ if( Crv_out ) { Crv_nbrk = 0; Crv_len = 0.0F; /* Otherwise, add an extra break to the returned structure at the position of the last point to be plotted. */ } else { Crv_nbrk++; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; } } /* Store extra information about the curve in the returned structure, and purge any zero length sections. */ Curve_data.length = Crv_len; Curve_data.out = Crv_out; Curve_data.nbrk = Crv_nbrk; PurgeCdata( &Curve_data, status ); /* Annul the Mapping. */ Map4_map = astAnnul( Map4_map ); /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__CURVE_ID, 0, GRF__LINE, method, class ); } /* Return. */ return; } static int GetLabelUnits( AstPlot *this, int axis, int *status ) { /* * Name: * GetLabelUnits * Purpose: * Return the value of the LabelUnits attribute for a Plot axis. * Type: * Private function. * Synopsis: * #include "plot.h" * int GetLabelUnits( AstPlot *this, int axis, int *status ) * Class Membership: * Plot method. * Description: * This function returns the value of the LabelUnits attribute for a * Plot axis, supplying a suitable default if not set. * Parameters: * this * The Plot. * axis * The axis index (zero based). * status * Pointer to the inherited status variable. * Returned Value: * The attribute value. */ /* Local Variables: */ AstFrame *fr; /* The current Frame in the Plot */ AstFrame *primframe; /* The primary Frame holding the requested axis */ AstSystemType system; /* The SkyFrame System attribute */ int primaxis; /* Index of requested axis in the primary frame */ int ret; /* The returned value */ /* Initialise. */ ret = 0; /* Check global status. */ if( !astOK ) return ret; /* If a value has been set, return it. */ ret = this->labelunits[ axis ]; /* If no value has been set, find a default. */ if( ret == -1 ) { /* Assume "no" for any SkyAxis axes within the current frame of the Plot, and "yes" for other axes. Get a pointer to the current Frame of the Plot. */ fr = astGetFrame( this, AST__CURRENT ); /* The current Frame may be a CmpFrame. So find the primary Frame containing the requested axis. The primary Frame is guaranteed not to be a CmpFrame. */ astPrimaryFrame( fr, axis, &primframe, &primaxis ); /* If the primary Frame is a SkyFrame representing ICRS, equatorial, ecliptic, galactic or supergalactic coords, use a default of "no" for LabelUnits. Otherwise use a default of "yes". */ ret = 1; if( IsASkyFrame( (AstObject *) primframe, status ) ) { system = astGetSystem( primframe ); if( system == AST__ICRS || system == AST__FK4 || system == AST__FK4_NO_E || system == AST__FK5 || system == AST__GAPPT || system == AST__ECLIPTIC || system == AST__GALACTIC || system == AST__SUPERGALACTIC ) ret = 0; } /* Annul the frame pointers. */ primframe = astAnnul( primframe ); fr = astAnnul( fr ); } /* Return the answer. */ return ret; } static void GBBuf( AstPlot *this, const char *method, const char *class, int *status ) { /* * * Name: * GBBuf * Purpose: * Call the GBBuf Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GBBuf( AstPlot *this, const char *method, * const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the GBBuf grf function to begin a new graphics * context, either calling the version registered using astGrfSet, or * the version in the linked grf module. The linked version is used * if the Grf attribute is zero, or if no function has been registered * for GBBuf using astGrfSet. * Parameters: * this * The Plot. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GBBUF ] ) { grf_status = ( *( this->GBBuf ) )( this, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGBBuf(); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGBBuf. ", status, method, class ); } } static void GEBuf( AstPlot *this, const char *method, const char *class, int *status ) { /* * * Name: * GEBuf * Purpose: * Call the GEBuf Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GEBuf( AstPlot *this, const char *method, * const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the GEBuf grf function to end the current graphics * context, either calling the version registered using astGrfSet, or * the version in the linked grf module. The linked version is used * if the Grf attribute is zero, or if no function has been registered * for GEBuf using astGrfSet. * Parameters: * this * The Plot. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GEBUF ] ) { grf_status = ( *( this->GEBuf ) )( this, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGEBuf(); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGEBuf. ", status, method, class ); } } static void GFlush( AstPlot *this, const char *method, const char *class, int *status ) { /* * * Name: * GFlush * Purpose: * Call the Gflush Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GFlush( AstPlot *this, const char *method, * const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the Gflush grf function to flush graphics, either * calling the version registered using astGrfSet, or the version in the * linked grf module. The linked version is used if the Grf attribute * is zero, or if no function has been registered for Gflush using * astGrfSet. * Parameters: * this * The Plot. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GFLUSH ] ) { grf_status = ( *( this->GFlush ) )( this, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGFlush(); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGFlush. ", status, method, class ); } } static void GLine( AstPlot *this, int n, const float *x, const float *y, const char *method, const char *class, int *status ) { /* * * Name: * GLine * Purpose: * Call the Gline Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GLine( AstPlot *this, int n, const float *x, * const float *y, const char *method, * const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the Gline grf function to draw a polyline, either * calling the version registered using astGrfSet, or the version in the * linked grf module. The linked version is used if the Grf attribute * is zero, or if no function has been registered for Gline using * astGrfSet. * Parameters: * this * The Plot. * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int i; /* Loop count */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Do not draw anything if we are using "invisible ink". */ if( astGetInvisible( this ) ) { grf_status = 1; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ } else if( astGetGrf( this ) && this->grffun[ AST__GLINE ] ) { grf_status = ( *( this->GLine ) )( this, n, x, y, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGLine( n, x, y ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGLine. ", status, method, class ); /* Otherwise, update the box containing all drawn graphics primitives. */ } else if( !Boxp_freeze ){ for( i = 0; i < n; i++ ) { Boxp_lbnd[ 0 ] = astMIN( x[ i ], Boxp_lbnd[ 0 ] ); Boxp_ubnd[ 0 ] = astMAX( x[ i ], Boxp_ubnd[ 0 ] ); Boxp_lbnd[ 1 ] = astMIN( y[ i ], Boxp_lbnd[ 1 ] ); Boxp_ubnd[ 1 ] = astMAX( y[ i ], Boxp_ubnd[ 1 ] ); } } } static void GMark( AstPlot *this, int n, const float *x, const float *y, int type, const char *method, const char *class, int *status ) { /* * * Name: * GMark * Purpose: * Call the GMark Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GMark( AstPlot *this, int n, const float *x, * const float *y, int type, const char *method, * const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the GMark grf function to draw markers, either * calling the version registered using astGrfSet, or the version in the * linked grf module. The linked version is used if the Grf attribute * is zero, or if no function has been registered for GMark using * astGrfSet. * Parameters: * this * The Plot. * n * The number of positions to be joined together. * x * A pointer to an array holding the "n" x values. * y * A pointer to an array holding the "n" y values. * type * An integer which can be used to indicate the type of marker symbol * required. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int i; /* Loop count */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Do not draw anything if we are using "invisible ink". */ if( astGetInvisible( this ) ) { grf_status = 1; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ } else if( astGetGrf( this ) && this->grffun[ AST__GMARK ] ) { grf_status = ( *( this->GMark ) )( this, n, x, y, type, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGMark( n, x, y, type ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGMark. ", status, method, class ); /* Otherwise, update the box containing all drawn graphics primitives. */ } else if( !Boxp_freeze ){ for( i = 0; i < n; i++ ) { Boxp_lbnd[ 0 ] = astMIN( x[ i ], Boxp_lbnd[ 0 ] ); Boxp_ubnd[ 0 ] = astMAX( x[ i ], Boxp_ubnd[ 0 ] ); Boxp_lbnd[ 1 ] = astMIN( y[ i ], Boxp_lbnd[ 1 ] ); Boxp_ubnd[ 1 ] = astMAX( y[ i ], Boxp_ubnd[ 1 ] ); } } } static void GQch( AstPlot *this, float *chv, float *chh, const char *method, const char *class, int *status ) { /* * * Name: * GQch * Purpose: * Call the GQch Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GQch( AstPlot *this, float *chv, float *chh, const char *method, * const char *class, int *status ) * Class Membership: * Plot private function. * Description: * This function calls the GQch grf function, either calling the * version registered using astGrfSet, or the version in the linked grf * module. The linked version is used if the Grf attribute is zero, or if * no function has been registered for GQch using astGrfSet. * Parameters: * this * The Plot. * chv * A pointer to the double which is to receive the height of * characters drawn with a vertical baseline . This will be an * increment in the X axis. * chh * A pointer to the double which is to receive the height of * characters drawn with a horizontal baseline. This will be an * increment in the Y axis. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* if we already have the required values, return them. */ if( Grf_chh != AST__BAD && Grf_chv != AST__BAD ) { *chh = Grf_chh; *chv = Grf_chv; return; } /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GQCH ] ) { grf_status = ( *( this->GQch ) )( this, chv, chh, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGQch( chv, chh ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Check neither value is zero. */ if( grf_status && ( *chh == 0.0 || *chv == 0.0 ) ) { astError( AST__GRFER, "astGQch: Returned text heights are %g and %g " "but zero is illegal!", status, *chv, *chh ); grf_status = 0; } /* Report an error if anything went wrong, and return safe values. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGQch. ", status, method, class ); *chh = 1.0; *chv = 1.0; } /* Store them for future use. */ Grf_chh = *chh; Grf_chv = *chv; } static void GText( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy, const char *method, const char *class, int *status ) { /* * * Name: * GText * Purpose: * Call the GText Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GText( AstPlot *this, const char *text, float x, float y, * const char *just, float upx, float upy, * const char *method, const char *class, int *status ) { * Class Membership: * Plot private function. * Description: * This function calls the GText grf function to draw a text string, either * calling the version registered using astGrfSet, or the version in the * linked grf module. The linked version is used if the Grf attribute * is zero, or if no function has been registered for GText using * astGrfSet. * Parameters: * this * The Plot. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* Do not draw anything if we are using "invisible ink". */ if( astGetInvisible( this ) ) { grf_status = 1; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ } else if( astGetGrf( this ) && this->grffun[ AST__GTEXT ] ) { grf_status = ( *( this->GText ) )( this, text, x, y, just, upx, upy, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGText( text, x, y, just, upx, upy ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGText. ", status, method, class ); } } static void GTxExt( AstPlot *this, const char *text, float x, float y, const char *just, float upx, float upy, float *xbn, float *ybn, const char *method, const char *class, int *status ) { /* * * Name: * GTxExt * Purpose: * Call the GTxExt Grf function. * Type: * Private function. * Synopsis: * #include "plot.h" * void GTxExt( AstPlot *this, const char *text, float x, float y, * const char *just, float upx, float upy, float *xbn, * float *ybn, const char *method, const char *class, int *status ) * Class Membership: * Plot private function. * Description: * This function calls the GTxExt grf function to find the extent * of a text string, either calling the version registered using * astGrfSet, or the version in the linked grf module. The linked * version is used if the Grf attribute is zero, or if no function * has been registered for GTxExt using astGrfSet. * Parameters: * this * The Plot. * text * Pointer to a null-terminated character string to be displayed. * x * The reference x coordinate. * y * The reference y coordinate. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. * upy * The y component of the up-vector for the text, in graphics world * coordinates. If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * xbn * An array of 4 elements in which to return the x coordinate of * each corner of the bounding box. * ybn * An array of 4 elements in which to return the y coordinate of * each corner of the bounding box. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - The corners are returned in no particular order. */ /* Local Variables: */ int grf_status; /* Status retruned from Grf function */ /* Check the global error status. */ if ( !astOK ) return; /* Since we are about to call an external function which may not be thread safe, prevent any other thread from executing the following code until the current thread has finished executing it. */ LOCK_MUTEX2; /* If the Grf attribute is set to a non-zero value, use the Grf function registered using astGrfSet (so long as a function has been supplied). This is called via a wrapper which adapts the interface to suit the language in which the function is written. */ if( astGetGrf( this ) && this->grffun[ AST__GTXEXT ] ) { grf_status = ( *( this->GTxExt ) )( this, text, x, y, just, upx, upy, xbn, ybn, status ); /* Otherwise, use the function in the external Grf module, selected at link-time using ast_link options.*/ } else { grf_status = astGTxExt( text, x, y, just, upx, upy, xbn, ybn ); } /* Allow the next thread to proceed. */ UNLOCK_MUTEX2; /* Report an error if anything went wrong. */ if( !grf_status ) { astError( AST__GRFER, "%s(%s): Graphics error in astGTxExt. ", status, method, class ); } } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Plot. * Type: * Private function. * Synopsis: * #include "plot.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot member function (over-rides the protected astGetAttrib * method inherited from the FrameSet class). * Description: * This function returns a pointer to the value of a specified * attribute for a Plot, formatted as a character string. * * The value returned is the value which would actually be used if * astGrid was called with the current set of attribute values. This * may not always be the same as the value set by the user. For * instance, if Labelling is set to "exterior" by the user, it may not * be possible to produce exterior labels, in which case interior labels * will be produced. If this function is used to get the value of * Labelling in this situation, then the value actually used (i.e. * interior) will be returned instead of the requested value (i.e. * exterior). * * Some attributes have dynamic defaults, (i.e. the behaviour if not * set depends on the values of other attributes). If the value for * such an attribute is enquired using this function, then the dynamic * default value actually used will be returned if no value has been * set explicitly for the attribute. * Parameters: * this * Pointer to the Plot. * 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 Plot, 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 Plot. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPlot *this; /* Pointer to the Plot structure */ const char *result; /* Pointer value to return */ char label[21]; /* Graphics item label */ double dval; /* Double attribute value */ int axis; /* Axis number */ int ival; /* Int attribute value */ int len; /* Length of attrib string */ int nax; /* Number of base Frame axes */ int nc; /* No. characters read by astSscanf */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Get the number of base Frame axis (2 for a Plot, 3 for a Plot3D). */ nax = astGetNin( this ); /* Indicate that the current bound box should not be changed during the execution of this function (this may happen if a grid is drawn to get the default value for an attribute such as Labelling). */ Boxp_freeze = 1; /* 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. */ /* Tol. */ /* ---- */ if ( !strcmp( attrib, "tol" ) ) { dval = astGetTol( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Grid. */ /* ----- */ } else if ( !strcmp( attrib, "grid" ) ) { ival = GetUsedGrid( this, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* TickAll. */ /* -------- */ } else if ( !strcmp( attrib, "tickall" ) ) { ival = astGetTickAll( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ForceExterior. */ /* -------------- */ } else if ( !strcmp( attrib, "forceexterior" ) ) { ival = astGetForceExterior( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Invisible. */ /* ---------- */ } else if ( !strcmp( attrib, "invisible" ) ) { ival = astGetInvisible( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Border. */ /* ------- */ } else if ( !strcmp( attrib, "border" ) ) { ival = GetUsedBorder( this, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* ClipOp. */ /* ------- */ } else if ( !strcmp( attrib, "clipop" ) ) { ival = astGetClipOp( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Clip. */ /* ----- */ } else if ( !strcmp( attrib, "clip" ) ) { ival = astGetClip( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Grf. */ /* ---- */ } else if ( !strcmp( attrib, "grf" ) ) { ival = astGetGrf( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* DrawTitle. */ /* --------- */ } else if ( !strcmp( attrib, "drawtitle" ) ) { ival = astGetDrawTitle( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Escape. */ /* ------- */ } else if ( !strcmp( attrib, "escape" ) ) { ival = astGetEscape( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LabelAt(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelat(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = GetUsedLabelAt( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Centre(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "centre(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = GetUsedCentre( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Gap. */ /* ---- */ } else if ( !strcmp( attrib, "gap" ) ) { dval = GetUsedGap( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Gap(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "gap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = GetUsedGap( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* LogGap. */ /* ---- */ } else if ( !strcmp( attrib, "loggap" ) ) { dval = GetUsedLogGap( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* LogGap(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loggap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = GetUsedLogGap( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* NumLabGap. */ /* -------- */ } else if ( !strcmp( attrib, "numlabgap" ) ) { dval = astGetNumLabGap( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* NumLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetNumLabGap( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* TextLabGap. */ /* ----------- */ } else if ( !strcmp( attrib, "textlabgap" ) ) { dval = astGetTextLabGap( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* TextLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetTextLabGap( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* LabelUp. */ /* -------- */ } else if ( !strcmp( attrib, "labelup" ) ) { ival = astGetLabelUp( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LabelUp(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelup(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = astGetLabelUp( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogPlot. */ /* -------- */ } else if ( !strcmp( attrib, "logplot" ) ) { ival = astGetLogPlot( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogPlot(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logplot(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = astGetLogPlot( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogLabel. */ /* -------- */ } else if ( !strcmp( attrib, "loglabel" ) ) { ival = GetUsedLogLabel( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogLabel(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loglabel(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedLogLabel( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogTicks. */ /* -------- */ } else if ( !strcmp( attrib, "logticks" ) ) { ival = GetUsedLogTicks( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LogTicks(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logticks(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedLogTicks( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* NumLab. */ /* -------- */ } else if ( !strcmp( attrib, "numlab" ) ) { ival = astGetNumLab( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* NumLab(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = astGetNumLab( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* MinTick. */ /* -------- */ } else if ( !strcmp( attrib, "mintick" ) ) { ival = GetUsedMinTick( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* MinTick(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "mintick(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedMinTick( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* TextLab. */ /* ---------- */ } else if ( !strcmp( attrib, "textlab" ) ) { ival = GetUsedTextLab( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* TextLab(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedTextLab( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* DrawAxes. */ /* ----------- */ } else if ( !strcmp( attrib, "drawaxes" ) ) { ival = astGetDrawAxes( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* DrawAxes(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "drawaxes(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetDrawAxes( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Abbrev. */ /* ----------- */ } else if ( !strcmp( attrib, "abbrev" ) ) { ival = astGetAbbrev( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Abbrev(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "abbrev(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetAbbrev( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LabelUnits. */ /* ----------- */ } else if ( !strcmp( attrib, "labelunits" ) ) { ival = GetUsedLabelUnits( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LabelUnits(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelunits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedLabelUnits( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Style. */ /* ------ */ } else if ( !strcmp( attrib, "style" ) ) { ival = GetUseStyle( this, AST__BORDER_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Style(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "style(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { ival = GetUseStyle( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Font. */ /* ----- */ } else if ( !strcmp( attrib, "font" ) ) { ival = GetUseFont( this, AST__TEXTLABS_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Font(label). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "font(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { ival = GetUseFont( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Colour. */ /* ------- */ } else if ( !strcmp( attrib, "colour" ) ) { ival = GetUseColour( this, AST__TEXTLABS_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Colour(label). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "colour(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { ival = GetUseColour( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Color. */ /* ------ */ } else if ( !strcmp( attrib, "color" ) ) { ival = GetUseColour( this, AST__TEXTLABS_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Color(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "color(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { ival = GetUseColour( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* Width. */ /* ------ */ } else if ( !strcmp( attrib, "width" ) ) { dval = GetUseWidth( this, AST__BORDER_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Width(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "width(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { dval = GetUseWidth( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Size. */ /* ----- */ } else if ( !strcmp( attrib, "size" ) ) { dval = GetUseSize( this, AST__TEXTLABS_ID, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Size(label). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "size(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { dval = GetUseSize( this, FullForm( GrfLabels, label, attrib, "astGet", astGetClass( this ), status ), status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* TitleGap. */ /* --------- */ } else if ( !strcmp( attrib, "titlegap" ) ) { dval = astGetTitleGap( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* MajTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "majticklen" ) ) { dval = GetUsedMajTickLen( this, 0, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* MajTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "majticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = GetUsedMajTickLen( this, axis - 1, status ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* MinTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "minticklen" ) ) { dval = astGetMinTickLen( this, 0 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* MinTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "minticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetMinTickLen( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Labelling. */ /* ---------- */ } else if ( !strcmp( attrib, "labelling" ) ) { ival = GetUsedLabelling( this, status ); if ( astOK ) { result = ival ? xlbling[1] : xlbling[0]; } /* Edge(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "edge(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = GetUsedEdge( this, axis - 1, status ); if ( astOK ) { if( ival == LEFT ){ result = "left"; } else if( ival == RIGHT ){ result = "right"; } else if( ival == TOP ){ result = "top"; } else if( ival == BOTTOM ){ result = "bottom"; } else { result = ""; } } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Unfreeze the bound box so that it may be updated by subsequent plotting functions. */ Boxp_freeze = 0; /* Return the result. */ return result; } static AstPointSet *GetDrawnTicks( AstPlot *this, int axis, int major, int *status ){ /* *+ * Name: * astGetDrawnTicks * Purpose: * Return information about the ticks last drawn by astGrid. * Type: * Protected virtual function. * Synopsis: * #include "plot.h" * AstPointSet *GetDrawnTicks( AstPlot *this, int axis, int major ) * Class Membership: * Plot method. * Description: * This function returns a PointSet holding information about the * tick marks (either major and minor) that were drawn by the previous * invocation of astGrid. A NULL pointer is returned if astGrid has * not yet been invoked. * Parameters: * this * Pointer to a Plot. * axis * The zero-based axis of the axis for which tick mark information * is required. * major * Supply a non-zero value if information about the major tick * marks is to be returned, and zero if information about the minor * tick marks is to be returned. * Returned Value: * A pointSet with one point for every tick of the requested type drawn * by astGrid for the specified axis. Each point has 2 coordinate values, * being the graphics coordinates at the start of the tick mark. The * returned PointSet pointer should be annulled when no longer needed. *- */ /* Local Variables: */ AstPointSet *result = NULL; double *ptr[ 3 ]; int n; /* Check the global status. */ if( !astOK ) return result; /* Report an error if the supplied axis value is incorrect. */ if( axis < 0 || axis > 1 ) { astError( AST__INTER, "astGetDrawnTicks(Plot): Supplied \"axis\" " "value is %d - should 0 or 1 (internal AST programming " "error).", status, axis ); n = 0; /* If OK, get the number of stored tick marks. */ } else { n = major ? this->majtickcount[ axis ] : this->mintickcount[ axis ]; } /* Check that information is available. */ if( n > 0 && astOK ) { /* Create a PointSet with the required size. */ result = astPointSet( n, 2, "", status ); /* Store pointers to the arrays within the Plot that hold the required tick marks positions and types. */ ptr[ 0 ] = major ? this->majtickgx[ axis ] : this->mintickgx[ axis ]; ptr[ 1 ] = major ? this->majtickgy[ axis ] : this->mintickgy[ axis ]; astSetPoints( result, ptr ); } /* Return the PointSet. */ return result; } static double GetTicks( AstPlot *this, int axis, double *cen, double **ticks, int *nmajor, double **minticks, int *nminor, int format_set, int *inval, double *refval, GetTicksStatics **pstatics, const char *method, const char *class, int *status ){ /* * Name: * GetTicks * Purpose: * Obtain a list of logarithmically or linearly spaced tick mark values for * a single axis in a 2-D physical coordinate Frame. * Type: * Private function. * Synopsis: * #include "plot.h" * double GetTicks( AstPlot *this, int axis, double *cen, double **ticks, * int *nmajor, double **minticks, int *nminor, * int format_set, int *inval, double *refval, * GetTicksStatics **pstatics, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * For linearly spaced major ticks the "gap" returned by this function * is the constant difference between adjacent major tick marks. For * logarithmically spaced major ticks the "gap" returned by this * function is the constant ratio between adjacent major tick marks. * * If a gap size has been specified using attribute Gap (or LogGap for * logarithmic ticks) supplied, the specified value is returned, and used * to determine the tick values. If no gap size is supplied, a default * gap size is used and returned. * * All this is over-ridden if the astSetTickValues method has been * called to store explicit tick mark values in the Plot structure. * In this case, the values supplied using astSetTickValues are * returned. * Parameters: * this * The Plot. Supplying a NULL pointer will cause statics resources * to be released. * axis * The zero-based index of the axis to use. * cen * Pointer to the supplied axis value at which to put a single * central tick. Other ticks will be placed evenly on either side * of this tick. If AST__BAD is provided, a value will be used * which would put a tick at an axis value of one. The used value * is returned. * ticks * Pointer to a place at which to return a pointer to the memory in * which are stored the major tick values to be used. This pointer * should be freed using astFree when no longer needed. The number of * values in the array is given by the value returned by parameter * "nmajor". * nmajor * A pointer to a location at which to return the number of major * ticks. * minticks * Pointer to a place at which to return a pointer to the memory in * which are stored the minor tick values to be used. This pointer * should be freed using astFree when no longer needed. The number of * values in the array is given by the value returned by parameter * "nminor". The minor tick marks values returned in this array are * the ones stored in the Plot via a call to the astSetTickValues * function. If this function has not been called, then a NULL * pointer is returned, and the "nminor" value is returned holding the * number of divisions between major ticks. * nminor * A pointer to a location at which to return either the number of * division into which each gap should be divided when drawing minor * tick marks (if "*minticks" is returned holding NULL), or the * total number of minor tick values stored in "*minticks" (if * "*minticks" is returned non-NULL). The number of divisions * between major tick values is one more than the number of minor * tick marks. * format_set * Indicates if an explicit format has been set for the axis. If * not, "cen" is always assumed to be AST__BAD, and any specified * Gap value is rounded to the nearest "nice" value. This has * to be done because the algorithm for choosing a format avoiding * unnecessary precision only works if the gap size causes 1 digit to * change between adjacent labels. * inval * A pointer to a location at which to return a flag indicating if * any invalid physical coordinates were encountered. * refval * A pointer to a location at which to return a value for the other * axis which can be used when normalizing the returned tick mark * values. * pstatics * Address of a pointer to a structure holding static data values * used within this function. A NULL pointer should be supplied on * the first invocation (dynamic memory will then be allocated to * hold ths structure). The memory is freed when a NULL value for * "this" is supplied. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The used gap size. * Notes: * - This function allocates some static resources on its first * invocation, which should be released when no longer needed, or when * a different Plot is supplied, by calling this function with a NULL * pointer for parameter "this". All other parameters are ignored. * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - An error is reported if the region containing valid physical * coordinates is too small to use. * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned in "ticks", zero * is returned for the number of major and minor ticks marks. */ /* Local Variables: */ GetTicksStatics *statics; /* Pointer to statics structure */ double *tick; /* Pointer to next tick value */ double cen0; /* Supplied value of cen */ double dran; /* Dynamic range of axis values */ double frac; /* Fraction of plot area holding good coords */ double gap; /* Supplied value for Gap or LogGap */ double log_used_gap; /* Log10( the used gap size ) */ double maxv; /* Max axis value */ double minv; /* Min axis value */ double new_used_gap; /* New value for the used gap size */ double old_used_gap; /* Old value for the used gap size */ double test_gap; /* Trial gap size */ double used_cen; /* Used value of cen */ double used_gap; /* The used gap size */ int findcen; /* Find a new centre value? */ int gap_too_small; /* Test gap too small? */ int gap_too_large; /* Test gap too large? */ int i; /* Axis index */ int ihi; /* Highest tick mark index */ int ilo; /* Lowest tick mark index */ int nochange; /* No. of ineffective attempts to change gap size */ /* Initialise the returned information. */ *ticks = NULL; *minticks = NULL; *nmajor = 0; *nminor = 0; /* Get a pointer to the supplied statics object. */ statics = *pstatics; /* If a NULL pointer has been supplied for "this", release the resources allocated on the first call to this function, and return. */ if( !this ){ if( statics ) { if( statics->map ) statics->map = astAnnul( statics->map ); if( statics->pset ) statics->pset = astAnnul( statics->pset ); if( statics->frame ) statics->frame = astAnnul( statics->frame ); *pstatics = astFree( statics ); } return 0.0; } /* Check the global error status. */ if ( !astOK ) return 0.0; /* If no statics structure was supplied, create one now and initialise it. */ if( !statics ) { statics = astMalloc( sizeof( GetTicksStatics ) ); if( statics ) { statics->pset=NULL; *pstatics = statics; } } /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ maxv = 0.0; minv = 0.0; used_cen = 0.0; used_gap = 0.0; ihi = 0; ilo = 0; /* If this is the first call to this function, do some initialisation. */ if( !statics->pset ){ /* Get the Mapping from Base to Current Frame in the Plot. */ statics->map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Get a pointer to the current Frame from the Plot. */ statics->frame = astGetFrame( this, AST__CURRENT ); /* Get initial guesses at suitable gaps for each axis. A PointSet is returned holding sorted values (non-normalized) for the physical axes. */ statics->pset = DefGap( this, statics->defgaps, statics->ngood, &frac, &statics->bad, method, class, status ); /* Store the maximum and minimum number of major tick marks along each axis. These numbers are reduced if only a small part of the plotting area contains valid coordinates, so that the tick marks do not end up to close together. */ statics->maxticks = (int) ( 0.5 + MAJTICKS_MAX*sqrt( frac ) ); statics->mintick = (int) ( 0.5 + MAJTICKS_MIN*sqrt( frac ) ); if( statics->mintick < 3 ) statics->mintick = 3; if( statics->maxticks < 8 ) statics->maxticks = 8; if( statics->maxticks < statics->mintick ) statics->maxticks = statics->mintick; /* Get a pointer to the data in the PointSet. */ statics->ptr = astGetPoints( statics->pset ); /* Find a typical value on each axis. */ for( i = 0; i < 2 && astOK; i++ ){ statics->typval[ i ] = Typical( statics->ngood[ i ], statics->ptr[ i ], -DBL_MAX, DBL_MAX, statics->width + i, status ); } } /* Return the flag indicating if any regions of invalid physical coordinates were found. */ *inval = statics->bad; /* Return the typical value on the other axis. */ *refval = statics->typval[ 1 - axis ]; /* See if any tick marks values have been stored in the Plot structure using astSetTickValues. If so, copy the tick mark values to the returned arrays and exit with a gap size determined by the first two ticks. */ if( this->nmajtickval[ axis ] > 0 ) { *ticks = astStore( NULL, this->majtickval[ axis ], this->nmajtickval[ axis ]*sizeof(double) ); *minticks = astStore( NULL, this->mintickval[ axis ], this->nmintickval[ axis ]*sizeof(double) ); *nmajor = this->nmajtickval[ axis ]; *nminor = this->nmintickval[ axis ]; if( *nmajor > 1 && (*ticks)[ 0 ] != AST__BAD && (*ticks)[ 1 ] != AST__BAD ) { used_gap = fabs( (*ticks)[ 1 ] - (*ticks)[ 0 ] ); } else { used_gap = AST__BAD; } return used_gap; } /* See if the user has specified a gap size. The default for astGetLogTicks is determined in DefGaps, so we can now decide whether to use attribute Gap or LogGap to get the user-supplied gap size. Obtain the requested gap attribute values for both physical axes. */ if( astGetLogTicks( this, axis ) ) { gap = astGetLogGap( this, axis ); } else { gap = astGetGap( this, axis ); } /* Find the maximum and minimum value in the plotting area. DefGap will have reported an error if minv*maxv is negative or zero. */ if( astOK ) { maxv = statics->ptr[ axis ][ statics->ngood[ axis ] - 1 ]; minv = statics->ptr[ axis ][ 0 ]; } /* First deal with logarithmically spaced ticks. */ dran = ( minv != 0.0 ) ? maxv/minv : 0.0; if( astGetLogTicks( this, axis ) ) { /* If the ratio of max and min data value is not larger than 10, report an error. */ dran = ( minv != 0.0 ) ? maxv/minv :0.0; if( dran < 10.0 && dran > 0.1 ) { astError( AST__VSMAL, "%s(%s): Cannot produce logarithmically " "spaced major tick marks on axis %d since the dynamic " "range of the axis is too small.", status, method, class, axis + 1 ); } /* Should we find a new value for "cen"? */ findcen = !cen || *cen == AST__BAD || !format_set; /* Try to find a "nice" gap size, so long as the caller has not supplied a gap size. The default gap size obtained above is our initial guess. */ if( gap == AST__BAD && astOK ){ /* Start off using the default gap found during the initialisation. */ test_gap = statics->defgaps[ axis ]; /* Loop round until a gap size is found which gives an acceptable number of tick marks. Upto 10 gap sizes are tried. */ for( i = 0; i < 10 && astOK; i++ ){ /* Find a "nice" gap size close to the current test gap size. Also find the number of minor tick marks to use with the nice gap size. Gaps for logarithmic axes are always powers of ten. */ log_used_gap = (int) ( log10( test_gap ) + 0.5 ); if( log_used_gap == 0.0 ) { log_used_gap = ( test_gap > 1.0 ) ? 1.0 : -1.0; } *nminor = 9; used_gap = pow( 10.0, log_used_gap ); /* If no value has been supplied for *cen, choose a value which would put a major tick mark at the value 1 (or -1), and which is mid way between the maximum and minimum axis value. */ if( findcen ) { used_cen = pow( used_gap, (int) ( 0.5*log10( maxv*minv ) / log_used_gap ) ); if( maxv < 0 ) used_cen = -used_cen; } else { used_cen = *cen; } /* Find the index of the highest tick which is not larger than the lowest axis value. */ if( log_used_gap > 0.0 ) { ilo = floor( log10( minv/used_cen )/log_used_gap ); } else { ilo = ceil( log10( minv/used_cen )/log_used_gap ); } /* Find the index of the lowest tick which is not less than the highest axis value. */ if( log_used_gap > 0.0 ) { ihi = ceil( log10( maxv/used_cen )/log_used_gap ); } else { ihi = floor( log10( maxv/used_cen )/log_used_gap ); } /* Find the total number of tick marks. */ *nmajor = ihi - ilo + 1; /* If the number of ticks is unacceptable, try a different gap size. If the gap was too large to produce any ticks, try using half the gap size. */ if( *nmajor <= 0 ) { test_gap = sqrt( test_gap ); /* If there were some ticks, but not enough, decrease the gap size in proportion to the shortfall. */ } else if( *nmajor < statics->mintick ){ test_gap = pow( test_gap, (double)( *nmajor )/(double)( statics->mintick ) ); /* If there were too many ticks, increase the gap size in proportion to the excess. */ } else if( *nmajor > statics->maxticks ){ test_gap = pow( test_gap, (double)( *nmajor )/(double)( statics->maxticks ) ); /* If the number of ticks is acceptable, break out of the loop early.*/ } else { break; } } /* Increase the tick coverage by one at each end to cover up the gaps. */ ilo--; ihi++; *nmajor += 2; /* If an explicit gap size was supplied, use it. */ } else if( astOK ) { /* Check it is usable. */ if( gap == 0.0 && astOK ) { astError( AST__ATTIN, "%s(%s): Invalid value zero given for " "attribute LogGap(%d).", status, method, class, axis + 1 ); } else if( gap < 0.0 && astOK ) { astError( AST__ATTIN, "%s(%s): Invalid negative value %f given for " "attribute LogGap(%d).", status, method, class, gap, axis + 1 ); /* If necessary, take its reciprocal in order to ensure that the absolute tick mark values get smaller or larger as required. */ } else { used_gap = gap; if( fabs( maxv ) < fabs( minv ) ) { if( gap > 1.0 ) used_gap = 1.0/gap; } else { if( gap < 1.0 ) used_gap = 1.0/gap; } /* Find the nearest power of 10 ( do not allow 10**0 (=1.0) to be used). */ log_used_gap = (int) ( log10( used_gap ) + 0.5 ); if( log_used_gap == 0.0 ) { log_used_gap = ( gap > 1.0 ) ? 1.0 : -1.0; } used_gap = pow( 10.0, log_used_gap ); /* We always use 9 minor intervals. */ *nminor = 9; /* If no value has been supplied for *cen, choose a value which would put a major tick mark at the value 1 (or -1), and which is mid way between the maximum and minimum axis value. */ if( findcen ) { used_cen = pow( used_gap, (int) ( 0.5*log10( maxv*minv ) / log_used_gap ) ); if( maxv < 0 ) used_cen = -used_cen; } else { used_cen = *cen; } /* Find the index of the highest tick which is not larger than the lowest axis value. */ if( log_used_gap > 0.0 ) { ilo = floor( log10( minv/used_cen )/log_used_gap ); } else { ilo = ceil( log10( minv/used_cen )/log_used_gap ); } /* Find the index of the lowest tick which is not less than the highest axis value. */ if( log_used_gap > 0.0 ) { ihi = ceil( log10( maxv/used_cen )/log_used_gap ); } else { ihi = floor( log10( maxv/used_cen )/log_used_gap ); } /* Find the total number of tick marks. */ *nmajor = ihi - ilo + 1; if( *nmajor < 2 && astOK ) { astError( AST__ATTIN, "%s(%s): Unusable value %f given for " "attribute LogGap(%d).", status, method, class, gap, axis + 1 ); } } } /* Allocate memory to hold the tick values themselves. */ *ticks = (double *) astMalloc( sizeof( double )*( *nmajor ) ); if( astOK ) { /* Store them. */ tick = *ticks; for( i = ilo; i <= ihi; i++, tick++ ) { *tick = used_cen*pow( used_gap, i ); } } /* Store returned centre value. */ if( cen ) *cen = used_cen; /* Now deal with linearly spaced ticks */ } else { /* Store the supplied value of cen. */ cen0 = ( cen ) ? *cen : AST__BAD; /* If no format has been set for the axis, ensure AST__BAD is used for cen. */ if( !format_set ) cen0 = AST__BAD; /* Try to find a "nice" gap size, so long as the caller has not supplied a gap size. The default gap size obtained above is our initial guess. */ if( gap == AST__BAD ){ old_used_gap = AST__BAD; /* Start of using the default gap found during the initialisation. */ test_gap = statics->defgaps[ axis ]; used_gap = 0.0; /* Initialise flags saying the test gap is too large or too small */ gap_too_large = 0; gap_too_small = 0; /* So far, there have been no ineffective attempts to change the gap size. */ nochange = 0; /* Loop round until a gap size is found which gives an acceptable number of tick marks. Upto 10 gap sizes are tried. */ for( i = 0; i < 10 && astOK; i++ ){ /* Find a "nice" gap size close to the current test gap size. Also find the number of minor tick marks to use with the nice gap size. */ new_used_gap = astGap( statics->frame, axis, test_gap, nminor ); /* Find the number and positions of major tick marks which would result from using this gap size. Annul the memory used to hold any previous tick data first. Only do this if the gap being used has actually changed, otherwise we just retain the values created from the previous run with this gap size. */ if( new_used_gap != used_gap ) { nochange = 0; old_used_gap = used_gap; used_gap = new_used_gap; if( *ticks ) *ticks = astFree( *ticks ); if( cen ) *cen = cen0; *nmajor = FindMajTicks( statics->map, statics->frame, axis, *refval, statics->width[ 1-axis ], used_gap, cen, statics->ngood[ axis ], statics->ptr[ axis ], ticks, status ); /* If the gap size has not changed do an extra pass through this loop, but only do this a maximum of 25 times in succession. */ } else if( nochange < 25 ) { nochange++; i--; } else if( astOK ){ astError( AST__VSMAL, "%s(%s): Cannot produce enough major " "tick marks on axis %d using the current axis " "format (\"%s\").", status, method, class, axis + 1, astGetFormat( statics->frame, axis ) ); break; } /* If the number of ticks is unacceptable, try a different gap size. If the gap was too large to produce any ticks, try using half the gap size. */ if( *nmajor == 0 ) { test_gap *= 0.5; gap_too_large = 1; gap_too_small = 0; /* If there were some ticks, but not enough... */ } else if( *nmajor < statics->mintick ){ /* If the previous test gap produced too many ticks, use the current gap size. */ if( gap_too_small ) { break; /* Otherwise, decrease the gap size in proportion to the shortfall. */ } else { test_gap *= (double)( *nmajor )/(double)( statics->mintick ); gap_too_large = 1; gap_too_small = 0; } /* If there were too many ticks... */ } else if( *nmajor > statics->maxticks ){ /* If the previous test gap produced too few ticks, use the previous gap size. */ if( gap_too_large ) { used_gap = old_used_gap; if( *ticks ) *ticks = astFree( *ticks ); if( cen ) *cen = cen0; *nmajor = FindMajTicks( statics->map, statics->frame, axis, *refval, statics->width[ 1-axis ], used_gap, cen, statics->ngood[ axis ], statics->ptr[ axis ], ticks, status ); break; /* Otherwise, increase the gap size in proportion to the excess. */ } else { test_gap *= (double)( *nmajor )/(double)( statics->maxticks ); gap_too_small = 1; gap_too_large = 0; } /* If the number of ticks is acceptable, break out of the loop early.*/ } else { break; } } /* If an explicit gap size was supplied, use it. */ } else { /* Find a likely value for the number of minor tick marks to use, and find a nice gap close to the supplied gap (unless an explicit format has been set). */ if( format_set ){ used_gap = gap; (void) astGap( statics->frame, axis, used_gap, nminor ); } else { used_gap = astGap( statics->frame, axis, gap, nminor ); } /* Find where the major ticks should be put. */ if( cen ) *cen = cen0; *nmajor = FindMajTicks( statics->map, statics->frame, axis, *refval, statics->width[ 1-axis ], used_gap, cen, statics->ngood[ axis ], statics->ptr[ axis ], ticks, status ); } } /* Report an error if no ticks can be found. */ if( *nmajor == 0 && astOK ) { astError( AST__GRFER, "%s(%s): Cannot find any usable tick mark values. ", status, method, class ); } /* If an error has occurred, annul the memory used to hold tick data, and return zero ticks. */ if( !astOK ) { *ticks = (double *) astFree( (void *) *ticks ); *nmajor = 0; *nminor = 0; used_gap = 0.0; } /* Return. */ return used_gap; } static double GoodGrid( AstPlot *this, int *dim, AstPointSet **pset1, AstPointSet **pset2, const char *method, const char *class, int *status ){ /* * Name: * GoodGrid * Purpose: * Create a grid covering the region containing good coordinates in a * 2-D physical coordinate Frame. * Type: * Private function. * Synopsis: * #include "plot.h" * double GoodGrid( AstPlot *this, int *dim, AstPointSet **pset1, * AstPointSet **pset2, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function creates two PointSets, one holding a square grid of * graphics coordinates, and the other holding the corresponding physical * coordinates (not normalized). The grid covers just the area containing * good physical coordinates. The points are stored row by row in the * returned PointSets. * Parameters: * this * The Plot. * dim * A pointer to an integer in which to store the number of samples * along each edge of the returned grid. * pset1 * A pointer to a location at which to store a pointer to the * PointSet holding the graphics coordinates. * pset2 * A pointer to a location at which to store a pointer to the * PointSet holding the physical coordinates. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * The fraction of the plotting area containing good physical * coordinates. * Notes: * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - The returned PointSets should be annulled when no longer needed, * using astAnnul. * - An error is reported if the region containing valid physical * coordinates is too small to use. * - A function value of zero, and NULL pointers are returned if an error * has already occurred, or if this function should fail for any reason. */ /* Local Variables: */ AstFrame *frm; /* Pointer to the Current Frame in the Plot */ AstMapping *map; /* Pointer to "graphics to physical" mapping */ double **ptr1; /* Pointer to physical axis value data */ double **ptr2; /* Pointer to graphics axis value data */ double *pa; /* Pointer to next value on 1st physical axis */ double *pb; /* Pointer to next value on 2nd physical axis */ double *px; /* Pointer to next value on 1st graphics axis */ double *py; /* Pointer to next value on 2nd graphics axis */ double dx; /* Cell size along graphics X (1st) axis */ double dy; /* Cell size along graphics Y (2nd) axis */ double frac; /* Fraction of good physical coordinates */ double xmax; /* High X bound of region containing good phy. coords */ double xmin; /* Low X bound of region containing good phy. coords */ double ymax; /* High Y bound of region containing good phy. coords */ double ymin; /* Low Y bound of region containing good phy. coords */ int j; /* Element offset */ int ngood; /* Number of grid points with good physical coords */ int size; /* Number of grid points */ /* Initialise the returned PointSet pointers. */ *pset1 = NULL; *pset2 = NULL; /* Check the global error status. */ if ( !astOK ) return 0.0; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ ptr1 = NULL; frac = 0.0; xmax = 0.0; xmin = 0.0; ymax = 0.0; ymin = 0.0; /* Get the Mapping from base (graphics) to current (physical) Frame in the supplied Plot. */ map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Get a pointer to the Current Frame in the Plot. */ frm = astGetFrame( this, AST__CURRENT ); /* Initialise the grid dimension. */ *dim = 16; /* We need a grid which has at least 4 good points. */ ngood = 0; while( ngood < 4 && astOK ){ /* Double the grid dimension. */ *dim *= 2; /* Report an error if the grid is now too big. */ if( *dim >= 512 ){ astError( AST__VSMAL, "%s(%s): The area of the plot containing " "usable coordinates on both axes is too small.", status, method, class ); break; } /* Get two PointSets, one holding a regular grid of graphics coordinates, and the other holding the corresponding physical coordinates. The grid covers the entire plotting area with the current grid dimension. A pointer to the physical axis values is returned. */ ptr2 = MakeGrid( this, frm, map, 1, *dim, this->xlo, this->xhi, this->ylo, this->yhi, 2, pset1, pset2, 0, method, class, status ); /* Get the number of graphics axis values. */ size = astGetNpoint( *pset1 ); /* Get a pointer to the graphics axis values. */ ptr1 = astGetPoints( *pset1 ); /* Check the pointers can be used. */ if( astOK ){ /* Find the bounds in graphics coordinates of the area enclosing the good physical positions in the grid, and count the good positions. */ ngood = 0; pa = ptr2[ 0 ]; pb = ptr2[ 1 ]; px = ptr1[ 0 ]; py = ptr1[ 1 ]; xmin = DBL_MAX; xmax = -DBL_MAX; ymin = DBL_MAX; ymax = -DBL_MAX; for( j = 0; j < size; j++ ){ if( *pa != AST__BAD && *pb != AST__BAD ){ if( *px < xmin ) xmin = *px; if( *px > xmax ) xmax = *px; if( *py < ymin ) ymin = *py; if( *py > ymax ) ymax = *py; ngood++; } px++; py++; pa++; pb++; } } } /* Store approximate fraction of the plotting area containing good physical coordinates. */ if( astOK ) { frac = ( (double) ngood )/(double)( astGetNpoint( *pset1 ) ); /* Get the size of each grid cell. */ dx = ptr1[0][1] - ptr1[0][0]; dy = ptr1[1][1] - ptr1[1][0]; /* Extend the area containing good points by one grid cell. */ xmax += dx; xmin -= dx; ymax += dy; ymin -= dy; /* If the area containing good points is significantly smaller than the supplied area, create a new grid covering just the area containing good positions. */ if( ( xmax - xmin ) < 0.9*( this->xhi - this->xlo ) || ( ymax - ymin ) < 0.9*( this->yhi - this->ylo ) ){ /* Find a new grid dimension which results in a cell size similar to the one used to create the grid, but covering only the region containing good physical coordinates. */ *dim *= astMAX( (xmax - xmin)/(this->xhi - this->xlo), (ymax - ymin)/(this->yhi - this->ylo) ); if( *dim < 32 ) *dim = 32; /* Annul the PointSet holding the current grid. */ *pset1 = astAnnul( *pset1 ); *pset2 = astAnnul( *pset2 ); /* Create the new grid covering the region containing good physical coordinates. */ (void) MakeGrid( this, frm, map, 1, *dim, xmin, xmax, ymin, ymax, 2, pset1, pset2, 0, method, class, status ); } } /* Annul the Mapping from base to current Frame, and the pointer to the Current Frame. */ map = astAnnul( map ); frm = astAnnul( frm ); /* If an error has occurred, annul the two pointsets and indicate that there are no good points in the plotting area. */ if( !astOK ){ *pset1 = astAnnul( *pset1 ); *pset2 = astAnnul( *pset2 ); frac = 0.0; } /* Return. */ return frac; } static int GraphGrid( int dim, int disk, double xlo, double xhi, double ylo, double yhi, double **ptr1, int *status ){ /* * Name: * GraphGrid * Purpose: * Fill an array with a square grid of graphics coordinates. * Type: * Private function. * Synopsis: * #include "plot.h" * int GraphGrid( int dim, int disk, double xlo, double xhi, double ylo, * double yhi, double **ptr1, int *status ) * Class Membership: * Plot member function. * Description: * This function fills the supplied array with a square grid of graphics * coordinates covering the supplied area. The points are stored row by * row, i.e. if the cell size for the grid is (dx,dy), the first point * is (xmin,ymin), followed by (xmin+dx,ymin), (xmin+2*dx,ymin), up to * (xmin+(dim-1)*dx,ymin), followed by the next row (xmin,ymin+dy), * (xmin+dx,ymin+dy), etc. * Parameters: * dim * The number of samples along each edge of the grid. * disk * If non-zero, the corners of the grid are omitted, resulting in a * grid that is more disk like than rectangular. * xlo * The lower bound on the first axis of the region to be covered * by the grid. * xhi * The upper bound on the first axis of the region to be covered * by the grid. * ylo * The lower bound on the second axis of the region to be covered * by the grid. * yhi * The upper bound on the second axis of the region to be covered * by the grid. * ptr1 * A pointer to an array of two pointers giving the start of the two * arrays to receive the values for each of the two axes of the graphics * coordinate data. * status * Pointer to the inherited status variable. * Returned Value: * The number of points in the grid. If "disk" is zero, this will be * the square of "dim". If "disk" is non-zero, this will be less than * the square of "dim" to account for the lack of corner points. */ /* Local Variables: */ double *px; double *py; double cen; double dx; double dy2; double dy; double dx2; double r2; double y; int i; int j; int ok; /* Check the global error status. */ if ( !astOK ) return 0; /* Find the cell size. */ dx = ( xhi - xlo )/(double)( dim - 1 ); dy = ( yhi - ylo )/(double)( dim - 1 ); /* Store the mid cell index. */ cen = 0.5*( dim - 1 ); /* Store the squared radius of the disk. */ r2 = 1.9*cen*cen; /* Initialise pointers to the start of the two arrays to recieve the returned graphics values for each axis. */ px = ptr1[ 0 ]; py = ptr1[ 1 ]; /* Loop round row. */ for( j = 0; j < dim; j++ ){ dy2 = j - cen; dy2 *= dy2; /* Get the Y coordinate of the current row. */ y = ylo + j*dy; /* Loop round each column in the current row. */ for( i = 0; i < dim; i++ ){ /* If we are forming a disk rather than a square, check if this point is sufficiently close to the centre to be included in the disk. */ if( disk ) { dx2 = i - cen; dx2 *= dx2; ok = ( dx2 + dy2 <= r2 ); } else { ok = 1; } /* Store the coordinates of the current grid point. */ if( ok ) { *(px++) = xlo + i*dx; *(py++) = y; } } } /* Return the used length of the PointSet. */ return (int)( px - ptr1[ 0 ] ); } static void GrfPop( AstPlot *this, int *status ) { /* *++ * Name: c astGrfPop f AST_GRFPOP * Purpose: * Restore previously saved graphics functions used by a Plot. * Type: * Public function. * Synopsis: c #include "plot.h" c void astGrfPop( AstPlot *this ) f CALL AST_GRFPOP( THIS STATUS ) * Class Membership: * Plot member function. * Description: c This function restores a snapshot of the graphics functions c stored previously by calling astGrfPush. The restored graphics c functions become the current graphics functions used by the Plot. * c The astGrfPush and astGrfPop functions are intended for situations c where it is necessary to make temporary changes to the graphics c functions used by the Plot. The current functions should first be c saved by calling astGrfPush. New functions should then be registered c using astGrfSet. The required graphics should then be produced. c Finally, astGrfPop should be called to restore the original graphics c functions. f The AST_GRFPUSH and AST_GRFPOP functions are intended for situations f where it is necessary to make temporary changes to the graphics f functions used by the Plot. The current functions should first be f saved by calling AST_GRFPUSH. New functions should then be registered f using AST_GRFSET. The required graphics should then be produced. f Finally, AST_GRFPOP should be called to restore the original graphics f functions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: f - This routine returns without action if there are no snapshots to c - This function returns without action if there are no snapshots to * restore. No error is reported in this case. *-- */ /* Local Variables: */ AstGrfPtrs *newframe; /* Pointer to the stack frame to restore */ int i; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Check the stack is not already empty. */ if( this->grfnstack > 0 ) { this->grfnstack--; if( astOK ) { newframe = this->grfstack + this->grfnstack; for( i = 0; i < AST__NGRFFUN; i++ ) { this->grffun[i] = (newframe->grffun)[i]; } this->GAttr = newframe->GAttr; this->GBBuf = newframe->GBBuf; this->GEBuf = newframe->GEBuf; this->GFlush = newframe->GFlush; this->GLine = newframe->GLine; this->GMark = newframe->GMark; this->GText = newframe->GText; this->GCap = newframe->GCap; this->GTxExt = newframe->GTxExt; this->GScales = newframe->GScales; this->GQch = newframe->GQch; } } } static void GrfPush( AstPlot *this, int *status ) { /* *++ * Name: c astGrfPush f AST_GRFPUSH * Purpose: * Save the current graphics functions used by a Plot. * Type: * Public function. * Synopsis: c #include "plot.h" c void astGrfPush( AstPlot *this ) f CALL AST_GRFPUSH( THIS STATUS ) * Class Membership: * Plot member function. * Description: c This function takes a snapshot of the graphics functions which are f This routine takes a snapshot of the graphics functions which are * currently registered with the supplied Plot, and saves the snapshot * on a first-in-last-out stack within the Plot. The snapshot can be * restored later using function c astGrfPop. f AST_GRFPOP. * c The astGrfPush and astGrfPop functions are intended for situations c where it is necessary to make temporary changes to the graphics c functions used by the Plot. The current functions should first be c saved by calling astGrfPush. New functions should then be registered c using astGrfSet. The required graphics should then be produced. c Finally, astGrfPop should be called to restore the original graphics c functions. f The AST_GRFPUSH and AST_GRFPOP functions are intended for situations f where it is necessary to make temporary changes to the graphics f functions used by the Plot. The current functions should first be f saved by calling AST_GRFPUSH. New functions should then be registered f using AST_GRFSET. The required graphics should then be produced. f Finally, AST_GRFPOP should be called to restore the original graphics f functions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstGrfPtrs *newframe; /* Pointer to the new stack frame */ int i; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Increment the number of frames on the stack. */ this->grfnstack++; /* Ensure the stack is large enough to hold this many frames. */ this->grfstack = (AstGrfPtrs *) astGrow( (void *) this->grfstack, this->grfnstack, sizeof( AstGrfPtrs ) ); if( astOK ) { /* Get a pointer to the new stack frame. */ newframe = this->grfstack + this->grfnstack - 1; /* Copy the graphics function pointers from the main Plot attributes to the new stack frame. */ for( i = 0; i < AST__NGRFFUN; i++ ) { (newframe->grffun)[i] = this->grffun[i]; } newframe->GAttr = this->GAttr; newframe->GBBuf = this->GBBuf; newframe->GEBuf = this->GEBuf; newframe->GFlush = this->GFlush; newframe->GLine = this->GLine; newframe->GMark = this->GMark; newframe->GText = this->GText; newframe->GCap = this->GCap; newframe->GTxExt = this->GTxExt; newframe->GQch = this->GQch; newframe->GScales = this->GScales; } } static void GrfSet( AstPlot *this, const char *name, AstGrfFun fun, int *status ){ /* *++ * Name: c astGrfSet f AST_GRFSET * Purpose: c Register a graphics function for use by a Plot. f Register a graphics routine for use by a Plot. * Type: * Public function. * Synopsis: c #include "plot.h" c void astGrfSet( AstPlot *this, const char *name, AstGrfFun fun ) f CALL AST_GRFSET( THIS, NAME, FUN, STATUS ) * Class Membership: * Plot member function. * Description: c This function can be used to select the underlying graphics c functions to be used when the supplied Plot produces graphical output. c If this function is not called prior to producing graphical c output, then the underlying graphics functions selected at c link-time (using the ast_link command) will be used. To use c alternative graphics functions, call this function before c the graphical output is created, specifying the graphics c functions to be used. This will register the function for future c use, but the function will not actually be used until the Grf c attribute is given a non-zero value. f This routine can be used to select the underlying graphics f routines to be used when the supplied Plot produces graphical output. f If this routine is not called prior to producing graphical f output, then the underlying graphics routines selected at f link-time (using the ast_link command) will be used. To use f alternative graphics routines, call this routine before f the graphical output is created, specifying the graphics f routines to be used. This will register the routine for future f use, but the routine will not actually be used until the Grf f attribute is given a non-zero value. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c name f NAME = CHARACTER * ( * ) (Given) c A name indicating the graphics function to be replaced. c Various graphics functions are used by the c Plot class, and any combination of them may be supplied by calling c this function once for each function to be replaced. If any of the c graphics functions are not replaced in this way, the c corresponding functions in the graphics interface selected at c link-time (using the ast_link command) are used. The allowed c names are: f A name indicating the graphics routine to be replaced. f Various graphics routines are used by the f Plot class, and any combination of them may be supplied by calling f this routine once for each routine to be replaced. If any of the f graphics routines are not replaced in this way, the f corresponding routines in the graphics interface selected at f link-time (using the ast_link command) are used. The allowed f function names are: * * - Attr - Enquire or set a graphics attribute value * - BBuf - Start a new graphics buffering context * - Cap - Inquire a capability * - EBuf - End the current graphics buffering context * - Flush - Flush all pending graphics to the output device * - Line - Draw a polyline (i.e. a set of connected lines) * - Mark - Draw a set of markers * - Qch - Return the character height in world coordinates * - Scales - Get the axis scales * - Text - Draw a character string * - TxExt - Get the extent of a character string * * The string is case insensitive. For details of the interface * required for each, see the sections below. c fun f FUN = INTEGER FUNCTION (Given) c A Pointer to the function to be used to provide the c functionality indicated by parameter name. The interface for c each function is described below, but the function pointer should c be cast to a type of AstGrfFun when calling astGrfSet. f The name of the routine to be used to provide the f functionality indicated by parameter NAME (the name f should also appear in a Fortran EXTERNAL statement in the f routine which invokes AST_GRFSET). * c Once a function has been provided, a null pointer can be supplied c in a subsequent call to astGrfSet to reset the function to the c corresponding function in the graphics interface selected at c link-time. f Once a routine has been provided, the "null" routine AST_NULL can f be supplied in a subsequent call to astGrfSet to reset the routine f to the corresponding routine in the graphics interface selected at f link-time. AST_NULL is defined in the AST_PAR include file. f STATUS = INTEGER (Given and Returned) f The global status. * Function Interfaces: * All the functions listed below (except for "Cap") should return an * integer value of 0 if an error occurs, and 1 otherwise. All x and y * values refer f to "graphics cordinates" as defined by the GRAPHBOX parameter of f the AST_PLOT call which created the Plot. c to "graphics cordinates" as defined by the graphbox parameter of c the astPlot call which created the Plot. * c The first parameter ("grfcon") f The first argument (GRFCON) * for each function is an AST KeyMap pointer that can be used by the * called function to establish the context in which it is being called. * The contents of the KeyMap are determined by the calling * application, which should obtain a pointer to the KeyMap using the f AST_GETGRFCONTEXT routine, c astGetGrfContext function, * and then store any necessary information in the KeyMap using the * methods of the KeyMap class. Note, the functions listed below * should never annul or delete the supplied KeyMap pointer. * Attr: * The "Attr" function returns the current value of a specified graphics * attribute, and optionally establishes a new value. The supplied * value is converted to an integer value if necessary before use. * It requires the following interface: * c int Attr( AstObject *grfcon, int attr, double value, double *old_value, int prim ) f INTEGER FUNCTION ATTR( GRFCON, ATT, VAL, OLDVAL, PRIM ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - attr - An integer value identifying the required attribute. c The following symbolic values are defined in grf.h: f - ATT = INTEGER (Given) - An integer identifying the required attribute. f The following symbolic values are defined in GRF_PAR: * GRF__STYLE (Line style), * GRF__WIDTH (Line width), * GRF__SIZE (Character and marker size scale factor), * GRF__FONT (Character font), * GRF__COLOUR (Colour index). c - value - f - VAL = DOUBLE PRECISION (Given) - c A new value to store for the attribute. If this is AST__BAD * no value is stored. c - old_value - A pointer to a double in which to return f - OLDVAL = DOUBLE PRECISION (Returned) - Returned holding * the attribute value. c If this is NULL, no value is returned. c - prim - f - PRIM = INTEGER (Given) - * The sort of graphics primitive to be drawn with the new attribute. c Identified by the following values defined in grf.h: f Identified by the following values defined in GRF_PAR: * GRF__LINE, * GRF__MARK, * GRF__TEXT. * BBuf: * The "BBuf" function should start a new graphics buffering context. * A matching call to the function "EBuf" should be used to end the * context. The nature of the buffering is determined by the underlying * graphics system. * c int BBuf( AstObject *grfcon ) f INTEGER FUNCTION BBUF( GRFCON ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. * Cap: * The "Cap" function is called to determine if the grf module has a * given capability, as indicated by the "cap" argument: * c int Cap( AstObject *grfcon, int cap, int value ) f INTEGER FUNCTION CAP( GRFCON, CAP, VALUE ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - cap - f - CAP = INTEGER (Given) * The capability being inquired about. This will be one of the c following constants defined in grf.h: f following constants defined in GRF_PAR: * * GRF__SCALES: This function should return a non-zero value if the * "Scales" function is implemented, and zero otherwise. The supplied c "value" argument should be ignored. f VALUE argument should be ignored. * * GRF__MJUST: This function should return a non-zero value if * the "Text" and "TxExt" functions recognise "M" as a * character in the justification string. If the first character of * a justification string is "M", then the text should be justified * with the given reference point at the bottom of the bounding box. * This is different to "B" justification, which requests that the * reference point be put on the baseline of the text, since some * characters hang down below the baseline. If the "Text" or * "TxExt" function cannot differentiate between "M" and "B", * then this function should return zero, in which case "M" * justification will never be requested by Plot. The supplied c "value" argument should be ignored. f VALUE argument should be ignored. * * GRF__ESC: This function should return a non-zero value if the * "Text" and "TxExt" functions can recognise and interpret * graphics escape sequences within the supplied string (see * attribute Escape). Zero should be returned if escape sequences * cannot be interpreted (in which case the Plot class will interpret c them itself if needed). The supplied "value" argument should be f them itself if needed). The supplied VALUE argument should be * ignored only if escape sequences cannot be interpreted by "Text" and c "TxExt". Otherwise, "value" indicates whether "Text" and "TxExt" c should interpret escape sequences in subsequent calls. If "value" is f "TxExt". Otherwise, VALUE indicates whether "Text" and "TxExt" f should interpret escape sequences in subsequent calls. If VALUE is * non-zero then escape sequences should be interpreted by "Text" and * "TxExt". Otherwise, they should be drawn as literal text. * c - value - f - VALUE = INTEGER (Given) c The use of this parameter depends on the value of "cap" as f The use of this parameter depends on the value of CAP as * described above. * - Returned Function Value: c The value returned by the function depends on the value of "cap" f The value returned by the function depends on the value of CAP * as described above. Zero should be returned if the supplied * capability is not recognised. * EBuf: * The "EBuf" function should end the current graphics buffering * context. See the description of "BBuf" above for further details. * It requires the following interface: * c int EBuf( AstObject *grfcon ) f INTEGER FUNCTION EBUF( GRFCON ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. * Flush: * The "Flush" function ensures that the display device is up-to-date, * by flushing any pending graphics to the output device. It * requires the following interface: * c int Flush( AstObject *grfcon ) f INTEGER FUNCTION FLUSH( GRFCON ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. * Line: * The "Line" function displays lines joining the given positions and * requires the following interface: * c int Line( AstObject *grfcon, int n, const float *x, const float *y ) f INTEGER FUNCTION LINE( GRFCON, N, X, Y ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - n - The number of positions to be joined together. f - N = INTEGER (Given) - The number of positions to be joined together. c - x - A pointer to an array holding the "n" x values. f - X( N ) = REAL (Given) - An array holding the "n" x values. c - y - A pointer to an array holding the "n" y values. f - Y( N ) = REAL (Given) - An array holding the "n" y values. * Mark: * The "Mark" function displays markers at the given positions. It * requires the following interface: * c int Mark( AstObject *grfcon, int n, const float *x, const float *y, int type ) f INTEGER FUNCTION MARK( GRFCON, N, X, Y, TYPE ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - n - The number of positions to be marked. f - N = INTEGER (Given) - The number of positions to be marked. c - x - A pointer to an array holding the "n" x values. f - X( N ) = REAL (Given) - An array holding the "n" x values. c - y - A pointer to an array holding the "n" y values. f - Y( N ) = REAL (Given) - An array holding the "n" y values. c - type - An integer which can be used to indicate the type of marker c symbol required. f - TYPE = INTEGER (Given) - An integer which can be used to indicate f the type of marker symbol required. * Qch: * The "Qch" function returns the heights of characters drawn vertically * and horizontally in graphics coordinates. It requires the following * interface: * c int Qch( AstObject *grfcon, float *chv, float *chh ) f INTEGER FUNCTION QCH( GRFCON, CHV, CHH ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - chv - A pointer to the float which is to receive the height of f - CHV = REAL (Returned) The height of * characters drawn with a vertical baseline. This will be an * increment in the X axis. c - chh - A pointer to the float which is to receive the height of f - CHH = REAL (Returned) The height of * characters drawn with a horizontal baseline. This will be an * increment in the Y axis. * Scales: * The "Scales" function returns two values (one for each axis) which * scale increments on the corresponding axis into a "normal" coordinate * system in which: 1) the axes have equal scale in terms of (for instance) * millimetres per unit distance, 2) X values increase from left to * right, and 3) Y values increase from bottom to top. It requires the * following interface: * c int Scales( AstObject *grfcon, float *alpha, float *beta ) f INTEGER FUNCTION SCALES( GRFCON, ALPHA, BETA ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - alpha - A pointer to the float which is to receive the f - ALPHA = REAL (Returned) The * scale for the X axis (i.e. Xnorm = alpha*Xworld). c - beta - A pointer to the float which is to receive the f - BETA = REAL (Returned) The * scale for the Y axis (i.e. Ynorm = beta*Yworld). * Text: * The "Text" function displays a character string at a given * position using a specified justification and up-vector. It * requires the following interface: * c int Text( AstObject *grfcon, const char *text, float x, float y, const char *just, c float upx, float upy ) f INTEGER FUNCTION TEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - text - Pointer to a null-terminated character string to be displayed. f - TEXT = CHARACTER * ( * ) (Given) - The string to be displayed. c - x - The reference x coordinate. f - X = REAL (Given) - The reference x coordinate. c - y - The reference y coordinate. f - Y = REAL (Given) - The reference y coordinate. c - just - A character string which specifies the location within the f - JUST = CHARACTER * ( * ) (Given ) - A string which specifies the f location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. Note, "bottom" * corresponds to the base-line of normal text. Some characters * (eg "y", "g", "p", etc) descend below the base-line. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. c - upx - The x component of the up-vector for the text. f - UPX = REAL (Given) - The x component of the up-vector for the text. * If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * left to right on the screen. c - upy - The y component of the up-vector for the text. f - UPX = REAL (Given) - The y component of the up-vector for the text. * If necessary the supplied value should be negated * to ensure that positive values always refer to displacements from * bottom to top on the screen. * TxExt: * The "TxExt" function returns the corners of a box which would enclose * the supplied character string if it were displayed using the * Text function described above. The returned box includes any leading * or trailing spaces. It requires the following interface: * c int TxExt( AstObject *grfcon, const char *text, float x, float y, const char *just, c float upx, float upy, float *xb, float *yb ) f INTEGER FUNCTION TXEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY, XB, YB ) * c - grfcon - f - GRFCON = INTEGER (Given) - * A KeyMap containing information passed from the calling application. c - text - Pointer to a null-terminated character string to be displayed. f - TEXT = CHARACTER * ( * ) (Given) - The string to be displayed. c - x - The reference x coordinate. f - X = REAL (Given) - The reference x coordinate. c - y - The reference y coordinate. f - Y = REAL (Given) - The reference y coordinate. c - just - A character string which specifies the location within the f - JUST = CHARACTER * ( * ) (Given ) - A string which specifies the f location within the * text string which is to be placed at the reference position * given by x and y. See "Text" above. c - upx - The x component of the up-vector for the text. f - UPX = REAL (Given) - The x component of the up-vector for the text. * See "Text" above. c - upy - The y component of the up-vector for the text. f - UPX = REAL (Given) - The y component of the up-vector for the text. * See "Text" above. c - xb - An array of 4 elements in which to return the x coordinate of f - XB( 4 ) = REAL (Returned) - Returned holding the x coordinate of * each corner of the bounding box. c - yb - An array of 4 elements in which to return the y coordinate of f - YB( 4 ) = REAL (Returned) - Returned holding the y coordinate of * each corner of the bounding box. *-- */ /* Local Variables: */ const char *class; /* Object class */ const char *method; /* Current method */ int ifun; /* Index into grf function list */ void (* wrapper)(); /* Wrapper function for C Grf routine*/ /* Check the global error status. */ if ( !astOK ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ wrapper = NULL; /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astGrfSet"; class = astClass( this ); /* Identify the supplied function name and get its integer index into the list of grf functions. */ ifun = astGrfFunID( name, method, class ); /* Store the pointer. */ if( astOK ) { this->grffun[ifun] = fun; /* In general, the interface to each Grf function will differ for different languages. So we need a wrapper function with a known fixed interface which can be used to invoke the actual Grf function with an interface suited to the language in use. Call astGrfWrapper to store a wrapper to a suitable function which can invoke the supplied grf function. Here, we assume that the supplied function has a C interface, so we set up a C wrapper. If this function is being called from another language, then the interface for this function within that language should set up an appropriate wrapper after calling this function, thus over-riding the C wrapper set up here. */ if( ifun == AST__GATTR ) { wrapper = (AstGrfWrap) CGAttrWrapper; } else if( ifun == AST__GBBUF ) { wrapper = (AstGrfWrap) CGBBufWrapper; } else if( ifun == AST__GEBUF ) { wrapper = (AstGrfWrap) CGEBufWrapper; } else if( ifun == AST__GFLUSH ) { wrapper = (AstGrfWrap) CGFlushWrapper; } else if( ifun == AST__GLINE ) { wrapper = (AstGrfWrap) CGLineWrapper; } else if( ifun == AST__GMARK ) { wrapper = (AstGrfWrap) CGMarkWrapper; } else if( ifun == AST__GTEXT ) { wrapper = (AstGrfWrap) CGTextWrapper; } else if( ifun == AST__GCAP ) { wrapper = (AstGrfWrap) CGCapWrapper; } else if( ifun == AST__GTXEXT ) { wrapper = (AstGrfWrap) CGTxExtWrapper; } else if( ifun == AST__GSCALES ) { wrapper = (AstGrfWrap) CGScalesWrapper; } else if( ifun == AST__GQCH ) { wrapper = (AstGrfWrap) CGQchWrapper; } else if( astOK ) { astError( AST__INTER, "%s(%s): AST internal programming error - " "Grf function id %d not yet supported.", status, method, class, ifun ); } astGrfWrapper( this, name, wrapper ); } } int astGrfFunID_( const char *name, const char *method, const char *class, int *status ) { /* *+ * Name: * astGrfFunID * Purpose: * Return the integer identifier for a given GRF routine. * Type: * Hidden public function. * Synopsis: * #include "plot.h" * int astGrfFunID( const char *name, const char *method, * const char *class ) * Class Membership: * Plot member function. * Description: * This function returns an integer identifying the named grf function. * An error is reported if the named function is unknown. This function * is used by non-class modules within AST (e.g. fplot.c) which is why * it is public. It is not intended to be used by the public. * Parameters: * name * The grf function name. Any unambiguous abbreviation will do. * Case is ignored. The full list of grf function names is: * "Attr BBuf EBuf Scales Flush Line Mark Qch Text TxExt". See * grf_pgplot.c for details of these functions. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. *- */ /* Note that the list of identifiers here must be in the same order as the sorted values of the constants AST__GATTR, AST__GFLUSH, etc */ return FullForm( "Attr Flush Line Mark Text TxExt Scales Qch Cap BBuf " "EBuf", name, "Grf function name (programming error)", method, class, status ); } static char *GrfItem( int item, const char *text, int *axis, int *status ){ /* * Name: * GrfItem * Purpose: * Return the textual name corresponding to a specified graphical item * index. * Type: * Private function. * Synopsis: * #include "plot.h" * char *GrfItem( int item, const char *text, int *axis, int *status ) * Class Membership: * Plot member function. * Description: * This function returns a textual description of the graphical item * with the supplied index. * Parameters: * item * The index of the graphical item. * text * A pointer to a string which will be appended to the textual * description of the graphical item. May be NULL. * axis * Pointer to a place in which to return the index (0,1, or 2) of * the axis to which the attribute refers, If the attribute does * not refer to a specific axis, -1 is returned. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated string holding the textual * description of the graphical item, followed by any supplied "text". * Notes: * - An error is reported and a NULL pointer returned if the * index does not correspond to any graphical item. * - The returned pointer should be freed using astFree when it is no * longer needed. * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ char *desc; /* Pointer to the item description */ char *ret; /* Pointer to the returned string */ int dlen; /* Length of the item description */ if( axis ) *axis = -1; if( item == AST__BORDER_ID ) { desc = "Border"; } else if ( item == AST__GRIDLINE_ID ) { desc = "Gridline"; } else if ( item == AST__GRIDLINE1_ID ) { desc = "Axis 1 gridline"; if( axis ) *axis = 0; } else if ( item == AST__GRIDLINE2_ID ) { desc = "Axis 2 gridline"; if( axis ) *axis = 1; } else if ( item == AST__GRIDLINE3_ID ) { desc = "Axis 3 gridline"; if( axis ) *axis = 2; } else if ( item == AST__CURVE_ID ) { desc = "Curve"; } else if ( item == AST__NUMLABS_ID ) { desc = "Numerical labels"; } else if ( item == AST__TEXTLABS_ID ) { desc = "Textual labels"; } else if ( item == AST__TITLE_ID ) { desc = "Title"; } else if ( item == AST__MARKS_ID ) { desc = "Markers"; } else if ( item == AST__TEXT_ID ) { desc = "Text string"; } else if ( item == AST__TICKS_ID ) { desc = "Major and minor ticks"; } else if ( item == AST__AXIS1_ID ) { desc = "Axis 1"; if( axis ) *axis = 0; } else if ( item == AST__AXIS2_ID ) { desc = "Axis 2"; if( axis ) *axis = 1; } else if ( item == AST__AXIS3_ID ) { desc = "Axis 3"; if( axis ) *axis = 2; } else if ( item == AST__NUMLAB1_ID ) { desc = "Axis 1 numerical labels"; if( axis ) *axis = 0; } else if ( item == AST__NUMLAB2_ID ) { desc = "Axis 2 numerical labels"; if( axis ) *axis = 1; } else if ( item == AST__NUMLAB3_ID ) { desc = "Axis 3 numerical labels"; if( axis ) *axis = 2; } else if ( item == AST__TEXTLAB1_ID ) { desc = "Axis 1 textual label"; if( axis ) *axis = 0; } else if ( item == AST__TEXTLAB2_ID ) { desc = "Axis 2 textual label"; if( axis ) *axis = 1; } else if ( item == AST__TEXTLAB3_ID ) { desc = "Axis 3 textual label"; if( axis ) *axis = 2; } else if ( item == AST__TICKS1_ID ) { desc = "Axis 1 tick marks"; if( axis ) *axis = 0; } else if ( item == AST__TICKS2_ID ) { desc = "Axis 2 tick marks"; if( axis ) *axis = 1; } else if ( item == AST__TICKS3_ID ) { desc = "Axis 3 tick marks"; if( axis ) *axis = 2; } else { desc = NULL; if( astOK ){ astError( AST__INTER, "GrfItem: AST internal programming error - " "Invalid graphical item index %d supplied to GrfItem.", status, item ); } } if( desc ) { dlen = strlen( desc ); if( text ) { ret = astStore( NULL, desc, dlen + strlen( text ) + 1 ); if( ret ) strcpy( ret + dlen, text ); } else { ret = astStore( NULL, desc, dlen + 1 ); } } else { ret = NULL; } /* Return the answer. */ return ret; } static void GrfWrapper( AstPlot *this, const char *name, AstGrfWrap wrapper, int *status ) { /* *+ * Name: * astGrfWrapper * Purpose: * Register a wrapper function for a F77 or C Grf function. * Type: * Protected function. * Synopsis: * #include "plot.h" * void astGrfWrapper( AstPlot *this, const char *name, AstGrfWrap wrapper) * Description: * This function stores a pointer to the supplied wrapper function * within the plot, associating it with the grf function indicated by * the "name" parameter. The supplied wrapper function should call the * named grf function, using an interface appropriate to the language * in which the grf function is written. * Parameters: * this * The plot. * name * A name indicating the graphics function which is called by the * supplied wrapper function. See astGrfSet for details. * wrapper * A pointer to the wrapper function. This will be cast to a * specific type for the named grf function before being store * in the Plot. *- */ /* Local Variables: */ const char *class; /* Object class */ const char *method; /* Current method */ int ifun; /* Index into grf function list */ /* Check the global error status. */ if ( !astOK ) return; /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astGrfWrapper"; class = astClass( this ); /* Identify the supplied function name and get its integer index into the list of grf functions. */ ifun = astGrfFunID( name, method, class ); /* Cast the wrapper to an interface appropriate for the wrapped grf function, and store it in the appropriate component of the Plot. */ if( ifun == AST__GATTR ) { this->GAttr = (AstGAttrWrap) wrapper; } else if( ifun == AST__GBBUF ) { this->GBBuf = (AstGBBufWrap) wrapper; } else if( ifun == AST__GEBUF ) { this->GEBuf = (AstGEBufWrap) wrapper; } else if( ifun == AST__GFLUSH ) { this->GFlush = (AstGFlushWrap) wrapper; } else if( ifun == AST__GLINE ) { this->GLine = (AstGLineWrap) wrapper; } else if( ifun == AST__GMARK ) { this->GMark = (AstGMarkWrap) wrapper; } else if( ifun == AST__GTEXT ) { this->GText = (AstGTextWrap) wrapper; } else if( ifun == AST__GCAP ) { this->GCap = (AstGCapWrap) wrapper; } else if( ifun == AST__GTXEXT ) { this->GTxExt = (AstGTxExtWrap) wrapper; } else if( ifun == AST__GSCALES ) { this->GScales = (AstGScalesWrap) wrapper; } else if( ifun == AST__GQCH ) { this->GQch = (AstGQchWrap) wrapper; } else if( astOK ) { astError( AST__INTER, "%s(%s): AST internal programming error - " "Grf function id %d not yet supported.", status, method, class, ifun ); } } static void Grid( AstPlot *this_nd, int *status ){ /* *++ * Name: c astGrid f AST_GRID * Purpose: * Draw a set of labelled coordinate axes. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astGrid( AstPlot *this ) f CALL AST_GRID( THIS, STATUS ) * Class Membership: * Plot method. * Description: c This function draws a complete annotated set of f This routine draws a complete annotated set of * coordinate axes for a Plot with (optionally) a coordinate grid * superimposed. Details of the axes and grid can be controlled by * setting values for the various attributes defined by the Plot * class (q.v.). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If the supplied Plot is a Plot3D, the axes will be annotated * using three 2-dimensional Plots, one for each 2D plane in the 3D * current coordinate system. The plots will be "pasted" onto 3 faces * of the cuboid graphics volume specified when the Plot3D was * constructed. The faces to be used can be controlled by the "RootCorner" * attribute. * - An error results if either the current Frame or the base Frame * of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. * - An error also results if the transformation between the base * and current Frames of the Plot is not defined in either * direction (i.e. the Plot's TranForward or TranInverse attribute * is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPlot *this; /* Plot with 2d current Frame */ AstPlotCurveData **cdata;/* Pointer to info. about breaks in curves */ TickInfo **grid; /* Pointer to info. about tick marks */ const char *class; /* Object class */ const char *method; /* Current method */ double cen[ 2 ]; /* Position of first tick mark */ double gap[ 2 ]; /* Gap between tick marks */ double labelat[ 2 ]; /* Axis values at which tick marks are put */ int axis; /* Physical axis index */ int border; /* Draw a border? */ int clip; /* Original Clip attribute value */ int dounits[2]; /* Include Units in each axis label? */ int drawgrid; /* Is a grid of lines to be drawn? */ int clredge; /* Clear the Edge attributes before returning? */ int edgeticks; /* Draw labels round edges of plotting area? */ int escs; /* Original astEscapes value */ int ink; /* Draw the grid with visible ink? */ int inval; /* Were areas of invalid coordinates found? */ int labelling; /* Value of Labelling attribute */ int loglabelset[2]; /* Were the LogLabel attributes set initially? */ int logticksset[2]; /* Were the LogTicks attributes set initially? */ int naxes; /* No. of axes in the base or current Frame */ int oldedge0; /* Default value for Edge(1) */ int oldedge1; /* Default value for Edge(2) */ int useint; /* Do interior labels give us an advantage? */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_nd); /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astGrid"; class = astClass( this_nd ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this_nd ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Ensure AST functions included graphical escape sequences in any returned text strings. */ escs = astEscapes( 1 ); /* Note if attributes which have complex dynamic defaults are set initially. */ logticksset[0] = astTestLogTicks( this_nd, 0 ); logticksset[1] = astTestLogTicks( this_nd, 1 ); loglabelset[0] = astTestLogLabel( this_nd, 0 ); loglabelset[1] = astTestLogLabel( this_nd, 1 ); /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Get a Plot with a 2D (or 1D) current Frame. */ this = (AstPlot *) Fset2D( (AstFrameSet *) this_nd, AST__CURRENT, status ); /* Check the current Frame of the Plot is 2-D. */ naxes = astGetNout( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the current " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Ensure that all lines are clipped at the plot boundary.*/ if( astTestClip( this ) ) { clip = astGetClip( this ); astSetClip( this, 1 ); } else { clip = -1; } /* If the protected attribute "Ink" is set to zero, then the plot is drawn in "invisble ink" (i.e. all the calculations needed to produce the grid are performed, but nothing is actually drawn). */ ink = astGetInk( this ); /* Initialise the bounds of the box containing all plotted lines and numerical labels. */ Box_lbnd[ 0 ] = FLT_MAX; Box_lbnd[ 1 ] = FLT_MAX; Box_ubnd[ 0 ] = FLT_MIN; Box_ubnd[ 1 ] = FLT_MIN; /* Obtain the requested centre attribute values for both physical axes. */ for( axis = 0; axis < 2; axis++ ){ cen[ axis ] = astGetCentre( this, axis ); } /* Determine where to put the major axis values. */ grid = GridLines( this, cen, gap, &inval, method, class, status ); /* If the user has set an explicit value for Grid, use it. */ if( astTestGrid( this ) ){ drawgrid = astGetGrid( this ); /* If not, the default for Grid is based on whether or not there are any invalid regions. */ } else if( inval ){ drawgrid = 1; } else { drawgrid = 0; } /* Draw the curves marking the major tick values on each axis. Information is returned describing the positions of the breaks in these curves. */ cdata = DrawGrid( this, grid, ( ink && drawgrid ), method, class, status ); /* See if labels and tick marks will be drawn round the edges of the plotting area, rather than within it (no labels are actually drawn yet). Interior labels can always be produced, in which case edgeticks is set explicitly to zero to indicate that ticks will be internal. Exterior labelling may or may not be possible. If it is requested, check to see if it is possible. */ clredge = 0; labelling = astGetLabelling( this ); if( labelling ){ edgeticks = 0; } else { edgeticks = EdgeLabels( this, 0, grid, cdata, 0, method, class, status ); /* If the external labelling was requested, but could not be produced... */ if( !edgeticks ) { /* and if the Edge attributes have not been set... */ if( !astTestEdge( this, 0 ) && !astTestEdge( this, 1 ) ) { /* Try flipping the default Edge values, to see if this allows us to honour the requested Labelling scheme. */ oldedge0 = astGetEdge( this, 0 ); oldedge1 = astGetEdge( this, 1 ); astSetEdge( this, 0, oldedge1 ); astSetEdge( this, 1, oldedge0 ); /* See if exterior labels could be drawn with these new edges. */ edgeticks = EdgeLabels( this, 0, grid, cdata, 0, method, class, status ); /* If this would allow us to use the requested labelling scheme, retain the new Edge values, setting a flag to indicate that they will need to be cleared before returning. Otherwise, clear them. */ if( edgeticks ) { clredge = 1; } else { astClearEdge( this, 0 ); astClearEdge( this, 1 ); } } } } /* If edge ticks can still not be produced, but the ForceExterior attribute has a non-zero value, attempt to create exterior labels even though it looks like there may be insufficient of them to justify their use. */ if( !edgeticks && astGetForceExterior( this ) ) { edgeticks = EdgeLabels( this, 0, grid, cdata, 1, method, class, status ); } /* We may also need to swap edge values when using interior labelling in order to ensure that the text labels are placed on appropriate edges of the plotting box. */ if( !edgeticks && !astTestEdge( this, 0 ) && !astTestEdge( this, 1 ) ) { if( swapEdges( this, grid, cdata, status ) ) { oldedge0 = astGetEdge( this, 0 ); oldedge1 = astGetEdge( this, 1 ); astSetEdge( this, 0, oldedge1 ); astSetEdge( this, 1, oldedge0 ); clredge = 1; } } /* If edge ticks are being used, store bad values for the labelat values to indicate that labels are not being drawn within the interior of the plotting area. */ if( edgeticks ){ labelat[ 0 ] = AST__BAD; labelat[ 1 ] = AST__BAD; /* Otherwise, see where interior labels and tick marks should go (the axis values are put in "labelat"). */ } else { useint = Labelat( this, grid, cdata, labelat, method, class, status ); /* If interior labelling does not allow us to draw any more ticks, revert to edge labelling if that is what the user requested. */ if( !useint && !labelling ) { labelat[ 0 ] = AST__BAD; labelat[ 1 ] = AST__BAD; edgeticks = EdgeLabels( this, 0, grid, cdata, 1, method, class, status ); } } /* See if a border is required. By default, a border is drawn only when using exterior labelling. */ if( astTestBorder( this ) ) { border = astGetBorder( this ); } else { border = edgeticks; } /* See if the Units string is to be inluded in the label. */ dounits[ 0 ] = astGetLabelUnits( this, 0 ); dounits[ 1 ] = astGetLabelUnits( this, 1 ); /* The rest is not done if no output is required. */ if( ink ) { /* Draw tick marks (major and minor). */ DrawTicks( this, grid, drawgrid, labelat, gap, method, class, status ); /* If required, ensure that curves through the tick marks have been drawn */ DrawAxis( this, grid, labelat, gap, method, class, status ); /* If required, draw a curve around the edge of the area containing valid physical coordinates. */ if( border ) (void) astBorder( this ); /* Draw the numerical labels at the major tick values. */ Labels( this, grid, cdata, gap, labelat, method, class, status ); /* Draw the textual labels for each axis and a title. */ TextLabels( this, edgeticks, dounits, method, class, status ); } /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); /* Store the actual values used for all attributes which have dynamic defaults. Check the global status to ensure the pointer "grid" can be used without the possibility of a segmentation violation. */ for( axis = 0; axis < 2 && astOK ; axis++ ) { SetUsedLogTicks( this_nd, axis, astGetLogTicks( this, axis ), status ); SetUsedLogLabel( this_nd, axis, astGetLogLabel( this, axis ), status ); if( astGetLogTicks( this, axis ) ) { SetUsedLogGap( this_nd, axis, gap[ axis ], status ); } else { SetUsedGap( this_nd, axis, gap[ axis ], status ); } SetUsedCentre( this_nd, axis, cen[ axis ], status ); SetUsedEdge( this_nd, axis, astGetEdge( this, axis ), status ); SetUsedLabelAt( this_nd, axis, labelat[ axis ], status ); SetUsedLabelUnits( this_nd, axis, dounits[ axis ], status ); /* If explicit minor tick values were supplied using astSetTickValues, then set MinTick to the average number of minor tick divisions per major tick division. */ if( grid[ axis ]->minticks ) { SetUsedMinTick( this_nd, axis, ( grid[ axis ]->nminor + grid[ axis ]->nmajor )/ ( grid[ axis ]->nmajor - 1 ), status ); } else { SetUsedMinTick( this_nd, axis, grid[ axis ]->nminor, status ); } if( astTestTextLab( this, axis ) ) { SetUsedTextLab( this_nd, axis, astGetTextLab( this, axis ), status ); } else { SetUsedTextLab( this_nd, axis, edgeticks, status ); } if( astTestMajTickLen( this, axis ) ) { SetUsedMajTickLen( this_nd, axis, astGetMajTickLen( this, axis ), status ); } else { SetUsedMajTickLen( this_nd, axis, drawgrid ? 0.0 : astGetMajTickLen( this, axis ), status ); } } SetUsedGrid( this_nd, drawgrid, status ); SetUsedLabelling( this_nd, edgeticks ? 0 : 1, status ); SetUsedBorder( this_nd, border, status ); /* Free the memory used to hold information about the curves. */ cdata = CleanCdata( cdata, status ); /* Free the memory used to hold information about the tick marks. */ grid = CleanGrid( grid, status ); /* If required clear attributes. */ if( clredge ) { astClearEdge( this, 0 ); astClearEdge( this, 1 ); } if( !logticksset[ 0 ] ) astClearLogTicks( this, 0 ); if( !logticksset[ 1 ] ) astClearLogTicks( this, 1 ); if( !loglabelset[ 0 ] ) astClearLogLabel( this, 0 ); if( !loglabelset[ 1 ] ) astClearLogLabel( this, 1 ); /* Restore the original value of the Clip attribute. */ if( clip != -1 ) astSetClip( this, clip ); /* Free the 2D Plot. */ this = astAnnul( this ); /* Restore the original value of the flag which says whether graphical escape sequences should be incldued in any returned text strings. */ astEscapes( escs ); /* Copy the total bounding box to the box which is returned by astBoundingBox. */ if( !Boxp_freeze ){ Boxp_lbnd[ 0 ] = Box_lbnd[ 0 ]; Boxp_lbnd[ 1 ] = Box_lbnd[ 1 ]; Boxp_ubnd[ 0 ] = Box_ubnd[ 0 ]; Boxp_ubnd[ 1 ] = Box_ubnd[ 1 ]; } /* Return. */ return; } static void GridLine( AstPlot *this, int axis, const double start[], double length, int *status ){ /* *++ * Name: c astGridLine f AST_GRIDLINE * Purpose: * Draw a grid line (or axis) for a Plot. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astGridLine( AstPlot *this, int axis, const double start[], c double length ) f CALL AST_GRIDLINE( THIS, AXIS, START, LENGTH, STATUS ) * Class Membership: * Plot method. * Description: c This function draws a curve in the physical coordinate system of f This routine draws a curve in the physical coordinate system of * a Plot by varying only one of the coordinates along the length * of the curve. It is intended for drawing coordinate axes, * coordinate grids, and tick marks on axes (but note that these c are also available via the more comprehensive astGrid function). f are also available via the more comprehensive AST_GRID routine). * * The curve is transformed into graphical coordinate space for * plotting, so that a straight line in physical coordinates may * result in a curved line being drawn if the Mapping involved is * non-linear. Any discontinuities in the Mapping between physical * and graphical coordinates are catered for, as is any c clipping established using astClip. f clipping established using AST_CLIP. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c axis f AXIS = INTEGER (Given) * The index of the Plot axis whose physical coordinate value is * to be varied along the length of the curve (all other * coordinates will remain fixed). This value should lie in the * range from 1 to the number of Plot axes (Naxes attribute). c start f START( * ) = DOUBLE PRECISION (Given) * An array, with one element for each axis of the Plot, giving * the physical coordinates of the start of the curve. c length f LENGTH = DOUBLE PRECISION (Given) * The length of curve to be drawn, given as an increment along * the selected physical axis. This may be positive or negative. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - No curve is drawn if the "start" array contains any c coordinates with the value AST__BAD, nor if "length" has this value. f - No curve is drawn if the START array contains any f coordinates with the value AST__BAD, nor if LENGTH has this value. * - An error results if the base Frame of the Plot is not 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *class; /* Object class */ const char *method; /* Current method */ int naxes; /* No. of axes in the base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astGridLine"; class = astGetClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Initialise the bounding box for primatives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Validate the axis index, converting the axis index to be zero-based. */ (void) astValidateAxis( this, axis - 1, 1, method ); /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Draw the curve. The break information is stored in an external structure where it can be accessed by public methods which return information about the most recently drawn curve. */ AxPlot( this, axis - 1, start, length, 1, &Curve_data, method, class, status ); /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); } static TickInfo **GridLines( AstPlot *this, double *cen, double *gap, int *inval, const char *method, const char *class, int *status ){ /* * Name: * GridLines * Purpose: * Obtain information desribing the major tick values within the plotting * area. * Type: * Private function. * Synopsis: * #include "plot.h" * TickInfo **GridLines( AstPlot *this, double *cen, double *gap, * int *inval, const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * A pointer is returned which points to an array of two pointers. Each * of these pointers points to a TickInfo structure which holds * information about the ticks on a single axis. These structures, * together with the array holding the two pointers, should be released * when no longer needed using CleanGrid. * Parameters: * this * The Plot. * cen * A pointer to an array holding axis values at which to put a single * central tick. Other ticks are placed evenly on either side of this * tick. If AST__BAD is provided, a value will be used which would put a * tick at an axis value of zero. * gap * A pointer to an array holding the gaps between ticks required on * each axis. If this is AST__BAD a suitable default value will be used * and returned in place of the AST__BAD value. * inval * A pointer to a location at which to return a flag indicating if * any invalid physical coordinates were encountered while deciding on * the tick values. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to an array of two TickInfo pointers. * Notes: * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned. */ /* Local Variables: */ AstFrame *fr; /* Pointer to current Frame */ GetTicksStatics *statics = NULL; /* Pointer to static data for GetTicks */ TickInfo **info; /* Returned array of two TickInfo pointers */ double *lengths; /* Pointer to lengths of each curve section */ double *starts; /* Pointer to start of each curve section */ double *ticks; /* Pointer to tick mark values */ double bot; /* Lowest axis value to display */ double end; /* Axis value at end of curve section */ double tmp; /* Temp storage */ double top; /* Highest axis value to display */ int i; /* Tick mark index */ int j; /* Axis index */ int k; /* Section index */ int logticks[ 2 ]; /* Uses logarithmicaly spaced tick marks? */ int nticks; /* Number of tick marks */ /* Check the global status. */ if( !astOK ) return NULL; /* Get memory to hold two TickInfo pointers. */ info = (TickInfo **) astMalloc( 2*sizeof( TickInfo *) ); /* If succesfull... */ if( astOK ){ /* Initialise the two pointers. */ info[ 0 ] = NULL; info[ 1 ] = NULL; /* Obtain the tick mark values, and the corresponding formatted labels for each axis. */ for( j = 0; j < 2; j++ ){ info[ j ] = TickMarks( this, j, cen + j, gap + j, inval, &statics, method, class, status ); logticks[ j ] = astGetLogTicks( this, j ); } /* Release the resources allocated in the first call to TickMarks. */ for( j = 0; j < 2; j++ ){ (void) TickMarks( NULL, j, NULL, gap, NULL, &statics, method, class, status ); } /* Each major tick value for axis "j" may be marked with a curve parallel to axis "1-j" drawn across the entire plotting area. We need to decide where to start drawing this curve and how long it should be. We can simply use the minimum value on axis "1-j" together with the tick value on axis "j" to define the starting position. The length could be taken as the difference between the maximum and minimum values on axis "1-j". However, this may not be right in some situations. For instance if the plotting area covers a small range of Right Ascension from 23:59:59 to 00:00:01. Using the difference between the maximum and minimum values to give the length of the curve would result in the curve starting at 00:00:00 (the minimum axis value) and extending for a length of 23:59:59 (the axis range). To get round this sort of problem, the curve is split up into sections with lengths and starting positions determined by the tick mark values on axis "1-j". The first section starts at the minimum axis value and extends upto the first missing tick mark (in the RA example, this would be at 00:00:01). Subsequent sections starts at the next tick mark (23:59:59 in the RA example) and extends upto the next missing tick mark, or the last tick mark if none are missing. */ /* Get the current frame. */ fr = astGetFrame( this, AST__CURRENT ); /* If either axis has log tick spacing, use the simple approach which assumes that each curve has only one section. */ if( logticks[ 0 ] || logticks[ 1 ] ) { /* Find the start and length of the curve for each tick mark on axis "j". */ for( j = 0; j < 2 && astOK; j++ ){ /* Find the axis range to display on the other axis. */ bot = astGetBottom( fr, 1 - j ); top = astGetTop( fr, 1 - j ); if( bot > top ) { tmp = top; top = bot; bot = tmp; } /* Get a pointer to the major tick mark values on the other axis ("1-j"), together with the number of them. */ ticks = info[ 1 - j ]->ticks; nticks = info[ 1 - j ]->nmajor; /* Reserve memory to hold the starts and lengths of each section of the grid line marking the major ticks on the axis "j". There will only be one section. */ starts = (double *) astMalloc( sizeof(double) ); lengths = (double *) astMalloc( sizeof(double) ); info[ j ]->start = starts; info[ j ]->length = lengths; /* Check that the pointers can be used. */ if( astOK ) { /* The section starts one gap below the first tick, and ends one gap above the first tick. Limit both to the displayed range of the axis. */ if( logticks[ 1 - j ] ) { starts[ 0 ] = astMIN( top, astMAX( bot, ticks[ 0 ]/gap[ 1 - j ] ) ); end = astMIN( top, astMAX( bot, ticks[ nticks - 1 ]*gap[ 1 - j ] ) ); } else { starts[ 0 ] = astMIN( top, astMAX( bot, ticks[ 0 ] - gap[ 1 - j ] ) ); end = astMIN( top, astMAX( bot, ticks[ nticks - 1 ] + gap[ 1 - j ] ) ); } /* Store the length of the section. */ lengths[ 0 ] = end - starts[ 0 ]; /* Store the number of sections in the returned structure. */ info[ 0 ]->nsect = 1; } } /* If both axes have linear tick spacing, use the complete approach. */ } else { /* Find the start and length of each section of the curve for each tick mark on axis "j". */ for( j = 0; j < 2 && astOK; j++ ){ /* Find the axis range to display on the other axis. */ bot = astGetBottom( fr, 1 - j ); top = astGetTop( fr, 1 - j ); if( bot > top ) { tmp = top; top = bot; bot = tmp; } /* Get a pointer to the major tick mark values on the other axis ("1-j"), together with the number of them. */ ticks = info[ 1 - j ]->ticks; nticks = info[ 1 - j ]->nmajor; /* Reserve memory to hold the starts and lengths of each section of the grid line marking the major ticks on the axis "j". The allocated arrays are the largest that could possibly be needed (i.e. if every tick mark starts a new section). */ starts = (double *) astMalloc( sizeof(double)*(size_t) nticks ); lengths = (double *) astMalloc( sizeof(double)*(size_t) nticks ); info[ j ]->start = starts; info[ j ]->length = lengths; /* Check that the pointers can be used. */ if( astOK ) { /* Loop round each of the major tick marks on axis "1-j". */ k = 0; i = 0; while( i < nticks ){ /* Record the start of the next section of the grid lines. */ starts[ k ] = ticks[ i++ ]; /* Tick marks should be regularly spaced by the values in "gap". Check each tick mark until a missing tick mark is found. The section ends at the start of the gap. */ while( i < nticks && ( ticks[ i ] - ticks[ i - 1 ] ) < 1.5*gap[ 1 - j ] ) i++; /* Record the length of the section. */ lengths[ k ] = ticks[ i - 1 ] - starts[ k ]; /* The section is extended at start and end by one gap in order to "cover up the joins". Limit this to the displayed range of the axis. */ starts[ k ] -= gap[ 1 - j]; lengths[ k ] += 2.0*gap[ 1 - j ]; /* Limit the start and end to the displayed range of the axis. */ end = starts[ k ] + lengths[ k ]; starts[ k ] = astMIN( top, astMAX( bot, starts[ k ] ) ); lengths[ k ] = astMIN( top, astMAX( bot, end ) ) - starts[ k ]; /* Increment the number of sections. */ k++; } /* Store the number of sections in the returned structure. */ info[j]->nsect = k; } } } /* Annull the current frame. */ fr = astAnnul( fr ); } /* If an error has occurred, clean up the returned TickInfo structures. */ if( !astOK ) info = CleanGrid( info, status ); /* Return. */ return info; } void astGrfAttrs_( AstPlot *this, int id, int set, int prim, const char *method, const char *class, int *status ){ /* *+ * Name: * astGrfAttrs * Purpose: * Establish values for the graphics attributes for a given object. * Type: * Protected function. * Synopsis: * #include "plot.h" * void astGrfAttrs( AstPlot *this, int id, int set, int prim, const char *method, const char *class ) * Class Membership: * Plot member function. * Description: * This function should be called with "set=1" to establish the correct * graphics attributes prior to drawing specific graphical objects. Once * the object has been drawn, it should be called again with "set=0" to * re-establish the original graphics attributes. * * NOTE, each type of graphical object identified by "id" should be * drawn entirely by calls to just one of GMark, GText or GLine * as indicated by argument "prim". * Parameters: * this * A pointer to the Plot. * id * An integer specifying the graphical object to be drawn. * set * If non-zero then the attributes for the specified object are set * to the values indicated by the corresponding Plot attributes, * and the current values are saved in a static array. If zero, then * the values are set to the values stored in the static array. * prim * Indicates the sort of graphics primative used to draw the * object. This must be one of (defined in grf.h) : * * GRF__LINE * GRF__MARK * GRF__TEXT * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * Notes: * - This function should always be called in pairs with set=1 on the * first call and set=0 on the second call. * - If a pair of calls is nested within another pair of calls, the * inner pair has no effect. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double *attr; /* Pointer to the next attribute value */ double dval; /* Floating point attribute value */ int ival; /* Integer attribute value */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Set up a pointer to the next element in "grfattrs_attrs". */ attr = grfattrs_attrs; /* If we are setting new values, increment the nesting level, otherwise decrement it. */ if( set ){ grfattrs_nesting++; } else { grfattrs_nesting--; } /* If we are changing any line attributes, ensure all lines are flushed to the graphics system. */ if( prim == GRF__LINE ) Fpoly( this, method, class, status ); /* First deal with cases where we are establishing new values for the graphics attributes by setting them to the values of the corresponding Plot attributes. Only do this if we are at nesting level one. */ if( set && grfattrs_nesting == 1 ){ /* See if a value has been set in the Plot for the line style attribute for the specified object, If so, use the value. */ if( TestUseStyle( this, id, status ) ) { ival = GetUseStyle( this, id, status ); /* Save the current value, and establish the new value. */ GAttr( this, GRF__STYLE, (double) ival, attr++, prim, method, class, status ); /* If no style was specified, retain the current value. Indicate that no new value has been established by setting the old value bad. */ } else { *(attr++) = AST__BAD; } /* Do the same for the line width attribute. */ if( TestUseWidth( this, id, status ) ){ dval = GetUseWidth( this, id, status ); GAttr( this, GRF__WIDTH, dval, attr++, prim, method, class, status ); } else { *(attr++) = AST__BAD; } /* Do the same for the character size attribute. */ if( TestUseSize( this, id, status ) ) { dval = GetUseSize( this, id, status ); GAttr( this, GRF__SIZE, dval, attr++, prim, method, class, status ); } else { *(attr++) = AST__BAD; } /* Do the same for the character font attribute. */ if( TestUseFont( this, id, status ) ){ ival = GetUseFont( this, id, status ); GAttr( this, GRF__FONT, (double) ival, attr++, prim, method, class, status ); } else { *(attr++) = AST__BAD; } /* Do the same for the colour attribute. */ if( TestUseColour( this, id, status ) ) { ival = GetUseColour( this, id, status ); GAttr( this, GRF__COLOUR, (double) ival, attr++, prim, method, class, status ); } else { *(attr++) = AST__BAD; } } /* Now deal with cases where we are re-establishing old values saved on a previous call to this function. Only do this if we are at nesting level zero. */ if( !set && !grfattrs_nesting ){ GAttr( this, GRF__STYLE, *(attr++), NULL, prim, method, class, status ); GAttr( this, GRF__WIDTH, *(attr++), NULL, prim, method, class, status ); GAttr( this, GRF__SIZE, *(attr++), NULL, prim, method, class, status ); GAttr( this, GRF__FONT, *(attr++), NULL, prim, method, class, status ); GAttr( this, GRF__COLOUR, *(attr++), NULL, prim, method, class, status ); } /* Return. */ return; } static int GVec( AstPlot *this, AstMapping *mapping, double *phy, int axis, double delta, AstPointSet **pset1, AstPointSet **pset2, double *gx, double *gy, double *dx, double *dy, int *flag, const char *method, const char *class, int *status ){ /* * Name: * GVec * Purpose: * Returns a unit vector parallel to a physical axis at a given point. * Type: * Private function. * Synopsis: * #include "plot.h" * int GVec( AstPlot *this, AstMapping *mapping, double *phy, * int axis, double delta, AstPointSet **pset1, * AstPointSet **pset2, double *gx, double *gy, * double *dx, double *dy, int *flag, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function returns a unit vector (in the graphics coordinate * system) in the positive direction of the specified physical axis, * at the given physical position. It works by transforming the given * physical position, together with another very close position, and * returning the vector between them. It is possible for a * discontinuity to occur between these two close positions, * resulting in a very large meaningless vector prior to * normalisation. For this reason two vectors are found, one joining * the given position to a close position higher up the axis, and one * joining a close position lower down the axis to the given position. * If these two vectors differ in magnitude by a large factor, then * the shorter of the two vectors is normalised and returned. * Otherwise, the vector which is closest in direction to the vector * supplied in [dx,dy] is returned. The returned vector is reversed if * necessary so that it always points in the positive direction of the * axis. * * If neither of the two vectors can be found (i.e. if the graphics * coordinates are bad, or coincident), then the vector supplied in * [dx,dy] is returned unchanged, and a function value of zero is * returned. Otherwise, a function value of one is returned. * Parameters: * this * Pointer to the Plot. * mapping * Pointer to the Mapping from the base Frame of the Plot ot the * current Frame. * phy * Pointer to an array holding the coordinates in the current Frame * of the Plot at which the tangent vector is required. * axis * The index of the axis within the current Frame for which the * tangent vector is required. * delta * The increment in the axis value to use between positions defining * the vectors. * pset1 * A pointer to a place at which to store a pointer to a PointSet * holding current Frame coordinates. This PointSet pointer should * be supplied as NULL on the first call to this function, resulting * in a new PointSet being created and a pointer to it returned. * Subsequent calls to this function shopuld retain the pointer * returned by the first call. The PointSet pointer should be * annulled using astAnnul when no longer needed. * pset2 * A pointer to a place at which to store a pointer to a PointSet * holding base Frame coordinates. This PointSet is managed in the * same way as "pset1". * gx * A pointer to a double in which to return the graphics X * coordinate of the position supplied by "phy". * gy * A pointer to a double in which to return the graphics Y * coordinate of the position supplied by "phy". * dx * A pointer to a double in which to return the X component * of the unit tangent vector. This should be supplied holding a * "default" unit vector which is left unchanged if no new vector * can be found. * dy * A pointer to a double in which to return the Y component * of the unit tangent vector. This should be supplied holding a * "default" unit vector which is left unchanged if no new vector * can be found. * flag * A pointer to an int in which to return a flag indicating which * of the two vectors was returned. Zero is returned if the vector * was estimated by moving in a positive direction along the axis * from the position supplied by "phy". One is returned if the vector * was estimated by moving in a negative direction along the axis * from the position supplied by "phy" (in this case the returned * vector will have been negated so that it refers to the positive * direction). * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * One is returned if the vector was found succesfully, Zero is returned * if the vector could not be estimated for any reason. No error is * reported if the failure was due to the nature of the mapping. * Notes: * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned. */ /* Local Variables: */ double dd1; /* Length of positive vector */ double dd2; /* Length of negative vector */ double dx1; /* X component of positive vector */ double dx2; /* X component of negative vector */ double dy1; /* Y component of positive vector */ double dy2; /* Y component of negative vector */ double **ptr1; /* Pointers to physical coordinate data */ double **ptr2; /* Pointers to graphics coordinate data */ int i; /* Axis index */ int nphy; /* No. of axes in current (physical) Frame */ int ret; /* Was a vector estimated succesfully? */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ dx1 = 0.0; dx2 = 0.0; dy1 = 0.0; dy2 = 0.0; /* Initialise the returned value to indicate that the vector can not be found. */ ret = 0; /* Get the number of physical coordinates from the mapping. */ nphy = astGetNout( mapping ); /* If no PointSets have been supplied, create some now. PointSet 1 contains physical coordinates, PointSet 2 contains graphics coordinates. */ if( !(*pset1) ) *pset1 = astPointSet( 3, nphy, "", status ); if( !(*pset2) ) *pset2 = astPointSet( 3, 2, "", status ); /* Get pointers to the PointSet data. */ ptr1 = astGetPoints( *pset1 ); ptr2 = astGetPoints( *pset2 ); /* Check the PointSets can be used. */ if( astOK ){ /* Store the physical coordinates of three close points on a curve parallel to the given axis, with the centre point at the given position. */ for( i = 0; i < nphy; i++ ){ ptr1[ i ][ 0 ] = phy[ i ]; ptr1[ i ][ 1 ] = phy[ i ]; ptr1[ i ][ 2 ] = phy[ i ]; } if( phy[ axis ] != AST__BAD ){ ptr1[ axis ][ 0 ] = phy[ axis ] - delta; ptr1[ axis ][ 2 ] = phy[ axis ] + delta; } /* Find the corresponding graphics coordinates. */ (void) Trans( this, NULL, mapping, *pset1, 0, *pset2, 0, method, class, status ); /* Check the central position is OK. */ *gx = ptr2[ 0 ][ 1 ]; *gy = ptr2[ 1 ][ 1 ]; if( astOK && *gx != AST__BAD && *gy != AST__BAD ){ /* Get the unit vector between the central position and the position at the higher physical axis value. Also get the length of the vector joining the two positions. */ if( ptr2[ 0 ][ 2 ] != AST__BAD && ptr2[ 1 ][ 2 ] != AST__BAD ){ dx1 = ptr2[ 0 ][ 2 ] - *gx; dy1 = ptr2[ 1 ][ 2 ] - *gy; dd1 = dx1*dx1 + dy1*dy1; if( dd1 > 0.0 ) { dd1 = sqrt( dd1 ); dx1 /= dd1; dy1 /= dd1; } else { dd1 = AST__BAD; } } else { dd1 = AST__BAD; } /* Do the same for the position with lower physical axis value, reversing the direction of the vector so that it refers to the positive direction. */ if( ptr2[ 0 ][ 0 ] != AST__BAD && ptr2[ 1 ][ 0 ] != AST__BAD ){ dx2 = *gx - ptr2[ 0 ][ 0 ]; dy2 = *gy - ptr2[ 1 ][ 0 ]; dd2 = dx2*dx2 + dy2*dy2; if( dd2 > 0.0 ) { dd2 = sqrt( dd2 ); dx2 /= dd2; dy2 /= dd2; } else { dd2 = AST__BAD; } } else { dd2 = AST__BAD; } /* Only overwrite the supplied vector if at least one of the two tangent vectors was defined. */ if( dd1 != AST__BAD || dd2 != AST__BAD ){ /* If the first vector was not defined, return the second. */ if( dd1 == AST__BAD ){ *dx = dx2; *dy = dy2; *flag = 1; ret = 1; /* If the second vector was not defined, return the first. */ } else if( dd2 == AST__BAD ){ *dx = dx1; *dy = dy1; *flag = 0; ret = 1; /* If the first vector is much longer than the second, return the second. */ } else if( dd1 > 100.0*dd2 ){ *dx = dx2; *dy = dy2; *flag = 1; ret = 1; /* If the second vector is much longer than the first, return the first. */ } else if( dd2 > 100.0*dd1 ){ *dx = dx1; *dy = dy1; *flag = 0; ret = 1; /* If both vectors are defined and of comparable length, return the vector which is most nearly parallel to the supplied vector. Note, we assume that the supplied vector [dx,dy] is a unit vector. */ } else if( *dx != AST__BAD && *dx != AST__BAD ){ if( ( dx1*(*dx) + dy1*(*dy) )/dd1 > ( dx2*(*dx) + dy2*(*dy) )/dd2 ){ *dx = dx1; *dy = dy1; *flag = 0; ret = 1; } else { *dx = dx2; *dy = dy2; *flag = 1; ret = 1; } /* If no vector was supplied, return the shorter of the two vectors. */ } else if( dd1 < dd2 ){ *dx = dx1; *dy = dy1; *flag = 0; ret = 1; } else { *dx = dx2; *dy = dy2; *flag = 1; ret = 1; } } } } /* Return the answer. */ return ret; } static int HasEscapes( const char *text, int *status ) { /* * Name: * HasEscapes * Purpose: * Check if a text string contains any escape sequences. * Type: * Private function. * Synopsis: * #include "plot.h" * int HasEscapes( const char *text, int *status ) * Class Membership: * Plot member function. * Description: * This function checks if a text string contains any escape sequences * (see attribute Escape). * Parameters: * text * The text to check. * status * Pointer to the inherited status variable. * Returned: * Non-zero if any escape sequences are found in the text. Zero * otherwise. */ /* Local Variables: */ int result; int type; int value; int nc; /* Initialise. */ result = 0; /* Check the global error status and the supplied pointer. */ if ( !astOK || ! text ) return result; /* Does the string begin with an escape sequence? */ if( astFindEscape( text, &type, &value, &nc ) ){ result = 1; /* If not, there must be an escape sequence later in the string if the number of characters skipped by the above call to astFindEscape is less than the length of the string. */ } else if( nc < strlen( text ) ) { result = 1; } /* Return the result. */ return result; } static int IdFind( int id, int nax, int *id1, int *id2, int *id3, int *status ) { /* * Name: * IdFind * Purpose: * Find the numerical identifiers to use for a given identifier. * Type: * Private function. * Synopsis: * #include "plot.h" * int IdFind( int id, int nax, int *id1, int *id2, int *id3, int *status ) * Class Membership: * Plot member function. * Description: * The supplied integer should be a numerical identifier for a * graphical element of a plot (AST__MARKS_ID, AST__CURVES_ID, etc), or a * "psuedo-identifier" which represents two other genuine identifiers. * If the supplied value is a genuine identifier then it is returned * in *id1, and *id2 is returned equal to -1. If the supplied value * is a pseudo-identifier then the two corresponding genuine * identifiers are returned in *id1 and *id2 * For instance, if "id" is AST__AXIS1_ID (a genuine id), then *id1 is * returned equal to AST__AXIS1_ID and *id2 is returned equal to -1. If * "id" is AST__AXES_ID (a pseudo-identifier), then *id1 is returned equal * to AST__AXIS1_ID and *id2 is returned equal to AST__AXIS2_ID. * Genuine identifiers all have values which are less than the value * of AST__NPID. Pseudo-identifiers have values which are greater than * or equal to the value of AST__NPID. * Parameters: * id * The supplied identifier (genuine or pseudo). * nax * The number of axes spanning graphics space (2 or 3). * id1 * Pointer to the int at which to return the first genuine * identifier corresponding to "id". * id2 * Pointer to the int at which to return the second genuine * identifier corresponding to "id" (or -1 if "id" is a genuine * identifier). * id3 * Pointer to the int at which to return the third genuine * identifier corresponding to "id" (or -1 if "id" has no third * genuine identifier). * status * Pointer to the inherited status variable. * Returned Value: * The number of genuine identifiers corresponding to the supplied * (possibly Pseudo-) identifier. This will be in the range 1 to 3. */ /* Local Variables: */ int ret; /* Initialise returned values. */ *id1 = id; *id2 = -1; *id3 = -1; ret = 0; /* Check the local error status. */ if ( !astOK ) return ret; /* Assume a genuine identifier was supplied. */ ret = 1; /* Check against all known pseudo-identifier. */ if( id == AST__AXES_ID ) { ret = nax; *id1 = AST__AXIS1_ID; *id2 = AST__AXIS2_ID; if( nax == 3 ) *id3 = AST__AXIS3_ID; } else if( id == AST__GRIDLINE_ID ) { ret = nax; *id1 = AST__GRIDLINE1_ID; *id2 = AST__GRIDLINE2_ID; if( nax == 3 ) *id3 = AST__GRIDLINE3_ID; } else if( id == AST__NUMLABS_ID ) { ret = nax; *id1 = AST__NUMLAB1_ID; *id2 = AST__NUMLAB2_ID; if( nax == 3 ) *id3 = AST__NUMLAB3_ID; } else if( id == AST__TEXTLABS_ID ) { ret = nax; *id1 = AST__TEXTLAB1_ID; *id2 = AST__TEXTLAB2_ID; if( nax == 3 ) *id3 = AST__TEXTLAB3_ID; } else if( id == AST__TICKS_ID ) { ret = nax; *id1 = AST__TICKS1_ID; *id2 = AST__TICKS2_ID; if( nax == 3 ) *id3 = AST__TICKS3_ID; } else if( id >= AST__NPID ) { astError( AST__INTER, "AST internal programming error - " "function IdFind in class Plot does not yet support " "pseudo-identifier value %d", status, id ); } /* Return the answer. */ return ret; } void astInitPlotVtab_( AstPlotVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPlotVtab * Purpose: * Initialise a virtual function table for a Plot. * Type: * Protected function. * Synopsis: * #include "plot.h" * void astInitPlotVtab( AstPlotVtab *vtab, const char *name ) * Class Membership: * Plot vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Plot 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 */ AstFrameSetVtab *fset; /* Pointer to FrameSet component of Vtab */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitFrameSetVtab( (AstFrameSetVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPlot) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_init variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstFrameSetVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->BBuf = BBuf; vtab->Border = Border; vtab->BoundingBox = BoundingBox; vtab->ClearGrid = ClearGrid; vtab->ClearTol = ClearTol; vtab->Clip = Clip; vtab->CopyPlotDefaults = CopyPlotDefaults; vtab->Curve = Curve; vtab->CvBrk = CvBrk; vtab->EBuf = EBuf; vtab->GenCurve = GenCurve; vtab->GetDrawnTicks = GetDrawnTicks; vtab->GetGrid = GetGrid; vtab->GetTol = GetTol; vtab->GrfPop = GrfPop; vtab->GrfPush = GrfPush; vtab->GrfSet = GrfSet; vtab->GrfWrapper = GrfWrapper; vtab->Grid = Grid; vtab->GridLine = GridLine; vtab->Mark = Mark; vtab->Mirror = Mirror; vtab->PolyCurve = PolyCurve; vtab->RegionOutline = RegionOutline; vtab->SetGrid = SetGrid; vtab->SetTickValues = SetTickValues; vtab->SetTol = SetTol; vtab->TestGrid = TestGrid; vtab->TestTol = TestTol; vtab->Text = Text; vtab->ClearTickAll = ClearTickAll; vtab->SetTickAll = SetTickAll; vtab->GetTickAll = GetTickAll; vtab->TestTickAll = TestTickAll; vtab->ClearForceExterior = ClearForceExterior; vtab->SetForceExterior = SetForceExterior; vtab->GetForceExterior = GetForceExterior; vtab->TestForceExterior = TestForceExterior; vtab->ClearInvisible = ClearInvisible; vtab->SetInvisible = SetInvisible; vtab->GetInvisible = GetInvisible; vtab->TestInvisible = TestInvisible; vtab->ClearBorder = ClearBorder; vtab->SetBorder = SetBorder; vtab->GetBorder = GetBorder; vtab->TestBorder = TestBorder; vtab->ClearInk = ClearInk; vtab->SetInk = SetInk; vtab->GetInk = GetInk; vtab->TestInk = TestInk; vtab->ClearClipOp = ClearClipOp; vtab->SetClipOp = SetClipOp; vtab->GetClipOp = GetClipOp; vtab->TestClipOp = TestClipOp; vtab->ClearClip = ClearClip; vtab->SetClip = SetClip; vtab->GetClip = GetClip; vtab->TestClip = TestClip; vtab->ClearGrf = ClearGrf; vtab->SetGrf = SetGrf; vtab->GetGrf = GetGrf; vtab->TestGrf = TestGrf; vtab->ClearDrawTitle = ClearDrawTitle; vtab->SetDrawTitle = SetDrawTitle; vtab->GetDrawTitle = GetDrawTitle; vtab->TestDrawTitle = TestDrawTitle; vtab->ClearLabelUp = ClearLabelUp; vtab->SetLabelUp = SetLabelUp; vtab->GetLabelUp = GetLabelUp; vtab->TestLabelUp = TestLabelUp; vtab->ClearLogPlot = ClearLogPlot; vtab->SetLogPlot = SetLogPlot; vtab->GetLogPlot = GetLogPlot; vtab->TestLogPlot = TestLogPlot; vtab->ClearLogTicks = ClearLogTicks; vtab->SetLogTicks = SetLogTicks; vtab->GetLogTicks = GetLogTicks; vtab->TestLogTicks = TestLogTicks; vtab->ClearLogLabel = ClearLogLabel; vtab->SetLogLabel = SetLogLabel; vtab->GetLogLabel = GetLogLabel; vtab->TestLogLabel = TestLogLabel; vtab->ClearDrawAxes = ClearDrawAxes; vtab->SetDrawAxes = SetDrawAxes; vtab->GetDrawAxes = GetDrawAxes; vtab->TestDrawAxes = TestDrawAxes; vtab->ClearAbbrev = ClearAbbrev; vtab->SetAbbrev = SetAbbrev; vtab->GetAbbrev = GetAbbrev; vtab->TestAbbrev = TestAbbrev; vtab->ClearEscape = ClearEscape; vtab->SetEscape = SetEscape; vtab->GetEscape = GetEscape; vtab->TestEscape = TestEscape; vtab->ClearLabelling = ClearLabelling; vtab->SetLabelling = SetLabelling; vtab->GetLabelling = GetLabelling; vtab->TestLabelling = TestLabelling; vtab->ClearMajTickLen = ClearMajTickLen; vtab->SetMajTickLen = SetMajTickLen; vtab->GetMajTickLen = GetMajTickLen; vtab->TestMajTickLen = TestMajTickLen; vtab->ClearLogGap = ClearLogGap; vtab->SetLogGap = SetLogGap; vtab->GetLogGap = GetLogGap; vtab->TestLogGap = TestLogGap; vtab->ClearTitleGap = ClearTitleGap; vtab->SetTitleGap = SetTitleGap; vtab->GetTitleGap = GetTitleGap; vtab->TestTitleGap = TestTitleGap; vtab->ClearMinTickLen = ClearMinTickLen; vtab->SetMinTickLen = SetMinTickLen; vtab->GetMinTickLen = GetMinTickLen; vtab->TestMinTickLen = TestMinTickLen; vtab->ClearNumLabGap = ClearNumLabGap; vtab->SetNumLabGap = SetNumLabGap; vtab->GetNumLabGap = GetNumLabGap; vtab->TestNumLabGap = TestNumLabGap; vtab->ClearTextLabGap = ClearTextLabGap; vtab->SetTextLabGap = SetTextLabGap; vtab->GetTextLabGap = GetTextLabGap; vtab->TestTextLabGap = TestTextLabGap; vtab->ClearLabelAt = ClearLabelAt; vtab->SetLabelAt = SetLabelAt; vtab->GetLabelAt = GetLabelAt; vtab->TestLabelAt = TestLabelAt; vtab->ClearCentre = ClearCentre; vtab->SetCentre = SetCentre; vtab->GetCentre = GetCentre; vtab->TestCentre = TestCentre; vtab->ClearGap = ClearGap; vtab->SetGap = SetGap; vtab->GetGap = GetGap; vtab->TestGap = TestGap; vtab->ClearEdge = ClearEdge; vtab->SetEdge = SetEdge; vtab->GetEdge = GetEdge; vtab->TestEdge = TestEdge; vtab->ClearNumLab = ClearNumLab; vtab->SetNumLab = SetNumLab; vtab->GetNumLab = GetNumLab; vtab->TestNumLab = TestNumLab; vtab->ClearMinTick = ClearMinTick; vtab->SetMinTick = SetMinTick; vtab->GetMinTick = GetMinTick; vtab->TestMinTick = TestMinTick; vtab->ClearTextLab = ClearTextLab; vtab->SetTextLab = SetTextLab; vtab->GetTextLab = GetTextLab; vtab->TestTextLab = TestTextLab; vtab->ClearLabelUnits = ClearLabelUnits; vtab->SetLabelUnits = SetLabelUnits; vtab->GetLabelUnits = GetLabelUnits; vtab->TestLabelUnits = TestLabelUnits; vtab->ClearStyle = ClearStyle; vtab->SetStyle = SetStyle; vtab->GetStyle = GetStyle; vtab->TestStyle = TestStyle; vtab->ClearFont = ClearFont; vtab->SetFont = SetFont; vtab->GetFont = GetFont; vtab->TestFont = TestFont; vtab->ClearColour = ClearColour; vtab->SetColour = SetColour; vtab->GetColour = GetColour; vtab->TestColour = TestColour; vtab->ClearWidth = ClearWidth; vtab->SetWidth = SetWidth; vtab->GetWidth = GetWidth; vtab->TestWidth = TestWidth; vtab->ClearSize = ClearSize; vtab->SetSize = SetSize; vtab->GetSize = GetSize; vtab->TestSize = TestSize; vtab->GetGrfContext = GetGrfContext; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; fset = (AstFrameSetVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; parent_removeframe = fset->RemoveFrame; fset->RemoveFrame = RemoveFrame; /* Declare the destructor and copy constructor. */ astSetDelete( (AstObjectVtab *) vtab, Delete ); astSetCopy( (AstObjectVtab *) vtab, Copy ); /* Declare the class dump function. */ astSetDump( vtab, Dump, "Plot", "Provide facilities for 2D graphical output" ); /* 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 int Inside( int n, float *cx, float *cy, float x, float y, int *status ){ /* * Name: * Inside * Purpose: * See if a given point is inside a 2-d polygon. * Type: * Private function. * Synopsis: * #include "plot.h" * int Inside( int n, float *cx, float *cy, float x, float y, int *status ) * Class Membership: * Plot member function. * Description: * This function determines if the position given by x and y, is inside * or outside the polygon specified by the vertices given in arrays cx * and cy. * Parameters: * n * The number of vertices in the polygon. * cx * A pointer to an array holding the x coordinates at the "n" vertices. * cy * A pointer to an array holding the y coordinates at the "n" vertices. * x * The x coordinate of the test point. * y * The y coordinate of the test point. * status * Pointer to the inherited status variable. * Returned Value: * A boolean flag indicating if the test point is inside the polygon. * Notes: * - The algorithm used only works for convex polygons. * - The polygon is closed by joining the last vertex to the first * vertex. * - Zero is returned if an error has occurred. */ /* Local Variables: */ int i; /* Index of the current vertex */ int j; /* Index of the next vertex */ int ret; /* Is the test point inside the polygon? */ int sgn; /* Which side of the first edge is the test point? */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise the returned value to indicate that the point is inside the box. */ ret = 1; /* Get the sign of the angle between the vector joining vertex 1 to vertex 0, and the vector joining the test point to vertex zero. */ if( ( cx[ 1 ] - cx[ 0 ] )*( y - cy[ 0 ] ) > ( x - cx[ 0 ] )*( cy[ 1 ] - cy[ 0 ] ) ){ sgn = 1; } else { sgn = -1; } /* Check that the remaining test point is on the same side of the remaining sides. */ for( i = 1; i < n; i++ ){ /* Get the index of the next vertex, joining the last vertex up with vertex zero. */ j = i + 1; if( j >= n ) j -= n; /* Get the sign of the angle between the vector joining vertex j to vertex i, and the vector joining the test point to vertex i. If the sign is opposite to that found for vertex zero, then the test point is outside the polygon. Break out of the loop if this is the case. */ if( ( cx[ j ] - cx[ i ] )*( y - cy[ i ] ) > ( x - cx[ i ] )*( cy[ j ] - cy[ i ] ) ){ if( sgn == -1 ) { ret = 0; break; } } else { if( sgn == 1 ) { ret = 0; break; } } } /* Return the answer. */ return ret; } static void InterpEscape( AstPlot *this, int type, double value, float *x, float *y, float ux, float uy, float rx, float ry, const char *just, float *rise, double nsize, double nstyle, double nwidth, double ncol, double nfont, const char *method, const char *class, int *status ){ /* * Name: * InterpEscape * Purpose: * Prepare things for drawing the next part of a string which includes * graphics escape sequences. * Synopsis: * #include "plot.h" * void InterpEscape( AstPlot *this, int type, double value, float *x, * float *y, float ux, float uy, float rx, float ry, * const char *just, float *rise, double nsize, * double nstyle, double nwidth, double ncol, * double nfont, const char *method, const char *class, int *status ) * Description: * This function modifies the current graphics attributes, the supplied * reference position, in preparation for drawing another sub-string * from a string containing graphics escape sequences. The type and * value of an escape sequence preceding the substring is supplied. * Note, this function ignored escape sequences which represent an * escaped percent sign. Such escape sequences are drawn as normal * text by the claling function. * Parameters: * this * The plot. * type * The type of escape sequence. Each type is identified by a symbolic * constant defined in grf.h. * value * The value associated with the escape sequence. All usable values * will be positive. A value of -1 shold be supplied if the attribute * identified by "type" should be reset to its "normal" value (as * established using the astGAttr function, etc). * x * Pointer to a double holding the x coordinate at the concatenation * point. This will be modified on exit if the escape sequence * requires it. * y * Pointer to a double holding the y coordinate at the concatenation * point. This will be modified on exit if the escape sequence * requires it. * ux * The x component of the up-vector for the text, in graphics coords. * The length of this vector should be equal to the height of normal * text drawn with this up-vector. * uy * The y component of the up-vector for the text. See "ux". * rx * The x component of the right-vector for the text. The length of this * vector should be equal to the height of normal text drawn with the * supplied up-vector. * ry * The y component of the right-vector for the text. see "rx". * just * The justification being used for each substring. * rise * Pointer to a float holding the height of the current baseline * above the normal baseline, given as a percentage of the height of * normal text. May be negative for sub-scripts. May be modified on * exit if the escape sequence effects the height of the baseline. * nsize * The size of normal text. * nstyle * The style of normal text. * nwidth * The width of normal text. * ncol * The colour of normal text. * nfont * The font of normal text. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ float new_rise; float t1, t2; /* Check the global error status. */ if ( !astOK ) return; /* Type GRF__ESSUP: Move the concatenation point in the up direction, and update the current baseline height. If the value is -1, then reset the baseline to its normal height. */ if( type == GRF__ESSUP ) { if( value > 0 ) { *x += 0.01*ux*( value - *rise ); *y += 0.01*uy*( value - *rise ); *rise = value; } else { *x -= 0.01*ux*(*rise); *y -= 0.01*uy*(*rise); *rise = 0; } /* Type GRF__ESSUB: Move the concatenation point in the down direction, and update the current baseline height. If the value is -1, then reset the baseline to its normal height. */ } else if( type == GRF__ESSUB ) { if( value > 0 ) { *x -= 0.01*ux*( value + *rise ); *y -= 0.01*uy*( value + *rise ); *rise = -value; } else { *x -= 0.01*ux*(*rise); *y -= 0.01*uy*(*rise); *rise = 0; } /* Type GRF__ESGAP: Move the concatenation point to the right. */ } else if( type == GRF__ESGAP ) { *x += 0.01*rx*value; *y += 0.01*ry*value; /* Type GRF__ESBAC: Move the concatenation point to the left. */ } else if( type == GRF__ESBAC ) { *x -= 0.01*rx*value; *y -= 0.01*ry*value; /* Remember the current horizontal position. */ } else if( type == GRF__ESH ) { this->hmarkx = *x; this->hmarky = *y; /* Go to the previously stored horizontal position. */ } else if( type == GRF__ESG ) { if( this->hmarkx != FLT_MAX && this->hmarky != FLT_MAX ) { t1 = ( *x - this->hmarkx )*rx + ( *y - this->hmarky )*ry; t2 = rx*rx + ry*ry; *x -= rx*t1/t2; *y -= ry*t1/t2; } /* Type GRF__ESSIZ: Change the text size. */ } else if( type == GRF__ESSIZ ) { if( value < 0 ) value = 100.0; GAttr( this, GRF__SIZE, 0.01*value*nsize, NULL, GRF__TEXT, method, class, status ); /* Type GRF__ESWID: Change the text width. */ } else if( type == GRF__ESWID ) { if( value < 0 ) value = 100.0; GAttr( this, GRF__WIDTH, 0.01*value*nwidth, NULL, GRF__TEXT, method, class, status ); /* Type GRF__ESFON: Change the text font. */ } else if( type == GRF__ESFON ) { if( value < 0 ) value = nfont; GAttr( this, GRF__FONT, value, NULL, GRF__TEXT, method, class, status ); /* Type GRF__ESCOL: Change the text colour. */ } else if( type == GRF__ESCOL ) { if( value < 0 ) value = ncol; GAttr( this, GRF__COLOUR, value, NULL, GRF__TEXT, method, class, status ); /* Type GRF__ESSTY: Change the text style. */ } else if( type == GRF__ESSTY ) { if( value < 0 ) value = nstyle; GAttr( this, GRF__STYLE, value, NULL, GRF__TEXT, method, class, status ); /* Type GRF__ESPSH: Push current attributes onto a stack. */ } else if( type == GRF__ESPSH ) { PushGat( this, *rise, method, class, status ); /* Type GRF__ESSTY: Reset everything to normal. */ } else if( type == GRF__ESPOP ) { if( !PopGat( this, &new_rise, method, class, status ) ) { new_rise = 0.0; GAttr( this, GRF__SIZE, nsize, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__WIDTH, nwidth, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__COLOUR, ncol, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__FONT, nfont, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__STYLE, nstyle, NULL, GRF__TEXT, method, class, status ); } *x -= 0.01*ux*( *rise - new_rise ); *y -= 0.01*uy*( *rise - new_rise ); *rise = new_rise; } } static int IsASkyAxis( AstFrame *frm, int axis, int *status ) { /* * Name: * IsASkyAxis * Purpose: * Checks if a specified axis of the supplied Frame is a SkyAxis. * Type: * Private function. * Synopsis: * #include "plot.h" * int IsASkyAxis( AstFrame *frm, int axis, int *status ) * Class Membership: * Plot member function. * Description: * This function checks if if a specified axis of the supplied Frame is * a SkyAxis. * Parameters: * frm * The Frame. * axis * The zero-based axis index. * status * Pointer to the inherited status variable. * Returned Value: * A boolean flag indicating if the axis is a SkyAxis. */ /* Local Variables: */ int ret; AstAxis *ax; /* initialise */ ret = 0; /* Check the global status. */ if( !astOK ) return ret; /* Extract the required axis from the Frame and test if it is a SkyAxis. Then free the axis memory. */ ax = astGetAxis( frm, axis ); ret = astIsASkyAxis( ax ); ax = astAnnul( ax ); /* Return the answer. */ return ret; } static int IsASkyFrame( AstObject *obj, int *status ) { /* * Name: * IsASkyFrame * Purpose: * Checks if the supplied Object ca be treated as a SkyFrame. * Type: * Private function. * Synopsis: * #include "plot.h" * int IsASkyFrame( AstObject *obj, int *status ) * Class Membership: * Plot member function. * Description: * This function checks if the supplied Object is a SkyFrame or a * FrameSet which has a SkyFrame as its current Frame. * Parameters: * obj * The object. * status * Pointer to the inherited status variable. * Returned Value: * A boolean flag indicating if the Object can be treated as SkyFrame. */ /* Local Variables: */ int ret; AstFrame *frm; /* initialise */ ret = 0; /* Check the global status. */ if( !astOK ) return ret; /* If the Object is a SkyFrame, return 1. */ if( astIsASkyFrame( obj ) ) { ret = 1; /* If the Object is a FrameSet, check its current Frame recursively, using this method. */ } else if( astIsAFrameSet( obj ) ) { frm = astGetFrame( (AstFrameSet *) obj, AST__CURRENT ); ret = IsASkyFrame( (AstObject *) frm, status ); frm = astAnnul( frm ); } /* Return the answer. */ return ret; } static const char *JustMB( AstPlot *this, int esc, const char *text, float *x, float *y, float upx, float upy, const char *just, float uxu, float uyu, float rxu, float ryu, float *x0, float *y0, const char *method, const char *class, int *status ){ /* * Name: * JustMB * Purpose: * Modifies a "M" vertical reference point to be a "B" reference point, * if necessary. * Synopsis: * #include "plot.h" * const char *JustMB( AstPlot *this, int esc, const char *text, float *x, * float *y, float upx, float upy, const char *just, * float uxu, float uyu, float rxu, float ryu, * float *x0, float *y0, const char *method, * const char *class, int *status ) * Description: * This function is used to modify the reference point and justification * of a string by converting the vertical "M" justification option (which * indicates that the reference point refers to the bottom of the * bounding box) into a corresponding "B" option (which indicates that * the reference point refers to the text baseline). The reference * point is modified accordingly. * * This is only done if the grf module does not support "M" * justification. Otherwise, the supplied justification string and * reference point coordinates are returned unchanged. * Parameters: * this * The plot. * esc * Should escape sequences be interpreted? They will be printed * literally otherwise. * text * Pointer to a null-terminated character string to be displayed. * x * Pointer to a double holding the x coordinate at the reference * point. This is modified on exit if the supplied "just" string * indicates that the supplied value refers to the bottom of the * bounding box, and the grf module does not support such * justification. In this case, the returned value is a point on * the baseline of the text which would result in the bottom of * the bounding box being at the supplied position. * y * Pointer to a double holding the y coordinate at the reference * point. This is modified on exit if the supplied "just" string * indicates that the supplied value refers to the bottom of the * bounding box, and the grf module does not support such * justification. In this case, the returned value is a point on * the baseline of the text which would result in the bottom of * the bounding box being at the supplied position. * upx * The x component of the up-vector for the text. Positive values * always refer to displacements from left to right on the screen, * even if the graphics x axis increases in the opposite sense. * upy * The y component of the up-vector for the text. Positive values * always refer to displacements from left to right on the screen, * even if the graphics y axis increases in the opposite sense. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", 'B' for "baseline" or "M" for "bottom", and * specifies the vertical location of the reference position. Note, * "baseline" corresponds to the base-line of normal text,and "M" * corresponds to the bottom of the bounding box. Some characters * (eg "y", "g", "p", etc) and sub-scripts descend below the base-line. * The second character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * uxu * X component of normalised up-vector, in graphics coords. * uyu * Y component of normalised up-vector, in graphics coords. * rxu * X component of normalised right-vector, in graphics coords. * ryu * Y component of normalised right-vector, in graphics coords. * x0 * Address of a float at which to return the x coordinate at the * left end of the baseline of the whole string. * y0 * Address of a float at which to return the y coordinate at the * left end of the baseline of the whole string. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated string which contains the * justification to use in future. This pointer should be freed using * astFree when no longer needed. This string will contain a full * upper-case justification string which can be used by the current * grf module. * Notes; * - NULL is returned if an error has occurred. */ /* Local Variables: */ char cc; float drop; float dx; float dy; float f; float height; float width; float xbn[ 4 ]; float ybn[ 4 ]; int called; char *result; /* Check inherited status */ if( !astOK ) return NULL; /* Allocate memory for the returned string. */ result = astMalloc( sizeof( char )*3 ); if( astOK ) { /* Fill in any missing parts of the justification string. */ if( just ){ cc = toupper( just[ 0 ] ); result[ 0 ] = ( cc == 'T' || cc == 'C' || cc == 'B' || cc == 'M' ) ? cc : 'C'; cc = toupper( just[ 1 ] ); result[ 1 ] = ( cc == 'L' || cc == 'C' || cc == 'R' ) ? cc : 'C'; } else { result[ 0 ] = 'C'; result[ 1 ] = 'C'; } result[ 2 ] = 0; /* Indicate that DrawText has not been called. */ called = 0; /* The justfication need not be changed unless the requested vertical justification is "bottom" (m), AND the grf module does not support "M" justification. */ if( ( result[ 0 ] == 'M' ) && !GCap( this, GRF__MJUST, 1, status ) ){ /* Find the bounding box which would result from putting the left end of the baseline at the specified position. */ DrawText( this, 0, esc, text, *x, *y, "BL", upx, upy, xbn, ybn, &drop, method, class, status ); /* Indicate that DrawText has not been called. */ called = 1; /* Get the vector from the bottom left corner of the bounding box to the reference point (on the base-line), and add this vector on to the reference point. */ *x += *x - xbn[ 0 ]; *y += *y - ybn[ 0 ]; /* Modified the returned justification string. */ result[ 0 ] = 'B'; } /* If the returned justification is "BL", then the left end of the baseline is just the returned reference point. */ if( result[ 0 ] == 'B' && result[ 1 ] == 'L' ) { *x0 = *x; *y0 = *y; /* Otherwise, we work out the coords of the left end of the baseline from the values returned by DrawText above. Call DrawText now if it was not called above. */ } else { if( ! called ) { DrawText( this, 0, esc, text, *x, *y, "BL", upx, upy, xbn, ybn, &drop, method, class, status ); } /* Find the height and width of the bounding box. */ dx = xbn[ 0 ] - xbn[ 3 ]; dy = ybn[ 0 ] - ybn[ 3 ]; width = sqrt( dx*dx + dy*dy ); dx = xbn[ 0 ] - xbn[ 1 ]; dy = ybn[ 0 ] - ybn[ 1 ]; height = sqrt( dx*dx + dy*dy ); /* For "C" and "R" horizontal justification we first need to move the returned reference point left by 0.5 or 1.0 times the width of the whole string respectively. */ if( result[ 1 ] == 'C' ) { f = 0.5; } else if( result[ 1 ] == 'R' ) { f = 1.0; } else { f = 0.0; } f *= width; *x0 = *x - f*rxu; *y0 = *y - f*ryu; /* Unless the vertical justification is "B", we also need to move the concatenation point vertically to put it on the baseline. */ if( result[ 0 ] == 'T' ) { f = height - drop; } else if( result[ 0 ] == 'C' ) { f = 0.5*height - drop; } else if( result[ 0 ] == 'M' ) { f = -drop; } else { f = 0.0; } *x0 -= f*uxu; *y0 -= f*uyu; } } /* Return the result. */ return result; } static int Labelat( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, double *labelat, const char *method, const char *class, int *status ){ /* * * Name: * Labelat * Purpose: * Determine the other axis value at which to place interior labels * and tick marks. * Type: * Private function. * Synopsis: * #include "plot.h" * int Labelat( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, * double *labelat, const char *method, const char *class ) * Class Membership: * Plot member function. * Description: * If tick marks and labels are to be placed within the plotting area, * the tick values stored in "grid" determine their position on one * axis, and their position on the other axis is determined by this * function. If a value has been set for the "LabelAt" attribute, then * it is used, otherwise the "other axis" value on the longest curve * parallel to the "other axis" is used (although the curve "other axis * = zero" is used if it passes through the plotting area and is not too * short). The effective length assigned to each curve is reduced in * proportion to the number of tick marks which are close to the edge * of the plotting area. * * A flag is returned indicating if the two axes appear to be * independent, in which case there is nothing to be gained by using * interior labelling. * Parameters: * this * A pointer to the Plot. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick values on the axis. See function GridLines. * cdata * A pointer to an array of two AstPlotCurveData pointers (one for each axis), * each pointing to an array of AstPlotCurveData structure (one for each * major tick value on the axis), holding information about breaks * in the curves drawn to mark the major tick values. See function * DrawGrid. * labelat * A pointer to a 2 element array in which to store the constant axis * values at which tick marks are put. Element 0 is returned holding * the axis 1 value at which tick marks for axis 0 are placed. Element * 1 is returned holding the axis 0 value at which tick marks for axis * 1 are placed. * flags * A pointer to a 2 element array. Each element is a flag which is * returned non-zero if the corresponding axis * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * Returned Value: * Zero if and only if the lines of constant axis value are all the * same length for all tick marks on either axis. If this is so, using * interior labelling will not enable any more major ticks to be * drawn, and so there is no reason to switch to interior labelling (unless * the user has specifically requested interior labelling). * Notes: * - This function assumes the current Frame of the Plot is 2 * dimensional, and it should not be called if this is not the case. */ /* Local Variables: */ AstMapping *mapping; /* Mapping from graphics to physical coords */ AstPointSet *pset2; /* Pointset for graphical tick positions */ AstPointSet *pset[ 2 ];/* Pointsets for physical tick positions */ AstPlotCurveData *cdt; /* Pointer to the AstPlotCurveData for the next tick */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ double **ptr2; /* Pointers to graphics pointset data */ double *ptr1[ 2 ]; /* Pointers to physical pointset data */ double *tvals[ 2 ]; /* Pointers to arrays of other axis values */ double *value; /* Current tick value */ double efflen; /* Effective length of current curve */ double lim; /* Largest insignificant axis value */ double margin; /* Width of margin around plotting area */ double maxlen; /* Effective length of longest curve */ double minlen; /* Effective length of shortest (non-zero) curve */ double x; /* Tick X value */ double xhi; /* Upper limit on acceptable X range */ double xlo; /* Lower limit on acceptable X range */ double y; /* Tick Y value */ double yhi; /* Upper limit on acceptable Y range */ double ylo; /* Lower limit on acceptable Y range */ double zerolen; /* Effective length of curve for other axis = 0.0 */ int axis; /* Current axis index */ int i; /* Tick index for this axis */ int nin; /* No. of counted ticks */ int result; /* Does interior labelling allow more ticks to be drawn? */ int tick; /* Tick index */ /* Check the global status. */ if( !astOK ) return 0; /* Initialise */ result = 1; /* Create two PointSets to hold a set of tick mark positions along each axis. The values on "axis" will be taken from the info structure. For each axis create an array to hold values for the "other" axis. */ for( axis = 0; axis < 2; axis++ ){ info = grid[ axis ]; pset[ axis ] = astPointSet( info->nmajor, 2, "", status ); tvals[ axis ] = (double *) astMalloc( sizeof(double)*(size_t)(info->nmajor) ); } /* Get the mapping from Base (graphics) frame the Current (physical) */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Get the bounds of the area in which tick marks must occur to be counted. This is the total plotting area minus a 5% margin at each edge. */ margin = 0.05*( this->xhi - this->xlo ); xlo = this->xlo + margin; xhi = this->xhi - margin; margin = 0.05*( this->yhi - this->ylo ); ylo = this->ylo + margin; yhi = this->yhi - margin; /* Do each axis. */ for( axis = 0; axis < 2 && astOK; axis++ ){ /* Find the longest and shortest curves parallel to the axis being labelled. Also find the length of the curve which passes through the origin of the other axis which is within the plotting area. We need to do this even if LabelAt has been set since we need to calculate the returned flag. */ /* Store pointers to the arrays holding tick mark physical coordinates, and set these in the PointSet. */ ptr1[ axis ] = grid[ axis ]->ticks; ptr1[ 1 - axis ] = tvals[ axis ]; astSetPoints( pset[ axis ], ptr1 ); /* Get a pointer to the structure containing information describing the positions of the major tick marks along the other axis. */ info = grid[ 1 - axis ]; /* Get a pointer to the other axis value at the first other axis major tick mark. */ value = info->ticks; /* Get a limit on absolute magnitude for an axis value to be consider equal to zero. */ lim = 1.0E-6*fabs( value[ 1 ] - value [ 0 ] ); /* Get a pointer to the structure containing information describing the breaks in the curve which passes through the first major tick mark. */ cdt = cdata[ 1 - axis ]; /* Initialise the effective length of the longest and shortest curves, and the curve passing through the origin. */ maxlen = -1.0; minlen = DBL_MAX; zerolen = 0.0; labelat[ axis ] = AST__BAD; /* Loop round each of the major tick marks on the other axis. */ for( tick = 0; tick < info->nmajor && astOK; tick++ ){ /* Fill the array of other axis values with the current other axis value. */ for( i = 0; i < grid[ axis ]->nmajor; i++ ){ tvals[ axis ][ i ] = *value; } /* Transform the tick positions from the current frame (i.e. physical coordinates) to the base frame (i.e. graphics coordinates) using the inverse Mapping. */ pset2 = Trans( this, NULL, mapping, pset[ axis ], 0, NULL, 0, method, class, status ); /* Get pointers to the graphics coordinates. */ ptr2 = astGetPoints( pset2 ); if( astOK ) { /* Count the number of graphics positions which are well within the plotting area. */ nin = 0; for( i = 0; i < grid[ axis ]->nmajor; i++ ){ x = ptr2[ 0 ][ i ]; y = ptr2[ 1 ][ i ]; if( x != AST__BAD && x > xlo && x < xhi && y != AST__BAD && y > ylo && y < yhi ) nin++; } /* Find the effective length of this curve.*/ efflen = sqrt( (float) nin )*cdt->length; /* If the curve through this tick mark has a greater effective length than any other found so far, record it. */ if( efflen > maxlen ){ maxlen = efflen; labelat[ axis ] = *value; } /* If the curve through this tick mark has a smaller non-zero effective length than any other found so far, record it. */ if( efflen < minlen && efflen > 0.0 ) minlen = efflen; /* If this tick mark is at the origin, note the effective length. */ if( fabs( *value ) <= lim ) zerolen = efflen; /* Get a pointer to the curve through the next major tick mark. */ cdt++; /* Get a pointer to the axis value at the next major tick mark. */ value++; } /* Free resources. */ pset2 = astAnnul( pset2 ); } /* Use the curve through the origin unless it is significantly shorter than the longest curve. */ if( zerolen > 0.4*maxlen ) labelat[ axis ] = 0.0; /* Return a flag if the lengths of the shortest and longest curves are nearly equal. */ if( ( maxlen - minlen )/( maxlen + minlen ) < 1.0E-5 ) result = 0; /* If the LabelAt attribute has been set, use it in preference to the value found above. */ if( astTestLabelAt( this, axis ) ){ labelat[ axis ] = astGetLabelAt( this, axis ); } } /* Release resources. */ for( axis = 0; axis < 2; axis++ ){ if( pset[ axis ] ) pset[ axis ] = astAnnul( pset[ axis ] ); if( tvals[ axis ] ) tvals[ axis ] = (double *) astFree( (void *) tvals[ axis ] ); } mapping = astAnnul( mapping ); /* Return. */ return result; } static void Labels( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, double *gap, double *labelat, const char *method, const char *class, int *status ){ /* * * Name: * Labels * Purpose: * Draw numerical axis labels for a 2-D annotated coordinate grid. * Type: * Private function. * Synopsis: * #include "plot.h" * void Labels( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, * double *gap, double *labelat, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * The policy for placing labels for the major tick values is broadly as * follows: if possible, labels for a given physical axis are placed on * one edge of the plotting area, at the place where the curve for a * major tick value crosses the edge. If very few of the curves cross * the edge, then the label for a curve is placed at the intersection * of that curve with the longest of the curves representing the major * tick values on the other axis. * Parameters: * this * A pointer to the Plot. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick values on the axis. See function GridLines. * cdata * A pointer to an array of two AstPlotCurveData pointers (one for each axis), * each pointing to an array of AstPlotCurveData structure (one for each * major tick value on the axis), holding information about breaks * in the curves drawn to mark the major tick values. See function * DrawGrid. * gap * Pointer to array of two values holding the gap between major * tick values on the two axes. * labelat * A pointer to a 2 element array holding the constant axis * values at which tick marks are put. Element 0 should hold * the axis 1 value at which tick marks for axis 0 are placed. Element * 1 should hold the axis 0 value at which tick marks for axis * 1 are placed. If labels are to be placed round the edges of the * plotting zone instead of within the plotting zone, then values of * AST__BAD should be supplied. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - This function assumes the current Frame of the Plot is 2 * dimensional, and it should not be called if this is not the case. */ /* Local Variables: */ AstFrame *frame; /* Pointer to current Frame */ AstMapping *mapping; /* Pointer to graphics->physical Mapping */ AstPointSet *pset1; /* Pointer to PointSet holding physical coords. */ AstPointSet *pset2; /* Pointer to PointSet holding graphics coords. */ AstPlotCurveData *cdt; /* Pointer to the AstPlotCurveData for the next tick */ LabelList *labellist; /* Pointer to list of labels to be plotted */ LabelList *ll; /* Pointer to next label to be plotted */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ char just_buf[3]; /* Buffer to hold a justification string */ const char *just; /* Justification string */ const char *text; /* Pointer to label text */ double *used; /* Pointer to list of used label values */ double *value; /* Current tick value */ double diff; /* Difference between adjacent major tick marks */ double dx; /* Text base-line X component */ double dy; /* Text base-line Y component */ double gx; /* Reference position graphics X coord. */ double gy; /* Reference position graphics Y coord. */ double mindim; /* Shortest dimension of plotting area */ double offx; /* X component of offset vector */ double offy; /* Y component of offset vector */ double rlen; /* Length of perpendicular vector */ double rx; /* X comp of vector perpendicular to (dx,dy) */ double ry; /* Y comp of vector perpendicular to (dx,dy) */ double sin45; /* Sine of 45 degrees */ double txtgap; /* Absolute gap between labels and edges */ double upx; /* Text up-vector X component */ double upy; /* Text up-vector Y component */ double val[ 2 ]; /* Physical coordinates */ float *box; /* Pointer to array of label bounding boxes */ float alpha; /* Factor to convert graphics X to equal scaled X */ float beta; /* Factor to convert graphics Y to equal scaled Y */ int axis; /* Current axis index */ int esc; /* Interpret escape sequences? */ int flag; /* Flag indicating which way the base-vector points */ int iused; /* Index into list of used axis values */ int last; /* The index of the last tick to use */ int logticks; /* ARe major ticks spaced logarithmically? */ int nlab; /* The number of labels to be plotted */ int nused; /* Number of used axis values */ int t0; /* Index of central tick */ int tick; /* Current tick index */ int tinc; /* Increment between ticks */ int upfree; /* Are we free to change the up-vector? */ int gelid; /* ID for next graphical element to be drawn */ /* Check the global status. */ if( !astOK ) return; /* See if escape sequences in text strings are to be interpreted */ esc = astGetEscape( this ); /* Empty the list of bounding boxes kept by the Overlap function. */ (void) Overlap( this, 0, 0, NULL, 0.0, 0.0, NULL, 0.0, 0.0, NULL, method, class, status ); /* If required, draw the labels around the edges of the plotting area. */ if( labelat[ 0 ] == AST__BAD || labelat[ 1 ] == AST__BAD ){ (void) EdgeLabels( this, 1, grid, cdata, 1, method, class, status ); /* Otherwise, draw labels within the interior of the plotting area. */ } else { /* Find the scale factors for the two axes which scale graphics coordinates into a "standard" equal scaled coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, 3) Y values increase from bottom to top. */ GScales( this, &alpha, &beta, method, class, status ); /* Get the minimum dimension of the plotting area in equal scaled coords. */ mindim = astMIN( fabs( alpha*(this->xhi - this->xlo) ), fabs( beta*(this->yhi - this->ylo) ) ); /* Store a value for the sine of 45 degrees. */ sin45 = 1.0/sqrt( 2.0 ); /* Initialise the pointer to the memory holding the bounding boxes for all labels (used by function Overlap). */ box = NULL; /* Get a pointer to the current Frame in the Plot. */ frame = astGetFrame( this, AST__CURRENT ); /* Get a pointer to the mapping form the base Frame to the current Frame in the Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Initialize the id value for graphical element being drawn. */ gelid = AST__NUMLAB1_ID; /* Do each axis. */ for( axis = 0; axis < 2; axis++ ){ /* See of major ticks are spaced logarithmically on this axis. */ logticks = astGetLogTicks( this, axis ); /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, gelid, 1, GRF__TEXT, method, class ); /* Get a pointer to the structure containing information describing the positions of the major tick marks along this axis. */ info = grid[ axis ]; /* Only progress if there are some labels stored within the structure. */ if( info->labels ) { /* Initialise the pointer to the list of text strings to be drawn. */ labellist = NULL; nlab = 0; /* See if numerical labels are always to be drawn horizontal. If so, set a flag and initialise a vertical up-vector. */ if( astGetLabelUp( this, axis ) ){ upfree = 0; upx = 0.0; upy = 1.0; /* Otherwise, clear the flag and indicate that we do not yet have an up-vector. */ } else { upfree = 1; upx = AST__BAD; upy = AST__BAD; } /* Indicate that the tangent vector to the other axis is not yet known. */ dx = AST__BAD; dy = AST__BAD; gx = AST__BAD; gy = AST__BAD; /* Store the gap to put next to the label text. This is in equal scaled coords, not graphics coords. */ txtgap = astGetNumLabGap( this, axis )*mindim; /* Get a pointer to the structure containing information describing the breaks in the curve which passes through the first major tick mark. */ cdt = cdata[ axis ]; /* Get a pointer to the axis value at the first major tick mark. */ value = info->ticks; /* Initialise pointers to two PointSets which will be created and used within function GVec. */ pset1 = NULL; pset2 = NULL; /* Get memory to hold the axis values at which labels have been put. */ used = (double *) astMalloc( sizeof(double)*(size_t)info->nmajor ); nused = 0; /* The tick marks are done in two batches, each batch working out from the middle. This is done because there may be extra tick marks outside the normal ranges at the extremes, and these should not be given the priority caused by doing them first. Store the mid-tick index, the current tick index, and the increment between ticks. The ticks from the middle up to the highest index are done first. */ t0 = info->nmajor/2; tick = t0 - 1; tinc = 1; /* Loop round until all ticks have been done. */ last = info->nmajor - 1; while( (tick += tinc) >= 0 && astOK ){ /* If we have done the highest tick index, start again at the tick just below middle, and work done towards index zero. */ if( tick == info->nmajor ){ tick = t0 - 1; tinc = -1; } /* Store the reference position for the label . */ val[ axis ] = value[ tick ]; val[ 1 - axis ] = labelat[ axis ]; /* Store the difference between this tick and the next. */ if( logticks ) { diff = value[ tick ]*( gap[ axis ] - 1.0 ); } else { diff = gap[ axis ]; } /* See if this axis value has already been used. */ for( iused = 0; iused < nused; iused++ ){ if( fabs( val[ axis ] - used[ iused ] ) < 1.0E-3*diff ) break; } /* If the axis value has already been used, don't use it again. */ if( iused >= nused || nused == 0 ){ used[ nused++ ] = val[ axis ]; /* We now need to decide where to put the reference point for the text string, and what justification to use. Assuming that NumLabGap is +ve, the labels are drawn on the left hand side of the axis as seen by someone moving along the axis in the positive direction, with an up-vector which is normal to the axis tangent. First, find the graphics coordinates at the point being labelled, and the unit tangent-vector parallel to the axis being labelled. If the tangent vector is not defined, then the tangent vector used for the previous label is re-used. This unit tangent vector is expressed in graphics coords. */ GVec( this, mapping, val, axis, 0.01*diff, &pset1, &pset2, &gx, &gy, &dx, &dy, &flag, method, class, status ); /* If we now have a tangent vector and good graphics coordinates for the label's reference position... */ if( dx != AST__BAD && dy != AST__BAD && gx != AST__BAD && gy != AST__BAD ){ /* Convert the unit tangent vector from graphics coords to equal-scaled coords. */ dx *= alpha; dy *= beta; /* Rotate through 90 degrees to get a vector perpendicular to the axis in equal scaled coords. This vector points to the left as you move along the physical axis in the positive direction. Find its length. */ rx = -dy; ry = dx; rlen = sqrt( rx*rx + ry*ry ); /* The reference position for the text is displaced away from the reference position normal to the axis on the left hand side by the "txtgap" value. */ offx = rx*txtgap/rlen; offy = ry*txtgap/rlen; gx += offx/alpha; gy += offy/beta; /* The up-vector and justification for the text depends on whether or not the up-vector is free to rotate. If it is free, the up-vector is chosen so that the text is not upside-down. Note, the up-vector is specified in the equally scaled coordinate system. */ if( upfree ){ if( dx < -0.01*fabs( alpha ) ){ upx = -rx; upy = -ry; just = ( txtgap < 0.0 )? "BC" : "TC"; } else { upx = rx; upy = ry; just = ( txtgap < 0.0 )? "TC" : "BC"; } if( txtgap == 0.0 ) just = "CC"; /* If the up vector is required to be vertical, a system is used which tries to put the centre of the text string on or near the offset vector. */ } else { upx = 0.0; upy = 1.0; if( offy > fabs(txtgap)*sin45 ){ just_buf[0] = 'B'; } else if( offy < -fabs(txtgap)*sin45 ){ just_buf[0] = 'T'; } else { just_buf[0] = 'C'; } if( txtgap == 0.0 ) just_buf[0] = 'C'; if( offx < -fabs(txtgap)*sin45 ){ just_buf[1] = 'R'; } else if( offx > fabs(txtgap)*sin45 ){ just_buf[1] = 'L'; } else { just_buf[1] = 'C'; } if( txtgap == 0.0 ) just_buf[1] = 'C'; just_buf[2] = 0; just = just_buf; } /* Get the label text. */ text = (info->labels)[ tick ]; if( text ){ /* Check that the reference position is within the plotting area. If so, add it to the list of labels to be drawn. */ if( gx >= this->xlo && gx <= this->xhi && gy >= this->ylo && gy <= this->yhi ){ labellist = (LabelList *) astGrow( (void *) labellist, nlab + 1, sizeof(LabelList) ); if ( astOK ) { (labellist + nlab)->index = tick; (labellist + nlab)->text = (char *) astStore( NULL, (void *) text, strlen(text) + 1 ); (labellist + nlab)->x = gx; (labellist + nlab)->y = gy; (labellist + nlab)->just = (char *) astStore( NULL, (void *) just, strlen(just) + 1 ); (labellist + nlab)->upx = upx; (labellist + nlab)->upy = upy; (labellist + nlab)->val = val[ axis ]; nlab++; } else { break; } } } } } } /* If any labels were stored, draw the text strings, and then release the memory used to hold the text, etc. */ if( nlab > 0 ) { PlotLabels( this, esc, frame, axis, labellist, info->fmt, nlab, &box, method, class, status ); ll = labellist; for( tick = 0; tick < nlab; tick ++ ) { ll->text = (char *) astFree( (void *) ll->text ); ll->just = (char *) astFree( (void *) ll->just ); ll++; } labellist = (LabelList *) astFree( (void *) labellist ); } /* Free the memory used to hold the axis values at which labels have been put. */ used = (double *) astFree( (void *) used ); /* Annul the PointSets (if used). */ if( pset1 ) pset1 = astAnnul( pset1 ); if( pset2 ) pset2 = astAnnul( pset2 ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gelid, 0, GRF__TEXT, method, class ); /* Set up the id for the next graphical element to be drawn. */ gelid = AST__NUMLAB2_ID; } } /* Free the memory used to hold the bounding boxes. */ box = (float *) astFree( (void *) box ); /* Annul the pointers to the Frame and the Mapping. */ mapping = astAnnul( mapping ); frame = astAnnul( frame ); } /* Return. */ return; } static void LinePlot( AstPlot *this, double xa, double ya, double xb, double yb, int ink, AstPlotCurveData *cdata, const char *method, const char *class, int *status ){ /* * * Name: * LinePlot * Purpose: * Draws a straight line omitting bad regions. * Type: * Private function. * Synopsis: * #include "plot.h" * void LinePlot( AstPlot *this, double xa, double ya, double xb, * double yb, int ink, AstPlotCurveData *cdata, * const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function draws a straight line between two positions in graphics * coordinates but leaves gaps in the line where it passes through * regions which have no corresponding physical coordinates. * Parameters: * this * Pointer to the Plot. * xa * The graphics X coordinate at the start of the line. * ya * The graphics Y coordinate at the start of the line. * xb * The graphics X coordinate at the end of the line. * yb * The graphics Y coordinate at the end of the line. * ink * If zero, the line is not actually drawn, but information about * the breaks is still returned. If non-zero, the line is also drawn. * cdata * A pointer to a structure in which to return information about the * breaks in the line. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Notes: * - No curve is draw if any of the start or end positions are bad * (i.e. equal to AST__BAD), or if a NULL pointer is supplied for "cdata". * No errors are reported in these cases. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ double tol; /* Absolute tolerance value */ int i; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Check the supplied values are usable. */ if( xa == AST__BAD || ya == AST__BAD || xb == AST__BAD || yb == AST__BAD || !cdata ) return; /* Convert the tolerance from relative to absolute graphics coordinates. */ tol = astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Set up the external variables used by the Crv and CrvLine function (see their prologues for details). */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_ux0 = AST__BAD; Crv_limit = 0.5*tol*tol; Crv_tol = tol; Crv_map = Map2; Crv_ink = ink; Crv_len = 0.0F; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_out = 1; Crv_xbrk = cdata->xbrk; Crv_ybrk = cdata->ybrk; Crv_vxbrk = cdata->vxbrk; Crv_vybrk = cdata->vybrk; Crv_clip = astGetClip( this ) & 1; /* Create a set of evenly spaced values between 0.0 and 1.0. These are the offsets the edge of the plotting zone at which the mapping is tested. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Now set up the externals used to communicate with the Map2 function. Map2 transforms a set of offsets between zero and one into a set of corresponding graphics coordinates, with bad values substituted for any offsets which correspond to points outside the domain of the mapping. */ /* The number of axes in the physical coordinate system (i.e. the current Frame). */ Map2_ncoord = astGetNout( this ); /* A pointer to the mapping from graphics world cordinates to physical coordinates. */ Map2_plot = this; Map2_map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* The graphics coordinates corresponding to an offset of zero (i.e. the start of the line). */ Map2_x0 = xa; Map2_y0 = ya; /* The increments in X and Y between offset zero (the start of the line) and offset 1 (the end of the line). */ Map2_deltax = xb - xa; Map2_deltay = yb - ya; /* Get the graphics coordinates corresponding to the initial set of offsets. */ Map2( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map2 to draw the intersection of the straight line with the region containing valid physical coordinates. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* End the current poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map2. */ Map2( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* If no part of the curve could be drawn, set the number of breaks and the length of the drawn curve to zero. */ if( Crv_out ) { Crv_nbrk = 0; Crv_len = 0.0F; /* Otherwise, add an extra break to the returned structure at the position of the last point to be plotted. */ } else { Crv_nbrk++; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; } } /* Store extra information about the curve in the returned structure, and purge any zero length sections. */ if( cdata ){ cdata->length = Crv_len; cdata->out = Crv_out; cdata->nbrk = Crv_nbrk; PurgeCdata( cdata, status ); } /* Annul the Mapping. */ Map2_map = astAnnul( Map2_map ); /* Return. */ return; } static double **MakeGrid( AstPlot *this, AstFrame *frm, AstMapping *map, int disk, int dim, double xlo, double xhi, double ylo, double yhi, int nphy, AstPointSet **pset1, AstPointSet **pset2, int norm, const char *method, const char *class, int *status ){ /* * Name: * MakeGrid * Purpose: * Create a square grid of graphics coordinates and the corresponding * physical coordinates. * Type: * Private function. * Synopsis: * #include "plot.h" * double **MakeGrid( AstPlot *this, AstFrame *frm, AstMapping *map, * int disk, int dim, double xlo, double xhi, double ylo, * double yhi, int nphy, AstPointSet **pset1, * AstPointSet **pset2, int norm, const char *method, * const char *class, int *status ){ * Class Membership: * Plot member function. * Description: * This function creates two PointSets, one holding a square grid of * graphics coordinates covering the supplied area, and the other * holding the corresponding physical coordinates. The points are * stored row by row in the returned PointSets, i.e. if the cell size * for the grid is (dx,dy), the first point is (xmin,ymin), followed * by (xmin+dx,ymin), (xmin+2*dx,ymin), up to (xmin+(dim-1)*dx,ymin), * followed by the next row (xmin,ymin+dy), (xmin+dx,ymin+dy), etc. * Parameters: * this * The Plot. * frm * A pointer to the Current Frame in the Plot. If this is supplied * NULL, then a pointer is found within this function if required (i.e. * if "norm" is non-zero). * map * The Mapping from graphics to physical coordinates, extracted from * the Plot. * disk * If non-zero, the corners of the grid are omitted form the * returned PointSets, resulting in a grid that is more disk like than * rectangular. * dim * The number of samples along each edge of the grid. * xlo * The lower bound on the first axis of the region to be covered * by the grid. * xhi * The upper bound on the first axis of the region to be covered * by the grid. * ylo * The lower bound on the second axis of the region to be covered * by the grid. * yhi * The upper bound on the second axis of the region to be covered * by the grid. * nphy * The number of axes in the physical cooridinate system. * pset1 * A pointer to a location at which to store a pointer to the * PointSet holding the graphics coordinates. * pset2 * A pointer to a location at which to store a pointer to the * PointSet holding the physical coordinates. * norm * If non-zero the physical cooridnates are normalised using the * Plot's astNorm method. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the physical coordinate data stored in the PointSet * "pset2". * Notes: * - The returned PointSets should be annulled when no longer needed, * using astAnnul. * - NULL pointers are returned if an error has already occurred, or * if this function should fail for any reason. */ /* Local Variables: */ double **ptr1; /* Pointers to graphics axis values */ double **ptr2; /* Pointers to physical axis values */ int size; /* No. of points in the grid */ /* Initialise the returned pointers. */ *pset1 = NULL; *pset2 = NULL; /* Check the global error status. */ if ( !astOK ) return NULL; /* Create two PointSets. We assume for the moment that they cover the full grid, including corners. */ size = dim*dim; *pset1 = astPointSet( size, 2, "", status ); *pset2 = astPointSet( size, nphy, "", status ); /* Get pointers to the data arrays for the two PointSets. */ ptr1 = astGetPoints( *pset1 ); ptr2 = astGetPoints( *pset2 ); /* Create a grid covering the supplied area. */ size = GraphGrid( dim, disk, xlo, xhi, ylo, yhi, ptr1, status ); /* If the corners are being omitted, reduce the number of points in the two PointSets. */ if( disk ) { astSetNpoint( *pset1, size ); astSetNpoint( *pset2, size ); } /* Transform these graphics positions to physical coordinates. */ Trans( this, frm, map, *pset1, 1, *pset2, norm, method, class, status ); /* If an error has occurred, annul the two pointsets. */ if( !astOK ){ *pset1 = astAnnul( *pset1 ); *pset2 = astAnnul( *pset2 ); ptr2 = NULL; } /* Return. */ return ptr2; } #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: * Plot 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: */ AstPlot *this; /* Pointer to Plot structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Plot structure. */ this = (AstPlot *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* If defined, ensure the grfcontext KeyMap contained within the Plot is locked, unlocked or checked. */ if( this->grfcontext ) { if( !result ) result = astManageLock( this->grfcontext, mode, extra, fail ); /* Also lock or unlock the associated object handle. */ if( mode == AST__LOCK ) { if( !result ) astLock( this->grfcontextID, extra ); } else if( mode == AST__UNLOCK ) { if( !result ) astUnlock( this->grfcontextID, 0 ); } } return result; } #endif static void Map1( int n, double *dist, double *x, double *y, const char *method, const char *class, int *status GLOBALS_ARG ){ /* * Name: * Map1 * Purpose: * Find graphics coordinates at given distances along a curve * parallel to a physical axis. * Type: * Private function. * Synopsis: * #include "plot.h" * void Map1( int n, double *dist, double *x, double *y, * const char *method, const char *class, * int *status [,AstGlobals *AST__GLOBALS] ) * Class Membership: * Plot member function. * Description: * The supplied distances are converted into physical coordinates * using the scalings described by various external variables, and then * these physical coordinates are mapped into graphics coordinates. * Parameters: * n * The number of points to map. Static resources are released but * no points are mapped if zero is supplied. * dist * A pointer to an array holding "n" distances. A "dist" value of * zero corresponds to the starting position supplied in external * variable Map1_origin. A "dist" value of one corresponds to the * finishing position which is a distance Map1_length away from * Map1_origin, moving in the positive direction of the axis given * by Map1_axis. "dist" values can be either linearly or * logarithmically related to axis values (see Map1_log). * x * A pointer to an array in which to store the "n" graphics X * coordinate values corresponding to the positions in "dist". * y * A pointer to an array in which to store the "n" graphics Y * coordinate values corresponding to the positions in "dist". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * AST__GLOBALS * Only present if compiled with -DTHREAD_SAFE. It is a pointer to * the structure holding the global data for the executing thread. * It is passed as a function parameter, rather than being accessed * within this function using the astGET_GLOBALS(NULL) macro (as * other Object-less functions do) in order to avoid the time * overheads of calling astGET_GLOBALS(NULL) . This function is * time-critical. * External Variables: * Map1_log = int (Read) * If zero, then "dist" in learly related to axis value. Otherwise * it is linearly related to log10(axis value). * Map1_ncoord = int (Read) * The number of axes in the physical coordinate system. * Map1_axis = int (Read) * The zero-based index of the axis which the curve follows (i.e. * the axis which changes value along the curve). * Map1_statics = Map1Statics * (Read and Write) * Pointer to a structure holding other static data used by Map1. * Map1_origin = const double * (Read) * A pointer to an array holding the physical coordinate value on * each axis at the start of the curve (i.e. at dist = 0.0). * Map1_length = double (Read) * The scale factor to convert "dist" values into increments * along the physical axis given by Map1_axis. * Map1_plot = AstPlot * (Read) * A pointer to the Plot defining the mapping from graphics cordinates * to physical coordinates. * Map1_map = AstMapping * (Read) * A pointer to the mapping from graphics cordinates to physical * coordinates extracted from the Plot. * Map1_frame = AstFrame * (Read) * A pointer to the Current Frame in the Plot. * Map1_norm = int (Read) * A flag indicating if physical coordinate values which are not in * the normal ranges of the corresponding axes should be considered * bad. * Notes: * - On the first call, this function allocates static resources which * are used by subsequent invocation. These resources should be freed before * calling this function with new values for any of the external variables, * or when no longer needed, by calling this function with "n" supplied as * zero. * - If an error has already occurred, this runction returns without * action ,except that if "n" is supplied as zero then static resources * are released even if an error has already occurred. */ /* Local Constants: */ Map1Statics *statics; /* Pointer to structure holding static data */ double *p; /* Pointer to next value */ double axval; /* Axis origin value */ int i, j; /* Loop counts */ /* Convert the global "void *" pointer to a Map1Statics pointer */ statics = (Map1Statics *) Map1_statics; /* If zero points were supplied, release static resources and return. */ if( n == 0 ){ if( statics ) { if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); if( statics->work1 ) statics->work1 = (double *) astFree( (void *) statics->work1 ); if( statics->work2 ) statics->work2 = (double *) astFree( (void *) statics->work2 ); Map1_statics = astFree( statics ); } return; } /* Otherwise, check the inherited global status. */ if( !astOK ) return; /* Create and initialise a structure to hold extra static information if this has not already been done. */ if( !statics ) { statics = astMalloc( sizeof( Map1Statics ) ); if( statics ) { statics->pset1 = NULL; statics->pset2 = NULL; statics->ptr1 = NULL; statics->pax = NULL; statics->ptr2[ 0 ] = NULL; statics->ptr2[ 1 ] = NULL; statics->work1 = NULL; statics->work2 = NULL; statics->nl = 0; Map1_statics = statics; } } /* If the number of points to be mapped is different to last time, set up some PointSets to store the specified number of points. */ if( n != statics->nl ){ statics->nl = n; /* Create a PointSet to hold the physical coordinates corresponding to the supplied offsets. First annul any existing PointSet. */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); statics->pset1 = astPointSet( n, Map1_ncoord, "", status ); statics->ptr1 = astGetPoints( statics->pset1 ); /* Create a PointSet to hold the corresponding graphics coordinates. The supplied "x" and "y" arrays will be used to store the data so we do not need to get pointers to the data using astGetPoints. First annul any existing PointSet. */ if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); statics->pset2 = astPointSet( n, 2, "", status ); /* Get work space to hold two positions. */ statics->work1 = (double *) astRealloc( (void *) statics->work1, sizeof(double)*(size_t)Map1_ncoord ); statics->work2 = (double *) astRealloc( (void *) statics->work2, sizeof(double)*(size_t)Map1_ncoord ); /* Check the pointer can be used. */ if( astOK ){ /* Store a pointer to the start of the memory which will be used to store the physical data for the axis being drawn. */ statics->pax = statics->ptr1[ Map1_axis ]; /* Fill the PointSet which is used to hold physical data with the physical coordinates at the start of the curve. */ for( i = 0; i < Map1_ncoord; i++ ){ axval = Map1_origin[ i ]; p = statics->ptr1[ i ]; for( j = 0; j < n; j++ ) *(p++) = axval; } /* Store the scale and offset to apply to the "dist" values. If Map1_log is zero (linear axes) then applying these values gives axis value directly. If Map1_log is non-zero (log axes) then applying these values gives log10( axis value). */ if( Map1_log ) { statics->neg = ( Map1_origin[ Map1_axis ] < 0 ); statics->axorig = log10( fabs( Map1_origin[ Map1_axis ] ) ); statics->axscale = log10( fabs( Map1_origin[ Map1_axis ] + Map1_length ) ) - statics->axorig; } else { statics->axorig = Map1_origin[ Map1_axis ]; statics->axscale = Map1_length; } } } /* Check the initialisation went OK (if done). */ if( astOK ){ /* Loop round each offset along the curve, converting the normalised offset in the range [0,1] to a physical coordinate and storing in PointSet 1. */ p = statics->pax; for( i = 0; i < n; i++){ *(p++) = statics->axorig + statics->axscale*dist[ i ]; } if( Map1_log ) { p = statics->pax; for( i = 0; i < n; i++,p++ ){ *p = statics->neg ? -pow( 10.0, *p ) : pow( 10.0, *p ); } } /* Store pointers to the results arrays in PointSet 2. */ statics->ptr2[ 0 ] = x; statics->ptr2[ 1 ] = y; astSetPoints( statics->pset2, statics->ptr2 ); /* Map all the positions into graphics coordinates. */ (void) Trans( Map1_plot, NULL, Map1_map, statics->pset1, 0, statics->pset2, 1, method, class, status ); /* If points not in their normal ranges are to be set bad... */ if( Map1_norm ) { /* The following code simply normalizes the physical position, and if this produces any change, the graphics positions are set bad. */ for( i = 0; i < n; i++){ for( j = 0; j < Map1_ncoord; j++) statics->work1[j] = statics->ptr1[j][i]; astNorm( Map1_frame, statics->work1 ); for( j = 0; j < Map1_ncoord; j++) { if( !astEQUALS( statics->work1[j], statics->ptr1[j][i], 1.0E8 ) ) { statics->ptr2[0][i] = AST__BAD; statics->ptr2[1][i] = AST__BAD; break; } } } } } /* Return. */ return; } static void Map2( int n, double *dist, double *x, double *y, const char *method, const char *class, int *status GLOBALS_ARG ){ /* * Name: * Map2 * Purpose: * Find which graphics coordinates have good physical coordinates * at given distances along a straight line. * Type: * Private function. * Synopsis: * #include "plot.h" * void Map2( int n, double *dist, double *x, double *y, * const char *method, const char *class, * int *status [,AstGlobals *AST__GLOBALS] ) * Class Membership: * Plot member function. * Description: * The supplied distances refer to the distance along a straight line * in the graphics coordinate system. The returned graphics coordinates * correspond to the supplied distances, except that any position for * which there are no defined physical coordinates is returned bad. * Parameters: * n * The number of points to map. Static resources are released but * no points are mapped if zero is supplied. * dist * A pointer to an array holding "n" distances. A "dist" value of * zero corresponds to the graphics position supplied in external * variables (Map2_x0, Map2_y0). A "dist" value of one corresponds to * the graphics position which is offset from the start by the vector * (Map2_deltax, Map2_deltay). * x * A pointer to an array in which to store the "n" graphics X * coordinate values corresponding to the positions in "dist", * except that any which have no corresponding physical coordinates * are set to AST__BAD. * y * A pointer to an array in which to store the "n" graphics Y * coordinate values corresponding to the positions in "dist", * except that any which have no corresponding physical coordinates * are set to AST__BAD. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * AST__GLOBALS * Only present if compiled with -DTHREAD_SAFE. It is a pointer to * the structure holding the global data for the executing thread. * It is passed as a function parameter, rather than being accessed * within this function using the astGET_GLOBALS(NULL) macro (as * other Object-less functions do) in order to avoid the time * overheads of calling astGET_GLOBALS(NULL) . This function is * time-critical. * External Variables: * Map2_ncoord = int (Read) * The number of axes in the physical coordinate system. * Map2_x0 = double (Read) * The graphics X coordinate at the start of the line (i.e. at dist * = 0.0). * Map2_y0 = double (Read) * The graphics Y coordinate at the start of the line (i.e. at dist * = 0.0). * Map2_deltax = double (Read) * The increment along the graphics X axis between the start and * end of the line. * Map2_deltay = double (Read) * The increment along the graphics Y axis between the start and * end of the line. * Map2_plot = AstPlot * (Read) * A pointer to the Plot defining the mapping from graphics cordinates * to physical coordinates. * Map2_map = AstMapping * (Read) * A pointer to the mapping from graphics cordinates to physical * coordinates, extracted from the Plot. * Map2_statics = Map2Statics * (Read and Write) * Pointer to a structure holding other static data used by Map2. * Notes: * - On the first call, this function allocates static resources which * are used by subsequent invocation. These resources should be freed before * calling this function with new values for any of the external variables, * or when no longer needed, by calling this function with "n" supplied as * zero. * - If an error has already occurred, this runction returns without * action ,except that if "n" is supplied as zero then static resources * are released even if an error has already occurred. */ /* Local Constants: */ Map2Statics *statics; /* Pointer to structure holding static data */ int i, j; /* Loop counts */ double *p; /* Pointer to next physical value */ double *px; /* Pointer to next x graphics value */ double *py; /* Pointer to next y graphics value */ /* Convert the global "void *" pointer to a Map2Statics pointer */ statics = (Map2Statics *) Map2_statics; /* If zero points were supplied, release static resources and return. */ if( n == 0 ){ if( statics ) { if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); Map2_statics = astFree( statics ); } return; } /* Otherwise, check the inherited global status. */ if( !astOK ) return; /* Create and initialise a structure to hold extra static information if this has not already been done. */ if( !statics ) { statics = astMalloc( sizeof( Map2Statics ) ); if( statics ) { statics->pset1 = NULL; statics->pset2 = NULL; statics->ptr2 = NULL; statics->ptr1[ 0 ] = NULL; statics->ptr1[ 1 ] = NULL; statics->nl = 0; Map2_statics = statics; } } /* If the number of points to be mapped is different to last time, set up some PointSets to store the specified number of points. */ if( n != statics->nl ){ statics->nl = n; /* Create a PointSet to hold the graphics coordinates corresponding to the supplied offsets. The supplied arrays will be used to hold the data for this PointSet, and so astGetPoints is not called. */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); statics->pset1 = astPointSet( n, 2, "", status ); /* Create a PointSet to hold the corresponding physical coordinates, and get pointers to the associated axis values. */ if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); statics->pset2 = astPointSet( n, Map2_ncoord, "", status ); statics->ptr2 = astGetPoints( statics->pset2 ); } /* Check the initialisation went OK (if done). */ if( astOK ){ /* Store pointers to the results arrays in PointSet 1. */ statics->ptr1[ 0 ] = x; statics->ptr1[ 1 ] = y; astSetPoints( statics->pset1, statics->ptr1 ); /* Loop round each offset along the curve, converting the normalised offset in the range [0,1] to graphics coordinate and storing in PointSet 1. */ px = x; py = y; for( i = 0; i < n; i++){ *(px++) = Map2_x0 + Map2_deltax*dist[ i ]; *(py++) = Map2_y0 + Map2_deltay*dist[ i ]; } /* Map all the positions into physical coordinates. */ (void) Trans( Map2_plot, NULL, Map2_map, statics->pset1, 1, statics->pset2, 0, method, class, status ); /* Check the physical coordinates for bad values, setting the corresponding graphics coordinates bad. */ for( j = 0; j < Map2_ncoord; j++ ){ p = statics->ptr2[ j ]; px = x; py = y; for( i = 0; i < n; i++){ if( *(p++) == AST__BAD ){ *(px++) = AST__BAD; *(py++) = AST__BAD; } else { px++; py++; } } } } /* Return. */ return; } static void Map3( int n, double *dist, double *x, double *y, const char *method, const char *class, int *status GLOBALS_ARG ){ /* * Name: * Map3 * Purpose: * Find graphics coordinates at given distances along a geodesic curve * between two physical coordinate positions. * Type: * Private function. * Synopsis: * #include "plot.h" * void Map3( int n, double *dist, double *x, double *y, * const char *method, const char *class, * int *status [,AstGlobals *AST__GLOBALS] ) * Class Membership: * Plot member function. * Description: * The supplied distances are converted into physical offsets along the * geodesic curve joining the starting and finishing points given by * externals Map3_origin and Map3_end. The physical coordinates at these * offsets are found, and transformed into graphics coordinates. * Parameters: * n * The number of points to map. Static resources are released but * no points are mapped if zero is supplied. * dist * A pointer to an array holding "n" distances. A "dist" value of * zero corresponds to the starting position supplied in external * variable Map3_origin. A "dist" value of one corresponds to the * finishing position given by Map3_end. * x * A pointer to an array in which to store the "n" graphics X * coordinate values corresponding to the positions in "dist". * y * A pointer to an array in which to store the "n" graphics Y * coordinate values corresponding to the positions in "dist". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * AST__GLOBALS * Only present if compiled with -DTHREAD_SAFE. It is a pointer to * the structure holding the global data for the executing thread. * It is passed as a function parameter, rather than being accessed * within this function using the astGET_GLOBALS(NULL) macro (as * other Object-less functions do) in order to avoid the time * overheads of calling astGET_GLOBALS(NULL) . This function is * time-critical. * External Variables: * Map3_ncoord = int (Read) * The number of axes in the physical coordinate system. * Map3_origin = const double * (Read) * A pointer to an array holding the physical coordinate value on * each axis at the start of the curve (i.e. at dist = 0.0). * Map3_end = const double * (Read) * A pointer to an array holding the physical coordinate value on * each axis at the end of the curve (i.e. at dist = 1.0). * Map3_scale = double (Read) * The scale factor to convert "dist" values into physical offsets * along the geodesic curve. * Map3_statics = Map3Statics * (Read and Write) * Pointer to a structure holding other static data used by Map3. * Map3_plot = AstPlot * (Read) * A pointer to the Plot defining the mapping from graphics cordinates * to physical coordinates. * Map3_map = AstMapping * (Read) * A pointer to the mapping from graphics cordinates to physical * coordinates extracted from the Plot. * Map3_frame = AstFrame * (Read) * A pointer to the Current Frame in the Plot. * Notes: * - On the first call, this function allocates static resources which * are used by subsequent invocation. These resources should be freed before * calling this function with new values for any of the external variables, * or when no longer needed, by calling this function with "n" supplied as * zero. * - If an error has already occurred, this runction returns without * action ,except that if "n" is supplied as zero then static resources * are released even if an error has already occurred. */ /* Local Constants: */ Map3Statics *statics; /* Pointer to structure holding static data */ int i, j; /* Loop counts */ /* Convert the global "void *" pointer to a Map3Statics pointer */ statics = (Map3Statics *) Map3_statics; /* If zero points were supplied, release static resources and return. */ if( n == 0 ){ if( statics ) { if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); if( statics->pos ) statics->pos = (double *) astFree( (void *) statics->pos ); Map3_statics = astFree( statics ); } return; } /* Otherwise, check the inherited global status. */ if( !astOK ) return; /* Create and initialise a structure to hold extra static information if this has not already been done. */ if( !statics ) { statics = astMalloc( sizeof( Map3Statics ) ); if( statics ) { statics->pset1 = NULL; statics->pset2 = NULL; statics->ptr1 = NULL; statics->ptr2[ 0 ] = NULL; statics->ptr2[ 1 ] = NULL; statics->nc = 0; statics->nl = 0; statics->pos = NULL; Map3_statics = statics; } } /* If the number of points to be mapped is different to last time, set up some PointSets to store the specified number of points. */ if( n != statics->nl ){ statics->nl = n; /* Create a PointSet to hold the physical coordinates corresponding to the supplied offsets. First annul any existing PointSet. */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); statics->pset1 = astPointSet( n, Map3_ncoord, "", status ); statics->ptr1 = astGetPoints( statics->pset1 ); /* Create a PointSet to hold the corresponding graphics coordinates. The supplied "x" and "y" arrays will be used to store the data so we do not need to get pointers to the data using astGetPoints. First annul any existing PointSet. */ if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); statics->pset2 = astPointSet( n, 2, "", status ); } /* If the number of physical axes is different to last time, allocate memory to hold a single physical position. */ if( statics->nc != Map3_ncoord ){ statics->nc = Map3_ncoord; statics->pos = (double *) astMalloc( sizeof(double)*(size_t)Map3_ncoord ); } /* Check the initialisation went OK (if done). */ if( astOK ){ /* Loop round each offset along the curve, converting the normalised offset in the range [0,1] to a physical offset, and then into a physical position, and store in PointSet 1. */ for( i = 0; i < n; i++){ astOffset( Map3_frame, Map3_origin, Map3_end, Map3_scale*dist[ i ], statics->pos ); for( j = 0; j < Map3_ncoord; j++ ){ statics->ptr1[ j ][ i ] = statics->pos[ j ]; } } /* Store pointers to the results arrays in PointSet 2. */ statics->ptr2[ 0 ] = x; statics->ptr2[ 1 ] = y; astSetPoints( statics->pset2, statics->ptr2 ); /* Map all the positions into graphics coordinates. */ (void) Trans( Map3_plot, NULL, Map3_map, statics->pset1, 0, statics->pset2, 1, method, class, status ); } /* Return. */ return; } static void Map4( int n, double *dist, double *x, double *y, const char *method, const char *class, int *status GLOBALS_ARG ){ /* * Name: * Map4 * Purpose: * Find graphics coordinates at given distances along a user * specified curve. * Type: * Private function. * Synopsis: * #include "plot.h" * void Map4( int n, double *dist, double *x, double *y, * const char *method, const char *class, * int *status [,AstGlobals *AST__GLOBALS] ) * Class Membership: * Plot member function. * Description: * The supplied distances are converted into physical coordinates using * the Mapping Map4_umap. These physical coordinates are transformed into * graphics coordinates. * Parameters: * n * The number of points to map. Static resources are released but * no points are mapped if zero is supplied. * dist * A pointer to an array holding "n" distances. A "dist" value of * zero corresponds to the starting position supplied in external * variable Map3_origin. A "dist" value of one corresponds to the * finishing position given by Map3_end. * x * A pointer to an array in which to store the "n" graphics X * coordinate values corresponding to the positions in "dist". * y * A pointer to an array in which to store the "n" graphics Y * coordinate values corresponding to the positions in "dist". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * AST__GLOBALS * Only present if compiled with -DTHREAD_SAFE. It is a pointer to * the structure holding the global data for the executing thread. * It is passed as a function parameter, rather than being accessed * within this function using the astGET_GLOBALS(NULL) macro (as * other Object-less functions do) in order to avoid the time * overheads of calling astGET_GLOBALS(NULL) . This function is * time-critical. * External Variables: * Map4_ncoord = int (Read) * The number of axes in the physical coordinate system. * Map4_plot = AstPlot * (Read) * A pointer to the Plot defining the mapping from graphics cordinates * to physical coordinates. * Map4_map = AstMapping * (Read) * A pointer to the mapping from graphics cordinates to physical * coordinates extracted from the Plot. * Map4_statics = Map4Statics * (Read and Write) * Pointer to a structure holding other static data used by Map4. * Map4_umap = AstMapping * (Read) * A pointer to the mapping from distance along the curve to physical * coordinates. * Notes: * - On the first call, this function allocates static resources which * are used by subsequent invocation. These resources should be freed before * calling this function with new values for any of the external variables, * or when no longer needed, by calling this function with "n" supplied as * zero. * - If an error has already occurred, this runction returns without * action ,except that if "n" is supplied as zero then static resources * are released even if an error has already occurred. */ /* Local Variables: */ Map4Statics *statics; /* Pointer to structure holding static data */ double *ptr1[ 1 ]; /* Pointer to distances data */ double *ptr3[ 2 ]; /* Pointers to graphics coord data */ /* Convert the global "void *" pointer to a Map4Statics pointer */ statics = (Map4Statics *) Map4_statics; /* If zero points were supplied, release static resources and return. */ if( n == 0 ){ if( statics ) { if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); if( statics->pset3 ) statics->pset3 = astAnnul( statics->pset3 ); Map4_statics = astFree( statics ); } return; } /* Otherwise, check the inherited global status. */ if( !astOK ) return; /* Create and initialise a structure to hold extra static information if this has not already been done. */ if( !statics ) { statics = astMalloc( sizeof( Map4Statics ) ); if( statics ) { statics->pset1 = NULL; statics->pset2 = NULL; statics->pset3 = NULL; statics->nl = 0; Map4_statics = statics; } } /* If the number of points to be mapped is different to last time, set up some PointSets to store the specified number of points. */ if( n != statics->nl ){ statics->nl = n; /* Create a PointSet to hold the distances along the curve. First annul any existing PointSet. */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); statics->pset1 = astPointSet( n, 1, "", status ); /* Create a PointSet to hold the physical coordinates corresponding to the supplied distances. First annul any existing PointSet. */ if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); statics->pset2 = astPointSet( n, Map4_ncoord, "", status ); /* Create a PointSet to hold the corresponding graphics coordinates. First annul any existing PointSet. */ if( statics->pset3 ) statics->pset3 = astAnnul( statics->pset3 ); statics->pset3 = astPointSet( n, 2, "", status ); } /* Check the initialisation went OK (if done). */ if( astOK ){ /* Use Map4_umap to convert the supplied distances into physical coords (i.e. coords in the current Frame of the Plot). */ ptr1[ 0 ] = dist; astSetPoints( statics->pset1, ptr1 ); (void) astTransform( Map4_umap, statics->pset1, 1, statics->pset2 ); /* Store pointers to the results arrays in PointSet 2. */ ptr3[ 0 ] = x; ptr3[ 1 ] = y; astSetPoints( statics->pset3, ptr3 ); /* Now transform these physical coords into graphical coords, incorporating clipping. */ (void) Trans( Map4_plot, NULL, Map4_map, statics->pset2, 0, statics->pset3, 1, method, class, status ); } /* Return. */ return; } static void Map5( int n, double *dist, double *x, double *y, const char *method, const char *class, int *status GLOBALS_ARG ){ /* * Name: * Map5 * Purpose: * Find graphics coordinates at given distances along the boundary of * a Region. * Type: * Private function. * Synopsis: * #include "plot.h" * void Map5( int n, double *dist, double *x, double *y, * const char *method, const char *class, * int *status [,AstGlobals *AST__GLOBALS] ) * Class Membership: * Plot member function. * Description: * The supplied distances are converted into physical coordinates * using the Region specified by an external variable, and then * these physical coordinates are mapped into graphics coordinates. * Parameters: * n * The number of points to map. Static resources are released but * no points are mapped if zero is supplied. * dist * A pointer to an array holding "n" distances. A "dist" value of * zero corresponds to the starting position supplied in external * variable Map1_origin. A "dist" value of one corresponds to the * finishing position which is a distance Map1_length away from * Map1_origin, moving in the positive direction of the axis given * by Map1_axis. "dist" values can be either linearly or * logarithmically related to axis values (see Map1_log). * x * A pointer to an array in which to store the "n" graphics X * coordinate values corresponding to the positions in "dist". * y * A pointer to an array in which to store the "n" graphics Y * coordinate values corresponding to the positions in "dist". * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * AST__GLOBALS * Only present if compiled with -DTHREAD_SAFE. It is a pointer to * the structure holding the global data for the executing thread. * It is passed as a function parameter, rather than being accessed * within this function using the astGET_GLOBALS(NULL) macro (as * other Object-less functions do) in order to avoid the time * overheads of calling astGET_GLOBALS(NULL) . This function is * time-critical. * External Variables: * Map1_log = int (Read) * If zero, then "dist" in learly related to axis value. Otherwise * it is linearly related to log10(axis value). * Map1_ncoord = int (Read) * The number of axes in the physical coordinate system. * Map1_axis = int (Read) * The zero-based index of the axis which the curve follows (i.e. * the axis which changes value along the curve). * Map1_statics = Map1Statics * (Read and Write) * Pointer to a structure holding other static data used by Map1. * Map1_origin = const double * (Read) * A pointer to an array holding the physical coordinate value on * each axis at the start of the curve (i.e. at dist = 0.0). * Map1_length = double (Read) * The scale factor to convert "dist" values into increments * along the physical axis given by Map1_axis. * Map1_plot = AstPlot * (Read) * A pointer to the Plot defining the mapping from graphics cordinates * to physical coordinates. * Map1_map = AstMapping * (Read) * A pointer to the mapping from graphics cordinates to physical * coordinates extracted from the Plot. * Map1_frame = AstFrame * (Read) * A pointer to the Current Frame in the Plot. * Map1_norm = int (Read) * A flag indicating if physical coordinate values which are not in * the normal ranges of the corresponding axes should be considered * bad. * Notes: * - On the first call, this function allocates static resources which * are used by subsequent invocation. These resources should be freed before * calling this function with new values for any of the external variables, * or when no longer needed, by calling this function with "n" supplied as * zero. * - If an error has already occurred, this runction returns without * action ,except that if "n" is supplied as zero then static resources * are released even if an error has already occurred. */ /* Local Constants: */ Map5Statics *statics; /* Pointer to structure holding static data */ /* Convert the global "void *" pointer to a Map5Statics pointer */ statics = (Map5Statics *) Map5_statics; /* If zero points were supplied, release static resources and return. */ if( n == 0 ){ if( statics ) { if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); Map5_statics = astFree( statics ); } return; } /* Otherwise, check the inherited global status. */ if( !astOK ) return; /* Create and initialise a structure to hold extra static information if this has not already been done. */ if( !statics ) { statics = astMalloc( sizeof( Map3Statics ) ); if( statics ) { statics->pset1 = NULL; statics->pset2 = NULL; statics->ptr1 = NULL; statics->ptr2[ 0 ] = NULL; statics->ptr2[ 1 ] = NULL; statics->nl = 0; Map5_statics = statics; } } /* If the number of points to be mapped is different to last time, set up some PointSets to store the specified number of points. */ if( n != statics->nl ){ statics->nl = n; /* Create a PointSet to hold the physical coordinates corresponding to the supplied offsets. First annul any existing PointSet. */ if( statics->pset1 ) statics->pset1 = astAnnul( statics->pset1 ); statics->pset1 = astPointSet( n, Map5_ncoord, "", status ); statics->ptr1 = astGetPoints( statics->pset1 ); /* Create a PointSet to hold the corresponding graphics coordinates. The supplied "x" and "y" arrays will be used to store the data so we do not need to get pointers to the data using astGetPoints. First annul any existing PointSet. */ if( statics->pset2 ) statics->pset2 = astAnnul( statics->pset2 ); statics->pset2 = astPointSet( n, 2, "", status ); } /* Get the physical coords at the required positions along the Region border. */ astRegTrace( Map5_region, n, dist, statics->ptr1 ); /* Store pointers to the results arrays in PointSet 2. */ statics->ptr2[ 0 ] = x; statics->ptr2[ 1 ] = y; astSetPoints( statics->pset2, statics->ptr2 ); /* Map all the positions into graphics coordinates. */ (void) Trans( Map5_plot, NULL, Map5_map, statics->pset1, 0, statics->pset2, 1, method, class, status ); /* Return. */ return; } static void Mark( AstPlot *this, int nmark, int ncoord, int indim, const double *in, int type, int *status ){ /* *++ * Name: c astMark f AST_MARK * Purpose: * Draw a set of markers for a Plot. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astMark( AstPlot *this, int nmark, int ncoord, int indim, c const double *in, int type ) f CALL AST_MARK( THIS, NMARK, NCOORD, INDIM, IN, TYPE, STATUS ) * Class Membership: * Plot method. * Description: c This function draws a set of markers (symbols) at positions f This routine draws a set of markers (symbols) at positions * specified in the physical coordinate system of a Plot. The * positions are transformed into graphical coordinates to * determine where the markers should appear within the plotting * area. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c nmark f NMARK = INTEGER (Given) * The number of markers to draw. This may be zero, in which * case nothing will be drawn. c ncoord f NCOORD = INTEGER (Given) * The number of coordinates being supplied for each mark * (i.e. the number of axes in the current Frame of the Plot, as * given by its Naxes attribute). c indim f INDIM = INTEGER (Given) c The number of elements along the second dimension of the "in" f The number of elements along the first dimension of the IN * array (which contains the marker coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value c given should not be less than "nmark". f given should not be less than NMARK. c in f IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given) c The address of the first element of a 2-dimensional array of c shape "[ncoord][indim]" giving the c physical coordinates of the points where markers are to be c drawn. These should be stored such that the value of c coordinate number "coord" for input mark number "mark" is c found in element "in[coord][mark]". f A 2-dimensional array giving the physical coordinates of the f points where markers are to be drawn. These should be f stored such that the value of coordinate number COORD for f input mark number MARK is found in element IN(MARK,COORD). c type f TYPE = INTEGER (Given) * A value specifying the type (e.g. shape) of marker to be * drawn. The set of values which may be used (and the shapes * that will result) is determined by the underlying graphics * system. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Markers are not drawn at positions which have any coordinate * equal to the value AST__BAD (or where the transformation into * graphical coordinates yields coordinates containing the value * AST__BAD). c - If any marker position is clipped (see astClip), then the f - If any marker position is clipped (see AST_CLIP), then the * entire marker is not drawn. * - An error results if the base Frame of the Plot is not 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *mapping; /* Pointer to graphics->physical mapping */ AstPointSet *pset1; /* PointSet holding physical positions */ AstPointSet *pset2; /* PointSet holding graphics positions */ const char *class; /* Object class */ const char *method; /* Current method */ const double **ptr1; /* Pointer to physical positions */ double **ptr2; /* Pointer to graphics positions */ double *xpd; /* Pointer to next double precision x value */ double *ypd; /* Pointer to next double precision y value */ double xx; /* X axis value */ double yy; /* Y axis value */ float *x; /* Pointer to single precision x values */ float *xpf; /* Pointer to next single precision x value */ float *y; /* Pointer to single precision y values */ float *ypf; /* Pointer to next single precision y value */ int axis; /* Axis index */ int clip; /* Clips marks at plot boundary? */ int i; /* Loop count */ int naxes; /* No. of axes in the base Frame */ int nn; /* Number of good marker positions */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astMark"; class = astClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Also validate the input array dimension argument. */ if ( astOK && ( indim < nmark ) ) { astError( AST__DIMIN, "%s(%s): The input array dimension value " "(%d) is invalid.", status, method, class, indim ); astError( AST__DIMIN, "This should not be less than the number of " "markers being drawn (%d).", status, nmark ); } /* Initialise the bounding box for primatives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__MARKS_ID, 1, GRF__MARK, method, class ); /* Create a PointSet to hold the supplied physical coordinates. */ pset1 = astPointSet( nmark, ncoord, "", status ); /* Allocate memory to hold pointers to the first value on each axis. */ ptr1 = (const double **) astMalloc( sizeof( const double * )* (size_t)( ncoord )); /* Check the pointer can be used, then store pointers to the first value on each axis. */ if( astOK ){ for( axis = 0; axis < ncoord; axis++ ){ ptr1[ axis ] = in + axis*indim; } } /* Store these pointers in the PointSet. */ astSetPoints( pset1, (double **) ptr1 ); /* Transform the supplied data from the current frame (i.e. physical coordinates) to the base frame (i.e. graphics coordinates) using the inverse Mapping defined by the Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); pset2 = Trans( this, NULL, mapping, pset1, 0, NULL, 0, method, class, status ); mapping = astAnnul( mapping ); /* Get pointers to the graphics coordinates. */ ptr2 = astGetPoints( pset2 ); /* Allocate memory to hold single precision versions of the graphics coordinates. */ x = (float *) astMalloc( sizeof( float )*(size_t) nmark ); y = (float *) astMalloc( sizeof( float )*(size_t) nmark ); /* Check the pointers can be used. */ if( astOK ){ /* Store pointers to the next single and double precision x and y values. */ xpf = x; ypf = y; xpd = ptr2[ 0 ]; ypd = ptr2[ 1 ]; /* Convert the double precision values to single precision, rejecting any bad marker positions. If clipping is switched on, also clip any markers with centres outside the plotting area. */ clip = astGetClip( this ) & 2; nn = 0; for( i = 0; i < nmark; i++ ){ if( *xpd != AST__BAD && *ypd != AST__BAD ){ xx = *(xpd++); yy = *(ypd++); if( !clip || ( xx >= this->xlo && xx <= this->xhi && yy >= this->ylo && yy <= this->yhi ) ) { nn++; *(xpf++) = (float) xx; *(ypf++) = (float) yy; } } else { xpd++; ypd++; } } /* Draw the remaining markers. */ GMark( this, nn, x, y, type, method, class, status ); } /* Free the memory used to store single precision graphics coordinates. */ x = (float *) astFree( (void *) x ); y = (float *) astFree( (void *) y ); /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free the memory holding the pointers to the first value on each axis. */ ptr1 = (const double **) astFree( (void *) ptr1 ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__MARKS_ID, 0, GRF__MARK, method, class ); /* Return */ return; } static void Mirror( AstPlot *this, int axis, int *status ){ /* *+ * Name: * astMirror * Purpose: * Flip a graphics axis of a Plot. * Type: * Protected virtual function. * Synopsis: * #include "plot.h" * void astMirror( AstPlot *this, int axis ) * Class Membership: * Plot method. * Description: * This function referses the direction of a specified graphics axis * in the Plot. * Parameters: * this * Pointer to a Plot. * axis * The zero-based axis of the axis to mirror. *- */ /* Check the global status. */ if( !astOK ) return; if( axis == 0 ) { this->xrev = ( this->xrev == 0 ); } else if( axis == 1 ){ this->yrev = ( this->yrev == 0 ); } else { astError( AST__INTER, "astMirror(%s): Illegal axis index (%d) " "supplied (internal AST programming error).", status, astGetClass( this ), axis ); } } static void Norm1( AstMapping *map, int axis, int nv, double *vals, double refval, double width, int *status ){ /* * Name: * Norm1 * Purpose: * Use a Mapping to normalize an array of axis values. * Type: * Private function. * Synopsis: * #include "plot.h" * void Norm1( AstMapping *map, int axis, int nv, double *vals, * double refval, double width, int *status ) * Class Membership: * Plot member function. * Description: * The normalization of a position in physical space has two parts; * firstly, the Mapping may determine a form of normalization; * secondly, the Frame may provide an additional normalizion by the * astNorm method. This function implements normalization using a * Mapping, by transforming the physical position into Graphics position, * and then back into a physical position. For instance, if the Mapping * represents a mapping of Cartesian graphics axes onto a 2D polar * coordinate system, a physical theta value of 3.PI will be normalized by * the Mapping into a theta value of 1.PI (probably, but it depends on * the Mapping). In this case, the Mapping normalization may well be the * only normalization available, since the 2D polar coord. system will * probably use a simple Frame to represent the (radius,theta) system, * and a simple Frame defines no normalization (i.e. the astNorm method * returns the supplied position unchanged). * * Complications arise though because it is not possible to normalise * a single axis value - you can only normalize a complete position. * Therefore some value must be supplied for the other axis. We * should use the LabelAt value, but we do not yet know what the LabelAt * value will be. Instead, we try first using the supplied "refval" * which should be close to the mode of the other aixs values. Usually * the value used is not very important. However, for some complex * projections (such as quad-cubes, TSC, etc) the choice can be more * critical since some positions on the ksy correspond to undefined * graphics positions (e.g the face edges in a TSC projection). * Therefore, if the supplied refval results in any positions being * undefined we refine the process by transforming the undefined * positaons again using a different refval. We do this twice to bump * up the likelihood of finding a suitable reference value. * Parameters: * mapping * The Mapping from Graphics Frame to the current Frame. * axis * The index of the axis for which values are supplied in "vals". * nv * The number of values supplied in "vals". * vals * Pointer to an array of axis values. On exit they are normalized. * refval * The preffered constant value to use for the other axis when * normalizing the values in "vals". * width * The range of used values for the other axis. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *pset1; /* PointSet holding physical coords */ AstPointSet *pset2; /* PointSet holding graphics coords */ double **ptr1; /* Pointer to physical coords data */ double *a; /* Pointer to next axis value */ double *b; /* Pointer to next axis value */ int i; /* Loop count */ int itry; /* Loop count for re-try loop */ int nbad; /* No. of bad values found after transformation */ int *flags; /* Pointer to flags array */ /* Check the inherited global status. */ if( !astOK ) return; /* Store the supplied positions in a PointSet. */ pset1 = astPointSet( nv, 2, "", status ); ptr1 = astGetPoints( pset1 ); if( astOK ) { a = ptr1[ axis ]; b = ptr1[ 1 - axis ]; for( i = 0; i < nv; i++){ *(a++) = vals[ i ]; *(b++) = refval; } } /* Transform the supplied positions into the Base Frame. */ pset2 = astTransform( map, pset1, 0, NULL ); /* Transform the Base Frame positions back into the Current Frame. */ (void) astTransform( map, pset2, 1, pset1 ); /* Allocate memory to hold a flag for each position which is non-zero if we currently have a good axis value to return for the position. */ flags = (int *) astMalloc( sizeof(int)* (size_t) nv ); /* If good, store these values back in the supplied array. If the transformed values are bad, retain the original good values for the moment in "vals", and also copy the good values back into pset1. So at the end, pset1 will contain the original good values at any points which produced bad values after the above transformation - the other points in pset1 will be bad. */ nbad = 0; if( astOK ) { a = ptr1[ axis ]; for( i = 0; i < nv; i++, a++ ){ if( *a != AST__BAD ) { vals[ i ] = *a; *a = AST__BAD; flags[ i ] = 1; } else if( vals[ i ] != AST__BAD ) { nbad++; *a = vals[ i ]; flags[ i ] = 0; } else { flags[ i ] = 1; } } } /* We now try normalising any remaining bad positions using different values for the other axis. This may result in some or all of the remaining points being normalised succesfully. */ for( itry = 0; itry < 10; itry++ ) { /* If the above transformation produced any bad values, try again with a different value on the other axis. */ if( astOK && nbad > 0 ) { b = ptr1[ 1 - axis ]; for( i = 0; i < nv; i++){ *(b++) = refval + 0.1*( itry + 1 )*width; } /* Transform to graphics coords and back to world coords. */ (void) astTransform( map, pset1, 0, pset2 ); (void) astTransform( map, pset2, 1, pset1 ); /* Copy any good positions back into the returned vals array. Count remaining bad positions. */ a = ptr1[ axis ]; nbad = 0; for( i = 0; i < nv; i++, a++ ){ if( *a != AST__BAD ) { vals[ i ] = *a; flags[ i ] = 1; *a = AST__BAD; } else if( !flags[ i ] ) { nbad++; *a = vals[ i ]; } } } /* If the above transformation produced any bad values, try again with a different value on the other axis. */ if( astOK && nbad > 0 ) { b = ptr1[ 1 - axis ]; for( i = 0; i < nv; i++){ *(b++) = refval - 0.1*( itry + 1 )*width; } /* Transform to graphics coords and back to world coords. */ (void) astTransform( map, pset1, 0, pset2 ); (void) astTransform( map, pset2, 1, pset1 ); /* Copy any good positions back into the returned vals array. Count remaining bad positions. */ a = ptr1[ axis ]; nbad = 0; for( i = 0; i < nv; i++, a++ ){ if( *a != AST__BAD ) { vals[ i ] = *a; flags[ i ] = 1; *a = AST__BAD; } else if( !flags[ i ] ) { nbad++; *a = vals[ i ]; } } } } /* Free resources. */ flags = (int *) astFree( flags ); pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); } static void Opoly( AstPlot *this, int *status ){ /* * Name: * Opoly * Purpose: * Draws the current poly line. * Type: * Private function. * Synopsis: * #include "plot.h" * void Opoly( AstPlot *this, int *status ) * Class Membership: * Plot member function. * Description: * This function draws the current poly line, and empties the buffer. * Parameters: * this * Pointer to the Plot. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int ipoly; /* Index of new polyline */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Draw the poly-line if needed. */ if( Poly_n > 0 ) { /* Extend the global arrays that hold pointers to the polylines already drawn. */ ipoly = Poly_npoly++; astBeginPM; Poly_xp = astGrow( Poly_xp, Poly_npoly, sizeof(float*) ); Poly_yp = astGrow( Poly_yp, Poly_npoly, sizeof(float*) ); Poly_np = astGrow( Poly_np, Poly_npoly, sizeof(int) ); astEndPM; if( astOK ) { /* Add pointers to the new polyline to the end of the above extended arrays. */ Poly_xp[ ipoly ] = Poly_x; Poly_yp[ ipoly ] = Poly_y; Poly_np[ ipoly ] = Poly_n; /* Indicate that the current polyline is now empty. */ Poly_x = NULL; Poly_y = NULL; Poly_n = 0; } } } static int Overlap( AstPlot *this, int mode, int esc, const char *text, float x, float y, const char *just, float upx, float upy, float **work, const char *method, const char *class, int *status ){ /* * Name: * Overlap * Purpose: * See if a major tick value label would overlap any of the previously * drawn labels. * Type: * Private function. * Synopsis: * #include "plot.h" * int Overlap( AstPlot *this, int mode, int esc, const char *text, float x, * float y, const char *just, float upx, float upy, * float **work, const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * The operation of this function is determined by the "mode" parameter. * A record is kept of the bounding boxes enclosing all the displayed * labels. If the bounding box of the new label defined by the given * parameter values would overlap any of the old bounding boxes, 0 is * returned. Otherwise 1 is returned and the bounding box for the new * label is added to the list of old bounding boxes. * This function also updates the external variables Box_lbnd and * Box_ubnd which hold the lower and upper bounds of the area enclosing * all used labels. * Parameters: * this * A pointer to the Plot. * mode * - If -1, find the bounding box of the supplied label, add it * to the list of stored bounding box, and return 1 if it overlaps * any previously stored bounding boxes. * - If -2, leave the bounding boxes unchanged and return the * number of bounding boxes currently stored. No other action is taken * and all other arguments are ignored. * - Otherwise, reset the number of stored bounding boxes to the * value of mode, and return the new number of bounding boxes. No * action is taken if mode is less than zero or greater than the current * number of stored boxes. No other action is taken and all other * arguments are ignored. * esc * Should escape sequences in the text be interpreted? * text * A pointer to the label text string. * x * The graphics X coordinate of the label's reference point. * y * The graphics Y coordinate of the label's reference point. * just * A character string which specifies the location within the * text string which is to be placed at the reference position * given by x and y. The first character may be 'T' for "top", * 'C' for "centre", or 'B' for "bottom", and specifies the * vertical location of the reference position. The second * character may be 'L' for "left", 'C' for "centre", or 'R' * for "right", and specifies the horizontal location of the * reference position. If the string has less than 2 characters * then 'C' is used for the missing characters. * upx * The x component of the up-vector for the text. * upy * The y component of the up-vector for the text. * work * A pointer to a place at which to store a pointer to an array of * floats holding the old bounding boxes. Memory to hold this array * is allocated automatically within this function. The pointer to * the array should be supplied as NULL on the first call to this * function, and the array should be freed using astFree when no * longer needed. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * See parameter "mode." * Notes: * - Zero is returned if an error has occurred, or if this function * should fail for any reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ int nbox = 0; /* Number of boxes stored in "work" */ int ret; /* Does the new label overlap a previous label? */ int i; /* Box index */ float *cx; /* Pointer to next corner's X value */ float *cy; /* Pointer to next corner's Y value */ float xbn[ 4 ]; /* X coords at corners of new label's bounding box */ float ybn[ 4 ]; /* Y coords at corners of new label's bounding box */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Initialise the returned value to indicate no overlap has been found. */ ret = 0; /* Get the number of bounding boxes in the supplied work array. */ if( work && *work ) { nbox = (*work)[ 0 ]; } else { nbox = 0; } /* If required, return the number of bounding boxes currently stored. */ if( mode == -2 ) return nbox; /* If required, reset the number of bounding boxes currently stored, and return the new number. */ if( mode >= 0 ) { if( mode < nbox && work && *work ) { nbox = mode; (*work)[ 0 ] = nbox; } return nbox; } /* If no work array has been supplied, allocate one now with room for 10 boxes. Each box requires 8 floats, 2 for each of the 4 corners. The X graphics coordinates at the 4 corners are stored in the first 4 floats, and the corresponding Y graphics coordinates in the second group of 4 floats. */ if( work && !(*work) ) { *work = (float *) astMalloc( 81*sizeof(float) ); if( astOK ) { nbox = 0; (*work)[ 0 ] = 0; } } /* Check the global status. */ if( !astOK ) return ret; /* Get the bounds of the box containing the new label. */ DrawText( this, 0, esc, text, x, y, just, upx, upy, xbn, ybn, NULL, method, class, status ); /* If the bounding box was obtained succesfully... */ if( astOK ) { /* Check for an overlap between the box and each of the previous boxes. */ cx = *work + 1; cy = cx + 4; for( i = 0; i < nbox; i++ ){ if( BoxCheck( xbn, ybn, cx, cy, status ) ) { ret = 1; break; } /* Increment the pointers to the next box. */ cx += 8; cy += 8; } /* If no overlap was found, add the new box to the list. */ if( !ret ){ *work = (float *) astGrow( (void *) *work, 8*nbox + 9, sizeof(float) ); cx = *work + 1 + 8*nbox; cy = cx + 4; for( i = 0; i < 4; i++ ){ cx[ i ] = xbn[ i ]; cy[ i ] = ybn[ i ]; } (*work)[ 0 ]++; /* Extend the bounds of the global bounding box held externally to include the new box. */ for( i = 0; i < 4; i++ ){ Box_lbnd[ 0 ] = astMIN( xbn[ i ], Box_lbnd[ 0 ] ); Box_ubnd[ 0 ] = astMAX( xbn[ i ], Box_ubnd[ 0 ] ); Box_lbnd[ 1 ] = astMIN( ybn[ i ], Box_lbnd[ 1 ] ); Box_ubnd[ 1 ] = astMAX( ybn[ i ], Box_ubnd[ 1 ] ); } } } /* If an error has occur, return a value of 0. */ if( !astOK ) ret = 0; /* Return the answer. */ return ret; } static void PlotLabels( AstPlot *this, int esc, AstFrame *frame, int axis, LabelList *list, char *fmt, int nlab, float **box, const char *method, const char *class, int *status ) { /* * * Name: * PlotLabels * Purpose: * Draws the numerical labels which have been selected for display. * Type: * Private function. * Synopsis: * #include "plot.h" * void PlotLabels( AstPlot *this, int esc, AstFrame *frame, int axis, * LabelList *list, char *fmt, int nlab, float **box, * const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function displays the numerical labels supplied in the * structure pointed to by "list". Overlapping labels are omitted, * and redundant leading fields are removed from adjacent labels. * Nothing is plotted if the NumLab attribute for the axis is false. * Parameters: * this * A pointer to the Plot. * esc * Interpret escape sequences in labels? * frame * A pointer to the current Frame of the Plot. * axis * The axis index (0 or 1). * list * A pointer to the LabelList structure holding information about * the selected numerical labels. * fmt * A pointer to a null terminated string holding the format * specification used to create the labels. * nlab * The number of labels described by "list". * box * A pointer to a place at which to store a pointer to an array of * floats holding the bounding boxes of displayed labels. Memory to * hold this array is allocated automatically within this function. * The pointer to the array should be supplied as NULL on the first * call to this function, and the array should be freed using astFree * when no longer needed. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ LabelList *ll; /* Pointer to next label structure */ LabelList *llhi; /* Pointer to higher neighbouring label structure */ LabelList *lllo; /* Pointer to lower neighbouring label structure */ char *text; /* Pointer to label text */ const char *latext; /* Axis label at previous label */ const char *texthi; /* Pointer to text abbreviated with higher neighbour */ const char *textlo; /* Pointer to text abbreviated with lower neighbour */ float tolx; /* Min allowed X interval between labels */ float toly; /* Min allowed Y interval between labels */ float xbn[ 4 ]; /* X coords at corners of new label's bounding box */ float ybn[ 4 ]; /* Y coords at corners of new label's bounding box */ int abb; /* Abbreviate leading fields? */ int dp; /* Number of decimal places */ int found; /* Non-zero digit found? */ int hilen; /* Length of texthi */ int i; /* Label index */ int j; /* Label index offset */ int jgap; /* Gap in index between rejected labels */ int lab0; /* Index of middle label */ int lolen; /* Length of textlo */ int mxdp; /* Maximum number of decimal places */ int nbox; /* The number of boinding boxes supplied */ int nexti; /* Index of next label to retain */ int nleft; /* No. of labels left */ int nz; /* Number of trailing zeros in this label */ int nzmax; /* Max. number of trailing zeros */ int odd; /* DO we have a strange axis? */ int off; /* Offset from central label */ int olap; /* Any overlap found? */ int prio; /* Current priority */ int root; /* Index of unabbreviated label */ int root_found; /* Has the root label been decided on? */ int rootoff; /* Distance from middle to root label */ int split; /* Indicates whether to split labels into 2 lines */ /* Return without action if an error has occurred, or there are no labels to draw. */ if( !astOK || nlab == 0 || !list || !astGetNumLab( this, axis ) ) return; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ rootoff = 0; /* Get the number of bounding boxes describing the labels already drawn (this will be non-zero only if this is the second axis to be labelled). */ nbox = Overlap( this, -2, 0, NULL, 0.0, 0.0, NULL, 0.0, 0.0, box, method, class, status ); /* Ensure the labels are sorted into increasing index order. */ qsort( (void *) list, (size_t) nlab, sizeof(LabelList), Compare_LL ); /* Complex curves can have multiple edge crossings very close together. This means that the same label can sometimes be included more than once in the supplied list at the same (x,y) position. Purge duplicate labels by setting their priority to -1. Initialise the priority of the remaining labels to zero. */ tolx = 0.02*fabs( this->xhi - this->xlo ); toly = 0.02*fabs( this->yhi - this->ylo ); ll = list; ll->priority = 0; ll->saved_prio = 0; for( i = 1; i < nlab; i++ ) { ll++; ll->priority = 0; ll->saved_prio = 0; for( j = 0; j < i; j++ ){ if( !strcmp( ll->text, list[ j ].text ) ) { if( fabs( ll->x - list[ j ].x ) < tolx && fabs( ll->y - list[ j ].y ) < toly ) { ll->priority = -1; ll->saved_prio = -1; break; } } } } /* Find the maximum number of decimal places in any label. */ mxdp = 0; ll = list - 1; for( i = 0; i < nlab; i++ ) { ll++; FindDPTZ( frame, axis, fmt, ll->text, &dp, &nz, status ); if( dp > mxdp ) mxdp = dp; } /* Indicate that we do not yet know whether SplitValue should split labels into two lines or not. */ split = 0; /* Find the highest priority label (the "root" label). This label is never abbreviated to remove leading fields, and is never omitted due to overlaps with other labels. To find this label, each label is assigned a priority equal to the number of trailing zeros in the label text. If the text has fewer than the maximum number of decimal places, pretend the text is padded with trailing zeros to bring the number of decimal places up to the maximum. The root label is the highest priority label, giving preference to labels which occur in the middle of the index order. At the same time, initialize the abbreviated text for each label to be equal to the unabbreviated text. */ lab0 = nlab/2; nzmax = -1; ll = list - 1; root = -1; root_found = 0; for( i = 0; i < nlab; i++ ) { ll++; if( ll->priority > -1 ) { text = ll->text; /* Find the number of decimal places and the number of trailing zeros in this label. Note if a non-zero digit was found in the label. */ found = FindDPTZ( frame, axis, fmt, text, &dp, &nz, status ); /* Add on some extra trailing zeros to make the number of decimal places up to the maximum value. */ nz += mxdp - dp; /* Store the priority for this label. */ ll->priority = nz; ll->saved_prio = nz; /* Note the highest priority of any label. */ if( nz > nzmax ) nzmax = nz; /* We will use this label as the root label if: - We have not already found the root label AND - It does not overlap any labels drawn for a previous axis AND - We do not currently have a candidate root label, or - The priority for this label is higher than the priority of the current root label, or - The priority for this label is equal to the priority of the current root label and this label is closer to the centre of the axis, or - The label value is zero. */ if( root == -1 || nz > list[ root ].priority || ( nz == list[ root ].priority && abs( i - lab0 ) < rootoff ) || !found ) { if( !root_found ) { if( axis == 0 || !Overlap( this, -1, esc, SplitValue( this, ll->text, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, box, method, class, status ) ) { root = i; rootoff = abs( i - lab0 ); /* If the label value was zero, we will use label as the root label, regardless of the priorities of later labels. */ if( !found ) root_found = 1; } /* Reset the list of bounding boxes to exclude any box added above. */ Overlap( this, nbox, esc, NULL, 0.0, 0.0, NULL, 0.0, 0.0, box, method, class, status ); } } } /* Initialise the abbreviated text to be the same as the full text. */ ll->atext = ll->text; } /* If all the labels overlapped labels on a previous axis, arbitrarily use the label with non-genative priority that is closest to the middle as the root label (this should never happen but is included to avoid segmentation violations occurring in error conditions such as the txExt function being buggy and cuasing spurious overlaps). */ if( root == -1 ) { for( off = 0; off < (nlab-1)/2; off++ ) { root = nlab/2 + off; if( list[ root ].priority >= 0 ) break; root = nlab/2 - off; if( list[ root ].priority >= 0 ) break; } if( root == -1 ) { astError( AST__PLFMT, "%s(%s): Cannot produce labels for axis %d.", status, method, class, axis + 1 ); root = nlab/2; } } /* Assign a priority higher than any other priority to the root label. */ list[ root ].priority = nzmax + 1; list[ root ].saved_prio = nzmax + 1; /* See if leading fields are to be abbreviated */ abb = astGetAbbrev( this, axis ); /* The following process may have removed some labels which define the missing fields in neighbouring abbreviated fields, so that the user would not be able to tell what value the abbvreviated leading fields should have. We therefore loop back and perform the abbreviation process again, omitting the removed labels this time. Continue doing this until no further labels are removed. */ jgap = 1; olap = 1; odd = 0; while( olap && !odd ) { /* We now attempt to abbreviate the remaining labels (i.e. those which have not been rejected on an earlier pass through this loop). Labels are abbreviated in order of their priority. Higher priority labels are abbreviated first (except that the root label, which has the highest priority, is never abbreviated). Each label is abbreviated by comparing it with the nearest label with a higher priority. */ /* Loop through all the priority values, starting with the highest priority (excluding the root label so that the root label is never abbreviated), and working downwards to finish with zero priority. */ prio = nzmax + 1; while( prio-- > 0 ) { /* Look for labels which have the current priority. */ ll = list - 1; for( i = 0; i < nlab; i++ ) { ll++; if( ll->priority == prio ) { /* Find the closest label to this one on the high index side which has a higher priority. */ llhi = NULL; for( j = i + 1; j < nlab; j++ ) { if( list[ j ].priority > prio ) { llhi = list + j; break; } } /* If no higher priority neighbour was found on the high index side, use the nearest label with the current priority on the high index side. */ if( !llhi ) { for( j = i + 1; j < nlab; j++ ) { if( list[ j ].priority == prio ) { llhi = list + j; break; } } } /* Find the closest label to this one on the low index side which has a higher priority. */ lllo = NULL; for( j = i - 1; j >= 0; j-- ) { if( list[ j ].priority > prio ) { lllo = list + j; break; } } /* If no higher priority neighbour was found on the low index side, use the nearest label with the current priority on the low index side. */ if( !lllo ) { for( j = i - 1; j >= 0; j-- ) { if( list[ j ].priority == prio ) { lllo = list + j; break; } } } /* If we are not abbreviating, use the full text as the abbreviated text.*/ if( !abb ) { ll->atext = ll->text; /* Otherwise, if only one of these two neighbouring labels was found, we abbreviate the current label by comparing it with the one found neighbouring label. If they are identical, we use the last field as the abbreviated text. */ } else if( !lllo ) { ll->atext = astAbbrev( frame, axis, fmt, llhi->text, ll->text ); } else if( !llhi ) { ll->atext = astAbbrev( frame, axis, fmt, lllo->text, ll->text ); /* If two neighbouring labels were found, we abbreviate the current label by comparing it with both neighbouring labels, and choosing the shorter abbreviation. */ } else { textlo = abb ? astAbbrev( frame, axis, fmt, lllo->text, ll->text ) : ll->text; texthi = abb ? astAbbrev( frame, axis, fmt, llhi->text, ll->text ) : ll->text; lolen = strlen( textlo ); hilen = strlen( texthi ); if( lolen > 0 && lolen < hilen ) { ll->atext = textlo; } else { ll->atext = texthi; } } /* If the two fields are identical, the abbreviated text returned by astAbbrev will be a null string. In this case, find the start of the last field in the formatted value (using astAbbrev again), and use that as the abbreviated text. */ if( !(ll->atext)[0] ) { ll->atext = astAbbrev( frame, axis, fmt, NULL, ll->text ); } } } } /* Find the bounding box of the root label and add it to the list of bounding boxes. */ nleft = 1; ll = list + root; olap = Overlap( this, -1, esc, SplitValue( this, ll->atext, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, box, method, class, status ); /* Now look for labels which would overlap. First, check labels above the root label. Do not count overlaps where the two abbreviated labels have the same text. */ ll = list + root; latext = ll->atext; for( i = root + 1; i < nlab; i++ ) { ll++; if( ll->priority >= 0 ) { if( strcmp( ll->atext, latext ) ) { if( Overlap( this, -1, esc, SplitValue( this, ll->atext, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, box, method, class, status ) ){ olap++; } else { nleft++; } } latext = ll->atext; } } /* Now check the labels below the root label. */ ll = list + root; latext = ll->atext; for( i = root - 1; i >= 0; i-- ) { ll--; if( ll->priority >= 0 ) { if( strcmp( ll->atext, latext ) ) { if( Overlap( this, -1, esc, SplitValue( this, ll->atext, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, box, method, class, status ) ){ olap++; } else { nleft++; } } latext = ll->atext; } } /* If only one overlap was found, and this is the second axis, ignore it since it is probably caused by the crossing of the two axes. */ if( axis == 1 && olap == 1 ) olap = 0; /* If we are now only plotting every 3rd label, or if there are less than 3 labels left, and there are still overlapping labels, then we must have a very odd axis (such as logarithmically spaced ticks on a linearly mapped axis). In this case, we will re-instate the orignal label priorities and then leave this loop so that we attempt to plot all labels. Also retain original priorities if the axis is mapped logarithmically onto the screen. */ if( olap && ( jgap == 3 || nleft < 3 || astGetLogPlot( this, axis ) ) ){ jgap = 0; odd = 1; } else { odd = 0; } /* If any labels overlapped, re-instate the priority of all previously excluded labels (using the copy of the label's real priority stored in "saved_prio"), and then remove labels (by setting their priorities negative) to increase the gap between labels, and try again. */ if( olap ) { jgap++; nexti = root + jgap; for( i = root + 1; i < nlab; i++ ) { if( i == nexti ) { nexti += jgap; list[ i ].priority = list[ i ].saved_prio; } else { list[ i ].priority = -1; } } nexti = root - jgap; for( i = root - 1; i >= 0; i-- ) { if( i == nexti ) { nexti -= jgap; list[ i ].priority = list[ i ].saved_prio; } else { list[ i ].priority = -1; } } /* Reset the abbreviated text to be the full text. */ for( i = 0; i < nlab - 1; i++ ) list[ i ].atext = list[ i ].text; } /* Rest the list of bounding boxes to exclude the boxes added above. */ Overlap( this, nbox, esc, NULL, 0.0, 0.0, NULL, 0.0, 0.0, box, method, class, status ); } /* We can now draw the abbreviated labels (ignoring rejected labels). */ ll = list-1; for( i = 0; i < nlab; i++ ) { ll++; if( ll->priority >= 0 ) { /* Check that this label does not overlap any labels drawn for previous axes (we know from the above processing that it will not overlap any other label on the current axis). */ if( !Overlap( this, -1, esc, SplitValue( this, ll->atext, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, box, method, class, status ) ) { /* Draw the abbreviated label text, and get the bounds of the box containing the new label, splitting long formatted values (such as produced by TimeFrames) into two lines. */ DrawText( this, 1, esc, SplitValue( this, ll->atext, axis, &split, status ), (float) ll->x, (float) ll->y, ll->just, (float) ll->upx, (float) ll->upy, xbn, ybn, NULL, method, class, status ); } } } } static void PolyCurve( AstPlot *this, int npoint, int ncoord, int indim, const double *in, int *status ){ /* *++ * Name: c astPolyCurve f AST_POLYCURVE * Purpose: * Draw a series of connected geodesic curves. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astPolyCurve( AstPlot *this, int npoint, int ncoord, int indim, c const double *in ) f CALL AST_POLYCURVE( THIS, NPOINT, NCOORD, INDIM, IN, STATUS ) * Class Membership: * Plot method. * Description: c This function joins a series of points specified in the physical c coordinate system of a Plot by drawing a sequence of geodesic c curves. It is equivalent to making repeated use of the astCurve c function (q.v.), except that astPolyCurve will generally be more c efficient when drawing many geodesic curves end-to-end. A c typical application of this might be in drawing contour lines. f This routine joins a series of points specified in the physical f coordinate system of a Plot by drawing a sequence of geodesic f curves. It is equivalent to making repeated calls to the f AST_CURVE routine (q.v.), except that AST_POLYCURVE will f generally be more efficient when drawing many geodesic curves f end-to-end. A typical application of this might be in drawing f contour lines. * c As with astCurve, full account is taken of the Mapping between c physical and graphical coordinate systems. This includes any c discontinuities and clipping established using astClip. f As with AST_CURVE, full account is taken of the Mapping between f physical and graphical coordinate systems. This includes any f discontinuities and clipping established using AST_CLIP. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c npoint f NPOINT = INTEGER (Given) * The number of points between which geodesic curves are to be drawn. c ncoord f NCOORD = INTEGER (Given) * The number of coordinates being supplied for each point (i.e. * the number of axes in the current Frame of the Plot, as given * by its Naxes attribute). c indim f INDIM = INTEGER (Given) c The number of elements along the second dimension of the "in" f The number of elements along the first dimension of the IN * array (which contains the input coordinates). This value is * required so that the coordinate values can be correctly * located if they do not entirely fill this array. The value c given should not be less than "npoint". f given should not be less than NPOINT. c in f IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given) c The address of the first element in a 2-dimensional array of shape c "[ncoord][indim]" giving the c physical coordinates of the points which are to be joined in c sequence by geodesic curves. These should be stored such that c the value of coordinate number "coord" for point number c "point" is found in element "in[coord][point]". f A 2-dimensional array giving the physical coordinates of the f points which are to be joined in sequence by geodesic f curves. These should be stored such that the value of f coordinate number COORD for input point number POINT is found f in element IN(POINT,COORD). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - No curve is drawn on either side of any point which has any * coordinate equal to the value AST__BAD. * - An error results if the base Frame of the Plot is not * 2-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ const char *class; /* Object class */ const char *method; /* Current method */ const double **in_ptr; /* Pointer to array of data pointers */ double *finish; /* Pointer to array holding segment end position */ double *start; /* Pointer to array holding segment start position */ double d[ CRV_NPNT ]; /* Offsets to evenly spaced points along curve */ double tol; /* Absolute tolerance value */ double x[ CRV_NPNT ]; /* X coords at evenly spaced points along curve */ double y[ CRV_NPNT ]; /* Y coords at evenly spaced points along curve */ int coord; /* Loop counter for coordinates */ int i; /* Loop count */ int naxes; /* No. of Frame axes */ int ok; /* Are all start and end coords good? */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astPolyCurve"; class = astGetClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Initialise the bounding box for primatives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Check the current Frame of the Plot has ncoord axes. */ naxes = astGetNout( this ); if( naxes != ncoord && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the current " "Frame of the supplied %s is invalid - this number should " "be %d (possible programming error).", status, method, class, naxes, class, ncoord ); } /* Check the array dimension argument. */ if ( astOK && ( indim < npoint ) ) { astError( AST__DIMIN, "%s(%s): The array dimension value " "(%d) is invalid.", status, method, class, indim ); astError( AST__DIMIN, "This should not be less than the number of " "points being drawn (%d).", status, npoint ); } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Allocate memory to hold the array of data pointers, the start position, and the end position. */ if ( astOK ) { in_ptr = (const double **) astMalloc( sizeof( const double * ) * (size_t) ncoord ); start = (double *) astMalloc( sizeof( double ) * (size_t) ncoord ); finish = (double *) astMalloc( sizeof( double ) * (size_t) ncoord ); /* Set up externals used to communicate with the Map3 function... The number of axes in the physical coordinate system (i.e. the current Frame). */ Map3_ncoord = ncoord; /* A pointer to the Plot, the Current Frame, and and Mapping. */ Map3_plot = this; Map3_frame = astGetFrame( this, AST__CURRENT ); Map3_map = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Convert the tolerance from relative to absolute graphics coordinates. */ tol = astGetTol( this )*astMAX( this->xhi - this->xlo, this->yhi - this->ylo ); /* Ensure the globals holding the scaling from graphics coords to equally scaled coords are available. */ GScales( this, NULL, NULL, method, class, status ); /* Now set up the external variables used by the Crv and CrvLine function. */ Crv_scerr = ( astGetLogPlot( this, 0 ) || astGetLogPlot( this, 1 ) ) ? 100.0 : 1.5; Crv_tol = tol; Crv_limit = 0.5*tol*tol; Crv_map = Map3; Crv_ink = 1; Crv_xlo = this->xlo; Crv_xhi = this->xhi; Crv_ylo = this->ylo; Crv_yhi = this->yhi; Crv_clip = astGetClip( this ) & 1; /* Set up a list of points spread evenly over each curve segment. */ for( i = 0; i < CRV_NPNT; i++ ){ d[ i ] = ( (double) i)/( (double) CRV_NSEG ); } /* Initialise the data pointers to locate the coordinate data in the "in" array. */ if ( astOK ) { for ( coord = 0; coord < ncoord; coord++ ) { in_ptr[ coord ] = in + coord * indim; } /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__CURVE_ID, 1, GRF__LINE, method, class ); /* Loop round each curve segment. */ for( i = 1 ; i < npoint; i++ ) { /* Store the start position and check it for bad values. Increment the pointers to the next position on each axis, so that they refer to the finish point of the current curve segment. */ ok = 1; for( coord = 0; coord < ncoord; coord++ ) { if( *( in_ptr[coord] ) == AST__BAD ){ ok = 0; } else { start[ coord ] = *( in_ptr[coord] ); } ( in_ptr[coord] )++; } /* Store the end position and check it for bad values. Do not increment the axis pointers. This means that they will refer to the start position of the next curve segment on the next pass through this loop. */ for( coord = 0; coord < ncoord; coord++ ) { if( *( in_ptr[coord] ) == AST__BAD ){ ok = 0; } else { finish[ coord ] = *( in_ptr[coord] ); } } /* Pass on to the next curve segment if either the start or finish position was bad. */ if( ok ) { /* Set up the remaining externals used to communicate with the Map3 function... */ /* The physical coordinates at the start of the curve. */ Map3_origin = start; /* The physical coordinates at the end of the curve. */ Map3_end = finish; /* The scale factor to convert "dist" values into physical offset values. */ Map3_scale = astDistance( Map3_frame, start, finish ); /* Now set up the remaining external variables used by the Crv and CrvLine function. */ Crv_ux0 = AST__BAD; Crv_out = 1; Crv_xbrk = Curve_data.xbrk; Crv_ybrk = Curve_data.ybrk; Crv_vxbrk = Curve_data.vxbrk; Crv_vybrk = Curve_data.vybrk; /* Map the evenly spread distances between "start" and "finish" into graphics coordinates. */ Map3( CRV_NPNT, d, x, y, method, class, status GLOBALS_NAME ); /* Use Crv and Map3 to draw the curve segment. */ Crv( this, d, x, y, 0, NULL, NULL, method, class, status ); /* If no part of the curve could be drawn, set the number of breaks and the length of the drawn curve to zero. */ if( Crv_out ) { Crv_nbrk = 0; Crv_len = 0.0F; /* Otherwise, add an extra break to the returned structure at the position of the last point to be plotted. */ } else { Crv_nbrk++; if( Crv_nbrk > AST__PLOT_CRV_MXBRK ){ astError( AST__CVBRK, "%s(%s): Number of breaks in curve " "exceeds %d.", status, method, class, AST__PLOT_CRV_MXBRK ); } else { *(Crv_xbrk++) = (float) Crv_xl; *(Crv_ybrk++) = (float) Crv_yl; *(Crv_vxbrk++) = (float) -Crv_vxl; *(Crv_vybrk++) = (float) -Crv_vyl; } } /* Store extra information about the curve in the returned structure, and purge any zero length sections. */ Curve_data.length = Crv_len; Curve_data.out = Crv_out; Curve_data.nbrk = Crv_nbrk; PurgeCdata( &Curve_data, status ); } } /* End the last poly line. */ Opoly( this, status ); /* Tidy up the static data used by Map3. */ Map3( 0, NULL, NULL, NULL, method, class, status GLOBALS_NAME ); /* Ensure all lines are flushed to the graphics system. */ Fpoly( this, method, class, status ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__CURVE_ID, 0, GRF__LINE, method, class ); } /* Annul the Frame and Mapping. */ Map3_frame = astAnnul( Map3_frame ); Map3_map = astAnnul( Map3_map ); /* Free the memory used for the data pointers, and start and end positions. */ in_ptr = (const double **) astFree( (void *) in_ptr ); start = (double *) astFree( (void *) start ); finish = (double *) astFree( (void *) finish ); } } static int PopGat( AstPlot *this, float *rise, const char *method, const char *class, int *status ) { /* * Name: * PopGat * Purpose: * Pop current graphical attributes for text from a stack. * Type: * Private function. * Synopsis: * #include "plot.h" * int PopGat( AstPlot *this, float *rise, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function restores the current graphical attributes for text * from the values on a stack. Current attributes are left unchanged if * the stack is empty. * Parameters: * this * Pointer to the Plot. * rise * Pointer to a location at which to return thhe height of the baseline * above the normal baseline, expressed as a percentage of the normal * character height. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * Returns zero if the stack is empty, and 1 otherwise. */ /* Local Variables: */ AstGat *gat; int result; /* Initialise */ result = 0; /* Check inherited status */ if( !astOK ) return result; /* Check there is at least one AstGat structure on the stack. */ if( this->ngat ) { /* Decrement the number of entries in the stack, and get a pointer to the AstGat structure. Nullify the pointer on the stack. */ gat = (this->gat)[ --(this->ngat) ]; (this->gat)[ this->ngat ] = NULL; /* Restore the values in the AstGat structure */ *rise = gat->rise; GAttr( this, GRF__SIZE, gat->size, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__WIDTH, gat->width, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__COLOUR, gat->col, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__FONT, gat->font, NULL, GRF__TEXT, method, class, status ); GAttr( this, GRF__STYLE, gat->style, NULL, GRF__TEXT, method, class, status ); /* Free the AstGat structure. */ gat = astFree( gat ); /* Indicate success.*/ result = 1; } /* Return the result. */ return result; } static void PurgeCdata( AstPlotCurveData *cdata, int *status ){ /* * * Name: * AstPlotCurveData * Purpose: * Remove any zero length sections from the description of a curve. * Type: * Private function. * Synopsis: * #include "plot.h" * void PurgeCdata( AstPlotCurveData *cdata ) * Class Membership: * Plot member function. * Description: * This function removes any zero length sections from the supplied * AstPlotCurveData struture, which describes a multi-section curve. * Parameters: * cdata * A pointer to the structure containing information about the * breaks in a curve. */ /* Local Variables: */ int brk; /*Break index */ int i; /*Break index */ /* Check the global error status. */ if ( !astOK || !cdata ) return; /* Loop round all breaks. */ brk = 0; while( brk < cdata->nbrk ) { /* If this break and the next one are co-incident, remove both breaks. */ if( cdata->xbrk[ brk ] == cdata->xbrk[ brk + 1 ] && cdata->ybrk[ brk ] == cdata->ybrk[ brk + 1 ] ) { /* Shuffle down the higher elements of all the arrays in the curve data. */ for( i = brk + 2; i < cdata->nbrk; i++ ){ cdata->xbrk[ i - 2 ] = cdata->xbrk[ i ]; cdata->ybrk[ i - 2 ] = cdata->ybrk[ i ]; cdata->vxbrk[ i - 2 ] = cdata->vxbrk[ i ]; cdata->vybrk[ i - 2 ] = cdata->vybrk[ i ]; } /* Decrement the number of breaks in the curve data. */ cdata->nbrk -= 2; /* If the section is not zero length, move on to the next pair of breaks. */ } else { brk += 2; } } } static void PushGat( AstPlot *this, float rise, const char *method, const char *class, int *status ) { /* * Name: * PushGat * Purpose: * Push current graphical attributes for text onto a stack. * Type: * Private function. * Synopsis: * #include "plot.h" * void PushGat( AstPlot *this, float rise, const char *method, * const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function stores the current graphical attributes for text * on a stack. * Parameters: * this * Pointer to the Plot. * rise * The height of the baseline above the normal baseline, expressed * as a percentage of the normal character height. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstGat *new_gat; /* Check inherited status */ if( !astOK ) return; /* Allocate memory for a new AstGat structure to store the graphical attributes. */ new_gat = astMalloc( sizeof( AstGat ) ); if( astOK ) { /* Store the height of the current baseline above the normal baseline, expressed as a percentage of a normal character height. */ new_gat->rise = rise; /* Store the current graphical attribute values. */ GAttr( this, GRF__SIZE, AST__BAD, &(new_gat->size), GRF__TEXT, method, class, status ); GAttr( this, GRF__WIDTH, AST__BAD, &(new_gat->width), GRF__TEXT, method, class, status ); GAttr( this, GRF__FONT, AST__BAD, &(new_gat->font), GRF__TEXT, method, class, status ); GAttr( this, GRF__STYLE, AST__BAD, &(new_gat->style), GRF__TEXT, method, class, status ); GAttr( this, GRF__COLOUR, AST__BAD, &(new_gat->col), GRF__TEXT, method, class, status ); /* Increment the number of AstGat structures on the stack.*/ this->ngat++; /* Extend the array of AstGat pointers in the Plot structure so that there is room for the new one. */ this->gat = (AstGat **) astGrow( this->gat, this->ngat, sizeof( AstGat * ) ); if( astOK ) { /* Store the new pointer. */ (this->gat)[ this->ngat - 1 ] = new_gat; } } } static void RegionOutline( AstPlot *this, AstRegion *region, int *status ){ /* *++ * Name: c astRegionOutline f AST_RegionOutline * Purpose: * Draw the outline of an AST Region. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astRegionOutline( AstPlot *this, AstRegion *region ) f CALL AST_REGIONOUTLINE( THIS, REGION, STATUS ) * Class Membership: * Plot method. * Description: * This function draws an outline around the supplied AST Region object. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c region f REGION = INTEGER (Given) * Pointer to the Region. f STATUS = INTEGER (Given and Returned) f The global status. *-- */ /* Local Variables: */ AstFrameSet *fs; AstMapping *map; const char *class; const char *method; int ibase; int icurr; /* Check the global error status. */ if ( !astOK ) return; /* Store the current method, and the class of the supplied object for use in error messages.*/ method = "astRegionOutline"; class = astGetClass( this ); /* Save the base Frame index within the Plot, since astConvert will change it. */ ibase = astGetBase( this ); /* Get the FrameSet that converts from the current Frame of the Plot, to the Frame represented by the Region. Check a conversion was found. */ fs = astConvert( this, region, " " ); /* Re-instate the original base Frame. */ astSetBase( this, ibase ); /* Report an error if the Region could not be mapped into the current Frame of the Plot. */ if( !fs ) { if( astOK ) { astError( AST__NOCNV, "%s(%s): Cannot find a mapping from the " "%d-dimensional Plot coordinate system (%s) to the " "%d-dimensional Region coordinate system (%s).", status, method, class, astGetNout( this ), astGetTitle( this ), astGetNout( region ), astGetTitle( region ) ); } /* If a transformation from Plot to Region was found... */ } else { /* Add the Region as a new Frame into the Plot, connecting it to the current Frame using the FrameSet found above. It becomes the new current Frame. First record the index of the original current Frame since astAddFrame will modify the FrameSet to use a different current Frame. */ icurr = astGetCurrent( this ); map = astGetMapping( fs, AST__BASE, AST__CURRENT ); astAddFrame( this, icurr, map, region ); /* Draw the outline of the Region (now the current Frame in the Plot). */ astBorder( this ); /* Tidy up by removing the Region (i.e. the current Frame) from the Plot and re-instating the original current Frame. */ astRemoveFrame( this, AST__CURRENT ); astSetCurrent( this, icurr ); /* Free resources. */ map = astAnnul( map ); fs = astAnnul( fs ); } } static void RemoveFrame( AstFrameSet *this_fset, int iframe, int *status ) { /* * Name: * RemoveFrame * Purpose: * Remove a Frame from a Plot. * Type: * Public virtual function. * Synopsis: * #include "plot.h" * void RemoveFrame( AstFrameSet *this_fset, int iframe, int *status ) * Class Membership: * Plot member function (over-rides the astRemoveFrame public * method inherited from the FrameSet class). * Description: * This function removes a Frame from a Plot. All other Frames * in the Plot have their indices re-numbered from one (if * necessary), but are otherwise unchanged. * * If the index of the clipping Frame is changed, the index value * stored in the Plot is updated. If the clipping Frame itself is * removed, all clipping information is removed from the Plot. * Parameters: * this_fset * Pointer to the FrameSet component of the Plot. * iframe * The index within the Plot of the Frame to be removed. * This value should lie in the range from 1 to the number of * Frames in the Plot (as given by its Nframe attribute). * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot *this; /* Pointer to Plot structure */ int ifrm; /* Validated frame index */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_fset; /* Validate the frame index. */ ifrm = astValidateFrameIndex( this_fset, iframe, "astRemoveFrame" ); /* Invoke the parent astRemoveFrame method to remove the Frame. */ (*parent_removeframe)( this_fset, iframe, status ); /* If the index of the removed Frame is smaller than the clipping Frame index, then decrement the clipping Frame index so that the same Frame will be used in future. */ if( astOK ){ if( ifrm < this->clip_frame ){ (this->clip_frame)--; /* If the clipping fgrame itself has been removed, indicate that no clipping should nbow be performed. */ } else if( ifrm == this->clip_frame ){ astClip( this, AST__NOFRAME, NULL, NULL ); } } } static void RightVector( AstPlot *this, float *ux, float *uy, float *rx, float *ry, const char *method, const char *class, int *status ){ /* * Name: * RightVector * Purpose: * Return a vector in the direction of the base line of normal text. * Synopsis: * #include "plot.h" * void RightVector( AstPlot *this, float *ux, float *uy, float *rx, * float *ry, const char *method, const char *class, int *status ) * Description: * This function returns a vector which points from left to right along * the text baseline, taking account of any difference in the scales of * the x and y axes. It also scales the supplied up vector so that it has * a length equal to the height of normal text, and scales the returned * right vector to have the same length (on the screen) as the up vector. * Parameters: * this * The plot. * ux * Pointer to a float holding the x component of the up-vector for the * text, in graphics coords. Scaled on exit so that the up vector has * length equal to the height of normal text. * uy * Pointer to a float holding the y component of the up-vector for the * text, in graphics coords. Scaled on exit so that the up vector has * length equal to the height of normal text. * rx * Pointer to a double in which will be put the x component of a * vector parallel to the baseline of normal text. * ry * Pointer to a double in which will be put the y component of a * vector parallel to the baseline of normal text. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ float alpha; /* Scale factor for X axis */ float beta; /* Scale factor for Y axis */ float chv; float chh; float l; /* Normalisation constant */ float a; float b; float nl; /* Character height in standard coordinates */ /* Check inherited status */ if( !astOK ) return; /* Find the scale factors for the two axes which scale graphics coordinates into a "standard" coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, 3) Y values increase from bottom to top. */ GScales( this, &alpha, &beta, method, class, status ); /* Convert the up-vector into "standard" system in which the axes have equal scales, and increase left-to-right, bottom-to-top. */ *ux *= alpha; *uy *= beta; /* Normalise this up-vector. */ l = sqrt( (*ux)*(*ux) + (*uy)*(*uy) ); if( l <= 0.0 ) { *ux = 0.0; *uy = 1.0; } else { *ux /= l; *uy /= l; } /* Find the height in "standard" coordinates of "normal" text draw with the requested up-vector. */ GQch( this, &chv, &chh, method, class, status ); a = (*ux)/(chv*alpha); b = (*uy)/(chh*beta); nl = 1.0/sqrt( a*a + b*b ); /* Scale the up-vector so that is has length equal to the height of "normal" text with the specified up-vector. */ *ux *= nl; *uy *= nl; /* Get the vector along the base-line of the text, by rotating the up-vector by 90 degrees clockwise. */ *rx = *uy; *ry = -*ux; /* Convert both vectors back from standard coords to normal world coords */ *ux /= alpha; *uy /= beta; *rx /= alpha; *ry /= beta; } static void SaveTick( AstPlot *this, int axis, double gx, double gy, int major, int *status ){ /* * Name: * SaveTick * Purpose: * Save info about a drawn tick in the Plot structure. * Type: * Private function. * Synopsis: * #include "plot.h" * void SaveTick( AstPlot *this, int axis, double gx, double gy, * int major, int *status ) * Class Membership: * Plot member function. * Description: * This function stores the start position and type of each drawn * tick in the given Plot. * Parameters: * this * Pointer to the Plot. * axis * The zero-based axis index to which the tick refers. If a * negative value is specified then all information about drawn ticks * curently stored in the Plot is erased. * gx * The graphics X position at the start of the tick mark. * gy * The graphics Y position at the start of the tick mark. * major * Non-zero if the tick mark is a major tick. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int i; int *count; double *tickgx; double *tickgy; /* Free the tick info in the supplied Plot if required. Do this before checking the error status. */ if( axis < 0 ) { for( i = 0; i < 3; i++ ) { this->majtickgx[ i ] = astFree( this->majtickgx[ i ] ); this->majtickgy[ i ] = astFree( this->majtickgy[ i ] ); this->mintickgx[ i ] = astFree( this->mintickgx[ i ] ); this->mintickgy[ i ] = astFree( this->mintickgy[ i ] ); this->mintickcount[ i ] = 0; this->majtickcount[ i ] = 0; } return; } /* Check the global error status. */ if ( !astOK ) return; /* Get pointers to the arrays to use, and ensure the arrays are big enough to hold the new tick. */ if( major ) { count = this->majtickcount + axis; tickgx = this->majtickgx[ axis ]; tickgy = this->majtickgy[ axis ]; } else { count = this->mintickcount + axis; tickgx = this->mintickgx[ axis ]; tickgy = this->mintickgy[ axis ]; } /* Ensure the arrays are big enough to hold the new tick. */ i = *count; tickgx = astGrow( tickgx, i + 1, sizeof( double ) ); tickgy = astGrow( tickgy, i + 1, sizeof( double ) ); /* If memory was allocated succesfully, store the new tick information in the expanded arrays. */ if( astOK ) { tickgx[ i ] = gx; tickgy[ i ] = gy; *count = i + 1; /* Store the potentially updated array pointers. */ if( major ) { this->majtickgx[ axis ] = tickgx; this->majtickgy[ axis ] = tickgy; } else { this->mintickgx[ axis ] = tickgx; this->mintickgy[ axis ] = tickgy; } } } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Plot. * Type: * Private function. * Synopsis: * #include "plot.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Plot member function (over-rides the astSetAttrib protected * method inherited from the FrameSet class). * Description: * This function assigns an attribute value for a Plot, 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 Plot. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPlot *this; /* Pointer to the Plot structure */ char label[21]; /* Graphics item label */ const char *class; /* Pointer to class string */ double dval; /* Double attribute value */ int axis; /* Index for the axis */ int edge; /* Index of edge within list */ int id1; /* Plot object id */ int id2; /* Plot object id */ int id; /* Plot object id */ int ival; /* Int attribute value */ int len; /* Length of setting string */ int nax; /* Number of graphics frame axes */ int nc; /* Number of characters read by astSscanf */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_object; /* Get the number of base Frame axis (2 for a Plot, 3 for a Plot3D). */ nax = astGetNin( this ); /* Obtain the length of the setting string. */ len = (int) 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. */ /* Tol. */ /* ---- */ if ( nc = 0, ( 1 == astSscanf( setting, "tol= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetTol( this, dval ); /* Grid. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "grid= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetGrid( this, ival ); /* TickAll. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "tickall= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetTickAll( this, ival ); /* ForceExterior */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "forceexterior= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetForceExterior( this, ival ); /* Invisible. */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "invisible= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetInvisible( this, ival ); /* Border. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "border= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetBorder( this, ival ); /* ClipOp. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "clipop= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetClipOp( this, ival ); /* Clip. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "clip= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetClip( this, ival ); /* Grf. */ /* ---- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "grf= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetGrf( this, ival ); /* DrawTitle. */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "drawtitle= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetDrawTitle( this, ival ); /* DrawAxes. */ /* --------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "drawaxes= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetDrawAxes( this, axis, ival ); /* DrawAxes(axis). */ /* --------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "drawaxes(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetDrawAxes( this, axis - 1, ival ); /* Abbrev. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "abbrev= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetAbbrev( this, axis, ival ); /* Abbrev(axis). */ /* --------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "abbrev(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetAbbrev( this, axis - 1, ival ); /* Escape. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "escape= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetEscape( this, ival ); /* Edge(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "edge(%d)= %n%*s %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { edge = FullForm( "left right top bottom", setting + ival, setting, "astSet", astGetClass( this ), status ); if( edge == 0 ) { astSetEdge( this, axis - 1, LEFT ); } else if( edge == 1 ) { astSetEdge( this, axis - 1, RIGHT ); } else if( edge == 2 ) { astSetEdge( this, axis - 1, TOP ); } else if( edge == 3 ) { astSetEdge( this, axis - 1, BOTTOM ); } /* LabelAt (axis). */ /* --------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "labelat(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetLabelAt( this, axis - 1, dval ); /* Centre(axis). */ /* ------------ */ } else if ( nc = 0, ( 2 == astSscanf( setting, "centre(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetCentre( this, axis - 1, dval ); /* Gap. */ /* ---- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "gap= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetGap( this, axis, dval ); /* Gap(axis). */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "gap(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetGap( this, axis - 1, dval ); /* LogGap. */ /* ---- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "loggap= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLogGap( this, axis, dval ); /* LogGap(axis). */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "loggap(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetLogGap( this, axis - 1, dval ); /* NumLabGap. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "numlabgap= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetNumLabGap( this, axis, dval ); /* NumLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "numlabgap(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetNumLabGap( this, axis - 1, dval ); /* TextLabGap. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "textlabgap= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetTextLabGap( this, axis, dval ); /* TextLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "textlabgap(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetTextLabGap( this, axis - 1, dval ); /* LabelUp. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "labelup= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLabelUp( this, axis, ival ); /* LabelUp(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "labelup(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetLabelUp( this, axis - 1, ival ); /* LogPlot. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "logplot= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLogPlot( this, axis, ival ); /* LogPlot(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "logplot(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetLogPlot( this, axis - 1, ival ); /* LogTicks. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "logticks= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLogTicks( this, axis, ival ); /* LogTicks(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "logticks(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetLogTicks( this, axis - 1, ival ); /* LogLabel. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "loglabel= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLogLabel( this, axis, ival ); /* LogLabel(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "loglabel(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetLogLabel( this, axis - 1, ival ); /* NumLab. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "numlab= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetNumLab( this, axis, ival ); /* NumLab(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "numlab(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetNumLab( this, axis - 1, ival ); /* MinTick. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "mintick= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetMinTick( this, axis, ival ); /* MinTick(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "mintick(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetMinTick( this, axis - 1, ival ); /* TextLab. */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "textlab= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetTextLab( this, axis, ival ); /* TextLab(axis). */ /* ---------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "textlab(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetTextLab( this, axis - 1, ival ); /* LabelUnits. */ /* --------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "labelunits= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetLabelUnits( this, axis, ival ); /* LabelUnits(axis). */ /* ---------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "labelunits(%d)= %d %n", &axis, &ival, &nc ) ) && ( nc >= len ) ) { astSetLabelUnits( this, axis - 1, ival ); /* Style. */ /* ------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "style= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetStyle( this, id, ival ); /* Style(label). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "style(%20[^()])= %d %n", label, &ival, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Style", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetStyle( this, id1, ival ); if( nid > 1 ) astSetStyle( this, id2, ival ); if( nid > 2 ) astSetStyle( this, id3, ival ); /* Font. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "font= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetFont( this, id, ival ); /* Font(label). */ /* ------------ */ } else if ( nc = 0, ( 2 == astSscanf( setting, "font(%20[^()])= %d %n", label, &ival, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Font", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetFont( this, id1, ival ); if( nid > 1 ) astSetFont( this, id2, ival ); if( nid > 2 ) astSetFont( this, id3, ival ); /* Colour. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "colour= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetColour( this, id, ival ); /* Colour(label). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "colour(%20[^()])= %d %n", label, &ival, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Colour", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetColour( this, id1, ival ); if( nid > 1 ) astSetColour( this, id2, ival ); if( nid > 2 ) astSetColour( this, id3, ival ); /* Color. */ /* ------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "color= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetColour( this, id, ival ); /* Color(label). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "color(%20[^()])= %d %n", label, &ival, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Color", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetColour( this, id1, ival ); if( nid > 1 ) astSetColour( this, id2, ival ); if( nid > 2 ) astSetColour( this, id3, ival ); /* Width. */ /* ------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "width= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetWidth( this, id, dval ); /* Width(label). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "width(%20[^()])= %lg %n", label, &dval, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Width", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetWidth( this, id1, dval ); if( nid > 1 ) astSetWidth( this, id2, dval ); if( nid > 2 ) astSetWidth( this, id3, dval ); /* Size. */ /* ----- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "size= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( id = 0; id < AST__NPID; id++ ) astSetSize( this, id, dval ); /* Size(label). */ /* ------------ */ } else if ( nc = 0, ( 2 == astSscanf( setting, "size(%20[^()])= %lg %n", label, &dval, &nc ) ) && ( nc >= len ) ) { class = astGetClass( this ); nid = IdFind( FullForm( GrfLabels, label, "Size", "astSet", class, status ), nax, &id1, &id2, &id3, status ); astSetSize( this, id1, dval ); if( nid > 1 ) astSetSize( this, id2, dval ); if( nid > 2 ) astSetSize( this, id3, dval ); /* TitleGap. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "titlegap= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetTitleGap( this, dval ); /* MajTickLen. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "majticklen= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetMajTickLen( this, axis, dval ); /* MajTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "majticklen(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetMajTickLen( this, axis - 1, dval ); /* MinTickLen. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "minticklen= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { for( axis = 0; axis < nax; axis++ ) astSetMinTickLen( this, axis, dval ); /* MinTickLen(axis). */ /* ----------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "minticklen(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetMinTickLen( this, axis - 1, dval ); /* Labelling. */ /* -------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "labelling= %n%*s %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetLabelling( this, FullForm( "exterior interior", setting + ival, setting, "astSet", astGetClass( this ), status ) ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } /* Undefine macros local to this function. */ #undef MATCH } static void SetLogPlot( AstPlot *this, int axis, int ival, int *status ){ /* * * Name: * SetLogPlot * Purpose: * Set a new value for a LogPlot attribute * Type: * Private function. * Synopsis: * #include "plot.h" * void SetLogPlot( AstPlot *this, int axis, int ival, int *status ) * Class Membership: * Plot member function * Description: * Assigns a new value to the LogPlot attribute of the specified axis, * and also re-maps the base Frame of the Plot if necessary. * Parameters: * this * The Plot. * axis * Zero based axis index. * ival * The new value for the ogPlot attribute. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int oldval; /* Original attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index. */ if( axis < 0 || axis >= 2 ){ astError( AST__AXIIN, "astSetLogPlot(%s): Index (%d) is invalid for " "attribute LogPlot - it should be in the range 1 to 2.", status, astGetClass( this ), axis + 1 ); /* If the axis index is OK, store the original attribute value. We use astGetLogPlot to get the value rather than directly accessing "this->logplot" in order to get the any default value in the case of no value having been set. */ } else { oldval = astGetLogPlot( this, axis ); /* If the current attribute value will change, attempt to re-map the plot axis. If the attempt succeeds, toggle the current attribute value. */ if( ( ival != 0 ) != ( oldval != 0 ) ){ if( ToggleLogLin( this, axis, oldval, "astSetLogPlot", status ) ){ this->logplot[ axis ] = ( !oldval ); } /* If the current attribute value will not change, just store the supplied value (this is not redundant because it may cause a previously defaulted value to become an explicitly set value ). */ } else { this->logplot[ axis ] = oldval; } } } static void SetTickValues( AstPlot *this, int axis, int nmajor, double *major, int nminor, double *minor, int *status ){ /* *+ * Name: * astSetTickValues * Purpose: * Store the tick mark values to use for a given Plot axis. * Type: * Protected virtual function. * Synopsis: * #include "plot.h" * void astSetTickValues( AstPlot *this, int axis, int nmajor, * double *major, int nminor, double *minor ) * Class Membership: * Plot method. * Description: * This function stores a set of tick mark values that should be used by * subsequent calls to astGrid. * Parameters: * this * Pointer to a Plot. * axis * The zero-based index of the axis for which tick marks values * have been supplied. * nmajor * The number of major tick mark values. If zero is supplied then * the other parameters are ignored, and subsequent calls to * astGrid will itself determine the tick values to be used. * major * Pointer to an array holding "nmajor" values for axis "axis" in * the current Frame of the suppled Plot. Major tick marks will be * drawn at these values. * nminor * The number of minor tick mark values. * minor * Pointer to an array holding "nminor" values for axis "axis" in * the current Frame of the suppled Plot. Minor tick marks will be * drawn at these values. *- */ /* Check the global status. */ if( !astOK ) return; /* Report an error if the supplied axis value is incorrect. */ if( axis < 0 || axis >= astGetNin( this ) ) { astError( AST__INTER, "astSetTickValues(Plot): Supplied \"axis\" " "value is %d - should in the range 0 to %d (internal AST " "programming error).", status, axis, astGetNin( this ) - 1 ); /* Otherwise store or clear the values. */ } else if( nmajor > 0 ){ this->nmajtickval[ axis ] = nmajor; this->majtickval[ axis ] = astStore( this->majtickval[ axis ], major, sizeof( double )*nmajor ); this->nmintickval[ axis ] = nminor; this->mintickval[ axis ] = astStore( this->mintickval[ axis ], minor, sizeof( double )*nminor ); /* Sort them into increasing order. */ qsort( (void *) this->majtickval[ axis ], (size_t) nmajor, sizeof(double), Compared ); qsort( (void *) this->mintickval[ axis ], (size_t) nminor, sizeof(double), Compared ); } else { this->nmajtickval[ axis ] = 0; this->majtickval[ axis ] = astFree( this->majtickval[ axis ] ); this->nmintickval[ axis ] = 0; this->mintickval[ axis ] = astFree( this->mintickval[ axis ] ); } } const char *astStripEscapes_( const char *text, int *status ) { /* *++ * Name: c astStripEscapes f AST_STRIPESCAPES * Purpose: * Remove AST escape sequences from a string. * Type: * Public function. * Synopsis: c #include "plot.h" c const char *astStripEscapes( const char *text ) f RESULT = AST_STRIPESCAPES( TEXT ) * Description: * This function removes AST escape sequences from a supplied string, * returning the resulting text as the function value. The behaviour * of this function can be controlled by invoking the c astEscapes function, f AST_ESCAPES routine, * which can be used to supress or enable the removal of escape * sequences by this function. * * AST escape sequences are used by the Plot class to modify the * appearance and position of sub-strings within a plotted text string. * See the "Escape" attribute for further information. * Parameters: c text c Pointer to the string to be checked. f TEXT f The string to be checked. * Returned Value: c astStripEscapes() f AST_STRIPESCAPES = CHARACTER c Pointer to the modified string. If no escape sequences were found c in the supplied string, then a copy of the supplied pointer is c returned. Otherwise, the pointer will point to a static buffer c holding the modified text. This text will be over-written by c subsequent invocations of this function. If the astEscapes function f The modified string. If the AST_ESCAPES routine * has been called indicating that escape sequences should not be * stripped, then the supplied string is returned without change. *-- */ /* Local Variables: */ astDECLARE_GLOBALS const char *a; char *b; int nc; int ncc; int type; int value; const char *result; /* Initialise */ result= text; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check inherited status and supplied pointer. Also return if the string contains no escape sequences or if stripping of escapes has been supressed. */ if( !astOK || astEscapes( -1 ) || !text || !HasEscapes( text, status ) ) return result; /* Initialise a pointer to the next character to be read from the supplied string. */ a = text; /* Initialise a pointer to the next character to be written to the returned string. */ b = stripescapes_buff; /* Note the available space left in the buffer. */ ncc = AST__PLOT_STRIPESCAPES_BUFF_LEN; /* Loop until all the string has been read, or the buffer is full. */ while( *a && ncc > 0 ){ /* If the remaining string starts with an escape sequence, increment the read point by the length of the escape sequence, but leave the write pointer where it is. */ if( astFindEscape( a, &type, &value, &nc ) ) { a += nc; /* If the remaining string does not start with an escape sequence, copy the following text from the read position to the write position. */ } else { if( nc > ncc ) nc = ncc; memcpy( b, a, sizeof( char )*nc ); a += nc; b += nc; ncc -= nc; } } /* Terminate the returned string. */ *b = 0; /* Return the result.*/ return stripescapes_buff; } static int swapEdges( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, int *status ) { /* * Name: * swapEdges * Purpose: * Determine if edges for text labels should be swapped. * Type: * Private function. * Synopsis: * #include "plot.h" * int swapEdges( AstPlot *this, TickInfo **grid, AstPlotCurveData **cdata, int *status ) * Class Membership: * Plot member function. * Description: * This function returns a boolean result (0 or 1) to indicate whether * or not it is necessary to swap the Edges(0) and Edges(1) attributes * in order to place textual labels on appropriate edges. This should * only be used if the attributes have not explicitly been set, and if * interior labelling is being used. The sides are determines by * looking at the bounding box of tick marks on axis 0, in graphics * coordinates. The returned value causes the label for axis 0 to be * placed on the edge parallel to the longest side of this bounding box. * The label for axis 1 is placed parallel to the shortest side of this * bounding box. * Parameters: * this * A pointer to the Plot. * grid * A pointer to an array of two TickInfo pointers (one for each axis), * each pointing to a TickInfo structure holding information about * tick marks on the axis. See function GridLines. * cdata * A pointer to an array of two AstPlotCurveData pointers (one for each axis), * each pointing to an array of AstPlotCurveData structure (one for each * major tick value on the axis), holding information about breaks * in the curves drawn to mark the major tick values. See function * DrawGrid. * status * Pointer to the inherited status variable. * Returned Value: * One if the edges should be swapped, 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: */ AstPlotCurveData *cdt; /* Pointer to the AstPlotCurveData for the next tick */ TickInfo *info; /* Pointer to the TickInfo for the current axis */ float xmax; /* Max graphics X value */ float xmin; /* Min graphics X value */ float ymax; /* Max graphics Y value */ float ymin; /* Min graphics Y value */ int oldedge; /* The original edge for axis 0 */ int result; /* Swap edges? */ int tick; /* Tick index */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the structure containing information describing the positions of the major tick marks along axis 0. */ info = grid[ 0 ]; /* Get a pointer to the structure containing information describing the breaks in the curve which is parallel to axis 1 and passes through the first major tick mark on axis 0. */ cdt = cdata[ 0 ]; /* Initialise the graphiocs X and Y bounds of the area covered by the axis. */ xmax = -1.0E10; xmin = 1.0E10; ymax = -1.0E10; ymin = 1.0E10; /* Loop round each of the major tick marks on axis 0. */ for( tick = 0; cdt && info && tick < info->nmajor; tick++ ){ /* Update the max and min graphics X and Y coords covered by the axis. */ if( cdt->nbrk > 0 ) { xmax = astMAX( xmax, cdt->xbrk[0] ); xmin = astMIN( xmin, cdt->xbrk[0] ); ymax = astMAX( ymax, cdt->ybrk[0] ); ymin = astMIN( ymin, cdt->ybrk[0] ); } /* Get a pointer to the curve through the next major tick mark. */ cdt++; } /* See which edge axis 0 would normally be labelled on. */ oldedge = astGetEdge( this, 0 ); /* If the X range is larger than the Y range, the textual label should be placed on the bottom edge. If required, indicate that the edges must be swapped to achieve this. */ if( xmax - xmin > ymax - ymin ) { if( oldedge == 0 || oldedge == 2 ) result = 1; /* If the X range is smaller than the Y range, the textual label should be placed on the left edge. If required, indicate that the edges must be swapped to achieve this. */ } else { if( oldedge == 1 || oldedge == 3 ) result = 1; } 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 Plot. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Plot member function (over-rides the astTestAttrib protected * method inherited from the FrameSet class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Plot's attributes. * Parameters: * this * Pointer to the Plot. * 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: */ AstPlot *this; /* Pointer to the Plot structure */ char label[21]; /* Graphics item label */ int axis; /* Axis number */ int len; /* Length of attrib string */ int nax; /* Number of base Frame axes */ int nc; /* No. characters read by astSscanf */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_object; /* Get the number of base Frame axis (2 for a Plot, 3 for a Plot3D). */ nax = astGetNin( this ); /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* Tol. */ /* ---- */ if ( !strcmp( attrib, "tol" ) ) { result = astTestTol( this ); /* Edge(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "edge(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestEdge( this, axis - 1 ); /* Grid. */ /* ----- */ } else if ( !strcmp( attrib, "grid" ) ) { result = astTestGrid( this ); /* TickAll. */ /* -------- */ } else if ( !strcmp( attrib, "tickall" ) ) { result = astTestTickAll( this ); /* ForceExterior */ /* ------------- */ } else if ( !strcmp( attrib, "forceexterior" ) ) { result = astTestForceExterior( this ); /* Invisible. */ /* ---------- */ } else if ( !strcmp( attrib, "invisible" ) ) { result = astTestInvisible( this ); /* Border. */ /* ------- */ } else if ( !strcmp( attrib, "border" ) ) { result = astTestBorder( this ); /* ClipOp. */ /* ------- */ } else if ( !strcmp( attrib, "clipop" ) ) { result = astTestClipOp( this ); /* Clip. */ /* ----- */ } else if ( !strcmp( attrib, "clip" ) ) { result = astTestClip( this ); /* Grf. */ /* ---- */ } else if ( !strcmp( attrib, "grf" ) ) { result = astTestGrf( this ); /* DrawTitle. */ /* ---------- */ } else if ( !strcmp( attrib, "drawtitle" ) ) { result = astTestDrawTitle( this ); /* DrawAxes. */ /* --------- */ } else if ( !strcmp( attrib, "drawaxes" ) ) { result = astTestDrawAxes( this, 0 ); /* DrawAxes(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "drawaxes(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestDrawAxes( this, axis - 1 ); /* Abbrev. */ /* --------- */ } else if ( !strcmp( attrib, "abbrev" ) ) { result = astTestAbbrev( this, 0 ); /* Abbrev(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "abbrev(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestAbbrev( this, axis - 1 ); /* Escape. */ /* ------- */ } else if ( !strcmp( attrib, "escape" ) ) { result = astTestEscape( this ); /* Gap. */ /* ---- */ } else if ( !strcmp( attrib, "gap" ) ) { result = astTestGap( this, 0 ); /* Gap(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "gap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestGap( this, axis - 1 ); /* LabelAt(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelat(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLabelAt( this, axis - 1 ); /* LogGap. */ /* ---- */ } else if ( !strcmp( attrib, "loggap" ) ) { result = astTestLogGap( this, 0 ); /* LogGap(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loggap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLogGap( this, axis - 1 ); /* NumLabGap. */ /* --------- */ } else if ( !strcmp( attrib, "numlabgap" ) ) { result = astTestNumLabGap( this, 0 ); /* NumLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestNumLabGap( this, axis - 1 ); /* TextLabGap. */ /* --------- */ } else if ( !strcmp( attrib, "textlabgap" ) ) { result = astTestTextLabGap( this, 0 ); /* TextLabGap(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlabgap(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestTextLabGap( this, axis - 1 ); /* LabelUp. */ /* -------- */ } else if ( !strcmp( attrib, "labelup" ) ) { result = astTestLabelUp( this, 0 ); /* LabelUp(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelup(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLabelUp( this, axis - 1 ); /* LogPlot. */ /* -------- */ } else if ( !strcmp( attrib, "logplot" ) ) { result = astTestLogPlot( this, 0 ); /* LogPlot(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logplot(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLogPlot( this, axis - 1 ); /* LogTicks. */ /* -------- */ } else if ( !strcmp( attrib, "logticks" ) ) { result = astTestLogTicks( this, 0 ); /* LogTicks(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "logticks(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLogTicks( this, axis - 1 ); /* LogLabel. */ /* -------- */ } else if ( !strcmp( attrib, "loglabel" ) ) { result = astTestLogLabel( this, 0 ); /* LogLabel(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "loglabel(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLogLabel( this, axis - 1 ); /* NumLab. */ /* -------- */ } else if ( !strcmp( attrib, "numlab" ) ) { result = astTestNumLab( this, 0 ); /* NumLab(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "numlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestNumLab( this, axis - 1 ); /* MinTick. */ /* -------- */ } else if ( !strcmp( attrib, "mintick" ) ) { result = astTestMinTick( this, 0 ); /* MinTick(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "mintick(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestMinTick( this, axis - 1 ); /* TextLab. */ /* ---------- */ } else if ( !strcmp( attrib, "textlab" ) ) { result = astTestTextLab( this, 0 ); /* TextLab(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "textlab(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestTextLab( this, axis - 1 ); /* LabelUnits. */ /* --------- */ } else if ( !strcmp( attrib, "labelunits" ) ) { result = astTestLabelUnits( this, 0 ); /* LabelUnits(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "labelunits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLabelUnits( this, axis - 1 ); /* Style. */ /* ------ */ } else if ( !strcmp( attrib, "style" ) ) { result = TestUseStyle( this, AST__BORDER_ID, status ); /* Style(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "style(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseStyle( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* Font. */ /* ----- */ } else if ( !strcmp( attrib, "font" ) ) { result = TestUseFont( this, AST__TEXTLABS_ID, status ); /* Font(label). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "font(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseFont( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* Colour. */ /* ------- */ } else if ( !strcmp( attrib, "colour" ) ) { result = TestUseColour( this, AST__TEXTLABS_ID, status ); /* Color. */ /* ------- */ } else if ( !strcmp( attrib, "color" ) ) { result = TestUseColour( this, AST__TEXTLABS_ID, status ); /* Colour(label). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "colour(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseColour( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* Color(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "color(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseColour( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* Width. */ /* ------ */ } else if ( !strcmp( attrib, "width" ) ) { result = TestUseWidth( this, AST__BORDER_ID, status ); /* Width(label). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "width(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseWidth( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* Size. */ /* ----- */ } else if ( !strcmp( attrib, "size" ) ) { result = TestUseSize( this, AST__TEXTLABS_ID, status ); /* Size(label). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "size(%20[^()])%n", label, &nc ) ) && ( nc >= len ) ) { result = TestUseSize( this, FullForm( GrfLabels, label, attrib, "astTest", astGetClass( this ), status ), status ); /* TitleGap. */ /* --------- */ } else if ( !strcmp( attrib, "titlegap" ) ) { result = astTestTitleGap( this ); /* MajTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "majticklen" ) ) { result = astTestMajTickLen( this, 0 ); /* MajTickLen(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "majticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestMajTickLen( this, axis - 1 ); /* MinTickLen. */ /* ----------- */ } else if ( !strcmp( attrib, "minticklen" ) ) { result = astTestMinTickLen( this, 0 ); /* MinTickLen(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "minticklen(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestMinTickLen( this, axis - 1 ); /* Labelling. */ /* -------- */ } else if ( !strcmp( attrib, "labelling" ) ) { result = astTestLabelling( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static void Text( AstPlot *this, const char *text, const double pos[], const float up[], const char *just, int *status ){ /* *++ * Name: c astText f AST_TEXT * Purpose: * Draw a text string for a Plot. * Type: * Public virtual function. * Synopsis: c #include "plot.h" c void astText( AstPlot *this, const char *text, const double pos[], c const float up[], const char *just ) f CALL AST_TEXT( THIS, TEXT, POS, UP, JUST, STATUS ) * Class Membership: * Plot method. * Description: * This function draws a string of text at a position specified in * the physical coordinate system of a Plot. The physical position * is transformed into graphical coordinates to determine where the * text should appear within the plotting area. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Plot. c text f TEXT = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string containing the f A character string containing the * text to be drawn. Trailing white space is ignored. c pos f POS( * ) = DOUBLE PRECISION (Given) * An array, with one element for each axis of the Plot, giving * the physical coordinates of the point where the reference * position of the text string is to be placed. c up f UP( * ) = REAL (Given) * An array holding the components of a vector in the "up" * direction of the text (in graphical coordinates). For c example, to get horizontal text, the vector {0.0f,1.0f} should f example, to get horizontal text, the vector [0.0,1.0] should * be supplied. For a basic Plot, 2 values should be supplied. For * a Plot3D, 3 values should be supplied, and the actual up vector * used is the projection of the supplied up vector onto the text plane * specified by the current value of the Plot3D's Norm attribute. c just f JUST = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string identifying the f A character string identifying the * reference point for the text being drawn. The first character in * this string identifies the reference position in the "up" direction * and may be "B" (baseline), "C" (centre), "T" (top) or "M" (bottom). * The second character identifies the side-to-side reference position * and may be "L" (left), "C" (centre) or "R" (right ). The string is * case-insensitive, and only the first two characters are significant. * * For example, a value of "BL" means that the left end of the * baseline of the original (un-rotated) text is to be drawn at the c position given by "pos". f position given by POS. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - The Plot3D class currently does not interpret graphical escape * sequences contained within text displayed using this method. * - Text is not drawn at positions which have any coordinate equal * to the value AST__BAD (or where the transformation into * graphical coordinates yields coordinates containing the value * AST__BAD). c - If the plotting position is clipped (see astClip), then no f - If the plotting position is clipped (see AST_CLIP), then no * text is drawn. * - An error results if the base Frame of the Plot is not * 2-dimensional or (for a Plot3D) 3-dimensional. * - An error also results if the transformation between the * current and base Frames of the Plot is not defined (i.e. the * Plot's TranInverse attribute is zero). *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *mapping; /* Pointer to graphics->physical mapping */ AstPointSet *pset1; /* PointSet holding physical positions */ AstPointSet *pset2; /* PointSet holding graphics positions */ const char *class; /* Object class */ const char *method; /* Current method */ const double **ptr1; /* Pointer to physical positions */ char ljust[3]; /* Upper case copy of "just" */ char *ltext; /* Local copy of "text" excluding trailing spaces */ double **ptr2; /* Pointer to graphics positions */ float xbn[ 4 ]; /* X coords of text bounding box. */ float ybn[ 4 ]; /* Y coord of text bounding box. */ int axis; /* Axis index */ int escs; /* Original astEscapes value */ int naxes; /* No. of axes in the base Frame */ int ncoord; /* No. of axes in the current Frame */ int ulen; /* Length of "text" excluding trailing spaces */ /* Check the global error status. */ if ( !astOK || !text ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Store the current method and class for inclusion in error messages generated by lower level functions. */ method = "astText"; class = astClass( this ); /* Check the base Frame of the Plot is 2-D. */ naxes = astGetNin( this ); if( naxes != 2 && astOK ){ astError( AST__NAXIN, "%s(%s): Number of axes (%d) in the base " "Frame of the supplied %s is invalid - this number should " "be 2.", status, method, class, naxes, class ); } /* Ensure AST functions included graphical escape sequences in any returned text strings. */ escs = astEscapes( 1 ); /* Initialise the bounding box for primatives produced by this call. */ if( !Boxp_freeze ) { Boxp_lbnd[ 0 ] = FLT_MAX; Boxp_lbnd[ 1 ] = FLT_MAX; Boxp_ubnd[ 0 ] = FLT_MIN; Boxp_ubnd[ 1 ] = FLT_MIN; } /* Indicate that the GRF module should re-calculate it's cached values (in case the state of the graphics system has changed since the last thing was drawn). */ RESET_GRF; /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__TEXT_ID, 1, GRF__TEXT, method, class ); /* Get the number of coordinates in the physical coordinate frame. */ ncoord = astGetNout( this ); /* Create a PointSet to hold the supplied physical coordinates. */ pset1 = astPointSet( 1, ncoord, "", status ); /* Allocate memory to hold pointers to the first value on each axis. */ ptr1 = (const double **) astMalloc( sizeof( const double * )* (size_t)( ncoord )); /* Check the pointer can be used, then store pointers to the first value on each axis. */ if( astOK ){ for( axis = 0; axis < ncoord; axis++ ){ ptr1[ axis ] = pos + axis; } } /* Store these pointers in the PointSet. */ astSetPoints( pset1, (double **) ptr1 ); /* Transform the supplied data from the current frame (i.e. physical coordinates) to the base frame (i.e. graphics coordinates) using the inverse Mapping defined by the Plot. */ mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); pset2 = Trans( this, NULL, mapping, pset1, 0, NULL, 0, method, class, status ); mapping = astAnnul( mapping ); /* Get pointers to the graphics coordinates. */ ptr2 = astGetPoints( pset2 ); /* Take a copy of the string excluding any trailing white space. */ ulen = ChrLen( text, status ); ltext = (char *) astStore( NULL, (void *) text, ulen + 1 ); /* Check the pointers can be used. */ if( astOK ){ /* Terminate the local copy of the text string. */ ltext[ ulen ] = 0; /* Produce an upper-case copy of the first two characters in "just". */ ljust[0] = (char) toupper( (int) just[0] ); ljust[1] = (char) toupper( (int) just[1] ); ljust[2] = 0; /* Convert the double precision values to single precision, checking for bad positions. */ if( ptr2[0][0] != AST__BAD && ptr2[1][0] != AST__BAD ){ /* Draw the text string. */ DrawText( this, 1, astGetEscape( this ), ltext, (float) ptr2[0][0], (float) ptr2[1][0], ljust, up[ 0 ], up[ 1 ], xbn, ybn, NULL, method, class, status ); } /* Free the local copy of the string. */ ltext = (char *) astFree( (void *) ltext ); } /* Annul the PointSets. */ pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Free the memory holding the pointers to the first value on each axis. */ ptr1 = (const double **) astFree( (void *) ptr1 ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__TEXT_ID, 0, GRF__TEXT, method, class ); /* Restore the original value of the flag which says whether graphical escape sequences should be incldued in any returned text strings. */ astEscapes( escs ); /* Return */ return; } static void TextLabels( AstPlot *this, int edgeticks, int dounits[2], const char *method, const char *class, int *status ){ /* * * Name: * TextLabels * Purpose: * Draw textual labels round a grid. * Type: * Private function. * Synopsis: * #include "plot.h" * void TextLabels( AstPlot *this, int edgeticks, int dounits[2], * const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * This function displays a textual label for each physical axis, and a * title. The text strings are obtained from the Label and Title * attributes of the current Frame in the Plot. * Parameters: * this * A pointer to the Plot. * edgeticks * If tick marks and numerical labels were drawn around the edges * of the plotting area, this should be supplied as 1. Otherwise it * should be supplied as zero. * dounits * Flags indicating if the axis Units string should be included in * the edge labels. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char *new_text; /* Pointer to complete text string (inc. units) */ char *just; /* Pointer to axis label justification string */ const char *text; /* Pointer to text string to be displayed */ const char *units; /* Pointer to text string describing the units */ double mindim; /* Minimum dimension of plotting area */ double xrange; /* Width of plotting area */ double yrange; /* Height of plotting area */ float txtgap; /* Gap between bounding box and text string */ float upx; /* X component of text up-vector */ float upy; /* Y component of text up-vector */ float xbn[ 4 ]; /* X coords at corners of new label's bounding box */ float ybn[ 4 ]; /* Y coords at corners of new label's bounding box */ float xref; /* Graphics X coord. at text ref. position */ float yref; /* Graphics Y coord. at text ref. position */ float xlo, xhi, ylo, yhi;/* The original bounding box (excluding labels) */ int axis; /* Axis index */ int draw; /* Should label be drawn? */ int edge; /* Edge to be labelled */ int esc; /* Interpret escape sequences? */ int gelid; /* ID for next graphical element to be drawn */ int tlen; /* No. of characetsr in label */ int ulen; /* No. of characetsr in units */ /* Check the global status. */ if( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this); /* Get the minimum dimension of the plotting area. */ xrange = this->xhi - this->xlo; yrange = this->yhi - this->ylo; mindim = astMIN( xrange, yrange ); /* Take a copy of the bounding box which encloses all other parts of the annotated grid. If nothing has been plotted, use an area 20 % smaller than the plotting area. */ if( Box_lbnd[ 0 ] != FLT_MAX ) { xlo = Box_lbnd[ 0 ]; xhi = Box_ubnd[ 0 ]; ylo = Box_lbnd[ 1 ]; yhi = Box_ubnd[ 1 ]; } else { xlo = this->xlo + 0.2*xrange; xhi = this->xhi - 0.2*xrange; ylo = this->ylo + 0.2*yrange; yhi = this->yhi - 0.2*yrange; } /* See if escape sequences are to be interpreted within the labels. */ esc = astGetEscape( this ); /* Initialize the id value for graphical element being drawn. */ gelid = AST__TEXTLAB1_ID; /* Now write a label for each physical axis. */ for( axis = 0; axis < 2 && astOK; axis++ ){ /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, gelid, 1, GRF__TEXT, method, class ); /* See if the label is to be drawn. If an explicit value has not been set for the TextLab attribute, the default is to draw the label if tick marks were draw round the edge of the plotting area, and not to otherwise. */ if( astTestTextLab( this, axis ) ){ draw = astGetTextLab( this, axis ); } else { draw = edgeticks; } /* If so get the label. */ if( draw ){ text = astGetLabel( this, axis ); tlen = ChrLen( text, status ); /* If required, get the units string and concatenate it with the label (inside parenthesise). Ignore trailing spaces. */ if( dounits[ axis ] ){ units = astGetUnit( this, axis ); if( units && units[0] ){ ulen = ChrLen( units, status ); new_text = astMalloc( tlen + ulen + 4 ); if( new_text ) memcpy( new_text, text, tlen ); text = new_text + tlen; memcpy( (void *) text, " (", 2 ); text += 2; memcpy( (char *) text, units, ulen ); text += ulen; memcpy( (char *) text, ")", 1 ); text += 1; ( (char *) text )[0] = 0; text = new_text; } else { new_text = astStore( NULL, (void *) text, tlen + 1 ); new_text[ tlen ] = 0; text = new_text; units = NULL; } } else { new_text = astStore( NULL, (void *) text, tlen + 1 ); new_text[ tlen ] = 0; text = new_text; units = NULL; } /* Get the gap between the edge of the bounding box and the closest edge of the text string. */ txtgap = (float)( mindim*astGetTextLabGap( this, axis ) ); /* Get the edge to be labelled. Edge 0 is the left hand edge. Edge 1 is the top edge. Edge 2 is the right-hand edge. Edge 3 is the bottom edge. */ edge = astGetEdge( this, axis ) % 4; if( edge < 0 ) edge = -edge; /* If the label is to be put on the left hand edge... */ if( edge == 0 ){ /* Set the up vector so that the text is written from bottom to top. */ upx = -1.0; upy = 0.0; /* Justify the bottom of the whole bounding box (not just the text base-line). */ just = "MC"; /* Set the x reference position just outside the box enclosing all the graphics drawn so far. The reference point refers to the centre of the text string in both directions ("CC" justification). Take account of whether or not the x axis is reversed. Do not allow the text to be written outside the whole plotting surface. */ if( this->xrev ){ xref = xhi + txtgap; } else { xref = xlo - txtgap; } /* The Y reference position is at the mid point vertically. */ yref = 0.5*( astMIN( yhi, this->yhi ) + astMAX( ylo, this->ylo ) ); /* Do the same for the top edge. */ } else if( edge == 1 ){ upx = 0.0; upy = 1.0; just = "MC"; if( this->yrev ){ yref = ylo - txtgap; } else { yref = yhi + txtgap; } xref = 0.5*( astMIN( xhi, this->xhi ) + astMAX( xlo, this->xlo ) ); /* Do the same for the right-hand edge. */ } else if( edge == 2 ){ upx = 1.0; upy = 0.0; just = "MC"; if( this->xrev ){ xref = xlo - txtgap; } else { xref = xhi + txtgap; } yref = 0.5*( astMIN( yhi, this->yhi ) + astMAX( ylo, this->ylo ) ); /* Do the same for the bottom edge. */ } else { upx = 0.0; upy = 1.0; just = "TC"; if( this->yrev ){ yref = yhi + txtgap; } else { yref = ylo - txtgap; } xref = 0.5*( astMIN( xhi, this->xhi ) + astMAX( xlo, this->xlo ) ); } /* Display the label. */ DrawText( this, 1, esc, text, xref, yref, just, upx, upy, xbn, ybn, NULL, method, class, status ); /* Release the memory allocated to store the axis label;. */ new_text = (char *) astFree( (void *) new_text ); text = NULL; } /* Re-establish the original graphical attributes. */ astGrfAttrs( this, gelid, 0, GRF__TEXT, method, class ); /* Set up the id for the next graphical element to be drawn. */ gelid = AST__TEXTLAB2_ID; } /* See if the title is to be drawn. */ if( astOK && astGetDrawTitle( this ) ){ /* If so get the title. */ text = astGetTitle( this ); /* Create a copy from which trailing spaces have been removed. */ tlen = ChrLen( text, status ); new_text = (char *) astStore( NULL, (void *) text, tlen + 1 ); new_text[ tlen ] = 0; text = new_text; /* Establish the correct graphical attributes as defined by attributes with the supplied Plot. */ astGrfAttrs( this, AST__TITLE_ID, 1, GRF__TEXT, method, class ); /* Take a copy of the bounding box which encloses all other parts of the annotated grid (this may have been extended by the above code). If nothing has been plotted, use an area 20 % smaller than the plotting area. */ if( Box_lbnd[ 0 ] != FLT_MAX ) { xlo = Box_lbnd[ 0 ]; xhi = Box_ubnd[ 0 ]; ylo = Box_lbnd[ 1 ]; yhi = Box_ubnd[ 1 ]; } else { xlo = this->xlo + 0.2*xrange; xhi = this->xhi - 0.2*xrange; ylo = this->ylo + 0.2*yrange; yhi = this->yhi - 0.2*yrange; } /* Get the graphics coordinates of the bottom centre point of the title. The X centre is put at the mid point of the used x axis range (restricted to the range of the plotting area). */ xref = 0.5*( astMIN( xhi, this->xhi ) + astMAX( xlo, this->xlo ) ); /* The Y centre is put a "TitleGap" distance outside the box containing the everything else. */ if( this->yrev ){ yref = ylo - (float)( mindim*astGetTitleGap( this ) ); } else { yref = yhi + (float)( mindim*astGetTitleGap( this ) ); } /* Display the title. Justify the bottom of the whole bounding box (not just the text base-line). */ DrawText( this, 1, esc, text, xref, yref, "MC", 0.0F, 1.0F, xbn, ybn, NULL, method, class, status ); /* Re-establish the original graphical attributes. */ astGrfAttrs( this, AST__TITLE_ID, 0, GRF__TEXT, method, class ); /* Release the memory allocated to store the title. */ new_text = (char *) astFree( (void *) new_text ); text = NULL; } /* Include the labels in the bounding box held in global variables Box_lbnd/ubnd. */ if( Box_lbnd[ 0 ] != FLT_MAX ) { Box_lbnd[ 0 ] = astMIN( Box_lbnd[ 0 ], Boxp_lbnd[ 0 ] ); Box_ubnd[ 0 ] = astMAX( Box_ubnd[ 0 ], Boxp_ubnd[ 0 ] ); Box_lbnd[ 1 ] = astMIN( Box_lbnd[ 1 ], Boxp_lbnd[ 1 ] ); Box_ubnd[ 1 ] = astMAX( Box_ubnd[ 1 ], Boxp_ubnd[ 1 ] ); } else { Box_lbnd[ 0 ] = Boxp_lbnd[ 0 ]; Box_ubnd[ 0 ] = Boxp_ubnd[ 0 ]; Box_lbnd[ 1 ] = Boxp_lbnd[ 1 ]; Box_ubnd[ 1 ] = Boxp_ubnd[ 1 ]; } /* Return. */ return; } static void UpdateConcat( float *xbn, float *ybn, float ux, float uy, float rx, float ry, float *x, float *y, float x0, float y0, float *alpha_lo, float *alpha_hi, float *beta_lo, float *beta_hi, int *status ){ /* * Name: * UpdateConcat * Purpose: * Update the concatenation point for a text string in preparation for * appending another string. * Synopsis: * #include "plot.h" * void UpdateConcat( float *xbn, float *ybn, float ux, float uy, * float rx, float ry, float *x, float *y, * float x0, float y0, float *alpha_lo, float *alpha_hi, * float *beta_lo, float *beta_hi, int *status ) * Description: * This function modifies the supplied concatenation point (x,y) by moving * it to the right along the baseline of the text by an amount equal * to the width of the supplied sub-string bounding box. It also updates * the supplied total bounding box so that it includes the supplied * sub-string bounding box. * Parameters: * xbn * Pointer to an array holding the x coord at the four corners of * the sub-string bounding box. * ybn * Pointer to an array holding the y coord at the four corners of * the sub-string bounding box. * ux * The x component of the up-vector for the text, in graphics coords. * The length of this vector should be equal to the height of normal * text drawn with this up-vector. * uy * The y component of the up-vector for the text. See "ux". * rx * The x component of the right-vector for the text. The length of this * vector should be equal to the height of normal text drawn with the * supplied up-vector. * ry * The y component of the right-vector for the text. see "rx". * x * Pointer to a float holding the x coord of the concatenation point * of the text just drawn. This is changed on exit so that the next * string will be appended to the end of the text just drawn. * y * Pointer to a float holding the y coord of the concatenation point * of the text just drawn. This is changed on exit so that the next * string will be appended to the end of the text just drawn. * x0 * The X coord at the left end of the baseline of the total string. * y0 * The Y coord at the left end of the baseline of the total string. * alpha_lo * Pointer to a double holding a value which gives the position of the * bottom edge of the total bounding box. The value is such that * (x0,y0) + alpha_lo*(ux,uy) is a point on the bottom edge of the * total bounding box. The returned value is updated so that the * total bounding box includes the supplied sub-string bounding box. * alpha_hi * Pointer to a double holding a value which gives the position of the * top edge of the total bounding box. The value is such that * (x0,y0) + alpha_hi*(ux,uy) is a point on the top edge of the * total bounding box. The returned value is updated so that the * total bounding box includes the supplied sub-string bounding box. * beta_lo * Pointer to a double holding a value which gives the position of the * left edge of the total bounding box. The value is such that * (x0,y0) + beta_lo*(rx,ry) is a point on the left edge of the * total bounding box. The returned value is updated so that the * total bounding box includes the supplied sub-string bounding box. * beta_hi * Pointer to a double holding a value which gives the position of the * right edge of the total bounding box. The value is such that * (x0,y0) + beta_hi*(rx,ry) is a point on the right edge of the * total bounding box. The returned value is updated so that the * total bounding box includes the supplied sub-string bounding box. * status * Pointer to the inherited status variable. */ /* Local Variables: */ float ahi; float alo; float alpha; float beta; float bhi; float blo; float denom; float dx; float dy; float xc; float yc; int ic; /* Check the global error status. */ if ( !astOK ) return; /* Check the supplied up and right vectors are not parallel. */ denom = ux*ry - uy*rx; if( denom != 0.0 ) { /* Get the coords at the centre of the sub-string bounding box. */ xc = ( xbn[ 0 ] + xbn[ 1 ] + xbn[ 2 ] + xbn[ 3 ] )/4.0; yc = ( ybn[ 0 ] + ybn[ 1 ] + ybn[ 2 ] + ybn[ 3 ] )/4.0; /* For each of the 4 corners of the sub-string bounding box, we consider the vector from the centre of the bounding box to the corner. We want to express this vector, vx, as a sum of a vector in the up direction and a vector in the right direction: vx = alpha*ux + beta+rx vy = alpha*uy + beta+ry where alpha and beta are constants which are different for each corner vector. We also want to find the minimum and maximum alpha and beta covered by the box. First initialise the limits. */ alo = 0.0; ahi = 0.0; blo = 0.0; bhi = 0.0; /* Now find alpha and beta for each of the four corners. */ for( ic = 0; ic < 4; ic++ ) { dx = xbn[ ic ] - xc; dy = ybn[ ic ] - yc; alpha = ( dx*ry - dy*rx ) /denom; beta = ( dy*ux - dx*uy ) /denom; /* Extend the bounds in alpha and beta. */ if( alpha < alo ) alo = alpha; if( alpha > ahi ) ahi = alpha; if( beta < blo ) blo = beta; if( beta > bhi ) bhi = beta; /* The bottom left corner has negative values for both alpha and beta. Commence the process of updating the concatenation point by subtracting off the coordinates at the bottom left corner. For zero height bounding boxes (such as may be produced if the text is completely blank), the "alpha" value should be zero, but may be slightly non-zero due to rounding errors. Allow for this (assuming non-blank text will always produce a boundiong box that is at least 1.0E-4 of the up vector in height). We do the same for bounding box width (although zero width boxes will probably not occur). */ if( alpha < 1.0E-4 ) { if( beta < 1.0E-4 ) { *x -= xbn[ ic ]; *y -= ybn[ ic ]; /* The bottom right corner has negative alpha and positive beta. Complete the process of updating the concatenation point by adding on the coordinates at the bottom right corner. */ } else if( beta > -1.0E-4 ) { *x += xbn[ ic ]; *y += ybn[ ic ]; } } } /* Also express the vector from (x0,y0) to (xc,yc) as a sum of a vector in the up direction and a vector in the right direction: xc - x0 = alpha*ux + beta*rx yc - y0 = alpha*uy + beta*ry Find alpha and beta. */ dx = xc - x0; dy = yc - y0; alpha = ( dx*ry - dy*rx ) /denom; beta = ( dy*ux - dx*uy ) /denom; /* We can now express the vector from (x0,y0) to each of the 4 corners as a sum of alpha*up and beta*right. Form the bounds of the sub-string in terms of up-vectors and right vectors from (x0,y0) instead of from the centre of the box. */ alo += alpha; ahi += alpha; blo += beta; bhi += beta; /* Extend the supplied alpha and beta bounding box to include these limits. */ if( alo < *alpha_lo ) *alpha_lo = alo; if( ahi > *alpha_hi ) *alpha_hi = ahi; if( blo < *beta_lo ) *beta_lo = blo; if( bhi > *beta_hi ) *beta_hi = bhi; } } static void Ticker( AstPlot *this, int edge, int axis, double value, double *gap, double tklen, int majtick, int save, EdgeCrossingsStatics **pstatics, const char *method, const char *class, int *status ){ /* * * Name: * Ticker * Purpose: * Draw edge tick marks for a given axis value. * Type: * Private function. * Synopsis: * #include "plot.h" * void Ticker( AstPlot *this, int edge, int axis, double value, * double *gap, double tklen, int majtick, int save, * EdgeCrossingsStatics **pstatics, const char *method, * const char *class, int *status ){ * Class Membership: * Plot member function. * Description: * This function draws tick marks at all occurences of a given * physical axis value on a given edge of the plotting area. * Parameters: * this * A pointer to the Plot. * edge * The edge of the plotting area to be ticked. Edge 0 is the left hand * edge. Edge 1 is the top edge. Edge 2 is the right-hand edge. Edge 3 * is the bottom edge. * axis * The index of the axis to which "value" refers. The tick mark extends * parallel to this axis. * value * The physical axis value at which to place the tick mark. * gap * Pointer to array of two values holding the gap between major * tick marks on the two axes. * tklen * The length of the tick, in graphics units. * majtick * Non-zero if the tick mark being drawn is a major tick, and zero * if it is a minor tick. * save * If non-zero, the tick mark position will be saved in the Plot structure. * pstatics * Address of a pointer to a structure holding values for variables * which were statically defined within this function prior to the * thread-safe version of AST. If the pointer is supplied as NULL, * then a new structure is allocated and initialised. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double *cross; /* Pointer to crossings information */ double *vx; /* Pointer to next X vector component value */ double *vy; /* Pointer to next Y vector component value */ double *x; /* Pointer to next X value */ double *y; /* Pointer to next Y value */ double xe; /* X at tick end */ double ye; /* Y at tick end */ int j; /* Crossing index */ int ncross; /* No. of crossings of tick value and edge */ /* Check the global status. */ if( !astOK ) return; /* See where the current major tick value crosses the edge. */ ncross = EdgeCrossings( this, edge, axis, value, gap, &cross, pstatics, method, class, status ); /* Do nothing if the supplied axis value does not occur on the specified edge of the plotting area. */ if( ncross ){ /* Draw major tick marks at the crossings. */ x = cross; y = cross + 1; vx = cross + 2; vy = cross + 3; /* Draw a tick mark at each occurence of the axis value on the specified edge. */ for( j = 0; j < ncross; j++ ){ /* Check the tick mark position and directionm are defined. */ if( *vx != AST__BAD && *vy != AST__BAD && *x != AST__BAD && *y != AST__BAD ){ /* Ensure the tick mark will point into the plotting area, no matter which edge it is on. First ensure the direction vector refers to a system in which X increases to the left and Y increases upwards. */ if( this->xrev ) *vx = -*vx; if( this->yrev ) *vy = -*vy; /* If necessary reverse the vector so that it points into the plotting area. How to do this depends on which edge is being ticked. */ if( ( edge == 0 && *vx < 0.0 ) || /* left-hand edge */ ( edge == 1 && *vy > 0.0 ) || /* Top edge */ ( edge == 2 && *vx > 0.0 ) || /* Right-hand edge */ ( edge == 3 && *vy < 0.0 ) ){ /* Bottom edge */ *vx = -*vx; *vy = -*vy; } /* Now ensure the direction vector refers to a the native graphics system taking account of any reversal of axes. */ if( this->xrev ) *vx = -*vx; if( this->yrev ) *vy = -*vy; /* Do not draw the tick if the start of the tick is outside the bounds of the axis it is labelling. */ if( ( ( edge == 1 || edge == 3 ) && *x < this->xhi && *x > this->xlo ) || ( ( edge == 0 || edge == 2 ) && *y < this->yhi && *y > this->ylo ) ) { /* Store the x and y graphics coords of the far end of the tick mark */ xe = *x + tklen*(*vx); ye = *y + tklen*(*vy); /* Ensure the far end of the tick mark is within the bounds of the axis it is labelling. If not, redice the length of the tick mark until it is.*/ if( edge == 1 || edge == 3 ) { /* Top or bottom edge */ if( xe > this->xhi ) { ye = *y + tklen*(*vy)*( this->xhi - *x )/(xe - *x ); xe = this->xhi; } else if( xe < this->xlo ) { ye = *y + tklen*(*vy)*( this->xlo - *x )/(xe - *x ); xe = this->xlo; } } else { /* Left or right edge */ if( ye > this->yhi ) { xe = *x + tklen*(*vx)*( this->yhi - *y )/(ye - *y ); ye = this->yhi; } else if( ye < this->ylo ) { xe = *x + tklen*(*vx)*( this->ylo - *y )/(ye - *y ); ye = this->ylo; } } /* Draw the tick mark as a straight line of the specified length. */ if( save ) SaveTick( this, axis, *x, *y, majtick, status ); if( *x != xe || *y != ye ) { Bpoly( this, (float) *x, (float) *y, status ); Apoly( this, (float) xe, (float) ye, status ); Opoly( this, status ); } } /* Move on to the next crossing. */ x += 4; y += 4; vx += 4; vy += 4; } } /* Free the memory holding the crossings. */ if( cross ) cross = (double *) astFree( (void *) cross ); } /* Return. */ return; } static TickInfo *TickMarks( AstPlot *this, int axis, double *cen, double *gap, int *inval, GetTicksStatics **pstatics, const char *method, const char *class, int *status ){ /* * Name: * TickMarks * Purpose: * Obtain a list of tick mark values and labels for a single axis in a 2-D * physical coordinate Frame. * Type: * Private function. * Synopsis: * #include "plot.h" * TickInfo *TickMarks( AstPlot *this, int axis, double *cen, double *gap, * int *inval, GetTicksStatics **pstatics, * const char *method, const char *class, int *status ) * Class Membership: * Plot member function. * Description: * A set of tick marks values and corresponding formatted labels are * found for an axis which result in all adjacent labels being different, * but using the minimum number of digits of precision in the formatting. * This algorithm is over-ridden if the caller has set an explicit Format * string for the axis. The gap between tick marks can be specified by * the caller or a default value may be found automatically. * Parameters: * this * The Plot. * axis * The zero-based index of the axis to use. * cen * Pointer to the supplied axis value at which to put a single * central tick. Other ticks will be placed evenly on either side of * this tick. If AST__BAD is provided, a value will be used which * would put a tick at an axis value of zero. The used value is * returned. * gap * The supplied values for the gaps between ticks on the axis. If * this is AST__BAD a suitable default value will be used and * returned in place of the AST__BAD value. * inval * A pointer to a location at which to return a flag indicating if * any invalid physical coordinates were encountered while deciding on * the tick values. * pstatics * Address of a pointer to a structure holding static data values * used within the GetTicks function. A NULL pointer should be supplied * on the first invocation (dynamic memory will then be allocated to * hold ths structure). The memory is freed when a NULL value for * "this" is supplied. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a TickInfo structure holding information about the tick * marks (no. of major and minor ticks, the major tick mark values and * labels). This structure should be freed, together with its contents, * using astFree when it is no longer needed. * Notes: * - The returned labels are NOT abbreviated to remove identical * leading fields. * - This function allocates some static resources on its first * invocation, which should be released when no longer needed, or when * a different Plot is supplied, by calling this function with a NULL * pointer for parameter "this". All other parameters (except axis) are * ignored. * - This function assumes that the physical coordinate system is 2 * dimensional, and it should not be used if this is not the case. * - An error is reported if the region containing valid physical * coordinates is too small to use. * - If an error has already occurred, or if this function should fail * for any reason, then a NULL pointer is returned. */ /* Local Constants: */ #define MAXFLD 10 /* Local Variables: */ AstAxis *ax; /* Pointer to the axis. */ AstFrame *frame; /* Pointer to the current Frame in the Plot */ TickInfo *ret; /* Pointer to the returned structure. */ char **labels; /* Pointer to list of formatted labels */ char **newlabels; /* Pointer to new list of shortened formatted labels */ char **oldlabels; /* Pointer to old list of formatted labels */ char *fields[ MAXFLD ]; /* Pointers to starts of fields in a label */ char *old_format; /* Original Format string */ char *used_fmt; /* Copy of format string actually used */ const char *a; /* Pointer to next character to consider */ const char *fmt; /* Format string actually used */ double *ticks; /* Pointer to major tick mark values */ double *minticks; /* Pointer to minor tick mark values */ double cen0; /* Supplied value of cen */ double junk; /* Unused value */ double refval; /* Value for other axis to use when normalizing */ double used_gap; /* The gap size actually used */ int bot_digits; /* Digits value which makes labels as short as possible */ int digits; /* New Digits value */ int digset; /* Did the format string fix the no. of digits to use? */ int fmtset; /* Was a format set? */ int i; /* Tick index. */ int nc[ MAXFLD ]; /* Lengths of fields in a label */ int nf; /* Number of fields in a label */ int nmajor; /* No. of major tick marks */ int nminor; /* No. of minor tick marks */ int ok; /* Are all adjacent labels different? */ int reset_fmt; /* Re-instate the original state of the Format attribute? */ /* If a NULL pointer has been supplied for "this", release the resources allocated within GetTicks, and return. */ if( !this ){ (void) GetTicks( NULL, axis, NULL, &ticks, &nmajor, &minticks, &nminor, 0, inval, &refval, pstatics, method, class, status ); return NULL; } /* Check the global status. */ if( !astOK ) return NULL; /* Initialise the returned pointer. */ ret = NULL; /* Store the supplied value of cen. */ cen0 = cen ? *cen : AST__BAD ; /* Get a pointer to the current Frame from the Plot. */ frame = astGetFrame( this, AST__CURRENT ); /* Initialise a flag to indicate that all adjacent labels are different. */ ok = 0; /* Initialise the pointer to the list of formatted tick mark values to indicate that no memory has yet been obtained. */ labels = NULL; /* Initialise the pointer to a copy of the used format string to indicate that no memory has yet been obtained. */ used_fmt = NULL; /* Get a pointer to the axis. */ ax = astGetAxis( frame, axis ); /* See if a value has been set for the axis Format. */ fmtset = astTestFormat( frame, axis ); /* Get an initial set of tick mark values. This also establishes defaults for LogTicks and LogLabel attributes, and so must be done before the following block which uses the LogLabel attribute. */ used_gap = GetTicks( this, axis, cen, &ticks, &nmajor, &minticks, &nminor, fmtset, inval, &refval, pstatics, method, class, status ); /* See if exponential labels using superscript powers are required. */ old_format = NULL; reset_fmt = 0; if( astGetLogLabel( this, axis ) && astGetEscape( this ) && GCap( this, GRF__SCALES, 1, status ) ) { /* Save a copy of the Frame's Format value, if set. It will be re-instated at the end of this function. */ if( fmtset ) { fmt = astGetFormat( frame, axis ); old_format = astStore( NULL, (void *) fmt, strlen(fmt) + 1 ); } /* Temporarily use a format of "%&g" to get "10**x" style axis labels, with super-scripted "x". */ astSetFormat( frame, axis, "%&g" ); /* Not all subclasses of Frame support this format specifier, so format a test value, and see if it has two fields, the first of which is "10". If not, we cannot use log labels so re-instate the original format. */ nf = astFields( frame, axis, "%&g", astFormat( frame, axis, 1.0E4 ), MAXFLD, fields, nc, &junk ); if( nf != 2 || nc[ 0 ] != 2 || strncmp( fields[ 0 ], "10", 2 ) ) { if( old_format ) { astSetFormat( frame, axis, old_format ); old_format = astFree( old_format); } else { astClearFormat( frame, axis ); } /* If the "%&g" format is usable, note that we should reset the Format back to its original state before leaving this function. */ } else { reset_fmt = 1; } } /* If a value has been set for the axis Format, see if the format string contains a wildcard precision specifier ".*". If so, we are free to vary the number of digits used in the label in order to produce distinct labels. If no value has been set for the axis Format, we are also free to vary the number of digits. */ digset = 0; if( fmtset ) { fmt = astGetFormat( frame, axis ); if( fmt ) { digset = 1; a = fmt; while( (a = strchr( a, '.' )) ){ if( *(++a) == '*' ) { digset = 0; break; } } } } /* If the axis precision has been specified, either through the Format string or Digits value, or the Frame Digits value, we should use it so that the user's attempts to get a specific result are not foiled. */ if( digset || astTestAxisDigits( ax ) || astTestDigits( frame ) ){ /* Reserve memory to hold pointers to the formatted labels. */ labels = (char **) astMalloc( sizeof(char *)*(size_t)nmajor ); /* Format the labels. We do not check that all adjacent labels are distinct in order not to foil the users choice of format. That is, "ok" is set non-zero by the call to CheckLabels, even if some identical adjacent labels are found. */ ok = CheckLabels( this, frame, axis, ticks, nmajor, 1, labels, refval, status ); /* Note the format used. */ fmt = astGetFormat( frame, axis ); if( fmt ) used_fmt = (char *) astStore( used_fmt, (void *) fmt, strlen( fmt ) + 1 ); /* If no precision has been specified for the axis, we need to find a Digits value which gives different labels, but without using any more digits than necessary. */ } else if( astOK ){ /* Reserve memory to hold pointers to an initial set of labels formatted with the default digits value. */ labels = (char **) astMalloc( sizeof(char *)*(size_t)nmajor ); /* Produce these default labels. */ CheckLabels( this, frame, axis, ticks, nmajor, 1, labels, refval, status ); /* The first task is to decide what the smallest usable number of digits is. Starting at the default number of digits used above to produce the default labels, we reduce the number of digits until one or more of the formatted labels *increases* in length. This can happen for instance if printf decides to include an exponent in the label. The *absolute* minimum value 1. Set this first. */ bot_digits = 1; oldlabels = labels; for( digits = astGetDigits( frame ) - 1; digits > 0; digits-- ){ astSetAxisDigits( ax, digits ); /* CheckLabels2 formats the labels with the decreased number of digits, and compares them with the old labels in "labels". If any of the new labels are longer than the corresponding old labels, then a null pointer is returned. Otherwise, a pointer is returned to the new set of labels. */ newlabels = CheckLabels2( this, frame, axis, ticks, nmajor, oldlabels, refval, status ); /* Free the old labels unless they are the orignal labels (which are needed below). */ if( oldlabels != labels ) { for( i = 0; i < nmajor; i++ ){ if( oldlabels[ i ] ) oldlabels[ i ] = (char *) astFree( (void *) oldlabels[ i ] ); } oldlabels = (char **) astFree( (void *) oldlabels ); } /* If any of the labels got longer as a result of reducing the digits value, then use the previous number of digits as the lowest possible number of digits. Break out of the loop. */ if( !newlabels ) { bot_digits = digits + 1; break; } /* If none of the labels got longer, we arrive here. Use the shorter labels for the next pass round this loop. */ oldlabels = newlabels; } /* Free any remaining labels. */ if( oldlabels && oldlabels != labels ) { for( i = 0; i < nmajor; i++ ){ if( oldlabels[ i ] ) oldlabels[ i ] = (char *) astFree( (void *) oldlabels[ i ] ); } oldlabels = (char **) astFree( (void *) oldlabels ); } /* Now loop round increasing the number of digits in the formatted labels from the lowest usable value found above until all adjacent labels are different. An arbitrary upper limit of 1000 is used for Digits to stop it looping for ever. */ for( digits = bot_digits; digits < 1000; digits++ ){ /* Store the new Digits value. */ astSetAxisDigits( ax, digits ); /* Free memory used to hold the current set of labels. A new set will be created by the following call to CheckLabels. */ if( labels ) { for( i = 0; i < nmajor; i++ ) labels[ i ] = astFree( labels[ i ] ); } /* Break out of the loop if a Digits value has been found which results in all adjacent labels being different. Note the format used (we know the Format attribute is currently unset, but the default Format string reflects the current value of the Digits attribute). */ if( CheckLabels( this, frame, axis, ticks, nmajor, 0, labels, refval, status ) ) { ok = 1; fmt = astGetFormat( frame, axis ); used_fmt = (char *) astStore( NULL, (void *) fmt, strlen( fmt ) + 1 ); break; } } /* Clear the Digits value. */ astClearAxisDigits( ax ); } /* Annul the pointer to the Axis. */ ax = astAnnul( ax ); /* Re-instate the original format specifier if required. */ if( reset_fmt ) { if( old_format ) { astSetFormat( frame, axis, old_format ); old_format = astFree( old_format); } else { astClearFormat( frame, axis ); } } /* If suitable labels were found... */ if( ok && astOK ) { /* Store the used gap size. */ *gap = used_gap; /* If the caller has specified the number of minor tick marks to use, use the specified value rather than the value found above. */ if( astTestMinTick( this, axis ) ){ nminor = astGetMinTick( this, axis ); } /* Allocate memory for the returned structure. */ ret = (TickInfo *) astMalloc( sizeof( TickInfo ) ); /* If the pointer can be used, store the information. */ if( astOK ){ ret->nmajor = nmajor; ret->nminor = nminor; ret->ticks = ticks; ret->minticks = minticks; ret->labels = labels; ret->fmt = used_fmt; used_fmt = NULL; ret->start = NULL; ret->length = NULL; ret->nsect = 0; ret->gap = used_gap; } /* If no suitable labels were found report an error. */ } else if( astOK ){ if( fmtset ){ astError( AST__PLFMT, "%s(%s): No numerical labels can be produced " "for axis %d using the supplied %s format string '%s'.", status, method, class, axis + 1, astGetClass( frame ), astGetFormat( frame, axis ) ); } else { astError( AST__PLFMT, "%s(%s): No suitable format can be found to " "produce numerical labels for axis %d of a %s.", status, method, class, axis + 1, astGetClass( frame ) ); } } /* Release any remaining resources. */ frame = astAnnul( frame ); if( used_fmt ) used_fmt = astFree( used_fmt ); /* If an error has occurred, release the returned information. */ if( !astOK ){ ticks = (double *) astFree( (void *) ticks ); minticks = (double *) astFree( (void *) minticks ); if( labels ){ for( i = 0; i < nmajor; i++ ) { labels[ i ] = (char *) astFree( (void *) labels[ i ] ); } labels = (char **) astFree( (void *) labels ); if( ret ) (void ) astFree( (void *) ret->fmt ); } ret = (TickInfo *) astFree( (void *) ret ); } /* Return the structure. */ return ret; /* Undefine local constants. */ #undef MAXFLD } static int TraceBorder( AstPlot *this, AstMapping *map, double xlo, double xhi, double ylo, double yhi, int dim, double tol, int edges[ 4 ], const char *method, const char *class, int *status ) { /* * Name: * TraceBorder * Purpose: * Trace the boundary between good and bad physical coordinates through a * fine grid. * Type: * Private function. * Synopsis: * #include "plot.h" * int TraceBorder( AstPlot *this, AstMapping *map, double xlo, double xhi, * double ylo, double yhi, int dim, double tol, * int edges[ 4 ], const char *method, const char *class, * int *status ) { * Class Membership: * Plot member function. * Description: * A rectangular grid of points in graphics coords is created covering * the region specified by (xlo,xhi,ylo,yhi), using "dim" points along * each axis. This grid of points is converted into physical (WCS) * coords, and a flag is associatred with each point saying whether * the WCS coords are good or bad. The cells in this grid are then * scanned from bottom left to top right in raster fashion (each cell * has a grid point at each of its 4 corners). If a cell has a mix of * bad and good corners, the good/bad boundary must pass through it. * If the grid is sufficiently fine (as defined by "tol") then this * function draws a single straight line through each cell as an * approximation to the good bad boundary. This line joins the centres * of the two cells edges through which the boundary passes (as * indicated by the fact that one end of the edge has good WCS coords * and the other end has bad WCS coords). If the grid is not * sufficiently fine to meet the "tol" requirement, then this function * is invoked recursively to draw the curve through each cell through * which the boundary passes. * Parameters: * this * The plot. * map * The Graphics->WCS mapping. * xlo * The lower bounds on the graphics X axis of the rectangle being * considered. * xhi * The upper bounds on the graphics X axis of the rectangle being * considered. * ylo * The lower bounds on the graphics Y axis of the rectangle being * considered. * yhi * The upper bounds on the graphics Y axis of the rectangle being * considered. * dim * The number of points along one edge of the fine grid. * tol * The plotting tolerance. Once each cell is smaller than this * distance (in graphics coords), the cell is drawn. Otherwise, * this function is invoked recursively to draw the cell using a * finer grid. * edges * A pointer to an array of 4 int, in which will be returned * flags indicating if the good/bad boundary intersects any of the * edges of the grid. These flags are stored in the order left, * top, right, bottom. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *pset1; AstPointSet *pset2; double **ptr2; double *px1; double *px2; double *py1; double *py2; double cxhi; double cxlo; double cyhi; double cylo; double dx; double dy; float xc; float yc; int *bndry; int *drawn; int bad1; int bad2; int bad3; int bad4; int icell; int icol; int irow; int lastcell; int ncell; int recurse; int result; int sedges[ 4 ]; int totcells; /* Initialise returned edge flags */ edges[ 0 ] = 0; edges[ 1 ] = 0; edges[ 2 ] = 0; edges[ 3 ] = 0; /* Initialise the returned flag to indicate that no bad regions were found. */ result = 0; /* Check the global status. */ if ( !astOK ) return result; /* Create a grid of graphics and WCS coords covering the specified region of graphics coords. "ptr2" is used to access the WCS coords at each point in the grid. */ ptr2 = MakeGrid( this, NULL, map, 0, dim, xlo, xhi, ylo, yhi, 2, &pset1, &pset2, 0, method, class, status ); /* The number of cells along each axis of the grid is one less than the number of points. Also get the number of cells in the whole grid. */ ncell = dim - 1; totcells = ncell*ncell; /* Store the dimensions of each cell in graphics coords. */ dx = ( xhi - xlo )/ncell; dy = ( yhi - ylo )/ncell; /* Set a flag indicating if the cell size is larger than the required plotting tolerance. If so, we will call this function recursively to draw the curve using a finer grid. */ recurse = ( dx > tol || dy > tol ); /* If we have not yet reached the plotting tolerance, allocate work arrays with one element for each cell in the grid. */ if( recurse ) { bndry = astMalloc( sizeof( int )*totcells ); drawn = astMalloc( sizeof( int )*totcells ); } else { bndry = NULL; drawn = NULL; } /* Check pointers can be used safely. */ if( astOK ) { /* If required, initialise work arrays to hold zero. */ if( recurse ) { /* Initialise "boundary passes through cell" flags to zero. */ memset( bndry, 0, sizeof( int )*totcells ); /* Initialise "cell has been drawn" flags to zero. */ memset( drawn, 0, sizeof( int )*totcells ); } /* Store the Y graphics coords at the bottom and top of the first row. */ cylo = ylo; cyhi = ylo + dy; /* Store pointers to the physical coords at the bottom left corner of the first cell in the first row. */ px1 = ptr2[ 0 ]; py1 = ptr2[ 1 ]; /* Store pointers to the physical coords at the top left corner of the first cell in the first row. */ px2 = px1 + dim; py2 = py1 + dim; /* Store the index of the last cell in a row or column. */ lastcell = ncell - 1; /* Initialise index of next cell. */ icell = 0; /* Loop round every row of cells in this grid. */ for( irow = 0; irow < ncell; irow++ ) { /* See if the physical coords are bad at the bottom left corner of the first cell in this row. At the same time, increment the pointers so they refer to the bottom right corner of the first cell in this row. */ bad1 = ( *px1 == AST__BAD || *py1 == AST__BAD ); /* Increment the pointers. Do not do it in the above "if" statement since the or (!!) means that the second expression may never be evaluated. */ px1++; py1++; /* See if the physical coords are bad at the top left corner of the first cell in this row. At the same time, increment the pointers so they refer to the top right corner of the first cell in this row. */ bad2 = ( *px2 == AST__BAD || *py2 == AST__BAD ); px2++; py2++; /* Loop round every cell in the current row of cells. */ for( icol = 0; icol < ncell; icol++, icell++ ) { /* See if the physical coords are bad at the bottom right corner of the current cell in this row. At the same time, increment the pointers so they refer to the bottom right corner of the next cell in this row. */ bad3 = ( *px1 == AST__BAD || *py1 == AST__BAD ); px1++; py1++; /* See if the physical coords are bad at the top right corner of the current cell in this row. At the same time, increment the pointers so they refer to the top right corner of the next cell in this row. */ bad4 = ( *px2 == AST__BAD || *py2 == AST__BAD ); px2++; py2++; /* Set the returned flag non-zero if any invalidpositions are found. */ if( bad1 || bad2 || bad3 || bad4 ) result = 1; /* If there are a mixture of good and bad corners, the good/bad boundary must pass through the current cell. */ if( bad2 != bad1 || bad3 != bad1 || bad4 != bad1 ) { /* If we have not yet reached the required plotting tolerance, set a flag to indicate that the boundary should be plotted through this cell using a recirsive call to this function. */ if( recurse ) { bndry[ icell ] = 1; /* If we have reached the required plotting tolerance, draw the boundary as a straight line between the centres of the edges through which the boundary enteres and leaves the current cell. */ } else { /* Get the upper and lower graphics X bounds of the current cell. */ cxlo = xlo + icol*dx; cxhi = cxlo + dx; /* If an edge of the current cell has good coords at one end but bad coords at the other, the boundary is assumed to pass through the edge at its centre. Normally, we expect only two cell edges to have this property (i.e the boundary enters the cell through one edge and leaves through the other). However, sometimes all four edges may have this property. In this case, two sections of the boundary must pass through the cell, and there is no way of knowing which edges connect together (short of further recursion), and we arbitrarily decide to join opposite edges. */ if( bad1 == bad4 && bad2 == bad3 ) { /* Draw a horizontal line through the cell centre */ yc = 0.5*( cylo + cyhi ); Bpoly( this, (float) cxlo, yc, status ); Apoly( this, (float) cxhi, yc, status ); /* Draw a vertical line through the cell centre */ xc = 0.5*( cxlo + cxhi ); Bpoly( this, xc, (float) cylo, status ); Apoly( this, xc, (float) cyhi, status ); /* If the boundary passes through the left hand edge, it must also have passed through the right edge of the previous cell in the row (unless this is the first cell in the row), so we do not need to begin a new polyline (we can just extend the existing polyline). */ } else if( bad1 != bad2 ) { /* If this is the first cell in the row, begin a new polyline. */ yc = 0.5*( cylo + cyhi ); if( icol == 0 ) Bpoly( this, (float) cxlo, yc, status ); /* and through the top edge, draw a line between the centres of the left and top edges. */ if( bad2 != bad4 ) { xc = 0.5*( cxlo + cxhi ); Apoly( this, xc, (float) cyhi, status ); /* or through the right edge, draw a line between the centres of the left and right edges. */ } else if( bad3 != bad4 ) { Apoly( this, (float) cxhi, yc, status ); /* Otherwise, draw a line between the centres of the left and bottom edges. */ } else { xc = 0.5*( cxlo + cxhi ); Apoly( this, xc, (float) cylo, status ); } /* If the boundary passes through the top edge (we do not need to check the left edge because that was done above)... */ } else if( bad4 != bad2 ) { /* and through the right edge, draw a line between the centres of the top and right edges. */ if( bad3 != bad4 ) { xc = 0.5*( cxlo + cxhi ); yc = 0.5*( cylo + cyhi ); Bpoly( this, xc, (float) cyhi, status ); Apoly( this, (float) cxhi, yc, status ); /* Otherwise, draw a line between the centres of the top and bottom edges. */ } else { xc = 0.5*( cxlo + cxhi ); Bpoly( this, xc, (float) cyhi, status ); Apoly( this, xc, (float) cylo, status ); } /* If the boundary passes through the right edge it must also pass throught the bottom edge since all other combinations will have been trapped above. */ } else { xc = 0.5*( cxlo + cxhi ); yc = 0.5*( cylo + cyhi ); Bpoly( this, xc, (float) cylo, status ); Apoly( this, (float) cxhi, yc, status ); } /* If the current cell is on the edge of the grid, set flags in the returned "edges" array to indicate that the boundary passes out of the grid on the appropriate edge. */ if( icol == 0 ) { if( bad1 != bad2 ) edges[ 0 ] = 1; /* Left edge */ } else if( icol == lastcell ) { if( bad3 != bad4 ) edges[ 2 ] = 1; /* Right edge */ } if( irow == 0 ) { if( bad1 != bad3 ) edges[ 3 ] = 1; /* Bottom edge */ } else if( irow == lastcell ) { if( bad2 != bad4 ) edges[ 1 ] = 1; /* Top edge */ } } } /* The flags for the right hand corners of the current cell can be re-used as the flags for the left hand corners of the next cell. */ bad1 = bad3; bad2 = bad4; } /* Store the Y graphics coords at the bottom and top of the next row. */ cylo = cyhi; cyhi = cylo + dy; } /* If we have not yet reached the required plotting tolerance, call this function recursively to draw the boundary through the cells identified above. On each pass through this loop, we may discover more boundary cells in the grid, in addition to those found above. Continue looping until no further boundary cells are found. */ while( recurse ) { /* Assume that the current pass though this loop will result in all boundary cells being draw, in which case we can then leave the loop. */ recurse = 0; /* Store the Y graphics coords at the bottom and top of the first row. */ cylo = ylo; cyhi = ylo + dy; /* Initialise the cell index */ icell = 0; /* Loop round every row of cells in this grid. */ for( irow = 0; irow < ncell; irow++ ) { /* Loop round every cell in the current row of cells. */ for( icol = 0; icol < ncell; icol++, icell++ ) { /* If the good/bad boundary passes through the current cell we need to draw it unless it has already been drawn. */ if( bndry[ icell ] && ! drawn[ icell ] ){ /* Get the upper and lower graphics X bounds of the current cell. */ cxlo = xlo + icol*dx; cxhi = cxlo + dx; /* Call this function recursively to draw the boundary through the current cell, setting the returned flag non-zero if any bad positions are found. */ if( TraceBorder( this, map, cxlo, cxhi, cylo, cyhi, 3, tol, sedges, method, class, status ) ) result = 1; /* The boundary may have passed out of the current cell and then back into the cell on the same edge (i.e. a small loop that pokes out into a neighbouring cell). Such neighbouring cells may not have been identified by the earlier section of this function, so we now ensure that any such cells are flagged as boundary cells. */ /* If the boundary passed out of the left edge of the cell... */ if( sedges[ 0 ] ) { /* If the current cell is at the left edge of the grid, indicate that the boundary passes out of the left edge of the grid. */ if( icol == 0 ) { edges[ 0 ] = 1; /* Left edge */ /* Otherwise, if the left hand neighbour of the current cell is not flagged as a boundary cell, flag it now and indicate that another pass though the loop is needed to draw the extra cell. */ } else if( ! bndry[ icell - 1 ] ) { bndry[ icell - 1 ] = 1; recurse = 1; } } /* If the boundary passed out of the top edge of the cell... */ if( sedges[ 1 ] ) { /* If the current cell is at the top edge of the grid, indicate that the boundary passes out of the top edge of the grid. */ if( irow == lastcell ) { edges[ 1 ] = 1; /* Top edge */ /* Otherwise, ensure that the upper neighbour of the current cell is flagged as a boundary cell. */ } else { bndry[ icell + ncell ] = 1; } } /* If the boundary passed out of the right edge of the cell... */ if( sedges[ 2 ] ) { /* If the current cell is at the right edge of the grid, indicate that the boundary passes out of the right edge of the grid. */ if( icol == lastcell ) { edges[ 2 ] = 1; /* Right edge */ /* Otherwise, ensure that the right hand neighbour of the current cell is flagged as a boundary cell. */ } else { bndry[ icell + 1 ] = 1; } } /* If the boundary passed out of the bottom edge of the cell... */ if( sedges[ 3 ] ) { /* If the current cell is at the bottom edge of the grid, indicate that the boundary passes out of the bottom edge of the grid. */ if( irow == 0 ) { edges[ 3 ] = 1; /* Bottom edge */ /* Otherwise, if the lower neighbour of the current cell is not flagged as a boundary cell, flag it now and indicate that another pass though the loop is needed to draw the extra cell. */ } else if( ! bndry[ icell - ncell ] ) { bndry[ icell - ncell ] = 1; recurse = 1; } } /* Indicate this cell has been drawn. */ drawn[ icell ] = 1; } } /* Store the Y graphics coords at the bottom and top of the next row. */ cylo += dy; cyhi = cylo + dy; } } } /* Free resources */ bndry = astFree( bndry ); drawn = astFree( drawn ); pset1 = astAnnul( pset1 ); pset2 = astAnnul( pset2 ); /* Return the result. */ return result; } static AstPointSet *Trans( AstPlot *this, AstFrame *frm, AstMapping *mapping, AstPointSet *in, int forward, AstPointSet *out, int norm, const char *method, const char *class, int *status ) { /* * Name: * Trans * Purpose: * Use a Mapping to transform a set of points. * Type: * Private function. * Synopsis: * #include "plot.h" * AstPointSet *Trans( AstPlot *this, AstFrame *frm, AstMapping *mapping, * AstPointSet *in, int forward, AstPointSet *out, * int norm, const char *method, const char *class ) * Class Membership: * Plot member function. * Description: * This performs the same task as the protected method astTransform * but uses the astTransform method for the supplied Mapping instead * the parent method for the Plot. This allows the Mapping to be * extracted from the Plot using astGetMapping once, rather than every * time a mapping is performed. * Parameters: * this * Pointer to the Plot (only used to access clipping attributes and * other methods). * frm * Pointer to the Current Frame in the Plot. If this is NULL, then * a pointer for the Current Frame is found within this function if * required (i.e. if "forward" and "norm" are both non-zero). * mapping * Pointer to the Mapping extracted from the Plot. If this is NULL, then * a pointer for the base->current Mapping is found within this function. * 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. * norm * The normalisation of returned physical coordinates is only done * if "norm" is non-zero. Otherwise they are left as returned by * astTransform. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * Returned Value: * Pointer to the output (possibly new) PointSet. * Notes: * - Clipping is only performed as set up using the astClip method. * In particular, the clipping specified by the arguments to the astPlot * constructor function is NOT performed. This is done in order to improve * the efficiency of the curve drawing method astGridLine. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Plot being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstFrame *cfr; /* Pointer to the Current Frame */ AstFrame *fr; /* Pointer to the clipping Frame */ AstMapping *map; /* Pointer to output->clip mapping */ AstPointSet *clip; /* Positions in clipping Frame */ AstPointSet *result; /* Positions in output Frame */ double **ptr_clip; /* Pointer to clipping Frame data */ double **ptr_out; /* Pointer to output coordinate data */ double *work; /* Pointer to array holding an o/p position */ double axval; /* Axis value in clipping frame */ double lbnd; /* Lower bound on current clipping axis */ double ubnd; /* Upper bound on current clipping axis */ int axin; /* Is the axis value within the allowed range? */ int clip_norm; /* Normalise the clipping positions? */ int clip_or; /* Combine axes using a logical OR? */ int clipit; /* Should the current point be clipped? */ int i; /* Point index */ int iframe; /* Validated index for clipping Frame */ int j; /* Axis index */ int naxes; /* Number of axes in clipping Frame */ int ncoord_out; /* Number of coordinates per output point */ int npoint; /* Number of points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Ensure we have a Mapping */ if( !mapping ) mapping = astGetMapping( this, AST__BASE, AST__CURRENT ); /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent FrameSet class. */ result = astTransform( mapping, in, forward, out ); /* Get the dimensions of the returned data, and an array of pointers to the axis values. */ ncoord_out = astGetNcoord( result ); npoint = astGetNpoint( result ); ptr_out = astGetPoints( result ); /* If we have done a forward mapping, we now normalise the returned physical positions if required using the astNorm method for the supplied object. */ if( forward && norm ){ /* If no Frame was supplied, get a pointer to the Current Frame. Otherwise, use the supplied pointer. */ if( !frm ) { cfr = astGetFrame( this, AST__CURRENT ); } else { cfr = frm; } /* Get work space to hold a single positions. */ work = (double *) astMalloc( sizeof(double)*(size_t)ncoord_out ); /* Check the work space and axis pointers can be used. */ if( astOK ){ /* Now loop through every position, copying the axis values to the work array, normalising them using astNorm, and copying them back to the returned PointSet. */ for( i = 0; i < npoint; i++ ){ for( j = 0; j < ncoord_out; j++ ) work[ j ] = ptr_out[ j ][ i ]; astNorm( cfr, work ); for( j = 0; j < ncoord_out; j++ ) ptr_out[ j ][ i ] = work[ j ]; } } /* Free the work space. */ work = (double *) astFree( (void *) work ); /* Annul the pointer to the Current Frame if it was obtained in this function. */ if( !frm ) cfr = astAnnul( cfr ); } /* Clipping is only performed if the bounds of a clipping region are available for both axes. */ if( this->clip_lbnd && this->clip_ubnd ){ /* Validate and translate the index of the clipping Frame. */ iframe = astValidateFrameIndex( this, this->clip_frame, method ); /* Obtain a pointer to the clipping Frame and determine how many axes it has. */ fr = astGetFrame( this, iframe ); naxes = astGetNaxes( fr ); /* Report an error if the number of bounds does not equal the number of axes in the clipping Frame. */ if( astOK && naxes != this->clip_axes ){ astError( AST__CLPAX, "%s%s): The supplied %s specifies clipping " "in %d dimensions, but the clipping Frame ('%s') has " "%d axes.", status, method, class, class, this->clip_axes, astGetTitle( fr ), naxes ); } /* Set a flag indicating if the coordinates in the clipping frame need to be normalised. */ clip_norm = 1; /* We now obtain a pointer to a PointSet holding the corresponding coordinates in the clipping frame. If the clipping frame is the base frame, then take a clone of the PointSet holding base frame coordinates. */ if( iframe == astGetBase( this ) ){ if( forward ){ clip = astClone( in ); } else { clip = astClone( result ); } /* If the clipping frame is the current frame, then take a clone of the PointSet holding current coordinates. Note, if the returned physical coordinates have already been normalised, we don't need to normalise the clipping coordinates. */ } else if( iframe == astGetCurrent( this ) ){ if( forward ){ clip = astClone( result ); if( norm ) clip_norm = 0; } else { clip = astClone( in ); } /* If the clipping Frame is neither the base nor the current Frame, we need to map the returned normalised points into the clipping Frame. */ } else { if( forward ){ map = astGetMapping( this, AST__CURRENT, iframe ); } else { map = astGetMapping( this, AST__BASE, iframe ); } clip = astTransform( map, result, 1, NULL ); map = astAnnul( map ); } /* Get a pointer to the coordinate data in the clipping Frame. */ ptr_clip = astGetPoints( clip ); /* If necessary, normalise the coordinates in the clipping frame. */ if( clip_norm ){ /* Get work space to hold a single position. */ work = (double *) astMalloc( sizeof(double)*(size_t)naxes ); /* Check the work space and axis pointers can be used. */ if( astOK ){ /* Now loop through every position, copying the axis values to the work array, normalising them using astNorm, and copying them back to the clipping PointSet. */ for( i = 0; i < npoint; i++ ){ for( j = 0; j < naxes; j++ ) work[ j ] = ptr_clip[ j ][ i ]; astNorm( fr, work ); for( j = 0; j < naxes; j++ ) ptr_clip[ j ][ i ] = work[ j ]; } } /* Free the work space. */ work = (double *) astFree( (void *) work ); } /* If all has gone ok, we will now clip the returned points. */ if( astOK ){ /* Get the logical operation to be used to determine if a point is to be clipped. A zero value means that a logical AND is to be performed between the axes (i.e. all axes must be within the supplied bounds for a point to be retained). A non-zero value means that a logical OR is to be performed between the axes (i.e. only a single axis need be within the supplied bounds for a point to be retained). */ clip_or = astGetClipOp( this ); /* Do each point in turn. */ for( j = 0; j < npoint; j++ ){ /* If all axes must fall within the supplied range to avoid the point being clipped (i.e. if clip_or is 0), then assume initially that the point is not to be clipped. This will be toggled as soon as the first out-of-bounds point is found. If, on the other hand, the point is only clipped if all axis values are out-of-bounds, then assume initially that the point is to be clipped. This will be toggled as soon as the first axis value is found which is not out-of-bounds. */ clipit = clip_or; /* Check each axis value for the current point. */ for( i = 0; i < naxes; i++ ){ axval = ptr_clip[ i ][ j ]; /* Chekc that it is not bad. */ if( axval != AST__BAD ){ /* Store the bounds of the clipping volume on this axis. */ lbnd = this->clip_lbnd[ i ]; ubnd = this->clip_ubnd[ i ]; /* Set a flag indicating if the axis value is within the specified range. If the supplied bounds are reversed, they specify the range to exclude, otherwise they specify the range to include. */ if( lbnd <= ubnd ){ axin = ( axval >= lbnd && axval <= ubnd ); } else { axin = ( axval < ubnd || axval > lbnd ); } /* If the point is within the range and only one such point is required to avoid the point being clipped, indicate that the point should not be clipped, and leave the loop. */ if( axin && clip_or ){ clipit = 0; break; /* If the point is not within the range and we only one such point is required to cause the point to be clipped, indicate that the point should be clipped, and leave the loop. */ } else if( !axin && !clip_or ){ clipit = 1; break; } /* Clip the point if any axis value is bad in the clipping Frame. */ } else { clipit = 1; break; } } /* If the point is to be clipped, set all returned axis values bad. */ if( clipit ) { for( i = 0; i < naxes; i++ ) ptr_out[ i ][ j ] = AST__BAD; } } } /* Annul the PointSet holding clipping Frame positions. */ if( clip ) clip = astAnnul( clip ); /* Annul the clipping Frame pointer. */ fr = astAnnul( fr ); } /* If an error has occurred, annul the result. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Use a Plot to transform a set of points. * Type: * Private function. * Synopsis: * #include "plot.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out ) * Class Membership: * Plot member function (over-rides the astTransform protected * method inherited from the FrameSet class). * Description: * This function takes a Plot and a set of points encapsulated in a * PointSet and transforms the points from graphics coordinates to * physical coordinates (in the forward direction). If the returned * positions are physical coordinates (i.e. if a forward mapping is * performed) they are normalised using the astNorm method of the supplied * Plot. The returned axis values are set to AST__BAD for any positions * which are outside the clipping volume set up by the astClip method. * Parameters: * this * Pointer to the Plot. * in * Pointer to the PointSet holding the input coordinate data. * forward * A non-zero value indicates that the forward coordinate * transformation should be applied while a zero value requests the * inverse transformation. * out * Pointer to a PointSet which will hold the transformed (output) * coordinate values. A NULL value may also be given, in which case a * new PointSet will be created by this function. * Returned Value: * Pointer to the output (possibly new) PointSet. * Notes: * - Clipping is only performed as set up using the astClip method. * In particular, the clipping specified by the arguments to the astPlot * constructor function is NOT performed. This is done in order to improve * the efficiency of the curve drawing method astGridLine. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Plot being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstMapping *map; /* Pointer to the mapping */ AstPointSet *result; /* Positions in output Frame */ AstPlot *plot; /* The Plot */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the Plot. */ plot = (AstPlot *) this; /* Get the Mapping from the base to the current Frame. */ map = astGetMapping( plot, AST__BASE, AST__CURRENT ); /* Do the transformation. */ result = Trans( plot, NULL, map, in, forward, out, 1, "astTransform", astGetClass( this ), status ); /* Annul the mapping. */ map = astAnnul( map ); /* If an error has occurred, annul the result. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static double Typical( int n, double *value, double lolim, double hilim, double *width, int *status ) { /* * Name: * Typical * Purpose: * Return a typical value within the supplied array of values. * Type: * Private function. * Synopsis: * #include "plot.h" * double Typical( int n, double *value, double lolim, double hilim, * double *width, int *status ) * Class Membership: * Plot member function. * Description: * This function locates the approximate mode of the supplied values, * and returns one of the supplied values which is close to the modal * value. Values outside an indicated range are ignored. * Parameters: * n * The number of data values. * value * A pointer to an array of "n" values. * lolim * Values less than lolim are ignored. Supply as -DBL_MAX if there * is no lower limit. * hilim * Values greater than hilim are ignored. Supply as DBL_MAX if there * is no upper limit. * width * Pointer to a double in which to return the width (i,e, data range) * of the non-empty histogram cells. This is an estimate of the * range of used values in the supplied array. NULL may be supplied. * status * Pointer to the inherited status variable. * Returned Value: * A typical value from the supplied array. AST__BAD is returned only * if an error has occurred, or if all the supplied values are AST__BAD * or outside the specified range. */ /* Local Variables: */ double *a; /* Pointer to next value */ double cnt; /* Modified count */ double delta; /* Bin size */ double maxval; /* Maximum supplied value */ double mean; /* Mean supplied value */ double minval; /* Minimum supplied value */ double result; /* The returned value. */ double w0; /* Rate of increase of weight with dist from edge */ double w1; /* Weight for left edge */ double w2; /* Weight for right edge */ double w; /* Weight for this bin */ int *hist; /* Pointer to first cell of histogram array */ int i; /* Loop count */ int ibin; /* Bin index */ int maxcnt; /* Maximum no. of values in any bin */ int modify; /* Modify the effect of the edge bins? */ int nbin; /* No. of bins in histogram */ int nc; /* Total number of points in histogram */ int ngood; /* No. of good values supplied */ int nonemp; /* No. of non-empty bins in hstogram */ /* Initialise. */ result = AST__BAD; if( width ) *width = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ ibin = 0; /* Find the minimum and maximum value in the supplied array, which are also within the supplied limits. Also store the first good value encountered in "result". */ minval = DBL_MAX; maxval = -DBL_MAX; a = value; ngood = 0; for( i = 0; i < n; i++, a++ ) { if( *a != AST__BAD ) { if( *a >= lolim && *a <= hilim ) { if( *a < minval ) minval = *a; if( *a > maxval ) maxval = *a; if( ngood == 0 ) result = *a; ngood++; } } } /* Initialise the returned width to the total data range. */ if( width && maxval != -DBL_MAX ) *width = maxval - minval; /* If less than 3 points were found, we will return the first. Otherwise, if 3 or more good values were found, find a typical value. */ if( ngood > 2 ) { /* We will form a histogram of the supplied values in order to find the mode. The number of bins in this histogram is chosen so that there is an average of 2 points per bin. Find the number of bins. */ nbin = ( ngood + 1 )/2; /* Find the bin size. If zero (i.e. if all values are equal), return the first good value established above. */ delta = ( maxval - minval )/ nbin; if( delta > 0.0 ) { /* Allocat ememory for the histogram. */ hist = astMalloc( sizeof(int)*(size_t)nbin ); if( hist ) { /* Initialise the histogram. */ for( i = 0; i < nbin; i++ ) hist[ i ] = 0; /* Form the histogram. Form the mean data value at the same time. */ mean = 0.0; a = value; nc = 0; for( i = 0; i < n; i++, a++ ){ if( *a != AST__BAD ) { if( *a >= lolim && *a <= hilim ) { mean += *a; ibin = (int) ( ( *a - minval )/ delta ); if( ibin == nbin ) ibin--; hist[ ibin ]++; nc++; } } } mean /= ngood; /* We tend to prefer not to use reference values which are very close the the limits since they can give problems with regard to normalization (rounding errors can knock them over the edge), so we modify the counts in each bin of the histogram to reduce the impact of bins near the edge. However, we do not do this if the number of bins is very small or if all the counts are in the edge bins. */ modify = ( nbin > 4 && ( hist[ 0 ] + hist[ nbin - 1 ] < 0.98*ngood ) ); /* Find the bin with the highest modified count. If there is more than one bin with the highest modified count, choose the one which is closest to the mean data value found above. Also count the number of non-empty bins. */ nonemp = 0; maxcnt = 0; w0 = nbin/2; for( i = 0; i < nbin; i++ ) { cnt = hist[ i ]; if( cnt ) nonemp++; if( modify ) { w1 = i*w0; w2 = ( nbin - 1 - i )*w0; w = ( w1 < w2 ) ? w1 :w2; if( w < 1.0 ) cnt *= w; } if( cnt > maxcnt ) { maxcnt = cnt; ibin = i; } else if( cnt == maxcnt ) { if( fabs( minval + ( i - 0.5 )*delta - mean ) < fabs( minval + ( ibin - 0.5 )*delta - mean ) ) { maxcnt = cnt; ibin = i; } } } /* Free the histogram memory. */ hist = astFree( hist ); /* If required, return the width of the non-empty bins. */ if( width ) *width = nonemp*delta; /* Call this function recursively to refine the value, restricting attention to those data values which are within the range of the bin found above. */ if( maxcnt < nc && ibin*delta > 1000.0*DBL_EPSILON*fabs(maxval) ) { minval += ibin*delta; maxval = minval + delta; result = Typical( n, value, minval, maxval, NULL, status ); } } } } /* Return the result. */ return result; } static int GetUseColour( AstPlot *this, int id, int *status ) { /* * Name: * GetUseColour * Purpose: * Get the Colour value to use for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int GetUseColour( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This returns the Colour value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the colour * for the first set specific value is returned. For example, if the * Colour for AST__AXES_ID is requested, then the colour for AST__AXIS1_ID * will be returned if set, and otherwise the colour for AST__AXIS2_ID will * be returned. If AST__AXIS2_ID is not set either, then the default for * AST__AXIS2_ID will be returned. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Colour value to use. */ /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return NOCOLOUR; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the value of the first set genuine identifier. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); if( nid > 1 ) { if( astTestColour( this, id1 ) ) { id = id1; } else if( nid > 1 && astTestColour( this, id2 ) ) { id = id2; } else if( nid > 2 && astTestColour( this, id3 ) ) { id = id3; } else { id = id1; } } /* Return the result. */ return astGetColour( this, id ); } static int GetUseFont( AstPlot *this, int id, int *status ) { /* * Name: * GetUseFont * Purpose: * Get the Font value to use for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int GetUseFont( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This returns the Font value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the Font * for the first set specific value is returned. For example, if the * Font for AST__AXES_ID is requested, then the Font for AST__AXIS1_ID * will be returned if set, and otherwise the Font for AST__AXIS2_ID will * be returned. If AST__AXIS2_ID is not set either, then the default for * AST__AXIS2_ID will be returned. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Font value to use. */ /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return NOFONT; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the value of the first set genuine identifier. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); if( nid > 1 ) { if( astTestFont( this, id1 ) ) { id = id1; } else if( nid > 1 && astTestFont( this, id2 ) ) { id = id2; } else if( nid > 2 && astTestFont( this, id3 ) ) { id = id3; } else { id = id1; } } /* Return the result. */ return astGetFont( this, id ); } static double GetUseSize( AstPlot *this, int id, int *status ) { /* * Name: * GetUseSize * Purpose: * Get the Size value to use for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * double GetUseSize( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This returns the Size value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the Size * for the first set specific value is returned. For example, if the * Size for AST__AXES_ID is requested, then the Size for AST__AXIS1_ID * will be returned if set, and otherwise the Size for AST__AXIS2_ID will * be returned. If AST__AXIS2_ID is not set either, then the default for * AXIS2_ID will be returned. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Size value to use. */ /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return NOSIZE; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the value of the first set genuine identifier. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); if( nid > 1 ) { if( astTestSize( this, id1 ) ) { id = id1; } else if( nid > 1 && astTestSize( this, id2 ) ) { id = id2; } else if( nid > 2 && astTestSize( this, id3 ) ) { id = id3; } else { id = id1; } } /* Return the result. */ return astGetSize( this, id ); } static int GetUseStyle( AstPlot *this, int id, int *status ) { /* * Name: * GetUseStyle * Purpose: * Get the Style value to use for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int GetUseStyle( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This returns the Style value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the style * for the first set specific value is returned. For example, if the * Style for AST__AXES_ID is requested, then the style for AST__AXIS1_ID * will be returned if set, and otherwise the style for AST__AXIS2_ID will * be returned. If AST__AXIS2_ID is not set either, then the default for * AST__AXIS2_ID will be returned. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Style value to use. */ /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return NOSTYLE; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the value of the first set genuine identifier. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); if( nid > 1 ) { if( astTestStyle( this, id1 ) ) { id = id1; } else if( nid > 1 && astTestStyle( this, id2 ) ) { id = id2; } else if( nid > 2 && astTestStyle( this, id3 ) ) { id = id3; } else { id = id1; } } /* Return the result. */ return astGetStyle( this, id ); } static double GetUseWidth( AstPlot *this, int id, int *status ) { /* * Name: * GetUseWidth * Purpose: * Get the Width value to use for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * double GetUseWidth( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This returns the Width value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the Width * for the first set specific value is returned. For example, if the * Width for AST__AXES_ID is requested, then the Width for AST__AXIS1_ID * will be returned if set, and otherwise the Width for AST__AXIS2_ID will * be returned. If AST__AXIS2_ID is not set either, then the default for * AST__AXIS2_ID will be returned. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Width value to use. */ /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return NOWIDTH; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the value of the first set genuine identifier. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); if( nid > 1 ) { if( astTestWidth( this, id1 ) ) { id = id1; } else if( nid > 1 && astTestWidth( this, id2 ) ) { id = id2; } else if( nid > 2 && astTestWidth( this, id3 ) ) { id = id3; } else { id = id1; } } /* Return the result. */ return astGetWidth( this, id ); } static int TestUseColour( AstPlot *this, int id, int *status ) { /* * Name: * TestUseColour * Purpose: * Test the Colour value for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestUseColour( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This tests the Colour value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the element * is considered to be set if all the corresponding specific values are * set. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Colour value state (1 if set, zero otherwise). */ /* Local Variables: */ int ret; /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return 0; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the logical AND of the test flags for the genuine identifiers. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); ret = astTestColour( this, id1 ); if( nid > 1 ) ret = ret && astTestColour( this, id2 ); if( nid > 2 ) ret = ret && astTestColour( this, id3 ); /* Return the result. */ return ret; } static int TestUseFont( AstPlot *this, int id, int *status ) { /* * Name: * TestUseFont * Purpose: * Test the Font value for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestUseFont( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This tests the Font value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the element * is considered to be set if all the corresponding specific values are * set. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Font value state (1 if set, zero otherwise). */ /* Local Variables: */ int ret; /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return 0; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the logical AND of the test flags for the genuine identifiers. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); ret = astTestFont( this, id1 ); if( nid > 1 ) ret = ret && astTestFont( this, id2 ); if( nid > 2 ) ret = ret && astTestFont( this, id3 ); /* Return the result. */ return ret; } static int TestUseSize( AstPlot *this, int id, int *status ) { /* * Name: * TestUseSize * Purpose: * Test the Size value for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestUseSize( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This tests the Size value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the element * is considered to be set if all the corresponding specific values are * set. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Size value state (1 if set, zero otherwise). */ /* Local Variables: */ int ret; /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return 0; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the logical AND of the test flags for the genuine identifiers. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); ret = astTestSize( this, id1 ); if( nid > 1 ) ret = ret && astTestSize( this, id2 ); if( nid > 2 ) ret = ret && astTestSize( this, id3 ); /* Return the result. */ return ret; } static int TestUseStyle( AstPlot *this, int id, int *status ) { /* * Name: * TestUseStyle * Purpose: * Test the Style value for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestUseStyle( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This tests the Style value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the element * is considered to be set if all the corresponding specific values are * set. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Style value state (1 if set, zero otherwise). */ /* Local Variables: */ int ret; /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return 0; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the logical AND of the test flags for the genuine identifiers. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); ret = astTestStyle( this, id1 ); if( nid > 1 ) ret = ret && astTestStyle( this, id2 ); if( nid > 2 ) ret = ret && astTestStyle( this, id3 ); /* Return the result. */ return ret; } static int TestUseWidth( AstPlot *this, int id, int *status ) { /* * Name: * TestUseWidth * Purpose: * Test the Width value for a specified graphical element. * Type: * Private function. * Synopsis: * #include "plot.h" * int TestUseWidth( AstPlot *this, int id, int *status ) * Class Membership: * Plot member function. * Description: * This tests the Width value for the graphical element specified by * id. If an element related to a generic value is being accessed (e.g * "Axes" is generic, "Axis1" and "Axis2" are not), then the element * is considered to be set if all the corresponding specific values are * set. * Parameters: * this * Pointer to the Plot. * id * An integer specifying the graphical element to be drawn. * status * Pointer to the inherited status variable. * Returned Value: * The Width value state (1 if set, zero otherwise). */ /* Local Variables: */ int ret; /* Local Variables: */ int id1; /* First genuine identifier */ int id2; /* Second genuine identifier */ int id3; /* Third genuine identifier */ int nid; /* Number of genuine attributes */ /* Check the global error status. */ if ( !astOK ) return 0; /* See if the supplied identifier is a psuedo-identifier representing two or three other genuine identifiers. If so, return the logical AND of the test flags for the genuine identifiers. */ nid = IdFind( id, astGetNin( this ), &id1, &id2, &id3, status ); ret = astTestWidth( this, id1 ); if( nid > 1 ) ret = ret && astTestWidth( this, id2 ); if( nid > 2 ) ret = ret && astTestWidth( this, id3 ); /* Return the result. */ return ret; } static int ToggleLogLin( AstPlot *this, int axis, int islog, const char *method, int *status ){ /* * * Name: * ToggleLogLin * Purpose: * Toggle the nature of the Plot axis mapping. * Type: * Private function. * Synopsis: * #include "plot.h" * int ToggleLogLin( AstPlot *this, int axis, int islog, * const char *method, int *status ) * Class Membership: * Plot member function * Description: * Each axis in the graphics Frame of a Plot can be mapped linearly or * logarithmically onto the corresponding axis in the base Frame of * the FrameSet supplied whtn the Plot was constructed. This function * toggles the nature of the specified axis; if it is currently * logarithmic it becomes linear, and if it is linear it becomes * logarithmic. * * If the Frame canot be re-maped (for instance because the visible * part of the axis includes the value zero), then zero is returned * but no error is reported. * Parameters: * this * The Plot. * axis * Zero based axis index. * islog * Is the axis currently logarithmic? If so, this function remaps * it so that it is linear (and vice-versa). * method * Pointer to a null-terminated string holding the name of the calling * method (only used within error mesages). * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the attempt to re-map the graphics Frame was succesful, * zero otherwise. */ /* Local Variables: */ AstCmpMap *remap1; /* 1D Mapping to re-map the graphics Frame */ AstCmpMap *remap2; /* 2D Mapping to re-map the graphics Frame */ AstMathMap *logmap; /* 1D Logarithmic axis Mapping */ AstUnitMap *unitmap; /* 1D Unit mapping */ AstWinMap *linmap; /* 1D Linear axis Mapping */ char fwdexp[ 25 + 2*DBL_DIG ]; /* Forward log mapping expression */ char invexp[ 28 + 2*DBL_DIG ]; /* Inverse log mapping expression */ const char *fwd[1]; /* Pointer to pass to MathMap constructor */ const char *inv[1]; /* Pointer to pass to MathMap constructor */ double a; /* Constant for log expression */ double b1; /* Original base Frame axis value at first edge */ double b2; /* Original base Frame axis value at second edge */ double b; /* Constant for log expression */ double c; /* Constant for log expression */ double g1; /* Graphics axis value at first edge */ double g2; /* Graphics axis value at second edge */ int result; /* Returned value */ /* Inotialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Get the corresponding axis limits in the graphics coordinate system and the original base Frame coordinate system. */ if( axis == 0 ) { if( this->xrev ) { g1 = this->xhi; g2 = this->xlo; } else { g1 = this->xlo; g2 = this->xhi; } b1 = this->bbox[ 0 ]; b2 = this->bbox[ 2 ]; } else { if( this->yrev ) { g1 = this->yhi; g2 = this->ylo; } else { g1 = this->ylo; g2 = this->yhi; } b1 = this->bbox[ 1 ]; b2 = this->bbox[ 3 ]; } /* Check the limits are usable (e.g. the base Frame values will be bad if this Plot was restored from a dump of a Plot created before the LogPlot attributes were added). */ if( b1 != AST__BAD && b2 != AST__BAD && g1 != g2 && b1 != b2 && b1*b2 > 0.0 ) { /* Form the 1D Mapping which maps the specified axis linearly onto the plotting surface. The forward transformation goes from graphics to base Frame. */ linmap = astWinMap( 1, &g1, &g2, &b1, &b2, "", status ); /* Form the 1D Mapping which maps the specified axis logarithmically onto the plotting surface. The forward transformation goes from graphics to base Frame. */ c = log10( b1/b2 ); a = ( g1 - g2 )/c; if( b1 > 0.0 ) { b = ( g2*log10( b1 ) - g1*log10( b2 ) )/c; (void) sprintf( invexp, "g=%.*g*log10(b)+%.*g", DBL_DIG, a, DBL_DIG, b ); (void) sprintf( fwdexp, "b=pow(10,(g-%.*g)/%.*g)", DBL_DIG, b, DBL_DIG, a ); } else { b = ( g2*log10( -b1 ) - g1*log10( -b2 ) )/c; (void) sprintf( invexp, "g=%.*g*log10(-b)+%.*g", DBL_DIG, a, DBL_DIG, b ); (void) sprintf( fwdexp, "b=-pow(10,(g-%.*g)/%.*g)", DBL_DIG, b, DBL_DIG, a ); } fwd[ 0 ] = (const char *) fwdexp; inv[ 0 ] = (const char *) invexp; logmap = astMathMap( 1, 1, 1, fwd, 1, inv, "SimpFI=1,SimpIF=1", status ); /* If the axis was previously logarithmic, get the Mapping with which to remap the graphics Frame so that it becomes linearly related to the base Frame in the FrameSet supplied when the Plot was constructed. */ if( islog ) { astInvert( linmap ); remap1 = astCmpMap( logmap, linmap, 1, "", status ); /* If the axis was previously linear, store the new value and get the Mapping with which to remap the graphics Frame so that it becomes logarithmically related to the base Frame in the FrameSet supplied when the Plot was constructed. */ } else { astInvert( logmap ); remap1 = astCmpMap( linmap, logmap, 1, "", status ); } /* Add a 1D UnitMap to map the unaltered mapping. */ unitmap = astUnitMap( 1, "", status ); if( axis == 0 ) { remap2 = astCmpMap( remap1, unitmap, 0, "", status ); } else { remap2 = astCmpMap( unitmap, remap1, 0, "", status ); } /* Remap the base (graphics) Frame in the Plot. */ astRemapFrame( this, AST__BASE, remap2 ); /* Free resources. */ remap1 = astAnnul( remap1 ); remap2 = astAnnul( remap2 ); logmap = astAnnul( logmap ); linmap = astAnnul( linmap ); unitmap = astAnnul( unitmap ); /* Indicate success. */ if( astOK ) result = 1; } /* Return the result. */ return result; } static int Ustrcmp( const char *a, const char *b, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strcmp. * Type: * Private function. * Synopsis: * #include "plot.h" * int Ustrcmp( const char *a, const char *b ) * Class Membership: * Plot member function. * Description: * Returns 0 if there are no differences between the two strings, and 1 * otherwise. Comparisons are case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference between * the two strings, whereas "strcmp" does. * - This function attempts to execute even if an error has occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Loop round each character. */ while( 1 ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } static int Ustrncmp( const char *a, const char *b, size_t n, int *status ){ /* * Name: * Ustrncmp * Purpose: * A case blind version of strncmp. * Type: * Private function. * Synopsis: * #include "plot.h" * int Ustrncmp( const char *a, const char *b, size_t n ) * Class Membership: * Plot member function. * Description: * Returns 0 if there are no differences between the first "n" * characters of the two strings, and 1 otherwise. Comparisons are * case blind. * Parameters: * a * Pointer to first string. * b * Pointer to second string. * n * The maximum number of characters to compare. * Returned Value: * Zero if the strings match, otherwise one. * Notes: * - This function does not consider the sign of the difference * between the two strings, whereas "strncmp" does. * - This function attempts to execute even if an error has * occurred. */ /* Local Variables: */ const char *aa; /* Pointer to next "a" character */ const char *bb; /* Pointer to next "b" character */ int i; /* Character index */ int ret; /* Returned value */ /* Initialise the returned value to indicate that the strings match. */ ret = 0; /* Initialise pointers to the start of each string. */ aa = a; bb = b; /* Compare up to "n" characters. */ for( i = 0; i < (int) n; i++ ){ /* We leave the loop if either of the strings has been exhausted. */ if( !(*aa ) || !(*bb) ){ /* If one of the strings has not been exhausted, indicate that the strings are different. */ if( *aa || *bb ) ret = 1; /* Break out of the loop. */ break; /* If neither string has been exhausted, convert the next characters to upper case and compare them, incrementing the pointers to the next characters at the same time. If they are different, break out of the loop. */ } else { if( toupper( (int) *(aa++) ) != toupper( (int) *(bb++) ) ){ ret = 1; break; } } } /* Return the result. */ return ret; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Plot objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Plot 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: */ AstPlot *this; /* Pointer to Plot */ int i; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) obj; /* Free the clipping bounds arrays. */ this->clip_lbnd = (double *) astFree( (void *) this->clip_lbnd ); this->clip_ubnd = (double *) astFree( (void *) this->clip_ubnd ); /* Free the Grf function stack */ this->grfstack = (AstGrfPtrs *) astFree( (void *) this->grfstack ); /* Free the graphics attribute stack. */ for( i = this->ngat - 1; i >= 0; i-- ) { this->gat[ i ] = astFree( this->gat[ i ] ); } /* Free the graphics context pointer. */ if( this->grfcontext ) { this->grfcontext = astAnnul( this->grfcontext ); this->grfcontextID = astAnnulId( this->grfcontextID ); } /* Free the information about the tick marks to draw. */ for( i = 0; i < 3; i++ ) { this->majtickval[ i ] = astFree( this->majtickval[ i ] ); this->mintickval[ i ] = astFree( this->mintickval[ i ] ); this->nmajtickval[ i ] = 0; this->nmintickval[ i ] = 0; } /* Free the information about the drawn tick marks. */ SaveTick( this, -1, 0.0, 0.0, 0, status ); } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Plot objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Plot 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: */ AstPlot *in; /* Pointer to input Plot */ AstPlot *out; /* Pointer to output Plot */ int axis; /* Zero based axis index */ int n; /* Number of ticks saved */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Plots. */ in = (AstPlot *) objin; out = (AstPlot *) objout; /* For safety, first clear any references to the input memory from the output Plot. */ out->clip_lbnd = NULL; out->clip_ubnd = NULL; out->gat = NULL; out->ngat = 0; for( axis = 0; axis < 3; axis++ ) { out->majtickgx[ axis ] = NULL; out->majtickgy[ axis ] = NULL; out->majtickcount[ axis ] = 0; out->mintickgx[ axis ] = NULL; out->mintickgy[ axis ] = NULL; out->mintickcount[ axis ] = 0; out->majtickval[ axis ] = NULL; out->nmajtickval[ axis ] = 0; out->mintickval[ axis ] = NULL; out->nmintickval[ axis ] = 0; } /* Copy the clipping bounds arrays. */ out->clip_lbnd = (double *) astStore( NULL, (void *) in->clip_lbnd, sizeof(double)*(size_t)(in->clip_axes) ); out->clip_ubnd = (double *) astStore( NULL, (void *) in->clip_ubnd, sizeof(double)*(size_t)(in->clip_axes) ); /* Copy the Grf function stack */ out->grfstack = (AstGrfPtrs *) astStore( NULL, (void *) in->grfstack, sizeof(AstGrfPtrs)*(size_t)(in->grfnstack )); /* Copy the information about drawn tick marks. */ for( axis = 0; axis < 3; axis++ ) { n = in->majtickcount[ axis ]; out->majtickgx[ axis ] = (double *) astStore( NULL, in->majtickgx[ axis ], n*sizeof( double ) ); out->majtickgy[ axis ] = (double *) astStore( NULL, in->majtickgy[ axis ], n*sizeof( double ) ); out->majtickcount[ axis ] = n; n = in->mintickcount[ axis ]; out->mintickgx[ axis ] = (double *) astStore( NULL, in->mintickgx[ axis ], n*sizeof( double ) ); out->mintickgy[ axis ] = (double *) astStore( NULL, in->mintickgy[ axis ], n*sizeof( double ) ); out->mintickcount[ axis ] = n; n = in->nmajtickval[ axis ]; out->majtickval[ axis ] = (double *) astStore( NULL, in->majtickval[ axis ], n*sizeof( double ) ); out->nmajtickval[ axis ] = n; n = in->nmintickval[ axis ]; out->mintickval[ axis ] = (double *) astStore( NULL, in->mintickval[ axis ], n*sizeof( double ) ); out->nmintickval[ axis ] = n; } /* If an error occurred, free any allocated memory. */ if ( !astOK ) { out->clip_lbnd = (double *) astFree( out->clip_lbnd ); out->clip_ubnd = (double *) astFree( out->clip_ubnd ); out->grfstack = (AstGrfPtrs *) astFree( out->grfstack ); SaveTick( out, -1, 0.0, 0.0, 0, status ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Plot 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 Plot class to an output Channel. * Parameters: * this * Pointer to the Plot whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstPlot *this; /* Pointer to the Plot structure */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ char *comment; /* Pointer to comment string */ double dval; /* Double precision value */ int ax; /* Axis to which element refers */ int axis; /* Zero based axis index */ int id; /* Zero based graphical object id */ int ival; /* Integer value */ int itick; /* Tick mark index */ int nax; /* Number of base Frame axes */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Plot structure. */ this = (AstPlot *) this_object; /* Get the number of graphics (base) frame axes - 2 for a Plot, 3 for a Plot3D. */ nax = astGetNin( this ); /* Write out values representing the instance variables for the Plot 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. */ /* Tol. */ /* ---- */ set = TestTol( this, status ); dval = set ? GetTol( this, status ) : astGetTol( this ); astWriteDouble( channel, "Tol", set, 0, dval, "Plotting tolerance" ); /* Grid. */ /* ----- */ set = TestGrid( this, status ); ival = set ? GetGrid( this, status ) : astGetGrid( this ); astWriteInt( channel, "Grid", set, 0, ival, "Is a grid required?" ); /* TickAll. */ /* -------- */ set = TestTickAll( this, status ); ival = set ? GetTickAll( this, status ) : astGetTickAll( this ); astWriteInt( channel, "TckAll", set, 1, ival, "Put ticks on all edges?" ); /* ForceExterior. */ /* -------------- */ set = TestForceExterior( this, status ); ival = set ? GetForceExterior( this, status ) : astGetForceExterior( this ); astWriteInt( channel, "FrcExt", set, 1, ival, "Force exterior labelling?" ); /* Invisible. */ /* ---------- */ set = TestInvisible( this, status ); ival = set ? GetInvisible( this, status ) : astGetInvisible( this ); astWriteInt( channel, "Invsbl", set, 1, ival, "Use invisible ink?" ); /* Border. */ /* ------- */ set = TestBorder( this, status ); ival = set ? GetBorder( this, status ) : astGetBorder( this ); astWriteInt( channel, "Border", set, 0, ival, "Draw a border round the grid?" ); /* ClipOp. */ /* ------- */ set = TestClipOp( this, status ); ival = set ? GetClipOp( this, status ) : astGetClipOp( this ); astWriteInt( channel, "ClpOp", set, 0, ival, "Clip using logical OR?" ); /* Clip. */ /* ----- */ set = TestClip( this, status ); ival = set ? GetClip( this, status ) : astGetClip( this ); astWriteInt( channel, "Clip", set, 0, ival, ((ival == 0)?"Do not clip at plot edges": ((ival == 1)?"Clip curves at plot edges": ((ival == 2)?"Clip markers at plot edges": "Clip markers and curves at plot edges")))); /* DrawTitle. */ /* --------- */ set = TestDrawTitle( this, status ); ival = set ? GetDrawTitle( this, status ) : astGetDrawTitle( this ); astWriteInt( channel, "DrwTtl", set, 1, ival, "Add a title to the grid?" ); /* DrawAxesUnits(axis). */ /* ----------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestDrawAxes( this, axis, status ); ival = set ? GetDrawAxes( this, axis, status ) : astGetDrawAxes( this, axis ); (void) sprintf( buff, "DrwAxs%d", axis + 1 ); astWriteInt( channel, buff, set, 0, ival, "Draw axis through ticks?" ); } /* Abbrev(axis). */ /* ------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestAbbrev( this, axis, status ); ival = set ? GetAbbrev( this, axis, status ) : astGetAbbrev( this, axis ); (void) sprintf( buff, "Abbrv%d", axis + 1 ); astWriteInt( channel, buff, set, 0, ival, "Abbreviate numerical axis labels?" ); } /* Escape. */ /* ------- */ set = TestEscape( this, status ); ival = set ? GetEscape( this, status ) : astGetEscape( this ); astWriteInt( channel, "Escape", set, 1, ival, "Interpret escape sequences?" ); /* LabelAt(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLabelAt( this, axis, status ); dval = set ? GetLabelAt( this, axis, status ) : astGetLabelAt( this, axis ); if( dval != AST__BAD ){ (void) sprintf( buff, "LblAt%d", axis + 1 ); astWriteDouble( channel, buff, set, 0, dval, "Put numerical labels at" ); } } /* Centre(axis). */ /* ------------ */ for( axis = 0; axis < nax; axis++ ){ set = TestCentre( this, axis, status ); dval = set ? GetCentre( this, axis, status ) : astGetCentre( this, axis ); if( dval != AST__BAD ){ (void) sprintf( buff, "Cen%d", axis + 1 ); astWriteDouble( channel, buff, set, 0, dval, "Tick mark origin" ); } } /* Gap(axis). */ /* ---------- */ /* Discovering the default value requires a lot of calculation. Only write out this attribute if an explicit value has been set. */ for( axis = 0; axis < nax; axis++ ){ if( astTestGap( this, axis ) ) { dval = astGetGap( this, axis ); if( dval != AST__BAD ){ (void) sprintf( buff, "Gap%d", axis + 1 ); astWriteDouble( channel, buff, set, 0, dval, "Difference between ticks" ); } } } /* LogGap(axis). */ /* ------------- */ /* Discovering the default value requires a lot of calculation. Only write out this attribute if an explicit value has been set. */ for( axis = 0; axis < nax; axis++ ){ if( astTestLogGap( this, axis ) ) { dval = astGetLogGap( this, axis ); if( dval != AST__BAD ){ (void) sprintf( buff, "LgGap%d", axis + 1 ); astWriteDouble( channel, buff, set, 0, dval, "Ratio between ticks" ); } } } /* NumLabGap(axis). */ /* ---------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestNumLabGap( this, axis, status ); dval = set ? GetNumLabGap( this, axis, status ) : astGetNumLabGap( this, axis ); if( dval != AST__BAD ) { (void) sprintf( buff, "NmGap%d", axis + 1 ); astWriteDouble( channel, buff, set, 1, dval, "Spacing of numerical labels" ); } } /* TextLabGap(axis). */ /* ----------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestTextLabGap( this, axis, status ); dval = set ? GetTextLabGap( this, axis, status ) : astGetTextLabGap( this, axis ); if( dval != AST__BAD ) { (void) sprintf( buff, "TxGap%d", axis + 1 ); astWriteDouble( channel, buff, set, 1, dval, "Spacing of descriptive labels" ); } } /* LabelUp(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLabelUp( this, axis, status ); ival = set ? GetLabelUp( this, axis, status ) : astGetLabelUp( this, axis ); (void) sprintf( buff, "LblUp%d", axis + 1 ); astWriteInt( channel, buff, set, 1, ival, "Draw numerical labels upright?" ); } /* LogPlot(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLogPlot( this, axis, status ); ival = set ? GetLogPlot( this, axis, status ) : astGetLogPlot( this, axis ); (void) sprintf( buff, "LgPlt%d", axis + 1 ); astWriteInt( channel, buff, set, 1, ival, "Map plot axis logarithmically?" ); } /* LogTicks(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLogTicks( this, axis, status ); ival = set ? GetLogTicks( this, axis, status ) : astGetLogTicks( this, axis ); (void) sprintf( buff, "LgTck%d", axis + 1 ); astWriteInt( channel, buff, set, 1, ival, "Space ticks logarithmically?" ); } /* LogLabel(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLogLabel( this, axis, status ); ival = set ? GetLogLabel( this, axis, status ) : astGetLogLabel( this, axis ); (void) sprintf( buff, "LgLbl%d", axis + 1 ); astWriteInt( channel, buff, set, 1, ival, "Scientific notation for labels?" ); } /* NumLab(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestNumLab( this, axis, status ); ival = set ? GetNumLab( this, axis, status ) : astGetNumLab( this, axis ); (void) sprintf( buff, "NmLbl%d", axis + 1 ); astWriteInt( channel, buff, set, 1, ival, "Draw numerical labels?" ); } /* MinTick(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestMinTick( this, axis, status ); ival = set ? GetMinTick( this, axis, status ) : astGetMinTick( this, axis ); (void) sprintf( buff, "MnTks%d", axis + 1 ); astWriteInt( channel, buff, set, 0, ival, "No. of sub-divisions " "between major tick marks" ); } /* TextLab(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestTextLab( this, axis, status ); ival = set ? GetTextLab( this, axis, status ) : astGetTextLab( this, axis ); (void) sprintf( buff, "TxLbl%d", axis + 1 ); astWriteInt( channel, buff, set, 0, ival, "Draw textual label?" ); } /* LabelUnits(axis). */ /* ----------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestLabelUnits( this, axis, status ); ival = set ? GetLabelUnits( this, axis, status ) : astGetLabelUnits( this, axis ); (void) sprintf( buff, "LbUnt%d", axis + 1 ); astWriteInt( channel, buff, set, 0, ival, "Add units to axis label?" ); } /* Style(object). */ /* -------------- */ for( id = 0; id < AST__NPID; id++ ){ set = TestStyle( this, id, status ); ival = set ? GetStyle( this, id, status ) : astGetStyle( this, id ); (void) sprintf( buff, "Style%d", id + 1 ); comment = GrfItem( id, " line style", &ax, status ); if( ax < nax ) astWriteInt( channel, buff, set, 0, ival, comment ); comment = (char *) astFree( (void *) comment ); } /* Font(object). */ /* ------------- */ for( id = 0; id < AST__NPID; id++ ){ set = TestFont( this, id, status ); ival = set ? GetFont( this, id, status ) : astGetFont( this, id ); (void) sprintf( buff, "Font%d", id + 1 ); comment = GrfItem( id, " character font", &ax, status ); if( ax < nax ) astWriteInt( channel, buff, set, 0, ival, comment ); comment = (char *) astFree( (void *) comment ); } /* Colour(object). */ /* --------------- */ for( id = 0; id < AST__NPID; id++ ){ set = TestColour( this, id, status ); ival = set ? GetColour( this, id, status ) : astGetColour( this, id ); (void) sprintf( buff, "Col%d", id + 1 ); comment = GrfItem( id, " colour index", &ax, status ); if( ax < nax ) astWriteInt( channel, buff, set, 0, ival, comment ); comment = (char *) astFree( (void *) comment ); } /* Width(object). */ /* -------------- */ for( id = 0; id < AST__NPID; id++ ){ set = TestWidth( this, id, status ); dval = set ? GetWidth( this, id, status ) : astGetWidth( this, id ); if( dval != AST__BAD ) { (void) sprintf( buff, "Width%d", id + 1 ); comment = GrfItem( id, " line width", &ax, status ); if( ax < nax ) astWriteDouble( channel, buff, set, 0, dval, comment ); comment = (char *) astFree( (void *) comment ); } } /* Size(object). */ /* ------------- */ for( id = 0; id < AST__NPID; id++ ){ set = TestSize( this, id, status ); dval = set ? GetSize( this, id, status ) : astGetSize( this, id ); if( dval != AST__BAD ) { (void) sprintf( buff, "Size%d", id + 1 ); comment = GrfItem( id, " character size", &ax, status ); if( ax < nax ) astWriteDouble( channel, buff, set, 0, dval, comment ); comment = (char *) astFree( (void *) comment ); } } /* TitleGap. */ /* --------- */ set = TestTitleGap( this, status ); dval = set ? GetTitleGap( this, status ) : astGetTitleGap( this ); if( dval != AST__BAD ) astWriteDouble( channel, "TtlGap", set, 1, dval, "Gap between title and edge" ); /* MajTickLen(axis). */ /* ----------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestMajTickLen( this, axis, status ); dval = set ? GetMajTickLen( this, axis, status ) : astGetMajTickLen( this, axis ); if( dval != AST__BAD ) { (void) sprintf( buff, "MjTkLn%d", axis + 1 ); astWriteDouble( channel, buff, set, 0, dval, "Major tick length" ); } } /* MinTickLen(axis). */ /* ----------------- */ for( axis = 0; axis < nax; axis++ ){ set = TestMinTickLen( this, axis, status ); dval = set ? GetMinTickLen( this, axis, status ) : astGetMinTickLen( this, axis ); if( dval != AST__BAD ) { (void) sprintf( buff, "MnTkLn%d", axis + 1 ); astWriteDouble( channel, buff, set, 1, dval, "Minor tick length" ); } } /* Labelling. */ /* ---------- */ set = TestLabelling( this, status ); ival = set ? GetLabelling( this, status ) : astGetLabelling( this ); comment = "Labelling scheme"; astWriteString( channel, "Lbling", set, 0, xlbling[ival], comment ); /* Edge(axis). */ /* ----------- */ for( axis = 0; axis < nax; axis++ ){ set = TestEdge( this, axis, status ); ival = set ? GetEdge( this, axis, status ) : astGetEdge( this, axis ); (void) sprintf( buff, "Edge%d", axis + 1 ); comment = "Edge used to label an axis"; astWriteString( channel, buff, set, 0, xedge[ival], comment ); } /* Now do instance variables which are not attributes. */ /* =================================================== */ /* Only write out clipping information if set. */ if( this->clip_lbnd && this->clip_ubnd ){ /* The lower bounds of the clipping volume. */ for( axis = 0; axis < this->clip_axes; axis++ ){ (void) sprintf( buff, "ClpLb%d", axis + 1 ); if( this->clip_lbnd && (this->clip_lbnd)[ axis ] != AST__BAD ){ astWriteDouble( channel, buff, 1, 0, (this->clip_lbnd)[ axis ], "Lower bound of clipping region" ); } } /* The upper bounds of the clipping volume. */ for( axis = 0; axis < this->clip_axes; axis++ ){ (void) sprintf( buff, "ClpUb%d", axis + 1 ); if( this->clip_ubnd && (this->clip_ubnd)[ axis ] != AST__BAD ){ astWriteDouble( channel, buff, 1, 0, (this->clip_ubnd)[ axis ], "Upper bound of clipping region" ); } } /* The number of bounds supplied for the clipping volume. */ astWriteInt( channel, "ClpAxs", 1, 0, this->clip_axes, "No. of bounds for clipping region" ); /* The index of the clipping Frame within the Plot. */ astWriteInt( channel, "ClpFrm", 1, 0, this->clip_frame, "Index of clipping Frame" ); } /* The bounds of the plotting area in graphics coords. */ astWriteDouble( channel, "Xlo", 1, 1, this->xlo, "Lower X bound of plotting area" ); astWriteDouble( channel, "Ylo", 1, 1, this->ylo, "Lower Y bound of plotting area" ); astWriteDouble( channel, "Xhi", 1, 1, this->xhi, "Upper X bound of plotting area" ); astWriteDouble( channel, "Yhi", 1, 1, this->yhi, "Upper Y bound of plotting area" ); /* Axis reversal flags. */ astWriteInt( channel, "Xrev", 1, 0, this->xrev, "X axis reversed?" ); astWriteInt( channel, "Yrev", 1, 0, this->yrev, "Y axis reversed?" ); /* The bounds of the plotting area in the base Frame of the FrameSet supplied when the Plot was constructed. */ astWriteDouble( channel, "Xb1", 1, 1, this->bbox[ 0 ], "Lower X bound of supplied base Frame" ); astWriteDouble( channel, "Yb1", 1, 1, this->bbox[ 1 ], "Lower Y bound of supplied base Frame" ); astWriteDouble( channel, "Xb2", 1, 1, this->bbox[ 2 ], "Upper X bound of supplied base Frame" ); astWriteDouble( channel, "Yb2", 1, 1, this->bbox[ 3 ], "Upper Y bound of supplied base Frame" ); /* User-specified tick values */ for( axis = 0; axis < 3; axis++ ) { if( this->nmajtickval[ axis ] > 0 ) { sprintf( buff, "NMjTk%d", axis + 1 ); astWriteInt( channel, buff, 1, 1, this->nmajtickval[ axis ], "" ); for( itick = 0; itick < this->nmajtickval[ axis ]; itick++ ) { sprintf( buff, "MjTk%d_%d", axis + 1, itick + 1 ); astWriteDouble( channel, buff, 1, 1, this->majtickval[ axis ][ itick ], "" ); } } if( this->nmintickval[ axis ] > 0 ) { sprintf( buff, "NMnTk%d", axis + 1 ); astWriteInt( channel, buff, 1, 1, this->nmintickval[ axis ], "" ); for( itick = 0; itick < this->nmintickval[ axis ]; itick++ ) { sprintf( buff, "MnTk%d_%d", axis + 1, itick + 1 ); astWriteDouble( channel, buff, 1, 1, this->mintickval[ axis ][ itick ], "" ); } } } /* Return. */ return; /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPlot and astCheckPlot functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Plot,FrameSet) astMAKE_CHECK(Plot) AstPlot *astPlot_( void *frame_void, const float *graphbox, const double *basebox, const char *options, int *status, ...) { /* *+ * Name: * astPlot * Purpose: * Create a Plot. * Type: * Protected function. * Synopsis: * #include "plot.h" * AstPlot *astPlot( AstFrame *frame, const float *graphbox, * const double *basebox, const char *options, ..., int *status ) * Class Membership: * Plot constructor. * Description: * This function creates a new Plot and optionally initialises * its attributes. * * The supplied Frame (or the base frame if a FrameSet was supplied) is * assumed to be related to the graphics world coordinate system by a * simple shift and scale along each axis. The mapping between graphics * world coordinates and this Frame is specified by supplying the * coordinates in both systems at the bottom left and top right corners * of a box on the graphics device. By default, no graphics will be * produced outside the supplied box, but this default behaviour can be * changed by setting explicit values for the various clipping attributes. * Parameters: * frame * A pointer to a Frame or FrameSet to be annotated. If a NULL pointer * is supplied, then a default 2-D Frame will be created to which labels, * etc, can be attached by setting the relevant Frame attributes. * graphbox * A pointer to an array of 4 values giving the graphics world * coordinates of the bottom left and top right corners of a box on * the graphics output device. The first pair of values should be the * coordinates of the bottom left corner of the box and the second * pair of values should be the coordinates of the top right corner. * The horizontal axis should be given first in each pair. * basebox * A pointer to an array of 4 values giving the coordinates in the * supplied Frame, or base frame of the supplied FrameSet, at the * bottom left and top right corners of the box specified by parameter * graphbox. These should be supplied in the same order as for * parameter "graphbox". * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Plot. 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 Plot. * Notes: * - The base Frame of the created Plot corresponds to the graphics world * coordinate system, and should not, in general, be changed. * - The current Frame of the created Plot corresponds to the Frame * given by parameter "frame". If a FrameSet was supplied then its * current Frame becomes the current Frame of the created Plot. * - If the supplied Frame, or base Frame if a FrameSet was supplied, * has more than 2 axes, then the sub-Frame defined by the first 2 axes * is used. * - 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 Plot constructor which * is available via the protected interface to the Plot class. * A public interface is provided by the astPlotId_ 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 */ AstPlot *new; /* Pointer to new Plot */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ new = NULL; /* Obtain and validate a pointer to any supplied Frame structure. */ if( frame_void ){ frame = astCheckFrame( frame_void ); } else { frame = NULL; } /* Check the pointer can be used. */ if ( astOK ) { /* Initialise the Plot, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPlot( NULL, sizeof( AstPlot ), !class_init, &class_vtab, "Plot", frame, graphbox, basebox ); /* 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 Plot'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 Plot. */ return new; } AstPlot *astInitPlot_( void *mem, size_t size, int init, AstPlotVtab *vtab, const char *name, AstFrame *frame, const float *graphbox, const double *basebox, int *status ) { /* *+ * Name: * astInitPlot * Purpose: * Initialise a Plot. * Type: * Protected function. * Synopsis: * #include "plot.h" * AstPlot *astInitPlot( void *mem, size_t size, int init, * AstPlotVtab *vtab, const char *name, * AstFrame *frame, const float *graphbox, * const double *basebox ) * Class Membership: * Plot initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Plot object. It allocates memory (if necessary) to accommodate * the Plot plus any additional data associated with the derived class. * It then initialises a Plot 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 Plot at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Plot is to be created. This * must be of sufficient size to accommodate the Plot data * (sizeof(Plot)) 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 Plot (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 Plot * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Plot'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 Plot. If NULL, the vtab associated with this class * (Plot) will be used. * 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 * A pointer to the Frame or Frameset to be annotated. * graphbox * A pointer to an array of 4 values giving the graphics coordinates * of the bottom left and top right corners of a box on the graphics * output device. The first pair of values should be the graphics * coordinates of the bottom left corner of the box and the second * pair of values are the graphics coordinates of the top right corner. * The horizontal axis should be given first in each pair. * basebox * A pointer to an array of 4 values giving the coordinates in the * supplied Frame or base Frame of the supplied FrameSet at the bottom * left and top right corners of the box specified by parameter graphbox. * These should be supplied in the same order as for parameter "graphbox". * Returned Value: * A pointer to the new Plot. * Notes: * - If the supplied Frame, or base Frame if a FrameSet was supplied, * has more than 2 axes, then the sub-Frame defined by the first 2 axes * is used. * - The current Frame of the supplied FrameSet need not be 2-dimensional. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *baseframe; /* Pointer to base frame */ AstFrame *graphicsframe; /* Pointer to graphics frame */ AstFrameSet *fset0; /* The n-D FrameSet to be annotated */ AstFrameSet *fset; /* The 2-D FrameSet to be annotated */ AstPlot *new; /* Pointer to new Plot */ AstWinMap *map; /* Mapping for converting bbox -> gbox */ char *mess; /* Pointer to a descriptive message */ double gbox[ 4 ]; /* Double precision version of "graphbox" */ int axis; /* Axis index, 0 or 1 */ int bi; /* Index of base frame */ int ci; /* Index of current frame */ int i; /* Loop count */ int id; /* Plot object id */ int naxes; /* No. of axes in frame */ /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(frame); /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ fset = NULL; mess = NULL; /* If no vtab was supplied, use the vtab for this class (Plot). */ if( !vtab ) { vtab = &class_vtab; if ( !class_init ) { astInitPlotVtab( vtab, "Plot" ); class_init = 1; } /* If necessary, initialise the virtual function table. */ } else if ( init ) { astInitPlotVtab( vtab, name ); } /* Initialise. */ new = NULL; baseframe = NULL; /* First of all we need to ensure that we have a FrameSet and a base Frame on which to base the new Plot. If a NULL Frame pointer was supplied, create a default 2-D Frame, and then create a FrameSet containing just this default Frame. Also store a pointer to a message which can be used to describe the object within error messages. */ if( !frame ){ baseframe = astFrame( 2, "", status ); fset = astFrameSet( baseframe, "", status ); mess = "default 2-d Frame"; /* If an object was supplied, report an error if it is not a Frame or an object derived from a Frame (such as a FrameSet). */ } else if( !astIsAFrame( frame ) ){ if( astOK ){ astError( AST__BDOBJ, "astInitPlot(%s): Supplied Object (class '%s') " "is not a Frame.", status, name, astGetClass( frame ) ); } /* If the supplied object is a Plot or an object derived from a Plot (a Plot is a sort of Frame and so will pass the above test), extract a FrameSet from the Plot, and clear the Domain attribute for any existing Frames which have Domain GRAPHICS. */ } else if( astIsAPlot( frame ) ){ fset0 = astFrameSet( frame, "", status ); fset = astCopy( fset0 ); fset0 = astAnnul( fset0 ); for( i = 0; i < astGetNframe( fset ); i++ ) { graphicsframe = astGetFrame( fset, i ); if( !strcmp( astGetDomain( graphicsframe ), "GRAPHICS" ) ) { astClearDomain( graphicsframe ); } graphicsframe = astAnnul( graphicsframe ); } baseframe = astGetFrame( fset, astGetBase( fset ) ); mess = "base Frame of the supplied Plot"; /* If the object is not a FrameSet, create a FrameSet holding the supplied Frame. If the Frame is not 2D, an extra 2D Frame is included in the FrameSet derived from axes 1 and 2 of the supplied Frame. This new Frame becomes the base Frame. */ } else if( !astIsAFrameSet( frame ) ){ fset0 = astFrameSet( frame, "", status ); mess = "supplied Frame"; fset = Fset2D( fset0, AST__BASE, status ); fset0 = astAnnul( fset0 ); baseframe = astGetFrame( fset, astGetBase( fset ) ); /* If a FrameSet was supplied, ensure it has a 2D base Frame. If the supplied FrameSet is not 2D, then a new base Frame is inserted into it which is derived from axes 1 and 2 of the original base Frame. */ } else { fset = Fset2D( (AstFrameSet *) frame, AST__BASE, status ); baseframe = astGetFrame( fset, astGetBase( fset ) ); mess = "base Frame of the supplied FrameSet"; } /* Check that there are 2 axes in the base frame of the FrameSet. */ naxes = astGetNaxes( baseframe ); if ( naxes != 2 && astOK ) { astError( AST__NAXIN, "astInitPlot(%s): Number of axes (%d) in the %s " "is invalid - this number should be 2.", status, name, naxes, mess ); } /* Check that neither dimension of the graphbox is zero. */ if( ( graphbox[ 2 ] == graphbox[ 0 ] || graphbox[ 3 ] == graphbox[ 1 ] ) && astOK ){ astError( AST__BADBX, "astInitPlot(%s): The plotting area has zero size " "in the graphics world coordinate system.", status, name ); } /* Check that neither dimension of the graphbox is bad. */ if( astISBAD(graphbox[0]) || astISBAD(graphbox[1]) || astISBAD(graphbox[2]) || astISBAD(graphbox[3]) ) { astError( AST__BADBX, "astInitPlot(%s): The plotting area has undefined limits " "in the graphics world coordinate system.", status, name ); } /* Check that neither dimension of the basebox is zero. */ if( astISBAD(basebox[2]) || astISBAD(basebox[0]) ) { astError( AST__BADBX, "astInitPlot(%s): The limits of the horizontal " "axis of the %s are undefined or bad.", status, name, name ); } else if( astISBAD(basebox[3]) || astISBAD(basebox[1]) ) { astError( AST__BADBX, "astInitPlot(%s): The limits of the vertical " "axis of the %s are undefined or bad.", status, name, name ); } /* Create a Frame which describes the graphics world coordinate system. */ graphicsframe = astFrame( 2, "Domain=GRAPHICS,Title=Graphical Coordinates", status ); /* Initialise a FrameSet structure (the parent class) as the first component within the Plot structure, allocating memory if necessary. The new FrameSet is initialised to hold the graphics Frame created above. */ new = (AstPlot *) astInitFrameSet( mem, size, 0, (AstFrameSetVtab *) vtab, name, graphicsframe ); if ( astOK ) { /* Initialise the Plot data. */ /* ----------------------------- */ /* Get a double precision version of "graphbox". */ gbox[ 0 ] = (double) graphbox[ 0 ]; gbox[ 1 ] = (double) graphbox[ 1 ]; gbox[ 2 ] = (double) graphbox[ 2 ]; gbox[ 3 ] = (double) graphbox[ 3 ]; /* Store the bounds in graphics coordinates of the clipping box, ensuring that the low bound is lower than the high bound. Set flags to indicate if the supplied bounds has to be reversed to do this (some graphics system have the Y axis increasing from the top of the screen to the bottom). */ if( graphbox[ 0 ] <= graphbox[ 2 ] ){ new->xlo = gbox[ 0 ]; new->xhi = gbox[ 2 ]; new->xrev = 0; } else { new->xhi = gbox[ 0 ]; new->xlo = gbox[ 2 ]; new->xrev = 1; astSetDirection( graphicsframe, 0, 0 ); } if( graphbox[ 1 ] <= graphbox[ 3 ] ){ new->ylo = gbox[ 1 ]; new->yhi = gbox[ 3 ]; new->yrev = 0; } else { new->yhi = gbox[ 1 ]; new->ylo = gbox[ 3 ]; new->yrev = 1; astSetDirection( graphicsframe, 1, 0 ); } /* Store the bounds of the Plot within the base Frame of the supplied FrameSet. */ new->bbox[ 0 ] = basebox[ 0 ]; new->bbox[ 1 ] = basebox[ 1 ]; new->bbox[ 2 ] = basebox[ 2 ]; new->bbox[ 3 ] = basebox[ 3 ]; /* We initially assume that the base Frame of the supplied FrameSet is mapped lineary onto the graphics frame. This may be changed later by assigning values to the LogPlot attributes. Create a WinMap which maps the base box (within the base Frame of the supplied FrameSet) onto the graphics box. */ map = astWinMap( 2, gbox, gbox + 2, basebox, basebox + 2, "", status ); /* Get the index of the current (physical) and base (pixel) Frames in the supplied FrameSet. */ bi = astGetBase( fset ); ci = astGetCurrent( fset ); /* Temporarily set the current Frame to be the pixel frame. */ astSetCurrent( fset, bi ); /* Add the supplied FrameSet into the Plot (i.e. FrameSet) created earlier. This leaves the graphics frame with index 1 in the returned Plot. We use the linear mapping initially. */ astAddFrame( (AstFrameSet *) new, 1, map, fset ); map = astAnnul( map ); /* Set the current Frame in the Plot to be the physical coordinate Frame (with index incremented by one because the graphics Frame has been added). */ astSetCurrent( (AstFrameSet *) new, ci + 1 ); /* Re-establish the original current Frame in the supplied FrameSet. */ astSetCurrent( fset, ci ); /* Store a value of -1.0 for Tol to indicate that no value has yet been set. This will cause a default value of 0.001 to be used. */ new->tol = -1.0; /* Set up default clipping information which gives no clipping. */ new->clip_frame = AST__NOFRAME; new->clip_lbnd = NULL; new->clip_ubnd = NULL; new->clip_axes = 0; /* Is a grid covering the plotting area required? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 0 (no) to be used. */ new->grid = -1; /* Are tick marks to be placed on both edges in a pair of opposite edges? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 1 (yes) to be used. */ new->tickall = -1; /* Graphics context identifier */ new->grfcontext = NULL; new->grfcontextID = NULL; /* Shoudl ast Grid draw a boundary round the regions of valid coordinates? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 1 (yes) to be used. */ new->border = -1; /* Should graphics be drawn invisible? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 0 (no) to be used. */ new->invisible = -1; /* By default clip markers but not curves at the boundary of the plotting area. This was the only behaviour available prior to the introduction of the Clip attribute, and is chosen as the default to maintain backwards compatibility. */ new->clip = -1; /* Is clipping to be done using a logical OR operation between the axes? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 0 (no, i.e. a logical AND) to be used. */ new->clipop = -1; /* Is the graphics interface registered using astGrfSet to be used? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 0 (no, i.e. use the graphics interface selected at link-time) to be used. */ new->grf = -1; /* Wrapper functions to call the drawing routines. These are the default wrappers which call GRF routines written in C. Alternative wrappers are defined in fplot.c for use with GRF routines written in F77. */ new->GAttr = CGAttrWrapper; new->GBBuf = CGBBufWrapper; new->GEBuf = CGEBufWrapper; new->GFlush = CGFlushWrapper; new->GLine = CGLineWrapper; new->GMark = CGMarkWrapper; new->GText = CGTextWrapper; new->GCap = CGCapWrapper; new->GTxExt = CGTxExtWrapper; new->GScales = CGScalesWrapper; new->GQch = CGQchWrapper; for( i = 0; i < AST__NGRFFUN; i++ ) new->grffun[i] = NULL; new->grfstack = NULL; new->grfnstack = 0; /* Is a title to be added to an annotated grid? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 1 (yes) to be used. */ new->drawtitle = -1; /* Are escape sequences within text strings to be interpreted? If not, they are printed literally. Store a value of -1 when not set. This will cause a default value of 1 (yes) to be used. */ new->escape = -1; /* A boolean attribute indicating where numerical labels are to be placed; zero implies round the edges of the plotting area; non-zero implies within the plotting area. The unset value of -9999 yields a default of zero. */ new->labelling = -9999; /* Graphics attributes. Default behaviour is to use the current values. */ for( id = 0; id < AST__NPID; id++ ){ new->style[ id ] = -1; new->font[ id ] = -1; new->colour[ id ] = -1; new->width[ id ] = AST__BAD; new->size[ id ] = AST__BAD; } /* The space between the top edge and the grid title as a fraction of the minimum dimension of the plotting area. Store AST__BAD to indicate that no value has been set. This will cause a default of 0.05 to be used. */ new->titlegap = AST__BAD; /* Initialise the protected Ink attribute so that visible ink is used. */ new->ink = -1; /* A stack of AstGat pointers used to store the graphical attributes for text within strings which include graphical escape sequences. */ new->gat = NULL; new->ngat = 0; /* Now set the attribute values for each axis. The arrays stored in the Plot struture allow for 3 graphics axes (e.g. as used by a Plot3D) so we initialise 3 axes here even though the Plot class only uses 2. */ for( axis = 0; axis < 3; axis++ ) { /* Are curves to be drawn through the tick marks even if no grid is produced? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 1 (yes) to be used. */ new->drawaxes[ axis ] = -1; /* Are adjacent numerical axis labels to be abbreviated by removing matching leading fields? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 1 (yes) to be used. */ new->abbrev[ axis ] = -1; /* The length of the major tick marks as a fraction of the minimum dimension of the plotting area. Store AST__BAD to indicate that no value has been set. This will cause a default of 0.015 to be used. */ new->majticklen[ axis ] = AST__BAD; /* The length of the minor tick marks as a fraction of the minimum dimension of the plotting area. Store AST__BAD to indicate that no value has been set. This will cause a default of 0.007 to be used. */ new->minticklen[ axis ] = AST__BAD; /* Are numeric labels to be drawn upright? Store a value of -1 to indicate that no value has yet been set. This will cause a default value of 0 (no) to be used. */ new->labelup[ axis ] = -1; /* The space between an axis and its numeric labels as a fraction of the minimum dimension of the plotting area. Store AST__BAD to indicate that no value has been set. This will cause a default of 0.01 to be used. */ new->numlabgap[ axis ] = AST__BAD; new->textlabgap[ axis ] = AST__BAD; /* The edges on which to put labels for axes 1 and 2. Store values of -1 to indicate that no values have been set. This will cause default values to be used. */ new->edge[ axis ] = -1; /* The placement of labels within the plotting area will be done automatically by default. */ new->labelat[ axis ] = AST__BAD; /* The central tick is placed automatically by default. */ new->centre[ axis ] = AST__BAD; /* The gap between tick marks and the number of minor tick marks will be found automatically by default. */ new->gap[ axis ] = AST__BAD; new->loggap[ axis ] = AST__BAD; new->mintick[ axis ] = -1; /* Both axes will be labelled by default. */ new->numlab[ axis ] = -1; new->textlab[ axis ] = -1; new->labelunits[ axis ] = -1; /* Log/lin attributes. Default value is to use linear axes. */ new->logplot[ axis ] = -1; new->logticks[ axis ] = -1; new->loglabel[ axis ] = -1; /* Initialise the components used to store the values actually used for attributes which have dynamic defaults. */ new->ulglb[ axis ] = new->loglabel[ axis ]; new->ulgtk[ axis ] = new->logticks[ axis ]; new->uloggap[ axis ] = new->loggap[ axis ]; new->ugap[ axis ] = new->gap[ axis ]; new->ucentre[ axis ] = new->centre[ axis ]; new->uedge[ axis ] = new->edge[ axis ]; new->ulblat[ axis ] = new->labelat[ axis ]; new->ulbunit[ axis ] = new->labelunits[ axis ]; new->umintk[ axis ] = new->mintick[ axis ]; new->utxtlb[ axis ] = new->textlab[ axis ]; new->umjtkln[ axis ] = new->majticklen[ axis ]; /* Initialise the arrays used to hold information describing the tick marks that have been drawn for the axis. */ new->majtickgx[ axis ] = NULL; new->majtickgy[ axis ] = NULL; new->majtickcount[ axis ] = 0; new->mintickgx[ axis ] = NULL; new->mintickgy[ axis ] = NULL; new->mintickcount[ axis ] = 0; new->nmajtickval[ axis ] = 0; new->majtickval[ axis ] = NULL; new->nmintickval[ axis ] = 0; new->mintickval[ axis ] = NULL; } new->ugrid = new->grid; new->ulbling = new->labelling; new->uborder = new->border; } /* Annul the frame. */ graphicsframe = astAnnul( graphicsframe ); /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); /* Annul the pointer to the base Frame and FrameSet. */ baseframe = astAnnul( baseframe ); fset = astAnnul( fset ); /* Return a pointer to the new object. */ return new; } AstPlot *astLoadPlot_( void *mem, size_t size, AstPlotVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPlot * Purpose: * Load a Plot. * Type: * Protected function. * Synopsis: * #include "Plot.h" * AstPlot *astLoadPlot( void *mem, size_t size, * AstPlotVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * Plot loader. * Description: * This function is provided to load a new Plot 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 * Plot structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Plot at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Plot is to be * loaded. This must be of sufficient size to accommodate the * Plot data (sizeof(Plot)) 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 Plot (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 Plot 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(AstPlot) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Plot. If this is NULL, a pointer * to the (static) virtual function table for the Plot 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 "Plot" is used instead. * Returned Value: * A pointer to the new Plot. * 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. *- */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPlot *new; /* Pointer to the new Plot */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ char *text; /* Textual version of integer value */ int axis; /* Zero based axis index */ int id; /* Zero based graphical object id */ int i; /* Loop count */ int itick; /* Tick mark index */ int nax; /* Number of base Frame axes */ int ntick; /* Total number of ticks */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Plot. In this case the Plot belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPlot ); vtab = &class_vtab; name = "Plot"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPlotVtab( 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 Plot. */ new = astLoadFrameSet( mem, size, (AstFrameSetVtab *) vtab, name, channel ); if ( astOK ) { /* Get the number of graphics (base) frame axes - 2 for a Plot, 3 for a Plot3D. */ nax = astGetNin( new ); /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "Plot" ); /* 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. */ /* Tol. */ /* ---- */ new->tol = astReadDouble( channel, "tol", -1.0 ); if ( TestTol( new, status ) ) SetTol( new, new->tol, status ); /* Grid. */ /* ----- */ new->grid = astReadInt( channel, "grid", -1 ); if ( TestGrid( new, status ) ) SetGrid( new, new->grid, status ); /* TickAll. */ /* -------- */ new->tickall = astReadInt( channel, "tckall", -1 ); if ( TestTickAll( new, status ) ) SetTickAll( new, new->tickall, status ); /* ForceExterior. */ /* -------- */ new->forceexterior = astReadInt( channel, "frcext", -1 ); if ( TestForceExterior( new, status ) ) SetForceExterior( new, new->forceexterior, status ); /* Invisible. */ /* ---------- */ new->invisible = astReadInt( channel, "invsbl", -1 ); if ( TestInvisible( new, status ) ) SetInvisible( new, new->invisible, status ); /* Border. */ /* -------- */ new->border = astReadInt( channel, "border", -1 ); if ( TestBorder( new, status ) ) SetBorder( new, new->border, status ); /* ClipOp. */ /* ------- */ new->clipop = astReadInt( channel, "clpop", -1 ); if ( TestClipOp( new, status ) ) SetClipOp( new, new->clipop, status ); /* Clip. */ /* ----- */ new->clip = astReadInt( channel, "clip", -1 ); if ( TestClip( new, status ) ) SetClip( new, new->clip, status ); /* DrawTitle. */ /* --------- */ new->drawtitle = astReadInt( channel, "drwttl", -1 ); if ( TestDrawTitle( new, status ) ) SetDrawTitle( new, new->drawtitle, status ); /* LabelUp(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lblup%d", axis + 1 ); new->labelup[ axis ] = astReadInt( channel, buff, -1 ); if ( TestLabelUp( new, axis, status ) ) SetLabelUp( new, axis, new->labelup[ axis ], status ); } /* LogPlot(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lgplt%d", axis + 1 ); new->logplot[ axis ] = astReadInt( channel, buff, -1 ); if ( TestLogPlot( new, axis, status ) ) SetLogPlot( new, axis, new->logplot[ axis ], status ); } /* LogTicks(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lgtck%d", axis + 1 ); new->logticks[ axis ] = astReadInt( channel, buff, -1 ); if ( TestLogTicks( new, axis, status ) ) SetLogTicks( new, axis, new->logticks[ axis ], status ); } /* LogLabel(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lglbl%d", axis + 1 ); new->loglabel[ axis ] = astReadInt( channel, buff, -1 ); if ( TestLogLabel( new, axis, status ) ) SetLogLabel( new, axis, new->loglabel[ axis ], status ); } /* DrawAxes. */ /* --------- */ new->drawaxes[ 0 ] = astReadInt( channel, "drwaxs", -1 ); if( new->drawaxes[ 0 ] != -1 ) { new->drawaxes[ 1 ] = new->drawaxes[ 0 ]; if ( TestDrawAxes( new, 0, status ) ) SetDrawAxes( new, 0, new->drawaxes[ 0 ], status ); if ( TestDrawAxes( new, 1, status ) ) SetDrawAxes( new, 1, new->drawaxes[ 1 ], status ); } else { for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "drwaxs%d", axis + 1 ); new->drawaxes[ axis ] = astReadInt( channel, buff, -1 ); if ( TestDrawAxes( new, axis, status ) ) SetDrawAxes( new, axis, new->drawaxes[ axis ], status ); } } /* Abbrev. */ /* ------- */ new->abbrev[ 0 ] = astReadInt( channel, "abbrv", -1 ); if( new->abbrev[ 0 ] != -1 ) { new->abbrev[ 1 ] = new->abbrev[ 0 ]; if ( TestAbbrev( new, 0, status ) ) SetAbbrev( new, 0, new->abbrev[ 0 ], status ); if ( TestAbbrev( new, 1, status ) ) SetAbbrev( new, 1, new->abbrev[ 1 ], status ); } else { for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "abbrv%d", axis + 1 ); new->abbrev[ axis ] = astReadInt( channel, buff, -1 ); if ( TestAbbrev( new, axis, status ) ) SetAbbrev( new, axis, new->abbrev[ axis ], status ); } } /* Escape. */ /* ------- */ new->escape = astReadInt( channel, "escape", -1 ); if ( TestEscape( new, status ) ) SetEscape( new, new->escape, status ); /* LabelAt(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lblat%d", axis + 1 ); new->labelat[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestLabelAt( new, axis, status ) ) SetLabelAt( new, axis, new->labelat[ axis ], status ); } /* Centre(axis). */ /* ------------ */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "cen%d", axis + 1 ); new->centre[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestCentre( new, axis, status ) ) SetCentre( new, axis, new->centre[ axis ], status ); } /* Gap(axis). */ /* ---------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "gap%d", axis + 1 ); new->gap[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestGap( new, axis, status ) ) SetGap( new, axis, new->gap[ axis ], status ); } /* LogGap(axis). */ /* ------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lggap%d", axis + 1 ); new->loggap[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestLogGap( new, axis, status ) ) SetLogGap( new, axis, new->loggap[ axis ], status ); } /* NumLabGap(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "nmgap%d", axis + 1 ); new->numlabgap[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestNumLabGap( new, axis, status ) ) SetNumLabGap( new, axis, new->numlabgap[ axis ], status ); } /* TextLabGap(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "txgap%d", axis + 1 ); new->textlabgap[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestTextLabGap( new, axis, status ) ) SetTextLabGap( new, axis, new->textlabgap[ axis ], status ); } /* NumLab(axis). */ /* ---------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "nmlbl%d", axis + 1 ); new->numlab[ axis ] = astReadInt( channel, buff, -1 ); if ( TestNumLab( new, axis, status ) ) SetNumLab( new, axis, new->numlab[ axis ], status ); } /* MinTick(axis). */ /* --------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "mntks%d", axis + 1 ); new->mintick[ axis ] = astReadInt( channel, buff, -1 ); if ( TestMinTick( new, axis, status ) ) SetMinTick( new, axis, new->mintick[ axis ], status ); } /* TextLab(axis). */ /* -------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "txlbl%d", axis + 1 ); new->textlab[ axis ] = astReadInt( channel, buff, -1 ); if ( TestTextLab( new, axis, status ) ) SetTextLab( new, axis, new->textlab[ axis ], status ); } /* LabelUnits(axis). */ /* --------------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "lbunt%d", axis + 1 ); new->labelunits[ axis ] = astReadInt( channel, buff, -1 ); if ( TestLabelUnits( new, axis, status ) ) SetLabelUnits( new, axis, new->labelunits[ axis ], status ); } /* Style(object). */ /* ------------ */ for( id = 0; id < AST__NPID; id++ ){ (void) sprintf( buff, "style%d", id + 1 ); new->style[ id ] = astReadInt( channel, buff, -1 ); if ( TestStyle( new, id, status ) ) SetStyle( new, id, new->style[ id ], status ); } /* Font(object). */ /* ----------- */ for( id = 0; id < AST__NPID; id++ ){ (void) sprintf( buff, "font%d", id + 1 ); new->font[ id ] = astReadInt( channel, buff, -1 ); if ( TestFont( new, id, status ) ) SetFont( new, id, new->font[ id ], status ); } /* Colour(object). */ /* --------------- */ for( id = 0; id < AST__NPID; id++ ){ (void) sprintf( buff, "col%d", id + 1 ); new->colour[ id ] = astReadInt( channel, buff, -1 ); if ( TestColour( new, id, status ) ) SetColour( new, id, new->colour[ id ], status ); } /* Width(object). */ /* ------------ */ for( id = 0; id < AST__NPID; id++ ){ (void) sprintf( buff, "width%d", id + 1 ); new->width[ id ] = astReadDouble( channel, buff, AST__BAD ); if ( TestWidth( new, id, status ) ) SetWidth( new, id, new->width[ id ], status ); } /* Size(object). */ /* ----------- */ for( id = 0; id < AST__NPID; id++ ){ (void) sprintf( buff, "size%d", id + 1 ); new->size[ id ] = astReadDouble( channel, buff, AST__BAD ); if ( TestSize( new, id, status ) ) SetSize( new, id, new->size[ id ], status ); } /* TitleGap. */ /* --------- */ new->titlegap = astReadDouble( channel, "ttlgap", AST__BAD ); if ( TestTitleGap( new, status ) ) SetTitleGap( new, new->titlegap, status ); /* MajTickLen. */ /* ----------- */ /* Retained in order to read old Plots - new Plots use MajTickLen(axis). */ new->majticklen[ 0 ] = astReadDouble( channel, "mjtkln", AST__BAD ); if( new->majticklen[ 0 ] != AST__BAD ) { new->majticklen[ 1 ] = new->majticklen[ 0 ]; if ( TestMajTickLen( new, 0, status ) ) SetMajTickLen( new, 0, new->majticklen[ 0 ], status ); if ( TestMajTickLen( new, 1, status ) ) SetMajTickLen( new, 1, new->majticklen[ 1 ], status ); /* MajTickLen(axis). */ /* ----------------- */ } else { for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "mjtkln%d", axis + 1 ); new->majticklen[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestMajTickLen( new, axis, status ) ) SetMajTickLen( new, axis, new->majticklen[ axis ], status ); } } /* MinTickLen. */ /* ----------- */ /* Retained in order to read old Plots - new Plots use MinTickLen(axis). */ new->minticklen[ 0 ] = astReadDouble( channel, "mntkln", AST__BAD ); if( new->minticklen[ 0 ] != AST__BAD ) { new->minticklen[ 1 ] = new->minticklen[ 0 ]; if ( TestMinTickLen( new, 0, status ) ) SetMinTickLen( new, 0, new->minticklen[ 0 ], status ); if ( TestMinTickLen( new, 1, status ) ) SetMinTickLen( new, 1, new->minticklen[ 1 ], status ); /* MinTickLen(axis). */ /* ----------------- */ } else { for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "mntkln%d", axis + 1 ); new->minticklen[ axis ] = astReadDouble( channel, buff, AST__BAD ); if ( TestMinTickLen( new, axis, status ) ) SetMinTickLen( new, axis, new->minticklen[ axis ], status ); } } /* Labelling. */ /* ---------- */ text = astReadString( channel, "lbling", " " ); if( astOK && strcmp( text, " " ) ) { new->labelling = FindString( 2, xlbling, text, "the Plot component 'Lbling'", "astRead", astGetClass( channel ), status ); } else { new->labelling = -9999; } if ( TestLabelling( new, status ) ) SetLabelling( new, new->labelling, status ); text = astFree( text ); /* Edge(axis). */ /* ----------- */ for( axis = 0; axis < nax; axis++ ){ (void) sprintf( buff, "edge%d", axis + 1 ); text = astReadString( channel, buff, " " ); if( astOK && strcmp( text, " " ) ) { new->edge[ axis ] = FindString( 4, xedge, text, "the Plot component 'Edge'", "astRead", astGetClass( channel ), status ); } else { new->edge[ axis ] = -1; } if ( TestEdge( new, axis, status ) ) SetEdge( new, axis, new->edge[ axis ], status ); text = astFree( text ); } /* Now do instance variables which are not attributes. */ /* =================================================== */ /* We have no graphics context. */ new->grfcontext = NULL; new->grfcontextID = NULL; /* Initialise the protected Ink attribute so that visible ink is used. */ new->ink = -1; /* The number of bounds supplied for the clipping volume. */ new->clip_axes = astReadInt( channel, "clpaxs", 0 ); if ( new->clip_axes < 0 ) new->clip_axes = 0; /* The index of the clipping Frame within the Plot. */ new->clip_frame = astReadInt( channel, "clpfrm", AST__NOFRAME ); /* If necessary, allocate memory to hold the bounds of the clipping volume. */ if( new->clip_axes > 0 ){ new->clip_lbnd = astMalloc( sizeof( double ) * (size_t) new->clip_axes ); new->clip_ubnd = astMalloc( sizeof( double ) * (size_t) new->clip_axes ); /* If an error occurs, ensure that all allocated memory is freed. */ if ( !astOK ) { new->clip_lbnd = (double *) astFree( (void *) new->clip_lbnd ); new->clip_ubnd = (double *) astFree( (void *) new->clip_ubnd ); /* Otherwise, store the bounds. Use extreme defaults if no values are available. */ } else { for( axis = 0; axis < new->clip_axes; axis++ ){ (void) sprintf( buff, "clplb%d", axis + 1 ); new->clip_lbnd[ axis ] = astReadDouble( channel, buff, -DBL_MAX ); (void) sprintf( buff, "clpub%d", axis + 1 ); new->clip_ubnd[ axis ] = astReadDouble( channel, buff, DBL_MAX ); } } /* If there are no clipping axes, store NULL pointers for the bounds arrays. */ } else { new->clip_lbnd = NULL; new->clip_ubnd = NULL; } /* The bounds of the plotting area in graphics coords. */ new->xlo = astReadDouble( channel, "xlo", 0.0 ); new->xhi = astReadDouble( channel, "xhi", 1.0 ); new->ylo = astReadDouble( channel, "ylo", 0.0 ); new->yhi = astReadDouble( channel, "yhi", 1.0 ); /* Axis reversal flags. */ new->xrev = astReadInt( channel, "xrev", 0 ); new->yrev = astReadInt( channel, "yrev", 0 ); /* The bounds of the plotting area in the base Frame of the FrameSet supplied when the Plot was constructed. */ new->bbox[ 0 ] = astReadDouble( channel, "xb1", AST__BAD ); new->bbox[ 1 ] = astReadDouble( channel, "yb1", AST__BAD ); new->bbox[ 2 ] = astReadDouble( channel, "xb2", AST__BAD ); new->bbox[ 3 ] = astReadDouble( channel, "yb2", AST__BAD ); /* Grf. */ new->grf = -1; new->GAttr = CGAttrWrapper; new->GBBuf = CGBBufWrapper; new->GEBuf = CGEBufWrapper; new->GFlush = CGFlushWrapper; new->GLine = CGLineWrapper; new->GMark = CGMarkWrapper; new->GText = CGTextWrapper; new->GCap = CGCapWrapper; new->GTxExt = CGTxExtWrapper; new->GScales = CGScalesWrapper; new->GQch = CGQchWrapper; for( i = 0; i < AST__NGRFFUN; i++ ) new->grffun[i] = NULL; new->grfstack = NULL; new->grfnstack = 0; /* A stack of AstGat pointers used to store the graphical attributes for text within strings which include graphical escape sequences. */ new->gat = NULL; new->ngat = 0; /* Arrays holding user-specified major and minot tick mark values. */ for( axis = 0; axis < 3; axis++ ) { sprintf( buff, "nmjtk%d", axis + 1 ); ntick = astReadInt( channel, buff, 0 ); new->nmajtickval[ axis ] = ntick; new->majtickval[ axis ] = astMalloc( ntick*sizeof( double ) ); for( itick = 0; itick < ntick; itick++ ) { sprintf( buff, "mjtk%d_%d", axis + 1, itick + 1 ); new->majtickval[ axis ][ itick ] = astReadDouble( channel, buff, AST__BAD ); } sprintf( buff, "nmntk%d", axis + 1 ); ntick = astReadInt( channel, buff, 0 ); new->nmintickval[ axis ] = ntick; new->mintickval[ axis ] = astMalloc( ntick*sizeof( double ) ); for( itick = 0; itick < ntick; itick++ ) { sprintf( buff, "mntk%d_%d", axis + 1, itick + 1 ); new->mintickval[ axis ][ itick ] = astReadDouble( channel, buff, AST__BAD ); } } /* Initialise the arrays used to hold information describing the tick marks that have already been drawn for each axis. */ for( axis = 0; axis < 3; axis++ ) { new->majtickgx[ axis ] = NULL; new->majtickgy[ axis ] = NULL; new->majtickcount[ axis ] = 0; new->mintickgx[ axis ] = NULL; new->mintickgy[ axis ] = NULL; new->mintickcount[ axis ] = 0; } /* If an error occurred, clean up by deleting the new Plot. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Plot pointer. */ return new; } /* 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 astBBuf_( AstPlot *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,BBuf))(this, status ); } int astBorder_( AstPlot *this, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,Plot,Border))(this, status ); } void astBoundingBox_( AstPlot *this, float lbnd[2], float ubnd[2], int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,BoundingBox))(this,lbnd,ubnd, status ); } void astClip_( AstPlot *this, int iframe, const double lbnd[], const double ubnd[], int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,Clip))(this,iframe,lbnd,ubnd, status ); } void astGrid_( AstPlot *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,Grid))(this, status ); } int astCvBrk_( AstPlot *this, int ibrk, double *brk, double *vbrk, double *len, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,Plot,CvBrk))(this,ibrk,brk,vbrk,len, status ); } void astEBuf_( AstPlot *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,EBuf))(this, status ); } void astMirror_( AstPlot *this, int axis, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,Mirror))(this,axis, status ); } AstPointSet *astGetDrawnTicks_( AstPlot *this, int axis, int major, int *status ){ if( !astOK ) return NULL; return (**astMEMBER(this,Plot,GetDrawnTicks))(this,axis,major, status ); } void astSetTickValues_( AstPlot *this, int axis, int nmajor, double *major, int nminor, double *minor, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,SetTickValues))(this,axis,nmajor,major,nminor,minor, status ); } void astCopyPlotDefaults_( AstPlot *this, int axis, AstPlot *dplot, int daxis, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,CopyPlotDefaults))(this,axis,dplot,daxis, status ); } int astGetLabelUnits_( AstPlot *this, int axis, int *status ){ if( !astOK ) return 0; return (**astMEMBER(this,Plot,GetLabelUnits))(this,axis, status ); } void astMark_( AstPlot *this, int nmark, int ncoord, int indim, const double *in, int type, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Plot,Mark))( this, nmark, ncoord, indim, in, type, status ); } void astText_( AstPlot *this, const char *text, const double pos[], const float up[], const char *just, int *status ){ if ( !astOK ) return; (**astMEMBER(this,Plot,Text))( this, text, pos, up, just, status ); } void astGridLine_( AstPlot *this, int axis, const double start[], double length, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GridLine))(this,axis,start,length, status ); } void astCurve_( AstPlot *this, const double start[], const double finish[], int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,Curve))(this,start,finish, status ); } void astGenCurve_( AstPlot *this, AstMapping *map, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GenCurve))(this,map, status ); } void astPolyCurve_( AstPlot *this, int npoint, int ncoord, int dim, const double *in, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,PolyCurve))(this,npoint,ncoord,dim,in, status ); } void astRegionOutline_( AstPlot *this, AstRegion *region, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,RegionOutline))(this,region,status); } void astGrfSet_( AstPlot *this, const char *name, AstGrfFun fun, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GrfSet))(this,name,fun, status ); } void astGrfPush_( AstPlot *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GrfPush))(this, status ); } void astGrfPop_( AstPlot *this, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GrfPop))(this, status ); } void astGrfWrapper_( AstPlot *this, const char *name, AstGrfWrap wrapper, int *status ){ if( !astOK ) return; (**astMEMBER(this,Plot,GrfWrapper))(this,name,wrapper, status ); } void astSetLogPlot_( AstPlot *this, int axis, int value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Plot,SetLogPlot))( this, axis, value, status ); } void astClearLogPlot_( AstPlot *this, int axis, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Plot,ClearLogPlot))( this, axis, status ); } AstKeyMap *astGetGrfContext_( AstPlot *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Plot,GetGrfContext))( this, 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. */ /* Special interface function implementations. */ /* ------------------------------------------- */ AstPlot *astPlotId_( void *frame_void, const float graphbox[4], const double basebox[4], const char *options, ... ) { /* *++ * Name: c astPlot f AST_PLOT * Purpose: * Create a Plot. * Type: * Public function. * Synopsis: c #include "plot.h" c AstPlot *astPlot( AstFrame *frame, const float graphbox[ 4 ], c const double basebox[ 4 ], const char *options, ... ) f RESULT = AST_PLOT( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS ) * Class Membership: * Plot constructor. * Description: * This function creates a new Plot and optionally initialises its * attributes. * * A Plot is a specialised form of FrameSet, in which the base * Frame describes a "graphical" coordinate system and is * associated with a rectangular plotting area in the underlying * graphics system. This plotting area is where graphical output * appears. It is defined when the Plot is created. * * The current Frame of a Plot describes a "physical" coordinate * system, which is the coordinate system in which plotting * operations are specified. The results of each plotting operation * are automatically transformed into graphical coordinates so as * to appear in the plotting area (subject to any clipping which * may be in effect). * * Because the Mapping between physical and graphical coordinates * may often be non-linear, or even discontinuous, most plotting * does not result in simple straight lines. The basic plotting * element is therefore not a straight line, but a geodesic curve c (see astCurve). A Plot also provides facilities for drawing c markers or symbols (astMark), text (astText) and grid lines c (astGridLine). It is also possible to draw curvilinear axes with c optional coordinate grids (astGrid). f (see AST_CURVE). A Plot also provides facilities for drawing f markers or symbols (AST_MARK), text (AST_TEXT) and grid lines f (AST_GRIDLINE). It is also possible to draw curvilinear axes f with optional coordinate grids (AST_GRID). * A range of Plot attributes is available to allow precise control * over the appearance of graphical output produced by these c functions. f routines. * * You may select different physical coordinate systems in which to * plot (including the native graphical coordinate system itself) * by selecting different Frames as the current Frame of a Plot, * using its Current attribute. You may also set up clipping (see c astClip) to limit the extent of any plotting you perform, and f AST_CLIP) to limit the extent of any plotting you perform, and * this may be done in any of the coordinate systems associated * with the Plot, not necessarily the one you are plotting in. * * Like any FrameSet, a Plot may also be used as a Frame. In this * case, it behaves like its current Frame, which describes the * physical coordinate system. * * When used as a Mapping, a Plot describes the inter-relation * between graphical coordinates (its base Frame) and physical * coordinates (its current Frame). It differs from a normal * FrameSet, however, in that an attempt to transform points which * lie in clipped areas of the Plot will result in bad coordinate * values (AST__BAD). * Parameters: c frame f FRAME = INTEGER (Given) * Pointer to a Frame describing the physical coordinate system * in which to plot. A pointer to a FrameSet may also be given, * in which case its current Frame will be used to define the * physical coordinate system and its base Frame will be mapped * on to graphical coordinates (see below). * * If a null Object pointer (AST__NULL) is given, a default * 2-dimensional Frame will be used to describe the physical * coordinate system. Labels, etc. may then be attached to this * by setting the appropriate Frame attributes * (e.g. Label(axis)) for the Plot. c graphbox f GRAPHBOX( 4 ) = REAL (Given) * An array giving the position and extent of the plotting area * (on the plotting surface of the underlying graphics system) * in which graphical output is to appear. This must be * specified using graphical coordinates appropriate to the * underlying graphics system. * * The first pair of values should give the coordinates of the * bottom left corner of the plotting area and the second pair * should give the coordinates of the top right corner. The * coordinate on the horizontal axis should be given first in * each pair. Note that the order in which these points are * given is important because it defines up, down, left and * right for subsequent graphical operations. c basebox f BASEBOX( 4 ) = DOUBLE PRECISION (Given) * An array giving the coordinates of two points in the supplied * Frame (or in the base Frame if a FrameSet was supplied) which * correspond to the bottom left and top right corners of the * plotting area, as specified above. This range of coordinates * will be mapped linearly on to the plotting area. The * coordinates should be given in the same order as above. 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 Plot. 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 Plot. 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 astPlot() f AST_PLOT * A pointer to the new Plot. * Notes: * - The base Frame of the returned Plot will be a new Frame which * is created by this function to represent the coordinate system * of the underlying graphics system (graphical coordinates). It is * given a Frame index of 1 within the Plot. The choice of base * Frame (Base attribute) should not, in general, be changed once a * Plot has been created (although you could use this as a way of * moving the plotting area around on the plotting surface). c - If a Frame is supplied (via the "frame" pointer), then it f - If a Frame is supplied (via the FRAME pointer), then it * becomes the current Frame of the new Plot and is given a Frame * index of 2. c - If a FrameSet is supplied (via the "frame" pointer), then f - If a FrameSet is supplied (via the FRAME pointer), then * all the Frames within this FrameSet become part of the new Plot * (where their Frame indices are increased by 1), with the * FrameSet's current Frame becoming the current Frame of the Plot. * - If a null Object pointer (AST__NULL) is supplied (via the c "frame" pointer), then the returned Plot will contain two f FRAME pointer), then the returned Plot will contain two * Frames, both created by this function. The base Frame will * describe graphics coordinates (as above) and the current Frame * will be a basic Frame with no attributes set (this will * therefore give default values for such things as the Plot Title * and the Label on each axis). Physical coordinates will be mapped * linearly on to graphical coordinates. * - An error will result if the Frame supplied (or the base Frame * if a FrameSet was supplied) is not 2-dimensional. * - 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 astPlot constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astPlot_ 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 astPlot_ 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 */ AstPlot *new; /* Pointer to new Plot */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get apointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ new = NULL; /* Obtain a Frame pointer from any ID supplied and validate the pointer to ensure it identifies a valid Frame. */ if( frame_void ){ frame = astVerifyFrame( astMakePointer( frame_void ) ); } else { frame = NULL; } /* Check the pointer can be used. */ if ( astOK ) { /* Initialise the Plot, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPlot( NULL, sizeof( AstPlot ), !class_init, &class_vtab, "Plot", frame, graphbox, basebox ); /* 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 Plot'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 Plot. */ return astMakeId( new ); } ast-8.3.0/ferror.c0000664000175000017500000000340213004147321010671 00000000000000/* *+ * Name: * ferror.c * Purpose: * Define a FORTRAN 77 interface to the AST Error module. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Error module. * Routines Defined: * None. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 15-JUL-1996 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "error.h" /* C interface to the Error module */ /* At present there are no Fortran callable routines in this module. */ ast-8.3.0/flutmap.c0000664000175000017500000000640413004147321011047 00000000000000/* *+ * Name: * flutmap.c * Purpose: * Define a FORTRAN 77 interface to the AST LutMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the LutMap class. * Routines Defined: * AST_ISALUTMAP * AST_LUTMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 8-JUL-1997 (RFWS): * Original version. *- */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "lutmap.h" /* C interface to the LutMap class */ F77_LOGICAL_FUNCTION(ast_isalutmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISALUTMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsALutMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_lutmap)( INTEGER(NLUT), DOUBLE_ARRAY(LUT), DOUBLE(START), DOUBLE(INC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NLUT) GENPTR_DOUBLE_ARRAY(LUT) GENPTR_DOUBLE(START) GENPTR_DOUBLE(INC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; astAt( "AST_LUTMAP", NULL, 0 ); astWatchSTATUS( char *options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astLutMap( *NLUT, LUT, *START, *INC, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/ast_link.in0000664000175000017500000004434113004147320011370 00000000000000 # N.B. the previous line should be blank. #++ # Name: # ast_link # Purpose: # Link a program with the AST library. # Type of Module: # Shell script. # Description: # This command should be used when building programs which use the AST # library, in order to generate the correct arguments to allow the compiler # to link your program. The arguments generated are written to standard # output but may be substituted into the compiler command line in the # standard UNIX way using backward quotes (see below). # # By default, it is assumed that you are building a stand-alone program # which does not produce graphical output. However, switches are provided # for linking other types of program. # Invocation: #c cc program.c -L/star/lib `ast_link [switches]` -o program #f f77 program.f -L/star/lib `ast_link [switches]` -o program # Switches: # The following switches may optionally be given to this command to # modify its behaviour: # # # - ``-csla'': Ignored. Provided for backward compatibility only. # # - ``-fsla'': Ignored. Provided for backward compatibility only. # # - ``-ems'': Requests that the program be linked so that error messages # produced by the AST library are delivered via the Starlink EMS (Error # Message Service) library (Starlink System Note SSN/4). By default, # error messages are simply written to standard error. # # - ``-drama'': Requests that the program be linked so that error messages # produced by the AST library are delivered via the DRAMA Ers (Error # Reporting Service) library. By default, error messages are simply # written to standard error. # # - ``-grf'': Requests that no arguments be generated to specify which # 2D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new graphics system yourself and wish to provide your own arguments for # linking with it. This switch differs from the other ``grf'' switches in # that it assumes that your graphics module implements the complete # interface required by the current version of AST. If future versions of # AST introduce new functions to the graphics interface, this switch will # cause ``unresolved symbol'' errors to occur during linking, warning you # that you need to implement new functions in your graphics module. To # avoid such errors, you can use one of the other, version-specific, # switches in place of the ``-grf'' switch, but these will cause run-time # errors to be reported if any AST function is invoked which requires # facilities not in the implemented interface. # # - ``-grf_v2.0'': This switch is equivalent to the ``-mygrf'' switch. # It indicates that you want to link with your own graphics module # which implements the 2D graphics interface required by V2.0 of AST. # # - ``-grf_v3.2'': Indicates that you want to link with your own # graphics module which implements the 2D graphics interface required by # V3.2 of AST. # # - ``-grf_v5.6'': Indicates that you want to link with your own # graphics module which implements the 2D graphics interface required by # V5.6 of AST. # # - ``-myerr'': Requests that no arguments be generated to specify how # error messages produced by the AST library should be delivered. You # should use this option only if you have implemented an interface to a # new error delivery system yourself and wish to provide your own # arguments for linking with it. # # - ``-mygrf'': This switch has been superceeded by the ``-grf'' switch, # but is retained in order to allow applications to be linked with a # graphics module which implements the 2D interface used by AST V2.0. It # is equivalent to the ``-grf_v2.0'' switch. # # - ``-pgp'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no 2D graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via # the standard (or ``native'') version of the PGPLOT graphics # package. By default, no 2D graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # # - ``-grf3d'': Requests that no arguments be generated to specify which # 3D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new 3D graphics system yourself and wish to provide your own arguments # for linking with it. # # - ``-pgp3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no 3D graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via # the standard (or ``native'') version of the PGPLOT graphics # package. By default, no 3D graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # ERFA & PAL: # The AST distribution includes bundled copies of the ERFA and PAL # libraries. These will be used for fundamental positional astronomy # calculations unless the "--with-external_pal" option was used when # AST was configured. If "--with-external_pal" is used, this script # will include "-lpal" in the returned list of linking options, and # the user should then ensure that external copies of the PAL and # ERFA libraries are available (ERFA functions are used within PAL). # Examples: #c cc display.c -L/star/lib `ast_link -pgplot` -o display #c Compiles and links a C program called ``display'' which uses #c the standard version of PGPLOT for graphical output. #c cc plotit.c -L. -L/star/lib `ast_link -grf` -lgrf -o plotit #c Compiles and links a C program ``plotit''. The ``-grf'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by the current version of AST. #c Here, this interface is supplied by means of the ``-lgrf'' library #c reference. #c cc plotit.c -L. -L/star/lib `ast_link -grf_v2.0` -lgrf -o plotit #c Compiles and links a C program ``plotit''. The ``-grf_v2.0'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by version 2.0 of AST. #c Here, this interface is supplied by means of the ``-lgrf'' library #c reference. #f f77 display.f -L/star/lib `ast_link -pgplot` -o display #f Compiles and links a Fortran program called ``display'' which uses #f the standard version of PGPLOT for graphical output. #f f77 plotit.f -L. -L/star/lib `ast_link -grf` -lgrf -o plotit #f Compiles and links a Fortran program ``plotit''. The ``-grf'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by the current version of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. #f f77 plotit.f -L. -L/star/lib `ast_link -grf_v2.0` -lgrf -o plotit #f Compiles and links a Fortran program ``plotit''. The ``-grf_v2.0'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by version 2.0 of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. # Copyright: # Copyright (C) 1997-2006 Council for the Central Laboratory of the Research Councils # Copyright (C) 2007-2008 Science & Technology Facilities Council. # All Rights Reserved. # Authors: # RFWS: R.F. Warren-Smith (STARLINK) # DSB: David S. Berry (STARLINK) # TIMJ: Tim Jenness (JAC, Hawaii) # {enter_new_authors_here} # History: # 11-JUN-1996 (RFWS): # Original version. # 11-NOV-1996 (RFWS): # Added switches. # 18-NOV-1997 (RFWS): # Adapted prologue for document extraction. # 28-SEP-1998 (RFWS): # Distinguish between -pgp and -pgplot options. # 12-JAN-2001 (DSB): # Move terminating "}" in function "find" onto a new line to # avoid error when run under bash 2.04.11(1) (redhat 7). # 3-MAY-2001 (DSB): # Added a terminating ";" to the "done" statement at the end of # the "find" function, so that ast_link can be used on Debian Linux. # 23-JAN-2004 (DSB): # Added switches to support older grf implementations. # 24-AUG-2004 (DSB): # Removed f77='y' from -ems case. # 21-APR-2005 (DSB): # Added "-fsla" option. # 16-JUN-2006 (DSB): # Ignore "-fsla" and "-clsa" options, and always use PAL. # 26-JUN-2007 (DSB): # Added "-grf3d", "-pgplot3d" and "-pgp3d" flags. # 13-NOV-2008 (TIMJ): # Add -drama option for DRAMA Ers support. # 3-MAR-2011 (DSB): # Added grf 5.6 options. # {enter_further_changes_here} # Bugs: # {note_any_bugs_here} #-- # This line is edited during configuration of this script to define a list # of the libraries that must be linked in order to resolve Fortran 77 # references made from within a C main program. Typically, these will arise # from libraries written in Fortran which the AST library (or the C # program) calls. The value here is worked out by the autoconf macro # AC_FC_LIBRARY_LDFLAGS. flibs='@FCLIBS@' # This function searches the directory path specified in PATH, looking for # an executable file which is not a directory. If found, it echos the full # file name to standard output. Otherwise, it outputs nothing. find() { IFS=':'; for d in $PATH; do f="${d:=.}/${1}" test -x "${f}" -a ! -d "${f}" && echo "${f}" && break done; } # Initialise linking options. err='' grf='' grf3d='' sla='' f77='' # Interpret command line switches. # -------------------------------- while :; do case "${1}" in # -csla - Previously used to request C version of SLALIB. Now ignored. -csla) # sla='c' shift;; # -fsla - Previously used to request Fortran version of SLALIB. Now ignored. -fsla) # sla='f' shift;; # -ems - Requests error reporting through EMS. -ems) err='ems' shift;; # -drama - Requests error reporting through DRAMA Ers. -drama) err='drama' shift;; # -myerr - Requests no error reporting. -myerr) err='my' shift;; # -grf - Requests no 2D graphics. -grf) grf='current' shift;; # -mygrf - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -mygrf) grf='v2.0' shift;; # -grf_v2.0 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -grf_v2.0) grf='v2.0' shift;; # -grf_v3.2 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V3.2. -grf_v3.2) grf='v3.2' shift;; # -grf_v5.6 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V5.6. -grf_v5.6) grf='v5.6' shift;; # -pgp - Requests 2D graphical output through Starlink PGPLOT. -pgp) grf='pgp' shift;; # -pgplot - Requests 2D graphical output through native PGPLOT. -pgplot) grf='pgplot' shift;; # -grf3d - Requests no 3D graphics. -grf3d) grf3d='current' shift;; # -pgp3d - Requests 3D graphical output through Starlink PGPLOT. -pgp3d) grf3d='pgp' shift;; # -pgplot3d - Requests 3D graphical output through native PGPLOT. -pgplot3d) grf3d='pgplot' shift;; # Once all switches have been read, continue with the rest of the script. '') break;; # Catch unrecognised arguments and report an error. *) echo >&2 "ast_link: unknown argument \""${1}"\" given" exit 1;; esac done # Link with the main AST library. # ------------------------------- # Start forming the list of arguments with the main AST library itself. args='-last ' # Generate arguments for linking PAL. # ----------------------------------- case "@EXTERNAL_PAL@" in # If we configured --with-external_pal include a link option to pick up # an external PAL library. 1) args="${args} -lpal";; # Otherwise, use the internal PAL & ERFA libraries. *) args="${args} -last_pal";; esac # Generate arguments for linking the 2D graphics system. # ------------------------------------------------------ case "${grf}" in # If using Starlink PGPLOT, link with the AST PGPLOT interface and # the Fortran library via the PGP link script (if found). pgp) args="${args} -last_pgplot `\`find pgp_link\``" f77='y';; # If using native PGPLOT, link with the AST PGPLOT interface and the # Fortran library via the PGPLOT link script (if found). pgplot) args="${args} -last_pgplot `\`find pgplot_link\``" f77='y';; # If using own graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # If using own graphics which conform to the requirements of version 5.6 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 5.6. v5.6) :;; # If using own graphics which conform to the requirements of version 3.2 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 3.2. v3.2) args="${args} -last_grf_5.6";; # If using own graphics which conform to the requirements of version 2.0 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 2.0. v2.0) args="${args} -last_grf_3.2 -last_grf_5.6";; # Default graphics (none) requires linking with all the default (null) AST # "grf" modules. *) args="${args} -last_grf_2.0 -last_grf_3.2 -last_grf_5.6";; esac # Generate arguments for linking the 3D graphics system. # ------------------------------------------------------ case "${grf3d}" in # If using Starlink PGPLOT, link with the AST 3D PGPLOT interface and # the Fortran library via the PGP link script (if found). pgp) args="${args} -last_pgplot3d `\`find pgp_link\``" f77='y';; # If using native PGPLOT, link with the AST 3D PGPLOT interface and the # Fortran library via the PGPLOT link script (if found). pgplot) args="${args} -last_pgplot3d `\`find pgplot_link\``" f77='y';; # If using own 3D graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # Default graphics (none) requires linking with all the default (null) AST # "grf3d" modules. *) args="${args} -last_grf3d";; esac # Make a second pass through the AST library. # ------------------------------------------- # This library is a link to the main AST library and results in a second # pass to resolve any backward references generated by the other modules # used above. A different library name must be used to avoid the two passes # being merged into one (either below, or by other link scripts). args="${args} -last_pass2" # Generate arguments for linking the error reporting system. # ---------------------------------------------------------- case "${err}" in # If using EMS, link with the AST EMS interface and the EMS library via the # link script (if found). ems) args="${args} -last_ems `\`find ems_link\``";; # If using DRAMA, link with the AST DRAMA interface and the DRAMA Ers library # via the link script (if found). drama) args="${args} -last_drama -lers";; # If using own error reporting, do not produce any arguments. my) :;; # Default error reporting requires linking with the default AST "err" module. *) args="${args} -last_err";; esac # Link with the maths library. # ---------------------------- args="${args} -lm" # Link with the starmem library, if available. # -------------------------------------------- args="${args} `\`find starmem_link\``" # Resolve Fortran 77 references. # ------------------------------ # If libraries written in Fortran are being linked against, then include # additional libaries needed to resolve the references these will produce # (in the event that the main program is not Fortran). if test "${f77}" = 'y'; then args="${args} ${flibs}"; fi # Pass the resulting argument list through an awk script which eliminates # all except the last reference to each library. echo "${args}" \ | awk 'BEGIN{RS=" ";FS="\n"} {if($1)f[i++]=$1} END{for(;i--;)if(!w[f[i]]++)l=f[i]" "l;print l}' # End of script. ast-8.3.0/tranmap.c0000664000175000017500000023771613004147321011055 00000000000000/* *class++ * Name: * TranMap * Purpose: * Mapping with specified forward and inverse transformations. * Constructor Function: c astTranMap f AST_TRANMAP * Description: * A TranMap is a Mapping which combines the forward transformation of * a supplied Mapping with the inverse transformation of another * supplied Mapping, ignoring the un-used transformation in each * Mapping (indeed the un-used transformation need not exist). * * When the forward transformation of the TranMap is referred to, the * transformation actually used is the forward transformation of the * first Mapping supplied when the TranMap was constructed. Likewise, * when the inverse transformation of the TranMap is referred to, the * transformation actually used is the inverse transformation of the * second Mapping supplied when the TranMap was constructed. * Inheritance: * The TranMap class inherits from the Mapping class. * Attributes: * The TranMap class does not define any new attributes beyond those * which are applicable to all Mappings. * Functions: c The TranMap class does not define any new functions beyond those f The TranMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 10-FEB-2004 (DSB): * Original version. * 19-JAN-2005 (DSB): * Fix memory leak. * 14-FEB-2006 (DSB): * - Over-ride the astDecompose method. * - Fix bug in MapSplit related to use of invert flags. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 10-MAY-2006 (DSB): * Override astEqual. *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 TranMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate Mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "permmap.h" /* Coordinate permutation Mappings */ #include "cmpmap.h" /* Compound Mappings */ #include "unitmap.h" /* Unit Mappings */ #include "tranmap.h" /* Interface definition for this class */ #include "frame.h" /* Frames */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int *(* parent_mapsplit)( AstMapping *, int, const int *, AstMapping **, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(TranMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(TranMap,Class_Init) #define class_vtab astGLOBAL(TranMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstTranMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstTranMap *astTranMapId_( void *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *RemoveRegions( AstMapping *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, 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 MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void Decompose( AstMapping *, AstMapping **, AstMapping **, int *, int *, int *, int * ); static int GetObjSize( AstObject *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two TranMaps are equivalent. * Type: * Private function. * Synopsis: * #include "tranmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * TranMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two TranMaps are equivalent. * Parameters: * this * Pointer to the first Object (a TranMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the TranMaps are equivalent, zero otherwise. * 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: */ AstTranMap *that; AstTranMap *this; int nin; int nout; int result; int that_inv1; int that_inv2; int this_inv1; int this_inv2; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two TranMap structures. */ this = (AstTranMap *) this_object; that = (AstTranMap *) that_object; /* Check the second object is a TranMap. We know the first is a TranMap since we have arrived at this implementation of the virtual function. */ if( astIsATranMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* Temporarily re-instate the original Invert flag values. */ that_inv1 = astGetInvert( that->map1 ); that_inv2 = astGetInvert( that->map2 ); this_inv1 = astGetInvert( this->map1 ); this_inv2 = astGetInvert( this->map2 ); astSetInvert( this->map1, this->invert1 ); astSetInvert( this->map2, this->invert2 ); astSetInvert( that->map1, that->invert1 ); astSetInvert( that->map2, that->invert2 ); /* If the Invert flags for the two TranMaps differ, it may still be possible for them to be equivalent. First compare the TranMaps if their Invert flags are the same. In this case all the attributes of the two TranMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { if( astEqual( this->map1, that->map1 ) && astEqual( this->map2, that->map2 ) ) { result = 1; } /* If the Invert flags for the two TranMaps differ, the attributes of the two TranMaps must be inversely related to each other. */ } else { astInvert( that->map1 ); astInvert( that->map2 ); if( astEqual( this->map1, that->map2 ) && astEqual( this->map2, that->map1 ) ) { result = 1; } } /* Restore the original Invert flag values. */ astSetInvert( this->map1, this_inv1 ); astSetInvert( this->map2, this_inv2 ); astSetInvert( that->map1, that_inv1 ); astSetInvert( that->map2, that_inv2 ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "tranmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * TranMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied TranMap, * in bytes. * Parameters: * this * Pointer to the TranMap. * 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: */ AstTranMap *this; /* Pointer to TranMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the TranMap structure. */ this = (AstTranMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->map1 ); result += astGetObjSize( this->map2 ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void Decompose( AstMapping *this_mapping, AstMapping **map1, AstMapping **map2, int *series, int *invert1, int *invert2, int *status ) { /* * * Name: * Decompose * Purpose: * Decompose a Mapping into two component Mappings. * Type: * Private function. * Synopsis: * #include "tranmap.h" * void Decompose( AstMapping *this, AstMapping **map1, * AstMapping **map2, int *series, * int *invert1, int *invert2, int *status ) * Class Membership: * TranMap member function (over-rides the protected astDecompose * method inherited from the Mapping class). * Description: * This function returns pointers to the two Mappings encapsulated by * a TranMap. * Parameters: * this * Pointer to the Mapping. * map1 * Address of a location to receive a pointer to first component * Mapping (the forward Mapping). * map2 * Address of a location to receive a pointer to second component * Mapping (the inverse Mapping). * series * Address of a location to receive a value indicating if the * component Mappings are applied in series or parallel. A non-zero * value means that the supplied Mapping is equivalent to applying map1 * followed by map2 in series. A zero value means that the supplied * Mapping is equivalent to applying map1 to the lower numbered axes * and map2 to the higher numbered axes, in parallel. Zero is * returned for a TranMap. * invert1 * The value of the Invert attribute to be used with map1. * invert2 * The value of the Invert attribute to be used with map2. * status * Pointer to the inherited status variable. * Notes: * - Any changes made to the component Mappings using the returned * pointers will be reflected in the supplied Mapping. *- */ /* Local Variables: */ AstTranMap *this; /* Pointer to TranMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TranMap structure. */ this = (AstTranMap *) this_mapping; /* If the TranMap has been inverted, return the Mappings in reverse order with inverted Invert falgs. */ if( astGetInvert( this ) ) { if( map1 ) *map1 = astClone( this->map2 ); if( map2 ) *map2 = astClone( this->map1 ); if( invert1 ) *invert1 = this->invert2 ? 0 : 1; if( invert2 ) *invert2 = this->invert1 ? 0 : 1; /* If the TranMap has not been inverted, return the Mappings in their original order with their original Invert flags. */ } else { if( map1 ) *map1 = astClone( this->map1 ); if( map2 ) *map2 = astClone( this->map2 ); if( invert1 ) *invert1 = this->invert1; if( invert2 ) *invert2 = this->invert2; } } void astInitTranMapVtab_( AstTranMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTranMapVtab * Purpose: * Initialise a virtual function table for a TranMap. * Type: * Protected function. * Synopsis: * #include "tranmap.h" * void astInitTranMapVtab( AstTranMapVtab *vtab, const char *name ) * Class Membership: * TranMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the TranMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsATranMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* None. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; mapping->RemoveRegions = RemoveRegions; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; parent_mapsplit = mapping->MapSplit; mapping->MapSplit = MapSplit; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->Decompose = Decompose; mapping->MapMerge = MapMerge; mapping->Rate = Rate; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "TranMap", "Compound Transformation Mapping" ); /* 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) ); } } #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: * TranMap 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: */ AstTranMap *this; /* Pointer to TranMap structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the TranMap structure. */ this = (AstTranMap *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->map1, mode, extra, fail ); if( !result ) result = astManageLock( this->map2, mode, extra, fail ); return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a TranMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * TranMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated TranMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated TranMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated TranMap which is to be merged with * its neighbours. This should be a cloned copy of the TranMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * TranMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated TranMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstCmpMap *cmap; /* Pointer to compound Mapping */ AstMapping *cmap_f; /* Pointer to compound Mapping */ AstMapping *cmap_i; /* Pointer to compound Mapping */ AstMapping *hmap1; /* Pointer to 1st comp of higher TranMap */ AstMapping *hmap2; /* Pointer to 2nd comp of higher TranMap */ AstMapping *hmap_f; /* Pointer to fwd Mapping of higher TranMap */ AstMapping *hmap_i; /* Pointer to inv Mapping of higher TranMap */ AstMapping *map1; /* Pointer to 1st comp of nominated TranMap */ AstMapping *map2; /* Pointer to 2nd comp of nominated TranMap */ AstMapping *map_f; /* Pointer to fwd Mapping of nominated TranMap */ AstMapping *map_i; /* Pointer to inv Mapping of nominated TranMap */ AstMapping *smap; /* Pointer to simplified Mapping */ AstMapping *smap_f; /* Pointer to simplified Mapping */ AstMapping *smap_i; /* Pointer to simplified Mapping */ AstTranMap *hmap; /* Pointer to higher TranMap */ AstTranMap *map; /* Pointer to this TranMap */ AstTranMap *new; /* Pointer to merged TranMap */ int i; /* Loop count */ int old_hinv1; /* Original Invert flag for hmap->map1 */ int old_hinv2; /* Original Invert flag for hmap->map2 */ int old_inv1; /* Original Invert flag for this->map1 */ int old_inv2; /* Original Invert flag for this->map2 */ int result; /* The value to return */ /* Initialise.*/ result = -1; /* Check the inherited status. */ if ( !astOK ) return result; /* Get a pointer to this TranMap. */ map = (AstTranMap *) this; /* Get the two component Mappings,and temporarily set their Invert attributes back to the values they had when the TranMap was created, saving their current Invert values so that they can be re-instated later. */ map1 = map->map1; old_inv1 = astGetInvert( map1 ); astSetInvert( map1, map->invert1 ); map2 = map->map2; old_inv2 = astGetInvert( map2 ); astSetInvert( map2, map->invert2 ); /* Simplify the TranMap on its own. */ /* ================================ */ /* If the TranMap is inverted, creat an equal TranMap which is not inverted. To do this, invert and swap the component Mappings. */ if( ( *invert_list )[ where ] ) { astInvert( map1 ); astInvert( map2 ); new = astTranMap( map2, map1, "", status ); astInvert( map1 ); astInvert( map2 ); (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) new; ( *invert_list )[ where ] = 0; result = where; /* Otherwise, try to simplify each of the component Mappings. */ } else { smap_f = astSimplify( map1 ); smap_i = astSimplify( map2 ); /* Assume some simplification took place if the pointers have changed. */ if( smap_f != map1 || smap_i != map2 ) { /* Construct a new TranMap from these simplifgied Mappings. */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) astTranMap( smap_f, smap_i, "", status ); result = where; /* Otherwise, if the both component Mappings are defined in both directions... */ } else if( astGetTranForward( map1 ) && astGetTranInverse( map1 ) && astGetTranForward( map2 ) && astGetTranInverse( map2 ) ) { /* Form a series CmpMap from the two component Mappings, with the second Mapping inverted. */ astInvert( map2 ); cmap = astCmpMap( map1, map2, 1, "", status ); astInvert( map2 ); /* If this CmpMap simplifies to a UnitMap, then the two components of the TranMap are equal, and so we can replace the entire TranMap with either of its components. Note, we leave the supplied invert flag unchanged, since the copycreated below refers to the Mapping as it was when the TranMap was created. However, we invert the returned Mapping if necessary. */ smap = astSimplify( cmap ); if( astIsAUnitMap( smap ) ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = astCopy( map1 ); if( ( *invert_list )[ where ] ) astInvert( ( *map_list )[ where ] ); result = where; } /* Release resources. */ smap = astAnnul( smap ); cmap = astAnnul( cmap ); } /* Release resources. */ smap_f = astAnnul( smap_f ); smap_i = astAnnul( smap_i ); } /* Merge the TranMap with a neighbouring TranMap. */ /* ============================================== */ /* Only do this if no change was made above, and we are combining the Mappings in series. */ if( result == -1 && series ) { /* Is the higher neighbour a TranMap? */ if( where < ( *nmap - 1 ) && astIsATranMap( ( *map_list )[ where + 1 ] ) ){ /* Get the two component Mappings of the higher TranMap, and temporarily set their Invert attributes back to the values they had when the TranMap was created, saving their current Invert values so that they can be re-instated later. */ hmap = (AstTranMap *) ( *map_list )[ where + 1 ]; hmap1 = hmap->map1; old_hinv1 = astGetInvert( hmap1 ); astSetInvert( hmap1, hmap->invert1 ); hmap2 = hmap->map2; old_hinv2 = astGetInvert( hmap2 ); astSetInvert( hmap2, hmap->invert2 ); /* Get the Mappings which defines the forward and inverse transformation of the lower TranMap ("this"). Then, map_f and map_i are pointers to Mappings which could be used to construct a new TranMap which would be equivalent to "this" with the supplied invert setting. */ if( ( *invert_list )[ where ] ) { map_f = map2; map_i = map1; astInvert( map_f ); astInvert( map_i ); } else { map_f = map1; map_i = map2; } /* Likewise, get the Mappings which defines the forward and inverse transformation of the higher TranMap. */ if( ( *invert_list )[ where + 1 ] ) { hmap_f = hmap2; hmap_i = hmap1; astInvert( hmap_f ); astInvert( hmap_i ); } else { hmap_f = hmap1; hmap_i = hmap2; } /* Combine the two forward Mappings together into a series CmpMap, and simplify it. */ cmap_f = (AstMapping *) astCmpMap( map_f, hmap_f, 1, "", status ); smap_f = astSimplify( cmap_f ); /* Do the same for the inverse Mappings */ cmap_i = (AstMapping *) astCmpMap( map_i, hmap_i, 1, "", status ); smap_i = astSimplify( cmap_i ); /* Was any simplification performed? We assume this is the case if the either of the simplied pointer differs from the original pointer. */ if( cmap_f != smap_f || cmap_i != smap_i ) { /* In which case,construct a new TranMap from the simplified Mappings. */ new = astTranMap( smap_f, smap_i, "", status ); } else { new = NULL; } /* Free resources.*/ cmap_f = astAnnul( cmap_f ); smap_f = astAnnul( smap_f ); cmap_i = astAnnul( cmap_i ); smap_i = astAnnul( smap_i ); /* Re-instate the original Invert values for the component Mappings of the higher TranMap. */ astSetInvert( hmap1, old_hinv1 ); astSetInvert( hmap2, old_hinv2 ); /* If we have a new TranMap, annul the first of the two Mappings, and replace it with the merged TranMap. Also set the invert flag. */ if( new ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) new; ( *invert_list )[ where ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ where + 1 ] ); for ( i = where + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = where; } } } /* Re-instate the original Invert values for the component Mappings. */ astSetInvert( map1, old_inv1 ); astSetInvert( map2, old_inv2 ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } 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 * TranMap. * Type: * Private function. * Synopsis: * #include "tranmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * TranMap 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 TranMap. This is only possible if the specified inputs * correspond to some subset of the TranMap outputs. That is, there * must exist a subset of the TranMap outputs for which each output * depends only on the selected TranMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied TranMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the TranMap to be split (the TranMap 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 TranMap, 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 TranMap 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 TranMap. 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 *fmap; /* Pointer to forward Mapping in supplied TranMap */ AstMapping *imap; /* Pointer to inverse Mapping in supplied TranMap */ AstMapping *rfmap; /* Pointer to split forward Mapping */ AstMapping *rimap; /* Pointer to split inverse Mapping */ AstTranMap *this; /* Pointer to TranMap structure */ int *ires; /* I/ps of inv Mapping dependent on selected o/ps */ int *out; /* O/ps of fwd Mapping dependent on selected i/ps */ int *result; /* Pointer to returned array */ int finv; /* Invert flag to use with fmap */ int i; /* Loop count */ int iinv; /* Invert flag to use with imap */ int nout; /* No. of outputs dependent on selected inputs */ int ok; /* Can required Mapping be created? */ int old_finv; /* Original Invert flag for fmap */ int old_iinv; /* Original Invert flag for imap */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the parent astMapSplit method to see if it can do the job. */ result = (*parent_mapsplit)( this_map, nin, in, map, status ); /* If not, we provide a special implementation here. */ if( !result ) { /* Get a pointer to the TranMap structure. */ this = (AstTranMap *) this_map; /* Get pointers to the forward and inverse Mappings, taking into account whether the TranMap has been inverted. */ if( !astGetInvert( this ) ) { fmap = this->map1; finv = this->invert1; imap = this->map2; iinv = this->invert2; } else { imap = this->map1; iinv = !( this->invert1 ); fmap = this->map2; finv = !( this->invert2 ); } /* Temporarily set the Invert flag of both Mappings back to their original values. */ old_finv = astGetInvert( fmap ); astSetInvert( fmap, finv ); old_iinv = astGetInvert( imap ); astSetInvert( imap, iinv ); /* Try to split the forward Mapping. */ out = astMapSplit( fmap, nin, in, &rfmap ); /* Check the split could be done. */ if( out ) { /* Get the number of outputs which are fed by the selected inputs. */ nout = astGetNout( rfmap ); /* See if the inverse Mapping can be split using these outputs as inputs. */ astInvert( imap ); ires = astMapSplit( imap, nout, out, &rimap ); astInvert( imap ); if( ires ) { astInvert( rimap ); /* Check that the resulting inputs are the same as the supplied inputs. */ if( astGetNin( rimap ) == nin ) { ok = 1; for( i = 0; i < nin; i++ ) { if( in[ i ] != ires[ i ] ) { ok = 0; break; } } /* If so create the required new TranMap. */ if( ok ) { *map = (AstMapping *) astTranMap( rfmap, rimap, "", status ); result = out; } } /* Free resources. */ ires = astFree( ires ); rimap = astAnnul( rimap ); } if( !result ) out = astFree( out ); rfmap = astAnnul( rfmap ); } /* Re-instate the Invert flags of the component Mappings. */ astSetInvert( fmap, old_finv ); astSetInvert( imap, old_iinv ); } /* 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 double Rate( AstMapping *this, 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 "tranmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * TranMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. Also evaluates the second derivative. * 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: * 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. */ /* Local Variables: */ AstTranMap *map; AstMapping *cmap; double result; int cinv; int old_inv; /* Check inherited status */ if( !astOK ) return AST__BAD; /* Get a pointer to the TranMap structure. */ map = (AstTranMap *) this; /* Choose the component Mapping to use, and get its original Invert value. Invert this if the TranMap itself has been inverted (this is because the astRate function has no "invert" argument so we need to invert the Mapping before calling astRate). */ if( astGetInvert( this ) ) { cmap = map->map2; cinv = !(map->invert2); } else { cmap = map->map1; cinv = map->invert1; } /* Temporarily set the Invert flag of the component Mapping back to its original value. */ old_inv = astGetInvert( cmap ); astSetInvert( cmap, cinv ); /* Use the astRate method of the component Mapping. */ result = astRate( cmap, at, ax1, ax2 ); /* Re-instate the Invert flag of the component Mapping. */ astSetInvert( cmap, old_inv ); /* Return the result. */ return result; } static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { /* * Name: * RemoveRegions * Purpose: * Remove any Regions from a Mapping. * Type: * Private function. * Synopsis: * #include "tranmap.h" * AstMapping *RemoveRegions( AstMapping *this, int *status ) * Class Membership: * TranMap 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 TranMap) 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 TranMap), then it is replaced with an equivalent UnitMap * in the returned Mapping. * * The implementation provided by the TranMap class invokes the * astRemoveRegions method on the two component Mappings, and joins * the results together into a new TranMap. * 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: */ AstTranMap *new; /* Pointer to new TranMap */ AstTranMap *this; /* Pointer to TranMap structure */ AstMapping *newmap1; /* New first component Mapping */ AstMapping *newmap2; /* New second component Mapping */ AstMapping *result; /* Result pointer to return */ int nax; /* Number of Frame axes */ int unit1; /* Is new first Mapping a UnitMap? */ int unit2; /* Is new second Mapping a UnitMap? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the TranMap. */ this = (AstTranMap *) this_mapping; /* Invoke the astRemoveRegions method on the two component Mappings. */ newmap1 = astRemoveRegions( this->map1 ); newmap2 = astRemoveRegions( this->map2 ); /* If neither component was modified, just return a clone of the supplied pointer. */ if( this->map1 == newmap1 && this->map2 == newmap2 ) { result = astClone( this ); /* Otherwise, we need to create a new Mapping to return. */ } else { /* 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 either of these new Mappings is a Frame, replace it with an equivalent UnitMap. Also, get flags indicating if either Mapping is a UnitMap.*/ if( astIsAFrame( newmap1 ) ) { nax = astGetNin( newmap1 ); (void) astAnnul( newmap1 ); newmap1 = (AstMapping *) astUnitMap( nax, " ", status ); unit1 = 1; } else { unit1 = astIsAUnitMap( newmap1 ); } if( astIsAFrame( newmap2 ) ) { nax = astGetNin( newmap2 ); (void) astAnnul( newmap2 ); newmap2 = (AstMapping *) astUnitMap( nax, " ", status ); unit2 = 1; } else { unit2 = astIsAUnitMap( newmap2 ); } /* If both new Mappings are UnitMaps, return an equivalent UnitMap. */ if( unit1 && unit2 ) { result = (AstMapping *) astUnitMap( astGetNin( newmap1 ) + astGetNin( newmap2 ), " ", status ); /* Otherwise, return a new TranMap containing the two new Mappings. */ } else { new = astCopy( this ); (void) astAnnul( new->map1 ); (void) astAnnul( new->map2 ); new->map1 = astClone( newmap1 ); new->map2 = astClone( newmap2 ); result = (AstMapping *) new; } } /* Free resources. */ newmap1 = astAnnul( newmap1 ); newmap2 = astAnnul( newmap2 ); /* Annul the returned Mapping if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a TranMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "tranmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * TranMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a TranMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required Mapping. * This implies applying each of the TranMap's component Mappings in turn, * either in series or in parallel. * Parameters: * this * Pointer to the TranMap. * in * Pointer to the PointSet associated with the input coordinate values. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the TranMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstMapping *cmap; /* Mapping which defines the required transformation */ AstPointSet *result; /* Pointer to output PointSet */ AstTranMap *map; /* Pointer to TranMap to be applied */ int cinv; /* Invert flag when TranMap was created */ int old_inv; /* Invert flag on entry to this function */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the TranMap. */ map = (AstTranMap *) this; /* Apply the parent Mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We now extend the parent astTransform method by applying the component Mappings of the TranMap to generate the output coordinate values. */ /* Determine whether to apply the forward or inverse Mapping, according to the direction specified and whether the Mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* Choose the component Mapping to use, and get its original Invert value. */ if( forward ) { cmap = map->map1; cinv = map->invert1; }else { cmap = map->map2; cinv = map->invert2; } /* Temporarily set the Invert flag of the component Mapping back to its original value. */ old_inv = astGetInvert( cmap ); astSetInvert( cmap, cinv ); /* Use the Transform method of the component Mapping. */ result = astTransform( cmap, in, forward, out ); /* Re-instate the Invert flag of the component Mapping. */ astSetInvert( cmap, old_inv ); /* If an error occurred, clean up by deleting the output PointSet (if allocated by this function) and setting a NULL result pointer. */ if ( !astOK ) { if ( !out ) result = astDelete( result ); result = NULL; } /* Return a pointer to the output PointSet. */ return result; } /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for TranMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for TranMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the component * Mappings within the TranMap. */ /* Local Variables: */ AstTranMap *in; /* Pointer to input TranMap */ AstTranMap *out; /* Pointer to output TranMap */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output TranMaps. */ in = (AstTranMap *) objin; out = (AstTranMap *) objout; /* For safety, start by clearing any references to the input component Mappings from the output TranMap. */ out->map1 = NULL; out->map2 = NULL; /* Make copies of these Mappings and store pointers to them in the output TranMap structure. */ out->map1 = astCopy( in->map1 ); out->map2 = astCopy( in->map2 ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for TranMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for TranMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstTranMap *this; /* Pointer to TranMap */ /* Obtain a pointer to the TranMap structure. */ this = (AstTranMap *) obj; /* Annul the pointers to the component Mappings. */ this->map1 = astAnnul( this->map1 ); this->map2 = astAnnul( this->map2 ); /* Clear the remaining TranMap variables. */ this->invert1 = 0; this->invert2 = 0; } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for TranMap 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 TranMap class to an output Channel. * Parameters: * this * Pointer to the TranMap 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 Variables: */ AstTranMap *this; /* Pointer to the TranMap structure */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TranMap structure. */ this = (AstTranMap *) this_object; /* Write out values representing the instance variables for the TranMap 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. */ /* First Invert flag. */ /* ------------------ */ ival = this->invert1; set = ( ival != 0 ); astWriteInt( channel, "InvA", set, 0, ival, ival ? "First Mapping used in inverse direction" : "First Mapping used in forward direction" ); /* Second Invert flag. */ /* ------------------- */ ival = this->invert2; set = ( ival != 0 ); astWriteInt( channel, "InvB", set, 0, ival, ival ? "Second Mapping used in inverse direction" : "Second Mapping used in forward direction" ); /* First Mapping. */ /* -------------- */ astWriteObject( channel, "MapA", 1, 1, this->map1, "Mapping for forward transformation" ); /* Second Mapping. */ /* --------------- */ astWriteObject( channel, "MapB", 1, 1, this->map2, "Mapping for inverse transformation" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsATranMap and astCheckTranMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(TranMap,Mapping) astMAKE_CHECK(TranMap) AstTranMap *astTranMap_( void *map1_void, void *map2_void, const char *options, int *status, ...) { /* *+ * Name: * astTranMap * Purpose: * Create a TranMap. * Type: * Protected function. * Synopsis: * #include "tranmap.h" * AstTranMap *astTranMap( AstMapping *map1, AstMapping *map2, const char *options, int *status, ... ) * Class Membership: * TranMap constructor. * Description: * This function creates a new TranMap and optionally initialises its * attributes. * Parameters: * map1 * Pointer to the first Mapping (which deinfes the forward * transformation). * map2 * Pointer to the second Mapping (which deinfes the inverse * transformation). * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new TranMap. 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 TranMap. * 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 TranMap constructor which is * available via the protected interface to the TranMap class. A * public interface is provided by the astTranMapId_ 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 * "map1" and "map2" parameters are of type (void *) and are * converted and validated within the function itself. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTranMap *new; /* Pointer to new TranMap */ AstMapping *map1; /* Pointer to first Mapping structure */ AstMapping *map2; /* Pointer to second Mapping structure */ 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 pointers to the Mapping structures provided. */ map1 = astCheckMapping( map1_void ); map2 = astCheckMapping( map2_void ); if ( astOK ) { /* Initialise the TranMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTranMap( NULL, sizeof( AstTranMap ), !class_init, &class_vtab, "TranMap", map1, map2 ); /* 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 TranMap'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 TranMap. */ return new; } AstTranMap *astTranMapId_( void *map1_void, void *map2_void, const char *options, ... ) { /* *++ * Name: c astTranMap f AST_TRANMAP * Purpose: * Create a TranMap. * Type: * Public function. * Synopsis: c #include "tranmap.h" c AstTranMap *astTranMap( AstMapping *map1, AstMapping *map2, c const char *options, ... ) f RESULT = AST_TRANMAP( MAP1, MAP2, OPTIONS, STATUS ) * Class Membership: * TranMap constructor. * Description: * This function creates a new TranMap and optionally initialises * its attributes. * * A TranMap is a Mapping which combines the forward transformation of * a supplied Mapping with the inverse transformation of another * supplied Mapping, ignoring the un-used transformation in each * Mapping (indeed the un-used transformation need not exist). * * When the forward transformation of the TranMap is referred to, the * transformation actually used is the forward transformation of the * first Mapping supplied when the TranMap was constructed. Likewise, * when the inverse transformation of the TranMap is referred to, the * transformation actually used is the inverse transformation of the * second Mapping supplied when the TranMap was constructed. * Parameters: c map1 f MAP1 = INTEGER (Given) * Pointer to the first component Mapping, which defines the * forward transformation. c map2 f MAP2 = INTEGER (Given) * Pointer to the second component Mapping, which defines the * inverse transformation. 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 TranMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new TranMap. The syntax used is identical to that for the f AST_SET routine. 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 astTranMap() f AST_TRANMAP = INTEGER * A pointer to the new TranMap. * Notes: * - The number of output coordinates generated by the two Mappings * (their Nout attribute) must be equal, as must the number of input * coordinates accepted by each Mapping (their Nin attribute). * - The forward transformation of the first Mapping must exist. * - The inverse transformation of the second Mapping must exist. c - Note that the component Mappings supplied are not copied by c astTranMap (the new TranMap simply retains a reference to c them). They may continue to be used for other purposes, but c should not be deleted. If a TranMap containing a copy of its c component Mappings is required, then a copy of the TranMap should c be made using astCopy. f - Note that the component Mappings supplied are not copied by f AST_TRANMAP (the new TranMap simply retains a reference to f them). They may continue to be used for other purposes, but f should not be deleted. If a TranMap containing a copy of its f component Mappings is required, then a copy of the TranMap should f be made using AST_COPY. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- * Implementation Notes: * - This function implements the external (public) interface to * the astTranMap constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astTranMap_ 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 "map1" and "map2" parameters * are of type (void *) and are converted from an ID value to a * pointer and validated within the function itself. * - The variable argument list also prevents this function from * invoking astTranMap_ 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 */ AstTranMap *new; /* Pointer to new TranMap */ AstMapping *map1; /* Pointer to first Mapping structure */ AstMapping *map2; /* Pointer to second Mapping structure */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ new = NULL; /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return new; /* Obtain the Mapping pointers from the ID's supplied and validate the pointers to ensure they identify valid Mappings. */ map1 = astVerifyMapping( astMakePointer( map1_void ) ); map2 = astVerifyMapping( astMakePointer( map2_void ) ); if ( astOK ) { /* Initialise the TranMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTranMap( NULL, sizeof( AstTranMap ), !class_init, &class_vtab, "TranMap", map1, map2 ); /* 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 TranMap'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 TranMap. */ return astMakeId( new ); } AstTranMap *astInitTranMap_( void *mem, size_t size, int init, AstTranMapVtab *vtab, const char *name, AstMapping *map1, AstMapping *map2, int *status ) { /* *+ * Name: * astInitTranMap * Purpose: * Initialise a TranMap. * Type: * Protected function. * Synopsis: * #include "tranmap.h" * AstTranMap *astInitTranMap( void *mem, size_t size, int init, * AstTranMapVtab *vtab, const char *name, * AstMapping *map1, AstMapping *map2 ) * Class Membership: * TranMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new TranMap object. It allocates memory (if necessary) to * accommodate the TranMap plus any additional data associated with the * derived class. It then initialises a TranMap 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 TranMap at the start of * the memory passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the TranMap is to be initialised. * This must be of sufficient size to accommodate the TranMap data * (sizeof(TranMap)) 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 TranMap (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 * TranMap structure, so a valid value must be supplied even if not * required for allocating memory. * init * A logical flag indicating if the TranMap'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 TranMap. * 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 Object * astClass function). * map1 * Pointer to the first Mapping. * map2 * Pointer to the second Mapping. * Returned Value: * A pointer to the new TranMap. * 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: */ AstTranMap *new; /* Pointer to new TranMap */ int nin; /* No. input coordinates for TranMap */ int nout; /* No. output coordinates for TranMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitTranMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Report an error if map1 has no forward transformation. */ if( !astGetTranForward( map1 ) && astOK ) { astError( AST__INTRD, "astInitTranMap(%s): The first supplied Mapping " "is not able to transform coordinates in the forward direction.", status, name ); } /* Report an error if map2 has no inverse transformation. */ if( !astGetTranInverse( map2 ) && astOK ) { astError( AST__INTRD, "astInitTranMap(%s): The second supplied Mapping " "is not able to transform coordinates in the inverse direction.", status, name ); } /* Check that the number of coordinates are compatible and report an error if they are not. */ nout = astGetNout( map1 ); if ( astGetNout( map2 ) != nout && astOK ) { astError( AST__INNCO, "astInitTranMap(%s): The number of output " "coordinates per point (%d) for the first Mapping " "supplied does not match the number of output " "coordinates (%d) for the second Mapping.", status, name, nout, astGetNout( map2 ) ); } nin = astGetNin( map1 ); if ( astGetNin( map2 ) != nin && astOK ) { astError( AST__INNCO, "astInitTranMap(%s): The number of input " "coordinates per point (%d) for the first Mapping " "supplied does not match the number of input " "coordinates (%d) for the second Mapping.", status, name, nin, astGetNin( map2 ) ); } /* Initialise a Mapping structure (the parent class) as the first component within the TranMap structure, allocating memory if necessary. Specify the number of input and output coordinates and in which directions the Mapping should be defined. */ if ( astOK ) { new = (AstTranMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, 1, 1 ); if ( astOK ) { /* Initialise the TranMap data. */ /* --------------------------- */ /* Store pointers to the component Mappings. */ new->map1 = astClone( map1 ); new->map2 = astClone( map2 ); /* Save the initial values of the inversion flags for these Mappings. */ new->invert1 = astGetInvert( map1 ); new->invert2 = astGetInvert( map2 ); /* If an error occurred, clean up by annulling the Mapping pointers and deleting the new object. */ if ( !astOK ) { new->map1 = astAnnul( new->map1 ); new->map2 = astAnnul( new->map2 ); new = astDelete( new ); } } } /* Return a pointer to the new object. */ return new; } AstTranMap *astLoadTranMap_( void *mem, size_t size, AstTranMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadTranMap * Purpose: * Load a TranMap. * Type: * Protected function. * Synopsis: * #include "tranmap.h" * AstTranMap *astLoadTranMap( void *mem, size_t size, * AstTranMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * TranMap loader. * Description: * This function is provided to load a new TranMap 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 * TranMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a TranMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the TranMap is to be * loaded. This must be of sufficient size to accommodate the * TranMap data (sizeof(TranMap)) 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 TranMap (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 TranMap 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(AstTranMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new TranMap. If this is NULL, a pointer to * the (static) virtual function table for the TranMap 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 "TranMap" is used instead. * Returned Value: * A pointer to the new TranMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTranMap *new; /* Pointer to the new TranMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this TranMap. In this case the TranMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstTranMap ); vtab = &class_vtab; name = "TranMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitTranMapVtab( 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 TranMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "TranMap" ); /* 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. */ /* First Invert flag. */ /* ------------------ */ new->invert1 = astReadInt( channel, "inva", 0 ); new->invert1 = ( new->invert1 != 0 ); /* Second Invert flag. */ /* ------------------- */ new->invert2 = astReadInt( channel, "invb", 0 ); new->invert2 = ( new->invert2 != 0 ); /* First Mapping. */ /* -------------- */ new->map1 = astReadObject( channel, "mapa", NULL ); /* Second Mapping. */ /* --------------- */ new->map2 = astReadObject( channel, "mapb", NULL ); /* If an error occurred, clean up by deleting the new TranMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new TranMap pointer. */ return new; } /* 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. */ /* None. */ ast-8.3.0/fshiftmap.c0000664000175000017500000000620013004147321011352 00000000000000/* *+ * Name: * fshiftmap.c * Purpose: * Define a FORTRAN 77 interface to the AST ShiftMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the ShiftMap class. * Routines Defined: * AST_ISASHIFTMAP * AST_SHIFTMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 18-AUG-2003 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "shiftmap.h" /* C interface to the ShiftMap class */ F77_LOGICAL_FUNCTION(ast_isashiftmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASHIFTMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAShiftMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_shiftmap)( INTEGER(NAXES), DOUBLE(SHIFT), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NAXES) GENPTR_DOUBLE(SHIFT) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_SHIFTMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astShiftMap( *NAXES, SHIFT, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/xml.h0000664000175000017500000004315713004147321010212 00000000000000#if !defined( XML_INCLUDED ) /* Include this file only once */ #define XML_INCLUDED /* *+ * Name: * xml.h * Type: * C include file. * Purpose: * Define the interface to the AST xml module * Invocation: * #include "xml.h" * Description: * This include file defines the interface to the internal xml module * used by the AST library and provides the type definitions, function * prototypes and macros, etc. needed to use this module. * Inheritance: * The xml module is not a class and does not inherit. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-OCT-2003 (DSB): * Original version. * 12-JAN-2004 (DSB): * Major revisions. */ /* Constant Values. */ /* ================ */ /* These constants are used as identifiers for the different classes of XML object defined in this file. They are purposefully obscure to reduce the possibility of random integer values being incorrectly interpreted as valid XML types */ #define AST__XMLBAD 0 /* Id for an uninitialised XmlObject */ #define AST__XMLOBJECT 198263577 /* Id for XmlObject structure */ #define AST__XMLELEM 182874779 /* Id for XmlElement structure */ #define AST__XMLATTR 837746634 /* Id for XmlAttribute structure */ #define AST__XMLCDATA 293854662 /* Id for XmlCDdataSection structure */ #define AST__XMLCOM 748737648 /* Id for XmlComment structure */ #define AST__XMLPI 983763553 /* Id for XmlPI structure */ #define AST__XMLNAME 236756469 /* Id for XmlNamespace structure */ #define AST__XMLDOC 356274395 /* Id for XmlDocument structure */ #define AST__XMLPRO 743682474 /* Id for XmlPrologue structure */ #define AST__XMLDEC 987546328 /* Id for XmlDeclPI structure */ #define AST__XMLDTD 874673747 /* Id for XmlDTDec structure */ #define AST__XMLWHITE 675849952 /* Id for XmlWhite structure */ #define AST__XMLBLACK 347657863 /* Id for XmlBlack structure */ /* The following constants refer to "interfaces", not "classes". */ #define AST__XMLCHAR 456739289 /* Id for XmlCharData structure */ #define AST__XMLCONT 673882993 /* Id for XmlContentItem structure */ #define AST__XMLMISC 358768954 /* Id for XmlMiscItem structure */ #define AST__XMLPAR 874366235 /* Id for XmlParent structure */ /* Define constants used to size global arrays in this module. */ #define AST__XML_GETTAG_BUFF_LEN 200 /* Type Definitions. */ /* ================= */ /* Pre-define types so they can be used within structure definitions. */ typedef struct AstXmlObject AstXmlObject; typedef struct AstXmlAttribute AstXmlAttribute; typedef struct AstXmlNamespace AstXmlNamespace; typedef struct AstXmlElement AstXmlElement; typedef struct AstXmlBlack AstXmlBlack; typedef struct AstXmlWhite AstXmlWhite; typedef struct AstXmlCDataSection AstXmlCDataSection; typedef struct AstXmlComment AstXmlComment; typedef struct AstXmlPI AstXmlPI; typedef struct AstXmlDocument AstXmlDocument; typedef struct AstXmlPrologue AstXmlPrologue; typedef struct AstXmlDeclPI AstXmlDeclPI; typedef struct AstXmlDTDec AstXmlDTDec; /* The following data types define "interfaces". That is each data type corresponds to a subset of the above classes. */ /* Marks a class as "character data" */ typedef AstXmlObject AstXmlCharData; /* Marks a class as a "content item" */ typedef AstXmlObject AstXmlContentItem; /* Marks a class as a "miscalleneous item" */ typedef AstXmlObject AstXmlMiscItem; /* Marks a class as being able to own a child */ typedef AstXmlObject AstXmlParent; /* XmlObject structure. */ /* -------------------- */ /* Contains data common to all other structures */ struct AstXmlObject { AstXmlParent *parent; /* The parent which contains this XmlObject */ long int type; /* An ID giving the type of structure */ int id; /* A unique id for this object. */ }; /* XmlAttribute structure. */ /* ----------------------- */ /* Describes an XML attribute */ struct AstXmlAttribute { AstXmlObject obj; /* General information for this XmlObject */ char *name; /* The name of the attribute */ char *value; /* Attribute value */ char *prefix; /* Namespace prefix for this attribute */ }; /* XmlNamespace structure. */ /* ----------------------- */ /* Describes an XML namespace definition */ struct AstXmlNamespace { AstXmlObject obj; /* General information for this XmlObject */ char *prefix; /* Namespace prefix */ char *uri; /* Namespace URI */ }; /* XmlElement structure. */ /* --------------------- */ /* Describes an XML element */ struct AstXmlElement { AstXmlObject obj; /* General information for this XmlObject */ char *name; /* The type (name) of the element */ AstXmlAttribute **attrs; /* Ptr. to list of attributes of the element */ int nattr; /* Number of attributes in the above list */ AstXmlContentItem **items; /* Ptr. to list of items in the element's content */ int nitem; /* Number of items in above list */ char *defns; /* Default Namespace URI for element content */ char *prefix; /* Namespace prefix for this element */ AstXmlNamespace **nsprefs; /* Ptr. to list of new Namespaces defined by this element */ int nnspref; /* Number of Namespaces in above list */ int complete; /* Have the contents of the element been read? */ }; /* XmlBlack structure. */ /* ---------------------- */ /* Describes character data containing at least one non-blank character. */ struct AstXmlBlack { AstXmlObject obj; /* General information for this XmlObject */ char *text; /* The character data */ }; /* XmlWhite structure. */ /* ------------------- */ /* Describes character data containing no one non-blank characters. */ struct AstXmlWhite { AstXmlObject obj; /* General information for this XmlObject */ char *text; /* The white character data */ }; /* XmlCDataSection structure. */ /* ----------------------- */ /* Describes an XML CDATA section */ struct AstXmlCDataSection { AstXmlObject obj; /* General information for this XmlObject */ char *text; /* The text of the cdata section */ }; /* XmlComment structure. */ /* --------------------- */ /* Describes an XML CDATA section */ struct AstXmlComment { AstXmlObject obj; /* General information for this XmlObject */ char *text; /* The text of the comment */ }; /* XmlPI structure. */ /* ---------------- */ /* Describes an XML processing instruction */ struct AstXmlPI { AstXmlObject obj; /* General information for this XmlObject */ char *target; /* The target of the processing instruction */ char *text; /* The text of the processing instruction */ }; /* XmlDocument structure. */ /* ---------------------- */ /* Describes an entire XML document */ struct AstXmlDocument { AstXmlObject obj; /* General information for this XmlObject */ AstXmlPrologue *prolog; /* Pointer to document prologue */ AstXmlElement *root; /* Pointer to root element */ AstXmlMiscItem **epilog; /* List of XmlObjects forming the document epilogue */ int nepi; /* No of XmlObjects pointers in "epilogue" */ AstXmlElement *current; /* Pointer to element being read */ }; /* XmlPrologue structure. */ /* ---------------------- */ /* Describes an XML document prologue */ struct AstXmlPrologue { AstXmlObject obj; /* General information for this XmlObject */ AstXmlDeclPI *xmldecl; /* Pointer to XML declaration PI */ AstXmlMiscItem **misc1; /* Group of of miscalleneous XmlObjects pointers */ int nmisc1; /* No of XmlObjects pointers in "misc1" */ AstXmlDTDec *dtdec; /* Pointer to Document Type Declaration */ AstXmlMiscItem **misc2; /* Group of of miscalleneous XmlObjects pointers */ int nmisc2; /* No of XmlObjects pointers in "misc2" */ }; /* XmlDecPI structure. */ /* ------------------- */ /* Describes an XML declaration PI */ struct AstXmlDeclPI { AstXmlObject obj; /* General information for this XmlObject */ char *text; /* The text of the XML declaration */ }; /* XmlDTDec structure. */ /* ------------------- */ /* Describes a data type declaration */ struct AstXmlDTDec { AstXmlObject obj; /* General information for this XmlObject */ char *name; /* Document type name */ char *external; /* External ID */ char *internal; /* Internal declarations */ }; #if defined(THREAD_SAFE) && defined(astCLASS) /* Define a structure holding all data items that are global within the xml.c file. */ typedef struct AstXmlGlobals { int Next_ID; char GetTag_Buff[ AST__XML_GETTAG_BUFF_LEN + 1 ]; } AstXmlGlobals; #endif /* Function prototypes. */ /* ==================== */ AstXmlAttribute *astXmlCheckAttribute_( void *, int, int * ); AstXmlBlack *astXmlCheckBlack_( void *, int, int * ); AstXmlCDataSection *astXmlCheckCDataSection_( void *, int, int * ); AstXmlComment *astXmlCheckComment_( void *, int, int * ); AstXmlContentItem *astXmlGetItem_( AstXmlElement *, int, int * ); AstXmlDTDec *astXmlCheckDTDec_( void *, int, int * ); AstXmlDeclPI *astXmlCheckDeclPI_( void *, int, int * ); AstXmlDocument *astXmlCheckDocument_( void *, int, int * ); AstXmlElement *astXmlAddElement_( AstXmlElement *, const char *, const char *, int * ); AstXmlElement *astXmlCheckElement_( void *, int, int * ); AstXmlParent *astXmlGetParent_( AstXmlObject *, int * ); AstXmlObject *astXmlGetRoot_( AstXmlObject *, int * ); AstXmlElement *astXmlReadDocument_( AstXmlDocument **, int (*)( AstXmlElement *, int * ), int, char (*)( void *, int * ), void *, int * ); AstXmlNamespace *astXmlCheckNamespace_( void *, int, int * ); AstXmlObject *astXmlCopy_( AstXmlObject *, int * ); AstXmlObject *astXmlCheckObject_( void *, int, int * ); AstXmlPI *astXmlCheckPI_( void *, int, int * ); AstXmlPrologue *astXmlCheckPrologue_( void *, int, int * ); AstXmlWhite *astXmlCheckWhite_( void *, int, int * ); AstXmlCharData *astXmlCheckCharData_( void *, int, int * ); AstXmlContentItem *astXmlCheckContentItem_( void *, int, int * ); AstXmlMiscItem *astXmlCheckMiscItem_( void *, int, int * ); AstXmlParent *astXmlCheckParent_( void *, int, int * ); const char *astXmlFormat_( AstXmlObject *, int * ); const char *astXmlGetAttributeValue_( AstXmlElement *, const char *, int * ); const char *astXmlGetName_( AstXmlObject *, int * ); const char *astXmlGetTag_( AstXmlObject *, int, int * ); const char *astXmlGetType_( AstXmlObject *, int * ); const char *astXmlGetURI_( AstXmlObject *, int * ); const char *astXmlGetValue_( AstXmlObject *, int, int * ); const char *astXmlShow_( AstXmlObject *, int * ); int astXmlCheckType_( void *, long int, int * ); int astXmlGetNattr_( AstXmlElement *, int * ); int astXmlGetNitem_( AstXmlElement *, int * ); void *astXmlAnnulTree_( AstXmlObject *, int * ); void *astXmlAnnul_( AstXmlObject *, int * ); void *astXmlDelete_( void *, int * ); void astXmlAddAttr_( AstXmlElement *, const char *, const char *, const char *, int * ); void astXmlAddCDataSection_( AstXmlElement *, const char *, int * ); void astXmlAddCharData_( AstXmlParent *, int, const char *, int * ); void astXmlAddComment_( AstXmlParent *, int, const char *, int * ); void astXmlAddPI_( AstXmlParent *, int, const char *, const char *, int * ); void astXmlAddURI_( AstXmlElement *, const char *, const char *, int * ); void astXmlInsertElement_( AstXmlElement *, AstXmlElement *, int * ); void astXmlPurge_( AstXmlParent *, int * ); void astXmlRemoveAttr_( AstXmlElement *, const char *, const char *, int * ); void astXmlRemoveItem_( AstXmlContentItem *, int * ); void astXmlRemoveURI_( AstXmlElement *, const char *, int * ); void astXmlSetXmlDec_( AstXmlDocument *, const char *, int * ); void astXmlSetDTDec_( AstXmlDocument *, const char *, const char *, const char *, int * ); #if defined(THREAD_SAFE) && defined(astCLASS) void astInitXmlGlobals_( AstXmlGlobals * ); #else #ifdef DEBUG int astXmlTrace_( int ); #endif #endif /* Function interfaces. */ /* ==================== */ /* These wrap up the functions defined by this module. */ #define astXmlGetType(this) astXmlGetType_(this,STATUS_PTR) #define astXmlCheckAttribute(this,nullok) astXmlCheckAttribute_(this,nullok,STATUS_PTR) #define astXmlCheckBlack(this,nullok) astXmlCheckBlack_(this,nullok,STATUS_PTR) #define astXmlCheckCDataSection(this,nullok) astXmlCheckCDataSection_(this,nullok,STATUS_PTR) #define astXmlCheckCharData(this,nullok) astXmlCheckCharData_(this,nullok,STATUS_PTR) #define astXmlCheckComment(this,nullok) astXmlCheckComment_(this,nullok,STATUS_PTR) #define astXmlCheckContentItem(this,nullok) astXmlCheckContentItem_(this,nullok,STATUS_PTR) #define astXmlCheckDTDec(this,nullok) astXmlCheckDTDec_(this,nullok,STATUS_PTR) #define astXmlCheckDeclPI(this,nullok) astXmlCheckDeclPI_(this,nullok,STATUS_PTR) #define astXmlCheckDocument(this,nullok) astXmlCheckDocument_(this,nullok,STATUS_PTR) #define astXmlCheckElement(this,nullok) astXmlCheckElement_(this,nullok,STATUS_PTR) #define astXmlCheckMiscItem(this,nullok) astXmlCheckMiscItem_(this,nullok,STATUS_PTR) #define astXmlCheckNamespace(this,nullok) astXmlCheckNamespace_(this,nullok,STATUS_PTR) #define astXmlCheckObject(this,nullok) astXmlCheckObject_(this,nullok,STATUS_PTR) #define astXmlCheckPI(this,nullok) astXmlCheckPI_(this,nullok,STATUS_PTR) #define astXmlCheckParent(this,nullok) astXmlCheckParent_(this,nullok,STATUS_PTR) #define astXmlCheckPrologue(this,nullok) astXmlCheckPrologue_(this,nullok,STATUS_PTR) #define astXmlCheckWhite(this,nullok) astXmlCheckWhite_(this,nullok,STATUS_PTR) #define astXmlAddAttr(elem,name,value,prefix) astXmlAddAttr_(astXmlCheckElement(elem,0),name,value,prefix,STATUS_PTR) #define astXmlAddURI(elem,prefix,uri) astXmlAddURI_(astXmlCheckElement(elem,0),prefix,uri,STATUS_PTR) #define astXmlAnnul(this) astXmlAnnul_(astXmlCheckObject(this,1),STATUS_PTR) #define astXmlDelete(this) astXmlDelete_(this,STATUS_PTR) #define astXmlAnnulTree(this) astXmlAnnulTree_(astXmlCheckObject(this,1),STATUS_PTR) #define astXmlAddCDataSection(this,text) astXmlAddCDataSection_(astXmlCheckElement(this,0),text,STATUS_PTR) #define astXmlAddCharData(this,where,text) astXmlAddCharData_(astXmlCheckParent(this,0),where,text,STATUS_PTR) #define astXmlAddComment(this,where,text) astXmlAddComment_(astXmlCheckParent(this,0),where,text,STATUS_PTR) #define astXmlAddElement(this,name,prefix) astXmlAddElement_(astXmlCheckElement(this,1),name,prefix,STATUS_PTR) #define astXmlAddPI(this,where,target,text) astXmlAddPI_(astXmlCheckParent(this,0),where,target,text,STATUS_PTR) #define astXmlGetParent(this) astXmlGetParent_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlGetRoot(this) astXmlGetRoot_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlGetName(this) astXmlGetName_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlGetValue(this,report) astXmlGetValue_(astXmlCheckObject(this,0),report,STATUS_PTR) #define astXmlGetAttributeValue(this,name) astXmlGetAttributeValue_(astXmlCheckElement(this,0),name,STATUS_PTR) #define astXmlGetNattr(this) astXmlGetNattr_(astXmlCheckElement(this,0),STATUS_PTR) #define astXmlGetNitem(this) astXmlGetNitem_(astXmlCheckElement(this,0),STATUS_PTR) #define astXmlGetItem(this,item) astXmlGetItem_(astXmlCheckElement(this,0),item,STATUS_PTR) #define astXmlGetAttributeValue(this,name) astXmlGetAttributeValue_(astXmlCheckElement(this,0),name,STATUS_PTR) #define astXmlGetTag(this,opening) astXmlGetTag_(astXmlCheckObject(this,0),opening,STATUS_PTR) #define astXmlGetURI(this) astXmlGetURI_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlFormat(this) astXmlFormat_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlShow(this) astXmlShow_(astXmlCheckObject(this,0),STATUS_PTR) #define astXmlRemoveItem(this) astXmlRemoveItem_(astXmlCheckContentItem(this,0),STATUS_PTR) #define astXmlRemoveAttr(this,name,prefix) astXmlRemoveAttr_(astXmlCheckElement(this,0),name,prefix,STATUS_PTR) #define astXmlRemoveURI(this,prefix) astXmlRemoveURI_(astXmlCheckElement(this,0),prefix,STATUS_PTR) #define astXmlReadDocument(doc,is_wanted,skip,source,data) astXmlReadDocument_(doc,is_wanted,skip,source,data,STATUS_PTR) #define astXmlInsertElement(this,elem) astXmlInsertElement_(astXmlCheckElement(this,0),astXmlCheckElement(elem,0),STATUS_PTR) #define astXmlPurge(this) astXmlPurge_(astXmlCheckParent(this,1),STATUS_PTR) #define astXmlSetXmlDec(this,text) astXmlSetXmlDec_(astXmlCheckDocument(this,0),text,STATUS_PTR) #define astXmlSetDTDec(this,text1,text2,text3) astXmlSetDTDec_(astXmlCheckDocument(this,0),text1,text2,text3,STATUS_PTR) #define astXmlCheckType(this,type) astXmlCheckType_(this,type,STATUS_PTR) #define astXmlCopy(this) astXmlCopy_(astXmlCheckObject(this,1),STATUS_PTR) #ifdef DEBUG #define astXmlTrace(show) astXmlTrace_(show) #endif #endif ast-8.3.0/fstcschan.c0000664000175000017500000001010413004147321011343 00000000000000/* *+ * Name: * fstcschan.c * Purpose: * Define a FORTRAN 77 interface to the AST StcsChan class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the StcsChan class. * Routines Defined: * AST_STCSCHAN * AST_ISASTCSCHAN * Copyright: * Copyright (C) 2008 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (JAC,UCLan) * History: * 18-DEC-2008 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "channel.h" /* Provides wrapper functions */ #include "stcschan.h" /* C interface to the StcsChan class */ #include /* Prototypes for external functions. */ /* ================================== */ /* This is the null function defined by the FORTRAN interface in fobject.c. */ F77_SUBROUTINE(ast_null)( void ); /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_INTEGER_FUNCTION(ast_stcschan)( void (* SOURCE)(), void (* SINK)(), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; const char *(* source)( void ); int i; void (* sink)( const char * ); astAt( "AST_STCSCHAN", NULL, 0 ); astWatchSTATUS( /* Set the source and sink function pointers to NULL if a pointer to the null routine AST_NULL has been supplied. */ source = (const char *(*)( void )) SOURCE; if ( source == (const char *(*)( void )) F77_EXTERNAL_NAME(ast_null) ) { source = NULL; } sink = (void (*)( const char * )) SINK; if ( sink == (void (*)( const char * )) F77_EXTERNAL_NAME(ast_null) ) { sink = NULL; } options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astStcsChanFor( source, astSourceWrap, sink, astSinkWrap, "%s", options ) ); astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isastcschan)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASTCSCHAN", NULL, 0 ); astWatchSTATUS( RESULT = astIsAStcsChan( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } ast-8.3.0/fspecframe.c0000664000175000017500000000764413004147321011521 00000000000000/* *+ * Name: * fspecframe.c * Purpose: * Define a FORTRAN 77 interface to the AST SpecFrame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the SpecFrame class. * Routines Defined: * AST_ISASPECFRAME * AST_SPECFRAME * AST_SETREFPOS * AST_GETREFPOS * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 20-NOV-2002 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "specframe.h" /* C interface to the SpecFrame class */ F77_LOGICAL_FUNCTION(ast_isaspecframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASPECFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsASpecFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_specframe)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_SPECFRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astSpecFrame( "%s", options ) ); astFree( options ); ) return RESULT; } F77_SUBROUTINE(ast_getrefpos)( INTEGER(THIS), INTEGER(FRM), DOUBLE(LON), DOUBLE(LAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(FRM) GENPTR_DOUBLE(LON) GENPTR_DOUBLE(LAT) astAt( "AST_GETREFPOS", NULL, 0 ); astWatchSTATUS( astGetRefPos( astI2P( *THIS ), astI2P( *FRM ), LON, LAT ); ) } F77_SUBROUTINE(ast_setrefpos)( INTEGER(THIS), INTEGER(FRM), DOUBLE(LON), DOUBLE(LAT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(FRM) GENPTR_DOUBLE(LON) GENPTR_DOUBLE(LAT) astAt( "AST_SETREFPOS", NULL, 0 ); astWatchSTATUS( astSetRefPos( astI2P( *THIS ), astI2P( *FRM ), *LON, *LAT ); ) } ast-8.3.0/timeframe.c0000664000175000017500000074370513004147321011364 00000000000000/* *class++ * Name: * TimeFrame * Purpose: * Time coordinate system description. * Constructor Function: c astTimeFrame f AST_TIMEFRAME * Description: * A TimeFrame is a specialised form of one-dimensional Frame which * represents various coordinate systems used to describe positions in * time. * * A TimeFrame represents a moment in time as either an Modified Julian * Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, * as determined by the System attribute. Optionally, a zero point can be * specified (using attribute TimeOrigin) which results in the TimeFrame * representing time offsets from the specified zero point. * * Even though JD and MJD are defined as being in units of days, the * TimeFrame class allows other units to be used (via the Unit attribute) * on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 * hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs * can be described in units other than the usual years. Besselian epoch * are always represented in units of (tropical) years. * * The TimeScale attribute allows the time scale to be specified (that * is, the physical process used to define the rate of flow of time). * MJD, JD and Julian epoch can be used to represent a time in any * supported time scale. However, Besselian epoch may only be used with the * "TT" (Terrestrial Time) time scale. The list of supported time scales * includes universal time and siderial time. Strictly, these represent * angles rather than time scales, but are included in the list since * they are in common use and are often thought of as time scales. * * When a time value is formatted it can be formated either as a simple * floating point value, or as a Gregorian date (see the Format * attribute). * Inheritance: * The TimeFrame class inherits from the Frame class. * Attributes: * In addition to those attributes common to all Frames, every * TimeFrame also has the following attributes: * * - AlignTimeScale: Time scale in which to align TimeFrames * - LTOffset: The offset of Local Time from UTC, in hours. * - TimeOrigin: The zero point for TimeFrame axis values * - TimeScale: The timescale used by the TimeFrame * * Several of the Frame attributes inherited by the TimeFrame class * refer to a specific axis of the Frame (for instance Unit(axis), * Label(axis), etc). Since a TimeFrame is strictly one-dimensional, * it allows these attributes to be specified without an axis index. * So for instance, "Unit" is allowed in place of "Unit(1)". * Functions: c In addition to those functions applicable to all Frames, the c following functions may also be applied to all TimeFrames: f In addition to those routines applicable to all Frames, the f following routines may also be applied to all TimeFrames: * c - astCurrentTime: Return the current system time f - AST_CURRENTTIME: Return the current system time * 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 * . * Authors: * NG: Norman Gray (Starlink) * DSB: David Berry (Starlink) * History: * XX-Aug-2003 (NG): * Original version, drawing heavily on specframe.c. * 20-MAY-2005 (NG): * Merged into main AST system. * 25-MAY-2005 (DSB): * Extensive modifications to add extra timescales, unit support, * support for relative times, etc, and to make it more like the * other AST Frame classes. * 12-AUG-2005 (DSB): * Remove ClockLon and ClockLat attributes. Use the new ObsLon and * ObsLat attributes in the parent Frame class instead. Note, for * backward compatibility the public attribute accessors and the * astLoadTimeFrame functions still recogonise ClockLon and ClockLat, * but use the ObsLat/ObsLon attributes internally. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 29-JUN-2006 (DSB): * - Activate astAbbrev function for abbreviating leading fields in * plot labels. * - Include TimeOrigin in default Label. * 30-JUN-2006 (DSB): * When splitting a date/time string into fields, allow each field * to include a decimal point. * 30-JUN-2006 (DSB): * Allow astAbbrev to have a null "str1" value. * 16-OCT-2006 (DSB): * Allow conversions between UTC and UT1 (using the new Frame attribute * 1-NOV-2006 (DSB): * Correct sign of longitude passed to TimeMap contrutcorss in * function MakeMap. * 31-JAN-2007 (DSB): * Modified so that a TimeFrame can be used as a template to find a * TimeFrame contained within a CmpFrame. This involves changes in * Match and the removal of the local versions of SetMaxAxes and * SetMinAxes. * 3-SEP-2007 (DSB): * In SubFrame, since AlignSystem is extended by the TimeFrame class * it needs to be cleared before invoking the parent SubFrame * method in cases where the result Frame is not a TimeFrame. * 2-OCT-2007 (DSB): * In Overlay, clear AlignSystem as well as System before calling * the parent overlay method. * 2-OCT-2007 (DSB): * Added "LT" (Local Time) time scale. * 9-DEC-2008 (DSB): * Ensure Format string pointer is used correctly. * 19-JAN-2009 (DSB): * Ensure "" is returned by astFormat if the axis value is bad. * 31-MAR-2009 (DSB): * Extend TimeFrame "iso" Format to allow it to specify the character to * place between the time and date strings. * 15-APR-2009 (DSB): * Increase the number of nice calendar time axis gaps allowed by * the Gap function. Previously, there was a jump from 1 day to 1 * year making it difficult to plot calendar axes covering time * ranges of the order of 0.5 to 2 years. Now, nice numbers of days * are allowed as intermediate gaps. Since months do not all have * the same number of days, this means that the day number at major * ticks will bounce around a bit. * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. * 16-APR-2015 (DSB): * Add more choices when chosing gaps on time axes. * 17-APR-2015 (DSB): * - Added Centre. * - Remove some "set but unused" variables. * 21-APR-2016 (DSB): * - Over-ride astFields. *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 TimeFrame /* Define the first and last acceptable System values. */ #define FIRST_SYSTEM AST__MJD #define LAST_SYSTEM AST__BEPOCH /* Define the first and last acceptable TimeScale values. */ #define FIRST_TS AST__TAI #define LAST_TS AST__LT /* The supported time scales fall into two groups. Time scales in the first group depend on the clock position. That is, transformation between a time scale in one group and a timescale in the other group requires the clock position, as does transformation between two time scales within the first group. Define a macro which tests if a given timescale belongs to the first group. */ #define CLOCK_SCALE(ts) \ ( ( ts == AST__LMST || \ ts == AST__LAST || \ ts == AST__TDB || \ ts == AST__TCB ) ? 1 : 0 ) /* Define a macro which tests if a given timescale requires a Dut1 value in order to convert from the timescale to UTC. */ #define DUT1_SCALE(ts) \ ( ( ts == AST__LMST || \ ts == AST__LAST || \ ts == AST__GMST || \ ts == AST__UT1 ) ? 1 : 0 ) /* Define a macro which tests if a given timescale requires a LTOffset value in order to convert from the timescale to UTC. */ #define LTOFFSET_SCALE(ts) \ ( ( ts == AST__LT ) ? 1 : 0 ) /* The Unix epoch (00:00:00 UTC 1 January 1970 AD) as an absolute MJD in the UTC timescale. */ #define UNIX_EPOCH 40587.0 /* 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 "unit.h" /* Units management facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "timemap.h" /* Time coordinate Mappings */ #include "frame.h" /* Parent Frame class */ #include "timeframe.h" /* Interface definition for this class */ #include "mapping.h" /* Coordinate Mappings */ #include "cmpmap.h" /* Compound Mappings */ #include "unitmap.h" /* Unit Mappings */ #include "shiftmap.h" /* Shift of origins */ #include "pal.h" /* SlaLib interface */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* 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 used or extended by this class. */ static AstSystemType (* parent_getalignsystem)( AstFrame *, int * ); static AstSystemType (* parent_getsystem)( AstFrame *, int * ); static double (* parent_centre)( AstFrame *, int, double, double, int * ); static double (* parent_gap)( AstFrame *, int, double, int *, int * ); static const char *(* parent_abbrev)( AstFrame *, int, const char *, const char *, const char *, int * ); static const char *(* parent_format)( AstFrame *, int, double, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static const char *(* parent_getdomain)( AstFrame *, int * ); static const char *(* parent_getlabel)( AstFrame *, int, int * ); static const char *(* parent_getsymbol)( AstFrame *, int, int * ); static const char *(* parent_gettitle)( AstFrame *, int * ); static const char *(* parent_getunit)( AstFrame *, int, int * ); static double (* parent_getepoch)( AstFrame *, int * ); static int (* parent_fields)( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); static int (* parent_match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int (* parent_subframe)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static int (* parent_unformat)( AstFrame *, int, const char *, double *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_clearsystem)( AstFrame *, int * ); static void (* parent_overlay)( AstFrame *, const int *, AstFrame *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_setsystem)( AstFrame *, AstSystemType, int * ); static void (* parent_setunit)( AstFrame *, int, const char *, int * ); /* The Unix epoch (00:00:00 UTC 1 January 1970 AD) as an absolute MJD in the TAI timescale. */ static double tai_epoch; /* 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->Format_Buff[ 0 ] = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->GetLabel_Buff[ 0 ] = 0; \ globals->GetSymbol_Buff[ 0 ] = 0; \ globals->GetTitle_Buff[ 0 ] = 0; \ /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(TimeFrame) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(TimeFrame,Class_Init) #define class_vtab astGLOBAL(TimeFrame,Class_Vtab) #define format_buff astGLOBAL(TimeFrame,Format_Buff) #define getattrib_buff astGLOBAL(TimeFrame,GetAttrib_Buff) #define getlabel_buff astGLOBAL(TimeFrame,GetLabel_Buff) #define getsymbol_buff astGLOBAL(TimeFrame,GetSymbol_Buff) #define gettitle_buff astGLOBAL(TimeFrame,GetTitle_Buff) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffers for strings returned by various functions. */ static char getattrib_buff[ AST__TIMEFRAME_GETATTRIB_BUFF_LEN + 1 ]; static char format_buff[ AST__TIMEFRAME_FORMAT_BUFF_LEN + 1 ]; static char getlabel_buff[ AST__TIMEFRAME_GETLABEL_BUFF_LEN + 1 ]; static char getsymbol_buff[ AST__TIMEFRAME_GETSYMBOL_BUFF_LEN + 1 ]; static char gettitle_buff[ AST__TIMEFRAME_GETTITLE_BUFF_LEN + 1 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstTimeFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #endif /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *MakeMap( AstTimeFrame *, AstSystemType, AstSystemType, AstTimeScaleType, AstTimeScaleType, double, double, const char *, const char *, const char *, int * ); static AstSystemType GetAlignSystem( AstFrame *, int * ); static AstSystemType SystemCode( AstFrame *, const char *, int * ); static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); static AstTimeScaleType TimeScaleCode( const char *, int * ); static const char *DefUnit( AstSystemType, const char *, const char *, int * ); static const char *Format( AstFrame *, int, double, int * ); static const char *GetDomain( AstFrame *, 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 *SystemLabel( AstSystemType, int * ); static const char *SystemString( AstFrame *, AstSystemType, int * ); static const char *TimeScaleString( AstTimeScaleType, int * ); static double CurrentTime( AstTimeFrame *, int * ); static double FromMJD( AstTimeFrame *, double, int * ); static double GetEpoch( AstFrame *, int * ); static double GetTimeOriginCur( AstTimeFrame *, int * ); static double ToMJD( AstSystemType, double, int * ); static double ToUnits( AstTimeFrame *, const char *, double, const char *, int * ); static int DateFormat( const char *, int *, char *, int * ); static int Fields( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); static int GetActiveUnit( AstFrame *, int * ); static int MakeTimeMapping( AstTimeFrame *, AstTimeFrame *, AstTimeFrame *, int, AstMapping **, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int TestActiveUnit( AstFrame *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void OriginScale( AstTimeFrame *, AstTimeScaleType, const char *, int * ); static void OriginSystem( AstTimeFrame *, AstSystemType, const char *, int * ); static void Overlay( AstFrame *, const int *, AstFrame *, int * ); static void SetUnit( AstFrame *, int, const char *, int * ); static void VerifyAttrs( AstTimeFrame *, const char *, const char *, const char *, int * ); static AstMapping *ToMJDMap( AstSystemType, double, int * ); static int Unformat( AstFrame *, int, const char *, double *, int * ); static const char *Abbrev( AstFrame *, int, const char *, const char *, const char *, int * ); static double Centre( AstFrame *, int, double, double, int * ); static double Gap( AstFrame *, int, double, int *, int * ); static AstSystemType GetSystem( AstFrame *, int * ); static void SetSystem( AstFrame *, AstSystemType, int * ); static void ClearSystem( AstFrame *, int * ); static double GetTimeOrigin( AstTimeFrame *, int * ); static int TestTimeOrigin( AstTimeFrame *, int * ); static void ClearTimeOrigin( AstTimeFrame *, int * ); static void SetTimeOrigin( AstTimeFrame *, double, int * ); static double GetLTOffset( AstTimeFrame *, int * ); static int TestLTOffset( AstTimeFrame *, int * ); static void ClearLTOffset( AstTimeFrame *, int * ); static void SetLTOffset( AstTimeFrame *, double, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static AstTimeScaleType GetAlignTimeScale( AstTimeFrame *, int * ); static int TestAlignTimeScale( AstTimeFrame *, int * ); static void ClearAlignTimeScale( AstTimeFrame *, int * ); static void SetAlignTimeScale( AstTimeFrame *, AstTimeScaleType, int * ); static AstTimeScaleType GetTimeScale( AstTimeFrame *, int * ); static int TestTimeScale( AstTimeFrame *, int * ); static void ClearTimeScale( AstTimeFrame *, int * ); static void SetTimeScale( AstTimeFrame *, AstTimeScaleType, int * ); /* 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 Frame axis value by skipping leading fields. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *Abbrev( AstFrame *this, int axis, const char *fmt, * const char *str1, const char *str2, int *status ) * Class Membership: * TimeFrame member function (over-rides the astAbbrev protected * method inherited from the Frame class). * Description: * This function compares two Frame axis values that have been * formatted (using astFormat) and determines if they have any * redundant leading fields (i.e. leading fields in common which * can be suppressed when tabulating the values or plotting them on * the axis of a graph). * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which the values have been * formatted (axis numbering starts at zero for the first axis). * fmt * Pointer to a constant null-terminated string containing the * format specification used to format the two values. * str1 * Pointer to a constant null-terminated string containing the * first formatted value. If this is null, the returned pointer * points to the start of the final field in str2. * str2 * Pointer to a constant null-terminated string containing the * second formatted value. * 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 Frame axis. * - A pointer to the start of "str2" will be returned if this * function is invoked with the global error status set, or if it * should fail for any reason. *- */ /* Local Variables: */ const char *p1; const char *p2; const char *result; int df; int nc1; int nc2; int ndp; /* Initialise. */ result = str2; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index. */ astValidateAxis( this_frame, axis, 1, "astAbbrev" ); /* Use the parent astAbbrev function unless the Format attribute indicates that axis values are to be formatted as multi-field date/time strings. */ df = DateFormat( fmt, &ndp, NULL, status ); if( !df ) { result = (*parent_abbrev)( this_frame, axis, fmt, str1, str2, status ); /* Otherwise, if no "str1" string was supplied find the start of the last field in "str2". */ } else if( !str1 ){ /* Initialise a pointer to the start of the next field in the "str2" string (skip leading spaces). */ p2 = str2; while( *p2 && isspace( *p2 ) ) p2++; /* Check the entire string, saving the start of the next field as the returned pointer. */ while( *p2 ) { result = p2; /* Each field in a date/time field consists of digits only (and maybe a decimal point). Find the number of leading digits/dots in this field and increment the point to the following character (the first delimiter character). */ p2 += strspn( p2, "0123456789." ); /* Skip inter-field (non-numeric) delimiters. */ p2 += strcspn( p2, "0123456789." ); } /* Otherwise, if an "str1" string was supplied find the start of the first differing field in "str2". */ } else { /* Initialise pointers to the start of the next field in each string (skip leading spaces). */ p1 = str1; p2 = str2; while( *p1 && isspace( *p1 ) ) p1++; while( *p2 && isspace( *p2 ) ) p2++; /* Check the entire string */ result = p2; while( *p1 && *p2 ) { /* Each field in a date/time field consists of digits only (and maybe a decimal point). Find the number of leading digits/dots in each string */ nc1 = strspn( p1, "0123456789." ); nc2 = strspn( p2, "0123456789." ); /* If the next field has different lengths in the two strings, or of the content of the fields differ, break out of th eloop, leaving "result" pointing to the start of the current field. */ if( nc1 != nc2 || strncmp( p1, p2, nc1 ) ) { break; /* If the next field is identical in the two strings, skip to the character following the end of the field. */ } else { p1 += nc1; p2 += nc2; /* Skip inter-field (non-numeric) delimiters. */ p1 += strcspn( p1, "0123456789." ); p2 += strcspn( p2, "0123456789." ); } /* Prepare to check the next field. */ result = p2; } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = str2; /* Return the result. */ return result; } 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 "timeframe.h" * double Centre( AstFrame *this_frame, int axis, double value, * double gap, int *status ) * Class Membership: * TimeFrame 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: * - The supplied axis value is returned if the supplied gap size is * zero, or if this function is invoked with the global error status * set, or if it should fail for any reason. */ /* Local Variables: */ AstTimeFrame *this; char *date1; char *date2; char *f1; char *f2; char *fres; char *p1; char *p2; char *pres; const char *fmt; const char *date; double result; int df; int fmod; int nc1; int nc2; int ndp; int nres; int v1; int v2; /* Initialise. */ result = value; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index. */ astValidateAxis( this_frame, axis, 1, "astCentre" ); /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Use the parent astCentre function unless the Format attribute indicates that axis values are to be formatted as multi-field date/time strings. */ fmt = astGetFormat( this, 0 ); df = DateFormat( fmt, &ndp, NULL, status ); if( !df ) { result = (*parent_centre)( this_frame, axis, value, gap, status ); /* Otherwise. */ } else { /* Format time values one gap above the supplied axis value and one gap below it. Take copies of each string since the astFormat buffer will be over-written by each call. */ date = astFormat( this, 0, value - gap ); if( date ) date1 = astStore( NULL, date, strlen( date ) + 1 ); date = astFormat( this, 0, value + gap ); if( date ) date2 = astStore( NULL, date, strlen( date ) + 1 ); if( astOK ) { /* Initialise a formatted version of the returned central value to be equal to "date1". */ nres = strlen( date1 ); fres = astStore( NULL, date1, nres + 1 ); /* Loop over all characters within the first date. */ fmod = 0; nc1 = 0; f1 = NULL; p1 = date1; nc2 = 0; f2 = NULL; p2 = date2; while( 1 ) { /* If we have not yet found the length of the next numerical field in date1, continue looking for it. */ if( !nc1 ) { /* If we are currently looking for the start of a numerical field, indicate we have found one if the current character is a digit. */ if( !f1 ) { if( isdigit( *p1 ) ) f1 = p1; /* If we are currently looking for the end of a numeric field, we have found the end if the current character is not a digit. */ } else { if( !isdigit( *p1 ) ) { nc1 = p1 - f1; } } /* Look at the next character */ p1++; } /* If we have not yet found the length of the next numerical field in date2, continue looking for it. */ if( !nc2 ) { /* If we are currently looking for the start of a numerical field, indicate we have found one if the current character is a digit. */ if( !f2 ) { if( isdigit( *p2 ) ) f2 = p2; /* If we are currently looking for the end of a numeric field, we have found the end if the current character is not a digit. */ } else { if( !isdigit( *p2 ) ) { nc2 = p2 - f2; } } /* Look at the next character */ p2++; } /* If we have found the next numerical field in both dates, convert them to integers. */ if( nc1 && nc2 ) { v1 = atoi( f1 ); v2 = atoi( f2 ); /* If the values are different, replace this field and all subsequent fields with zeros in the formatted version of the returned central value, and leave the loop. */ if( v1 != v2 ) { pres = fres + ( f1 - date1 ) - 1; while( *(++pres) ) { if( isdigit( *pres ) ) *pres = '0'; } fmod = 1; break; } /* Prepare to look for the next numerical field in both strings. */ nc1 = nc2 = 0; f1 = f2 = NULL; /* If either string has been exhausted, leave the loop. */ if( !*p1 || !*p2 ) break; } } /* If the formatted "nice" value was changed, unformatted it to get the returned axis value. Otherwise we rettina the returned value set earlier. */ if( fmod ) { if( astUnformat( this, 0, fres, &result ) != nres && astOK ) { astError( AST__INTER, "astCentre(%s): Error unformatting " "the central time axis value '%s' (internal AST " "programming error).", status, astClass( this ), fres ); } } /* Free resources. */ fres = astFree( fres ); } date1 = astFree( date1 ); date2 = astFree( date2 ); } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0.0; /* Return the result. */ return result; } static int DateFormat( const char *fmt, int *ndp, char *sep, int *status ){ /* * Name: * DateFormat * Purpose: * Determine if TimeFrame values should be formatted as a date. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int DateFormat( const char *fmt, int *ndp, char *sep, int *status ) * Class Membership: * TimeFrame member function * Description: * This function returns a flag indicating if the supplied Format string * requires the TimeFrame value to be formatted as a date and/or time of * day. * Parameters: * fmt * Pointer to Format string. * ndp * A pointer to an integer in which is returned a value indicating * if a time is required as well as a date. A value of -1 will be * returned in no time is required, otherwise the returned value will * equal the number of decimal places required for the seconds field. * sep * A pointer to a char in which is returned the character that * should be used to separate the date and time fields. Ignored if * NULL. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the formatted TimeFrame value should include a date. */ /* Local Variables: */ const char *c; int nc; int result; /* Initialise */ result = 0; *ndp = -1; /* Check the Format string */ if( fmt ) { /* Find the first non-white character */ c = fmt; while( *c && isspace( *c ) ) c++; /* If the first non-white character starts the string "iso" assume a date is required. If so see if a time is also required (indicated by 1 dot following) and how many seconds of precision are required (the interegr following the dot). */ if( !strncmp( c, "iso", 3 ) ) { result = 1; if( astSscanf( c, "iso.%d%n", ndp, &nc ) == 1 ) { /* Check the separate character (if any) at the end of the format string. Only "T" is allowed. A space is used if no separator is given. */ if( sep ) *sep = ( c[ nc ] == 'T' || c[ nc ] == 't' ) ? 'T' : ' '; } else { *ndp = -1; } } } return result; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * TimeFrame 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 * TimeFrame, so that the default value will subsequently be used. * Parameters: * this * Pointer to the TimeFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ char *new_attrib; /* Pointer value to new attribute name */ int len; /* Length of attrib string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* First look for axis attributes defined by the Frame class. Since a TimeFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent ClearAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); (*parent_clearattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignTimeScale. */ /* --------------- */ } else if ( !strcmp( attrib, "aligntimescale" ) ) { astClearAlignTimeScale( this ); /* ClockLat. */ /* --------- */ /* Retained for backward compatibility with older versions of AST in which TimeFrame had ClockLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( !strcmp( attrib, "clocklat" ) ) { astClearAttrib( this, "obslat" ); /* ClockLon. */ /* --------- */ /* Retained for backward compatibility with older versions of AST in which TimeFrame had ClockLon/Lat attributes (now ObsLon/Lat are used instead). */ } else if ( !strcmp( attrib, "clocklon" ) ) { astClearAttrib( this, "obslon" ); /* LTOffset. */ /* --------- */ } else if ( !strcmp( attrib, "ltoffset" ) ) { astClearLTOffset( this ); /* TimeOrigin. */ /* ---------- */ } else if ( !strcmp( attrib, "timeorigin" ) ) { astClearTimeOrigin( this ); /* TimeScale. */ /* ---------- */ } else if ( !strcmp( attrib, "timescale" ) ) { astClearTimeScale( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearSystem( AstFrame *this_frame, int *status ) { /* * Name: * ClearSystem * Purpose: * Clear the System attribute for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void ClearSystem( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astClearSystem protected * method inherited from the Frame class). * Description: * This function clears the System attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSystemType oldsys; /* System before clearing */ AstTimeFrame *this; /* Pointer to TimeFrame structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Save the original system */ oldsys = astGetSystem( this_frame ); /* Use the parent ClearSystem method to clear the System value. */ (*parent_clearsystem)( this_frame, status ); /* Do nothing more if the system has not actually changed. */ if( astGetSystem( this_frame ) != oldsys ) { /* Modify the TimeOrigin value to use the new System */ OriginSystem( this, oldsys, "astClearSystem", status ); /* Clear attributes which have system-specific defaults. */ astClearLabel( this_frame, 0 ); astClearSymbol( this_frame, 0 ); astClearTitle( this_frame ); /* If the old system was BEPOCH also clear units and timescale. This is because we need to ensure that TimeScale=TT and Unit=yr will be used in future (these are the only acceptable values for System=BEPOCH). */ if( oldsys == AST__BEPOCH ) { astClearUnit( this_frame, 0 ); astClearTimeScale( (AstTimeFrame *) this_frame ); } } } static void ClearTimeScale( AstTimeFrame *this, int *status ) { /* *+ * Name: * astClearTimeScale * Purpose: * Clear the TimeScale attribute for a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * void astClearTimeScale( AstTimeFrame *this ) * Class Membership: * TimeFrame virtual function * Description: * This function clears the TimeScale attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. *- */ /* Check the global error status. */ if ( !astOK ) return; /* If the System is currently set to BEPOCH, then the TimeScale will either be set to TT or will be unset (since SetTimeScale will not allow any other value than TT if the System is BEPOCH). Therefore, if System is BEPOCH, we will not need to modify the TimeOrigin value, since it will already be appropriate. Otherwise, we modify the TimeOrigin value stored in the TimeFrame structure to refer to the default timescale (TAI or TT). */ if( astGetSystem( this ) != AST__BEPOCH ) OriginScale( this, AST__TAI, "astClearTimeScale", status ); /* Store a bad value for the timescale in the TimeFrame structure. */ this->timescale = AST__BADTS; } static double CurrentTime( AstTimeFrame *this, int *status ){ /* *++ * Name: c astCurrentTime f AST_CURRENTTIME * Purpose: * Return the current system time. * Type: * Public virtual function. * Synopsis: c #include "timeframe.h" c double astCurrentTime( AstTimeFrame *this ) f RESULT = AST_CURRENTTIME( THIS, STATUS ) * Class Membership: * TimeFrame method. * Description: c This function f This routine * returns the current system time, represented in the form specified * by the supplied TimeFrame. That is, the returned floating point * value should be interpreted using the attribute values of the * TimeFrame. This includes System, TimeOrigin, LTOffset, TimeScale, * and Unit. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the TimeFrame. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astCurrentTime() f AST_CURRENTTIME = DOUBLE c A TimeFrame axis value representing the current system time. * Notes: * - Values of AST__BAD will be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. * - It is assumes that the system time (returned by the C time() * function) follows the POSIX standard, representing a continuous * monotonic increasing count of SI seconds since the epoch 00:00:00 * UTC 1 January 1970 AD (equivalent to TAI with a constant offset). * Resolution is one second. * - An error will be reported if the TimeFrame has a TimeScale value * which cannot be converted to TAI (e.g. "angular" systems such as * UT1, GMST, LMST and LAST). * - Any inaccuracy in the system clock will be reflected in the value * returned by this function. *-- */ /* Local Constants: */ /* Local Variables: */ AstMapping *map; double result; double systime; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get a Mapping from the system time (TAI seconds relative to "tai_epoch") to the system represented by the supplied TimeFrame. */ map = MakeMap( this, AST__MJD, astGetSystem( this ), AST__TAI, astGetTimeScale( this ), tai_epoch, astGetTimeOrigin( this ), "s", astGetUnit( this, 0 ), "astCurrentTime", status ); if( !map ) { astError( AST__INCTS, "astCurrentTime(%s): Cannot convert the " "current system time to the required timescale (%s).", status, astGetClass( this ), TimeScaleString( astGetTimeScale( this ), status ) ); /* Get the system time. The "time" function returns a "time_t" which may be encoded in any way. We use "difftime" to convert this into a floating point number of seconds by taking the difference between the current time and zero time. This assumes nothing about the structure of a "time_t" except that zero can be cast into a time_t representing the epoch. */ } else { systime = difftime( time( NULL ), (time_t) 0 ); /* Use the Mapping to convert the time into the requied system. */ astTran1( map, 1, &systime, 1, &result ); /* Free resources */ map = astAnnul( map ); } /* Set result to AST__BAD if an error occurred. */ if( !astOK ) result = AST__BAD; /* Return the result. */ return result; } static const char *DefUnit( AstSystemType system, const char *method, const char *class, int *status ){ /* * Name: * DefUnit * Purpose: * Return the default units for a time coordinate system type. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *DefUnit( AstSystemType system, const char *method, * const char *class, int *status ) * Class Membership: * TimeFrame member function. * Description: * This function returns a textual representation of the default * units associated with the specified time coordinate system. * Parameters: * system * The time coordinate system. * method * Pointer to a string holding the name of the calling method. * This is only for use in constructing error messages. * class * Pointer to a string holding the name of the supplied object class. * This is only for use in constructing error messages. * status * Pointer to the inherited status variable. * Returned Value: * A string describing the default units. This string follows the * units syntax described in FITS WCS paper I "Representations of world * coordinates in FITS" (Greisen & Calabretta). * Notes: * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ const char *result; /* Value to return */ /* Initialize */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get an identifier for the default units. */ if( system == AST__MJD ) { result = "d"; } else if( system == AST__JD ) { result = "d"; } else if( system == AST__BEPOCH ) { result = "yr"; } else if( system == AST__JEPOCH ) { result = "yr"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "%s(%s): Corrupt %s contains illegal System " "identification code (%d).", status, method, class, class, (int) system ); } /* 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: * Fields * Purpose: * Identify numerical fields within a formatted Axis value. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int Fields( AstFrame *this, int axis, const char *fmt, * const char *str, int maxfld, char **fields, * int *nc, double *val ) * Class Membership: * TimeFrame member function (over-rides the astFields protected * method inherited from the Frame class). * Description: * This function identifies the numerical fields within a Frame axis * value that has been formatted using astAxisFormat. It assumes that * the value was formatted using the supplied format string. It also * returns the equivalent floating point value. * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which the values have been * formatted (axis numbering starts at zero for the first axis). * fmt * Pointer to a constant null-terminated string containing the * format used when creating "str". * str * Pointer to a constant null-terminated string containing the * formatted value. * maxfld * The maximum number of fields to identify within "str". * fields * A pointer to an array of at least "maxfld" character pointers. * Each element is returned holding a pointer to the start of the * corresponding field in "str" (in the order in which they occur * within "str"), or NULL if no corresponding field can be found. * nc * A pointer to an array of at least "maxfld" integers. Each * element is returned holding the number of characters in the * corresponding field, or zero if no corresponding field can be * found. * val * Pointer to a location at which to store the value * equivalent to the returned field values. If this is NULL, * it is ignored. * Returned Value: * The number of fields succesfully identified and returned. * Notes: * - Leading and trailing spaces are ignored. * - If the formatted value is not consistent with the supplied format * string, then a value of zero will be returned, "fields" will be * returned holding NULLs, "nc" will be returned holding zeros, and * "val" is returned holding VAL__BAD. * - Fields are counted from the start of the formatted string. If the * string contains more than "maxfld" fields, then trailing fields are * ignored. */ /* Local Variables: */ AstTimeFrame *this; char *p; int bad; int df; int ifld; int ndp; int result; int state; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astFields" ); /* Call the method inherited from the parent Frame class, unless the format string indicates date-time formatting. */ df = DateFormat( fmt, &ndp, NULL, status ); if( !df ) { result = (*parent_fields)( this_frame, axis, fmt, str, maxfld, fields, nc, val, status ); /* Now handle date/time formats.... */ } else { /* Initialise. */ for( ifld = 0; ifld < maxfld; ifld++ ) { fields[ ifld ] = NULL; nc[ ifld ] = 0; } if( val ) *val = AST__BAD; /* The formatted string should always include a date in ISO format - three integer fields separated by dashes. Loop round each character until all characters have been read, or the max number of fields have been obtained, or it is shown that the string is badly formatted. */ bad = 0; state = 0; ifld = 0; p = (char *) str - 1; while( *(++p) && ifld < maxfld && !bad ){ /* Looking for the start of the year field. */ if( state == 0 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 1; } else if( !isspace( *p ) ) { bad = 1; } /* Looking for the end of the year field. */ } else if( state == 1 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != '-' ){ bad = 1; } else { state = 2; ifld++; } /* Looking for the start of the month field. */ } else if( state == 2 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 3; } else { bad = 1; } /* Looking for the end of the month field. */ } else if( state == 3 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != '-' ){ bad = 1; } else { state = 4; ifld++; } /* Looking for the start of the day field. */ } else if( state == 4 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 5; } else { bad = 1; } /* Looking for the end of the day field. */ } else if( state == 5 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != ' ' && *p != 'T' ){ bad = 1; } else { state = 6; ifld++; } /* Looking for the start of the hour field. */ } else if( state == 6 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 7; } else { bad = 1; } /* Looking for the end of the hour field. */ } else if( state == 7 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != ':' ){ bad = 1; } else { state = 8; ifld++; } /* Looking for the start of the minute field. */ } else if( state == 8 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 9; } else { bad = 1; } /* Looking for the end of the minute field. */ } else if( state == 9 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != ':' ){ bad = 1; } else { state = 10; ifld++; } /* Looking for the start of the integer part of the seconds field. */ } else if( state == 10 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 11; } else { bad = 1; } /* Looking for the end of the integer part of the seconds field. */ } else if( state == 11 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( *p != '.' ){ bad = 1; } else { state = 12; ifld++; } /* Looking for the start of the decimal part of the seconds field. */ } else if( state == 12 ) { if( isdigit( *p ) ) { fields[ ifld ] = p; nc[ ifld ] = 1; state = 13; } else { bad = 1; } /* Looking for the end of the decimal part of the seconds field. */ } else if( state == 13 ) { if( isdigit( *p ) ) { nc[ ifld ]++; } else if( !isspace( *p ) ){ bad = 1; } } else { bad = 1; } } /* If he string is badly formatted, return null values. */ if( bad ) { result = 0; for( ifld = 0; ifld < maxfld; ifld++ ) { fields[ ifld ] = NULL; nc[ ifld ] = 0; } /* Otherwise, unformat the string if required. */ } else if( val ) { (void) astUnformat( this, axis, str, val ); } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0; /* 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 TimeFrame axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *Format( AstFrame *this, int axis, double value, int *status ) * Class Membership: * TimeFrame 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 TimeFrame 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 TimeFrame. * axis * The number of the axis (zero-based) for which formatting is to be * performed. * value * The coordinate value to be formatted, in radians. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a null-terminated string containing the formatted value. * 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: */ astDECLARE_GLOBALS AstMapping *map; AstSystemType sys; AstTimeFrame *this; AstTimeScaleType ts; char *d; char sep; char tbuf[ 100 ]; char sign[ 2 ]; const char *fmt; const char *result; const char *u; double fd; double mjd; double off; int df; int id; int ihmsf[ 4 ]; int im; int iy; int j; int ndp; /* 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_frame); /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astFormat" ); /* Check if a bad coordinate value was supplied and return a pointer to an appropriate string if necessary. */ if ( value == AST__BAD ) { result = ""; } else { /* If the format string does not indicate a date/time format, invoke the parent Format method. */ fmt = astGetFormat( this, 0 ); df = DateFormat( fmt, &ndp, &sep, status ); if( !df ) { result = (*parent_format)( this_frame, axis, value, status ); /* Otherwise, format the value as a date/time */ } else { /* Convert the value to an absolute MJD in units of days. */ ts = astGetTimeScale( this ); sys = astGetSystem( this ); off = astGetTimeOrigin( this ); u = astGetUnit( this, 0 ); map = MakeMap( this, sys, AST__MJD, ts, ts, off, 0.0, u, "d", "astFormat", status ); if( map ) { astTran1( map, 1, &value, 1, &mjd ); map = astAnnul( map ); /* If no time fields will be produced, round to the nearest day. */ if( ndp < 0 ) mjd = (int) ( mjd + 0.5 ); /* Convert the MJD into a set of numeric date fields, plus day fraction, and format them. */ palDjcl( mjd, &iy, &im, &id, &fd, &j ); d = format_buff; d += sprintf( d, "%4d-%2.2d-%2.2d", iy, im, id ); /* If required, convert the day fraction into a set of numerical time fields. */ if( ndp >= 0 ) { palDd2tf( ndp, fd, sign, ihmsf ); /* Format the time fields. */ if( ndp > 0 ) { (void) sprintf( tbuf, "%c%2.2d:%2.2d:%2.2d.%*.*d", sep, ihmsf[0], ihmsf[1], ihmsf[2], ndp, ndp, ihmsf[3] ); } else { (void) sprintf( tbuf, "%c%2.2d:%2.2d:%2.2d", sep, ihmsf[0], ihmsf[1], ihmsf[2] ); } /* Add in the formatted time. */ d += sprintf( d, "%s", tbuf ); } result = format_buff; } } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static double FromMJD( AstTimeFrame *this, double oldval, int *status ){ /* * * Name: * FromMJD * Purpose: * Convert a supplied MJD value to the System of the supplied TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double FromMJD( AstTimeFrame *this, double oldval, int *status ) * Class Membership: * TimeFrame member function * Description: * This function converts the supplied time value from an MJD to * the System of the supplied TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * oldval * The value to be converted. It is assume to be an absolute MJD * value (i.e. zero offset) in units of days. * status * Pointer to the inherited status variable. * Returned Value: * The converted value (with zero offset), in the default units * associated with the System of "this". */ /* Local Variables: */ AstTimeMap *timemap; AstSystemType newsys; double args[ 2 ]; double result; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get the System attribute from the supplied TimeFrame. */ newsys = astGetSystem( this ); /* If this is MJD just return the value unchanged. */ if( newsys == AST__MJD ) { result = oldval; /* Otherwise create a TimeMap wich converts from the MJD to the required system, and use it to transform the supplied value. */ } else { timemap = astTimeMap( 0, "", status ); /* The supplied and returned values are assumed to have zero offset.*/ args[ 0 ] = 0.0; args[ 1 ] = 0.0; /* If required, add a TimeMap conversion which converts from MJD to the new system. */ if( newsys == AST__JD ) { astTimeAdd( timemap, "MJDTOJD", args ); } else if( newsys == AST__JEPOCH ) { astTimeAdd( timemap, "MJDTOJEP", args ); } else if( newsys == AST__BEPOCH ) { astTimeAdd( timemap, "MJDTOBEP", args ); } /* Use the TimeMap to convert the supplied value. */ astTran1( timemap, 1, &oldval, 1, &result ); /* Free resources */ timemap = astAnnul( timemap ); } /* 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 Frame axis values. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGap protected * method inherited from the Frame class). * Description: * This function returns a gap size which produces a nicely spaced * series of formatted values for a Frame axis, the returned gap * size being as close as possible to the supplied target gap * size. It also returns a convenient number of divisions into * which the gap can be divided. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which a gap is to be found. * gap * The target gap size. * ntick * Address of an int in which to return a convenient number of * divisions into which the gap can be divided. * 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: */ AstMapping *map; AstTimeFrame *this; AstTimeScaleType ts; const char *fmt; double mjdgap; double result; double xin[2]; double xout[2]; int df; int ndp; /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index. */ astValidateAxis( this_frame, axis, 1, "astGap" ); /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Use the parent astGap function unless the Format attribute indicates that axis values are to be formatted as multi-field date/time strings. */ fmt = astGetFormat( this, 0 ); df = DateFormat( fmt, &ndp, NULL, status ); if( !df ) { result = (*parent_gap)( this_frame, axis, gap, ntick, status ); /* Otherwise. */ } else { /* Get a Mapping which converts TimeFrame values to MJD values. */ ts = astGetTimeScale( this ); map = MakeMap( this, astGetSystem( this ), AST__MJD, ts, ts, astGetTimeOrigin( this ), 0.0, astGetUnit( this, 0 ), "d", "astGap", status ); if( map ) { /* Use it to transform two TimeFrame times to MJD. The first is the current time, and the second is the current time plus the target gap. */ xin[ 0 ] = astCurrentTime( this ); xin[ 1 ] = xin[ 0 ] + gap; astTran1( map, 2, xin, 1, xout ); /* Find the target MJD gap. */ mjdgap = xout[ 1 ] - xout[ 0 ]; /* If it is 1 year or more, use the parent astGap method to find a nice number of years, and convert back to days. */ if( mjdgap >= 365.25 ) { mjdgap = 365.25*(*parent_gap)( this_frame, axis, mjdgap/365.25, ntick, status ); /* If it is more than 270 days days use 1 year. */ } else if( mjdgap > 270.0 ) { mjdgap = 365.25; *ntick = 4; /* If it is more than 150 days days use 180 days (roughly half a year). Use 6 divisions (30 days each, or roughly 1 month). */ } else if( mjdgap > 150.0 ) { mjdgap = 180.0; *ntick = 6; /* If it is more than 90 days days use 120 days (roughly 4 months). */ } else if( mjdgap > 90.0 ) { mjdgap = 120.0; *ntick = 4; /* If it is more than 45 days days use 60 days (roughly 2 months). */ } else if( mjdgap > 45.0 ) { mjdgap = 60.0; *ntick = 2; /* If it is more than 22 days days use 30 days (roughly one month). Use 3 ten day divisions. */ } else if( mjdgap > 22.0 ) { mjdgap = 30.0; *ntick = 3; /* If it is more than 12 days days use 15 days (roughly half a month). */ } else if( mjdgap > 12.0 ) { mjdgap = 15.0; *ntick = 3; /* If it is more than 7.5 days days use 10 days, with 5 two-day divisions. */ } else if( mjdgap > 7.5 ) { mjdgap = 10.0; *ntick = 5; /* If it is more than 4.5 days days use 5 days. */ } else if( mjdgap > 4.5 ) { mjdgap = 5.0; *ntick = 5; /* If it is more than 3 days days use 4 days. */ } else if( mjdgap > 3.0 ) { mjdgap = 4.0; *ntick = 4; /* If it is more than 1.5 days days use 2 days. */ } else if( mjdgap > 1.5 ) { mjdgap = 2.0; *ntick = 2; /* If it is more than 0.5 of a day use 1 day. */ } else if( mjdgap > 0.5 ) { mjdgap = 1.0; *ntick = 4; /* Otherwise, if the format indicates that no time field is allowed, use 1 day. */ } else if( ndp < 0 ) { mjdgap = 1.0; *ntick = 2; /* Otherwise (i.e. if the target gap is 0.5 day or less and the format indicates that a time field is allowed), choose a value which looks nice. */ } else if( mjdgap >= 6.0/24.0 ) { /* 12 hours */ mjdgap = 12.0/24.0; *ntick = 4; } else if( mjdgap >= 3.0/24.0 ) { /* 6 hours */ mjdgap = 6.0/24.0; *ntick = 3; } else if( mjdgap >= 1.0/24.0 ) { /* 2 hours */ mjdgap = 2.0/24.0; *ntick = 4; } else if( mjdgap >= 30.0/1440.0 ) { /* 1 hour */ mjdgap = 60.0/1440.0; *ntick = 4; } else if( mjdgap >= 15.0/1440.0 ) { /* 30 minutes */ mjdgap = 30.0/1440.0; *ntick = 3; } else if( mjdgap >= 5.0/1440.0 ) { /* 10 minutes */ mjdgap = 10.0/1440.0; *ntick = 5; } else if( mjdgap >= 2.5/1440.0 ) { /* 5 minutes */ mjdgap = 5.0/1440.0; *ntick = 5; } else if( mjdgap >= 1.0/1440.0 ) { /* 2 minutes */ mjdgap = 2.0/1440.0; *ntick = 4; } else if( mjdgap >= 0.5/1440.0 ) { /* 1 minute */ mjdgap = 1.0/1440.0; *ntick = 4; } else if( mjdgap >= 15.0/86400.0 ) { /* 30 seconds */ mjdgap = 30.0/86400.0; *ntick = 3; } else if( mjdgap >= 5.0/86400.0 ) { /* 10 seconds */ mjdgap = 10.0/86400.0; *ntick = 5; } else if( mjdgap >= 2.5/86400.0 ) { /* 5 seconds */ mjdgap = 5.0/86400.0; *ntick = 5; } else if( mjdgap >= 1.0/86400.0 ) { /* 2 seconds */ mjdgap = 2.0/86400.0; *ntick = 4; } else if( mjdgap >= 0.5/86400.0 ) { /* 1 second */ mjdgap = 1.0/86400.0; *ntick = 4; } else { /* Less than 1 second */ mjdgap = 86400.0*(*parent_gap)( this_frame, axis, mjdgap/86400.0, ntick, status ); } /* Convert the MJD gap back into the system of the supplied TimeFrame. */ xout[ 1 ] = xout[ 0 ] + mjdgap; astTran1( map, 2, xout, 0, xin ); result = xin[ 1 ] - xin[ 0 ]; /* Free resources */ map = astAnnul( map ); /* If no Mapping could be found, use the parent astGap method. */ } else { result = (*parent_gap)( this_frame, axis, gap, ntick, status ); } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0.0; /* Return the result. */ return result; } static int GetActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * GetActiveUnit * Purpose: * Obtain the value of the ActiveUnit flag for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int GetActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetActiveUnit protected * method inherited from the Frame class). * Description: * This function returns the value of the ActiveUnit flag for a * TimeFrame, which is always 1. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The value to use for the ActiveUnit flag (1). */ return 1; } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * TimeFrame 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 TimeFrame, formatted as a character string. * Parameters: * this * Pointer to the TimeFrame. * attrib * Pointer to a null-terminated string containing the name of * the attribute whose value is required. This name should be in * lower case, with all white space removed. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a null-terminated string containing the attribute * value. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - The returned string pointer may point at memory allocated * within the TimeFrame, 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 TimeFrame. 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: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ AstTimeScaleType ts; /* Time scale */ astDECLARE_GLOBALS /* Declare the thread specific global data */ char *new_attrib; /* Pointer value to new attribute name */ const char *result; /* Pointer value to return */ double dval; /* Attribute value */ int len; /* Length of attrib string */ /* 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 TimeFrame structure. */ this = (AstTimeFrame *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* First look for axis attributes defined by the Frame class. Since a TimeFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent GetAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); result = (*parent_getattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignTimeScale. */ /* --------------- */ /* Obtain the AlignTimeScale code and convert to a string. */ } else if ( !strcmp( attrib, "aligntimescale" ) ) { ts = astGetAlignTimeScale( this ); if ( astOK ) { result = TimeScaleString( ts, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid AlignTimeScale " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) ts ); } } /* ClockLat. */ /* ------- */ } else if ( !strcmp( attrib, "clocklat" ) ) { result = astGetAttrib( this, "obslat" ); /* ClockLon. */ /* ------- */ } else if ( !strcmp( attrib, "clocklon" ) ) { result = astGetAttrib( this, "obslon" ); /* TimeOrigin. */ /* ----------- */ } else if ( !strcmp( attrib, "timeorigin" ) ) { dval = GetTimeOriginCur( this, status ); if( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* LTOffset. */ /* --------- */ } else if ( !strcmp( attrib, "ltoffset" ) ) { dval = astGetLTOffset( this ); if( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* TimeScale. */ /* ---------- */ /* Obtain the TimeScale code and convert to a string. */ } else if ( !strcmp( attrib, "timescale" ) ) { ts = astGetTimeScale( this ); if ( astOK ) { result = TimeScaleString( ts, status ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid TimeScale " "identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) ts ); } } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static double GetTimeOriginCur( AstTimeFrame *this, int *status ) { /* * Name: * GetTimeOriginCur * Purpose: * Obtain the TimeOrigin attribute for a TimeFrame in current units. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double GetTimeOriginCur( AstTimeFrame *this, int *status ) * Class Membership: * TimeFrame virtual function * Description: * This function returns the TimeOrigin attribute for a TimeFrame, in * the current units of the TimeFrame. The protected astGetTimeOrigin * method can be used to obtain the time origin in the default units of * the TimeFrame's System. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The TimeOrigin value, in the units, system and timescale specified * by the current values of the Unit, System and TimeScale attributes * within "this". * Notes: * - AST__BAD is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstMapping *map; const char *cur; const char *def; double result; double defval; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get the value in the default units */ result = astGetTimeOrigin( this ); /* If non-zero we convert to the current units.*/ if( result != 0.0 && result != AST__BAD ) { /* Get the default units for the TimeFrame's System. */ def = DefUnit( astGetSystem( this ), "astGetTimeOrigin", "TimeFrame", status ); /* Get the current units from the TimeFrame. */ cur = astGetUnit( this, 0 ); /* If the units differ, get a Mapping from default to current units. */ if( cur && def ){ if( strcmp( cur, def ) ) { map = astUnitMapper( def, cur, NULL, NULL ); /* Report an error if the units are incompatible. */ if( !map ) { astError( AST__BADUN, "%s(%s): The current units (%s) are not suitable " "for a TimeFrame.", status, "astGetTimeOrigin", astGetClass( this ), cur ); /* Otherwise, transform the stored origin value.*/ } else { defval = result; astTran1( map, 1, &defval, 1, &result ); map = astAnnul( map ); } } } } /* Return the result. */ return result; } static const char *GetDomain( AstFrame *this_frame, int *status ) { /* * Name: * GetDomain * Purpose: * Obtain a pointer to the Domain attribute string for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetDomain( AstFrame *this, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetDomain protected * method inherited from the Frame class). * Description: * This function returns a pointer to the Domain attribute string * for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a constant null-terminated string containing the * Domain value. * Notes: * - The returned pointer or the string it refers to may become * invalid following further invocation of this function or * modification of the TimeFrame. * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to TimeFrame 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 TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* If a Domain attribute string has been set, invoke the parent method to obtain a pointer to it. */ if ( astTestDomain( this ) ) { result = (*parent_getdomain)( this_frame, status ); /* Otherwise, provide a pointer to a suitable default string. */ } else { result = "TIME"; } /* Return the result. */ return result; } static double GetEpoch( AstFrame *this_frame, int *status ) { /* * Name: * GetEpoch * Purpose: * Get a value for the Epoch attribute of a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double GetEpoch( AstFrame *this, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetEpoch method * inherited from the Frame class). * Description: * This function returns a value for the Epoch attribute of a * TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The Epoch attribute value. * 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: */ AstMapping *map; AstSystemType sys; AstTimeFrame *this; AstTimeScaleType ts; const char *u; double oldval; double result; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* If an Epoch attribute value has been set, invoke the parent method to obtain it. */ if ( astTestEpoch( this ) ) { result = (*parent_getepoch)( this_frame, status ); /* Otherwise, if the TimeOrigin value is set in the TimeFrame, return it, converted to an absolute TDB MJD. */ } else if( astTestTimeOrigin( this ) ){ /* Get the required properties of the TimeFrame. */ oldval = astGetTimeOrigin( this ); ts = astGetTimeScale( this ); sys = astGetSystem( this ); u = DefUnit( sys, "astGetEpoch", "TimeFrame", status ); /* Epoch is defined as a TDB value. If the timescale is stored in an angular timescale such as UT1, then we would not normally be able to convert it to TDB since knowledge of DUT1 is required (the difference between UTC and UT1). Since the default Epoch value is not critical we assume a DUT1 value of zero in this case. We first map the stored value to UT1 then from UTC to TDB (using the approximation UT1 == UTC). */ if( ts == AST__UT1 || ts == AST__GMST || ts == AST__LAST || ts == AST__LMST ) { map = MakeMap( this, sys, AST__MJD, ts, AST__UT1, 0.0, 0.0, u, "d", "astGetEpoch", status ); if( map ) { astTran1( map, 1, &oldval, 1, &result ); map = astAnnul( map ); /* Update the values to use when converting to TBD. */ oldval = result; ts = AST__UTC; sys = AST__MJD; u = "d"; } else if( astOK ) { astError( AST__INTER, "astGetEpoch(%s): No Mapping from %s to " "UT1 (AST internal programming error).", status, astGetClass( this ), TimeScaleString( ts, status ) ); } } /* Now convert to TDB */ map = MakeMap( this, sys, AST__MJD, ts, AST__TDB, 0.0, 0.0, u, "d", "astGetEpoch", status ); if( map ) { oldval = astGetTimeOrigin( this ); astTran1( map, 1, &oldval, 1, &result ); map = astAnnul( map ); } else if( astOK ) { astError( AST__INTER, "astGetEpoch(%s): No Mapping from %s to " "TDB (AST internal programming error).", status, astGetClass( this ), TimeScaleString( ts, status ) ); } /* Otherwise, return the default Epoch value from the parent Frame. */ } else { result = (*parent_getepoch)( this_frame, status ); } /* Return the result. */ return result; } static const char *GetLabel( AstFrame *this, int axis, int *status ) { /* * Name: * GetLabel * Purpose: * Access the Label string for a TimeFrame axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetLabel( AstFrame *this, int axis, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetLabel method inherited * from the Frame class). * Description: * This function returns a pointer to the Label string for a specified axis * of a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstMapping *map; /* Mapping between units */ AstSystemType system; /* Code identifying type of time coordinates */ char *new_lab; /* Modified label string */ const char *fmt; /* Pointer to original Format string */ const char *result; /* Pointer to label string */ double ltoff; /* Local Time offset from UTC (hours) */ double orig; /* Time origin (seconds) */ int fmtSet; /* Was Format attribute set? */ int ndp; /* Number of decimal places for seconds field */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetLabel" ); /* Check if a value has been set for the required axis label string. If so, invoke the parent astGetLabel method to obtain a pointer to it. */ if ( astTestLabel( this, axis ) ) { result = (*parent_getlabel)( this, axis, status ); /* Otherwise, provide a suitable default label. */ } else { /* If the Format attribute indicates that time values will be formatted as dates, then choose a suitable label. */ fmt = astGetFormat( this, 0 ); if( DateFormat( fmt, &ndp, NULL, status ) ) { result = ( ndp >= 0 ) ? "Date/Time" : "Date"; /* Otherwise, identify the time coordinate system described by the TimeFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default label string. */ if ( astOK ) { result = strcpy( getlabel_buff, SystemLabel( system, status ) ); getlabel_buff[ 0 ] = toupper( getlabel_buff[ 0 ] ); /* If a non-zero TimeOrigin has been specified, include the offset now as a date/time string. */ orig = astGetTimeOrigin( this ); if( orig != 0.0 ) { /* Save the Format attribute, and then temporarily set it to give a date/time string. */ fmt = astStore( NULL, fmt, strlen( fmt ) + 1 ); fmtSet = astTestFormat( this, 0 ); astSetFormat( this, 0, "iso.0" ); /* Format the origin value as an absolute time and append it to the returned label string. Note, the origin always corresponds to a TimeFrame axis value of zero. */ sprintf( getlabel_buff + strlen( getlabel_buff ), " offset from %s", astFormat( this, 0, 0.0 ) ); /* Re-instate the original Format value. */ if( fmtSet ) { astSetFormat( this, 0, fmt ); } else { astClearFormat( this, 0 ); } /* Free the memory holding the copy of the format string. */ fmt = astFree( (char *) fmt ); /* If the time of day is "00:00:00", remove it. */ if( !strcmp( getlabel_buff + strlen( getlabel_buff ) - 8, "00:00:00" ) ) { getlabel_buff[ strlen( getlabel_buff ) - 8 ] = 0; } } /* Modify this default to take account of the current value of the Unit attribute, if set. */ if( astTestUnit( this, axis ) ) { /* Find a Mapping from the default Units for the current System, to the units indicated by the Unit attribute. This Mapping is used to modify the existing default label appropriately. For instance, if the default units is "yr" and the actual units is "log(yr)", then the default label of "Julian epoch" is changed to "log( Julian epoch )". */ map = astUnitMapper( DefUnit( system, "astGetLabel", astGetClass( this ), status ), astGetUnit( this, axis ), result, &new_lab ); if( new_lab ) { result = strcpy( getlabel_buff, new_lab ); new_lab = astFree( new_lab ); } /* Annul the unused Mapping. */ if( map ) map = astAnnul( map ); } } } /* If the time is a Local Time, indicate the offset from UTC. */ if( astGetTimeScale( this ) == AST__LT ) { ltoff = astGetLTOffset( this ); if( ltoff >= 0.0 ) { sprintf( getlabel_buff, "%s (UTC+%g)", result, ltoff ); } else { sprintf( getlabel_buff, "%s (UTC-%g)", result, -ltoff ); } result = getlabel_buff; } } /* Return the result. */ return result; } static const char *GetSymbol( AstFrame *this, int axis, int *status ) { /* * Name: * GetSymbol * Purpose: * Obtain a pointer to the Symbol string for a TimeFrame axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetSymbol( AstFrame *this, int axis, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetSymbol method inherited * from the Frame class). * Description: * This function returns a pointer to the Symbol string for a specified axis * of a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstMapping *map; /* Mapping between units */ AstSystemType system; /* Code identifying type of sky coordinates */ char *new_sym; /* Modified symbol string */ const char *result; /* Pointer to symbol string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetSymbol" ); /* Check if a value has been set for the required axis symbol string. If so, invoke the parent astGetSymbol method to obtain a pointer to it. */ if ( astTestSymbol( this, axis ) ) { result = (*parent_getsymbol)( this, axis, status ); /* Otherwise, identify the sky coordinate system described by the TimeFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default Symbol string. */ if ( astOK ) { if( system == AST__MJD ) { result = "MJD"; } else if( system == AST__JD ) { result = "JD"; } else if( system == AST__BEPOCH ) { result = "BEP"; } else if( system == AST__JEPOCH ) { result = "JEP"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "astGetSymbol(%s): Corrupt %s contains " "invalid System identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } /* Modify this default to take account of the current value of the Unit attribute, if set. */ if( astTestUnit( this, axis ) ) { /* Find a Mapping from the default Units for the current System, to the units indicated by the Unit attribute. This Mapping is used to modify the existing default symbol appropriately. For instance, if the default units is "yr" and the actual units is "log(yr)", then the default symbol of "JEP" is changed to "log( JEP )". */ map = astUnitMapper( DefUnit( system, "astGetSymbol", astGetClass( this ), status ), astGetUnit( this, axis ), result, &new_sym ); if( new_sym ) { result = strcpy( getsymbol_buff, new_sym ); new_sym = astFree( new_sym ); } /* Annul the unused Mapping. */ if( map ) map = astAnnul( map ); } } } /* Return the result. */ return result; } static AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetAlignSystem * Purpose: * Obtain the AlignSystem attribute for a TimeFrame. * Type: * Private function. * Synopsis: * #include "Specframe.h" * AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetAlignSystem protected * method inherited from the Frame class). * Description: * This function returns the AlignSystem attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The AlignSystem value. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to TimeFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* If a AlignSystem attribute has been set, invoke the parent method to obtain it. */ if ( astTestAlignSystem( this ) ) { result = (*parent_getalignsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__MJD; } /* Return the result. */ return result; } static AstTimeScaleType GetAlignTimeScale( AstTimeFrame *this, int *status ) { /* *+ * Name: * astGetAlignTimeScale * Purpose: * Obtain the AlignTimeScale attribute for a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * AstTimeScaleType GetAlignTimeScale( AstTimeFrame *this ) * Class Membership: * TimeFrame virtual function * Description: * This function returns the System attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * Returned Value: * The System value. * Notes: * - AST__BADTS is returned if this function is invoked with * the global error status set or if it should fail for any reason. *- */ /* Local Variables: */ AstTimeScaleType result; AstTimeScaleType ts; /* Initialise. */ result = AST__BADTS; /* Check the global error status. */ if ( !astOK ) return result; /* If a value has been set, return it. */ if( this->aligntimescale != AST__BADTS ) { result = this->aligntimescale; /* Otherwise, return a default depending on the current TimeScale value */ } else { ts = astGetTimeScale( this ); if ( ts == AST__UT1 || ts == AST__LAST || ts == AST__LMST || ts == AST__GMST ) { result = AST__UT1; } else { result = AST__TAI; } } /* Return the result. */ return result; } static AstSystemType GetSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetSystem * Purpose: * Obtain the System attribute for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * AstSystemType GetSystem( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetSystem protected * method inherited from the Frame class). * Description: * This function returns the System attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The System value. * Notes: * - AST__BADSYSTEM is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to TimeFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* If a System attribute has been set, invoke the parent method to obtain it. */ if ( astTestSystem( this ) ) { result = (*parent_getsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__MJD; } /* Return the result. */ return result; } static AstTimeScaleType GetTimeScale( AstTimeFrame *this, int *status ) { /* *+ * Name: * astGetTimeScale * Purpose: * Obtain the TimeScale attribute for a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * AstTimeScaleType GetTimeScale( AstTimeFrame *this ) * Class Membership: * TimeFrame virtual function * Description: * This function returns the System attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * Returned Value: * The System value. * Notes: * - AST__BADTS is returned if this function is invoked with * the global error status set or if it should fail for any reason. *- */ /* Local Variables: */ AstTimeScaleType result; /* Initialise. */ result = AST__BADTS; /* Check the global error status. */ if ( !astOK ) return result; /* If a value has been set, return it. */ if( this->timescale != AST__BADTS ) { result = this->timescale; /* Otherwise, return a default depending on the current System value. */ } else { if ( astGetSystem( this ) == AST__BEPOCH ) { result = AST__TT; } else { result = AST__TAI; } } /* Return the result. */ return result; } static const char *GetTitle( AstFrame *this_frame, int *status ) { /* * Name: * GetTitle * Purpose: * Obtain a pointer to the Title string for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetTitle( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astGetTitle method inherited * from the Frame class). * Description: * This function returns a pointer to the Title string for a TimeFrame. * A pointer to a suitable default string is returned if no Title value has * previously been set. * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null-terminated character string containing the requested * information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstSystemType system; /* Code identifying type of coordinates */ AstTimeScaleType ts; /* Time scale value */ AstTimeFrame *this; /* Pointer to TimeFrame structure */ const char *fmt; /* Pointer to original Format string */ const char *result; /* Pointer to result string */ double ltoff; /* Local Time offset from UTC (hours) */ double orig; /* Time origin (seconds) */ int fmtSet; /* Was Format attribute set? */ int nc; /* No. of characters added */ int ndp; /* Number of decimal places */ int pos; /* Buffer position to enter text */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_frame); /* Initialise. */ result = NULL; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* See if a Title string has been set. If so, use the parent astGetTitle method to obtain a pointer to it. */ if ( astTestTitle( this ) ) { result = (*parent_gettitle)( this_frame, status ); /* Otherwise, we will generate a default Title string. Obtain the values of the TimeFrame's attributes that determine what this string will be. */ } else { system = astGetSystem( this ); orig = GetTimeOriginCur( this, status ); ts = astGetTimeScale( this ); if ( astOK ) { result = gettitle_buff; /* Begin with the system's default label. */ pos = sprintf( gettitle_buff, "%s", SystemLabel( system, status ) ); gettitle_buff[ 0 ] = toupper( gettitle_buff[ 0 ] ); /* Append the time scale code, if a value has been set for the timescale. Do not do this if the system is BEPOCH since BEPOCH can only be used with the TT timescale. */ if( system != AST__BEPOCH && astTestTimeScale( this ) ) { nc = sprintf( gettitle_buff + pos, " [%s", TimeScaleString( ts, status ) ); pos += nc; /* For Local Time, include the offset from UTC. */ if( ts == AST__LT ) { ltoff = astGetLTOffset( this ); if( ltoff >= 0.0 ) { nc = sprintf( gettitle_buff + pos, " (UTC+%g)", ltoff ); } else { nc = sprintf( gettitle_buff + pos, " (UTC-%g)", -ltoff ); } pos += nc; } /* Close the brackets. */ nc = sprintf( gettitle_buff + pos, "]" ); pos += nc; } /* If a non-zero offset has been specified, and the Format attribute does not indicate a date string (which is always absolute), include the offset now as a date/time string. */ fmt = astGetFormat( this, 0 ); if( orig != 0.0 && !DateFormat( fmt, &ndp, NULL, status ) ) { /* Save the Format attribute, and then temporarily set it to give a date/time string. */ fmt = astStore( NULL, fmt, strlen( fmt ) + 1 ); fmtSet = astTestFormat( this, 0 ); astSetFormat( this, 0, "iso.0" ); /* Format the origin value as an absolute time and append it to the returned title string. Note, the origin always corresponds to a TimeFrame axis value of zero. */ nc = sprintf( gettitle_buff+pos, " offset from %s", astFormat( this, 0, 0.0 ) ); pos += nc; /* Re-instate the original Format value. */ if( fmtSet ) { astSetFormat( this, 0, fmt ); } else { astClearFormat( this, 0 ); } /* Free the Format string copy. */ fmt = astFree( (char *) fmt ); } } } /* If an error occurred, clear the returned pointer value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static const char *GetUnit( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetUnit * Purpose: * Obtain a pointer to the Unit string for a TimeFrame's axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *GetUnit( AstFrame *this_frame, int axis ) * Class Membership: * TimeFrame member function (over-rides the astGetUnit method inherited * from the Frame class). * Description: * This function returns a pointer to the Unit string for a specified axis * of a TimeFrame. If the Unit attribute has not been set for the axis, a * pointer to a suitable default string is returned instead. * Parameters: * this * Pointer to the TimeFrame. * axis * The number of the axis (zero-based) for which information is required. * Returned Value: * A pointer to a null-terminated string containing the Unit value. * 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: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ AstSystemType system; /* The TimeFrame's System value */ const char *result; /* Pointer value to return */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetUnit" ); /* If a value has been set for the Unit attribute, use the parent GetUnit method to return a pointer to the required Unit string. */ if( astTestUnit( this, axis ) ){ result = (*parent_getunit)( this_frame, axis, status ); /* Otherwise, identify the time coordinate system described by the TimeFrame. */ } else { system = astGetSystem( this ); /* Return a string describing the default units. */ result = DefUnit( system, "astGetUnit", astGetClass( this ), status ); } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } void astInitTimeFrameVtab_( AstTimeFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTimeFrameVtab * Purpose: * Initialise a virtual function table for a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * void astInitTimeFrameVtab( AstTimeFrameVtab *vtab, const char *name ) * Class Membership: * TimeFrame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the TimeFrame 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 */ AstMapping *map; /* Temporary Maping */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ double utc_epoch; /* Unix epoch as a UTC MJD */ /* 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 astIsATimeFrame) 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->ClearAlignTimeScale = ClearAlignTimeScale; vtab->TestAlignTimeScale = TestAlignTimeScale; vtab->GetAlignTimeScale = GetAlignTimeScale; vtab->SetAlignTimeScale = SetAlignTimeScale; vtab->ClearTimeOrigin = ClearTimeOrigin; vtab->TestTimeOrigin = TestTimeOrigin; vtab->GetTimeOrigin = GetTimeOrigin; vtab->SetTimeOrigin = SetTimeOrigin; vtab->ClearLTOffset = ClearLTOffset; vtab->TestLTOffset = TestLTOffset; vtab->GetLTOffset = GetLTOffset; vtab->SetLTOffset = SetLTOffset; vtab->ClearTimeScale = ClearTimeScale; vtab->TestTimeScale = TestTimeScale; vtab->GetTimeScale = GetTimeScale; vtab->SetTimeScale = SetTimeScale; vtab->CurrentTime = CurrentTime; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; frame = (AstFrameVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_getdomain = frame->GetDomain; frame->GetDomain = GetDomain; parent_getsystem = frame->GetSystem; frame->GetSystem = GetSystem; parent_setsystem = frame->SetSystem; frame->SetSystem = SetSystem; parent_clearsystem = frame->ClearSystem; frame->ClearSystem = ClearSystem; parent_getalignsystem = frame->GetAlignSystem; frame->GetAlignSystem = GetAlignSystem; parent_getlabel = frame->GetLabel; frame->GetLabel = GetLabel; parent_getsymbol = frame->GetSymbol; frame->GetSymbol = GetSymbol; parent_gettitle = frame->GetTitle; frame->GetTitle = GetTitle; parent_getepoch = frame->GetEpoch; frame->GetEpoch = GetEpoch; parent_getunit = frame->GetUnit; frame->GetUnit = GetUnit; parent_setunit = frame->SetUnit; frame->SetUnit = SetUnit; parent_match = frame->Match; frame->Match = Match; parent_overlay = frame->Overlay; frame->Overlay = Overlay; parent_subframe = frame->SubFrame; frame->SubFrame = SubFrame; parent_format = frame->Format; frame->Format = Format; parent_unformat = frame->Unformat; frame->Unformat = Unformat; parent_abbrev = frame->Abbrev; frame->Abbrev = Abbrev; parent_fields = frame->Fields; frame->Fields = Fields; parent_gap = frame->Gap; frame->Gap = Gap; parent_centre = frame->Centre; frame->Centre = Centre; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ frame->GetActiveUnit = GetActiveUnit; frame->TestActiveUnit = TestActiveUnit; frame->ValidateSystem = ValidateSystem; frame->SystemString = SystemString; frame->SystemCode = SystemCode; /* Declare the copy constructor, destructor and class dump function. */ astSetDump( vtab, Dump, "TimeFrame", "Description of time coordinate system" ); /* Convert the Unix Epoch (00:00:00 UTC 1 January 1970 AD) from UTC to TAI. */ LOCK_MUTEX2 map = MakeMap( NULL, AST__MJD, AST__MJD, AST__UTC, AST__TAI, 0.0, 0.0, "d", "d", "astInitTimeFrameVtab", status ); utc_epoch = UNIX_EPOCH; astTran1( map, 1, &utc_epoch, 1, &tai_epoch ); map = astAnnul( map ); UNLOCK_MUTEX2 /* 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 AstMapping *MakeMap( AstTimeFrame *this, AstSystemType sys1, AstSystemType sys2, AstTimeScaleType ts1, AstTimeScaleType ts2, double off1, double off2, const char *unit1, const char *unit2, const char *method, int *status ){ /* * Name: * MakeMap * Purpose: * Make a Mapping between stated timescales and systems. * Type: * Private function. * Synopsis: * #include "timeframe.h" * AstMapping *MakeMap( AstTimeFrame *this, AstSystemType sys1, * AstSystemType sys2, AstTimeScaleType ts1, * AstTimeScaleType ts2, double off1, double off2, * const char *unit1, const char unit2, * const char *method, int *status ) * Class Membership: * TimeFrame member function * Description: * This function creates a Mapping from a stated pair of System and * TimeScale to another stated pair. * Parameters: * this * A TimeFrame which specifies extra attributes (the clock position, * time zone, etc) for both input and output. * sys1 * The input System. * sys2 * The output System. * ts1 * The input System. * ts2 * The output System. * off1 * The axis offset used with the input, in the defaults units * associated with "sys1". * off2 * The axis offset used with the output, in the defaults units * associated with "sys2". * unit1 * The input units. * unit2 * The output units. * method * A string containing the method name to include in error messages. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the new Mapping. NULL if the timescales were * incompatible. */ /* Local Variables: */ AstMapping *result; AstMapping *tmap; AstMapping *tmap2; AstMapping *umap; AstMapping *umap1; AstMapping *umap2; AstTimeMap *timemap; const char *du; double args[ 4 ]; double args_lt[ 1 ]; double args_ut[ 1 ]; double shift; /* Check the global error status. */ result = NULL; if ( !astOK ) return result; /* If the timescales are equal... */ if( ts1 == ts2 ) { /* and the time systems are equal... */ if( sys1 == sys2 ) { /* and the time offsets are equal... */ if( astEQUALS( off1, off2, 1.0E3 ) ) { /* and the units are equal, return a UnitMap. */ if( !strcmp( unit1, unit2 ) ) { result = (AstMapping *) astUnitMap( 1, "", status ); /* If only the units differ, return the appropriate units Mapping. */ } else { result = astUnitMapper( unit1, unit2, NULL, NULL ); } /* If the time offsets differ... */ } else { /* Transform the difference in offsets from the default units associated with the (common) system, to the units associated with the output. */ shift = off1 - off2; du = DefUnit( sys1, method, "TimeFrame", status ); if( du && strcmp( du, unit2 ) && shift != 0.0 ) { umap = astUnitMapper( DefUnit( sys1, method, "TimeFrame", status ), unit2, NULL, NULL ); astTran1( umap, 1, &shift, 1, &shift ); umap = astAnnul( umap ); } /* Create a ShiftMap to apply the shift. */ result = (AstMapping *) astShiftMap( 1, &shift, "", status ); /* If the input and output units also differ, include the appropriate units Mapping. */ if( strcmp( unit1, unit2 ) ) { umap = astUnitMapper( unit1, unit2, NULL, NULL ); tmap = (AstMapping *) astCmpMap( umap, result, 1, "", status ); umap = astAnnul( umap ); (void) astAnnul( result ); result = tmap; } } } } /* If the systems and/or timescales differ, we convert first from the input frame to a common frame, then from the common frame to the output frame. */ if( !result ) { /* First, a Mapping from the input units to the default units for the input System (these are the units expected by the TimeMap conversions). */ umap1 = astUnitMapper( unit1, DefUnit( sys1, method, "TimeFrame", status ), NULL, NULL ); /* Now create a null TimeMap. */ timemap = astTimeMap( 0, "", status ); /* Store the input time offsets to use. They correspond to the same moment in time (the second is the MJD equivalent of the first). */ args[ 0 ] = off1; args[ 1 ] = ToMJD( sys1, off1, status ); /* Add a conversion from the input System to MJD. */ if( sys1 == AST__JD ) { astTimeAdd( timemap, "JDTOMJD", args ); } else if( sys1 == AST__JEPOCH ) { astTimeAdd( timemap, "JEPTOMJD", args ); } else if( sys1 == AST__BEPOCH ) { astTimeAdd( timemap, "BEPTOMJD", args ); } /* All timescale conversions except UTTOUTC and UTCTOUT require the input (MJD) offset as the first argument. In general, the observers longitude, latitude and altitude are also needed. The Frame class stores longitude values in a +ve eastwards sense, but the TimeMap class needs +ve westwards, so negate the longitude. */ args[ 0 ] = args[ 1 ]; args[ 1 ] = this ? -astGetObsLon( this ) : 0.0; args[ 2 ] = this ? astGetObsLat( this ) : 0.0; args[ 3 ] = this ? astGetObsAlt( this ) : 0.0; /* The UTTOUTC and UTCTOUT conversions required just the DUT1 value. */ args_ut[ 0 ] = this ? astGetDut1( this ) : 0.0; /* The LTTOUTC and UTCTOLT conversions required just the time zone correction. */ args_lt[ 0 ] = this ? astGetLTOffset( this ) : 0.0; /* If the input and output timescales differ, now add a conversion from the input timescale to TAI. */ if( ts1 != ts2 ) { if( ts1 == AST__TAI ) { } else if( ts1 == AST__UTC ) { astTimeAdd( timemap, "UTCTOTAI", args ); } else if( ts1 == AST__TT ) { astTimeAdd( timemap, "TTTOTAI", args ); } else if( ts1 == AST__TDB ) { astTimeAdd( timemap, "TDBTOTT", args ); astTimeAdd( timemap, "TTTOTAI", args ); } else if( ts1 == AST__TCG ) { astTimeAdd( timemap, "TCGTOTT", args ); astTimeAdd( timemap, "TTTOTAI", args ); } else if( ts1 == AST__LT ) { astTimeAdd( timemap, "LTTOUTC", args_lt ); astTimeAdd( timemap, "UTCTOTAI", args ); } else if( ts1 == AST__TCB ) { astTimeAdd( timemap, "TCBTOTDB", args ); astTimeAdd( timemap, "TDBTOTT", args ); astTimeAdd( timemap, "TTTOTAI", args ); } else if( ts1 == AST__UT1 ) { astTimeAdd( timemap, "UTTOUTC", args_ut ); astTimeAdd( timemap, "UTCTOTAI", args ); } else if( ts1 == AST__GMST ) { astTimeAdd( timemap, "GMSTTOUT", args ); astTimeAdd( timemap, "UTTOUTC", args_ut ); astTimeAdd( timemap, "UTCTOTAI", args ); } else if( ts1 == AST__LAST ) { astTimeAdd( timemap, "LASTTOLMST", args ); astTimeAdd( timemap, "LMSTTOGMST", args ); astTimeAdd( timemap, "GMSTTOUT", args ); astTimeAdd( timemap, "UTTOUTC", args_ut ); astTimeAdd( timemap, "UTCTOTAI", args ); } else if( ts1 == AST__LMST ) { astTimeAdd( timemap, "LMSTTOGMST", args ); astTimeAdd( timemap, "GMSTTOUT", args ); astTimeAdd( timemap, "UTTOUTC", args_ut ); astTimeAdd( timemap, "UTCTOTAI", args ); } /* Now add a conversion from TAI to the output timescale. */ if( ts2 == AST__TAI ) { } else if( ts2 == AST__UTC ) { astTimeAdd( timemap, "TAITOUTC", args ); } else if( ts2 == AST__TT ) { astTimeAdd( timemap, "TAITOTT", args ); } else if( ts2 == AST__TDB ) { astTimeAdd( timemap, "TAITOTT", args ); astTimeAdd( timemap, "TTTOTDB", args ); } else if( ts2 == AST__TCG ) { astTimeAdd( timemap, "TAITOTT", args ); astTimeAdd( timemap, "TTTOTCG", args ); } else if( ts2 == AST__TCB ) { astTimeAdd( timemap, "TAITOTT", args ); astTimeAdd( timemap, "TTTOTDB", args ); astTimeAdd( timemap, "TDBTOTCB", args ); } else if( ts2 == AST__UT1 ) { astTimeAdd( timemap, "TAITOUTC", args ); astTimeAdd( timemap, "UTCTOUT", args_ut ); } else if( ts2 == AST__GMST ) { astTimeAdd( timemap, "TAITOUTC", args ); astTimeAdd( timemap, "UTCTOUT", args_ut ); astTimeAdd( timemap, "UTTOGMST", args ); } else if( ts2 == AST__LAST ) { astTimeAdd( timemap, "TAITOUTC", args ); astTimeAdd( timemap, "UTCTOUT", args_ut ); astTimeAdd( timemap, "UTTOGMST", args ); astTimeAdd( timemap, "GMSTTOLMST", args ); astTimeAdd( timemap, "LMSTTOLAST", args ); } else if( ts2 == AST__LMST ) { astTimeAdd( timemap, "TAITOUTC", args ); astTimeAdd( timemap, "UTCTOUT", args_ut ); astTimeAdd( timemap, "UTTOGMST", args ); astTimeAdd( timemap, "GMSTTOLMST", args ); } else if( ts2 == AST__LT ) { astTimeAdd( timemap, "TAITOUTC", args ); astTimeAdd( timemap, "UTCTOLT", args_lt ); } } /* Add a conversion from MJD to the output System, if needed. */ args[ 1 ] = off2; if( sys2 == AST__MJD ) { if( args[ 0 ] != off2 ) astTimeAdd( timemap, "MJDTOMJD", args ); } else if( sys2 == AST__JD ) { astTimeAdd( timemap, "MJDTOJD", args ); } else if( sys2 == AST__JEPOCH ) { astTimeAdd( timemap, "MJDTOJEP", args ); } else if( sys2 == AST__BEPOCH ) { astTimeAdd( timemap, "MJDTOBEP", args ); } /* Now, create a Mapping from the default units for the output System (these are the units produced by the TimeMap conversions) to the requested output units. */ umap2 = astUnitMapper( DefUnit( sys2, method, "TimeFrame", status ), unit2, NULL, NULL ); /* If OK, combine the Mappings in series. Note, umap1 and umap2 should always be non-NULL because the suitablity of units strings is checked within OriginSystem - called from within SetSystem. */ if( umap1 && umap2 ) { tmap = (AstMapping *) astCmpMap( umap1, timemap, 1, "", status ); tmap2 = (AstMapping *) astCmpMap( tmap, umap2, 1, "", status ); tmap = astAnnul( tmap ); result = astSimplify( tmap2 ); tmap2 = astAnnul( tmap2 ); } /* Free remaining resources */ if( umap1 ) umap1 = astAnnul( umap1 ); if( umap2 ) umap2 = astAnnul( umap2 ); timemap = astAnnul( timemap ); } /* Return NULL if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int MakeTimeMapping( AstTimeFrame *target, AstTimeFrame *result, AstTimeFrame *align_frm, int report, AstMapping **map, int *status ) { /* * Name: * MakeTimeMapping * Purpose: * Generate a Mapping between two TimeFrames. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int MakeTimeMapping( AstTimeFrame *target, AstTimeFrame *result, * AstTimeFrame *align_frm, int report, * AstMapping **map, int *status ) { * Class Membership: * TimeFrame member function. * Description: * This function takes two TimeFrames and generates a Mapping that * converts between them, taking account of differences in their * coordinate systems, offsets, timescales, units, etc. * Parameters: * target * Pointer to the first TimeFrame. * result * Pointer to the second TimeFrame. * align_frm * A TimeFrame defining the system and time scale in which to * align the target and result TimeFrames. The AlignSystem and * AlignTimeScale attributes are used for this purpose. * report * Should errors be reported if no match is possible? These reports * will describe why no match was possible. * map * Pointer to a location which is to receive a pointer to the * returned Mapping. The forward transformation of this Mapping * will convert from "target" coordinates to "result" * coordinates, and the inverse transformation will convert in * the opposite direction (all coordinate values in radians). * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Mapping could be generated, or zero if the two * TimeFrames are sufficiently un-related that no meaningful Mapping * can be produced (albeit an "unmeaningful" Mapping will be returned * in this case, which will need to be annulled). * Notes: * A value of zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ AstMapping *map1; /* Intermediate Mapping */ AstMapping *map2; /* Intermediate Mapping */ AstMapping *tmap; /* Intermediate Mapping */ AstSystemType sys1; /* Code to identify input system */ AstSystemType sys2; /* Code to identify output system */ AstTimeScaleType align_ts; /* Alignment time scale */ AstTimeScaleType ts1; /* Input time scale */ AstTimeScaleType ts2; /* Output time scale */ const char *align_unit; /* Units used for alignment */ const char *u1; /* Input target units */ const char *u2; /* Output target units */ double align_off; /* Axis offset */ double ltoff1; /* Input axis Local Time offset */ double ltoff2; /* Output axis Local Time offset */ double off1; /* Input axis offset */ double off2; /* Output axis offset */ int arclk; /* Align->result depends on clock position? */ int ardut; /* Align->result depends on Dut1? */ int arlto; /* Align->result depends on LT offset? */ int clkdiff; /* Do target and result clock positions differ? */ int dut1diff; /* Do target and result Dut1 values differ? */ int ltodiff; /* Do target and result LTOffset values differ? */ int match; /* Mapping can be generated? */ int taclk; /* Target->align depends on clock position? */ int tadut; /* Target->align depends on Dut1? */ int talto; /* Target->align depends on LT offset? */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise the returned values. */ match = 0; *map = NULL; /* Get the required properties of the input (target) TimeFrame */ sys1 = astGetSystem( target ); ts1 = astGetTimeScale( target ); off1 = astGetTimeOrigin( target ); u1 = astGetUnit( target, 0 ); ltoff1= astGetLTOffset( target ); /* Get the required properties of the output (result) TimeFrame */ sys2 = astGetSystem( result ); ts2 = astGetTimeScale( result ); off2 = astGetTimeOrigin( result ); u2 = astGetUnit( result, 0 ); ltoff2= astGetLTOffset( result ); /* Get the timescale in which alignment is to be performed. The alignment System does not matter since they all supported time systems are linearly related, and so the choice of alignment System has no effect on the total Mapping. We arbitrarily choose MJD as the alignment System (if needed). */ align_ts = astGetAlignTimeScale( align_frm ); /* The main difference between this function and the MakeMap function is that this function takes account of the requested alignment frame. But the alignment Frame only makes a difference to the overall Mapping if 1) the observer's positions are different in the target and result Frame, and 2) one or both of the Mappings to or from the alignment frame depends on the observer's position. If either of these 2 conditions is not met, then the alignment frame can be ignored, and the simpler MakeMap function can be called. See if the observer's positions differ. */ clkdiff = ( astGetObsLon( target ) != astGetObsLon( result ) || astGetObsLat( target ) != astGetObsLat( result ) || astGetObsAlt( target ) != astGetObsAlt( result ) ); /* See if the Mapping from target to alignment frame depends on the observer's position. */ taclk = CLOCK_SCALE( ts1 ) || CLOCK_SCALE( align_ts ); /* See if the Mapping from alignment to result frame depends on the observer's position. */ arclk = CLOCK_SCALE( align_ts ) || CLOCK_SCALE( ts2 ); /* In addition, the alignment frame is significant if either of the Mappings depends on DUT1 and the values of the DUT1 attribute are different for the two TimeFrames. */ dut1diff = ( astGetDut1( target ) != astGetDut1( result ) ); tadut = DUT1_SCALE( ts1 ) != DUT1_SCALE( align_ts ); ardut = DUT1_SCALE( align_ts ) != DUT1_SCALE( ts2 ); /* In addition, the alignment frame is significant if either of the Mappings depends on LTOffset and the values of the LTOffset attribute are different for the two TimeFrames. */ ltodiff = ( ltoff1 != ltoff2 ); talto = LTOFFSET_SCALE( ts1 ) != LTOFFSET_SCALE( align_ts ); arlto = LTOFFSET_SCALE( align_ts ) != LTOFFSET_SCALE( ts2 ); /* If the alignment frame can be ignored, use MakeMap */ if( ( !clkdiff || !( taclk || arclk ) ) && ( !ltodiff || !( talto || arlto ) ) && ( !dut1diff || !( tadut || ardut ) ) ) { *map = MakeMap( target, sys1, sys2, ts1, ts2, off1, off2, u1, u2, "astSubFrame", status ); if( *map ) match = 1; /* Otherwise, we create the Mapping in two parts; first a Mapping from the target Frame to the alignment Frame (using the target clock, dut1 and ltoffset), then a Mapping from the alignment Frame to the results Frame (using the result clock, dut1 and ltoffset). */ } else { /* Create a Mapping from target units/system/timescale/offset to MJD in the alignment timescale with default units and offset equal to the MJD equivalent of the target offset. */ align_off = ToMJD( sys1, off1, status ); align_unit = DefUnit( AST__MJD, "MakeTimeMap", "TimeFrame", status ); map1 = MakeMap( target, sys1, AST__MJD, ts1, align_ts, off1, align_off, u1, align_unit, "MakeTimeMap", status ); /* Report an error if the timescales were incompatible. */ if( !map1 ){ match = 0; if( report && astOK ) { astError( AST__INCTS, "astMatch(%s): Alignment in requested " "timescale (%s) is not possible since one or both of the " "TimeFrames being aligned refer to the %s timescale.", status, astGetClass( target ), TimeScaleString( align_ts, status ), TimeScaleString( ts1, status ) ); } } /* We now create a Mapping that converts from the alignment System (MJD), TimeScale and offset to the result coordinate system. */ map2 = MakeMap( result, AST__MJD, sys2, align_ts, ts2, align_off, off2, align_unit, u2, "MakeTimeMap", status ); /* Report an error if the timescales were incompatible. */ if( !map2 ){ match = 0; if( report && astOK ) { astError( AST__INCTS, "astMatch(%s): Alignment in requested " "timescale (%s) is not possible since one or both of the " "TimeFrames being aligned refer to the %s timescale.", status, astGetClass( result ), TimeScaleString( align_ts, status ), TimeScaleString( ts2, status ) ); } } /* Combine these two Mappings. */ if( map1 && map2 ) { match = 1; tmap = (AstMapping *) astCmpMap( map1, map2, 1, "", status ); *map = astSimplify( tmap ); tmap = astAnnul( tmap ); } /* Free resources. */ if( map1 ) map1 = astAnnul( map1 ); if( map2 ) map2 = astAnnul( map2 ); } /* If an error occurred, annul the returned Mapping and clear the returned values. */ if ( !astOK ) { *map = astAnnul( *map ); match = 0; } /* Return the result. */ return match; } static int Match( AstFrame *template_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 "timeframe.h" * int Match( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result, int *status ) * Class Membership: * TimeFrame member function (over-rides the protected astMatch method * inherited from the Frame class). * Description: * This function matches a "template" TimeFrame to a "target" Frame and * determines whether it is possible to convert coordinates between them. * If it is, a mapping that performs the transformation is returned along * with a new Frame that describes the coordinate system that results when * this mapping is applied to the "target" coordinate system. In addition, * information is returned to allow the axes in this "result" Frame to be * associated with the corresponding axes in the "target" and "template" * Frames from which they are derived. * Parameters: * template * Pointer to the template TimeFrame. This describes the coordinate * system (or set of possible coordinate systems) into which we wish to * convert our coordinates. * target * Pointer to the target Frame. This describes the coordinate system in * which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case. * 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 template TimeFrame axis from * which it is derived. If it is not derived from any template * TimeFrame 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 and the template Frames. In * particular, when the template allows the possibility of transformaing * to any one of a set of alternative coordinate systems, the "result" * Frame will indicate which of the alternatives was used. * 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. * Implementation Notes: * This implementation addresses the matching of a TimeFrame class * object to any other class of Frame. A TimeFrame will match any class * of TimeFrame (i.e. possibly from a derived class) but will not match * a less specialised class of Frame. */ AstFrame *frame0; /* Pointer to Frame underlying axis 0 */ AstTimeFrame *template; /* Pointer to template TimeFrame structure */ int iaxis0; /* Axis index underlying axis 0 */ int iaxis; /* Axis index */ int match; /* Coordinate conversion possible? */ int target_axis0; /* Index of TimeFrame axis in the target */ int target_naxes; /* Number of target axes */ /* Initialise the returned values. */ *template_axes = NULL; *target_axes = NULL; *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain a pointer to the template TimeFrame structure. */ template = (AstTimeFrame *) template_frame; /* Obtain the number of axes in the target Frame. */ target_naxes = astGetNaxes( target ); /* The first criterion for a match is that the template matches as a Frame class object. This ensures that the number of axes (1) and domain, etc. of the target Frame are suitable. Invoke the parent "astMatch" method to verify this. */ match = (*parent_match)( template_frame, target, matchsub, template_axes, target_axes, map, result, status ); /* If a match was found, annul the returned objects, which are not needed, but keep the memory allocated for the axis association arrays, which we will re-use. */ if ( astOK && match ) { *map = astAnnul( *map ); *result = astAnnul( *result ); } /* If OK so far, obtain pointers to the primary Frames which underlie all target axes. Stop when a TimeFrame axis is found. */ if ( match && astOK ) { match = 0; for( iaxis = 0; iaxis < target_naxes; iaxis++ ) { astPrimaryFrame( target, iaxis, &frame0, &iaxis0 ); if( astIsATimeFrame( frame0 ) ) { frame0 = astAnnul( frame0 ); target_axis0 = iaxis; match = 1; break; } else { frame0 = astAnnul( frame0 ); } } } /* Check at least one TimeFrame axis was found it the target. Store the axis associataions. */ if( match && astOK ) { (*template_axes)[ 0 ] = 0; (*target_axes)[ 0 ] = target_axis0; /* Use the target's "astSubFrame" method to create a new Frame (the result Frame) with copies of the target axes in the required order. This process also overlays the template attributes on to the target Frame and returns a Mapping between the target and result Frames which effects the required coordinate conversion. */ match = astSubFrame( target, template, 1, *target_axes, *template_axes, map, result ); } /* If an error occurred, or conversion to the result Frame's coordinate system was not possible, then free all memory, annul the returned objects, and reset the returned value. */ if ( !astOK || !match ) { *template_axes = astFree( *template_axes ); *target_axes = astFree( *target_axes ); if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } static void OriginScale( AstTimeFrame *this, AstTimeScaleType newts, const char *method, int *status ){ /* * Name: * OriginScale * Purpose: * Convert the TimeOrigin in a TimeFrame to a new timescale. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void OriginScale( AstTimeFrame *this, AstTimeScaleType newts, * const char *method, int *status ) * Class Membership: * TimeFrame member function * Description: * This function converts the value of the TimeOrigin attribute stored * within a supplied TimeFrame from the timescale currently associated * with the TimeFrame, to the new timescale indicated by "newts". * Parameters: * this * Point to the TimeFrame. On entry, the TimeOrigin value is * assumed to refer to the timescale given by the astGetTimeScale * method. On exit, the TimeOrigin value refers to the timescale * supplied in "newts". The TimeScale attribute of the TimeFrame * should then be modified in order to keep things consistent. * newts * The timescale to which the TimeOrigin value stored within "this" * should refer on exit. * method * Pointer to a string holding the name of the method to be * included in any error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMapping *map; AstSystemType sys; AstTimeScaleType oldts; const char *u; double newval; double oldval; /* Check the global error status. */ if ( !astOK ) return; /* Do nothing if the TimeOrigin attribute has not been assigned a value. */ if( astTestTimeOrigin( this ) ) { /* Do nothing if the Scale will not change. */ oldts = astGetTimeScale( this ); if( newts != oldts ) { /* Create a Mapping to perform the TimeScale change. */ sys = astGetSystem( this ); u = DefUnit( sys, method, "TimeFrame", status ), map = MakeMap( this, sys, sys, oldts, newts, 0.0, 0.0, u, u, method, status ); /* Use the Mapping to convert the stored TimeOrigin value. */ if( map ) { oldval = astGetTimeOrigin( this ); astTran1( map, 1, &oldval, 1, &newval ); /* Store the new value */ astSetTimeOrigin( this, newval ); /* Free resources */ map = astAnnul( map ); } else if( astOK ) { astError( AST__INCTS, "%s(%s): Cannot convert the TimeOrigin " "value to a different timescale because of " "incompatible time scales.", status, method, astGetClass( this ) ); } } } } static void OriginSystem( AstTimeFrame *this, AstSystemType oldsys, const char *method, int *status ){ /* * Name: * OriginSystem * Purpose: * Convert the TimeOrigin in a TimeFrame to a new System. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void OriginSystem( AstTimeFrame *this, AstSystemType oldsys, * const char *method, int *status ) * Class Membership: * TimeFrame member function * Description: * This function converts the value of the TimeOrigin attribute stored * within a supplied TimeFrame from its original System, etc, to the * System, etc, currently associated with the TimeFrame. * Parameters: * this * Point to the TimeFrame. On entry, the TimeOrigin value is * assumed to refer to the System given by "oldsys", etc. On exit, the * TimeOrigin value refers to the System returned by the astGetSystem * method, etc. * oldsys * The System to which the TimeOrigin value stored within "this" * refers on entry. * method * A string containing the method name for error messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMapping *map; AstSystemType newsys; AstTimeScaleType ts; const char *oldu; const char *newu; double newval; double oldval; /* Check the global error status. */ if ( !astOK ) return; /* Do nothing if the TimeOrigin attribute has not been assigned a value. */ if( astTestTimeOrigin( this ) ) { /* Do nothing if the System has not changed. */ newsys = astGetSystem( this ); if( oldsys != newsys ) { /* Create a Mapping to perform the System change. */ ts = astGetTimeScale( this ); oldu = DefUnit( oldsys, method, "TimeFrame", status ), newu = DefUnit( newsys, method, "TimeFrame", status ), map = MakeMap( this, oldsys, newsys, ts, ts, 0.0, 0.0, oldu, newu, method, status ); /* Use the Mapping to convert the stored TimeOrigin value. */ if( map ) { oldval = astGetTimeOrigin( this ); astTran1( map, 1, &oldval, 1, &newval ); /* Store the new value */ astSetTimeOrigin( this, newval ); /* Free resources */ map = astAnnul( map ); } else if( astOK ) { astError( AST__INCTS, "%s(%s): Cannot convert the TimeOrigin " "value to a different System because of incompatible " "time scales.", status, method, astGetClass( this ) ); } } } } static void Overlay( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { /* * Name: * Overlay * Purpose: * Overlay the attributes of a template TimeFrame on to another Frame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void Overlay( AstFrame *template, const int *template_axes, * AstFrame *result, int *status ) * Class Membership: * TimeFrame member function (over-rides the protected astOverlay method * inherited from the Frame class). * Description: * This function overlays attributes of a TimeFrame (the "template") on to * another Frame, so as to over-ride selected attributes of that second * Frame. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which a Frame acquires attributes from the template, but * retains its original attributes (as the default) if new values have not * previously been explicitly set in the template. * * Note that if the result Frame is a TimeFrame and a change of time * coordinate system occurs as a result of overlaying its System * attribute, then some of its original attribute values may no * longer be appropriate (e.g. the Title, or attributes describing * its axes). In this case, these will be cleared before overlaying * any new values. * Parameters: * template * Pointer to the template TimeFrame, for which values should have been * explicitly set for any attribute which is to be transferred. * template_axes * Pointer to an array of int, with one element for each axis of the * "result" Frame (see below). For each axis in the result frame, the * corresponding element of this array should contain the (zero-based) * index of the template axis to which it corresponds. This array is used * to establish from which template axis any axis-dependent attributes * should be obtained. * * If any axis in the result Frame is not associated with a template * axis, the corresponding element of this array should be set to -1. * * If a NULL pointer is supplied, the template and result axis * indices are assumed to be identical. * result * Pointer to the Frame which is to receive the new attribute values. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - In general, if the result Frame is not from the same class as the * template TimeFrame, or from a class derived from it, then attributes may * exist in the template TimeFrame which do not exist in the result Frame. * In this case, these attributes will not be transferred. */ /* Local Variables: */ AstSystemType new_alignsystem;/* Code identifying new alignment coords */ AstSystemType new_system; /* Code identifying new cordinates */ AstSystemType old_system; /* Code identifying old coordinates */ int resetSystem; /* Was the template System value cleared? */ int timeframe; /* Result Frame is a TimeFrame? */ /* Check the global error status. */ if ( !astOK ) return; /* Get the old and new systems. */ old_system = astGetSystem( result ); new_system = astGetSystem( template ); /* If the result Frame is a TimeFrame, we must test to see if overlaying its System attribute will change the type of coordinate system it describes. Determine the value of this attribute for the result and template TimeFrames. */ resetSystem = 0; timeframe = astIsATimeFrame( result ); if( timeframe ) { /* If the coordinate system will change, any value already set for the result TimeFrame's Title, etc, will no longer be appropriate, so clear it. */ if ( new_system != old_system ) { astClearTitle( result ); astClearLabel( result, 0 ); astClearSymbol( result, 0 ); } /* If the result Frame is not a TimeFrame, we must temporarily clear the System and AlignSystem values since the values used by this class are only appropriate to this class. */ } else { if( astTestSystem( template ) ) { astClearSystem( template ); new_alignsystem = astGetAlignSystem( template ); astClearAlignSystem( template ); resetSystem = 1; } } /* Invoke the parent class astOverlay method to transfer attributes inherited from the parent class. */ (*parent_overlay)( template, template_axes, result, status ); /* Reset the System and AlignSystem values if necessary */ if( resetSystem ) { astSetSystem( template, new_system ); astSetAlignSystem( template, new_alignsystem ); } /* Check if the result Frame is a TimeFrame or from a class derived from TimeFrame. If not, we cannot transfer TimeFrame attributes to it as it is insufficiently specialised. In this case simply omit these attributes. */ if ( timeframe && astOK ) { /* Define macros that test whether an attribute is set in the template and, if so, transfers its value to the result. */ #define OVERLAY(attribute) \ if ( astTest##attribute( template ) ) { \ astSet##attribute( result, astGet##attribute( template ) ); \ } /* Use the macro to transfer each TimeFrame attribute in turn. Note, SourceVRF must be overlayed before SourceVel. Otherwise the stored value for SourceVel would be changed from the default SourceVRF to the specified SourceVRF when SourceVRF was overlayed. */ OVERLAY(AlignTimeScale) OVERLAY(LTOffset) OVERLAY(TimeOrigin) OVERLAY(TimeScale) } /* Undefine macros local to this function. */ #undef OVERLAY } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * TimeFrame member function (extends the astSetAttrib method inherited from * the Mapping class). * Description: * This function assigns an attribute value for a TimeFrame, 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 TimeFrame. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This protected method is intended to be invoked by the Object astSet * method and makes additional attributes accessible to it. */ /* Local Vaiables: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ AstTimeScaleType ts; /* time scale type code */ char *a; /* Pointer to next character */ char *new_setting; /* Pointer value to new attribute setting */ double dval; /* Double atribute value */ double mjd; /* MJD read from setting */ double origin; /* TimeOrigin value */ int len; /* Length of setting string */ int namelen; /* Length of attribute name in setting */ int nc; /* Number of characters read by astSscanf */ int off; /* Offset of attribute value */ int rep; /* Original error reporting state */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) 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. */ /* First look for axis attributes defined by the Frame class. Since a TimeFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strncmp( setting, "direction=", 10 ) || !strncmp( setting, "bottom=", 7 ) || !strncmp( setting, "top=", 4 ) || !strncmp( setting, "format=", 7 ) || !strncmp( setting, "label=", 6 ) || !strncmp( setting, "symbol=", 7 ) || !strncmp( setting, "unit=", 5 ) ) { /* Create a new setting string from the original by appending the string "(1)" to the end of the attribute name and then use the parent SetAttrib method. */ new_setting = astMalloc( len + 4 ); if( new_setting ) { memcpy( new_setting, setting, len + 1 ); a = strchr( new_setting, '=' ); namelen = a - new_setting; memcpy( a, "(1)", 4 ); a += 3; strcpy( a, setting + namelen ); (*parent_setattrib)( this_object, new_setting, status ); new_setting = astFree( new_setting ); } /* AlignTimeScale. */ /* --------------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "aligntimescale=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a TimeScale code before use. */ ts = TimeScaleCode( setting + off, status ); if ( ts != AST__BADTS ) { astSetAlignTimeScale( this, ts ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid time scale " "description \"%s\".", status, astGetClass( this ), setting+off ); } /* ClockLat. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "clocklat=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { new_setting = astMalloc( sizeof( char )*(size_t) len + 1 ); new_setting[ 0 ] = 'o'; new_setting[ 1 ] = 'b'; new_setting[ 2 ] = 's'; strcpy( new_setting + 3, setting + 5 ); astSetAttrib( this, new_setting ); new_setting = astFree( new_setting ); /* ClockLon. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "clocklon=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { new_setting = astMalloc( sizeof( char )*(size_t) len + 1 ); new_setting[ 0 ] = 'o'; new_setting[ 1 ] = 'b'; new_setting[ 2 ] = 's'; strcpy( new_setting + 3, setting + 5 ); astSetAttrib( this, new_setting ); new_setting = astFree( new_setting ); /* LTOffset */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "ltoffset= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetLTOffset( this, dval ); /* TimeOrigin */ /* ---------- */ /* Floating-point without any units indication - assume the current Unit value. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "timeorigin= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetTimeOrigin( this, ToUnits( this, astGetUnit( this, 0 ), dval, "astSetTimeOrigin", status ) ); /* Floating-point with units. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "timeorigin= %lg %n%*s %n", &dval, &off, &nc ) ) && ( nc >= len ) ) { /* Defer error reporting in case a date string was given which starts with a floating point number, then convert the supplied value to the default units for the TimeFrame's System. */ rep = astReporting( 0 ); origin = ToUnits( this, setting + off, dval, "astSetTimeOrigin", status ); if( !astOK ) astClearStatus; astReporting( rep ); /* If the origin was converted, store it. */ if( origin != AST__BAD ) { astSetTimeOrigin( this, origin ); /* Otherwise, interpret the string as a date. Convert first to MJD then to default system. */ } else if ( nc = 0, ( 0 == astSscanf( setting, "timeorigin=%n%*[^\n]%n", &off, &nc ) ) && ( nc >= len ) ) { mjd = astReadDateTime( setting + off ); if ( astOK ) { astSetTimeOrigin( this, FromMJD( this, mjd, status ) ); /* Report contextual information if the conversion failed. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid TimeOrigin value " "\"%s\" given.", status, astGetClass( this ), setting + off ); } } /* String (assumed to be a date). Convert first to MJD then to default system. */ } else if ( nc = 0, ( 0 == astSscanf( setting, "timeorigin=%n%*[^\n]%n", &off, &nc ) ) && ( nc >= len ) ) { mjd = astReadDateTime( setting + off ); if ( astOK ) { astSetTimeOrigin( this, FromMJD( this, mjd, status ) ); /* Report contextual information if the conversion failed. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid TimeOrigin value " "\"%s\" given.", status, astGetClass( this ), setting + off ); } /* TimeScale. */ /* ---------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "timescale=%n%*s %n", &off, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a TimeScale code before use. */ ts = TimeScaleCode( setting + off, status ); if ( ts != AST__BADTS ) { astSetTimeScale( this, ts ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid time scale " "description \"%s\".", status, astGetClass( this ), setting + off ); } /* Pass any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetSystem( AstFrame *this_frame, AstSystemType newsys, int *status ) { /* * Name: * SetSystem * Purpose: * Set the System attribute for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void SetSystem( AstFrame *this_frame, AstSystemType newsys, int *status ) * Class Membership: * TimeFrame member function (over-rides the astSetSystem protected * method inherited from the Frame class). * Description: * This function sets the System attribute for a TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * newsys * The new System value to be stored. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to TimeFrame structure */ AstSystemType oldsys; /* Original System value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* If we are changing the System to BEPOCH, set the Unit attribute to "yr" and TimeScale to "TT". */ if( newsys == AST__BEPOCH ) { astSetUnit( this_frame, 0, "yr" ); astSetTimeScale( (AstTimeFrame *) this_frame, AST__TT ); } /* Save the original System value */ oldsys = astGetSystem( this_frame ); /* Use the parent SetSystem method to store the new System value. */ (*parent_setsystem)( this_frame, newsys, status ); /* If the system has changed... */ if( oldsys != newsys ) { /* Modify the stored TimeOrigin. */ OriginSystem( this, oldsys, "astSetSystem", status ); /* Clear all attributes which have system-specific defaults. */ astClearLabel( this_frame, 0 ); astClearSymbol( this_frame, 0 ); astClearTitle( this_frame ); } } static void SetTimeScale( AstTimeFrame *this, AstTimeScaleType value, int *status ) { /* *+ * Name: * astSetTimeScale * Purpose: * Set the TimeScale attribute for a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * void astSetTimeScale( AstTimeFrame *this, AstTimeScaleType value ) * Class Membership: * TimeFrame virtual function * Description: * This function set a new value for the TimeScale attribute for a * TimeFrame. * Parameters: * this * Pointer to the TimeFrame. * value * The new value. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Verify the supplied timescale value */ if( value < FIRST_TS || value > LAST_TS ) { astError( AST__ATTIN, "%s(%s): Bad value (%d) given for TimeScale " "attribute.", status, "astSetTimeScale", astGetClass( this ), (int) value ); /* Report an error if System is set to BEPOCH and an in appropriate TimeScale was supplied. */ } else if( astGetSystem( this ) == AST__BEPOCH && value != AST__TT ) { astError( AST__ATTIN, "%s(%s): Supplied TimeScale (%s) cannot be " "used because the %s represents Besselian Epoch which " "is defined in terms of TT.", status, "astSetTimeScale", astGetClass( this ), TimeScaleString( value, status ), astGetClass( this ) ); /* Otherwise set the new TimeScale */ } else { /* Modify the TimeOrigin value stored in the TimeFrame structure to refer to the new timescale. */ OriginScale( this, value, "astSetTimeScale", status ); /* Store the new value for the timescale in the TimeFrame structure. */ this->timescale = value; } } static void SetUnit( AstFrame *this_frame, int axis, const char *value, int *status ) { /* * Name: * SetUnit * Purpose: * Set a pointer to the Unit string for a TimeFrame's axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void SetUnit( AstFrame *this_frame, int axis, const char *value ) * Class Membership: * TimeFrame member function (over-rides the astSetUnit method inherited * from the Frame class). * Description: * This function stores a pointer to the Unit string for a specified axis * of a TimeFrame. It also stores the string in the "usedunits" array * in the TimeFrame structure, in the element associated with the * current System. * Parameters: * this * Pointer to the TimeFrame. * axis * The number of the axis (zero-based) for which information is required. * unit * The new string to store. */ /* Local Variables: */ AstTimeFrame *this; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astSetUnit" ); /* Report an error if System is set to BEPOCH and an in appropriate Unit was supplied. */ if( astGetSystem( this ) == AST__BEPOCH && strcmp( "yr", value ) ) { astError( AST__ATTIN, "astSetUnit(%s): Supplied Unit (%s) cannot " "be used because the %s represents Besselian Epoch which " "is defined in units of years (yr).", status, astGetClass( this ), value, astGetClass( this ) ); /* Otherwise use the parent SetUnit method to store the value in the Axis structure */ } else { (*parent_setunit)( this_frame, axis, value, status ); } } static AstTimeScaleType TimeScaleCode( const char *ts, int *status ) { /* * Name: * TimeScaleCode * Purpose: * Convert a string into a time scale type code. * Type: * Private function. * Synopsis: * #include "timeframe.h" * AstTimeScaleType TimeScaleCode( const char *ts ) * Class Membership: * TimeFrame member function. * Description: * This function converts a string used for the external description of * a time scale into a TimeFrame time scale type code (TimeScale attribute * value). It is the inverse of the TimeScaleString function. * Parameters: * ts * Pointer to a constant null-terminated string containing the * external description of the time scale. * Returned Value: * The TimeScale type code. * Notes: * - A value of AST__BADTS is returned if the time scale * description was not recognised. This does not produce an error. * - A value of AST__BADTS is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ AstTimeScaleType result; /* Result value to return */ /* Initialise. */ result = AST__BADTS; /* Check the global error status. */ if ( !astOK ) return result; /* Match the timescale string against each possibility and assign the result. */ if ( astChrMatch( "TAI", ts ) ) { result = AST__TAI; } else if ( astChrMatch( "UTC", ts ) ) { result = AST__UTC; } else if ( astChrMatch( "UT1", ts ) ) { result = AST__UT1; } else if ( astChrMatch( "GMST", ts ) ) { result = AST__GMST; } else if ( astChrMatch( "LAST", ts ) ) { result = AST__LAST; } else if ( astChrMatch( "LMST", ts ) ) { result = AST__LMST; } else if ( astChrMatch( "TT", ts ) ) { result = AST__TT; } else if ( astChrMatch( "TDB", ts ) ) { result = AST__TDB; } else if ( astChrMatch( "TCG", ts ) ) { result = AST__TCG; } else if ( astChrMatch( "TCB", ts ) ) { result = AST__TCB; } else if ( astChrMatch( "LT", ts ) ) { result = AST__LT; } /* Return the result. */ return result; } static const char *TimeScaleString( AstTimeScaleType ts, int *status ) { /* * Name: * TimeScaleString * Purpose: * Convert a time scale type code into a string. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *TimeScaleString( AstTimeScaleType ts, int *status ) * Class Membership: * TimeFrame member function. * Description: * This function converts a TimeFrame time scale type code (TimeScale * attribute value) into a string suitable for use as an external * representation of the time scale type. * Parameters: * ts * The time scale 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 time scale * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the timescale value against each possibility and convert to a string pointer. */ switch ( ts ) { case AST__TAI: result = "TAI"; break; case AST__UTC: result = "UTC"; break; case AST__UT1: result = "UT1"; break; case AST__GMST: result = "GMST"; break; case AST__LAST: result = "LAST"; break; case AST__LMST: result = "LMST"; break; case AST__TT: result = "TT"; break; case AST__TDB: result = "TDB"; break; case AST__TCB: result = "TCB"; break; case AST__TCG: result = "TCG"; break; case AST__LT: result = "LT"; break; } /* Return the result pointer. */ return result; } static int SubFrame( AstFrame *target_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 TimeFrame and convert to the new coordinate * system. * Type: * Private function. * Synopsis: * #include "timeframe.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: * TimeFrame 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 a "target" TimeFrame and creates a new Frame with copies of * the selected axes assembled in the requested order. It then * optionally overlays the attributes of a "template" Frame on to the * result. It returns both the resulting Frame and a Mapping that * describes how to convert between the coordinate systems described by * the target and result Frames. If necessary, this Mapping takes * account of any differences in the Frames' attributes due to the * influence of the template. * Parameters: * target * Pointer to the target TimeFrame, from which axes are to be * selected. * template * Pointer to the template Frame, from which new attributes for the * result Frame are to be obtained. Optionally, this may be NULL, in * which case no overlaying of template attributes will be performed. * result_naxes * Number of axes to be selected from the target Frame. This number may * be greater than or less than the number of axes in this Frame (or * equal). * target_axes * Pointer to an array of int with result_naxes elements, giving a list * of the (zero-based) axis indices of the axes to be selected from the * target TimeFrame. The order in which these are given determines * the order in which the axes appear in the result Frame. If any of the * values in this array is set to -1, the corresponding result axis will * not be derived from the target Frame, but will be assigned default * attributes instead. * template_axes * Pointer to an array of int with result_naxes elements. This should * contain a list of the template axes (given as zero-based axis indices) * with which the axes of the result Frame are to be associated. This * array determines which axes are used when overlaying axis-dependent * attributes of the template on to the result. If any element of this * array is set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not used and * a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned Mapping. * The forward transformation of this Mapping will describe how to * convert coordinates from the coordinate system described by the target * TimeFrame 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 target and the result Frame. Otherwise zero is returned and * *map and *result are returned as NULL (but this will not in itself * result in an error condition). In general, coordinate conversion should * always be possible if no template Frame is supplied but may not always * be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * Implementation Notes: * - This implementation addresses the selection of axes from a * TimeFrame object. This results in another object of the same class * only if the single TimeFrame axis is selected exactly once. * Otherwise, the result is a Frame class object which inherits the * TimeFrame's axis information (if appropriate) but none of the other * properties of a TimeFrame. * - In the event that a TimeFrame results, the returned Mapping will * take proper account of the relationship between the target and result * coordinate systems. * - In the event that a Frame class object results, the returned Mapping * will only represent a selection/permutation of axes. * Implementation Deficiencies: * - Any axis selection is currently permitted. Probably this should be * restricted so that each axis can only be selected once. The * astValidateAxisSelection method will do this but currently there are bugs * in the CmpFrame class that cause axis selections which will not pass this * test. Install the validation when these are fixed. */ /* Local Variables: */ AstTimeFrame *target; /* Pointer to the TimeFrame structure */ AstTimeFrame *temp; /* Pointer to copy of target TimeFrame */ AstTimeFrame *align_frm; /* Frame in which to align the TimeFrames */ int match; /* Coordinate conversion is possible? */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain a pointer to the target TimeFrame structure. */ target = (AstTimeFrame *) target_frame; /* Result is a TimeFrame. */ /* -------------------------- */ /* Check if the result Frame is to have one axis obtained by selecting the single target TimeFrame axis. If so, the result will also be a TimeFrame. */ if ( ( result_naxes == 1 ) && ( target_axes[ 0 ] == 0 ) ) { /* Form the result from a copy of the target. */ *result = astCopy( target ); /* If required, overlay the template attributes on to the result TimeFrame. Also choose the Frame which defined the alignment system and time scale (via its AlignSystem and AlignTimeScale attributes) in which to align the two TimeFrames. This is the template (if there is a template). */ if ( template ) { astOverlay( template, template_axes, *result ); if( astIsATimeFrame( template ) ) { align_frm = astClone( template ); } else { align_frm = astClone( target ); } /* If no template was supplied, align in the System and TimeScale of the target. */ } else { VerifyAttrs( target, "convert between different time systems", "TimeScale", "astMatch", status ); align_frm = astClone( target ); } /* Generate a Mapping that takes account of changes in the sky coordinate system (equinox, epoch, etc.) between the target TimeFrame and the result TimeFrame. If this Mapping can be generated, set "match" to indicate that coordinate conversion is possible. */ match = ( MakeTimeMapping( target, (AstTimeFrame *) *result, align_frm, 0, map, status ) != 0 ); /* Free resources. */ align_frm = astAnnul( align_frm ); /* Result is not a TimeFrame. */ /* ------------------------------ */ /* In this case, we select axes as if the target were from the Frame class. However, since the resulting data will then be separated from their enclosing TimeFrame, default attribute values may differ if the methods for obtaining them were over-ridden by the TimeFrame class. To overcome this, we ensure that these values are explicitly set for the result Frame (rather than relying on their defaults). */ } else { /* Make a temporary copy of the target TimeFrame. We will explicitly set the attribute values in this copy so as not to modify the original. */ temp = astCopy( target ); /* Define a macro to test if an attribute is set. If not, set it explicitly to its default value. */ #define SET(attribute) \ if ( !astTest##attribute( temp ) ) { \ astSet##attribute( temp, astGet##attribute( temp ) ); \ } /* Set attribute values which apply to the Frame as a whole and which we want to retain, but whose defaults are over-ridden by the TimeFrame class. */ SET(Domain) SET(Title) /* Define a macro to test if an attribute is set for axis zero (the only axis of a TimeFrame). If not, set it explicitly to its default value. */ #define SET_AXIS(attribute) \ if ( !astTest##attribute( temp, 0 ) ) { \ astSet##attribute( temp, 0, \ astGet##attribute( temp, 0 ) ); \ } /* Use this macro to set explicit values for all the axis attributes for which the TimeFrame class over-rides the default value. */ SET_AXIS(Label) SET_AXIS(Symbol) SET_AXIS(Unit) /* Clear attributes which have an extended range of values allowed by this class. */ astClearSystem( temp ); astClearAlignSystem( temp ); /* Invoke the astSubFrame method inherited from the Frame class to produce the result Frame by selecting the required set of axes and overlaying the template Frame's attributes. */ match = (*parent_subframe)( (AstFrame *) temp, template, result_naxes, target_axes, template_axes, map, result, status ); /* Delete the temporary copy of the target TimeFrame. */ temp = astDelete( temp ); } /* If an error occurred or no match was found, annul the returned objects and reset the returned result. */ if ( !astOK || !match ) { if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; /* Undefine macros local to this function. */ #undef SET #undef SET_AXIS } static AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) { /* * Name: * SystemCode * Purpose: * Convert a string into a coordinate system type code. * Type: * Private function. * Synopsis: * #include "timeframe.h" * AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) * Class Membership: * TimeFrame member function (over-rides the astSystemCode method * inherited from the Frame class). * Description: * This function converts a string used for the external description of * a coordinate system into a TimeFrame coordinate system type code * (System attribute value). It is the inverse of the astSystemString * function. * Parameters: * this * The Frame. * system * Pointer to a constant null-terminated string containing the * external description of the sky 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 sky coordinate * system description was not recognised. This does not produce an * error. * - A value of AST__BADSYSTEM is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ AstSystemType result; /* Result value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" string against each possibility and assign the result. */ if ( astChrMatch( "MJD", system ) || astChrMatch( "Modified Julian Date", system ) ) { result = AST__MJD; } else if ( astChrMatch( "JD", system ) || astChrMatch( "Julian Date", system ) ) { result = AST__JD; } else if ( astChrMatch( "BEPOCH", system ) || astChrMatch( "Besselian Epoch", system ) ) { result = AST__BEPOCH; } else if ( astChrMatch( "JEPOCH", system ) || astChrMatch( "Julian Epoch", system ) ) { result = AST__JEPOCH; } /* Return the result. */ return result; } static const char *SystemLabel( AstSystemType system, int *status ) { /* * Name: * SystemLabel * Purpose: * Return a label for a coordinate system type code. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *SystemLabel( AstSystemType system, int *status ) * Class Membership: * TimeFrame member function. * Description: * This function converts a TimeFrame coordinate system type code * (System attribute value) into a descriptive string for human readers. * Parameters: * 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 sky coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. */ switch ( system ) { case AST__MJD: result = "Modified Julian Date"; break; case AST__JD: result = "Julian Date"; break; case AST__JEPOCH: result = "Julian Epoch"; break; case AST__BEPOCH: result = "Besselian Epoch"; break; } /* Return the result pointer. */ return result; } static const char *SystemString( AstFrame *this, AstSystemType system, int *status ) { /* * Name: * SystemString * Purpose: * Convert a coordinate system type code into a string. * Type: * Private function. * Synopsis: * #include "timeframe.h" * const char *SystemString( AstFrame *this, AstSystemType system, int *status ) * Class Membership: * TimeFrame member function (over-rides the astSystemString method * inherited from the Frame class). * Description: * This function converts a TimeFrame coordinate system type code * (System attribute value) into a string suitable for use as an * external representation of the coordinate system type. * Parameters: * this * 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 sky coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. (Where possible, return the same string as would be used in the FITS WCS representation of the coordinate system). */ switch ( system ) { case AST__MJD: result = "MJD"; break; case AST__JD: result = "JD"; break; case AST__JEPOCH: result = "JEPOCH"; break; case AST__BEPOCH: result = "BEPOCH"; break; } /* Return the result pointer. */ return result; } static int TestActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * TestActiveUnit * Purpose: * Test the ActiveUnit flag for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int TestActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * TimeFrame member function (over-rides the astTestActiveUnit protected * method inherited from the Frame class). * Description: * This function test the value of the ActiveUnit flag for a TimeFrame, * which is always "unset". * Parameters: * this * Pointer to the TimeFrame. * status * Pointer to the inherited status variable. * Returned Value: * The result of the test (0). */ return 0; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * TimeFrame 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 TimeFrame's attributes. * Parameters: * this * Pointer to the TimeFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Returned Value: * One if a value has been set, otherwise zero. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ char *new_attrib; /* Pointer value to new attribute name */ int len; /* Length of attrib string */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* First look for axis attributes defined by the Frame class. Since a TimeFrame has only 1 axis, we allow these attributes to be specified without a trailing "(axis)" string. */ if ( !strcmp( attrib, "direction" ) || !strcmp( attrib, "bottom" ) || !strcmp( attrib, "top" ) || !strcmp( attrib, "format" ) || !strcmp( attrib, "label" ) || !strcmp( attrib, "symbol" ) || !strcmp( attrib, "unit" ) ) { /* Create a new attribute name from the original by appending the string "(1)" and then use the parent TestAttrib method. */ new_attrib = astMalloc( len + 4 ); if( new_attrib ) { memcpy( new_attrib, attrib, len ); memcpy( new_attrib + len, "(1)", 4 ); result = (*parent_testattrib)( this_object, new_attrib, status ); new_attrib = astFree( new_attrib ); } /* AlignTimeScale. */ /* --------------- */ } else if ( !strcmp( attrib, "aligntimescale" ) ) { result = astTestAlignTimeScale( this ); /* ClockLat. */ /* ------- */ } else if ( !strcmp( attrib, "clocklat" ) ) { result = astTestAttrib( this, "obslat" ); /* ClockLon. */ /* ------- */ } else if ( !strcmp( attrib, "clocklon" ) ) { result = astTestAttrib( this, "obslon" ); /* LTOffset. */ /* --------- */ } else if ( !strcmp( attrib, "ltoffset" ) ) { result = astTestLTOffset( this ); /* TimeOrigin. */ /* --------- */ } else if ( !strcmp( attrib, "timeorigin" ) ) { result = astTestTimeOrigin( this ); /* TimeScale. */ /* ---------- */ } else if ( !strcmp( attrib, "timescale" ) ) { result = astTestTimeScale( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static double ToMJD( AstSystemType oldsys, double oldval, int *status ){ /* * Name: * ToMJD * Purpose: * Convert a time value from TimeFrame's System to MJD. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double ToMJD( AstSystemType oldsys, double oldval, int *status ){ * Class Membership: * TimeFrame member function * Description: * This function converts the supplied value from the supplied System * to an MJD. * Parameters: * oldsys * The System in which the oldval is supplied. * oldval * The value to convert, assumed to be in the default units * associated with "oldsys". * status * Pointer to the inherited status variable. * Returned Value: * The MJD value corresponding to "oldval" * Notes: * - Both old and new value are assumed to be absolute (i.e. have zero * offset). */ /* Local Variables; */ AstMapping *map; double result; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* If the old system is MJD just return the value unchanged. */ if( oldsys == AST__MJD ) { result = oldval; /* Otherwise create a TimeMap wich converts from the TimeFrame system to MJD, and use it to transform the supplied value. */ } else { map = ToMJDMap( oldsys, 0.0, status ); /* Use the TimeMap to convert the supplied value. */ astTran1( map, 1, &oldval, 1, &result ); /* Free resources */ map = astAnnul( map ); } /* Return the result */ return result; } static AstMapping *ToMJDMap( AstSystemType oldsys, double off, int *status ){ /* * Name: * ToMJDMap * Purpose: * Create a Mapping from a specified System to MJD. * Type: * Private function. * Synopsis: * #include "timeframe.h" * AstMapping *ToMJDMap( AstSystemType oldsys, double off, int *status ){ * Class Membership: * TimeFrame member function * Description: * This function creates a Mapping which converts from the supplied * system and offset to absolute MJD. * Parameters: * oldsys * The System in which the oldval is supplied. * off * The axis offset used with the old System, assumed to be in the * default system associated with oldsys. * status * Pointer to the inherited status variable. * Returned Value: * The Mapping. */ /* Local Variables; */ AstTimeMap *timemap; double args[ 2 ]; /* Check the global error status. */ if ( !astOK ) return NULL; /* Create a null TimeMap */ timemap = astTimeMap( 0, "", status ); /* Set the offsets for the supplied and returned values. */ args[ 0 ] = off; args[ 1 ] = 0.0; /* If required, add a TimeMap conversion which converts from the TimeFrame system to MJD. */ if( oldsys == AST__MJD ) { /* if( off != 0.0 ) astTimeAdd( timemap, "MJDTOMJD", args ); */ astTimeAdd( timemap, "MJDTOMJD", args ); } else if( oldsys == AST__JD ) { astTimeAdd( timemap, "JDTOMJD", args ); } else if( oldsys == AST__JEPOCH ) { astTimeAdd( timemap, "JEPTOMJD", args ); } else if( oldsys == AST__BEPOCH ) { astTimeAdd( timemap, "BEPTOMJD", args ); } /* Return the result */ return (AstMapping *) timemap; } static double ToUnits( AstTimeFrame *this, const char *oldunit, double oldval, const char *method, int *status ){ /* * * Name: * ToUnits * Purpose: * Convert a supplied time value to the default units of the supplied TimeFrame. * Type: * Private function. * Synopsis: * #include "timeframe.h" * double ToUnits( AstTimeFrame *this, const char *oldunit, double oldval, * const char *method, int *status ) * Class Membership: * TimeFrame member function * Description: * This function converts the supplied time value from the supplied * units to the default units associated with the supplied TimeFrame's * System. * Parameters: * this * Pointer to the TimeFrame. * oldunit * The units in which "oldval" is supplied. * oldval * The value to be converted. * method * Pointer to a string holding the name of the method to be * included in any error messages. * status * Pointer to the inherited status variable. * Returned Value: * The converted value. */ /* Local Variables: */ AstMapping *map; const char *defunit; double result; /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Get default units associated with the System attribute of the supplied TimeFrame, and find a Mapping from the old units to the default. */ defunit = DefUnit( astGetSystem( this ), method, "TimeFrame", status ); map = astUnitMapper( oldunit, defunit, NULL, NULL ); if( map ) { /* Use the Mapping to convert the supplied value. */ astTran1( map, 1, &oldval, 1, &result ); /* Free resources. */ map = astAnnul( map ); /* Report an error if no conversion is possible. */ } else if( astOK ){ astError( AST__BADUN, "%s(%s): Cannot convert the supplied attribute " "value from units of %s to %s.", status, method, astGetClass( this ), oldunit, defunit ); } /* Return the result */ 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 TimeFrame axis. * Type: * Private function. * Synopsis: * #include "timeframe.h" * int Unformat( AstFrame *this, int axis, const char *string, * double *value, int *status ) * Class Membership: * TimeFrame member function (over-rides the public astUnformat * method inherited from the Frame class). * Description: * This function reads a formatted coordinate value for a TimeFrame * 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 TimeFrame. * axis * The number of the TimeFrame 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 "" 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: */ AstMapping *map; AstTimeFrame *this; AstTimeScaleType ts1; AstTimeScaleType ts2; const char *c; char *old_fmt; char *str; const char *txt; double mjd; double val1; int l; int lt; int nc1; int nc; int ndp; int rep; /* Initialise. */ nc = 0; /* Check the global error status. */ if ( !astOK ) return nc; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astUnformat" ); /* First attempt to read the value using the parent unformat method, and note how many characters were used. We temporarily clear the Format attribute if it has been set to a date format, since the parent Frame class does not understand date format.*/ txt = astGetFormat( this, axis ); if( DateFormat( txt, &ndp, NULL, status ) ) { old_fmt = astStore( NULL, txt, strlen( txt ) + 1 ); astClearFormat( this, axis ); } else { old_fmt = NULL; } nc1 = (*parent_unformat)( this_frame, axis, string, &val1, status ); /* Re-instate the original Format */ if( old_fmt ) { astSetFormat( this,axis, old_fmt ); old_fmt = astFree( old_fmt ); } /* The astReadDateTime function (defined within frame.c) does not allow for any extra text to be appended to the end of the formatted date/time (AST__BAD is returned if any such extra text is present). But astUnformat is contracted to allow such text. So we need to make multiple attempts at reading the date/time in order to find the longest leading string which gives a non-bad value. First take a copy of the supplied string si we can terminate it at any point we wish. */ l = astChrLen( string ); str = astStore( NULL, string, l + 1 ); /* Now attempt to read an ISO date from the start of the string. We switch off error reporting to avoid reports of unsuitable syntax. */ rep = astReporting( 0 ); /* Attempt to read a date/time from the whol string. If this fails terminate the string in order to make it one character shorter and try again. */ for( lt = l; lt > 0; lt-- ) { str[ lt ] = 0; mjd = astReadDateTime( str ); if( !astOK ) astClearStatus; if( mjd != AST__BAD ) break; } /* Re-instate error reporting. */ astReporting( rep ); /* Free resources. */ str = astFree( str ); /* If the whole non-blank start of the string was consumed, add on any trailing white space. */ if( lt >= l ) lt = strlen( string ); /* If no date/time could be read, or if reading the value as a floating point value was at least as good, return the floating point value (assumed to be in the system and units of the TimeFrame. */ if( mjd == AST__BAD || nc1 >= l ) { *value = val1; nc = nc1; /* Otherwise, if a date/time was read convert it to the TimeFrame system, etc. */ } else if( mjd != AST__BAD ) { /* Save the number of character read from the supplied string. */ nc = lt; /* We require a value in the timescale of the supplied TimeFrame. Get this TimeScale. */ ts2 = astGetTimeScale( this ); /* If the supplied string gave the date/time as a Besselian epoch, the input timescale is TT, otherwise it is assumed to be the TimeScale of the TimeFrame. Locate the first non-space character. */ c = string; while( *c && isspace( *c ) ) c++; /* If the first non-space is a "B", assuming a TT timescale. Otherwise assume the timescale of the supplied TimeFrame. */ ts1 = ( *c == 'B' || *c == 'b' ) ? AST__TT : ts2; /* Create the Mapping and use it to transform the mjd value. */ map = MakeMap( this, AST__MJD, astGetSystem( this ), ts1, ts2, 0.0, astGetTimeOrigin( this ), "d", astGetUnit( this, 0 ), "astFormat", status ); if( map ) { astTran1( map, 1, &mjd, 1, value ); map = astAnnul( map ); } else { astError( AST__INCTS, "astUnformat(%s): Cannot convert the " "supplied date/time string (%s) to the required " "timescale (%s).", status, astGetClass( this ), string, TimeScaleString( ts2, status ) ); } } /* Return the number of characters read. */ return nc; } static int ValidateSystem( AstFrame *this, AstSystemType system, const char *method, int *status ) { /* * * Name: * ValidateSystem * Purpose: * Validate a value for a Frame's System attribute. * Type: * Protected virtual function. * Synopsis: * #include "timeframe.h" * int ValidateSystem( AstFrame *this, AstSystemType system, * const char *method, int *status ) * Class Membership: * TimeFrame member function (over-rides the 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 */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* If the value is out of bounds, report an error. */ if ( system < FIRST_SYSTEM || system > LAST_SYSTEM ) { astError( AST__AXIIN, "%s(%s): Bad value (%d) given for the System " "or AlignSystem attribute of a %s.", status, method, astGetClass( this ), (int) system, astGetClass( this ) ); /* Otherwise, return the supplied value. */ } else { result = system; } /* Return the result. */ return result; } static void VerifyAttrs( AstTimeFrame *this, const char *purp, const char *attrs, const char *method, int *status ) { /* * Name: * VerifyAttrs * Purpose: * Verify that usable attribute values are available. * Type: * Private function. * Synopsis: * #include "timeframe.h" * void VerifyAttrs( AstTimeFrame *this, const char *purp, * const char *attrs, const char *method, int *status ) * Class Membership: * TimeFrame member function * Description: * This function tests each attribute listed in "attrs". It returns * without action if 1) an explicit value has been set for each attribute * or 2) the UseDefs attribute of the supplied TimeFrame is non-zero. * * If UseDefs is zero (indicating that default values should not be * used for attributes), and any of the named attributes does not have * an explicitly set value, then an error is reported. * Parameters: * this * Pointer to the TimeFrame. * purp * Pointer to a text string containing a message which will be * included in any error report. This shouldindicate the purpose * for which the attribute value is required. * attrs * A string holding a space separated list of attribute names. * method * A string holding the name of the calling method for use in error * messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *a; const char *desc; const char *p; int len; int set; int state; /* Check inherited status */ if( !astOK ) return; /* Stop compiler warnings about uninitialised variables */ a = NULL; desc = NULL; len = 0; set = 0; /* If the TimeFrame has a non-zero value for its UseDefs attribute, then all attributes are assumed to have usable values, since the defaults will be used if no explicit value has been set. So we only need to do any checks if UseDefs is zero. */ if( !astGetUseDefs( this ) ) { /* Loop round the "attrs" string identifying the start and length of each non-blank word in the string. */ state = 0; p = attrs; while( 1 ) { if( state == 0 ) { if( !isspace( *p ) ) { a = p; len = 1; state = 1; } } else { if( isspace( *p ) || !*p ) { /* The end of a word has just been reached. Compare it to each known attribute value. Get a flag indicating if the attribute has a set value, and a string describing the attribute.*/ if( len > 0 ) { if( !strncmp( "ObsLat", a, len ) ) { set = astTestObsLat( this ); desc = "observer latitude"; } else if( !strncmp( "ObsLon", a, len ) ) { set = astTestObsLon( this ); desc = "observer longitude"; } else if( !strncmp( "ObsAlt", a, len ) ) { set = astTestObsAlt( this ); desc = "observer altitude"; } else if( !strncmp( "Dut1", a, len ) ) { set = astTestDut1( this ); desc = "UT1-UTC correction"; } else if( !strncmp( "TimeOrigin", a, len ) ) { set = astTestTimeOrigin( this ); desc = "time offset"; } else if( !strncmp( "LTOffset", a, len ) ) { set = astTestLTOffset( this ); desc = "local time offset"; } else if( !strncmp( "TimeScale", a, len ) ) { set = astTestTimeScale( this ); desc = "time scale"; } else { astError( AST__INTER, "VerifyAttrs(TimeFrame): " "Unknown attribute name \"%.*s\" supplied (AST " "internal programming error).", status, len, a ); } /* If the attribute does not have a set value, report an error. */ if( !set && astOK ) { astError( AST__NOVAL, "%s(%s): Cannot %s.", status, method, astGetClass( this ), purp ); astError( AST__NOVAL, "No value has been set for " "the AST \"%.*s\" attribute (%s).", status, len, a, desc ); } /* Continue the word search algorithm. */ } len = 0; state = 0; } else { len++; } } if( !*(p++) ) break; } } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* *att++ * Name: * TimeOrigin * Purpose: * The zero point for TimeFrame axis values * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This specifies the origin from which all time values are measured. * The default value (zero) results in the TimeFrame describing * absolute time values in the system given by the System attribute * (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to * describe elapsed time since some origin, the TimeOrigin attribute * should be set to hold the required origin value. The TimeOrigin value * stored inside the TimeFrame structure is modified whenever TimeFrame * attribute values are changed so that it refers to the original moment * in time. * * Input Formats: * The formats accepted when setting a TimeOrigin value are listed * below. They are all case-insensitive and are generally tolerant * of extra white space and alternative field delimiters: * * - Besselian Epoch: Expressed in decimal years, with or without * decimal places ("B1950" or "B1976.13" for example). * * - Julian Epoch: Expressed in decimal years, with or without * decimal places ("J2000" or "J2100.9" for example). * * - Units: An unqualified decimal value is interpreted as a value in * the system specified by the TimeFrame's System attribute, in the * units given by the TimeFrame's Unit attribute. Alternatively, an * appropriate unit string can be appended to the end of the floating * point value ("123.4 d" for example), in which case the supplied value * is scaled into the units specified by the Unit attribute. * * - Julian Date: With or without decimal places ("JD 2454321.9" for * example). * * - Modified Julian Date: With or without decimal places * ("MJD 54321.4" for example). * * - Gregorian Calendar Date: With the month expressed either as an * integer or a 3-character abbreviation, and with optional decimal * places to represent a fraction of a day ("1996-10-2" or * "1996-Oct-2.6" for example). If no fractional part of a day is * given, the time refers to the start of the day (zero hours). * * - Gregorian Date and Time: Any calendar date (as above) but with * a fraction of a day expressed as hours, minutes and seconds * ("1996-Oct-2 12:13:56.985" for example). The date and time can be * separated by a space or by a "T" (as used by ISO8601 format). * Output Format: * When enquiring TimeOrigin values, the returned formatted floating * point value represents a value in the TimeFrame's System, in the unit * specified by the TimeFrame's Unit attribute. * Applicability: * TimeFrame * All TimeFrames have this attribute. *att-- */ /* The time origin, stored internally in the default units associated with the current System value. Clear the TimeOrigin value by setting it to AST__BAD, which gives 0.0 as the default value. Any value is acceptable. */ astMAKE_CLEAR(TimeFrame,TimeOrigin,timeorigin,AST__BAD) astMAKE_GET(TimeFrame,TimeOrigin,double,0.0,((this->timeorigin!=AST__BAD)?this->timeorigin:0.0)) astMAKE_SET(TimeFrame,TimeOrigin,double,timeorigin,value) astMAKE_TEST(TimeFrame,TimeOrigin,( this->timeorigin != AST__BAD )) /* *att++ * Name: * LTOffset * Purpose: * The offset from UTC to Local Time, in hours. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This specifies the offset from UTC to Local Time, in hours (fractional * hours can be supplied). It is positive for time zones east of Greenwich. * AST uses the figure as given, without making any attempt to correct for * daylight saving. The default value is zero. * Applicability: * TimeFrame * All TimeFrames have this attribute. *att-- */ astMAKE_CLEAR(TimeFrame,LTOffset,ltoffset,AST__BAD) astMAKE_GET(TimeFrame,LTOffset,double,0.0,((this->ltoffset!=AST__BAD)?this->ltoffset:0.0)) astMAKE_SET(TimeFrame,LTOffset,double,ltoffset,value) astMAKE_TEST(TimeFrame,LTOffset,( this->ltoffset != AST__BAD )) /* *att++ * Name: * AlignTimeScale * Purpose: * Time scale to use when aligning TimeFrames. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls how a TimeFrame behaves when it is used (by c astFindFrame or astConvert) as a template to match another (target) f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) * TimeFrame. It identifies the time scale in which alignment is * to occur. See the TimeScale attribute for a desription of the values * which may be assigned to this attribute. The default AlignTimeScale * value depends on the current value of TimeScale: if TimeScale is * UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all * other TimeScales the default is TAI. * c When astFindFrame or astConvert is used on two TimeFrames (potentially f When AST_FindFrame or AST_CONVERT is used on two TimeFrames (potentially * describing different time coordinate systems), it returns a Mapping * which can be used to transform a position in one TimeFrame into the * corresponding position in the other. The Mapping is made up of the * following steps in the indicated order: * * - Map values from the system used by the target (MJD, JD, etc) to the * system specified by the AlignSystem attribute. * * - Map these values from the target's time scale to the time scale * specified by the AlignTimeScale attribute. * * - Map these values from the time scale specified by the AlignTimeScale * attribute, to the template's time scale. * * - Map these values from the system specified by the AlignSystem * attribute, to the system used by the template. * Applicability: * TimeFrame * All TimeFrames have this attribute. *att-- */ astMAKE_TEST(TimeFrame,AlignTimeScale,( this->aligntimescale != AST__BADTS )) astMAKE_CLEAR(TimeFrame,AlignTimeScale,aligntimescale,AST__BADTS) astMAKE_SET(TimeFrame,AlignTimeScale,AstTimeScaleType,aligntimescale,( ( ( value >= FIRST_TS ) && ( value <= LAST_TS ) ) ? value : ( astError( AST__ATTIN, "%s(%s): Bad value (%d) " "given for AlignTimeScale attribute.", status, "astSetAlignTimeScale", astGetClass( this ), (int) value ), /* Leave the value unchanged on error. */ this->aligntimescale ) ) ) /* *att++ * Name: * TimeScale * Purpose: * Time scale. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute identifies the time scale to which the time axis values * of a TimeFrame refer, and may take any of the values listed in the * "Time Scales" section (below). * * The default TimeScale value depends on the current System value; if * the current TimeFrame system is "Besselian epoch" the default is * "TT", otherwise it is "TAI". Note, if the System attribute is set * so that the TimeFrame represents Besselian Epoch, then an error * will be reported if an attempt is made to set the TimeScale to * anything other than TT. * * Note, the supported time scales fall into two groups. The first group * containing UT1, GMST, LAST and LMST define time in terms of the * orientation of the earth. The second group (containing all the remaining * time scales) define time in terms of an atomic process. Since the rate of * rotation of the earth varies in an unpredictable way, conversion between * two timescales in different groups relies on a value being supplied for * the Dut1 attribute (defined by the parent Frame class). This attribute * specifies the difference between the UT1 and UTC time scales, in seconds, * and defaults to zero. See the documentation for the Dut1 attribute for * further details. * Applicability: * TimeFrame * All TimeFrames have this attribute. * Time Scales: * The TimeFrame class supports the following TimeScale values (all are * case-insensitive): * * - "TAI" - International Atomic Time * - "UTC" - Coordinated Universal Time * - "UT1" - Universal Time * - "GMST" - Greenwich Mean Sidereal Time * - "LAST" - Local Apparent Sidereal Time * - "LMST" - Local Mean Sidereal Time * - "TT" - Terrestrial Time * - "TDB" - Barycentric Dynamical Time * - "TCB" - Barycentric Coordinate Time * - "TCG" - Geocentric Coordinate Time * - "LT" - Local Time (the offset from UTC is given by attribute LTOffset) * * An very informative description of these and other time scales is * available at http://www.ucolick.org/~sla/leapsecs/timescales.html. * UTC Warnings: * UTC should ideally be expressed using separate hours, minutes and * seconds fields (or at least in seconds for a given date) if leap seconds * are to be taken into account. Since the TimeFrame class represents * each moment in time using a single floating point number (the axis value) * there will be an ambiguity during a leap second. Thus an error of up to * 1 second can result when using AST to convert a UTC time to another * time scale if the time occurs within a leap second. Leap seconds * occur at most twice a year, and are introduced to take account of * variation in the rotation of the earth. The most recent leap second * occurred on 1st January 1999. Although in the vast majority of cases * leap second ambiguities won't matter, there are potential problems in * on-line data acquisition systems and in critical applications involving * taking the difference between two times. *att-- */ astMAKE_TEST(TimeFrame,TimeScale,( this->timescale != AST__BADTS )) /* Copy constructor. */ /* ----------------- */ /* Destructor. */ /* ----------- */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for TimeFrame 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 TimeFrame class to an output Channel. * Parameters: * this * Pointer to the TimeFrame 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 Variables: */ AstTimeFrame *this; /* Pointer to the TimeFrame structure */ AstTimeScaleType ts; /* TimeScale attribute value */ const char *sval; /* Pointer to string value */ double dval; /* Double value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the TimeFrame structure. */ this = (AstTimeFrame *) this_object; /* Write out values representing the instance variables for the TimeFrame 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. */ /* TimeScale. */ /* ---------- */ set = TestTimeScale( this, status ); ts = set ? GetTimeScale( this, status ) : astGetTimeScale( this ); /* If set, convert explicitly to a string for the external representation. */ sval = ""; if ( set ) { if ( astOK ) { sval = TimeScaleString( ts, status ); /* Report an error if the TimeScale value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid time scale " "identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) ts ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "timescale" ); } /* Write out the value. */ astWriteString( channel, "TmScl", set, 1, sval, "Time scale" ); /* AlignTimeScale. */ /* --------------- */ set = TestAlignTimeScale( this, status ); ts = set ? GetAlignTimeScale( this, status ) : astGetAlignTimeScale( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = TimeScaleString( ts, status ); /* Report an error if the TimeScale value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "%s(%s): Corrupt %s contains invalid alignment time " "scale identification code (%d).", status, "astWrite", astGetClass( channel ), astGetClass( this ), (int) ts ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "aligntimescale" ); } /* Write out the value. */ astWriteString( channel, "ATmScl", set, 0, sval, "Alignment time scale" ); /* TimeOrigin. */ /* ----------- */ set = TestTimeOrigin( this, status ); dval = set ? GetTimeOrigin( this, status ) : astGetTimeOrigin( this ); astWriteDouble( channel, "TmOrg", set, 0, dval, "Time offset" ); /* LTOffset. */ /* --------- */ set = TestLTOffset( this, status ); dval = set ? GetLTOffset( this, status ) : astGetLTOffset( this ); astWriteDouble( channel, "LTOff", set, 0, dval, "Local Time offset from UTC" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsATimeFrame and astCheckTimeFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(TimeFrame,Frame) astMAKE_CHECK(TimeFrame) AstTimeFrame *astTimeFrame_( const char *options, int *status, ...) { /* *+ * Name: * astTimeFrame * Purpose: * Create a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * AstTimeFrame *astTimeFrame( const char *options, int *status, ... ) * Class Membership: * TimeFrame constructor. * Description: * This function creates a new TimeFrame and optionally initialises its * attributes. * Parameters: * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new TimeFrame. 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 TimeFrame. * 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 TimeFrame constructor which * is available via the protected interface to the TimeFrame class. * A public interface is provided by the astTimeFrameId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *um; /* Mapping from default to actual units */ AstTimeFrame *new; /* Pointer to new TimeFrame */ AstSystemType s; /* System */ const char *u; /* Units string */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the TimeFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTimeFrame( NULL, sizeof( AstTimeFrame ), !class_init, &class_vtab, "TimeFrame" ); /* 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 TimeFrame's attributes. */ va_start( args, status ); astVSet( new, options, NULL, args ); va_end( args ); /* Check the Units are appropriate for the System. */ u = astGetUnit( new, 0 ); s = astGetSystem( new ); um = astUnitMapper( DefUnit( s, "astTimeFrame", "TimeFrame", status ), u, NULL, NULL ); if( um ) { um = astAnnul( um ); } else { astError( AST__BADUN, "astTimeFrame: Inappropriate units (%s) " "specified for a %s axis.", status, u, SystemLabel( s, status ) ); } /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new TimeFrame. */ return new; } AstTimeFrame *astInitTimeFrame_( void *mem, size_t size, int init, AstTimeFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitTimeFrame * Purpose: * Initialise a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * AstTimeFrame *astInitTimeFrame( void *mem, size_t size, int init, * AstFrameVtab *vtab, const char *name ) * Class Membership: * TimeFrame initialiser. * Description: * This function is provided for use by class implementations to * initialise a new TimeFrame object. It allocates memory (if * necessary) to accommodate the TimeFrame plus any additional data * associated with the derived class. It then initialises a * TimeFrame 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 TimeFrame at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the TimeFrame is to be * created. This must be of sufficient size to accommodate the * TimeFrame data (sizeof(TimeFrame)) 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 TimeFrame (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 TimeFrame structure, so a valid value must be supplied * even if not required for allocating memory. * init * A logical flag indicating if the TimeFrame'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 TimeFrame. * 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). * Returned Value: * A pointer to the new TimeFrame. * 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: */ AstTimeFrame *new; /* Pointer to the new TimeFrame */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitTimeFrameVtab( vtab, name ); /* Initialise a 1D Frame structure (the parent class) as the first component within the TimeFrame structure, allocating memory if necessary. */ new = (AstTimeFrame *) astInitFrame( mem, size, 0, (AstFrameVtab *) vtab, name, 1 ); if ( astOK ) { /* Initialise the TimeFrame data. */ /* ----------------------------- */ /* Initialise all attributes to their "undefined" values. */ new->timeorigin = AST__BAD; new->ltoffset = AST__BAD; new->timescale = AST__BADTS; new->aligntimescale = AST__BADTS; /* 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; } AstTimeFrame *astLoadTimeFrame_( void *mem, size_t size, AstTimeFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadTimeFrame * Purpose: * Load a TimeFrame. * Type: * Protected function. * Synopsis: * #include "timeframe.h" * AstTimeFrame *astLoadTimeFrame( void *mem, size_t size, * AstTimeFrameVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * TimeFrame loader. * Description: * This function is provided to load a new TimeFrame 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 * TimeFrame structure in this memory, using data read from the * input Channel. * Parameters: * mem * A pointer to the memory into which the TimeFrame is to be * loaded. This must be of sufficient size to accommodate the * TimeFrame data (sizeof(TimeFrame)) 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 TimeFrame (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 TimeFrame 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(AstTimeFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new TimeFrame. If this is NULL, a pointer * to the (static) virtual function table for the TimeFrame 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 "TimeFrame" is used instead. * Returned Value: * A pointer to the new TimeFrame. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstTimeFrame *new; /* Pointer to the new TimeFrame */ char *sval; /* Pointer to string value */ double obslat; /* Value for ObsLat attribute */ double obslon; /* Value for ObsLon attribute */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this TimeFrame. In this case the TimeFrame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstTimeFrame ); vtab = &class_vtab; name = "TimeFrame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitTimeFrameVtab( 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 TimeFrame. */ 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, "TimeFrame" ); /* 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. */ /* TimeScale. */ /* ---------- */ /* Set the default and read the external representation as a string. */ new->timescale = AST__BADTS; sval = astReadString( channel, "tmscl", NULL ); /* If a value was read, convert from a string to a TimeScale code. */ if ( sval ) { if ( astOK ) { new->timescale = TimeScaleCode( sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->timescale == AST__BADTS ) { astError( AST__ATTIN, "astRead(%s): Invalid time scale description " "\"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* AlignTimeScale. */ /* --------------- */ /* Set the default and read the external representation as a string. */ new->aligntimescale = AST__BADTS; sval = astReadString( channel, "atmscl", NULL ); /* If a value was read, convert from a string to a TimeScale code. */ if ( sval ) { if ( astOK ) { new->aligntimescale = TimeScaleCode( sval, status ); /* Report an error if the value wasn't recognised. */ if ( new->aligntimescale == AST__BADTS ) { astError( AST__ATTIN, "astRead(%s): Invalid alignment time scale " "description \"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* ClockLat. */ /* --------- */ /* Retained for backward compatibility with older versions of AST in which TimeFrame had a ClockLat attribute (now ObsLat is used instead). */ if( !astTestObsLat( new ) ) { obslat = astReadDouble( channel, "cllat", AST__BAD ); if ( obslat != AST__BAD ) astSetObsLat( new, obslat ); } /* ClockLon. */ /* ------- */ /* Retained for backward compatibility with older versions of AST in which TimeFrame had a ClockLon attribute (now ObsLon is used instead). */ if( !astTestObsLon( new ) ) { obslon = astReadDouble( channel, "cllon", AST__BAD ); if ( obslon != AST__BAD ) astSetObsLon( new, obslon ); } /* TimeOrigin. */ /* --------- */ new->timeorigin = astReadDouble( channel, "tmorg", AST__BAD ); if ( TestTimeOrigin( new, status ) ) SetTimeOrigin( new, new->timeorigin, status ); /* LTOffset. */ /* --------- */ new->ltoffset = astReadDouble( channel, "ltoff", AST__BAD ); if ( TestLTOffset( new, status ) ) SetLTOffset( new, new->ltoffset, status ); /* If an error occurred, clean up by deleting the new TimeFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new TimeFrame pointer. */ return new; } /* 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 astSetTimeScale_( AstTimeFrame *this, AstTimeScaleType value, int *status ){ if ( !astOK ) return; (**astMEMBER(this,TimeFrame,SetTimeScale))(this,value, status ); } void astClearTimeScale_( AstTimeFrame *this, int *status ){ if ( !astOK ) return; (**astMEMBER(this,TimeFrame,ClearTimeScale))(this, status ); } AstTimeScaleType astGetAlignTimeScale_( AstTimeFrame *this, int *status ) { if ( !astOK ) return AST__BADTS; return (**astMEMBER(this,TimeFrame,GetAlignTimeScale))(this, status ); } AstTimeScaleType astGetTimeScale_( AstTimeFrame *this, int *status ) { if ( !astOK ) return AST__BADTS; return (**astMEMBER(this,TimeFrame,GetTimeScale))(this, status ); } double astCurrentTime_( AstTimeFrame *this, int *status ){ if ( !astOK ) return AST__BAD; return (**astMEMBER(this,TimeFrame,CurrentTime))(this, 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. */ AstTimeFrame *astTimeFrameId_( const char *, ... ); /* Special interface function implementations. */ /* ------------------------------------------- */ AstTimeFrame *astTimeFrameId_( const char *options, ... ) { /* *++ * Name: c astTimeFrame f AST_TIMEFRAME * Purpose: * Create a TimeFrame. * Type: * Public function. * Synopsis: c #include "timeframe.h" c AstTimeFrame *astTimeFrame( const char *options, ... ) f RESULT = AST_TIMEFRAME( OPTIONS, STATUS ) * Class Membership: * TimeFrame constructor. * Description: * This function creates a new TimeFrame and optionally initialises * its attributes. * * A TimeFrame is a specialised form of one-dimensional Frame which * represents various coordinate systems used to describe positions in * time. * * A TimeFrame represents a moment in time as either an Modified Julian * Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, * as determined by the System attribute. Optionally, a zero point can be * specified (using attribute TimeOrigin) which results in the TimeFrame * representing time offsets from the specified zero point. * * Even though JD and MJD are defined as being in units of days, the * TimeFrame class allows other units to be used (via the Unit attribute) * on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 * hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs * can be described in units other than the usual years. Besselian epoch * are always represented in units of (tropical) years. * * The TimeScale attribute allows the time scale to be specified (that * is, the physical proces used to define the rate of flow of time). * MJD, JD and Julian epoch can be used to represent a time in any * supported time scale. However, Besselian epoch may only be used with the * "TT" (Terrestrial Time) time scale. The list of supported time scales * includes universal time and siderial time. Strictly, these represent * angles rather than time scales, but are included in the list since * they are in common use and are often thought of as time scales. * * When a time value is formatted it can be formated either as a simple * floating point value, or as a Gregorian date (see the Format * attribute). * Parameters: 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 TimeFrame. 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 TimeFrame. 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 astTimeFrame() f AST_TIMEFRAME = INTEGER * A pointer to the new TimeFrame. * Notes: * - When conversion between two TimeFrames is requested (as when c supplying TimeFrames to astConvert), f supplying TimeFrames AST_CONVERT), * account will be taken of the nature of the time coordinate systems * they represent, together with any qualifying time scale, offset, * unit, etc. The AlignSystem and AlignTimeScale attributes will also be * taken into account. * - 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 astTimeFrame constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astTimeFrame_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astTimeFrame_ directly, so it must be a * re-implementation of it in all respects, except for the final * conversion of the result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMapping *um; /* Mapping from default to actual units */ AstTimeFrame *new; /* Pointer to new TimeFrame */ AstSystemType s; /* System */ const char *u; /* Units string */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the TimeFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitTimeFrame( NULL, sizeof( AstTimeFrame ), !class_init, &class_vtab, "TimeFrame" ); /* 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 TimeFrame's attributes. */ va_start( args, options ); astVSet( new, options, NULL, args ); va_end( args ); /* Check the Units are appropriate for the System. */ u = astGetUnit( new, 0 ); s = astGetSystem( new ); um = astUnitMapper( DefUnit( s, "astTimeFrame", "TimeFrame", status ), u, NULL, NULL ); if( um ) { um = astAnnul( um ); } else { astError( AST__BADUN, "astTimeFrame: Inappropriate units (%s) " "specified for a %s axis.", status, u, SystemLabel( s, status ) ); } /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return an ID value for the new TimeFrame. */ return astMakeId( new ); } ast-8.3.0/channel.h0000664000175000017500000006665313004147321011030 00000000000000/* *+ * Name: * channel.h * Type: * C include file. * Purpose: * Define the interface to the Channel class. * Invocation: * #include "channel.h" * Description: * This include file defines the interface to the Channel class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * A Channel is the basic form of AST I/O channel, through which * Objects may be written and later read back. It causes I/O to * take place using a textual format via standard input and * standard output. * * Writing to a Channel will result in a textual representation of * an Object being produced on standard output. Reading from a * Channel will causes a textual description of an Object to be * read from standard input, and that Object to be * re-created. Channel I/O is stream based, and multiple objects * may be written or read in succession through the same Channel. A * null Object pointer is returned if there is no more input to * read. * Inheritance: * The Channel class inherits from the Object class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Comment (integer) * A boolean value (0 or 1) which controls whether comments are * to be included in textual output generated by a Channel. If * this value is non-zero (the default), then comments will be * included. If it is zero, comments will be omitted. * Full (integer) * A three-state flag (taking values -1, 0 or +1) which controls * the amount of information included in textual output * generated by a Channel. If this value is zero (the default), * then a modest amount of non-essential but useful information * will be included along with the output. If Full is negative, * all non-essential information will be suppressed, while if it * is positive, the output will include the maximum amount of * information about the Object being written. * Skip (integer) * A boolean value which indicates whether the Objects being * read through a Channel are inter-mixed with other external * data. If this value is zero (the default), then the source of * input data is expected to contain descriptions of AST Objects * and comments and nothing else (if anything else is read, an * error will result). If Skip is non-zero, then any non-Object * data encountered between Objects will simply be skipped over * in order to reach the next Object. * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a Mapping. * astGetAttrib * Get an attribute value for a Mapping. * astSetAttrib * Set an attribute value for a Mapping. * astTestAttrib * Test if an attribute value has been set for a Mapping. * New Methods Defined: * Public: * astRead * Read an Object from a Channel. * astWrite * Write an Object to a Channel. * * Protected: * astClearComment * Clear the Comment attribute for a Channel. * astClearFull * Clear the Full attribute for a Channel. * astClearSkip * Clear the Skip attribute for a Channel. * astGetComment * Get the value of the Comment attribute for a Channel. * astGetFull * Get the value of the Full attribute for a Channel. * astGetNextData * Read the next item of data from a data source. * astGetNextText * Read the next line of input text from a data source. * astGetSkip * Get the value of the Skip attribute for a Channel. * astPutNextText * Write a line of output text to a data sink. * astReadClassData * Read values from a data source for a class loader. * astReadDouble * Read a double value as part of loading a class. * astReadInt * Read an int value as part of loading a class. * astReadObject * Read a (sub)Object as part of loading a class. * astReadString * Read a string value as part of loading a class. * astSetComment * Set the value of the Comment attribute for a Channel. * astSetFull * Set the value of the Full attribute for a Channel. * astSetSkip * Set the value of the Skip attribute for a Channel. * astTestComment * Test whether a value has been set for the Comment attribute of a * Channel. * astTestFull * Test whether a value has been set for the Full attribute of a * Channel. * astTestSkip * Test whether a value has been set for the Skip attribute of a * Channel. * astWriteBegin * Write a "Begin" data item to a data sink. * astWriteDouble * Write a double value to a data sink. * astWriteEnd * Write an "End" data item to a data sink. * astWriteInt * Write an integer value to a data sink. * astWriteIsA * Write an "IsA" data item to a data sink. * astWriteObject * Write an Object as a value to a data sink. * astWriteString * Write a string value to a data sink. * Other Class Functions: * Public: * astChannel * Create a Channel. * astChannelFor * Create a Channel from a foreign language interface. * astIsAChannel * Test class membership. * * Protected: * astCheckChannel * Validate class membership. * astInitChannel * Initialise a Channel. * astInitChannelVtab * Initialise the virtual function table for the Channel class. * astLoadChannel * Load a Channel. * Type Definitions: * Public: * AstChannel * Channel object type. * * Protected: * AstChannelVtab * Channel virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 12-AUG-1996 (RFWS): * Original version. * 12-DEC-1996 (RFWS): * Added the astChannelFor function. * 11-NOV-2002 (DSB): * Added astWriteInvocations. * 8-JAN-2003 (DSB): * Added protected astInitAxisVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ /* Note that the usual setting of the CHANNEL_INCLUDED flag, which prevents this file being included more than once, must be deferred until after including the "object.h" file. This is because "object.h" needs to include the present interface definition (as a form of "forward reference") in order to have access to I/O Channels itself. */ #if !defined( CHANNEL_INCLUDED ) #define CHANNEL_INCLUDED /* C header files. */ /* --------------- */ #include /* Macros */ /* ====== */ /* Define constants used to size global arrays in this module. */ #define AST__CHANNEL_GETATTRIB_BUFF_LEN 50 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* The astWarnings function returns a KeyMap pointer, but we cannot include keymap.h here to define the AstKeyMap type since keymap.h itself include sthis file. So we make a temporary declaration which will be replaced by the full one when the keymap.h file is included. */ struct AstKeyMap; /* Channel structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstChannel { /* Attributes inherited from the parent class. */ AstObject object; /* Parent class structure */ /* Attributes specific to objects in this class. */ const char *(* source)( void ); /* Pointer to source function */ char *(* source_wrap)( const char *(*)(void), int * ); /* Source wrapper function pointer */ void (* sink)( const char * ); /* Pointer to sink function */ void (* sink_wrap)( void (*)( const char *), const char *, int * ); /* Sink wrapper function pointer */ int comment; /* Output comments? */ int full; /* Set max/normal/min information level */ int skip; /* Skip data between Objects? */ int indent; /* Indentation increment in astWrite output */ int report_level; /* Skip data between Objects? */ int strict; /* Report unexpected data items? */ void *data; /* Data to pass to source/sink functions */ char **warnings; /* Array of warning strings */ int nwarn; /* Size of warnings array */ FILE *fd_in; /* Descriptor for source text file */ char *fn_in; /* Full path for source text file */ FILE *fd_out; /* Descriptor for sink text file */ char *fn_out; /* Full path for sink text file */ } AstChannel; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstChannelVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstObjectVtab object_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ struct AstKeyMap *(* Warnings)( AstChannel *, int * ); AstObject *(* Read)( AstChannel *, int * ); AstObject *(* ReadObject)( AstChannel *, const char *, AstObject *, int * ); char *(* GetNextText)( AstChannel *, int * ); char *(* ReadString)( AstChannel *, const char *, const char *, int * ); double (* ReadDouble)( AstChannel *, const char *, double, int * ); int (* GetComment)( AstChannel *, int * ); int (* GetFull)( AstChannel *, int * ); int (* GetStrict)( AstChannel *, int * ); int (* ReadInt)( AstChannel *, const char *, int, int * ); int (* TestComment)( AstChannel *, int * ); int (* TestFull)( AstChannel *, int * ); int (* TestStrict)( AstChannel *, int * ); int (* Write)( AstChannel *, AstObject *, int * ); void (* AddWarning)( AstChannel *, int, const char *, const char *, int * ); void (* ClearComment)( AstChannel *, int * ); void (* ClearFull)( AstChannel *, int * ); void (* ClearStrict)( AstChannel *, int * ); void (* GetNextData)( AstChannel *, int, char **, char **, int * ); void (* PutChannelData)( AstChannel *, void *, int * ); void (* PutNextText)( AstChannel *, const char *, int * ); void (* ReadClassData)( AstChannel *, const char *, int * ); void (* SetComment)( AstChannel *, int, int * ); void (* SetFull)( AstChannel *, int, int * ); void (* SetStrict)( AstChannel *, int, int * ); void (* WriteBegin)( AstChannel *, const char *, const char *, int * ); void (* WriteDouble)( AstChannel *, const char *, int, int, double, const char *, int * ); void (* WriteEnd)( AstChannel *, const char *, int * ); void (* WriteInt)( AstChannel *, const char *, int, int, int, const char *, int * ); void (* WriteIsA)( AstChannel *, const char *, const char *, int * ); void (* WriteObject)( AstChannel *, const char *, int, int, AstObject *, const char *, int * ); void (* WriteString)( AstChannel *, const char *, int, int, const char *, const char *, int * ); int (* GetSkip)( AstChannel *, int * ); int (* TestSkip)( AstChannel *, int * ); void (* ClearSkip)( AstChannel *, int * ); void (* SetSkip)( AstChannel *, int, int * ); int (* GetReportLevel)( AstChannel *, int * ); int (* TestReportLevel)( AstChannel *, int * ); void (* ClearReportLevel)( AstChannel *, int * ); void (* SetReportLevel)( AstChannel *, int, int * ); int (* GetIndent)( AstChannel *, int * ); int (* TestIndent)( AstChannel *, int * ); void (* ClearIndent)( AstChannel *, int * ); void (* SetIndent)( AstChannel *, int, int * ); const char *(* GetSourceFile)( AstChannel *, int * ); int (* TestSourceFile)( AstChannel *, int * ); void (* ClearSourceFile)( AstChannel *, int * ); void (* SetSourceFile)( AstChannel *, const char *, int * ); const char *(* GetSinkFile)( AstChannel *, int * ); int (* TestSinkFile)( AstChannel *, int * ); void (* ClearSinkFile)( AstChannel *, int * ); void (* SetSinkFile)( AstChannel *, const char *, int * ); } AstChannelVtab; /* Define a private structure type used to store linked lists of name-value associations. */ typedef struct AstChannelValue { struct AstChannelValue *flink; /* Link to next element */ struct AstChannelValue *blink; /* Link to previous element */ char *name; /* Pointer to name string */ union { /* Holds pointer to value */ char *string; /* Pointer to string value */ AstObject *object; /* Pointer to Object value */ } ptr; int is_object; /* Whether value is an Object (else string) */ } AstChannelValue; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstChannelGlobals { AstChannelVtab Class_Vtab; int Class_Init; int AstReadClassData_Msg; char GetAttrib_Buff[ AST__CHANNEL_GETATTRIB_BUFF_LEN + 1 ]; int Items_Written; int Current_Indent; int Nest; int Nwrite_Invoc; char **Object_Class; AstChannelValue **Values_List; char **Values_Class; int *Values_OK; int *End_Of_Object; void *Channel_Data; } AstChannelGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Channel) /* Check class membership */ astPROTO_ISA(Channel) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstChannel *astChannel_( const char *(*)( void ), void (*)( const char * ), const char *, int *, ...); #else AstChannel *astChannelId_( const char *(*)( void ), void (*)( const char * ), const char *, ... )__attribute__((format(printf,3,4))); AstChannel *astChannelForId_( const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), const char *, ... ); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstChannel *astInitChannel_( void *, size_t, int, AstChannelVtab *, const char *, const char *(*)( void ), char *(*)( const char *(*)( void ), int * ), void (*)( const char * ), void (*)( void (*)( const char * ), const char *, int * ), int * ); /* Vtab initialiser. */ void astInitChannelVtab_( AstChannelVtab *, const char *, int * ); /* Loader. */ AstChannel *astLoadChannel_( void *, size_t, AstChannelVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitChannelGlobals_( AstChannelGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstObject *astRead_( AstChannel *, int * ); int astWrite_( AstChannel *, AstObject *, int * ); void astPutChannelData_( AstChannel *, void *, int * ); void *astChannelData_( void ); struct AstKeyMap *astWarnings_( AstChannel *, int * ); char *astSourceWrap_( const char *(*)( void ), int * ); void astSinkWrap_( void (*)( const char * ), const char *, int * ); # if defined(astCLASS) /* Protected */ void astStoreChannelData_( AstChannel *, int * ); AstObject *astReadObject_( AstChannel *, const char *, AstObject *, int * ); char *astGetNextText_( AstChannel *, int * ); char *astReadString_( AstChannel *, const char *, const char *, int * ); double astReadDouble_( AstChannel *, const char *, double, int * ); int astGetComment_( AstChannel *, int * ); int astGetFull_( AstChannel *, int * ); int astGetStrict_( AstChannel *, int * ); int astReadInt_( AstChannel *, const char *, int, int * ); int astTestComment_( AstChannel *, int * ); int astTestFull_( AstChannel *, int * ); int astTestStrict_( AstChannel *, int * ); void astAddWarning_( void *, int, const char *, const char *, int *, ... )__attribute__((format(printf,3,6))); void astClearComment_( AstChannel *, int * ); void astClearFull_( AstChannel *, int * ); void astClearStrict_( AstChannel *, int * ); void astGetNextData_( AstChannel *, int, char **, char **, int * ); void astPutNextText_( AstChannel *, const char *, int * ); void astReadClassData_( AstChannel *, const char *, int * ); void astSetComment_( AstChannel *, int, int * ); void astSetFull_( AstChannel *, int, int * ); void astSetStrict_( AstChannel *, int, int * ); void astWriteBegin_( AstChannel *, const char *, const char *, int * ); void astWriteDouble_( AstChannel *, const char *, int, int, double, const char *, int * ); void astWriteEnd_( AstChannel *, const char *, int * ); void astWriteInt_( AstChannel *, const char *, int, int, int, const char *, int * ); int astWriteInvocations_( int * ); void astWriteIsA_( AstChannel *, const char *, const char *, int * ); void astWriteObject_( AstChannel *, const char *, int, int, AstObject *, const char *, int * ); void astWriteString_( AstChannel *, const char *, int, int, const char *, const char *, int * ); int astGetSkip_( AstChannel *, int * ); int astTestSkip_( AstChannel *, int * ); void astClearSkip_( AstChannel *, int * ); void astSetSkip_( AstChannel *, int, int * ); int astGetReportLevel_( AstChannel *, int * ); int astTestReportLevel_( AstChannel *, int * ); void astClearReportLevel_( AstChannel *, int * ); void astSetReportLevel_( AstChannel *, int, int * ); int astGetIndent_( AstChannel *, int * ); int astTestIndent_( AstChannel *, int * ); void astClearIndent_( AstChannel *, int * ); void astSetIndent_( AstChannel *, int, int * ); const char *astGetSourceFile_( AstChannel *, int * ); int astTestSourceFile_( AstChannel *, int * ); void astClearSourceFile_( AstChannel *, int * ); void astSetSourceFile_( AstChannel *, const char *, int * ); const char *astGetSinkFile_( AstChannel *, int * ); int astTestSinkFile_( AstChannel *, int * ); void astClearSinkFile_( AstChannel *, int * ); void astSetSinkFile_( AstChannel *, const char *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckChannel(this) astINVOKE_CHECK(Channel,this,0) #define astVerifyChannel(this) astINVOKE_CHECK(Channel,this,1) /* Test class membership. */ #define astIsAChannel(this) astINVOKE_ISA(Channel,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astChannel astINVOKE(F,astChannel_) #else #define astChannel astINVOKE(F,astChannelId_) #define astChannelFor astINVOKE(F,astChannelForId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitChannel(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap) \ astINVOKE(O,astInitChannel_(mem,size,init,vtab,name,source,source_wrap,sink,sink_wrap,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitChannelVtab(vtab,name) astINVOKE(V,astInitChannelVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadChannel(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadChannel_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckChannel to validate Channel pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astRead(this) \ astINVOKE(O,astRead_(astCheckChannel(this),STATUS_PTR)) #define astWrite(this,object) \ astINVOKE(V,astWrite_(astCheckChannel(this),astCheckObject(object),STATUS_PTR)) #define astPutChannelData(this,data) \ astINVOKE(V,astPutChannelData_(astCheckChannel(this),data,STATUS_PTR)) #define astWarnings(this) \ astINVOKE(O,astWarnings_(astCheckChannel(this),STATUS_PTR)) #define astSourceWrap astSourceWrap_ #define astSinkWrap astSinkWrap_ #define astChannelData astChannelData_() #if defined(astCLASS) /* Protected */ #define astAddWarning astAddWarning_ #define astStoreChannelData(this) \ astStoreChannelData_(astCheckChannel(this),STATUS_PTR) #define astClearComment(this) \ astINVOKE(V,astClearComment_(astCheckChannel(this),STATUS_PTR)) #define astClearFull(this) \ astINVOKE(V,astClearFull_(astCheckChannel(this),STATUS_PTR)) #define astClearStrict(this) \ astINVOKE(V,astClearStrict_(astCheckChannel(this),STATUS_PTR)) #define astGetComment(this) \ astINVOKE(V,astGetComment_(astCheckChannel(this),STATUS_PTR)) #define astGetFull(this) \ astINVOKE(V,astGetFull_(astCheckChannel(this),STATUS_PTR)) #define astGetNextData(this,begin,name,val) \ astINVOKE(V,astGetNextData_(astCheckChannel(this),begin,name,val,STATUS_PTR)) #define astGetNextText(this) \ astINVOKE(V,astGetNextText_(astCheckChannel(this),STATUS_PTR)) #define astGetStrict(this) \ astINVOKE(V,astGetStrict_(astCheckChannel(this),STATUS_PTR)) #define astPutNextText(this,line) \ astINVOKE(V,astPutNextText_(astCheckChannel(this),line,STATUS_PTR)) #define astReadClassData(this,class) \ astINVOKE(V,astReadClassData_(astCheckChannel(this),class,STATUS_PTR)) #define astReadDouble(this,name,def) \ astINVOKE(V,astReadDouble_(astCheckChannel(this),name,def,STATUS_PTR)) #define astReadInt(this,name,def) \ astINVOKE(V,astReadInt_(astCheckChannel(this),name,def,STATUS_PTR)) #define astReadObject(this,name,def) \ astINVOKE(O,astReadObject_(astCheckChannel(this),name,(def)?astCheckObject(def):NULL,STATUS_PTR)) #define astReadString(this,name,def) \ astINVOKE(V,astReadString_(astCheckChannel(this),name,def,STATUS_PTR)) #define astSetComment(this,value) \ astINVOKE(V,astSetComment_(astCheckChannel(this),value,STATUS_PTR)) #define astSetFull(this,value) \ astINVOKE(V,astSetFull_(astCheckChannel(this),value,STATUS_PTR)) #define astSetStrict(this,value) \ astINVOKE(V,astSetStrict_(astCheckChannel(this),value,STATUS_PTR)) #define astTestComment(this) \ astINVOKE(V,astTestComment_(astCheckChannel(this),STATUS_PTR)) #define astTestFull(this) \ astINVOKE(V,astTestFull_(astCheckChannel(this),STATUS_PTR)) #define astTestStrict(this) \ astINVOKE(V,astTestStrict_(astCheckChannel(this),STATUS_PTR)) #define astWriteBegin(this,class,comment) \ astINVOKE(V,astWriteBegin_(astCheckChannel(this),class,comment,STATUS_PTR)) #define astWriteDouble(this,name,set,helpful,value,comment) \ astINVOKE(V,astWriteDouble_(astCheckChannel(this),name,set,helpful,value,comment,STATUS_PTR)) #define astWriteEnd(this,class) \ astINVOKE(V,astWriteEnd_(astCheckChannel(this),class,STATUS_PTR)) #define astWriteInt(this,name,set,helpful,value,comment) \ astINVOKE(V,astWriteInt_(astCheckChannel(this),name,set,helpful,value,comment,STATUS_PTR)) #define astWriteIsA(this,class,comment) \ astINVOKE(V,astWriteIsA_(astCheckChannel(this),class,comment,STATUS_PTR)) #define astWriteObject(this,name,set,helpful,value,comment) \ astINVOKE(V,astWriteObject_(astCheckChannel(this),name,set,helpful,astCheckObject(value),comment,STATUS_PTR)) #define astWriteString(this,name,set,helpful,value,comment) \ astINVOKE(V,astWriteString_(astCheckChannel(this),name,set,helpful,value,comment,STATUS_PTR)) #define astWriteInvocations astWriteInvocations_(STATUS_PTR) #define astClearSkip(this) \ astINVOKE(V,astClearSkip_(astCheckChannel(this),STATUS_PTR)) #define astGetSkip(this) \ astINVOKE(V,astGetSkip_(astCheckChannel(this),STATUS_PTR)) #define astSetSkip(this,value) \ astINVOKE(V,astSetSkip_(astCheckChannel(this),value,STATUS_PTR)) #define astTestSkip(this) \ astINVOKE(V,astTestSkip_(astCheckChannel(this),STATUS_PTR)) #define astClearReportLevel(this) \ astINVOKE(V,astClearReportLevel_(astCheckChannel(this),STATUS_PTR)) #define astGetReportLevel(this) \ astINVOKE(V,astGetReportLevel_(astCheckChannel(this),STATUS_PTR)) #define astSetReportLevel(this,value) \ astINVOKE(V,astSetReportLevel_(astCheckChannel(this),value,STATUS_PTR)) #define astTestReportLevel(this) \ astINVOKE(V,astTestReportLevel_(astCheckChannel(this),STATUS_PTR)) #define astClearIndent(this) \ astINVOKE(V,astClearIndent_(astCheckChannel(this),STATUS_PTR)) #define astGetIndent(this) \ astINVOKE(V,astGetIndent_(astCheckChannel(this),STATUS_PTR)) #define astSetIndent(this,value) \ astINVOKE(V,astSetIndent_(astCheckChannel(this),value,STATUS_PTR)) #define astTestIndent(this) \ astINVOKE(V,astTestIndent_(astCheckChannel(this),STATUS_PTR)) #define astClearSourceFile(this) \ astINVOKE(V,astClearSourceFile_(astCheckChannel(this),STATUS_PTR)) #define astGetSourceFile(this) \ astINVOKE(V,astGetSourceFile_(astCheckChannel(this),STATUS_PTR)) #define astSetSourceFile(this,value) \ astINVOKE(V,astSetSourceFile_(astCheckChannel(this),value,STATUS_PTR)) #define astTestSourceFile(this) \ astINVOKE(V,astTestSourceFile_(astCheckChannel(this),STATUS_PTR)) #define astClearSinkFile(this) \ astINVOKE(V,astClearSinkFile_(astCheckChannel(this),STATUS_PTR)) #define astGetSinkFile(this) \ astINVOKE(V,astGetSinkFile_(astCheckChannel(this),STATUS_PTR)) #define astSetSinkFile(this,value) \ astINVOKE(V,astSetSinkFile_(astCheckChannel(this),value,STATUS_PTR)) #define astTestSinkFile(this) \ astINVOKE(V,astTestSinkFile_(astCheckChannel(this),STATUS_PTR)) #endif #endif ast-8.3.0/fstc.c0000664000175000017500000000632313004147321010336 00000000000000/* *+ * Name: * fstc.c * Purpose: * Define a FORTRAN 77 interface to the AST Stc class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Stc class. * Routines Defined: * AST_ISASTC * AST_GETSTCREGION * AST_GETSTCCOORD * AST_GETSTCNCOORD * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-NOV-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "stc.h" /* C interface to the Stc class */ F77_INTEGER_FUNCTION(ast_getstcncoord)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETSTCNCOORD", NULL, 0 ); astWatchSTATUS( RESULT = astGetStcNCoord( astI2P( *THIS ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_getstccoord)( INTEGER(THIS), INTEGER(ICOORD), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(ICOORD) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETSTCCOORD", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetStcCoord( astI2P( *THIS ), *ICOORD ) ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isastc)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASTC", NULL, 0 ); astWatchSTATUS( RESULT = astIsAStc( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_getstcregion)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_GETSTCREGION", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astGetStcRegion( astI2P( *THIS ) ) ); ) return RESULT; } ast-8.3.0/pg3d.h0000664000175000017500000000407513004147321010243 00000000000000#if !defined( PG3D_INCLUDED ) /* Include this file only once */ #define PG3D_INCLUDED /* *+ * Name: * pg3d.h * Type: * C include file. * Purpose: * Define the interface to the pg3d module * Invocation: * #include "pg3d.h" * Description: * This include file defines the interface to the pg3d module * (implemented in file grf3d_pgplot.c) and provides the type * definitions, function prototypes and macros, etc. needed to * use this module. * * The functions in the pg3d interface provide control of the view * of the 3D world coordinate system visible on the 2D PGPLOT * viewport. They are provided for users of the PGPLOT implementation * of the grf3D interface distributed with AST. No calls to these * functions are made from within AST itself. * Copyright: * Copyright (C) 2007 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (JACH - UCLan) * History: * 20-JUN-2007 (DSB): * Original version. *- */ int PG3DRotateEye( int, float ); int PG3DSetCamera( float[3], float[3], float[3], float ); int PG3DSetEye( float[3] ); int PG3DSetTarget( float[3] ); int PG3DSetUp( float[3] ); int PG3DSetScreen( float ); int PG3DForward( float ); int PG3DAutoCamera( float[3], float[3] ); int PG3DFindNearest( int, float *, float *, float *, int * ); #endif ast-8.3.0/memory.h0000664000175000017500000003070113004147321010711 00000000000000#if !defined( MEMORY_INCLUDED ) /* Include this file only once */ #define MEMORY_INCLUDED /* *+ * Name: * memory.h * Purpose: * Define the interface to the Memory module. * Description: * This module defines functions which wrap up and extend the * standard C functions for performing memory allocation. They * provide better security against memory leaks, etc., and should * not be inter-mixed with the standard C functions. * * Note that this module is not a class implementation, although it * resembles one. * Functions Defined: * Public: * None. * * Protected: * astAppendString * Append a string to another string which grows dynamically. * astCalloc * Allocate memory. * astChrMatch * Case-insensitive string comparison. * astChrMatchN * Case-insensitive string comparison of an most N characters. * astFree * Free previously allocated memory. * astGrow * Allocate memory for an adjustable array. * astMalloc * Allocate memory. * astRealloc * Change the size of a dynamically allocated region of memory. * astSizeOf * Determine the size of a dynamically allocated region of memory. * astStore * Store data in dynamically allocated memory. * astString * Create a C string from an array of characters. * astStringArray * Create an array of C strings from an array of characters. * astStringCase * Convert a string to upper or lower case. * astChrLen * Returns length of a string without trailing white space, etc. * astChrTrunc * Terminate a string to exclude trailing spaces. * astSscanf * Like sscanf, but fixes certain platform-specific bugs in the * native sscanf implementation. * astTSizeOf * Determine the total size of a dynamically allocated region of memory. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: D.S. Berry (Starlink) * History: * 8-JAN-1996 (RFWS): * Original version. * 26-JAN-1996 (RFWS) * Added function interfaces. * 20-JUN-1996 (RFWS): * Added astString. * 15-JUL-1996 (RFWS): * Use improved prologue style, etc. and make all functions protected. * 11-SEP-1996 (RFWS): * Added astStringArray (original written by DSB). * 18-MAR-1998 (RFWS): * Make interface available for writing foreign language and * graphics interfaces, etc. * 18-MAR-1998 (RFWS): * Added explicit arguments to function macros. * 29-JAN-2002 (DSB): * Added astChrLen and astSscanf. * 15-NOV-2002 (DSB): * Added astChrMatch astChrMatchN. * 23-FEB-2006 (DSB): * Added astMemCaching and AST__TUNULL. * 2-MAR-2006 (DSB): * Only use astSscanf if the system on which AST was configured * showed the non-ANSI behaviour reported by Bill Joye. * 27-JUN-2007 (DSB): * Added astIsDynamic. * 25-OCT-2007 (DSB): * Added astRemoveLeadingBlanks. * 22-FEB-2008 (DSB): * Added astChrSub. * 19-MAY-2010 (DSB): * Added astStringCase. * 26-MAR-2015 (DSB): * Added astChrTrunc. *- */ /* Include files. */ /* ============== */ /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* C header files. */ /* --------------- */ #include #include "error.h" /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__TUNULL -99999 #define AST__TUNULLC "" /* Type definitions */ /* ================ */ #if defined(astCLASS) /* Header for allocated memory. */ /* ---------------------------- */ /* This stores a "magic" value so that dynamically allocated memory can be recognised, together with the allocated size. It also ensures correct alignment. */ typedef struct Memory { struct Memory *next; unsigned long magic; size_t size; #ifdef MEM_DEBUG struct Memory *prev; /* Pointer to the previous linked Memory structure */ int id; /* A unique identifier for every allocated memory chunk */ int perm; /* Is this chunk part of an acceptable once-off "memory leak"? */ int line; /* Line number in "file" (below). */ char file[50];/* The source file that made the top-level call to AST */ #endif } Memory; /* Define the largest size of a cached memory block in bytes. This does not include the size of the Memory header. This does not need to be too big because the vast majority of memory blocks allocated by AST are less than a few hundred bytes. */ #define MXCSIZE 300 #endif #if defined(THREAD_SAFE) && defined(astCLASS) /* Define a structure holding all data items that are global within the memory.c file. */ typedef struct AstMemoryGlobals { size_t Sizeof_Memory; int Cache_Init; int Use_Cache; Memory *Cache[ MXCSIZE + 1 ]; } AstMemoryGlobals; #endif /* Function prototypes. */ /* ==================== */ #if defined(THREAD_SAFE) && defined(astCLASS) void astInitMemoryGlobals_( AstMemoryGlobals * ); #endif #if defined(astCLASS) || 1 /* Nominally protected, but available for */ /* use in developing (e.g.) foreign */ /* language or graphics interfaces. */ int astMemCaching_( int, int * ); void astChrCase_( const char *, char *, int, int, int * ); char **astChrSplit_( const char *, int *, int * ); char **astChrSplitRE_( const char *, const char *, int *, const char **, int * ); char **astChrSplitC_( const char *, char, int *, int * ); int astChrMatch_( const char *, const char *, int * ); int astChrMatchN_( const char *, const char *, size_t, int * ); char **astStringArray_( const char *, int, int, int * ); char *astStringCase_( const char *, int, int * ); char *astString_( const char *, int, int * ); int astSscanf_( const char *str, const char *format, ...); size_t astSizeOf_( const void *, int * ); int astIsDynamic_( const void *, int * ); size_t astTSizeOf_( const void *, int * ); void *astFree_( void *, int * ); void *astFreeDouble_( void *, int * ); void *astGrow_( void *, int, size_t, int * ); void *astCalloc_( size_t, size_t, int * ); void *astMalloc_( size_t, int, int * ); void *astRealloc_( void *, size_t, int * ); void *astStore_( void *, const void *, size_t, int * ); size_t astChrLen_( const char *, int * ); double astChr2Double_( const char *, int * ); void astRemoveLeadingBlanks_( char *, int * ); char *astAppendString_( char *, int *, const char *, int * ); char *astAppendStringf_( char *, int *, const char *, ... )__attribute__((format(printf,3,4))); char *astChrSub_( const char *, const char *, const char *[], int, int * ); void astChrTrunc_( char *, int * ); #ifdef MEM_PROFILE void astStartTimer_( const char *, int, const char *, int * ); void astStopTimer_( int * ); void astEnableTimers_( int, int * ); #endif #ifdef MEM_DEBUG void astActiveMemory_( const char * ); void astWatchMemory_( int ); void astCheckMemory_( int * ); void astFlushMemory_( int, int * ); int astMemoryTune_( const char *, int, int * ); void *astMemoryPtr_( int ); void astMemoryAlarm_( const char * ); void astMemoryStats_( int , size_t *, size_t *, int * ); void astMemoryWarning_( size_t, int * ); void astMemoryUse_( const void *, const char *, int * ); int astMemoryId_( const void *, int * ); void astBeginPM_( int * ); void astEndPM_( int * ); #endif #endif /* Function interfaces. */ /* ==================== */ /* These wrap up the functions defined by this module. */ #define astCalloc(nmemb,size) astERROR_INVOKE(astCalloc_(nmemb,size,STATUS_PTR)) #define astChrMatch(str1,str2) astERROR_INVOKE(astChrMatch_(str1,str2,STATUS_PTR)) #define astChrMatchN(str1,str2,n) astERROR_INVOKE(astChrMatchN_(str1,str2,n,STATUS_PTR)) #define astFree(ptr) astERROR_INVOKE(astFree_(ptr,STATUS_PTR)) #define astFreeDouble(ptr) astERROR_INVOKE(astFreeDouble_(ptr,STATUS_PTR)) #define astGrow(ptr,n,size) astERROR_INVOKE(astGrow_(ptr,n,size,STATUS_PTR)) #define astMalloc(size) astERROR_INVOKE(astMalloc_(size,0,STATUS_PTR)) #define astMemCaching(flag) astERROR_INVOKE(astMemCaching_(flag,STATUS_PTR)) #define astRealloc(ptr,size) astERROR_INVOKE(astRealloc_(ptr,size,STATUS_PTR)) #define astSizeOf(ptr) astERROR_INVOKE(astSizeOf_(ptr,STATUS_PTR)) #define astIsDynamic(ptr) astERROR_INVOKE(astIsDynamic_(ptr,STATUS_PTR)) #define astTSizeOf(ptr) astERROR_INVOKE(astTSizeOf_(ptr,STATUS_PTR)) #define astStore(ptr,data,size) astERROR_INVOKE(astStore_(ptr,data,size,STATUS_PTR)) #define astAppendString(str1,nc,str2) astERROR_INVOKE(astAppendString_(str1,nc,str2,STATUS_PTR)) #define astAppendStringf astAppendStringf_ #define astString(chars,nchars) astERROR_INVOKE(astString_(chars,nchars,STATUS_PTR)) #define astStringArray(chars,nel,len) astERROR_INVOKE(astStringArray_(chars,nel,len,STATUS_PTR)) #define astStringCase(string,toupper) astERROR_INVOKE(astStringCase_(string,toupper,STATUS_PTR)) #define astChrLen(string) astERROR_INVOKE(astChrLen_(string,STATUS_PTR)) #define astChrTrunc(string) astERROR_INVOKE(astChrTrunc_(string,STATUS_PTR)) #define astChr2Double(string) astERROR_INVOKE(astChr2Double_(string,STATUS_PTR)) #define astRemoveLeadingBlanks(string) astERROR_INVOKE(astRemoveLeadingBlanks_(string,STATUS_PTR)) #define astChrSub(test,template,subs,nsub) astERROR_INVOKE(astChrSub_(test,template,subs,nsub,STATUS_PTR)) #define astChrCase(in,out,upper,blen) astERROR_INVOKE(astChrCase_(in,out,upper,blen,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astMallocInit(size) astMalloc_(size,1,STATUS_PTR) #endif #ifdef HAVE_NONANSI_SSCANF #define astSscanf astERROR_INVOKE(astSscanf_) #else #define astSscanf astERROR_INVOKE(sscanf) #endif #define astChrSplit(str,n) astERROR_INVOKE(astChrSplit_(str,n,STATUS_PTR)) #define astChrSplitC(str,c,n) astERROR_INVOKE(astChrSplitC_(str,c,n,STATUS_PTR)) #define astChrSplitRE(str,c,n,m) astERROR_INVOKE(astChrSplitRE_(str,c,n,m,STATUS_PTR)) #ifdef MEM_PROFILE #define astStartTimer(name) astERROR_INVOKE(astStartTimer_(__FILE__,__LINE__,name,STATUS_PTR)) #define astStopTimer astERROR_INVOKE(astStopTimer_(STATUS_PTR)) #define astEnableTimers(enable) astERROR_INVOKE(astEnableTimers_(enable,STATUS_PTR)) #endif /* Functions used for debugging memory leaks, etc */ #ifdef MEM_DEBUG #define astActiveMemory(label) astERROR_INVOKE(astActiveMemory_(label)) #define astMemoryTune(name,value) astERROR_INVOKE(astMemoryTune_(name,value,STATUS_PTR)) #define astWatchMemory(id) astERROR_INVOKE(astWatchMemory_(id)) #define astCheckMemory astERROR_INVOKE(astCheckMemory_(STATUS_PTR)) #define astFlushMemory(leak) astERROR_INVOKE(astFlushMemory_(leak,STATUS_PTR)) #define astBeginPM astERROR_INVOKE(astBeginPM_(STATUS_PTR)) #define astEndPM astERROR_INVOKE(astEndPM_(STATUS_PTR)) #define astMemoryPtr(id) astERROR_INVOKE(astMemoryPtr_(id)) #define astMemoryAlarm(text) astERROR_INVOKE(astMemoryAlarm_(text)) #define astMemoryStats(reset,peak,current) astERROR_INVOKE(astMemoryStats_(reset,peak,current,STATUS_PTR)) #define astMemoryWarning(threshold) astERROR_INVOKE(astMemoryWarning_(threshold,STATUS_PTR)) #define astMemoryUse(ptr,text) astERROR_INVOKE(astMemoryUse_(ptr,text,STATUS_PTR)) #define astMemoryId(ptr) astERROR_INVOKE(astMemoryId_(ptr,STATUS_PTR)) #else #define astActiveMemory(label) #define astMemoryTune(name,value) #define astWatchMemory(id) #define astCheckMemory #define astFlushMemory(leak) #define astBeginPM #define astEndPM #define astMemoryPtr(id) NULL #define astMemoryAlarm(text) #define astMemoryStats(reset,peak,current) #define astMemoryUse(ptr,text) #define astMemoryId(ptr) #define astMemoryWarning(threshold) #endif #endif ast-8.3.0/mathmap.c0000664000175000017500000111336013004147321011027 00000000000000/* *class++ * Name: * MathMap * Purpose: * Transform coordinates using mathematical expressions. * Constructor Function: c astMathMap f AST_MATHMAP * Description: c A MathMap is a Mapping which allows you to specify a set of forward c and/or inverse transformation functions using arithmetic operations c and mathematical functions similar to those available in C. The c MathMap interprets these functions at run-time, whenever its forward c or inverse transformation is required. Because the functions are not c compiled in the normal sense (unlike an IntraMap), they may be used to c describe coordinate transformations in a transportable manner. A c MathMap therefore provides a flexible way of defining new types of c Mapping whose descriptions may be stored as part of a dataset and c interpreted by other programs. f A MathMap is a Mapping which allows you to specify a set of forward f and/or inverse transformation functions using arithmetic operations f and mathematical functions similar to those available in Fortran. The f MathMap interprets these functions at run-time, whenever its forward f or inverse transformation is required. Because the functions are not f compiled in the normal sense (unlike an IntraMap), they may be used to f describe coordinate transformations in a transportable manner. A f MathMap therefore provides a flexible way of defining new types of f Mapping whose descriptions may be stored as part of a dataset and f interpreted by other programs. * Inheritance: * The MathMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * MathMap also has the following attributes: * - Seed: Random number seed * - SimpFI: Forward-inverse MathMap pairs simplify? * - SimpIF: Inverse-forward MathMap pairs simplify? * Functions: c The MathMap class does not define any new functions beyond those f The MathMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 3-SEP-1999 (RFWS): * Original version. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitMathMapVtab * method. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 14-MAR-2006 (DSB): * - Add QIF function. * - Override astEqual method. * 20-NOV-2006 (DSB): * Re-implement the Equal method to avoid use of astSimplify. * 30-AUG-2012 (DSB): * Fix bug in undocumented Gaussian noise function. *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 MathMap /* Allocate pointer array. */ /* ----------------------- */ /* This macro allocates an array of pointers. If successful, each element of the array is initialised to NULL. */ #define MALLOC_POINTER_ARRAY(array_name,array_type,array_size) \ \ /* Allocate the array. */ \ (array_name) = astMalloc( sizeof(array_type) * (size_t) (array_size) ); \ if ( astOK ) { \ \ /* If successful, loop to initialise each element. */ \ int array_index_; \ for ( array_index_ = 0; array_index_ < (array_size); array_index_++ ) { \ (array_name)[ array_index_ ] = NULL; \ } \ } /* Free pointer array. */ /* ------------------- */ /* This macro frees a dynamically allocated array of pointers, each of whose elements may point at a further dynamically allocated array (which is also to be freed). It also allows for the possibility of any of the pointers being NULL. */ #define FREE_POINTER_ARRAY(array_name,array_size) \ \ /* Check that the main array pointer is not NULL. */ \ if ( (array_name) ) { \ \ /* If OK, loop to free each of the sub-arrays. */ \ int array_index_; \ for ( array_index_ = 0; array_index_ < (array_size); array_index_++ ) { \ \ /* Check that each sub-array pointer is not NULL before freeing it. */ \ if ( (array_name)[ array_index_ ] ) { \ (array_name)[ array_index_ ] = \ astFree( (array_name)[ array_index_ ] ); \ } \ } \ \ /* Free the main pointer array. */ \ (array_name) = astFree( (array_name) ); \ } /* SizeOf pointer array. */ /* --------------------- */ /* This macro increments "result" by the number of bytes allocated for an array of pointers, each of whose elements may point at a further dynamically allocated array (which is also to be included). It also allows for the possibility of any of the pointers being NULL. */ #define SIZEOF_POINTER_ARRAY(array_name,array_size) \ \ /* Check that the main array pointer is not NULL. */ \ if ( (array_name) ) { \ \ /* If OK, loop to measure each of the sub-arrays. */ \ int array_index_; \ for ( array_index_ = 0; array_index_ < (array_size); array_index_++ ) { \ \ /* Check that each sub-array pointer is not NULL before measuring it. */ \ if ( (array_name)[ array_index_ ] ) { \ result += astTSizeOf( (array_name)[ array_index_ ] ); \ } \ } \ \ /* Include the main pointer array. */ \ result += astTSizeOf( (array_name) ); \ } /* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "channel.h" /* I/O channels */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "cmpmap.h" /* Compound Mappings */ #include "mathmap.h" /* Interface definition for this class */ #include "memory.h" /* Memory allocation facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points */ #include "unitmap.h" /* Unit Mapping */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include #include /* Module Variables. */ /* ================= */ /* This type is made obscure since it is publicly accessible (but not useful). Provide shorthand for use within this module. */ typedef AstMathMapRandContext_ Rcontext; /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); /* This declaration enumerates the operation codes recognised by the EvaluateFunction function which evaluates arithmetic expressions. */ typedef enum { /* User-supplied constants and variables. */ OP_LDCON, /* Load constant */ OP_LDVAR, /* Load variable */ /* System constants. */ OP_LDBAD, /* Load bad value (AST__BAD) */ OP_LDDIG, /* Load # decimal digits (DBL_DIG) */ OP_LDEPS, /* Load relative precision (DBL_EPSILON) */ OP_LDMAX, /* Load largest value (DBL_MAX) */ OP_LDMAX10E, /* Max. decimal exponent (DBL_MAX_10_EXP) */ OP_LDMAXE, /* Load maximum exponent (DBL_MAX_EXP) */ OP_LDMDIG, /* Load # mantissa digits (DBL_MANT_DIG) */ OP_LDMIN, /* Load smallest value (DBL_MIN) */ OP_LDMIN10E, /* Min. decimal exponent (DBL_MIN_10_EXP) */ OP_LDMINE, /* Load minimum exponent (DBL_MIN_EXP) */ OP_LDRAD, /* Load floating radix (FLT_RADIX) */ OP_LDRND, /* Load rounding mode (FLT_ROUNDS) */ /* Mathematical constants. */ OP_LDE, /* Load e (base of natural logarithms) */ OP_LDPI, /* Load pi */ /* Functions with one argument. */ OP_ABS, /* Absolute value (sign removal) */ OP_ACOS, /* Inverse cosine (radians) */ OP_ACOSD, /* Inverse cosine (degrees) */ OP_ACOSH, /* Inverse hyperbolic cosine */ OP_ACOTH, /* Inverse hyperbolic cotangent */ OP_ACSCH, /* Inverse hyperbolic cosecant */ OP_ASECH, /* Inverse hyperbolic secant */ OP_ASIN, /* Inverse sine (radians) */ OP_ASIND, /* Inverse sine (degrees) */ OP_ASINH, /* Inverse hyperbolic sine */ OP_ATAN, /* Inverse tangent (radians) */ OP_ATAND, /* Inverse tangent (degrees) */ OP_ATANH, /* Inverse hyperbolic tangent */ OP_CEIL, /* C ceil function (round up) */ OP_COS, /* Cosine (radians) */ OP_COSD, /* Cosine (degrees) */ OP_COSH, /* Hyperbolic cosine */ OP_COTH, /* Hyperbolic cotangent */ OP_CSCH, /* Hyperbolic cosecant */ OP_EXP, /* Exponential function */ OP_FLOOR, /* C floor function (round down) */ OP_INT, /* Integer value (round towards zero) */ OP_ISBAD, /* Test for bad value */ OP_LOG, /* Natural logarithm */ OP_LOG10, /* Base 10 logarithm */ OP_NINT, /* Fortran NINT function (round to nearest) */ OP_POISS, /* Poisson random number */ OP_SECH, /* Hyperbolic secant */ OP_SIN, /* Sine (radians) */ OP_SINC, /* Sinc function [= sin(x)/x] */ OP_SIND, /* Sine (degrees) */ OP_SINH, /* Hyperbolic sine */ OP_SQR, /* Square */ OP_SQRT, /* Square root */ OP_TAN, /* Tangent (radians) */ OP_TAND, /* Tangent (degrees) */ OP_TANH, /* Hyperbolic tangent */ /* Functions with two arguments. */ OP_ATAN2, /* Inverse tangent (2 arguments, radians) */ OP_ATAN2D, /* Inverse tangent (2 arguments, degrees) */ OP_DIM, /* Fortran DIM (positive difference) fn. */ OP_GAUSS, /* Gaussian random number */ OP_MOD, /* Modulus function */ OP_POW, /* Raise to power */ OP_RAND, /* Uniformly distributed random number */ OP_SIGN, /* Transfer of sign function */ /* Functions with three arguments. */ OP_QIF, /* C "question mark" operator "a?b:c" */ /* Functions with variable numbers of arguments. */ OP_MAX, /* Maximum of 2 or more values */ OP_MIN, /* Minimum of 2 or more values */ /* Unary arithmetic operators. */ OP_NEG, /* Negate (change sign) */ /* Unary boolean operators. */ OP_NOT, /* Boolean NOT */ /* Binary arithmetic operators. */ OP_ADD, /* Add */ OP_DIV, /* Divide */ OP_MUL, /* Multiply */ OP_SUB, /* Subtract */ /* Bit-shift operators. */ OP_SHFTL, /* Shift bits left */ OP_SHFTR, /* Shift bits right */ /* Relational operators. */ OP_EQ, /* Relational equal */ OP_GE, /* Greater than or equal */ OP_GT, /* Greater than */ OP_LE, /* Less than or equal */ OP_LT, /* Less than */ OP_NE, /* Not equal */ /* Bit-wise operators. */ OP_BITAND, /* Bit-wise AND */ OP_BITOR, /* Bit-wise OR */ OP_BITXOR, /* Bit-wise exclusive OR */ /* Binary boolean operators. */ OP_AND, /* Boolean AND */ OP_EQV, /* Fortran logical .EQV. operation */ OP_OR, /* Boolean OR */ OP_XOR, /* Boolean exclusive OR */ /* Null operation. */ OP_NULL /* Null operation */ } Oper; /* This structure holds a description of each symbol which may appear in an expression. */ typedef struct { const char *text; /* Symbol text as it appears in expressions */ const int size; /* Size of symbol text */ const int operleft; /* An operator when seen from the left? */ const int operright; /* An operator when seen from the right? */ const int unarynext; /* May be followed by a unary +/- ? */ const int unaryoper; /* Is a unary +/- ? */ const int leftpriority; /* Priority when seen from the left */ const int rightpriority; /* Priority when seen from the right */ const int parincrement; /* Change in parenthesis level */ const int stackincrement; /* Change in evaluation stack size */ const int nargs; /* Number of function arguments */ const Oper opcode; /* Resulting operation code */ } Symbol; /* This initialises an array of Symbol structures to hold data on all the supported symbols. The order is not important, but symbols are arranged here in approximate order of descending evaluation priority. The end of the array is indicated by an element with a NULL "text" component. */ static const Symbol symbol[] = { /* User-supplied constants and variables. */ { "" , 0, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDCON }, { "" , 0, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDVAR }, /* System constants. */ { "" , 5, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDBAD }, { "" , 5, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDDIG }, { "" , 9, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDEPS }, { "" , 10, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMDIG }, { "" , 5, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMAX }, { "", 12, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMAX10E }, { "" , 9, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMAXE }, { "" , 5, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMIN }, { "", 12, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMIN10E }, { "" , 9, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDMINE }, { "" , 7, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDRAD }, { "" , 8, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDRND }, /* Mathematical constants. */ { "" , 3, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDE }, { "" , 4, 0, 0, 0, 0, 19, 19, 0, 1, 0, OP_LDPI }, /* Functions with one argument. */ { "abs(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ABS }, { "acos(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ACOS }, { "acosd(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ACOSD }, { "acosh(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ACOSH }, { "acoth(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ACOTH }, { "acsch(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ACSCH }, { "aint(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_INT }, { "asech(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ASECH }, { "asin(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ASIN }, { "asind(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ASIND }, { "asinh(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ASINH }, { "atan(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ATAN }, { "atand(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ATAND }, { "atanh(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ATANH }, { "ceil(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_CEIL }, { "cos(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_COS }, { "cosd(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_COSD }, { "cosh(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_COSH }, { "coth(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_COTH }, { "csch(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_CSCH }, { "exp(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_EXP }, { "fabs(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ABS }, { "floor(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_FLOOR }, { "int(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_INT }, { "isbad(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_ISBAD }, { "log(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_LOG }, { "log10(" , 6, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_LOG10 }, { "nint(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_NINT }, { "poisson(" , 8, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_POISS }, { "sech(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SECH }, { "sin(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SIN }, { "sinc(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SINC }, { "sind(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SIND }, { "sinh(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SINH }, { "sqr(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SQR }, { "sqrt(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_SQRT }, { "tan(" , 4, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_TAN }, { "tand(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_TAND }, { "tanh(" , 5, 0, 1, 1, 0, 19, 1, 1, 0, 1, OP_TANH }, /* Functions with two arguments. */ { "atan2(" , 6, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_ATAN2 }, { "atan2d(" , 7, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_ATAN2D }, { "dim(" , 4, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_DIM }, { "fmod(" , 5, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_MOD }, { "gauss(" , 6, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_GAUSS }, { "mod(" , 4, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_MOD }, { "pow(" , 4, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_POW }, { "rand(" , 5, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_RAND }, { "sign(" , 5, 0, 1, 1, 0, 19, 1, 1, -1, 2, OP_SIGN }, /* Functions with two arguments. */ { "qif(" , 4, 0, 1, 1, 0, 19, 1, 1, -2, 3, OP_QIF }, /* Functions with variable numbers of arguments. */ { "max(" , 4, 0, 1, 1, 0, 19, 1, 1, -1, -2, OP_MAX }, { "min(" , 4, 0, 1, 1, 0, 19, 1, 1, -1, -2, OP_MIN }, /* Parenthesised expressions. */ { ")" , 1, 1, 0, 0, 0, 2, 19, -1, 0, 0, OP_NULL }, { "(" , 1, 0, 1, 1, 0, 19, 1, 1, 0, 0, OP_NULL }, /* Unary arithmetic operators. */ { "+" , 1, 0, 1, 1, 1, 17, 16, 0, 0, 0, OP_NULL }, { "-" , 1, 0, 1, 1, 1, 17, 16, 0, 0, 0, OP_NEG }, /* Unary boolean operators. */ { "!" , 1, 0, 1, 1, 0, 17, 16, 0, 0, 0, OP_NOT }, { ".not." , 5, 0, 1, 1, 0, 17, 16, 0, 0, 0, OP_NOT }, /* Binary arithmetic operators. */ { "**" , 2, 1, 1, 1, 0, 18, 15, 0, -1, 0, OP_POW }, { "*" , 1, 1, 1, 1, 0, 14, 14, 0, -1, 0, OP_MUL }, { "/" , 1, 1, 1, 1, 0, 14, 14, 0, -1, 0, OP_DIV }, { "+" , 1, 1, 1, 1, 0, 13, 13, 0, -1, 0, OP_ADD }, { "-" , 1, 1, 1, 1, 0, 13, 13, 0, -1, 0, OP_SUB }, /* Bit-shift operators. */ { "<<" , 2, 1, 1, 1, 0, 12, 12, 0, -1, 0, OP_SHFTL }, { ">>" , 2, 1, 1, 1, 0, 12, 12, 0, -1, 0, OP_SHFTR }, /* Relational operators. */ { "<" , 1, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_LT }, { ".lt." , 4, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_LT }, { "<=" , 2, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_LE }, { ".le." , 4, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_LE }, { ">" , 1, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_GT }, { ".gt." , 4, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_GT }, { ">=" , 2, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_GE }, { ".ge." , 4, 1, 1, 1, 0, 11, 11, 0, -1, 0, OP_GE }, { "==" , 2, 1, 1, 1, 0, 10, 10, 0, -1, 0, OP_EQ }, { ".eq." , 4, 1, 1, 1, 0, 10, 10, 0, -1, 0, OP_EQ }, { "!=" , 2, 1, 1, 1, 0, 10, 10, 0, -1, 0, OP_NE }, { ".ne." , 4, 1, 1, 1, 0, 10, 10, 0, -1, 0, OP_NE }, /* Bit-wise operators. */ { "&" , 1, 1, 1, 1, 0, 9, 9, 0, -1, 0, OP_BITAND }, { "^" , 1, 1, 1, 1, 0, 8, 8, 0, -1, 0, OP_BITXOR }, { "|" , 1, 1, 1, 1, 0, 7, 7, 0, -1, 0, OP_BITOR }, /* Binary boolean operators. */ { "&&" , 2, 1, 1, 1, 0, 6, 6, 0, -1, 0, OP_AND }, { ".and." , 5, 1, 1, 1, 0, 6, 6, 0, -1, 0, OP_AND }, { "^^" , 2, 1, 1, 1, 0, 5, 5, 0, -1, 0, OP_XOR }, { "||" , 2, 1, 1, 1, 0, 4, 4, 0, -1, 0, OP_OR }, { ".or." , 4, 1, 1, 1, 0, 4, 4, 0, -1, 0, OP_OR }, { ".eqv." , 5, 1, 1, 1, 0, 3, 3, 0, -1, 0, OP_EQV }, { ".neqv." , 6, 1, 1, 1, 0, 3, 3, 0, -1, 0, OP_XOR }, { ".xor." , 5, 1, 1, 1, 0, 3, 3, 0, -1, 0, OP_XOR }, /* Separators. */ { "," , 1, 1, 1, 1, 0, 2, 2, 0, 0, 0, OP_NULL }, /* End of symbol data. */ { NULL , 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, OP_NULL } }; /* These variables identify indices in the above array which hold special symbols used explicitly in the code. */ static const int symbol_ldcon = 0; /* Load a constant */ static const int symbol_ldvar = 1; /* Load a variable */ /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(MathMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(MathMap,Class_Init) #define class_vtab astGLOBAL(MathMap,Class_Vtab) #define getattrib_buff astGLOBAL(MathMap,GetAttrib_Buff) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); static pthread_mutex_t mutex3 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX3 pthread_mutex_lock( &mutex3 ); #define UNLOCK_MUTEX3 pthread_mutex_unlock( &mutex3 ); static pthread_mutex_t mutex4 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX4 pthread_mutex_lock( &mutex4 ); #define UNLOCK_MUTEX4 pthread_mutex_unlock( &mutex4 ); static pthread_mutex_t mutex5 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX5 pthread_mutex_lock( &mutex5 ); #define UNLOCK_MUTEX5 pthread_mutex_unlock( &mutex5 ); static pthread_mutex_t mutex6 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX6 pthread_mutex_lock( &mutex6 ); #define UNLOCK_MUTEX6 pthread_mutex_unlock( &mutex6 ); static pthread_mutex_t mutex7 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX7 pthread_mutex_lock( &mutex7 ); #define UNLOCK_MUTEX7 pthread_mutex_unlock( &mutex7 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char getattrib_buff[ 51 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstMathMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #define LOCK_MUTEX3 #define UNLOCK_MUTEX3 #define LOCK_MUTEX4 #define UNLOCK_MUTEX4 #define LOCK_MUTEX5 #define UNLOCK_MUTEX5 #define LOCK_MUTEX6 #define UNLOCK_MUTEX6 #define LOCK_MUTEX7 #define UNLOCK_MUTEX7 #endif /* External 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. */ AstMathMap *astMathMapId_( int, int, int, const char *[], int, const char *[], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int GetObjSize( AstObject *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static double Gauss( Rcontext *, int * ); static double LogGamma( double, int * ); static double Poisson( Rcontext *, double, int * ); static double Rand( Rcontext *, int * ); static int DefaultSeed( const Rcontext *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetSeed( AstMathMap *, int * ); static int GetSimpFI( AstMathMap *, int * ); static int GetSimpIF( AstMathMap *, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestSeed( AstMathMap *, int * ); static int TestSimpFI( AstMathMap *, int * ); static int TestSimpIF( AstMathMap *, int * ); static void CleanFunctions( int, const char *[], char ***, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearSeed( AstMathMap *, int * ); static void ClearSimpFI( AstMathMap *, int * ); static void ClearSimpIF( AstMathMap *, int * ); static void CompileExpression( const char *, const char *, const char *, int, const char *[], int **, double **, int *, int * ); static void CompileMapping( const char *, const char *, int, int, int, const char *[], int, const char *[], int ***, int ***, double ***, double ***, int *, int *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void EvaluateFunction( Rcontext *, int, const double **, const int *, const double *, int, double *, int * ); static void EvaluationSort( const double [], int, int [], int **, int *, int * ); static void ExtractExpressions( const char *, const char *, int, const char *[], int, char ***, int * ); static void ExtractVariables( const char *, const char *, int, const char *[], int, int, int, int, int, char ***, int * ); static void ParseConstant( const char *, const char *, const char *, int, int *, double *, int * ); static void ParseName( const char *, int, int *, int * ); static void ParseVariable( const char *, const char *, const char *, int, int, const char *[], int *, int *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetSeed( AstMathMap *, int, int * ); static void SetSimpFI( AstMathMap *, int, int * ); static void SetSimpIF( AstMathMap *, int, int * ); static void ValidateSymbol( const char *, const char *, const char *, int, int, int *, int **, int **, int *, double **, int * ); /* Member functions. */ /* ================= */ static void CleanFunctions( int nfun, const char *fun[], char ***clean, int *status ) { /* * Name: * CleanFunctions * Purpose: * Make a clean copy of a set of functions. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void CleanFunctions( int nfun, const char *fun[], char ***clean, int *status ) * Class Membership: * MathMap member function. * Description: * This function copies an array of strings, eliminating any white space * characters and converting to lower case. It is intended for cleaning * up arrays of function definitions prior to compilation. The returned * copy is stored in dynamically allocated memory. * Parameters: * nfun * The number of functions to be cleaned. * fun * Pointer to an array, with "nfun" elements, of pointers to null * terminated strings which contain each of the functions. * clean * Address in which to return a pointer to an array (with "nfun" * elements) of pointers to null terminated strings containing the * cleaned functions (i.e. this returns an array of strings). * * Both the returned array of pointers, and the strings to which they * point, will be dynamically allocated and should be freed by the * caller (using astFree) when no longer required. * status * Pointer to the inherited status variable. * Notes: * - A NULL value will be returned for "*clean" if this function is * invoked with the global error status set, or if it should fail for * any reason. */ /* Local Variables: */ char c; /* Character from function string */ int i; /* Loop counter for characters */ int ifun; /* Loop counter for functions */ int nc; /* Count of non-blank characters */ /* Initialise. */ *clean = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Allocate and initialise an array to hold the returned pointers. */ MALLOC_POINTER_ARRAY( *clean, char *, nfun ) /* Loop through all the input functions. */ if ( astOK ) { for ( ifun = 0; ifun < nfun; ifun++ ) { /* Count the number of non-blank characters in each function string. */ nc = 0; for ( i = 0; ( c = fun[ ifun ][ i ] ); i++ ) nc += !isspace( c ); /* Allocate a string long enough to hold the function with all the white space removed, storing its pointer in the array allocated earlier. Check for errors. */ ( *clean )[ ifun ] = astMalloc( sizeof( char ) * (size_t) ( nc + 1 ) ); if ( !astOK ) break; /* Loop to copy the non-blank function characters into the new string. */ nc = 0; for ( i = 0; ( c = fun[ ifun ][ i ] ); i++ ) { if ( !isspace( c ) ) ( *clean )[ ifun ][ nc++ ] = tolower( c ); } /* Null-terminate the result. */ ( *clean )[ ifun ][ nc ] = '\0'; } /* If an error occurred, then free the main pointer array together with any strings that have been allocated, resetting the output value. */ if ( !astOK ) { FREE_POINTER_ARRAY( *clean, nfun ) } } } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a MathMap. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * MathMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * MathMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the MathMap. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstMathMap *this; /* Pointer to the MathMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* Seed. */ /* ----- */ if ( !strcmp( attrib, "seed" ) ) { astClearSeed( this ); /* SimpFI. */ /* ------- */ } else if ( !strcmp( attrib, "simpfi" ) ) { astClearSimpFI( this ); /* SimpIF. */ /* ------- */ } else if ( !strcmp( attrib, "simpif" ) ) { astClearSimpIF( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void CompileExpression( const char *method, const char *class, const char *exprs, int nvar, const char *var[], int **code, double **con, int *stacksize, int *status ) { /* * Name: * CompileExpression * Purpose: * Compile a mathematical expression. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void CompileExpression( const char *method, const char *class, * const char *exprs, int nvar, const char *var[], * int **code, double **con, int *stacksize ) * Class Membership: * MathMap member function. * Description: * This function checks and compiles a mathematical expression. It * produces a sequence of operation codes (opcodes) and a set of * numerical constants which may subsequently be used to evaluate the * expression on a push-down stack. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * exprs * Pointer to a null-terminated string containing the expression * to be compiled. This is case sensitive and should contain no white * space. * nvar * The number of variable names defined for use in the expression. * var * An array of pointers (with "nvar" elements) to null-terminated * strings. Each of these should contain a variable name which may * appear in the expression. These strings are case sensitive and * should contain no white space. * code * Address of a pointer which will be set to point at a dynamically * allocated array of int containing the set of opcodes (cast to int) * produced by this function. The first element of this array will * contain a count of the number of opcodes which follow. * * The allocated space must be freed by the caller (using astFree) when * no longer required. * con * Address of a pointer which will be set to point at a dynamically * allocated array of double containing the set of constants * produced by this function (this may be NULL if no constants are * produced). * * The allocated space must be freed by the caller (using astFree) when * no longer required. * stacksize * Pointer to an int in which to return the size of the push-down stack * required to evaluate the expression using the returned opcodes and * constants. * Algorithm: * The function passes through the input expression searching for * symbols. It looks for standard symbols (arithmetic operators, * parentheses, function calls and delimiters) in the next part of the * expression to be parsed, using identification information stored in * the static "symbol" array. It ignores certain symbols, according to * whether they appear to be operators or operands. The choice depends on * what the previous symbol was; for instance, two operators may not * occur in succession. Unary +/- operators are also ignored in * situations where they are not permitted. * * If a standard symbol is found, it is passed to the ValidateSymbol * function, which keeps track of the current level of parenthesis in the * expression and of the number of arguments supplied to any (possibly * nested) function calls. This function then accepts or rejects the * symbol according to whether it is valid within the current context. An * error is reported if it is rejected. * * If the part of the expression currently being parsed did not contain a * standard symbol, an attempt is made to parse it first as a constant, * then as a variable name. If either of these succeeds, an appropriate * symbol number is added to the list of symbols identified so far, and a * value is added to the list of constants - this is either the value of * the constant itself, or the identification number of the variable. If * the expression cannot be parsed, an error is reported. * * When the entire expression has been analysed as a sequence of symbols * (and associated constants), the EvaluationSort function is * invoked. This sorts the symbols into evaluation order, which is the * order in which the associated operations must be performed on a * push-down arithmetic stack to evaluate the expression. This routine * also substitutes operation codes (defined in the "Oper" enum) for the * symbol numbers and calculates the size of evaluation stack which will * be required. * Notes: * - A value of NULL will be returned for the "*code" and "*con" pointers * and a value of zero will be returned for the "*stacksize" value if this * function is invoked with the global error status set, or if it should * fail for any reason. */ /* Local Variables: */ double c; /* Value of parsed constant */ int *argcount; /* Array of argument count information */ int *opensym; /* Array of opening parenthesis information */ int *symlist; /* Array of symbol indices */ int found; /* Standard symbol identified? */ int iend; /* Ending index in the expression string */ int istart; /* Staring index in the expression string */ int isym; /* Loop counter for symbols */ int ivar; /* Index of variable name */ int lpar; /* Parenthesis level */ int ncon; /* Number of constants generated */ int nsym; /* Number of symbols identified */ int opernext; /* Next symbol an operator (from left)? */ int size; /* Size of symbol matched */ int sym; /* Index of symbol in static "symbol" array */ int unarynext; /* Next symbol may be unary +/- ? */ /* Initialise. */ *code = NULL; *con = NULL; *stacksize = 0; /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ argcount = NULL; lpar = 0; ncon = 0; nsym = 0; opensym = NULL; symlist = NULL; sym = 0; ivar = 0; /* The first symbol to be encountered must not look like an operator from the left. It may be a unary + or - operator. */ opernext = 0; unarynext = 1; /* Search through the expression to classify each symbol which appears in it. Stop when there are no more input characters or an error is detected. */ istart = 0; for ( istart = 0; astOK && exprs[ istart ]; istart = iend + 1 ) { /* Compare each of the symbols in the symbol data with the next section of the expression, looking for the longest symbol text which will match. Stop if a NULL "text" value is found, which acts as the end flag. */ found = 0; size = 0; for ( isym = 0; symbol[ isym ].text; isym++ ) { /* Only consider symbols which have text associated with them and which look like operators or operands from the left, according to the setting of the "opernext" flag. Thus, if an operator or operand is missing from the input expression, the next symbol will not be identified, because it will be of the wrong type. Also exclude unary +/- operators if they are out of context. */ if ( symbol[ isym ].size && ( symbol[ isym ].operleft == opernext ) && ( !symbol[ isym ].unaryoper || unarynext ) ) { /* Test if the text of the symbol matches the expression at the current position. If so, note that a match has been found. */ if ( !strncmp( exprs + istart, symbol[ isym ].text, (size_t) symbol[ isym ].size ) ) { found = 1; /* If this symbol matches more characters than any previous symbol, then store the symbol's index and note its size. */ if ( symbol[ isym ].size > size ) { sym = isym; size = symbol[ isym ].size; /* Calculate the index of the last symbol character in the expression string. */ iend = istart + size - 1; } } } } /* If the symbol was identified as one of the standard symbols, then validate it, updating the parenthesis level and argument count information at the same time. */ if ( found ) { ValidateSymbol( method, class, exprs, iend, sym, &lpar, &argcount, &opensym, &ncon, con, status ); /* If it was not one of the standard symbols, then check if the next symbol was expected to be an operator. If so, then there is a missing operator, so report an error. */ } else { if ( opernext ) { astError( AST__MIOPR, "%s(%s): Missing or invalid operator in the expression " "\"%.*s\".", status, method, class, istart + 1, exprs ); /* If the next symbol was expected to be an operand, then it may be a constant, so try to parse it as one. */ } else { ParseConstant( method, class, exprs, istart, &iend, &c, status ); if ( astOK ) { /* If successful, set the symbol number to "symbol_ldcon" (load constant) and extend the "*con" array to accommodate a new constant. Check for errors. */ if ( iend >= istart ) { sym = symbol_ldcon; *con = astGrow( *con, ncon + 1, sizeof( double ) ); if ( astOK ) { /* Append the constant to the "*con" array. */ ( *con )[ ncon++ ] = c; } /* If the symbol did not parse as a constant, then it may be a variable name, so try to parse it as one. */ } else { ParseVariable( method, class, exprs, istart, nvar, var, &ivar, &iend, status ); if ( astOK ) { /* If successful, set the symbol to "symbol_ldvar" (load variable) and extend the "*con" array to accommodate a new constant. Check for errors. */ if ( ivar != -1 ) { sym = symbol_ldvar; *con = astGrow( *con, ncon + 1, sizeof( double ) ); if ( astOK ) { /* Append the variable identification number as a constant to the "*con" array. */ ( *con )[ ncon++ ] = (double) ivar; } /* If the expression did not parse as a variable name, then there is a missing operand in the expression, so report an error. */ } else { astError( AST__MIOPA, "%s(%s): Missing or invalid operand in the " "expression \"%.*s\".", status, method, class, istart + 1, exprs ); } } } } } } /* If there has been no error, then the next symbol in the input expression has been identified and is valid. */ if ( astOK ) { /* Decide whether the next symbol should look like an operator or an operand from the left. This is determined by the nature of the symbol just identified (seen from the right) - two operands or two operators cannot be adjacent. */ opernext = !symbol[ sym ].operright; /* Also decide whether the next symbol may be a unary +/- operator, according to the "unarynext" symbol data entry for the symbol just identified. */ unarynext = symbol[ sym ].unarynext; /* Extend the "symlist" array to accommodate the symbol just identified. Check for errors. */ symlist = astGrow( symlist, nsym + 1, sizeof( int ) ); if ( astOK ) { /* Append the symbol's index to the end of this list. */ symlist[ nsym++ ] = sym; } } } /* If there has been no error, check the final context after identifying all the symbols... */ if ( astOK ) { /* If an operand is still expected, then there is an unsatisfied operator on the end of the expression, so report an error. */ if ( !opernext ) { astError( AST__MIOPA, "%s(%s): Missing or invalid operand in the expression " "\"%s\".", status, method, class, exprs ); /* If the final parenthesis level is positive, then there is a missing right parenthesis, so report an error. */ } else if ( lpar > 0 ) { astError( AST__MRPAR, "%s(%s): Missing right parenthesis in the expression " "\"%s\".", status, method, class, exprs ); } } /* Sort the symbols into evaluation order to produce output opcodes. */ EvaluationSort( *con, nsym, symlist, code, stacksize, status ); /* Free any memory used as workspace. */ if ( argcount ) argcount = astFree( argcount ); if ( opensym ) opensym = astFree( opensym ); if ( symlist ) symlist = astFree( symlist ); /* If OK, re-allocate the "*con" array to have the correct size (since astGrow may have over-allocated space). */ if ( astOK && *con ) { *con = astRealloc( *con, sizeof( double ) * (size_t) ncon ); } /* If an error occurred, free any allocated memory and reset the output values. */ if ( !astOK ) { *code = astFree( *code ); *con = astFree( *con ); *stacksize = 0; } } static void CompileMapping( const char *method, const char *class, int nin, int nout, int nfwd, const char *fwdfun[], int ninv, const char *invfun[], int ***fwdcode, int ***invcode, double ***fwdcon, double ***invcon, int *fwdstack, int *invstack, int *status ) { /* * Name: * CompileMapping * Purpose: * Compile the transformation functions for a MathMap. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void CompileMapping( const char *method, const char *class, * int nin, int nout, * int nfwd, const char *fwdfun[], * int ninv, const char *invfun[], * int ***fwdcode, int ***invcode, * double ***fwdcon, double ***invcon, * int *fwdstack, int *invstack, int *status ) * Class Membership: * MathMap member function. * Description: * This function checks and compiles the transformation functions required * to create a MathMap. It produces sequences of operation codes (opcodes) * and numerical constants which may subsequently be used to evaluate the * functions on a push-down stack. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * nin * Number of input variables for the MathMap. * nout * Number of output variables for the MathMap. * nfwd * The number of forward transformation functions being supplied. * This must be at least equal to "nout". * fwdfun * Pointer to an array, with "nfwd" elements, of pointers to null * terminated strings which contain each of the forward transformation * functions. These must be in lower case and should contain no white * space. * ninv * The number of inverse transformation functions being supplied. * This must be at least equal to "nin". * invfun * Pointer to an array, with "ninv" elements, of pointers to null * terminated strings which contain each of the inverse transformation * functions. These must be in lower case and should contain no white * space. * fwdcode * Address in which to return a pointer to an array (with "nfwd" * elements) of pointers to arrays of int containing the set of opcodes * (cast to int) for each forward transformation function. The number * of opcodes produced for each function is given by the first element * of the opcode array. * * Both the returned array of pointers, and the arrays of int to which * they point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. * * If the right hand sides (including the "=" sign) of all the supplied * functions are absent, then this indicates an undefined transformation * and the returned pointer value will be NULL. An error results if * an "=" sign is present but no expression follows it. * invcode * Address in which to return a pointer to an array (with "ninv" * elements) of pointers to arrays of int containing the set of opcodes * (cast to int) for each inverse transformation function. The number * of opcodes produced for each function is given by the first element * of the opcode array. * * Both the returned array of pointers, and the arrays of int to which * they point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. * * If the right hand sides (including the "=" sign) of all the supplied * functions are absent, then this indicates an undefined transformation * and the returned pointer value will be NULL. An error results if * an "=" sign is present but no expression follows it. * fwdcon * Address in which to return a pointer to an array (with "nfwd" * elements) of pointers to arrays of double containing the set of * constants for each forward transformation function. * * Both the returned array of pointers, and the arrays of double to which * they point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. Note * that any of the pointers to the arrays of double may be NULL if no * constants are associated with a particular function. * * If the forward transformation is undefined, then the returned pointer * value will be NULL. * invcon * Address in which to return a pointer to an array (with "ninv" * elements) of pointers to arrays of double containing the set of * constants for each inverse transformation function. * * Both the returned array of pointers, and the arrays of double to which * they point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. Note * that any of the pointers to the arrays of double may be NULL if no * constants are associated with a particular function. * * If the inverse transformation is undefined, then the returned pointer * value will be NULL. * fwdstack * Pointer to an int in which to return the size of the push-down stack * required to evaluate the forward transformation functions. * invstack * Pointer to an int in which to return the size of the push-down stack * required to evaluate the inverse transformation functions. * status * Pointer to the inherited status variable. * Notes: * - A value of NULL will be returned for the "*fwdcode", "*invcode", * "*fwdcon" and "*invcon" pointers and a value of zero will be returned * for the "*fwdstack" and "*invstack" values if this function is invoked * with the global error status set, or if it should fail for any reason. */ /* Local Variables: */ char **exprs; /* Pointer to array of expressions */ char **var; /* Pointer to array of variable names */ const char **strings; /* Pointer to temporary array of strings */ int ifun; /* Loop counter for functions */ int nvar; /* Number of variables to extract */ int stacksize; /* Required stack size */ /* Initialise. */ *fwdcode = NULL; *invcode = NULL; *fwdcon = NULL; *invcon = NULL; *fwdstack = 0; *invstack = 0; nvar = 0; /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ exprs = NULL; var = NULL; /* Compile the forward transformation. */ /* ----------------------------------- */ /* Allocate space for an array of pointers to the functions from which we will extract variable names. */ strings = astMalloc( sizeof( char * ) * (size_t) ( nin + nfwd ) ); /* Fill the first elements of this array with pointers to the inverse transformation functions ("nin" in number) which yield the final input values. These will have the names of the input variables on their left hand sides. */ if ( astOK ) { nvar = 0; for ( ifun = ninv - nin; ifun < ninv; ifun++ ) { strings[ nvar++ ] = invfun[ ifun ]; } /* Fill the remaining elements of the array with pointers to the forward transformation functions. These will have the names of any intermediate variables plus the final output variables on their left hand sides. */ for ( ifun = 0; ifun < nfwd; ifun++ ) strings[ nvar++ ] = fwdfun[ ifun ]; /* Extract the variable names from the left hand sides of these functions and check them for validity and absence of duplication. */ ExtractVariables( method, class, nvar, strings, nin, nout, nfwd, ninv, 1, &var, status ); } /* Free the temporary array of string pointers. */ strings = astFree( strings ); /* Extract the expressions from the right hand sides of the forward transformation functions. */ ExtractExpressions( method, class, nfwd, fwdfun, 1, &exprs, status ); /* If OK, and the forward transformation is defined, then allocate and initialise space for an array of pointers to the opcodes for each expression and, similarly, for the constants for each expression. */ if ( astOK && exprs ) { MALLOC_POINTER_ARRAY( *fwdcode, int *, nfwd ) MALLOC_POINTER_ARRAY( *fwdcon, double *, nfwd ) /* If OK, loop to compile each of the expressions, storing pointers to the resulting opcodes and constants in the arrays allocated above. On each loop, we make progressively more of the variable names in "var" visible to the compilation function. This ensures that each expression can only use variables which have been defined earlier. */ if ( astOK ) { for ( ifun = 0; ifun < nfwd; ifun++ ) { CompileExpression( method, class, exprs[ ifun ], nin + ifun, (const char **) var, &( *fwdcode )[ ifun ], &( *fwdcon )[ ifun ], &stacksize, status ); /* If an error occurs, then report contextual information and quit. */ if ( !astOK ) { astError( astStatus, "Error in forward transformation function %d.", status, ifun + 1 ); break; } /* If OK, calculate the maximum evaluation stack size required by any of the expressions. */ *fwdstack = ( *fwdstack > stacksize ) ? *fwdstack : stacksize; } } } /* Free the memory containing the extracted expressions and variables. */ FREE_POINTER_ARRAY( exprs, nfwd ) FREE_POINTER_ARRAY( var, nvar ) /* Compile the inverse transformation. */ /* ----------------------------------- */ /* Allocate space for an array of pointers to the functions from which we will extract variable names. */ strings = astMalloc( sizeof( char * ) * (size_t) ( nout + ninv ) ); /* Fill the first elements of this array with pointers to the forward transformation functions ("nout" in number) which yield the final output values. These will have the names of the output variables on their left hand sides. */ if ( astOK ) { nvar = 0; for ( ifun = nfwd - nout; ifun < nfwd; ifun++ ) { strings[ nvar++ ] = fwdfun[ ifun ]; } /* Fill the remaining elements of the array with pointers to the inverse transformation functions. These will have the names of any intermediate variables plus the final input variables on their left hand sides. */ for ( ifun = 0; ifun < ninv; ifun++ ) strings[ nvar++ ] = invfun[ ifun ]; /* Extract the variable names from the left hand sides of these functions and check them for validity and absence of duplication. */ ExtractVariables( method, class, nvar, strings, nin, nout, nfwd, ninv, 0, &var, status ); } /* Free the temporary array of string pointers. */ strings = astFree( strings ); /* Extract the expressions from the right hand sides of the inverse transformation functions. */ ExtractExpressions( method, class, ninv, invfun, 0, &exprs, status ); /* If OK, and the forward transformation is defined, then allocate and initialise space for an array of pointers to the opcodes for each expression and, similarly, for the constants for each expression. */ if ( astOK && exprs ) { MALLOC_POINTER_ARRAY( *invcode, int *, ninv ) MALLOC_POINTER_ARRAY( *invcon, double *, ninv ) /* If OK, loop to compile each of the expressions, storing pointers to the resulting opcodes and constants in the arrays allocated above. On each loop, we make progressively more of the variable names in "var" visible to the compilation function. This ensures that each expression can only use variables which have been defined earlier. */ if ( astOK ) { for ( ifun = 0; ifun < ninv; ifun++ ) { CompileExpression( method, class, exprs[ ifun ], nout + ifun, (const char **) var, &( *invcode )[ ifun ], &( *invcon )[ ifun ], &stacksize, status ); /* If an error occurs, then report contextual information and quit. */ if ( !astOK ) { astError( astStatus, "Error in inverse transformation function %d.", status, ifun + 1 ); break; } /* If OK, calculate the maximum evaluation stack size required by any of the expressions. */ *invstack = ( *invstack > stacksize ) ? *invstack : stacksize; } } } /* Free the memory containing the extracted expressions and variables. */ FREE_POINTER_ARRAY( exprs, ninv ) FREE_POINTER_ARRAY( var, nvar ) /* If an error occurred, then free all remaining allocated memory and reset the output values. */ if ( !astOK ) { FREE_POINTER_ARRAY( *fwdcode, nfwd ) FREE_POINTER_ARRAY( *invcode, ninv ) FREE_POINTER_ARRAY( *fwdcon, nfwd ) FREE_POINTER_ARRAY( *invcon, ninv ) *fwdstack = 0; *invstack = 0; } } static int DefaultSeed( const Rcontext *context, int *status ) { /* * Name: * DefaultSeed * Purpose: * Generate an unpredictable seed for a random number generator. * Type: * Private function. * Synopsis: * #include "mathmap.h" * int DefaultSeed( Rcontext *context, int *status ) * Class Membership: * MathMap member function. * Description: * On each invocation this function returns an integer value which is * highly unpredictable. This value may be used as a default seed for the * random number generator associated with a MathMap, so that it * generates a different sequence on each occasion. * Parameters: * context * Pointer to the random number generator context associated with * the MathMap. * status * Pointer to the inherited status variable. * Returned Value: * The unpredictable integer. * Notes: * - This function does not perform error checking and will execute even * if the global error status is set. */ /* Local Constants: */ const int nwarm = 5; /* Number of warm-up iterations */ const long int a = 8121L; /* Constants for random number generator... */ const long int c = 28411L; const long int m = 134456L; /* Local Variables; */ int iwarm; /* Loop counter for warm-up iterations */ static long init = 0; /* Local initialisation performed? */ static long int rand; /* Local random integer */ unsigned long int bits; /* Bit pattern for producing result */ /* On the first invocation, initialise a local random number generator to a value derived by combining bit patterns obtained from the system clock and the processor time used. The result needs to be positive and lie in the range 0 to "m-1". */ LOCK_MUTEX5 if ( !init ) { rand = (long int) ( ( (unsigned long int) time( NULL ) ^ (unsigned long int) clock() ) % (unsigned long int) m ); /* These values will typically only change in their least significant bits between programs run successively, but by using the bit pattern as a seed, we ensure that these differences are rapidly propagated to other bits. To hasten this process, we "warm up" the local generator with a few iterations. This is a quick and dirty generator using constants from Press et al. (Numerical recipes). */ for ( iwarm = 0; iwarm < nwarm; iwarm++ ) { rand = ( rand * a + c ) % m; } /* Note that this initialisation has been performed. */ init = 1; } UNLOCK_MUTEX5 /* Generate a new bit pattern from the system time. Apart from the first invocation, this will be a different time to that used above. */ bits = (unsigned long int) time( NULL ); /* Mask in a pattern derived from the CPU time used. */ bits ^= (unsigned long int) clock(); /* The system time may change quite slowly (e.g. every second), so also mask in the address of the random number generator context supplied. This makes the seed depend on which MathMap is in use. */ bits ^= (unsigned long int) context; /* Now mask in the last random integer produced by the random number generator whose context has been supplied. This makes the seed depend on the MathMap's past use of random numbers. */ bits ^= (unsigned long int) context->random_int; /* Finally, in order to produce different seeds when this function is invoked twice in rapid succession on the same object (with no intermediate processing), we also mask in a pseudo-random value generated here. Generate the next local random integer. */ rand = ( rand * a + c ) % m; /* We then scale this value to give an integer in the range 0 to ULONG_MAX and mask the corresponding bit pattern into our seed. */ bits ^= (unsigned long int) ( ( (double) rand / (double) ( m - 1UL ) ) * ( ( (double) ULONG_MAX + 1.0 ) * ( 1.0 - DBL_EPSILON ) ) ); /* Return the integer value of the seed (which may involve discarding some unwanted bits). */ return (int) bits; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two MathMaps are equivalent. * Type: * Private function. * Synopsis: * #include "mapping.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * MathMap member function (over-rides the astEqual protected * method inherited from the Object class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two MathMaps are equivalent. * Parameters: * this * Pointer to the first Object (a MathMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the MathMaps are equivalent, zero otherwise. * Notes: * - The two MathMaps are considered equivalent if the combination of * the first in series with the inverse of the second simplifies to a * UnitMap. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstMathMap *that; /* Pointer to the second MathMap structure */ AstMathMap *this; /* Pointer to the first MathMap structure */ double **that_con; /* Lists of constants from "that" */ double **this_con; /* Lists of constants from "this" */ int **that_code; /* Lists of opcodes from "that" */ int **this_code; /* Lists of opcodes from "this" */ int code; /* Opcode value */ int icode; /* Opcode index */ int icon; /* Constant index */ int ifun; /* Function index */ int ncode; /* No. of opcodes for current "this" function */ int ncode_that; /* No. of opcodes for current "that" function */ int nin; /* Number of inputs */ int nout; /* Number of outputs */ int pass; /* Check fwd or inv */ int result; /* Result value to return */ int that_nfun; /* Number of functions from "that" */ int this_nfun; /* Number of functions from "this" */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two MathMap structures. */ this = (AstMathMap *) this_object; that = (AstMathMap *) that_object; /* Check the second object is a MathMap. We know the first is a MathMap since we have arrived at this implementation of the virtual function. */ if( astIsAMathMap( that ) ) { /* Check they have the same number of inputs and outputs */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNout( that ) == nout && astGetNin( that ) == nin ) { /* Assume equality. */ result = 1; /* The first pass through this next loop compares forward functions, and the second pass compares inverse functions. */ for( pass = 0; pass < 2 && result; pass++ ) { /* On the first pass, get pointers to the lists of opcodes and constants for the effective forward transformations (taking into account the value of the Invert attribute), together with the number of such functions. */ if( pass == 0 ) { if( !astGetInvert( this ) ) { this_code = this->fwdcode; this_con = this->fwdcon; this_nfun = this->nfwd; } else { this_code = this->invcode; this_con = this->invcon; this_nfun = this->ninv; } if( !astGetInvert( that ) ) { that_code = that->fwdcode; that_con = that->fwdcon; that_nfun = that->nfwd; } else { that_code = that->invcode; that_con = that->invcon; that_nfun = that->ninv; } /* On the second pass, get pointers to the lists of opcodes and constants for the effective inverse transformations, together with the number of such functions. */ } else { if( astGetInvert( this ) ) { this_code = this->fwdcode; this_con = this->fwdcon; this_nfun = this->nfwd; } else { this_code = this->invcode; this_con = this->invcon; this_nfun = this->ninv; } if( astGetInvert( that ) ) { that_code = that->fwdcode; that_con = that->fwdcon; that_nfun = that->nfwd; } else { that_code = that->invcode; that_con = that->invcon; that_nfun = that->ninv; } } /* Check that "this" and "that" have the same number of functions */ if( that_nfun != this_nfun ) result = 0; /* Loop round each function. */ for( ifun = 0; ifun < this_nfun && result; ifun++ ) { /* The first element in the opcode array is the number of subsequent opcodes. Obtain and compare these counts. */ ncode = this_code ? this_code[ ifun ][ 0 ] : 0; ncode_that = that_code ? that_code[ ifun ][ 0 ] : 0; if( ncode != ncode_that ) result = 0; /* Compare the following opcodes. Some opcodes consume constants from the list of constants associated with the MathMap. Compare the constants for such opcodes. */ icon = 0; for( icode = 0; icode < ncode && result; icode++ ){ code = this_code[ ifun ][ icode ]; if( that_code[ ifun ][ icode ] != code ) { result = 0; } else if( code == OP_LDCON || code == OP_LDVAR || code == OP_MAX || code == OP_MIN ) { if( this_con[ ifun ][ icon ] != that_con[ ifun ][ icon ] ) { result = 0; } else { icon++; } } } } } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static void EvaluateFunction( Rcontext *rcontext, int npoint, const double **ptr_in, const int *code, const double *con, int stacksize, double *out, int *status ) { /* * Name: * EvaluateFunction * Purpose: * Evaluate a compiled function. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void EvaluateFunction( Rcontext *rcontext, int npoint, * const double **ptr_in, const int *code, * const double *con, int stacksize, double *out, int *status ) * Class Membership: * MathMap member function. * Description: * This function implements a "virtual machine" which executes operations * on an arithmetic stack in order to evaluate transformation functions. * Each operation is specified by an input operation code (opcode) and * results in the execution of a vector operation on a stack. The final * result, after executing all the supplied opcodes, is returned as a * vector. * * This function detects arithmetic errors (such as overflow and division * by zero) and propagates any "bad" coordinate values, including those * present in the input, to the output. * Parameters: * npoint * The number of points to be transformd (i.e. the size of the vector * of values on which operations are to be performed). * ptr_in * Pointer to an array of pointers to arrays of double (with "npoint" * elements). These arrays should contain the input coordinate values, * such that coordinate number "coord" for point number "point" can be * found in "ptr_in[coord][point]". * code * Pointer to an array of int containing the set of opcodes (cast to int) * for the operations to be performed. The first element of this array * should contain a count of the number of opcodes which follow. * con * Pointer to an array of double containing the set of constants required * to evaluate the function (this may be NULL if no constants are * required). * stacksize * The size of the stack required to evaluate the expression using the * opcodes and constants supplied. This value should be calculated during * expression compilation. * out * Pointer to an array of double (with "npoint" elements) in which to * return the vector of result values. * status * Pointer to the inherited status variable. */ /* Local Constants: */ const int bits = /* Number of bits in an unsigned long */ sizeof( unsigned long ) * CHAR_BIT; const double eps = /* Smallest number subtractable from 2.0 */ 2.0 * DBL_EPSILON; const double scale = /* 2.0 raised to the power "bits" */ ldexp( 1.0, bits ); const double scale1 = /* 2.0 raised to the power "bits-1" */ scale * 0.5; const double rscale = /* Reciprocal scale factor */ 1.0 / scale; const double rscale1 = /* Reciprocal initial scale factor */ 1.0 / scale1; const int nblock = /* Number of blocks of bits to process */ ( sizeof( double ) + sizeof( unsigned long ) - 1 ) / sizeof( unsigned long ); const unsigned long signbit = /* Mask for extracting sign bit */ 1UL << ( bits - 1 ); /* Local Variables: */ double **stack; /* Array of pointers to stack elements */ double *work; /* Pointer to stack workspace */ double *xv1; /* Pointer to first argument vector */ double *xv2; /* Pointer to second argument vector */ double *xv3; /* Pointer to third argument vector */ double *xv; /* Pointer to sole argument vector */ double *y; /* Pointer to result */ double *yv; /* Pointer to result vector */ double abs1; /* Absolute value (temporary variable) */ double abs2; /* Absolute value (temporary variable) */ double frac1; /* First (maybe normalised) fraction */ double frac2; /* Second (maybe normalised) fraction */ double frac; /* Sole normalised fraction */ double newexp; /* New power of 2 exponent value */ double ran; /* Random number */ double result; /* Function result value */ double unscale; /* Factor for removing scaling */ double value; /* Value to be assigned to stack vector */ double x1; /* First argument value */ double x2; /* Second argument value */ double x3; /* Third argument value */ double x; /* Sole argument value */ int expon1; /* First power of 2 exponent */ int expon2; /* Second power of 2 exponent */ int expon; /* Sole power of 2 exponent */ int iarg; /* Loop counter for arguments */ int iblock; /* Loop counter for blocks of bits */ int icode; /* Opcode value */ int icon; /* Counter for number of constants used */ int istk; /* Loop counter for stack elements */ int ivar; /* Input variable number */ int narg; /* Number of function arguments */ int ncode; /* Number of opcodes to process */ int point; /* Loop counter for stack vector elements */ int sign; /* Argument is non-negative? */ int tos; /* Top of stack index */ static double d2r; /* Degrees to radians conversion factor */ static double log2; /* Natural logarithm of 2.0 */ static double pi; /* Value of PI */ static double r2d; /* Radians to degrees conversion factor */ static double rsafe_sq; /* Reciprocal of "safe_sq" */ static double safe_sq; /* Huge value that can safely be squared */ static int init = 0; /* Initialisation performed? */ unsigned long b1; /* Block of bits from first argument */ unsigned long b2; /* Block of bits from second argument */ unsigned long b; /* Block of bits for result */ unsigned long neg; /* Result is negative? (sign bit) */ /* Check the global error status. */ if ( !astOK ) return; /* If this is the first invocation of this function, then initialise constant values. */ LOCK_MUTEX2 if ( !init ) { /* Trigonometrical conversion factors. */ pi = acos( -1.0 ); r2d = 180.0 / pi; d2r = pi / 180.0; /* Natural logarithm of 2.0. */ log2 = log( 2.0 ); /* This value must be safe to square without producing overflow, yet large enough that adding or subtracting 1.0 from the square makes no difference. We also need its reciprocal. */ safe_sq = 0.9 * sqrt( DBL_MAX ); rsafe_sq = 1.0 / safe_sq; /* Note that initialisation has been performed. */ init = 1; } UNLOCK_MUTEX2 /* Allocate space for an array of pointers to elements of the workspace stack (each stack element being an array of double). */ stack = astMalloc( sizeof( double * ) * (size_t) stacksize ); /* Allocate space for the stack itself. */ work = astMalloc( sizeof( double ) * (size_t) ( npoint * ( stacksize - 1 ) ) ); /* If OK, then initialise the stack pointer array to identify the start of each vector on the stack. The first element points at the output array (in which the result will be accumulated), while other elements point at successive vectors within the workspace allocated above. */ if ( astOK ) { stack[ 0 ] = out; for ( istk = 1; istk < stacksize; istk++ ) { stack[ istk ] = work + ( istk - 1 ) * npoint; } /* Define stack operations. */ /* ======================== */ /* We now define a set of macros for performing vector operations on elements of the stack. Each is in the form of a "case" block for execution in response to the appropriate operation code (opcode). */ /* Zero-argument operation. */ /* ------------------------ */ /* This macro performs a zero-argument operation, which results in the insertion of a new vector on to the stack. */ #define ARG_0(oper,setup,function) \ \ /* Test for the required opcode value. */ \ case oper: \ \ /* Perform any required initialisation. */ \ {setup;} \ \ /* Increment the top of stack index and obtain a pointer to the new stack \ element (vector). */ \ yv = stack[ ++tos ]; \ \ /* Loop to access each vector element, obtaining a pointer to it. */ \ for ( point = 0; point < npoint; point++ ) { \ y = yv + point; \ \ /* Perform the processing, which results in assignment to this element. */ \ {function;} \ } \ \ /* Break out of the "case" block. */ \ break; /* One-argument operation. */ /* ----------------------- */ /* This macro performs a one-argument operation, which processes the top stack element without changing the stack size. */ #define ARG_1(oper,function) \ \ /* Test for the required opcode value. */ \ case oper: \ \ /* Obtain a pointer to the top stack element (vector). */ \ xv = stack[ tos ]; \ \ /* Loop to access each vector element, obtaining its value and \ checking that it is not bad. */ \ for ( point = 0; point < npoint; point++ ) { \ if ( ( x = xv[ point ] ) != AST__BAD ) { \ \ /* Also obtain a pointer to the element. */ \ y = xv + point; \ \ /* Perform the processing, which uses the element's value and then \ assigns the result to this element. */ \ {function;} \ } \ } \ \ /* Break out of the "case" block. */ \ break; /* One-argument boolean operation. */ /* ------------------------------- */ /* This macro is similar in function to ARG_1 above, except that no checks are made for bad argument values. It is intended for use with boolean functions where bad values are handled explicitly. */ #define ARG_1B(oper,function) \ \ /* Test for the required opcode value. */ \ case oper: \ \ /* Obtain a pointer to the top stack element (vector). */ \ xv = stack[ tos ]; \ \ /* Loop to access each vector element, obtaining the argument value \ and a pointer to the element. */ \ for ( point = 0; point < npoint; point++ ) { \ x = xv[ point ]; \ y = xv + point; \ \ /* Perform the processing, which uses the element's value and then \ assigns the result to this element. */ \ {function;} \ } \ \ /* Break out of the "case" block. */ \ break; /* Two-argument operation. */ /* ----------------------- */ /* This macro performs a two-argument operation, which processes the top two stack elements and produces a single result, resulting in the stack size decreasing by one. In this case, we first define a macro without the "case" block statements present. */ #define DO_ARG_2(function) \ \ /* Obtain pointers to the top two stack elements (vectors), decreasing \ the top of stack index by one. */ \ xv2 = stack[ tos-- ]; \ xv1 = stack[ tos ]; \ \ /* Loop to access each vector element, obtaining the value of the \ first argument and checking that it is not bad. */ \ for ( point = 0; point < npoint; point++ ) { \ if ( ( x1 = xv1[ point ] ) != AST__BAD ) { \ \ /* Also obtain a pointer to the element which is to receive the \ result. */ \ y = xv1 + point; \ \ /* Obtain the value of the second argument, again checking that it is \ not bad. */ \ if ( ( x2 = xv2[ point ] ) != AST__BAD ) { \ \ /* Perform the processing, which uses the two argument values and then \ assigns the result to the appropriate top of stack element. */ \ {function;} \ \ /* If the second argument was bad, so is the result. */ \ } else { \ *y = AST__BAD; \ } \ } \ } /* This macro simply wraps the one above up in a "case" block. */ #define ARG_2(oper,function) \ case oper: \ DO_ARG_2(function) \ break; /* Two-argument boolean operation. */ /* ------------------------------- */ /* This macro is similar in function to ARG_2 above, except that no checks are made for bad argument values. It is intended for use with boolean functions where bad values are handled explicitly. */ #define ARG_2B(oper,function) \ \ /* Test for the required opcode value. */ \ case oper: \ \ /* Obtain pointers to the top two stack elements (vectors), decreasing \ the top of stack index by one. */ \ xv2 = stack[ tos-- ]; \ xv1 = stack[ tos ]; \ \ /* Loop to access each vector element, obtaining the value of both \ arguments and a pointer to the element which is to receive the \ result. */ \ for ( point = 0; point < npoint; point++ ) { \ x1 = xv1[ point ]; \ x2 = xv2[ point ]; \ y = xv1 + point; \ \ /* Perform the processing, which uses the two argument values and then \ assigns the result to the appropriate top of stack element. */ \ {function;} \ } \ \ /* Break out of the "case" block. */ \ break; /* Three-argument boolean operation. */ /* --------------------------------- */ /* This macro is similar in function to ARG_2B above, except that it takes three values of the stack and puts one back. It performs no checks for bad values. */ #define ARG_3B(oper,function) \ \ /* Test for the required opcode value. */ \ case oper: \ \ /* Obtain pointers to the top three stack elements (vectors), decreasing \ the top of stack index by two. */ \ xv3 = stack[ tos-- ]; \ xv2 = stack[ tos-- ]; \ xv1 = stack[ tos ]; \ \ /* Loop to access each vector element, obtaining the value of all 3 \ arguments and a pointer to the element which is to receive the \ result. */ \ for ( point = 0; point < npoint; point++ ) { \ x1 = xv1[ point ]; \ x2 = xv2[ point ]; \ x3 = xv3[ point ]; \ y = xv1 + point; \ \ /* Perform the processing, which uses the three argument values and then \ assigns the result to the appropriate top of stack element. */ \ {function;} \ } \ \ /* Break out of the "case" block. */ \ break; /* Define arithmetic operations. */ /* ============================= */ /* We now define macros for performing some of the arithmetic operations we will require in a "safe" way - i.e. trapping numerical problems such as overflow and invalid arguments and translating them into the AST__BAD value. */ /* Absolute value. */ /* --------------- */ /* This is just shorthand. */ #define ABS(x) ( ( (x) >= 0.0 ) ? (x) : -(x) ) /* Integer part. */ /* ------------- */ /* This implements rounding towards zero without involving conversion to an integer (which could overflow). */ #define INT(x) ( ( (x) >= 0.0 ) ? floor( (x) ) : ceil( (x) ) ) /* Trap maths overflow. */ /* -------------------- */ /* This macro calls a C maths library function and checks for overflow in the result. */ #define CATCH_MATHS_OVERFLOW(function) \ ( \ \ /* Clear the "errno" value. */ \ errno = 0, \ \ /* Evaluate the function. */ \ result = (function), \ \ /* Check if "errno" and the returned result indicate overflow and \ return the appropriate result. */ \ ( ( errno == ERANGE ) && ( ABS( result ) == HUGE_VAL ) ) ? AST__BAD : \ result \ ) /* Trap maths errors. */ /* ------------------ */ /* This macro is similar to the one above, except that it also checks for domain errors (i.e. invalid argument values). */ #define CATCH_MATHS_ERROR(function) \ ( \ \ /* Clear the "errno" value. */ \ errno = 0, \ \ /* Evaluate the function. */ \ result = (function), \ \ /* Check if "errno" and the returned result indicate a domain error or \ overflow and return the appropriate result. */ \ ( ( errno == EDOM ) || \ ( ( errno == ERANGE ) && ( ABS( result ) == HUGE_VAL ) ) ) ? \ AST__BAD : result \ ) /* Tri-state boolean OR. */ /* --------------------- */ /* This evaluates a boolean OR using tri-state logic. For example, "a||b" may evaluate to 1 if "a" is bad but "b" is non-zero, so that the normal rules of bad value propagation do not apply. */ #define TRISTATE_OR(x1,x2) \ \ /* Test if the first argument is bad. */ \ ( (x1) == AST__BAD ) ? ( \ \ /* If so, test the second argument. */ \ ( ( (x2) == 0.0 ) || ( (x2) == AST__BAD ) ) ? AST__BAD : 1.0 \ ) : ( \ \ /* Test if the second argument is bad. */ \ ( (x2) == AST__BAD ) ? ( \ \ /* If so, test the first argument. */ \ ( (x1) == 0.0 ) ? AST__BAD : 1.0 \ \ /* If neither argument is bad, use the normal OR operator. */ \ ) : ( \ ( (x1) != 0.0 ) || ( (x2) != 0.0 ) \ ) \ ) /* Tri-state boolean AND. */ /* ---------------------- */ /* This evaluates a boolean AND using tri-state logic. */ #define TRISTATE_AND(x1,x2) \ \ /* Test if the first argument is bad. */ \ ( (x1) == AST__BAD ) ? ( \ \ /* If so, test the second argument. */ \ ( (x2) != 0.0 ) ? AST__BAD : 0.0 \ ) : ( \ \ /* Test if the second argument is bad. */ \ ( (x2) == AST__BAD ) ? ( \ \ /* If so, test the first argument. */ \ ( (x1) != 0.0 ) ? AST__BAD : 0.0 \ \ /* If neither argument is bad, use the normal AND operator. */ \ ) : ( \ ( (x1) != 0.0 ) && ( (x2) != 0.0 ) \ ) \ ) /* Safe addition. */ /* -------------- */ /* This macro performs addition while avoiding possible overflow. */ #define SAFE_ADD(x1,x2) ( \ \ /* Test if the first argument is non-negative. */ \ ( (x1) >= 0.0 ) ? ( \ \ /* If so, then we can perform addition if the second argument is \ non-positive. Otherwise, we must calculate the most positive safe \ second argument value that can be added and test for this (the test \ itself is safe against overflow). */ \ ( ( (x2) <= 0.0 ) || ( ( (DBL_MAX) - (x1) ) >= (x2) ) ) ? ( \ \ /* Perform addition if it is safe, otherwise return AST__BAD. */ \ (x1) + (x2) \ ) : ( \ AST__BAD \ ) \ \ /* If the first argument is negative, then we can perform addition if \ the second argument is non-negative. Otherwise, we must calculate the \ most negative second argument value that can be added and test for \ this (the test itself is safe against overflow). */ \ ) : ( \ ( ( (x2) >= 0.0 ) || ( ( (DBL_MAX) + (x1) ) >= -(x2) ) ) ? ( \ \ /* Perform addition if it is safe, otherwise return AST__BAD. */ \ (x1) + (x2) \ ) : ( \ AST__BAD \ ) \ ) \ ) /* Safe subtraction. */ /* ----------------- */ /* This macro performs subtraction while avoiding possible overflow. */ #define SAFE_SUB(x1,x2) ( \ \ /* Test if the first argument is non-negative. */ \ ( (x1) >= 0.0 ) ? ( \ \ /* If so, then we can perform subtraction if the second argument is \ also non-negative. Otherwise, we must calculate the most negative safe \ second argument value that can be subtracted and test for this (the \ test itself is safe against overflow). */ \ ( ( (x2) >= 0.0 ) || ( ( (DBL_MAX) - (x1) ) >= -(x2) ) ) ? ( \ \ /* Perform subtraction if it is safe, otherwise return AST__BAD. */ \ (x1) - (x2) \ ) : ( \ AST__BAD \ ) \ \ /* If the first argument is negative, then we can perform subtraction \ if the second argument is non-positive. Otherwise, we must calculate \ the most positive second argument value that can be subtracted and \ test for this (the test itself is safe against overflow). */ \ ) : ( \ ( ( (x2) <= 0.0 ) || ( ( (DBL_MAX) + (x1) ) >= (x2) ) ) ? ( \ \ /* Perform subtraction if it is safe, otherwise return AST__BAD. */ \ (x1) - (x2) \ ) : ( \ AST__BAD \ ) \ ) \ ) /* Safe multiplication. */ /* -------------------- */ /* This macro performs multiplication while avoiding possible overflow. */ #define SAFE_MUL(x1,x2) ( \ \ /* Multiplication is safe if the absolute value of either argument is \ unity or less. Otherwise, we must use the first argument to calculate \ the maximum absolute value that the second argument may have and test \ for this (the test itself is safe against overflow). */ \ ( ( ( abs1 = ABS( (x1) ) ) <= 1.0 ) || \ ( ( abs2 = ABS( (x2) ) ) <= 1.0 ) || \ ( ( (DBL_MAX) / abs1 ) >= abs2 ) ) ? ( \ \ /* Perform multiplication if it is safe, otherwise return AST__BAD. */ \ (x1) * (x2) \ ) : ( \ AST__BAD \ ) \ ) /* Safe division. */ /* -------------- */ /* This macro performs division while avoiding possible overflow. */ #define SAFE_DIV(x1,x2) ( \ \ /* Division is unsafe if the second argument is zero. Otherwise, it is \ safe if the abolute value of the second argument is unity or \ more. Otherwise, we must use the second argument to calculate the \ maximum absolute value that the first argument may have and test for \ this (the test itself is safe against overflow). */ \ ( ( (x2) != 0.0 ) && \ ( ( ( abs2 = ABS( (x2) ) ) >= 1.0 ) || \ ( ( (DBL_MAX) * abs2 ) >= ABS( (x1) ) ) ) ) ? ( \ \ /* Perform division if it is safe, otherwise return AST__BAD. */ \ (x1) / (x2) \ ) : ( \ AST__BAD \ ) \ ) /* Bit-shift operation. */ /* -------------------- */ /* This macro shifts the bits in a double value a specified number of places to the left, which simply corresponds to multiplying by the appropriate power of two. */ #define SHIFT_BITS(x1,x2) ( \ \ /* Decompose the value into a normalised fraction and a power of 2. */ \ frac = frexp( (x1), &expon ), \ \ /* Calculate the new power of 2 which should apply after the shift, \ rounding towards zero to give an integer value. */ \ newexp = INT( (x2) ) + (double) expon, \ \ /* If the new exponent is too negative to convert to an integer, then \ the result must underflow to zero. */ \ ( newexp < (double) -INT_MAX ) ? ( \ 0.0 \ \ /* Otherwise, if it is too positive to convert to an integer, then the \ result must overflow, unless the normalised fraction is zero. */ \ ) : ( ( newexp > (double) INT_MAX ) ? ( \ ( frac == 0.0 ) ? 0.0 : AST__BAD \ \ /* Otherwise, convert the new exponent to an integer and apply \ it. Trap any overflow which may still occur. */ \ ) : ( \ CATCH_MATHS_OVERFLOW( ldexp( frac, (int) newexp ) ) \ ) ) \ ) /* Two-argument bit-wise boolean operation. */ /* ---------------------------------------- */ /* This macro expands to code which performs a bit-wise boolean operation on a pair of arguments and assigns the result to the variable "result". It operates on floating point (double) values, which are regarded as if they are fixed-point binary numbers with negative values expressed in twos-complement notation. This means that it delivers the same results for integer values as the normal (integer) C bit-wise operations. However, it will also operate on the fraction bits of floating point numbers. It also offers greater precision (the first 53 or so significant bits of the result being preserved for typical IEEE floating point implementations). */ #define BIT_OPER(oper,x1,x2) \ \ /* Convert each argument to a normalised fraction in the range \ [0.5,1.0) and a power of two exponent, removing any sign \ information. */ \ frac1 = frexp( ABS( (x1) ), &expon1 ); \ frac2 = frexp( ABS( (x2) ), &expon2 ); \ \ /* Set "expon" to be the larger of the two exponents. If the two \ exponents are not equal, divide the fraction with the smaller exponent \ by 2 to the power of the exponent difference. This gives both \ fractions the same effective exponent (although one of them may no \ longer be normalised). Note that overflow is avoided because all \ numbers remain less than 1.0, but underflow may occur. */ \ expon = expon1; \ if ( expon2 > expon1 ) { \ expon = expon2; \ frac1 = ldexp( frac1, expon1 - expon ); \ } else if ( expon1 > expon2 ) { \ frac2 = ldexp( frac2, expon2 - expon ); \ } \ \ /* If either of the original arguments is negative, we now subtract \ the corresponding fraction from 2.0. If we think of the fraction as \ represented in fixed-point binary notation, this corresponds to \ converting negative numbers into the twos-complement form normally used \ for integers (the sign bit being the bit with value 1) instead \ of having a separate sign bit as for floating point numbers. \ \ Note that one of the fractions may have underflowed during the \ scaling above. In that case (if the original argument was negative), \ we must subtract the value "eps" (= 2.0 * DBL_EPSILON) from 2.0 \ instead, so that we produce the largest number less than 2.0. In \ twos-complement notation this represents the smallest possible \ negative number and corresponds to extending the sign bit of the \ original number up into more significant bits. This causes all bits to \ be set as we require (rather than all being clear if the underflow \ is simply ignored). */ \ if ( (x1) < 0.0 ) frac1 = 2.0 - ( ( frac1 > eps ) ? frac1 : eps ); \ if ( (x2) < 0.0 ) frac2 = 2.0 - ( ( frac2 > eps ) ? frac2 : eps ); \ \ /* We now extract the bits from the fraction values into integer \ variables so that we may perform bit-wise operations on them. However, \ since a double may be longer than any available integer, we may \ have to handle several successive blocks of bits individually. */ \ \ /* Extract the first block of bits by scaling by the required power of \ 2 to shift the required bits to the left of the binary point. Then \ extract the integer part. Note that this initial shift is one bit less \ than the number of bits in an unsigned long, because we have \ introduced an extra sign bit. */ \ frac1 *= scale1; \ frac2 *= scale1; \ b1 = (unsigned long) frac1; \ b2 = (unsigned long) frac2; \ \ /* Perform the required bit-wise operation on the extracted blocks of \ bits. */ \ b = b1 oper b2; \ \ /* Extract the sign bit from this initial result. This determines \ whether the final result bit pattern should represent a negative \ floating point number. */ \ neg = b & signbit; \ \ /* Initialise the floating point result by setting it to the integer \ result multipled by the reciprocal of the scale factor used to shift \ the bits above. This returns the result bits to their correct \ significance. */ \ unscale = rscale1; \ result = (double) b * unscale; \ \ /* We now loop to extract and process further blocks of bits (if \ present). The number of blocks is determined by the relative lengths \ of a double and an unsigned long. In practice, some bits of the double \ will be used by its exponent, so the last block may be incomplete and \ will simply be padded with zeros. */ \ for ( iblock = 1; iblock < nblock; iblock++ ) { \ \ /* Subtract the integer part (which has already been processed) from \ each fraction, to leave the bits which remain to be processed. Then \ multiply by a scale factor to shift the next set of bits to the left \ of the binary point. This time, we use as many bits as will fit into \ an unsigned long. */ \ frac1 = ( frac1 - (double) b1 ) * scale; \ frac2 = ( frac2 - (double) b2 ) * scale; \ \ /* Extract the integer part, which contains the required bits. */ \ b1 = (unsigned long) frac1; \ b2 = (unsigned long) frac2; \ \ /* Perform the required bit-wise operation on the extracted blocks of \ bits. */ \ b = b1 oper b2; \ \ /* Update the result floating point value by adding the new integer \ result multiplied by a scale factor to return the bits to their \ original significance. */ \ unscale *= rscale; \ result += (double) b * unscale; \ } \ \ /* If the (normalised fraction) result represents a negative number, \ then subtract 2.0 from it (equivalent to subtracting it from 2 and \ negating the result). This converts back to using a separate sign bit \ instead of twos-complement notation. */ \ if ( neg ) result -= 2.0; \ \ /* Scale by the required power of 2 to remove the initial \ normalisation applied and assign the result to the "result" \ variable. */ \ result = ldexp( result, expon ) /* Gaussian random number. */ /* ----------------------- */ /* This macro expands to code which assigns a pseudo-random value to the "result" variable. The value is drawn from a Gaussian distribution with mean "x1" and standard deviation "ABS(x2)". */ #define GAUSS(x1,x2) \ \ /* Loop until a satisfactory result is obtained. */ \ do { \ \ /* Obtain a value drawn from a standard Gaussian distribution. */ \ ran = Gauss( rcontext, status ); \ \ /* Multiply by "ABS(x2)", trapping possible overflow. */ \ result = ABS( (x2) ); \ result = SAFE_MUL( ran, result ); \ \ /* If OK, add "x1", again trapping possible overflow. */ \ if ( result != AST__BAD ) result = SAFE_ADD( result, (x1) ); \ \ /* Continue generating values until one is found which does not cause \ overflow. */ \ } while ( result == AST__BAD ); /* Implement the stack-based arithmetic. */ /* ===================================== */ /* Initialise the top of stack index and constant counter. */ tos = -1; icon = 0; /* Determine the number of opcodes to be processed and loop to process them, executing the appropriate "case" block for each one. */ ncode = code[ 0 ]; for ( icode = 1; icode <= ncode; icode++ ) { switch ( (Oper) code[ icode ] ) { /* Ignore any null opcodes (which shouldn't occur). */ case OP_NULL: break; /* Otherwise, perform the required vector operation on the stack... */ /* User-supplied constants and variables. */ /* -------------------------------------- */ /* Loading a constant involves incrementing the constant count and assigning the next constant's value to the top of stack element. */ ARG_0( OP_LDCON, value = con[ icon++ ], *y = value ) /* Loading a variable involves obtaining the variable's index by consuming a constant (as above), and then copying the variable's values into the top of stack element. */ ARG_0( OP_LDVAR, ivar = (int) ( con[ icon++ ] + 0.5 ), *y = ptr_in[ ivar ][ point ] ) /* System constants. */ /* ----------------- */ /* Loading a "bad" value simply means assigning AST__BAD to the top of stack element. */ ARG_0( OP_LDBAD, ;, *y = AST__BAD ) /* The following load constants associated with the (double) floating point representation into the top of stack element. */ ARG_0( OP_LDDIG, ;, *y = (double) DBL_DIG ) ARG_0( OP_LDEPS, ;, *y = DBL_EPSILON ) ARG_0( OP_LDMAX, ;, *y = DBL_MAX ) ARG_0( OP_LDMAX10E, ;, *y = (double) DBL_MAX_10_EXP ) ARG_0( OP_LDMAXE, ;, *y = (double) DBL_MAX_EXP ) ARG_0( OP_LDMDIG, ;, *y = (double) DBL_MANT_DIG ) ARG_0( OP_LDMIN, ;, *y = DBL_MIN ) ARG_0( OP_LDMIN10E, ;, *y = (double) DBL_MIN_10_EXP ) ARG_0( OP_LDMINE, ;, *y = (double) DBL_MIN_EXP ) ARG_0( OP_LDRAD, ;, *y = (double) FLT_RADIX ) ARG_0( OP_LDRND, ;, *y = (double) FLT_ROUNDS ) /* Mathematical constants. */ /* ----------------------- */ /* The following load mathematical constants into the top of stack element. */ ARG_0( OP_LDE, value = exp( 1.0 ), *y = value ) ARG_0( OP_LDPI, ;, *y = pi ) /* Functions with one argument. */ /* ---------------------------- */ /* The following simply evaluate a function of the top of stack element and assign the result to the same element. */ ARG_1( OP_ABS, *y = ABS( x ) ) ARG_1( OP_ACOS, *y = ( ABS( x ) <= 1.0 ) ? acos( x ) : AST__BAD ) ARG_1( OP_ACOSD, *y = ( ABS( x ) <= 1.0 ) ? acos( x ) * r2d : AST__BAD ) ARG_1( OP_ACOSH, *y = ( x < 1.0 ) ? AST__BAD : ( ( x > safe_sq ) ? log( x ) + log2 : log( x + sqrt( x * x - 1.0 ) ) ) ) ARG_1( OP_ACOTH, *y = ( ABS( x ) <= 1.0 ) ? AST__BAD : 0.5 * ( log( ( x + 1.0 ) / ( x - 1.0 ) ) ) ) ARG_1( OP_ACSCH, *y = ( ( x == 0.0 ) ? AST__BAD : ( sign = ( x >= 0.0 ), x = ABS( x ), ( sign ? 1.0 : -1.0 ) * ( ( x < rsafe_sq ) ? log2 - log( x ) : ( x = 1.0 / x, log( x + sqrt( x * x + 1.0 ) ) ) ) ) ) ) ARG_1( OP_ASECH, *y = ( ( x <= 0 ) || ( x > 1.0 ) ) ? AST__BAD : ( ( x < rsafe_sq ) ? log2 - log( x ) : ( x = 1.0 / x, log( x + sqrt( x * x - 1.0 ) ) ) ) ) ARG_1( OP_ASIN, *y = ( ABS( x ) <= 1.0 ) ? asin( x ) : AST__BAD ) ARG_1( OP_ASIND, *y = ( ABS( x ) <= 1.0 ) ? asin( x ) * r2d : AST__BAD ) ARG_1( OP_ASINH, *y = ( sign = ( x >= 0.0 ), x = ABS( x ), ( sign ? 1.0 : -1.0 ) * ( ( x > safe_sq ) ? log( x ) + log2 : log( x + sqrt( x * x + 1.0 ) ) ) ) ) ARG_1( OP_ATAN, *y = atan( x ) ) ARG_1( OP_ATAND, *y = atan( x ) * r2d ) ARG_1( OP_ATANH, *y = ( ABS( x ) >= 1.0 ) ? AST__BAD : 0.5 * ( log( ( 1.0 + x ) / ( 1.0 - x ) ) ) ) ARG_1( OP_CEIL, *y = ceil( x ) ) ARG_1( OP_COS, *y = cos( x ) ) ARG_1( OP_COSD, *y = cos( x * d2r ) ) ARG_1( OP_COSH, *y = CATCH_MATHS_OVERFLOW( cosh( x ) ) ) ARG_1( OP_COTH, *y = ( x = tanh( x ), SAFE_DIV( 1.0, x ) ) ) ARG_1( OP_CSCH, *y = ( x = CATCH_MATHS_OVERFLOW( sinh( x ) ), ( x == AST__BAD ) ? 0.0 : SAFE_DIV( 1.0, x ) ) ) ARG_1( OP_EXP, *y = CATCH_MATHS_OVERFLOW( exp( x ) ) ) ARG_1( OP_FLOOR, *y = floor( x ) ) ARG_1( OP_INT, *y = INT( x ) ) ARG_1B( OP_ISBAD, *y = ( x == AST__BAD ) ) ARG_1( OP_LOG, *y = ( x > 0.0 ) ? log( x ) : AST__BAD ) ARG_1( OP_LOG10, *y = ( x > 0.0 ) ? log10( x ) : AST__BAD ) ARG_1( OP_NINT, *y = ( x >= 0 ) ? floor( x + 0.5 ) : ceil( x - 0.5 ) ) ARG_1( OP_POISS, *y = Poisson( rcontext, x, status ) ) ARG_1( OP_SECH, *y = ( x = CATCH_MATHS_OVERFLOW( cosh( x ) ), ( x == AST__BAD ) ? 0.0 : 1.0 / x ) ) ARG_1( OP_SIN, *y = sin( x ) ) ARG_1( OP_SINC, *y = ( x == 0.0 ) ? 1.0 : sin( x ) / x ) ARG_1( OP_SIND, *y = sin( x * d2r ) ) ARG_1( OP_SINH, *y = CATCH_MATHS_OVERFLOW( sinh( x ) ) ) ARG_1( OP_SQR, *y = SAFE_MUL( x, x ) ) ARG_1( OP_SQRT, *y = ( x >= 0.0 ) ? sqrt( x ) : AST__BAD ) ARG_1( OP_TAN, *y = CATCH_MATHS_OVERFLOW( tan( x ) ) ) ARG_1( OP_TAND, *y = tan( x * d2r ) ) ARG_1( OP_TANH, *y = tanh( x ) ) /* Functions with two arguments. */ /* ----------------------------- */ /* These evaluate a function of the top two entries on the stack. */ ARG_2( OP_ATAN2, *y = atan2( x1, x2 ) ) ARG_2( OP_ATAN2D, *y = atan2( x1, x2 ) * r2d ) ARG_2( OP_DIM, *y = ( x1 > x2 ) ? x1 - x2 : 0.0 ) ARG_2( OP_GAUSS, GAUSS( x1, x2 ); *y = result ) ARG_2( OP_MOD, *y = ( x2 != 0.0 ) ? fmod( x1, x2 ) : AST__BAD ) ARG_2( OP_POW, *y = CATCH_MATHS_ERROR( pow( x1, x2 ) ) ) ARG_2( OP_RAND, ran = Rand( rcontext, status ); *y = x1 * ran + x2 * ( 1.0 - ran ); ) ARG_2( OP_SIGN, *y = ( ( x1 >= 0.0 ) == ( x2 >= 0.0 ) ) ? x1 : -x1 ) /* Functions with three arguments. */ /* ------------------------------- */ /* These evaluate a function of the top three entries on the stack. */ ARG_3B( OP_QIF, *y = ( ( x1 ) ? ( x2 ) : ( x3 ) ) ) /* Functions with variable numbers of arguments. */ /* --------------------------------------------- */ /* These operations take a variable number of arguments, the actual number being determined by consuming a constant. We then loop to perform a 2-argument operation on the stack (as above) the required number of times. */ case OP_MAX: narg = (int) ( con[ icon++ ] + 0.5 ); for ( iarg = 0; iarg < ( narg - 1 ); iarg++ ) { DO_ARG_2( *y = ( x1 >= x2 ) ? x1 : x2 ) } break; case OP_MIN: narg = (int) ( con[ icon++ ] + 0.5 ); for ( iarg = 0; iarg < ( narg - 1 ); iarg++ ) { DO_ARG_2( *y = ( x1 <= x2 ) ? x1 : x2 ) } break; /* Unary arithmetic operators. */ /* --------------------------- */ ARG_1( OP_NEG, *y = -x ) /* Unary boolean operators. */ /* ------------------------ */ ARG_1( OP_NOT, *y = ( x == 0.0 ) ) /* Binary arithmetic operators. */ /* ---------------------------- */ ARG_2( OP_ADD, *y = SAFE_ADD( x1, x2 ) ) ARG_2( OP_SUB, *y = SAFE_SUB( x1, x2 ) ) ARG_2( OP_MUL, *y = SAFE_MUL( x1, x2 ) ) ARG_2( OP_DIV , *y = SAFE_DIV( x1, x2 ) ) /* Bit-shift operators. */ /* -------------------- */ ARG_2( OP_SHFTL, *y = SHIFT_BITS( x1, x2 ) ) ARG_2( OP_SHFTR, *y = SHIFT_BITS( x1, -x2 ) ) /* Relational operators. */ /* --------------------- */ ARG_2( OP_EQ, *y = ( x1 == x2 ) ) ARG_2( OP_GE, *y = ( x1 >= x2 ) ) ARG_2( OP_GT, *y = ( x1 > x2 ) ) ARG_2( OP_LE, *y = ( x1 <= x2 ) ) ARG_2( OP_LT, *y = ( x1 < x2 ) ) ARG_2( OP_NE, *y = ( x1 != x2 ) ) /* Bit-wise operators. */ /* ------------------- */ ARG_2( OP_BITOR, BIT_OPER( |, x1, x2 ); *y = result ) ARG_2( OP_BITXOR, BIT_OPER( ^, x1, x2 ); *y = result ) ARG_2( OP_BITAND, BIT_OPER( &, x1, x2 ); *y = result ) /* Binary boolean operators. */ /* ------------------------- */ ARG_2B( OP_AND, *y = TRISTATE_AND( x1, x2 ) ) ARG_2( OP_EQV, *y = ( ( x1 != 0.0 ) == ( x2 != 0.0 ) ) ) ARG_2B( OP_OR, *y = TRISTATE_OR( x1, x2 ) ) ARG_2( OP_XOR, *y = ( ( x1 != 0.0 ) != ( x2 != 0.0 ) ) ) } } } /* When all opcodes have been processed, the result of the function evaluation will reside in the lowest stack entry - i.e. the output array. */ /* Free the workspace arrays. */ work = astFree( work ); stack = astFree( stack ); /* Undefine macros local to this function. */ #undef ARG_0 #undef ARG_1 #undef ARG_1B #undef DO_ARG_2 #undef ARG_2 #undef ARG_2B #undef ABS #undef INT #undef CATCH_MATHS_OVERFLOW #undef CATCH_MATHS_ERROR #undef TRISTATE_OR #undef TRISTATE_AND #undef SAFE_ADD #undef SAFE_SUB #undef SAFE_MUL #undef SAFE_DIV #undef SHIFT_BITS #undef BIT_OPER #undef GAUSS } static void EvaluationSort( const double con[], int nsym, int symlist[], int **code, int *stacksize, int *status ) { /* * Name: * EvaluationSort * Purpose: * Perform an evaluation-order sort on parsed expression symbols. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void EvaluationSort( const double con[], int nsym, int symlist[], * int **code, int *stacksize, int *status ) * Class Membership: * MathMap member function. * Description: * This function sorts a sequence of numbers representing symbols * identified in an expression. The symbols (i.e. the expression syntax) * must have been fully validated beforehand, as no validation is * performed here. * * The symbols are sorted into the order in which corresponding * operations must be performed on a push-down arithmetic stack in order * to evaluate the expression. Operation codes (opcodes), as defined in * the "Oper" enum, are then substituted for the symbol numbers. * Parameters: * con * Pointer to an array of double containing the set of constants * generated while parsing the expression (these are required in order * to determine the number of arguments associated with functions which * take a variable number of arguments). * nsym * The number of symbols identified while parsing the expression. * symlist * Pointer to an array of int, with "nsym" elements. On entry, this * should contain the indices in the static "symbol" array of the * symbols identified while parsing the expression. On exit, the * contents are undefined. * code * Address of a pointer which will be set to point at a dynamically * allocated array of int containing the set of opcodes (cast to int) * produced by this function. The first element of this array will * contain a count of the number of opcodes which follow. * * The allocated space must be freed by the caller (using astFree) when * no longer required. * stacksize * Pointer to an int in which to return the size of the push-down stack * required to evaluate the expression using the returned opcodes. * status * Pointer to the inherited status variable. * Notes: * - A value of NULL will be returned for the "*code" pointer and a value * of zero will be returned for the "*stacksize" value if this function is * invoked with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ int flush; /* Flush parenthesised symbol sequence? */ int icon; /* Input constant counter */ int isym; /* Input symbol counter */ int ncode; /* Number of opcodes generated */ int nstack; /* Evaluation stack size */ int push; /* Push a new symbol on to stack? */ int sym; /* Variable for symbol number */ int tos; /* Top of sort stack index */ /* Initialise */ *code = NULL; *stacksize = 0; /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ flush = 0; icon = 0; isym = 0; ncode = 0; nstack = 0; tos = -1; /* Loop to generate output opcodes until the sort stack is empty and there are no further symbols to process, or an error is detected. */ while ( astOK && ( ( tos > -1 ) || ( isym < nsym ) ) ) { /* Decide whether to push a symbol on to the sort stack (which "diverts" it so that higher-priority symbols can be output), or to pop the top symbol off the sort stack and send it to the output stream... */ /* We must push a symbol on to the sort stack if the stack is currently empty. */ if ( tos == -1 ) { push = 1; /* We must pop the top symbol off the sort stack if there are no more input symbols to process. */ } else if ( isym >= nsym ) { push = 0; /* If the sort stack is being flushed to complete the evaluation of a parenthesised expression, then the top symbol (which will be the opening parenthesis or function call) must be popped. This is only done once, so reset the "flush" flag before the next loop. */ } else if ( flush ) { push = 0; flush = 0; /* In all other circumstances, we must push a symbol on to the sort stack if its evaluation priority (seen from the left) is higher than that of the current top of stack symbol (seen from the right). This means it will eventually be sent to the output stream ahead of the current top of stack symbol. */ } else { push = ( symbol[ symlist[ isym ] ].leftpriority > symbol[ symlist[ tos ] ].rightpriority ); } /* If a symbol is being pushed on to the sort stack, then get the next input symbol which is to be used. */ if ( push ) { sym = symlist[ isym++ ]; /* If the symbol decreases the parenthesis level (a closing parenthesis), then all the sort stack entries down to the symbol which opened the current level of parenthesis (the matching opening parenthesis or function call) will already have been sent to the output stream as a consequence of the evaluation priority defined for a closing parenthesis in the symbol data. The opening parenthesis (or function call) must next be flushed from the sort stack, so set the "flush" flag which is interpreted on the next loop. Ignore the current symbol, which cancels with the opening parenthesis on the stack. */ if ( symbol[ sym ].parincrement < 0 ) { flush = 1; /* All other symbols are pushed on to the sort stack. The stack occupies that region of the "symlist" array from which the input symbol numbers have already been extracted. */ } else { symlist[ ++tos ] = sym; } /* If a symbol is being popped from the top of the sort stack, then the top of stack entry is transferred to the output stream. Obtain the symbol number from the stack. Increment the local constant counter if the associated operation will use a constant. */ } else { sym = symlist[ tos-- ]; icon += ( ( sym == symbol_ldvar ) || ( sym == symbol_ldcon ) ); /* If the output symbol does not represent a "null" operation, increase the size of the output opcode array to accommodate it, checking for errors. Note that we allocate one extra array element (the first) which will eventually hold a count of all the opcodes generated. */ if ( symbol[ sym ].opcode != OP_NULL ) { *code = astGrow( *code, ncode + 2, sizeof( int ) ); if ( astOK ) { /* Append the new opcode to the end of this array. */ ( *code )[ ++ncode ] = (int) symbol[ sym ].opcode; /* Increment/decrement the counter representing the stack size required for evaluation of the expression. If the symbol is a function with a variable number of arguments (indicated by a negative "nargs" entry in the symbol data table), then the change in stack size must be determined from the argument number stored in the constant table. */ if ( symbol[ sym ].nargs >= 0 ) { nstack += symbol[ sym ].stackincrement; } else { nstack -= (int) ( con[ icon++ ] + 0.5 ) - 1; } /* Note the maximum size of the stack. */ *stacksize = ( nstack > *stacksize ) ? nstack : *stacksize; } } } } /* If no "*code" array has been allocated, then allocate one simply to store the number of opcodes generated, i.e. zero (this shouldn't normally happen as this represents an invalid expression). */ if ( !*code ) *code = astMalloc( sizeof( int ) ); /* If no error has occurred, store the count of opcodes generated in the first element of the "*code" array and re-allocate the array to its final size (since astGrow may have over-allocated space). */ if ( astOK ) { ( *code )[ 0 ] = ncode; *code = astRealloc( *code, sizeof( int ) * (size_t) ( ncode + 1 ) ); } /* If an error occurred, free any memory that was allocated and reset the output values. */ if ( !astOK ) { *code = astFree( *code ); *stacksize = 0; } } static void ExtractExpressions( const char *method, const char *class, int nfun, const char *fun[], int forward, char ***exprs, int *status ) { /* * Name: * ExtractExpressions * Purpose: * Extract and validate expressions. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ExtractExpressions( const char *method, const char *class, * int nfun, const char *fun[], int forward, * char ***exprs, int *status ) * Class Membership: * MathMap member function. * Description: * This function extracts expressions from the right hand sides of a set * of functions. These expressions are then validated to check that they * are either all present, or all absent (absence indicating an undefined * transformation). An error is reported if anything is found to be * wrong. * * Note that the syntax of the expressions is not checked by this function * (i.e. they are not compiled). * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * nfun * The number of functions to be analysed. * fun * Pointer to an array, with "nfun" elements, of pointers to null * terminated strings which contain each of the functions. These * strings should contain no white space. * forward * A non-zero value indicates the the MathMap's forward transformation * functions are being processed, while a zero value indicates processing * of the inverse transformation functions. This value is used solely for * constructing error messages. * exprs * Address in which to return a pointer to an array (with "nfun" * elements) of pointers to null terminated strings containing the * extracted expressions (i.e. this returns an array of strings). * * Both the returned array of pointers, and the strings to which they * point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. * * If the right hand sides (including the "=" sign) of all the supplied * functions are absent, then this indicates an undefined transformation * and the returned pointer value will be NULL. An error results if * an "=" sign is present but no expression follows it. * status * Pointer to the inherited status variable. * Notes: * - A NULL value will be returned for "*exprs" if this function is * invoked with the global error status set, or if it should fail for * any reason. */ /* Local Variables: */ char *ex; /* Pointer to start of expression string */ int ifun; /* Loop counter for functions */ int iud; /* Index of first undefined function */ int nud; /* Number of undefined expressions */ /* Initialise. */ *exprs = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Further initialisation. */ nud = 0; iud = 0; /* Allocate and initialise memory for the returned array of pointers. */ MALLOC_POINTER_ARRAY( *exprs, char *, nfun ) /* Loop to inspect each function in turn. */ if ( astOK ) { for ( ifun = 0; ifun < nfun; ifun++ ) { /* Search for the first "=" sign. */ if ( ( ex = strchr( fun[ ifun ], '=' ) ) ) { /* If found, and there are more characters after the "=" sign, then find the length of the expression which follows. Allocate a string to hold this expression, storing its pointer in the array allocated above. Check for errors. */ if ( *++ex ) { ( *exprs )[ ifun ] = astMalloc( strlen( ex ) + (size_t) 1 ); if ( !astOK ) break; /* If OK, extract the expression string. */ (void) strcpy( ( *exprs )[ ifun ], ex ); /* If an "=" sign was found but there are no characters following it, then there is a missing right hand side to a function, so report an error and quit. */ } else { astError( AST__NORHS, "%s(%s): Missing right hand side in expression: " "\"%s\".", status, method, class, fun[ ifun ] ); astError( astStatus, "Error in %s transformation function %d.", status, forward ? "forward" : "inverse", ifun + 1 ); break; } /* If no "=" sign was found, then the transformation may be undefined, in which case each function should only contain a variable name. Count the number of times this happens and record the index of the first instance. */ } else { nud++; if ( nud == 1 ) iud = ifun; } } } /* Either all functions should have an "=" sign (in which case the transformation is defined), or none of them should have (in which case it is undefined). If some do and some don't, then report an error, citing the first instance of a missing "=" sign. */ if ( astOK && ( nud != 0 ) && ( nud != nfun ) ) { astError( AST__NORHS, "%s(%s): Missing right hand side in function: \"%s\".", status, method, class, fun[ iud ] ); astError( astStatus, "Error in %s transformation function %d.", status, forward ? "forward" : "inverse", iud + 1 ); } /* If an error occurred, or all the expressions were absent, then free any allocated memory and reset the output value. */ if ( !astOK || nud ) { FREE_POINTER_ARRAY( *exprs, nfun ) } } static void ExtractVariables( const char *method, const char *class, int nfun, const char *fun[], int nin, int nout, int nfwd, int ninv, int forward, char ***var, int *status ) { /* * Name: * ExtractVariables * Purpose: * Extract and validate variable names. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ExtractVariables( const char *method, const char *class, * int nfun, const char *fun[], * int nin, int nout, int nfwd, int ninv, * int forward, char ***var, int *status ) * Class Membership: * MathMap member function. * Description: * This function extracts variable names from the left hand sides of a * set of transformation functions belonging to a MathMap. These variable * names are then validated to check for correct syntax and no * duplication. An error is reported if anything is wrong with the * variable names obtained. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * nfun * The number of functions to be analysed. * fun * Pointer to an array, with "nfun" elements, of pointers to null * terminated strings which contain each of the functions. These strings * are case sensitive and should contain no white space. * * The first elements of this array should point to the functions that * define the primary input/output variables (depending on direction). * These should be followed by any functions which define intermediate * variables (taken from the set of functions which transform in the * opposite direction to the first ones). * nin * Number of input variables for the MathMap. * nout * Number of output variables for the MathMap. * nfwd * Number of forward transformation functions for the MathMap. * ninv * Number of inverse transformation functions for the MathMap. * forward * A non-zero value indicates the the MathMap's forward transformation * functions are being processed, while a zero value indicates processing * of the inverse transformation functions. This value, together with * "nin", "nout", "nfwd" and "ninv" are used solely for constructing * error messages. * var * Address in which to return a pointer to an array (with "nfun" * elements) of pointers to null terminated strings containing the * extracted variable names (i.e. this returns an array of strings). * * Both the returned array of pointers, and the strings to which they * point, will be stored in dynamically allocated memory and should * be freed by the caller (using astFree) when no longer required. * status * Pointer to the inherited status variable. * Notes: * - A NULL value will be returned for "*var" if this function is * invoked with the global error status set, or if it should fail for * any reason. */ /* Local Variables: */ char *duser1; /* Transformation direction for function */ char *duser2; /* Transformation direction for function */ char c; /* Extracted character */ int i1; /* Loop counter for detecting duplicates */ int i2; /* Loop counter for detecting duplicates */ int i; /* Loop counter for characters */ int iend; /* Last character index in parsed name */ int ifun; /* Loop counter for functions */ int iuser1; /* Function number as known to the user */ int iuser2; /* Function number as known to the user */ int nc; /* Character count */ int nextra; /* Number of intermediate functions */ int nprimary; /* Number of primary input/output variables */ /* Initialise. */ *var = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Obtain the number of primary input/output variables, depending on the direction of the coordinate transformation. */ nprimary = ( forward ? nin : nout ); /* Deterine the number of extra (intermediate) functions that come before these primary ones. These affect the numbering of transformation functions as known to the user, and must be accounted for when reporting error messages. */ nextra = ( forward ? ninv - nin : nfwd - nout ); /* Allocate and initialise memory for the returned array of pointers. */ MALLOC_POINTER_ARRAY( *var, char *, nfun ) /* Loop to process each function in turn. */ if ( astOK ) { for ( ifun = 0; ifun < nfun; ifun++ ) { /* Count the number of characters appearing before the "=" sign (or in the entire string if the "=" is absent). */ for ( nc = 0; ( c = fun[ ifun ][ nc ] ); nc++ ) if ( c == '=' ) break; /* If no characters were counted, then report an appropriate error message, depending on whether the function string was entirely blank. */ if ( !nc ) { if ( c ) { astError( AST__MISVN, "%s(%s): No left hand side in expression: \"%s\".", status, method, class, fun[ ifun ] ); } else { astError( AST__MISVN, "%s: Transformation function contains no variable " "name.", status, method ); } break; } /* If OK, allocate memory to hold the output string and check for errors. */ ( *var )[ ifun ] = astMalloc( sizeof( char ) * (size_t) ( nc + 1 ) ) ; if ( !astOK ) break; /* If OK, copy the characters before the "=" sign to the new string. */ nc = 0; for ( i = 0; ( c = fun[ ifun ][ i ] ); i++ ) { if ( c == '=' ) break; ( *var )[ ifun ][ nc++] = c; } /* Null terminate the result. */ ( *var )[ ifun ][ nc ] = '\0'; /* Try to parse the contents of the extracted string as a name. */ ParseName( ( *var )[ ifun ], 0, &iend, status ); /* If unsuccessful, or if all the characters were not parsed, then we have an invalid variable name, so report an error and quit. */ if ( ( iend < 0 ) || ( *var )[ ifun ][ iend + 1 ] ) { astError( AST__VARIN, "%s(%s): Variable name is invalid: \"%s\".", status, method, class, ( *var )[ ifun ] ); break; } } /* If an error occurred above, then determine the function number, and the direction of the transformation of which it forms part, as known to the user. */ if ( !astOK ) { if ( ifun < nprimary ) { iuser1 = ifun + 1 + nextra; duser1 = ( forward ? "inverse" : "forward" ); } else { iuser1 = ifun + 1 - nprimary; duser1 = ( forward ? "forward" : "inverse" ); } /* Report a contextual error message. */ astError( astStatus, "Error in %s transformation function %d.", status, duser1, iuser1 ); } } /* If there has been no error, loop to compare all the variable names with each other to detect duplication. */ if ( astOK ) { for ( i1 = 1; i1 < nfun; i1++ ) { for ( i2 = 0; i2 < i1; i2++ ) { /* If a duplicate variable name is found, report an error. */ if ( !strcmp( ( *var )[ i1 ], ( *var )[ i2 ] ) ) { astError( AST__DUVAR, "%s(%s): Duplicate definition of variable name: " "\"%s\".", status, method, class, ( *var )[ i1 ] ); /* For each transformation function involved, determine the function number and the direction of the transformation of which it forms part, as known to the user. */ if ( i1 < nprimary ) { iuser1 = i1 + 1 + nextra; duser1 = ( forward ? "inverse" : "forward" ); } else { iuser1 = i1 + 1 - nprimary; duser1 = ( forward ? "forward" : "inverse" ); } if ( i2 < nprimary ) { iuser2 = i2 + 1 + nextra; duser2 = ( forward ? "inverse" : "forward" ); } else { iuser2 = i2 + 1 - nprimary; duser2 = ( forward ? "forward" : "inverse" ); } /* Report a contextual error message. */ astError( astStatus, "Conflict between %s function %d and %s function %d.", status, duser1, iuser1, duser2, iuser2 ); break; } } if ( !astOK ) break; } } /* If an error occurred, free any allocated memory and reset the output value. */ if ( !astOK ) { FREE_POINTER_ARRAY( *var, nfun ) } } static double Gauss( Rcontext *context, int *status ) { /* * Name: * Gauss * Purpose: * Produce a pseudo-random sample from a standard Gaussian distribution. * Type: * Private function. * Synopsis: * #include "mathmap.h" * double Gauss( Rcontext *context, int *status ) * Class Membership: * MathMap member function. * Description: * On each invocation, this function returns a pseudo-random sample drawn * from a standard Gaussian distribution with mean zero and standard * deviation unity. The Box-Muller transformation method is used. * Parameters: * context * Pointer to an Rcontext structure which holds the random number * generator's context between invocations. * status * Pointer to the inherited status variable. * Returned Value: * A sample from a standard Gaussian distribution. * Notes: * - The sequence of numbers returned is determined by the "seed" * value in the Rcontext structure supplied. * - If the seed value is changed, the "active" flag must also be cleared * so that this function can re-initiallise the Rcontext structure before * generating the next pseudo-random number. The "active" flag should * also be clear to force initialisation the first time an Rcontext * structure is used. * - This function does not perform error checking and does not generate * errors. It will execute even if the global error status is set. */ /* Local Variables: */ double rsq; /* Squared radius */ double s; /* Scale factor */ double x; /* First result value */ static double y; /* Second result value */ static int ysaved = 0; /* Previously-saved value available? */ LOCK_MUTEX7 /* If the random number generator context is not active, then it will be (re)initialised on the first invocation of Rand (below). Ensure that any previously-saved value within this function is first discarded. */ if ( !context->active ) ysaved = 0; /* If there is a previously-saved value available, then use it and mark it as no longer available. */ if ( ysaved ) { x = y; ysaved = 0; /* Otherwise, loop until a suitable new pair of values has been obtained. */ } else { while ( 1 ) { /* Loop to obtain two random values uniformly distributed inside the unit circle, while avoiding the origin (which maps to an infinite result). */ do { x = 2.0 * Rand( context, status ) - 1.0; y = 2.0 * Rand( context, status ) - 1.0; rsq = x * x + y * y; } while ( ( rsq >= 1.0 ) || ( rsq == 0.0 ) ); /* Perform the Box-Muller transformation, checking that this will not produce overflow (which is extremely unlikely). If overflow would occur, we simply repeat the above steps with a new pair of random numbers. */ s = -2.0 * log( rsq ); if ( ( DBL_MAX * rsq ) >= s ) { s = sqrt( s / rsq ); /* Scale the original random values to give a pair of results. One will be returned and the second kept until next time. */ x *= s; y *= s; break; } } /* Note that a saved value is available. */ ysaved = 1; } UNLOCK_MUTEX7 /* Return the current result. */ return x; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "mathmap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * MathMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied MathMap, * in bytes. * Parameters: * this * Pointer to the MathMap. * 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: */ AstMathMap *this; /* Pointer to MathMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the MathMap structure. */ this = (AstMathMap *) 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 ); SIZEOF_POINTER_ARRAY( this->fwdfun, this->nfwd ) SIZEOF_POINTER_ARRAY( this->invfun, this->ninv ) SIZEOF_POINTER_ARRAY( this->fwdcode, this->nfwd ) SIZEOF_POINTER_ARRAY( this->invcode, this->ninv ) SIZEOF_POINTER_ARRAY( this->fwdcon, this->nfwd ) SIZEOF_POINTER_ARRAY( this->invcon, this->ninv ) /* 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 MathMap. * Type: * Private function. * Synopsis: * #include "mathmap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * MathMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a MathMap, formatted as a character string. * Parameters: * this * Pointer to the MathMap. * 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 MathMap, 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 MathMap. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMathMap *this; /* Pointer to the MathMap structure */ const char *result; /* Pointer value to return */ int ival; /* Integer attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) 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. */ /* Seed. */ /* ----- */ if ( !strcmp( attrib, "seed" ) ) { ival = astGetSeed( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* SimpFI. */ /* ------- */ } else if ( !strcmp( attrib, "simpfi" ) ) { ival = astGetSimpFI( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* SimpIF. */ /* ------- */ } else if ( !strcmp( attrib, "simpif" ) ) { ival = astGetSimpIF( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } void astInitMathMapVtab_( AstMathMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitMathMapVtab * Purpose: * Initialise a virtual function table for a MathMap. * Type: * Protected function. * Synopsis: * #include "mathmap.h" * void astInitMathMapVtab( AstMathMapVtab *vtab, const char *name ) * Class Membership: * MathMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the MathMap 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 */ 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. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAMathMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearSeed = ClearSeed; vtab->ClearSimpFI = ClearSimpFI; vtab->ClearSimpIF = ClearSimpIF; vtab->GetSeed = GetSeed; vtab->GetSimpFI = GetSimpFI; vtab->GetSimpIF = GetSimpIF; vtab->SetSeed = SetSeed; vtab->SetSimpFI = SetSimpFI; vtab->SetSimpIF = SetSimpIF; vtab->TestSeed = TestSeed; vtab->TestSimpFI = TestSimpFI; vtab->TestSimpIF = TestSimpIF; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "MathMap", "Transformation using mathematical functions" ); /* 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 double LogGamma( double x, int *status ) { /* * Name: * LogGamma * Purpose: * Calculate the logarithm of the gamma function. * Type: * Private function. * Synopsis: * #include "mathmap.h" * double LogGamma( double x, int *status ) * Class Membership: * MathMap member function. * Description: * This function returns the natural logarithm of the gamma function * for real arguments x>0. It uses the approximation of Lanczos, with * constants from Press et al. (Numerical Recipes), giving a maximum * fractional error (on the gamma function) of less than 2e-10. * Parameters: * x * The function argument, which must be greater than zero. * status * Pointer to the inherited status variable. * Returned Value: * The natural logarithm of the gamma function with "x" as argument, * or AST__BAD if "x" is not greater than zero. * Notes: * - This function does not generate errors and does not perform error * reporting. It will execute even if the global error status is set. */ /* Local Constants: */ const double c0 = 1.000000000190015; /* Coefficients for series sum... */ const double c1 = 76.18009172947146; const double c2 = -86.50532032941677; const double c3 = 24.01409824083091; const double c4 = -1.231739572450155; const double c5 = 0.1208650973866179e-2; const double c6 = -0.5395239384953e-5; const double g = 5.0; /* Local Variables: */ double result; /* Result value to return */ double sum; /* Series sum */ double xx; /* Denominator for summing series */ static double root_twopi; /* sqrt( 2.0 * pi ) */ static int init = 0; /* Initialisation performed? */ /* If initialisation has not yet been performed, calculate the constant required below. */ LOCK_MUTEX3 if ( !init ) { root_twopi = sqrt( 2.0 * acos( -1.0 ) ); /* Note that initialisation has been performed. */ init = 1; } UNLOCK_MUTEX3 /* Return a bad value if "x" is not greater than zero. */ if ( x <= 0.0 ) { result = AST__BAD; /* Otherwise, form the series sum. Since we only use 6 terms, the loop that would normally be used has been completely unrolled here. */ } else { xx = x; sum = c0; sum += c1 / ++xx; sum += c2 / ++xx; sum += c3 / ++xx; sum += c4 / ++xx; sum += c5 / ++xx; sum += c6 / ++xx; /* Calculate the result. */ result = x + g + 0.5; result -= ( x + 0.5 ) * log( result ); result = log( root_twopi * sum / x ) - result; } /* Return the result. */ return result; } static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a MathMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * MathMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated MathMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated MathMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated MathMap which is to be merged with * its neighbours. This should be a cloned copy of the MathMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * MathMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated MathMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *new; /* Pointer to replacement Mapping */ AstMathMap *mathmap1; /* Pointer to first MathMap */ AstMathMap *mathmap2; /* Pointer to second MathMap */ char **fwd1; /* Pointer to first forward function array */ char **fwd2; /* Pointer to second forward function array */ char **inv1; /* Pointer to first inverse function array */ char **inv2; /* Pointer to second inverse function array */ int ifun; /* Loop counter for functions */ int imap1; /* Index of first Mapping */ int imap2; /* Index of second Mapping */ int imap; /* Loop counter for Mappings */ int invert1; /* Invert flag for first MathMap */ int invert2; /* Invert flag for second MathMap */ int nfwd1; /* No. forward functions for first MathMap */ int nfwd2; /* No. forward functions for second MathMap */ int nin1; /* Number input coords for first MathMap */ int ninv1; /* No. inverse functions for first MathMap */ int ninv2; /* No. inverse functions for second MathMap */ int nout2; /* Number output coords for second MathMap */ int result; /* Result value to return */ int simplify; /* Mappings may simplify? */ /* Initialise the returned result. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ mathmap1 = NULL; mathmap2 = NULL; imap1 = 0; imap2 = 0; invert1 = 0; invert2 = 0; nfwd1 = 0; nin1 = 0; ninv1 = 0; /* MathMaps are only worth simplifying if they occur in series. */ simplify = series; /* If simplification appears possible, then obtain the indices of the nominated mapping and of the one which follows it. Check that a mapping exists for the second index. */ if ( simplify ) { imap1 = where; imap2 = imap1 + 1; simplify = ( imap2 < *nmap ); } /* If OK, check whether the class of both Mappings is "MathMap" (a MathMap can only combine with another MathMap). */ if ( simplify ) { simplify = !strcmp( astGetClass( ( *map_list )[ imap1 ] ), "MathMap" ); } if ( astOK && simplify ) { simplify = !strcmp( astGetClass( ( *map_list )[ imap2 ] ), "MathMap" ); } /* If still OK, obtain pointers to the two MathMaps and the associated invert flag values. */ if ( astOK && simplify ) { mathmap1 = (AstMathMap *) ( *map_list )[ imap1 ]; mathmap2 = (AstMathMap *) ( *map_list )[ imap2 ]; invert1 = ( *invert_list )[ imap1 ]; invert2 = ( *invert_list )[ imap2 ]; /* Depending on the invert flag values, obtain the SimpFI or SimpIF attribute value from each MathMap and check whether they are set so as to permit simplification. */ simplify = ( ( invert1 ? astGetSimpIF( mathmap1 ) : astGetSimpFI( mathmap1 ) ) && ( invert2 ? astGetSimpFI( mathmap2 ) : astGetSimpIF( mathmap2 ) ) ); } /* If still OK, obtain the effective numbers of input coordinates for the first MathMap and output coordinates for the second. Take account of the associated invert flags and the way the Invert attribute of each MathMap is currently set. */ if ( astOK && simplify ) { nin1 = ( invert1 == astGetInvert( mathmap1 ) ) ? astGetNin( mathmap1 ) : astGetNout( mathmap1 ); nout2 = ( invert2 == astGetInvert( mathmap2 ) ) ? astGetNout( mathmap2 ) : astGetNin( mathmap2 ); /* Simplification is only possible if these two numbers are equal (otherwise the the two MathMaps cannot be identical). */ simplify = ( nin1 == nout2 ); } /* If still OK, obtain the effective number of forward transformation functions for the first MathMap (allowing for the associated invert flag). Similarly, obtain the effective number of inverse transformation functions for the second MathMap. */ if ( astOK && simplify ) { nfwd1 = !invert1 ? mathmap1->nfwd : mathmap1->ninv; ninv2 = !invert2 ? mathmap2->ninv : mathmap2->nfwd; /* Check whether these values are equal. The MathMaps cannot be identical if they are not. */ simplify = ( nfwd1 == ninv2 ); } /* As above, obtain pointers to the array of effective forward transformation functions for the first MathMap, and the effective inverse transformation functions for the second MathMap. */ if ( astOK && simplify ) { fwd1 = !invert1 ? mathmap1->fwdfun : mathmap1->invfun; inv2 = !invert2 ? mathmap2->invfun : mathmap2->fwdfun; /* Loop to check whether these two sets of functions are identical. The MathMaps cannot be merged unless they are. */ for ( ifun = 0; ifun < nfwd1; ifun++ ) { simplify = !strcmp( fwd1[ ifun ], inv2[ ifun ] ); if ( !simplify ) break; } } /* If OK, repeat the above process to compare the effective inverse transformation functions of the first MathMap with the forward functions of the second one. */ if ( astOK && simplify ) { ninv1 = !invert1 ? mathmap1->ninv : mathmap1->nfwd; nfwd2 = !invert2 ? mathmap2->nfwd : mathmap2->ninv; simplify = ( ninv1 == nfwd2 ); } if ( astOK && simplify ) { inv1 = !invert1 ? mathmap1->invfun : mathmap1->fwdfun; fwd2 = !invert2 ? mathmap2->fwdfun : mathmap2->invfun; for ( ifun = 0; ifun < ninv1; ifun++ ) { simplify = !strcmp( inv1[ ifun ], fwd2[ ifun ] ); if ( !simplify ) break; } } /* If the two MathMaps can be merged, create a UnitMap as a replacement. */ if ( astOK && simplify ) { new = (AstMapping *) astUnitMap( nin1, "", status ); /* If OK, annul the pointers to the original MathMaps. */ if ( astOK ) { ( *map_list )[ imap1 ] = astAnnul( ( *map_list )[ imap1 ] ); ( *map_list )[ imap2 ] = astAnnul( ( *map_list )[ imap2 ] ); /* Insert the pointer to the replacement UnitMap and store the associated invert flag. */ ( *map_list )[ imap1 ] = new; ( *invert_list )[ imap1 ] = 0; /* Loop to move the following Mapping pointers and invert flags down in their arrays to close the gap. */ for ( imap = imap2 + 1; imap < *nmap; imap++ ) { ( *map_list )[ imap - 1 ] = ( *map_list )[ imap ]; ( *invert_list )[ imap - 1 ] = ( *invert_list )[ imap ]; } /* Clear the final entry in each array. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = imap1; } } /* If an error occurred, clear the returned value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } static void ParseConstant( const char *method, const char *class, const char *exprs, int istart, int *iend, double *con, int *status ) { /* * Name: * ParseConstant * Purpose: * Parse a constant. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ParseConstant( const char *method, const char *class, * const char *exprs, int istart, int *iend, * double *con, int *status ) * Class Membership: * MathMap member function. * Description: * This routine parses an expression, looking for a constant starting at * the character with index "istart" in the string "exprs". If it * identifies the constant successfully, "*con" it will return its value * and "*iend" will be set to the index of the final constant character * in "exprs". * * If the characters encountered are clearly not part of a constant (it * does not begin with a numeral or decimal point) the function returns * with "*con" set to zero and "*iend" set to -1, but without reporting * an error. However, if the first character appears to be a constant but * its syntax proves to be invalid, then an error is reported. * * The expression must be in lower case with no embedded white space. * The constant must not have a sign (+ or -) in front of it. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * exprs * Pointer to a null-terminated string containing the expression * to be parsed. * istart * Index of the first character in "exprs" to be considered by this * function. * iend * Pointer to an int in which to return the index in "exprs" of the * final character which forms part of the constant. If no constant is * found, a value of -1 is returned. * con * Pointer to a double, in which the value of the constant, if found, * will be returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char *str; /* Pointer to temporary string */ char c; /* Single character from the expression */ int dpoint; /* Decimal point encountered? */ int expon; /* Exponent character encountered? */ int i; /* Loop counter for characters */ int iscon; /* Character is part of the constant? */ int n; /* Number of values read by astSscanf */ int nc; /* Number of characters read by astSscanf */ int numer; /* Numeral encountered in current field? */ int sign; /* Sign encountered? */ int valid; /* Constant syntax valid? */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise. */ *con = 0.0; *iend = -1; /* Check if the expression starts with a numeral or a decimal point. */ c = exprs[ istart ]; numer = isdigit( c ); dpoint = ( c == '.' ); /* If it begins with any of these, the expression is clearly intended to be a constant, so any failure beyond this point will result in an error. Otherwise, failure to find a constant is not an error. */ if ( numer || dpoint ) { /* Initialise remaining variables specifying the parser context. */ expon = 0; sign = 0; valid = 1; /* Loop to increment the last constant character position until the following character in the expression does not look like part of the constant. */ *iend = istart; iscon = 1; while ( ( c = exprs[ *iend + 1 ] ) && iscon ) { iscon = 0; /* It may be part of a numerical constant if it is a numeral, wherever it occurs. */ if ( isdigit( c ) ) { numer = 1; iscon = 1; /* Or a decimal point, so long as it is the first one and is not in the exponent field. Otherwise it is invalid. */ } else if ( c == '.' ) { if ( !( dpoint || expon ) ) { dpoint = 1; iscon = 1; } else { valid = 0; } /* Or if it is a 'd' or 'e' exponent character, so long as it is the first one and at least one numeral has been encountered first. Otherwise it is invalid. */ } else if ( ( c == 'd' ) || ( c == 'e' ) ) { if ( !expon && numer ) { expon = 1; numer = 0; iscon = 1; } else { valid = 0; } /* Or if it is a sign, so long as it is in the exponent field and is the first sign with no previous numerals in the same field. Otherwise it is invalid (unless numerals have been encountered, in which case it marks the end of the constant). */ } else if ( ( c == '+' ) || ( c == '-' ) ) { if ( expon && !sign && !numer ) { sign = 1; iscon = 1; } else if ( !numer ) { valid = 0; } } /* Increment the character count if the next character may be part of the constant, or if it was invalid (it will then form part of the error message). */ if ( iscon || !valid ) ( *iend )++; } /* Finally, check that the last field contained a numeral. */ valid = ( valid && numer ); /* If the constant appears valid, allocate a temporary string to hold it. */ if ( valid ) { str = astMalloc( (size_t) ( *iend - istart + 2 ) ); if ( astOK ) { /* Copy the constant's characters, changing 'd' to 'e' so that "astSscanf" will recognise it as an exponent character. */ for ( i = istart; i <= *iend; i++ ) { str[ i - istart ] = ( exprs[ i ] == 'd' ) ? 'e' : exprs[ i ]; } str[ *iend - istart + 1 ] = '\0'; /* Attempt to read the constant as a double, noting how many values are read and how many characters consumed. */ n = astSscanf( str, "%lf%n", con, &nc ); /* Check that one value was read and all the characters consumed. If not, then the constant's syntax is invalid. */ if ( ( n != 1 ) || ( nc < ( *iend - istart + 1 ) ) ) valid = 0; } /* Free the temporary string. */ str = astFree( str ); } /* If the constant syntax is invalid, and no other error has occurred, then report an error. */ if ( astOK && !valid ) { astError( AST__CONIN, "%s(%s): Invalid constant syntax in the expression " "\"%.*s\".", status, method, class, *iend + 1, exprs ); } /* If an error occurred, reset the output values. */ if ( !astOK ) { *iend = -1; *con = 0.0; } } } static void ParseName( const char *exprs, int istart, int *iend, int *status ) { /* * Name: * ParseName * Purpose: * Parse a name. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ParseName( const char *exprs, int istart, int *iend, int *status ) * Class Membership: * MathMap member function. * Description: * This routine parses an expression, looking for a name starting at the * character with index "istart" in the string "exprs". If it identifies * a name successfully, "*iend" will return the index of the final name * character in "exprs". A name must begin with an alphabetic character * and subsequently contain only alphanumeric characters or underscores. * * If the expression does not contain a name at the specified location, * "*iend" is set to -1. No error results. * * The expression should not contain embedded white space. * Parameters: * exprs * Pointer to a null-terminated string containing the expression * to be parsed. * istart * Index of the first character in "exprs" to be considered by this * function. * iend * Pointer to an int in which to return the index in "exprs" of the * final character which forms part of the name. If no name is * found, a value of -1 is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ char c; /* Single character from expression */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise. */ *iend = -1; /* Check the first character is valid for a name (alphabetic). */ if ( isalpha( exprs[ istart ] ) ) { /* If so, loop to inspect each subsequent character until one is found which is not part of a name (not alphanumeric or underscore). */ for ( *iend = istart; ( c = exprs[ *iend + 1 ] ); ( *iend )++ ) { if ( !( isalnum( c ) || ( c == '_' ) ) ) break; } } } static void ParseVariable( const char *method, const char *class, const char *exprs, int istart, int nvar, const char *var[], int *ivar, int *iend, int *status ) { /* * Name: * ParseVariable * Purpose: * Parse a variable name. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ParseVariable( const char *method, const char *class, * const char *exprs, int istart, int nvar, * const char *var[], int *ivar, int *iend, int *status ) * Class Membership: * MathMap member function. * Description: * This routine parses an expression, looking for a recognised variable * name starting at the character with index "istart" in the string * "exprs". If it identifies a variable name successfully, "*ivar" will * return a value identifying it and "*iend" will return the index of the * final variable name character in "exprs". To be recognised, a name * must begin with an alphabetic character and subsequently contain only * alphanumeric characters or underscores. It must also appear in the * list of defined variable names supplied to this function. * * If the expression does not contain a name at the specified location, * "*ivar" and "*iend" are set to -1 and no error results. However, if * the expression contains a name but it is not in the list of defined * variable names supplied, then an error is reported. * * This function is case sensitive. The expression should not contain * embedded white space. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * exprs * Pointer to a null-terminated string containing the expression * to be parsed. * istart * Index of the first character in "exprs" to be considered by this * function. * nvar * The number of defined variable names. * var * An array of pointers (with "nvar" elements) to null-terminated * strings. Each of these should contain a variable name to be * recognised. These strings are case sensitive and should contain * no white space. * ivar * Pointer to an int in which to return the index in "vars" of the * variable name found. If no variable name is found, a value of -1 * is returned. * iend * Pointer to an int in which to return the index in "exprs" of the * final character which forms part of the variable name. If no variable * name is found, a value of -1 is returned. * status * Pointer to the inherited status variable. */ /* Local Variables: */ int found; /* Variable name recognised? */ int nc; /* Number of characters in variable name */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise. */ *ivar = -1; *iend = -1; /* Determine if the characters in the expression starting at index "istart" constitute a valid name. */ ParseName( exprs, istart, iend, status ); /* If so, calculate the length of the name. */ if ( *iend >= istart ) { nc = *iend - istart + 1; /* Loop to compare the name with the list of variable names supplied. */ found = 0; for ( *ivar = 0; *ivar < nvar; ( *ivar )++ ) { found = ( nc == (int) strlen( var[ *ivar ] ) ) && !strncmp( exprs + istart, var[ *ivar ], (size_t) nc ); /* Break if the name is recognised. */ if ( found ) break; } /* If it was not recognised, then report an error and reset the output values. */ if ( !found ) { astError( AST__UDVOF, "%s(%s): Undefined variable or function in the expression " "\"%.*s\".", status, method, class, *iend + 1, exprs ); *ivar = -1; *iend = -1; } } } static double Poisson( Rcontext *context, double mean, int *status ) { /* * Name: * Poisson * Purpose: * Produce a pseudo-random sample from a Poisson distribution. * Type: * Private function. * Synopsis: * #include "mathmap.h" * double Poisson( Rcontext *context, double mean, int *status ) * Class Membership: * MathMap member function. * Description: * On each invocation, this function returns a pseudo-random sample drawn * from a Poisson distribution with a specified mean. A combination of * methods is used, depending on the value of the mean. The algorithm is * based on that given by Press et al. (Numerical Recipes), but * re-implemented and extended. * Parameters: * context * Pointer to an Rcontext structure which holds the random number * generator's context between invocations. * mean * The mean of the Poisson distribution, which should not be * negative. * status * Pointer to the inherited status variable. * Returned Value: * A sample (which will only take integer values) from the Poisson * distribution, or AST__BAD if the mean supplied is negative. * Notes: * - The sequence of numbers returned is determined by the "seed" * value in the Rcontext structure supplied. * - If the seed value is changed, the "active" flag must also be cleared * so that this function can re-initiallise the Rcontext structure before * generating the next pseudo-random number. The "active" flag should * also be clear to force initialisation the first time an Rcontext * structure is used. * - This function does not perform error checking and does not generate * errors. It will execute even if the global error status is set. */ /* Local Constants: */ const double small = 9.3; /* "Small" distribution mean value */ /* Local Variables: */ double pfract; /* Probability of accepting sample */ double product; /* Product of random samples */ double ran; /* Sample from Lorentzian distribution */ double result; /* Result value to return */ static double beta; /* Constant for forming acceptance ratio */ static double huge; /* Large mean where std. dev. is negligible */ static double last_mean; /* Value of "mean" on last invocation */ static double log_mean; /* Logarithm of "mean" */ static double pi; /* Value of pi */ static double ranmax; /* Maximum safe value of "ran" */ static double root_2mean; /* sqrt( 2.0 * mean ) */ static double sqrt_point9; /* Square root of 0.9 */ static double thresh; /* Threshold for product of samples */ static int init = 0; /* Local initialisation performed? */ LOCK_MUTEX6 /* If initialisation has not yet been performed, then perform it now. */ if ( !init ) { /* Initialise the mean value from the previous invocation. */ last_mean = -1.0; /* Calculate simple constants. */ pi = acos( -1.0 ); sqrt_point9 = sqrt( 0.9 ); /* Calculate the value of the distribution mean for which the smallest representable deviation from the mean permitted by the machine precision is one thousand standard deviations. */ huge = pow( 1.0e3 / DBL_EPSILON, 2.0 ); /* Calculate the largest value such that (0.9+(sqrt_point9*ranmax)*(sqrt_point9*ranmax)) doesn't overflow, allowing a small margin for rounding error. */ ranmax = ( sqrt( DBL_MAX - 0.9 ) / sqrt( 0.9 ) ) * ( 1.0 - 4.0 * DBL_EPSILON ); /* Note that initialisation has been performed. */ init = 1; } /* If the distribution mean is less than zero, then return a bad result. */ if ( mean < 0.0 ) { result = AST__BAD; /* If the mean is zero, then the result can only be zero. */ } else if ( mean == 0.0 ) { result = 0.0; /* Otherwise, if the mean is sufficiently small, we can use the direct method of summing a series of exponentially distributed random samples and counting the number which occur before the mean is exceeded. This is equivalent to multiplying a series of uniformly distributed samples and counting the number which occur before the product becomes less then an equivalent threshold. */ } else if ( mean <= small ) { /* If the mean has changed since the last invocation, store the new mean and calculate a new threshold. */ if ( mean != last_mean ) { last_mean = mean; thresh = exp( -mean ); } /* Initialise the product and the result. */ product = 1.0; result = -1.0; /* Multiply the random samples, counting the number needed to reach the threshold. */ do { product *= Rand( context, status ); result += 1.0; } while ( product > thresh ); /* Otherwise, if the distribution mean is large (but not huge), we must use an indirect rejection method. */ } else if ( mean <= huge ) { /* If the mean has changed since the last invocation, then re-calculate the constants required below. Note that because of the restrictions we have placed on "mean", these calculations are safe against overflow. */ if ( mean != last_mean ) { last_mean = mean; log_mean = log( mean ); root_2mean = sqrt( 2.0 * mean ); beta = mean * log_mean - LogGamma( mean + 1.0, status ); } /* Loop until a suitable random sample has been generated. */ do { do { /* First transform a sample from a uniform distribution to obtain a sample from a Lorentzian distribution. Check that the result is not so large as to cause overflow later. Also check for overflow in the maths library. If necessary, obtain a new sample. */ do { errno = 0; ran = tan( pi * Rand( context, status ) ); } while ( ( ran > ranmax ) || ( ( errno == ERANGE ) && ( ( ( ran >= 0.0 ) ? ran : -ran ) == HUGE_VAL ) ) ); /* If OK, scale the sample and add a constant so that the sample's distribution approximates the Poisson distribution we require. Overflow is prevented by the check on "ran" above, together with the restricted value of "mean". */ result = ran * root_2mean + mean; /* If the result is less than zero (where the Poisson distribution has value zero), then obtain a new sample. */ } while ( result < 0.0 ); /* Round down to an integer, so that the sample is valid for a Poisson distribution. */ result = floor( result ); /* Calculate the ratio between the required Poisson distribution and the Lorentzian from which we have sampled (the factor of 0.9 prevents this exceeding 1.0, and overflow is again prevented by the checks performed above). */ ran *= sqrt_point9; pfract = ( 0.9 + ran * ran ) * exp( result * log_mean - LogGamma( result + 1.0, status ) - beta ); /* Accept the sample with this fractional probability, otherwise obtain a new sample. */ } while ( Rand( context, status ) > pfract ); /* If the mean is huge, the relative standard deviation will be negligible compared to the machine precision. In such cases, the probability of getting a result that differs from the mean is effectively zero, so we can simply return the mean. */ } else { result = mean; } UNLOCK_MUTEX6 /* Return the result. */ return result; } static double Rand( Rcontext *context, int *status ) { /* * Name: * Rand * Purpose: * Produce a uniformly distributed pseudo-random number. * Type: * Private function. * Synopsis: * #include "mathmap.h" * double Rand( Rcontext *context, int *status ) * Class Membership: * MathMap member function. * Description: * On each invocation, this function returns a pseudo-random number * uniformly distributed in the range 0.0 to 1.0 (inclusive). The * underlying algorithm is that used by the "ran2" function of Press et * al. (Numerical Recipes), which has a long period and good statistical * properties. This independent implementation returns double precision * values. * Parameters: * context * Pointer to an Rcontext structure which holds the random number * generator's context between invocations. * status * Pointer to the inherited status variable. * Notes: * - The sequence of numbers returned is determined by the "seed" * value in the Rcontext structure supplied. * - If the seed value is changed, the "active" flag must also be cleared * so that this function can re-initiallise the Rcontext structure before * generating the next pseudo-random number. The "active" flag should * also be clear to force initialisation the first time an Rcontext * structure is used. * - This function does not perform error checking and does not generate * errors. It will execute even if the global error status is set. */ /* Local Constants: */ const long int a1 = 40014L; /* Random number generator constants... */ const long int a2 = 40692L; const long int m1 = 2147483563L; const long int m2 = 2147483399L; const long int q1 = 53668L; const long int q2 = 52774L; const long int r1 = 12211L; const long int r2 = 3791L; const int ntab = /* Size of shuffle table */ AST_MATHMAP_RAND_CONTEXT_NTAB_; const int nwarm = 8; /* Number of warm-up iterations */ /* Local Variables: */ double result; /* Result value to return */ double scale; /* Scale factor for random integers */ double sum; /* Sum for forming normalisation constant */ int dbits; /* Approximate bits in double mantissa */ int irand; /* Loop counter for random integers */ int itab; /* Loop counter for shuffle table */ int lbits; /* Approximate bits used by generators */ long int seed; /* Random number seed */ long int tmp; /* Temporary variable */ static double norm; /* Normalisation constant */ static double scale0; /* Scale decrement for successive integers */ static int init = 0; /* Local initialisation performed? */ static int nrand; /* Number of random integers to use */ /* If the random number generator context is not active, then initialise it. */ if ( !context->active ) { /* First, perform local initialisation for this function, if not already done. */ LOCK_MUTEX4 if ( !init ) { /* Obtain the approximate number of bits used by the random integer generator from the value "m1". */ (void) frexp( (double) m1, &lbits ); /* Obtain the approximate number of bits used by the mantissa of the double value we want to produce, allowing for the (unlikely) possibility that the mantissa's radix isn't 2. */ dbits = (int) ceil( (double) DBL_MANT_DIG * log( (double) FLT_RADIX ) / log( 2.0 ) ); /* Hence determine how many random integers we need to combine to produce each double value, so that all the mantissa's bits will be used. */ nrand = ( dbits + lbits - 1 ) / lbits; /* Calculate the scale factor by which each successive random integer's contribution to the result is reduced so as to generate progressively less significant bits. */ scale0 = 1.0 / (double) ( m1 - 1L ); /* Loop to sum the maximum contributions from each random integer (assuming that each takes the largest possible value, of "m1-1", from which we will later subtract 1). This produces the normalisation factor by which the result must be scaled so as to lie between 0.0 and 1.0 (inclusive). */ sum = 0.0; scale = 1.0; for ( irand = 0; irand < nrand; irand++ ) { scale *= scale0; sum += scale; } norm = 1.0 / ( sum * (double) ( m1 - 2L ) ); /* Note that local initialisation has been done. */ init = 1; } UNLOCK_MUTEX4 /* Obtain the seed value, enforcing positivity. */ seed = (long int) context->seed; if ( seed < 1 ) seed = seed + LONG_MAX; if ( seed < 1 ) seed = LONG_MAX; /* Initialise the random number generators with this seed. */ context->rand1 = context->rand2 = seed; /* Now loop to initialise the shuffle table with an initial set of random values. We generate more values than required in order to "warm up" the generator before recording values in the table. */ for ( itab = ntab + nwarm - 1; itab >= 0; itab-- ) { /* Repeatedly update "rand1" from the expression "(rand1*a1)%m1" while avoiding overflow. */ tmp = context->rand1 / q1; context->rand1 = a1 * ( context->rand1 - tmp * q1 ) - tmp * r1; if ( context->rand1 < 0L ) context->rand1 += m1; /* After warming up, start recording values in the table. */ if ( itab < ntab ) context->table[ itab ] = context->rand1; } /* Record the last entry in the table as the "previous" random integer. */ context->random_int = context->table[ 0 ]; /* Note the random number generator context is active. */ context->active = 1; } /* Generate a random value. */ /* ------------------------ */ /* Initialise. */ result = 0.0; /* Loop to generate sufficient random integers to combine into a double value. */ scale = norm; for ( irand = 0; irand < nrand; irand++ ) { /* Update the first generator "rand1" from the expression "(a1*rand1)%m1" while avoiding overflow. */ tmp = context->rand1 / q1; context->rand1 = a1 * ( context->rand1 - tmp * q1 ) - tmp * r1; if ( context->rand1 < 0L ) context->rand1 += m1; /* Similarly, update the second generator "rand2" from the expression "(a2*rand2)%m2". */ tmp = context->rand2 / q2; context->rand2 = a2 * ( context->rand2 - tmp * q2 ) - tmp * r2; if ( context->rand2 < 0L ) context->rand2 += m2; /* Use the previous random integer to generate an index into the shuffle table. */ itab = (int) ( context->random_int / ( 1L + ( m1 - 1L ) / (long int) ntab ) ); /* The algorithm left by RFWS seems to have a bug that "itab" can sometimes be outside the range of [0.,ntab-1] causing the context->table array to be addressed out of bounds. To avoid this, use the following sticking plaster, since I'm not sure what the correct fix is. */ if( itab < 0 ) itab = -itab; itab = itab % ntab; /* Extract the table entry and replace it with a new random value from the first generator "rand1". This is the Bays-Durham shuffle. */ context->random_int = context->table[ itab ]; context->table[ itab ] = context->rand1; /* Combine the extracted value with the latest value from the second generator "rand2". */ context->random_int -= context->rand2; if ( context->random_int < 1L ) context->random_int += m1 - 1L; /* Update the scale factor to apply to the resulting random integer and accumulate its contribution to the result. */ scale *= scale0; result += scale * (double) ( context->random_int - 1L ); } /* Return the result. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a MathMap. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * MathMap member function (extends the astSetAttrib method inherited from * the Mapping class). * Description: * This function assigns an attribute value for a MathMap, 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 MathMap. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Returned Value: * void */ /* Local Vaiables: */ AstMathMap *this; /* Pointer to the MathMap structure */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) 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. */ /* Seed. */ /* ----- */ if ( nc = 0, ( 1 == astSscanf( setting, "seed= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetSeed( this, ival ); /* SimpFI. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "simpfi= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetSimpFI( this, ival ); /* SimpIF. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "simpif= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetSimpIF( this, ival ); /* Pass any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a MathMap. * Type: * Private function. * Synopsis: * #include "mathmap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * MathMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a MathMap's attributes. * Parameters: * this * Pointer to the MathMap. * 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: */ AstMathMap *this; /* Pointer to the MathMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* Seed. */ /* ----- */ if ( !strcmp( attrib, "seed" ) ) { result = astTestSeed( this ); /* SimpFI. */ /* ------- */ } else if ( !strcmp( attrib, "simpfi" ) ) { result = astTestSimpFI( this ); /* SimpIF. */ /* ------- */ } else if ( !strcmp( attrib, "simpif" ) ) { result = astTestSimpIF( this ); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *map, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a MathMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "mathmap.h" * AstPointSet *Transform( AstMapping *map, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * MathMap member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a MathMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required coordinate * transformation. * Parameters: * map * Pointer to the MathMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the MathMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstMathMap *this; /* Pointer to MathMap to be applied */ AstPointSet *result; /* Pointer to output PointSet */ double **data_ptr; /* Array of pointers to coordinate data */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *work; /* Workspace for intermediate results */ int idata; /* Loop counter for data pointer elements */ int ifun; /* Loop counter for functions */ int ncoord_in; /* Number of coordinates per input point */ int ncoord_out; /* Number of coordinates per output point */ int ndata; /* Number of data pointer elements filled */ int nfun; /* Number of functions to evaluate */ int npoint; /* Number of points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ work = NULL; /* Obtain a pointer to the MathMap. */ this = (AstMathMap *) map; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( map, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the transformation needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input and output PointSets and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); ncoord_out = astGetNcoord( result ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Determine whether to apply the forward or inverse transformation, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( this ) ) forward = !forward; /* Obtain the number of transformation functions that must be evaluated to perform the transformation. This will include any that produce intermediate results from which the final results are calculated. */ nfun = forward ? this->nfwd : this->ninv; /* If intermediate results are to be calculated, then allocate workspace to hold them (each intermediate result being a vector of "npoint" double values). */ if ( nfun > ncoord_out ) { work = astMalloc( sizeof( double) * (size_t) ( npoint * ( nfun - ncoord_out ) ) ); } /* Also allocate space for an array to hold pointers to the input data, intermediate results and output data. */ data_ptr = astMalloc( sizeof( double * ) * (size_t) ( ncoord_in + nfun ) ); /* We now set up the "data_ptr" array to locate the data to be processed. */ if ( astOK ) { /* The first elements of this array point at the input data vectors. */ ndata = 0; for ( idata = 0; idata < ncoord_in; idata++ ) { data_ptr[ ndata++ ] = ptr_in[ idata ]; } /* The following elements point at successive vectors within the workspace array (if allocated). These vectors will act first as output arrays for intermediate results, and then as input arrays for subsequent calculations which use these results. */ for ( idata = 0; idata < ( nfun - ncoord_out ); idata++ ) { data_ptr[ ndata++ ] = work + ( idata * npoint ); } /* The final elements point at the output coordinate data arrays into which the final results will be written. */ for ( idata = 0; idata < ncoord_out; idata++ ) { data_ptr[ ndata++ ] = ptr_out[ idata ]; } /* Perform coordinate transformation. */ /* ---------------------------------- */ /* Loop to evaluate each transformation function in turn. */ for ( ifun = 0; ifun < nfun; ifun++ ) { /* Invoke the function that evaluates compiled expressions. Pass the appropriate code and constants arrays, depending on the direction of coordinate transformation, together with the required stack size. The output array is the vector located by successive elements of the "data_ptr" array (skipping the input data elements), while the function has access to all previous elements of the "data_ptr" array to locate the required input data. */ EvaluateFunction( &this->rcontext, npoint, (const double **) data_ptr, forward ? this->fwdcode[ ifun ] : this->invcode[ ifun ], forward ? this->fwdcon[ ifun ] : this->invcon[ ifun ], forward ? this->fwdstack : this->invstack, data_ptr[ ifun + ncoord_in ], status ); } } /* Free the array of data pointers and any workspace allocated for intermediate results. */ data_ptr = astFree( data_ptr ); if ( nfun > ncoord_out ) work = astFree( work ); /* If an error occurred, then return a NULL pointer. If no output PointSet was supplied, also delete any new one that may have been created. */ if ( !astOK ) { result = ( result == out ) ? NULL : astDelete( result ); } /* Return a pointer to the output PointSet. */ return result; } static void ValidateSymbol( const char *method, const char *class, const char *exprs, int iend, int sym, int *lpar, int **argcount, int **opensym, int *ncon, double **con, int *status ) { /* * Name: * ValidateSymbol * Purpose: * Validate a symbol in an expression. * Type: * Private function. * Synopsis: * #include "mathmap.h" * void ValidateSymbol( const char *method, const char *class, * const char *exprs, int iend, int sym, int *lpar, * int **argcount, int **opensym, int *ncon, * double **con, int *status ) * Class Membership: * MathMap member function. * Description: * This function validates an identified standard symbol during * compilation of an expression. Its main task is to keep track of the * level of parenthesis in the expression and to count the number of * arguments supplied to functions at each level of parenthesis (for * nested function calls). On this basis it is able to interpret and * accept or reject symbols which represent function calls, parentheses * and delimiters. Other symbols are accepted automatically. * Parameters: * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function. * This method name is used solely for constructing error messages. * class * Pointer to a constant null-terminated character string containing the * class name of the Object being processed. This name is used solely * for constructing error messages. * exprs * Pointer to a null-terminated string containing the expression * being parsed. This is only used for constructing error messages. * iend * Index in "exprs" of the last character belonging to the most * recently identified symbol. This is only used for constructing error * messages. * sym * Index in the static "symbol" array of the most recently identified * symbol in the expression. This is the symbol to be verified. * lpar * Pointer to an int which holds the current level of parenthesis. On * the first invocation, this should be zero. The returned value should * be passed to subsequent invocations. * argcount * Address of a pointer to a dynamically allocated array of int in * which argument count information is maintained for each level of * parenthesis (e.g. for nested function calls). On the first invocation, * "*argcount" should be NULL. This function will allocate the required * space as needed and update this pointer. The returned pointer value * should be passed to subsequent invocations. * * The allocated space must be freed by the caller (using astFree) when * no longer required. * opensym * Address of a pointer to a dynamically allocated array of int, in which * information is maintained about the functions associated with each * level of parenthesis (e.g. for nested function calls). On the first * invocation, "*opensym" should be NULL. This function will allocate the * required space as needed and update this pointer. The returned pointer * value should be passed to subsequent invocations. * * The allocated space must be freed by the caller (using astFree) when * no longer required. * ncon * Pointer to an int which holds a count of the constants associated * with the expression (and determines the size of the "*con" array). * This function will update the count to reflect any new constants * appended to the "*con" array and the returned value should be passed * to subsequent invocations. * con * Address of a pointer to a dynamically allocated array of double, in * which the constants associated with the expression being parsed are * accumulated. On entry, "*con" should point at a dynamic array with * at least "*ncon" elements containing existing constants (or may be * NULL if no constants have yet been stored). This function will * allocate the required space as needed and update this pointer (and * "*ncon") appropriately. The returned pointer value should be passed * to subsequent invocations. * * The allocated space must be freed by the caller (using astFree) when * no longer required. * status * Pointer to the inherited status variable. * Notes: * - The dynamically allocated arrays normally returned by this function * will be freed and NULL pointers 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, but do not return at this point because dynamic arrays may require freeing. */ if ( astOK ) { /* Check if the symbol is a comma. */ if ( ( symbol[ sym ].text[ 0 ] == ',' ) && ( symbol[ sym ].text[ 1 ] == '\0' ) ) { /* A comma is only used to delimit function arguments. If the current level of parenthesis is zero, or the symbol which opened the current level of parenthesis was not a function call (indicated by an argument count of zero at the current level of parenthesis), then report an error. */ if ( ( *lpar <= 0 ) || ( ( *argcount )[ *lpar - 1 ] == 0 ) ) { astError( AST__COMIN, "%s(%s): Spurious comma encountered in the expression " "\"%.*s\".", status, method, class, iend + 1, exprs ); /* If a comma is valid, then increment the argument count at the current level of parenthesis. */ } else { ( *argcount )[ *lpar - 1 ]++; } /* If the symbol is not a comma, check if it increases the current level of parenthesis. */ } else if ( symbol[ sym ].parincrement > 0 ) { /* Increase the size of the arrays which hold parenthesis level information and check for errors. */ *argcount = astGrow( *argcount, *lpar + 1, sizeof( int ) ); *opensym = astGrow( *opensym, *lpar + 1, sizeof( int ) ); if ( astOK ) { /* Increment the level of parenthesis and initialise the argument count at the new level. This count is set to zero if the symbol which opens the parenthesis level is not a function call (indicated by a zero "nargs" entry in the symbol data), and it subsequently remains at zero. If the symbol is a function call, the argument count is initially set to 1 and increments whenever a comma is encountered at this parenthesis level. */ ( *argcount )[ ++( *lpar ) - 1 ] = ( symbol[ sym ].nargs != 0 ); /* Remember the symbol which opened this parenthesis level. */ ( *opensym )[ *lpar - 1 ] = sym; } /* Check if the symbol decreases the current parenthesis level. */ } else if ( symbol[ sym ].parincrement < 0 ) { /* Ensure that the parenthesis level is not already at zero. If it is, then there is a missing left parenthesis in the expression being compiled, so report an error. */ if ( *lpar == 0 ) { astError( AST__MLPAR, "%s(%s): Missing left parenthesis in the expression " "\"%.*s\".", status, method, class, iend + 1, exprs ); /* If the parenthesis level is valid and the symbol which opened this level of parenthesis was a function call with a fixed number of arguments (indicated by a positive "nargs" entry in the symbol data), then we must check the number of function arguments which have been encountered. */ } else if ( symbol[ ( *opensym )[ *lpar - 1 ] ].nargs > 0 ) { /* Report an error if the number of arguments is wrong. */ if ( ( *argcount )[ *lpar - 1 ] != symbol[ ( *opensym )[ *lpar - 1 ] ].nargs ) { astError( AST__WRNFA, "%s(%s): Wrong number of function arguments in the " "expression \"%.*s\".", status, method, class, iend + 1, exprs ); /* If the number of arguments is valid, decrement the parenthesis level. */ } else { ( *lpar )--; } /* If the symbol which opened this level of parenthesis was a function call with a variable number of arguments (indicated by a negative "nargs" entry in the symbol data), then we must check and process the number of function arguments. */ } else if ( symbol[ ( *opensym )[ *lpar - 1 ] ].nargs < 0 ) { /* Check that the minimum required number of arguments have been supplied. Report an error if they have not. */ if ( ( *argcount )[ *lpar - 1 ] < ( -symbol[ ( *opensym )[ *lpar - 1 ] ].nargs ) ) { astError( AST__WRNFA, "%s(%s): Insufficient function arguments in the " "expression \"%.*s\".", status, method, class, iend + 1, exprs ); /* If the number of arguments is valid, increase the size of the constants array and check for errors. */ } else { *con = astGrow( *con, *ncon + 1, sizeof( double ) ); if ( astOK ) { /* Append the argument count to the end of the array of constants and decrement the parenthesis level. */ ( *con )[ ( *ncon )++ ] = (double) ( *argcount )[ --( *lpar ) ]; } } /* Finally, if the symbol which opened this level of parenthesis was not a function call ("nargs" entry in the symbol data is zero), then decrement the parenthesis level. In this case there is no need to check the argument count, because it will not have been incremented. */ } else { ( *lpar )--; } } } /* If an error occurred (or the global error status was set on entry), then reset the parenthesis level and free any memory which may have been allocated. */ if ( !astOK ) { *lpar = 0; if ( *argcount ) *argcount = astFree( *argcount ); if ( *opensym ) *opensym = astFree( *opensym ); if ( *con ) *con = astFree( *con ); } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * Seed * Purpose: * Random number seed for a MathMap. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute, which may take any integer value, determines the * sequence of random numbers produced by the random number functions in * MathMap expressions. It is set to an unpredictable default value when * a MathMap is created, so that by default each MathMap uses a different * set of random numbers. * * If required, you may set this Seed attribute to a value of your * choosing in order to produce repeatable behaviour from the random * number functions. You may also enquire the Seed value (e.g. if an * initially unpredictable value has been used) and then use it to * reproduce the resulting sequence of random numbers, either from the * same MathMap or from another one. * * Clearing the Seed attribute gives it a new unpredictable default * value. * Applicability: * MathMap * All MathMaps have this attribute. *att-- */ /* Clear the Seed value by setting it to a new unpredictable value produced by DefaultSeed and clearing the "seed_set" flag in the MathMap's random number generator context. Also clear the "active" flag, so that the generator will be re-initialised to use this seed when it is next invoked. */ astMAKE_CLEAR(MathMap,Seed,rcontext.seed,( this->rcontext.seed_set = 0, this->rcontext.active = 0, DefaultSeed( &this->rcontext, status ) )) /* Return the "seed" value from the random number generator context. */ astMAKE_GET(MathMap,Seed,int,0,this->rcontext.seed) /* Store the new seed value in the MathMap's random number generator context and set the context's "seed_set" flag. Also clear the "active" flag, so that the generator will be re-initialised to use this seed when it is next invoked. */ astMAKE_SET(MathMap,Seed,int,rcontext.seed,( this->rcontext.seed_set = 1, this->rcontext.active = 0, value )) /* Test the "seed_set" flag in the random number generator context. */ astMAKE_TEST(MathMap,Seed,( this->rcontext.seed_set )) /* *att++ * Name: * SimpFI * Purpose: * Forward-inverse MathMap pairs simplify? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: c This attribute should be set to a non-zero value if applying a c MathMap's forward transformation, followed immediately by the matching c inverse transformation will always restore the original set of c coordinates. It indicates that AST may replace such a sequence of c operations by an identity Mapping (a UnitMap) if it is encountered c while simplifying a compound Mapping (e.g. using astSimplify). f This attribute should be set to a non-zero value if applying a f MathMap's forward transformation, followed immediately by the matching f inverse transformation will always restore the original set of f coordinates. It indicates that AST may replace such a sequence of f operations by an identity Mapping (a UnitMap) if it is encountered f while simplifying a compound Mapping (e.g. using AST_SIMPLIFY). * * By default, the SimpFI attribute is zero, so that AST will not perform * this simplification unless you have set SimpFI to indicate that it is * safe to do so. * Applicability: * MathMap * All MathMaps have this attribute. * Notes: * - For simplification to occur, the two MathMaps must be in series and * be identical (with textually identical transformation * functions). Functional equivalence is not sufficient. * - The consent of both MathMaps is required before simplification can * take place. If either has a SimpFI value of zero, then simplification * will not occur. * - The SimpFI attribute controls simplification only in the case where * a MathMap's forward transformation is followed by the matching inverse * transformation. It does not apply if an inverse transformation is * followed by a forward transformation. This latter case is controlled * by the SimpIF attribute. c - The "forward" and "inverse" transformations referred to are those c defined when the MathMap is created (corresponding to the "fwd" and c "inv" parameters of its constructor function). If the MathMap is c inverted (i.e. its Invert attribute is non-zero), then the role of the c SimpFI and SimpIF attributes will be interchanged. f - The "forward" and "inverse" transformations referred to are those f defined when the MathMap is created (corresponding to the FWD and f INV arguments of its constructor function). If the MathMap is f inverted (i.e. its Invert attribute is non-zero), then the role of the f SimpFI and SimpIF attributes will be interchanged. *att-- */ /* Clear the SimpFI value by setting it to -INT_MAX. */ astMAKE_CLEAR(MathMap,SimpFI,simp_fi,-INT_MAX) /* Supply a default of 0 if no SimpFI value has been set. */ astMAKE_GET(MathMap,SimpFI,int,0,( ( this->simp_fi != -INT_MAX ) ? this->simp_fi : 0 )) /* Set a SimpFI value of 1 if any non-zero value is supplied. */ astMAKE_SET(MathMap,SimpFI,int,simp_fi,( value != 0 )) /* The SimpFI value is set if it is not -INT_MAX. */ astMAKE_TEST(MathMap,SimpFI,( this->simp_fi != -INT_MAX )) /* *att++ * Name: * SimpIF * Purpose: * Inverse-forward MathMap pairs simplify? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: c This attribute should be set to a non-zero value if applying a c MathMap's inverse transformation, followed immediately by the matching c forward transformation will always restore the original set of c coordinates. It indicates that AST may replace such a sequence of c operations by an identity Mapping (a UnitMap) if it is encountered c while simplifying a compound Mapping (e.g. using astSimplify). f This attribute should be set to a non-zero value if applying a f MathMap's inverse transformation, followed immediately by the matching f forward transformation will always restore the original set of f coordinates. It indicates that AST may replace such a sequence of f operations by an identity Mapping (a UnitMap) if it is encountered f while simplifying a compound Mapping (e.g. using AST_SIMPLIFY). * * By default, the SimpIF attribute is zero, so that AST will not perform * this simplification unless you have set SimpIF to indicate that it is * safe to do so. * Applicability: * MathMap * All MathMaps have this attribute. * Notes: * - For simplification to occur, the two MathMaps must be in series and * be identical (with textually identical transformation * functions). Functional equivalence is not sufficient. * - The consent of both MathMaps is required before simplification can * take place. If either has a SimpIF value of zero, then simplification * will not occur. * - The SimpIF attribute controls simplification only in the case where * a MathMap's inverse transformation is followed by the matching forward * transformation. It does not apply if a forward transformation is * followed by an inverse transformation. This latter case is controlled * by the SimpFI attribute. c - The "forward" and "inverse" transformations referred to are those c defined when the MathMap is created (corresponding to the "fwd" and c "inv" parameters of its constructor function). If the MathMap is c inverted (i.e. its Invert attribute is non-zero), then the role of the c SimpFI and SimpIF attributes will be interchanged. f - The "forward" and "inverse" transformations referred to are those f defined when the MathMap is created (corresponding to the FWD and f INV arguments of its constructor function). If the MathMap is f inverted (i.e. its Invert attribute is non-zero), then the role of the f SimpFI and SimpIF attributes will be interchanged. *att-- */ /* Clear the SimpIF value by setting it to -INT_MAX. */ astMAKE_CLEAR(MathMap,SimpIF,simp_if,-INT_MAX) /* Supply a default of 0 if no SimpIF value has been set. */ astMAKE_GET(MathMap,SimpIF,int,0,( ( this->simp_if != -INT_MAX ) ? this->simp_if : 0 )) /* Set a SimpIF value of 1 if any non-zero value is supplied. */ astMAKE_SET(MathMap,SimpIF,int,simp_if,( value != 0 )) /* The SimpIF value is set if it is not -INT_MAX. */ astMAKE_TEST(MathMap,SimpIF,( this->simp_if != -INT_MAX )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for MathMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for MathMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstMathMap *in; /* Pointer to input MathMap */ AstMathMap *out; /* Pointer to output MathMap */ int ifun; /* Loop counter for functions */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output MathMaps. */ in = (AstMathMap *) objin; out = (AstMathMap *) objout; /* For safety, first clear any references to the input memory from the output MathMap. */ out->fwdfun = NULL; out->invfun = NULL; out->fwdcode = NULL; out->invcode = NULL; out->fwdcon = NULL; out->invcon = NULL; /* Now allocate and initialise each of the output pointer arrays required. */ if ( in->fwdfun ) { MALLOC_POINTER_ARRAY( out->fwdfun, char *, out->nfwd ) } if ( in->invfun ) { MALLOC_POINTER_ARRAY( out->invfun, char *, out->ninv ) } if ( in->fwdcode ) { MALLOC_POINTER_ARRAY( out->fwdcode, int *, out->nfwd ) } if ( in->invcode ) { MALLOC_POINTER_ARRAY( out->invcode, int *, out->ninv ) } if ( in->fwdcon ) { MALLOC_POINTER_ARRAY( out->fwdcon, double *, out->nfwd ) } if ( in->invcon ) { MALLOC_POINTER_ARRAY( out->invcon, double *, out->ninv ) } /* If OK, loop to make copies of the data (where available) associated with each forward transformation function, storing pointers to the copy in the output pointer arrays allocated above. */ if ( astOK ) { for ( ifun = 0; ifun < out->nfwd; ifun++ ) { if ( in->fwdfun && in->fwdfun[ ifun ] ) { out->fwdfun[ ifun ] = astStore( NULL, in->fwdfun[ ifun ], astSizeOf( in->fwdfun[ ifun ] ) ); } if ( in->fwdcode && in->fwdcode[ ifun ] ) { out->fwdcode[ ifun ] = astStore( NULL, in->fwdcode[ ifun ], astSizeOf( in->fwdcode[ ifun ] ) ); } if ( in->fwdcon && in->fwdcon[ ifun ] ) { out->fwdcon[ ifun ] = astStore( NULL, in->fwdcon[ ifun ], astSizeOf( in->fwdcon[ ifun ] ) ); } if ( !astOK ) break; } } /* Repeat this process for the inverse transformation functions. */ if ( astOK ) { for ( ifun = 0; ifun < out->ninv; ifun++ ) { if ( in->invfun && in->invfun[ ifun ] ) { out->invfun[ ifun ] = astStore( NULL, in->invfun[ ifun ], astSizeOf( in->invfun[ ifun ] ) ); } if ( in->invcode && in->invcode[ ifun ] ) { out->invcode[ ifun ] = astStore( NULL, in->invcode[ ifun ], astSizeOf( in->invcode[ ifun ] ) ); } if ( in->invcon && in->invcon[ ifun ] ) { out->invcon[ ifun ] = astStore( NULL, in->invcon[ ifun ], astSizeOf( in->invcon[ ifun ] ) ); } if ( !astOK ) break; } } /* If an error occurred, clean up by freeing all output memory allocated above. */ if ( !astOK ) { FREE_POINTER_ARRAY( out->fwdfun, out->nfwd ) FREE_POINTER_ARRAY( out->invfun, out->ninv ) FREE_POINTER_ARRAY( out->fwdcode, out->nfwd ) FREE_POINTER_ARRAY( out->invcode, out->ninv ) FREE_POINTER_ARRAY( out->fwdcon, out->nfwd ) FREE_POINTER_ARRAY( out->invcon, out->ninv ) } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for MathMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for MathMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstMathMap *this; /* Pointer to MathMap */ /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) obj; /* Free all memory allocated by the MathMap. */ FREE_POINTER_ARRAY( this->fwdfun, this->nfwd ) FREE_POINTER_ARRAY( this->invfun, this->ninv ) FREE_POINTER_ARRAY( this->fwdcode, this->nfwd ) FREE_POINTER_ARRAY( this->invcode, this->ninv ) FREE_POINTER_ARRAY( this->fwdcon, this->nfwd ) FREE_POINTER_ARRAY( this->invcon, this->ninv ) } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for MathMap 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 MathMap class to an output Channel. * Parameters: * this * Pointer to the MathMap 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: */ AstMathMap *this; /* Pointer to the MathMap structure */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment strings */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword strings */ int ifun; /* Loop counter for functions */ int invert; /* MathMap inverted? */ int ival; /* Integer attribute value */ int nin; /* True number of input coordinates */ int nout; /* True number of output coordinates */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the MathMap structure. */ this = (AstMathMap *) this_object; /* Determine if the MathMap is inverted and obtain the "true" number of input and output coordinates by un-doing the effects of any inversion. */ invert = astGetInvert( this ); nin = !invert ? astGetNin( this ) : astGetNout( this ); nout = !invert ? astGetNout( this ) : astGetNin( this ); /* Write out values representing the instance variables for the MathMap 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. */ /* Number of forward transformation functions. */ /* ------------------------------------------- */ /* We regard this value as set if it differs from the number of output coordinates for the MathMap. */ set = ( this->nfwd != nout ); astWriteInt( channel, "Nfwd", set, 0, this->nfwd, "Number of forward transformation functions" ); /* Forward transformation functions. */ /* --------------------------------- */ /* Loop to write out each forward transformation function, generating a suitable keyword and comment for each one. */ for ( ifun = 0; ifun < this->nfwd; ifun++ ) { (void) sprintf( key, "Fwd%d", ifun + 1 ); (void) sprintf( comment, "Forward function %d", ifun + 1 ); astWriteString( channel, key, 1, 1, this->fwdfun[ ifun ], comment ); } /* Number of inverse transformation functions. */ /* ------------------------------------------- */ /* We regard this value as set if it differs from the number of input coordinates for the MathMap. */ set = ( this->ninv != nin ); astWriteInt( channel, "Ninv", set, 0, this->ninv, "Number of inverse transformation functions" ); /* Inverse transformation functions. */ /* --------------------------------- */ /* Similarly, loop to write out each inverse transformation function. */ for ( ifun = 0; ifun < this->ninv; ifun++ ) { (void) sprintf( key, "Inv%d", ifun + 1 ); (void) sprintf( comment, "Inverse function %d", ifun + 1 ); astWriteString( channel, key, 1, 1, this->invfun[ ifun ], comment ); } /* SimpFI. */ /* ------- */ /* Write out the forward-inverse simplification flag. */ set = TestSimpFI( this, status ); ival = set ? GetSimpFI( this, status ) : astGetSimpFI( this ); astWriteInt( channel, "SimpFI", set, 0, ival, ival ? "Forward-inverse pairs may simplify" : "Forward-inverse pairs do not simplify" ); /* SimpIF. */ /* ------- */ /* Write out the inverse-forward simplification flag. */ set = TestSimpIF( this, status ); ival = set ? GetSimpIF( this, status ) : astGetSimpIF( this ); astWriteInt( channel, "SimpIF", set, 0, ival, ival ? "Inverse-forward pairs may simplify" : "Inverse-forward pairs do not simplify" ); /* Seed. */ /* ----- */ /* Write out any random number seed value which is set. Prefix this with a separate flag which indicates if the seed has been set. */ set = TestSeed( this, status ); ival = set ? GetSeed( this, status ) : astGetSeed( this ); astWriteInt( channel, "Seeded", set, 0, set, set? "Explicit random number seed set" : "No random number seed set" ); astWriteInt( channel, "Seed", set, 0, ival, set ? "Random number seed value" : "Default random number seed used" ); /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAMathMap and astCheckMathMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(MathMap,Mapping) astMAKE_CHECK(MathMap) AstMathMap *astMathMap_( int nin, int nout, int nfwd, const char *fwd[], int ninv, const char *inv[], const char *options, int *status, ...) { /* *+ * Name: * astMathMap * Purpose: * Create a MathMap. * Type: * Protected function. * Synopsis: * #include "mathmap.h" * AstMathMap *astMathMap( int nin, int nout, * int nfwd, const char *fwd[], * int ninv, const char *inv[], * const char *options, ..., int *status ) * Class Membership: * MathMap constructor. * Description: * This function creates a new MathMap and optionally initialises its * attributes. * Parameters: * nin * Number of input variables for the MathMap. * nout * Number of output variables for the MathMap. * nfwd * The number of forward transformation functions being supplied. * This must be at least equal to "nout". * fwd * Pointer to an array, with "nfwd" elements, of pointers to null * terminated strings which contain each of the forward transformation * functions. * ninv * The number of inverse transformation functions being supplied. * This must be at least equal to "nin". * inv * Pointer to an array, with "ninv" elements, of pointers to null * terminated strings which contain each of the inverse transformation * functions. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new MathMap. 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 MathMap. * 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 MathMap constructor which is * available via the protected interface to the MathMap class. A * public interface is provided by the astMathMapId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMathMap *new; /* Pointer to new MathMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the MathMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitMathMap( NULL, sizeof( AstMathMap ), !class_init, &class_vtab, "MathMap", nin, nout, nfwd, fwd, ninv, inv ); /* 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 MathMap'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 MathMap. */ return new; } AstMathMap *astMathMapId_( int nin, int nout, int nfwd, const char *fwd[], int ninv, const char *inv[], const char *options, ... ) { /* *++ * Name: c astMathMap f AST_MATHMAP * Purpose: * Create a MathMap. * Type: * Public function. * Synopsis: c #include "mathmap.h" c AstMathMap *astMathMap( int nin, int nout, c int nfwd, const char *fwd[], c int ninv, const char *inv[], c const char *options, ... ) f RESULT = AST_MATHMAP( NIN, NOUT, NFWD, FWD, NINV, INV, OPTIONS, STATUS ) * Class Membership: * MathMap constructor. * Description: * This function creates a new MathMap and optionally initialises its * attributes. * c A MathMap is a Mapping which allows you to specify a set of forward c and/or inverse transformation functions using arithmetic operations c and mathematical functions similar to those available in C. The c MathMap interprets these functions at run-time, whenever its forward c or inverse transformation is required. Because the functions are not c compiled in the normal sense (unlike an IntraMap), they may be used to c describe coordinate transformations in a transportable manner. A c MathMap therefore provides a flexible way of defining new types of c Mapping whose descriptions may be stored as part of a dataset and c interpreted by other programs. f A MathMap is a Mapping which allows you to specify a set of forward f and/or inverse transformation functions using arithmetic operations f and mathematical functions similar to those available in Fortran. The f MathMap interprets these functions at run-time, whenever its forward f or inverse transformation is required. Because the functions are not f compiled in the normal sense (unlike an IntraMap), they may be used to f describe coordinate transformations in a transportable manner. A f MathMap therefore provides a flexible way of defining new types of f Mapping whose descriptions may be stored as part of a dataset and f interpreted by other programs. * Parameters: c nin f NIN = INTEGER * Number of input variables for the MathMap. This determines the * value of its Nin attribute. c nout f NOUT = INTEGER * Number of output variables for the MathMap. This determines the * value of its Nout attribute. c nfwd f NFWD = INTEGER * The number of forward transformation functions being supplied. c This must be at least equal to "nout", but may be increased to f This must be at least equal to NOUT, but may be increased to * accommodate any additional expressions which define intermediate * variables for the forward transformation (see the "Calculating * Intermediate Values" section below). c fwd f FWD = CHARACTER * ( * )( NFWD ) c An array (with "nfwd" elements) of pointers to null terminated strings c which contain the expressions defining the forward transformation. f An array which contains the expressions defining the forward f transformation. * The syntax of these expressions is described below. c ninv f NINV = INTEGER * The number of inverse transformation functions being supplied. c This must be at least equal to "nin", but may be increased to f This must be at least equal to NIN, but may be increased to * accommodate any additional expressions which define intermediate * variables for the inverse transformation (see the "Calculating * Intermediate Values" section below). c inv f INV = CHARACTER * ( * )( NINV ) c An array (with "ninv" elements) of pointers to null terminated strings c which contain the expressions defining the inverse transformation. f An array which contains the expressions defining the inverse f transformation. * The syntax of these expressions is described below. 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 MathMap. 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 MathMap. 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 astMathMap() f AST_MATHMAP = INTEGER * A pointer to the new MathMap. * Defining Transformation Functions: c A MathMap's transformation functions are supplied as a set of c expressions in an array of character strings. Normally you would c supply the same number of expressions for the forward transformation, c via the "fwd" parameter, as there are output variables (given by the c MathMap's Nout attribute). For instance, if Nout is 2 you might use: c - "r = sqrt( x * x + y * y )" c - "theta = atan2( y, x )" c c which defines a transformation from Cartesian to polar c coordinates. Here, the variables that appear on the left of each c expression ("r" and "theta") provide names for the output variables c and those that appear on the right ("x" and "y") are references to c input variables. f A MathMap's transformation functions are supplied as a set of f expressions in an array of character strings. Normally you would f supply the same number of expressions for the forward transformation, f via the FWD argument, as there are output variables (given by the f MathMap's Nout attribute). For instance, if Nout is 2 you might use: f - 'R = SQRT( X * X + Y * Y )' f - 'THETA = ATAN2( Y, X )' f f which defines a transformation from Cartesian to polar f coordinates. Here, the variables that appear on the left of each f expression (R and THETA) provide names for the output variables and f those that appear on the right (X and Y) are references to input f variables. * c To complement this, you must also supply expressions for the inverse c transformation via the "inv" parameter. In this case, the number of c expressions given would normally match the number of MathMap input c coordinates (given by the Nin attribute). If Nin is 2, you might use: c - "x = r * cos( theta )" c - "y = r * sin( theta )" c c which expresses the transformation from polar to Cartesian c coordinates. Note that here the input variables ("x" and "y") are c named on the left of each expression, and the output variables ("r" c and "theta") are referenced on the right. f To complement this, you must also supply expressions for the inverse f transformation via the INV argument. In this case, the number of f expressions given would normally match the number of MathMap input f coordinates (given by the Nin attribute). If Nin is 2, you might use: f - 'X = R * COS( THETA )' f - 'Y = R * SIN( THETA )' f f which expresses the transformation from polar to Cartesian f coordinates. Note that here the input variables (X and Y) are named on f the left of each expression, and the output variables (R and THETA) f are referenced on the right. * * Normally, you cannot refer to a variable on the right of an expression * unless it is named on the left of an expression in the complementary * set of functions. Therefore both sets of functions (forward and * inverse) must be formulated using the same consistent set of variable * names. This means that if you wish to leave one of the transformations * undefined, you must supply dummy expressions which simply name each of * the output (or input) variables. For example, you might use: c - "x" c - "y" f - 'X' f - 'Y' * * for the inverse transformation above, which serves to name the input * variables but without defining an inverse transformation. * Calculating Intermediate Values: c It is sometimes useful to calculate intermediate values and then to c use these in the final expressions for the output (or input) c variables. This may be done by supplying additional expressions for c the forward (or inverse) transformation functions. For instance, the c following array of five expressions describes 2-dimensional pin-cushion c distortion: c - "r = sqrt( xin * xin + yin * yin )" c - "rout = r * ( 1 + 0.1 * r * r )" c - "theta = atan2( yin, xin )" c - "xout = rout * cos( theta )" c - "yout = rout * sin( theta )" f It is sometimes useful to calculate intermediate values and then to f use these in the final expressions for the output (or input) f variables. This may be done by supplying additional expressions for f the forward (or inverse) transformation functions. For instance, the f following array of five expressions describes 2-dimensional pin-cushion f distortion: f - 'R = SQRT( XIN * XIN + YIN * YIN )' f - 'ROUT = R * ( 1 + 0.1 * R * R )' f - 'THETA = ATAN2( YIN, XIN )', f - 'XOUT = ROUT * COS( THETA )' f - 'YOUT = ROUT * SIN( THETA )' * c Here, we first calculate three intermediate results ("r", "rout" c and "theta") and then use these to calculate the final results ("xout" c and "yout"). The MathMap knows that only the final two results c constitute values for the output variables because its Nout attribute c is set to 2. You may define as many intermediate variables in this c way as you choose. Having defined a variable, you may then refer to it c on the right of any subsequent expressions. f Here, we first calculate three intermediate results (R, ROUT f and THETA) and then use these to calculate the final results (XOUT f and YOUT). The MathMap knows that only the final two results f constitute values for the output variables because its Nout attribute f is set to 2. You may define as many intermediate variables in this f way as you choose. Having defined a variable, you may then refer to it f on the right of any subsequent expressions. * c Note that when defining the inverse transformation you may only refer c to the output variables "xout" and "yout". The intermediate variables c "r", "rout" and "theta" (above) are private to the forward c transformation and may not be referenced by the inverse c transformation. The inverse transformation may, however, define its c own private intermediate variables. f Note that when defining the inverse transformation you may only refer f to the output variables XOUT and YOUT. The intermediate variables R, f ROUT and THETA (above) are private to the forward transformation and f may not be referenced by the inverse transformation. The inverse f transformation may, however, define its own private intermediate f variables. * Expression Syntax: c The expressions given for the forward and inverse transformations c closely follow the syntax of the C programming language (with some c extensions for compatibility with Fortran). They may contain c references to variables and literal constants, together with c arithmetic, boolean, relational and bitwise operators, and function c invocations. A set of symbolic constants is also available. Each of c these is described in detail below. Parentheses may be used to c over-ride the normal order of evaluation. There is no built-in limit c to the length of expressions and they are insensitive to case or the c presence of additional white space. f The expressions given for the forward and inverse transformations f closely follow the syntax of Fortran (with some extensions for f compatibility with the C language). They may contain references to f variables and literal constants, together with arithmetic, logical, f relational and bitwise operators, and function invocations. A set of f symbolic constants is also available. Each of these is described in f detail below. Parentheses may be used to over-ride the normal order of f evaluation. There is no built-in limit to the length of expressions f and they are insensitive to case or the presence of additional white f space. * Variables: * Variable names must begin with an alphabetic character and may contain * only alphabetic characters, digits, and the underscore character * "_". There is no built-in limit to the length of variable names. * Literal Constants: c Literal constants, such as "0", "1", "0.007" or "2.505e-16" may appear c in expressions, with the decimal point and exponent being optional (a c "D" may also be used as an exponent character for compatibility with c Fortran). A unary minus "-" may be used as a prefix. f Literal constants, such as "0", "1", "0.007" or "2.505E-16" may appear f in expressions, with the decimal point and exponent being optional (a f "D" may also be used as an exponent character). A unary minus "-" may f be used as a prefix. * Arithmetic Precision: * All arithmetic is floating point, performed in double precision. * Propagation of Missing Data: * Unless indicated otherwise, if any argument of a function or operator * has the value AST__BAD (indicating missing data), then the result of * that function or operation is also AST__BAD, so that such values are * propagated automatically through all operations performed by MathMap * transformations. The special value AST__BAD can be represented in * expressions by the symbolic constant "". * * A result (i.e. equal to AST__BAD) is also produced in response * to any numerical error (such as division by zero or numerical * overflow), or if an invalid argument value is provided to a function * or operator. * Arithmetic Operators: * The following arithmetic operators are available: c - x1 + x2: Sum of "x1" and "x2". f - X1 + X2: Sum of X1 and X2. c - x1 - x2: Difference of "x1" and "x2". f - X1 - X2: Difference of X1 and X2. c - x1 * x2: Product of "x1" and "x1". f - X1 * X2: Product of X1 and X2. c - x1 / x2: Ratio of "x1" and "x2". f - X1 / X2: Ratio of X1 and X2. c - x1 ** x2: "x1" raised to the power of "x2". f - X1 ** X2: X1 raised to the power of X2. c - + x: Unary plus, has no effect on its argument. f - + X: Unary plus, has no effect on its argument. c - - x: Unary minus, negates its argument. f - - X: Unary minus, negates its argument. c Boolean Operators: f Logical Operators: c Boolean values are represented using zero to indicate false and c non-zero to indicate true. In addition, the value AST__BAD is taken to c mean "unknown". The values returned by boolean operators may therefore c be 0, 1 or AST__BAD. Where appropriate, "tri-state" logic is c implemented. For example, "a||b" may evaluate to 1 if "a" is non-zero, c even if "b" has the value AST__BAD. This is because the result of the c operation would not be affected by the value of "b", so long as "a" is c non-zero. f Logical values are represented using zero to indicate .FALSE. and f non-zero to indicate .TRUE.. In addition, the value AST__BAD is taken to f mean "unknown". The values returned by logical operators may therefore f be 0, 1 or AST__BAD. Where appropriate, "tri-state" logic is f implemented. For example, A.OR.B may evaluate to 1 if A is non-zero, f even if B has the value AST__BAD. This is because the result of the f operation would not be affected by the value of B, so long as A is f non-zero. * c The following boolean operators are available: f The following logical operators are available: c - x1 && x2: Boolean AND between "x1" and "x2", returning 1 if both "x1" c and "x2" are non-zero, and 0 otherwise. This operator implements c tri-state logic. (The synonym ".and." is also provided for compatibility c with Fortran.) f - X1 .AND. X2: Logical AND between X1 and X2, returning 1 if both X1 f and X2 are non-zero, and 0 otherwise. This operator implements f tri-state logic. (The synonym "&&" is also provided for compatibility f with C.) c - x1 || x2: Boolean OR between "x1" and "x2", returning 1 if either "x1" c or "x2" are non-zero, and 0 otherwise. This operator implements c tri-state logic. (The synonym ".or." is also provided for compatibility c with Fortran.) f - X1 .OR. X2: Logical OR between X1 and X2, returning 1 if either X1 f or X2 are non-zero, and 0 otherwise. This operator implements f tri-state logic. (The synonym "||" is also provided for compatibility f with C.) c - x1 ^^ x2: Boolean exclusive OR (XOR) between "x1" and "x2", returning c 1 if exactly one of "x1" and "x2" is non-zero, and 0 otherwise. Tri-state c logic is not used with this operator. (The synonyms ".neqv." and ".xor." c are also provided for compatibility with Fortran, although the second c of these is not standard.) f - X1 .NEQV. X2: Logical exclusive OR (XOR) between X1 and X2, f returning 1 if exactly one of X1 and X2 is non-zero, and 0 f otherwise. Tri-state logic is not used with this operator. (The f synonym ".XOR." is also provided, although this is not standard f Fortran. In addition, the C-like synonym "^^" may be used, although f this is also not standard.) c - x1 .eqv. x2: This is provided only for compatibility with Fortran c and tests whether the boolean states of "x1" and "x2" (i.e. true/false) c are equal. It is the negative of the exclusive OR (XOR) function. c Tri-state logic is not used with this operator. f - X1 .EQV. X2: Tests whether the logical states of X1 and X2 f (i.e. .TRUE./.FALSE.) are equal. It is the negative of the exclusive OR f (XOR) function. Tri-state logic is not used with this operator. c - ! x: Boolean unary NOT operation, returning 1 if "x" is zero, and c 0 otherwise. (The synonym ".not." is also provided for compatibility c with Fortran.) f - .NOT. X: Logical unary NOT operation, returning 1 if X is zero, and f 0 otherwise. (The synonym "!" is also provided for compatibility with f C.) * Relational Operators: c Relational operators return the boolean result (0 or 1) of comparing c the values of two floating point values for equality or inequality. The c value AST__BAD may also be returned if either argument is . f Relational operators return the logical result (0 or 1) of comparing f the values of two floating point values for equality or inequality. The f value AST__BAD may also be returned if either argument is . * * The following relational operators are available: c - x1 == x2: Tests whether "x1" equals "x1". (The synonym ".eq." is c also provided for compatibility with Fortran.) f - X1 .EQ. X2: Tests whether X1 equals X2. (The synonym "==" is also f provided for compatibility with C.) c - x1 != x2: Tests whether "x1" is unequal to "x2". (The synonym ".ne." c is also provided for compatibility with Fortran.) f - X1 .NE. X2: Tests whether X1 is unequal to X2. (The synonym "!=" is f also provided for compatibility with C.) c - x1 > x2: Tests whether "x1" is greater than "x2". (The synonym c ".gt." is also provided for compatibility with Fortran.) f - X1 .GT. X2: Tests whether X1 is greater than X2. (The synonym ">" is f also provided for compatibility with C.) c - x1 >= x2: Tests whether "x1" is greater than or equal to "x2". (The c synonym ".ge." is also provided for compatibility with Fortran.) f - X1 .GE. X2: Tests whether X1 is greater than or equal to X2. (The f synonym ">=" is also provided for compatibility with C.) c - x1 < x2: Tests whether "x1" is less than "x2". (The synonym ".lt." c is also provided for compatibility with Fortran.) f - X1 .LT. X2: Tests whether X1 is less than X2. (The synonym "<" is also f provided for compatibility with C.) c - x1 <= x2: Tests whether "x1" is less than or equal to "x2". (The c synonym ".le." is also provided for compatibility with Fortran.) f - X1 .LE. X2: Tests whether X1 is less than or equal to X2. (The synonym f "<=" is also provided for compatibility with C.) * c Note that relational operators cannot usefully be used to compare c values with the value (representing missing data), because the c result is always . The isbad() function should be used instead. f Note that relational operators cannot usefully be used to compare f values with the value (representing missing data), because the f result is always . The ISBAD() function should be used instead. f f Note, also, that because logical operators can operate on floating f point values, care must be taken to use parentheses in some cases f where they would not normally be required in Fortran. For example, f the expresssion: f - .NOT. A .EQ. B f f must be written: f - .NOT. ( A .EQ. B ) f f to prevent the .NOT. operator from associating with the variable A. * Bitwise Operators: c The bitwise operators provided by C are often useful when operating on c raw data (e.g. from instruments), so they are also provided for use in c MathMap expressions. In this case, however, the values on which they c operate are floating point values rather than pure integers. In order c to produce results which match the pure integer case, the operands are c regarded as fixed point binary numbers (i.e. with the binary c equivalent of a decimal point) with negative numbers represented using c twos-complement notation. For integer values, the resulting bit c pattern corresponds to that of the equivalent signed integer (digits c to the right of the point being zero). Operations on the bits c representing the fractional part are also possible, however. f Bitwise operators are often useful when operating on raw data f (e.g. from instruments), so they are provided for use in MathMap f expressions. In this case, however, the values on which they operate f are floating point values rather than the more usual pure integers. In f order to produce results which match the pure integer case, the f operands are regarded as fixed point binary numbers (i.e. with the f binary equivalent of a decimal point) with negative numbers f represented using twos-complement notation. For integer values, the f resulting bit pattern corresponds to that of the equivalent signed f integer (digits to the right of the point being zero). Operations on f the bits representing the fractional part are also possible, however. * * The following bitwise operators are available: c - x1 >> x2: Rightward bit shift. The integer value of "x2" is taken c (rounding towards zero) and the bits representing "x1" are then c shifted this number of places to the right (or to the left if the c number of places is negative). This is equivalent to dividing "x1" by c the corresponding power of 2. f - X1 >> X2: Rightward bit shift. The integer value of X2 is taken f (rounding towards zero) and the bits representing X1 are then f shifted this number of places to the right (or to the left if the f number of places is negative). This is equivalent to dividing X1 by f the corresponding power of 2. c - x1 << x2: Leftward bit shift. The integer value of "x2" is taken c (rounding towards zero), and the bits representing "x1" are then c shifted this number of places to the left (or to the right if the c number of places is negative). This is equivalent to multiplying "x1" c by the corresponding power of 2. f - X1 << X2: Leftward bit shift. The integer value of X2 is taken f (rounding towards zero), and the bits representing X1 are then f shifted this number of places to the left (or to the right if the f number of places is negative). This is equivalent to multiplying X1 f by the corresponding power of 2. c - x1 & x2: Bitwise AND between the bits of "x1" and those of "x2" c (equivalent to a boolean AND applied at each bit position in turn). f - X1 & X2: Bitwise AND between the bits of X1 and those of X2 f (equivalent to a logical AND applied at each bit position in turn). c - x1 | x2: Bitwise OR between the bits of "x1" and those of "x2" c (equivalent to a boolean OR applied at each bit position in turn). f - X1 | X2: Bitwise OR between the bits of X1 and those of X2 f (equivalent to a logical OR applied at each bit position in turn). c - x1 ^ x2: Bitwise exclusive OR (XOR) between the bits of "x1" and c those of "x2" (equivalent to a boolean XOR applied at each bit c position in turn). f - X1 ^ X2: Bitwise exclusive OR (XOR) between the bits of X1 and f those of X2 (equivalent to a logical XOR applied at each bit f position in turn). * c Note that no bit inversion operator ("~" in C) is provided. This is c because inverting the bits of a twos-complement fixed point binary c number is equivalent to simply negating it. This differs from the c pure integer case because bits to the right of the binary point are c also inverted. To invert only those bits to the left of the binary c point, use a bitwise exclusive OR with the value -1 (i.e. "x^-1"). f Note that no bit inversion operator is provided. This is f because inverting the bits of a twos-complement fixed point binary f number is equivalent to simply negating it. This differs from the f pure integer case because bits to the right of the binary point are f also inverted. To invert only those bits to the left of the binary f point, use a bitwise exclusive OR with the value -1 (i.e. X^-1). * Functions: * The following functions are available: c - abs(x): Absolute value of "x" (sign removal), same as fabs(x). f - ABS(X): Absolute value of X (sign removal), same as FABS(X). c - acos(x): Inverse cosine of "x", in radians. f - ACOS(X): Inverse cosine of X, in radians. c - acosd(x): Inverse cosine of "x", in degrees. f - ACOSD(X): Inverse cosine of X, in degrees. c - acosh(x): Inverse hyperbolic cosine of "x". f - ACOSH(X): Inverse hyperbolic cosine of X. c - acoth(x): Inverse hyperbolic cotangent of "x". f - ACOTH(X): Inverse hyperbolic cotangent of X. c - acsch(x): Inverse hyperbolic cosecant of "x". f - ACSCH(X): Inverse hyperbolic cosecant of X. c - aint(x): Integer part of "x" (round towards zero), same as int(x). f - AINT(X): Integer part of X (round towards zero), same as INT(X). c - asech(x): Inverse hyperbolic secant of "x". f - ASECH(X): Inverse hyperbolic secant of X. c - asin(x): Inverse sine of "x", in radians. f - ASIN(X): Inverse sine of X, in radians. c - asind(x): Inverse sine of "x", in degrees. f - ASIND(X): Inverse sine of X, in degrees. c - asinh(x): Inverse hyperbolic sine of "x". f - ASINH(X): Inverse hyperbolic sine of X. c - atan(x): Inverse tangent of "x", in radians. f - ATAN(X): Inverse tangent of X, in radians. c - atand(x): Inverse tangent of "x", in degrees. f - ATAND(X): Inverse tangent of X, in degrees. c - atanh(x): Inverse hyperbolic tangent of "x". f - ATANH(X): Inverse hyperbolic tangent of X. c - atan2(x1, x2): Inverse tangent of "x1/x2", in radians. f - ATAN2(X1, X2): Inverse tangent of X1/X2, in radians. c - atan2d(x1, x2): Inverse tangent of "x1/x2", in degrees. f - ATAN2D(X1, X2): Inverse tangent of X1/X2, in degrees. c - ceil(x): Smallest integer value not less then "x" (round towards c plus infinity). f - CEIL(X): Smallest integer value not less then X (round towards f plus infinity). c - cos(x): Cosine of "x" in radians. f - COS(X): Cosine of X in radians. c - cosd(x): Cosine of "x" in degrees. f - COSD(X): Cosine of X in degrees. c - cosh(x): Hyperbolic cosine of "x". f - COSH(X): Hyperbolic cosine of X. c - coth(x): Hyperbolic cotangent of "x". f - COTH(X): Hyperbolic cotangent of X. c - csch(x): Hyperbolic cosecant of "x". f - CSCH(X): Hyperbolic cosecant of X. c - dim(x1, x2): Returns "x1-x2" if "x1" is greater than "x2", otherwise 0. f - DIM(X1, X2): Returns X1-X2 if X1 is greater than X2, otherwise 0. c - exp(x): Exponential function of "x". f - EXP(X): Exponential function of X. c - fabs(x): Absolute value of "x" (sign removal), same as abs(x). f - FABS(X): Absolute value of X (sign removal), same as ABS(X). c - floor(x): Largest integer not greater than "x" (round towards c minus infinity). f - FLOOR(X): Largest integer not greater than X (round towards f minus infinity). c - fmod(x1, x2): Remainder when "x1" is divided by "x2", same as c mod(x1, x2). f - FMOD(X1, X2): Remainder when X1 is divided by X2, same as f MOD(X1, X2). c - gauss(x1, x2): Random sample from a Gaussian distribution with mean c "x1" and standard deviation "x2". f - GAUSS(X1, X2): Random sample from a Gaussian distribution with mean f X1 and standard deviation X2. c - int(x): Integer part of "x" (round towards zero), same as aint(x). f - INT(X): Integer part of X (round towards zero), same as AINT(X). c - isbad(x): Returns 1 if "x" has the value (AST__BAD), otherwise 0. f - ISBAD(X): Returns 1 if X has the value (AST__BAD), otherwise 0. c - log(x): Natural logarithm of "x". f - LOG(X): Natural logarithm of X. c - log10(x): Logarithm of "x" to base 10. f - LOG10(X): Logarithm of X to base 10. c - max(x1, x2, ...): Maximum of two or more values. f - MAX(X1, X2, ...): Maximum of two or more values. c - min(x1, x2, ...): Minimum of two or more values. f - MIN(X1, X2, ...): Minimum of two or more values. c - mod(x1, x2): Remainder when "x1" is divided by "x2", same as c fmod(x1, x2). f - MOD(X1, X2): Remainder when X1 is divided by X2, same as f FMOD(X1, X2). c - nint(x): Nearest integer to "x" (round to nearest). f - NINT(X): Nearest integer to X (round to nearest). c - poisson(x): Random integer-valued sample from a Poisson c distribution with mean "x". f - POISSON(X): Random integer-valued sample from a Poisson f distribution with mean X. c - pow(x1, x2): "x1" raised to the power of "x2". f - POW(X1, X2): X1 raised to the power of X2. c - qif(x1, x2, x3): Returns "x2" if "x1" is true, and "x3" otherwise. f - QIF(x1, x2, x3): Returns X2 if X1 is true, and X3 otherwise. c - rand(x1, x2): Random sample from a uniform distribution in the c range "x1" to "x2" inclusive. f - RAND(X1, X2): Random sample from a uniform distribution in the f range X1 to X2 inclusive. c - sech(x): Hyperbolic secant of "x". f - SECH(X): Hyperbolic secant of X. c - sign(x1, x2): Absolute value of "x1" with the sign of "x2" c (transfer of sign). f - SIGN(X1, X2): Absolute value of X1 with the sign of X2 f (transfer of sign). c - sin(x): Sine of "x" in radians. f - SIN(X): Sine of X in radians. c - sinc(x): Sinc function of "x" [= "sin(x)/x"]. f - SINC(X): Sinc function of X [= SIN(X)/X]. c - sind(x): Sine of "x" in degrees. f - SIND(X): Sine of X in degrees. c - sinh(x): Hyperbolic sine of "x". f - SINH(X): Hyperbolic sine of X. c - sqr(x): Square of "x" (= "x*x"). f - SQR(X): Square of X (= X*X). c - sqrt(x): Square root of "x". f - SQRT(X): Square root of X. c - tan(x): Tangent of "x" in radians. f - TAN(X): Tangent of X in radians. c - tand(x): Tangent of "x" in degrees. f - TAND(X): Tangent of X in degrees. c - tanh(x): Hyperbolic tangent of "x". f - TANH(X): Hyperbolic tangent of X. * Symbolic Constants: * The following symbolic constants are available (the enclosing "<>" * brackets must be included): c - : The "bad" value (AST__BAD) used to flag missing data. Note c that you cannot usefully compare values with this constant because the c result is always . The isbad() function should be used instead. f - : The "bad" value (AST__BAD) used to flag missing data. Note f that you cannot usefully compare values with this constant because the f result is always . The ISBAD() function should be used instead. c - : Number of decimal digits of precision available in a c floating point (double) value. f - : Number of decimal digits of precision available in a f floating point (double precision) value. * - : Base of natural logarithms. * - : Smallest positive number such that 1.0+ is * distinguishable from unity. c - : The number of base digits stored in the c mantissa of a floating point (double) value. f - : The number of base digits stored in the f mantissa of a floating point (double precision) value. c - : Maximum representable floating point (double) value. f - : Maximum representable floating point (double precision) value. c - : Maximum integer such that 10 raised to that power c can be represented as a floating point (double) value. f - : Maximum integer such that 10 raised to that power f can be represented as a floating point (double precision) value. c - : Maximum integer such that raised to that c power minus 1 can be represented as a floating point (double) value. f - : Maximum integer such that raised to that f power minus 1 can be represented as a floating point (double precision) f value. c - : Smallest positive number which can be represented as a c normalised floating point (double) value. f - : Smallest positive number which can be represented as a f normalised floating point (double precision) value. c - : Minimum negative integer such that 10 raised to that c power can be represented as a normalised floating point (double) value. f - : Minimum negative integer such that 10 raised to that f power can be represented as a normalised floating point (double f precision) value. c - : Minimum negative integer such that raised to c that power minus 1 can be represented as a normalised floating point c (double) value. f - : Minimum negative integer such that raised to f that power minus 1 can be represented as a normalised floating point f (double precision) value. * - : Ratio of the circumference of a circle to its diameter. c - : The radix (number base) used to represent the mantissa of c floating point (double) values. f - : The radix (number base) used to represent the mantissa of f floating point (double precision) values. * - : The mode used for rounding floating point results after * addition. Possible values include: -1 (indeterminate), 0 (toward * zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus * infinity). Other values indicate machine-dependent behaviour. * Evaluation Precedence and Associativity: * Items appearing in expressions are evaluated in the following order * (highest precedence first): * - Constants and variables * - Function arguments and parenthesised expressions * - Function invocations * - Unary + - ! .not. * - ** * - * / * - + - * - << >> * - < .lt. <= .le. > .gt. >= .ge. * - == .eq. != .ne. * - & * - ^ * - | * - && .and. * - ^^ * - || .or * - .eqv. .neqv. .xor. * * All operators associate from left-to-right, except for unary +, * unary -, !, .not. and ** which associate from right-to-left. * Notes: * - The sequence of numbers produced by the random number functions * available within a MathMap is normally unpredictable and different for * each MathMap. However, this behaviour may be controlled by means of * the MathMap's Seed attribute. c - Normally, compound Mappings (CmpMaps) which involve MathMaps will c not be subject to simplification (e.g. using astSimplify) because AST c cannot know how different MathMaps will interact. However, in the c special case where a MathMap occurs in series with its own inverse, c then simplification may be possible. Whether simplification does, in c fact, occur under these circumstances is controlled by the MathMap's c SimpFI and SimpIF attributes. f - Normally, compound Mappings (CmpMaps) which involve MathMaps will f not be subject to simplification (e.g. using AST_SIMPLIFY) because AST f cannot know how different MathMaps will interact. However, in the f special case where a MathMap occurs in series with its own inverse, f then simplification may be possible. Whether simplification does, in f fact, occur under these circumstances is controlled by the MathMap's f SimpFI and SimpIF attributes. * - 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 astMathMap constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astMathMap_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astMathMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstMathMap *new; /* Pointer to new MathMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the MathMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitMathMap( NULL, sizeof( AstMathMap ), !class_init, &class_vtab, "MathMap", nin, nout, nfwd, fwd, ninv, inv ); /* 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 MathMap'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 MathMap. */ return astMakeId( new ); } AstMathMap *astInitMathMap_( void *mem, size_t size, int init, AstMathMapVtab *vtab, const char *name, int nin, int nout, int nfwd, const char *fwd[], int ninv, const char *inv[], int *status ) { /* *+ * Name: * astInitMathMap * Purpose: * Initialise a MathMap. * Type: * Protected function. * Synopsis: * #include "mathmap.h" * AstMathMap *astInitMathMap_( void *mem, size_t size, int init, * AstMathMapVtab *vtab, const char *name, * int nin, int nout, * int nfwd, const char *fwd[], * int ninv, const char *inv[] ) * Class Membership: * MathMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new MathMap object. It allocates memory (if necessary) to accommodate * the MathMap plus any additional data associated with the derived class. * It then initialises a MathMap 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 MathMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the MathMap is to be initialised. * This must be of sufficient size to accommodate the MathMap data * (sizeof(MathMap)) 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 MathMap (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 MathMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the MathMap'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 MathMap. * 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 Object * astClass function). * nin * Number of input variables for the MathMap. * nout * Number of output variables for the MathMap. * nfwd * The number of forward transformation functions being supplied. * This must be at least equal to "nout". * fwd * Pointer to an array, with "nfwd" elements, of pointers to null * terminated strings which contain each of the forward transformation * functions. * ninv * The number of inverse transformation functions being supplied. * This must be at least equal to "nin". * inv * Pointer to an array, with "ninv" elements, of pointers to null * terminated strings which contain each of the inverse transformation * functions. * Returned Value: * A pointer to the new MathMap. * Notes: * - This function does not attempt to ensure that the forward and inverse * transformations performed by the resulting MathMap are consistent in any * way. * - This function makes a copy of the contents of the strings supplied. * - 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: */ AstMathMap *new; /* Pointer to new MathMap */ char **fwdfun; /* Array of cleaned forward functions */ char **invfun; /* Array of cleaned inverse functions */ double **fwdcon; /* Constants for forward functions */ double **invcon; /* Constants for inverse functions */ int **fwdcode; /* Code for forward functions */ int **invcode; /* Code for inverse functions */ int fwdstack; /* Stack size for forward functions */ int invstack; /* Stack size for inverse functions */ /* Initialise. */ new = NULL; /* Check the global status. */ if ( !astOK ) return new; /* If necessary, initialise the virtual function table. */ if ( init ) astInitMathMapVtab( vtab, name ); /* Check the numbers of input and output variables for validity, reporting an error if necessary. */ if ( nin < 1 ) { astError( AST__BADNI, "astInitMathMap(%s): Bad number of input coordinates (%d).", status, name, nin ); astError( AST__BADNI, "This number should be one or more." , status); } else if ( nout < 1 ) { astError( AST__BADNO, "astInitMathMap(%s): Bad number of output coordinates (%d).", status, name, nout ); astError( AST__BADNI, "This number should be one or more." , status); /* Check that sufficient number of forward and inverse transformation functions have been supplied and report an error if necessary. */ } else if ( nfwd < nout ) { astError( AST__INNTF, "astInitMathMap(%s): Too few forward transformation functions " "given (%d).", status, name, nfwd ); astError( astStatus, "At least %d forward transformation functions must be " "supplied. ", status, nout ); } else if ( ninv < nin ) { astError( AST__INNTF, "astInitMathMap(%s): Too few inverse transformation functions " "given (%d).", status, name, ninv ); astError( astStatus, "At least %d inverse transformation functions must be " "supplied. ", status, nin ); /* Of OK, clean the forward and inverse functions provided. This makes a lower-case copy with white space removed. */ } else { CleanFunctions( nfwd, fwd, &fwdfun, status ); CleanFunctions( ninv, inv, &invfun, status ); /* Compile the cleaned functions. From the returned pointers (if successful), we can now tell which transformations (forward and/or inverse) are defined. */ CompileMapping( "astInitMathMap", name, nin, nout, nfwd, (const char **) fwdfun, ninv, (const char **) invfun, &fwdcode, &invcode, &fwdcon, &invcon, &fwdstack, &invstack, status ); /* Initialise a Mapping structure (the parent class) as the first component within the MathMap structure, allocating memory if necessary. Specify that the Mapping should be defined in the required directions. */ new = (AstMathMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, ( fwdcode != NULL ), ( invcode != NULL ) ); /* If an error has occurred, free all the memory which may have been allocated by the cleaning and compilation steps above. */ if ( !astOK ) { FREE_POINTER_ARRAY( fwdfun, nfwd ) FREE_POINTER_ARRAY( invfun, ninv ) FREE_POINTER_ARRAY( fwdcode, nfwd ) FREE_POINTER_ARRAY( invcode, ninv ) FREE_POINTER_ARRAY( fwdcon, nfwd ) FREE_POINTER_ARRAY( invcon, ninv ) } /* Initialise the MathMap data. */ /* ---------------------------- */ /* Store pointers to the compiled function information, together with other MathMap data. */ if ( new ) { new->fwdfun = fwdfun; new->invfun = invfun; new->fwdcode = fwdcode; new->invcode = invcode; new->fwdcon = fwdcon; new->invcon = invcon; new->fwdstack = fwdstack; new->invstack = invstack; new->nfwd = nfwd; new->ninv = ninv; new->simp_fi = -INT_MAX; new->simp_if = -INT_MAX; /* Initialise the random number generator context associated with the MathMap, using an unpredictable default seed value. */ new->rcontext.active = 0; new->rcontext.random_int = 0; new->rcontext.seed_set = 0; new->rcontext.seed = DefaultSeed( &new->rcontext, status ); /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } } /* Return a pointer to the new object. */ return new; } AstMathMap *astLoadMathMap_( void *mem, size_t size, AstMathMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadMathMap * Purpose: * Load a MathMap. * Type: * Protected function. * Synopsis: * #include "mathmap.h" * AstMathMap *astLoadMathMap( void *mem, size_t size, * AstMathMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * MathMap loader. * Description: * This function is provided to load a new MathMap 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 * MathMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a MathMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the MathMap is to be * loaded. This must be of sufficient size to accommodate the * MathMap data (sizeof(MathMap)) 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 MathMap (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 MathMap 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(AstMathMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new MathMap. If this is NULL, a pointer * to the (static) virtual function table for the MathMap 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 "MathMap" is used instead. * Returned Value: * A pointer to the new MathMap. * 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: */ AstMathMap *new; /* Pointer to the new MathMap */ char key[ KEY_LEN + 1 ]; /* Buffer for keyword strings */ int ifun; /* Loop counter for functions */ int invert; /* Invert attribute value */ int nin; /* True number of input coordinates */ int nout; /* True number of output coordinates */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this MathMap. In this case the MathMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstMathMap ); vtab = &class_vtab; name = "MathMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitMathMapVtab( 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 MathMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "MathMap" ); /* Determine if the MathMap is inverted and obtain the "true" number of input and output coordinates by un-doing the effects of any inversion. */ invert = astGetInvert( new ); nin = invert ? astGetNout( new ) : astGetNin( new ); nout = invert ? astGetNin( new ) : astGetNout( new ); /* 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. */ /* Numbers of transformation functions. */ /* ------------------------------------ */ /* Read the numbers of forward and inverse transformation functions, supplying appropriate defaults. */ new->nfwd = astReadInt( channel, "nfwd", nout ); new->ninv = astReadInt( channel, "ninv", nin ); if ( astOK ) { /* Allocate memory for the MathMap's transformation function arrays. */ MALLOC_POINTER_ARRAY( new->fwdfun, char *, new->nfwd ) MALLOC_POINTER_ARRAY( new->invfun, char *, new->ninv ) if ( astOK ) { /* Forward transformation functions. */ /* --------------------------------- */ /* Create a keyword for each forward transformation function and read the function's value as a string. */ for ( ifun = 0; ifun < new->nfwd; ifun++ ) { (void) sprintf( key, "fwd%d", ifun + 1 ); new->fwdfun[ ifun ] = astReadString( channel, key, "" ); } /* Inverse transformation functions. */ /* --------------------------------- */ /* Repeat this process for the inverse transformation functions. */ for ( ifun = 0; ifun < new->ninv; ifun++ ) { (void) sprintf( key, "inv%d", ifun + 1 ); new->invfun[ ifun ] = astReadString( channel, key, "" ); } /* Forward-inverse simplification flag. */ /* ------------------------------------ */ new->simp_fi = astReadInt( channel, "simpfi", -INT_MAX ); if ( TestSimpFI( new, status ) ) SetSimpFI( new, new->simp_fi, status ); /* Inverse-forward simplification flag. */ /* ------------------------------------ */ new->simp_if = astReadInt( channel, "simpif", -INT_MAX ); if ( TestSimpIF( new, status ) ) SetSimpIF( new, new->simp_if, status ); /* Random number context. */ /* ---------------------- */ /* Initialise the random number generator context. */ new->rcontext.active = 0; new->rcontext.random_int = 0; /* Read the flag that determines if the Seed value is set, and the Seed value itself. */ new->rcontext.seed_set = astReadInt( channel, "seeded", 0 ); if ( TestSeed( new, status ) ) { new->rcontext.seed = astReadInt( channel, "seed", 0 ); SetSeed( new, new->rcontext.seed, status ); /* Supply an unpredictable default Seed value if necessary. */ } else { new->rcontext.seed = DefaultSeed( &new->rcontext, status ); } /* Compile the MathMap's transformation functions. */ CompileMapping( "astLoadMathMap", name, nin, nout, new->nfwd, (const char **) new->fwdfun, new->ninv, (const char **) new->invfun, &new->fwdcode, &new->invcode, &new->fwdcon, &new->invcon, &new->fwdstack, &new->invstack, status ); } /* If an error occurred, clean up by deleting the new MathMap. */ if ( !astOK ) new = astDelete( new ); } } /* Return the new MathMap pointer. */ return new; /* Undefine macros local to this function. */ #undef KEY_LEN } ast-8.3.0/normmap.c0000664000175000017500000015503013004147321011050 00000000000000/* *class++ * Name: * NormMap * Purpose: * Normalise coordinates using a supplied Frame. * Constructor Function: c astNormMap f AST_NORMMAP * Description: * The NormMap class implements a Mapping which normalises coordinate * values using the c astNorm function f AST_NORM routine * of a supplied Frame. The number of inputs and outputs of a NormMap * are both equal to the number of axes in the supplied Frame. * * The forward and inverse transformation of a NormMap are both * defined but are identical (that is, they do not form a real inverse * pair in that the inverse transformation does not undo the * normalisation, instead it reapplies it). However, the c astSimplify f AST_SIMPLIFY * function will replace neighbouring pairs of forward and inverse * NormMaps by a single UnitMap. * Inheritance: * The NormMap class inherits from the Mapping class. * Attributes: * The NormMap class does not define any new attributes beyond * those which are applicable to all Mappings. * Functions: c The NormMap class does not define any new functions beyond those f The NormMap class does not define any new routines beyond those * which are applicable to all Mappings. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 11-JUL-2005 (DSB): * Original version. * 23-AUG-2006 (DSB): * Override astEqual. *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 NormMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "channel.h" /* I/O channels */ #include "unitmap.h" /* Unit Mappings */ #include "normmap.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static int *(* parent_mapsplit)( AstMapping *, int, const int *, AstMapping **, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(NormMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(NormMap,Class_Init) #define class_vtab astGLOBAL(NormMap,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstNormMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstNormMap *astNormMapId_( void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *RemoveRegions( AstMapping *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double Rate( AstMapping *, double *, int, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two NormMaps are equivalent. * Type: * Private function. * Synopsis: * #include "normmap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * NormMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two NormMaps are equivalent. * Parameters: * this * Pointer to the first Object (a NormMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the NormMaps are equivalent, zero otherwise. * 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: */ AstNormMap *that; AstNormMap *this; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two NormMap structures. */ this = (AstNormMap *) this_object; that = (AstNormMap *) that_object; /* Check the second object is a NormMap. We know the first is a NormMap since we have arrived at this implementation of the virtual function. */ if( astIsANormMap( that ) ) { /* Check the Invert flags for the two NormMaps are equal. */ if( astGetInvert( this ) == astGetInvert( that ) ) { /* Check the two Frames are equal. */ if( astEqual( this->frame, that->frame ) ) { result = 1; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } void astInitNormMapVtab_( AstNormMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitNormMapVtab * Purpose: * Initialise a virtual function table for a NormMap. * Type: * Protected function. * Synopsis: * #include "normmap.h" * void astInitNormMapVtab( AstNormMapVtab *vtab, const char *name ) * Class Membership: * NormMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the NormMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsANormMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; mapping->RemoveRegions = RemoveRegions; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_transform = mapping->Transform; mapping->Transform = Transform; parent_mapsplit = mapping->MapSplit; mapping->MapSplit = MapSplit; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; mapping->MapSplit = MapSplit; mapping->Rate = Rate; /* Declare the copy constructor, destructor and class dump function. */ astSetDump( vtab, Dump, "NormMap", "Normalise axis values" ); astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); /* 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) ); } } #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: * NormMap 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: */ AstNormMap *this; /* Pointer to NormMap structure */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the NormMap structure. */ this = (AstNormMap *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( !result ) result = astManageLock( this->frame, mode, extra, fail ); return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a NormMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * NormMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated NormMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated NormMap with one which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated NormMap which is to be merged with * its neighbours. This should be a cloned copy of the NormMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * NormMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated NormMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 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 *frm1; AstFrame *frm2; AstMapping *smap; AstNormMap *map; AstNormMap *nmap1; AstNormMap *nmap2; int cancel; int map_inv; int nax; int result; /* Initialise. */ result = -1; /* Check the inherited status. */ if ( !astOK ) return result; /* Initialisation to avoid compiler warnings. */ nax = 0; /* Get a pointer to this NormMap. */ map = (AstNormMap *) this; /* Temporarily set its Invert flag to the requested value. */ map_inv = astGetInvert( map ); astSetInvert( map, ( *invert_list )[ where ] ); /* First try to simplify the NormMap by simplifying its encapsulated Frame. */ smap = astSimplify( map->frame ); /* If any simplification took place, create a new NormMap with the simplified Frame. */ if( smap != (AstMapping *) map->frame ) { (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = (AstMapping *) astNormMap( (AstFrame *) smap, "", status ); result = where; /* The only other simplication which can be performed is to cancel a NormMap with its own inverse in series. */ } else if( series ) { /* Indicate we have nothing to cancel with as yet. */ cancel = -1; /* First consider the lower neighbour. */ if( where > 0 && astIsANormMap( ( *map_list )[ where - 1 ] ) ) { /* Check the Invert flags are opposite */ if( ( *invert_list )[ where ] != ( *invert_list )[ where - 1 ] ) { nmap1 = map; nmap2 = (AstNormMap *) ( *map_list )[ where - 1 ]; /* Check the encapsulated Frames are equal. */ frm1 = nmap1->frame; frm2 = nmap2->frame; if( astEqual( frm1, frm2 ) ) cancel = where - 1; nax = astGetNout( nmap1 ); } } /* Likewise consider the upper neighbour. */ if( cancel == -1 && where + 1 < *nmap && astIsANormMap( ( *map_list )[ where + 1 ] ) ) { if( ( *invert_list )[ where ] != ( *invert_list )[ where + 1 ] ) { nmap1 = map; nmap2 = (AstNormMap *) ( *map_list )[ where + 1 ]; frm1 = nmap1->frame; frm2 = nmap2->frame; if( astEqual( frm1, frm2 ) ) cancel = where + 1; nax = astGetNin( nmap1 ); } } /* If we can cancel with a neightbour, do so. */ if( cancel != -1 ) { (void) astAnnul( ( *map_list )[ where ] ); (void) astAnnul( ( *map_list )[ cancel ] ); ( *map_list )[ where ] = (AstMapping *) astUnitMap( nax, "", status ); ( *invert_list )[ where ] = 0; ( *map_list )[ cancel ] = (AstMapping *) astUnitMap( nax, "", status ); ( *invert_list )[ cancel ] = 0; result = ( cancel < where ) ? cancel : where; } } /* Free resources. */ smap = astAnnul( smap ); /* Reset the original Invert attribute for the specified NormMap */ astSetInvert( map, map_inv ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = -1; /* Return the result. */ return result; } 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 * NormMap. * Type: * Private function. * Synopsis: * #include "normmap.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * NormMap 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 NormMap. This is only possible if the specified inputs * correspond to some subset of the NormMap outputs. That is, there * must exist a subset of the NormMap outputs for which each output * depends only on the selected NormMap inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied NormMap, then a NULL Mapping is returned. * Parameters: * this * Pointer to the NormMap to be split (the NormMap 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 NormMap, 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 NormMap 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 NormMap. 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: */ AstFrame *frm2; /* Pointer to new Frame */ AstNormMap *this; /* Pointer to NormMap structure */ int *result; /* Pointer to returned array */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Invoke the parent astMapSplit method to see if it can do the job. */ result = (*parent_mapsplit)( this_map, nin, in, map, status ); /* If not, we provide a special implementation here. */ if( !result ) { /* Get a pointer to the NormMap structure. */ this = (AstNormMap *) this_map; /* Pick the requried axes from the encapsulated Frame. */ frm2 = astPickAxes( this->frame, nin, in, NULL ); /* Create a new NormMap from this. */ *map = (AstMapping *) astNormMap( frm2, "", status ); /* The returned list of output axes is a copy the supplied list of input axes. */ result = astStore( NULL, in, sizeof( int )*(size_t) nin ); /* Free resources. */ frm2 = astAnnul( frm2 ); } /* 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 double Rate( AstMapping *this, 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 "normmap.h" * result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) * Class Membership: * NormMap member function (overrides the astRate method inherited * from the Mapping class ). * Description: * This function returns the rate of change of a specified output of * the supplied Mapping with respect to a specified input, at a * specified input position. * 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: * 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. */ return ( ax1 == ax2 ) ? 1.0 : 0.0; } static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { /* * Name: * RemoveRegions * Purpose: * Remove any Regions from a Mapping. * Type: * Private function. * Synopsis: * #include "normmap.h" * AstMapping *RemoveRegions( AstMapping *this, int *status ) * Class Membership: * NormMap 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 CmpMap) for any component Mappings * that are instances of the AST Region class. It then creates a new * Mapping from which all Regions have been removed. If a Region * cannot simply be removed (for instance, if it is a component of a * parallel CmpMap), then it is replaced with an equivalent UnitMap * in the returned Mapping. * * The implementation provided by the NormMap class invokes the * astRemoveRegions method on the encapsulated Frame, and returns a * new NormMap containing the resulting Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the modified mapping. * Notes: * - A NULL pointer value will be returned if this function is * invoked with the AST error status set, or if it should fail for * any reason. */ /* Local Variables: */ AstFrame *newfrm; /* New component Frame */ AstMapping *result; /* Result pointer to return */ AstNormMap *new; /* Pointer to new MormMap */ AstNormMap *this; /* Pointer to NormMap structure */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the NormMap. */ this = (AstNormMap *) this_mapping; /* Invoke the astRemoveRegions method on the component Frame. */ newfrm = astRemoveRegions( this->frame ); /* If the Frame was not modified, just return a clone of the supplied pointer. */ if( this->frame == newfrm ) { result = astClone( this ); /* Otherwise, we need to create a new NormMap to return. We take a deep copy of the supplied NormMap and then modify the Frame so that we retain any extra information in the supplied NormMap. */ } else { new = astCopy( this ); (void) astAnnul( new->frame ); new->frame = astClone( newfrm ); result = (AstMapping *) new; } /* Free resources. */ newfrm = astAnnul( newfrm ); /* Annul the returned Mapping if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a NormMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "normmap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * NormMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a NormMap and a set of points encapsulated in a * PointSet and transforms the points so as to apply the required zoom * factor. * Parameters: * this * Pointer to the NormMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the NormMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstNormMap *map; /* Pointer to NormMap to be applied */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double *work; /* Work space for a single point */ int coord; /* Loop counter for coordinates */ int ncoord_in; /* Number of coordinates per input point */ int npoint; /* Number of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the NormMap. */ map = (AstNormMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* Determine the numbers of points and coordinates per point from the input PointSet and obtain pointers for accessing the input and output coordinate values. */ ncoord_in = astGetNcoord( in ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); work = astMalloc( sizeof( double )* ncoord_in ); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { for ( point = 0; point < npoint; point++ ) { for ( coord = 0; coord < ncoord_in; coord++ ) { work[ coord ] = ptr_in[ coord ][ point ]; } astNorm( map->frame, work ); for ( coord = 0; coord < ncoord_in; coord++ ) { ptr_out[ coord ][ point ] = work[ coord ]; } } } /* Free resources */ work = astFree( work ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for NormMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for NormMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the * Frame within the NormMap. */ /* Local Variables: */ AstNormMap *in; /* Pointer to input NormMap */ AstNormMap *out; /* Pointer to output NormMap */ /* Check the global error status. */ if ( !astOK ) return; in = (AstNormMap *) objin; out = (AstNormMap *) objout; out->frame = astCopy( in->frame ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for NormMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for NormMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstNormMap *this; /* Pointer to NormMap */ this = (AstNormMap *) obj; this->frame = astAnnul( this->frame ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for NormMap 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 NormMap class to an output Channel. * Parameters: * this * Pointer to the NormMap 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 Variables: */ AstNormMap *this; /* Pointer to the NormMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the NormMap structure. */ this = (AstNormMap *) this_object; /* Write out values representing the instance variables for the NormMap class. Accompany these with appropriate comment strings, possibly depending on the values being written.*/ /* Frame. */ /* ------ */ astWriteObject( channel, "Frame", 1, 1, this->frame, "Frame defining the normalisation" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsANormMap and astCheckNormMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(NormMap,Mapping) astMAKE_CHECK(NormMap) AstNormMap *astNormMap_( void *frame_void, const char *options, int *status, ...) { /* *++ * Name: c astNormMap f AST_NORMMAP * Purpose: * Create a NormMap. * Type: * Public function. * Synopsis: c #include "normmap.h" c AstNormMap *astNormMap( AstFrame *frame, const char *options, ... ) f RESULT = AST_NORMMAP( FRAME, OPTIONS, STATUS ) * Class Membership: * NormMap constructor. * Description: * This function creates a new NormMap and optionally initialises its * attributes. * * A NormMap is a Mapping which normalises coordinate values using the c astNorm function f AST_NORM routine * of the supplied Frame. The number of inputs and outputs of a NormMap * are both equal to the number of axes in the supplied Frame. * * The forward and inverse transformation of a NormMap are both * defined but are identical (that is, they do not form a real inverse * pair in that the inverse transformation does not undo the * normalisation, instead it reapplies it). However, the c astSimplify f AST_SIMPLIFY * function will replace neighbouring pairs of forward and inverse * NormMaps by a single UnitMap. * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame which is to be used to normalise the * supplied axis values. 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 NormMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new NormMap. The syntax used is identical to that for the f AST_SET routine. 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 astNormMap() f AST_NORMMAP = INTEGER * A pointer to the new NormMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* The Frame pointer */ AstNormMap *new; /* Pointer to new NormMap */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate pointers to the Frame structures provided. */ frame = astCheckFrame( frame_void ); /* Initialise the NormMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitNormMap( NULL, sizeof( AstNormMap ), !class_init, &class_vtab, "NormMap", frame ); if( astOK ) { /* 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 NormMap'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 NormMap. */ return new; } AstNormMap *astNormMapId_( void *frame_void, const char *options, ... ) { /* * Name: * astNormMapId_ * Purpose: * Create a NormMap. * Type: * Private function. * Synopsis: * #include "normmap.h" * AstNormMap *astNormMapId_( int ncoord, double zoom, * const char *options, ... ) * Class Membership: * NormMap constructor. * Description: * This function implements the external (public) interface to the * astNormMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astNormMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astNormMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astNormMap_. * Returned Value: * The ID value associated with the new NormMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* The Frame pointer */ AstNormMap *new; /* Pointer to new NormMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate pointers to the Frame structures provided. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Initialise the NormMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitNormMap( NULL, sizeof( AstNormMap ), !class_init, &class_vtab, "NormMap", 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 NormMap'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 NormMap. */ return astMakeId( new ); } AstNormMap *astInitNormMap_( void *mem, size_t size, int init, AstNormMapVtab *vtab, const char *name, AstFrame *frame, int *status ) { /* *+ * Name: * astInitNormMap * Purpose: * Initialise a NormMap. * Type: * Protected function. * Synopsis: * #include "normmap.h" * AstNormMap *astInitNormMap( void *mem, size_t size, int init, * AstNormMapVtab *vtab, const char *name, * AstFrame *frame ) * Class Membership: * NormMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new NormMap object. It allocates memory (if necessary) to accommodate * the NormMap plus any additional data associated with the derived class. * It then initialises a NormMap 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 NormMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the NormMap is to be initialised. * This must be of sufficient size to accommodate the NormMap data * (sizeof(NormMap)) 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 NormMap (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 NormMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the NormMap'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 NormMap. * 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 * The Frame to use to do the normalisations. * Returned Value: * A pointer to the new NormMap. * 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: */ AstNormMap *new; /* Pointer to new NormMap */ int ncoord; /* Number of input and output coords */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitNormMapVtab( vtab, name ); /* Initialise. */ new = NULL; /* Get the number of axes in the Frame. */ ncoord = astGetNaxes( frame ); /* Initialise a Mapping structure (the parent class) as the first component within the NormMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstNormMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, ncoord, ncoord, 1, 1 ); if ( astOK ) { /* Initialise the NormMap data. */ /* ---------------------------- */ /* Store a pointer to the Frame. */ new->frame = astClone( frame ); /* If an error occurred, clean up by deleting the new NormMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new NormMap. */ return new; } AstNormMap *astLoadNormMap_( void *mem, size_t size, AstNormMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadNormMap * Purpose: * Load a NormMap. * Type: * Protected function. * Synopsis: * #include "normmap.h" * AstNormMap *astLoadNormMap( void *mem, size_t size, * AstNormMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * NormMap loader. * Description: * This function is provided to load a new NormMap 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 * NormMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a NormMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the NormMap is to be * loaded. This must be of sufficient size to accommodate the * NormMap data (sizeof(NormMap)) 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 NormMap (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 NormMap 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(AstNormMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new NormMap. If this is NULL, a pointer * to the (static) virtual function table for the NormMap 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 "NormMap" is used instead. * Returned Value: * A pointer to the new NormMap. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstNormMap *new; /* Pointer to the new NormMap */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this NormMap. In this case the NormMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstNormMap ); vtab = &class_vtab; name = "NormMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitNormMapVtab( 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 NormMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) 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, "NormMap" ); /* 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. */ /* Frame. */ /* ------ */ new->frame = astReadObject( channel, "frame", NULL ); /* If an error occurred, clean up by deleting the new NormMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new NormMap pointer. */ return new; } /* 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. */ ast-8.3.0/grf.h0000664000175000017500000000572413004147321010166 00000000000000#if !defined( GRF_INCLUDED ) /* Include this file only once */ #define GRF_INCLUDED /* *+ * Name: * grf.h * Type: * C include file. * Purpose: * Define the interface to the grf module * Invocation: * #include "grf.h" * Description: * This include file defines the interface to the grf module and * provides the type definitions, function prototypes and macros, etc. * needed to use this module. * Inheritance: * The grf module is not a class and does not inherit. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 27-JUN-1996 (DSB): * Original version. * 25-OCT-1996 (DSB): * Primatives macros defined, extra parameter added to astGAttr. * 17-FEB-2006 (DSB): * Added GRF__ESH and GRF__ESG. *- */ /* Constant Values. */ /* ================ */ /* Values identifying different graphics attributes. */ #define GRF__STYLE 0 #define GRF__WIDTH 1 #define GRF__SIZE 2 #define GRF__FONT 3 #define GRF__COLOUR 4 /* Values identifying different graphics primatives. */ #define GRF__TEXT 0 #define GRF__LINE 1 #define GRF__MARK 2 /* The number of different graphics attributes */ #define GRF__NATTR 5 /* Values identifying capabilities */ #define GRF__ESC 0 #define GRF__MJUST 1 #define GRF__SCALES 2 /* Values identifying types of graphics escape sequence */ #define GRF__ESPER 1 #define GRF__ESSUP 2 #define GRF__ESSUB 3 #define GRF__ESGAP 4 #define GRF__ESBAC 5 #define GRF__ESSIZ 6 #define GRF__ESWID 7 #define GRF__ESFON 8 #define GRF__ESCOL 9 #define GRF__ESSTY 10 #define GRF__ESPOP 11 #define GRF__ESPSH 12 #define GRF__ESH 13 #define GRF__ESG 14 /* Function prototypes. */ /* ==================== */ int astGAttr( int, double, double *, int ); int astGScales( float *, float * ); int astGBBuf( void ); int astGEBuf( void ); int astGFlush( void ); int astGLine( int, const float *, const float * ); int astGMark( int, const float *, const float *, int ); int astGQch( float *, float * ); int astGText( const char *, float, float, const char *, float, float ); int astGTxExt( const char *, float, float, const char *, float, float, float *, float * ); int astGCap( int, int ); #endif ast-8.3.0/dsbspecframe.c0000664000175000017500000034652213004147321012045 00000000000000/* *class++ * Name: * DSBSpecFrame * Purpose: * Dual sideband spectral coordinate system description. * Constructor Function: c astDSBSpecFrame f AST_DSBSPECFRAME * Description: * A DSBSpecFrame is a specialised form of SpecFrame which represents * positions in a spectrum obtained using a dual sideband instrument. * Such an instrument produces a spectrum in which each point contains * contributions from two distinctly different frequencies, one from * the "lower side band" (LSB) and one from the "upper side band" (USB). * Corresponding LSB and USB frequencies are connected by the fact * that they are an equal distance on either side of a fixed central * frequency known as the "Local Oscillator" (LO) frequency. * * When quoting a position within such a spectrum, it is necessary to * indicate whether the quoted position is the USB position or the * corresponding LSB position. The SideBand attribute provides this * indication. Another option that the SideBand attribute provides is * to represent a spectral position by its topocentric offset from the * LO frequency. * * In practice, the LO frequency is specified by giving the distance * from the LO frequency to some "central" spectral position. Typically * this central position is that of some interesting spectral feature. * The distance from this central position to the LO frequency is known * as the "intermediate frequency" (IF). The value supplied for IF can * be a signed value in order to indicate whether the LO frequency is * above or below the central position. * Inheritance: * The DSBSpecFrame class inherits from the SpecFrame class. * Attributes: * In addition to those attributes common to all SpecFrames, every * DSBSpecFrame also has the following attributes: * * - AlignSideBand: Should alignment occur between sidebands? * - DSBCentre: The central position of interest. * - IF: The intermediate frequency used to define the LO frequency. * - ImagFreq: The image sideband equivalent of the rest frequency. * - SideBand: Indicates which sideband the DSBSpecFrame represents. * Functions: c The DSBSpecFrame class does not define any new functions beyond those f The DSBSpecFrame class does not define any new routines beyond those * which are applicable to all SpecFrames. * 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 * . * Authors: * DSB: David Berry (Starlink) * History: * 5-AUG-2004 (DSB): * Original version. * 7-OCT-2004 (DSB): * Fixed SetAttrib code which assigns values to SideBand. Previously * all supplied values were ignored, leaving SideBand unchanged. * 2-SEP-2005 (DSB): * Allow conversion in any Domain within TopoMap (sometimes * SpecFrames have a new Domain set which is not equal to SPECTRUM"). * 12-SEP-2005 (DSB): * Set all attributes required to described the RestFreq value * before determining Mapping from RestFreq to ImagFreq in * GetImageFreq. * 2-DEC-2005 (DSB): * Change default Domain from SPECTRUM to DSBSPECTRUM * 3-APR-2006 (DSB): * Fix memory leak in astLoadDSBSpecFrame. * 6-OCT-2006 (DSB): * Guard against annulling null pointers in subFrame. * 27-OCT-2006 (DSB): * Added AlignSideBand attribute. * 31-OCT-2006 (DSB): * Use AlignSideBand attribute in SubFrame only if we are not * currently restoring a FrameSet's integrity. * 31-JAN-2007 (DSB): * Modified so that a DSBSpecFrame can be used as a template to find a * DSBSpecFrame (or SpecFrame) contained within a CmpFrame. This * involves changes in Match. * 1-MAY-2007 (DSB): * The default for AlignSideband has been changed from 1 to 0. * 8-MAY-2007 (DSB): * Correct initialisation of alignsideband in astInitDSBSpecFrame_. * 19-OCT-2007 (DSB): * Ignore SideBand alignment if the AlignSideBand attribute is zero * in either the target or the template. * 16-JAN-2007 (DSB): * Modify SubFrame so that DSBSpecFrames are aligned in the * observed sideband (LSB or USB) rather than always being aligned * in the USB. * 12-FEB-2010 (DSB): * Report an error if the local oscillator frequency looks silly * (specifically, if it less than the absolute intermediate frequency). * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. *class-- * Implementation Deficiencies: * - The default values for System and StdOfRest inherited from the * SpecFrame class are "Wave" and "Heliocentric". These are not * usually what is wanted for a DSB instrument. Defaults such as * "Freq" and "Topo" may be more appropriate. However, changing the * defaults inherited from SpecFrame may cause problems in the * astConvert algorithm. The astConvertX function in frame.c includes * the following implementation deficiency warning: "One likely * problem is with attributes which default in both the source and * destination Frames. This means they also default in the common * coordinate system. If these default values were to differ when * matching different target Frames, however, we would be in trouble, * because the common coordinate system would not then be remaining * constant. The longer-term solution to this is probably to provide * some mechanism to "fix" all attribute values for a Frame, by taking * any attributes that are un-set and explicitly setting a firm value * (equal to the default) so they cannot then change". So the defaults * should probably be left unchanged until this fix is made. */ /* 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 DSBSpecFrame #define BADSB -9999 #define FIRST_SB -1 #define LSB -1 #define LO 0 #define USB 1 #define LAST_SB 1 /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory management facilities */ #include "object.h" /* Base Object class */ #include "channel.h" /* I/O channels */ #include "specframe.h" /* Spectral frames (parent class) */ #include "unit.h" /* Unit handling */ #include "cmpmap.h" /* Compound Mappings */ #include "unitmap.h" /* Unit Mappings */ #include "winmap.h" /* Window Mappings */ #include "dsbspecframe.h" /* Interface definition for this class */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static const char *(* parent_getlabel)( AstFrame *, int, int * ); static int (* parent_match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int (* parent_subframe)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_overlay)( AstFrame *, const int *, AstFrame *, int * ); static const char *(* parent_getdomain)( AstFrame *, int * ); /* 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->GetLabel_Buff[ 0 ] = 0; \ /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(DSBSpecFrame) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(DSBSpecFrame,Class_Init) #define class_vtab astGLOBAL(DSBSpecFrame,Class_Vtab) #define getattrib_buff astGLOBAL(DSBSpecFrame,GetAttrib_Buff) #define getlabel_buff astGLOBAL(DSBSpecFrame,GetLabel_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Define the thread-specific globals for this class. */ /* Buffer returned by GetAttrib. */ static char getattrib_buff[ 101 ]; /* Default Label string buffer */ static char getlabel_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstDSBSpecFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstDSBSpecFrame *astDSBSpecFrameId_( const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *TopoMap( AstDSBSpecFrame *, int, const char *, int * ); static AstMapping *ToLOMapping( AstDSBSpecFrame *, const char *, int * )__attribute__((unused)); static AstMapping *ToLSBMapping( AstDSBSpecFrame *, const char *, int * ); static AstMapping *ToUSBMapping( AstDSBSpecFrame *, const char *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetLabel( AstFrame *, int, int * ); static double GetImagFreq( AstDSBSpecFrame *, int * ); static double GetLO( AstDSBSpecFrame *, const char *, const char *, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void Overlay( AstFrame *, const int *, AstFrame *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void VerifyAttrs( AstDSBSpecFrame *, const char *, const char *, const char *, int * ); static const char *GetDomain( AstFrame *, int * ); static double GetIF( AstDSBSpecFrame *, int * ); static int TestIF( AstDSBSpecFrame *, int * ); static void ClearIF( AstDSBSpecFrame *, int * ); static void SetIF( AstDSBSpecFrame *, double, int * ); static double GetDSBCentre( AstDSBSpecFrame *, int * ); static int TestDSBCentre( AstDSBSpecFrame *, int * ); static void ClearDSBCentre( AstDSBSpecFrame *, int * ); static void SetDSBCentre( AstDSBSpecFrame *, double, int * ); static int GetSideBand( AstDSBSpecFrame *, int * ); static int TestSideBand( AstDSBSpecFrame *, int * ); static void ClearSideBand( AstDSBSpecFrame *, int * ); static void SetSideBand( AstDSBSpecFrame *, int, int * ); static int GetAlignSideBand( AstDSBSpecFrame *, int * ); static int TestAlignSideBand( AstDSBSpecFrame *, int * ); static void ClearAlignSideBand( AstDSBSpecFrame *, int * ); static void SetAlignSideBand( AstDSBSpecFrame *, int, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the astClearAttrib protected * method inherited from the SpecFrame class). * Description: * This function clears the value of a specified attribute for a * DSBSpecFrame, so that the default value will subsequently be used. * Parameters: * this * Pointer to the DSBSpecFrame. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstDSBSpecFrame *this; /* Pointer to the DSBSpecFrame structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the DSBSpecFrame structure. */ this = (AstDSBSpecFrame *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* DSBCentre. */ /* ---------- */ if ( !strcmp( attrib, "dsbcentre" ) ) { astClearDSBCentre( this ); /* IF */ /* -- */ } else if ( !strcmp( attrib, "if" ) ) { astClearIF( this ); /* SideBand */ /* -------- */ } else if ( !strcmp( attrib, "sideband" ) ) { astClearSideBand( this ); /* AlignSideBand */ /* ------------- */ } else if ( !strcmp( attrib, "alignsideband" ) ) { astClearAlignSideBand( this ); /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then report an error. */ } else if ( !strcmp( attrib, "imagfreq" ) ) { 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); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the protected astGetAttrib * method inherited from the SpecFrame class). * Description: * This function returns a pointer to the value of a specified * attribute for a DSBSpecFrame, formatted as a character string. * Parameters: * this * Pointer to the DSBSpecFrame. * 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 DSBSpecFrame, 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 DSBSpecFrame. 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 */ AstDSBSpecFrame *this; /* Pointer to the DSBSpecFrame structure */ AstMapping *tmap; /* Ptr to Mapping from topofreq to this */ const char *result; /* Pointer value to return */ double dval; /* Attribute value */ double dtemp; /* Attribute value */ int ival; /* 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 SpecFrame structure. */ this = (AstDSBSpecFrame *) 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. */ /* DSBCentre */ /* --------- */ if ( !strcmp( attrib, "dsbcentre" ) ) { /* Get the value as topocentric frequency in Hz. */ dval = astGetDSBCentre( this ); /* Find the Mapping from topocentric frequency in Hz to the spectral system described by this SpecFrame. */ tmap = TopoMap( this, 0, "astGetAttrib", status ); if ( astOK ) { /* Transform the internal value from topocentric frequency into the required system. */ astTran1( tmap, 1, &dval, 1, &dtemp ); if( dtemp == AST__BAD ) { astError( AST__INTER, "astGetAttrib(%s): Cannot convert DSBCentre " "value from topocentric frequency to the required " "system.", status, astGetClass( this ) ); } else { /* Format it. */ (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dtemp ); result = getattrib_buff; } tmap = astAnnul( tmap ); } /* IF */ /* -- */ } else if ( !strcmp( attrib, "if" ) ) { dval = astGetIF( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval*1.0E-9 ); result = getattrib_buff; } /* ImagFreq */ /* -------- */ } else if ( !strcmp( attrib, "imagfreq" ) ) { dval = astGetImagFreq( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval*1.0E-9 ); result = getattrib_buff; } /* SideBand */ /* -------- */ } else if ( !strcmp( attrib, "sideband" ) ) { ival = astGetSideBand( this ); if ( astOK ) { result = ( ival == USB ) ? "USB" : (( ival == LO ) ? "LO" : "LSB" ); } /* AlignSideBand */ /* ------------- */ } else if ( !strcmp( attrib, "alignsideband" ) ) { ival = astGetAlignSideBand( this ) ? 1 : 0; if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static const char *GetDomain( AstFrame *this_frame, int *status ) { /* * Name: * GetDomain * Purpose: * Obtain a pointer to the Domain attribute string for a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * const char *GetDomain( AstFrame *this, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the astGetDomain protected * method inherited from the SpecFrame class). * Description: * This function returns a pointer to the Domain attribute string * for a DSBSpecFrame. * Parameters: * this * Pointer to the DSBSpecFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a constant null-terminated string containing the * Domain value. * Notes: * - The returned pointer or the string it refers to may become * invalid following further invocation of this function or * modification of the DSBSpecFrame. * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstDSBSpecFrame *this; /* Pointer to DSBSpecFrame 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 DSBSpecFrame structure. */ this = (AstDSBSpecFrame *) this_frame; /* If a Domain attribute string has been set, invoke the parent method to obtain a pointer to it. */ if ( astTestDomain( this ) ) { result = (*parent_getdomain)( this_frame, status ); /* Otherwise, provide a pointer to a suitable default string. */ } else { result = "DSBSPECTRUM"; } /* Return the result. */ return result; } static double GetImagFreq( AstDSBSpecFrame *this, int *status ) { /* *+ * Name: * astGetImagFreq * Purpose: * Get the value of the ImagFreq attribute. * Type: * Protected virtual function. * Synopsis: * #include "dsbspecframe.h" * double GetImagFreq( AstDSBSpecFrame *this ) * Class Membership: * DSBSpecFrame method. * Description: * This function returns the image sideband frequency corresponding to * the rest frequency. * Parameters: * this * Pointer to the Frame. * Returned Value: * The required frequency, in Hz. * 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: */ AstDSBSpecFrame *rf_frame;/* DSBSpecFrame describing the rest frequency */ AstMapping *map; /* Pointer to "Observed to Image" mapping */ double result; /* The returned frequency */ double rf; /* Rest frequency in observed sideband */ int sb; /* SideBand value */ /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* The RestFreq attribute is an observed sideband frequency in the source's standard of rest, measured in Hz. Temporaily set attributes to these values. Create a copy of the supplied DSBSpecFrame and set its attributes to these values. */ rf_frame = astCopy( this ); astSetStdOfRest( rf_frame, AST__SCSOR ); astSetSystem( rf_frame, AST__FREQ ); astSetUnit( rf_frame, 0, "Hz" ); astSetC( rf_frame, "SideBand", "observed" ); /* Create a Mapping which transforms positions from the observed to the image sideband. */ sb = astGetSideBand( rf_frame ); if( sb == USB ) { map = ToLSBMapping( rf_frame, "astGetImagFreq", status ); } else if( sb == LSB ) { map = ToUSBMapping( rf_frame, "astGetImagFreq", status ); } else { map = NULL; astError( AST__INTER, "astGetImagFreq(%s): Illegal sideband value " "(%d) encountered (internal AST programming error).", status, astGetClass( this ), sb ); } /* Get the rest frequency in Hz, and transform it using the above Mapping. */ rf = astGetRestFreq( rf_frame ); astTran1( map, 1, &rf, 1, &result ); /* Free resources */ map = astAnnul( map ); rf_frame = astAnnul( rf_frame ); /* If an error has occurrred, return AST__BAD. */ if( !astOK ) result = AST__BAD; /* Return the result. */ return result; } static const char *GetLabel( AstFrame *this, int axis, int *status ) { /* * Name: * GetLabel * Purpose: * Access the Label string for a DSBSpecFrame axis. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * const char *GetLabel( AstFrame *this, int axis, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the astGetLabel method inherited * from the SpecFrame class). * Description: * This function returns a pointer to the Label string for a specified axis * of a DSBSpecFrame. * Parameters: * this * Pointer to the SpecFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ const char *result; /* Pointer to label string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate the axis index. */ astValidateAxis( this, axis, 1, "astGetLabel" ); /* Invoke the parent astGetLabel method to obtain a pointer to it. */ result = (*parent_getlabel)( this, axis, status ); /* Check if this is a default value. If so, append a string indicating the sideband. */ if ( !astTestLabel( this, axis ) ) { /* If OK, supply a pointer to a suitable default label string. */ sprintf( getlabel_buff, "%s (%s)", result, astGetAttrib( this, "sideband" ) ); result = getlabel_buff; } /* Return the result. */ return result; } static double GetLO( AstDSBSpecFrame *this, const char *check_msg, const char *method, int *status ) { /* * Name: * GetLO * Purpose: * Get the Local Oscillator frequency. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * double GetLO( AstDSBSpecFrame *this, const char *check_msg, * const char *method, int *status ) * Class Membership: * DSBSpecFrame method. * Description: * This function returns the local oscillator frequency in topocentric * frequency. * Parameters: * this * Pointer to the Frame. * check_msg * If not NULL, an error will be reported if either the DSBCentre * or IF attribute has not been set to an explicit value. In this * case, the error message will include the supplied text. * method * The name of the calling method - used in error messages. * status * Pointer to the inherited status value. * Returned Value: * The local oscillator frequency, in Hz. * Notes: * - An error is reported if the local oscillator frequency looks * un-physical (specifically, if it is less than the absolute value of * the intermediate frequency). * - 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: */ double f_if; /* Intermediate frequency (topo,HZ) */ double result; /* The returned frequency */ /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* If required, check that explicit values have been assigned to the required attributes (i.e. report an error if a default value would be used for either attribute). */ if( check_msg ) VerifyAttrs( this, check_msg, "IF DSBCentre", method, status ); /* The local oscillator is the sum of the intermediate frequency and the observation centre frequency. */ f_if = astGetIF( this ); result = astGetDSBCentre( this ) + f_if; /* Check the local oscillator frequency is no smaller than the absolute intermediate frequency. */ if( result < fabs( f_if ) && astOK ) { astError( AST__ATTIN, "%s(%s): The local oscillator frequency (%g Hz) " "is too low (less than the intermediate frequency: %g Hz).", status, method, astGetClass( this ), result, fabs( f_if ) ); astError( AST__ATTIN, " This could be caused by a bad value for" " either the IF attribute (currently %g Hz) or the DSBCentre " "attribute (currently %g Hz).", status, f_if, astGetDSBCentre( this ) ); } /* If an error has occurrred, return AST__BAD. */ if( !astOK ) result = AST__BAD; /* Return the result. */ return result; } void astInitDSBSpecFrameVtab_( AstDSBSpecFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitDSBSpecFrameVtab * Purpose: * Initialise a virtual function table for a DSBSpecFrame. * Type: * Protected function. * Synopsis: * #include "dsbspecframe.h" * void astInitDSBSpecFrameVtab( AstDSBSpecFrameVtab *vtab, const char *name ) * Class Membership: * DSBSpecFrame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the DSBSpecFrame class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstFrameVtab *frame; /* Pointer to Frame 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. */ astInitSpecFrameVtab( (AstSpecFrameVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsADSBSpecFrame) 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 = &(((AstSpecFrameVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearDSBCentre = ClearDSBCentre; vtab->TestDSBCentre = TestDSBCentre; vtab->GetDSBCentre = GetDSBCentre; vtab->SetDSBCentre = SetDSBCentre; vtab->ClearIF = ClearIF; vtab->TestIF = TestIF; vtab->GetIF = GetIF; vtab->SetIF = SetIF; vtab->ClearSideBand = ClearSideBand; vtab->TestSideBand = TestSideBand; vtab->GetSideBand = GetSideBand; vtab->SetSideBand = SetSideBand; vtab->ClearAlignSideBand = ClearAlignSideBand; vtab->TestAlignSideBand = TestAlignSideBand; vtab->GetAlignSideBand = GetAlignSideBand; vtab->SetAlignSideBand = SetAlignSideBand; vtab->GetImagFreq = GetImagFreq; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; frame = (AstFrameVtab *) vtab; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_getdomain = frame->GetDomain; frame->GetDomain = GetDomain; parent_overlay = frame->Overlay; frame->Overlay = Overlay; parent_match = frame->Match; frame->Match = Match; parent_subframe = frame->SubFrame; frame->SubFrame = SubFrame; parent_getlabel = frame->GetLabel; frame->GetLabel = GetLabel; /* Declare the class delete function.*/ astSetDump( vtab, Dump, "DSBSpecFrame", "Dual sideband spectral axis" ); /* 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 int Match( AstFrame *template_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 "dsbspecframe.h" * int Match( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the protected astMatch method * inherited from the SpecFrame class). * Description: * This function matches a "template" DSBSpecFrame to a "target" Frame and * determines whether it is possible to convert coordinates between them. * If it is, a mapping that performs the transformation is returned along * with a new Frame that describes the coordinate system that results when * this mapping is applied to the "target" coordinate system. In addition, * information is returned to allow the axes in this "result" Frame to be * associated with the corresponding axes in the "target" and "template" * Frames from which they are derived. * Parameters: * template * Pointer to the template DSBSpecFrame. This describes the coordinate * system (or set of possible coordinate systems) into which we wish to * convert our coordinates. * target * Pointer to the target Frame. This describes the coordinate system in * which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case. * 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 template DSBSpecFrame axis from * which it is derived. If it is not derived from any template * DSBSpecFrame 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 and the template Frames. In * particular, when the template allows the possibility of transformaing * to any one of a set of alternative coordinate systems, the "result" * Frame will indicate which of the alternatives was used. * 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. * Implementation Notes: * This implementation addresses the matching of a DSBSpecFrame class * object to any other class of Frame. A DSBSpecFrame will match any class * of DSBSpecFrame (i.e. possibly from a derived class) but will not match * a less specialised class of Frame (except for a SpecFrame). */ /* Local Variables: */ AstDSBSpecFrame *template; /* Pointer to template DSBSpecFrame structure */ AstFrame *frame0; /* Pointer to Frame underlying axis 0 */ int iaxis0; /* Axis index underlying axis 0 */ int match; /* Coordinate conversion possible? */ /* 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 template DSBSpecFrame structure. */ template = (AstDSBSpecFrame *) template_frame; /* The first criterion for a match is that the template matches as a SpecFrame class object. This ensures that the number of axes (1) and domain, class, etc. of the target Frame are suitable. Invoke the parent "astMatch" method to verify this. */ match = (*parent_match)( template_frame, target, matchsub, template_axes, target_axes, map, result, status ); /* If a match was found, the target Frame must be (or contain) a SpecFrame, but this target SpecFrame may be a simple SpecFrame rather than a DSBSpecFrame. We use the returned objects directly if the target SpecFrame is not a DSBSpecFrame. So if a DSBSpecFrame and a base SpecFrame are aligned, this will result in the DSBSpecFrame behaving as a normal SpecFrame. */ if ( astOK && match ) { /* Get the primary Frame associated with the matching target axis. */ astPrimaryFrame( target, (*target_axes)[ 0 ], &frame0, &iaxis0 ); /* Skip this next section, thus retaining the values returned by the parent Match method above, if the target axis is not a DSBSpecFrame. */ if( astIsADSBSpecFrame( frame0 ) ) { /* Annul the returned objects, which are not needed, but keep the axis association arrays which already hold the correct values. */ *map = astAnnul( *map ); *result = astAnnul( *result ); /* Use the target's "astSubFrame" method to create a new Frame (the result Frame) with a copy of of the target axis. This process also overlays the template attributes on to the target Frame and returns a Mapping between the target and result Frames which effects the required coordinate conversion. */ match = astSubFrame( target, template, 1, *target_axes, *template_axes, map, result ); } /* Free resources. */ frame0 = astAnnul( frame0 ); } /* If an error occurred, or conversion to the result Frame's coordinate system was not possible, then free all memory, annul the returned objects, and reset the returned value. */ if ( !astOK || !match ) { if( *template_axes ) *template_axes = astFree( *template_axes ); if( *target_axes ) *target_axes = astFree( *target_axes ); if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } static void Overlay( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { /* * Name: * Overlay * Purpose: * Overlay the attributes of a template DSBSpecFrame on to another Frame. * Type: * Private function. * Synopsis: * #include "specframe.h" * void Overlay( AstFrame *template, const int *template_axes, * AstFrame *result, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the protected astOverlay method * inherited from the SpecFrame class). * Description: * This function overlays attributes of a DSBSpecFrame (the "template") on to * another Frame, so as to over-ride selected attributes of that second * Frame. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which a Frame acquires attributes from the template, but * retains its original attributes (as the default) if new values have not * previously been explicitly set in the template. * * Note that if the result Frame is a DSBSpecFrame and a change of spectral * coordinate system occurs as a result of overlaying its System * attribute, then some of its original attribute values may no * longer be appropriate (e.g. the Title, or attributes describing * its axes). In this case, these will be cleared before overlaying * any new values. * Parameters: * template * Pointer to the template DSBSpecFrame, for which values should have been * explicitly set for any attribute which is to be transferred. * template_axes * Pointer to an array of int, with one element for each axis of the * "result" Frame (see below). For each axis in the result frame, the * corresponding element of this array should contain the (zero-based) * index of the template axis to which it corresponds. This array is used * to establish from which template axis any axis-dependent attributes * should be obtained. * * If any axis in the result Frame is not associated with a template * axis, the corresponding element of this array should be set to -1. * * If a NULL pointer is supplied, the template and result axis * indices are assumed to be identical. * result * Pointer to the Frame which is to receive the new attribute values. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - In general, if the result Frame is not from the same class as the * template DSBSpecFrame, or from a class derived from it, then attributes may * exist in the template DSBSpecFrame which do not exist in the result Frame. * In this case, these attributes will not be transferred. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent class astOverlay method to transfer attributes inherited from the parent class. */ (*parent_overlay)( template, template_axes, result, status ); /* Check if the result Frame is a DSBSpecFrame or from a class derived from DSBSpecFrame. If not, we cannot transfer DSBSpecFrame attributes to it as it is insufficiently specialised. In this case simply omit these attributes. */ if( astIsADSBSpecFrame( result ) && astOK ) { /* Define macros that test whether an attribute is set in the template and, if so, transfers its value to the result. */ #define OVERLAY(attribute) \ if ( astTest##attribute( template ) ) { \ astSet##attribute( result, astGet##attribute( template ) ); \ } /* Use the macro to transfer each DSBSpecFrame attribute in turn. */ OVERLAY(DSBCentre) OVERLAY(IF) OVERLAY(SideBand) OVERLAY(AlignSideBand) } /* Undefine macros local to this function. */ #undef OVERLAY } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * DSBSpecFrame member function (over-rides the astSetAttrib protected * method inherited from the SpecFrame class). * Description: * This function assigns an attribute value for a DSBSpecFrame, 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 DSBSpecFrame. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstDSBSpecFrame *this; /* Pointer to the DSBSpecFrame structure */ AstMapping *tmap; /* Ptr to Mapping from this to topofreq */ AstMapping *umap; /* Ptr to Mapping between units */ double dtemp; /* Attribute value */ double dval; /* Attribute value */ int ival; /* Attribute value */ int len; /* Length of setting string */ int nc; /* Used length */ int off; /* Offset to start of string */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the DSBSpecFrame structure. */ this = (AstDSBSpecFrame *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* DSBCentre */ /* --------- */ if ( strstr( setting, "dsbcentre=" ) ) { /* Without any units indication - assume it is supplied in the system of the DSBSpecFrame. */ int ok = 0; if( nc = 0, ( 1 == astSscanf( setting, "dsbcentre= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { ok = 1; /* With units indication. Is there a Mapping from the supplied units to the units used by the DSBSpecFrame? If so, use the Mapping to convert the supplied value to the required units. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "dsbcentre= %lg %n%*s %n", &dval, &off, &nc ) ) && ( nc >= len ) ) { if( ( umap = astUnitMapper( setting + off, astGetUnit( this, 0 ), NULL, NULL ) ) ) { astTran1( umap, 1, &dval, 1, &dtemp ); dval = dtemp; umap = astAnnul( umap ); if( astOK && dval != AST__BAD ) ok = 1; /* Otherwise report an error. */ } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): Value supplied for " "attribute \"DSBCentre\" (%s) uses units which are " "inappropriate for the current spectral system (%s).", status, astGetClass( this ), setting + 10, astGetTitle( this ) ); } } /* Convert the value from the supplied system to topocentric frequency in Hx, and store. */ if( ok ) { /* Find the Mapping from the spectral system described by this SpecFrame to topocentric frequency in Hz. */ tmap = TopoMap( this, 1, "astSetAttrib", status ); if ( astOK ) { /* Transform the supplied value to topocentric frequency. */ astTran1( tmap, 1, &dval, 1, &dtemp ); if( dtemp == AST__BAD ) { astError( AST__ATTIN, "astSetAttrib(%s): The setting \"%s\" is " "invalid for a %s.", status, astGetClass( this ), setting, astGetClass( this ) ); } else { /* Store it. */ astSetDSBCentre( this, dtemp ); } tmap = astAnnul( tmap ); } } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): The setting \"%s\" is " "invalid for a %s.", status, astGetClass( this ), setting, astGetClass( this ) ); } /* IF */ /* -- */ /* Without any units indication - assume GHz. Convert to Hz for storage. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "if= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetIF( this, dval*1.0E9 ); /* With units indication. */ } else if ( nc = 0, ( 1 == astSscanf( setting, "if= %lg %n%*s %n", &dval, &off, &nc ) ) && ( nc >= len ) ) { /* Is there a Mapping from the supplied units to Hz? If so, use the Mapping to convert the supplied value to Hz. */ if( ( umap = astUnitMapper( setting + off, "Hz", NULL, NULL ) ) ) { astTran1( umap, 1, &dval, 1, &dtemp ); umap = astAnnul( umap ); /* Set the intermediate frequency. */ astSetIF( this, dtemp ); /* Otherwise report an error. */ } else if( astOK ) { astError( AST__ATTIN, "astSetAttrib(%s): Intermediate frequency given " "in an inappropriate system of units \"%g %s\".", status, astGetClass( this ), dval, setting + off ); } /* SideBand */ /* -------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "sideband= %n%*s %n", &ival, &nc ) ) && ( nc >= len ) ) { if( astChrMatch( "usb", setting+ival ) ) { astSetSideBand( this, USB ); } else if( astChrMatch( "lsb", setting+ival ) ) { astSetSideBand( this, LSB ); } else if( astChrMatch( "lo", setting+ival ) ) { astSetSideBand( this, LO ); } else if( astChrMatch( "observed", setting+ival ) ) { astSetSideBand( this, ( astGetIF( this ) > 0 ) ? LSB : USB ); } else if( astChrMatch( "image", setting+ival ) ) { astSetSideBand( this, ( astGetIF( this ) <= 0 ) ? LSB : USB ); } else { astError( AST__ATTIN, "astSetAttrib(%s): The setting \"%s\" is " "invalid for a %s.", status, astGetClass( this ), setting, astGetClass( this ) ); } /* AlignSideBand */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "alignsideband= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetAlignSideBand( this, ival ); /* Read-only attributes. */ /* --------------------- */ /* Define a macro to see if the setting string matches any of the read-only attributes of this class. */ #define MATCH(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ ( nc >= len ) ) /* Use this macro to report an error if a read-only attribute has been specified. */ } else if ( MATCH( "imagfreq" ) ) { 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 any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static int SubFrame( AstFrame *target_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 DSBSpecFrame and convert to the new coordinate * system. * Type: * Private function. * Synopsis: * #include "dsbspecframe.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: * DSBSpecFrame member function (over-rides the protected astSubFrame * method inherited from the SpecFrame class). * Description: * This function selects a requested sub-set (or super-set) of the axes * from a "target" DSBSpecFrame and creates a new Frame with copies of * the selected axes assembled in the requested order. It then * optionally overlays the attributes of a "template" Frame on to the * result. It returns both the resulting Frame and a Mapping that * describes how to convert between the coordinate systems described by * the target and result Frames. If necessary, this Mapping takes * account of any differences in the Frames' attributes due to the * influence of the template. * Parameters: * target * Pointer to the target DSBSpecFrame, from which axes are to be * selected. * template * Pointer to the template Frame, from which new attributes for the * result Frame are to be obtained. Optionally, this may be NULL, in * which case no overlaying of template attributes will be performed. * result_naxes * Number of axes to be selected from the target Frame. This number may * be greater than or less than the number of axes in this Frame (or * equal). * target_axes * Pointer to an array of int with result_naxes elements, giving a list * of the (zero-based) axis indices of the axes to be selected from the * target DSBSpecFrame. The order in which these are given determines * the order in which the axes appear in the result Frame. If any of the * values in this array is set to -1, the corresponding result axis will * not be derived from the target Frame, but will be assigned default * attributes instead. * template_axes * Pointer to an array of int with result_naxes elements. This should * contain a list of the template axes (given as zero-based axis indices) * with which the axes of the result Frame are to be associated. This * array determines which axes are used when overlaying axis-dependent * attributes of the template on to the result. If any element of this * array is set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not used and * a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned Mapping. * The forward transformation of this Mapping will describe how to * convert coordinates from the coordinate system described by the target * DSBSpecFrame 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 target and the result Frame. Otherwise zero is returned and * *map and *result are returned as NULL (but this will not in itself * result in an error condition). In general, coordinate conversion should * always be possible if no template Frame is supplied but may not always * be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * Implementation Notes: * - This implementation addresses the selection of axes from a * DSBSpecFrame object. This results in another object of the same class * only if the single DSBSpecFrame axis is selected exactly once. * Otherwise, the result is a Frame class object which inherits the * DSBSpecFrame's axis information (if appropriate) but none of the other * properties of a DSBSpecFrame. * - In the event that a DSBSpecFrame results, the returned Mapping will * take proper account of the relationship between the target and result * coordinate systems. * - In the event that a Frame class object results, the returned Mapping * will only represent a selection/permutation of axes. * Implementation Deficiencies: * - Any axis selection is currently permitted. Probably this should be * restricted so that each axis can only be selected once. The * astValidateAxisSelection method will do this but currently there are bugs * in the CmpFrame class that cause axis selections which will not pass this * test. Install the validation when these are fixed. */ /* Local Variables: */ AstDSBSpecFrame *dsbresult;/* Pointer to the DSBSpecFrame result Frame */ AstDSBSpecFrame *dsbtarget;/* Pointer to the DSBSpecFrame target Frame */ AstMapping *map1; /* Intermediate Mapping */ AstMapping *map2; /* Intermediate Mapping */ AstMapping *map3; /* Intermediate Mapping */ int alignsb; /* Use sidebands to align the Frames? */ int match; /* Coordinate conversion is possible? */ int obs_sb; /* The observed sideband value */ int old_sb; /* The original Sideband value */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Invoke the astSubFrame method inherited from the parent SpecFrame class. This will (if possible) create a result Frame which is a DSBSpecFrame (since the supplied target Frame is a DSBSpecFrame). However, the Mapping from target to result Frame will take no account of any differences in the values of the attributes specific to the DSBSpecFrame class. */ match = (*parent_subframe)( target_frame, template, result_naxes, target_axes, template_axes, map, result, status ); /* If a match occurred, and the result and template Frames are both DSBSpecFrames, we now modify the Mapping to take account of DSBSpecFrame-specific attributes. */ if( match && template && astIsADSBSpecFrame( template ) && astIsADSBSpecFrame( *result ) ) { /* Get pointers to the two DSBSpecFrames */ dsbtarget = (AstDSBSpecFrame *) target_frame; /* See whether alignment occurs between sidebands. If the current call to this function is part of the process of restoring a FrameSet's integrity following changes to the FrameSet's current Frame, then we ignore the setting of the AlignSideBand attributes and use 1. This ensures that when the SideBand attribute (for instance) is changed via a FrameSet pointer, the Mappings within the FrameSet are modified to produce frequencies in the new SideBand. In most other cases, astronomers usually want to align the DSBSpecFrames as if they were basic SpecFrames (that is, ignoring the setting of the SideBand attribute). */ if( astGetFrameFlags( target_frame ) & AST__INTFLAG ) { alignsb = 1; } else { alignsb = astGetAlignSideBand( dsbtarget ) && astGetAlignSideBand( (AstDSBSpecFrame *) template ); } /* If we are aligning the sidebands we need to modify the Mapping returned above by the parent SubFrame method. The existing Mapping will convert between the spectral systems represented by the two DSBSpecFrames but will not take account of any difference in sidebands. */ if( alignsb ) { /* We assume that alignment occurs in the observed sideband. Determine which side band is the observed sideband in the target. */ old_sb = astGetSideBand( dsbtarget ); astSetC( dsbtarget, "SideBand", "observed" ); obs_sb = astGetSideBand( dsbtarget ); astSetSideBand( dsbtarget, old_sb ); /* Create a Mapping which transforms positions from the target to an exact copy of the target in which the SideBand attribute is set to the observed (USB or LSB) sideband. This will be a UnitMap if the target already represents the observed sideband. */ if( obs_sb == USB ) { map1 = ToUSBMapping( dsbtarget, "astSubFrame", status ); } else if( obs_sb == LSB ) { map1 = ToLSBMapping( dsbtarget, "astSubFrame", status ); } else { map1 = NULL; astError( AST__INTER, "astGetImagFreq(%s): Illegal sideband value " "(%d) encountered (internal AST programming error).", status, astGetClass( target_frame ), obs_sb ); } /* Determine which side band is the observed sideband in the result. */ dsbresult = (AstDSBSpecFrame *) *result; old_sb = astGetSideBand( dsbresult ); astSetC( dsbresult, "SideBand", "observed" ); obs_sb = astGetSideBand( dsbresult ); astSetSideBand( dsbresult, old_sb ); /* Create a Mapping which transforms positions from the result to an exact copy of the result in which the SideBand attribute is set to the obserfed sideband. This will be a UnitMap if the target already represents the observed sideband. */ if( obs_sb == USB ) { map2 = ToUSBMapping( dsbresult, "astSubFrame", status ); } else if( obs_sb == LSB ) { map2 = ToLSBMapping( dsbresult, "astSubFrame", status ); } else { map2 = NULL; astError( AST__INTER, "astGetImagFreq(%s): Illegal sideband value " "(%d) encountered (internal AST programming error).", status, astGetClass( target_frame ), obs_sb ); } /* Invert it to get the mapping from the observed sideband to the result. */ astInvert( map2 ); /* Form a Mapping which first maps target values to the observed sideband, then applies the Mapping returned by the parent SubFrame method in order to convert between spectral systems, and then converts from the observed sideband to the SideBand of the result. */ map3 = (AstMapping *) astCmpMap( map1, *map, 1, "", status ); map1 = astAnnul( map1 ); *map = astAnnul( *map ); map1 = (AstMapping *) astCmpMap( map3, map2, 1, "", status ); map3 = astAnnul( map3 ); map2 = astAnnul( map2 ); /* Returned the simplified Mapping. */ *map = astSimplify( map1 ); map1 = astAnnul( map1 ); } } /* If an error occurred or no match was found, annul the returned objects and reset the returned result. */ if ( !astOK || !match ) { if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * DSBSpecFrame member function (over-rides the astTestAttrib protected * method inherited from the SpecFrame class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a DSBSpecFrame's attributes. * Parameters: * this * Pointer to the DSBSpecFrame. * 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: */ AstDSBSpecFrame *this; /* Pointer to the DSBSpecFrame structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the DSBSpecFrame structure. */ this = (AstDSBSpecFrame *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* DSBCentre */ /* --------- */ if ( !strcmp( attrib, "dsbcentre" ) ) { result = astTestDSBCentre( this ); /* IF */ /* -- */ } else if ( !strcmp( attrib, "if" ) ) { result = astTestIF( this ); /* SideBand */ /* -------- */ } else if ( !strcmp( attrib, "sideband" ) ) { result = astTestSideBand( this ); /* AlignSideBand */ /* ------------- */ } else if ( !strcmp( attrib, "alignsideband" ) ) { result = astTestAlignSideBand( this ); /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then return zero. */ } else if ( !strcmp( attrib, "imagfreq" ) ) { result = 0; /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstMapping *ToLOMapping( AstDSBSpecFrame *this, const char *method, int *status ){ /* * Name: * ToLOMapping * Purpose: * Create a Mapping which transforms a DSBSpecFrame to offset from the * local oscillator frequency. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * AstMapping *ToLOMapping( AstDSBSpecFrame *this, const char *method, int *status ) * Class Membership: * DSBSpecFrame member function * Description: * This function returns a pointer to a new Mapping which transforms * positions in the supplied DSBSpecFrame into an offset from the local * oscillator frequency. This will be a UnitMap if the DSBSpecFrame * already represents offset from the local oscillator frequency. * Parameters: * this * Pointer to the DSBSpecFrame. * method * Pointer to a null-terminated string containing the name of the * public invoking method. This is only used in the construction of * error messages. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a new Mapping. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *fmap; /* LSB to USB (topo freq) */ AstMapping *map1; /* This to USB (topo freq) */ AstMapping *map2; /* This (LSB) to This (USB) */ AstMapping *result; /* Pointer to the returned Mapping */ AstMapping *tmap; /* This to topocentric freq */ double f_lo; /* Local oscillator freq (topo Hz) */ double f_in_a; /* First LSB or USB freq */ double f_in_b; /* Second LSB or USB freq */ double f_out_a; /* First LO freq */ double f_out_b; /* Second LO freq */ int sb; /* SideBand value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the DSBSpecFrame already represents LO offset, return a UnitMap.*/ sb = astGetSideBand( this ); if( sb == LO ) { result = (AstMapping *) astUnitMap( 1, "", status ); /* If the DSBSpecFrame represents the USB or LSB, create a suitable WinMap. */ } else { /* Find the Mapping from the spectral system described by this SpecFrame to topocentric frequency in Hz. */ tmap = TopoMap( this, 1, method, status ); /* Calculate the local oscillator frequency (topocentric in Hertz). */ f_lo = GetLO( this, "create a Mapping to upper sideband", "astGetImagFreq", status ); /* Create a 1D WinMap which converts f_in to f_out. */ if( sb == LSB ) { f_in_a = 0.0; f_in_b = f_lo; f_out_a = f_lo; f_out_b = 0.0; } else { f_in_a = 0.0; f_in_b = -f_lo; f_out_a = f_lo; f_out_b = 0.0; } fmap = (AstMapping *) astWinMap( 1, &f_in_a, &f_in_b, &f_out_a, &f_out_b, "", status ); /* Construct the Mapping: input to f_in, f_in to f_out, f_out to input */ map1 = (AstMapping *) astCmpMap( tmap, fmap, 1, "", status ); astInvert( tmap ); map2 = (AstMapping *) astCmpMap( map1, tmap, 1, "", status ); /* Simplify */ result = astSimplify( map2 ); /* Free resources */ tmap = astAnnul( tmap ); fmap = astAnnul( fmap ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } /* Return NULL if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstMapping *ToLSBMapping( AstDSBSpecFrame *this, const char *method, int *status ){ /* * Name: * ToLSBMapping * Purpose: * Create a Mapping which transforms a DSBSpecFrame to the lower * sideband. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * AstMapping *ToLSBMapping( AstDSBSpecFrame *this, const char *method, int *status ) * Class Membership: * DSBSpecFrame member function * Description: * This function returns a pointer to a new Mapping which transforms * positions in the supplied DSBSpecFrame to the lower sideband. This * will be a UnitMap if the DSBSpecFrame already represents the lower * sideband. * Parameters: * this * Pointer to the DSBSpecFrame. * method * Pointer to a null-terminated string containing the name of the * public invoking method. This is only used in the construction of * error messages. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a new Mapping. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *fmap; /* LSB to USB (topo freq) */ AstMapping *map1; /* This to USB (topo freq) */ AstMapping *map2; /* This (LSB) to This (USB) */ AstMapping *result; /* Pointer to the returned Mapping */ AstMapping *tmap; /* This to topocentric freq */ double f_lo; /* Local oscillator freq (topo Hz) */ double f_out_a; /* First LSB freq */ double f_out_b; /* Second LSB freq */ double f_in_a; /* First USB or LO freq */ double f_in_b; /* Second USB or LO freq */ int sb; /* SideBand value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the DSBSpecFrame already represents the LSB, return a UnitMap.*/ sb = astGetSideBand( this ); if( sb == LSB ) { result = (AstMapping *) astUnitMap( 1, "", status ); /* If the DSBSpecFrame represents the USB or LO offset, create a suitable WinMap. */ } else { /* Find the Mapping from the spectral system described by this SpecFrame to topocentric frequency in Hz. */ tmap = TopoMap( this, 1, method, status ); /* Calculate the local oscillator frequency (topocentric in Hertz). */ f_lo = GetLO( this, "create a Mapping to lower sideband", "astGetImagFreq", status ); /* Create a 1D WinMap which converts USB or LO to LSB. */ if( sb == USB ) { f_in_a = 0.0; f_in_b = 2*f_lo; f_out_a = 2*f_lo; f_out_b = 0.0; } else { f_in_a = 0.0; f_in_b = f_lo; f_out_a = f_lo; f_out_b = 0.0; } fmap = (AstMapping *) astWinMap( 1, &f_in_a, &f_in_b, &f_out_a, &f_out_b, "", status ); /* Construct the Mapping: input to f_in, f_in to f_out, f_out to input */ map1 = (AstMapping *) astCmpMap( tmap, fmap, 1, "", status ); astInvert( tmap ); map2 = (AstMapping *) astCmpMap( map1, tmap, 1, "", status ); /* Simplify */ result = astSimplify( map2 ); /* Free resources */ tmap = astAnnul( tmap ); fmap = astAnnul( fmap ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } /* Return NULL if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstMapping *TopoMap( AstDSBSpecFrame *this, int forward, const char *method, int *status ){ /* * Name: * TopoMap * Purpose: * Create a Mapping which transforms a DSBSpecFrame to topocentric * frequency. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * AstMapping *TopoMap( AstDSBSpecFrame *this, int forward, * const char *method, int *status ) * Class Membership: * DSBSpecFrame member function * Description: * This function returns a pointer to a new Mapping which transforms * positions in the supplied DSBSpecFrame to the corresponding * topocentric frequency values in Hz (or the inverse of this). * Parameters: * this * Pointer to the DSBSpecFrame. * forward * If zero, the calcuated Mapping is inverted before being returned. * method * Pointer to a null-terminated string containing the name of the * public invoking method. This is only used in the construction of * error messages. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a new Mapping. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *result; /* The returned Mapping */ AstFrameSet *fs; /* FrameSet connecting tf1 and tf2 */ AstSpecFrame *tf1; /* SpecFrame corresponding to this DSBSpecFrame */ AstSpecFrame *tf2; /* Topocentric frequency SpecFrame */ int template_axis; /* The axis to overlay */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Make a SpecFrame and then overlay the SpecFrame attributes of this DSBSpecFrame onto the new SpecFrame. This means it inherits the current values of things like ObsLon and ObsLat. */ tf1 = astSpecFrame( "", status ); template_axis = 0; (*parent_overlay)( (AstFrame *) this, &template_axis, (AstFrame *) tf1, status ); /* Copy this new SpecFrame and set its attributes to describe topocentric frequency in Hz. Ensure that alignment occurs in the topocentric Frame. */ astSetAlignStdOfRest( tf1, AST__TPSOR); tf2 = astCopy( tf1 ); astSetSystem( tf2, AST__FREQ ); astSetStdOfRest( tf2, AST__TPSOR ); astSetUnit( tf2, 0, "Hz" ); /* Find the Mapping from the spectral system described by this SpecFrame to topocentric frequency in Hz. */ fs = astConvert( tf1, tf2, "" ); if ( astOK ) { if( !fs ) { astError( AST__INTER, "%s(%s): Cannot convert DSBCentre " "value from the supplied system to topocentric frequency " "(internal AST programming error).", status, method, astGetClass( this ) ); } else { result = astGetMapping( fs, AST__BASE, AST__CURRENT ); if( !forward ) astInvert( result ); } fs = astAnnul( fs ); } /* Free resources */ tf1 = astAnnul( tf1 ); tf2 = astAnnul( tf2 ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstMapping *ToUSBMapping( AstDSBSpecFrame *this, const char *method, int *status ){ /* * Name: * ToUSBMapping * Purpose: * Create a Mapping which transforms a DSBSpecFrame to the upper * sideband. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * AstMapping *ToUSBMapping( AstDSBSpecFrame *this, const char *method, int *status ) * Class Membership: * DSBSpecFrame member function * Description: * This function returns a pointer to a new Mapping which transforms * positions in the supplied DSBSpecFrame to the upper sideband. This * will be a UnitMap if the DSBSpecFrame already represents the upper * sideband. * Parameters: * this * Pointer to the DSBSpecFrame. * method * Pointer to a null-terminated string containing the name of the * public invoking method. This is only used in the construction of * error messages. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a new Mapping. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstMapping *fmap; /* LSB to USB (topo freq) */ AstMapping *map1; /* This to USB (topo freq) */ AstMapping *map2; /* This (LSB) to This (USB) */ AstMapping *result; /* Pointer to the returned Mapping */ AstMapping *tmap; /* This to topocentric freq */ double f_lo; /* Local oscillator freq (topo Hz) */ double f_in_a; /* First LSB or LO freq */ double f_in_b; /* Second LSB or LO freq */ double f_out_a; /* First USB freq */ double f_out_b; /* Second USB freq */ int sb; /* SideBand value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the DSBSpecFrame already represents the USB, return a UnitMap.*/ sb = astGetSideBand( this ); if( sb == USB ) { result = (AstMapping *) astUnitMap( 1, "", status ); /* If the DSBSpecFrame represents the LSB, or LO offset, create a suitable WinMap. */ } else { /* Find the Mapping from the spectral system described by this SpecFrame to topocentric frequency in Hz. */ tmap = TopoMap( this, 1, method, status ); /* Calculate the local oscillator frequency (topocentric in Hertz). */ f_lo = GetLO( this, "create a Mapping to upper sideband", "astGetImagFreq", status ); /* Create a 1D WinMap which converts f_in to f_out. */ if( sb == LSB ) { f_in_a = 0.0; f_in_b = 2*f_lo; f_out_a = 2*f_lo; f_out_b = 0.0; } else { f_in_a = 0.0; f_in_b = -f_lo; f_out_a = f_lo; f_out_b = 0.0; } fmap = (AstMapping *) astWinMap( 1, &f_in_a, &f_in_b, &f_out_a, &f_out_b, "", status ); /* Construct the Mapping: input to f_in, f_in to f_out, f_out to input */ map1 = (AstMapping *) astCmpMap( tmap, fmap, 1, "", status ); astInvert( tmap ); map2 = (AstMapping *) astCmpMap( map1, tmap, 1, "", status ); /* Simplify */ result = astSimplify( map2 ); /* Free resources */ tmap = astAnnul( tmap ); fmap = astAnnul( fmap ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); } /* Return NULL if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void VerifyAttrs( AstDSBSpecFrame *this, const char *purp, const char *attrs, const char *method, int *status ) { /* * Name: * VerifyAttrs * Purpose: * Verify that usable attribute values are available. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * void VerifyAttrs( AstDSBSpecFrame *this, const char *purp, * const char *attrs, const char *method, int *status ) * Class Membership: * DSBSpecFrame member function * Description: * This function tests each attribute listed in "attrs". It returns * without action if 1) an explicit value has been set for each attribute * or 2) the UseDefs attribute of the supplied DSBSpecFrame is non-zero. * * If UseDefs is zero (indicating that default values should not be * used for attributes), and any of the named attributes does not have * an explicitly set value, then an error is reported. * Parameters: * this * Pointer to the DSBSpecFrame. * purp * Pointer to a text string containing a message which will be * included in any error report. This shouldindicate the purpose * for which the attribute value is required. * attrs * A string holding a space separated list of attribute names. * method * A string holding the name of the calling method for use in error * messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *a; const char *desc; const char *p; int len; int set; int state; /* Check inherited status */ if( !astOK ) return; /* If the DSBSpecFrame has a non-zero value for its UseDefs attribute, then all attributes are assumed to have usable values, since the defaults will be used if no explicit value has been set. So we only need to do any checks if UseDefs is zero. */ if( !astGetUseDefs( this ) ) { /* Initialise variables to avoid compiler warnings. */ a = NULL; desc = NULL; len = 0; set = 0; /* Loop round the "attrs" string identifying the start and length of each non-blank word in the string. */ state = 0; p = attrs; while( 1 ) { if( state == 0 ) { if( !isspace( *p ) ) { a = p; len = 1; state = 1; } } else { if( isspace( *p ) || !*p ) { /* The end of a word has just been reached. Compare it to each known attribute value. Get a flag indicating if the attribute has a set value, and a string describing the attribute.*/ if( len > 0 ) { if( !strncmp( "DSBCentre", a, len ) ) { set = astTestDSBCentre( this ); desc = "central position of interest"; } else if( !strncmp( "IF", a, len ) ) { set = astTestIF( this ); desc = "intermediate frequency"; } else { astError( AST__INTER, "VerifyAttrs(DSBSpecFrame): " "Unknown attribute name \"%.*s\" supplied (AST " "internal programming error).", status, len, a ); } /* If the attribute does not have a set value, report an error. */ if( !set && astOK ) { astError( AST__NOVAL, "%s(%s): Cannot %s.", status, method, astGetClass( this ), purp ); astError( AST__NOVAL, "No value has been set for " "the AST \"%.*s\" attribute (%s).", status, len, a, desc ); } /* Continue the word search algorithm. */ } len = 0; state = 0; } else { len++; } } if( !*(p++) ) break; } } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * ImagFreq * Purpose: * The image sideband equivalent of the rest frequency. * Type: * Public attribute. * Synopsis: * Floating point, read-only. * Description: * This is a read-only attribute giving the frequency which * corresponds to the rest frequency but is in the opposite sideband. * The value is calculated by first transforming the rest frequency * (given by the RestFreq attribute) from the standard of rest of the * source (given by the SourceVel and SourceVRF attributes) to the * standard of rest of the observer (i.e. the topocentric standard of * rest). The resulting topocentric frequency is assumed to be in the * same sideband as the value given for the DSBCentre attribute (the * "observed" sideband), and is transformed to the other sideband (the * "image" sideband). The new frequency is converted back to the standard * of rest of the source, and the resulting value is returned as the * attribute value, in units of GHz. * Applicability: * DSBSpecFrame * All DSBSpecFrames have this attribute. *att-- */ /* *att++ * Name: * DSBCentre * Purpose: * The central position of interest in a dual sideband spectrum. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute specifies the central position of interest in a dual * sideband spectrum. Its sole use is to determine the local oscillator * frequency (the frequency which marks the boundary between the lower * and upper sidebands). See the description of the IF (intermediate * frequency) attribute for details of how the local oscillator frequency * is calculated. The sideband containing this central position is * referred to as the "observed" sideband, and the other sideband as * the "image" sideband. * * The value is accessed as a position in the spectral system * represented by the SpecFrame attributes inherited by this class, but * is stored internally as topocentric frequency. Thus, if the System * attribute of the DSBSpecFrame is set to "VRAD", the Unit attribute * set to "m/s" and the StdOfRest attribute set to "LSRK", then values * for the DSBCentre attribute should be supplied as radio velocity in * units of "m/s" relative to the kinematic LSR (alternative units may * be used by appending a suitable units string to the end of the value). * This value is then converted to topocentric frequency and stored. If * (say) the Unit attribute is subsequently changed to "km/s" before * retrieving the current value of the DSBCentre attribute, the stored * topocentric frequency will be converted back to LSRK radio velocity, * this time in units of "km/s", before being returned. * * The default value for this attribute is 30 GHz. * Applicability: * DSBSpecFrame * All DSBSpecFrames have this attribute. * Note: * - The attributes which define the transformation to or from topocentric * frequency should be assigned their correct values before accessing * this attribute. These potentially include System, Unit, StdOfRest, * ObsLon, ObsLat, ObsAlt, Epoch, RefRA, RefDec and RestFreq. *att-- */ /* The central frequency (topocentric frequency in Hz). */ astMAKE_CLEAR(DSBSpecFrame,DSBCentre,dsbcentre,AST__BAD) astMAKE_GET(DSBSpecFrame,DSBCentre,double,3.0E10,((this->dsbcentre!=AST__BAD)?this->dsbcentre:3.0E10)) astMAKE_SET(DSBSpecFrame,DSBCentre,double,dsbcentre,value) astMAKE_TEST(DSBSpecFrame,DSBCentre,( this->dsbcentre != AST__BAD )) /* *att++ * Name: * IF * Purpose: * The intermediate frequency in a dual sideband spectrum. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute specifies the (topocentric) intermediate frequency in * a dual sideband spectrum. Its sole use is to determine the local * oscillator (LO) frequency (the frequency which marks the boundary * between the lower and upper sidebands). The LO frequency is * equal to the sum of the centre frequency and the intermediate * frequency. Here, the "centre frequency" is the topocentric * frequency in Hz corresponding to the current value of the DSBCentre * attribute. The value of the IF attribute may be positive or * negative: a positive value results in the LO frequency being above * the central frequency, whilst a negative IF value results in the LO * frequency being below the central frequency. The sign of the IF * attribute value determines the default value for the SideBand * attribute. * * When setting a new value for this attribute, the units in which the * frequency value is supplied may be indicated by appending a suitable * string to the end of the formatted value. If the units are not * specified, then the supplied value is assumed to be in units of GHz. * For instance, the following strings all result in an IF of 4 GHz being * used: "4.0", "4.0 GHz", "4.0E9 Hz", etc. * * When getting the value of this attribute, the returned value is * always in units of GHz. The default value for this attribute is 4 GHz. * Applicability: * DSBSpecFrame * All DSBSpecFrames have this attribute. *att-- */ /* The intermediate frequency (topocentric in Hz). */ astMAKE_CLEAR(DSBSpecFrame,IF,ifr,AST__BAD) astMAKE_GET(DSBSpecFrame,IF,double,4.0E9,((this->ifr!=AST__BAD)?this->ifr:4.0E9)) astMAKE_SET(DSBSpecFrame,IF,double,ifr,value) astMAKE_TEST(DSBSpecFrame,IF,( this->ifr != AST__BAD )) /* *att++ * Name: * SideBand * Purpose: * Indicates which sideband a dual sideband spectrum represents. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute indicates whether the DSBSpecFrame currently * represents its lower or upper sideband, or an offset from the local * oscillator frequency. When querying the current value, the returned * string is always one of "usb" (for upper sideband), "lsb" (for lower * sideband), or "lo" (for offset from the local oscillator frequency). * When setting a new value, any of the strings "lsb", "usb", "observed", * "image" or "lo" may be supplied (case insensitive). The "observed" * sideband is which ever sideband (upper or lower) contains the central * spectral position given by attribute DSBCentre, and the "image" * sideband is the other sideband. It is the sign of the IF attribute * which determines if the observed sideband is the upper or lower * sideband. The default value for SideBand is the observed sideband. * Applicability: * DSBSpecFrame * All DSBSpecFrames have this attribute. *att-- */ /* Protected access to the SideBand attribute uses BADSB to indicate "unset". Other negative values mean "LSB", zero means "LO" and positive values mean "USB". */ astMAKE_CLEAR(DSBSpecFrame,SideBand,sideband,BADSB) astMAKE_SET(DSBSpecFrame,SideBand,int,sideband,((value<0)?LSB:((value==0)?LO:USB))) astMAKE_TEST(DSBSpecFrame,SideBand,( this->sideband != BADSB )) astMAKE_GET(DSBSpecFrame,SideBand,int,USB,(this->sideband == BADSB ? ((astGetIF( this )>0)?LSB:USB):this->sideband)) /* *att++ * Name: * AlignSideBand * Purpose: * Should the SideBand attribute be taken into account when aligning * this DSBSpecFrame with another DSBSpecFrame? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls how a DSBSpecFrame behaves when an attempt * is made to align it with another DSBSpecFrame using c astFindFrame or astConvert. f AST_FINDFRAME or AST_CONVERT. * If both DSBSpecFrames have a non-zero value for AlignSideBand, the * value of the SideBand attribute in each DSBSpecFrame is used so that * alignment occurs between sidebands. That is, if one DSBSpecFrame * represents USB and the other represents LSB then c astFindFrame and astConvert f AST_FINDFRAME and AST_CONVERT * will recognise that the DSBSpecFrames represent different sidebands * and will take this into account when constructing the Mapping that * maps positions in one DSBSpecFrame into the other. If AlignSideBand * in either DSBSpecFrame is set to zero, then the values of the SideBand * attributes are ignored. In the above example, this would result in a * frequency in the first DSBSpecFrame being mapped onto the same * frequency in the second DSBSpecFrame, even though those frequencies * refer to different sidebands. In other words, if either AlignSideBand * attribute is zero, then the two DSBSpecFrames aligns like basic * SpecFrames. The default value for AlignSideBand is zero. * c When astFindFrame or astConvert f When AST_FINDFRAME or AST_CONVERT * is used on two DSBSpecFrames (potentially describing different spectral * coordinate systems and/or sidebands), it returns a Mapping which can be * used to transform a position in one DSBSpecFrame into the corresponding * position in the other. The Mapping is made up of the following steps in * the indicated order: * * - If both DSBSpecFrames have a value of 1 for the AlignSideBand * attribute, map values from the target's current sideband (given by its * SideBand attribute) to the observed sideband (whether USB or LSB). If * the target already represents the observed sideband, this step will * leave the values unchanged. If either of the two DSBSpecFrames have a * value of zero for its AlignSideBand attribute, then this step is omitted. * * - Map the values from the spectral system of the target to the spectral * system of the template. This Mapping takes into account all the * inherited SpecFrame attributes such as System, StdOfRest, Unit, etc. * * - If both DSBSpecFrames have a value of 1 for the AlignSideBand * attribute, map values from the result's observed sideband to the * result's current sideband (given by its SideBand attribute). If the * result already represents the observed sideband, this step will leave * the values unchanged. If either of the two DSBSpecFrames have a value * of zero for its AlignSideBand attribute, then this step is omitted. * Applicability: * DSBSpecFrame * All DSBSpecFrames have this attribute. *att-- */ /* The AlignSideBand value has a value of -1 when not set yielding a default of 0. */ astMAKE_TEST(DSBSpecFrame,AlignSideBand,( this->alignsideband != -1 )) astMAKE_CLEAR(DSBSpecFrame,AlignSideBand,alignsideband,-1) astMAKE_GET(DSBSpecFrame,AlignSideBand,int,-1,((this->alignsideband==-1)?0:this->alignsideband) ) astMAKE_SET(DSBSpecFrame,AlignSideBand,int,alignsideband,(value?1:0)) /* Copy constructor. */ /* ----------------- */ /* None needed */ /* Destructor. */ /* ----------- */ /* None needed */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for DSBSpecFrame 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 DSBSpecFrame class to an output Channel. * Parameters: * this * Pointer to the DSBSpecFrame 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 Variables: */ AstDSBSpecFrame *this; /* Pointer to the DSBSpecFrame structure */ const char *cval; /* Attribute value */ const char *comm; /* Attribute comment */ double dval; /* Attribute value */ int ival; /* Attribute value */ int set; /* Is attribute set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the DSBSpecFrame structure. */ this = (AstDSBSpecFrame *) this_object; /* 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. */ /* DSBCentre */ /* --------- */ set = TestDSBCentre( this, status ); dval = set ? GetDSBCentre( this, status ) : astGetDSBCentre( this ); astWriteDouble( channel, "DSBCen", set, 1, dval, "Central frequency (Hz topo)" ); /* IF */ /* -- */ set = TestIF( this, status ); dval = set ? GetIF( this, status ) : astGetIF( this ); astWriteDouble( channel, "IF", set, 1, dval, "Intermediate frequency (Hz)" ); /* SideBand */ /* -------- */ set = TestSideBand( this, status ); ival = set ? GetSideBand( this, status ) : astGetSideBand( this ); if( ival == LSB ) { cval = "LSB"; comm = "Represents lower sideband"; } else if( ival == LO ) { cval = "LO"; comm = "Represents offset from LO frequency"; } else { cval = "USB"; comm = "Represents upper sideband"; } astWriteString( channel, "SideBn", set, 1, cval, comm ); /* AlignSideBand */ /* ------------- */ set = TestAlignSideBand( this, status ); ival = set ? GetAlignSideBand( this, status ) : astGetAlignSideBand( this ); astWriteInt( channel, "AlSdBn", set, 1, ival, "Align sidebands?" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsADSBSpecFrame and astCheckDSBSpecFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(DSBSpecFrame,SpecFrame) astMAKE_CHECK(DSBSpecFrame) AstDSBSpecFrame *astDSBSpecFrame_( const char *options, int *status, ...) { /* *++ * Name: c astDSBSpecFrame f AST_DSBSPECFRAME * Purpose: * Create a DSBSpecFrame. * Type: * Public function. * Synopsis: c #include "dsbspecframe.h" c AstDSBSpecFrame *astDSBSpecFrame( const char *options, ... ) f RESULT = AST_DSBSPECFRAME( OPTIONS, STATUS ) * Class Membership: * DSBSpecFrame constructor. * Description: * This function creates a new DSBSpecFrame and optionally initialises its * attributes. * * A DSBSpecFrame is a specialised form of SpecFrame which represents * positions in a spectrum obtained using a dual sideband instrument. * Such an instrument produces a spectrum in which each point contains * contributions from two distinctly different frequencies, one from * the "lower side band" (LSB) and one from the "upper side band" (USB). * Corresponding LSB and USB frequencies are connected by the fact * that they are an equal distance on either side of a fixed central * frequency known as the "Local Oscillator" (LO) frequency. * * When quoting a position within such a spectrum, it is necessary to * indicate whether the quoted position is the USB position or the * corresponding LSB position. The SideBand attribute provides this * indication. Another option that the SideBand attribute provides is * to represent a spectral position by its topocentric offset from the * LO frequency. * * In practice, the LO frequency is specified by giving the distance * from the LO frequency to some "central" spectral position. Typically * this central position is that of some interesting spectral feature. * The distance from this central position to the LO frequency is known * as the "intermediate frequency" (IF). The value supplied for IF can * be a signed value in order to indicate whether the LO frequency is * above or below the central position. * Parameters: 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 DSBSpecFrame. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new DSBSpecFrame. The syntax used is identical to that for the f AST_SET routine. 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 astDSBSpecFrame() f AST_DSBSPECFRAME = INTEGER * A pointer to the new DSBSpecFrame. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstDSBSpecFrame *new; /* Pointer to new DSBSpecFrame */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the DSBSpecFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitDSBSpecFrame( NULL, sizeof( AstDSBSpecFrame ), !class_init, &class_vtab, "DSBSpecFrame" ); /* 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 DSBSpecFrame'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 DSBSpecFrame. */ return new; } AstDSBSpecFrame *astDSBSpecFrameId_( const char *options, ... ) { /* * Name: * astDSBSpecFrameId_ * Purpose: * Create a DSBSpecFrame. * Type: * Private function. * Synopsis: * #include "dsbspecframe.h" * AstDSBSpecFrame *astDSBSpecFrameId_( const char *options, ... ) * Class Membership: * DSBSpecFrame constructor. * Description: * This function implements the external (public) interface to the * astDSBSpecFrame constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astDSBSpecFrame_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astDSBSpecFrame_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astDSBSpecFrame_. * Returned Value: * The ID value associated with the new DSBSpecFrame. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstDSBSpecFrame *new; /* Pointer to new DSBSpecFrame */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the DSBSpecFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitDSBSpecFrame( NULL, sizeof( AstDSBSpecFrame ), !class_init, &class_vtab, "DSBSpecFrame" ); /* 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 DSBSpecFrame'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 DSBSpecFrame. */ return astMakeId( new ); } AstDSBSpecFrame *astInitDSBSpecFrame_( void *mem, size_t size, int init, AstDSBSpecFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitDSBSpecFrame * Purpose: * Initialise a DSBSpecFrame. * Type: * Protected function. * Synopsis: * #include "dsbspecframe.h" * AstDSBSpecFrame *astInitDSBSpecFrame( void *mem, size_t size, int init, * AstDSBSpecFrameVtab *vtab, const char *name ) * Class Membership: * DSBSpecFrame initialiser. * Description: * This function is provided for use by class implementations to initialise * a new DSBSpecFrame object. It allocates memory (if necessary) to accommodate * the DSBSpecFrame plus any additional data associated with the derived class. * It then initialises a DSBSpecFrame 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 DSBSpecFrame at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the DSBSpecFrame is to be initialised. * This must be of sufficient size to accommodate the DSBSpecFrame data * (sizeof(DSBSpecFrame)) 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 DSBSpecFrame (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 DSBSpecFrame * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the DSBSpecFrame'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 DSBSpecFrame. * 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). * Returned Value: * A pointer to the new DSBSpecFrame. * 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: */ AstDSBSpecFrame *new; /* Pointer to new DSBSpecFrame */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitDSBSpecFrameVtab( vtab, name ); /* Initialise. */ new = NULL; /* Initialise a SpecFrame structure (the parent class) as the first component within the DSBSpecFrame structure, allocating memory if necessary. Specify that the SpecFrame should be defined in both the forward and inverse directions. */ new = (AstDSBSpecFrame *) astInitSpecFrame( mem, size, 0, (AstSpecFrameVtab *) vtab, name ); if ( astOK ) { /* Initialise the DSBSpecFrame data. */ /* --------------------------------- */ new->dsbcentre = AST__BAD; new->ifr = AST__BAD; new->sideband = BADSB; new->alignsideband = -1; /* If an error occurred, clean up by deleting the new DSBSpecFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new DSBSpecFrame. */ return new; } AstDSBSpecFrame *astLoadDSBSpecFrame_( void *mem, size_t size, AstDSBSpecFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadDSBSpecFrame * Purpose: * Load a DSBSpecFrame. * Type: * Protected function. * Synopsis: * #include "dsbspecframe.h" * AstDSBSpecFrame *astLoadDSBSpecFrame( void *mem, size_t size, * AstDSBSpecFrameVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * DSBSpecFrame loader. * Description: * This function is provided to load a new DSBSpecFrame 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 * DSBSpecFrame structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a DSBSpecFrame at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the DSBSpecFrame is to be * loaded. This must be of sufficient size to accommodate the * DSBSpecFrame data (sizeof(DSBSpecFrame)) 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 DSBSpecFrame (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 DSBSpecFrame 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(AstDSBSpecFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new DSBSpecFrame. If this is NULL, a pointer * to the (static) virtual function table for the DSBSpecFrame 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 "DSBSpecFrame" is used instead. * Returned Value: * A pointer to the new DSBSpecFrame. * 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: */ AstDSBSpecFrame *new; /* Pointer to the new DSBSpecFrame */ char *text; /* Pointer to string value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this DSBSpecFrame. In this case the DSBSpecFrame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstDSBSpecFrame ); vtab = &class_vtab; name = "DSBSpecFrame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitDSBSpecFrameVtab( 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 DSBSpecFrame. */ new = astLoadSpecFrame( mem, size, (AstSpecFrameVtab *) 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, "DSBSpecFrame" ); /* 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. */ /* DSBCentre */ /* --------- */ new->dsbcentre = astReadDouble( channel, "dsbcen", AST__BAD ); if ( TestDSBCentre( new, status ) ) SetDSBCentre( new, new->dsbcentre, status ); /* IF */ /* -- */ new->ifr = astReadDouble( channel, "if", AST__BAD ); if ( TestIF( new, status ) ) SetIF( new, new->ifr, status ); /* SideBand */ /* -------- */ text = astReadString( channel, "sidebn", " " ); if( astOK ) { if( !strcmp( text, " " ) ) { new->sideband = BADSB; } else if( !strcmp( text, "USB" ) ) { new->sideband = USB; } else if( !strcmp( text, "LSB" ) ) { new->sideband = LSB; } else if( !strcmp( text, "LO" ) ) { new->sideband = LO; } else { astError( AST__ATTIN, "astRead(%s): Invalid SideBand description " "\"%s\".", status, astGetClass( channel ), text ); } if ( TestSideBand( new, status ) ) SetSideBand( new, new->sideband, status ); text = astFree( text ); } /* AlignSideBand */ /* ------------- */ new->alignsideband = astReadInt( channel, "alsdbn", -1 ); if( TestAlignSideBand( new, status ) ) SetAlignSideBand( new, new->alignsideband, status ); /* If an error occurred, clean up by deleting the new DSBSpecFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new DSBSpecFrame pointer. */ return new; } /* 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. */ double astGetImagFreq_( AstDSBSpecFrame *this, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,DSBSpecFrame,GetImagFreq))( this, status ); } ast-8.3.0/fintramap.c0000664000175000017500000003032213004147321011354 00000000000000/* *+ * Name: * fintramap.c * Purpose: * Define a FORTRAN 77 interface to the AST IntraMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the IntraMap class. * Routines Defined: * AST_INTRAMAP * AST_INTRAREG * AST_ISAINTRAMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 18-MAR-1998 (RFWS): * Original version. * 15-SEP-1999 (RFWS): * Added a THIS pointer to the external transformation function * used by an IntraMap. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "intramap.h" /* C interface to the IntraMap class */ #include #include /* Prototypes for private functions. */ /* ================================= */ static void TranWrap( void (*)( AstMapping *, int, int, const double *[], int, int, double *[] ), AstMapping *, int, int, const double *[], int, int, double *[], int * ); /* Transformation function interface. */ /* ================================== */ /* This is concerned with allowing FORTRAN implementations of transformation functions to be passed to the IntraMap class and invoked when necessary by C code in the main class implementation. All FORTRAN-specific aspects of this interface are encapsulated here. */ static void TranWrap( void (* tran)( AstMapping *, int, int, const double *[], int, int, double *[] ), AstMapping *this, int npoint, int ncoord_in, const double *ptr_in[], int forward, int ncoord_out, double *ptr_out[], int *status ) { /* * Name: * TranWrap * Purpose: * Wrapper function to invoke a FORTRAN transformation function. * Type: * Private function. * Synopsis: * void TranWrap( void (* tran)( AstMapping *, int, int, const double *[], * int, int, double *[] ), * AstMapping *this, int npoint, int ncoord_in, * const double *ptr_in[], int forward, int ncoord_out, * double *ptr_out[], int *status ) * Description: * This function invokes a FORTRAN implementation of a * transformation function (which resembles AST_TRANN from the * Mapping class FORTRAN interface) in order to make it callable by * C code which would prefer to call a C function that resembles * astTranP (from the Mapping class C interface). * Parameters: * tran * Pointer to the FORTRAN transformation function to be invoked. * This should result from a cast applied to a pointer to a * function that resembles AST_TRANN (but with the first * argument omitted). * this * An external Mapping ID associated with the internal (true C) pointer * for the IntraMap whose transformation is being evaluated. * npoint * The number of points to be transformed. * ncoord_in * The number of coordinates being supplied for each input point * (i.e. the number of dimensions of the space in which the * input points reside). * ptr_in * An array of pointers to double, with "ncoord_in" * elements. Element "ptr_in[coord]" should point at the first * element of an array of double (with "npoint" elements) which * contain the values of coordinate number "coord" for each * input (untransformed) point. The value of coordinate number * "coord" for input point number "point" is therefore given by * "ptr_in[coord][point]". * forward * A non-zero value indicates that the forward coordinate * transformation is to be applied, while a zero value indicates * that the inverse transformation should be used. * ncoord_out * The number of coordinates being generated for each output * point (i.e. the number of dimensions of the space in which * the output points reside). This need not be the same as * "ncoord_in". * ptr_out * An array of pointers to double, with "ncoord_out" * elements. Element "ptr_out[coord]" should point at the first * element of an array of double (with "npoint" elements) into * which the values of coordinate number "coord" for each output * (transformed) point will be written. The value of coordinate * number "coord" for output point number "point" will therefore * be found in "ptr_out[coord][point]". * status * Pointer to the inherited status value. */ /* Local Variables; */ DECLARE_INTEGER(INDIM); /* First dimension size of input array */ DECLARE_INTEGER(NCOORD_IN); /* Number of input coordinates */ DECLARE_INTEGER(NCOORD_OUT); /* Number of output coordinates */ DECLARE_INTEGER(NPOINT); /* Number of points */ DECLARE_INTEGER(OUTDIM); /* First dimension size of output array */ DECLARE_INTEGER(STATUS); /* FORTRAN error status variable */ DECLARE_INTEGER(THIS); /* External ID for the IntraMap */ DECLARE_LOGICAL(FORWARD); /* Use forward transformation? */ F77_DOUBLE_TYPE *IN; /* Input coordinate array for FORTRAN */ F77_DOUBLE_TYPE *OUT; /* Output coordinate array for FORTRAN */ int coord; /* Loop counter for coordinates */ int i; /* Index into FORTRAN arrays */ /* Check the global error status. */ if ( !astOK ) return; /* Assign input values to the arguments for the FORTRAN transformation function. */ THIS = astP2I( this ); NPOINT = npoint; NCOORD_IN = ncoord_in; INDIM = npoint; FORWARD = forward ? F77_TRUE : F77_FALSE; NCOORD_OUT = ncoord_out; OUTDIM = npoint; /* Since the input/output coordinate values may be stored in separate arrays, we must move them temporarily into new 2-dimensional arrays, as required by the FORTRAN transformation function interface. Allocate memory for these arrays. */ IN = astMalloc( (size_t) ( npoint * ncoord_in ) * sizeof( F77_DOUBLE_TYPE ) ); OUT = astMalloc( (size_t) ( npoint * ncoord_out ) * sizeof( F77_DOUBLE_TYPE ) ); /* If OK, fill the input array with coordinate values. Use "memcpy" to avoid numerical errors if the data contain junk - this allows the transformation function to produce the appropriate error instead of it happening here. */ if ( astOK ) { i = 0; for ( coord = 0; coord < ncoord_in; coord++ ) { (void) memcpy( IN + i, ptr_in[ coord ], (size_t) npoint * sizeof( F77_DOUBLE_TYPE ) ); i += npoint; } } /* Cast the transformation function pointer to a pointer to the FORTRAN subroutine and then invoke it. Transfer the AST error status to and from the subroutine's error status argument. */ if ( astOK ) { STATUS = astStatus; ( *(void (*)()) tran )( INTEGER_ARG(&THIS), INTEGER_ARG(&NPOINT), INTEGER_ARG(&NCOORD_IN), INTEGER_ARG(&INDIM), DOUBLE_ARRAY_ARG(IN), LOGICAL_ARG(&FORWARD), INTEGER_ARG(&NCOORD_OUT), INTEGER_ARG(&OUTDIM), DOUBLE_ARRAY_ARG(OUT), INTEGER_ARG(&STATUS) ); astSetStatus( STATUS ); } /* If OK, transfer the transformed coordinate values to the output arrays. */ if ( astOK ) { i = 0; for ( coord = 0; coord < ncoord_out; coord++ ) { (void) memcpy( ptr_out[ coord ], OUT + i, (size_t) npoint * sizeof( F77_DOUBLE_TYPE ) ); i += npoint; } } /* Free the temporary arrays. */ astFree( IN ); astFree( OUT ); } /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_SUBROUTINE(ast_intrareg)( CHARACTER(NAME), INTEGER(NIN), INTEGER(NOUT), void (* TRAN)(), INTEGER(FLAGS), CHARACTER(PURPOSE), CHARACTER(AUTHOR), CHARACTER(CONTACT), INTEGER(STATUS) TRAIL(NAME) TRAIL(PURPOSE) TRAIL(AUTHOR) TRAIL(CONTACT) ) { GENPTR_CHARACTER(NAME) GENPTR_INTEGER(NIN) GENPTR_INTEGER(NOUT) GENPTR_INTEGER(FLAGS) GENPTR_CHARACTER(PURPOSE) GENPTR_CHARACTER(AUTHOR) GENPTR_CHARACTER(CONTACT) char *name; void (* tran)( AstMapping *, int, int, const double *[], int, int, double *[] ); char *purpose; char *author; char *contact; astAt( "AST_INTRAREG", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); tran = (void (*)( AstMapping *, int, int, const double *[], int, int, double *[] )) TRAN; purpose = astString( PURPOSE, PURPOSE_length ); author = astString( AUTHOR, AUTHOR_length ); contact = astString( CONTACT, CONTACT_length ); astIntraRegFor( name, *NIN, *NOUT, tran, TranWrap, *FLAGS, purpose, author, contact ); astFree( name ); astFree( purpose ); astFree( author ); astFree( contact ); ) } F77_INTEGER_FUNCTION(ast_intramap)( CHARACTER(NAME), INTEGER(NIN), INTEGER(NOUT), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(NAME) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(NAME) GENPTR_INTEGER(NIN) GENPTR_INTEGER(NOUT) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *name; char *options; int i; astAt( "AST_INTRAMAP", NULL, 0 ); astWatchSTATUS( name = astString( NAME, NAME_length ); options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astIntraMap( name, *NIN, *NOUT, "%s", options ) ); astFree( name ); astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isaintramap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAINTRAMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAIntraMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } ast-8.3.0/error.h0000664000175000017500000002345313004147321010540 00000000000000#if !defined( ERROR_INCLUDED ) /* Include this file only once */ #define ERROR_INCLUDED 1 /* *+ * Name: * error.h * Purpose: * Define the interface to the Error module. * Description: * This module defines functions which implement error handling and * reporting of error messages from within the AST library. A * simple public interface is included to allow the AST error * status to be tested and cleared after an error. * * Note that this module is not a class implementation, although it * resembles one. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S Berry (Starlink) * NG: Norman Gray (Starlink) * History: * 2-JAN-1996 (RFWS): * Original version. * 26-JAN-1996 (RFWS): * Added function interfaces. * 14-JUN-1996 (RFWS): * Added AST__FAC and astAt. * 20-JUN-1996 (RFWS): * Added astSetStatus. * 16-JUL-1996 (RFWS): * Added astWatch. * 18-MAR-1998 (RFWS): * Make interface available for writing foreign language and * graphics interfaces, etc. * 27-NOV-2002 (DSB): * Added astReporting. * 14-MAR-2005 (NG): * Added astAssert * 20-MAY-2005 (DSB): * Modified astAssert so that it does nothing if the AST error * status is already set, and also so that does nothing unless * the DEBUG macro is defined. * 16-FEB-2006 (DSB): * Improve efficiency by replacing the astOK_ function with a macro * which tests the value of status variable. The pointer which points * to the status variable are now global rather than static. * 1-MAR-2006 (DSB): * Remove astAssert. * 19-SEP-2008 (DSB) * Big changes for thread-safe version of AST. *- */ /* Suppress "operands are evaluated in unspecified order" warnings from the Intel icc compiler. These are caused by the astGetStatusPtr_ function being called several times within each of the macros that form the public interface for AST. */ #ifdef __INTEL_COMPILER #pragma warning(disable:981) #endif /* Include files. */ /* ============== */ #if defined(THREAD_SAFE) #include #endif /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) /* Protected */ /* Define a facility number that is unique to this library. The number here * is the facility code assigned to the AST library, but it doesn't have to * be this number -- it only has to be probably unique. If that code were * ever to change, then you can update this number if you feel it's tidier * that way. */ #define AST__FAC (1521) /* Max number of messages which can be deferred when reporting is switched off. */ #define AST__ERROR_MSTACK_SIZE 100 #endif /* This macro expands to an invocation of a specified function, together with a call to astAt to record the file and line number at which the invocation occurs. These are included in public error reports. This is only done for invocations from outside of AST (i.e. public invocations).*/ #if defined(astCLASS) || defined(astFORTRAN77) #define astERROR_INVOKE(function) (function) #else #define astERROR_INVOKE(function) (astAt_(NULL,__FILE__,__LINE__,0,astGetStatusPtr),(function)) #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type definitions */ /* ================ */ /* Define a structure to hold information about an error context. */ typedef struct AstErrorContext { int reporting; /* Value of error reporting flag at start of context */ int ok; /* Was the status value OK at start of context? */ int status; /* The status value at the start of the context */ } AstErrorContext; #if defined(THREAD_SAFE) && ( defined(astCLASS) || defined(astFORTRAN77) ) /* Define a structure holding all data items that are global within the error.c file. */ typedef struct AstErrorGlobals { /* Reporting flag: delivery of message is supressed if zero. */ int Reporting; /* Error context. */ const char *Current_File; /* Current file name pointer */ const char *Current_Routine; /* Current routine name pointer */ int Current_Line; /* Current line number */ int Foreign_Set; /* Have foreign values been set? */ /* Un-reported message stack */ char *Message_Stack[ AST__ERROR_MSTACK_SIZE ]; int Mstack_Size; } AstErrorGlobals; /* Structure to hold the internal status variable, and the status pointer for a single thread. */ typedef struct AstStatusBlock { int internal_status; int *status_ptr; } AstStatusBlock; #endif /* Function Macros. */ /* ================ */ #if defined(astCLASS) /* *+ * Name: * astErrorBegin * Purpose: * Begin a new error reporting context. * Type: * Protected macro. * Synopsis: * #include "error.h" * astErrorBegin( AstErrorContext *context ); * Description: * This macro starts a new error reporting context. It saves any * existing error status in the supplied ontext structure, and then * clears the status value. It also defers further error reporting. * * Each invocation of this macro should be followed (eventually) by a * matching invocation of astErrorEnd. * Parameters: * context * Pointer to a structure in which to to storeinformation about the * current error reporting context. This structure should be passed * unchanged to the corresponding invocation of astErrorEnd. *- */ #define astErrorBegin(context) {\ \ /* Save the original error status value. */ \ (context)->status = astStatus; \ \ /* Save a flag indicating if the original error status was good. */ \ (context)->ok = astOK; \ \ /* Switch off the immediate delivery of error messages, recording the \ original value of the reporting flag. */ \ (context)->reporting = astReporting( 0 ); \ \ /* Clear any existing error condition. */ \ astClearStatus; \ } /* *+ * Name: * astErrorEnd * Purpose: * End an error reporting context. * Type: * Protected macro. * Synopsis: * #include "error.h" * astErrorEnd( AstErrorContext *context ); * Description: * This macro ends an error reporting context started using * astErrorBegin. * * Each invocation of this macro should correspond to an earlier * invocation of astErrorBegin. * Parameters: * context * Pointer to a structure holding information returned by the * matching invocation of astErrorBegin. *- */ #define astErrorEnd(context) { \ \ /* If an error condition existed when astErrorBegin was called, and \ another error has since occurred, clear the deferred messages \ reported during the error context without displaying them. */ \ if( !(context)->ok && !astOK ) astClearStatus; \ \ /* Put the error reporting flag back to its original value. This will \ have the effect of displaying any remaining errors reported within \ the error context (they will already have been cleared if an error \ condition existed at the start of the context). */ \ astReporting( (context)->reporting ); \ \ /* If an error condition existed at the start of the context, re-instate \ the original status value. */ \ if( !(context)->ok ) astSetStatus( (context)->status ); \ } #endif /* Function prototypes. */ /* ==================== */ int *astWatch_( int * ); void astClearStatus_( int * ); int *astGetStatusPtr_( void )__attribute__((pure)); void astAt_( const char *, const char *, int, int, int * ); #if defined(astCLASS) || defined(astFORTRAN77) /* Protected only */ int astReporting_( int, int * ); void astError_( int, const char *, int *, ... )__attribute__((format(printf,2,4))); void astBacktrace_( int * ); #if defined(THREAD_SAFE) void astInitErrorGlobals_( AstErrorGlobals * ); #endif #endif void astErrorPublic_( int, const char *, ... )__attribute__((format(printf,2,3))); /* Function interfaces. */ /* ==================== */ /* These wrap up the functions defined by this module to make them easier to use. */ #define astWatch(status_ptr) astWatch_(status_ptr) #define astGetStatusPtr astGetStatusPtr_() #define astOK (astStatus==0) #define astSetStatus(status_value) (astStatus=(status_value)) #if defined(astCLASS) /* Protected */ #define astAt(routine,file,line) astAt_(routine,file,line,0,status) #define astClearStatus astClearStatus_(status) #define astStatus (*status) #define astError astError_ #define astReporting(report) astReporting_(report,status) #define astBacktrace astBacktrace_(status) #elif defined(astFORTRAN77) #define astAt(routine,file,line) astAt_(routine,file,line,1,STATUS) #define astClearStatus astClearStatus_(status) #define astStatus (*status) #define astError astError_ #define astReporting(report) astReporting_(report,status) #else #define astAt(routine,file,line) astAt_(routine,file,line,1,astGetStatusPtr) #define astClearStatus astClearStatus_(astGetStatusPtr) #define astStatus (*astGetStatusPtr) #define astError astErrorPublic_ #endif #endif ast-8.3.0/skyframe.c0000664000175000017500000150572413004147321011232 00000000000000/* *class++ * Name: * SkyFrame * Purpose: * Celestial coordinate system description. * Constructor Function: c astSkyFrame f AST_SKYFRAME * Description: * A SkyFrame is a specialised form of Frame which describes * celestial longitude/latitude coordinate systems. The particular * celestial coordinate system to be represented is specified by * setting the SkyFrame's System attribute (currently, the default * is ICRS) qualified, as necessary, by a mean Equinox value and/or * an Epoch. * * For each of the supported celestial coordinate systems, a SkyFrame * can apply an optional shift of origin to create a coordinate system * representing offsets within the celestial coordinate system from some * specified reference point. This offset coordinate system can also be * rotated to define new longitude and latitude axes. See attributes * SkyRef, SkyRefIs, SkyRefP and AlignOffset. * * All the coordinate values used by a SkyFrame are in * radians. These may be formatted in more conventional ways for c display by using astFormat. f display by using AST_FORMAT. * For a SkyFrame, the Unit attribute describes the formatted value of * a SkyFrame axis, and may for instance be "h:m:s", indicating that a * formatted axis value contains colon-separated fields for hours, minutes * and seconds. On the other hand, the InternalUnit attribute for a * SkyFrame is always set to "rad" (i.e. radians), indicating that the * unformatted (i.e. floating point) axis values used by application code * are always in units of radians * Inheritance: * The SkyFrame class inherits from the Frame class. * Attributes: * In addition to those attributes common to all Frames, every * SkyFrame also has the following attributes: * * - AlignOffset: Align SkyFrames using the offset coordinate system? * - AsTime(axis): Format celestial coordinates as times? * - Equinox: Epoch of the mean equinox * - IsLatAxis: Is the specified axis the latitude axis? * - IsLonAxis: Is the specified axis the longitude axis? * - LatAxis: Index of the latitude axis * - LonAxis: Index of the longitude axis * - NegLon: Display longitude values in the range [-pi,pi]? * - Projection: Sky projection description. * - SkyRef: Position defining location of the offset coordinate system * - SkyRefIs: Selects the nature of the offset coordinate system * - SkyRefP: Position defining orientation of the offset coordinate system * - SkyTol: Smallest significant shift in sky coordinates * Functions: * In addition to those c functions f routines * applicable to all Frames, the following c functions f routines * may also be applied to all SkyFrames: * c - astSkyOffsetMap: Obtain a Mapping from absolute to offset coordinates f - AST_SKYOFFSETMAP: Obtain a Mapping from absolute to offset coordinates * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * BEC: Brad Cavanagh (JAC, Hawaii) * History: * 4-MAR-1996 (RFWS): * Original version. * 17-MAY-1996 (RFWS): * Tidied up, etc. * 31-JUL-1996 (RFWS): * Added support for attributes and a public interface. * 11-SEP-1996 (RFWS): * Added Gap (written by DSB). * 24-SEP-1996 (RFWS): * Added I/O facilities. * 27-FEB-1997 (RFWS): * Improved the public prologues. * 27-MAY-1997 (RFWS): * Modified to use a new public interface to the SlaMap class * and to use the astSimplify method to remove redundant * conversions. * 16-JUN-1997 (RFWS): * Fixed bug in axis associations returned by astMatch if axes * were swapped. * 16-JUL-1997 (RFWS): * Added Projection attribute. * 14-NOV-1997 (RFWS): * Corrected the omission of axis permutations from astNorm. * 21-JAN-1998 (RFWS): * Ensure that Title and Domain values appropriate to a SkyFrame * are preserved if a Frame result is generated by SubFrame. * 26-FEB-1998 (RFWS): * Over-ride the astUnformat method. * 3-APR-2001 (DSB): * Added "Unknown" option for the System attribute. Added read-only * attributes LatAxis and LonAxis. * 21-JUN-2001 (DSB): * Added astAngle and astOffset2. * 4-SEP-2001 (DSB): * Added NegLon attribute, and astResolve method. * 9-SEP-2001 (DSB): * Added astBear method. * 21-SEP-2001 (DSB): * Removed astBear method. * 10-OCT-2002 (DSB): * Moved definitions of macros for SkyFrame system values from * this file into skyframe.h. * 24-OCT-2002 (DSB): * Modified MakeSkyMapping so that any two SkyFrames with system=unknown * are assumed to be related by a UnitMap. previously, they were * considered to be unrelated, resulting in no ability to convert from * one to the other. This could result for instance in astConvert * being unable to find a maping from a SkyFrame to itself. * 15-NOV-2002 (DSB): * Moved System and Epoch attributes to the Frame class. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitSkyFrameVtab * method. * 11-JUN-2003 (DSB): * Added ICRS option for System attribute, and made it the default * in place of FK5. * 27-SEP-2003 (DSB): * Added HELIOECLIPTIC option for System attribute. * 19-APR-2004 (DSB): * Added SkyRef, SkyRefIs, SkyRefP and AlignOffset attributes. * 8-SEP-2004 (DSB): * Added astResolvePoints method. * 2-DEC-2004 (DSB): * Added System "J2000" * 27-JAN-2005 (DSB): * Fix memory leaks in astLoadSkyFrame_ and Match. * 7-APR-2005 (DSB): * Allow SkyRefIs to be set to "Ignored". * 12-MAY-2005 (DSB): * Override astNormBox method. * 15-AUG-2005 (DSB): * Added AZEL system. * 13-SEP-2005 (DSB): * Override astClearSystem so that SkyRef/SkyRefPcan be converted * from the original System to the default System. * 19-SEP-2005 (DSB): * Changed default for SkyRefIs from ORIGIN to IGNORED. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 22-FEB-2006 (DSB): * Store the Local Apparent Sidereal Time in the SkyFrame structure * in order to avoid expensive re-computations. * 22-AUG-2006 (DSB): * Ensure the cached Local Apparent Siderial Time is initialised * when initialising or loading a SkyFrame. * 22-SEP-2006 (DSB): * Report an error in SetSystem if it is not possible to convert * from old to new systems. * 3-OCT-2006 (DSB): * Added Equation of Equinoxes to the SkyFrame structure. * 6-OCT-2006 (DSB): * - Guard against annulling null pointers in subFrame. * - Add Dut1 attribute * - Use linear approximation for LAST over short periods (less * than 0.001 of a day) * - Remove Equation of Equinoxes from the SkyFrame structure. * 10-OCT-2006 (DSB): * Use "AlOff" instead of "AlignOffset" as the external channel name * for the AlignOffset attribute. The longer form exceeded the * limit that can be used by the Channel class. * 14-OCT-2006 (DSB): * - Move Dut1 attribute to the Frame class. * - Use the TimeFrame class to do the TDB->LAST conversions. * 17-JAN-2007 (DSB): * - Use a UnitMap to align offset coordinate systems in two * SkyFrames, regardless of other attribute values. * - Only align in offset coordinates if both target and template * have a non-zero value for AlignOffset. * 23-JAN-2007 (DSB): * Modified so that a SkyFrame can be used as a template to find a * SkyFrame contained within a CmpFrame. This involves changes in * Match and the removal of the local versions of SetMaxAxes and * SetMinAxes. * 4-JUL-2007 (DSB): * Modified GetLast to use the correct solar to sidereal conversion * factor. As a consequence the largest acceptable epoch gap before * the LAST needs to be recalculated has been increased. * 11-JUL-2007 (DSB): * Override astSetEpoch and astClearEpoch by implementations which * update the LAST value stored in the SkyFrame. * 7-AUG-2007 (DSB): * - Set a value for the CentreZero attribute when extracting a * SkyAxis from a SkyFrame in function SubFrame. * - In SubFrame, clear extended attributes such as System after * all axis attributes have been "fixated. * 30-AUG-2007 (DSB): * Override astSetDut1 and astClearDut1 by implementations which * update the LAST value stored in the SkyFrame. * 31-AUG-2007 (DSB): * - Cache the magnitude of the diurnal aberration vector in the * SkyFrame structure for use when correcting for diurnal aberration. * - Modify the azel conversions to include correction for diurnal * aberration. * - Override astClearObsLat and astSetObsLat by implementations which * reset the magnitude of the diurnal aberration vector. * 3-SEP-2007 (DSB): * In SubFrame, since AlignSystem is extended by the SkyFrame class * it needs to be cleared before invoking the parent SubFrame * method in cases where the result Frame is not a SkyFrame. * 2-OCT-2007 (DSB): * In Overlay, clear AlignSystem as well as System before calling * the parent overlay method. * 10-OCT-2007 (DSB): * In MakeSkyMapping, correct the usage of variables "system" and * "align_sys" when aligning in AZEL. * 18-OCT-2007 (DSB): * Compare target and template AlignSystem values in Match, rather * than comparing target and result AlignSystem values in MakeSkyMapping * (since result is basically a copy of target). * 27-NOV-2007 (DSB): * - Modify SetSystem to ensure that SkyRef and SkyRefP position are * always transformed as absolute values, rather than as offset * values. * - Modify SubMatch so that a value of zero is assumed for * AlignOffset when restoring thre integrity of a FrameSet. * 15-DEC-2008 (DSB): * Improve calculation of approximate Local Apparent Sidereal time * by finding and using the ratio of solar to sidereal time * independently for each approximation period. * 14-JAN-2009 (DSB): * Override the astIntersect method. * 21-JAN-2009 (DSB): * Fix mis-use of results buffers for GetFormat and GetAttrib. * 16-JUN-2009 (DSB): * All sky coordinate systems currently supported by SkyFrame are * left handed. So fix GetDirection method to return zero for all * longitude axes and 1 for all latitude axes. * 18-JUN-2009 (DSB): * Incorporate the new ObsAlt attribute. * 23-SEP-2009 (DSB): * Allow some rounding error when checking for changes in SetObsLon * and SetDut1. This reduces the number of times the expensive * calculation of LAST is performed. * 24-SEP-2009 (DSB); * Create a static cache of LAST values stored in the class virtual * function table. These are used in preference to calculating a new * value from scratch. * 25-SEP-2009 (DSB); * Do not calculate LAST until it is needed. * 12-OCT-2009 (DSB); * - Handle 2.PI->0 discontinuity in cached LAST values. * 12-OCT-2009 (BEC); * - Fix bug in caching LAST value. * 31-OCT-2009 (DSB); * Correct SetCachedLAST to handle cases where the epoch to be * stored is smaller than any epoch already in the table. * 24-NOV-2009 (DSB): * - In CalcLast, only use end values form the table of stored * LAST values if the corresponding epochs are within 0.001 of * a second of the required epoch (this tolerance used to be * 0.1 seconds). * - Do not clear the cached LAST value in SetEpoch and ClearEpoch. * 8-MAR-2010 (DSB): * Add astSkyOffsetMap method. * 7-APR-2010 (DSB): * Add IsLatAxis and IsLonAxis attributes. * 11-MAY-2010 (DSB): * In SetSystem, clear SkyRefP as well as SkyRef. * 22-MAR-2011 (DSB): * Override astFrameGrid method. * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. * 23-MAY-2011 (DSB): * Truncate returned PointSet in function FrameGrid to exclude unused points. * 24-MAY-2011 (DSB): * When clearing or setting the System attribute, clear SkyRef rather * than reporting an error if the Mapping from the old System to the * new System is unknown. * 30-NOV-2011 (DSB): * When aligning two SkyFrames in the system specified by AlignSystem, * do not assume inappropriate default equinox values for systems * that are not referred to the equinox specified by the Equinox attribute. * 26-APR-2012 (DSB): * - Correct Dump function so that any axis permutation is taken into * account when dumping SkyFrame attributes that have a separate value * for each axis (e.g. SkyRef and SkyRefP). * - Take axis permutation into account when setting a new value * for attributes that have a separate value for each axis (e.g. * SkyRef and SkyRefP). * - Remove the code that overrides ClearEpoch and SetEpoch (these * overrides have not been needed since the changes made on * 24/11/2009). * 27-APR-2012 (DSB): * - Correct astLoadSkyFrame function so that any axis permutation is * taken into account when loading SkyFrame attributes that have a * separate value for each axis. * 25-JUL-2013 (DSB): * Use a single table of cached LAST values for all threads, rather * than a separate table for each thread. The problem with a table per * thread is that if you have N threads, each table contains only * one N'th of the total number of cached values, resulting in * poorer accuracy, and small variations in interpolated LAST value * depending on the way the cached values are distributed amongst the * N threads. * 6-AST-2013 (DSB): * Fix the use of the read-write lock that is used to serialise * access to the table of cached LAST values. This bug could * cause occasional problems where an AST pointer would became * invalid for no apparent reason. * 21-FEB-2014 (DSB): * Rounding errors in the SkyLineDef constructor could result in the line * between coincident points being given a non-zero length. * 6-JUL-2015 (DSB): * Added SkyTol attribute. *class-- */ /* Module Macros. */ /* ============== */ /* Set the name of the class we are implementing. This indicates to the header files that define class interfaces that they should make "protected" symbols available. */ #define astCLASS SkyFrame /* Define the first and last acceptable System values. */ #define FIRST_SYSTEM AST__FK4 #define LAST_SYSTEM AST__AZEL /* Speed of light (AU per day) (from SLA_AOPPA) */ #define C 173.14463331 /* Ratio between solar and sidereal time (from SLA_AOPPA) */ #define SOLSID 1.00273790935 /* Define values for the different values of the SkyRefIs attribute. */ #define POLE_STRING "Pole" #define ORIGIN_STRING "Origin" #define IGNORED_STRING "Ignored" /* Define other numerical constants for use in this module. */ #define GETATTRIB_BUFF_LEN 200 #define GETFORMAT_BUFF_LEN 50 #define GETLABEL_BUFF_LEN 40 #define GETSYMBOL_BUFF_LEN 20 #define GETTITLE_BUFF_LEN 200 /* A macro which returns a flag indicating if the supplied system is references to the equinox specified by the Equinox attribute. */ #define EQREF(system) \ ((system==AST__FK4||system==AST__FK4_NO_E||system==AST__FK5||system==AST__ECLIPTIC)?1:0) /* * * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "skyframe.h" * MAKE_CLEAR(attr,component,assign,nval) * Class Membership: * Defined by the SkyFrame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstSkyFrame *this, int axis ) * * and an external interface function of the form: * * void astClear_( AstSkyFrame *this, int axis ) * * which implement a method for clearing a single value in a specified * multi-valued attribute for an axis of a SkyFrame. * Parameters: * attr * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabelAt"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_CLEAR(attr,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attr( AstSkyFrame *this, int axis, int *status ) { \ \ int axis_p; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate and permute the axis index. */ \ axis_p = astValidateAxis( this, axis, 1, "astClear" #attr ); \ \ /* Assign the "clear" value. */ \ if( astOK ) { \ this->component[ axis_p ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attr##_( AstSkyFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,SkyFrame,Clear##attr))( this, axis, status ); \ } /* * * Name: * MAKE_GET * Purpose: * Implement a method to get a single value in a multi-valued attribute. * Type: * Private macro. * Synopsis: * #include "skyframe.h" * MAKE_GET(attr,type,bad_value,assign,nval) * Class Membership: * Defined by the SkyFrame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstSkyFrame *this, int axis ) * * and an external interface function of the form: * * astGet_( AstSkyFrame *this, int axis ) * * which implement a method for getting a single value from a specified * multi-valued attribute for an axis of a SkyFrame. * Parameters: * attr * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. This can * use the string "axis" to represent the zero-based value index. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. * */ /* Define the macro. */ #define MAKE_GET(attr,type,bad_value,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attr( AstSkyFrame *this, int axis, int *status ) { \ int axis_p; /* Permuted axis index */ \ type result; /* Result to be returned */ \ \ /* Initialise */\ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate and permute the axis index. */ \ axis_p = astValidateAxis( this, axis, 1, "astGet" #attr ); \ \ /* Assign the result value. */ \ if( astOK ) { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attr##_( AstSkyFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,SkyFrame,Get##attr))( this, axis, status ); \ } /* * * Name: * MAKE_SET * Purpose: * Implement a method to set a single value in a multi-valued attribute * for a SkyFrame. * Type: * Private macro. * Synopsis: * #include "skyframe.h" * MAKE_SET(attr,type,component,assign,nval) * Class Membership: * Defined by the SkyFrame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstSkyFrame *this, int axis, value ) * * and an external interface function of the form: * * void astSet_( AstSkyFrame *this, int axis, value ) * * which implement a method for setting a single value in a specified * multi-valued attribute for a SkyFrame. * Parameters: * attr * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabelAt"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_SET(attr,type,component,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attr( AstSkyFrame *this, int axis, type value, int *status ) { \ \ int axis_p; \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate and permute the axis index. */ \ axis_p = astValidateAxis( this, axis, 1, "astSet" #attr ); \ \ /* Store the new value in the structure component. */ \ if( astOK ) { \ this->component[ axis_p ] = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attr##_( AstSkyFrame *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,SkyFrame,Set##attr))( this, axis, value, status ); \ } /* * * Name: * MAKE_TEST * Purpose: * Implement a method to test if a single value has been set in a * multi-valued attribute for a class. * Type: * Private macro. * Synopsis: * #include "skyframe.h" * MAKE_TEST(attr,assign,nval) * Class Membership: * Defined by the SkyFrame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( AstSkyFrame *this, int axis ) * * and an external interface function of the form: * * int astTest_( AstSkyFrame *this, int axis ) * * which implement a method for testing if a single value in a specified * multi-valued attribute has been set for a class. * Parameters: * attr * The name of the attribute to be tested, as it appears in the function * name (e.g. Label in "astTestLabelAt"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. This can use the string "axis" to represent the zero-based * index of the value within the attribute. * nval * Specifies the number of values in the multi-valued attribute. The * "axis" values supplied to the created function should be in the * range zero to (nval - 1). * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define MAKE_TEST(attr,assign,nval) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attr( AstSkyFrame *this, int axis, int *status ) { \ int result; /* Value to return */ \ int axis_p; /* Permuted axis index */ \ \ /* Initialise */ \ result =0; \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate and permute the axis index. */ \ axis_p = astValidateAxis( this, axis, 1, "astTest" #attr ); \ \ /* Assign the result value. */ \ if( astOK ) { \ result = (assign); \ } \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attr##_( AstSkyFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,SkyFrame,Test##attr))( this, axis, status ); \ } /* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "globals.h" /* Thread-safe global data access */ #include "object.h" /* Base Object class */ #include "pointset.h" /* Sets of points (for AST__BAD) */ #include "unitmap.h" /* Unit Mappings */ #include "permmap.h" /* Coordinate permutations */ #include "cmpmap.h" /* Compound Mappings */ #include "slamap.h" /* SLALIB sky coordinate Mappings */ #include "timemap.h" /* Time conversions */ #include "skyaxis.h" /* Sky axes */ #include "frame.h" /* Parent Frame class */ #include "matrixmap.h" /* Matrix multiplication */ #include "sphmap.h" /* Cartesian<->Spherical transformations */ #include "skyframe.h" /* Interface definition for this class */ #include "pal.h" /* SLALIB library interface */ #include "wcsmap.h" /* Factors of PI */ #include "timeframe.h" /* Time system transformations */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* Type Definitions. */ /* ================= */ /* Cached Line structure. */ /* ---------------------- */ /* This structure contains information describing a line segment within a SkyFrame. It differs from the AstLineDef defined in frame.h because positions are represented by 3D (x,y,z) cartesian coords rather than 2D (long,lat) coords. */ typedef struct SkyLineDef { AstFrame *frame; /* Pointer to Frame in which the line is defined */ double length; /* Line length */ int infinite; /* Disregard the start and end of the line? */ double start[3]; /* Unit vector defining start of line */ double end[3]; /* Unit vector defining end of line */ double dir[3]; /* Unit vector defining line direction */ double q[3]; /* Unit vector perpendicular to line */ double start_2d[2]; double end_2d[2]; } SkyLineDef; /* 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 used or extended by this class. */ static AstSystemType (* parent_getalignsystem)( AstFrame *, int * ); static AstSystemType (* parent_getsystem)( AstFrame *, int * ); static const char *(* parent_format)( AstFrame *, int, double, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static const char *(* parent_getdomain)( AstFrame *, int * ); static const char *(* parent_getformat)( AstFrame *, int, int * ); static const char *(* parent_getlabel)( AstFrame *, int, int * ); static const char *(* parent_getsymbol)( AstFrame *, int, int * ); static const char *(* parent_gettitle)( AstFrame *, int * ); static const char *(* parent_getunit)( AstFrame *, int, int * ); static double (* parent_gap)( AstFrame *, int, double, int *, int * ); static double (* parent_getbottom)( AstFrame *, int, int * ); static double (* parent_getepoch)( AstFrame *, int * ); static double (* parent_gettop)( AstFrame *, int, int * ); static int (* parent_getdirection)( AstFrame *, int, int * ); static int (* parent_getobjsize)( AstObject *, int * ); static int (* parent_match)( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int (* parent_subframe)( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static int (* parent_testformat)( AstFrame *, int, int * ); static int (* parent_unformat)( AstFrame *, int, const char *, double *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_cleardut1)( AstFrame *, int * ); static void (* parent_clearformat)( AstFrame *, int, int * ); static void (* parent_clearobsalt)( AstFrame *, int * ); static void (* parent_clearobslat)( AstFrame *, int * ); static void (* parent_clearobslon)( AstFrame *, int * ); static void (* parent_clearsystem)( AstFrame *, int * ); static void (* parent_overlay)( AstFrame *, const int *, AstFrame *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_setdut1)( AstFrame *, double, int * ); static void (* parent_setformat)( AstFrame *, int, const char *, int * ); static void (* parent_setobsalt)( AstFrame *, double, int * ); static void (* parent_setobslat)( AstFrame *, double, int * ); static void (* parent_setobslon)( AstFrame *, double, int * ); static void (* parent_setsystem)( AstFrame *, AstSystemType, int * ); /* Factors for converting between hours, degrees and radians. */ static double hr2rad; static double deg2rad; static double pi; static double piby2; /* Table of cached Local Apparent Sidereal Time values and corresponding epochs. */ static int nlast_tables = 0; static AstSkyLastTable **last_tables = NULL; /* 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->GetFormat_Buff[ 0 ] = 0; \ globals->GetLabel_Buff[ 0 ] = 0; \ globals->GetSymbol_Buff[ 0 ] = 0; \ globals->GetTitle_Buff[ 0 ] = 0; \ globals->GetTitle_Buff2[ 0 ] = 0; \ globals->TDBFrame = NULL; \ globals->LASTFrame = NULL; \ /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SkyFrame) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SkyFrame,Class_Init) #define class_vtab astGLOBAL(SkyFrame,Class_Vtab) #define getattrib_buff astGLOBAL(SkyFrame,GetAttrib_Buff) #define getformat_buff astGLOBAL(SkyFrame,GetFormat_Buff) #define getlabel_buff astGLOBAL(SkyFrame,GetLabel_Buff) #define getsymbol_buff astGLOBAL(SkyFrame,GetSymbol_Buff) #define gettitle_buff astGLOBAL(SkyFrame,GetTitle_Buff) #define gettitle_buff2 astGLOBAL(SkyFrame,GetTitle_Buff2) #define tdbframe astGLOBAL(SkyFrame,TDBFrame) #define lastframe astGLOBAL(SkyFrame,LASTFrame) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); /* A read-write lock used to protect the table of cached LAST values so that multiple threads can read simultaneously so long as no threads are writing to the table. */ static pthread_rwlock_t rwlock1=PTHREAD_RWLOCK_INITIALIZER; #define LOCK_WLOCK1 pthread_rwlock_wrlock( &rwlock1 ); #define LOCK_RLOCK1 pthread_rwlock_rdlock( &rwlock1 ); #define UNLOCK_RWLOCK1 pthread_rwlock_unlock( &rwlock1 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffer returned by GetAttrib. */ static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ]; /* Buffer returned by GetFormat. */ static char getformat_buff[ GETFORMAT_BUFF_LEN + 1 ]; /* Default GetLabel string buffer */ static char getlabel_buff[ GETLABEL_BUFF_LEN + 1 ]; /* Default GetSymbol buffer */ static char getsymbol_buff[ GETSYMBOL_BUFF_LEN + 1 ]; /* Default Title string buffer */ static char gettitle_buff[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; static char gettitle_buff2[ AST__SKYFRAME_GETTITLE_BUFF_LEN + 1 ]; /* TimeFrames for doing TDB<->LAST conversions. */ static AstTimeFrame *tdbframe = NULL; static AstTimeFrame *lastframe = NULL; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSkyFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #define LOCK_WLOCK1 #define LOCK_RLOCK1 #define UNLOCK_RWLOCK1 #endif /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstLineDef *LineDef( AstFrame *, const double[2], const double[2], int * ); static AstMapping *SkyOffsetMap( AstSkyFrame *, int * ); static AstPointSet *FrameGrid( AstFrame *, int, const double *, const double *, int * ); static AstPointSet *ResolvePoints( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); static AstSystemType GetAlignSystem( AstFrame *, int * ); static AstSystemType GetSystem( AstFrame *, int * ); static AstSystemType SystemCode( AstFrame *, const char *, int * ); static AstSystemType ValidateSystem( AstFrame *, AstSystemType, 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 *GetProjection( AstSkyFrame *, int * ); static const char *GetSymbol( AstFrame *, int, int * ); static const char *GetTitle( AstFrame *, int * ); static const char *GetUnit( AstFrame *, int, int * ); static const char *SystemString( AstFrame *, AstSystemType, int * ); static double Angle( AstFrame *, const double[], const double[], const double[], int * ); static double CalcLAST( AstSkyFrame *, double, double, double, double, double, int * ); static double Distance( AstFrame *, const double[], const double[], int * ); static double Gap( AstFrame *, int, double, int *, int * ); static double GetBottom( AstFrame *, int, int * ); static double GetCachedLAST( AstSkyFrame *, double, double, double, double, double, int * ); static double GetEpoch( AstFrame *, int * ); static double GetEquinox( AstSkyFrame *, int * ); static void SetCachedLAST( AstSkyFrame *, double, double, double, double, double, double, int * ); static void SetLast( AstSkyFrame *, int * ); static double GetTop( AstFrame *, int, int * ); static double Offset2( AstFrame *, const double[2], double, double, double[2], int * ); static double GetDiurab( AstSkyFrame *, int * ); static double GetLAST( AstSkyFrame *, int * ); static int GetActiveUnit( AstFrame *, int * ); static int GetAsTime( AstSkyFrame *, int, int * ); static int GetDirection( AstFrame *, int, int * ); static int GetIsLatAxis( AstSkyFrame *, int, int * ); static int GetIsLonAxis( AstSkyFrame *, int, int * ); static int GetLatAxis( AstSkyFrame *, int * ); static int GetLonAxis( AstSkyFrame *, int * ); static int GetNegLon( AstSkyFrame *, int * ); static int GetObjSize( AstObject *, int * ); static int IsEquatorial( AstSystemType, int * ); static int LineContains( AstFrame *, AstLineDef *, int, double *, int * ); static int LineCrossing( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); static int LineIncludes( SkyLineDef *, double[3], int * ); static int MakeSkyMapping( AstSkyFrame *, AstSkyFrame *, AstSystemType, AstMapping **, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int TestActiveUnit( AstFrame *, int * ); static int TestAsTime( AstSkyFrame *, int, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestEquinox( AstSkyFrame *, int * ); static int TestNegLon( AstSkyFrame *, int * ); static int TestProjection( AstSkyFrame *, int * ); static int TestSlaUnit( AstSkyFrame *, AstSkyFrame *, AstSlaMap *, int * ); static int Unformat( AstFrame *, int, const char *, double *, int * ); static void ClearAsTime( AstSkyFrame *, int, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearDut1( AstFrame *, int * ); static void ClearEquinox( AstSkyFrame *, int * ); static void ClearNegLon( AstSkyFrame *, int * ); static void ClearObsAlt( AstFrame *, int * ); static void ClearObsLat( AstFrame *, int * ); static void ClearObsLon( AstFrame *, int * ); static void ClearProjection( AstSkyFrame *, int * ); static void ClearSystem( AstFrame *, 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 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 Resolve( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); static void SetAsTime( AstSkyFrame *, int, int, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetDut1( AstFrame *, double, int * ); static void SetEquinox( AstSkyFrame *, double, int * ); static void SetNegLon( AstSkyFrame *, int, int * ); static void SetObsAlt( AstFrame *, double, int * ); static void SetObsLat( AstFrame *, double, int * ); static void SetObsLon( AstFrame *, double, int * ); static void SetProjection( AstSkyFrame *, const char *, int * ); static void SetSystem( AstFrame *, AstSystemType, int * ); static void Shapp( double, double *, double *, double, double *, int * ); static void Shcal( double, double, double, double *, double *, int * ); static void VerifyMSMAttrs( AstSkyFrame *, AstSkyFrame *, int, const char *, const char *, int * ); static double GetSkyRef( AstSkyFrame *, int, int * ); static int TestSkyRef( AstSkyFrame *, int, int * ); static void SetSkyRef( AstSkyFrame *, int, double, int * ); static void ClearSkyRef( AstSkyFrame *, int, int * ); static double GetSkyRefP( AstSkyFrame *, int, int * ); static int TestSkyRefP( AstSkyFrame *, int, int * ); static void SetSkyRefP( AstSkyFrame *, int, double, int * ); static void ClearSkyRefP( AstSkyFrame *, int, int * ); static int GetSkyRefIs( AstSkyFrame *, int * ); static int TestSkyRefIs( AstSkyFrame *, int * ); static void SetSkyRefIs( AstSkyFrame *, int, int * ); static void ClearSkyRefIs( AstSkyFrame *, int * ); static int GetAlignOffset( AstSkyFrame *, int * ); static int TestAlignOffset( AstSkyFrame *, int * ); static void SetAlignOffset( AstSkyFrame *, int, int * ); static void ClearAlignOffset( AstSkyFrame *, int * ); static double GetSkyTol( AstSkyFrame *, int * ); static int TestSkyTol( AstSkyFrame *, int * ); static void SetSkyTol( AstSkyFrame *, double, int * ); static void ClearSkyTol( AstSkyFrame *, int * ); /* Member functions. */ /* ================= */ 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 "skyframe.h" * double Angle( AstFrame *this_frame, const double a[], * const double b[], const double c[], int *status ) * Class Membership: * SkyFrame member function (over-rides the 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 (great circles). * Parameters: * this * Pointer to the SkyFrame. * a * An array of double, with one element for each SkyFrame axis, * containing the coordinates of the first point. * b * An array of double, with one element for each SkyFrame axis, * containing the coordinates of the second point. * c * An array of double, with one element for each SkyFrame axis, * containing the coordinates of the third point. * status * Pointer to the inherited status variable. * Returned Value: * The angle in radians, from the line AB to the line CB, in * the range $\pm \pi$ with positive rotation is in the same sense * as rotation from axis 2 to axis 1. * 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 points A and B are * co-incident, or if points B and C are co-incident. * - 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. */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ const int *perm; /* Axis permutation array */ double aa[ 2 ]; /* Permuted a coordinates */ double anga; /* Angle from north to the line BA */ double angc; /* Angle from north to the line BC */ double bb[ 2 ]; /* Permuted b coordinates */ double cc[ 2 ]; /* Permuted c coordinates */ double result; /* Value to return */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Check that all supplied coordinates are OK. */ if ( ( a[ 0 ] != AST__BAD ) && ( a[ 1 ] != AST__BAD ) && ( b[ 0 ] != AST__BAD ) && ( b[ 1 ] != AST__BAD ) && ( c[ 0 ] != AST__BAD ) && ( c[ 1 ] != AST__BAD ) ) { /* Apply the axis permutation array to obtain the coordinates of the three points in the required (longitude,latitude) order. */ aa[ perm[ 0 ] ] = a[ 0 ]; aa[ perm[ 1 ] ] = a[ 1 ]; bb[ perm[ 0 ] ] = b[ 0 ]; bb[ perm[ 1 ] ] = b[ 1 ]; cc[ perm[ 0 ] ] = c[ 0 ]; cc[ perm[ 1 ] ] = c[ 1 ]; /* Check that A and B are not co-incident. */ if( aa[ 0 ] != bb[ 0 ] || aa[ 1 ] != bb[ 1 ] ) { /* Check that C and B are not co-incident. */ if( cc[ 0 ] != bb[ 0 ] || cc[ 1 ] != bb[ 1 ] ) { /* Find the angle from north to the line BA. */ anga = palDbear( bb[ 0 ], bb[ 1 ], aa[ 0 ], aa[ 1 ] ); /* Find the angle from north to the line BC. */ angc = palDbear( bb[ 0 ], bb[ 1 ], cc[ 0 ], cc[ 1 ] ); /* Find the difference. */ result = angc - anga; /* This value is the angle from north, but we want the angle from axis 2. If the axes have been swapped so that axis 2 is actually the longitude axis, then we need to correct this result. */ if( perm[ 0 ] != 0 ) result = piby2 - result; /* Fold the result into the range +/- PI. */ result = palDrange( result ); } } } } /* Return the result. */ return result; } static double CalcLAST( AstSkyFrame *this, double epoch, double obslon, double obslat, double obsalt, double dut1, int *status ) { /* * Name: * CalcLAST * Purpose: * Calculate the Local Appearent Sidereal Time for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double CalcLAST( AstSkyFrame *this, double epoch, double obslon, * double obslat, double obsalt, double dut1, * int *status ) * Class Membership: * SkyFrame member function. * Description: * This function calculates and returns the Local Apparent Sidereal Time * at the given epoch, etc. * Parameters: * this * Pointer to the SkyFrame. * epoch * The epoch (MJD). * obslon * Observatory geodetic longitude (radians) * obslat * Observatory geodetic latitude (radians) * obsalt * Observatory geodetic altitude (metres) * dut1 * The UT1-UTC correction, in seconds. * status * Pointer to the inherited status variable. * Returned Value: * The Local Apparent Sidereal Time, in radians. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstFrameSet *fs; /* Mapping from TDB offset to LAST offset */ double epoch0; /* Supplied epoch value */ double result; /* Returned LAST value */ /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* See if the required LAST value can be determined from the cached LAST values in the SkyFrame virtual function table. */ result = GetCachedLAST( this, epoch, obslon, obslat, obsalt, dut1, status ); /* If not, we do an exact calculation from scratch. */ if( result == AST__BAD ) { /* If not yet done, create two TimeFrames. Note, this is done here rather than in astInitSkyFrameVtab in order to avoid infinite vtab initialisation loops (caused by the TimeFrame class containing a static SkyFrame). */ if( ! tdbframe ) { astBeginPM; tdbframe = astTimeFrame( "system=mjd,timescale=tdb", status ); lastframe = astTimeFrame( "system=mjd,timescale=last", status ); astEndPM; } /* For better accuracy, use this integer part of the epoch as the origin of the two TimeFrames. */ astSetTimeOrigin( tdbframe, (int) epoch ); astSetTimeOrigin( lastframe, (int) epoch ); /* Convert the absolute Epoch value to an offset from the above origin. */ epoch0 = epoch; epoch -= (int) epoch; /* Store the observers position in the two TimeFrames. */ astSetObsLon( tdbframe, obslon ); astSetObsLon( lastframe, obslon ); astSetObsLat( tdbframe, obslat ); astSetObsLat( lastframe, obslat ); astSetObsAlt( tdbframe, obsalt ); astSetObsAlt( lastframe, obsalt ); /* Store the DUT1 value. */ astSetDut1( tdbframe, dut1 ); astSetDut1( lastframe, dut1 ); /* Get the conversion from tdb mjd offset to last mjd offset. */ fs = astConvert( tdbframe, lastframe, "" ); /* Use it to transform the SkyFrame Epoch from TDB offset to LAST offset. */ astTran1( fs, 1, &epoch, 1, &epoch ); fs = astAnnul( fs ); /* Convert the LAST offset from days to radians. */ result = ( epoch - (int) epoch )*2*AST__DPI; /* Cache the new LAST value in the SkyFrame virtual function table. */ SetCachedLAST( this, result, epoch0, obslon, obslat, obsalt, dut1, status ); } /* Return the required LAST value. */ return result; } static void ClearAsTime( AstSkyFrame *this, int axis, int *status ) { /* * Name: * ClearAsTime * Purpose: * Clear the value of the AsTime attribute for a SkyFrame's axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearAsTime( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function clears any value that has been set for the AsTime * attribute for a specified axis of a SkyFrame. This attribute indicates * whether axis values should be formatted as times (as opposed to angles) * by default. * Parameters: * this * Pointer to the SkyFrame. * axis * Index of the axis for which the value is to be cleared (zero based). * status * Pointer to the inherited status variable. * Returned Value: * void. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astClearAsTime" ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis ); /* If the Axis is a SkyAxis, clear the AsTime attribute (if it is not a SkyAxis, it will not have this attribute anyway). */ if ( astIsASkyAxis( ax ) ) astClearAxisAsTime( ax ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyFrame 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 * SkyFrame, so that the default value will subsequently be used. * Parameters: * this * Pointer to the SkyFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ int axis; /* SkyFrame axis number */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* AsTime(axis). */ /* ------------- */ if ( nc = 0, ( 1 == astSscanf( attrib, "astime(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearAsTime( this, axis - 1 ); /* Equinox. */ /* -------- */ } else if ( !strcmp( attrib, "equinox" ) ) { astClearEquinox( this ); /* NegLon. */ /* ------- */ } else if ( !strcmp( attrib, "neglon" ) ) { astClearNegLon( this ); /* Projection. */ /* ----------- */ } else if ( !strcmp( attrib, "projection" ) ) { astClearProjection( this ); /* SkyRef. */ /* ------- */ } else if ( !strcmp( attrib, "skyref" ) ) { astClearSkyRef( this, 0 ); astClearSkyRef( this, 1 ); /* SkyTol. */ /* ------- */ } else if ( !strcmp( attrib, "skytol" ) ) { astClearSkyTol( this ); /* SkyRef(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyref(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearSkyRef( this, axis - 1 ); /* SkyRefP. */ /* -------- */ } else if ( !strcmp( attrib, "skyrefp" ) ) { astClearSkyRefP( this, 0 ); astClearSkyRefP( this, 1 ); /* SkyRefP(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyrefp(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearSkyRefP( this, axis - 1 ); /* SkyRefIs. */ /* --------- */ } else if ( !strcmp( attrib, "skyrefis" ) ) { astClearSkyRefIs( this ); /* AlignOffset. */ /* ------------ */ } else if ( !strcmp( attrib, "alignoffset" ) ) { astClearAlignOffset( 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 ( !strncmp( attrib, "islataxis", 9 ) || !strncmp( attrib, "islonaxis", 9 ) || !strcmp( attrib, "lataxis" ) || !strcmp( attrib, "lonaxis" ) ) { 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); /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearDut1( AstFrame *this, int *status ) { /* * Name: * ClearDut1 * Purpose: * Clear the value of the Dut1 attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearDut1( AstFrame *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astClearDut1 method * inherited from the Frame class). * Description: * This function clears the Dut1 value and updates the LAST value * stored in the SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original value */ orig = astGetDut1( this ); /* Invoke the parent method to clear the Frame Dut1 */ (*parent_cleardut1)( this, status ); /* If the DUT1 value has changed significantly, indicate that the LAST value will need to be re-calculated when it is next needed. */ if( fabs( orig - astGetDut1( this ) ) > 1.0E-6 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; } } static void ClearObsAlt( AstFrame *this, int *status ) { /* * Name: * ClearObsAlt * Purpose: * Clear the value of the ObsAlt attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearObsAlt( AstFrame *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astClearObsAlt method * inherited from the Frame class). * Description: * This function clears the ObsAlt value. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original value */ orig = astGetObsAlt( this ); /* Invoke the parent method to clear the Frame ObsAlt. */ (*parent_clearobsalt)( this, status ); /* If the altitude has changed significantly, indicate that the LAST value and magnitude of the diurnal aberration vector will need to be re-calculated when next needed. */ if( fabs( orig - astGetObsAlt( this ) ) > 0.001 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; ( (AstSkyFrame *) this )->diurab = AST__BAD; } } static void ClearObsLat( AstFrame *this, int *status ) { /* * Name: * ClearObsLat * Purpose: * Clear the value of the ObsLat attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearObsLat( AstFrame *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astClearObsLat method * inherited from the Frame class). * Description: * This function clears the ObsLat value. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original value */ orig = astGetObsLat( this ); /* Invoke the parent method to clear the Frame ObsLat. */ (*parent_clearobslat)( this, status ); /* If the altitude has changed significantly, indicate that the LAST value and magnitude of the diurnal aberration vector will need to be re-calculated when next needed. */ if( fabs( orig - astGetObsLat( this ) ) > 1.0E-8 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; ( (AstSkyFrame *) this )->diurab = AST__BAD; } } static void ClearObsLon( AstFrame *this, int *status ) { /* * Name: * ClearObsLon * Purpose: * Clear the value of the ObsLon attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearObsLon( AstFrame *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astClearObsLon method * inherited from the Frame class). * Description: * This function clears the ObsLon value. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original value */ orig = astGetObsLon( this ); /* Invoke the parent method to clear the Frame ObsLon. */ (*parent_clearobslon)( this, status ); /* If the longitude has changed significantly, indicate that the LAST value will need to be re-calculated when it is next needed. */ if( fabs( orig - astGetObsLon( this ) ) > 1.0E-8 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; } } static void ClearSystem( AstFrame *this_frame, int *status ) { /* * Name: * ClearSystem * Purpose: * Clear the System attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void ClearSystem( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astClearSystem protected * method inherited from the Frame class). * Description: * This function clears the System attribute for a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrameSet *fs; /* FrameSet to be used as the Mapping */ AstSkyFrame *sfrm; /* Copy of original SkyFrame */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ double xin[ 2 ]; /* Axis 0 values */ double yin[ 2 ]; /* Axis 1 values */ double xout[ 2 ]; /* Axis 0 values */ double yout[ 2 ]; /* Axis 1 values */ int skyref_set; /* Is either SkyRef attribute set? */ int skyrefp_set; /* Is either SkyRefP attribute set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* See if either the SkyRef or SkyRefP attribute is set. */ skyref_set = astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ); skyrefp_set = astTestSkyRefP( this, 0 ) || astTestSkyRefP( this, 1 ); /* If so, we will need to transform their values into the new coordinate system. Save a copy of the SkyFrame with its original System value. */ sfrm = ( skyref_set || skyrefp_set )?astCopy( this ):NULL; /* Use the parent method to clear the System value. */ (*parent_clearsystem)( this_frame, status ); /* Now modify the SkyRef and SkyRefP attributes if necessary. */ if( sfrm ) { /* Save the SkyRef and SkyRefP values. */ xin[ 0 ] = astGetSkyRef( sfrm, 0 ); xin[ 1 ] = astGetSkyRefP( sfrm, 0 ); yin[ 0 ] = astGetSkyRef( sfrm, 1 ); yin[ 1 ] = astGetSkyRefP( sfrm, 1 ); /* Clear the SkyRef values to avoid infinite recursion in the following call to astConvert. */ if( skyref_set ) { astClearSkyRef( sfrm, 0 ); astClearSkyRef( sfrm, 1 ); astClearSkyRef( this, 0 ); astClearSkyRef( this, 1 ); } /* Get the Mapping from the original System to the default System. Invoking astConvert will recursively invoke ClearSystem again. This is why we need to be careful to ensure that SkyRef is cleared above - doing so ensure we do not end up with infinite recursion. */ fs = astConvert( sfrm, this, "" ); /* Check the Mapping was found. */ if( fs ) { /* Use the Mapping to find the SkyRef and SkyRefP positions in the default coordinate system. */ astTran2( fs, 2, xin, yin, 1, xout, yout ); /* Store the values as required. */ if( skyref_set ) { astSetSkyRef( this, 0, xout[ 0 ] ); astSetSkyRef( this, 1, yout[ 0 ] ); } if( skyrefp_set ) { astSetSkyRefP( this, 0, xout[ 1 ] ); astSetSkyRefP( this, 1, yout[ 1 ] ); } /* Free resources. */ fs = astAnnul( fs ); /* If the Mapping is not defined, we cannot convert the SkyRef or SkyRefP positions in the new Frame so clear them. */ } else { if( skyref_set ) { astClearSkyRef( this, 0 ); astClearSkyRef( this, 1 ); } if( skyrefp_set ) { astClearSkyRefP( this, 0 ); astClearSkyRefP( this, 1 ); } } /* Free resources. */ sfrm = astAnnul( sfrm ); } } 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 "skyframe.h" * double Distance( AstFrame *this, * const double point1[], const double point2[], int *status ) * Class Membership: * SkyFrame member function (over-rides the astDistance method * inherited from the Frame class). * Description: * This function finds the distance between two points whose * SkyFrame coordinates are given. The distance calculated is that * along the geodesic curve (i.e. great circle) that joins the two * points. * Parameters: * this * Pointer to the SkyFrame. * point1 * An array of double, with one element for each SkyFrame axis, * containing the coordinates of the first point. * point2 * An array of double, with one element for each SkyFrame axis, * containing the coordinates of the second point. * status * Pointer to the inherited status variable. * Returned Value: * The distance between the two points, in radians. * 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: */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ const int *perm; /* Axis permutation array */ double p1[ 2 ]; /* Permuted point1 coordinates */ double p2[ 2 ]; /* Permuted point2 coordinates */ double result; /* Value to return */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Check that all supplied coordinates are OK. */ if ( ( point1[ 0 ] != AST__BAD ) && ( point1[ 1 ] != AST__BAD ) && ( point2[ 0 ] != AST__BAD ) && ( point2[ 1 ] != AST__BAD ) ) { /* Apply the axis permutation array to obtain the coordinates of the two points in the required (longitude,latitude) order. */ p1[ perm[ 0 ] ] = point1[ 0 ]; p1[ perm[ 1 ] ] = point1[ 1 ]; p2[ perm[ 0 ] ] = point2[ 0 ]; p2[ perm[ 1 ] ] = point2[ 1 ]; /* Calculate the great circle distance between the points in radians. */ result = palDsep( p1[ 0 ], p1[ 1 ], p2[ 0 ], p2[ 1 ] ); } } /* 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 SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *Format( AstFrame *this, int axis, double value, int *status ) * Class Membership: * SkyFrame 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 SkyFrame axis. The * formatting applied is that specified by a previous invocation of the * astSetFormat method. A suitable default format is applied if necessary, * and this may depend on which sky coordinate system the SkyFrame * describes. * Parameters: * this * Pointer to the SkyFrame. * axis * The number of the axis (zero-based) for which formatting is to be * performed. * value * The coordinate value to be formatted, in radians. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a null-terminated string containing the formatted value. * 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const char *result; /* Pointer value to return */ int format_set; /* Format attribute set? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astFormat" ); /* Determine if a Format value has been set for the axis and set a temporary value if it has not. Use the GetFormat member function for this class together with member functions inherited from the parent class (rather than using the object's methods directly) because if any of these methods have been over-ridden by a derived class the Format string syntax may no longer be compatible with this class. */ format_set = (*parent_testformat)( this_frame, axis, status ); if ( !format_set ) { (*parent_setformat)( this_frame, axis, GetFormat( this_frame, axis, status ), status ); } /* Use the Format member function inherited from the parent class to format the value and return a pointer to the resulting string. */ result = (*parent_format)( this_frame, axis, value, status ); /* If necessary, clear any temporary Format value that was set above. */ if ( !format_set ) (*parent_clearformat)( this_frame, axis, status ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static AstPointSet *FrameGrid( AstFrame *this_object, 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 "skyframe.h" * AstPointSet *FrameGrid( AstFrame *this_frame, int size, * const double *lbnd, const double *ubnd, * int *status ) * Class Membership: * SkyFrame 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: */ AstPointSet *result; AstSkyFrame *this; double **ptr; double box_area; double cl; double dlon; double hilat; double hilon; double inclon; double lat_size; double lat; double lon; double lolon; double lon_size; double lolat; double totlen; int ilat; int ilon; int imer; int ip; int ipar; int ipmax; int nmer; int npar; /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Get the zero-based indices of the longitude and latitude axes. */ ilon = astGetLonAxis( this ); ilat = 1 - ilon; /* The latitude bounds may not be the right way round so check for it. */ if( lbnd[ ilat ] <= ubnd[ ilat ] ) { lolat = lbnd[ ilat ]; hilat = ubnd[ ilat ]; } else { lolat = ubnd[ ilat ]; hilat = lbnd[ ilat ]; } /* Check all bounds are good. Also check the size is positive. */ lolon = lbnd[ ilon ]; hilon = ubnd[ ilon ]; if( size > 0 && lolat != AST__BAD && hilat != AST__BAD && lolon != AST__BAD && hilon != AST__BAD ) { /* Ensure the longitude bounds are in the range 0-2PI. */ lolon = palDranrm( lolon ); hilon = palDranrm( hilon ); /* If the upper longitude limit is less than the lower limit, add 2.PI */ if( hilon <= lolon && ubnd[ ilon ] != lbnd[ ilon ] ) hilon += 2*AST__DPI; /* Get the total area of the box in steradians. */ dlon = hilon - lolon; box_area = fabs( dlon*( sin( hilat ) - sin( lolat ) ) ); /* Get the nominal size of a square grid cell, in radians. */ lat_size = sqrt( box_area/size ); /* How many parallels should we use to cover the box? Ensure we use at least two. These parallels pass through the centre of the grid cells. */ npar = (int)( 0.5 + ( hilat - lolat )/lat_size ); if( npar < 2 ) npar = 2; /* Find the actual sample size implied by this number of parallels. */ lat_size = ( hilat - lolat )/npar; /* Find the total arc length of the parallels. */ totlen = 0.0; lat = lolat + 0.5*lat_size; for( ipar = 0; ipar < npar; ipar++ ) { totlen += dlon*cos( lat ); lat += lat_size; } /* If we space "size" samples evenly over this total arc-length, what is the arc-distance between samples? */ lon_size = totlen/size; /* Create a PointSet in which to store the grid. Make it bigger than necessary in order to leave room for extra samples caused by integer truncation. */ ipmax = 2*size; result = astPointSet( ipmax, 2, " ", status ); ptr = astGetPoints( result ); if( astOK ) { /* Loop over all the parallels. */ ip = 0; lat = lolat + 0.5*lat_size; for( ipar = 0; ipar < npar; ipar++ ) { /* Get the longitude increment between samples on this parallel. */ cl = cos( lat ); inclon = ( cl != 0.0 ) ? lon_size/cl : 0.0; /* Get the number of longitude samples for this parallel. Reduce it if it would extend beyond the end of the PointSet. */ nmer = dlon/inclon; if( ip + nmer >= ipmax ) nmer = ipmax - ip; /* Adjust the longitude increment to take up any slack caused by the above integer division. */ inclon = dlon/nmer; /* Produce the samples for the current parallel. */ lon = lolon + 0.5*inclon; for( imer = 0; imer < nmer; imer++ ) { ptr[ ilon ][ ip ] = lon; ptr[ ilat ][ ip ] = lat; lon += inclon; ip++; } /* Get the latitude on the next parallel. */ lat += lat_size; } /* Truncate the PointSet to exclude unused elements at the end. */ astSetNpoint( result, ip ); } /* Report error if supplied values were bad. */ } else if( astOK ) { if( size < 1 ) { astError( AST__ATTIN, "astFrameGrid(%s): The supplied grid " "size (%d) is invalid (programming error).", status, astGetClass( this ), size ); } else { astError( AST__ATTIN, "astFrameGrid(%s): One of more of the " "supplied bounds is AST__BAD (programming error).", status, astGetClass( this ) ); } } /* Annul the returned PointSet if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the PointSet holding the grid. */ return result; } static double Gap( AstFrame *this_frame, int axis, double gap, int *ntick, int *status ) { /* * Name: * Gap * Purpose: * Find a "nice" gap for tabulating SkyFrame axis values. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) * Class Membership: * SkyFrame 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 SkyFrame 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 SkyFrame. * 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ double result; /* Gap value to return */ int format_set; /* Format attribute set? */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astGap" ); /* Determine if a Format value has been set for the axis and set a temporary value if it has not. Use the GetFormat member function for this class together with member functions inherited from the parent class (rather than using the object's methods directly) because if any of these methods have been over-ridden by a derived class the Format string syntax may no longer be compatible with this class. */ format_set = (*parent_testformat)( this_frame, axis, status ); if ( !format_set ) { (*parent_setformat)( this_frame, axis, GetFormat( this_frame, axis, status ), status ); } /* Use the Gap member function inherited from the parent class to find the gap size. */ result = (*parent_gap)( this_frame, axis, gap, ntick, status ); /* If necessary, clear any temporary Format value that was set above. */ if ( !format_set ) (*parent_clearformat)( this_frame, axis, status ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0.0; /* Return the result. */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SkyFrame, * in bytes. * Parameters: * this * Pointer to the SkyFrame. * 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: */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->projection ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * GetActiveUnit * Purpose: * Obtain the value of the ActiveUnit flag for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetActiveUnit protected * method inherited from the Frame class). * Description: * This function returns the value of the ActiveUnit flag for a * SkyFrame, which is always 0. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The value to use for the ActiveUnit flag (0). */ return 0; } static int GetAsTime( AstSkyFrame *this, int axis, int *status ) { /* * Name: * GetAsTime * Purpose: * Obtain the value of the AsTime attribute for a SkyFrame's axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetAsTime( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns the boolean value of the AsTime attribute for a * specified axis of a SkyFrame. This value indicates whether axis values * should be formatted as times (as opposed to angles) by default. * Parameters: * this * Pointer to the SkyFrame. * axis * Index of the axis for which information is required (zero based). * status * Pointer to the inherited status variable. * Returned Value: * Zero or one, according to the setting of the AsTime attribute (if no * value has previously been set, a suitable default is returned). * 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: */ AstAxis *ax; /* Pointer to Axis object */ int axis_p; /* Permuted axis index */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 0; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetAsTime" ); /* Obtain a pointer to the required Axis object. */ ax = astGetAxis( this, axis ); /* Determine if the AsTime attribute has been set for the axis (this can only be the case if the object is a SkyAxis). If the attribute is set, obtain its value. */ if ( astIsASkyAxis( ax ) && astTestAxisAsTime( ax ) ) { result = astGetAxisAsTime( ax ); /* Otherwise, check which (permuted) axis is involved. Only the first (longitude) axis may be displayed as a time by default. */ } else if ( axis_p == 0 ) { /* Test for those coordinate systems which normally have their longitude axes displayed as times (basically, those that involve the Earth's equator) and set the returned value appropriately. */ result = IsEquatorial( astGetSystem( this ), status ); } /* Annul the Axis object pointer. */ ax = astAnnul( ax ); /* 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 SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyFrame 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 SkyFrame, formatted as a character string. * Parameters: * this * Pointer to the SkyFrame. * attrib * Pointer to a null-terminated string containing the name of * the attribute whose value is required. This name should be in * lower case, with all white space removed. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a null-terminated string containing the attribute * value. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - The returned string pointer may point at memory allocated * within the SkyFrame, 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 SkyFrame. 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 */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const char *cval; /* Pointer to character attribute value */ const char *result; /* Pointer value to return */ double dval; /* Floating point attribute value */ double equinox; /* Equinox attribute value (as MJD) */ int as_time; /* AsTime attribute value */ int axis; /* SkyFrame axis number */ int ival; /* Integer attribute value */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ int neglon; /* Display long. values as [-pi,pi]? */ /* 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 SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* 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. */ /* AsTime(axis). */ /* ------------- */ if ( nc = 0, ( 1 == astSscanf( attrib, "astime(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { as_time = astGetAsTime( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", as_time ); result = getattrib_buff; } /* Equinox. */ /* -------- */ } else if ( !strcmp( attrib, "equinox" ) ) { equinox = astGetEquinox( this ); if ( astOK ) { /* Format the Equinox as decimal years. Use a Besselian epoch if it will be less than 1984.0, otherwise use a Julian epoch. */ result = astFmtDecimalYr( ( equinox < palEpj2d( 1984.0 ) ) ? palEpb( equinox ) : palEpj( equinox ), DBL_DIG ); } /* IsLatAxis(axis) */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "islataxis(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = astGetIsLatAxis( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* IsLonAxis(axis) */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "islonaxis(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { ival = astGetIsLonAxis( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* LatAxis */ /* -------- */ } else if ( !strcmp( attrib, "lataxis" ) ) { axis = astGetLatAxis( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", axis + 1 ); result = getattrib_buff; } /* LonAxis */ /* -------- */ } else if ( !strcmp( attrib, "lonaxis" ) ) { axis = astGetLonAxis( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", axis + 1 ); result = getattrib_buff; } /* NegLon */ /* ------ */ } else if ( !strcmp( attrib, "neglon" ) ) { neglon = astGetNegLon( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", neglon ); result = getattrib_buff; } /* SkyTol */ /* ------ */ } else if ( !strcmp( attrib, "skytol" ) ) { dval = astGetSkyTol( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Projection. */ /* ----------- */ } else if ( !strcmp( attrib, "projection" ) ) { result = astGetProjection( this ); /* SkyRef. */ /* ------- */ } else if ( !strcmp( attrib, "skyref" ) ) { cval = astFormat( this, 0, astGetSkyRef( this, 0 ) ); if ( astOK ) { nc = sprintf( getattrib_buff, "%s, ", cval ); cval = astFormat( this, 1, astGetSkyRef( this, 1 ) ); if ( astOK ) { (void) sprintf( getattrib_buff + nc, "%s", cval ); result = getattrib_buff; } } /* SkyRef(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyref(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetSkyRef( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* SkyRefP. */ /* -------- */ } else if ( !strcmp( attrib, "skyrefp" ) ) { cval = astFormat( this, 0, astGetSkyRefP( this, 0 ) ); if ( astOK ) { nc = sprintf( getattrib_buff, "%s, ", cval ); cval = astFormat( this, 1, astGetSkyRefP( this, 1 ) ); if ( astOK ) { (void) sprintf( getattrib_buff + nc, "%s", cval ); result = getattrib_buff; } } /* SkyRefP(axis). */ /* -------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyrefp(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetSkyRefP( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* SkyRefIs. */ /* --------- */ } else if ( !strcmp( attrib, "skyrefis" ) ) { ival = astGetSkyRefIs( this ); if ( astOK ) { if( ival == AST__POLE_REF ){ result = POLE_STRING; } else if( ival == AST__IGNORED_REF ){ result = IGNORED_STRING; } else { result = ORIGIN_STRING; } } /* AlignOffset */ /* ----------- */ } else if ( !strcmp( attrib, "alignoffset" ) ) { ival = astGetAlignOffset( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static int GetDirection( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetDirection * Purpose: * Obtain the value of the Direction attribute for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetDirection( AstFrame *this_frame, int axis, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetDirection method inherited * from the Frame class). * Description: * This function returns the value of the Direction attribute for a * specified axis of a SkyFrame. A suitable default value is returned if no * Direction value has previously been set. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Zero or one, depending on the Direction attribute value. * 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ int axis_p; /* Permuted axis index */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 0; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetDirection" ); /* Check if a value has been set for the axis Direction attribute. If so, obtain its value. */ if ( astTestDirection( this, axis ) ) { result = (*parent_getdirection)( this_frame, axis, status ); /* Otherwise, we will generate a default Direction value. Currently all systems supported by SkyFrame are left handed, so all longitude axes are reversed and all latitude axes are not reversed. */ } else if( axis_p == 0 ) { result = 0; } else { result = 1; } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static double GetBottom( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetBottom * Purpose: * Obtain the value of the Bottom attribute for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetBottom( AstFrame *this_frame, int axis, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetBottom method inherited * from the Frame class). * Description: * This function returns the value of the Bottom attribute for a * specified axis of a SkyFrame. A suitable default value is returned if no * value has previously been set. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * The Bottom value to use. * Notes: * - A value of -DBL_MAX will be returned if this function is invoked * with the global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ int axis_p; /* Permuted axis index */ double result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return -DBL_MAX; /* Initialise. */ result = -DBL_MAX; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetBottom" ); /* Check if a value has been set for the axis Bottom attribute. If so, obtain its value. */ if ( astTestBottom( this, axis ) ) { result = (*parent_getbottom)( this_frame, axis, status ); /* Otherwise, we will return a default Bottom value appropriate to the SkyFrame class. */ } else { /* If it is a latitude axis return -pi/2. */ if( axis_p == 1 ) { result = -piby2; /* If it is a longitude value return -DBL_MAX (i.e. no lower limit). */ } else { result = -DBL_MAX; } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -DBL_MAX; /* Return the result. */ return result; } static double GetCachedLAST( AstSkyFrame *this, double epoch, double obslon, double obslat, double obsalt, double dut1, int *status ) { /* * Name: * GetCachedLAST * Purpose: * Attempt to get a LAST value from the cache in the SkyFrame vtab. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetCachedLAST( AstSkyFrame *this, double epoch, double obslon, * double obslat, double obsalt, double dut1, * int *status ) * Class Membership: * SkyFrame member function. * Description: * This function searches the static cache of LAST values held in the * SkyFrame virtual function table for a value that corresponds to the * supplied parameter values. If one is found, it is returned. * Otherwise AST__BAD is found. * Parameters: * this * Pointer to the SkyFrame. * epoch * The epoch (MJD). * obslon * Observatory geodetic longitude (radians) * obslat * Observatory geodetic latitude (radians) * obsalt * Observatory geodetic altitude (metres) * dut1 * The UT1-UTC correction, in seconds. * status * Pointer to the inherited status variable. * Returned Value: * The Local Apparent Sidereal Time, in radians. * 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: */ astDECLARE_GLOBALS AstSkyLastTable *table; double *ep; double *lp; double dep; double result; int ihi; int ilo; int itable; int itest; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Wait until the table is not being written to by any thread. This also prevents a thread from writing to the table whilst we are reading it. */ LOCK_RLOCK1 /* Loop round every LAST table held in the vtab. Each table refers to a different observatory position and/or DUT1 value. */ for( itable = 0; itable < nlast_tables; itable++ ) { table = last_tables[ itable ]; /* See if the table refers to the given position and dut1 value, allowing some small tolerance. */ if( fabs( table->obslat - obslat ) < 2.0E-7 && fabs( table->obslon - obslon ) < 2.0E-7 && fabs( table->obsalt - obsalt ) < 1.0 && fabs( table->dut1 - dut1 ) < 1.0E-5 ) { /* Get pointers to the array of epoch and corresponding LAST values in the table. */ ep = table->epoch; lp = table->last; /* The values in the epoch array are monotonic increasing. Do a binary chop within the table's epoch array to find the earliest entry that has a value equal to or greater than the supplied epoch value. */ ilo = 0; ihi = table->nentry - 1; while( ihi > ilo ) { itest = ( ilo + ihi )/2; if( ep[ itest ] >= epoch ) { ihi = itest; } else { ilo = itest + 1; } } /* Get the difference between the epoch at the entry selected above and the requested epoch. */ dep = ep[ ilo ] - epoch; /* If the entry selected above is the first entry in the table, it can only be used if it is within 0.001 second of the requested epoch. */ if( ilo == 0 ) { if( fabs( dep ) < 0.001/86400.0 ) { result = lp[ 0 ]; } /* If the list of epoch values contained no value that was greater than the supplied epoch value, then we can use the last entry if it is no more than 0.001 second away from the requested epoch. */ } else if( dep <= 0.0 ) { if( fabs( dep ) < 0.001/86400.0 ) { result = lp[ ilo ]; } /* Otherwise, see if the entry selected above is sufficiently close to its lower neighbour (i.e. closer than 0.4 days) to allow a reasonably accurate LAST value to be determined by interpolation. */ } else if( ep[ ilo ] - ep[ ilo - 1 ] < 0.4 ) { ep += ilo - 1; lp += ilo - 1; result = *lp + ( epoch - *ep )*( lp[ 1 ] - *lp )/( ep[ 1 ] - *ep ); /* If the neighbouring point is too far away for interpolation to be reliable, then we can only use the point if it is within 0.001 seconds of the requested epoch. */ } else if( fabs( dep ) < 0.001/86400.0 ) { result = lp[ ilo ]; } /* If we have found the right table, we do not need to look at any other tables, so leave the table loop. */ break; } } /* Indicate that threads may now write to the table. */ UNLOCK_RWLOCK1 /* Ensure the returned value is within the range 0 - 2.PI. */ if( result != AST__BAD ) { while( result > 2*AST__DPI ) result -= 2*AST__DPI; while( result < 0.0 ) result += 2*AST__DPI; } /* Return the required LAST value. */ return result; } static double GetEpoch( AstFrame *this_frame, int *status ) { /* * Name: * GetEpoch * Purpose: * Obtain the value of the Epoch attribute for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetEpoch( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetEpoch method inherited * from the Frame class). * Description: * This function returns the value of the Epoch attribute for a * SkyFrame. A suitable default value is returned if no value has * previously been set. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The Epoch value to use. * 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ AstSystemType system; /* System attribute */ double result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* Initialise. */ result = AST__BAD; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Check if a value has been set for the Epoch attribute. If so, obtain its value. */ if ( astTestEpoch( this ) ) { result = (*parent_getepoch)( this_frame, status ); /* Otherwise, we will return a default Epoch value appropriate to the SkyFrame class. */ } else { /* Provide a default value of B1950.0 or J2000.0 depending on the System setting. */ system = astGetSystem( this ); if( system == AST__FK4 || system == AST__FK4_NO_E ) { result = palEpb2d( 1950.0 ); } else { result = palEpj2d( 2000.0 ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = AST__BAD; /* Return the result. */ return result; } static double GetTop( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetTop * Purpose: * Obtain the value of the Top attribute for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetTop( AstFrame *this_frame, int axis, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetTop method inherited * from the Frame class). * Description: * This function returns the value of the Top attribute for a * specified axis of a SkyFrame. A suitable default value is returned if no * value has previously been set. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * The Top value to use. * Notes: * - A value of DBL_MAX will be returned if this function is invoked * with the global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ int axis_p; /* Permuted axis index */ double result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return DBL_MAX; /* Initialise. */ result = DBL_MAX; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetTop" ); /* Check if a value has been set for the axis Top attribute. If so, obtain its value. */ if ( astTestTop( this, axis ) ) { result = (*parent_gettop)( this_frame, axis, status ); /* Otherwise, we will return a default Top value appropriate to the SkyFrame class. */ } else { /* If this is a latitude axis return pi/2. */ if( axis_p == 1 ) { result = piby2; /* If it is a longitude value return DBL_MAX (i.e. no upper limit). */ } else { result = DBL_MAX; } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = DBL_MAX; /* Return the result. */ return result; } static const char *GetDomain( AstFrame *this_frame, int *status ) { /* * Name: * GetDomain * Purpose: * Obtain a pointer to the Domain attribute string for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetDomain( AstFrame *this, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetDomain protected * method inherited from the Frame class). * Description: * This function returns a pointer to the Domain attribute string * for a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a constant null-terminated string containing the * Domain value. * Notes: * - The returned pointer or the string it refers to may become * invalid following further invocation of this function or * modification of the SkyFrame. * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to SkyFrame 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 SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* If a Domain attribute string has been set, invoke the parent method to obtain a pointer to it. */ if ( astTestDomain( this ) ) { result = (*parent_getdomain)( this_frame, status ); /* Otherwise, provide a pointer to a suitable default string. */ } else { result = "SKY"; } /* Return the result. */ return result; } static const char *GetFormat( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetFormat * Purpose: * Access the Format string for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetFormat( AstFrame *this, int axis ) * Class Membership: * SkyFrame member function (over-rides the astGetFormat method inherited * from the Frame class). * Description: * This function returns a pointer to the Format string for a specified axis * of a SkyFrame. A pointer to a suitable default string is returned if no * Format value has previously been set. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * Returned Value: * Pointer to a null-terminated character string containing the requested * information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstAxis *ax; /* Pointer to Axis object */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const char *result; /* Pointer value to return */ int as_time; /* Value of AsTime attribute */ int as_time_set; /* AsTime attribute set? */ int axis_p; /* Permuted axis index */ int digits; /* Number of digits of precision */ int is_latitude; /* Value of IsLatitude attribute */ int is_latitude_set; /* IsLatitude attribute set? */ int parent; /* Use parent method? */ int skyaxis; /* Is the Axis a SkyAxis? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_frame); /* Initialise. */ result = NULL; as_time_set = 0; is_latitude = 0; is_latitude_set = 0; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetFormat" ); /* Obtain a pointer to the Axis structure. */ ax = astGetAxis( this, axis ); /* Decide whether the parent astGetFormat method is able to provide the format string we require. We must use the parent method if the Axis is not a SkyAxis, because the syntax of the Format string would become unsuitable for use with the Axis astFormat method if it was over-ridden here. We also use the parent method to return a Format pointer if an explicit Format string has already been set. */ skyaxis = astIsASkyAxis( ax ); parent = ( !skyaxis || (*parent_testformat)( this_frame, axis, status ) ); /* If neither of the above conditions apply, we may still be able to use the parent method if the Axis (actually a SkyAxis) is required to behave as a normal RA or DEC axis, as this is the standard behaviour provided by the SkyAxis class. Examine the SkyFrame's System attribute to determine if its axes should behave in this way. */ if ( !parent ) parent = IsEquatorial( astGetSystem( this ), status ); /* If using the parent method and dealing with a SkyAxis, determine the settings of any attributes that may affect the Format string. */ if ( astOK ) { if ( parent ) { if ( skyaxis ) { as_time_set = astTestAsTime( this, axis ); is_latitude_set = astTestAxisIsLatitude( ax ); is_latitude = astGetAxisIsLatitude( ax ); /* If no AsTime value is set for the axis, set a temporary value as determined by the astGetAsTime method, which supplies suitable defaults for the axes of a SkyFrame. */ if ( !as_time_set ) { astSetAsTime( this, axis, astGetAsTime( this, axis ) ); } /* Temporarly over-ride the SkyAxis IsLatitude attribute, regardless of its setting, as the second axis of a SkyFrame is always the latitude axis. */ astSetAxisIsLatitude( ax, axis_p == 1 ); } /* Invoke the parent method to obtain a pointer to the Format string. */ result = (*parent_getformat)( this_frame, axis, status ); /* Now restore the attributes that were temporarily over-ridden above to their previous states. */ if ( skyaxis ) { if ( !as_time_set ) astClearAsTime( this, axis ); if ( !is_latitude_set ) { astClearAxisIsLatitude( ax ); } else { astSetAxisIsLatitude( ax, is_latitude ); } } /* If the parent method is unsuitable, we must construct a new Format string here. This affects only those coordinate systems whose axes do not behave like standard RA/DEC axes (e.g. typically ecliptic, galactic and supergalactic coordinates). For these, we format values as decimal degrees (or decimal hours if the AsTime attribute is set). Obtain the AsTime value. */ } else { as_time = astGetAsTime( this, axis ); /* Determine how many digits of precision to use. This is obtained from the SkyAxis Digits attribute (if set), otherwise from the Digits attribute of the enclosing SkyFrame. */ if ( astTestAxisDigits( ax ) ) { digits = astGetAxisDigits( ax ); } else { digits = astGetDigits( this ); } /* If a time format is required, generate a Format string using decimal hours. */ if ( astOK ) { if ( as_time ) { if ( digits <= 2 ) { result = "h"; } else { (void) sprintf( getformat_buff, "h.%d", digits - 2 ); result = getformat_buff; } /* Otherwise use decimal degrees. */ } else { if ( digits <= 3 ) { result = "d"; } else { (void) sprintf( getformat_buff, "d.%d", digits - 3 ); result = getformat_buff; } } } } } /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static const char *GetLabel( AstFrame *this, int axis, int *status ) { /* * Name: * GetLabel * Purpose: * Access the Label string for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetLabel( AstFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetLabel method inherited * from the Frame class). * Description: * This function returns a pointer to the Label string for a specified axis * of a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstSystemType system; /* Code identifying type of sky coordinates */ const char *result; /* Pointer to label string */ int axis_p; /* Permuted axis index */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetLabel" ); /* Check if a value has been set for the required axis label string. If so, invoke the parent astGetLabel method to obtain a pointer to it. */ if ( astTestLabel( this, axis ) ) { result = (*parent_getlabel)( this, axis, status ); /* Otherwise, identify the sky coordinate system described by the SkyFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default label string. */ if ( astOK ) { /* Equatorial coordinate systems. */ if ( IsEquatorial( system, status ) ) { result = ( axis_p == 0 ) ? "Right ascension" : "Declination"; /* Ecliptic coordinates. */ } else if ( system == AST__ECLIPTIC ) { result = ( axis_p == 0 ) ? "Ecliptic longitude" : "Ecliptic latitude"; /* Helio-ecliptic coordinates. */ } else if ( system == AST__HELIOECLIPTIC ) { result = ( axis_p == 0 ) ? "Helio-ecliptic longitude" : "Helio-ecliptic latitude"; /* AzEl coordinates. */ } else if ( system == AST__AZEL ) { result = ( axis_p == 0 ) ? "Azimuth" : "Elevation"; /* Galactic coordinates. */ } else if ( system == AST__GALACTIC ) { result = ( axis_p == 0 ) ? "Galactic longitude" : "Galactic latitude"; /* Supergalactic coordinates. */ } else if ( system == AST__SUPERGALACTIC ) { result = ( axis_p == 0 ) ? "Supergalactic longitude" : "Supergalactic latitude"; /* Unknown spherical coordinates. */ } else if ( system == AST__UNKNOWN ) { result = ( axis_p == 0 ) ? "Longitude" : "Latitude"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "astGetLabel(%s): Corrupt %s contains " "invalid sky coordinate system identification code " "(%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } /* If the SkyRef attribute has a set value, append " offset" to the label. */ if( astGetSkyRefIs( this ) != AST__IGNORED_REF && ( astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ) ) ) { sprintf( getlabel_buff, "%s offset", result ); result = getlabel_buff; } } } /* Return the result. */ return result; } static double GetDiurab( AstSkyFrame *this, int *status ) { /* * Name: * GetDiurab * Purpose: * Return the magnitude of the diurnal aberration vector. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetDiurab( AstSkyFrame *this, int *status ) * Class Membership: * SkyFrame member function * Description: * This function returns the magnitude of the diurnal aberration * vector. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The magnitude of the diurnal aberration vector. */ /* Local Variables: */ double uau; double vau; /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* If the magnitude of the diurnal aberration vector has not yet been found, find it now, and cache it in the SkyFrame structure. The cached value will be reset to AST__BAD if the ObsLat attribute value is changed. This code is transliterated from SLA_AOPPA. */ if( this->diurab == AST__BAD ) { palGeoc( astGetObsLat( this ), astGetObsAlt( this ), &uau, &vau ); this->diurab = 2*AST__DPI*uau*SOLSID/C; } /* Return the result, */ return this->diurab; } static double GetLAST( AstSkyFrame *this, int *status ) { /* * Name: * GetLAST * Purpose: * Return the Local Apparent Sidereal Time for the SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetLAST( AstSkyFrame *this, int *status ) * Class Membership: * SkyFrame member function * Description: * This function returns the Local Apparent Sidereal Time (LAST) * at the moment intime given by the Epoch attribute of the SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The LAST value. */ /* Local Variables: */ double dlast; /* Change in LAST */ double epoch; /* Epoch (TDB MJD) */ double last1; /* LAST at end of current interval */ double result; /* Result value to return */ double delta_epoch; /* Change in Epoch */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* The "last" component of the SkyFrame structure holds the accurate LAST at the moment in time given by the "eplast" (a TDB MJD) component of the SkyFrame structure. If the current value of the SkyFrame's Epoch attribute is not much different to "eplast" (within 0.4 of a day), then the returned LAST value is the "last" value plus the difference between Epoch and "eplast", converted from solar to sidereal time, then converted to radians. This approximation seems to be good to less than a tenth of an arcsecond. If this approximation cannot be used, invoke SetLast to recalculate the accurate LAST and update the "eplast" and "last" values. */ if( this->eplast != AST__BAD ) { epoch = astGetEpoch( this ); delta_epoch = epoch - this->eplast; /* Return the current LAST value if the epoch has not changed. */ if( delta_epoch == 0.0 ) { result = this->last; /* If the previous full calculation of LAST was less than 0.4 days ago, use a linear approximation to LAST. */ } else if( fabs( delta_epoch ) < 0.4 ) { /* If we do not know the ratio of sidereal to solar time at the current epoch, calculate it now. This involves a full calculation of LAST at the end of the current linear approximation period. */ if( this->klast == AST__BAD ) { last1 = CalcLAST( this, this->eplast + 0.4, astGetObsLon( this ), astGetObsLat( this ), astGetObsAlt( this ), astGetDut1( this ), status ); /* Ensure the change in LAST is positive so that we get a positive ratio. */ dlast = last1 - this->last; if( dlast < 0.0 ) dlast += 2*AST__DPI; this->klast = 2*AST__DPI*0.4/dlast; } /* Now use the ratio of solar to sidereal time to calculate the linear approximation to LAST. */ result = this->last + 2*AST__DPI*delta_epoch/this->klast; /* If the last accurate calculation of LAST was more than 0.4 days ago, do a full accurate calculation. */ } else { SetLast( this, status ); result = this->last; } /* If we have not yet done an accurate calculation of LAST, do one now. */ } else { SetLast( this, status ); result = this->last; } /* Return the result, */ return result; } static int GetIsLatAxis( AstSkyFrame *this, int axis, int *status ) { /* * Name: * GetIsLatAxis * Purpose: * Test an axis to see if it is a latitude axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetIsLatAxis( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function tests if a SkyFrame axis is a celestial latitude axis. * Parameters: * this * Pointer to the SkyFrame. * axis * Zero based axis index. * status * Pointer to the inherited status variable. * Returned Value: * One if the supplied axis is a celestial latitude axis, and zero * 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: */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Get the index of the latitude axis and compare to the supplied axis index. */ result = ( axis == astGetLatAxis( this ) ); /* Return the result. */ return astOK ? result : 0; } static int GetIsLonAxis( AstSkyFrame *this, int axis, int *status ) { /* * Name: * GetIsLonAxis * Purpose: * Test an axis to see if it is a longitude axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetIsLonAxis( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function tests if a SkyFrame axis is a celestial longitude axis. * Parameters: * this * Pointer to the SkyFrame. * axis * Zero based axis index. * status * Pointer to the inherited status variable. * Returned Value: * One if the supplied axis is a celestial longitude axis, and zero * 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: */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Get the index of the longitude axis and compare to the supplied axis index. */ result = ( axis == astGetLonAxis( this ) ); /* Return the result. */ return astOK ? result : 0; } static int GetLatAxis( AstSkyFrame *this, int *status ) { /* * Name: * GetLatAxis * Purpose: * Obtain the index of the latitude axis of a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetLatAxis( AstSkyFrame *this, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns the zero-based index of the latitude axis of * a SkyFrame, taking into account any current axis permutation. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The zero based axis index (0 or 1) of the latitude axis. * Notes: * - A value of one will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ int result; /* Result to be returned */ const int *perm; /* Axis permutation array */ /* Check the global error status. */ if ( !astOK ) return 1; /* Initialise. */ result = 1; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Identify the latitude axis. */ if( perm[ 0 ] == 1 ) { result = 0; } else { result = 1; } } /* Return the result. */ return result; } static int GetLonAxis( AstSkyFrame *this, int *status ) { /* * Name: * GetLonAxis * Purpose: * Obtain the index of the longitude axis of a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int GetLonAxis( AstSkyFrame *this, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns the zero-based index of the longitude axis of * a SkyFrame, taking into account any current axis permutation. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The zero based axis index (0 or 1) of the longitude axis. * 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: */ int result; /* Result to be returned */ const int *perm; /* Axis permutation array */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 0; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Identify the longitude axis. */ if( perm[ 0 ] == 0 ) { result = 0; } else { result = 1; } } /* Return the result. */ return result; } static double GetSkyRefP( AstSkyFrame *this, int axis, int *status ) { /* * Name: * GetSkyRefP * Purpose: * Obtain the value of the SkyRefP attribute for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double GetSkyRefP( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns the value of the SkyRefP attribute for a * SkyFrame axis, providing suitable defaults. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * The SkyRefP value to be used. * 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: */ double result; /* Returned value */ int axis_p; /* Permuted axis index */ /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetSkyRefP" ); /* Check if a value has been set for the required axis. If so, return it. */ if( this->skyrefp[ axis_p ] != AST__BAD ) { result = this->skyrefp[ axis_p ]; /* Otherwise, return the default value */ } else { /* The default longitude value is always zero. */ if( axis_p == 0 ) { result= 0.0; /* The default latitude value depends on SkyRef. The usual default is the north pole. The exception to this is if the SkyRef attribute identifies either the north or the south pole, in which case the origin is used as the default. Allow some tolerance. */ } else if( fabs( cos( this->skyref[ 1 ] ) ) > 1.0E-10 ) { result = pi/2; } else { result = 0.0; } } /* Return the result. */ return result; } static const char *GetSymbol( AstFrame *this, int axis, int *status ) { /* * Name: * GetSymbol * Purpose: * Obtain a pointer to the Symbol string for a SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetSymbol( AstFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetSymbol method inherited * from the Frame class). * Description: * This function returns a pointer to the Symbol string for a specified axis * of a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * axis * Axis index (zero-based) identifying the axis for which information is * required. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a constant null-terminated character string containing the * requested information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstSystemType system; /* Code identifying type of sky coordinates */ const char *result; /* Pointer to symbol string */ int axis_p; /* Permuted axis index */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise. */ result = NULL; /* Validate and permute the axis index. */ axis_p = astValidateAxis( this, axis, 1, "astGetSymbol" ); /* Check if a value has been set for the required axis symbol string. If so, invoke the parent astGetSymbol method to obtain a pointer to it. */ if ( astTestSymbol( this, axis ) ) { result = (*parent_getsymbol)( this, axis, status ); /* Otherwise, identify the sky coordinate system described by the SkyFrame. */ } else { system = astGetSystem( this ); /* If OK, supply a pointer to a suitable default Symbol string. */ if ( astOK ) { /* Equatorial coordinate systems. */ if ( IsEquatorial( system, status ) ) { result = ( axis_p == 0 ) ? "RA" : "Dec"; /* Ecliptic coordinates. */ } else if ( system == AST__ECLIPTIC ) { result = ( axis_p == 0 ) ? "Lambda" : "Beta"; /* Helio-ecliptic coordinates. */ } else if ( system == AST__HELIOECLIPTIC ) { result = ( axis_p == 0 ) ? "Lambda" : "Beta"; /* AzEl coordinates. */ } else if ( system == AST__AZEL ) { result = ( axis_p == 0 ) ? "Az" : "El"; /* Galactic coordinates. */ } else if ( system == AST__GALACTIC ) { result = ( axis_p == 0 ) ? "l" : "b"; /* Supergalactic coordinates. */ } else if ( system == AST__SUPERGALACTIC ) { result = ( axis_p == 0 ) ? "SGL" : "SGB"; /* Unknown spherical coordinates. */ } else if ( system == AST__UNKNOWN ) { result = ( axis_p == 0 ) ? "Lon" : "Lat"; /* Report an error if the coordinate system was not recognised. */ } else { astError( AST__SCSIN, "astGetSymbol(%s): Corrupt %s contains " "invalid sky coordinate system identification code " "(%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } /* If the SkyRef attribute had a set value, prepend "D" (for "delta") to the Symbol. */ if( astGetSkyRefIs( this ) != AST__IGNORED_REF && ( astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ) ) ) { sprintf( getsymbol_buff, "D%s", result ); result = getsymbol_buff; } } } /* Return the result. */ return result; } static AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetAlignSystem * Purpose: * Obtain the AlignSystem attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * AstSystemType GetAlignSystem( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetAlignSystem protected * method inherited from the Frame class). * Description: * This function returns the AlignSystem attribute for a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The AlignSystem value. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* If a AlignSystem attribute has been set, invoke the parent method to obtain it. */ if ( astTestAlignSystem( this ) ) { result = (*parent_getalignsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__ICRS; } /* Return the result. */ return result; } static AstSystemType GetSystem( AstFrame *this_frame, int *status ) { /* * Name: * GetSystem * Purpose: * Obtain the System attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * AstSystemType GetSystem( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetSystem protected * method inherited from the Frame class). * Description: * This function returns the System attribute for a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The System value. * Notes: * - AST__BADSYSTEM is returned if this function is invoked with * the global error status set or if it should fail for any reason. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ AstSystemType result; /* Value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* If a System attribute has been set, invoke the parent method to obtain it. */ if ( astTestSystem( this ) ) { result = (*parent_getsystem)( this_frame, status ); /* Otherwise, provide a suitable default. */ } else { result = AST__ICRS; } /* Return the result. */ return result; } static const char *GetTitle( AstFrame *this_frame, int *status ) { /* * Name: * GetTitle * Purpose: * Obtain a pointer to the Title string for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetTitle( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astGetTitle method inherited * from the Frame class). * Description: * This function returns a pointer to the Title string for a SkyFrame. * A pointer to a suitable default string is returned if no Title value has * previously been set. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null-terminated character string containing the requested * information. * 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: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ AstSystemType system; /* Code identifying type of sky coordinates */ const char *extra; /* Pointer to extra information */ const char *p; /* Character pointer */ const char *projection; /* Pointer to sky projection description */ const char *result; /* Pointer to result string */ const char *word; /* Pointer to critical word */ double epoch; /* Value of Epoch attribute */ double equinox; /* Value of Equinox attribute */ int lextra; /* Length of extra information */ int offset; /* Using offset coordinate system? */ int pos; /* Buffer position to enter text */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_frame); /* Initialise. */ result = NULL; pos = 0; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* See if a Title string has been set. If so, use the parent astGetTitle method to obtain a pointer to it. */ if ( astTestTitle( this ) ) { result = (*parent_gettitle)( this_frame, status ); /* Otherwise, we will generate a default Title string. Obtain the values of the SkyFrame's attributes that determine what this string will be. */ } else { epoch = astGetEpoch( this ); equinox = astGetEquinox( this ); projection = astGetProjection( this ); system = astGetSystem( this ); /* See if an offset coordinate system is being used.*/ offset = ( astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ) ) && ( astGetSkyRefIs( this ) != AST__IGNORED_REF ); /* Use this to determine if the word "coordinates" or "offsets" should be used.*/ word = offset ? "offsets" : "coordinates"; /* Classify the coordinate system type and create an appropriate Title string. (Note that when invoking the astFmtDecimalYr function we must use a separate sprintf on each occasion so as not to over-write its internal buffer before the result string has been used.) */ if ( astOK ) { result = gettitle_buff; switch ( system ) { /* FK4 equatorial coordinates. */ /* --------------------------- */ /* Display the Equinox and Epoch values. */ case AST__FK4: pos = sprintf( gettitle_buff, "FK4 equatorial %s", word ); if( astTestEquinox( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; mean equinox B%s", astFmtDecimalYr( palEpb( equinox ), 9 ) ); } if( astTestEpoch( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; epoch B%s", astFmtDecimalYr( palEpb( epoch ), 9 ) ); } break; /* FK4 coordinates with no E-terms of aberration. */ /* ---------------------------------------------- */ /* Display the Equinox and Epoch values. */ case AST__FK4_NO_E: pos = sprintf( gettitle_buff, "FK4 equatorial %s; no E-terms", word ); if( astTestEquinox( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; mean equinox B%s", astFmtDecimalYr( palEpb( equinox ), 9 ) ); } if( astTestEpoch( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; epoch B%s", astFmtDecimalYr( palEpb( epoch ), 9 ) ); } break; /* FK5 equatorial coordinates. */ /* --------------------------- */ /* Display only the Equinox value. */ case AST__FK5: pos = sprintf( gettitle_buff, "FK5 equatorial %s", word ); if( astTestEquinox( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; mean equinox J%s", astFmtDecimalYr( palEpj( equinox ), 9 ) ); } break; /* J2000 equatorial coordinates. */ /* ----------------------------- */ /* Based on the dynamically determined mean equator and equinox of J2000, rather than on a model such as FK4 or FK5 */ case AST__J2000: pos = sprintf( gettitle_buff, "J2000 equatorial %s", word ); break; /* ICRS coordinates. */ /* ----------------- */ /* ICRS is only like RA/Dec by co-incidence, it is not really an equatorial system by definition. */ case AST__ICRS: pos = sprintf( gettitle_buff, "ICRS %s", word ); break; /* AzEl coordinates. */ /* ----------------- */ case AST__AZEL: pos = sprintf( gettitle_buff, "Horizon (Azimuth/Elevation) %s", word ); break; /* Geocentric apparent equatorial coordinates. */ /* ------------------------------------------ */ /* Display only the Epoch value. */ case AST__GAPPT: pos = sprintf( gettitle_buff, "Geocentric apparent equatorial %s; " "; epoch J%s", word, astFmtDecimalYr( palEpj( epoch ), 9 ) ); break; /* Ecliptic coordinates. */ /* --------------------- */ /* Display only the Equinox value. */ case AST__ECLIPTIC: pos = sprintf( gettitle_buff, "Ecliptic %s", word ); if( astTestEquinox( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; mean equinox J%s", astFmtDecimalYr( palEpj( equinox ), 9 ) ); } break; /* Helio-ecliptic coordinates. */ /* --------------------------- */ /* Display only the Epoch value (equinox is fixed). */ case AST__HELIOECLIPTIC: pos = sprintf( gettitle_buff, "Helio-ecliptic %s; mean equinox J2000", word ); if( astTestEpoch( this ) || astGetUseDefs( this ) ) { pos += sprintf( gettitle_buff + pos, "; epoch J%s", astFmtDecimalYr( palEpj( epoch ), 9 ) ); } break; /* Galactic coordinates. */ /* --------------------- */ /* Do not display an Equinox or Epoch value. */ case AST__GALACTIC: pos = sprintf( gettitle_buff, "IAU (1958) galactic %s", word ); break; /* Supergalactic coordinates. */ /* -------------------------- */ /* Do not display an Equinox or Epoch value. */ case AST__SUPERGALACTIC: pos = sprintf( gettitle_buff, "De Vaucouleurs supergalactic %s", word ); break; /* Unknown coordinates. */ /* -------------------------- */ case AST__UNKNOWN: pos = sprintf( gettitle_buff, "Spherical %s", word ); break; /* Report an error if the coordinate system was not recognised. */ default: astError( AST__SCSIN, "astGetTitle(%s): Corrupt %s contains " "invalid sky coordinate system identification code " "(%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); break; } /* If OK, we add either a description of the sky projection, or (if used) a description of the origin or pole of the offset coordinate system. We include only one of these two strings in order to keep the length of the title down to a reasonable value.*/ if ( astOK ) { /* If the SkyRef attribute has set values, create a description of the offset coordinate system. */ if( offset ){ word = ( astGetSkyRefIs( this ) == AST__POLE_REF )?"pole":"origin"; lextra = sprintf( gettitle_buff2, "%s at %s ", word, astFormat( this, 0, astGetSkyRef( this, 0 ) ) ); lextra += sprintf( gettitle_buff2 + lextra, "%s", astFormat( this, 1, astGetSkyRef( this, 1 ) ) ); extra = gettitle_buff2; /* Otherwise, get the sky projection description. */ } else { extra = projection; /* Determine the length of the extra information, after removing trailing white space. */ for ( lextra = (int) strlen( extra ); lextra > 0; lextra-- ) { if ( !isspace( extra[ lextra - 1 ] ) ) break; } } /* If non-blank extra information is available, append it to the title string, checking that the end of the buffer is not over-run. */ if ( lextra ) { p = "; "; while ( ( pos < AST__SKYFRAME_GETTITLE_BUFF_LEN ) && *p ) gettitle_buff[ pos++ ] = *p++; p = extra; while ( ( pos < AST__SKYFRAME_GETTITLE_BUFF_LEN ) && ( p < ( extra + lextra ) ) ) gettitle_buff[ pos++ ] = *p++; if( extra == projection ) { p = " projection"; while ( ( pos < AST__SKYFRAME_GETTITLE_BUFF_LEN ) && *p ) gettitle_buff[ pos++ ] = *p++; } gettitle_buff[ pos ] = '\0'; } } } } /* If an error occurred, clear the returned pointer value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static const char *GetUnit( AstFrame *this_frame, int axis, int *status ) { /* * Name: * GetUnit * Purpose: * Obtain a pointer to the Unit string for a SkyFrame's axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *GetUnit( AstFrame *this_frame, int axis ) * Class Membership: * SkyFrame member function (over-rides the astGetUnit method inherited * from the Frame class). * Description: * This function returns a pointer to the Unit string for a specified axis * of a SkyFrame. If the Unit attribute has not been set for the axis, a * pointer to a suitable default string is returned instead. This string may * depend on the value of the Format attribute for the axis and, in turn, on * the type of sky coordinate system that the SkyFrame describes. * Parameters: * this * Pointer to the SkyFrame. * axis * The number of the axis (zero-based) for which information is required. * Returned Value: * A pointer to a null-terminated string containing the Unit value. * 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const char *result; /* Pointer value to return */ int format_set; /* Format attribute set? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astGetUnit" ); /* The Unit value may depend on the value of the Format attribute, so determine if a Format value has been set for the axis and set a temporary value if it has not. Use the GetFormat member function for this class together with member functions inherited from the parent class (rather than using the object's methods directly) because if any of these methods have been over-ridden by a derived class the Format string syntax may no longer be compatible with this class. */ format_set = (*parent_testformat)( this_frame, axis, status ); if ( !format_set ) { (*parent_setformat)( this_frame, axis, GetFormat( this_frame, axis, status ), status ); } /* Use the parent GetUnit method to return a pointer to the required Unit string. */ result = (*parent_getunit)( this_frame, axis, status ); /* If necessary, clear any temporary Format value that was set above. */ if ( !format_set ) (*parent_clearformat)( this_frame, axis, status ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } void astInitSkyFrameVtab_( AstSkyFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSkyFrameVtab * Purpose: * Initialise a virtual function table for a SkyFrame. * Type: * Protected function. * Synopsis: * #include "skyframe.h" * void astInitSkyFrameVtab( AstSkyFrameVtab *vtab, const char *name ) * Class Membership: * SkyFrame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SkyFrame 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 */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ int stat; /* SLALIB status */ /* 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 astIsASkyFrame) 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->ClearAsTime = ClearAsTime; vtab->ClearEquinox = ClearEquinox; vtab->ClearNegLon = ClearNegLon; vtab->ClearProjection = ClearProjection; vtab->GetAsTime = GetAsTime; vtab->GetEquinox = GetEquinox; vtab->GetNegLon = GetNegLon; vtab->GetIsLatAxis = GetIsLatAxis; vtab->GetIsLonAxis = GetIsLonAxis; vtab->GetLatAxis = GetLatAxis; vtab->GetLonAxis = GetLonAxis; vtab->GetProjection = GetProjection; vtab->SetAsTime = SetAsTime; vtab->SetEquinox = SetEquinox; vtab->SetNegLon = SetNegLon; vtab->SetProjection = SetProjection; vtab->SkyOffsetMap = SkyOffsetMap; vtab->TestAsTime = TestAsTime; vtab->TestEquinox = TestEquinox; vtab->TestNegLon = TestNegLon; vtab->TestProjection = TestProjection; vtab->TestSkyTol = TestSkyTol; vtab->SetSkyTol = SetSkyTol; vtab->GetSkyTol = GetSkyTol; vtab->ClearSkyTol = ClearSkyTol; vtab->TestSkyRef = TestSkyRef; vtab->SetSkyRef = SetSkyRef; vtab->GetSkyRef = GetSkyRef; vtab->ClearSkyRef = ClearSkyRef; vtab->TestSkyRefP = TestSkyRefP; vtab->SetSkyRefP = SetSkyRefP; vtab->GetSkyRefP = GetSkyRefP; vtab->ClearSkyRefP = ClearSkyRefP; vtab->TestSkyRefIs = TestSkyRefIs; vtab->SetSkyRefIs = SetSkyRefIs; vtab->GetSkyRefIs = GetSkyRefIs; vtab->ClearSkyRefIs = ClearSkyRefIs; vtab->TestAlignOffset = TestAlignOffset; vtab->SetAlignOffset = SetAlignOffset; vtab->GetAlignOffset = GetAlignOffset; vtab->ClearAlignOffset = ClearAlignOffset; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; frame = (AstFrameVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_gettop = frame->GetTop; frame->GetTop = GetTop; parent_setobsalt = frame->SetObsAlt; frame->SetObsAlt = SetObsAlt; parent_setobslat = frame->SetObsLat; frame->SetObsLat = SetObsLat; parent_setobslon = frame->SetObsLon; frame->SetObsLon = SetObsLon; parent_clearobslon = frame->ClearObsLon; frame->ClearObsLon = ClearObsLon; parent_clearobsalt = frame->ClearObsAlt; frame->ClearObsAlt = ClearObsAlt; parent_clearobslat = frame->ClearObsLat; frame->ClearObsLat = ClearObsLat; parent_getbottom = frame->GetBottom; frame->GetBottom = GetBottom; parent_getepoch = frame->GetEpoch; frame->GetEpoch = GetEpoch; parent_format = frame->Format; frame->Format = Format; parent_gap = frame->Gap; frame->Gap = Gap; parent_getdirection = frame->GetDirection; frame->GetDirection = GetDirection; parent_getdomain = frame->GetDomain; frame->GetDomain = GetDomain; parent_getsystem = frame->GetSystem; frame->GetSystem = GetSystem; parent_setsystem = frame->SetSystem; frame->SetSystem = SetSystem; parent_clearsystem = frame->ClearSystem; frame->ClearSystem = ClearSystem; parent_getalignsystem = frame->GetAlignSystem; frame->GetAlignSystem = GetAlignSystem; parent_getformat = frame->GetFormat; frame->GetFormat = GetFormat; parent_getlabel = frame->GetLabel; frame->GetLabel = GetLabel; parent_getsymbol = frame->GetSymbol; frame->GetSymbol = GetSymbol; parent_gettitle = frame->GetTitle; frame->GetTitle = GetTitle; parent_getunit = frame->GetUnit; frame->GetUnit = GetUnit; parent_match = frame->Match; frame->Match = Match; parent_overlay = frame->Overlay; frame->Overlay = Overlay; parent_subframe = frame->SubFrame; frame->SubFrame = SubFrame; parent_unformat = frame->Unformat; frame->Unformat = Unformat; parent_setdut1 = frame->SetDut1; frame->SetDut1 = SetDut1; parent_cleardut1 = frame->ClearDut1; frame->ClearDut1 = ClearDut1; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ frame->Angle = Angle; frame->Distance = Distance; frame->FrameGrid = FrameGrid; frame->Intersect = Intersect; frame->Norm = Norm; frame->NormBox = NormBox; frame->Resolve = Resolve; frame->ResolvePoints = ResolvePoints; frame->Offset = Offset; frame->Offset2 = Offset2; frame->ValidateSystem = ValidateSystem; frame->SystemString = SystemString; frame->SystemCode = SystemCode; frame->LineDef = LineDef; frame->LineContains = LineContains; frame->LineCrossing = LineCrossing; frame->LineOffset = LineOffset; frame->GetActiveUnit = GetActiveUnit; frame->TestActiveUnit = TestActiveUnit; frame->MatchAxesX = MatchAxesX; /* Store pointers to inherited methods that will be invoked explicitly by this class. */ parent_clearformat = frame->ClearFormat; parent_setformat = frame->SetFormat; parent_testformat = frame->TestFormat; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "SkyFrame", "Description of celestial coordinate system" ); /* Initialize constants for converting between hours, degrees and radians, etc.. */ LOCK_MUTEX2 palDtf2r( 1, 0, 0.0, &hr2rad, &stat ); palDaf2r( 1, 0, 0.0, °2rad, &stat ); palDaf2r( 180, 0, 0.0, &pi, &stat ); piby2 = 0.5*pi; UNLOCK_MUTEX2 /* 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 "skyframe.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: * SkyFrame 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Pointer to axis permutation array */ double aa1[ 2 ]; /* Permuted coordinates for a1 */ double aa2[ 2 ]; /* Permuted coordinates for a2 */ double bb1[ 2 ]; /* Permuted coordinates for b1 */ double bb2[ 2 ]; /* Permuted coordinates for b2 */ double cc[ 2 ]; /* Permuted coords at intersection */ double d1; /* Cos(distance from a1 to vp) */ double d2; /* Cos(distance from a1 to -vp) */ double na[ 3 ]; /* Normal to the a1/a2 great circle */ double nb[ 3 ]; /* Normal to the b1/b2 great circle */ double va1[ 3 ]; /* Vector pointing at a1 */ double va2[ 3 ]; /* Vector pointing at a2 */ double vb1[ 3 ]; /* Vector pointing at b1 */ double vb2[ 3 ]; /* Vector pointing at b2 */ double vmod; /* Length of "vp" */ double vp[ 3 ]; /* Vector pointing at the intersection */ double vpn[ 3 ]; /* Normalised vp */ int iaxis; /* Axis index */ /* Initialise. */ cross[ 0 ] = AST__BAD; cross[ 1 ] = AST__BAD; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Check that all supplied values are OK. */ if ( ( a1[ 0 ] != AST__BAD ) && ( a1[ 1 ] != AST__BAD ) && ( a2[ 0 ] != AST__BAD ) && ( a2[ 1 ] != AST__BAD ) && ( b1[ 0 ] != AST__BAD ) && ( b1[ 1 ] != AST__BAD ) && ( b2[ 0 ] != AST__BAD ) && ( b2[ 1 ] != AST__BAD ) ) { /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Apply the axis permutation array to obtain the coordinates of the points in the required (longitude,latitude) order. */ for( iaxis = 0; iaxis < 2; iaxis++ ) { aa1[ perm[ iaxis ] ] = a1[ iaxis ]; aa2[ perm[ iaxis ] ] = a2[ iaxis ]; bb1[ perm[ iaxis ] ] = b1[ iaxis ]; bb2[ perm[ iaxis ] ] = b2[ iaxis ]; } /* Convert each (lon,lat) pair into a unit length 3-vector. */ palDcs2c( aa1[ 0 ], aa1[ 1 ], va1 ); palDcs2c( aa2[ 0 ], aa2[ 1 ], va2 ); palDcs2c( bb1[ 0 ], bb1[ 1 ], vb1 ); palDcs2c( bb2[ 0 ], bb2[ 1 ], vb2 ); /* Find the normal vectors to the two great cicles. */ palDvxv( va1, va2, na ); palDvxv( vb1, vb2, nb ); /* The cross product of the two normal vectors points to one of the two diametrically opposite intersections. */ palDvxv( na, nb, vp ); /* Normalise the "vp" vector, also obtaining its original modulus. */ palDvn( vp, vpn, &vmod ); if( vmod != 0.0 ) { /* We want the intersection which is closest to "a1". The dot product gives the cos(distance) between two positions. So find the dot product between "a1" and "vpn", and then between "a1" and the point diametrically opposite "vpn". */ d1 = palDvdv( vpn, va1 ); vpn[ 0 ] = -vpn[ 0 ]; vpn[ 1 ] = -vpn[ 1 ]; vpn[ 2 ] = -vpn[ 2 ]; d2 = palDvdv( vpn, va1 ); /* Revert to "vpn" if it is closer to "a1". */ if( d1 > d2 ) { vpn[ 0 ] = -vpn[ 0 ]; vpn[ 1 ] = -vpn[ 1 ]; vpn[ 2 ] = -vpn[ 2 ]; } /* Convert the vector back into a (lon,lat) pair, and put the longitude into the range 0 to 2.pi. */ palDcc2s( vpn, cc, cc + 1 ); *cc = palDranrm( *cc ); /* Permute the result coordinates to undo the effect of the SkyFrame axis permutation array. */ cross[ 0 ] = cc[ perm[ 0 ] ]; cross[ 1 ] = cc[ perm[ 1 ] ]; } } } } static int IsEquatorial( AstSystemType system, int *status ) { /* * Name: * IsEquatorial * Purpose: * Test for an equatorial sky coordinate system. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int IsEquatorial( AstSystemType system, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns a boolean value to indicate if a sky coordinate * system is equatorial. * Parameters: * system * Code to identify the sky coordinate system. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the sky coordinate system is equatorial, otherwise zero. * Notes: * - A value of zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Variables: */ int result; /* Result value to return */ /* Check the global error status. */ if ( !astOK ) return 0; /* Determine if the sky coordinate system is an equatorial one. Note, ICRS is not equatorial by definition, but is included here because it is normally treated as an equatorial system in terms of the axis labels, formats, etc. */ result = ( ( system == AST__FK4 ) || ( system == AST__FK4_NO_E ) || ( system == AST__ICRS ) || ( system == AST__FK5 ) || ( system == AST__J2000 ) || ( system == AST__GAPPT ) ); /* Return the result. */ return result; } static int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) { /* * Name: * LineContains * Purpose: * Determine if a line contains a point. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) * Class Membership: * SkyFrame member function (over-rides the protected astLineContains * method inherited from the Frame class). * Description: * This function determines if the supplied point is on the supplied * line within the supplied Frame. The start point of the line is * considered to be within the line, but the end point is not. The tests * are that the point of closest approach of the line to the point should * be between the start and end, and that the distance from the point to * the point of closest aproach should be less than 1.0E-7 of the length * of the line. * Parameters: * this * Pointer to the Frame. * l * Pointer to the structure defining the line. * def * Should be set non-zero if the "point" array was created by a * call to astLineCrossing (in which case it may contain extra * information following the axis values),and zero otherwise. * point * Point to an array containing the axis values of the point to be * tested, possibly followed by extra cached information (see "def"). * status * Pointer to the inherited status variable. * Returned Value: * A non-zero value is returned if the line contains the point. * Notes: * - The pointer supplied for "l" should have been created using the * astLineDef method. These structures contained cached information about * the lines which improve the efficiency of this method when many * repeated calls are made. An error will be reported if the structure * does not refer to the Frame specified by "this". * - Zero will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. *- */ /* Local Variables: */ SkyLineDef *sl; /* SkyLine information */ const int *perm; /* Pointer to axis permutation array */ double *b; /* Pointer to Cartesian coords array */ double bb[3]; /* Buffer for Cartesian coords */ double p1[2]; /* Buffer for Spherical coords */ double t1, t2; int result; /* Returned value */ /* Initialise */ result =0; /* Check the global error status. */ if ( !astOK ) return result; /* Check that the line refers to the supplied Frame. */ if( l->frame != this ) { astError( AST__INTER, "astLineContains(%s): The supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); /* Check the axis values are good */ } else if( point[ 0 ] != AST__BAD && point[ 1 ] != AST__BAD ){ /* Get a pointer to an array holding the corresponding Cartesian coords. */ if( def ) { b = point + 2; } else { perm = astGetPerm( this ); if ( perm ) { p1[ perm[ 0 ] ] = point[ 0 ]; p1[ perm[ 1 ] ] = point[ 1 ]; palDcs2c( p1[ 0 ], p1[ 1 ], bb ); b = bb; } else { b = NULL; } } /* Recast the supplied AstLineDef into a SkyLineDef to get the different structure (we know from the above check on the Frame that it is safe to do this). */ sl = (SkyLineDef *) l; /* Check that the point of closest approach of the line to the point is within the limits of the line. */ if( LineIncludes( sl, b, status ) ){ /* Check that the point is 90 degrees away from the pole of the great circle containing the line. */ t1 = palDvdv( sl->q, b ); t2 = 1.0E-7*sl->length; if( t2 < 1.0E-10 ) t2 = 1.0E-10; if( fabs( t1 ) <= t2 ) result = 1; } } /* Return the result. */ return result; } static int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, double **cross, int *status ) { /* * Name: * LineCrossing * Purpose: * Determine if two lines cross. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, * double **cross, int *status ) * Class Membership: * SkyFrame 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: */ SkyLineDef *sl1; /* SkyLine information for line 1 */ SkyLineDef *sl2; /* SkyLine information for line 2 */ const int *perm; /* Pointer to axis permutation array */ double *crossing; /* Pointer to returned array */ double *b; /* Pointer to Cartesian coords */ double len; /* Vector length */ double p[ 2 ]; /* Temporary (lon,lat) pair */ double temp[ 3 ]; /* Temporary vector */ int result; /* Returned value */ /* Initialise */ result = 0; if( cross ) *cross = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate returned array (2 elements for the lon and lat values, plus 3 for the corresponding (x,y,z) coords). */ crossing = astMalloc( sizeof(double)*5 ); /* Check that both lines refer to the supplied Frame. */ if( l1->frame != this ) { astError( AST__INTER, "astLineCrossing(%s): First supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); } else if( l2->frame != this ) { astError( AST__INTER, "astLineCrossing(%s): Second supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); /* Recast the supplied AstLineDefs into a SkyLineDefs to get the different structure (we know from the above check on the Frame that it is safe to do this). */ } else if( crossing ){ sl1 = (SkyLineDef *) l1; sl2 = (SkyLineDef *) l2; /* Point of intersection of the two great circles is perpendicular to the pole vectors of both great circles. Put the Cartesian coords in elements 2 to 4 of the returned array. */ palDvxv( sl1->q, sl2->q, temp ); b = crossing + 2; palDvn( temp, b, &len ); /* See if this point is within the length of both arcs. If so return it. */ if( LineIncludes( sl2, b, status ) && LineIncludes( sl1, b, status ) ) { result = 1; /* If not, see if the negated b vector is within the length of both arcs. If so return it. Otherwise, we return zero. */ } else { b[ 0 ] *= -1.0; b[ 1 ] *= -1.0; b[ 2 ] *= -1.0; if( LineIncludes( sl2, b, status ) && LineIncludes( sl1, b, status ) ) result = 1; } /* Store the spherical coords in elements 0 and 1 of the returned array. */ palDcc2s( b, p, p + 1 ); /* Permute the spherical axis value into the order used by the SkyFrame. */ perm = astGetPerm( this ); if( perm ){ crossing[ 0 ] = p[ perm[ 0 ] ]; crossing[ 1 ] = p[ perm[ 1 ] ]; } } /* If an error occurred, return 0. */ if( !astOK ) { result = 0; crossing = astFree( crossing ); } /* Return the array */ if( cross ) { *cross = crossing; } else { crossing = astFree( crossing ); } /* Return the result. */ return result; } static AstLineDef *LineDef( AstFrame *this, 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 "skyframe.h" * AstLineDef *LineDef( AstFrame *this, const double start[2], * const double end[2], int *status ) * Class Membership: * SkyFrame 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: */ SkyLineDef *result; /* Returned value */ const int *perm; /* Axis permutation array */ double le; /* Length of end vector */ double len; /* Permuted point1 coordinates */ double ls; /* Length of start vector */ double p1[ 2 ]; /* Permuted point1 coordinates */ double p2[ 2 ]; /* Permuted point2 coordinates */ double temp[3]; /* Cartesian coords at offset position */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return NULL; /* Check the axis values are good */ if( start[ 0 ] != AST__BAD && start[ 1 ] != AST__BAD && end[ 0 ] != AST__BAD && end[ 1 ] != AST__BAD ) { /* Allocate memory for the returned structure. */ result = astMalloc( sizeof( SkyLineDef ) ); /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( perm ) { /* Apply the axis permutation array to obtain the coordinates of the two input points in the required (longitude,latitude) order. */ p1[ perm[ 0 ] ] = start[ 0 ]; p1[ perm[ 1 ] ] = start[ 1 ]; p2[ perm[ 0 ] ] = end[ 0 ]; p2[ perm[ 1 ] ] = end[ 1 ]; /* Convert each point into a 3-vector of unit length and store in the returned structure. */ palDcs2c( p1[ 0 ], p1[ 1 ], result->start ); palDcs2c( p2[ 0 ], p2[ 1 ], result->end ); /* Calculate the great circle distance between the points in radians and store in the result structure. Correct for rounding errors in palDcs2c that can result in the vectors not having exactly unit length. */ result->length = palDvdv( result->start, result->end ); ls = result->start[0]*result->start[0] + result->start[1]*result->start[1] + result->start[2]*result->start[2]; le = result->end[0]*result->end[0] + result->end[1]*result->end[1] + result->end[2]*result->end[2]; result->length = acos( result->length/sqrt( ls*le ) ); /* Find a unit vector representing the pole of the system in which the equator is given by the great circle. This is such that going the short way from the start to the end, the pole is to the left of the line as seen by the observer (i.e. from the centre of the sphere). If the line has zero length, or 180 degrees length, the pole is undefined, so we use an arbitrary value. */ if( result->length == 0.0 || result->length > pi - 5.0E-11 ) { palDcs2c( p1[ 0 ] + 0.01, p1[ 1 ] + 0.01, temp ); palDvxv( temp, result->start, result->dir ); } else { palDvxv( result->end, result->start, result->dir ); } palDvn( result->dir, result->q, &len ); /* Also store a point which is 90 degrees along the great circle from the start. */ palDvxv( result->start, result->q, result->dir ); /* Store a pointer to the defining SkyFrame. */ result->frame = this; /* Indicate that the line is considered to be terminated at the start and end points. */ result->infinite = 0; /* Normalise the spherical start and end positions stored in the returned structure. */ result->start_2d[ 0 ] = start[ 0 ]; result->start_2d[ 1 ] = start[ 1 ]; result->end_2d[ 0 ] = end[ 0 ]; result->end_2d[ 1 ] = end[ 1 ]; astNorm( this, result->start_2d ); astNorm( this, result->end_2d ); } } /* Free the returned pointer if an error occurred. */ if( !astOK ) result = astFree( result ); /* Return a pointer to the output structure. */ return (AstLineDef *) result; } static int LineIncludes( SkyLineDef *l, double point[3], int *status ) { /* * Name: * LineIncludes * Purpose: * Determine if a line includes a point which is known to be in the * great circle. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int LineIncludes( SkyLineDef *l, double point[3], int *status ) * Class Membership: * SkyFrame member function (over-rides the protected astLineIncludes * method inherited from the Frame class). * Description: * The supplied point is assumed to be a point on the great circle of * which the supplied line is a segment. This function returns true if * "point" is within the bounds of the segment (the end point of the * line is assumed * not to be part of the segment). * Parameters: * l * Pointer to the structure defining the line. * point * An array holding the Cartesian coords of the point to be tested. * status * Pointer to the inherited status variable. * Returned Value: * A non-zero value is returned if the line includes the point. * Notes: * - Zero will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. */ /* Local Variables: */ double t1, t2, t3; /* Check the global error status. */ if ( !astOK ) return 0; /* If the line is of infite length, it is assumed to include the supplied point. */ if( l->infinite ) return 1; /* Otherwise, get the unsigned distance of the point from the start of the line in the range 0 - 180 degs. Check it is less than the line length. Then check that the point is not more than 90 degs away from the quarter point. */ t1 = palDvdv( l->start, point ); t2 = acos( t1 ); t3 = palDvdv( l->dir, point ); return ( ((l->length > 0) ? t2 < l->length : t2 == 0.0 ) && t3 >= -1.0E-8 ); } static void LineOffset( AstFrame *this, 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 "skyframe.h" * void LineOffset( AstFrame *this, AstLineDef *line, double par, * double prp, double point[2], int *status ) * Class Membership: * SkyFrame 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; */ SkyLineDef *sl; const int *perm; double c; double nx; double ny; double nz; double p[2]; double s; double v[3]; /* Check the global error status. */ if ( !astOK ) return; /* Check that the line refers to the supplied Frame. */ if( line->frame != this ) { astError( AST__INTER, "astLineOffset(%s): The supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); /* This implementation uses spherical geometry. */ } else { /* Get a pointer to the SkyLineDef structure. */ sl = (SkyLineDef *) line; /* Move a distance par from start to end. */ c = cos( par ); s = sin( par ); nx = c * sl->start[ 0 ] + s * sl->dir[ 0 ]; ny = c * sl->start[ 1 ] + s * sl->dir[ 1 ]; nz = c * sl->start[ 2 ] + s * sl->dir[ 2 ]; /* Move a distance prp from this point towards the pole point. */ if( prp != 0.0 ) { c = cos( prp ); s = sin( prp ); v[ 0 ] = c * nx + s * sl->q[ 0 ]; v[ 1 ] = c * ny + s * sl->q[ 1 ]; v[ 2 ] = c * nz + s * sl->q[ 2 ]; } else { v[ 0 ] = nx; v[ 1 ] = ny; v[ 2 ] = nz; } /* Convert to lon/lat */ palDcc2s( v, p, p + 1 ); /* Permute the spherical axis value into the order used by the SkyFrame. */ perm = astGetPerm( this ); if( perm ){ point[ 0 ] = p[ perm[ 0 ] ]; point[ 1 ] = p[ perm[ 1 ] ]; } } } static int MakeSkyMapping( AstSkyFrame *target, AstSkyFrame *result, AstSystemType align_sys, AstMapping **map, int *status ) { /* * Name: * MakeSkyMapping * Purpose: * Generate a Mapping between two SkyFrames. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int MakeSkyMapping( AstSkyFrame *target, AstSkyFrame *result, * AstSystemType align_sys, AstMapping **map, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function takes two SkyFrames and generates a Mapping that * converts between them, taking account of differences in their * coordinate systems, equinox value, epoch, etc. (but not allowing * for any axis permutations). * Parameters: * target * Pointer to the first SkyFrame. * result * Pointer to the second SkyFrame. * align_sys * The system in which to align the two SkyFrames. * map * Pointer to a location which is to receive a pointer to the * returned Mapping. The forward transformation of this Mapping * will convert from "target" coordinates to "result" * coordinates, and the inverse transformation will convert in * the opposite direction (all coordinate values in radians). * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the Mapping could be generated, or zero if the two * SkyFrames are sufficiently un-related that no meaningful Mapping * can be produced. * Notes: * A value of zero is returned if this function is invoked with the * global error status set or if it should fail for any reason. */ /* Local Constants: */ #define MAX_ARGS 4 /* Max arguments for an SlaMap conversion */ /* Local Variables: */ AstMapping *omap; /* Mapping from coorinates to offsets */ AstMapping *tmap2; /* Temporary Mapping */ AstMapping *tmap; /* Temporary Mapping */ AstSlaMap *slamap; /* Pointer to SlaMap */ AstSystemType result_system; /* Code to identify result coordinate system */ AstSystemType system; /* Code to identify coordinate system */ AstSystemType target_system; /* Code to identify target coordinate system */ double args[ MAX_ARGS ]; /* Conversion argument array */ double epoch; /* Epoch as Modified Julian Date */ double epoch_B; /* Besselian epoch as decimal years */ double epoch_J; /* Julian epoch as decimal years */ double equinox; /* Equinox as Modified Julian Date */ double equinox_B; /* Besselian equinox as decimal years */ double equinox_J; /* Julian equinox as decimal years */ double diurab; /* Magnitude of diurnal aberration vector */ double last; /* Local Apparent Sidereal Time */ double lat; /* Observers latitude */ double result_epoch; /* Result frame Epoch */ double result_equinox; /* Result frame Epoch */ double target_epoch; /* Target frame Epoch */ double target_equinox; /* Target frame Epoch */ int isunit; /* Is the SlaMap effectively a unit mapping? */ int match; /* Mapping can be generated? */ int step1; /* Convert target to FK5 J2000? */ int step2; /* Convert FK5 J2000 to align sys? */ int step3; /* Convert align sys to FK5 J2000? */ int step4; /* Convert FK5 J2000 to result? */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise the returned values. */ match = 1; *map = NULL; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ epoch_B = 0.0; epoch_J = 0.0; equinox_B = 0.0; equinox_J = 0.0; /* Get the two epoch values. */ result_epoch = astGetEpoch( result ); target_epoch = astGetEpoch( target ); /* Get the two equinox values. */ result_equinox = astGetEquinox( result ); target_equinox = astGetEquinox( target ); /* Get the two system values. */ result_system = astGetSystem( result ); target_system = astGetSystem( target ); /* If either system is not references to the equinox given by the Equinox attribute, then use the equinox of the other system rather than adopting the arbitrary default of J2000. */ if( !EQREF(result_system) ) result_equinox = target_equinox; if( !EQREF(target_system) ) target_equinox = result_equinox; /* If both systems are unknown, assume they are the same. Return a UnitMap. We need to do this, otherwise a simple change of Title (for instance) will result in a FrameSet whose current Frame has System=AST__UNKNOWN loosing its integrity. */ if( target_system == AST__UNKNOWN && result_system == AST__UNKNOWN ) { *map = (AstMapping *) astUnitMap( 2, "", status ); return 1; } /* The total Mapping is divided into two parts in series; the first part converts from the target SkyFrame to the alignment system, using the Epoch and Equinox of the target Frame, the second part converts from the alignment system to the result SkyFrame, using the Epoch and Equinox of the result Frame. Each of these parts has an arbitrary input and an output system, and therefore could be implemented using a collection of NxN conversions. To reduce the complexity, each part is implement by converting from the input system to FK5 J2000, and then from FK5 J2000 to the output system. This scheme required only N conversions rather than NxN. Thus overall the total Mapping is made up of 4 steps in series. Some of these steps may be ommitted if they are effectively a UnitMap. Determine which steps need to be included. Assume all need to be done to begin with. */ step1 = 1; step2 = 1; step3 = 1; step4 = 1; /* If the target system is the same as the alignment system, neither of the first 2 steps need be done. */ if( target_system == align_sys ) { step1 = 0; step2 = 0; } /* If the result system is the same as the alignment system, neither of the last 2 steps need be done. */ if( result_system == align_sys ) { step3 = 0; step4 = 0; } /* If the two epochs are the same, or if the alignment system is FK5 J2000, steps 2 and 3 are not needed. */ if( step2 && step3 ) { if( align_sys == AST__FK5 || result_epoch == target_epoch ) { step2 = 0; step3 = 0; } } /* None are needed if the target and result SkyFrames have the same System, Epoch and Equinox. */ if( result_system == target_system && result_epoch == target_epoch && result_equinox == target_equinox ) { step1 = 0; step2 = 0; step3 = 0; step4 = 0; } /* Create an initial (null) SlaMap. */ slamap = astSlaMap( 0, "", status ); /* Define local macros as shorthand for adding sky coordinate conversions to this SlaMap. Each macro simply stores details of the additional arguments in the "args" array and then calls astSlaAdd. The macros differ in the number of additional argument values. */ #define TRANSFORM_0(cvt) \ astSlaAdd( slamap, cvt, NULL ); #define TRANSFORM_1(cvt,arg0) \ args[ 0 ] = arg0; \ astSlaAdd( slamap, cvt, args ); #define TRANSFORM_2(cvt,arg0,arg1) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ astSlaAdd( slamap, cvt, args ); #define TRANSFORM_3(cvt,arg0,arg1,arg2) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ args[ 2 ] = arg2; \ astSlaAdd( slamap, cvt, args ); #define TRANSFORM_4(cvt,arg0,arg1,arg2,arg3) \ args[ 0 ] = arg0; \ args[ 1 ] = arg1; \ args[ 2 ] = arg2; \ args[ 3 ] = arg3; \ astSlaAdd( slamap, cvt, args ); /* Convert _to_ FK5 J2000.0 coordinates. */ /* ===================================== */ /* The overall conversion is formulated in four phases. In this first phase, we convert from the target coordinate system to intermediate sky coordinates expressed using the FK5 system, mean equinox J2000.0. */ /* Obtain the sky coordinate system, equinox, epoch, etc, of the target SkyFrame. */ system = target_system; equinox = target_equinox; epoch = target_epoch; last = GetLAST( target, status ); diurab = GetDiurab( target, status ); lat = astGetObsLat( target ); if( astOK && step1 ) { /* Convert the equinox and epoch values (stored as Modified Julian Dates) into the equivalent Besselian and Julian epochs (as decimal years). */ equinox_B = palEpb( equinox ); equinox_J = palEpj( equinox ); epoch_B = palEpb( epoch ); epoch_J = palEpj( epoch ); /* Formulate the conversion... */ /* From FK4. */ /* --------- */ /* If necessary, apply the old-style FK4 precession model to bring the equinox to B1950.0, with rigorous handling of the E-terms of aberration. Then convert directly to FK5 J2000.0 coordinates. */ if ( system == AST__FK4 ) { VerifyMSMAttrs( target, result, 1, "Equinox Epoch", "astMatch", status ); if ( equinox_B != 1950.0 ) { TRANSFORM_1( "SUBET", equinox_B ) TRANSFORM_2( "PREBN", equinox_B, 1950.0 ) TRANSFORM_1( "ADDET", 1950.0 ) } TRANSFORM_1( "FK45Z", epoch_B ) /* From FK4 with no E-terms. */ /* ------------------------- */ /* This is the same as above, except that we do not need to subtract the E-terms initially as they are already absent. */ } else if ( system == AST__FK4_NO_E ) { VerifyMSMAttrs( target, result, 1, "Equinox Epoch", "astMatch", status ); if ( equinox_B != 1950.0 ) { TRANSFORM_2( "PREBN", equinox_B, 1950.0 ) } TRANSFORM_1( "ADDET", 1950.0 ) TRANSFORM_1( "FK45Z", epoch_B ) /* From FK5. */ /* --------- */ /* We simply need to apply a precession correction for the change of equinox. Omit even this if the equinox is already J2000.0. */ } else if ( system == AST__FK5 ) { VerifyMSMAttrs( target, result, 1, "Equinox", "astMatch", status ); if ( equinox_J != 2000.0 ) { TRANSFORM_2( "PREC", equinox_J, 2000.0 ); } /* From J2000. */ /* ----------- */ /* Convert from J2000 to ICRS, then from ICRS to FK5. */ } else if ( system == AST__J2000 ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_0( "J2000H" ) TRANSFORM_1( "HFK5Z", epoch_J ); /* From geocentric apparent. */ /* ------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__GAPPT ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_2( "AMP", epoch, 2000.0 ) /* From ecliptic coordinates. */ /* -------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__ECLIPTIC ) { VerifyMSMAttrs( target, result, 1, "Equinox", "astMatch", status ); TRANSFORM_1( "ECLEQ", equinox ) /* From helio-ecliptic coordinates. */ /* -------------------------------- */ } else if ( system == AST__HELIOECLIPTIC ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_1( "HEEQ", epoch ) /* From galactic coordinates. */ /* -------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__GALACTIC ) { TRANSFORM_0( "GALEQ" ) /* From ICRS. */ /* ---------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__ICRS ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_1( "HFK5Z", epoch_J ); /* From supergalactic coordinates. */ /* ------------------------------- */ /* Convert to galactic coordinates and then to FK5 J2000.0 equatorial. */ } else if ( system == AST__SUPERGALACTIC ) { TRANSFORM_0( "SUPGAL" ) TRANSFORM_0( "GALEQ" ) /* From AzEl. */ /* ---------- */ /* Rotate from horizon to equator (H2E), shift hour angle into RA (H2R), go from geocentric apparent to FK5 J2000. */ } else if ( system == AST__AZEL ) { VerifyMSMAttrs( target, result, 1, "ObsLon ObsLat Epoch", "astMatch", status ); TRANSFORM_2( "H2E", lat, diurab ) TRANSFORM_1( "H2R", last ) TRANSFORM_2( "AMP", epoch, 2000.0 ) /* From unknown coordinates. */ /* ------------------------- */ /* No conversion is possible. */ } else if ( system == AST__UNKNOWN ) { match = 0; } } /* Convert _from_ FK5 J2000.0 coordinates _to_ the alignment system. */ /* ============================================================ */ /* In this second phase, we convert to the system given by the align_sys argument (if required), still using the properties of the target Frame. */ if ( astOK && match && step2 ) { /* Align in FK4. */ /* --------------- */ /* Convert directly from FK5 J2000.0 to FK4 B1950.0 coordinates at the appropriate epoch. Then, if necessary, apply the old-style FK4 precession model to bring the equinox to that required, with rigorous handling of the E-terms of aberration. */ if ( align_sys == AST__FK4 ) { VerifyMSMAttrs( target, result, 1, "Equinox Epoch", "astMatch", status ); TRANSFORM_1( "FK54Z", epoch_B ) if ( equinox_B != 1950.0 ) { TRANSFORM_1( "SUBET", 1950.0 ) TRANSFORM_2( "PREBN", 1950.0, equinox_B ) TRANSFORM_1( "ADDET", equinox_B ) } /* Align in FK4 with no E-terms. */ /* ------------------------------- */ /* This is the same as above, except that we do not need to add the E-terms at the end. */ } else if ( align_sys == AST__FK4_NO_E ) { VerifyMSMAttrs( target, result, 1, "Equinox Epoch", "astMatch", status ); TRANSFORM_1( "FK54Z", epoch_B ) TRANSFORM_1( "SUBET", 1950.0 ) if ( equinox_B != 1950.0 ) { TRANSFORM_2( "PREBN", 1950.0, equinox_B ) } /* Align in FK5. */ /* ------------- */ /* We simply need to apply a precession correction for the change of equinox. Omit even this if the required equinox is J2000.0. */ } else if ( align_sys == AST__FK5 ) { VerifyMSMAttrs( target, result, 1, "Equinox", "astMatch", status ); if ( equinox_J != 2000.0 ) { TRANSFORM_2( "PREC", 2000.0, equinox_J ) } /* Align in J2000. */ /* --------------- */ /* Mov from FK5 to ICRS, and from ICRS to J2000. */ } else if ( align_sys == AST__J2000 ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_1( "FK5HZ", epoch_J ) TRANSFORM_0( "HJ2000" ) /* Align in geocentric apparent. */ /* ------------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__GAPPT ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_2( "MAP", 2000.0, epoch ) /* Align in ecliptic coordinates. */ /* -------------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__ECLIPTIC ) { VerifyMSMAttrs( target, result, 1, "Equinox", "astMatch", status ); TRANSFORM_1( "EQECL", equinox ) /* Align in helio-ecliptic coordinates. */ /* ------------------------------------ */ } else if ( align_sys == AST__HELIOECLIPTIC ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_1( "EQHE", epoch ) /* Align in galactic coordinates. */ /* -------------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__GALACTIC ) { TRANSFORM_0( "EQGAL" ) /* Align in ICRS. */ /* -------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__ICRS ) { VerifyMSMAttrs( target, result, 1, "Epoch", "astMatch", status ); TRANSFORM_1( "FK5HZ", epoch_J ) /* Align in supergalactic coordinates. */ /* ------------------------------------- */ /* Convert to galactic coordinates and then to supergalactic. */ } else if ( align_sys == AST__SUPERGALACTIC ) { TRANSFORM_0( "EQGAL" ) TRANSFORM_0( "GALSUP" ) /* Align in AzEl coordinates. */ /* -------------------------- */ /* Go from FK5 J2000 to geocentric apparent (MAP), shift RA into hour angle (R2H), rotate from equator to horizon (E2H). */ } else if ( align_sys == AST__AZEL ) { VerifyMSMAttrs( target, result, 1, "ObsLon ObsLat Epoch", "astMatch", status ); TRANSFORM_2( "MAP", 2000.0, epoch ) TRANSFORM_1( "R2H", last ) TRANSFORM_2( "E2H", lat, diurab ) /* Align in unknown coordinates. */ /* ------------------------------- */ /* No conversion is possible. */ } else if ( align_sys == AST__UNKNOWN ) { match = 0; } } /* Convert _from_ the alignment system _to_ FK5 J2000.0 coordinates */ /* =========================================================== */ /* In this third phase, we convert from the alignment system (if required) to the intermediate FK5 J2000 system, using the properties of the result SkyFrame. */ /* Obtain the sky coordinate system, equinox, epoch, etc, of the result SkyFrame. */ system = result_system; equinox = result_equinox; epoch = result_epoch; diurab = GetDiurab( result, status ); last = GetLAST( result, status ); lat = astGetObsLat( result ); /* Convert the equinox and epoch values (stored as Modified Julian Dates) into the equivalent Besselian and Julian epochs (as decimal years). */ if( astOK ) { equinox_B = palEpb( equinox ); equinox_J = palEpj( equinox ); epoch_B = palEpb( epoch ); epoch_J = palEpj( epoch ); } /* Check we need to do the conversion. */ if ( astOK && match && step3 ) { /* Formulate the conversion... */ /* From FK4. */ /* --------- */ /* If necessary, apply the old-style FK4 precession model to bring the equinox to B1950.0, with rigorous handling of the E-terms of aberration. Then convert directly to FK5 J2000.0 coordinates. */ if ( align_sys == AST__FK4 ) { VerifyMSMAttrs( target, result, 3, "Equinox Epoch", "astMatch", status ); if ( equinox_B != 1950.0 ) { TRANSFORM_1( "SUBET", equinox_B ) TRANSFORM_2( "PREBN", equinox_B, 1950.0 ) TRANSFORM_1( "ADDET", 1950.0 ) } TRANSFORM_1( "FK45Z", epoch_B ) /* From FK4 with no E-terms. */ /* ------------------------- */ /* This is the same as above, except that we do not need to subtract the E-terms initially as they are already absent. */ } else if ( align_sys == AST__FK4_NO_E ) { VerifyMSMAttrs( target, result, 3, "Equinox Epoch", "astMatch", status ); if ( equinox_B != 1950.0 ) { TRANSFORM_2( "PREBN", equinox_B, 1950.0 ) } TRANSFORM_1( "ADDET", 1950.0 ) TRANSFORM_1( "FK45Z", epoch_B ) /* From FK5. */ /* --------- */ /* We simply need to apply a precession correction for the change of equinox. Omit even this if the equinox is already J2000.0. */ } else if ( align_sys == AST__FK5 ) { VerifyMSMAttrs( target, result, 3, "Equinox", "astMatch", status ); if ( equinox_J != 2000.0 ) { TRANSFORM_2( "PREC", equinox_J, 2000.0 ); } /* From geocentric apparent. */ /* ------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__GAPPT ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_2( "AMP", epoch, 2000.0 ) /* From ecliptic coordinates. */ /* -------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__ECLIPTIC ) { VerifyMSMAttrs( target, result, 3, "Equinox", "astMatch", status ); TRANSFORM_1( "ECLEQ", equinox ) /* From helio-ecliptic coordinates. */ /* -------------------------------- */ } else if ( align_sys == AST__HELIOECLIPTIC ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_1( "HEEQ", epoch ) /* From galactic coordinates. */ /* -------------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__GALACTIC ) { TRANSFORM_0( "GALEQ" ) /* From ICRS. */ /* ---------- */ /* This conversion is supported directly by SLALIB. */ } else if ( align_sys == AST__ICRS ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_1( "HFK5Z", epoch_J ) /* From J2000. */ /* ----------- */ /* From J2000 to ICRS, and from ICRS to FK5. */ } else if ( align_sys == AST__J2000 ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_0( "J2000H" ) TRANSFORM_1( "HFK5Z", epoch_J ) /* From supergalactic coordinates. */ /* ------------------------------- */ /* Convert to galactic coordinates and then to FK5 J2000.0 equatorial. */ } else if ( align_sys == AST__SUPERGALACTIC ) { TRANSFORM_0( "SUPGAL" ) TRANSFORM_0( "GALEQ" ) /* From AzEl. */ /* ---------- */ /* Rotate from horizon to equator (H2E), shift hour angle into RA (H2R), go from geocentric apparent to FK5 J2000. */ } else if ( align_sys == AST__AZEL ) { VerifyMSMAttrs( target, result, 3, "ObsLon ObsLat Epoch", "astMatch", status ); TRANSFORM_2( "H2E", lat, diurab ) TRANSFORM_1( "H2R", last ) TRANSFORM_2( "AMP", epoch, 2000.0 ) /* From unknown coordinates. */ /* ------------------------------- */ /* No conversion is possible. */ } else if ( align_sys == AST__UNKNOWN ) { match = 0; } } /* Convert _from_ FK5 J2000.0 coordinates. */ /* ======================================= */ /* In this fourth and final phase, we convert to the result coordinate system from the intermediate FK5 J2000 sky coordinates generated above. */ if ( astOK && match && step4 ) { /* To FK4. */ /* ------- */ /* Convert directly from FK5 J2000.0 to FK4 B1950.0 coordinates at the appropriate epoch. Then, if necessary, apply the old-style FK4 precession model to bring the equinox to that required, with rigorous handling of the E-terms of aberration. */ if ( system == AST__FK4 ) { VerifyMSMAttrs( target, result, 3, "Equinox Epoch", "astMatch", status ); TRANSFORM_1( "FK54Z", epoch_B ) if ( equinox_B != 1950.0 ) { TRANSFORM_1( "SUBET", 1950.0 ) TRANSFORM_2( "PREBN", 1950.0, equinox_B ) TRANSFORM_1( "ADDET", equinox_B ) } /* To FK4 with no E-terms. */ /* ----------------------- */ /* This is the same as above, except that we do not need to add the E-terms at the end. */ } else if ( system == AST__FK4_NO_E ) { VerifyMSMAttrs( target, result, 3, "Equinox Epoch", "astMatch", status ); TRANSFORM_1( "FK54Z", epoch_B ) TRANSFORM_1( "SUBET", 1950.0 ) if ( equinox_B != 1950.0 ) { TRANSFORM_2( "PREBN", 1950.0, equinox_B ) } /* To FK5. */ /* ------- */ /* We simply need to apply a precession correction for the change of equinox. Omit even this if the required equinox is J2000.0. */ } else if ( system == AST__FK5 ) { VerifyMSMAttrs( target, result, 3, "Equinox", "astMatch", status ); if ( equinox_J != 2000.0 ) { TRANSFORM_2( "PREC", 2000.0, equinox_J ) } /* To geocentric apparent. */ /* ----------------------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__GAPPT ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_2( "MAP", 2000.0, epoch ) /* To ecliptic coordinates. */ /* ------------------------ */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__ECLIPTIC ) { VerifyMSMAttrs( target, result, 3, "Equinox", "astMatch", status ); TRANSFORM_1( "EQECL", equinox ) /* To helio-ecliptic coordinates. */ /* ------------------------------ */ } else if ( system == AST__HELIOECLIPTIC ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_1( "EQHE", epoch ) /* To galactic coordinates. */ /* ------------------------ */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__GALACTIC ) { TRANSFORM_0( "EQGAL" ) /* To ICRS. */ /* -------- */ /* This conversion is supported directly by SLALIB. */ } else if ( system == AST__ICRS ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_1( "FK5HZ", epoch_J ) /* To J2000. */ /* --------- */ /* From FK5 to ICRS, then from ICRS to J2000. */ } else if ( system == AST__J2000 ) { VerifyMSMAttrs( target, result, 3, "Epoch", "astMatch", status ); TRANSFORM_1( "FK5HZ", epoch_J ) TRANSFORM_0( "HJ2000" ) /* To supergalactic coordinates. */ /* ----------------------------- */ /* Convert to galactic coordinates and then to supergalactic. */ } else if ( system == AST__SUPERGALACTIC ) { TRANSFORM_0( "EQGAL" ) TRANSFORM_0( "GALSUP" ) /* To AzEl */ /* ------- */ /* Go from FK5 J2000 to geocentric apparent (MAP), shift RA into hour angle (R2H), rotate from equator to horizon (E2H). */ } else if ( system == AST__AZEL ) { VerifyMSMAttrs( target, result, 3, "ObsLon ObsLat Epoch", "astMatch", status ); TRANSFORM_2( "MAP", 2000.0, epoch ) TRANSFORM_1( "R2H", last ) TRANSFORM_2( "E2H", lat, diurab ) /* To unknown coordinates. */ /* ----------------------------- */ /* No conversion is possible. */ } else if ( system == AST__UNKNOWN ) { match = 0; } } /* See of the slamap created above is effectively a unit mapping to within the tolerance of the more accurate SkyFrame (target or result). */ isunit = TestSlaUnit( target, result, slamap, status ); /* Now need to take account of the possibility that the input or output SkyFrame may represent an offset system rather than a coordinate system. Form the Mapping from the target coordinate system to the associated offset system. A UnitMap is returned if the target does not use an offset system. */ omap = SkyOffsetMap( target, status ); /* Invert it to get the Mapping from the actual used system (whther offsets or coordinates) to the coordinate system. */ astInvert( omap ); /* Combine it with the slamap created earlier, so that its coordinate outputs feed the inputs of the slamap. We only do this if the slamap is not effectively a unit mapping. Annul redundant pointers afterwards. */ if( ! isunit ) { tmap = (AstMapping *) astCmpMap( omap, slamap, 1, "", status ); } else { tmap = astClone( omap ); } omap = astAnnul( omap ); slamap =astAnnul( slamap ); /* Now form the Mapping from the result coordinate system to the associated offset system. A UnitMap is returned if the result does not use an offset system. */ omap = SkyOffsetMap( result, status ); /* Combine it with the above CmpMap, so that the CmpMap outputs feed the new Mapping inputs. Annul redundant pointers afterwards. */ tmap2 = (AstMapping *) astCmpMap( tmap, omap, 1, "", status ); omap =astAnnul( omap ); tmap =astAnnul( tmap ); /* Simplify the Mapping produced above (this eliminates any redundant conversions) and annul the original pointer. */ *map = astSimplify( tmap2 ); tmap2 = astAnnul( tmap2 ); /* If an error occurred, annul the returned Mapping and clear the returned values. */ if ( !astOK ) { *map = astAnnul( *map ); match = -1; } /* Return the result. */ return match; /* Undefine macros local to this function. */ #undef MAX_ARGS #undef TRANSFORM_0 #undef TRANSFORM_1 #undef TRANSFORM_2 #undef TRANSFORM_3 } static int Match( AstFrame *template_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 "skyframe.h" * int Match( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result, int *status ) * Class Membership: * SkyFrame member function (over-rides the protected astMatch method * inherited from the Frame class). * Description: * This function matches a "template" SkyFrame to a "target" Frame and * determines whether it is possible to convert coordinates between them. * If it is, a mapping that performs the transformation is returned along * with a new Frame that describes the coordinate system that results when * this mapping is applied to the "target" coordinate system. In addition, * information is returned to allow the axes in this "result" Frame to be * associated with the corresponding axes in the "target" and "template" * Frames from which they are derived. * Parameters: * template * Pointer to the template SkyFrame. This describes the coordinate system * (or set of possible coordinate systems) into which we wish to convert * our coordinates. * target * Pointer to the target Frame. This describes the coordinate system in * which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case. * 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 template SkyFrame axis from which * it is derived. If it is not derived from any template SkyFrame 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 and the template Frames. In * particular, when the template allows the possibility of transformaing * to any one of a set of alternative coordinate systems, the "result" * Frame will indicate which of the alternatives was used. * 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. * Implementation Notes: * This implementation addresses the matching of a SkyFrame class object to * any other class of Frame. A SkyFrame will match any class of SkyFrame * (i.e. possibly from a derived class) but will not match a less * specialised class of Frame. */ /* Local Variables: */ AstFrame *frame0; /* Pointer to Frame underlying axis 0 */ AstFrame *frame1; /* Pointer to Frame underlying axis 1 */ AstSkyFrame *template; /* Pointer to template SkyFrame structure */ int iaxis; /* Axis index */ int iaxis0; /* Axis index underlying axis 0 */ int iaxis1; /* Axis index underlying axis 1 */ int match; /* Coordinate conversion possible? */ int swap1; /* Template axes swapped? */ int swap2; /* Target axes swapped? */ int swap; /* Additional axis swap needed? */ int target_axis0; /* Index of 1st SkyFrame axis in the target */ int target_axis1; /* Index of 2nd SkyFrame axis in the target */ int target_naxes; /* Number of target axes */ /* Initialise the returned values. */ *template_axes = NULL; *target_axes = NULL; *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Initialise variables to avoid "used of uninitialised variable" messages from dumb compilers. */ swap = 0; target_axis0 = -1; target_axis1 = -1; /* Obtain a pointer to the template SkyFrame structure. */ template = (AstSkyFrame *) template_frame; /* Obtain the number of axes in the target Frame. */ target_naxes = astGetNaxes( target ); /* The first criterion for a match is that the template matches as a Frame class object. This ensures that the number of axes (2) and domain, etc. of the target Frame are suitable. Invoke the parent "astMatch" method to verify this. */ match = (*parent_match)( template_frame, target, matchsub, template_axes, target_axes, map, result, status ); /* If a match was found, annul the returned objects, which are not needed, but keep the memory allocated for the axis association arrays, which we will re-use. */ if ( astOK && match ) { *map = astAnnul( *map ); *result = astAnnul( *result ); } /* If OK so far, obtain pointers to the primary Frames which underlie all target axes. Stop when a SkyFrame axis is found. */ if ( match && astOK ) { match = 0; for( iaxis = 0; iaxis < target_naxes; iaxis++ ) { astPrimaryFrame( target, iaxis, &frame0, &iaxis0 ); if( astIsASkyFrame( frame0 ) ) { target_axis0 = iaxis; match = 1; break; } else { frame0 = astAnnul( frame0 ); } } /* Check at least one SkyFrame axis was found it the target. */ if( match ) { /* If so, search the remaining target axes for another axis that is derived from the same SkyFrame. */ match = 0; for( iaxis++ ; iaxis < target_naxes; iaxis++ ) { astPrimaryFrame( target, iaxis, &frame1, &iaxis1 ); if( frame1 == frame0 ) { target_axis1 = iaxis; frame1 = astAnnul( frame1 ); match = 1; break; } else { frame1 = astAnnul( frame1 ); } } /* Annul the remaining Frame pointer used in the above tests. */ frame0 = astAnnul( frame0 ); } /* If this test is passed, we can now test that the underlying axis indices are 0 and 1, in either order. This then ensures that we have a single SkyFrame (not a compound Frame) with both axes present. */ if ( match && astOK ) { match = ( ( ( iaxis0 == 0 ) && ( iaxis1 == 1 ) ) || ( ( iaxis1 == 0 ) && ( iaxis0 == 1 ) ) ); } } /* If a possible match has been detected, we must now decide how the order of the axes in the result Frame relates to the order of axes in the target Frame. There are two factors involved. The first depends on whether the axis permutation array for the template SkyFrame (whose method we are executing) causes an axis reversal. Determine this by permuting axis index zero. */ if ( astOK && match ) { swap1 = ( astValidateAxis( template, 0, 1, "astMatch" ) != 0 ); /* The second factor depends on whether the axes of the underlying primary SkyFrame are reversed when seen in the target Frame. */ swap2 = ( iaxis0 != 0 ); /* Combine these to determine if an additional axis swap will be needed. */ swap = ( swap1 != swap2 ); /* Now check to see if this additional swap is permitted by the template's Permute attribute. */ match = ( !swap || astGetPermute( template ) ); } /* If the Frames still match, we next set up the axis association arrays. */ if ( astOK && match ) { /* If the target axis order is to be preserved, then the target axis association involves no permutation but the template axis association may involve an axis swap. */ if ( astGetPreserveAxes( template ) ) { (*template_axes)[ 0 ] = swap; (*template_axes)[ 1 ] = !swap; (*target_axes)[ 0 ] = target_axis0; (*target_axes)[ 1 ] = target_axis1; /* Otherwise, any swap applies to the target axis association instead. */ } else { (*template_axes)[ 0 ] = 0; (*template_axes)[ 1 ] = 1; (*target_axes)[ 0 ] = swap ? target_axis1 : target_axis0; (*target_axes)[ 1 ] = swap ? target_axis0 : target_axis1; } /* Use the target's "astSubFrame" method to create a new Frame (the result Frame) with copies of the target axes in the required order. This process also overlays the template attributes on to the target Frame and returns a Mapping between the target and result Frames which effects the required coordinate conversion. */ match = astSubFrame( target, template, 2, *target_axes, *template_axes, map, result ); } /* If an error occurred, or conversion to the result Frame's coordinate system was not possible, then free all memory, annul the returned objects, and reset the returned value. */ if ( !astOK || !match ) { *template_axes = astFree( *template_axes ); *target_axes = astFree( *target_axes ); if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } 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 "skyframe.h" * void MatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes ) * int *status ) * Class Membership: * SkyFrame 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 *resfrm; AstMapping *resmap; AstSkyFrame *frm2; int *frm2_axes; int *frm1_axes; int max_axes; int min_axes; int preserve_axes; /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the SkyFrame. */ frm2 = (AstSkyFrame *) frm2_frame; /* Temporarily ensure that the PreserveAxes attribute is non-zero in the first supplied Frame. This means thte result Frame returned by astMatch below will have the axis count and order of the target Frame (i.e. "pfrm"). */ if( astTestPreserveAxes( frm1 ) ) { preserve_axes = astGetPreserveAxes( frm1 ) ? 1 : 0; } else { preserve_axes = -1; } astSetPreserveAxes( frm1, 1 ); /* Temporarily ensure that the MaxAxes and MinAxes attributes in the first supplied Frame are set so the Frame can be used as a template in astMatch for matching any number of axes. */ if( astTestMaxAxes( frm1 ) ) { max_axes = astGetMaxAxes( frm1 ); } else { max_axes = -1; } astSetMaxAxes( frm1, 10000 ); if( astTestMinAxes( frm1 ) ) { min_axes = astGetMinAxes( frm1 ); } else { min_axes = -1; } astSetMinAxes( frm1, 1 ); /* Attempt to find a sub-frame within the first supplied Frame that corresponds to the supplied SkyFrame. */ if( astMatch( frm1, frm2, 1, &frm1_axes, &frm2_axes, &resmap, &resfrm ) ) { /* If successfull, Store the one-based index within "frm1" of the corresponding axes. */ axes[ 0 ] = frm1_axes[ 0 ] + 1; axes[ 1 ] = frm1_axes[ 1 ] + 1; /* Free resources */ frm1_axes = astFree( frm1_axes ); frm2_axes = astFree( frm2_axes ); resmap = astAnnul( resmap ); resfrm = astAnnul( resfrm ); /* If no corresponding SkyFrame was found store zeros in the returned array. */ } else { axes[ 0 ] = 0; axes[ 1 ] = 0; } /* Re-instate the original attribute values in the first supplied Frame. */ if( preserve_axes == -1 ) { astClearPreserveAxes( frm1 ); } else { astSetPreserveAxes( frm1, preserve_axes ); } if( max_axes == -1 ) { astClearMaxAxes( frm1 ); } else { astSetMaxAxes( frm1, max_axes ); } if( min_axes == -1 ) { astClearMinAxes( frm1 ); } else { astSetMinAxes( frm1, min_axes ); } } static void Norm( AstFrame *this_frame, double value[], int *status ) { /* * Name: * Norm * Purpose: * Normalise a set of SkyFrame coordinates. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void Norm( AstAxis *this, double value[], int *status ) * Class Membership: * SkyFrame member function (over-rides the astNorm method inherited * from the Frame class). * Description: * This function converts a set of SkyFrame coordinate values, * 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. * * This is done by wrapping coordinates so that the latitude lies * in the range (-pi/2.0) <= latitude <= (pi/2.0). If the NegLon * attribute is zero (the default), then the wrapped longitude value * lies in the range 0.0 <= longitude < (2.0*pi). Otherwise, it lies * in the range -pi <= longitude < pi. * Parameters: * this * Pointer to the SkyFrame. * value * An array of double, with one element for each SkyFrame 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Axis permutation array */ double sky_lat; /* Sky latitude value */ double sky_long; /* Sky longitude value */ double v[ 2 ]; /* Permuted value coordinates */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Obtain the sky longitude and latitude values, allowing for any axis permutation. */ v[ perm[ 0 ] ] = value[ 0 ]; v[ perm[ 1 ] ] = value[ 1 ]; sky_long = v[ 0 ]; sky_lat = v[ 1 ]; /* Test if both values are OK (i.e. not "bad"). */ if ( ( sky_long != AST__BAD ) && ( sky_lat != AST__BAD ) ) { /* Fold the longitude value into the range 0 to 2*pi and the latitude into the range -pi to +pi. */ sky_long = palDranrm( sky_long ); sky_lat = palDrange( sky_lat ); /* If the latitude now exceeds pi/2, shift the longitude by pi in whichever direction will keep it in the range 0 to 2*pi. */ if ( sky_lat > ( pi / 2.0 ) ) { sky_long += ( sky_long < pi ) ? pi : -pi; /* Reflect the latitude value through the pole, so it lies in the range 0 to pi/2. */ sky_lat = pi - sky_lat; /* If the latitude is less than -pi/2, shift the longitude in the same way as above. */ } else if ( sky_lat < -( pi / 2.0 ) ) { sky_long += ( sky_long < pi ) ? pi : -pi; /* But reflect the latitude through the other pole, so it lies in the range -pi/2 to 0. */ sky_lat = -pi - sky_lat; } /* If only the longitude value is valid, wrap it into the range 0 to 2*pi. */ } else if ( sky_long != AST__BAD ) { sky_long = palDranrm( sky_long ); /* If only the latitude value is valid, wrap it into the range -pi to +pi. */ } else if ( sky_lat != AST__BAD ) { sky_lat = palDrange( sky_lat ); /* Then refect through one of the poles (as above), if necessary, to move it into the range -pi/2 to +pi/2. */ if ( sky_lat > ( pi / 2.0 ) ) { sky_lat = pi - sky_lat; } else if ( sky_lat < -( pi / 2.0 ) ) { sky_lat = -pi - sky_lat; } } /* Convert 2*pi longitude into zero. Allow for a small error. */ if ( fabs( sky_long - ( 2.0 * pi ) ) <= ( 2.0 * pi ) * ( DBL_EPSILON * (double) FLT_RADIX ) ) sky_long = 0.0; /* If the NegLon attribute is set, and the longitude value is good, convert it into the range -pi to +pi. */ if( sky_long != AST__BAD && astGetNegLon( this ) ) { sky_long = palDrange( sky_long ); } /* Return the new values, allowing for any axis permutation. */ v[ 0 ] = sky_long; v[ 1 ] = sky_lat; value[ 0 ] = v[ perm[ 0 ] ]; value[ 1 ] = v[ perm[ 1 ] ]; } } 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 "skyframe.h" * void astNormBox( AstFrame *this, double lbnd[], double ubnd[], * AstMapping *reg, int *status ) * Class Membership: * SkyFrame 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Axis permutation array */ double lb[ 2 ]; /* Permuted lower bounds */ double t; /* Temporary storage */ double t2; /* Temporary storage */ double ub[ 2 ]; /* Permuted upper bounds */ double x[2]; /* 1st axis values at poles */ double xo[2]; /* Tested 1st axis values at poles */ double y[2]; /* 2nd axis values at poles */ double yo[2]; /* Tested 2nd axis values at poles */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if( perm ) { /* Obtain the sky longitude and latitude limits, allowing for any axis permutation. */ lb[ perm[ 0 ] ] = lbnd[ 0 ]; lb[ perm[ 1 ] ] = lbnd[ 1 ]; ub[ perm[ 0 ] ] = ubnd[ 0 ]; ub[ perm[ 1 ] ] = ubnd[ 1 ]; /* Use the supplied Mapping to test if box includes either pole. */ if( perm[ 0 ] == 0 ) { x[ 0 ] = 0.0; y[ 0 ] = AST__DPIBY2; x[ 1 ] = 0.0; y[ 1 ] = -AST__DPIBY2; } else { x[ 0 ] = AST__DPIBY2; y[ 0 ] = 0.0; x[ 1 ] = -AST__DPIBY2; y[ 1 ] = 0.0; } astTran2( reg, 2, x, y, 1, xo, yo ); /* If the box includes the north pole... */ if( xo[ 0 ] != AST__BAD ) { /* Find the lowest latitude after normalisation. */ if( ub[ 1 ] != AST__BAD && lb[ 1 ] != AST__BAD ){ t = palDrange( ub[ 1 ] ); t2 = palDrange( lb[ 1 ] ); if( t2 < t ) t = t2; } else { t = AST__BAD; } /* Set the lower returned limit to this value and the upper returned limit to +90 degs */ lb[ 1 ] = t; ub[ 1 ] = AST__DPIBY2; /* Set the longitude range to 0 to 2PI */ lb[ 0 ] = 0; ub[ 0 ] = 2*AST__DPI; } /* If the box includes the south pole... */ if( xo[ 1 ] != AST__BAD ) { /* Find the highest latitude after normalisation. */ if( ub[ 1 ] != AST__BAD && lb[ 1 ] != AST__BAD ){ t = palDrange( ub[ 1 ] ); t2 = palDrange( lb[ 1 ] ); if( t2 > t ) t = t2; } else { t = AST__BAD; } /* Set the upper returned limit to this value and the lower returned limit to -90 degs */ lb[ 1 ] = -AST__DPIBY2; ub[ 1 ] = t; /* Set the longitude range to 0 to 2PI */ lb[ 0 ] = 0; ub[ 0 ] = 2*AST__DPI; } /* Return the modified limits. */ lbnd[ 0 ] = lb[ perm[ 0 ] ]; lbnd[ 1 ] = lb[ perm[ 1 ] ]; ubnd[ 0 ] = ub[ perm[ 0 ] ]; ubnd[ 1 ] = ub[ perm[ 1 ] ]; } } 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: * Private function. * Synopsis: * #include "skyframe.h" * void Offset( AstFrame *this, * const double point1[], const double point2[], * double offset, double point3[], int *status ) * Class Membership: * SkyFrame member function (over-rides the astOffset method * inherited from the Frame class). * Description: * This function finds the SkyFrame coordinate values of a point * which is offset a specified distance along the geodesic curve * (i.e. great circle) between two other points. * Parameters: * this * Pointer to the SkyFrame. * point1 * An array of double, with one element for each SkyFrame 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 SkyFrame 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, in radians. 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 SkyFrame 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Pointer to axis permutation array */ double mrot[ 3 ][ 3 ]; /* Rotation matrix */ double p1[ 2 ]; /* Permuted coordinates for point1 */ double p2[ 2 ]; /* Permuted coordinates for point2 */ double p3[ 2 ]; /* Permuted coordinates for point3 */ double scale; /* Scale factor */ double v1[ 3 ]; /* 3-vector for p1 */ double v2[ 3 ]; /* 3-vector for p2 */ double v3[ 3 ]; /* 3-vector for p3 */ double vmod; /* Modulus of vector */ double vrot[ 3 ]; /* Vector along rotation axis */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Check that all supplied coordinates are OK. If not, generate "bad" output coordinates. */ if ( ( point1[ 0 ] == AST__BAD ) || ( point1[ 1 ] == AST__BAD ) || ( point2[ 0 ] == AST__BAD ) || ( point2[ 1 ] == AST__BAD ) ) { point3[ 0 ] = AST__BAD; point3[ 1 ] = AST__BAD; /* Otherwise, apply the axis permutation array to obtain the coordinates of the two input points in the required (longitude,latitude) order. */ } else { p1[ perm[ 0 ] ] = point1[ 0 ]; p1[ perm[ 1 ] ] = point1[ 1 ]; p2[ perm[ 0 ] ] = point2[ 0 ]; p2[ perm[ 1 ] ] = point2[ 1 ]; /* Convert each point into a 3-vector of unit length. */ palDcs2c( p1[ 0 ], p1[ 1 ], v1 ); palDcs2c( p2[ 0 ], p2[ 1 ], v2 ); /* Find the cross product between these two vectors (the vector order is reversed here to compensate for the sense of rotation introduced by palDav2m and palDmxv below). */ palDvxv( v2, v1, v3 ); /* Normalise the cross product vector, also obtaining its original modulus. */ palDvn( v3, vrot, &vmod ); /* If the original modulus was zero, the input points are either coincident or diametrically opposite, so do not uniquely define a great circle. In either case, we can only generate output coordinates if the offset required is an exact multiple of pi. If it is, generate the 3-vector that results from rotating the first input point through this angle. */ if ( vmod == 0.0 ) { if ( sin( offset ) == 0.0 ) { scale = cos( offset ); v3[ 0 ] = v1[ 0 ] * scale; v3[ 1 ] = v1[ 1 ] * scale; v3[ 2 ] = v1[ 2 ] * scale; /* Convert the 3-vector back into spherical cooordinates and then constrain the longitude result to lie in the range 0 to 2*pi (palDcc2s doesn't do this itself). */ palDcc2s( v3, &p3[ 0 ], &p3[ 1 ] ); p3[ 0 ] = palDranrm( p3[ 0 ] ); /* If the offset was not a multiple of pi, generate "bad" output coordinates. */ } else { p3[ 0 ] = AST__BAD; p3[ 1 ] = AST__BAD; } /* If the two input points define a great circle, scale the normalised cross product vector to make its length equal to the required offset (angle) between the first input point and the result. */ } else { vrot[ 0 ] *= offset; vrot[ 1 ] *= offset; vrot[ 2 ] *= offset; /* Generate the rotation matrix that implements this rotation and use it to rotate the first input point (3-vector) to give the required result (3-vector). */ palDav2m( vrot, mrot ); palDmxv( mrot, v1, v3 ); /* Convert the 3-vector back into spherical cooordinates and then constrain the longitude result to lie in the range 0 to 2*pi. */ palDcc2s( v3, &p3[ 0 ], &p3[ 1 ] ); p3[ 0 ] = palDranrm( p3[ 0 ] ); } /* Permute the result coordinates to undo the effect of the SkyFrame axis permutation array. */ point3[ 0 ] = p3[ perm[ 0 ] ]; point3[ 1 ] = p3[ perm[ 1 ] ]; } } } static AstMapping *SkyOffsetMap( AstSkyFrame *this, int *status ){ /* *++ * Name: c astSkyOffsetMap f AST_SKYOFFSETMAP * Purpose: * Returns a Mapping which goes from absolute coordinates to offset * coordinates. * Type: * Public virtual function. * Synopsis: c #include "skyframe.h" c AstMapping *astSkyOffsetMap( AstSkyFrame *this ) f RESULT = AST_SKYOFFSETMAP( THIS, STATUS ) * Class Membership: * SkyFrame method. * Description: * This function returns a Mapping in which the forward transformation * transforms a position in the coordinate system given by the System * attribute of the supplied SkyFrame, into the offset coordinate system * specified by the SkyRef, SkyRefP and SkyRefIs attributes of the * supplied SkyFrame. * * A UnitMap is returned if the SkyFrame does not define an offset * coordinate system. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the SkyFrame. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astSkyOffsetMap() f AST_SKYOFFSETMAP = INTEGER * Pointer to the returned Mapping. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ AstCmpMap *map3; /* Partial Mapping. */ AstMapping *result; /* The returned Mapping. */ AstMatrixMap *map1; /* Spherical rotation in 3D cartesian space */ AstSphMap *map2; /* 3D Cartesian to 2D spherical Mapping */ double *vx; /* Pointer to x unit vector. */ double *vy; /* Pointer to y unit vector. */ double *vz; /* Pointer to z unit vector. */ double mat[ 9 ]; /* Spherical rotation matrix */ double vmod; /* Length of vector (+ve) */ double vp[ 3 ]; /* Unit vector representin SkyRefP position. */ int lataxis; /* Index of the latitude axis */ int lonaxis; /* Index of the longitude axis */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Return a UnitMap if the offset coordinate system is not defined. */ if( astGetSkyRefIs( this ) == AST__IGNORED_REF || ( !astTestSkyRef( this, 0 ) && !astTestSkyRef( this, 1 ) ) ) { result = (AstMapping *) astUnitMap( 2, "", status ); /* Otherwise... */ } else { /* Get the longitude and latitude at the reference point and at a point on the primary meridian. */ lataxis = astGetLatAxis( this ); lonaxis = 1 - lataxis; /* Initialise pointers to the rows of the 3x3 matrix. Each row will be used to store a unit vector. */ vx = mat; vy = mat + 3; vz = mat + 6; /* The following trig converts between (longitude,latitude) and (x,y,z) on a unit sphere, in which (0,0) is at (1,0,0), (0,pi/2) is (0,0,1) and (pi/2,0) is at (0,1,0). */ /* First deal with cases where the SkyRef attribute holds the standard coords at the origin of the offset coordinate system. */ if( astGetSkyRefIs( this ) == AST__ORIGIN_REF ) { /* Convert each point into a 3-vector of unit length. The SkyRef position defines the X axis in the offset coord system. */ palDcs2c( astGetSkyRef( this, lonaxis ), astGetSkyRef( this, lataxis ), vx ); palDcs2c( astGetSkyRefP( this, lonaxis ), astGetSkyRefP( this, lataxis ), vp ); /* The Y axis is perpendicular to both the X axis and the skyrefp position. That is, it is parallel to the cross product of the 2 above vectors.*/ palDvxv( vp, vx, vy ); /* Normalize the y vector. */ palDvn( vy, vy, &vmod ); /* Report an error if the modulus of the vector is zero.*/ if( vmod == 0.0 ) { astError( AST__BADOC, "astConvert(%s): The position specified by the SkyRefP " "attribute is either coincident, with or opposite to, the " "position specified by the SkyRef attribute.", status, astGetClass( this ) ); /* If OK, form the Z axis as the cross product of the x and y axes. */ } else { palDvxv( vx, vy, vz ); } /* Now deal with cases where the SkyRef attribute holds the standard coords at the north pole of the offset coordinate system. */ } else { /* Convert each point into a 3-vector of unit length. The SkyRef position defines the Z axis in the offset coord system. */ palDcs2c( astGetSkyRef( this, lonaxis ), astGetSkyRef( this, lataxis ), vz ); palDcs2c( astGetSkyRefP( this, lonaxis ), astGetSkyRefP( this, lataxis ), vp ); /* The Y axis is perpendicular to both the Z axis and the skyrefp position. That is, it is parallel to the cross product of the 2 above vectors.*/ palDvxv( vz, vp, vy ); /* Normalize the y vector. */ palDvn( vy, vy, &vmod ); /* Report an error if the modulus of the vector is zero.*/ if( vmod == 0.0 ) { astError( AST__BADOC, "astConvert(%s): The position specified by the SkyRefP " "attribute is either coincident, with or opposite to, the " "position specified by the SkyRef attribute.", status, astGetClass( this ) ); /* If OK, form the X axis as the cross product of the y and z axes. */ } else { palDvxv( vy, vz, vx ); } } /* Create a MatrixMap which implements the above spherical rotation. Each row in this matrix represents one of the unit axis vectors found above. */ map1 = astMatrixMap( 3, 3, 0, mat, "", status ); /* Create a 3D cartesian to 2D spherical Mapping. */ map2 = astSphMap( "UnitRadius=1", status ); /* Form a series CmpMap which converts from 2D (long,lat) in the base System to 2D (long,lat) in the offset coordinate system. */ map3 = astCmpMap( map1, map2, 1, "", status ); astInvert( map2 ); result = (AstMapping *) astCmpMap( map2, map3, 1, "", status ); /* Free resources. */ map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); map3 = astAnnul( map3 ); } /* Annul the returned Mapping if anything has gone wrong. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } 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 at a given bearing. * Type: * Private function. * Synopsis: * #include "skyframe.h" * double Offset2( AstFrame *this_frame, const double point1[2], * double angle, double offset, double point2[2], int *status ) * Class Membership: * SkyFrame member function (over-rides the astOffset2 method * inherited from the Frame class). * Description: * This function finds the SkyFrame coordinate values of a point * which is offset a specified distance along the geodesic curve * (i.e. great circle) at a given angle from a given starting point. * Parameters: * this * Pointer to the SkyFrame. * point1 * An array of double, with one element for each SkyFrame axis. * 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, in radians. If this is positive, it will be towards * the given angle. If it is negative, it will be in the * opposite direction. * point2 * An array of double, with one element for each SkyFrame 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. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Pointer to axis permutation array */ double p1[ 2 ]; /* Permuted coordinates for point1 */ double p2[ 2 ]; /* Permuted coordinates for point2 */ double result; /* The returned answer */ double cosoff; /* Cosine of offset */ double cosa1; /* Cosine of longitude at start */ double cosb1; /* Cosine of latitude at start */ double pa; /* A position angle measured from north */ double q1[ 3 ]; /* Vector PI/2 away from R4 in meridian of R4 */ double q2[ 3 ]; /* Vector PI/2 away from R4 on equator */ double q3[ 3 ]; /* Vector PI/2 away from R4 on great circle */ double r0[ 3 ]; /* Reference position vector */ double r3[ 3 ]; /* Vector PI/2 away from R0 on great circle */ double sinoff; /* Sine of offset */ double sina1; /* Sine of longitude at start */ double sinb1; /* Sine of latitude at start */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Check that all supplied values are OK. If not, generate "bad" output coordinates. */ if ( ( point1[ 0 ] == AST__BAD ) || ( point1[ 1 ] == AST__BAD ) || ( angle == AST__BAD ) || ( offset == AST__BAD ) ) { point2[ 0 ] = AST__BAD; point2[ 1 ] = AST__BAD; /* Otherwise, apply the axis permutation array to obtain the coordinates of the starting point in the required (longitude,latitude) order. */ } else { p1[ perm[ 0 ] ] = point1[ 0 ]; p1[ perm[ 1 ] ] = point1[ 1 ]; /* If the axes are permuted, convert the supplied angle into a position angle. */ pa = ( perm[ 0 ] == 0 )? angle: piby2 - angle; /* Use Shcal to calculate the required vectors R0 (representing the reference point) and R3 (representing the point which is 90 degrees away from the reference point, along the required great circle). The XY plane defines zero latitude, Z is in the direction of increasing latitude, X is towards zero longitude, and Y is towards longitude 90 degrees. */ Shcal( p1[ 0 ], p1[ 1 ], pa, r0, r3, status ); /* Use Shapp to use R0 and R3 to calculate the new position. */ Shapp( offset, r0, r3, p1[ 0 ], p2, status ); /* Normalize the result. */ astNorm( this, p2 ); /* Create the vector Q1 representing the point in the meridian of the required point which has latitude 90 degrees greater than the required point. */ sina1 = sin( p2[ 0 ] ); cosa1 = cos( p2[ 0 ] ); sinb1 = sin( p2[ 1 ] ); cosb1 = cos( p2[ 1 ] ); q1[ 0 ] = -sinb1*cosa1; q1[ 1 ] = -sinb1*sina1; q1[ 2 ] = cosb1; /* Create the vector Q2 representing the point on the equator (i.e. a latitude of zero), which has a longitude 90 degrees to the west of the required point. */ q2[ 0 ] = -sina1; q2[ 1 ] = cosa1; q2[ 2 ] = 0.0; /* Create the vector Q3 representing the point which is 90 degrees away from the required point, along the required great circle. */ cosoff = cos( offset ); sinoff = sin( offset ); q3[ 0 ] = -sinoff*r0[ 0 ] + cosoff*r3[ 0 ]; q3[ 1 ] = -sinoff*r0[ 1 ] + cosoff*r3[ 1 ]; q3[ 2 ] = -sinoff*r0[ 2 ] + cosoff*r3[ 2 ]; /* Calculate the position angle of the great circle at the required point. */ pa = atan2( palDvdv( q3, q2 ), palDvdv( q3, q1 ) ); /* Convert this from a pa into the required angle. */ result = ( perm[ 0 ] == 0 )? pa: piby2 - pa; /* Ensure that the end angle is in the range 0 to 2*pi. */ result = palDranrm( result ); /* Permute the result coordinates to undo the effect of the SkyFrame axis permutation array. */ point2[ 0 ] = p2[ perm[ 0 ] ]; point2[ 1 ] = p2[ perm[ 1 ] ]; } } /* Return the result. */ return result; } static void Overlay( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { /* * Name: * Overlay * Purpose: * Overlay the attributes of a template SkyFrame on to another Frame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void Overlay( AstFrame *template, const int *template_axes, * AstFrame *result, int *status ) * Class Membership: * SkyFrame member function (over-rides the protected astOverlay method * inherited from the Frame class). * Description: * This function overlays attributes of a SkyFrame (the "template") on to * another Frame, so as to over-ride selected attributes of that second * Frame. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which a Frame acquires attributes from the template, but * retains its original attributes (as the default) if new values have not * previously been explicitly set in the template. * * Note that if the result Frame is a SkyFrame and a change of sky * coordinate system occurs as a result of overlaying its System * attribute, then some of its original attribute values may no * longer be appropriate (e.g. the Title, or attributes describing * its axes). In this case, these will be cleared before overlaying * any new values. * Parameters: * template * Pointer to the template SkyFrame, for which values should have been * explicitly set for any attribute which is to be transferred. * template_axes * Pointer to an array of int, with one element for each axis of the * "result" Frame (see below). For each axis in the result frame, the * corresponding element of this array should contain the (zero-based) * index of the template axis to which it corresponds. This array is used * to establish from which template axis any axis-dependent attributes * should be obtained. * * If any axis in the result Frame is not associated with a template * axis, the corresponding element of this array should be set to -1. * * If a NULL pointer is supplied, the template and result axis * indices are assumed to be identical. * result * Pointer to the Frame which is to receive the new attribute values. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - In general, if the result Frame is not from the same class as the * template SkyFrame, or from a class derived from it, then attributes may * exist in the template SkyFrame which do not exist in the result Frame. In * this case, these attributes will not be transferred. */ /* Local Variables: */ AstSystemType new_alignsystem;/* Code identifying new alignment coords */ AstSystemType new_system; /* Code identifying new sky cordinates */ AstSystemType old_system; /* Code identifying old sky coordinates */ int axis; /* Loop counter for result SkyFrame axes */ int skyref_changed; /* Has the SkyRef attribute changed? */ int reset_system; /* Was the template System value cleared? */ int skyframe; /* Result Frame is a SkyFrame? */ int tax0; /* Template axis for result axis 0 */ int tax1; /* Template axis for result axis 1 */ /* Check the global error status. */ if ( !astOK ) return; /* Indicate that we do not need to reset the System attribute of the template. */ reset_system = 0; new_system = AST__UNKNOWN; /* If the result Frame is a SkyFrame, we must test to see if overlaying its System attribute will change the type of sky coordinate system it describes. Determine the value of this attribute for the result and template SkyFrames. We also need to do this if either SkyRef attribute would change. */ skyframe = astIsASkyFrame( result ); if ( skyframe ) { old_system = astGetSystem( result ); new_system = astGetSystem( template ); skyref_changed = ( astGetSkyRef( result, 0 ) != astGetSkyRef( template, 0 ) ) || ( astGetSkyRef( result, 1 ) != astGetSkyRef( template, 1 ) ); /* If the coordinate system will change, any value already set for the result SkyFrame's Title will no longer be appropriate, so clear it. */ if ( new_system != old_system || skyref_changed ) { astClearTitle( result ); /* Test if the old and new sky coordinate systems are similar enough to make use of the same axis attribute values (e.g. if they are both equatorial systems, then they can both use the same axis labels, etc.,so long as the SKyRefIs value has not changed). */ if ( IsEquatorial( new_system, status ) != IsEquatorial( old_system, status ) || skyref_changed ) { /* If necessary, clear inappropriate values for all those axis attributes whose access functions are over-ridden by this class (these access functions will then provide suitable defaults appropriate to the new coordinate system instead). */ for ( axis = 0; axis < 2; axis++ ) { astClearAsTime( result, axis ); astClearDirection( result, axis ); astClearFormat( result, axis ); astClearLabel( result, axis ); astClearSymbol( result, axis ); astClearUnit( result, axis ); } } } /* If the result Frame is not a SkyFrame, we must temporarily clear the System and AlignSystem values since the values used by this class are only appropriate to this class. */ } else { if( astTestSystem( template ) ) { new_system = astGetSystem( template ); astClearSystem( template ); new_alignsystem = astGetAlignSystem( template ); astClearAlignSystem( template ); reset_system = 1; } } /* Invoke the parent class astOverlay method to transfer attributes inherited from the parent class. */ (*parent_overlay)( template, template_axes, result, status ); /* Reset the System and AlignSystem values if necessary */ if( reset_system ) { astSetSystem( template, new_system ); astSetAlignSystem( template, new_alignsystem ); } /* Check if the result Frame is a SkyFrame or from a class derived from SkyFrame. If not, we cannot transfer SkyFrame attributes to it as it is insufficiently specialised. In this case simply omit these attributes. */ if ( skyframe && astOK ) { /* Define a macro that tests whether an attribute is set in the template and, if so, transfers its value to the result. */ #define OVERLAY(attr) \ if ( astTest##attr( template ) ) { \ astSet##attr( result, astGet##attr( template ) ); \ } /* Store template axis indices */ if( template_axes ) { tax0 = template_axes[ 0 ]; tax1 = template_axes[ 1 ]; } else { tax0 = 0; tax1 = 1; } /* Define a similar macro that does the same for SkyFrame specific axis attributes. */ #define OVERLAY2(attr) \ if( astTest##attr( template, tax0 ) ) { \ astSet##attr( result, 0, astGet##attr( template, tax0 ) ); \ } \ if( astTest##attr( template, tax1 ) ) { \ astSet##attr( result, 1, astGet##attr( template, tax1 ) ); \ } /* Use the macro to transfer each SkyFrame attribute in turn. */ OVERLAY(Equinox); OVERLAY(Projection); OVERLAY(NegLon); OVERLAY(SkyTol); OVERLAY(AlignOffset); OVERLAY(SkyRefIs); OVERLAY2(SkyRef); OVERLAY2(SkyRefP); } /* Undefine macros local to this function. */ #undef OVERLAY #undef OVERLAY2 } 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 "skyframe.h" * void Resolve( AstFrame *this, const double point1[], * const double point2[], const double point3[], * double point4[], double *d1, double *d2, int *status ) * Class Membership: * SkyFrame member function (over-rides the 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. * * Each vector is a geodesic curve. For a SkyFrame, these are great * circles on the celestial sphere. * 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 returned value is always * positive. * status * Pointer to the inherited status variable. * Notes: * - 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ const int *perm; /* Pointer to axis permutation array */ double n1[ 3 ]; /* Unit normal to grt crcl thru p1 and p2 */ double n2[ 3 ]; /* Unit normal to grt crcl thru p3 and p4 */ double p1[ 2 ]; /* Permuted coordinates for point1 */ double p2[ 2 ]; /* Permuted coordinates for point2 */ double p3[ 2 ]; /* Permuted coordinates for point3 */ double p4[ 2 ]; /* Permuted coordinates for point4 */ double v1[ 3 ]; /* 3-vector for p1 */ double v2[ 3 ]; /* 3-vector for p2 */ double v3[ 3 ]; /* 3-vector for p3 */ double v4[ 3 ]; /* 3-vector for p4 */ double v5[ 3 ]; /* 3-vector 90 degs away from p1 */ double vmod; /* Modulus of vector */ double vtemp[ 3 ]; /* Temporary vector workspace */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Store initial bad output values. */ point4[ 0 ] = AST__BAD; point4[ 1 ] = AST__BAD; *d1 = AST__BAD; *d2 = AST__BAD; /* Check that all supplied values are OK. */ if ( ( point1[ 0 ] != AST__BAD ) && ( point1[ 1 ] != AST__BAD ) && ( point2[ 0 ] != AST__BAD ) && ( point2[ 1 ] != AST__BAD ) && ( point3[ 0 ] != AST__BAD ) && ( point3[ 1 ] != AST__BAD ) ) { /* If so, obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); if ( astOK ) { /* Apply the axis permutation array to obtain the coordinates of the three supplied point in the required (longitude,latitude) order. */ p1[ perm[ 0 ] ] = point1[ 0 ]; p1[ perm[ 1 ] ] = point1[ 1 ]; p2[ perm[ 0 ] ] = point2[ 0 ]; p2[ perm[ 1 ] ] = point2[ 1 ]; p3[ perm[ 0 ] ] = point3[ 0 ]; p3[ perm[ 1 ] ] = point3[ 1 ]; /* Convert each point into a 3-vector of unit length. */ palDcs2c( p1[ 0 ], p1[ 1 ], v1 ); palDcs2c( p2[ 0 ], p2[ 1 ], v2 ); palDcs2c( p3[ 0 ], p3[ 1 ], v3 ); /* Find the cross product between the first two vectors, and normalize is. This is the unit normal to the great circle plane defining parallel distance. */ palDvxv( v2, v1, vtemp ); palDvn( vtemp, n1, &vmod ); /* Return with bad values if the normal is undefined (i.e. if the first two vectors are identical or diametrically opposite). */ if( vmod > 0.0 ) { /* Now take the cross product of the normal vector and v1. This gives a point, v5, on the great circle which is 90 degrees away from v1, in the direction of v2. */ palDvxv( v1, n1, v5 ); /* Find the cross product of the outlying point (point 3), and the vector n1 found above, and normalize it. This is the unit normal to the great circle plane defining perpendicular distance. */ palDvxv( v3, n1, vtemp ); palDvn( vtemp, n2, &vmod ); /* Return with bad values if the normal is undefined (i.e. if the outlying point is normal to the great circle defining the basis vector). */ if( vmod > 0.0 ) { /* The point of closest approach, point 4, is the point which is normal to both normal vectors (i.e. the intersection of the two great circles). This is the cross product of n1 and n2. No need to normalize this time since both n1 and n2 are unit vectors, and so v4 will already be a unit vector. */ palDvxv( n1, n2, v4 ); /* The dot product of v4 and v1 is the cos of the parallel distance, d1, whilst the dot product of v4 and v5 is the sin of the parallel distance. Use these to get the parallel distance with the correct sign, in the range -PI to +PI. */ *d1 = atan2( palDvdv( v4, v5 ), palDvdv( v4, v1 ) ); /* The dot product of v4 and v3 is the cos of the perpendicular distance, d2, whilst the dot product of n1 and v3 is the sin of the perpendicular distance. Use these to get the perpendicular distance. */ *d2 = fabs( atan2( palDvdv( v3, n1 ), palDvdv( v3, v4 ) ) ); /* Convert the 3-vector representing the intersection of the two planes back into spherical cooordinates and then constrain the longitude result to lie in the range 0 to 2*pi. */ palDcc2s( v4, &p4[ 0 ], &p4[ 1 ] ); p4[ 0 ] = palDranrm( p4[ 0 ] ); /* Permute the result coordinates to undo the effect of the SkyFrame axis permutation array. */ point4[ 0 ] = p4[ perm[ 0 ] ]; point4[ 1 ] = p4[ perm[ 1 ] ]; } } } } return; } 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 "frame.h" * AstPointSet *astResolvePoints( AstFrame *this, const double point1[], * const double point2[], AstPointSet *in, * AstPointSet *out ) * Class Membership: * SkyFrame 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 be signed only if the Frame is 2-dimensional, in which * case a positive value indicates that rotation from the basis vector * to the tested vector is in the same sense as rotation from the first * to the second axis of the Frame. * Notes: * - The number of coordinate values per point in the input * PointSet must match the number of axes in the supplied Frame. * - If an output PointSet is supplied, it must have space for * sufficient number of points and 2 coordinate values per point. * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * - We assume spherical geometry throughout this function. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ const int *perm; /* Pointer to axis permutation array */ double **ptr_in; /* Pointers to input axis values */ double **ptr_out; /* Pointers to returned axis values */ double *d1; /* Pointer to next parallel component value */ double *d2; /* Pointer to next perpendicular component value */ double *point3x; /* Pointer to next first axis value */ double *point3y; /* Pointer to next second axis value */ double n1[ 3 ]; /* Unit normal to grt crcl thru p1 and p2 */ double n2[ 3 ]; /* Unit normal to grt crcl thru p3 and p4 */ double p1[ 2 ]; /* Permuted coordinates for point1 */ double p2[ 2 ]; /* Permuted coordinates for point2 */ double p3[ 2 ]; /* Permuted coordinates for point3 */ double sign; /* Sign for perpendicular distances */ double v1[ 3 ]; /* 3-vector for p1 */ double v2[ 3 ]; /* 3-vector for p2 */ double v3[ 3 ]; /* 3-vector for p3 */ double v4[ 3 ]; /* 3-vector for p4 */ double v5[ 3 ]; /* 3-vector 90 degs away from p1 */ double vmod; /* Modulus of vector */ double vtemp[ 3 ]; /* Temporary vector workspace */ int ipoint; /* Index of next point */ int ncoord_in; /* Number of input PointSet coordinates */ int ncoord_out; /* Number of coordinates in output PointSet */ int npoint; /* Number of points to transform */ int npoint_out; /* Number of points in output PointSet */ int ok; /* OK to proceed? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Obtain the number of input vectors to resolve and the number of coordinate values per vector. */ npoint = astGetNpoint( in ); ncoord_in = astGetNcoord( in ); /* If OK, check that the number of input coordinates matches the number required by the Frame. Report an error if these numbers do not match. */ if ( astOK && ( ncoord_in != 2 ) ) { astError( AST__NCPIN, "astResolvePoints(%s): Bad number of coordinate " "values (%d) in input %s.", status, astGetClass( this ), ncoord_in, astGetClass( in ) ); astError( AST__NCPIN, "The %s given requires 2 coordinate values for " "each input point.", status, astGetClass( this ) ); } /* If still OK, and a non-NULL pointer has been given for the output PointSet, then obtain the number of points and number of coordinates per point for this PointSet. */ if ( astOK && out ) { npoint_out = astGetNpoint( out ); ncoord_out = astGetNcoord( out ); /* Check that the dimensions of this PointSet are adequate to accommodate the output coordinate values and report an error if they are not. */ if ( astOK ) { if ( npoint_out < npoint ) { astError( AST__NOPTS, "astResolvePoints(%s): Too few points (%d) in " "output %s.", status, astGetClass( this ), npoint_out, astGetClass( out ) ); astError( AST__NOPTS, "The %s needs space to hold %d transformed " "point(s).", status, astGetClass( this ), npoint ); } else if ( ncoord_out < 2 ) { astError( AST__NOCTS, "astResolvePoints(%s): Too few coordinate " "values per point (%d) in output %s.", status, astGetClass( this ), ncoord_out, astGetClass( out ) ); astError( AST__NOCTS, "The %s supplied needs space to store 2 " "coordinate value(s) per transformed point.", status, astGetClass( this ) ); } } } /* If all the validation stages are passed successfully, and a NULL output pointer was given, then create a new PointSet to encapsulate the output coordinate data. */ if ( astOK ) { if ( !out ) { result = astPointSet( npoint, 2, "", status ); /* Otherwise, use the PointSet supplied. */ } else { result = out; } } /* Get pointers to the input and output axis values */ ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Obtain a pointer to the SkyFrame's axis permutation array. */ perm = astGetPerm( this ); /* If the axes have been swapped we need to swap the sign of the returned perpendicular distances. */ sign = ( perm[ 0 ] == 0 ) ? -1.0 : 1.0; /* Check pointers can be used safely */ if( astOK ) { /* Apply the axis permutation array to obtain the coordinates of the two supplied points in the required (longitude,latitude) order. */ p1[ perm[ 0 ] ] = point1[ 0 ]; p1[ perm[ 1 ] ] = point1[ 1 ]; p2[ perm[ 0 ] ] = point2[ 0 ]; p2[ perm[ 1 ] ] = point2[ 1 ]; /* Convert these points into 3-vectors of unit length. */ palDcs2c( p1[ 0 ], p1[ 1 ], v1 ); palDcs2c( p2[ 0 ], p2[ 1 ], v2 ); /* Find the cross product between the vectors, and normalize it. This is the unit normal to the great circle plane defining parallel distance. */ palDvxv( v2, v1, vtemp ); palDvn( vtemp, n1, &vmod ); /* Return with bad values if the normal is undefined (i.e. if the first two vectors are identical or diametrically opposite). */ ok = 0; if( vmod > 0.0 ) { ok = 1; /* Now take the cross product of the normal vector and v1. This gives a point, v5, on the great circle which is 90 degrees away from v1, in the direction of v2. */ palDvxv( v1, n1, v5 ); } /* Store pointers to the first two axis arrays in the returned PointSet. */ d1 = ptr_out[ 0 ]; d2 = ptr_out[ 1 ]; /* Store pointers to the axis values in the supplied PointSet. */ point3x = ptr_in[ 0 ]; point3y = ptr_in[ 1 ]; /* Check supplied values can be used */ if( ok ) { /* Loop round each supplied vector. */ for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++, point3x++, point3y++ ) { /* Store bad output values if either input axis value is bad. */ if( *point3x == AST__BAD || *point3y == AST__BAD ){ *d1 = AST__BAD; *d2 = AST__BAD; /* If both are good... */ } else { /* Apply the axis permutation array to obtain the coordinates in the required (longitude,latitude) order. */ p3[ perm[ 0 ] ] = *point3x; p3[ perm[ 1 ] ] = *point3y; /* Convert into a 3-vector of unit length. */ palDcs2c( p3[ 0 ], p3[ 1 ], v3 ); /* Find the cross product of the outlying point (point 3), and the vector n1 found above, and normalize it. This is the unit normal to the great circle plane defining perpendicular distance. */ palDvxv( v3, n1, vtemp ); palDvn( vtemp, n2, &vmod ); /* Return with bad values if the normal is undefined (i.e. if the outlying point is normal to the great circle defining the basis vector). */ if( vmod <= 0.0 ) { *d1 = AST__BAD; *d2 = AST__BAD; } else { /* The point of closest approach, point 4, is the point which is normal to both normal vectors (i.e. the intersection of the two great circles). This is the cross product of n1 and n2. No need to normalize this time since both n1 and n2 are unit vectors, and so v4 will already be a unit vector. */ palDvxv( n1, n2, v4 ); /* The dot product of v4 and v1 is the cos of the parallel distance, d1, whilst the dot product of v4 and v5 is the sin of the parallel distance. Use these to get the parallel distance with the correct sign, in the range -PI to +PI. */ *d1 = atan2( palDvdv( v4, v5 ), palDvdv( v4, v1 ) ); /* The dot product of v4 and v3 is the cos of the perpendicular distance, d2, whilst the dot product of n1 and v3 is the sin of the perpendicular distance. Use these to get the perpendicular distance. */ *d2 = sign*atan2( palDvdv( v3, n1 ), palDvdv( v3, v4 ) ); } } } /* If supplied values cannot be used, fill the returned PointSet with bad values */ } else { for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++ ) { *d1 = AST__BAD; *d2 = AST__BAD; } } } /* Annul the returned PointSet if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static void SetAsTime( AstSkyFrame *this, int axis, int value, int *status ) { /* * Name: * SetAsTime * Purpose: * Set a value for the AsTime attribute for a SkyFrame's axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetAsTime( AstSkyFrame *this, int axis, int value, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function sets the boolean value of the AsTime attribute for a * specified axis of a SkyFrame. This value indicates whether axis values * should be formatted as times (as opposed to angles) by default. * Parameters: * this * Pointer to the SkyFrame. * axis * Index of the axis for which a value is to be set (zero based). * value * The boolean value to be set. * status * Pointer to the inherited status variable. * Returned Value: * void. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ AstSkyAxis *new_ax; /* Pointer to new SkyAxis object */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astSetAsTime" ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis ); /* Check if the Axis object is a SkyAxis. If not, we will replace it with one. */ if ( !astIsASkyAxis( ax ) ) { /* Create a new SkyAxis and overlay the attributes of the original Axis. */ new_ax = astSkyAxis( "", status ); astAxisOverlay( ax, new_ax ); /* Modify the SkyFrame to use the new Skyaxis and annul the original Axis pointer. Retain a pointer to the new SkyAxis. */ astSetAxis( this, axis, new_ax ); ax = astAnnul( ax ); ax = (AstAxis *) new_ax; } /* Set a value for the Axis AsTime attribute. */ astSetAxisAsTime( ax, value ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * SkyFrame member function (extends the astSetAttrib method inherited from * the Mapping class). * Description: * This function assigns an attribute value for a SkyFrame, 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 SkyFrame. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Returned Value: * void * Attributes: * As well as those attributes inherited from the parent class, this * function also accepts values for the following additional attributes: * * Equinox (double, read as a string) * Notes: * This protected method is intended to be invoked by the Object astSet * method and makes additional attributes accessible to it. */ /* Local Vaiables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ double dval; /* Floating point attribute value */ double dval1; /* Floating point attribute value */ double dval2; /* Floating point attribute value */ double mjd; /* Modified Julian Date */ int astime; /* Value of AsTime attribute */ int axis; /* Axis index */ int equinox; /* Offset of Equinox attribute value */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ int neglon; /* Display -ve longitudes? */ int ok; /* Can string be used? */ int offset; /* Offset of start of attribute value */ int projection; /* Offset of projection attribute value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) 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. */ /* AsTime(axis). */ /* ------------- */ if ( nc = 0, ( 2 == astSscanf( setting, "astime(%d)= %d %n", &axis, &astime, &nc ) ) && ( nc >= len ) ) { astSetAsTime( this, axis - 1, astime ); /* Equinox. */ /* -------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "equinox=%n%*[^\n]%n", &equinox, &nc ) ) && ( nc >= len ) ) { /* Convert the Equinox value to a Modified Julian Date before use. */ mjd = astReadDateTime( setting + equinox ); if ( astOK ) { astSetEquinox( this, mjd ); /* Report contextual information if the conversion failed. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid equinox value " "\"%s\" given for sky coordinate system.", status, astGetClass( this ), setting + equinox ); } /* NegLon. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "neglon= %d %n", &neglon, &nc ) ) && ( nc >= len ) ) { astSetNegLon( this, neglon ); /* SkyTol. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "skytol= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetSkyTol( this, dval ); /* Projection. */ /* ----------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "projection=%n%*[^\n]%n", &projection, &nc ) ) && ( nc >= len ) ) { astSetProjection( this, setting + projection ); /* SkyRef. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "skyref=%n%*[^\n]%n", &offset, &nc ) ) && ( nc >= len ) ) { ok = 0; nc = astUnformat( this, 0, setting + offset, &dval1 ); if( setting[ offset + nc ] == ',' ) { nc++; nc += astUnformat( this, 1, setting + offset + nc, &dval2 ); if( nc == strlen( setting + offset ) ) { astSetSkyRef( this, 0, dval1 ); astSetSkyRef( this, 1, dval2 ); ok = 1; } } if( !ok && astOK ) { astError( AST__BADOC, "astSetAttrib(%s): Invalid axis values string " "\"%.*s\" given for SkyRef attribute.", status, astGetClass( this ), (int) astChrLen( setting + offset ), setting + offset ); } /* SkyRef(axis). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "skyref(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetSkyRef( this, axis - 1, dval ); /* SkyRefIs. */ /* --------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "skyrefis=%n%*[^\n]%n", &offset, &nc ) ) && ( nc >= len ) ) { if( astChrMatch( setting + offset, POLE_STRING ) ) { astSetSkyRefIs( this, AST__POLE_REF ); } else if( astChrMatch( setting + offset, ORIGIN_STRING ) ) { astSetSkyRefIs( this, AST__ORIGIN_REF ); } else if( astChrMatch( setting + offset, IGNORED_STRING ) ) { astSetSkyRefIs( this, AST__IGNORED_REF ); } else if( astOK ) { astError( AST__OPT, "astSet(%s): option '%s' is unknown in '%s'.", status, astGetClass( this ), setting+offset, setting ); } /* SkyRefP. */ /* -------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "skyrefp=%n%*[^\n]%n", &offset, &nc ) ) && ( nc >= len ) ) { ok = 0; nc = astUnformat( this, 0, setting + offset, &dval1 ); if( setting[ offset + nc ] == ',' ) { nc++; nc += astUnformat( this, 1, setting + offset + nc, &dval2 ); if( nc == strlen( setting + offset ) ) { astSetSkyRefP( this, 0, dval1 ); astSetSkyRefP( this, 1, dval2 ); ok = 1; } } if( !ok && astOK ) { astError( AST__BADOC, "astSetAttrib(%s): Invalid axis values string " "\"%.*s\" given for SkyRefP attribute.", status, astGetClass( this ), (int) astChrLen( setting + offset ), setting + offset ); } /* SkyRefP(axis). */ /* -------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "skyrefp(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetSkyRefP( this, axis - 1, dval ); /* AlignOffset. */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "alignoffset= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetAlignOffset( this, ival ); /* 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 ( !strncmp( setting, "islataxis", 9 ) || !strncmp( setting, "islonaxis", 9 ) || MATCH( "lataxis" ) || MATCH( "lonaxis" ) ) { 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 any unrecognised setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetCachedLAST( AstSkyFrame *this, double last, double epoch, double obslon, double obslat, double obsalt, double dut1, int *status ) { /* * Name: * SetCachedLAST * Purpose: * Store a LAST value in the cache in the SkyFrame vtab. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetCachedLAST( AstSkyFrame *this, double last, double epoch, * double obslon, double obslat, double obsalt, * double dut1, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function stores the supplied LAST value in a cache in the * SkyFrame virtual function table for later use by GetCachedLAST. * Parameters: * this * Pointer to the SkyFrame. * last * The Local Apparent Sidereal Time (radians). * epoch * The epoch (MJD). * obslon * Observatory geodetic longitude (radians) * obslat * Observatory geodetic latitude (radians) * obsalt * Observatory geodetic altitude (metres) * dut1 * The UT1-UTC correction, in seconds. * status * Pointer to the inherited status variable. */ /* Local Variables: */ astDECLARE_GLOBALS AstSkyLastTable *table; double *ep; double *lp; double lp_ref; int i; int itable; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Initialise */ table = NULL; /* Check the global error status. */ if ( !astOK ) return; /* Ensure no threads are allowed to read the table whilst we are writing to it. */ LOCK_WLOCK1 /* Loop round every LAST table held in the vtab. Each table refers to a different observatory position and/or DUT1 value. */ for( itable = 0; itable < nlast_tables; itable++ ) { table = last_tables[ itable ]; /* See if the table refers to the given position and dut1 value, allowing some small tolerance. If it does, leave the loop. */ if( fabs( table->obslat - obslat ) < 2.0E-7 && fabs( table->obslon - obslon ) < 2.0E-7 && fabs( table->obsalt - obsalt ) < 1.0 && fabs( table->dut1 - dut1 ) < 1.0E-5 ) break; /* Ensure "table" ends up NULL if no suitable table is found. */ table = NULL; } /* If no table was found, create one now, and add it into the vtab cache. */ if( !table ) { astBeginPM; table = astMalloc( sizeof( AstSkyLastTable ) ); itable = nlast_tables++; last_tables = astGrow( last_tables, nlast_tables, sizeof( AstSkyLastTable * ) ); astEndPM; if( astOK ) { last_tables[ itable ] = table; table->obslat = obslat; table->obslon = obslon; table->obsalt = obsalt; table->dut1 = dut1; table->nentry = 1; astBeginPM; table->epoch = astMalloc( sizeof( double ) ); table->last = astMalloc( sizeof( double ) ); astEndPM; if( astOK ) { table->epoch[ 0 ] = epoch; table->last[ 0 ] = last; } } /* If we have a table, add the new point into it. */ } else { /* Extend the epoch and last arrays. */ astBeginPM; table->epoch = astGrow( table->epoch, ++(table->nentry), sizeof( double ) ); table->last = astGrow( table->last, table->nentry, sizeof( double ) ); astEndPM; /* Check memory allocation was successful. */ if( astOK ) { /* Get pointers to the last original elements in the arrays of epoch and corresponding LAST values in the table. */ ep = table->epoch + table->nentry - 2; lp = table->last + table->nentry - 2; /* Starting from the end of the arrays, shuffle all entries up one element until an element is found which is less than the supplied epoch value. This maintains the epoch array in monotonic increasing order. */ for( i = table->nentry - 2; i >= 0; i--,ep--,lp-- ) { if( *ep <= epoch ) break; ep[ 1 ] = *ep; lp[ 1 ] = *lp; } /* Store the new epoch and LAST value. Add or subtract 2.PI as needed from the new LAST value to ensure it is continuous with an adjacent LAST value. This is needed for interpolation between the two values to be meaningful. */ ep[ 1 ] = epoch; /* For most cases, compare with the previous LAST value. If the new epoch value is smaller than any epoch already in the table, there will be no previous LAST value. So compare with the next value instead. */ if( i >= 0 ) { lp_ref = lp[ 0 ]; } else { lp_ref = lp[ 2 ]; } if( last > lp_ref + AST__DPI ) { lp[ 1 ] = last - 2*AST__DPI; } else if( last < lp_ref - AST__DPI ) { lp[ 1 ] = last + 2*AST__DPI; } else { lp[ 1 ] = last; } } } /* Indicate other threads are now allowed to read the table. */ UNLOCK_RWLOCK1 } static void SetDut1( AstFrame *this_frame, double val, int *status ) { /* * Name: * SetDut1 * Purpose: * Set the value of the Dut1 attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetDut1( AstFrame *this, double val, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSetDut1 method * inherited from the Frame class). * Description: * This function clears the Dut1 value and updates the LAST value * stored in the SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * val * New Dut1 value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSkyFrame *this; double orig; /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Note the original Dut1 value. */ orig = astGetDut1( this ); /* Invoke the parent method to set the Frame Dut1 value. */ (*parent_setdut1)( this_frame, val, status ); /* If the DUT1 value has changed significantly, indicate that the LAST value will need to be re-calculated when it is next needed. */ if( fabs( orig - val ) > 1.0E-6 ) { this->last = AST__BAD; this->eplast = AST__BAD; this->klast = AST__BAD; } } static void SetLast( AstSkyFrame *this, int *status ) { /* * Name: * SetLast * Purpose: * Set the Local Appearent Sidereal Time for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetLast( AstSkyFrame *this, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function sets the Local Apparent Sidereal Time at the epoch * and geographical longitude given by the current values of the Epoch * and ObsLon attributes associated with the supplied SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * 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: */ double epoch; /* Epoch as a TDB MJD */ /* Check the global error status. */ if ( !astOK ) return; /* Get the SkyFrame Epoch as a TDB MJD. */ epoch = astGetEpoch( this ); /* Calculate the LAST value (in rads) and store in the SkyFrame structure. */ this->last = CalcLAST( this, epoch, astGetObsLon( this ), astGetObsLat( this ), astGetObsAlt( this ), astGetDut1( this ), status ); /* Save the TDB MJD to which this LAST corresponds. */ this->eplast = epoch; /* The ratio between solar and sidereal time is a slowly varying function of epoch. The GetLAST function returns a fast approximation to LAST by using the ratio between solar and sidereal time. Indicate that GetLAST should re-calculate the ratio by setting the ratio value bad. */ this->klast = AST__BAD; } static void SetObsAlt( AstFrame *this, double val, int *status ) { /* * Name: * SetObsAlt * Purpose: * Set the value of the ObsAlt attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetObsAlt( AstFrame *this, double val, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSetObsAlt method * inherited from the Frame class). * Description: * This function sets the ObsAlt value. * Parameters: * this * Pointer to the SkyFrame. * val * New ObsAlt value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original ObsAlt value. */ orig = astGetObsAlt( this ); /* Invoke the parent method to set the Frame ObsAlt. */ (*parent_setobsalt)( this, val, status ); /* If the altitude has changed significantly, indicate that the LAST value and magnitude of the diurnal aberration vector will need to be re-calculated when next needed. */ if( fabs( orig - val ) > 0.001 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; ( (AstSkyFrame *) this )->diurab = AST__BAD; } } static void SetObsLat( AstFrame *this, double val, int *status ) { /* * Name: * SetObsLat * Purpose: * Set the value of the ObsLat attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetObsLat( AstFrame *this, double val, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSetObsLat method * inherited from the Frame class). * Description: * This function sets the ObsLat value. * Parameters: * this * Pointer to the SkyFrame. * val * New ObsLat value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original ObsLat value. */ orig = astGetObsLat( this ); /* Invoke the parent method to set the Frame ObsLat. */ (*parent_setobslat)( this, val, status ); /* If the altitude has changed significantly, indicate that the LAST value and magnitude of the diurnal aberration vector will need to be re-calculated when next needed. */ if( fabs( orig - val ) > 1.0E-8 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; ( (AstSkyFrame *) this )->diurab = AST__BAD; } } static void SetObsLon( AstFrame *this, double val, int *status ) { /* * Name: * SetObsLon * Purpose: * Set the value of the ObsLon attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetObsLon( AstFrame *this, double val, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSetObsLon method * inherited from the Frame class). * Description: * This function sets the ObsLon value. * Parameters: * this * Pointer to the SkyFrame. * val * New ObsLon value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double orig; /* Check the global error status. */ if ( !astOK ) return; /* Note the original ObsLon value. */ orig = astGetObsLon( this ); /* Invoke the parent method to set the Frame ObsLon. */ (*parent_setobslon)( this, val, status ); /* If the longitude has changed significantly, indicate that the LAST value will need to be re-calculated when it is next needed. */ if( fabs( orig - val ) > 1.0E-8 ) { ( (AstSkyFrame *) this )->last = AST__BAD; ( (AstSkyFrame *) this )->eplast = AST__BAD; ( (AstSkyFrame *) this )->klast = AST__BAD; } } static void SetSystem( AstFrame *this_frame, AstSystemType system, int *status ) { /* * Name: * SetSystem * Purpose: * Set the System attribute for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void SetSystem( AstFrame *this_frame, AstSystemType system, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSetSystem protected * method inherited from the Frame class). * Description: * This function assigns a new value to the System attribute for a SkyFrame. * Parameters: * this * Pointer to the SkyFrame. * system * The new System value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrameSet *fs; /* FrameSet to be used as the Mapping */ AstSkyFrame *sfrm; /* Copy of original SkyFrame */ AstSkyFrame *this; /* Pointer to SkyFrame structure */ double xin[ 2 ]; /* Axis 0 values */ double xout[ 2 ]; /* Axis 0 values */ double yin[ 2 ]; /* Axis 1 values */ double yout[ 2 ]; /* Axis 1 values */ int aloff; /* The AlignOffset attribute value */ int aloff_set; /* Is the AlignOffset attribute set? */ int skyref_set; /* Is either SkyRef attribute set? */ int skyrefis; /* The SkyRefIs attribute value */ int skyrefis_set; /* Is the SkyRefIs attribute set? */ int skyrefp_set; /* Is either SkyRefP attribute set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* See if either the SkyRef or SkyRefP attribute is set. */ skyref_set = astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ); skyrefp_set = astTestSkyRefP( this, 0 ) || astTestSkyRefP( this, 1 ); /* If so, we will need to transform their values into the new coordinate system. Save a copy of the SkyFrame with its original System value. */ sfrm = ( skyref_set || skyrefp_set )?astCopy( this ):NULL; /* Use the parent method to set the new System value. */ (*parent_setsystem)( this_frame, system, status ); /* Now modify the SkyRef and SkyRefP attributes if necessary. */ if( sfrm ) { /* Save the AlignOffset, SkyRefIs, SkyRef and SkyRefP values. */ aloff_set = astTestAlignOffset( sfrm ); aloff = astGetAlignOffset( sfrm ); skyrefis_set = astTestSkyRefIs( sfrm ); skyrefis = astGetSkyRefIs( sfrm ); xin[ 0 ] = astGetSkyRef( sfrm, 0 ); xin[ 1 ] = astGetSkyRefP( sfrm, 0 ); yin[ 0 ] = astGetSkyRef( sfrm, 1 ); yin[ 1 ] = astGetSkyRefP( sfrm, 1 ); /* Clear the SkyRef and SkyRefP values to avoid infinite recursion in the following call to astConvert. */ if( skyref_set ) { astClearSkyRef( sfrm, 0 ); astClearSkyRef( sfrm, 1 ); astClearSkyRef( this, 0 ); astClearSkyRef( this, 1 ); } if( skyrefp_set ) { astClearSkyRefP( sfrm, 0 ); astClearSkyRefP( sfrm, 1 ); astClearSkyRefP( this, 0 ); astClearSkyRefP( this, 1 ); } /* Also set AlignOffset and SkyRefIs so that the following call to astConvert does not align in offset coords. */ astSetAlignOffset( sfrm, 0 ); astSetSkyRefIs( sfrm, AST__IGNORED_REF ); /* Get the Mapping from the original System to the new System. Invoking astConvert will recursively invoke SetSystem again. This is why we need to be careful to ensure that SkyRef and SKyRefP are cleared above - doing so ensure we do not end up with infinite recursion. */ fs = astConvert( sfrm, this, "" ); /* If the conversion is not possible, clear the SkyRef and SkyRefP values. */ if( !fs ) { if( skyref_set ) { astClearSkyRef( this, 0 ); astClearSkyRef( this, 1 ); } if( skyrefp_set ) { astClearSkyRefP( this, 0 ); astClearSkyRefP( this, 1 ); } /* Use the Mapping to find the SkyRef and SkyRefP positions in the new coordinate system. */ } else { astTran2( fs, 2, xin, yin, 1, xout, yout ); /* Store the values as required. */ if( skyref_set ) { astSetSkyRef( this, 0, xout[ 0 ] ); astSetSkyRef( this, 1, yout[ 0 ] ); } if( skyrefp_set ) { astSetSkyRefP( this, 0, xout[ 1 ] ); astSetSkyRefP( this, 1, yout[ 1 ] ); } /* Restore the original SkyRefIs and AlignOffset values. */ if( aloff_set ) { astSetAlignOffset( this, aloff ); } else { astClearAlignOffset( this ); } if( skyrefis_set ) { astSetSkyRefIs( this, skyrefis ); } else { astClearSkyRefIs( this ); } /* Free resources. */ fs = astAnnul( fs ); } sfrm = astAnnul( sfrm ); } } static void Shapp( double dist, double *r0, double *r3, double a0, double *p4, int *status ){ /* * Name: * Shapp * Purpose: * Use the vectors calculated by Shcal to find a sky position * which is offset along a given position angle. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void Shapp( double dist, double *r0, double *r3, double a0, * double *p4, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function uses the vectors R0 and R3 calculated previously by * Shcal to find the sky position which is offset away from the * "reference" position (see function Offset2) by a given arc * distance, along a given great circle. * * No checks are made for AST__BAD values. * Parameters: * dist * The arc distance to move away from the reference position * in the given direction, in radians. * r0 * Pointer to an array holding the 3-vector representing the reference * position. * r3 * Pointer to an array holding the 3-vector representing the * point which is 90 degrees away from the reference point, along * the required great circle. * a0 * The sky longitude of the reference position, in radians. * p4 * Pointer to an array of 2 doubles in which to put the sky longitude * and latitude of the required point, in radians. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double cosdst; /* Cosine of DIST */ double r4[ 3 ]; /* Required position vector */ double sindst; /* Sine of DIST */ /* Check the global error status. */ if ( !astOK ) return; /* Store commonly used values. */ sindst = sin( dist ); cosdst = cos( dist ); /* The vector R4 representing the required point is produced as a linear sum of R0 and R3. */ r4[ 0 ] = cosdst*r0[ 0 ] + sindst*r3[ 0 ]; r4[ 1 ] = cosdst*r0[ 1 ] + sindst*r3[ 1 ]; r4[ 2 ] = cosdst*r0[ 2 ] + sindst*r3[ 2 ]; /* Create the longitude of the required point. If this point is at a pole it is assigned the same longitude as the reference point. */ if( r4[ 0 ] != 0.0 || r4[ 1 ] != 0.0 ) { p4[ 0 ] = atan2( r4[ 1 ], r4[ 0 ] ); } else { p4[ 0 ] = a0; } /* Create the latitude of the required point. */ if( r4[ 2 ] > 1.0 ) { r4[ 2 ] = 1.0; } else if( r4[ 2 ] < -1.0 ) { r4[ 2 ] = -1.0; } p4[ 1 ] = asin( r4[ 2 ] ); } static void Shcal( double a0, double b0, double angle, double *r0, double *r3, int *status ) { /* * Name: * Shcal * Purpose: * Calculate vectors required by Offset2. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void Shcal( double a0, double b0, double angle, double *r0, * double *r3, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function calculates the 3-vector R0, representing the given * sky position (A0,B0), and the 3-vector R3, representing the sky * position which is 90 degrees away from R0, along a great circle * passing through R0 at a position angle given by ANGLE. Each * 3-vector holds Cartesian (X,Y,Z) values with origin at the centre * of the celestial sphere. The XY plane is the "equator", the Z * axis is in the direction of the "north pole", X is towards zero * longitude (A=0), and Y is towards longitude 90 degrees. * * No checks are made for AST__BAD input values. * Parameters: * a0 * The sky longitude of the given position, in radians. * b0 * The sky latitude of the given position, in radians. * angle * The position angle of a great circle passing through the given * position. That is, the angle from north to the required * direction, in radians. Positive angles are in the sense of * rotation from north to east. * r0 * A pointer to an array to receive 3-vector R0. See above. * r3 * A pointer to an array to receive 3-vector R3. See above. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double cosa0; /* Cosine of A0 */ double cosb0; /* Cosine of B0 */ double cospa; /* Cosine of ANGLE */ double r1[ 3 ]; /* Vector PI/2 away from R0 in meridian of R0 */ double r2[ 3 ]; /* Vector PI/2 away from R0 on equator */ double sinpa; /* Sine of ANGLE */ double sina0; /* Sine of A0 */ double sinb0; /* Sine of B0 */ /* Check the global error status. */ if ( !astOK ) return; /* Store commonly used values. */ sina0 = sin( a0 ); cosa0 = cos( a0 ); sinb0 = sin( b0 ); cosb0 = cos( b0 ); sinpa = sin( angle ); cospa = cos( angle ); /* Create the vector R0 representing the given point. The XY plane defines zero latitude, Z is in the direction of increasing latitude, X is towards zero longitude, and Y is towards longitude 90 degrees. */ r0[ 0 ] = cosb0*cosa0; r0[ 1 ] = cosb0*sina0; r0[ 2 ] = sinb0; /* Create the vector R1 representing the point in the meridian of the given point which has latitude 90 degrees greater than the given point. */ r1[ 0 ] = -sinb0*cosa0; r1[ 1 ] = -sinb0*sina0; r1[ 2 ] = cosb0; /* Create the vector R2 representing the point on the equator (i.e. a latitude of zero), which has a longitude 90 degrees to the west of the given point. */ r2[ 0 ] = -sina0; r2[ 1 ] = cosa0; r2[ 2 ] = 0.0; /* Create the vector R3 representing the point which is 90 degrees away from the given point, along the required great circle. */ r3[ 0 ] = cospa*r1[ 0 ] + sinpa*r2[ 0 ]; r3[ 1 ] = cospa*r1[ 1 ] + sinpa*r2[ 1 ]; r3[ 2 ] = cospa*r1[ 2 ] + sinpa*r2[ 2 ]; /* Return */ return; } static int SubFrame( AstFrame *target_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 SkyFrame and convert to the new coordinate system. * Type: * Private function. * Synopsis: * #include "skyframe.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: * SkyFrame 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 * a "target" SkyFrame and creates a new Frame with copies of the selected * axes assembled in the requested order. It then optionally overlays the * attributes of a "template" Frame on to the result. It returns both the * resulting Frame and a Mapping that describes how to convert between the * coordinate systems described by the target and result Frames. If * necessary, this Mapping takes account of any differences in the Frames' * attributes due to the influence of the template. * Parameters: * target * Pointer to the target SkyFrame, from which axes are to be selected. * template * Pointer to the template Frame, from which new attributes for the * result Frame are to be obtained. Optionally, this may be NULL, in * which case no overlaying of template attributes will be performed. * result_naxes * Number of axes to be selected from the target Frame. This number may * be greater than or less than the number of axes in this Frame (or * equal). * target_axes * Pointer to an array of int with result_naxes elements, giving a list * of the (zero-based) axis indices of the axes to be selected from the * target SkyFrame. The order in which these are given determines the * order in which the axes appear in the result Frame. If any of the * values in this array is set to -1, the corresponding result axis will * not be derived from the target Frame, but will be assigned default * attributes instead. * template_axes * Pointer to an array of int with result_naxes elements. This should * contain a list of the template axes (given as zero-based axis indices) * with which the axes of the result Frame are to be associated. This * array determines which axes are used when overlaying axis-dependent * attributes of the template on to the result. If any element of this * array is set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not used and * a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned Mapping. * The forward transformation of this Mapping will describe how to * convert coordinates from the coordinate system described by the target * SkyFrame 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 target and the result Frame. Otherwise zero is returned and * *map and *result are returned as NULL (but this will not in itself * result in an error condition). In general, coordinate conversion should * always be possible if no template Frame is supplied but may not always * be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * Implementation Notes: * - This implementation addresses the selection of axes from a SkyFrame * object. This results in another object of the same class only if both * axes of the SkyFrame are selected, once each. Otherwise, the result is a * Frame class object which inherits the SkyFrame's axis information (if * appropriate) but none of the other properties of a SkyFrame. * - In the event that a SkyFrame results, the returned Mapping will take * proper account of the relationship between the target and result sky * coordinate systems. * - In the event that a Frame class object results, the returned Mapping * will only represent a selection/permutation of axes. * Implementation Deficiencies: * - Any axis selection is currently permitted. Probably this should be * restricted so that each axis can only be selected once. The * astValidateAxisSelection method will do this but currently there are bugs * in the CmpFrame class that cause axis selections which will not pass this * test. Install the validation when these are fixed. */ /* Local Variables: */ AstAxis *ax; /* Pointer to result Frame Axis object */ AstMapping *tmpmap; /* Temporary Mapping pointer */ AstPermMap *permmap; /* Pointer to PermMap */ AstSkyFrame *target; /* Pointer to the SkyFrame structure */ AstSkyFrame *temp; /* Pointer to copy of target SkyFrame */ AstSystemType align_sys; /* System in which to align the SkyFrames */ int match; /* Coordinate conversion is possible? */ int perm[ 2 ]; /* Permutation array for axis swap */ int result_swap; /* Swap result SkyFrame coordinates? */ int set_usedefs; /* Set the returned UseDefs attribute zero?*/ int target_axis; /* Target SkyFrame axis index */ int target_swap; /* Swap target SkyFrame coordinates? */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain a pointer to the target SkyFrame structure. */ target = (AstSkyFrame *) target_frame; /* Result is a SkyFrame. */ /* --------------------- */ /* Check if the result Frame is to have two axes obtained by selecting both of the target SkyFrame axes, in either order. If so, the result will also be a SkyFrame. */ if ( ( result_naxes == 2 ) && ( ( ( target_axes[ 0 ] == 0 ) && ( target_axes[ 1 ] == 1 ) ) || ( ( target_axes[ 0 ] == 1 ) && ( target_axes[ 1 ] == 0 ) ) ) ) { /* If a template has not been supplied, or is the same object as the target, we are simply extracting axes from the supplied SkyFrame. In this case we temporarily force the UseDefs attribute to 1 so that (for instance) the astPickAxes method can function correctly. E.g. if you have a SkyFrame with no set Epoch and UseDefs set zero, and you try to swap the axes, the attempt would fail because MakeSkyMapping would be unable to determine the Mapping from original to swapped SkyFrame, because of the lack of an Epoch value. */ set_usedefs = 0; if( !template || template == target_frame ) { if( !astGetUseDefs( target ) ) { astClearUseDefs( target ); set_usedefs = 1; } } /* Form the result from a copy of the target and then permute its axes into the order required. */ *result = astCopy( target ); astPermAxes( *result, target_axes ); /* If required, overlay the template attributes on to the result SkyFrame. Also get the system in which to align the two SkyFrames. This is the value of the AlignSystem attribute from the template (if there is a template). */ if ( template ) { astOverlay( template, template_axes, *result ); align_sys = astGetAlignSystem( template ); } else { align_sys = astGetAlignSystem( target ); } /* See whether alignment occurs in offset coordinates or absolute coordinates. If the current call to this function is part of the process of restoring a FrameSet's integrity following changes to the FrameSet's current Frame, then we ignore the setting of the AlignOffset attributes and use 0. This ensures that when the System attribute (for instance) is changed via a FrameSet pointer, the Mappings within the FrameSet are modified to produce offsets in the new System. If we are not currently restoring a FrameSet's integrity, then we align in offsets if the template is a SkyFrame and both template and target want alignment to occur in the offset coordinate system. In this case we use a UnitMap to connect them. */ if( ( astGetFrameFlags( target_frame ) & AST__INTFLAG ) == 0 ) { if( astGetAlignOffset( target ) && astGetSkyRefIs( target ) != AST__IGNORED_REF && template && astIsASkyFrame( template ) ){ if( astGetAlignOffset( (AstSkyFrame *) template ) && astGetSkyRefIs( (AstSkyFrame *) template ) != AST__IGNORED_REF ) { match = 1; *map = (AstMapping *) astUnitMap( 2, "", status ); } } } /* Otherwise, generate a Mapping that takes account of changes in the sky coordinate system (equinox, epoch, etc.) between the target SkyFrame and the result SkyFrame. If this Mapping can be generated, set "match" to indicate that coordinate conversion is possible. */ if( ! *map ) { match = ( MakeSkyMapping( target, (AstSkyFrame *) *result, align_sys, map, status ) != 0 ); } /* If required, re-instate the original zero value of UseDefs. */ if( set_usedefs ) { astSetUseDefs( target, 0 ); astSetUseDefs( *result, 0 ); } /* If a Mapping has been obtained, it will expect coordinate values to be supplied in (longitude,latitude) pairs. Test whether we need to swap the order of the target SkyFrame coordinates to conform with this. */ if ( astOK && match ) { target_swap = ( astValidateAxis( target, 0, 1, "astSubFrame" ) != 0 ); /* Coordinates will also be delivered in (longitude,latitude) pairs, so check to see whether the result SkyFrame coordinate order should be swapped. */ result_swap = ( target_swap != ( target_axes[ 0 ] != 0 ) ); /* If either set of coordinates needs swapping, create a PermMap that will swap a pair of coordinates. */ permmap = NULL; if ( target_swap || result_swap ) { perm[ 0 ] = 1; perm[ 1 ] = 0; permmap = astPermMap( 2, perm, 2, perm, NULL, "", status ); } /* If necessary, prefix this PermMap to the main Mapping. */ if ( target_swap ) { tmpmap = (AstMapping *) astCmpMap( permmap, *map, 1, "", status ); *map = astAnnul( *map ); *map = tmpmap; } /* Also, if necessary, append it to the main Mapping. */ if ( result_swap ) { tmpmap = (AstMapping *) astCmpMap( *map, permmap, 1, "", status ); *map = astAnnul( *map ); *map = tmpmap; } /* Annul the pointer to the PermMap (if created). */ if ( permmap ) permmap = astAnnul( permmap ); } /* Result is not a SkyFrame. */ /* ------------------------- */ /* In this case, we select axes as if the target were from the Frame class. However, since the resulting data will then be separated from their enclosing SkyFrame, default attribute values may differ if the methods for obtaining them were over-ridden by the SkyFrame class. To overcome this, we ensure that these values are explicitly set for the result Frame (rather than relying on their defaults). */ } else { /* Make a temporary copy of the target SkyFrame. We will explicitly set the attribute values in this copy so as not to modify the original. */ temp = astCopy( target ); /* Define a macro to test if an attribute is set. If not, set it explicitly to its default value. */ #define SET(attribute) \ if ( !astTest##attribute( temp ) ) { \ astSet##attribute( temp, astGet##attribute( temp ) ); \ } /* Set attribute values which apply to the Frame as a whole and which we want to retain, but whose defaults are over-ridden by the SkyFrame class. */ SET(Domain) SET(Title) /* Now loop to set explicit attribute values for each axis. */ for ( target_axis = 0; target_axis < 2; target_axis++ ) { /* Define a macro to test if an axis attribute is set. If not, set it explicitly to its default value. */ #define SET_AXIS(attribute) \ if ( !astTest##attribute( temp, target_axis ) ) { \ astSet##attribute( temp, target_axis, \ astGet##attribute( temp, target_axis ) ); \ } /* Use this macro to set explicit values for all the axis attributes for which the SkyFrame class over-rides the default value. */ SET_AXIS(AsTime) SET_AXIS(Format) SET_AXIS(Label) SET_AXIS(Symbol) SET_AXIS(Unit) /* Now handle axis attributes for which there are no SkyFrame access methods. For these we require a pointer to the temporary SkyFrame's Axis object. */ ax = astGetAxis( temp, target_axis ); /* Set an explicit value for the IsLatitude and CentreZero attributes. */ if( astValidateAxis( temp, target_axis, 1, "astSubFrame" ) == 1 ) { astSetAxisIsLatitude( ax, 1 ); astSetAxisCentreZero( ax, 1 ); } else { astSetAxisIsLatitude( ax, 0 ); astSetAxisCentreZero( ax, astGetNegLon( temp ) ); } /* Annul the Axis object pointer. */ ax = astAnnul( ax ); } /* Clear attributes which have an extended range of values allowed by this class. */ astClearSystem( temp ); astClearAlignSystem( temp ); /* Invoke the astSubFrame method inherited from the Frame class to produce the result Frame by selecting the required set of axes and overlaying the template Frame's attributes. */ match = (*parent_subframe)( (AstFrame *) temp, template, result_naxes, target_axes, template_axes, map, result, status ); /* Delete the temporary copy of the target SkyFrame. */ temp = astDelete( temp ); } /* Ensure the returned Frame does not have active units. */ astSetActiveUnit( *result, 0 ); /* If an error occurred or no match was found, annul the returned objects and reset the returned result. */ if ( !astOK || !match ) { if( *map ) *map = astAnnul( *map ); if( *result ) *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; /* Undefine macros local to this function. */ #undef SET #undef SET_AXIS } static AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) { /* * Name: * SystemCode * Purpose: * Convert a string into a coordinate system type code. * Type: * Private function. * Synopsis: * #include "skyframe.h" * AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSystemCode method * inherited from the Frame class). * Description: * This function converts a string used for the external * description of a sky coordinate system into a SkyFrame * coordinate system type code (System attribute value). It is the * inverse of the astSystemString function. * Parameters: * this * The Frame. * system * Pointer to a constant null-terminated string containing the * external description of the sky 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 sky coordinate * system description was not recognised. This does not produce an * error. * - A value of AST__BADSYSTEM is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ AstSystemType result; /* Result value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" string against each possibility and assign the result. */ if ( astChrMatch( "FK4", system ) ) { result = AST__FK4; } else if ( astChrMatch( "FK4_NO_E", system ) || astChrMatch( "FK4-NO-E", system ) ) { result = AST__FK4_NO_E; } else if ( astChrMatch( "FK5", system ) || astChrMatch( "Equatorial", system ) ) { result = AST__FK5; } else if ( astChrMatch( "J2000", system ) ) { result = AST__J2000; } else if ( astChrMatch( "ICRS", system ) ) { result = AST__ICRS; } else if ( astChrMatch( "AZEL", system ) ) { result = AST__AZEL; } else if ( astChrMatch( "GAPPT", system ) || astChrMatch( "GEOCENTRIC", system ) || astChrMatch( "APPARENT", system ) ) { result = AST__GAPPT; } else if ( astChrMatch( "ECLIPTIC", system ) ) { result = AST__ECLIPTIC; } else if ( astChrMatch( "HELIOECLIPTIC", system ) ) { result = AST__HELIOECLIPTIC; } else if ( astChrMatch( "GALACTIC", system ) ) { result = AST__GALACTIC; } else if ( astChrMatch( "SUPERGALACTIC", system ) ) { result = AST__SUPERGALACTIC; } else if ( astChrMatch( "UNKNOWN", system ) ) { result = AST__UNKNOWN; } /* Return the result. */ return result; } static const char *SystemString( AstFrame *this, AstSystemType system, int *status ) { /* * Name: * SystemString * Purpose: * Convert a coordinate system type code into a string. * Type: * Private function. * Synopsis: * #include "skyframe.h" * const char *SystemString( AstFrame *this, AstSystemType system, int *status ) * Class Membership: * SkyFrame member function (over-rides the astSystemString method * inherited from the Frame class). * Description: * This function converts a SkyFrame coordinate system type code * (System attribute value) into a string suitable for use as an * external representation of the coordinate system type. * Parameters: * this * 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 sky coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. (Where possible, return the same string as would be used in the FITS WCS representation of the coordinate system). */ switch ( system ) { case AST__FK4: result = "FK4"; break; case AST__FK4_NO_E: result = "FK4-NO-E"; break; case AST__FK5: result = "FK5"; break; case AST__J2000: result = "J2000"; break; case AST__ICRS: result = "ICRS"; break; case AST__GAPPT: result = "GAPPT"; break; case AST__AZEL: result = "AZEL"; break; case AST__ECLIPTIC: result = "ECLIPTIC"; break; case AST__HELIOECLIPTIC: result = "HELIOECLIPTIC"; break; case AST__GALACTIC: result = "GALACTIC"; break; case AST__SUPERGALACTIC: result = "SUPERGALACTIC"; break; case AST__UNKNOWN: result = "Unknown"; break; } /* Return the result pointer. */ return result; } static int TestActiveUnit( AstFrame *this_frame, int *status ) { /* * Name: * TestActiveUnit * Purpose: * Test the ActiveUnit flag for a SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int TestActiveUnit( AstFrame *this_frame, int *status ) * Class Membership: * SkyFrame member function (over-rides the astTestActiveUnit protected * method inherited from the Frame class). * Description: * This function test the value of the ActiveUnit flag for a SkyFrame, * which is always "unset". * Parameters: * this * Pointer to the SkyFrame. * status * Pointer to the inherited status variable. * Returned Value: * The result of the test (0). */ return 0; } static int TestAsTime( AstSkyFrame *this, int axis, int *status ) { /* * Name: * TestAsTime * Purpose: * Determine if a value has been set for a SkyFrame's AsTime attribute. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int TestAsTime( AstSkyFrame *this, int axis, int *status ) * Class Membership: * SkyFrame member function. * Description: * This function returns a boolean value to indicate if a value has * previously been set for the AsTime attribute for a specified axis of a * SkyFrame. This attribute indicates whether axis values should be * formatted as times (as opposed to angles) by default. * Parameters: * this * Pointer to the SkyFrame. * axis * Index of the axis for which information is required (zero based). * status * Pointer to the inherited status variable. * Returned Value: * Zero or one, according to whether the AsTime attribute has been set. * 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. */ AstAxis *ax; /* Pointer to Axis object */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astTestAsTime" ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis ); /* Determine if the AsTime attribute has been set for it (it cannot have been set unless the object is a SkyAxis). */ result = ( astIsASkyAxis( ax ) && astTestAxisAsTime( ax ) ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* Return the result. */ 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 SkyFrame. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyFrame 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 SkyFrame's attributes. * Parameters: * this * Pointer to the SkyFrame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Returned Value: * One if a value has been set, otherwise zero. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ int axis; /* SkyFrame axis number */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* AsTime(axis). */ /* ------------- */ if ( nc = 0, ( 1 == astSscanf( attrib, "astime(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestAsTime( this, axis - 1 ); /* Equinox. */ /* -------- */ } else if ( !strcmp( attrib, "equinox" ) ) { result = astTestEquinox( this ); /* NegLon. */ /* ------- */ } else if ( !strcmp( attrib, "neglon" ) ) { result = astTestNegLon( this ); /* SkyTol. */ /* ------- */ } else if ( !strcmp( attrib, "skytol" ) ) { result = astTestSkyTol( this ); /* Projection. */ /* ----------- */ } else if ( !strcmp( attrib, "projection" ) ) { result = astTestProjection( this ); /* SkyRefIs. */ /* --------- */ } else if ( !strcmp( attrib, "skyrefis" ) ) { result = astTestSkyRefIs( this ); /* SkyRef. */ /* ------- */ } else if ( !strcmp( attrib, "skyref" ) ) { result = astTestSkyRef( this, 0 ) || astTestSkyRef( this, 1 ); /* SkyRef(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyref(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestSkyRef( this, axis - 1 ); /* SkyRefP. */ /* -------- */ } else if ( !strcmp( attrib, "skyrefp" ) ) { result = astTestSkyRefP( this, 0 ) || astTestSkyRefP( this, 1 ); /* SkyRefP(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "skyrefp(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestSkyRefP( this, axis - 1 ); /* AlignOffset */ /* ----------- */ } else if ( !strcmp( attrib, "alignoffset" ) ) { result = astTestAlignOffset( 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 ( !strncmp( attrib, "islataxis", 9 ) || !strncmp( attrib, "islonaxis", 9 ) || !strcmp( attrib, "lataxis" ) || !strcmp( attrib, "lonaxis" ) ) { result = 0; /* If the attribute is not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static int TestSlaUnit( AstSkyFrame *sf1, AstSkyFrame *sf2, AstSlaMap *slamap, int *status ){ /* * Name: * Unformat * Purpose: * See if a slamap is effectively a unit mapping. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int TestSlaUnit( AstSkyFrame *sf1, AstSkyFrame *sf2, AstSlaMap *slamap, * int *status ) * Class Membership: * SkyFrame member function. * Description: * This function tests a SlaMap to see if it is effectively a unit * transformatuon to within a tolerance given by the smaller tolerance * of the two supplied SkyFrames. * Parameters: * sf1 * Pointer to the first SkyFrame. * sf2 * Pointer to the second SkyFrame (may be NULL) * slamap * Pointer to the SlaMap to test. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the SlaMap is effectively a unit mapping, and zero * otherwise. */ /* Number of test points. */ #define NTEST 14 /* Local Variables: */ double maxshift; /* Max. shift produced by slamap (rads) */ double olat[NTEST]; /* Transformed latitudes */ double olon[NTEST]; /* Transformed longitudes */ double shift; /* Shift produced by slamap (rads) */ double tol2; /* Second tolerance (in radians) */ double tol; /* Used tolerance (in radians) */ int i; /* Loop count */ int result; /* Returned flag */ /* A grid of lon/lat points covering the sphere. */ double lat[ NTEST ] = { 0.0, 0.0, 0.0, 0.0, 0.8, 0.8, 0.8, 0.8, -0.8, -0.8, -0.8, -0.8, 1.570796, -1.570796 }; double lon[ NTEST ] = { 0.0, 1.57, 3.14, 4.71, 0.8, 2.37, 3.94, 5.51, 0.8, 2.37, 3.94, 5.51, 0.0, 0.0 }; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* If the SlaMap is empty (i.e. has no conversions in it), then is it a UnitMap. So save time by not transforming the test values. */ if( astSlaIsEmpty( slamap ) ) { result = 1; /* Otherwise, get the smaller of the tolerances associated with the supplied SkyFrames, in radians. */ } else { tol = astGetSkyTol( sf1 ); if( sf2 ) { tol2 = astGetSkyTol( sf2 ); if( tol2 < tol ) tol = tol2; } /* If the tolerance is zero, there is no need to do the test. */ if( tol > 0.0 ) { /* Transform the test point using the SlaMap. */ astTran2( slamap, NTEST, lon, lat, 1, olon, olat ); /* Find the maximum shift produced by the SlaMap at any of the test positions. Again, to avoid the slow-down produced by checking for axis permutation, use palDsep rather than astDistance. */ maxshift = 0.0; for( i = 0; i < NTEST; i++ ) { shift = palDsep( lon[ i ], lat[ i ], olon[ i ], olat[ i ] ); if( shift > maxshift ) maxshift = shift; } /* Convert the max shift to arc-seconds and do the check. */ result = ( maxshift*AST__DR2D*3600 < tol ); } } 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 SkyFrame axis. * Type: * Private function. * Synopsis: * #include "skyframe.h" * int Unformat( AstFrame *this, int axis, const char *string, * double *value, int *status ) * Class Membership: * SkyFrame member function (over-rides the public astUnformat * method inherited from the Frame class). * Description: * This function reads a formatted coordinate value for a SkyFrame * 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 SkyFrame. * axis * The number of the SkyFrame 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 (in radians). * 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 "" 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: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ double coord; /* Coordinate value read */ int format_set; /* Format attribute set? */ int nc; /* Number of characters read */ /* Initialise. */ nc = 0; /* Check the global error status. */ if ( !astOK ) return nc; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_frame; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astUnformat" ); /* Determine if a Format value has been set for the axis and set a temporary value if it has not. Use the GetFormat member function for this class together with member functions inherited from the parent class (rather than using the object's methods directly) because if any of these methods have been over-ridden by a derived class the Format string syntax may no longer be compatible with this class. */ format_set = (*parent_testformat)( this_frame, axis, status ); if ( !format_set ) { (*parent_setformat)( this_frame, axis, GetFormat( this_frame, axis, status ), status ); } /* Use the Unformat member function inherited from the parent class to read the coordinate value. */ nc = (*parent_unformat)( this_frame, axis, string, &coord, status ); /* If necessary, clear any temporary Format value that was set above. */ if ( !format_set ) (*parent_clearformat)( this_frame, axis, status ); /* 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 ValidateSystem( AstFrame *this, AstSystemType system, const char *method, int *status ) { /* * * Name: * ValidateSystem * Purpose: * Validate a value for a Frame's System attribute. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int ValidateSystem( AstFrame *this, AstSystemType system, * const char *method, int *status ) * Class Membership: * SkyFrame member function (over-rides the 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 */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* If the value is out of bounds, report an error. */ if ( system < FIRST_SYSTEM || system > LAST_SYSTEM ) { astError( AST__AXIIN, "%s(%s): Bad value (%d) given for the System " "or AlignSystem attribute of a %s.", status, method, astGetClass( this ), (int) system, astGetClass( this ) ); /* Otherwise, return the supplied value. */ } else { result = system; } /* Return the result. */ return result; } static void VerifyMSMAttrs( AstSkyFrame *target, AstSkyFrame *result, int which, const char *attrs, const char *method, int *status ) { /* * Name: * VerifyMSMAttrs * Purpose: * Verify that usable attribute values are available. * Type: * Private function. * Synopsis: * #include "skyframe.h" * void VerifyMSMAttrs( AstSkyFrame *target, AstSkyFrame *result, * int which, const char *attrs, const char *method, int *status ) * Class Membership: * SkyFrame member function * Description: * This function tests each attribute listed in "attrs". It returns * without action if 1) an explicit value has been set for each attribute * in the SkyFrame indicated by "which" or 2) the UseDefs attribute of the * "which" SkyFrame is non-zero. * * If UseDefs is zero (indicating that default values should not be * used for attributes), and any of the named attributes does not have * an explicitly set value, then an error is reported. * * The displayed error message assumes that tjis function was called * as part of the process of producing a Mapping from "target" to "result". * Parameters: * target * Pointer to the target SkyFrame. * result * Pointer to the result SkyFrame. * which * If 2, both the target and result SkyFrames are checked for the * supplied attributes. If less than 2, only the target SkyFrame is * checked. If greater than 2, only the result SkyFrame is checked. * attrs * A string holding a space separated list of attribute names. * method * A string holding the name of the calling method for use in error * messages. * status * Pointer to the inherited status variable. */ /* Local Variables: */ const char *a; const char *p; const char *desc; int len; int set1; int set2; int state; int usedef1; int usedef2; /* Check inherited status */ if( !astOK ) return; /* Get the UseDefs attributes of the two SkyFrames. */ usedef1 = astGetUseDefs( target ); usedef2 = astGetUseDefs( result ); /* If both SkyFrames have a non-zero value for its UseDefs attribute, then all attributes are assumed to have usable values, since the defaults will be used if no explicit value has been set. So we only need to do any checks if UseDefs is zero for either SkyFrame. */ if( !usedef1 || !usedef2 ) { /* Stop compiler warnings about uninitialised variables */ a = NULL; desc = NULL; len = 0; set1 = 0; set2 = 0; /* Loop round the "attrs" string identifying the start and length of each non-blank word in the string. */ state = 0; p = attrs; while( 1 ) { if( state == 0 ) { if( !isspace( *p ) ) { a = p; len = 1; state = 1; } } else { if( isspace( *p ) || !*p ) { /* The end of a word has just been reached. Compare it to each known attribute value. Get a flag indicating if the attribute has a set value, and a string describing the attribute.*/ if( len > 0 ) { if( !strncmp( "Equinox", a, len ) ) { set1 = astTestEquinox( target ); set2 = astTestEquinox( result ); desc = "reference equinox"; } else if( !strncmp( "Dut1", a, len ) ) { set1 = astTestDut1( target ); set2 = astTestDut1( result ); desc = "UT1-UTC correction"; } else if( !strncmp( "Epoch", a, len ) ) { set1 = astTestEpoch( target ); set2 = astTestEpoch( result ); desc = "epoch of observation"; } else if( !strncmp( "ObsLon", a, len ) ) { set1 = astTestObsLon( target ); set2 = astTestObsLon( result ); desc = "longitude of observer"; } else if( !strncmp( "ObsLat", a, len ) ) { set1 = astTestObsLat( target ); set2 = astTestObsLat( result ); desc = "latitude of observer"; } else if( !strncmp( "ObsAlt", a, len ) ) { set1 = astTestObsAlt( target ); set2 = astTestObsAlt( result ); desc = "altitude of observer"; } else { astError( AST__INTER, "VerifyMSMAttrs(SkyFrame): " "Unknown attribute name \"%.*s\" supplied (AST " "internal programming error).", status, len, a ); } /* If the attribute is not set in the target but should be, report an error. */ if( !usedef1 && !set1 && which < 3 ) { astClearTitle( target ); astClearTitle( result ); astError( AST__NOVAL, "%s(%s): Cannot convert " "celestial coordinates from %s to %s.", status, method, astGetClass( target ), astGetC( target, "Title" ), astGetC( result, "Title" ) ); astError( AST__NOVAL, "No value has been set for " "the \"%.*s\" attribute (%s) in the input %s.", status, len, a, desc, astGetClass( target ) ); break; } /* If the attribute is not set in the result but should be, report an error. */ if( !usedef2 && !set2 && which > 1 ) { astClearTitle( target ); astClearTitle( result ); astError( AST__NOVAL, "%s(%s): Cannot convert " "celestial coordinates from %s to %s.", status, method, astGetClass( result ), astGetC( target, "Title" ), astGetC( result, "Title" ) ); astError( AST__NOVAL, "No value has been set for " "the \"%.*s\" attribute (%s) in the output %s.", status, len, a, desc, astGetClass( result ) ); break; } /* Continue the word search algorithm. */ } len = 0; state = 0; } else { len++; } } if( !*(p++) ) break; } } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* *att++ * Name: * AlignOffset * Purpose: * Align SkyFrames using the offset coordinate system? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which controls how a SkyFrame * behaves when it is used (by c astFindFrame or astConvert) as a template to match another (target) f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) * SkyFrame. It determines the coordinate system in which the two * SkyFrames are aligned if a match occurs. * * If the template and target SkyFrames both have defined offset coordinate * systems (i.e. the SkyRefIs attribute is set to either "Origin" or " * Pole"), and they both have a non-zero value for AlignOffset, then * alignment occurs within the offset coordinate systems (that is, a * UnitMap will always be used to align the two SkyFrames). If either * the template or target SkyFrame has zero (the default value) for * AlignOffset, or if either SkyFrame has SkyRefIs set to "Ignored", then * alignment occurring within the coordinate system specified by the * AlignSystem attribute. * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ astMAKE_CLEAR(SkyFrame,AlignOffset,alignoffset,-INT_MAX) astMAKE_GET(SkyFrame,AlignOffset,int,0,( ( this->alignoffset != -INT_MAX ) ? this->alignoffset : 0 )) astMAKE_SET(SkyFrame,AlignOffset,int,alignoffset,( value != 0 )) astMAKE_TEST(SkyFrame,AlignOffset,( this->alignoffset != -INT_MAX )) /* *att++ * Name: * AsTime(axis) * Purpose: * Format celestal coordinates as times? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute specifies the default style of formatting to be c used (e.g. by astFormat) for the celestial coordinate values f used (e.g. by AST_FORMAT) for the celestial coordinate values * described by a SkyFrame. It takes a separate boolean value for * each SkyFrame axis so that, for instance, the setting * "AsTime(2)=0" specifies the default formatting style for * celestial latitude values. * * If the AsTime attribute for a SkyFrame axis is zero, then * coordinates on that axis will be formatted as angles by default * (using degrees, minutes and seconds), otherwise they will be * formatted as times (using hours, minutes and seconds). * * The default value of AsTime is chosen according to the sky * coordinate system being represented, as determined by the * SkyFrame's System attribute. This ensures, for example, that * right ascension values will be formatted as times by default, * following normal conventions. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - The AsTime attribute operates by changing the default value of * the corresponding Format(axis) attribute. This, in turn, may * also affect the value of the Unit(axis) attribute. * - Only the default style of formatting is affected by the AsTime * value. If an explicit Format(axis) value is set, it will * over-ride any effect from the AsTime attribute. *att-- */ /* *att++ * Name: * Equinox * Purpose: * Epoch of the mean equinox. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute is used to qualify those celestial coordinate * systems described by a SkyFrame which are notionally based on * the ecliptic (the plane of the Earth's orbit around the Sun) * and/or the Earth's equator. * * Both of these planes are in motion and their positions are * difficult to specify precisely. In practice, therefore, a model * ecliptic and/or equator are used instead. These, together with * the point on the sky that defines the coordinate origin (the * intersection of the two planes termed the "mean equinox") move * with time according to some model which removes the more rapid * fluctuations. The SkyFrame class supports both the FK4 and * FK5 models. * * The position of a fixed source expressed in any of these * coordinate systems will appear to change with time due to * movement of the coordinate system itself (rather than motion of * the source). Such coordinate systems must therefore be * qualified by a moment in time (the "epoch of the mean equinox" * or "equinox" for short) which allows the position of the model * coordinate system on the sky to be determined. This is the role * of the Equinox attribute. * * The Equinox attribute is stored as a Modified Julian Date, but * when setting or getting its value you may use the same formats * as for the Epoch attribute (q.v.). * * The default Equinox value is B1950.0 (Besselian) for the old * FK4-based coordinate systems (see the System attribute) and * J2000.0 (Julian) for all others. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - Care must be taken to distinguish the Equinox value, which * relates to the definition of a time-dependent coordinate system * (based on solar system reference planes which are in motion), * from the superficially similar Epoch value. The latter is used * to qualify coordinate systems where the positions of sources * change with time (or appear to do so) for a variety of other * reasons, such as aberration of light caused by the observer's * motion, etc. * - See the description of the System attribute for details of * which qualifying attributes apply to each celestial coordinate * system. *att-- */ /* Clear the Equinox value by setting it to AST__BAD. */ astMAKE_CLEAR(SkyFrame,Equinox,equinox,AST__BAD) /* Provide a default value of B1950.0 or J2000.0 depending on the System setting. */ astMAKE_GET(SkyFrame,Equinox,double,AST__BAD,( ( this->equinox != AST__BAD ) ? this->equinox : ( ( ( astGetSystem( this ) == AST__FK4 ) || ( astGetSystem( this ) == AST__FK4_NO_E ) ) ? palEpb2d( 1950.0 ) : palEpj2d( 2000.0 ) ) )) /* Allow any Equinox value to be set, unless the System is Helio-ecliptic (in which case clear the value so that J2000 is used). */ astMAKE_SET(SkyFrame,Equinox,double,equinox,((astGetSystem(this)!=AST__HELIOECLIPTIC)?value:AST__BAD)) /* An Equinox value is set if it is not equal to AST__BAD. */ astMAKE_TEST(SkyFrame,Equinox,( this->equinox != AST__BAD )) /* *att++ * Name: * IsLatAxis(axis) * Purpose: * Is the specified celestial axis a latitude axis? * Type: * Public attribute. * Synopsis: * Integer (boolean), read-only. * Description: * This is a read-only boolean attribute that indicates the nature of * the specified axis. The attribute has a non-zero value if the * specified axis is a celestial latitude axis (Declination, Galactic * latitude, etc), and is zero otherwise. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the SkyFrame axis to be tested. *att-- */ /* *att++ * Name: * IsLonAxis(axis) * Purpose: * Is the specified celestial axis a longitude axis? * Type: * Public attribute. * Synopsis: * Integer (boolean), read-only. * Description: * This is a read-only boolean attribute that indicates the nature of * the specified axis. The attribute has a non-zero value if the * specified axis is a celestial longitude axis (Right Ascension, Galactic * longitude, etc), and is zero otherwise. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the SkyFrame axis to be tested. *att-- */ /* *att++ * Name: * LatAxis * Purpose: * Index of the latitude axis. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This read-only attribute gives the index (1 or 2) of the latitude * axis within the SkyFrame (taking into account any current axis * permutations). * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ /* *att++ * Name: * LonAxis * Purpose: * Index of the longitude axis. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This read-only attribute gives the index (1 or 2) of the longitude * axis within the SkyFrame (taking into account any current axis * permutations). * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ /* *att++ * Name: * NegLon * Purpose: * Display negative longitude values? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which controls how longitude values c are normalized for display by astNorm. f are normalized for display by AST_NORM. * * If the NegLon attribute is zero, then normalized * longitude values will be in the range zero to 2.pi. If NegLon is * non-zero, then normalized longitude values will be in the range -pi * to pi. * * The default value depends on the current value of the SkyRefIs * attribute, If SkyRefIs has a value of "Origin", then the default for * NegLon is one, otherwise the default is zero. * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ /* Clear the NegLon value by setting it to -INT_MAX. */ astMAKE_CLEAR(SkyFrame,NegLon,neglon,-INT_MAX) /* Supply a default of 0 for absolute coords and 1 for offset coords if no NegLon value has been set. */ astMAKE_GET(SkyFrame,NegLon,int,0,( ( this->neglon != -INT_MAX ) ? this->neglon : (( astGetSkyRefIs( this ) == AST__ORIGIN_REF )? 1 : 0))) /* Set a NegLon value of 1 if any non-zero value is supplied. */ astMAKE_SET(SkyFrame,NegLon,int,neglon,( value != 0 )) /* The NegLon value is set if it is not -INT_MAX. */ astMAKE_TEST(SkyFrame,NegLon,( this->neglon != -INT_MAX )) /* *att++ * Name: * SkyTol * Purpose: * The smallest significant shift in sky coordinates. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute indicates the accuracy of the axis values that will * be represented by the SkyFrame. If the arc-distance between two * positions within the SkyFrame is smaller than the value of SkyTol, * then the two positions will (for the puposes indicated below) be * considered to be co-incident. * * This value is used only when constructing the Mapping between * two different SkyFrames (for instance, when calling c astConvert or astFindFrame). f AST_CONVERT or AST_FINDFRAME). * If the transformation between the two SkyFrames causes positions to * shift by less than SkyTol arc-seconds, then the transformation is * replaced by a UnitMap. This could in certain circumatances allow * major simplifications to be made to the transformation between * any pixel grids associated with the two SkyFrames (for instance, if * each SkyFrame is part of the WCS FrameSet associated with an image). * * A common case is when two SkyFrames use the FK5 system, but have * slightly different Epoch values. If the AlignSystem attribute has * its default value of "ICRS", then the transformation between the * two SkyFrames will include a very small rotation (FK5 rotates with * respect to ICRS as a rate of about 0.0005 arc-seconds per year). In * most circumstances such a small rotation is insignificant. Setting * SkyTol to some suitably small non-zero value will cause this * rotation to be ignored, allowing much simpler transformations to * be used. * * The test to determine the shift introduced by transforming between * the two SkyFrames is performed by transforming a set of 14 position * spread evenly over the whole sky. The largest shift produced at any * of these 14 positions is compared to the value of SkyTol. * * The SkyTol value is in units of arc-seconds, and the default value * is 0.001. * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ astMAKE_CLEAR(SkyFrame,SkyTol,skytol,AST__BAD) astMAKE_GET(SkyFrame,SkyTol,double,0.001,((this->skytol!=AST__BAD)?this->skytol:0.001)) astMAKE_SET(SkyFrame,SkyTol,double,skytol,fabs(value)) astMAKE_TEST(SkyFrame,SkyTol,(this->skytol!=AST__BAD)) /* *att++ * Name: * Projection * Purpose: * Sky projection description. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute provides a place to store a description of the * type of sky projection used when a SkyFrame is attached to a * 2-dimensional object, such as an image or plotting surface. For * example, typical values might be "orthographic", "Hammer-Aitoff" * or "cylindrical equal area". * * The Projection value is purely descriptive and does not affect * the celestial coordinate system represented by the SkyFrame in * any way. If it is set to a non-blank string, the description * provided may be used when forming the default value for the * SkyFrame's Title attribute (so that typically it will appear in * graphical output, for instance). The default value is an empty * string. * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ /* Clear the Projection value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(SkyFrame,Projection,projection,astFree( this->projection )) /* If the Projection value is not set, return a pointer to an empty string. */ astMAKE_GET(SkyFrame,Projection,const char *,NULL,( this->projection ? this->projection : "" )) /* Set a Projection value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(SkyFrame,Projection,const char *,projection,astStore( this->projection, value, strlen( value ) + (size_t) 1 )) /* The Projection value is set if the pointer to it is not NULL. */ astMAKE_TEST(SkyFrame,Projection,( this->projection != NULL )) /* *att++ * Name: * SkyRefIs * Purpose: * Selects the nature of the offset coordinate system. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls how the values supplied for the SkyRef and * SkyRefP attributes are used. These three attributes together allow * a SkyFrame to represent offsets relative to some specified origin * or pole within the coordinate system specified by the System attribute, * rather than absolute axis values. SkyRefIs can take one of the * case-insensitive values "Origin", "Pole" or "Ignored". * * If SkyRefIs is set to "Origin", then the coordinate system * represented by the SkyFrame is modified to put the origin of longitude * and latitude at the position specified by the SkyRef attribute. * * If SkyRefIs is set to "Pole", then the coordinate system represented * by the SkyFrame is modified to put the north pole at the position * specified by the SkyRef attribute. * * If SkyRefIs is set to "Ignored" (the default), then any value set for the * SkyRef attribute is ignored, and the SkyFrame represents the coordinate * system specified by the System attribute directly without any rotation. * Applicability: * SkyFrame * All SkyFrames have this attribute. *att-- */ astMAKE_CLEAR(SkyFrame,SkyRefIs,skyrefis,AST__BAD_REF) astMAKE_SET(SkyFrame,SkyRefIs,int,skyrefis,value) astMAKE_TEST(SkyFrame,SkyRefIs,( this->skyrefis != AST__BAD_REF )) astMAKE_GET(SkyFrame,SkyRefIs,int,AST__IGNORED_REF,(this->skyrefis == AST__BAD_REF ? AST__IGNORED_REF : this->skyrefis)) /* *att++ * Name: * SkyRef(axis) * Purpose: * Position defining the offset coordinate system. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute allows a SkyFrame to represent offsets, rather than * absolute axis values, within the coordinate system specified by the * System attribute. If supplied, SkyRef should be set to hold the * longitude and latitude of a point within the coordinate system * specified by the System attribute. The coordinate system represented * by the SkyFrame will then be rotated in order to put the specified * position at either the pole or the origin of the new coordinate system * (as indicated by the SkyRefIs attribute). The orientation of the * modified coordinate system is then controlled using the SkyRefP * attribute. * * If an integer axis index is included in the attribute name (e.g. * "SkyRef(1)") then the attribute value should be supplied as a single * floating point axis value, in radians, when setting a value for the * attribute, and will be returned in the same form when getting the value * of the attribute. In this case the integer axis index should be "1" * or "2" (the values to use for longitude and latitude axes are * given by the LonAxis and LatAxis attributes). * * If no axis index is included in the attribute name (e.g. "SkyRef") then * the attribute value should be supplied as a character string * containing two formatted axis values (an axis 1 value followed by a * comma, followed by an axis 2 value). The same form * will be used when getting the value of the attribute. * * The default values for SkyRef are zero longitude and zero latitude. * Aligning SkyFrames with Offset Coordinate Systems: * The offset coordinate system within a SkyFrame should normally be * considered as a superficial "re-badging" of the axes of the coordinate * system specified by the System attribute - it merely provides an * alternative numerical "label" for each position in the System coordinate * system. The SkyFrame retains full knowledge of the celestial coordinate * system on which the offset coordinate system is based (given by the * System attribute). For instance, the SkyFrame retains knowledge of the * way that one celestial coordinate system may "drift" with respect to * another over time. Normally, if you attempt to align two SkyFrames (e.g. f using the AST_CONVERT or AST_FINDFRAME routine), c using the astConvert or astFindFrame routine), * the effect of any offset coordinate system defined in either SkyFrame * will be removed, resulting in alignment being performed in the * celestial coordinate system given by the AlignSystem attribute. * However, by setting the AlignOffset attribute ot a non-zero value, it * is possible to change this behaviour so that the effect of the offset * coordinate system is not removed when aligning two SkyFrames. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - If the System attribute of the SkyFrame is changed, any position * given for SkyRef is transformed into the new System. * - If a value has been assigned to SkyRef attribute, then * the default values for certain attributes are changed as follows: * the default axis Labels for the SkyFrame are modified by appending * " offset" to the end, the default axis Symbols for the SkyFrame are * modified by prepending the character "D" to the start, and the * default title is modified by replacing the projection information by the * origin information. *att-- */ MAKE_CLEAR(SkyRef,skyref,AST__BAD,2) MAKE_SET(SkyRef,double,skyref,value,2) MAKE_TEST(SkyRef,( this->skyref[axis_p] != AST__BAD ),2) MAKE_GET(SkyRef,double,0.0,((this->skyref[axis_p]!=AST__BAD)?this->skyref[axis_p]:0.0),2) /* *att++ * Name: * SkyRefP(axis) * Purpose: * Position on primary meridian of offset coordinate system. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute is used to control the orientation of the offset * coordinate system defined by attributes SkyRef and SkyRefIs. If used, * it should be set to hold the longitude and latitude of a point within * the coordinate system specified by the System attribute. The offset * coordinate system represented by the SkyFrame will then be rotated in * order to put the position supplied for SkyRefP on the zero longitude * meridian. This rotation is about an axis from the centre of the * celestial sphere to the point specified by the SkyRef attribute. * The default value for SkyRefP is usually the north pole (that is, a * latitude of +90 degrees in the coordinate system specified by the System * attribute). The exception to this is if the SkyRef attribute is * itself set to either the north or south pole. In these cases the * default for SkyRefP is the origin (that is, a (0,0) in the coordinate * system specified by the System attribute). * * If an integer axis index is included in the attribute name (e.g. * "SkyRefP(1)") then the attribute value should be supplied as a single * floating point axis value, in radians, when setting a value for the * attribute, and will be returned in the same form when getting the value * of the attribute. In this case the integer axis index should be "1" * or "2" (the values to use for longitude and latitude axes are * given by the LonAxis and LatAxis attributes). * * If no axis index is included in the attribute name (e.g. "SkyRefP") then * the attribute value should be supplied as a character string * containing two formatted axis values (an axis 1 value followed by a * comma, followed by an axis 2 value). The same form * will be used when getting the value of the attribute. * Applicability: * SkyFrame * All SkyFrames have this attribute. * Notes: * - If the position given by the SkyRef attribute defines the origin * of the offset coordinate system (that is, if the SkyRefIs attribute * is set to "origin"), then there will in general be two orientations * which will put the supplied SkyRefP position on the zero longitude * meridian. The orientation which is actually used is the one which * gives the SkyRefP position a positive latitude in the offset coordinate * system (the other possible orientation would give the SkyRefP position * a negative latitude). * - An error will be reported if an attempt is made to use a * SkyRefP value which is co-incident with SkyRef or with the point * diametrically opposite to SkyRef on the celestial sphere. The * reporting of this error is deferred until the SkyRef and SkyRefP * attribute values are used within a calculation. * - If the System attribute of the SkyFrame is changed, any position * given for SkyRefP is transformed into the new System. *att-- */ MAKE_CLEAR(SkyRefP,skyrefp,AST__BAD,2) MAKE_SET(SkyRefP,double,skyrefp,value,2) MAKE_TEST(SkyRefP,( this->skyrefp[axis_p] != AST__BAD ),2) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SkyFrame objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SkyFrame 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: */ AstSkyFrame *in; /* Pointer to input SkyFrame */ AstSkyFrame *out; /* Pointer to output SkyFrame */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SkyFrames. */ in = (AstSkyFrame *) objin; out = (AstSkyFrame *) objout; /* For safety, first clear any references to the input memory from the output SkyFrame. */ out->projection = NULL; /* If necessary, allocate memory in the output SkyFrame and store a copy of the input Projection string. */ if ( in->projection ) out->projection = astStore( NULL, in->projection, strlen( in->projection ) + (size_t) 1 ); /* If an error occurred, free any allocated memory. */ if ( !astOK ) { out->projection = astFree( out->projection ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SkyFrame objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SkyFrame 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: */ AstSkyFrame *this; /* Pointer to SkyFrame */ /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) obj; /* Free the memory used for the Projection string if necessary. */ this->projection = astFree( this->projection ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SkyFrame 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 SkyFrame class to an output Channel. * Parameters: * this * Pointer to the SkyFrame 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 Variables: */ AstSkyFrame *this; /* Pointer to the SkyFrame structure */ AstSystemType system; /* System attribute value */ char buf[ 100 ]; /* Comment buffer */ char key[ 10 ]; /* Buffer for keywords */ const char *sval; /* Pointer to string value */ const int *perm; /* Pointer to axis permutation array */ double dval; /* Double value */ int bessyr; /* Use a Besselian year value ?*/ int helpful; /* Helpful to display un-set value? */ int invperm[ 2 ]; /* Inverse permutation array */ int ival; /* Integer value */ int set; /* Attribute value set? */ int axis; /* External (i.e. permuted) zero-based axis index */ int axis_p; /* Internal zero-based axis index */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyFrame structure. */ this = (AstSkyFrame *) this_object; /* Get a pointer to the SkyFrame's axis permutation array (using a method, to allow for any over-ride by a derived class). */ perm = astGetPerm( this ); /* Generate an inverse axis permutation array from the forward permutation values. This will be used to determine which axis should be enquired about (using possibly over-ridden methods) to obtain data to correspond with a particular internal value (i.e. instance variable) relating to an axis. This step is needed so that the effect of any axis permutation can be un-done before values are written out, as output values are written by this function in un-permuted order. */ for ( axis = 0; axis < 2; axis++ ) invperm[ perm[ axis ] ] = axis; /* Write out values representing the instance variables for the SkyFrame 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. */ /* Projection. */ /* ----------- */ set = TestProjection( this, status ); sval = set ? GetProjection( this, status ) : astGetProjection( this ); astWriteString( channel, "Proj", set, 0, sval, "Description of sky projection" ); /* NegLon. */ /* ------- */ set = TestNegLon( this, status ); ival = set ? GetNegLon( this, status ) : astGetNegLon( this ); astWriteInt( channel, "NegLon", set, 0, ival, ival ? "Display negative longitude values" : "Display positive longitude values" ); /* SkyTol. */ /* ------- */ set = TestSkyTol( this, status ); dval = set ? GetSkyTol( this, status ) : astGetSkyTol( this ); astWriteDouble( channel, "SkyTol", set, 1, dval, "Smallest significant separation [arc-sec]"); /* Equinox. */ /* -------- */ set = TestEquinox( this, status ); dval = set ? GetEquinox( this, status ) : astGetEquinox( this ); /* Decide whether the Equinox value is relevant to the current coordinate system. */ system = astGetSystem( this ); helpful = ( ( system == AST__FK4 ) || ( system == AST__FK4_NO_E ) || ( system == AST__FK5 ) || ( system == AST__ECLIPTIC ) ); /* Convert MJD to Besselian or Julian years, depending on the value. */ bessyr = ( dval < palEpj2d( 1984.0 ) ); dval = bessyr ? palEpb( dval ) : palEpj( dval ); astWriteDouble( channel, "Eqnox", set, helpful, dval, bessyr ? "Besselian epoch of mean equinox" : "Julian epoch of mean equinox" ); /* SkyRefIs. */ /* --------- */ set = TestSkyRefIs( this, status ); ival = set ? GetSkyRefIs( this, status ) : astGetSkyRefIs( this ); if( ival == AST__POLE_REF ) { astWriteString( channel, "SRefIs", set, 0, POLE_STRING, "Rotated to put pole at ref. pos." ); } else if( ival == AST__IGNORED_REF ) { astWriteString( channel, "SRefIs", set, 0, IGNORED_STRING, "Not rotated (ref. pos. is ignored)" ); } else { astWriteString( channel, "SRefIs", set, 0, ORIGIN_STRING, "Rotated to put origin at ref. pos." ); } /* SkyRef. */ /* ------- */ /* The inverse axis permutation array is used to obtain the axis index to use when accessing the SkyRef attribute. This reverses the effect of the SkyFrame's axis permutation array and yields a value appropriate to the axis with internal index "axis". */ for ( axis_p = 0; axis_p < 2; axis_p++ ) { axis = invperm[ axis_p ]; set = TestSkyRef( this, axis, status ); dval = set ? GetSkyRef( this, axis, status ) : astGetSkyRef( this, axis ); sprintf( buf, "Ref. pos. %s %s", astGetSymbol( this, axis ), astFormat( this, axis, dval ) ); sprintf( key, "SRef%d", axis_p + 1 ); astWriteDouble( channel, key, set, 0, dval, buf ); } /* SkyRefP. */ /* -------- */ for ( axis_p = 0; axis_p < 2; axis_p++ ) { axis = invperm[ axis_p ]; set = TestSkyRefP( this, axis, status ); dval = set ? GetSkyRefP( this, axis, status ) : astGetSkyRefP( this, axis ); sprintf( buf, "Ref. north %s %s", astGetSymbol( this, axis ), astFormat( this, axis, dval ) ); sprintf( key, "SRefP%d", axis_p + 1 ); astWriteDouble( channel, key, set, 0, dval, buf ); } /* AlignOffset. */ /* ------------ */ set = TestAlignOffset( this, status ); ival = set ? GetAlignOffset( this, status ) : astGetAlignOffset( this ); astWriteInt( channel, "AlOff", set, 0, ival, ival ? "Align in offset coords" : "Align in system coords" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASkyFrame and astCheckSkyFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SkyFrame,Frame) astMAKE_CHECK(SkyFrame) AstSkyFrame *astSkyFrame_( const char *options, int *status, ...) { /* *+ * Name: * astSkyFrame * Purpose: * Create a SkyFrame. * Type: * Protected function. * Synopsis: * #include "skyframe.h" * AstSkyFrame *astSkyFrame( const char *options, int *status, ... ) * Class Membership: * SkyFrame constructor. * Description: * This function creates a new SkyFrame and optionally initialises its * attributes. * Parameters: * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new SkyFrame. 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 SkyFrame. * 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 SkyFrame constructor which * is available via the protected interface to the SkyFrame class. * A public interface is provided by the astSkyFrameId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyFrame *new; /* Pointer to new SkyFrame */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SkyFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSkyFrame( NULL, sizeof( AstSkyFrame ), !class_init, &class_vtab, "SkyFrame" ); /* 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 SkyFrame'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 SkyFrame. */ return new; } AstSkyFrame *astInitSkyFrame_( void *mem, size_t size, int init, AstSkyFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSkyFrame * Purpose: * Initialise a SkyFrame. * Type: * Protected function. * Synopsis: * #include "skyframe.h" * AstSkyFrame *astInitSkyFrame( void *mem, size_t size, int init, * AstFrameVtab *vtab, const char *name ) * Class Membership: * SkyFrame initialiser. * Description: * This function is provided for use by class implementations to initialise * a new SkyFrame object. It allocates memory (if necessary) to accommodate * the SkyFrame plus any additional data associated with the derived class. * It then initialises a SkyFrame 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 SkyFrame at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SkyFrame is to be created. This * must be of sufficient size to accommodate the SkyFrame data * (sizeof(SkyFrame)) 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 SkyFrame (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 SkyFrame * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the SkyFrame'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 SkyFrame. * 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). * Returned Value: * A pointer to the new SkyFrame. * 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: */ AstSkyAxis *ax; /* Pointer to SkyAxis object */ AstSkyFrame *new; /* Pointer to the new SkyFrame */ int axis; /* Loop counter for axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSkyFrameVtab( vtab, name ); /* Initialise a Frame structure (the parent class) as the first component within the SkyFrame structure, allocating memory if necessary. */ new = (AstSkyFrame *) astInitFrame( mem, size, 0, (AstFrameVtab *) vtab, name, 2 ); if ( astOK ) { /* Initialise the SkyFrame data. */ /* ----------------------------- */ /* Initialise all attributes to their "undefined" values. */ new->equinox = AST__BAD; new->projection = NULL; new->neglon = -INT_MAX; new->skytol = AST__BAD; new->alignoffset = -INT_MAX; new->skyrefis = AST__BAD_REF; new->skyref[ 0 ] = AST__BAD; new->skyref[ 1 ] = AST__BAD; new->skyrefp[ 0 ] = AST__BAD; new->skyrefp[ 1 ] = AST__BAD; new->last = AST__BAD; new->eplast = AST__BAD; new->klast = AST__BAD; new->diurab = AST__BAD; /* Loop to replace the Axis object associated with each SkyFrame axis with a SkyAxis object instead. */ for ( axis = 0; axis < 2; axis++ ) { /* Create the new SkyAxis, assign it to the required SkyFrame axis and then annul the SkyAxis pointer. */ ax = astSkyAxis( "", status ); astSetAxis( new, axis, ax ); ax = astAnnul( ax ); } /* 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; } AstSkyFrame *astLoadSkyFrame_( void *mem, size_t size, AstSkyFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSkyFrame * Purpose: * Load a SkyFrame. * Type: * Protected function. * Synopsis: * #include "skyframe.h" * AstSkyFrame *astLoadSkyFrame( void *mem, size_t size, * AstSkyFrameVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SkyFrame loader. * Description: * This function is provided to load a new SkyFrame 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 * SkyFrame structure in this memory, using data read from the * input Channel. * Parameters: * mem * A pointer to the memory into which the SkyFrame is to be * loaded. This must be of sufficient size to accommodate the * SkyFrame data (sizeof(SkyFrame)) 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 SkyFrame (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 SkyFrame 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(AstSkyFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SkyFrame. If this is NULL, a pointer * to the (static) virtual function table for the SkyFrame 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 "SkyFrame" is used instead. * Returned Value: * A pointer to the new SkyFrame. * 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: */ AstSkyFrame *new; /* Pointer to the new SkyFrame */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char *sval; /* Pointer to string value */ const int *perm; /* Pointer to axis permutation array */ double dval; /* Floating point attribute value */ int axis; /* External axis index */ int invperm[ 2 ]; /* Inverse permutation array */ /* Initialise. */ new = NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* 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 SkyFrame. In this case the SkyFrame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSkyFrame ); vtab = &class_vtab; name = "SkyFrame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSkyFrameVtab( 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 SkyFrame. */ new = astLoadFrame( mem, size, (AstFrameVtab *) vtab, name, channel ); if ( astOK ) { /* Get a pointer to the SkyFrame's axis permutation array (using a method, to allow for any over-ride by a derived class). */ perm = astGetPerm( new ); /* Generate an inverse axis permutation array from the forward permutation values. This will be used to determine which axis should be enquired about (using possibly over-ridden methods) to obtain data to correspond with a particular internal value (i.e. instance variable) relating to an axis. This step is needed so that the effect of any axis permutation can be un-done before values are written out, as output values are written by this function in un-permuted order. */ for( axis = 0; axis < 2; axis++ ) invperm[ perm[ axis ] ] = axis; /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "SkyFrame" ); /* 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. */ /* The attributes defining the offset coordinate system must be loaded before the System attrivbute, since SetSystem uses them. */ /* AlignOffset */ /* ----------- */ new->alignoffset = astReadInt( channel, "aloff", -INT_MAX ); if ( TestAlignOffset( new, status ) ) SetAlignOffset( new, new->alignoffset, status ); /* SkyRefIs. */ /* --------- */ sval = astReadString( channel, "srefis", " " ); if( sval ){ new->skyrefis = AST__BAD_REF; if( astChrMatch( sval, POLE_STRING ) ) { new->skyrefis = AST__POLE_REF; } else if( astChrMatch( sval, ORIGIN_STRING ) ) { new->skyrefis = AST__ORIGIN_REF; } else if( astChrMatch( sval, IGNORED_STRING ) ) { new->skyrefis = AST__IGNORED_REF; } else if( !astChrMatch( sval, " " ) && astOK ){ astError( AST__INTER, "astRead(SkyFrame): Corrupt SkyFrame contains " "invalid SkyRefIs attribute value (%s).", status, sval ); } if( TestSkyRefIs( new, status ) ) SetSkyRefIs( new, new->skyrefis, status ); sval = astFree( sval ); } /* SkyRef. */ /* ------- */ new->skyref[ 0 ] = astReadDouble( channel, "sref1", AST__BAD ); axis = invperm[ 0 ]; if ( TestSkyRef( new, axis, status ) ) SetSkyRef( new, axis, new->skyref[ 0 ], status ); new->skyref[ 1 ] = astReadDouble( channel, "sref2", AST__BAD ); axis = invperm[ 1 ]; if ( TestSkyRef( new, axis, status ) ) SetSkyRef( new, axis, new->skyref[ 1 ], status ); /* SkyRefP. */ /* -------- */ new->skyrefp[ 0 ] = astReadDouble( channel, "srefp1", AST__BAD ); axis = invperm[ 0 ]; if ( TestSkyRefP( new, axis, status ) ) SetSkyRefP( new, axis, new->skyrefp[ 0 ], status ); new->skyrefp[ 1 ] = astReadDouble( channel, "srefp2", AST__BAD ); axis = invperm[ 1 ]; if ( TestSkyRefP( new, axis, status ) ) SetSkyRefP( new, axis, new->skyrefp[ 1 ], status ); /* System. */ /* ------- */ /* The System attribute is now part of the Frame class, but this code is retained to allow this version of AST to read SkyFrames dumped by previous versions. */ /* Check a value has not already been assigned to the Frames System attribute. */ if( !astTestSystem( new ) ){ /* Read the external representation as a string. */ sval = astReadString( channel, "system", NULL ); /* If a value was read, use the SetAttrib method to validate and store the new value in the correct place, then free the string. */ if ( sval ) { astSet( new, "System=%s", status, sval); sval = astFree( sval ); } } /* Epoch. */ /* ------ */ /* The Epoch attribute is now part of the Frame class, but this code is retained to allow this version of AST to read SkyFrames dumped by previous versions. */ /* Check a value has not already been assigned to the Frames Epoch attribute. */ if( !astTestEpoch( new ) ){ /* Get the value. */ dval = astReadDouble( channel, "epoch", AST__BAD ); /* If a value was read, use the SetAttrib method to validate and store the new value in the correct place. */ if( dval != AST__BAD ) { if( dval < 1984.0 ) { astSet( new, "Epoch=B%.*g", status, DBL_DIG, dval); } else { astSet( new, "Epoch=J%.*g", status, DBL_DIG, dval); } } } /* Projection. */ /* ----------- */ new->projection = astReadString( channel, "proj", NULL ); /* Equinox. */ /* -------- */ /* Interpret this as Besselian or Julian depending on its value. */ new->equinox = astReadDouble( channel, "eqnox", AST__BAD ); if ( TestEquinox( new, status ) ) { SetEquinox( new, ( new->equinox < 1984.0 ) ? palEpb2d( new->equinox ) : palEpj2d( new->equinox ), status ); } /* NegLon. */ /* ------- */ new->neglon = astReadInt( channel, "neglon", -INT_MAX ); if ( TestNegLon( new, status ) ) SetNegLon( new, new->neglon, status ); /* SkyTol. */ /* ------- */ new->skytol = astReadDouble( channel, "skytol", AST__BAD ); if ( TestSkyTol( new, status ) ) SetSkyTol( new, new->skytol, status ); /* Other values */ /* ------------ */ new->last = AST__BAD; new->eplast = AST__BAD; new->klast = AST__BAD; new->diurab = AST__BAD; /* If an error occurred, clean up by deleting the new SkyFrame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SkyFrame pointer. */ return new; } /* 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 astClearAsTime_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return; (**astMEMBER(this,SkyFrame,ClearAsTime))( this, axis, status ); } int astGetAsTime_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,SkyFrame,GetAsTime))( this, axis, status ); } void astSetAsTime_( AstSkyFrame *this, int axis, int value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,SkyFrame,SetAsTime))( this, axis, value, status ); } int astTestAsTime_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,SkyFrame,TestAsTime))( this, axis, status ); } int astGetIsLatAxis_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,SkyFrame,GetIsLatAxis))( this, axis, status ); } int astGetIsLonAxis_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,SkyFrame,GetIsLonAxis))( this, axis, status ); } int astGetLatAxis_( AstSkyFrame *this, int *status ) { if ( !astOK ) return 1; return (**astMEMBER(this,SkyFrame,GetLatAxis))( this, status ); } int astGetLonAxis_( AstSkyFrame *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,SkyFrame,GetLonAxis))( this, status ); } double astGetSkyRefP_( AstSkyFrame *this, int axis, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,SkyFrame,GetSkyRefP))( this, axis, status ); } AstMapping *astSkyOffsetMap_( AstSkyFrame *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,SkyFrame,SkyOffsetMap))( this, 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. */ AstSkyFrame *astSkyFrameId_( const char *, ... ); /* Special interface function implementations. */ /* ------------------------------------------- */ AstSkyFrame *astSkyFrameId_( const char *options, ... ) { /* *++ * Name: c astSkyFrame f AST_SKYFRAME * Purpose: * Create a SkyFrame. * Type: * Public function. * Synopsis: c #include "skyframe.h" c AstSkyFrame *astSkyFrame( const char *options, ... ) f RESULT = AST_SKYFRAME( OPTIONS, STATUS ) * Class Membership: * SkyFrame constructor. * Description: * This function creates a new SkyFrame and optionally initialises * its attributes. * * A SkyFrame is a specialised form of Frame which describes * celestial longitude/latitude coordinate systems. The particular * celestial coordinate system to be represented is specified by * setting the SkyFrame's System attribute (currently, the default * is ICRS) qualified, as necessary, by a mean Equinox value and/or * an Epoch. * * For each of the supported celestial coordinate systems, a SkyFrame * can apply an optional shift of origin to create a coordinate system * representing offsets within the celestial coordinate system from some * specified point. This offset coordinate system can also be rotated to * define new longitude and latitude axes. See attributes SkyRef, SkyRefIs * and SkyRefP * * All the coordinate values used by a SkyFrame are in * radians. These may be formatted in more conventional ways for c display by using astFormat. f display by using AST_FORMAT. * Parameters: 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 SkyFrame. 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 SkyFrame. 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 astSkyFrame() f AST_SKYFRAME = INTEGER * A pointer to the new SkyFrame. * Examples: c frame = astSkyFrame( "" ); c Creates a SkyFrame to describe the default ICRS celestial c coordinate system. c frame = astSkyFrame( "System = FK5, Equinox = J2005, Digits = 10" ); c Creates a SkyFrame to describe the FK5 celestial c coordinate system, with a mean Equinox of J2005.0. c Because especially accurate coordinates will be used, c additional precision (10 digits) has been requested. This will c be used when coordinate values are formatted for display. c frame = astSkyFrame( "System = FK4, Equinox = 1955-sep-2" ); c Creates a SkyFrame to describe the old FK4 celestial c coordinate system. A default Epoch value (B1950.0) is used, c but the mean Equinox value is given explicitly as "1955-sep-2". c frame = astSkyFrame( "System = GAPPT, Epoch = %s", date ); c Creates a SkyFrame to describe the Geocentric Apparent c celestial coordinate system. The Epoch value, which specifies c the date of observation, is obtained from a date/time string c supplied via the string pointer "date". f FRAME = AST_SKYFRAME( ' ', STATUS ) f Creates a SkyFrame to describe the default ICRS celestial f coordinate system. f FRAME = AST_SKYFRAME( 'System = FK5, Equinox = J2005, Digits = 10', STATUS ) f Creates a SkyFrame to describe the FK5 celestial f coordinate system, with a mean Equinox of J2005.0. f Because especially accurate coordinates will be used, f additional precision (10 digits) has been requested. This will f be used when coordinate values are formatted for display. f FRAME = AST_SKYFRAME( 'System = FK4, Equinox = 1955-SEP-2', STATUS ) f Creates a SkyFrame to describe the old FK4 celestial f coordinate system. A default Epoch value (B1950.0) is used, f but the mean Equinox value is given explicitly as "1955-SEP-2". f FRAME = AST_SKYFRAME( 'System = GAPPT, Epoch = ' // DATE, STATUS ) f Creates a SkyFrame to describe the Geocentric Apparent f celestial coordinate system. The Epoch value, which specifies f the date of observation, is obtained from a date/time string f contained in the character variable DATE. * Notes: * - Currently, the default celestial coordinate system is * ICRS. However, this default may change in future as new * astrometric standards evolve. The intention is to track the most * modern appropriate standard. For this reason, you should use the * default only if this is what you intend (and can tolerate any * associated slight change in behaviour with future versions of * this function). If you intend to use the ICRS system * indefinitely, then you should specify it explicitly using an c "options" value of "System=ICRS". f OPTIONS value of "System=ICRS". * - Whichever celestial coordinate system is represented, it will * have two axes. The first of these will be the longitude axis * and the second will be the latitude axis. This order can be c changed using astPermAxes if required. f changed using AST_PERMAXES if required. * - When conversion between two SkyFrames is requested (as when c supplying SkyFrames to astConvert), f supplying SkyFrames AST_CONVERT), * account will be taken of the nature of the celestial coordinate * systems they represent, together with any qualifying mean Equinox or * Epoch values, etc. The AlignSystem attribute will also be taken into * account. The results will therefore fully reflect the * relationship between positions on the sky measured in the two * systems. * - 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 astSkyFrame constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astSkyFrame_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astSkyFrame_ directly, so it must be a * re-implementation of it in all respects, except for the final * conversion of the result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyFrame *new; /* Pointer to new SkyFrame */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the SkyFrame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSkyFrame( NULL, sizeof( AstSkyFrame ), !class_init, &class_vtab, "SkyFrame" ); /* 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 SkyFrame'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 SkyFrame. */ return astMakeId( new ); } ast-8.3.0/finterval.c0000664000175000017500000000652413004147321011374 00000000000000/* *+ * Name: * finterval.c * Purpose: * Define a FORTRAN 77 interface to the AST Interval class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Interval class. * Routines Defined: * AST_ISAINTERVAL * AST_INTERVAL * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 31-AUG-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "interval.h" /* C interface to the Interval class */ F77_LOGICAL_FUNCTION(ast_isainterval)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAINTERVAL", NULL, 0 ); astWatchSTATUS( RESULT = astIsAInterval( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_interval)( INTEGER(FRAME), DOUBLE_ARRAY(LBND), DOUBLE_ARRAY(UBND), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_DOUBLE_ARRAY(LBND) GENPTR_DOUBLE_ARRAY(UBND) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_INTERVAL", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astInterval( astI2P( *FRAME ), LBND, UBND, astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/stc.h0000664000175000017500000001657113004147321010203 00000000000000#if !defined( STC_INCLUDED ) /* Include this file only once */ #define STC_INCLUDED /* *+ * Name: * stc.h * Type: * C include file. * Purpose: * Define the interface to the Stc class. * Invocation: * #include "stc.h" * Description: * This include file defines the interface to the Stc class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The Stc class is an implementation of the IVOA STC class which forms * part of the IVOA Space-Time Coordinate Metadata system. See: * * http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The Stc class inherits from the Region class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 23-NOV-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "region.h" /* Coordinate regions (parent class) */ #include "keymap.h" /* Lists of value/key pairs */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #define AST__STCNAME "Name" #define AST__STCVALUE "Value" #define AST__STCERROR "Error" #define AST__STCRES "Resolution" #define AST__STCSIZE "Size" #define AST__STCPIXSZ "PixSize" /* Type Definitions. */ /* ================= */ /* Stc structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStc { /* Attributes inherited from the parent class. */ AstRegion parent_region; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstRegion *region; /* Encapsulated Region */ AstKeyMap **coord; /* STC AstroCoords info */ int ncoord; /* Number of AstroCoords in "coords" */ } AstStc; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstRegionVtab region_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ const char *(* GetRegionClass)( AstStc *, int * ); AstRegion *(* GetStcRegion)( AstStc *, int * ); AstKeyMap *(* GetStcCoord)( AstStc *, int, int * ); int (* GetStcNCoord)( AstStc *, int * ); } AstStcVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstStcGlobals { AstStcVtab Class_Vtab; int Class_Init; } AstStcGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitStcGlobals_( AstStcGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Stc) /* Check class membership */ astPROTO_ISA(Stc) /* Test class membership */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStc *astInitStc_( void *, size_t, int, AstStcVtab *, const char *, AstRegion *, int, AstKeyMap **, int * ); /* Vtab initialiser. */ void astInitStcVtab_( AstStcVtab *, const char *, int * ); /* Loader. */ AstStc *astLoadStc_( void *, size_t, AstStcVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ AstRegion *astGetStcRegion_( AstStc *, int * ); AstKeyMap *astGetStcCoord_( AstStc *, int, int * ); int astGetStcNCoord_( AstStc *, int * ); # if defined(astCLASS) /* Protected */ const char *astGetRegionClass_( AstStc *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStc(this) astINVOKE_CHECK(Stc,this,0) #define astVerifyStc(this) astINVOKE_CHECK(Stc,this,1) /* Test class membership. */ #define astIsAStc(this) astINVOKE_ISA(Stc,this) #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStc(mem,size,init,vtab,name,reg,ncoords,coords) \ astINVOKE(O,astInitStc_(mem,size,init,vtab,name,reg,ncoords,coords,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcVtab(vtab,name) astINVOKE(V,astInitStcVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStc(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStc_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckStc to validate Stc pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astGetStcRegion(this) astINVOKE(O,astGetStcRegion_(astCheckStc(this),STATUS_PTR)) #define astGetStcCoord(this,icoord) astINVOKE(O,astGetStcCoord_(astCheckStc(this),icoord,STATUS_PTR)) #define astGetStcNCoord(this) astINVOKE(V,astGetStcNCoord_(astCheckStc(this),STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astGetRegionClass(this) astINVOKE(V,astGetRegionClass_(astCheckStc(this),STATUS_PTR)) #endif #endif ast-8.3.0/fwinmap.c0000664000175000017500000000657613004147321011052 00000000000000/* *+ * Name: * fwinmap.c * Purpose: * Define a FORTRAN 77 interface to the AST WinMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the WinMap class. * Routines Defined: * AST_ISAWINMAP * AST_WINMAP * 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 * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 23-OCT-1996 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "winmap.h" /* C interface to the WinMap class */ F77_LOGICAL_FUNCTION(ast_isawinmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAWINMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAWinMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_winmap)( INTEGER(NAXES), DOUBLE(C1_IN), DOUBLE(C2_IN), DOUBLE(C1_OUT), DOUBLE(C2_OUT), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NAXES) GENPTR_DOUBLE(C1_IN) GENPTR_DOUBLE(C2_IN) GENPTR_DOUBLE(C1_OUT) GENPTR_DOUBLE(C2_OUT) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_WINMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astWinMap( *NAXES, C1_IN, C2_IN, C1_OUT, C2_OUT, "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/ast_cpp.in0000664000175000017500000000062513004147320011212 00000000000000 # Replacement for the C pre-processor command "cpp" which is not # always available. This uses the compiler command "cc" to do the same # thing. Also, this reads from standard input (which "cc" won't do). # # The name of the CPP processor is substituted in by the ./configure script, # based on the result of the AC_PROG_CPP test. cat >/tmp/ast_cpp_$$.c @CPP@ /tmp/ast_cpp_$$.c rm -f /tmp/ast_cpp_$$.c ast-8.3.0/ffluxframe.c0000664000175000017500000000626413004147321011542 00000000000000/* *+ * Name: * ffluxframe.c * Purpose: * Define a FORTRAN 77 interface to the AST FluxFrame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the FluxFrame class. * Routines Defined: * AST_ISAFLUXFRAME * AST_FLUXFRAME * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 1-DEC-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "fluxframe.h" /* C interface to the FluxFrame class */ F77_LOGICAL_FUNCTION(ast_isafluxframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAFLUXFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsAFluxFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_fluxframe)( DOUBLE(SPECVAL), INTEGER(SPECFRM), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_DOUBLE(SPECVAL) GENPTR_INTEGER(SPECFRM) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_FLUXFRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astFluxFrame( *SPECVAL, astI2P( *SPECFRM ), "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/stccatalogentrylocation.h0000664000175000017500000001671113004147321014345 00000000000000#if !defined( STCCATALOGENTRYLOCATION_INCLUDED ) /* Include this file only once */ #define STCCATALOGENTRYLOCATION_INCLUDED /* *+ * Name: * stccatalogentrylocation.h * Type: * C include file. * Purpose: * Define the interface to the StcCatalogEntryLocation class. * Invocation: * #include "stccatalogentrylocation.h" * Description: * This include file defines the interface to the StcCatalogEntryLocation class * and provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The StcCatalogEntryLocation class is a sub-class of Stc used to describe * the coverage of the datasets contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcCatalogEntryLocation class inherits from the Stc class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-NOV-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "stc.h" /* Coordinate stcs (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* StcCatalogEntryLocation structure. */ /* ----------------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStcCatalogEntryLocation { /* Attributes inherited from the parent class. */ AstStc stc; /* Parent class structure */ } AstStcCatalogEntryLocation; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcCatalogEntryLocationVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstStcVtab stc_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstStcCatalogEntryLocationVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstStcCatalogEntryLocationGlobals { AstStcCatalogEntryLocationVtab Class_Vtab; int Class_Init; } AstStcCatalogEntryLocationGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitStcCatalogEntryLocationGlobals_( AstStcCatalogEntryLocationGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(StcCatalogEntryLocation) /* Check class membership */ astPROTO_ISA(StcCatalogEntryLocation) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstStcCatalogEntryLocation *astStcCatalogEntryLocation_( void *, int, AstKeyMap **, const char *, int *, ...); #else AstStcCatalogEntryLocation *astStcCatalogEntryLocationId_( void *, int, AstKeyMap **, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStcCatalogEntryLocation *astInitStcCatalogEntryLocation_( void *, size_t, int, AstStcCatalogEntryLocationVtab *, const char *, AstRegion *, int, AstKeyMap **, int * ); /* Vtab initialiser. */ void astInitStcCatalogEntryLocationVtab_( AstStcCatalogEntryLocationVtab *, const char *, int * ); /* Loader. */ AstStcCatalogEntryLocation *astLoadStcCatalogEntryLocation_( void *, size_t, AstStcCatalogEntryLocationVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStcCatalogEntryLocation(this) astINVOKE_CHECK(StcCatalogEntryLocation,this,0) #define astVerifyStcCatalogEntryLocation(this) astINVOKE_CHECK(StcCatalogEntryLocation,this,1) /* Test class membership. */ #define astIsAStcCatalogEntryLocation(this) astINVOKE_ISA(StcCatalogEntryLocation,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astStcCatalogEntryLocation astINVOKE(F,astStcCatalogEntryLocation_) #else #define astStcCatalogEntryLocation astINVOKE(F,astStcCatalogEntryLocationId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStcCatalogEntryLocation(mem,size,init,vtab,name,region,ncoords,coords) \ astINVOKE(O,astInitStcCatalogEntryLocation_(mem,size,init,vtab,name,region,ncoords,coords,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcCatalogEntryLocationVtab(vtab,name) astINVOKE(V,astInitStcCatalogEntryLocationVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStcCatalogEntryLocation(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStcCatalogEntryLocation_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckStcCatalogEntryLocation to validate StcCatalogEntryLocation pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/stcsearchlocation.h0000664000175000017500000001614213004147321013114 00000000000000#if !defined( STCSEARCHLOCATION_INCLUDED ) /* Include this file only once */ #define STCSEARCHLOCATION_INCLUDED /* *+ * Name: * stcsearchlocation.h * Type: * C include file. * Purpose: * Define the interface to the StcSearchLocation class. * Invocation: * #include "stcsearchlocation.h" * Description: * This include file defines the interface to the StcSearchLocation class * and provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The StcSearchLocation class is a sub-class of Stc used to describe * the coverage of a VO query. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcSearchLocation class inherits from the Stc class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-NOV-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "stc.h" /* Coordinate stcs (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* StcSearchLocation structure. */ /* ----------------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStcSearchLocation { /* Attributes inherited from the parent class. */ AstStc stc; /* Parent class structure */ } AstStcSearchLocation; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcSearchLocationVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstStcVtab stc_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ } AstStcSearchLocationVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstStcSearchLocationGlobals { AstStcSearchLocationVtab Class_Vtab; int Class_Init; } AstStcSearchLocationGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitStcSearchLocationGlobals_( AstStcSearchLocationGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(StcSearchLocation) /* Check class membership */ astPROTO_ISA(StcSearchLocation) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstStcSearchLocation *astStcSearchLocation_( void *, int, AstKeyMap **, const char *, int *, ...); #else AstStcSearchLocation *astStcSearchLocationId_( void *, int, AstKeyMap **, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStcSearchLocation *astInitStcSearchLocation_( void *, size_t, int, AstStcSearchLocationVtab *, const char *, AstRegion *, int, AstKeyMap **, int * ); /* Vtab initialiser. */ void astInitStcSearchLocationVtab_( AstStcSearchLocationVtab *, const char *, int * ); /* Loader. */ AstStcSearchLocation *astLoadStcSearchLocation_( void *, size_t, AstStcSearchLocationVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStcSearchLocation(this) astINVOKE_CHECK(StcSearchLocation,this,0) #define astVerifyStcSearchLocation(this) astINVOKE_CHECK(StcSearchLocation,this,1) /* Test class membership. */ #define astIsAStcSearchLocation(this) astINVOKE_ISA(StcSearchLocation,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astStcSearchLocation astINVOKE(F,astStcSearchLocation_) #else #define astStcSearchLocation astINVOKE(F,astStcSearchLocationId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStcSearchLocation(mem,size,init,vtab,name,region,ncoords,coords) \ astINVOKE(O,astInitStcSearchLocation_(mem,size,init,vtab,name,region,ncoords,coords,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcSearchLocationVtab(vtab,name) astINVOKE(V,astInitStcSearchLocationVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStcSearchLocation(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStcSearchLocation_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckStcSearchLocation to validate StcSearchLocation pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/table.h0000664000175000017500000002620013004147321010467 00000000000000#if !defined( TABLE_INCLUDED ) /* Include this file only once */ #define TABLE_INCLUDED /* *+ * Name: * table.h * Type: * C include file. * Purpose: * Define the interface to the Table class. * Invocation: * #include "table.h" * Description: * This include file defines the interface to the Table class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * Inheritance: * The Table class inherits from the KeyMap class. * Copyright: * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-NOV-2010 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "keymap.h" /* Parent class */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* Maximum length of a column name */ #define AST__MXCOLNAMLEN 100 /* Maximum length of a key for a column cell */ #define AST__MXCOLKEYLEN ( AST__MXCOLNAMLEN + 23 ) #endif /* Type Definitions. */ /* ================= */ /* Table structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstTable { /* Attributes inherited from the parent class. */ AstKeyMap keymap; /* Parent class structure */ /* Attributes specific to objects in this class. */ int nrow; /* Mo. of rows in table */ AstKeyMap *columns; /* KeyMap holding column definitions */ AstKeyMap *parameters; /* KeyMap holding parameter definitions */ } AstTable; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstTableVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstKeyMapVtab keymap_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ AstKeyMap *(* ColumnProps)( AstTable *, int * ); AstKeyMap *(* ParameterProps)( AstTable *, int * ); const char *(* ColumnName)( AstTable *, int, int * ); const char *(* ParameterName)( AstTable *, int, int * ); const char *(* GetColumnUnit)( AstTable *, const char *, int * ); int (* GetColumnLenC)( AstTable *, const char *, int * ); int (* GetColumnLength)( AstTable *, const char *, int * ); int (* GetColumnNdim)( AstTable *, const char *, int * ); int (* GetColumnType)( AstTable *, const char *, int * ); int (* GetNcolumn)( AstTable *, int * ); int (* GetNparameter)( AstTable *, int * ); int (* GetNrow)( AstTable *, int * ); int (* HasColumn)( AstTable *, const char *, int * ); int (* HasParameter)( AstTable *, const char *, int * ); void (* AddColumn)( AstTable *, const char *, int, int, int *, const char *, int * ); void (* AddParameter)( AstTable *, const char *, int * ); void (* ColumnShape)( AstTable *, const char *, int, int *, int *, int * ); void (* PurgeRows)( AstTable *, int * ); void (* RemoveColumn)( AstTable *, const char *, int * ); void (* RemoveParameter)( AstTable *, const char *, int * ); void (* RemoveRow)( AstTable *, int, int * ); void (* SetNrow)( AstTable *, int, int * ); } AstTableVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstTableGlobals { AstTableVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstTableGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitTableGlobals_( AstTableGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Table) /* Check class membership */ astPROTO_ISA(Table) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstTable *astTable_( const char *, int *, ...); #else AstTable *astTableId_( const char *, ... )__attribute__((format(printf,1,2))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstTable *astInitTable_( void *, size_t, int, AstTableVtab *, const char *, int * ); /* Vtab initialiser. */ void astInitTableVtab_( AstTableVtab *, const char *, int * ); /* Loader. */ AstTable *astLoadTable_( void *, size_t, AstTableVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ void astAddColumn_( AstTable *, const char *, int, int, int *, const char *, int * ); void astAddParameter_( AstTable *, const char *, int * ); void astRemoveColumn_( AstTable *, const char *, int * ); void astRemoveParameter_( AstTable *, const char *, int * ); void astRemoveRow_( AstTable *, int, int * ); void astPurgeRows_( AstTable *, int * ); const char *astColumnName_( AstTable *, int, int * ); const char *astParameterName_( AstTable *, int, int * ); void astColumnShape_( AstTable *, const char *, int, int *, int *, int * ); int astHasColumn_( AstTable *, const char *, int * ); int astHasParameter_( AstTable *, const char *, int * ); #if defined(astCLASS) /* Protected */ AstKeyMap *astColumnProps_( AstTable *, int * ); AstKeyMap *astParameterProps_( AstTable *, int * ); const char *astGetColumnUnit_( AstTable *, const char *, int * ); int astGetColumnLenC_( AstTable *, const char *, int * ); int astGetColumnLength_( AstTable *, const char *, int * ); int astGetColumnNdim_( AstTable *, const char *, int * ); int astGetColumnType_( AstTable *, const char *, int * ); int astGetNcolumn_( AstTable *, int * ); int astGetNparameter_( AstTable *, int * ); int astGetNrow_( AstTable *, int * ); void astSetNrow_( AstTable *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckTable(this) astINVOKE_CHECK(Table,this,0) #define astVerifyTable(this) astINVOKE_CHECK(Table,this,1) /* Test class membership. */ #define astIsATable(this) astINVOKE_ISA(Table,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astTable astINVOKE(F,astTable_) #else #define astTable astINVOKE(F,astTableId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitTable(mem,size,init,vtab,name) \ astINVOKE(O,astInitTable_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitTableVtab(vtab,name) astINVOKE(V,astInitTableVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadTable(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadTable_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckTable to validate Table pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #define astAddColumn(this,name,type,ndim,dims,unit) astINVOKE(V,astAddColumn_(astCheckTable(this),name,type,ndim,dims,unit, STATUS_PTR)) #define astAddParameter(this,name) astINVOKE(V,astAddParameter_(astCheckTable(this),name,STATUS_PTR)) #define astRemoveColumn(this,name) astINVOKE(V,astRemoveColumn_(astCheckTable(this),name,STATUS_PTR)) #define astRemoveParameter(this,name) astINVOKE(V,astRemoveParameter_(astCheckTable(this),name,STATUS_PTR)) #define astRemoveRow(this,index) astINVOKE(V,astRemoveRow_(astCheckTable(this),index,STATUS_PTR)) #define astPurgeRows(this) astINVOKE(V,astPurgeRows_(astCheckTable(this),STATUS_PTR)) #define astColumnName(this,index) astINVOKE(V,astColumnName_(astCheckTable(this),index,STATUS_PTR)) #define astParameterName(this,index) astINVOKE(V,astParameterName_(astCheckTable(this),index,STATUS_PTR)) #define astColumnShape(this,column,mxdim,ndim,dims) astINVOKE(V,astColumnShape_(astCheckTable(this),column,mxdim,ndim,dims,STATUS_PTR)) #define astHasColumn(this,column) astINVOKE(V,astHasColumn_(astCheckTable(this),column,STATUS_PTR)) #define astHasParameter(this,param) astINVOKE(V,astHasParameter_(astCheckTable(this),param,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #define astColumnProps(this) \ astINVOKE(O,astColumnProps_(astCheckTable(this),STATUS_PTR)) #define astParameterProps(this) \ astINVOKE(O,astParameterProps_(astCheckTable(this),STATUS_PTR)) #define astGetNcolumn(this) \ astINVOKE(V,astGetNcolumn_(astCheckTable(this),STATUS_PTR)) #define astGetNparameter(this) \ astINVOKE(V,astGetNparameter_(astCheckTable(this),STATUS_PTR)) #define astGetNrow(this) \ astINVOKE(V,astGetNrow_(astCheckTable(this),STATUS_PTR)) #define astSetNrow(this,value) \ astINVOKE(V,astSetNrow_(astCheckTable(this),value,STATUS_PTR)) #define astGetColumnLenC(this,column) \ astINVOKE(V,astGetColumnLenC_(astCheckTable(this),column,STATUS_PTR)) #define astGetColumnLength(this,column) \ astINVOKE(V,astGetColumnLength_(astCheckTable(this),column,STATUS_PTR)) #define astGetColumnNdim(this,column) \ astINVOKE(V,astGetColumnNdim_(astCheckTable(this),column,STATUS_PTR)) #define astGetColumnType(this,column) \ astINVOKE(V,astGetColumnType_(astCheckTable(this),column,STATUS_PTR)) #define astGetColumnUnit(this,column) \ astINVOKE(V,astGetColumnUnit_(astCheckTable(this),column,STATUS_PTR)) #endif #endif ast-8.3.0/frame.c0000664000175000017500000215266513004147321010506 00000000000000/* *class++ * Name: * Frame * Purpose: * Coordinate system description. * Constructor Function: c astFrame f AST_FRAME * Description: * This class is used to represent coordinate systems. It does this * in rather the same way that a frame around a graph describes the * coordinate space in which data are plotted. Consequently, a * Frame has a Title (string) attribute, which describes the * coordinate space, and contains axes which in turn hold * information such as Label and Units strings which are used for * labelling (e.g.) graphical output. In general, however, the * number of axes is not restricted to two. * * Functions are available for converting Frame coordinate values * into a form suitable for display, and also for calculating * distances and offsets between positions within the Frame. * * Frames may also contain knowledge of how to transform to and * from related coordinate systems. * Inheritance: * The Frame class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * Frame also has the following attributes (if the Frame has only one * axis, the axis specifier can be omited from the following attribute * names): * * - AlignSystem: Coordinate system used to align Frames * - Bottom(axis): Lowest axis value to display * - Digits/Digits(axis): Number of digits of precision * - Direction(axis): Display axis in conventional direction? * - Domain: Coordinate system domain * - Dut1: Difference between the UT1 and UTC timescale * - Epoch: Epoch of observation * - Format(axis): Format specification for axis values * - InternalUnit(axis): Physical units for unformated axis values * - Label(axis): Axis label * - MatchEnd: Match trailing axes? * - MaxAxes: Maximum number of Frame axes to match * - MinAxes: Minimum number of Frame axes to match * - Naxes: Number of Frame axes * - NormUnit(axis): Normalised physical units for formatted axis values * - ObsAlt: Geodetic altitude of observer * - ObsLat: Geodetic latitude of observer * - ObsLon: Geodetic longitude of observer * - Permute: Permute axis order? * - PreserveAxes: Preserve axes? * - Symbol(axis): Axis symbol * - System: Coordinate system used to describe the domain * - Title: Frame title * - Top(axis): Highest axis value to display * - Unit(axis): Physical units for formatted axis values * Functions: c In addition to those functions applicable to all Mappings, the c following functions may also be applied to all Frames: f In addition to those routines applicable to all Mappings, the f following routines may also be applied to all Frames: * c - astAngle: Calculate the angle subtended by two points at a third point c - astAxAngle: Find the angle from an axis, to a line through two points c - astAxDistance: Calculate the distance between two axis values c - astAxNorm: Normalises an array of axis values c - astAxOffset: Calculate an offset along an axis c - astConvert: Determine how to convert between two coordinate systems c - astDistance: Calculate the distance between two points in a Frame c - astFindFrame: Find a coordinate system with specified characteristics c - astFormat: Format a coordinate value for a Frame axis c - astGetActiveUnit: Determines how the Unit attribute will be used c - astIntersect: Find the intersection between two geodesic curves c - astMatchAxes: Find any corresponding axes in two Frames c - astNorm: Normalise a set of Frame coordinates c - astOffset: Calculate an offset along a geodesic curve c - astOffset2: Calculate an offset along a geodesic curve in a 2D Frame c - astPermAxes: Permute the order of a Frame's axes c - astPickAxes: Create a new Frame by picking axes from an existing one c - astResolve: Resolve a vector into two orthogonal components c - astSetActiveUnit: Specify how the Unit attribute should be used c - astUnformat: Read a formatted coordinate value for a Frame axis f - AST_ANGLE: Find the angle subtended by two points at a third point f - AST_AXANGLE: Find the angle from an axis, to a line through two points f - AST_AXDISTANCE: Calculate the distance between two axis values f - AST_AXNORM: Normalises an array of axis values f - AST_AXOFFSET: Calculate an offset along an axis f - AST_CONVERT: Determine how to convert between two coordinate systems f - AST_DISTANCE: Calculate the distance between two points in a Frame f - AST_FINDFRAME: Find a coordinate system with specified characteristics f - AST_FORMAT: Format a coordinate value for a Frame axis f - AST_GETACTIVEUNIT: Determines how the Unit attribute will be used f - AST_INTERSECT: Find the intersection between two geodesic curves f - AST_MATCHAXES: Find any corresponding axes in two Frames f - AST_NORM: Normalise a set of Frame coordinates f - AST_OFFSET: Calculate an offset along a geodesic curve f - AST_OFFSET2: Calculate an offset along a geodesic curve in a 2D Frame f - AST_PERMAXES: Permute the order of a Frame's axes f - AST_PICKAXES: Create a new Frame by picking axes from an existing one f - AST_RESOLVE: Resolve a vector into two orthogonal components f - AST_SETACTIVEUNIT: Specify how the Unit attribute should be used f - AST_UNFORMAT: Read a formatted coordinate value for a Frame axis * Notes: * - When used as a Mapping, a Frame implements a unit (null) * transformation in both the forward and inverse directions * (equivalent to a UnitMap). The Nin and Nout attribute values are * both equal to the number of Frame axes. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: B.S. Berry (Starlink) * History: * 1-MAR-1996 (RFWS): * Original version. * 4-JUN-1996 (RFWS): * Added the CleanDomain function to fold all Domain strings to * upper case and remove white space. * 12-JUL-1996 (RFWS): * Over-ride the astReportPoints method to provide * Frame-specific formatting. * 11-SEP-1996 (RFWS): * Added astGap (written by DSB). * 10-JUN-1997 (RFWS): * Re-implemented astConvert and astFindFrame. * 1-SEP-1997 (RFWS): * Added missing return statement in astAbbrev_. * 14-NOV-1997 (RFWS): * Fixed wrong amount of memory allocated in ValidateAxisSelection. * 20-NOV-1997 (RFWS): * Updated astConvert prologue. * 22-DEC-1997 (RFWS): * Updated astConvert prologue again. * 15-FEB-1998 (RFWS): * Added astUnformat. * 2-MAR-1999 (RFWS); * Fixed missing STATUS arguments in examples for AST_FINDFRAME * prologue. * 18-JUL-1999 (RFWS): * Fixed memory leak in ConvertX. * 21-JUN-2001 (DSB): * Added methods astAngle and astOffset2. * 29-AUG-2001 (DSB): * Added methods astAxDistance and astAxOffset. * 4-SEP-2001 (DSB): * Added method astResolve. * 9-SEP-2001 (DSB): * Added method astBear. * 21-SEP-2001 (DSB): * Replaced astBear with astAxAngle. * 10-OCT-2002 (DSB): * Added Top and Bottom. * 15-NOV-2002 (DSB): * Moved the System and Epoch attributes from the SkyFrame class to * this class. Added virtual method astValidateSystem, astSystemString, * astSystemCode. Added attribute AlignSystem. * 17-DEC-2002 (DSB): * Added the GetActiveUnit, TestActiveUnit and SetActiveUnit functions. * 8-JAN-2003 (DSB): * Changed private InitVtab method to protected astInitFrameVtab * method. * 15-SEP-2003 (DSB): * Allow Frame attribute names to include an axis specifier within * GetAttrib, SetAttrib, TestAttrib and ClearAttrib (eg "Domain(1)" * is now accepted as equivalent to "Domain"). * 24-JAN-2004 (DSB): * o Added astFields. * o Added argument "fmt" to Abbrev. * 24-MAR-2004 (DSB): * Add protected function astIsUnitFrame. * 7-SEP-2004 (DSB): * Modified SetUnit to exclude any trailing spaces * 8-SEP-2004 (DSB): * - Added astResolvePoints. * - Override astEqual. * 29-NOV-2004 (DSB): * - Set/Get/Test/ClearAttrib: Allow axis specifier to be omitted from * axis attribute names if the Frame only has one axis. * 2-FEB-2005 (DSB): * - Avoid using astStore to allocate more storage than is supplied * in the "data" pointer. This can cause access violations since * astStore will then read beyond the end of the "data" area. * 17-FEB-2005 (DSB): * - Change use of ActiveUnit flag so that both target and template * Frames must have active units in order for the Mapping to take * account of differences in units. Previously, the test was based * on the template Frame alone. * 23-MAR-2005 (DSB): * - GetActiveUnit: Always return zero if the Frame contains any * SkyAxes. * 5-APR-2005 (DSB): * Correct error checking in Clear/Get/Set/TestAttrib. * 12-MAY-2005 (DSB): * Added astNormBox method. * 16-JUN-2005 (DSB): * Added documentation for the TimeFrame class. * 12-AUG-2005 (DSB): * Added ObsLat and ObsLon attributes. * 1-MAR-2006 (DSB): * Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. * 15-MAY-2006 (DSB): * Remove unused global variable parent_equal. * 26-JUN-2006 (DSB): * Document the use of the Direction attribute by the Plot class. * 30-JUN-2006 (DSB): * Allow astAbbrev to have a null "str1" value. * 16-AUG-2006 (DSB): * Correct "Class Applicability" to "Applicability". * 5-OCT-2006 (DSB): * Increase the number of digits used when formating a ObsLon or * ObsLat value in GetAttrib. * 14-OCT-2006 (DSB): * - Add Dut1 attribute * 26-JAN-2007 (DSB): * Fix bug in NewUnit that causes segvio when changing axis symbols * to accomodate changes in units. * 17-MAY-2007 (DSB): * Added read-only attribute NormUnit. * 21-MAY-2007 (DSB): * Use rather than ignore the value returned by astTestAxisDigits in * TestAttrib. * 25-JUN-2007 (DSB): * Documentation typos. * 26-NOV-2007 (DSB): * In Clear/Get/Set/TestAttrib, include any appropriate axis index in * the attribute name when attempting to get the attribute value from * the primary frame * 17-NOV-2008 (DSB): * Correct parent class in invocation of astMAKE_ISA. * 14-JAN-2009 (DSB): * Added astIntersect. * 18-MAR-2009 (DSB): * Fixed bug in LineCrossing. * 18-JUN-2000 (DSB): * Added ObsAlt attribute. * 28-SEP-2009 (DSB): * Added astMatchAxes method. * 22-MAR-2011 (DSB): * Add astFrameGrid method. * 29-APR-2011 (DSB): * Prevent astFindFrame from matching a subclass template against a * superclass target. * 11-APR-2012 (DSB): * Change astValidateAxis so that it can permute in either direction. * 29-APR-2013 (DSB): * Added protected methods astSetFrameVariants and astGetFrameVariants. * 1-MAY-2013 (DSB): * Override the astDoNotSimplify method to indicate that Frames should * always be simplified. This is mainly because the STC class uses the * Ident attribute with Frames, and preventing such frames from * simplifying (which is what the parent astDoNotSimplify method does) * causes the STC tester in the ast_tester directory to fail. * 10-FEB-2015 (DSB): * When checking attribute settings for attribute names that end with * an axis index, stop looking for the axis index when the first equals * sign is encountered. * 17-APR-2015 (DSB): * Added astCentre. * 27-APR-2015 (DSB): * Added read-only attribute InternalUnit. * 26-OCT-2016 (DSB): * Added method astAxNorm. *class-- */ /* Module Macros. */ /* ============== */ /* Set the name of the class we are implementing. This indicates to the header files that define class interfaces that they should make "protected" symbols available. */ #define astCLASS Frame /* Define numerical constants for use in this module. */ #define LABEL_BUFF_LEN 100 /* Max length of default axis Label string */ #define SYMBOL_BUFF_LEN 50 /* Max length of default axis Symbol string */ #define TITLE_BUFF_LEN 100 /* Max length of default title string */ #define GETATTRIB_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ #define ASTFMTDECIMALYR_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ #define ASTFORMATID_MAX_STRINGS 50 /* Number of string values buffer by astFormatID*/ /* Define the first and last acceptable System values. */ #define FIRST_SYSTEM AST__CART #define LAST_SYSTEM AST__CART /* Define macros to implement methods for accessing axis attributes. */ /* * Name: * MAKE_CLEAR * Purpose: * Implement a method to clear an attribute value for a Frame axis. * Type: * Private macro. * Synopsis: * #include "frame.h" * MAKE_CLEAR(attribute) * Class Membership: * Defined by the Frame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( AstFrame *this, int axis ) * * and an external interface function of the form: * * void astClear_( AstFrame *this, int axis ) * * which implement a method for clearing an attribute value for a specified * axis of a Frame. * Parameters: * attribute * The name of the attribute to be cleared, as it appears in the * function name (e.g. Label in "astClearLabel"). * Notes: * - This macro assumes the existence of a method of the form: * * void astClearAxis( AstAxis *this ) * * which clears the required attribute for an Axis object. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_CLEAR(attribute) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( AstFrame *this, int axis, int *status ) { \ AstAxis *ax; /* Pointer to Axis object */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index and obtain a pointer to the required Axis. */ \ (void) astValidateAxis( this, axis, 1, "astClear" #attribute ); \ ax = astGetAxis( this, axis ); \ \ /* Clear the Axis attribute. */ \ astClearAxis##attribute( ax ); \ \ /* Annul the Axis pointer. */ \ ax = astAnnul( ax ); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( AstFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Frame,Clear##attribute))( this, axis, status ); \ } /* * Name: * MAKE_GET * Purpose: * Implement a method to get an attribute value for a Frame axis. * Type: * Private macro. * Synopsis: # #include "frame.h" * MAKE_GET(attribute,type,bad_value,default,assign_default) * Class Membership: * Defined by the Frame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( AstFrame *this, int axis ) * * and an external interface function of the form: * * Type astGet_( AstFrame *this, int axis ) * * which implement a method for getting an attribute value for a specified * axis of a Frame. * Parameters: * attribute * The name of the attribute whose value is to be obtained, as * it appears in the function name (e.g. Label in * "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the global error status is set, or if * the function fails. * default * A boolean (int) constant that indicates whether a new default value * should be returned by the method if the requested attribute has not * been set for the axis. If this value is zero, the axis default will * be used instead. * assign_default * An expression that evaluates to the new default value to be assigned. * This value is ignored if "default" is zero, but a valid (e.g. * constant) value should nevertheless be supplied. * Notes: * - This macro assumes the existence of a method of the form: * * astGetAxis( AstAxis *this ) * * which gets the required attribute for an Axis object. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_GET(attribute,type,bad_value,default,assign_default) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attribute( AstFrame *this, int axis, int *status ) { \ AstAxis *ax; /* Pointer to Axis object */ \ int digits_set; /* Axis Digits attribute set? */ \ int old_axis; /* Original (un-permuted) axis index */ \ type result; /* Result to be returned */ \ \ /* Initialise. */ \ result = (bad_value); \ \ /* Check the global error status. */ \ if ( !astOK ) return result; \ \ /* Validate and permute the axis index and obtain a pointer to the required \ Axis. */ \ old_axis = axis; \ axis = astValidateAxis( this, axis, 1, "astGet" #attribute ); \ ax = astGetAxis( this, old_axis ); \ \ /* Since the Axis is "managed" by the enclosing Frame, we next test if any \ Axis attributes which may affect the result are undefined (i.e. have not \ been explicitly set). If so, we over-ride them, giving them temporary \ values dictated by the Frame. Only the Digits attribute is relevant \ here. */ \ digits_set = astTestAxisDigits( ax ); \ if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); \ \ /* If the default value is to be over-ridden, test if the Axis attribute has \ been set. Then, if required, obtain the attribute value from the Axis. */ \ if ( !(default) || astTestAxis##attribute( ax ) ) { \ result = astGetAxis##attribute( ax ); \ \ /* If required, assign the new default value. */ \ } else { \ result = (assign_default); \ } \ \ /* Clear Axis attributes which were temporarily over-ridden above and annul \ the Axis pointer. */ \ if ( !digits_set ) astClearAxisDigits( ax ); \ ax = astAnnul( ax ); \ \ /* If an error occurred, clear the result value. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ \ /* External interface. */ \ /* ------------------- */ \ type astGet##attribute##_( AstFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Frame,Get##attribute))( this, axis, status ); \ } /* * Name: * MAKE_SET * Purpose: * Implement a method to set an attribute value for a Frame axis. * Type: * Private macro. * Synopsis: * #include "frame.h" * MAKE_SET(attribute,type) * Class Membership: * Defined by the Frame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( AstFrame *this, int axis, value ) * * and an external interface function of the form: * * void astSet_( AstFrame *this, int axis, value ) * * which implement a method for setting an attribute value for a specified * axis of a Frame. * Parameters: * attribute * The name of the attribute to be set, as it appears in the * function name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * Notes: * - This macro assumes the existence of a method of the form: * * void astSetAxis( AstAxis *this, value ) * * which sets the required attribute for an Axis object. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_SET(attribute,type) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( AstFrame *this, int axis, type value, int *status ) { \ AstAxis *ax; /* Pointer to Axis object */ \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Validate the axis index and obtain a pointer to the required Axis. */ \ (void) astValidateAxis( this, axis, 1, "astSet" #attribute ); \ ax = astGetAxis( this, axis ); \ \ /* Set the Axis attribute value. */ \ astSetAxis##attribute( ax, value ); \ \ /* Annul the Axis pointer. */ \ ax = astAnnul( ax ); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( AstFrame *this, int axis, type value, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,Frame,Set##attribute))( this, axis, value, status ); \ } /* * Name: * MAKE_TEST * Purpose: * Implement a method to test if an attribute has been set for a Frame axis. * Type: * Private macro. * Synopsis: * #include "frame.h" * MAKE_TEST(attribute) * Class Membership: * Defined by the Frame class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( AstFrame *this, int axis ) * * and an external interface function of the form: * * int astTest_( AstFrame *this, int axis ) * * which implement a method for testing if an attribute has been set for a * specified axis of a Frame. * Parameters: * attribute * The name of the attribute to be tested, as it appears in the * function name (e.g. Label in "astTestLabel"). * Notes: * - This macro assumes the existence of a method of the form: * * void astTestAxis( AstAxis *this ) * * which tests the required attribute for an Axis object. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. */ /* Define the macro. */ #define MAKE_TEST(attribute) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attribute( AstFrame *this, int axis, int *status ) { \ AstAxis *ax; /* Pointer to Axis object */ \ int result; /* Value to be returned */ \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Validate the axis index and obtain a pointer to the required Axis. */ \ (void) astValidateAxis( this, axis, 1, "astTest" #attribute ); \ ax = astGetAxis( this, axis ); \ \ /* Test if the attribute has been set. */ \ result = astTestAxis##attribute( ax ); \ \ /* Annul the Axis pointer. */ \ ax = astAnnul( ax ); \ \ /* If an error occurred, clear the result value. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ \ /* External interface. */ \ /* ------------------- */ \ int astTest##attribute##_( AstFrame *this, int axis, int *status ) { \ \ /* Check the global error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,Frame,Test##attribute))( this, axis, status ); \ } /* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "object.h" /* Base Object class */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "pointset.h" /* Sets of points */ #include "unitmap.h" /* Unit Mapping */ #include "permmap.h" /* Coordinate permutation Mapping */ #include "cmpmap.h" /* Compound Mappings */ #include "axis.h" /* Coordinate Axis */ #include "skyaxis.h" /* Sky coordinate axes */ #include "skyframe.h" /* Celestial coordinate frames */ #include "channel.h" /* I/O channels */ #include "frame.h" /* Interface definition for this class */ #include "frameset.h" /* Collections of Frames */ #include "cmpframe.h" /* Compound Frames */ #include "pal.h" /* SLALIB library interface */ #include "unit.h" /* Units identification and mapping */ #include "globals.h" /* Thread-safe global data access */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; /* Pointers to parent class methods which are extended by this class. */ static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static void (* parent_cleanattribs)( AstObject *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif /* Define a variable to hold a SkyFrame which will be used for formatting and unformatting ObsLat and ObsLon values. */ static AstSkyFrame *skyframe; /* Define macros for accessing each item of thread specific global data. */ #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->AstFormatID_Init = 0; \ globals->AstFormatID_Istr = 0; \ globals->Label_Buff[ 0 ] = 0; \ globals->Symbol_Buff[ 0 ] = 0; \ globals->Title_Buff[ 0 ] = 0; \ globals->AstFmtDecimalYr_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Frame) #define class_init astGLOBAL(Frame,Class_Init) #define class_vtab astGLOBAL(Frame,Class_Vtab) #define getattrib_buff astGLOBAL(Frame,GetAttrib_Buff) #define astformatid_strings astGLOBAL(Frame,AstFormatID_Strings) #define astformatid_istr astGLOBAL(Frame,AstFormatID_Istr) #define astformatid_init astGLOBAL(Frame,AstFormatID_Init) #define label_buff astGLOBAL(Frame,Label_Buff) #define symbol_buff astGLOBAL(Frame,Symbol_Buff) #define title_buff astGLOBAL(Frame,Title_Buff) #define astfmtdecimalyr_buff astGLOBAL(Frame,AstFmtDecimalYr_Buff) /* If thread safety is not needed, declare and initialise globals at static variables. */ #else /* Buffer returned by GetAttrib. */ static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ]; /* Strings returned by astFormatID */ static char *astformatid_strings[ ASTFORMATID_MAX_STRINGS ]; /* Offset of next string in "AstFormatID_Strings" */ static int astformatid_istr; /* "AstFormatID_Strings" array initialised? */ static int astformatid_init; /* Default Label string buffer */ static char label_buff[ LABEL_BUFF_LEN + 1 ]; /* Default Symbol buffer */ static char symbol_buff[ SYMBOL_BUFF_LEN + 1 ]; /* Default Title string buffer */ static char title_buff[ TITLE_BUFF_LEN + 1 ]; /* Buffer for result string */ static char astfmtdecimalyr_buff[ ASTFMTDECIMALYR_BUFF_LEN + 1 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstFrameVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstAxis *GetAxis( AstFrame *, int, int * ); static AstFrame *PickAxes( AstFrame *, int, const int[], AstMapping **, int * ); static AstFrameSet *Convert( AstFrame *, AstFrame *, const char *, int * ); static AstFrameSet *ConvertX( AstFrame *, AstFrame *, const char *, int * ); static AstFrameSet *FindFrame( AstFrame *, AstFrame *, const char *, int * ); static void MatchAxes( AstFrame *, AstFrame *, int *, int * ); static void MatchAxesX( AstFrame *, AstFrame *, int *, int * ); static AstLineDef *LineDef( AstFrame *, const double[2], const double[2], int * ); static AstPointSet *FrameGrid( AstFrame *, int, const double *, const double *, int * ); static AstPointSet *ResolvePoints( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static char *CleanDomain( char *, int * ); static const char *Abbrev( AstFrame *, int, const char *, const char *, const char *, int * ); static const char *Format( AstFrame *, int, double, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetDefaultLabel( int, int * ); static const char *GetDefaultSymbol( AstFrame *, int, int * ); static const char *GetDefaultTitle( AstFrame *, int * ); static const char *GetDomain( AstFrame *, int * ); static const char *GetFormat( AstFrame *, int, int * ); static const char *GetInternalUnit( AstFrame *, int, int * ); static const char *GetLabel( AstFrame *, int, int * ); static const char *GetNormUnit( AstFrame *, int, int * ); static const char *GetSymbol( AstFrame *, int, int * ); static const char *GetTitle( AstFrame *, int * ); static const char *GetUnit( AstFrame *, int, int * ); static const int *GetPerm( AstFrame *, int * ); static double Angle( AstFrame *, const double[], const double[], const double[], int * ); static double AxAngle( AstFrame *, const double[], const double[], int, int * ); static double AxDistance( AstFrame *, int, double, double, int * ); static double AxOffset( AstFrame *, int, double, double, int * ); static double Distance( AstFrame *, const double[], const double[], int * ); static double Centre( AstFrame *, int, double, double, int * ); static double Gap( AstFrame *, int, double, int *, int * ); static double Offset2( AstFrame *, const double[2], double, double, double[2], int * ); static int AxIn( AstFrame *, int, double, double, double, int, int * ); static int ConsistentMaxAxes( AstFrame *, int, int * ); static int ConsistentMinAxes( AstFrame *, int, int * ); static int DefaultMaxAxes( AstFrame *, int * ); static int DefaultMinAxes( AstFrame *, int * ); static int DoNotSimplify( AstMapping *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int Fields( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); static int GetDigits( AstFrame *, int * ); static int GetDirection( AstFrame *, int, int * ); static int GetIsLinear( AstMapping *, int * ); static int GetIsSimple( AstMapping *, int * ); static int LineContains( AstFrame *, AstLineDef *, int, double *, int * ); static int LineCrossing( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); static int GetObjSize( AstObject *, int * ); static void AxNorm( AstFrame *, int, int, int, double *, int * ); static void CleanAttribs( AstObject *, int * ); static void LineOffset( AstFrame *, AstLineDef *, double, double, double[2], int * ); static double GetTop( AstFrame *, int, int * ); static int TestTop( AstFrame *, int, int * ); static void ClearTop( AstFrame *, int, int * ); static void SetTop( AstFrame *, int, double, int * ); static double GetBottom( AstFrame *, int, int * ); static int TestBottom( AstFrame *, int, int * ); static void ClearBottom( AstFrame *, int, int * ); static void SetBottom( AstFrame *, int, double, int * ); static AstSystemType GetSystem( AstFrame *, int * ); static int TestSystem( AstFrame *, int * ); static void ClearSystem( AstFrame *, int * ); static void SetSystem( AstFrame *, AstSystemType, int * ); static AstSystemType GetAlignSystem( AstFrame *, int * ); static int TestAlignSystem( AstFrame *, int * ); static void ClearAlignSystem( AstFrame *, int * ); static void SetAlignSystem( AstFrame *, AstSystemType, int * ); static double GetEpoch( AstFrame *, int * ); static int TestEpoch( AstFrame *, int * ); static void ClearEpoch( AstFrame *, int * ); static void SetEpoch( AstFrame *, double, int * ); static double GetObsLat( AstFrame *, int * ); static int TestObsLat( AstFrame *, int * ); static void ClearObsLat( AstFrame *, int * ); static void SetObsLat( AstFrame *, double, int * ); static double GetObsLon( AstFrame *, int * ); static int TestObsLon( AstFrame *, int * ); static void ClearObsLon( AstFrame *, int * ); static void SetObsLon( AstFrame *, double, int * ); static double GetObsAlt( AstFrame *, int * ); static int TestObsAlt( AstFrame *, int * ); static void ClearObsAlt( AstFrame *, int * ); static void SetObsAlt( AstFrame *, double, int * ); static double GetDut1( AstFrame *, int * ); static int TestDut1( AstFrame *, int * ); static void ClearDut1( AstFrame *, int * ); static void SetDut1( AstFrame *, double, int * ); static int GetActiveUnit( AstFrame *, int * ); static int TestActiveUnit( AstFrame *, int * ); static void SetActiveUnit( AstFrame *, int, int * ); static AstFrameSet *GetFrameVariants( AstFrame *, int * ); static void SetFrameVariants( AstFrame *, AstFrameSet *, int * ); static int GetFrameFlags( AstFrame *, int * ); static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); static int GetMatchEnd( AstFrame *, int * ); static int GetMaxAxes( AstFrame *, int * ); static int GetMinAxes( AstFrame *, int * ); static int GetNaxes( AstFrame *, int * ); static int GetNin( AstMapping *, int * ); static int GetNout( AstMapping *, int * ); static int GetPermute( AstFrame *, int * ); static int GetPreserveAxes( AstFrame *, int * ); static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestDigits( AstFrame *, int * ); static int TestDirection( AstFrame *, int, int * ); static int TestDomain( AstFrame *, int * ); static int TestFormat( AstFrame *, int, int * ); static int TestLabel( AstFrame *, int, int * ); static int TestMatchEnd( AstFrame *, int * ); static int TestMaxAxes( AstFrame *, int * ); static int TestMinAxes( AstFrame *, int * ); static int TestPermute( AstFrame *, int * ); static int TestPreserveAxes( AstFrame *, int * ); static int TestSymbol( AstFrame *, int, int * ); static int TestTitle( AstFrame *, int * ); static int TestUnit( AstFrame *, int, int * ); static int IsUnitFrame( AstFrame *, int * ); static int Unformat( AstFrame *, int, const char *, double *, int * ); static int ValidateAxis( AstFrame *, int, int, const char *, int * ); static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); static AstSystemType SystemCode( AstFrame *, const char *, int * ); static const char *SystemString( AstFrame *, AstSystemType, int * ); static void AddUnderscores( char *, int * ); static void CheckPerm( AstFrame *, const int *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearDigits( AstFrame *, int * ); static void ClearDirection( AstFrame *, int, int * ); static void ClearDomain( AstFrame *, int * ); static void ClearFormat( AstFrame *, int, int * ); static void ClearLabel( AstFrame *, int, int * ); static void ClearMatchEnd( AstFrame *, int * ); static void ClearMaxAxes( AstFrame *, int * ); static void ClearMinAxes( AstFrame *, int * ); static void ClearPermute( AstFrame *, int * ); static void ClearPreserveAxes( AstFrame *, int * ); static void ClearSymbol( AstFrame *, int, int * ); static void ClearTitle( AstFrame *, int * ); static void ClearUnit( AstFrame *, int, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void Intersect( AstFrame *, const double[2], const double[2], const double[2], const double[2], double[2], int * ); static void Norm( AstFrame *, double[], int * ); static void NormBox( AstFrame *, double[], double[], AstMapping *, int * ); static void Offset( AstFrame *, const double[], const double[], double, double[], int * ); static void Overlay( AstFrame *, const int *, AstFrame *, int * ); static void PermAxes( AstFrame *, const int[], int * ); static void PrimaryFrame( AstFrame *, int, AstFrame **, int *, int * ); static void ReportPoints( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); static void Resolve( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetAxis( AstFrame *, int, AstAxis *, int * ); static void SetDigits( AstFrame *, int, int * ); static void SetDirection( AstFrame *, int, int, int * ); static void SetDomain( AstFrame *, const char *, int * ); static void SetFormat( AstFrame *, int, const char *, int * ); static void SetFrameFlags( AstFrame *, int, int * ); static void SetLabel( AstFrame *, int, const char *, int * ); static void SetMatchEnd( AstFrame *, int, int * ); static void SetMaxAxes( AstFrame *, int, int * ); static void SetMinAxes( AstFrame *, int, int * ); static void SetPermute( AstFrame *, int, int * ); static void SetPreserveAxes( AstFrame *, int, int * ); static void SetSymbol( AstFrame *, int, const char *, int * ); static void SetTitle( AstFrame *, const char *, int * ); static void SetUnit( AstFrame *, int, const char *, int * ); static void NewUnit( AstAxis *, const char *, const char *, const char *, const char *, int * ); static void ValidateAxisSelection( AstFrame *, int, const int *, const char *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif /* Member functions. */ /* ================= */ static const char *Abbrev( AstFrame *this, int axis, const char *fmt, const char *str1, const char *str2, int *status ) { /* *+ * Name: * astAbbrev * Purpose: * Abbreviate a formatted Frame axis value by skipping leading fields. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * const char *astAbbrev( AstFrame *this, int axis, const char *fmt, * const char *str1, const char *str2 ) * Class Membership: * Frame method. * Description: * This function compares two Frame axis values that have been * formatted (using astFormat) and determines if they have any * redundant leading fields (i.e. leading fields in common which * can be suppressed when tabulating the values or plotting them on * the axis of a graph). * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which the values have been * formatted (axis numbering starts at zero for the first axis). * fmt * Pointer to a constant null-terminated string containing the * format specification used to format the two values. * str1 * Pointer to a constant null-terminated string containing the * first formatted value. If this is null, the returned pointer * points to the start of the final field in str2. * str2 * Pointer to a constant null-terminated string containing the * second formatted value. * Returned Value: * A pointer into the "str2" string which locates the first * character in the first field that differs between the two * formatted values. * * If the two values have no leading fields in common, the returned * value will point at the start of string "str2". If the two * values are equal, it will point at the terminating null at the * end of this string. * Notes: * - This function assumes that the format specification used was * the same when both values were formatted and that they both * apply to the same Frame axis. * - A pointer to the start of "str2" will be returned if this * function is invoked with the global error status set, or if it * should fail for any reason. *- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ const char *result; /* Result pointer to return */ /* Initialise. */ result = str2; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astAbbrev" ); ax = astGetAxis( this, axis ); /* Invoke the Axis astAxisAbbrev method to perform the processing. */ result = astAxisAbbrev( ax, fmt, str1, str2 ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = str2; /* Return the result. */ return result; } static void AddUnderscores( char *string, int *status ) { /* * Name: * AddUnderscores * Purpose: * Add underscores to a string in place of white space. * Type: * Private function. * Synopsis: * #include "frame.h" * void AddUnderscores( char *string, int *status ) * Class Membership: * Frame member function. * Description: * This function changes all white space characters in a string into * the underscore character '_'. * Parameters: * this * Pointer to the Frame. * string * Pointer to the null terminated string to be processed. * status * Pointer to the inherited status variable. */ /* Local Variables. */ int i; /* Loop counter for characters */ /* Inspect each character in the string. */ for ( i = 0; string[ i ]; i++ ) { /* If it is a white space character, replace it with an underscore. */ if ( isspace( string[ i ] ) ) string[ i ] = '_'; } } static double Angle( AstFrame *this, const double a[], const double b[], const double c[], int *status ) { /* *++ * Name: c astAngle f AST_ANGLE * Purpose: * Calculate the angle subtended by two points at a third point. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astAngle( AstFrame *this, const double a[], const double b[], c const double c[] ) f RESULT = AST_ANGLE( THIS, A, B, C, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * finds the angle at point B between the line joining points A and B, * and the line joining points C and B. These lines will in fact be * geodesic curves appropriate to the Frame in use. For instance, in * SkyFrame, they will be great circles. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c a f A( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the first point. c b f B( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the second point. c c f C( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the third point. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astAngle f AST_ANGLE = DOUBLE PRECISION * The angle in radians, from the line AB to the line CB. If the * Frame is 2-dimensional, it will be in the range $\pm \pi$, * and positive rotation is in the same sense as rotation from * the positive direction of axis 2 to the positive direction of * axis 1. If the Frame has more than 2 axes, a positive value will * always be returned in the range zero to $\pi$. * Notes: * - A value of AST__BAD will also be returned if points A and B are * co-incident, or if points B and C are co-incident. * - A value of AST__BAD will also be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- */ /* Local Variables: */ double *ab; /* Pointer to vector AB */ double *cb; /* Pointer to vector CB */ double cos; /* cosine of required angle */ double anga; /* Angle from +ve Y to the line BA */ double angc; /* Angle from +ve Y to the line BC */ double result; /* Result value to return */ double sla; /* Squared length of vector AB */ double slc; /* Squared length of vector CB */ double sp; /* Scalar product of AB and CB */ int axis; /* Axis index */ int naxes; /* Number of Frame axes */ int ok; /* Supplied points OK? */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Assume everything is ok */ ok = 1; /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); /* Obtain workspace. */ ab = (double *) astMalloc( sizeof(double)*naxes ); cb = (double *) astMalloc( sizeof(double)*naxes ); /* Check all positions are good, and form the vectors from b to a, and from b to c. Also find the squared length of each vector. */ if( astOK ) { sla = 0.0; slc = 0.0; for( axis = 0; axis < naxes; axis++ ) { if( a[ axis ] == AST__BAD || b[ axis ] == AST__BAD || c[ axis ] == AST__BAD ) { ok = 0; break; } else { ab[ axis ] = a[ axis ] - b[ axis ]; cb[ axis ] = c[ axis ] - b[ axis ]; sla += ( ab[ axis ] )*( ab[ axis ] ); slc += ( cb[ axis ] )*( cb[ axis ] ); } } /* Check that neither of the vectors have zero length. */ if( sla == 0 || slc == 0 ) ok = 0; /* Only proceed if these checks were passed. */ if ( ok ) { /* Deal first with 2-dimensional Frames. */ if( naxes == 2 ) { /* Find the angle from +ve Y to the line BA. */ anga = atan2( ab[ 0 ], ab[ 1 ] ); /* Find the angle from +ve Y to the line BC. */ angc = atan2( cb[ 0 ], cb[ 1 ] ); /* Find the difference, folded into the range +/- PI. */ result = palDrange( angc - anga ); /* Now deal with Frames with more than 2 axes. */ } else { /* Form the scalar product of the two vectors. */ sp = 0.0; for( axis = 0; axis < naxes; axis++ ) { sp += ab[ axis ]*cb[ axis ]; } /* Derive the required angle from the normalized scalar product. */ cos = sp/sqrt( sla*slc ); if( cos > 1.0 ) { cos = 1.0; } else if( cos < -1.0 ) { cos = -1.0; } result =acos( cos ); } } } /* Free the work space. */ ab = (double *) astFree( (void *) ab ); cb = (double *) astFree( (void *) cb ); /* Return the result. */ return result; } static double AxAngle( AstFrame *this, const double a[], const double b[], int axis, int *status ) { /* *++ * Name: c astAxAngle f AST_AXANGLE * Purpose: * Returns the angle from an axis, to a line through two points. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astAxAngle( AstFrame *this, const double a[], const double b[], int axis ) f RESULT = AST_AXANGLE( THIS, A, B, AXIS, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * finds the angle, as seen from point A, between the positive * direction of a specified axis, and the geodesic curve joining point * A to point B. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c a f A( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the first point. c b f B( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the second point. c axis f AXIS = INTEGER (Given) * The number of the Frame axis from which the angle is to be * measured (axis numbering starts at 1 for the first axis). f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astAxAngle f AST_AXANGLE = DOUBLE PRECISION * The angle in radians, from the positive direction of the * specified axis, to the line AB. If the Frame is 2-dimensional, * it will be in the range [-PI/2,+PI/2], and positive rotation is in * the same sense as rotation from the positive direction of axis 2 * to the positive direction of axis 1. If the Frame has more than 2 * axes, a positive value will always be returned in the range zero * to PI. * Notes: c - The geodesic curve used by this function is the path of f - The geodesic curve used by this routine is the path of * shortest distance between two points, as defined by the c astDistance function. f AST_DISTANCE function. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value, or if the require * position angle is undefined. *-- */ /* Local Variables: */ double *aa; /* Pointer to third point */ double ab; /* Absolute value of component */ double mxab; /* Largest absolute value of component */ double result; /* The returned value */ int iaxis; /* Axis index */ int naxes; /* Number of Frame axes */ int ok; /* Are values ok to use? */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index. */ (void) astValidateAxis( this, axis - 1, 1, "astAxAngle" ); /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); /* Obtain workspace. */ aa = (double *) astMalloc( sizeof(double)*naxes ); /* Create a position which is offset slightly from point A in the positive direction of the specified axis. Also get the largest absolute value of any component of the vector AB. */ if( astOK ) { ok = 1; mxab = 0.0; for( iaxis = 0; iaxis < naxes; iaxis++ ) { if( a[ iaxis ] != AST__BAD && b[ iaxis ] != AST__BAD ) { aa[ iaxis ] = a[ iaxis ]; ab = fabs( a[ iaxis ] - b[ iaxis ] ); if( ab > mxab ) mxab = ab; } else { ok = 0; break; } } if( ok ) { if( a[ axis - 1 ] != 0.0 ) { aa[ axis - 1 ] += 10000.0*DBL_EPSILON*fabs( a[ axis - 1 ] ); } else if( b[ axis - 1 ] != 0.0 ) { aa[ axis - 1 ] = 10000.0*DBL_EPSILON*fabs( b[ iaxis - 1 ] ); } else if( mxab != 0.0 ) { aa[ axis - 1 ] = 10000.0*DBL_EPSILON*mxab; } else { aa[ axis - 1 ] = 1.0; } /* Use astAngle to get the required angle. */ result = astAngle( this, aa, a, b ); } } /* Free the workspace. */ aa = (double *) astFree( (void *) aa ); /* Return the result. */ return result; } static double AxDistance( AstFrame *this, int axis, double v1, double v2, int *status ) { /* *++ * Name: c astAxDistance f AST_AXDISTANCE * Purpose: * Find the distance between two axis values. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astAxDistance( AstFrame *this, int axis, double v1, double v2 ) f RESULT = AST_AXDISTANCE( THIS, AXIS, V1, V2, STATUS ) * Class Membership: * Frame method. * Description: c This function returns a signed value representing the axis increment f This routine returns a signed value representing the axis increment * from axis value v1 to axis value v2. * * For a simple Frame, this is a trivial operation returning the * difference between the two axis values. But for other derived classes * of Frame (such as a SkyFrame) this is not the case. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c axis f AXIS = INTEGER (Given) * The index of the axis to which the supplied values refer. The * first axis has index 1. c v1 f V1 = DOUBLE PRECISION (Given) * The first axis value. c v2 f V2 = DOUBLE PRECISION (Given) * The second axis value. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astAxDistance f AST_AXDISTANCE = DOUBLE PRECISION * The distance from the first to the second axis value. * Notes: * - This function will return a "bad" result value (AST__BAD) if * any of the input values has this value. * - A "bad" value will also be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- * Implementation Deficiencies; * - The protected interface for this function uses 1-based axis * numbering (like the public interface), rather than the more usual * zero-based system used by all other protected interfaces. There is * no real reason for this, and it should be changed at some time. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ double result; /* The returned answer */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis - 1, 1, "astAxDistance" ); ax = astGetAxis( this, axis - 1 ); /* Use the AxisDistance method associated with the Axis. */ if( astOK ) result = astAxisDistance( ax, v1, v2 ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* Return the result. */ return result; } static void AxNorm( AstFrame *this, int axis, int oper, int nval, double *values, int *status ){ /* *++ * Name: c astAxNorm f AST_AXNORM * Purpose: * Normalise an array of axis values. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astAxNorm( AstFrame *this, int axis, int oper, int nval, c double *values, int *status ) f CALL AST_AXNORM( THIS, AXIS, OPER, NVAL, VALUES, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * modifies a supplied array of axis values so that they are normalised * in the manner indicated by c parameter "oper". f argument OPER. * * No normalisation is possible for a simple Frame and so the supplied * values are returned unchanged. However, this may not be the case for * specialised sub-classes of Frame. For instance, a SkyFrame has a * discontinuity at zero longitude and so a longitude value can be * expressed in the range [-Pi,+PI] or the range [0,2*PI]. See the * "Applicability:" section below for details. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c axis f AXIS = INTEGER (Given) * The index of the axis to which the supplied values refer. The * first axis has index 1. c oper f OPER = INTEGER (Given) * Indicates the type of normalisation to be applied. If zero is * supplied, the normalisation will be the same as that performed by c function astNorm. f routine AST_NORM. * If 1 is supplied, the normalisation will be chosen automatically * so that the resulting list has the smallest range. c nval f NVAL = INTEGER (Given) * The number of points in the values array. c values f VALUES( NVAL ) = DOUBLE PRECISION (Given and Returned) * On entry, the axis values to be normalised. Modified on exit to * hold the normalised values. f STATUS = INTEGER (Given and Returned) f The global status. * Applicability: * SkyFrame c If "oper" f If OPER * is 0, longitude values are returned in the range [0,2*PI]. c If "oper" f If OPER * is 1, longitude values are returned in either the range * [0,2*PI] or [-PI,PI]. The choice is made so that that the * resulting list has the smallest range. Latitude values are * always returned in the range [-PI,PI]. * All other classes of Frame * The supplied axis values are returned unchanged. *-- * Implementation Deficiencies; * - The protected interface for this function uses 1-based axis * numbering (like the public interface), rather than the more usual * zero-based system used by all other protected interfaces. There is * no real reason for this, and it should be changed at some time. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis - 1, 1, "astAxNorm" ); ax = astGetAxis( this, axis - 1 ); /* Validate ther "oper" value. */ if( ( oper < 0 || oper > 1 ) && astOK ) { astError( AST__OPRIN, "astAxNorm(%s): Invalid operation %d.", status, astGetClass( this ), oper ); } /* Use the AxisNormValues method associated with the Axis. */ if( astOK ) astAxisNormValues( ax, oper, nval, values ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); } static int AxIn( AstFrame *this, int axis, double lo, double hi, double val, int closed, int *status ){ /* *+ * Name: * astAxIn * Purpose: * Test if an axis value lies within a given interval. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astAxIn( AstFrame *this, int axis, double lo, double hi, double val, * int closed ) * Class Membership: * Frame member function. * Description: * This function returns non-zero if a given axis values lies within a * given axis interval. * Parameters: * this * Pointer to the Frame. * axis * The index of the axis. The first axis has index 0. * lo * The lower axis limit of the interval. * hi * The upper axis limit of the interval. * val * The axis value to be tested. * closed * If non-zero, then the lo and hi axis values are themselves * considered to be within the interval. Otherwise they are outside. * Returned Value: * Non-zero if the test value is inside the interval. * Applicability: * Frame * Uses simple Euclidean test * SkyFrame * All angles which are numerically between "lo" and "hi" are within * the interval. Angle outside this range are also within the interval * if they can be brought into the range by addition or subtraction * of a multiple of 2.PI. *- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ int result; /* Returned value */ /* For speed, omit the astOK check and axis validation (since this is protected code, AST should get it right). Obtain a pointer to the required Axis. */ ax = astGetAxis( this, axis ); /* Use the AxisIn method associated with the Axis. */ result = ax ? astAxisIn( ax, lo, hi, val, closed ) : 0; /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* Return the result. */ return result; } static double AxOffset( AstFrame *this, int axis, double v1, double dist, int *status ) { /* *++ * Name: c astAxOffset f AST_AXOFFSET * Purpose: * Add an increment onto a supplied axis value. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astAxOffset( AstFrame *this, int axis, double v1, double dist ) f RESULT = AST_AXOFFSET( THIS, AXIS, V1, DIST, STATUS ) * Class Membership: * Frame method. * Description: c This function returns an axis value formed by adding a signed axis f This routine returns an axis value formed by adding a signed axis * increment onto a supplied axis value. * * For a simple Frame, this is a trivial operation returning the * sum of the two supplied values. But for other derived classes * of Frame (such as a SkyFrame) this is not the case. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c axis f AXIS = INTEGER (Given) * The index of the axis to which the supplied values refer. The * first axis has index 1. c v1 f V1 = DOUBLE PRECISION (Given) * The original axis value. c dist f DIST = DOUBLE PRECISION (Given) * The axis increment to add to the original axis value. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astAxOffset f AST_AXOFFSET = DOUBLE PRECISION * The incremented axis value. * Notes: * - This function will return a "bad" result value (AST__BAD) if * any of the input values has this value. * - A "bad" value will also be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ double result; /* The returned answer */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis - 1, 1, "astAxOffset" ); ax = astGetAxis( this, axis - 1 ); /* Use the AxisOffset method associated with the Axis. */ if( astOK ) result = astAxisOffset( ax, v1, dist ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* Return the result. */ return result; } static double Centre( AstFrame *this, int axis, double value, double gap, int *status ) { /* *+ * Name: * astCentre * Purpose: * Find a "nice" central value for tabulating Axis values. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * double astCentre( AstFrame *this, int axis, double value, double gap ) * Class Membership: * Frame method. * Description: * This function returns an axis value which produces a nice formatted * value suitable for a major tick mark on a plot axis, close to the * supplied axis value. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which a gap is to be found. * value * An arbitrary axis value in the section that is being plotted. * gap * The gap size. * Returned Value: * The nice central axis value. * Notes: * - A value of zero is returned if the supplied gap size is zero. * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ double result; /* The nice central value */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astCentre" ); ax = astGetAxis( this, axis ); /* Find the nice central value. */ result = astAxisCentre( ax, value, gap ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0.0; /* Return the result. */ return result; } static void CheckPerm( AstFrame *this, const int *perm, const char *method, int *status ) { /* *+ * Name: * astCheckPerm * Purpose: * Check that an array contains a valid permutation. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astCheckPerm( AstFrame *this, const int *perm, const char *method ) * Class Membership: * Frame method. * Description: * This function checks the validity of a permutation array that * will be used to permute the order of a Frame's axes. If the * permutation specified by the array is not valid, an error is * reported and the global error status is set. Otherwise, the * function returns without further action. * Parameters: * this * Pointer to the Frame. * perm * Pointer to an array of integers with the same number of * elements as there are axes in the Frame. For each axis, the * corresponding integer gives the (zero based) axis index to be * used to identify the information for that axis (using the * un-permuted axis numbering). To be valid, the integers in * this array should therefore all lie in the range zero to * (naxes-1) inclusive, where "naxes" is the number of Frame * axes, and each value should occur exactly once. * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function * to validate a permutation array. This method name is used * solely for constructing error messages. * Notes: * - Error messages issued by this function refer to the external * (public) numbering system used for axes (which is one-based), * whereas zero-based axis indices are used internally. *- */ /* Local Variables: */ int *there; /* Pointer to temporary array */ int axis; /* Loop counter for axes */ int naxes; /* Number of Frame axes */ int valid; /* Permutation array is valid? */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise. */ valid = 1; /* Obtain the number of Frame axes and allocate a temporary array of integers with the same number of elements. */ naxes = astGetNaxes( this ); there = astMalloc( sizeof( int ) * (size_t) naxes ); if ( astOK ) { /* Initialise the temporary array to zero. */ for ( axis = 0; axis < naxes; axis++ ) there[ axis ] = 0; /* Scan the permutation array, checking that each permuted axis index it contains is within the correct range. Note an error and quit checking if an invalid value is found. */ for ( axis = 0; axis < naxes; axis++ ) { if ( ( perm[ axis ] < 0 ) || ( perm[ axis ] >= naxes ) ) { valid = 0; break; /* Use the temporary array to count how many times each valid axis index occurs. */ } else { there[ perm[ axis ] ]++; } } /* If all the axis indices were within range, check to ensure that each value occurred only once. */ if ( valid ) { for ( axis = 0; axis < naxes; axis++ ) { /* Note an error and quit checking if any value did not occur exactly once. */ if ( there[ axis ] != 1 ) { valid = 0; break; } } } } /* Free the temporary array. */ there = astFree( there ); /* If an invalid permutation was detected and no other error has occurred, then report an error (note we convert to one-based axis numbering in the error message). */ if ( !valid && astOK ) { astError( AST__PRMIN, "%s(%s): Invalid axis permutation array.", status, method, astGetClass( this ) ); astError( AST__PRMIN, "Each axis index should lie in the range 1 to %d " "and should occur only once.", status, naxes ); } } static void CleanAttribs( AstObject *this_object, int *status ) { /* * Name: * CleanAttribs * Purpose: * Clear any invalid set attribute values. * Type: * Private function. * Synopsis: * #include "frame.h" * void CleanAttribs( AstObject *this_object, int *status ) * Class Membership: * Frame member function (over-rides the protected astCleanAttribs * method inherited from the Object class). * Description: * This function clears any attributes that are currently set to * invalid values in thr supplied object. * Parameters: * this * Pointer to the Object to be cleaned. */ /* Local Variables; */ AstAxis *ax; AstFrame *this; int i; int nax; int reporting; /* Check inherited status */ if( !astOK ) return; /* Get a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Defer error reporting, as required by the astCLEAN_ATTRIB macro. */ reporting = astReporting( 0 ); /* Clean attributes in any Objects contained within "this". */ nax = astGetNaxes( this ); for( i = 0; i < nax; i++ ) { ax = astGetAxis( this, i ); astCleanAttribs( ax ); ax = astAnnul( ax ); } /* Clean attributes of this class. */ astCLEAN_ATTRIB(System) astCLEAN_ATTRIB(AlignSystem) /* Re-establish error reporting. */ astReporting( reporting ); /* Invoke the method inherited form the parent to clean attributes defined by the parent class. */ (*parent_cleanattribs)( this_object, status ); } static char *CleanDomain( char *domain, int *status ) { /* * Name: * CleanDomain * Purpose: * Clean a Domain string and convert to upper case. * Type: * Private function. * Synopsis: * #include "frame.h" * char *CleanDomain( char *domain, int *status ) * Class Membership: * Frame member function. * Description: * This function removes all white space from a string and converts * other characters to upper case. It is intended for cleaning up * values supplied for the Domain attribute of a Frame. * Parameters: * domain * Pointer to the null terminated Domain string to be modified. * status * Pointer to the inherited status variable. * Returned Value: * The pointer value "domain" is always returned (even under error * conditions). */ /* Local Variables: */ int i; /* Loop counter for characters */ int j; /* Good character count */ /* Check the global error status. */ if ( !astOK ) return domain; /* Eliminate white space characters and convert the rest to upper case. */ for ( i = j = 0; domain[ i ]; i++ ) { if ( !isspace( domain[ i ] ) ) domain[ j++ ] = toupper( domain[ i ] ); } domain[ j ] = '\0'; /* Return the string pointer. */ return domain; } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Frame member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * Frame, so that the default value will subsequently be used. * Parameters: * this * Pointer to the Frame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis */ AstFrame *pfrm; /* Pointer to primary Frame containing axis */ AstFrame *this; /* Pointer to the Frame structure */ char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ char *axis_attrib; /* Pointer to axis attribute name */ const char *old_attrib; /* Pointer to supplied attribute name string */ int axis; /* Frame axis number */ int axis_nc; /* No. characters in axis attribute name */ int free_axis_attrib; /* Should axis_attrib be freed? */ int has_axis; /* Does attrib name include axis specifier? */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ int oldrep; /* Original error reporting state */ int paxis; /* Axis index within primary frame */ int used; /* Could the setting string be used? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Set a flag indicating if the attribute name includes an axis specifier. */ has_axis = ( strchr( attrib, '(' ) != NULL ); /* A flag indicating that we do not need to free the axis_attrib memory. */ free_axis_attrib = 0; /* Initialise things to avoid compiler warnings. */ axis_attrib = NULL; old_attrib = NULL; /* Jump back to here if we are trying the same attribute but with an explicit axis "(1)" added to the end of the name. */ L1: /* Obtain the length of the "attrib" string. */ len = strlen( attrib ); /* Check the attribute name and clear the appropriate attribute. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { astClearDigits( this ); /* Digits(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { /* There is no function to clear the Digits attribute for an axis directly, so obtain a pointer to the Axis and use this to clear the attribute. */ (void) astValidateAxis( this, axis - 1, 1, "astClearDigits(axis)" ); ax = astGetAxis( this, axis - 1 ); astClearAxisDigits( ax ); ax = astAnnul( ax ); /* Direction(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearDirection( this, axis - 1 ); /* Epoch. */ /* ------ */ } else if ( !strcmp( attrib, "epoch" ) ) { astClearEpoch( this ); /* Top(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearTop( this, axis - 1 ); /* Bottom(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearBottom( this, axis - 1 ); /* Domain. */ /* ------- */ } else if ( !strcmp( attrib, "domain" ) ) { astClearDomain( this ); /* Format(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearFormat( this, axis - 1 ); /* Label(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearLabel( this, axis - 1 ); /* MatchEnd. */ /* --------- */ } else if ( !strcmp( attrib, "matchend" ) ) { astClearMatchEnd( this ); /* MaxAxes. */ /* -------- */ } else if ( !strcmp( attrib, "maxaxes" ) ) { astClearMaxAxes( this ); /* MinAxes. */ /* -------- */ } else if ( !strcmp( attrib, "minaxes" ) ) { astClearMinAxes( this ); /* Permute. */ /* -------- */ } else if ( !strcmp( attrib, "permute" ) ) { astClearPermute( this ); /* PreserveAxes. */ /* ------------- */ } else if ( !strcmp( attrib, "preserveaxes" ) ) { astClearPreserveAxes( this ); /* Symbol(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearSymbol( this, axis - 1 ); /* System. */ /* ------- */ } else if ( !strcmp( attrib, "system" ) ) { astClearSystem( this ); /* AlignSystem. */ /* ------------ */ } else if ( !strcmp( attrib, "alignsystem" ) ) { astClearAlignSystem( this ); /* Title. */ /* ------ */ } else if ( !strcmp( attrib, "title" ) ) { astClearTitle( this ); /* Unit(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { astClearUnit( this, axis - 1 ); /* ObsLat. */ /* ------- */ } else if ( !strcmp( attrib, "obslat" ) ) { astClearObsLat( this ); /* ObsLon. */ /* ------- */ } else if ( !strcmp( attrib, "obslon" ) ) { astClearObsLon( this ); /* ObsAlt. */ /* ------- */ } else if ( !strcmp( attrib, "obsalt" ) ) { astClearObsAlt( this ); /* Dut1 */ /* --- */ } else if ( !strcmp( attrib, "dut1" ) ) { astClearDut1( this ); /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then report an error. */ } else if ( !strcmp( attrib, "naxes" ) || !strncmp( attrib, "normunit", 8 ) || !strncmp( attrib, "internalunit", 12 ) ) { astError( AST__NOWRT, "astClear: Invalid attempt to clear the \"%s\" " "value for a %s.", status, attrib, astGetClass( this ) ); astError( AST__NOWRT, "This is a read-only attribute." , status); /* Other axis attributes. */ /* ---------------------- */ /* If the attribute was not identified above, but appears to refer to a Frame axis, then it may refer to an Axis object of a derived type (which has additional attributes not recognised here). */ } else if( !free_axis_attrib && ( nc = 0, ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", &axis_nc, &axis, &nc ) ) && ( nc >= len ) ) ) { /* Validate the axis index and extract the attribute name. */ (void) astValidateAxis( this, axis - 1, 1, "astClear" ); axis_attrib = astString( attrib, axis_nc ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis - 1 ); if( astOK ) { /* Assume that we will be able to use the attribute name. */ used = 1; /* Temporarily switch off error reporting so that if the following attempt to access the axis attribute fails, we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. Any errors reported in this context will simply be ignored, in particularly they are not deferred for later delivery. */ oldrep = astReporting( 0 ); /* Use the Axis astClearAttrib method to clear the attribute value. */ astClearAttrib( ax, axis_attrib ); /* If the above call failed with a status of AST__BADAT, indicating that the attribute name was not recognised, clear the status so that we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. */ if( astStatus == AST__BADAT ) { astClearStatus; /* Find the primary Frame containing the specified axis. */ astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); /* Only attempt to use the primary Frame if it is not the same as "this" - otherwise we could end up in an infinite loop. */ if( pfrm != this ) { /* astPrimaryFrame returns the original - unpermuted - axis index within the primary Frame. So we need to take into account any axis permutation which has been applied to the primary Frame when forming the attribute name to use below. Find the permuted (external) axis index which corresponds to the internal (unpermuted) axis index "paxis". */ paxis = astValidateAxis( pfrm, paxis, 0, "astClear" ); /* Modify the attribute name to refer to the axis numbering of the primary frame. */ sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); /* Attempt to clear the attribute as an attribute of the primary Frame. */ astClearAttrib( pfrm, pfrm_attrib ); /* If this failed, clear the status and indicate that we have not managed to use the attribute name. */ if( !astOK ) { astClearStatus; used = 0; } } else { used = 0; } /* If not found attempt to clear the attribute value in the Axis, omitting the axis index. */ if( ! used ) { astClearAttrib( pfrm, axis_attrib ); if( !astOK ) { astClearStatus; } else { used = 1; } } /* Annul the primary Frame pointer. */ pfrm = astAnnul( pfrm ); } /* Re-instate the original error reporting state. */ astReporting( oldrep ); /* If we could not use the attribute name, attempt to clear the axis attribute again, this time retaining the error report. This is done to ensure the user gets an appropriate error message. */ if( !used ) astClearAttrib( ax, axis_attrib ); } /* Annul the Axis pointer and free the memory holding the attribute name. */ ax = astAnnul( ax ); axis_attrib = astFree( axis_attrib ); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, and the Frame has only 1 axis, and the attribute name does not already include an axis specifier, try again after appending "(1)" to the end of the attribute name. */ } else if( !has_axis && astGetNaxes( this ) == 1 ) { /* Take a copy of the supplied name, allowing 3 extra characters for the axis specifier "(1)". */ axis_attrib = astMalloc( len + 4 ); if( axis_attrib ) memcpy( axis_attrib, attrib, len ); /* Indicate we should free the axis_attrib memory. */ free_axis_attrib = 1; /* Add in the axis specifier. */ strcpy( axis_attrib + len, "(1)" ); /* Use the new attribute name instead of the supplied name. */ old_attrib = attrib; attrib = axis_attrib; /* Indicate the attribute name now has an axis specifier. */ has_axis = 1; /* Jump back to try interpreting the new attribute name. */ goto L1; /* Not recognised. */ /* --------------- */ /* If the attribute name is still not recognised, pass it on to the parent method for further interpretation. First re-instate the original attrib name string if it was changed above. */ } else { if( free_axis_attrib ) { attrib = old_attrib; axis_attrib = astFree( axis_attrib ); } (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearUnit( AstFrame *this, int axis, int *status ) { /* * Name: * ClearUnit * Purpose: * Clear the Unit attribute of a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void ClearUnit( AstFrame *this, int axis, int *status ) * Class Membership: * Frame method. * Description: * This function clears the Unit value for an axis of a Frame. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which the Unit value is to * be cleared. * unit * The new value to be set. * status * Pointer to the inherited status variable. * Returned Value: * void. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ const char *units; /* Pointer to units string */ char *old_units; /* Pointer to copy of original units */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the axis index. */ (void) astValidateAxis( this, axis, 1, "astSetUnit" ); /* Do nothing more if the attribute is already cleared. */ if( astTestUnit( this, axis ) ) { /* Obtain a pointer to the required Axis. */ ax = astGetAxis( this, axis ); /* Save a copy of the old units. */ units = astGetAxisUnit( ax ); old_units = astStore( NULL, units, strlen( units ) + 1 ); /* Clear the Axis Unit attribute value, and then get a pointer to the new default Units string. */ astClearAxisUnit( ax ); units = astGetUnit( this, axis ); /* The new unit may require the Label and/or Symbol to be changed, but only if the Frames ActiveUnit flag is set. */ if( astGetActiveUnit( this ) ) NewUnit( ax, old_units, units, "astSetUnit", astGetClass( this ), status ); /* Free resources. */ old_units = astFree( old_units ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); } } static int ConsistentMaxAxes( AstFrame *this, int value, int *status ) { /* * Name: * ConsistentMaxAxes * Purpose: * Ensure a consistent value when setting the MaxAxes attribute. * Type: * Private function. * Synopsis: * #include "frame.h" * int ConsistentMaxAxes( AstFrame *this, int value, int *status ) * Class Membership: * Frame member function. * Description: * This function accepts a value which is to be set for a Frame's MaxAxes * attribute and returns an appropriately adjusted value to be assigned * to the Frame structure's max_axes component. If necessary, the Frame's * MinAxes attribute is adjusted to remain consistent with the new MaxAxes * value (but note that the MaxAxes value itself is not assigned by this * function). * Parameters: * this * Pointer to the Frame. * value * The new value being set for the MaxAxes attribute. * status * Pointer to the inherited status variable. * Returned Value: * The value to be assigned to the max_axes component. * Notes: * - A value of -INT_MAX will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return -INT_MAX; /* Ensure that the result value isn't negative. */ result = ( value >= 0 ) ? value : 0; /* Check if the MinAxes attribute is set. If not, its default value will be consistent with the MaxAxes value (the DefaultMinAxes function ensures this). Otherwise, obtain its value to check for consistency. */ if ( astTestMinAxes( this ) ) { /* If necessary, set a new MinAxes value to prevent it exceeding the MaxAxes value about to be returned. */ if ( astGetMinAxes( this ) > result ) astSetMinAxes( this, result ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -INT_MAX; /* Return the result. */ return result; } static int ConsistentMinAxes( AstFrame *this, int value, int *status ) { /* * Name: * ConsistentMinAxes * Purpose: * Ensure a consistent value when setting the MinAxes attribute. * Type: * Private function. * Synopsis: * #include "frame.h" * int ConsistentMinAxes( AstFrame *this, int value, int *status ) * Class Membership: * Frame member function. * Description: * This function accepts a value which is to be set for a Frame's MinAxes * attribute and returns an appropriately adjusted value to be assigned * to the Frame structure's min_axes component. If necessary, the Frame's * MaxAxes attribute is adjusted to remain consistent with the new MinAxes * value (but note that the MinAxes value itself is not assigned by this * function). * Parameters: * this * Pointer to the Frame. * value * The new value being set for the MinAxes attribute. * status * Pointer to the inherited status variable. * Returned Value: * The value to be assigned to the min_axes component. * Notes: * - A value of -INT_MAX will be returned if this function is * invoked with the global error status set, or if it should fail * for any reason. */ /* Local Variables: */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return -INT_MAX; /* Ensure that the result value isn't negative. */ result = ( value >= 0 ) ? value : 0; /* Check if the MaxAxes attribute is set. If not, its default value will be consistent with the MinAxes value (the DefaultMaxAxes function ensures this). Otherwise, obtain its value to check for consistency. */ if ( astTestMaxAxes( this ) ) { /* If necessary, set a new MaxAxes value to prevent it being less than the MinAxes value about to be returned. */ if ( astGetMaxAxes( this ) < result ) astSetMaxAxes( this, result ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -INT_MAX; /* Return the result. */ return result; } static AstFrameSet *Convert( AstFrame *from, AstFrame *to, const char *domainlist, int *status ) { /* *++ * Name: c astConvert f AST_CONVERT * Purpose: * Determine how to convert between two coordinate systems. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c AstFrameSet *astConvert( AstFrame *from, AstFrame *to, c const char *domainlist ) f RESULT = AST_CONVERT( FROM, TO, DOMAINLIST, STATUS ) * Class Membership: * Frame method. * Description: * This function compares two Frames and determines whether it is * possible to convert between the coordinate systems which they * represent. If conversion is possible, it returns a FrameSet * which describes the conversion and which may be used (as a * Mapping) to transform coordinate values in either direction. * * The same function may also be used to determine how to convert * between two FrameSets (or between a Frame and a FrameSet, or * vice versa). This mode is intended for use when (for example) * two images have been calibrated by attaching a FrameSet to each. c astConvert might then be used to search for a f AST_CONVERT might then be used to search for a * celestial coordinate system that both images have in common, and * the result could then be used to convert between the pixel * coordinates of both images -- having effectively used their * celestial coordinate systems to align them. * * When using FrameSets, there may be more than one possible * intermediate coordinate system in which to perform the * conversion (for instance, two FrameSets might both have * celestial coordinates, detector coordinates, pixel coordinates, * etc.). A comma-separated list of coordinate system domains may * therefore be given which defines a priority order to use when * selecting the intermediate coordinate system. The path used for * conversion must go via an intermediate coordinate system whose * Domain attribute matches one of the domains given. If conversion * cannot be achieved using the first domain, the next one is * considered, and so on, until success is achieved. * Parameters: c from f FROM = INTEGER (Given) * Pointer to a Frame which represents the "source" coordinate * system. This is the coordinate system in which you already * have coordinates available. * * If a FrameSet is given, its current Frame (as determined by * its Current attribute) is taken to describe the source * coordinate system. Note that the Base attribute of this * FrameSet may be modified by this function to indicate which * intermediate coordinate system was used (see under * "FrameSets" in the "Applicability" section for details). c to f TO = INTEGER (Given) * Pointer to a Frame which represents the "destination" * coordinate system. This is the coordinate system into which * you wish to convert your coordinates. * * If a FrameSet is given, its current Frame (as determined by * its Current attribute) is taken to describe the destination * coordinate system. Note that the Base attribute of this * FrameSet may be modified by this function to indicate which * intermediate coordinate system was used (see under * "FrameSets" in the "Applicability" section for details). c domainlist f DOMAINLIST = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string containing a f A character string containing a * comma-separated list of Frame domains. This may be used to * define a priority order for the different intermediate * coordinate systems that might be used to perform the * conversion. * * The function will first try to obtain a conversion by making * use only of an intermediate coordinate system whose Domain * attribute matches the first domain in this list. If this * fails, the second domain in the list will be used, and so on, * until conversion is achieved. A blank domain (e.g. two * consecutive commas) indicates that all coordinate systems * should be considered, regardless of their domains. * * This list is case-insensitive and all white space is ignored. * If you do not wish to restrict the domain in this way, c you should supply an empty string. This is normally f you should supply a blank string. This is normally * appropriate if either of the source or destination coordinate * systems are described by Frames (rather than FrameSets), * since there is then usually only one possible choice of * intermediate coordinate system. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astConvert() f AST_CONVERT = INTEGER * If the requested coordinate conversion is possible, the * function returns a pointer to a FrameSet which describes the * conversion. Otherwise, a null Object pointer (AST__NULL) is * returned without error. * * If a FrameSet is returned, it will contain two Frames. Frame * number 1 (its base Frame) will describe the source coordinate c system, corresponding to the "from" parameter. Frame number 2 f system, corresponding to the FROM argument. Frame number 2 * (its current Frame) will describe the destination coordinate c system, corresponding to the "to" parameter. The Mapping f system, corresponding to the TO argument. The Mapping * which inter-relates these two Frames will perform the * required conversion between their respective coordinate * systems. * * Note that a FrameSet may be used both as a Mapping and as a * Frame. If the result is used as a Mapping (e.g. with c astTran2), then it provides a means of converting coordinates f AST_TRAN2), then it provides a means of converting coordinates * from the source to the destination coordinate system (or * vice versa if its inverse transformation is selected). If it * is used as a Frame, its attributes will describe the * destination coordinate system. * Applicability: * DSBSpecFrame * If the AlignSideBand attribute is non-zero, alignment occurs in the * upper sideband expressed within the spectral system and standard of * rest given by attributes AlignSystem and AlignStdOfRest. If * AlignSideBand is zero, the two DSBSpecFrames are aligned as if * they were simple SpecFrames (i.e. the SideBand is ignored). * Frame * This function applies to all Frames. Alignment occurs within the * coordinate system given by attribute AlignSystem. * FrameSet c If either of the "from" or "to" parameters is a pointer to a f If either of the FROM or TO arguments is a pointer to a c FrameSet, then astConvert will attempt to convert from the f FrameSet, then AST_CONVERT will attempt to convert from the c coordinate system described by the current Frame of the "from" f coordinate system described by the current Frame of the FROM c FrameSet to that described by the current Frame of the "to" f FrameSet to that described by the current Frame of the TO * FrameSet. * * To achieve this, it will consider all of the Frames within * each FrameSet as a possible way of reaching an intermediate * coordinate system that can be used for the conversion. There * is then the possibility that more than one conversion path * may exist and, unless the choice is sufficiently restricted c by the "domainlist" string, the sequence in which the Frames f by the DOMAINLIST string, the sequence in which the Frames * are considered can be important. In this case, the search * for a conversion path proceeds as follows: c - Each field in the "domainlist" string is considered in turn. f - Each field in the DOMAINLIST string is considered in turn. * - The Frames within each FrameSet are considered in a * specific order: (1) the base Frame is always considered * first, (2) after this come all the other Frames in * Frame-index order (but omitting the base and current Frames), * (3) the current Frame is always considered last. However, if * either FrameSet's Invert attribute is set to a non-zero value * (so that the FrameSet is inverted), then its Frames are * considered in reverse order. (Note that this still means that * the base Frame is considered first and the current Frame * last, because the Invert value will also cause these Frames * to swap places.) * - All source Frames are first considered (in the appropriate * order) for conversion to the first destination Frame. If no * suitable intermediate coordinate system emerges, they are * then considered again for conversion to the second * destination Frame (in the appropriate order), and so on. * - Generally, the first suitable intermediate coordinate * system found is used. However, the overall Mapping between * the source and destination coordinate systems is also * examined. Preference is given to cases where both the * forward and inverse transformations are defined (as indicated * by the TranForward and TranInverse attributes). If only one * transformation is defined, the forward one is preferred. * - If the domain of the intermediate coordinate system matches c the current "domainlist" field, the conversion path is f the current DOMAINLIST field, the conversion path is c accepted. Otherwise, the next "domainlist" field is considered f accepted. Otherwise, the next DOMAINLIST field is considered * and the process repeated. * * If conversion is possible, the Base attributes of the two * FrameSets will be modified on exit to identify the Frames * used to access the intermediate coordinate system which was * finally accepted. * * Note that it is possible to force a particular Frame within a * FrameSet to be used as the basis for the intermediate * coordinate system, if it is suitable, by (a) focussing * attention on c it by specifying its domain in the "domainlist" string, or (b) f it by specifying its domain in the DOMAINLIST string, or (b) * making it the base Frame, since this is always considered * first. * SpecFrame * Alignment occurs within the spectral system and standard of rest * given by attributes AlignSystem and AlignStdOfRest. * TimeFrame * Alignment occurs within the time system and time scale given by * attributes AlignSystem and AlignTimeScale. * Examples: c cvt = astConvert( a, b, "" ); f CVT = AST_CONVERT( A, B, ' ', STATUS ) * Attempts to convert between the coordinate systems represented c by "a" and "b" (assumed to be Frames). If successful, a FrameSet f by A and B (assumed to be Frames). If successful, a FrameSet c is returned via the "cvt" pointer which may be used to apply the f is returned via the CVT pointer which may be used to apply the c conversion to sets of coordinates (e.g. using astTran2). f conversion to sets of coordinates (e.g. using AST_TRAN2). c cvt = astConvert( astSkyFrame(""), astSkyFrame("Equinox=2005"), "" ); f CVT = AST_CONVERT( AST_SKYFRAME( ' ', STATUS ), AST_SKYFRAME( 'Equinox=2005', STATUS ), ' ', STATUS ) * Creates a FrameSet which describes precession in the default * FK5 celestial coordinate system between equinoxes J2000 (also c the default) and J2005. The returned "cvt" pointer may then f the default) and J2005. The returned CVT pointer may then c be passed to astTran2 to apply this precession correction to f be passed to AST_TRAN2 to apply this precession correction to * any number of coordinate values given in radians. * * Note that the returned FrameSet also contains information * about how to format coordinate values. This means that * setting its Report attribute to 1 is a simple way to obtain * printed output (formatted in sexagesimal notation) to show * the coordinate values before and after conversion. c cvt = astConvert( a, b, "sky,detector," ); f CVT = AST_CONVERT( A, B, 'SKY,DETECTOR,', STATUS ) * Attempts to convert between the coordinate systems c represented by the current Frames of "a" and "b" f represented by the current Frames of A and B * (now assumed to be FrameSets), via the intermediate "SKY" * coordinate system. This, by default, is the Domain * associated with a celestial coordinate system represented by * a SkyFrame. * * If this fails (for example, because either FrameSet lacks * celestial coordinate information), then the user-defined * "DETECTOR" coordinate system is used instead. If this also * fails, then all other possible ways of achieving conversion * are considered before giving up. * c The returned pointer "cvt" indicates whether conversion was f The returned pointer CVT indicates whether conversion was * possible and will have the value AST__NULL if it was not. If c conversion was possible, "cvt" will point at a new FrameSet f conversion was possible, CVT will point at a new FrameSet * describing the conversion. * * The Base attributes of the two FrameSets c will be set by astConvert to indicate which of their Frames was f will be set by AST_CONVERT to indicate which of their Frames was * used for the intermediate coordinate system. This means that * you can subsequently determine which coordinate system was * used by enquiring the Domain attribute of either base Frame. * Notes: * - The Mapping represented by the returned FrameSet results in * alignment taking place in the coordinate system specified by the c AlignSystem attribute of the "to" Frame. See the description of the f AlignSystem attribute of the TO Frame. See the description of the * AlignSystem attribute for further details. * - When aligning (say) two images, which have been calibrated by * attaching FrameSets to them, it is usually necessary to convert * between the base Frames (representing "native" pixel * coordinates) of both FrameSets. This may be achieved by * inverting the FrameSets (e.g. using astInvert) so as to * interchange their base and current Frames before using * astConvert. * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- * Implementation Notes: * This function is simply a wrap-up for the protected astConvertX * method which performs the required processing but swaps the order * of the first two arguments. This is a trick to allow the * astConvert method to be over-ridden by derived classes on the * basis of the class of either of the first two arguments. */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Invoke the "astConvertX" method with the first two arguments swapped. */ return astConvertX( to, from, domainlist ); } static AstFrameSet *ConvertX( AstFrame *to, AstFrame *from, const char *domainlist, int *status ) { /* *+ * Name: * astConvertX * Purpose: * Determine how to convert between two coordinate systems. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstFrameSet *astConvertX( AstFrame *to, AstFrame *from, * const char *domainlist ) * Class Membership: * Frame method. * Description: * This function performs the processing for the public astConvert * method and has exactly the same interface except that the order * of the first two arguments is swapped. This is a trick to allow * the astConvert method to be over-ridden by derived classes on * the basis of the class of either of its first two arguments. * * See the astConvert method for details of the interface. *- * Implementation Deficiencies: * - This function's job is basically to negotiate with two Frames * to try and find a mutually agreeable coordinate system for * conversion. Ideally, it should be able to juggle the number of * axes, etc. to do this. At present, however, the implementation * is much simpler. This is adequate for the Frame classes which * exist at the time of writing, but the implementation may need * beefing up in future. * - One likely problem is with attributes which default in both * the source and destination Frames. This means they also default * in the common coordinate system. If these default values were to * differ when matching different target Frames, however, we would * be in trouble, because the common coordinate system would not * then be remaining constant. The longer-term solution to this is * probably to provide some mechanism to "fix" all attribute values * for a Frame, by taking any attributes that are un-set and * explicitly setting a firm value (equal to the default) so they * cannot then change. */ /* Local Variables: */ AstFrameSet *result; /* Pointer to Mapping to be returned */ AstFrame *ftmp; /* Pointer to returned Frame */ AstMapping **map1_address; /* Location of first Mapping pointer */ AstMapping **map2_address; /* Location of second Mapping pointer */ AstMapping *common0; /* Initial common coordinate system */ AstMapping *common1; /* Improved common coordinate system */ AstMapping *common2; /* Final common coordinate system */ AstMapping *frame1; /* Pointer to Frame for first match */ AstMapping *frame2; /* Pointer to Frame for second match */ AstMapping *from_map; /* Pointer to "from" Mapping */ AstMapping *map; /* Pointer to conversion Mapping */ AstMapping *result_map; /* Pointer to result Mapping */ AstMapping *tmp; /* Temporary Mapping pointer */ AstMapping *to_map; /* Pointer to "to" Mapping */ char *domain; /* Pointer to result domain */ char *domain_end; /* Pointer to null at end of domain */ char *domainlist_copy; /* Pointer to copy of domainlist */ int *axes1; /* Pointer to axis assignments */ int *axes2; /* Pointer to axis assignments */ int best_score; /* Score assigned to best match */ int icom; /* Common coordinate system loop counter */ int match1; /* First match succeeded? */ int match2; /* Second match succeeded? */ int match; /* Overall match found? */ int perfect; /* Perfect match found? */ int score; /* Score assigned to match */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Further initialisation. */ result_map = NULL; /* Make a temporary copy of the domains list. */ domainlist_copy = astStore( NULL, domainlist, strlen( domainlist ) + (size_t) 1 ); if ( astOK ) { /* Loop to inspect each comma-separated field in the domains list until an error occurs, all the domains are used up, or a match is found. */ domain = domainlist_copy; match = 0; while ( astOK && domain && !match ) { /* Change the comma at the end of each field to a null to terminate the domain. Then convert the domain to upper case and eliminate white space. */ if ( ( domain_end = strchr( domain, ',' ) ) ) *domain_end = '\0'; CleanDomain( domain, status ); /* For any given domain, we will ignore imperfect matches in favour of better ones by assigning a score to each match. Initialise the best score value for the current domain. */ best_score = -1; /* Loop to consider both the "to" and "from" Frames in turn as the basis of a possible common coordinate system. Quit looping early if an error occurs or a perfect match is found. */ perfect = 0; for ( icom = 0; astOK && !perfect && ( icom <= 1 ); icom++ ) { /* Make a copy of the Frame representing the initial guess at a common coordinate system. We will use this to probe the other Frame. Ensure that axes are not preserved (so that we convert to the common axis number/order). */ common0 = astCopy( icom ? from : to ); astSetPreserveAxes( common0, 0 ); /* Also, if the current domain is not blank, set the Domain attribute (so we will only find coordinate systems which match the current "domainlist" field). */ if ( *domain ) astSetDomain( common0, domain ); /* Obtain a pointer to the other Frame. */ frame1 = astClone( icom ? to : from ); /* Set the address at which to store the resulting Mapping pointer. */ map1_address = icom ? &to_map : &from_map; /* See if conversion from "frame1" to the common coordinate system is possible. If successful, this results in a new approximation ("common1") to the possible common coordinate system. */ match1 = astMatch( common0, frame1, 1, &axes1, &axes2, map1_address, &ftmp ); common1 = (AstMapping *) ftmp; /* If successful, free memory allocated for the axis association arrays, which are not needed. */ if ( astOK && match1 ) { axes1 = astFree( axes1 ); axes2 = astFree( axes2 ); /* Using the improved approximation to the common coordinate system, now test if conversion from the alternative Frame "frame2" is possible. */ frame2 = astClone( icom ? from : to ); map2_address = icom ? &from_map : &to_map; astSetPreserveAxes( common1, 0 ); match2 = astMatch( common1, frame2, 1, &axes1, &axes2, map2_address, &ftmp ); common2 = (AstMapping *) ftmp; /* If successful, free memory allocated for the axis association arrays, which are not needed. */ if ( astOK && match2 ) { axes1 = astFree( axes1 ); axes2 = astFree( axes2 ); /* Invert the "to" Mapping and concatenate the two Mappings to describe the conversion between the "from" and "to" Frames. Then simplify the result. */ astInvert( to_map ); tmp = (AstMapping *) astCmpMap( from_map, to_map, 1, "", status ); map = astSimplify( tmp ); tmp = astAnnul( tmp ); /* Assign a score that favours Mappings with both transformations available over those with only one, and Mappings with only a forward transformation over those with only an inverse transformation. */ score = ( astGetTranForward( map ) ? 2 : 0 ) + ( astGetTranInverse( map ) ? 1 : 0 ); /* If the new score is better than the previous one (or is the first one), note that we have a possible match. */ if ( astOK && ( score > best_score ) ) { match = 1; /* Update the best score and note if it indicates a perfect match (in which case we can stop searching at this point). */ best_score = score; perfect = ( best_score >= 3 ); /* Annul any previous result Mapping pointer and replace it with this better one. */ if ( result_map ) result_map = astAnnul( result_map ); result_map = astClone( map ); } /* Annul pointers to all the intermediate Objects. */ map = astAnnul( map ); common2 = astAnnul( common2 ); *map2_address = astAnnul( *map2_address ); } frame2 = astAnnul( frame2 ); common1 = astAnnul( common1 ); *map1_address = astAnnul( *map1_address ); } frame1 = astAnnul( frame1 ); common0 = astAnnul( common0 ); } /* Go on to consider the next field in the domains list. */ domain = domain_end ? domain_end + 1 : NULL; } } /* Free the domain list copy. */ domainlist_copy = astFree( domainlist_copy ); /* If returning a result, build the result FrameSet. Then annul the result Mapping pointer. */ if ( result_map ) { result = astFrameSet( from, "", status ); astAddFrame( result, AST__BASE, result_map, to ); result_map = astAnnul( result_map ); } /* If an error occurred, annul the result FrameSet pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int DefaultMaxAxes( AstFrame *this, int *status ) { /* * Name: * DefaultMaxAxes * Purpose: * Obtain the MaxAxes attribute from a Frame structure, with defaulting. * Type: * Private function. * Synopsis: * #include "frame.h" * int DefaultMaxAxes( AstFrame *this, int *status ) * Class Membership: * Frame member function. * Description: * This function inspects the max_axes component of a Frame structure and * derives a value for the MaxAxes attribute. If the component's value * indicates that the attribute has not been set, a suitable default is * returned which is consistent with the state of the Frames's MinAxes * attribute. * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * The value to be used for the MaxAxes attribute. */ /* Local Variables. */ int result; /* Result to be returned */ int min_axes; /* Value of MinAxes attribute */ /* Check the global error status. */ if ( !astOK ) return 0; /* If the Frame's max_axes component is set, return its value. */ if ( this->max_axes != -INT_MAX ) { result = this->max_axes; /* Otherwise, the preferred default value is the number of Frame axes. */ } else { result = astGetNaxes( this ); /* Before returning this value, check if the MinAxes attribute is set. If it is, obtain its value. */ if ( astTestMinAxes( this ) ) { min_axes = astGetMinAxes( this ); /* If necessary, increase the MaxAxes default value so that it is not less than MinAxes. */ if ( result < min_axes ) result = min_axes; } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static int DefaultMinAxes( AstFrame *this, int *status ) { /* * Name: * DefaultMinAxes * Purpose: * Obtain the MinAxes attribute from a Frame structure, with defaulting. * Type: * Private function. * Synopsis: * #include "frame.h" * int DefaultMinAxes( AstFrame *this, int *status ) * Class Membership: * Frame member function. * Description: * This function inspects the min_axes component of a Frame structure and * derives a value for the MinAxes attribute. If the component's value * indicates that the attribute has not been set, a suitable default is * returned which is consistent with the state of the Frames's MaxAxes * attribute. * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * The value to be used for the MinAxes attribute. */ /* Local Variables: */ int result; /* Result to be returned */ int max_axes; /* Value of MaxAxes attribute */ /* Check the global error status. */ if ( !astOK ) return 0; /* If the Frame's min_axes component is set, return its value. */ if ( this->min_axes != -INT_MAX ) { result = this->min_axes; /* Otherwise, the preferred default value is the number of Frame axes. */ } else { result = astGetNaxes( this ); /* Before returning this value, check if the MaxAxes attribute is set. If it is, obtain its value. */ if ( astTestMaxAxes( this ) ) { max_axes = astGetMaxAxes( this ); /* If necessary, reduce the MinAxes default value so that it does not exceed MaxAxes. */ if ( result > max_axes ) result = max_axes; } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static double Distance( AstFrame *this, const double point1[], const double point2[], int *status ) { /* *++ * Name: c astDistance f AST_DISTANCE * Purpose: * Calculate the distance between two points in a Frame. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astDistance( AstFrame *this, c const double point1[], const double point2[] ) f RESULT = AST_DISTANCE( THIS, POINT1, POINT2, STATUS ) * Class Membership: * Frame method. * Description: * This function finds the distance between two points whose Frame * coordinates are given. The distance calculated is that along * the geodesic curve that joins the two points. * * For example, in a basic Frame, the distance calculated will be * the Cartesian distance along the straight line joining the two * points. For a more specialised Frame describing a sky coordinate * system, however, it would be the distance along the great circle * passing through two sky positions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c point1 f POINT1( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute) containing the coordinates of the first point. c point2 f POINT2( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * containing the coordinates of the second point. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astDistance f AST_DISTANCE = DOUBLE PRECISION * The distance between the two points. * Notes: * - This function will return a "bad" result value (AST__BAD) if * any of the input coordinates has this value. * - A "bad" value will also be returned if this function is c invoked with the AST error status set, or if it should fail for f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- */ /* Local Variables: */ double delta; /* Separation along an axis */ double result; /* Result value to return */ int axis; /* Loop counter for axes */ int naxes; /* Number of Frame axes */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); if ( astOK ) { /* Loop to determine the Cartesian distance between the points. */ result = 0.0; for ( axis = 0; axis < naxes; axis++ ) { /* If any of the coordinates supplied is bad, set the distance to be bad and quit looping. */ if ( ( point1[ axis ] == AST__BAD ) || ( point2[ axis ] == AST__BAD ) ) { result = AST__BAD; break; /* Otherwise, accumulate the sum of squared separations along each axis. */ } else { delta = point1[ axis ] - point2[ axis ]; result += ( delta * delta ); } } /* Take the square root to find the distance (if valid). */ if ( result != AST__BAD ) result = sqrt( result ); } /* Return the result. */ return result; } static int DoNotSimplify( AstMapping *this, int *status ) { /* * Name: * DoNotSimplify * Purpose: * Check if a Mapping is appropriate for simplification. * Type: * Private function. * Synopsis: * #include "object.h" * int DoNotSImplify( AstMapping *this ); * Class Membership: * CmpMap member function (over-rides the astDoNotSimplify protected * method inherited from the parent class). * Description: * This function returns a flag indivating if the supplied Mapping is * appropriate for simplification. * Parameters: * this * Pointer to the Mapping. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the supplied Mapping is not appropriate for * simplification, and zero otherwise. * Notes: * - A value of 0 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Unlike basic Mappings, Frames that have a set value for the Ident can be simplified. So always return zero. */ return 0; } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two Frames are equivalent. * Type: * Private function. * Synopsis: * #include "frame.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * Frame member function (over-rides the astEqual protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two Frames are equivalent. * Parameters: * this * Pointer to the first Frame. * that * Pointer to the second Frame. * status * Pointer to the inherited status variable. * Returned Value: * One if the Frames are equivalent, zero otherwise. * Notes: * - The two Frames are considered equivalent if the Mapping between * them is a UnitMap. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstFrame *that; /* Pointer to the second Frame structure */ AstFrame *this; /* Pointer to the first Frame structure */ AstFrameSet *fs; /* FrameSet connecting the two Frames */ AstMapping *map1; /* Mapping connecting the two Frames */ AstMapping *map2; /* Simplified mapping connecting two Frames */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Checks that the second object is of the same class as the first . */ if( !strcmp( astGetClass( this_object ), astGetClass( that_object ) ) ){ /* Obtain pointers to the two Frame structures. */ this = (AstFrame *) this_object; that = (AstFrame *) that_object; /* Get the Mapping between them, and see if it is a UnitMap. */ fs = astConvert( that, this, "" ); if( fs ) { map1 = astGetMapping( fs, AST__BASE, AST__CURRENT ); map2 = astSimplify( map1 ); result = astIsAUnitMap( map2 ); map1 = astAnnul( map1 ); map2 = astAnnul( map2 ); fs = astAnnul( fs ); } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int Fields( AstFrame *this, int axis, const char *fmt, const char *str, int maxfld, char **fields, int *nc, double *val, int *status ) { /* *+ * Name: * astFields * Purpose: * Identify numerical fields within a formatted Axis value. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astFields( AstFrame *this, int axis, const char *fmt, * const char *str, int maxfld, char **fields, * int *nc, double *val ) * Class Membership: * Frame method. * Description: * This function identifies the numerical fields within a Frame axis * value that has been formatted using astAxisFormat. It assumes that * the value was formatted using the supplied format string. It also * returns the equivalent floating point value. * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which the values have been * formatted (axis numbering starts at zero for the first axis). * fmt * Pointer to a constant null-terminated string containing the * format used when creating "str". * str * Pointer to a constant null-terminated string containing the * formatted value. * maxfld * The maximum number of fields to identify within "str". * fields * A pointer to an array of at least "maxfld" character pointers. * Each element is returned holding a pointer to the start of the * corresponding field in "str" (in the order in which they occur * within "str"), or NULL if no corresponding field can be found. * nc * A pointer to an array of at least "maxfld" integers. Each * element is returned holding the number of characters in the * corresponding field, or zero if no corresponding field can be * found. * val * Pointer to a location at which to store the value * equivalent to the returned field values. If this is NULL, * it is ignored. * Returned Value: * The number of fields succesfully identified and returned. * Notes: * - Leading and trailing spaces are ignored. * - If the formatted value is not consistent with the supplied format * string, then a value of zero will be returned, "fields" will be * returned holding NULLs, "nc" will be returned holding zeros, and * "val" is returned holding VAL__BAD. * - Fields are counted from the start of the formatted string. If the * string contains more than "maxfld" fields, then trailing fields are * ignored. * - If this function is invoked with the global error status set, or * if it should fail for any reason, then a value of zero will be returned * as the function value, and "fields", "nc" and "val" will be returned * holding their supplied values *- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ int result; /* Result field count to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astFields" ); ax = astGetAxis( this, axis ); /* Invoke the Axis astAxisFields method to perform the processing. */ result = astAxisFields( ax, fmt, str, maxfld, fields, nc, val ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the returned value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static AstFrameSet *FindFrame( AstFrame *target, AstFrame *template, const char *domainlist, int *status ) { /* *++ * Name: c astFindFrame f AST_FINDFRAME * Purpose: * Find a coordinate system with specified characteristics. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c AstFrameSet *astFindFrame( AstFrame *target, AstFrame *template, c const char *domainlist ) f RESULT = AST_FINDFRAME( TARGET, TEMPLATE, DOMAINLIST, STATUS ) * Class Membership: * Frame method. * Description: * This function uses a "template" Frame to search another Frame * (or FrameSet) to identify a coordinate system which has a * specified set of characteristics. If a suitable coordinate * system can be found, the function returns a pointer to a * FrameSet which describes the required coordinate system and how * to convert coordinates to and from it. * * This function is provided to help answer general questions about * coordinate systems, such as typically arise when coordinate * information is imported into a program as part of an initially * unknown dataset. For example: * - Is there a wavelength scale? * - Is there a 2-dimensional coordinate system? * - Is there a celestial coordinate system? * - Can I plot the data in ecliptic coordinates? * * You can also use this function as a means of reconciling a * user's preference for a particular coordinate system (for * example, what type of axes to draw) with what is actually * possible given the coordinate information available. * * To perform a search, you supply a "target" Frame (or FrameSet) * which represents the set of coordinate systems to be searched. * If a basic Frame is given as the target, this set of coordinate * systems consists of the one described by this Frame, plus all * other "virtual" coordinate systems which can potentially be * reached from it by applying built-in conversions (for example, * any of the celestial coordinate conversions known to the AST * library would constitute a "built-in" conversion). If a FrameSet * is given as the target, the set of coordinate systems to be * searched consists of the union of those represented by all the * individual Frames within it. * * To select from this large set of possible coordinate systems, * you supply a "template" Frame which is an instance of the type * of Frame you are looking for. Effectively, you then ask the * function to "find a coordinate system that looks like this". * * You can make your request more or less specific by setting * attribute values for the template Frame. If a particular * attribute is set in the template, then the function will only * find coordinate systems which have exactly the same value for * that attribute. If you leave a template attribute un-set, * however, then the function has discretion about the value the * attribute should have in any coordinate system it finds. The * attribute will then take its value from one of the actual * (rather than virtual) coordinate systems in the target. If the * target is a FrameSet, its Current attribute will be modified to * indicate which of its Frames was used for this purpose. * * The result of this process is a coordinate system represented by * a hybrid Frame which acquires some attributes from the template * (but only if they were set) and the remainder from the * target. This represents the "best compromise" between what you * asked for and what was available. A Mapping is then generated * which converts from the target coordinate system to this hybrid * one, and the returned FrameSet encapsulates all of this * information. * Parameters: c target f TARGET = INTEGER (Given) * Pointer to the target Frame (or FrameSet). * * Note that if a FrameSet is supplied (and a suitable * coordinate system is found), then its Current attribute will * be modified to indicate which Frame was used to obtain * attribute values which were not specified by the template. * This Frame will, in some sense, represent the "closest" * non-virtual coordinate system to the one you requested. c template f TEMPLATE = INTEGER (Given) * Pointer to the template Frame, which should be an instance of * the type of Frame you wish to find. If you wanted to find a * Frame describing a celestial coordinate system, for example, * then you might use a SkyFrame here. See the "Examples" * section for more ideas. c domainlist f DOMAINLIST = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string containing a f A character string containing a * comma-separated list of Frame domains. This may be used to * establish a priority order for the different types of * coordinate system that might be found. * * The function will first try to find a suitable coordinate * system whose Domain attribute equals the first domain in this * list. If this fails, the second domain in the list will be * used, and so on, until a result is obtained. A blank domain * (e.g. two consecutive commas) indicates that any coordinate * system is acceptable (subject to the template) regardless of * its domain. * * This list is case-insensitive and all white space is ignored. * If you do not wish to restrict the domain in this way, c you should supply an empty string. f you should supply a blank string. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astFindFrame() f AST_FINDFRAME = INTEGER * If the search is successful, the function returns a pointer * to a FrameSet which contains the Frame found and a * description of how to convert to (and from) the coordinate * system it represents. Otherwise, a null Object pointer * (AST__NULL) is returned without error. * * If a FrameSet is returned, it will contain two Frames. Frame * number 1 (its base Frame) represents the target coordinate * system and will be the same as the (base Frame of the) * target. Frame number 2 (its current Frame) will be a Frame * representing the coordinate system which the function * found. The Mapping which inter-relates these two Frames will * describe how to convert between their respective coordinate * systems. * * Note that a FrameSet may be used both as a Mapping and as a * Frame. If the result is used as a Mapping (e.g. with * astTran2), then it provides a means of converting coordinates * from the target coordinate system into the new coordinate * system that was found (and vice versa if its inverse * transformation is selected). If it is used as a Frame, its * attributes will describe the new coordinate system. * Applicability: * Frame * This function applies to all Frames. * FrameSet * If the target is a FrameSet, the possibility exists that * several of the Frames within it might be matched by the * template. Unless the choice is sufficiently restricted by c the "domainlist" string, the sequence in which Frames are f the DOMAINLIST string, the sequence in which Frames are * searched can then become important. In this case, the search * proceeds as follows: c - Each field in the "domainlist" string is considered in turn. f - Each field in the DOMAINLIST string is considered in turn. * - An attempt is made to match the template to each of the * target's Frames in the order: (1) the current Frame, (2) the * base Frame, (3) each remaining Frame in the order of being * added to the target FrameSet. * - Generally, the first match found is used. However, the * Mapping between the target coordinate system and the * resulting Frame is also examined. Preference is given to * cases where both the forward and inverse transformations are * defined (as indicated by the TranForward and TranInverse * attributes). If only one transformation is defined, the * forward one is preferred. * - If a match is found and the domain of the resulting Frame also c matches the current "domainlist" field, it is f matches the current DOMAINLIST field, it is c accepted. Otherwise, the next "domainlist" field is considered f accepted. Otherwise, the next DOMAINLIST field is considered * and the process repeated. * * If a suitable coordinate system is found, the Current * attribute of the target FrameSet will be modified on exit to * identify the Frame whose match with the target was eventually * accepted. * Examples: c result = astFindFrame( target, astFrame( 3, "" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 3, ' ', STATUS ), ' ', STATUS ) * Searches for a 3-dimensional coordinate system in the target * Frame (or FrameSet). No attributes have been set in the c template Frame (created by astFrame), so no restriction has f template Frame (created by AST_FRAME), so no restriction has * been placed on the required coordinate system, other than * that it should have 3 dimensions. The first suitable Frame c found will be returned as part of the "result" FrameSet. f found will be returned as part of the RESULT FrameSet. c result = astFindFrame( target, astSkyFrame( "" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( ' ', STATUS ), ' ', STATUS ) * Searches for a celestial coordinate system in the target * Frame (or FrameSet). The type of celestial coordinate system c is unspecified, so astFindFrame will return the first one f is unspecified, so AST_FINDFRAME will return the first one c found as part of the "result" FrameSet. If the target is f found as part of the RESULT FrameSet. If the target is * a FrameSet, then its Current attribute will be updated to * identify the Frame that was used. * * If no celestial coordinate system can be found, a value of * AST__NULL will be returned without error. c result = astFindFrame( target, astSkyFrame( "MaxAxes=100" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'MaxAxes=100', STATUS ), ' ', STATUS ) * This is like the last example, except that in the event of the * target being a CmpFrame, the component Frames encapsulated by the * CmpFrame will be searched for a SkyFrame. If found, the returned * Mapping will included a PermMap which selects the required axes * from the target CmpFrame. * * This is acomplished by setting the MaxAxes attribute of the * template SkyFrame to a large number (larger than or equal to the * number of axes in the target CmpFrame). This allows the SkyFrame * to be used as a match for Frames containing from 2 to 100 axes. c result = astFindFrame( target, astSkyFrame( "System=FK5" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'System=FK5', STATUS ), ' ', STATUS ) * Searches for an equatorial (FK5) coordinate system in the * target. The Equinox value for the coordinate system has not * been specified, so will be obtained from the target. If the * target is a FrameSet, its Current attribute will be updated * to indicate which SkyFrame was used to obtain this value. c result = astFindFrame( target, astFrame( 2, "" ), "sky,pixel," ); f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 2, ' ', STATUS ), 'SKY,PIXEL,', STATUS ) * Searches for a 2-dimensional coordinate system in the * target. Initially, a search is made for a suitable coordinate * system whose Domain attribute has the value "SKY". If this * search fails, a search is then made for one with the domain * "PIXEL". If this also fails, then any 2-dimensional c coordinate system is returned as part of the "result" f coordinate system is returned as part of the RESULT * FrameSet. * * Only if no 2-dimensional coordinate systems can be reached by * applying built-in conversions to any of the Frames in the * target will a value of AST__NULL be returned. c result = astFindFrame( target, astFrame( 1, "Domain=WAVELENGTH" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, 'Domain=WAVELENGTH', STATUS ), ' ', STATUS ) * Searches for any 1-dimensional coordinate system in the * target which has the domain "WAVELENGTH". c result = astFindFrame( target, astFrame( 1, "" ), "wavelength" ); f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, ' ', STATUS ), 'WAVELENGTH', STATUS ) * This example has exactly the same effect as that above. It * illustrates the equivalence of the template's Domain attribute c and the fields in the "domainlist" string. f and the fields in the DOMAINLIST string. c result = astFindFrame( target, astFrame( 1, "MaxAxes=3" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, 'MaxAxes=3', STATUS ), ' ', STATUS ) * This is a more advanced example which will search for any * coordinate system in the target having 1, 2 or 3 c dimensions. The Frame returned (as part of the "result" f dimensions. The Frame returned (as part of the RESULT * FrameSet) will always be 1-dimensional, but will be related * to the coordinate system that was found by a suitable Mapping * (e.g. a PermMap) which simply extracts the first axis. * * If we had wanted a Frame representing the actual (1, 2 or * 3-dimensional) coordinate system found, we could set the * PreserveAxes attribute to a non-zero value in the template. c result = astFindFrame( target, astSkyFrame( "Permute=0" ), "" ); f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'Permute=0', STATUS ), ' ', STATUS ) * Searches for any celestial coordinate system in the target, * but only finds one if its axes are in the conventional * (longitude,latitude) order and have not been permuted c (e.g. with astPermAxes). f (e.g. with AST_PERMAXES). * Notes: * - The Mapping represented by the returned FrameSet results in * alignment taking place in the coordinate system specified by the c AlignSystem attribute of the "template" Frame. See the description f AlignSystem attribute of the TEMPLATE Frame. See the description * of the AlignSystem attribute for further details. * - Beware of setting the Domain attribute of the template and then c using a "domainlist" string which does not include the template's domain f using a DOMAINLIST string which does not include the template's domain * (or a blank field). If you do so, no coordinate system will be * found. * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. * More on Using Templates: * A Frame (describing a coordinate system) will be found by this * function if (a) it is "matched" by the template you supply, and c (b) the value of its Domain attribute appears in the "domainlist" f (b) the value of its Domain attribute appears in the DOMAINLIST * string (except that a blank field in this string permits any * domain). A successful match by the template depends on a number * of criteria, as outlined below: * - In general, a template will only match another Frame which * belongs to the same class as the template, or to a derived (more * specialised) class. For example, a SkyFrame template will match * any other SkyFrame, but will not match a basic * Frame. Conversely, a basic Frame template will match any class * of Frame. * - The exception to this is that a Frame of any class can be used to * match a CmpFrame, if that CmpFrame contains a Frame of the same * class as the template. Note however, the MaxAxes and MinAxes * attributes of the template must be set to suitable values to allow * it to match the CmpFrame. That is, the MinAxes attribute must be * less than or equal to the number of axes in the target, and the MaxAxes * attribute must be greater than or equal to the number of axes in * the target. * - If using a CmpFrame as a template frame, the MinAxes and MaxAxes * for the template are determined by the MinAxes and MaxAxes values of * the component Frames within the template. So if you want a template * CmpFrame to be able to match Frames with different numbers of axes, * then you must set the MaxAxes and/or MinAxes attributes in the component * template Frames, before combining them together into the template * CmpFrame. * - If a template has a value set for any of its main attributes, then * it will only match Frames which have an identical value for that * attribute (or which can be transformed, using a built-in * conversion, so that they have the required value for that * attribute). If any attribute in the template is un-set, however, * then Frames are matched regardless of the value they may have * for that attribute. You may therefore make a template more or * less specific by choosing the attributes for which you set * values. This requirement does not apply to 'descriptive' attributes * such as titles, labels, symbols, etc. * - An important application of this principle involves the Domain * attribute. Setting the Domain attribute of the template has the * effect of restricting the search to a particular type of Frame * (with the domain you specify). Conversely, if the Domain * attribute is not set in the template, then the domain of the * Frame found is not relevant, so all Frames are searched. Note * that the c "domainlist" string provides an alternative way of restricting the f DOMAINLIST string provides an alternative way of restricting the * search in the same manner, but is a more convenient interface if * you wish to search automatically for another domain if the first * search fails. * - Normally, a template will only match a Frame which has the * same number of axes as itself. However, for some classes of * template, this default behaviour may be changed by means of the * MinAxes, MaxAxes and MatchEnd attributes. In addition, the * behaviour of a template may be influenced by its Permute and * PreserveAxes attributes, which control whether it matches Frames * whose axes have been permuted, and whether this permutation is * retained in the Frame which is returned (as opposed to returning * the axes in the order specified in the template, which is the * default behaviour). You should consult the descriptions of these * attributes for details of this more advanced use of templates. *-- */ /* Local Variables: */ AstFrame *frame; /* Pointer to result Frame */ AstFrameSet *result; /* Pointer to result FrameSet */ AstMapping *map; /* Pointer to result Mapping */ AstMapping *tmp; /* Temporary Mapping pointer */ char *domain_copy; /* Pointer to copy of result domain */ char *domainlist_copy; /* Pointer to copy of domains list */ const char *domain; /* Pointer to result Domain value */ int *target_axes; /* Pointer to target axis assignments */ int *template_axes; /* Pointer to template axis assignments */ int i; /* Loop counter for characters */ int j; /* Character index */ int match; /* Template matched target? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate space to store a copy of the domains list, with added commas. */ domainlist_copy = astMalloc( strlen( domainlist ) + (size_t) 3 ); if ( astOK ) { /* Make a copy of the domains list, with an extra comma added at each end. Also remove all white space and convert to upper case. */ domainlist_copy[ 0 ] = ','; for ( i = 0, j = 1; domainlist[ i ]; i++ ) { if ( !isspace( domainlist[ i ] ) ) { domainlist_copy[ j++ ] = toupper( domainlist[ i ] ); } } domainlist_copy[ j++ ] = ','; domainlist_copy[ j ] = '\0'; /* Invoke the protected astMatch method associated with the template Frame. This matches the template to the target and returns information about how to convert between the target and the Frame it found (if any). */ match = astMatch( template, target, 0, &template_axes, &target_axes, &map, &frame ); /* If successful, obtain a pointer to the Domain string of the result Frame. Allocate space for a copy of this string, with added commas. */ if ( match && astOK ) { domain = astGetDomain( frame ); if ( astOK ) { domain_copy = astMalloc( strlen( domain ) + (size_t) 3 ); if ( astOK ) { /* Make a copy of the domain, adding an extra comma at each end. */ domain_copy[ 0 ] = ','; for ( i = 0, j = 1; domain[ i ]; i++ ) { domain_copy[ j++ ] = domain[ i ]; } domain_copy[ j++ ] = ','; domain_copy[ j ] = '\0'; /* Test if the domain appears in the domains list (with added commas). If not, test if a blank domain (which permits the result Frame to have any Domain) appears instead. */ if ( strstr( domainlist_copy, domain_copy ) || strstr( domainlist_copy, ",," ) ) { /* If the result Frame is acceptable, simplify the result Mapping. */ tmp = astSimplify( map ); map = astAnnul( map ); map = tmp; /* Build the result FrameSet. */ result = astFrameSet( target, "", status ); astAddFrame( result, AST__BASE, map, frame ); } } /* Free the copy of the result domain. */ domain_copy = astFree( domain_copy ); } /* Free space and annul pointers allocated by astMatch. */ template_axes = astFree( template_axes ); target_axes = astFree( target_axes ); map = astAnnul( map ); frame = astAnnul( frame ); } } /* Free the copy of the domains list. */ domainlist_copy = astFree( domainlist_copy ); /* If an error occurred, annul any result pointer. */ if ( !astOK && result ) result = astAnnul( result ); /* Return the result. */ return result; } const char *astFmtDecimalYr_( double year, int digits, int *status ) { /* *+ * Name: * astFmtDecimalYr * Purpose: * Format an epoch expressed in years as a decimal string. * Type: * Protected function. * Synopsis: * #include "frame.h" * const char *astFmtDecimalYr( double year, int digits ) * Class Membership: * Frame member function. * Description: * This function formats an epoch expressed in years as a decimal string * and returns a pointer to the result. It is intended for formatting * Frame Epoch values, etc, for display. * Parameters: * year * The epoch to be formatted. * digits * The number of digits of precision required. * Returned Value: * Pointer to a null terminated string containing the formatted value. * Notes: * - The result string is stored in static memory and may be * over-written by a subsequent invocation of this function. * - A NULL pointer is returned if this function is invoked with * the global error status set or if it should fail for any reason. *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ int nc; /* Number of characters in buffer */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* Limit the precision to what is meaningful. */ digits = ( digits > DBL_DIG ) ? DBL_DIG : digits; /* Format the year value. Use "g" format to avoid buffer overflow and to get useful diagnostic output if a silly value is given. */ nc = sprintf( astfmtdecimalyr_buff, "%#.*g", digits, year ); /* Loop to remove redundant zeros from the end of the result. */ while ( astfmtdecimalyr_buff[ --nc ] == '0' ) astfmtdecimalyr_buff[ nc ] = '\0'; /* If the last character is now a decimal point, put back one zero. */ if ( astfmtdecimalyr_buff[ nc ] == '.' ) { astfmtdecimalyr_buff[ ++nc ] = '0'; astfmtdecimalyr_buff[ ++nc ] = '\0'; } /* Return the result. */ return astfmtdecimalyr_buff; } static const char *Format( AstFrame *this, int axis, double value, int *status ) { /* *+ * Name: * astFormat * Purpose: * Format a coordinate value for a Frame axis. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * const char *astFormat( AstFrame *this, int axis, double value ) * Class Membership: * Frame method. * Description: * This function returns a pointer to a string containing the * formatted (character) version of a coordinate value for a Frame * axis. The formatting applied is determined by the Frame's * attributes and, in particular, by any Format attribute string * that has been set for the axis. A suitable default format will * be applied if necessary. * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which formatting is to be * performed (axis numbering starts at zero for the first axis). * value * The coordinate value to be formatted. * Returned Value: * A pointer to a null-terminated string containing the formatted * value. * Notes: * - The returned string pointer may point at memory allocated * within the Frame, or at static memory. The contents of the * string may be over-written or the pointer may become invalid * following a further invocation of the same function or any * modification of the Frame. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- * Implementation Notes: * - This function implements the basic astFormat method available * via the protected interface to the Frame class. The public * interface to this method is provided by the astFormatId_ * function. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ const char *result; /* Pointer value to return */ int digits_set; /* Axis Digits attribute set? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astFormat" ); ax = astGetAxis( this, axis ); /* Test if any Axis attributes which may affect the result are undefined (i.e. have not been explicitly set). If so, we over-ride them, giving them temporary values dictated by the Frame. Only the Digits attribute is relevant here. */ digits_set = astTestAxisDigits( ax ); if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); /* Format the value. */ result = astAxisFormat( ax, value ); /* Clear any Axis attributes that were temporarily over-ridden. */ if ( !digits_set ) astClearAxisDigits( ax ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static AstPointSet *FrameGrid( AstFrame *this, int size, const double *lbnd, const double *ubnd, int *status ){ /* *+ * Name: * astFrameGrid * Purpose: * Return a grid of points covering a rectangular area of a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstPointSet *astFrameGrid( AstFrame *this_frame, int size, * const double *lbnd, const double *ubnd ) * Class Membership: * Frame method. * Description: * This function returns a PointSet containing positions spread * approximately evenly throughtout a specified rectangular area of * the Frame. * Parameters: * this * Pointer to the Frame. * size * The preferred number of points in the returned PointSet. The * actual number of points in the returned PointSet may be * different, but an attempt is made to stick reasonably closely to * the supplied value. * lbnd * Pointer to an array holding the lower bound of the rectangular * area on each Frame axis. The array should have one element for * each Frame axis. * ubnd * Pointer to an array holding the upper bound of the rectangular * area on each Frame axis. The array should have one element for * each Frame axis. * Returned Value: * A pointer to a new PointSet holding the grid of points. * Notes: * - A NULL pointer is returned if an error occurs. *- */ /* Local Variables: */ AstPointSet *result; const char *unit; double **ptr; double *gmean; double *step; int *maxi; int *nsame; int *ntick; int *pi; int bad; int iax; int ipp; int jax; int naxes; int np; int ntick0; /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get the number of axes in the Frame. */ naxes = astGetNaxes( this ); /* Allocate an array to hold the number of ticks along each axis. */ ntick = astMalloc( sizeof(int)*naxes ); /* Allocate an array to hold the geometric mean of the lengths of the axes that have the same units as the current axis. */ gmean = astMalloc( naxes*sizeof(double) ); /* Allocate an array to hold the number of axes that share the same unit. */ nsame = astMalloc( naxes*sizeof(int) ); if( astOK ) { /* For each axis, find the total number of axes in the Frame that have the same unit string. Also, find the product of the lengths of these axes. */ bad = 0; for( iax = 0; iax < naxes; iax++ ) { nsame[ iax ] = 1; if( ubnd[ iax ] == AST__BAD && lbnd[ iax ] == AST__BAD ) { bad = 1; break; } gmean[ iax ] = ubnd[ iax ] - lbnd[ iax ]; unit = astGetUnit( this, iax ); for( jax = 0; jax < naxes; jax++ ) { if( jax != iax ) { if( astOK && !strcmp( unit, astGetUnit( this, jax ) ) ) { nsame[ iax ]++; gmean[ iax ] *= ubnd[ jax ] - lbnd[ jax ]; } } } } /* Do nothing if any bad bounds were supplied, or if the size is less than 1. */ if( !bad && size >= 1 ) { /* Get the nominal number of ticks per axis. */ ntick0 = pow( size, 1.0/(double)naxes ); if( ntick0 < 2 ) ntick0 = 2; /* Convert the dimension products into geometric means. */ for( iax = 0; iax < naxes; iax++ ) { gmean[ iax ] = pow( fabs(gmean[ iax ]), 1.0/(double)nsame[ iax ] ); } /* The number of ticks to use on each axis is equal to the nominal number multiplied by the ratio of the axis length to the geometric mean of the axis lengths that sahare the same unit string. This gives more ticks on the longer axes within any group of common-unit axes, whilst retaining the overall number of ticks (roughly). Also find the total number of points. */ np = 1; for( iax = 0; iax < naxes; iax++ ) { ntick[ iax ] = ntick0*( ubnd[ iax ] - lbnd[ iax ] )/gmean[ iax ]; if( ntick[ iax ] < 2 ) ntick[ iax ] = 2; np *= ntick[ iax ]; } /* Create a PointSet large enough to hold this many points. */ result = astPointSet( np, naxes, " ", status ); ptr = astGetPoints( result ); /* Allocate memory to hold the max indices on each axis. */ maxi = astMalloc( sizeof( int )*(size_t) naxes ); /* Allocate memory to hold the indices of the current position.*/ pi = astMalloc( sizeof( int )*(size_t) naxes ); /* Allocate memory to hold the step size for each axis. */ step = astMalloc( sizeof( double )*(size_t) naxes ); if( astOK ) { /* For every axis, set up the step size, initialise the current position to the lower bound, and store a modified upper limit which includes some safety marging to allow for rounding errors. */ for( iax = 0; iax < naxes; iax++ ) { step[ iax ] = ( ubnd[ iax ] - lbnd[ iax ] )/( ntick[ iax ] - 1 ); pi[ iax ] = 0; maxi[ iax ] = ntick[ iax ] - 1; } /* Initialise the index of the next position to store. */ ipp = 0; /* Loop round adding points to the array until the whole volume has been done. */ iax = 0; while( iax < naxes ) { /* Add the current point to the supplied array, and increment the index of the next point to add. */ for( iax = 0; iax < naxes; iax++ ) { ptr[ iax ][ ipp ] = lbnd[ iax ] + pi[ iax ]*step[ iax ]; } ipp++; /* We now move the current position on to the next sample */ iax = 0; while( iax < naxes ) { pi[ iax ]++; if( pi[ iax ] > maxi[ iax ] ) { pi[ iax ] = 0; iax++; } else { break; } } } } /* Free resources. */ maxi = astFree( maxi ); pi = astFree( pi ); step = astFree( step ); /* Report error if supplied values were bad. */ } else if( astOK ) { if( bad ) { astError( AST__ATTIN, "astFrameGrid(%s): One of more of the " "supplied bounds is AST__BAD (programming error).", status, astGetClass( this ) ); } else if( size < 1 ) { astError( AST__ATTIN, "astFrameGrid(%s): The supplied grid " "size (%d) is invalid (programming error).", status, astGetClass( this ), size ); } } } /* Free resources. */ ntick = astFree( ntick ); nsame = astFree( nsame ); gmean = astFree( gmean ); /* Annul the returned PointSet if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the PointSet holding the grid. */ return result; } static double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) { /* *+ * Name: * astGap * Purpose: * Find a "nice" gap for tabulating Frame axis values. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * double astGap( AstFrame *this, int axis, double gap, int *ntick ) * Class Membership: * Frame method. * Description: * This function returns a gap size which produces a nicely spaced * series of formatted values for a Frame axis, the returned gap * size being as close as possible to the supplied target gap * size. It also returns a convenient number of divisions into * which the gap can be divided. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which a gap is to be found. * gap * The target gap size. * ntick * Address of an int in which to return a convenient number of * divisions into which the gap can be divided. * Returned Value: * The nice gap size. * Notes: * - A value of zero is returned if the target gap size is zero. * - A negative gap size is returned if the supplied gap size is negative. * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ double result; /* The nice gap value */ /* Check the global error status. */ if ( !astOK ) return 0.0; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astGap" ); ax = astGetAxis( this, axis ); /* Find the gap. */ result = astAxisGap( ax, gap, ntick ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0.0; /* Return the result. */ return result; } static int GetActiveUnit( AstFrame *this, int *status ){ /* *++ * Name: c astGetActiveUnit f AST_GETACTIVEUNIT * Purpose: * Determines how the Unit attribute will be used. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c int astGetActiveUnit( AstFrame *this ) f RESULT = AST_GETACTIVEUNIT( THIS, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * returns the current value of the ActiveUnit flag for a Frame. See c the description of the astSetActiveUnit function f the description of the AST_SETACTIVEUNIT routine * for a description of the ActiveUnit flag. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astGetActiveUnit f AST_GETACTIVEUNIT = LOGICAL * The current value of the ActiveUnit flag. * Notes: c - A zero value will be returned if this function is c invoked with the AST error status set, or if it should fail for f - A value of .FALSE. will be returned if this function is f invoked with STATUS set to an error value, or if it should fail for * any reason. *-- */ /* Local Variables: */ AstAxis *ax; /* Pointer to axis structure */ int i; /* Index of axis in Frame */ int has_skyaxis; /* Does Frame contain any SkyAxes? */ int nax; /* Number of axes in Frame */ int result; /* The returned value */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* See if the Frame contains a SkyAxis. */ has_skyaxis = 0; nax = astGetNaxes( this ); for( i = 0; i < nax; i++ ) { ax = astGetAxis( this, i ); if( astIsASkyAxis( ax ) ) has_skyaxis = 1; ax = astAnnul( ax ); } /* If the Frame contains a SkyAxis the ActiveUnit flag is always zero. */ if( !has_skyaxis ) { /* Otherwise, get the value from the Frame. If it has not yet been assigned a value return the value zero. */ result = this->active_unit; if( result == -INT_MAX ) result = 0; } /* Return the result. */ return result; } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Frame member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a Frame, formatted as a character string. * Parameters: * this * Pointer to the Frame. * attrib * Pointer to a null-terminated string containing the name of * the attribute whose value is required. This name should be in * lower case, with all white space removed. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a null-terminated string containing the attribute * value. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - The returned string pointer may point at memory allocated * within the Frame, or at static memory. The contents of the * string may be over-written or the pointer may become invalid * following a further invocation of the same function or any * modification of the Frame. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ AstAxis *ax; /* Pointer to Axis */ AstFrame *pfrm; /* Pointer to primary Frame containing axis */ AstFrame *this; /* Pointer to the Frame structure */ AstSystemType system; /* System code */ char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ char *axis_attrib; /* Pointer to axis attribute name */ const char *old_attrib; /* Pointer to supplied attribute name string */ const char *result; /* Pointer value to return */ double dval; /* Double attibute value */ double epoch; /* Epoch attribute value (as MJD) */ int axis; /* Frame axis number */ int axis_nc; /* No. characters in axis attribute name */ int digits; /* Digits attribute value */ int direction; /* Direction attribute value */ int free_axis_attrib; /* Should axis_attrib be freed? */ int has_axis; /* Does attrib name include axis specifier? */ int len; /* Length of attrib string */ int match_end; /* MatchEnd attribute value */ int max_axes; /* MaxAxes attribute value */ int min_axes; /* MinAxes attribute value */ int naxes; /* Naxes attribute value */ int nc; /* No. characters read by astSscanf */ int oldrep; /* Original error reporting state */ int paxis; /* Axis index within primary frame */ int permute; /* Permute attribute value */ int preserve_axes; /* PreserveAxes attribute value */ int used; /* Could the setting string be used? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Set a flag indicating if the attribute name includes an axis specifier. */ has_axis = ( strchr( attrib, '(' ) != NULL ); /* A flag indicating that we do not need to free the axis_attrib memory. */ free_axis_attrib = 0; /* Initialise things to avoid compiler warnings. */ axis_attrib = NULL; old_attrib = NULL; /* Jump back to here if we are trying the same attribute but with an explicit axis "(1)" added to the end of the name. */ L1: /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Save the number of axes in the Frame for later use. */ naxes = astGetNaxes( this ); /* Compare "attrib" with each recognised attribute name in turn, obtaining the value of the required attribute. If necessary, write the value into "getattrib_buff" as a null-terminated string in an appropriate format. Set "result" to point at the result string. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { digits = astGetDigits( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", digits ); result = getattrib_buff; } /* Digits(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { /* There is no function to obtain the Digits attribute value for an axis directly, so obtain a pointer to the Axis and use this to obtain the value. Use the Frame's Digits attribute instead if the Axis attribute value is not set. */ (void) astValidateAxis( this, axis - 1, 1, "astGetDigits(axis)" ); ax = astGetAxis( this, axis - 1 ); if ( astTestAxisDigits( ax ) ) { digits = astGetAxisDigits( ax ); } else { digits = astGetDigits( this ); } ax = astAnnul( ax ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", digits ); result = getattrib_buff; } /* Direction(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { direction = astGetDirection( this, axis - 1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", direction ); result = getattrib_buff; } /* Epoch. */ /* ------ */ } else if ( !strcmp( attrib, "epoch" ) ) { epoch = astGetEpoch( this ); if ( astOK ) { /* Format the Epoch as decimal years. Use a Besselian epoch if it will be less than 1984.0, otherwise use a Julian epoch. */ result = astFmtDecimalYr( ( epoch < palEpj2d( 1984.0 ) ) ? palEpb( epoch ) : palEpj( epoch ), DBL_DIG ); } /* Top(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetTop( this, axis -1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Bottom(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { dval = astGetBottom( this, axis -1 ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Domain. */ /* ------- */ } else if ( !strcmp( attrib, "domain" ) ) { result = astGetDomain( this ); /* Format(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetFormat( this, axis - 1 ); /* Label(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetLabel( this, axis - 1 ); /* MatchEnd. */ /* --------- */ } else if ( !strcmp( attrib, "matchend" ) ) { match_end = astGetMatchEnd( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", match_end ); result = getattrib_buff; } /* MaxAxes. */ /* -------- */ } else if ( !strcmp( attrib, "maxaxes" ) ) { max_axes = astGetMaxAxes( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", max_axes ); result = getattrib_buff; } /* MinAxes. */ /* -------- */ } else if ( !strcmp( attrib, "minaxes" ) ) { min_axes = astGetMinAxes( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", min_axes ); result = getattrib_buff; } /* Naxes. */ /* -----_ */ } else if ( !strcmp( attrib, "naxes" ) ) { (void) sprintf( getattrib_buff, "%d", naxes ); result = getattrib_buff; /* Permute. */ /* -------- */ } else if ( !strcmp( attrib, "permute" ) ) { permute = astGetPermute( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", permute ); result = getattrib_buff; } /* PreserveAxes. */ /* ------------- */ } else if ( !strcmp( attrib, "preserveaxes" ) ) { preserve_axes = astGetPreserveAxes( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", preserve_axes ); result = getattrib_buff; } /* Symbol(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetSymbol( this, axis - 1 ); /* AlignSystem. */ /* ------------ */ /* Obtain the AlignSystem code and convert to a string. */ } else if ( !strcmp( attrib, "alignsystem" ) ) { system = astGetAlignSystem( this ); if ( astOK ) { result = astSystemString( this, system ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid " "AlignSystem identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } } /* System. */ /* ------- */ /* Obtain the System code and convert to a string. */ } else if ( !strcmp( attrib, "system" ) ) { system = astGetSystem( this ); if ( astOK ) { result = astSystemString( this, system ); /* Report an error if the value was not recognised. */ if ( !result ) { astError( AST__SCSIN, "astGetAttrib(%s): Corrupt %s contains invalid " "System identification code (%d).", status, astGetClass( this ), astGetClass( this ), (int) system ); } } /* Title. */ /* ------ */ } else if ( !strcmp( attrib, "title" ) ) { result = astGetTitle( this ); /* Unit(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetUnit( this, axis - 1 ); /* NormUnit(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "normunit(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetNormUnit( this, axis - 1 ); /* InternalUnit(axis). */ /* --------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "internalunit(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astGetInternalUnit( this, axis - 1 ); /* ObsLat. */ /* ------- */ } else if ( !strcmp( attrib, "obslat" ) ) { dval = astGetObsLat( this ); if ( astOK ) { /* If not already created, create an FK5 J2000 SkyFrame which will be used for formatting and unformatting ObsLon and ObsLat values. */ if( !skyframe ) { astBeginPM; skyframe = astSkyFrame("system=FK5,equinox=J2000,format(2)=dms.2", status ); astEndPM; } /* Display absolute value preceded by "N" or "S" as appropriate. */ if( dval < 0 ) { (void) sprintf( getattrib_buff, "S%s", astFormat( skyframe, 1, -dval ) ); } else { (void) sprintf( getattrib_buff, "N%s", astFormat( skyframe, 1, dval ) ); } result = getattrib_buff; } /* ObsLon. */ /* ------- */ } else if ( !strcmp( attrib, "obslon" ) ) { dval = astGetObsLon( this ); if ( astOK ) { /* Put into range +/- PI. */ dval = palDrange( dval ); /* If not already created, create an FK5 J2000 SkyFrame which will be used for formatting and unformatting ObsLon and ObsLat values. */ if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); astEndPM; } /* Display absolute value preceded by "E" or "W" as appropriate. */ if( dval < 0 ) { (void) sprintf( getattrib_buff, "W%s", astFormat( skyframe, 1, -dval ) ); } else { (void) sprintf( getattrib_buff, "E%s", astFormat( skyframe, 1, dval ) ); } result = getattrib_buff; } /* ObsAlt. */ /* ------- */ } else if ( !strcmp( attrib, "obsalt" ) ) { dval = astGetObsAlt( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Dut1. */ /* ---- */ } else if ( !strcmp( attrib, "dut1" ) ) { dval = astGetDut1( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* Other axis attributes. */ /* ---------------------- */ /* If the attribute was not identified above, but appears to refer to a Frame axis, then it may refer to an Axis object of a derived type (which has additional attributes not recognised here). */ } else if ( !free_axis_attrib && ( nc = 0, ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", &axis_nc, &axis, &nc ) ) && ( nc >= len ) ) ) { /* Validate the axis index and extract the attribute name. */ (void) astValidateAxis( this, axis - 1, 1, "astGet" ); axis_attrib = astString( attrib, axis_nc ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis - 1 ); if( astOK ) { /* Assume that we will be able to use the attribute name. */ used = 1; /* Temporarily switch off error reporting so that if the following attempt to access the axis attribute fails, we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. Any errors reported in this context will simply be ignored, in particularly they are not deferred for later delivery. */ oldrep = astReporting( 0 ); /* Use the Axis astGetAttrib method to obtain the result. */ result = astGetAttrib( ax, axis_attrib ); /* If the above call failed with a status of AST__BADAT, indicating that the attribute name was not recognised, clear the status so that we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. */ if( astStatus == AST__BADAT ) { astClearStatus; /* Find the primary Frame containing the specified axis. */ astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); /* Only attempt to use the primary Frame if it is not the same as "this" - otherwise we could end up in an infinite loop. */ if( pfrm != this ) { /* astPrimaryFrame returns the original - unpermuted - axis index within the primary Frame. So we need to take into account any axis permutation which has been applied to the primary Frame when forming the attribute name to use below. Find the permuted (external) axis index which corresponds to the internal (unpermuted) axis index "paxis". */ paxis = astValidateAxis( pfrm, paxis, 0, "astGet" ); /* Modify the attribute name to refer to the axis numbering of the primary frame. */ sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); /* Attempt to use the Axis astGetAttrib method to obtain the result. */ result = astGetAttrib( pfrm, pfrm_attrib ); /* If this failed, clear the status and indicate that we have not managed to use the attribute name. */ if( !astOK ) { astClearStatus; used = 0; } } else { used = 0; } /* If not found attempt to get the attribute value from the Axis, omitting the axis index. */ if( ! used ) { result = astGetAttrib( pfrm, axis_attrib ); if( !astOK ) { astClearStatus; } else { used = 1; } } /* Annul the primary Frame pointer. */ pfrm = astAnnul( pfrm ); } /* Re-instate the original error reporting state. */ astReporting( oldrep ); /* If we could not use the attribute name, attempt to get the axis attribute again, this time retaining the error report. This is done to ensure the user gets an appropriate error message. */ if( !used ) result = astGetAttrib( ax, axis_attrib ); } /* Annul the Axis pointer and free the memory holding the attribute name. */ ax = astAnnul( ax ); axis_attrib = astFree( axis_attrib ); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, and the Frame has only 1 axis, and the attribute name does not already include an axis specifier, try again after appending "(1)" to the end of the attribute name. */ } else if( !has_axis && naxes == 1 ) { /* Take a copy of the supplied name, allowing 3 extra characters for the axis specifier "(1)". */ axis_attrib = astMalloc( len + 4 ); if( axis_attrib ) memcpy( axis_attrib, attrib, len ); /* Indicate we should free the axis_attrib memory. */ free_axis_attrib = 1; /* Add in the axis specifier. */ strcpy( axis_attrib + len, "(1)" ); /* Use the new attribute name instead of the supplied name. */ old_attrib = attrib; attrib = axis_attrib; /* Indicate the attribute name now has an axis specifier. */ has_axis = 1; /* Jump back to try interpreting the new attribute name. */ goto L1; /* Not recognised. */ /* --------------- */ /* If the attribute name is still not recognised, pass it on to the parent method for further interpretation. First re-instate the original attrib name string if it was changed above. */ } else { if( free_axis_attrib ) { attrib = old_attrib; axis_attrib = astFree( axis_attrib ); } result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static AstAxis *GetAxis( AstFrame *this, int axis, int *status ) { /* *+ * Name: * astGetAxis * Purpose: * Obtain a pointer to a specified Axis from a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstAxis *astGetAxis( AstFrame *this, int axis ) * Class Membership: * Frame method. * Description: * This function returns a pointer to the Axis object associated * with one of the axes of a Frame. This object describes the * quantity which is represented along that axis. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which an Axis pointer is * required. * Returned Value: * A pointer to the requested Axis object. * Notes: * - The reference count of the requested Axis object will be * incremented by one to reflect the additional pointer returned by * this function. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstAxis *result; /* Pointer to Axis */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise. */ result = NULL; /* Validate and permute the axis index. */ axis = astValidateAxis( this, axis, 1, "astGetAxis" ); /* If OK, clone the required Axis pointer. */ if ( astOK ) result = astClone( this->axis[ axis ] ); /* Return the result. */ return result; } static const char *GetDefaultLabel( int axis, int *status ) { /* * Name: * GetDefaultLabel * Purpose: * Return a pointer to a default axis Label string. * Type: * Private function. * Synopsis: * #include "frame.h" * const char *GetDefaultLabel( int axis, int *status ) * Class Membership: * Frame member function * Description: * This function returns a pointer to a string holding a default axis * Label value. * Parameters: * axis * Zero based axis index. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a static null-terminated string containing the attribute * value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(NULL); /* Format the axis index, putting the string in a global buffer. */ (void) sprintf( label_buff, "Axis %d", axis + 1 ); /* Return a pointer to the global buffer. */ return label_buff; } static const char *GetDefaultSymbol( AstFrame *this, int axis, int *status ) { /* * Name: * GetDefaultSymbol * Purpose: * Return a pointer to a default axis Symbol string. * Type: * Private function. * Synopsis: * #include "frame.h" * const char *GetDefaultSymbol( AstFrame *this, int axis, int *status ) * Class Membership: * Frame member function * Description: * This function returns a pointer to a string holding a default axis * Symbol value. * Parameters: * this * Pointer to the Frame. * axis * Zero based axis index. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a static null-terminated string containing the attribute * value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Note we use "sprintf" once to determine how many characters are produced by the "%d" format string and then limit the number of characters used from the Domain string in the second invocation of "sprintf" so that the total length of the default Symbol string does not exceed SYMBOL_BUFF_LEN characters. */ (void) sprintf( symbol_buff, "%.*s%d", SYMBOL_BUFF_LEN - sprintf( symbol_buff, "%d", axis + 1 ), astTestDomain( this ) ? astGetDomain( this ) : "x", axis + 1 ); /* Use the AddUnderscores function to replace any white space in the Symbol string with underscore characters. */ AddUnderscores( symbol_buff, status ); /* Return a pointer to the global buffer. */ return symbol_buff; } static const char *GetDefaultTitle( AstFrame *this, int *status ) { /* * Name: * GetDefaultTitle * Purpose: * Return a pointer to a default Title string. * Type: * Private function. * Synopsis: * #include "frame.h" * const char *GetDefaultTitle( AstFrame *this, int *status ) * Class Membership: * Frame member function * Description: * This function returns a pointer to a string holding a default Title value. * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * - Pointer to a static null-terminated string containing the attribute * value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Declare the thread specific global data */ /* Get a pointer to the structure holding thread-specific global data. */ astGET_GLOBALS(this); /* Create the Title value and put it in the global buffer. */ (void) sprintf( title_buff, "%d-d coordinate system", astGetNaxes( this ) ); /* Return a pointer to the global buffer. */ return title_buff; } static int GetFrameFlags( AstFrame *this, int *status ){ /* *+ * Name: * astGetFrameFlags * Purpose: * Return the bit mask of flags associated with a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * int *astGetFrameFlags( astFrame *this ) * Class Membership: * Frame virtual function. * Description: * This function returns a bit mask holding the current set of flags * associated with a Frame. See astSetFrameFlags for details of these * flags. * Parameters: * this * The Frame. * Returned Value: * The bit mask. * Notes: * - Zero is returned if this function is invoked with * the global error status set or if it should fail for any reason. *- */ /* Check the global error status. */ if ( !astOK ) return 0; /* Return the result. */ return this->flags; } static int GetIsLinear( AstMapping *this_mapping, int *status ){ /* * Name: * GetIsLinear * Purpose: * Return the value of the IsLinear attribute for a Frame. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsLinear( AstMapping *this, int *status ) * Class Membership: * Frame member function (over-rides the protected astGetIsLinear * method inherited from the Mapping class). * Description: * This function returns the value of the IsLinear attribute for a * Frame, which is always one because a Frame is treated like a UnitMap. * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. */ return 1; } static int GetIsSimple( AstMapping *this_mapping, int *status ){ /* * Name: * GetIsSimple * Purpose: * Return the value of the IsSimple attribute for a Frame. * Type: * Private function. * Synopsis: * #include "mapping.h" * void GetIsSimple( AstMapping *this, int *status ) * Class Membership: * Frame member function (over-rides the protected astGetIsSimple * method inherited from the Mapping class). * Description: * This function returns the value of the IsSimple attribute for a * Frame, which is always zero because Frames are not immutable (unlike * non-Frame Mappings). * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. */ return 0; } static int GetNaxes( AstFrame *this, int *status ) { /* *+ * Name: * astGetNaxes * Purpose: * Determine how many axes a Frame has. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astGetNaxes( AstFrame *this ) * Class Membership: * Frame method. * Description: * This function returns the number of axes for a Frame. * Parameters: * this * Pointer to the Frame. * Returned Value: * The number of Frame axes. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Check the global error status. */ if ( !astOK ) return 0; /* Return the number of Frame axes. */ return this->naxes; } static int GetNin( AstMapping *this_mapping, int *status ) { /* * Name: * GetNin * Purpose: * Get the number of input coordinates for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * int GetNin( AstMapping *this, int *status ) * Class Membership: * Frame member function (over-rides the astGetNin method inherited * from the Mapping class). * Description: * This function returns the number of input coordinate values * required per point by a Frame, when used as a Mapping (i.e. the * number of dimensions of the space in which input points reside). * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * Number of coordinate values required. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstFrame *this; /* Pointer to Frame structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_mapping; /* Return the number of Frame axes. */ result = astGetNaxes( this ); /* Return the result. */ return result; } static int GetNout( AstMapping *this_mapping, int *status ) { /* * Name: * GetNout * Purpose: * Get the number of output coordinates for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * int GetNout( AstMapping *this, int *status ) * Class Membership: * Frame member function (over-rides the astGetNout method * inherited from the Mapping class). * Description: * This function returns the number of output coordinate values * generated per point by a Frame, when used as a Mapping (i.e. the * number of dimensions of the space in which output points * reside). * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * Number of coordinate values generated. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstFrame *this; /* Pointer to Frame structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_mapping; /* Return the number of Frame axes. */ result = astGetNaxes( this ); /* Return the result. */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "frame.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * Frame member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied Frame, * in bytes. * Parameters: * this * Pointer to the Frame. * status * Pointer to the inherited status variable. * Returned Value: * The Object size, in bytes. * Notes: * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstFrame *this; /* Pointer to Frame structure */ int axis; /* Axis index */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the FrameSet structure. */ this = (AstFrame *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astGetObjSize( this->variants ); result += astTSizeOf( this->domain ); result += astTSizeOf( this->title ); result += astTSizeOf( this->axis ); result += astTSizeOf( this->perm ); for ( axis = 0; axis < this->naxes; axis++ ) { result += astGetObjSize( this->axis[ axis ] ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static const int *GetPerm( AstFrame *this, int *status ) { /* *+ * Name: * astGetPerm * Purpose: * Access the axis permutation array for a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * const int *astGetPerm( AstFrame *this ) * Class Membership: * Frame method. * Description: * This function returns a pointer to the axis permutation array * for a Frame. This array constitutes a lookup-table that converts * between an axis number supplied externally and the corresponding * index in the Frame's internal axis arrays. * Parameters: * this * Pointer to the Frame. * Returned Value: * Pointer to the Frame's axis permutation array (a constant array * of int). Each element of this contains the (zero-based) * internal axis index to be used in place of the external index * which is used to address the permutation array. If the Frame has * zero axes, this pointer will be NULL. * Notes: * - This protected method is provided to assist class * implementations which need to implement axis-dependent * extensions to Frame methods, and which therefore need to know * how a Frames's external axis index is converted for internal * use. * - The pointer returned by this function gives direct access to * data internal to the Frame object. It remains valid only so long * as the Frame exists. The permutation array contents may be * modified by other functions which operate on the Frame and this * may render the returned pointer invalid. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Return a pointer to the axis permutation array. */ return this->perm; } static AstFrameSet *GetFrameVariants( AstFrame *this, int *status ){ /* *+ * Name: * astGetFrameVariants * Purpose: * Returns the FrameSet holding the available Frame variants. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstFrameSet *astGetFrameVariants( AstFrame *this ) * Class Membership: * Frame method. * Description: * This function returns a pointer to any FrameSet previously stored * in the Frame using method astSetVariants. * Parameters: * this * Pointer to the Frame. * Returned Value: * astGetFrameVariants * A pointer to the FrameSet. It should be annulled using astAnnul * when no longer needed. NULL will be returned if no FrameSet is * stored in the Frame. * Notes: * - A NULL value will be returned if this function is invoked with the * AST error status set, or if it should fail for any reason. *- */ /* Local Variables: */ AstFrameSet *result; /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a clone of any FrameSet pointer. */ if( this->variants ) result = astClone( this->variants ); /* Return the result. */ return result; } void astInitFrameVtab_( AstFrameVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitFrameVtab * Purpose: * Initialise a virtual function table for a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * void astInitFrameVtab( AstFrameVtab *vtab, const char *name ) * Class Membership: * Frame vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Frame class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAFrame ) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->Abbrev = Abbrev; vtab->CheckPerm = CheckPerm; vtab->ClearDigits = ClearDigits; vtab->ClearDirection = ClearDirection; vtab->ClearDomain = ClearDomain; vtab->ClearFormat = ClearFormat; vtab->ClearLabel = ClearLabel; vtab->ClearMatchEnd = ClearMatchEnd; vtab->ClearMaxAxes = ClearMaxAxes; vtab->ClearMinAxes = ClearMinAxes; vtab->ClearPermute = ClearPermute; vtab->ClearPreserveAxes = ClearPreserveAxes; vtab->ClearSymbol = ClearSymbol; vtab->ClearTitle = ClearTitle; vtab->ClearUnit = ClearUnit; vtab->Convert = Convert; vtab->ConvertX = ConvertX; vtab->Angle = Angle; vtab->Distance = Distance; vtab->Fields = Fields; vtab->FindFrame = FindFrame; vtab->MatchAxes = MatchAxes; vtab->MatchAxesX = MatchAxesX; vtab->Format = Format; vtab->Centre = Centre; vtab->Gap = Gap; vtab->GetAxis = GetAxis; vtab->GetDigits = GetDigits; vtab->GetDirection = GetDirection; vtab->GetDomain = GetDomain; vtab->GetFormat = GetFormat; vtab->GetLabel = GetLabel; vtab->GetMatchEnd = GetMatchEnd; vtab->GetMaxAxes = GetMaxAxes; vtab->GetMinAxes = GetMinAxes; vtab->GetNaxes = GetNaxes; vtab->GetPerm = GetPerm; vtab->GetPermute = GetPermute; vtab->GetPreserveAxes = GetPreserveAxes; vtab->GetSymbol = GetSymbol; vtab->GetTitle = GetTitle; vtab->GetUnit = GetUnit; vtab->GetInternalUnit = GetInternalUnit; vtab->GetNormUnit = GetNormUnit; vtab->Intersect = Intersect; vtab->IsUnitFrame = IsUnitFrame; vtab->Match = Match; vtab->Norm = Norm; vtab->NormBox = NormBox; vtab->AxDistance = AxDistance; vtab->AxNorm = AxNorm; vtab->AxOffset = AxOffset; vtab->AxIn = AxIn; vtab->AxAngle = AxAngle; vtab->FrameGrid = FrameGrid; vtab->Offset = Offset; vtab->Offset2 = Offset2; vtab->Resolve = Resolve; vtab->ResolvePoints = ResolvePoints; vtab->LineDef = LineDef; vtab->LineContains = LineContains; vtab->LineCrossing = LineCrossing; vtab->LineOffset = LineOffset; vtab->Overlay = Overlay; vtab->PermAxes = PermAxes; vtab->PickAxes = PickAxes; vtab->PrimaryFrame = PrimaryFrame; vtab->SetAxis = SetAxis; vtab->SetDigits = SetDigits; vtab->SetDirection = SetDirection; vtab->SetDomain = SetDomain; vtab->SetFormat = SetFormat; vtab->SetLabel = SetLabel; vtab->SetMatchEnd = SetMatchEnd; vtab->SetMaxAxes = SetMaxAxes; vtab->SetMinAxes = SetMinAxes; vtab->SetPermute = SetPermute; vtab->SetPreserveAxes = SetPreserveAxes; vtab->SetSymbol = SetSymbol; vtab->SetTitle = SetTitle; vtab->SetUnit = SetUnit; vtab->SubFrame = SubFrame; vtab->TestDigits = TestDigits; vtab->TestDirection = TestDirection; vtab->TestDomain = TestDomain; vtab->TestFormat = TestFormat; vtab->TestLabel = TestLabel; vtab->TestMatchEnd = TestMatchEnd; vtab->TestMaxAxes = TestMaxAxes; vtab->TestMinAxes = TestMinAxes; vtab->TestPermute = TestPermute; vtab->TestPreserveAxes = TestPreserveAxes; vtab->TestSymbol = TestSymbol; vtab->TestTitle = TestTitle; vtab->TestUnit = TestUnit; vtab->Unformat = Unformat; vtab->ValidateAxis = ValidateAxis; vtab->ValidateAxisSelection = ValidateAxisSelection; vtab->ValidateSystem = ValidateSystem; vtab->SystemString = SystemString; vtab->SystemCode = SystemCode; vtab->GetFrameFlags = GetFrameFlags; vtab->SetFrameFlags = SetFrameFlags; vtab->TestActiveUnit = TestActiveUnit; vtab->GetActiveUnit = GetActiveUnit; vtab->SetActiveUnit = SetActiveUnit; vtab->GetFrameVariants = GetFrameVariants; vtab->SetFrameVariants = SetFrameVariants; vtab->ClearSystem = ClearSystem; vtab->GetSystem = GetSystem; vtab->SetSystem = SetSystem; vtab->TestSystem = TestSystem; vtab->ClearAlignSystem = ClearAlignSystem; vtab->GetAlignSystem = GetAlignSystem; vtab->SetAlignSystem = SetAlignSystem; vtab->TestAlignSystem = TestAlignSystem; vtab->ClearTop = ClearTop; vtab->GetTop = GetTop; vtab->SetTop = SetTop; vtab->TestTop = TestTop; vtab->ClearBottom = ClearBottom; vtab->GetBottom = GetBottom; vtab->SetBottom = SetBottom; vtab->TestBottom = TestBottom; vtab->ClearEpoch = ClearEpoch; vtab->GetEpoch = GetEpoch; vtab->SetEpoch = SetEpoch; vtab->TestEpoch = TestEpoch; vtab->ClearObsLat = ClearObsLat; vtab->TestObsLat = TestObsLat; vtab->GetObsLat = GetObsLat; vtab->SetObsLat = SetObsLat; vtab->ClearObsLon = ClearObsLon; vtab->TestObsLon = TestObsLon; vtab->GetObsLon = GetObsLon; vtab->SetObsLon = SetObsLon; vtab->ClearObsAlt = ClearObsAlt; vtab->TestObsAlt = TestObsAlt; vtab->GetObsAlt = GetObsAlt; vtab->SetObsAlt = SetObsAlt; vtab->ClearDut1 = ClearDut1; vtab->GetDut1 = GetDut1; vtab->SetDut1 = SetDut1; vtab->TestDut1 = TestDut1; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_cleanattribs = object->CleanAttribs; object->CleanAttribs = CleanAttribs; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping = (AstMappingVtab *) vtab; object->Equal = Equal; mapping->GetIsLinear = GetIsLinear; mapping->GetIsSimple = GetIsSimple; mapping->GetNin = GetNin; mapping->GetNout = GetNout; mapping->ReportPoints = ReportPoints; mapping->Transform = Transform; mapping->MapSplit = MapSplit; mapping->DoNotSimplify = DoNotSimplify; /* Declare the copy constructor, destructor and class dump function. */ astSetCopy( vtab, Copy ); astSetDelete( vtab, Delete ); astSetDump( vtab, Dump, "Frame", "Coordinate system description" ); /* If we have just initialised the vtab for the current class, indicate that the vtab is now initialised, and store a pointer to the class identifier in the base "object" level of the vtab. */ if( vtab == &class_vtab ) { class_init = 1; astSetVtabClassIdentifier( vtab, &(vtab->id) ); } } static void Intersect( AstFrame *this, const double a1[2], const double a2[2], const double b1[2], const double b2[2], double cross[2], int *status ) { /* *++ * Name: c astIntersect f AST_INTERSECT * Purpose: * Find the point of intersection between two geodesic curves. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astIntersect( AstFrame *this, const double a1[2], c const double a2[2], const double b1[2], c const double b2[2], double cross[2] ) f CALL AST_INTERSECT( THIS, A1, A2, B1, B2, CROSS, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * finds the coordinate values at the point of intersection between * two geodesic curves. Each curve is specified by two points on * the curve. It can only be used with 2-dimensional Frames. * * For example, in a basic Frame, it will find the point of * intersection between two straight lines. But for a SkyFrame it * will find an intersection of two great circles. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c a1 f A1( 2 ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of the * first point on the first geodesic curve. c a2 f A2( 2 ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of a * second point on the first geodesic curve. It should not be * co-incident with the first point. c b1 f B1( 2 ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of the * first point on the second geodesic curve. c b2 f B2( 2 ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of a * second point on the second geodesic curve. It should not be * co-incident with the first point. c cross f CROSS( 2 ) = DOUBLE PRECISION (Returned) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * in which the coordinates of the required intersection will * be returned. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - For SkyFrames each curve will be a great circle, and in general * each pair of curves will intersect at two diametrically opposite * points on the sky. The returned position is the one which is * closest to point c "a1". f A1. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value, or if the two * points defining either geodesic are co-incident, or if the two * curves do not intersect. c - The geodesic curve used by this function is the path of f - The geodesic curve used by this routine is the path of * shortest distance between two points, as defined by the c astDistance function. f AST_DISTANCE function. * - An error will be reported if the Frame is not 2-dimensional. *-- */ /* Local Variables: */ double ca; /* Y axis intercept of line a */ double cb; /* Y axis intercept of line b */ double dxa; /* X range spanned by line a */ double dxb; /* X range spanned by line b */ double ma; /* Gradient of line a */ double mb; /* Gradient of line b */ int naxes; /* Number of Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Initialize bad values. */ cross[ 0 ] = AST__BAD; cross[ 1 ] = AST__BAD; /* Determine the number of Frame axes. */ naxes = astGetNaxes( this ); /* Report an error if the Frame is not 2 dimensional. */ if( naxes != 2 && astOK ) { astError( AST__NAXIN, "astIntersect(%s): Invalid number of Frame axes (%d)." " astIntersect can only be used with 2 dimensonal Frames.", status, astGetClass( this ), naxes ); } /* Check that all supplied values are OK. */ if ( ( a1[ 0 ] != AST__BAD ) && ( a1[ 1 ] != AST__BAD ) && ( a2[ 0 ] != AST__BAD ) && ( a2[ 1 ] != AST__BAD ) && ( b1[ 0 ] != AST__BAD ) && ( b1[ 1 ] != AST__BAD ) && ( b2[ 0 ] != AST__BAD ) && ( b2[ 1 ] != AST__BAD ) ) { /* Find the x increments spanned by the two lines. */ /* Check the first line is not vertical. */ dxa = a2[ 0 ] - a1[ 0 ]; dxb = b2[ 0 ] - b1[ 0 ]; if( dxa != 0.0 ) { /* Find the gradient and Y axis intercept of the first line. */ ma = ( a2[ 1 ] - a1[ 1 ] )/dxa; ca = a1[ 1 ] - a1[ 0 ]*ma; /* Check the second line is not vertical. */ if( dxb != 0.0 ) { /* Find the gradient and Y axis intercept of the second line. */ mb = ( b2[ 1 ] - b1[ 1 ] )/dxb; cb = b1[ 1 ] - b1[ 0 ]*mb; /* Check the lines are not parallel. */ if( ma != mb ) { /* Find the intersection of the two lines. */ cross[ 0 ] = ( cb -ca )/( ma - mb ); cross[ 1 ] = ( ( ma + mb )*cross[ 0 ] + ca + cb )/2; } /* If the second line is vertical but the first is not. */ } else if( b1[ 1 ] != b2[ 1 ] ){ cross[ 0 ] = b1[ 0 ]; cross[ 1 ] = ma*b1[ 0 ] + ca; } /* First line is vertical but second is not. */ } else if( dxb != 0.0 && a1[ 1 ] != a2[ 1 ] ){ /* Find the gradient and Y axis intercept of the second line. */ mb = ( b2[ 1 ] - b1[ 1 ] )/dxb; cb = b1[ 1 ] - b1[ 0 ]*mb; /* Find the intercection. */ cross[ 0 ] = a1[ 0 ]; cross[ 1 ] = mb*a1[ 0 ] + cb; } } } static int IsUnitFrame( AstFrame *this, int *status ){ /* *+ * Name: * astIsUnitFrame * Purpose: * Is this Frame equivalent to a UnitMap? * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astIsUnitFrame( AstFrame *this ) * Class Membership: * Frame method. * Description: * This function returns a flag indicating if the supplied Frame is * equivalent to a UnitMap when treated as a Mapping (note, the Frame * class inherits from Mapping and therefore every Frame is also a Mapping). * Parameters: * this * Pointer to the Frame. * Returned Value: * A non-zero value is returned if the supplied Frame is equivalent to * a UnitMap when treated as a Mapping. *- */ /* Check the local error status. */ if( !astOK ) return 0; /* The base Frame class is always equivalent to a UnitMap. */ return 1; } static int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) { /* *+ * Name: * astLineContains * Purpose: * Determine if a line contains a point. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astLineContains( AstFrame *this, AstLineDef *l, int def, double *point ) * Class Membership: * Frame method. * Description: * This function determines if the supplied point is on the supplied * line within the supplied Frame. The start point of the line is * considered to be within the line, but the end point is not. The tests * are that the point of closest approach of the line to the point should * be between the start and end, and that the distance from the point to * the point of closest aproach should be less than 1.0E-7 of the length * of the line. * Parameters: * this * Pointer to the Frame. * l * Pointer to the structure defining the line. * def * Should be set non-zero if the "point" array was created by a * call to astLineCrossing (in which case it may contain extra * information following the axis values),and zero otherwise. * point * Point to an array containing the axis values of the point to be * tested, possibly followed by extra cached information (see "def"). * Returned Value: * A non-zero value is returned if the line contains the point. * Notes: * - The pointer supplied for "l" should have been created using the * astLineDef method. These structures contained cached information about * the lines which improve the efficiency of this method when many * repeated calls are made. An error will be reported if the structure * does not refer to the Frame specified by "this". * - Zero will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. *- */ /* Local Variables: */ int result; double dx, dy, p; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Check that the line refers to the supplied Frame. */ if( l->frame != this ) { astError( AST__INTER, "astLineContains(%s): The supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); /* If the point is good, find the offsets from the start of the line. */ } else if( point[ 0 ] != AST__BAD && point[ 1 ] != AST__BAD ) { dx = point[ 0 ] - l->start[ 0 ]; dy = point[ 1 ] - l->start[ 1 ]; /* Check the nearest point on the line is between the start and end. Exclude the end point. */ p = dx*l->dir[ 0 ] + dy*l->dir[ 1 ]; if( p >= 0.0 && p < l->length ) { /* Check the distance from the point to the nearest point on the line is not further than 1.0E-7 of the length of the line. */ if( fabs( dx*l->q[ 0 ] + dy*l->q[ 1 ] ) <= 1.0E-7*l->length ) { result = 1; } } } /* Return zero if an error occurred. */ if( !astOK ) result = 0; /* Return a pointer to the output structure. */ return result; } static int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, double **cross, int *status ) { /* *+ * Name: * astLineCrossing * Purpose: * Determine if two lines cross. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astLineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, * double **cross ) * Class Membership: * Frame method. * Description: * This function determines if the two suplied line segments cross, * and if so returns the axis values at the point where they cross. * A flag is also returned indicating if the crossing point occurs * within the length of both line segments, or outside one or both of * the line segments. * Parameters: * this * Pointer to the Frame. * l1 * Pointer to the structure defining the first line. * l2 * Pointer to the structure defining the second line. * cross * Pointer to a location at which to put a pointer to a dynamically * alocated array containing the axis values at the crossing. If * NULL is supplied no such array is returned. Otherwise, the returned * array should be freed using astFree when no longer needed. If the * lines are parallel (i.e. do not cross) then AST__BAD is returned for * all axis values. Note usable axis values are returned even if the * lines cross outside the segment defined by the start and end points * of the lines. The order of axes in the returned array will take * account of the current axis permutation array if appropriate. Note, * sub-classes such as SkyFrame may append extra values to the end * of the basic frame axis values. A NULL pointer is returned if an * error occurs. * Returned Value: * A non-zero value is returned if the lines cross at a point which is * within the [start,end) segment of the lines that are flagged as * finite (if a line is marked as infinite any crossing is assumed to * be within the bounds of the line). If the crossing point is outside * this segment on either (inifinte) line, or if the lines are parallel, * zero is returned. Note, the start point is considered to be inside * the length of the segment, but the end point is outside. * Notes: * - The pointers supplied for "l1" and "l2" should have been created * using the astLineDef method. These structures contained cached * information about the lines which improve the efficiency of this method * when many repeated calls are made. An error will be reported if * either structure does not refer to the Frame specified by "this". * - Zero will be returned if this function is invoked with the global * error status set, or if it should fail for any reason. *- */ /* Local Variables: */ double *crossing; /* Returned array */ double den; /* Denominator */ double dx; /* Offset in start X values */ double dy; /* Offset in start Y values */ double t1; /* Distance from start of line 1 to crossing */ double t2; /* Distance from start of line 2 to crossing */ int result; /* Returned value */ /* Check the global error status. */ if ( !astOK ) return 0; /* Initialise. */ result = 0; crossing = astMalloc( sizeof(double)*2 ); /* Check that both lines refer to the supplied Frame. */ if( l1->frame != this ) { astError( AST__INTER, "astLineCrossing(%s): First supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); } else if( l2->frame != this ) { astError( AST__INTER, "astLineCrossing(%s): Second supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); } else if( crossing ){ /* Each of the lines can be represented as "p = start + t.v" where start is the start position, v is the unit vector pointing from start to end, and t is the scalar distance from the start position. So to find the intersection put "start1 + t1.v1 = start2 + t2.v2" and solve for t1 and t2. */ den = (l1->dir[ 0 ])*(l2->dir[ 1 ]) - (l2->dir[ 0 ])*(l1->dir[ 1 ]); if( den != 0.0 ) { dx = l2->start[ 0 ] - l1->start[ 0 ]; dy = l2->start[ 1 ] - l1->start[ 1 ]; t1 = ( l2->dir[ 1 ]*dx - l2->dir[ 0 ]*dy )/den; t2 = ( l1->dir[ 1 ]*dx - l1->dir[ 0 ]*dy )/den; /* Store the crossing point, using the smaller t value to redue error. */ if( fabs( t1 ) < fabs( t2 ) ) { crossing[ 0 ] = l1->start[ 0 ] + t1*l1->dir[ 0 ]; crossing[ 1 ] = l1->start[ 1 ] + t1*l1->dir[ 1 ]; } else { crossing[ 0 ] = l2->start[ 0 ] + t2*l2->dir[ 0 ]; crossing[ 1 ] = l2->start[ 1 ] + t2*l2->dir[ 1 ]; } /* See if the intersection is within the length of both lines (excluding the end points). If a line is flagged as infinite, set the "t" parameter to zero to make it look like the crossing is within the line. */ if( l1->infinite ) t1 = 0.0; if( l2->infinite ) t2 = 0.0; if( t1 >= 0.0 && t1 < l1->length && t2 >= 0.0 && t2 < l2->length ) result = 1; } else { crossing[ 0 ] = AST__BAD; crossing[ 1 ] = AST__BAD; } } /* Return zero if an error occurred. */ if( !astOK ) { crossing = astFree( crossing ); result = 0; } /* Return the crossing pointer. */ if( cross ) { *cross = crossing; } else if( crossing ){ crossing = astFree( crossing ); } /* Return a pointer to the output structure. */ return result; } static AstLineDef *LineDef( AstFrame *this, const double start[2], const double end[2], int *status ) { /* *+ * Name: * astLineDef * Purpose: * Creates a structure describing a line segment in a 2D Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstLineDef *astLineDef( AstFrame *this, const double start[2], * const double end[2] ) * Class Membership: * Frame method. * Description: * This function creates a structure containing information describing a * given line segment within the supplied 2D Frame. This may include * information which allows other methods such as astLineCrossing to * function more efficiently. Thus the returned structure acts as a * cache to store intermediate values used by these other methods. * Parameters: * this * Pointer to the Frame. Must have 2 axes. * start * An array of 2 doubles marking the start of the line segment. * end * An array of 2 doubles marking the end of the line segment. * Returned Value: * Pointer to the memory structure containing the description of the * line. This structure should be freed using astFree when no longer * needed. A NULL pointer is returned (without error) if any of the * supplied axis values are AST__BAD. * Notes: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstLineDef *result; /* Pointer to output structure */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Check the Frame has 2 axes. */ if( astGetNaxes( this ) != 2 ) { astError( AST__INTER, "astLineDef(%s): The supplied %s is not 2 " "dimensional (internal AST proramming error).", status, astGetClass( this ), astGetClass( this ) ); } /* Check the axis values are good */ if( start[ 0 ] != AST__BAD && start[ 1 ] != AST__BAD && end[ 0 ] != AST__BAD && end[ 1 ] != AST__BAD ) { /* Allocate memory for the returned structure. */ result = astMalloc( sizeof( AstLineDef ) ); if( result ) { /* Store the supplied axis values in the returned structure. */ result->start[ 0 ] = start[ 0 ]; result->start[ 1 ] = start[ 1 ]; result->end[ 0 ] = end[ 0 ]; result->end[ 1 ] = end[ 1 ]; /* Store the length of the line segment. */ result->length = astDistance( this, start, end ); /* Store a unit vector pointing from the start to the end. */ if( result->length > 0.0 ) { result->dir[ 0 ] = ( end[ 0 ] - start[ 0 ] )/result->length; result->dir[ 1 ] = ( end[ 1 ] - start[ 1 ] )/result->length; } else { result->dir[ 0 ] = 1.0; result->dir[ 1 ] = 0.0; } /* Store a unit vector perpendicular to the line, such that the vector points to the left, as vewied from the observer, when moving from the start to the end of the line. */ result->q[ 0 ] = -result->dir[ 1 ]; result->q[ 1 ] = result->dir[ 0 ]; /* Store a pointer to the defining Frame. */ result->frame = this; /* Indicate that the line is considered to be terminated at the start and end points. */ result->infinite = 0; } } /* Free the returned pointer if an error occurred. */ if( !astOK ) result = astFree( result ); /* Return a pointer to the output structure. */ return result; } static void LineOffset( AstFrame *this, AstLineDef *line, double par, double prp, double point[2], int *status ){ /* *+ * Name: * astLineOffset * Purpose: * Find a position close to a line. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void LineOffset( AstFrame *this, AstLineDef *line, double par, * double prp, double point[2] ) * Class Membership: * Frame method. * Description: * This function returns a position formed by moving a given distance along * the supplied line, and then a given distance away from the supplied line. * Parameters: * this * Pointer to the Frame. * line * Pointer to the structure defining the line. * par * The distance to move along the line from the start towards the end. * prp * The distance to move at right angles to the line. Positive * values result in movement to the left of the line, as seen from * the observer, when moving from start towards the end. * Notes: * - The pointer supplied for "line" should have been created using the * astLineDef method. This structure contains cached information about the * line which improves the efficiency of this method when many repeated * calls are made. An error will be reported if the structure does not * refer to the Frame specified by "this". *- */ /* Check the global error status. */ if ( !astOK ) return; /* Check that the line refers to the supplied Frame. */ if( line->frame != this ) { astError( AST__INTER, "astLineOffset(%s): The supplied line does " "not relate to the supplied %s (AST internal programming " "error).", status, astGetClass( this ), astGetClass( this ) ); /* This implementation uses simple flat geometry. */ } else { point[ 0 ] = line->start[ 0 ] + par*line->dir[ 0 ] + prp*line->q[ 0 ]; point[ 1 ] = line->start[ 1 ] + par*line->dir[ 1 ] + prp*line->q[ 1 ]; } } #if defined(THREAD_SAFE) static int ManageLock( AstObject *this_object, int mode, int extra, AstObject **fail, int *status ) { /* * Name: * ManageLock * Purpose: * Manage the thread lock on an Object. * Type: * Private function. * Synopsis: * #include "object.h" * AstObject *ManageLock( AstObject *this, int mode, int extra, * AstObject **fail, int *status ) * Class Membership: * CmpMap member function (over-rides the astManageLock protected * method inherited from the parent class). * Description: * This function manages the thread lock on the supplied Object. The * lock can be locked, unlocked or checked by this function as * deteremined by parameter "mode". See astLock for details of the way * these locks are used. * Parameters: * this * Pointer to the Object. * mode * An integer flag indicating what the function should do: * * AST__LOCK: Lock the Object for exclusive use by the calling * thread. The "extra" value indicates what should be done if the * Object is already locked (wait or report an error - see astLock). * * AST__UNLOCK: Unlock the Object for use by other threads. * * AST__CHECKLOCK: Check that the object is locked for use by the * calling thread (report an error if not). * extra * Extra mode-specific information. * fail * If a non-zero function value is returned, a pointer to the * Object that caused the failure is returned at "*fail". This may * be "this" or it may be an Object contained within "this". Note, * the Object's reference count is not incremented, and so the * returned pointer should not be annulled. A NULL pointer is * returned if this function returns a value of zero. * status * Pointer to the inherited status variable. * Returned Value: * A local status value: * 0 - Success * 1 - Could not lock or unlock the object because it was already * locked by another thread. * 2 - Failed to lock a POSIX mutex * 3 - Failed to unlock a POSIX mutex * 4 - Bad "mode" value supplied. * Notes: * - This function attempts to execute even if an error has already * occurred. */ /* Local Variables: */ AstFrame *this; /* Pointer to Frame structure */ int i; /* Loop count */ int result; /* Returned status value */ /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointers to the Frame structure. */ this = (AstFrame *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ for( i = 0; i < this->naxes; i++ ) { if( !result ) result = astManageLock( this->axis[ i ], mode, extra, fail ); } if( this->variants && !result ) result = astManageLock( this->variants, mode, extra, fail ); return result; } #endif static int *MapSplit( AstMapping *this_map, int nin, const int *in, AstMapping **map, int *status ){ /* * Name: * MapSplit * Purpose: * Create a Mapping representing a subset of the inputs of an existing * Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) * Class Membership: * Frame method (over-rides the protected astMapSplit method * inherited from the Mapping class). * Description: * This function creates a new Mapping by picking specified inputs from * an existing Frame. This is only possible if the specified inputs * correspond to some subset of the Frame outputs. That is, there * must exist a subset of the Frame outputs for which each output * depends only on the selected Frame inputs, and not on any of the * inputs which have not been selected. If this condition is not met * by the supplied Frame, then a NULL Mapping is returned. * Parameters: * this * Pointer to the Frame to be split (the Frame is not actually * modified by this function). * nin * The number of inputs to pick from "this". * in * Pointer to an array of indices (zero based) for the inputs which * are to be picked. This array should have "nin" elements. If "Nin" * is the number of inputs of the supplied Frame, then each element * should have a value in the range zero to Nin-1. * map * Address of a location at which to return a pointer to the new * Mapping. This Mapping will have "nin" inputs (the number of * outputs may be different to "nin"). A NULL pointer will be * returned if the supplied Frame has no subset of outputs which * depend only on the selected inputs. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to a dynamically allocated array of ints. The number of * elements in this array will equal the number of outputs for the * returned Mapping. Each element will hold the index of the * corresponding output in the supplied Frame. The array should be * freed using astFree when no longer needed. A NULL pointer will * be returned if no output Mapping can be created. * Notes: * - If this function is invoked with the global error status set, * or if it should fail for any reason, then NULL values will be * returned as the function value and for the "map" pointer. */ /* Local Variables: */ int *result; /* Returned pointer */ /* Initialise */ result = NULL; *map = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Pick the selected axes from the Frame. */ *map = (AstMapping *) astPickAxes( (AstFrame *) this_map, nin, in, NULL ); /* Return a copy of the supplied axis array.*/ result = astStore( NULL, in, sizeof( int )*(size_t) nin ); /* Free returned resources if an error has occurred. */ if( !astOK ) { result = astFree( result ); *map = astAnnul( *map ); } /* Return the list of output indices. */ return result; } static int Match( AstFrame *template, AstFrame *target, int matchsub, int **template_axes, int **target_axes, AstMapping **map, AstFrame **result, int *status ) { /* *+ * Name: * astMatch * Purpose: * Determine if conversion is possible between two coordinate systems. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astMatch( AstFrame *template, AstFrame *target, int matchsub, * int **template_axes, int **target_axes, * AstMapping **map, AstFrame **result ) * Class Membership: * Frame method. * Description: * This function matches a "template" frame to a "target" frame and * determines whether it is possible to convert coordinates between * them. If it is, a mapping that performs the transformation is * returned along with a new Frame that describes the coordinate * system that results when this mapping is applied to the "target" * coordinate system. In addition, information is returned to allow * the axes in this "result" Frame to be associated with the * corresponding axes in the "target" and "template" Frames from * which they are derived. * Parameters: * template * Pointer to the template Frame. This describes the coordinate * system (or set of possible coordinate systems) into which we * wish to convert our coordinates. * target * Pointer to the target Frame. This describes the coordinate * system in which we already have coordinates. * matchsub * If zero then a match only occurs if the template is of the same * class as the target, or of a more specialised class. If non-zero * then a match can occur even if this is not the case (i.e. if the * target is of a more specialised class than the template). In * this latter case, the target is cast down to the class of the * template. NOTE, this argument is handled by the global method * wrapper function "astMatch_", rather than by the class-specific * implementations of this method. * template_axes * Address of a location where a pointer to int will be returned * if the requested coordinate conversion is possible. This * pointer will point at a dynamically allocated array of * integers with one element for each axis of the "result" Frame * (see below). It must be freed by the caller (using astFree) * when no longer required. * * For each axis in the result Frame, the corresponding element * of this array will return the (zero-based) index of the * template Frame axis from which it is derived. If it is not * derived from any template frame axis, a value of -1 will be * returned instead. * target_axes * Address of a location where a pointer to int will be returned * if the requested coordinate conversion is possible. This * pointer will point at a dynamically allocated array of * integers with one element for each axis of the "result" Frame * (see below). It must be freed by the caller (using astFree) * when no longer required. * * For each axis in the result Frame, the corresponding element * of this array will return the (zero-based) index of the * target Frame axis from which it is derived. If it is not * derived from any target Frame axis, a value of -1 will be * returned instead. * map * Address of a location where a pointer to a new Mapping will * be returned if the requested coordinate conversion is * possible. If returned, the forward transformation of this * Mapping may be used to convert coordinates between the * "target" Frame and the "result" Frame (see below) and the * inverse transformation will convert in the opposite * direction. * result * Address of a location where a pointer to a new Frame will be * returned if the requested coordinate conversion is * possible. If returned, this Frame describes the coordinate * system that results from applying the returned Mapping * (above) to the "target" coordinate system. In general, this * Frame will combine attributes from (and will therefore be * more specific than) both the target and the template * Frames. In particular, when the template allows the * possibility of transformaing to any one of a set of * alternative coordinate systems, the "result" Frame will * indicate which of the alternatives was used. * Returned Value: * A non-zero value is returned if the requested coordinate * conversion is possible. Otherwise zero is returned (this will * not in itself result in an error condition). * Notes: * - By default, the "result" frame will have its number of axes * and axis order determined by the "template" Frame. However, if * the PreserveAxes attribute of the template frame is non-zero, * then the axis count and axis order of the "target" frame will be * used instead. * - The template_axes and target_axes arrays are provided so that * if the caller needs to permute the target and/or template axes * before invoking this function, it is possible to deduce how the * result axes should be permuted so as to correspond with the * original template/target axis order. * - For result axes that do not correspond with a template and/or * target axis (where a value of -1 is returned in the * template_axes and/or target_axes arrays), the caller has no * clear way of knowing where these axes should appear in any * permuted order. In this case, the relative position of these * axes within the result Frame (with respect to axes that do have * template/target axis associations) will be used to convey this * information. Such axes should be taken to be associated either * with the next preceding or following axis (depending on the * AST__MATCHEND flag of the template frame) which does have an * association. * - If the result Frame has zero axes, then NULL pointer values * will be returned for *template_axes and *target_axes. * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- * Implementation Notes: * This implementation addresses the matching of a Frame class * object to other types of Frames (i.e. the target may be from a * derived class). A Frame will match any other type of Frame with * an acceptable number of axes but will not distinguish axis order * (i.e. it will match the axes in whatever order they are * given). If the template Frame has a value set for its Domain * attribute, then it will only match another Frame with the same * Domain. */ /* Local Variables: */ char *template_domain; /* Pointer to copy of template domain */ const char *ptr; /* Pointer to domain string */ const char *target_domain; /* Pointer to target domain string */ int match; /* Template matches target? */ int match_end; /* Match final axes of target? */ int max_axes; /* Maximum acceptable number of axes */ int min_axes; /* Minimum acceptable nu,ber of axes */ int preserve_axes; /* Preserve target axes? */ int result_axis; /* Loop counter for result axes */ int result_naxes; /* Number of result axes */ int target_naxes; /* Number of target axes */ int template_naxes; /* Number of template axes */ /* Initialise the returned values. */ *template_axes = NULL; *target_axes = NULL; *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* The first requirement for a match is that the target object is a Frame. This is already known to be true, as it forms part of the argument validation for this function. */ /* The second requirement is that the number of target axes is acceptable. Obtain the number of target axes and the minimum and maximum number of axes that the template will match. */ target_naxes = astGetNaxes( target ); min_axes = astGetMinAxes( template ); max_axes = astGetMaxAxes( template ); /* Test if the number of target axes is acceptable. */ if ( astOK ) { match = ( ( target_naxes >= min_axes ) && ( target_naxes <= max_axes ) ); } /* The third requirement is that if the template has its Domain attribute defined, then the target must also have the same Domain (although it need not be set - the default will do). First check if the template has a domain. */ if ( astOK && match ) { if ( astTestDomain( template ) ) { /* Obtain a pointer to the template domain. Then allocate memory and make a copy of it (this is necessary as we will next inquire the domain of the target and may over-write the buffer holding the template's domain). */ ptr = astGetDomain( template ); if ( astOK ) { template_domain = astStore( NULL, ptr, strlen( ptr ) + (size_t) 1 ); /* Obtain a pointer to the target domain. */ target_domain = astGetDomain( target ); /* Compare the domain strings for equality. Then free the memory allocated above. */ match = astOK && !strcmp( template_domain, target_domain ); template_domain = astFree( template_domain ); } } } /* If the template matches, obtain the values of the template's PreserveAxes and MatchEnd attributes and determine the number of template axes. */ if ( astOK && match ) { preserve_axes = astGetPreserveAxes( template ); match_end = astGetMatchEnd( template ); template_naxes = astGetNaxes( template ); /* If the PreserveAxes attribute is non-zero, the target axes should be preserved, so the number of result axes equals the number of target axes. Otherwise the number of template axes is used. */ result_naxes = preserve_axes ? target_naxes : template_naxes; /* Allocate memory for the arrays of axis associations to be returned. */ *template_axes = astMalloc( sizeof( int ) * (size_t) result_naxes ); *target_axes = astMalloc( sizeof( int ) * (size_t) result_naxes ); if ( astOK ) { /* Loop through each of the result axes. */ for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { /* Set up the axis associations. By default, associate the first result axis with the first template/target axis. */ (*template_axes)[ result_axis ] = result_axis; (*target_axes)[ result_axis ] = result_axis; /* However, if the MatchEnd attribute is non-zero, associate the last result axis with the last template/target axis (this only makes a difference if there is a difference in the number of axes). */ if ( match_end ) { (*template_axes)[ result_axis ] += template_naxes - result_naxes; (*target_axes)[ result_axis ] += target_naxes - result_naxes; } /* If any of the associations would be with a template/target axis that doesn't exist, then use an axis index of -1 for the association instead. */ if ( ( (*template_axes)[ result_axis ] < 0 ) || ( (*template_axes)[ result_axis ] >= template_naxes ) ) { (*template_axes)[ result_axis ] = -1; } if ( ( (*target_axes)[ result_axis ] < 0 ) || ( (*target_axes)[ result_axis ] >= target_naxes ) ) { (*target_axes)[ result_axis ] = -1; } } /* Use the target's astSubFrame method to select the required axes from it, overlaying the template's attributes on to the resulting Frame. This process also generates the required Mapping between the target and result Frames. */ match = astSubFrame( target, template, result_naxes, *target_axes, *template_axes, map, result ); } } /* If an error occurred, free any allocated memory and reset the result. */ if ( !astOK || !match ) { *template_axes = astFree( *template_axes ); *target_axes = astFree( *target_axes ); match = 0; } /* Return the result. */ return match; } static void MatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes, int *status ) { /* *++ * Name: c astMatchAxes f AST_MATCHAXES * Purpose: * Find any corresponding axes in two Frames. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astMatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes ) f CALL AST_MATCHAXES( FRM1, FRM2, AXES, STATUS ) * Class Membership: * Frame method. * Description: * This function looks for corresponding axes within two supplied * Frames. An array of integers is returned that contains an element * for each axis in the second supplied Frame. An element in this array * will be set to zero if the associated axis within the second Frame * has no corresponding axis within the first Frame. Otherwise, it * will be set to the index (a non-zero positive integer) of the * corresponding axis within the first supplied Frame. * Parameters: c frm1 f FRM1 = INTEGER (Given) * Pointer to the first Frame. c frm2 f FRM2 = INTEGER (Given) * Pointer to the second Frame. c axes f AXES = INTEGER( * ) (Returned) c Pointer to an f An * integer array in which to return the indices of the axes (within * the first Frame) that correspond to each axis within the second * Frame. Axis indices start at 1. A value of zero will be stored * in the returned array for each axis in the second Frame that has * no corresponding axis in the first Frame. * * The number of elements in this array must be greater than or * equal to the number of axes in the second Frame. f STATUS = INTEGER (Given and Returned) f The global status. * Applicability: * Frame * This function applies to all Frames. * Notes: * - Corresponding axes are identified by the fact that a Mapping can * be found between them using c astFindFrame or astConvert. f AST_FINDFRAME or AST_CONVERT. * Thus, "corresponding axes" are not necessarily identical. For * instance, SkyFrame axes in two Frames will match even if they * describe different celestial coordinate systems *-- * Implementation Notes: * This function is simply a wrap-up for the protected astMatchAxesX * method which performs the required processing but swaps the order * of the first two arguments. This is a trick to allow the * astMatchAxes method to be over-ridden by derived classes on the * basis of the class of either of the first two arguments. * * In practice, each class that represents an encapsulated Frame (e.g. * FrameSet, Region, etc) should over-ride this method, extracting a * Frame from the supplied "frm1" pointer, and then invoking * astMatchAxesX. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the "astMatchAxesX" method with the first two arguments swapped. */ astMatchAxesX( frm2, frm1, axes ); } static void MatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes, int *status ) { /* *+ * Name: * astMatchAxesX * Purpose: * Find any corresponding axes in two Frames. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astMatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes ) * Class Membership: * Frame method. * Description: * This function performs the processing for the public astMatchAxes * method and has exactly the same interface except that the order * of the first two arguments is swapped. This is a trick to allow * the astMatchAxes method to be over-ridden by derived classes on * the basis of the class of either of its first two arguments. * * See the astMatchAxes method for details of the interface. *- */ /* Local Variables: */ AstFrame *pfrm; AstFrame *resfrm; AstMapping *resmap; int *frm1_axes; int *pfrm_axes; int ifirst; int max_axes; int min_axes; int nax2; int pax; int preserve_axes; /* Check the global error status. */ if ( !astOK ) return; /* Temporarily ensure that the PreserveAxes attribute is non-zero in the second supplied Frame. This means thte result Frame returned by astMatch below will have the axis count and order of the target Frame (i.e. "pfrm"). */ if( astTestPreserveAxes( frm1 ) ) { preserve_axes = astGetPreserveAxes( frm1 ) ? 1 : 0; } else { preserve_axes = -1; } astSetPreserveAxes( frm1, 1 ); /* Temporarily ensure that the MaxAxes and MinAxes attributes in the second supplied Frame are set so the Frame can be used as a template in astMatch for matching any number of axes. */ if( astTestMaxAxes( frm1 ) ) { max_axes = astGetMaxAxes( frm1 ); } else { max_axes = -1; } astSetMaxAxes( frm1, 10000 ); if( astTestMinAxes( frm1 ) ) { min_axes = astGetMinAxes( frm1 ); } else { min_axes = -1; } astSetMinAxes( frm1, 1 ); /* Get the number of axes in the frm2 Frame. */ nax2 = astGetNaxes( frm2 ); /* Loop round the axes in the frm2 Frame. */ for( ifirst = 0; ifirst < nax2; ifirst++ ) { /* Identify the primary Frame defining the current axis in the frm2 Frame. */ astPrimaryFrame( frm2, ifirst, &pfrm, &pax ); /* Attempt to find a sub-frame within the frm1 Frame that corresponds to this primary Frame. */ if( astMatch( frm1, pfrm, 1, &frm1_axes, &pfrm_axes, &resmap, &resfrm ) ) { /* Store the one-based index within "frm1" of the corresponding axis. */ axes[ ifirst ] = frm1_axes[ pax ] + 1; /* Free resources */ frm1_axes = astFree( frm1_axes ); pfrm_axes = astFree( pfrm_axes ); resmap = astAnnul( resmap ); resfrm = astAnnul( resfrm ); /* If no corresponding axis was found store zero in the returned array. */ } else { axes[ ifirst ] = 0; } /* Free resouces. */ pfrm = astAnnul( pfrm ); } /* Re-instate the original attribute values in the frm1 Frame. */ if( preserve_axes == -1 ) { astClearPreserveAxes( frm1 ); } else { astSetPreserveAxes( frm1, preserve_axes ); } if( max_axes == -1 ) { astClearMaxAxes( frm1 ); } else { astSetMaxAxes( frm1, max_axes ); } if( min_axes == -1 ) { astClearMinAxes( frm1 ); } else { astSetMinAxes( frm1, min_axes ); } } static void NewUnit( AstAxis *ax, const char *old_units, const char *new_units, const char *method, const char *class, int *status ) { /* * Name: * NewUnit * Purpose: * Modify an Axis Label and Symbol to reflect a new Unit value. * Type: * Private function. * Synopsis: * #include "frame.h" * void NewUnit( AstAxis *ax, const char *old_units, const char *new_units, * const char *method, const char *class ) * Class Membership: * Frame method. * Description: * This function modifies the Label and Symbol attributes of an Axis * to reflect a new Unit value. This function should only be called if * the ActiveUnit flag of the parent Frame is non-zero (this is not * checked within this function). * * If the axis has a set label, then we may be able to modify it to * correctly describe the axis in the supplied new units. For instance, * if the original units were "Hz", the original label was "frequency", * and the new units are "log(Hz)", then the label is modified to become * "log( frequency )". * * The Axis Format attribute is cleared if the supplied units are * different to the old units (because any set format is probably not * going to be appropriate for a new system of units. * Parameters: * ax * Pointer to the Axis. * old_units * The original units value. * new_units * The new units value. * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function * to validate an axis selection. This method name is used * solely for constructing error messages. * class * Pointer to a constant null-terminated character string * containing the name of the class upon which this function * was invoked. This is used solely for constructing error messages. * Returned Value: * void. */ /* Local Variables: */ AstMapping *map; /* Pointer to units Mapping */ char *new_lab; /* Pointer to new axis label */ char *new_sym; /* Pointer to new axis symbol */ /* Check the global error status. */ if ( !astOK ) return; /* Check that the axis label is set. We relay on sub-classes to return appropriate default labels if the label is not set. */ if( astTestAxisLabel( ax ) ) { /* See if it is possible to map the old units into the new units. If it is, then a Mapping is returned together with an appropriately modified label. */ map = astUnitMapper( old_units, new_units, astGetAxisLabel( ax ), &new_lab ); /* If succesfull, annul the Mapping (which we do not need), and store the modified label in the Axis, finally freeing the memory used to hold the modified label. */ if( map ) { map = astAnnul( map ); if( new_lab ) { astSetAxisLabel( ax, new_lab ); new_lab = astFree( new_lab ); } } } /* Do the same for the axis symbol. */ if( astTestAxisSymbol( ax ) ) { map = astUnitMapper( old_units, new_units, astGetAxisSymbol( ax ), &new_sym ); if( map ) { map = astAnnul( map ); if( new_sym ) { astSetAxisSymbol( ax, new_sym ); new_sym = astFree( new_sym ); } } } /* If succesful, clear the axis format if the new and old units are different. */ if( astOK ) { if( strcmp( old_units, new_units ) ) astClearAxisFormat( ax ); } } static void Norm( AstFrame *this, double value[], int *status ) { /* *++ * Name: c astNorm f AST_NORM * Purpose: * Normalise a set of Frame coordinates. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astNorm( AstFrame *this, double value[] ) f CALL AST_NORM( THIS, VALUE, STATUS ) * Class Membership: * Frame method. * Description: c This function normalises a set of Frame coordinate values which f This routine normalises a set of Frame coordinate values which * might be unsuitable for display (e.g. may lie outside the * expected range) into a set of acceptable values suitable for * display. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c value f VALUE( * ) = DOUBLE PRECISION (Given and Returned) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). Initially, this should contain a set of * coordinate values representing a point in the space which the * Frame describes. If these values lie outside the expected * range for the Frame, they will be replaced with more * acceptable (normalised) values. Otherwise, they will be * returned unchanged. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - For some classes of Frame, whose coordinate values are not * constrained, this function will never modify the values * supplied. However, for Frames whose axes represent cyclic * quantities (such as angles or positions on the sky), coordinates * will typically be wrapped into an appropriate standard range, * such as zero to 2*pi. * - The NormMap class is a Mapping which can be used to normalise a * set of points using the c astNorm function f AST_NORM routine * of a specified Frame. * - It is intended to be possible to put any set of coordinates * into a form suitable for display by using this function to * normalise them, followed by appropriate formatting c (using astFormat). f (using AST_FORMAT). *-- */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ int axis; /* Loop counter for axes */ int naxes; /* Number of Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); /* Loop to process the coordinate for each axis in turn. */ for ( axis = 0; axis < naxes; axis++ ) { /* Obtain a pointer to the relevant Frame Axis. */ ax = astGetAxis( this, axis ); /* Normalise the coordinate for this axis. */ astAxisNorm( ax, value + axis ); /* Annul the pointer to the Axis. */ ax = astAnnul( ax ); /* Quit looping if an error occurs. */ if ( !astOK ) break; } } static void NormBox( AstFrame *this, double lbnd[], double ubnd[], AstMapping *reg, int *status ) { /* *+ * Name: * astNormBox * Purpose: * Extend a box to include effect of any singularities in the Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astNormBox( AstFrame *this, double lbnd[], double ubnd[], * AstMapping *reg ) * Class Membership: * Frame method. * Description: * This function modifies a supplied box to include the effect of any * singularities in the co-ordinate system represented by the Frame. * For a normal Cartesian coordinate system, the box will be returned * unchanged. Other classes of Frame may do other things. For instance, * a SkyFrame will check to see if the box contains either the north * or south pole and extend the box appropriately. * Parameters: * this * Pointer to the Frame. * lbnd * An array of double, with one element for each Frame axis * (Naxes attribute). Initially, this should contain a set of * lower axis bounds for the box. They will be modified on exit * to include the effect of any singularities within the box. * ubnd * An array of double, with one element for each Frame axis * (Naxes attribute). Initially, this should contain a set of * upper axis bounds for the box. They will be modified on exit * to include the effect of any singularities within the box. * reg * A Mapping which should be used to test if any singular points are * inside or outside the box. The Mapping should leave an input * position unchanged if the point is inside the box, and should * set all bad if the point is outside the box. *- */ /* This base class returns the box limits unchanged. */ } static double Offset2( AstFrame *this, const double point1[2], double angle, double offset, double point2[2], int *status ){ /* *++ * Name: c astOffset2 f AST_OFFSET2 * Purpose: * Calculate an offset along a geodesic curve in a 2D Frame. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c double astOffset2( AstFrame *this, const double point1[2], double angle, c double offset, double point2[2] ); f RESULT = AST_OFFSET2( THIS, POINT1, ANGLE, OFFSET, POINT2, STATUS ) * Class Membership: * Frame method. * Description: c This function finds the Frame coordinate values of a point which f This routine finds the Frame coordinate values of a point which * is offset a specified distance along the geodesic curve at a * given angle from a specified starting point. It can only be * used with 2-dimensional Frames. * * For example, in a basic Frame, this offset will be along the * straight line joining two points. For a more specialised Frame * describing a sky coordinate system, however, it would be along * the great circle passing through two sky positions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c point1 f POINT1( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of the * point marking the start of the geodesic curve. c angle f ANGLE = DOUBLE PRECISION (Given) * The angle (in radians) from the positive direction of the second * axis, to the direction of the required position, as seen from * the starting position. Positive rotation is in the sense of * rotation from the positive direction of axis 2 to the positive * direction of axis 1. c offset f OFFSET = DOUBLE PRECISION * The required offset from the first point along the geodesic * curve. If this is positive, it will be in the direction of the * given angle. If it is negative, it will be in the opposite * direction. c point2 f POINT2( * ) = DOUBLE PRECISION (Returned) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * in which the coordinates of the required point will be returned. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astOffset2 f AST_OFFSET2 = DOUBLE PRECISION * The direction of the geodesic curve at the end point. That is, the * angle (in radians) between the positive direction of the second * axis and the continuation of the geodesic curve at the requested * end point. Positive rotation is in the sense of rotation from * the positive direction of axis 2 to the positive direction of axis * 1. * Notes: c - The geodesic curve used by this function is the path of f - The geodesic curve used by this routine is the path of * shortest distance between two points, as defined by the c astDistance function. f AST_DISTANCE function. * - An error will be reported if the Frame is not 2-dimensional. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value. *-- */ /* Local Variables: */ int naxes; /* Number of Frame axes */ double result; /* Returned value */ /* Check the global error status. */ result = AST__BAD; if ( !astOK ) return result; /* Initialize bad values. */ point2[ 0 ] = AST__BAD; point2[ 1 ] = AST__BAD; /* Determine the number of Frame axes. */ naxes = astGetNaxes( this ); /* Report an error if the Frame is not 2 dimensional. */ if( naxes != 2 && astOK ) { astError( AST__NAXIN, "astOffset2(%s): Invalid number of Frame axes (%d)." " astOffset2 can only be used with 2 dimensonal Frames.", status, astGetClass( this ), naxes ); } /* Check the supplied values. */ if ( astOK && point1[ 0 ] != AST__BAD && point1[ 1 ] != AST__BAD && angle != AST__BAD && offset != AST__BAD ) { /* Store the results. */ point2[ 0 ] = point1[ 0 ] + sin( angle )*offset; point2[ 1 ] = point1[ 1 ] + cos( angle )*offset; /* The position angle of the curve does not vary in cartesian coordinates */ result = angle; } /* Return the result. */ return result; } static void Offset( AstFrame *this, const double point1[], const double point2[], double offset, double point3[], int *status ) { /* *++ * Name: c astOffset f AST_OFFSET * Purpose: * Calculate an offset along a geodesic curve. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astOffset( AstFrame *this, c const double point1[], const double point2[], c double offset, double point3[] ) f CALL AST_OFFSET( THIS, POINT1, POINT2, OFFSET, POINT3, STATUS ) * Class Membership: * Frame method. * Description: c This function finds the Frame coordinate values of a point which f This routine finds the Frame coordinate values of a point which * is offset a specified distance along the geodesic curve between * two other points. * * For example, in a basic Frame, this offset will be along the * straight line joining two points. For a more specialised Frame * describing a sky coordinate system, however, it would be along * the great circle passing through two sky positions. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c point1 f POINT1( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This should contain the coordinates of the * point marking the start of the geodesic curve. c point2 f POINT2( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis. * This should contain the coordinates of the point marking the * end of the geodesic curve. c offset f OFFSET = DOUBLE PRECISION * The required offset from the first point along the geodesic * curve. If this is positive, it will be towards the second * point. If it is negative, it will be in the opposite * direction. This offset need not imply a position lying * between the two points given, as the curve will be * extrapolated if necessary. c point3 f POINT3( * ) = DOUBLE PRECISION (Returned) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * in which the coordinates of the required point will be returned. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - The geodesic curve used by this function is the path of f - The geodesic curve used by this routine is the path of * shortest distance between two points, as defined by the c astDistance function. f AST_DISTANCE function. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value. * - "Bad" coordinate values will also be returned if the two * points supplied are coincident (or otherwise fail to uniquely * specify a geodesic curve) but the requested offset is non-zero. *-- */ /* Local Variables: */ double delta; /* Displacement along axis */ double dist; /* Distance between points */ double fract; /* Fraction of distance required */ int axis; /* Loop counter for axes */ int naxes; /* Number of Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Determine the number of Frame axes. */ naxes = astGetNaxes( this ); if ( astOK ) { /* Loop to determine the Cartesian distance between points 1 and 2. */ dist = 0.0; for ( axis = 0; axis < naxes; axis++ ) { /* If any of the coordinates supplied is bad, set the distance to be bad and quit looping. */ if ( ( point1[ axis ] == AST__BAD ) || ( point2[ axis ] == AST__BAD ) ) { dist = AST__BAD; break; /* Otherwise, accumulate the sum of squared displacements along each axis. */ } else { delta = point1[ axis ] - point2[ axis ]; dist += ( delta * delta ); } } /* Take the square root to find the distance (if valid). */ if ( dist != AST__BAD ) dist = sqrt( dist ); /* If the distance between the points cannot be found, or the distance is zero but the required offset is non-zero, then set the result coordinates to be bad. */ if ( ( dist == AST__BAD ) || ( ( dist == 0.0 ) && ( offset != 0.0 ) ) ) { for ( axis = 0; axis < naxes; axis++ ) { point3[ axis ] = AST__BAD; } /* Otherwise, calculate what fraction of the distance between the points we need to move, and apply this fraction of the displacement along each axis. */ } else { fract = ( dist == 0.0 ) ? 0.0 : offset / dist; for ( axis = 0; axis < naxes; axis++ ) { point3[ axis ] = point1[ axis ] + fract * ( point2[ axis ] - point1[ axis ] ); } } } } static void Overlay( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { /* *+ * Name: * astOverlay * Purpose: * Overlay the attributes of a template Frame on to another Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astOverlay( AstFrame *template, const int *template_axes, * AstFrame *result ) * Class Membership: * Frame method. * Description: * This function overlays attributes of one Frame (the "template") on to * another Frame, so as to over-ride selected attributes of that second * Frame. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which a Frame acquires attributes from the template, but * retains its original attributes (as the default) if new values have not * previously been explicitly set in the template. * Parameters: * template * Pointer to the template Frame, for which values should have been * explicitly set for any attribute which is to be transferred. * template_axes * Pointer to an array of int, with one element for each axis of the * "result" Frame (see below). For each axis in the result frame, the * corresponding element of this array should contain the (zero-based) * index of the template axis to which it corresponds. This array is used * to establish from which template axis any axis-dependent attributes * should be obtained. * * If any axis in the result Frame is not associated with a template * axis, the corresponding element of this array should be set to -1. * * If a NULL pointer is supplied, the template and result axis * indices are assumed to be identical. * result * Pointer to the Frame which is to receive the new attribute values. *- */ /* Local Variables: */ AstAxis *result_ax; /* Pointer to result Axis object */ AstAxis *template_ax; /* Pointer to template Axis object */ AstSystemType sys; /* System value */ int result_axis; /* Loop counter for result Frame axes */ int result_naxes; /* Number of result Frame axes */ int template_axis; /* Index of template Frame axis */ int template_naxes; /* Number of template Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Define a macro that tests whether an attribute is set in the template and, if so, transfers its value to the target. */ #define OVERLAY(attribute) \ if ( astTest##attribute( template ) ) { \ astSet##attribute( result, astGet##attribute( template ) ); \ } /* Use the macro to transfer each Frame attribute in turn. */ OVERLAY(Dut1); OVERLAY(Digits); OVERLAY(Domain); OVERLAY(Epoch); OVERLAY(Title); OVERLAY(ObsLat) OVERLAY(ObsLon) OVERLAY(ObsAlt) /* Transfer the ActiveUnit flag. */ astSetActiveUnit( result, astGetActiveUnit( template ) ); /* Only overlay the System and AlignSystem attribute if the values are valid for the result class. */ if( astTestSystem( template ) ) { sys = astGetSystem( template ); if( astValidateSystem( result, sys, "astOverlay" ) ) { astSetSystem( result, sys ); } } if( astTestAlignSystem( template ) ) { sys = astGetAlignSystem( template ); if( astValidateSystem( result, sys, "astOverlay" ) ) { astSetAlignSystem( result, sys ); } } /* Now transfer attributes associated with individual axes. Obtain the number of axes in the template and result Frames. */ template_naxes = astGetNaxes( template ); result_naxes = astGetNaxes( result ); if ( astOK ) { /* Loop through all the axes in the result Frame and determine to which template axis each one corresponds. Check that the resulting axis index is valid. If not, then the axis will not receive new attributes. */ for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { template_axis = template_axes ? template_axes[ result_axis ] : result_axis; if ( ( template_axis >= 0 ) && ( template_axis < template_naxes ) ) { /* Obtain pointers to the relevant Axis objects of each Frame and use the astAxisOverlay method of the template Axis to overlay attributes on to the result Axis. Annul the Axis pointers afterwards. */ template_ax = astGetAxis( template, template_axis ); result_ax = astGetAxis( result, result_axis ); astAxisOverlay( template_ax, result_ax ); template_ax = astAnnul( template_ax ); result_ax = astAnnul( result_ax ); /* Quit looping if an error occurs. */ if ( !astOK ) break; } } } /* Undefine macros local to this function. */ #undef OVERLAY } static void PermAxes( AstFrame *this, const int perm[], int *status ) { /* *+ * Name: * astPermAxes * Purpose: * Permute the order of a Frame's axes. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astPermAxes( AstFrame *this, const int perm[] ) * Class Membership: * Frame method. * Description: * This function permutes the order in which a Frame's axes occur. * Parameters: * this * Pointer to the Frame. * perm * An array of int (with one element for each axis of the Frame) * which lists the axes in their new order. Each element of this * array should be a (zero-based) axis index identifying the * axes according to their old (un-permuted) order. * Notes: * - Only genuine permutations of the axis order are permitted, so * each axis must be referenced exactly once in the "perm" array. * - If more than one axis permutation is applied to a Frame, the * effects are cumulative. *- * Implementation Notes: * - This function implements the basic astPermAxes method which is * available via the protected interface to the Frame class. A * public interface to this method is provided by the * astPermAxesId_ function. */ /* Local Variables: */ int *old; /* Pointer to copy of old permutation array */ int axis; /* Loop counter for Frame axes */ int naxes; /* Number of Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Validate the permutation array, to check that it describes a genuine permutation. */ astCheckPerm( this, perm, "astPermAxes" ); /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); /* Allocate memory and use it to store a copy of the old permutation array for the Frame. */ old = astStore( NULL, this->perm, sizeof( int ) * (size_t) naxes ); /* Apply the new axis permutation cumulatively to the old one and store the result in the Frame. */ if ( astOK ) { for ( axis = 0; axis < naxes; axis++ ) { this->perm[ axis ] = old[ perm[ axis ] ]; } } /* Free the temporary copy of the old array. */ old = astFree( old ); } static AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], AstMapping **map, int *status ) { /* *+ * Name: * astPickAxes * Purpose: * Create a new Frame by picking axes from an existing one. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], * AstMapping **map ) * Class Membership: * Frame method. * Description: * This function creates a new Frame whose axes are copies of axes * picked from an existing Frame. Other Frame attributes are also * copied to the new Frame. Zero or more of the original axes may * be picked in any order, but each can be used only * once. Additional axes (with default characteristics) may be * included in the new Frame if required. * * Optionally, a Mapping that converts between the original Frame's * axes and those of the new Frame may also be returned. * Parameters: * this * Pointer to the original Frame. * naxes * The number of axes required in the new Frame. * axes * Pointer to an array of int with naxes elements. This should * contain (zero based) axis indices specifying the axes which * are to be included in the new Frame, in the order * required. Each axis index may occur only once. * * If additional (default) axes are also to be included, the * corresponding elements of this array should be set to -1. * map * Address of a location to receive a pointer to a new * Mapping. This will be a PermMap (or a UnitMap as a special * case) that describes the axis permutation that has taken * place between the original and new Frames. The forward * transformation will convert from the original Frame's axes to * the new one's, and vice versa. * * If this Mapping is not required, a NULL value may be supplied * for this parameter. * Returned Value: * Pointer to the new Frame. * Notes: * - The class of object returned may differ from that of the * original Frame, depending on which axes are selected. For * example, if a single axis is picked from a SkyFrame (which * always has two axes), the resulting Frame cannot be a valid * SkyFrame, so will revert to the parent class (Frame) instead. * - The new Frame contains a deep copy of all the data selected * from the original Frame. Modifying the new Frame will therefore * not affect the original one. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- * Implementation Notes: * - This function implements the basic astPickAxes method * available via the protected interface to the Frame class. The * public interface to this method is provided by the * astPickAxesId_ function. */ /* Local Variables: */ AstFrame *frame; /* Pointer to Frame to be returned */ AstMapping *mapping; /* Pointer to Mapping to be returned */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the returned pointers. */ frame = NULL; if ( map ) *map = NULL; /* Check that a valid set of axes is being selected . */ astValidateAxisSelection( this, naxes, axes, "astPickAxes" ); /* Create the required new Frame by selecting the axes. This also returns a Mapping which transforms between the original Frame and the new one. */ astSubFrame( this, NULL, naxes, axes, NULL, &mapping, &frame ); if ( astOK ) { /* Return the Mapping pointer if required. */ if ( map ) { *map = mapping; /* Otherwise annul the Mapping. If an error occurs, also annul the Frame. */ } else { mapping = astAnnul( mapping ); if ( !astOK ) frame = astAnnul( frame ); } } /* Return the pointer to the new Frame. */ return frame; } static void PrimaryFrame( AstFrame *this, int axis1, AstFrame **frame, int *axis2, int *status ) { /* *+ * Name: * astPrimaryFrame * Purpose: * Uniquely identify a primary Frame and one of its axes. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astPrimaryFrame( AstFrame *this, int axis1, AstFrame **frame, * int *axis2 ) * Class Membership: * Frame method. * Description: * This function returns information about the underlying (primary) Frame * corresponding to a specified axis, when given what may be a compound * Frame composed of more than one simpler one. * Parameters: * this * Pointer to the Frame. * axis1 * An axis index (zero-based) identifying the Frame axis for which * information is required. * frame * Address of a location to receive a pointer to the underlying (primary) * frame to which the requested axis belongs (i.e. this will not be a * compound Frame). * axis2 * Pointer to an int which is to receive the (zero-based) axis * index within "frame" which identifies the axis being referred * to, using the axis order that applied when the primary Frame * was originally constructed (i.e. this function undoes all * subsequent axis pemutations and the effects of combining * Frames, in order to reveal the original underlying axis * order). * Notes: * - This protected method is provided so that class implementations can * distinguish the axes of frames from one another (e.g. can distinguish * a longitude axis as being different from a latitide axis) even after * their order has been permuted and they have been combined with axes from * other Frames. * - The reference count of the primary Frame will be incremented by one to * reflect the new pointer returned. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise the returned values. */ *frame = NULL; *axis2 = 0; /* Validate and permute the axis index supplied. */ axis1 = astValidateAxis( this, axis1, 1, "astPrimaryFrame" ); /* Since "this" is a primary Frame (i.e. is not compound), simply clone a pointer to it. */ if ( astOK ) *frame = astClone( this ); /* Return the permuted axis index, which refers to the original axis order. */ if ( astOK ) *axis2 = axis1; } double astReadDateTime_( const char *value, int *status ) { /* *+ * Name: * astReadDateTime * Purpose: * Read a date/time string. * Type: * Private function. * Synopsis: * #include "frame.h" * double astReadDateTime( const char *value ) * Class Membership: * Frame member function. * Description: * This function reads a date/time string in a variety of formats and * returns the resulting time as a Modified Julian Date. If the string * cannot be interpreted as a date/time or contains invalid values, an * error is reported. * Parameters: * value * Pointer to a null terminated string containing the value to be read. * Returned Value: * The time as a Modified Julian date. * Date/Time Formats: * The date/time formats supported by this function are listed below. These * are interpreted in a case-insensitive manner and the function is * generally flexible about the presence of additional white space and the * use of alternative field delimiters. * * Besselian Epoch * Expressed in decimal years, with or without decimal places * ("B1950" or "B1976.13", for example). * Julian Epoch * Expressed in decimal years, with or without decimal places * ("J2000" or "J2100.9", for example). * Year * Decimal years, with or without decimal places ("1996.8" for example). * Such values are interpreted as a Besselian epoch (see above) if less * than 1984.0 and as a Julian epoch otherwise. * Julian Date * With or without decimal places ("JD 2454321.9" for example). * Modified Julian Date * With or without decimal places ("MJD 54321.4" for example). * Gregorian Calendar Date * With the month expressed as an integer or 3-character * abbreviation, and with optional decimal places to represent a * fraction of a day ("1996-10-2" or "1996-Oct-2.6" for * example). If no fractional part of a day is given, the time * refers to the start of the day (zero hours). * Gregorian Date and Time * Any calendar date (as above) but with a fraction of a day expressed * as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). * The date and time can be separated by a space or by a "T" (as used * by ISO8601). * Notes: * - The date/time value is interpreted as a calendar date and time, not * linked to any particular time system. Thus, interpretation of hours, * minutes and seconds is done in the obvious manner assuming 86400 seconds * in a day. No allowance for is made, for instance, for leap seconds or for * the varying length of a second in some time systems. * - A value of AST__BAD is returned if this function is invoked with the * global error status set or if it should fail for any reason. *- */ /* Local Vaiables: */ char cmonth[ 4 ]; /* Buffer for name of month */ char sep1[ 2 ]; /* Year/month separator string */ char sep2[ 2 ]; /* Month/day separator string */ char sep3[ 2 ]; /* Hour/minute separator string */ char sep4[ 2 ]; /* Minute/second separator string */ char *cc; /* Pointer to copy of remaining text */ const char *v; /* Pointer into value string */ const char *p; /* Pointer to date/time separator */ double day; /* Day number plus fraction of whole day */ double epoch; /* Epoch stored as decimal years */ double hms; /* Hours, min & sec as fraction of a day */ double jd; /* Julian Date */ double mjd; /* Modified Julian Date */ double result; /* Result to be returned */ double sec; /* Seconds and fractions of a second */ int hour; /* Number of hours */ int iday; /* Number of whole days */ int l; /* Length of string remaining */ int len; /* Length of string */ int match; /* Date/time string has correct form? */ int minute; /* Number of minutes */ int month; /* Number of months */ int nc; /* Number of characters read from string */ int stat; /* Status return from SLALIB functions */ int year; /* Number of years */ /* Check the global error status. */ if ( !astOK ) return AST__BAD; /* Initialise. */ result = AST__BAD; /* Obtain the length of the input string. */ len = (int) strlen( value ); /* Attempt to read the string using each recognised format in turn. */ /* Besselian epoch in decimal years (e.g. "B1950.0"). */ /* ================================================== */ if ( nc = 0, ( 1 == astSscanf( value, " %*1[Bb] %lf %n", &epoch, &nc ) ) && ( nc >= len ) ) { /* Convert to Modified Julian Date. */ result = palEpb2d( epoch ); /* Julian epoch in decimal years (e.g. "J2000.0"). */ /* =============================================== */ } else if ( nc = 0, ( 1 == astSscanf( value, " %*1[Jj] %lf %n", &epoch, &nc ) ) && ( nc >= len ) ) { /* Convert to Modified Julian Date. */ result = palEpj2d( epoch ); /* Decimal years (e.g. "1976.2"). */ /* ============================== */ } else if ( nc = 0, ( 1 == astSscanf( value, " %lf %n", &epoch, &nc ) ) && ( nc >= len ) ) { /* Convert to Modified Julian Date, treating the epoch as Julian or Besselian depending on whether it is 1984.0 or later. */ result = ( epoch < 1984.0 ) ? palEpb2d( epoch ) : palEpj2d( epoch ); /* Modified Julian Date (e.g. "MJD 54321.0"). */ /* ============================================ */ } else if ( nc = 0, ( 1 == astSscanf( value, " %*1[Mm] %*1[Jj] %*1[Dd] %lf %n", &mjd, &nc ) ) && ( nc >= len ) ) { /* Use the result directly. */ result = mjd; /* Julian Date (e.g. "JD 2454321.5"). */ /* ==================================== */ } else if ( nc = 0, ( 1 == astSscanf( value, " %*1[Jj] %*1[Dd] %lf %n", &jd, &nc ) ) && ( nc >= len ) ) { /* Convert to Modified Julian Date. */ result = jd - 2400000.5; /* Gregorian calendar date (e.g. "1996-10-2" or "1996-Oct-2"). */ /* =========================================================== */ /* This format also allows day fractions expressed as decimal days, e.g: "1996-Oct-2.5001" or as hours, minutes and seconds, e.g: "1996-Oct-2 12:14:30.52" Various alternative field delimiters are also allowed. */ } else { /* Note that the method used to parse this format relies heavily on conditional execution controlled by "&&" and "||" operators. Initialise the variables used. */ v = value; l = len; *cmonth = '\0'; year = month = iday = hour = minute = 0; day = sec = 0.0; /* Identify the year and month. */ /* ---------------------------- */ /* Try to match an initial " 1996 - 10 -" or " 1996 10 " or similar. */ match = ( nc = 0, ( 4 == astSscanf( v, " %d %1[:/-] %2d %1[:/-]%n", &year, sep1, &month, sep2, &nc ) ) ); match = match || ( nc = 0, ( 4 == astSscanf( v, " %d%1[ ] %2d%1[ ]%n", &year, sep1, &month, sep2, &nc ) ) ); /* If that failed, allow " 1996 - Oct -" or " 1996 Oct " or similar. */ match = match || ( nc = 0, ( 4 == astSscanf( v, " %d %1[:/-] %3[ABCDEFGHIJKLMNOPQRSTUVWXYZ" "abcdefghijklmnopqrstuvwxyz] %1[:/-]%n", &year, sep1, cmonth, sep2, &nc ) ) ); match = match || ( nc = 0, ( 4 == astSscanf( v, " %d%1[ ] %3[ABCDEFGHIJKLMNOPQRSTUVWXYZ" "abcdefghijklmnopqrstuvwxyz]%1[ ]%n", &year, sep1, cmonth, sep2, &nc ) ) ); /* Alternative field separators are permitted above, but ensure that they are both the same. */ match = match && ( *sep1 == *sep2 ); /* Identify the day and fraction of day. */ /*-------------------------------------- */ /* If the above matched correctly, modify the string pointer "v" to the next character to be interpreted and decrement the remaining string length. */ if ( match ) { v += nc; l -= nc; /* ISO8601 format uses the litter T as a delimiter between the date and time. If there is a T in the remaining string, take a copy and change the T to a space. */ p = strchr( v, 'T' ); if( p ) { cc = astStore( NULL, v, l + 1 ); cc[ p - v ] = ' '; v = cc; } else { cc = NULL; } /* We now try to match the following characters but without reading any values. This is done to ensure the string has the correct form (e.g. exclude "-" signs and exponents in numbers, which are otherwise hard to detect). */ /* Try to match " 12.3456 " or similar. */ match = ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789].%*[0123456789] %n", &nc ) ) && ( nc == l ) ); /* If that failed, then try to match " 12. " or similar. */ match = match || ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789]. %n", &nc ) ) && ( nc == l ) ); /* If that also failed, then try to match just " 12 " or similar. */ match = match || ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789] %n", &nc ) ) && ( nc == l ) ); /* If any of the above patterns matched, now read the data (the day number) as a double value. */ if ( match ) { match = ( nc = 0, ( 1 == astSscanf( v, " %lf %n", &day, &nc ) ) && ( nc == l ) ); /* If none of the above matched, then look to see if the day fraction has been given in hours, minutes and seconds by trying to match " 12 03 : 45 :" or " 12 13 45 " or similar. */ } else { match = ( nc = 0, ( 5 == astSscanf( v, " %2d%*1[ ] %2d %1[:/-] %2d %1[:/-]%n", &iday, &hour, sep3, &minute, sep4, &nc ) ) ); match = match || ( nc = 0, ( 5 == astSscanf( v, " %2d%*1[ ] %2d%1[ ] %2d%1[ ]%n", &iday, &hour, sep3, &minute, sep4, &nc ) ) ); /* Alternative field separators are permitted above, but ensure that they are both the same. */ match = match && ( *sep3 == *sep4 ); /* If the day number was read as an integer, convert it to double. */ if ( match ) day = (double) iday; /* If no match, see if we can get a match without a trailing seconds field. */ if( !match ) { match = ( nc = 0, ( 4 == astSscanf( v, " %2d%*1[ ] %2d %1[:/-] %2d %n", &iday, &hour, sep3, &minute, &nc ) && ( nc == l ) ) ); match = match || ( nc = 0, ( 4 == astSscanf( v, " %2d%*1[ ] %2d%1[ ] %2d %n", &iday, &hour, sep3, &minute, &nc ) && ( nc == l ) ) ); /* If the day number was read as an integer, convert it to double. */ if ( match ) day = (double) iday; /* Otherwise, identify the seconds field. */ /* -------------------------------------- */ /* If hours and minutes fields have been matched, now look for the final seconds (and fractions of seconds) field. This is similar to the day/fraction field (see earlier) in that we first check that it has the correct form before reading its value. */ /* Adjust the string pointer and remaining string length. */ } else { v += nc; l -= nc; /* Try to match " 12.3456 " or similar. */ match = ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789].%*[0123456789] %n", &nc ) ) && ( nc == l ) ); /* If that failed, then try to match " 12. " or similar. */ match = match || ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789]. %n", &nc ) ) && ( nc == l ) ); /* If that also failed, then try to match just " 12 " or similar. */ match = match || ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789] %n", &nc ) ) && ( nc == l ) ); /* If any of the above patterns matched, now read the data (the number of seconds) as a double value. */ if ( match ) { match = ( nc = 0, ( 1 == astSscanf( v, " %lf %n", &sec, &nc ) ) && ( nc == l ) ); } } } /* Free resources */ if( cc ) cc = astFree( cc ); } /* Interpret the values that were read. */ /* ------------------------------------ */ /* We execute this if all of the above text matching was successful, transferred the required number of data values, and consumed the entire input string. */ if ( match ) { /* See if the month was given as a character string (e.g. "Oct") instead of a number. If so, define local variables for use in converting it. */ if ( *cmonth ) { char lcmonth[ 4 ]; /* Lower case copy of month string */ const char *ptr; /* Pointer result from look up */ const char *table = /* Month look up table */ "jan feb mar apr may jun jul aug sep oct nov dec"; int i; /* Loop counter for characters */ /* Convert the month string to lower case. */ for ( i = 0; cmonth[ i ]; i++ ) { lcmonth[ i ] = tolower( cmonth[ i ] ); } lcmonth[ i ] = '\0'; /* Look the month up in the table of months and generate the required month number. */ if ( ( ptr = strstr( table, lcmonth ) ) ) { month = 1 + ( ptr - table ) / 4; /* If the lookup failed, report an error. */ } else { astError( AST__DTERR, "Month value \"%s\" is invalid.", status, cmonth ); } } /* If OK, extract the integral day number and convert years, months and days to a Modified Julian Date. */ if ( astOK ) { iday = (int) day; palCaldj( year, month, iday, &mjd, &stat ); /* Examine the return status from the conversion and report an appropriate error if necessary. */ switch ( stat ) { case 1: astError( AST__DTERR, "Year value (%d) is invalid.", status, year ); break; case 2: astError( AST__DTERR, "Month value (%d) is invalid.", status, month ); break; case 3: astError( AST__DTERR, "Day value (%.*g) is invalid.", status, DBL_DIG, day ); break; /* If conversion to MJD was successful, add any fractional part of a day to the result. */ default: mjd += ( day - (double) iday ); /* Convert hours, minutes and seconds to a fraction of a day (this will give zero if none of these quantities was supplied). */ palDtf2d( hour, minute, sec, &hms, &stat ); /* Examine the return status from the conversion and report an appropriate error if necessary. */ switch ( stat ) { case 1: astError( AST__DTERR, "Hour value (%d) is invalid.", status, hour ); break; case 2: astError( AST__DTERR, "Minute value (%d) is invalid.", status, minute ); break; case 3: astError( AST__DTERR, "Seconds value (%.*g) is invalid.", status, DBL_DIG, sec ); break; /* Add the fraction of a day derived from hours, minutes and seconds fields to the result. */ default: mjd += hms; break; } break; } /* Return the result, if no error occurred. */ if ( astOK ) result = mjd; } /* If none of the supported date/time formats matched, then report an error. */ } else { astError( AST__DTERR, "Date/time does not have the correct form." , status); } } /* Return the result. */ return result; } static void ReportPoints( AstMapping *this_mapping, int forward, AstPointSet *in_points, AstPointSet *out_points, int *status ) { /* * Name: * ReportPoints * Purpose: * Report the effect of transforming a set of points using a Frame. * Type: * Private function. * Synopsis: * #include "mapping.h" * void ReportPoints( AstMapping *this, int forward, * AstPointSet *in_points, AstPointSet *out_points, int *status ) * Class Membership: * Frame member function (over-rides the protected astReportPoints * method inherited from the Mapping class). * Description: * This function reports the coordinates of a set of points before * and after being transformed by a Frame, by writing them to * standard output. * Parameters: * this * Pointer to the Frame. * forward * A non-zero value indicates that the Frame's forward * coordinate transformation has been applied, while a zero * value indicates the inverse transformation. * in_points * Pointer to a PointSet which is associated with the * coordinates of a set of points before the Frame was applied. * out_points * Pointer to a PointSet which is associated with the * coordinates of the same set of points after the Frame has * been applied. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *this; /* Pointer to the Frame structure */ double **ptr_in; /* Pointer to array of input data pointers */ double **ptr_out; /* Pointer to array of output data pointers */ int coord; /* Loop counter for coordinates */ int ncoord_in; /* Number of input coordinates per point */ int ncoord_out; /* Number of output coordinates per point */ int npoint; /* Number of points to report */ int npoint_in; /* Number of input points */ int npoint_out; /* Number of output points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_mapping; /* Obtain the numbers of points and coordinates associated with each PointSet. */ npoint_in = astGetNpoint( in_points ); npoint_out = astGetNpoint( out_points ); ncoord_in = astGetNcoord( in_points ); ncoord_out = astGetNcoord( out_points ); /* Obtain the pointers that give access to the coordinate data associated with each PointSet. */ ptr_in = astGetPoints( in_points ); ptr_out = astGetPoints( out_points ); /* In the event that both PointSets don't contain equal numbers of points (this shouldn't actually happen), simply use the minimum number. */ npoint = ( npoint_in < npoint_out ) ? npoint_in : npoint_out; /* Loop to report the effect of the transformation on each point in turn. */ for ( point = 0; point < npoint; point++ ) { /* Report the input coordinates (in parentheses and separated by commas). Format each value for display using the Frame's astFormat method. */ printf( "(" ); for ( coord = 0; coord < ncoord_in; coord++ ) { printf( "%s%s", coord ? ", " : "", astFormat( this, coord, ptr_in[ coord ][ point ] ) ); } /* Similarly report the output coordinates. */ printf( ") --> (" ); for ( coord = 0; coord < ncoord_out; coord++ ) { printf( "%s%s", coord ? ", " : "", astFormat( this, coord, ptr_out[ coord ][ point ] ) ); } printf( ")\n" ); } } static void Resolve( AstFrame *this, const double point1[], const double point2[], const double point3[], double point4[], double *d1, double *d2, int *status ){ /* *++ * Name: c astResolve f AST_RESOLVE * Purpose: * Resolve a vector into two orthogonal components * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astResolve( AstFrame *this, const double point1[], c const double point2[], const double point3[], c double point4[], double *d1, double *d2 ); f CALL AST_RESOLVE( THIS, POINT1, POINT2, POINT3, POINT4, D1, D2, f STATUS ) * Class Membership: * Frame method. * Description: c This function resolves a vector into two perpendicular components. f This routine resolves a vector into two perpendicular components. * The vector from point 1 to point 2 is used as the basis vector. * The vector from point 1 to point 3 is resolved into components * parallel and perpendicular to this basis vector. The lengths of the * two components are returned, together with the position of closest * aproach of the basis vector to point 3. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c point1 f POINT1( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This marks the start of the basis vector, * and of the vector to be resolved. c point2 f POINT2( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This marks the end of the basis vector. c point3 f POINT3( * ) = DOUBLE PRECISION (Given) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * (Naxes attribute). This marks the end of the vector to be * resolved. c point4 f POINT4( * ) = DOUBLE PRECISION (Returned) c An array of double, with one element for each Frame axis f An array with one element for each Frame axis * in which the coordinates of the point of closest approach of the * basis vector to point 3 will be returned. c d1 f D1 = DOUBLE PRECISION (Returned) c The address of a location at which to return the distance from f The distance from * point 1 to point 4 (that is, the length of the component parallel * to the basis vector). Positive values are in the same sense as * movement from point 1 to point 2. c d2 f D2 = DOUBLE PRECISION (Returned) c The address of a location at which to return the distance from f The distance from * point 4 to point 3 (that is, the length of the component * perpendicular to the basis vector). The value is always positive. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: c - Each vector used in this function is the path of f - Each vector used in this routine is the path of * shortest distance between two points, as defined by the c astDistance function. f AST_DISTANCE function. * - This function will return "bad" coordinate values (AST__BAD) * if any of the input coordinates has this value, or if the required * output values are undefined. *-- */ /* Local Variables: */ double bv; /* Length of basis vector */ double c; /* Component length */ double dp; /* Dot product */ int axis; /* Loop counter for axes */ int naxes; /* Number of Frame axes */ int ok; /* OK to proceed? */ /* Check the global error status. */ *d1 = AST__BAD; *d2 = AST__BAD; if ( !astOK ) return; /* Determine the number of Frame axes. */ naxes = astGetNaxes( this ); /* Initialize bad values, and check if the supplied vectors are good. */ ok = 1; for( axis = 0; axis < naxes; axis++ ){ point4[ axis ] = AST__BAD; if( point1[ axis ] == AST__BAD || point2[ axis ] == AST__BAD || point3[ axis ] == AST__BAD ) ok = 0; } /* Check the supplied values. */ if ( ok ) { /* Find the dot product of the basis vector with the vector joining point 1 and point 3. At the same time form the squared length of the basis vector. */ dp = 0.0; bv = 0.0; for( axis = 0; axis < naxes; axis++ ){ c = point2[ axis ] - point1[ axis ]; dp += c * ( point3[ axis ] - point1[ axis ] ); bv += c * c; } /* Check the basis vector does not have zero length, and convert the squared length into a length. */ if( bv > 0.0 ) { bv = sqrt( bv ); /* The dot product is the required distance d1 multiplied by the length of the basis vector. Form the distance d1. */ *d1 = dp/bv; /* Offset away from point 1 towards point 2 by a distance of d1. */ for( axis = 0; axis < naxes; axis++ ){ point4[ axis ] = point1[ axis ] + (*d1/bv)*( point2[ axis ] - point1[ axis ] ); } /* Finally, form the required length d2. */ *d2 = 0.0; for( axis = 0; axis < naxes; axis++ ){ c = ( point3[ axis ] - point4[ axis ] ); *d2 += c*c; } *d2 = sqrt( *d2 ); } } return; } static AstPointSet *ResolvePoints( AstFrame *this, const double point1[], const double point2[], AstPointSet *in, AstPointSet *out, int *status ) { /* *+ * Name: * astResolvePoints * Purpose: * Resolve a set of vectors into orthogonal components * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstPointSet *astResolvePoints( AstFrame *this, const double point1[], * const double point2[], AstPointSet *in, * AstPointSet *out ) * Class Membership: * Frame method. * Description: * This function takes a Frame and a set of vectors encapsulated * in a PointSet, and resolves each one into two orthogonal components, * returning these two components in another PointSet. * * This is exactly the same as the public astResolve method, except * that this method allows many vectors to be processed in a single call, * thus reducing the computational cost of overheads of many * individual calls to astResolve. * Parameters: * this * Pointer to the Frame. * point1 * An array of double, with one element for each Frame axis * (Naxes attribute). This marks the start of the basis vector, * and of the vectors to be resolved. * point2 * An array of double, with one element for each Frame axis * (Naxes attribute). This marks the end of the basis vector. * in * Pointer to the PointSet holding the ends of the vectors to be * resolved. * out * Pointer to a PointSet which will hold the length of the two * resolved components. A NULL value may also be given, in which * case a new PointSet will be created by this function. * Returned Value: * Pointer to the output (possibly new) PointSet. The first axis will * hold the lengths of the vector components parallel to the basis vector. * These values will be signed (positive values are in the same sense as * movement from point 1 to point 2. The second axis will hold the lengths * of the vector components perpendicular to the basis vector. These * values will be signed only if the Frame is 2-dimensional, in which * case a positive value indicates that rotation from the basis vector * to the tested vector is in the same sense as rotation from the first * to the second axis of the Frame. * Notes: * - The number of coordinate values per point in the input * PointSet must match the number of axes in the supplied Frame. * - If an output PointSet is supplied, it must have space for * sufficient number of points and 2 coordinate values per point. * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * - We assume flat geometry throughout this function. Other classes, * (e.g. SkyFrame) will override this method using more appropriate * geometry. *- */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_in; /* Pointers to input axis values */ double **ptr_out; /* Pointers to returned axis values */ double *basisv; /* Pointer to array holding basis vector */ double *d1; /* Pointer to next parallel component value */ double *d2; /* Pointer to next perpendicular component value */ double *ip; /* Pointer to next input axis value */ double bv; /* Length of basis vector */ double c; /* Constant value */ double d; /* Component length */ double dp; /* Dot product */ double x1; /* First axis of basis vector */ double x2; /* First axis of test vector */ double y1; /* Second axis of basis vector */ double y2; /* Second axis of test vector */ int axis; /* Loop counter for axes */ int ipoint; /* Index of next point */ int nax; /* Number of Frame axes */ int ncoord_in; /* Number of input PointSet coordinates */ int ncoord_out; /* Number of coordinates in output PointSet */ int npoint; /* Number of points to transform */ int npoint_out; /* Number of points in output PointSet */ int ok; /* OK to proceed? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain the number of axes in the Frame. */ nax = astGetNaxes( this ); /* Obtain the number of input vectors to resolve and the number of coordinate values per vector. */ npoint = astGetNpoint( in ); ncoord_in = astGetNcoord( in ); /* If OK, check that the number of input coordinates matches the number required by the Frame. Report an error if these numbers do not match. */ if ( astOK && ( ncoord_in != nax ) ) { astError( AST__NCPIN, "astResolvePoints(%s): Bad number of coordinate " "values (%d) in input %s.", status, astGetClass( this ), ncoord_in, astGetClass( in ) ); astError( AST__NCPIN, "The %s given requires %d coordinate value(s) for " "each input point.", status, astGetClass( this ), nax ); } /* If still OK, and a non-NULL pointer has been given for the output PointSet, then obtain the number of points and number of coordinates per point for this PointSet. */ if ( astOK && out ) { npoint_out = astGetNpoint( out ); ncoord_out = astGetNcoord( out ); /* Check that the dimensions of this PointSet are adequate to accommodate the output coordinate values and report an error if they are not. */ if ( astOK ) { if ( npoint_out < npoint ) { astError( AST__NOPTS, "astResolvePoints(%s): Too few points (%d) in " "output %s.", status, astGetClass( this ), npoint_out, astGetClass( out ) ); astError( AST__NOPTS, "The %s needs space to hold %d transformed " "point(s).", status, astGetClass( this ), npoint ); } else if ( ncoord_out < 2 ) { astError( AST__NOCTS, "astResolvePoints(%s): Too few coordinate " "values per point (%d) in output %s.", status, astGetClass( this ), ncoord_out, astGetClass( out ) ); astError( AST__NOCTS, "The %s supplied needs space to store 2 " "coordinate value(s) per transformed point.", status, astGetClass( this ) ); } } } /* If all the validation stages are passed successfully, and a NULL output pointer was given, then create a new PointSet to encapsulate the output coordinate data. */ if ( astOK ) { if ( !out ) { result = astPointSet( npoint, 2, "", status ); /* Otherwise, use the PointSet supplied. */ } else { result = out; } } /* Get pointers to the input and output axis values */ ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Store points to the first two axis arrays in the returned PointSet. */ d1 = ptr_out[ 0 ]; d2 = ptr_out[ 1 ]; /* Allocate work space. */ basisv = astMalloc( sizeof( double )*(size_t) nax ); /* If the Frame has only one axis, then the supplied basic vector is irrelevant - the returned perpendicular distances are always zero and the returned parallel distances are just the distances from point1 to each input point. */ if( nax < 2 && basisv ) { ip = ptr_in[ 0 ]; for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++, ip++ ) { *d1 = astAxDistance( this, 1, point1[0], *ip ); *d2 = 0.0; } /* Now deal with Frames which have 2 or more axes */ } else if( basisv ){ /* Check if the supplied positions defining the basis vector are good. Store the basis vector, and get its squared length. */ ok = 1; bv = 0.0; for( axis = 0; axis < nax; axis++ ){ if( point1[ axis ] == AST__BAD || point2[ axis ] == AST__BAD ) { ok = 0; break; } else { basisv[ axis ] = point2[ axis ] - point1[ axis ]; bv += basisv[ axis ]*basisv[ axis ]; } } /* Check the basis vector does not have zero length, and convert the squared length into a length. */ if( ok && bv > 0.0 ) { bv = sqrt( bv ); } else { ok = 0; } /* Store points to the first two axis arrays in the returned PointSet. */ d1 = ptr_out[ 0 ]; d2 = ptr_out[ 1 ]; /* Check supplied values can be used */ if( ok ) { /* Loop round each supplied vector. */ for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++ ) { /* Find the dot product of the basis vector with the vector joining point 1 and the end of the current vector. */ ok = 1; dp = 0.0; for( axis = 0; axis < nax; axis++ ){ d = ptr_in[ axis ][ ipoint ] - point1[ axis ]; if( d != AST__BAD ) { dp += basisv[ axis ] * d; } else { ok = 0; break; } } /* If this input position is good... */ if( ok ) { /* The dot product is the required parallel component length multiplied by the length of the basis vector. Form the distance d1. */ *d1 = dp/bv; /* Offset away from point 1 towards point 2 by a distance of d1, and form the required length d2. */ c = *d1/bv; if( nax > 2 ) { *d2 = 0.0; for( axis = 0; axis < nax; axis++ ){ d = ptr_in[ axis ][ ipoint ] - ( point1[ axis ] + c*basisv[ axis ] ); *d2 += d*d; } *d2 = sqrt( *d2 ); /* If the Frame is 2 dimensional, we can give a sign the the perpendicular component. */ } else { x1 = c*basisv[ 0 ]; y1 = c*basisv[ 1 ]; x2 = ptr_in[ 0 ][ ipoint ] - ( point1[ 0 ] + x1 ); y2 = ptr_in[ 1 ][ ipoint ] - ( point1[ 1 ] + y1 ); *d2 = sqrt( x2*x2 + y2*y2 ); if( x1*y2 - x2*y1 < 0.0 ) *d2 = -(*d2); } /* If this input vector is bad, put bad values in the output */ } else { *d1 = AST__BAD; *d2 = AST__BAD; } } /* If supplied values cannot be used, fill the returned PointSet with bad values */ } else { for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++ ) { *d1 = AST__BAD; *d2 = AST__BAD; } } } /* Free resources */ basisv = astFree( basisv ); /* Annul the returned PointSet if an error occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static void SetActiveUnit( AstFrame *this, int value, int *status ){ /* *++ * Name: c astSetActiveUnit f AST_SETACTIVEUNIT * Purpose: * Specify how the Unit attribute should be used. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astSetActiveUnit( AstFrame *this, int value ) f CALL AST_SETACTIVEUNIT( THIS, VALUE, STATUS ) * Class Membership: * Frame method. * Description: c This function f This routine * sets the current value of the ActiveUnit flag for a Frame, which * controls how the Frame behaves when it is used (by c astFindFrame or astConvert) f AST_FINDFRAME or AST_CONVERT) * to match another Frame. If the ActiveUnit flag is set in both * template and target Frames then the returned Mapping takes into account * any differences in axis units. The default value for simple Frames is * zero, which preserves the behaviour of versions of AST prior to * version 2.0. * * If the ActiveUnit flag of either Frame is c zero, f .FALSE., * then the Mapping will ignore any difference in the Unit attributes of * corresponding template and target axes. In this mode, the Unit * attributes are purely descriptive commentary for the benefit of * human readers and do not influence the Mappings between Frames. * This is the behaviour which all Frames had in older version of AST, * prior to the introduction of this attribute. * * If the ActiveUnit flag of both Frames is c non-zero, f .TRUE., * then the Mapping from template to target will take account of any * difference in the axis Unit attributes, where-ever possible. For * instance, if corresponding target and template axes have Unit strings of * "km" and "m", then the FrameSet class will use a ZoomMap to connect * them which introduces a scaling of 1000. If no Mapping can be found * between the corresponding units string, then an error is reported. * In this mode, it is assumed that values of the Unit attribute conform * to the syntax for units strings described in the FITS WCS Paper I * "Representations of world coordinates in FITS" (Greisen & Calabretta). * Particularly, any of the named unit symbols, functions, operators or * standard multiplier prefixes listed within that paper can be used within * a units string. A units string may contain symbols for unit which are * not listed in the FITS paper, but transformation to any other units * will then not be possible (except to units which depend only on the * same unknown units - thus "flops" can be transformed to "Mflops" * even though "flops" is not a standard FITS unit symbol). * * A range of common non-standard variations of unit names and multiplier * prefixes are also allowed, such as adding an "s" to the end of Angstrom, * using a lower case "a" at the start of "angstrom", "micron" instead of * "um", "sec" instead of "s", etc. * c If the ActiveUnit flag is non-zero, setting a new Unit value for an f If the ActiveUnit flag is .TRUE., setting a new Unit value for an * axis may also change its Label and Symbol attributes. For instance, if * an axis has Unit "Hz" and Label "frequency", then changing its Unit to * "log(Hz)" will change its Label to "log( frequency )". In addition, * the Axis Format attribute will be cleared when-ever a new value * is assigned to the Unit attribute. * c Note, if a non-zero value is set for the ActiveUnit flag, then changing a f Note, if a .TRUE. value is set for the ActiveUnit flag, then changing a * Unit value for the current Frame within a FrameSet will result in the * Frame being re-mapped (that is, the Mappings which define the * relationships between Frames within the FrameSet will be modified to * take into account the change in Units). * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c value f VALUE = LOGICAL (Given) * The new value to use. f STATUS = INTEGER (Given and Returned) f The global status. * Applicability: * SkyFrame c The ActiveUnit flag for a SkyFrame is always 0 (any value c supplied using this function is ignored). f The ActiveUnit flag for a SkyFrame is always .FALSE. (any value f supplied using this routine is ignored). * SpecFrame c The ActiveUnit flag for a SpecFrame is always 1 (any value c supplied using this function is ignored). f The ActiveUnit flag for a SpecFrame is always .TRUE. (any value f supplied using this routine is ignored). * FluxFrame c The ActiveUnit flag for a FluxFrame is always 1 (any value c supplied using this function is ignored). f The ActiveUnit flag for a FluxFrame is always .TRUE. (any value f supplied using this routine is ignored). * CmpFrame c The default ActiveUnit flag for a CmpFrame is 1 if both of the c component Frames are using active units, and zero otherwise. When f The default ActiveUnit flag for a CmpFrame is .TRUE. if both of the f component Frames are using active units, and .FALSE. otherwise. When * a new value is set for the ActiveUnit flag, the flag value * is propagated to the component Frames. This change will be * reflected through all references to the component Frames, not * just those encapsulated within the CmpFrame. * Region: * Regions always use active units if possible. * Notes: * - The ActiveUnit flag resembles a Frame attribute, except that it * cannot be tested or cleared, and it cannot be accessed using the c generic astGet and astSet functions. f generic AST_GET and AST_SET routines. c - The astGetActiveUnit function can be used to retrieve the current f - The AST_GETACTIVEUNIT routine can be used to retrieve the current * value of the ActiveUnit flag. *-- */ /* Check the global error status. */ if ( !astOK ) return; /* Store a value of 1 for the Frame component if the supplied value is non-zero. */ this->active_unit = ( value ) ? 1 : 0; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * Frame member function (over-rides the astSetAttrib method inherited * from the Mapping class). * Description: * This function assigns an attribute value for a Frame, the * attribute and its value being specified by means of a string of * the form: * * "attribute= value " * * Here, "attribute" specifies the attribute name and should be in * lower case with no white space present. The value to the right * of the "=" should be a suitable textual representation of the * value to be assigned and this will be interpreted according to * the attribute's data type. White space surrounding the value is * only significant for string attributes. * Parameters: * this * Pointer to the Frame. * setting * Pointer to a null terminated string specifying the new attribute * value. * status * Pointer to the inherited status variable. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. */ /* Local Vaiables: */ AstAxis *ax; /* Pointer to Axis */ AstFrame *pfrm; /* Pointer to primary Frame containing axis */ AstFrame *this; /* Pointer to the Frame structure */ AstSystemType system_code; /* System code */ char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ char *pfrm_setting; /* Primary Frame attribute */ char *axis_setting; /* Pointer to axis attribute setting string */ const char *equals; /* Pointer to equals sign */ const char *old_setting; /* Pointer to supplied setting string */ const char *op; /* Pointer to opening parenthesis */ double dval; /* Double attibute value */ double mjd; /* Epoch as a Modified Julian Date */ int axis; /* Index for the Frame axis */ int axis_nc; /* No. characters in axis attribute name */ int axis_value; /* Offset of value to be assigned to axis */ int digits; /* Number of digits of precision */ int direction; /* Axis direction flag */ int domain; /* Offset of Domain string */ int epoch; /* Offset of Epoch string */ int format; /* Offset of axis Format string */ int free_axis_setting; /* Should axis_setting be freed? */ int has_axis; /* Does setting include an axis specifier? */ int ival; /* Integer attribute value */ int label; /* Offset of axis Label string */ int len; /* Length of setting string */ int match_end; /* Match final axes of target? */ int max_axes; /* Maximum number of axes matched */ int min_axes; /* Minimum number of axes matched */ int nc; /* Number of characters read by astSscanf */ int off2; /* Modified offset of attribute value */ int off; /* Offset of attribute value */ int oldrep; /* Original error reporting state */ int paxis; /* Axis index within primary frame */ int permute; /* Permute axes in order to match? */ int preserve_axes; /* Preserve matched target axes? */ int sign; /* Sign of longitude value */ int symbol; /* Offset of axis Symbol string */ int system; /* Offset of System string */ int title; /* Offset of Title string */ int unit; /* Offset of axis Unit string */ int used; /* Could the setting string be used? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Find the offset to the first equal sign in the setting string. */ equals = strchr( setting, '=' ); /* Set a flag indicating if the attribute name includes an axis specifier. */ op = strchr( setting, '(' ); has_axis = ( !op || op > equals ) ? 0 : 1; /* A flag indicating that we do not need to free the axis_setting memory. */ free_axis_setting = 0; /* Initialise things to avoid compiler warnings. */ axis_setting = NULL; old_setting = NULL; /* Jump back to here if we are trying the same attribute setting but with an explicit axis "(1)" added to the attribute name. */ L1: /* Obtain the length of the setting string. */ len = strlen( setting ); /* Test for each recognised attribute in turn, using "astSscanf" to parse the setting string and extract the attribute value (or an offset to it in the case of string values). In each case, use the value set in "nc" to check that the entire string was matched. Once a value has been obtained, use the appropriate method to set it. */ /* Digits. */ /* ------- */ if ( nc = 0, ( 1 == astSscanf( setting, "digits= %d %n", &digits, &nc ) ) && ( nc >= len ) ) { astSetDigits( this, digits ); /* Digits(axis). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "digits(%d)= %d %n", &axis, &digits, &nc ) ) && ( nc >= len ) ) { /* There is no function to set the Digits attribute value for an axis directly, so obtain a pointer to the Axis and use this to set the attribute. */ (void) astValidateAxis( this, axis - 1, 1, "astSetDigits(axis)" ); ax = astGetAxis( this, axis - 1 ); astSetAxisDigits( ax, digits ); ax = astAnnul( ax ); /* Direction(axis). */ /* ---------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "direction(%d)= %d %n", &axis, &direction, &nc ) ) && ( nc >= len ) ) { astSetDirection( this, axis - 1, direction ); /* Epoch. */ /* ------ */ } else if ( nc = 0, ( 0 == astSscanf( setting, "epoch=%n%*[^\n]%n", &epoch, &nc ) ) && ( nc >= len ) ) { /* Convert the Epoch value to a Modified Julian Date before use. */ mjd = astReadDateTime( setting + epoch ); if ( astOK ) { astSetEpoch( this, mjd ); /* Report contextual information if the conversion failed. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid epoch value " "\"%s\" given for coordinate system.", status, astGetClass( this ), setting + epoch ); } /* Top(axis). */ /* ---------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "top(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetTop( this, axis - 1, dval ); /* Bottom(axis). */ /* ------------- */ } else if ( nc = 0, ( 2 == astSscanf( setting, "bottom(%d)= %lg %n", &axis, &dval, &nc ) ) && ( nc >= len ) ) { astSetBottom( this, axis - 1, dval ); /* Domain. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "domain=%n%*[^\n]%n", &domain, &nc ) ) && ( nc >= len ) ) { astSetDomain( this, setting + domain ); /* Format(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "format(%d)=%n%*[^\n]%n", &axis, &format, &nc ) ) && ( nc >= len ) ) { astSetFormat( this, axis - 1, setting + format ); /* Label(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( setting, "label(%d)=%n%*[^\n]%n", &axis, &label, &nc ) ) && ( nc >= len ) ) { astSetLabel( this, axis - 1, setting + label ); /* MatchEnd. */ /* --------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "matchend= %d %n", &match_end, &nc ) ) && ( nc >= len ) ) { astSetMatchEnd( this, match_end ); /* MaxAxes. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "maxaxes= %d %n", &max_axes, &nc ) ) && ( nc >= len ) ) { astSetMaxAxes( this, max_axes ); /* MinAxes. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "minaxes= %d %n", &min_axes, &nc ) ) && ( nc >= len ) ) { astSetMinAxes( this, min_axes ); /* Permute. */ /* -------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "permute= %d %n", &permute, &nc ) ) && ( nc >= len ) ) { astSetPermute( this, permute ); /* PreserveAxes. */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "preserveaxes= %d %n", &preserve_axes, &nc ) ) && ( nc >= len ) ) { astSetPreserveAxes( this, preserve_axes ); /* Symbol(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "symbol(%d)=%n%*[^\n]%n", &axis, &symbol, &nc ) ) && ( nc >= len ) ) { astSetSymbol( this, axis - 1, setting + symbol ); /* AlignSystem. */ /* ------------ */ } else if ( nc = 0, ( 0 == astSscanf( setting, "alignsystem= %n%*s %n", &system, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a System code before use. */ system_code = astSystemCode( this, system + setting ); if ( system_code != AST__BADSYSTEM ) { astSetAlignSystem( this, system_code ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid AlignSystem description \"%s\".", status, astGetClass( this ), system + setting ); } /* System. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "system= %n%*s %n", &system, &nc ) ) && ( nc >= len ) ) { /* Convert the string to a System code before use. */ system_code = astSystemCode( this, system + setting ); if ( system_code != AST__BADSYSTEM ) { astSetSystem( this, system_code ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid System description \"%s\".", status, astGetClass( this ), system + setting ); } /* Title. */ /* ------ */ } else if ( nc = 0, ( 0 == astSscanf( setting, "title=%n%*[^\n]%n", &title, &nc ) ) && ( nc >= len ) ) { astSetTitle( this, setting + title ); /* Unit(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "unit(%d)=%n%*[^\n]%n", &axis, &unit, &nc ) ) & ( nc >= len ) ) { astSetUnit( this, axis - 1, setting + unit ); /* ObsLat. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "obslat=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { /* If the first character in the value string is "N" or "S", remember the sign of the value and skip over the sign character. Default is north (+ve). */ off2 = off; if( setting[ off ] == 'N' || setting[ off ] == 'n' ) { off2++; sign = +1; } else if( setting[ off ] == 'S' || setting[ off ] == 's' ) { off2++; sign = -1; } else { sign = +1; } /* If not already created, create an FK5 J2000 SkyFrame which will be used for formatting and unformatting ObsLon and ObsLat values. */ if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); astEndPM; } /* Convert the string to a radians value before use. */ ival = astUnformat( skyframe, 1, setting + off2, &dval ); if ( ival == astChrLen( setting ) - off2 ) { astSetObsLat( this, dval*sign ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid value for " "ObsLat (observers latitude) \"%s\".", status, astGetClass( this ), setting + off ); } /* ObsLon. */ /* ------- */ } else if ( nc = 0, ( 0 == astSscanf( setting, "obslon=%n%*s %n", &off, &nc ) ) && ( nc >= 7 ) ) { /* If the first character in the value string is "E" or "W", remember the sign of the value and skip over the sign character. Default is east (+ve). */ off2 = off; if( setting[ off ] == 'E' || setting[ off ] == 'e' ) { off2++; sign = +1; } else if( setting[ off ] == 'W' || setting[ off ] == 'w' ) { off2++; sign = -1; } else { sign = +1; } /* If not already created, create an FK5 J2000 SkyFrame which will be used for formatting and unformatting ObsLon and ObsLat values. */ if( !skyframe ) { astBeginPM; skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); astEndPM; } /* Convert the string to a radians value before use. */ ival = astUnformat( skyframe, 1, setting + off2, &dval ); if ( ival == astChrLen( setting ) - off2 ) { astSetObsLon( this, dval*sign ); /* Report an error if the string value wasn't recognised. */ } else { astError( AST__ATTIN, "astSetAttrib(%s): Invalid value for " "ObsLon (observers longitude) \"%s\".", status, astGetClass( this ), setting + off ); } /* ObsAlt. */ /* ------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "obsalt= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetObsAlt( this, dval ); /* Dut1. */ /* ---- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "dut1= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetDut1( this, dval ); /* Read-only attributes. */ /* --------------------- */ /* Define a macro to see if the setting string matches any of the read-only attributes of this class. */ #define MATCH(attrib) \ ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ ( nc >= len ) ) /* Use this macro to report an error if a read-only attribute has been specified. */ } else if ( MATCH( "naxes" ) || !strncmp( setting, "normunit", 8 ) || !strncmp( setting, "internalunit", 12 ) ) { astError( AST__NOWRT, "astSet: The setting \"%s\" is invalid for a %s.", status, setting, astGetClass( this ) ); astError( AST__NOWRT, "This is a read-only attribute." , status); /* Other axis attributes. */ /* ---------------------- */ /* If the attribute was not identified above, but appears to refer to a Frame axis, then it may refer to an Axis object of a derived type (which has additional attributes not recognised here). */ } else if ( !free_axis_setting && ( nc = 0, ( 1 == astSscanf( setting, "%*[^()=]%n(%d)%n=%*[^\n]%n", &axis_nc, &axis, &axis_value, &nc ) ) && ( nc >= len ) ) ) { /* Validate the axis index and copy the attribute setting string. */ (void) astValidateAxis( this, axis - 1, 1, "astSet" ); axis_setting = astString( setting, len ); if ( astOK ) { /* Over-write the axis index in the copy with the value to be assigned. */ (void) strcpy( axis_setting + axis_nc, setting + axis_value ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis - 1 ); if( astOK ) { /* Assume that we will be able to use the setting. */ used = 1; /* Temporarily switch off error reporting so that if the following attempt to access the axis attribute fails, we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. Any errors reported in this context will simply be ignored, in particularly they are not deferred for later delivery. */ oldrep = astReporting( 0 ); /* Use the Axis astSetAttrib method to set the value. */ astSetAttrib( ax, axis_setting ); /* If the above call failed with a status of AST__BADAT, indicating that the attribute name was not recognised, clear the status so that we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. */ if( astStatus == AST__BADAT ) { astClearStatus; /* Find the primary Frame containing the specified axis. */ astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); /* Only attempt to use the primary Frame if it is not the same as "this" - otherwise we could end up in an infinite loop. */ if( pfrm != this ) { /* astPrimaryFrame returns the original - unpermuted - axis index within the primary Frame. So we need to take into account any axis permutation which has been applied to the primary Frame when forming the attribute name to use below. Find the permuted (external) axis index which corresponds to the internal (unpermuted) axis index "paxis". */ paxis = astValidateAxis( pfrm, paxis, 0, "astSet" ); /* Modify the attribute name to refer to the axis numbering of the primary frame. */ sprintf( pfrm_attrib, "%.*s(%d)", axis_nc, setting, paxis + 1 ); /* Create a setting string in which the attribute name refers to the axis numbering of the primary frame. */ pfrm_setting = NULL; nc = 0; pfrm_setting = astAppendString( pfrm_setting, &nc, pfrm_attrib ); pfrm_setting = astAppendString( pfrm_setting, &nc, setting + axis_value ); /* Attempt to set the attribute within the primary Frame. */ astSetAttrib( pfrm, pfrm_setting ); /* Free the memory. */ pfrm_setting = astFree( pfrm_setting ); /* If this failed, clear the status and indicate that we have not managed to use the attribute setting. */ if( !astOK ) { astClearStatus; used = 0; } } else { used = 0; } /* If not found attempt to set the attribute value in the Axis, omitting the axis index. */ if( ! used ) { astSetAttrib( pfrm, axis_setting ); if( !astOK ) { astClearStatus; } else { used = 1; } } /* Free the setting string, and annul the primary Frame pointer. */ pfrm = astAnnul( pfrm ); } /* Re-instate the original error reporting state. */ astReporting( oldrep ); /* If we could not use the setting, attempt to set the axis attribute again, this time retaining the error report. This is done to ensure the user gets an appropriate error message. */ if( !used ) astSetAttrib( ax, axis_setting ); } /* Annul the Axis pointer and free the memory holding the attribute setting. */ ax = astAnnul( ax ); } axis_setting = astFree( axis_setting ); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, and the Frame has only 1 axis, and the attribute name does not already include an axis specifier, try again after appending "(1)" to the end of the attribute name. */ } else if( !has_axis && astGetNaxes( this ) == 1 && equals ) { /* Take a copy of the supplied setting, allowing 3 extra characters for the axis specifier "(1)". */ axis_setting = astMalloc( len + 4 ); if( axis_setting ) memcpy( axis_setting, setting, len ); /* Indicate we should free the axis_setting memory. */ free_axis_setting = 1; /* Add in the axis specifier. */ strcpy( axis_setting + ( equals - setting ), "(1)" ); /* Add in the equals sign and attribute value. */ strcpy( axis_setting + ( equals - setting ) + 3, equals ); /* Use the new setting instead of the supplied setting. */ old_setting = setting; setting = axis_setting; /* Indicate the setting now has an axis specifier. */ has_axis = 1; /* Jump back to try interpreting the new setting string. */ goto L1; /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. First re-instate the original setting string if it was changed above. */ } else { if( free_axis_setting ) { setting = old_setting; axis_setting = astFree( axis_setting ); free_axis_setting = 0; } (*parent_setattrib)( this_object, setting, status ); } if( free_axis_setting ) axis_setting = astFree( axis_setting ); /* Undefine macros local to this function. */ #undef MATCH } static void SetAxis( AstFrame *this, int axis, AstAxis *newaxis, int *status ) { /* *+ * Name: * astSetAxis * Purpose: * Set a new Axis for a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astSetAxis( AstFrame *this, int axis, AstAxis *newaxis ) * Class Membership: * Frame method. * Description: * This function allows a new Axis object to be associated with one * of the axes of a Frame, replacing the previous one. Each Axis * object contains a description of the quantity represented along * one of the Frame's axes, so this function allows this * description to be exchanged for another one. * Parameters: * this * Pointer to the Frame. * axis * The index (zero-based) of the axis whose associated Axis object is to * be replaced. * newaxis * Pointer to the new Axis object. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Validate and permute the axis index supplied. */ axis = astValidateAxis( this, axis, 1, "astSetAxis" ); /* If OK, annul the Frame's pointer to the old Axis object and clone a pointer to the new one to replace it. */ if ( astOK ) { this->axis[ axis ] = astAnnul( this->axis[ axis ] ); this->axis[ axis ] = astClone( newaxis ); } } static void SetFrameFlags( AstFrame *this, int flags, int *status ){ /* *+ * Name: * astSetFrameFlags * Purpose: * Store a new bit mask of flags in a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * void astSetFrameFlags( astFrame *this, int flags ) * Class Membership: * Frame member function. * Description: * This function stores a new set of flags in a Frame. The flags can * be retrieved using astGetFrameFlags. * Parameters: * this * The Frame. * flags * A bit mask holding the flags. Currently, the following bits are * used: * * 0 - Used to indicate if the Frame is currently involved in an * attempt to restore the integrity of a FrameSet following * changes to the attribute values of the Frame. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Assign the new bit mask. */ this->flags = flags; } static void SetFrameVariants( AstFrame *this, AstFrameSet *variants, int *status ){ /* *+ * Name: * astSetFrameVariants * Purpose: * Store a FrameSet holding alternative Frame properties. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astSetVariants( AstFrame *this, AstFrameSet *variants ) * Class Membership: * Frame method. * Description: * This function adds sets of alternative Frame properties to a Frame. * Parameters: * this * Pointer to the Frame. * variants * Pointer to a FrameSet in which each Frame is of the same class * and dimensionality as "this" and all Frames have unique Domain * names. * Notes: * - A clone of the supplied FrameSet pointer is stored in the Frame. *- */ /* Check the global error status. */ if ( !astOK ) return; /* Annul any variants FrameSet already stored in the Frame. */ if( this->variants ) this->variants = astAnnul( this->variants ); /* Store a clone of ht esupplied FrameSet pointer. */ if( variants ) this->variants = astClone( variants ); } static void SetUnit( AstFrame *this, int axis, const char *unit, int *status ) { /* * Name: * SetUnit * Purpose: * Set a value for the Unit attribute of a Frame. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void SetUnit( AstFrame *this, int axis, const char *unit, int *status ) * Class Membership: * Frame method. * Description: * This function sets the Unit value for a Frame. * Parameters: * this * Pointer to the Frame. * axis * The number of the axis (zero-based) for which the Unit value is to * be set. * unit * The new value to be set. * status * Pointer to the inherited status variable. * Returned Value: * void. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ char *c; /* Copy of supplied string */ const char *oldunit; /* Pointer to old units string */ int l; /* Used length of supplied string */ /* Check the global error status. */ if ( !astOK ) return; /* Get a copy of the supplied string which excludes trailing spaces. */ l = astChrLen( unit ); c = astStore( NULL, unit, (size_t) (l + 1) ); if( astOK ) { c[ l ] = 0; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astSetUnit" ); ax = astGetAxis( this, axis ); /* The new unit may require the Label and/or Symbol to be changed, but only if the Frames ActiveUnit flag is set. */ if( astGetActiveUnit( this ) ) { /* Get the existing Axis unit, using the astGetUnit method (rather than astGetAxisUnit) in order to get any default value in the case where the Unit attribute is not set. */ oldunit = astGetUnit( this, axis ); /* Assign the new Unit value. This modifies labels and/or Symbols if necessary. */ NewUnit( ax, oldunit, c, "astSetUnit", astGetClass( this ), status ); } /* Set the Axis Unit attribute value. */ astSetAxisUnit( ax, c ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); } /* Free the string copy */ c = astFree( c ); } static int SubFrame( AstFrame *target, AstFrame *template, int result_naxes, const int *target_axes, const int *template_axes, AstMapping **map, AstFrame **result, int *status ) { /* *+ * Name: * astSubFrame * Purpose: * Select axes from a Frame and convert to the new coordinate system. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astSubFrame( AstFrame *target, AstFrame *template, * int result_naxes, const int *target_axes, * const int *template_axes, AstMapping **map, * AstFrame **result ) * Class Membership: * Frame method. * Description: * This function selects a requested sub-set (or super-set) of the axes from * a "target" Frame and creates a new Frame with copies of the selected * axes assembled in the requested order. It then optionally overlays the * attributes of a "template" Frame on to the result. It returns both the * resulting Frame and a Mapping that describes how to convert between the * coordinate systems described by the target and result Frames. If * necessary, this Mapping takes account of any differences in the Frames' * attributes due to the influence of the template. * Parameters: * target * Pointer to the target Frame, from which axes are to be selected. * template * Pointer to the template Frame, from which new attributes for the * result Frame are to be obtained. Optionally, this may be NULL, in * which case no overlaying of template attributes will be performed. * result_naxes * Number of axes to be selected from the target Frame. This number may * be greater than or less than the number of axes in this Frame (or * equal). * target_axes * Pointer to an array of int with result_naxes elements, giving a list * of the (zero-based) axis indices of the axes to be selected from the * target Frame. The order in which these are given determines the order * in which the axes appear in the result Frame. If any of the values in * this array is set to -1, the corresponding result axis will not be * derived from the target Frame, but will be assigned default attributes * instead. * template_axes * Pointer to an array of int with result_naxes elements. This should * contain a list of the template axes (given as zero-based axis indices) * with which the axes of the result Frame are to be associated. This * array determines which axes are used when overlaying axis-dependent * attributes of the template on to the result. If any element of this * array is set to -1, the corresponding result axis will not receive any * template attributes. * * If the template argument is given as NULL, this array is not used and * a NULL pointer may also be supplied here. * map * Address of a location to receive a pointer to the returned Mapping. * The forward transformation of this Mapping will describe how to * convert coordinates from the coordinate system described by the target * Frame to that described by the result Frame. The inverse * transformation will convert in the opposite direction. * result * Address of a location to receive a pointer to the result Frame. * Returned Value: * A non-zero value is returned if coordinate conversion is * possible between the target and the result Frame. Otherwise zero * is returned and *map and *result are returned as NULL (but this * will not in itself result in an error condition). In general, * coordinate conversion should always be possible if no template * Frame is supplied but may not always be possible otherwise. * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * Implementation Deficiencies: * - Any axis selection is currently permitted. Probably this * should be restricted so that each axis can only be selected * once. The astValidateAxisSelection method will do this but * currently there are bugs in the CmpFrame class that cause axis * selections which will not pass this test. Install the validation * when these are fixed. *- * Implementation Notes: * - This implementation addresses the selection of axes from a * Frame class object. This simply results in another object of the * same class and a Mapping which describes an axis permutation (or * a unit Mapping as a special case). Changes of Frame attributes * have no significance for coordinate values in this class, so do * not affect the Mapping returned. */ /* Local Variables: */ AstAxis *newaxis; /* Pointer to new Axis object */ AstFrame *tempframe; /* Pointer to temporary Frame */ AstMapping *aumap; /* A units Mapping for a single axis */ AstMapping *numap; /* The new total units Mapping */ AstMapping *umap; /* The total units Mapping */ int *inperm; /* Pointer to permutation array */ int *outperm; /* Pointer to permutation array */ int match; /* Coordinate conversion possible? */ int result_axis; /* Result Frame axis index */ int target_axis; /* Target Frame axis index */ int target_naxes; /* Number of target Frame axes */ int unit; /* Unit Mapping appropriate? */ int uunit; /* Is the "umap" Mapping a UnitMap? */ /* Initialise the returned values. */ *map = NULL; *result = NULL; match = 0; /* Check the global error status. */ if ( !astOK ) return match; /* Obtain the number of target Frame axes. */ target_naxes = astGetNaxes( target ); /* Ensure we do not attempt to use a negative number of result axes. */ if ( result_naxes < 0 ) result_naxes = 0; /* Create a temporary new Frame with the required number of axes. This will have a default Axis object associated with each of its axes. We will replace these where necessary with copies of the actual Axis objects we require. */ tempframe = astFrame( result_naxes, "", status ); /* Allocate memory to store two permutation arrays. These will be used to construct the Mapping that relates the target and result Frames. */ inperm = astMalloc( sizeof( int ) * (size_t) target_naxes ); outperm = astMalloc( sizeof( int ) * (size_t) result_naxes ); if ( astOK ) { /* Initialise the array that associates each target axis with the corresponding result axis (filling it with the value -1 initially signifies no associations). */ for ( target_axis = 0; target_axis < target_naxes; target_axis++ ) { inperm[ target_axis ] = -1; } /* Loop through each axis in the result Frame and obtain the index of the axis in the target Frame from which it is to be derived. */ for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { target_axis = target_axes[ result_axis ]; /* Check if the resulting axis index is valid. If not, this result axis is not to be derived from any target axis, and it will therefore be left with its default attributes. Make an entry in the appropriate permutation array to indicate that this result axis is unassociated. */ if ( ( target_axis < 0 ) || ( target_axis >= target_naxes ) ) { outperm[ result_axis ] = -1; /* Otherwise, obtain a pointer to the target Axis object and modify the temporary Frame so that its axis is associated with the same Axis object. Annul the Axis pointer afterwards. */ } else { newaxis = astGetAxis( target, target_axis ); astSetAxis( tempframe, result_axis, newaxis ); newaxis = astAnnul( newaxis ); /* Update both permutation arrays to record the association between the target and result axes. */ outperm[ result_axis ] = target_axis; inperm[ target_axis ] = result_axis; } /* Quit looping if an error occurs. */ if ( !astOK ) break; } /* So far, we have only modified pointers in the temporary Frame to refer to the target Frame's Axis objects. Since we will next modify these objects' attributes, we must make a deep copy of the entire temporary Frame so that we do not modify the target's axes. This copy now becomes our result Frame. Annul the temporary one. */ if ( astOK ) { *result = astCopy( tempframe ); tempframe = astAnnul( tempframe ); /* Invoke the target "astOverlay" method to overlay any remaining attributes from the target Frame which are not associated with individual axes (e.g. the Frame's Title and Domain). */ astOverlay( target, target_axes, *result ); /* If a template Frame was supplied, also invoke its astOverlay method to overlay its attributes on the result Frame. (Note that in this particular case this has no effect other than transferring attributes. In general, however, i.e. in derived classes, this process is vital to determining the mapping below, whose main purpose is to convert between the target and result Frames. These will have different attributes as a result of the influence that the template has here.) */ if ( template ) astOverlay( template, template_axes, *result ); /* We will next generate the Mapping that relates the target and result Frames. If appropriate this should be a unit Mapping (UnitMap), so test if the number of axes in both Frames is equal. */ unit = ( target_naxes == result_naxes ); /* If so, check the contents of one of the permutation arrays to see if all result axes are associated with the corresponding target axis (the converse then also follows). If not, note this fact and quit checking. */ if ( unit ) { for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { if ( outperm[ result_axis ] != result_axis ) { unit = 0; break; } } } /* If a unit Mapping is appropriate, then construct it. */ if ( unit ) { *map = (AstMapping *) astUnitMap( result_naxes, "", status ); /* Otherwise, construct a Mapping describing the axis permutation we have produced. */ } else { *map = (AstMapping *) astPermMap( target_naxes, inperm, result_naxes, outperm, NULL, "", status ); } /* Note that coordinate conversion is possible. */ match = 1; /* If the ActiveUnit flag in both template and result Frame is non-zero, we now modify the Mapping to take account of any differences in the Units attributes of the target and results Frames. */ if( template && astGetActiveUnit( template ) && astGetActiveUnit( *result ) ) { /* Loop round the axes of the results Frame, accumulating a parallel CmpMap ("umap") in which each Mapping is the 1-D Mapping which transforms the Units of the corresponding target axis into the Units of the results axis. */ umap = NULL; uunit = 1; for( result_axis = 0; result_axis < result_naxes; result_axis++ ) { /* Find the index of the corresponding target axis. */ if( unit ) { target_axis = result_axis; } else { target_axis = outperm[ result_axis ]; } /* Get the Unit string for both axes, and attempt to find a Mapping which transforms values in the target units into the corresponding value in the results units. If this results axis does not have a corresponding target axis, then indicate that no units mapping can be found. */ if( target_axis > -1 ) { aumap = astUnitMapper( astGetUnit( target, target_axis ), astGetUnit( *result, result_axis ), NULL, NULL ); } else { aumap = NULL; } /* If no Mapping could be found, annull the Mapping and leave the loop. Otherwise, see if the Mapping is a UnitMap. If not, set a flag to indicate that we have at least one non-unit map. */ if( !aumap ) { if( umap ) umap = astAnnul( umap ); match = 0; break; } else { if( !astIsAUnitMap( aumap ) ) uunit = 0; } /* Add this Mapping into the parallel CmpMap. */ if( umap ) { numap = (AstMapping *) astCmpMap( umap, aumap, 0, "", status ); umap = astAnnul( umap ); aumap = astAnnul( aumap ); umap = numap; } else { umap = aumap; } } /* If the resulting CmpMap is not just a UnitMap, add it in series with the current results mapping, and then simplify it. */ if( !uunit && umap ) { numap = (AstMapping *) astCmpMap( *map, umap, 1, "", status ); (void) astAnnul( *map ); *map = numap; } /* Annul the CmpMap containing the units Mappings. */ if( umap ) umap = astAnnul( umap ); /* If the units could not bve matched annul the returned mapping. */ if( !match && *map ) *map = astAnnul( *map ); } } } /* Free the memory used for the permutation arrays. */ inperm = astFree( inperm ); outperm = astFree( outperm ); /* If an error occurred, annul the returned objects and reset the returned value. */ if ( !astOK ) { *map = astAnnul( *map ); *result = astAnnul( *result ); match = 0; } /* Return the result. */ return match; } static AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) { /* *+ * Name: * astSystemCode * Purpose: * Convert a string into a coordinate system type code. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * AstSystemType SystemCode( AstFrame *this, const char *system ) * Class Membership: * Frame method. * Description: * This function converts a string used for the external description of * a coordinate system into a Frame coordinate system type code (System * attribute value). It is the inverse of the astSystemString function. * Parameters: * this * Pointer to the Frame. * system * Pointer to a constant null-terminated string containing the * external description of the coordinate system. * Returned Value: * The System type code. * Notes: * - A value of AST__BADSYSTEM is returned if the coordinate system * description was not recognised. This does not produce an error. * - A value of AST__BADSYSTEM is also returned if this function * is invoked with the global error status set or if it should fail * for any reason. *- */ /* Local Variables: */ AstSystemType result; /* Result value to return */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" string against each possibility and assign the result. The basic Frame class only supports a single system "Cartesian". */ if ( astChrMatch( "Cartesian", system ) ) { result = AST__CART; } /* Return the result. */ return result; } static const char *SystemString( AstFrame *this, AstSystemType system, int *status ) { /* *+ * Name: * astSystemString * Purpose: * Convert a coordinate system type code into a string. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * const char *astSystemString( AstFrame *this, AstSystemType system ) * Class Membership: * Frame method. * Description: * This function converts a Frame coordinate system type code * (System attribute value) into a string suitable for use as an * external representation of the coordinate system type. * Parameters: * this * Pointer to the Frame. * system * The coordinate system type code. * Returned Value: * Pointer to a constant null-terminated string containing the * textual equivalent of the type code supplied. * Notes: * - A NULL pointer value is returned if the coordinate system * code was not recognised. This does not produce an error. * - A NULL pointer value is also returned if this function is * invoked with the global error status set or if it should fail * for any reason. *- */ /* Local Variables: */ const char *result; /* Pointer value to return */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Match the "system" value against each possibility and convert to a string pointer. (Where possible, return the same string as would be used in the FITS WCS representation of the coordinate system). A basic Frame only allows a single System value, "Cartesian". */ switch ( system ) { case AST__CART: result = "Cartesian"; break; } /* Return the result pointer. */ return result; } static int TestActiveUnit( AstFrame *this, int *status ){ /* *+ * Name: * astTestActiveUnit * Purpose: * Determines if the ActiveUnit flag is set. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astTestActiveUnit( AstFrame *this ) * Class Membership: * Frame method. * Description: * This function tests the current value of the ActiveUnit flag for a * Frame. See the description of the astSetActiveUnit function for a * description of the ActiveUnit flag. * Parameters: * this * Pointer to the Frame. * Returned Value: * Non-zero if the flag has been set. Zero otherwise. * Notes: * - A zero value will be returned if this function is * invoked with the AST error status set, or if it should fail for * any reason. *-- */ /* Local Variables: */ int result; /* The returned value */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Return the result. */ return ( this->active_unit != -INT_MAX ); } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a Frame. * Type: * Private function. * Synopsis: * #include "frame.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * Frame member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a Frame's attributes. * Parameters: * this * Pointer to the Frame. * attrib * Pointer to a null terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. * Returned Value: * One if a value has been set, otherwise zero. * Notes: * - This function uses one-based axis numbering so that it is * suitable for external (public) use. * - A value of zero will be returned if this function is invoked * with the global status set, or if it should fail for any reason. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis */ AstFrame *pfrm; /* Pointer to primary Frame containing axis */ AstFrame *this; /* Pointer to the Frame structure */ char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ char *axis_attrib; /* Pointer to axis attribute name */ const char *old_attrib; /* Pointer to supplied attribute name string */ int axis; /* Frame axis number */ int axis_nc; /* No. characters in axis attribute name */ int free_axis_attrib; /* Should axis_attrib be freed? */ int has_axis; /* Does attrib name include axis specifier? */ int len; /* Length of attrib string */ int nc; /* No. characters read by astSscanf */ int oldrep; /* Original error reporting state */ int paxis; /* Axis index within primary frame */ int result; /* Result value to return */ int used; /* Could the setting string be used? */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Set a flag indicating if the attribute name includes an axis specifier. */ has_axis = ( strchr( attrib, '(' ) != NULL ); /* A flag indicating that we do not need to free the axis_attrib memory. */ free_axis_attrib = 0; /* Initialise things to avoid compiler warnings. */ axis_attrib = NULL; old_attrib = NULL; /* Jump back to here if we are trying the same attribute but with an explicit axis "(1)" added to the end of the name. */ L1: /* Obtain the length of the attrib string. */ len = strlen( attrib ); /* Check the attribute name and test the appropriate attribute. */ /* Digits. */ /* ------- */ if ( !strcmp( attrib, "digits" ) ) { result = astTestDigits( this ); /* Digits(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { /* There is no function to test the Digits attribute for an axis directly, so obtain a pointer to the Axis and use this to test the attribute. */ (void) astValidateAxis( this, axis - 1, 1, "astTestDigits(axis)" ); ax = astGetAxis( this, axis - 1 ); result = astTestAxisDigits( ax ); ax = astAnnul( ax ); /* Direction(axis). */ /* ---------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestDirection( this, axis - 1 ); /* Epoch. */ /* ------ */ } else if ( !strcmp( attrib, "epoch" ) ) { result = astTestEpoch( this ); /* Bottom(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestBottom( this, axis - 1 ); /* Top(axis). */ /* ---------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestTop( this, axis - 1 ); /* Domain. */ /* ------- */ } else if ( !strcmp( attrib, "domain" ) ) { result = astTestDomain( this ); /* Format(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestFormat( this, axis - 1 ); /* Label(axis). */ /* ------------ */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestLabel( this, axis - 1 ); /* MatchEnd. */ /* --------- */ } else if ( !strcmp( attrib, "matchend" ) ) { result = astTestMatchEnd( this ); /* MaxAxes. */ /* -------- */ } else if ( !strcmp( attrib, "maxaxes" ) ) { result = astTestMaxAxes( this ); /* MinAxes. */ /* -------- */ } else if ( !strcmp( attrib, "minaxes" ) ) { result = astTestMinAxes( this ); /* Permute. */ /* -------- */ } else if ( !strcmp( attrib, "permute" ) ) { result = astTestPermute( this ); /* PreserveAxes. */ /* ------------- */ } else if ( !strcmp( attrib, "preserveaxes" ) ) { result = astTestPreserveAxes( this ); /* Symbol(axis). */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestSymbol( this, axis - 1 ); /* AlignSystem. */ /* ------------ */ } else if ( !strcmp( attrib, "alignsystem" ) ) { result = astTestAlignSystem( this ); /* System. */ /* ------- */ } else if ( !strcmp( attrib, "system" ) ) { result = astTestSystem( this ); /* Title. */ /* ------ */ } else if ( !strcmp( attrib, "title" ) ) { result = astTestTitle( this ); /* Unit(axis). */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) && ( nc >= len ) ) { result = astTestUnit( this, axis - 1 ); /* ObsLat. */ /* ------- */ } else if ( !strcmp( attrib, "obslat" ) ) { result = astTestObsLat( this ); /* ObsLon. */ /* ------- */ } else if ( !strcmp( attrib, "obslon" ) ) { result = astTestObsLon( this ); /* ObsAlt. */ /* ------- */ } else if ( !strcmp( attrib, "obsalt" ) ) { result = astTestObsAlt( this ); /* Dut1. */ /* ---- */ } else if ( !strcmp( attrib, "dut1" ) ) { result = astTestDut1( this ); /* Read-only attributes. */ /* --------------------- */ /* Test if the attribute name matches any of the read-only attributes of this class. If it does, then return zero. */ } else if ( !strcmp( attrib, "naxes" ) || !strncmp( attrib, "normunit", 8 ) || !strncmp( attrib, "internalunit", 12 ) ) { result = 0; /* Other axis attributes. */ /* ---------------------- */ /* If the attribute was not identified above, but appears to refer to a Frame axis, then it may refer to an Axis object of a derived type (which has additional attributes not recognised here). */ } else if ( !free_axis_attrib && ( nc = 0, ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", &axis_nc, &axis, &nc ) ) && ( nc >= len ) ) ) { /* Validate the axis index and extract the attribute name. */ (void) astValidateAxis( this, axis - 1, 1, "astTest" ); axis_attrib = astString( attrib, axis_nc ); /* Obtain a pointer to the Axis object. */ ax = astGetAxis( this, axis - 1 ); if( astOK ) { /* Assume that we will be able to use the attribute name. */ used = 1; /* Temporarily switch off error reporting so that if the following attempt to access the axis attribute fails, we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. Any errors reported in this context will simply be ignored, in particularly they are not deferred for later delivery. */ oldrep = astReporting( 0 ); /* Use the Axis astTestAttrib method to test the attribute value. */ result = astTestAttrib( ax, axis_attrib ); /* If the above call failed with a status of AST__BADAT, indicating that the attribute name was not recognised, clear the status so that we can try to interpret the attribute name as an attribute of the primary Frame containing the specified axis. */ if( astStatus == AST__BADAT ) { astClearStatus; /* Find the primary Frame containing the specified axis. */ astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); /* Only attempt to use the primary Frame if it is not the same as "this" - otherwise we could end up in an infinite loop. */ if( pfrm != this ) { /* astPrimaryFrame returns the original - unpermuted - axis index within the primary Frame. So we need to take into account any axis permutation which has been applied to the primary Frame when forming the attribute name to use below. Find the permuted (external) axis index which corresponds to the internal (unpermuted) axis index "paxis". */ paxis = astValidateAxis( pfrm, paxis, 0, "astTest" ); /* Modify the attribute name to refer to the axis numbering of the primary frame. */ sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); /* Attempt to test the attribute as an attribute of the primary Frame. */ result = astTestAttrib( pfrm, pfrm_attrib ); /* If this failed, clear the status and indicate that we have not managed to use the attribute name. */ if( !astOK ) { astClearStatus; used = 0; } } else { used = 0; } /* If not found attempt to test the attribute value in the Axis, omitting the axis index. */ if( ! used ) { result = astTestAttrib( pfrm, axis_attrib ); if( !astOK ) { astClearStatus; } else { used = 1; } } /* Annul the primary Frame pointer. */ pfrm = astAnnul( pfrm ); } /* Re-instate the original error reporting state. */ astReporting( oldrep ); /* If we could not use the attribute name, attempt to test the axis attribute again, this time retaining the error report. This is done to ensure the user gets an appropriate error message. */ if( !used ) result = astTestAttrib( ax, axis_attrib ); } /* Annul the Axis pointer and free the memory holding the attribute name. */ ax = astAnnul( ax ); axis_attrib = astFree( axis_attrib ); /* Not recognised. */ /* --------------- */ /* If the attribute is still not recognised, and the Frame has only 1 axis, and the attribute name does not already include an axis specifier, try again after appending "(1)" to the end of the attribute name. */ } else if( !has_axis && astGetNaxes( this ) == 1 ) { /* Take a copy of the supplied name, allowing 3 extra characters for the axis specifier "(1)". */ axis_attrib = astMalloc( len + 4 ); if( axis_attrib ) memcpy( axis_attrib, attrib, len ); /* Indicate we should free the axis_attrib memory. */ free_axis_attrib = 1; /* Add in the axis specifier. */ strcpy( axis_attrib + len, "(1)" ); /* Use the new attribute name instead of the supplied name. */ old_attrib = attrib; attrib = axis_attrib; /* Indicate the attribute name now has an axis specifier. */ has_axis = 1; /* Jump back to try interpreting the new attribute name. */ goto L1; /* Not recognised. */ /* --------------- */ /* If the attribute name is still not recognised, pass it on to the parent method for further interpretation. First re-instate the original attrib name string if it was changed above. */ } else { if( free_axis_attrib ) { attrib = old_attrib; axis_attrib = astFree( axis_attrib ); } result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Use a Frame to transform a set of points. * Type: * Private function. * Synopsis: * #include "frame.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Frame member function (over-rides the astTransform method inherited * from the Mapping class). * Description: * This function takes a Frame and a set of points encapsulated in a * PointSet and transforms the points so as to perform the identity * transformation (i.e. simply copies the coordinate values). * Parameters: * this * Pointer to the Frame. * in * Pointer to the PointSet holding the input coordinate data. * forward * A non-zero value indicates that the forward coordinate transformation * should be applied, while a zero value requests the inverse * transformation. In this case, both transformations are equivalent. * out * Pointer to a PointSet which will hold the transformed (output) * coordinate values. A NULL value may also be given, in which case a * new PointSet will be created by this function. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the output (possibly new) PointSet. * Notes: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of coordinates for the Frame being applied. This number * will be equal to the number of Frame axes. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstFrame *this; /* Pointer to the Frame structure */ AstPointSet *result; /* Pointer value to be returned */ AstUnitMap *unitmap; /* Pointer to temporary UnitMap */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_mapping; /* Create a unit Mapping with one coordinate for each Frame axis. */ unitmap = astUnitMap( astGetNaxes( this ), "", status ); /* Use the Mapping to transform (i.e. copy) the coordinate values. */ result = astTransform( unitmap, in, forward, out ); /* Annul the Mapping. */ unitmap = astAnnul( unitmap ); /* If an error occurred and a new PointSet may have been created, then annul the result. In any case, ensure that a NULL pointer is returned. */ if ( !astOK ) { if ( !out ) result = astAnnul( result ); result = NULL; } /* Return the result pointer. */ return result; } static int Unformat( AstFrame *this, int axis, const char *string, double *value, int *status ) { /* *+ * Name: * astUnformat * Purpose: * Read a formatted coordinate value for a Frame axis. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astUnformat( AstFrame *this, int axis, const char *string, * double *value ) * Class Membership: * Frame method. * Description: * This function reads a formatted coordinate value for a Frame * axis (supplied as a string) and returns the equivalent numerical * value as a double. It also returns the number of characters read * from the string. * Parameters: * this * Pointer to the Frame. * axis * The number of the Frame axis for which the coordinate value * is to be read (axis numbering starts at zero for the first * axis). * string * Pointer to a constant null-terminated string containing the * formatted coordinate value. * value * Pointer to a double in which the coordinate value read will be * returned. * Returned Value: * The number of characters read from the string to obtain the * coordinate value. * Notes: * - Any white space at the beginning of the string will be * skipped, as also will any trailing white space following the * coordinate value read. The function's return value will reflect * this. * - A function value of zero (and no coordinate value) will be * returned, without error, if the string supplied does not contain * a suitably formatted value. * - The string "" is recognised as a special case and will * generate the value AST__BAD, without error. The test for this * string is case-insensitive and permits embedded white space. * - A function result of zero will be returned and no coordinate * value will be returned via the "value" pointer if this function * is invoked with the global error status set, or if it should * fail for any reason. *- * Implementation Notes: * - This function implements the basic astUnformat method * available via the protected interface to the Frame class. The * public interface to this method is provided by the * astUnformatId_ function. */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis object */ const char *label; /* Pointer to axis label string */ double coord; /* Coordinate value read */ int digits_set; /* Axis Digits attribute set? */ int nc; /* Number of characters read */ int status_value; /* AST error status */ /* Initialise. */ nc = 0; /* Check the global error status. */ if ( !astOK ) return nc; /* Validate the axis index and obtain a pointer to the required Axis. */ (void) astValidateAxis( this, axis, 1, "astUnformat" ); ax = astGetAxis( this, axis ); /* Test if any Axis attributes which may affect the result are undefined (i.e. have not been explicitly set). If so, we over-ride them, giving them temporary values dictated by the Frame. Only the Digits attribute is potentially relevant here. */ digits_set = astTestAxisDigits( ax ); if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); /* Read the coordinate value. */ if ( astOK ) { nc = astAxisUnformat( ax, string, &coord ); /* If an error occurred, save and temporarily clear the global error status while the axis Label string is obtained. Then restore the original error status value afterwards. */ if ( !astOK ) { status_value = astStatus; astClearStatus; label = astGetLabel( this, axis ); astSetStatus( status_value ); /* Report a contextual error message containing the axis label. */ astError( status_value, "%s(%s): Unable to read \"%s\" value.", status, "astUnformat", astGetClass( this ), label ); } } /* Clear any Axis attributes that were temporarily over-ridden. */ if ( !digits_set ) astClearAxisDigits( ax ); /* Annul the Axis pointer. */ ax = astAnnul( ax ); /* If an error occurred, clear the count of characters read. */ if ( !astOK ) { nc = 0; /* Otherwise, if characters were read, return the coordinate value. */ } else if ( nc ) { *value = coord; } /* Return the number of characters read. */ return nc; } static int ValidateAxis( AstFrame *this, int axis, int fwd, const char *method, int *status ) { /* *+ * Name: * astValidateAxis * Purpose: * Validate and permute a Frame's axis index. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astValidateAxis( AstFrame *this, int axis, int fwd, * const char *method ) * Class Membership: * Frame method. * Description: * This function checks the validity of an index (zero-based) which * is to be used to address one of the coordinate axes of a * Frame. If the index is valid, it is permuted using the axis * permutation array associated with the Frame and the (zero-based) * permuted axis index is returned. This gives the location of the * required axis information within the Frame's internal arrays. If * the axis index supplied is not valid, an error is reported and * the global error status is set. * Parameters: * this * Pointer to the Frame. * axis * The axis index (zero-based) to be checked. To be valid, it * must lie between zero and (naxes-1) inclusive, where "naxes" * is the number of coordinate axes associated with the Frame. * fwd * If non-zero, the suppplied axis index is assumed to be an * "external" axis index, and the corresponding "internal" axis index * is returned as the function value. Otherwise, the suppplied axis * index is assumed to be an "internal" axis index, and the * corresponding "external" axis index is returned as the function * value. * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function * to validate an axis index. This method name is used solely * for constructing error messages. * Returned Value: * The permuted axis index - either "internal" or "external" as * specified by "fwd". * Notes: * - A value of zero will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. * - Error messages issued by this function refer to the public * numbering system used for axes which is one-based (zero-based axis * indices are used internally). *- */ /* Local Variables: */ const int *perm; /* Pointer to axis permutation array */ int naxes; /* Number of Frame axes */ int result; /* Permuted axis index */ /* Initialise. */ result = 0; /* Determine the number of Frame axes. */ naxes = astGetNaxes( this ); if ( astOK ) { /* If the Frame has no axes, report an error (note we convert to one-based axis numbering in the error message). */ if ( naxes == 0 ) { astError( AST__AXIIN, "%s(%s): Invalid attempt to use an axis index " "(%d) for a %s which has no axes.", status, method, astGetClass( this ), axis + 1, astGetClass( this ) ); /* Otherwise, check the axis index for validity and report an error if it is not valid (again, use one-based axis numbering). */ } else if ( ( axis < 0 ) || ( axis >= naxes ) ) { astError( AST__AXIIN, "%s(%s): Axis index (%d) invalid - it should " "be in the range 1 to %d.", status, method, astGetClass( this ), axis + 1, naxes ); /* If the axis index was valid, obtain the axis permutation array and use this to generate the permuted axis value. */ } else { perm = astGetPerm( this ); if( perm ) { /* External to internal is a simple look-up. */ if( fwd ) { result = perm[ axis ]; /* Internal to external requires a search through the permutation array. */ } else { for( result = 0; result < naxes; result++ ) { if( perm[ result ] == axis ) break; } } } } } /* Return the result. */ return result; } static void ValidateAxisSelection( AstFrame *this, int naxes, const int *axes, const char *method, int *status ) { /* *+ * Name: * astValidateAxisSelection * Purpose: * Check that a set of axes selected from a Frame is valid. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * void astValidateAxisSelection( AstFrame *this, int naxes, * const int *axes, const char *method ) * Class Membership: * Frame method. * Description: * This function checks the validity of an array of (zero-based) * axis indices that specify a set of axes to be selected from a * Frame. To be valid, no axis should be selected more than * once. In assessing this, any axis indices that do not refer to * valid Frame axes (e.g. are set to -1) are ignored. * * If the axis selection is valid, this function returns without further * action. Otherwise, an error is reported and the global error status is * set. * Parameters: * this * Pointer to the Frame. * naxes * The number of axes to be selected (may be zero). * axes * Pointer to an array of int with naxes elements that contains the * (zero based) axis indices to be checked. * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function * to validate an axis selection. This method name is used * solely for constructing error messages. *- */ /* Local Variables: */ int *count; /* Pointer to temporary array of counts */ int axis; /* Loop counter for selected axes */ int frame_axis; /* Loop counter for Frame axes */ int frame_naxes; /* Number of Frame axes */ int valid; /* Axis selection valid? */ /* Check the global error status. */ if ( !astOK ) return; /* Check to see if no axes have been selected. If so, there is nothing to do. */ if ( naxes ) { /* Initialise. */ valid = 1; /* Obtain the number of Frame axes and allocate an array of int with one element for each Frame axis. This will store a count of the number of times each axis is selected. */ frame_naxes = astGetNaxes( this ); count = astMalloc( sizeof( int ) * (size_t) frame_naxes ); if ( astOK ) { /* Initialise the array of counts to zero. */ for ( frame_axis = 0; frame_axis < frame_naxes; frame_axis++ ) { count[ frame_axis ] = 0; } /* Loop through each selected axis. */ for ( axis = 0; axis < naxes; axis++ ) { frame_axis = axes[ axis ]; /* Check if the selected axis index is valid for the Frame. If so, increment the selection count for that Frame axis. */ if ( ( frame_axis >= 0 ) && ( frame_axis < frame_naxes ) ) { count[ frame_axis ]++; } } /* Loop through the count array and check that no Frame axis was selected more than once. If it was, clear the "valid" flag and quit checking. */ for ( frame_axis = 0; frame_axis < frame_naxes; frame_axis++ ) { if ( count[ frame_axis ] > 1 ) { valid = 0; break; } } } /* Free the temporary count array. */ count = astFree( count ); /* If no error has occurred, but the axis selection is not valid, then report an error. */ if ( astOK && !valid ) { astError( AST__SELIN, "%s(%s): Invalid axis selection - each axis " "may be selected only once.", status, method, astGetClass( this ) ); } } } static int ValidateSystem( AstFrame *this, AstSystemType system, const char *method, int *status ) { /* *+ * Name: * astValidateSystem * Purpose: * Validate a value for a Frame's System attribute. * Type: * Protected virtual function. * Synopsis: * #include "frame.h" * int astValidateSystem( AstFrame *this, AstSystemType system, * const char *method ) * Class Membership: * Frame method. * Description: * This function checks the validity of the supplied system value. * If the value is valid, it is returned unchanged. Otherwise, an * error is reported and a value of AST__BADSYSTEM is returned. * Parameters: * this * Pointer to the Frame. * system * The system value to be checked. * method * Pointer to a constant null-terminated character string * containing the name of the method that invoked this function * to validate an axis index. This method name is used solely * for constructing error messages. * Returned Value: * The validated system value. * Notes: * - A value of AST_BADSYSTEM will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstSystemType result; /* Validated system value */ /* Initialise. */ result = AST__BADSYSTEM; /* Check the global error status. */ if ( !astOK ) return result; /* If the value is out of bounds, report an error. */ if ( system < FIRST_SYSTEM || system > LAST_SYSTEM ) { astError( AST__AXIIN, "%s(%s): Bad value (%d) given for the System " "or AlignSystem attribute of a %s.", status, method, astGetClass( this ), (int) system, astGetClass( this ) ); /* Otherwise, return the supplied value. */ } else { result = system; } /* Return the result. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with the axes of a Frame using the private macros defined for this purpose at the start of this file. */ /* *att++ * Name: * Naxes * Purpose: * Number of Frame axes. * Type: * Public attribute. * Synopsis: * Integer, read-only. * Description: * This is a read-only attribute giving the number of axes in a * Frame (i.e. the number of dimensions of the coordinate space * which the Frame describes). This value is determined when the * Frame is created. * Applicability: * Frame * All Frames have this attribute. * FrameSet * The Naxes attribute of a FrameSet is the same as that of its * current Frame (as specified by the Current attribute). * CmpFrame * The Naxes attribute of a CmpFrame is equal to the sum of the * Naxes values of its two component Frames. *att-- */ /* *att++ * Name: * Direction(axis) * Purpose: * Display axis in conventional direction? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which suggests how the axes of * a Frame should be displayed (e.g.) in graphical output. By * default, it has the value one, indicating that they should be * shown in the conventional sense (increasing left to right for an * abscissa, and bottom to top for an ordinate). If set to zero, * this attribute indicates that the direction should be reversed, * as would often be done for an astronomical magnitude or a right * ascension axis. * Applicability: * Frame * The default Direction value supplied by the Frame class is 1, * indicating that all axes should be displayed in the * conventional direction. * SkyFrame * The SkyFrame class re-defines the default Direction value to * suggest that certain axes (e.g. right ascension) should be * plotted in reverse when appropriate. * FrameSet * The Direction attribute of a FrameSet axis is the same as * that of its current Frame (as specified by the Current * attribute). * Plot * The Direction attribute of the base Frame in a Plot is set to * indicate the sense of the two graphics axes, as implied by the * graphics bounding box supplied when the Plot was created. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. * - The Direction attribute does not directly affect the behaviour * of the AST library. Instead, it serves as a hint to applications * programs about the orientation in which they may wish to display * any data associated with the Frame. Applications are free to * ignore this hint if they wish. *att-- */ /* This simply provides an interface to the Axis methods for accessing the Direction flag. */ MAKE_CLEAR(Direction) MAKE_GET(Direction,int,0,0,0) MAKE_SET(Direction,int) MAKE_TEST(Direction) /* *att++ * Name: * Dut1 * Purpose: * The UT1-UTC correction. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute is used when calculating the Local Apparent Sidereal * Time corresponding to SkyFrame's Epoch value (used when converting * positions to or from the "AzEl" system). It should be set to the * difference, in seconds, between the UT1 and UTC timescales at the * moment in time represented by the SkyFrame's Epoch attribute. The * value to use is unpredictable and depends on changes in the earth's * rotation speed. Values for UT1-UTC can be obtained from the * International Earth Rotation and Reference Systems Service * (IERS) at http://www.iers.org/. * * Currently, the correction is always less than 1 second. This is * ensured by the occasional introduction of leap seconds into the UTC * timescale. Therefore no great error will usually result if no value * is assigned to this attribute (in which case a default value of * zero is used). However, it is possible that a decision may be taken * at some time in the future to abandon the introduction of leap * seconds, in which case the DUT correction could grow to significant * sizes. * Applicability: * Frame * All Frames have this attribute. *att-- */ /* The UT1-UTC correction, in seconds. Has a value of AST__BAD when not set yielding a default value of 0.0. */ astMAKE_CLEAR(Frame,Dut1,dut1,AST__BAD) astMAKE_GET(Frame,Dut1,double,0.0,(this->dut1 == AST__BAD ? 0.0 : this->dut1)) astMAKE_SET(Frame,Dut1,double,dut1,value) astMAKE_TEST(Frame,Dut1,( this->dut1 != AST__BAD )) /* *att++ * Name: * Epoch * Purpose: * Epoch of observation. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute is used to qualify the coordinate systems described by * a Frame, by giving the moment in time when the coordinates are known * to be correct. Often, this will be the date of observation, and is * important in cases where coordinates systems move with respect to each * other over the course of time. * * The Epoch attribute is stored as a Modified Julian Date, but * when setting its value it may be given in a variety of * formats. See the "Input Formats" section (below) for details. * Strictly, the Epoch value should be supplied in the TDB timescale, * but for some purposes (for instance, for converting sky positions * between different types of equatorial system) the timescale is not * significant, and UTC may be used. * Input Formats: * The formats accepted when setting an Epoch value are listed * below. They are all case-insensitive and are generally tolerant * of extra white space and alternative field delimiters: * * - Besselian Epoch: Expressed in decimal years, with or without * decimal places ("B1950" or "B1976.13" for example). * * - Julian Epoch: Expressed in decimal years, with or without * decimal places ("J2000" or "J2100.9" for example). * * - Year: Decimal years, with or without decimal places ("1996.8" * for example). Such values are interpreted as a Besselian epoch * (see above) if less than 1984.0 and as a Julian epoch otherwise. * * - Julian Date: With or without decimal places ("JD 2454321.9" for * example). * * - Modified Julian Date: With or without decimal places * ("MJD 54321.4" for example). * * - Gregorian Calendar Date: With the month expressed either as an * integer or a 3-character abbreviation, and with optional decimal * places to represent a fraction of a day ("1996-10-2" or * "1996-Oct-2.6" for example). If no fractional part of a day is * given, the time refers to the start of the day (zero hours). * * - Gregorian Date and Time: Any calendar date (as above) but with * a fraction of a day expressed as hours, minutes and seconds * ("1996-Oct-2 12:13:56.985" for example). The date and time can be * separated by a space or by a "T" (as used by ISO8601 format). * Output Format: * When enquiring Epoch values, the format used is the "Year" * format described under "Input Formats". This is a value in * decimal years which will be a Besselian epoch if less than * 1984.0 and a Julian epoch otherwise. By omitting any character * prefix, this format allows the Epoch value to be obtained as * either a character string or a floating point value. * Applicability: * Frame * All Frames have this attribute. The basic Frame class provides * a default of J2000.0 (Julian) but makes no use of the Epoch value. * This is because the Frame class does not distinguish between * different Cartesian coordinate systems (see the System attribute). * CmpFrame * The default Epoch value for a CmpFrame is selected as follows; * if the Epoch attribute has been set in the first component Frame * then the Epoch value from the first component Frame is used as * the default for the CmpFrame. Otherwise, if the Epoch attribute has * been set in the second component Frame then the Epoch value from the * second component Frame is used as the default for the CmpFrame. * Otherwise, the default Epoch value from the first component * Frame is used as the default for the CmpFrame. When the Epoch * attribute of a CmpFrame is set or cleared, it is also set or * cleared in the two component Frames. * FrameSet * The Epoch attribute of a FrameSet is the same as that of its current * Frame (as specified by the Current attribute). * SkyFrame * The coordinates of sources within a SkyFrame can changed with time * for various reasons, including: (i) changing aberration of light * caused by the observer's velocity (e.g. due to the Earth's motion * around the Sun), (ii) changing gravitational deflection by the Sun * due to changes in the observer's position with time, (iii) fictitious * motion due to rotation of non-inertial coordinate systems (e.g. the * old FK4 system), and (iv) proper motion of the source itself (although * this last effect is not handled by the SkyFrame class because it * affects individual sources rather than the coordinate system as * a whole). * * The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the * old FK4-based coordinate systems (see the System attribute) and * J2000.0 (Julian) for all others. * * Care must be taken to distinguish the Epoch value, which relates to * motion (or apparent motion) of the source, from the superficially * similar Equinox value. The latter is used to qualify a coordinate * system which is itself in motion in a (notionally) predictable way * as a result of being referred to a slowly moving reference plane * (e.g. the equator). * * See the description of the System attribute for details of which * qualifying attributes apply to each celestial coordinate system. * TimeFrame * A TimeFrame describes a general time axis and so cannot be completely * characterised by a single Epoch value. For this reason the TimeFrame * class makes no use of the Epoch attribute. However, user code can * still make use of the attribute if necessary to represent a "typical" * time spanned by the TimeFrame. The default Epoch value for a TimeFrame * will be the TDB equivalent of the current value of the TimeFrame's * TimeOrigin attribute. If no value has been set for TimeOrigin, * then the default Epoch value is J2000.0. The coordinates of sources within a SkyFrame can changed with time *att-- */ /* Clear the Epoch value by setting it to AST__BAD. */ astMAKE_CLEAR(Frame,Epoch,epoch,AST__BAD) /* Provide a default value of J2000.0 setting. */ astMAKE_GET(Frame,Epoch,double,AST__BAD,( ( this->epoch != AST__BAD ) ? this->epoch : palEpj2d( 2000.0 ))) /* Allow any Epoch value to be set. */ astMAKE_SET(Frame,Epoch,double,epoch,value) /* An Epoch value is set if it is not equal to AST__BAD. */ astMAKE_TEST(Frame,Epoch,( this->epoch != AST__BAD )) /* *att++ * Name: * Top(axis) * Purpose: * Highest axis value to display * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute gives the highest axis value to be displayed (for c instance, by the astGrid method). f instance, by the AST_GRID method). * Applicability: * Frame * The default supplied by the Frame class is to display all axis * values, without any limit. * SkyFrame * The SkyFrame class re-defines the default Top value to +90 degrees * for latitude axes, and 180 degrees for co-latitude axes. The * default for longitude axes is to display all axis values. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This simply provides an interface to the Axis methods for accessing the Top value. */ MAKE_CLEAR(Top) MAKE_GET(Top,double,DBL_MAX,0,DBL_MAX) MAKE_SET(Top,double) MAKE_TEST(Top) /* *att++ * Name: * Bottom(axis) * Purpose: * Lowest axis value to display * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute gives the lowest axis value to be displayed (for c instance, by the astGrid method). f instance, by the AST_GRID method). * Applicability: * Frame * The default supplied by the Frame class is to display all axis * values, without any limit. * SkyFrame * The SkyFrame class re-defines the default Bottom value to -90 degrees * for latitude axes, and 0 degrees for co-latitude axes. The * default for longitude axes is to display all axis values. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This simply provides an interface to the Axis methods for accessing the Bottom value. */ MAKE_CLEAR(Bottom) MAKE_GET(Bottom,double,-DBL_MAX,0,-DBL_MAX) MAKE_SET(Bottom,double) MAKE_TEST(Bottom) /* *att++ * Name: * Format(axis) * Purpose: * Format specification for axis values. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the format to be used when displaying * coordinate values associated with a particular Frame axis * (i.e. to convert values from binary to character form). It is c interpreted by the astFormat function and determines the f interpreted by the AST_FORMAT function and determines the * formatting which it applies. * * If no Format value is set for a Frame axis, a default value is * supplied instead. This is based on the value of the Digits, or * Digits(axis), attribute and is chosen so that it displays the * requested number of digits of precision. * Applicability: * Frame * The Frame class interprets this attribute as a format * specification string to be passed to the C "printf" function * (e.g. "%1.7G") in order to format a single coordinate value * (supplied as a double precision number). c c When supplying a value for this attribute, beware that the c "%" character may be interpreted directly as a format c specification by some printf-like functions (such as c astSet). You may need to double it (i.e. use "%%") to avoid c this. * SkyFrame * The SkyFrame class re-defines the syntax and default value of * the Format string to allow the formatting of sexagesimal * values as appropriate for the particular celestial coordinate * system being represented. The syntax of SkyFrame Format * strings is described (below) in the "SkyFrame Formats" * section. * FrameSet * The Format attribute of a FrameSet axis is the same as that * of its current Frame (as specified by the Current * attribute). Note that the syntax of the Format string is also * determined by the current Frame. * TimeFrame * The TimeFrame class extends the syntax of the Format string to * allow the formatting of TimeFrame axis values as Gregorian calendar * dates and times. The syntax of TimeFrame Format strings is described * (below) in the "TimeFrame Formats" section. * SkyFrame Formats: * The Format string supplied for a SkyFrame should contain zero or * more of the following characters. These may occur in any order, * but the following is recommended for clarity: * * - "+": Indicates that a plus sign should be prefixed to positive * values. By default, no plus sign is used. * * - "z": Indicates that leading zeros should be prefixed to the * value so that the first field is of constant width, as would be * required in a fixed-width table (leading zeros are always * prefixed to any fields that follow). By default, no leading * zeros are added. * * - "i": Use the standard ISO field separator (a colon) between * fields. This is the default behaviour. * * - "b": Use a blank to separate fields. * * - "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to * separate fields. * * - "g": Use a letter and symbols to separate fields ("h"/"d", "m" or "s", * etc, as appropriate), but include escape sequences in the formatted * value so that the Plot class will draw the separators as small * super-scripts. c The default escape sequences are optimised for the pgplot graphics c package, but new escape sequences may be specified using function c astSetSkyDelim. * * - "d": Include a degrees field. Expressing the angle purely in * degrees is also the default if none of "h", "m", "s" or "t" are * given. * * - "h": Express the angle as a time and include an hours field * (where 24 hours correspond to 360 degrees). Expressing the angle * purely in hours is also the default if "t" is given without * either "m" or "s". * * - "m": Include a minutes field. By default this is not included. * * - "s": Include a seconds field. By default this is not included. * This request is ignored if "d" or "h" is given, unless a minutes * field is also included. * * - "t": Express the angle as a time (where 24 hours correspond to * 360 degrees). This option is ignored if either "d" or "h" is * given and is intended for use where the value is to be expressed * purely in minutes and/or seconds of time (with no hours * field). If "t" is given without "d", "h", "m" or "s" being * present, then it is equivalent to "h". * * - ".": Indicates that decimal places are to be given for the * final field in the formatted string (whichever field this * is). The "." should be followed immediately by an unsigned * integer which gives the number of decimal places required, or by an * asterisk. If an asterisk is supplied, a default number of decimal * places is used which is based on the value of the Digits * attribute. * * All of the above format specifiers are case-insensitive. If * several characters make conflicting requests (e.g. if both "i" * and "b" appear), then the character occurring last takes * precedence, except that "d" and "h" always override "t". * * If the format string starts with a percentage sign (%), then the * whole format string is assumed to conform to the syntax defined by * the Frame class, and the axis values is formated as a decimal * radians value. * TimeFrame Formats: * The Format string supplied for a TimeFrame should either use the * syntax defined by the base Frame class (i.e. a C "printf" format * string), or the extended "iso" syntax described below (the default * value is inherited from the Frame class): * * - C "printf" syntax: If the Format string is a C "printf" format * description such as "%1.7G", the TimeFrame axis value will be * formatted without change as a floating point value using this format. * The formatted string will thus represent an offset from the zero point * specified by the TimeFrame's TimeOrigin attribute, measured in * units given by the TimeFrame's Unit attribute. * * - "iso" syntax: This is used to format a TimeFrame axis value as a * Gregorian date followed by an optional time of day. If the Format * value commences with the string "iso" then the TimeFrame axis value * will be converted to an absolute MJD, including the addition of the * current TimeOrigin value, and then formatted as a Gregorian date * using the format "yyyy-mm-dd". Optionally, the Format value may * include an integer precision following the "iso" specification (e.g. * "iso.2"), in which case the time of day will be appended to the * formatted date (if no time of day is included, the date field is * rounded to the nearest day). The integer value in the Format string * indicates the number of decimal places to use in the seconds field. For * instance, a Format value of "iso.0" produces a time of day of the form * "hh:mm:ss", and a Format value of "iso.2" produces a time of day of the * form "hh:mm:ss.ss". The date and time fields will be separated by a * space unless 'T' is appended to the end of string, in which case * the letter T (upper case) will be used as the separator. The value of * the Digits attribute is ignored when using this "iso" format. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This simply provides an interface to the Axis methods for accessing the Format string. */ MAKE_CLEAR(Format) MAKE_GET(Format,const char *,NULL,0,0) MAKE_SET(Format,const char *) MAKE_TEST(Format) /* *att++ * Name: * Label(axis) * Purpose: * Axis label. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies a label to be attached to each axis of * a Frame when it is represented (e.g.) in graphical output. * * If a Label value has not been set for a Frame axis, then a * suitable default is supplied. * Applicability: * Frame * The default supplied by the Frame class is the string "Axis * ", where is 1, 2, etc. for each successive axis. * SkyFrame * The SkyFrame class re-defines the default Label value * (e.g. to "Right ascension" or "Galactic latitude") as * appropriate for the particular celestial coordinate system * being represented. * TimeFrame * The TimeFrame class re-defines the default Label value as * appropriate for the particular time system being represented. * FrameSet * The Label attribute of a FrameSet axis is the same as that of * its current Frame (as specified by the Current attribute). * Notes: * - Axis labels are intended purely for interpretation by human * readers and not by software. * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This provides an interface to the Axis methods for accessing the Label string, but provides an alternative default Label based on the axis number. This default string is written to the static "label_buff" buffer and a pointer to this is returned if required. */ MAKE_CLEAR(Label) MAKE_GET(Label,const char *,NULL,1,GetDefaultLabel( axis, status )) MAKE_SET(Label,const char *) MAKE_TEST(Label) /* *att++ * Name: * Symbol(axis) * Purpose: * Axis symbol. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies a short-form symbol to be used to * represent coordinate values for a particular axis of a * Frame. This might be used (e.g.) in algebraic expressions where * a full description of the axis would be inappropriate. Examples * include "RA" and "Dec" (for Right Ascension and Declination). * * If a Symbol value has not been set for a Frame axis, then a * suitable default is supplied. * Applicability: * Frame * The default Symbol value supplied by the Frame class is the * string "", where is 1, 2, etc. for successive * axes, and is the value of the Frame's Domain * attribute (truncated if necessary so that the final string * does not exceed 15 characters). If no Domain value has been * set, "x" is used as the value in constructing this * default string. * SkyFrame * The SkyFrame class re-defines the default Symbol value * (e.g. to "RA" or "Dec") as appropriate for the particular * celestial coordinate system being represented. * TimeFrame * The TimeFrame class re-defines the default Symbol value as * appropriate for the particular time system being represented. * FrameSet * The Symbol attribute of a FrameSet axis is the same as that * of its current Frame (as specified by the Current attribute). * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This provides an interface to the Axis methods for accessing the Symbol string, but provides an alternative default Symbol based on the axis number and the Frame's Domain (if defined, otherwise "x" is used). This default string is written to the static "symbol_buff" buffer and a pointer to this is returned if required. */ MAKE_CLEAR(Symbol) MAKE_GET(Symbol,const char *,NULL,1,GetDefaultSymbol( this, axis, status ) ) MAKE_SET(Symbol,const char *) MAKE_TEST(Symbol) /* *att++ * Name: * Unit(axis) * Purpose: * Physical units for formatted axis values * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute contains a textual representation of the physical * units used to represent formatted coordinate values on a particular * axis of a Frame. c The astSetActiveUnit function controls how the Unit values f The AST_SETACTIVEUNIT routine controls how the Unit values * are used. * Applicability: * Frame * The default supplied by the Frame class is an empty string. * SkyFrame * The SkyFrame class re-defines the default Unit value (e.g. to * "hh:mm:ss.sss") to describe the character string returned by c the astFormat function when formatting coordinate values. f the AST_FORMAT function when formatting coordinate values. * SpecFrame * The SpecFrame class re-defines the default Unit value so that it * is appropriate for the current System value. See the System * attribute for details. An error will be reported if an attempt * is made to use an inappropriate Unit. * TimeFrame * The TimeFrame class re-defines the default Unit value so that it * is appropriate for the current System value. See the System * attribute for details. An error will be reported if an attempt * is made to use an inappropriate Unit (e.g. "km"). * FrameSet * The Unit attribute of a FrameSet axis is the same as that of * its current Frame (as specified by the Current attribute). * Notes: * - This attribute described the units used when an axis value is * formatted into a string using c astFormat. f AST_FORMAT. * In some cases these units may be different to those used to represent * floating point axis values within application code (for instance a * SkyFrame always uses radians to represent floating point axis values). * The InternalUnit attribute described the units used for floating * point values. * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This simply provides an interface to the Axis methods for accessing the Unit string. */ MAKE_GET(Unit,const char *,NULL,0,0) MAKE_TEST(Unit) /* *att++ * Name: * NormUnit(axis) * Purpose: * Normalised physical units for formatted axis values * Type: * Public attribute. * Synopsis: * String, read-only. * Description: * The value of this read-only attribute is derived from the current * value of the Unit attribute. It will represent an equivalent system * of units to the Unit attribute, but will potentially be simplified. * For instance, if Unit is set to "s*(m/s)", the NormUnit value will * be "m". If no simplification can be performed, the value of the * NormUnit attribute will equal that of the Unit attribute. * Applicability: * Frame * All Frames have this attribute. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* This simply provides an interface to the Axis methods for accessing the NormUnit string. */ MAKE_GET(NormUnit,const char *,NULL,0,0) /* *att++ * Name: * InternalUnit(axis) * Purpose: * Physical units for unformated axis values * Type: * Public attribute. * Synopsis: * String, read-only. * Description: * This read-only attribute contains a textual representation of the * physical units used to represent unformatted (i.e. floating point) * values on a particular axis of a Frame, typically handled internally * within application code. In most cases, the value of the InternalUnit * attribute will be the same as Unit attribute (i.e. formatted and * unformatted axis values will normally use the same system of units). * The main exception to this is the SkyFrame class, which represents * unformatted axis values in radians, regardless of the current * setting of the Unit attribute. * Applicability: * Frame * All Frames have this attribute. * Notes: * - When specifying this attribute by name, it should be * subscripted with the number of the Frame axis to which it * applies. *att-- */ /* If the Axis structure provides a value for InternalUnit, then use that value. Otherwise, use a default equal to the value of the Unit attribute for the axis. */ MAKE_GET(InternalUnit,const char *,NULL,1,astGetUnit(this,axis)) /* Implement member functions to access the attributes associated with the Frame as a whole using the macros defined for this purpose in the "object.h" file. */ /* *att++ * Name: * Digits/Digits(axis) * Purpose: * Number of digits of precision. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute specifies how many digits of precision are * required by default when a coordinate value is formatted for a c Frame axis (e.g. using astFormat). Its value may be set either f Frame axis (e.g. using AST_FORMAT). Its value may be set either * for a Frame as a whole, or (by subscripting the attribute name * with the number of an axis) for each axis individually. Any * value set for an individual axis will over-ride the value for * the Frame as a whole. * * Note that the Digits value acts only as a means of determining a * default Format string. Its effects are over-ridden if a Format * string is set explicitly for an axis. However, if the Format * attribute specifies the precision using the string ".*", then * the Digits attribute is used to determine the number of decimal * places to produce. * Applicability: * Frame * The default Digits value supplied by the Frame class is 7. If * a value less than 1 is supplied, then 1 is used instead. * FrameSet * The Digits attribute of a FrameSet (or one of its axes) is * the same as that of its current Frame (as specified by the * Current attribute). * Plot * The default Digits value used by the Plot class when drawing * annotated axis labels is the smallest value which results in all * adjacent labels being distinct. * TimeFrame * The Digits attribute is ignored when a TimeFrame formats a value * as a date and time string (see the Format attribute). *att-- */ /* Clear the Digits value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,Digits,digits,-INT_MAX) /* Supply a default of 7 digits if no value has been set. */ astMAKE_GET(Frame,Digits,int,0,( ( this->digits != -INT_MAX ) ? this->digits : 7 )) /* Constrain the Digits value being set to be at least 1. */ astMAKE_SET(Frame,Digits,int,digits,( value > 1 ? value : 1 )) /* The Digits value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,Digits,( this->digits != -INT_MAX )) /* *att++ * Name: * MatchEnd * Purpose: * Match trailing axes? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute is a boolean value which controls how a Frame c behaves when it is used (by astFindFrame) as a template to match f behaves when it is used (by AST_FINDFRAME) as a template to match * another (target) Frame. It applies only in the case where a * match occurs between template and target Frames with different * numbers of axes. * * If the MatchEnd value of the template Frame is zero, then the * axes which occur first in the target Frame will be matched and * any trailing axes (in either the target or template) will be * disregarded. If it is non-zero, the final axes in each Frame * will be matched and any un-matched leading axes will be * disregarded instead. * Applicability: * Frame * The default MatchEnd value for a Frame is zero, so that * trailing axes are disregarded. * FrameSet * The MatchEnd attribute of a FrameSet is the same as that of * its current Frame (as specified by the Current attribute). *att-- */ /* Clear the MatchEnd value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,MatchEnd,match_end,-INT_MAX) /* Supply a default of 0 if no MatchEnd value has been set. */ astMAKE_GET(Frame,MatchEnd,int,0,( ( this->match_end != -INT_MAX ) ? this->match_end : 0 )) /* Set a MatchEnd value of 1 if any non-zero value is supplied. */ astMAKE_SET(Frame,MatchEnd,int,match_end,( value != 0 )) /* The MatchEnd value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,MatchEnd,( this->match_end != -INT_MAX )) /* *att++ * Name: * MaxAxes * Purpose: * Maximum number of Frame axes to match. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute controls how a Frame behaves when it is used (by c astFindFrame) as a template to match another (target) Frame. It f AST_FINDFRAME) as a template to match another (target) Frame. It * specifies the maximum number of axes that the target Frame may * have in order to match the template. * * Normally, this value will equal the number of Frame axes, so * that a template Frame will only match another Frame with the * same number of axes as itself. By setting a different value, * however, the matching process may be used to identify Frames * with specified numbers of axes. * Applicability: * Frame * The default MaxAxes value for a Frame is equal to the number * of Frame axes (Naxes attribute). * CmpFrame * The MaxAxes attribute of a CmpFrame defaults to a large number * (1000000) which is much larger than any likely number of axes in * a Frame. Combined with the MinAxes default of zero (for a * CmpFrame), this means that the default behaviour for a CmpFrame * is to match any target Frame that consists of a subset of the * axes in the template CmpFrame. To change this so that a CmpFrame * will only match Frames that have the same number of axes, you * should set the CmpFrame MaxAxes and MinAxes attributes to the * number of axes in the CmpFrame. * FrameSet * The MaxAxes attribute of a FrameSet is the same as that of * its current Frame (as specified by the Current attribute). * Notes: * - When setting a MaxAxes value, the value of the MinAxes * attribute may also be silently changed so that it remains * consistent with (i.e. does not exceed) the new value. The * default MaxAxes value may also be reduced to remain consistent * with the MinAxes value. * - If a template Frame is used to match a target with a different * number of axes, the MatchEnd attribute of the template is used * to determine how the individual axes of each Frame should match. *att-- */ /* Clear the MaxAxes value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,MaxAxes,max_axes,-INT_MAX) /* Use the DefaultMaxAxes and ConsistentMaxAxes functions (defined earlier) for the Get and Set operations to ensure that MinAxes and MaxAxes values remain consistent. */ astMAKE_GET(Frame,MaxAxes,int,0,DefaultMaxAxes( this, status )) astMAKE_SET(Frame,MaxAxes,int,max_axes,ConsistentMaxAxes( this, value, status )) /* The MaxAxes value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,MaxAxes,( this->max_axes != -INT_MAX )) /* *att++ * Name: * MinAxes * Purpose: * Minimum number of Frame axes to match. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute controls how a Frame behaves when it is used (by c astFindFrame) as a template to match another (target) Frame. It f AST_FINDFRAME) as a template to match another (target) Frame. It * specifies the minimum number of axes that the target Frame may * have in order to match the template. * * Normally, this value will equal the number of Frame axes, so * that a template Frame will only match another Frame with the * same number of axes as itself. By setting a different value, * however, the matching process may be used to identify Frames * with specified numbers of axes. * Applicability: * Frame * The default MinAxes value for a Frame is equal to the number * of Frame axes (Naxes attribute). * CmpFrame * The MinAxes attribute of a CmpFrame defaults to zero. Combined * with the MaxAxes default of 1000000 (for a CmpFrame), this means * that the default behaviour for a CmpFrame is to match any target * Frame that consists of a subset of the axes in the template * CmpFrame. To change this so that a CmpFrame will only match Frames * that have the same number of axes, you should set the CmpFrame * MinAxes and MaxAxes attributes to the number of axes in the CmpFrame. * FrameSet * The MinAxes attribute of a FrameSet is the same as that of * its current Frame (as specified by the Current attribute). * Notes: * - When setting a MinAxes value, the value of the MaxAxes * attribute may also be silently changed so that it remains * consistent with (i.e. is not less than) the new value. The * default MinAxes value may also be reduced to remain consistent * with the MaxAxes value. * - If a template Frame is used to match a target with a different * number of axes, the MatchEnd attribute of the template is used * to determine how the individual axes of each Frame should match. *att-- */ /* Clear the MinAxes value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,MinAxes,min_axes,-INT_MAX) /* Use the DefaultMinAxes and ConsistentMinAxes functions (defined earlier) for the Get and Set operations to ensure that MinAxes and MaxAxes values remain consistent. */ astMAKE_GET(Frame,MinAxes,int,0,DefaultMinAxes( this, status )) astMAKE_SET(Frame,MinAxes,int,min_axes,ConsistentMinAxes( this, value, status )) /* The MinAxes value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,MinAxes,( this->min_axes != -INT_MAX )) /* *att++ * Name: * Domain * Purpose: * Coordinate system domain. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute contains a string which identifies the physical * domain of the coordinate system that a Frame describes. * * The Domain attribute also controls how a Frame behaves when it is c used (by astFindFrame) as a template to match another (target) f used (by AST_FINDFRAME) as a template to match another (target) * Frame. It does this by specifying the Domain that the target * Frame should have in order to match the template. If the Domain * value in the template Frame is set, then only targets with the * same Domain value will be matched. If the template's Domain * value is not set, however, then the target's Domain will be * ignored. * Applicability: * Frame * The default Domain value supplied by the Frame class is an * empty string. * SkyFrame * The SkyFrame class re-defines the default Domain value to be * "SKY". * CmpFrame * The CmpFrame class re-defines the default Domain value to be * of the form "-", where and are the * Domains of the two component Frames. If both these Domains are * blank, then the string "CMP" is used as the default Domain name. * FrameSet * The Domain attribute of a FrameSet is the same as that of its * current Frame (as specified by the Current attribute). * SpecFrame * The SpecFrame class re-defines the default Domain value to be * "SPECTRUM". * DSBSpecFrame * The DSBSpecFrame class re-defines the default Domain value to be * "DSBSPECTRUM". * FluxFrame * The FluxFrame class re-defines the default Domain value to be * "FLUX". * SpecFluxFrame * The FluxFrame class re-defines the default Domain value to be * "SPECTRUM-FLUX". * TimeFrame * The TimeFrame class re-defines the default Domain value to be * "TIME". * Notes: * - All Domain values are converted to upper case and white space * is removed before use. *att-- */ /* Clear the Domain value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Frame,Domain,domain,astFree( this->domain )) /* If the Domain value is not set, supply a default in the form of a pointer to the constant string "". */ astMAKE_GET(Frame,Domain,const char *,NULL,( this->domain ? this->domain : "" )) /* Set a Domain value by freeing any previously allocated memory, allocating new memory, storing the string, removing white space, converting to upper case and saving the pointer to the cleaned copy. */ astMAKE_SET(Frame,Domain,const char *,domain,CleanDomain( astStore( this->domain, value, strlen( value ) + (size_t) 1 ), status )) /* The Domain value is set if the pointer to it is not NULL. */ astMAKE_TEST(Frame,Domain,( this->domain != NULL )) /* *att++ * Name: * Permute * Purpose: * Permute axis order? * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute is a boolean value which controls how a Frame c behaves when it is used (by astFindFrame) as a template to match f behaves when it is used (by AST_FINDFRAME) as a template to match * another (target) Frame. It specifies whether the axis order of * the target Frame may be permuted in order to obtain a match. * * If the template's Permute value is zero, it will match a target * only if it can do so without changing the order of its * axes. Otherwise, it will attempt to permute the target's axes as * necessary. * * The default value is 1, so that axis permutation will be attempted. * Applicability: * Frame * All Frames have this attribute. However, the Frame class * effectively ignores this attribute and behaves as if it has * the value 1. This is because the axes of a basic Frame are * not distinguishable and will always match any other Frame * whatever their order. * SkyFrame * Unlike a basic Frame, the SkyFrame class makes use of this * attribute. * FrameSet * The Permute attribute of a FrameSet is the same as that of * its current Frame (as specified by the Current attribute). *att-- */ /* Clear the Permute value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,Permute,permute,-INT_MAX) /* Supply a default of 1 if no Permute value has been set. */ astMAKE_GET(Frame,Permute,int,0,( ( this->permute != -INT_MAX ) ? this->permute : 1 )) /* Set a Permute value of 1 if any non-zero value is supplied. */ astMAKE_SET(Frame,Permute,int,permute,( value != 0 )) /* The Permute value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,Permute,( this->permute != -INT_MAX )) /* *att++ * Name: * PreserveAxes * Purpose: * Preserve axes? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute controls how a Frame behaves when it is used (by c astFindFrame) as a template to match another (target) Frame. It f AST_FINDFRAME) as a template to match another (target) Frame. It * determines which axes appear (and in what order) in the "result" * Frame produced. * * If PreserveAxes is zero in the template Frame, then the result * Frame will have the same number (and order) of axes as the * template. If it is non-zero, however, the axes of the target * Frame will be preserved, so that the result Frame will have the * same number (and order) of axes as the target. * * The default value is zero, so that target axes are not preserved * and the result Frame resembles the template. * Applicability: * Frame * All Frames have this attribute. * FrameSet * The PreserveAxes attribute of a FrameSet is the same as that * of its current Frame (as specified by the Current attribute). *att-- */ /* Clear the PreserveAxes value by setting it to -INT_MAX. */ astMAKE_CLEAR(Frame,PreserveAxes,preserve_axes,-INT_MAX) /* Supply a default of 0 if no PreserveAxes value has been set. */ astMAKE_GET(Frame,PreserveAxes,int,0,( ( this->preserve_axes != -INT_MAX ) ? this->preserve_axes : 0 )) /* Set a PreserveAxes value of 1 if any non-zero value is supplied. */ astMAKE_SET(Frame,PreserveAxes,int,preserve_axes,( value != 0 )) /* The PreserveAxes value is set if it is not -INT_MAX. */ astMAKE_TEST(Frame,PreserveAxes,( this->preserve_axes != -INT_MAX )) /* *att++ * Name: * AlignSystem * Purpose: * Coordinate system in which to align the Frame. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute controls how a Frame behaves when it is used (by c astFindFrame or astConvert) as a template to match another (target) f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) * Frame. It identifies the coordinate system in which the two Frames * will be aligned by the match. * * The values which may be assigned to this attribute, and its default * value, depend on the class of Frame and are described in the * "Applicability" section below. In general, the AlignSystem attribute * will accept any of the values which may be assigned to the System * attribute. * c The Mapping returned by AST_FINDFRAME or AST_CONVERT will use the f The Mapping returned by astFindFrame or astConvert will use the * coordinate system specified by the AlignSystem attribute as an * intermediate coordinate system. The total returned Mapping will first * map positions from the first Frame into this intermediate coordinate * system, using the attributes of the first Frame. It will then map * these positions from the intermediate coordinate system into the * second Frame, using the attributes of the second Frame. * Applicability: * Frame * The AlignSystem attribute for a basic Frame always equals "Cartesian", * and may not be altered. * CmpFrame * The AlignSystem attribute for a CmpFrame always equals "Compound", * and may not be altered. * FrameSet * The AlignSystem attribute of a FrameSet is the same as that of its * current Frame (as specified by the Current attribute). * SkyFrame * The default AlignSystem attribute for a SkyFrame is "ICRS". * SpecFrame * The default AlignSystem attribute for a SpecFrame is "Wave" * (wavelength). * TimeFrame * The default AlignSystem attribute for a TimeFrame is "MJD". *att-- */ /* Clear the AlignSystem value by setting it to AST__BADSYSTEM. */ astMAKE_CLEAR(Frame,AlignSystem,alignsystem,AST__BADSYSTEM) /* Provide a default AlignSystem of AST__CART. */ astMAKE_GET(Frame,AlignSystem,AstSystemType,AST__BADSYSTEM,( ( this->alignsystem == AST__BADSYSTEM ) ? AST__CART : this->alignsystem ) ) /* Validate the AlignSystem value being set and retain the original if the supplied value is not recognized. */ astMAKE_SET(Frame,AlignSystem,AstSystemType,alignsystem,( (astValidateSystem( this, value, "astSetAlignSystem" ) != AST__BADSYSTEM) ? value : this->alignsystem )) /* The AlignSystem value is set if it is not AST__BADSYSTEM. */ astMAKE_TEST(Frame,AlignSystem,( this->alignsystem != AST__BADSYSTEM )) /* *att++ * Name: * System * Purpose: * Coordinate system used to describe positions within the domain * Type: * Public attribute. * Synopsis: * String. * Description: * In general it is possible for positions within a given physical * domain to be described using one of several different coordinate * systems. For instance, the SkyFrame class can use galactic * coordinates, equatorial coordinates, etc, to describe positions on * the sky. As another example, the SpecFrame class can use frequency, * wavelength, velocity, etc, to describe a position within an * electromagnetic spectrum. The System attribute identifies the particular * coordinate system represented by a Frame. Each class of Frame * defines a set of acceptable values for this attribute, as listed * below (all are case insensitive). Where more than one alternative * System value is shown, the first of will be returned when an * enquiry is made. * Applicability: * Frame * The System attribute for a basic Frame always equals "Cartesian", * and may not be altered. * CmpFrame * The System attribute for a CmpFrame always equals "Compound", * and may not be altered. In addition, the CmpFrame class allows * the System attribute to be referenced for a component Frame by * including the index of an axis within the required component * Frame. For instance, "System(3)" refers to the System attribute * of the component Frame which includes axis 3 of the CmpFrame. * FrameSet * The System attribute of a FrameSet is the same as that of its * current Frame (as specified by the Current attribute). * SkyFrame * The SkyFrame class supports the following System values and * associated celestial coordinate systems: * * - "AZEL": Horizon coordinates. The longitude axis is azimuth * such that geographic north has an azimuth of zero and geographic * east has an azimuth of +PI/2 radians. The zenith has elevation * +PI/2. When converting to and from other celestial coordinate * systems, no corrections are applied for atmospheric refraction * or polar motion (however, a correction for diurnal aberattion is * applied). Note, unlike most other * celestial coordinate systems, this system is right handed. Also, * unlike other SkyFrame systems, the AzEl system is sensitive to * the timescale in which the Epoch value is supplied. This is * because of the gross diurnal rotation which this system undergoes, * causing a small change in time to translate to a large rotation. * When converting to or from an AzEl system, the Epoch value for * both source and destination SkyFrames should be supplied in the * TDB timescale. The difference between TDB and TT is between 1 * and 2 milliseconds, and so a TT value can usually be supplied in * place of a TDB value. The TT timescale is related to TAI via * TT = TAI + 32.184 seconds. * * - "ECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the * ecliptic and mean equinox specified by the qualifying Equinox * value. * * - "FK4": The old FK4 (barycentric) equatorial coordinate system, * which should be qualified by an Equinox value. The underlying * model on which this is based is non-inertial and rotates slowly * with time, so for accurate work FK4 coordinate systems should * also be qualified by an Epoch value. * * - "FK4-NO-E" or "FK4_NO_E": The old FK4 (barycentric) equatorial * system but without the "E-terms of aberration" (e.g. some radio * catalogues). This coordinate system should also be qualified by * both an Equinox and an Epoch value. * * - "FK5" or "EQUATORIAL": The modern FK5 (barycentric) equatorial * coordinate system. This should be qualified by an Equinox value. * * - "GALACTIC": Galactic coordinates (IAU 1958). * * - "GAPPT", "GEOCENTRIC" or "APPARENT": The geocentric apparent * equatorial coordinate system, which gives the apparent positions * of sources relative to the true plane of the Earth's equator and * the equinox (the coordinate origin) at a time specified by the * qualifying Epoch value. (Note that no Equinox is needed to * qualify this coordinate system because no model "mean equinox" * is involved.) These coordinates give the apparent right * ascension and declination of a source for a specified date of * observation, and therefore form an approximate basis for * pointing a telescope. Note, however, that they are applicable to * a fictitious observer at the Earth's centre, and therefore * ignore such effects as atmospheric refraction and the (normally * much smaller) aberration of light due to the rotational velocity * of the Earth's surface. Geocentric apparent coordinates are * derived from the standard FK5 (J2000.0) barycentric coordinates * by taking account of the gravitational deflection of light by * the Sun (usually small), the aberration of light caused by the * motion of the Earth's centre with respect to the barycentre * (larger), and the precession and nutation of the Earth's spin * axis (normally larger still). * * - "HELIOECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the * ecliptic and mean equinox of J2000.0, in which an offset is added to * the longitude value which results in the centre of the sun being at * zero longitude at the date given by the Epoch attribute. Attempts to * set a value for the Equinox attribute will be ignored, since this * system is always referred to J2000.0. * * - "ICRS": The Internation Celestial Reference System, realised * through the Hipparcos catalogue. Whilst not an equatorial system * by definition, the ICRS is very close to the FK5 (J2000) system * and is usually treated as an equatorial system. The distinction * between ICRS and FK5 (J2000) only becomes important when accuracies * of 50 milli-arcseconds or better are required. ICRS need not be * qualified by an Equinox value. * * - "J2000": An equatorial coordinate system based on the mean * dynamical equator and equinox of the J2000 epoch. The dynamical * equator and equinox differ slightly from those used by the FK5 * model, and so a "J2000" SkyFrame will differ slightly from an * "FK5(Equinox=J2000)" SkyFrame. The J2000 System need not be * qualified by an Equinox value * * - "SUPERGALACTIC": De Vaucouleurs Supergalactic coordinates. * * - "UNKNOWN": Any other general spherical coordinate system. No * Mapping can be created between a pair of SkyFrames if either of the * SkyFrames has System set to "Unknown". * * Currently, the default System value is "ICRS". However, this * default may change in future as new astrometric standards * evolve. The intention is to track the most modern appropriate * standard. For this reason, you should use the default only if * this is what you intend (and can tolerate any associated slight * change in future). If you intend to use the ICRS system * indefinitely, then you should specify it explicitly. * SpecFrame * The SpecFrame class supports the following System values and * associated spectral coordinate systems (the default is "WAVE" - * wavelength). They are all defined in FITS-WCS paper III: * * - "FREQ": Frequency (GHz) * - "ENER" or "ENERGY": Energy (J) * - "WAVN" or "WAVENUM": Wave-number (1/m) * - "WAVE" or "WAVELEN": Vacuum wave-length (Angstrom) * - "AWAV" or "AIRWAVE": Wave-length in air (Angstrom) * - "VRAD" or "VRADIO": Radio velocity (km/s) * - "VOPT" or "VOPTICAL": Optical velocity (km/s) * - "ZOPT" or "REDSHIFT": Redshift (dimensionless) * - "BETA": Beta factor (dimensionless) * - "VELO" or "VREL": Apparent radial ("relativistic") velocity (km/s) * * The default value for the Unit attribute for each system is shown * in parentheses. Note that the default value for the ActiveUnit flag c is non-zero f is .TRUE. * for a SpecFrame, meaning that changes to the Unit attribute for * a SpecFrame will result in the SpecFrame being re-mapped within * its enclosing FrameSet in order to reflect the change in units c (see astSetActiveUnit function for further information). f (see AST_SETACTIVEUNIT routine for further information). * TimeFrame * The TimeFrame class supports the following System values and * associated coordinate systems (the default is "MJD"): * * - "MJD": Modified Julian Date (d) * - "JD": Julian Date (d) * - "JEPOCH": Julian epoch (yr) * - "BEPOCH": Besselian (yr) * * The default value for the Unit attribute for each system is shown * in parentheses. Strictly, these systems should not allow changes * to be made to the units. For instance, the usual definition of * "MJD" and "JD" include the statement that the values will be in * units of days. However, AST does allow the use of other units * with all the above supported systems (except BEPOCH), on the * understanding that conversion to the "correct" units involves * nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, * 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined * in terms of tropical years of 365.2422 days, rather than the * usual Julian year of 365.25 days. Therefore, to avoid any * confusion, the Unit attribute is automatically cleared to "yr" when * a System value of BEPOCH System is selected, and an error is * reported if any attempt is subsequently made to change the Unit * attribute. * * Note that the default value for the ActiveUnit flag c is non-zero f is .TRUE. * for a TimeFrame, meaning that changes to the Unit attribute for * a TimeFrame will result in the TimeFrame being re-mapped within * its enclosing FrameSet in order to reflect the change in units c (see astSetActiveUnit function for further information). f (see AST_SETACTIVEUNIT routine for further information). * FluxFrame * The FluxFrame class supports the following System values and * associated systems for measuring observed value: * * - "FLXDN": Flux per unit frequency (W/m^2/Hz) * - "FLXDNW": Flux per unit wavelength (W/m^2/Angstrom) * - "SFCBR": Surface brightness in frequency units (W/m^2/Hz/arcmin**2) * - "SFCBRW": Surface brightness in wavelength units (W/m^2/Angstrom/arcmin**2) * * The above lists specified the default units for each System. If an * explicit value is set for the Unit attribute but no value is set * for System, then the default System value is determined by the Unit * string (if the units are not appropriate for describing any of the * supported Systems then an error will be reported when an attempt is * made to access the System value). If no value has been specified for * either Unit or System, then System=FLXDN and Unit=W/m^2/Hz are * used. *att-- */ /* Clear the System value by setting it to AST__BADSYSTEM. */ astMAKE_CLEAR(Frame,System,system,AST__BADSYSTEM) /* Provide a default coordinate system of AST__CART. */ astMAKE_GET(Frame,System,AstSystemType,AST__BADSYSTEM,( ( this->system == AST__BADSYSTEM ) ? AST__CART : this->system ) ) /* Validate the System value being set and retain the original if the supplied value is not recognized. */ astMAKE_SET(Frame,System,AstSystemType,system,( (astValidateSystem( this, value, "astSetSystem" ) != AST__BADSYSTEM) ? value : this->system )) /* The System value is set if it is not AST__BADSYSTEM. */ astMAKE_TEST(Frame,System,( this->system != AST__BADSYSTEM )) /* *att++ * Name: * Title * Purpose: * Frame title. * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute holds a string which is used as a title in (e.g.) * graphical output to describe the coordinate system which a Frame * represents. Examples might be "Detector Coordinates" or * "Galactic Coordinates". * * If a Title value has not been set for a Frame, then a suitable * default is supplied, depending on the class of the Frame. * Applicability: * Frame * The default supplied by the Frame class is "-d coordinate * system", where is the number of Frame axes (Naxes * attribute). * CmpFrame * The CmpFrame class re-defines the default Title value to be * "-d compound coordinate system", where is the number * of CmpFrame axes (Naxes attribute). * FrameSet * The Title attribute of a FrameSet is the same as that of its * current Frame (as specified by the Current attribute). * Notes: * - A Frame's Title is intended purely for interpretation by human * readers and not by software. *att-- */ /* Clear the Title value by freeing the allocated memory and assigning a NULL pointer. */ astMAKE_CLEAR(Frame,Title,title,astFree( this->title )) /* If the Title value is not set, write a default based on the number of Frame axes into the static "title_buff" buffer, and return a pointer to this buffer. */ astMAKE_GET(Frame,Title,const char *,NULL,( this->title ? this->title : GetDefaultTitle( this, status ) )) /* Set a Title value by freeing any previously allocated memory, allocating new memory, storing the string and saving the pointer to the copy. */ astMAKE_SET(Frame,Title,const char *,title,astStore( this->title, value, strlen( value ) + (size_t) 1 )) /* The Title value is set if the pointer to it is not NULL. */ astMAKE_TEST(Frame,Title,( this->title != NULL )) /* *att++ * Name: * ObsLat * Purpose: * The geodetic latitude of the observer * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the geodetic latitude of the observer, in * degrees, relative to the IAU 1976 reference ellipsoid. The basic Frame * class makes no use of this attribute, but specialised subclasses of * Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame * classes use it. The default value is zero. * * The value is stored internally in radians, but is converted to and * from a degrees string for access. Some example input formats are: * "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", * "-45.6", "S45.6". As indicated, the sign of the latitude can * optionally be indicated using characters "N" and "S" in place of the * usual "+" and "-". When converting the stored value to a string, the * format "[s]dd:mm:ss.ss" is used, when "[s]" is "N" or "S". * Applicability: * Frame * All Frames have this attribute. * SpecFrame * Together with the ObsLon, Epoch, RefRA and RefDec attributes, * it defines the Doppler shift introduced by the observers diurnal * motion around the earths axis, which is needed when converting to * or from the topocentric standard of rest. The maximum velocity * error which can be caused by an incorrect value is 0.5 km/s. The * default value for the attribute is zero. * TimeFrame * Together with the ObsLon attribute, it is used when converting * between certain time scales (TDB, TCB, LMST, LAST) *att-- */ /* The geodetic latitude of the observer (radians). Clear the ObsLat value by setting it to AST__BAD, returning zero as the default value. Any value is acceptable. */ astMAKE_CLEAR(Frame,ObsLat,obslat,AST__BAD) astMAKE_GET(Frame,ObsLat,double,0.0,((this->obslat!=AST__BAD)?this->obslat:0.0)) astMAKE_SET(Frame,ObsLat,double,obslat,value) astMAKE_TEST(Frame,ObsLat,(this->obslat!=AST__BAD)) /* *att++ * Name: * ObsAlt * Purpose: * The geodetic altitude of the observer * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the geodetic altitude of the observer, in * metres, relative to the IAU 1976 reference ellipsoid. The basic Frame * class makes no use of this attribute, but specialised subclasses of * Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame * classes use it. The default value is zero. * Applicability: * Frame * All Frames have this attribute. * SpecFrame * Together with the ObsLon, Epoch, RefRA and RefDec attributes, * it defines the Doppler shift introduced by the observers diurnal * motion around the earths axis, which is needed when converting to * or from the topocentric standard of rest. The maximum velocity * error which can be caused by an incorrect value is 0.5 km/s. The * default value for the attribute is zero. * TimeFrame * Together with the ObsLon attribute, it is used when converting * between certain time scales (TDB, TCB, LMST, LAST) *att-- */ /* The geodetic altitude of the observer (metres). Clear the ObsAlt value by setting it to AST__BAD, returning zero as the default value. Any value is acceptable. */ astMAKE_CLEAR(Frame,ObsAlt,obsalt,AST__BAD) astMAKE_GET(Frame,ObsAlt,double,0.0,((this->obsalt!=AST__BAD)?this->obsalt:0.0)) astMAKE_SET(Frame,ObsAlt,double,obsalt,value) astMAKE_TEST(Frame,ObsAlt,(this->obsalt!=AST__BAD)) /* *att++ * Name: * ObsLon * Purpose: * The geodetic longitude of the observer * Type: * Public attribute. * Synopsis: * String. * Description: * This attribute specifies the geodetic (or equivalently, geocentric) * longitude of the observer, in degrees, measured positive eastwards. * See also attribute ObsLat. The basic Frame class makes no use of this * attribute, but specialised subclasses of Frame may use it. For instance, * the SpecFrame, SkyFrame and TimeFrame classes use it. The default value * is zero. * * The value is stored internally in radians, but is converted to and * from a degrees string for access. Some example input formats are: * "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", * "-204.67689", "W204.67689". As indicated, the sign of the longitude can * optionally be indicated using characters "E" and "W" in place of the * usual "+" and "-". When converting the stored value to a string, the * format "[s]ddd:mm:ss.ss" is used, when "[s]" is "E" or "W" and the * numerical value is chosen to be less than 180 degrees. * Applicability: * Frame * All Frames have this attribute. * SpecFrame * Together with the ObsLon, Epoch, RefRA and RefDec attributes, * it defines the Doppler shift introduced by the observers diurnal * motion around the earths axis, which is needed when converting to * or from the topocentric standard of rest. The maximum velocity * error which can be caused by an incorrect value is 0.5 km/s. The * default value for the attribute is zero. * TimeFrame * Together with the ObsLon attribute, it is used when converting * between certain time scales (TDB, TCB, LMST, LAST) *att-- */ /* The geodetic longitude of the observer (radians). Clear the ObsLon value by setting it to AST__BAD, returning zero as the default value. Any value is acceptable. */ astMAKE_CLEAR(Frame,ObsLon,obslon,AST__BAD) astMAKE_GET(Frame,ObsLon,double,0.0,((this->obslon!=AST__BAD)?this->obslon:0.0)) astMAKE_SET(Frame,ObsLon,double,obslon,value) astMAKE_TEST(Frame,ObsLon,(this->obslon!=AST__BAD)) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Frame objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Frame objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstFrame *in; /* Pointer to input Frame */ AstFrame *out; /* Pointer to output Frame */ int axis; /* Loop counter for axes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Frames. */ in = (AstFrame *) objin; out = (AstFrame *) objout; /* For safety, first clear any references to the input memory from the output Frame. */ out->axis = NULL; out->domain = NULL; out->perm = NULL; out->title = NULL; out->variants = NULL; /* If necessary, allocate memory in the output Frame and store a copy of the input Title and Domain strings. */ if ( in->title ) out->title = astStore( NULL, in->title, strlen( in->title ) + (size_t) 1 ); if ( in->domain ) out->domain = astStore( NULL, in->domain, strlen( in->domain ) + (size_t) 1 ); /* Allocate memory to hold the output Frame's Axis object pointers and its axis permutation array. */ out->axis = astMalloc( sizeof( AstAxis * ) * (size_t) in->naxes ); out->perm = astMalloc( sizeof( int ) * (size_t) in->naxes ); /* Make a copy of each of the input Frame's Axis objects, storing the pointer to each new Axis in the memory just allocated. Also copy the axis permutation array. */ if ( astOK ) { for ( axis = 0; axis < in->naxes; axis++ ) { out->axis[ axis ] = astCopy( in->axis[ axis ] ); out->perm[ axis ] = in->perm[ axis ]; } /* If an error occurred while copying the Axis objects, then loop through the resulting array of pointers and make sure that all of them are properly annulled. */ if ( !astOK ) { for ( axis = 0; axis < in->naxes; axis++ ) { out->axis[ axis ] = astAnnul( out->axis[ axis ] ); } } } /* Other remaining objects */ if( in->variants ) out->variants = astCopy( in->variants ); /* If an error occurred, free any allocated memory. */ if ( !astOK ) { out->axis = astFree( out->axis ); out->domain = astFree( out->domain ); out->perm = astFree( out->perm ); out->title = astFree( out->title ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Frame objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Frame objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstFrame *this; /* Pointer to Frame */ int axis; /* Loop counter for Frame axes */ /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) obj; /* Free the memory used for the Title and Domain strings if necessary. */ this->title = astFree( this->title ); this->domain = astFree( this->domain ); /* If memory has been allocated to store pointers to the Frame's Axis objects, annul each of these pointers and then free the memory. */ if ( this->axis ) { for ( axis = 0; axis < this->naxes; axis++ ) { this->axis[ axis ] = astAnnul( this->axis[ axis ] ); } this->axis = astFree( this->axis ); } /* Free memory used for the axis permutation array if necessary. */ this->perm = astFree( this->perm ); /* Other objects. */ if( this->variants ) this->variants = astAnnul( this->variants ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Frame objects. * Type: * Private function. * Synopsis: * void Dump( AstObject *this, AstChannel *channel, int *status ) * Description: * This function implements the Dump function which writes out data * for the Frame class to an output Channel. * Parameters: * this * Pointer to the Frame whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ /* Local Constants: */ #define COMMENT_LEN 150 /* Maximum length of a comment string */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstAxis *ax; /* Pointer to Axis */ AstFrame *cfrm; /* Pointer to FrameSet's current Frame */ AstFrame *this; /* Pointer to the Frame structure */ AstSystemType system; /* System code */ char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment strings */ char key[ KEY_LEN + 1 ]; /* Buffer for keywords */ const char *sval; /* Pointer to string value */ const char *lab; /* Pointer to unit label */ const int *perm; /* Pointer to axis permutation array */ double dval; /* Double attibute value */ int *invperm; /* Pointer to inverse permutation array */ int axis; /* Loop counter for Frame axes */ int bessyr; /* Format as Besselian years (else Julian) */ int digits_set; /* Digits set explicitly for any axis? */ int full; /* Full attribute value */ int full_set; /* Full attribute set? */ int helpful; /* Helpful to show value even if not set? */ int isFrame; /* Is this a simple Frame? */ int ival; /* Integer value */ int naxes; /* Number of Frame axes */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Frame structure. */ this = (AstFrame *) this_object; /* Determine the number of Frame axes and a pointer to the Frame's axis permutation array (using methods, to allow for any over-ride by a derived class). */ naxes = astGetNaxes( this ); perm = astGetPerm( this ); /* Some default attribute values are not helpful for a simple Frame. Note if this is a simple Frame, or if it is a FrameSet with a simple Frame as its current Frame., or if it is a CmpFrame. */ if( !strcmp( astGetClass( this ), "Frame" ) ) { isFrame = 1; } else if( astIsAFrameSet( this ) ) { cfrm = astGetFrame( (AstFrameSet *) this, AST__CURRENT ); isFrame = !strcmp( astGetClass( cfrm ), "Frame" ); cfrm = astAnnul( cfrm ); } else if( astIsACmpFrame( this ) ) { isFrame = 1; } else { isFrame = 0; } /* Allocate memory to hold an inverse axis permutation array and generate this array from the forward permutation values. This will be used to determine which axis should be enquired about (using possibly over-ridden methods) to obtain data to correspond with a particular internal value (i.e. instance variable) relating to an axis. This step is needed so that the effect of any axis permutation can be un-done before values are written out, as output values are written by this function in un-permuted order. */ invperm = astMalloc( sizeof( int ) * (size_t) naxes ); if ( astOK ) { for ( axis = 0; axis < naxes; axis++ ) invperm[ perm[ axis ] ] = axis; /* Write out values representing the instance variables for the Frame class. Accompany these with appropriate comment strings, possibly depending on the values being written.*/ /* In the case of attributes, we first use the appropriate (private) Test... member function to see if they are set. If so, we then use the (private) Get... function to obtain the value to be written out. For attributes which are not set, we use the astGet... method to obtain the value instead. This will supply a default value (possibly provided by a derived class which over-rides this method) which is more useful to a human reader as it corresponds to the actual default attribute value. Since "set" will be zero, these values are for information only and will not be read back. */ /* Title. */ /* ------ */ set = TestTitle( this, status ); sval = set ? GetTitle( this, status ) : astGetTitle( this ); astWriteString( channel, "Title", set, 1, sval, "Title of coordinate system" ); /* Naxes. */ /* ------ */ set = ( this->naxes != 0 ); ival = set ? this->naxes : naxes; astWriteInt( channel, "Naxes", set, 1, ival, "Number of coordinate axes" ); /* Domain. */ /* ------- */ set = TestDomain( this, status ); sval = set ? GetDomain( this, status ) : astGetDomain( this ); /* Don't show an un-set Domain value if it is blank. */ helpful = ( sval && *sval ); astWriteString( channel, "Domain", set, helpful, sval, "Coordinate system domain" ); /* Epoch. */ /* ------ */ set = TestEpoch( this, status ); dval = set ? GetEpoch( this, status ) : astGetEpoch( this ); /* Convert MJD to Besselian or Julian years, depending on the value. */ bessyr = ( dval < palEpj2d( 1984.0 ) ); dval = bessyr ? palEpb( dval ) : palEpj( dval ); astWriteDouble( channel, "Epoch", set, !isFrame, dval, bessyr ? "Besselian epoch of observation" : "Julian epoch of observation" ); /* Label. */ /* ------ */ /* This, and some other, attributes are stored internally by the Frame's Axis objects, but are "re-packaged" by the Frame class to appear as Frame attributes. We treat them here like Frame attributes that are "un-set". There is a Label value for each Frame axis. */ for ( axis = 0; axis < naxes; axis++ ) { /* The inverse axis permutation array is used to obtain the axis index for astGetLabel. This reverses the effect of the Frame's axis permutation array and yields a default value appropriate to the axis with internal index "axis". */ sval = astGetLabel( this, invperm[ axis ] ); /* Create keyword and comment strings appropriate to each axis (converting to 1-based axis numbering) and write out the Label values. */ (void) sprintf( key, "Lbl%d", axis + 1 ); (void) sprintf( comment, "Label for axis %d", axis + 1 ); astWriteString( channel, key, 0, 1, sval, comment ); } /* Symbol. */ /* ------- */ /* There is a Symbol value for each Frame axis. These are handled in the same way as the Label values. */ for ( axis = 0; axis < naxes; axis++ ) { sval = astGetSymbol( this, invperm[ axis ] ); (void) sprintf( key, "Sym%d", axis + 1 ); (void) sprintf( comment, "Symbol for axis %d", axis + 1 ); astWriteString( channel, key, 0, 0, sval, comment ); } /* System. */ /* ------- */ set = TestSystem( this, status ); system = set ? GetSystem( this, status ) : astGetSystem( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = astSystemString( this, system ); /* Report an error if the System value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "astWrite(%s): Corrupt %s contains invalid " "System identification code (%d).", status, astGetClass( channel ), astGetClass( this ), (int) system ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "system" ); } /* Write out the value. */ astWriteString( channel, "System", set, !isFrame, sval, "Coordinate system type" ); /* AlignSystem. */ /* ------------ */ set = TestAlignSystem( this, status ); system = set ? GetAlignSystem( this, status ) : astGetAlignSystem( this ); /* If set, convert explicitly to a string for the external representation. */ if ( set ) { if ( astOK ) { sval = astSystemString( this, system ); /* Report an error if the AlignSystem value was not recognised. */ if ( !sval ) { astError( AST__SCSIN, "astWrite(%s): Corrupt %s contains invalid " "AlignSystem identification code (%d).", status, astGetClass( channel ), astGetClass( this ), (int) system ); } } /* If not set, use astGetAttrib which returns a string value using (possibly over-ridden) methods. */ } else { sval = astGetAttrib( this_object, "alignsystem" ); } /* Write out the value. */ astWriteString( channel, "AlSys", set, 0, sval, "Alignment coordinate system" ); /* Unit. */ /* ----- */ /* There is a Unit value for each axis. */ for ( axis = 0; axis < naxes; axis++ ) { sval = astGetUnit( this, invperm[ axis ] ); /* Get any label associated with the unit string. */ lab = astUnitLabel( sval ); /* Construct a comment including the above label (but only if it is not the same as the unit string) . */ if( lab && strcmp( lab, sval ) ) { (void) sprintf( comment, "Units for axis %d (%s)", axis + 1, lab ); } else { (void) sprintf( comment, "Units for axis %d", axis + 1 ); } /* Show the Unit value if it is not blank. */ helpful = ( sval && *sval ); (void) sprintf( key, "Uni%d", axis + 1 ); astWriteString( channel, key, 0, helpful, sval, comment ); } /* Digits. */ /* ------- */ /* There is a Digits value for each axis... */ digits_set = 0; for ( axis = 0; axis < naxes; axis++ ) { /* Obtain the axis Digits value, using the Frame's Digits value as a default. */ ax = astGetAxis( this, invperm[ axis ] ); set = astTestAxisDigits( ax ); ival = set ? astGetAxisDigits( ax ) : astGetDigits( this ); ax = astAnnul( ax ); /* Show the value if it is set for the axis (i.e. if it differs from the default for the whole Frame) and note if any such value is set. */ helpful = set; if ( set ) digits_set = 1; (void) sprintf( key, "Dig%d", axis + 1 ); (void) sprintf( comment, "Individual precision for axis %d", axis + 1 ); astWriteInt( channel, key, 0, helpful, ival, comment ); } /* There is also a Digits value for the Frame as a whole... */ set = TestDigits( this, status ); /* Show the value (even if not set) if an explicit Digits value has been set for any axis (above). */ helpful = digits_set; ival = set ? GetDigits( this, status ) : astGetDigits( this ); astWriteInt( channel, "Digits", set, helpful, ival, "Default formatting precision" ); /* Format. */ /* ------- */ /* There is a Format value for each axis. */ for ( axis = 0; axis < naxes; axis++ ) { sval = astGetFormat( this, invperm[ axis ] ); /* Show the Format value if the Digits value is set for an individual axis. */ ax = astGetAxis( this, invperm[ axis ] ); helpful = astTestAxisDigits( ax ); ax = astAnnul( ax ); (void) sprintf( key, "Fmt%d", axis + 1 ); (void) sprintf( comment, "Format specifier for axis %d", axis + 1 ); astWriteString( channel, key, 0, helpful, sval, comment ); } /* Direction. */ /* ---------- */ /* There is a Direction value for each axis. */ for ( axis = 0; axis < naxes; axis++ ) { ival = astGetDirection( this, invperm[ axis ] ); /* Show the value if it is zero. */ helpful = ( ival == 0 ); (void) sprintf( key, "Dir%d", axis + 1 ); (void) sprintf( comment, ival ? "Plot axis %d in conventional direction" : "Plot axis %d in reverse direction", axis + 1 ); astWriteInt( channel, key, 0, helpful, ival, comment ); } /* Bottom. */ /* ------- */ /* There is a Bottom value for each axis. */ for ( axis = 0; axis < naxes; axis++ ) { dval = astGetBottom( this, invperm[ axis ] ); /* Show the value if it is zero. */ helpful = ( dval != -DBL_MAX ); (void) sprintf( key, "Bot%d", axis + 1 ); astWriteDouble( channel, key, 0, helpful, dval, "Lowest legal axis value"); } /* Top. */ /* ------- */ /* There is a Top value for each axis. */ for ( axis = 0; axis < naxes; axis++ ) { dval = astGetTop( this, invperm[ axis ] ); /* Show the value if it is zero. */ helpful = ( dval != DBL_MAX ); (void) sprintf( key, "Top%d", axis + 1 ); astWriteDouble( channel, key, 0, helpful, dval, "Highest legal axis value"); } /* PreserveAxes. */ /* ------------- */ set = TestPreserveAxes( this, status ); ival = set ? GetPreserveAxes( this, status ) : astGetPreserveAxes( this ); astWriteInt( channel, "Presrv", set, 0, ival, ival ? "Preserve target axes" : "Don't preserve target axes" ); /* Permute. */ /* -------- */ set = TestPermute( this, status ); ival = set ? GetPermute( this, status ) : astGetPermute( this ); astWriteInt( channel, "Permut", set, 0, ival, ival ? "Axes may be permuted to match" : "Axes may not be permuted match" ); /* MinAxes. */ /* -------- */ set = TestMinAxes( this, status ); ival = set ? GetMinAxes( this, status ) : astGetMinAxes( this ); astWriteInt( channel, "MinAx", set, 0, ival, "Minimum number of axes to match" ); /* MaxAxes. */ /* -------- */ set = TestMaxAxes( this, status ); ival = set ? GetMaxAxes( this, status ) : astGetMaxAxes( this ); astWriteInt( channel, "MaxAx", set, 0, ival, "Maximum number of axes to match" ); /* MatchEnd. */ /* --------- */ set = TestMatchEnd( this, status ); ival = set ? GetMatchEnd( this, status ) : astGetMatchEnd( this ); astWriteInt( channel, "MchEnd", set, 0, ival, ival ? "Match final target axes" : "Match initial target axes" ); /* ObsLat. */ /* ------- */ set = TestObsLat( this, status ); dval = set ? GetObsLat( this, status ) : astGetObsLat( this ); astWriteDouble( channel, "ObsLat", set, 0, dval, "Observers geodetic latitude (rads)" ); /* ObsLon. */ /* ------- */ set = TestObsLon( this, status ); dval = set ? GetObsLon( this, status ) : astGetObsLon( this ); astWriteDouble( channel, "ObsLon", set, 0, dval, "Observers geodetic longitude (rads)" ); /* ObsAlt. */ /* ------- */ set = TestObsAlt( this, status ); dval = set ? GetObsAlt( this, status ) : astGetObsAlt( this ); astWriteDouble( channel, "ObsAlt", set, 0, dval, "Observers geodetic altitude (metres)" ); /* Dut1*/ /* ---- */ set = TestDut1( this, status ); dval = set ? GetDut1( this, status ) : astGetDut1( this ); astWriteDouble( channel, "Dut1", set, 0, dval, "UT1-UTC in seconds" ); /* ActiveUnit. */ /* ----------- */ if( astTestActiveUnit( this ) ) { ival = astGetActiveUnit( this ); astWriteInt( channel, "ActUnt", 1, 0, ival, ival ? "Unit strings affects alignment" : "Unit strings do not affect alignment" ); } /* Axis permutation array. */ /* ----------------------- */ /* Write out the axis permutation array value for each axis, converting to 1-based axis numbering. */ for ( axis = 0; axis < this->naxes; axis++ ) { set = ( this->perm[ axis ] != axis ); ival = this->perm[ axis ] + 1; /* Create a keyword and comment appropriate to the axis. */ (void) sprintf( key, "Prm%d", axis + 1 ); if ( set ) { (void) sprintf( comment, "Axis %d permuted to use internal axis %d", axis + 1, ival ); } else { (void) sprintf( comment, "Axis %d not permuted", axis + 1 ); } astWriteInt( channel, key, set, 0, ival, comment ); } /* Axis Objects. */ /* ------------- */ /* Temporarily set the Channel's Full attribute to -1 (unless it is +1 to start with), remembering the original setting. This prevents any unnecessary "un-set" Axis values being output that would otherwise simply duplicate the Frame's attributes which have already been written. "Set" Axis values are still written, however (and all values are written if Full is set to 1). */ full_set = astTestFull( channel ); full = astGetFull( channel ); if ( full <= 0 ) astSetFull( channel, -1 ); /* Handle each axis in turn. */ for ( axis = 0; axis < this->naxes; axis++ ) { /* Create a keyword and comment appropriate to the axis (converting to 1-based axis numbering). */ (void) sprintf( key, "Ax%d", axis + 1 ); (void) sprintf( comment, "Axis number %d", axis + 1 ); /* Write out the axis Object description. */ astWriteObject( channel, key, 1, 0, this->axis[ axis ], comment ); } /* Restore the Channel's original Full attribute setting. */ if ( full_set ) { astSetFull( channel, full ); } else { astClearFull( channel ); } /* Free the inverse axis permutation array. */ invperm = astFree( invperm ); /* Variants */ /* ------- */ if( this->variants ) astWriteObject( channel, "Vrnts", 1, 0, this->variants, "Variant Frames" ); } /* Undefine macros local to this function. */ #undef COMMENT_LEN #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAFrame and astCheckFrame functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Frame,Mapping) astMAKE_CHECK(Frame) AstFrame *astFrame_( int naxes, const char *options, int *status, ...) { /* *+ * Name: * astFrame * Purpose: * Create a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * AstFrame *astFrame( int naxes, const char *options, int *status, ... ) * Class Membership: * Frame constructor. * Description: * This function creates a new Frame and optionally initialises its * attributes. * Parameters: * naxes * The number of Frame axes. * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new Frame. The syntax used is the same as * for the astSet method and may include "printf" format * specifiers identified by "%" symbols in the normal way. * status * Pointer to the inherited status variable. * ... * If the "options" string contains "%" format specifiers, then * an optional list of arguments may follow it in order to * supply values to be substituted for these specifiers. The * rules for supplying these are identical to those for the * astSet method (and for the C "printf" function). * Returned Value: * A pointer to the new Frame. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- * Implementation Notes: * - This function implements the basic Frame constructor which is * available via the protected interface to the Frame class. A * public interface is provided by the astFrameId_ function. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *new; /* Pointer to new Frame */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the Frame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitFrame( NULL, sizeof( AstFrame ), !class_init, &class_vtab, "Frame", naxes ); /* If successful, note that the virtual function table has been initialised. */ if ( astOK ) { class_init = 1; /* Obtain the variable argument list and pass it along with the options string to the astVSet method to initialise the new Frame's attributes. */ va_start( args, status ); astVSet( new, options, NULL, args ); va_end( args ); /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new Frame. */ return new; } AstFrame *astInitFrame_( void *mem, size_t size, int init, AstFrameVtab *vtab, const char *name, int naxes, int *status ) { /* *+ * Name: * astInitFrame * Purpose: * Initialise a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * AstFrame *astInitFrame( void *mem, size_t size, int init, * AstFrameVtab *vtab, const char *name, * int naxes ) * Class Membership: * Frame initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Frame object. It allocates memory (if necessary) to accommodate * the Frame plus any additional data associated with the derived class. * It then initialises a Frame structure at the start of this memory. If * the "init" flag is set, it also initialises the contents of a virtual * function table for a Frame at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Frame is to be created. This * must be of sufficient size to accommodate the Frame data * (sizeof(Frame)) plus any data used by the derived class. If a value * of NULL is given, this function will allocate the memory itself using * the "size" parameter to determine its size. * size * The amount of memory used by the Frame (plus derived class data). * This will be used to allocate memory if a value of NULL is given for * the "mem" parameter. This value is also stored in the Frame * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Frame's virtual function table is * to be initialised. If this value is non-zero, the virtual function * table will be initialised by this function. * vtab * Pointer to the start of the virtual function table to be associated * with the new Frame. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the new object belongs (it is this * pointer value that will subsequently be returned by the astGetClass * method). * naxes * The number of Frame axes. * Returned Value: * A pointer to the new Frame. * Notes: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. *- */ /* Local Variables: */ AstFrame *new; /* Pointer to new Frame */ int axis; /* Loop counter for Frame axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitFrameVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the number of axes for validity, reporting an error if necessary. */ if ( naxes < 0 ) { astError( AST__NAXIN, "astInitFrame(%s): Number of axes (%d) is " "invalid - this number should not be negative.", status, name, naxes ); /* Initialise a Mapping structure (the parent class) as the first component within the Frame structure, allocating memory if necessary. Set the number of input/output coordinates to zero (the astGetNin and astGetNout methods are over-ridden by the Frame class to provide values for these that are equal to the number of Frame axes). */ } else { new = (AstFrame *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, 0, 0, 1, 1 ); if ( astOK ) { /* Initialise the Frame data. */ /* ----------------------------- */ /* Set the number of Frame axes. */ new->naxes = naxes; /* Initialise all attributes to their "undefined" values. */ new->digits = -INT_MAX; new->domain = NULL; new->epoch = AST__BAD; new->match_end = -INT_MAX; new->max_axes = -INT_MAX; new->min_axes = -INT_MAX; new->permute = -INT_MAX; new->preserve_axes = -INT_MAX; new->title = NULL; new->system = AST__BADSYSTEM; new->alignsystem = AST__BADSYSTEM; new->active_unit = -INT_MAX; new->obsalt = AST__BAD; new->obslat = AST__BAD; new->obslon = AST__BAD; new->dut1 = AST__BAD; new->flags = 0; new->variants = NULL; /* Allocate memory to store pointers to the Frame's Axis objects and to store its axis permutation array. */ new->axis = astMalloc( sizeof( AstAxis * ) * (size_t) naxes ); new->perm = astMalloc( sizeof( int ) * (size_t) naxes ); /* Create a new Axis object to describe each axis of the Frame and store the resulting pointers in the memory allocated above. Also initialise the axis permutation array so that the axes appear in their natural order. */ if ( astOK ) { for ( axis = 0; axis < naxes; axis++ ) { new->axis[ axis ] = astAxis( "", status ); new->perm[ axis ] = axis; } /* If an error occurred while creating the Axis objects, scan through the array of pointers to them again to ensure that they are all correctly annulled. */ if ( !astOK ) { for ( axis = 0; axis < naxes; axis++ ) { new->axis[ axis ] = astAnnul( new->axis[ axis ] ); } } } /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } } /* Return a pointer to the new object. */ return new; } AstFrame *astLoadFrame_( void *mem, size_t size, AstFrameVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadFrame * Purpose: * Load a Frame. * Type: * Protected function. * Synopsis: * #include "frame.h" * AstFrame *astLoadFrame( void *mem, size_t size, * AstFrameVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * Frame loader. * Description: * This function is provided to load a new Frame using data read * from a Channel. It first loads the data used by the parent class * (which allocates memory if necessary) and then initialises a * Frame structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Frame at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Frame is to be loaded. * This must be of sufficient size to accommodate the Frame data * (sizeof(Frame)) plus any data used by derived classes. If a * value of NULL is given, this function will allocate the * memory itself using the "size" parameter to determine its * size. * size * The amount of memory used by the Frame (plus derived class * data). This will be used to allocate memory if a value of * NULL is given for the "mem" parameter. This value is also * stored in the Frame structure, so a valid value must be * supplied even if not required for allocating memory. * * If the "vtab" parameter is NULL, the "size" value is ignored * and sizeof(AstFrame) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Frame. If this is NULL, a pointer to * the (static) virtual function table for the Frame class is * used instead. * name * Pointer to a constant null-terminated character string which * contains the name of the class to which the new object * belongs (it is this pointer value that will subsequently be * returned by the astGetClass method). * * If the "vtab" parameter is NULL, the "name" value is ignored * and a pointer to the string "Frame" is used instead. * Returned Value: * A pointer to the new Frame. * Notes: * - A null pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Constants: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstFrame *new; /* Pointer to the new Frame */ char *sval; /* Pointer to string value */ char key[ KEY_LEN + 1 ]; /* Buffer for keywords */ double dval; /* DOuble attribute value */ int axis; /* Loop counter for axes */ int ival; /* Integer value */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Frame. In this case the Frame belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstFrame ); vtab = &class_vtab; name = "Frame"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitFrameVtab( vtab, name ); class_init = 1; } } /* Invoke the parent class loader to load data for all the ancestral classes of the current one, returning a pointer to the resulting partly-built Frame. */ new = astLoadMapping( mem, size, (AstMappingVtab *) vtab, name, channel ); if ( astOK ) { /* Assign values for transient components that are not included in the Frame dump */ new->flags = 0; /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "Frame" ); /* Now read each individual data item from this list and use it to initialise the appropriate instance variable(s) for this class. */ /* In the case of attributes, we first read the "raw" input value, supplying the "unset" value as the default. If a "set" value is obtained, we then use the appropriate (private) Set... member function to validate and set the value properly. */ /* Naxes. */ /* ------ */ /* Obtain the number of Frame axes and allocate memory for the arrays which hold axis information. */ new->naxes = astReadInt( channel, "naxes", 0 ); if ( new->naxes < 0 ) new->naxes = 0; new->perm = astMalloc( sizeof( int ) * (size_t) new->naxes ); new->axis = astMalloc( sizeof( AstAxis * ) * (size_t) new->naxes ); /* If an error occurred, ensure that any allocated memory is freed. */ if ( !astOK ) { new->perm = astFree( new->perm ); new->axis = astFree( new->axis ); /* Otherwise, initialise the array of Axis pointers. */ } else { for ( axis = 0; axis < new->naxes; axis++ ) new->axis[ axis ] = NULL; /* Now obtain those input values which are required for each axis... */ for ( axis = 0; axis < new->naxes; axis++ ) { /* Axis object. */ /* ------------ */ /* This must be read first, so that it can hold the other axis values obtained below. */ /* Create a keyword appropriate to this axis. */ (void) sprintf( key, "ax%d", axis + 1 ); /* Read the Axis object. If none was read, provide a default Axis instead. */ new->axis[ axis ] = astReadObject( channel, key, NULL ); if ( !new->axis[ axis ] ) new->axis[ axis ] = astAxis( "", status ); /* Label. */ /* ------ */ /* Read the Label string for each axis. If a value is obtained, use it to set the Label attribute for the axis. Free the memory holding the string when no longer needed. */ (void) sprintf( key, "lbl%d", axis + 1 ); sval = astReadString( channel, key, NULL ); if ( sval ) { astSetAxisLabel( new->axis[ axis ], sval ); sval = astFree( sval ); } /* Symbol. */ /* ------- */ (void) sprintf( key, "sym%d", axis + 1 ); sval = astReadString( channel, key, NULL ); if ( sval ) { astSetAxisSymbol( new->axis[ axis ], sval ); sval = astFree( sval ); } /* Format. */ /* ------- */ (void) sprintf( key, "fmt%d", axis + 1 ); sval = astReadString( channel, key, NULL ); if ( sval ) { astSetAxisFormat( new->axis[ axis ], sval ); sval = astFree( sval ); } /* Unit. */ /* ----- */ (void) sprintf( key, "uni%d", axis + 1 ); sval = astReadString( channel, key, NULL ); if ( sval ) { astSetAxisUnit( new->axis[ axis ], sval ); sval = astFree( sval ); } /* Direction. */ /* ---------- */ (void) sprintf( key, "dir%d", axis + 1 ); ival = astReadInt( channel, key, -INT_MAX ); if ( ival != -INT_MAX ) { astSetAxisDirection( new->axis[ axis ], ival ); } /* Top. */ /*----- */ (void) sprintf( key, "top%d", axis + 1 ); dval = astReadDouble( channel, key, AST__BAD ); if ( dval != AST__BAD ) { astSetAxisTop( new->axis[ axis ], dval ); } /* Bottom. */ /*----- -- */ (void) sprintf( key, "bot%d", axis + 1 ); dval = astReadDouble( channel, key, AST__BAD ); if ( dval != AST__BAD ) { astSetAxisBottom( new->axis[ axis ], dval ); } /* Digits. */ /* ------- */ (void) sprintf( key, "dig%d", axis + 1 ); ival = astReadInt( channel, key, -INT_MAX ); if ( ival != -INT_MAX ) { astSetAxisDigits( new->axis[ axis ], ival ); } /* Axis permutation array. */ /* ----------------------- */ /* Convert from 1-based to zero-based axis numbering at this point. The default is the "un-permuted" value. */ sprintf( key, "prm%d", axis + 1 ); new->perm[ axis ] = astReadInt( channel, key, axis + 1 ) - 1; /* Quit looping if an error occurs. */ if ( !astOK ) break; } /* The remaining values are not associated with particular axes... */ /* Title. */ /* ------ */ new->title = astReadString( channel, "title", NULL ); /* Domain. */ /* ------- */ new->domain = astReadString( channel, "domain", NULL ); /* Epoch. */ /* ------ */ /* Interpret this as Besselian or Julian depending on its value. */ new->epoch = astReadDouble( channel, "epoch", AST__BAD ); if ( TestEpoch( new, status ) ) { SetEpoch( new, ( new->epoch < 1984.0 ) ? palEpb2d( new->epoch ) : palEpj2d( new->epoch ), status ); } /* Digits. */ /* ------- */ /* This is the value that applies to the Frame as a whole. */ new->digits = astReadInt( channel, "digits", -INT_MAX ); if ( TestDigits( new, status ) ) SetDigits( new, new->digits, status ); /* PreserveAxes. */ /* ------------- */ new->preserve_axes = astReadInt( channel, "presrv", -INT_MAX ); if ( TestPreserveAxes( new, status ) ) { SetPreserveAxes( new, new->preserve_axes, status ); } /* Permute. */ /* -------- */ new->permute = astReadInt( channel, "permut", -INT_MAX ); if ( TestPermute( new, status ) ) SetPermute( new, new->permute, status ); /* MinAxes. */ /* -------- */ new->min_axes = astReadInt( channel, "minax", -INT_MAX ); if ( TestMinAxes( new, status ) ) SetMinAxes( new, new->min_axes, status ); /* MaxAxes. */ /* -------- */ new->max_axes = astReadInt( channel, "maxax", -INT_MAX ); if ( TestMaxAxes( new, status ) ) SetMaxAxes( new, new->max_axes, status ); /* MatchEnd. */ /* --------- */ new->match_end = astReadInt( channel, "mchend", -INT_MAX ); if ( TestMatchEnd( new, status ) ) SetMatchEnd( new, new->match_end, status ); /* ObsLat. */ /* ------- */ new->obslat = astReadDouble( channel, "obslat", AST__BAD ); if ( TestObsLat( new, status ) ) SetObsLat( new, new->obslat, status ); /* ObsLon. */ /* ------- */ new->obslon = astReadDouble( channel, "obslon", AST__BAD ); if ( TestObsLon( new, status ) ) SetObsLon( new, new->obslon, status ); /* ObsAlt. */ /* ------- */ new->obsalt = astReadDouble( channel, "obsalt", AST__BAD ); if ( TestObsAlt( new, status ) ) SetObsAlt( new, new->obsalt, status ); /* Dut1. */ /* ---- */ new->dut1 = astReadDouble( channel, "dut1", AST__BAD ); if ( TestDut1( new, status ) ) SetDut1( new, new->dut1, status ); /* ActiveUnit. */ /* ----------- */ new->active_unit = astReadInt( channel, "actunt", -INT_MAX ); if ( TestActiveUnit( new, status ) ) SetActiveUnit( new, new->active_unit, status ); /* System. */ /* ------- */ /* Set the default and read the external representation as a string. */ new->system = AST__BADSYSTEM; sval = astReadString( channel, "system", NULL ); /* If a value was read, convert from a string to a System code. */ if ( sval ) { if ( astOK ) { new->system = astSystemCode( new, sval ); /* Report an error if the value wasn't recognised. */ if ( new->system == AST__BADSYSTEM ) { astError( AST__ATTIN, "astRead(%s): Invalid System description " "\"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* AlignSystem. */ /* ------------ */ /* Set the default and read the external representation as a string. */ new->alignsystem = AST__BADSYSTEM; sval = astReadString( channel, "alsys", NULL ); /* If a value was read, convert from a string to a System code. */ if ( sval ) { if ( astOK ) { new->alignsystem = astSystemCode( new, sval ); /* Report an error if the value wasn't recognised. */ if ( new->alignsystem == AST__BADSYSTEM ) { astError( AST__ATTIN, "astRead(%s): Invalid AlignSystem description " "\"%s\".", status, astGetClass( channel ), sval ); } } /* Free the string value. */ sval = astFree( sval ); } /* Variants. */ /* -------- */ new->variants = astReadObject( channel, "vrnts", NULL ); } /* If an error occurred, clean up by deleting the new Frame. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Frame pointer. */ return new; /* Undefine macros local to this function. */ #undef KEY_LEN } /* Virtual function interfaces. */ /* ============================ */ /* These provide the external interface to the virtual functions defined by this class. Each simply checks the global error status and then locates and executes the appropriate member function, using the function pointer stored in the object's virtual function table (this pointer is located using the astMEMBER macro defined in "object.h"). Note that the member function may not be the one defined here, as it may have been over-ridden by a derived class. However, it should still have the same interface. */ const char *astAbbrev_( AstFrame *this, int axis, const char *fmt, const char *str1, const char *str2, int *status ) { if ( !astOK ) return str2; return (**astMEMBER(this,Frame,Abbrev))( this, axis, fmt, str1, str2, status ); } int astFields_( AstFrame *this, int axis, const char *fmt, const char *str, int maxfld, char **fields, int *nc, double *val, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,Fields))( this, axis, fmt, str, maxfld, fields, nc, val, status ); } void astCheckPerm_( AstFrame *this, const int *perm, const char *method, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,CheckPerm))( this, perm, method, status ); } AstPointSet *astResolvePoints_( AstFrame *this, const double point1[], const double point2[], AstPointSet *in, AstPointSet *out, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,ResolvePoints))( this, point1, point2, in, out, status ); } AstLineDef *astLineDef_( AstFrame *this, const double start[2], const double end[2], int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,LineDef))( this, start, end, status ); } int astLineCrossing_( AstFrame *this, AstLineDef *l1, AstLineDef *l2, double **cross, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,LineCrossing))( this, l1, l2, cross, status ); } void astLineOffset_( AstFrame *this, AstLineDef *line, double par, double prp, double point[2], int *status ){ if ( !astOK ) return; (**astMEMBER(this,Frame,LineOffset))( this, line, par, prp, point, status ); } int astLineContains_( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,LineContains))( this, l, def, point, status ); } AstFrameSet *astConvert_( AstFrame *from, AstFrame *to, const char *domainlist, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(from,Frame,Convert))( from, to, domainlist, status ); } AstFrameSet *astConvertX_( AstFrame *to, AstFrame *from, const char *domainlist, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(to,Frame,ConvertX))( to, from, domainlist, status ); } double astAngle_( AstFrame *this, const double a[], const double b[], const double c[], int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,Angle))( this, a, b, c, status ); } int astGetActiveUnit_( AstFrame *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,GetActiveUnit))( this, status ); } int astTestActiveUnit_( AstFrame *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,TestActiveUnit))( this, status ); } void astSetActiveUnit_( AstFrame *this, int value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,SetActiveUnit))( this, value, status ); } double astDistance_( AstFrame *this, const double point1[], const double point2[], int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,Distance))( this, point1, point2, status ); } AstFrameSet *astFindFrame_( AstFrame *target, AstFrame *template, const char *domainlist, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(target,Frame,FindFrame))( target, template, domainlist, status ); } void astMatchAxes_( AstFrame *frm1, AstFrame *frm2, int *axes, int *status ) { if ( !astOK ) return; (**astMEMBER(frm1,Frame,MatchAxes))( frm1, frm2, axes, status ); } void astMatchAxesX_( AstFrame *frm2, AstFrame *frm1, int *axes, int *status ) { if ( !astOK ) return; (**astMEMBER(frm2,Frame,MatchAxesX))( frm2, frm1, axes, status ); } const char *astFormat_( AstFrame *this, int axis, double value, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,Format))( this, axis, value, status ); } double astCentre_( AstFrame *this, int axis, double value, double gap, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,Frame,Centre))( this, axis, value, gap, status ); } double astGap_( AstFrame *this, int axis, double gap, int *ntick, int *status ) { if ( !astOK ) return 0.0; return (**astMEMBER(this,Frame,Gap))( this, axis, gap, ntick, status ); } AstAxis *astGetAxis_( AstFrame *this, int axis, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,GetAxis))( this, axis, status ); } int astGetNaxes_( AstFrame *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,GetNaxes))( this, status ); } const int *astGetPerm_( AstFrame *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,GetPerm))( this, status ); } AstFrameSet *astGetFrameVariants_( AstFrame *this, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,GetFrameVariants))( this, status ); } void astSetFrameVariants_( AstFrame *this, AstFrameSet *variants, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,SetFrameVariants))( this, variants, status ); } int astMatch_( AstFrame *this, AstFrame *target, int matchsub, int **template_axes, int **target_axes, AstMapping **map, AstFrame **result, int *status ) { AstFrame *super_this; const char *dom; int match; if ( !astOK ) return 0; match = (**astMEMBER(this,Frame,Match))( this, target, matchsub, template_axes, target_axes, map, result, status ); /* If the template ("this") could not be used to probe the target, it may be because the template class is a more specialised form of the target class. E.g. a SkyFrame cannot directly be used to probe a Frame, but a Frame *can* be used to probe a SkyFrame. This means (for instance), that a basic Frame with Domain FRED cannot be aligned (using astConvert) with a CmpFrame with Domain FRED. This sort of alignment is often useful, so we try now to use the supplied template to probe a modified form of the target that has been cast into the same class as the template. This is only possible if the template class is a sub-class of the target class. Attempt to do the cast. */ if( ! match && matchsub ) { super_this = (AstFrame *) astCast( this, target ); /* If the cast was possible, fix the template Domain since the parent class may provide a different default Domain, and then invoke the Match method appropriate to the new template class (i.e. the target class). */ if( super_this ) { if( astTestDomain( target ) ) { dom = astGetDomain( this ); if( astChrLen( dom ) > 0 ) astSetDomain( super_this, dom ); } match = (**astMEMBER(super_this,Frame,Match))( super_this, target, matchsub, template_axes, target_axes, map, result, status ); super_this = astAnnul( super_this ); } } return match; } int astIsUnitFrame_( AstFrame *this, int *status ){ if ( !astOK ) return 0; return (**astMEMBER(this,Frame,IsUnitFrame))( this, status ); } void astNorm_( AstFrame *this, double value[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,Norm))( this, value, status ); } void astNormBox_( AstFrame *this, double lbnd[], double ubnd[], AstMapping *reg, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,NormBox))( this, lbnd, ubnd, reg, status ); } double astAxDistance_( AstFrame *this, int axis, double v1, double v2, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,AxDistance))( this, axis, v1, v2, status ); } void astAxNorm_( AstFrame *this, int axis, int oper, int nval, double *values, int *status ){ if ( !astOK ) return; return (**astMEMBER(this,Frame,AxNorm))( this, axis, oper, nval, values, status ); } double astAxOffset_( AstFrame *this, int axis, double v1, double dist, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,AxOffset))( this, axis, v1, dist, status ); } AstPointSet *astFrameGrid_( AstFrame *this, int size, const double *lbnd, const double *ubnd, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,FrameGrid))( this, size, lbnd, ubnd, status ); } void astOffset_( AstFrame *this, const double point1[], const double point2[], double offset, double point3[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,Offset))( this, point1, point2, offset, point3, status ); } double astAxAngle_( AstFrame *this, const double a[2], const double b[2], int axis, int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,AxAngle))( this, a, b, axis, status ); } double astOffset2_( AstFrame *this, const double point1[2], double angle, double offset, double point2[2], int *status ) { if ( !astOK ) return AST__BAD; return (**astMEMBER(this,Frame,Offset2))( this, point1, angle, offset, point2, status ); } void astIntersect_( AstFrame *this, const double a1[2], const double a2[2], const double b1[2], const double b2[2], double cross[2], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,Intersect))( this, a1, a2, b1, b2, cross, status ); } void astOverlay_( AstFrame *template, const int *template_axes, AstFrame *result, int *status ) { if ( !astOK ) return; (**astMEMBER(template,Frame,Overlay))( template, template_axes, result, status ); } void astPermAxes_( AstFrame *this, const int perm[], int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,PermAxes))( this, perm, status ); } AstFrame *astPickAxes_( AstFrame *this, int naxes, const int axes[], AstMapping **map, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,PickAxes))( this, naxes, axes, map, status ); } void astPrimaryFrame_( AstFrame *this, int axis1, AstFrame **frame, int *axis2, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,PrimaryFrame))( this, axis1, frame, axis2, status ); } void astResolve_( AstFrame *this, const double point1[], const double point2[], const double point3[], double point4[], double *d1, double *d2, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,Resolve))( this, point1, point2, point3, point4, d1, d2, status ); } void astSetAxis_( AstFrame *this, int axis, AstAxis *newaxis, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,SetAxis))( this, axis, newaxis, status ); } void astSetUnit_( AstFrame *this, int axis, const char *value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,SetUnit))( this, axis, value, status ); } void astClearUnit_( AstFrame *this, int axis, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,ClearUnit))( this, axis, status ); } int astSubFrame_( AstFrame *target, AstFrame *template, int result_naxes, const int *target_axes, const int *template_axes, AstMapping **map, AstFrame **result, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(target,Frame,SubFrame))( target, template, result_naxes, target_axes, template_axes, map, result, status ); } int astUnformat_( AstFrame *this, int axis, const char *string, double *value, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,Unformat))( this, axis, string, value, status ); } int astValidateAxis_( AstFrame *this, int axis, int fwd, const char *method, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,ValidateAxis))( this, axis, fwd, method, status ); } void astValidateAxisSelection_( AstFrame *this, int naxes, const int *axes, const char *method, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,ValidateAxisSelection))( this, naxes, axes, method, status ); } AstSystemType astValidateSystem_( AstFrame *this, AstSystemType system, const char *method, int *status ) { if ( !astOK ) return AST__BADSYSTEM; return (**astMEMBER(this,Frame,ValidateSystem))( this, system, method, status ); } AstSystemType astSystemCode_( AstFrame *this, const char *system, int *status ) { if ( !astOK ) return AST__BADSYSTEM; return (**astMEMBER(this,Frame,SystemCode))( this, system, status ); } const char *astSystemString_( AstFrame *this, AstSystemType system, int *status ) { if ( !astOK ) return NULL; return (**astMEMBER(this,Frame,SystemString))( this, system, status ); } int astAxIn_( AstFrame *this, int axis, double lo, double hi, double val, int closed, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,AxIn))( this, axis, lo, hi, val, closed, status ); } int astGetFrameFlags_( AstFrame *this, int *status ) { if ( !astOK ) return 0; return (**astMEMBER(this,Frame,GetFrameFlags))( this, status ); } void astSetFrameFlags_( AstFrame *this, int value, int *status ) { if ( !astOK ) return; (**astMEMBER(this,Frame,SetFrameFlags))( this, value, status ); } /* Special public interface functions. */ /* =================================== */ /* These provide the public interface to certain special functions whose public interface cannot be handled using macros (such as astINVOKE) alone. In general, they are named after the corresponding protected version of the function, but with "Id" appended to the name. */ /* Public Interface Function Prototypes. */ /* ------------------------------------- */ /* The following functions have public prototypes only (i.e. no protected prototypes), so we must provide local prototypes for use within this module. */ AstFrame *PickAxesId_( AstFrame *, int, const int[], AstMapping **, int * ); AstFrame *astFrameId_( int, const char *, ... ); const char *astFormatId_( AstFrame *, int, double, int * ); int astUnformatId_( AstFrame *, int, const char *, double *, int * ); void astPermAxesId_( AstFrame *, const int[], int * ); /* Special interface function implementations. */ /* ------------------------------------------- */ const char *astFormatId_( AstFrame *this, int axis, double value, int *status ) { /* *++ * Name: c astFormat f AST_FORMAT * Purpose: * Format a coordinate value for a Frame axis. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c const char *astFormat( AstFrame *this, int axis, double value ) f RESULT = AST_FORMAT( THIS, AXIS, VALUE, STATUS ) * Class Membership: * Frame method. * Description: c This function returns a pointer to a string containing the f This function returns a character string containing the * formatted (character) version of a coordinate value for a Frame * axis. The formatting applied is determined by the Frame's * attributes and, in particular, by any Format attribute string * that has been set for the axis. A suitable default format (based * on the Digits attribute value) will be applied if necessary. * Parameters: c this f THIS = INTEGER (given) * Pointer to the Frame. c axis f AXIS = INTEGER (Given) * The number of the Frame axis for which formatting is to be * performed (axis numbering starts at 1 for the first axis). c value f VALUE = DOUBLE PRECISION (Given) * The coordinate value to be formatted. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astFormat() c A pointer to a null-terminated string containing the formatted c value. f AST_FORMAT = CHARACTER * ( AST__SZCHR ) f The formatted value. * Notes: c - The returned pointer is guaranteed to remain valid and the c string to which it points will not be over-written for a total c of 50 successive invocations of this function. After this, the c memory containing the string may be re-used, so a copy of the c string should be made if it is needed for longer than this. c - A formatted value may be converted back into a numerical (double) c value using astUnformat. f - A formatted value may be converted back into a numerical f (double precision) value using AST_UNFORMAT. c - A NULL pointer will be returned if this function is invoked c with the AST error status set, or if it should fail for any c reason. f - A blank string will be returned if this function is invoked f with STATUS set to an error value, or if it should fail for any f reason. *-- * Implementation Notes: * This function implements the public interface for the astFormat * method. It is identical to astFormat_ except that: * * - The axis index is decremented by 1 before use. This allows the * public interface to use 1-based axis numbers (whereas internally * axis numbers are zero-based). * * - The returned string value is buffered in dynamically allocated * memory so that it will remain valid for a guaranteed number of * function invocations. */ /* Local Variables: */ astDECLARE_GLOBALS /* Thread-specific global data */ const char *fvalue; /* Pointer to formatted value */ const char *result; /* Pointer value to return */ int i; /* Loop counter for initialisation */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to Thread-specific global data. */ astGET_GLOBALS(this); /* If the "astformatid_strings" array has not been initialised, fill it with NULL pointers. */ if ( !astformatid_init ) { astformatid_init = 1; for ( i = 0; i < ASTFORMATID_MAX_STRINGS; i++ ) astformatid_strings[ i ] = NULL; } /* Invoke the normal astFormat_ function to obtain a pointer to the required formatted value, adjusting the axis index to become zero-based. */ fvalue = astFormat( this, axis - 1, value ); /* If OK, store a copy of the resulting string in dynamically allocated memory, putting a pointer to the copy into the next element of the "astformatid_strings" array. (This process also de-allocates any previously allocated memory pointed at by this "astformatid_strings" element, so the earlier string is effectively replaced by the new one.) */ if ( astOK ) { astBeginPM; astformatid_strings[ astformatid_istr ] = astStore( astformatid_strings[ astformatid_istr ], fvalue, strlen( fvalue ) + (size_t) 1 ); astEndPM; /* If OK, return a pointer to the copy and increment "astformatid_istr" to use the next element of "astformatid_strings" on the next invocation. Recycle "astformatid_istr" to zero when all elements have been used. */ if ( astOK ) { result = astformatid_strings[ astformatid_istr++ ]; if ( astformatid_istr == ( ASTFORMATID_MAX_STRINGS - 1 ) ) astformatid_istr = 0; } } /* Return the result. */ return result; } AstFrame *astFrameId_( int naxes, const char *options, ... ) { /* *++ * Name: c astFrame f AST_FRAME * Purpose: * Create a Frame. * Type: * Public function. * Synopsis: c #include "frame.h" c AstFrame *astFrame( int naxes, const char *options, ... ) f RESULT = AST_FRAME( NAXES, OPTIONS, STATUS ) * Class Membership: * Frame constructor. * Description: * This function creates a new Frame and optionally initialises its * attributes. * * A Frame is used to represent a coordinate system. It does this * in rather the same way that a frame around a graph describes the * coordinate space in which data are plotted. Consequently, a * Frame has a Title (string) attribute, which describes the * coordinate space, and contains axes which in turn hold * information such as Label and Units strings which are used for * labelling (e.g.) graphical output. In general, however, the * number of axes is not restricted to two. * * Functions are available for converting Frame coordinate values * into a form suitable for display, and also for calculating * distances and offsets between positions within the Frame. * * Frames may also contain knowledge of how to transform to and * from related coordinate systems. * Parameters: c naxes f NAXES = INTEGER (Given) * The number of Frame axes (i.e. the number of dimensions of * the coordinate space which the Frame describes). c options f OPTIONS = CHARACTER * ( * ) (Given) c Pointer to a null-terminated string containing an optional c comma-separated list of attribute assignments to be used for c initialising the new Frame. The syntax used is identical to c that for the astSet function and may include "printf" format c specifiers identified by "%" symbols in the normal way. c If no initialisation is required, a zero-length string may be c supplied. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Frame. The syntax used is identical to that for the f AST_SET routine. If no initialisation is required, a blank f value may be supplied. c ... c If the "options" string contains "%" format specifiers, then c an optional list of additional arguments may follow it in c order to supply values to be substituted for these c specifiers. The rules for supplying these are identical to c those for the astSet function (and for the C "printf" c function). f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astFrame() f AST_FRAME = INTEGER * A pointer to the new Frame. * Examples: c frame = astFrame( 2, "Title=Energy Spectrum: Plot %d", n ); c Creates a new 2-dimensional Frame and initialises its Title c attribute to the string "Energy Spectrum: Plot ", where c takes the value of the int variable "n". c frame = astFrame( 2, "Label(1)=Energy, Label(2)=Response" ); c Creates a new 2-dimensional Frame and initialises its axis c Label attributes to suitable string values. f FRAME = AST_FRAME( 2, 'Title=Energy Spectrum', STATUS ); f Creates a new 2-dimensional Frame and initialises its Title f attribute to the string "Energy Spectrum". f FRAME = AST_FRAME( 2, 'Label(1)=Energy, Label(2)=Response', STATUS ); f Creates a new 2-dimensional Frame and initialises its axis f Label attributes to suitable string values. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- * Implementation Notes: * - This function implements the external (public) interface to * the astFrame constructor function. It returns an ID value * (instead of a true C pointer) to external users, and must be * provided because astFrame_ has a variable argument list which * cannot be encapsulated in a macro (where this conversion would * otherwise occur). * - The variable argument list also prevents this function from * invoking astFrame_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *new; /* Pointer to new Frame */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the Frame, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitFrame( NULL, sizeof( AstFrame ), !class_init, &class_vtab, "Frame", naxes ); /* If successful, note that the virtual function table has been initialised. */ if ( astOK ) { class_init = 1; /* Obtain the variable argument list and pass it along with the options string to the astVSet method to initialise the new Frame's attributes. */ va_start( args, options ); astVSet( new, options, NULL, args ); va_end( args ); /* If an error occurred, clean up by deleting the new object. */ if ( !astOK ) new = astDelete( new ); } /* Return an ID value for the new Frame. */ return astMakeId( new ); } void astPermAxesId_( AstFrame *this, const int perm[], int *status ) { /* *++ * Name: c astPermAxes f AST_PERMAXES * Purpose: * Permute the axis order in a Frame. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c void astPermAxes( AstFrame *this, const int perm[] ) f CALL AST_PERMAXES( THIS, PERM, STATUS ) * Class Membership: * Frame method. * Description: c This function permutes the order in which a Frame's axes occur. f This routine permutes the order in which a Frame's axes occur. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c perm f PERM( * ) = INTEGER (Given) * An array with one element for each axis of the Frame (Naxes * attribute). This should list the axes in their new order, * using the original axis numbering (which starts at 1 for the * first axis). f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - Only genuine permutations of the axis order are permitted, so c each axis must be referenced exactly once in the "perm" array. f each axis must be referenced exactly once in the PERM array. * - If successive axis permutations are applied to a Frame, then * the effects are cumulative. *-- * Implementation Notes: * This function implements the public interface for the * astPermAxes method. It is identical to astPermAxes_ except that * the axis numbers in the "perm" array are decremented by 1 before * use. This is to allow the public interface to use one-based axis * numbering (internally, zero-based axis numbering is used). */ /* Local Variables: */ int *perm1; /* Pointer to modified perm array */ int axis; /* Loop counter for Frame axes */ int naxes; /* Number of Frame axes */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain the number of Frame axes. */ naxes = astGetNaxes( this ); /* Allocate an array to hold a modified version of the "perm" array. */ perm1 = astMalloc( sizeof( int ) * (size_t) naxes ); if ( astOK ) { /* Make a modified copy of the "perm" array by subtracting one from each element. This allows the public interface to use one-based axis numbering, whereas all internal code is zero-based. */ for ( axis = 0; axis < naxes; axis++ ) perm1[ axis ] = perm[ axis ] - 1; /* Invoke the normal astPermAxes_ function to permute the Frame's axes. */ astPermAxes( this, perm1 ); } /* Free the temporary array. */ perm1 = astFree( perm1 ); } AstFrame *astPickAxesId_( AstFrame *this, int naxes, const int axes[], AstMapping **map, int *status ) { /* *++ * Name: c astPickAxes f AST_PICKAXES * Purpose: * Create a new Frame by picking axes from an existing one. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c AstFrame *astPickAxes( AstFrame *this, int naxes, const int axes[], c AstMapping **map ) f RESULT = AST_PICKAXES( THIS, NAXES, AXES, MAP, STATUS ) * Class Membership: * Frame method. * Description: * This function creates a new Frame whose axes are copied from an * existing Frame along with other Frame attributes, such as its * Title. Any number (zero or more) of the original Frame's axes * may be copied, in any order, and additional axes with default * attributes may also be included in the new Frame. * c Optionally, a Mapping that converts between the coordinate f A Mapping that converts between the coordinate * systems described by the two Frames will also be returned. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the original Frame. c naxes f NAXES = INTEGER (Given) * The number of axes required in the new Frame. c axes f AXES( NAXES ) = INTEGER (Given) c An array, with "naxes" elements, which lists the axes to be f An array which lists the axes to be * copied. These should be given in the order required in the * new Frame, using the axis numbering in the original Frame * (which starts at 1 for the first axis). Axes may be selected * in any order, but each may only be used once. If additional * (default) axes are also to be included, the corresponding * elements of this array should be set to zero. c map f MAP = INTEGER (Returned) c Address of a location in which to return a pointer to a new f A pointer to a new * Mapping. This will be a PermMap (or a UnitMap as a special * case) that describes the axis permutation that has taken * place between the original and new Frames. The Mapping's * forward transformation will convert coordinates from the * original Frame into the new one, and vice versa. c c If this Mapping is not required, a NULL value may be supplied c for this parameter. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astPickAxes() f AST_PICKAXES = INTEGER * A pointer to the new Frame. * Applicability: * Frame * This function applies to all Frames. The class of Frame returned * may differ from that of the original Frame, depending on which * axes are selected. For example, if a single axis is picked from a * SkyFrame (which must always have two axes) then the resulting * Frame cannot be a valid SkyFrame, so will revert to the parent * class (Frame) instead. * FrameSet * Using this function on a FrameSet is identical to using it on * the current Frame in the FrameSet. The returned Frame will not * be a FrameSet. * Region * If this function is used on a Region, an attempt is made to * retain the bounds information on the selected axes. If * succesful, the returned Frame will be a Region of some class. * Otherwise, the returned Frame is obtained by calling this * function on the Frame represented by the supplied Region (the * returned Frame will then not be a Region). In order to be * succesful, the selected axes in the Region must be independent * of the others. For instance, a Box can be split in this way but * a Circle cannot. Another requirement for success is that no * default axes are added (that is, the c "axes" f AXES * array must not contain any zero values. * Notes: c - The new Frame will contain a "deep" copy (c.f. astCopy) of all f - The new Frame will contain a "deep" copy (c.f. AST_COPY) of all * the data selected from the original Frame. Modifying any aspect * of the new Frame will therefore not affect the original one. * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- * Implementation Notes: * This function implements the public interface for the * astPickAxes method. It is identical to astPickAxes_ except for * the following: * * - The axis numbers in the "axes" array are decremented by 1 before * use. This is to allow the public interface to use one-based axis * numbering (internally, zero-based axis numbering is used). * * - An ID value is returned via the "map" parameter (if used) * instead of a true C pointer. This is required because this * conversion cannot be performed by the macro that invokes the * function. */ /* Local Variables: */ AstFrame *result; /* Pointer to result Frame */ int *axes1; /* Pointer to modified axes array */ int axis; /* Loop counter for axes */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Allocate an array to hold a modified version of the "axes" array (check that "naxes" is valid first - if not, this error will be reported by astPickAxes_ below). */ axes1 = ( naxes >= 0 ) ? astMalloc( sizeof( int ) * (size_t) naxes ) : NULL; if ( astOK ) { /* Make a modified copy of the "axes" array by subtracting one from each element. This allows the public interface to use one-based axis numbering, whereas all internal code is zero-based. */ for ( axis = 0; axis < naxes; axis++ ) axes1[ axis ] = axes[ axis ] - 1; /* Invoke the normal astPickAxes_ function to select the required axes. */ result = astPickAxes( this, naxes, axes1, map ); } /* Free the temporary array. */ axes1 = astFree( axes1 ); /* If required, return an ID value for the Mapping. */ if ( map ) *map = astMakeId( *map ); /* Return the result. */ return result; } int astUnformatId_( AstFrame *this, int axis, const char *string, double *value, int *status ) { /* *++ * Name: c astUnformat f AST_UNFORMAT * Purpose: * Read a formatted coordinate value for a Frame axis. * Type: * Public virtual function. * Synopsis: c #include "frame.h" c int astUnformat( AstFrame *this, int axis, const char *string, c double *value ) f RESULT = AST_UNFORMAT( THIS, AXIS, STRING, VALUE, STATUS ) * Class Membership: * Frame method. * Description: c This function reads a formatted coordinate value (given as a c character string) for a Frame axis and returns the equivalent c numerical (double) value. It also returns the number of c characters read from the string. f This function reads a formatted coordinate value (given as a f character string) for a Frame axis and returns the equivalent f numerical (double precision) value. It also returns the number f of characters read from the string. * c The principle use of this function is in decoding user-supplied c input which contains formatted coordinate values. Free-format c input is supported as far as possible. If input is ambiguous, it c is interpreted with reference to the Frame's attributes (in c particular, the Format string associated with the Frame's c axis). This function is, in essence, the inverse of astFormat. f The principle use of this function is in decoding user-supplied f input which contains formatted coordinate values. Free-format f input is supported as far as possible. If input is ambiguous, it f is interpreted with reference to the Frame's attributes (in f particular, the Format string associated with the Frame's f axis). This function is, in essence, the inverse of AST_FORMAT. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Frame. c axis f AXIS = INTEGER (Given) * The number of the Frame axis for which a coordinate value is to * be read (axis numbering starts at 1 for the first axis). c string f STRING = CHARACTER * ( * ) (Given) c Pointer to a null-terminated character string containing the c formatted coordinate value. f A character string containing the formatted coordinate value. * This string may contain additional information following the * value to be read, in which case reading stops at the first * character which cannot be interpreted as part of the value. * Any white space before or after the value is discarded. c value f VALUE = DOUBLE PRECISION (Returned) c Pointer to a double in which the coordinate value read will be c returned. f The coordinate value read. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astUnformat() f AST_UNFORMAT = INTEGER * The number of characters read from the string in order to * obtain the coordinate value. This will include any white * space which occurs before or after the value. * Applicability: * Frame * This function applies to all Frames. See the "Frame Input * Format" section below for details of the input formats * accepted by a basic Frame. * SkyFrame * The SkyFrame class re-defines the input format to be suitable * for representing angles and times, with the resulting * coordinate value returned in radians. See the "SkyFrame * Input Format" section below for details of the formats * accepted. * FrameSet * The input formats accepted by a FrameSet are determined by * its current Frame (as specified by the Current attribute). * Frame Input Format * The input format accepted for a basic Frame axis is as follows: * - An optional sign, followed by: * - A sequence of one or more digits possibly containing a decimal point, * followed by: * - An optional exponent field. * - The exponent field, if present, consists of "E" or "e" * followed by a possibly signed integer. * * Examples of acceptable Frame input formats include: * - 99 * - 1.25 * - -1.6 * - 1E8 * - -.99e-17 * - * SkyFrame Input Format * The input format accepted for a SkyFrame axis is as follows: * - An optional sign, followed by between one and three fields * representing either degrees, arc-minutes, arc-seconds or hours, * minutes, seconds (e.g. "-12 42 03"). * - Each field should consist of a sequence of one or more digits, * which may include leading zeros. At most one field may contain a * decimal point, in which case it is taken to be the final field * (e.g. decimal degrees might be given as "124.707", while degrees * and decimal arc-minutes might be given as "-13 33.8"). * - The first field given may take any value, allowing angles and * times outside the conventional ranges to be * represented. However, subsequent fields must have values of less * than 60 (e.g. "720 45 31" is valid, whereas "11 45 61" is not). * - Fields may be separated by white space or by ":" (colon), but * the choice of separator must be used consistently throughout the * value. Additional white space may be present around fields and * separators (e.g. "- 2: 04 : 7.1"). * - The following field identification characters may be used as * separators to replace either of those above (or may be appended * to the final field), in order to identify the field to which * they are appended: "d"---degrees; "h"---hours; "m"---minutes of * arc or time; "s"---seconds of arc or time; "'" (single * quote)---minutes of arc; """ (double quote)---seconds of arc. * Either lower or upper case may be used. Fields must be given in * order of decreasing significance (e.g. "-11D 3' 14.4"" or * "22h14m11.2s"). * - The presence of any of the field identification characters * "d", "'" (single quote) or """ (double quote) indicates that the * value is to be interpreted as an angle. Conversely, the presence * of "h" indicates that it is to be interpreted as a time (with 24 * hours corresponding to 360 degrees). Incompatible angle/time * identification characters may not be mixed (e.g. "10h14'3"" is * not valid). The remaining field identification characters and * separators do not specify a preference for an angle or a time * and may be used with either. c - If no preference for an angle or a time is expressed anywhere c within the value, it is interpreted as an angle if the Format c attribute string associated with the SkyFrame axis generates an c angle and as a time otherwise. This ensures that values produced c by astFormat are correctly interpreted by astUnformat. f - If no preference for an angle or a time is expressed anywhere f within the value, it is interpreted as an angle if the Format f attribute string associated with the SkyFrame axis generates an f angle and as a time otherwise. This ensures that values produced f by AST_FORMAT are correctly interpreted by AST_UNFORMAT. * - Fields may be omitted, in which case they default to zero. The * remaining fields may be identified by using appropriate field * identification characters (see above) and/or by adding extra * colon separators (e.g. "-05m13s" is equivalent to "-:05:13"). If * a field is not identified explicitly, it is assumed that * adjacent fields have been given, after taking account of any * extra separator characters (e.g. "14:25.4s" specifies minutes * and seconds, while "14::25.4s" specifies degrees and seconds). c - If fields are omitted in such a way that the remaining ones c cannot be identified uniquely (e.g. "01:02"), then the first c field (either given explicitly or implied by an extra leading c colon separator) is taken to be the most significant field that c astFormat would produce when formatting a value (using the c Format attribute associated with the SkyFrame axis). By c default, this means that the first field will normally be c interpreted as degrees or hours. However, if this does not c result in consistent field identification, then the last field c (either given explicitly or implied by an extra trailing colon c separator) is taken to to be the least significant field that c astFormat would produce. f - If fields are omitted in such a way that the remaining ones f cannot be identified uniquely (e.g. "01:02"), then the first f field (either given explicitly or implied by an extra leading f colon separator) is taken to be the most significant field that f AST_FORMAT would produce when formatting a value (using the f Format attribute associated with the SkyFrame axis). By f default, this means that the first field will normally be f interpreted as degrees or hours. However, if this does not f result in consistent field identification, then the last field f (either given explicitly or implied by an extra trailing colon f separator) is taken to to be the least significant field that f AST_FORMAT would produce. * c This final convention is intended to ensure that values formatted c by astFormat which contain less than three fields will be c correctly interpreted if read back using astUnformat, even if c they do not contain field identification characters. f This final convention is intended to ensure that values formatted f by AST_FORMAT which contain less than three fields will be f correctly interpreted if read back using AST_UNFORMAT, even if f they do not contain field identification characters. * * Examples of acceptable SkyFrame input formats (with * interpretation in parentheses) include: * - -14d 13m 22.2s (-14d 13' 22.2") * - + 12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s) * - 001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s) * - 22h 30 (22h 30m 00s) * - 136::10" (136d 00' 10" or 136h 00m 10s) * - -14M 27S (-0d 14' 27" or -0h 14m 27s) * - -:14: (-0d 14' 00" or -0h 14m 00s) * - -::4.1 (-0d 00' 04.1" or -0h 00m 04.1s) * - .9" (0d 00' 00.9") * - d12m (0d 12' 00") * - H 12:22.3s (0h 12m 22.3s) * - (AST__BAD) * * Where alternative interpretations are shown, the choice of angle or * time depends on the associated Format(axis) attribute. * Notes: * - A function value of zero (and no coordinate value) will be * returned, without error, if the string supplied does not contain * a suitably formatted value. c - Beware that it is possible for a formatting error part-way c through an input string to terminate input before it has been c completely read, but to yield a coordinate value that appears c valid. For example, if a user types "1.5r6" instead of "1.5e6", c the "r" will terminate input, giving an incorrect coordinate c value of 1.5. It is therefore most important to check the return c value of this function to ensure that the correct number of c characters have been read. f - Beware that it is possible for a formatting error part-way f through an input string to terminate input before it has been f completely read, but to yield a coordinate value that appears f valid. For example, if a user types "1.5R6" instead of "1.5E6", f the "R" will terminate input, giving an incorrect coordinate f value of 1.5. It is therefore most important to check the return f value of this function to ensure that the correct number of f characters have been read. * - An error will result if a value is read which appears to have * the correct format, but which cannot be converted into a valid * coordinate value (for instance, because the value of one or more * of its fields is invalid). * - The string "" is recognised as a special case and will * yield the coordinate value AST__BAD without error. The test for * this string is case-insensitive and also permits embedded white * space. c - A function result of zero will be returned and no coordinate c value will be returned via the "value" pointer if this function c is invoked with the AST error status set, or if it should fail c for any reason. f - A function result of zero will be returned and no coordinate f value will be returned via the VALUE argument if this function f is invoked with the AST error status set, or if it should fail f for any reason. *-- * Implementation Notes: * This function implements the public interface for the * astUnformat method. It is identical to astUnformat_ except that: * * - The axis index is decremented by 1 before use. This allows the * public interface to use 1-based axis numbers (whereas internally * axis numbers are zero-based). */ /* Invoke the normal astUnformat_ function, adjusting the axis index to become zero-based. */ return astUnformat( this, axis - 1, string, value ); } ast-8.3.0/normmap.h0000664000175000017500000001451013004147321011052 00000000000000#if !defined( NORMMAP_INCLUDED ) /* Include this file only once */ #define NORMMAP_INCLUDED /* *+ * Name: * normmap.h * Type: * C include file. * Purpose: * Define the interface to the NormMap class. * Invocation: * #include "normmap.h" * Description: * This include file defines the interface to the NormMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The NormMap class implements Mappings which use a Frame to * normalise the input axis values. * Inheritance: * The NormMap class inherits from the Mapping class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 11-JUL-2005 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "frame.h" /* Coordinate Frames */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* NormMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstNormMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstFrame *frame; /* Encapsulated Frame */ } AstNormMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstNormMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; } AstNormMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstNormMapGlobals { AstNormMapVtab Class_Vtab; int Class_Init; } AstNormMapGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitNormMapGlobals_( AstNormMapGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(NormMap) /* Check class membership */ astPROTO_ISA(NormMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstNormMap *astNormMap_( void *, const char *, int *, ...); #else AstNormMap *astNormMapId_( void *, const char *, ... )__attribute__((format(printf,2,3))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstNormMap *astInitNormMap_( void *, size_t, int, AstNormMapVtab *, const char *, AstFrame *, int * ); /* Vtab initialiser. */ void astInitNormMapVtab_( AstNormMapVtab *, const char *, int * ); /* Loader. */ AstNormMap *astLoadNormMap_( void *, size_t, AstNormMapVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckNormMap(this) astINVOKE_CHECK(NormMap,this,0) #define astVerifyNormMap(this) astINVOKE_CHECK(NormMap,this,1) /* Test class membership. */ #define astIsANormMap(this) astINVOKE_ISA(NormMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astNormMap astINVOKE(F,astNormMap_) #else #define astNormMap astINVOKE(F,astNormMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitNormMap(mem,size,init,vtab,name,frame) \ astINVOKE(O,astInitNormMap_(mem,size,init,vtab,name,frame,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitNormMapVtab(vtab,name) astINVOKE(V,astInitNormMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadNormMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadNormMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckNormMap to validate NormMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #endif #endif ast-8.3.0/ellipse.c0000664000175000017500000031714413004147321011042 00000000000000/* *class++ * Name: * Ellipse * Purpose: * An elliptical region within a 2-dimensional Frame. * Constructor Function: c astEllipse f AST_ELLIPSE * Description: * The Ellipse class implements a Region which represents a ellipse * within a 2-dimensional Frame. * Inheritance: * The Ellipse class inherits from the Region class. * Attributes: * The Ellipse class does not define any new attributes beyond * those which are applicable to all Regions. * Functions: c In addition to those functions applicable to all Regions, the c following functions may also be applied to all Ellipses: f In addition to those routines applicable to all Regions, the f following routines may also be applied to all Ellipses: * c - astEllipsePars: Get the geometric parameters of the Ellipse f - AST_ELLIPSEPARS: Get the geometric parameters of the Ellipse * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 7-SEP-2004 (DSB): * Original version. * 4-NOV-2013 (DSB): * Modify RegPins so that it can handle uncertainty regions that straddle * a discontinuity. Previously, such uncertainty Regions could have a huge * bounding box resulting in matching region being far too big. * 6-JAN-2014 (DSB): * Ensure cached information is available in RegCentre even if no new * centre is supplied. *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 Ellipse /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "box.h" /* Box Regions */ #include "wcsmap.h" /* Definitons of AST__DPI etc */ #include "circle.h" /* Interface definition for circle class */ #include "ellipse.h" /* Interface definition for this class */ #include "mapping.h" /* Position mappings */ #include "unitmap.h" /* Unit Mapping */ #include "pal.h" /* Positional astronomy library */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); static void (* parent_setregfs)( AstRegion *, AstFrame *, int * ); static void (* parent_resetcache)( AstRegion *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(Ellipse) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(Ellipse,Class_Init) #define class_vtab astGLOBAL(Ellipse,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstEllipseVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstEllipse *astEllipseId_( void *, int, const double[2], const double[2], const double[2], void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static double *RegCentre( AstRegion *this, double *, double **, int, int, int * ); static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); static int RegTrace( AstRegion *, int, double *, double **, int * ); static void Cache( AstEllipse *, int * ); static void CalcPars( AstFrame *, double[2], double[2], double[2], double *, double *, double *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void EllipsePars( AstEllipse *, double[2], double *, double *, double *, double[2], double[2], int * ); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void ResetCache( AstRegion *this, int * ); static void SetRegFS( AstRegion *, AstFrame *, int * ); /* Member functions. */ /* ================= */ AstRegion *astBestEllipse_( AstPointSet *mesh, double *cen, AstRegion *unc, int *status ){ /* *+ * Name: * astBestEllipse * Purpose: * Find the best fitting Ellipse through a given mesh of points. * Type: * Protected function. * Synopsis: * #include "ellipse.h" * AstRegion *astBestEllipse( AstPointSet *mesh, double *cen, AstRegion *unc ) * Class Membership: * Ellipse member function * Description: * This function finds the best fitting Ellipse through a given mesh of * points. Ellispes are always 2-dimensional. * Parameters: * mesh * Pointer to a PointSet holding the mesh of points. They are * assumed to be in the Frame represented by "unc". * cen * Pointer to an array holding the coordinates of the new Ellipse * centre. * unc * A Region representing the uncertainty associated with each point * on the mesh. * Returned Value: * Pointer to the best fitting Ellipse. It will inherit the positional * uncertainty and Frame represented by "unc". * Implementation Deficiencies: * - The method used by this function is not very accurate, and assumes * that the supplied mesh provides uniform coverage of the entire ellipse. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. *- */ /* Local Variables: */ AstFrame *frm; AstPointSet *ps2; AstRegion *result; double **ptr2; double **ptr; double *ang; double *dist; double *px; double *py; double a0; double a; double aa[2]; double at; double b; double c0; double c1; double c2; double c; double d; double den; double e; double f; double mn; double mx; double p[2]; double pa[2]; double pb[2]; double r1; double r2; double r3; double smn; double t1; double t2; double t3; int ip; int maxat; int np; double sw; /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get no. of points in the mesh. */ np = astGetNpoint( mesh ); /* Get pointers to the axis values. */ ptr = astGetPoints( mesh ); /* Allocate work space */ dist = astMalloc( sizeof( double )*(size_t) np ); ang = astMalloc( sizeof( double )*(size_t) np ); /* Get a pointer to the Frame represented by "unc". This is the Frame to which the supplied mesh points refer. */ frm = astGetFrame( unc->frameset, AST__CURRENT ); /* Check pointers can be used safely */ if( astOK ) { /* Find the first mesh point which is at a non-zero distance from the centre. */ px = ptr[ 0 ]; py = ptr[ 1 ]; for( ip = 0; ip < np; ip++, px++, py++ ) { p[ 0 ] = *px; p[ 1 ] = *py; dist[ ip ] = astDistance( frm, cen, p ); if( dist[ ip ] != AST__BAD && dist[ ip ] != 0.0 ) { break; } else { ang[ ip ] = AST__BAD; dist[ ip ] = AST__BAD; } } /* Find a point which is this distance away from the centre along the second axis. This point is used to define zero angle when calling astAngle below. */ astOffset2( frm, cen, 0.0, dist[ ip ], aa ); ang[ ip ] = astAngle( frm, aa, cen, p ); /* Get the distance from the centre to each of the remaining mesh points. Also find the orientation of the radial lines through the centre to each mesh point. At the same time, find the index of the point with the largest radial distance. */ maxat = ip; r2 = dist[ maxat ]; ip++; px++; py++; for( ; ip < np; ip++, px++, py++ ) { p[ 0 ] = *px; p[ 1 ] = *py; dist[ ip ] = astDistance( frm, cen, p ); ang[ ip ] = astAngle( frm, aa, cen, p ); if( dist[ ip ] != AST__BAD && dist[ ip ] > r2 ) { r2 = dist[ ip ]; maxat = ip; } } /* Find the higher index neighbouring point, wrapping back to the start of the list when the end is reached. Note the radius and position angle at this neighbouring point. */ t2 = 0.0; r3 = AST__BAD; t3 = AST__BAD; a0 = ang[ maxat ]; for( ip = maxat + 1; ip < np; ip++ ) { if( dist[ ip ] != AST__BAD ) { r3 = dist[ ip ]; t3 = palDrange( ang[ ip ] - a0 ); break; } } if( r3 == AST__BAD ) { for( ip = 0; ip < maxat; ip++ ) { if( dist[ ip ] != AST__BAD ) { r3 = dist[ ip ]; t3 = palDrange( ang[ ip ] - a0 ); break; } } } /* Find the lower index neighbouring point, wrapping back to the end of the list when the start is reached. Note the radius and position angle at this neighbouring point. */ r1 = AST__BAD; t1 = AST__BAD; for( ip = maxat - 1; ip > -1; ip-- ) { if( dist[ ip ] != AST__BAD ) { r1 = dist[ ip ]; t1 = palDrange( ang[ ip ] - a0 ); break; } } if( r1 == AST__BAD ) { for( ip = np - 1; ip > maxat; ip-- ) { if( dist[ ip ] != AST__BAD ) { r1 = dist[ ip ]; t1 = palDrange( ang[ ip ] - a0 ); break; } } } /* Fit a quadratic through the three pairs of (radius,angle) values. The centre point (r2,t2) is the point which is furthest from the centre, and the other two are the neighbouring points found above. */ a = r2 - r1; b = t2 - t1; c = t2*t2 - t1*t1; d = r3 - r2; e = t3 - t2; f = t3*t3 - t2*t2; den = c*e - b*f; if( den != 0.0 ) { /* The co-efficients of the interpolating polynomial... */ c1 = ( d*c - a*f )/den; c2 = ( a*e - d*b )/den; c0 = r1 - c1*t1 - c2*t1*t1; /* Find the largest radius (the turning point of the quadratic), and the angle at which it occurs. */ if( c2 < 0.0 ) { mx = ( 4*c0*c2 - c1*c1 )/( 4*c2 ); at = a0 - c1/( 2*c2 ); } else { mx = r2; at = a0 - t2; } /* This point is the end of the ellipse primary axis. Find its (x,y) coords, and store in "pa". */ astOffset2( frm, cen, at, mx, pa ); /* Resolve all the supplied points into components parallel and perpendicular to the line joining the centre and "pa". */ ps2 = astResolvePoints( frm, cen, pa, mesh, NULL ); ptr2 = astGetPoints( ps2 ); if( astOK ) { /* For each other mesh point, work out the length of the secondary axis which would result if we used that point to define the ellipse. Find the mean of these secondary axis lengths, weighted by the length of the y component to reduce influence of poor conditioning at very low y. */ smn = 0.0; sw = 0.0; px = ptr2[ 0 ]; py = ptr2[ 1 ]; for( ip = 0; ip < np; ip++, px++, py++ ) { if( *px != AST__BAD && *py != AST__BAD ) { den = mx*mx - (*px)*(*px); if( den > 0.0 ) { smn += fabs( mx*(*py)*(*py) )/sqrt( den ); sw += fabs( *py ); } } } if( sw > 0 ) { mn = smn/sw; /* Find the coords at the end of the mean secondary axis. */ astOffset2( frm, cen, at + AST__DPIBY2, mn, pb ); /* Create the Ellipse to return. */ result = (AstRegion *) astEllipse( frm, 0, cen, pa, pb, unc, "", status ); } } /* Free resources. */ ps2 = astAnnul( ps2 ); } } dist = astFree( dist ); ang = astFree( ang ); frm = astAnnul( frm ); /* Return NULL if anything went wrong. */ if( !astOK ) result = astAnnul( result ); /* Return the result.*/ return result; } void astInitEllipseVtab_( AstEllipseVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitEllipseVtab * Purpose: * Initialise a virtual function table for a Ellipse. * Type: * Protected function. * Synopsis: * #include "ellipse.h" * void astInitEllipseVtab( AstEllipseVtab *vtab, const char *name ) * Class Membership: * Ellipse vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the Ellipse 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAEllipse) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->EllipsePars = EllipsePars; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; parent_setregfs = region->SetRegFS; region->SetRegFS = SetRegFS; parent_resetcache = region->ResetCache; region->ResetCache = ResetCache; region->RegPins = RegPins; region->RegBaseMesh = RegBaseMesh; region->RegBaseBox = RegBaseBox; region->RegCentre = RegCentre; region->RegTrace = RegTrace; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump functions. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "Ellipse", "Elliptical region" ); /* 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 Cache( AstEllipse *this, int *status ){ /* * Name: * Cache * Purpose: * Calculate intermediate values and cache them in the Ellipse structure. * Type: * Private function. * Synopsis: * #include "ellipse.h" * void Cache( AstEllipse *this, int *status ) * Class Membership: * Ellipse member function * Description: * This function uses the PointSet stored in the parent Region to calculate * some intermediate values which are useful in other methods. These * values are stored within the Ellipse structure. * Parameters: * this * Pointer to the Ellipse. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstFrame *frm; /* Pointer to base Frame in Ellipse */ double **ptr; /* Pointer to data in the encapsulated PointSet */ double *centre; /* Array holding centre coords */ double *point1; /* Array holding coords at end of primary axis */ double *point2; /* Array holding coords at another point on ellipse */ double a; /* The half-length of the primary axis */ double angle; /* Orientation of primary axis */ double b; /* The half-length of the secondary axis */ int i; /* Axis index */ /* Check the global error status. */ if ( !astOK ) return; /* Do Nothing if the cached information is up to date. */ if( this->stale ) { /* Get a pointer to the base Frame. */ frm = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); /* Allocate memory. */ centre = (double *) astMalloc( sizeof( double )*2 ); point1 = (double *) astMalloc( sizeof( double )*2 ); point2 = (double *) astMalloc( sizeof( double )*2 ); /* Get pointers to the coordinate data in the parent Region structure. */ ptr = astGetPoints( ((AstRegion *) this)->points ); /* Check pointers can be used safely. */ if( astOK ) { /* Copy the points in to the allocated memory. */ for( i = 0; i < 2; i++ ) { centre[ i ] = ptr[ i ][ 0 ]; point1[ i ] = ptr[ i ][ 1 ]; point2[ i ] = ptr[ i ][ 2 ]; } /* Calculate the geometric parameters of the ellipse. */ CalcPars( frm, centre, point1, point2, &a, &b, &angle, status ); /* Check the returned values. */ if( a <= 0.0 || a == AST__BAD || b <= 0.0 || b == AST__BAD ) { if( astOK ) astError( AST__BADIN, "astInitEllipse(%s): The " "supplied points do not determine an " "ellipse.", status, astGetClass( this ) ); } /* Store useful things in the Ellipse structure. */ if( astOK ) { astFree( this->centre ); this->centre = centre; centre = NULL; astFree( this->point1 ); this->point1 = point1; point1 = NULL; this->a = a; this->b = b; this->angle = angle; } } /* Initialise the bounding box. This is set properly when the astRegBaseMesh function is called. These variables should not be used unless the "basemesh" component of the parent Region structure is set to a non-null value. */ this->lbx = -DBL_MAX; this->ubx = DBL_MAX; this->lby = -DBL_MAX; this->uby = DBL_MAX; /* Free resources */ frm = astAnnul( frm ); if( centre ) centre = astFree( centre ); if( point1 ) point1 = astFree( point1 ); point2 = astFree( point2 ); /* Indicate cached information is up to date. */ this->stale = 0; } } static void CalcPars( AstFrame *frm, double centre[2], double point1[2], double point2[2], double *a, double *b, double *angle, int *status ){ /* * Name: * CalcPars * Purpose: * Calculate ellipse parameters. * Type: * Private function. * Synopsis: * #include "ellipse.h" * void CalcPars( AstFrame *frm, double centre[2], double point1[2], * double point2[2], double *a, double *b, double *angle, * int *status ) * Class Membership: * Ellipse member function * Description: * This function uses the supplied positions to calculate the * geometric parameters of an ellipse. * Parameters: * frm * Pointer to the Frame in which the positions are defined. * centre; * Array holding centre coords. * point1 * Array holding coords at end of primary axis * point2 * Array holding coords at another point on ellipse. On exit it * holds the coords at the end of the secondary axis. * a * Pointer to location at which to store the half-length of the * primary axis. * b * Pointer to location at which to store the half-length of the * secondary axis. * angle * Pointer to location at which to store the angle from the * positive direction of the second Frame axis to the primary * ellipse axis, in radians. Rotation from the second to the first * Frame axis is positive. * status * Pointer to the inherited status variable. */ /* Local Variables: */ double point3[ 2 ]; /* Array holding a point on the primary axis */ double x; /* The offset parallel to the primary axis */ double y; /* The offset perpendicular to the primary axis */ /* Check the global error status. */ if ( !astOK ) return; /* Get the geodesic distance between the centre and point 1 (the end of the primary axis of the ellipse). This is the half length of the primary axis of the ellipse (the axis which joins the centre position to point 1). */ *a = astDistance( frm, centre, point1 ); /* Find the point (point3) on the primary axis which is closest to point 2, and thus get the geodesic offsets (resolved parallel and perpendicular to the primary axis) between the centre and point 2. */ if( *a > 0.0 ) { astResolve( frm, centre, point1, point2, point3, &x, &y ); /* Find the half-length of the secondary ellipse axis. */ if( astOK ) { *b = (*a)*(*a) - x*x; if( *b > 0.0 ) *b = (*a)*y/sqrt( *b ); } else { *b = *a; } /* Find the angle from the positive direction of the second axis to the primary ellipse axis. */ point3[ 0 ] = centre[ 0 ]; point3[ 1 ] = centre[ 1 ] + fabs( 0.1*(*a) ); *angle = astAngle( frm, point3, centre, point1 ); /* Find the end point of the secondary axis. */ (void) astOffset2( frm, centre, *angle + AST__DPIBY2, *b, point2 ); } } static void EllipsePars( AstEllipse *this, double centre[2], double *a, double *b, double *angle, double p1[2], double p2[2], int *status ){ /* *++ * Name: c astEllipsePars f AST_ELLIPSEPARS * Purpose: * Returns the geometric parameters of an Ellipse. * Type: * Public virtual function. * Synopsis: c #include "ellipse.h" c void astEllipsePars( AstEllipse *this, double centre[2], double *a, c double *b, double *angle, double p1[2], double p2[2] ) f CALL AST_ELLIPSEPARS( THIS, CENTRE, A, B, ANGLE, P1, P2, STATUS ) * Class Membership: * Region method. * Description: c This function f This routine * returns the geometric parameters describing the supplied ellipse. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the Region. c centre f CENTRE( 2 ) = DOUBLE PRECISION (Returned) * The coordinates of the Ellipse centre are returned in this arrays. c a f A = DOUBLE PRECISION (Returned) * Returned holding the half-length of the first axis of the * ellipse. c b f B = DOUBLE PRECISION (Returned) * Returned holding the half-length of the second axis of the * ellipse. c angle f ANGLE = DOUBLE PRECISION (Returned) * If the coordinate system in which the Ellipse is defined has * axes (X,Y), then c "*angle" f ANGLE * is returned holding the angle from the positive direction of * the Y axis to the first axis of the ellipse, in radians. * Positive rotation is in the same sense as rotation from the * positive direction of Y to the positive direction of X. c p1 f P1( 2 ) = DOUBLE PRECISION (Returned) * An array in which to return the coordinates at one of the two ends * of the first axis of the ellipse. c A NULL pointer can be supplied if these coordinates are not needed. c p2 f P2( 2 ) = DOUBLE PRECISION (Returned) * An array in which to return the coordinates at one of the two ends * of the second axis of the ellipse. c A NULL pointer can be supplied if these coordinates are not needed. f STATUS = INTEGER (Given and Returned) f The global status. * Notes: * - If the coordinate system represented by the Ellipse has been * changed since it was first created, the returned parameters refer * to the new (changed) coordinate system, rather than the original * coordinate system. Note however that if the transformation from * original to new coordinate system is non-linear, the shape * represented by the supplied Ellipse object may not be an accurate * ellipse. * - Values of AST__BAD are returned for the parameters without error * if the ellipse is degenerate or undefined. *-- */ /* Local Variables: */ AstFrame *frm; /* Current Frame represented by the Ellipse */ AstPointSet *pset; /* PointSet holding PointList axis values */ AstRegion *this_region; /* Parent Region pointer */ double **ptr; /* Pointer to axes values in the PointList */ double *point1; /* Pointer to "p1" or "buf1" */ double *point2; /* Pointer to "p2" or "buf2" */ double buf1[2]; /* Local substitute array for "p1" */ double buf2[2]; /* Local substitute array for "p2" */ int i; /* Axis index */ /* Check the inherited status. */ if( !astOK ) return; /* Store a pointer to the parent region structure. */ this_region = (AstRegion *) this; /* Transform the base Frame axis values into the current Frame. */ pset = astTransform( this_region->frameset, this_region->points, 1, NULL ); /* Get pointers to the coordinate data. */ ptr = astGetPoints( pset ); /* Choose the arrays to use - supplied arrays if possible, local arrays otherwise. */ if( p1 ) { point1 = p1; } else { point1 = buf1; } if( p2 ) { point2 = p2; } else { point2 = buf2; } /* Check pointers can be used safely. */ if( astOK ) { /* Copy the points in to separate arrays. */ for( i = 0; i < 2; i++ ) { centre[ i ] = ptr[ i ][ 0 ]; point1[ i ] = ptr[ i ][ 1 ]; point2[ i ] = ptr[ i ][ 2 ]; } /* Get the Ellipse frame. */ frm = astGetFrame( this_region->frameset, AST__CURRENT ); /* Calculate the geometric parameters of the ellipse. */ CalcPars( frm, centre, point1, point2, a, b, angle, status ); /* Ensure no zero values are returned. */ if( *a <= 0.0 || *b <= 0.0 ) { *a = AST__BAD; *b = AST__BAD; *angle = AST__BAD; } /* Free resources */ frm = astAnnul( frm ); } pset = astAnnul( pset ); } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "ellipse.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * Ellipse member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstEllipse *this; /* Pointer to Ellipse structure */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the Ellipse structure */ this = (AstEllipse *) this_region; /* The bounding box of the mesh returned by astRegBaseMesh is used as the bounding box of the Ellipse. These bounds are cached in the Ellipse structure by astRegBaseMesh. Ensure astRegBaseMesh has been invoked, so that it is safe to use the cached bounding box. */ if( !this_region->basemesh ) (void) astAnnul( astRegBaseMesh( this ) ); /* Store the bounding box. */ lbnd[ 0 ] = this->lbx; ubnd[ 0 ] = this->ubx; lbnd[ 1 ] = this->lby; ubnd[ 1 ] = this->uby; } static AstPointSet *RegBaseMesh( AstRegion *this_region, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "ellipse.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * Ellipse member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the PointSet. Annul the pointer using astAnnul when it * is no longer needed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Constants: */ #define NP_EDGE 50 /* No. of points for determining geodesic */ /* Local Variables: */ AstEllipse *this; /* The Ellipse structure */ AstFrame *frm; /* Base Frame in encapsulated FrameSet */ AstPointSet *result; /* Returned pointer */ AstRegion *reg; /* Copy of supplied Ellipse */ double **ptr; /* Pointers to data */ double ang; /* Position angular of primary axis at "dx" */ double angle; /* Ellipse parametric angle at point */ double delta; /* Angular separation of points */ double dist; /* Offset along an axis */ double dx; /* Primary axis offset */ double dy; /* Secondary axis offset */ double lbnd[2]; /* Lower bounding box bounds */ double lbx; /* Lower x bound of mesh bounding box */ double lby; /* Lower y bound of mesh bounding box */ double p2[ 2 ]; /* Position in 2D Frame */ double p[ 2 ]; /* Position in 2D Frame */ double ubnd[2]; /* Upper bounding box bounds */ double ubx; /* Upper x bound of mesh bounding box */ double uby; /* Upper y bound of mesh bounding box */ int i; /* Point index */ int np; /* No. of points in returned PointSet */ /* Initialise */ result= NULL; /* Check the global error status. */ if ( !astOK ) return result; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this_region->basemesh ) { result = astClone( this_region->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Initialise the bounding box of the mesh points. */ lbx = DBL_MAX; ubx = -DBL_MAX; lby = DBL_MAX; uby = -DBL_MAX; /* Get a pointer to the Ellipse structure. */ this = (AstEllipse *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* Get the requested number of points to put on the mesh. */ np = astGetMeshSize( this ); /* Store the angular increment between points. */ delta = 2*AST__DPI/np; /* Create a suitable PointSet to hold the returned positions. */ result = astPointSet( np, 2, "", status ); ptr = astGetPoints( result ); if( astOK ) { /* Loop round each point. The angle is the parametric angle, phi, where the ellipse is defined by: dx = a.cos( phi ) dy = a.sin( phi ) measured from the primary ellipse. Positive in the sense of rotation from axis 2 to axis 1. */ angle = 0.0; for( i = 0; i < np; i++ ) { /* Find the offsets from the centre. "dx" is geodesic distance along the primary axis, and dy is geodesic distance along the secondary axis. */ dx = this->a*cos( angle ); dy = this->b*sin( angle ); /* Now find the point which corresponds to this dx and dy, taking account of the potential spherical geometry of hte coordinate system. First move a distance "dx" from the centre along the primary axis. The function value returned is 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. */ ang = astOffset2( frm, this->centre, this->angle, dx, p ); /* Now move a distance "dy" from the point found above at right angles to the primary axis. */ astOffset2( frm, p, ang + AST__DPIBY2, dy, p2 ); /* Store the resulting axis values. */ ptr[ 0 ][ i ] = p2[ 0 ]; ptr[ 1 ][ i ] = p2[ 1 ]; /* Update the bounds of the mesh bounding box. The box is expressed in terms of axis offsets from the centre, in order to avoid problems with boxes that cross RA=0 or RA=12h */ if( p2[ 0 ] != AST__BAD && p2[ 1 ] != AST__BAD ){ dist = astAxDistance( frm, 1, this->centre[ 0 ], p2[ 0 ] ); if( dist < lbx ) { lbx = dist; } else if( dist > ubx ) { ubx = dist; } dist = astAxDistance( frm, 1, this->centre[ 1 ], p2[ 1 ] ); if( dist < lby ) { lby = dist; } else if( dist > uby ) { uby = dist; } } /* Increment the angular position of the next mesh point. */ angle += delta; } } /* Save the returned pointer in the Region structure so that it does not need to be created again next time this function is called. Also cache the bounding box in the Ellipse structure. */ if( astOK && result ) { this_region->basemesh = astClone( result ); /* Extend the bounding box if it contains any singularies. The astNormBox requires a Mapping which can be used to test points in the base Frame. Create a copy of the Circle and then set its FrameSet so that the current Frame in the copy is the same as the base Frame in the original. */ reg = astCopy( this ); astSetRegFS( reg, frm ); astSetNegated( reg, 0 ); /* Normalise this box. */ lbnd[ 0 ] = this->centre[ 0 ] + lbx; lbnd[ 1 ] = this->centre[ 1 ] + lby; ubnd[ 0 ] = this->centre[ 0 ] + ubx; ubnd[ 1 ] = this->centre[ 1 ] + uby; astNormBox( frm, lbnd, ubnd, reg ); /* Save this box */ this->lbx = lbnd[ 0 ]; this->ubx = ubnd[ 0 ]; this->lby = lbnd[ 1 ]; this->uby = ubnd[ 1 ]; /* Free resources. */ reg = astAnnul( reg ); } frm = astAnnul( frm ); } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } static double *RegCentre( AstRegion *this_region, double *cen, double **ptr, int index, int ifrm, int *status ){ /* * Name: * RegCentre * Purpose: * Re-centre a Region. * Type: * Private function. * Synopsis: * #include "ellipse.h" * double *RegCentre( AstRegion *this, double *cen, double **ptr, * int index, int ifrm, int *status ) * Class Membership: * Ellipse member function (over-rides the astRegCentre protected * method inherited from the Region class). * Description: * This function shifts the centre of the supplied Region to a * specified position, or returns the current centre of the Region. * Parameters: * this * Pointer to the Region. * cen * Pointer to an array of axis values, giving the new centre. * Supply a NULL value for this in order to use "ptr" and "index" to * specify the new centre. * ptr * Pointer to an array of points, one for each axis in the Region. * Each pointer locates an array of axis values. This is the format * returned by the PointSet method astGetPoints. Only used if "cen" * is NULL. * index * The index of the point within the arrays identified by "ptr" at * which is stored the coords for the new centre position. Only used * if "cen" is NULL. * ifrm * Should be AST__BASE or AST__CURRENT. Indicates whether the centre * position is supplied and returned in the base or current Frame of * the FrameSet encapsulated within "this". * status * Pointer to the inherited status variable. * Returned Value: * If both "cen" and "ptr" are NULL then a pointer to a newly * allocated dynamic array is returned which contains the centre * coords of the Region. This array should be freed using astFree when * no longer needed. If either of "ptr" or "cen" is not NULL, then a * NULL pointer is returned. * Notes: * - Some Region sub-classes do not have a centre. Such classes will report * an AST__INTER error code if this method is called. */ /* Local Variables: */ AstEllipse *this; /* Pointer to Ellipse structure */ AstFrame *frm; /* Base Frame */ double **rptr; /* Data pointers for Region PointSet */ double *bc; /* Base Frame centre position */ double *result; /* Returned pointer */ double *tmp; /* Temporary array pointer */ double a[ 2 ]; /* Original position */ double angle; /* Orietentation of offset from old to new centre */ double axval; /* Axis value */ double b[ 2 ]; /* New position */ double dist; /* Distance from old to new centre */ double newcen[ 2 ]; /* New centre */ int ic; /* Coordinate index */ int ip; /* Position index */ int ncb; /* Number of base frame coordinate values per point */ int ncc; /* Number of current frame coordinate values per point */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get a pointer to the Ellipse structure. */ this = (AstEllipse *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* Get the number of axis values per point in the current Frame. */ ncc = astGetNout( this_region->frameset ); /* An ellipse always has 2 base frame axes. */ ncb = 2; /* If the centre coords are to be returned, return either a copy of the base Frame centre coords, or transform the base Frame centre coords into the current Frame. */ if( !ptr && !cen ) { if( ifrm == AST__CURRENT ) { result = astRegTranPoint( this_region, this->centre, 1, 1 ); } else { result = astStore( NULL, this->centre, sizeof( double )*ncb ); } /* Otherwise, we store the supplied new centre coords and return a NULL pointer. */ } else { /* Get a pointer to the axis values stored in the Region structure. */ rptr = astGetPoints( this_region->points ); /* Check pointers can be used safely */ if( astOK ) { /* If the centre position was supplied in the current Frame, find the corresponding base Frame position... */ if( ifrm == AST__CURRENT ) { if( cen ) { bc = astRegTranPoint( this_region, cen, 1, 0 ); } else { tmp = astMalloc( sizeof( double)*(size_t)ncc ); if( astOK ) { for( ic = 0; ic < ncc; ic++ ) tmp[ ic ] = ptr[ ic ][ index ]; } bc = astRegTranPoint( this_region, tmp, 1, 0 ); tmp = astFree( tmp ); } /* Replace any bad centre values with their current values. */ for( ic = 0; ic < ncb; ic++ ) { if( bc[ ic ] == AST__BAD ) bc[ ic ] = this->centre[ ic ]; } /* If the centre position was supplied in the base Frame, use the supplied "cen" or "ptr" pointer directly to change the coords in the parent Region structure and the cached coords in the Ellipse structure. */ } else { bc = newcen; for( ic = 0; ic < ncb; ic++ ) { axval = cen ? cen[ ic ] : ptr[ ic ][ index ]; newcen[ ic ] = ( axval != AST__BAD ) ? axval : this->centre[ ic ]; } } /* Find the direction and length of the offset between the old and new centre. */ frm = astGetFrame( this_region->frameset, AST__BASE ); angle = astAxAngle( frm, this->centre, bc, 2 ); dist = astDistance( frm, this->centre, bc ); /* Shift each point in the parent Region structure by the same length and direction. */ for( ip = 0; ip < 3; ip++ ) { a[ 0 ] = rptr[ ip ][ 0 ]; a[ 1 ] = rptr[ ip ][ 1 ]; astOffset2( frm, a, angle, dist, b ); rptr[ ip ][ 0 ] = b[ 0 ]; rptr[ ip ][ 1 ] = b[ 1 ]; } /* Indicate that the cache is stale. */ astResetCache( this ); /* Free resources */ frm = astAnnul( frm ); if( bc != newcen ) bc = astFree( bc ); } } /* Return the result. */ return result; } static int RegPins( AstRegion *this_region, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ /* * Name: * RegPins * Purpose: * Check if a set of points fall on the boundary of a given Ellipse. * Type: * Private function. * Synopsis: * #include "ellipse.h" * int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, * int **mask, int *status ) * Class Membership: * Ellipse member function (over-rides the astRegPins protected * method inherited from the Region class). * Description: * This function returns a flag indicating if the supplied set of * points all fall on the boundary of the given Ellipse. * * Some tolerance is allowed, as specified by the uncertainty Region * stored in the supplied Ellipse "this", and the supplied uncertainty * Region "unc" which describes the uncertainty of the supplied points. * Parameters: * this * Pointer to the Ellipse. * pset * Pointer to the PointSet. The points are assumed to refer to the * base Frame of the FrameSet encapsulated by "this". * unc * Pointer to a Region representing the uncertainties in the points * given by "pset". The Region is assumed to represent the base Frame * of the FrameSet encapsulated by "this". Zero uncertainity is assumed * if NULL is supplied. * mask * Pointer to location at which to return a pointer to a newly * allocated dynamic array of ints. The number of elements in this * array is equal to the value of the Npoint attribute of "pset". * Each element in the returned array is set to 1 if the * corresponding position in "pset" is on the boundary of the Region * and is set to zero otherwise. A NULL value may be supplied * in which case no array is created. If created, the array should * be freed using astFree when no longer needed. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the points all fall on the boundary of the given * Region, to within the tolerance specified. Zero otherwise. */ /* Local variables: */ AstEllipse *large_ellipse; /* Ellipse slightly larger than "this" */ AstEllipse *small_ellipse; /* Ellipse slightly smaller than "this" */ AstEllipse *this; /* Pointer to the Ellipse structure. */ AstFrame *frm; /* Base Frame in supplied Ellipse */ AstPointSet *ps1; /* Points masked by larger Ellipse */ AstPointSet *ps2; /* Points masked by larger and smaller Ellipsees */ AstRegion *tunc; /* Uncertainity Region from "this" */ double **ptr; /* Pointer to axis values in "ps2" */ double *p; /* Pointer to next axis value */ double *safe; /* An interior point in "this" */ double drad; /* Radius increment corresponding to border width */ double l1; /* Length of bounding box diagonal */ double l2; /* Length of bounding box diagonal */ double lbnd_tunc[2]; /* Lower bounds of "this" uncertainty Region */ double lbnd_unc[2]; /* Lower bounds of supplied uncertainty Region */ double lim; /* Smallest semi-minor/major axis length */ double p1[2]; /* New ellipse axis lengths */ double ubnd_tunc[2]; /* Upper bounds of "this" uncertainty Region */ double ubnd_unc[2]; /* Upper bounds of supplied uncertainty Region */ int i; /* Axis index */ int j; /* Point index */ int np; /* No. of supplied points */ int result; /* Returned flag */ /* Initialise */ result = 0; if( mask ) *mask = NULL; /* Check the inherited status. */ if( !astOK ) return result; /* Get a pointer to the Ellipse structure. */ this = (AstEllipse *) this_region; /* Check the supplied PointSet has 2 axis values per point. */ if( astGetNcoord( pset ) != 2 && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axis " "values per point (%d) in the supplied PointSet - should be " "2 (internal AST programming error).", status, astGetClass( this ), astGetNcoord( pset ) ); } /* Get the number of axes in the uncertainty Region and check it is also 2. */ if( unc && astGetNaxes( unc ) != 2 && astOK ) { astError( AST__INTER, "astRegPins(%s): Illegal number of axes (%d) " "in the supplied uncertainty Region - should be 2 " "(internal AST programming error).", status, astGetClass( this ), astGetNaxes( unc ) ); } /* Get the centre of the region in the base Frame. We use this as a "safe" interior point within the region. */ safe = astRegCentre( this, NULL, NULL, 0, AST__BASE ); /* We now find the maximum distance on each axis that a point can be from the boundary of the Ellipse for it still to be considered to be on the boundary. First get the Region which defines the uncertainty within the Ellipse being checked (in its base Frame), re-centre it on the interior point found above (to avoid problems if the uncertainty region straddles a discontinuity), and get its bounding box. */ tunc = astGetUncFrm( this, AST__BASE ); if( safe ) astRegCentre( tunc, safe, NULL, 0, AST__CURRENT ); astGetRegionBounds( tunc, lbnd_tunc, ubnd_tunc ); /* Find the geodesic length within the base Frame of "this" of the diagonal of the bounding box. */ frm = astGetFrame( this_region->frameset, AST__BASE ); l1 = astDistance( frm, lbnd_tunc, ubnd_tunc ); /* Also get the Region which defines the uncertainty of the supplied points and get its bounding box. First re-centre the uncertainty at the interior position to avoid problems from uncertainties that straddle a discontinuity. */ if( unc ) { if( safe ) astRegCentre( unc, safe, NULL, 0, AST__CURRENT ); astGetRegionBounds( unc, lbnd_unc, ubnd_unc ); /* Find the geodesic length of the diagonal of this bounding box. */ l2 = astDistance( frm, lbnd_unc, ubnd_unc ); /* Assume zero uncertainty if no "unc" Region was supplied. */ } else { l2 = 0.0; } /* Ensure cached information is available. */ Cache( this, status ); /* The required border width is half of the total diagonal of the two bounding boxes. */ if( astOK ) { drad = 0.5*( l1 + l2 ); /* Create two new Ellipse, one of which is larger than "this" by the amount found above, and the other of which is smaller than "this" by the amount found above. */ p1[ 0 ] = this->a + 0.5*drad; p1[ 1 ] = this->b + 0.5*drad; large_ellipse = astEllipse( frm, 1, this->centre, p1, &(this->angle), NULL, " ", status ); p1[ 0 ] = this->a - 0.5*drad; p1[ 1 ] = this->b - 0.5*drad; lim = 1.0E-6*drad; if( p1[ 0 ] < lim ) p1[ 0 ] = lim; if( p1[ 1 ] < lim ) p1[ 1 ] = lim; small_ellipse = astEllipse( frm, 1, this->centre, p1, &(this->angle), NULL, " ", status ); /* Negate the smaller region.*/ astNegate( small_ellipse ); /* Points are on the boundary of "this" if they are inside both the large Ellipse and the negated small Ellipse. First transform the supplied PointSet using the large Ellipse, then transform them using the negated smaller Ellipse. */ ps1 = astTransform( large_ellipse, pset, 1, NULL ); ps2 = astTransform( small_ellipse, ps1, 1, NULL ); /* Get a point to the resulting axis values, and the number of axis values per axis. */ ptr = astGetPoints( ps2 ); np = astGetNpoint( ps2 ); /* If a mask array is to be returned, create one. */ if( mask ) { *mask = astMalloc( sizeof(int)*(size_t) np ); /* Check all the resulting points, setting mask values for all of them. */ if( astOK ) { /* Initialise the mask elements on the basis of the first axis values */ result = 1; p = ptr[ 0 ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } else { (*mask)[ j ] = 1; } } /* Now check for bad values on other axes. */ for( i = 1; i < 2; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; (*mask)[ j ] = 0; } } } } /* If no output mask is to be made, we can break out of the check as soon as the first bad value is found. */ } else if( astOK ) { result = 1; for( i = 0; i < 2 && result; i++ ) { p = ptr[ i ]; for( j = 0; j < np; j++ ) { if( *(p++) == AST__BAD ) { result = 0; break; } } } } /* Free resources. */ large_ellipse = astAnnul( large_ellipse ); small_ellipse = astAnnul( small_ellipse ); ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); } tunc = astAnnul( tunc ); frm = astAnnul( frm ); safe = astFree( safe ); /* If an error has occurred, return zero. */ if( !astOK ) { result = 0; if( mask ) *mask = astAnnul( *mask ); } /* Return the result. */ return result; } static int RegTrace( AstRegion *this_region, int n, double *dist, double **ptr, int *status ){ /* *+ * Name: * RegTrace * Purpose: * Return requested positions on the boundary of a 2D Region. * Type: * Private function. * Synopsis: * #include "ellipse.h" * int astTraceRegion( AstRegion *this, int n, double *dist, double **ptr ); * Class Membership: * Ellipse member function (overrides the astTraceRegion method * inherited from the parent Region class). * Description: * This function returns positions on the boundary of the supplied * Region, if possible. The required positions are indicated by a * supplied list of scalar parameter values in the range zero to one. * Zero corresponds to some arbitrary starting point on the boundary, * and one corresponds to the end (which for a closed region will be * the same place as the start). * Parameters: * this * Pointer to the Region. * n * The number of positions to return. If this is zero, the function * returns without action (but the returned function value still * indicates if the method is supported or not). * dist * Pointer to an array of "n" scalar parameter values in the range * 0 to 1.0. * ptr * A pointer to an array of pointers. The number of elements in * this array should equal tthe number of axes in the Frame spanned * by the Region. Each element of the array should be a pointer to * an array of "n" doubles, in which to return the "n" values for * the corresponding axis. The contents of the arrays are unchanged * if the supplied Region belongs to a class that does not * implement this method. * Returned Value: * Non-zero if the astTraceRegion method is implemented by the class * of Region supplied, and zero if not. *- */ /* Local Variables; */ AstEllipse *this; AstFrame *frm; AstMapping *map; AstPointSet *bpset; AstPointSet *cpset; double **bptr; double ang; double angle; double dx; double dy; double p2[ 2 ]; double p[ 2 ]; int i; int ncur; /* Check inherited status, and the number of points to return, returning a non-zero value to indicate that this class supports the astRegTrace method. */ if( ! astOK || n == 0 ) return 1; /* Get a pointer to the Ellipse structure. */ this = (AstEllipse *) this_region; /* Ensure cached information is available. */ Cache( this, status ); /* Get a pointer to the base Frame in the encapsulated FrameSet. */ frm = astGetFrame( this_region->frameset, AST__BASE ); /* We first determine the required positions in the base Frame of the Region, and then transform them into the current Frame. Get the base->current Mapping, and the number of current Frame axes. */ map = astGetMapping( this_region->frameset, AST__BASE, AST__CURRENT ); /* If it's a UnitMap we do not need to do the transformation, so put the base Frame positions directly into the supplied arrays. */ if( astIsAUnitMap( map ) ) { bpset = NULL; bptr = ptr; ncur = 2; /* Otherwise, create a PointSet to hold the base Frame positions (known to be 2D since this is an ellipse). */ } else { bpset = astPointSet( n, 2, " ", status ); bptr = astGetPoints( bpset ); ncur = astGetNout( map ); } /* Check the pointers can be used safely. */ if( astOK ) { /* Loop round each point. */ for( i = 0; i < n; i++ ) { /* The supplied scalar parameter values are the parametric angles, phi, where the ellipse is defined by: dx = a.cos( phi ) dy = a.sin( phi ) measured from the primary ellipse. Positive in the sense of rotation from axis 2 to axis 1. */ angle = dist[ i ]*2*AST__DPI; /* Find the offsets from the centre. "dx" is geodesic distance along the primary axis, and dy is geodesic distance along the secondary axis. */ dx = this->a*cos( angle ); dy = this->b*sin( angle ); /* Now find the point which corresponds to this dx and dy, taking account of the potential spherical geometry of hte coordinate system. First move a distance "dx" from the centre along the primary axis. The function value returned is 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. */ ang = astOffset2( frm, this->centre, this->angle, dx, p ); /* Now move a distance "dy" from the point found above at right angles to the primary axis. */ astOffset2( frm, p, ang + AST__DPIBY2, dy, p2 ); /* Store the resulting axis values. */ bptr[ 0 ][ i ] = p2[ 0 ]; bptr[ 1 ][ i ] = p2[ 1 ]; } } /* If required, transform the base frame positions into the current Frame, storing them in the supplied array. Then free resources. */ if( bpset ) { cpset = astPointSet( n, ncur, " ", status ); astSetPoints( cpset, ptr ); (void) astTransform( map, bpset, 1, cpset ); cpset = astAnnul( cpset ); bpset = astAnnul( bpset ); } /* Free remaining resources. */ map = astAnnul( map ); frm = astAnnul( frm ); /* Return a non-zero value to indicate that this class supports the astRegTrace method. */ return 1; } static void ResetCache( AstRegion *this, int *status ){ /* * Name: * ResetCache * Purpose: * Clear cached information within the supplied Region. * Type: * Private function. * Synopsis: * #include "ellipse.h" * void ResetCache( AstRegion *this, int *status ) * Class Membership: * Region member function (overrides the astResetCache method * inherited from the parent Region class). * Description: * This function clears cached information from the supplied Region * structure. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. */ if( this ) { ( (AstEllipse *) this )->stale = 1; (*parent_resetcache)( this, status ); } } static void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) { /* * Name: * SetRegFS * Purpose: * Stores a new FrameSet in a Region * Type: * Private function. * Synopsis: * #include "ellipse.h" * void SetRegFS( AstRegion *this_region, AstFrame *frm, int *status ) * Class Membership: * Ellipse method (over-rides the astSetRegFS method inherited from * the Region class). * Description: * This function creates a new FrameSet and stores it in the supplied * Region. The new FrameSet contains two copies of the supplied * Frame, connected by a UnitMap. * Parameters: * this * Pointer to the Region. * frm * The Frame to use. * status * Pointer to the inherited status variable. */ /* Check the global error status. */ if ( !astOK ) return; /* Invoke the parent method to store the FrameSet in the parent Region structure. */ (* parent_setregfs)( this_region, frm, status ); /* Indicate that cached information will need to be re-calculated before it is next used. */ astResetCache( this_region ); } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "ellipse.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * Ellipse method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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: */ AstMapping *map; /* Base -> current Mapping */ AstMapping *result; /* Result pointer to return */ AstPointSet *mesh; /* Mesh of current Frame positions */ AstPointSet *ps2; /* Ellipse PointSet in current Frame */ AstRegion *new; /* Pointer to simplified Region */ AstRegion *newreg; /* Equivalent circle or ellipse */ AstRegion *this; /* Pointer to supplied Region structure */ AstRegion *unc; /* Pointer to uncertainty Region */ double **ptr2; /* Pointer axis values in "ps2" */ double *cen; /* Pointer to array holding new centre coords */ int ic; /* Axis index */ int nc; /* No. of axis values per point */ int ok; /* Was the new centre found OK? */ int simpler; /* Has some simplication taken place? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the supplied Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Note if any simplification took place. This is assumed to be the case if the pointer returned by the above call is different to the supplied pointer. */ simpler = ( new != this ); /* We attempt to simplify the Ellipse by re-defining it within its current Frame. Transforming the Ellipse from its base to its current Frame may result in the region no longer being an ellipse. We test this by transforming a set of bounds on the Ellipse boundary. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); /* Get a mesh of points covering the Ellipse in its current Frame. */ mesh = astRegMesh( new ); /* Get the Region describing the positional uncertainty within the Ellipse in its current Frame. */ unc = astGetUncFrm( new, AST__CURRENT ); /* Transform the PointSet holding the ellipse centre into the current Frame, and copy the axis values into a new array. */ ps2 = astRegTransform( this, this->points, 1, NULL, NULL ); nc = astGetNcoord( ps2 ); cen = astMalloc( sizeof( double )*(size_t) nc ); ptr2 = astGetPoints( ps2 ); if( astOK ) { ok = 1; for( ic = 0; ic < nc; ic++ ) { cen[ ic ] = ptr2[ ic ][ 0 ]; if( cen[ ic ] == AST__BAD ) ok = 0; } /* Find the best fitting Circle (defined in the current Frame) through these points */ newreg = ok ? astBestCircle( mesh, cen, unc ) : NULL; /* See if all points within this mesh fall on the boundary of the best fitting Circle, to within the uncertainty of the Region. */ if( newreg && astRegPins( newreg, mesh, NULL, NULL ) ) { /* If so, use the new Circle in place of the original Region. */ (void) astAnnul( new ); new = astClone( newreg ); simpler =1; /* Otherwise, if the region is 2-d we see if an Ellipse can represent the mesh. */ } else if( ok && nc == 2 ){ /* Find the best fitting Ellipse (defined in the current Frame) through these points */ if( newreg ) (void) astAnnul( newreg ); newreg = astBestEllipse( mesh, cen, unc ); /* See if all points within this mesh fall on the boundary of the best fitting Ellipse, to within the uncertainty of the Region. */ if( newreg && astRegPins( newreg, mesh, NULL, NULL ) ) { /* If so, use the new Ellipse in place of the original Region. */ (void) astAnnul( new ); new = astClone( newreg ); simpler = 1; } } /* Free resources. */ if( newreg ) newreg = astAnnul( newreg ); } ps2 = astAnnul( ps2 ); cen = astFree( cen ); mesh = astAnnul( mesh ); unc = astAnnul( unc ); map = astAnnul( map ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( simpler ){ astRegOverlay( new, this, 1 ); result = (AstMapping *) new; } else { new = astAnnul( new ); result = astClone( this ); } /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a Ellipse to transform a set of points. * Type: * Private function. * Synopsis: * #include "ellipse.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * Ellipse member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a Ellipse and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the Ellipse. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the Ellipse. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstEllipse *this; /* Pointer to Ellipse */ AstFrame *frm; /* Pointer to base Frame in FrameSet */ AstPointSet *pset_res; /* Pointer to PointSet holding resolved components */ AstPointSet *pset_tmp; /* Pointer to PointSet holding base Frame positions*/ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_out; /* Pointer to output coordinate data */ double **ptr_res; /* Pointer to resolved components coordinate data */ double *px; /* Pointer to array of primary axis components */ double *py; /* Pointer to array of secondary axis components */ double c1; /* Constant */ double c2; /* Constant */ double d; /* Elliptical distance to current point */ int closed; /* Is the boundary part of the Region? */ int coord; /* Zero-based index for coordinates */ int inside; /* Is the point inside the Region? */ int ncoord_out; /* No. of coordinates per output point */ int neg; /* Has the Region been negated? */ int npoint; /* No. of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the Ellipse structure. */ this = (AstEllipse *) this_mapping; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* Ensure cached information is available. */ Cache( this, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* First use the encapsulated FrameSet to transform the supplied positions from the current Frame in the encapsulated FrameSet (the Frame represented by the Region), to the base Frame (the Frame in which the Region is defined). This call also returns a pointer to the base Frame of the encapsulated FrameSet. Note, the returned pointer may be a clone of the "in" pointer, and so we must be carefull not to modify the contents of the returned PointSet. */ pset_tmp = astRegTransform( this, in, 0, NULL, &frm ); /* Resolve all the base Frame positions into components parallel to and perpendicular to the primary axis, relative to the ellipse centre. The components are returned in a new PointSet. */ pset_res = astResolvePoints( frm, this->centre, this->point1, pset_tmp, NULL ); /* Determine the numbers of points from the component PointSet and obtain pointers for accessing the component and output coordinate values. */ npoint = astGetNpoint( pset_res ); ptr_res = astGetPoints( pset_res ); ncoord_out = astGetNcoord( result ); ptr_out = astGetPoints( result ); /* See if the boundary is part of the Region. */ closed = astGetClosed( this ); /* See if the Region has been negated. */ neg = astGetNegated( this ); /* Form some frequently needed constants. */ c1 = 1.0/(this->a*this->a); c2 = 1.0/(this->b*this->b); /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { px = ptr_res[ 0 ]; py = ptr_res[ 1 ]; /* Loop round each point */ for ( point = 0; point < npoint; point++, px++, py++ ) { /* Bad input points result in bad output points */ if( *px == AST__BAD || *py == AST__BAD ) { inside = 0; /* If the input points are good... */ } else { /* Find the elliptical distance from the centre to the supplied point (the ellipse circumference has an "elliptical distance" of 1.0 at all points).*/ d = c1*(*px)*(*px) + c2*(*py)*(*py); /* Now consider whether this radius value puts the point in or out of the Ellipse. */ if( d != AST__BAD ){ if( neg ) { if( closed ) { inside = ( d >= 1.0 ); } else { inside = ( d > 1.0 ); } } else { if( closed ) { inside = ( d <= 1.0 ); } else { inside = ( d < 1.0 ); } } } else { inside = 0; } } /* If the point is outside, store bad output values. */ if( !inside ) { for ( coord = 0; coord < ncoord_out; coord++ ) { ptr_out[ coord ][ point ] = AST__BAD; } } } } /* Free resources */ pset_tmp = astAnnul( pset_tmp ); pset_res = astAnnul( pset_res ); frm = astAnnul( frm ); /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for Ellipse objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for Ellipse 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: */ AstEllipse *in; /* Pointer to input Ellipse */ AstEllipse *out; /* Pointer to output Ellipse */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output Ellipses. */ in = (AstEllipse *) objin; out = (AstEllipse *) objout; /* For safety, first clear any references to the input memory from the output Ellipse. */ out->centre = NULL; out->point1 = NULL; /* Copy dynamic memory contents */ out->centre = astStore( NULL, in->centre, sizeof( double )*2 ); out->point1 = astStore( NULL, in->point1, sizeof( double )*2 ); } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for Ellipse objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for Ellipse 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: */ AstEllipse *this; /* Pointer to Ellipse */ /* Obtain a pointer to the Ellipse structure. */ this = (AstEllipse *) obj; /* Annul all resources. */ this->centre = astFree( this->centre ); this->point1 = astFree( this->point1 ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for Ellipse 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 Ellipse class to an output Channel. * Parameters: * this * Pointer to the Ellipse 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 Variables: */ AstEllipse *this; /* Pointer to the Ellipse structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the Ellipse structure. */ this = (AstEllipse *) this_object; /* Write out values representing the instance variables for the Ellipse 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAEllipse and astCheckEllipse functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(Ellipse,Region) astMAKE_CHECK(Ellipse) AstEllipse *astEllipse_( void *frame_void, int form, const double centre[2], const double point1[2], const double point2[2], AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astEllipse f AST_ELLIPSE * Purpose: * Create a Ellipse. * Type: * Public function. * Synopsis: c #include "ellipse.h" c AstEllipse *astEllipse( AstFrame *frame, int form, const double centre[2], c const double point1[2], const double point2[2], c AstRegion *unc, const char *options, ... ) f RESULT = AST_ELLIPSE( FRAME, FORM, CENTRE, POINT1, POINT2, UNC, OPTIONS, f STATUS ) * Class Membership: * Ellipse constructor. * Description: * This function creates a new Ellipse and optionally initialises its * attributes. * * A Ellipse is a Region which represents a elliptical area within the * supplied 2-dimensional Frame. * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. It must * have exactly 2 axes. A deep copy is taken of the supplied Frame. * This means that any subsequent changes made to the Frame using the * supplied pointer will have no effect the Region. c form f FORM = INTEGER (Given) * Indicates how the ellipse is described by the remaining parameters. * A value of zero indicates that the ellipse is specified by a * centre position and two positions on the circumference. A value of * one indicates that the ellipse is specified by its centre position, * the half-lengths of its two axes, and the orientation of its first * axis. c centre f CENTRE( 2 ) = DOUBLE PRECISION (Given) c An array of 2 doubles, f An array * containing the coordinates at the centre of * the ellipse. c point1 f POINT1( 2 ) = DOUBLE PRECISION (Given) c An array of 2 doubles. If "form" f If FORM * is zero, this array should contain the coordinates of one of the four * points where an axis of the ellipse crosses the circumference of the * ellipse. c If "form" f If FORM * is one, it should contain the lengths of semi-major and * semi-minor axes of the ellipse, given as geodesic distances * within the Frame. c point2 f POINT2( 2 ) = DOUBLE PRECISION (Given) c An array of 2 doubles. If "form" f If FORM * is zero, this array should containing the coordinates at some other * point on the circumference of the ellipse, distinct from c "point1". If "form" f POINT1. If FORM * is one, the first element of this array should hold the angle * between the second axis of the Frame and the first ellipse axis * (i.e. the ellipse axis which is specified first in the c "point1" f POINT1 * array), and the second element will be ignored. The angle should be * given in radians, measured positive in the same sense as rotation * from the positive direction of the second Frame axis to the positive * direction of the first Frame axis. c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with the boundary of the Ellipse being created. * The uncertainty in any point on the boundary of the Ellipse is found by * shifting the supplied "uncertainty" Region so that it is centred at * the boundary point being considered. The area covered by the * shifted uncertainty Region then represents the uncertainty in the * boundary position. The uncertainty is assumed to be the same for * all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created Ellipse. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty is used * equivalent to a box 1.0E-6 of the size of the Ellipse being created. * * The uncertainty Region has two uses: 1) when the c astOverlap f AST_OVERLAP * function compares two Regions for equality the uncertainty * Region is used to determine the tolerance on the comparison, and 2) * when a Region is mapped into a different coordinate system and * subsequently simplified (using c astSimplify), f AST_SIMPLIFY), * the uncertainties are used to determine if the transformed boundary * can be accurately represented by a specific shape of Region. 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 Ellipse. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new Ellipse. The syntax used is identical to that for the f AST_SET routine. 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 astEllipse() f AST_ELLIPSE = INTEGER * A pointer to the new Ellipse. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstEllipse *new; /* Pointer to new Ellipse */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the Ellipse, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitEllipse( NULL, sizeof( AstEllipse ), !class_init, &class_vtab, "Ellipse", frame, form, centre, point1, point2, unc ); /* 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 Ellipse'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 Ellipse. */ return new; } AstEllipse *astEllipseId_( void *frame_void, int form, const double centre[2], const double point1[2], const double point2[2], void *unc_void, const char *options, ... ) { /* * Name: * astEllipseId_ * Purpose: * Create a Ellipse. * Type: * Private function. * Synopsis: * #include "ellipse.h" * AstEllipse *astEllipseId( void *frame_void, int form, const double centre[2], * const double point1[2], const double point2[2], * void *unc_void, const char *options, ..., int *status ) * Class Membership: * Ellipse constructor. * Description: * This function implements the external (public) interface to the * astEllipse constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astEllipse_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astEllipse_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astEllipse_. * status * Pointer to the inherited status variable. * Returned Value: * The ID value associated with the new Ellipse. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstEllipse *new; /* Pointer to new Ellipse */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* 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 NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the Ellipse, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitEllipse( NULL, sizeof( AstEllipse ), !class_init, &class_vtab, "Ellipse", frame, form, centre, point1, point2, unc ); /* 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 Ellipse'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 Ellipse. */ return astMakeId( new ); } AstEllipse *astInitEllipse_( void *mem, size_t size, int init, AstEllipseVtab *vtab, const char *name, AstFrame *frame, int form, const double centre[2], const double point1[2], const double point2[2], AstRegion *unc, int *status ){ /* *+ * Name: * astInitEllipse * Purpose: * Initialise a Ellipse. * Type: * Protected function. * Synopsis: * #include "ellipse.h" * AstEllipse *astInitEllipse( void *mem, size_t size, int init, * AstEllipseVtab *vtab, const char *name, * AstFrame *frame, const double centre[2], * const double point1[2], const double point2[2], * AstRegion *unc ) * Class Membership: * Ellipse initialiser. * Description: * This function is provided for use by class implementations to initialise * a new Ellipse object. It allocates memory (if necessary) to accommodate * the Ellipse plus any additional data associated with the derived class. * It then initialises a Ellipse 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 Ellipse at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the Ellipse is to be initialised. * This must be of sufficient size to accommodate the Ellipse data * (sizeof(Ellipse)) 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 Ellipse (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 Ellipse * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the Ellipse'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 Ellipse. * 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 * A pointer to the Frame in which the region is defined. * form * Indicates how the "point" parameter should be interpreted. * Should be either 0 or 1. * centre * An array of double, with one element for each Frame axis (Naxes * attribute) containing the coordinates of the ellipse centre. * point1 * An array of double, with one element for each Frame axis (Naxes * attribute). If "form" is zero, it should contain the coordinates at * the end of one of the axes of the ellipse. If "form" is one, it * should contain the semi-major and semi-minor axes of the ellipse. * point2 * An array of double, with one element for each Frame axis (Naxes * attribute). If "form" is zero, it should contain the coordinates at * some other point on the circumference of the ellipse. If "form" is * one, element [1] is ignored and element [0] should contain the * angle from the second frame axis to the first ellipse axis, given in * radians, measured positive in the same sense as rotation from the * positive direction of the second Frame axis to the positive * direction of the first Frame axis. The "first" ellipse axis is * whichever of the semi-major or semi-minor axis is specified first in * the "point1" array. * unc * A pointer to a Region which specifies the uncertainty in the * supplied positions (all points on the boundary of the new Ellipse * being initialised are assumed to have the same uncertainty). A NULL * pointer can be supplied, in which case default uncertainties equal to * 1.0E-6 of the dimensions of the new Ellipse's bounding box are used. * If an uncertainty Region is supplied, it must be either a Box, a * Circle or an Ellipse, and its encapsulated Frame must be related * to the Frame supplied for parameter "frame" (i.e. astConvert * should be able to find a Mapping between them). Two positions * the "frame" Frame are considered to be co-incident if their * uncertainty Regions overlap. The centre of the supplied * uncertainty Region is immaterial since it will be re-centred on the * point being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new Ellipse. * 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: */ AstEllipse *new; /* Pointer to new Ellipse */ AstPointSet *pset; /* PointSet to pass to Region initialiser */ double **ptr; /* Pointer to coords data in pset */ const double *p1; /* Pointer to circumference point 1 */ const double *p2; /* Pointer to circumference point 2 */ int i; /* axis index */ int nc; /* No. of axes */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitEllipseVtab( vtab, name ); /* Initialise. */ new = NULL; /* Check the supplied value for "form" is legal. */ if( form != 0 && form != 1 && astOK ) { astError( AST__BADIN, "astInitEllipse(%s): The value supplied for " "parameter \"form\" (%d) is illegal - it should be 0 or 1 " "(programming error).", status, name, form ); } /* Get the number of axis values required for each position. */ nc = astGetNaxes( frame ); /* Report an error if the Frame is not 2-dimensional. */ if( nc != 2 ) { astError( AST__BADIN, "astInitEllipse(%s): The supplied %s has %d " "axes - ellipses must have exactly 2 axes.", status, name, astGetClass( frame ), nc ); } /* If the ellipse is specified by axis lengths and orientation, find two points on the circumference (ends of the two ellipse axes). */ if( form == 1 ) { p1 = astMalloc( sizeof( double )*2 ); p2 = astMalloc( sizeof( double )*2 ); if( astOK ) { astOffset2( frame, centre, *point2, point1[ 0 ], (double *) p1 ); astOffset2( frame, centre, *point2 + AST__DPIBY2, point1[ 1 ], (double *) p2 ); } /* If the ellipse is specified by two points on the circumference, use them. */ } else { p1 = point1; p2 = point2; } /* Create a PointSet to hold the supplied values, and get points to the data arrays. */ pset = astPointSet( 3, nc, " ", status ); ptr = astGetPoints( pset ); /* Copy the supplied coordinates into the PointSet, checking that no bad values have been supplied. */ for( i = 0; astOK && i < nc; i++ ) { if( centre[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitEllipse(%s): The value of axis %d is " "undefined at the ellipse centre.", status, name, i + 1 ); } if( astOK && p1[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitEllipse(%s): The value of axis %d is " "undefined at point 1 on the circumference of " "the ellipse.", status, name, i + 1 ); } if( astOK && p2[ i ] == AST__BAD ) { astError( AST__BADIN, "astInitEllipse(%s): The value of axis %d is " "undefined at point 2 on the circumference of " "the ellipse.", status, name, i + 1 ); } ptr[ i ][ 0 ] = centre[ i ]; ptr[ i ][ 1 ] = p1[ i ]; ptr[ i ][ 2 ] = p2[ i ]; } /* Check pointers can be used safely. */ if( astOK ) { /* Initialise a Region structure (the parent class) as the first component within the Ellipse structure, allocating memory if necessary. */ new = (AstEllipse *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, pset, unc ); if ( astOK ) { /* Initialise the Ellipse data. */ /* ------------------------ */ new->stale = 1; /* If an error occurred, clean up by deleting the new Ellipse. */ if ( !astOK ) new = astDelete( new ); } } /* Free resources. */ pset = astAnnul( pset ); if( form == 1 ) { p1 = astFree( (void *) p1 ); p2 = astFree( (void *) p2 ); } /* Return a pointer to the new Ellipse. */ return new; } AstEllipse *astLoadEllipse_( void *mem, size_t size, AstEllipseVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadEllipse * Purpose: * Load a Ellipse. * Type: * Protected function. * Synopsis: * #include "ellipse.h" * AstEllipse *astLoadEllipse( void *mem, size_t size, AstEllipseVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * Ellipse loader. * Description: * This function is provided to load a new Ellipse 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 * Ellipse structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a Ellipse at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the Ellipse is to be * loaded. This must be of sufficient size to accommodate the * Ellipse data (sizeof(Ellipse)) 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 Ellipse (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 Ellipse 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(AstEllipse) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new Ellipse. If this is NULL, a pointer * to the (static) virtual function table for the Ellipse 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 "Ellipse" is used instead. * Returned Value: * A pointer to the new Ellipse. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstEllipse *new; /* Pointer to the new Ellipse */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this Ellipse. In this case the Ellipse belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstEllipse ); vtab = &class_vtab; name = "Ellipse"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitEllipseVtab( 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 Ellipse. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "Ellipse" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* Indicate that no cache intermediate results are yet available in the Ellipse structure */ new->stale = 1; /* If an error occurred, clean up by deleting the new Ellipse. */ if ( !astOK ) new = astDelete( new ); } /* Return the new Ellipse pointer. */ return new; } /* 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 astEllipsePars_( AstEllipse *this, double centre[2], double *a, double *b, double *angle, double p1[2], double p2[2], int *status ){ if ( !astOK ) return; (**astMEMBER(this,Ellipse,EllipsePars))( this, centre, a, b, angle, p1, p2, status ); } ast-8.3.0/AST_ERR0000664000175000017500000004143013004147334010317 00000000000000* FORTRAN error include file for facility AST (Code 1521) * Generated by the MESSGEN utility * attribute getting error INTEGER AST__ATGER PARAMETER ( AST__ATGER = 233933154 ) * attribute setting error INTEGER AST__ATSER PARAMETER ( AST__ATSER = 233933162 ) * attribute value invalid INTEGER AST__ATTIN PARAMETER ( AST__ATTIN = 233933170 ) * axis index invalid INTEGER AST__AXIIN PARAMETER ( AST__AXIIN = 233933178 ) * bad attribute name INTEGER AST__BADAT PARAMETER ( AST__BADAT = 233933186 ) * zero-sized box given INTEGER AST__BADBX PARAMETER ( AST__BADBX = 233933194 ) * bad input data INTEGER AST__BADIN PARAMETER ( AST__BADIN = 233933202 ) * bad number of input coordinates INTEGER AST__BADNI PARAMETER ( AST__BADNI = 233933210 ) * bad number of output coordinates INTEGER AST__BADNO PARAMETER ( AST__BADNO = 233933218 ) * PolyMap contains illegal power value INTEGER AST__BADPW PARAMETER ( AST__BADPW = 233933226 ) * ShiftMap contains no shift information INTEGER AST__BADSM PARAMETER ( AST__BADSM = 233933234 ) * WinMap contains no bounds information INTEGER AST__BADWM PARAMETER ( AST__BADWM = 233933242 ) * bad break index INTEGER AST__BDBRK PARAMETER ( AST__BDBRK = 233933250 ) * bad field specifier INTEGER AST__BDFMT PARAMETER ( AST__BDFMT = 233933258 ) * invalid FITS keyword value found INTEGER AST__BDFTS PARAMETER ( AST__BDFTS = 233933266 ) * inappropriate Object supplied INTEGER AST__BDOBJ PARAMETER ( AST__BDOBJ = 233933274 ) * wrong number of clipping axes INTEGER AST__CLPAX PARAMETER ( AST__CLPAX = 233933282 ) * range of coordinates invalid INTEGER AST__CORNG PARAMETER ( AST__CORNG = 233933290 ) * too many breaks in a curve INTEGER AST__CVBRK PARAMETER ( AST__CVBRK = 233933298 ) * array dimensions invalid INTEGER AST__DIMIN PARAMETER ( AST__DIMIN = 233933306 ) * date/time error INTEGER AST__DTERR PARAMETER ( AST__DTERR = 233933314 ) * invalid use of astEnd INTEGER AST__ENDIN PARAMETER ( AST__ENDIN = 233933322 ) * end of input Channel encountered INTEGER AST__EOCHN PARAMETER ( AST__EOCHN = 233933330 ) * attempt to export Object pointer from level zero INTEGER AST__EXPIN PARAMETER ( AST__EXPIN = 233933338 ) * corrupted FitsChan supplied INTEGER AST__FCRPT PARAMETER ( AST__FCRPT = 233933346 ) * error while formatting coordinate value INTEGER AST__FMTER PARAMETER ( AST__FMTER = 233933354 ) * Frame index invalid INTEGER AST__FRMIN PARAMETER ( AST__FRMIN = 233933362 ) * FrameSet invalid INTEGER AST__FRSIN PARAMETER ( AST__FRSIN = 233933370 ) * cannot convert FITS data value type INTEGER AST__FTCNV PARAMETER ( AST__FTCNV = 233933378 ) * low level graphics error INTEGER AST__GRFER PARAMETER ( AST__GRFER = 233933386 ) * invalid Handle INTEGER AST__INHAN PARAMETER ( AST__INHAN = 233933394 ) * incompatible numbers of coordinates INTEGER AST__INNCO PARAMETER ( AST__INNCO = 233933402 ) * internal programming error INTEGER AST__INTER PARAMETER ( AST__INTER = 233933410 ) * incompatible transformation directions INTEGER AST__INTRD PARAMETER ( AST__INTRD = 233933418 ) * circular dependency between KeyMaps INTEGER AST__KYCIR PARAMETER ( AST__KYCIR = 233933426 ) * class loader error INTEGER AST__LDERR PARAMETER ( AST__LDERR = 233933434 ) * invalid lookup table increment INTEGER AST__LUTII PARAMETER ( AST__LUTII = 233933442 ) * invalid number of lookup table elements INTEGER AST__LUTIN PARAMETER ( AST__LUTIN = 233933450 ) * requested memory size invalid INTEGER AST__MEMIN PARAMETER ( AST__MEMIN = 233933458 ) * not a 2d or 3d MatrixMap INTEGER AST__MTR23 PARAMETER ( AST__MTR23 = 233933466 ) * null rotation axis supplied INTEGER AST__MTRAX PARAMETER ( AST__MTRAX = 233933474 ) * bad matrix shapes for multiplication INTEGER AST__MTRML PARAMETER ( AST__MTRML = 233933482 ) * null matrix supplied INTEGER AST__MTRMT PARAMETER ( AST__MTRMT = 233933490 ) * number of axes invalid INTEGER AST__NAXIN PARAMETER ( AST__NAXIN = 233933498 ) * number of characters invalid INTEGER AST__NCHIN PARAMETER ( AST__NCHIN = 233933506 ) * number of coordinates invalid INTEGER AST__NCOIN PARAMETER ( AST__NCOIN = 233933514 ) * number of coordinates per point invalid INTEGER AST__NCPIN PARAMETER ( AST__NCPIN = 233933522 ) * number of array elements invalid INTEGER AST__NELIN PARAMETER ( AST__NELIN = 233933530 ) * number of output coordinates too small INTEGER AST__NOCTS PARAMETER ( AST__NOCTS = 233933538 ) * transformation not defined INTEGER AST__NODEF PARAMETER ( AST__NODEF = 233933546 ) * required FITS keywords missing INTEGER AST__NOFTS PARAMETER ( AST__NOFTS = 233933554 ) * unable to allocate memory INTEGER AST__NOMEM PARAMETER ( AST__NOMEM = 233933562 ) * number of output points too small INTEGER AST__NOPTS PARAMETER ( AST__NOPTS = 233933570 ) * attribute is read-only INTEGER AST__NOWRT PARAMETER ( AST__NOWRT = 233933578 ) * number of points invalid INTEGER AST__NPTIN PARAMETER ( AST__NPTIN = 233933586 ) * Object invalid INTEGER AST__OBJIN PARAMETER ( AST__OBJIN = 233933594 ) * invalid Plot option INTEGER AST__OPT PARAMETER ( AST__OPT = 233933602 ) * points data structure invalid INTEGER AST__PDSIN PARAMETER ( AST__PDSIN = 233933610 ) * no numerical labels can be produced INTEGER AST__PLFMT PARAMETER ( AST__PLFMT = 233933618 ) * permutation invalid INTEGER AST__PRMIN PARAMETER ( AST__PRMIN = 233933626 ) * pointer invalid INTEGER AST__PTRIN PARAMETER ( AST__PTRIN = 233933634 ) * range of points invalid INTEGER AST__PTRNG PARAMETER ( AST__PTRNG = 233933642 ) * read error INTEGER AST__RDERR PARAMETER ( AST__RDERR = 233933650 ) * invalid or corrupted Region structure supplied INTEGER AST__REGIN PARAMETER ( AST__REGIN = 233933658 ) * invalid attempt to remove last Frame INTEGER AST__REMIN PARAMETER ( AST__REMIN = 233933666 ) * sky coordinate system invalid INTEGER AST__SCSIN PARAMETER ( AST__SCSIN = 233933674 ) * axis selection invalid INTEGER AST__SELIN PARAMETER ( AST__SELIN = 233933682 ) * bad SLALIB transformation type INTEGER AST__SLAIN PARAMETER ( AST__SLAIN = 233933690 ) * coordinate transformation not defined INTEGER AST__TRNND PARAMETER ( AST__TRNND = 233933698 ) * unmatched quotes INTEGER AST__UNMQT PARAMETER ( AST__UNMQT = 233933706 ) * valid area too small INTEGER AST__VSMAL PARAMETER ( AST__VSMAL = 233933714 ) * non-existent longitude or latitude axis INTEGER AST__WCSAX PARAMETER ( AST__WCSAX = 233933722 ) * too few mapping coordinates INTEGER AST__WCSNC PARAMETER ( AST__WCSNC = 233933730 ) * invalid projection parameters INTEGER AST__WCSPA PARAMETER ( AST__WCSPA = 233933738 ) * unknown projection type INTEGER AST__WCSTY PARAMETER ( AST__WCSTY = 233933746 ) * too many Objects in use at once INTEGER AST__XSOBJ PARAMETER ( AST__XSOBJ = 233933754 ) * zoom factor invalid INTEGER AST__ZOOMI PARAMETER ( AST__ZOOMI = 233933762 ) * bad coordinate index INTEGER AST__BADCI PARAMETER ( AST__BADCI = 233933770 ) * FrameSet integrity lost INTEGER AST__ILOST PARAMETER ( AST__ILOST = 233933778 ) * error in IntraMap transformation function INTEGER AST__ITFER PARAMETER ( AST__ITFER = 233933786 ) * IntraMap transformation function name invalid INTEGER AST__ITFNI PARAMETER ( AST__ITFNI = 233933794 ) * Mapping bounding box not found INTEGER AST__MBBNF PARAMETER ( AST__MBBNF = 233933802 ) * multiple registration of IntraMap transformation function INTEGER AST__MRITF PARAMETER ( AST__MRITF = 233933810 ) * Object class unknown INTEGER AST__OCLUK PARAMETER ( AST__OCLUK = 233933818 ) * error while unformatting a coordinate value INTEGER AST__UNFER PARAMETER ( AST__UNFER = 233933826 ) * unregistered IntraMap transformation function INTEGER AST__URITF PARAMETER ( AST__URITF = 233933834 ) * grid bounds invalid INTEGER AST__GBDIN PARAMETER ( AST__GBDIN = 233933842 ) * number of grid dimensions invalid INTEGER AST__NGDIN PARAMETER ( AST__NGDIN = 233933850 ) * positional accuracy tolerance invalid INTEGER AST__PATIN PARAMETER ( AST__PATIN = 233933858 ) * sub-pixel interpolation scheme invalid INTEGER AST__SISIN PARAMETER ( AST__SISIN = 233933866 ) * scale size in pixels invalid INTEGER AST__SSPIN PARAMETER ( AST__SSPIN = 233933874 ) * error in user-supplied sub-pixel interpolation function INTEGER AST__UINER PARAMETER ( AST__UINER = 233933882 ) * error in user-supplied 1-d sub-pixel interpolation kernel INTEGER AST__UK1ER PARAMETER ( AST__UK1ER = 233933890 ) * invalid comma in expression INTEGER AST__COMIN PARAMETER ( AST__COMIN = 233933898 ) * invalid constant in expression INTEGER AST__CONIN PARAMETER ( AST__CONIN = 233933906 ) * duplicate variable name INTEGER AST__DUVAR PARAMETER ( AST__DUVAR = 233933914 ) * invalid number of transformation functions INTEGER AST__INNTF PARAMETER ( AST__INNTF = 233933922 ) * missing or invalid operand in expression INTEGER AST__MIOPA PARAMETER ( AST__MIOPA = 233933930 ) * missing or invalid operator in expression INTEGER AST__MIOPR PARAMETER ( AST__MIOPR = 233933938 ) * missing variable name INTEGER AST__MISVN PARAMETER ( AST__MISVN = 233933946 ) * missing left parenthesis in expression INTEGER AST__MLPAR PARAMETER ( AST__MLPAR = 233933954 ) * missing right parenthesis in expression INTEGER AST__MRPAR PARAMETER ( AST__MRPAR = 233933962 ) * missing right hand side in function INTEGER AST__NORHS PARAMETER ( AST__NORHS = 233933970 ) * undefined variable or function in expression INTEGER AST__UDVOF PARAMETER ( AST__UDVOF = 233933978 ) * variable name invalid INTEGER AST__VARIN PARAMETER ( AST__VARIN = 233933986 ) * wrong number of function arguments in expression INTEGER AST__WRNFA PARAMETER ( AST__WRNFA = 233933994 ) * invalid units specification INTEGER AST__BADUN PARAMETER ( AST__BADUN = 233934002 ) * no rest frequency is defined INTEGER AST__NORSF PARAMETER ( AST__NORSF = 233934010 ) * no standard of rest is defined INTEGER AST__NOSOR PARAMETER ( AST__NOSOR = 233934018 ) * invalid SpecMap INTEGER AST__SPCIN PARAMETER ( AST__SPCIN = 233934026 ) * invalid XML name or prefix INTEGER AST__XMLNM PARAMETER ( AST__XMLNM = 233934034 ) * invalid XML comment text INTEGER AST__XMLCM PARAMETER ( AST__XMLCM = 233934042 ) * invalid XML processing instruction target text INTEGER AST__XMLPT PARAMETER ( AST__XMLPT = 233934050 ) * invalid XML content item index INTEGER AST__XMLIT PARAMETER ( AST__XMLIT = 233934058 ) * supplied XML document is not well formed INTEGER AST__XMLWF PARAMETER ( AST__XMLWF = 233934066 ) * Range of log axis scale includes zero INTEGER AST__ZERAX PARAMETER ( AST__ZERAX = 233934074 ) * Invalid parameters for offset sky coordinate system INTEGER AST__BADOC PARAMETER ( AST__BADOC = 233934082 ) * error getting a named value from a KeyMap INTEGER AST__MPGER PARAMETER ( AST__MPGER = 233934090 ) * invalid integer index supplied for a KeyMap entry INTEGER AST__MPIND PARAMETER ( AST__MPIND = 233934098 ) * region cannot be re-centred INTEGER AST__REGCN PARAMETER ( AST__REGCN = 233934106 ) * attribute has no usable value INTEGER AST__NOVAL PARAMETER ( AST__NOVAL = 233934114 ) * incompatible time scales INTEGER AST__INCTS PARAMETER ( AST__INCTS = 233934122 ) * invalid TimeMap INTEGER AST__TIMIN PARAMETER ( AST__TIMIN = 233934130 ) * cannot use supplied AstroCoords info INTEGER AST__STCKEY PARAMETER ( AST__STCKEY = 233934138 ) * invalid AstroCoords index INTEGER AST__STCIND PARAMETER ( AST__STCIND = 233934146 ) * cannot conserve flux whilst resampling an array of data INTEGER AST__CNFLX PARAMETER ( AST__CNFLX = 233934154 ) * Unknown AST tuning parameter name supplied INTEGER AST__TUNAM PARAMETER ( AST__TUNAM = 233934162 ) * Bad value supplied for a public function parameter INTEGER AST__BDPAR PARAMETER ( AST__BDPAR = 233934170 ) * Supplied FrameSet does not contain any independent axes INTEGER AST__3DFSET PARAMETER ( AST__3DFSET = 233934178 ) * Attempt to delete original Plot3D base Frame INTEGER AST__PXFRRM PARAMETER ( AST__PXFRRM = 233934186 ) * Illegal syntax for string substitution template INTEGER AST__BADSUB PARAMETER ( AST__BADSUB = 233934194 ) * Incompatible flags for re-sampling or re-binning INTEGER AST__BADFLG PARAMETER ( AST__BADFLG = 233934202 ) * Error locking or unlocking an AST Object INTEGER AST__LCKERR PARAMETER ( AST__LCKERR = 233934210 ) * FITS keyword had undefined value INTEGER AST__FUNDEF PARAMETER ( AST__FUNDEF = 233934218 ) * invalid integer index supplied for a KeyMap vector element INTEGER AST__MPVIN PARAMETER ( AST__MPVIN = 233934226 ) * operation specifier invalid INTEGER AST__OPRIN PARAMETER ( AST__OPRIN = 233934234 ) * no inside point found INTEGER AST__NONIN PARAMETER ( AST__NONIN = 233934242 ) * requested key not found in KeyMap INTEGER AST__MPKER PARAMETER ( AST__MPKER = 233934250 ) * error putting a named value into a KeyMap INTEGER AST__MPPER PARAMETER ( AST__MPPER = 233934258 ) * Attempt made to add an entry to a locked KeyMap INTEGER AST__BADKEY PARAMETER ( AST__BADKEY = 233934266 ) * Bad data type INTEGER AST__BADTYP PARAMETER ( AST__BADTYP = 233934274 ) * Column already exists with different properties INTEGER AST__OLDCOL PARAMETER ( AST__OLDCOL = 233934282 ) * Bad null value for a FITS table column INTEGER AST__BADNULL PARAMETER ( AST__BADNULL = 233934290 ) * Key string is too long INTEGER AST__BIGKEY PARAMETER ( AST__BIGKEY = 233934298 ) * No such column exists in the table INTEGER AST__BADCOL PARAMETER ( AST__BADCOL = 233934306 ) * Table is too large INTEGER AST__BIGTAB PARAMETER ( AST__BIGTAB = 233934314 ) * Invalid array size INTEGER AST__BADSIZ PARAMETER ( AST__BADSIZ = 233934322 ) * Error reading WCS from FITS binary table INTEGER AST__BADTAB PARAMETER ( AST__BADTAB = 233934330 ) * Cannot access FITS binary table INTEGER AST__NOTAB PARAMETER ( AST__NOTAB = 233934338 ) * Error in levmar Levenberg-Marquardt code INTEGER AST__LEVMAR PARAMETER ( AST__LEVMAR = 233934346 ) * Fit failed INTEGER AST__NOFIT PARAMETER ( AST__NOFIT = 233934354 ) * A transformation generated one or more NaN values INTEGER AST__ISNAN PARAMETER ( AST__ISNAN = 233934362 ) * write error INTEGER AST__WRERR PARAMETER ( AST__WRERR = 233934370 ) * Bad variant Mapping name INTEGER AST__BDVNM PARAMETER ( AST__BDVNM = 233934378 ) * Attempt to add a variant Mapping to a mirror Frame INTEGER AST__MIRRO PARAMETER ( AST__MIRRO = 233934386 ) * Error in cminpack Levenberg-Marquardt code INTEGER AST__MNPCK PARAMETER ( AST__MNPCK = 233934394 ) * Supplied array has too many pixels INTEGER AST__EXSPIX PARAMETER ( AST__EXSPIX = 233934402 ) * No mapping found between coordinate systems INTEGER AST__NOCNV PARAMETER ( AST__NOCNV = 233934410 ) * Attempt to change an immutable attribute INTEGER AST__IMMUT PARAMETER ( AST__IMMUT = 233934418 ) ast-8.3.0/Makefile.am0000664000175000017500000005037213004147320011271 00000000000000## Process this file with automake to produce Makefile.in # First declare various groups of files. These were initially extracted # from the grp.make file, as constructed by the SDT newdev command GRP_C_ROUTINES = \ axis.c \ box.c \ channel.c \ circle.c \ cmpframe.c \ cmpmap.c \ cmpregion.c \ dsbspecframe.c \ dssmap.c \ ellipse.c \ error.c \ fitschan.c \ fitstable.c \ fluxframe.c \ frame.c \ frameset.c \ globals.c \ grismmap.c \ interval.c \ intramap.c \ keymap.c \ loader.c \ lutmap.c \ mapping.c \ mathmap.c \ matrixmap.c \ memory.c \ normmap.c \ nullregion.c \ object.c \ pcdmap.c \ permmap.c \ plot.c \ plot3d.c \ pointlist.c \ pointset.c \ polygon.c \ polymap.c \ prism.c \ ratemap.c \ region.c \ selectormap.c \ shiftmap.c \ skyaxis.c \ skyframe.c \ slamap.c \ specfluxframe.c \ specframe.c \ specmap.c \ sphmap.c \ stc.c \ stccatalogentrylocation.c \ stcobsdatalocation.c \ stcresourceprofile.c \ stcschan.c \ stcsearchlocation.c \ switchmap.c \ table.c \ timeframe.c \ timemap.c \ tranmap.c \ unit.c \ unitmap.c \ unitnormmap.c \ wcsmap.c \ winmap.c \ xml.c \ xmlchan.c \ zoommap.c # The C source files required for the Fortran interface if !NOFORTRAN F_C_ROUTINES = \ c2f77.c \ fbox.c \ fchannel.c \ fcircle.c \ fcmpframe.c \ fcmpmap.c \ fcmpregion.c \ fdsbspecframe.c \ fdssmap.c \ fellipse.c \ ferror.c \ ffitschan.c \ ffitstable.c \ ffluxframe.c \ fframe.c \ fframeset.c \ fgrismmap.c \ finterval.c \ fintramap.c \ fkeymap.c \ flutmap.c \ fmapping.c \ fmathmap.c \ fmatrixmap.c \ fnormmap.c \ fnullregion.c \ fobject.c \ fpcdmap.c \ fpermmap.c \ fplot.c \ fplot3d.c \ fpointlist.c \ fpolygon.c \ fpolymap.c \ fprism.c \ fratemap.c \ fregion.c \ fselectormap.c \ fshiftmap.c \ fskyframe.c \ fslamap.c \ fspecfluxframe.c \ fspecframe.c \ fspecmap.c \ fsphmap.c \ fstc.c \ fstccatalogentrylocation.c \ fstcobsdatalocation.c \ fstcresourceprofile.c \ fstcschan.c \ fstcsearchlocation.c \ fswitchmap.c \ ftable.c \ ftimeframe.c \ ftimemap.c \ ftranmap.c \ funitmap.c \ funitnormmap.c \ fwcsmap.c \ fwinmap.c \ fxmlchan.c \ fzoommap.c else F_C_ROUTINES = endif # Header files which contribute to the "ast.h" file, organised to correspond # with the class hierarchy. AST_H_FILES = \ xml.h \ wcstrig.h \ proj.h \ memory.h \ error.h \ globals.h \ unit.h \ ast_err.h \ version.h \ object.h \ keymap.h \ table.h \ fitstable.h \ pointset.h \ axis.h \ skyaxis.h \ mapping.h \ cmpmap.h \ dssmap.h \ grismmap.h \ intramap.h \ lutmap.h \ mathmap.h \ matrixmap.h \ pcdmap.h \ permmap.h \ polymap.h \ ratemap.h \ normmap.h \ shiftmap.h \ slamap.h \ specmap.h \ sphmap.h \ timemap.h \ selectormap.h \ switchmap.h \ tranmap.h \ unitmap.h \ unitnormmap.h \ wcsmap.h \ winmap.h \ zoommap.h \ frame.h \ cmpframe.h \ specfluxframe.h \ fluxframe.h \ frameset.h \ plot.h \ plot3d.h \ skyframe.h \ specframe.h \ dsbspecframe.h \ region.h \ box.h \ circle.h \ cmpregion.h \ ellipse.h \ interval.h \ nullregion.h \ pointlist.h \ polygon.h \ prism.h \ stc.h \ stcresourceprofile.h \ stcsearchlocation.h \ stccatalogentrylocation.h \ stcobsdatalocation.h \ timeframe.h \ channel.h \ fitschan.h \ stcschan.h \ xmlchan.h # All the (C) include files required to build the library. GRP_C_INCLUDE_FILES = \ $(AST_H_FILES) \ ems.h \ err.h \ Ers.h \ f77.h \ grf.h \ grf3d.h \ pg3d.h \ loader.h \ pal2ast.h \ skyaxis.h \ erfa2ast.h \ stc.h \ stcresourceprofile.h \ stcsearchlocation.h \ stccatalogentrylocation.h \ stcobsdatalocation.h \ wcsmath.h \ wcstrig.h \ xmlchan.h if !NOFORTRAN F_C_INCLUDE_FILES = \ c2f77.h # The following list should include AST_PAR, but that must not be # distributed, and so it is listed separately in # nodist_libast_la_SOURCES below. GRP_F_INCLUDE_FILES = \ GRF_PAR \ AST_ERR else F_C_INCLUDE_FILES = GRP_F_INCLUDE_FILES = endif # If we have no Fortran we are not building f77.h and we probably # do not want a Fortran runtime. This requires that PGPLOT is disabled. # We replace it with the stub GRF interface. An alternative would # be to have the PGPLOT wrappers use a preprocessor symbol to build # the pgplot to always error if used. if !NOFORTRAN GRF_PGPLOT_SOURCES = \ grf_pgplot.c GRF3D_PGPLOT_SOURCES = \ grf3d_pgplot.c else GRF_PGPLOT_SOURCES = \ grf_5.6.c GRF3D_PGPLOT_SOURCES = \ grf3d.c endif ## Following declaration isn't used ## LATEX_DOCUMENTATION_FILES = \ ## sun210.tex \ ## sun211.tex DOCUMENTATION_PRODUCTS = $(PAPER_DOCUMENTATION) $(HYPER_DOCUMENTATION) PAPER_DOCUMENTATION = sun210.tex sun211.tex sun210.pdf sun211.pdf HYPER_DOCUMENTATION = sun210.htx_tar sun211.htx_tar PDF_FIGURES = \ cmpframe.pdf \ complex.pdf \ frames.pdf \ frameset.pdf \ fronta.pdf \ fronta_bw.pdf \ frontb.pdf \ frontb_bw.pdf \ frontc.pdf \ frontc_bw.pdf \ fsalign.pdf \ fsconvert.pdf \ fsexample.pdf \ fsmerge.pdf \ fsremap.pdf \ gridplot.pdf \ gridplot_bw.pdf \ mapping.pdf \ overgrid.pdf \ overgrid_bw.pdf \ parallel.pdf \ series.pdf \ simpexamp.pdf WCSLIB_FILES = \ proj.c \ tpn.c \ proj.h \ wcstrig.c \ wcsmath.h \ wcstrig.h STAR_PAL_FILES = \ pal/pal.h \ pal/palAddet.c \ pal/palAmpqk.c \ pal/palCaldj.c \ pal/palDat.c \ pal/palDe2h.c \ pal/palDeuler.c \ pal/palDh2e.c \ pal/palDjcal.c \ pal/palDmat.c \ pal/palDrange.c \ pal/palDs2tp.c \ pal/palDtp2s.c \ pal/palDtps2c.c \ pal/palDtt.c \ pal/palEcmat.c \ pal/palEqgal.c \ pal/palEtrms.c \ pal/palEvp.c \ pal/palFk45z.c \ pal/palFk524.c \ pal/palFk54z.c \ pal/palGaleq.c \ pal/palGalsup.c \ pal/palMappa.c \ pal/palMapqkz.c \ pal/palOne2One.c \ pal/palPrebn.c \ pal/palPrec.c \ pal/palPrenut.c \ pal/palPvobs.c \ pal/palRvgalc.c \ pal/palRvlg.c \ pal/palRvlsrd.c \ pal/palRvlsrk.c \ pal/palSubet.c \ pal/palSupgal.c \ pal/pal1sofa.h \ pal/palmac.h ERFA_FILES = \ erfa/00READ.ME \ erfa/erfa.h \ erfa/erfam.h \ erfa/a2af.c \ erfa/a2tf.c \ erfa/af2a.c \ erfa/anp.c \ erfa/anpm.c \ erfa/bi00.c \ erfa/bp00.c \ erfa/bp06.c \ erfa/bpn2xy.c \ erfa/c2i00a.c \ erfa/c2i00b.c \ erfa/c2i06a.c \ erfa/c2ibpn.c \ erfa/c2ixy.c \ erfa/c2ixys.c \ erfa/c2s.c \ erfa/c2t00a.c \ erfa/c2t00b.c \ erfa/c2t06a.c \ erfa/c2tcio.c \ erfa/c2teqx.c \ erfa/c2tpe.c \ erfa/c2txy.c \ erfa/cal2jd.c \ erfa/cp.c \ erfa/cpv.c \ erfa/cr.c \ erfa/d2dtf.c \ erfa/d2tf.c \ erfa/dat.c \ erfa/dtdb.c \ erfa/dtf2d.c \ erfa/ee00.c \ erfa/ee00a.c \ erfa/ee00b.c \ erfa/ee06a.c \ erfa/eect00.c \ erfa/eform.c \ erfa/eo06a.c \ erfa/eors.c \ erfa/epb.c \ erfa/epb2jd.c \ erfa/epj.c \ erfa/epj2jd.c \ erfa/epv00.c \ erfa/eqeq94.c \ erfa/era00.c \ erfa/fad03.c \ erfa/fae03.c \ erfa/faf03.c \ erfa/faju03.c \ erfa/fal03.c \ erfa/falp03.c \ erfa/fama03.c \ erfa/fame03.c \ erfa/fane03.c \ erfa/faom03.c \ erfa/fapa03.c \ erfa/fasa03.c \ erfa/faur03.c \ erfa/fave03.c \ erfa/fk52h.c \ erfa/fk5hip.c \ erfa/fk5hz.c \ erfa/fw2m.c \ erfa/fw2xy.c \ erfa/gc2gd.c \ erfa/gc2gde.c \ erfa/gd2gc.c \ erfa/gd2gce.c \ erfa/gmst00.c \ erfa/gmst06.c \ erfa/gmst82.c \ erfa/gst00a.c \ erfa/gst00b.c \ erfa/gst06.c \ erfa/gst06a.c \ erfa/gst94.c \ erfa/h2fk5.c \ erfa/hfk5z.c \ erfa/ir.c \ erfa/jd2cal.c \ erfa/jdcalf.c \ erfa/num00a.c \ erfa/num00b.c \ erfa/num06a.c \ erfa/numat.c \ erfa/nut00a.c \ erfa/nut00b.c \ erfa/nut06a.c \ erfa/nut80.c \ erfa/nutm80.c \ erfa/obl06.c \ erfa/obl80.c \ erfa/p06e.c \ erfa/p2pv.c \ erfa/p2s.c \ erfa/pap.c \ erfa/pas.c \ erfa/pb06.c \ erfa/pdp.c \ erfa/pfw06.c \ erfa/plan94.c \ erfa/pm.c \ erfa/pmat00.c \ erfa/pmat06.c \ erfa/pmat76.c \ erfa/pmp.c \ erfa/pn.c \ erfa/pn00.c \ erfa/pn00a.c \ erfa/pn00b.c \ erfa/pn06.c \ erfa/pn06a.c \ erfa/pnm00a.c \ erfa/pnm00b.c \ erfa/pnm06a.c \ erfa/pnm80.c \ erfa/pom00.c \ erfa/ppp.c \ erfa/ppsp.c \ erfa/pr00.c \ erfa/prec76.c \ erfa/pv2p.c \ erfa/pv2s.c \ erfa/pvdpv.c \ erfa/pvm.c \ erfa/pvmpv.c \ erfa/pvppv.c \ erfa/pvstar.c \ erfa/pvu.c \ erfa/pvup.c \ erfa/pvxpv.c \ erfa/pxp.c \ erfa/refco.c \ erfa/rm2v.c \ erfa/rv2m.c \ erfa/rx.c \ erfa/rxp.c \ erfa/rxpv.c \ erfa/rxr.c \ erfa/ry.c \ erfa/rz.c \ erfa/s00.c \ erfa/s00a.c \ erfa/s00b.c \ erfa/s06.c \ erfa/s06a.c \ erfa/s2c.c \ erfa/s2p.c \ erfa/s2pv.c \ erfa/s2xpv.c \ erfa/sepp.c \ erfa/seps.c \ erfa/sp00.c \ erfa/starpm.c \ erfa/starpv.c \ erfa/sxp.c \ erfa/sxpv.c \ erfa/taitt.c \ erfa/taiut1.c \ erfa/taiutc.c \ erfa/tcbtdb.c \ erfa/tcgtt.c \ erfa/tdbtcb.c \ erfa/tdbtt.c \ erfa/tf2a.c \ erfa/tf2d.c \ erfa/tr.c \ erfa/trxp.c \ erfa/trxpv.c \ erfa/tttai.c \ erfa/tttcg.c \ erfa/tttdb.c \ erfa/ttut1.c \ erfa/ut1tai.c \ erfa/ut1tt.c \ erfa/ut1utc.c \ erfa/utctai.c \ erfa/utcut1.c \ erfa/xy06.c \ erfa/xys00a.c \ erfa/xys00b.c \ erfa/xys06a.c \ erfa/zp.c \ erfa/zpv.c \ erfa/zr.c PAL_FILES = \ palwrap.c \ pal.h \ erfa.h \ erfam.h CMINPACK_FILES = \ cminpack/cminpack.h \ cminpack/cminpackP.h \ cminpack/lmder1.c \ cminpack/lmder.c \ cminpack/dpmpar.c \ cminpack/enorm.c \ cminpack/qrfac.c \ cminpack/lmpar.c \ cminpack/qrsolv.c bin_SCRIPTS = ast_link dist_bin_SCRIPTS = ast_link_adam noinst_SCRIPTS = ast_cpp dist_noinst_SCRIPTS = makeh # Scripts are not distributed by default (since they might be derived objects) # Add these to the distribution below. In fact, it would be useful # and straightforward to make ast_link{,_adam} derived, since they # could then have installation directories painlessly edited in to # them. This might be a requirement for scripts which supported # linking against shared libraries. # Headers required by library users. Both of the following lines # indicate headers which are installed. include_HEADERS = GRF_PAR grf.h grf3d.h # Following are generated, so should not be distributed. nodist_include_HEADERS = ast.h AST_PAR include_MESSAGES = AST_ERR ast_err.h if EXTERNAL_PAL PAL_LIB = else PAL_LIB = libast_pal.la endif lib_LTLIBRARIES = \ $(PAL_LIB) \ libast.la \ libast_err.la \ libast_ems.la \ libast_drama.la \ libast_grf3d.la \ libast_grf_2.0.la \ libast_grf_3.2.la \ libast_grf_5.6.la \ libast_pgplot.la \ libast_pgplot3d.la stardocs_DATA = @STAR_LATEX_DOCUMENTATION@ dist_starnews_DATA = ast.news dist_pkgdata_DATA = COPYING COPYING.LESSER COPYING.LIB # Make all library code position independent by default. This is handy for # creating shareable libraries from the static ones (Java JNI libraries). # Note we do not simply set the AM_CFLAGS variable, as this would also # apply to programs compiled without using libtool, possibly causing the # compilation to fail. if !NOTHREADS if !NOPIC libast_la_CFLAGS = $(AM_CFLAGS) -prefer-pic -DTHREAD_SAFE else libast_la_CFLAGS = $(AM_CFLAGS) -DTHREAD_SAFE endif else libast_la_CFLAGS = $(AM_CFLAGS) -prefer-pic endif if !NOPIC libast_err_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_ems_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_drama_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_grf3d_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_grf_2_0_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_grf_3_2_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_grf_5_6_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_pgplot_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_pgplot3d_la_CFLAGS = $(AM_CFLAGS) -prefer-pic libast_pal_la_CFLAGS = $(AM_CFLAGS) -prefer-pic endif # The module containing the main AST classes libast_la_SOURCES = \ $(GRP_C_ROUTINES) \ $(F_C_ROUTINES) \ $(GRP_C_INCLUDE_FILES) \ $(F_C_INCLUDE_FILES) \ $(GRP_F_INCLUDE_FILES) \ $(CMINPACK_FILES) \ $(WCSLIB_FILES) \ ast_err.h # Ensure libast links against libraries containing functions used within # libast. If AST is configured --with-external-pal, then the internal # libast_pal library will be empty, and we link to an external PAL # library instead. if EXTERNAL_PAL libast_la_LIBADD = $(libdir)/libpal.la else libast_la_LIBADD = libast_pal.la endif # AST_PAR is really part of GRP_F_INCLUDE_FILES, but it must not be # distributed, so list it separately. nodist_libast_la_SOURCES = \ ast.h \ AST_PAR # The default error reporting module. libast_err_la_SOURCES = err_null.c # The error reporting module that uses EMS to deliver errors. libast_ems_la_SOURCES = err_ems.c # The error reporting module that uses DRAMA Ers to deliver errors. libast_drama_la_SOURCES = err_drama.c # The module containing null implementations of the 3D graphics routines # required by AST libast_grf3d_la_SOURCES = grf3d.c # The module containing null implementations of the graphics routines # required by AST V2.0 libast_grf_2_0_la_SOURCES = grf_2.0.c # The module containing null implementations of the graphics routines # added by AST V3.2 and not present in V2.0 libast_grf_3_2_la_SOURCES = grf_3.2.c # The module containing null implementations of the graphics routines # added by AST V5.6 and not present in V3.2 libast_grf_5_6_la_SOURCES = grf_5.6.c # The graphics module that uses PGPLOT for 2D graphical output. libast_pgplot_la_SOURCES = $(GRF_PGPLOT_SOURCES) # The graphics module that uses PGPLOT for 3D graphical output. libast_pgplot3d_la_SOURCES = $(GRF3D_PGPLOT_SOURCES) # Positional astronomy libraries. libast_pal_la_SOURCES = $(PAL_FILES) # The following files are built by the targets in this makefile. MAINTAINERCLEANFILES = version.h builddocs addversion \ ast.h $(DOCUMENTATION_PRODUCTS) CLEANFILES = AST_PAR ast.h # Special cases start here # The AST_PAR include file is produced by compiling the astbad.c # program and editing its output into the ast_par.source file (while # also changing the "E" exponent character to a "D"). The astbad.c # and ast_par.source must be distributed (the generation of the # AST__BAD value must be done on the build host) but not installed. noinst_PROGRAMS = astbad astbad_SOURCES = astbad.c pointset.h AST_PAR: ast_par.source astbad sed -e 's//'`./astbad AST__BAD | tr 'E' 'D'`'/' \ -e 's//'`./astbad AST__NAN | tr 'E' 'D'`'/' \ -e 's//'`./astbad AST__NANF | tr 'E' 'D'`'/' \ ast_par.source >$@ # ast_link is generated from ast_link.in; ast_link_adam does not # need configuration, and so is not mentioned in AC_CONFIG_FILES within # configure.ac, and so is not distributed automatically. # # makeh is required in order to build ast.h after distribution (see below). EXTRA_DIST = ast_par.source sun210_figures sun211_figures pal erfa cminpack # ast.h depends on the error-facility files. ast.h _could_ be made # before distribution, but since it's generated from other distributed # files, it's more robust to distribute makeh and make ast.h on the # build host. ast.h: $(AST_H_FILES) ast_err.h makeh config.h @PERL@ ./makeh -s $(srcdir) $(AST_H_FILES) >$@ # AST_ERR and ast_err.h are `generated source files', and so must be # generated before any other compilations are done. Note that these # files are generated on the distribution host, and so this # declaration has no effect post-distribution. # # AST_PAR is also a generated source file, but it should _not_ be # included in the list of BUILT_SOURCES, otherwise `make' tries to make # it before it makes the `astbad' program it depends on. Instead, # just rely on the dependencies expressed in the main body above to # have AST_PAR built before it is needed. # # version.h is included by object.h, and thus indirectly by most modules. # It's most straightforward to build it at the beginning. BUILT_SOURCES = AST_ERR ast_err.h version.h # Form a second link to the main object library (static and shared). This # is used when a second pass through the library is needed during linking # to resolve references made within other AST libraries (e.g. the grf # modules, etc), to functions defined within libast (e.g. memory management # and error reporting functions). Do not forget to change the contents of # the libast_pass2.la file to refer to libast_pass2.* rather than libast.*. # Use target install-exec-hook rather than install-exec-local so that the # soft links and files are created *after* the main library has been # installed. install-exec-hook: libast.la $(mkdir_p) $(DESTDIR)$(libdir) cd $(DESTDIR)$(libdir); \ for f in `ls libast.*`; do \ ff=`echo $$f | sed -e 's/libast/libast_pass2/'`; \ if test -f "$$ff"; then rm "$$ff"; fi; \ $(LN_S) $$f $$ff; \ $(MANIFEST) && echo "MANIFEST:$(DESTDIR)$(libdir)/$$ff" || :; \ done; \ if test -f "libast.la"; then \ if test -f "libast_pass2.la"; then rm "libast_pass2.la"; fi; \ sed -e 's/libast\./libast_pass2\./g' libast.la > libast_pass2.la; \ fi # Make pre-distribution files. These are files which are required for # building the distribution, but are not themselves distributed. # The source files here should be mentioned in STAR_PREDIST_SOURCES in # configure.ac @PREDIST@predist_subs = sed \ @PREDIST@ -e 's,@PACKAGE_VERSION\@,$(PACKAGE_VERSION),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MAJOR\@,$(PACKAGE_VERSION_MAJOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_MINOR\@,$(PACKAGE_VERSION_MINOR),' \ @PREDIST@ -e 's,@PACKAGE_VERSION_RELEASE\@,$(PACKAGE_VERSION_RELEASE),' \ @PREDIST@ -e 's,@PERL\@,$(PERL),' \ @PREDIST@ -e 's,@STARLINK\@,$(STARLINK),' @PREDIST@version.h: version.h.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) version.h.in >$@ @PREDIST@builddocs: builddocs.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) builddocs.in >$@; chmod +x $@ @PREDIST@addversion: addversion.in configure.ac @PREDIST@ rm -f $@; $(predist_subs) addversion.in >$@; chmod +x $@ # Documentation @PREDIST@$(PAPER_DOCUMENTATION): sun211_figures builddocs addversion @PREDIST@ ./builddocs # The contents of the sun211_figures directory is identical to that # sun210_figures sun211_figures: sun210_figures $(LN_S) sun210_figures sun211_figures # Installation check TESTS = ast_test check_PROGRAMS = ast_test ast_test_SOURCES = ast_test.c #ast_test_LDADD = `ast_link` # Expand ast_link to avoid libast_pass2, which causes problems for Solaris ast_test_LDADD = @LIBPAL@ libast.la libast_pal.la libast_grf_3.2.la libast_grf_5.6.la libast_grf_2.0.la libast_grf3d.la libast_err.la -lm # Need to include latex support files in the distribution tar ball so # that the docs can be built from the tex source files. Requires environment # variable STARLATEXSUPPORT to be deined. Is there a better way to do this? dist-hook: cp -p $(STARLATEXSUPPORT)/starlink.cls $(distdir)/ cp -p $(STARLATEXSUPPORT)/starabbrev.sty $(distdir)/ cp -p $(STARLATEXSUPPORT)/starstyle.sty $(distdir)/ cp -p $(STARLATEXSUPPORT)/sst.sty $(distdir)/ ast-8.3.0/polymap.c0000664000175000017500000057314013004147321011066 00000000000000/* *class++ * Name: * PolyMap * Purpose: * Map coordinates using polynomial functions. * Constructor Function: c astPolyMap f AST_POLYMAP * Description: * A PolyMap is a form of Mapping which performs a general polynomial * transformation. Each output coordinate is a polynomial function of * all the input coordinates. The coefficients are specified separately * for each output coordinate. The forward and inverse transformations * are defined independantly by separate sets of coefficients. If no * inverse transformation is supplied, an iterative method can be used * to evaluate the inverse based only on the forward transformation. * Inheritance: * The PolyMap class inherits from the Mapping class. * Attributes: * In addition to those attributes common to all Mappings, every * PolyMap also has the following attributes: * * - IterInverse: Provide an iterative inverse transformation? * - NiterInverse: Maximum number of iterations for iterative inverse * - TolInverse: Target relative error for iterative inverse * Functions: c In addition to those functions applicable to all Objects, the c following functions may also be applied to all Mappings: f In addition to those routines applicable to all Objects, the f following routines may also be applied to all Mappings: * c - astPolyTran: Fit a PolyMap inverse or forward transformation f - AST_POLYTRAN: Fit a PolyMap inverse or forward transformation * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2011 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: D.S. Berry (Starlink) * History: * 27-SEP-2003 (DSB): * Original version. * 13-APR-2005 (DSB): * Changed the keys used by the Dump/astLoadPolyMap functions. They * used to exceed 8 characters and consequently caused problems for * FitsChans. * 20-MAY-2005 (DSB): * Correct the indexing of keywords produced in the Dump function. * 20-APR-2006 (DSB): * Guard against undefined transformations in Copy. * 10-MAY-2006 (DSB): * Override astEqual. * 4-JUL-2008 (DSB): * Fixed loop indexing problems in Equal function. * 27-MAY-2011 (DSB): * Added public method astPolyTran. * 18-JUL-2011 (DSB): * - Added attributes IterInverse, NiterInverse and TolInverse. * - Do not report an error if astPolyTran fails to fit an inverse. * 15-OCT-2011 (DSB): * Improve argument checking and error reporting in PolyTran * 8-MAY-2014 (DSB): * Move to using CMinPack for minimisations. *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 PolyMap /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "mapping.h" /* Coordinate mappings (parent class) */ #include "cmpmap.h" /* Compound mappings */ #include "polymap.h" /* Interface definition for this class */ #include "unitmap.h" /* Unit mappings */ #include "cminpack/cminpack.h" /* Levenberg - Marquardt minimization */ #include "pal.h" /* SLALIB function definitions */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static const char *(* parent_getattrib)( AstObject *, const char *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static int (* parent_getobjsize)( AstObject *, int * ); #if defined(THREAD_SAFE) static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); #endif #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(PolyMap) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(PolyMap,Class_Init) #define class_vtab astGLOBAL(PolyMap,Class_Vtab) #define getattrib_buff astGLOBAL(LutMap,GetAttrib_Buff) #include #else static char getattrib_buff[ 101 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstPolyMapVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* Type Definitions */ /* ================ */ /* Structure used to pass data to the Levenberg - Marquardt non-linear minimization algorithm. */ typedef struct MinPackData { int order; /* Max power of X1 or X2, plus one. */ int nsamp; /* No. of polynomial samples to fit */ int init_jac; /* Has the constant Jacobian been found yet? */ double *xp1; /* Pointer to powers of X1 (1st poly i/p) at all samples */ double *xp2; /* Pointer to powers of X2 (2nd poly i/p) at all samples */ double *y[ 2 ]; /* Pointers to Y1 and Y2 values at all samples */ } MinPackData; /* External 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. */ AstPolyMap *astPolyMapId_( int, int, int, const double[], int, const double[], const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstPolyMap **GetJacobian( AstPolyMap *, int * ); static AstPolyMap *PolyTran( AstPolyMap *, int, double, double, int, const double *, const double *, int * ); static double **SamplePoly1D( AstPolyMap *, int, double **, double, double, int, int *, double[2], int * ); static double **SamplePoly2D( AstPolyMap *, int, double **, const double *, const double *, int, int *, double[4], int * ); static double *FitPoly1D( int, double, int, double **, double[2], int *, double *, int * ); static double *FitPoly2D( int, double, int, double **, double[4], int *, double *, int * ); static int Equal( AstObject *, AstObject *, int * ); static int GetObjSize( AstObject *, int * ); static int GetTranForward( AstMapping *, int * ); static int GetTranInverse( AstMapping *, int * ); static int MPFunc1D( void *, int, int, const double *, double *, double *, int, int ); static int MPFunc2D( void *, int, int, const double *, double *, double *, int, int ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int ReplaceTransformation( AstPolyMap *, int, double, double, int, const double *, const double *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *obj, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void FreeArrays( AstPolyMap *, int, int * ); static void IterInverse( AstPolyMap *, AstPointSet *, AstPointSet *, int * ); static void LMFunc1D( const double *, double *, int, int, void * ); static void LMFunc2D( const double *, double *, int, int, void * ); static void LMJacob1D( const double *, double *, int, int, void * ); static void LMJacob2D( const double *, double *, int, int, void * ); static void StoreArrays( AstPolyMap *, int, int, const double *, int * ); #if defined(THREAD_SAFE) static int ManageLock( AstObject *, int, int, AstObject **, int * ); #endif static const char *GetAttrib( AstObject *, const char *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static int GetIterInverse( AstPolyMap *, int * ); static int TestIterInverse( AstPolyMap *, int * ); static void ClearIterInverse( AstPolyMap *, int * ); static void SetIterInverse( AstPolyMap *, int, int * ); static int GetNiterInverse( AstPolyMap *, int * ); static int TestNiterInverse( AstPolyMap *, int * ); static void ClearNiterInverse( AstPolyMap *, int * ); static void SetNiterInverse( AstPolyMap *, int, int * ); static double GetTolInverse( AstPolyMap *, int * ); static int TestTolInverse( AstPolyMap *, int * ); static void ClearTolInverse( AstPolyMap *, int * ); static void SetTolInverse( AstPolyMap *, double, int * ); /* Member functions. */ /* ================= */ static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a PolyMap. * Type: * Private function. * Synopsis: * #include "polymap.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PolyMap member function (over-rides the astClearAttrib protected * method inherited from the Mapping class). * Description: * This function clears the value of a specified attribute for a * PolyMap, so that the default value will subsequently be used. * Parameters: * this * Pointer to the PolyMap. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPolyMap *this; /* Pointer to the PolyMap structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* IterInverse. */ /* ------------ */ if ( !strcmp( attrib, "iterinverse" ) ) { astClearIterInverse( this ); /* NiterInverse. */ /* ------------- */ } else if ( !strcmp( attrib, "niterinverse" ) ) { astClearNiterInverse( this ); /* TolInverse. */ /* ----------- */ } else if ( !strcmp( attrib, "tolinverse" ) ) { astClearTolInverse( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { /* * Name: * Equal * Purpose: * Test if two PolyMaps are equivalent. * Type: * Private function. * Synopsis: * #include "polymap.h" * int Equal( AstObject *this, AstObject *that, int *status ) * Class Membership: * PolyMap member function (over-rides the astEqual protected * method inherited from the astMapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * two PolyMaps are equivalent. * Parameters: * this * Pointer to the first Object (a PolyMap). * that * Pointer to the second Object. * status * Pointer to the inherited status variable. * Returned Value: * One if the PolyMaps are equivalent, zero otherwise. * 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: */ AstPolyMap *that; AstPolyMap *this; int i, j, k; int nin; int nout; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain pointers to the two PolyMap structures. */ this = (AstPolyMap *) this_object; that = (AstPolyMap *) that_object; /* Check the second object is a PolyMap. We know the first is a PolyMap since we have arrived at this implementation of the virtual function. */ if( astIsAPolyMap( that ) ) { /* Get the number of inputs and outputs and check they are the same for both. */ nin = astGetNin( this ); nout = astGetNout( this ); if( astGetNin( that ) == nin && astGetNout( that ) == nout ) { /* If the Invert flags for the two PolyMaps differ, it may still be possible for them to be equivalent. First compare the PolyMaps if their Invert flags are the same. In this case all the attributes of the two PolyMaps must be identical. */ if( astGetInvert( this ) == astGetInvert( that ) ) { result = 1; for( i = 0; i < nout && result; i++ ) { if( this->ncoeff_f[ i ] != that->ncoeff_f[ i ] || this->mxpow_i[ i ] != that->mxpow_i[ i ] ) { result = 0; } } if( this->coeff_f && that->coeff_f ) { for( i = 0; i < nout && result; i++ ) { for( j = 0; j < this->ncoeff_f[ i ] && result; j++ ) { if( !astEQUAL( this->coeff_f[ i ][ j ], that->coeff_f[ i ][ j ] ) ) { result = 0; } } } } if( this->power_f && that->power_f ) { for( i = 0; i < nout && result; i++ ) { for( j = 0; j < this->ncoeff_f[ i ] && result; j++ ) { for( k = 0; k < nin && result; k++ ) { if( this->power_f[ i ][ j ][ k ] != that->power_f[ i ][ j ][ k ] ) { result = 0; } } } } } for( i = 0; i < nin && result; i++ ) { if( this->ncoeff_i[ i ] != that->ncoeff_i[ i ] || this->mxpow_f[ i ] != that->mxpow_f[ i ] ) { result = 0; } } if( this->coeff_i && that->coeff_i ) { for( i = 0; i < nin && result; i++ ) { for( j = 0; j < this->ncoeff_i[ i ] && result; j++ ) { if( !astEQUAL( this->coeff_i[ i ][ j ], that->coeff_i[ i ][ j ] ) ) { result = 0; } } } } if( this->power_i && that->power_i ) { for( i = 0; i < nin && result; i++ ) { for( j = 0; j < this->ncoeff_i[ i ] && result; j++ ) { for( k = 0; k < nout && result; k++ ) { if( this->power_i[ i ][ j ][ k ] != that->power_i[ i ][ j ][ k ] ) { result = 0; } } } } } /* If the Invert flags for the two PolyMaps differ, the attributes of the two PolyMaps must be inversely related to each other. */ } else { /* In the specific case of a PolyMap, Invert flags must be equal. */ result = 0; } } } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static double *FitPoly1D( int nsamp, double acc, int order, double **table, double scales[2], int *ncoeff, double *racc, int *status ){ /* * Name: * FitPoly1D * Purpose: * Fit a (1-in,1-out) polynomial to a supplied set of data. * Type: * Private function. * Synopsis: * double *FitPoly1D( int nsamp, double acc, int order, double **table, * double scales[2], int *ncoeff, double *racc, * int *status ) * Description: * This function fits a least squares 1D polynomial curve to the * positions in a supplied table. For the purposes of this function, * the polynomial input is refered to as x1 and the output as y1. So * the polynomial is: * * y1 = P1( x1 ) * Parameters: * nsamp * The number of (x1,y1) positions in the supplied table. * acc * The required accuracy, expressed as an offset within the polynomials * output space. * order * The maximum power (plus one) of x1 within P1. So for instance, a * value of 3 refers to a quadratic polynomial. * table * Pointer to an array of 2 pointers. Each of these pointers points * to an array of "nsamp" doubles, being the scaled and sampled values * for x1 and y1 in that order. * scales * Array holding the scaling factors for the two columns of the table. * Multiplying the table values by the scale factor produces PolyMap * input or output axis values. * ncoeff * Pointer to an ant in which to return the number of coefficients * described by the returned array. * racc * Pointer to a double in which to return the achieved accuracy * (which may be greater than "acc"). * status * Pointer to the inherited status variable. * Returned Value: * A pointer to an array of doubles defining the polynomial in the * form required by the PolyMap contructor. The number of coefficients * is returned via "ncoeff". If the polynomial could not be found, * then NULL is returned. The returned pointer should be freed using * astFree when no longer needed. */ /* Local Variables: */ MinPackData data; double *coeffs; double *pc; double *pr; double *px1; double *pxp1; double *result; double *work1; double *work2; double *work4; double f1; double f2; double maxterm; double term; double tv; double x1; int *work3; int info; int k; int ncof; int w1; /* Initialise returned value */ result = NULL; *ncoeff = 0; *racc = 10*acc; /* Check inherited status */ if( !astOK ) return result; /* Number of coefficients per poly. */ ncof = order; /* Initialise the elements of the structure. */ data.order = order; data.nsamp = nsamp; data.init_jac = 1; data.xp1 = astMalloc( nsamp*order*sizeof( double ) ); data.xp2 = NULL; data.y[ 0 ] = table[ 1 ]; data.y[ 1 ] = NULL; /* Work space to hold coefficients. */ coeffs = astMalloc( ncof*sizeof( double ) ); /* Other work space. */ work1 = astMalloc( nsamp*sizeof( double ) ); work2 = astMalloc( ncof*nsamp*sizeof( double ) ); work3 = astMalloc( ncof*sizeof( int ) ); work4 = astMalloc( (5*ncof+nsamp)*sizeof( double ) ); if( astOK ) { /* Get pointers to the supplied x1 values. */ px1 = table[ 0 ]; /* Get pointers to the location for the next power of x1. */ pxp1 = data.xp1; /* Loop round all samples. */ for( k = 0; k < nsamp; k++ ) { /* Get the current x1 value. */ x1 = *(px1++); /* Find all the required powers of x1 and store them in the "xp1" component of the data structure. */ tv = 1.0; for( w1 = 0; w1 < order; w1++ ) { *(pxp1++) = tv; tv *= x1; } } /* The initial guess at the coefficient values represents a unit transformation in PolyMap axis values. */ for( k = 0; k < ncof; k++ ) coeffs[ k ] = 0.0; coeffs[ 1 ] = scales[ 0 ]/scales[ 1 ]; /* Find the best coefficients */ info = lmder1( MPFunc1D, &data, nsamp, ncof, coeffs, work1, work2, nsamp, sqrt(DBL_EPSILON), work3, work4, (5*ncof+nsamp) ); if( info == 0 ) astError( AST__MNPCK, "astPolyMap(PolyTran): Minpack error " "detected (possible programming error).", status ); /* Return the achieved accuracy. */ pr = work1; tv = 0.0; for( k = 0; k < nsamp; k++,pr++ ) tv += (*pr)*(*pr); *racc = scales[ 1 ]*sqrt( tv/nsamp ); /* The best fitting polynomial coefficient found above relate to the polynomial between the scaled positions stored in "table". These scaled positions are related to PolyMap input/output axis values via the scale factors supplied in "scales". Find the initial factor for the current output. */ f1 = scales[ 1 ]; f2 = 1.0; /* Look at each coefficient. */ pc = coeffs; for( w1 = 0; w1 < order; w1++,pc++ ) { /* Get a pointer to the powers of X1 appropriate for the current coefficient, at the first sample. */ pxp1 = data.xp1 + w1; /* We find the contribution which this coefficient makes to the total polynomial value. Find the maximum contribution made at any sample points. */ maxterm = 0.0; for( k = 0; k < nsamp; k++ ) { /* Get the absolute value of the polynomial term that uses the current coefficient. */ term = fabs( ( *pc )*( *pxp1 ) ); /* Update the maximum term found at any sample. */ if( term > maxterm ) maxterm = term; /* Increment the pointers to refer to the next sample. */ pxp1 += order; } /* If the maximum contribution made by this term is less than the required accuracy, set the coefficient value to zero. */ if( maxterm*f1 < acc ) { *pc = 0.0; /* Scale the best fitting polynomial coefficient found above to take account of the fact that the tabulated input and output positions in "table" were are not actual PolyMap input and output axis values, but are scaled by the factors stored in "scales". */ } else { *pc *= f1/f2; } f2 *= scales[ 0 ]; } /* Convert the array of coefficients into PolyMap form. */ result = astMalloc( ncof*3*sizeof( double ) ); *ncoeff = 0; pr = result; pc = coeffs; for( w1 = 0; w1 < order; w1++,pc++ ) { if( *pc != 0.0 ) { *(pr++) = *pc; *(pr++) = 1; *(pr++) = w1; (*ncoeff)++; } } /* Truncate the returned array. */ result = astRealloc( result, (*ncoeff)*3*sizeof( double ) ); } /* Free resources. */ coeffs = astFree( coeffs ); data.xp1 = astFree( data.xp1 ); work1 = astFree( work1 ); work2 = astFree( work2 ); work3 = astFree( work3 ); work4 = astFree( work4 ); /* Return the coefficient array. */ return result; } static double *FitPoly2D( int nsamp, double acc, int order, double **table, double scales[4], int *ncoeff, double *racc, int *status ){ /* * Name: * FitPoly2D * Purpose: * Fit a (2-in,2-out) polynomial to a supplied set of data. * Type: * Private function. * Synopsis: * double *FitPoly2D( int nsamp, double acc, int order, double **table, * double scales[4], int *ncoeff, double *racc, * int *status ) * Description: * This function fits a pair of least squares 2D polynomial surfaces * to the positions in a supplied table. For the purposes of this * function, the polynomial inputs are refered to as (x1,x2) and the * outputs as (y1,y2). So the two polynomials are: * * y1 = P1( x1, x2 ) * y2 = P2( x1, x2 ) * * P1 and P2 have the same maximum power on each input (specified by * the "order" parameter). * Parameters: * nsamp * The number of (x1,x2,y1,y2) positions in the supplied table. * acc * The required accuracy, expressed as a geodesic distance within * the polynomials output space. * order * The maximum power (plus one) of x1 or x2 within P1 and P2. So for * instance, a value of 3 refers to a quadratic polynomial. Note, cross * terms with total powers greater than or equal to "order" are not * included in the fit. So the maximum number of terms in the fitted * polynomial is order*(order+1)/2. * table * Pointer to an array of 4 pointers. Each of these pointers points * to an array of "nsamp" doubles, being the scaled and sampled values * for x1, x2, y1 or y2 in that order. * scales * Array holding the scaling factors for the four columns of the table. * Multiplying the table values by the scale factor produces PolyMap * input or output axis values. * ncoeff * Pointer to an ant in which to return the number of coefficients * described by the returned array. * racc * Pointer to a double in which to return the achieved accuracy * (which may be greater than "acc"). * status * Pointer to the inherited status variable. * Returned Value: * A pointer to an array of doubles defining the polynomial in the * form required by the PolyMap contructor. The number of coefficients * is returned via "ncoeff". If the polynomial could not be found with * sufficient accuracy , then NULL is returned. The returned pointer * should be freed using astFree when no longer needed. */ /* Local Variables: */ MinPackData data; double *coeffs; double *pc; double *pr; double *px1; double *px2; double *pxp1; double *pxp2; double *result; double *work1; double *work2; double *work4; double f1; double f20; double f2; double f3; double facc; double maxterm; double term; double tv; double x1; double x2; int *work3; int info; int iout; int k; int ncof; int w12; int w1; int w2; /* Initialise returned value */ result = NULL; *ncoeff = 0; *racc = 10*acc; /* Check inherited status */ if( !astOK ) return result; /* Number of coefficients per poly. */ ncof = order*( order + 1 )/2; /* Initialise the elements of the structure. */ data.order = order; data.nsamp = nsamp; data.init_jac = 1; data.xp1 = astMalloc( nsamp*order*sizeof( double ) ); data.xp2 = astMalloc( nsamp*order*sizeof( double ) ); data.y[ 0 ] = table[ 2 ]; data.y[ 1 ] = table[ 3 ]; /* Work space to hold coefficients. */ coeffs = astMalloc( 2*ncof*sizeof( double ) ); /* Other work space. */ work1 = astMalloc( 2*nsamp*sizeof( double ) ); work2 = astMalloc( 4*ncof*nsamp*sizeof( double ) ); work3 = astMalloc( 2*ncof*sizeof( int ) ); work4 = astMalloc( 2*(5*ncof+nsamp)*sizeof( double ) ); if( astOK ) { /* Get pointers to the supplied x1 and x2 values. */ px1 = table[ 0 ]; px2 = table[ 1 ]; /* Get pointers to the location for the next power of x1 and x2. */ pxp1 = data.xp1; pxp2 = data.xp2; /* Loop round all samples. */ for( k = 0; k < nsamp; k++ ) { /* Get the current x1 and x2 values. */ x1 = *(px1++); x2 = *(px2++); /* Find all the required powers of x1 and store them in the "xp1" component of the data structure. */ tv = 1.0; for( w1 = 0; w1 < order; w1++ ) { *(pxp1++) = tv; tv *= x1; } /* Find all the required powers of x2 and store them in the "xp2" comonent of the data structure. */ tv = 1.0; for( w2 = 0; w2 < order; w2++ ) { *(pxp2++) = tv; tv *= x2; } } /* The initial guess at the coefficient values represents a unit transformation in PolyMap axis values. */ for( k = 0; k < 2*ncof; k++ ) coeffs[ k ] = 0.0; coeffs[ 1 ] = scales[ 0 ]/scales[ 2 ]; coeffs[ 5 ] = scales[ 1 ]/scales[ 3 ]; /* Find the best coefficients */ info = lmder1( MPFunc2D, &data, 2*nsamp, 2*ncof, coeffs, work1, work2, 2*nsamp, sqrt(DBL_EPSILON), work3, work4, 2*(5*ncof+nsamp) ); if( info == 0 ) astError( AST__MNPCK, "astPolyMap(PolyTran): Minpack error " "detected (possible programming error).", status ); /* Return the achieved accuracy. */ pr = work1; tv = 0.0; for( k = 0; k < 2*nsamp; k++,pr++ ) tv += (*pr)*(*pr); facc = 1.0/(scales[2]*scales[2]) + 1.0/(scales[3]*scales[3]); *racc = sqrt( tv/(2*nsamp*facc) ); /* Pointer to the first coefficient. */ pc = coeffs; /* Look at coefficients for each output in turn. */ for( iout = 0; iout < 2 && astOK; iout++ ) { /* The best fitting polynomial coefficient found above relate to the polynomial between the scaled positions stored in "table". These scaled positions are related to PolyMap input/output axis values via the scale factors supplied in "scales". Find the initial factor for the current output. */ f1 = scales[ 2 + iout ]; /* Look at each coefficient for the current output. */ f20 = 1.0; for( w12 = 0; w12 < order; w12++ ) { f3 = 1.0; f2 = f20; for( w2 = 0; w2 <= w12; w2++,pc++ ) { w1 = w12 - w2; /* Get pointers to the powers of X1 and X2 appropriate for the current coefficient, at the first sample. */ pxp1 = data.xp1 + w1; pxp2 = data.xp2 + w2; /* We find the contribution which this coefficient makes to the total polynomial value. Find the maximum contribution made at any sample points. */ maxterm = 0.0; for( k = 0; k < nsamp; k++ ) { /* Get the absolute value of the polynomial term that uses the current coefficient. */ term = fabs( ( *pc )*( *pxp1 )*( *pxp2 ) ); /* Update the maximum term found at any sample. */ if( term > maxterm ) maxterm = term; /* Increment the pointers to refer to the next sample. */ pxp1 += order; pxp2 += order; } /* If the maximum contribution made by this term is less than the required accuracy, set the coefficient value to zero. */ if( maxterm*f1 < acc ) { *pc = 0.0; /* Scale the best fitting polynomial coefficient found above to take account of the fact that the tabulated input and output positions in "table" were are not actual PolyMap input and output axis values, but are scaled by the factors stored in "scales". */ } else { *pc *= f1/( f2*f3 ); } f2 /= scales[ 0 ]; f3 *= scales[ 1 ]; } f20 *= scales[ 0 ]; } } /* Convert the array of coefficients into PolyMap form. */ result = astMalloc( 2*ncof*4*sizeof( double ) ); *ncoeff = 0; pr = result; pc = coeffs; for( iout = 0; iout < 2 && astOK; iout++ ) { for( w12 = 0; w12 < order; w12++ ) { for( w2 = 0; w2 <= w12; w2++,pc++ ) { w1 = w12 - w2; if( *pc != 0.0 ) { *(pr++) = *pc; *(pr++) = iout + 1; *(pr++) = w1; *(pr++) = w2; (*ncoeff)++; } } } } /* Truncate the returned array. */ result = astRealloc( result, (*ncoeff)*4*sizeof( double ) ); } /* Free resources. */ coeffs = astFree( coeffs ); data.xp1 = astFree( data.xp1 ); data.xp2 = astFree( data.xp2 ); work1 = astFree( work1 ); work2 = astFree( work2 ); work3 = astFree( work3 ); work4 = astFree( work4 ); /* Return the coefficient array. */ return result; } static void FreeArrays( AstPolyMap *this, int forward, int *status ) { /* * Name: * FreeArrays * Purpose: * Free the dynamic arrays contained within a PolyMap * Type: * Private function. * Synopsis: * void FreeArrays( AstPolyMap *this, int forward, int *status ) * Description: * This function frees all the dynamic arrays allocated as part of a * PolyMap. * Parameters: * this * Pointer to the PolyMap. * forward * If non-zero, the arrays for the forward transformation are freed. * Otherwise, the arrays for the inverse transformation are freed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ int nin; /* Number of inputs */ int nout; /* Number of outputs */ int i; /* Loop count */ int j; /* Loop count */ /* Get the number of inputs and outputs of the uninverted Mapping. */ nin = ( (AstMapping *) this )->nin; nout = ( (AstMapping *) this )->nout; /* Free the dynamic arrays for the forward transformation. */ if( forward ) { if( this->coeff_f ) { for( i = 0; i < nout; i++ ) { this->coeff_f[ i ] = astFree( this->coeff_f[ i ] ); } this->coeff_f = astFree( this->coeff_f ); } if( this->power_f ) { for( i = 0; i < nout; i++ ) { if( this->ncoeff_f && this->power_f[ i ] ) { for( j = 0; j < this->ncoeff_f[ i ]; j++ ) { this->power_f[ i ][ j ] = astFree( this->power_f[ i ][ j ] ); } } this->power_f[ i ] = astFree( this->power_f[ i ] ); } this->power_f = astFree( this->power_f ); } this->ncoeff_f = astFree( this->ncoeff_f ); this->mxpow_f = astFree( this->mxpow_f ); /* Free the dynamic arrays for the inverse transformation. */ } else { if( this->coeff_i ) { for( i = 0; i < nin; i++ ) { this->coeff_i[ i ] = astFree( this->coeff_i[ i ] ); } this->coeff_i = astFree( this->coeff_i ); } if(this->power_i ) { for( i = 0; i < nin; i++ ) { if( this->ncoeff_i && this->power_i[ i ] ) { for( j = 0; j < this->ncoeff_i[ i ]; j++ ) { this->power_i[ i ][ j ] = astFree( this->power_i[ i ][ j ] ); } } this->power_i[ i ] = astFree( this->power_i[ i ] ); } this->power_i = astFree( this->power_i ); } this->ncoeff_i = astFree( this->ncoeff_i ); this->mxpow_i = astFree( this->mxpow_i ); } } static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * GetAttrib * Purpose: * Get the value of a specified attribute for a PolyMap. * Type: * Private function. * Synopsis: * #include "polymap.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PolyMap member function (over-rides the protected astGetAttrib * method inherited from the Mapping class). * Description: * This function returns a pointer to the value of a specified * attribute for a PolyMap, formatted as a character string. * Parameters: * this * Pointer to the PolyMap. * 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 PolyMap, 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 PolyMap. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPolyMap *this; /* Pointer to the PolyMap structure */ const char *result; /* Pointer value to return */ double dval; /* Floating point attribute value */ int ival; /* Integer attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) 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. */ /* IterInverse. */ /* ------------ */ if ( !strcmp( attrib, "iterinverse" ) ) { ival = astGetIterInverse( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* NiterInverse. */ /* ------------- */ } else if ( !strcmp( attrib, "niterinverse" ) ) { ival = astGetNiterInverse( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", ival ); result = getattrib_buff; } /* TolInverse. */ /* ----------- */ } else if ( !strcmp( attrib, "tolinverse" ) ) { dval = astGetTolInverse( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%.*g", DBL_DIG, dval ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static AstPolyMap **GetJacobian( AstPolyMap *this, int *status ){ /* * Name: * GetJacobian * Purpose: * Get a description of a Jacobian matrix for the fwd transformation * of a PolyMap. * Type: * Private function. * Synopsis: * AstPolyMap **GetJacobian( AstPolyMap *this, int *status ) * Description: * This function returns a set of PolyMaps which define the Jacobian * matrix of the forward transformation of the supplied PolyMap. * * The Jacobian matrix has "nout" rows and "nin" columns, where "nin" * and "nout" are the number of inputs and outputs of the supplied PolyMap. * Row "i", column "j" of the matrix holds the rate of change of the * i'th PolyMap output with respect to the j'th PolyMap input. * * Since the values in the Jacobian matrix vary across the input space * of the PolyMap, the matrix is returned in the form of a set of new * PolyMaps which generate the elements of the Jacobian for any given * position in the input space. The "nout" values in a single column of * the Jacobian matrix are generated by the "nout" outputs from a single * new PolyMap. The whole matrix is described by "nin" PolyMaps. * * The returned PolyMaps are cached in the supplied PolyMap object in * order to speed up subsequent calls to this function. * Parameters: * this * The PolyMap for which the Jacbian is required. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to an array of "nin" PolyMap pointers, where "nin" is the number * of inputs for the sipplied PolyMap. The returned array should not be changed * in any way, and the PolyMaps should not be freed (they will be freed when * the supplied PolyMap is deleted). */ /* Local Variables: */ double *coeffs; double *pc; int icof; int icol; int iin; int irow; int ncof; int ncof_row; int ncof_total; int nin; int nout; int power; /* Check inherited status */ if( !astOK ) return NULL; /* Ensure there is a Jacobian stored in the PolyMap. */ if( !this->jacobian ) { /* Get the number of inputs and outputs. */ nin = astGetNin( this ); nout = astGetNout( this ); /* Allocate memory to hold pointers to the PolyMaps used to describe the Jacobian matrix. */ this->jacobian = astCalloc( nin, sizeof(AstPolyMap *) ); /* Find the total number of coefficients used to describe the supplied PolyMap (forward transformation) and allocate work space to hold the coefficients for a single new PolyMap forward transformation. */ ncof = 0; for( irow = 0; irow < nout; irow++ ) { ncof += this->ncoeff_f[ irow ]; } coeffs = astMalloc( ncof*( 2 + nin )*sizeof( double ) ); /* Check pointers can be used safely. */ if( astOK ) { /* The Jacobian matrix has "nout" rows and "nin" columns. The "nout" values in a single column of the Jacobian matrix corresponds to the "nout" outputs from a single PolyMap. The whole matrix is described by "nin" PolyMaps. Loop over each column of the Matrix, creating the corresponding PolyMap for each. */ for( icol = 0; icol < nin; icol++ ) { /* Initialise the total number of coefficients used to describe the element of the PolyMap. */ ncof_total = 0; /* Loop over each row of the Jacobian matrix (i.e. each PolyMap output). */ pc = coeffs; for( irow = 0; irow < nout; irow++ ) { /* Loop over each coefficient used in the polynomial that generates the current PolyMap output. */ ncof_row = this->ncoeff_f[ irow ]; for( icof = 0; icof < ncof_row; icof++ ) { /* Get the power of input "icol" associated with the current coefficient. */ power = (int)( this->power_f[ irow ][ icof ][ icol ] + 0.5 ); /* We can skip the coefficient if the power is zero. */ if( power > 0 ) { ncof_total++; /* Store the coefficient value, modified so that it describes a polynomial that has been differentiated with respect to input "icol". */ *(pc++) = this->coeff_f[ irow ][ icof ]*power; /* Store the output PolyMap to which the coeff relates. */ *(pc++) = irow + 1; /* Store the powers of the inputs associated with the coeff. These are the same as the original powers, except that the power of "icol" (the input with respect to which the output has been differentiated) is reduced by one. */ for( iin = 0; iin < nin; iin++ ) { if( iin != icol ) { *(pc++) = this->power_f[ irow ][ icof ][ iin ]; } else { *(pc++) = this->power_f[ irow ][ icof ][ iin ] - 1; } } } } } /* Create the PolyMap and store a pointer to it in the jacobian array in the supplied PolyMap. */ (this->jacobian)[ icol ] = astPolyMap( nin, nout, ncof_total, coeffs, 0, NULL, " ", status ); } } /* Free resources */ coeffs = astFree( coeffs ); } /* Return the Jacobian. */ return this->jacobian; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "polymap.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * PolyMap member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied PolyMap, * in bytes. * Parameters: * this * Pointer to the PolyMap. * 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: */ AstPolyMap *this; int ic; int nc; int result; /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by this class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); if( this->jacobian ) { nc = astGetNin( this ); for( ic = 0; ic < nc; ic++ ) { result += astGetObjSize( (this->jacobian)[ ic ] ); } result += sizeof( AstPolyMap * )*nc; } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result, */ return result; } static int GetTranForward( AstMapping *this, int *status ) { /* * * Name: * GetTranForward * Purpose: * Determine if a PolyMap defines a forward coordinate transformation. * Type: * Private function. * Synopsis: * #include "mapping.h" * int GetTranForward( AstMapping *this, int *status ) * Class Membership: * PolyMap member function (over-rides the astGetTranForward method * inherited from the Mapping class). * Description: * This function returns a value indicating if the PolyMap is able * to perform a forward coordinate transformation. * Parameters: * this * Pointer to the PolyMap. * status * Pointer to the inherited status variable. * 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: */ AstPolyMap *map; /* Pointer to PolyMap to be queried */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the PolyMap. */ map = (AstPolyMap *) this; /* Return the result. */ return map->ncoeff_f ? 1 : 0; } static int GetTranInverse( AstMapping *this, int *status ) { /* * * Name: * GetTranInverse * Purpose: * Determine if a PolyMap defines an inverse coordinate transformation. * Type: * Private function. * Synopsis: * #include "matrixmap.h" * int GetTranInverse( AstMapping *this, int *status ) * Class Membership: * PolyMap member function (over-rides the astGetTranInverse method * inherited from the Mapping class). * Description: * This function returns a value indicating if the PolyMap is able * to perform an inverse coordinate transformation. * Parameters: * this * Pointer to the PolyMap. * status * Pointer to the inherited status variable. * 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: */ AstPolyMap *map; /* Pointer to PolyMap to be queried */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the PolyMap. */ map = (AstPolyMap *) this; /* Return the result. */ return ( map->ncoeff_i || astGetIterInverse( map ) ) ? 1 : 0; } void astInitPolyMapVtab_( AstPolyMapVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitPolyMapVtab * Purpose: * Initialise a virtual function table for a PolyMap. * Type: * Protected function. * Synopsis: * #include "polymap.h" * void astInitPolyMapVtab( AstPolyMapVtab *vtab, const char *name ) * Class Membership: * PolyMap vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the PolyMap class. * Parameters: * vtab * Pointer to the virtual function table. The components used by * all ancestral classes will be initialised if they have not already * been initialised. * name * Pointer to a constant null-terminated character string which contains * the name of the class to which the virtual function table belongs (it * is this pointer value that will subsequently be returned by the Object * astClass function). *- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ /* Check the local error status. */ if ( !astOK ) return; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialize the component of the virtual function table used by the parent class. */ astInitMappingVtab( (AstMappingVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAPolyMap) to determine if an object belongs to this class. We can conveniently use the address of the (static) class_check variable to generate this unique value. */ vtab->id.check = &class_check; vtab->id.parent = &(((AstMappingVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->PolyTran = PolyTran; vtab->ClearIterInverse = ClearIterInverse; vtab->GetIterInverse = GetIterInverse; vtab->SetIterInverse = SetIterInverse; vtab->TestIterInverse = TestIterInverse; vtab->ClearNiterInverse = ClearNiterInverse; vtab->GetNiterInverse = GetNiterInverse; vtab->SetNiterInverse = SetNiterInverse; vtab->TestNiterInverse = TestNiterInverse; vtab->ClearTolInverse = ClearTolInverse; vtab->GetTolInverse = GetTolInverse; vtab->SetTolInverse = SetTolInverse; vtab->TestTolInverse = TestTolInverse; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; mapping = (AstMappingVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; #if defined(THREAD_SAFE) parent_managelock = object->ManageLock; object->ManageLock = ManageLock; #endif parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_transform = mapping->Transform; mapping->Transform = Transform; mapping->GetTranForward = GetTranForward; mapping->GetTranInverse = GetTranInverse; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ object->Equal = Equal; mapping->MapMerge = MapMerge; /* Declare the destructor and copy constructor. */ astSetDelete( (AstObjectVtab *) vtab, Delete ); astSetCopy( (AstObjectVtab *) vtab, Copy ); /* Declare the class dump function. */ astSetDump( vtab, Dump, "PolyMap", "Polynomial transformation" ); /* 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 IterInverse( AstPolyMap *this, AstPointSet *out, AstPointSet *result, int *status ){ /* * Name: * IterInverse * Purpose: * Use an iterative method to evaluate the inverse transformation of a * PolyMap at a set of output positions. * Type: * Private function. * Synopsis: * void IterInverse( AstPolyMap *this, AstPointSet *out, AstPointSet *result, * int *status ) * Description: * This function transforms a set of PolyMap output positions using * the inverse transformation of the PolyMap, to generate the corresponding * input positions. An iterative Newton-Raphson method is used which * only required the forward transformation of the PolyMap to be deifned. * Parameters: * this * The PolyMap. * out * A PointSet holding the PolyMap output positions that are to be * transformed using the inverse transformation. * result * A PointSet into which the generated PolyMap input positions are to be * stored. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstPointSet *work; AstPointSet **ps_jac; AstPolyMap **jacob; double *vec; double *pb; double **ptr_work; double ***ptr_jac; double *mat; double **ptr_out; double **ptr_in; double *pa; double det; double maxerr; double vlensq; double xlensq; double xx; int *flags; int *iw; int fwd; int icol; int icoord; int ipoint; int irow; int iter; int maxiter; int nconv; int ncoord; int npoint; int sing; /* Check inherited status */ if( !astOK ) return; /* Check the PolyMap has equal numbers of inputs and outputs. */ ncoord = astGetNin( this ); if( ncoord != astGetNout( this ) ) { astError( AST__INTER, "astTransform(%s): Supplied %s has unequal numbers" " of inputs and outputs and therefore an iterative inverse " "cannot be used (internal AST Programming errpr).", status, astGetClass(this), astGetClass(this) ); } /* Get information about the Jacobian matrix for the forward polynomial transformation. This matrix is a ncoord X ncoord matrix, in which element (row=I,col=J) is the rate of change of output coord I with respect to input coord J, of the supplied PolyMap's forward transformation. The numerical values of the matrix vary depending on where it is evaluated within the input space of the PolyMap. For this reason, the "jacob" variable holds a vector of "ncoord" PolyMaps. The outputs of each of these PolyMaps corresponds to a single column in the Jacobian matrix. */ jacob = GetJacobian( this, status ); /* Get the number of points to be transformed. */ npoint = astGetNpoint( out ); /* Get another PointSet to hold intermediate results. */ work = astPointSet( npoint, ncoord, " ", status ); /* See if the PolyMap has been inverted. */ fwd = !astGetInvert( this ); /* Get pointers to the data arrays for all PointSets. Note, here "in" and "out" refer to inputs and outputs of the PolyMap (i.e. the forward transformation). These are respectively *outputs* and *inputs* of the inverse transformation. */ ptr_in = astGetPoints( result ); /* Returned input positions */ ptr_out = astGetPoints( out ); /* Supplied output positions */ ptr_work = astGetPoints( work ); /* Work space */ /* Allocate an array of PointSets to hold the elements of the Jacobian matrix. */ ptr_jac = astMalloc( sizeof( double ** )*ncoord ); ps_jac = astCalloc( ncoord, sizeof( AstPointSet * ) ); if( astOK ) { for( icoord = 0; icoord < ncoord; icoord++ ) { ps_jac[ icoord ] = astPointSet( npoint, ncoord, " ", status ); ptr_jac[ icoord ] = astGetPoints( ps_jac[ icoord ] ); } } /* Allocate an array to hold flags indicating if each position has converged. Initialise it to hold zero at every element. */ flags = astCalloc( npoint, sizeof( int ) ); /* Allocate memory to hold the Jacobian matrix at a single point. */ mat = astMalloc( sizeof( double )*ncoord*ncoord ); /* Allocate memory to hold the offset vector. */ vec = astMalloc( sizeof( double )*ncoord ); /* Allocate memory to hold work space for palDmat. */ iw = astMalloc( sizeof( int )*ncoord ); /* Check pointers can be used safely. */ if( astOK ) { /* Store the initial guess at the required input positions. We assume initially that the inverse transformation is a unit mapping, and so we just copy the supplied outputs positions to the results PointSet holding the corresponding input positions. */ for( icoord = 0; icoord < ncoord; icoord++ ) { memcpy( ptr_in[ icoord ], ptr_out[ icoord ], sizeof( double )*npoint ); } /* Get the maximum number of iterations to perform. */ maxiter = astGetNiterInverse( this ); /* Get the target relative error for the returned input axis values, and square it. */ maxerr = astGetTolInverse( this ); maxerr *= maxerr; /* Initialise the number of positions which have reached the required accuracy. */ nconv = 0; /* Loop round doing iterations of a Newton-Raphson algorithm, until all points have achieved the required relative error, or the maximum number of iterations have been performed. */ for( iter = 0; iter < maxiter && nconv < npoint && astOK; iter++ ) { /* Use the forward transformation of the supplied PolyMap to transform the current guesses at the required input positions into the corresponding output positions. Store the results in the "work" PointSet. */ (void) astTransform( this, result, fwd, work ); /* Modify the work PointSet so that it holds the offsets from the output positions produced by the current input position guesses, and the required output positions. */ for( icoord = 0; icoord < ncoord; icoord++ ) { pa = ptr_out[ icoord ]; pb = ptr_work[ icoord ]; for( ipoint = 0; ipoint< npoint; ipoint++,pa++,pb++ ) { if( *pa != AST__BAD && *pb != AST__BAD ){ *pb = *pa - *pb; } else { *pb = AST__BAD; } } } /* Evaluate the elements of the Jacobian matrix at the current input position guesses. */ for( icoord = 0; icoord < ncoord; icoord++ ) { (void) astTransform( jacob[ icoord ], result, 1, ps_jac[ icoord ] ); } /* For each position, we now invert the matrix equation Dy = Jacobian.Dx to find a guess at the vector (dx) holding the offsets from the current input positions guesses to their required values. Loop over all points. */ for( ipoint = 0; ipoint < npoint; ipoint++ ) { /* Do not change positions that have already converged. */ if( !flags[ ipoint ] ) { /* Get the numerical values for the elements of the Jacobian matrix at the current point. */ pa = mat; for( irow = 0; irow < ncoord; irow++ ) { for( icol = 0; icol < ncoord; icol++ ) { *(pa++) = ptr_jac[ icol ][ irow ][ ipoint ]; } /* Store the offset from the current output position to the required output position. */ vec[ irow ] = ptr_work[ irow ][ ipoint ]; } /* Find the corresponding offset from the current input position to the required input position. */ palDmat( ncoord, mat, vec, &det, &sing, iw ); /* If the matrix was singular, the input position cannot be evaluated so store a bad value for it and indicate it has converged. */ if( sing ) { for( icoord = 0; icoord < ncoord; icoord++ ) { ptr_in[ icoord ][ ipoint ] = AST__BAD; } flags[ ipoint ] = 1; nconv++; /* Otherwise, update the input position guess. */ } else { vlensq = 0.0; xlensq = 0.0; pa = vec; for( icoord = 0; icoord < ncoord; icoord++,pa++ ) { xx = ptr_in[ icoord ][ ipoint ] + (*pa); ptr_in[ icoord ][ ipoint ] = xx; xlensq += xx*xx; vlensq += (*pa)*(*pa); } /* Check for convergence. */ if( vlensq < maxerr*xlensq ) { flags[ ipoint ] = 1; nconv++; } } } } } } /* Free resources. */ vec = astFree( vec ); iw = astFree( iw ); mat = astFree( mat ); flags = astFree( flags ); work = astAnnul( work ); if( ps_jac ) { for( icoord = 0; icoord < ncoord; icoord++ ) { ps_jac[ icoord ] = astAnnul( ps_jac[ icoord ] ); } ps_jac = astFree( ps_jac ); } ptr_jac = astFree( ptr_jac ); } static void LMFunc1D( const double *p, double *hx, int m, int n, void *adata ){ /* * Name: * LMFunc1D * Purpose: * Evaluate a test 1D polynomal. * Type: * Private function. * Synopsis: * void LMFunc1D( const double *p, double *hx, int m, int n, void *adata ) * Description: * This function finds the residuals implied by a supplied set of * candidate polynomial coefficients. Each residual is a candidate * polynomial evaluated at one of the sample points, minus the * supplied target value for the polynomial at that test point. * * The minimisation process minimises the sum of the squared residuals. * Parameters: * p * An array of "m" coefficients for the candidate polynomial. The * coefficients are ordered C0, C1, C2, etc. * hx * An array in which to return the "n" residuals. The residual at * sample "k" is returned in element (k). * m * The length of the "p" array. This should be equal to order. * n * The length of the "hx" array. This should be equal to nsamp. * adata * Pointer to a structure holding the sample positions and values, * and other information. */ /* Local Variables: */ MinPackData *data; double *px1; double *py; const double *vp; double *vr; double res; int k; int w1; /* Get a pointer to the data structure. */ data = (MinPackData *) adata; /* Initialise a pointer to the current returned residual value. */ vr = hx; /* Initialise a pointer to the sampled Y values for the polynomial output. */ py = data->y[ 0 ]; /* Initialise a pointer to the powers of the input X values at the curent (i.e. first) sample. */ px1 = data->xp1; /* Loop over the index of the sample to which this residual refers. */ for( k = 0; k < data->nsamp; k++ ) { /* Initialise a pointer to the first coefficient (the constant term) for the polynomial output coordinate. */ vp = p; /* Initialise this residual to hold the sampled Y value. Increment the pointer to the next sampled value for the current polynomial output. */ res = -( *(py++) ); /* Loop over the coefficients. */ for( w1 = 0; w1 < data->order; w1++ ) { /* Increment the residual by the value of the current term Cw1*(x1^w1). Increment the pointer to the next coefficient (C). Also increment the pointer to the next higher power of X1. */ res += ( *(vp++) )*( *(px1++) ); } /* Store the complete residual in the returned array, and increment the pointer to the next residual. */ *(vr++) = res; } } static void LMFunc2D( const double *p, double *hx, int m, int n, void *adata ){ /* * Name: * LMFunc2D * Purpose: * Evaluate a test 2D polynomal. * Type: * Private function. * Synopsis: * void LMFunc2D( const double *p, double *hx, int m, int n, void *adata ) * Description: * This function finds the residuals implied by a supplied set of * candidate polynomial coefficients. Each residual is a candidate * polynomial (either P1 or P2) evaluated at one of the sample points * (x1,x2), minus the supplied target value for the polynomial at that * test point. * * The minimisation process minimises the sum of the squared residuals. * Parameters: * p * An array of "m" coefficients for the candidate polynomial. All the * coefficients for polynomial P1 come first, followed by those for P2. * Within each each polynomial, the coefficients are order C00, C10, * C01, C20, C11, C02, C30, C21, C12, C03, etc. So the coefficient * of (x1^j*x2^k) (=Cjk) for polynomial Pi is stored in element * [k + (j + k)*(j + k + 1)/2 + i*order*(order+1)/2] of the "p" array. * hx * An array in which to return the "n" residuals. The residual at * sample "k" for polynomial "i" is returned in element (k + nsamp*i). * m * The length of the "p" array. This should be equal to order*(order+1). * n * The length of the "hx" array. This should be equal to 2*nsamp. * adata * Pointer to a structure holding the sample positions and values, * and other information. */ /* Local Variables: */ MinPackData *data; const double *vp0; const double *vp; double *py; double *px1; double *px10; double *px20; double *vr; double res; double *px2; int iout; int k; int w12; int w2; /* Get a pointer to the data structure. */ data = (MinPackData *) adata; /* Initialise a pointer to the current returned residual value. */ vr = hx; /* Initilise a pointer to the first coefficient (the constant term) for the current (i.e. first) polynomial output coordinate. */ vp0 = p; /* Loop over each polynomial output coordinate. */ for( iout = 0; iout < 2; iout++ ) { /* Initialise a pointer to the sampled Y values for the first polynomial output. */ py = data->y[ iout ]; /* Initialise pointers to the powers of the input X values at the curent (i.e. first) sample. */ px10 = data->xp1; px20 = data->xp2; /* Loop over the index of the sample to which this residual refers. */ for( k = 0; k < data->nsamp; k++ ) { /* Reset the pointer to the first coefficient (the constant term) for the current polynomial output coordinate. */ vp = vp0; /* Initialise this residual to hold the sampled Y value. Increment the pointer to the next sampled value for the current polynomial output. */ res = -( *(py++) ); /* The w12 value is the sum of the powers of X1 and X2. So w12=0 corresponds to the constant term in the polynomial, and (e.g.) w12=6 corresponds to all the terms for which the sum of the powerss (w1+w2) is 6. Loop over all possible w12 values. */ for( w12 = 0; w12 < data->order; w12++ ) { /* The next coeff refers to (x1^w12)*(x2^0). Get pointers to the values holding x1^w12 and x2^0. */ px1 = px10++; px2 = px20; /* Loop over powers of x2. The corresponding power of x1 is "w12-x2", but is not explicitly needed here. So x1 moves down from w12 to zero, as w2 moves up from zero to w12. */ for( w2 = 0; w2 <= w12; w2++ ) { /* Increment the residual by the value of the current term Cw1w2*(x1^w1)*(x2^w2). Increment the pointer tio the next coefficient (C). Also decrement the pointer to the next lower power of X1, and increment the pointer to the next higher power of X2. */ res += ( *(vp++) )*( *(px1--) )*( *(px2++) ); } } /* Move on to the x2 powers for the next sample. Don't need to do this for x1 since px10 is incremented within the above loop. */ px20 += data->order; /* Store the complete residual in the returned array, and increment the pointer to the next residual. */ *(vr++) = res; } /* Get a pointer to the first coefficient (the constant term) for the next polynomial output coordinate. */ vp0 += data->order*( 1 + data->order )/2; } } static void LMJacob1D( const double *p, double *jac, int m, int n, void *adata ){ /* * Name: * LMJacob1D * Purpose: * Evaluate the Jacobian matrix of a test 1D polynomal. * Type: * Private function. * Synopsis: * void LMJacob1D( const double *p, double *jac, int m, int n, void *adata ) * Description: * This function finds the Jacobian matrix that describes the rate of * change of every residual with respect to every polynomial coefficient. * Each residual is a candidate polynomial evaluated at one of the sample * points minus the supplied target value for the polynomial at that test * point. * * For a polynomial the Jacobian matrix is constant (i.e. does not * depend on the values of the polynomial coefficients). So we only * evaluate it on the first call. * Parameters: * p * An array of "m" coefficients for the candidate polynomial. * jac * An array in which to return the "m*n" elements of the Jacobian * matrix. The rate of change of residual "r" with respect to * coefficient "c" is returned in element "r + c*n". The residual * at sample "k" of polynomial Pi has an "r" index of (k + nsamp*i). * The coefficient of (x1^j) for polynomial Pi has a "c" index * of j. * m * The length of the "p" array. This should be equal to order. * n * The number of residuals. This should be equal to nsamp. * adata * Pointer to a structure holding the sample positions and values, * and other information. */ /* Local Variables: */ MinPackData *data; int k; int w1; /* Get a pointer to the data structure. */ data = (MinPackData *) adata; /* The Jacobian of the residuals with respect to the polynomial coefficients is constant (i.e. does not depend on the values of the polynomial coefficients). So we only need to calculate it once. If this is the first call, calculate the Jacobian and return it in "jac". otherwise, just return immediately retaining the supplied "jac" values (which will be the values returned by the previous call to this function). */ if( data->init_jac ) { data->init_jac = 0; /* Loop over all residuals. */ for( k = 0; k < n; k++ ) { /* Loop over all parameters (i.e. polynomial coefficients). */ for( w1 = 0; w1 < m; w1++ ) { /* Store the Jacobian. */ jac[ k + w1*n ] = (data->xp1)[ w1 + k*data->order ]; } } } } static void LMJacob2D( const double *p, double *jac, int m, int n, void *adata ){ /* * Name: * LMJacob2D * Purpose: * Evaluate the Jacobian matrix of a test 2D polynomal. * Type: * Private function. * Synopsis: * void LMJacob2D( const double *p, double *jac, int m, int n, void *adata ) * Description: * This function finds the Jacobian matrix that describes the rate of * change of every residual with respect to every polynomial coefficient. * Each residual is a candidate polynomial (either P1 or P2) evaluated * at one of the sample points (x1,x2), minus the supplied target value * for the polynomial at that test point. * * For a polynomial the Jacobian matrix is constant (i.e. does not * depend on the values of the polynomial coefficients). So we only * evaluate it on the first call. * Parameters: * p * An array of "m" coefficients for the candidate polynomial. All the * coefficients for polynomial P1 come first, followed by those for P2. * Within each each polynomial, the coefficients are order C00, C10, * C01, C20, C11, C02, C30, C21, C12, C03, etc. So the coefficient * of (x1^j*x2^k) (=Cjk) for polynomial Pi is stored in element * [k + (j + k)*(j + k + 1)/2 + i*order*(order+1)/2] of the "p" array. * jac * An array in which to return the "m*n" elements of the Jacobian * matrix. The rate of change of residual "r" with respect to * coefficient "c" is returned in element "r + c*n". The residual * at sample "k" of polynomial Pi has an "r" index of (k + nsamp*i). * The coefficient of (x1^j*x2^k) for polynomial Pi has a "c" index * of [k + (j + k)*(j + k + 1)/2 + i*order*(order+1)/2]. * m * The length of the "p" array. This should be equal to order*(order+1). * n * The number of residuals. This should be equal to 2*nsamp. * adata * Pointer to a structure holdin gthe sample positions and values, * and other information. */ /* Local Variables: */ MinPackData *data; int iout; int k; int ncof; int vp; int vr; int w1; int w12; int w2; /* Get a pointer to the data structure. */ data = (MinPackData *) adata; /* The Jacobian of the residuals with respect to the polynomial coefficients is constant (i.e. does not depend on the values of the polynomial coefficients). So we only need to calculate it once. If this is the first call, calculate the Jacobian and return it in "jac". otherwise, just return immediately retaining the supplied "jac" values (which will be the values returned by the previous call to this function). */ if( data->init_jac ) { data->init_jac = 0; /* Store the number of coefficients in one polynomial. */ ncof = data->order*( 1 + data->order )/2; /* Loop over all residuals. */ for( vr = 0; vr < n; vr++ ) { /* Calculate the polynomial output index, and sample index, that creates the current residual. */ iout = vr/data->nsamp; k = vr - iout*data->nsamp; /* Loop over all parameters (i.e. polynomial coefficients). */ for( vp = 0; vp < m; vp++ ) { /* If this coefficient is not used in the creation of the current polynomial output value, then the Jacobian value is zero. */ if( vp/ncof != iout ) { jac[ vr + vp*n ] = 0.0; /* Otherwise, get the powers of the two polynomial inputs, to which the current coefficient relates. */ } else { w12 = ( -1.0 + sqrt( 1.0 + 8.0*(vp - iout*ncof) ) )/2.0; w2 = vp - iout*ncof - w12*( w12 + 1 )/2; w1 = w12 - w2; /* Store the Jacobian. */ jac[ vr + vp*n ] = (data->xp1)[ w1 + k*data->order ]* (data->xp2)[ w2 + k*data->order ]; } } } } } #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: * PolyMap 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: */ AstPolyMap *this; int ic; int result; int nc; /* Initialise */ result = 0; /* Check the supplied pointer is not NULL. */ if( !this_object ) return result; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Invoke the ManageLock method inherited from the parent class. */ if( !result ) result = (*parent_managelock)( this_object, mode, extra, fail, status ); /* Invoke the astManageLock method on any Objects contained within the supplied Object. */ if( this->jacobian ) { nc = astGetNin( this ); for( ic = 0; ic < nc && result; ic++ ) { result = astManageLock( (this->jacobian)[ ic ], mode, extra, fail ); } } return result; } #endif static int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a PolyMap. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * PolyMap method (over-rides the protected astMapMerge method * inherited from the Mapping class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated PolyMap in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated PolyMap with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated PolyMap which is to be merged with * its neighbours. This should be a cloned copy of the PolyMap * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * PolyMap it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated PolyMap resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstPolyMap *pmap0; /* Nominated PolyMap */ AstPolyMap *pmap1; /* Neighbouring PolyMap */ int i; /* Index of neighbour */ int iax_in; /* Index of input coordinate */ int iax_out; /* Index of output coordinate */ int ico; /* Index of coefficient */ int inv0; /* Supplied Invert flag for nominated PolyMap */ int inv1; /* Supplied Invert flag for neighbouring PolyMap */ int nc; /* Number of coefficients */ int nin; /* Number of input coordinates for nominated PolyMap */ int nout; /* Number of output coordinates for nominated PolyMap */ int ok; /* Are PolyMaps equivalent? */ int result; /* Result value to return */ int swap0; /* Swap inputs and outputs for nominated PolyMap? */ int swap1; /* Swap inputs and outputs for neighbouring PolyMap? */ /* Initialise. */ result = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Save a pointer to the nominated PolyMap. */ pmap0 = (AstPolyMap *) ( *map_list )[ where ]; /* The only simplification which can currently be performed is to merge a PolyMap with its own inverse. This can only be done in series. Obviously, there are potentially other simplications which could be performed, but time does not currently allow these to be coded. */ if( series ) { /* Set a flag indicating if "input" and "output" needs to be swapped for the nominated PolyMap. */ inv0 = ( *invert_list )[ where ]; swap0 = ( inv0 != astGetInvert( pmap0 ) ); /* Get the number of inputs and outputs to the nominated PolyMap. */ nin = !swap0 ? astGetNin( pmap0 ) : astGetNout( pmap0 ); nout = !swap0 ? astGetNout( pmap0 ) : astGetNin( pmap0 ); /* Check each neighbour. */ for( i = where - 1; i <= where + 1; i += 2 ) { /* Continue with the next pass if the neighbour does not exist. */ if( i < 0 || i >= *nmap ) continue; /* Continue with the next pass if this neighbour is not a PermMap. */ if( strcmp( "PolyMap", astGetClass( ( *map_list )[ i ] ) ) ) continue; /* Get a pointer to it. */ pmap1 = (AstPolyMap *) ( *map_list )[ i ]; /* Check it is used in the opposite direction to the nominated PolyMap. */ if( ( *invert_list )[ i ] == ( *invert_list )[ where ] ) continue; /* Set a flag indicating if "input" and "output" needs to be swapped for the neighbouring PolyMap. */ inv1 = ( *invert_list )[ i ]; swap1 = ( inv1 != astGetInvert( pmap1 ) ); /* Check the number of inputs and outputs are equal to the nominated PolyMap. */ if( astGetNin( pmap1 ) != (!swap1 ? nin : nout ) && astGetNout( pmap1 ) != (!swap1 ? nout : nin ) ) continue; /* Check the forward coefficients are equal. */ ok = 1; for( iax_out = 0; iax_out < nout && ok; iax_out++ ) { nc = pmap1->ncoeff_f[ iax_out ]; if( nc != pmap0->ncoeff_f[ iax_out ] ) continue; for( ico = 0; ico < nc && ok; ico++ ) { if( !astEQUAL( pmap1->coeff_f[ iax_out ][ ico ], pmap0->coeff_f[ iax_out ][ ico ] ) ){ ok = 0; } else { for( iax_in = 0; iax_in < nin && ok; iax_in++ ) { ok = ( pmap1->power_f[ iax_out ][ ico ][ iax_in ] == pmap0->power_f[ iax_out ][ ico ][ iax_in ] ); } } } } if( !ok ) continue; /* Check the inverse coefficients are equal. */ ok = 1; for( iax_in = 0; iax_in < nin && ok; iax_in++ ) { nc = pmap1->ncoeff_i[ iax_in ]; if( nc != pmap0->ncoeff_i[ iax_in ] ) continue; for( ico = 0; ico < nc && ok; ico++ ) { if( !astEQUAL( pmap1->coeff_i[ iax_in ][ ico ], pmap0->coeff_i[ iax_in ][ ico ] ) ){ ok = 0; } else { for( iax_out = 0; iax_out < nout && ok; iax_out++ ) { ok = ( pmap1->power_i[ iax_in ][ ico ][ iax_out ] == pmap0->power_i[ iax_in ][ ico ][ iax_out ] ); } } } } if( !ok ) continue; /* If we get this far, then the nominated PolyMap and the current neighbour cancel each other out, so replace each by a UnitMap. */ (void) astAnnul( pmap0 ); (void) astAnnul( pmap1 ); if( i < where ) { ( *map_list )[ where ] = (AstMapping *) astUnitMap( nout, "", status ); ( *map_list )[ i ] = (AstMapping *) astUnitMap( nout, "", status ); ( *invert_list )[ where ] = 0; ( *invert_list )[ i ] = 0; result = i; } else { ( *map_list )[ where ] = (AstMapping *) astUnitMap( nin, "", status ); ( *map_list )[ i ] = (AstMapping *) astUnitMap( nin, "", status ); ( *invert_list )[ where ] = 0; ( *invert_list )[ i ] = 0; result = where; } /* Leave the loop. */ break; } } /* Return the result. */ return result; } static int MPFunc1D( void *p, int m, int n, const double *x, double *fvec, double *fjac, int ldfjac, int iflag ) { /* * Name: * MPFunc1D * Purpose: * Evaluate a test 1D polynomal or its Jacobian. * Type: * Private function. * Synopsis: * int MPFunc1D( void *p, int m, int n, const double *x, double *fvec, * double *fjac, int ldfjac, int iflag ) * Description: * This function finds the residuals or Jacobian implied by a supplied * set of candidate polynomial coefficients. Each residual is a candidate * polynomial evaluated at one of the sample points, minus the * supplied target value for the polynomial at that test point. * * The minimisation process minimises the sum of the squared residuals. * Parameters: * p * A pointer to data needed to evaluate the required residuals or * Jacobians. * m * The number of residuals. * n * The number of coefficients. * x * An array of "n" coefficients for the candidate polynomial. * fvec * An array in which to return the "m" residuals. * fjac * An array in which to return the "mxn" Jacobian values. * ldflac * Unused (should always be equal to "m"). * iflag * If 1 calculate the residuals, otherwise calculate the Jacobians. */ /* If required, calculate the function values at X, and return this vector in fvec. Do not alter fjac. */ if( iflag == 1 ) { LMFunc1D( x, fvec, n, m, p ); /* Otherwise, calculate the Jacobian values at X, and return this matrix in fjac. Do not alter fvec. */ } else { LMJacob1D( x, fjac, n, m, p ); } return 0; } static int MPFunc2D( void *p, int m, int n, const double *x, double *fvec, double *fjac, int ldfjac, int iflag ) { /* * Name: * MPFunc1D * Purpose: * Evaluate a test 2D polynomal or its Jacobian. * Type: * Private function. * Synopsis: * int MPFunc2D( void *p, int m, int n, const double *x, double *fvec, * double *fjac, int ldfjac, int iflag ) * Description: * This function finds the residuals or Jacobian implied by a supplied * set of candidate polynomial coefficients. Each residual is a candidate * polynomial evaluated at one of the sample points, minus the * supplied target value for the polynomial at that test point. * * The minimisation process minimises the sum of the squared residuals. * Parameters: * p * A pointer to data needed to evaluate the required residuals or * Jacobians. * m * The number of residuals. * n * The number of coefficients. * x * An array of "n" coefficients for the candidate polynomial. * fvec * An array in which to return the "m" residuals. * fjac * An array in which to return the "mxn" Jacobian values. * ldflac * Unused (should always be equal to "m"). * iflag * If 1 calculate the residuals, otherwise calculate the Jacobians. */ /* If required, calculate the function values at X, and return this vector in fvec. Do not alter fjac. */ if( iflag == 1 ) { LMFunc2D( x, fvec, n, m, p ); /* Otherwise, calculate the Jacobian values at X, and return this matrix in fjac. Do not alter fvec. */ } else { LMJacob2D( x, fjac, n, m, p ); } return 0; } static AstPolyMap *PolyTran( AstPolyMap *this, int forward, double acc, double maxacc, int maxorder, const double *lbnd, const double *ubnd, int *status ){ /* *++ * Name: c astPolyTran f AST_POLYTRAN * Purpose: * Fit a PolyMap inverse or forward transformation. * Type: * Public function. * Synopsis: c #include "polymap.h" c AstPolyMap *astPolyTran( AstPolyMap *this, int forward, double acc, c double maxacc, int maxorder, const double *lbnd, c const double *ubnd ) f RESULT = AST_POLYTRAN( THIS, FORWARD, ACC, MAXACC, MAXORDER, LBND, f UBND, STATUS ) * Class Membership: * PolyMap method. * Description: * This function creates a new PolyMap which is a copy of the supplied * PolyMap, in which a specified transformation (forward or inverse) * has been replaced by a new polynomial transformation. The * coefficients of the new transformation are estimated by sampling * the other transformation and performing a least squares polynomial * fit in the opposite direction to the sampled positions and values. * * This method can only be used on (1-input,1-output) or (2-input,2-output) * PolyMaps. * * The transformation to create is specified by the c "forward" parameter. f FORWARD parameter. * In what follows "X" refers to the inputs of the PolyMap, and "Y" to * the outputs of the PolyMap. The forward transformation transforms * input values (X) into output values (Y), and the inverse transformation * transforms output values (Y) into input values (X). Within a PolyMap, * each transformation is represented by an independent set of * polynomials, P_f or P_i: Y=P_f(X) for the forward transformation and * X=P_i(Y) for the inverse transformation. * c The "forward" f The FORWARD * parameter specifies the transformation to be replaced. If it is c non-zero, f is .TRUE., * a new forward transformation is created * by first finding the input values (X) using the inverse transformation * (which must be available) at a regular grid of points (Y) covering a * rectangular region of the PolyMap's output space. The coefficients of * the required forward polynomial, Y=P_f(X), are chosen in order to * minimise the sum of the squared residuals between the sampled values * of Y and P_f(X). * c If "forward" is zero (probably the most likely case), f If FORWARD is .FALSE. (probably the most likely case), * a new inverse transformation is created by * first finding the output values (Y) using the forward transformation * (which must be available) at a regular grid of points (X) covering a * rectangular region of the PolyMap's input space. The coefficients of * the required inverse polynomial, X=P_i(Y), are chosen in order to * minimise the sum of the squared residuals between the sampled values * of X and P_i(Y). * * This fitting process is performed repeatedly with increasing * polynomial orders (starting with linear) until the target * accuracy is achieved, or a specified maximum order is reached. If * the target accuracy cannot be achieved even with this maximum-order * polynomial, the best fitting maximum-order polynomial is returned so * long as its accuracy is better than c "maxacc". f MAXACC. * If it is not, an error is reported. * Parameters: c this f THIS = INTEGER (Given) * Pointer to the original Mapping. c forward f FORWARD = LOGICAL (Given) c If non-zero, f If .TRUE., * the forward PolyMap transformation is replaced. Otherwise the * inverse transformation is replaced. c acc f ACC = DOUBLE (Given) * The target accuracy, expressed as a geodesic distance within * the PolyMap's input space (if c "forward" is zero) or output space (if "forward" is non-zero). f FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). c maxacc f MAXACC = DOUBLE (Given) * The maximum allowed accuracy for an acceptable polynomial, * expressed as a geodesic distance within the PolyMap's input * space (if c "forward" is zero) or output space (if "forward" is non-zero). f FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). c maxorder f MAXORDER = INTEGER (Given) * The maximum allowed polynomial order. This is one more than the * maximum power of either input axis. So for instance, a value of * 3 refers to a quadratic polynomial. Note, cross terms with total * powers greater than or equal to c maxorder f MAXORDER * are not inlcuded in the fit. So the maximum number of terms in * each of the fitted polynomials is c maxorder*(maxorder+1)/2. f MAXORDER*(MAXORDER+1)/2. c lbnd f LBND( * ) = DOUBLE PRECISION (Given) c Pointer to an f An * array holding the lower bounds of a rectangular region within * the PolyMap's input space (if c "forward" is zero) or output space (if "forward" is non-zero). f FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). * The new polynomial will be evaluated over this rectangle. The * length of this array should equal the value of the PolyMap's Nin * or Nout attribute, depending on c "forward". f FORWARD. c ubnd f UBND( * ) = DOUBLE PRECISION (Given) c Pointer to an f An * array holding the upper bounds of a rectangular region within * the PolyMap's input space (if c "forward" is zero) or output space (if "forward" is non-zero). f FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). * The new polynomial will be evaluated over this rectangle. The * length of this array should equal the value of the PolyMap's Nin * or Nout attribute, depending on c "forward". f FORWARD. f STATUS = INTEGER (Given and Returned) f The global status. * Returned Value: c astPolyTran() f AST_POLYTRAN = INTEGER * A pointer to the new PolyMap. c A NULL pointer f AST__NULL * will be returned if the fit fails to achieve the accuracy * specified by c "maxacc", f MAXACC, * but no error will be reported. * Notes: * - This function can only be used on 1D or 2D PolyMaps which have * the same number of inputs and outputs. * - 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: */ AstPolyMap *result; int ok; /* Initialise. */ result = NULL; /* Check the inherited status. */ if ( !astOK ) return result; /* Take a copy of the supplied PolyMap. */ result = astCopy( this ); /* Replace the required transformation. */ ok = ReplaceTransformation( result, forward, acc, maxacc, maxorder, lbnd, ubnd, status ); /* If an error occurred, or the fit was not good enough, annul the returned PolyMap. */ if ( !ok || !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int ReplaceTransformation( AstPolyMap *this, int forward, double acc, double maxacc, int maxorder, const double *lbnd, const double *ubnd, int *status ){ /* * Name: * ReplaceTransformation * Purpose: * Create a new inverse or forward transformation for a PolyMap. * Type: * Private function. * Synopsis: * int ReplaceTransformation( AstPolyMap *this, int forward, double acc, * double maxacc, int maxorder, const double *lbnd, * const double *ubnd, int *status ) * Description: * This function creates a new forward or inverse transformation for * the supplied PolyMap (replacing any existing transformation), by * sampling the other transformation and performing a least squares * polynomial fit to the sample positions and values. * * The transformation to create is specified by the "forward" parameter. * In what follows "X" refers to the inputs of the PolyMap, and "Y" to * the outputs of the PolyMap. The forward transformation transforms * input values (X) into output values (Y), and the inverse transformation * transforms output values (Y) into input values (X). Within a PolyMap, * each transformation is represented by an independent set of * polynomials: Y=P_f(X) for the forward transformation and X=P_i(Y) * for the inverse transformation. * * If "forward" is zero then a new inverse transformation is created by * first finding the output values (Y) using the forward transformation * (which must be available) at a regular grid of points (X) covering a * rectangular region of the PolyMap's input space. The coefficients of * the required inverse polynomial, X=P_i(Y), are chosen in order to * minimise the sum of the squared residuals between the sampled values * of X and P_i(Y). * * If "forward" is non-zero then a new forward transformation is created * by first finding the input values (X) using the inverse transformation * (which must be available) at a regular grid of points (Y) covering a * rectangular region of the PolyMap's output space. The coefficients of * the required forward polynomial, Y=P_f(X), are chosen in order to * minimise the sum of the squared residuals between the sampled values * of Y and P_f(X). * * This fitting process is performed repeatedly with increasing * polynomial orders (starting with linear) until the target * accuracy is achieved, or a specified maximum order is reached. If * the target accuracy cannot be achieved even with this maximum-order * polynomial, the best fitting maximum-order polynomial is returned so * long as its accuracy is better than "maxacc". * Parameters: * this * The PolyMap. * forward * If non-zero, then the forward PolyMap transformation is * replaced. Otherwise the inverse transformation is replaced. * acc * The target accuracy, expressed as a geodesic distance within * the PolyMap's input space (if "forward" is zero) or output * space (if "forward" is non-zero). * maxacc * The maximum allowed accuracy for an acceptable polynomial, * expressed as a geodesic distance within the PolyMap's input * space (if "forward" is zero) or output space (if "forward" is * non-zero). * maxorder * The maximum allowed polynomial order. This is one more than the * maximum power of either input axis. So for instance, a value of * 3 refers to a quadratic polynomial. Note, cross terms with total * powers greater than or equal to maxorder are not inlcuded in the * fit. So the maximum number of terms in each of the fitted polynomials * is maxorder*(maxorder+1)/2. * lbnd * An array holding the lower bounds of a rectangular region within * the PolyMap's input space (if "forward" is zero) or output * space (if "forward" is non-zero). The new polynomial will be * evaluated over this rectangle. * ubnd * An array holding the upper bounds of a rectangular region within * the PolyMap's input space (if "forward" is zero) or output * space (if "forward" is non-zero). The new polynomial will be * evaluated over this rectangle. * status * Pointer to the inherited status variable. * Returned Value: * - Non-zero if a fit was performed succesfully, to at least the * maximum allowed accuracy. Zero if the fit failed, or an error * occurred. * Notes: * - No error is reported if the fit fails to achieve the required * maximum accuracy. * - An error is reported if the transformation that is not being * replaced is not defined. * - An error is reported if the PolyMap does not have equal numbers * of inputs and outputs. * - An error is reported if the PolyMap has more than 2 inputs or outputs. */ /* Local Variables: */ double **table; double *cofs; double racc; double scales[ 4 ]; int ndim; int ncof; int nsamp; int order; int result; /* Check inherited status */ if( !astOK ) return 0; /* Check the PolyMap can be used. */ ndim = astGetNin( this ); if( astGetNout( this ) != ndim && astOK ) { astError( AST__BADNI, "astPolyTran(%s): Supplied %s has " "different number of inputs (%d) and outputs (%d).", status, astGetClass( this ), astGetClass( this ), ndim, astGetNout( this ) ); } else if( ndim > 2 && astOK ) { astError( AST__BADNI, "astPolyTran(%s): Supplied %s has " "too many inputs and outputs (%d) - must be 1 or 2.", status, astGetClass( this ), astGetClass( this ), ndim ); } if( forward != astGetInvert( this ) ){ if( ! this->ncoeff_i && astOK ) { astError( AST__NODEF, "astPolyTran(%s): Supplied %s has " "no inverse transformation.", status, astGetClass( this ), astGetClass( this ) ); } } else { if( ! this->ncoeff_f && astOK ) { astError( AST__NODEF, "astPolyTran(%s): Supplied %s has " "no forward transformation.", status, astGetClass( this ), astGetClass( this ) ); } } /* Check the bounds can be used. */ if( lbnd[ 0 ] >= ubnd[ 0 ] && astOK ) { astError( AST__NODEF, "astPolyTran(%s): Supplied upper " "bound for the first axis (%g) is less than or equal to the " "supplied lower bound (%g).", status, astGetClass( this ), lbnd[ 0 ], ubnd[ 0 ] ); } else if( ndim == 2 && lbnd[ 1 ] >= ubnd[ 1 ] && astOK ) { astError( AST__NODEF, "astPolyTran(%s): Supplied upper " "bound for the second axis (%g) is less than or equal to the " "supplied lower bound (%g).", status, astGetClass( this ), lbnd[ 1 ], ubnd[ 1 ] ); } /* Initialise pointer to work space. */ table = NULL; /* Loop over increasing polynomial orders until the required accuracy is achieved, up to the specified maximum order. The "order" value is one more than the maximum power in the polynomial (so a quadratic has "order" 3). */ if( maxorder < 2 ) maxorder = 2; for( order = 2; order <= maxorder; order++ ) { /* First do 2D PolyMaps. */ if( ndim == 2 ) { /* Sample the requested polynomial transformation at a grid of points. This grid covers the user-supplied region, using 2*order points on each axis. If the PolyMap is 1D, then it will be treated as a 2D polynomial in which the second output is a unit transformation. */ table = SamplePoly2D( this, !forward, table, lbnd, ubnd, 2*order, &nsamp, scales, status ); /* Fit the polynomial. Always fit a linear polynomial ("order" 2) to any dummy second axis. If successfull, replace the PolyMap transformation and break out of the order loop. */ cofs = FitPoly2D( nsamp, acc, order, table, scales, &ncof, &racc, status ); /* Now do 1D PolyMaps. */ } else { table = SamplePoly1D( this, !forward, table, lbnd[ 0 ], ubnd[ 0 ], 2*order, &nsamp, scales, status ); cofs = FitPoly1D( nsamp, acc, order, table, scales, &ncof, &racc, status ); } /* If the fit was succesful, replace the PolyMap transformation and break out of the order loop. */ if( cofs && ( racc < acc || ( racc < maxacc && order == maxorder ) ) ) { StoreArrays( this, forward, ncof, cofs, status ); break; } else { cofs = astFree( cofs ); } } /* If no fit was produced, return zero. */ result = cofs ? 1 : 0; /* Free resources. */ cofs = astFree( cofs ); table = astFreeDouble( table ); /* Return the result. */ return result; } static double **SamplePoly1D( AstPolyMap *this, int forward, double **table, double lbnd, double ubnd, int npoint, int *nsamp, double scales[2], int *status ){ /* * Name: * SamplePoly1D * Purpose: * Create a table of input and output positions for a 1D PolyMap. * Type: * Private function. * Synopsis: * double **SamplePoly1D( AstPolyMap *this, int forward, double **table, * double lbnd, double ubnd, int npoint, int *nsamp, * double scales[2], int *status ) * Description: * This function creates a table containing samples of the requested * polynomial transformation at a grid of input points. This grid covers * the user-supplied region, using "npoint" points. * Parameters: * this * The PolyMap. * forward * If non-zero, then the forward PolyMap transformation is sampled. * Otherwise the inverse transformation is sampled. * table * Pointer to a previous table created by this function, which is * to be re-used, or NULL. * lbnd * The lower bounds of the region within the PolyMap's 1D input space * (if "forward" is non-zero) or output space (if "forward" is zero). * The new polynomial will be evaluated over this region. * ubnd * The upper bounds of the region within the PolyMap's 1D input space * (if "forward" is non-zero) or output space (if "forward" is zero). * The new polynomial will be evaluated over this region. * npoint * The number of points to use. * nsamp * Address of an int in which to return the total number of samples * in the returned table. * scales * Array in which to return the scaling factors for the two columns * of the returned table. Multiplying the returned table values by * the scale factor produces PolyMap input or output axis values. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to an array of 2 pointers. Each of these pointers points * to an array of "nsamp" doubles, being the sampled values for y1 * and x1 in that order. Here x1 is the input value for the sampled * transformation (these are spaced on the regular grid specified * by lbnd, ubnd and npoint), and y1 is the output position produced * by the sampled transformation. The returned values are scaled so * that each column has an RMS value of 1.0. The scaling factors that * convert scaled values into original values are returned in "scales". * The returned pointer should be freed using astFreeDouble when no * longer needed. */ /* Local Variables: */ AstPointSet *ps1; AstPointSet *ps2; double **result; double *p0; double *p1; double *ptr1[ 1 ]; double *ptr2[ 1 ]; double delta0; double rms; double sum; double val0; int i; int icol; /* Initialise returned value */ result = table; *nsamp = 0; /* Check inherited status */ if( !astOK ) return result; /* Ensure we have a table of the correct size. */ *nsamp = npoint; if( !result ) result = astCalloc( 2, sizeof( double * ) ); if( result ) { for( i = 0; i < 2; i++ ) { result[ i ] = astRealloc( result[ i ] , (*nsamp)*sizeof( double ) ); } } /* Work out the step sizes for the grid. */ delta0 = ( ubnd - lbnd )/( npoint - 1 ); /* Create a PointSet to hold the grid of input positions. Use column 1 of the table to hold the PointSet values. */ ps1 = astPointSet( *nsamp, 1, " ", status ); ptr1[ 0 ] = result[ 1 ]; astSetPoints( ps1, ptr1 ); /* Create a PointSet to hold the grid of output positions. Use column 0 of the table to hold the PointSet values. */ ps2 = astPointSet( *nsamp, 1, " ", status ); ptr2[ 0 ] = result[ 0 ]; astSetPoints( ps2, ptr2 ); if( astOK ) { /* Calculate the grid of input positions and store in the PointSet and therefore also in the returned table. */ val0 = lbnd; p0 = ptr1[ 0 ]; for( i = 0; i < npoint; i++ ) { *(p0++) = val0; val0 += delta0; } /* Transform the input grid to get the output grid. */ (void) astTransform( this, ps1, forward, ps2 ); /* Scale each column in turn. */ for( icol = 0; icol < 2; icol++ ) { /* Find the RMS of the values in the column. */ sum = 0.0; p0 = result[ icol ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) sum += ( *p0 )*( *p0 ); rms = sqrt( sum/(*nsamp) ); /* Divide the table values by the RMS. */ p0 = result[ icol ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) *p0 /= rms; /* Return the RMS as the scale factor. */ scales[ icol ] = rms; } } /* Free resources */ ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); /* If an error occurred, free the returned array. */ if( !astOK ) result = astFreeDouble( result ); /* Return a pointer to the table. */ return result; } static double **SamplePoly2D( AstPolyMap *this, int forward, double **table, const double *lbnd, const double *ubnd, int npoint, int *nsamp, double scales[4], int *status ){ /* * Name: * SamplePoly2D * Purpose: * Create a table of input and output positions for a 2D PolyMap. * Type: * Private function. * Synopsis: * double **SamplePoly2D( AstPolyMap *this, int forward, double **table, * const double *lbnd, const double *ubnd, int npoint, * int *nsamp, double scales[4], int *status ) * Description: * This function creates a table containing samples of the requested * polynomial transformation at a grid of input points. This grid covers * the user-supplied region, using "npoint" points on each axis. * Parameters: * this * The PolyMap. * forward * If non-zero, then the forward PolyMap transformation is sampled. * Otherwise the inverse transformation is sampled. * table * Pointer to a previous table created by this function, which is * to be re-used, or NULL. * lbnd * An array holding the lower bounds of a rectangular region within * the PolyMap's input space (if "forward" is non-zero) or output * space (if "forward" is zero). The new polynomial will be * evaluated over this rectangle. * ubnd * An array holding the upper bounds of a rectangular region within * the PolyMap's input space (if "forward" is non-zero) or output * space (if "forward" is zero). The new polynomial will be * evaluated over this rectangle. * npoint * The number of points along each edge of the grid. * nsamp * Address of an int in which to return the total number of samples * in the returned table. * scales * Array in which to return the scaling factors for the four * columns of the returned table. Multiplying the returned table * values by the scale factor produces PolyMap input or output axis * values. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to an array of 4 pointers. Each of these pointers points * to an array of "nsamp" doubles, being the sampled values for y1, * y2, x1 or x2 in that order. Here (x1,x2) are the input values * for the sampled transformation (these are spaced on the regular * grid specified by lbnd, ubnd and npoint), and (y1,y2) are the * output positions produced by the sampled transformation. The * returned values are scaled so that each column has an RMS value * of 1.0. The scaling factors that convert scaled values into * original values are returned in "scales". The returned pointer * should be freed using astFreeDouble when no longer needed. */ /* Local Variables: */ AstPointSet *ps1; AstPointSet *ps2; double **result; double *p0; double *p1; double *ptr1[ 2 ]; double *ptr2[ 2 ]; double delta1; double delta0; double rms; double sum; double val0; double val1; int i; int icol; int j; /* Initialise returned value */ result = table; *nsamp = 0; /* Check inherited status */ if( !astOK ) return result; /* Ensure we have a table of the correct size. */ *nsamp = npoint*npoint; if( !result ) result = astCalloc( 4, sizeof( double * ) ); if( result ) { for( i = 0; i < 4; i++ ) { result[ i ] = astRealloc( result[ i ] , (*nsamp)*sizeof( double ) ); } } /* Work out the step sizes for the grid. */ delta0 = ( ubnd[ 0 ] - lbnd[ 0 ] )/( npoint - 1 ); delta1 = ( ubnd[ 1 ] - lbnd[ 1 ] )/( npoint - 1 ); /* Create a PointSet to hold the grid of input positions. Use columns 2 and 3 of the table to hold the PointSet values. */ ps1 = astPointSet( *nsamp, 2, " ", status ); ptr1[ 0 ] = result[ 2 ]; ptr1[ 1 ] = result[ 3 ]; astSetPoints( ps1, ptr1 ); /* Create a PointSet to hold the grid of output positions. Use columns 0 and 1 of the table to hold the PointSet values. */ ps2 = astPointSet( *nsamp, 2, " ", status ); ptr2[ 0 ] = result[ 0 ]; ptr2[ 1 ] = result[ 1 ]; astSetPoints( ps2, ptr2 ); if( astOK ) { /* Calculate the grid of input positions and store in the PointSet and therefore also in the returned table. */ val0 = lbnd[ 0 ]; p0 = ptr1[ 0 ]; p1 = ptr1[ 1 ]; for( i = 0; i < npoint; i++ ) { val1 = lbnd[ 1 ]; for( j = 0; j < npoint; j++ ) { *(p0++) = val0; *(p1++) = val1; val1 += delta1; } val0 += delta0; } /* Transform the input grid to get the output grid. */ (void) astTransform( this, ps1, forward, ps2 ); /* Scale each pair of columns in turn. Use the ssame scale factor for each axis in order to ensure an isotropic metric. */ for( icol = 0; icol < 4; icol += 2 ) { /* Find the RMS of the values in the two columns. */ sum = 0.0; p0 = result[ icol ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) sum += ( *p0 )*( *p0 ); p0 = result[ icol + 1 ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) sum += ( *p0 )*( *p0 ); rms = sqrt( sum/(2*(*nsamp)) ); /* Divide the table values by the RMS. */ p0 = result[ icol ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) *p0 /= rms; p0 = result[ icol + 1 ]; p1 = p0 + (*nsamp); for( ; p0 < p1; p0++ ) *p0 /= rms; /* Return the RMS as the scale factor. */ scales[ icol ] = rms; scales[ icol + 1 ] = rms; } } /* Free resources */ ps1 = astAnnul( ps1 ); ps2 = astAnnul( ps2 ); /* If an error occurred, free the returned array. */ if( !astOK ) result = astFreeDouble( result ); /* Return a pointer to the table. */ return result; } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a PolyMap. * Type: * Private function. * Synopsis: * #include "polymap.h" * void SetAttrib( AstObject *this, const char *setting ) * Class Membership: * PolyMap member function (over-rides the astSetAttrib protected * method inherited from the Mapping class). * Description: * This function assigns an attribute value for a PolyMap, 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 PolyMap. * setting * Pointer to a null-terminated string specifying the new attribute * value. */ /* Local Variables: */ AstPolyMap *this; /* Pointer to the PolyMap structure */ double dval; /* Floating point attribute value */ int ival; /* Integer attribute value */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* IterInverse. */ /* ------------ */ if ( nc = 0, ( 1 == astSscanf( setting, "iterinverse= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetIterInverse( this, ival ); /* NiterInverse. */ /* ------------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "niterinverse= %d %n", &ival, &nc ) ) && ( nc >= len ) ) { astSetNiterInverse( this, ival ); /* TolInverse. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "tolinverse= %lg %n", &dval, &nc ) ) && ( nc >= len ) ) { astSetTolInverse( this, dval ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void StoreArrays( AstPolyMap *this, int forward, int ncoeff, const double *coeff, int *status ){ /* * Name: * StoreArrays * Purpose: * Store the dynamic arrays for a single transformation within a PolyMap * Type: * Private function. * Synopsis: * #include "polymap.h" * void StoreArrays( AstPolyMap *this, int forward, int ncoeff, * const double *coeff, int *status ) * Class Membership: * PolyMap initialiser. * Description: * This function sets up the arrays within a PolyMap structure that * describes either the forward or inverse transformation. * Parameters: * this * The PolyMap. * forward * If non-zero, replace the forward transformation. Otherwise, * replace the inverse transformation. * ncoeff * The number of non-zero coefficients necessary to define the * specified transformation of the PolyMap. If zero is supplied, the * transformation will be undefined. * coeff * An array containing "ncof*( 2 + nin )" elements. Each group * of "2 + nin" adjacent elements describe a single coefficient of * the transformation. Within each such group, the first * element is the coefficient value; the next element is the * integer index of the PolyMap output which uses the coefficient * within its defining polynomial (the first output has index 1); * the remaining elements of the group give the integer powers to * use with each input coordinate value (powers must not be * negative). * status * Pointer to inherited status. */ /* Local Variables: */ const double *group; /* Pointer to start of next coeff. description */ int *pows; /* Pointer to powers for current coeff. */ int gsize; /* Length of each coeff. description */ int i; /* Loop count */ int ico; /* Index of next coeff. for current input or output */ int iin; /* Input index extracted from coeff. description */ int iout; /* Output index extracted from coeff. description */ int j; /* Loop count */ int nin; /* Number of inputs */ int nout; /* Number of outputs */ int pow; /* Power extracted from coeff. description */ /* Check the global status. */ if ( !astOK ) return; /* Get the number of inputs and outputs. */ nin = astGetNin( this ); nout = astGetNout( this ); /* First Free any existing arrays. */ FreeArrays( this, forward, status ); /* Now initialise the forward transformation, if required. */ if( forward && ncoeff > 0 ) { /* Create the arrays decribing the forward transformation. */ this->ncoeff_f = astMalloc( sizeof( int )*(size_t) nout ); this->mxpow_f = astMalloc( sizeof( int )*(size_t) nin ); this->power_f = astMalloc( sizeof( int ** )*(size_t) nout ); this->coeff_f = astMalloc( sizeof( double * )*(size_t) nout ); if( astOK ) { /* Initialise the count of coefficients for each output coordinate to zero. */ for( i = 0; i < nout; i++ ) this->ncoeff_f[ i ] = 0; /* Initialise max power for each input coordinate to zero. */ for( j = 0; j < nin; j++ ) this->mxpow_f[ j ] = 0; /* Scan through the supplied forward coefficient array, counting the number of coefficients which relate to each output. Also find the highest power used for each input axis. Report errors if any unusable values are found in the supplied array. */ group = coeff; gsize = 2 + nin; for( i = 0; i < ncoeff && astOK; i++, group += gsize ) { iout = floor( group[ 1 ] + 0.5 ); if( iout < 1 || iout > nout ) { astError( AST__BADCI, "astInitPolyMap(%s): Forward " "coefficient %d referred to an illegal output " "coordinate %d.", status, astGetClass( this ), i + 1, iout ); astError( AST__BADCI, "This number should be in the " "range 1 to %d.", status, nout ); break; } this->ncoeff_f[ iout - 1 ]++; for( j = 0; j < nin; j++ ) { pow = floor( group[ 2 + j ] + 0.5 ); if( pow < 0 ) { astError( AST__BADPW, "astInitPolyMap(%s): Forward " "coefficient %d has a negative power (%d) " "for input coordinate %d.", status, astGetClass( this ), i + 1, pow, j + 1 ); astError( AST__BADPW, "All powers should be zero or " "positive." , status); break; } if( pow > this->mxpow_f[ j ] ) this->mxpow_f[ j ] = pow; } } /* Allocate the arrays to store the input powers associated with each coefficient, and the coefficient values. Reset the coefficient count for each axis to zero afterwards so that we can use the array as an index to the next vacant slot withint he following loop. */ for( i = 0; i < nout; i++ ) { this->power_f[ i ] = astMalloc( sizeof( int * )* (size_t) this->ncoeff_f[ i ] ); this->coeff_f[ i ] = astMalloc( sizeof( double )* (size_t) this->ncoeff_f[ i ] ); this->ncoeff_f[ i ] = 0; } if( astOK ) { /* Extract the coefficient values and powers form the supplied array and store them in the arrays created above. */ group = coeff; for( i = 0; i < ncoeff && astOK; i++, group += gsize ) { iout = floor( group[ 1 ] + 0.5 ) - 1; ico = ( this->ncoeff_f[ iout ] )++; this->coeff_f[ iout ][ ico ] = group[ 0 ]; pows = astMalloc( sizeof( int )*(size_t) nin ); this->power_f[ iout ][ ico ] = pows; if( astOK ) { for( j = 0; j < nin; j++ ) { pows[ j ] = floor( group[ 2 + j ] + 0.5 ); } } } } } } /* Now initialise the inverse transformation, if required. */ if( !forward && ncoeff > 0 ) { /* Create the arrays decribing the inverse transformation. */ this->ncoeff_i = astMalloc( sizeof( int )*(size_t) nin ); this->mxpow_i = astMalloc( sizeof( int )*(size_t) nout ); this->power_i = astMalloc( sizeof( int ** )*(size_t) nin ); this->coeff_i = astMalloc( sizeof( double * )*(size_t) nin ); if( astOK ) { /* Initialise the count of coefficients for each input coordinate to zero. */ for( i = 0; i < nin; i++ ) this->ncoeff_i[ i ] = 0; /* Initialise max power for each output coordinate to zero. */ for( j = 0; j < nout; j++ ) this->mxpow_i[ j ] = 0; /* Scan through the supplied inverse coefficient array, counting the number of coefficients which relate to each input. Also find the highest power used for each output axis. Report errors if any unusable values are found in the supplied array. */ group = coeff; gsize = 2 + nout; for( i = 0; i < ncoeff && astOK; i++, group += gsize ) { iin = floor( group[ 1 ] + 0.5 ); if( iin < 1 || iin > nin ) { astError( AST__BADCI, "astInitPolyMap(%s): Inverse " "coefficient %d referred to an illegal input " "coordinate %d.", status, astGetClass( this ), i + 1, iin ); astError( AST__BADCI, "This number should be in the " "range 1 to %d.", status, nin ); break; } this->ncoeff_i[ iin - 1 ]++; for( j = 0; j < nout; j++ ) { pow = floor( group[ 2 + j ] + 0.5 ); if( pow < 0 ) { astError( AST__BADPW, "astInitPolyMap(%s): Inverse " "coefficient %d has a negative power (%d) " "for output coordinate %d.", status, astGetClass( this ), i + 1, pow, j + 1 ); astError( AST__BADPW, "All powers should be zero or " "positive." , status); break; } if( pow > this->mxpow_i[ j ] ) this->mxpow_i[ j ] = pow; } } /* Allocate the arrays to store the output powers associated with each coefficient, and the coefficient values. Reset the coefficient count for each axis to zero afterwards so that we can use the array as an index to the next vacant slot within the following loop. */ for( i = 0; i < nin; i++ ) { this->power_i[ i ] = astMalloc( sizeof( int * )* (size_t) this->ncoeff_i[ i ] ); this->coeff_i[ i ] = astMalloc( sizeof( double )* (size_t) this->ncoeff_i[ i ] ); this->ncoeff_i[ i ] = 0; } if( astOK ) { /* Extract the coefficient values and powers form the supplied array and store them in the arrays created above. */ group = coeff; for( i = 0; i < ncoeff && astOK; i++, group += gsize ) { iin = floor( group[ 1 ] + 0.5 ) - 1; ico = ( this->ncoeff_i[ iin ] )++; this->coeff_i[ iin ][ ico ] = group[ 0 ]; pows = astMalloc( sizeof( int )*(size_t) nout ); this->power_i[ iin ][ ico ] = pows; if( astOK ) { for( j = 0; j < nout; j++ ) { pows[ j ] = floor( group[ 2 + j ] + 0.5 ); } } } } } } } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a PolyMap. * Type: * Private function. * Synopsis: * #include "polymap.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * PolyMap member function (over-rides the astTestAttrib protected * method inherited from the Mapping class). * Description: * This function returns a boolean result (0 or 1) to indicate whether * a value has been set for one of a PolyMap's attributes. * Parameters: * this * Pointer to the PolyMap. * 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: */ AstPolyMap *this; /* Pointer to the PolyMap structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* IterInverse. */ /* ------------ */ if ( !strcmp( attrib, "iterinverse" ) ) { result = astTestIterInverse( this ); /* NiterInverse. */ /* ------------- */ } else if ( !strcmp( attrib, "niterinverse" ) ) { result = astTestNiterInverse( this ); /* TolInverse. */ /* ----------- */ } else if ( !strcmp( attrib, "tolinverse" ) ) { result = astTestTolInverse( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static AstPointSet *Transform( AstMapping *this, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a PolyMap to transform a set of points. * Type: * Private function. * Synopsis: * #include "polymap.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * PolyMap member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a PolyMap and a set of points encapsulated in a * PointSet and transforms the points. * Parameters: * this * Pointer to the PolyMap. * 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: * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of columns in the PolyMap being applied. * - The number of coordinate values per point in the output PointSet will * equal the number of rows in the PolyMap being applied. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstPointSet *result; /* Pointer to output PointSet */ AstPolyMap *map; /* Pointer to PolyMap to be applied */ double **coeff; /* Pointer to coefficient value arrays */ double **ptr_in; /* Pointer to input coordinate data */ double **ptr_out; /* Pointer to output coordinate data */ double **work; /* Pointer to exponentiated axis values */ double *outcof; /* Pointer to next coefficient value */ double *pwork; /* Pointer to exponentiated axis values */ double outval; /* Output axis value */ double term; /* Term to be added to output value */ double x; /* Input axis value */ double xp; /* Exponentiated input axis value */ int ***power; /* Pointer to coefficient power arrays */ int **outpow; /* Pointer to next set of axis powers */ int *mxpow; /* Pointer to max used power for each input */ int *ncoeff; /* Pointer to no. of coefficients */ int in_coord; /* Index of output coordinate */ int ico; /* Coefficient index */ int ip; /* Axis power */ int nc; /* No. of coefficients in polynomial */ int ncoord_in; /* Number of coordinates per input point */ int ncoord_out; /* Number of coordinates per output point */ int npoint; /* Number of points */ int out_coord; /* Index of output coordinate */ int point; /* Loop counter for points */ int pow; /* Next axis power */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the PolyMap. */ map = (AstPolyMap *) this; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Mapping class. This function validates all arguments and generates an output PointSet if necessary, but does not actually transform any coordinate values. */ result = (*parent_transform)( this, in, forward, out, status ); /* Determine whether to apply the forward or inverse mapping, according to the direction specified and whether the mapping has been inverted. */ if ( astGetInvert( map ) ) forward = !forward; /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* If we are using the inverse transformatiom, and the IterInverse attribute is non-zero, use an iterative inverse algorithm rather than any inverse transformation defined within the PolyMap. */ if( !forward && astGetIterInverse(map) ) { IterInverse( map, in, result, status ); /* Otherwise, determine the numbers of points and coordinates per point from the input and output PointSets and obtain pointers for accessing the input and output coordinate values. */ } else { ncoord_in = astGetNcoord( in ); ncoord_out = astGetNcoord( result ); npoint = astGetNpoint( in ); ptr_in = astGetPoints( in ); ptr_out = astGetPoints( result ); /* Get a pointer to the arrays holding the required coefficient values and powers, according to the direction of mapping required. */ if ( forward ) { ncoeff = map->ncoeff_f; coeff = map->coeff_f; power = map->power_f; mxpow = map->mxpow_f; } else { ncoeff = map->ncoeff_i; coeff = map->coeff_i; power = map->power_i; mxpow = map->mxpow_i; } /* Allocate memory to hold the required powers of the input axis values. */ work = astMalloc( sizeof( double * )*(size_t) ncoord_in ); for( in_coord = 0; in_coord < ncoord_in; in_coord++ ) { work[ in_coord ] = astMalloc( sizeof( double )*(size_t) ( mxpow[ in_coord ] + 1 ) ); } /* Perform coordinate arithmetic. */ /* ------------------------------ */ if ( astOK ) { /* Loop to apply the polynomial to each point in turn.*/ for ( point = 0; point < npoint; point++ ) { /* Find the required powers of the input axis values and store them in the work array. */ for( in_coord = 0; in_coord < ncoord_in; in_coord++ ) { pwork = work[ in_coord ]; pwork[ 0 ] = 1.0; x = ptr_in[ in_coord ][ point ]; if( x == AST__BAD ) { for( ip = 1; ip <= mxpow[ in_coord ]; ip++ ) pwork[ ip ] = AST__BAD; } else { for( ip = 1; ip <= mxpow[ in_coord ]; ip++ ) { pwork[ ip ] = pwork[ ip - 1 ]*x; } } } /* Loop round each output. */ for( out_coord = 0; out_coord < ncoord_out; out_coord++ ) { /* Initialise the output value. */ outval = 0.0; /* Get pointers to the coefficients and powers for this output. */ outcof = coeff[ out_coord ]; outpow = power[ out_coord ]; /* Loop round all polynomial coefficients.*/ nc = ncoeff[ out_coord ]; for ( ico = 0; ico < nc && outval != AST__BAD; ico++, outcof++, outpow++ ) { /* Initialise the current term to be equal to the value of the coefficient. If it is bad, store a bad output value. */ term = *outcof; if( term == AST__BAD ) { outval = AST__BAD; /* Otherwise, loop round all inputs */ } else { for( in_coord = 0; in_coord < ncoord_in; in_coord++ ) { /* Get the power of the current input axis value used by the current coefficient. If it is zero, pass on. */ pow = (*outpow)[ in_coord ]; if( pow > 0 ) { /* Get the axis value raised to the appropriate power. */ xp = work[ in_coord ][ pow ]; /* If bad, set the output value bad and break. */ if( xp == AST__BAD ) { outval = AST__BAD; break; /* Otherwise multiply the current term by the exponentiated axis value. */ } else { term *= xp; } } } } /* Increment the output value by the current term of the polynomial. */ outval += term; } /* Store the output value. */ ptr_out[ out_coord ][ point ] = outval; } } } /* Free resources. */ for( in_coord = 0; in_coord < ncoord_in; in_coord++ ) { work[ in_coord ] = astFree( work[ in_coord ] ); } work = astFree( work ); } /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* *att++ * Name: * IterInverse * Purpose: * Provide an iterative inverse transformation? * Type: * Public attribute. * Synopsis: * Integer (boolean). * Description: * This attribute indicates whether the inverse transformation of * the PolyMap should be implemented via an iterative Newton-Raphson * approximation that uses the forward transformation to transform * candidate input positions until an output position is found which * is close to the required output position. By default, an iterative * inverse is provided if, and only if, no inverse polynomial was supplied * when the PolyMap was constructed. * * The NiterInverse and TolInverse attributes provide parameters that * control the behaviour of the inverse approcimation method. * Applicability: * PolyMap * All PolyMaps have this attribute. * Notes: * - An iterative inverse can only be used if the PolyMap has equal * numbers of inputs and outputs, as given by the Nin and Nout * attributes. An error will be reported if IterInverse is set non-zero * for a PolyMap that does not meet this requirement. *att-- */ astMAKE_CLEAR(PolyMap,IterInverse,iterinverse,-INT_MAX) astMAKE_GET(PolyMap,IterInverse,int,0,( ( this->iterinverse == -INT_MAX ) ? (this->ncoeff_i == 0) : this->iterinverse )) astMAKE_SET(PolyMap,IterInverse,int,iterinverse, (((astGetNin(this)==astGetNout(this))||!value)?((value?1:0)):(astError(AST__ATTIN,"astSetIterInverse(%s):" "Cannot use an iterative inverse because the %s has unequal numbers of " "inputs and outputs.", status, astGetClass(this),astGetClass(this)),this->iterinverse))) astMAKE_TEST(PolyMap,IterInverse,( this->iterinverse != -INT_MAX )) /* NiterInverse. */ /* --------- */ /* *att++ * Name: * NiterInverse * Purpose: * Maximum number of iterations for the iterative inverse transformation. * Type: * Public attribute. * Synopsis: * Integer. * Description: * This attribute controls the iterative inverse transformation * used if the IterInverse attribute is non-zero. * * Its value gives the maximum number of iterations of the * Newton-Raphson algorithm to be used for each transformed position. * The default value is 4. See also attribute TolInverse. * Applicability: * PolyMap * All PolyMaps have this attribute. *att-- */ astMAKE_CLEAR(PolyMap,NiterInverse,niterinverse,-INT_MAX) astMAKE_GET(PolyMap,NiterInverse,int,0,( this->niterinverse == -INT_MAX ? 4 : this->niterinverse)) astMAKE_SET(PolyMap,NiterInverse,int,niterinverse,value) astMAKE_TEST(PolyMap,NiterInverse,( this->niterinverse != -INT_MAX )) /* TolInverse. */ /* ----------- */ /* *att++ * Name: * TolInverse * Purpose: * Target relative error for the iterative inverse transformation. * Type: * Public attribute. * Synopsis: * Floating point. * Description: * This attribute controls the iterative inverse transformation * used if the IterInverse attribute is non-zero. * * Its value gives the target relative error in teh axis values of * each transformed position. Further iterations will be performed * until the target relative error is reached, or the maximum number * of iterations given by attribute NiterInverse is reached. * The default value is 1.0E-6. * Applicability: * PolyMap * All PolyMaps have this attribute. *att-- */ astMAKE_CLEAR(PolyMap,TolInverse,tolinverse,AST__BAD) astMAKE_GET(PolyMap,TolInverse,double,0.0,( this->tolinverse == AST__BAD ? 1.0E-6 : this->tolinverse)) astMAKE_SET(PolyMap,TolInverse,double,tolinverse,value) astMAKE_TEST(PolyMap,TolInverse,( this->tolinverse != AST__BAD )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for PolyMap objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for PolyMap objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy, including a copy of the * coefficients associated with the input PolyMap. */ /* Local Variables: */ AstPolyMap *in; /* Pointer to input PolyMap */ AstPolyMap *out; /* Pointer to output PolyMap */ int nin; /* No. of input coordinates */ int nout; /* No. of output coordinates */ int i; /* Loop count */ int j; /* Loop count */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output PolyMaps. */ in = (AstPolyMap *) objin; out = (AstPolyMap *) objout; /* Nullify the pointers stored in the output object since these will currently be pointing at the input data (since the output is a simple byte-for-byte copy of the input). Otherwise, the input data could be freed by accidient if the output object is deleted due to an error occuring in this function. */ out->ncoeff_f = NULL; out->power_f = NULL; out->coeff_f = NULL; out->mxpow_f = NULL; out->ncoeff_i = NULL; out->power_i = NULL; out->coeff_i = NULL; out->mxpow_i = NULL; out->jacobian = NULL; /* Get the number of inputs and outputs of the uninverted Mapping. */ nin = ( (AstMapping *) in )->nin; nout = ( (AstMapping *) in )->nout; /* Copy the number of coefficients associated with each output of the forward transformation. */ if( in->ncoeff_f ) { out->ncoeff_f = (int *) astStore( NULL, (void *) in->ncoeff_f, sizeof( int )*(size_t) nout ); /* Copy the maximum power of each input axis value used by the forward transformation. */ out->mxpow_f = (int *) astStore( NULL, (void *) in->mxpow_f, sizeof( int )*(size_t) nin ); /* Copy the coefficient values used by the forward transformation. */ if( in->coeff_f ) { out->coeff_f = astMalloc( sizeof( double * )*(size_t) nout ); if( astOK ) { for( i = 0; i < nout; i++ ) { out->coeff_f[ i ] = (double *) astStore( NULL, (void *) in->coeff_f[ i ], sizeof( double )*(size_t) in->ncoeff_f[ i ] ); } } } /* Copy the input axis powers associated with each coefficient of the forward transformation. */ if( in->power_f ) { out->power_f = astMalloc( sizeof( int ** )*(size_t) nout ); if( astOK ) { for( i = 0; i < nout; i++ ) { out->power_f[ i ] = astMalloc( sizeof( int * )*(size_t) in->ncoeff_f[ i ] ); if( astOK ) { for( j = 0; j < in->ncoeff_f[ i ]; j++ ) { out->power_f[ i ][ j ] = (int *) astStore( NULL, (void *) in->power_f[ i ][ j ], sizeof( int )*(size_t) nin ); } } } } } } /* Do the same for the inverse transformation. */ if( in->ncoeff_i ) { out->ncoeff_i = (int *) astStore( NULL, (void *) in->ncoeff_i, sizeof( int )*(size_t) nin ); out->mxpow_i = (int *) astStore( NULL, (void *) in->mxpow_i, sizeof( int )*(size_t) nout ); if( in->coeff_i ) { out->coeff_i = astMalloc( sizeof( double * )*(size_t) nin ); if( astOK ) { for( i = 0; i < nin; i++ ) { out->coeff_i[ i ] = (double *) astStore( NULL, (void *) in->coeff_i[ i ], sizeof( double )*(size_t) in->ncoeff_i[ i ] ); } } } if( in->power_i ) { out->power_i = astMalloc( sizeof( int ** )*(size_t) nin ); if( astOK ) { for( i = 0; i < nin; i++ ) { out->power_i[ i ] = astMalloc( sizeof( int * )*(size_t) in->ncoeff_i[ i ] ); if( astOK ) { for( j = 0; j < in->ncoeff_i[ i ]; j++ ) { out->power_i[ i ][ j ] = (int *) astStore( NULL, (void *) in->power_i[ i ][ j ], sizeof( int )*(size_t) nout ); } } } } } } /* If an error has occurred, free al the resources allocated above. */ if( !astOK ) { FreeArrays( out, 1, status ); FreeArrays( out, 0, status ); } return; } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for PolyMap objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for PolyMap objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstPolyMap *this; int nc; int ic; int lstat; int error; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) obj; /* Free the arrays. */ FreeArrays( this, 1, status ); FreeArrays( this, 0, status ); /* Free the resources used to store the Jacobian of the forward transformation. */ if( this->jacobian ) { /* Get the number of PolyMap inputs. We need to clear any error status first since astGetNin returns zero if an error has occurred. The Jacobian will only be non-NULL if the number of inputs and outputs are equal. */ error = !astOK; if( error ) { lstat = astStatus; astClearStatus; } nc = astGetNin( this ); if( error ) astSetStatus( lstat ); for( ic = 0; ic < nc; ic++ ) { (this->jacobian)[ ic ] = astAnnul( (this->jacobian)[ ic ] ); } this->jacobian = astFree( this->jacobian ); } } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for PolyMap 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 PolyMap class to an output Channel. * Parameters: * this * Pointer to the PolyMap whose data are being written. * channel * Pointer to the Channel to which the data are being written. * status * Pointer to the inherited status variable. */ #define KEY_LEN 50 /* Maximum length of a keyword */ /* Local Variables: */ AstPolyMap *this; /* Pointer to the PolyMap structure */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ char comm[ 100 ]; /* Buffer for comment string */ double dval; /* Floating point attribute value */ int i; /* Loop index */ int iv; /* Vectorised keyword index */ int ival; /* Integer value */ int j; /* Loop index */ int k; /* Loop index */ int nin; /* No. of input coords */ int nout; /* No. of output coords */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the PolyMap structure. */ this = (AstPolyMap *) this_object; /* Find the number of inputs and outputs of the uninverted Mapping. */ nin = ( (AstMapping *) this )->nin; nout = ( (AstMapping *) this )->nout; /* Write out values representing the instance variables for the PolyMap class. */ /* First do the forward transformation arrays. Check they are used. */ if( this->ncoeff_f ) { /* Store the maximum power of each input axis value used by the forward transformation. */ for( i = 0; i < nin; i++ ){ (void) sprintf( buff, "MPF%d", i + 1 ); (void) sprintf( comm, "Max. power of input %d in any forward polynomial", i + 1 ); astWriteInt( channel, buff, 1, 1, (this->mxpow_f)[ i ], comm ); } /* Store the number of coefficients associated with each output of the forward transformation. */ for( i = 0; i < nout; i++ ){ (void) sprintf( buff, "NCF%d", i + 1 ); (void) sprintf( comm, "No. of coeff.s for forward polynomial %d", i + 1 ); astWriteInt( channel, buff, 1, 1, (this->ncoeff_f)[ i ], comm ); } /* Store the coefficient values used by the forward transformation. */ iv = 1; for( i = 0; i < nout; i++ ){ for( j = 0; j < this->ncoeff_f[ i ]; j++, iv++ ){ if( (this->coeff_f)[ i ][ j ] != AST__BAD ) { (void) sprintf( buff, "CF%d", iv ); (void) sprintf( comm, "Coeff %d of forward polynomial %d", j + 1, i + 1 ); astWriteDouble( channel, buff, 1, 1, (this->coeff_f)[ i ][ j ], comm ); } } } /* Store the input axis powers associated with each coefficient of the forward transformation. */ iv = 1; for( i = 0; i < nout; i++ ){ for( j = 0; j < this->ncoeff_f[ i ]; j++ ){ for( k = 0; k < nin; k++, iv++ ){ if( (this->power_f)[ i ][ j ][ k ] > 0 ) { (void) sprintf( buff, "PF%d", iv ); (void) sprintf( comm, "Power of i/p %d for coeff %d of fwd poly %d", k + 1, j + 1, i + 1 ); astWriteDouble( channel, buff, 1, 1, (this->power_f)[ i ][ j ][ k ], comm ); } } } } } /* Now do the inverse transformation arrays. Check they are used. */ if( this->ncoeff_i ) { /* Store the maximum power of each output axis value used by the inverse transformation. */ for( i = 0; i < nout; i++ ){ (void) sprintf( buff, "MPI%d", i + 1 ); (void) sprintf( comm, "Max. power of output %d in any inverse polynomial", i + 1 ); astWriteInt( channel, buff, 1, 1, (this->mxpow_i)[ i ], comm ); } /* Store the number of coefficients associated with each input of the inverse transformation. */ for( i = 0; i < nin; i++ ){ (void) sprintf( buff, "NCI%d", i + 1 ); (void) sprintf( comm, "No. of coeff.s for inverse polynomial %d", i + 1 ); astWriteInt( channel, buff, 1, 1, (this->ncoeff_i)[ i ], comm ); } /* Store the coefficient values used by the inverse transformation. */ iv = 1; for( i = 0; i < nin; i++ ){ for( j = 0; j < this->ncoeff_i[ i ]; j++, iv++ ){ if( (this->coeff_i)[ i ][ j ] != AST__BAD ) { (void) sprintf( buff, "CI%d", iv ); (void) sprintf( comm, "Coeff %d of inverse polynomial %d", j + 1, i + 1 ); astWriteDouble( channel, buff, 1, 1, (this->coeff_i)[ i ][ j ], comm ); } } } /* Store the output axis powers associated with each coefficient of the inverse transformation. */ iv = 1; for( i = 0; i < nin; i++ ){ for( j = 0; j < this->ncoeff_i[ i ]; j++ ){ for( k = 0; k < nout; k++, iv++ ){ if( (this->power_i)[ i ][ j ][ k ] > 0 ) { (void) sprintf( buff, "PI%d", iv ); (void) sprintf( comm, "Power of o/p %d for coeff %d of inv poly %d", k + 1, j + 1, i + 1 ); astWriteDouble( channel, buff, 1, 1, (this->power_i)[ i ][ j ][ k ], comm ); } } } } } /* Use an iterative inverse? */ set = TestIterInverse( this, status ); ival = set ? GetIterInverse( this, status ) : astGetIterInverse( this ); astWriteInt( channel, "IterInv", set, 0, ival, ival ? "Use an iterative inverse" : "Do not use an iterative inverse" ); /* Max number of iterations for iterative inverse. */ set = TestNiterInverse( this, status ); ival = set ? GetNiterInverse( this, status ) : astGetNiterInverse( this ); astWriteInt( channel, "NiterInv", set, 0, ival, "Max number of iterations for iterative inverse" ); /* Target relative error for iterative inverse. */ set = TestTolInverse( this, status ); dval = set ? GetTolInverse( this, status ) : astGetTolInverse( this ); astWriteDouble( channel, "TolInv", set, 0, dval, "Target relative error for iterative inverse" ); /* Undefine macros local to this function. */ #undef KEY_LEN } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAPolyMap and astCheckPolyMap functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(PolyMap,Mapping) astMAKE_CHECK(PolyMap) AstPolyMap *astPolyMap_( int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], const char *options, int *status, ...){ /* *++ * Name: c astPolyMap f AST_POLYMAP * Purpose: * Create a PolyMap. * Type: * Public function. * Synopsis: c #include "polymap.h" c AstPolyMap *astPolyMap( int nin, int nout, int ncoeff_f, const double coeff_f[], c int ncoeff_i, const double coeff_i[], c const char *options, ... ) f RESULT = AST_POLYMAP( NIN, NOUT, NCOEFF_F, COEFF_F, NCOEFF_I, COEFF_I, f OPTIONS, STATUS ) * Class Membership: * PolyMap constructor. * Description: * This function creates a new PolyMap and optionally initialises * its attributes. * * A PolyMap is a form of Mapping which performs a general polynomial * transformation. Each output coordinate is a polynomial function of * all the input coordinates. The coefficients are specified separately * for each output coordinate. The forward and inverse transformations * are defined independantly by separate sets of coefficients. If no * inverse transformation is supplied, an iterative method can be used * to evaluate the inverse based only on the forward transformation. * Parameters: c nin f NIN = INTEGER (Given) * The number of input coordinates. c nout f NOUT = INTEGER (Given) * The number of output coordinates. c ncoeff_f f NCOEFF_F = INTEGER (Given) * The number of non-zero coefficients necessary to define the * forward transformation of the PolyMap. If zero is supplied, the * forward transformation will be undefined. c coeff_f f COEFF_F( * ) = DOUBLE PRECISION (Given) * An array containing c "ncoeff_f*( 2 + nin )" elements. Each group of "2 + nin" f "NCOEFF_F*( 2 + NIN )" elements. Each group of "2 + NIN" * adjacent elements describe a single coefficient of the forward * transformation. Within each such group, the first element is the * coefficient value; the next element is the integer index of the * PolyMap output which uses the coefficient within its defining * polynomial (the first output has index 1); the remaining elements * of the group give the integer powers to use with each input * coordinate value (powers must not be negative, and floating * point values are rounded to the nearest integer). c If "ncoeff_f" is zero, a NULL pointer may be supplied for "coeff_f". * * For instance, if the PolyMap has 3 inputs and 2 outputs, each group * consisting of 5 elements, A groups such as "(1.2, 2.0, 1.0, 3.0, 0.0)" * describes a coefficient with value 1.2 which is used within the * definition of output 2. The output value is incremented by the * product of the coefficient value, the value of input coordinate * 1 raised to the power 1, and the value of input coordinate 2 raised * to the power 3. Input coordinate 3 is not used since its power is * specified as zero. As another example, the group "(-1.0, 1.0, * 0.0, 0.0, 0.0 )" describes adds a constant value -1.0 onto * output 1 (it is a constant value since the power for every input * axis is given as zero). * c Each final output coordinate value is the sum of the "ncoeff_f" terms c described by the "ncoeff_f" groups within the supplied array. f Each final output coordinate value is the sum of the "NCOEFF_F" terms f described by the "NCOEFF_F" groups within the supplied array. c ncoeff_i f NCOEFF_I = INTEGER (Given) * The number of non-zero coefficients necessary to define the * inverse transformation of the PolyMap. If zero is supplied, the * inverse transformation will be undefined. c coeff_i f COEFF_I( * ) = DOUBLE PRECISION (Given) * An array containing c "ncoeff_i*( 2 + nout )" elements. Each group of "2 + nout" f "NCOEFF_I*( 2 + NOUT )" elements. Each group of "2 + NOUT" * adjacent elements describe a single coefficient of the inverse c transformation, using the same schame as "coeff_f", f transformation, using the same schame as "COEFF_F", * except that "inputs" and "outputs" are transposed. c If "ncoeff_i" is zero, a NULL pointer may be supplied for "coeff_i". 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 PolyMap. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new PolyMap. The syntax used is identical to that for the f AST_SET routine. 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 astPolyMap() f AST_POLYMAP = INTEGER * A pointer to the new PolyMap. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPolyMap *new; /* Pointer to new PolyMap */ va_list args; /* Variable argument list */ /* Check the global status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise the PolyMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPolyMap( NULL, sizeof( AstPolyMap ), !class_init, &class_vtab, "PolyMap", nin, nout, ncoeff_f, coeff_f, ncoeff_i, coeff_i ); /* 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 PolyMap'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 PolyMap. */ return new; } AstPolyMap *astPolyMapId_( int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], const char *options, ... ){ /* * Name: * astPolyMapId_ * Purpose: * Create a PolyMap. * Type: * Private function. * Synopsis: * #include "polymap.h" * AstPolyMap *astPolyMap( int nin, int nout, int ncoeff_f, const double coeff_f[], * int ncoeff_i, const double coeff_i[], * const char *options, ... ) * Class Membership: * PolyMap constructor. * Description: * This function implements the external (public) interface to the * astPolyMap constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astPolyMap_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astPolyMap_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astPolyMap_. * Returned Value: * The ID value associated with the new PolyMap. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstPolyMap *new; /* Pointer to new PolyMap */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Initialise the PolyMap, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitPolyMap( NULL, sizeof( AstPolyMap ), !class_init, &class_vtab, "PolyMap", nin, nout, ncoeff_f, coeff_f, ncoeff_i, coeff_i ); /* 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 PolyMap'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 PolyMap. */ return astMakeId( new ); } AstPolyMap *astInitPolyMap_( void *mem, size_t size, int init, AstPolyMapVtab *vtab, const char *name, int nin, int nout, int ncoeff_f, const double coeff_f[], int ncoeff_i, const double coeff_i[], int *status ){ /* *+ * Name: * astInitPolyMap * Purpose: * Initialise a PolyMap. * Type: * Protected function. * Synopsis: * #include "polymap.h" * AstPolyMap *astInitPolyMap( void *mem, size_t size, int init, * AstPolyMapVtab *vtab, const char *name, * int nin, int nout, int ncoeff_f, * const double coeff_f[], int ncoeff_i, * const double coeff_i[] ) * Class Membership: * PolyMap initialiser. * Description: * This function is provided for use by class implementations to initialise * a new PolyMap object. It allocates memory (if necessary) to accommodate * the PolyMap plus any additional data associated with the derived class. * It then initialises a PolyMap 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 PolyMap at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the PolyMap is to be initialised. * This must be of sufficient size to accommodate the PolyMap data * (sizeof(PolyMap)) 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 PolyMap (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 PolyMap * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the PolyMap'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 PolyMap. * 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). * nin * The number of input coordinate values per point. This is the * same as the number of columns in the matrix. * nout * The number of output coordinate values per point. This is the * same as the number of rows in the matrix. * ncoeff_f * The number of non-zero coefficients necessary to define the * forward transformation of the PolyMap. If zero is supplied, the * forward transformation will be undefined. * coeff_f * An array containing "ncoeff_f*( 2 + nin )" elements. Each group * of "2 + nin" adjacent elements describe a single coefficient of * the forward transformation. Within each such group, the first * element is the coefficient value; the next element is the * integer index of the PolyMap output which uses the coefficient * within its defining polynomial (the first output has index 1); * the remaining elements of the group give the integer powers to * use with each input coordinate value (powers must not be * negative) * * For instance, if the PolyMap has 3 inputs and 2 outputs, each group * consisting of 5 elements, A groups such as "(1.2, 2.0, 1.0, 3.0, 0.0)" * describes a coefficient with value 1.2 which is used within the * definition of output 2. The output value is incremented by the * product of the coefficient value, the value of input coordinate * 1 raised to the power 1, and the value of input coordinate 2 raised * to the power 3. Input coordinate 3 is not used since its power is * specified as zero. As another example, the group "(-1.0, 1.0, * 0.0, 0.0, 0.0 )" describes adds a constant value -1.0 onto * output 1 (it is a constant value since the power for every input * axis is given as zero). * * Each final output coordinate value is the sum of the "ncoeff_f" terms * described by the "ncoeff_f" groups within the supplied array. * ncoeff_i * The number of non-zero coefficients necessary to define the * inverse transformation of the PolyMap. If zero is supplied, the * inverse transformation will be undefined. * coeff_i * An array containing * "ncoeff_i*( 2 + nout )" elements. Each group of "2 + nout" * adjacent elements describe a single coefficient of the inverse * transformation, using the same schame as "coeff_f", except that * "inputs" and "outputs" are transposed. * Returned Value: * A pointer to the new PolyMap. * 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: */ AstPolyMap *new; /* Pointer to new PolyMap */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitPolyMapVtab( vtab, name ); /* Initialise a Mapping structure (the parent class) as the first component within the PolyMap structure, allocating memory if necessary. Specify that the Mapping should be defined in both the forward and inverse directions. */ new = (AstPolyMap *) astInitMapping( mem, size, 0, (AstMappingVtab *) vtab, name, nin, nout, 1, 1 ); if ( astOK ) { /* Initialise the PolyMap data. */ /* ---------------------------- */ /* First initialise the pointers in case of errors. */ new->ncoeff_f = NULL; new->power_f = NULL; new->coeff_f = NULL; new->mxpow_f = NULL; new->ncoeff_i = NULL; new->power_i = NULL; new->coeff_i = NULL; new->mxpow_i = NULL; /* Store the forward transformation. */ StoreArrays( new, 1, ncoeff_f, coeff_f, status ); /* Store the inverse transformation. */ StoreArrays( new, 0, ncoeff_i, coeff_i, status ); /* Other class attributes. */ new->iterinverse = -INT_MAX; new->niterinverse = -INT_MAX; new->tolinverse = AST__BAD; new->jacobian = NULL; /* If an error occurred, clean up by deleting the new PolyMap. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new PolyMap. */ return new; } AstPolyMap *astLoadPolyMap_( void *mem, size_t size, AstPolyMapVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadPolyMap * Purpose: * Load a PolyMap. * Type: * Protected function. * Synopsis: * #include "polymap.h" * AstPolyMap *astLoadPolyMap( void *mem, size_t size, * AstPolyMapVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * PolyMap loader. * Description: * This function is provided to load a new PolyMap 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 * PolyMap structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a PolyMap at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the PolyMap is to be * loaded. This must be of sufficient size to accommodate the * PolyMap data (sizeof(PolyMap)) 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 PolyMap (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 PolyMap 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(AstPolyMap) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new PolyMap. If this is NULL, a pointer * to the (static) virtual function table for the PolyMap 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 "PolyMap" is used instead. * Returned Value: * A pointer to the new PolyMap. * 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. *- */ #define KEY_LEN 50 /* Maximum length of a keyword */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ /* Local Variables: */ AstPolyMap *new; /* Pointer to the new PolyMap */ char buff[ KEY_LEN + 1 ]; /* Buffer for keyword string */ int i; /* Loop index */ int iv; /* Vectorised keyword index */ int j; /* Loop index */ int k; /* Loop index */ int nin; /* No. of input coords */ int nout; /* No. of output coords */ int undef; /* Is the transformation undefined? */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this PolyMap. In this case the PolyMap belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstPolyMap ); vtab = &class_vtab; name = "PolyMap"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitPolyMapVtab( 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 PolyMap. */ new = astLoadMapping( mem, size, (AstMappingVtab *) vtab, name, channel ); if ( astOK ) { /* Get the number of inputs and outputs for the uninverted Mapping. */ nin = ( (AstMapping *) new )->nin; nout = ( (AstMapping *) new )->nout; /* Read input data. */ /* ================ */ /* Request the input Channel to read all the input data appropriate to this class into the internal "values list". */ astReadClassData( channel, "PolyMap" ); /* Allocate memory to hold the forward arrays. */ new->ncoeff_f = astMalloc( sizeof( int )*(size_t) nout ); new->mxpow_f = astMalloc( sizeof( int )*(size_t) nin ); new->power_f = astMalloc( sizeof( int ** )*(size_t) nout ); new->coeff_f = astMalloc( sizeof( double * )*(size_t) nout ); if( astOK ) { /* Assume the forward transformation is defined. */ undef = 0; /* Get the maximum power of each input axis value used by the forward transformation. Set a flag "undef" if no values relating to the forward transformation are found (this indicates that the forward transformation is not defined). */ for( i = 0; i < nin && !undef; i++ ){ (void) sprintf( buff, "mpf%d", i + 1 ); (new->mxpow_f)[ i ] = astReadInt( channel, buff, INT_MAX ); if( (new->mxpow_f)[ i ] == INT_MAX ) undef = 1; } /* Get the number of coefficients associated with each output of the forward transformation. */ for( i = 0; i < nout && !undef; i++ ){ (void) sprintf( buff, "ncf%d", i + 1 ); (new->ncoeff_f)[ i ] = astReadInt( channel, buff, INT_MAX ); if( (new->ncoeff_f)[ i ] == INT_MAX ) undef = 1; } /* Get the coefficient values used by the forward transformation. This uses new style vectorised key names if available. Otherwise it uses old style indexed names (which were superceded by vectorised names because they are shorter and so work better with FitsChans). */ iv = 0; for( i = 0; i < nout && !undef; i++ ){ (new->coeff_f)[ i ] = astMalloc( sizeof( double )* (size_t) new->ncoeff_f[ i ] ); if( astOK ) { for( j = 0; j < new->ncoeff_f[ i ]; j++ ){ (void) sprintf( buff, "cf%d", ++iv ); (new->coeff_f)[ i ][ j ] = astReadDouble( channel, buff, AST__BAD ); if( (new->coeff_f)[ i ][ j ] == AST__BAD ) { (void) sprintf( buff, "cf%d_%d", i + 1, j + 1 ); (new->coeff_f)[ i ][ j ] = astReadDouble( channel, buff, AST__BAD ); } } } } /* Get the input axis powers associated with each coefficient of the forward transformation. */ iv = 0; for( i = 0; i < nout && !undef; i++ ){ (new->power_f)[ i ] = astMalloc( sizeof( int * )* (size_t) new->ncoeff_f[ i ] ); if( astOK ) { for( j = 0; j < new->ncoeff_f[ i ]; j++ ){ (new->power_f)[ i ][ j ] = astMalloc( sizeof( int )* (size_t) nin ); if( astOK ) { for( k = 0; k < nin; k++ ){ (void) sprintf( buff, "pf%d", ++iv ); (new->power_f)[ i ][ j ][ k ] = astReadInt( channel, buff, 0 ); if( (new->power_f)[ i ][ j ][ k ] == 0 ) { (void) sprintf( buff, "pf%d_%d_%d", i + 1, j + 1, k + 1 ); (new->power_f)[ i ][ j ][ k ] = astReadInt( channel, buff, 0 ); } } } } } } /* Free the arrays if the forward transformation is undefined. */ if( undef ) { new->ncoeff_f = astFree( new->ncoeff_f ); new->mxpow_f = astFree( new->mxpow_f ); new->power_f = astFree( new->power_f ); new->coeff_f = astFree( new->coeff_f ); } } /* Allocate memory to hold the inverse arrays. */ new->ncoeff_i = astMalloc( sizeof( int )*(size_t) nin ); new->mxpow_i = astMalloc( sizeof( int )*(size_t) nout ); new->power_i = astMalloc( sizeof( int ** )*(size_t) nin ); new->coeff_i = astMalloc( sizeof( double * )*(size_t) nin ); if( astOK ) { /* Assume the inverse transformation is defined. */ undef = 0; /* Get the maximum power of each output axis value used by the inverse transformation. Set a flag "undef" if no values relating to the inverse transformation are found (this indicates that the inverse transformation is not defined). */ for( i = 0; i < nout && !undef; i++ ){ (void) sprintf( buff, "mpi%d", i + 1 ); (new->mxpow_i)[ i ] = astReadInt( channel, buff, INT_MAX ); if( (new->mxpow_i)[ i ] == INT_MAX ) undef = 1; } /* Get the number of coefficients associated with each input of the inverse transformation. */ for( i = 0; i < nin && !undef; i++ ){ (void) sprintf( buff, "nci%d", i + 1 ); (new->ncoeff_i)[ i ] = astReadInt( channel, buff, INT_MAX ); if( (new->ncoeff_i)[ i ] == INT_MAX ) undef = 1; } /* Get the coefficient values used by the inverse transformation. */ iv = 0; for( i = 0; i < nin && !undef; i++ ){ (new->coeff_i)[ i ] = astMalloc( sizeof( double )* (size_t) new->ncoeff_i[ i ] ); if( astOK ) { for( j = 0; j < new->ncoeff_i[ i ]; j++ ){ (void) sprintf( buff, "ci%d", ++iv ); (new->coeff_i)[ i ][ j ] = astReadDouble( channel, buff, AST__BAD ); if( (new->coeff_i)[ i ][ j ] == AST__BAD ) { (void) sprintf( buff, "ci%d_%d", i + 1, j + 1 ); (new->coeff_i)[ i ][ j ] = astReadDouble( channel, buff, AST__BAD ); } } } } /* Get the output axis powers associated with each coefficient of the inverse transformation. */ iv = 0; for( i = 0; i < nin && !undef; i++ ){ (new->power_i)[ i ] = astMalloc( sizeof( int * )* (size_t) new->ncoeff_i[ i ] ); if( astOK ) { for( j = 0; j < new->ncoeff_i[ i ]; j++ ){ (new->power_i)[ i ][ j ] = astMalloc( sizeof( int )* (size_t) nout ); if( astOK ) { for( k = 0; k < nout; k++ ){ (void) sprintf( buff, "pi%d", ++iv ); (new->power_i)[ i ][ j ][ k ] = astReadInt( channel, buff, 0 ); if( (new->power_i)[ i ][ j ][ k ] == 0 ) { (void) sprintf( buff, "pi%d_%d_%d", i + 1, j + 1, k + 1 ); (new->power_i)[ i ][ j ][ k ] = astReadInt( channel, buff, 0 ); } } } } } } /* Free the arrays if the inverse transformation is undefined. */ if( undef ) { new->ncoeff_i = astFree( new->ncoeff_i ); new->mxpow_i = astFree( new->mxpow_i ); new->power_i = astFree( new->power_i ); new->coeff_i = astFree( new->coeff_i ); } } /* Whether to use an iterative inverse transformation. */ new->iterinverse = astReadInt( channel, "iterinv", -INT_MAX ); if ( TestIterInverse( new, status ) ) SetIterInverse( new, new->iterinverse, status ); /* Max number of iterations for iterative inverse transformation. */ new->niterinverse = astReadInt( channel, "niterinv", -INT_MAX ); if ( TestNiterInverse( new, status ) ) SetNiterInverse( new, new->niterinverse, status ); /* Target relative error for iterative inverse transformation. */ new->tolinverse = astReadDouble( channel, "tolinv", AST__BAD ); if ( TestTolInverse( new, status ) ) SetTolInverse( new, new->tolinverse, status ); /* The Jacobian of the PolyMap's forward transformation has not yet been found. */ new->jacobian = NULL; /* If an error occurred, clean up by deleting the new PolyMap. */ if ( !astOK ) new = astDelete( new ); } /* Return the new PolyMap 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. */ AstPolyMap *astPolyTran_( AstPolyMap *this, int forward, double acc, double maxacc, int maxorder, const double *lbnd, const double *ubnd, int *status ){ if ( !astOK ) return NULL; return (**astMEMBER(this,PolyMap,PolyTran))( this, forward, acc, maxacc, maxorder, lbnd, ubnd, status ); } ast-8.3.0/COPYING.LIB0000664000175000017500000006126113004147320010674 00000000000000 GNU LIBRARY GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights. Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library. Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license. The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such. Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better. However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library. Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. GNU LIBRARY GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library 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 Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. , 1 April 1990 Ty Coon, President of Vice That's all there is to it! ast-8.3.0/stcresourceprofile.c0000664000175000017500000007335513004147321013332 00000000000000/* *class++ * Name: * StcResourceProfile * Purpose: * Correspond to the IVOA STCResourceProfile class. * Constructor Function: c astStcResourceProfile f AST_STCRESOURCEPROFILE * Description: * The StcResourceProfile class is a sub-class of Stc used to describe * the coverage of the datasets contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcResourceProfile class inherits from the Stc class. * Attributes: * The StcResourceProfile class does not define any new attributes beyond * those which are applicable to all Stcs. * Functions: c The StcResourceProfile class does not define any new functions beyond those f The StcResourceProfile class does not define any new routines beyond those * which are applicable to all Stcs. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 26-NOV-2004 (DSB): * Original version. *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 StcResourceProfile /* Include 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 "stc.h" /* Coordinate stcs (parent class) */ #include "channel.h" /* I/O channels */ #include "region.h" /* Regions within coordinate systems */ #include "stcresourceprofile.h" /* Interface definition for this class */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include /* Module Variables. */ /* ================= */ /* Address of this static variable is used as a unique identifier for member of this class. */ static int class_check; #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(StcResourceProfile) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(StcResourceProfile,Class_Init) #define class_vtab astGLOBAL(StcResourceProfile,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstStcResourceProfileVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstStcResourceProfile *astStcResourceProfileId_( void *, int, AstKeyMap **, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static void Dump( AstObject *, AstChannel *, int * ); /* Member functions. */ /* ================= */ void astInitStcResourceProfileVtab_( AstStcResourceProfileVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitStcResourceProfileVtab * Purpose: * Initialise a virtual function table for a StcResourceProfile. * Type: * Protected function. * Synopsis: * #include "stcresourceprofile.h" * void astInitStcResourceProfileVtab( AstStcResourceProfileVtab *vtab, const char *name ) * Class Membership: * StcResourceProfile vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the StcResourceProfile 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstStcVtab *stc; /* Pointer to Stc 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. */ astInitStcVtab( (AstStcVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsAStcResourceProfile) 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 = &(((AstStcVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; stc = (AstStcVtab *) vtab; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ /* Declare the copy constructor, destructor and class dump functions. */ astSetDump( vtab, Dump, "StcResourceProfile", "Resource coverage" ); /* 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) ); } } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ /* None */ /* Destructor. */ /* ----------- */ /* None */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for StcResourceProfile 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 StcResourceProfile class to an output Channel. * Parameters: * this * Pointer to the StcResourceProfile 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 Variables: */ AstStcResourceProfile *this; /* Pointer to the StcResourceProfile structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the StcResourceProfile structure. */ this = (AstStcResourceProfile *) this_object; /* Write out values representing the instance variables for the StcResourceProfile 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsAStcResourceProfile and astCheckStcResourceProfile functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(StcResourceProfile,Stc) astMAKE_CHECK(StcResourceProfile) AstStcResourceProfile *astStcResourceProfile_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, int *status, ...) { /* *++ * Name: c astStcResourceProfile f AST_STCRESOURCEPROFILE * Purpose: * Create a StcResourceProfile. * Type: * Public function. * Synopsis: c #include "stcresourceprofile.h" c AstStcResourceProfile *astStcResourceProfile( AstRegion *region, c int ncoords, AstKeyMap *coords[], const char *options, ... ) f RESULT = AST_STCRESOURCEPROFILE( REGION, NCOORDS, COORDS, OPTIONS, STATUS ) * Class Membership: * StcResourceProfile constructor. * Description: * This function creates a new StcResourceProfile and optionally initialises its * attributes. * * The StcResourceProfile class is a sub-class of Stc used to describe * the coverage of the datasets contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Parameters: c region f REGION = INTEGER (Given) * Pointer to the encapsulated Region. c ncoords f NCOORDS = INTEGER (Given) c The length of the "coords" array. Supply zero if "coords" is NULL. f The length of the COORDS array. Supply zero if COORDS should be f ignored. c coords f COORDS( NCOORDS ) = INTEGER (Given) c Pointer to an array holding "ncoords" AstKeyMap pointers (if "ncoords" f An array holding NCOORDS AstKeyMap pointers (if NCOORDS * is zero, the supplied value is ignored). Each supplied KeyMap * describes the contents of a single STC element, and * should have elements with keys given by constants AST__STCNAME, * AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. Any of these elements may be omitted, but no other * elements should be included. If supplied, the AST__STCNAME element * should be a vector of character string pointers holding the "Name" * item for each axis in the coordinate system represented by c "region". f REGION. * Any other supplied elements should be scalar elements, each holding * a pointer to a Region describing the associated item of ancillary * information (error, resolution, size, pixel size or value). These * Regions should describe a volume within the coordinate system c represented by "region". f represented by REGION. 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 StcResourceProfile. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new StcResourceProfile. The syntax used is identical to that for the f AST_SET routine. 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 astStcResourceProfile() f AST_STCRESOURCEPROFILE = INTEGER * A pointer to the new StcResourceProfile. * Notes: * - A deep copy is taken of the supplied Region. This means that * any subsequent changes made to the encapsulated Region using the * supplied pointer will have no effect on the Stc. * - 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. * Status Handling: * The protected interface to this function includes an extra * parameter at the end of the parameter list descirbed above. This * parameter is a pointer to the integer inherited status * variable: "int *status". *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstRegion *region; /* Pointer to Region structure */ AstStcResourceProfile *new; /* Pointer to new StcResourceProfile */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the Region structure provided. */ region = astCheckRegion( region_void ); /* Initialise the StcResourceProfile, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcResourceProfile( NULL, sizeof( AstStcResourceProfile ), !class_init, &class_vtab, "StcResourceProfile", region, ncoords, coords ); /* 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 StcResourceProfile'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 StcResourceProfile. */ return new; } AstStcResourceProfile *astStcResourceProfileId_( void *region_void, int ncoords, AstKeyMap **coords, const char *options, ... ) { /* * Name: * astStcResourceProfileId_ * Purpose: * Create a StcResourceProfile. * Type: * Private function. * Synopsis: * #include "stcresourceprofile.h" * AstStcResourceProfile *astStcResourceProfileId( AstRegion *region, * int ncoords, AstKeyMap *coords[], const char *options, ... ) * Class Membership: * StcResourceProfile constructor. * Description: * This function implements the external (public) interface to the * astStcResourceProfile constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astStcResourceProfile_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astStcResourceProfile_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astStcResourceProfile_. * Returned Value: * The ID value associated with the new StcResourceProfile. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstKeyMap **keymaps; /* Pointer to array of KeyMap pointers */ AstRegion *region; /* Pointer to Region structure */ AstStcResourceProfile *new; /* Pointer to new StcResourceProfile */ int icoord; /* Keymap index */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ astGET_GLOBALS(NULL); /* Get a pointer to the thread specific global data structure. */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain a Region pointer from the supplied ID and validate the pointer to ensure it identifies a valid Region. */ region = astVerifyRegion( astMakePointer( region_void ) ); /* Obtain pointer from the supplied KeyMap ID's and validate the pointers to ensure it identifies a valid KeyMap. */ keymaps = astMalloc( sizeof( AstKeyMap * )*(size_t) ncoords ); if( keymaps ) { for( icoord = 0; icoord < ncoords; icoord++ ) { keymaps[ icoord ] = astVerifyKeyMap( astMakePointer( coords[ icoord ] ) ); } } /* Initialise the StcResourceProfile, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitStcResourceProfile( NULL, sizeof( AstStcResourceProfile ), !class_init, &class_vtab, "StcResourceProfile", region, ncoords, keymaps ); /* Free resources. */ keymaps = astFree( keymaps ); /* 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 StcResourceProfile'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 StcResourceProfile. */ return astMakeId( new ); } AstStcResourceProfile *astInitStcResourceProfile_( void *mem, size_t size, int init, AstStcResourceProfileVtab *vtab, const char *name, AstRegion *region, int ncoords, AstKeyMap **coords, int *status ) { /* *+ * Name: * astInitStcResourceProfile * Purpose: * Initialise a StcResourceProfile. * Type: * Protected function. * Synopsis: * #include "stcresourceprofile.h" * AstStcResourceProfile *astInitStcResourceProfile_( void *mem, size_t size, * int init, AstStcResourceProfileVtab *vtab, * const char *name, AstRegion *region, * int ncoords, AstKeyMap **coords ) * Class Membership: * StcResourceProfile initialiser. * Description: * This function is provided for use by class implementations to initialise * a new StcResourceProfile object. It allocates memory (if necessary) to accommodate * the StcResourceProfile plus any additional data associated with the derived class. * It then initialises a StcResourceProfile 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 StcResourceProfile at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the StcResourceProfile is to be initialised. * This must be of sufficient size to accommodate the StcResourceProfile data * (sizeof(StcResourceProfile)) 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 StcResourceProfile (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 StcResourceProfile * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the StcResourceProfile'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 StcResourceProfile. * 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). * region * A pointer to the Region encapsulated by the StcResourceProfile. * ncoords * Number of KeyMap pointers supplied in "coords". Can be zero. * Ignored if "coords" is NULL. * coords * Pointer to an array of "ncoords" KeyMap pointers, or NULL if * "ncoords" is zero. Each KeyMap defines defines a single * element, and should have elements with keys given by constants * AST__STCNAME, AST__STCVALUE, AST__STCERROR, AST__STCRES, AST__STCSIZE, * AST__STCPIXSZ. These elements hold values for the corresponding * components of the STC AstroCoords element. Any of these elements may * be omitted, but no other elements should be included. All supplied * elements should be vector elements, with vector length less than or * equal to the number of axes in the supplied Region. The data type of * all elements should be "double", except for AST__STCNAME which should * be "character string". If no value is available for a given axis, then * AST__BAD (or NULL for the AST__STCNAME element) should be stored in * the vector at the index corresponding to the axis (trailing axes * can be omitted completely from the KeyMap). * Returned Value: * A pointer to the new StcResourceProfile. * 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: */ AstStcResourceProfile *new; /* Pointer to new StcResourceProfile */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitStcResourceProfileVtab( vtab, name ); /* Initialise a Stc structure (the parent class) as the first component within the StcResourceProfile structure, allocating memory if necessary. */ new = (AstStcResourceProfile *) astInitStc( mem, size, 0, (AstStcVtab *) vtab, name, region, ncoords, coords ); /* If an error occurred, clean up by deleting the new StcResourceProfile. */ if ( !astOK ) new = astDelete( new ); /* Return a pointer to the new StcResourceProfile. */ return new; } AstStcResourceProfile *astLoadStcResourceProfile_( void *mem, size_t size, AstStcResourceProfileVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadStcResourceProfile * Purpose: * Load a StcResourceProfile. * Type: * Protected function. * Synopsis: * #include "stcresourceprofile.h" * AstStcResourceProfile *astLoadStcResourceProfile( void *mem, size_t size, AstStcResourceProfileVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * StcResourceProfile loader. * Description: * This function is provided to load a new StcResourceProfile 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 * StcResourceProfile structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a StcResourceProfile at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the StcResourceProfile is to be * loaded. This must be of sufficient size to accommodate the * StcResourceProfile data (sizeof(StcResourceProfile)) 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 StcResourceProfile (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 StcResourceProfile 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(AstStcResourceProfile) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new StcResourceProfile. If this is NULL, a pointer * to the (static) virtual function table for the StcResourceProfile 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 "StcResourceProfile" is used instead. * Returned Value: * A pointer to the new StcResourceProfile. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstStcResourceProfile *new; /* Pointer to the new StcResourceProfile */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this StcResourceProfile. In this case the StcResourceProfile belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstStcResourceProfile ); vtab = &class_vtab; name = "StcResourceProfile"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitStcResourceProfileVtab( 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 StcResourceProfile. */ new = astLoadStc( mem, size, (AstStcVtab *) 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, "StcResourceProfile" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* If an error occurred, clean up by deleting the new StcResourceProfile. */ if ( !astOK ) new = astDelete( new ); } /* Return the new StcResourceProfile pointer. */ return new; } /* 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. */ ast-8.3.0/nullregion.c0000664000175000017500000021776513004147321011573 00000000000000/* *class++ * Name: * NullRegion * Purpose: * A boundless region within a Frame. * Constructor Function: c astNullRegion f AST_NULLREGION * Description: * The NullRegion class implements a Region with no bounds within a Frame. * If the Negated attribute of a NullRegion is false, the NullRegion * represents a Region containing no points. If the Negated attribute of * a NullRegion is true, the NullRegion represents an infinite Region * (that is, all points in the coordinate system are inside the NullRegion). * Inheritance: * The NullRegion class inherits from the Region class. * Attributes: * The NullRegion class does not define any new attributes beyond * those which are applicable to all Regions. * Functions: c The NullRegion class does not define any new functions beyond those f The NullRegion class does not define any new routines beyond those * which are applicable to all Regions. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2009 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 11-OCT-2004 (DSB): * Original version. * 20-JAN-2009 (DSB): * Over-ride astRegBasePick. * 26-JAN-2009 (DSB): * Over-ride astMapMerge. *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 NullRegion /* Include 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 "pointset.h" /* Sets of points/coordinates */ #include "region.h" /* Coordinate regions (parent class) */ #include "channel.h" /* I/O channels */ #include "nullregion.h" /* Interface definition for this class */ #include "mapping.h" /* Position mappings */ #include "circle.h" /* Circle regions */ #include "prism.h" /* Extruded Regions */ #include "unitmap.h" /* Unit Mapping */ #include "cmpframe.h" /* Compound Frames */ #include "cmpmap.h" /* Compound Mappings */ /* Error code definitions. */ /* ----------------------- */ #include "ast_err.h" /* AST error codes */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include /* 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 AstPointSet *(* parent_transform)( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstMapping *(* parent_simplify)( AstMapping *, int * ); #ifdef THREAD_SAFE /* Define how to initialise thread-specific globals. */ #define GLOBAL_inits \ globals->Class_Init = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(NullRegion) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(NullRegion,Class_Init) #define class_vtab astGLOBAL(NullRegion,Class_Vtab) #include #else /* Define the class virtual function table and its initialisation flag as static variables. */ static AstNullRegionVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #endif /* External 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. */ AstNullRegion *astNullRegionId_( void *, void *, const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static AstMapping *Simplify( AstMapping *, int * ); static AstPointSet *RegBaseMesh( AstRegion *, int * ); static AstPointSet *RegMesh( AstRegion *, int * ); static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); static AstRegion *RegBasePick( AstRegion *this, int, const int *, int * ); static AstRegion *GetDefUnc( AstRegion *, int * ); static AstRegion *MergeNullRegion( AstNullRegion *, AstRegion *, int, int * ); static int MapMerge( AstMapping *, int, int, int *, AstMapping ***, int **, int * ); static int Overlap( AstRegion *, AstRegion *, int * ); static int OverlapX( AstRegion *, AstRegion *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void RegBaseBox( AstRegion *this, double *, double *, int * ); static void GetRegionBounds( AstRegion *this, double *, double *, int * ); /* Member functions. */ /* ================= */ static AstRegion *GetDefUnc( AstRegion *this, int *status ) { /* *+ * Name: * astGetDefUnc * Purpose: * Obtain a pointer to the default uncertainty Region for a given Region. * Type: * Protected function. * Synopsis: * #include "nullregion.h" * AstRegion *astGetDefUnc( AstRegion *this ) * Class Membership: * NullRegion member function (over-rides the astGetDefUnc protected * method inherited from the Region class). * Description: * This function returns a pointer to a Region which represents the * default uncertainty associated with a position on the boundary of the * given Region. The returned Region refers to the base Frame within the * FrameSet encapsulated by the supplied Region. * Parameters: * this * Pointer to the Region. * Returned Value: * A pointer to the Region. This should be annulled (using astAnnul) * when no longer needed. * Notes: * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. *- */ /* Local Variables: */ AstRegion *result; double *cen; double rad; int i; int n; /* Initialise */ result = NULL; /* Check inherited status */ if( !astOK ) return result; /* Create a Circle centred on the origin with zero radius. */ n = astGetNaxes( this ); cen = astMalloc( sizeof(double)*(size_t) n ); if( cen ) { for( i = 0; i < n; i++ ) cen[ i ] = 0.0; rad = 0.0; result = (AstRegion *) astCircle( this, 1, cen, &rad, NULL, "", status ); cen = astFree( cen ); } /* Return the default uncertainty Region. */ return result; } void astInitNullRegionVtab_( AstNullRegionVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitNullRegionVtab * Purpose: * Initialise a virtual function table for a NullRegion. * Type: * Protected function. * Synopsis: * #include "nullregion.h" * void astInitNullRegionVtab( AstNullRegionVtab *vtab, const char *name ) * Class Membership: * NullRegion vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the NullRegion 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 */ AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ AstRegionVtab *region; /* Pointer to Region 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. */ astInitRegionVtab( (AstRegionVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsANullRegion) 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 = &(((AstRegionVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ mapping = (AstMappingVtab *) vtab; region = (AstRegionVtab *) vtab; parent_transform = mapping->Transform; mapping->Transform = Transform; parent_simplify = mapping->Simplify; mapping->Simplify = Simplify; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ mapping->MapMerge = MapMerge; region->GetDefUnc = GetDefUnc; region->Overlap = Overlap; region->OverlapX = OverlapX; region->RegBaseBox = RegBaseBox; region->RegBaseMesh = RegBaseMesh; region->GetRegionBounds = GetRegionBounds; region->RegMesh = RegMesh; region->RegBasePick = RegBasePick; /* Declare the copy constructor, destructor and class dump functions. */ astSetDump( vtab, Dump, "NullRegion", "Boundless region" ); /* 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 int MapMerge( AstMapping *this, int where, int series, int *nmap, AstMapping ***map_list, int **invert_list, int *status ) { /* * Name: * MapMerge * Purpose: * Simplify a sequence of Mappings containing a NullRegion. * Type: * Private function. * Synopsis: * #include "mapping.h" * int MapMerge( AstMapping *this, int where, int series, int *nmap, * AstMapping ***map_list, int **invert_list, int *status ) * Class Membership: * NullRegion method (over-rides the protected astMapMerge method * inherited from the Region class). * Description: * This function attempts to simplify a sequence of Mappings by * merging a nominated NullRegion in the sequence with its neighbours, * so as to shorten the sequence if possible. * * In many cases, simplification will not be possible and the * function will return -1 to indicate this, without further * action. * * In most cases of interest, however, this function will either * attempt to replace the nominated NullRegion with a Mapping which it * considers simpler, or to merge it with the Mappings which * immediately precede it or follow it in the sequence (both will * normally be considered). This is sufficient to ensure the * eventual simplification of most Mapping sequences by repeated * application of this function. * * In some cases, the function may attempt more elaborate * simplification, involving any number of other Mappings in the * sequence. It is not restricted in the type or scope of * simplification it may perform, but will normally only attempt * elaborate simplification in cases where a more straightforward * approach is not adequate. * Parameters: * this * Pointer to the nominated NullRegion which is to be merged with * its neighbours. This should be a cloned copy of the NullRegion * pointer contained in the array element "(*map_list)[where]" * (see below). This pointer will not be annulled, and the * NullRegion it identifies will not be modified by this function. * where * Index in the "*map_list" array (below) at which the pointer * to the nominated NullRegion resides. * series * A non-zero value indicates that the sequence of Mappings to * be simplified will be applied in series (i.e. one after the * other), whereas a zero value indicates that they will be * applied in parallel (i.e. on successive sub-sets of the * input/output coordinates). * nmap * Address of an int which counts the number of Mappings in the * sequence. On entry this should be set to the initial number * of Mappings. On exit it will be updated to record the number * of Mappings remaining after simplification. * map_list * Address of a pointer to a dynamically allocated array of * Mapping pointers (produced, for example, by the astMapList * method) which identifies the sequence of Mappings. On entry, * the initial sequence of Mappings to be simplified should be * supplied. * * On exit, the contents of this array will be modified to * reflect any simplification carried out. Any form of * simplification may be performed. This may involve any of: (a) * removing Mappings by annulling any of the pointers supplied, * (b) replacing them with pointers to new Mappings, (c) * inserting additional Mappings and (d) changing their order. * * The intention is to reduce the number of Mappings in the * sequence, if possible, and any reduction will be reflected in * the value of "*nmap" returned. However, simplifications which * do not reduce the length of the sequence (but improve its * execution time, for example) may also be performed, and the * sequence might conceivably increase in length (but normally * only in order to split up a Mapping into pieces that can be * more easily merged with their neighbours on subsequent * invocations of this function). * * If Mappings are removed from the sequence, any gaps that * remain will be closed up, by moving subsequent Mapping * pointers along in the array, so that vacated elements occur * at the end. If the sequence increases in length, the array * will be extended (and its pointer updated) if necessary to * accommodate any new elements. * * Note that any (or all) of the Mapping pointers supplied in * this array may be annulled by this function, but the Mappings * to which they refer are not modified in any way (although * they may, of course, be deleted if the annulled pointer is * the final one). * invert_list * Address of a pointer to a dynamically allocated array which, * on entry, should contain values to be assigned to the Invert * attributes of the Mappings identified in the "*map_list" * array before they are applied (this array might have been * produced, for example, by the astMapList method). These * values will be used by this function instead of the actual * Invert attributes of the Mappings supplied, which are * ignored. * * On exit, the contents of this array will be updated to * correspond with the possibly modified contents of the * "*map_list" array. If the Mapping sequence increases in * length, the "*invert_list" array will be extended (and its * pointer updated) if necessary to accommodate any new * elements. * status * Pointer to the inherited status variable. * Returned Value: * If simplification was possible, the function returns the index * in the "map_list" array of the first element which was * modified. Otherwise, it returns -1 (and makes no changes to the * arrays supplied). * Notes: * - A value of -1 will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ AstNullRegion *oldint; /* Pointer to supplied NullRegion */ AstMapping *map; /* Pointer to adjacent Mapping */ AstMapping *new; /* Simplified or merged Region */ int i1; /* Index of first Mapping merged */ int i; /* Loop counter */ int result; /* Result value to return */ /* Initialise. */ result = -1; i1 = -1; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the NullRegion. */ oldint = (AstNullRegion *) this; /* First of all, see if the NullRegion can be replaced by a simpler Region, without reference to the neighbouring Regions in the list. */ /* =====================================================================*/ /* Try to simplify the NullRegion. If the pointer value has changed, we assume some simplification took place. */ new = astSimplify( oldint ); if( new != (AstMapping *) oldint ) { /* Annul the NullRegion pointer in the list and replace it with the new Region pointer, and indicate that the forward transformation of the returned Region should be used (not really needed but keeps things clean). */ (void) astAnnul( ( *map_list )[ where ] ); ( *map_list )[ where ] = new; ( *invert_list )[ where ] = 0; /* Return the index of the first modified element. */ result = where; /* If the NullRegion itself could not be simplified, see if it can be merged with the Regions on either side of it in the list. We can only merge in parallel. */ /* =====================================================================*/ } else if( ! series ){ new = astAnnul( new ); /* Attempt to merge the NullRegion with its lower neighbour (if any). */ if( where > 0 ) { i1 = where - 1; map = ( *map_list )[ where - 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeNullRegion( oldint, (AstRegion *) map, 0, status ); } } /* If this did not produced a merged Region, attempt to merge the NullRegion with its upper neighbour (if any). */ if( !new && where < *nmap - 1 ) { i1 = where; map = ( *map_list )[ where + 1 ]; if( astIsARegion( map ) ) { new = (AstMapping *) MergeNullRegion( oldint, (AstRegion *) map, 1, status ); } } /* If succesfull... */ if( new ){ /* Annul the first of the two Mappings, and replace it with the merged Region. Also clear the invert flag. */ (void) astAnnul( ( *map_list )[ i1 ] ); ( *map_list )[ i1 ] = new; ( *invert_list )[ i1 ] = 0; /* Annul the second of the two Mappings, and shuffle down the rest of the list to fill the gap. */ (void) astAnnul( ( *map_list )[ i1 + 1 ] ); for ( i = i1 + 2; i < *nmap; i++ ) { ( *map_list )[ i - 1 ] = ( *map_list )[ i ]; ( *invert_list )[ i - 1 ] = ( *invert_list )[ i ]; } /* Clear the vacated element at the end. */ ( *map_list )[ *nmap - 1 ] = NULL; ( *invert_list )[ *nmap - 1 ] = 0; /* Decrement the Mapping count and return the index of the first modified element. */ ( *nmap )--; result = i1; } } else { new = astAnnul( new ); } /* Return the result. */ return result; } static AstRegion *MergeNullRegion( AstNullRegion *this, AstRegion *reg, int intfirst, int *status ) { /* * Name: * MergeNullRegion * Purpose: * Attempt to merge a NullRegion with another Region to form a Region of * higher dimensionality. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstRegion *MergeNullRegion( AstNullRegion *this, AstRegion *reg, * int intfirst, int *status ) * Class Membership: * NullRegion member function. * Description: * This function attempts to combine the supplied Regions together * into a Region of higher dimensionality. * Parameters: * this * Pointer to a NullRegion. * reg * Pointer to another Region. * intfirst * If non-zero, then the NullRegion axes are put first in the new Region. * Otherwise, the other Region's axes are put first. * status * Pointer to the inherited status value. * Returned Value: * A pointer to a new region, or NULL if the supplied Regions could * not be merged. */ /* Local Variables: */ AstFrame *bfrm; /* Pointer to base Frame for "result" */ AstFrame *cfrm; /* Pointer to current Frame for "result" */ AstFrame *frm_reg; /* Pointer to Frame from "reg" */ AstFrame *frm_this; /* Pointer to Frame from "this" */ AstMapping *bcmap; /* Base->current Mapping for "result" */ AstMapping *map_reg; /* Base->current Mapping from "reg" */ AstMapping *map_this; /* Base->current Mapping from "this" */ AstMapping *sbunc; /* Simplified uncertainty */ AstRegion *bunc; /* Base Frame uncertainty Region */ AstRegion *new; /* Pointer to new NullRegion in base Frame */ AstRegion *result; /* Pointer to returned NullRegion in current Frame */ AstRegion *unc_reg; /* Current Frame uncertainty Region from "reg" */ AstRegion *unc_this; /* Current Frame uncertainty Region from "this" */ double fac_reg; /* Ratio of used to default MeshSize for "reg" */ double fac_this; /* Ratio of used to default MeshSize for "this" */ int msz_reg; /* Original MeshSize for "reg" */ int msz_reg_set; /* Was MeshSize originally set for "reg"? */ int msz_this; /* Original MeshSize for "this" */ int msz_this_set; /* Was MeshSize originally set for "this"? */ int nax; /* Number of axes in "result" */ int nax_reg; /* Number of axes in "reg" */ int nax_this; /* Number of axes in "this" */ int neg_reg; /* Negated attribute value for other supplied Region */ int neg_this; /* Negated attribute value for supplied NullRegion */ /* Initialise */ result = NULL; /* Check the local error status. */ if ( !astOK ) return result; /* Get the Closed attributes of the two Regions. They must be the same in each Region if we are to merge the Regions. In addition, in order to merge, either both Regions must have a defined uncertainty, or neither Region must have a defined Uncertainty. */ if( astGetClosed( this ) == astGetClosed( reg ) && astTestUnc( this ) == astTestUnc( reg ) ) { /* Get the Nagated attributes of the two Regions. */ neg_this = astGetNegated( this ); neg_reg = astGetNegated( reg ); /* Get the number of axes in the two supplied Regions. */ nax_reg = astGetNaxes( reg ); nax_this = astGetNaxes( this ); /* If the Regions can be combined, get the number of axes the combination will have. */ nax = nax_reg + nax_this; /* Get the base Frames from the two Region FrameSets, and combine them into a single CmpFrame that will be used to create any new Region. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__BASE ); frm_reg = astGetFrame( reg->frameset, AST__BASE ); if( intfirst ) { bfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { bfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); /* Indicate we do not yet have a merged Region. */ new = NULL; /* We only check for merging with another NullRegion (other classes such as Box and Interval check for merging of NullRegions with other classes). The result will be an NullRegion. Both Regions must have the same value for the Negated flag. */ if( astIsANullRegion( reg ) && neg_this == neg_reg ) { new = (AstRegion *) astNullRegion( bfrm, NULL, "", status ); /* Propagate remaining attributes of the supplied Region to it. */ astRegOverlay( new, this, 1 ); /* Ensure the Negated flag is set correctly in the returned NullRegion. */ if( neg_this ) { astSetNegated( new, neg_this ); } else { astClearNegated( new ); } /* If both the supplied Regions have uncertainty, assign the new Region an uncertainty. */ if( astTestUnc( this ) && astTestUnc( reg ) ) { /* Get the uncertainties from the two supplied Regions. */ unc_this = astGetUncFrm( this, AST__BASE ); unc_reg = astGetUncFrm( reg, AST__BASE ); /* Combine them into a single Region (a Prism), in the correct order. */ if( intfirst ) { bunc = (AstRegion *) astPrism( unc_this, unc_reg, "", status ); } else { bunc = (AstRegion *) astPrism( unc_reg, unc_this, "", status ); } /* Attempt to simplify the Prism. */ sbunc = astSimplify( bunc ); /* Use the simplified Prism as the uncertainty for the returned Region. */ astSetUnc( new, sbunc ); /* Free resources. */ sbunc = astAnnul( sbunc ); bunc = astAnnul( bunc ); unc_reg = astAnnul( unc_reg ); unc_this = astAnnul( unc_this ); } /* Get the current Frames from the two Region FrameSets, and combine them into a single CmpFrame. */ frm_this = astGetFrame( ((AstRegion *) this)->frameset, AST__CURRENT ); frm_reg = astGetFrame( reg->frameset, AST__CURRENT ); if( intfirst ) { cfrm = (AstFrame *) astCmpFrame( frm_this, frm_reg, "", status ); } else { cfrm = (AstFrame *) astCmpFrame( frm_reg, frm_this, "", status ); } /* Get the base -> current Mappings from the two Region FrameSets, and combine them into a single parallel CmpMap that connects bfrm and cfrm. */ map_this = astGetMapping( ((AstRegion *) this)->frameset, AST__BASE, AST__CURRENT ); map_reg = astGetMapping( reg->frameset, AST__BASE, AST__CURRENT ); if( intfirst ) { bcmap = (AstMapping *) astCmpMap( map_this, map_reg, 0, "", status ); } else { bcmap = (AstMapping *) astCmpMap( map_reg, map_this, 0, "", status ); } /* Map the new Region into the new current Frame. */ result = astMapRegion( new, bcmap, cfrm ); /* The filling factor in the returned is the product of the filling factors for the two supplied Regions. */ if( astTestFillFactor( reg ) || astTestFillFactor( this ) ) { astSetFillFactor( result, astGetFillFactor( reg )* astGetFillFactor( this ) ); } /* If the MeshSize value is set in either supplied Region, set a value for the returned Region which scales the default value by the product of the scaling factors for the two supplied Regions. First see if either MeshSize value is set. */ msz_this_set = astTestMeshSize( this ); msz_reg_set = astTestMeshSize( reg ); if( msz_this_set || msz_reg_set ) { /* If so, get the two MeshSize values (one of which may be a default value), and then clear them so that the default value will be returned in future. */ msz_this = astGetMeshSize( this ); msz_reg = astGetMeshSize( reg ); astClearMeshSize( this ); astClearMeshSize( reg ); /* Get the ratio of the used MeshSize to the default MeshSize for both Regions. */ fac_this = (double)msz_this/(double)astGetMeshSize( this ); fac_reg = (double)msz_reg/(double)astGetMeshSize( reg ); /* The MeshSize of the returned Returned is the default value scaled by the product of the two ratios found above. */ astSetMeshSize( result, fac_this*fac_reg*astGetMeshSize( result ) ); /* Re-instate the original MeshSize values for the supplied Regions (if set) */ if( msz_this_set ) astSetMeshSize( this, msz_this ); if( msz_reg_set ) astSetMeshSize( reg, msz_reg ); } /* Free remaining resources */ frm_this = astAnnul( frm_this ); frm_reg = astAnnul( frm_reg ); map_this = astAnnul( map_this ); map_reg = astAnnul( map_reg ); bcmap = astAnnul( bcmap ); new = astAnnul( new ); cfrm = astAnnul( cfrm ); } } /* If an error has occurred, annul the returned pointer. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static int Overlap( AstRegion *this, AstRegion *that, int *status ){ /* * Name: * Overlap * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "nullregion.h" * int Overlap( AstRegion *this, AstRegion *that ) * Class Membership: * NullRegion member function (over-rides the astOverlap method inherited * from the Region class). * Description: * This function returns an integer value indicating if the two * supplied Regions overlap. The two Regions are converted to a commnon * coordinate system before performing the check. If this conversion is * not possible (for instance because the two Regions represent areas in * different domains), then the check cannot be performed and a zero value * is returned to indicate this. * Parameters: * this * Pointer to the first Region. * that * Pointer to the second Region. * Returned Value: * astOverlap() * A value indicating if there is any overlap between the two Regions. * Possible values are: * * 0 - The check could not be performed because the second Region * could not be mapped into the coordinate system of the first * Region. * * 1 - There is no overlap between the two Regions. * * 2 - The first Region is completely inside the second Region. * * 3 - The second Region is completely inside the first Region. * * 4 - There is partial overlap between the two Regions. * * 5 - The Regions are identical. * * 6 - The second Region is the negation of the first Region. * Notes: * - The returned values 5 and 6 do not check the value of the Closed * attribute in the two Regions. * - A value of zero will be returned if this function is invoked with the * AST error status set, or if it should fail for any reason. * Implementation Notes: * - This function is simply a wrap-up for the OverlapX function * which performs the required processing but swaps the order of the * two arguments. This is a trick to allow the astOverlap * method to be over-ridden by derived classes on the basis of the * class of either of the two arguments. */ /* Check the inherited status. */ if ( !astOK ) return 0; /* Invoke the private "OverlapX" member function with the two arguments swapped. */ return OverlapX( that, this, status ); } static int OverlapX( AstRegion *that, AstRegion *this, int *status ){ /* * Name: * OverlapX * Purpose: * Test if two regions overlap each other. * Type: * Private function. * Synopsis: * #include "nullregion.h" * int OverlapX( AstRegion *that, AstRegion *this ) * Class Membership: * NullRegion member function (over-rides the astOverlapX method inherited * from the Region class). * Description: * This function performs the processing for the public astOverlap * method (as inherited from the Region class and over-ridden by the * NullRegion class) and has exactly the same interface except that * the order of the two arguments is swapped. This is a trick * to allow the astOverlap method to be over-ridden by derived * classes on the basis of the class of either of its two * arguments. * * See the astOverlap method for details of the interface. */ /* Local Variables: */ AstFrameSet *fs; /* FrameSet connecting Region Frames */ int result; /* Returned value */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Check that the Regions can be compared meaningfully. */ fs = astConvert( this, that, "" ); if( fs ) { fs = astAnnul( fs ); /* If both the supplied Regions are NullRegion... */ if( astIsANullRegion( this ) && astIsANullRegion( that ) ) { /* If the Negated attributes are equal, the Regions are identical. Otherwise they are mutually exclusive. */ if( astGetNegated( this ) == astGetNegated( that ) ) { result = 5; } else { result = 6; } /* If one of the supplied Region is a NullRegion containing no points, then there is no overlap. */ } else if( ( astIsANullRegion( this ) && !astGetNegated( this ) ) || ( astIsANullRegion( that ) && !astGetNegated( that ) ) ) { result = 1; /* If "that" is infinite and "this" is not infinite, then "this" is entirely inside "that". */ } else if( astIsANullRegion( that ) && astGetNegated( that ) ) { result = 2; /* If "this" is infinite and "that" is not infinite, then "that" is entirely inside "this". */ } else if( astIsANullRegion( this ) && astGetNegated( this ) ){ result = 3; /* Otherwise there is partial overlap. */ } else { result = 4; } } /* If not OK, return zero. */ if( !astOK ) result = 0; /* Return the result. */ return result; } static void RegBaseBox( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * RegBaseBox * Purpose: * Returns the bounding box of an un-negated Region in the base Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "nullregion.h" * void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * NullRegion member function (over-rides the astRegBaseBox protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the base Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the base Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the base Frame. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstNullRegion *this; /* Pointer to NullRegion structure */ int i; /* Axis index */ int nc; /* No. of axes in base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the NullRegion structure */ this = (AstNullRegion *) this_region; /* Get the number of base Frame axes. */ nc = astGetNin( this_region->frameset ); /* Set the upper bound less than the lower bound to indicate that the region contains no points. */ for( i = 0; i < nc; i++ ) { lbnd[ i ] = 1.0; ubnd[ i ] = -1.0; } } static AstPointSet *RegBaseMesh( AstRegion *this, int *status ){ /* * Name: * RegBaseMesh * Purpose: * Return a PointSet containing a mesh of points on the boundary of a * Region in its base Frame. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstPointSet *astRegBaseMesh( AstRegion *this, int *status ) * Class Membership: * NullRegion member function (over-rides the astRegBaseMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the base Frame of * the encapsulated FrameSet. Note, a NullRegion has no boundary. This * is indicated by returned a PointSet containing a single point with a * value of AST__BAD on every axis. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a new PointSet containing a single point with value of * AST__BAD on every axis. *- */ /* Local Variables: */ AstPointSet *result; double **ptr; int i; int nc; /* Initialise */ result = NULL; /* Check the inherited status */ if( !astOK ) return result; /* If the Region structure contains a pointer to a PointSet holding a previously created mesh, return it. */ if( this->basemesh ) { result = astClone( this->basemesh ); /* Otherwise, create a new mesh. */ } else { /* Get the number of base Frame axes */ nc = astGetNin( this->frameset ); /* Create the PointSet. */ result = astPointSet( 1, nc, "", status ); /* Get a pointer to the axis values. */ ptr = astGetPoints( result ); /* If OK, store AST__BAD on every axis. */ if( ptr ) for( i = 0; i < nc; i++ ) ptr[ i ][ 0 ] = AST__BAD; /* Same the returned pointer in the Region structure so that it does not need to be created again next time this function is called. */ if( astOK && result ) this->basemesh = astClone( result ); } /* Return the result. */ return result; } static AstRegion *RegBasePick( AstRegion *this_region, int naxes, const int *axes, int *status ){ /* * Name: * RegBasePick * Purpose: * Return a Region formed by picking selected base Frame axes from the * supplied Region. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, * int *status ) * Class Membership: * NullRegion member function (over-rides the astRegBasePick protected * method inherited from the Region class). * Description: * This function attempts to return a Region that is spanned by selected * axes from the base Frame of the encapsulated FrameSet of the supplied * Region. This may or may not be possible, depending on the class of * Region. If it is not possible a NULL pointer is returned. * Parameters: * this * Pointer to the Region. * naxes * The number of base Frame axes to select. * axes * An array holding the zero-based indices of the base Frame axes * that are to be selected. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Region, or NULL if no region can be formed. * Notes: * - A NULL pointer is returned if an error has already occurred, or if * this function should fail for any reason. */ /* Local Variables: */ AstFrame *bfrm; /* The base Frame in the supplied Region */ AstFrame *frm; /* The base Frame in the returned Region */ AstRegion *bunc; /* The uncertainty in the supplied Region */ AstRegion *result; /* Returned Region */ AstRegion *unc; /* The uncertainty in the returned Region */ /* Initialise */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the base Frame of the encapsulated FrameSet. */ bfrm = astGetFrame( this_region->frameset, AST__BASE ); /* Create a Frame by picking the selected axes from the base Frame of the encapsulated FrameSet. */ frm = astPickAxes( bfrm, naxes, axes, NULL ); /* Get the uncertainty Region (if any) within the base Frame of the supplied Region, and select the required axes from it. If the resulting Object is not a Region, annul it so that the returned Region will have no uncertainty. */ if( astTestUnc( this_region ) ) { bunc = astGetUncFrm( this_region, AST__BASE ); unc = astPickAxes( bunc, naxes, axes, NULL ); bunc = astAnnul( bunc ); if( ! astIsARegion( unc ) ) unc = astAnnul( unc ); } else { unc = NULL; } /* Create the new NullRegion. */ result = (AstRegion *) astNullRegion( frm, unc, "", status ); /* Free resources */ frm = astAnnul( frm ); bfrm = astAnnul( bfrm ); if( unc ) unc = astAnnul( unc ); /* Return a NULL pointer if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static void GetRegionBounds( AstRegion *this_region, double *lbnd, double *ubnd, int *status ){ /* * Name: * GetRegionBounds * Purpose: * Returns the bounding box of an un-negated Region in the current Frame of * the encapsulated FrameSet. * Type: * Private function. * Synopsis: * #include "nullregion.h" * void astGetRegionBounds( AstRegion *this, double *lbnd, double *ubnd, int *status ) * Class Membership: * NullRegion member function (over-rides the astGetRegionBounds protected * method inherited from the Region class). * Description: * This function returns the upper and lower axis bounds of a Region in * the current Frame of the encapsulated FrameSet, assuming the Region * has not been negated. That is, the value of the Negated attribute * is ignored. * Parameters: * this * Pointer to the Region. * lbnd * Pointer to an array in which to return the lower axis bounds * covered by the Region in the current Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the Region. * ubnd * Pointer to an array in which to return the upper axis bounds * covered by the Region in the current Frame of the encapsulated * FrameSet. It should have at least as many elements as there are * axes in the Region. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstNullRegion *this; /* Pointer to NullRegion structure */ int i; /* Axis index */ int nc; /* No. of axes in base Frame */ /* Check the global error status. */ if ( !astOK ) return; /* Get a pointer to the NullRegion structure */ this = (AstNullRegion *) this_region; /* Get the number of base Frame axes. */ nc = astGetNin( this_region->frameset ); /* Set the upper bound less than the lower bound to indicate that the region contains no points. */ for( i = 0; i < nc; i++ ) { lbnd[ i ] = 1.0; ubnd[ i ] = -1.0; } } static AstPointSet *RegMesh( AstRegion *this, int *status ){ /* * Name: * RegMesh * Purpose: * Return a PointSet containing points spread over the boundary of a * Region. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstPointSet *astRegMesh( AstRegion *this, int *status ) * Class Membership: * NullRegion member function (over-rides the astRegMesh protected * method inherited from the Region class). * Description: * This function returns a PointSet containing a mesh of points on the * boundary of the Region. The points refer to the current Frame of * the encapsulated FrameSet. Note, a NullRegion has no boundary and * so an error is reported if this function is called. * Parameters: * this * Pointer to the Region. * status * Pointer to the inherited status variable. * Returned Value: * NULL pointer. * Notes: * - This implementation reports and error and returns NULL since a * NullRegion has no boundary. *- */ astError( AST__INTER, "astRegMesh(%s): The %s class does not implement " "the astRegMesh method inherited from the Region class " "(internal AST programming error).", status, astGetClass( this ), astGetClass( this ) ); return NULL; } static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { /* * Name: * Simplify * Purpose: * Simplify the Mapping represented by a Region. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstMapping *Simplify( AstMapping *this, int *status ) * Class Membership: * NullRegion method (over-rides the astSimplify method inherited * from the Region class). * Description: * This function invokes the parent Region Simplify method, and then * performs any further region-specific simplification. * * If the Mapping from base to current Frame is not a UnitMap, this * will include attempting to fit a new Region to the boundary defined * in the current Frame. * Parameters: * this * Pointer to the original Region. * status * Pointer to the inherited status variable. * Returned Value: * A pointer to the simplified Region. A cloned pointer to the * supplied Region will be returned if no simplication could be * performed. * Notes: * - 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 *frm; /* Current Frame */ AstMapping *map; /* Base->current Mapping */ AstMapping *result; /* Result pointer to return */ AstRegion *new; /* Simplified Region */ AstRegion *this; /* Pointer to supplied Region structure */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the supplied Region structure. */ this = (AstRegion *) this_mapping; /* Invoke the parent Simplify method inherited from the Region class. This will simplify the encapsulated FrameSet and uncertainty Region. */ new = (AstRegion *) (*parent_simplify)( this_mapping, status ); /* Is the Mapping from base Frame to current Frame in the Region a UnitMap? If so, no simplification is possible. */ map = astGetMapping( new->frameset, AST__BASE, AST__CURRENT ); if( astIsAUnitMap( map ) ){ result = astClone( new ); } else { /* Create a NullRegion from the current Frame. */ frm = astGetFrame( new->frameset, AST__CURRENT ); result = (AstMapping *) astNullRegion( frm, astGetUnc( new, 0 ), "", status ); /* Free resources. */ frm = astAnnul( frm ); } map = astAnnul( map ); new = astAnnul( new ); /* If any simplification could be performed, copy Region attributes from the supplied Region to the returned Region, and return a pointer to it. If the supplied Region had no uncertainty, ensure the returned Region has no uncertainty. Otherwise, return a clone of the supplied pointer. */ if( result != this_mapping ) astRegOverlay( result, this, 1 ); /* If an error occurred, annul the returned pointer. */ if ( !astOK ) result = astAnnul( result ); /* Return the result. */ return result; } static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, int forward, AstPointSet *out, int *status ) { /* * Name: * Transform * Purpose: * Apply a NullRegion to transform a set of points. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstPointSet *Transform( AstMapping *this, AstPointSet *in, * int forward, AstPointSet *out, int *status ) * Class Membership: * NullRegion member function (over-rides the astTransform protected * method inherited from the Mapping class). * Description: * This function takes a NullRegion and a set of points encapsulated in a * PointSet and transforms the points by setting axis values to * AST__BAD for all points which are outside the region. Points inside * the region are copied unchanged from input to output. * Parameters: * this * Pointer to the NullRegion. * 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: * - The forward and inverse transformations are identical for a * Region. * - A null pointer will be returned if this function is invoked with the * global error status set, or if it should fail for any reason. * - The number of coordinate values per point in the input PointSet must * match the number of axes in the Frame represented by the NullRegion. * - If an output PointSet is supplied, it must have space for sufficient * number of points and coordinate values per point to accommodate the * result. Any excess space will be ignored. */ /* Local Variables: */ AstNullRegion *this; /* Pointer to NullRegion */ AstPointSet *result; /* Pointer to output PointSet */ double **ptr_out; /* Pointer to output coordinate data */ double *p; /* Pointer to next axis value */ int coord; /* Zero-based index for coordinates */ int ncoord_out; /* No. of coordinates per output point */ int npoint_out; /* No. of points */ int point; /* Loop counter for points */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Obtain a pointer to the NullRegion structure. */ this = (AstNullRegion *) this_mapping; /* Apply the parent mapping using the stored pointer to the Transform member function inherited from the parent Region class. This function validates all arguments and generates an output PointSet if necessary, containing a copy of the input PointSet. */ result = (*parent_transform)( this_mapping, in, forward, out, status ); /* We will now extend the parent astTransform method by performing the calculations needed to generate the output coordinate values. */ /* If the NullRegion has been inverted, it represents an infinite region which includes all points, so just retain the copy of the supplied PointSet created by the parent Transform method above. If the NullRegion has not been inverted, it contains no points and so set all output points bad. */ if( !astGetNegated( this ) ) { ncoord_out = astGetNcoord( result ); npoint_out = astGetNpoint( result ); ptr_out = astGetPoints( result ); if ( astOK ) { for ( coord = 0; coord < ncoord_out; coord++ ) { p = ptr_out[ coord ]; for ( point = 0; point < npoint_out; point++ ) { *(p++) = AST__BAD; } } } } /* Annul the result if an error has occurred. */ if( !astOK ) result = astAnnul( result ); /* Return a pointer to the output PointSet. */ return result; } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with this class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* Copy constructor. */ /* ----------------- */ /* None */ /* Destructor. */ /* ----------- */ /* None */ /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for NullRegion 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 NullRegion class to an output Channel. * Parameters: * this * Pointer to the NullRegion 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 Variables: */ AstNullRegion *this; /* Pointer to the NullRegion structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the NullRegion structure. */ this = (AstNullRegion *) this_object; /* Write out values representing the instance variables for the NullRegion 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. */ /* There are no values to write, so return without further action. */ } /* Standard class functions. */ /* ========================= */ /* Implement the astIsANullRegion and astCheckNullRegion functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(NullRegion,Region) astMAKE_CHECK(NullRegion) AstNullRegion *astNullRegion_( void *frame_void, AstRegion *unc, const char *options, int *status, ...) { /* *++ * Name: c astNullRegion f AST_NULLREGION * Purpose: * Create a NullRegion. * Type: * Public function. * Synopsis: c #include "nullregion.h" c AstNullRegion *astNullRegion( AstFrame *frame, AstRegion *unc, const char *options, ... ) f RESULT = AST_NULLREGION( FRAME, UNC, OPTIONS, STATUS ) * Class Membership: * NullRegion constructor. * Description: * This function creates a new NullRegion and optionally initialises its * attributes. * * A NullRegion is a Region with no bounds. If the Negated attribute of a * NullRegion is false, the NullRegion represents a Region containing no * points. If the Negated attribute of a NullRegion is true, the NullRegion * represents an infinite Region containing all points within the * coordinate system. * Parameters: c frame f FRAME = INTEGER (Given) * A pointer to the Frame in which the region is defined. A deep * copy is taken of the supplied Frame. This means that any * subsequent changes made to the Frame using the supplied pointer * will have no effect the Region. c unc f UNC = INTEGER (Given) * An optional pointer to an existing Region which specifies the * uncertainties associated with positions in the supplied Frame. * The uncertainty in any point in the Frame is found by shifting the * supplied "uncertainty" Region so that it is centred at the point * being considered. The area covered by the shifted uncertainty * Region then represents the uncertainty in the position. The * uncertainty is assumed to be the same for all points. * * If supplied, the uncertainty Region must be of a class for which * all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) * or be a Prism containing centro-symetric component Regions. A deep * copy of the supplied Region will be taken, so subsequent changes to * the uncertainty Region using the supplied pointer will have no * effect on the created NullRegion. Alternatively, f a null Object pointer (AST__NULL) c a NULL Object pointer * may be supplied, in which case a default uncertainty of zero is * used. 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 NullRegion. 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. f A character string containing an optional comma-separated f list of attribute assignments to be used for initialising the f new NullRegion. The syntax used is identical to that for the f AST_SET routine. 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 astNullRegion() f AST_NULLREGION = INTEGER * A pointer to the new NullRegion. * Notes: * - A null Object pointer (AST__NULL) will be returned if this c function is invoked with the AST error status set, or if it f function is invoked with STATUS set to an error value, or if it * should fail for any reason. *-- */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstNullRegion *new; /* Pointer to new NullRegion */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global status. */ if ( !astOK ) return NULL; /* Obtain and validate a pointer to the supplied Frame structure. */ frame = astCheckFrame( frame_void ); /* Initialise the NullRegion, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitNullRegion( NULL, sizeof( AstNullRegion ), !class_init, &class_vtab, "NullRegion", frame, unc ); /* 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 NullRegion'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 NullRegion. */ return new; } AstNullRegion *astNullRegionId_( void *frame_void, void *unc_void, const char *options, ... ) { /* * Name: * astNullRegionId_ * Purpose: * Create a NullRegion. * Type: * Private function. * Synopsis: * #include "nullregion.h" * AstNullRegion *astNullRegionId_( AstFrame *frame, AstRegion *unc, const char *options, ... ) * Class Membership: * NullRegion constructor. * Description: * This function implements the external (public) interface to the * astNullRegion constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astNullRegion_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astNullRegion_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astNullRegion_. * Returned Value: * The ID value associated with the new NullRegion. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstFrame *frame; /* Pointer to Frame structure */ AstNullRegion *new; /* Pointer to new NullRegion */ AstRegion *unc; /* Pointer to Region structure */ va_list args; /* Variable argument list */ int *status; /* 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 NULL; /* Obtain a Frame pointer from the supplied ID and validate the pointer to ensure it identifies a valid Frame. */ frame = astVerifyFrame( astMakePointer( frame_void ) ); /* Obtain a Region pointer from the supplied "unc" ID and validate the pointer to ensure it identifies a valid Region . */ unc = unc_void ? astCheckRegion( astMakePointer( unc_void ) ) : NULL; /* Initialise the NullRegion, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitNullRegion( NULL, sizeof( AstNullRegion ), !class_init, &class_vtab, "NullRegion", frame, unc ); /* 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 NullRegion'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 NullRegion. */ return astMakeId( new ); } AstNullRegion *astInitNullRegion_( void *mem, size_t size, int init, AstNullRegionVtab *vtab, const char *name, AstFrame *frame, AstRegion *unc, int *status ) { /* *+ * Name: * astInitNullRegion * Purpose: * Initialise a NullRegion. * Type: * Protected function. * Synopsis: * #include "nullregion.h" * AstNullRegion *astInitNullRegion_( void *mem, size_t size, int init, * AstNullRegionVtab *vtab, const char *name, * AstFrame *frame, AstRegion *unc ) * Class Membership: * NullRegion initialiser. * Description: * This function is provided for use by class implementations to initialise * a new NullRegion object. It allocates memory (if necessary) to accommodate * the NullRegion plus any additional data associated with the derived class. * It then initialises a NullRegion 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 NullRegion at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the NullRegion is to be initialised. * This must be of sufficient size to accommodate the NullRegion data * (sizeof(NullRegion)) 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 NullRegion (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 NullRegion * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the NullRegion'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 NullRegion. * 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 * A pointer to the Frame in which the region is defined. * unc * A pointer to a Region which specifies the uncertainty of positions * within the supplied Frame. A NULL pointer can be supplied, in which * case default uncertainties of zero are used. If an uncertainty * Region is supplied, it must be either a Box, a Circle or an Ellipse, * and its encapsulated Frame must be related to the Frame supplied * for parameter "frame" (i.e. astConvert should be able to find a * Mapping between them). The centre of the supplied uncertainty * Region is immaterial since it will be re-centred on the point * being tested before use. A deep copy is taken of the supplied * Region. * Returned Value: * A pointer to the new NullRegion. * 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: */ AstNullRegion *new; /* Pointer to new NullRegion */ /* Check the global status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitNullRegionVtab( vtab, name ); /* Initialise a Region structure (the parent class) as the first component within the NullRegion structure, allocating memory if necessary. */ new = (AstNullRegion *) astInitRegion( mem, size, 0, (AstRegionVtab *) vtab, name, frame, NULL, unc ); /* If an error occurred, clean up by deleting the new NullRegion. */ if ( !astOK ) new = astDelete( new ); /* Return a pointer to the new NullRegion. */ return new; } AstNullRegion *astLoadNullRegion_( void *mem, size_t size, AstNullRegionVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadNullRegion * Purpose: * Load a NullRegion. * Type: * Protected function. * Synopsis: * #include "nullregion.h" * AstNullRegion *astLoadNullRegion( void *mem, size_t size, AstNullRegionVtab *vtab, * const char *name, AstChannel *channel ) * Class Membership: * NullRegion loader. * Description: * This function is provided to load a new NullRegion 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 * NullRegion structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a NullRegion at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the NullRegion is to be * loaded. This must be of sufficient size to accommodate the * NullRegion data (sizeof(NullRegion)) 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 NullRegion (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 NullRegion 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(AstNullRegion) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new NullRegion. If this is NULL, a pointer * to the (static) virtual function table for the NullRegion 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 "NullRegion" is used instead. * Returned Value: * A pointer to the new NullRegion. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstNullRegion *new; /* Pointer to the new NullRegion */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this NullRegion. In this case the NullRegion belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstNullRegion ); vtab = &class_vtab; name = "NullRegion"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitNullRegionVtab( 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 NullRegion. */ new = astLoadRegion( mem, size, (AstRegionVtab *) 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, "NullRegion" ); /* 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. */ /* There are no values to read. */ /* ---------------------------- */ /* If an error occurred, clean up by deleting the new NullRegion. */ if ( !astOK ) new = astDelete( new ); } /* Return the new NullRegion pointer. */ return new; } /* 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. */ ast-8.3.0/stcobsdatalocation.h0000664000175000017500000001732213004147321013265 00000000000000#if !defined( STCOBSDATALOCATION_INCLUDED ) /* Include this file only once */ #define STCOBSDATALOCATION_INCLUDED /* *+ * Name: * stcobsdatalocation.h * Type: * C include file. * Purpose: * Define the interface to the StcObsDataLocation class. * Invocation: * #include "stcobsdatalocation.h" * Description: * This include file defines the interface to the StcObsDataLocation class * and provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The StcObsDataLocation class is a sub-class of Stc used to describe * the an observation contained in some VO resource. * * See http://hea-www.harvard.edu/~arots/nvometa/STC.html * Inheritance: * The StcObsDataLocation class inherits from the Stc class. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 25-APR-2005 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "stc.h" /* Coordinate stcs (parent class) */ #include "pointlist.h" /* Points within coordinate systems */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* StcObsDataLocation structure. */ /* ----------------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstStcObsDataLocation { /* Attributes inherited from the parent class. */ AstStc stc; /* Parent class structure */ /* Attributes specific to the StcObsDataLOcation class. */ AstPointList *obs; /* Observatory position */ } AstStcObsDataLocation; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstStcObsDataLocationVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstStcVtab stc_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ void (* StcSetObs)( AstStcObsDataLocation *, AstPointList *, int * ); } AstStcObsDataLocationVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstStcObsDataLocationGlobals { AstStcObsDataLocationVtab Class_Vtab; int Class_Init; } AstStcObsDataLocationGlobals; /* Thread-safe initialiser for all global data used by this module. */ void astInitStcObsDataLocationGlobals_( AstStcObsDataLocationGlobals * ); #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(StcObsDataLocation) /* Check class membership */ astPROTO_ISA(StcObsDataLocation) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstStcObsDataLocation *astStcObsDataLocation_( void *, int, AstKeyMap **, const char *, int *, ...); #else AstStcObsDataLocation *astStcObsDataLocationId_( void *, int, AstKeyMap **, const char *, ... )__attribute__((format(printf,4,5))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstStcObsDataLocation *astInitStcObsDataLocation_( void *, size_t, int, AstStcObsDataLocationVtab *, const char *, AstRegion *, int, AstKeyMap **, int * ); /* Vtab initialiser. */ void astInitStcObsDataLocationVtab_( AstStcObsDataLocationVtab *, const char *, int * ); /* Loader. */ AstStcObsDataLocation *astLoadStcObsDataLocation_( void *, size_t, AstStcObsDataLocationVtab *, const char *, AstChannel *, int * ); #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ void astStcSetObs_( AstStcObsDataLocation *, AstPointList *, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckStcObsDataLocation(this) astINVOKE_CHECK(StcObsDataLocation,this,0) #define astVerifyStcObsDataLocation(this) astINVOKE_CHECK(StcObsDataLocation,this,1) /* Test class membership. */ #define astIsAStcObsDataLocation(this) astINVOKE_ISA(StcObsDataLocation,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astStcObsDataLocation astINVOKE(F,astStcObsDataLocation_) #else #define astStcObsDataLocation astINVOKE(F,astStcObsDataLocationId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitStcObsDataLocation(mem,size,init,vtab,name,region,ncoords,coords) \ astINVOKE(O,astInitStcObsDataLocation_(mem,size,init,vtab,name,region,ncoords,coords,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitStcObsDataLocationVtab(vtab,name) astINVOKE(V,astInitStcObsDataLocationVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadStcObsDataLocation(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadStcObsDataLocation_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckStcObsDataLocation to validate StcObsDataLocation pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astStcSetObs(this,obs) \ astINVOKE(V,astStcSetObs_(astCheckStcObsDataLocation(this),obs?astCheckPointList(obs):NULL,STATUS_PTR)) #endif #endif ast-8.3.0/fcircle.c0000664000175000017500000000753113004147321011010 00000000000000/* *+ * Name: * fcircle.c * Purpose: * Define a FORTRAN 77 interface to the AST Circle class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Circle class. * Routines Defined: * AST_ISACIRCLE * AST_CIRCLE * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 31-AUG-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "circle.h" /* C interface to the Circle class */ F77_LOGICAL_FUNCTION(ast_isacircle)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISACIRCLE", NULL, 0 ); astWatchSTATUS( RESULT = astIsACircle( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_circle)( INTEGER(FRAME), INTEGER(FORM), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), INTEGER(UNC), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(FRAME) GENPTR_INTEGER(FORM) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) GENPTR_INTEGER(UNC) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_CIRCLE", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astCircle( astI2P( *FRAME ), *FORM, POINT1, POINT2, astI2P( *UNC ), "%s", options ) ); astFree( options ); ) return RESULT; } F77_SUBROUTINE(ast_circlepars)( INTEGER(THIS), DOUBLE_ARRAY(CENTRE), DOUBLE(RADIUS), DOUBLE_ARRAY(P1), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(CENTRE) GENPTR_DOUBLE(RADIUS) GENPTR_DOUBLE_ARRAY(P1) astAt( "AST_CIRCLEPARS", NULL, 0 ); astWatchSTATUS( astCirclePars( astI2P( *THIS ), CENTRE, RADIUS, P1 ); ) } ast-8.3.0/ast_link_adam0000664000175000017500000004045213004147333011750 00000000000000 # N.B. the previous line should be blank. #++ # Name: # ast_link_adam # Purpose: # Link an ADAM program with the AST library. # Type of Module: # Shell script. # Description: # This command should only be used when building Starlink ADAM programs # which use the AST library, in order to generate the correct arguments # to allow the ADAM ``alink'' command to link the program. The arguments # generated are written to standard output but may be substituted into # the ``alink'' command line in the standard UNIX way using backward # quotes (see below). # # By default, it is assumed that you are building an ADAM program which # does not produce graphical output. However, switches are provided for # linking other types of program. This command should not be used when # building stand-alone (non-ADAM) programs. Use the ``ast_link'' command # instead. # Invocation: #c alink program.o -L/star/lib `ast_link_adam [switches]` #f alink program.f -L/star/lib `ast_link_adam [switches]` # Switches: # The following switches may optionally be given to this command to # modify its behaviour: # # - ``-csla'': Ignored. Provided for backward compatibility only. # # - ``-fsla'': Ignored. Provided for backward compatibility only. # # - ``-grf'': Requests that no arguments be generated to specify which # 2D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new graphics system yourself and wish to provide your own arguments for # linking with it. This switch differs from the other ``grf'' switches in # that it assumes that your graphics module implements the complete # interface required by the current version of AST. If future versions of # AST introduce new functions to the graphics interface, this switch will # cause ``unresolved symbol'' errors to occur during linking, warning you # that you need to implement new functions in your graphics module. To # avoid such errors, you can use one of the other, version-specific, # switches in place of the ``-grf'' switch, but these will cause run-time # errors to be reported if any AST function is invoked which requires # facilities not in the implemented interface. # # - ``-grf_v2.0'': This switch is equivalent to the ``-mygrf'' switch. # It indicates that you want to link with your own graphics module which # implements the 2D graphics interface required by V2.0 of AST. # # - ``-grf_v3.2'': Indicates that you want to link with your own graphics # module which implements the 2D graphics interface required by V3.2 of AST. # # - ``-grf_v5.6'': Indicates that you want to link with your own graphics # module which implements the 2D graphics interface required by V5.6 of AST. # # - ``-myerr'': Requests that no arguments be generated to specify how # error messages produced by the AST library should be delivered. You # should use this option only if you have implemented an interface to a # new error delivery system yourself and wish to provide your own # arguments for linking with it. By default, error messages are delivered # in the standard ADAM way via the EMS Error Message Service (Starlink # System Note SSN/4). # # - ``-mygrf'': This switch has been superceeded by the ``-grf'' switch, # but is retained in order to allow applications to be linked with a # graphics module which implements the interface used by AST V2.0. It is # equivalent to the ``-grf_v2.0'' switch. # # - ``-pgp'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot'': Requests that the program be linked so that 2D # graphical output from the AST library is displayed via the # standard (or ``native'') version of the PGPLOT graphics # package. By default, no graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # # - ``-grf3d'': Requests that no arguments be generated to specify which # 3D graphics system is used to display output from the AST library. You # should use this option only if you have implemented an interface to a # new 3D graphics system yourself and wish to provide your own arguments # for linking with it. # # - ``-pgp3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via the # Starlink version of the PGPLOT graphics package (which uses GKS # for its output). By default, no 3D graphics package is linked and # this will result in an error at run time if AST routines are # invoked that attempt to generate graphical output. # # - ``-pgplot3d'': Requests that the program be linked so that 3D # graphical output from the AST library is displayed via # the standard (or ``native'') version of the PGPLOT graphics # package. By default, no 3D graphics package is linked and this will # result in an error at run time if AST routines are invoked that # attempt to generate graphical output. # SLALIB: # The AST distribution includes a cut down subset of the C version of # the SLALIB library written by Pat Wallace. This subset contains only # the functions needed by the AST library. It is built as part of the # process of building AST and is distributed under GPL (and is thus # compatible with the AST license). Previous version of this script # allowed AST applications to be linked against external SLALIB # libraries (either Fortran or C) rather than the internal version. # The current version of this script does not provide this option, # and always uses the internal SLALIB library. However, for backward # compatibility, this script still allows the "-fsla" and "-csla" flags # (previously used for selecting which version of SLALIB to use) to be # specified, but they will be ignored. # Examples: #c alink display.o -L/star/lib `ast_link_adam -pgplot` #c Links an ADAM program ``display'' which uses the standard #c version of PGPLOT for graphical output. #c alink plotit.o -L. -L/star/lib `ast_link_adam -grf` -lgrf #c Links an ADAM program ``plotit'', written in C. The ``-grf'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by the current version of AST. #c Here, this interface is supplied by means of the ``-lgrf'' library #c reference. #c alink plotit.o -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf #c Links an ADAM program ``plotit'', written in C. The ``-grf_v2.0'' #c switch indicates that graphical output will be delivered through #c a graphical interface which you have implemented yourself, which #c corresponds to the interface required by version 2.0 of AST. Here, #c this interface is supplied by means of the ``-lgrf'' library #c reference. #f alink display.f -L/star/lib `ast_link_adam -pgplot` #f Compiles and links an ADAM Fortran program called ``display'' which #f uses the standard version of PGPLOT for graphical output. #f alink plotit.f -L. -L/star/lib `ast_link_adam -grf` -lgrf #f Compiles and links an ADAM Fortran program ``plotit''. The ``-grf'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by the current version of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. #f alink plotit.f -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf #f Compiles and links an ADAM Fortran program ``plotit''. The ``-grf_v2.0'' #f switch indicates that graphical output will be delivered through #f a graphical interface which you have implemented yourself, which #f corresponds to the interface required by version 2.0 of AST. #f Here, this interface is supplied by means of the ``-lgrf'' library #f reference. # Copyright: # Copyright (C) 1997-2006 Council for the Central Laboratory of the Research Councils # Authors: # RFWS: R.F. Warren-Smith (STARLINK) # {enter_new_authors_here} # History: # 11-NOV-1996 (RFWS): # Original version. # 18-NOV-1997 (RFWS): # Adapted prologue for document extraction. # 28-SEP-1998 (RFWS): # Distinguish between -pgp and -pgplot options. # 23-JAN-2004 (DSB): # Added switches to support older grf implementations. # 21-APR-2005 (DSB): # Added "-fsla" option. # 16-JUN-2006 (DSB): # Ignore "-fsla" and "-clsa" options, and always use PAL. # 22-AUG-2007 (DSB): # Added "-grf3d", "-pgplot3d" and "-pgp3d" flags. # 4-MAR-2011 (DSB): # Added v5.6 grf options. # {enter_changes_here} # Bugs: # {note_any_bugs_here} #-- # This function searches the directory path specified in PATH, looking for # an executable file which is not a directory. If found, it echos the full # file name to standard output. Otherwise, it outputs nothing. find() { IFS=':'; for d in $PATH; do f="${d:=.}/${1}" test -x "${f}" -a ! -d "${f}" && echo "${f}" && break done; } # Initialise linking options. err='' grf='' grf3d='' sla='' # Interpret command line switches. # -------------------------------- while :; do case "${1}" in # -csla - Previously used to request C version of SLALIB. Now ignored. -csla) # sla='c' shift;; # -fsla - Previously used to request Fortran version of SLALIB. Now ignored. -fsla) # sla='f' shift;; # -myerr - Requests no error reporting. -myerr) err='my' shift;; # -grf - Requests no 2D graphics. -grf) grf='current' shift;; # -mygrf - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -mygrf) grf='v2.0' shift;; # -grf_v2.0 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V2.0. -grf_v2.0) grf='v2.0' shift;; # -grf_v3.2 - Requests no 2D graphics, except for null implementations of # functions aded to the grf interface after AST V3.2. -grf_v3.2) grf='v3.2' shift;; # -grf_v5.6 - Requests no 2D graphics, except for null implementations of # functions added to the grf interface after AST V5.6. -grf_v5.6) grf='v5.6' shift;; # -pgp - Requests 2D graphical output through Starlink PGPLOT. -pgp) grf='pgp' shift;; # -pgplot - Requests 2D graphical output through native PGPLOT. -pgplot) grf='pgplot' shift;; # -grf3d - Requests no 3D graphics. -grf3d) grf3d='current' shift;; # -pgp3d - Requests 3D graphical output through Starlink PGPLOT. -pgp3d) grf3d='pgp' shift;; # -pgplot3d - Requests 3D graphical output through native PGPLOT. -pgplot3d) grf3d='pgplot' shift;; # Once all switches have been read, continue with the rest of the script. '') break;; # Catch unrecognised switches and report an error. *) echo >&2 "ast_link_adam: unknown argument \""${1}"\" given" exit 1;; esac done # Link with the main AST library. # ------------------------------- # Start forming the list of arguments with the main AST library itself. args='-last' # Generate arguments for linking PAL. # ----------------------------------- case "0" in # If we configured --with-external_pal include a link option to pick up # an external PAL library. 1) args="${args} -lpal";; # Otherwise, use the internal PAL & ERFA libraries. *) args="${args} -last_pal";; esac # Generate arguments for linking the 2D graphics system. # ------------------------------------------------------ case "${grf}" in # If using Starlink PGPLOT, link with the AST PGPLOT interface and # the Fortran library via the PGP link script. pgp) args="${args} -last_pgplot `pgp_link_adam`";; # If using native PGPLOT, link with the AST PGPLOT interface and # the Fortran library via the PGPLOT link script. pgplot) args="${args} -last_pgplot `pgplot_link_adam`";; # If using own graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # If using own graphics which conform to the requirements of version 5.6 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 5.6. v5.6) :;; # If using own graphics which conform to the requirements of version 3.2 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 3.2. v3.2) args="${args} -last_grf_5.6";; # If using own graphics which conform to the requirements of version 2.0 # of AST, produce arguments which link in dummy implementations of any # functions which are required by the current version of AST but which were # not required by version 2.0. v2.0) args="${args} -last_grf_3.2 -last_grf_5.6";; # Default graphics (none) requires linking with all the default (null) AST # "grf" modules. *) args="${args} -last_grf_2.0 -last_grf_3.2 -last_grf_5.6";; esac # Generate arguments for linking the 3D graphics system. # ------------------------------------------------------ case "${grf3d}" in # If using Starlink PGPLOT, link with the AST 3D PGPLOT interface and # the Fortran library via the PGP link script (if found). pgp) args="${args} -last_pgplot3d `\`find pgp_link\``" f77='y';; # If using native PGPLOT, link with the AST 3D PGPLOT interface and the # Fortran library via the PGPLOT link script (if found). pgplot) args="${args} -last_pgplot3d `\`find pgplot_link\``" f77='y';; # If using own 3D graphics which conform to the requirements of the current # version of AST, do not produce any arguments. current) :;; # Default graphics (none) requires linking with all the default (null) AST # "grf3d" modules. *) args="${args} -last_grf3d";; esac # Make a second pass through the AST library. # ------------------------------------------- # This library is a link to the main AST library and results in a second # pass to resolve any backward references generated by the other modules # used above. A different library name must be used to avoid the two passes # being merged into one (either below, or by other link scripts). args="${args} -last_pass2" # Generate arguments for linking the error reporting system. # ---------------------------------------------------------- case "${err}" in # If using own error reporting, do not produce any arguments. my) :;; # Default error reporting requires linking with the AST EMS interface and # the EMS library via the link script. *) args="${args} -last_ems `ems_link_adam`";; esac # Link with the maths library. # ---------------------------- args="${args} -lm" # Link with the starmem library, if available. # -------------------------------------------- args="${args} `\`find starmem_link\``" # Pass the resulting argument list through an awk script which eliminates # all except the last reference to each library. echo "${args}" \ | awk 'BEGIN{RS=" ";FS="\n"} {if($1)f[i++]=$1} END{for(;i--;)if(!w[f[i]]++)l=f[i]" "l;print l}' # End of script. ast-8.3.0/fmapping.c0000664000175000017500000006541213004147321011204 00000000000000/* *+ * Name: * fmapping.c * Purpose: * Define a FORTRAN 77 interface to the AST Mapping class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Mapping class. * Routines Defined: * AST_DECOMPOSE * AST_INVERT * AST_ISAMAPPING * AST_LINEARMAPPING * AST_REBIN * AST_REBINSEQ * AST_MAPBOX * AST_MAPSPLIT * AST_RATE * AST_REMOVEREGIONS * AST_RESAMPLE * AST_SIMPLIFY * AST_TRAN1 * AST_TRAN2 * AST_TRANGRID * AST_TRANN * AST_RATE * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 11-JUL-1996 (RFWS): * Original version. * 13-DEC-1996 (RFWS) * Added AST_SIMPLIFY. * 28-MAY-1998 (RFWS): * Added AST_MAPBOX. * 12-NOV-1998 (RFWS): * Added AST_RESAMPLE. * 22-NOV-2000 (DSB): * Pass the "flags" argument by reference instead of by value in the * MAKE_AST_RESAMPLE_UINTERP macro. * 9-JAN-2001 (DSB): * Changed in and out arguments for TranN from type "double (*)[]" * to "double *". * 26-SEP-2001 (DSB): * Added AST_DECOMPOSE. * 16-JUL-2003 (DSB): * Added AST_RATE. * 30-JUN-2005 (DSB): * Added AST_REBIN. * 1-SEP-2005 (DSB): * Added AST_REBINSEQ. * 8-MAR-2006 (DSB): * Added AST_TRANGRID. * 5-MAY-2009 (DSB): * Added AST_REMOVEREGIONS. * 4-MAY-2010 (DSB): * Add support for AST__VARWGT flag to AST_REBINSEQ. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "mapping.h" /* C interface to the Mapping class */ #include /* Module Variables. */ /* ================= */ /* Pointer to user-supplied (FORTRAN 77) interpolation function for use by AST_RESAMPLE. */ static void (* ast_resample_FINTERP)(); /* Interpolation function interface. */ /* ================================= */ /* These functions are associated with allowing FORTRAN 77 implementations of interpolation functions to be passed to AST_RESAMPLE via the FORTRAN 77 interface and then to be invoked when necessary by the C code in the main implementation of astResample. */ /* Define a macro which defines an interface function called ast_resample_uinterp for a specific data type. The resulting function has a suitable interface to allow it to be passed as an interpolation function to the C interface of astResample in the case where the "interp" parameter is set to AST__UINTERP. In turn, it invokes the equivalent user-supplied FORTRAN 77 interpolation function, a pointer to which should previously have been stored in the static variable "ast_resample_FINTERP". */ #define MAKE_AST_RESAMPLE_UINTERP(X,Xtype,Ftype) \ static void ast_resample_uinterp##X( int ndim, \ const int lbnd[], const int ubnd[], \ const Xtype in[], const Xtype in_var[], \ int npoint, const int offset[], \ const double *const coords[], \ const double params[], int flags, \ Xtype badval, \ Xtype *out, Xtype *out_var, \ int *nbad ) { \ DECLARE_INTEGER(STATUS); \ int *status; \ \ /* Get a pointer to the inherited staus value. */ \ status = astGetStatusPtr; \ \ /* Obtain the C status and then invoke the FORTRAN 77 interpolation \ function via the stored pointer. Note that the "coords" array we \ pass to FORTRAN has to be a contiguous 2-d array, so we must \ de-reference one level of pointer compared to the C case. */ \ STATUS = astStatus; \ ( *ast_resample_FINTERP )( INTEGER_ARG(&ndim), \ INTEGER_ARRAY_ARG(lbnd), \ INTEGER_ARRAY_ARG(ubnd), \ Ftype##_ARRAY_ARG(in), \ Ftype##_ARRAY_ARG(in_var), \ INTEGER_ARG(&npoint), \ INTEGER_ARRAY_ARG(offset), \ DOUBLE_ARRAY_ARG(coords[ 0 ]), \ DOUBLE_ARRAY_ARG(params), \ INTEGER_ARG(&flags), \ Ftype##_ARG(&badval), \ Ftype##_ARRAY_ARG(out), \ Ftype##_ARRAY_ARG(out_var), \ INTEGER_ARG(nbad), \ INTEGER_ARG(&STATUS) ); \ \ /* Set the C status to the returned FORTRAN 77 status. */ \ astSetStatus( STATUS ); \ } /* Invoke the above macro to define an interface function for each required data type. */ MAKE_AST_RESAMPLE_UINTERP(D,double,DOUBLE) MAKE_AST_RESAMPLE_UINTERP(F,float,REAL) MAKE_AST_RESAMPLE_UINTERP(I,int,INTEGER) MAKE_AST_RESAMPLE_UINTERP(UI,unsigned int,INTEGER) MAKE_AST_RESAMPLE_UINTERP(K,INT_BIG,INTEGER8) MAKE_AST_RESAMPLE_UINTERP(UK,UINT_BIG,INTEGER8) MAKE_AST_RESAMPLE_UINTERP(S,short int,WORD) MAKE_AST_RESAMPLE_UINTERP(US,unsigned short int,UWORD) MAKE_AST_RESAMPLE_UINTERP(B,signed char,BYTE) MAKE_AST_RESAMPLE_UINTERP(UB,unsigned char,UBYTE) /* Undefine the macro. */ #undef MAKE_AST_RESAMPLE_UINTERP /* Define a function called ast_resample_ukern1 which has a suitable interface to allow it to be passed as an interpolation function to the C interface of astResample in the case where the "interp" parameter is set to AST__UKERN1. In turn, it invokes the equivalent user-supplied FORTRAN 77 interpolation function, a pointer to which should previously have been stored in the static variable "ast_resample_FINTERP". */ static void ast_resample_ukern1( double offset, const double params[], int flags, double *value ) { DECLARE_INTEGER(STATUS); int *status; /* Obtain the C status and then invoke the FORTRAN 77 interpolation function via the stored pointer. */ status = astGetStatusPtr; STATUS = astStatus; ( *ast_resample_FINTERP )( DOUBLE_ARG(&offset), DOUBLE_ARRAY_ARG(params), INTEGER_ARG(&flags), DOUBLE_ARG(value), INTEGER_ARG(&STATUS) ); /* Set the C status to the returned FORTRAN 77 status. */ astSetStatus( STATUS ); } /* FORTRAN interface functions. */ /* ============================ */ /* These functions implement the remainder of the FORTRAN interface. */ F77_SUBROUTINE(ast_decompose)( INTEGER(THIS), INTEGER(MAP1), INTEGER(MAP2), LOGICAL(SERIES), INTEGER(INVERT1), INTEGER(INVERT2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(MAP1) GENPTR_INTEGER(MAP2) GENPTR_LOGICAL(SERIES) GENPTR_INTEGER(INVERT1) GENPTR_INTEGER(INVERT2) AstMapping *map1; AstMapping *map2; int series; astAt( "AST_DECOMPOSE", NULL, 0 ); astWatchSTATUS( astDecompose( astI2P( *THIS ), &map1, &map2, &series, INVERT1, INVERT2 ); *MAP1 = astP2I( map1 ); *MAP2 = astP2I( map2 ); *SERIES = ( series )?F77_TRUE:F77_FALSE; ) } F77_SUBROUTINE(ast_invert)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) astAt( "AST_INVERT", NULL, 0 ); astWatchSTATUS( astInvert( astI2P( *THIS ) ); ) } F77_LOGICAL_FUNCTION(ast_isamapping)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAMAPPING", NULL, 0 ); astWatchSTATUS( RESULT = astIsAMapping( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_LOGICAL_FUNCTION(ast_linearapprox)( INTEGER(THIS), DOUBLE_ARRAY(LBND), DOUBLE_ARRAY(UBND), DOUBLE(TOL), DOUBLE_ARRAY(FIT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(LBND) GENPTR_DOUBLE_ARRAY(UBND) GENPTR_DOUBLE(TOL) GENPTR_DOUBLE_ARRAY(FIT) F77_LOGICAL_TYPE(RESULT); astAt( "AST_LINEARAPPROX", NULL, 0 ); astWatchSTATUS( RESULT = astLinearApprox( astI2P( *THIS ), LBND, UBND, *TOL, FIT ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_quadapprox)( INTEGER(THIS), DOUBLE_ARRAY(LBND), DOUBLE_ARRAY(UBND), INTEGER(NX), INTEGER(NY), DOUBLE_ARRAY(FIT), DOUBLE(RMS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(LBND) GENPTR_DOUBLE_ARRAY(UBND) GENPTR_INTEGER(NX) GENPTR_INTEGER(NY) GENPTR_DOUBLE_ARRAY(FIT) GENPTR_DOUBLE(RMS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_QUADAPPROX", NULL, 0 ); astWatchSTATUS( RESULT = astQuadApprox( astI2P( *THIS ), LBND, UBND, *NX, *NY, FIT, RMS ); ) return RESULT; } F77_SUBROUTINE(ast_mapbox)( INTEGER(THIS), DOUBLE_ARRAY(LBND_IN), DOUBLE_ARRAY(UBND_IN), LOGICAL(FORWARD), INTEGER(COORD_OUT), DOUBLE(LBND_OUT), DOUBLE(UBND_OUT), DOUBLE_ARRAY(XL), DOUBLE_ARRAY(XU), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(LBND_IN) GENPTR_DOUBLE_ARRAY(UBND_IN) GENPTR_LOGICAL(FORWARD) GENPTR_INTEGER(COORD_OUT) GENPTR_DOUBLE(LBND_OUT) GENPTR_DOUBLE(UBND_OUT) GENPTR_DOUBLE_ARRAY(XL) GENPTR_DOUBLE_ARRAY(XU) double lbnd_out; double ubnd_out; astAt( "AST_MAPBOX", NULL, 0 ); astWatchSTATUS( astMapBox( astI2P( *THIS ), LBND_IN, UBND_IN, F77_ISTRUE( *FORWARD ), *COORD_OUT, &lbnd_out, &ubnd_out, XL, XU ); *LBND_OUT = lbnd_out; *UBND_OUT = ubnd_out; ) } /* AST_RESAMPLE requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_RESAMPLE(f,F,Ftype,X,Xtype) \ F77_INTEGER_FUNCTION(ast_resample##f)( INTEGER(THIS), \ INTEGER(NDIM_IN), \ INTEGER_ARRAY(LBND_IN), \ INTEGER_ARRAY(UBND_IN), \ Ftype##_ARRAY(IN), \ Ftype##_ARRAY(IN_VAR), \ INTEGER(INTERP), \ void (* FINTERP)(), \ DOUBLE_ARRAY(PARAMS), \ INTEGER(FLAGS), \ DOUBLE(TOL), \ INTEGER(MAXPIX), \ Ftype(BADVAL), \ INTEGER(NDIM_OUT), \ INTEGER_ARRAY(LBND_OUT), \ INTEGER_ARRAY(UBND_OUT), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ Ftype##_ARRAY(OUT), \ Ftype##_ARRAY(OUT_VAR), \ INTEGER(STATUS) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_INTEGER(NDIM_IN) \ GENPTR_INTEGER_ARRAY(LBND_IN) \ GENPTR_INTEGER_ARRAY(UBND_IN) \ GENPTR_##Ftype##_ARRAY(IN) \ GENPTR_##Ftype##_ARRAY(IN_VAR) \ GENPTR_INTEGER(INTERP) \ GENPTR_DOUBLE_ARRAY(PARAMS) \ GENPTR_INTEGER(FLAGS) \ GENPTR_DOUBLE(TOL) \ GENPTR_INTEGER(MAXPIX) \ GENPTR_##Ftype(BADVAL) \ GENPTR_INTEGER(NDIM_OUT) \ GENPTR_INTEGER_ARRAY(LBND_OUT) \ GENPTR_INTEGER_ARRAY(UBND_OUT) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_##Ftype##_ARRAY(OUT) \ GENPTR_##Ftype##_ARRAY(OUT_VAR) \ GENPTR_INTEGER(STATUS) \ \ void (* finterp)(); \ Xtype *out_var; \ const Xtype *in_var; \ F77_INTEGER_TYPE RESULT; \ \ astAt( "AST_RESAMPLE"#F, NULL, 0 ); \ astWatchSTATUS( \ \ /* If *INTERP is set to a value that requires a user-supplied \ interpolation function, then store a pointer to the supplied \ FORTRAN 77 version of this function and use the appropriate C \ wrapper function (defined above) to invoke it. */ \ if ( *INTERP == AST__UINTERP ) { \ ast_resample_FINTERP = FINTERP; \ finterp = (void (*)()) ast_resample_uinterp##X; \ } else if ( *INTERP == AST__UKERN1 ) { \ ast_resample_FINTERP = FINTERP; \ finterp = (void (*)()) ast_resample_ukern1; \ } else { \ ast_resample_FINTERP = NULL; \ finterp = NULL; \ } \ \ /* If the AST__USEVAR flag is set, use the input and output variance \ arrays, otherwise pass NULL pointers. */ \ in_var = out_var = NULL; \ if ( AST__USEVAR & *FLAGS ) { \ in_var = (const Xtype *) IN_VAR; \ out_var = (Xtype *) OUT_VAR; \ } \ RESULT = astResample##X( astI2P( *THIS ), *NDIM_IN, \ LBND_IN, UBND_IN, (const Xtype *) IN, in_var, \ *INTERP, finterp, PARAMS, *FLAGS, \ *TOL, *MAXPIX, *BADVAL, \ *NDIM_OUT, LBND_OUT, UBND_OUT, \ LBND, UBND, (Xtype *) OUT, out_var ); \ ) \ return RESULT; \ } /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_RESAMPLE(d,D,DOUBLE,D,double) MAKE_AST_RESAMPLE(r,R,REAL,F,float) MAKE_AST_RESAMPLE(i,I,INTEGER,I,int) MAKE_AST_RESAMPLE(ui,UI,INTEGER,UI,unsigned int) MAKE_AST_RESAMPLE(k,K,INTEGER8,K,INT_BIG) MAKE_AST_RESAMPLE(uk,UK,INTEGER8,UK,UINT_BIG) MAKE_AST_RESAMPLE(s,S,WORD,S,short int) MAKE_AST_RESAMPLE(us,US,UWORD,US,unsigned short int) MAKE_AST_RESAMPLE(w,W,WORD,S,short int) MAKE_AST_RESAMPLE(uw,UW,UWORD,US,unsigned short int) MAKE_AST_RESAMPLE(b,B,BYTE,B,signed char) MAKE_AST_RESAMPLE(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_RESAMPLE /* AST_REBIN requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_REBIN(f,F,Ftype,X,Xtype) \ F77_SUBROUTINE(ast_rebin##f)( INTEGER(THIS), \ DOUBLE(WLIM), \ INTEGER(NDIM_IN), \ INTEGER_ARRAY(LBND_IN), \ INTEGER_ARRAY(UBND_IN), \ Ftype##_ARRAY(IN), \ Ftype##_ARRAY(IN_VAR), \ INTEGER(INTERP), \ DOUBLE_ARRAY(PARAMS), \ INTEGER(FLAGS), \ DOUBLE(TOL), \ INTEGER(MAXPIX), \ Ftype(BADVAL), \ INTEGER(NDIM_OUT), \ INTEGER_ARRAY(LBND_OUT), \ INTEGER_ARRAY(UBND_OUT), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ Ftype##_ARRAY(OUT), \ Ftype##_ARRAY(OUT_VAR), \ INTEGER(STATUS) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_DOUBLE(WLIM) \ GENPTR_INTEGER(NDIM_IN) \ GENPTR_INTEGER_ARRAY(LBND_IN) \ GENPTR_INTEGER_ARRAY(UBND_IN) \ GENPTR_##Ftype##_ARRAY(IN) \ GENPTR_##Ftype##_ARRAY(IN_VAR) \ GENPTR_INTEGER(INTERP) \ GENPTR_DOUBLE_ARRAY(PARAMS) \ GENPTR_INTEGER(FLAGS) \ GENPTR_DOUBLE(TOL) \ GENPTR_INTEGER(MAXPIX) \ GENPTR_##Ftype(BADVAL) \ GENPTR_INTEGER(NDIM_OUT) \ GENPTR_INTEGER_ARRAY(LBND_OUT) \ GENPTR_INTEGER_ARRAY(UBND_OUT) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_##Ftype##_ARRAY(OUT) \ GENPTR_##Ftype##_ARRAY(OUT_VAR) \ GENPTR_INTEGER(STATUS) \ \ Xtype *out_var; \ const Xtype *in_var; \ \ astAt( "AST_REBIN"#F, NULL, 0 ); \ astWatchSTATUS( \ \ /* If the AST__USEVAR flag is set, use the input and output variance \ arrays, otherwise pass NULL pointers. */ \ in_var = out_var = NULL; \ if ( AST__USEVAR & *FLAGS ) { \ in_var = (const Xtype *) IN_VAR; \ out_var = (Xtype *) OUT_VAR; \ } \ astRebin##X( astI2P( *THIS ), *WLIM, *NDIM_IN, \ LBND_IN, UBND_IN, (const Xtype *) IN, in_var, \ *INTERP, PARAMS, *FLAGS, \ *TOL, *MAXPIX, *BADVAL, \ *NDIM_OUT, LBND_OUT, UBND_OUT, \ LBND, UBND, (Xtype *) OUT, out_var ); \ ) \ } /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_REBIN(d,D,DOUBLE,D,double) MAKE_AST_REBIN(r,R,REAL,F,float) MAKE_AST_REBIN(i,I,INTEGER,I,int) MAKE_AST_REBIN(b,B,BYTE,B,signed char) MAKE_AST_REBIN(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_REBIN /* AST_REBINSEQ requires a function for each possible data type, so define it via a macro. */ #define MAKE_AST_REBINSEQ(f,F,Ftype,X,Xtype) \ F77_SUBROUTINE(ast_rebinseq##f)( INTEGER(THIS), \ DOUBLE(WLIM), \ INTEGER(NDIM_IN), \ INTEGER_ARRAY(LBND_IN), \ INTEGER_ARRAY(UBND_IN), \ Ftype##_ARRAY(IN), \ Ftype##_ARRAY(IN_VAR), \ INTEGER(INTERP), \ DOUBLE_ARRAY(PARAMS), \ INTEGER(FLAGS), \ DOUBLE(TOL), \ INTEGER(MAXPIX), \ Ftype(BADVAL), \ INTEGER(NDIM_OUT), \ INTEGER_ARRAY(LBND_OUT), \ INTEGER_ARRAY(UBND_OUT), \ INTEGER_ARRAY(LBND), \ INTEGER_ARRAY(UBND), \ Ftype##_ARRAY(OUT), \ Ftype##_ARRAY(OUT_VAR), \ DOUBLE_ARRAY(WEIGHTS), \ INTEGER8(NUSED), \ INTEGER(STATUS) ) { \ GENPTR_INTEGER(THIS) \ GENPTR_DOUBLE(WLIM) \ GENPTR_INTEGER(NDIM_IN) \ GENPTR_INTEGER_ARRAY(LBND_IN) \ GENPTR_INTEGER_ARRAY(UBND_IN) \ GENPTR_##Ftype##_ARRAY(IN) \ GENPTR_##Ftype##_ARRAY(IN_VAR) \ GENPTR_INTEGER(INTERP) \ GENPTR_DOUBLE_ARRAY(PARAMS) \ GENPTR_INTEGER(FLAGS) \ GENPTR_DOUBLE(TOL) \ GENPTR_INTEGER(MAXPIX) \ GENPTR_##Ftype(BADVAL) \ GENPTR_INTEGER(NDIM_OUT) \ GENPTR_INTEGER_ARRAY(LBND_OUT) \ GENPTR_INTEGER_ARRAY(UBND_OUT) \ GENPTR_INTEGER_ARRAY(LBND) \ GENPTR_INTEGER_ARRAY(UBND) \ GENPTR_##Ftype##_ARRAY(OUT) \ GENPTR_##Ftype##_ARRAY(OUT_VAR) \ GENPTR_DOUBLE_ARRAY(WEIGHTS) \ GENPTR_INTEGER8(NUSED) \ GENPTR_INTEGER(STATUS) \ \ Xtype *out_var; \ const Xtype *in_var; \ int64_t nused; \ \ astAt( "AST_REBINSEQ"#F, NULL, 0 ); \ astWatchSTATUS( \ \ /* We need the input variances if the AST__USEVAR or AST__VARWGT flag is \ set. Otherwise use a NULL pointer for the input variances. */ \ if ( AST__USEVAR & *FLAGS || AST__VARWGT & *FLAGS ) { \ in_var = (const Xtype *) IN_VAR; \ } else { \ in_var = NULL; \ } \ \ /* We need the output variances if the AST__USEVAR or AST__GENVAR flag is \ set. Otherwise use a NULL pointer for the output variances. */ \ if ( AST__USEVAR & *FLAGS || AST__GENVAR & *FLAGS ) { \ out_var = (Xtype *) OUT_VAR; \ } else { \ out_var = NULL; \ } \ \ nused = *NUSED; \ astRebinSeq##X( astI2P( *THIS ), *WLIM, *NDIM_IN, \ LBND_IN, UBND_IN, (const Xtype *) IN, in_var, \ *INTERP, PARAMS, *FLAGS, \ *TOL, *MAXPIX, *BADVAL, \ *NDIM_OUT, LBND_OUT, UBND_OUT, \ LBND, UBND, (Xtype *) OUT, out_var, WEIGHTS, \ &nused ); \ *NUSED = nused; \ ) \ } \ /* Invoke the above macro to define a function for each data type. Include synonyms for some functions. */ MAKE_AST_REBINSEQ(d,D,DOUBLE,D,double) MAKE_AST_REBINSEQ(r,R,REAL,F,float) MAKE_AST_REBINSEQ(i,I,INTEGER,I,int) MAKE_AST_REBINSEQ(b,B,BYTE,B,signed char) MAKE_AST_REBINSEQ(ub,UB,UBYTE,UB,unsigned char) #undef MAKE_AST_REBINSEQ F77_INTEGER_FUNCTION(ast_removeregions)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_REMOVEREGIONS", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astRemoveRegions( astI2P( *THIS ) ) ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_simplify)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_INTEGER_TYPE(RESULT); astAt( "AST_SIMPLIFY", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astSimplify( astI2P( *THIS ) ) ); ) return RESULT; } F77_SUBROUTINE(ast_tran1)( INTEGER(THIS), INTEGER(NPOINT), DOUBLE(XIN), LOGICAL(FORWARD), DOUBLE(XOUT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NPOINT) GENPTR_DOUBLE(XIN) GENPTR_LOGICAL(FORWARD) GENPTR_DOUBLE(XOUT) astAt( "AST_TRAN1", NULL, 0 ); astWatchSTATUS( astTran1( astI2P( *THIS ), *NPOINT, XIN, F77_ISTRUE( *FORWARD ), XOUT ); ) } F77_SUBROUTINE(ast_tran2)( INTEGER(THIS), INTEGER(NPOINT), DOUBLE(XIN), DOUBLE(YIN), LOGICAL(FORWARD), DOUBLE(XOUT), DOUBLE(YOUT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NPOINT) GENPTR_DOUBLE(XIN) GENPTR_DOUBLE(YIN) GENPTR_LOGICAL(FORWARD) GENPTR_DOUBLE(XOUT) GENPTR_DOUBLE(YOUT) astAt( "AST_TRAN2", NULL, 0 ); astWatchSTATUS( astTran2( astI2P( *THIS ), *NPOINT, XIN, YIN, F77_ISTRUE( *FORWARD ), XOUT, YOUT ); ) } F77_SUBROUTINE(ast_trangrid)( INTEGER(THIS), INTEGER(NCOORD_IN), INTEGER_ARRAY(LBND), INTEGER_ARRAY(UBND), DOUBLE(TOL), INTEGER(MAXPIX), LOGICAL(FORWARD), INTEGER(NCOORD_OUT), INTEGER(OUTDIM), DOUBLE_ARRAY(OUT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NCOORD_IN) GENPTR_INTEGER_ARRAY(LBND) GENPTR_INTEGER_ARRAY(UBND) GENPTR_DOUBLE(TOL) GENPTR_INTEGER(MAXPIX) GENPTR_LOGICAL(FORWARD) GENPTR_INTEGER(NCOORD_OUT) GENPTR_INTEGER(OUTDIM) GENPTR_DOUBLE_ARRAY(OUT) astAt( "AST_TRANGRID", NULL, 0 ); astWatchSTATUS( astTranGrid( astI2P( *THIS ), *NCOORD_IN, LBND, UBND, *TOL, *MAXPIX, F77_ISTRUE( *FORWARD ), *NCOORD_OUT, *OUTDIM, OUT ); ) } F77_SUBROUTINE(ast_trann)( INTEGER(THIS), INTEGER(NPOINT), INTEGER(NCOORD_IN), INTEGER(INDIM), DOUBLE_ARRAY(IN), LOGICAL(FORWARD), INTEGER(NCOORD_OUT), INTEGER(OUTDIM), DOUBLE_ARRAY(OUT), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NPOINT) GENPTR_INTEGER(NCOORD_IN) GENPTR_INTEGER(INDIM) GENPTR_DOUBLE_ARRAY(IN) GENPTR_LOGICAL(FORWARD) GENPTR_INTEGER(NCOORD_OUT) GENPTR_INTEGER(OUTDIM) GENPTR_DOUBLE_ARRAY(OUT) astAt( "AST_TRANN", NULL, 0 ); astWatchSTATUS( astTranN( astI2P( *THIS ), *NPOINT, *NCOORD_IN, *INDIM, (const double *)IN, F77_ISTRUE( *FORWARD ), *NCOORD_OUT, *OUTDIM, OUT ); ) } F77_DOUBLE_FUNCTION(ast_rate)( INTEGER(THIS), DOUBLE_ARRAY(AT), INTEGER(AX1), INTEGER(AX2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(AX1) GENPTR_INTEGER(AX2) GENPTR_DOUBLE_ARRAY(AT) F77_DOUBLE_TYPE(RESULT); astAt( "AST_RATE", NULL, 0 ); astWatchSTATUS( RESULT = astRate( astI2P( *THIS ), AT, *AX1, *AX2 ); ) return RESULT; } F77_SUBROUTINE(ast_mapsplit)( INTEGER(THIS), INTEGER(NIN), INTEGER_ARRAY(IN), INTEGER_ARRAY(OUT), INTEGER(MAP), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NIN) GENPTR_INTEGER_ARRAY(IN) GENPTR_INTEGER_ARRAY(OUT) GENPTR_INTEGER(MAP) AstMapping *map; astAt( "AST_MAPSPLIT", NULL, 0 ); astWatchSTATUS( astMapSplit( astI2P( *THIS ), *NIN, IN, OUT, &map ); *MAP = astP2I( map ); ) } ast-8.3.0/fmathmap.c0000664000175000017500000000756013004147321011200 00000000000000/* *+ * Name: * fmathmap.c * Purpose: * Define a FORTRAN 77 interface to the AST MathMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the MathMap class. * Routines Defined: * AST_ISAMATHMAP * AST_MATHMAP * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 3-SEP-1999 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "mathmap.h" /* C interface to the MathMap class */ F77_LOGICAL_FUNCTION(ast_isamathmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAMATHMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAMathMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_mathmap)( INTEGER(NIN), INTEGER(NOUT), INTEGER(NFWD), CHARACTER_ARRAY(FWD), INTEGER(NINV), CHARACTER_ARRAY(INV), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(FWD) TRAIL(INV) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NIN) GENPTR_INTEGER(NOUT) GENPTR_INTEGER(NFWD) GENPTR_CHARACTER_ARRAY(FWD) GENPTR_INTEGER(NINV) GENPTR_CHARACTER_ARRAY(INV) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char **fwd; char **inv; char *options; int i; astAt( "AST_MATHMAP", NULL, 0 ); astWatchSTATUS( fwd = astStringArray( FWD, *NFWD, FWD_length ); inv = astStringArray( INV, *NINV, INV_length ); options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astMathMap( *NIN, *NOUT, *NFWD, (const char **) fwd, *NINV, (const char **) inv, "%s", options ) ); astFree( options ); astFree( inv ); astFree( fwd ); ) return RESULT; } ast-8.3.0/sst.sty0000664000175000017500000001707612710127547010627 00000000000000\ProvidesPackage{sst} %%%% % Packet for formatting latex code output from prolat %%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % .. Set up the sectioning and appearance for the sstroutine. \RequirePackage{titlesec} %... New subsection sstrefsection \titleclass{\sstrefsection}{straight}[\subsection] \newcounter{sstrefsection} \renewcommand{\thesstrefsection}{\arabic{sstrefsection}} %... Formatting the title for sstrefsection \titleformat{name=\sstrefsection}% {\normalfont\Large\bfseries\centering}{}{0pt}{} \titlespacing*{\sstrefsection}{0pt}{3.5ex plus 1ex minus .2ex}{2.3ex plus .2ex} %... Command to turn name and short description into single variable for title. \newcommand{\sstsectitle}[2]{\strut \vphantom{#1}#1\newline \ignorespaces#2\strut} % .. Command to completely remove section from contents so it can be % added in manually at the correct section. \newcommand{\nocontentsline}[3]{} \newcommand{\tocless}[2]{\bgroup\let\addcontentsline=\nocontentsline#1{#2}\egroup} %% Add a toc entry which will be used in the main toc \newcommand{\sstmaintocline}[2]{\addcontentsline{toc}{subsection}{\protect\numberline{}#1}} %% commands to temporarily stop sstroutines from writing anything into the main toc \newcommand{\sstnomaintoc}{\renewcommand{\sstmaintocline}[2]{}} %% Command to restart sstroutines appearing in the main html toc %% (does nothing in pdf) \newcommand{\sstmaintoc}{\renewcommand{\sstmaintocline}[2]{\addcontentsline{toc}{subsection}{\protect\numberline{}##1}}} %% .. command to format the sst title \newcommand{\ssttitle}[2]{ \tocless\sstrefsection{\centering\rule{\textwidth}{0.5mm}\\% #1\\#2\\\rule{\textwidth}{0.5mm}} \sstmaintocline{\RemoveSpaces{#1}}{#2} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %... Basic SSTROUTINE command \newcommand{\sstroutine}[3]{ \clearpage % Create the section. \ssttitle{#1}{#2} % Set the first parameter as the label; need to remove spaces first. \label{\RemoveSpaces{#1}} %.. change the mark on the left hand side to include the name of the chapter. \markright{\textit{\RemoveSpaces{#1}}} \iftwoside \fancyhead[RE,LO]{\thepage\hspace{1cm}\rightmark} \else \lhead{\thepage\hspace{1cm}\rightmark} \fi %.. Nest all the material within a description \begin{description}[style=nextline] #3 \end{description} % End the page \newpage } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % .. Various sst macros that are used within an \sstroutine % .. diytopic -- basis for many of th commands. \newcommand{\sstdiytopic}[2]{\item[#1:] \begin{description}[style=nextline]\item[]\end{description} #2} \newcommand{\sstdescription}[1]{\item[Description:] #1 } \newcommand{\sstusage}[1]{\item[Usage:]{\raggedright \tt #1}} \newcommand{\sstparameters}[1]{\item[Parameters:] \begin{description}[style=nextline]\item[] #1 \end{description}} \newcommand{\sstkeywords}[1]{\item[Keywords:] \begin{description}[style=nextline]\item[] #1 \end{description}} \newcommand{\sstsubsection}[2]{\item[{#1}] #2} \newcommand{\sstnotes}[1]{\sstdiytopic{Notes}{#1}} \newcommand{\sstdiylist}[2]{\item[#1] #2} \newcommand{\sstimplementationstatus}[1]{\item[Implementation Status:] #1} \newcommand{\sstbugs}[1]{\item[Bugs:] #1} % Format a list of items while in paragraph mode. \newcommand{\sstitemlist}[1]{ \mbox{}%\vspace{-1\baselineskip} \begin{itemize} #1 \end{itemize} } \newcommand{\ssthitemlist}[1]{\mbox{}\begin{itemize}#1\end{itemize}} \newcommand{\sstapplicability}[1]{\sstdiytopic{Applicability}{#1}} \newcommand{\sstresparameters}[1]{\sstdiytopic{Results Parameters}{#1}} \newcommand{\sstarguments}[1]{\sstdiytopic{Arguments}{#1}} \newcommand{\sstinvocation}[1]{\sstdiytopic{Invocation}{{\tt #1}}} \newcommand{\sstreturnedvalue}[1]{\sstdiytopic{Returned Value}{#1}} \newcommand{\sstimplementation}[1]{\sstdiytopic{Implementation}{#1}} \newcommand{\sstexamplesubsection}[2]{\sloppy \item[{\texttt{\textcolor{MidnightBlue}{#1}}}] #2 } % Set the font of the label of the sstexample items: % (extra \\ spacing is required to not have weird effects. I think the % important point is to explicitly force the label into vertical mode, % so it doesn't try and continue the previous paragraph). \newcommand{\sstexamplefont}[1]{\\#1\\\\} \newcommand{\sstexamples}[1]{ \setlength{\parindent}{0mm} \item[Examples:] \begin{description}[style=unboxed,font=\sstexamplefont, leftmargin=0pt,] #1 \end{description} } % Define the format of an item. \newcommand{\sstitem}{\item\mbox{}} % Format the attribute data type section. \providecommand{\sstattributetype}[1]{}%\item[Type:]#1} % an environment for references (for the SST sstdiytopic command). \newenvironment{refs}{\vspace{-4ex} % normally 3ex \begin{list}{}{\setlength{\topsep}{0mm} \setlength{\partopsep}{0mm} \setlength{\itemsep}{0mm} \setlength{\parsep}{0mm} \setlength{\leftmargin}{1.5em} \setlength{\itemindent}{-\leftmargin} \setlength{\labelsep}{0mm} \setlength{\labelwidth}{0mm}} }{\end{list}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % .. Additional SST-routine like commands. % .. SST attribute command: similar to an sstroutine, but slightly % different formatting and doesn't force a new page. See SUN/95 for % example of usage. Also doesn't appear in the table of contents. \newcommand{\sstattribute}[3]{ % Create the section. \subsubsection*{\centering \rule{\textwidth}{0.5mm}\\\Large\ignorespaces#1 \\#2\\\rule{\textwidth}{0.5mm}} % Set the first parameter as the label; need to remove spaces first. \label{\RemoveSpaces{#1}} %.. change the mark on the left hand side to include the name of the section. \markright{\textit{\RemoveSpaces{#1}}} \iftwoside \fancyhead[RE,LO]{\thepage\hspace{1cm}\rightmark} \else \lhead{\thepage\hspace{1cm}\rightmark} \fi %.. Nest all the material within a description \begin{description}[style=nextline] #3 \end{description}% } %% SSTroutinenolabel should be same as regular sstroutine, but not %% define a label (see sun209 -- this is because sun209 uses \textit %% in some of its macro titles, so thesse cannot be automatically %% changed to a label. The label must be manually created when %% using these. \newcommand{\sstroutinenolabel}[3]{ \clearpage % Create the section. \ssttitle{#1}{#2} %.. change the mark on the left hand side to include the name of the chapter. \markright{\textit{\RemoveSpaces{#1}}} \iftwoside \fancyhead[RE,LO]{\thepage\hspace{1cm}\rightmark} \else \lhead{\thepage\hspace{1cm}\rightmark} \fi %.. Nest all the material within a description \begin{description}[style=nextline] #3 \end{description} % End the page \newpage } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % .. Miscellaneous %% Change the \wedge command to something that looks better. \renewcommand{\wedge}{\mbox{\textasciicircum}} %% command to prevent sstroutines from appearing in the extra html toc %% called by \sstminitoc{Title of Toc} (does nothing in pdf) \newcommand{\sstnoextratoc}{} %% Command to restart sstroutines appearing in the extra html toc %% called by \sstminitoc{Title of Toc} (does nothing in pdf) \newcommand{\sstextratoc}{} % Command that in html typesets a listing of all % sstroutines/sstroutinenolables that occur before the next sectioning % command. Does nothing in pdf at the moment. \newcommand{\sstminitoc}[1]{} ast-8.3.0/fdsbspecframe.c0000664000175000017500000000602513004147321012202 00000000000000/* *+ * Name: * fdsbspecframe.c * Purpose: * Define a FORTRAN 77 interface to the AST DSBSpecFrame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the DSBSpecFrame class. * Routines Defined: * AST_ISADSBSPECFRAME * AST_DSBSPECFRAME * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 5-AUG-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "dsbspecframe.h" /* C interface to the DSBSpecFrame class */ F77_LOGICAL_FUNCTION(ast_isadsbspecframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISADSBSPECFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsADSBSpecFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_dsbspecframe)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); int i; char *options; astAt( "AST_DSBSPECFRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astDSBSpecFrame( "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/globals.h0000664000175000017500000001547313004147321011035 00000000000000#if !defined( GLOBALS_INCLUDED ) /* Include this file only once */ #define GLOBALS_INCLUDED 1 /* If thread-safety is required... */ #if defined( THREAD_SAFE ) && ( defined( astCLASS ) || defined( astFORTRAN77) ) /* Include files: */ /* ============== */ /* AST includes */ #include "axis.h" #include "box.h" #include "channel.h" #include "circle.h" #include "cmpframe.h" #include "cmpmap.h" #include "cmpregion.h" #include "dsbspecframe.h" #include "dssmap.h" #include "ellipse.h" #include "error.h" #include "fitschan.h" #include "fitstable.h" #include "fluxframe.h" #include "frame.h" #include "frameset.h" #include "grismmap.h" #include "interval.h" #include "intramap.h" #include "keymap.h" #include "lutmap.h" #include "mapping.h" #include "mathmap.h" #include "matrixmap.h" #include "memory.h" #include "normmap.h" #include "nullregion.h" #include "object.h" #include "pcdmap.h" #include "permmap.h" #include "plot.h" #include "plot3d.h" #include "pointlist.h" #include "pointset.h" #include "polygon.h" #include "polymap.h" #include "prism.h" #include "ratemap.h" #include "region.h" #include "selectormap.h" #include "shiftmap.h" #include "skyaxis.h" #include "skyframe.h" #include "slamap.h" #include "specfluxframe.h" #include "specframe.h" #include "specmap.h" #include "sphmap.h" #include "stc.h" #include "stccatalogentrylocation.h" #include "stcobsdatalocation.h" #include "stcresourceprofile.h" #include "stcsearchlocation.h" #include "stcschan.h" #include "switchmap.h" #include "table.h" #include "timeframe.h" #include "timemap.h" #include "tranmap.h" #include "unitmap.h" #include "unitnormmap.h" #include "wcsmap.h" #include "winmap.h" #include "xml.h" #include "xmlchan.h" #include "zoommap.h" /* System includes */ #include /* Macros */ /* ====== */ /* The name of the variable used to access thread-specific global data */ #define AST__GLOBALS ast_globals /* Defines a macro that gives access to a specific global data item. */ #define astGLOBAL(class,name) (AST__GLOBALS->class.name) /* Declares the pointer for the structure holding thread-specific values for AST global data. */ #define astDECLARE_GLOBALS AstGlobals *AST__GLOBALS; /* A macro that should be invoked in each function that refers to a global data item. The "This" parameter should be a pointer to an Object, or NULL. It ensures the thread-specific data key has been created. It also allocates and initialises memory to hold the global data. */ #define astGET_GLOBALS(This) \ \ /* If the supplied Object pointer contains a pointer to the thread-specific \ data structure, return it. */ \ if( This && ((AstObject *)This)->globals ) { \ AST__GLOBALS = ((AstObject *)This)->globals; \ \ /* Otherwise, ensure that the thread specific data key has been created. */ \ } else if( pthread_once( &starlink_ast_globals_initialised, \ astGlobalsCreateKey_ ) ) { \ AST__GLOBALS = NULL; \ fprintf( stderr, "Starlink AST package initialisation failed." ); \ \ /* If the current thread does not yet have a structure to hold \ thread-specific global data, create one now (initialising its \ contents) and associate it with the thread speciifc data key. */ \ } else if( ( AST__GLOBALS = \ pthread_getspecific( starlink_ast_globals_key ) ) == NULL ) { \ AST__GLOBALS = astGlobalsInit_(); \ if( pthread_setspecific( starlink_ast_globals_key, AST__GLOBALS ) ) { \ fprintf( stderr, "Starlink AST failed to store Thread-Specific " \ "Data pointer." ); \ } \ } /* A macro that expands to the value of a unique integer identifier for the calling thread. */ #define AST__THREAD_ID (AST__GLOBALS->thread_identifier) \ #define astMAKE_INITGLOBALS(class) \ \ void astInit##class##Globals_( Ast##class##Globals *globals ){ \ GLOBAL_inits \ } /* Type definitions */ /* ================ */ typedef struct AstGlobals { int thread_identifier; AstMemoryGlobals Memory; AstErrorGlobals Error; AstObjectGlobals Object; AstAxisGlobals Axis; AstMappingGlobals Mapping; AstFrameGlobals Frame; AstChannelGlobals Channel; AstCmpMapGlobals CmpMap; AstKeyMapGlobals KeyMap; AstFitsChanGlobals FitsChan; AstFitsTableGlobals FitsTable; AstCmpFrameGlobals CmpFrame; AstDSBSpecFrameGlobals DSBSpecFrame; AstFrameSetGlobals FrameSet; AstLutMapGlobals LutMap; AstMathMapGlobals MathMap; AstPcdMapGlobals PcdMap; AstPointSetGlobals PointSet; AstSkyAxisGlobals SkyAxis; AstSkyFrameGlobals SkyFrame; AstSlaMapGlobals SlaMap; AstSpecFrameGlobals SpecFrame; AstSphMapGlobals SphMap; AstTimeFrameGlobals TimeFrame; AstWcsMapGlobals WcsMap; AstZoomMapGlobals ZoomMap; AstFluxFrameGlobals FluxFrame; AstSpecFluxFrameGlobals SpecFluxFrame; AstGrismMapGlobals GrismMap; AstIntraMapGlobals IntraMap; AstPlotGlobals Plot; AstPlot3DGlobals Plot3D; AstRegionGlobals Region; AstBoxGlobals Box; AstXmlGlobals Xml; AstXmlChanGlobals XmlChan; AstCircleGlobals Circle; AstCmpRegionGlobals CmpRegion; AstDssMapGlobals DssMap; AstEllipseGlobals Ellipse; AstIntervalGlobals Interval; AstMatrixMapGlobals MatrixMap; AstNormMapGlobals NormMap; AstNullRegionGlobals NullRegion; AstPermMapGlobals PermMap; AstPointListGlobals PointList; AstPolyMapGlobals PolyMap; AstPolygonGlobals Polygon; AstPrismGlobals Prism; AstRateMapGlobals RateMap; AstSelectorMapGlobals SelectorMap; AstShiftMapGlobals ShiftMap; AstSpecMapGlobals SpecMap; AstStcGlobals Stc; AstStcCatalogEntryLocationGlobals StcCatalogEntryLocation; AstStcObsDataLocationGlobals StcObsDataLocation; AstSwitchMapGlobals SwitchMap; AstTableGlobals Table; AstTimeMapGlobals TimeMap; AstTranMapGlobals TranMap; AstUnitMapGlobals UnitMap; AstUnitNormMapGlobals UnitNormMap; AstWinMapGlobals WinMap; AstStcResourceProfileGlobals StcResourceProfile; AstStcSearchLocationGlobals StcSearchLocation; AstStcsChanGlobals StcsChan; } AstGlobals; /* Externally declared variables */ /* ============================= */ /* The pthreads key that is associated with the thread-specific data for each thread. Declared in global.c. */ extern pthread_key_t starlink_ast_globals_key; /* The pthreads key that is associated with the thread-specific status value for each thread. Declared in global.c. */ extern pthread_key_t starlink_ast_status_key; /* This is a flag indicating that the thread-specific data key has not yet been created. Declared in globals.c. */ extern pthread_once_t starlink_ast_globals_initialised; /* Function Prototypes: */ /* ==================== */ void astGlobalsCreateKey_( void ); AstGlobals *astGlobalsInit_( void ); /* If thread-safety is not required, define some null macros. */ #else #define astDECLARE_GLOBALS #define astGET_GLOBALS(This) #define astINIT_GLOBALS #endif #endif ast-8.3.0/object.h0000664000175000017500000020364113004147333010657 00000000000000#if !defined( OBJECT_INCLUDED ) /* Include this file only once */ #define OBJECT_INCLUDED /* *++ * Name: * object.h * Type: * C include file. * Purpose: * Define the interface to the Object class. * Invocation: * #include "object.h" * Description: * This include file defines the interface to the Object class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * The Object class is the base class from which all other classes * in the AST library are derived. This class provides all the * basic Object behaviour and Object manipulation facilities * required throughout the library. There is no Object constructor, * however, as Objects on their own are not of much use. * Inheritance: * The Object base class does not inherit from any other class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Class (string) * This is a read-only attribute containing the name of the * class to which an Object belongs. * ID (string) * An identification string which may be used to identify the * Object (e.g.) in debugging output, or when stored in an * external medium such as a data file. There is no restriction * on the string's contents. The default is an empty string. * Ident (string) * Like ID, this is an identification string which may be used * to identify the Object. Unlike ID, Ident is transferred when an * Object is copied. * UseDefs (int) * Should default values be used for unset attributes? * Nobject (integer) * This is a read-only attribute which gives the total number of * Objects currently in existence in the same class as the * Object given. It does not include Objects which belong to * derived (more specialised) classes. This value is mainly * intended for debugging, as it can be used to show whether * Objects which should have been deleted have, in fact, been * deleted. * ObjSize (int) * The in-memory size of the Object in bytes. * RefCount (integer) * This is a read-only Attribute which gives the "reference * count" (the number of active pointers) associated with an * Object. It is modified whenever pointers are created or * annulled (by astClone or astAnnul/astEnd for example) and * includes the initial pointer issued when the Object was * created. If the reference count for an Object falls to zero * as the result of annulling a pointer to it, then the Object * will be deleted. * Methods Over-Ridden: * None. * New Methods Defined: * Public: * astAnnul * Annul a pointer to an Object. * astClear * Clear attribute values for an Object. * astClone * Clone a pointer to an Object. * astCopy * Copy an Object. * astDelete * Delete an Object. * astExempt * Exempt an Object pointer from AST context handling * astExport * Export an Object pointer to an outer context. * astGet, where = C, D, F, I, L * Get an attribute value for an Object. * astImport * Import an Object pointer into the current context. * astSame * Return true if two pointers refer to the same object. * astSet * Set attribute values for an Object. * astSet, where = C, D, F, I, L * Set an attribute value for an Object. * astShow * Display a textual representation of an Object on standard output. * astTest * Test if an attribute value is set for an Object. * astTune * Get or set the value of a global AST tuning parameter. * * Protected: * astAnnulId * Annul an external ID for an Object (for use from protected code * which must handle external IDs). * astClearAttrib * Clear the value of a specified attribute for an Object. * astClearID * Clear the value of the ID attribute for an Object. * astClearIdent * Clear the value of the Ident attribute for an Object. * astCast * Return a deep copy of an object, cast into an instance of a * parent class. * astDump * Write an Object to a Channel. * astEqual * Are two Objects equivalent? * astGetAttrib * Get the value of a specified attribute for an Object. * astGetClass (deprecated synonym astClass) * Obtain the value of the Class attribute for an Object. * astGetID * Obtain the value of the ID attribute for an Object. * astGetIdent * Obtain the value of the Ident attribute for an Object. * astGetNobject * Obtain the value of the Nobject attribute for an Object. * astGetRefCount * Obtain the value of the RefCount attribute for an Object. * astSetAttrib * Set the value of a specified attribute for an Object. * astSetCopy * Declare a copy constructor for an Object. * astSetDelete * Declare a destructor for an Object. * astSetDump * Declare a dump function for an Object. * astSetVtab * Chaneg the virtual function table associated with an Object. * astSetID * Set the value of the ID attribute for an Object. * astSetIdent * Set the value of the Ident attribute for an Object. * astTestAttrib * Test if a specified attribute value is set for an Object. * astTestID * Test whether the ID attribute for an Object is set. * astTestIdent * Test whether the Ident attribute for an Object is set. * astVSet * Set values for an Object's attributes. * Other Class Functions: * Public: * astBegin * Begin a new AST context. * astEnd * End an AST context. * astIsAObject * Test class membership. * astVersion * Returns the AST library version number. * astEscapes * Remove escape sequences from returned text strings? * astP2I * Retrieve an int from a pointer. * astI2P * Pack an int into a pointer. * * Protected: * astCheckObject * Validate class membership. * astInitObject * Initialise an Object. * astInitObjectVtab * Initialise the virtual function table for the Object class. * astLoadObject * Load an Object. * astMakeId * Issue an identifier for an Object. * astMakePointer * Obtain a true C pointer from an Object identifier. * Macros: * Public: * AST__NULL * Null Object pointer value. * AST__VMAJOR * The AST library major version number. * AST__VMINOR * The AST library minor version number. * AST__RELEASE * The AST library release number. * * Protected: * astEQUAL * Compare two doubles for equality. * astMAX * Return maximum of two values. * astMIN * Return minimum of two values. * astMAKE_CHECK * Implement the astCheck_ function for a class. * astMAKE_CLEAR * Implement a method to clear an attribute value for a class. * astMAKE_GET * Implement a method to get an attribute value for a class. * astMAKE_ISA * Implement the astIsA_ function for a class. * astMAKE_SET * Implement a method to set an attribute value for a class. * astMAKE_TEST * Implement a method to test if an attribute has been set for a * class. * astMEMBER * Locate a member function. * Type Definitions: * Public: * AstObject * Object type. * * Protected: * AstObjectVtab * Object virtual function table type. * Feature Test Macros: * AST_CHECK_CLASS * If the AST_CHECK_CLASS macro is defined, then Object class * checking is enabled for all internal function invocations * within the AST library. Otherwise, this checking is * omitted. This macro should normally be defined as a compiler * option during library development and debugging, but left * undefined for software releases, so as to improve * peformance. Class checking by the AST public interface is not * affected by this macro. * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * astFORTRAN77 * If the astFORTRAN77 macro is defined, reporting of error * context information is suppressed. This is necessary when * implementing foreign language interfaces to the AST library, as * otherwise the file names and line numbers given would refer * to the interface implementation rather than the user's own * code. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2010 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 30-JAN-1996 (RFWS): * Original version. * 19-APR-1996 (RFWS): * Added macros for implementing attribute access methods. * 3-JUL-1996 (RFWS): * Added new definitions to support the external interface. * 10-SEP-1996 (RFWS): * Added loader and related facilities. * 30-MAY-1997 (RFWS): * Add the ID attribute. * 14-JUL-1997 (RFWS): * Add astExempt function. * 20-JAN-1998 (RFWS): * Make the astClear and astVSet methods virtual. * 15-SEP-1999 (RFWS): * Made the astAnnulId function accessible to protected code. * 3-APR-2001 (DSB): * Added Ident attribute. * 8-JAN-2003 (DSB): * Added protected astInitObjectVtab method. * 30-APR-2003 (DSB): * Added macros AST__VMAJOR, AST__VMINOR and AST__RELEASE. * Added astVersion function. * 7-FEB-2004 (DSB): * Added astEscapes function. * 11-MAR-2005 (DSB): * Added UseDefs attribute. * 7-FEB-2006 (DSB): * Added astTune function. * 14-FEB-2006 (DSB): * Added ObjSize attribute. * 23-FEB-2006 (DSB): * Moved AST__TUNULL from this file to memory.h. * 10-MAY-2006 (DSB): * Added astEQUAL, astMAX and astMIN. * 26-MAY-2006 (DSB): * Make all system includes unconditional, so that makeh is not * confused when creating ast.h. * 22-JUN-2007 (DSB): * - Make astVSet return a pointer to dynamic memory holding the * expanded setting string. * - Add ast astSetVtab and astCast. * 22-APR-2008 (DSB): * Added astSame. * 7-APR-2010 (DSB): * Added astHasAttribute. *-- */ /* Include files. */ /* ============== */ /* Configuration results. */ /* ---------------------- */ #if HAVE_CONFIG_H #include #endif /* Interface definitions. */ /* ---------------------- */ #include "error.h" /* Error reporting facilities */ #include "version.h" /* Version number macros */ /* C header files. */ /* --------------- */ #include #include #include #include #if defined(THREAD_SAFE) #include #endif /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Set to "1" (yes) or "0" (no) to indicate if AST was build with threads support. */ #define AST__THREADSAFE 1 #if defined(astCLASS ) #define AST__GETATTRIB_BUFF_LEN 50 /* Length of string returned by GetAttrib. */ #define AST__ASTGETC_MAX_STRINGS 50 /* Number of string values to buffer within astGetC */ /* Values supplied to astManageLock */ #define AST__LOCK 1 /* Lock the object */ #define AST__UNLOCK 2 /* Unlock the object */ #define AST__CHECKLOCK 3 /* Check if the object is locked */ /* Values returned by astThread */ #define AST__UNLOCKED 1 /* Object is unlocked */ #define AST__RUNNING 2 /* Object is locked by the running thread */ #define AST__OTHER 3 /* Object is locked by another thread */ #endif /* Value that indicates that two classes are not in direct line from each other. */ #if defined(astCLASS ) #define AST__COUSIN -1000000 #endif /* *+ * Name: * astINVOKE * Type: * Protected macro. * Purpose: * Invoke an AST function. * Synopsis: * #include "object.h" * astINVOKE(rettype,function) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an invocation of an AST function, together * with any additional actions required to support it. The actual * expansion depends on whether the macro is expanded in internal * code (astCLASS defined) or external code (astCLASS undefined) * and it therefore hides the differences between these two * interfaces. * Parameters: * rettype * A character to indicate the type of result returned by the function: * * V * The function returns a value (including void or a pointer * value, but excluding an Object pointer). astINVOKE will * return the value unchanged. * O * The function returns an Object pointer. astINVOKE will * convert it to an Object identifier if necessary. * F * The function returns a function pointer. astINVOKE will * return it unchanged. This is typically used when the * function has a variable argument list. In this case the * function name is passed to astINVOKE without its argument * list and a pointer to the function is returned which can * then be supplied with an argument list. This avoids the * need to define a macro with a variable number of arguments * (which isn't allowed). * function * A normal invocation of the function returning the required * result. In the case of a variable argument list, the * argument list should be omitted so that the function is not * invoked but a function pointer is returned that may then be * used to invoke it. * Examples: * #define astGetNobject(this) \ * astINVOKE(V,astGetNobject_(astCheckObject(this))) * Defines a macro to invoke the astGetNobject_ function which * returns an int. * #define astClone(this) \ * astINVOKE(O,astClone_(astCheckObject(this))) * Defines a macro to invoke the astClone_ function which * returns an Object pointer. * #define astSet astINVOKE(F,astSet_) * Defines a macro to invoke the astSet_ function which has a * variable argument list and returns void. The macro result is * a pointer to the astSet_ function. This function must perform * its own argument validation, as (e.g) astCheckObject cannot * be invoked on its arguments via a macro. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define astINVOKE, which records the current file and line number (in case of error) using astAt, and then invokes the function supplied as an argument of the astRetV_, astRetO_ or astRetF_ macro. Suppress reporting of the file and line number from internal code and from foreign language interfaces by not using astAt in these cases. */ #if defined(astCLASS) || defined(astFORTRAN77) #define astINVOKE(rettype,function) astRet##rettype##_(function) #else #define astINVOKE(rettype,function) \ astERROR_INVOKE(astRet##rettype##_(function)) #endif /* astRetF_ and astRetV_ currently do nothing. */ #define astRetF_(x) (x) #define astRetV_(x) (x) /* However, astRetO_ converts a pointer to an ID if necessary. */ #if defined(astCLASS) #define astRetO_(x) ((void *)(x)) #else #define astRetO_(x) ((void *)astMakeId_((AstObject *)(x),STATUS_PTR)) #endif /* *+ * Name: * astINVOKE_CHECK * astINVOKE_ISA * Type: * Protected macros. * Purpose: * Invoke the astCheck_ and astIsA_ functions. * Synopsis: * #include "object.h" * astINVOKE_CHECK(class,this,force) * astINVOKE_ISA(class,this) * Class Membership: * Defined by the Object class. * Description: * These macros expand to invocations of the standard * astCheck_ and astIsA_ functions for a class. * Parameters: * class * The name (not the type) of the class for which the function * is to be invoked. * this * The "this" argument (the Object pointer) to be passed to the * function. * force * Type checking takes time, and so can be disabled within the * protected context in order to save time. Setting "force" to * zero causes the astINVOKE_CHECK macro to skip the class check * in a protected context (it assumes that AST "knows what it is * doing"). Setting "force" to a non-zero value forces the class * check even in a protected context. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* For the public interface (and also internally if AST_CHECK_CLASS is defined), define astINVOKE_CHECK to invoke the astCheck function. */ #if !defined(astCLASS) || defined(AST_CHECK_CLASS) #define astINVOKE_CHECK(class,this,force) \ astCheck##class##_((Ast##class *)astEnsurePointer_(this),astGetStatusPtr) /* For the internal interface, astINVOKE_CHECK omits the astCheck function (unless AST_CHECK_CLASS is defined). */ #else #define astINVOKE_CHECK(class,this,force) ( (force) ? \ ( astCheck##class##_((Ast##class *)astEnsurePointer_(this),astGetStatusPtr) ) : \ ( (Ast##class *) astEnsurePointer_(this) ) ) #endif /* Define astINVOKE_ISA to invoke the astIsA function. */ #if defined(astCLASS) /* Protected */ #define astINVOKE_ISA(class,this) \ astIsA##class##_((const Ast##class *)(this),status) #else /* Public */ #define astINVOKE_ISA(class,this) \ astINVOKE(V,astIsA##class##_((const Ast##class *)astEnsurePointer_(this),astGetStatusPtr)) #endif /* The astEnsurePointer_ macro ensures a true C pointer, converting from an ID if necessary. */ #if defined(astCLASS) /* Protected */ #define astEnsurePointer_(x) ((void *)(x)) #else /* Public */ #define astEnsurePointer_(x) ((void *)astCheckLock_(astMakePointer_((AstObject *)(x),STATUS_PTR),STATUS_PTR)) #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CHECK * Type: * Protected macro. * Purpose: * Implement the astCheck_ function for a class. * Synopsis: * #include "object.h" * astMAKE_CHECK(class) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of the public astCheck_ * function (q.v.) which validates membership of a specified class. * Parameters: * class * The name (not the type) of the class whose membership is to be * validated. * Notes: * - This macro is provided so that class definitions can easiy * implement the astCheck_ function, which is essentially the same * for each class apart for a change of name. * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ #ifndef MEM_DEBUG /* Define the macro. */ #define astMAKE_CHECK(class) \ \ /* Declare the function (see the object.c file for a prologue). */ \ Ast##class *astCheck##class##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return this; \ \ /* Check if the object is a class member. */ \ if ( !astIsA##class( this ) ) { \ \ /* If not, but the pointer was valid (which means it identifies an Object \ of some sort), then report more information about why this Object is \ unsuitable. */ \ if ( astOK ) { \ astError( AST__OBJIN, "Pointer to " #class " required, but pointer " \ "to %s given.", status, astGetClass( this ) ); \ } \ } \ \ /* Return the pointer value supplied. */ \ return this; \ } /* Define the macro with memory debugging facilities. */ #else #define astMAKE_CHECK(class) \ \ /* Declare the function (see the object.c file for a prologue). */ \ Ast##class *astCheck##class##_( Ast##class *this, int *status ) { \ \ char buf[100]; \ \ /* Check the inherited error status. */ \ if ( !astOK ) return this; \ \ /* Check if the object is a class member. */ \ if ( !astIsA##class( this ) ) { \ \ /* If not, but the pointer was valid (which means it identifies an Object \ of some sort), then report more information about why this Object is \ unsuitable. */ \ if ( astOK ) { \ astError( AST__OBJIN, "Pointer to " #class " required, but pointer " \ "to %s given.", status, astGetClass( this ) ); \ }\ \ } else { \ \ /* Call the astMemoryUse function to report it if the memory block is \ being watched. */ \ sprintf( buf, "checked (refcnt: %d)", astGetRefCount_( (AstObject *) this, status ) ); \ astMemoryUse( this, buf ); \ } \ \ /* Return the pointer value supplied. */ \ return this; \ } #endif #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CLEAR * Purpose: * Implement a method to clear an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_CLEAR(class,attribute,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( Ast *this ) * * and an external interface function of the form: * * void astClear_( Ast *this ) * * which implement a method for clearing a specified attribute value for * a class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabel"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * Examples: * astMAKE_CLEAR(MyStuff,Flag,flag,-1) * Implements the astClearFlag method for the MyStuff class which * operates by setting the "flag" structure component to -1 to indicate * that it has no value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_CLEAR(class,attribute,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Assign the "clear" value. */ \ this->component = (assign); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Clear##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_CLEAR1 * Purpose: * Implement a method to clear an attribute value for a class, reporting * an error if the object has more than one reference. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_CLEAR1(class,attribute,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Clear( Ast *this ) * * and an external interface function of the form: * * void astClear_( Ast *this ) * * which implement a method for clearing a specified attribute value for * a class. An error is reported if the object has a reference count that * is greater than one. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be cleared, as it appears in the function * name (e.g. Label in "astClearLabel"). * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to assign to the component * to clear its value. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_CLEAR1(class,attribute,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Clear##attribute( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astClear(%s): The " #attribute "attribute of " \ "the supplied %s cannot be cleared because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, assign the "clear" value in the structure component. */ \ } else { \ this->component = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astClear##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Clear##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_GET * Purpose: * Implement a method to get an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_GET(class,attribute,type,bad_value,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static Get( Ast *this ) * * and an external interface function of the form: * * astGet_( Ast *this ) * * which implement a method for getting a specified attribute value for a * class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute whose value is to be obtained, as it * appears in the function name (e.g. Label in "astGetLabel"). * type * The C type of the attribute. * bad_value * A constant value to return if the inherited error status is set, or if * the function fails. * assign * An expression that evaluates to the value to be returned. * Examples: * astMAKE_GET(MyStuff,Flag,int,0,( this->flag == 1 )) * Implements the astGetFlag method for the MyStuff class which operates * by examining the integer "flag" structure component and comparing it * with the value 1 to see if it is set. A value of 0 is returned if the * method fails to complete successfully. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_GET(class,attribute,type,bad_value,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static type Get##attribute( Ast##class *this, int *status ) { \ type result; /* Result to be returned */ \ \ /* Check the inherited error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Assign the result value. */ \ result = (assign); \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = (bad_value); \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ type astGet##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return (bad_value); \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,class,Get##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_ISA * Type: * Protected macro. * Purpose: * Implement the astIsA_ function for a class. * Synopsis: * #include "object.h" * astMAKE_ISA(class,parent) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of the public * astIsA_ function (q.v.) which checks membership of a * specified class. * Parameters: * class * The name (not the type) of the class whose membership is to be * tested. * parent * The name of the parent class. * Notes: * - This macro is provided so that class definitions can easiy * implement the astIsA_ function, which is essentially the * same for each class apart for a change of name. * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_ISA(class,parent) \ \ /* Declare the function (see the object.c file for a prologue). */ \ int astIsA##class##_( const Ast##class *this, int *status ) { \ \ /* Local Variables: */ \ int isa = 0; /* Is object a member? */ \ \ /* To test if the object is correctly constructed, we first test if it is a \ member of the parent class. This improves the security of the test by \ checking the object structure from the base Object class downwards \ (without this, the "magic numbers" that identify classes might be \ encountered by accident or we might address parts of the Object which \ don't exist). */ \ if ( astIsA##parent( this ) ) { \ \ /* Obtain the Object's size and check it is adequate for an object of the \ proposed type (this avoids any attempt to access derived class data that \ doesn't exist and therefore lies outside the memory allocated for the \ object). */ \ if ( ( (AstObject *) this )->size >= sizeof( Ast##class ) ) { \ \ /* If OK, see whether the check component in the object's virtual function \ table matches the expected "magic" value. */ \ isa = ( *astMEMBER(this,class,id.check) == &class_check ); \ } \ } \ \ /* Return the result. */ \ return isa; \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_SET * Purpose: * Implement a method to set an attribute value for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_SET(class,attribute,type,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( Ast *this, value ) * * and an external interface function of the form: * * void astSet_( Ast *this, value ) * * which implement a method for setting a specified attribute value for a * class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. * Examples: * astMAKE_SET(MyStuff,Flag,int,flag,( value != 0 )) * Implements the astSetFlag method for the MyStuff class which operates * by setting the "flag" structure component to 0 or 1 depending on * whether the "value" parameter is non-zero or not. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_SET(class,attribute,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Store the new value in the structure component. */ \ this->component = (assign); \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Set##attribute))( this, value, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_SET1 * Purpose: * Implement a method to set an attribute value for a class, reporting * an error if the object has more than one reference. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_SET1(class,attribute,type,component,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static void Set( Ast *this, value ) * * and an external interface function of the form: * * void astSet_( Ast *this, value ) * * which implement a method for setting a specified attribute value for a * class. An error is reported if the object has a reference count that * is greater than one. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be set, as it appears in the function * name (e.g. Label in "astSetLabel"). * type * The C type of the attribute. * component * The name of the class structure component that holds the attribute * value. * assign * An expression that evaluates to the value to be assigned to the * component. *- */ /* Define the macro. */ #define astMAKE_SET1(class,attribute,type,component,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static void Set##attribute( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Report an error if the object has been cloned (i.e. has a reference \ count that is greater than one). */ \ if( astGetRefCount( this ) > 1 ) { \ astError( AST__IMMUT, "astSet(%s): The " #attribute "attribute of " \ "the supplied %s cannot be changed because the %s has " \ "been cloned (programming error).", status, \ astGetClass(this), astGetClass(this), astGetClass(this) ); \ \ /* Otherwise, store the new value in the structure component. */ \ } else { \ this->component = (assign); \ } \ } \ \ /* External interface. */ \ /* ------------------- */ \ void astSet##attribute##_( Ast##class *this, type value, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return; \ \ /* Invoke the required method via the virtual function table. */ \ (**astMEMBER(this,class,Set##attribute))( this, value, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMAKE_TEST * Purpose: * Implement a method to test if an attribute has been set for a class. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMAKE_TEST(class,attribute,assign) * Class Membership: * Defined by the Object class. * Description: * This macro expands to an implementation of a private member function of * the form: * * static int Test( Ast *this ) * * and an external interface function of the form: * * int astTest_( Ast *this ) * * which implement a method for testing if a specified attribute has been * set for a class. * Parameters: * class * The name (not the type) of the class to which the attribute belongs. * attribute * The name of the attribute to be tested, as it appears in the function * name (e.g. Label in "astTestLabel"). * assign * An expression that evaluates to 0 or 1, to be used as the returned * value. * Examples: * astMAKE_TEST(MyStuff,Flag,( this->flag != -1 )) * Implements the astTestFlag method for the MyStuff class which operates * by testing the "flag" structure component to see if it is set to a * value other than -1. * Notes: * - To avoid problems with some compilers, you should not leave any white * space around the macro arguments. *- */ /* Define the macro. */ #define astMAKE_TEST(class,attribute,assign) \ \ /* Private member function. */ \ /* ------------------------ */ \ static int Test##attribute( Ast##class *this, int *status ) { \ int result; /* Value to return */ \ \ /* Check the inherited error status. */ \ if ( !astOK ) return 0; \ \ /* Assign the result value. */ \ result = (assign); \ \ /* Check for errors and clear the result if necessary. */ \ if ( !astOK ) result = 0; \ \ /* Return the result. */ \ return result; \ } \ /* External interface. */ \ /* ------------------- */ \ int astTest##attribute##_( Ast##class *this, int *status ) { \ \ /* Check the inherited error status. */ \ if ( !astOK ) return 0; \ \ /* Invoke the required method via the virtual function table. */ \ return (**astMEMBER(this,class,Test##attribute))( this, status ); \ } #endif #if defined(astCLASS) /* Protected */ /* *+ * Name: * astMEMBER * Purpose: * Locate a member function. * Type: * Protected macro. * Synopsis: * #include "object.h" * astMEMBER(this,class,method) * Class Membership: * Defined by the Object class. * Description: * This macro evaluates to the address where the pointer to a * specified Object member function is stored. Typically, this will * be used to obtain a pointer to the member function so that it * can be invoked. It may also be used to assign a new function * pointer so that a derived class can re-define a virtual function * and hence over-ride an inherited method. * Parameters: * this * Pointer to an Object belonging to the class for which the * virtual function is required. This must either be the class * that originally defined the method, or one derived from it. * class * Name of the class that originally defined the method. This * may differ from (i.e. be an ancestor of) the class to which * "this" belongs. * method * Name of the method whose member function is to be located. * Returned Value: * The address where the member function pointer is stored (the * type of the result is determined by the type of the member * function itself). * Examples: * astMEMBER(this,Gnome,astFish) * Returns the address where the pointer to the function that * implements the astFish method for the "this" object is * stored. The Gnome class should be where the astFish method * was first defined (i.e. from where it was inherited by * "this"). * (**astMEMBER(this,Gnome,astFish))( this, arg1, arg2 ); * Invokes the virtual function that implements the astFish * method for object "this" and passes it additional arguments * "arg2" and "arg2". Again, Gnome should be the class that * originally defined the astFish method. * *astMEMBER(this,Gnome,astFish) = myFish; * Stores a pointer to the myFish function so that it replaces * the virtual function that previously implemented the astFish * method for the "this" object. Note that all objects in the * same class as "this" are affected, but objects in class * "class" are not affected (unless it happens to be the class * to which "this" belongs). * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* A subsiduary macro that returns a pointer to the vtab of an object, cast to an AstObjectVtab. */ #define astVTAB(this) (((AstObject*)(this))->vtab) /* Define the macro. This functions by (a) casting the Object pointer to type (AstObject *) and locating the Object's virtual function table (b) casting the table pointer to the correct type (AstClassVtab *) for the class in which the method pointer resides, (c) locating the component holding the member function pointer, and (d) taking its address. */ #define astMEMBER(this,class,method) \ (&((Ast##class##Vtab*)astVTAB(this))->method) #endif /* *+ * Name: * astPROTO_CHECK * astPROTO_ISA * Type: * Protected macros. * Purpose: * Prototype the astCheck_ and astIsA_ functions. * Synopsis: * #include "object.h" * astPROTO_CHECK(class) * astPROTO_ISA(class) * Class Membership: * Defined by the Object class. * Description: * These macros expands to function prototypes for the * astCheck_ and astIsA_ functions (q.v.) which * validate and test for membership of a specified class. * Parameters: * class * The name (not the type) of the class whose membership is to * be validated. * Notes: * - To avoid problems with some compilers, you should not leave * any white space around the macro arguments. *- */ /* Define the macros. */ #define astPROTO_CHECK(class) Ast##class *astCheck##class##_( Ast##class *, int * ); #define astPROTO_ISA(class) int astIsA##class##_( const Ast##class *, int * ); /* Macros which return the maximum and minimum of two values. */ #define astMAX(aa,bb) ((aa)>(bb)?(aa):(bb)) #define astMIN(aa,bb) ((aa)<(bb)?(aa):(bb)) /* Check for equality of floating point values. We cannot compare bad values directly because of the danger of floating point exceptions, so bad values are dealt with explicitly. */ #define astEQUALS(aa,bb,tol) (((aa)==AST__BAD)?(((bb)==AST__BAD)?1:0):(((bb)==AST__BAD)?0:(fabs((aa)-(bb))<=(tol)*astMAX((fabs(aa)+fabs(bb))*DBL_EPSILON,DBL_MIN)))) #define astEQUAL(aa,bb) astEQUALS(aa,bb,1.0E5) /* AST__NULL. */ /* ---------- */ /* Define the AST__NULL macro, which evaluates to a null Object pointer. */ #define AST__NULL (astI2P(0)) #if defined(astCLASS) /* Protected */ /* Test the validy of an attribute value */ /* ------------------------------------- */ /* If the set attribute value is invalid, clear it. These macros should be used in a context in which error reporting has been deferred by calling astReporting( 0 ). */ #define astCLEAN_ATTRIB(attr) \ if( astTest##attr(this) ) { \ astSet##attr( this, astGet##attr( this ) ); \ if( !astOK ) { \ astClearStatus; \ astClear##attr( this ); \ } \ } #define astCLEAN_INDEXED_ATTRIB(attr,index) \ if( astTest##attr(this,index) ) { \ astSet##attr( this, index, astGet##attr( this, index ) ); \ if( !astOK ) { \ astClearStatus; \ astClear##attr( this, index ); \ } \ } #endif #if defined(astCLASS) /* Protected */ #define astSetVtabClassIdentifier(vtab,id_ptr) \ ((AstObjectVtab *)(vtab))->top_id = (id_ptr) #endif /* Type Definitions. */ /* ================= */ /* Object structure. */ /* ----------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstObject { /* Attributes specific to objects in this class. */ unsigned long check; /* Check value to identify Objects */ size_t size; /* Amount of memory used by Object */ struct AstObjectVtab *vtab; /* Pointer to virtual function table */ char dynamic; /* Memory allocated dynamically? */ int ref_count; /* Number of active pointers to the Object */ char *id; /* Pointer to ID string */ char *ident; /* Pointer to Ident string */ char usedefs; /* Use default attribute values? */ int iref; /* Object index (unique within class) */ void *proxy; /* A pointer to an external object that acts as a foreign language proxy for the AST object */ #if defined(THREAD_SAFE) int locker; /* Thread that has locked this Object */ pthread_mutex_t mutex1; /* Guards access to all elements of the Object except for the "locker" and "ref_count" components */ pthread_mutex_t mutex2; /* Guards access to the "locker" and "ref_count" components */ struct AstGlobals *globals; /* Pointer to thread-specific global data */ #endif } AstObject; /* Class identifier structure */ typedef struct AstClassIdentifier { int *check; struct AstClassIdentifier *parent; } AstClassIdentifier; /* Virtual function table. */ /* ----------------------- */ /* The virtual function table makes a forward reference to the AstChannel structure which is not defined until "channel.h" is included (below). Hence make a preliminary definition available now. */ struct AstChannel; /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstObjectVtab { /* A unique identifier for this class. */ AstClassIdentifier id; /* Pointer to the structure that identifies the top-level class described by the whole vtab (of which the AstObjectVtab is just the first, lowest-level, component). */ AstClassIdentifier *top_id; /* Pointer to a dynamically allocated string holding the default attribute values to use when creating new objects. These are read from environment variables of the form "_OPTIONS". */ const char *defaults; /* Properties specific to this class. */ void ( *CleanAttribs )( AstObject *, int * ); AstObject *( *Cast )( AstObject *, AstObject *, int * ); const char *( *GetID )( AstObject *, int * ); const char *( *GetIdent )( AstObject *, int * ); const char *(* GetAttrib)( AstObject *, const char *, int * ); int (* TestAttrib)( AstObject *, const char *, int * ); int (* TestID)( AstObject *, int * ); int (* Same)( AstObject *, AstObject *, int * ); int (* HasAttribute)( AstObject *, const char *, int * ); int (* TestIdent)( AstObject *, int * ); void (* Clear)( AstObject *, const char *, int * ); void (* ClearAttrib)( AstObject *, const char *, int * ); void (* ClearID)( AstObject *, int * ); void (* ClearIdent)( AstObject *, int * ); void (* Dump)( AstObject *, struct AstChannel *, int * ); int (* Equal)( AstObject *, AstObject *, int * ); void (* SetAttrib)( AstObject *, const char *, int * ); void (* SetID)( AstObject *, const char *, int * ); void (* SetIdent)( AstObject *, const char *, int * ); void (* Show)( AstObject *, int * ); void (* VSet)( AstObject *, const char *, char **, va_list, int * ); void (* EnvSet)( AstObject *, int * ); void *(* GetProxy)( AstObject *, int * ); void (* SetProxy)( AstObject *, void *, int * ); int (* GetObjSize)( AstObject *, int * ); int (* TestUseDefs)( AstObject *, int * ); int (* GetUseDefs)( AstObject *, int * ); void (* SetUseDefs)( AstObject *, int, int * ); void (* ClearUseDefs)( AstObject *, int * ); const char *class; /* Pointer to class name string */ void (** delete)( AstObject *, int * ); /* Pointer to array of destructors */ void (** copy)( const AstObject *, AstObject *, int * ); /* Copy constructors */ void (** dump)( AstObject *, struct AstChannel *, int * ); /* Dump functions */ const char **dump_class; /* Dump function class string pointers */ const char **dump_comment; /* Dump function comment string pointers */ int ndelete; /* Number of destructors */ int ncopy; /* Number of copy constructors */ int ndump; /* Number of dump functions */ int nobject; /* Number of active objects in the class */ int nfree; /* No. of entries in "free_list" */ AstObject **free_list; /* List of pointers for freed Objects */ #if defined(THREAD_SAFE) int (* ManageLock)( AstObject *, int, int, AstObject **, int * ); #endif } AstObjectVtab; #endif #if defined(THREAD_SAFE) && defined(astCLASS) /* Define a structure holding all data items that are global within the object.c file. */ typedef struct AstObjectGlobals { AstObjectVtab Class_Vtab; int Class_Init; int Retain_Esc; int Context_Level; int *Active_Handles; char GetAttrib_Buff[ AST__GETATTRIB_BUFF_LEN + 1 ]; char *AstGetC_Strings[ AST__ASTGETC_MAX_STRINGS ]; int AstGetC_Istr; int AstGetC_Init; int Nvtab; AstObjectVtab **Known_Vtabs; } AstObjectGlobals; #endif /* More include files. */ /* =================== */ /* The interface to the Channel class must be included here (after the type definitions for the Object class) because "channel.h" itself includes this file ("object.h"), although "object.h" refers to the AstChannel structure above. This seems a little strange at first, but is simply analogous to making a forward reference to a structure type when recursively defining a normal C structure (except that here the definitions happen to be in separate include files). */ #include "channel.h" /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Object) /* Validate class membership */ astPROTO_ISA(Object) /* Test class membership */ /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstObject *astInitObject_( void *, size_t, int, AstObjectVtab *, const char *, int * ); /* Vtab Initialiser. */ void astInitObjectVtab_( AstObjectVtab *, const char *, int * ); /* Loader. */ AstObject *astLoadObject_( void *, size_t, AstObjectVtab *, const char *, AstChannel *channel, int * ); #if defined(THREAD_SAFE) void astInitObjectGlobals_( AstObjectGlobals * ); #endif #endif /* Prototypes for other class functions. */ /* ------------------------------------- */ #if !defined(astCLASS) /* Public */ void astBegin_( void ); void astEnd_( int * ); #endif AstObject *astI2P_( int, int * ); AstObject *astMakeId_( AstObject *, int * ); AstObject *astMakePointer_( AstObject *, int * ); AstObject *astMakePointer_NoLockCheck_( AstObject *, int * ); int astP2I_( AstObject *, int * ); int astVersion_( int * ); int astEscapes_( int, int * ); int astTune_( const char *, int, int * ); void astTuneC_( const char *, const char *, char *, int, int * ); /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ AstObject *astAnnul_( AstObject *, int * ); AstObject *astDelete_( AstObject *, int * ); void astSet_( void *, const char *, int *, ... ); #else /* Public */ AstObject *astDeleteId_( AstObject *, int * ); int astThreadId_( AstObject *, int, int * ); void astExportId_( AstObject *, int * ); void astImportId_( AstObject *, int * ); void astSetId_( void *, const char *, ... )__attribute__((format(printf,2,3))); #endif AstObject *astAnnulId_( AstObject *, int * ); AstObject *astCheckLock_( AstObject *, int * ); AstObject *astClone_( AstObject *, int * ); AstObject *astCopy_( const AstObject *, int * ); AstObject *astFromString_( const char *, int * ); char *astToString_( AstObject *, int * ); const char *astGetC_( AstObject *, const char *, int * ); double astGetD_( AstObject *, const char *, int * ); float astGetF_( AstObject *, const char *, int * ); int astEqual_( AstObject *, AstObject *, int * ); int astGetI_( AstObject *, const char *, int * ); int astHasAttribute_( AstObject *, const char *, int * ); int astSame_( AstObject *, AstObject *, int * ); int astTest_( AstObject *, const char *, int * ); long astGetL_( AstObject *, const char *, int * ); void *astGetProxy_( AstObject *, int * ); void astClear_( AstObject *, const char *, int * ); void astExemptId_( AstObject *, int * ); void astLockId_( AstObject *, int, int * ); void astSetC_( AstObject *, const char *, const char *, int * ); void astSetD_( AstObject *, const char *, double, int * ); void astSetF_( AstObject *, const char *, float, int * ); void astSetI_( AstObject *, const char *, int, int * ); void astSetL_( AstObject *, const char *, long, int * ); void astSetProxy_( AstObject *, void *, int * ); void astShow_( AstObject *, int * ); void astUnlockId_( AstObject *, int, int * ); #if defined(astCLASS) /* Protected */ void astCleanAttribs_( AstObject *, int * ); AstObject *astCast_( AstObject *, AstObject *, int * ); AstObject *astCastCopy_( AstObject *, AstObject *, int * ); #if defined(THREAD_SAFE) int astManageLock_( AstObject *, int, int, AstObject **, int * ); #endif int astGetObjSize_( AstObject *, int * ); int astTestUseDefs_( AstObject *, int * ); int astGetUseDefs_( AstObject *, int * ); void astSetUseDefs_( AstObject *, int, int * ); void astClearUseDefs_( AstObject *, int * ); const char *astGetAttrib_( AstObject *, const char *, int * ); const char *astGetClass_( const AstObject *, int * ); const char *astGetID_( AstObject *, int * ); const char *astGetIdent_( AstObject *, int * ); int astClassCompare_( AstObjectVtab *, AstObjectVtab *, int * ); int astGetNobject_( const AstObject *, int * ); int astGetRefCount_( AstObject *, int * ); int astTestAttrib_( AstObject *, const char *, int * ); int astTestID_( AstObject *, int * ); int astTestIdent_( AstObject *, int * ); void astClearAttrib_( AstObject *, const char *, int * ); void astClearID_( AstObject *, int * ); void astClearIdent_( AstObject *, int * ); void astDump_( AstObject *, AstChannel *, int * ); void astSetAttrib_( AstObject *, const char *, int * ); void astSetCopy_( AstObjectVtab *, void (*)( const AstObject *, AstObject *, int * ), int * ); void astSetDelete_( AstObjectVtab *, void (*)( AstObject *, int * ), int * ); void astSetDump_( AstObjectVtab *, void (*)( AstObject *, AstChannel *, int * ), const char *, const char *, int * ); void astSetVtab_( AstObject *, AstObjectVtab *, int * ); void astSetID_( AstObject *, const char *, int * ); void astSetIdent_( AstObject *, const char *, int * ); void astEnvSet_( AstObject *, int * ); void astVSet_( AstObject *, const char *, char **, va_list, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Check class membership. */ #define astCheckObject(this) astINVOKE_CHECK(Object,this,0) #define astVerifyObject(this) astINVOKE_CHECK(Object,this,1) /* Test class membership. */ #define astIsAObject(this) astINVOKE_ISA(Object,this) /* NB. There is no constructor function for this class. */ #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitObject(mem,size,init,vtab,name) \ astINVOKE(O,astInitObject_(mem,size,init,vtab,name,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitObjectVtab(vtab,name) astINVOKE(V,astInitObjectVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadObject(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadObject_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to other class functions. */ /* ------------------------------------ */ #if !defined(astCLASS) /* Public */ #define astBegin astBegin_() #define astEnd astINVOKE(V,astEnd_(STATUS_PTR)) #else /* Protected */ #define astMakePointer_NoLockCheck(id) ((void *)astMakePointer_NoLockCheck_((AstObject *)(id),STATUS_PTR)) #endif #define astVersion astVersion_(STATUS_PTR) #define astEscapes(int) astEscapes_(int,STATUS_PTR) #define astTune(name,val) astTune_(name,val,STATUS_PTR) #define astTuneC(name,value,buff,bufflen) astTuneC_(name,value,buff,bufflen,STATUS_PTR) #define astI2P(integer) ((void *)astI2P_(integer,STATUS_PTR)) #define astMakeId(pointer) ((void *)astMakeId_((AstObject *)(pointer),STATUS_PTR)) #define astP2I(pointer) astP2I_((AstObject *)(pointer),STATUS_PTR) #define astMakePointer(id) ((void *)astCheckLock_(astMakePointer_((AstObject *)(id),STATUS_PTR),STATUS_PTR)) #define astToString(this) astINVOKE(V,astToString_(astCheckObject(this),STATUS_PTR)) #define astFromString(string) astINVOKE(O,astFromString_(string,STATUS_PTR)) /* Interfaces to member functions. */ /* ------------------------------- */ /* Here we make use of astCheckObject (et al.) to validate Object pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. In the case of an external caller, it also performs the required conversion from an Object identifier to a true C pointer. */ /* These functions require special treatment for external use because they handle Object identifiers and their resources explicitly, and must therefore be passed identifier values without conversion to C pointers. */ #if defined(astCLASS) || defined(astFORTRAN77) /* Protected or Fotran interface */ #define astAnnulId(this) astINVOKE(O,astAnnulId_((AstObject *)(this),STATUS_PTR)) #endif #if defined(astCLASS) /* Protected only */ #define astAnnul(this) astINVOKE(O,astAnnul_(astCheckObject(this),STATUS_PTR)) #define astDelete(this) astINVOKE(O,astDelete_(astCheckObject(this),STATUS_PTR)) #define astSet astINVOKE(F,astSet_) #else /* Public only */ #define astAnnul(this) astINVOKE(O,astAnnulId_((AstObject *)(this),STATUS_PTR)) #define astDelete(this) astINVOKE(O,astDeleteId_((AstObject *)(this),STATUS_PTR)) #define astExport(this) astINVOKE(V,astExportId_((AstObject *)(this),STATUS_PTR)) #define astImport(this) astINVOKE(V,astImportId_((AstObject *)(this),STATUS_PTR)) #define astSet astINVOKE(F,astSetId_) #define astThread(this,ptr) astINVOKE(V,astThreadId_((AstObject *)(this),ptr,STATUS_PTR)) #endif /* Both.... */ #define astLock(this,wait) astINVOKE(V,astLockId_((AstObject *)(this),wait,STATUS_PTR)) #define astUnlock(this,report) astINVOKE(V,astUnlockId_((AstObject *)(this),report,STATUS_PTR)) #define astEqual(this,that) astINVOKE(V,(((AstObject*)this==(AstObject*)that)||astEqual_(astCheckObject(this),astCheckObject(that),STATUS_PTR))) #define astExempt(this) astINVOKE(V,astExemptId_((AstObject *)(this),STATUS_PTR)) #define astClear(this,attrib) astINVOKE(V,astClear_(astCheckObject(this),attrib,STATUS_PTR)) #define astClone(this) astINVOKE(O,astClone_(astCheckObject(this),STATUS_PTR)) #define astCopy(this) astINVOKE(O,astCopy_(astCheckObject(this),STATUS_PTR)) #define astGetC(this,attrib) astINVOKE(V,astGetC_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetD(this,attrib) astINVOKE(V,astGetD_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetF(this,attrib) astINVOKE(V,astGetF_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetI(this,attrib) \ astINVOKE(V,astGetI_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetL(this,attrib) \ astINVOKE(V,astGetL_(astCheckObject(this),attrib,STATUS_PTR)) #define astSetC(this,attrib,value) \ astINVOKE(V,astSetC_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetD(this,attrib,value) \ astINVOKE(V,astSetD_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetF(this,attrib,value) \ astINVOKE(V,astSetF_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetI(this,attrib,value) \ astINVOKE(V,astSetI_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astSetL(this,attrib,value) \ astINVOKE(V,astSetL_(astCheckObject(this),attrib,value,STATUS_PTR)) #define astShow(this) \ astINVOKE(V,astShow_(astCheckObject(this),STATUS_PTR)) #define astTest(this,attrib) \ astINVOKE(V,astTest_(astCheckObject(this),attrib,STATUS_PTR)) #define astSame(this,that) \ astINVOKE(V,astSame_(astCheckObject(this),astCheckObject(that),STATUS_PTR)) #define astHasAttribute(this,attrib) \ astINVOKE(V,astHasAttribute_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetProxy(this) \ astINVOKE(V,astGetProxy_(astCheckObject(this),STATUS_PTR)) #define astSetProxy(this,proxy) \ astINVOKE(V,astSetProxy_(astCheckObject(this),proxy,STATUS_PTR)) #if defined(astCLASS) /* Protected */ #if defined(THREAD_SAFE) #define astManageLock(this,mode,extra,fail) \ astINVOKE(V,astManageLock_(astCheckObject(this),mode, extra,fail,STATUS_PTR)) #else #define astManageLock(this,mode,extra,fail) #endif #define astCleanAttribs(this) astINVOKE(V,astCleanAttribs_(astCheckObject(this),STATUS_PTR)) #define astGetObjSize(this) astINVOKE(V,astGetObjSize_(astCheckObject(this),STATUS_PTR)) #define astCast(this,obj) astINVOKE(O,astCast_(astCheckObject(this),astCheckObject(obj),STATUS_PTR)) #define astCastCopy(this,obj) astCastCopy_((AstObject*)this,(AstObject*)obj,STATUS_PTR) #define astClearUseDefs(this) astINVOKE(V,astClearUseDefs_(astCheckObject(this),STATUS_PTR)) #define astTestUseDefs(this) astINVOKE(V,astTestUseDefs_(astCheckObject(this),STATUS_PTR)) #define astGetUseDefs(this) astINVOKE(V,astGetUseDefs_(astCheckObject(this),STATUS_PTR)) #define astSetUseDefs(this,val) astINVOKE(V,astSetUseDefs_(astCheckObject(this),val,STATUS_PTR)) #define astClearAttrib(this,attrib) \ astINVOKE(V,astClearAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astClearID(this) astINVOKE(V,astClearID_(astCheckObject(this),STATUS_PTR)) #define astClearIdent(this) astINVOKE(V,astClearIdent_(astCheckObject(this),STATUS_PTR)) #define astDump(this,channel) \ astINVOKE(V,astDump_(astCheckObject(this),astCheckChannel(channel),STATUS_PTR)) #define astGetAttrib(this,attrib) \ astINVOKE(V,astGetAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astGetClass(this) astINVOKE(V,astGetClass_((const AstObject *)(this),STATUS_PTR)) #define astGetID(this) astINVOKE(V,astGetID_(astCheckObject(this),STATUS_PTR)) #define astGetIdent(this) astINVOKE(V,astGetIdent_(astCheckObject(this),STATUS_PTR)) #define astGetNobject(this) astINVOKE(V,astGetNobject_(astCheckObject(this),STATUS_PTR)) #define astClassCompare(class1,class2) astClassCompare_(class1,class2,STATUS_PTR) #define astGetRefCount(this) astINVOKE(V,astGetRefCount_(astCheckObject(this),STATUS_PTR)) #define astSetAttrib(this,setting) \ astINVOKE(V,astSetAttrib_(astCheckObject(this),setting,STATUS_PTR)) #define astSetCopy(vtab,copy) \ astINVOKE(V,astSetCopy_((AstObjectVtab *)(vtab),copy,STATUS_PTR)) #define astSetDelete(vtab,delete) \ astINVOKE(V,astSetDelete_((AstObjectVtab *)(vtab),delete,STATUS_PTR)) #define astSetDump(vtab,dump,class,comment) \ astINVOKE(V,astSetDump_((AstObjectVtab *)(vtab),dump,class,comment,STATUS_PTR)) #define astSetVtab(object,vtab) \ astINVOKE(V,astSetVtab_((AstObject *)object,(AstObjectVtab *)(vtab),STATUS_PTR)) #define astSetID(this,id) astINVOKE(V,astSetID_(astCheckObject(this),id,STATUS_PTR)) #define astSetIdent(this,id) astINVOKE(V,astSetIdent_(astCheckObject(this),id,STATUS_PTR)) #define astVSet(this,settings,text,args) \ astINVOKE(V,astVSet_(astCheckObject(this),settings,text,args,STATUS_PTR)) #define astEnvSet(this) \ astINVOKE(V,astEnvSet_(astCheckObject(this),STATUS_PTR)) #define astTestAttrib(this,attrib) \ astINVOKE(V,astTestAttrib_(astCheckObject(this),attrib,STATUS_PTR)) #define astTestID(this) astINVOKE(V,astTestID_(astCheckObject(this),STATUS_PTR)) #define astTestIdent(this) astINVOKE(V,astTestIdent_(astCheckObject(this),STATUS_PTR)) /* Deprecated synonym. */ #define astClass(this) astGetClass(this) #endif /* Extra stuff for debuging probnlems with object handles and memory usage */ #ifdef MEM_DEBUG void astWatchHandle_( int ); void astHandleUse_( int, const char *, ... ); void astHandleAlarm_( const char *, va_list ); #define astWatchHandle astWatchHandle_ #define astHandleUse astHandleUse_ #define astHandleAlarm astHandleAlarm_ #else #define astWatchHandle #define astHandleUse #define astHandleAlarm #endif #endif ast-8.3.0/skyaxis.c0000664000175000017500000053772513004147321011111 00000000000000/* *class++ * Name: * SkyAxis * Purpose: * Store celestial axis information. * Constructor Function: * None. * Description: * The SkyAxis class is used to store information associated with a * particular axis of a SkyFrame. It is used internally by the AST * library and has no constructor function. You should encounter it c only within textual output (e.g. from astWrite). f only within textual output (e.g. from AST_WRITE). * Inheritance: * The SkyAxis class inherits from the Axis class. * Copyright: * Copyright (C) 1997-2006 Council for the Central Laboratory of the * Research Councils * Copyright (C) 2008 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: B.S. Berry (Starlink) * History: * 1-MAR-1996 (RFWS): * Original version. * 19-APR-1996 (RFWS): * Tidied up, etc. * 8-MAY-1996 (RFWS): * Remove leading minus sign from formatted HMS string if all * fields are zero. * 9-MAY-1996 (RFWS): * Fixed bug in rounding of fractional parts of HMS strings and * improved algorithm to cope gracefully with requests for * excessive numbers of decimal places. * 13-MAY-1996 (RFWS): * Over-ride the astGetAxisDirection method so that a SkyAxis * with the AsTime attribute set is displayed in reverse by * default. * 17-MAY-1996 (RFWS): * Change AxisNorm to return a bad coordinate value if a bad * value is given. * 11-SEP-1996 (RFWS): * Added AxisGap and DHmsGap (written by DSB). * 26-FEB-1998 (RFWS): * Over-ride the astAxisUnformat method. * 6-MAR-1998 (RFWS): * Add formatting options to omit degrees/hours field and change * all affected functions. * 10-AUG-2000 (DSB): * Fixed bug in DHmsFormat which could cause (for instance) a formatted * galactic longitude value of zero to be formated as "-0.-0". * 29-AUG-2001 (DSB): * Added AxisDistance and AxisOffset. * 10-OCT-2002 (DSB): * Over-ride the astGetAxisTop and astGetAxisBottom methods so that a * SkyAxis with the IsLatitude attribute set is legal between plus * and minus 90 degrees. * 8-JAN-2003 (DSB): * - Changed private InitVtab method to protected astInitSkyAxisVtab * method. * - Modify DHmsGap to avoid decimal gap "4" which produces things * like "0.0 0.4 0.8 1.2 1.6 2.0" ("4" replaced by "5"). * 24-JAN-2004 (DSB): * o Added AxisFields. * o Added 'g' format character which produces graphical separators. * o Modified AxisAbbrev to use AxisFields so that delimiters which * include digits can be recognised. * 13-SEP-20904 (DSB): * Modify AxisFields to correct usage of the "p" pointer in the * case that the first and only field begins with a minus sign. * 15-SEP-2004 (DSB): * Modified ParseDHmsFormat so that the number of decimal places * is specified by Digits if the given format string include a ".*" * precision (e.g. "dms.*"). * 18-MAR-2005 (DSB): * Invoke methods inherited from parent Axis class if the format * string starts with a '%' character. * 14-FEB-2006 (DSB): * Override astGetObjSize. * 30-JUN-2006 (DSB): * Guard against a null "str1" value in AxisAbbrev. * 7-AUG-2007 (DSB): * Added CentreZero attribute. * 1-FEB-2008 (DSB): * Modified AxisUnformat to allow the final numerical field to include * an exponent. * 13-OCT-2011 (DSB): * Use tuning parameters to store graphical delimiters. * 27-APR-2015 (DSB): * Added InternalUNit attribute.. * 26-OCT-2016 (DSB): * Override astAxisNormValues. *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 SkyAxis /* Header files. */ /* ============= */ #include "ast_err.h" /* Error code definitions */ /* Interface definitions. */ /* ---------------------- */ #include "pal.h" /* SLALIB interface */ #include "globals.h" /* Thread-safe global data access */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory allocation facilities */ #include "pointset.h" /* Sets of points (for AST__BAD) */ #include "axis.h" /* Axis (parent) class interface */ #include "skyaxis.h" /* Interface definition for this class */ #include "globals.h" /* Thread-safe global data access */ #include "wcsmap.h" /* For constants */ /* C header files. */ /* --------------- */ #include #include #include #include #include #include #include #include /* 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 const char *(* parent_getattrib)( AstObject *, const char *, int * ); static const char *(* parent_getaxislabel)( AstAxis *, int * ); static const char *(* parent_getaxissymbol)( AstAxis *, int * ); static const char *(* parent_getaxisunit)( AstAxis *, int * ); static int (* parent_testattrib)( AstObject *, const char *, int * ); static int (*parent_getaxisdirection)( AstAxis *this, int * ); static void (* parent_axisoverlay)( AstAxis *, AstAxis *, int * ); static void (* parent_clearattrib)( AstObject *, const char *, int * ); static void (* parent_setattrib)( AstObject *, const char *, int * ); static double (*parent_getaxisbottom)( AstAxis *this, int * ); static double (*parent_getaxistop)( AstAxis *this, int * ); static const char *(* parent_axisformat)( AstAxis *, double, int * ); static double (*parent_axisgap)( AstAxis *, double, int *, int * ); static int (*parent_axisunformat)( AstAxis *, const char *, double *, int * ); static int (*parent_axisfields)( AstAxis *, const char *, const char *, int, char **, int *, double *, int * ); /* Factors for converting between hours, degrees and radians. */ static double hr2rad; static double deg2rad; static double pi; static double piby2; /* 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->DHmsFormat_Buff[ 0 ] = 0; \ globals->DHmsUnit_Buff[ 0 ] = 0; \ globals->GetAttrib_Buff[ 0 ] = 0; \ globals->GetAxisFormat_Buff[ 0 ] = 0; /* Create the function that initialises global data for this module. */ astMAKE_INITGLOBALS(SkyAxis) /* Define macros for accessing each item of thread specific global data. */ #define class_init astGLOBAL(SkyAxis,Class_Init) #define class_vtab astGLOBAL(SkyAxis,Class_Vtab) #define dhmsformat_buff astGLOBAL(SkyAxis,DHmsFormat_Buff) #define dhmsunit_buff astGLOBAL(SkyAxis,DHmsUnit_Buff) #define getattrib_buff astGLOBAL(SkyAxis,GetAttrib_Buff) #define getaxisformat_buff astGLOBAL(SkyAxis,GetAxisFormat_Buff) static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER; #define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 ); #define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 ); /* If thread safety is not needed, declare and initialise globals at static variables. */ #else static char dhmsformat_buff[ AST__SKYAXIS_DHMSFORMAT_BUFF_LEN + 1 ]; static char dhmsunit_buff[ AST__SKYAXIS_DHMSUNIT_BUFF_LEN + 1 ]; static char getattrib_buff[ AST__SKYAXIS_GETATTRIB_BUFF_LEN + 1 ]; static char getaxisformat_buff[ AST__SKYAXIS_GETAXISFORMAT_BUFF_LEN + 1 ]; /* Define the class virtual function table and its initialisation flag as static variables. */ static AstSkyAxisVtab class_vtab; /* Virtual function table */ static int class_init = 0; /* Virtual function table initialised? */ #define LOCK_MUTEX2 #define UNLOCK_MUTEX2 #endif /* External 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. */ AstSkyAxis *astSkyAxisId_( const char *, ... ); /* Prototypes for Private Member Functions. */ /* ======================================== */ static const char *AxisAbbrev( AstAxis *, const char *, const char *, const char *, int * ); static const char *AxisFormat( AstAxis *, double, int * ); static int GetObjSize( AstObject *, int * ); static const char *GetAttrib( AstObject *, const char *, int * ); static const char *GetAxisFormat( AstAxis *, int * ); static const char *GetAxisInternalUnit( AstAxis *, int * ); static const char *GetAxisLabel( AstAxis *, int * ); static const char *GetAxisSymbol( AstAxis *, int * ); static const char *GetAxisUnit( AstAxis *, int * ); static const char *DHmsFormat( const char *, int, double, int * ); static const char *DHmsUnit( const char *, int, int, int * ); static double AxisGap( AstAxis *, double, int *, int * ); static double AxisDistance( AstAxis *, double, double, int * ); static double AxisOffset( AstAxis *, double, double, int * ); static double DHmsGap( const char *, int, double, int *, int * ); static double GetAxisTop( AstAxis *, int * ); static double GetAxisBottom( AstAxis *, int * ); static int AxisIn( AstAxis *, double, double, double, int, int * ); static int AxisFields( AstAxis *, const char *, const char *, int, char **, int *, double *, int * ); static int AxisUnformat( AstAxis *, const char *, double *, int * ); static int GetAxisAsTime( AstSkyAxis *, int * ); static int GetAxisDirection( AstAxis *, int * ); static int GetAxisIsLatitude( AstSkyAxis *, int * ); static int GetAxisCentreZero( AstSkyAxis *, int * ); static int TestAttrib( AstObject *, const char *, int * ); static int TestAxisAsTime( AstSkyAxis *, int * ); static int TestAxisFormat( AstAxis *, int * ); static int TestAxisInternalUnit( AstAxis *, int * ); static int TestAxisIsLatitude( AstSkyAxis *, int * ); static int TestAxisCentreZero( AstSkyAxis *, int * ); static void AxisNorm( AstAxis *, double *, int * ); static void AxisNormValues( AstAxis *, int, int, double *, int * ); static void AxisOverlay( AstAxis *, AstAxis *, int * ); static void ClearAttrib( AstObject *, const char *, int * ); static void ClearAxisAsTime( AstSkyAxis *, int * ); static void ClearAxisFormat( AstAxis *, int * ); static void ClearAxisIsLatitude( AstSkyAxis *, int * ); static void ClearAxisCentreZero( AstSkyAxis *, int * ); static void Copy( const AstObject *, AstObject *, int * ); static void Delete( AstObject *, int * ); static void Dump( AstObject *, AstChannel *, int * ); static void ParseDHmsFormat( const char *, int, char *, int *, int *, int *, int *, int *, int *, int *, int * ); static void SetAttrib( AstObject *, const char *, int * ); static void SetAxisAsTime( AstSkyAxis *, int, int * ); static void SetAxisFormat( AstAxis *, const char *, int * ); static void SetAxisIsLatitude( AstSkyAxis *, int, int * ); static void SetAxisCentreZero( AstSkyAxis *, int, int * ); /* Member functions. */ /* ================= */ static const char *AxisAbbrev( AstAxis *this_axis, const char *fmt, const char *str1, const char *str2, int *status ) { /* * Name: * AxisAbbrev * Purpose: * Abbreviate a formatted SkyAxis value by skipping leading fields. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *AxisAbbrev( AstAxis *this, const char *fmt, * const char *str1, const char *str2 ) * Class Membership: * SkyAxis member function (over-rides the protected astAxisAbbrev * method inherited from the Axis class). * Description: * This function compares two SkyAxis values that have been * formatted with the supplied format specifier (using astAxisFormat) * 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 SkyAxis. * fmt * Pointer to a constant null-terminated string containing the * format specifier used to format the two values. * str1 * Pointer to a constant null-terminated string containing the * first formatted value. If this is null, the returned pointer * points to the start of the final field in str2. * str2 * Pointer to a constant null-terminated string containing the * second formatted value. * Returned Value: * A pointer into the "str2" string which locates the first * character in the first field that differs between the two * formatted values. * * If the two values have no leading fields in common, the returned * value will point at the start of string "str2". If the two * values are equal, it will point at the terminating null at the * end of this string. * Notes: * - 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: */ char *fld1[ 3 ]; /* Pointers to start of each field in str1 */ char *fld2[ 3 ]; /* Pointers to start of each field in str2 */ const char *result; /* Result pointer to return */ int i; /* Loop counter for string fields */ int nf1; /* Number of fields found in str1 */ int nf2; /* Number of fields found in str2 */ int nc1[ 3 ]; /* Length of each field in str1 */ int nc2[ 3 ]; /* Length of each field in str2 */ /* Initialise. */ result = str2; /* Check the global error status. */ if ( !astOK ) return result; /* Find the fields within the "str2" string. */ nf2 = astAxisFields( this_axis, fmt, str2, 3, fld2, nc2, NULL ); /* If "str1" was not supplied, return a pointer to the final field in "str2". */ if( !str1 ) { result = fld2[ nf2 - 1 ]; /* Otherwise, find the fields within the "str1" string. */ } else { nf1 = astAxisFields( this_axis, fmt, str1, 3, fld1, nc1, NULL ); /* Loop to inspect corresponding fields from each string. */ for ( i = 0; i < nf1 && i < nf2; i++ ) { /* If the fields are different, break out of the loop. */ if ( nc1[ i ] != nc2[ i ] || strncmp( fld1[ i ], fld2[ i ], nc1[ i ] ) ) { break; /* Otherwise, move the returned poitner on to point to the start of the next field in str2. If we are already at the last field in str2, return a pointer to the terminating null. */ } else { if ( i + 1 < nf2 ) { result = fld2[ i + 1 ]; } else { result = strchr( str2, '\0' ); } } } } /* Return the result. */ return result; } static double AxisDistance( AstAxis *this_axis, double v1, double v2, int *status ) { /* * Name: * AxisDistance * Purpose: * Find the distance between two axis values. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * AxisDistance( AstAxis *this, double v1, double v2 ) * Class Membership: * SkyAxis member function (over-rides the protected astAxisDistance * method inherited from the Axis class). * Description: * This function returns a signed value representing the axis increment * from axis value v1 to axis value v2. * * For a SkyAxis, the angular difference between the two supplied axis * values is normalized into the range +PI to -PI. * Parameters: * this * Pointer to the SkyAxis. * v1 * The first axis value * v2 * The second axis value * Returned Value: * The axis increment from v1 to v2. * Notes: * - A value of AST__BAD is returned if either axis value is AST__BAD. * - 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: */ double result; /* Returned gap size */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Check both axis values are OK, and form the returned increment, normalizing it into the range +PI to -PI. */ if( v1 != AST__BAD && v2 != AST__BAD ) result = palDrange( v2 - v1 ); /* Return the result. */ return result; } static int AxisFields( AstAxis *this_axis, const char *fmt, const char *str, int maxfld, char **fields, int *nc, double *val, int *status ) { /* * Name: * AxisFields * Purpose: * Identify numerical fields within a formatted SkyAxis value. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int AxisFields( AstAxis *this_axis, const char *fmt, const char *str, * int maxfld, char **fields, int *nc, double *val ) * Class Membership: * SkyAxis member function (over-rides the protected astAxisFields * method inherited from the Axis class). * Description: * This function identifies the numerical fields within a SkyAxis value * that have been formatted using astAxisFormat. It assumes that the * value was formatted using the supplied format string. It also * returns the equivalent floating point value in radians. * Parameters: * this * Pointer to the SkyAxis. * 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 radians 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char sep; /* Field separator character */ char tbuf[50]; /* Buffer for terminator string */ char *p; /* Pointer to next character */ char *t; /* Pointer to start of terminator string */ char *term; /* Pointer to terminator string */ double dval; /* Value read from string */ double value; /* Equivalent radians value */ int as_time; /* Format the value as a time? */ int dh; /* Hours field required? */ int ifld; /* Field index */ int lead_zero; /* Add leading zeros? */ int min; /* Minutes field required? */ int ndp; /* Number of decimal places */ int ok; /* Value and format consistent? */ int plus; /* Add leading plus sign? */ int result; /* Result fields count to return */ int sec; /* Seconds field required? */ int sign; /* The sign of the radians value */ /* Check the global error status. */ if ( !astOK ) return 0; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_axis); /* If the format string starts with a "%" call the method inherited from the parent Axis class. */ if( fmt[ 0 ] == '%' ) { return (*parent_axisfields)( this_axis, fmt, str, maxfld, fields, nc, val, status ); } /* Initialise. */ result = 0; for( ifld = 0; ifld < maxfld; ifld++ ) { fields[ ifld ] = NULL; nc[ ifld ] = 0; } if( val ) *val = AST__BAD; /* Parse the format specifier. */ ParseDHmsFormat( fmt, astGetAxisDigits( this_axis ), &sep, &plus, &lead_zero, &as_time, &dh, &min, &sec, &ndp, status ); /* Only proceed if the format was parsed succesfully, and the supplied arrays are not of zero size. */ if( astOK && maxfld > 0 ) { /* Indicate that we have not yet found any inconsistency between the formatted value and the forat string. */ ok = 1; /* Variable "p" points to the next character to be read from the formatted string. Initialise it to point to the first non-space character. */ p = (char *) str; while( *p == ' ' ) p++; /* Note the start of the first field. */ fields[ 0 ] = p; /* If the first non-blank character is a + or - sign, skip it and note the sign of the final value. */ sign = 1; if( *p == '-' ) { sign = -1; p++; } else if( *p == '+' ) { p++; } /* Initialise the equivalent radian value. */ value = 0.0; /* If the format string specifies a degrees or hours field, it should be the first field. */ if( dh ) { /* If the format indicates that fields are separated by characters, or if there is a minutes or seconds field, then the first field should end with the appropriate separator. In these cases locate the terminator,and store the length of the first field. */ if( sep == 'l' || sep == 'g' || min || sec ) { if( sep == 'l' ) { term = as_time ? "h" : "d"; } else if( sep == 'g' ) { astTuneC( as_time ? "hrdel":"dgdel", NULL, tbuf, sizeof( tbuf ) ); term = tbuf; } else { tbuf[ 0 ] = sep; tbuf[ 1 ] = '\0'; term = tbuf; } t = strstr( p, term ); if( t ) { nc[ 0 ] = t - fields[ 0 ]; } else { ok = 0; } /* Move on to the first character following the terminator. */ p = t + strlen( term ); /* In all other cases, the first field is the only field and is not terminated. Note its length (ignoring trailing spaces). Move the pointer on by the length of the field, remembering that any leading minus sign has already been skipped. */ } else { nc[ 0 ] = astChrLen( fields[ 0 ] ); p += nc[ result ]; if( sign == -1 ) p--; } /* Read a numerical value from the first field. */ if( astSscanf( fields[ 0 ], "%lg", &dval ) ) { value = fabs( dval ); } else { ok = 0; } /* Increment then number of returned fields if OK */ if( ok ) result++; } /* If the format string specifies a minutes field, it should be the next field. */ if( min && ok ) { /* Note the start of the next field. */ fields[ result ] = p; /* If the format indicates that fields are separated by characters, or if there is a seconds field, then this field should end with the appropriate separator. In these cases locate the terminator,and store the length of this field. */ if( sep == 'l' || sep == 'g' || sec ) { if( sep == 'l' ) { term = "m"; } else if( sep == 'g' ) { astTuneC( as_time ? "mndel":"amdel", NULL, tbuf, sizeof( tbuf ) ); term = tbuf; } else { tbuf[ 0 ] = sep; tbuf[ 1 ] = '\0'; term = tbuf; } t = strstr( p, term ); if( t ) { nc[ result ] = t - fields[ result ]; } else { ok = 0; } /* Move on to the first character following the terminator. */ p = t + strlen( term ); /* In all other cases, this field is not terminated. Note its length (ignoring trailing spaces). */ } else { nc[ result ] = astChrLen( fields[ result ] ); p += nc[ result ]; } /* Read a numerical value from this field. */ if( astSscanf( fields[ result ], "%lg", &dval ) ) { value += dval/60.0; } else { ok = 0; } /* Increment then number of returned fields if OK */ if( ok ) result++; } /* If the format string specifies a seconds field, it should be the next field. */ if( sec && ok ) { /* Note the start of the next field. */ fields[ result ] = p; /* If the format indicates that fields are separated by characters, then this field should end with the appropriate separator. In this case locate the terminator,and store the length of this field. */ if( sep == 'l' || sep == 'g' ) { if( sep == 'l' ) { term = "s"; } else { astTuneC( as_time ? "scdel":"asdel", NULL, tbuf, sizeof( tbuf ) ); term = tbuf; } t = strstr( p, term ); if( t ) { nc[ result ] = t - fields[ result ]; } else { ok = 0; } /* Move on to the first character following the terminator. */ p = t + strlen( term ); /* In all other cases, this field is not terminated. Note its length (ignoring trailing spaces). */ } else { nc[ result ] = astChrLen( fields[ result ] ); p += nc[ result ]; } /* Read a numerical value from this field. */ if( astSscanf( fields[ result ], "%lg", &dval ) ) { value += dval/3600.0; } else { ok = 0; } /* Increment then number of returned fields if OK */ if( ok ) result++; } /* Check that nothing is left.*/ if( astChrLen( p ) > 0 ) ok = 0; /* If OK, convert the axis value to radians. */ if( ok ) { if( val ) { *val = sign*value*( as_time ? hr2rad : deg2rad ); } /* Otherwise, return zero. */ } else { result = 0; for( ifld = 0; ifld < maxfld; ifld++ ) { fields[ ifld ] = NULL; nc[ ifld ] = 0; } } } /* Return the result. */ return result; } static const char *AxisFormat( AstAxis *this_axis, double value, int *status ) { /* * Name: * AxisFormat * Purpose: * Format a coordinate value for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *AxisFormat( AstAxis *this, double value, int *status ) * Class Membership: * SkyAxis member function (over-rides the astAxisFormat method inherited * from the Axis class). * Description: * This function returns a pointer to a string containing the formatted * (character) version of a coordinate value for a SkyAxis. The formatting * applied is that specified by a previous invocation of the * astSetAxisFormat method. A suitable default format is applied if * necessary. * Parameters: * this * Pointer to the SkyAxis. * value * The coordinate value to be formatted (in radians). * 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 SkyAxis 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 SkyAxis. 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: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *fmt; /* Pointer to format specifier */ const char *result; /* Pointer to result string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise. */ result = NULL; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Obtain a pointer to the format specifier to be used. Note we use a private member function to obtain this (not a method) in case derived classes have extended the syntax of this string. */ fmt = GetAxisFormat( this_axis, status ); /* If the format string starts with a percent, use the AxisFormat method inherited from the parent Axis class. Otherwise, format using the syntax of this class. */ if ( astOK ) { if( fmt[ 0 ] == '%' ) { result = (*parent_axisformat)( this_axis, value, status ); } else { result = DHmsFormat( fmt, astGetAxisDigits( this ), value, status ); } } /* Return the result. */ return result; } static double AxisGap( AstAxis *this_axis, double gap, int *ntick, int *status ) { /* * Name: * AxisGap * Purpose: * Find a "nice" gap for tabulating SkyAxis values. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * double AxisGap( AstAxis *this, double gap, int *ntick, int *status ) * Class Membership: * SkyAxis member function (over-rides the protected astAxisGap * method inherited from the Axis class). * Description: * This function returns a gap size in radians which produces a * nicely spaced series of formatted SkyAxis values, 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 SkyAxis. * 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: * - The returned gap size is influenced by the format string * specified for the SkyAxis by a previous invocation of the * astSetAxisFormat method. A suitable default format is used if * necessary. * - A value of zero is returned if the supplied 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: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *fmt; /* Pointer to Format string */ double result; /* Returned gap size */ /* Initialise. */ result = 0.0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Obtain a pointer to the format string to be used. Note we use a private member function to obtain this (not a method) in case derived classes have extended the syntax of this string. */ fmt = GetAxisFormat( this_axis, status ); /* Obtain the closest "nice" gap size. */ if ( astOK ) result = DHmsGap( fmt, astGetAxisDigits( this ), gap, ntick, status ); /* If the format string starts with a percent, use the AxisGap method inherited from the parent Axis class. Otherwise, use the method provided by this class. */ if ( astOK ) { if( fmt[ 0 ] == '%' ) { result = (*parent_axisgap)( this_axis, gap, ntick, status ); } else { result = DHmsGap( fmt, astGetAxisDigits( this ), gap, ntick, status ); } } /* Return the result. */ return result; } static int AxisIn( AstAxis *this, double lo, double hi, double val, int closed, int *status ){ /* * Name: * AxisIn * Purpose: * Test if an axis value lies within a given interval. * Type: * Protected virtual function. * Synopsis: * #include "skyaxis.h" * int AxisIn( AstAxis *this, double lo, double hi, double val, int closed, int *status ) * Class Membership: * SkyAxis member function (over-rides the astAxisIn method inherited * from the Axis class). * Description: * This function returns non-zero if a given axis values lies within a * given axis interval. * * The SkyAxis implementation of this method treats the supplied * numerical values as non-cyclic (e.g. lo=10, hi = 350 implies that * val = 180 is inside and zero is outside: lo = 10, hi = 400 would imply * that all angles are inside: lo = -10, hi = 10 would imply that 180 is * outside and zero is inside). But when testing a supplied value, adding * or subtracting multiples of 2.PI from the supplied value will make no * difference to whether the point is inside or outside). * Parameters: * this * Pointer to the Axis. * lo * The lower axis limit of the interval. * hi * The upper axis limit of the interval. * val * The axis value to be tested. * closed * If non-zero, then the lo and hi axis values are themselves * considered to be within the interval. Otherwise they are outside. * status * Pointer to the inherited status variable. * Returned Value: * Non-zero if the test value is inside the interval. */ /* For speed, omit the astOK check since no pointers are being used. */ /* Deal with closed intervals. */ if( closed ) { /* If the supplied value is greater than the upper limit, subtract 2.PI until it is not. */ while( val > hi ) val -= 2*pi; /* If the value is now less than the lower limit, add 2.PI until it is not. */ while( val < lo ) val += 2*pi; /* The axis value is in the range if its numerical value is less than or equal to the end value. */ return ( val <= hi ); /* Now deal with open intervals. */ } else { /* If the supplied value is greater than or equal to the upper limit, subtract 2.PI until it is not. */ while( val >= hi ) val -= 2*pi; /* If the value is now less than or equal to the lower limit, add 2.PI until it is not. */ while( val <= lo ) val += 2*pi; /* The axis value is in the range if its numerical value is less than the end value. */ return ( val < hi ); } } static void AxisNorm( AstAxis *this_axis, double *value, int *status ) { /* * Name: * AxisNorm * Purpose: * Normalise a SkyAxis coordinate value. * Type: * Public virtual function. * Synopsis: * #include "skyaxis.h" * void AxisNorm( AstAxis *this, double *value, int *status ) * Class Membership: * SkyAxis member function (over-rides the astAxisNorm method inherited * from the Axis class). * Description: * This function converts a SkyAxis coordinate value which might * potentially be unsuitable for display to a user (for instance, * may lie outside the expected range of values) into an acceptable * alternative value suitable for display. * * For a SkyAxis that is a longitude axis, values are wrapped into * the range zero to 2*pi, while for a latitude axis, they are * wrapped into the range -pi to +pi. The astAxisCentreZero method * is used to determine which algorithm to apply. * Parameters: * this * Pointer to the SkyAxis. * value * Pointer to the coordinate value to be normalised, which will * be modified in place. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ int centrezero; /* SkyAxis range centred on zero? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* If the coordinate value is bad, then return it unchanged. Otherwise, determine if the SkyAxis range is centred on zero or PI. */ if ( *value != AST__BAD ) { centrezero = astGetAxisCentreZero( this ); /* Wrap the value into the appropriate range. */ if ( astOK ) *value = centrezero ? palDrange( *value ) : palDranrm( *value ); } } static void AxisNormValues( AstAxis *this_axis, int oper, int nval, double *values, int *status ){ /* * Name: * astAxisNormValues * Purpose: * Normalise an array of axis coordinate values. * Type: * Public virtual function. * Synopsis: * #include "skyaxis.h" * void astAxisNormValues( AstAxis *this, int oper, int nval, * double *values ) * Class Membership: * SkyAxis member function (over-rides the astAxisNormValues method * inherited from the Axis class). * Description: * This function modifies a supplied array of axis values so that * they are normalised in the manner indicated by parameter "oper". * * For a SkyAxis, if "oper" is 0, longitude values are returned in * the range [0,2*PI]. If "oper" is 1, longitude values are returned * in either the range [0,2*PI] or [-PI,PI]. The choice is made so * that the resulting list has the smallest range. Latitude values * are always returned in the range [-PI,PI]. * Parameters: * this * Pointer to the Axis. * oper * Indicates the type of normalisation to be applied. If zero is * supplied, the normalisation will be the same as that performed by * function astAxisNorm. 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. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ double *pv; /* Pointer to next axis value */ double hi; /* Max axis value after normalisation */ double lo; /* Min axis value after normalisation */ double mn1; /* Min value in range [-pi,0] */ double mn2; /* Min value in range [0,pi] */ double mn3; /* Min value in range [pi,2pi] */ double mx1; /* Max value in range [-pi,0] */ double mx2; /* Max value in range [0,pi] */ double mx3; /* Max value in range [pi,2pi] */ double range1; /* Range after normalising to [0,2*pi] */ double range2; /* Range after normalising to [-pi,pi] */ double twopi; /* Two PI */ int centrezero; /* SkyAxis range centred on zero? */ int i; /* Index of next axis value */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Oper 0 - always normalise according to the value of the CentreZero attribute (i.e. mimic AxisNorm). */ if( oper == 0 ) { /* Determine if the SkyAxis range is centred on zero or PI. */ centrezero = astGetAxisCentreZero( this ); /* Loop over axis values. */ pv = values; for( i = 0; i < nval; i++,pv++ ) { /* If the coordinate value is bad, then return it unchanged. Otherwise, wrap the value into the appropriate range. */ if( *pv != AST__BAD ) *pv = centrezero ? palDrange( *pv ) : palDranrm( *pv ); } /* Oper 1 - choose a range that leaves most values unchanged. */ } else if( oper == 1 ) { /* Normalise latitude axes into [-PI,+PI]. */ if( astGetAxisIsLatitude( this ) ) { pv = values; for( i = 0; i < nval; i++,pv++ ) { *pv = palDrange( *pv ); } /* Now deal with longitude axes. */ } else { /* First ensure all values are in the range [-PI,2*PI] and find the max and min value in each of the three ranges [-PI,0], [0,PI], [PI, 2PI]. */ twopi = 2*AST__DPI; mx1 = -DBL_MAX; mn1 = DBL_MAX; mx2 = -DBL_MAX; mn2 = DBL_MAX; mx3 = -DBL_MAX; mn3 = DBL_MAX; pv = values; for( i = 0; i < nval; i++,pv++ ) { while( *pv > twopi ) *pv -= twopi; while( *pv < -AST__DPIBY2 ) *pv += twopi; if( *pv > AST__DPI ) { mx3 = astMAX( mx3, *pv ); mn3 = astMIN( mn3, *pv ); } else if( *pv > 0 ) { mx2 = astMAX( mx2, *pv ); mn2 = astMIN( mn2, *pv ); } else { mx1 = astMAX( mx1, *pv ); mn1 = astMIN( mn1, *pv ); } } /* What would the range be if we normalised into [0,2.PI] ? */ if( mx1 != -DBL_MAX ) { hi = astMAX( mx2, astMAX( mx1 + twopi, mx3) ); lo = astMIN( mn2, astMIN( mn1 + twopi, mn3) ); } else { hi = astMAX( mx2, mx3 ); lo = astMIN( mn2, mn3 ); } range1 = hi - lo; /* What would the range be if we normalised into [-PI,PI] ? */ if( mn3 != -DBL_MAX ) { hi = astMAX( mx2, astMAX( mx3 - twopi, mx1) ); lo = astMIN( mn2, astMIN( mn3 - twopi, mn1) ); } else { hi = astMAX( mx2, mx1 ); lo = astMIN( mn2, mn1 ); } range2 = hi - lo; /* If [-PI,PI] produces the smaller range, normalise into [-PI,PI]. */ if( range2 < range1 ) { pv = values; for( i = 0; i < nval; i++,pv++ ) { *pv = palDrange( *pv ); } /* Otherwise, normalise all into the range [0,2PI]. */ } else { pv = values; for( i = 0; i < nval; i++,pv++ ) { *pv = palDranrm( *pv ); } } } /* Report an error if the supplied operation is invalid. */ } else if( astOK ) { astError( AST__INTER, "astAxisNormValues: Invalid oper value %d " "supplied (internal AST programming error).", status, oper ); } } static double AxisOffset( AstAxis *this_axis, double v1, double dist, int *status ) { /* * * Name: * AxisOffset * Purpose: * Add an increment onto a supplied axis value. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * AxisOffset( AstSkyAxis *this, double v1, double dist ) * Class Membership: * SkyAxis member function (over-rides the protected astAxisOffset * method inherited from the Axis class). * Description: * This function returns an axis value formed by adding a signed axis * increment onto a supplied axis value. * * For a SkyFrame, the result is normalized into the correct angular * range (+PI to -PI for latitude axes, and 0 to 2*PI for longitude axes). * Parameters: * this * Pointer to the SkyAxis. * v1 * The supplied axis value * dist * The axis increment * Returned Value: * The axis value which is the specified increment away from v1. * Notes: * - A value of AST__BAD is returned if either axis value is AST__BAD. * - 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: */ double result; /* Returned gap size */ /* Initialise. */ result = AST__BAD; /* Check the global error status. */ if ( !astOK ) return result; /* Check both axis values are OK, and form the returned axis value. */ if( v1 != AST__BAD && dist != AST__BAD ) { result = v1 + dist; AxisNorm( this_axis, &result, status ); } /* Return the result. */ return result; } static void AxisOverlay( AstAxis *template_axis, AstAxis *result, int *status ) { /* * Name: * AxisOverlay * Purpose: * Overlay the attributes of a template SkyAxis on to another Axis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void AxisOverlay( AstAxis *template, AstAxis *result, int *status ) * Class Membership: * SkyAxis member function (over-rides the astAxisOverlay method inherited * from the Axis class). * Description: * This function overlays attributes of a SkyAxis (the "template") on to * another Axis, so as to over-ride selected attributes of that second * Axis. Normally only those attributes which have been specifically set * in the template will be transferred. This implements a form of * defaulting, in which an Axis 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 SkyAxis, for which values should have been * explicitly set for any attribute which is to be transferred. * result * Pointer to the Axis which is to receive the new attribute values. * status * Pointer to the inherited status variable. * Returned Value: * void */ /* Local Variables: */ AstSkyAxis *template; /* Pointer to the SkyAxis structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the template SkyAxis structure. */ template = (AstSkyAxis *) template_axis; /* Invoke the parent astAstOverlay method to overlay inherited attributes. */ (*parent_axisoverlay)( template_axis, result, status ); /* Test if the "result" Axis is a SkyAxis (if not, it cannot acquire any further attributes, so there is nothing more to do). */ if ( astIsASkyAxis( result ) && astOK ) { /* Overlay the Format attribute if it is set in the template. Note that we use private member functions (not methods) to access the Format value, since derived classes may extend the syntax of this string and we should not overlay a string whose syntax cannot be interpreted by the result Axis. */ if ( TestAxisFormat( template_axis, status ) ) { SetAxisFormat( result, GetAxisFormat( template_axis, status ), status ); } /* Overlay the AsTime attribute in the same way, but this time using methods to access it. */ if ( astTestAxisAsTime( template ) ) { astSetAxisAsTime( result, astGetAxisAsTime( template ) ); } /* Also overlay the IsLatitude attribute. */ if ( astTestAxisIsLatitude( template ) ) { astSetAxisIsLatitude( result, astGetAxisIsLatitude( template ) ); } /* Also overlay the CentreZero attribute. */ if ( astTestAxisCentreZero( template ) ) { astSetAxisCentreZero( result, astGetAxisCentreZero( template ) ); } } } static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * ClearAttrib * Purpose: * Clear an attribute value for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void ClearAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyAxis member function (over-rides the astClearAttrib protected * method inherited from the Axis class). * Description: * This function clears the value of a specified attribute for a * SkyAxis, so that the default value will subsequently be used. * Parameters: * this * Pointer to the SkyAxis. * attrib * Pointer to a null-terminated string specifying the attribute * name. This should be in lower case with no surrounding white * space. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_object; /* Check the attribute name and clear the appropriate attribute. */ /* AsTime. */ /* ------- */ if ( !strcmp( attrib, "astime" ) ) { astClearAxisAsTime( this ); /* IsLatitude. */ /* ----------- */ } else if ( !strcmp( attrib, "islatitude" ) ) { astClearAxisIsLatitude( this ); /* CentreZero. */ /* ----------- */ } else if ( !strcmp( attrib, "centrezero" ) ) { astClearAxisCentreZero( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { (*parent_clearattrib)( this_object, attrib, status ); } } static void ClearAxisFormat( AstAxis *this_axis, int *status ) { /* * Name: * ClearAxisFormat * Purpose: * Clear the Format attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void ClearAxisFormat( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astClearAxisFormat method * inherited from the Axis class). * Description: * This function clears the Format attribute of a SkyAxis, as if no value * had ever been set for it. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * void */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Free any memory allocated to hold the Format string and reset the string pointer to NULL. */ this->skyformat = astFree( this->skyformat ); } static const char *DHmsFormat( const char *fmt, int digs, double value, int *status ) { /* * Name: * DHmsFormat * Purpose: * Format a value representing degrees/hours, minutes and seconds. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *DHmsFormat( const char *fmt, int digs, double value, int *status ) * Class Membership: * SkyAxis member function. * Description: * This function formats a value representing an angle in radians * into a text string giving degrees/hours, minutes and seconds * according to a format specifier supplied. See the "Format * Specifier" section for details of the formats available. * Parameters: * fmt * Pointer to a null terminated string containing the format * specifier. * digs * The default number of digits of precision to use. This is used * if the given format specifier indicates the number of decimal * places to use with the string ".*". In this case, the number of * decimal places produced will be chosen so that the total number * of digits of precision is equal to "digs". * double * The value to be formatted (in radians). * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null terminated character string containing the * formatted value. * Format Specifier: * The format specifier supplied via the "fmt" parameter should * contain zero or more of the following characters to specify the * format required. These characters may occur in any order, but * the following is recommended for clarity: * * '+' * Indicates that a plus sign should be prefixed to positive * values. By default, no plus sign is used. * 'z' * Indicates that leading zeros should be prefixed to the value * so that the first field is always of constant width, as would * be required in a fixed-width table. (Leading zeros are always * prefixed to any fields that follow.) By default, no leading * zeros are added. * 'i' * Use the standard ISO field separator (a colon) between * fields. This is the default behaviour. * 'b' * Use a blank to separate fields. * 'l' * Use a letter ('d'/'h', 'm' or 's' as appropriate) to separate * and identify fields. * 'g' * As 'l', but escape sequences are included in the returned * character string which cause the separators ('h', 'd', 'm', etc) * to be drawn as small super-scripts when plotted by the astText * or astGrid. * 'd' * Express the value as an angle and include a degrees * field. Expressing the value as an angle is also the default * behaviour if neither 'h' nor 't' is given, and expressing it * in degrees is the default if neither 'm' nor 's' is given. * 'h' * Express the value as a time instead of an angle (where 24 * hours correspond to 360 degrees) and include an hours * field. Expressing times in hours is the default if 't' is * given without either 'm' or 's'. * 'm' * Include a minutes field. By default this is not included. * 's' * Include a seconds field. By default this is not * included. This request is ignored if 'd' or 'h' is given, * unless a minutes field is also included. * 't' * Express the value as a time instead of an angle (where 24 * hours correspond to 360 degrees). This option is ignored if * either 'd' or 'h' is given and is intended for use in cases * where the value is to be expressed purely in minutes and/or * seconds of time (no hours field). If 't' is given without * 'd', 'h', 'm' or 's' being present, then it is equivalent to * 'h'. * '.' * Indicates that decimal places are to be given for the final * field in the formatted string (whichever field this is). The * '.' should be followed immediately by a zero or positive integer * which gives the number of decimal places required. The '.' may * also be followed by asterisk (i.e. '.*') which causes the number * of decimal places to be chosen so that the total number of digits * is equal to the value of Digits. * * Format specifiers are not case sensitive. If several characters * make conflicting requests (e.g. if both 'i' and 'l' appear in a * format specifier), then the character occurring last takes * precedence, except that 'd' and 'h' always override 't'. * Notes: * - The result string may be stored in static memory. Its contents * may be over-written or the returned pointer may become invalid * following a further invocation of this function. 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. * Acknowledgements: * - This function is a close approximation to a Fortran 77 routine * written by Clive Davenhall which implements the system of format * specifiers for angles described in his document on the CAT * catalogue access library (Starlink User Note 181). Some minor * improvements have been made to ensure better behaviour when * results are rounded to a specified number of decimal places. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char *term; /* Pointer to terminator string */ char sep; /* Field separator character */ char tbuf[50]; /* Buffer for terminator string */ const char *result; /* Pointer to result string */ double absvalue; /* Absolute value in radians */ double fract; /* Fractional part of final field */ double idh; /* Integer number of degrees/hours */ double ifract; /* Fractional part expressed as an integer */ double imin; /* Integer number of minutes */ double isec; /* Integer number of seconds */ double shift; /* Factor for rounding fractional part */ double test; /* Test value to determine rounding */ int as_time; /* Format the value as a time? */ int dh; /* Degrees/hours field required? */ int lead_zero; /* Add leading zeros? */ int min; /* Minutes field required? */ int ndp; /* Number of decimal places */ int plus; /* Add leading plus sign? */ int pos; /* Position to add next character */ int positive; /* Value is positive (or zero)? */ int sec; /* Seconds field required? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Initialise. */ result = NULL; /* Check if a bad coordinate value has been given and return an appropriate string. */ if ( value == AST__BAD ) { result = ""; /* Otherwise... */ } else { /* Parse the format specifier. */ ParseDHmsFormat( fmt, digs, &sep, &plus, &lead_zero, &as_time, &dh, &min, &sec, &ndp, status ); /* Break the value into fields. */ /* ---------------------------- */ /* Restrict the number of decimal places requested, if necessary, so that under the worst case the buffer for the result string is not likely to overflow. */ if ( astOK ) { if ( ( ndp + 11 ) > AST__SKYAXIS_DHMSFORMAT_BUFF_LEN ) ndp = AST__SKYAXIS_DHMSFORMAT_BUFF_LEN - 11; /* Some operating systems have a "minus zero" value (for instance "-1.2*0" would give "-0"). This value is numerically equivalent to zero, but is formated as "-0" instead of "0". The leading minus sign confuses the following code, and so ensure now that all zero values are the usual "+0". */ if ( value == 0.0 ) value = 0.0; /* Determine if the value to be formatted is positive and obtain its absolute value in radians. */ positive = ( value >= 0.0 ); absvalue = positive ? value : -value; /* Convert this to an absolute number of degrees or hours, as required. */ fract = absvalue / ( as_time ? hr2rad : deg2rad ); /* If a degrees/hours field is required, extract the whole number of degrees/hours and the remaining fractional part of a degree/hour. */ idh = 0.0; if ( dh ) fract = modf( fract, &idh ); /* If a minutes field is required, convert the value remaining to minutes and extract the whole number of minutes and the remaining fractional part of a minute. */ imin = 0.0; if ( min ) fract = modf( fract * 60.0, &imin ); /* If a seconds field is required, convert the value remaining to seconds (allowing for the absence of a minutes field if necessary) and extract the whole number of seconds and the remaining fractional part of a second. */ isec = 0.0; if ( sec ) { if ( !min ) fract *= 60.0; fract = modf( fract * 60.0, &isec ); } /* Round to the required number of decimal places. */ /* ----------------------------------------------- */ /* We must now round the fractional part (of whichever field) to the required number of decimal places. Calculate the power of 10 that brings the least significant digit into the units column. Scale the fractional part by this factor and truncate to an integer (but stored as a double to prevent possible integer overflow if the number of decimal places is excessive). */ shift = pow( 10.0, (double) ndp ); ifract = floor( fract * shift ); /* Next we must determine if truncation was adequate, or whether we should round upwards instead. This process is more subtle than it seems because if a value with a 5 as the final digit is converted to radians and then back again, it may no longer end in 5 (because it cannot be represented exactly in radians) and so may round either up or down. If we want to recover the original (textual) value, we must compare the value we are formatting not with a test value whose last digit is 5, but with the closest number to this that can be represented exactly in radians. To do this, we add 0.5 to our truncated value, divide by the scale factor (to get the truncated fractional part, but now with a trailing digit 5 appended) and then combine this fractional part with the value of all the other fields. Finally, we convert this test value back into radians. */ test = ( 0.5 + ifract ) / shift; if ( sec ) test = ( isec + test ) / 60.0; if ( min ) { test = ( imin + test ) / 60.0; } else if ( sec ) { test /= 60.0; } if ( dh ) test += idh; test *= ( as_time ? hr2rad : deg2rad ); /* We now compare the absolute value we are formatting with this test value. If it is not smaller than it, we should have rounded up instead of truncating the final digit of the fractional part, so increment the integer representation of the truncated fractional part by 1.0 to compensate. */ if ( absvalue >= test ) ifract += 1.0; /* Divide by the scale factor to obtain the correctly rounded fractional part. Then check if this fractional part is 1.0. If so, rounding has caused it to overflow into the units column of the final field, so clear the fractional part. */ fract = ( ifract / shift ); if ( fract >= 1.0 ) { ifract = 0.0; /* If a seconds field is present, propagate the overflow up through each field in turn, but omitting fields which are not required. Be careful about possible rounding errors when comparing integer values stored as double. */ if ( sec ) { isec += 1.0; if ( ( floor( isec + 0.5 ) > 59.5 ) && min ) { isec = 0.0; imin += 1.0; if ( ( floor( imin + 0.5 ) > 59.5 ) && dh ) { imin = 0.0; idh += 1.0; } } /* Omit the seconds field if it is not present. */ } else if ( min ) { imin += 1.0; if ( ( floor( imin + 0.5 ) > 59.5 ) && dh ) { imin = 0.0; idh += 1.0; } /* If only the degree/hour field is present, simply increment it. */ } else { idh += 1.0; } } /* Construct the result string. */ /* ---------------------------- */ /* We now have the value of each field and the information about how they are to be formatted, so we can combine them into the required string. */ /* If each field is either not required or equal to zero, disregard any sign. */ if ( !positive && ( !dh || floor( idh + 0.5 ) < 0.5 ) && ( !min || floor( imin + 0.5 ) < 0.5 ) && ( !sec || floor( isec + 0.5 ) < 0.5 ) && ( floor( ifract + 0.5 ) < 0.5 ) ) { positive = 1; } /* Use "pos" to identify where the next character should be added. Insert a leading '+' or '-' sign if required. */ pos = 0; if ( !positive ) { dhmsformat_buff[ pos++ ] = '-'; } else if ( plus ) { dhmsformat_buff[ pos++ ] = '+'; } /* Use "sprintf" to format the degrees/hours field, if required. Set the minimum field width according to whether padding with leading zeros is required and whether the value represents hours (2 digits) or degrees (3 digits). */ if ( dh ) { pos += sprintf( dhmsformat_buff + pos, "%0*.0f", lead_zero ? ( as_time ? 2 : 3 ) : 1, idh ); /* If letters are being used as field separators, and there are more fields to follow, append "d" or "h" as necessary. */ if ( min || sec ) { if ( sep == 'l' ) { dhmsformat_buff[ pos++ ] = ( as_time ? 'h' : 'd' ); } else if( sep == 'g' ) { astTuneC( as_time ? "hrdel":"dgdel", NULL, tbuf, sizeof( tbuf ) ); term = tbuf; pos += sprintf( dhmsformat_buff + pos, "%s", term ); } } } /* If a minutes field is required, first add an appropriate non-letter field separator if needed. */ if ( min ) { if ( ( sep != 'l' && sep != 'g' ) && dh ) dhmsformat_buff[ pos++ ] = sep; /* Then format the minutes field with a leading zero to make it two digits if necessary. */ pos += sprintf( dhmsformat_buff + pos, "%0*.0f", ( dh || lead_zero ) ? 2 : 1, imin ); /* If letters are being used as field separators, and there is another field to follow, append the separator. */ if ( sec ) { if ( sep == 'l' ) { dhmsformat_buff[ pos++ ] = 'm'; } else if( sep == 'g' ) { astTuneC( as_time ? "mndel":"amdel", NULL, tbuf, sizeof( tbuf ) ); term = tbuf; pos += sprintf( dhmsformat_buff + pos, "%s", term ); } } } /* Similarly, if a seconds field is required, first add an appropriate non-letter field separator if needed. */ if ( sec ) { if ( ( sep != 'l' && sep != 'g' ) && ( dh || min ) ) dhmsformat_buff[ pos++ ] = sep; /* Then format the seconds field with a leading zero to make it two digits if necessary. */ pos += sprintf( dhmsformat_buff + pos, "%0*.0f", ( dh || min || lead_zero ) ? 2 : 1, isec ); } /* If decimal places are needed, add a decimal point followed by the integer representation of the correctly rounded fractional part, padded with leading zeros if necessary. */ if ( ndp > 0 ) { dhmsformat_buff[ pos++ ] = '.'; pos += sprintf( dhmsformat_buff + pos, "%0*.0f", ndp, ifract ); } /* If letters are being used as separators, append the appropriate one to the final field. */ if ( sep == 'l' ) { dhmsformat_buff[ pos++ ] = ( sec ? 's' : ( min ? 'm' : ( as_time ? 'h' : 'd' ) ) ); } else if ( sep == 'g' ) { astTuneC( as_time ? ( sec ? "scdel" : ( min ? "mndel" : "hrdel" ) ) : ( sec ? "asdel" : ( min ? "amdel" : "dgdel" ) ), NULL, tbuf, sizeof( tbuf ) ); term = tbuf; pos += sprintf( dhmsformat_buff + pos, "%s", term ); } /* Terminate the result string and return a pointer to it. */ dhmsformat_buff[ pos ] = '\0'; result = dhmsformat_buff; } } /* Return the result. */ return result; } static double DHmsGap( const char *fmt, int digs, double gap, int *ntick, int *status ) { /* * Name: * DHmsGap * Purpose: * Find a "nice" gap for formatted SkyAxis values. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * double DHmsGap( const char *fmt, int digs, double gap, int *ntick, int *status ) * Class Membership: * SkyAxis member function. * Description: * This function returns a gap size in radians which produces a * nicely spaced series of formatted SkyAxis values, 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: * fmt * Pointer to a constant null-terminated string containing the * format specifier which will be used to format the SkyAxis * values. * digs * The default number of digits of precision to use. This is used * if the given format specifier indicates the number of decimal * places to use with the string ".*". In this case, the number of * decimal places produced will be chosen so that the total number * of digits of precision is equal to "digs". * 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 Constants: */ #define BUFF_LEN 50 /* Length of character buffer */ /* Local Variables: */ char buff[ BUFF_LEN + 1 ]; /* Buffer for formatted scaled "nice" value */ char sep; /* Field separator character */ const double *table; /* Pointer to nice gap table */ const int *nticks; /* Pointer to number of subdivisions table */ double field_value[ 3 ]; /* Formatted field values in radians */ double scale; /* Power of ten scaling factor */ double scaled_table_value; /* Scaled "nice" value to test against */ int as_time; /* Format the value as a time? */ int decimal; /* Use nice decimal gap value? */ int dh; /* Degrees/hours field required? */ int field; /* ID of most significant formatted field */ int i; /* Look-up-table index */ int iter; /* Iteration count */ int lead_zero; /* Add leading zeros? */ int min; /* Minutes field required? */ int ndp; /* Number of decimal places */ int plus; /* Add leading plus sign? */ int positive; /* Value is positive (or zero)? */ int sec; /* Seconds field required? */ /* Local Data: */ /* ----------- */ /* Table of nice decimal gaps. */ const double dec_table[] = { 1.0, 2.0, 5.0, 5.0, 10.0, -1.0 }; const int dec_nticks[] = { 5, 4, 5, 5, 5 }; /* Table of nice degrees gaps. */ const double deg_table[] = { 1.0, 2.0, 5.0, 10.0, 30.0, 45.0, 60.0, 90.0, 180.0, 360.0, -1.0 }; const int deg_nticks[] = { 4, 4, 5, 5, 6, 3, 6, 3, 3, 4 }; /* Table of nice hours gaps. */ const double hr_table[] = { 1.0, 2.0, 3.0, 6.0, 12.0, 24.0, -1.0 }; const int hr_nticks[] = { 4, 4, 6, 6, 4, 4 }; /* Table of nice minutes or seconds gaps. */ const double minsec_table[] = { 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, -1.0 }; const int minsec_nticks[] = { 4, 4, 5, 5, 6, 4 }; /* Check the global error status. */ if ( !astOK ) return 0.0; /* Check that the supplied gap size is not zero. */ if ( gap != 0.0 ) { /* Parse the format specifier. */ ParseDHmsFormat( fmt, digs, &sep, &plus, &lead_zero, &as_time, &dh, &min, &sec, &ndp, status ); /* If OK, calculate the value of each formatted field in radians. */ if ( astOK ) { field_value[ 0 ] = ( as_time ? hr2rad : deg2rad ); field_value[ 1 ] = field_value[ 0 ] / 60.0; field_value[ 2 ] = field_value[ 0 ] / 3600.0; /* Determine if the suggested gap size is positive and obtain its absolute value. */ positive = ( gap >= 0.0 ); if ( !positive ) gap = -gap; /* Perform two iterations to determine the optimum gap value. This is because the method of choosing the gap value depends on the initial value. If a nice decimal gap is chosen on the first iteration, this may round the suggested gap value downwards, making it preferable to choose the gap value using a different method on the second iteration. */ for ( iter = 0; iter < 2; iter++ ) { /* Decide which is the most significant field that the suggested gap value will occupy when formatted. Also decide whether to use a special "nice" gap value specific to that field, or simply to use a generic nice decimal gap value. Perform all tests on the gap size in radians, so as to avoid any rounding problems from conversion into degrees/hours, minutes or seconds. */ decimal = 0; /* Suggested values exceeding one degree/hour. */ /* ------------------------------------------- */ if ( gap > field_value[ 0 ] ) { /* If a degree/hour field is present, use a special gap value, unless the suggested value exceeds the normal range of this field (in which case use a decimal gap). */ if ( dh ) { field = 1; decimal = ( gap > ( field_value[ 0 ] * ( as_time ? 24.0 : 360.0 ) ) ); /* If the most significant field is not degrees/hours, then its normal range will be exceeded, so use a decimal gap. */ } else if ( min ) { field = 2; decimal = 1; } else { field = 3; decimal = 1; } /* Suggested values exceeding one minute. */ /* -------------------------------------- */ } else if ( gap > field_value[ 1 ] ) { /* If a minutes field is present, the suggested value will lie within its normal range, so use a special gap value. */ if ( min ) { field = 2; /* Otherwise, if the most significant field is seconds, its normal range will be exceeded, so use a decimal gap value. */ } else if ( sec ) { field = 3; decimal = 1; /* If only a degrees/hours field is present, then only digits after the decimal point can be affected, so use a decimal gap value. */ } else { field = 1; decimal = 1; } /* Suggested values exceeding one second. */ /* -------------------------------------- */ } else if ( gap > field_value[ 2 ] ) { /* If a seconds field is present, the suggested value will lie within its normal range, so use a special gap value. */ if ( sec ) { field = 3; /* If the least significant field is degrees/hours or minutes, then only digits after the decimal point can be affected, so use a decimal gap value. */ } else if ( min ) { field = 2; decimal = 1; } else { field = 1; decimal = 1; } /* Suggested values less than one second. */ /* -------------------------------------- */ } else { /* Only digits after the decimal point can be affected, so decide which is the least significant field present and use a decimal gap. */ if ( sec ) { field = 3; } else if ( min ) { field = 2; } else { field = 1; } decimal = 1; } /* If a decimal gap value is required, select the appropriate table of gap values and numbers of subdivisions. */ if ( decimal ) { table = dec_table; nticks = dec_nticks; /* Find a power of ten divisor which scales the suggested value (when formatted) into the range 1.0 to 10.0. */ scale = pow( 10.0, floor( log10( gap / field_value[ field - 1 ] ) ) ); /* Look the scaled value up in the table, comparing values in radians to avoid rounding problems due to conversion to/from degrees/radians, etc. */ for ( i = 0; table[ i + 1 ] > 0.0; i++ ) { /* We must be careful about rounding errors here. If, for example, we read in a value of 0.15 as the suggested gap value, the scaled "nice" value we would be comparing it with would be 0.1 times the values in the nice values table. The relevant value in this table is 1.5 (i.e. 0.5 * ( 1.0 + 2.0 ) ), so we would compute 0.1 * 1.5 as the test value. However, this is probably not equal (to machine precision) to the number that results when a formatted value of 0.15 is read, because 0.1 isn't exactly representable. Since it is the formatted appearance of the numbers which matters, we want a new scaled nice table containing the numbers that result from reading the formatted values 0.1, 0.2, etc. To achieve this effect, we format the scaled table value using the default floating point precision (which rounds to a relatively small number of decimal digits) and then read the value back again. */ (void ) sprintf( buff, "%g", scale * 0.5 * ( table[ i ] + table[ i + 1 ] ) ); (void) astSscanf( buff, "%lf", &scaled_table_value ); /* Now test the suggested gap value against the scaled table value. */ if ( gap < ( field_value[ field - 1 ] * scaled_table_value ) ) break; } /* Return the nice gap value and the number of subdivisions. */ gap = scale * field_value[ field - 1 ] * table[ i ]; if ( ntick ) *ntick = nticks[ i ]; /* If a special gap value appropriate to the field is required, then select the table of gap values and numbers of subdivisions according to which field we are considering and whether it contains degrees or hours. */ } else { if ( field == 1 ) { if ( as_time ) { table = hr_table; nticks = hr_nticks; } else { table = deg_table; nticks = deg_nticks; } } else { table = minsec_table; nticks = minsec_nticks; } /* Search the table for a suitable gap. We do not need to format and unformat the test value here (as we did above) because the table values are being used literally and not being scaled. */ for ( i = 0; table[ i + 1 ] > 0.0; i++ ) { if ( gap < ( field_value[ field - 1 ] * 0.5 * ( table[ i ] + table[ i + 1 ] ) ) ) break; } /* Return the nice gap value and the number of subdivisions. */ gap = field_value[ field - 1 ] * table[ i ]; if ( ntick ) *ntick = nticks[ i ]; } } /* After iterations are complete, restore the original sign. */ if ( !positive ) gap = -gap; } } /* If an error occurred, clear the returned value. */ if ( !astOK ) gap = 0.0; /* Return the result. */ return gap; /* Undefine macros local to this function */ #undef BUFF_LEN } static const char *DHmsUnit( const char *fmt, int digs, int output, int *status ) { /* * Name: * DHmsUnit * Purpose: * Generate a unit string to describe a formatted angle or time. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *DHmsUnit( const char *fmt, int digs, int output, int *status ) * Class Membership: * SkyAxis member function. * Description: * This function generates a string that may be used to describe * either (a) the units of an angle or time that has been formatted * for output using the DHmsFormat function, or (b) a suitable * format to be used for an angle or time that is to be supplied as * an input coordinate value. * Parameters: * fmt * Pointer to a null terminated string containing the format * specifier used to format coordinate values. For details of * the syntax of this string, see the DHmsFormat function. * digs * The default number of digits of precision to use. This is used * if the given format specifier indicates the number of decimal * places to use with the string ".*". In this case, the number of * decimal places produced will be chosen so that the total number * of digits of precision is equal to "digs". * output * If non-zero, the returned string will be in a form suitable * for describing the units/format of output produced using * DHmsFormat. * * If zero, the returned string will be in a form suitable for * describing a suggested input format, which will subsequently * be read using AxisUnformat. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to a null terminated string containing the unit description. * Notes: * - The result string may be stored in static memory. Its contents * may be over-written or the returned pointer may become invalid * following a further invocation of this function. A copy of the * string should therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ char dpchar; /* Character to indicate decimal places */ char sep; /* Field separator character */ const char *result; /* Pointer to result string */ const int maxdp = 6; /* Maximum number of decimal places to show */ int as_time; /* Value formatted as a time? */ int dh; /* Degrees/hours field required? */ int dp; /* Loop counter for decimal places */ int lead_zero; /* Add leading zeros? */ int min; /* Minutes field required? */ int ndp; /* Number of decimal places */ int plus; /* Leading plus sign required? */ int pos; /* Position to add next character */ int sec; /* Seconds field required? */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Parse the format specifier. */ ParseDHmsFormat( fmt, digs, &sep, &plus, &lead_zero, &as_time, &dh, &min, &sec, &ndp, status ); /* If the units string is required to describe formatted output and the field separators are letters (e.g. giving "01h23m45s" or "012d34m56s"), then the units will already be clear so return a pointer to an empty units string. */ if ( astOK ) { if ( output && ( sep == 'l' || sep == 'g' ) ) { result = ""; /* Otherwise, if the units string is required to describe formatted output and there is only one field present, then select an appropriate string. */ } else if ( output && dh && !min && !sec ) { result = as_time ? "hours" : "degrees"; } else if ( output && !dh && min && !sec ) { result = as_time ? "minutes of time" : "arcminutes"; } else if ( output && !dh && !min && sec ) { result = as_time ? "seconds of time" : "arcseconds"; /* If there is more than one field present, or we want to describe how to supply formatted input, then we will generate a units string of the general form "ddd:mm:ss.sss" or "hh:mm:ss.s" or similar. Initialise the output character count and the character to be used to represent decimal places. */ } else { pos = 0; dpchar = 'd'; /* Decide which field separator to use (use a space if letters were requested since it is easier to input). */ if ( sep == 'l' || sep == 'g' ) sep = ' '; /* Start with the "ddd" or "hh" field, if required, and update the decimal places character appropriately. */ if ( dh ) { pos += sprintf( dhmsunit_buff, "%s", as_time ? "hh" : "ddd" ); dpchar = as_time ? 'h' : 'd'; } /* If a minutes field is present, add a separator if necessary and "mm" and update the decimal places character. */ if ( min ) { if ( dh ) dhmsunit_buff[ pos++ ] = sep; dhmsunit_buff[ pos++ ] = 'm'; dhmsunit_buff[ pos++ ] = 'm'; dpchar = 'm'; } /* Repeat this process for the seconds field, if present. */ if ( sec ) { if ( dh || min ) dhmsunit_buff[ pos++ ] = sep; dhmsunit_buff[ pos++ ] = 's'; dhmsunit_buff[ pos++ ] = 's'; dpchar = 's'; } /* If decimal places are present, add a decimal point and then loop to add further instances of the decimal places character to represent the digits that follow. */ if ( ndp > 0 ) { dhmsunit_buff[ pos++ ] = '.'; for ( dp = 0; dp < ndp; dp++ ) { if ( dp < maxdp ) { dhmsunit_buff[ pos++ ] = dpchar; /* After showing the maximum number of decimal places, simply add an ellipsis and quit (otherwise the result gets boring to look at). */ } else { dhmsunit_buff[ pos - 1 ] = '.'; dhmsunit_buff[ pos - 2 ] = '.'; dhmsunit_buff[ pos - 3 ] = '.'; break; } } } /* Terminate the result string and return a pointer to it. */ dhmsunit_buff[ pos ] = '\0'; result = dhmsunit_buff; } } /* Return the result. */ return result; } static int GetObjSize( AstObject *this_object, int *status ) { /* * Name: * GetObjSize * Purpose: * Return the in-memory size of an Object. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int GetObjSize( AstObject *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetObjSize protected * method inherited from the parent class). * Description: * This function returns the in-memory size of the supplied SkyAxis, * in bytes. * Parameters: * this * Pointer to the SkyAxis. * 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: */ AstSkyAxis *this; /* Pointer to SkyAxis structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointers to the SkyAxis structure. */ this = (AstSkyAxis *) this_object; /* Invoke the GetObjSize method inherited from the parent class, and then add on any components of the class structure defined by thsi class which are stored in dynamically allocated memory. */ result = (*parent_getobjsize)( this_object, status ); result += astTSizeOf( this->skyformat ); /* 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 SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *GetAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyAxis member function (over-rides the protected astGetAttrib * method inherited from the Axis class). * Description: * This function returns a pointer to the value of a specified * attribute for a SkyAxis, formatted as a character string. * Parameters: * this * Pointer to the SkyAxis. * 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 SkyAxis, 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 SkyAxis. A copy of the string should * therefore be made if necessary. * - A NULL pointer will be returned if this function is invoked * with the global error status set, or if it should fail for any * reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *result; /* Pointer value to return */ int as_time; /* AsTime attribute value */ int centrezero; /* CentreZero attribute value */ int is_latitude; /* IsLatitude attribute value */ /* Initialise. */ result = NULL; /* Check the global error status. */ if ( !astOK ) return result; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_object); /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) 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. */ /* AsTime. */ /* ------- */ if ( !strcmp( attrib, "astime" ) ) { as_time = astGetAxisAsTime( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", as_time ); result = getattrib_buff; } /* IsLatitude. */ /* ----------- */ } else if ( !strcmp( attrib, "islatitude" ) ) { is_latitude = astGetAxisIsLatitude( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", is_latitude ); result = getattrib_buff; } /* CentreZero. */ /* ----------- */ } else if ( !strcmp( attrib, "centrezero" ) ) { centrezero= astGetAxisCentreZero( this ); if ( astOK ) { (void) sprintf( getattrib_buff, "%d", centrezero ); result = getattrib_buff; } /* If the attribute name was not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_getattrib)( this_object, attrib, status ); } /* Return the result. */ return result; } static double GetAxisBottom( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisBottom * Purpose: * Obtain the value of the Bottom attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * double GetAxisBottom( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisBottom method * inherited from the Axis class). * Description: * This function returns a value for the Bottom attribute of a SkyAxis. * This attribute indicates the lowest legal value for the axis. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * The atribute value. A suitable default value is supplied if necessary. * Notes: * - A value of -DBL_MAX will be returned if this function is invoked * with the global error status set, or if it should fail for any reason. */ /* Local Variables. */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ double result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return -DBL_MAX; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Check if a value has been set for the Bottom attribute. If so, obtain this value. */ if ( astTestAxisBottom( this ) ) { result = (*parent_getaxisbottom)( this_axis, status ); /* Otherwise, supply a default of -pi/2 for latitude axes, and -DBL_MAX for longitude axes. */ } else { result = astGetAxisIsLatitude( this ) ? -piby2 : -DBL_MAX; } /* If an error occurred, clear the result value. */ if ( !astOK ) result = -DBL_MAX; /* Return the result. */ return result; } static const char *GetAxisInternalUnit( AstAxis *this, int *status ){ /* * Name: * GetAxisInternalUnit * Purpose: * Return the unit string for unformatted Axis values * Type: * Private function. * Synopsis: * #include "axis.h" * const char *GetAxisInternalUnit( AstAxis *this ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisInternalUnit method * inherited from the Axis class). * Description: * This function returns the axis InternalUnit attribute. For sky * axes, the InternalUnit is always "rad" (radians). * Parameters: * this * Pointer to the Axis. * Returned Value: * - Pointer to a null-terminated string containing the internal * unit string. * Notes: * - The returned pointer points to a static memory buffer. The * contents of this buffer will be over-written on each invocation of * this function. A copy of the returned string should therefore be * taken if it will be needed later. * - 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. */ return "rad"; } static double GetAxisTop( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisTop * Purpose: * Obtain the value of the Top attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * double GetAxisTop( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisTop method * inherited from the Axis class). * Description: * This function returns a value for the Top attribute of a SkyAxis. * This attribute indicates the highest legal value for the axis. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * The atribute value. A suitable default value is supplied if necessary. * Notes: * - A value of DBL_MAX will be returned if this function is invoked * with the global error status set, or if it should fail for any reason. */ /* Local Variables. */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ double result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return DBL_MAX; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Check if a value has been set for the Top attribute. If so, obtain this value. */ if ( astTestAxisTop( this ) ) { result = (*parent_getaxistop)( this_axis, status ); /* Otherwise, supply a default of pi/2 for latitude axes, and DBL_MAX for longitude axes. */ } else { result = astGetAxisIsLatitude( this ) ? piby2 : DBL_MAX; } /* If an error occurred, clear the result value. */ if ( !astOK ) result = DBL_MAX; /* Return the result. */ return result; } static int GetAxisDirection( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisDirection * Purpose: * Obtain the value of the Direction attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int GetAxisDirection( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisDirection method * inherited from the Axis class). * Description: * This function returns a value for the Direction attribute of a SkyAxis. * This attribute indicates in which direction the SkyAxis's values should * increase when represented on a graph (1 for the conventional direction, * 0 for reverse direction). * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Zero or one, according to the attribute setting. A suitable default * value is supplied if necessary. * 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. */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Check if a value has been set for the Direction attribute. If so, obtain this value. */ if ( astTestAxisDirection( this ) ) { result = (*parent_getaxisdirection)( this_axis, status ); /* Otherwise, supply a default of 1 unless the SkyAxis values are being formatted as times (instead of angles) by default. */ } else { result = !astGetAxisAsTime( this ); } /* If an error occurred, clear the result value. */ if ( !astOK ) result = 0; /* Return the result. */ return result; } static const char *GetAxisFormat( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisFormat * Purpose: * Obtain a pointer to the Format attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *GetAxisFormat( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisFormat method inherited * from the Axis class). * Description: * This function returns a pointer to the Format attribute associated with * a SkyAxis and provides a suitable default if necessary. This string * attribute contains the format specifier that will be interpreted by the * astAxisFormat method when formatting a value for the SkyAxis. The default * Format may depend on other attribute settings, in particular on the * Digits and AsTime attributes. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Format string (null terminated). * Notes: * - The pointer returned may point at memory allocated within the SkyAxis * 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, deletion of the SkyAxis, or assignment * of a new Format value. A copy of the string should therefore be made if * necessary. * - This function will return a NULL pointer if it is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *result; /* Pointer to result string */ int as_time; /* Format SkyAxis values as times? */ int digits; /* Number of digits of precision */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(this_axis); /* Initialise. */ result = NULL; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Obtain a pointer to the Format string stored in the SkyAxis structure. Note we do not use a method to obtain this, because we want a string with a syntax appropriate to this class, and derived classes may have extended the syntax. */ result = this->skyformat; /* If no Format string has been set, we must generate a default one. Determine how many digits of precision are to be used by default and whether the SkyAxis values are to be formatted as times (instead of angles). */ if ( !result ) { digits = astGetAxisDigits( this ); as_time = astGetAxisAsTime( this ); if ( astOK ) { /* If formatting values as times, use the number of digits to select an appropriate Format string and obtain a pointer to it. */ if ( as_time ) { if ( digits <= 2 ) { result = "h"; } else if ( digits == 3 ) { result = "hm"; } else if ( digits == 4 ) { result = "hm"; } else if ( digits == 5 ) { result = "hms"; } else if ( digits == 6 ) { result = "hms"; /* Construct the Format string in a buffer if necessary. */ } else { (void) sprintf( getaxisformat_buff, "hms.%d", digits - 6 ); result = getaxisformat_buff; } /* Similarly, select a Format for expressing an angle if necessary. */ } else { if ( digits <= 3 ) { result = "d"; } else if ( digits == 4 ) { result = "dm"; } else if ( digits == 5 ) { result = "dm"; } else if ( digits == 6 ) { result = "dms"; } else if ( digits == 7 ) { result = "dms"; } else { (void) sprintf( getaxisformat_buff, "dms.%d", digits - 7 ); result = getaxisformat_buff; } } } } /* Return the result. */ return result; } static const char *GetAxisLabel( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisLabel * Purpose: * Obtain a pointer to the Label attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *GetAxisLabel( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisLabel method inherited * from the Axis class). * Description: * This function returns a pointer to the Label attribute associated with * a SkyAxis and provides a suitable default if necessary. This string * attribute specifies the label to be attached to the SkyAxis when it is * represented in (e.g.) a graph. It is intended purely for interpretation * by human readers and not by software. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Label string (null terminated). * Notes: * - The pointer returned may point at memory allocated within the SkyAxis * 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, deletion of the SkyAxis, or assignment * of a new Label value. A copy of the string should therefore be made if * necessary. * - This function will return a NULL pointer if it is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *result; /* Pointer value to be returned */ int as_time; /* SkyAxis values formatted as times? */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise. */ result = NULL; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Test if the Label attribute is set. If so, use the parent astGetAxisLabel method to get a pointer to it. */ if ( astTestAxisLabel( this ) ) { result = (*parent_getaxislabel)( this_axis, status ); /* Otherwise, return a pointer to a suitable default string, using the result of the astGetAxisAsTime method to determine whether a string describing time or angle is more appropriate. */ } else { as_time = astGetAxisAsTime( this ); if ( !astTestAxisIsLatitude( this ) ) { result = as_time ? "Angle on sky expressed as time" : "Angle on sky"; } else if ( astGetAxisIsLatitude( this ) ) { result = as_time ? "Sky latitude expressed as time" : "Sky latitude"; } else { result = as_time ? "Sky longitude expressed as time" : "Sky longitude"; } } /* If an error occurred, clear the result pointer. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static const char *GetAxisSymbol( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisSymbol * Purpose: * Obtain a pointer to the Symbol attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *GetAxisSymbol( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisSymbol method inherited * from the Axis class). * Description: * This function returns a pointer to the Symbol attribute associated with * a SkyAxis and provides a suitable default if necessary. This string * attribute specifies the symbol to be used to represent coordinate values * for the SkyAxis in "short form", such as in algebraic expressions where a * full description would be inappropriate. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Symbol string (null terminated). * Notes: * - The pointer returned may point at memory allocated within the SkyAxis * 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, deletion of the SkyAxis, or assignment * of a new Symbol value. A copy of the string should therefore be made if * necessary. * - This function will return a NULL pointer if it is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *result; /* Pointer value to return */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise. */ result = NULL; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Test if the Symbol attribute is set. If so, use the parent astGetAxisSymbol method to get a pointer to it. */ if ( astTestAxisSymbol( this ) ) { result = (*parent_getaxissymbol)( this_axis, status ); /* If a value has been set for the IsLatitude attribute, use it to decide whether to use "delta" (for latitude) or "alpha" (for longitude). */ } else if ( astTestAxisIsLatitude( this ) ) { result = astGetAxisIsLatitude( this ) ? "delta" : "alpha"; /* Otherwise, use the AsTime attribute to decide whether the SkyAxis is likely to be a longitude or latitude axis (the former usually having values formatted as times). */ } else { result = astGetAxisAsTime( this ) ? "alpha" : "delta"; } /* If an error occurred, clear the result pointer. */ if ( !astOK ) result = NULL; /* Return the result. */ return result; } static const char *GetAxisUnit( AstAxis *this_axis, int *status ) { /* * Name: * GetAxisUnit * Purpose: * Obtain a pointer to the Unit attribute for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * const char *GetAxisUnit( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astGetAxisUnit method inherited * from the Axis class). * Description: * This function returns a pointer to the Unit attribute associated with * a SkyAxis and provides a suitable default if necessary. This string * attribute describes the unit used to represent formatted coordinate * values on the SkyAxis. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Pointer to the Unit string (null terminated). * Notes: * - The pointer returned may point at memory allocated within the SkyAxis * 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, deletion of the SkyAxis, or assignment * of a new Unit value. A copy of the string should therefore be made if * necessary. * - This function will return a NULL pointer if it is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *fmt; /* Pointer to format specifier */ const char *result; /* Pointer to result string */ /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise */ result = NULL; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Test if the Unit attribute is set. If so, invoke the parent astGetAxisUnit method to obtain a pointer to it. */ if ( astTestAxisUnit( this ) ) { result = (*parent_getaxisunit)( this_axis, status ); /* If we must provide a default, obtain a pointer to the format specifier used to format SkyAxis values. Use a private member function (not a method) to access this, in case derived classes have extended the syntax of this string. */ } else { fmt = GetAxisFormat( this_axis, status ); /* If the format string starts with a percent, use "rad" as the default units string. Otherwise, use the format specifier to generate a matching default Unit string and obtain a pointer to it. */ if ( astOK ) { if( fmt[ 0 ] == '%' ) { result = "rad"; } else { result = DHmsUnit( fmt, astGetAxisDigits( this_axis ), 1, status ); } } } /* Return the result. */ return result; } void astInitSkyAxisVtab_( AstSkyAxisVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSkyAxisVtab * Purpose: * Initialise a virtual function table for a SkyAxis. * Type: * Protected function. * Synopsis: * #include "skyaxis.h" * void astInitSkyAxisVtab( AstSkyAxisVtab *vtab, const char *name ) * Class Membership: * SkyAxis vtab initialiser. * Description: * This function initialises the component of a virtual function * table which is used by the SkyAxis 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 */ AstAxisVtab *axis; /* Pointer to Axis component of Vtab */ AstObjectVtab *object; /* Pointer to Object component of Vtab */ int stat; /* SLALIB status */ /* 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. */ astInitAxisVtab( (AstAxisVtab *) vtab, name ); /* Store a unique "magic" value in the virtual function table. This will be used (by astIsASkyAxis) 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 = &(((AstAxisVtab *) vtab)->id); /* Initialise member function pointers. */ /* ------------------------------------ */ /* Store pointers to the member functions (implemented here) that provide virtual methods for this class. */ vtab->ClearAxisAsTime = ClearAxisAsTime; vtab->ClearAxisIsLatitude = ClearAxisIsLatitude; vtab->ClearAxisCentreZero = ClearAxisCentreZero; vtab->GetAxisAsTime = GetAxisAsTime; vtab->GetAxisIsLatitude = GetAxisIsLatitude; vtab->GetAxisCentreZero = GetAxisCentreZero; vtab->SetAxisAsTime = SetAxisAsTime; vtab->SetAxisIsLatitude = SetAxisIsLatitude; vtab->SetAxisCentreZero = SetAxisCentreZero; vtab->TestAxisAsTime = TestAxisAsTime; vtab->TestAxisIsLatitude = TestAxisIsLatitude; vtab->TestAxisCentreZero = TestAxisCentreZero; /* Save the inherited pointers to methods that will be extended, and replace them with pointers to the new member functions. */ object = (AstObjectVtab *) vtab; axis = (AstAxisVtab *) vtab; parent_getobjsize = object->GetObjSize; object->GetObjSize = GetObjSize; parent_clearattrib = object->ClearAttrib; object->ClearAttrib = ClearAttrib; parent_getattrib = object->GetAttrib; object->GetAttrib = GetAttrib; parent_setattrib = object->SetAttrib; object->SetAttrib = SetAttrib; parent_testattrib = object->TestAttrib; object->TestAttrib = TestAttrib; parent_axisoverlay = axis->AxisOverlay; axis->AxisOverlay = AxisOverlay; parent_getaxisdirection = axis->GetAxisDirection; axis->GetAxisDirection = GetAxisDirection; parent_getaxislabel = axis->GetAxisLabel; axis->GetAxisLabel = GetAxisLabel; parent_getaxissymbol = axis->GetAxisSymbol; axis->GetAxisSymbol = GetAxisSymbol; parent_getaxisunit = axis->GetAxisUnit; axis->GetAxisUnit = GetAxisUnit; parent_getaxistop = axis->GetAxisTop; axis->GetAxisTop = GetAxisTop; parent_getaxisbottom = axis->GetAxisBottom; axis->GetAxisBottom = GetAxisBottom; parent_axisformat = axis->AxisFormat; axis->AxisFormat = AxisFormat; parent_axisunformat = axis->AxisUnformat; axis->AxisUnformat = AxisUnformat; parent_axisgap = axis->AxisGap; axis->AxisGap = AxisGap; parent_axisfields = axis->AxisFields; axis->AxisFields = AxisFields; /* Store replacement pointers for methods which will be over-ridden by new member functions implemented here. */ axis->AxisAbbrev = AxisAbbrev; axis->AxisIn = AxisIn; axis->AxisDistance = AxisDistance; axis->AxisOffset = AxisOffset; axis->AxisNorm = AxisNorm; axis->AxisNormValues = AxisNormValues; axis->ClearAxisFormat = ClearAxisFormat; axis->GetAxisFormat = GetAxisFormat; axis->SetAxisFormat = SetAxisFormat; axis->TestAxisFormat = TestAxisFormat; axis->GetAxisInternalUnit = GetAxisInternalUnit; axis->TestAxisInternalUnit = TestAxisInternalUnit; /* Declare the destructor, copy constructor and dump function. */ astSetDelete( vtab, Delete ); astSetCopy( vtab, Copy ); astSetDump( vtab, Dump, "SkyAxis", "Celestial coordinate axis" ); /* Initialize constants for converting between hours, degrees and radians. */ LOCK_MUTEX2 palDtf2r( 1, 0, 0.0, &hr2rad, &stat ); palDaf2r( 1, 0, 0.0, °2rad, &stat ); palDaf2r( 180, 0, 0.0, &pi, &stat ); piby2 = 0.5*pi; UNLOCK_MUTEX2 /* 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 ParseDHmsFormat( const char *fmt, int digs, char *sep, int *plus, int *lead_zero, int *as_time, int *dh, int *min, int *sec, int *ndp, int *status ) { /* * Name: * ParseDHmsFormat * Purpose: * Parse a format specifier for degrees/hours, minutes and seconds. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void ParseDHmsFormat( const char *fmt, int digs, char *sep, int *plus, * int *lead_zero, int *as_time, int *dh, int *min, * int *sec, int *ndp, int *status ) * Class Membership: * SkyAxis member function. * Description: * This function parses a SkyAxis format specifier which describes * how to convert an angle in radians into a text string with * separate fields for degrees/hours, minutes and seconds. * Parameters: * fmt * Pointer to a null terminated string containing the format * specifier. For details of the syntax of this string, see the * DHmsFormat function. * digs * The default number of digits of precision to use. This is used * if the given format specifier indicates the number of decimal * places to use with the string ".*". In this case, the returned * value for "ndp" will be set to produce the number of digits of * precision given by "digs". * sep * Pointer to a location in which a single character will be * returned to indicate which separator should be used to * separate the fields. The returned value will be one of ' ' * (use a blank as the separator), ':' (use a colon as the * separator) or 'l' (use one of the letters "hdms" as * appropriate) or 'g' (use one of the letters "hdms" but * include suitable escape sequences to allow the Plot class to draw * the letter as a small super-script). * plus * Pointer to an int in which a boolean value will be returned * to indicate if a plus sign should be prefixed to positive * values. * lead_zero * Pointer to an int in which a boolean value will be returned * to indicate if leading zeros should be prefixed to the value * so that the first field is always of constant (maximum) * width, as would be required in a fixed-width table. Leading * zeros are always prefixed to any fields that follow. * as_time * Pointer to an int in which a boolean value will be returned * to indicate whether the value is to be formatted as a time * (e.g. in hours) rather than as an angle (in degrees). * dh * Pointer to an int in which a boolean value will be returned * to indicate whether a degrees or hours field is required. * min * Pointer to an int in which a boolean value will be returned * to indicate whether a minutes field is required. * sec * Pointer to an int in which a boolean value will be returned * to indicate whether a seconds field is required. * ndp * Pointer to an int in which to return the number of digits * required following the decimal point in the final field. A * value of zero indicates that the decimal point should be * omitted. See parameter "digs". * status * Pointer to the inherited status variable. * Returned Value: * void * Acknowledgements: * - This function is a close approximation to a Fortran 77 routine * written by Clive Davenhall which implements the system of format * specifiers for angles described in his document on the CAT * catalogue access library (Starlink User Note 181). It supports * the same format specifiers. */ /* Local Variables: */ int decpos; /* Offset of decimal point */ int i; /* Loop counter for format characters */ int ndpval; /* Number of decimal places required */ /* Check the global error status. */ if ( !astOK ) return; /* Initialise. */ *as_time = -1; *lead_zero = 0; *dh = 0; *min = 0; *ndp = 0; *plus = 0; *sec = 0; *sep = ':'; decpos = -1; /* Loop to inspect and classify each character. */ for ( i = 0; fmt[ i ]; i++ ) { switch ( fmt[ i ] ) { /* Note if a '+' sign is needed. */ case '+': *plus = 1; break; /* Note if leading zeros are needed. */ case 'Z': case 'z': *lead_zero = 1; break; /* Set the required separator. Note we only use graphical separators if astEscapes indicates that escape sequences are currently being used. */ case 'I': case 'i': *sep = ':'; break; case 'B': case 'b': *sep = ' '; break; case 'L': case 'l': *sep = 'l'; break; case 'G': case 'g': *sep = astEscapes( -1 ) ? 'g' : 'l'; break; /* Note if the value is to be formatted as a time (but not if a degrees or hours field has already been specified). */ case 'T': case 't': if ( *as_time == -1 ) *as_time = 1; break; /* Note if a degrees or hours field is required (and hence whether the value is to be formatted as a time or an angle). */ case 'H': case 'h': *dh = 1; *as_time = 1; break; case 'D': case 'd': *dh = 1; *as_time = 0; break; /* Note if a minutes field is required. */ case 'M': case 'm': *min = 1; break; /* Note if a seconds field is required. */ case 'S': case 's': *sec = 1; break; /* Note if decimal places are required. */ case '.': decpos = i; } } /* Format the value as an angle by default. */ if ( *as_time == -1 ) *as_time = 0; /* Use degrees (or hours) as the default field. */ if ( !*min && !*sec ) *dh = 1; /* Omit the seconds field if the degrees/hours field is present but the minutes field is not. */ if ( *dh && !*min ) *sec = 0; /* Determine the default number of decimal places following the final field. This is the number which will be used if the format specifier does not indicate how many decimal places should be produced. It is shosen to produce the requested total number of digits of precision. */ /* If decimal places are required, attempt to read the integer value following the decimal point which specifies how many. If successful, and a valid (positive or zero) result was obtained, note its value. If an asterisk follows the decimal point, use a value determined by the supplied "digs" value. */ if ( ( decpos >= 0 ) && ( decpos < ( i - 1 ) ) ) { if ( astSscanf( fmt + decpos + 1, "%d", &ndpval ) == 1 ) { if ( ndpval >= 0 ) *ndp = ndpval; } else if ( fmt[ decpos + 1 ] == '*' ) { *ndp = digs; if( *as_time ) { *ndp = ( digs > 2 ) ? digs : 2; if( *dh ) *ndp -= 2; } else { *ndp = ( digs > 3 ) ? digs : 3; if( *dh ) *ndp -= 3; } if( *min ) *ndp -= 2; if( *sec ) *ndp -= 2; if( *ndp < 0 ) *ndp = 0; } } } static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { /* * Name: * SetAttrib * Purpose: * Set an attribute value for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void SetAttrib( AstObject *this, const char *setting, int *status ) * Class Membership: * SkyAxis member function (over-rides the astSetAttrib method * inherited from the Axis class). * Description: * This function assigns an attribute value for a SkyAxis, 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 SkyAxis. * setting * Pointer to a null terminated string specifying the new * attribute value. * status * Pointer to the inherited status variable. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ int as_time; /* Format values as times? */ int centrezero; /* SkyAxis range centred on zero? */ int is_latitude; /* SkyAxis is a latitude axis? */ int len; /* Length of setting string */ int nc; /* Number of characters read by astSscanf */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_object; /* Obtain the length of the setting string. */ len = (int) 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. */ /* AsTime. */ /* ------- */ if ( nc = 0, ( 1 == astSscanf( setting, "astime= %d %n", &as_time, &nc ) ) && ( nc >= len ) ) { astSetAxisAsTime( this, as_time ); /* IsLatitude. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "islatitude= %d %n", &is_latitude, &nc ) ) && ( nc >= len ) ) { astSetAxisIsLatitude( this, is_latitude ); /* CentreZero. */ /* ----------- */ } else if ( nc = 0, ( 1 == astSscanf( setting, "centrezero= %d %n", ¢rezero, &nc ) ) && ( nc >= len ) ) { astSetAxisCentreZero( this, centrezero ); /* Pass any unrecognised attribute setting to the parent method for further interpretation. */ } else { (*parent_setattrib)( this_object, setting, status ); } } static void SetAxisFormat( AstAxis *this_axis, const char *format, int *status ) { /* * Name: * SetAxisFormat * Purpose: * Set a value for the Format attribute of a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * void SetAxisFormat( AstAxis *this, const char *format ) * Class Membership: * SkyAxis member function (over-rides the astSetAxisFormat method inherited * from the Axis class). * Description: * This function sets a new value for the Format attribute of a SkyAxis. * Parameters: * this * Pointer to the SkyAxis. * format * Pointer to a null terminated string containing the new Format value. * Returned Value: * void * Notes: * - For details of the syntax of the Format string, see the DHmsFormat * function. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* Store a pointer to a copy of the Format string in the SkyAxis structure. */ this->skyformat = astStore( this->skyformat, format, strlen( format ) + (size_t) 1 ); } static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { /* * Name: * TestAttrib * Purpose: * Test if a specified attribute value is set for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int TestAttrib( AstObject *this, const char *attrib, int *status ) * Class Membership: * SkyAxis member function (over-rides the astTestAttrib protected * method inherited from the Axis class). * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for one of a SkyAxis' attributes. * Parameters: * this * Pointer to the SkyAxis. * 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: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ int result; /* Result value to return */ /* Initialise. */ result = 0; /* Check the global error status. */ if ( !astOK ) return result; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_object; /* Check the attribute name and test the appropriate attribute. */ /* AsTime. */ /* ------- */ if ( !strcmp( attrib, "astime" ) ) { result = astTestAxisAsTime( this ); /* IsLatitude. */ /* ----------- */ } else if ( !strcmp( attrib, "islatitude" ) ) { result = astTestAxisIsLatitude( this ); /* CentreZero. */ /* ----------- */ } else if ( !strcmp( attrib, "centrezero" ) ) { result = astTestAxisCentreZero( this ); /* If the attribute is still not recognised, pass it on to the parent method for further interpretation. */ } else { result = (*parent_testattrib)( this_object, attrib, status ); } /* Return the result, */ return result; } static int TestAxisFormat( AstAxis *this_axis, int *status ) { /* * Name: * TestAxisFormat * Purpose: * Test if a value has been set for the Format attribute of a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int TestAxisFormat( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astTestAxisFormat method * inherited from the Axis class). * Description: * This function returns 0 or 1 to indicate whether a value has been set * for the Format attribute of a SkyAxis. * Parameters: * this * Pointer to the SkyAxis. * status * Pointer to the inherited status variable. * Returned Value: * Zero if no Format value has been set, otherwise one. * Notes: * - This function will return a value of zero if it is invoked with the * global error status set, or if it should fail for any reason. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ int result; /* Result to be returned */ /* Check the global error status. */ if ( !astOK ) return 0; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_axis; /* The Format string has been set if the pointer to it is not NULL. */ result = ( this->skyformat != NULL ); /* Return the result. */ return result; } static int TestAxisInternalUnit( AstAxis *this, int *status ){ /* * Name: * TestAxisInternalUnit * Purpose: * Test if a InternalUnit attribute value is set for an Axis. * Type: * Private function. * Synopsis: * #include "axis.h" * int TestAxisInternalUnit( AstAxis *this, int *status ) * Class Membership: * SkyAxis member function (over-rides the astTestAxisInternalUnit * protected method inherited from the Axis class). * Description: * This function returns a boolean result (0 or 1) to indicate * whether a value has been set for the InternalUnit string. * Parameters: * this * Pointer to the Axis. * 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. */ /* Tell the world that we know what value to use for InternalUnit (i.e. "rad"). */ return 1; } static int AxisUnformat( AstAxis *this_axis, const char *string, double *value, int *status ) { /* * Name: * AxisUnformat * Purpose: * Read a formatted coordinate value for a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * int AxisUnformat( AstAxis *axis, const char *string, double *value, int *status ) * Class Membership: * SkyAxis member function (over-rides the astAxisUnformat method * inherited from the Axis class). * Description: * This function reads a formatted coordinate value for a SkyAxis * (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 SkyAxis. * 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 (in radians). * 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 "" 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 Constants: */ #define FMT_LEN 50 /* Length of format buffer */ /* Local Variables: */ char fmtbuf[ FMT_LEN + 1 ]; /* Buffer for C format specification */ char fmtsep; /* Format field separator character */ char last_sep; /* Previous separator character */ char sep; /* Separator character */ char sep_used; /* Separator character being used */ char sign[ 2 ]; /* Sign character as string */ const char *field_start[ 3 ]; /* Pointer to start of each field */ const char *fmt; /* Pointer to SkyAxis Format string */ const char *s; /* Pointer to current reading position */ const char *string_start; /* Pointer to first significant character */ double field[ 3 ]; /* Field values */ double testval; /* Value to test for invalid fields */ int angle_or_time; /* Value known to be angle or time? */ int as_time; /* Value is a time (else an angle)? */ int decimal; /* Decimal point in field? */ int dh; /* Hours field required? */ int digs; /* Default no. of digits of precision */ int exponent; /* Exponent at end of field? */ int field_id[ 3 ]; /* Field identification (0 = don't know) */ int final; /* Final field read? */ int good_sep; /* Separator character valid? */ int i; /* Loop counter for characters */ int ifield; /* Loop counter for fields */ int lead_zero; /* Add leading zeros? */ int len; /* Significant length of string */ int m; /* Number of characters read by astSscanf */ int match; /* Character pattern matches? */ int min; /* Minutes field required? */ int n; /* Number of characters read by astSscanf */ int nc; /* Total no. characters read */ int nchar; /* Number of characters in erroneous value */ int ndp; /* Number of decimal places */ int next_id; /* Next field ID to use (0 = don't know) */ int nfield; /* Number of fields read */ int nread; /* No. characters read for current field */ int plus; /* Add leading plus sign? */ int positive; /* Value is positive? */ int sec; /* Seconds field required? */ int sep_angle_or_time; /* Separator indicates angle or time? */ int sep_field_id; /* Field ID from separator (0 = don't know) */ int sep_index; /* Index of separator character in table */ int sep_len; /* Length of separator plus trailing space */ int suffix_sep; /* Field has a suffix separator? */ /* Local Data: */ const char *sep_list = /* List of separator characters recognised */ " :hHdDmM'sS\""; const int angle_or_time_list[] = /* Whether separator indicates angle or time (1 or 2). Zero => don't know. */ { 0, 0, 2, 2, 1, 1, 0, 0, 1, 0, 0, 1 }; const int field_id_list[] = /* Whether separator identifies previous field (1, 2, or 3). Zero => doesn't identify. */ { 0, 0, 1, 1, 1, 1, 2, 2, 2, 3, 3, 3 }; const double fieldvalue[ 3 ] = /* Nominal field values (degrees/hours) */ { 1.0, 1.0 / 60.0, 1.0 / 3600.0 }; /* Initialise. */ nc = 0; /* Check the global error status. */ if ( !astOK ) return nc; /* Obtain the SkyAxis Format string. If its starts with a "%" sign, use the parent AxisUnformat method inherited from the Axis class. Use a private method to obtain the Format string, in case the syntax has been over-ridden by a derived class. */ fmt = GetAxisFormat( this_axis, status ); if( fmt && fmt[0] == '%' ) { nc = (*parent_axisunformat)( this_axis, string, value, status ); /* Otherwise, parse it to determine the default choice of input format. */ } else if( astOK ){ digs = astGetAxisDigits( this_axis ); ParseDHmsFormat( fmt, digs, &fmtsep, &plus, &lead_zero, &as_time, &dh, &min, &sec, &ndp, status ); /* Initialise a pointer into the string and advance it to the first non-white space character. Save a copy of this pointer. */ s = string; while ( isspace( (int) *s ) ) s++; string_start = s; /* Read sign information. */ /* ---------------------- */ /* Attempt to read an optional sign character ("+" or "-"), possibly surrounded by white space. Set a flag to indicate if the returned value should be positive or not. Increment the string pointer to the next significant character. */ positive = 1; n = 0; if ( 1 == astSscanf( s, " %1[+-] %n", sign, &n ) ) { positive = ( *sign == '+' ); s += n; } /* Loop to read field information. */ /* ------------------------------- */ /* Initialise, then loop to read the values of up to three fields and to identify the separators that accompany them. */ angle_or_time = 0; last_sep = '\0'; next_id = 0; nfield = 0; sep_used = '\0'; suffix_sep = 0; sep_len = 0; for ( ifield = 0; ifield < 3; ifield++ ) { /* Set the default field value. */ field[ ifield ] = 0.0; /* If a prefix separator was identified for the second and subsequent fields (when the previous field was being read), then step over the prefix, including any following white space. */ if ( ifield && !suffix_sep ) s += sep_len; /* Note where in the input string the field's numerical value starts. */ field_start[ ifield ] = s; /* Each field must consist of a string of digits, possibly surrounded by white space, except that an optional decimal point may also be present (in which case it indicates the final field). Since we want to exclude signs, etc. from these fields, we must first identify a valid sequence of digits, before attempting to read them as a number. Start by assuming that we will find a decimal point but not an exponent. */ decimal = 1; exponent = 0; /* Match a field and obtain its value. */ /* ----------------------------------- */ /* Look for a character sequence like "12.345", or similar, setting a flag to identify a match. */ n = 0; match = ( 0 == astSscanf( s, "%*[0123456789].%*[0123456789]%n", &n ) ) && n; /* If that failed, then look for a sequence like "12.", or similar. */ if ( !match ) { n = 0; match = ( 0 == astSscanf( s, "%*[0123456789].%n", &n ) ) && n; } /* If that also failed, then look for a sequence like ".12", or similar. */ if ( !match ) { n = 0; match = ( 0 == astSscanf( s, ".%*[0123456789]%n", &n ) ) && n; } /* If that also failed, then look for a sequence containing digits only. */ if ( !match ) { n = 0; match = ( 0 == astSscanf( s, "%*[0123456789]%n", &n ) ) && n; /* Note we have not found a decimal point. */ decimal = 0; } /* Now look for numbers that end with an exponent. First check that the string starts with a sequence of digits with or without a decimal point. */ if( match ) { /* See if the numbers are followed by an exponent with an explicit sign character. If so, increment the number of characters in the numerical string prefix. */ m = 0; if( ( 0 == astSscanf( s + n, "%*1[Ee]%*1[+-]%*[0123456789]%n", &m ) ) && m ) { n += m; exponent = 1; /* If the above check failed, see if the numbers are followed by an exponent without an explicit sign character. If so, increment the number of characters in the numerical string prefix. */ } else { m = 0; if( ( 0 == astSscanf( s + n, "%*1[Ee]%*[0123456789]%n", &m ) ) && m ) { n += m; exponent = 1; } } } /* If we identified a suitable sequence of characters above, we will now read them as a number. To prevent any subsequent characters being included as part of this number, the field width must be restricted to the length of the sequence we found. Write a format specification to read a double with this field width, followed by optional white space, and to return the total number of characters read. */ nread = 0; if ( match ) { (void) sprintf( fmtbuf, "%%%dlf %%n", n ); /* Use this format specification to read the field value. If successful, increment the string pointer to the next significant character. */ if ( 1 == astSscanf( s, fmtbuf, field + ifield, &nread ) ) s += nread; } /* Note the total number of characters read up to the end of the numerical value in this field (including any following white space). */ nc = s - string; /* Identify the following separator. */ /* --------------------------------- */ /* We will now attempt to identify the field separator (if any) which follows the field we have just read. By default, we behave as if the separator is a space. Note we have actually found a space (at least) if extra white space characters were read as part of the field value above. */ sep = ' '; good_sep = ( nread > n ); /* Look for one of the recognised separator characters. If one is found, save a copy of it and note we appear (so far) to have a valid separator. */ sep_len = 0; if ( *s && strchr( sep_list, *s ) ) { sep = *s; good_sep = 1; /* Set "sep_len" to the number of characters associated with the separator. This includes any following white space. */ while ( isspace( (int) s[ ++sep_len ] ) ); } /* Identify the separator character by looking it up in the separator list (this just uses a space if no valid separator has been found). */ sep_index = strchr( sep_list, sep ) - sep_list; /* Determine if the separator can be used to identify the field which preceded it and if it allows us to determine whether an angle or a time is being read. Both of these properties are specified in data tables (with zero indicating that the separator didn't supply any information). */ sep_field_id = field_id_list[ sep_index ]; sep_angle_or_time = angle_or_time_list[ sep_index ]; /* Validate the separator. */ /* ----------------------- */ /* Now perform further checks that the separator is valid (i.e. conforms to the required syntax). If it appears to identify the previous field (i.e. is a "suffix" separator like "m" or "s"), then it is valid only if its field ID is no less than the ID value that would be used next, based on previous fields (if any), and no less than the current field number. This ensures that fields occur in the correct order without duplication. */ if ( good_sep ) { if ( sep_field_id ) { good_sep = ( sep_field_id >= next_id ) && ( sep_field_id > ifield ); /* Otherwise (i.e. we appear to have a "prefix" separator like ":" or " "), it is valid if it is the first one used, or if it matches the previous one used. Keep a note of the first such separator used for checking subsequent ones. */ } else { good_sep = !sep_used || ( sep == sep_used ); if ( !sep_used ) sep_used = sep; } } /* If the separator seems OK and we don't yet know whether we are reading an angle or a time, then use whatever information the separator provides about this. */ if ( good_sep ) { if ( !angle_or_time ) { angle_or_time = sep_angle_or_time; /* If we already know whether we are reading an angle or a time and the current separator also contains information about this, then check that these sources of information are compatible. This prevents inconsistent use of angle/time field separators. */ } else { good_sep = !sep_angle_or_time || ( sep_angle_or_time == angle_or_time ); } } /* Update the count of characters read for this field and note if we have identified a valid suffix separator. */ if ( good_sep ) nread += sep_len; suffix_sep = good_sep && sep_field_id; /* Identify which field was read. */ /* ------------------------------ */ /* If we have a valid suffix separator, store the field ID. Also make a note of the ID to use for the next field. */ if ( suffix_sep ) { field_id[ ifield ] = sep_field_id; next_id = sep_field_id + 1; /* Step over the separator (plus any following white space) and update the total number of characters read (prefix separators are not accounted for until we start to read the next field). */ s += sep_len; nc = s - string;; /* If the separator does not identify the current field, then assign a field ID based on the previous field (if any). Update the ID to use for the next field, if known. */ } else { field_id[ ifield ] = next_id; if ( next_id ) next_id++; } /* Count fields and exit when done. */ /* -------------------------------- */ /* If no characters have been read for the current field, then disregard the field if: (a) it is the first one (i.e. there is nothing to read), or (b) it follows a white space separator (because trailing space does not delimit an extra field). In either case, we have now read all the fields. Otherwise, increment the count of fields read. */ final = 0; if ( !nread && ( !ifield || isspace( (int) last_sep ) ) ) { final = 1; } else { nfield++; } /* We have also read all the fields if: (a) the last one contained a decimal point, or (b) the last one ended with an exponent, or (c) the next character is not a valid field separator, or (d) we have read the seconds field so the next field ID would exceed 3. */ final = final || decimal || exponent || !good_sep || ( next_id > 3 ); /* Quit reading if we have read the final field. Otherwise, save the separator character and attempt to read the next field. */ if ( final ) break; last_sep = sep; } /* Complete the identification of fields. */ /* -------------------------------------- */ /* Although we have propagated field IDs from earlier ones to later ones in the loop above, we have still not done the reverse. This means there there may still be some leading fields which have not been positively identified (i.e. still have a field ID of zero). In fact, all the fields we have read might still be unidentified at this point. */ /* Calculate the field ID that would apply to the final field we have read in the absence of any other information. This depends on the number of leading fields that are expected to be missing. */ next_id = nfield + ( dh ? 0 : ( min ? 1 : 2 ) ); if ( next_id > 3 ) next_id = 3; /* Loop through the fields in reverse order, propagating any positive identifications backwards towards the first field. If no fields have been positively identified, then they are simply numbered consecutively based on the value calculated above. */ for ( ifield = nfield - 1; ifield >= 0; ifield-- ) { if ( field_id[ ifield ] ) { next_id = field_id[ ifield ] - 1; } else { field_id[ ifield ] = next_id--; } } /* Handle inability to read any value. */ /* ----------------------------------- */ /* If no fields were read, then check to see if we are trying to read the string "" (or similar) possibly surrounded by, or containing, white space. If so, return the coordinate value AST__BAD. */ if ( !nfield ) { if ( n = 0, ( 0 == astSscanf( string, " < %*1[Bb] %*1[Aa] %*1[Dd] > %n", &n ) && n ) ) { *value = AST__BAD; nc = n; /* If the string still cannot be read, then return a function value of zero. */ } else { nc = 0; } /* Finally determine angle or time. */ /* -------------------------------- */ /* If one or more fields have been read, check if we know whether to interpret the value as an angle or a time (if not, we continue to use the default choice obtained from the SkyAxis Format string). */ } else { if ( angle_or_time ) as_time = ( angle_or_time == 2 ); /* Validate field values. */ /* ---------------------- */ /* If OK, check all fields except the first one for a valid value (we allow the first field to be unconstrained, so that angles and times outside the conventional ranges can be represented). We only need to test for values over 60.0, since negative values can't be read. */ if ( astOK ) { for ( ifield = 1; ifield < nfield; ifield++ ) { if ( field[ ifield ] >= 60.0 ) { /* If a suspect field is found, we must now re-read it. This is because values like "59.9999..." are valid, even if they round up to 60, whereas "60" isn't. To distinguish these cases, we read the digits that occur before the decimal point (if any). Determine how many such digits there are. */ n = 0; if ( ( 0 == astSscanf( field_start[ ifield ], "%*[0123456789]%n", &n ) ) && n ) { /* If there are none (this shouldn't happen), the field is valid. Otherwise, construct a format specification to read these digits as a floating point number. */ (void) sprintf( fmtbuf, "%%%dlf", n ); /* Read the digits and compare the result with 60.0. Report an error and quit if necessary, limiting the string length in the error message to include just the significant characters in the value read. */ if ( ( 1 == astSscanf( field_start[ ifield ], fmtbuf, &testval ) ) && ( testval >= 60.0 ) ) { nchar = nc - ( string_start - string ); for ( i = len = 0; i < nchar; i++ ) { if ( !isspace( (int) string_start[ i ] ) ) { len = i + 1; } } astError( AST__UNFER, "Invalid %s%s value in sky " "coordinate \"%.*s\".", status, as_time ? "" : "arc", ( field_id[ ifield ] == 2 ) ? "minutes" : "seconds", len, string_start ); break; } } } } } /* Calculate final result. */ /* ----------------------- */ /* If OK, calculate the result by summing the field values and converting to radians. */ if ( astOK ) { *value = 0.0; for ( ifield = 0; ifield < nfield; ifield++ ) { *value += field[ ifield ] * fieldvalue[ field_id[ ifield ] - 1 ] * ( as_time ? hr2rad : deg2rad ); } /* Change sign if necessary. */ if ( !positive ) *value = - *value; } } } /* If an error occurred, set the number of characters read to zero. */ if ( !astOK ) nc = 0; /* Return the number of characters read. */ return nc; /* Undefine macros local to this function. */ #undef FMT_LEN } /* Functions which access class attributes. */ /* ---------------------------------------- */ /* Implement member functions to access the attributes associated with the SkyAxis class using the macros defined for this purpose in the "object.h" file. For a description of each attribute, see the class interface (in the associated .h file). */ /* AsTime. */ /* ------- */ /* The value is constrained to be -INT_MAX, 0 or 1, with -INT_MAX for "undefined". The default value is 0 unless the "IsLatitude" attribute has been explicitly set to 0, in which case "AsTime" defaults to 1. */ astMAKE_CLEAR(SkyAxis,AxisAsTime,as_time,-INT_MAX) astMAKE_GET(SkyAxis,AxisAsTime,int,0,( ( this->as_time != -INT_MAX ) ? this->as_time : ( astTestAxisIsLatitude( this ) && !astGetAxisIsLatitude( this ) ) )) astMAKE_SET(SkyAxis,AxisAsTime,int,as_time,( value != 0 )) astMAKE_TEST(SkyAxis,AxisAsTime,( this->as_time != -INT_MAX )) /* IsLatitude. */ /* ----------- */ /* The value is constrained to be -INT_MAX, 0 or 1, with -INT_MAX for "undefined". The default value is 0. */ astMAKE_CLEAR(SkyAxis,AxisIsLatitude,is_latitude,-INT_MAX) astMAKE_GET(SkyAxis,AxisIsLatitude,int,0,( this->is_latitude != -INT_MAX ? this->is_latitude : 0 )) astMAKE_SET(SkyAxis,AxisIsLatitude,int,is_latitude,( value != 0 )) astMAKE_TEST(SkyAxis,AxisIsLatitude,( this->is_latitude != -INT_MAX )) /* CentreZero. */ /* ----------- */ /* The value is constrained to be -INT_MAX, 0 or 1, with -INT_MAX for "undefined". The default value is equal to the value of IsLatitude. */ astMAKE_CLEAR(SkyAxis,AxisCentreZero,centrezero,-INT_MAX) astMAKE_GET(SkyAxis,AxisCentreZero,int,0,( this->centrezero != -INT_MAX ? this->centrezero : astGetAxisIsLatitude( this ) )) astMAKE_SET(SkyAxis,AxisCentreZero,int,centrezero,( value != 0 )) astMAKE_TEST(SkyAxis,AxisCentreZero,( this->centrezero != -INT_MAX )) /* Copy constructor. */ /* ----------------- */ static void Copy( const AstObject *objin, AstObject *objout, int *status ) { /* * Name: * Copy * Purpose: * Copy constructor for SkyAxis objects. * Type: * Private function. * Synopsis: * void Copy( const AstObject *objin, AstObject *objout, int *status ) * Description: * This function implements the copy constructor for SkyAxis objects. * Parameters: * objin * Pointer to the object to be copied. * objout * Pointer to the object being constructed. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * - This constructor makes a deep copy. */ /* Local Variables: */ AstSkyAxis *in; /* Pointer to input SkyAxis */ AstSkyAxis *out; /* Pointer to output SkyAxis */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain pointers to the input and output SkyAxis structures. */ in = (AstSkyAxis *) objin; out = (AstSkyAxis *) objout; /* For safety, first clear any references to the input memory from the output SkyAxis. */ out->skyformat = NULL; /* Make copies of the allocated strings. */ if ( in->skyformat ) out->skyformat = astStore( NULL, in->skyformat, strlen( in->skyformat ) + (size_t) 1 ); /* If an error occurred, clean up by freeing all memory allocated above. */ if ( !astOK ) { out->skyformat = astFree( out->skyformat ); } } /* Destructor. */ /* ----------- */ static void Delete( AstObject *obj, int *status ) { /* * Name: * Delete * Purpose: * Destructor for SkyAxis objects. * Type: * Private function. * Synopsis: * void Delete( AstObject *obj, int *status ) * Description: * This function implements the destructor for SkyAxis objects. * Parameters: * obj * Pointer to the object to be deleted. * status * Pointer to the inherited status variable. * Returned Value: * void * Notes: * This function attempts to execute even if the global error status is * set. */ /* Local Variables: */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) obj; /* Free all allocated memory. */ this->skyformat = astFree( this->skyformat ); } /* Dump function. */ /* -------------- */ static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { /* * Name: * Dump * Purpose: * Dump function for SkyAxis 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 SkyAxis class to an output Channel. * Parameters: * this * Pointer to the SkyAxis 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 Variables: */ AstAxis *this_axis; /* Pointer to Axis structure */ AstSkyAxis *this; /* Pointer to the SkyAxis structure */ const char *sval; /* Pointer to string value */ int ival; /* Integer value */ int set; /* Attribute value set? */ /* Check the global error status. */ if ( !astOK ) return; /* Obtain a pointer to the SkyAxis structure. */ this = (AstSkyAxis *) this_object; /* Write out values representing the instance variables for the SkyAxis 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. */ /* Format. */ /* ------- */ /* We must write out the Format value stored locally as it over-rides that provided by the Axis class. */ this_axis = (AstAxis *) this; set = TestAxisFormat( this_axis, status ); sval = set ? GetAxisFormat( this_axis, status ) : astGetAxisFormat( this ); astWriteString( channel, "Format", set, 0, sval, "Format specifier" ); /* IsLatitude. */ /* ----------- */ set = TestAxisIsLatitude( this, status ); ival = set ? GetAxisIsLatitude( this, status ) : astGetAxisIsLatitude( this ); astWriteInt( channel, "IsLat", set, 0, ival, ival ? "Latitude axis (not longitude)" : "Longitude axis (not latitude)" ); /* CentreZero. */ /* ----------- */ set = TestAxisCentreZero( this, status ); ival = set ? GetAxisCentreZero( this, status ) : astGetAxisCentreZero( this ); astWriteInt( channel, "CnZer", set, 0, ival, ival ? "Display axis values in range -PI -> +PI" : "Display axis values in range 0 -> 2.PI" ); /* AsTime. */ /* ------- */ set = TestAxisAsTime( this, status ); ival = set ? GetAxisAsTime( this, status ) : astGetAxisAsTime( this ); astWriteInt( channel, "AsTime", set, 0, ival, ival ? "Display values as times (not angles)" : "Display values as angles (not times)" ); } /* Standard class functions. */ /* ========================= */ /* Implement the astIsASkyAxis and astCheckSkyAxis functions using the macros defined for this purpose in the "object.h" header file. */ astMAKE_ISA(SkyAxis,Axis) astMAKE_CHECK(SkyAxis) AstSkyAxis *astSkyAxis_( const char *options, int *status, ...) { /* *+ * Name: * astSkyAxis * Purpose: * Create a SkyAxis. * Type: * Public function. * Synopsis: * #include "skyaxis.h" * AstSkyAxis *astSkyAxis( const char *options, int *status, ... ) * Class Membership: * SkyAxis constructor. * Description: * This function creates a new SkyAxis and optionally initialises its * attributes. * Parameters: * options * Pointer to a null terminated string containing an optional * comma-separated list of attribute assignments to be used for * initialising the new SkyAxis. 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 SkyAxis. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyAxis *new; /* Pointer to new SkyAxis */ va_list args; /* Variable argument list */ /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the SkyAxis, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSkyAxis( NULL, sizeof( AstSkyAxis ), !class_init, &class_vtab, "SkyAxis" ); /* 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 SkyAxis' 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 SkyAxis. */ return new; } AstSkyAxis *astSkyAxisId_( const char *options, ... ) { /* * Name: * astSkyAxisId_ * Purpose: * Create a SkyAxis. * Type: * Private function. * Synopsis: * #include "skyaxis.h" * AstSkyAxis *astSkyAxisId_( const char *options, ... ) * Class Membership: * SkyAxis constructor. * Description: * This function implements the external (public) interface to the * astSkyAxis constructor function. It returns an ID value (instead * of a true C pointer) to external users, and must be provided * because astSkyAxis_ has a variable argument list which cannot be * encapsulated in a macro (where this conversion would otherwise * occur). * * The variable argument list also prevents this function from * invoking astSkyAxis_ directly, so it must be a re-implementation * of it in all respects, except for the final conversion of the * result to an ID value. * Parameters: * As for astSkyAxis_. * Returned Value: * The ID value associated with the new SkyAxis. */ /* Local Variables: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyAxis *new; /* Pointer to new SkyAxis */ va_list args; /* Variable argument list */ int *status; /* Pointer to inherited status value */ /* Get a pointer to the inherited status value. */ status = astGetStatusPtr; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(NULL); /* Check the global error status. */ if ( !astOK ) return NULL; /* Initialise the SkyAxis, allocating memory and initialising the virtual function table as well if necessary. */ new = astInitSkyAxis( NULL, sizeof( AstSkyAxis ), !class_init, &class_vtab, "SkyAxis" ); /* 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 SkyAxis' 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 SkyAxis. */ return astMakeId( new ); } AstSkyAxis *astInitSkyAxis_( void *mem, size_t size, int init, AstSkyAxisVtab *vtab, const char *name, int *status ) { /* *+ * Name: * astInitSkyAxis * Purpose: * Initialise a SkyAxis. * Type: * Protected function. * Synopsis: * #include "skyaxis.h" * AstSkyAxis *astInitSkyAxis( void *mem, size_t size, int init, * AstSkyAxisVtab *vtab, const char *name ) * Class Membership: * SkyAxis initialiser. * Description: * This function is provided for use by class implementations to initialise * a new SkyAxis object. It allocates memory (if necessary) to accommodate * the SkyAxis plus any additional data associated with the derived class. * It then initialises a SkyAxis 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 SkyAxis at the start of the memory passed via the * "vtab" parameter. * Parameters: * mem * A pointer to the memory in which the SkyAxis is to be created. This * must be of sufficient size to accommodate the SkyAxis data * (sizeof(SkyAxis)) 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 SkyAxis (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 SkyAxis * structure, so a valid value must be supplied even if not required for * allocating memory. * init * A logical flag indicating if the SkyAxis'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 SkyAxis. * 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 astClass * method). * Returned Value: * A pointer to the new SkyAxis. * 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: */ AstSkyAxis *new; /* Pointer to the new SkyAxis */ /* Check the global error status. */ if ( !astOK ) return NULL; /* If necessary, initialise the virtual function table. */ if ( init ) astInitSkyAxisVtab( vtab, name ); /* Initialise an Axis structure (the parent class) as the first component within the SkyAxis structure, allocating memory if necessary. */ new = (AstSkyAxis *) astInitAxis( mem, size, 0, (AstAxisVtab *) vtab, name ); if ( astOK ) { /* Initialise the SkyAxis data. */ /* ---------------------------- */ /* Initialise all attributes to their "undefined" values. */ new->as_time = -INT_MAX; new->is_latitude = -INT_MAX; new->centrezero = -INT_MAX; new->skyformat = NULL; /* If an error occurred, clean up by deleting the new SkyAxis. */ if ( !astOK ) new = astDelete( new ); } /* Return a pointer to the new SkyAxis. */ return new; } AstSkyAxis *astLoadSkyAxis_( void *mem, size_t size, AstSkyAxisVtab *vtab, const char *name, AstChannel *channel, int *status ) { /* *+ * Name: * astLoadSkyAxis * Purpose: * Load a SkyAxis. * Type: * Protected function. * Synopsis: * #include "skyaxis.h" * AstSkyAxis *astLoadSkyAxis( void *mem, size_t size, * AstSkyAxisVtab *vtab, const char *name, * AstChannel *channel ) * Class Membership: * SkyAxis loader. * Description: * This function is provided to load a new SkyAxis 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 * SkyAxis structure in this memory, using data read from the input * Channel. * * If the "init" flag is set, it also initialises the contents of a * virtual function table for a SkyAxis at the start of the memory * passed via the "vtab" parameter. * Parameters: * mem * A pointer to the memory into which the SkyAxis is to be * loaded. This must be of sufficient size to accommodate the * SkyAxis data (sizeof(SkyAxis)) 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 SkyAxis (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 SkyAxis 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(AstSkyAxis) is used instead. * vtab * Pointer to the start of the virtual function table to be * associated with the new SkyAxis. If this is NULL, a pointer * to the (static) virtual function table for the SkyAxis 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 "SkyAxis" is used instead. * Returned Value: * A pointer to the new SkyAxis. * 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: */ astDECLARE_GLOBALS /* Pointer to thread-specific global data */ AstSkyAxis *new; /* Pointer to the new SkyAxis */ /* Initialise. */ new = NULL; /* Check the global error status. */ if ( !astOK ) return new; /* Get a pointer to the thread specific global data structure. */ astGET_GLOBALS(channel); /* If a NULL virtual function table has been supplied, then this is the first loader to be invoked for this SkyAxis. In this case the SkyAxis belongs to this class, so supply appropriate values to be passed to the parent class loader (and its parent, etc.). */ if ( !vtab ) { size = sizeof( AstSkyAxis ); vtab = &class_vtab; name = "SkyAxis"; /* If required, initialise the virtual function table for this class. */ if ( !class_init ) { astInitSkyAxisVtab( 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 SkyAxis. */ new = astLoadAxis( mem, size, (AstAxisVtab *) 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, "SkyAxis" ); /* 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. */ /* Format. */ /* ------- */ /* Note that string values do not require any additional processing. */ new->skyformat = astReadString( channel, "format", NULL ); /* IsLatitude. */ /* ----------- */ new->is_latitude = astReadInt( channel, "islat", -INT_MAX ); if ( TestAxisIsLatitude( new, status ) ) { SetAxisIsLatitude( new, new->is_latitude, status ); } /* CentreZero. */ /* ----------- */ new->centrezero = astReadInt( channel, "cnzer", -INT_MAX ); if ( TestAxisCentreZero( new, status ) ) { SetAxisCentreZero( new, new->centrezero, status ); } /* AsTime. */ /* ------- */ new->as_time = astReadInt( channel, "astime", -INT_MAX ); if ( TestAxisAsTime( new, status ) ) SetAxisAsTime( new, new->as_time, status ); /* If an error occurred, clean up by deleting the new SkyAxis. */ if ( !astOK ) new = astDelete( new ); } /* Return the new SkyAxis pointer. */ return new; } /* 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. */ /* (No more to define at present.) */ ast-8.3.0/plot3d.h0000664000175000017500000002104413004147321010606 00000000000000#if !defined( PLOT3D_INCLUDED ) /* Include this file only once */ #define PLOT3D_INCLUDED /* *+ * Name: * plot3d.h * Type: * C include file. * Purpose: * Define the interface to the Plot3D class. * Invocation: * #include "plot3d.h" * Description: * This include file defines the interface to the Plot3D class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * Copyright: * Copyright (C) 2007 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 6-JUN-2007 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "plot.h" /* Parent Plot class */ /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif #if defined(astCLASS) /* Protected */ #endif /* Type Definitions. */ /* ================= */ /* Plot3D structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstPlot3D { /* Attributes inherited from the parent class. */ AstPlot plot; /* Parent class structure */ /* Attributes specific to objects in this class. */ AstPlot *plotxy; /* Plot describing the XY plane */ AstPlot *plotxz; /* Plot describing the XZ plane */ AstPlot *plotyz; /* Plot describing the YZ plane */ double gbox[6]; /* Graphics box */ int pix_frame; /* Index of original base Frame */ int rootcorner; /* Corner at junction of the annotated axes */ int baseplot; /* The Plot that is used to label 2 3D axes */ int axis_plot1[3]; /* The Plot used to label each 3D axis */ int axis_index1[3]; /* The axis index within the axis_plot1 Plot */ int axis_plot2[3]; /* The other Plot touching each 3D axis */ int axis_index2[3]; /* The axis index within the axis_plot2 Plot */ double norm[3]; /* Normal vector for text plane */ } AstPlot3D; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstPlot3DVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstPlotVtab plot_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; int (* GetRootCorner)( AstPlot3D *, int * ); int (* TestRootCorner)( AstPlot3D *, int * ); void (* SetRootCorner)( AstPlot3D *, int, int * ); void (* ClearRootCorner)( AstPlot3D *, int * ); double (* GetNorm)( AstPlot3D *, int, int * ); int (* TestNorm)( AstPlot3D *, int, int * ); void (* SetNorm)( AstPlot3D *, int, double, int * ); void (* ClearNorm)( AstPlot3D *, int, int * ); } AstPlot3DVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstPlot3DGlobals { AstPlot3DVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstPlot3DGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(Plot3D) /* Check class membership */ astPROTO_ISA(Plot3D) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstPlot3D *astPlot3D_( void *, const float *, const double *, const char *, int *, ...); #else AstPlot3D *astPlot3DId_( void *, const float [], const double [], const char *, ... ); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstPlot3D *astInitPlot3D_( void *, size_t, int, AstPlot3DVtab *, const char *, AstFrame *, const float *, const double *, int * ); /* Vtab initialiser. */ void astInitPlot3DVtab_( AstPlot3DVtab *, const char *, int * ); /* Loader. */ AstPlot3D *astLoadPlot3D_( void *, size_t, AstPlot3DVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitPlot3DGlobals_( AstPlot3DGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ int astGetRootCorner_( AstPlot3D *, int * ); int astTestRootCorner_( AstPlot3D *, int * ); void astSetRootCorner_( AstPlot3D *, int, int * ); void astClearRootCorner_( AstPlot3D *, int * ); double astGetNorm_( AstPlot3D *, int, int * ); int astTestNorm_( AstPlot3D *, int, int * ); void astSetNorm_( AstPlot3D *, int, double, int * ); void astClearNorm_( AstPlot3D *, int, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckPlot3D(this) astINVOKE_CHECK(Plot3D,this,0) #define astVerifyPlot3D(this) astINVOKE_CHECK(Plot3D,this,1) /* Test class membership. */ #define astIsAPlot3D(this) astINVOKE_ISA(Plot3D,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astPlot3D astINVOKE(F,astPlot3D_) #else #define astPlot3D astINVOKE(F,astPlot3DId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitPlot3D(mem,size,init,vtab,name,frame,graph,base) \ astINVOKE(O,astInitPlot3D_(mem,size,init,vtab,name,frame,graph,base,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitPlot3DVtab(vtab,name) astINVOKE(V,astInitPlot3DVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadPlot3D(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadPlot3D_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Interfaces to protected member functions. */ /* ----------------------------------------- */ /* Here we make use of astCheckPlot3D to validate Plot3D pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetRootCorner(this) astINVOKE(V,astGetRootCorner_(astCheckPlot3D(this),STATUS_PTR)) #define astTestRootCorner(this) astINVOKE(V,astTestRootCorner_(astCheckPlot3D(this),STATUS_PTR)) #define astClearRootCorner(this) astINVOKE(V,astClearRootCorner_(astCheckPlot3D(this),STATUS_PTR)) #define astSetRootCorner(this,value) astINVOKE(V,astSetRootCorner_(astCheckPlot3D(this),value,STATUS_PTR)) #define astGetNorm(this,axis) astINVOKE(V,astGetNorm_(astCheckPlot3D(this),axis,STATUS_PTR)) #define astTestNorm(this,axis) astINVOKE(V,astTestNorm_(astCheckPlot3D(this),axis,STATUS_PTR)) #define astClearNorm(this,axis) astINVOKE(V,astClearNorm_(astCheckPlot3D(this),axis,STATUS_PTR)) #define astSetNorm(this,axis,value) astINVOKE(V,astSetNorm_(astCheckPlot3D(this),axis,value,STATUS_PTR)) #endif #endif ast-8.3.0/wcstrig.h0000664000175000017500000000446213004147321011070 00000000000000/*============================================================================= * * WCSLIB - an implementation of the FITS WCS proposal. * Copyright (C) 1995-2002, Mark Calabretta * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published * by the Free Software Foundation; either version 2 of the License, or (at * your option) any later version. * * This library 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 Library * General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA * * Correspondence concerning WCSLIB may be directed to: * Internet email: mcalabre@atnf.csiro.au * Postal address: Dr. Mark Calabretta, * Australia Telescope National Facility, * P.O. Box 76, * Epping, NSW, 2121, * AUSTRALIA * * Author: Mark Calabretta, Australia Telescope National Facility * $Id$ *============================================================================= * * This version of wcstrig.h is based on the version in wcslib-2.9, but has * been modified in the following ways by the Starlink project (e-mail: * ussc@star.rl.ac.uk): * - Support for non-ANSI C prototypes removed * - Changed the name of the WCSLIB_TRIG macro to WCSLIB_TRIG_INCLUDED * - Changed names of degrees trig functions to avoid clashes with * wcslib. *===========================================================================*/ #ifndef WCSLIB_TRIG_INCLUDED #define WCSLIB_TRIG_INCLUDED #ifdef __cplusplus extern "C" { #endif double astCosd(const double); double astSind(const double); double astTand(const double); double astACosd(const double); double astASind(const double); double astATand(const double); double astATan2d(const double, const double); /* Domain tolerance for asin and acos functions. */ #define WCSTRIG_TOL 1e-10 #ifdef __cplusplus }; #endif #endif /* WCSLIB_TRIG_INCLUDED */ ast-8.3.0/fframe.c0000664000175000017500000003601613004147321010641 00000000000000/* *+ * Name: * fframe.c * Purpose: * Define a FORTRAN 77 interface to the AST Frame class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the Frame class. * Routines Defined: * AST_ANGLE * AST_AXANGLE * AST_AXDISTANCE * AST_AXOFFSET * AST_CONVERT * AST_DISTANCE * AST_FORMAT * AST_FRAME * AST_GETACTIVEUNIT * AST_INTERSECT * AST_ISAFRAME * AST_NORM * AST_OFFSET * AST_OFFSET2 * AST_PERMAXES * AST_PICKAXES * AST_RESOLVE * AST_SETACTIVEUNIT * AST_UNFORMAT * Copyright: * Copyright (C) 1997-2009 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * History: * 23-JUL-1996 (RFWS): * Original version. * 16-SEP-1996 (RFWS): * Added AST_DISTANCE and AST_OFFSET. * 25-FEB-1998 (RFWS): * Added AST_UNFORMAT. * 21-JUN-2001 (DSB): * Added AST_ANGLE and AST_OFFSET2. * 29-AUG-2001 (DSB): * Added AST_AXDISTANCE and AST_AXOFFSET. * 9-SEP-2001 (DSB): * Added AST_RESOLVE and AST_BEAR. * 21-SEP-2001 (DSB): * Replaced AST_BEAR by AST_AXANGLE. * 17-DEC-2002 (DSB): * Added AST_GETACTIVEUNIT and AST_SETACTIVEUNIT. * 14-JAN-2009 (DSB): * Added AST_INTERSECT. * 26-OCT-2016 (DSB): * Added method AST_AXNORM. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "mapping.h" /* C interface to the Mapping class */ #include "frame.h" /* C interface to the Frame class */ F77_INTEGER_FUNCTION(ast_convert)( INTEGER(FROM), INTEGER(TO), CHARACTER(NAMELIST), INTEGER(STATUS) TRAIL(NAMELIST) ) { GENPTR_INTEGER(FROM) GENPTR_INTEGER(TO) GENPTR_INTEGER(NAMELIST) F77_INTEGER_TYPE(RESULT); char *namelist; astAt( "AST_CONVERT", NULL, 0 ); astWatchSTATUS( namelist = astString( NAMELIST, NAMELIST_length ); RESULT = astP2I( astConvert( astI2P( *FROM ), astI2P( *TO ), namelist ) ); namelist = astFree( namelist ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_angle)( INTEGER(THIS), DOUBLE_ARRAY(A), DOUBLE_ARRAY(B), DOUBLE_ARRAY(C), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(A) GENPTR_DOUBLE_ARRAY(B) GENPTR_DOUBLE_ARRAY(C) F77_DOUBLE_TYPE(RESULT); astAt( "AST_ANGLE", NULL, 0 ); astWatchSTATUS( RESULT = astAngle( astI2P( *THIS ), A, B, C ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_axangle)( INTEGER(THIS), DOUBLE_ARRAY(A), DOUBLE_ARRAY(B), INTEGER(AXIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(A) GENPTR_DOUBLE_ARRAY(B) GENPTR_INTEGER(AXIS) F77_DOUBLE_TYPE(RESULT); astAt( "AST_AXANGLE", NULL, 0 ); astWatchSTATUS( RESULT = astAxAngle( astI2P( *THIS ), A, B, *AXIS ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_distance)( INTEGER(THIS), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) F77_DOUBLE_TYPE(RESULT); astAt( "AST_DISTANCE", NULL, 0 ); astWatchSTATUS( RESULT = astDistance( astI2P( *THIS ), POINT1, POINT2 ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_axdistance)( INTEGER(THIS), INTEGER(AXIS), DOUBLE(V1), DOUBLE(V2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_DOUBLE(V1) GENPTR_DOUBLE(V2) F77_DOUBLE_TYPE(RESULT); astAt( "AST_AXDISTANCE", NULL, 0 ); astWatchSTATUS( RESULT = astAxDistance( astI2P( *THIS ), *AXIS, *V1, *V2 ); ) return RESULT; } F77_DOUBLE_FUNCTION(ast_axoffset)( INTEGER(THIS), INTEGER(AXIS), DOUBLE(V1), DOUBLE(DIST), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_DOUBLE(V1) GENPTR_DOUBLE(DIST) F77_DOUBLE_TYPE(RESULT); astAt( "AST_AXOFFSET", NULL, 0 ); astWatchSTATUS( RESULT = astAxOffset( astI2P( *THIS ), *AXIS, *V1, *DIST ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_findframe)( INTEGER(TARGET), INTEGER(TEMPLATE), CHARACTER(NAMELIST), INTEGER(STATUS) TRAIL(NAMELIST) ) { GENPTR_INTEGER(TARGET) GENPTR_INTEGER(TEMPLATE) GENPTR_INTEGER(NAMELIST) F77_INTEGER_TYPE(RESULT); char *namelist; astAt( "AST_FINDFRAME", NULL, 0 ); astWatchSTATUS( namelist = astString( NAMELIST, NAMELIST_length ); RESULT = astP2I( astFindFrame( astI2P( *TARGET ), astI2P( *TEMPLATE ), namelist ) ); ) return RESULT; } F77_SUBROUTINE(ast_matchaxes)( INTEGER(FRM1), INTEGER(FRM2), INTEGER_ARRAY(AXES), INTEGER(STATUS) ) { GENPTR_INTEGER(FRM1) GENPTR_INTEGER(FRM2) GENPTR_INTEGER_ARRAY(AXES) astAt( "AST_MATCHAXES", NULL, 0 ); astWatchSTATUS( astMatchAxes( astI2P( *FRM1 ), astI2P( *FRM2 ), AXES ); ) } /* NO_CHAR_FUNCTION indicates that the f77.h method of returning a character result doesn't work, so add an extra argument instead and wrap this function up in a normal FORTRAN 77 function (in the file frame.f). */ #if NO_CHAR_FUNCTION F77_SUBROUTINE(ast_format_a)( CHARACTER(RESULT), #else F77_SUBROUTINE(ast_format)( CHARACTER_RETURN_VALUE(RESULT), #endif INTEGER(THIS), INTEGER(AXIS), DOUBLE(VALUE), INTEGER(STATUS) #if NO_CHAR_FUNCTION TRAIL(RESULT) #endif ) { GENPTR_CHARACTER(RESULT) GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_DOUBLE(VALUE) const char *result; int i; astAt( "AST_FORMAT", NULL, 0 ); astWatchSTATUS( result = astFormat( astI2P( *THIS ), *AXIS, *VALUE ); i = 0; if ( astOK ) { /* Copy result */ for ( ; result[ i ] && i < RESULT_length; i++ ) { RESULT[ i ] = result[ i ]; } } while ( i < RESULT_length ) RESULT[ i++ ] = ' '; /* Pad with blanks */ ) } F77_INTEGER_FUNCTION(ast_frame)( INTEGER(NAXES), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(NAXES) GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_FRAME", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exclude any trailing spaces. */ astChrTrunc( options ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astFrame( *NAXES, "%s", options ) ); (void) astFree( options ); ) return RESULT; } F77_LOGICAL_FUNCTION(ast_isaframe)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAFRAME", NULL, 0 ); astWatchSTATUS( RESULT = astIsAFrame( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_LOGICAL_FUNCTION(ast_getactiveunit)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_GETACTIVEUNIT", NULL, 0 ); astWatchSTATUS( RESULT = astGetActiveUnit( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_SUBROUTINE(ast_setactiveunit)( INTEGER(THIS), LOGICAL(VALUE), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_LOGICAL(VALUE) astAt( "AST_SETACTIVEUNIT", NULL, 0 ); astWatchSTATUS( astSetActiveUnit( astI2P( *THIS ), F77_ISTRUE( *VALUE ) ? 1 : 0 ); ) } F77_SUBROUTINE(ast_norm)( INTEGER(THIS), DOUBLE_ARRAY(VALUE), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(VALUE) astAt( "AST_NORM", NULL, 0 ); astWatchSTATUS( astNorm( astI2P( *THIS ), VALUE ); ) } F77_SUBROUTINE(ast_offset)( INTEGER(THIS), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), DOUBLE(OFFSET), DOUBLE_ARRAY(POINT3), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) GENPTR_DOUBLE(OFFSET) GENPTR_DOUBLE_ARRAY(POINT3) astAt( "AST_OFFSET", NULL, 0 ); astWatchSTATUS( astOffset( astI2P( *THIS ), POINT1, POINT2, *OFFSET, POINT3 ); ) } F77_DOUBLE_FUNCTION(ast_offset2)( INTEGER(THIS), DOUBLE_ARRAY(POINT1), DOUBLE(ANGLE), DOUBLE(OFFSET), DOUBLE_ARRAY(POINT2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE(ANGLE) GENPTR_DOUBLE(OFFSET) GENPTR_DOUBLE_ARRAY(POINT2) F77_DOUBLE_TYPE(RESULT); astAt( "AST_OFFSET2", NULL, 0 ); astWatchSTATUS( RESULT = astOffset2( astI2P( *THIS ), POINT1, *ANGLE, *OFFSET, POINT2 ); ) return RESULT; } F77_SUBROUTINE(ast_resolve)( INTEGER(THIS), DOUBLE_ARRAY(POINT1), DOUBLE_ARRAY(POINT2), DOUBLE_ARRAY(POINT3), DOUBLE_ARRAY(POINT4), DOUBLE(D1), DOUBLE(D2), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(POINT1) GENPTR_DOUBLE_ARRAY(POINT2) GENPTR_DOUBLE_ARRAY(POINT3) GENPTR_DOUBLE_ARRAY(POINT4) GENPTR_DOUBLE(D1) GENPTR_DOUBLE(D2) astAt( "AST_RESOLVE", NULL, 0 ); astWatchSTATUS( astResolve( astI2P( *THIS ), POINT1, POINT2, POINT3, POINT4, D1, D2 ); ) } F77_SUBROUTINE(ast_intersect)( INTEGER(THIS), DOUBLE_ARRAY(A1), DOUBLE_ARRAY(A2), DOUBLE_ARRAY(B1), DOUBLE_ARRAY(B2), DOUBLE_ARRAY(CROSS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_DOUBLE_ARRAY(A1) GENPTR_DOUBLE_ARRAY(A2) GENPTR_DOUBLE_ARRAY(B1) GENPTR_DOUBLE_ARRAY(B2) GENPTR_DOUBLE_ARRAY(CROSS) astAt( "AST_INTERSECT", NULL, 0 ); astWatchSTATUS( astIntersect( astI2P( *THIS ), A1, A2, B1, B2, CROSS ); ) } F77_SUBROUTINE(ast_permaxes)( INTEGER(THIS), INTEGER_ARRAY(PERM), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER_ARRAY(PERM) astAt( "AST_PERMAXES", NULL, 0 ); astWatchSTATUS( astPermAxes( astI2P( *THIS ), PERM ); ) } F77_INTEGER_FUNCTION(ast_pickaxes)( INTEGER(THIS), INTEGER(NAXES), INTEGER_ARRAY(AXES), INTEGER(MAP), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(NAXES) GENPTR_INTEGER_ARRAY(AXES) GENPTR_INTEGER(MAP) F77_INTEGER_TYPE(RESULT); AstMapping *map; astAt( "AST_PICKAXES", NULL, 0 ); astWatchSTATUS( RESULT = astP2I( astPickAxes( astI2P( *THIS ), *NAXES, AXES, &map ) ); *MAP = astP2I( map ); ) return RESULT; } F77_INTEGER_FUNCTION(ast_unformat)( INTEGER(THIS), INTEGER(AXIS), CHARACTER(STRING), DOUBLE(VALUE), INTEGER(STATUS) TRAIL(STRING) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_CHARACTER(STRING) GENPTR_DOUBLE(VALUE) GENPTR_INTEGER(STATUS) F77_INTEGER_TYPE(RESULT); char *string; double value; astAt( "AST_UNFORMAT", NULL, 0 ); astWatchSTATUS( string = astString( STRING, STRING_length ); RESULT = astUnformat( astI2P( *THIS ), *AXIS, string, &value ); *VALUE = value; (void) astFree( string ); ) return RESULT; } F77_SUBROUTINE(ast_axnorm)( INTEGER(THIS), INTEGER(AXIS), INTEGER(OPER), INTEGER(NVAL), DOUBLE(VALUES), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) GENPTR_INTEGER(AXIS) GENPTR_INTEGER(OPER) GENPTR_INTEGER(NVAL) GENPTR_DOUBLE(VALUES) astAt( "AST_AXNORM", NULL, 0 ); astWatchSTATUS( astAxNorm( astI2P( *THIS ), *AXIS, *OPER, *NVAL, VALUES ); ) } ast-8.3.0/fgrismmap.c0000664000175000017500000000574313004147321011371 00000000000000/* *+ * Name: * fgrismmap.c * Purpose: * Define a FORTRAN 77 interface to the AST GrismMap class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the GrismMap class. * Routines Defined: * AST_ISAGRISMMAP * AST_GRISMMAP * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 10-JUL-2003 (RFWS): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "grismmap.h" /* C interface to the GrismMap class */ F77_LOGICAL_FUNCTION(ast_isagrismmap)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISAGRISMMAP", NULL, 0 ); astWatchSTATUS( RESULT = astIsAGrismMap( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_grismmap)( CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_CHARACTER(OPTIONS) F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_GRISMMAP", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } RESULT = astP2I( astGrismMap( "%s", options ) ); astFree( options ); ) return RESULT; } ast-8.3.0/fluxframe.h0000664000175000017500000002125613004147321011377 00000000000000#if !defined( FLUXFRAME_INCLUDED ) /* Include this file only once */ #define FLUXFRAME_INCLUDED /* *+ * Name: * fluxframe.h * Type: * C include file. * Purpose: * Define the interface to the FluxFrame class. * Invocation: * #include "fluxframe.h" * Description: * This include file defines the interface to the FluxFrame class * and provides the type definitions, function prototypes and * macros, etc. needed to use this class. * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 1-DEC-2004 (DSB): * Original version. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "object.h" /* Base Object class */ #include "frame.h" /* Parent Frame class */ #include "specframe.h" /* Spectral coordinate systems */ /* Macros. */ /* ======= */ #if defined(astCLASS) || defined(astFORTRAN77) #define STATUS_PTR status #else #define STATUS_PTR astGetStatusPtr #endif /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif #if defined(astCLASS) /* Protected */ /* Values used to represent different System attribute values. */ #define AST__FLUXDEN 1 #define AST__FLUXDENW 2 #define AST__SBRIGHT 3 #define AST__SBRIGHTW 4 /* Define constants used to size global arrays in this module. */ #define AST__FLUXFRAME_GETATTRIB_BUFF_LEN 50 #define AST__FLUXFRAME_GETLABEL_BUFF_LEN 200 #define AST__FLUXFRAME_GETSYMBOL_BUFF_LEN 20 #define AST__FLUXFRAME_GETTITLE_BUFF_LEN 200 #endif /* Type Definitions. */ /* ================= */ /* FluxFrame structure. */ /* ------------------- */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstFluxFrame { /* Attributes inherited from the parent class. */ AstFrame frame; /* Parent class structure */ /* Attributes specific to objects in this class. */ double specval; /* Spectral position */ double defspecval; /* Default spectral position */ AstSpecFrame *specframe; /* SpecFrame describing specval & defspecval */ int nuunits; /* Size of usedunits array */ char **usedunits; /* Last used units for each system */ } AstFluxFrame; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstFluxFrameVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstFrameVtab frame_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; AstSystemType (* GetDensitySystem)( AstFluxFrame *, int * ); const char *(* GetDensityUnit)( AstFluxFrame *, int * ); double (* GetSpecVal)( AstFluxFrame *, int * ); int (* TestSpecVal)( AstFluxFrame *, int * ); void (* ClearSpecVal)( AstFluxFrame *, int * ); void (* SetSpecVal)( AstFluxFrame *, double, int * ); } AstFluxFrameVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstFluxFrameGlobals { AstFluxFrameVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ AST__FLUXFRAME_GETATTRIB_BUFF_LEN + 1 ]; char GetLabel_Buff[ AST__FLUXFRAME_GETLABEL_BUFF_LEN + 1 ]; char GetSymbol_Buff[ AST__FLUXFRAME_GETSYMBOL_BUFF_LEN + 1 ]; char GetTitle_Buff[ AST__FLUXFRAME_GETTITLE_BUFF_LEN + 1 ]; } AstFluxFrameGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(FluxFrame) /* Check class membership */ astPROTO_ISA(FluxFrame) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected */ AstFluxFrame *astFluxFrame_( double, void *, const char *, int *, ...); #else AstFluxFrame *astFluxFrameId_( double, void *, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstFluxFrame *astInitFluxFrame_( void *, size_t, int, AstFluxFrameVtab *, const char *, double, AstSpecFrame *, int * ); /* Vtab initialiser. */ void astInitFluxFrameVtab_( AstFluxFrameVtab *, const char *, int * ); /* Loader. */ AstFluxFrame *astLoadFluxFrame_( void *, size_t, AstFluxFrameVtab *, const char *, AstChannel *channel, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitFluxFrameGlobals_( AstFluxFrameGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ #if defined(astCLASS) /* Protected */ AstSystemType astGetDensitySystem_( AstFluxFrame *, int * ); const char *astGetDensityUnit_( AstFluxFrame *, int * ); double astGetSpecVal_( AstFluxFrame *, int * ); int astTestSpecVal_( AstFluxFrame *, int * ); void astClearSpecVal_( AstFluxFrame *, int * ); void astSetSpecVal_( AstFluxFrame *, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckFluxFrame(this) astINVOKE_CHECK(FluxFrame,this,0) #define astVerifyFluxFrame(this) astINVOKE_CHECK(FluxFrame,this,1) /* Test class membership. */ #define astIsAFluxFrame(this) astINVOKE_ISA(FluxFrame,this) /* Constructor. */ #if defined(astCLASS) /* Protected */ #define astFluxFrame astINVOKE(F,astFluxFrame_) #else #define astFluxFrame astINVOKE(F,astFluxFrameId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitFluxFrame(mem,size,init,vtab,name,specval,specfrm) \ astINVOKE(O,astInitFluxFrame_(mem,size,init,vtab,name,specval,astCheckSpecFrame(specfrm),STATUS_PTR)) /* Vtab Initialiser. */ #define astInitFluxFrameVtab(vtab,name) astINVOKE(V,astInitFluxFrameVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadFluxFrame(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadFluxFrame_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* None. */ /* Interfaces to protected member functions. */ /* ----------------------------------------- */ /* Here we make use of astCheckFluxFrame to validate FluxFrame pointers before use. This provides a contextual error report if a pointer to the wrong sort of object is supplied. */ #if defined(astCLASS) /* Protected */ #define astGetDensitySystem(this) astINVOKE(V,astGetDensitySystem_(astCheckFluxFrame(this),STATUS_PTR)) #define astGetDensityUnit(this) astINVOKE(V,astGetDensityUnit_(astCheckFluxFrame(this),STATUS_PTR)) #define astGetSpecVal(this) astINVOKE(V,astGetSpecVal_(astCheckFluxFrame(this),STATUS_PTR)) #define astTestSpecVal(this) astINVOKE(V,astTestSpecVal_(astCheckFluxFrame(this),STATUS_PTR)) #define astClearSpecVal(this) astINVOKE(V,astClearSpecVal_(astCheckFluxFrame(this),STATUS_PTR)) #define astSetSpecVal(this,value) astINVOKE(V,astSetSpecVal_(astCheckFluxFrame(this),value,STATUS_PTR)) #endif #endif ast-8.3.0/grf_5.6.c0000664000175000017500000000446713004147321010554 00000000000000/* * Name: * grf_5.6.c * Purpose: * Implement the grf module required by AST V5.6 if no graphics system * is available. * Description: * This file implements the low level graphics functions required * by the rest of AST V5.6, except for those already defined in * earlier grf_xxx.c files (i.e. those needed by ealier versions * of AST). These implementations simply report an error when called. * Inheritance: * This module is not a class and does not inherit. * Copyright: * Copyright (C) 2011 Science & Technology Facilities Council. * All Rights Reserved. * Licence: * This program is free software: you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation, either * version 3 of the License, or (at your option) any later * version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General * License along with this program. If not, see * . * Authors: * DSB: David S. Berry (Starlink) * History: * 4-MAR-2011 (DSB): * Original version. */ /* Header files */ /* ============ */ #include "grf.h" /* Declare the functions in this module */ #include "error.h" /* AST error reporting facilities */ #include "ast_err.h" /* AST error codes */ /* Function Prototypes */ /* =================== */ static void Report( const char * ); /* Function definitions */ /* ==================== */ int astGBBuf( void ){ Report( "astGBBuf" ); return 0; } int astGEBuf( void ){ Report( "astGEBuf" ); return 0; } static void Report( const char *name ){ astError( AST__GRFER, "%s: The graphics facilities implement by %s " "(introduced at AST V5.6) are needed but are unavailable.", name, name ); astError( AST__GRFER, "Re-link using a suitable option such as '-pgplot' " "with the ast_link script, or add an implementation of this " "function to your 'grf' module." ); } ast-8.3.0/fstcresourceprofile.c0000664000175000017500000000737413004147321013476 00000000000000/* *+ * Name: * fstcresourceprofile.c * Purpose: * Define a FORTRAN 77 interface to the AST StcResourceProfile class. * Type of Module: * C source file. * Description: * This file defines FORTRAN 77-callable C functions which provide * a public FORTRAN 77 interface to the StcResourceProfile class. * Routines Defined: * AST_ISASTCRESOURCEPROFILE * AST_STCRESOURCEPROFILE * 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 * . * Authors: * DSB: David S. Berry (Starlink) * History: * 22-NOV-2004 (DSB): * Original version. */ /* Define the astFORTRAN77 macro which prevents error messages from AST C functions from reporting the file and line number where the error occurred (since these would refer to this file, they would not be useful). */ #define astFORTRAN77 /* Header files. */ /* ============= */ #include "f77.h" /* FORTRAN <-> C interface macros (SUN/209) */ #include "c2f77.h" /* F77 <-> C support functions/macros */ #include "error.h" /* Error reporting facilities */ #include "memory.h" /* Memory handling facilities */ #include "object.h" /* Basic AST Object management functions */ #include "stcresourceprofile.h" /* C interface to the StcResourceProfile class */ F77_LOGICAL_FUNCTION(ast_isastcresourceprofile)( INTEGER(THIS), INTEGER(STATUS) ) { GENPTR_INTEGER(THIS) F77_LOGICAL_TYPE(RESULT); astAt( "AST_ISASTCRESOURCEPROFILE", NULL, 0 ); astWatchSTATUS( RESULT = astIsAStcResourceProfile( astI2P( *THIS ) ) ? F77_TRUE : F77_FALSE; ) return RESULT; } F77_INTEGER_FUNCTION(ast_stcresourceprofile)( INTEGER(REG), INTEGER(NCOORDS), INTEGER_ARRAY(COORDS), CHARACTER(OPTIONS), INTEGER(STATUS) TRAIL(OPTIONS) ) { GENPTR_INTEGER(REG) GENPTR_INTEGER(NCOORDS) GENPTR_CHARACTER(OPTIONS) GENPTR_INTEGER_ARRAY(COORDS) AstKeyMap **coords; F77_INTEGER_TYPE(RESULT); char *options; int i; astAt( "AST_STCRESOURCEPROFILE", NULL, 0 ); astWatchSTATUS( options = astString( OPTIONS, OPTIONS_length ); /* Truncate the options string to exlucde any trailing spaces. */ astChrTrunc( options ); /* Change ',' to '\n' (see AST_SET in fobject.c for why). */ if ( astOK ) { for ( i = 0; options[ i ]; i++ ) { if ( options[ i ] == ',' ) options[ i ] = '\n'; } } /* Convert supplied integers to pointers. */ coords = astMalloc( sizeof( AstKeyMap * )*(size_t)( *NCOORDS )); if( astOK ) { for( i = 0; i < *NCOORDS; i++ ) { coords[ i ] = (AstKeyMap *) astMakePointer( astI2P( COORDS[ i ] )); } } RESULT = astP2I( astStcResourceProfile( astI2P( *REG ), *NCOORDS, coords, "%s", options ) ); astFree( coords ); astFree( options ); ) return RESULT; } ast-8.3.0/astbad.c0000664000175000017500000001322413004147321010633 00000000000000/* Header files. */ /* ============= */ /* Interface definitions. */ /* ---------------------- */ #include "pointset.h" /* declaration of AST__BAD etc */ /* C header files. */ /* --------------- */ #include #include #include /* Local Constants: */ #define BUFF_LEN ( 2 * DBL_DIG + 20 ) /* Buffer length */ #define IEEE_DIG 17 /* Minimum number of digits required by IEEE for conversion from binary to string and back again to be an identity. */ /* Prototypes for local functions */ static void printdval( double ); static void printfval( float ); /* Main function. */ /* ============== */ int main( int argc, char *argv[] ) { /* *+ * Name: * astbad * Purpose: * Generate a string representing an AST floating point constant. * Invocation: * astbad * Type: * C program. * Description: * This program writes a string to standard output containing * a formatted decimal representation of a specified C floating point * constant defined by AST. This is intended for use in defining these * constants for use from languages other than C. * * The value written should contain sufficient decimal digits so * that a routine that uses it to generate a value in another * language will produce exactly the same value as a C program * using the same macro. * Arguments: * value = LITERAL * The name of the constant to be printed: AST__BAD, AST__NAN or * AST__NANF. If not supplied, AST__BAD is printed. * Copyright: * Copyright (C) 2009-2011 Science & Technology Facilities Council. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * DSB: David S. Berry (Starlink) * TIMJ: Tim Jenness (JAC, Hawaii) * History: * 18-NOV-1997 (RFWS); * Original version. * 24-OCT-2000 (DSB): * Ensure that the number of digits used is at least the minimum * required by IEEE for a conversion from binary to string and back * to binary to be an identity. * 31-MAR-2009 (TIMJ): * Does not take any arguments so don't try to read arguments. * 18-JAN-2011 (DSB): * Extend to print other floating point constants as well as * AST__BAD. *- */ /* Local Variables; */ const char *name; /* Pointer to name of constant to be printed */ /* Get the name of the constant to be printed. */ if( argc > 1 ) { name = argv[1]; } else { name = "AST__BAD"; } /* Print it. */ if( !strcmp( name, "AST__BAD" ) ) { printdval( AST__BAD ); } else if( !strcmp( name, "AST__NAN" ) ) { printdval( AST__NAN ); } else if( !strcmp( name, "AST__NANF" ) ) { printfval( AST__NANF ); /* Issue an error message if the argument is unknown. */ } else { (void) fprintf( stderr, "astbad: Unknown constant requested: %s\n", name ); } /* Exit. */ return 0; } /* Print a double precision value to standard output */ static void printdval( double val ){ /* Local Variables: */ char buff[ BUFF_LEN + 1 ]; /* Buffer for formatted string */ double newval; /* Value read back from string */ int digits; /* Number of digits of precision */ /* Vary the precision over a reasonable range to see how many decimal digits are required. The initial number of digits is the larger of DBL_DIG and IEEE_DIG. */ for ( digits = ( DBL_DIG > IEEE_DIG )?DBL_DIG:IEEE_DIG; digits <= ( 2 * DBL_DIG ); digits++ ) { /* Format the value using this precision and then read it back. */ (void) sprintf( buff, "%.*G", digits, val ); (void) sscanf( buff, "%lg", &newval ); /* Quit looping when the original value is read back. */ if ( newval == val ) break; } /* Write the value to standard output, with one extra digit for good measure. */ (void) printf( "%.*G\n", digits + 1, val ); } /* Print a single precision value to standard output */ static void printfval( float val ){ /* Local Variables: */ char buff[ BUFF_LEN + 1 ]; /* Buffer for formatted string */ float newval; /* Value read back from string */ int digits; /* Number of digits of precision */ /* Vary the precision over a reasonable range to see how many decimal digits are required. The initial number of digits is FLT_DIG. */ for ( digits = FLT_DIG; digits <= ( 2 * FLT_DIG ); digits++ ) { /* Format the value using this precision and then read it back. */ (void) sprintf( buff, "%.*G", digits, val ); (void) sscanf( buff, "%g", &newval ); /* Quit looping when the original value is read back. */ if ( newval == val ) break; } /* Write the value to standard output, with one extra digit for good measure. */ (void) printf( "%.*G\n", digits + 1, val ); } ast-8.3.0/zoommap.h0000664000175000017500000002360113004147321011064 00000000000000#if !defined( ZOOMMAP_INCLUDED ) /* Include this file only once */ #define ZOOMMAP_INCLUDED /* *+ * Name: * zoommap.h * Type: * C include file. * Purpose: * Define the interface to the ZoomMap class. * Invocation: * #include "zoommap.h" * Description: * This include file defines the interface to the ZoomMap class and * provides the type definitions, function prototypes and macros, * etc. needed to use this class. * * The ZoomMap class implements Mappings which perform a "zoom" * transformation by multiplying all coordinate values by the same * scale factor (the inverse transformation is performed by * dividing by this scale factor). * Inheritance: * The ZoomMap class inherits from the Mapping class. * Attributes Over-Ridden: * None. * New Attributes Defined: * Zoom (double) * The ZoomMap scale factor, by which coordinate values are * multiplied (by the forward transformation) or divided (by the * inverse transformation). This factor is set when a ZoomMap is * created, but may later be modified. It may not be set to * zero. The default value (if cleared) is one. * * Note that if the ZoomMap is inverted (by using astInvert or * setting a non-zero value for its Invert attribute), then the * reciprocal of this Zoom value will, in effect, be used. * Methods Over-Ridden: * Public: * None. * * Protected: * astClearAttrib * Clear an attribute value for a ZoomMap. * astGetAttrib * Get an attribute value for a ZoomMap. * astSetAttrib * Set an attribute value for a ZoomMap. * astTestAttrib * Test if an attribute value has been set for a ZoomMap. * astTransform * Apply a ZoomMap to transform a set of points. * New Methods Defined: * Public: * None. * * Protected: * astClearZoom * Clear the Zoom attribute value for a ZoomMap. * astGetZoom * Get the Zoom attribute value for a ZoomMap. * astSetZoom * Set the Zoom attribute value for a ZoomMap. * astTestZoom * Test if a Zoom attribute value has been set for a ZoomMap. * Other Class Functions: * Public: * astIsAZoomMap * Test class membership. * astZoomMap * Create a ZoomMap. * * Protected: * astCheckZoomMap * Validate class membership. * astInitZoomMap * Initialise a ZoomMap. * astInitZoomMapVtab * Initialise the virtual function table for the ZoomMap class. * astLoadZoomMap * Load a ZoomMap. * Macros: * None. * Type Definitions: * Public: * AstZoomMap * ZoomMap object type. * * Protected: * AstZoomMapVtab * ZoomMap virtual function table type. * Feature Test Macros: * astCLASS * If the astCLASS macro is undefined, only public symbols are * made available, otherwise protected symbols (for use in other * class implementations) are defined. This macro also affects * the reporting of error context information, which is only * provided for external calls to the AST library. * 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 * . * Authors: * RFWS: R.F. Warren-Smith (Starlink) * History: * 30-JAN-1996 (RFWS): * Original version. * 18-JUL-1996 (RFWS): * Updated to provide an external interface. * 10-SEP-1996 (RFWS): * Added I/O facilities. * 8-JAN-2003 (DSB): * Added protected astInitZoomMapVtab method. *- */ /* Include files. */ /* ============== */ /* Interface definitions. */ /* ---------------------- */ #include "mapping.h" /* Coordinate mappings (parent class) */ #if defined(astCLASS) /* Protected */ #include "channel.h" /* I/O channels */ #endif /* C header files. */ /* --------------- */ #if defined(astCLASS) /* Protected */ #include #endif /* Macros */ /* ====== */ /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ #ifndef __GNUC__ # define __attribute__(x) /*NOTHING*/ #endif /* Type Definitions. */ /* ================= */ /* ZoomMap structure. */ /* ------------------ */ /* This structure contains all information that is unique to each object in the class (e.g. its instance variables). */ typedef struct AstZoomMap { /* Attributes inherited from the parent class. */ AstMapping mapping; /* Parent class structure */ /* Attributes specific to objects in this class. */ double zoom; /* Zoom factor */ } AstZoomMap; /* Virtual function table. */ /* ----------------------- */ /* This table contains all information that is the same for all objects in the class (e.g. pointers to its virtual functions). */ #if defined(astCLASS) /* Protected */ typedef struct AstZoomMapVtab { /* Properties (e.g. methods) inherited from the parent class. */ AstMappingVtab mapping_vtab; /* Parent class virtual function table */ /* A Unique identifier to determine class membership. */ AstClassIdentifier id; /* Properties (e.g. methods) specific to this class. */ double (*GetZoom)( AstZoomMap *, int * ); int (* TestZoom)( AstZoomMap *, int * ); void (* ClearZoom)( AstZoomMap *, int * ); void (* SetZoom)( AstZoomMap *, double, int * ); } AstZoomMapVtab; #if defined(THREAD_SAFE) /* Define a structure holding all data items that are global within this class. */ typedef struct AstZoomMapGlobals { AstZoomMapVtab Class_Vtab; int Class_Init; char GetAttrib_Buff[ 101 ]; } AstZoomMapGlobals; #endif #endif /* Function prototypes. */ /* ==================== */ /* Prototypes for standard class functions. */ /* ---------------------------------------- */ astPROTO_CHECK(ZoomMap) /* Check class membership */ astPROTO_ISA(ZoomMap) /* Test class membership */ /* Constructor. */ #if defined(astCLASS) /* Protected. */ AstZoomMap *astZoomMap_( int, double, const char *, int *, ...); #else AstZoomMap *astZoomMapId_( int, double, const char *, ... )__attribute__((format(printf,3,4))); #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ AstZoomMap *astInitZoomMap_( void *, size_t, int, AstZoomMapVtab *, const char *, int, double, int * ); /* Vtab initialiser. */ void astInitZoomMapVtab_( AstZoomMapVtab *, const char *, int * ); /* Loader. */ AstZoomMap *astLoadZoomMap_( void *, size_t, AstZoomMapVtab *, const char *, AstChannel *, int * ); /* Thread-safe initialiser for all global data used by this module. */ #if defined(THREAD_SAFE) void astInitZoomMapGlobals_( AstZoomMapGlobals * ); #endif #endif /* Prototypes for member functions. */ /* -------------------------------- */ # if defined(astCLASS) /* Protected */ double astGetZoom_( AstZoomMap *, int * ); int astTestZoom_( AstZoomMap *, int * ); void astClearZoom_( AstZoomMap *, int * ); void astSetZoom_( AstZoomMap *, double, int * ); #endif /* Function interfaces. */ /* ==================== */ /* These macros are wrap-ups for the functions defined by this class to make them easier to invoke (e.g. to avoid type mis-matches when passing pointers to objects from derived classes). */ /* Interfaces to standard class functions. */ /* --------------------------------------- */ /* Some of these functions provide validation, so we cannot use them to validate their own arguments. We must use a cast when passing object pointers (so that they can accept objects from derived classes). */ /* Check class membership. */ #define astCheckZoomMap(this) astINVOKE_CHECK(ZoomMap,this,0) #define astVerifyZoomMap(this) astINVOKE_CHECK(ZoomMap,this,1) /* Test class membership. */ #define astIsAZoomMap(this) astINVOKE_ISA(ZoomMap,this) /* Constructor. */ #if defined(astCLASS) /* Protected. */ #define astZoomMap astINVOKE(F,astZoomMap_) #else #define astZoomMap astINVOKE(F,astZoomMapId_) #endif #if defined(astCLASS) /* Protected */ /* Initialiser. */ #define astInitZoomMap(mem,size,init,vtab,name,ncoord,zoom) \ astINVOKE(O,astInitZoomMap_(mem,size,init,vtab,name,ncoord,zoom,STATUS_PTR)) /* Vtab Initialiser. */ #define astInitZoomMapVtab(vtab,name) astINVOKE(V,astInitZoomMapVtab_(vtab,name,STATUS_PTR)) /* Loader. */ #define astLoadZoomMap(mem,size,vtab,name,channel) \ astINVOKE(O,astLoadZoomMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) #endif /* Interfaces to public member functions. */ /* -------------------------------------- */ /* Here we make use of astCheckZoomMap to validate ZoomMap pointers before use. This provides a contextual error report if a pointer to the wrong sort of Object is supplied. */ #if defined(astCLASS) /* Protected */ #define astClearZoom(this) astINVOKE(V,astClearZoom_(astCheckZoomMap(this),STATUS_PTR)) #define astGetZoom(this) astINVOKE(V,astGetZoom_(astCheckZoomMap(this),STATUS_PTR)) #define astSetZoom(this,value) \ astINVOKE(V,astSetZoom_(astCheckZoomMap(this),value,STATUS_PTR)) #define astTestZoom(this) astINVOKE(V,astTestZoom_(astCheckZoomMap(this),STATUS_PTR)) #endif #endif